diff --git a/.bundle/config b/.bundle/config deleted file mode 100644 index 9bc01b4c32..0000000000 --- a/.bundle/config +++ /dev/null @@ -1,3 +0,0 @@ ---- -BUNDLE_PATH: "vendor/bundle" -BUNDLE_DISABLE_SHARED_GEMS: "true" diff --git a/.drone.yml b/.drone.yml deleted file mode 100644 index d36025ce89..0000000000 --- a/.drone.yml +++ /dev/null @@ -1,6 +0,0 @@ -pipeline: - build: - image: scalacenter/scala-rvm-jvm-coursier:2.0 - pull: true - commands: - - ./scripts/ci.sh diff --git a/.drone.yml.sig b/.drone.yml.sig deleted file mode 100644 index 8240a38b07..0000000000 --- a/.drone.yml.sig +++ /dev/null @@ -1 +0,0 @@ -eyJhbGciOiJIUzI1NiJ9.cGlwZWxpbmU6CiAgYnVpbGQ6CiAgICBpbWFnZTogamRrLXJ2bS1jb3Vyc2llcjpsYXRlc3QKICAgIHB1bGw6IHRydWUKICAgIGNvbW1hbmRzOgogICAgICAtIHNvdXJjZSB-Ly5wcm9maWxlCiAgICAgIC0gYnVuZGxlIGluc3RhbGwKICAgICAgLSAuL3NjcmlwdHMvcnVuLXR1dC5zaAogICAgICAtIHJtIC1yIHR1dC10bXAKICAgICAgLSBidW5kbGUgZXhlYyBqZWt5bGwgYnVpbGQK.7Rp37FEwRqAo85EdFYZh1PoyU8mxpFdEnpchWaQkHCc diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000000..ce1bb0f48b --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +/_ja @scala/docs-ja diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000000..f48b4ada51 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +version: 2 +updates: +- package-ecosystem: bundler + directory: "/" + schedule: + interval: daily + open-pull-requests-limit: 10 + ignore: + - dependency-name: html-proofer + versions: + - "> 3.15.3" diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000000..e56f07a0ab --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,33 @@ +name: Build +on: [push, pull_request] +jobs: + build: + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: 3.2.6 + bundler-cache: true + - name: Set up coursier + uses: coursier/setup-action@v1.3.5 + with: + jvm: adopt:11 + - name: Run mdoc + run: | + ./scripts/run-mdoc.sh + rm -r /tmp/mdoc-out/ + - name: Jekyll build + run: bundle exec jekyll build + - name: HTMLProofer + run: | + # # Checking for docs.scala-lang/blob/main leads to a chicken and egg problem because of the edit links of new pages. + bundle exec htmlproofer ./_site/\ + --only-4xx\ + --ignore-status-codes "400,401,403,429"\ + --ignore-empty-alt\ + --allow-hash-href\ + --no-enforce-https\ + --ignore-urls '/https://github.com/scala/,/www.oracle.com/' + diff --git a/.gitignore b/.gitignore index c73823b558..055aee462d 100644 --- a/.gitignore +++ b/.gitignore @@ -8,5 +8,5 @@ _site vendor/bundle .idea/ /coursier -/tut-tmp/ .sass-cache/ +.jekyll-cache/ \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 948de8e719..0511f2126d 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,78 +1,7 @@ -## Scala Code of Conduct +all repositories in these organizations: -We are committed to providing a friendly, safe and welcoming environment for -all, regardless of level of experience, gender, gender identity and expression, -sexual orientation, disability, personal appearance, body size, race, ethnicity, -age, religion, nationality, or other such characteristics. +* [scala](https://github.com/scala) +* [scalacenter](https://github.com/scalacenter) +* [lampepfl](https://github.com/lampepfl) -### Our Standards - -**Whether you’re a regular contributor or a newcomer, we care about making this community a welcoming and safe place for you and we’ve got your back.** - -As a member of the community, you agree to the following: - -**Encouraged:** - -- Be kind and courteous. -- Respect differences of opinion and remember that every design or implementation choice carries a trade-off and numerous costs. There is seldom a single right answer. -- Remember that everyone was new to Scala at some point. We want to encourage newcomers to join our community and learn the Scala language and ecosystem. Assume competence. -- Show empathy towards other community members. - -**Discouraged:** - -- Keep unstructured critique to a minimum. We encourage sharing ideas and perspectives, so please ensure that your feedback is constructive and relevant. If you have solid ideas you want to experiment with, make a fork and see how it works. -- Avoid aggressive and micro-aggressive behavior, such as unconstructive criticism, providing corrections that do not improve the conversation (sometimes referred to as "well actually"s), repeatedly interrupting or talking over someone else, feigning surprise at someone’s lack of knowledge or awareness about a topic, or subtle prejudice (for example, comments like “That’s so easy my grandmother could do it.”). For more examples of this kind of behavior, [see the Recurse Center's user manual](https://www.recurse.com/manual#sec-environment). -- We will exclude you from interaction if you insult, demean or harass anyone. The term “Harassment” includes “Unacceptable Behavior” described in the [Citizen Code of Conduct](http://citizencodeofconduct.org/). **In particular, we don’t tolerate behavior that excludes people in socially marginalized groups.** -- Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made uncomfortable by a community member's behavior, please contact one of the [moderators](https://contributors.scala-lang.org/about) or any member of the [Scala Center](http://scala.epfl.ch/) immediately. -- Likewise any spamming, trolling, flaming, baiting or other attention-stealing behaviour is not welcome. - -### Moderation - -These are the policies for upholding our community’s standards of conduct. If -you feel that a thread needs moderation, please contact anyone on the -[moderation team](https://contributors.scala-lang.org/about), or any employee of -the [Scala Center](https://scala.epfl.ch/). - -- Remarks that violate the above code of conduct, including hateful, hurtful, oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed, but never targeting another user, and never in a hateful manner.) -- Moderators will warn users who make remarks inconsistent with the above code of conduct. -- If the warning is unheeded, the user will be “kicked,” i.e., kicked out of the communication channel to cool off. -- If the user comes back and continues to make trouble, they will be banned, i.e., indefinitely excluded. -- Moderators may choose at their discretion to un-ban the user if it was a first offense and they if they make suitable amends with the offended party. -- If you think a ban is unjustified, please take it up with that moderator, or with a different moderator, in private. Complaints about bans in-channel are not allowed. -- Moderators are held to a higher standard than other community members. If a moderator acts inappropriately, they should expect less leeway than others. - -In the Scala community we strive to go the extra step to look out for each -other. Don’t just aim to be technically unimpeachable; try to be your best self. -In particular, avoid exacerbating offensive or sensitive issues, particularly if -they’re off-topic; this all too often leads to unnecessary fights, hurt -feelings, and damaged trust; worse, it can drive people away from the community -entirely. - -If someone takes issue with something you said or did, resist the urge to be -defensive. Rather, stop the offending behavior, apologize, and be sensitive -thereafter. Even if you feel you were misinterpreted or unfairly accused, -chances are good there was something you could’ve communicated better — remember -that it’s your responsibility to make your fellow Scala developers comfortable. -We are all here first and foremost because we want to talk about cool -technology, and everyone wants to get along in doing so. People are generally -eager to assume good intent and forgive. - -### Domain - -The enforcement policies listed above apply to all official Scala channels: -mailing lists, GitHub repositories and Gitter channels under scala and -scalacenter, Discourse, and Scala Center venues and hackathons. For other -projects adopting the Scala Code of Conduct, please contact the maintainers of -those projects for enforcement. If you wish to use this code of conduct for your -own project, consider explicitly mentioning your moderation policy or making a -copy with your own moderation policy so as to avoid confusion. - -### Credits - -Adapted from and/or inspired by multiple successful Codes of Conduct, including: - -* [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html) -* [The Node.js Policy on Trolling](http://blog.izs.me/post/30036893703/policy-on-trolling) -* [The Contributor Covenant v1.4.0](http://contributor-covenant.org/version/1/4/) -* [The Recurse Center's User Manual](https://www.recurse.com/manual#sec-environment) -* [The 18F Code of Conduct](https://18f.gsa.gov/code-of-conduct/) \ No newline at end of file +are covered by the Scala Code of Conduct: https://scala-lang.org/conduct/ diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000..b2bbc255f9 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,12 @@ +FROM ruby:3.2.6 + +RUN gem install bundler:2.6.5 + +WORKDIR /srv/jekyll + +COPY Gemfile . +COPY Gemfile.lock . + +RUN echo -n "bundle version: " && bundle --version +RUN chmod u+s /bin/chown +RUN bundle install diff --git a/Gemfile b/Gemfile index a0b87e6bb8..31cb37fbea 100644 --- a/Gemfile +++ b/Gemfile @@ -1,14 +1,6 @@ source 'https://rubygems.org' -gem 'jekyll-redirect-from' -gem 'jekyll-scalafiddle' +gem 'github-pages' +gem 'webrick' +# gem 'html-proofer' -# gem 'html-proofer' # link-checking: bundle exec htmlproofer ./_site/ --only-4xx --empty-alt-ignore --allow-hash-href - -# group :jekyll_plugins do -# gem 'hawkins' -# end - -# ^ Useful for live reloading the site in your -# browser during development. To use, uncomment -# and do: -# bundle exec jekyll liveserve --incremental +# gem 'html-proofer' # link-checking: bundle exec htmlproofer ./_site/ --only-4xx --ignore-empty-alt=true --allow-hash-href=true diff --git a/Gemfile.lock b/Gemfile.lock index 4157511c7d..8088be3873 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,97 +1,333 @@ GEM remote: https://rubygems.org/ specs: - activesupport (5.2.0) - concurrent-ruby (~> 1.0, >= 1.0.2) - i18n (>= 0.7, < 2) - minitest (~> 5.1) - tzinfo (~> 1.1) - addressable (2.5.2) - public_suffix (>= 2.0.2, < 4.0) + Ascii85 (2.0.1) + activesupport (8.0.1) + base64 + benchmark (>= 0.3) + bigdecimal + concurrent-ruby (~> 1.0, >= 1.3.1) + connection_pool (>= 2.2.5) + drb + i18n (>= 1.6, < 2) + logger (>= 1.4.2) + minitest (>= 5.1) + securerandom (>= 0.3) + tzinfo (~> 2.0, >= 2.0.5) + uri (>= 0.13.1) + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + afm (0.2.2) + async (2.23.0) + console (~> 1.29) + fiber-annotation + io-event (~> 1.9) + metrics (~> 0.12) + traces (~> 0.15) + base64 (0.2.0) + benchmark (0.4.0) + bigdecimal (3.1.9) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.12.2) colorator (1.1.0) - colorize (0.8.1) - concurrent-ruby (1.0.5) - em-websocket (0.5.1) + commonmarker (0.23.11) + concurrent-ruby (1.3.5) + connection_pool (2.5.0) + console (1.29.3) + fiber-annotation + fiber-local (~> 1.1) + json + csv (3.3.2) + dnsruby (1.72.3) + base64 (~> 0.2.0) + simpleidn (~> 0.2.1) + drb (2.2.1) + em-websocket (0.5.3) eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - ethon (0.11.0) - ffi (>= 1.3.0) + http_parser.rb (~> 0) + ethon (0.16.0) + ffi (>= 1.15.0) eventmachine (1.2.7) - ffi (1.9.25) + execjs (2.10.0) + faraday (2.12.2) + faraday-net_http (>= 2.0, < 3.5) + json + logger + faraday-net_http (3.4.0) + net-http (>= 0.5.0) + ffi (1.17.1-arm64-darwin) + ffi (1.17.1-x64-mingw-ucrt) + ffi (1.17.1-x86_64-linux-gnu) + fiber-annotation (0.2.0) + fiber-local (1.1.0) + fiber-storage + fiber-storage (1.0.0) forwardable-extended (2.6.0) - html-proofer (3.9.1) - activesupport (>= 4.2, < 6.0) + gemoji (4.1.0) + github-pages (232) + github-pages-health-check (= 1.18.2) + jekyll (= 3.10.0) + jekyll-avatar (= 0.8.0) + jekyll-coffeescript (= 1.2.2) + jekyll-commonmark-ghpages (= 0.5.1) + jekyll-default-layout (= 0.1.5) + jekyll-feed (= 0.17.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.16.1) + jekyll-include-cache (= 0.2.1) + jekyll-mentions (= 1.6.0) + jekyll-optional-front-matter (= 0.3.2) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.3.0) + jekyll-redirect-from (= 0.16.0) + jekyll-relative-links (= 0.6.1) + jekyll-remote-theme (= 0.4.3) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.8.0) + jekyll-sitemap (= 1.4.0) + jekyll-swiss (= 1.0.0) + jekyll-theme-architect (= 0.2.0) + jekyll-theme-cayman (= 0.2.0) + jekyll-theme-dinky (= 0.2.0) + jekyll-theme-hacker (= 0.2.0) + jekyll-theme-leap-day (= 0.2.0) + jekyll-theme-merlot (= 0.2.0) + jekyll-theme-midnight (= 0.2.0) + jekyll-theme-minimal (= 0.2.0) + jekyll-theme-modernist (= 0.2.0) + jekyll-theme-primer (= 0.6.0) + jekyll-theme-slate (= 0.2.0) + jekyll-theme-tactile (= 0.2.0) + jekyll-theme-time-machine (= 0.2.0) + jekyll-titles-from-headings (= 0.5.3) + jemoji (= 0.13.0) + kramdown (= 2.4.0) + kramdown-parser-gfm (= 1.1.0) + liquid (= 4.0.4) + mercenary (~> 0.3) + minima (= 2.5.1) + nokogiri (>= 1.16.2, < 2.0) + rouge (= 3.30.0) + terminal-table (~> 1.4) + webrick (~> 1.8) + github-pages-health-check (1.18.2) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (>= 4, < 8) + public_suffix (>= 3.0, < 6.0) + typhoeus (~> 1.3) + hashery (2.1.2) + html-pipeline (2.14.3) + activesupport (>= 2) + nokogiri (>= 1.4) + html-proofer (5.0.10) addressable (~> 2.3) - colorize (~> 0.8) - mercenary (~> 0.3.2) - nokogiri (~> 1.8.1) - parallel (~> 1.3) + async (~> 2.1) + nokogiri (~> 1.13) + pdf-reader (~> 2.11) + rainbow (~> 3.0) typhoeus (~> 1.3) yell (~> 2.0) - http_parser.rb (0.6.0) - i18n (0.9.5) + zeitwerk (~> 2.5) + http_parser.rb (0.8.0) + i18n (1.14.7) concurrent-ruby (~> 1.0) - jekyll (3.8.3) + io-event (1.9.0) + jekyll (3.10.0) addressable (~> 2.4) colorator (~> 1.0) + csv (~> 3.0) em-websocket (~> 0.5) - i18n (~> 0.7) + i18n (>= 0.7, < 2) jekyll-sass-converter (~> 1.0) jekyll-watch (~> 2.0) - kramdown (~> 1.14) + kramdown (>= 1.17, < 3) liquid (~> 4.0) mercenary (~> 0.3.3) pathutil (~> 0.9) rouge (>= 1.7, < 4) safe_yaml (~> 1.0) - jekyll-redirect-from (0.14.0) - jekyll (~> 3.3) + webrick (>= 1.0) + jekyll-avatar (0.8.0) + jekyll (>= 3.0, < 5.0) + jekyll-coffeescript (1.2.2) + coffee-script (~> 2.2) + coffee-script-source (~> 1.12) + jekyll-commonmark (1.4.0) + commonmarker (~> 0.22) + jekyll-commonmark-ghpages (0.5.1) + commonmarker (>= 0.23.7, < 1.1.0) + jekyll (>= 3.9, < 4.0) + jekyll-commonmark (~> 1.4.0) + rouge (>= 2.0, < 5.0) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-feed (0.17.0) + jekyll (>= 3.7, < 5.0) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.16.1) + jekyll (>= 3.4, < 5.0) + octokit (>= 4, < 7, != 4.4.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-mentions (1.6.0) + html-pipeline (~> 2.3) + jekyll (>= 3.7, < 5.0) + jekyll-optional-front-matter (0.3.2) + jekyll (>= 3.0, < 5.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.3.0) + jekyll (>= 3.0, < 5.0) + jekyll-redirect-from (0.16.0) + jekyll (>= 3.3, < 5.0) + jekyll-relative-links (0.6.1) + jekyll (>= 3.3, < 5.0) + jekyll-remote-theme (0.4.3) + addressable (~> 2.0) + jekyll (>= 3.5, < 5.0) + jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0) + rubyzip (>= 1.3.0, < 3.0) jekyll-sass-converter (1.5.2) sass (~> 3.4) - jekyll-scalafiddle (1.0.1) - jekyll (~> 3.0) - jekyll-watch (2.0.0) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-sitemap (1.4.0) + jekyll (>= 3.7, < 5.0) + jekyll-swiss (1.0.0) + jekyll-theme-architect (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.6.0) + jekyll (> 3.5, < 5.0) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.2.0) + jekyll (> 3.5, < 5.0) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.3) + jekyll (>= 3.3, < 5.0) + jekyll-watch (2.2.1) listen (~> 3.0) - kramdown (1.17.0) - liquid (4.0.0) - listen (3.1.5) - rb-fsevent (~> 0.9, >= 0.9.4) - rb-inotify (~> 0.9, >= 0.9.7) - ruby_dep (~> 1.2) + jemoji (0.13.0) + gemoji (>= 3, < 5) + html-pipeline (~> 2.2) + jekyll (>= 3.0, < 5.0) + json (2.10.2) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + logger (1.6.6) mercenary (0.3.6) - mini_portile2 (2.3.0) - minitest (5.11.3) - nokogiri (1.8.4) - mini_portile2 (~> 2.3.0) - parallel (1.12.1) - pathutil (0.16.1) + metrics (0.12.1) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.25.4) + net-http (0.6.0) + uri + nokogiri (1.18.8-arm64-darwin) + racc (~> 1.4) + nokogiri (1.18.8-x64-mingw-ucrt) + racc (~> 1.4) + nokogiri (1.18.8-x86_64-linux-gnu) + racc (~> 1.4) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) + pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (3.0.2) - rb-fsevent (0.10.3) - rb-inotify (0.9.10) - ffi (>= 0.5.0, < 2) - rouge (3.1.1) - ruby_dep (1.5.0) - safe_yaml (1.0.4) - sass (3.5.7) + pdf-reader (2.14.1) + Ascii85 (>= 1.0, < 3.0, != 2.0.0) + afm (~> 0.2.1) + hashery (~> 2.0) + ruby-rc4 + ttfunk + public_suffix (5.1.1) + racc (1.8.1) + rainbow (3.1.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.1) + rouge (3.30.0) + ruby-rc4 (0.1.5) + rubyzip (2.4.1) + safe_yaml (1.0.5) + sass (3.7.4) sass-listen (~> 4.0.0) sass-listen (4.0.0) rb-fsevent (~> 0.9, >= 0.9.4) rb-inotify (~> 0.9, >= 0.9.7) - thread_safe (0.3.6) - typhoeus (1.3.0) + sawyer (0.9.2) + addressable (>= 2.3.5) + faraday (>= 0.17.3, < 3) + securerandom (0.4.1) + simpleidn (0.2.3) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + traces (0.15.2) + ttfunk (1.8.0) + bigdecimal (~> 3.1) + typhoeus (1.4.1) ethon (>= 0.9.0) - tzinfo (1.2.5) - thread_safe (~> 0.1) - yell (2.0.7) + tzinfo (2.0.6) + concurrent-ruby (~> 1.0) + unicode-display_width (1.8.0) + uri (1.0.3) + webrick (1.9.1) + yell (2.2.2) + zeitwerk (2.7.2) PLATFORMS - ruby + arm64-darwin-22 + arm64-darwin-23 + arm64-darwin-24 + x64-mingw-ucrt + x86_64-linux DEPENDENCIES + github-pages html-proofer - jekyll-redirect-from - jekyll-scalafiddle + webrick BUNDLED WITH - 1.16.2 + 2.6.5 diff --git a/README.md b/README.md index 6dccfec463..013a66267c 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,62 @@ # Scala Documentation # -[![Build Status](https://platform-ci.scala-lang.org/api/badges/scala/docs.scala-lang/status.svg)](https://platform-ci.scala-lang.org/scala/docs.scala-lang) +[![Build Status](https://github.com/scala/docs.scala-lang/actions/workflows/build.yml/badge.svg)](https://github.com/scala/docs.scala-lang/actions/workflows/build.yml?query=branch%3Amain) This repository contains the source for the Scala documentation website, as well as the source for "Scala Improvement Process" (SIP) documents. +## Dependencies ## + +This site uses a Jekyll, a Ruby framework. You'll need Ruby and Bundler installed; see [Jekyll installation instructions](https://jekyllrb.com/docs/installation/) for the details. + ## Quickstart ## To build and view the site locally: - gem install bundler bundle install bundle exec jekyll serve -I +([Trouble on MacOS?](https://github.com/scala/docs.scala-lang/issues/1150)) + For more details, read on. +## Quickstart with Docker Compose ## + +You need to have [Docker Engine](https://docs.docker.com/engine/) and [Docker Compose](https://docs.docker.com/compose/) installed on your machine. +Under macOS (Intel or Apple silicon), instead of installing [Docker Desktop](https://docs.docker.com/desktop/) you can also use [HomeBrew](https://brew.sh/) with [Colima](https://github.com/abiosoft/colima): `brew install colima docker docker-compose`. +UID and GID environment variables are needed to avoid docker from writing files as root in your directory. +By default, docker-compose will use the file docker-compose.yml which will build the website and serve it on 0.0.0.0:4000 . +If you just need to build the website, add ```-f docker-compose_build-only.yml``` + +``` +env UID="$(id -u)" GID="$(id -g)" docker-compose up +``` + +The generated site is available at `http://localhost:4000`. + +When the website dependencies change (the content of the `Gemfile`), +you have to re-build the Docker image: + +``` +env UID="$(id -u)" GID="$(id -g)" docker-compose up --build +``` + +If you have problems with the Docker image or want to force the rebuild of the Docker image: +``` +env UID="$(id -u)" GID="$(id -g)" docker-compose build --no-cache +``` + + +For more details on the Docker option, see also [this issue](https://github.com/scala/docs.scala-lang/issues/1286). + ## Contributing ## -Please have a look at [http://docs.scala-lang.org/contribute.html](http://docs.scala-lang.org/contribute.html) before making a contribution. +Please have a look at [Add New Guides/Tutorials](https://docs.scala-lang.org/contribute/add-guides.html) before making a contribution. This document gives an overview of the type of documentation contained within the Scala Documentation repository and the repository's structure. Small changes, or corrected typos will generally be pulled in right away. Large changes, like the addition of new documents, or the rewriting of existing documents will be thoroughly reviewed-- please keep in mind that, generally, new documents must be very well-polished, complete, and maintained in order to be accepted. -## Dependencies ## - -This site uses a Jekyll, a Ruby framework. You'll need Ruby and Bundler installed; see [Jekyll installation instructions](http://jekyllrb.com/docs/installation/) for the details. - ## Building & Viewing ## cd into the directory where you cloned this repository, then install the required gems with `bundle install`. This will automatically put the gems into `./vendor/bundle`. @@ -43,19 +73,19 @@ If you add `--watch` at the end of the command line above, Jekyll will automatic If you get `incompatible encoding` errors when generating the site under Windows, then ensure that the console in which you are running jekyll can work with UTF-8 characters. As described in the blog -[Solving UTF problem with Jekyll on Windows](http://joseoncode.com/2011/11/27/solving-utf-problem-with-jekyll-on-windows/) +[Solving UTF problem with Jekyll on Windows](https://joseoncode.com/2011/11/27/solving-utf-problem-with-jekyll-on-windows/) you have to execute `chcp 65001`. This command is best added to the `jekyll.bat`-script. ## Markdown ## -The markdown used in this site uses [kramdown](http://kramdown.gettalong.org/) extensions. +The markdown used in this site uses [kramdown](https://kramdown.gettalong.org/) extensions. ### Markdown Editor for OSX ### -There's a free markdown editor for OSX called [Mou](http://25.io/mou/). It's quite convenient to work with, and it generates the translated Markdown in real-time alongside of your editor window, as can be seen here: +There's a free markdown editor for OSX called [MacDown](https://github.com/MacDownApp/macdown). It's quite convenient to work with, and it generates the translated Markdown in real-time alongside of your editor window, as can be seen here: -![Mou Screen Shot](http://25.io/mou/img/1.png) +![MacDown Screen Shot](https://raw.githubusercontent.com/MacDownApp/macdown/3e2a2bf101c215c143bf00d9f857965f0ee82487/assets/screenshot.png) ## License ## -All documentation contained in this repository is licensed by EPFL under a Creative Commons Attribution-Share Alike 3.0 Unported license ("CC-BY-SA"), unless otherwise noted. By submitting a "pull request," or otherwise contributing to this repository, you implicitly agree to license your contribution under the above CC-BY-SA license. The source code of this website is licensed to EPFL under the [Scala License](http://www.scala-lang.org/node/146), unless otherwise noted. +All documentation contained in this repository is licensed by EPFL under a Creative Commons Attribution-Share Alike 3.0 Unported license ("CC-BY-SA"), unless otherwise noted. By submitting a "pull request," or otherwise contributing to this repository, you implicitly agree to license your contribution under the above CC-BY-SA license. The source code of this website is licensed to EPFL under the [Scala License](https://www.scala-lang.org/node/146), unless otherwise noted. diff --git a/_ba/cheatsheets/index.md b/_ba/cheatsheets/index.md index 0a7e59790f..3ca8f61b70 100644 --- a/_ba/cheatsheets/index.md +++ b/_ba/cheatsheets/index.md @@ -1,11 +1,11 @@ --- layout: cheatsheet -title: Scalacheat +title: Scala Cheatsheet partof: cheatsheet by: Brendan O'Connor -about: Zahvaljujući Brendan O'Connoru ovaj cheatsheet teži da bude kratki pregled sintakse Scale. Licenca pripada Brendan O'Connor-u, pod CC-BY-SA 3.0 licencom. +about: Zahvaljujući Brendan O'Connoru ovaj cheatsheet teži da bude kratki pregled sintakse Scale. Licenca pripada Brendan O'Connor-u, pod CC-BY-SA 3.0 licencom. language: ba --- @@ -47,7 +47,7 @@ language: ba | `var (x,y,z) = (1,2,3)` | destrukturirajuće vezivanje: otpakivanje torke podudaranjem uzoraka (pattern matching). | | Loše`var x,y,z = (1,2,3)` | skrivena greška: svim varijablama dodijeljena cijela torka. | | `var xs = List(1,2,3)` | lista (nepromjenjiva). | -| `xs(2)` | indeksiranje zagradama ([slajdovi](http://www.slideshare.net/Odersky/fosdem-2009-1013261/27)). | +| `xs(2)` | indeksiranje zagradama ([slajdovi](https://www.slideshare.net/Odersky/fosdem-2009-1013261/27)). | | `1 :: List(2,3)` | cons. | | `1 to 5` _isto kao_ `1 until 6`
`1 to 10 by 2` | šećer za raspon (range). | | `()` _(prazne zagrade)_ | jedina instanca Unit tipa (slično kao u C/Java void). | @@ -56,11 +56,11 @@ language: ba | `if (check) happy` _isto kao_
`if (check) happy else ()` | sintaksni šećer za uslov. | | `while (x < 5) { println(x); x += 1}` | while petlja. | | `do { println(x); x += 1} while (x < 5)` | do while petlja. | -| `import scala.util.control.Breaks._`
`breakable {`
` for (x <- xs) {`
` if (Math.random < 0.1) break`
` }`
`}`| break ([slajdovi](http://www.slideshare.net/Odersky/fosdem-2009-1013261/21)). | +| `import scala.util.control.Breaks._`
`breakable {`
` for (x <- xs) {`
` if (Math.random < 0.1) break`
` }`
`}`| break ([slajdovi](https://www.slideshare.net/Odersky/fosdem-2009-1013261/21)). | | `for (x <- xs if x%2 == 0) yield x*10` _isto kao_
`xs.filter(_%2 == 0).map(_*10)` | for komprehensija: filter/map. | | `for ((x,y) <- xs zip ys) yield x*y` _isto kao_
`(xs zip ys) map { case (x,y) => x*y }` | for komprehensija: destrukturirajuće vezivanje. | | `for (x <- xs; y <- ys) yield x*y` _isto kao_
`xs flatMap {x => ys map {y => x*y}}` | for komprehensija: međuproizvod (vektorski proizvod). | -| `for (x <- xs; y <- ys) {`
`println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
`}` | for komprehensija: imperativ-asto.
[sprintf-stil.](http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | +| `for (x <- xs; y <- ys) {`
`println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
`}` | for komprehensija: imperativ-asto.
[sprintf-stil.](https://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | | `for (i <- 1 to 5) {`
`println(i)`
`}` | for komprehensija: iteracija uključujući gornju granicu. | | `for (i <- 1 until 5) {`
`println(i)`
`}` | for komprehensija: iteracija ne uključujući gornju granicu. | | podudaranje uzoraka (pattern matching) | | diff --git a/_ba/tour/abstract-types.md b/_ba/tour/abstract-type-members.md similarity index 97% rename from _ba/tour/abstract-types.md rename to _ba/tour/abstract-type-members.md index 10aa2d7d41..b7034b6922 100644 --- a/_ba/tour/abstract-types.md +++ b/_ba/tour/abstract-type-members.md @@ -2,9 +2,6 @@ layout: tour title: Apstraktni tipovi language: ba - -discourse: true - partof: scala-tour num: 23 @@ -18,7 +15,7 @@ Trejtovi i apstraktne klase mogu imati apstraktne tipove kao članove. To znači da konkretne implementacije definišu stvarni tip. Slijedi primjer: -```tut +```scala mdoc trait Buffer { type T val element: T @@ -29,7 +26,7 @@ U gornjem primjeru smo definisali apstraktni tip `T`. On se koristi za opis člana `element`. Ovaj trejt možemo naslijediti u apstraktnoj klasi i dodati gornju granicu tipa za `T` da bi ga učinili preciznijim. -```tut +```scala mdoc abstract class SeqBuffer extends Buffer { type U type T <: Seq[U] @@ -43,7 +40,7 @@ mora biti podtip `Seq[U]` za neki novi apstraktni tip `U`. Trejtovi ili [klase](classes.html) s apstraktnim tip-članovima se često koriste u kombinaciji s instanciranjem anonimnih klasa. Radi ilustracije, pogledaćemo program koji radi s sekvencijalnim baferom koji sadrži listu integera: -```tut +```scala mdoc abstract class IntSeqBuffer extends SeqBuffer { type U = Int } @@ -64,7 +61,7 @@ Metoda `newIntSeqBuf` koristi anonimnu klasu kao implementaciju `IntSeqBuf` pos Često je moguće pretvoriti apstraktni tip-član u tipski parametar klase i obrnuto. Slijedi verzija gornjeg koda koji koristi tipske parametre: -```tut +```scala mdoc:nest abstract class Buffer[+T] { val element: T } diff --git a/_ba/tour/annotations.md b/_ba/tour/annotations.md index 2040c97626..24b17a9012 100644 --- a/_ba/tour/annotations.md +++ b/_ba/tour/annotations.md @@ -2,13 +2,10 @@ layout: tour title: Anotacije language: ba - -discourse: true - partof: scala-tour num: 32 -next-page: default-parameter-values +next-page: packages-and-imports previous-page: by-name-parameters --- @@ -33,7 +30,7 @@ Redoslijed anotacijskih klauza nije bitan. Određene anotacije će uzrokovati pad kompajliranja ako određeni uslovi nisu ispunjeni. Npr, anotacija `@tailrec` osigurava da je metoda [tail-rekurzivna](https://en.wikipedia.org/wiki/Tail_call). Tail-rekurzija može zadržati memorijske zahtjeve konstantnim. Evo kako se koristi na metodi koja izračunava faktorijel: -```tut +```scala mdoc import scala.annotation.tailrec def factorial(x: Int): Int = { @@ -82,7 +79,7 @@ Java ima korisnički definisane metapodatke u formi [anotacija](https://docs.ora I upotrijebiti je ovako: ``` -@Source(URL = "http://coders.com/", +@Source(URL = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... ``` @@ -90,7 +87,7 @@ public class MyClass extends HisClass ... Primjena anotacije u Scali izgleda kao poziv konstruktora, dok se za instanciranje Javinih anotacija moraju koristiti imenovani argumenti: ``` -@Source(URL = "http://coders.com/", +@Source(URL = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` @@ -108,14 +105,14 @@ ako se koristi naziv `value` onda se u Javi može koristiti i konstruktor-sintak I upotrijebiti je kao: ``` -@SourceURL("http://coders.com/") +@SourceURL("https://coders.com/") public class MyClass extends HisClass ... ``` U ovom slučaju, Scala omogućuje istu sintaksu: ``` -@SourceURL("http://coders.com/") +@SourceURL("https://coders.com/") class MyScalaClass ... ``` @@ -123,7 +120,7 @@ Element `mail` je specificiran s podrazumijevanom vrijednošću tako da ne moram Međutim, ako trebamo, ne možemo miješati dva Javina stila: ``` -@SourceURL(value = "http://coders.com/", +@SourceURL(value = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... ``` @@ -131,7 +128,7 @@ public class MyClass extends HisClass ... Scala omogućuje veću fleksibilnost u ovom pogledu: ``` -@SourceURL("http://coders.com/", +@SourceURL("https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` diff --git a/_ba/tour/automatic-closures.md b/_ba/tour/automatic-closures.md deleted file mode 100644 index dc6e83de40..0000000000 --- a/_ba/tour/automatic-closures.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: tour -title: Automatic Type-Dependent Closure Construction - -discourse: false - -partof: scala-tour - -language: ba ---- diff --git a/_ba/tour/basics.md b/_ba/tour/basics.md index ae47a88d38..97956e6149 100644 --- a/_ba/tour/basics.md +++ b/_ba/tour/basics.md @@ -2,9 +2,6 @@ layout: tour title: Osnove language: ba - -discourse: true - partof: scala-tour num: 2 @@ -17,9 +14,9 @@ Na ovoj stranici ćemo objasniti osnove Scale. ## Probavanje Scale u browseru -Scalu možete probati u Vašem browser sa ScalaFiddle aplikacijom. +Scalu možete probati u Vašem browser sa Scastie aplikacijom. -1. Idite na [https://scalafiddle.io](https://scalafiddle.io). +1. Idite na [Scastie](https://scastie.scala-lang.org/). 2. Zalijepite `println("Hello, world!")` u lijevi panel. 3. Kliknite "Run" dugme. Izlaz će se pojaviti u desnom panelu. @@ -33,7 +30,7 @@ Izrazi su izjave koje imaju vrijednost. ``` Rezultate izraza možete prikazati pomoću `println`. -```tut +```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! @@ -44,33 +41,33 @@ println("Hello," + " world!") // Hello, world! Rezultatima možete dodijeliti naziv pomoću ključne riječi `val`. -```tut +```scala mdoc val x = 1 + 1 println(x) // 2 ``` -Imenovani rezultati, kao `x` ovdje, nazivaju se vrijednostima. +Imenovani rezultati, kao `x` ovdje, nazivaju se vrijednostima. Referenciranje vrijednosti ne okida njeno ponovno izračunavanje. Vrijednosti se ne mogu mijenjati. -```tut:fail +```scala mdoc:fail x = 3 // Ovo se ne kompajlira. ``` Tipovi vrijednosti mogu biti (automatski) zaključeni, ali možete i eksplicitno navesti tip: -```tut +```scala mdoc:nest val x: Int = 1 + 1 ``` -Primijetite da deklaracija tipa `Int` dolazi nakon identifikatora `x`. Također morate dodati i `:`. +Primijetite da deklaracija tipa `Int` dolazi nakon identifikatora `x`. Također morate dodati i `:`. ### Varijable Varijable su kao vrijednosti, osim što ih možete promijeniti. Varijable se definišu ključnom riječju `var`. -```tut +```scala mdoc:nest var x = 1 + 1 x = 3 // Ovo se kompajlira jer je "x" deklarisano s "var" ključnom riječju. println(x * x) // 9 @@ -78,7 +75,7 @@ println(x * x) // 9 Kao i s vrijednostima, tip možete eksplicitno navesti ako želite: -```tut +```scala mdoc:nest var x: Int = 1 + 1 ``` @@ -89,7 +86,7 @@ Izraze možete kombinovati okružujući ih s `{}`. Ovo se naziva blok. Rezultat zadnjeg izraza u bloku je rezultat cijelog bloka, također. -```tut +```scala mdoc println({ val x = 1 + 1 x + 1 @@ -102,7 +99,7 @@ Funkcije su izrazi koji primaju parametre. Možete definisati anonimnu funkciju (bez imena) koja vraća cijeli broj plus jedan: -```tut +```scala mdoc (x: Int) => x + 1 ``` @@ -110,21 +107,21 @@ Na lijevoj strani `=>` je lista parametara. Na desnoj strani je izraz koji koris Funkcije možete i imenovati. -```tut +```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` Funkcije mogu imati više parametara. -```tut +```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` Ili bez parametara. -```tut +```scala mdoc val getTheAnswer = () => 42 println(getTheAnswer()) // 42 ``` @@ -135,7 +132,7 @@ Metode izgledaju i ponašaju se vrlo slično funkcijama, ali postoji nekoliko ra Metode se definišu ključnom riječju `def`. Nakon `def` slijedi naziv, lista parametara, povratni tip, i tijelo. -```tut +```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` @@ -144,14 +141,14 @@ Primijetite da je povratni tip deklarisan _nakon_ liste parametara i dvotačke ` Metode mogu imati više listi parametara. -```tut +```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` Ili bez listi parametara ikako. -```tut +```scala mdoc def name: String = System.getProperty("name") println("Hello, " + name + "!") ``` @@ -159,32 +156,35 @@ println("Hello, " + name + "!") Postoje i neke druge razlike, ali zasad, možete misliti o njima kao nečemu sličnom funkcijama. Metode mogu imati višelinijske izraze također. -```tut + +```scala mdoc def getSquareString(input: Double): String = { val square = input * input square.toString } +println(getSquareString(2.5)) // 6.25 ``` + Zadnjo izraz u tijelu metode je povratna vrijednost metode. (Scala ima ključnu riječ `return`, ali se rijetko koristi.) ## Klase Klasu možete definisati ključnom riječju `class` praćenom imenom i parametrima konstruktora. -```tut +```scala mdoc class Greeter(prefix: String, suffix: String) { def greet(name: String): Unit = println(prefix + name + suffix) } ``` -Povratni tip metode `greet` je `Unit`, koji kaže da metoda ne vraća ništa značajno. -Koristi se slično kao `void` u Javi ili C-u. -(Razlika je u tome što svaki Scalin izraz mora imati neku vrijednost, postoji singlton vrijednost tipa `Unit`, piše se `()`. +Povratni tip metode `greet` je `Unit`, koji kaže da metoda ne vraća ništa značajno. +Koristi se slično kao `void` u Javi ili C-u. +(Razlika je u tome što svaki Scalin izraz mora imati neku vrijednost, postoji singlton vrijednost tipa `Unit`, piše se `()`. Ne prenosi nikakvu korisnu informaciju.) Instancu klase možete kreirati pomoću ključne riječi `new`. -```tut +```scala mdoc val greeter = new Greeter("Hello, ", "!") greeter.greet("Scala developer") // Hello, Scala developer! ``` @@ -193,16 +193,16 @@ Detaljniji pregled klasa biće dat [kasnije](classes.html). ## Case klase -Scala ima poseban tip klase koji se zove "case" klasa. +Scala ima poseban tip klase koji se zove "case" klasa. Po defaultu, case klase su nepromjenjive i porede se po vrijednosti. Možete ih definisati s `case class` ključnim riječima. -```tut +```scala mdoc case class Point(x: Int, y: Int) ``` Instancu case klase možete kreirati i bez ključne riječi `new`. -```tut +```scala mdoc val point = Point(1, 2) val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) @@ -210,17 +210,17 @@ val yetAnotherPoint = Point(2, 2) I porede se po vrijednosti. -```tut +```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) i Point(1,2) su iste. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) su Point(2,2) različite. ``` @@ -233,7 +233,7 @@ Objasnićemo ih u dubinu [kasnije](case-classes.html). Objekti su jedine instance svojih definicija. Možete misliti o njima kao singltonima svoje vlastite klase. Objekte možete definisati ključnom riječju `object`. -```tut +```scala mdoc object IdFactory { private var counter = 0 def create(): Int = { @@ -245,7 +245,7 @@ object IdFactory { Objektima možete pristupati referenciranjem njihovog imena. -```tut +```scala mdoc val newId: Int = IdFactory.create() println(newId) // 1 val newerId: Int = IdFactory.create() @@ -260,7 +260,7 @@ Trejtovi su tipovi koji sadrže polja i metode. Više trejtova se može kombino Definišu se pomoću `trait` ključne riječi. -```tut +```scala mdoc:nest trait Greeter { def greet(name: String): Unit } @@ -268,7 +268,7 @@ trait Greeter { Metode trejtova mogu imati defaultnu implementaciju. -```tut +```scala mdoc:reset trait Greeter { def greet(name: String): Unit = println("Hello, " + name + "!") @@ -277,7 +277,7 @@ trait Greeter { Možete naslijediti trejtove s `extends` ključnom riječi i redefinisati (override) implementacije s `override` ključnom riječi. -```tut +```scala mdoc class DefaultGreeter extends Greeter class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { @@ -299,12 +299,12 @@ Trejtove ćemo pokriti u dubinu [kasnije](traits.html). ## Glavna metoda -Glavna metoda je ulazna tačka programa. +Glavna metoda je ulazna tačka programa. Java Virtuelna Mašina traži da se glavna metoda zove `main` i da prima jedan argument, niz stringova. Koristeći objekt, možete definisati glavnu metodu ovako: -```tut +```scala mdoc object Main { def main(args: Array[String]): Unit = println("Hello, Scala developer!") diff --git a/_ba/tour/by-name-parameters.md b/_ba/tour/by-name-parameters.md index 4a46335095..5cfc42f8cb 100644 --- a/_ba/tour/by-name-parameters.md +++ b/_ba/tour/by-name-parameters.md @@ -2,9 +2,6 @@ layout: tour title: By-name parametri language: ba - -discourse: true - partof: scala-tour num: 31 @@ -16,7 +13,7 @@ previous-page: operators _By-name parametri_ (u slobodnom prevodu "po-imenu parametri") se izračunavaju samo kada se koriste. Oni su kontrastu sa _by-value parametrima_ ("po-vrijednosti parametri"). Da bi parametar bio pozivan by-name, dodajte `=>` prije njegovog tipa. -```tut +```scala mdoc def calculate(input: => Int) = input * 37 ``` By-name parametri imaju prednost da se ne izračunavaju ako se ne koriste u tijelu funkcije. @@ -24,7 +21,7 @@ U drugu ruku, by-value parametri imaju prednost da se izračunavaju samo jednom. Ovo je primjer kako bi mogli implementirati while petlju: -```tut +```scala mdoc def whileLoop(condition: => Boolean)(body: => Unit): Unit = if (condition) { body diff --git a/_ba/tour/case-classes.md b/_ba/tour/case-classes.md index 2f0babb99f..0c6de6d7b4 100644 --- a/_ba/tour/case-classes.md +++ b/_ba/tour/case-classes.md @@ -2,9 +2,6 @@ layout: tour title: Case klase language: ba - -discourse: true - partof: scala-tour num: 11 @@ -20,7 +17,7 @@ U sljedećem koraku turneje, vidjećemo kako su korisne u [podudaranju uzoraka ( ## Definisanje case klase Minimalna case klasa se sastoji iz ključnih riječi `case class`, identifikatora, i liste parametara (koja može biti prazna): -```tut +```scala mdoc case class Book(isbn: String) val frankenstein = Book("978-0486282114") diff --git a/_ba/tour/classes.md b/_ba/tour/classes.md index aa5c36068c..29f170dca0 100644 --- a/_ba/tour/classes.md +++ b/_ba/tour/classes.md @@ -2,9 +2,6 @@ layout: tour title: Klase language: ba - -discourse: true - partof: scala-tour num: 4 @@ -21,7 +18,7 @@ Tipovi, objekti i trejtovi biće pokriveni kasnije. ## Definisanje klase Minimalna definicija klase sastoji se od riječi `class` i identifikatora. Imena klasa bi trebala počinjati velikim slovom. -```tut +```scala mdoc class User val user1 = new User @@ -31,7 +28,7 @@ Ključna riječ `new` koristi se za kreiranje instance klase. Međutim, često ćete imati konstruktor i tijelo klase. Slijedi definicija klase `Point` (en. tačka): -```tut +```scala mdoc class Point(var x: Int, var y: Int) { def move(dx: Int, dy: Int): Unit = { @@ -59,7 +56,7 @@ Pošto `toString` prebrisava metodu `toString` iz [`AnyRef`](unified-types.html) Konstruktori mogu imati opcione parametre koristeći podrazumijevane vrijednosti: -```tut +```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val origin = new Point // x and y are both set to 0 @@ -70,7 +67,7 @@ println(point1.x) // prints 1 U ovoj verziji klase `Point`, `x` i `y` imaju podrazumijevanu vrijednost `0` tako da ne morate proslijediti argumente. Međutim, pošto se argumenti konstruktora čitaju s lijeva na desno, ako želite proslijediti samo `y` vrijednost, morate imenovati parametar. -``` +```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val point2 = new Point(y=2) println(point2.y) // prints 2 @@ -81,7 +78,7 @@ Ovo je također dobra praksa zbog poboljšanja čitljivosti. ## Privatni članovi i sintaksa getera/setera Članovi su javni (`public`) po defaultu. Koristite `private` modifikator pristupa da sakrijete članove klase. -```tut +```scala mdoc:nest class Point { private var _x = 0 private var _y = 0 @@ -111,14 +108,14 @@ Primijetite specijalnu sintaksu za setere: metoda ima `_=` nadodano na identifik Parametri primarnog konstruktora s `val` i `var` su javni. Međutim, pošto su `val` nepromjenjivi, ne možete napisati sljedeće. -``` +```scala mdoc:fail class Point(val x: Int, val y: Int) val point = new Point(1, 2) point.x = 3 // <-- does not compile ``` Parametri bez `val` ili `var` su privatne vrijednosti, vidljive samo unutar klase. -``` +```scala mdoc:fail class Point(x: Int, y: Int) val point = new Point(1, 2) point.x // <-- does not compile diff --git a/_ba/tour/compound-types.md b/_ba/tour/compound-types.md index 8f84b72176..3781e866e3 100644 --- a/_ba/tour/compound-types.md +++ b/_ba/tour/compound-types.md @@ -2,14 +2,11 @@ layout: tour title: Složeni tipovi language: ba - -discourse: true - partof: scala-tour num: 24 next-page: self-types -previous-page: abstract-types +previous-page: abstract-type-members --- @@ -18,7 +15,7 @@ U Scali ovo može biti izraženo pomoću *složenih tipova*, koji su presjeci ti Pretpostavimo da imamo dva trejta: `Cloneable` i `Resetable`: -```tut +```scala mdoc trait Cloneable extends java.lang.Cloneable { override def clone(): Cloneable = { super.clone().asInstanceOf[Cloneable] @@ -56,4 +53,4 @@ def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { Složeni tipovi mogu se sastojati od više tipova i mogu imati jednu rafinaciju koja može biti korištena da suzi potpis postojećih članova objekta. General forma je: `A with B with C ... { refinement }` -Primjer za upotrebu rafinacije dat je na stranici o [apstraktnim tipovima](abstract-types.html). +Primjer za upotrebu rafinacije dat je na stranici o [apstraktnim tipovima](abstract-type-members.html). diff --git a/_ba/tour/default-parameter-values.md b/_ba/tour/default-parameter-values.md index 2071d3a661..f4fc257900 100644 --- a/_ba/tour/default-parameter-values.md +++ b/_ba/tour/default-parameter-values.md @@ -2,9 +2,6 @@ layout: tour title: Podrazumijevane vrijednosti parametara language: ba - -discourse: true - partof: scala-tour num: 33 @@ -16,7 +13,7 @@ prerequisite-knowledge: named-arguments, function syntax Scala omogućuje davanje podrazumijevanih vrijednosti parametrima koje dozvoljavaju korisniku metode da izostavi te parametre. -```tut +```scala mdoc def log(message: String, level: String = "INFO") = println(s"$level: $message") log("System starting") // prints INFO: System starting @@ -25,7 +22,7 @@ log("User not found", "WARNING") // prints WARNING: User not found Parametar `level` ima podrazumijevanu vrijednost tako da je opcioni. Na zadnjoj liniji, argument `"WARNING"` prebrisava podrazumijevani argument `"INFO"`. Gdje biste koristili overloadane metode u Javi, možete koristiti metode s opcionim parametrima da biste postigli isti efekat. Međutim, ako korisnik izostavi argument, bilo koji sljedeći argumenti moraju biti imenovani. -```tut +```scala mdoc class Point(val x: Double = 0, val y: Double = 0) val point1 = new Point(y = 1) @@ -34,7 +31,7 @@ Ovdje moramo reći `y = 1`. Podrazumijevani parametri u Scali nisu opcioni kada se koriste iz Java koda: -```tut +```scala mdoc:reset // Point.scala class Point(val x: Double = 0, val y: Double = 0) ``` diff --git a/_ba/tour/extractor-objects.md b/_ba/tour/extractor-objects.md index 7aef9bd432..0d0618aa00 100644 --- a/_ba/tour/extractor-objects.md +++ b/_ba/tour/extractor-objects.md @@ -2,9 +2,6 @@ layout: tour title: Ekstraktor objekti language: ba - -discourse: true - partof: scala-tour num: 16 @@ -14,15 +11,15 @@ previous-page: regular-expression-patterns --- Ekstraktor objekat je objekat koji ima `unapply` metodu. -Dok je `apply` metoda kao konstruktor koji uzima argumente i kreira objekat, `unapply` metoda prima objekat i pokušava vratiti argumente. +Dok je `apply` metoda kao konstruktor koji uzima argumente i kreira objekat, `unapply` metoda prima objekat i pokušava vratiti argumente. Ovo se najčešće koristi u podudaranju uzoraka i parcijalnim funkcijama. -```tut +```scala mdoc import scala.util.Random object CustomerID { - def apply(name: String) = s"$name--${Random.nextLong}" + def apply(name: String) = s"$name--${Random.nextLong()}" def unapply(customerID: String): Option[String] = { val name = customerID.split("--").head @@ -37,14 +34,14 @@ customer1ID match { } ``` -Metoda `apply` kreira `CustomerID` string od argumenta `name`. -Metoda `unapply` radi suprotno da dobije `name` nazad. -Kada pozovemo `CustomerID("Sukyoung")`, to je skraćena sintaksa za `CustomerID.apply("Sukyoung")`. +Metoda `apply` kreira `CustomerID` string od argumenta `name`. +Metoda `unapply` radi suprotno da dobije `name` nazad. +Kada pozovemo `CustomerID("Sukyoung")`, to je skraćena sintaksa za `CustomerID.apply("Sukyoung")`. Kada pozovemo `case CustomerID(name) => customer1ID`, ustvari pozivamo `unapply` metodu. Metoda `unapply` se može koristiti i za dodjelu vrijednosti. -```tut +```scala mdoc val customer2ID = CustomerID("Nico") val CustomerID(name) = customer2ID println(name) // prints Nico @@ -52,7 +49,7 @@ println(name) // prints Nico Ovo je ekvivalentno `val name = CustomerID.unapply(customer2ID).get`. Ako se uzorak ne podudari, baciće se `scala.MatchError` izuzetak: -```tut:fail +```scala mdoc:crash val CustomerID(name2) = "--asdfasdfasdf" ``` diff --git a/_ba/tour/for-comprehensions.md b/_ba/tour/for-comprehensions.md index efdeb57dc8..7d5d0f9166 100644 --- a/_ba/tour/for-comprehensions.md +++ b/_ba/tour/for-comprehensions.md @@ -21,7 +21,7 @@ Komprehensija evaluira tijelo `e` za svako vezivanje varijable generisano od str Slijedi primjer: -```tut +```scala mdoc case class User(name: String, age: Int) val userBase = List(User("Travis", 28), @@ -38,7 +38,7 @@ twentySomethings.foreach(name => println(name)) // prints Travis Dennis Slijedi malo komplikovaniji primjer koji s dva generatora. Izračunava sve parove brojeva između `0` i `n-1` čija je suma jednaka vrijednosti `v`: -```tut +```scala mdoc def foo(n: Int, v: Int) = for (i <- 0 until n; j <- i until n if i + j == v) @@ -54,5 +54,5 @@ Ovdje je `n == 10` i `v == 10`. U prvoj iteraciji, `i == 0` i `j == 0` tako da ` Bez `if` čuvara, ovo bi ispisalo sljedeće: ``` -(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 1) ... +(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... ``` diff --git a/_ba/tour/generic-classes.md b/_ba/tour/generic-classes.md index b9601f024c..6b52e9ccd8 100644 --- a/_ba/tour/generic-classes.md +++ b/_ba/tour/generic-classes.md @@ -2,9 +2,6 @@ layout: tour title: Generičke klase language: ba - -discourse: true - partof: scala-tour num: 18 @@ -22,10 +19,11 @@ Vrlo su korisne za implementiranje kolekcija. Generičke klase primaju tip kao parametar u uglastim zagradama `[]`. Konvencija je da se koristi slovo `A` kao identifikator tipa, mada se može koristiti bilo koje ime. -```tut +```scala mdoc class Stack[A] { private var elements: List[A] = Nil - def push(x: A) { elements = x :: elements } + def push(x: A): Unit = + elements = x :: elements def peek: A = elements.head def pop(): A = { val currentTop = peek diff --git a/_ba/tour/higher-order-functions.md b/_ba/tour/higher-order-functions.md index 50531716b0..56f1c1807a 100644 --- a/_ba/tour/higher-order-functions.md +++ b/_ba/tour/higher-order-functions.md @@ -2,9 +2,6 @@ layout: tour title: Funkcije višeg reda language: ba - -discourse: true - partof: scala-tour num: 8 @@ -17,15 +14,15 @@ Scala dozvoljava definisanje funkcija višeg reda. To su funkcije koje _primaju druge funkcije kao parametre_, ili čiji je _rezultat funkcija_. Ovo je funkcija `apply` koja uzima drugu funkciju `f` i vrijednost `v` i primjenjuje funkciju `f` na `v`: -```tut +```scala mdoc def apply(f: Int => String, v: Int) = f(v) ``` _Napomena: metode se automatski pretvaraju u funkcije ako to kontekst zahtijeva._ Ovo je još jedan primjer: - -```tut + +```scala mdoc class Decorator(left: String, right: String) { def layout[A](x: A) = left + x.toString() + right } @@ -36,7 +33,7 @@ object FunTest extends App { println(apply(decorator.layout, 7)) } ``` - + Izvršavanjem se dobije izlaz: ``` diff --git a/_ba/tour/implicit-conversions.md b/_ba/tour/implicit-conversions.md index 69609f61f9..5a1ea3b9fa 100644 --- a/_ba/tour/implicit-conversions.md +++ b/_ba/tour/implicit-conversions.md @@ -2,9 +2,6 @@ layout: tour title: Implicitne konverzije language: ba - -discourse: true - partof: scala-tour num: 27 @@ -46,11 +43,11 @@ Implicitno importovani objekt `scala.Predef` deklariše nekoliko predefinisanih Naprimjer, kada se pozivaju Javine metode koje očekuju `java.lang.Integer`, možete proslijediti `scala.Int`. Možete, zato što `Predef` uključuje slj. implicitnu konverziju: -```tut +```scala mdoc import scala.language.implicitConversions -implicit def int2Integer(x: Int) = - java.lang.Integer.valueOf(x) +implicit def int2Integer(x: Int): Integer = + Integer.valueOf(x) ``` Pošto su implicitne konverzije opasne ako se koriste pogrešno, kompajler upozorava kada kompajlira definiciju implicitne konverzije. diff --git a/_ba/tour/implicit-parameters.md b/_ba/tour/implicit-parameters.md index d3ebff2667..c39d87d626 100644 --- a/_ba/tour/implicit-parameters.md +++ b/_ba/tour/implicit-parameters.md @@ -2,9 +2,6 @@ layout: tour title: Implicitni parametri language: ba - -discourse: true - partof: scala-tour num: 26 @@ -25,7 +22,7 @@ Argumenti koji se mogu proslijediti kao implicitni parametri spadaju u dvije kat U sljedećem primjeru definisaćemo metodu `sum` koja izračunava sumu liste elemenata koristeći `add` i `unit` operacije monoida. Molimo primijetite da implicitne vrijednosti ne mogu biti top-level, već moraju biti članovi templejta. -```tut +```scala mdoc abstract class SemiGroup[A] { def add(x: A, y: A): A } diff --git a/_ba/tour/inner-classes.md b/_ba/tour/inner-classes.md index 0917237fe7..ef72aa8929 100644 --- a/_ba/tour/inner-classes.md +++ b/_ba/tour/inner-classes.md @@ -2,13 +2,10 @@ layout: tour title: Unutarnje klase language: ba - -discourse: true - partof: scala-tour num: 22 -next-page: abstract-types +next-page: abstract-type-members previous-page: lower-type-bounds --- @@ -20,12 +17,12 @@ Pretpostavimo da želimo da nas kompejler spriječi da pomiješamo koji čvorovi Radi ilustracije razlike, prikazaćemo implementaciju klase grafa: -```tut +```scala mdoc class Graph { class Node { var connectedNodes: List[Node] = Nil - def connectTo(node: Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -38,11 +35,11 @@ class Graph { } } ``` - + U našem programu, grafovi su predstavljeni listom čvorova (`List[Node]`). Svaki čvor ima listu drugih čvorova s kojima je povezan (`connectedNodes`). Klasa `Node` je _path-dependent tip_ jer je ugniježdena u klasi `Graph`. Stoga, svi čvorovi u `connectedNodes` moraju biti kreirani koristeći `newNode` iz iste instance klase `Graph`. -```tut +```scala mdoc val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode val node2: graph1.Node = graph1.newNode @@ -50,14 +47,14 @@ val node3: graph1.Node = graph1.newNode node1.connectTo(node2) node3.connectTo(node1) ``` - + Eksplicitno smo deklarisali tip `node1`, `node2`, i `node3` kao `graph1.Node` zbog jasnosti ali ga je kompajler mogao sam zaključiti. Pošto kada pozivamo `graph1.newNode` koja poziva `new Node`, metoda koristi instancu `Node` specifičnu instanci `graph1`. Da imamo dva grafa, sistem tipova Scale ne dozvoljava miješanje čvorova definisanih u različitim grafovima, jer čvorovi različitih grafova imaju različit tip. Ovo je primjer netačnog programa: - -``` + +```scala mdoc:fail val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode val node2: graph1.Node = graph1.newNode @@ -72,13 +69,13 @@ U Javi bi zadnja linija prethodnog primjera bila tačna. Za čvorove oba grafa, Java bi dodijelila isti tip `Graph.Node`; npr. `Node` bi imala prefiks klase `Graph`. U Scali takav tip je također moguće izraziti, piše se kao `Graph#Node`. Ako želimo povezati čvorove različitih grafova, moramo promijeniti definiciju naše inicijalne implementacije grafa: - -```tut + +```scala mdoc:nest class Graph { class Node { var connectedNodes: List[Graph#Node] = Nil - def connectTo(node: Graph#Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -91,6 +88,6 @@ class Graph { } } ``` - + > Primijetite da ovaj program ne dozvoljava da dodamo čvor u dva različita grafa. Ako bi htjeli ukloniti i ovo ograničenje, moramo promijeniti tipski parametar `nodes` u `Graph#Node`. diff --git a/_ba/tour/lower-type-bounds.md b/_ba/tour/lower-type-bounds.md index cf310ead80..85dd54a401 100644 --- a/_ba/tour/lower-type-bounds.md +++ b/_ba/tour/lower-type-bounds.md @@ -2,9 +2,6 @@ layout: tour title: Donja granica tipa language: ba - -discourse: true - partof: scala-tour num: 21 @@ -20,7 +17,7 @@ Izraz `B >: A` izražava tipski parametar `B` ili apstraktni tip `B` koji je nad Kroz sljedeći primjer vidjećemo zašto je ovo korisno: -```tut:fail +```scala mdoc:fail trait Node[+B] { def prepend(elem: B): Node[B] } @@ -46,7 +43,7 @@ Ovo ne radi jer su funkcije *kontra*varijantne u svojim tipovima parametara i *k Da bismo popravili ovo, moramo zamijeniti varijansu tipskog parametra `elem` u `prepend`. Ovo radimo uvođenjem novog tipskog parametra `U` koji ima `B` kao svoju donju granicu tipa. -```tut +```scala mdoc trait Node[+B] { def prepend[U >: B](elem: U): Node[U] } @@ -63,7 +60,7 @@ case class Nil[+B]() extends Node[B] { ``` Sada možemo uraditi sljedeće: -```tut +```scala mdoc trait Bird case class AfricanSwallow() extends Bird case class EuropeanSwallow() extends Bird @@ -71,6 +68,6 @@ case class EuropeanSwallow() extends Bird val africanSwallowList= ListNode[AfricanSwallow](AfricanSwallow(), Nil()) val birdList: Node[Bird] = africanSwallowList -birdList.prepend(new EuropeanSwallow) +birdList.prepend(EuropeanSwallow()) ``` `Node[Bird]` može biti dodijeljena `africanSwallowList` ali onda prihvatiti `EuropeanSwallow`e. diff --git a/_ba/tour/mixin-class-composition.md b/_ba/tour/mixin-class-composition.md index 7a1940bcc0..a8216abfb6 100644 --- a/_ba/tour/mixin-class-composition.md +++ b/_ba/tour/mixin-class-composition.md @@ -2,21 +2,18 @@ layout: tour title: Kompozicija mixin klasa language: ba - -discourse: true - partof: scala-tour num: 6 next-page: higher-order-functions -previous-page: traits +previous-page: tuples prerequisite-knowledge: inheritance, traits, abstract-classes, unified-types --- Mixini su trejtovi koji se koriste za kompoziciju klase. -```tut +```scala mdoc abstract class A { val message: String } @@ -32,23 +29,23 @@ val d = new D d.message // I'm an instance of class B d.loudMessage // I'M AN INSTANCE OF CLASS B ``` -Klasa `D` je nadklasa od `B` i mixina `C`. +Klasa `D` je nadklasa od `B` i mixina `C`. Klase mogu imati samo jednu nadklasu alid mogu imati više mixina (koristeći ključne riječi `extends` i `with` respektivno). Mixini i nadklasa mogu imati isti nadtip. Pogledajmo sada zanimljiviji primjer počevši od apstraktne klase: - -```tut + +```scala mdoc abstract class AbsIterator { type T def hasNext: Boolean def next(): T } ``` - + Klasa ima apstraktni tip `T` i standardne metode iteratora. Dalje, implementiraćemo konkretnu klasu (svi apstraktni članovi `T`, `hasNext`, i `next` imaju implementacije): -```tut +```scala mdoc class StringIterator(s: String) extends AbsIterator { type T = Char private var i = 0 @@ -62,14 +59,14 @@ class StringIterator(s: String) extends AbsIterator { ``` `StringIterator` prima `String` i može se koristiti za iteraciju nad `String`om (npr. da vidimo da li sadrži određeni karakter). - + trait RichIterator extends AbsIterator { - def foreach(f: T => Unit) { while (hasNext) f(next()) } + def foreach(f: T => Unit): Unit = { while (hasNext) f(next()) } } Kreirajmo sada trejt koji također nasljeđuje `AbsIterator`. -```tut +```scala mdoc trait RichIterator extends AbsIterator { def foreach(f: T => Unit): Unit = while (hasNext) f(next()) } @@ -77,16 +74,16 @@ trait RichIterator extends AbsIterator { Pošto je `RichIterator` trejt, on ne mora implementirati apstraktne članove `AbsIterator`a. -Željeli bismo iskombinirati funkcionalnosti `StringIterator`a i `RichIterator`a u jednoj klasi. +Željeli bismo iskombinirati funkcionalnosti `StringIterator`a i `RichIterator`a u jednoj klasi. -```tut +```scala mdoc object StringIteratorTest extends App { class Iter extends StringIterator("Scala") with RichIterator val iter = new Iter iter foreach println } ``` - + Nova klasa `Iter` ima `StringIterator` kao nadklasu i `RichIterator` kao mixin. S jednostrukim nasljeđivanjem ne bismo mogli postići ovaj nivo fleksibilnosti. diff --git a/_ba/tour/multiple-parameter-lists.md b/_ba/tour/multiple-parameter-lists.md index ba0042557c..68230aa12b 100644 --- a/_ba/tour/multiple-parameter-lists.md +++ b/_ba/tour/multiple-parameter-lists.md @@ -2,9 +2,6 @@ layout: tour title: Curry-jevanje language: ba - -discourse: true - partof: scala-tour num: 10 @@ -19,7 +16,7 @@ onda će to vratiti funkciju koja prima preostale liste parametara kao argumente Primjer: -```tut +```scala mdoc object CurryTest extends App { def filter(xs: List[Int], p: Int => Boolean): List[Int] = diff --git a/_ba/tour/named-arguments.md b/_ba/tour/named-arguments.md index a2e98b1d56..6656b02da2 100644 --- a/_ba/tour/named-arguments.md +++ b/_ba/tour/named-arguments.md @@ -2,9 +2,6 @@ layout: tour title: Imenovani parametri language: ba - -discourse: true - partof: scala-tour num: 34 @@ -15,7 +12,7 @@ prerequisite-knowledge: function-syntax Kada se pozivaju metode, možete koristiti imena varijabli eksplicitno pri pozivu: -```tut +```scala mdoc def printName(first: String, last: String): Unit = { println(first + " " + last) } diff --git a/_ba/tour/nested-functions.md b/_ba/tour/nested-functions.md index f7122a33f8..1a00eaba59 100644 --- a/_ba/tour/nested-functions.md +++ b/_ba/tour/nested-functions.md @@ -2,9 +2,6 @@ layout: tour title: Ugniježdene metode language: ba - -discourse: true - partof: scala-tour num: 9 @@ -16,7 +13,7 @@ previous-page: higher-order-functions U Scali je moguće ugnježdavati definicije metode. Sljedeći objekt sadrži metodu `factorial` za računanje faktorijela datog broja: -```tut +```scala mdoc def factorial(x: Int): Int = { def fact(x: Int, accumulator: Int): Int = { if (x <= 1) accumulator diff --git a/_ba/tour/operators.md b/_ba/tour/operators.md index 363cf74858..f1e8f3da07 100644 --- a/_ba/tour/operators.md +++ b/_ba/tour/operators.md @@ -2,9 +2,6 @@ layout: tour title: Operatori language: ba - -discourse: true - partof: scala-tour num: 30 @@ -28,9 +25,9 @@ Međutim, lakše je čitati kada se napiše kao infiksni operator: ## Definisanje i korištenje operatora Možete koristiti bilo koji legalni identifikator kao operator. To uključuje i imena kao `add` ili simbole kao `+`. -```tut -case class Vec(val x: Double, val y: Double) { - def +(that: Vec) = new Vec(this.x + that.x, this.y + that.y) +```scala mdoc +case class Vec(x: Double, y: Double) { + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) } val vector1 = Vec(1.0, 1.0) @@ -45,7 +42,7 @@ Koristeći zagrade, možete pisati kompleksne izraze s čitljivom sintaksom. Slijedi definicija klase `MyBool` koja definiše tri metode `and`, `or`, i `negate`. -```tut +```scala mdoc case class MyBool(x: Boolean) { def and(that: MyBool): MyBool = if (x) that else this def or(that: MyBool): MyBool = if (x) this else that @@ -55,7 +52,7 @@ case class MyBool(x: Boolean) { Sada je moguće koristiti `and` i `or` kao infiksne operatore: -```tut +```scala mdoc def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) ``` @@ -74,7 +71,7 @@ Kada izraz koristi više operatora, operatori se primjenjuju bazirano na priorit & ^ | -(sva slova) +(sva slova, $, _) ``` Ovo se odnosi na metode koje definišete. Npr, sljedeći izraz: ``` diff --git a/_ba/tour/package-objects.md b/_ba/tour/package-objects.md new file mode 100644 index 0000000000..cef657c1f5 --- /dev/null +++ b/_ba/tour/package-objects.md @@ -0,0 +1,14 @@ +--- +layout: tour +title: Package Objects +language: ba +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- + +# Package objects + +(this section of the tour has not been translated yet. pull request +with translation welcome!) diff --git a/_ba/tour/packages-and-imports.md b/_ba/tour/packages-and-imports.md index b466c5946a..b21770e3d0 100644 --- a/_ba/tour/packages-and-imports.md +++ b/_ba/tour/packages-and-imports.md @@ -2,14 +2,11 @@ layout: tour title: Packages and Imports language: ba - -discourse: true - partof: scala-tour num: 35 previous-page: named-arguments -next-page: type-inference +next-page: package-objects --- # Packages and Imports diff --git a/_ba/tour/pattern-matching.md b/_ba/tour/pattern-matching.md index 9e304a3fd0..e303e05d63 100644 --- a/_ba/tour/pattern-matching.md +++ b/_ba/tour/pattern-matching.md @@ -2,9 +2,6 @@ layout: tour title: Podudaranje uzoraka (pattern matching) language: ba - -discourse: true - partof: scala-tour num: 12 @@ -19,7 +16,7 @@ Podudaranje uzoraka je mehanizam za provjeranje da li vrijednost odgovara uzroku ## Sintaksa Izraz za podudaranje ima vrijednost, `match` ključnu riječ, i bar jednu `case` klauzu. -```tut +```scala mdoc import scala.util.Random val x: Int = Random.nextInt(10) @@ -37,7 +34,7 @@ Zadnji slučaj, `_`, je "uhvati sve" slučaj za brojeve veće od 2. Slučajevi se još zovu i _alternative_. Izrazi za podudaranje imaju vrijednost. -```tut +```scala mdoc def matchTest(x: Int): String = x match { case 1 => "one" case 2 => "two" @@ -53,7 +50,7 @@ Stoga, metoda `matchTest` vraća `String`. Case klase su posebno korisne za podudaranje uzoraka. -```tut +```scala mdoc abstract class Notification case class Email(sender: String, title: String, body: String) extends Notification @@ -121,9 +118,9 @@ U `case Email(email, _, _) if importantPeopleInfo.contains(email)`, uzorak se po ## Podudaranje samo tipa Možete podudarati samo tip ovako: -```tut +```scala mdoc abstract class Device -case class Phone(model: String) extends Device{ +case class Phone(model: String) extends Device { def screenOff = "Turning screen off" } case class Computer(model: String) extends Device { @@ -143,7 +140,7 @@ Konvencija je da se koristi prvo slovo tipa kao identifikator (`p` i `c` ovdje). Trejtovi i klase mogu biti `sealed` što znači da svi podtipovi moraju biti reklarisani u istom fajlu. Ovo osigurava da su svi podtipovi poznati. -```tut +```scala mdoc sealed abstract class Furniture case class Couch() extends Furniture case class Chair() extends Furniture diff --git a/_ba/tour/polymorphic-methods.md b/_ba/tour/polymorphic-methods.md index 250cd850ee..a5ad6e27f4 100644 --- a/_ba/tour/polymorphic-methods.md +++ b/_ba/tour/polymorphic-methods.md @@ -2,9 +2,6 @@ layout: tour title: Polimorfne metode language: ba - -discourse: true - partof: scala-tour num: 28 @@ -21,7 +18,7 @@ Vrijednosni parameteri ("obični") su ograđeni parom zagrada, dok su tipski par Slijedi primjer: -```tut +```scala mdoc def listOfDuplicates[A](x: A, length: Int): List[A] = { if (length < 1) Nil diff --git a/_ba/tour/regular-expression-patterns.md b/_ba/tour/regular-expression-patterns.md index bf6a256e76..558b039a24 100644 --- a/_ba/tour/regular-expression-patterns.md +++ b/_ba/tour/regular-expression-patterns.md @@ -2,9 +2,6 @@ layout: tour title: Regularni izrazi language: ba - -discourse: true - partof: scala-tour num: 15 @@ -17,7 +14,7 @@ previous-page: singleton-objects Regularni izrazi su stringovi koji se mogu koristiti za traženje uzoraka u podacima. Bilo koji string se može pretvoriti u regularni izraz pozivom `.r` metode. -```tut +```scala mdoc import scala.util.matching.Regex val numberPattern: Regex = "[0-9]".r @@ -33,7 +30,7 @@ U gornjem primjeru, `numberPattern` je `Regex` Također, možete tražiti grupe regularnih izraza koristeći zagrade. -```tut +```scala mdoc import scala.util.matching.Regex val keyValPattern: Regex = "([0-9a-zA-Z-#() ]+): ([0-9a-zA-Z-#() ]+)".r diff --git a/_ba/tour/self-types.md b/_ba/tour/self-types.md index 0160d48250..9b0ccd95a2 100644 --- a/_ba/tour/self-types.md +++ b/_ba/tour/self-types.md @@ -2,9 +2,6 @@ layout: tour title: Self-tipovi language: ba - -discourse: true - partof: scala-tour num: 25 @@ -20,7 +17,7 @@ Self-tip je način da se suzi tip `this` ili drugi identifikator koji je alijas Sintaksa izgleda kao obična funkcija ali znači nešto sasvim drugačije. Da bi koristili self-tip u trejtu, napišite identifikator, tip drugog trejta za umiksavanje, i `=>` (tj. `someIdentifier: SomeOtherTrait =>`). -```tut +```scala mdoc trait User { def username: String } diff --git a/_ba/tour/singleton-objects.md b/_ba/tour/singleton-objects.md index 0b570b4593..7f8ac84ba4 100644 --- a/_ba/tour/singleton-objects.md +++ b/_ba/tour/singleton-objects.md @@ -2,9 +2,6 @@ layout: tour title: Singlton objekti language: ba - -discourse: true - partof: scala-tour num: 13 @@ -34,7 +31,7 @@ Kao i `val`, singlton objekti mogu biti definisani kao članovi [trejta](traits. Singlton objekt može naslijediti klase i trejtove. Ustvari, [case klasa](case-classes.html) bez [tipskih parametara](generic-classes.html) će podrazumijevano kreirati singlton objekt s istim imenom, -i implementiranim [`Function*`](http://www.scala-lang.org/api/current/scala/Function1.html) trejtom. +i implementiranim [`Function*`](https://www.scala-lang.org/api/current/scala/Function1.html) trejtom. ## Kompanjoni (prijatelji) ## @@ -47,7 +44,7 @@ ako krug s velikim “C” ili “O” ima savijenu ivicu (kao papir), možete k Klasa i njen kompanjon objekt, ako ga ima, moraju biti definisani u istom izvornom fajlu: -```tut +```scala mdoc class IntPair(val x: Int, val y: Int) object IntPair { diff --git a/_ba/tour/tour-of-scala.md b/_ba/tour/tour-of-scala.md index e30b2cc5c5..9ebb53983b 100644 --- a/_ba/tour/tour-of-scala.md +++ b/_ba/tour/tour-of-scala.md @@ -2,9 +2,6 @@ layout: tour title: Uvod language: ba - -discourse: true - partof: scala-tour num: 1 @@ -45,7 +42,7 @@ Konkretno, sistem tipova podržava sljedeće: * [generičke klase](generic-classes.html) * [anotacije varijanse](variances.html) * [gornje](upper-type-bounds.html) i [donje](lower-type-bounds.html) granice tipa, -* [unutarnje klase](inner-classes.html) i [apstraktne tipove](abstract-types.html) kao članove objekta +* [unutarnje klase](inner-classes.html) i [apstraktne tipove](abstract-type-members.html) kao članove objekta * [složene tipove](compound-types.html) * [eksplicitno tipizirane samo-reference](self-types.html) * implicitne [parametre](implicit-parameters.html) i [konverzije](implicit-conversions.html) diff --git a/_ba/tour/traits.md b/_ba/tour/traits.md index d4ac8596e0..8f7a82cc9e 100644 --- a/_ba/tour/traits.md +++ b/_ba/tour/traits.md @@ -2,13 +2,10 @@ layout: tour title: Trejtovi language: ba - -discourse: true - partof: scala-tour num: 5 -next-page: mixin-class-composition +next-page: tuples previous-page: classes assumed-knowledge: expressions, classes, generics, objects, companion-objects @@ -21,12 +18,12 @@ Klase i objekti mogu naslijediti trejtove ali trejtovi ne mogu biti instancirani ## Definisanje trejta Minimalni trejt je samo ključna riječ `trait` i identifikator: -```tut +```scala mdoc trait HairColor ``` Trejtovi su vrlo korisni s generičkim tipovima i apstraktnim metodama. -```tut +```scala mdoc trait Iterator[A] { def hasNext: Boolean def next(): A @@ -37,7 +34,7 @@ Nasljeđivanje `trait Iterator[A]` traži tip `A` i implementacije metoda `hasNe ## Korištenje trejtova Koristite `extends` za nasljeđivanje trejta. Zatim implementirajte njegove apstraktne članove koristeći `override` ključnu riječ: -```tut +```scala mdoc:nest trait Iterator[A] { def hasNext: Boolean def next(): A @@ -65,7 +62,7 @@ Ona nasljeđuje `Iterator[Int]` što znači da `next` mora vraćati `Int`. ## Podtipovi Podtipovi trejtova mogu se koristiti gdje se trejt traži. -```tut +```scala mdoc import scala.collection.mutable.ArrayBuffer trait Pet { diff --git a/_ba/tour/tuples.md b/_ba/tour/tuples.md new file mode 100644 index 0000000000..99f49e7247 --- /dev/null +++ b/_ba/tour/tuples.md @@ -0,0 +1,13 @@ +--- +layout: tour +title: Tuples +language: ba +partof: scala-tour +num: +next-page: mixin-class-composition +previous-page: traits + +--- + +(this section of the tour has not been translated yet. pull request +with translation welcome!) diff --git a/_ba/tour/type-inference.md b/_ba/tour/type-inference.md index 926c3a4feb..d3b7eb1867 100644 --- a/_ba/tour/type-inference.md +++ b/_ba/tour/type-inference.md @@ -2,9 +2,6 @@ layout: tour title: Lokalno zaključivanje tipova (type inference) language: ba - -discourse: true - partof: scala-tour num: 29 @@ -19,7 +16,7 @@ Povratni tipovi metoda također mogu biti izostavljeni jer oni odgovaraju tipu t Slijedi jedan primjer: -```tut +```scala mdoc object InferenceTest1 extends App { val x = 1 + 2 * 3 // the type of x is Int val y = x.toString() // the type of y is String @@ -30,7 +27,7 @@ object InferenceTest1 extends App { Za rekurzivne metode, kompajler nije u mogućnosti da zaključi tip rezultata. Ovo je program koji se ne može kompajlirati iz ovog razloga: -```tut:fail +```scala mdoc:fail object InferenceTest2 { def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1) } @@ -43,7 +40,7 @@ Scala kompajler će zaključiti nedostajuće tipske parametre iz konteksta i iz Ovo je primjer koji to ilustrira: ``` -case class MyPair[A, B](x: A, y: B); +case class MyPair[A, B](x: A, y: B) object InferenceTest3 extends App { def id[T](x: T) = x val p = MyPair(1, "scala") // type: MyPair[Int, String] @@ -61,7 +58,7 @@ val y: Int = id[Int](1) U nekim situacijama može biti vrlo opasno osloniti se na Scalin mehanizam zaključivanja tipova: -```tut:fail +```scala mdoc:fail object InferenceTest4 { var obj = null obj = new Object() diff --git a/_ba/tour/unified-types.md b/_ba/tour/unified-types.md index 44af9e748e..92c1e2a61e 100644 --- a/_ba/tour/unified-types.md +++ b/_ba/tour/unified-types.md @@ -2,9 +2,6 @@ layout: tour title: Sjedinjeni tipovi language: ba - -discourse: true - partof: scala-tour num: 3 @@ -21,14 +18,14 @@ Dijagram ispod prikazuje hijerarhiju Scala klasa. ## Hijerarhija tipova u Scali ## -[`Any`](http://www.scala-lang.org/api/2.12.1/scala/Any.html) je nadtip svih tipova, zove se još i vrh-tip. +[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html) je nadtip svih tipova, zove se još i vrh-tip. Definiše određene univerzalne metode kao što su `equals`, `hashCode` i `toString`. `Any` ima dvije direktne podklase, `AnyVal` i `AnyRef`. -`AnyVal` predstavlja vrijednosne tipove. Postoji devet predefinisanih vrijednosnih tipova i oni ne mogu biti `null`: +`AnyVal` predstavlja vrijednosne tipove. Postoji devet predefinisanih vrijednosnih tipova i oni ne mogu biti `null`: `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit` i `Boolean`. -`Unit` je vrijednosni tip koji ne nosi značajnu informaciju. Postoji tačno jedna instanca tipa `Unit` koja se piše `()`. +`Unit` je vrijednosni tip koji ne nosi značajnu informaciju. Postoji tačno jedna instanca tipa `Unit` koja se piše `()`. Sve funkcije moraju vratiti nešto tako da je `Unit` ponekad koristan povratni tip. `AnyRef` predstavlja referencne tipove. Svi nevrijednosni tipovi definišu se kao referencni. @@ -37,7 +34,7 @@ Ako se Scala koristi u kontekstu JRE, onda `AnyRef` odgovara klasi `java.lang.Ob Slijedi primjer koji demonstrira da su stringovi, integeri, karakteri, booleani i funkcije svi objekti kao bilo koji drugi: -```tut +```scala mdoc val list: List[Any] = List( "a string", 732, // an integer @@ -67,9 +64,9 @@ Vrijednosni tipovi mogu biti kastovani na sljedeći način: Npr: -```tut +```scala mdoc val x: Long = 987654321 -val y: Float = x // 9.8765434E8 (određena doza preciznosti se gubi ovdje) +val y: Float = x.toFloat // 9.8765434E8 (određena doza preciznosti se gubi ovdje) val face: Char = '☺' val number: Int = face // 9786 @@ -79,17 +76,17 @@ Kastovanje je jednosmjerno. Ovo se ne kompajlira: ``` val x: Long = 987654321 -val y: Float = x // 9.8765434E8 +val y: Float = x.toFloat // 9.8765434E8 val z: Long = y // Does not conform ``` Također možete kastovati i referencni tip u podtip. Ovo će biti pokriveno kasnije. ## Nothing i Null -`Nothing` je podtip svih tipova, također se zove i donji tip (en. bottom type). Ne postoji vrijednost koja ima tip `Nothing`. +`Nothing` je podtip svih tipova, također se zove i donji tip (en. bottom type). Ne postoji vrijednost koja ima tip `Nothing`. Česta upotreba ovog tipa je signalizacija neterminacije kao što je bacanje izuzetka, izlaz iz programa, ili beskonačna petlja (tj. tip izraza koji se ne izračunava u vrijednost, ili metoda koja se ne završava normalno). -`Null` je podtip svih referencnih tipova (tj. bilo kog podtipa `AnyRef`). -Ima jednu vrijednost koja se piše literalom `null`. -`Null` se uglavnom koristi radi interoperabilnosti s ostalim JVM jezicima i skoro nikad se ne koristi u Scala kodu. +`Null` je podtip svih referencnih tipova (tj. bilo kog podtipa `AnyRef`). +Ima jednu vrijednost koja se piše literalom `null`. +`Null` se uglavnom koristi radi interoperabilnosti s ostalim JVM jezicima i skoro nikad se ne koristi u Scala kodu. Alternative za `null` obradićemo kasnije. diff --git a/_ba/tour/upper-type-bounds.md b/_ba/tour/upper-type-bounds.md index b8afa51ee2..e91d904d5d 100644 --- a/_ba/tour/upper-type-bounds.md +++ b/_ba/tour/upper-type-bounds.md @@ -2,9 +2,6 @@ layout: tour title: Gornja granica tipa language: ba - -discourse: true - partof: scala-tour categories: tour num: 20 @@ -13,12 +10,12 @@ previous-page: variances --- -U Scali, [tipski parametri](generic-classes.html) i [apstraktni tipovi](abstract-types.html) mogu biti ograničeni granicom tipa. +U Scali, [tipski parametri](generic-classes.html) i [apstraktni tipovi](abstract-type-members.html) mogu biti ograničeni granicom tipa. Takve granice tipa ograničavaju konkretne vrijednosti tipskih varijabli i ponekad otkrivaju još informacija o članovima takvih tipova. _Gornja granica tipa_ `T <: A` kaže da se tipska varijabla `T` odnosi na podtip tipa `A`. Slijedi primjer koji demonstrira gornju granicu tipa za tipski parametar klase `PetContainer`: -```tut +```scala mdoc abstract class Animal { def name: String } @@ -45,7 +42,7 @@ val dogContainer = new PetContainer[Dog](new Dog) val catContainer = new PetContainer[Cat](new Cat) ``` -```tut:fail +```scala mdoc:fail val lionContainer = new PetContainer[Lion](new Lion) // this would not compile ``` Klasa `PetContainer` prima tipski parametar `P` koji mora biti podtip od `Pet`. diff --git a/_ba/tour/variances.md b/_ba/tour/variances.md index a1f955543a..2920e00dac 100644 --- a/_ba/tour/variances.md +++ b/_ba/tour/variances.md @@ -2,9 +2,6 @@ layout: tour title: Varijanse language: ba - -discourse: true - partof: scala-tour num: 19 @@ -17,7 +14,7 @@ Varijansa je korelacija podtipskih veza kompleksnih tipova i podtipskih veza nji Scala podržava anotacije varijanse tipskih parametara [generičkih klasa](generic-classes.html), dozvoljavajući im da budu kovarijantni, kontravarijantni, ili invarijantni ako se anotacije ne koriste. Korištenje varijanse u sistemu tipova dozvoljava pravljenje intuitivnijih veza među kompleksnim tipovima, a nedostatak varijanse može ograničiti ponovno iskorištenje klasne apstrakcije. -```tut +```scala mdoc class Foo[+A] // kovarijantna klasa class Bar[-A] // kontravarijantna klasa class Baz[A] // invarijantna klasa @@ -31,7 +28,7 @@ Ovo dozvoljava pravljenje vrlo intuitivnih podtipskih veza koristeći generiku. Razmotrite sljedeću strukturu klasa: -```tut +```scala mdoc abstract class Animal { def name: String } @@ -47,7 +44,7 @@ Intuitivno, ima smisla da su lista mačaka i lista pasa također liste životinj U sljedećem primjeru, metoda `printAnimalNames` prima listu životinja kao argument i ispisuje njihova imena, svako na idućoj liniji. Da `List[A]` nije kovarijantna, zadnja dva poziva metode se ne bi kompajlirali, što bi značajno ograničilo korisnost `printAnimalNames` metode. -```tut +```scala mdoc object CovarianceTest extends App { def printAnimalNames(animals: List[Animal]): Unit = { animals.foreach { animal => @@ -76,7 +73,7 @@ To jest, za neku `class Writer[-A]`, kontravarijantno `A` znači da za dva tipa Razmotrimo `Cat`, `Dog`, i `Animal` klase u sljedećem primjeru: -```tut +```scala mdoc abstract class Printer[-A] { def print(value: A): Unit } @@ -84,7 +81,7 @@ abstract class Printer[-A] { `Printer[A]` je jednostavna klasa koja zna ispisati neki tip `A`. Definišimo neke podklase za specifične tipove: -```tut +```scala mdoc class AnimalPrinter extends Printer[Animal] { def print(animal: Animal): Unit = println("The animal's name is: " + animal.name) @@ -102,7 +99,7 @@ Inverzna veza ne vrijedi, jer `Printer[Cat]` ne zna kako da ispiše bilo koju `A Stoga, terbali bismo moći zamijeniti `Printer[Animal]` za `Printer[Cat]`, ako želimo, i praveći `Printer[A]` kontravarijantnim nam to dozvoljava. -```tut +```scala mdoc object ContravarianceTest extends App { val myCat: Cat = Cat("Boots") @@ -132,7 +129,7 @@ Ovo znač da nisu ni kovarijantne ni kontravarijantne. U kontekstu sljedećeg primjera, `Container` klasa je invarijantna. `Container[Cat]` _nije_ `Container[Animal]`, niti obrnuto. -```tut +```scala mdoc class Container[A](value: A) { private var _value: A = value def getValue: A = _value @@ -165,7 +162,7 @@ Za ovaj primjer koristićemo literal notaciju `A => B` za predstavljanje `Functi Pretpostavimo da imamo sličnu hijerarhiju klasa `Cat`, `Dog`, `Animal` otprije, plus sljedeće: -```tut +```scala mdoc class SmallAnimal class Mouse extends SmallAnimal ``` diff --git a/_books/1-programming-in-scala-3rd.md b/_books/1-programming-in-scala-3rd.md deleted file mode 100644 index 4c04d132c8..0000000000 --- a/_books/1-programming-in-scala-3rd.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Programming in Scala, 3rd ed" -link: http://booksites.artima.com/programming_in_scala_3ed -image: /resources/img/books/ProgrammingInScala.gif -status: Updated for Scala 2.12 -authors: ["Martin Odersky", "Lex Spoon", "Bill Benners"] -publisher: ---- - -(First edition [available for free online reading](http://www.artima.com/pins1ed/)) - -Being co-written by the language's designer, Martin Odersky, you will find it provides additional depth and clarity to the diverse features of the language. The book provides both an authoritative reference for Scala and a systematic tutorial covering all the features in the language. Once you are familiar with the basics of Scala you will appreciate having this source of invaluable examples and precise explanations of Scala on hand. The book is available from [Artima](http://booksites.artima.com/programming_in_scala_3ed). Award winning book - [Jolt Productivity award](http://www.drdobbs.com/joltawards/232601431) for Technical Books. diff --git a/_books/1-programming-in-scala-5th.md b/_books/1-programming-in-scala-5th.md new file mode 100644 index 0000000000..826e5361df --- /dev/null +++ b/_books/1-programming-in-scala-5th.md @@ -0,0 +1,11 @@ +--- +title: "Programming in Scala, 5th ed" +link: https://www.artima.com/shop/programming_in_scala_5ed +image: /resources/img/books/ProgrammingInScala.png +status: Updated for Scala 3 +authors: ["Martin Odersky", "Lex Spoon", "Bill Venners"] +publisher: Artima +publisherLink: https://www.artima.com/books +--- + +This book is co-authored by the language's designer, Martin Odersky. It provides depth and clarity on the diverse features of the language. The book provides both an authoritative reference for Scala and a systematic tutorial covering all the features in the language. Once you are familiar with the basics of Scala you will appreciate having this source of invaluable examples and precise explanations of Scala on hand. The book is available from [Artima](https://www.artima.com/shop/programming_in_scala_5ed). Award winning book - [Jolt Productivity award](https://www.drdobbs.com/joltawards/232601431) for Technical Books. diff --git a/_books/2-programming-scala.md b/_books/2-programming-scala.md new file mode 100644 index 0000000000..8fc729169f --- /dev/null +++ b/_books/2-programming-scala.md @@ -0,0 +1,11 @@ +--- +title: "Programming Scala" +link: http://programming-scala.com +image: /resources/img/books/ProgrammingScala-final-border.gif +status: Updated for Scala 3 +authors: ["Dean Wampler"] +publisher: O’Reilly +publisherLink: https://www.oreilly.com/ +--- + +Dean is a well-known member of the Scala community, using Scala recently for streaming data systems at Lightbend and now at Domino Data Lab. This edition covers the new features of Scala 3, with comparisons to Scala 2, both to explain why the changes were made and how they improve Scala, and also to enable developers using mixed Scala 2 and 3 code bases to work effectively. The book is aimed at professional programmers who want a comprehensive, in-depth, yet pragmatic tour of Scala and best practices for using it. diff --git a/_books/3-programming-scala.md b/_books/3-programming-scala.md deleted file mode 100644 index eb814ff1fb..0000000000 --- a/_books/3-programming-scala.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Programming Scala" -link: http://shop.oreilly.com/product/0636920033073.do -image: /resources/img/books/ProgrammingScala-final-border.gif -status: Updated for Scala 2.11 -authors: ["Alex Payne", "Dean Wampler"] -publisher: O’Reilly -publisherLink: http://www.oreilly.com/ ---- - -Both are industry experts, Alex Payne being the lead API programmer at Twitter, a social networking service based on Scala. O’Reilly, the publisher, writes: "Learn how to be more productive with Scala, a new multi-paradigm language for the Java Virtual Machine (JVM) that integrates features of both object-oriented and functional programming. With this book, you'll discover why Scala is ideal for highly scalable, component-based applications that support concurrency and distribution. You'll also learn how to leverage the wealth of Java class libraries to meet the practical needs of enterprise and Internet projects more easily." \ No newline at end of file diff --git a/_books/2-scala-for-the-impatient.md b/_books/3-scala-for-the-impatient.md similarity index 56% rename from _books/2-scala-for-the-impatient.md rename to _books/3-scala-for-the-impatient.md index 41e63d0c1d..72c7c01f6d 100644 --- a/_books/2-scala-for-the-impatient.md +++ b/_books/3-scala-for-the-impatient.md @@ -1,15 +1,17 @@ --- title: "Scala for the Impatient" -link: http://www.horstmann.com/scala/index.html -image: /resources/img/books/scala_for_the_impatient.png -status: Available Now -authors: ["Cay S. Horstmann"] -publisher: Addison-Wesley +link: https://horstmann.com/scala/ +image: /resources/img/books/scala_for_the_impatient.jpg +status: Updated for Scala 3 +authors: ["Cay Horstmann"] +publisher: Addison-Wesley Professional +publisherLink: https://www.oreilly.com/publisher/addison-wesley-professional/ --- What you get: -* A rapid introduction to Scala for programmers who are competent in Java, C#, or C++ +* Up to date coverage of Scala 3 +* A rapid introduction to Scala for programmers who are competent in another language such as Java, C#, Python, JavaScript, or C++ * Blog-length chunks of information that you can digest quickly * An organization that you'll find useful as a quick reference diff --git a/_books/4-hands-on-scala.md b/_books/4-hands-on-scala.md new file mode 100644 index 0000000000..ba60fbf9b6 --- /dev/null +++ b/_books/4-hands-on-scala.md @@ -0,0 +1,11 @@ +--- +title: "Hands-on Scala Programming" +link: https://www.handsonscala.com/ +image: /resources/img/books/HandsOnScala.jpg +status: Covers Scala 2.13 +authors: ["Li Haoyi"] +publisher: Li Haoyi +publisherLink: http://www.lihaoyi.com +--- + +"Hands-on Scala teaches you how to use the Scala programming language in a practical, project-based fashion. This book is designed to quickly teach an existing programmer everything needed to go from "hello world" to building production applications like interactive websites, parallel web crawlers, and distributed systems in Scala. In the process you will learn how to use the Scala language to solve challenging problems in an elegant and intuitive manner." diff --git a/_books/5-get-programming.md b/_books/5-get-programming.md new file mode 100644 index 0000000000..5d6803860d --- /dev/null +++ b/_books/5-get-programming.md @@ -0,0 +1,11 @@ +--- +title: "Get Programming with Scala" +link: https://www.manning.com/books/get-programming-with-scala +image: /resources/img/books/get-programming-book.png +status: Covers Scala 2 and 3 +authors: ["Daniela Sfregola"] +publisher: Manning +publisherLink: https://www.manning.com/ +--- + +"The perfect starting point for your journey into Scala and functional programming. Scala is a multi-style programming language for the JVM that supports both object-oriented and functional programming. Master Scala, and you'll be well-equipped to match your programming approach to the type of problem you're dealing with. Packed with examples and exercises, _Get Programming with Scala_ is the perfect starting point for developers with some OO knowledge who want to learn Scala and pick up a few FP skills along the way." diff --git a/_books/5-scala-in-depth.md b/_books/5-scala-in-depth.md deleted file mode 100644 index 6262e3a4ee..0000000000 --- a/_books/5-scala-in-depth.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Scala in Depth" -link: http://www.manning.com/suereth -image: /resources/img/books/icon_Scala_in_Depth_93x116.png -status: Available now -authors: ["Joshua D. Suereth"] -publisher: Manning -publisherLink: http://www.manning.com/ ---- - -"While information about the Scala language is abundant, skilled practitioners, great examples, and insight into the best practices of the community are harder to find. Scala in Depth bridges that gap, preparing you to adopt Scala successfully for real world projects. Scala in Depth is a unique new book designed to help you integrate Scala effectively into your development process. By presenting the emerging best practices and designs from the Scala community, it guides you though dozens of powerful techniques example by example. There's no heavy-handed theory here-just lots of crisp, practical guides for coding in Scala." \ No newline at end of file diff --git a/_books/6-creative-scala.md b/_books/6-creative-scala.md new file mode 100644 index 0000000000..bd2007679a --- /dev/null +++ b/_books/6-creative-scala.md @@ -0,0 +1,11 @@ +--- +title: "Creative Scala" +link: https://www.creativescala.org +image: /resources/img/books/CreativeScala.png +status: Free online book +authors: ["Dave Gurnell", "Noel Welsh"] +publisher: Underscore +publisherLink: https://underscore.io +--- + +"The book for new developers who want to learn Scala and have fun. Creative Scala is aimed at developers who have no prior experience in Scala. It is designed to give you a fun introduction to functional programming. We assume you have some very basic familiarity with another programming language but little or no experience with Scala or other functional languages. We've chosen what we hope is a fun method to explore functional programming and Scala: computer graphics." diff --git a/_books/6-scala-puzzlers.md b/_books/6-scala-puzzlers.md deleted file mode 100644 index 13b54f555e..0000000000 --- a/_books/6-scala-puzzlers.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Scala Puzzlers" -link: http://www.artima.com/shop/scala_puzzlers -image: /resources/img/books/scala-puzzlers-book.jpg -status: Available now -authors: ["Andrew Phillips", "Nermin Šerifović"] -publisher: Artima Press -publisherLink: http://www.artima.com/index.jsp ---- - -"Getting code to do what we want it to do is perhaps the essence of our purpose as developers. So there are few things more intriguing or important than code that we think we understand, but that behaves rather contrary to our expectations. Scala Puzzlers is a collection of such examples in Scala. It is not only an entertaining and instructive way of understanding this highly expressive language better. It will also help you recognize many counter-intuitive traps and pitfalls and prevent them from inflicting further production bug hunt stress on Scala developers." diff --git a/_books/4-functional-programming-in-scala.md b/_books/7-functional-programming-in-scala.md similarity index 67% rename from _books/4-functional-programming-in-scala.md rename to _books/7-functional-programming-in-scala.md index 9a27404679..0b878c6b15 100644 --- a/_books/4-functional-programming-in-scala.md +++ b/_books/7-functional-programming-in-scala.md @@ -1,11 +1,13 @@ --- title: "Functional Programming in Scala" -link: https://www.manning.com/books/functional-programming-in-scala -image: /resources/img/books/FPiS_93x116.png -status: Available now -authors: ["Paul Chiusano", "Rúnar Bjarnason"] +link: https://www.manning.com/books/functional-programming-in-scala-second-edition +image: /resources/img/books/FPiS_93x116.jpg +status: Updated for Scala 3 +authors: ["Michael Pilquist", "Paul Chiusano", "Rúnar Bjarnason"] publisher: Manning -publisherLink: http://www.manning.com/ +publisherLink: https://www.manning.com/ --- -"Functional programming (FP) is a style of software development emphasizing functions that don't depend on program state... Functional Programming in Scala is a serious tutorial for programmers looking to learn FP and apply it to the everyday business of coding. The book guides readers from basic techniques to advanced topics in a logical, concise, and clear progression. In it, you'll find concrete examples and exercises that open up the world of functional programming." \ No newline at end of file +"Functional programming (FP) is a style of software development emphasizing functions that don't depend on program state... Functional Programming in Scala is a serious tutorial for programmers looking to learn FP and apply it to the everyday business of coding. The book guides readers from basic techniques to advanced topics in a logical, concise, and clear progression. In it, you'll find concrete examples and exercises that open up the world of functional programming." + +Forewords by Daniel Spiewak and Martin Odersky. diff --git a/_cheatsheets/index.md b/_cheatsheets/index.md new file mode 100644 index 0000000000..679e4ed242 --- /dev/null +++ b/_cheatsheets/index.md @@ -0,0 +1,622 @@ +--- +layout: cheatsheet +title: Scala Cheatsheet + +partof: cheatsheet + +by: Brendan O'Connor +about: Thanks to Brendan O'Connor, this cheatsheet aims to be a quick reference of Scala syntactic constructions. Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. + +languages: [ba, fr, ja, pl, pt-br, zh-cn, th, ru, uk] +--- + + + +{{ page.about }} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
variables 
var x = 5

Good
x = 6
Variable.
val x = 5

Bad
x = 6
Constant.
var x: Double = 5
Explicit type.
functions
Good
def f(x: Int) = { x * x }

Bad
def f(x: Int)   { x * x }
Define function.
Hidden error: without = it’s a procedure returning Unit; causes havoc. Deprecated in Scala 2.13.
Good
def f(x: Any) = println(x)

Bad
def f(x) = println(x)
Define function.
Syntax error: need types for every arg.
type R = Double
Type alias.
def f(x: R)
vs.
def f(x: => R)
Call-by-value.

Call-by-name (lazy parameters).
(x: R) => x * x
Anonymous function.
(1 to 5).map(_ * 2)
vs.
(1 to 5).reduceLeft(_ + _)
Anonymous function: underscore is positionally matched arg.
(1 to 5).map(x => x * x)
Anonymous function: to use an arg twice, have to name it.
(1 to 5).map { x =>
+  val y = x * 2
+  println(y)
+  y
+}
Anonymous function: block style returns last expression.
(1 to 5) filter {
+  _ % 2 == 0
+} map {
+  _ * 2
+}
Anonymous functions: pipeline style (or parens too).
def compose(g: R => R, h: R => R) =
+  (x: R) => g(h(x))

val f = compose(_ * 2, _ - 1)
Anonymous functions: to pass in multiple blocks, need outer parens.
val zscore =
+  (mean: R, sd: R) =>
+    (x: R) =>
+      (x - mean) / sd
Currying, obvious syntax.
def zscore(mean: R, sd: R) =
+  (x: R) =>
+    (x - mean) / sd
Currying, obvious syntax.
def zscore(mean: R, sd: R)(x: R) =
+  (x - mean) / sd
Currying, sugar syntax. But then:
val normer =
+  zscore(7, 0.4) _
Need trailing underscore to get the partial, only for the sugar version.
def mapmake[T](g: T => T)(seq: List[T]) =
+  seq.map(g)
Generic type.
5.+(3); 5 + 3

(1 to 5) map (_ * 2)
Infix sugar.
def sum(args: Int*) =
+  args.reduceLeft(_+_)
Varargs.
packages 
import scala.collection._
Wildcard import.
import scala.collection.Vector

import scala.collection.{Vector, Sequence}
Selective import.
import scala.collection.{Vector => Vec28}
Renaming import.
import java.util.{Date => _, _}
Import all from java.util except Date.
At start of file: 
package pkg

Packaging by scope: 
package pkg {
+  ...
+}

Package singleton: 
package object pkg {
+  ...
+}
Declare a package.
data structures 
(1, 2, 3)
Tuple literal (Tuple3).
var (x, y, z) = (1, 2, 3)
Destructuring bind: tuple unpacking via pattern matching.
Bad
var x, y, z = (1, 2, 3)
Hidden error: each assigned to the entire tuple.
var xs = List(1, 2, 3)
List (immutable).
xs(2)
Paren indexing (slides).
1 :: List(2, 3)
Cons.
1 to 5
same as 
1 until 6

1 to 10 by 2
Range sugar.
()
Empty parens is singleton value of the Unit type.
Equivalent to void in C and Java.
control constructs 
if (check) happy else sad
Conditional.
if (check) happy
+
same as
+ 
if (check) happy else ()
Conditional sugar.
while (x < 5) {
+  println(x)
+  x += 1
+}
While loop.
do {
+  println(x)
+  x += 1
+} while (x < 5)
Do-while loop.
import scala.util.control.Breaks._
+breakable {
+  for (x <- xs) {
+    if (Math.random < 0.1)
+      break
+  }
+}
Break (slides).
for (x <- xs if x % 2 == 0)
+  yield x * 10
+
same as
+ 
xs.filter(_ % 2 == 0).map(_ * 10)
For-comprehension: filter/map.
for ((x, y) <- xs zip ys)
+  yield x * y
+
same as
+ 
(xs zip ys) map {
+  case (x, y) => x * y
+}
For-comprehension: destructuring bind.
for (x <- xs; y <- ys)
+  yield x * y
+
same as
+ 
xs flatMap { x =>
+  ys map { y =>
+    x * y
+  }
+}
For-comprehension: cross product.
for (x <- xs; y <- ys) {
+  val div = x / y.toFloat
+  println("%d/%d = %.1f".format(x, y, div))
+}
For-comprehension: imperative-ish.
sprintf style.
for (i <- 1 to 5) {
+  println(i)
+}
For-comprehension: iterate including the upper bound.
for (i <- 1 until 5) {
+  println(i)
+}
For-comprehension: iterate omitting the upper bound.
pattern matching
Good
(xs zip ys) map {
+  case (x, y) => x * y
+}

Bad
(xs zip ys) map {
+  (x, y) => x * y
+}
Use case in function args for pattern matching.
Bad
+ 
val v42 = 42
+3 match {
+  case v42 => println("42")
+  case _   => println("Not 42")
+}
v42 is interpreted as a name matching any Int value, and “42” is printed.
Good
+ 
val v42 = 42
+3 match {
+  case `v42` => println("42")
+  case _     => println("Not 42")
+}
`v42` with backticks is interpreted as the existing val v42, and “Not 42” is printed.
Good
+ 
val UppercaseVal = 42
+3 match {
+  case UppercaseVal => println("42")
+  case _            => println("Not 42")
+}
UppercaseVal is treated as an existing val, rather than a new pattern variable, because it starts with an uppercase letter. Thus, the value contained within UppercaseVal is checked against 3, and “Not 42” is printed.
object orientation 
class C(x: R)
Constructor params - x is only available in class body.
class C(val x: R)

var c = new C(4)

c.x
Constructor params - automatic public member defined.
class C(var x: R) {
+  assert(x > 0, "positive please")
+  var y = x
+  val readonly = 5
+  private var secret = 1
+  def this() = this(42)
+}
Constructor is class body.
Declare a public member.
Declare a gettable but not settable member.
Declare a private member.
Alternative constructor.
new {
+  ...
+}
Anonymous class.
abstract class D { ... }
Define an abstract class (non-createable).
class C extends D { ... }
Define an inherited class.
class D(var x: R)

class C(x: R) extends D(x)
Inheritance and constructor params (wishlist: automatically pass-up params by default).
object O extends D { ... }
Define a singleton (module-like).
trait T { ... }

class C extends T { ... }

class C extends D with T { ... }
Traits.
Interfaces-with-implementation. No constructor params. mixin-able.
trait T1; trait T2

class C extends T1 with T2

class C extends D with T1 with T2
Multiple traits.
class C extends D { override def f = ...}
Must declare method overrides.
new java.io.File("f")
Create object.
Bad
new List[Int]

Good
List(1, 2, 3)
Type error: abstract type.
Instead, convention: callable factory shadowing the type.
classOf[String]
Class literal.
x.isInstanceOf[String]
Type check (runtime).
x.asInstanceOf[String]
Type cast (runtime).
x: String
Ascription (compile time).
options 
Some(42)
Construct a non empty optional value.
None
The singleton empty optional value.
Option(null) == None
+Option(obj.unsafeMethod)
+ but + 
Some(null) != None
Null-safe optional value factory.
val optStr: Option[String] = None
+ same as + 
val optStr = Option.empty[String]
Explicit type for empty optional value.
Factory for empty optional value.
val name: Option[String] =
+  request.getParameter("name")
+val upper = name.map {
+  _.trim
+} filter {
+  _.length != 0
+} map {
+  _.toUpperCase
+}
+println(upper.getOrElse(""))
Pipeline style.
val upper = for {
+  name <- request.getParameter("name")
+  trimmed <- Some(name.trim)
+    if trimmed.length != 0
+  upper <- Some(trimmed.toUpperCase)
+} yield upper
+println(upper.getOrElse(""))
For-comprehension syntax.
option.map(f(_))
+ same as + 
option match {
+  case Some(x) => Some(f(x))
+  case None    => None
+}
Apply a function on the optional value.
option.flatMap(f(_))
+ same as + 
option match {
+  case Some(x) => f(x)
+  case None    => None
+}
Same as map but function must return an optional value.
optionOfOption.flatten
+ same as + 
optionOfOption match {
+  case Some(Some(x)) => Some(x)
+  case _             => None
+}
Extract nested option.
option.foreach(f(_))
+ same as + 
option match {
+  case Some(x) => f(x)
+  case None    => ()
+}
Apply a procedure on optional value.
option.fold(y)(f(_))
+ same as + 
option match {
+  case Some(x) => f(x)
+  case None    => y
+}
Apply function on optional value, return default if empty.
option.collect {
+  case x => ...
+}
+ same as + 
option match {
+  case Some(x) if f.isDefinedAt(x) => ...
+  case Some(_)                     => None
+  case None                        => None
+}
Apply partial pattern match on optional value.
option.isDefined
+ same as + 
option match {
+  case Some(_) => true
+  case None    => false
+}
true if not empty.
option.isEmpty
+ same as + 
option match {
+  case Some(_) => false
+  case None    => true
+}
true if empty.
option.nonEmpty
+ same as + 
option match {
+  case Some(_) => true
+  case None    => false
+}
true if not empty.
option.size
+ same as + 
option match {
+  case Some(_) => 1
+  case None    => 0
+}
0 if empty, otherwise 1.
option.orElse(Some(y))
+ same as + 
option match {
+  case Some(x) => Some(x)
+  case None    => Some(y)
+}
Evaluate and return alternate optional value if empty.
option.getOrElse(y)
+ same as + 
option match {
+  case Some(x) => x
+  case None    => y
+}
Evaluate and return default value if empty.
option.get
+ same as + 
option match {
+  case Some(x) => x
+  case None    => throw new Exception
+}
Return value, throw exception if empty.
option.orNull
+ same as + 
option match {
+  case Some(x) => x
+  case None    => null
+}
Return value, null if empty.
option.filter(f)
+ same as + 
option match {
+  case Some(x) if f(x) => Some(x)
+  case _               => None
+}
Optional value satisfies predicate.
option.filterNot(f(_))
+ same as + 
option match {
+  case Some(x) if !f(x) => Some(x)
+  case _                => None
+}
Optional value doesn't satisfy predicate.
option.exists(f(_))
+ same as + 
option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => false
+}
Apply predicate on optional value or false if empty.
option.forall(f(_))
+ same as + 
option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => true
+}
Apply predicate on optional value or true if empty.
option.contains(y)
+ same as + 
option match {
+  case Some(x) => x == y
+  case None    => false
+}
Checks if value equals optional value or false if empty.
diff --git a/_config.yml b/_config.yml index b10d6d2d5d..e1ed8d682e 100644 --- a/_config.yml +++ b/_config.yml @@ -15,7 +15,9 @@ keywords: - Document - Guide -scala-version: 2.12.2 +scala-version: 2.13.16 +scala-212-version: 2.12.20 +scala-3-version: 3.7.1 collections: style: @@ -28,9 +30,15 @@ collections: tutorials: output: true permalink: /:collection/:path.html + glossary: + output: true + permalink: /:collection/:path.html sips: output: true permalink: /:collection/:path.html + cheatsheets: + output: true + permalink: /:collection/:path.html books: output: false ja: # Japanese translations @@ -72,6 +80,9 @@ collections: th: # Thai translations output: true permalink: /:collection/:path.html + uk: # Ukrainian translations + output: true + permalink: /:collection/:path.html defaults: - @@ -80,11 +91,126 @@ defaults: type: "tour" values: overview-name: "Tour of Scala" + - + scope: + path: "_overviews/getting-started" + values: + permalink: "/:path.html" + - + scope: + path: "_overviews/macros" + values: + scala2: true + versionSpecific: true + - + scope: + path: "_overviews/reflection" + values: + scala2: true + versionSpecific: true + - + scope: + path: "_overviews/quasiquotes" + values: + scala2: true + versionSpecific: true + - + scope: + path: "_overviews/repl" + values: + scala2: true + versionSpecific: true + - + scope: + path: "_overviews/plugins" + values: + scala2: true + versionSpecific: true + - + scope: + path: "_overviews/compiler-options" + values: + scala2: true + versionSpecific: true + - + scope: + path: "_overviews/scala3-book" + values: + scala3: true + # num: 99 # to list them in the TOC, should be overwritten individually + partof: scala3-book + type: section + overview-name: "Scala 3 — Book" + layout: multipage-overview + permalink: "/scala3/book/:title.html" + - + scope: + path: "_overviews/contribute" + values: + partof: scala-contribution + overview-name: Contributing to Scala's OSS Ecosystem + layout: multipage-overview + permalink: "/contribute/:title.html" + - + scope: + path: "_overviews/scala3-migration" + values: + scala3: true + # num: 99 # to list them in the TOC, should be overwritten individually + partof: scala3-migration + type: section + overview-name: "Scala 3 Migration Guide" + layout: multipage-overview + permalink: "/scala3/guides/migration/:title.html" + - + scope: + path: "_overviews/scala3-contribution" + values: + scala3: true + partof: scala3-contribution + type: section + overview-name: "Guide to Scala 3 Compiler Contribution" + layout: multipage-overview + permalink: "/scala3/guides/contribution/:title.html" + - + scope: + path: "_overviews/scala3-macros" + values: + scala3: true + versionSpecific: true + partof: scala3-macros + overview-name: "Macros in Scala 3" + layout: multipage-overview + permalink: "/scala3/guides/macros/:title.html" + - + scope: + path: "_overviews/scala3-scaladoc" + values: + scala3: true + versionSpecific: true + partof: scala3-scaladoc + overview-name: "Scaladoc" + layout: multipage-overview + permalink: "/scala3/guides/scaladoc/:title.html" + - + scope: + path: "_overviews/toolkit" + values: + partof: toolkit + overview-name: "The Scala Toolkit" + layout: multipage-overview + permalink: "/toolkit/:title.html" + - + scope: + path: "scala3" + values: + scala3: true + highlighter: rouge permalink: /:categories/:title.html:output_ext baseurl: -exclude: ["vendor"] +scala3ref: "https://docs.scala-lang.org/scala3/reference" +exclude: ["vendor", ".metals"] plugins: - jekyll-redirect-from - - jekyll-scalafiddle diff --git a/_data/compiler-options.yml b/_data/compiler-options.yml index c50ae356b8..f4cced5028 100644 --- a/_data/compiler-options.yml +++ b/_data/compiler-options.yml @@ -1,113 +1,107 @@ - category: "Standard Settings" description: "A set of standard options that are supported on the current development environment and will be supported in future releases." options: - - option: "-classpath" + - option: "-Dproperty=value" schema: - type: "Path" - arg: "path" - default: "." - description: "Specify where to find user class files." - abbreviations: - - "-cp" - - option: "-d" + type: "Prefix" + description: "Pass -Dproperty=value directly to the runtime system." + - option: "-J" + schema: + type: "Prefix" + description: "Pass flag directly to the runtime system." + - option: "-P" schema: type: "String" - arg: "directory|jar" - default: "." - description: "destination for generated classfiles." - - option: "-no-specialization" + arg: "plugin:opt" + multiple: "true" + description: "Pass an option to a plugin" + - option: "-V" schema: type: "Boolean" - description: "Ignore @specialize annotations." - - option: "-language" - schema: - type: "Choice" - arg: "feature" - multiple: true - choices: - - choice: "dynamics" - description: "Allow direct or indirect subclasses of scala.Dynamic" - - choice: "postfixOps" - description: "Allow postfix operator notation, such as `1 to 10 toList`" - - choice: "reflectiveCalls" - description: "Allow reflective access to members of structural types" - - choice: "implicitConversions" - description: "Allow definition of implicit functions called views" - - choice: "higherKinds" - description: "Allow higher-kinded types" - - choice: "existentials" - description: "Existential types (besides wildcard types) can be written and inferred" - - choice: "experimental.macros" - description: "Allow macro definition (besides implementation and application)" - description: "Enable or disable language features: `_` for all, `-language:help` to list choices." - - option: "-release" + description: "Print a synopsis of verbose options." + - option: "-W" schema: - type: "String" - arg: "release" - description: "Compile for a specific version of the Java platform. Supported targets: 6, 7, 8, 9" - - option: "-optimise" + type: "Boolean" + description: "Print a synopsis of warning options." + - option: "-Werror" schema: type: "Boolean" - description: "Compiler flag for the optimizer in Scala 2.11" + description: "Fail the compilation if there are any warnings." abbreviations: - - "-optimize" - - option: "value-overrides" + - "-Xfatal-warnings" + - option: "-X" + schema: + type: "Boolean" + description: "Print a synopsis of advanced options." + - option: "-Y" schema: type: "Boolean" - description: "Generated value class method overrides an implementation." + description: "Print a synopsis of private options." - option: "-bootclasspath" schema: type: "Path" arg: "path" - default: "Defaults.scalaBootClassPath" + default: description: "Override location of bootstrap class files." - - option: "-extdirs" - schema: - type: "Path" - arg: "path" - default: "Defaults.scalaExtDirs" - description: "Override location of installed extensions." - - option: "-javabootclasspath" - schema: - type: "Path" - arg: "path" - default: "Defaults.javaBootClassPath" - description: "Override java boot classpath." - - option: "-javaextdirs" + abbreviations: + - "--boot-class-path" + - option: "-classpath" schema: type: "Path" arg: "path" - default: "Defaults.javaExtDirs" - description: "Override java extdirs classpath." - - option: "-sourcepath" + default: "." + description: "Specify where to find user class files." + abbreviations: + - "-cp" + - "--class-path" + - option: "-d" schema: - type: "Path" - arg: "path" - description: "Specify location(s) of source files." + type: "String" + arg: "directory|jar" + default: "." + description: "destination for generated classfiles." - option: "-dependencyfile" schema: type: "String" arg: "file" default: ".scala_dependencies" description: "Set dependency tracking file." + abbreviations: + - "--dependency-file" - option: "-deprecation" schema: type: "Boolean" description: "Emit warning and location for usages of deprecated APIs." + abbreviations: + - "--deprecation" - option: "-encoding" schema: type: "String" arg: "encoding" - default: "Properties.sourceEncoding" + default: "UTF-8" description: "Specify character encoding used by source files." + abbreviations: + - "--encoding" - option: "-explaintypes" schema: type: "Boolean" description: "Explain type errors in more detail." + abbreviations: + - "--explain-types" + - option: "-extdirs" + schema: + type: "Path" + arg: "path" + default: + description: "Override location of installed extensions." + abbreviations: + - "--extension-directories" - option: "-feature" schema: type: "Boolean" description: "Emit warning and location for usages of features that should be imported explicitly." + abbreviations: + - "--feature" - option: "-g" schema: type: "Choice" @@ -119,86 +113,229 @@ - choice: "line" - choice: "vars" - choice: "notailcalls" - description: "Set level of generated debugging info. Choices: (none,source,line,vars,notailcalls), default: vars." + description: "Set level of generated debugging info. (none,source,line,[vars],notailcalls)" - option: "-help" schema: type: "Boolean" description: "Print a synopsis of standard options" + abbreviations: + - "--help" + - option: "-javabootclasspath" + schema: + type: "Path" + arg: "path" + default: "" + description: "Override java boot classpath." + abbreviations: + - "--java-boot-class-path" + - option: "-javaextdirs" + schema: + type: "Path" + arg: "path" + default: + description: "Override java extdirs classpath." + abbreviations: + - "--java-extension-directories" + - option: "-language" + schema: + type: "Choice" + arg: "feature" + multiple: "true" + choices: + - choice: "dynamics" + description: "Allow direct or indirect subclasses of scala.Dynamic" + - choice: "existentials" + description: "Existential types (besides wildcard types) can be written and inferred" + - choice: "higherKinds" + description: "Allow higher-kinded types" + - choice: "implicitConversions" + description: "Allow definition of implicit functions called views" + - choice: "postfixOps" + description: "Allow postfix operator notation, such as `1 to 10 toList` (not recommended)" + - choice: "reflectiveCalls" + description: "Allow reflective access to members of structural types" + - choice: "experimental.macros" + description: "Allow macro definition (besides implementation and application)" + description: "Enable or disable language features" + abbreviations: + - "--language" + - option: "-no-specialization" + schema: + type: "Boolean" + description: "Ignore @specialize annotations." + abbreviations: + - "--no-specialization" + - option: "-nobootcp" + schema: + type: "Boolean" + description: "Do not use the boot classpath for the scala jars." + abbreviations: + - "--no-boot-class-path" - option: "-nowarn" schema: type: "Boolean" description: "Generate no warnings." + abbreviations: + - "--no-warnings" + - option: "-opt" + schema: + type: "Choice" + arg: "optimization" + multiple: "true" + choices: + - choice: "unreachable-code" + description: "Eliminate unreachable code, exception handlers guarding no instructions, redundant metadata (debug information, line numbers)." + - choice: "simplify-jumps" + description: "Simplify branching instructions, eliminate unnecessary ones." + - choice: "compact-locals" + description: "Eliminate empty slots in the sequence of local variables." + - choice: "copy-propagation" + description: "Eliminate redundant local variables and unused values (including closures). Enables unreachable-code." + - choice: "redundant-casts" + description: "Eliminate redundant casts using a type propagation analysis." + - choice: "box-unbox" + description: "Eliminate box-unbox pairs within the same method (also tuples, xRefs, value class instances). Enables unreachable-code." + - choice: "nullness-tracking" + description: "Track nullness / non-nullness of local variables and apply optimizations." + - choice: "closure-invocations" + description: "Rewrite closure invocations to the implementation method." + - choice: "allow-skip-core-module-init" + description: "Allow eliminating unused module loads for core modules of the standard library (e.g., Predef, ClassTag)." + - choice: "assume-modules-non-null" + description: "Assume loading a module never results in null (happens if the module is accessed in its super constructor)." + - choice: "allow-skip-class-loading" + description: "Allow optimizations that can skip or delay class loading." + - choice: "inline" + description: "Inline method invocations according to -Yopt-inline-heuristics and -opt-inline-from." + - choice: "l:none" + description: "Disable optimizations. Takes precedence: `-opt:l:none,+box-unbox` / `-opt:l:none -opt:box-unbox` don`t enable box-unbox." + - choice: "l:default" + description: "Enable default optimizations: unreachable-code." + - choice: "l:method" + description: "Enable intra-method optimizations: unreachable-code,simplify-jumps,compact-locals,copy-propagation,redundant-casts,box-unbox,nullness-tracking,closure-invocations,allow-skip-core-module-init,assume-modules-non-null,allow-skip-class-loading." + - choice: "l:inline" + description: "Enable cross-method optimizations (note: inlining requires -opt-inline-from): l:method,inline." + description: "Enable optimizations" + - option: "-opt-inline-from" + schema: + type: "String" + arg: "patterns" + multiple: "true" + description: "Patterns for classfile names from which to allow inlining, `help` for details." + - option: "-opt-warnings" + schema: + type: "Choice" + arg: "warning" + multiple: "true" + choices: + - choice: "none" + description: "No optimizer warnings." + - choice: "at-inline-failed-summary" + description: "One-line summary if there were @inline method calls that could not be inlined." + - choice: "at-inline-failed" + description: "A detailed warning for each @inline method call that could not be inlined." + - choice: "any-inline-failed" + description: "A detailed warning for every callsite that was chosen for inlining by the heuristics, but could not be inlined." + - choice: "no-inline-mixed" + description: "In mixed compilation, warn at callsites methods defined in java sources (the inlining decision cannot be made without bytecode)." + - choice: "no-inline-missing-bytecode" + description: "Warn if an inlining decision cannot be made because a the bytecode of a class or member cannot be found on the compilation classpath." + - choice: "no-inline-missing-attribute" + description: "Warn if an inlining decision cannot be made because a Scala classfile does not have a ScalaInlineInfo attribute." + description: "Enable optimizer warnings" + - option: "-optimize" + schema: + type: "Boolean" + description: "Enables optimizations." + abbreviations: + - "-optimise" - option: "-print" schema: type: "Boolean" description: "Print program with Scala-specific features removed." + abbreviations: + - "--print" + - option: "-release" + schema: + type: "String" + arg: "release" + default: + description: "Compile for a specific version of the Java platform. Supported targets: 8, 11, or any higher version listed at https://docs.scala-lang.org/overviews/jdk-compatibility/overview.html" + abbreviations: + - "--release" + - option: "-sourcepath" + schema: + type: "Path" + arg: "path" + default: + description: "Specify location(s) of source files." + abbreviations: + - "--source-path" - option: "-target" schema: type: "Choice" arg: "target" - default: "jvm-1.8" + default: "8" choices: - - choice: "jvm-1.5" - - choice: "jvm-1.6" - - choice: "jvm-1.7" - - choice: "jvm-1.8" - description: "Target platform for object files. All JVM 1.5 - 1.7 targets are deprecated. Choices: (jvm-1.5,jvm-1.6,jvm-1.7,jvm-1.8), default: jvm-1.8." + - choice: "8" + - choice: "9" + - choice: "10" + - choice: "11" + - choice: "12" + description: "Target platform for object files. ([8],9,10,11,12)" + abbreviations: + - "--target" + - option: "-toolcp" + schema: + type: "Path" + arg: "path" + default: + description: "Add to the runner classpath." + abbreviations: + - "--tool-class-path" - option: "-unchecked" schema: type: "Boolean" description: "Enable additional warnings where generated code depends on assumptions." + abbreviations: + - "--unchecked" - option: "-uniqid" schema: type: "Boolean" description: "Uniquely tag all identifiers in debugging output." + abbreviations: + - "--unique-id" - option: "-usejavacp" schema: type: "Boolean" description: "Utilize the java.class.path in classpath resolution." + abbreviations: + - "--use-java-class-path" - option: "-usemanifestcp" schema: type: "Boolean" description: "Utilize the manifest in classpath resolution." + abbreviations: + - "--use-manifest-class-path" - option: "-verbose" schema: type: "Boolean" description: "Output messages about what the compiler is doing." + abbreviations: + - "--verbose" - option: "-version" schema: type: "Boolean" description: "Print product version and exit." -- category: "JVM Settings" - description: "Settings influencing the runtime system." - options: - - option: "-Jflag" - schema: - type: "Prefix" - description: "Pass flag directly to the runtime system." - - option: "-Dproperty=value" - schema: - type: "Prefix" - description: "Pass -Dproperty=value directly to the runtime system." - - option: "-nobootcp" + abbreviations: + - "--version" + - option: "@" schema: type: "Boolean" - description: "Do not use the boot classpath for the scala jars." -- category: "Plugin Settings" - description: "" - options: - - option: "-P" - schema: - type: "String" - arg: "plugin:opt" - multiple: true - description: "Pass an option to a plugin" - note: "If you use sbt, [compiler plugins support](https://www.scala-sbt.org/1.x/docs/Compiler-Plugins.html) may be useful." + description: "A text file containing compiler arguments (options and source files)" - category: "Advanced Settings" - description: "Options that starts with `-X` are maybe renamed or removed in future releases." + description: options: - - option: "-X" - schema: - type: "Boolean" - description: "Print a synopsis of advanced options." - option: "-Xcheckinit" schema: type: "Boolean" @@ -214,53 +351,94 @@ - option: "-Xelide-below" schema: type: "Int" - default: "Int.MinValue" + default: "-2147483648" description: "Calls to @elidable methods are omitted if method priority is lower than argument" - - option: "-Xno-forwarders" + - option: "-Xexperimental" schema: type: "Boolean" - description: "Do not generate static forwarders in mirror classes." + description: "Former graveyard for language-forking extensions." + - option: "-Xfuture" + schema: + type: "Boolean" + description: "Replaced by -Xsource." - option: "-Xgenerate-phase-graph" schema: type: "String" arg: "file" + default: description: "Generate the phase graphs (outputs .dot files) to fileX.dot." - - option: "-Xlog-implicits" - schema: - type: "Boolean" - description: "Show more detail on why some implicits are not applicable." - - option: "-Xlog-implicit-conversions" - schema: - type: "Boolean" - description: "Print a message whenever an implicit conversion is inserted." - - option: "-Xlog-reflective-calls" - schema: - type: "Boolean" - description: "Print a message when a reflective method call is generated" - - option: "-Xlog-free-terms" + - option: "-Xlint" schema: - type: "Boolean" - description: "Print a message when reification creates a free term." - - option: "-Xlog-free-types" + type: "Choice" + arg: "warning" + multiple: "true" + choices: + - choice: "adapted-args" + description: "Warn if an argument list is modified to match the receiver." + - choice: "nullary-unit" + description: "Warn when nullary methods return Unit." + - choice: "inaccessible" + description: "Warn about inaccessible types in method signatures." + - choice: "infer-any" + description: "Warn when a type argument is inferred to be `Any`." + - choice: "missing-interpolator" + description: "A string literal appears to be missing an interpolator id." + - choice: "doc-detached" + description: "A Scaladoc comment appears to be detached from its element." + - choice: "private-shadow" + description: "A private field (or class parameter) shadows a superclass field." + - choice: "type-parameter-shadow" + description: "A local type parameter shadows a type already in scope." + - choice: "poly-implicit-overload" + description: "Parameterized overloaded implicit methods are not visible as view bounds." + - choice: "option-implicit" + description: "Option.apply used implicit view." + - choice: "delayedinit-select" + description: "Selecting member of DelayedInit." + - choice: "package-object-classes" + description: "Class or object defined in package object." + - choice: "stars-align" + description: "Pattern sequence wildcard must align with sequence component." + - choice: "constant" + description: "Evaluation of a constant arithmetic expression results in an error." + - choice: "unused" + description: "Enable -Wunused:imports,privates,locals,implicits." + - choice: "nonlocal-return" + description: "A return statement used an exception for flow control." + - choice: "implicit-not-found" + description: "Check @implicitNotFound and @implicitAmbiguous messages." + - choice: "serial" + description: "@SerialVersionUID on traits and non-serializable classes." + - choice: "valpattern" + description: "Enable pattern checks in val definitions." + - choice: "eta-zero" + description: "Warn on eta-expansion (rather than auto-application) of zero-ary method." + - choice: "eta-sam" + description: "Warn on eta-expansion to meet a Java-defined functional interface that is not explicitly annotated with @FunctionalInterface." + - choice: "deprecation" + description: "Enable linted deprecations." + description: "Enable recommended warnings" + - option: "-Xmacro-settings" schema: - type: "Boolean" - description: "Print a message when reification resorts to generating a free type." - - option: "-Xmax-classfile-name" + type: "String" + arg: "option" + multiple: "true" + description: "Custom settings for macros." + - option: "-Xmain-class" schema: - type: "Int" - default: 255 - min: 72 - max: 255 - description: "Maximum filename length for generated classes" + type: "String" + arg: "path" + default: + description: "Class for manifest's Main-Class entry (only useful with -d jar)" - option: "-Xmaxerrs" schema: type: "Int" - default: 100 + default: "100" description: "Maximum errors to print" - option: "-Xmaxwarns" schema: type: "Int" - default: 100 + default: "100" description: "Maximum warnings to print" - option: "-Xmigration" schema: @@ -268,29 +446,42 @@ arg: "version" default: "none" description: "Warn about constructs whose behavior may have changed since version." - - option: "-Xno-uescape" + - option: "-Xmixin-force-forwarders" + schema: + type: "Choice" + arg: "mode" + default: "true" + choices: + - choice: "true" + description: "Always generate mixin forwarders." + - choice: "junit" + description: "Generate mixin forwarders for JUnit-annotated methods (JUnit 4 does not support default methods)." + - choice: "false" + description: "Only generate mixin forwarders required for program correctness." + description: "Generate forwarder methods in classes inhering concrete methods from traits. Default: `true`, `help` to list choices." + - option: "-Xno-forwarders" schema: type: "Boolean" - description: "Disable handling of \\u unicode escapes." - - option: "-Xnojline" + description: "Do not generate static forwarders in mirror classes." + - option: "-Xno-patmat-analysis" schema: type: "Boolean" - description: "Do not use JLine for editing." - - option: "-Xverify" + description: "Don't perform exhaustivity/unreachability analysis. Also, ignore @switch annotation." + - option: "-Xnojline" schema: type: "Boolean" - description: "Verify generic signatures in generated bytecode." + description: "Do not use JLine for editing." - option: "-Xplugin" schema: type: "String" arg: "paths" - multiple: true + multiple: "true" description: "Load a plugin from each classpath." - option: "-Xplugin-disable" schema: type: "String" arg: "plugin" - multiple: true + multiple: "true" description: "Disable plugins by name." - option: "-Xplugin-list" schema: @@ -300,35 +491,24 @@ schema: type: "String" arg: "plugin" - multiple: true + multiple: "true" description: "Abort if a named plugin is not loaded." - option: "-Xpluginsdir" schema: type: "String" arg: "path" - default: "Defaults.scalaPluginPath" + default: "" description: "Path to search for plugin archives." - - option: "-Xprint" - schema: - type: "Phases" - description: "Print out program after phases" - note: "See [Compilation Phases](#compilation-phases)" - - option: "-Xprint-pos" - schema: - type: "Boolean" - description: "Print tree positions, as offsets." - - option: "-Xprint-types" - schema: - type: "Boolean" - description: "Print tree types (debugging option)." - - option: "-Xprint-args" - schema: - type: "Boolean" - description: "Print all compiler arguments and exit." - option: "-Xprompt" schema: type: "Boolean" description: "Display a prompt after each error (debugging option)." + - option: "-Xreporter" + schema: + type: "String" + arg: "classname" + default: "scala.tools.nsc.reporters.ConsoleReporter" + description: "Specify a custom reporter for compiler messages." - option: "-Xresident" schema: type: "Boolean" @@ -337,286 +517,298 @@ schema: type: "String" arg: "object" + default: description: "Treat the source file as a script and wrap it in a main method." - - option: "-Xmain-class" - schema: - type: "String" - arg: "path" - description: "Class for manifest's Main-Class entry (only useful with -d jar)" - - option: "-Xshow-class" - schema: - type: "String" - arg: "class" - description: "Show internal representation of class." - - option: "-Xshow-object" - schema: - type: "String" - arg: "object" - description: "Show internal representation of object." - - option: "-Xshow-phases" + - option: "-Xsource" schema: - type: "Boolean" - description: "Print a synopsis of compiler phases." + type: "ScalaVersion" + arg: "version" + default: "2.13.0" + description: "Treat compiler input as Scala source for the specified version, see scala/bug#8126." - option: "-Xsource-reader" schema: type: "String" arg: "classname" + default: description: "Specify a custom method for reading source files." - - option: "-Xreporter" - schema: - type: "String" - arg: "classname" - default: "scala.tools.nsc.reporters.ConsoleReporter" - description: "Specify a custom reporter for compiler messages." - - option: "-Xstrict-inference" - schema: - type: "Boolean" - description: "Don't infer known-unsound types" - - option: "-Xsource" - schema: - type: "ScalaVersion" - arg: "version" - default: "2.12.0" - description: "Treat compiler input as Scala source for the specified version, see [scala/bug#8126](https://github.com/scala/bug/issues/8126)." - - option: "-Xno-patmat-analysis" - schema: - type: "Boolean" - description: "Don't perform exhaustivity/unreachability analysis. Also, ignore @switch annotation." - - option: "-Xfull-lubs" + - option: "-Xverify" schema: type: "Boolean" - description: "Retains pre 2.10 behavior of less aggressive truncation of least upper bounds." - - option: "-Xmixin-force-forwarders" - schema: - type: "Choice" - arg: "mode" - default: "true" - choices: - - choice: "true" - description: "Always generate mixin forwarders." - - choice: "junit" - description: "Generate mixin forwarders for JUnit-annotated methods (JUnit 4 does not support default methods)." - - choice: "false" - description: "Only generate mixin forwarders required for program correctness." - description: "Generate forwarder methods in classes inhering concrete methods from traits. Default: `true`, `help` to list choices." + description: "Verify generic signatures in generated bytecode." - option: "-Xxml" schema: type: "Choice" arg: "property" - multiple: true + multiple: "true" choices: - choice: "coalescing" description: "Convert PCData to Text and coalesce sibling nodes" - description: "Configure XML parsing.: `_` for all, `-Xxml:help` to list choices." - - option: "-Xfuture" + description: "Configure XML parsing." +- category: "Verbose Settings" + description: + options: + - option: "-Vbrowse" schema: - type: "Boolean" - description: "Turn on future language features." - - option: "-Xexperimental" + type: "Phases" + default: + description: "Browse the abstract syntax tree after phases" + abbreviations: + - "-Ybrowse" + - option: "-Vclasspath" schema: type: "Boolean" - description: "Enable experimental extensions." - deprecated: "For in Scala 2.12 and earlier. In 2.13 all options previously enabled by `-Xexperimental` are enabled by default or removed." - - option: "-Xmacro-settings" - schema: - type: "String" - arg: "option" - multiple: true - description: "Custom settings for macros." -- category: "Private Settings" - description: | - Options with `-Y` prefix are more experimental and unstable than those with `-X` prefix. - - Some without `-Y` prefix (e.g. `-opt:**` and `-opt-inline-from`) are also included, since such granular optimization-related options are changeable. - - Those influencing to language semantics are likely to be deprecated in Scala 2.13 (see [scala/scala-dev#430](https://github.com/scala/scala-dev/issues/430)). - options: - - option: "-Y" + description: "Output information about what classpath is being applied." + abbreviations: + - "-Ylog-classpath" + - option: "-Vdebug" schema: type: "Boolean" - description: "Print a synopsis of private options." - - option: "-Yoverride-objects" + description: "Increase the quantity of debugging output." + abbreviations: + - "-Ydebug" + - option: "-Vdoc" schema: type: "Boolean" - description: "Allow member objects to be overridden." - - option: "-Yoverride-vars" + description: "Trace scaladoc activity." + abbreviations: + - "-Ydoc-debug" + - option: "-Vfree-terms" schema: type: "Boolean" - description: "Allow vars to be overridden." - - option: "-Ybreak-cycles" + description: "Print a message when reification creates a free term." + abbreviations: + - "-Xlog-free-terms" + - option: "-Vfree-types" schema: type: "Boolean" - description: "Attempt to break cycles encountered during typing" - - option: "-Ybrowse" + description: "Print a message when reification resorts to generating a free type." + abbreviations: + - "-Xlog-free-types" + - option: "-Vhot-statistics" schema: - type: "Phases" - description: "Browse the abstract syntax tree after phases" - note: "See [Compilation Phases](#compilation-phases)" - - option: "-Ycheck" + type: "Boolean" + description: "Enable `-Vstatistics` to also print hot statistics." + abbreviations: + - "-Yhot-statistics" + - option: "-Vide" schema: - type: "Phases" - description: "Check the tree at the end of phases" - note: "See [Compilation Phases](#compilation-phases)" - - option: "-Yshow" + type: "Boolean" + description: "Generate, validate and output trees using the interactive compiler." + abbreviations: + - "-Yide-debug" + - option: "-Vimplicit-conversions" schema: - type: "Phases" - description: "(Requires -Xshow-class or -Xshow-object) Show after phases" - note: "See [Compilation Phases](#compilation-phases)" - - option: "-Ycompact-trees" + type: "Boolean" + description: "Print a message whenever an implicit conversion is inserted." + abbreviations: + - "-Xlog-implicit-conversions" + - option: "-Vimplicits" schema: type: "Boolean" - description: "Use compact tree printer when displaying trees." - - option: "-Yno-completion" + description: "Print dependent missing implicits." + abbreviations: + - "-Xlog-implicits" + - option: "-Vimplicits-verbose-tree" schema: type: "Boolean" - description: "Disable tab-completion in the REPL." - - option: "-Ydebug" + description: "Display all intermediate implicits in a chain." + - option: "-Vimplicits-max-refined" + schema: + type: "Int" + default: "0" + description: "max chars for printing refined types, abbreviate to `F {...}`" + - option: "-Vtype-diffs" schema: type: "Boolean" - description: "Increase the quantity of debugging output." - - option: "-Yresolve-term-conflict" + description: "Print found/required error messages as colored diffs." + - option: "-Vinline" schema: - type: "Choice" - arg: "strategy" - default: "error" - choices: - - choice: "package" - - choice: "object" - - choice: "error" - description: "Resolve term conflicts. Choices: (package,object,error), default: error." - - option: "-Ylog" + type: "String" + arg: "package/Class.method" + default: + description: "Print a summary of inliner activity; `_` to print all, prefix match to select." + abbreviations: + - "-Yopt-log-inline" + - option: "-Vissue" + schema: + type: "Boolean" + description: "Print stack traces when a context issues an error." + abbreviations: + - "-Yissue-debug" + - option: "-Vlog" schema: type: "Phases" + default: description: "Log operations during phases" - - option: "-Ylog-classpath" + abbreviations: + - "-Ylog" + - option: "-Vmacro" schema: type: "Boolean" - description: "Output information about what classpath is being applied." - - option: "-Yno-generic-signatures" + description: "Trace macro activities: compilation, generation of synthetics, classloading, expansion, exceptions." + abbreviations: + - "-Ymacro-debug-verbose" + - option: "-Vmacro-lite" schema: type: "Boolean" - description: "Suppress generation of generic signatures for Java." - - option: "-Yno-imports" + description: "Trace macro activities with less output." + abbreviations: + - "-Ymacro-debug-lite" + - option: "-Vopt" + schema: + type: "String" + arg: "package/Class.method" + default: + description: "Trace the optimizer progress for methods; `_` to print all, prefix match to select." + abbreviations: + - "-Yopt-trace" + - option: "-Vpatmat" schema: type: "Boolean" - description: "Compile without importing scala.*, java.lang.*, or Predef." - - option: "-Yno-predef" + description: "Trace pattern matching translation." + abbreviations: + - "-Ypatmat-debug" + - option: "-Vphases" schema: type: "Boolean" - description: "Compile without importing Predef." - - option: "-Yno-adapted-args" + description: "Print a synopsis of compiler phases." + abbreviations: + - "-Xshow-phases" + - option: "-Vpos" schema: type: "Boolean" - description: "Do not adapt an argument list (either by inserting () or creating a tuple) to match the receiver." - - option: "-Yrecursion" + description: "Trace position validation." + abbreviations: + - "-Ypos-debug" + - option: "-Vprint" schema: - type: "Int" - default: 0 - min: 0 - max: 2147483647 - description: "Set recursion depth used when locking symbols." - - option: "-Yshow-trees" + type: "Phases" + default: + description: "Print out program after phases" + abbreviations: + - "-Xprint" + - option: "-Vprint-args" schema: - type: "Boolean" - description: "(Requires -Xprint:) Print detailed ASTs in formatted form." - - option: "-Yshow-trees-compact" + type: "String" + arg: "file" + default: "-" + description: "Print all compiler arguments to the specified location. Use - to echo to the reporter." + abbreviations: + - "-Xprint-args" + - option: "-Vprint-pos" schema: type: "Boolean" - description: "(Requires -Xprint:) Print detailed ASTs in compact form." - - option: "-Yshow-trees-stringified" + description: "Print tree positions, as offsets." + abbreviations: + - "-Xprint-pos" + - option: "-Vprint-types" schema: type: "Boolean" - description: "(Requires -Xprint:) Print stringifications along with detailed ASTs." - - option: "-Yshow-syms" + description: "Print tree types (debugging option)." + abbreviations: + - "-Xprint-types" + - option: "-Vquasiquote" schema: type: "Boolean" - description: "Print the AST symbol hierarchy after each phase." - - option: "-Yshow-symkinds" + description: "Trace quasiquotations." + abbreviations: + - "-Yquasiquote-debug" + - option: "-Vreflective-calls" schema: type: "Boolean" - description: "Print abbreviated symbol kinds next to symbol names." - - option: "-Yshow-symowners" + description: "Print a message when a reflective method call is generated" + abbreviations: + - "-Xlog-reflective-calls" + - option: "-Vreify" schema: type: "Boolean" - description: "Print owner identifiers next to symbol names." - - option: "-Yskip" + description: "Trace reification." + abbreviations: + - "-Yreify-debug" + - option: "-Vshow" schema: type: "Phases" - description: "Skip phases" - note: "See [Compilation Phases](#compilation-phases)" - - option: "-Ygen-asmp" + default: + description: "(Requires -Xshow-class or -Xshow-object) Show after phases" + abbreviations: + - "-Yshow" + - option: "-Vshow-class" schema: type: "String" - arg: "dir" - description: "Generate a parallel output directory of .asmp files (ie ASM Textifier output)." - - option: "-Ydump-classes" + arg: "class" + default: + description: "Show internal representation of class." + abbreviations: + - "-Xshow-class" + - option: "-Vshow-member-pos" schema: type: "String" - arg: "dir" - description: "Dump the generated bytecode to .class files (useful for reflective compilation that utilizes in-memory classloaders)." - - option: "-Ystop-after" - schema: - type: "Phases" - description: "Stop after phases" - note: "See [Compilation Phases](#compilation-phases)" + arg: "output style" + default: + description: "Show start and end positions of members (implies -Yrangepos)" abbreviations: - - "-stop" - - option: "-Ystop-before" - schema: - type: "Phases" - description: "Stop before phases" - note: "See [Compilation Phases](#compilation-phases)" - - option: "-Yrangepos" - schema: - type: "Boolean" - description: "Use range positions for syntax trees." - - option: "-Yshow-member-pos" + - "-Yshow-member-pos" + - option: "-Vshow-object" schema: type: "String" - arg: "output style" - description: "Show start and end positions of members" - note: "`-Yrangepos` is enabled at the same time." - - option: "-Yreify-copypaste" + arg: "object" + default: + description: "Show internal representation of object." + abbreviations: + - "-Xshow-object" + - option: "-Vshow-symkinds" schema: type: "Boolean" - description: "Dump the reified trees in copypasteable representation." - - option: "-Ymacro-expand" - schema: - type: "Choice" - arg: "policy" - default: "normal" - choices: - - choice: "normal" - - choice: "none" - - choice: "discard" - description: "Control expansion of macros, useful for scaladoc and presentation compiler. Choices: (normal,none,discard), default: normal." - - option: "-Ymacro-no-expand" + description: "Print abbreviated symbol kinds next to symbol names." + abbreviations: + - "-Yshow-symkinds" + - option: "-Vshow-symowners" schema: type: "Boolean" - description: "Don't expand macros. Might be useful for scaladoc and presentation compiler, but will crash anything which uses macros and gets past typer." - deprecated: "Use `-Ymacro-expand:none` instead." - - option: "-Yrepl-sync" + description: "Print owner identifiers next to symbol names." + abbreviations: + - "-Yshow-symowners" + - option: "-Vstatistics" + schema: + type: "Phases" + default: "parser,typer,patmat,erasure,cleanup,jvm" + description: "Print compiler statistics for specific phases phases (default: parser,typer,patmat,erasure,cleanup,jvm)" + abbreviations: + - "-Ystatistics" + - option: "-Vsymbols" schema: type: "Boolean" - description: "Do not use asynchronous code for repl startup" - - option: "-Yrepl-class-based" + description: "Print the AST symbol hierarchy after each phase." + abbreviations: + - "-Yshow-syms" + - option: "-Vtyper" schema: type: "Boolean" - description: "Use classes to wrap REPL snippets instead of objects" - - option: "-Yrepl-outdir" + description: "Trace type assignments." + abbreviations: + - "-Ytyper-debug" +- category: "Private Settings" + description: + options: + - option: "-Ybackend-parallelism" schema: - type: "String" - arg: "path" - description: "Write repl-generated classfiles to given output directory (use \"\" to generate a temporary dir)" - - option: "-Yinfer-argument-types" + type: "Int" + default: "1" + min: "1" + max: "16" + description: "maximum worker threads for backend" + - option: "-Ybackend-worker-queue" schema: - type: "Boolean" - description: "Infer types for arguments of overridden methods." - - option: "-YdisableFlatCpCaching" + type: "Int" + default: "0" + min: "0" + max: "1000" + description: "backend threads worker queue size" + - option: "-Ybreak-cycles" schema: type: "Boolean" - description: "Do not cache flat classpath representation of classpath elements from jars across compiler instances." - - option: "-Ycache-plugin-class-loader" + description: "Attempt to break cycles encountered during typing" + - option: "-Ycache-macro-class-loader" schema: type: "Choice" arg: "policy" @@ -626,8 +818,10 @@ description: "Don't cache class loader" - choice: "last-modified" description: "Cache class loader, using file last-modified time to invalidate" - description: "Policy for caching class loaders for compiler plugins that are dynamically loaded. Default: `none`, `help` to list choices." - - option: "-Ycache-macro-class-loader" + - choice: "always" + description: "Cache class loader with no invalidation" + description: "Policy for caching class loaders for macros that are dynamically loaded. Default: `none`, `help` to list choices." + - option: "-Ycache-plugin-class-loader" schema: type: "Choice" arg: "policy" @@ -637,19 +831,18 @@ description: "Don't cache class loader" - choice: "last-modified" description: "Cache class loader, using file last-modified time to invalidate" - description: "Policy for caching class loaders for macros that are dynamically loaded. Default: `none`, `help` to list choices." - - option: "-Ypartial-unification" - schema: - type: "Boolean" - description: "Enable partial unification in type constructor inference" - - option: "-Yvirtpatmat" + - choice: "always" + description: "Cache class loader with no invalidation" + description: "Policy for caching class loaders for compiler plugins that are dynamically loaded. Default: `none`, `help` to list choices." + - option: "-Ycheck" schema: - type: "Boolean" - description: "Enable pattern matcher virtualization" - - option: "-Yexpose-empty-package" + type: "Phases" + default: + description: "Check the tree at the end of phases" + - option: "-Ycompact-trees" schema: type: "Boolean" - description: "Internal only: expose the empty package." + description: "Use compact tree printer when displaying trees." - option: "-Ydelambdafy" schema: type: "Choice" @@ -658,74 +851,78 @@ choices: - choice: "inline" - choice: "method" - description: "Strategy used for translating lambdas into JVM code. Choices: (inline,method), default: method." - - option: "-Ybackend-parallelism" + description: "Strategy used for translating lambdas into JVM code. (inline,[method])" + - option: "-Ydump-classes" schema: - type: "Int" - default: 1 - min: 1 - max: 16 - description: "maximum worker threads for backend" - - option: "-Ybackend-worker-queue" + type: "String" + arg: "dir" + default: + description: "Dump the generated bytecode to .class files (useful for reflective compilation that utilizes in-memory classloaders)." + - option: "-Ygen-asmp" schema: - type: "Int" - default: 0 - min: 0 - max: 1000 - description: "backend threads worker queue size" + type: "String" + arg: "dir" + default: + description: "Generate a parallel output directory of .asmp files (ie ASM Textifier output)." + - option: "-Yimports" + schema: + type: "String" + arg: "import" + multiple: "true" + description: "Custom root imports, default is `java.lang,scala,scala.Predef`." - option: "-Yjar-compression-level" schema: type: "Int" - default: -1 - min: -1 - max: 9 + default: "-1" + min: "-1" + max: "9" description: "compression level to use when writing jar files" - - option: "-opt" + - option: "-Ymacro-annotations" + schema: + type: "Boolean" + description: "Enable support for macro annotations, formerly in macro paradise." + - option: "-Ymacro-classpath" + schema: + type: "Path" + arg: "path" + default: + description: "The classpath used to reflectively load macro implementations, default is the compilation classpath." + - option: "-Ymacro-expand" schema: type: "Choice" - arg: "optimization" - multiple: true + arg: "policy" + default: "normal" choices: - - choice: "unreachable-code" - description: "Eliminate unreachable code, exception handlers guarding no instructions, redundant metadata (debug information, line numbers)." - - choice: "simplify-jumps" - description: "Simplify branching instructions, eliminate unnecessary ones." - - choice: "compact-locals" - description: "Eliminate empty slots in the sequence of local variables." - - choice: "copy-propagation" - description: "Eliminate redundant local variables and unused values (including closures). Enables unreachable-code." - - choice: "redundant-casts" - description: "Eliminate redundant casts using a type propagation analysis." - - choice: "box-unbox" - description: "Eliminate box-unbox pairs within the same method (also tuples, xRefs, value class instances). Enables unreachable-code." - - choice: "nullness-tracking" - description: "Track nullness / non-nullness of local variables and apply optimizations." - - choice: "closure-invocations" - description: "Rewrite closure invocations to the implementation method." - - choice: "inline" - description: "Inline method invocations according to -Yopt-inline-heuristics and -opt-inline-from." - - choice: "l:none" - description: "Disable optimizations. Takes precedence: `-opt:l:none,+box-unbox` / `-opt:l:none -opt:box-unbox` don`t enable box-unbox." - - choice: "l:default" - description: "Enable default optimizations: unreachable-code." - - choice: "l:method" - description: "Enable intra-method optimizations: unreachable-code,simplify-jumps,compact-locals,copy-propagation,redundant-casts,box-unbox,nullness-tracking,closure-invocations." - - choice: "l:inline" - description: "Enable cross-method optimizations (note: inlining requires -opt-inline-from): l:method,inline." - - choice: "l:project" - description: "[deprecated, use -opt:l:inline, -opt-inline-from] Enable cross-method optimizations within the current project." - deprecated: "Use `-opt:l:inline -opt-inline-from` instead." - - choice: "l:classpath" - description: "[deprecated, use -opt:l:inline, -opt-inline-from] Enable cross-method optimizations across the entire classpath." - deprecated: "Use `-opt:l:inline -opt-inline-from` instead." - description: "Enable optimizations: `_` for all, `-opt:help` to list choices." - note: "if `inline` not contained and either `l:project` or `l:classpath` are contained, then `l:inline` is enabled." - - option: "-opt-inline-from" + - choice: "normal" + - choice: "none" + - choice: "discard" + description: "Control expansion of macros, useful for scaladoc and presentation compiler. ([normal],none,discard)" + - option: "-Ymacro-global-fresh-names" schema: - type: "String" - arg: "patterns" - multiple: true - description: "Patterns for classfile names from which to allow inlining, `help` for details." + type: "Boolean" + description: "Should fresh names in macros be unique across all compilation units" + - option: "-Yno-completion" + schema: + type: "Boolean" + description: "Disable tab-completion in the REPL." + - option: "-Yno-flat-classpath-cache" + schema: + type: "Boolean" + description: "Do not cache flat classpath representation of classpath elements from jars across compiler instances." + abbreviations: + - "-YdisableFlatCpCaching" + - option: "-Yno-generic-signatures" + schema: + type: "Boolean" + description: "Suppress generation of generic signatures for Java." + - option: "-Yno-imports" + schema: + type: "Boolean" + description: "Compile without importing scala.*, java.lang.*, or Predef." + - option: "-Yno-predef" + schema: + type: "Boolean" + description: "Compile without importing Predef." - option: "-Yopt-inline-heuristics" schema: type: "Choice" @@ -735,125 +932,130 @@ - choice: "at-inline-annotated" - choice: "everything" - choice: "default" - description: "Set the heuristics for inlining decisions. Choices: (at-inline-annotated,everything,default), default: default." - - option: "-opt-warnings" + description: "Set the heuristics for inlining decisions. (at-inline-annotated,everything,[default])" + - option: "-Ypatmat-exhaust-depth" + schema: + type: "Int" + default: "20" + min: "10" + max: "2147483647" + description: "off" + - option: "-Yprint-trees" schema: type: "Choice" - arg: "warning" - multiple: true + arg: "style" + default: "text" choices: - - choice: "none" - description: "No optimizer warnings." - - choice: "at-inline-failed-summary" - description: "One-line summary if there were @inline method calls that could not be inlined." - - choice: "at-inline-failed" - description: "A detailed warning for each @inline method call that could not be inlined." - - choice: "any-inline-failed" - description: "A detailed warning for every callsite that was chosen for inlining by the heuristics, but could not be inlined." - - choice: "no-inline-mixed" - description: "In mixed compilation, warn at callsites methods defined in java sources (the inlining decision cannot be made without bytecode)." - - choice: "no-inline-missing-bytecode" - description: "Warn if an inlining decision cannot be made because a the bytecode of a class or member cannot be found on the compilation classpath." - - choice: "no-inline-missing-attribute" - description: "Warn if an inlining decision cannot be made because a Scala classfile does not have a ScalaInlineInfo attribute." - description: "Enable optimizer warnings: `_` for all, `-opt-warnings:help` to list choices." - - option: "-Yopt-trace" - schema: - type: "String" - arg: "package/Class.method" - description: "Trace the optimizer progress for methods; `_` to print all, prefix match to select." - - option: "-Yopt-log-inline" + - choice: "text" + - choice: "compact" + - choice: "format" + - choice: "text+format" + description: "How to print trees when -Vprint is enabled. ([text],compact,format,text+format)" + - option: "-Yprofile-destination" schema: type: "String" - arg: "package/Class.method" - description: "Print a summary of inliner activity; `_` to print all, prefix match to select." - - option: "-Ystatistics" - schema: - type: "Phases" - default: "parser,typer,patmat,erasure,cleanup,jvm" - description: "Print compiler statistics for specific phases phases (default: parser,typer,patmat,erasure,cleanup,jvm)" - note: "See [Compilation Phases](#compilation-phases)" - - option: "-Yhot-statistics-enabled" - schema: - type: "Boolean" - description: "Enable `-Ystatistics` to print hot statistics." + arg: "file" + default: + description: "Profiling output - specify a file or `-` for console." - option: "-Yprofile-enabled" schema: type: "Boolean" description: "Enable profiling." - - option: "-Yprofile-destination" - schema: - type: "String" - arg: "file" - description: "where to send profiling output - specify a file, default is to the console." - note: "`-Yprofile-enabled` is enabled at the same time." - option: "-Yprofile-external-tool" schema: type: "Phases" default: "typer" description: "Enable profiling for a phase using an external tool hook. Generally only useful for a single phase phases (default: typer)" - note: "`-Yprofile-enabled` is enabled at the same time." - option: "-Yprofile-run-gc" schema: type: "Phases" default: "_" description: "Run a GC between phases - this allows heap size to be accurate at the expense of more time. Specify a list of phases, or all phases (default: _)" - note: "`-Yprofile-enabled` is enabled at the same time." - - option: "-Ydoc-debug" + - option: "-Yprofile-trace" schema: - type: "Boolean" - description: "Trace all scaladoc activity." - - option: "-Yide-debug" + type: "String" + arg: "file" + default: "profile.trace" + description: "Capture trace of compilation in Chrome Trace format" + - option: "-Yrangepos" schema: type: "Boolean" - description: "Generate, validate and output trees using the interactive compiler." - - option: "-Yissue-debug" + description: "Use range positions for syntax trees." + - option: "-Yrecursion" schema: - type: "Boolean" - description: "Print stack traces when a context issues an error." - - option: "-Ymacro-debug-lite" + type: "Int" + default: "0" + min: "0" + max: "2147483647" + description: "Set recursion depth used when locking symbols." + - option: "-Yreify-copypaste" schema: type: "Boolean" - description: "Trace essential macro-related activities." - - option: "-Ymacro-debug-verbose" + description: "Dump the reified trees in copypasteable representation." + - option: "-Yrepl-class-based" schema: type: "Boolean" - description: "Trace all macro-related activities: compilation, generation of synthetics, classloading, expansion, exceptions." - - option: "-Ypos-debug" + description: "Use classes to wrap REPL snippets instead of objects" + - option: "-Yrepl-outdir" schema: - type: "Boolean" - description: "Trace position validation." - - option: "-Yreify-debug" + type: "String" + arg: "path" + default: + description: "Write repl-generated classfiles to given output directory (use \"\" to generate a temporary dir)" + - option: "-Yresolve-term-conflict" schema: - type: "Boolean" - description: "Trace reification." - - option: "-Ytyper-debug" + type: "Choice" + arg: "strategy" + default: "error" + choices: + - choice: "package" + - choice: "object" + - choice: "error" + description: "Resolve term conflicts. (package,object,[error])" + - option: "-Yscriptrunner" schema: - type: "Boolean" - description: "Trace all type assignments." - - option: "-Ypatmat-debug" + type: "String" + arg: "classname" + default: "default" + description: "Specify a scala.tools.nsc.ScriptRunner (default, resident, shutdown, or a class name)." + - option: "-Yskip" schema: - type: "Boolean" - description: "Trace pattern matching translation." - - option: "-Ypatmat-exhaust-depth" + type: "Phases" + default: + description: "Skip phases" + - option: "-Ystop-after" schema: - type: "Int" - default: 20 - min: 10 - max: 2147483647 - description: "off" - - option: "-Yquasiquote-debug" + type: "Phases" + default: + description: "Stop after phases" + abbreviations: + - "-stop" + - option: "-Ystop-before" schema: - type: "Boolean" - description: "Trace quasiquote-related activities." + type: "Phases" + default: + description: "Stop before phases" + - option: "-Yvalidate-pos" + schema: + type: "Phases" + default: + description: "Validate positions after the given phases (implies -Yrangepos) phases" - category: "Warning Settings" - description: "This section assembles the `-X` and `-Y` options those influence the printing of warnings." + description: options: - - option: "-Xfatal-warnings" + - option: "-Wdead-code" schema: type: "Boolean" - description: "Fail the compilation if there are any warnings." - - option: "-Ywarn-macros" + description: "Warn when dead code is identified." + abbreviations: + - "-Ywarn-dead-code" + - option: "-Wextra-implicit" + schema: + type: "Boolean" + description: "Warn when more than one implicit parameter section is defined." + abbreviations: + - "-Ywarn-extra-implicit" + - option: "-Wmacros" schema: type: "Choice" arg: "mode" @@ -868,24 +1070,31 @@ - choice: "both" description: "Inspect both user-written code and expanded trees when generating unused symbol warnings." description: "Enable lint warnings on macro expansions. Default: `before`, `help` to list choices." - - option: "-Ywarn-dead-code" + abbreviations: + - "-Ywarn-macros" + - option: "-Wnumeric-widen" schema: type: "Boolean" - description: "Warn when dead code is identified." - - option: "-Ywarn-value-discard" + description: "Warn when numerics are widened." + abbreviations: + - "-Ywarn-numeric-widen" + - option: "-Woctal-literal" schema: type: "Boolean" - description: "Warn when non-Unit expression results are unused." - note: "To reduce noises for common idiom, warning are suppressed if type of results are `this.type`." - - option: "-Ywarn-numeric-widen" + description: "Warn on obsolete octal syntax." + abbreviations: + - "-Ywarn-octal-literal" + - option: "-Wself-implicit" schema: type: "Boolean" - description: "Warn when numerics are widened." - - option: "-Ywarn-unused" + description: "Warn when an implicit resolves to an enclosing self-definition." + abbreviations: + - "-Ywarn-self-implicit" + - option: "-Wunused" schema: type: "Choice" arg: "warning" - multiple: true + multiple: "true" choices: - choice: "imports" description: "Warn if an import selector is not referenced." @@ -900,39 +1109,32 @@ - choice: "implicits" description: "Warn if an implicit parameter is unused." - choice: "params" - description: "Enable -Ywarn-unused:explicits,implicits." + description: "Enable -Wunused:explicits,implicits." - choice: "linted" description: "-Xlint:unused." - description: "Enable or disable specific `unused` warnings: `_` for all, `-Ywarn-unused:help` to list choices." - - option: "-Ywarn-extra-implicit" - schema: - type: "Boolean" - description: "Warn when more than one implicit parameter section is defined." - - option: "-Ywarn-self-implicit" + description: "Enable or disable specific `unused` warnings" + abbreviations: + - "-Ywarn-unused" + - option: "-Wvalue-discard" schema: type: "Boolean" - description: "Warn when an implicit resolves to an enclosing self-definition." + description: "Warn when non-Unit expression results are unused." + abbreviations: + - "-Ywarn-value-discard" - option: "-Xlint" schema: type: "Choice" arg: "warning" - multiple: true + multiple: "true" choices: - choice: "adapted-args" description: "Warn if an argument list is modified to match the receiver." - note: "Alias is `-Ywarn-adapted-args`." - choice: "nullary-unit" description: "Warn when nullary methods return Unit." - note: "Alias is `-Ywarn-nullary-unit`." - choice: "inaccessible" description: "Warn about inaccessible types in method signatures." - note: "Alias is `-Ywarn-inaccessible`." - - choice: "nullary-override" - description: "Warn when non-nullary `def f()` overrides nullary `def f`." - note: "Alias is `-Ywarn-nullary-override`." - choice: "infer-any" description: "Warn when a type argument is inferred to be `Any`." - note: "Alias is `-Ywarn-infer-any`." - choice: "missing-interpolator" description: "A string literal appears to be missing an interpolator id." - choice: "doc-detached" @@ -947,53 +1149,65 @@ description: "Option.apply used implicit view." - choice: "delayedinit-select" description: "Selecting member of DelayedInit." - - choice: "by-name-right-associative" - description: "By-name parameter of right associative operator." - choice: "package-object-classes" description: "Class or object defined in package object." - - choice: "unsound-match" - description: "Pattern match may not be typesafe." - choice: "stars-align" description: "Pattern sequence wildcard must align with sequence component." - choice: "constant" description: "Evaluation of a constant arithmetic expression results in an error." - choice: "unused" - description: "Enable -Ywarn-unused:imports,privates,locals,implicits." - description: "Enable or disable specific warnings: `_` for all, `-Xlint:help` to list choices." - note: "If this options contains `unused`, it enables `-Ywarn-unused:linted`. Otherwise it disables `-Ywarn-unused:linted`." -- category: "IDE Specific Settings" - description: "" + description: "Enable -Wunused:imports,privates,locals,implicits." + - choice: "nonlocal-return" + description: "A return statement used an exception for flow control." + - choice: "implicit-not-found" + description: "Check @implicitNotFound and @implicitAmbiguous messages." + - choice: "serial" + description: "@SerialVersionUID on traits and non-serializable classes." + - choice: "valpattern" + description: "Enable pattern checks in val definitions." + - choice: "eta-zero" + description: "Warn on eta-expansion (rather than auto-application) of zero-ary method." + - choice: "eta-sam" + description: "Warn on eta-expansion to meet a Java-defined functional interface that is not explicitly annotated with @FunctionalInterface." + - choice: "deprecation" + description: "Enable linted deprecations." + description: "Enable recommended warnings" +- category: "IDE-specific Settings" + description: options: - - option: "-Ypresentation-verbose" + - option: "-Ypresentation-any-thread" schema: type: "Boolean" - description: "Print information about presentation compiler tasks." + description: "Allow use of the presentation compiler from any thread" - option: "-Ypresentation-debug" schema: type: "Boolean" description: "Enable debugging output for the presentation compiler." - - option: "-Ypresentation-any-thread" - schema: - type: "Boolean" - description: "Allow use of the presentation compiler from any thread" - - option: "-Ypresentation-strict" + - option: "-Ypresentation-delay" schema: - type: "Boolean" - description: "Do not report type errors in sources with syntax errors." + type: "Int" + default: "0" + min: "0" + max: "999" + description: "Wait number of ms after typing before starting typechecking" - option: "-Ypresentation-log" schema: type: "String" arg: "file" + default: description: "Log presentation compiler events into file" - option: "-Ypresentation-replay" schema: type: "String" arg: "file" + default: description: "Replay presentation compiler events from file" - - option: "-Ypresentation-delay" + - option: "-Ypresentation-strict" schema: - type: "Int" - default: 0 - min: 0 - max: 999 - description: "Wait number of ms after typing before starting typechecking" + type: "Boolean" + description: "Do not report type errors in sources with syntax errors." + - option: "-Ypresentation-verbose" + schema: + type: "Boolean" + description: "Print information about presentation compiler tasks." + diff --git a/_data/doc-nav-header.yml b/_data/doc-nav-header.yml index f7a4ff3ea2..772da79703 100644 --- a/_data/doc-nav-header.yml +++ b/_data/doc-nav-header.yml @@ -1,23 +1,47 @@ -- title: API +- title: Getting Started url: "#" submenu: - - title: Current - url: https://www.scala-lang.org/api/current/ - - title: Nightly - url: https://www.scala-lang.org/files/archive/nightly/2.12.x/api/2.12.x/ - - title: All Versions - url: "/api/all.html" + - title: Install Scala + url: "/getting-started/install-scala.html" + - title: Scala IDEs + url: "/getting-started/scala-ides.html" - title: Learn url: "#" submenu: - - title: Getting Started - url: "/getting-started.html" - title: Tour of Scala url: "/tour/tour-of-scala.html" + - title: Scala 3 Book + url: "/scala3/book/introduction.html" + - title: Scala 2 Book + url: "/overviews/scala-book/introduction.html" + - title: Online Courses + url: "/online-courses.html" +- title: Scala 3 Migration + url: "#" + submenu: + - title: What's New? + url: "/scala3/new-in-scala3.html" + - title: Migrating From Scala 2 + url: "/scala3/guides/migration/compatibility-intro.html" + - title: New Features for Scaladoc + url: "/scala3/scaladoc.html" + - title: Videos and Talks + url: "/scala3/talks.html" +- title: Tutorials + url: "#" + submenu: + - title: Getting Started with Scala in IntelliJ + url: "/getting-started/intellij-track/getting-started-with-scala-in-intellij.html" + - title: Getting Started with Scala and sbt + url: "/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html" - title: Scala for Java Programmers url: "/tutorials/scala-for-java-programmers.html" - - title: Online Resources - url: "/learn.html" + - title: Scala on Android + url: "/tutorials/scala-on-android.html" + - title: Scala with Maven + url: "/tutorials/scala-with-maven.html" + - title: Using the Scala Toolkit + url: "/toolkit/introduction.html" - title: Reference url: "#" submenu: @@ -25,15 +49,23 @@ url: "/overviews/index.html" - title: Books url: "/books.html" - - title: Scala FAQs + - title: Scala FAQ url: "/tutorials/FAQ/index.html" - - title: Language Spec - url: http://scala-lang.org/files/archive/spec/2.12/ -- title: Style Guide - url: "/style/index.html" -- title: Cheatsheet - url: "/cheatsheets/index.html" -- title: Glossary - url: "/glossary/index.html" + - title: Scala 2 Language Specification + url: http://scala-lang.org/files/archive/spec/2.13/ + - title: Scala 3 Language Specification + url: http://scala-lang.org/files/archive/spec/3.4/ + - title: Scala 3 Language Reference + url: "https://docs.scala-lang.org/scala3/reference" + - title: Scala Contribution Guide + url: "/contribute/" + - title: Style Guide + url: "/style/index.html" + - title: Cheatsheet + url: "/cheatsheets/index.html" + - title: Glossary + url: "/glossary/index.html" +- title: API + url: "/api/all.html" - title: SIPs url: "/sips/index.html" diff --git a/_data/footer.yml b/_data/footer.yml index 04e60f45eb..789017f8b9 100644 --- a/_data/footer.yml +++ b/_data/footer.yml @@ -8,7 +8,7 @@ - title: Overviews/Guides url: "/overviews" - title: Language Specification - url: "http://scala-lang.org/files/archive/spec/2.12/" + url: "http://scala-lang.org/files/archive/spec/2.13/" - title: Download class: download links: @@ -21,9 +21,11 @@ links: - title: Community url: "http://scala-lang.org/community/" - - title: Mailing Lists - url: "http://scala-lang.org/community/index.html#mailing-lists" - - title: Chat Rooms & More + - title: Scala Ambassadors + url: "http://scala-lang.org/ambassadors/" + - title: Forums + url: "http://scala-lang.org/community/index.html#forums" + - title: Chat url: "http://scala-lang.org/community/index.html#chat-rooms" - title: Libraries and Tools url: "http://scala-lang.org/community/index.html#community-libraries-and-tools" @@ -39,16 +41,28 @@ - title: Scala class: scala links: + - title: Governance + url: "http://scala-lang.org/governance/" - title: Blog url: "http://scala-lang.org/blog/" - title: Code of Conduct url: "http://scala-lang.org/conduct/" - title: License url: "http://scala-lang.org/license/" + - title: Security Policy + url: "http://scala-lang.org/security/" - title: Social class: social links: - title: GitHub url: "https://github.com/scala/scala" - - title: Twitter - url: "https://twitter.com/scala_lang" + - title: Mastodon + url: "https://fosstodon.org/@scala_lang" + - title: Bluesky + url: "https://bsky.app/profile/scala-lang.org" + - title: X + url: "https://x.com/scala_lang" + - title: Discord + url: "https://discord.com/invite/scala" + - title: LinkedIn + url: "https://www.linkedin.com/company/scala-center/" \ No newline at end of file diff --git a/_data/messages.yml b/_data/messages.yml new file mode 100644 index 0000000000..642a7ac557 --- /dev/null +++ b/_data/messages.yml @@ -0,0 +1 @@ +scam-banner: "**⚠️ Beware of Scams**: since Feb 2024, scammers are using [fake Scala websites to sell courses](https://www.scala-lang.org/blog/2024/03/01/fake-scala-courses.html), please check you are using an official source." diff --git a/_data/nav-header.yml b/_data/nav-header.yml index 26bd280020..792c68fc1e 100644 --- a/_data/nav-header.yml +++ b/_data/nav-header.yml @@ -1,12 +1,14 @@ -- title: Documentation +- title: Learn url: "/" -- title: Download +- title: Install url: https://www.scala-lang.org/download/ +- title: Playground + url: https://scastie.scala-lang.org +- title: Find A Library + url: https://index.scala-lang.org - title: Community url: https://www.scala-lang.org/community/ -- title: Libraries - url: https://index.scala-lang.org -- title: Contribute - url: https://www.scala-lang.org/contribute/ +- title: Governance + url: https://www.scala-lang.org/governance/ - title: Blog url: https://www.scala-lang.org/blog/ diff --git a/_data/overviews-ja.yml b/_data/overviews-ja.yml new file mode 100644 index 0000000000..60277bd90c --- /dev/null +++ b/_data/overviews-ja.yml @@ -0,0 +1,326 @@ +- category: 標準ライブラリ + description: "Scala 標準ライブラリをカバーするガイドと概要" + overviews: + - title: Scala コレクション + by: Martin Odersky and Julien Richard-Foy + icon: sitemap + url: "collections-2.13/introduction.html" + description: "Scala のコレクションライブラリ" + subdocs: + - title: はじめに + url: "collections-2.13/introduction.html" + - title: 可変コレクションおよび不変コレクション + url: "collections-2.13/overview.html" + - title: Iterable トレイト + url: "collections-2.13/trait-iterable.html" + - title: 列トレイト Seq、IndexedSeq、および LinearSeq + url: "collections-2.13/seqs.html" + - title: 具象不変コレクションクラス + url: "collections-2.13/concrete-immutable-collection-classes.html" + - title: 具象可変コレクションクラス + url: "collections-2.13/concrete-mutable-collection-classes.html" + - title: 配列 + url: "collections-2.13/arrays.html" + - title: 文字列 + url: "collections-2.13/strings.html" + - title: 性能特性 + url: "collections-2.13/performance-characteristics.html" + - title: 等価性 + url: "collections-2.13/equality.html" + - title: ビュー + url: "collections-2.13/views.html" + - title: イテレータ + url: "collections-2.13/iterators.html" + - title: コレクションの作成 + url: "collections-2.13/creating-collections-from-scratch.html" + - title: Java と Scala 間のコレクションの変換 + url: "collections-2.13/conversions-between-java-and-scala-collections.html" + - title: プロジェクトを Scala 2.13 コレクションへ移行する + icon: sitemap + url: "core/collections-migration-213.html" + description: "このページは Scala 2.13 へ移行するコレクションユーザーにとっての主な変更を説明し、Scala 2.11、2.12、2.13 向けにクロスビルドする方法をお見せする。" + - title: Scala コレクションのアーキテクチャー + icon: sitemap + url: "core/architecture-of-scala-213-collections.html" + by: Julien Richard-Foy + description: "このページは Scala 2.13 で導入されたコレクションフレームワークのアーキテクチャーを説明する。コレクション API というよりはフレームワークの内部の動きがもっと分かるだろう。" + - title: カスタムコレクションを実装する + icon: building + url: "core/custom-collections.html" + by: Martin Odersky, Lex Spoon and Julien Richard-Foy + description: "このドキュメントでは、コレクションフレームワークがどのようにして数行のコードであなた自身が独自コレクションを定義でき、しかもフレームワークの圧倒的な量の機能を再利用できる助けをしているかを学べるだろう。" + - title: カスタムのコレクション操作を追加する + icon: building + url: "core/custom-collection-operations.html" + by: Julien Richard-Foy + description: "このガイドでは、どのようなコレクション型にも適用できて元のコレクション型を返すことができる操作の書き方、さらに組み立てるコレクション型によってパラメータ化された操作の書き方もお見せする。" + +- category: 言語 + description: "Scala 言語の機能をカバーするガイドと概要" + overviews: + - title: "Scala 2 から Scala 3 への移行" + icon: suitcase + root: "scala3/guides/" + url: "migration/compatibility-intro.html" + description: "Scala 3 との互換性と移行について知っておくべきことすべて" + - title: "Scala 3 マクロ" + by: Nicolas Stucki + icon: magic + root: "scala3/guides/" + url: "macros" + description: "Scala 3 のマクロの書き方に関係する全ての機能をカバーする詳しいチュートリアル" + label-text: new in Scala 3 + - title: 値クラスと汎用トレイト + by: Mark Harrah + description: "値クラスは Scala で実行時のオブジェクトアロケーションを避ける新しい仕組みだ。これは新しい AnyVal サブクラスを定義することで達成できる。" + icon: gem + url: "core/value-classes.html" + - title: TASTyの概要 + by: Alvin Alexander + icon: birthday-cake + root: "scala3/guides/" + url: "tasty-overview.html" + description: "Scala のエンドユーザー向けの TASTy のフォーマットの概要" + label-text: new in Scala 3 + - title: 文字列補間 + icon: dollar-sign + url: "core/string-interpolation.html" + description: > + 文字列補間は、ユーザーが加工文字列リテラル（processed string literal）に変数参照を直接埋め込めるようにしてくれる。以下例。 + 
val name = "James"
+        println(s"Hello, $name")  // Hello, James
+ 上記例では、リテラル s"Hello, $name" は加工文字列リテラルだ。これはコンパイラーがこのリテラルに追加の仕事をしていることを意味する。加工文字列リテラルは " に先行するいくつかの文字で示される。文字列補間は SIP-11 で導入され、そこには実装の全詳細が含まれる。 + - title: 暗黙クラス + by: Josh Suereth + description: "Scala 2.10 は暗黙クラス（implicit class）と呼ばれる新しい機能を導入した。暗黙クラスは implicit キーワードでマークされたクラスだ。このキーワードはそのクラスがスコープ内にあるとき、そのプライマリコンストラクターが暗黙変換に利用可能にする。" + url: "core/implicit-classes.html" + +- category: ライブラリの作成 + description: "Scala エコシステム向けのオープンソースライブラリの貢献方法のガイド" + overviews: + - title: ライブラリ作者へのガイド + by: "Julien Richard-Foy" + icon: tasks + url: "contributors/index.html" + description: "ライブラリ作者がライブラリを公開したりドキュメントしたりするのにセットアップすべき全ツールをリストにする。" + +- category: 並列並行プログラミング + description: "並列並行プログラミングのための Scala のライブラリをカバーする完全ガイド" + overviews: + - title: Future と Promise + by: "Philipp Haller, Aleksandar Prokopec, Heather Miller, Viktor Klang, Roland Kuhn, and Vojin Jovanovic" + icon: tasks + url: "core/futures.html" + description: "Futures は多くの処理を並列で、効率的かつノンブロッキングに実行する考え方を提供する。Future はまだ存在しない値のプレースホルダーオブジェクトだ。一般に Future の値は並行で供給され、その後で使うことができる。このようなやり方で並行タスクを組み立てると、高速、ノンブロッキングで並列なコードにつなげるのに役立つ。" + - title: 並行コレクション + by: Aleksandar Prokopec and Heather Miller + icon: rocket + url: "parallel-collections/overview.html" + description: "Scala の並行コレクションライブラリ" + subdocs: + - title: 概要 + url: "parallel-collections/overview.html" + - title: 具象並列コレクションクラス + url: "parallel-collections/concrete-parallel-collections.html" + - title: 並列コレクションへの変換 + url: "parallel-collections/conversions.html" + - title: 並行トライ + url: "parallel-collections/ctries.html" + - title: 並列コレクションライブラリのアーキテクチャ + url: "parallel-collections/architecture.html" + - title: カスタム並列コレクションの作成 + url: "parallel-collections/custom-parallel-collections.html" + - title: 並列コレクションの設定 + url: "parallel-collections/configuration.html" + - title: 性能の測定 + url: "parallel-collections/performance.html" + +- category: 互換性 + description: "何が何と動くか動かないか" + overviews: + - title: JDK バージョン互換性 + description: "どの Scala バージョンがどの JDK バージョンで動くか" + icon: coffee + url: "jdk-compatibility/overview.html" + - title: Scala リリースのバイナリ互換性 + description: "Scala の2つのバージョンがバイナリ互換であるとき、一方の Scala バージョンでプロジェクトをコンパイルし、実行時にもう一方の Scala バージョンにリンクするのは安全だ。安全な実行時リンクとは、同じバージョンの Scala でコンパイルや実行するときでは起こり得ないだろう複雑なシナリオでプログラムを実行しても、JVM が LinkageError（かそのサブクラス）を発生させないということ（のみ！）を意味する。具体的には、バイナリ互換である限り、コンパイル時とは異なる Scala バージョンの外部依存関係を実行時クラスパスに持つことができるということだ。言い換えると、異なるバイナリ互換バージョンでの分離コンパイルは、すべて Scala の同じバージョンでコンパイルも実行もすることと同様、問題ない。" + icon: puzzle-piece + url: "core/binary-compatibility-of-scala-releases.html" + - title: ライブラリ作者のためのバイナリ互換 + description: "多種多様なライブラリは生産性の高いソフトウェアエコシステムにとって重要だ。Scala ライブラリを開発・頒布するのはたやすいが、良いライブラリ作者はコードを書いて公開する以上のことをする。このガイドではライブラリのバイナリ互換という重要なトピックをカバーする。" + icon: puzzle-piece + url: "core/binary-compatibility-for-library-authors.html" + +- category: "ツール" + description: "Scala REPL や Scaladoc 生成のようなコアの Scala ツールの参考資料" + overviews: + - title: Scala REPL + icon: terminal + url: "repl/overview.html" + description: | + Scala REPL は Scala の式を評価するツール（scala）だ。 +

+ scala コマンドはソーススクリプトをテンプレートでラップし、コンパイルし、できあがったプログラムを実行することで実行する。 + - title: Scaladoc + url: "scaladoc/overview.html" + icon: book + description: "Scala の API ドキュメント生成ツール" + subdocs: + - title: 概要 + url: "scaladoc/overview.html" + - title: ライブラリ作者のための Scaladoc + url: "scaladoc/for-library-authors.html" + - title: Scaladoc インターフェースを使う + url: "scaladoc/interface.html" + +- category: コンパイラー + description: "Scala コンパイラーをカバーするガイドと概要。コンパイラプラグイン、リフレクション、マクロのようなメタプログラミング。" + overviews: + - title: リフレクション + by: Heather Miller, Eugene Burmako, and Philipp Haller + icon: binoculars + url: "reflection/overview.html" + description: Scala の実行時/コンパイル時のリフレクションフレームワーク。 + label-text: experimental + subdocs: + - title: 概要 + url: "reflection/overview.html" + - title: 環境、ユニバース、ミラー + url: "reflection/environment-universes-mirrors.html" + - title: シンボル、構文木、型 + url: "reflection/symbols-trees-types.html" + - title: アノテーション、名前、スコープ、その他 + url: "reflection/annotations-names-scopes.html" + - title: 型タグとマニフェスト + url: "reflection/typetags-manifests.html" + - title: スレッドセーフティ + url: "reflection/thread-safety.html" + - title: Scala 2.11 での変更 + url: "reflection/changelog211.html" + - title: マクロ + by: Eugene Burmako + icon: magic + url: "macros/usecases.html" + description: "Scala のメタプログラミングフレームワーク" + label-text: experimental + subdocs: + - title: ユースケース + url: "macros/usecases.html" + - title: Blackbox vs Whitebox + url: "macros/blackbox-whitebox.html" + - title: def マクロ + url: "macros/overview.html" + - title: 準クォート + url: "quasiquotes/intro.html" + - title: マクロバンドル + url: "macros/bundles.html" + - title: implicit マクロ + url: "macros/implicits.html" + - title: 抽出子マクロ + url: "macros/extractors.html" + - title: 型プロバイダ + url: "macros/typeproviders.html" + - title: マクロアノテーション + url: "macros/annotations.html" + - title: マクロパラダイス + url: "macros/paradise.html" + - title: ロードマップ + url: "macros/roadmap.html" + - title: Scala 2.11 での変更 + url: "macros/changelog211.html" + - title: 準クォート + by: Denys Shabalin + icon: quote-left + url: "quasiquotes/setup.html" + description: "準クォートは Scala の構文木を操作する便利な方法だ。" + label-text: experimental + subdocs: + - title: 依存関係とセットアップ + url: "quasiquotes/setup.html" + - title: はじめに + url: "quasiquotes/intro.html" + - title: リフト + url: "quasiquotes/lifting.html" + - title: アンリフト + url: "quasiquotes/unlifting.html" + - title: 健全性 + url: "quasiquotes/hygiene.html" + - title: ユースケース + url: "quasiquotes/usecases.html" + - title: 構文の概要 + url: "quasiquotes/syntax-summary.html" + - title: 式の詳細 + url: "quasiquotes/expression-details.html" + - title: 型の詳細 + url: "quasiquotes/type-details.html" + - title: パターンの詳細 + url: "quasiquotes/pattern-details.html" + - title: 定義とインポートの詳細 + url: "quasiquotes/definition-details.html" + - title: 専門用語の概要 + url: "quasiquotes/terminology.html" + - title: 将来の見通し + url: "quasiquotes/future.html" + - title: コンパイラープラグイン + by: Lex Spoon and Seth Tisue + icon: puzzle-piece + url: "plugins/index.html" + description: "コンパイラープラグインは Scala コンパイラーのカスタマイズと拡張を可能にする。このチュートリアルはプラグインの仕組みを説明し、かんたんなプラグインの作成をウォークスルーする。" + - title: コンパイラーオプション + by: Community + icon: cog + url: "compiler-options/index.html" + description: > + scalac がどのようにコードをコンパイルするかの様々な設定。 + + +- category: レガシー + description: "最近の Scala バージョン（2.12以上）には関係なくなった機能をカバーするガイド。" + overviews: + - title: Scala 2.8 から 2.12 までのコレクション + by: Martin Odersky + icon: sitemap + url: "collections/introduction.html" + description: "Scala's Collection Library." + subdocs: + - title: はじめに + url: "collections/introduction.html" + - title: 可変コレクションおよび不変コレクション + url: "collections/overview.html" + - title: Traversable トレイト + url: "collections/trait-traversable.html" + - title: Iterable トレイト + url: "collections/trait-iterable.html" + - title: 列トレイト Seq、IndexedSeq、および LinearSeq + url: "collections/seqs.html" + - title: 集合 + url: "collections/sets.html" + - title: マップ + url: "collections/maps.html" + - title: 具象不変コレクションクラス + url: "collections/concrete-immutable-collection-classes.html" + - title: 具象可変コレクションクラス + url: "collections/concrete-mutable-collection-classes.html" + - title: 配列 + url: "collections/arrays.html" + - title: 文字列 + url: "collections/strings.html" + - title: 性能特性 + url: "collections/performance-characteristics.html" + - title: 等価性 + url: "collections/equality.html" + - title: ビュー + url: "collections/views.html" + - title: イテレータ + url: "collections/iterators.html" + - title: コレクションの作成 + url: "collections/creating-collections-from-scratch.html" + - title: Java と Scala 間のコレクションの変換 + url: "collections/conversions-between-java-and-scala-collections.html" + - title: Scala 2.7 からの移行 + url: "collections/migrating-from-scala-27.html" + - title: Scala 2.8 から 2.12 までのコレクションのアーキテクチャ + icon: building + url: "core/architecture-of-scala-collections.html" + by: Martin Odersky and Lex Spoon + description: "これらのページは Scala コレクションフレームワークのアーキテクチャを詳細に説明する。コレクション API というよりはフレームワークの内部の動きがもっとよく分かるだろう。また、コレクションフレームワークがどのようにして数行のコードであなた自身が独自コレクションを定義でき、しかもフレームワークの圧倒的な量の機能を再利用できる助けをしているかを学べるだろう。" diff --git a/_data/overviews-ru.yml b/_data/overviews-ru.yml new file mode 100644 index 0000000000..f4a652a032 --- /dev/null +++ b/_data/overviews-ru.yml @@ -0,0 +1,307 @@ +- category: Стандартная Библиотека + description: "Руководства и обзоры, охватывающие стандартную библиотеку Scala." + overviews: + - title: Scala коллекции + by: Martin Odersky и Julien Richard-Foy + icon: sitemap + url: "collections-2.13/introduction.html" + description: "Библиотека Scala коллекций." + subdocs: + - title: Введение + url: "collections-2.13/introduction.html" + - title: Изменяемые и Неизменяемые Коллекции + url: "collections-2.13/overview.html" + - title: Трейт Iterable + url: "collections-2.13/trait-iterable.html" + - title: Последовательности. Трейты Seq, IndexedSeq и LinearSeq + url: "collections-2.13/seqs.html" + - title: Реализации Неизменяемых Коллекций + url: "collections-2.13/concrete-immutable-collection-classes.html" + - title: Реализации Изменяемых Коллекций + url: "collections-2.13/concrete-mutable-collection-classes.html" + - title: Массивы + url: "collections-2.13/arrays.html" + - title: Строки + url: "collections-2.13/strings.html" + - title: Показатели производительности + url: "collections-2.13/performance-characteristics.html" + - title: Равенство + url: "collections-2.13/equality.html" + - title: Отображения + url: "collections-2.13/views.html" + - title: Итераторы + url: "collections-2.13/iterators.html" + - title: Создание коллекций с нуля + url: "collections-2.13/creating-collections-from-scratch.html" + - title: Преобразования между Java и Scala коллекциями + url: "collections-2.13/conversions-between-java-and-scala-collections.html" + - title: Перевод проекта на использование коллекций Scala 2.13 + icon: sitemap + url: "core/collections-migration-213.html" + description: "Эта страница описывает главные изменения в коллекциях для тех кто + переводит проект на Scala 2.13, а также демонстрирует как собирать проект под версии Scala 2.11 / 2.12 и 2.13" + - title: Архитектура Scala коллекций + icon: sitemap + url: "core/architecture-of-scala-213-collections.html" + by: Julien Richard-Foy + description: "На этих страницах описывается архитектура фреймворка коллекций, представленного в Scala 2.13. По сравнению с API Коллекции вы узнаете здесь больше о внутренней работе фреймворка." + - title: Создание Своих Коллекций + icon: building + url: "core/custom-collections.html" + by: Martin Odersky, Lex Spoon и Julien Richard-Foy + description: "В этом документе вы узнаете, как коллекции помогают вам реализовывать собственные персональные коллекции, используя всего несколько строчек кода и переиспользуя большую часть функциональности коллекций из базового фреймворка." + - title: Добавление своих операций к коллекциям + icon: building + url: "core/custom-collection-operations.html" + by: Julien Richard-Foy + description: "В данном руководстве показано, как написать операции, которые могут быть применены к любому типу коллекции и которые вернут исходный тип коллекции, а также как написать операции, которые можно параметризовать по типу коллекции." + +- category: Язык + description: "Руководства и обзоры, охватывающие функционал языка Scala." + overviews: + - title: Строковая интерполяция + icon: dollar-sign + url: "core/string-interpolation.html" + description: > + Строковая интерполяция позволяет пользователям встраивать данные из переменных непосредственно в обрабатываемые строковые литералы. Вот пример: + 
val name = "James"
+          println(s"Hello, $name")  // Hello, James
+ В приведенном выше литерале s"Hello, $name" - это перерабатываемая строка. Такая запись указывает компилятору сделать некоторую дополнительную работу над самим литералом. Сам обрабатываемый строковый литерал обозначается набором символов, предшествующим ". Интерполяция строк была введена в SIP-11, который содержит все детали реализации. + - title: Неявные Классы + by: Josh Suereth + description: "В Скале 2.10 введена новая функциональность, называемая неявными классами. Неявный класс - это класс, помеченный ключевым словом implicit. Это ключевое слово позволяет использовать первичный конструктор класса в процессе неявного преобразования одного типа в другой, когда класс находится в области видимости." + url: "core/implicit-classes.html" + - title: Вычислительные Классы и Универсальные Трейты + by: Mark Harrah + description: "Вычислительные-Классы - это новый механизм в Scala, позволяющий избежать создания объектов во время исполнения, которое достигается за счет объявления класса в качестве подкласса AnyVal." + icon: gem + url: "core/value-classes.html" + +- category: Создание своих библиотек + description: "Руководства по вкладу в создание библиотек с открытым исходным кодом в Scala экосистеме" + overviews: + - title: Справочник для автора библиотек + by: "Julien Richard-Foy" + icon: tasks + url: "contributors/index.html" + description: "Список инструментов, которые авторы библиотек должны настроить для публикации и документирования своих библиотек." + +- category: Параллельное и Конкурентное Программирование + description: "Полное руководство по параллельному и конкурентному программированию в библиотеках Scala." + overviews: + - title: Futures и Promise + by: "Philipp Haller, Aleksandar Prokopec, Heather Miller, Viktor Klang, Roland Kuhn и Vojin Jovanovic" + icon: tasks + url: "core/futures.html" + description: "Фьючерсы (Futures) дают возможность эффективно и без блокировок осуществлять многие операции параллельно. Future - это обертка над объектом, который может пока ещё не существовать. Как правило, вычисление Future осуществляется конкурентно и может быть использовано позднее. Композиция таких конкурентных процессов приводит в итоге к более быстрому, асинхронному, не блокирующему, параллельно исполняемому коду." + - title: Параллельные коллекции + by: Aleksandar Prokopec и Heather Miller + icon: rocket + url: "parallel-collections/overview.html" + description: "Scala's Parallel Collections Library." + subdocs: + - title: Обзор + url: "parallel-collections/overview.html" + - title: Реализация Параллельных Коллекций + url: "parallel-collections/concrete-parallel-collections.html" + - title: Преобразования Параллельных Коллекций + url: "parallel-collections/conversions.html" + - title: Многопоточные Префиксные Деревья + url: "parallel-collections/ctries.html" + - title: Архитектура Библиотеки Параллельных Коллекций + url: "parallel-collections/architecture.html" + - title: Создание Пользовательской Параллельной Коллекции + url: "parallel-collections/custom-parallel-collections.html" + - title: Конфигурирование Параллельных Коллекций + url: "parallel-collections/configuration.html" + - title: Измерение производительности + url: "parallel-collections/performance.html" + +- category: Совместимость + description: "Что с чем работает (или не работает)." + overviews: + - title: Совместимость с версиями JDK + description: "Какие версии Scala работают с какими версиями JDK" + icon: coffee + url: "jdk-compatibility/overview.html" + - title: Совместимость релизов Scala на уровне двоичного кода + description: "Когда две версии Scala совместимы на уровне двоичного кода - это означает что проект безопасно компилировать на одной версии Scala и связывать с другой версией Scala во время исполнения. Безопасное связывание во время исполнения (только!) означает, что JVM не бросит исключение (подкласса) LinkageError при выполнении вашей программы в смешанном сценарии, предполагая, что никаких исключений не возникает при компиляции и запуске на одной и той же версии Scala. В том числе, это означает, что можно иметь внешние зависимости в программе, использующие другую версию Scala, чем та, с которой вы скомпилировали проект, до тех пор пока они совместимы на уровне двоичного кода. Другими словами, раздельная компиляция на разных но совместимых на уровне двоичного кода версиях не создает новых проблем, по сравнению с компиляцией и запуском проекта на одной и той же версии Scala." + icon: puzzle-piece + url: "core/binary-compatibility-of-scala-releases.html" + - title: Двоичная Совместимость для Авторов Библиотек + description: "Для любой продуктивной экосистемы важно иметь разнообразный и исчерпывающий набор библиотек. Хотя библиотеки Scala легко разрабатывать и распространять, хорошая разработка библиотек выходит за рамки простого написания кода и его публикации. В этом руководстве мы рассматриваем важную тему двоичной совместимости." + icon: puzzle-piece + url: "core/binary-compatibility-for-library-authors.html" + +- category: Инструменты + description: "Справочный материал по основным инструментам Scala, таким как Scala REPL и генерации Scaladoc." + overviews: + - title: Scala REPL + icon: terminal + url: "repl/overview.html" + description: | + Scala REPL это инструмент (scala) для обработки выражений в Scala. +

+ Он выполняет исходный скрипт, который в начале оборачивает в специальный блок, который затем компилирует и запускает. + - title: Scaladoc + url: "scaladoc/overview.html" + icon: book + description: "Scala API инструмента генерации документации." + subdocs: + - title: Обзор + url: "scaladoc/overview.html" + - title: Scaladoc для Авторов Библиотек + url: "scaladoc/for-library-authors.html" + - title: Использование интерфейса Scaladoc + url: "scaladoc/interface.html" + +- category: Компилятор + description: "Руководства и обзоры, охватывающие компилятор Scala: плагины компилятора, рефлексия и инструменты метапрограммирования такие как макросы." + overviews: + - title: Рефлексия + by: Heather Miller, Eugene Burmako и Philipp Haller + icon: binoculars + url: "reflection/overview.html" + description: Фреймворк рефлексии в Scala. + label-text: experimental + subdocs: + - title: Overview + url: "reflection/overview.html" + - title: Environment, Universes, and Mirrors + url: "reflection/environment-universes-mirrors.html" + - title: Symbols, Trees, and Types + url: "reflection/symbols-trees-types.html" + - title: Annotations, Names, Scopes, and More + url: "reflection/annotations-names-scopes.html" + - title: TypeTags and Manifests + url: "reflection/typetags-manifests.html" + - title: Thread Safety + url: "reflection/thread-safety.html" + - title: Changes in Scala 2.11 + url: "reflection/changelog211.html" + - title: Макросы + by: Eugene Burmako + icon: magic + url: "macros/usecases.html" + description: "Фреймворк метапрограммирования в Scala." + label-text: experimental + subdocs: + - title: Use Cases + url: "macros/usecases.html" + - title: Blackbox Vs Whitebox + url: "macros/blackbox-whitebox.html" + - title: Def Macros + url: "macros/overview.html" + - title: Quasiquotes + url: "quasiquotes/intro.html" + - title: Macro Bundles + url: "macros/bundles.html" + - title: Implicit Macros + url: "macros/implicits.html" + - title: Extractor Macros + url: "macros/extractors.html" + - title: Type Providers + url: "macros/typeproviders.html" + - title: Macro Annotations + url: "macros/annotations.html" + - title: Macro Paradise + url: "macros/paradise.html" + - title: Roadmap + url: "macros/roadmap.html" + - title: Changes in 2.11 + url: "macros/changelog211.html" + - title: Quasiquotes + by: Denys Shabalin + icon: quote-left + url: "quasiquotes/setup.html" + description: "Quasiquotes наиболее подходящий способ манипулирования синтаксическим деревом Scala." + label-text: experimental + subdocs: + - title: Dependencies and setup + url: "quasiquotes/setup.html" + - title: Introduction + url: "quasiquotes/intro.html" + - title: Lifting + url: "quasiquotes/lifting.html" + - title: Unlifting + url: "quasiquotes/unlifting.html" + - title: Hygiene + url: "quasiquotes/hygiene.html" + - title: Use cases + url: "quasiquotes/usecases.html" + - title: Syntax summary + url: "quasiquotes/syntax-summary.html" + - title: Expression details + url: "quasiquotes/expression-details.html" + - title: Type details + url: "quasiquotes/type-details.html" + - title: Pattern details + url: "quasiquotes/pattern-details.html" + - title: Definition and import details + url: "quasiquotes/definition-details.html" + - title: Terminology summary + url: "quasiquotes/terminology.html" + - title: Future prospects + url: "quasiquotes/future.html" + - title: Плагины Компилятора + by: Lex Spoon и Seth Tisue + icon: puzzle-piece + url: "plugins/index.html" + description: "Используя плагины можно настраивать и расширять компилятор Scala. В этом руководстве описываются возможности плагина и рассказывается о том, как создать простой плагин." + - title: Опции Компилятора + by: Сообщество + icon: cog + url: "compiler-options/index.html" + description: "Различные варианты управления тем, как scalac компилирует код." + + +- category: Наследие + description: "Руководство по функционалу, которые больше не соответствуют последним версиям Scala (2.12+)." + overviews: + - title: Scala коллекции с 2.8 по 2.12 + by: Martin Odersky + icon: sitemap + url: "collections/introduction.html" + description: "Scala's Collection Library." + subdocs: + - title: Introduction + url: "collections/introduction.html" + - title: Mutable and Immutable Collections + url: "collections/overview.html" + - title: Trait Traversable + url: "collections/trait-traversable.html" + - title: Trait Iterable + url: "collections/trait-iterable.html" + - title: The sequence traits Seq, IndexedSeq, and LinearSeq + url: "collections/seqs.html" + - title: Sets + url: "collections/sets.html" + - title: Maps + url: "collections/maps.html" + - title: Concrete Immutable Collection Classes + url: "collections/concrete-immutable-collection-classes.html" + - title: Concrete Mutable Collection Classes + url: "collections/concrete-mutable-collection-classes.html" + - title: Arrays + url: "collections/arrays.html" + - title: Strings + url: "collections/strings.html" + - title: Performance Characteristics + url: "collections/performance-characteristics.html" + - title: Equality + url: "collections/equality.html" + - title: Views + url: "collections/views.html" + - title: Iterators + url: "collections/iterators.html" + - title: Creating Collections From Scratch + url: "collections/creating-collections-from-scratch.html" + - title: Conversions Between Java and Scala Collections + url: "collections/conversions-between-java-and-scala-collections.html" + - title: Migrating from Scala 2.7 + url: "collections/migrating-from-scala-27.html" + - title: Архитектура Scala коллекций с 2.8 по 2.12 + icon: building + url: "core/architecture-of-scala-collections.html" + by: Martin Odersky и Lex Spoon + description: "На этих страницах описывается архитектура фреймворка коллекций до версии 2.12 . По сравнению с API Коллекции вы узнаете здесь больше о внутренней работе фреймворка." diff --git a/_data/overviews-uk.yml b/_data/overviews-uk.yml new file mode 100644 index 0000000000..02be500922 --- /dev/null +++ b/_data/overviews-uk.yml @@ -0,0 +1,348 @@ +- category: Стандартна бібліотека + description: "Посібники та огляди стандартної бібліотеки Scala." + overviews: + - title: Scala колекції + by: Martin Odersky та Julien Richard-Foy + icon: sitemap + url: "collections-2.13/introduction.html" + description: "Бібліотека колекцій Scala." + subdocs: + - title: Вступ + url: "collections-2.13/introduction.html" + - title: Змінювані та незмінювані колекції + url: "collections-2.13/overview.html" + - title: Трейт Iterable + url: "collections-2.13/trait-iterable.html" + - title: Трейти послідовностей. Seq, IndexedSeq та LinearSeq + url: "collections-2.13/seqs.html" + - title: Реалізація незмінюваних колекцій + url: "collections-2.13/concrete-immutable-collection-classes.html" + - title: Реалізація змінюваних колекцій + url: "collections-2.13/concrete-mutable-collection-classes.html" + - title: Масиви + url: "collections-2.13/arrays.html" + - title: Рядки + url: "collections-2.13/strings.html" + - title: Показники продуктивності + url: "collections-2.13/performance-characteristics.html" + - title: Рівність + url: "collections-2.13/equality.html" + - title: Відображення + url: "collections-2.13/views.html" + - title: Ітератори + url: "collections-2.13/iterators.html" + - title: Створення колекцій з нуля + url: "collections-2.13/creating-collections-from-scratch.html" + - title: Перетворення між колекціями Java та Scala + url: "collections-2.13/conversions-between-java-and-scala-collections.html" + - title: Міграція проєкту до колекцій Scala 2.13 + icon: sitemap + url: "core/collections-migration-213.html" + description: "Ця сторінка описує основні зміни в колекціях для користувачів, які переходять на Scala 2.13. Також, розглянуто варіанти побудови проєкти з перехресною сумісністю для Scala 2.11/2.12 і 2.13." + - title: Архітектура колекцій Scala + icon: sitemap + url: "core/architecture-of-scala-213-collections.html" + by: Julien Richard-Foy + description: "Ці сторінки описують архітектуру фреймворку колекцій, представленого в Scala 2.13. У порівнянні з Collections API ви дізнаєтеся більше про внутрішню роботу фреймворка." + - title: Реалізація користувацьких колекцій + icon: building + url: "core/custom-collections.html" + by: Martin Odersky, Lex Spoon та Julien Richard-Foy + description: "У цьому документі ви дізнаєтеся, як фреймворк колекцій допомагає вам визначати власні колекції за допомогою кількох рядків коду, повторно використовуючи переважну частину функцій колекції з фреймворку." + - title: Додавання спеціальних операцій до колекцій + icon: building + url: "core/custom-collection-operations.html" + by: Julien Richard-Foy + description: "У цьому посібнику показано, як писати перетворення, що застосовуються до всіх типів колекцій і повертати той самий тип колекції. Також, як писати операції, які параметризуються типом колекції." + +- category: Мова + description: "Посібники та огляди, що охоплюють функції на мові Scala." + overviews: + - title: Міграція зі Scala 2 на Scala 3 + by: Adrien Piquerez + icon: suitcase + root: "scala3/guides/" + url: "migration/compatibility-intro.html" + description: "Все, що потрібно знати про сумісність і міграцію на Scala 3." + - title: Макроси Scala 3 + by: Nicolas Stucki + icon: magic + root: "scala3/guides/" + url: "macros" + description: "Детальний підручник, який охоплює всі можливості, пов'язані з написанням макросів у Scala 3." + label-text: нове в Scala 3 + - title: Класи значень та універсальні трейти + by: Mark Harrah + description: "Класи значень – це новий механізм у Scala, що дозволяє уникнути виділення об'єктів під час виконання. Це досягається за допомогою визначення нових підкласів AnyVal." + icon: gem + url: "core/value-classes.html" + - title: Огляд TASTy + by: Alvin Alexander + icon: birthday-cake + label-text: нове в Scala 3 + root: "scala3/guides/" + url: "tasty-overview.html" + description: "Огляд формату TASTy, призначеного для користувачів мови Scala." + - title: Інтерполяція рядків + icon: dollar-sign + url: "core/string-interpolation.html" + description: > + Інтерполяція рядків дозволяє користувачам вбудовувати посилання на змінні безпосередньо в оброблені рядкові літерали. Ось приклад: + 
val name = "James"
+          println(s"Hello, $name")  // Hello, James
+ Літерал s"Hello, $name" є рядковим літералом, який буде додатково оброблено. Це означає, що компілятор виконує додаткову роботу над цим літералом. Оброблений рядковий літерал позначається набором символів, що передують ". Інтерполяція рядків була введена в SIP-11. + - title: Неявні класи + by: Josh Suereth + description: "Scala 2.10 представила нову функцію під назвою неявні класи. Неявний клас — це клас, позначений ключовим словом implicit. Це ключове слово робить основний конструктор класу доступним для неявних перетворень, коли клас знаходиться в області видимості." + url: "core/implicit-classes.html" + +- category: Створення бібліотек + description: "Посібники щодо розробки бібліотек з відкритим кодом для екосистеми Scala." + overviews: + - title: Посібник для авторів бібліотек + by: Julien Richard-Foy + icon: tasks + url: "contributors/index.html" + description: "Перелічує всі інструменти, які автори бібліотек мають налаштувати для публікації та документування своїх бібліотек." + +- category: Паралельне та конкурентне програмування + description: "Повні посібники, що охоплюють деякі бібліотеки Scala для паралельного та конкурентного програмування." + overviews: + - title: Future та Promise + by: Philipp Haller, Aleksandar Prokopec, Heather Miller, Viktor Klang, Roland Kuhn та Vojin Jovanovic + icon: tasks + url: "core/futures.html" + description: "Ф'ючери дають можливість міркувати про паралельне виконання багатьох операцій – ефективним і не блокуючим способом. Ф'ючер — це об’єкт-заповнювач для значення, яке може ще не існувати. Як правило, вартість Ф'ючеру надається одночасно і може згодом використовуватися. Складання одночасних завдань таким чином, як правило, призводить до швидшого, асинхронного, не блокувального паралельного коду." + - title: Паралельні колекції + by: Aleksandar Prokopec та Heather Miller + icon: rocket + url: "parallel-collections/overview.html" + description: "Бібліотека паралельних колекцій Scala." + subdocs: + - title: Огляд + url: "parallel-collections/overview.html" + - title: Реалізація паралельних колекцій + url: "parallel-collections/concrete-parallel-collections.html" + - title: Перетворення паралельних колекцій + url: "parallel-collections/conversions.html" + - title: Конкурентні Try + url: "parallel-collections/ctries.html" + - title: Архітектура бібліотеки паралельних колекцій + url: "parallel-collections/architecture.html" + - title: Створення користувацьких паралельних колекцій + url: "parallel-collections/custom-parallel-collections.html" + - title: Конфігурація паралельних колекцій + url: "parallel-collections/configuration.html" + - title: Вимірювання продуктивності + url: "parallel-collections/performance.html" + +- category: Сумісність + description: "Що з чим працює (чи ні)." + overviews: + - title: Сумісність версій JDK + description: "Які версії Scala працюють на яких версіях JDK" + icon: coffee + url: "jdk-compatibility/overview.html" + - title: Бінарна сумісність релізів Scala + description: "Якщо дві версії Scala бінарно сумісні, можна безпечно скомпілювати свій проєкт на одній версії Scala та зв'язати з іншою версією Scala під час виконання. Безпечне зв'язування під час виконання (тільки!) означає, що JVM не генерує (підклас) LinkageError під час виконання вашої програми у змішаному сценарії, припускаючи, що вона не виникає при компіляції та запуску в одній версії Scala. Конкретно це означає, що ви можете мати зовнішні залежності від вашого шляху до класу під час виконання, які використовують іншу версію Scala, ніж та, з якою ви компілюєте, за умови, що вони сумісні з бінарними файлами. Іншими словами, окрема компіляція в різних версіях, сумісних з бінарними файлами, не створює проблем у порівнянні з компіляцією та запуском всього в одній версії Scala." + icon: puzzle-piece + url: "core/binary-compatibility-of-scala-releases.html" + - title: Бінарна сумісність для авторів бібліотек + description: "Різноманітний і повний набір бібліотек важливий для будь-якої продуктивної екосистеми програмного забезпечення. Хоча розробляти та розповсюджувати бібліотеки Scala легко, добре авторство бібліотеки виходить за рамки простого написання коду та його публікації. У цьому посібнику ми розглянемо важливу тему бінарної сумісності." + icon: puzzle-piece + url: "core/binary-compatibility-for-library-authors.html" + +- category: Інструменти + description: "Довідковий матеріал про основні інструменти Scala, такі як покоління Scala REPL і Scaladoc." + overviews: + - title: Scala 2 REPL + icon: terminal + url: "repl/overview.html" + description: | + Scala REPL це інструмент (scala) для виконання виразів в Scala. +

+ Команда scala виконає скрипт шляхом обгортання його в шаблон, а потім компіляції та виконання отриманої програми + - title: Scaladoc для Scala 3 + by: Krzysztof Romanowski, Aleksander Boruch-Gruszecki, Andrzej Ratajczak, Kacper Korban, Filip Zybała + icon: book + root: "scala3/guides/" + url: "scaladoc" + label-text: оновлено + description: "Оновлення в Scala 3 для інструменту генерації документації API." + - title: Scaladoc + url: "scaladoc/overview.html" + icon: book + description: "Інструмент Scala для генерації документації для API." + subdocs: + - title: Огляд + url: "scaladoc/overview.html" + - title: Scaladoc для авторів бібліотек + url: "scaladoc/for-library-authors.html" + - title: Використання інтерфейсу Scaladoc + url: "scaladoc/interface.html" + +- category: Компілятор + description: "Посібники та огляди компілятора Scala: плагіни компілятора, інструменти рефлексії та метапрограмування, такі як макроси." + overviews: + - title: "Посібник з внесення змін у Scala 3" + by: Jamie Thompson, Anatolii Kmetiuk + icon: cogs + root: "scala3/guides/" + url: "contribution/contribution-intro.html" + description: "Посібник з компілятора Scala 3 та вирішення проблем." + - title: Рефлексія в Scala 2 + by: Heather Miller, Eugene Burmako та Philipp Haller + icon: binoculars + url: "reflection/overview.html" + description: Фреймворк Scala для рефлексії під час виконання/компіляції. + label-text: відсутнє в Scala 3 + subdocs: + - title: Огляд + url: "reflection/overview.html" + - title: Environment, Universe та Mirror + url: "reflection/environment-universes-mirrors.html" + - title: Symbol, Tree та Type + url: "reflection/symbols-trees-types.html" + - title: Annotation, Name, Scope та More + url: "reflection/annotations-names-scopes.html" + - title: TypeTag та Manifest + url: "reflection/typetags-manifests.html" + - title: Безпека потоків + url: "reflection/thread-safety.html" + - title: Зміни в Scala 2.11 + url: "reflection/changelog211.html" + - title: Макроси в Scala 2 + by: Eugene Burmako + icon: magic + url: "macros/usecases.html" + description: "Фреймворк метапрограмування Scala." + label-text: відсутнє в Scala 3 + subdocs: + - title: Випадки використання + url: "macros/usecases.html" + - title: Blackbox проти Whitebox + url: "macros/blackbox-whitebox.html" + - title: Макроси Def + url: "macros/overview.html" + - title: Квазіцитати + url: "quasiquotes/intro.html" + - title: Пакети макросів + url: "macros/bundles.html" + - title: Неявні макроси + url: "macros/implicits.html" + - title: Макроси-екстрактори + url: "macros/extractors.html" + - title: Провайдери типів + url: "macros/typeproviders.html" + - title: Анотації макросів + url: "macros/annotations.html" + - title: Макрос Paradise + url: "macros/paradise.html" + - title: Дорожня карта + url: "macros/roadmap.html" + - title: Зміни в 2.11 + url: "macros/changelog211.html" + - title: Квазіцитати в Scala 2 + by: Denys Shabalin + icon: quote-left + url: "quasiquotes/setup.html" + description: "Квазіцитати — це зручний спосіб маніпулювати синтаксичними деревами Scala." + label-text: відсутнє в Scala 3 + subdocs: + - title: Залежності та налаштування + url: "quasiquotes/setup.html" + - title: Вступ + url: "quasiquotes/intro.html" + - title: Підіймання + url: "quasiquotes/lifting.html" + - title: Опускання + url: "quasiquotes/unlifting.html" + - title: Гігієна + url: "quasiquotes/hygiene.html" + - title: Випадки використання + url: "quasiquotes/usecases.html" + - title: Резюме синтаксису + url: "quasiquotes/syntax-summary.html" + - title: Деталі виразів + url: "quasiquotes/expression-details.html" + - title: Деталі типів + url: "quasiquotes/type-details.html" + - title: Деталі патернів + url: "quasiquotes/pattern-details.html" + - title: Деталі визначення та імпорту + url: "quasiquotes/definition-details.html" + - title: Резюме термінології + url: "quasiquotes/terminology.html" + - title: Майбутні перспективи + url: "quasiquotes/future.html" + - title: Плагіни компілятора + by: Lex Spoon та Seth Tisue + icon: puzzle-piece + url: "plugins/index.html" + description: "Плагіни компілятора дозволяють налаштовувати та розширювати компілятор Scala. У цьому підручнику описується функція плагіну та пояснюється, як створити простий плагін." + - title: Параметри компілятора + by: Community + icon: cog + url: "compiler-options/index.html" + description: "Різні параметри того як scalac компілює ваш код." + - title: Форматування помилок + by: Torsten Schmits + icon: cog + url: "compiler-options/errors.html" + description: "Новий механізм для більш зручних повідомлень про помилки, друку ланцюжків залежних неявних параметрів та кольорових відмінностей знайдених/потрібних типів." + - title: Оптимізатор + by: Lukas Rytz та Andrew Marki + icon: cog + url: "compiler-options/optimizer.html" + description: "Компілятор може виконувати різні оптимізації." + +- category: Спадщина (legacy) + description: "Посібники, що охоплюють функції, які більше не стосуються останніх версій Scala (2.12+)." + overviews: + - title: Колекції Scala з 2.8 до 2.12 + by: Martin Odersky + icon: sitemap + url: "collections/introduction.html" + description: "Бібліотека колекцій Scala." + subdocs: + - title: Вступ + url: "collections/introduction.html" + - title: Змінювані та незмінювані колекції + url: "collections/overview.html" + - title: Трейт Traversable + url: "collections/trait-traversable.html" + - title: Трейт Iterable + url: "collections/trait-iterable.html" + - title: Трейти послідовностей. Seq, IndexedSeq та LinearSeq + url: "collections/seqs.html" + - title: Множини + url: "collections/sets.html" + - title: Асоціативні масиви + url: "collections/maps.html" + - title: Реалізація незмінюваних колекцій + url: "collections/concrete-immutable-collection-classes.html" + - title: Реалізація змінюваних колекцій + url: "collections/concrete-mutable-collection-classes.html" + - title: Масиви + url: "collections/arrays.html" + - title: Рядки + url: "collections/strings.html" + - title: Показники продуктивності + url: "collections/performance-characteristics.html" + - title: Рівність + url: "collections/equality.html" + - title: Відображення + url: "collections/views.html" + - title: Ітератори + url: "collections/iterators.html" + - title: Створення колекцій з нуля + url: "collections/creating-collections-from-scratch.html" + - title: Перетворення між колекціями Java та Scala + url: "collections/conversions-between-java-and-scala-collections.html" + - title: Міграція з версії Scala 2.7 + url: "collections/migrating-from-scala-27.html" + - title: Архітектура колекцій Scala з 2.8 до 2.12 + icon: building + url: "core/architecture-of-scala-collections.html" + by: Martin Odersky та Lex Spoon + description: "На цих сторінках детально описується архітектура фреймворку колекцій Scala. У порівнянні з Collections API ви дізнаєтеся більше про внутрішню роботу фреймворку. Ви також дізнаєтеся, як ця архітектура допомагає вам визначати власні колекції за допомогою кількох рядків коду, повторно використовуючи переважну частину функцій колекції з фреймворку." diff --git a/_data/overviews-zh-cn.yml b/_data/overviews-zh-cn.yml new file mode 100644 index 0000000000..1c48218eef --- /dev/null +++ b/_data/overviews-zh-cn.yml @@ -0,0 +1,312 @@ +- category: 标准库 + description: "涵盖 Scala 标准库的参考与概览" + overviews: + - title: Scala 容器 + by: Martin Odersky and Julien Richard-Foy + icon: sitemap + url: "collections-2.13/introduction.html" + description: "Scala 的容器库" + subdocs: + - title: 简介 + url: "collections-2.13/introduction.html" + - title: 可变与不可变容器 + url: "collections-2.13/overview.html" + - title: Iterable 特质 + url: "collections-2.13/trait-iterable.html" + - title: 序列特质 Seq, IndexedSeq, 和 LinearSeq + url: "collections-2.13/seqs.html" + - title: 具体不可变容器类 + url: "collections-2.13/concrete-immutable-collection-classes.html" + - title: 具体可变容器类 + url: "collections-2.13/concrete-mutable-collection-classes.html" + - title: 数组 + url: "collections-2.13/arrays.html" + - title: 字符串 + url: "collections-2.13/strings.html" + - title: 性能特点 + url: "collections-2.13/performance-characteristics.html" + - title: 相等性 + url: "collections-2.13/equality.html" + - title: 视图 + url: "collections-2.13/views.html" + - title: 迭代器 + url: "collections-2.13/iterators.html" + - title: 从头开始创建容器 + url: "collections-2.13/creating-collections-from-scratch.html" + - title: Java 与 Scala 间的容器转换 + url: "collections-2.13/conversions-between-java-and-scala-collections.html" + - title: 迁移项目容器至 Scala 2.13 的容器 + icon: sitemap + url: "core/collections-migration-213.html" + description: "本篇向欲迁移至 Scala 2.13 的容器用户介绍了主要变更并展示了如何通过 Scala 2.11，2.12 和 2.13 进行交叉编译" + - title: Scala 容器架构 + icon: sitemap + url: "core/architecture-of-scala-213-collections.html" + by: Julien Richard-Foy + description: "这几篇介绍了引进到 Scala 2.13 中的容器框架的架构，对照容器API就能知晓更多框架内部工作机制" + - title: 实现定制容器 + icon: building + url: "core/custom-collections.html" + by: Martin Odersky, Lex Spoon and Julien Richard-Foy + description: "从本篇中你会了解到如何利用容器框架通过几行代码来定义自己的容器，来重用来自框架的绝大部分容器功能。" + - title: 新增定制的容器操作 + icon: building + url: "core/custom-collection-operations.html" + by: Julien Richard-Foy + description: "本篇展示了如何定制可应用于任意容器类型并返回相同类型的操作，以及如何定制带有欲编译容器类型参数的操作" + +- category: 语言 + description: "涵盖 Scala 语言特性的参考与概览" + overviews: + - title: 字符串内插 + icon: dollar-sign + url: "core/string-interpolation.html" + description: > + 字符串内插允许用户在字符串字面插值中直接嵌入变量引用。这里有个例子： + String Interpolation allows users to embed variable references directly in processed string literals. Here’s an example: + 
val name = "James"
+          println(s"Hello, $name")  // Hello, James
+ 上例中，字面值 s"Hello, $name" 是个字符串字面插值，意味着编译器会对该字面值做些额外工作。字符串字面插值通过双引号前增加前导字符来表示。字符串插值由 SIP-11 引入，其中包含了所有实现细节。 + - title: 隐式类 + by: Josh Suereth + description: "Scala 2.10 中引入了一个新特性叫隐式类。隐式类是一个由 implicit 关键字标记的类，当类在作用域内时该关键字使得类的主构造器可用于隐式转换。" + url: "core/implicit-classes.html" + - title: 值类和通用特质 + by: Mark Harrah + description: "值类是 Scala 中摒弃创建运行时对象的一种新机制，可通过定义 AnyVal 的子类来实现" + icon: gem + url: "core/value-classes.html" + +- category: 创作库 + description: "参考如何为 Scala 生态贡献开源库" + overviews: + - title: 库作者参考 + by: "Julien Richard-Foy" + icon: tasks + url: "contributors/index.html" + description: "列出库作者为库发布及库文档所需设置的所有工具" + +- category: 并行和并发编程 + description: "涵盖 Scala 并行和并发编程库的完全指南" + overviews: + - title: Futures 和 Promises + by: "Philipp Haller, Aleksandar Prokopec, Heather Miller, Viktor Klang, Roland Kuhn, and Vojin Jovanovic" + icon: tasks + url: "core/futures.html" + description: "Futures 提供了一种推导并行执行多个操作的方式，即高效非阻塞的方式。一个 Future 就是一个可能还不存在的值的占位对象。通常来讲，Future 是并发赋值但顺序使用。这种方式来组织并发任务结果常常是更快的异步的非阻塞的并行代码。" + - title: 并行容器 + by: Aleksandar Prokopec and Heather Miller + icon: rocket + url: "parallel-collections/overview.html" + description: "Scala 并行容器库" + subdocs: + - title: 概览 + url: "parallel-collections/overview.html" + - title: 具体的并行容器类 + url: "parallel-collections/concrete-parallel-collections.html" + - title: 并行容器转换 + url: "parallel-collections/conversions.html" + - title: 并发字典树 + url: "parallel-collections/ctries.html" + - title: 并行容器库架构 + url: "parallel-collections/architecture.html" + - title: 创建定制的并行容器 + url: "parallel-collections/custom-parallel-collections.html" + - title: 配置并行容器 + url: "parallel-collections/configuration.html" + - title: 衡量性能 + url: "parallel-collections/performance.html" + +- category: 兼容性 + description: "各种（非）兼容性" + overviews: + - title: JDK 版本兼容性 + description: "Scala版本与JDK版本的兼容性" + icon: coffee + url: "jdk-compatibility/overview.html" + - title: Scala 各版本的二进制兼容性 + description: "当两个 Scala 版本是二进制兼容时，在一个 Scala 上编译的项目连接在另一个 Scala 的运行时将是安全的。安全的运行时连接（仅！）意味着 JVM 在这种混合场景下运行你的程序没有抛出连接错误（及其子类），且假使编译和运行在单一版本的 Scala 上没问题的情况下。具体点说，就是可能在你的运行时类路径中有外部依赖，这些依赖使用了跟你正在编译用到的不同版本的 Scala，只要他们是二进制兼容的。换句话说，在二进制兼容的不同版本上分开编译相比于在同一个版本上编译和运行所有东西不会带来问题。" + icon: puzzle-piece + url: "core/binary-compatibility-of-scala-releases.html" + - title: 针对库作者的二进制兼容性 + description: "一个多元综合的库集合对于任何软件生态来说都是重要的。尽管易于开发和分发 Scala 库，好的库管理者却不仅仅是写代码和发布它。此篇中覆盖了二进制兼容性的重要话题。" + icon: puzzle-piece + url: "core/binary-compatibility-for-library-authors.html" + +- category: "工具" + description: "关于核心 Scala 工具的参考材料，如 Scala REPL 和 Scaladoc 生成" + overviews: + - title: Scala REPL + icon: terminal + url: "repl/overview.html" + description: | + Scala REPL 是一个对 Scala 表达式求值的工具 (scala) +

+ scala 命令会通过包装源脚本到一模板中来执行它，然后编译并执行结果程序 + - title: Scaladoc + url: "scaladoc/overview.html" + icon: book + description: "Scala 的 API 文档生成工具" + subdocs: + - title: 概览 + url: "scaladoc/overview.html" + - title: 针对库作者的 Scaladoc + url: "scaladoc/for-library-authors.html" + - title: 使用 Scaladoc 接口 + url: "scaladoc/interface.html" + +- category: 编译器 + description: "涵盖 Scala 编译器的参考和概览：编译器插件，反射，以及元编程工具比如宏" + overviews: + - title: 反射 + by: Heather Miller, Eugene Burmako, and Philipp Haller + icon: binoculars + url: "reflection/overview.html" + description: Scala 的运行时和编译期的反射框架 + label-text: 实验 + subdocs: + - title: 概览 + url: "reflection/overview.html" + - title: 环境，通用和镜像（Environment, Universes, and Mirrors） + url: "reflection/environment-universes-mirrors.html" + - title: 符号，树和类型（Symbols, Trees, and Types） + url: "reflection/symbols-trees-types.html" + - title: 标号，名称，作用域及其他（Annotations, Names, Scopes, and More） + url: "reflection/annotations-names-scopes.html" + - title: TypeTags 和 Manifests + url: "reflection/typetags-manifests.html" + - title: 线程安全 + url: "reflection/thread-safety.html" + - title: Scala 2.11 中的变化 + url: "reflection/changelog211.html" + - title: 宏 + by: Eugene Burmako + icon: magic + url: "macros/usecases.html" + description: "Scala 的元编程框架" + label-text: 实验 + subdocs: + - title: 用例 + url: "macros/usecases.html" + - title: 黑盒与白盒 + url: "macros/blackbox-whitebox.html" + - title: Def 宏 + url: "macros/overview.html" + - title: 拟引号（Quasiquotes） + url: "quasiquotes/intro.html" + - title: 宏绑定 + url: "macros/bundles.html" + - title: 隐式宏 + url: "macros/implicits.html" + - title: Extractor 宏 + url: "macros/extractors.html" + - title: 类型 Providers + url: "macros/typeproviders.html" + - title: 宏标号 + url: "macros/annotations.html" + - title: 宏乐园 + url: "macros/paradise.html" + - title: 路线图 + url: "macros/roadmap.html" + - title: 2.11 中的变化 + url: "macros/changelog211.html" + - title: 拟引号 + by: Denys Shabalin + icon: quote-left + url: "quasiquotes/setup.html" + description: "拟引号是操作 Scala 语法树的便捷方式" + label-text: 实验 + subdocs: + - title: 依赖和设置 + url: "quasiquotes/setup.html" + - title: 简介 + url: "quasiquotes/intro.html" + - title: 提升（Lifting） + url: "quasiquotes/lifting.html" + - title: 拉降（Unlifting） + url: "quasiquotes/unlifting.html" + - title: 卫生（Hygiene） + url: "quasiquotes/hygiene.html" + - title: 用例 + url: "quasiquotes/usecases.html" + - title: 语法总结 + url: "quasiquotes/syntax-summary.html" + - title: 表达式细节 + url: "quasiquotes/expression-details.html" + - title: 类型细节 + url: "quasiquotes/type-details.html" + - title: 模式细节 + url: "quasiquotes/pattern-details.html" + - title: 定义和引用细节 + url: "quasiquotes/definition-details.html" + - title: 属于总结 + url: "quasiquotes/terminology.html" + - title: 未来展望 + url: "quasiquotes/future.html" + - title: 编译器插件 + by: Lex Spoon and Seth Tisue + icon: puzzle-piece + url: "plugins/index.html" + description: "编译器插件允许定制和扩展 Scala 编译器。本篇导引描述了插件设施并带你领略如何创作一个简单插件" + - title: 编译器选项 + by: Community + icon: cog + url: "compiler-options/index.html" + description: "控制 scalac 如何编译代码的各种选项" + - title: 错误格式 + by: Torsten Schmits + icon: cog + url: "compiler-options/errors.html" + description: "一个新的用户友好的错误消息引擎，可以打印依赖的隐式链，颜色区分找到的和所需的类型差异" + + +- category: 遗留问题 + description: "涵盖一些与最近的 Scala 版本（2.12+）不再相关的特性的参考" + overviews: + - title: Scala 2.8 到 2.12 的容器 + by: Martin Odersky + icon: sitemap + url: "collections/introduction.html" + description: "Scala 的容器库" + subdocs: + - title: 简介 + url: "collections/introduction.html" + - title: 可变和不可变容器 + url: "collections/overview.html" + - title: Traversable 特质 + url: "collections/trait-traversable.html" + - title: Iterable 特质 + url: "collections/trait-iterable.html" + - title: 序列特质 Seq, IndexedSeq, 和 LinearSeq + url: "collections/seqs.html" + - title: 集合（Sets） + url: "collections/sets.html" + - title: 映射（Maps） + url: "collections/maps.html" + - title: 具体的不可变容器类 + url: "collections/concrete-immutable-collection-classes.html" + - title: 具体的可变容器类 + url: "collections/concrete-mutable-collection-classes.html" + - title: 数组 + url: "collections/arrays.html" + - title: 字符串 + url: "collections/strings.html" + - title: 性能特点 + url: "collections/performance-characteristics.html" + - title: 相等性 + url: "collections/equality.html" + - title: 视图 + url: "collections/views.html" + - title: 迭代器 + url: "collections/iterators.html" + - title: 从头开始创建容器 + url: "collections/creating-collections-from-scratch.html" + - title: Java 和 Scala 间容器转换 + url: "collections/conversions-between-java-and-scala-collections.html" + - title: 从 Scala 2.7 迁移 + url: "collections/migrating-from-scala-27.html" + - title: Scala 2.8 到 2.12 的容器架构 + icon: building + url: "core/architecture-of-scala-collections.html" + by: Martin Odersky and Lex Spoon + description: "本篇细致地描述了 Scala 容器框架的架构，对比容器 API 你会发现更多框架的内部工作机制。你也会学到该架构如何帮你通过几行代码定义自己的容器，来重用来自框架的绝大部分容器功能。" diff --git a/_data/overviews.yml b/_data/overviews.yml index 784d7291e3..5756db5e3e 100644 --- a/_data/overviews.yml +++ b/_data/overviews.yml @@ -1,63 +1,91 @@ - - category: Standard Library description: "Guides and overviews covering the Scala standard library." overviews: - - title: Collections - by: Martin Odersky + - title: Scala Collections + by: Martin Odersky and Julien Richard-Foy icon: sitemap - url: "collections/introduction.html" + url: "collections-2.13/introduction.html" description: "Scala's Collection Library." subdocs: - title: Introduction - url: "collections/introduction.html" + url: "collections-2.13/introduction.html" - title: Mutable and Immutable Collections - url: "collections/overview.html" - - title: Trait Traversable - url: "collections/trait-traversable.html" + url: "collections-2.13/overview.html" - title: Trait Iterable - url: "collections/trait-iterable.html" + url: "collections-2.13/trait-iterable.html" - title: The sequence traits Seq, IndexedSeq, and LinearSeq + url: "collections-2.13/seqs.html" - title: Concrete Immutable Collection Classes - url: "collections/concrete-immutable-collection-classes.html" + url: "collections-2.13/concrete-immutable-collection-classes.html" - title: Concrete Mutable Collection Classes - url: "collections/concrete-mutable-collection-classes.html" + url: "collections-2.13/concrete-mutable-collection-classes.html" - title: Arrays - url: "collections/arrays.html" + url: "collections-2.13/arrays.html" - title: Strings - url: "collections/strings.html" + url: "collections-2.13/strings.html" - title: Performance Characteristics - url: "collections/performance-characteristics.html" + url: "collections-2.13/performance-characteristics.html" - title: Equality - url: "collections/equality.html" + url: "collections-2.13/equality.html" - title: Views - url: "collections/views.html" + url: "collections-2.13/views.html" - title: Iterators - url: "collections/iterators.html" + url: "collections-2.13/iterators.html" - title: Creating Collections From Scratch - url: "collections/creating-collections-from-scratch.html" + url: "collections-2.13/creating-collections-from-scratch.html" - title: Conversions Between Java and Scala Collections - url: "collections/conversions-between-java-and-scala-collections.html" + url: "collections-2.13/conversions-between-java-and-scala-collections.html" + - title: Migrating a Project to Scala 2.13's Collections + icon: sitemap + url: "core/collections-migration-213.html" + description: "This page describes the main changes for collection users that migrate to Scala + 2.13 and shows how to cross-build projects with Scala 2.11 / 2.12 and 2.13." - title: The Architecture of Scala Collections - icon: building - url: "core/architecture-of-scala-collections.html" - by: Martin Odersky and Lex Spoon - description: "These pages describe the architecture of the Scala collections framework in detail. Compared to the Collections API you will find out more about the internal workings of the framework. You will also learn how this architecture helps you define your own collections in a few lines of code, while reusing the overwhelming part of collection functionality from the framework." - - title: The Architecture of Scala 2.13’s Collections icon: sitemap url: "core/architecture-of-scala-213-collections.html" by: Julien Richard-Foy description: "These pages describe the architecture of the collections framework introduced in Scala 2.13. Compared to the Collections API you will find out more about the internal workings of the framework." - - title: Custom Collection Types + - title: Implementing Custom Collections icon: building url: "core/custom-collections.html" by: Martin Odersky, Lex Spoon and Julien Richard-Foy description: "In this document you will learn how the collections framework helps you define your own collections in a few lines of code, while reusing the overwhelming part of collection functionality from the framework." + - title: Adding Custom Collection Operations + icon: building + url: "core/custom-collection-operations.html" + by: Julien Richard-Foy + description: "This guide shows how to write operations that can be applied to any collection type and return the same collection type, and how to write operations that can be parameterized by the type of collection to build." - category: Language description: "Guides and overviews covering features in the Scala language." overviews: + - title: "Migration from Scala 2 to Scala 3" + by: Adrien Piquerez + icon: suitcase + root: "scala3/guides/" + url: "migration/compatibility-intro.html" + description: "Everything you need to know about compatibility and migration to Scala 3." + - title: Scala 3 Macros + by: Nicolas Stucki + icon: magic + root: "scala3/guides/" + url: "macros" + description: "A detailed tutorial to cover all the features involved in writing macros in Scala 3." + label-text: new in Scala 3 + - title: Value Classes and Universal Traits + by: Mark Harrah + description: "Value classes are a new mechanism in Scala to avoid allocating runtime objects. This is accomplished through the definition of new AnyVal subclasses." + icon: gem + url: "core/value-classes.html" + - title: An Overview of TASTy + by: Alvin Alexander + icon: birthday-cake + label-text: new in Scala 3 + root: "scala3/guides/" + url: "tasty-overview.html" + description: "An overview over the TASTy format aimed at end-users of the Scala language." - title: String Interpolation - icon: usd + icon: dollar-sign url: "core/string-interpolation.html" description: > String Interpolation allows users to embed variable references directly in processed string literals. Here’s an example: @@ -68,11 +96,24 @@ by: Josh Suereth description: "Scala 2.10 introduced a new feature called implicit classes. An implicit class is a class marked with the implicit keyword. This keyword makes the class’ primary constructor available for implicit conversions when the class is in scope." url: "core/implicit-classes.html" - - title: Value Classes and Universal Traits - by: Mark Harrah - description: "Value classes are a new mechanism in Scala to avoid allocating runtime objects. This is accomplished through the definition of new AnyVal subclasses." - icon: diamond - url: "core/value-classes.html" + - title: The Scala Book + by: Alvin Alexander + icon: book + label-color: "#899295" + label-text: archived + url: "scala-book/introduction.html" + description: > + A light introduction to the Scala language, focused on Scala 2. + Now updated for Scala 3, we are in the process of merging the two. + +- category: Authoring Libraries + description: "Guides for contributing open source libraries to the Scala ecosystem." + overviews: + - title: Library Author Guide + by: "Julien Richard-Foy" + icon: tasks + url: "contributors/index.html" + description: "Lists all the tools that library authors should setup to publish and document their libraries." - category: Parallel and Concurrent Programming description: "Complete guides covering some of Scala's libraries for parallel and concurrent programming." @@ -120,17 +161,27 @@ description: "A diverse and comprehensive set of libraries is important to any productive software ecosystem. While it is easy to develop and distribute Scala libraries, good library authorship goes beyond just writing code and publishing it. In this guide, we cover the important topic of Binary Compatibility." icon: puzzle-piece url: "core/binary-compatibility-for-library-authors.html" + - title: Nightly Versions of Scala + description: "We regularly publish 'nightlies' of both Scala 3 and Scala 2 so that users can preview and test the contents of upcoming releases. Here's how to find and use these versions." + url: "core/nightlies.html" - category: "Tools" description: "Reference material on core Scala tools like the Scala REPL and Scaladoc generation." overviews: - - title: Scala REPL + - title: Scala 2 REPL icon: terminal url: "repl/overview.html" description: | The Scala REPL is a tool (scala) for evaluating expressions in Scala.

The scala command will execute a source script by wrapping it in a template and then compiling and executing the resulting program + - title: Scaladoc For Scala 3 + by: Krzysztof Romanowski, Aleksander Boruch-Gruszecki, Andrzej Ratajczak, Kacper Korban, Filip Zybała + icon: book + root: "scala3/guides/" + url: "scaladoc" + description: "Updates in Scala 3 to Scala’s API documentation generation tool." + label-text: updated - title: Scaladoc url: "scaladoc/overview.html" icon: book @@ -146,12 +197,12 @@ - category: Compiler description: "Guides and overviews covering the Scala compiler: compiler plugins, reflection, and metaprogramming tools such as macros." overviews: - - title: Reflection + - title: Scala 2 Reflection by: Heather Miller, Eugene Burmako, and Philipp Haller icon: binoculars url: "reflection/overview.html" description: Scala's runtime/compile-time reflection framework. - label-text: experimental + label-text: removed in Scala 3 subdocs: - title: Overview url: "reflection/overview.html" @@ -167,12 +218,12 @@ url: "reflection/thread-safety.html" - title: Changes in Scala 2.11 url: "reflection/changelog211.html" - - title: Macros + - title: Scala 2 Macros by: Eugene Burmako icon: magic url: "macros/usecases.html" description: "Scala's metaprogramming framework." - label-text: experimental + label-text: removed in Scala 3 subdocs: - title: Use Cases url: "macros/usecases.html" @@ -198,12 +249,12 @@ url: "macros/roadmap.html" - title: Changes in 2.11 url: "macros/changelog211.html" - - title: Quasiquotes + - title: Quasiquotes in Scala 2 by: Denys Shabalin icon: quote-left url: "quasiquotes/setup.html" description: "Quasiquotes are a convenient way to manipulate Scala syntax trees." - label-text: experimental + label-text: removed in Scala 3 subdocs: - title: Dependencies and setup url: "quasiquotes/setup.html" @@ -231,30 +282,74 @@ url: "quasiquotes/terminology.html" - title: Future prospects url: "quasiquotes/future.html" - - title: Compiler Plugins + - title: Scala 2 Compiler Plugins by: Lex Spoon and Seth Tisue icon: puzzle-piece url: "plugins/index.html" description: "Compiler plugins permit customizing and extending the Scala compiler. This tutorial describes the plugin facility and walks you through how to create a simple plugin." - - title: Compiler Options + - title: Scala 2 Compiler Options by: Community icon: cog url: "compiler-options/index.html" description: "Various options to control how scalac compiles your code." - + - title: Error Formatting + by: Torsten Schmits + icon: cog + url: "compiler-options/errors.html" + description: "A new engine for more user-friendly error messages, printing chains of dependent implicits and colored found/required type diffs." + - title: Optimizer + by: Lukas Rytz and Andrew Marki + icon: cog + url: "compiler-options/optimizer.html" + description: "The compiler can perform various optimizations." - category: Legacy - description: "Guides covering features no longer relevant to recent Scala versions (2.11+)." + description: "Guides covering features no longer relevant to recent Scala versions (2.12+)." overviews: - - title: The Scala Actors Migration Guide - by: Vojin Jovanovic and Philipp Haller - icon: truck - url: "core/actors-migration-guide.html" - description: "To ease the migration from Scala Actors to Akka we have provided the Actor Migration Kit (AMK). The AMK consists of an extension to Scala Actors which is enabled by including the scala-actors-migration.jar on a project’s classpath. In addition, Akka 2.1 includes features, such as the ActorDSL singleton, which enable a simpler conversion of code using Scala Actors to Akka. The purpose of this document is to guide users through the migration process and explain how to use the AMK." - - title: The Scala Actors API - by: Philipp Haller and Stephen Tu - icon: users - url: "core/actors.html" - description: "This guide describes the API of the scala.actors package of Scala 2.8/2.9. The organization follows groups of types that logically belong together. The trait hierarchy is taken into account to structure the individual sections. The focus is on the run-time behavior of the various methods that these traits define, thereby complementing the existing Scaladoc-based API documentation." - label-color: "#899295" - label-text: deprecated + - title: Scala 2.8 to 2.12’s Collections + by: Martin Odersky + icon: sitemap + url: "collections/introduction.html" + description: "Scala's Collection Library." + subdocs: + - title: Introduction + url: "collections/introduction.html" + - title: Mutable and Immutable Collections + url: "collections/overview.html" + - title: Trait Traversable + url: "collections/trait-traversable.html" + - title: Trait Iterable + url: "collections/trait-iterable.html" + - title: The sequence traits Seq, IndexedSeq, and LinearSeq + url: "collections/seqs.html" + - title: Sets + url: "collections/sets.html" + - title: Maps + url: "collections/maps.html" + - title: Concrete Immutable Collection Classes + url: "collections/concrete-immutable-collection-classes.html" + - title: Concrete Mutable Collection Classes + url: "collections/concrete-mutable-collection-classes.html" + - title: Arrays + url: "collections/arrays.html" + - title: Strings + url: "collections/strings.html" + - title: Performance Characteristics + url: "collections/performance-characteristics.html" + - title: Equality + url: "collections/equality.html" + - title: Views + url: "collections/views.html" + - title: Iterators + url: "collections/iterators.html" + - title: Creating Collections From Scratch + url: "collections/creating-collections-from-scratch.html" + - title: Conversions Between Java and Scala Collections + url: "collections/conversions-between-java-and-scala-collections.html" + - title: Migrating from Scala 2.7 + url: "collections/migrating-from-scala-27.html" + - title: The Architecture of Scala 2.8 to 2.12’s Collections + icon: building + url: "core/architecture-of-scala-collections.html" + by: Martin Odersky and Lex Spoon + description: "These pages describe the architecture of the Scala collections framework in detail. Compared to the Collections API you will find out more about the internal workings of the framework. You will also learn how this architecture helps you define your own collections in a few lines of code, while reusing the overwhelming part of collection functionality from the framework." diff --git a/_data/setup-scala.yml b/_data/setup-scala.yml new file mode 100644 index 0000000000..cda4c2361b --- /dev/null +++ b/_data/setup-scala.yml @@ -0,0 +1,6 @@ +linux-x86-64: curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-linux.gz | gzip -d > cs && chmod +x cs && ./cs setup +linux-arm64: curl -fL https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-pc-linux.gz | gzip -d > cs && chmod +x cs && ./cs setup +macOS-x86-64: curl -fL https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-apple-darwin.gz | gzip -d > cs && chmod +x cs && (xattr -d com.apple.quarantine cs || true) && ./cs setup +macOS-arm64: curl -fL https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-apple-darwin.gz | gzip -d > cs && chmod +x cs && (xattr -d com.apple.quarantine cs || true) && ./cs setup +macOS-brew: brew install coursier && coursier setup +windows-link: https://github.com/coursier/coursier/releases/latest/download/cs-x86_64-pc-win32.zip diff --git a/_data/sip-data.yml b/_data/sip-data.yml index 6a6b19fe68..0a351b24da 100644 --- a/_data/sip-data.yml +++ b/_data/sip-data.yml @@ -1,27 +1,47 @@ +design: + color: "#839496" + text: "Design" + +implementation: + color: "#839496" + text: "Implementation" + +submitted: + color: "#2aa198" + text: "Submitted" + under-review: color: "#b58900" text: "Under Review" -pending: +vote-requested: color: "#b58900" - text: "Pending" - -dormant: - color: "#839496" - text: "Dormant" + text: "Vote Requested" -under-revision: - color: "#2aa198" - text: "Under Revision" +waiting-for-implementation: + color: "#b58900" + text: "Waiting for Implementation" accepted: color: "#859900" text: "Accepted" -complete: +shipped: color: "#859900" - text: "Complete" + text: "Shipped" rejected: color: "#dc322f" text: "Rejected" + +withdrawn: + color: "#839496" + text: "Withdrawn" + +accept: + color: "#859900" + text: "Accept" + +reject: + color: "#dc322f" + text: "Reject" diff --git a/_data/translations.yml b/_data/translations.yml index 3641a04203..80ab5afc1c 100644 --- a/_data/translations.yml +++ b/_data/translations.yml @@ -1,2 +1,2 @@ tour: - languages: [ba, es, ko, pt-br, pl, zh-cn, th] + languages: [ba, es, fr, ko, pt-br, pl, zh-cn, th, ru, ja] diff --git a/_de/tutorials/scala-for-java-programmers.md b/_de/tutorials/scala-for-java-programmers.md index 451cc0a940..9055d7caea 100644 --- a/_de/tutorials/scala-for-java-programmers.md +++ b/_de/tutorials/scala-for-java-programmers.md @@ -3,8 +3,6 @@ layout: singlepage-overview title: Ein Scala Tutorial für Java Programmierer partof: scala-for-java-programmers - -discourse: false language: de --- @@ -25,7 +23,7 @@ einfach ist, eignet es sich sehr gut, Scalas Funktionsweise zu demonstrieren, oh über die Sprache wissen muss. object HalloWelt { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { println("Hallo, Welt!") } } @@ -95,7 +93,7 @@ Klassen der Java-Pakete importieren: import java.text.DateFormat._ object FrenchDate { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val now = new Date val df = getDateInstance(LONG, Locale.FRANCE) println(df format now) @@ -147,24 +145,10 @@ der folgende exklusiv aus Methoden-Aufrufen, da es äquivalent zu folgendem Ausdruck ist, wie in vorhergehenden Abschnitt gezeigt wurde: - (1).+(((2).*(3))./(x)) + 1.+(2.*(3)./(x)) Dies bedeutet außerdem, dass `+`, `*`, etc. in Scala gültige Bezeichner sind. -Die Zahlen umschließenden Klammern der zweiten Variante sind notwendig, weil Scalas lexikalischer -Scanner eine Regel zur längsten Übereinstimmung der Token verwendet. Daher würde der folgende -Ausdruck: - - 1.+(2) - -in die Token `1.`, `+`, und `2` zerlegt werden. Der Grund für diese Zerlegung ist, dass `1.` eine -längere, gültige Übereinstimmung ist, als `1`. Daher würde das Token `1.` als das Literal `1.0` -interpretiert, also als Gleitkommazahl anstatt als Ganzzahl. Den Ausdruck als - - (1).+(2) - -zu schreiben, verhindert also, dass `1.` als Gleitkommazahl interpretiert wird. - ### Funktionen sind Objekte Vermutlich überraschender für Java-Programmierer ist, dass auch Funktionen in Scala Objekte sind. @@ -199,7 +183,7 @@ einmal pro Sekunde aus. println("Die Zeit vergeht wie im Flug.") } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(timeFlies) } } @@ -225,7 +209,7 @@ Variante des obigen Timer-Programmes verwendet eine anonyme Funktion anstatt der } } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(() => println("Die Zeit vergeht wie im Flug.")) } } @@ -272,7 +256,7 @@ Ein Problem der obigen Methoden `re` und `im` ist, dass man, um sie zu verwenden Klammerpaar hinter ihren Namen anhängen muss: object ComplexNumbers { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val c = new Complex(1.2, 3.4) println("imaginary part: " + c.im()) } @@ -449,7 +433,7 @@ noch aus. Zu diesem Zweck soll eine `main`-Methode dienen, die den Ausdruck `(x+ Beispiel verwendet: zuerst wird der Wert in der Umgebung `{ x -> 5, y -> 7 }` berechnet und darauf die beiden partiellen Ableitungen gebildet: - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) val env: Environment = { case "x" => 5 @@ -613,7 +597,7 @@ Um diese Referenz-Klasse zu verwenden, muss der generische Typ bei der Erzeugung angegeben werden. Für einen Ganzzahl-Container soll folgendes Beispiel dienen: object IntegerReference { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val cell = new Reference[Int] cell.set(13) println("Reference contains the half of " + (cell.get * 2)) diff --git a/_es/overviews/core/actors.md b/_es/overviews/core/actors.md deleted file mode 100644 index 8c74bcf92e..0000000000 --- a/_es/overviews/core/actors.md +++ /dev/null @@ -1,497 +0,0 @@ ---- -layout: singlepage-overview -title: API de actores en Scala - -partof: actors - -language: es - -discourse: false ---- - -**Philipp Haller and Stephen Tu** - -**Traducción e interpretación: Miguel Ángel Pastor Olivar** - -## Introducción - -La presente guía describe el API del paquete `scala.actors` de Scala 2.8/2.9. El documento se estructura en diferentes grupos lógicos. La jerarquía de "traits" es tenida en cuenta para llevar a cabo la estructuración de las secciones individuales. La atención se centra en el comportamiento exhibido en tiempo de ejecución por varios de los métodos presentes en los traits anteriores, complementando la documentación existente en el Scaladoc API. - -## Traits de actores: Reactor, ReplyReactor, y Actor - -### The Reactor trait - -`Reactor` es el padre de todos los traits relacionados con los actores. Heredando de este trait podremos definir actores con una funcionalidad básica de envío y recepción de mensajes. - -El comportamiento de un `Reactor` se define mediante la implementación de su método `act`. Este método es ejecutado una vez el `Reactor` haya sido iniciado mediante la invocación del método `start`, retornando el `Reactor`. El método `start`es *idempotente*, lo cual significa que la invocación del mismo sobre un actor que ya ha sido iniciado no surte ningún efecto. - -El trait `Reactor` tiene un parámetro de tipo `Msg` el cual determina el tipo de mensajes que un actor es capaz de recibir. - -La invocación del método `!` de un `Reactor` envía un mensaje al receptor. La operación de envío de un mensaje mediante el operador `!` es asíncrona por lo que el actor que envía el mensaje no se bloquea esperando a que el mensaje sea recibido sino que su ejecución continua de manera inmediata. Por ejemplo, `a ! msg` envia `msg` a `a`. Todos los actores disponen de un *buzón* encargado de regular los mensajes entrantes hasta que son procesados. - -El trait `Reactor` trait también define el método `forward`. Este método es heredado de `OutputChannel` y tiene el mismo efecto que el método `!`. Aquellos traits que hereden de `Reactor`, en particular el trait `ReplyActor`, sobreescriben este método para habilitar lo que comunmente se conocen como *"implicit reply destinations"* (ver a continuación) - -Un `Reactor` recibe mensajes utilizando el método `react`. Este método espera un argumento de tipo `PartialFunction[Msg, Unit]` el cual define cómo los mensajes de tipo `Msg` son tratados una vez llegan al buzón de un actor. En el siguiente ejemplo, el actor espera recibir la cadena "Hello", para posteriomente imprimir un saludo: - - react { - case "Hello" => println("Hi there") - } - -La invocación del método `react` nunca retorna. Por tanto, cualquier código que deba ejecutarse tras la recepción de un mensaje deberá ser incluido dentro de la función parcial pasada al método `react`. Por ejemplo, dos mensajes pueden ser recibidos secuencialmente mediante la anidación de dos llamadas a `react`: - - react { - case Get(from) => - react { - case Put(x) => from ! x - } - } - -El trait `Reactor` también ofrece una serie de estructuras de control que facilitan la programación utilizando el mecanismo de `react`. - -#### Terminación y estados de ejecución - -La ejecución de un `Reactor` finaliza cuando el cuerpo del método `act` ha sido completado. Un `Reactor` también pueden terminarse a si mismo de manera explícita mediante el uso del método `exit`. El tipo de retorno de `exit` es `Nothing`, dado que `exit` siempre dispara una excepción. Esta excepción únicamente se utiliza de manera interna y nunca debería ser capturada. - -Un `Reactor` finalizado pueden ser reiniciado mediante la invocación de su método `restart`. La invocación del método anterior sobre un `Reactor` que no ha terminado su ejecución lanza una excepción de tipo `IllegalStateException`. El reinicio de un actor que ya ha terminado provoca que el método `act` se ejecute nuevamente. - -El tipo `Reactor` define el método `getState`, el cual retorna, como un miembro de la enumeración `Actor.State`, el estado actual de la ejecución del actor. Un actor que todavía no ha sido iniciado se encuentra en el estado `Actor.State.New`. Si el actor se está ejecutando pero no está esperando por ningún mensaje su estado será `Actor.State.Runnable`. En caso de que el actor haya sido suspendido mientras espera por un mensaje estará en el estado `Actor.State.Suspended`. Por último, un actor ya terminado se encontrará en el estado `Actor.State.Terminated`. - -#### Manejo de excepciones - -El miembro `exceptionHandler` permite llevar a cabo la definición de un manejador de excepciones que estará habilitado durante toda la vida del `Reactor`: - - def exceptionHandler: PartialFunction[Exception, Unit] - -Este manejador de excepciones (`exceptionHandler`) retorna una función parcial que se utiliza para gestionar excepciones que no hayan sido tratadas de ninguna otra manera. Siempre que una excepción se propague fuera del método `act` de un `Reactor` el manejador anterior será aplicado a dicha excepción, permitiendo al actor ejecutar código de limpieza antes de que se termine. Nótese que la visibilidad de `exceptionHandler` es `protected`. - -El manejo de excepciones mediante el uso de `exceptionHandler` encaja a la perfección con las estructuras de control utilizadas para programas con el método `react`. Siempre que una excepción es manejada por la función parcial retornada por `excepctionHandler`, la ejecución continua con la "closure" actual: - - loop { - react { - case Msg(data) => - if (cond) // process data - else throw new Exception("cannot process data") - } - } - -Assumiendo que `Reactor` sobreescribe el atributo `exceptionHandler`, tras el lanzamiento de una excepción en el cuerpo del método `react`, y una vez ésta ha sido gestionada, la ejecución continua con la siguiente iteración del bucle. - -### The ReplyReactor trait - -El trait `ReplyReactor` extiende `Reactor[Any]` y sobrescribe y/o añade los siguientes métodos: - -- El método `!` es sobrescrito para obtener una referencia al actor - actual (el emisor). Junto al mensaje actual, la referencia a dicho - emisor es enviada al buzón del actor receptor. Este último dispone de - acceso al emisor del mensaje mediante el uso del método `sender` (véase más abajo). - -- El método `forward` es sobrescrito para obtener una referencia al emisor - del mensaje que actualmente está siendo procesado. Junto con el mensaje - actual, esta referencia es enviada como el emisor del mensaje actual. - Como consuencia de este hecho, `forward` nos permite reenviar mensajes - en nombre de actores diferentes al actual. - -- El método (añadido) `sender` retorna el emisor del mensaje que está siendo - actualmente procesado. Puesto que un mensaje puede haber sido reenviado, - `sender` podría retornar un actor diferente al que realmente envió el mensaje. - -- El método (añadido) `reply` envía una respuesta al emisor del último mensaje. - `reply` también es utilizado para responder a mensajes síncronos o a mensajes - que han sido enviados mediante un "future" (ver más adelante). - -- El método (añadido) `!?` ofrece un *mecanismo síncrono de envío de mensajes*. - La invocación de `!?` provoca que el actor emisor del mensaje se bloquee hasta - que se recibe una respuesta, momento en el cual retorna dicha respuesta. Existen - dos variantes sobrecargadas. La versión con dos parámetros recibe un argumento - adicional que representa el tiempo de espera (medido en milisegundos) y su tipo - de retorno es `Option[Any]` en lugar de `Any`. En caso de que el emisor no - reciba una respuesta en el periodo de espera establecido, el método `!?` retornará - `None`; en otro caso retornará la respuesta recibida recubierta con `Some`. - -- Los métodos (añadidos) `!!` son similares al envío síncrono de mensajes en el sentido de - que el receptor puede enviar una respuesta al emisor del mensaje. Sin embargo, en lugar - de bloquear el actor emisor hasta que una respuesta es recibida, retornan una instancia de - `Future`. Esta última puede ser utilizada para recuperar la respuesta del receptor una - vez se encuentre disponible; asimismo puede ser utilizada para comprobar si la respuesta - está disponible sin la necesidad de bloquear el emisor. Existen dos versiones sobrecargadas. - La versión que acepta dos parámetros recibe un argumento adicional de tipo - `PartialFunction[Any, A]`. Esta función parcial es utilizada para realizar el post-procesado de - la respuesta del receptor. Básicamente, `!!` retorna un "future" que aplicará la anterior - función parcial a la repuesta (una vez recibida). El resultado del "future" es el resultado - de este post-procesado. - -- El método (añadido) `reactWithin` permite llevar a cabo la recepción de mensajes en un periodo - determinado de tiempo. En comparación con el método `react`, recibe un parámetro adicional, - `msec`, el cual representa el periodo de tiempo, expresado en milisegundos, hasta que el patrón `TIMEOUT` - es satisfecho (`TIMEOUT` es un "case object" presente en el paquete `scala.actors`). Ejemplo: - - reactWithin(2000) { - case Answer(text) => // process text - case TIMEOUT => println("no answer within 2 seconds") - } - -- El método `reactWithin` también permite realizar accesos no bloqueantes al buzón. Si - especificamos un tiempo de espera de 0 milisegundos, primeramente el buzón será escaneado - en busca de un mensaje que concuerde. En caso de que no exista ningún mensaje concordante - tras el primer escaneo, el patrón `TIMEOUT` será satisfecho. Por ejemplo, esto nos permite - recibir determinado tipo de mensajes donde unos tienen una prioridad mayor que otros: - - reactWithin(0) { - case HighPriorityMsg => // ... - case TIMEOUT => - react { - case LowPriorityMsg => // ... - } - } - - En el ejemplo anterior, el actor procesa en primer lugar los mensajes `HighPriorityMsg` aunque - exista un mensaje `LowPriorityMsg` más antiguo en el buzón. El actor sólo procesará mensajes - `LowPriorityMsg` en primer lugar en aquella situación donde no exista ningún `HighProrityMsg` - en el buzón. - -Adicionalmente, el tipo `ReplyActor` añade el estado de ejecución `Actor.State.TimedSuspended`. Un actor suspendido, esperando la recepción de un mensaje mediante el uso de `reactWithin` se encuentra en dicho estado. - -### El trait Actor - -El trait `Actor` extiende de `ReplyReactor` añadiendo y/o sobrescribiendo los siguientes miembros: - -- El método (añadido) `receive` se comporta del mismo modo que `react`, con la excepción - de que puede retornar un resultado. Este hecho se ve reflejado en la definición del tipo, - que es polimórfico en el tipo del resultado: `def receive[R](f: PartialFunction[Any, R]): R`. - Sin embargo, la utilización de `receive` hace que el uso del actor - sea más pesado, puesto que el hilo subyacente es bloqueado mientras - el actor está esperando por la respuesta. El hilo bloqueado no está - disponible para ejecutar otros actores hasta que la invocación del - método `receive` haya retornado. - -- El método (añadido) `link` permite a un actor enlazarse y desenlazarse de otro - actor respectivamente. El proceso de enlazado puede utilizarse para monitorizar - y responder a la terminación de un actor. En particular, el proceso de enlazado - afecta al comportamiento mostrado en la ejecución del método `exit` tal y como - se escribe en el la documentación del API del trait `Actor`. - -- El atributo `trapExit` permite responder a la terminación de un actor enlazado, - independientemente de los motivos de su terminación (es decir, carece de importancia - si la terminación del actor es normal o no). Si `trapExit` toma el valor cierto en - un actor, este nunca terminará por culpa de los actores enlazados. En cambio, siempre - y cuando uno de sus actores enlazados finalice, recibirá un mensaje de tipo `Exit`. - `Exit` es una "case class" que presenta dos atributos: `from` referenciando al actor - que termina y `reason` conteniendo los motivos de la terminación. - -#### Terminación y estados de ejecución - -Cuando la ejecución de un actor finaliza, el motivo de dicha terminación puede ser -establecida de manera explícita mediante la invocación de la siguiente variante -del método `exit`: - - def exit(reason: AnyRef): Nothing - -Un actor cuyo estado de terminación es diferente del símbolo `'normal` propaga -los motivos de su terminación a todos aquellos actores que se encuentren enlazados -a él. Si el motivo de la terminación es una excepción no controlada, el motivo de -finalización será una instancia de la "case class" `UncaughtException`. - -El trait `Actor` incluye dos nuevos estados de ejecución. Un actor que se encuentra -esperando la recepción de un mensaje mediante la utilización del método `receive` se -encuentra en el método `Actor.State.Blocked`. Un actor esperado la recepción de un -mensaje mediante la utilización del método `receiveWithin` se encuentra en el estado -`Actor.State.TimeBlocked`. - -## Estructuras de control - -El trait `Reactor` define una serie de estructuras de control que simplifican el mecanismo -de programación con la función sin retorno `react`. Normalmente, una invocación al método -`react` no retorna nunca. Si el actor necesita ejecutar código a continuación de la invocación -anterior, tendrá que pasar, de manera explícita, dicho código al método `react` o utilizar -algunas de las estructuras que encapsulan este comportamiento. - -La estructura de control más basica es `andThen`. Permite registrar una `closure` que será -ejecutada una vez el actor haya terminado la ejecución de todo lo demas. - - actor { - { - react { - case "hello" => // processing "hello" - }: Unit - } andThen { - println("hi there") - } - } - -Por ejemplo, el actor anterior imprime un saludo tras realizar el procesado -del mensaje `hello`. Aunque la invocación del método `react` no retorna, -podemos utilizar `andThen` para registrar el código encargado de imprimir -el saludo a continuación de la ejecución del actor. - -Nótese que existe una *atribución de tipo* a continuación de la invocación -de `react` (`:Unit`). Básicamente, nos permite tratar el resultado de -`react` como si fuese de tipo `Unit`, lo cual es legal, puesto que el resultado -de una expresión siempre se puede eliminar. Es necesario llevar a cabo esta operación -dado que `andThen` no puede ser un miembro del tipo `Unit`, que es el tipo del resultado -retornado por `react`. Tratando el tipo de resultado retornado por `react` como -`Unit` permite llevar a cabo la aplicación de una conversión implícita la cual -hace que el miembro `andThen` esté disponible. - -El API ofrece unas cuantas estructuras de control adicionales: - -- `loop { ... }`. Itera de manera indefinidia, ejecutando el código entre -las llaves en cada una de las iteraciones. La invocación de `react` en el -cuerpo del bucle provoca que el actor se comporte de manera habitual ante -la llegada de un nuevo mensaje. Posteriormente a la recepción del mensaje, -la ejecución continua con la siguiente iteración del bucle actual. - -- `loopWhile (c) { ... }`. Ejecuta el código entre las llaves mientras la -condición `c` tome el valor `true`. La invocación de `react` en el cuerpo -del bucle ocasiona el mismo efecto que en el caso de `loop`. - -- `continue`. Continua con la ejecución de la closure actual. La invocación -de `continue` en el cuerpo de un `loop`o `loopWhile` ocasionará que el actor -termine la iteración en curso y continue con la siguiente. Si la iteración en -curso ha sido registrada utilizando `andThen`, la ejecución continua con la -segunda "closure" pasada como segundo argumento a `andThen`. - -Las estructuras de control pueden ser utilizadas en cualquier parte del cuerpo -del método `act` y en los cuerpos de los métodos que, transitivamente, son -llamados por `act`. Aquellos actores creados utilizando la sintáxis `actor { ... }` -pueden importar las estructuras de control desde el objeto `Actor`. - -#### Futures - -Los traits `RepyActor` y `Actor` soportan operaciones de envío de mensajes -(métodos `!!`) que, de manera inmediata, retornan un *future*. Un *future*, -es una instancia del trait `Future` y actúa como un manejador que puede -ser utilizado para recuperar la respuesta a un mensaje "send-with-future". - -El emisor de un mensaje "send-with-future" puede esperar por la respuesta del -future *aplicando* dicha future. Por ejemplo, el envío de un mensaje mediante -`val fut = a !! msg` permite al emisor esperar por el resultado del future -del siguiente modo: `val res = fut()`. - -Adicionalmente, utilizando el método `isSet`, un `Future` puede ser consultado -de manera no bloqueante para comprobar si el resultado está disponible. - -Un mensaje "send-with-future" no es el único modo de obtener una referencia a -un future. Estos pueden ser creados utilizando el método `future`. En el siguiente -ejemplo, `body` se ejecuta de manera concurrente, retornando un future como -resultado. - - val fut = Future { body } - // ... - fut() // wait for future - -Lo que hace especial a los futures en el contexto de los actores es la posibilidad -de recuperar su resultado utilizando las operaciones estándar de actores de -recepción de mensajes como `receive`, etc. Además, es posible utilizar las operaciones -basadas en eventos `react`y `reactWithin`. Esto permite a un actor esperar por el -resultado de un future sin la necesidad de bloquear el hilo subyacente. - -Las operaciones de recepción basadas en actores están disponibles a través del -atributo `inputChannel` del future. Dado un future de tipo `Future[T]`, el tipo -de `inputChannel` es `InputChannel[T]`. Por ejemplo: - - val fut = a !! msg - // ... - fut.inputChannel.react { - case Response => // ... - } - -## Canales - -Los canales pueden ser utilizados para simplificar el manejo de mensajes -que presentan tipos diferentes pero que son enviados al mismo actor. La -jerarquía de canales se divide en `OutputChannel` e `InputChannel`. - -Los `OutputChannel` pueden ser utilizados para enviar mensajes. Un -`OutputChannel` `out` soporta las siguientes operaciones: - -- `out ! msg`. Envía el mensaje `msg` a `out` de manera asíncrona. Cuando `msg` - es enviado directamente a un actor se incluye un referencia al actor emisor - del mensaje. - -- `out forward msg`. Reenvía el mensaje `msg` a `out` de manera asíncrona. - El actor emisor se determina en el caso en el que `msg` es reenviado a - un actor. - -- `out.receiver`. Retorna el único actor que está recibiendo mensajes que están - siendo enviados al canal `out`. - -- `out.send(msg, from)`. Envía el mensaje `msg` a `out` de manera asíncrona, - proporcionando a `from` como el emisor del mensaje. - -Nótese que el trait `OutputChannel` tiene un parámetro de tipo que especifica el -tipo de los mensajes que pueden ser enviados al canal (utilizando `!`, `forward`, -y `send`). Este parámetro de tipo es contra-variante: - - trait OutputChannel[-Msg] - -Los actores pueden recibir mensajes de un `InputChannel`. Del mismo modo que -`OutputChannel`, el trait `InputChannel` presenta un parámetro de tipo que -especifica el tipo de mensajes que pueden ser recibidos por el canal. En este caso, -el parámetro de tipo es covariante: - - trait InputChannel[+Msg] - -Un `InputChannel[Msg]` `in` soportal las siguientes operaciones. - -- `in.receive { case Pat1 => ... ; case Patn => ... }` (y de manera similar, - `in.receiveWithin`) recibe un mensaje proveniente de `in`. La invocación - del método `receive` en un canal de entrada presenta la misma semántica - que la operación estándar de actores `receive`. La única diferencia es que - la función parcial pasada como argumento tiene tipo `PartialFunction[Msg, R]` - donde `R` es el tipo de retorno de `receive`. - -- `in.react { case Pat1 => ... ; case Patn => ... }` (y de manera similar, - `in.reactWithin`). Recibe un mensaje de `in` utilizando la operación basada en - eventos `react`. Del mismo modo que la operación `react` en actores, el tipo - de retorno es `Nothing`, indicando que las invocaciones de este método nunca - retornan. Al igual que la operación `receive` anterior, la función parcial - que se pasa como argumento presenta un tipo más específico: - - PartialFunction[Msg, Unit] - -### Creando y compartiendo canales - -Los canales son creados utilizando la clase concreta `Channel`. Esta clase extiende -de `InputChannel` y `OutputChannel`. Un canal pueden ser compartido haciendo dicho -canal visible en el ámbito de múltiples actores o enviándolo como mensaje. - -El siguiente ejemplo muestra la compartición mediante publicación en ámbitos: - - actor { - var out: OutputChannel[String] = null - val child = actor { - react { - case "go" => out ! "hello" - } - } - val channel = new Channel[String] - out = channel - child ! "go" - channel.receive { - case msg => println(msg.length) - } - } - -La ejecución de este ejemplo imprime la cadena "5" en la consola. Nótese que el -actor `child` únicamente tiene acceso a `out`, que es un `OutputChannel[String]`. -La referencia al canal, la cual puede ser utilizada para llevar a cabo la recepción -de mensajes, se encuentra oculta. Sin embargo, se deben tomar precauciones y -asegurarse que el canal de salida es inicializado con un canal concreto antes de que -`child` le envíe ningún mensaje. En el ejemplo que nos ocupa, esto es llevado a cabo -mediante el mensaje "go". Cuando se está recibiendo de `channel` utilizando el método -`channel.receive` podemos hacer uso del hecho que `msg` es de tipo `String`, y por -lo tanto tiene un miembro `length`. - -Una alternativa a la compartición de canales es enviarlos a través de mensajes. -El siguiente fragmento de código muestra un sencillo ejemplo de aplicación: - - case class ReplyTo(out: OutputChannel[String]) - - val child = actor { - react { - case ReplyTo(out) => out ! "hello" - } - } - - actor { - val channel = new Channel[String] - child ! ReplyTo(channel) - channel.receive { - case msg => println(msg.length) - } - } - -La "case class" `ReplyTo` es un tipo de mensajes que utilizamos para distribuir -una referencia a un `OutputChannel[String]`. Cuando el actor `child` recibe un -mensaje de tipo `ReplyTo` éste envía una cadena a su canal de salida. El segundo -actor recibe en el canal del mismo modo que anteriormente. - -## Planificadores - -Un `Reactor`(o una instancia de uno de sus subtipos) es ejecutado utilizando un -*planificador*. El trait `Reactor` incluye el miembro `scheduler` el cual retorna el -planificador utilizado para ejecutar sus instancias: - - def scheduler: IScheduler - -La plataforma de ejecución ejecuta los actores enviando tareas al planificador mediante -el uso de los métodos `execute` definidos en el trait `IScheduler`. La mayor parte -del resto de métodos definidos en este trait únicamente adquieren cierto protagonismo -cuando se necesita implementar un nuevo planificador desde cero; algo que no es necesario -en muchas ocasiones. - -Los planificadores por defecto utilizados para ejecutar instancias de `Reactor` y -`Actor` detectan cuando los actores han finalizado su ejecución. En el momento que esto -ocurre, el planificador se termina a si mismo (terminando con cualquier hilo que estuviera -en uso por parte del planificador). Sin embargo, algunos planificadores como el -`SingleThreadedScheduler` (definido en el paquete `scheduler`) necesita ser terminado de -manera explícita mediante la invocación de su método `shutdown`). - -La manera más sencilla de crear un planificador personalizado consisten en extender la clase -`SchedulerAdapter`, implementando el siguiente método abstracto: - - def execute(fun: => Unit): Unit - -Por norma general, una implementación concreata utilizaría un pool de hilos para llevar a cabo -la ejecución del argumento por nombre `fun`. - -## Actores remotos - -Esta sección describe el API de los actores remotos. Su principal interfaz es el objecto -[`RemoteActor`](http://www.scala-lang.org/api/2.9.1/scala/actors/remote/RemoteActor$.html) definido -en el paquete `scala.actors.remote`. Este objeto facilita el conjunto de métodos necesarios para crear -y establecer conexiones a instancias de actores remotos. En los fragmentos de código que se muestran a -continuación se asume que todos los miembros de `RemoteActor` han sido importados; la lista completa -de importaciones utilizadas es la siguiente: - - import scala.actors._ - import scala.actors.Actor._ - import scala.actors.remote._ - import scala.actors.remote.RemoteActor._ - -### Iniciando actores remotos - -Un actore remot es identificado de manera unívoca por un -[`Symbol`](http://www.scala-lang.org/api/2.9.1/scala/Symbol.html). Este símbolo es único para la instancia -de la máquina virual en la que se está ejecutando un actor. Un actor remoto identificado con el nombre -`myActor` puede ser creado del siguiente modo. - - class MyActor extends Actor { - def act() { - alive(9000) - register('myActor, self) - // ... - } - } - -Nótese que el nombre únicamente puede ser registrado con un único actor al mismo tiempo. -Por ejemplo, para registrar el actor *A* como `'myActor` y posteriormente registrar otro -actor *B* como `'myActor`, debería esperar hasta que *A* haya finalizado. Este requisito -aplica a lo largo de todos los puertos, por lo que registrando a *B* en un puerto diferente -no sería suficiente. - -### Connecting to remote actors - -Establecer la conexión con un actor remoto es un proceso simple. Para obtener una referencia remota -a un actor remoto que está ejecutándose en la máquina `myMachine` en el puerto 8000 con el nombre -`'anActor`, tendremos que utilizar `select`del siguiente modo: - - val myRemoteActor = select(Node("myMachine", 8000), 'anActor) - -El actor retornado por `select` es de tipo `AbstractActor`, que proporciona esencialmente el mismo -interfaz que un actor normal, y por lo tanto es compatible con las habituales operaciones de envío -de mensajes: - - myRemoteActor ! "Hello!" - receive { - case response => println("Response: " + response) - } - myRemoteActor !? "What is the meaning of life?" match { - case 42 => println("Success") - case oops => println("Failed: " + oops) - } - val future = myRemoteActor !! "What is the last digit of PI?" - -Nótese que la operación `select` es perezosa; no inicializa ninguna conexión de red. Simplemente crea -una nueva instancia de `AbstractActor` que está preparada para iniciar una nueva conexión de red en el -momento en que sea necesario (por ejemplo cuando el método '!' es invocado). diff --git a/_es/overviews/core/string-interpolation.md b/_es/overviews/core/string-interpolation.md index 392a0b68ac..a85787d382 100644 --- a/_es/overviews/core/string-interpolation.md +++ b/_es/overviews/core/string-interpolation.md @@ -5,8 +5,6 @@ title: Interpolación de cadenas partof: string-interpolation language: es - -discourse: false --- **Josh Suereth** @@ -21,7 +19,7 @@ Este nuevo mecanismo permite a los usuarios incluir referencias a variables de m val name = "James" println(s"Hello, $name") // Hello, James -En el ejemplo anterior, el literal `s"Hello, $name"` es una cadena "procesada". Esto significa que el compilador debe realizar un trabajo adicional durante el tratamiento de dicha cadena. Una cadena "procesada" se denota mediante un conjunto de caracteres que preceden al símbolo `"`. La interpolación de cadenas ha sido introducida por [SIP-11](http://docs.scala-lang.org/sips/pending/string-interpolation.html), el cual contiene todos los detalles de implementación. +En el ejemplo anterior, el literal `s"Hello, $name"` es una cadena "procesada". Esto significa que el compilador debe realizar un trabajo adicional durante el tratamiento de dicha cadena. Una cadena "procesada" se denota mediante un conjunto de caracteres que preceden al símbolo `"`. La interpolación de cadenas ha sido introducida por [SIP-11](https://docs.scala-lang.org/sips/pending/string-interpolation.html), el cual contiene todos los detalles de implementación. ## Uso @@ -61,7 +59,7 @@ El interpolador `f` es seguro respecto a tipos. Si pasamos un número real a una f"$height%4d" ^ -El interpolador `f` hace uso de las utilidades de formateo de cadenas disponibles en java. Los formatos permitidos tras el carácter `%` son descritos en [Formatter javadoc](http://docs.oracle.com/javase/1.6.0/docs/api/java/util/Formatter.html#detail). Si el carácter `%` no aparece tras la definición de una variable, `%s` es utilizado por defecto. +El interpolador `f` hace uso de las utilidades de formateo de cadenas disponibles en java. Los formatos permitidos tras el carácter `%` son descritos en [Formatter javadoc](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html#detail). Si el carácter `%` no aparece tras la definición de una variable, `%s` es utilizado por defecto. ### Interpolador `raw` @@ -87,7 +85,7 @@ En Scala, todas las cadenas "procesadas" son simples transformaciones de código id"string content" -la transforma en la llamada a un método (`id`) sobre una instancia de [StringContext](http://www.scala-lang.org/api/current/index.html#scala.StringContext). Este método también puede estar disponible en un ámbito implícito. Para definiir nuestra propia cadena de interpolación simplemente necesitamos crear una clase implícita que añada un nuevo método a la clase `StringContext`. A continuación se muestra un ejemplo: +la transforma en la llamada a un método (`id`) sobre una instancia de [StringContext](https://www.scala-lang.org/api/current/index.html#scala.StringContext). Este método también puede estar disponible en un ámbito implícito. Para definiir nuestra propia cadena de interpolación simplemente necesitamos crear una clase implícita que añada un nuevo método a la clase `StringContext`. A continuación se muestra un ejemplo: // Note: We extends AnyVal to prevent runtime instantiation. See // value class guide for more info. @@ -115,10 +113,10 @@ De este modo, el método `json` tiene acceso a las diferentes partes de las cade def json(args: Any*): JSONObject = { val strings = sc.parts.iterator val expressions = args.iterator - var buf = new StringBuffer(strings.next) + var buf = new StringBuilder(strings.next) while(strings.hasNext) { - buf append expressions.next - buf append strings.next + buf.append(expressions.next()) + buf.append(strings.next()) } parseJson(buf) } diff --git a/_es/overviews/parallel-collections/architecture.md b/_es/overviews/parallel-collections/architecture.md index fa8d146b00..138a5dee08 100644 --- a/_es/overviews/parallel-collections/architecture.md +++ b/_es/overviews/parallel-collections/architecture.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Arquitectura de la librería de colecciones paralelas de Scala - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -90,7 +87,7 @@ de la librería de colecciones secuenciales -- de hecho, "replican" los correspo traits presentes en el framework de colecciones secuenciales, tal y como se muestra a continuación. -[]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png) +[Hierarchy of Scala Collections and Parallel Collections]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png)
Jerarquía de clases de las librerías de colecciones secuenciales y paralelas de Scala

@@ -115,4 +112,4 @@ paralelas referirse al artículo \[[1][1]\] 1. [On a Generic Parallel Collection Framework, Aleksandar Prokopec, Phil Bawgell, Tiark Rompf, Martin Odersky, June 2011][1] -[1]: http://infoscience.epfl.ch/record/165523/files/techrep.pdf "flawed-benchmark" +[1]: https://infoscience.epfl.ch/record/165523/files/techrep.pdf "flawed-benchmark" diff --git a/_es/overviews/parallel-collections/concrete-parallel-collections.md b/_es/overviews/parallel-collections/concrete-parallel-collections.md index 158c923f6e..4674d34b16 100644 --- a/_es/overviews/parallel-collections/concrete-parallel-collections.md +++ b/_es/overviews/parallel-collections/concrete-parallel-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Clases Concretas de las Colecciones Paralelas - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -13,7 +10,7 @@ language: es ## Array Paralelo -Una secuencia [ParArray](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/mutable/ParArray.html) contiene un conjunto de elementos contiguos lineales. Esto significa que los elementos pueden ser accedidos y actualizados (modificados) eficientemente al modificar la estructura subyacente (un array). El iterar sobre sus elementos es también muy eficiente por esta misma razón. Los Arrays Paralelos son como arrays en el sentido de que su tamaño es constante. +Una secuencia [ParArray](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/mutable/ParArray.html) contiene un conjunto de elementos contiguos lineales. Esto significa que los elementos pueden ser accedidos y actualizados (modificados) eficientemente al modificar la estructura subyacente (un array). El iterar sobre sus elementos es también muy eficiente por esta misma razón. Los Arrays Paralelos son como arrays en el sentido de que su tamaño es constante. scala> val pa = scala.collection.parallel.mutable.ParArray.tabulate(1000)(x => 2 * x + 1) pa: scala.collection.parallel.mutable.ParArray[Int] = ParArray(1, 3, 5, 7, 9, 11, 13,... @@ -31,7 +28,7 @@ Al invocar el método `seq`, los arrays paralelos son convertidos al tipo de col ## Vector Paralelo -Un [ParVector](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParVector.html) es una secuencia inmutable con un tiempo de acceso y modificación logarítimico bajo a constante. +Un [ParVector](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParVector.html) es una secuencia inmutable con un tiempo de acceso y modificación logarítimico bajo a constante. scala> val pv = scala.collection.parallel.immutable.ParVector.tabulate(1000)(x => x) pv: scala.collection.parallel.immutable.ParVector[Int] = ParVector(0, 1, 2, 3, 4, 5, 6, 7, 8, 9,... @@ -41,11 +38,11 @@ Un [ParVector](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/coll Los vectores inmutables son representados por árboles, por lo que los splitters dividen pasándose subárboles entre ellos. Los combiners concurrentemente mantienen un vector de elementos y son combinados al copiar dichos elementos de forma "retardada". Es por esta razón que los métodos tranformadores son menos escalables que sus contrapartes en arrays paralelos. Una vez que las operaciones de concatenación de vectores estén disponibles en una versión futura de Scala, los combiners podrán usar dichas características y hacer más eficientes los métodos transformadores. -Un vector paralelo es la contraparte paralela de un [Vector](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html) secuencial, por lo tanto la conversión entre estas dos estructuras se efectúa en tiempo constante. +Un vector paralelo es la contraparte paralela de un [Vector](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html) secuencial, por lo tanto la conversión entre estas dos estructuras se efectúa en tiempo constante. ## Rango (Range) Paralelo -Un [ParRange](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParRange.html) es una secuencia ordenada separada por intervalos iguales (ej: 1, 2, 3 o 1, 3, 5, 7). Un rango paralelo es creado de forma similar al [Rango](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html) secuencial: +Un [ParRange](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParRange.html) es una secuencia ordenada separada por intervalos iguales (ej: 1, 2, 3 o 1, 3, 5, 7). Un rango paralelo es creado de forma similar al [Rango](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html) secuencial: scala> 1 to 3 par res0: scala.collection.parallel.immutable.ParRange = ParRange(1, 2, 3) @@ -61,7 +58,7 @@ Tal como los rangos secuenciales no tienen constructores, los rangos paralelos n ## Tablas Hash Paralelas -Las tablas hash paralelas almacenan sus elementos en un array subyacente y los almacenan en una posición determinada por el código hash del elemento respectivo. Las versiones mutables de los hash sets paralelos ([mutable.ParHashSet](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/mutable/ParHashSet.html)) y los hash maps paraleos ([mutable.ParHashMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/mutable/ParHashMap.html)) están basados en tablas hash. +Las tablas hash paralelas almacenan sus elementos en un array subyacente y los almacenan en una posición determinada por el código hash del elemento respectivo. Las versiones mutables de los hash sets paralelos ([mutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParHashSet.html)) y los hash maps paraleos ([mutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/mutable/ParHashMap.html)) están basados en tablas hash. scala> val phs = scala.collection.parallel.mutable.ParHashSet(1 until 2000: _*) phs: scala.collection.parallel.mutable.ParHashSet[Int] = ParHashSet(18, 327, 736, 1045, 773, 1082,... @@ -75,9 +72,9 @@ Los "Mapas Hash" (Hash Maps) y los "Conjuntos Hash" (Hash Sets) secuenciales pue ## Hash Tries Paralelos -Los Hash Tries paralelos son la contraparte paralela de los hash tries inmutables, que son usados para representar conjuntos y mapas inmutables de forma eficiente. Las clases involucradas son: [immutable.ParHashSet](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParHashSet.html) +Los Hash Tries paralelos son la contraparte paralela de los hash tries inmutables, que son usados para representar conjuntos y mapas inmutables de forma eficiente. Las clases involucradas son: [immutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParHashSet.html) y -[immutable.ParHashMap](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/immutable/ParHashMap.html). +[immutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/immutable/ParHashMap.html). scala> val phs = scala.collection.parallel.immutable.ParHashSet(1 until 1000: _*) phs: scala.collection.parallel.immutable.ParHashSet[Int] = ParSet(645, 892, 69, 809, 629, 365, 138, 760, 101, 479,... @@ -92,7 +89,7 @@ Los hash tries paralelos pueden ser convertidos hacia y desde hash tries secuenc ## Tries Paralelos Concurrentes -Un [concurrent.TrieMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/concurrent/TrieMap.html) es un mapa thread-safe (seguro ante la utilización de múltiples hilos concurrentes) mientras que [mutable.ParTrieMap](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/mutable/ParTrieMap.html) es su contraparte paralela. Si bien la mayoría de las estructuras de datos no garantizan una iteración consistente si la estructura es modificada en medio de dicha iteración, los tries concurrentes garantizan que las actualizaciones sean solamente visibles en la próxima iteración. Esto significa que es posible mutar el trie concurrente mientras se está iterando sobre este, como en el siguiente ejemplo, que computa e imprime las raíces cuadradas de los números entre 1 y 99: +Un [concurrent.TrieMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/concurrent/TrieMap.html) es un mapa thread-safe (seguro ante la utilización de múltiples hilos concurrentes) mientras que [mutable.ParTrieMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParTrieMap.html) es su contraparte paralela. Si bien la mayoría de las estructuras de datos no garantizan una iteración consistente si la estructura es modificada en medio de dicha iteración, los tries concurrentes garantizan que las actualizaciones sean solamente visibles en la próxima iteración. Esto significa que es posible mutar el trie concurrente mientras se está iterando sobre este, como en el siguiente ejemplo, que computa e imprime las raíces cuadradas de los números entre 1 y 99: scala> val numbers = scala.collection.parallel.mutable.ParTrieMap((1 until 100) zip (1 until 100): _*) map { case (k, v) => (k.toDouble, v.toDouble) } numbers: scala.collection.parallel.mutable.ParTrieMap[Double,Double] = ParTrieMap(0.0 -> 0.0, 42.0 -> 42.0, 70.0 -> 70.0, 2.0 -> 2.0,... diff --git a/_es/overviews/parallel-collections/configuration.md b/_es/overviews/parallel-collections/configuration.md index 6e921bc9a5..c0c9604254 100644 --- a/_es/overviews/parallel-collections/configuration.md +++ b/_es/overviews/parallel-collections/configuration.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Configurando las colecciones paralelas - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -80,4 +77,4 @@ las diferentes tareas. 1. [On a Generic Parallel Collection Framework, June 2011][1] - [1]: http://infoscience.epfl.ch/record/165523/files/techrep.pdf "parallel-collections" + [1]: https://infoscience.epfl.ch/record/165523/files/techrep.pdf "parallel-collections" diff --git a/_es/overviews/parallel-collections/conversions.md b/_es/overviews/parallel-collections/conversions.md index 8461a2f9aa..dd3caa1543 100644 --- a/_es/overviews/parallel-collections/conversions.md +++ b/_es/overviews/parallel-collections/conversions.md @@ -1,8 +1,6 @@ --- layout: multipage-overview title: Conversiones en colecciones paralelas -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -61,16 +59,16 @@ en una colección `ParX` A continuación se muestra un resumen de todos los métodos de conversión: -| método | Tipo de Retorno| -| -------------- | -------------- | -| `toArray` | `Array` | -| `toList` | `List` | -| `toIndexedSeq` | `IndexedSeq` | -| `toStream` | `Stream` | -| `toIterator` | `Iterator` | -| `toBuffer` | `Buffer` | -| `toTraversable`| `GenTraverable`| -| `toIterable` | `ParIterable` | -| `toSeq` | `ParSeq` | -| `toSet` | `ParSet` | -| `toMap` | `ParMap` | +| método | Tipo de Retorno | +| -------------- | --------------- | +| `toArray` | `Array` | +| `toList` | `List` | +| `toIndexedSeq` | `IndexedSeq` | +| `toStream` | `Stream` | +| `toIterator` | `Iterator` | +| `toBuffer` | `Buffer` | +| `toTraversable`| `GenTraversable`| +| `toIterable` | `ParIterable` | +| `toSeq` | `ParSeq` | +| `toSet` | `ParSet` | +| `toMap` | `ParMap` | diff --git a/_es/overviews/parallel-collections/ctries.md b/_es/overviews/parallel-collections/ctries.md index c45a112520..2432510f03 100644 --- a/_es/overviews/parallel-collections/ctries.md +++ b/_es/overviews/parallel-collections/ctries.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Tries Concurrentes - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -163,6 +160,6 @@ en paralelo. 2. [Concurrent Tries with Efficient Non-Blocking Snapshots][2] 3. [Methods of computing square roots][3] - [1]: http://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf "Ctries-techreport" + [1]: https://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf "Ctries-techreport" [2]: http://lampwww.epfl.ch/~prokopec/ctries-snapshot.pdf "Ctries-snapshot" - [3]: http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method "babylonian-method" + [3]: https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method "babylonian-method" diff --git a/_es/overviews/parallel-collections/custom-parallel-collections.md b/_es/overviews/parallel-collections/custom-parallel-collections.md index 802d9f5286..d142e88083 100644 --- a/_es/overviews/parallel-collections/custom-parallel-collections.md +++ b/_es/overviews/parallel-collections/custom-parallel-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Creating Custom Parallel Collections - -discourse: false - partof: parallel-collections overview-name: Parallel Collections diff --git a/_es/overviews/parallel-collections/overview.md b/_es/overviews/parallel-collections/overview.md index 8e69d27b2a..41ec0d61a8 100644 --- a/_es/overviews/parallel-collections/overview.md +++ b/_es/overviews/parallel-collections/overview.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Overview - -discourse: false - partof: parallel-collections overview-name: Parallel Collections diff --git a/_es/overviews/parallel-collections/performance.md b/_es/overviews/parallel-collections/performance.md index 26d2237b10..c7de720783 100644 --- a/_es/overviews/parallel-collections/performance.md +++ b/_es/overviews/parallel-collections/performance.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Midiendo el rendimiento - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -273,5 +270,5 @@ los que serían requeridos por arrays o vectores). 1. [Anatomy of a flawed microbenchmark, Brian Goetz][1] 2. [Dynamic compilation and performance measurement, Brian Goetz][2] - [1]: http://www.ibm.com/developerworks/java/library/j-jtp02225/index.html "flawed-benchmark" - [2]: http://www.ibm.com/developerworks/library/j-jtp12214/ "dynamic-compilation" + [1]: https://www.ibm.com/developerworks/java/library/j-jtp02225/index.html "flawed-benchmark" + [2]: https://www.ibm.com/developerworks/library/j-jtp12214/ "dynamic-compilation" diff --git a/_es/tour/abstract-types.md b/_es/tour/abstract-type-members.md similarity index 70% rename from _es/tour/abstract-types.md rename to _es/tour/abstract-type-members.md index ac54a11ca7..1e9afc50d7 100644 --- a/_es/tour/abstract-types.md +++ b/_es/tour/abstract-type-members.md @@ -1,9 +1,6 @@ --- layout: tour title: Tipos Abstractos - -discourse: false - partof: scala-tour num: 2 @@ -17,56 +14,60 @@ previous-page: tour-of-scala En Scala, las cases son parametrizadas con valores (los parámetros de construcción) y con tipos (si las clases son [genéricas](generic-classes.html)). Por razones de consistencia, no es posible tener solo valores como miembros de objetos; tanto los tipos como los valores son miembros de objetos. Además, ambos tipos de miembros pueden ser concretos y abstractos. A continuación un ejemplo el cual define de forma conjunta una asignación de valor tardía y un tipo abstracto como miembros del [trait](traits.html) `Buffer`. - trait Buffer { - type T - val element: T - } +```scala mdoc +trait Buffer { + type T + val element: T +} +``` Los *tipos abstractos* son tipos los cuales su identidad no es precisamente conocida. En el ejemplo anterior, lo único que sabemos es que cada objeto de la clase `Buffer` tiene un miembro de tipo `T`, pero la definición de la clase `Buffer` no revela qué tipo concreto se corresponde con el tipo `T`. Tal como las definiciones de valores, es posible sobrescribir las definiciones de tipos en subclases. Esto permite revelar más información acerca de un tipo abstracto al acotar el tipo ligado (el cual describe las posibles instancias concretas del tipo abstracto). En el siguiente programa derivamos la clase `SeqBuffer` la cual nos permite almacenar solamente sequencias en el buffer al estipular que el tipo `T` tiene que ser un subtipo de `Seq[U]` para un nuevo tipo abstracto `U`: - abstract class SeqBuffer extends Buffer { - type U - type T <: Seq[U] - def length = element.length - } +```scala mdoc +abstract class SeqBuffer extends Buffer { + type U + type T <: Seq[U] + def length = element.length +} +``` Traits o [clases](classes.html) con miembros de tipos abstractos son generalmente usados en combinación con instancias de clases anónimas. Para ilustrar este concepto veremos un programa el cual trata con un buffer de sequencia que se remite a una lista de enteros. - abstract class IntSeqBuffer extends SeqBuffer { - type U = Int - } - - object AbstractTypeTest1 extends App { - def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = - new IntSeqBuffer { - type T = List[U] - val element = List(elem1, elem2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) - } +```scala mdoc +abstract class IntSeqBuffer extends SeqBuffer { + type U = Int +} + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` El tipo retornado por el método `newIntSeqBuf` está ligado a la especialización del trait `Buffer` en el cual el tipo `U` es ahora equivalente a `Int`. Existe un tipo alias similar en la instancia de la clase anónima dentro del cuerpo del método `newIntSeqBuf`. En ese lugar se crea una nueva instancia de `IntSeqBuffer` en la cual el tipo `T` está ligado a `List[Int]`. Es necesario notar que generalmente es posible transformar un tipo abstracto en un tipo paramétrico de una clase y viceversa. A continuación se muestra una versión del código anterior el cual solo usa tipos paramétricos. - abstract class Buffer[+T] { - val element: T - } - abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { - def length = element.length - } - object AbstractTypeTest2 extends App { - def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = - new SeqBuffer[Int, List[Int]] { - val element = List(e1, e2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) - } +```scala mdoc:reset +abstract class Buffer[+T] { + val element: T +} +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { + def length = element.length +} +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` Nótese que es necesario usar [variance annotations](variances.html) aquí; de otra manera no sería posible ocultar el tipo implementado por la secuencia concreta del objeto retornado por `newIntSeqBuf`. Además, existen casos en los cuales no es posible remplazar tipos abstractos con tipos parametrizados. diff --git a/_es/tour/annotations.md b/_es/tour/annotations.md index 490e2287da..37dd912f97 100644 --- a/_es/tour/annotations.md +++ b/_es/tour/annotations.md @@ -1,16 +1,13 @@ --- layout: tour title: Anotaciones - -discourse: false - partof: scala-tour num: 3 language: es -next-page: classes -previous-page: abstract-types +next-page: packages-and-imports +previous-page: abstract-type-members --- Las anotaciones sirven para asociar meta-información con definiciones. @@ -23,16 +20,15 @@ El significado de las anotaciones _depende de la implementación_. En la platafo | Scala | Java | | ------ | ------ | -| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (campo, variable) | -| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | +| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](https://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (campo, variable) | +| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](https://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | | [`scala.inline`](https://www.scala-lang.org/api/current/scala/inline.html) (desde 2.6.0) | sin equivalente | -| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (desde 2.6.0) | [`native`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | -| [`scala.remote`](https://www.scala-lang.org/api/current/scala/remote.html) | [`java.rmi.Remote`](http://java.sun.com/j2se/1.5.0/docs/api/java/rmi/Remote.html) | -| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | -| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | +| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (desde 2.6.0) | [`native`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | +| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | +| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | | [`scala.unchecked`](https://www.scala-lang.org/api/current/scala/unchecked.html) (desde 2.4.0) | sin equivalente | -| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | -| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`Design pattern`](http://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | +| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (palabra clave) | +| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`Design pattern`](https://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | En el siguiente ejemplo agregamos la anotación `throws` a la definición del método `read` de manera de capturar la excepción lanzada en el programa principal de Java. @@ -77,7 +73,7 @@ Si comentamos la anotación `throws` en la clase `Reader` se produce el siguient **Nota:** Asegurate de usar la opción `-target:jvm-1.5` con anotaciones de Java. -Java 1.5 introdujo metadata definida por el usuario en la forma de [anotaciones](http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html). Una característica fundamental de las anotaciones es que se basan en pares nombre-valor específicos para inicializar sus elementos. Por ejemplo, si necesitamos una anotación para rastrear el código de alguna clase debemos definirlo así: +Java 1.5 introdujo metadata definida por el usuario en la forma de [anotaciones](https://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html). Una característica fundamental de las anotaciones es que se basan en pares nombre-valor específicos para inicializar sus elementos. Por ejemplo, si necesitamos una anotación para rastrear el código de alguna clase debemos definirlo así: @interface Source { public String URL(); @@ -86,13 +82,13 @@ Java 1.5 introdujo metadata definida por el usuario en la forma de [anotaciones] Y después utilizarlo de la siguiente manera - @Source(URL = "http://coders.com/", + @Source(URL = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... Una anotación en Scala se asemeja a una invocación a un constructor. Para instanciar una anotación de Java es necesario usar los argumentos nombrados: - @Source(URL = "http://coders.com/", + @Source(URL = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... @@ -105,22 +101,22 @@ Esta sintaxis es bastante tediosa si la anotación contiene solo un elemento (si Y podemos aplicarlo así: - @SourceURL("http://coders.com/") + @SourceURL("https://coders.com/") public class MyClass extends HisClass ... En este caso, Scala provee la misma posibilidad: - @SourceURL("http://coders.com/") + @SourceURL("https://coders.com/") class MyScalaClass ... El elemento `mail` fue especificado con un valor por defecto (mediante la cláusula `default`) por lo tanto no necesitamos proveer explicitamente un valor para este. De todas maneras, si necesitamos pasarle un valor no podemos mezclar los dos estilos en Java: - @SourceURL(value = "http://coders.com/", + @SourceURL(value = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... Scala provee más flexibilidad en este caso: - @SourceURL("http://coders.com/", + @SourceURL("https://coders.com/", mail = "support@coders.com") class MyScalaClass ... diff --git a/_es/tour/automatic-closures.md b/_es/tour/automatic-closures.md deleted file mode 100644 index a6eba7b6c5..0000000000 --- a/_es/tour/automatic-closures.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: tour -title: Construcción de closures automáticas - -discourse: false - -partof: scala-tour - -num: 16 -language: es - -next-page: operators -previous-page: multiple-parameter-lists ---- - -Scala permite pasar funciones sin parámetros como parámetros de un método. Cuando un método así es invocado, los parámetros reales de la función enviada sin parámetros no son evaluados y una función "nularia" (de aridad cero, 0-aria, o sin parámetros) es pasada en su lugar. Esta función encapsula el comportamiento del parámetro correspondiente (comunmente conocido como "llamada por nombre"). - -Para aclarar un poco esto aquí se muestra un ejemplo: - - object TargetTest1 extends App { - def whileLoop(cond: => Boolean)(body: => Unit): Unit = - if (cond) { - body - whileLoop(cond)(body) - } - var i = 10 - whileLoop (i > 0) { - println(i) - i -= 1 - } - } - -La función `whileLoop` recibe dos parámetros `cond` y `body`. Cuando la función es llamada, los parámetros reales no son evaluados en ese momento. Pero cuando los parámetros son utilizados en el cuerpo de la función `whileLoop`, las funciones nularias creadas implícitamente serán evaluadas en su lugar. Así, nuestro método `whileLoop` implementa un bucle tipo Java mediante una implementación recursiva. - -Es posible combinar el uso de [operadores de infijo y postfijo (infix/postfix)](operators.html) con este mecanismo para crear declaraciones más complejas (con una sintaxis agradadable). - -Aquí mostramos la implementación de una declaración tipo repetir-a-menos-que (repetir el bucle a no ser que se cumpla X condición): - - object TargetTest2 extends App { - def loop(body: => Unit): LoopUnlessCond = - new LoopUnlessCond(body) - protected class LoopUnlessCond(body: => Unit) { - def unless(cond: => Boolean) { - body - if (!cond) unless(cond) - } - } - var i = 10 - loop { - println("i = " + i) - i -= 1 - } unless (i == 0) - } - -La función `loop` solo acepta el cuerpo de un bucle y retorna una instancia de la clase `LoopUnlessCond` (la cual encapsula el cuerpo del objeto). Es importante notar que en este punto el cuerpo del bucle no ha sido evaluado aún. La clase `LoopUnlessCond` tiene un método `unless` el cual puede ser usado como un *operador de infijo (infix)*. De esta manera podemos lograr una sintaxis muy natural para nuestro nuevo bucle `repetir { a_menos_que ( )`. - -A continuación se expone el resultado de la ejecución de `TargetTest2`: - - i = 10 - i = 9 - i = 8 - i = 7 - i = 6 - i = 5 - i = 4 - i = 3 - i = 2 - i = 1 diff --git a/_es/tour/basics.md b/_es/tour/basics.md index bd86428a9b..484470a508 100644 --- a/_es/tour/basics.md +++ b/_es/tour/basics.md @@ -1,9 +1,308 @@ --- layout: tour title: Basics - -discourse: false - partof: scala-tour language: es + +num: 2 +next-page: unified-types +previous-page: tour-of-scala --- + +En esta página, practicaremos conceptos básicos de Scala. + +## Probando Scala en el navegador + +Puedes ejecutar Scala en tu navegador con Scastie. + +1. Ve a [Scastie](https://scastie.scala-lang.org/). +2. Escribe `println("Hello, world!")` en el panel a la izquierda. +3. Presiona el botón "Run". En el panel de la derecha aparecerá el resultado. + +Así, de manera fácil y sin preparación, puedes probar fragmentos de código Scala. + +## Expresiones + +Las expresiones son sentencias computables. + +```scala mdoc +1 + 1 +``` + +Se puede ver el resultado de evaluar expresiones usando `println`. + +```scala mdoc +println(1) // 1 +println(1 + 1) // 2 +println("Hello!") // Hello! +println("Hello," + " world!") // Hello, world! +``` + +## Valores + +Se puede dar un nombre al resultado de una expresión usando la palabra reservada `val`. + +```scala mdoc +val x = 1 + 1 +println(x) // 2 +``` + +Los resultados con nombre, como `x` en el ejemplo, son llamados valores. Referenciar un valor no lo vuelve a computar. + +Los valores no pueden ser reasignados. + +```scala mdoc:fail +x = 3 // This does not compile. +``` + +Scala es capaz de inferir el tipo de un valor. Aun así, también se puede indicar el tipo usando una anotación: + +```scala mdoc:nest +val x: Int = 1 + 1 +``` + +Nótese que la anotación del tipo `Int` sigue al identificador `x` de la variable, separado por dos puntos `:`. + +## Variables + +Una variable es como un valor, excepto que a una variable se le puede re-asignar un valor después de declararla. Una variable se declara con la palabra reservada `var`. + +```scala mdoc:nest +var x = 1 + 1 +x = 3 // This compiles because "x" is declared with the "var" keyword. +println(x * x) // 9 +``` + +Como con los valores, si se quiere se puede especificar el tipo de una variable mutable: + +```scala mdoc:nest +var x: Int = 1 + 1 +``` + +## Bloques + +Se pueden combinar expresiones rodeándolas con `{}` . A esto le llamamos un bloque. + +El resultado de la última expresión del bloque es también el resultado total del bloque. + +```scala mdoc +println({ + val x = 1 + 1 + x + 1 +}) // 3 +``` + +## Funciones + +Una función es una expresión que acepta parámetros. + +Una función se puede declarar anónima, sin nombre. Por ejemplo, ésta es una función que acepta un número entero `x`, y devuelve el resultado de incrementarlo: + +```scala mdoc +(x: Int) => x + 1 +``` + +La lista de parámetros de la función está a la izquierda de la flecha `=>`, y a su derecha está el cuerpo de la función. + +También podemos asignarle un nombre a la función. + +```scala mdoc +val addOne = (x: Int) => x + 1 +println(addOne(1)) // 2 +``` + +Las funciones pueden tomar varios parámetros. + +```scala mdoc +val add = (x: Int, y: Int) => x + y +println(add(1, 2)) // 3 +``` + +O ninguno. + +```scala mdoc +val getTheAnswer = () => 42 +println(getTheAnswer()) // 42 +``` + +## Métodos + +Los métodos se parecen y comportan casi como a las funciones, pero se diferencian en dos aspectos clave: + +Un método se define con la palabra reservada `def`, seguida por el nombre del método, la lista de parámetros, el tipo de valores que el método devuelve, y el cuerpo del método. + +```scala mdoc:nest +def add(x: Int, y: Int): Int = x + y +println(add(1, 2)) // 3 +``` + +Observe que el tipo de retorno se declara _después_ de la lista de parámetros, y separado con dos puntos, p.ej. `: Int`. + +Un método puede tener varias listas de parámetros. + +```scala mdoc +def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier +println(addThenMultiply(1, 2)(3)) // 9 +``` + +O ninguna lista de parámetros. + +```scala mdoc +def name: String = System.getProperty("user.name") +println("Hello, " + name + "!") +``` + +Hay otras diferencias, pero para simplificar, podemos pensar que son similares a las funciones. + +Los métodos también pueden tener expresiones de varias lineas. + +```scala mdoc +def getSquareString(input: Double): String = { + val square = input * input + square.toString +} +println(getSquareString(2.5)) // 6.25 +``` + +La ultima expresión en el cuerpo del método es el valor de retorno del mismo. +(Scala tiene una palabra reservada `return`, pero se usa raramente y no se aconseja usarla) + +## Clases + +Una clase se define con la palabra reservada `class`, seguida del nombre, y la lista de parámetros del constructor. + +```scala mdoc +class Greeter(prefix: String, suffix: String) { + def greet(name: String): Unit = + println(prefix + name + suffix) +} +``` + +El método `greet` tiene un tipo de retorno `Unit`, que indica que el método no tiene nada significativo que devolver. Esto es similar al tipo `void` en C, C++, o Java. La diferencia con estos lenguajes es que en Scala toda expresión debe devolver un valor. Por ello, se usa un tipo `Unit` que tiene con un solo valor que se escribe `()` y no lleva información. + +Se puede crear una instancia de una clase con la palabra reservada *new*. + +```scala mdoc +val greeter = new Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` + +Las clases se tratan en profundidad [más adelante](classes.html). + +## Case Classes + +Hay un tipo especial de clases en Scala, las llamadas "case" classes. Por defecto, las instancias de una case class son inmutables, y se comparan con otras solo por los valores que contienen en cada campo. +Una case class se define con las palabras reservadas `case class`: + +```scala mdoc +case class Point(x: Int, y: Int) +``` + +Se puede crear una instancia de una `case class`, sin usar la palabra reservada `new`. + +```scala mdoc +val point = Point(1, 2) +val anotherPoint = Point(1, 2) +val yetAnotherPoint = Point(2, 2) +``` + +Y son comparadas por valor. + +```scala mdoc +if (point == anotherPoint) { + println(s"$point and $anotherPoint are the same.") +} else { + println(s"$point and $anotherPoint are different.") +} // Point(1,2) and Point(1,2) are the same. + +if (point == yetAnotherPoint) { + println(s"$point and $yetAnotherPoint are the same.") +} else { + println(s"$point and $yetAnotherPoint are different.") +} // Point(1,2) and Point(2,2) are different. +``` + +Hay mucho más sobre las case classes que queremos presentar, y estamos convencidos de que te vas a enamorar de ellas. Se tratan con más detalle [mas adelante](case-classes.html). + +## Objetos + +Los objetos son instancias de una sola clase de su propia definición. Puedes pensar en ellos como _singleton_ de sus propias clases. + +Un objeto se define usando la palabra reservada `object`. + +```scala mdoc +object IdFactory { + private var counter = 0 + def create(): Int = { + counter += 1 + counter + } +} +``` + +Para acceder al objeto, lo referencias por su nombre. + +```scala mdoc +val newId: Int = IdFactory.create() +println(newId) // 1 +val newerId: Int = IdFactory.create() +println(newerId) // 2 +``` + +Cubriremos los objetos en profundidad [más adelante](singleton-objects.html). + +## Traits + +Los traits son tipos que contienen campos y métodos. Se pueden combinar múltiples traits. + +Un trait se define usando la palabra reservada `trait`. + +```scala mdoc:nest +trait Greeter { + def greet(name: String): Unit +} +``` + +Un `trait` también puede definir un método, o un valor, con una implementación por defecto. + +```scala mdoc:reset +trait Greeter { + def greet(name: String): Unit = + println("Hello, " + name + "!") +} +``` + +Un `trait` también puede extender otros traits, usando la palabra clave `extends`. Asimismo, en un `trait` se puede redefinir la implementación de un método heredado, usando la palabra reservada `override`. + +```scala mdoc +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { + override def greet(name: String): Unit = { + println(prefix + name + postfix) + } +} + +val greeter = new DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = new CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` + +Aquí, `DefaultGreeter` extiende un solo trait, pero puede extender múltiples traits. + +Los `traits` se tratan con detalle [en otra página](traits.html). + +## Método principal (Main Method) + +El método principal (main) es el punto donde comienza la ejecución de un programa en Scala. La máquina virtual de java (_Java Virtual Machine_ or JVM) requiere, para ejecutar un código Scala, que éste tenga un método principal llamado `main` cuyo único parámetro sea un arrray de Strings. + +Usando un objeto, puedes definir el método principal de la siguiente forma: + +```scala mdoc +object Main { + def main(args: Array[String]): Unit = + println("Hello, Scala developer!") +} +``` diff --git a/_es/tour/by-name-parameters.md b/_es/tour/by-name-parameters.md index da953ddcb4..24f1e0cd23 100644 --- a/_es/tour/by-name-parameters.md +++ b/_es/tour/by-name-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: By-name Parameters - -discourse: false - partof: scala-tour language: es --- diff --git a/_es/tour/case-classes.md b/_es/tour/case-classes.md index 4e4a203b20..7a4989bde5 100644 --- a/_es/tour/case-classes.md +++ b/_es/tour/case-classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Clases Case - -discourse: false - partof: scala-tour num: 5 @@ -13,7 +10,7 @@ next-page: compound-types previous-page: classes --- -Scala da soporte a la noción de _clases caso_ (en inglés _case classes_, desde ahora _clases Case_). Las clases Case son clases regulares las cuales exportan sus parámetros constructores y a su vez proveen una descomposición recursiva de sí mismas a través de [reconocimiento de patrones](pattern-matching.html). +Scala da soporte a la noción de _clases case_ (en inglés _case classes_, desde ahora _clases Case_). Las clases Case son clases regulares las cuales exportan sus parámetros constructores y a su vez proveen una descomposición recursiva de sí mismas a través de [reconocimiento de patrones](pattern-matching.html). A continuación se muestra un ejemplo para una jerarquía de clases la cual consiste de una super clase abstracta llamada `Term` y tres clases concretas: `Var`, `Fun` y `App`. @@ -22,7 +19,7 @@ A continuación se muestra un ejemplo para una jerarquía de clases la cual cons case class Fun(arg: String, body: Term) extends Term case class App(f: Term, v: Term) extends Term -Esta jerarquía de clases puede ser usada para representar términos de [cálculo lambda no tipado](http://www.ezresult.com/article/Lambda_calculus). Para facilitar la construcción de instancias de clases Case, Scala no requiere que se utilice la primitiva `new`. Simplemente es posible utilizar el nombre de la clase como una llamada a una función. +Esta jerarquía de clases puede ser usada para representar términos de [cálculo lambda no tipado](https://es.wikipedia.org/wiki/C%C3%A1lculo_lambda). Para facilitar la construcción de instancias de clases Case, Scala no requiere que se utilice la primitiva `new`. Simplemente es posible utilizar el nombre de la clase como una llamada a una función. Aquí un ejemplo: @@ -76,6 +73,8 @@ Solo tiene sentido definir una clase Case si el reconocimiento de patrones es us println(isIdentityFun(t)) } -En nuestro ejemplo, la función `printTerm` es expresada como una sentencia basada en reconocimiento de patrones, la cual comienza con la palabra reservada `match` y consiste en secuencias de sentencias tipo `case PatronBuscado => Código que se ejecuta`. +En nuestro ejemplo, la función `printTerm` es expresada como una sentencia basada en reconocimiento de patrones, la cual comienza con la palabra reservada `match` y consiste en secuencias de sentencias tipo `case PatrónBuscado => Código que se ejecuta`. -El programa de arriba también define una función `isIdentityFun` la cual comprueba si un término dado se corresponde con una función identidad simple. Ese ejemplo utiliza patrones y guardas más avanzados (obsrvese la guarda `if x==y`). Tras reconocer un patrón con un valor dado, la guarda (definida después de la palabra clave `if`) es evaluada. Si retorna `true` (verdadero), el reconocimiento es exitoso; de no ser así, falla y se intenta con el siguiente patrón. +El programa de arriba también define una función `isIdentityFun` la cual comprueba si un término dado se corresponde con una función identidad simple. Ese ejemplo utiliza patrones y comparaciones más avanzadas (obsérvese la guarda `if x==y`). +Tras reconocer un patrón con un valor dado, se evalúa la comparación (definida después de la palabra clave `if`). +Si retorna `true` (verdadero), el reconocimiento es exitoso; de no ser así, falla y se intenta con el siguiente patrón. diff --git a/_es/tour/classes.md b/_es/tour/classes.md index 1ed2c731dc..3f3939b3bc 100644 --- a/_es/tour/classes.md +++ b/_es/tour/classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Clases - -discourse: false - partof: scala-tour num: 4 @@ -32,7 +29,7 @@ Las clases en Scala son parametrizadas con argumentos constructores (inicializad Para instanciar una clase es necesario usar la primitiva `new`, como se muestra en el siguiente ejemplo: object Classes { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val pt = new Point(1, 2) println(pt) pt.move(10, 10) diff --git a/_es/tour/compound-types.md b/_es/tour/compound-types.md index a60e7b54b5..9173b7ff1c 100644 --- a/_es/tour/compound-types.md +++ b/_es/tour/compound-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Tipos Compuestos - -discourse: false - partof: scala-tour num: 6 @@ -44,4 +41,4 @@ Los tipos compuestos pueden crearse a partir de varios tipos de objeto y pueden La forma general es: `A with B with C ... { refinamiento }` -Un ejemplo del uso de los refinamientos se muestra en la página sobre [tipos abstractos](abstract-types.html). +Un ejemplo del uso de los refinamientos se muestra en la página sobre [tipos abstractos](abstract-type-members.html). diff --git a/_es/tour/default-parameter-values.md b/_es/tour/default-parameter-values.md index 4a34538fce..f4fe5322f2 100644 --- a/_es/tour/default-parameter-values.md +++ b/_es/tour/default-parameter-values.md @@ -1,9 +1,6 @@ --- layout: tour title: Valores de parámetros por defecto - -discourse: false - partof: scala-tour num: 34 @@ -66,4 +63,4 @@ Scala cuenta con soporte directo para esto: // mediante parametros nombrados val m4 = new HashMap[String,Int](loadFactor = 0.8) -Nótese cómo podemos sacar ventaja de cualquier valor por defecto al utilizar [parámetros nombrados]({{ site.baseurl }}/tutorials/tour/named-arguments.html). +Nótese cómo podemos sacar ventaja de cualquier valor por defecto al utilizar [parámetros nombrados]({{ site.baseurl }}/es/tour/named-arguments.html). diff --git a/_es/tour/extractor-objects.md b/_es/tour/extractor-objects.md index 5f1d180488..a59c93558a 100644 --- a/_es/tour/extractor-objects.md +++ b/_es/tour/extractor-objects.md @@ -1,9 +1,6 @@ --- layout: tour title: Objetos Extractores - -discourse: false - partof: scala-tour num: 8 diff --git a/_es/tour/for-comprehensions.md b/_es/tour/for-comprehensions.md index 55903d9f1b..55f16ee7d6 100644 --- a/_es/tour/for-comprehensions.md +++ b/_es/tour/for-comprehensions.md @@ -1,9 +1,6 @@ --- layout: tour title: For Comprehensions - -discourse: false - partof: scala-tour language: es --- diff --git a/_es/tour/generic-classes.md b/_es/tour/generic-classes.md index 5236628353..b89b603ae3 100644 --- a/_es/tour/generic-classes.md +++ b/_es/tour/generic-classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Clases genéricas - -discourse: false - partof: scala-tour num: 9 @@ -17,12 +14,15 @@ Tal como en Java 5, Scala provee soporte nativo para clases parametrizados con t A continuación se muestra un ejemplo: - class Stack[T] { - var elems: List[T] = Nil - def push(x: T) { elems = x :: elems } - def top: T = elems.head - def pop() { elems = elems.tail } - } +```scala mdoc +class Stack[T] { + var elems: List[T] = Nil + def push(x: T): Unit = + elems = x :: elems + def top: T = elems.head + def pop(): Unit = { elems = elems.tail } +} +``` La clase `Stack` modela una pila mutable que contiene elementos de un tipo arbitrario `T` (se dice, "una pila de elementos `T`). Los parámetros de tipos nos aseguran que solo elementos legales (o sea, del tipo `T`) sean insertados en la pila (apilados). De forma similar, con los parámetros de tipo podemos expresar que el método `top` solo devolverá elementos de un tipo dado (en este caso `T`). diff --git a/_es/tour/higher-order-functions.md b/_es/tour/higher-order-functions.md index 899dca2139..c9e0a9e44b 100644 --- a/_es/tour/higher-order-functions.md +++ b/_es/tour/higher-order-functions.md @@ -1,9 +1,6 @@ --- layout: tour title: Funciones de orden superior - -discourse: false - partof: scala-tour num: 18 diff --git a/_es/tour/implicit-conversions.md b/_es/tour/implicit-conversions.md index 1979510108..a0e254a3ca 100644 --- a/_es/tour/implicit-conversions.md +++ b/_es/tour/implicit-conversions.md @@ -1,9 +1,6 @@ --- layout: tour title: Implicit Conversions - -discourse: false - partof: scala-tour num: 32 diff --git a/_es/tour/implicit-parameters.md b/_es/tour/implicit-parameters.md index 581593a7c3..f6c52d5c8a 100644 --- a/_es/tour/implicit-parameters.md +++ b/_es/tour/implicit-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: Parámetros implícitos - -discourse: false - partof: scala-tour num: 10 diff --git a/_es/tour/inner-classes.md b/_es/tour/inner-classes.md index c072021dc8..9b04862d27 100644 --- a/_es/tour/inner-classes.md +++ b/_es/tour/inner-classes.md @@ -1,58 +1,61 @@ --- layout: tour title: Clases Internas - -discourse: false - partof: scala-tour num: 11 language: es -next-page: mixin-class-composition +next-page: tuples previous-page: implicit-parameters --- En Scala es posible que las clases tengan como miembro otras clases. A diferencia de lenguajes similares a Java donde ese tipo de clases internas son miembros de las clases que las envuelven, en Scala esas clases internas están ligadas al objeto externo. Para ilustrar esta diferencia, vamos a mostrar rápidamente una implementación del tipo grafo: - class Graph { - class Node { - var connectedNodes: List[Node] = Nil - def connectTo(node: Node) { - if (connectedNodes.find(node.equals).isEmpty) { - connectedNodes = node :: connectedNodes - } - } - } - var nodes: List[Node] = Nil - def newNode: Node = { - val res = new Node - nodes = res :: nodes - res +```scala mdoc +class Graph { + class Node { + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes } } + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` En nuestro programa, los grafos son representados mediante una lista de nodos. Estos nodos son objetos de la clase interna `Node`. Cada nodo tiene una lista de vecinos que se almacena en la lista `connectedNodes`. Ahora podemos crear un grafo con algunos nodos y conectarlos incrementalmente: - object GraphTest extends App { - val g = new Graph - val n1 = g.newNode - val n2 = g.newNode - val n3 = g.newNode - n1.connectTo(n2) - n3.connectTo(n1) - } +```scala mdoc:nest +def graphTest: Unit = { + val g = new Graph + val n1 = g.newNode + val n2 = g.newNode + val n3 = g.newNode + n1.connectTo(n2) + n3.connectTo(n1) +} +``` Ahora vamos a completar el ejemplo con información relacionada al tipado para definir explicitamente de qué tipo son las entidades anteriormente definidas: - object GraphTest extends App { - val g: Graph = new Graph - val n1: g.Node = g.newNode - val n2: g.Node = g.newNode - val n3: g.Node = g.newNode - n1.connectTo(n2) - n3.connectTo(n1) - } +```scala mdoc:nest +def graphTest: Unit = { + val g: Graph = new Graph + val n1: g.Node = g.newNode + val n2: g.Node = g.newNode + val n3: g.Node = g.newNode + n1.connectTo(n2) + n3.connectTo(n1) +} +``` El código anterior muestra que al tipo del nodo le es prefijado con la instancia superior (que en nuestro ejemplo es `g`). Si ahora tenemos dos grafos, el sistema de tipado de Scala no nos permite mezclar nodos definidos en un grafo con nodos definidos en otro, ya que los nodos del otro grafo tienen un tipo diferente. @@ -73,8 +76,8 @@ Por favor note que en Java la última linea del ejemplo anterior hubiese sido co class Graph { class Node { var connectedNodes: List[Graph#Node] = Nil // Graph#Node en lugar de Node - def connectTo(node: Graph#Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } diff --git a/_es/tour/lower-type-bounds.md b/_es/tour/lower-type-bounds.md index 0fc3b5aba5..1ba22280af 100644 --- a/_es/tour/lower-type-bounds.md +++ b/_es/tour/lower-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: Límite de tipado inferior - -discourse: false - partof: scala-tour num: 26 diff --git a/_es/tour/mixin-class-composition.md b/_es/tour/mixin-class-composition.md index 6343e0a7c6..bd53274158 100644 --- a/_es/tour/mixin-class-composition.md +++ b/_es/tour/mixin-class-composition.md @@ -1,16 +1,13 @@ --- layout: tour title: Composición de clases mixin - -discourse: false - partof: scala-tour num: 12 language: es next-page: singleton-objects -previous-page: inner-classes +previous-page: tuples --- _Nota de traducción: La palabra `mixin` puede ser traducida como mezcla, dando título a esta sección de: Composición de clases Mezcla, pero es preferible utilizar la notación original_ @@ -25,7 +22,7 @@ A diferencia de lenguajes que solo soportan _herencia simple_, Scala tiene una n A continuación, considere una clase mezcla la cual extiende `AbsIterator` con un método `foreach` el cual aplica una función dada a cada elemento retornado por el iterador. Para definir una clase que puede usarse como una clase mezcla usamos la palabra clave `trait`. trait RichIterator extends AbsIterator { - def foreach(f: T => Unit) { while (hasNext) f(next()) } + def foreach(f: T => Unit): Unit = { while (hasNext) f(next()) } } Aquí se muestra una clase iterador concreta, la cual retorna caracteres sucesivos de una cadena de caracteres dada: @@ -40,7 +37,7 @@ Aquí se muestra una clase iterador concreta, la cual retorna caracteres sucesiv Nos gustaría combinar la funcionalidad de `StringIterator` y `RichIterator` en una sola clase. Solo con herencia simple e interfaces esto es imposible, ya que ambas clases contienen implementaciones para sus miembros. Scala nos ayuda con sus _compisiciones de clases mezcladas_. Permite a los programadores reutilizar el delta de la definición de una clase, esto es, todas las nuevas definiciones que no son heredadas. Este mecanismo hace posible combinar `StringIterator` con `RichIterator`, como es hecho en el siguiente programa, el cual imprime una columna de todos los caracteres de una cadena de caracteres dada. object StringIteratorTest { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { class Iter extends StringIterator("Scala") with RichIterator val iter = new Iter iter foreach println diff --git a/_es/tour/multiple-parameter-lists.md b/_es/tour/multiple-parameter-lists.md index 9eff54f5b1..83b7218c0b 100644 --- a/_es/tour/multiple-parameter-lists.md +++ b/_es/tour/multiple-parameter-lists.md @@ -1,24 +1,41 @@ --- layout: tour title: Currying - -discourse: false - partof: scala-tour num: 15 language: es -next-page: automatic-closures +next-page: operators previous-page: nested-functions --- -_Nota de traducción: Currying es una técnica de programación funcional nombrada en honor al matemático y lógico Haskell Curry. Es por eso que no se intentará hacer ninguna traducción sobre el término Currying. Entiendase este como una acción, técnica base de PF. Como una nota al paso, el lenguaje de programación Haskell debe su nombre a este eximio matemático._ +_Nota de traducción: Currying es una técnica de programación funcional nombrada en honor al matemático y lógico Haskell Curry. Es por eso que no se intentará hacer ninguna traducción sobre el término Currying. Entiéndase este como una acción, técnica base de PF. Como una nota al paso, el lenguaje de programación Haskell debe su nombre a este eximio matemático._ Los métodos pueden definir múltiples listas de parámetros. Cuando un método es invocado con un número menor de listas de parámetros, en su lugar se devolverá una función que toma las listas faltantes como sus argumentos. -Aquí se muestra un ejemplo: +### Ejemplos + +A continuación hay un ejemplo, tal y como se define en el trait `TraversableOnce` en el API de colecciones de Scala: + +```scala mdoc:fail +def foldLeft[B](z: B)(op: (B, A) => B): B +``` + +`foldLeft` aplica una función (que recibe dos parámetros) `op` a un valor inicial `z` y todos los elementos de esta colección, de izquierda a derecha. A continuación se muestra un ejemplo de su uso. + +Comenzando con un valor inicial 0, `foldLeft` aplica la función `(m, n) => m + n` a cada uno de los elementos de la lista y al valor acumulado previo. + +```scala mdoc +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val res = numbers.foldLeft(0)((m, n) => m + n) +println(res) // 55 +``` + +A continuación se muestra otro ejemplo: + +```scala mdoc object CurryTest extends App { def filter(xs: List[Int], p: Int => Boolean): List[Int] = @@ -32,10 +49,78 @@ Aquí se muestra un ejemplo: println(filter(nums, modN(2))) println(filter(nums, modN(3))) } +``` -_Nota: el método `modN` está parcialmente aplicado en las dos llamadas a `filter`; esto significa que solo su primer argumento es realmente aplicado. El término `modN(2)` devuelve una función de tipo `Int => Boolean` y es por eso un posible candidato para el segundo argumento de la función `filter`_ +_Nota: el método `modN` está parcialmente aplicado en las dos llamadas a `filter`; esto significa que solo su primer argumento es realmente aplicado. El término `modN(2)` devuelve una función de tipo `Int => Boolean` y es por eso un posible candidato para el segundo argumento de la función `filter`._ Aquí se muestra la salida del programa anterior: - List(2,4,6,8) - List(3,6) +```scala mdoc +List(2,4,6,8) +List(3,6) +``` + +### Casos de uso + +Casos de uso sugeridos para múltiples listas de parámetros incluyen: + +#### Inferencia de tipos + +En Scala, la inferencia de tipos se realiza parámetro a parámetro. +Suponer que se dispone del siguiente método: + +```scala mdoc +def foldLeft1[A, B](as: List[A], b0: B, op: (B, A) => B) = ??? +``` + +Si se invoca de la siguiente manera, se puede comprobar que no compila correctamente: + +```scala mdoc:fail +def notPossible = foldLeft1(numbers, 0, _ + _) +``` + +Debes invocarlo de alguna de las maneras propuestas a continuación: + +```scala mdoc +def firstWay = foldLeft1[Int, Int](numbers, 0, _ + _) +def secondWay = foldLeft1(numbers, 0, (a: Int, b: Int) => a + b) +``` + +Esto se debe a que Scala no será capaz de inferir el tipo de la función `_ + _`, como está aún infiriendo `A` y `B`. +Moviéndo el parámetro `op` a su propia lista de parámetros, los tipos de `A` y `B` son inferidos en la primera lista de parámetros. +Una vez se han inferido sus tipos, estos están disponibles para la segunda lista de parámetros y `_ + _ ` podrá casar con los tipos inferidos `(Int, Int) => Int` + +```scala mdoc +def foldLeft2[A, B](as: List[A], b0: B)(op: (B, A) => B) = ??? +def possible = foldLeft2(numbers, 0)(_ + _) +``` + +Esta definición no necesita de ninguna pista adicional y puede inferir todos los tipos de los parámetros. + + +#### Parámetros implícitos + +Para especificar solamente ciertos parámetros como [`implicit`](https://docs.scala-lang.org/tour/implicit-parameters.html), ellos deben ser colocados en su propia lista de parámetros implícitos (`implicit`). + +Un ejemplo de esto se muestra a continuación: + +```scala mdoc +def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ??? +``` + +#### Aplicación parcial + +Cuando un método es invocado con menos parámetros que los que están declarados en la definición del método, esto generará una función que toma los parámetros faltantes como argumentos. Esto se conoce formalmente como [aplicación parcial](https://en.wikipedia.org/wiki/Partial_application). + +Por ejemplo, + +```scala mdoc:nest +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]()) _ + +val squares = numberFunc((xs, x) => xs :+ x*x) +println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) + +val cubes = numberFunc((xs, x) => xs :+ x*x*x) +println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` diff --git a/_es/tour/named-arguments.md b/_es/tour/named-arguments.md index ab289648a7..fe38fe15d4 100644 --- a/_es/tour/named-arguments.md +++ b/_es/tour/named-arguments.md @@ -1,9 +1,6 @@ --- layout: tour title: Parámetros nombrados - -discourse: false - partof: scala-tour num: 35 @@ -14,24 +11,24 @@ previous-page: default-parameter-values En la invocación de métodos y funciones se puede usar el nombre de las variables explícitamente en la llamada, de la siguiente manera: - def imprimirNombre(nombre:String, apellido:String) = { + def imprimirNombre(nombre: String, apellido: String) = { println(nombre + " " + apellido) } imprimirNombre("John","Smith") // Imprime "John Smith" - imprimirNombre(first = "John",last = "Smith") + imprimirNombre(nombre = "John", apellido = "Smith") // Imprime "John Smith" - imprimirNombre(last = "Smith",first = "John") + imprimirNombre(apellido = "Smith", nombre = "John") // Imprime "John Smith" Note que una vez que se utilizan parámetros nombrados en la llamada, el orden no importa, mientras todos los parámetros sean nombrados. Esta característica funciona bien en conjunción con valores de parámetros por defecto: - def imprimirNombre(nombre:String = "John", apellido:String = "Smith") = { + def imprimirNombre(nombre: String = "John", apellido: String = "Smith") = { println(nombre + " " + apellido) } - printName(apellido = "Jones") + imprimirNombre(apellido = "Jones") // Imprime "John Jones" language: es diff --git a/_es/tour/nested-functions.md b/_es/tour/nested-functions.md index 3813a2b905..2e77eb4ea4 100644 --- a/_es/tour/nested-functions.md +++ b/_es/tour/nested-functions.md @@ -1,9 +1,6 @@ --- layout: tour title: Funciones Anidadas - -discourse: false - partof: scala-tour num: 13 diff --git a/_es/tour/operators.md b/_es/tour/operators.md index fa7c55cf65..6aeb98e046 100644 --- a/_es/tour/operators.md +++ b/_es/tour/operators.md @@ -1,16 +1,13 @@ --- layout: tour title: Operadores - -discourse: false - partof: scala-tour num: 17 language: es next-page: higher-order-functions -previous-page: automatic-closures +previous-page: multiple-parameter-lists --- En Scala, cualquier método el cual reciba un solo parámetro puede ser usado como un *operador de infijo (infix)*. Aquí se muestra la definición de la clase `MyBool`, la cual define tres métodos `and`, `or`, y `negate`. diff --git a/_es/tour/package-objects.md b/_es/tour/package-objects.md new file mode 100644 index 0000000000..3878959d9e --- /dev/null +++ b/_es/tour/package-objects.md @@ -0,0 +1,14 @@ +--- +layout: tour +title: Package Objects +language: es +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- + +# Package objects + +(this section of the tour has not been translated yet. pull request +with translation welcome!) diff --git a/_es/tour/packages-and-imports.md b/_es/tour/packages-and-imports.md index 6f1e51d951..d65092cb46 100644 --- a/_es/tour/packages-and-imports.md +++ b/_es/tour/packages-and-imports.md @@ -2,14 +2,11 @@ layout: tour title: Packages and Imports language: es - -discourse: true - partof: scala-tour num: 35 previous-page: named-arguments -next-page: type-inference +next-page: package-objects --- # Packages and Imports diff --git a/_es/tour/pattern-matching.md b/_es/tour/pattern-matching.md index d20d83bf56..40e733df7a 100644 --- a/_es/tour/pattern-matching.md +++ b/_es/tour/pattern-matching.md @@ -1,9 +1,6 @@ --- layout: tour title: Reconocimiento de patrones - -discourse: false - partof: scala-tour num: 20 diff --git a/_es/tour/polymorphic-methods.md b/_es/tour/polymorphic-methods.md index c14ca2a18d..ec656e9f8b 100644 --- a/_es/tour/polymorphic-methods.md +++ b/_es/tour/polymorphic-methods.md @@ -1,9 +1,6 @@ --- layout: tour title: Métodos polimórficos - -discourse: false - partof: scala-tour num: 21 diff --git a/_es/tour/regular-expression-patterns.md b/_es/tour/regular-expression-patterns.md index bb0571a27a..7631ce9397 100644 --- a/_es/tour/regular-expression-patterns.md +++ b/_es/tour/regular-expression-patterns.md @@ -1,9 +1,6 @@ --- layout: tour title: Patrones basados en expresiones regulares - -discourse: false - partof: scala-tour num: 22 diff --git a/_es/tour/self-types.md b/_es/tour/self-types.md index fa430d4887..df02b7dc0a 100644 --- a/_es/tour/self-types.md +++ b/_es/tour/self-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Autorefrencias explicitamente tipadas - -discourse: false - partof: scala-tour num: 27 @@ -28,7 +25,7 @@ Aquí hay una definición que sirve para describir un grafo: def agregarNodo: Nodo } -Los grafos consisten de una lista de nodos y vértices (o aristas en alguna bibliografía) donde tanto el tipo nodo, como el vértice fueron declarados abstractos. El uso de [tipos abstractos](abstract-types.html) permite las implementaciones del trait `Grafo` proveer sus propias clases concretas para nodos y vértices. Además, existe un método `agregarNodo` para agregar nuevos nodos al grafo. Los nodos se conectan entre sí utilizando el método `conectarCon`. +Los grafos consisten de una lista de nodos y vértices (o aristas en alguna bibliografía) donde tanto el tipo nodo, como el vértice fueron declarados abstractos. El uso de [tipos abstractos](abstract-type-members.html) permite las implementaciones del trait `Grafo` proveer sus propias clases concretas para nodos y vértices. Además, existe un método `agregarNodo` para agregar nuevos nodos al grafo. Los nodos se conectan entre sí utilizando el método `conectarCon`. Una posible implementación de la clase `Grafo`es dada en el siguiente programa: @@ -94,7 +91,7 @@ Por favor nótese que en esta clase nos es posible instanciar `NodoImpl` porque Aquí hay un ejemplo de uso de la clase `GrafoDirigidoConcreto`: - object GraphTest extends App { + def graphTest: Unit = { val g: Grafo = new GrafoDirigidoConcreto val n1 = g.agregarNodo val n2 = g.agregarNodo diff --git a/_es/tour/singleton-objects.md b/_es/tour/singleton-objects.md index 021b413912..dceed2d7ad 100644 --- a/_es/tour/singleton-objects.md +++ b/_es/tour/singleton-objects.md @@ -1,9 +1,6 @@ --- layout: tour title: Singleton Objects - -discourse: false - partof: scala-tour num: 12 @@ -25,11 +22,11 @@ Este método `sum` está disponible de manera global, y puede ser referenciado, Los objetos singleton son una especie de mezcla entre la definición de una clase de utilización única, la cual no pueden ser instanciada directamente, y un miembro `val`. De hecho, de la misma menera que los `val`, los objetos singleton pueden ser definidos como miembros de un [trait](traits.html) o de una clase, aunque esto no es muy frecuente. -Un objeto singleton puede extender clases y _traits_. De hecho, una [clase Case](case-classes.html) sin [parámetros de tipo](generic-classes.html) generará por defecto un objeto singleton del mismo nombre, con una [`Función*`](http://www.scala-lang.org/api/current/scala/Function1.html) trait implementada. +Un objeto singleton puede extender clases y _traits_. De hecho, una [clase Case](case-classes.html) sin [parámetros de tipo](generic-classes.html) generará por defecto un objeto singleton del mismo nombre, con una [`Función*`](https://www.scala-lang.org/api/current/scala/Function1.html) trait implementada. ## Acompañantes ## -La mayoría de los objetos singleton no están solos, sino que en realidad están asociados con clases del mismo nombre. El "objeto singleton del mismo nombre" de una case Case, mencionada anteriormente es un ejemplo de esto. Cuando esto sucede, el objeto singleton es llamado el *objeto acompañante* de la clase, y la clase es a su vez llamada la *clase acompañante* del objeto. +La mayoría de los objetos singleton no están solos, sino que en realidad están asociados con clases del mismo nombre. El "objeto singleton del mismo nombre" de una clase Case, mencionada anteriormente es un ejemplo de esto. Cuando esto sucede, el objeto singleton es llamado el *objeto acompañante* de la clase, y la clase es a su vez llamada la *clase acompañante* del objeto. [Scaladoc](/style/scaladoc.html) proporciona un soporte especial para ir y venir entre una clase y su acompañante: Si el gran círculo conteniendo la “C” u la “O” tiene su borde inferior doblado hacia adentro, es posible hacer click en el círculo para ir a su acompañante. diff --git a/_es/tour/tour-of-scala.md b/_es/tour/tour-of-scala.md index e9c26f9e58..b742b271ab 100644 --- a/_es/tour/tour-of-scala.md +++ b/_es/tour/tour-of-scala.md @@ -1,48 +1,54 @@ --- layout: tour title: Introducción - -discourse: false - partof: scala-tour num: 1 language: es -next-page: abstract-types +next-page: basics + --- -Scala es un lenguaje de programación moderno multi-paradigma diseñado para expresar patrones de programación comunes de una forma concisa, elegante, y de tipado seguro. Integra fácilmente características de lenguajes orientados a objetos y funcionales. +Scala es un lenguaje de programación moderno multi-paradigma diseñado para expresar patrones de programación comunes de una forma concisa, elegante, y con tipado seguro. Integra fácilmente características de lenguajes orientados a objetos y funcionales. ## Scala es orientado a objetos ## Scala es un lenguaje puramente orientado a objetos en el sentido de que todo es un objeto. Los tipos y comportamientos de objetos son descritos por [clases](classes.html) y [traits](traits.html) (que podría ser traducido como un "rasgo"). Las clases pueden ser extendidas a través de subclases y un mecanismo flexible [de composición mezclada](mixin-class-composition.html) que provee un claro remplazo a la herencia múltiple. ## Scala es funcional ## -Scala es también un lenguaje funcional en el sentido que toda función es un valor. Scala provee una sintaxis ligera para definir funciones anónimas. Soporta [funciones de primer orden](higher-order-functions.html), permite que las funciones sean [anidadas](nested-functions.html), y soporta [currying](multiple-parameter-lists.html). Las [clases caso](case-classes.html) de Scala y las construcciones incorporadas al lenguaje para [reconocimiento de patrones](pattern-matching.html) modelan tipos algebráicos usados en muchos lenguajes de programación funcionales. +Scala es también un lenguaje funcional en el sentido que toda función es un valor. Scala provee una sintaxis ligera para definir funciones anónimas. Soporta [funciones de orden superior](higher-order-functions.html), permite funciones [anidadas](nested-functions.html), y soporta [currying](multiple-parameter-lists.html). Las [clases Case](case-classes.html) de Scala y las construcciones incorporadas al lenguaje para [reconocimiento de patrones](pattern-matching.html) modelan tipos algebraicos usados en muchos lenguajes de programación funcionales. -Además, la noción de reconocimiento de patrones de Scala se puede extender naturalmente al procesamiento de datos XML con la ayuda de [patrones de expresiones regulares](regular-expression-patterns.html). En este contexto, seq comprehensions resultan útiles para formular consultas. Estas características hacen a Scala ideal para desarrollar aplicaciones como Web Services. +Además, la noción de reconocimiento de patrones de Scala se puede extender naturalmente al procesamiento de datos XML con la ayuda de [patrones de expresiones regulares](regular-expression-patterns.html). En este contexto, la compresión de bucles `for` resultan útiles para formular consultas. Estas características hacen a Scala un lenguaje ideal para desarrollar aplicaciones como Web Services. ## Scala estáticamente tipado ## Scala cuenta con un expresivo sistema de tipado que fuerza estáticamente las abstracciones a ser usadas en una manera coherente y segura. En particular, el sistema de tipado soporta: * [Clases genéricas](generic-classes.html) * [anotaciones variables](variances.html), * límites de tipado [superiores](upper-type-bounds.html) e [inferiores](lower-type-bounds.html), -* [clases internas](inner-classes.html) y [tipos abstractos](abstract-types.html) como miembros de objetos, +* [clases internas](inner-classes.html) y [tipos abstractos](abstract-type-members.html) como miembros de objetos, * [tipos compuestos](compound-types.html) * [auto-referencias explicitamente tipadas](self-types.html) * [implicit conversions](implicit-conversions.html) * [métodos polimórficos](polymorphic-methods.html) -El [mecanismo de inferencia de tipos locales](type-inference.html) se encarga de que el usuario no tengan que anotar el programa con información redundante de tipado. Combinadas, estas características proveen una base poderosa para el reuso seguro de abstracciones de programación y para la extensión segura (en cuanto a tipos) de software. +El [mecanismo de inferencia de tipos locales](type-inference.html) se encarga de que el usuario no tenga que anotar el programa con información redundante de tipado. Combinadas, estas características proveen una base poderosa para la reutilización segura de abstracciones de programación y para la extensión segura (en cuanto a tipos) de software. ## Scala es extensible ## -En la práctica el desarrollo de aplicaciones específicas para un dominio generalmente requiere de "Lenguajes de dominio específico" (DSL). Scala provee una única combinación de mecanismos del lenguaje que simplifican la creación de construcciones propias del lenguaje en forma de librerías: +En la práctica, el desarrollo de aplicaciones específicas para un dominio generalmente requiere de "Lenguajes de dominio específico" (DSL). Scala provee una única combinación de mecanismos del lenguaje que simplifican la creación de construcciones propias del lenguaje en forma de bibliotecas: * cualquier método puede ser usado como un operador de [infijo o postfijo](operators.html) -* [las closures son construidas automáticamente dependiendo del tipo esperado](automatic-closures.html) (tipos objetivo). El uso conjunto de ambas características facilita la definición de nuevas sentencias sin tener que extender la sintaxis y sin usar facciones de meta-programación como tipo macros. -Scala está diseñado para interoperar bien con el popular Entorno de ejecución de Java 2 (JRE). En particular, la interacción con el lenguaje orientado a objetos Java es muy sencillo. Scala tiene el mismo esquema de compilación (compilación separada, carga de clases dinámica) que java y permite acceder a las miles de librerías de gran calidad existentes. +## Scala interopera + +Scala está diseñado para interoperar correctamente con la popular Java Runtime Environment (JRE). +En particular, es posible la misma interacción con el lenguaje de programación Java. +Nuevas características de Java como SAMs, [lambdas](higher-order-functions.html), [anotaciones](annotations.html), y [clases genéricas](generic-classes.html) tienen sus análogos en Scala. + +Aquellas características de Scala que no tienen analogías en Java, como por ejemplo [parámetros por defecto](default-parameter-values.html) y [parámetros con nombre](named-arguments.html), compilan de una forma tan similar a Java como es razonablemente posible. +Scala tiene el mismo modelo de compilación (compilación separada, carga de clases dinámica) que Java y permite acceder a miles de bibliotecas de alta calidad ya existentes. + +## ¡Disfruta el tour! Por favor continúe a la próxima página para conocer más. diff --git a/_es/tour/traits.md b/_es/tour/traits.md index 363fee8148..6c41030de5 100644 --- a/_es/tour/traits.md +++ b/_es/tour/traits.md @@ -1,9 +1,6 @@ --- layout: tour title: Traits - -discourse: false - partof: scala-tour num: 24 diff --git a/_es/tour/tuples.md b/_es/tour/tuples.md new file mode 100644 index 0000000000..27ba0d9819 --- /dev/null +++ b/_es/tour/tuples.md @@ -0,0 +1,91 @@ +--- +layout: tour +title: Tuples +partof: scala-tour +num: +language: es + +next-page: mixin-class-composition +previous-page: inner-classes + +--- + +En Scala, una tupla es un valor que contiene un número fijo de elementos, +cada uno de ellos puede ser de distinto tipo. Las tuplas son inmutables. + +Las tuplas son especialmente útiles para retornar múltiples valores desde +un método. + +Una tupla con dos elementos puede ser creada del siguiente modo: + +```scala mdoc +val ingredient = ("Sugar", 25) +``` + +Esta instrucción crea una tupla que contiene un elemento de tipo `String` +y un elemento de tipo `Int`. + +El tipo de la tupla `ingredient` se infiere que es`(String, Int)`, lo cual es +una abreviatura de `Tuple2[String, Int]`. + +Para representar tuplas, Scala utiliza una serie de clases: `Tuple2`, `Tuple3`, +etc., hasta `Tuple22`. +Cada clase tiene tantos parámetros como número de elementos. + +## Accediendo a los elementos + +Una forma de acceder a los elementos de una tupla es por posición. +Los elementos concretos se llaman `_1`, `_2`, y así sucesivamente. + +```scala mdoc +println(ingredient._1) // Sugar +println(ingredient._2) // 25 +``` + +## Reconocimiento de patrones en tuplas + +Una tupla también puede ser dividida/expandida usando reconocimiento de patrones (pattern matching): + +```scala mdoc +val (name, quantity) = ingredient +println(name) // Sugar +println(quantity) // 25 +``` + +En esta ocasión el tipo de `name` es inferido como `String` y el de +`quantity` como `Int`. + +A continuación otro ejemplo de reconocimiento de patrones con tuplas: + +```scala mdoc +val planets = + List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6), + ("Mars", 227.9), ("Jupiter", 778.3)) +planets.foreach{ + case ("Earth", distance) => + println(s"Nuestro planeta está a $distance millones de kilómetros del Sol.") + case _ => +} +``` + +O en compresión de bucles `for`: + +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) +for ((a, b) <- numPairs) { + println(a * b) +} +``` + +## Tuplas y case classes + +A veces los usuarios encuentran difícil elegir entre tuplas y clases Case. +Los elementos de las clases Case tienen nombre. Los nombres pueden mejorar +la lectura en el código. +En el ejemplo anterior de los planetas, podríamos haber definido +`case class Planet(name: String, distance: Double)` en vez de usar tuplas. + + +## Más recursos + +* Aprende más acerca de las tuplas en el [Scala Book](/overviews/scala-book/tuples.html) diff --git a/_es/tour/type-inference.md b/_es/tour/type-inference.md index 0bbf7400fa..67e0b52099 100644 --- a/_es/tour/type-inference.md +++ b/_es/tour/type-inference.md @@ -1,9 +1,6 @@ --- layout: tour title: Inferencia de tipos Local - -discourse: false - partof: scala-tour num: 29 @@ -33,7 +30,7 @@ Tampoco es obligatorio especificar el tipo de los parámetros cuando se trate de Aquí se muestra un ejemplo que ilustra esto: - case class MyPair[A, B](x: A, y: B); + case class MyPair[A, B](x: A, y: B) object InferenceTest3 extends App { def id[T](x: T) = x val p = MyPair(1, "scala") // tipo: MyPair[Int, String] diff --git a/_es/tour/unified-types.md b/_es/tour/unified-types.md index d2f8bc76c2..3a1db1e651 100644 --- a/_es/tour/unified-types.md +++ b/_es/tour/unified-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Tipos Unificados - -discourse: false - partof: scala-tour num: 30 @@ -20,7 +17,7 @@ A diferencia de Java, todos los valores en Scala son objetos (incluyendo valores ## Jerarquía de clases en Scala ## La superclase de todas las clases, `scala.Any`, tiene dos subclases directas, `scala.AnyVal` y `scala.AnyRef` que representan dos mundos de clases muy distintos: clases para valores y clases para referencias. Todas las clases para valores están predefinidas; se corresponden con los tipos primitivos de los lenguajes tipo Java. Todas las otras clases definen tipos referenciables. Las clases definidas por el usuario son definidas como tipos referenciables por defecto, es decir, siempre (indirectamente) extienden de `scala.AnyRef`. Toda clase definida por usuario en Scala extiende implicitamente el trait `scala.ScalaObject`. Clases pertenecientes a la infraestructura en la cual Scala esté corriendo (ejemplo, el ambiente de ejecución de Java) no extienden de `scala.ScalaObject`. Si Scala es usado en el contexto de un ambiente de ejecución de Java, entonces `scala.AnyRef` corresponde a `java.lang.Object`. -Por favor note que el diagrama superior también muestra conversiones implícitas llamadas viestas entre las clases para valores. +Por favor note que el diagrama superior también muestra conversiones implícitas llamadas vistas entre las clases para valores. Aquí se muestra un ejemplo que demuestra que tanto valores numéricos, de caracteres, buleanos y funciones son objetos, tal como cualquier otro objeto: diff --git a/_es/tour/upper-type-bounds.md b/_es/tour/upper-type-bounds.md index 84124c8944..663915f957 100644 --- a/_es/tour/upper-type-bounds.md +++ b/_es/tour/upper-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: Límite de tipado superior - -discourse: false - partof: scala-tour num: 25 @@ -13,7 +10,7 @@ next-page: lower-type-bounds previous-page: traits --- -En Scala, los [parámetros de tipo](generic-classes.html) y los [tipos abstractos](abstract-types.html) pueden ser restringidos por un límite de tipado. Tales límites de tipado limitan los valores concretos de las variables de tipo y posiblemente revelan más información acerca de los miembros de tales tipos. Un _límite de tipado superior_ `T <: A` declara que la variable de tipo `T` es un subtipo del tipo `A`. +En Scala, los [parámetros de tipo](generic-classes.html) y los [tipos abstractos](abstract-type-members.html) pueden ser restringidos por un límite de tipado. Tales límites de tipado limitan los valores concretos de las variables de tipo y posiblemente revelan más información acerca de los miembros de tales tipos. Un _límite de tipado superior_ `T <: A` declara que la variable de tipo `T` es un subtipo del tipo `A`. Aquí se muestra un ejemplo el cual se basa en un límite de tipado superior para la implementación del método polimórfico `findSimilar`: trait Similar { diff --git a/_es/tour/variances.md b/_es/tour/variances.md index e437375545..eb961061a8 100644 --- a/_es/tour/variances.md +++ b/_es/tour/variances.md @@ -1,9 +1,6 @@ --- layout: tour title: Varianzas - -discourse: false - partof: scala-tour num: 31 @@ -17,7 +14,7 @@ Scala soporta anotaciones de varianza para parámetros de tipo para [clases gen En el artículo sobre clases genéricas dimos un ejemplo de una pila mutable. Explicamos que el tipo definido por la clase `Stack[T]` es objeto de subtipos invariantes con respecto al parámetro de tipo. Esto puede restringir el reuso de la abstracción (la clase). Ahora derivaremos una implementación funcional (es decir, inmutable) para pilas que no tienen esta restricción. Nótese que este es un ejemplo avanzado que combina el uso de [métodos polimórficos](polymorphic-methods.html), [límites de tipado inferiores](lower-type-bounds.html), y anotaciones de parámetros de tipo covariante de una forma no trivial. Además hacemos uso de [clases internas](inner-classes.html) para encadenar los elementos de la pila sin enlaces explícitos. -```tut +```scala mdoc class Stack[+T] { def push[S >: T](elem: S): Stack[S] = new Stack[S] { override def top: S = elem diff --git a/_es/tutorials/scala-for-java-programmers.md b/_es/tutorials/scala-for-java-programmers.md index 71a7ba6023..120d93d316 100644 --- a/_es/tutorials/scala-for-java-programmers.md +++ b/_es/tutorials/scala-for-java-programmers.md @@ -3,8 +3,6 @@ layout: singlepage-overview title: Tutorial de Scala para programadores Java partof: scala-for-java-programmers - -discourse: true language: es --- @@ -13,14 +11,14 @@ Traducción y arreglos Santiago Basulto. ## Introducción -Este documento provee una rápida introducción al lenguaje Scala como también a su compilador. Está pensado para personas que ya poseen cierta experiencia en programación y quieren una vista rápida de lo que pueden hacer con Scala. Se asume como un conocimiento básico de programación orientada a objetos, especialmente en Java. +Este documento provee una rápida introducción al lenguaje Scala como también a su compilador. Está pensado para personas que ya poseen cierta experiencia en programación y quieren una vista rápida de lo que pueden hacer con Scala. Se asume un conocimiento básico de programación orientada a objetos, especialmente en Java. ## Un primer ejemplo Como primer ejemplo, usaremos el programa *Hola mundo* estándar. No es muy fascinante, pero de esta manera resulta fácil demostrar el uso de herramientas de Scala sin saber demasiado acerca del lenguaje. Veamos como luce: object HolaMundo { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { println("¡Hola, mundo!") } } @@ -35,7 +33,7 @@ El lector astuto notará que el método `main` no es declarado como `static`. Es Para compilar el ejemplo utilizaremos `scalac`, el compilador de Scala. `scalac` funciona como la mayoría de los compiladores. Toma un archivo fuente como argumento, algunas opciones y produce uno o varios archivos objeto. Los archivos objeto que produce son archivos class de Java estándar. -Si guardamos el programa anterior en un archivo llamado `HolaMundo.scala`, podemos compilarlo ejecutando el siguiente comando (el símbolo mayor `>` representa el prompt del shell y no debe ser escrita): +Si guardamos el programa anterior en un archivo llamado `HolaMundo.scala`, podemos compilarlo ejecutando el siguiente comando (el símbolo mayor `>` representa el prompt del shell y no debe ser escrito): > scalac HolaMundo.scala @@ -58,11 +56,10 @@ Veamos un ejemplo que demuestra esto. Queremos obtener y formatear la fecha actu Las librerías de clases de Java definen clases de utilería poderosas, como `Date` y `DateFormat`. Ya que Scala interacciona fácilmente con Java, no es necesario implementar estas clases equivalentes en las librerías de Scala --podemos simplemente importar las clases de los correspondientes paquetes de Java: import java.util.{Date, Locale} - import java.text.DateFormat import java.text.DateFormat._ object FrenchDate { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val ahora = new Date val df = getDateInstance(LONG, Locale.FRANCE) println(df format ahora) @@ -71,7 +68,7 @@ Las librerías de clases de Java definen clases de utilería poderosas, como `Da Las declaraciones de importación de Scala lucen muy similares a las de Java, sin embargo, las primeras son bastante más poderosas. Múltiples clases pueden ser importadas desde el mismo paquete al encerrarlas en llaves como se muestra en la primer línea. Otra diferencia es que podemos importar todos los nombres de un paquete o clase, utilizando el carácter guión bajo (`_`) en vez del asterisco (`*`). Eso es porque el asterisco es un identificador válido en Scala (quiere decir que por ejemplo podemos nombrar a un método `*`), como veremos más adelante. -La declaración `import` en la tercer línea por lo tanto importa todos los miembros de la clase `DateFormat`. Esto hace que el método estático `getDateInstance` y el campo estático `LONG` sean directamente visibles. +La declaración `import` en la segunda línea importa todos los miembros de la clase `DateFormat`. Esto hace que el método estático `getDateInstance` y el campo estático `LONG` sean directamente visibles. Dentro del método `main` primero creamos una instancia de la clase `Date` la cual por defecto contiene la fecha actual. A continuación definimos un formateador de fechas utilizando el método estático `getDateInstance` que importamos previamente. Finalmente, imprimimos la fecha actual formateada de acuerdo a la instancia de `DateFormat` que fue "localizada". Esta última línea muestra una propiedad interesante de la sintaxis de Scala. Los métodos que toman un solo argumento pueden ser usados con una sintaxis de infijo Es decir, la expresión @@ -97,23 +94,13 @@ Ya que los números son objetos, estos también tienen métodos. De hecho, una e Consiste exclusivamente de llamadas a métodos, porque es equivalente a la siguiente expresión, como vimos en la sección anterior: - (1).+(((2).*(3))./(x)) + 1.+(2.*(3)./(x)) Esto también indica que `+`, `*`, etc. son identificadores válidos en Scala. -Los paréntesis alrededor de los números en la segunda versión son necesarios porque el analizador léxico de Scala usa la regla de "mayor coincidencia". Por lo tanto partiría la siguiente expresión: - - 1.+(2) - -En estas partes: `1.`, `+`, y `2`. La razón que esta regla es elegida es porque `1.` es una coincidencia válida y es mayor que `1`, haciendo a este un `Double` en vez de un `Int`. Al escribir la expresión así: - - (1).+(2) - -previene que el `1` sea tomado como un `Double`. - ### Las funciones son objetos -Tal vez suene más sorprendente para los programadores Java, las funciones en Scala también son objetos. Por lo tanto es posible pasar funciones como argumentos, almacenarlas en variables, y retornarlas desde otras funciones. Esta habilidad de manipular funciones como valores es una de las valores fundamentales de un paradigma de programación muy interesante llamado *programación funcional*. +Tal vez suene más sorprendente para los programadores Java, las funciones en Scala también son objetos. Por lo tanto es posible pasar funciones como argumentos, almacenarlas en variables, y retornarlas desde otras funciones. Esta habilidad de manipular funciones como valores es una de los valores fundamentales de un paradigma de programación muy interesante llamado *programación funcional*. Como un ejemplo muy simple de por qué puede ser útil usar funciones como valores consideremos una función *temporizador* (o timer, en inglés) cuyo propósito es realizar alguna acción cada un segundo. ¿Cómo pasamos al temporizador la acción a realizar? Bastante lógico, como una función. Este simple concepto de pasar funciones debería ser familiar para muchos programadores: es generalmente utilizado en código relacionado con Interfaces gráficas de usuario (GUIs) para registrar "retrollamadas" (call-back en inglés) que son invocadas cuando un evento ocurre. @@ -121,19 +108,20 @@ En el siguiente programa, la función del temporizador se llama `unaVezPorSegund object Temporizador { def unaVezPorSegundo(callback: () => Unit) { - while (true) { callback(); Thread sleep 1000 } + while (true) { + callback(); + Thread sleep 1000 + } } def tiempoVuela() { println("El tiempo vuela como una flecha...") } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { unaVezPorSegundo(tiempoVuela) } } _Nota: si nunca tuviste experiencias previas con programación funcional te recomiendo que te tomes unos segundos para analizar cuando se utilizan paréntesis y cuando no en los lugares donde aparece *callback*. Por ejemplo, dentro de la declaración de `unaVezPorSegundo` no aparece, ya que se trata de la función como un "valor", a diferencia de cómo aparece dentro del método, ya que en ese caso se la está invocando (por eso los paréntesis)._ -Note that in order to print the string, we used the predefined method -`println` instead of using the one from `System.out`. #### Funciones anónimas @@ -141,9 +129,12 @@ El programa anterior es fácil de entender, pero puede ser refinado aún más. P object TemporizadorAnonimo { def unaVezPorSegundo(callback: () => Unit) { - while (true) { callback(); Thread sleep 1000 } + while (true) { + callback(); + Thread sleep 1000 + } } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { unaVezPorSegundo( () => println("El tiempo vuela como una flecha...") ) @@ -176,7 +167,7 @@ El compilador no es siempre capaz de inferir los tipos como lo hace aquí, y des Un pequeño problema de los métodos `re` e `im` es que para poder llamarlos es necesario agregar un par de paréntesis vacíos después de sus nombres, como muestra el siguiente ejemplo: object NumerosComplejos { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val c = new Complejo(1.2, 3.4) println("Parte imaginaria: " + c.im()) } @@ -253,15 +244,15 @@ De ahora en más, el tipo `Entorno` puede ser usado como un alias del tipo de fu Ahora podemos dar la definición de la función evaluadora. Conceptualmente, es muy sencillo: el valor de una suma de dos expresiones es simplemente la suma de los valores de estas expresiones; el valor de una variable es obtenido directamente del entorno; y el valor de una constante es la constante en sí misma. Expresar esto en Scala no resulta para nada difícil: def eval(a: Arbol, ent: Entorno): Int = a match { - case Sum(i, d) => eval(i, ent) + eval(d, env) + case Sum(i, d) => eval(i, ent) + eval(d, ent) case Var(n) => ent(n) case Const(v) => v } Esta función evaluadora función realizando un *reconocimiento de patrones* (pattern matching) en el árbol `a`. Intuitivamente, el significado de la definición de arriba debería estar claro: -1. Primero comprueba si el árbol `t`es una `Sum`, y si lo es, asocia el sub-arbol izquierdo a una nueva variable llamada `i` y el sub-arbol derecho a la variable `r`, y después procede con la evaluación de la expresión que sigue a la flecha (`=>`); esta expresión puede (y hace) uso de las variables asociadas por el patrón que aparece del lado izquierdo de la flecha. -2. si la primer comprobación (la de `Sum`) no prospera, es decir que el árbol no es una `Sum`, sigue de largo y comprueba si `a` es un `Var`; si lo es, asocia el nombre contenido en el nodo `Var` a la variable `n` y procede con la parte derecha de la expresión. +1. Primero comprueba si el árbol `t`es una `Sum`, y si lo es, asocia el sub-arbol izquierdo a una nueva variable llamada `i` y el sub-arbol derecho a la variable `d`, y después procede con la evaluación de la expresión que sigue a la flecha (`=>`); esta expresión puede (y hace) uso de las variables asociadas por el patrón que aparece del lado izquierdo de la flecha. +2. Si la primer comprobación (la de `Sum`) no prospera, es decir que el árbol no es una `Sum`, sigue de largo y comprueba si `a` es un `Var`; si lo es, asocia el nombre contenido en el nodo `Var` a la variable `n` y procede con la parte derecha de la expresión. 3. si la segunda comprobación también falla, resulta que `a` no es un `Sum` ni un `Var`, por lo tanto comprueba que sea un `Const`, y si lo es, asocia el valor contenido en el nodo `Const` a la variable `v`y procede con el lado derecho. 4. finalmente, si todos las comprobaciones fallan, una excepción es lanzada para dar cuenta el fallo de la expresión; esto puede pasar solo si existen más subclases de `Arbol`. @@ -279,7 +270,7 @@ Para explorar un poco más esto de pattern matching definamos otra operación ar 2. la derivada de una variable `v` es uno (1) si `v` es la variable relativa a la cual la derivada toma lugar, y cero (0)de otra manera, 3. la derivada de una constante es cero (0). -Estas reglas pueden ser traducidas casi literalmente en código Sclaa, para obtener la siguiente definición. +Estas reglas pueden ser traducidas casi literalmente en código Scala, para obtener la siguiente definición. def derivada(a: Arbol, v: String): Arbol = a match { case Sum(l, r) => Sum(derivada(l, v), derivada(r, v)) @@ -291,7 +282,7 @@ Esta función introduce dos nuevos conceptos relacionados al pattern matching. P No hemos explorado el completo poder del pattern matching aún, pero nos detendremos aquí para mantener este documento corto. Todavía nos queda pendiente ver cómo funcionan las dos funciones de arriba en un ejemplo real. Para ese propósito, escribamos una función main simple que realice algunas operaciones sobre la expresión `(x+x)+(7+y)`: primero computa su valor en el entorno `{ x -> 5, y -> 7 }` y después computa su derivada con respecto a `x` y después a `y`. - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val exp: Arbol = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) val ent: Entonrno = { case "x" => 5 case "y" => 7 } println("Expresión: " + exp) @@ -321,7 +312,7 @@ Tal vez la forma más fácil para un programador Java de entender qué son los t Para ver la utilidad de los traits, veamos un ejemplo clásico: objetos ordenados. Generalmente es útil tener la posibilidad de comparar objetos de una clase dada entre ellos, por ejemplo, para ordenarlos. En Java, los objetos que son comparables implementan la interfaz `Comparable`. En Scala, podemos hacer algo un poco mejor que en Java al definir un trait equivalente `Comparable` que invocará a `Ord`. -Cuando comparamos objetos podemos utilizar seis predicados distintos: menor, menor o igual, igual, distinto, mayor o igual y mayor. De todas maneras, definir todos estos es fastidioso, especialmente que cuatro de estos pueden ser expresados en base a los otros dos. Esto es, dados los predicados "igual" y "menor" (por ejemplo), uno puede expresar los otros. En Scala, todas estas observaciones pueden ser fácilmente capturadas mediante la siguiente declaración de un Trait: +Cuando comparamos objetos podemos utilizar seis predicados distintos: menor, menor o igual, igual, distinto, mayor o igual y mayor. De todas maneras, definir todos estos es fastidioso, especialmente cuando cuatro de éstos pueden ser expresados en base a los otros dos. Esto es, dados los predicados "igual" y "menor" (por ejemplo), uno puede expresar los otros. En Scala, todas estas observaciones pueden ser fácilmente capturadas mediante la siguiente declaración de un Trait: trait Ord { def < (that: Any): Boolean @@ -358,7 +349,7 @@ Finalmente el último método para definir es el predicado que comprueba la infe def <(that: Any): Boolean = { if (!that.isInstanceOf[Fecha]) - error("no se puede comparar" + that + " y una fecha") + sys.error("no se puede comparar" + that + " y una fecha") val o = that.asInstanceOf[Fecha] (anno < o.anno) || @@ -395,10 +386,10 @@ El ejemplo anterior introduce a las variables en Scala, que no deberían requeri Para utilizar esta clase `Referencia`, uno necesita especificar qué tipo utilizar por el parámetro `T`, es decir, el tipo del elemento contenido por la referencia. Por ejemplo, para crear y utilizar una referencia que contenga un entero, podríamos escribir lo siguiente: object ReferenciaEntero { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val ref = new Referencia[Int] ref.set(13) - println("La referncia tiene la mitad de " + (ref.get * 2)) + println("La referencia tiene la mitad de " + (ref.get * 2)) } } diff --git a/_fr/cheatsheets/index.md b/_fr/cheatsheets/index.md index 9cb47c6f8d..953bfca164 100644 --- a/_fr/cheatsheets/index.md +++ b/_fr/cheatsheets/index.md @@ -1,11 +1,11 @@ --- layout: cheatsheet -title: Scalacheat +title: Scala Cheatsheet partof: cheatsheet by: Brendan O'Connor -about: Grâce à Brendan O'Connor, ce memento vise à être un guide de référence rapide pour les constructions syntaxiques en Scala. Licencié par Brendan O'Connor sous licence CC-BY-SA 3.0. +about: Grâce à Brendan O'Connor, ce memento vise à être un guide de référence rapide pour les constructions syntaxiques en Scala. Licencié par Brendan O'Connor sous licence CC-BY-SA 3.0. language: fr --- @@ -47,7 +47,7 @@ language: fr | `var (x,y,z) = (1,2,3)` | liaison déstructurée : le déballage du tuple se fait par le "pattern matching". | | Bad`var x,y,z = (1,2,3)` | erreur cachée : chaque variable est associée au tuple au complet. | | `var xs = List(1,2,3)` | liste (immuable). | -| `xs(2)` | indexe un élément par le biais des parenthèses. ([transparents](http://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) | +| `xs(2)` | indexe un élément par le biais des parenthèses. ([transparents](https://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) | | `1 :: List(2,3)` | créé une liste par le biais de l'opérateur "cons".| | `1 to 5` _est équivalent à_ `1 until 6`
`1 to 10 by 2` | sucre syntaxique pour les plages de valeurs. | | `()` _(parenthèses vides)_ | l'unique membre de type Unit (à l'instar de void en C/Java). | @@ -56,11 +56,11 @@ language: fr | `if (check) happy` _est équivalent à_
`if (check) happy else ()` | sucre syntaxique pour un test conditionnel. | | `while (x < 5) { println(x); x += 1}` | boucle while. | | `do { println(x); x += 1} while (x < 5)` | boucle do while. | -| `import scala.util.control.Breaks._`
`breakable {`
` for (x <- xs) {`
` if (Math.random < 0.1) break`
` }`
`}`| break. ([transparents](http://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) | +| `import scala.util.control.Breaks._`
`breakable {`
` for (x <- xs) {`
` if (Math.random < 0.1) break`
` }`
`}`| break. ([transparents](https://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) | | `for (x <- xs if x%2 == 0) yield x*10` _est équivalent à_
`xs.filter(_%2 == 0).map(_*10)` | *for comprehension*: filter/map | | `for ((x,y) <- xs zip ys) yield x*y` _est équivalent à_
`(xs zip ys) map { case (x,y) => x*y }` | *for comprehension* : liaison déstructurée | | `for (x <- xs; y <- ys) yield x*y` _est équivalent à_
`xs flatMap {x => ys map {y => x*y}}` | *for comprehension* : produit cartésien. | -| `for (x <- xs; y <- ys) {`
`println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
`}` | *for comprehension* : à la manière impérative
[sprintf-style](http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | +| `for (x <- xs; y <- ys) {`
`println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
`}` | *for comprehension* : à la manière impérative
[sprintf-style](https://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | | `for (i <- 1 to 5) {`
`println(i)`
`}` | *for comprehension* : itère jusqu'à la borne supérieure comprise. | | `for (i <- 1 until 5) {`
`println(i)`
`}` | *for comprehension* : itère jusqu'à la borne supérieure non comprise. | | pattern matching | | diff --git a/_fr/getting-started/install-scala.md b/_fr/getting-started/install-scala.md new file mode 100644 index 0000000000..76f7c537f9 --- /dev/null +++ b/_fr/getting-started/install-scala.md @@ -0,0 +1,198 @@ +--- +layout: singlepage-overview +title: Démarrage +partof: getting-started +language: fr +includeTOC: true +--- + +Les instructions ci-dessous couvrent à la fois Scala 2 et Scala 3. + +## Essayer Scala sans installation + +Pour commencer à expérimenter Scala sans plus attendre, utilisez “Scastie” dans votre navigateur _Scastie_ est un environnement "bac à sable" en ligne, où vous pouvez tester Scala, afin de comprendre comment fonctionne le langage et avec un accès à tous les compilateurs Scala et les librairies publiées. + +> Scastie supporte à la fois Scala 2 et Scala 3, en proposant Scala 3 par défaut. +> Si vous cherchez à tester un morceau de code avec Scala 2 +> [cliquez ici](https://scastie.scala-lang.org/MHc7C9iiTbGfeSAvg8CKAA). + +## Installer Scala sur votre ordinateur + +Installer Scala veut dire installer différents outils en ligne de commande, comme le compilateur Scala et les outils de build. +Nous recommandons l'utilisation de l'outil d'installation "Coursier" qui va automatiquement installer toutes les dépendances, mais vous pouvez aussi installer chaque outil à la main. + +### Utilisation de l'installateur Scala (recommandé) + +L'installateur Scala est un outil nommé [Coursier](https://get-coursier.io/docs/cli-overview), la commande principale de l'outil est `cs`. +Il s'assure que la JVM est les outils standards de Scala sont installés sur votre système. +Installez-le sur votre système avec les instructions suivantes. + + +{% tabs install-cs-setup-tabs class=platform-os-options %} + + +{% tab macOS for=install-cs-setup-tabs %} +{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-brew %} +{% altDetails cs-setup-macos-nobrew "Alternativement, si vous n'utilisez pas Homebrew:" %} + {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-x86-64 %} +{% endaltDetails %} +{% endtab %} + + + +{% tab Linux for=install-cs-setup-tabs %} + {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.linux-x86-64 %} +{% endtab %} + + + +{% tab Windows for=install-cs-setup-tabs %} + Téléchargez et exécutez [l'intallateur Scala pour Windows]({{site.data.setup-scala.windows-link}}) basé sur Coursier. +{% endtab %} + + + +{% tab Other for=install-cs-setup-tabs defaultTab %} + + Suivez + [les instructions pour installer la commande `cs`](https://get-coursier.io/docs/cli-installation) + puis exécutez `./cs setup`. +{% endtab %} + + +{% endtabs %} + + +En plus de gérer les JVMs, `cs setup` installe aussi des utilitaires en ligne de commande : + +- Un JDK (si vous n'en avez pas déjà un) +- L'outil de construction de package [sbt](https://www.scala-sbt.org/) +- [Ammonite](https://ammonite.io/), un REPL amélioré +- [scalafmt](https://scalameta.org/scalafmt/), le formatteur de code Scala +- `scalac` (le compilateur Scala 2) +- `scala` (le REPL et le lanceur de script Scala 2). + +Pour plus d'informations à propos de `cs`, vous pouvez lire la page suivante : +[coursier-cli documentation](https://get-coursier.io/docs/cli-overview). + +> Actuellement, `cs setup` installe le compilateur Scala 2 et le lanceur +> (les commandes `scalac` et `scala` respectivement). Ce n'est pas un problème, +> car la plupart des projets utilisent un outil de contruction +> de package qui fonctionne à la fois pour Scala 2 et Scala 3. +> Cependant, vous pouvez installer le compilateur et le lanceur Scala 3 en ligne de commande, +> en exécutant les commandes suivantes : +> ``` +> $ cs install scala3-compiler +> $ cs install scala3 +> ``` + +### ...ou manuellement + +Vous avez seulement besoin de deux outils pour compiler, lancer, tester et packager un projet Scala: Java 8 ou 11, et sbt. +Pour les installer manuellement : + +1. Si vous n'avez pas Java 8 ou 11 installé, téléchargez + Java depuis [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html), + ou [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Référez-vous à la page [JDK Compatibility](/overviews/jdk-compatibility/overview.html) pour les détails de compatibilité entre Java et Scala. +1. Installez [sbt](https://www.scala-sbt.org/download.html) + +## Créer un projet "Hello World" avec sbt + +Une fois que vous avez installé sbt, vous pouvez créer un projet Scala, comme expliqué dans la section suivante. + +Pour créer un projet, vous pouvez soit utiliser la ligne de commande, soit un IDE. +Si vous êtes habitué à la ligne de commande, nous recommandons cette approche. + +### Utiliser la ligne de commande + +sbt est un outil de construction de package pour Scala, sbt compile, lance et teste votre code Scala. +(Il peut aussi publier les librairies et faire beaucoup d'autres tâches.) + +Pour créer un nouveau projet Scala avec sbt : + +1. `cd` dans un répertoire vide. +1. Lancez la commande `sbt new scala/scala3.g8` pour créer un projet Scala 3, ou `sbt new scala/hello-world.g8` pour créer un projet Scala 2. + Cela va télécharger un projet modèle depuis Github. + Cela va aussi créer un dossier `target`, que vous pouvez ignorer. +1. Quand cela vous est demandé, nommez votre application `hello-world`. Cela va créer un projet appelé "hello-world". +1. Voyons ce que nous vennons de générer : + +``` +- hello-world + - project (sbt utilise ce dossier pour ses propres fichiers) + - build.properties + - build.sbt (fichier de définition de la construction du package pour sbt) + - src + - main + - scala (tout votre code Scala doit être placé ici) + - Main.scala (Point d'entrée du programme) <-- c'est tout ce dont nous avons besoin pour le moment +``` + +Vous pouvez trouver plus de documentation à propos de sbt dans le [Scala Book](/scala3/book/tools-sbt.html) ([Lien](/overviews/scala-book/scala-build-tool-sbt.html) vers la version Scala 2) et sur la [documentation](https://www.scala-sbt.org/1.x/docs/index.html) officielle de sbt. + +### Avec un IDE + +Vous pouvez ignorer le reste de cette page et aller directement sur [Building a Scala Project with IntelliJ and sbt](/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html). + + +## Ouvrir le projet hello-world + +Utilisons un IDE pour ouvrir le projet. Les plus populaires sont IntelliJ et VSCode. +Il proposent tout deux des fonctionnalités avancées. D'[autres éditeurs](https://scalameta.org/metals/docs/editors/overview.html) sont également disponibles. + +### Avec IntelliJ + +1. Téléchargez et installez [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/) +1. Installez l'extension Scala en suivant [les instruction IntelliJ pour installer des extensions](https://www.jetbrains.com/help/idea/managing-plugins.html) +1. Ouvrez le fichier `build.sbt` puis choisissez *Open as a project* + +### Avec VSCode et metals + +1. Téléchargez [VSCode](https://code.visualstudio.com/Download) +1. Installez l'extension Metals depuis [la marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals) +1. Ensuite, ouvrez le répertoire contenant le fichier `build.sbt` (cela doit être le dossier `hello-world` si vous avez suivi les instructions précédentes). Choisissez *Import build* lorsque cela vous est demandé. + +> [Metals](https://scalameta.org/metals) est un "Serveur de langage Scala" qui fournit une aide pour écrire du code Scala dans VSCode et d'autres éditeurs [Atom, Sublime Text, autres ...](https://scalameta.org/metals/docs/editors/overview.html), en utilisant le [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/). +> En arrière plan, Metals communique avec l'outil de construction de package en utilisant +> le [Build Server Protocol (BSP)](https://build-server-protocol.github.io/). +> Pour plus de détails sur le fonctionnement de Metals, suivez [“Write Scala in VS Code, Vim, Emacs, Atom and Sublime Text with Metals”](https://www.scala-lang.org/2019/04/16/metals.html). + +### Essayer avec le code source + +Ouvrez ces deux fichiers dans votre IDE : + +- _build.sbt_ +- _src/main/scala/Main.scala_ + +Quand vous lancerez votre projet à l'étape suivante, la configuration dans _build.sbt_ sera utilisée pour lancer le code dans _src/main/scala/Main.scala_. + +## Lancer Hello Word + +Si vous êtes habitué à votre IDE, vous pouvez lancer le code dans _Main.scala_ depuis celui-ci. + +Sinon, vous pouvez lancer l'application depuis le terminal avec ces étapes : + +1. `cd` vers `hello-world`. +1. Lancez `sbt`. Cela va ouvrir la console sbt. +1. Ecrivez `~run`. Le symbole `~` est optionnel, il va relancer l'application à chaque sauvegarde de fichier. + Cela permet un cyle rapide de modification/relance/debug. sbt va aussi générer un dossier `target` que vous pouvez ignorer. + +Quand vous avez fini d'expérimenter avec ce projet, appuyez sur `[Entrée]` pour interrompre la commande `run`. +Puis saisissez `exit` ou appuyez sur `[Ctrl+D]` pour quitter sbt et revenir à votre invite de commande. + +## Prochaines étapes + +Une fois que vous avez terminé le tutoriel ce dessus, vous pouvez consulter : + +* [The Scala Book](/scala3/book/introduction.html) ([Lien](/overviews/scala-book/introduction.html) vers la version Scala 2), qui fournit un ensemble de courtes leçons et introduit les fonctionnalités principales de Scala. +* [The Tour of Scala](/tour/tour-of-scala.html) pour une introduction des fonctionnalités Scala. +* [Learning Courses](/online-courses.html), qui contient des tutoriels et des cours interactifs. +* [Our list of some popular Scala books](/books.html). +* [The migration guide](/scala3/guides/migration/compatibility-intro.html) pour vous aider à migrer votre code Scala 2 vers Scala 3. + +## Obtenir de l'aide +Il y a plusieurs listes de diffusion et canaux de discussions instantanés si vous souhaitez rencontrer rapidement d'autres utilisateurs de Scala. Allez faire un tour sur notre page [community](https://scala-lang.org/community/) pour consulter la liste des ces ressources et obtenir de l'aide. + +Traduction par Antoine Pointeau. diff --git a/_fr/tour/abstract-type-members.md b/_fr/tour/abstract-type-members.md new file mode 100644 index 0000000000..68f1cdfd1e --- /dev/null +++ b/_fr/tour/abstract-type-members.md @@ -0,0 +1,76 @@ +--- +layout: tour +title: Abstract Type Members +partof: scala-tour +num: 25 +language: fr +next-page: compound-types +previous-page: inner-classes +topics: abstract type members +prerequisite-knowledge: variance, upper-type-bound +--- + +Les types abstraits, tels que les traits et les classes abstraites, peuvent avoir des membres type abstrait. +Cela signifie que les implémentations concrètes définissent les types réels. +Voici un exemple : + +```scala mdoc +trait Buffer { + type T + val element: T +} +``` + +Ici, nous avons défini un `type T` abstrait. Il est utilisé pour décrire le type de `element`. Nous pouvons étendre ce trait dans une classe abstraite, en ajoutant une borne de type supérieure à `T` pour le rendre plus spécifique. + +```scala mdoc +abstract class SeqBuffer extends Buffer { + type U + type T <: Seq[U] + def length = element.length +} +``` + +Remarquez comment nous pouvons utiliser un autre type abstrait `U` dans la spécification d'une borne supérieure pour `T`. Cette `class SeqBuffer` nous permet de stocker uniquement des séquences dans le tampon en indiquant que le type `T` doit être un sous-type de `Seq[U]` pour un nouveau type abstrait `U`. + +Les traits ou [classes](classes.html) avec des membres type abstrait sont souvent utilisés en combinaison avec des instanciations de classes anonymes. Pour illustrer cela, regardons maintenant un programme qui traite un "sequence buffer" qui fait référence à une liste d'entiers : + +```scala mdoc +abstract class IntSeqBuffer extends SeqBuffer { + type U = Int +} + + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` + +Ici, la factory `newIntSeqBuf` utilise une implémentation de classe anonyme de `IntSeqBuffer` (c'est-à-dire `new IntSeqBuffer`) pour définir le type abstrait `T` comme étant le type concret `List[Int]`. + +Il est également possible de transformer des membres type abstrait en paramètres de type de classes et *vice versa*. Voici une version du code ci-dessous qui n'utilise que des paramètres de type : + +```scala mdoc:nest +abstract class Buffer[+T] { + val element: T +} +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { + def length = element.length +} + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` + +Notez que nous devons utiliser ici [les annotaions de variance](variances.html) (`+T <: Seq[U]`) afin de masquer le type concret d'implémentation de séquence dans l'objet renvoyé par la méthode `newIntSeqBuf`. De plus, il existe des cas où il n'est pas possible de remplacer les membres de type abstrait par des paramètres de type. diff --git a/_fr/tour/annotations.md b/_fr/tour/annotations.md new file mode 100644 index 0000000000..5f2b4cbf55 --- /dev/null +++ b/_fr/tour/annotations.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Annotations +partof: scala-tour + +num: 30 + +language: fr + +next-page: packages-and-imports +previous-page: by-name-parameters +--- diff --git a/_fr/tour/basics.md b/_fr/tour/basics.md new file mode 100644 index 0000000000..a16e3c7970 --- /dev/null +++ b/_fr/tour/basics.md @@ -0,0 +1,11 @@ +--- +layout: tour +title: Basics +partof: scala-tour + +num: 2 +language: fr + +next-page: unified-types +previous-page: tour-of-scala +--- diff --git a/_fr/tour/by-name-parameters.md b/_fr/tour/by-name-parameters.md new file mode 100644 index 0000000000..917e78aede --- /dev/null +++ b/_fr/tour/by-name-parameters.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: By-name Parameters +partof: scala-tour + +num: 29 + +language: fr + +next-page: annotations +previous-page: operators +--- diff --git a/_fr/tour/case-classes.md b/_fr/tour/case-classes.md new file mode 100644 index 0000000000..66debb53f4 --- /dev/null +++ b/_fr/tour/case-classes.md @@ -0,0 +1,73 @@ +--- +layout: tour +title: Case Classes +partof: scala-tour + +num: 13 + +language: fr + +next-page: pattern-matching +previous-page: multiple-parameter-lists +--- + +Les classes de cas sont comme les autres classes avec quelques différences que nous allons présenter. Les classes de cas sont pratiques pour modéliser des données immuables. Dans la prochaine étape du tour, nous verrons comment elles peuvent être utilisées avec le [pattern matching](pattern-matching.html). + +## Définir une classe de cas + +Une classe de cas requiert au minimum le mot clef `case class`, un identifiant, et une liste de paramètres (qui peut être vide) : + +```scala mdoc +case class Book(isbn: String) + +val frankenstein = Book("978-0486282114") +``` + +Notez que le mot clef `new` n'a pas été utilisé pour instancier la classe de cas `Book`. C'est parce que la classe de cas a une méthode `apply` par défaut qui prend en charge la construction de l'objet. + +Quand vous créez une classe de cas avec des paramètres, les paramètres sont des `val` publiques. + +``` +case class Message(sender: String, recipient: String, body: String) +val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") + +println(message1.sender) // prints guillaume@quebec.ca +message1.sender = "travis@washington.us" // cette ligne ne compile pas +``` + +Vous ne pouvez pas réaffecter `message1.sender` parce que c'est une `val` (càd. une valeur immuable). Il est possible d'utiliser des `var` dans les classes de cas mais ce n'est pas recommandé. + +## Comparaison + +Les instances des classes de cas sont comparées structurellement et non par référence : + +```scala mdoc +case class Message(sender: String, recipient: String, body: String) + +val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val messagesAreTheSame = message2 == message3 // true +``` + +Même si `message2` et `message3` font référence à des objets différents, les valeurs de chaque objet sont égales. + +## Copier + +Vous pouvez créer une copie (superficielle) d'une instance de classe de cas simplement en utlisant la méthode `copy`. Vous pouvez optionnellement changer les arguments du constructeur. + +```scala mdoc:nest +case class Message(sender: String, recipient: String, body: String) +val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") +val message5 = message4.copy(sender = message4.recipient, recipient = "claire@bourgogne.fr") +message5.sender // travis@washington.us +message5.recipient // claire@bourgogne.fr +message5.body // "Me zo o komz gant ma amezeg" +``` + +Le destinataire (recipient) de `message4` est utilisé comment expéditeur (sender) du message `message5` mais le `body` du `message4` a été directement copié. + +## Plus d'informations + +* Apprennez-en plus sur les classes de cas dans [Scala Book](/overviews/scala-book/case-classes.html) + +Traduit par Antoine Pointeau. diff --git a/_fr/tour/classes.md b/_fr/tour/classes.md new file mode 100644 index 0000000000..40f56d0513 --- /dev/null +++ b/_fr/tour/classes.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Classes +partof: scala-tour + +num: 4 + +language: fr + +next-page: traits +previous-page: unified-types +--- diff --git a/_fr/tour/compound-types.md b/_fr/tour/compound-types.md new file mode 100644 index 0000000000..db813518b1 --- /dev/null +++ b/_fr/tour/compound-types.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Compound Types +partof: scala-tour + +num: 22 + +language: fr + +next-page: self-types +previous-page: abstract-type-members +--- diff --git a/_fr/tour/default-parameter-values.md b/_fr/tour/default-parameter-values.md new file mode 100644 index 0000000000..0f73ab1653 --- /dev/null +++ b/_fr/tour/default-parameter-values.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Default Parameter Values +partof: scala-tour + +num: 31 + +language: fr + +next-page: named-arguments +previous-page: annotations +--- diff --git a/_fr/tour/extractor-objects.md b/_fr/tour/extractor-objects.md new file mode 100644 index 0000000000..1f864b7f39 --- /dev/null +++ b/_fr/tour/extractor-objects.md @@ -0,0 +1,66 @@ +--- +layout: tour +title: Extractor Objects +partof: scala-tour + +num: 18 + +language: fr + +next-page: for-comprehensions +previous-page: regular-expression-patterns +--- + +Un objet extracteur est un objet avec une méthode `unapply`. Tandis que la méthode `apply` ressemble à un constructeur qui prend des arguments et crée un objet, `unapply` prend un object et essaye de retourner ses arguments. Il est utilisé le plus souvent en filtrage par motif (*pattern matching*) ou avec les fonctions partielles. + +```scala mdoc +import scala.util.Random + +object CustomerID { + + def apply(name: String) = s"$name--${Random.nextLong()}" + + def unapply(customerID: String): Option[String] = { + val stringArray: Array[String] = customerID.split("--") + if (stringArray.tail.nonEmpty) Some(stringArray.head) else None + } +} + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match { + case CustomerID(name) => println(name) // prints Sukyoung + case _ => println("Could not extract a CustomerID") +} +``` + +La méthode `apply` crée une chaîne de caractères `CustomerID` depuis `name`. La méthode `unapply` fait l'inverse pour retrouver le `name`. Lorsqu'on appelle `CustomerID("Sukyoung")`, c'est un raccourci pour `CustomerID.apply("Sukyoung")`. Lorsqu'on appelle `case CustomerID(name) => println(name)`, on appelle la méthode `unapply` avec `CustomerID.unapply(customer1ID)`. + +Sachant qu'une définition de valeur peut utiliser une décomposition pour introduire une nouvelle variable, un extracteur peut être utilisé pour initialiser la variable, avec la méthode `unapply` pour fournir la valeur. + +```scala mdoc +val customer2ID = CustomerID("Nico") +val CustomerID(name) = customer2ID +println(name) // prints Nico +``` + +C'est équivalent à `val name = CustomerID.unapply(customer2ID).get`. + +```scala mdoc +val CustomerID(name2) = "--asdfasdfasdf" +``` + +S'il n'y a pas de correspondance, une `scala.MatchError` est levée : + +```scala +val CustomerID(name3) = "-asdfasdfasdf" +``` + +Le type de retour de `unapply` doit être choisi comme suit : + +* Si c'est juste un test, retourner un `Boolean`. Par exemple, `case even()`. +* Si cela retourne une seule sous-valeur de type T, retourner un `Option[T]`. +* Si vous souhaitez retourner plusieurs sous-valeurs `T1,...,Tn`, groupez-les dans un tuple optionnel `Option[(T1,...,Tn)]`. + +Parfois, le nombre de valeurs à extraire n'est pas fixe et on souhaiterait retourner un nombre arbitraire de valeurs, en fonction des données d'entrée. Pour ce cas, vous pouvez définir des extracteurs avec la méthode `unapplySeq` qui retourne un `Option[Seq[T]]`. Un exemple commun d'utilisation est la déconstruction d'une liste en utilisant `case List(x, y, z) =>`. Un autre est la décomposition d'une `String` en utilisant une expression régulière `Regex`, comme `case r(name, remainingFields @ _*) =>`. + +Traduit par Antoine Pointeau. diff --git a/_fr/tour/for-comprehensions.md b/_fr/tour/for-comprehensions.md new file mode 100644 index 0000000000..ea4649ad39 --- /dev/null +++ b/_fr/tour/for-comprehensions.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: For Comprehensions +partof: scala-tour + +num: 15 + +language: fr + +next-page: generic-classes +previous-page: extractor-objects +--- diff --git a/_fr/tour/generic-classes.md b/_fr/tour/generic-classes.md new file mode 100644 index 0000000000..6eeb2e8fea --- /dev/null +++ b/_fr/tour/generic-classes.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Generic Classes +partof: scala-tour + +num: 16 + +language: fr + +next-page: variances +previous-page: extractor-objects +--- diff --git a/_fr/tour/higher-order-functions.md b/_fr/tour/higher-order-functions.md new file mode 100644 index 0000000000..513f6b619f --- /dev/null +++ b/_fr/tour/higher-order-functions.md @@ -0,0 +1,123 @@ +--- +layout: tour +title: Higher-order Functions +partof: scala-tour + +num: 10 + +language: fr + +next-page: nested-functions +previous-page: mixin-class-composition +--- + +Les fonctions d'ordre supérieur prennent d'autres fonctions en paramètres ou retournent une fonction en résultat. +C'est possible car les fonctions sont des valeurs de première classe en Scala. +La terminologie peut devenir une peu confuse à ce point, et nous utilisons l'expression "fonction d'ordre supérieur" à la fois pour les méthodes et les fonctions qui prennent d'autres fonctions en paramètres ou retournent une fonction en résultat. + +Dans le monde du pur orienté objet, une bonne pratique est d'éviter d'exposer des méthodes paramétrées avec des fonctions qui pourraient exposer l'état interne de l'objet. Le fait d’exposer l'état interne de l'objet pourrait casser les invariants de l'objet lui-même ce qui violerait l'encapsulation. + +Un des exemples les plus communs est la fonction d'ordre supérieur `map` qui est diponible pour les collections en Scala. + +```scala mdoc +val salaries = Seq(20000, 70000, 40000) +val doubleSalary = (x: Int) => x * 2 +val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) +``` + +`doubleSalary` est une fonction qui prend un seul entier, `x` et retourne `x * 2`. La partie à gauche de la flèche `=>` est la liste de paramètres, et la valeur de l'expression à droite est ce qui est retourné. Sur la ligne 3, la fonction `doubleSalary` est appliquée à chaque élément dans la liste des salariés. + +Pour réduire le code, nous pouvons faire une fonction anonyme et la passer directement en argument de `map` : + +```scala:nest +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) +``` + +Notez que `x` n'est pas déclaré comme un `Int` dans l'exemple ci-dessus. C'est parce que le compilateur peut inférrer le type en se basant sur le type que méthode `map` attend. (voir [Currying](/tour/multiple-parameter-lists.html)). Une autre façon d'écrire le même morceau de code encore plus idiomatique serait : + +```scala mdoc:nest +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(_ * 2) +``` + +Sachant que le compilateur Scala sait déjà quel est le type des paramètres (un seul `Int`), vous pouvez fournir uniquement la partie de droite de la fonction. +La seule contrepartie c'est que vous devez utiliser `_` à la place du nom du paramètre (c'était `x` dans l'exemple précédent). + +## Convertir les méthodes en fonctions + +Il est aussi possible de passer des méthodes comme arguments aux fonctions d'ordre supérieur, parce que le compilateur Scala va convertir la méthode en fonction. + +```scala mdoc +case class WeeklyWeatherForecast(temperatures: Seq[Double]) { + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF +} +``` + +Ici la méthode `convertCtoF` est passée à la fonction d'ordre supérieur `map`. C'est possible car le compilateur convertit `convertCtoF` vers la fonction `x => convertCtoF(x)` (note : `x` sera un nom généré qui sera garanti d'être unique dans le scope). + +## Les fonction qui acceptent des fonctions + +Une raison d'utiliser les fonctions d'ordre supérieur est de réduire le code redondant. Suposons que vous souhaitez des méthodes qui augmentent le salaire de quelqu'un en fonction de différents facteurs. Sans créer de fonction d'ordre supérieur, cela ressemblerait à ça : + +```scala mdoc +object SalaryRaiser { + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +} +``` + +Notez comment chacunes de ces trois méthodes ne changent que par le facteur de multiplication. +Pour simplifier, vous pouvez extraire le code répété dans une fonction d'ordre supérieur comme ceci : + +```scala mdoc:nest +object SalaryRaiser { + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +} +``` + +La nouvelle méthode, `promotion`, prend les salaires plus une fonction du type `Double => Double` (càd. une fonction qui prend un Double et retourne un Double) et retourne le produit. + +Les méthodes et les fonctions expriment généralement des comportements ou des transformations de données, donc avoir des fonctions qui composent en se basant sur d'autres fonctions peut aider à construire des mécanismes génériques. Ces opérations génériques reportent le verrouillage de l'intégralité du comportement de l'opération, donnant aux clients un moyen de contrôler ou de personnaliser davantage certaines parties de l'opération elle-même. + +## Les fonctions qui retournent des fonctions + +Il y a certains cas ou vous voulez générer une fonction. Voici un exemple de méthode qui retourne une fonction. + +```scala mdoc +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { + val schema = if (ssl) "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" +} + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` + +Notez le type de retour de urlBuilder `(String, String) => String`. Cela veut dire que la fonction anonyme retournée prend deux Strings et retourne une String. Dans ce cas, la fonction anonyme retournée est `(endpoint: String, query: String) => s"https://www.example.com/$endpoint?$query"` + +Traduit par Antoine Pointeau. \ No newline at end of file diff --git a/_fr/tour/implicit-conversions.md b/_fr/tour/implicit-conversions.md new file mode 100644 index 0000000000..1030827e4b --- /dev/null +++ b/_fr/tour/implicit-conversions.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Implicit Conversions +partof: scala-tour + +num: 25 + +language: fr + +next-page: polymorphic-methods +previous-page: implicit-parameters +--- diff --git a/_fr/tour/implicit-parameters.md b/_fr/tour/implicit-parameters.md new file mode 100644 index 0000000000..236dd136f5 --- /dev/null +++ b/_fr/tour/implicit-parameters.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Implicit Parameters +partof: scala-tour + +num: 24 + +language: fr + +next-page: implicit-conversions +previous-page: self-types +--- diff --git a/_fr/tour/inner-classes.md b/_fr/tour/inner-classes.md new file mode 100644 index 0000000000..a5df305ce5 --- /dev/null +++ b/_fr/tour/inner-classes.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Inner Classes +partof: scala-tour + +num: 20 + +language: fr + +next-page: abstract-type-members +previous-page: lower-type-bounds +--- diff --git a/_fr/tour/lower-type-bounds.md b/_fr/tour/lower-type-bounds.md new file mode 100644 index 0000000000..eb6ffb785c --- /dev/null +++ b/_fr/tour/lower-type-bounds.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Lower Type Bounds +partof: scala-tour + +num: 19 + +language: fr + +next-page: inner-classes +previous-page: upper-type-bounds +--- diff --git a/_fr/tour/mixin-class-composition.md b/_fr/tour/mixin-class-composition.md new file mode 100644 index 0000000000..8d1b823c11 --- /dev/null +++ b/_fr/tour/mixin-class-composition.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Class Composition with Mixins +partof: scala-tour + +num: 6 + +language: fr + +next-page: higher-order-functions +previous-page: tuples +--- diff --git a/_fr/tour/multiple-parameter-lists.md b/_fr/tour/multiple-parameter-lists.md new file mode 100644 index 0000000000..476e918cc1 --- /dev/null +++ b/_fr/tour/multiple-parameter-lists.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Multiple Parameter Lists (Currying) +partof: scala-tour + +num: 9 + +language: fr + +next-page: case-classes +previous-page: nested-functions +--- diff --git a/_fr/tour/named-arguments.md b/_fr/tour/named-arguments.md new file mode 100644 index 0000000000..fec11428a3 --- /dev/null +++ b/_fr/tour/named-arguments.md @@ -0,0 +1,34 @@ +--- +layout: tour +title: Named Arguments +partof: scala-tour + +num: 6 + +language: fr + +next-page: traits +previous-page: default-parameter-values +--- + +En appelant des méthodes, vous pouvez nommer leurs arguments comme ceci : + +```scala mdoc +def printName(first: String, last: String): Unit = { + println(first + " " + last) +} + +printName("John", "Smith") // Prints "John Smith" +printName(first = "John", last = "Smith") // Prints "John Smith" +printName(last = "Smith", first = "John") // Prints "John Smith" +``` + +Notez comment l'ordre des arguments nommés peut être réarrangé. Cependant, si certains arguments sont nommés et d'autres non, les arguments non nommés doivent venir en premier et suivrent l'ordre de leurs paramètres dans la signature de la méthode. + +```scala mdoc:fail +printName(last = "Smith", "john") // erreur: argument positionnel après un argument nommé +``` + +Les arguments nommés fonctionnent avec les appels de méthodes Java, mais seulement si la librairie Java en question a été compilée avec `-parameters`. + +Traduction par Antoine Pointeau. \ No newline at end of file diff --git a/_fr/tour/nested-functions.md b/_fr/tour/nested-functions.md new file mode 100644 index 0000000000..f92045364f --- /dev/null +++ b/_fr/tour/nested-functions.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Nested Methods +partof: scala-tour + +num: 8 + +language: fr + +next-page: multiple-parameter-lists +previous-page: higher-order-functions +--- diff --git a/_fr/tour/operators.md b/_fr/tour/operators.md new file mode 100644 index 0000000000..59c697727e --- /dev/null +++ b/_fr/tour/operators.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Operators +partof: scala-tour + +num: 28 + +language: fr + +next-page: by-name-parameters +previous-page: type-inference +--- diff --git a/_fr/tour/package-objects.md b/_fr/tour/package-objects.md new file mode 100644 index 0000000000..80cfb5e055 --- /dev/null +++ b/_fr/tour/package-objects.md @@ -0,0 +1,9 @@ +--- +layout: tour +title: Package Objects +language: fr +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- diff --git a/_fr/tour/packages-and-imports.md b/_fr/tour/packages-and-imports.md new file mode 100644 index 0000000000..8edac3b01c --- /dev/null +++ b/_fr/tour/packages-and-imports.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Packages and Imports +partof: scala-tour + +num: 33 + +language: fr + +previous-page: named-arguments +next-page: package-objects +--- diff --git a/_fr/tour/pattern-matching.md b/_fr/tour/pattern-matching.md new file mode 100644 index 0000000000..1cd3731b9a --- /dev/null +++ b/_fr/tour/pattern-matching.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Pattern Matching +partof: scala-tour + +num: 11 + +language: fr + +next-page: singleton-objects +previous-page: case-classes +--- diff --git a/_fr/tour/polymorphic-methods.md b/_fr/tour/polymorphic-methods.md new file mode 100644 index 0000000000..6375d54957 --- /dev/null +++ b/_fr/tour/polymorphic-methods.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Polymorphic Methods +partof: scala-tour + +num: 26 + +language: fr + +next-page: type-inference +previous-page: implicit-conversions +--- diff --git a/_fr/tour/regular-expression-patterns.md b/_fr/tour/regular-expression-patterns.md new file mode 100644 index 0000000000..253da8efa6 --- /dev/null +++ b/_fr/tour/regular-expression-patterns.md @@ -0,0 +1,63 @@ +--- +layout: tour +title: Regular Expression Patterns +partof: scala-tour + +num: 17 + +language: fr + +next-page: extractor-objects +previous-page: singleton-objects +--- + +Les expressions régulières sont des chaînes de caractères qui peuvent être utilisées pour trouver des motifs (ou l'absence de motif) dans un texte. Toutes les chaînes de caractères peuvent être converties en expressions régulières en utilisant la méthode `.r`. + +```scala mdoc +import scala.util.matching.Regex + +val numberPattern: Regex = "[0-9]".r + +numberPattern.findFirstMatchIn("awesomepassword") match { + case Some(_) => println("Password OK") + case None => println("Password must contain a number") +} +``` + +Dans l'exemple ci-dessus, `numberPattern` est une `Regex` (EXpression REGulière) que nous utilisons pour vérifier que le mot de passe contient un nombre. + +Vous pouvez aussi faire des recherches de groupes d'expressions régulières en utilisant les parenthèses. + +```scala mdoc +import scala.util.matching.Regex + +val keyValPattern: Regex = "([0-9a-zA-Z- ]+): ([0-9a-zA-Z-#()/. ]+)".r + +val input: String = + """background-color: #A03300; + |background-image: url(img/header100.png); + |background-position: top center; + |background-repeat: repeat-x; + |background-size: 2160px 108px; + |margin: 0; + |height: 108px; + |width: 100%;""".stripMargin + +for (patternMatch <- keyValPattern.findAllMatchIn(input)) + println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}") +``` + +Ici nous analysons les clefs et les valeurs d'une chaîne de caractère. Chaque correspondance a un groupe de sous-correspondances. Voici le résultat : + +``` +key: background-color value: #A03300 +key: background-image value: url(img/header100.png) +key: background-position value: top center +key: background-repeat value: repeat-x +key: background-size value: 2160px 108px +key: margin value: 0 +key: height value: 108px +key: width value: 100 +``` + +Traduit par Antoine Pointeau. \ No newline at end of file diff --git a/_fr/tour/self-types.md b/_fr/tour/self-types.md new file mode 100644 index 0000000000..9d82783417 --- /dev/null +++ b/_fr/tour/self-types.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Self-types +partof: scala-tour + +num: 23 + +language: fr + +next-page: implicit-parameters +previous-page: compound-types +--- diff --git a/_fr/tour/singleton-objects.md b/_fr/tour/singleton-objects.md new file mode 100644 index 0000000000..073dfaf5ec --- /dev/null +++ b/_fr/tour/singleton-objects.md @@ -0,0 +1,120 @@ +--- +layout: tour +title: Singleton Objects +partof: scala-tour + +num: 15 + +language: fr + +next-page: regular-expression-patterns +previous-page: pattern-matching +--- + +Un objet est une classe qui a exactement une instance. Il est créé de façon paresseuse au moment où il est référencé, comme une valeur paresseuse `lazy val`. + +En tant que valeur de premier niveau, un objet est un singleton. + +En tant que membre d'une classe englobante ou en tant que valeur locale, il se comporte exactement comme une `lazy val`. + +# Définir un objet singleton + +Un objet est une valeur. La définition d'un objet ressemble a une classe, mais utilise le mot clef `object` : + +```scala mdoc +object Box +``` + +Voici un exemple d'un objet avec une méthode : + +``` +package logging + +object Logger { + def info(message: String): Unit = println(s"INFO: $message") +} +``` + +La méthode `info` peut être importée depuis n'importe où dans le programme. Créer des méthodes utilitaires, comme celle-ci, est un cas d'usage commun pour les objets singleton. + +Regardons comment utiliser `info` dans un autre package : + +``` +import logging.Logger.info + +class Project(name: String, daysToComplete: Int) + +class Test { + val project1 = new Project("TPS Reports", 1) + val project2 = new Project("Website redesign", 5) + info("Created projects") // Prints "INFO: Created projects" +} +``` + +La méthode `info` est visible grâce à l'import, `import logging.Logger.info`. Les imports ont besoin d'un chemin d'accès stable aux ressources, et un objet est un chemin stable. + +Note : Si un `objet` est encapsulé dans une autre classe ou un autre objet, alors l'objet est dépendant du chemin d'accès, comme les autres membres. Cela veut dire, par exemple, que si on prend 2 types de boissons, `class Milk` et `class OrangeJuice`, un membre de classe `object NutritionInfo` est dépendant de son instance d'encapsulation. `milk.NutritionInfo` est complètement différent de `oj.NutritionInfo`. + +## Les objets compagnons + +Un objet avec le même nom qu'une classe est appelé un _objet compagnon_. Inversement, la classe se nomme la _classe compagnon_ de l'objet. Une classe ou un objet compagnon peut accéder aux membres privés de son compagnon. L'objet compagnon est utile pour les méthodes et les valeurs qui ne sont pas spécifiques aux instances de la classe compagnon. + +``` +import scala.math._ + +case class Circle(radius: Double) { + import Circle._ + def area: Double = calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = Circle(5.0) + +circle1.area +``` + +La classe `class Circle` a un membre `area` qui est spécifique à chaque instance, et un singleton `object Circle` qui a une méthode `calculateArea` qui est disponible pour chaque instance. + +L'objet compagnon peut aussi contenir des méthodes de fabrique (_factory_) : + +```scala mdoc +class Email(val username: String, val domainName: String) + +object Email { + def fromString(emailString: String): Option[Email] = { + emailString.split('@') match { + case Array(a, b) => Some(new Email(a, b)) + case _ => None + } + } +} + +val scalaCenterEmail = Email.fromString("scala.center@epfl.ch") +scalaCenterEmail match { + case Some(email) => println( + s"""Registered an email + |Username: ${email.username} + |Domain name: ${email.domainName} + """.stripMargin) + case None => println("Error: could not parse email") +} +``` + +L'objet `object Email` contient une méthode de fabrique `fromString` qui créé une instance de `Email` depuis une chaîne de caractères. L'instance est retournée en tant que `Option[Email]` pour gérer le cas des erreurs de syntaxe. + +Note : Si une classe ou un objet a un compagnon, tous deux doivent être définis dans le même fichier. Pour définir des compagnons dans le REPL, tous deux doivent être définis sur la même ligne ou définis en mode `:paste`. + +## Notes pour les programmeurs Java + +Les membres `static` en Java sont modélisés comme des membres ordinaires d'un objet compagnon en Scala. + +Lorsqu'on utilise un objet compagnon depuis du code Java, ses membres sont définis dans la classe compagnon avec le modificateur `static`. Cela s'appelle le _static forwarding_. Cela se produit même si vous n'avez pas défini de classe compagnon vous-même. + +## Plus d'informations + +* Apprenez-en plus sur les objets compagnons dans le [Scala Book](/overviews/scala-book/companion-objects.html) + +Traduit par Antoine Pointeau. diff --git a/_fr/tour/tour-of-scala.md b/_fr/tour/tour-of-scala.md new file mode 100644 index 0000000000..f5d0f5d20a --- /dev/null +++ b/_fr/tour/tour-of-scala.md @@ -0,0 +1,90 @@ +--- +layout: tour +title: Introduction +partof: scala-tour + +num: 1 +language: fr +next-page: basics + +--- + +## Bienvenue au tour +Ce tour contient une introduction morceaux par morceaux aux fonctionnalités les plus fréquemment +utilisées en Scala. Il est adressé aux novices de Scala. + +Ceci est un bref tour du language, non pas un tutoriel complet. +Si vous recherchez un guide plus détaillé, il est préférable d'opter pour [un livre](/books.html) ou de suivre +[un cours en ligne](/online-courses.html). + +## Qu'est-ce que le Scala ? +Scala est un langage de programmation à multiples paradigmes désigné pour exprimer des motifs de programmation communs de +façon concise, élégante et robuste. Il intègre sans problème les fonctionnalités des langages orientés objet et des +langages fonctionnels. + +## Scala est orienté objet ## +Scala est un langage purement orienté objet dans le sens où [toute valeur est un objet](unified-types.html). +Les types et les comportements de ces objets sont décrits par des [classes](classes.html) et des trait [traits](traits.html). +Les classes peuvent être étendues à travers des sous-classes et grâce à un système flexible de [composition de classes](mixin-class-composition.html). + +## Scala est fonctionnel ## +Scala est également un langage fonctionnel dans le sen où [toute fonction est une valeur](unified-types.html). +Scala propose une [syntaxe légère](basics.html) pour définir des fonctions anonymes, supporte des +[fonctions de haut niveau](higher-order-functions.html), autorise les fonctions [imbriquées](nested-functions.html) et +supporte le [currying](multiple-parameter-lists.html). +Les [case class](case-classes.html) de Scala et leur système intégré de [reconnaissance de motifs](pattern-matching.html) +permettent de construire des types algébriques utilisés dans de nombreux langages de programmation. +Les [objets singleton](singleton-objects.html) fournissent une façon pratique de regrouper des fonctions qui ne sont pas +membres d'une classe. + +De plus, la notion de reconnaissance de motifs de Scala s'étend naturellement au +[traitement des données XML](https://github.com/scala/scala-xml/wiki/XML-Processing) avec l'aide des +[patrons d'expressions régulières](regular-expression-patterns.html), grâce à une extension générale via des +[objets extracteurs](extractor-objects.html). Dans ce contexte, les [for comprehensions](for-comprehensions.html) sont +utiles pour formuler des requêtes. Ces fonctionnalités font de Scala un langage idéal pour développer des applications +comme des services Web. + +## Scala est fortement typé ## +A la compilation, le système de type expressif de Scala renforce l'utilisation des abstractions d'une manière +sécurisée et cohérente. En particulier, ce système de type supporte : + +* Les [classes génériques](generic-classes.html) +* Les [annotations variables](variances.html) +* Les limites de type [supérieures](upper-type-bounds.html) and [inférieures](lower-type-bounds.html) +* Les [classes internes](inner-classes.html) et les membres d'objets de [types abstraits](abstract-type-members.html) +* Les [types composés](compound-types.html) +* Les [auto-références explicitement typées](self-types.html) +* Les [paramètres](implicit-parameters.html) et les [conversions](implicit-conversions.html) implicites +* Les [méthodes polymorphiques](polymorphic-methods.html) + +L'[inférence de type](type-inference.html) signifie que l'utilisateur n'est pas obligé d'annoter son code avec des +informations redondantes. Rassemblées, toutes ces fonctionnalités fournissent une base solide pour la ré-utilisation +sécurisée d'abstractions de programmation et pour une extension sûre au niveau des types de programme. + +## Scala est extensible ## + +En pratique, le développement d'applications dans un domaine spécifique demande souvent des extensions de langage propre +à ce domaine. Scala fournit une combinaison de mécaniques de langage unique qui rend simple l'ajout de nouvelles +constructions de langage avec l'importation de nouvelles librairies. + +Dans beaucoup de cas, cela peut être fait sans utiliser des outils de méta-programmation, comme les macros. +En voici quelques exemples : + +* Les [classes implicites](/overviews/core/implicit-classes.html) permettent d'ajouter des méthodes supplémentaires à des types existants. +* L'[interpolation de String](/overviews/core/string-interpolation.html) est extensible par l'utilisateur avec des interpolateurs personnalisés. + +## Scala interagit ## + +Scala est conçu pour interagir proprement avec le populaire Java Runtime Environment (JRE). En particulier, l'interaction +avec le langage de programmation orienté objet le plus populaire du moment, Java, est la plus transparente possible. +Les nouvelles fonctionnalités Java comme les SAMs, les [lambdas](higher-order-functions.html), les [annotations](annotations.html), +et les [classes génériques](generic-classes.html) ont des équivalents directs en Scala. + +Il existe des fonctionnalités Scala sans équivalent Java, comme les [valeurs par défaut](default-parameter-values.html) et les +[paramètres nommés](named-arguments.html), qui se compilent d'une façon la plus proche de Java possible. Scala possède le +même modèle de compilation que Java (compilation séparée, chargement dynamique des classes) et permet d'avoir accès à des +milliers de librairies de haute qualité. + +## Bon tour ! + +Merci de continuer à la [page suivante](basics.html) pour en savoir plus. diff --git a/_fr/tour/traits.md b/_fr/tour/traits.md new file mode 100644 index 0000000000..069648bb53 --- /dev/null +++ b/_fr/tour/traits.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Traits +partof: scala-tour + +num: 5 + +language: fr + +next-page: tuples +previous-page: classes +--- diff --git a/_fr/tour/tuples.md b/_fr/tour/tuples.md new file mode 100644 index 0000000000..edef97a6ca --- /dev/null +++ b/_fr/tour/tuples.md @@ -0,0 +1,82 @@ +--- +layout: tour +title: Tuples +partof: scala-tour + +num: 8 + +language: fr + +next-page: mixin-class-composition +previous-page: traits +--- + +En Scala, un tuple est une valeur qui contient un nombre fixe d'éléments, chacun avec son propre type. Les tuples sont immuables. + +Les tuples sont notamment utiles pour retourner plusieurs valeurs depuis une méthode. + +Un tuple avec deux éléments peut être créé de la façon suivante : + +```scala mdoc +val ingredient = ("Sugar" , 25) +``` + +Cela crée un tuple contenant un élément de type `String` et un élément de type `Int`. + +Le type inféré de `ingredient` est `(String, Int)`, qui est un raccourci pour `Tuple2[String, Int]`. + +Pour représenter les tuples, Scala utilise une série de classes : `Tuple2`, `Tuple3`, etc., jusqu'a `Tuple22`. +Chaque classe a autant de paramètres de types qu'elle a d'éléments. + +## Accéder aux éléments + +Une des méthodes pour accéder aux éléments d'un tuple est par position. Les éléments sont nommés individuellement `_1`, `_2`, et ainsi de suite. + +```scala mdoc +println(ingredient._1) // Sugar +println(ingredient._2) // 25 +``` + +## Pattern matching sur les tuples + +Un tuple peut aussi être décomposé en utilisant le pattern matching : + +```scala mdoc +val (name, quantity) = ingredient +println(name) // Sugar +println(quantity) // 25 +``` + +Ici le type inféré de `name` est `String` et le type inféré de `quantity` est `Int`. + +Voici un autre exemple de pattern-matching sur un tuple : + +```scala mdoc +val planets = + List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6), + ("Mars", 227.9), ("Jupiter", 778.3)) +planets.foreach { + case ("Earth", distance) => + println(s"Our planet is $distance million kilometers from the sun") + case _ => +} +``` + +Ou, en décomposition dans un `for` : + +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) +for ((a, b) <- numPairs) { + println(a * b) +} +``` + +## Les tuples et les classes de cas + +Les utilisateurs trouvent parfois qu'il est difficile de choisir entre les tuples et les classes de cas. Les classes de cas ont des éléments nommés. Les noms peuvent améliorer la lisibilité de certains codes. Dans l'exemple ci-dessus avec planet, nous pourrions définir `case class Planet(name: String, distance: Double)` plutôt que d'utiliser les tuples. + +## Plus d'informations + +* Apprennez-en d'avantage sur les tuples dans [Scala Book](/overviews/scala-book/tuples.html) + +Traduction par Antoine Pointeau. \ No newline at end of file diff --git a/_fr/tour/type-inference.md b/_fr/tour/type-inference.md new file mode 100644 index 0000000000..019ed21ef5 --- /dev/null +++ b/_fr/tour/type-inference.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Type Inference +partof: scala-tour + +num: 27 + +language: fr + +next-page: operators +previous-page: polymorphic-methods +--- diff --git a/_fr/tour/unified-types.md b/_fr/tour/unified-types.md new file mode 100644 index 0000000000..6ecf013319 --- /dev/null +++ b/_fr/tour/unified-types.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Unified Types +partof: scala-tour + +num: 3 + +language: fr + +next-page: classes +previous-page: basics +--- diff --git a/_fr/tour/upper-type-bounds.md b/_fr/tour/upper-type-bounds.md new file mode 100644 index 0000000000..f47c6a4e30 --- /dev/null +++ b/_fr/tour/upper-type-bounds.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Upper Type Bounds +partof: scala-tour + +num: 18 + +language: fr + +next-page: lower-type-bounds +previous-page: variances +--- diff --git a/_fr/tour/variances.md b/_fr/tour/variances.md new file mode 100644 index 0000000000..5f535d303b --- /dev/null +++ b/_fr/tour/variances.md @@ -0,0 +1,12 @@ +--- +layout: tour +title: Variance +partof: scala-tour + +num: 17 + +language: fr + +next-page: upper-type-bounds +previous-page: generic-classes +--- diff --git a/_fr/tutorials/scala-for-java-programmers.md b/_fr/tutorials/scala-for-java-programmers.md new file mode 100644 index 0000000000..0b9d3ffa63 --- /dev/null +++ b/_fr/tutorials/scala-for-java-programmers.md @@ -0,0 +1,667 @@ +--- +layout: singlepage-overview +title: Tutoriel Scala pour développeurs Java + +partof: scala-for-java-programmers +language: fr +--- + +Par Michel Schinz and Philipp Haller. + +Traduction et arrangements par Agnès Maury. + +## Introduction + +Ce document présente une introduction rapide au langage Scala et à son compilateur. +Il est destiné aux personnes ayant une expérience de programmation et qui souhaitent +un aperçu de ce qu'ils peuvent faire avec Scala. On part du principe que le lecteur possède +des connaissances de base sur la programmation orientée objet, particulièrement sur Java. + + +## Un premier exemple + +Commençons par écrire le célèbre programme *Hello world*. +Bien que simple, il permet de découvrir plusieurs fonctionnalités du language +avec peu de connaissance préalable de Scala. Voilà à quoi il ressemble : + + object HelloWorld { + def main(args: Array[String]): Unit = { + println("Hello, world!") + } + } + +La structure de ce programme devrait être familière pour les développeurs Java : +il consiste en une méthode appelée `main` qui prend les arguments de la ligne de commande, +une array de String, comme paramètre ; le corps de cette méthode consiste en un simple appel de la méthode +prédéfinie `println` avec le salut amical comme argument. Cette méthode `main` ne retourne pas de valeur. +Pourtant, son type de retour est déclaré comme `Unit`. + +Ce qui est moins familier pour les développeurs Java est la déclaration `object` qui contient la méthode +`main`. Une telle déclaration introduit ce qui est communément connu comme un *objet singleton*, qui est une classe +avec une seule instance. La déclaration ci-dessus déclare à la fois une classe nommée `HelloWorld` +et une instance de cette classe, aussi nommée `HelloWorld`. Cette instance est créée sur demande, c'est-à-dire, +la première fois qu'elle est utilisée. + +Le lecteur avisé a pu remarquer que la méthode `main` n'est pas déclarée en tant que `static`. +C'est parce que les membres statiques (membres ou champs) n'existent pas en Scala. Plutôt que de définir des +membres statiques, le développeur Scala déclare ces membres dans un objet singleton. + +### Compiler l'exemple + +Pour compiler cet exemple, nous utilisons `scalac`, le compilateur Scala. +`scalac` fonctionne comme la plupart des compilateurs : il prend comme argument un fichier source, +potentiellement certaines options, et produit un ou plusieurs fichiers objets. +Les fichiers objets produits sont des fichiers classes de Java classiques. + +Si nous sauvegardons le programme ci-dessus dans un fichier appelé `HelloWorld.scala`, +nous pouvons le compiler en exécutant la commande suivante (le symbole supérieur `>` représente +l'invité de commandes et ne doit pas être écrit) : + + > scalac HelloWorld.scala + +Cette commande va générer un certain nombre de fichiers class dans le répertoire courant. +L'un d'entre eux s'appellera `HelloWorld.class` et contiendra une classe qui pourra être directement exécutée +en utilisant la commande `scala`, comme décrit dans la section suivante. + +### Exécuter l'exemple + +Une fois compilé, le programme Scala peut être exécuté en utilisant la commande `scala`. +Son utilisation est très similaire à la commande `java` utilisée pour exécuter les programmes Java, +et qui accepte les mêmes options. L'exemple ci-dessus peut être exécuté en utilisant la commande suivante, +ce qui produit le résultat attendu : + + > scala -classpath . HelloWorld + + Hello, world! + +## Interaction avec Java + +L'une des forces du Scala est qu'il rend très facile l'interaction avec le code Java. +Toutes les classes du paquet `java.lang` sont importées par défaut, alors que les autres +doivent être importées explicitement. + +Prenons l'exemple suivant. Nous voulons obtenir et formater la date actuelle +par rapport aux conventions utilisées dans un pays spécifique, par exemple la France. + +Les librairies de classes Java définissent des classes utilitaires très puissantes, comme `Date` +et `DateFormat`. Comme Scala interagit avec Java, il n'y a pas besoin de ré-implémenter ces classes en Scala +--nous pouvons simplement importer les classes des paquets correspondants de Java : + + import java.util.{Date, Locale} + import java.text.DateFormat._ + + object DateFrancaise { + def main(args: Array[String]): Unit = { + val maintenant = new Date + val df = getDateInstance(LONG, Locale.FRANCE) + println(df format maintenant) + } + } + +Les déclarations d'import de Scala sont très similaires à celle de Java, cependant, +elles sont bien plus puissantes. Plusieurs classes peuvent être importées du même paquet en les plaçant +dans des accolades comme démontré dans la première ligne. Une autre différence notable est de pouvoir +importer tous les noms d'un paquet ou d'une classe en utilisant le symbole underscore (`_`) au lieu de +l'astérisque (`*`). C'est parce que l'astérisque est un identifiant valide en Scala (par exemple pour +un nom de méthode), comme nous le verrons plus tard. + +Par conséquent, la déclaration d'importation dans la seconde ligne importe tous les membres de la classe +`DateFormat`. Cela rend la méthode statique `getDateInstance` et le champ statique `LONG` +directement visibles. + +Dans la méthode `main`, nous avons tout d'abord créé une instance de la classe Java `Date` +qui contient par défaut la date actuelle. Ensuite, nous définissons un format de date en utilisant la +méthode statique `getDateInstance` que nous avons importée précédemment. Enfin, nous imprimons +la date actuelle selon l'instance de `DateFormat` localisée. Cette dernière ligne montre une +propriété intéressante de la syntaxe Scala. Les méthodes qui ne prennent en entrée qu'un seul argument +peuvent être utilisées avec une syntaxe infixe. C'est-à-dire que l'expression + + df format maintenant + +est juste une autre façon moins verbeuse d'écrire l'expression + + df.format(maintenant) + +Cela peut paraître comme un détail syntaxique mineur, mais il entraîne des conséquences importantes, +dont l'une va être explorée dans la section suivante. + +Pour conclure cette section sur l'intégration avec Java, il faut noter qu'il est possible +d'hériter de classes Java et d'implémenter des interfaces Java directement en Scala. + +## Tout est objet + +Scala est un langage purement orienté objet dans le sens où *tout* est un objet, +y compris les nombres ou les fonctions. Cela diffère du Java dans cet aspect, car Java +distingue les types primitifs (comme `boolean` et `int`) des types référentiels. + +### Les nombres sont des objets + +Étant donné que les nombres sont des objets, ils ont aussi des méthodes. +De fait, une expression arithmétique comme la suivante : + + 1 + 2 * 3 / x + +consiste exclusivement en des appels de méthodes, parce qu'il est équivalent à l'expression +suivante, comme nous l'avons vu dans la section précédente : + + 1.+(2.*(3)./(x) + +Cela veut aussi dire que `+`, `*`, etc. sont des identifiants valides en Scala. + +### Les fonctions sont des objets + +Les fonctions sont aussi des objets en Scala. C'est pourquoi il est possible de passer +des fonctions en arguments, de les stocker dans des variables et de les retourner depuis d'autres +fonctions. Cette capacité à manipuler les fonctions en tant que valeurs est l'une des +pierres angulaires d'un paradigme de programmation très intéressant nommé *programmation fonctionnelle*. + +Pour illustrer à quel point il est peut être utile d'utiliser des fonctions en tant que valeurs, +considérons une fonction minuteur qui vise à performer une action toutes les secondes. Comment faire +pour passer au minuteur une action à performer ? En toute logique, comme une fonction. Ce concept de +passer une fonction devrait être familier à beaucoup de développeurs : il est souvent utilisé dans +le code d'interface utilisateur pour enregistrer des fonctions de rappel qui sont invoquées lorsque +certains évènements se produisent. + +Dans le programme suivant, la fonction minuteur est appelée `uneFoisParSeconde` et prend comme argument +une fonction de rappel. Le type de cette fonction est écrit `() => Unit`. C'est le type de toutes les +fonctions qui ne prennent aucun argument et ne renvoie rien (le type `Unit` est similaire à `void` en C/C++). +La principale fonction de ce programme est d'appeler la fonction minuteur avec une fonction de rappel +qui imprime une phrase dans le terminal. Dans d'autres termes, ce programme imprime à l'infini la phrase +"le temps passe comme une flèche". + + object Minuteur { + def uneFoisParSeconde(retour: () => Unit): Unit = { + while (true) { + retour() + Thread sleep 1000 + } + } + + def leTempsPasse(): Unit = { + println("le temps passe comme une flèche") + } + + def main(args: Array[String]): Unit = { + uneFoisParSeconde(leTempsPasse) + } + } + +Notez que pour imprimer la String, nous utilisons la méthode prédéfinie `println` au lieu +d'utiliser celle du paquet `System.out`. + +#### Fonctions anonymes + +Bien que ce programme soit facile à comprendre, il peut être affiné un peu plus. +Premièrement, notez que la fonction `leTempsPasse` est définie uniquement dans le but d'être +passée plus tard dans la fonction `uneFoisParSeconde`. Devoir nommer cette fonction qui ne va +être utilisée qu'une fois peut sembler superflu et il serait plus agréable de pouvoir construire +cette fonction juste au moment où elle est passée à `uneFoisParSeconde`. C'est possible en Scala +en utilisant des *fonctions anonymes*, ce qui correspond exactement à ça : des fonctions sans nom. +La version revisitée de notre programme minuteur en utilisant une fonction anonyme à la place de +*leTempsPasse* ressemble à ça : + + object MinuteurAnonyme { + def uneFoisParSeconde(retour: () => Unit): Unit = { + while (true) { + retour() + Thread sleep 1000 + } + } + + def main(args: Array[String]): Unit = { + uneFoisParSeconde( + () => println("le temps passe comme une flèche") + ) + } + } + +La présence d'une fonction anonyme dans cet exemple est reconnaissable par la flèche pointant à droite +`=>` qui sépare la liste des arguments de la fonction de son corps. Dans cet exemple, la liste des +arguments est vide, comme en témoigne la paire de parenthèses vide à gauche de la flèche. Le corps +de cette fonction est le même que celui de `leTempsPasse` décrit plus haut. + +## Classes + +Comme nous l'avons vu plus tôt, Scala est un langage orienté objet et de ce fait, possède le concept de classe +(pour être plus exact, il existe certains langages orientés objet qui ne possèdent pas le concept de classe +mais Scala n'en fait pas partie). Les classes en Scala sont déclarées en utilisant une syntaxe proche de +celle de Java. Une différence notable est que les classes en Scala peuvent avoir des paramètres. +Ceci est illustré dans la définition suivante des nombres complexes. + + class Complexe(reel: Double, imaginaire: Double) { + def re() = reel + def im() = imaginaire + } + +La classe `Complexe` prend en entrée deux arguments : la partie réelle et la partie imaginaire du +nombre complexe. Ces arguments peuvent être passés lors de la création d'une instance de `Complexe` comme +ceci : + + new Complexe(1.5, 2.3) + +La classe contient deux méthodes, appelées `re` et `im` qui donnent accès à ces deux parties. + +Il faut noter que le type de retour de ces méthodes n'est pas explicitement donné. Il sera inféré +automatiquement par le compilateur, qui regarde la partie droite de ces méthodes et en déduit que chacune +de ces fonctions renvoie une valeur de type `Double`. + +Le compilateur n'est pas toujours capable d'inférer des types comme il le fait ici et il n'y a +malheureusement aucune règle simple pour savoir dans quel cas il est capable de le faire. En pratique, +ce n'est pas généralement un problème car le compilateur se plaint quand il n'est pas capable d'inférer +un type qui n'a pas été donné explicitement. Une règle simple que les développeurs débutant en Scala +devraient suivre est d'essayer d'omettre les déclarations de type qui semblent être faciles à +déduire et voir si le compilateur ne renvoie pas d'erreur. Après quelque temps, le développeur devrait +avoir une bonne idée de quand il peut omettre les types et quand il faut les spécifier explicitement. + +### Les méthodes sans arguments + +Un petit problème des méthodes `re` et `im` est qu'il faut mettre une paire de parenthèses vides après +leur nom pour les appeler, comme démontré dans l'exemple suivant : + + object NombresComplexes { + def main(args: Array[String]): Unit = { + val c = new Complexe(1.2, 3.4) + println("partie imaginaire : " + c.im()) + } + } + +Il serait plus agréable de pouvoir accéder à la partie réelle et imaginaire comme si elles étaient des +champs, sans ajouter une paire de parenthèses vides. C'est parfaitement faisable en Scala, simplement en +les définissant comme des méthodes *sans argument*. De telles méthodes diffèrent des méthodes avec +aucun argument : elles n'ont pas de parenthèses après leur nom, que ce soit dans leur déclaration +ou lors de leur utilisation. Notre classe `Complexe` peut être réécrite de cette façon : + + class Complexe(reel: Double, imaginaire: Double) { + def re = reel + def im = imaginaire + } + + +### Héritage et redéfinition + +Toutes les classes en Scala héritent d'une super classe. Quand aucune super classe n'est spécifiée, +comme dans l'exemple `Complexe` de la section précédente, la classe `scala.AnyRef` est utilisée +implicitement. + +Il est possible de redéfinir les méthodes héritées d'une super classe en Scala. Cependant, il est +obligatoire de spécifier explicitement qu'une méthode en redéfinit une autre en utilisant le +modificateur `override` dans le but d'éviter les redéfinitions accidentelles. Dans notre exemple, +la classe `Complexe` peut être enrichie avec une redéfinition de la méthode `toString` héritée +de la classe `Object`. + + class Complexe(reel: Double, imaginaire: Double) { + def re() = reel + def im() = imaginaire + override def toString() = "" + re + (if (im >= 0) "+" + im + "i" else "") + } + +Nous pouvons alors appeler la méthode `toString` redéfinie comme ci-dessus. + + object NombresComplexes { + def main(args: Array[String]): Unit = { + val c = new Complexe(1.2, 3.4) + println("toString() redéfinie : " + c.toString) + } + } + +## Les case class et le pattern matching + +L'arbre est un type de structure de données qui revient souvent. +Par exemple, les interpréteurs et les compilateurs représentent généralement en interne les programmes +comme des arbres ; les documents XML sont des arbres ; et beaucoup de conteneurs sont basés sur des +arbres, comme les arbres bicolores. + +Nous allons maintenant examiner comment de tels arbres sont représentés et manipulés en Scala à travers +d'un petit programme de calculatrice. Le but de ce programme est de manipuler des expressions arithmétiques +simples composées de sommes, de constantes numériques et de variables. Deux exemples de telles expressions +sont `1+2` et `(x+x)+(7+y)`. + +Nous devons d'abord décider d'une représentation pour de telles expressions. +La manière la plus naturelle est un arbre où chaque nœud représente une opération (ici, une addition) et +chaque feuille est une valeur (ici des constantes ou variables). + +En Java, un tel arbre serait représenté par une super classe abstraite pour les arbres et une +sous classe concrète pour chaque nœud et feuille. Dans un langage de programmation fonctionnelle, +on utiliserait plutôt un type de donnée algébrique pour faire la même chose. Scala fournit le concept de +*case class* qui est quelque part entre ces deux concepts. Voici comment elles peuvent être utilisées pour +définir le type des arbres pour notre exemple : + + abstract class Arbre + case class Somme(l: Arbre, r: Arbre) extends Arbre + case class Var(n: String) extends Arbre + case class Const(v: Int) extends Arbre + +Le fait que les classes `Somme`, `Var` et `Const` sont définies en tant que case class signifie qu'elles +différent des classes traditionnelles en différents points : + +- le mot clé `new` n'est pas obligatoire lors de la création d'instance de ces classes (c'est-à-dire qu'on + peut écrire `Const(5)` à la place de `new Const(5)`) ; +- les fonctions accesseurs sont automatiquement définies pour les paramètres du constructeur + (c'est-à-dire qu'il est possible de récupérer la valeur du paramètre du constructeur `v` pour une instance `c` de + la classe `Const` en écrivant tout simplement `c.v`) ; +- une définition par défaut des méthodes `equals` et `hashCode` est fournie, qui se base sur la + *structure* des instances et non pas leur identité ; +- une définition par défaut de la méthode `toString` est fournie et imprime la valeur "à la source" + (par exemple, l'arbre pour l'expression `x+1` s'imprime comme `Somme(Var(x),Const(1))`) ; +- les instances de ces classes peuvent être décomposées avec un *pattern matching* (filtrage par motif) + comme nous le verrons plus bas. + +Maintenant que nous avons défini le type de données pour représenter nos expressions arithmétiques, +il est temps de définir des opérations pour les manipuler. Nous allons commencer par une fonction +pour évaluer une expression dans un certain *environnement*. Le but de cet environnement est de +donner des valeurs aux variables. Par exemple, l'expression `x+1` évaluée dans un environnement qui +associe la valeur `5` à la variable `x`, écrit `{ x -> 5 }`, donne comme résultat `6`. + +Il faut donc trouver un moyen de représenter ces environnements. Nous pouvons certes utiliser +une sorte de structure de données associatives comme une table de hashage, mais nous pouvons aussi +utiliser directement des fonctions ! Un environnement n'est ni plus ni moins qu'une fonction qui associe +une valeur à une variable. L'environnement `{ x -> 5 }` décrit plus tôt peut être écrit simplement comme +ceci en Scala : + + { case "x" => 5 } + +Cette notation définit une fonction qui, quand on lui donne une String `"x"` en entrée, retourne l'entier +`5` et renvoie une exception dans les autres cas. + +Avant d'écrire la fonction d'évaluation, donnons un nom au type de ces environnements. +Nous pouvons toujours utiliser le `String => Int` pour ces environnements mais cela simplifie +le programme si nous introduisons un nom pour ce type et rendra les modifications futures plus simples. +En Scala, on le réalise avec la notation suivante : + + type Environnement = String => Int + +À partir de maintenant, le type `Environnement` peut être utilisé comme un alias comme +le type des fonctions de `String` à `Int`. + +Maintenant, nous pouvons donner la définition de l'évaluation de fonction. +Théoriquement, c'est très simple : la valeur d'une somme de deux expressions +est tout simplement la somme des valeurs de ces expressions ; la valeur d'une +variable est obtenue directement à partir de l'environnement ; la valeur d'une +constante est la constante elle-même. Pour l'exprimer en Scala, ce n'est pas plus +compliqué : + + def eval(a: Arbre, env: Environnement): Int = a match { + case Somme(l, r) => eval(l, env) + eval(r, env) + case Var(n) => env(n) + case Const(v) => v + } + +Cette fonction d'évaluation fonctionne en effectuant un pattern matching +sur l'arbre `a`. De façon intuitive, la signification de la définition ci-dessus +devrait être claire : + +1. Tout d'abord, il vérifie si l'arbre `a` est une `Somme`. Si c'est le cas, + il relie le sous arbre de gauche à une nouvelle variable appelée `l` et + le sous arbre de gauche à une variable appelée `r`. Ensuite, il traite + l'expression à droite de la flèche : cette expression peut + utiliser (dans notre exemple, c'est le cas) les deux variables `l` et `r` extraites dans le + motif décrit à gauche de la flèche ; +2. Si la première vérification échoue, c'est-à-dire que l'arbre n'est pas une `Somme`, + on continue et on vérifie si `a` est une `Var`. Si c'est le cas, + il relie le nom contenu dans le nœud `Var` à une variable `n` et + il traite l'expression à droite de la flèche ; +3. Si la deuxième vérification échoue, c'est-à-dire que l'arbre n'est ni + une `Somme` ni une `Var`, on vérifie si l'arbre est un `Const`. Si + c'est le cas, il relie la valeur contenue dans le nœud `Const` à une + variable `v` et il traite l'expression à droite de la flèche ; +4. Enfin, si toutes les vérifications échouent, une exception est levée pour signaler + l'échec de l'expression. Dans notre cas, cela pourrait arriver si + d'autres sous classes de `Arbre` étaient déclarées. + +Nous observons que l'idée basique du pattern matching est de faire correspondre +une valeur à une série de motifs et dès qu'un motif correspond, extraire +et nommer les différentes parties de la valeur pour enfin évaluer du +code qui, généralement, utilise ces parties nommées. + +Un développeur orienté objet chevronné pourrait se demander pourquoi nous n'avions pas +défini `eval` comme une *méthode* de la classe `Arbre` et de ces +sous classes. En effet, nous aurions pu le faire, étant donné que Scala autorise +la définition de méthodes dans les case class tout comme dans les classes normales. +Décider d'utiliser un pattern matching ou des méthodes est donc une question de +goût mais a aussi des implications importantes sur l'extensibilité : + +- quand on utilise des méthodes, il est facile d'ajouter un nouveau type de nœud en même temps + qu'une nouvelle sous classe de `Arbre` est définie. Par contre, + ajouter une nouvelle opération pour manipuler un arbre est + fastidieux car il demande de modifier toutes les sous classes de `Arbre` ; +- quand on utilise un pattern matching, la situation est inversée : ajouter un + nouveau type de nœud demande la modification de toutes les fonctions qui effectuent + un pattern matching sur un arbre pour prendre en compte le nouveau nœud. + Par contre, ajouter une nouvelle opération est facile en la définissant + en tant que fonction indépendante. + +Pour explorer plus loin dans le pattern matching, définissons une autre opération +sur les expressions arithmétiques : la dérivée de fonction. Le lecteur doit +garder à l'esprit les règles suivantes par rapport à cette opération : + +1. la dérivée d'une somme est la somme des dérivées ; +2. la dérivée d'une variable `v` est 1 si `v` est égale la + variable utilisée pour la dérivation et zéro sinon ; +3. la dérivée d'une constante est zéro. + +Ces règles peuvent presque être traduites littéralement en du code Scala +pour obtenir la définition suivante : + + def derivee(a: Arbres, v: String): Arbres = a match { + case Somme(l, r) => Somme(derivee(l, v), derivee(r, v)) + case Var(n) if (v == n) => Const(1) + case _ => Const(0) + } + +Cette fonction introduit deux nouveaux concepts reliés au pattern matching. + +Premièrement, l'expression `case` qui peut être utilisé avec un *garde* qui suit le mot clé `if`. +Ce garde empêche le pattern matching de réussir à moins que l'expression soit vraie. Ici, il est utilisé +pour s'assurer qu'on retourne la constante `1` uniquement si le nom de +la variable se faisant dériver est la même que la variable de dérivation +`v`. La seconde nouvelle fonctionnalité du pattern matching utilisée ici est +le motif *joker*, représenté par `_`, qui est un motif correspondant à +n'importe quelle valeur sans lui donner un nom. + +Nous n'avons pas encore exploré l'étendue du pouvoir du pattern matching, mais nous +nous arrêterons ici afin de garder ce document court. Nous voulons toujours +voir comment les deux fonctions ci-dessus fonctionnent dans un exemple réel. Pour se +faire, écrivons une fonction `main` simple qui effectue plusieurs opérations sur l'expression +`(x+x)+(7+y)` : elle évalue tout d'abord sa valeur dans l'environnement +`{ x -> 5, y -> 7 }` puis on la dérive par rapport à `x` et par rapport à `y`. + + def main(args: Array[String]): Unit = { + val exp: Arbre = Somme(Somme(Var("x"),Var("x")),Somme(Const(7),Var("y"))) + val env: Environnement = { case "x" => 5 case "y" => 7 } + println("Expression : " + exp) + println("Évaluation avec x=5, y=7 : " + eval(exp, env)) + println("Dérivée par rapport à x :\n " + derivee(exp, "x")) + println("Dérivée par rapport à y :\n " + derivee(exp, "y")) + } + +Vous devrez envelopper le type `Environnement` et les méthodes`eval`, `derivee` et `main` +dans un objet `Calc` avant de compiler. En exécutant ce programme, on obtient le résultat attendu : + + Expression : Somme(Somme(Var(x),Var(x)),Somme(Const(7),Var(y))) + Évaluation avec x=5, y=7 : 24 + Dérivée par rapport à x : + Somme(Somme(Const(1),Const(1)),Somme(Const(0),Const(0))) + Dérivée par rapport à y : + Somme(Somme(Const(0),Const(0)),Somme(Const(0),Const(1))) + +En examinant la sortie, on voit que le résultat de la dérivée devrait être simplifiée avant +d'être présentée à l'utilisateur. Définir une simplification basique en utilisant +un pattern matching est un problème intéressant (mais curieusement délicat), laissé +comme exercice pour le lecteur. + +## Traits + +Hormis le fait d'hériter du code d'une super classe, une classe Scala peut aussi +importer du code d'un ou de plusieurs *traits*. + +Peut-être que le moyen le plus simple pour un développeur Java de comprendre les traits +est de le voir comme une interface qui peut aussi contenir du code. En +Scala, quand une classe hérite d'un trait, elle implémente son interface et +hérite de tout le code contenu dans ce trait. + +Notez que depuis Java 8, les interfaces Java peut aussi contenir du code, soit +en utilisant le mot clé `default` soit avec des méthodes statiques. + +Pour s'apercevoir de l'utilité des traits, regardons un exemple classique : +les objets ordonnés. Il est souvent utile de pouvoir comparer des objets +d'une même classe, par exemple pour les trier. En Java, +les objets qui sont comparables implémentent l'interface `Comparable`. +En Scala, on peut faire un peu mieux qu'en Java en définissant +notre équivalent de `Comparable` en tant que trait, qu'on appellera +`Ord`. + +Quand on compare des objets, six différents prédicats peuvent être utiles : +plus petit, plus petit ou égal, égal, inégal, plus grand, plus grand ou égal. +Cependant, tous les définir est fastidieux, surtout que quatre de ces six +prédicats peuvent être exprimés en utilisant les deux restantes. En effet, +en utilisant les prédicats égal et plus petit (par exemple), on peut +exprimer les autres. En Scala, toutes ces observations peuvent être +capturées dans la déclaration de trait suivante : + + trait Ord { + def < (that: Any): Boolean + def <=(that: Any): Boolean = (this < that) || (this == that) + def > (that: Any): Boolean = !(this <= that) + def >=(that: Any): Boolean = !(this < that) + } + +Cette définition crée à la fois un nouveau type appelé `Ord`, +qui joue un rôle similaire à l'interface Java `Comparable`, et +des implémentations par défaut de trois prédicats par rapport à un +quatrième prédicat abstrait. Les prédicats d'égalité et d'inégalité n'apparaissent pas +ici vu qu'ils sont présents par défaut dans tous les objets. + +Le type `Any` qui est utilisé plus haut est le type +qui est le super type de tous les autres types en Scala. Il peut être vu comme une +version plus générale du type Java `Object`, puisqu'il est aussi un +super type de types basic comme `Int`, `Float`, etc. + +Pour rendre les objets d'une classes comparables, il est alors suffisant de +définir les prédicats qui testent l'égalité et l'infériorité, puis les mixer +dans la classe `Ord` ci-dessus. Comme exemple, définissons une +classe `Date` qui représente les dates dans le calendrier grégorien. Elles +sont composées d'un jour, un mois et une année, que nous allons +représenter avec des entiers. Nous commençons toutefois la définition de la +classe `Date` comme ceci : + + class Date(a: Int, m: Int, j: Int) extends Ord { + def annee = a + def mois = m + def jour = j + override def toString(): String = annee + "-" + mois + "-" + jour + +La partie importante ici est la déclaration `extends Ord` qui +suit le nom de la classe et ses paramètres. Cela veut dire que la +classe `Date` hérite du trait `Ord`. + +Ensuite, nous redéfinissons la méthode `equals`, héritée de `Object`, +pour comparer correctement les dates en comparant leur +champs individuels. L'implémentation par défaut de `equals` n'est pas +utilisable, car en Java, elle compare les objets physiquement. On arrive +à la définition suivante : + + override def equals(that: Any): Boolean = + that.isInstanceOf[Date] && { + val d = that.asInstanceOf[Date] + d.jour == jour && d.mois == mois && d.annee == annee + } + +Cette méthode utilise les méthodes prédéfinies `isInstanceOf` et +`asInstanceOf`. La première méthode, `isInstanceOf` correspond à l'opérateur +Java `instanceof` et retourne true si et seulement si l'objet +sur lequel elle est appliquée est une instance du type donné. +La deuxième, `asInstanceOf`, correspond à l'opérateur de conversion de type : +si l'objet est une instance du type donné, il est vu en tant que tel, +sinon une `ClassCastException` est levée. + +Enfin, la dernière méthode à définir est le prédicat qui teste l'infériorité +comme décrit plus loin. Elle utilise une autre méthode, +`error` du paquet `scala.sys`, qui lève une exception avec le message d'erreur donné. + + def <(that: Any): Boolean = { + if (!that.isInstanceOf[Date]) + sys.error("on ne peut pas comparer " + that + " et une Date") + + val d = that.asInstanceOf[Date] + (annee < d.annee) || + (annee == d.annee && (mois < d.mois || + (mois == d.mois && jour < d.jour))) + } + +Cela complète la définition de la classe `Date`. Les instances de +cette classe peuvent être vues soit comme des dates, soit comme des objets comparables. +De plus, elles définissent les six prédicats de comparaison mentionnés +ci-dessus : `equals` et `<` car elles apparaissent directement dans +la définition de la classe `Date`, ainsi que les autres qui sont directement héritées du trait `Ord`. + +Bien sûr, les traits sont utiles dans d'autres situations que celle décrite ici, +mais discuter de leurs applications plus amplement est hors de la +portée de document. + +## Généricité + +La dernière caractéristique de Scala que nous allons explorer dans ce tutoriel est +la généricité. Les développeurs Java devraient être conscients des problèmes +posés par le manque de généricité dans leur langage, une lacune qui +a été compensée avec Java 1.5. + +La généricité est la capacité d'écrire du code paramétrisé par des types. Par +exemple, un développeur qui écrit une librairie pour des listes liées fait face au +problème de décider quel type donner aux éléments de la liste. +Comme cette liste est destinée à être utilisée dans divers contextes, il n'est +pas possible de décider quel type doit avoir les éléments de liste, par exemple, +`Int`. Ce serait complètement arbitraire et excessivement restrictif. + +Les développeurs Java se retrouvent à utiliser `Object`, le super type de +tous les objets. Cependant, cette solution est loin d'être +idéale, puisqu'elle ne marche pas pour les types basiques (`int`, +`long`, `float`, etc.) et cela implique que le développeur +devra faire un certain nombre de conversions de types. + +Scala rend possible la définition de classes (et de méthodes) génériques pour +résoudre ce problème. Examinons ceci au travers d'un exemple d'une +classes conteneur la plus simple possible : une référence, qui peut être +vide ou pointer vers un objet typé. + + class Reference[T] { + private var contenu: T = _ + def set(valeur: T) { contenu = valeur } + def get: T = contenu + } + +La classe `Reference` est paramétrisé par un type appelé `T` +qui est le type de son élément. Ce type est utilisé dans le corps de la +classe en tant que de la variable `contenu`, l'argument de la méthode +`set` et le type de retour de la méthode `get`. + +L'échantillon de code ci-dessus introduit les variables en Scala, ce qui ne devrait pas +demander plus d'explications. Cependant, il est intéressant de voir que +la valeur initiale donnée à la variable est `_` qui représente +une valeur par défaut. Cette valeur par défaut est 0 pour les types numériques, +`false` pour le type `Boolean`, `()` pour le type `Unit` +et `null` pour tous les types d'objet. + +Pour utiliser cette classe `Reference`, il faut spécifier quel type utiliser +pour le type paramètre `T`, le type de l'élément contenu dans la cellule. +Par exemple, pour créer et utiliser une cellule contenant +un entier, on peut écrire : + + object ReferenceEntier { + def main(args: Array[String]): Unit = { + val cellule = new Reference[Int] + cellule.set(13) + println("La référence contient la moitié de " + (cellule.get * 2)) + } + } + +Comme on peut le voir dans l'exemple, il n'est pas nécessaire de convertir la valeur +retournée par la méthode `get` avant de pouvoir l'utiliser en tant qu'entier. Il +n'est pas possible de stocker autre chose d'un entier dans cette +cellule particulière, puisqu'elle a été déclarée comme portant un entier. + +## Conclusion + +Ce document donne un rapide aperçu du langage Scala et +présente quelques exemples basiques. Le développeur intéressé peut poursuivre sa lecture, +par exemple, en lisant le *[Tour of Scala](https://docs.scala-lang.org/tour/tour-of-scala.html)* +(document en anglais) et consulter la *spécification du langage Scala* si nécessaire. diff --git a/glossary/index.md b/_glossary/index.md similarity index 86% rename from glossary/index.md rename to _glossary/index.md index 6959c4048a..9d4d490c65 100644 --- a/glossary/index.md +++ b/_glossary/index.md @@ -1,393 +1,395 @@ --- layout: glossary title: Glossary + +languages: [zh-cn] --- -
Glossary from the definitive book on Scala, Programming in Scala.
+
Glossary from the definitive book on Scala, Programming in Scala.
- +  
-* #### algebraic data type +* ### algebraic data type A type defined by providing several alternatives, each of which comes with its own constructor. It usually comes with a way to decompose the type through pattern matching. The concept is found in specification languages and functional programming languages. Algebraic data types can be emulated in Scala with case classes. -* #### alternative +* ### alternative A branch of a match expression. It has the form “`case` _pattern_ => _expression_.” Another name for alternative is _case_. -* #### annotation +* ### annotation An annotation appears in source code and is attached to some part of the syntax. Annotations are computer processable, so you can use them to effectively add an extension to Scala. -* #### anonymous class +* ### anonymous class An anonymous class is a synthetic subclass generated by the Scala compiler from a new expression in which the class or trait name is followed by curly braces. The curly braces contains the body of the anonymous subclass, which may be empty. However, if the name following new refers to a trait or class that contains abstract members, these must be made concrete inside the curly braces that define the body of the anonymous subclass. -* #### anonymous function +* ### anonymous function Another name for [function literal](#function-literal). -* #### apply +* ### apply You can apply a method, function, or closure to arguments, which means you invoke it on those arguments. -* #### argument +* ### argument When a function is invoked, an argument is passed for each parameter of that function. The parameter is the variable that refers to the argument. The argument is the object passed at invocation time. In addition, applications can take (command line) arguments that show up in the `Array[String]` passed to main methods of singleton objects. -* #### assign +* ### assign You can assign an object to a variable. Afterwards, the variable will refer to the object. -* #### auxiliary constructor +* ### auxiliary constructor Extra constructors defined inside the curly braces of the class definition, which look like method definitions named `this`, but with no result type. -* #### block -One or more expressions and declarations surrounded by curly braces. When the block evaluates, all of its expressions and declarations are processed in order, and then the block returns the value of the last expression as its own value. Blocks are commonly used as the bodies of functions, [for expressions](#for-expression), `while` loops, and any other place where you want to group a number of statements together. More formally, a block is an encapsulation construct for which you can only see side effects and a result value. The curly braces in which you define a class or object do not, therefore, form a block, because fields and methods (which are defined inside those curly braces) are visible from the out- side. Such curly braces form a template. +* ### block +One or more expressions and declarations surrounded by curly braces. When the block evaluates, all of its expressions and declarations are processed in order, and then the block returns the value of the last expression as its own value. Blocks are commonly used as the bodies of functions, [for expressions](#for-expression), `while` loops, and any other place where you want to group a number of statements together. More formally, a block is an encapsulation construct for which you can only see side effects and a result value. The curly braces in which you define a class or object do not, therefore, form a block, because fields and methods (which are defined inside those curly braces) are visible from the outside. Such curly braces form a template. -* #### bound variable +* ### bound variable A bound variable of an expression is a variable that’s both used and defined inside the expression. For instance, in the function literal expression `(x: Int) => (x, y)`, both variables `x` and `y` are used, but only `x` is bound, because it is defined in the expression as an `Int` and the sole argument to the function described by the expression. -* #### by-name parameter +* ### by-name parameter A parameter that is marked with a `=>` in front of the parameter type, e.g., `(x: => Int)`. The argument corresponding to a by-name parameter is evaluated not before the method is invoked, but each time the parameter is referenced by name inside the method. If a parameter is not by-name, it is by-value. -* #### by-value parameter +* ### by-value parameter A parameter that is not marked with a `=>` in front of the parameter type, e.g., `(x: Int)`. The argument corresponding to a by-value parameter is evaluated before the method is invoked. By-value parameters contrast with by-name parameters. -* #### class +* ### class Defined with the `class` keyword, a _class_ may either be abstract or concrete, and may be parameterized with types and values when instantiated. In `new Array[String](2)`, the class being instantiated is `Array` and the type of the value that results is `Array[String]`. A class that takes type parameters is called a _type constructor_. A type can be said to have a class as well, as in: the class of type `Array[String]` is `Array`. -* #### closure +* ### closure A function object that captures free variables, and is said to be “closed” over the variables visible at the time it is created. -* #### companion class +* ### companion class A class that shares the same name with a singleton object defined in the same source file. The class is the singleton object’s companion class. -* #### companion object +* ### companion object A singleton object that shares the same name with a class defined in the same source file. Companion objects and classes have access to each other’s private members. In addition, any implicit conversions defined in the companion object will be in scope anywhere the class is used. -* #### contravariant +* ### contravariant A _contravariant_ annotation can be applied to a type parameter of a class or trait by putting a minus sign (-) before the type parameter. The class or trait then subtypes contravariantly with—in the opposite direction as—the type annotated parameter. For example, `Function1` is contravariant in its first type parameter, and so `Function1[Any, Any]` is a subtype of `Function1[String, Any]`. -* #### covariant +* ### covariant A _covariant_ annotation can be applied to a type parameter of a class or trait by putting a plus sign (+) before the type parameter. The class or trait then subtypes covariantly with—in the same direction as—the type annotated parameter. For example, `List` is covariant in its type parameter, so `List[String]` is a subtype of `List[Any]`. -* #### currying +* ### currying A way to write functions with multiple parameter lists. For instance `def f(x: Int)(y: Int)` is a curried function with two parameter lists. A curried function is applied by passing several arguments lists, as in: `f(3)(4)`. However, it is also possible to write a _partial application_ of a curried function, such as `f(3)`. -* #### declare +* ### declare You can _declare_ an abstract field, method, or type, which gives an entity a name but not an implementation. The key difference between declarations and definitions is that definitions establish an implementation for the named entity, declarations do not. -* #### define +* ### define To _define_ something in a Scala program is to give it a name and an implementation. You can define classes, traits, singleton objects, fields, methods, local functions, local variables, _etc_. Because definitions always involve some kind of implementation, abstract members are declared not defined. -* #### direct subclass +* ### direct subclass A class is a _direct subclass_ of its direct superclass. -* #### direct superclass +* ### direct superclass The class from which a class or trait is immediately derived, the nearest class above it in its inheritance hierarchy. If a class `Parent` is mentioned in a class `Child`’s optional extends clause, then `Parent` is the direct superclass of `Child`. If a trait is mentioned in `Child`’s extends clause, the trait’s direct superclass is the `Child`’s direct superclass. If `Child` has no extends clause, then `AnyRef` is the direct superclass of `Child`. If a class’s direct superclass takes type parameters, for example class `Child` extends `Parent[String]`, the direct superclass of `Child` is still `Parent`, not `Parent[String]`. On the other hand, `Parent[String]` would be the direct supertype of `Child`. See [supertype](#supertype) for more discussion of the distinction between class and type. -* #### equality +* ### equality When used without qualification, _equality_ is the relation between values expressed by `==`. See also [reference equality](#reference-equality). -* #### existential type +* ### existential type An existential type includes references to type variables that are unknown. For example, `Array[T] forSome { type T }` is an existential type. It is an array of `T`, where `T` is some completely unknown type. All that is assumed about `T` is that it exists at all. This assumption is weak, but it means at least that an `Array[T] forSome { type T }` is indeed an array and not a banana. -* #### expression +* ### expression Any bit of Scala code that yields a result. You can also say that an expression _evaluates_ to a result or _results_ in a value. -* #### filter +* ### filter An `if` followed by a boolean expression in a [for expression](#for-expression). In `for(i <- 1 to 10; if i % 2 == 0)`, the filter is “`if i % 2 == 0`”. The value to the right of the `if` is the [filter expression](#filter-expression). Also known as a guard. -* #### filter expression +* ### filter expression A _filter expression_ is the boolean expression following an `if` in a [for expression](#for-expression). In `for( i <- 1 to 10 ; if i % 2 == 0)`,the filter expression is “`i % 2 == 0`”. -* #### first-class function +* ### first-class function Scala supports _first-class functions_, which means you can express functions in function literal syntax, i.e., `(x: Int) => x + 1`, and that functions can be represented by objects, which are called [function values](#function-value). -* #### for comprehension +* ### for comprehension A _for comprehension_ is a type of [for expression](#for-expression) that creates a new collection. For each iteration of the `for` comprehension, the [yield](#yield) clause defines an element of the new collection. For example, `for (i <- (0 until 2); j <- (2 until 4)) yield (i, j)` returns the collection `Vector((0,2), (0,3), (1,2), (1,3))`. -* #### for expression +* ### for expression A _for expression_ is either a [for loop](#for-loop), which iterates over one or more collections, or a [for comprehension](#for-comprehension), which builds a new collection from the elements of one or more collections. A `for` expression is built up of [generators](#generator), [filters](#filter), variable definitions, and (in the case of [for comprehensions](#for-comprehension)) a [yield](#yield) clause. -* #### for loop +* ### for loop A _for loop_ is a type of [for expression](#for-expression) that loops over one or more collections. Since `for` loops return unit, they usually produce side-effects. For example, `for (i <- 0 until 100) println(i)` prints the numbers 0 through 99. -* #### free variable +* ### free variable A _free variable_ of an expression is a variable that’s used inside the expression but not defined inside the expression. For instance, in the function literal expression `(x: Int) => (x, y)`, both variables `x` and `y` are used, but only `y` is a free variable, because it is not defined inside the expression. -* #### function +* ### function A _function_ can be [invoked](#invoke) with a list of arguments to produce a result. A function has a parameter list, a body, and a result type. Functions that are members of a class, trait, or singleton object are called [methods](#method). Functions defined inside other functions are called [local functions](#local-function). Functions with the result type of `Unit` are called [procedures](#procedure). Anonymous functions in source code are called [function literals](#function-literal). At run time, function literals are instantiated into objects called [function values](#function-value). -* #### function literal -A function with no name in Scala source code, specified with function literal syntax. For example, `(x: Int, y: Int) => x + y`. +* ### function literal +A function with no name in Scala source code, specified with _function literal_ syntax. For example, `(x: Int, y: Int) => x + y`. -* #### function value -A function object that can be invoked just like any other function. A function value’s class extends one of the `FunctionN` traits (e.g., `Function0`, `Function1`) from package `scala`, and is usually expressed in source code via [function literal](#function-literal) syntax. A function value is “invoked” when its apply method is called. A function value that captures free variables is a [closure](#closure). +* ### function value +A function object that can be invoked just like any other function. A _function value_’s class extends one of the `FunctionN` traits (e.g., `Function0`, `Function1`) from package `scala`, and is usually expressed in source code via [function literal](#function-literal) syntax. A function value is “invoked” when its apply method is called. A function value that captures free variables is a [closure](#closure). -* #### functional style +* ### functional style The _functional style_ of programming emphasizes functions and evaluation results and deemphasizes the order in which operations occur. The style is characterized by passing function values into looping methods, immutable data, methods with no side effects. It is the dominant paradigm of languages such as Haskell and Erlang, and contrasts with the [imperative style](#imperative-style). -* #### generator -A generator defines a named val and assigns to it a series of values in a [for expression](#for-expression). For example, in `for(i <- 1 to 10)`, the generator is “`i <- 1 to 10`”. The value to the right of the `<-` is the [generator expression](#generator-expression). +* ### generator +A _generator_ defines a named val and assigns to it a series of values in a [for expression](#for-expression). For example, in `for(i <- 1 to 10)`, the generator is “`i <- 1 to 10`”. The value to the right of the `<-` is the [generator expression](#generator-expression). -* #### generator expression -A generator expression generates a series of values in a [for expression](#for-expression). For example, in `for(i <- 1 to 10)`, the generator expression is “`1 to 10`”. +* ### generator expression +A _generator expression_ generates a series of values in a [for expression](#for-expression). For example, in `for(i <- 1 to 10)`, the generator expression is “`1 to 10`”. -* #### generic class -A class that takes type parameters. For example, because `scala.List` takes a type parameter, `scala.List` is a generic class. +* ### generic class +A class that takes type parameters. For example, because `scala.List` takes a type parameter, `scala.List` is a _generic class_. -* #### generic trait -A trait that takes type parameters. For example, because trait `scala.collection.Set` takes a type parameter, it is a generic trait. +* ### generic trait +A trait that takes type parameters. For example, because trait `scala.collection.Set` takes a type parameter, it is a _generic trait_. -* #### guard +* ### guard See [filter](#filter). -* #### helper function +* ### helper function A function whose purpose is to provide a service to one or more other functions nearby. Helper functions are often implemented as local functions. -* #### helper method +* ### helper method A [helper function](#helper-function) that’s a member of a class. Helper methods are often private. -* #### immutable +* ### immutable An object is _immutable_ if its value cannot be changed after it is created in any way visible to clients. Objects may or may not be immutable. -* #### imperative style +* ### imperative style The _imperative style_ of programming emphasizes careful sequencing of operations so that their effects happen in the right order. The style is characterized by iteration with loops, mutating data in place, and methods with side effects. It is the dominant paradigm of languages such as C, C++, C# and Java, and contrasts with the [functional style](#functional-style). -* #### initialize -When a variable is defined in Scala source code, you must initialize it with an object. +* ### initialize +When a variable is defined in Scala source code, you must _initialize_ it with an object. -* #### instance +* ### instance An _instance_, or class instance, is an object, a concept that exists only at run time. -* #### instantiate +* ### instantiate To _instantiate_ a class is to make a new object from the class, an action that happens only at run time. -* #### invariant +* ### invariant _Invariant_ is used in two ways. It can mean a property that always holds true when a data structure is well-formed. For example, it is an invariant of a sorted binary tree that each node is ordered before its right subnode, if it has a right subnode. Invariant is also sometimes used as a synonym for nonvariant: “class `Array` is invariant in its type parameter.” -* #### invoke +* ### invoke You can _invoke_ a method, function, or closure _on_ arguments, meaning its body will be executed with the specified arguments. -* #### JVM +* ### JVM The _JVM_ is the Java Virtual Machine, or [runtime](#runtime), that hosts a running Scala program. -* #### literal +* ### literal `1`, `"One"`, and `(x: Int) => x + 1` are examples of _literals_. A literal is a shorthand way to describe an object, where the shorthand exactly mirrors the structure of the created object. -* #### local function +* ### local function A _local function_ is a `def` defined inside a block. To contrast, a `def` defined as a member of a class, trait, or singleton object is called a [method](#method). -* #### local variable +* ### local variable A _local variable_ is a `val` or `var` defined inside a block. Although similar to [local variables](#local-variable), parameters to functions are not referred to as local variables, but simply as parameters or “variables” without the “local.” -* #### member +* ### member A _member_ is any named element of the template of a class, trait, or singleton object. A member may be accessed with the name of its owner, a dot, and its simple name. For example, top-level fields and methods defined in a class are members of that class. A trait defined inside a class is a member of its enclosing class. A type defined with the type keyword in a class is a member of that class. A class is a member of the package in which is it defined. By contrast, a local variable or local function is not a member of its surrounding block. -* #### message +* ### message Actors communicate with each other by sending each other _messages_. Sending a message does not interrupt what the receiver is doing. The receiver can wait until it has finished its current activity and its invariants have been reestablished. -* #### meta-programming +* ### meta-programming Meta-programming software is software whose input is itself software. Compilers are meta-programs, as are tools like `scaladoc`. Meta-programming software is required in order to do anything with an annotation. -* #### method +* ### method A _method_ is a function that is a member of some class, trait, or singleton object. -* #### mixin -_Mixin_ is what a trait is called when it is being used in a mixin composition. In other words, in “`trait Hat`,” `Hat` is just a trait, but in “`new Cat extends AnyRef with Hat`,” `Hat` can be called a mixin. When used as a verb, “mix in” is two words. For example, you can _mix_ traits _in_to classes or other traits. +* ### mixin +_Mixin_ is what a trait is called when it is being used in a mixin composition. In other words, in “`trait Hat`,” `Hat` is just a trait, but in “`new Cat extends AnyRef with Hat`,” `Hat` can be called a mixin. When used as a verb, “mix in” is two words. For example, you can _mix_ traits _in_ to classes or other traits. -* #### mixin composition +* ### mixin composition The process of mixing traits into classes or other traits. _Mixin composition_ differs from traditional multiple inheritance in that the type of the super reference is not known at the point the trait is defined, but rather is determined anew each time the trait is mixed into a class or other trait. -* #### modifier +* ### modifier A keyword that qualifies a class, trait, field, or method definition in some way. For example, the `private` modifier indicates that a class, trait, field, or method being defined is private. -* #### multiple definitions +* ### multiple definitions The same expression can be assigned in _multiple definitions_ if you use the syntax `val v1, v2, v3 = exp`. -* #### nonvariant +* ### nonvariant A type parameter of a class or trait is by default _nonvariant_. The class or trait then does not subtype when that parameter changes. For example, because class `Array` is nonvariant in its type parameter, `Array[String]` is neither a subtype nor a supertype of `Array[Any]`. -* #### operation +* ### operation In Scala, every _operation_ is a method call. Methods may be invoked in _operator notation_, such as `b + 2`, and when in that notation, `+` is an _operator_. -* #### parameter +* ### parameter Functions may take zero to many _parameters_. Each parameter has a name and a type. The distinction between parameters and arguments is that arguments refer to the actual objects passed when a function is invoked. Parameters are the variables that refer to those passed arguments. -* #### parameterless function -A function that takes no parameters, which is de- fined without any empty parentheses. Invocations of parameterless functions may not supply parentheses. This supports the [uniform access principle](#uniform-access-principle), which enables the `def` to be changed into a `val` without requiring a change to client code. +* ### parameterless function +A function that takes no parameters, which is defined without any empty parentheses. Invocations of parameterless functions may not supply parentheses. This supports the [uniform access principle](#uniform-access-principle), which enables the `def` to be changed into a `val` without requiring a change to client code. -* #### parameterless method +* ### parameterless method A _parameterless method_ is a parameterless function that is a member of a class, trait, or singleton object. -* #### parametric field +* ### parametric field A field defined as a class parameter. -* #### partially applied function +* ### partially applied function A function that’s used in an expression and that misses some of its arguments. For instance, if function `f` has type `Int => Int => Int`, then `f` and `f(1)` are _partially applied functions_. -* #### path-dependent type +* ### path-dependent type A type like `swiss.cow.Food`. The `swiss.cow` part is a path that forms a reference to an object. The meaning of the type is sensitive to the path you use to access it. The types `swiss.cow.Food` and `fish.Food`, for example, are different types. -* #### pattern +* ### pattern In a `match` expression alternative, a _pattern_ follows each `case` keyword and precedes either a _pattern guard_ or the `=>` symbol. -* #### pattern guard +* ### pattern guard In a `match` expression alternative, a _pattern guard_ can follow a [pattern](#pattern). For example, in “`case x if x % 2 == 0 => x + 1`”, the pattern guard is “`if x % 2 == 0`”. A case with a pattern guard will only be selected if the pattern matches and the pattern guard yields true. -* #### predicate +* ### predicate A _predicate_ is a function with a `Boolean` result type. -* #### primary constructor +* ### primary constructor The main constructor of a class, which invokes a superclass constructor, if necessary, initializes fields to passed values, and executes any top-level code defined between the curly braces of the class. Fields are initialized only for value parameters not passed to the superclass constructor, except for any that are not used in the body of the class and can therefore be optimized away. -* #### procedure +* ### procedure A _procedure_ is a function with result type of `Unit`, which is therefore executed solely for its side effects. -* #### reassignable +* ### reassignable A variable may or may not be _reassignable_. A `var` is reassignable while a `val` is not. -* #### recursive +* ### recursive A function is _recursive_ if it calls itself. If the only place the function calls itself is the last expression of the function, then the function is [tail recursive](#tail-recursive). -* #### reference +* ### reference A _reference_ is the Java abstraction of a pointer, which uniquely identifies an object that resides on the JVM’s heap. Reference type variables hold references to objects, because reference types (instances of `AnyRef`) are implemented as Java objects that reside on the JVM’s heap. Value type variables, by contrast, may sometimes hold a reference (to a boxed wrapper type) and sometimes not (when the object is being represented as a primitive value). Speaking generally, a Scala variable [refers](#refers) to an object. The term “refers” is more abstract than “holds a reference.” If a variable of type `scala.Int` is currently represented as a primitive Java `int` value, then that variable still refers to the `Int` object, but no reference is involved. -* #### reference equality +* ### reference equality _Reference equality_ means that two references identify the very same Java object. Reference equality can be determined, for reference types only, by calling `eq` in `AnyRef`. (In Java programs, reference equality can be determined using `==` on Java [reference types](#reference-type).) -* #### reference type +* ### reference type A _reference type_ is a subclass of `AnyRef`. Instances of reference types always reside on the JVM’s heap at run time. -* #### referential transparency +* ### referential transparency A property of functions that are independent of temporal context and have no side effects. For a particular input, an invocation of a referentially transparent function can be replaced by its result without changing the program semantics. -* #### refers +* ### refers A variable in a running Scala program always _refers_ to some object. Even if that variable is assigned to `null`, it conceptually refers to the `Null` object. At runtime, an object may be implemented by a Java object or a value of a primitive type, but Scala allows programmers to think at a higher level of abstraction about their code as they imagine it running. See also [reference](#reference). -* #### refinement type -A type formed by supplying a base type a number of members inside curly braces. The members in the curly braces refine the types that are present in the base type. For example, the type of “animal that eats grass” is `Animal { type SuitableFood = Grass }`. +* ### refinement type +A type formed by supplying a base type with a number of members inside curly braces. The members in the curly braces refine the types that are present in the base type. For example, the type of “animal that eats grass” is `Animal { type SuitableFood = Grass }`. -* #### result +* ### result An expression in a Scala program yields a _result_. The result of every expression in Scala is an object. -* #### result type +* ### result type A method’s _result type_ is the type of the value that results from calling the method. (In Java, this concept is called the return type.) -* #### return -A function in a Scala program `returns` a value. You can call this value the [result](#result) of the function. You can also say the function _results in_ the value. The result of every function in Scala is an object. +* ### return +A function in a Scala program _returns_ a value. You can call this value the [result](#result) of the function. You can also say the function _results in_ the value. The result of every function in Scala is an object. -* #### runtime +* ### runtime The Java Virtual Machine, or [JVM](#jvm), that hosts a running Scala program. Runtime encompasses both the virtual machine, as defined by the Java Virtual Machine Specification, and the runtime libraries of the Java API and the standard Scala API. The phrase at run time (with a space between run and time) means when the program is running, and contrasts with compile time. -* #### runtime type +* ### runtime type The type of an object at run time. To contrast, a [static type](#static-type) is the type of an expression at compile time. Most runtime types are simply bare classes with no type parameters. For example, the runtime type of `"Hi"` is `String`, and the runtime type of `(x: Int) => x + 1` is `Function1`. Runtime types can be tested with `isInstanceOf`. -* #### script +* ### script A file containing top level definitions and statements, which can be run directly with `scala` without explicitly compiling. A script must end in an expression, not a definition. -* #### selector +* ### selector The value being matched on in a `match` expression. For example, in “`s match { case _ => }`”, the selector is `s`. -* #### self type -A _self type_ of a trait is the assumed type of `this`, the receiver, to be used within the trait. Any concrete class that mixes in the trait must ensure that its type conforms to the trait’s self type. The most common use of self types is for dividing a large class into several traits (as described in Chapter 29 of [Programming in Scala](http://www.artima.com/shop/programming_in_scala). +* ### self type +A _self type_ of a trait is the assumed type of `this`, the receiver, to be used within the trait. Any concrete class that mixes in the trait must ensure that its type conforms to the trait’s self type. The most common use of self types is for dividing a large class into several traits (as described in Chapter 29 of [Programming in Scala](https://www.artima.com/shop/programming_in_scala)). -* #### semi-structured data +* ### semi-structured data XML data is semi-structured. It is more structured than a flat binary file or text file, but it does not have the full structure of a programming language’s data structures. -* #### serialization -You can _serialize_ an object into a byte stream which can then be saved to files or transmitted over the network. You can later _deserialize_ the byte stream, even on different computer, and obtain an object that is the same as the original serialized object. +* ### serialization +You can _serialize_ an object into a byte stream which can then be saved to a file or transmitted over the network. You can later _deserialize_ the byte stream, even on different computer, and obtain an object that is the same as the original serialized object. -* #### shadow +* ### shadow A new declaration of a local variable _shadows_ one of the same name in an enclosing scope. -* #### signature +* ### signature _Signature_ is short for [type signature](#type-signature). -* #### singleton object +* ### singleton object An object defined with the object keyword. Each singleton object has one and only one instance. A singleton object that shares its name with a class, and is defined in the same source file as that class, is that class’s [companion object](#companion-object). The class is its [companion class](#companion-class). A singleton object that doesn’t have a companion class is a [standalone object](#standalone-object). -* #### standalone object +* ### standalone object A [singleton object](#singleton-object) that has no [companion class](#companion-class). -* #### statement +* ### statement An expression, definition, or import, _i.e._, things that can go into a template or a block in Scala source code. -* #### static type +* ### static type See [type](#type). -* #### structural type +* ### structural type A [refinement type](#refinement-type) where the refinements are for members not in the base type. For example, `{ def close(): Unit }` is a structural type, because the base type is `AnyRef`, and `AnyRef` does not have a member named `close`. -* #### subclass +* ### subclass A class is a _subclass_ of all of its [superclasses](#superclass) and [supertraits](#supertrait). -* #### subtrait +* ### subtrait A trait is a _subtrait_ of all of its [supertraits](#supertrait). -* #### subtype +* ### subtype The Scala compiler will allow any of a type’s _subtypes_ to be used as a substitute wherever that type is required. For classes and traits that take no type parameters, the subtype relationship mirrors the subclass relationship. For example, if class `Cat` is a subclass of abstract class `Animal`, and neither takes type parameters, type `Cat` is a subtype of type `Animal`. Likewise, if trait `Apple` is a subtrait of trait `Fruit`, and neither takes type parameters, type `Apple` is a subtype of type `Fruit`. For classes and traits that take type parameters, however, variance comes into play. For example, because abstract class `List` is declared to be covariant in its lone type parameter (i.e., `List` is declared `List[+A]`), `List[Cat]` is a subtype of `List[Animal]`, and `List[Apple]` a subtype of `List[Fruit]`. These subtype relationships exist even though the class of each of these types is `List`. By contrast, because `Set` is not declared to be covariant in its type parameter (i.e., `Set` is declared `Set[A]` with no plus sign), `Set[Cat]` is not a subtype of `Set[Animal]`. A subtype should correctly implement the contracts of its supertypes, so that the Liskov Substitution Principle applies, but the compiler only verifies this property at the level of type checking. -* #### superclass +* ### superclass A class’s _superclasses_ include its direct superclass, its direct superclass’s direct superclass, and so on, all the way up to `Any`. -* #### supertrait +* ### supertrait A class’s or trait’s _supertraits_, if any, include all traits directly mixed into the class or trait or any of its superclasses, plus any supertraits of those traits. -* #### supertype +* ### supertype A type is a _supertype_ of all of its subtypes. -* #### synthetic class +* ### synthetic class A synthetic class is generated automatically by the compiler rather than being written by hand by the programmer. -* #### tail recursive +* ### tail recursive A function is _tail recursive_ if the only place the function calls itself is the last operation of the function. -* #### target typing +* ### target typing _Target typing_ is a form of type inference that takes into account the type that’s expected. In `nums.filter((x) => x > 0)`, for example, the Scala compiler infers type of `x` to be the element type of `nums`, because the `filter` method invokes the function on each element of `nums`. -* #### template +* ### template A _template_ is the body of a class, trait, or singleton object definition. It defines the type signature, behavior and initial state of the class, trait, or object. -* #### trait +* ### trait A _trait_, which is defined with the `trait` keyword, is like an abstract class that cannot take any value parameters and can be “mixed into” classes or other traits via the process known as [mixin composition](#mixin-composition). When a trait is being mixed into a class or trait, it is called a [mixin](#mixin). A trait may be parameterized with one or more types. When parameterized with types, the trait constructs a type. For example, `Set` is a trait that takes a single type parameter, whereas `Set[Int]` is a type. Also, `Set` is said to be “the trait of” type `Set[Int]`. -* #### type +* ### type Every variable and expression in a Scala program has a _type_ that is known at compile time. A type restricts the possible values to which a variable can refer, or an expression can produce, at run time. A variable or expression’s type can also be referred to as a _static type_ if necessary to differentiate it from an object’s [runtime type](#runtime-type). In other words, “type” by itself means static type. Type is distinct from class because a class that takes type parameters can construct many types. For example, `List` is a class, but not a type. `List[T]` is a type with a free type parameter. `List[Int]` and `List[String]` are also types (called ground types because they have no free type parameters). A type can have a “[class](#class)” or “[trait](#trait).” For example, the class of type `List[Int]` is `List`. The trait of type `Set[String]` is `Set`. -* #### type constraint +* ### type constraint Some [annotations](#annotation) are _type constraints_, meaning that they add additional limits, or constraints, on what values the type includes. For example, `@positive` could be a type constraint on the type `Int`, limiting the type of 32-bit integers down to those that are positive. Type constraints are not checked by the standard Scala compiler, but must instead be checked by an extra tool or by a compiler plugin. -* #### type constructor +* ### type constructor A class or trait that takes type parameters. -* #### type parameter +* ### type parameter A parameter to a generic class or generic method that must be filled in by a type. For example, class `List` is defined as “`class List[T] { . . . `”, and method `identity`, a member of object `Predef`, is defined as “`def identity[T](x:T) = x`”. The `T` in both cases is a type parameter. -* #### type signature +* ### type signature A method’s _type signature_ comprises its name, the number, order, and types of its parameters, if any, and its result type. The type signature of a class, trait, or singleton object comprises its name, the type signatures of all of its members and constructors, and its declared inheritance and mixin relations. -* #### uniform access principle +* ### uniform access principle The _uniform access principle_ states that variables and parameterless functions should be accessed using the same syntax. Scala supports this principle by not allowing parentheses to be placed at call sites of parameterless functions. As a result, a parameterless function definition can be changed to a `val`, or _vice versa_, without affecting client code. -* #### unreachable -At the Scala level, objects can become _unreachable_, at which point the memory they occupy may be reclaimed by the runtime. Unreachable does not necessarily mean unreferenced. Reference types (instances of `AnyRef`) are implemented as objects that reside on the JVM’s heap. When an instance of a reference type becomes unreachable, it indeed becomes unreferenced, and is available for garbage collection. Value types (instances of `AnyVal`) are implemented as both primitive type values and as instances of Java wrapper types (such as `java.lang.Integer`), which reside on the heap. Value type instances can be boxed (converted from a primitive value to a wrapper object) and unboxed (converted from a wrapper object to a primitive value) throughout the lifetime of the variables that refer to them. If a value type instance currently represented as a wrapper object on the JVM’s heap becomes unreachable, it indeed becomes unreferenced, and is available for garbage collection. But if a value type currently represented as a primitive value becomes unreachable, then it does not become unreferenced, because it does not exist as an object on the JVM’s heap at that point in time. The runtime may reclaim memory occupied by unreachable objects, but if an Int, for example, is implemented at run time by a primitive Java int that occupies some memory in the stack frame of an executing method, then the memory for that object is “reclaimed” when the stack frame is popped as the method completes. Memory for reference types, such as `Strings`, may be reclaimed by the JVM’s garbage collector after they become unreachable. +* ### unreachable +At the Scala level, objects can become _unreachable_, at which point the memory they occupy may be reclaimed by the runtime. Unreachable does not necessarily mean unreferenced. Reference types (instances of `AnyRef`) are implemented as objects that reside on the JVM’s heap. When an instance of a reference type becomes unreachable, it indeed becomes unreferenced, and is available for garbage collection. Value types (instances of `AnyVal`) are implemented as both primitive type values and as instances of Java wrapper types (such as `java.lang.Integer`), which reside on the heap. Value type instances can be boxed (converted from a primitive value to a wrapper object) and unboxed (converted from a wrapper object to a primitive value) throughout the lifetime of the variables that refer to them. If a value type instance currently represented as a wrapper object on the JVM’s heap becomes unreachable, it indeed becomes unreferenced, and is available for garbage collection. But if a value type currently represented as a primitive value becomes unreachable, then it does not become unreferenced, because it does not exist as an object on the JVM’s heap at that point of time. The runtime may reclaim memory occupied by unreachable objects, but if an Int, for example, is implemented at run time by a primitive Java int that occupies some memory in the stack frame of an executing method, then the memory for that object is “reclaimed” when the stack frame is popped as the method completes. Memory for reference types, such as `Strings`, may be reclaimed by the JVM’s garbage collector after they become unreachable. -* #### unreferenced +* ### unreferenced See [unreachable](#unreachable). -* #### value +* ### value The result of any computation or expression in Scala is a _value_, and in Scala, every value is an object. The term value essentially means the image of an object in memory (on the JVM’s heap or stack). -* #### value type -A _value type_ is any subclass of `AnyVal`, such as `Int`, `Double`, or `Unit`. This term has meaning at the level of Scala source code. At runtime, instances of value types that correspond to Java primitive types may be implemented in terms of primitive type values or instances of wrapper types, such as `java.lang.Integer`. Over the lifetime of a value type instance, the runtime may transform it back and forth be- tween primitive and wrapper types (_i.e._, to box and unbox it). +* ### value type +A _value type_ is any subclass of `AnyVal`, such as `Int`, `Double`, or `Unit`. This term has meaning at the level of Scala source code. At runtime, instances of value types that correspond to Java primitive types may be implemented in terms of primitive type values or instances of wrapper types, such as `java.lang.Integer`. Over the lifetime of a value type instance, the runtime may transform it back and forth between primitive and wrapper types (_i.e._, to box and unbox it). -* #### variable +* ### variable A named entity that refers to an object. A variable is either a `val` or a `var`. Both `val`s and `var`s must be initialized when defined, but only `var`s can be later reassigned to refer to a different object. -* #### variance +* ### variance A type parameter of a class or trait can be marked with a _variance_ annotation, either [covariant](#covariant) (+) or [contravariant](#contravariant) (-). Such variance annotations indicate how subtyping works for a generic class or trait. For example, the generic class `List` is covariant in its type parameter, and thus `List[String]` is a subtype of `List[Any]`. By default, _i.e._, absent a `+` or `-` annotation, type parameters are [nonvariant](#nonvariant). -* #### yield +* ### yield An expression can _yield_ a result. The `yield` keyword designates the result of a [for comprehension](#for-comprehension). diff --git a/_includes/_markdown/_ru/install-cask.md b/_includes/_markdown/_ru/install-cask.md new file mode 100644 index 0000000000..1cac104c20 --- /dev/null +++ b/_includes/_markdown/_ru/install-cask.md @@ -0,0 +1,45 @@ +{% altDetails require-info-box 'Установка Cask' %} + +{% tabs cask-install class=tabs-build-tool %} + +{% tab 'Scala CLI' %} + +Вы можете объявить зависимость от Cask с помощью следующей директивы `using`: + +```scala +//> using dep com.lihaoyi::cask::0.10.2 +``` + +{% endtab %} + +{% tab 'sbt' %} + +В файле `build.sbt` вы можете добавить зависимость от Cask: + +```scala +lazy val example = project.in(file("example")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "com.lihaoyi" %% "cask" % "0.10.2", + fork := true + ) +``` + +{% endtab %} + +{% tab 'Mill' %} + +В файле `build.sc` вы можете добавить зависимость от Cask: + +```scala +object example extends RootModule with ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = Agg( + ivy"com.lihaoyi::cask::0.10.2" + ) +} +``` +{% endtab %} + +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/_markdown/_ru/install-munit.md b/_includes/_markdown/_ru/install-munit.md new file mode 100644 index 0000000000..aa15142558 --- /dev/null +++ b/_includes/_markdown/_ru/install-munit.md @@ -0,0 +1,68 @@ +{% altDetails install-info-box 'Установка MUnit' %} + +{% tabs munit-unit-test-1 class=tabs-build-tool %} +{% tab 'Scala CLI' %} + +Вы можете запросить весь набор инструментов одной командой: + +```scala +//> using toolkit latest +``` + +MUnit, будучи тестовым фреймворком, доступен только в тестовых файлах: +файлах в каталоге `test` или тех, которые имеют расширение `.test.scala`. +Подробнее о тестовой области (test scope) см. [в документации Scala CLI](https://scala-cli.virtuslab.org/docs/commands/test/). + +В качестве альтернативы вы можете запросить только определенную версию MUnit: + +```scala +//> using dep org.scalameta::munit:1.1.0 +``` + +{% endtab %} + +{% tab 'sbt' %} + +В файле `build.sbt` вы можете добавить зависимость от toolkit-test: + +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit-test" % "0.7.0" % Test + ) +``` + +Здесь конфигурация `Test` означает, что зависимость используется только исходными файлами в `src/test`. + +В качестве альтернативы вы можете запросить только определенную версию MUnit: + +```scala +libraryDependencies += "org.scalameta" %% "munit" % "1.1.0" % Test +``` +{% endtab %} + +{% tab 'Mill' %} + +В файле `build.sc` вы можете добавить объект `test`, расширяющий `Tests` и `TestModule.Munit`: + +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + object test extends Tests with TestModule.Munit { + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit-test:0.7.0" + ) + } +} +``` + +В качестве альтернативы вы можете запросить только определенную версию MUnit: + +```scala +ivy"org.scalameta::munit:1.1.0" +``` +{% endtab %} +{% endtabs %} +{% endaltDetails %} \ No newline at end of file diff --git a/_includes/_markdown/_ru/install-os-lib.md b/_includes/_markdown/_ru/install-os-lib.md new file mode 100644 index 0000000000..f010d1f7fd --- /dev/null +++ b/_includes/_markdown/_ru/install-os-lib.md @@ -0,0 +1,64 @@ +{% altDetails require-info-box 'Установка OS-Lib' %} + +{% tabs oslib-install class=tabs-build-tool %} + +{% tab 'Scala CLI' %} + +Вы можете запросить весь набор инструментов одной командой: + +```scala +//> using toolkit latest +``` + +В качестве альтернативы вы можете запросить только определенную версию OS-Lib: + +```scala +//> using dep com.lihaoyi::os-lib:0.11.3 +``` + +{% endtab %} + +{% tab 'sbt' %} + +В файле `build.sbt` вы можете добавить зависимость от `toolkit`: + +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0" + ) +``` + +В качестве альтернативы вы можете запросить только определенную версию OS-Lib: + +```scala +libraryDependencies += "com.lihaoyi" %% "os-lib" % "0.11.3" +``` + +{% endtab %} + +{% tab 'Mill' %} + +В файле `build.sc` вы можете добавить зависимость от `toolkit`: + +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit:0.7.0" + ) +} +``` + +В качестве альтернативы вы можете запросить только определенную версию OS-Lib: + +```scala +ivy"com.lihaoyi::os-lib:0.11.3" +``` + +{% endtab %} + +{% endtabs %} +{% endaltDetails %} \ No newline at end of file diff --git a/_includes/_markdown/_ru/install-sttp.md b/_includes/_markdown/_ru/install-sttp.md new file mode 100644 index 0000000000..fec7938cea --- /dev/null +++ b/_includes/_markdown/_ru/install-sttp.md @@ -0,0 +1,64 @@ + +{% altDetails install-info-box 'Установка sttp' %} + +{% tabs sttp-install-methods class=tabs-build-tool%} + +{% tab 'Scala CLI' %} + +Вы можете запросить весь набор инструментов одной командой: + +```scala +//> using toolkit latest +``` + +В качестве альтернативы вы можете запросить только определенную версию sttp: + +```scala +//> using dep com.softwaremill.sttp.client4::core:4.0.0-RC1 +``` + +{% endtab %} + +{% tab 'sbt' %} + +В файле `build.sbt` вы можете добавить зависимость от `toolkit`: + +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0" + ) +``` + +В качестве альтернативы вы можете запросить только определенную версию sttp: + +```scala +libraryDependencies += "com.softwaremill.sttp.client4" %% "core" % "4.0.0-RC1" +``` + +{% endtab %} + +{% tab 'Mill' %} + +В файле `build.sc` вы можете добавить зависимость от `toolkit`: + +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit:0.7.0" + ) +} +``` + +В качестве альтернативы вы можете запросить только определенную версию sttp: + +```scala +ivy"com.softwaremill.sttp.client4::core:4.0.0-RC1" +``` + +{% endtab %} +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/_markdown/_ru/install-upickle.md b/_includes/_markdown/_ru/install-upickle.md new file mode 100644 index 0000000000..83880a91a8 --- /dev/null +++ b/_includes/_markdown/_ru/install-upickle.md @@ -0,0 +1,64 @@ + +{% altDetails install-info-box 'Установка upickle' %} + +{% tabs upickle-install-methods class=tabs-build-tool %} + +{% tab 'Scala CLI' %} + +Вы можете запросить весь набор инструментов одной командой: + +```scala +//> using toolkit latest +``` + +В качестве альтернативы вы можете запросить только определенную версию UPickle: + +```scala +//> using dep com.lihaoyi::upickle:4.1.0 +``` + +{% endtab %} + +{% tab 'sbt' %} + +В файле `build.sbt` вы можете добавить зависимость от `toolkit`: + +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0" + ) +``` + +В качестве альтернативы вы можете запросить только определенную версию UPickle: + +```scala +libraryDependencies += "com.lihaoyi" %% "upickle" % "4.1.0" +``` + +{% endtab %} + +{% tab 'Mill' %} + +В файле `build.sc` вы можете добавить зависимость от `toolkit`: + +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit:0.7.0" + ) +} +``` + +В качестве альтернативы вы можете запросить только определенную версию UPickle: + +```scala +ivy"com.lihaoyi::upickle:4.1.0" +``` + +{% endtab %} +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/_markdown/courses-coursera.md b/_includes/_markdown/courses-coursera.md new file mode 100644 index 0000000000..403c5e3100 --- /dev/null +++ b/_includes/_markdown/courses-coursera.md @@ -0,0 +1,18 @@ +## Scala Courses on Coursera by EPFL + +The [Scala Center](https://scala.epfl.ch) at EPFL offers free online courses of various levels, from beginner to advanced. + +For beginners: + +- [Effective Programming in Scala](https://www.coursera.org/learn/effective-scala): a practical introduction to Scala for professional developers +- [Functional Programming Principles in Scala](https://www.coursera.org/learn/scala-functional-programming): the foundational course by Martin Odersky, Scala's creator + +More advanced topics: + +- [Functional Program Design in Scala](https://www.coursera.org/learn/scala-functional-program-design): builds on functional principles with more advanced concepts +- [Parallel Programming](https://www.coursera.org/learn/scala-parallel-programming) +- [Big Data Analysis with Scala and Spark](https://www.coursera.org/learn/scala-spark-big-data) +- [Programming Reactive Systems](https://www.coursera.org/learn/scala-akka-reactive): introduces Akka, actors and reactive streams + +All courses are free to audit, with an option to pay for a certificate, to showcase your skills on your resume or LinkedIn. +For more on Scala Center's online courses, visit [this page](https://docs.scala-lang.org/online-courses.html#learning-platforms). diff --git a/_includes/_markdown/courses-extension-school.md b/_includes/_markdown/courses-extension-school.md new file mode 100644 index 0000000000..003c42a4f2 --- /dev/null +++ b/_includes/_markdown/courses-extension-school.md @@ -0,0 +1,9 @@ +## EPFL Extension School: Effective Programming in Scala + +Subscribing to [Effective programming in Scala](https://www.epfl.ch/education/continuing-education/effective-programming-in-scala/) on the EPFL Extension School offers: + +- Regular Q&A sessions and code reviews with experts from the Scala team +- An [Extension School certificate](https://www.epfl.ch/education/continuing-education/certifications/) upon completion + +This course combines video lessons, written content and hands-on exercise focused on practical aspects, including business domain modeling, error handling, data manipulation, and task parallelization. +For more on Scala Center's online courses, visit [this page](https://docs.scala-lang.org/online-courses.html#learning-platforms). diff --git a/_includes/_markdown/courses-rock-the-jvm.md b/_includes/_markdown/courses-rock-the-jvm.md new file mode 100644 index 0000000000..0b0db4f9f1 --- /dev/null +++ b/_includes/_markdown/courses-rock-the-jvm.md @@ -0,0 +1,17 @@ +## Rock the JVM Courses + +_As part of a partnership with the Scala Center, Rock the JVM donates 30% of the revenue from any courses purchased through the links in this section to support the Scala Center._ + +[Rock the JVM](https://rockthejvm.com?affcode=256201_r93i1xuv) is a learning platform with free and premium courses on the Scala language, and all major libraries and tools in the Scala ecosystem: Typelevel, Zio, Akka/Pekko, Spark, and others. +Its main Scala courses are: + +- [Scala at Light Speed](https://rockthejvm.com/courses/scala-at-light-speed?affcode=256201_r93i1xuv) (free) +- [Scala & Functional Programming Essentials](https://rockthejvm.com/courses/scala-essentials?affcode=256201_r93i1xuv) (premium) +- [Advanced Scala and Functional Programming](https://rockthejvm.com/courses/advanced-scala?affcode=256201_r93i1xuv) (premium) +- [Scala Macros & Metaprogramming](https://rockthejvm.com/courses/scala-macros-and-metaprogramming?affcode=256201_r93i1xuv) (premium) + +Other courses teach how to build full-stack Scala applications, using [Typelevel](https://rockthejvm.com/courses/typelevel-rite-of-passage?affcode=256201_r93i1xuv) or [ZIO](https://rockthejvm.com/courses/zio-rite-of-passage?affcode=256201_r93i1xuv) ecosystems. + + + +Explore more premium [courses](https://rockthejvm.com/courses?affcode=256201_r93i1xuv) or check out [free video tutorials](https://youtube.com/rockthejvm?affcode=256201_r93i1xuv) and [free articles](https://rockthejvm.com/articles?affcode=256201_r93i1xuv). diff --git a/_includes/_markdown/install-cask.md b/_includes/_markdown/install-cask.md new file mode 100644 index 0000000000..3637ddfac9 --- /dev/null +++ b/_includes/_markdown/install-cask.md @@ -0,0 +1,37 @@ +{% altDetails require-info-box 'Getting Cask' %} + +{% tabs cask-install class=tabs-build-tool %} + +{% tab 'Scala CLI' %} +You can declare a dependency on Cask with the following `using` directive: +```scala +//> using dep com.lihaoyi::cask::0.10.2 +``` +{% endtab %} + +{% tab 'sbt' %} +In your `build.sbt`, you can add a dependency on Cask: +```scala +lazy val example = project.in(file("example")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "com.lihaoyi" %% "cask" % "0.10.2", + fork := true + ) +``` +{% endtab %} + +{% tab 'Mill' %} +In your `build.sc`, you can add a dependency on Cask: +```scala +object example extends RootModule with ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = Agg( + ivy"com.lihaoyi::cask::0.10.2" + ) +} +``` +{% endtab %} + +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/_markdown/install-munit.md b/_includes/_markdown/install-munit.md new file mode 100644 index 0000000000..47eeb1509f --- /dev/null +++ b/_includes/_markdown/install-munit.md @@ -0,0 +1,53 @@ +{% altDetails install-info-box 'Getting MUnit' %} + +{% tabs munit-unit-test-1 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +You can require the entire toolkit in a single line: +```scala +//> using toolkit latest +``` +MUnit, being a testing framework, is only available in test files: files in a `test` directory or ones that have the `.test.scala` extension. Refer to the [Scala CLI documentation](https://scala-cli.virtuslab.org/docs/commands/test/) to learn more about the test scope. + +Alternatively, you can require just a specific version of MUnit: +```scala +//> using dep org.scalameta::munit:1.1.0 +``` +{% endtab %} +{% tab 'sbt' %} +In your build.sbt file, you can add the dependency on toolkit-test: +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit-test" % "0.7.0" % Test + ) +``` + +Here the `Test` configuration means that the dependency is only used by the source files in `src/test`. + +Alternatively, you can require just a specific version of MUnit: +```scala +libraryDependencies += "org.scalameta" %% "munit" % "1.1.0" % Test +``` +{% endtab %} +{% tab 'Mill' %} +In your build.sc file, you can add a `test` object extending `Tests` and `TestModule.Munit`: +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + object test extends Tests with TestModule.Munit { + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit-test:0.7.0" + ) + } +} +``` + +Alternatively, you can require just a specific version of MUnit: +```scala +ivy"org.scalameta::munit:1.1.0" +``` +{% endtab %} +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/_markdown/install-os-lib.md b/_includes/_markdown/install-os-lib.md new file mode 100644 index 0000000000..ae254d9d71 --- /dev/null +++ b/_includes/_markdown/install-os-lib.md @@ -0,0 +1,46 @@ +{% altDetails require-info-box 'Getting OS-Lib' %} + +{% tabs oslib-install class=tabs-build-tool %} +{% tab 'Scala CLI' %} +You can require the entire toolkit in a single line: +```scala +//> using toolkit latest +``` + +Alternatively, you can require just a specific version of OS-Lib: +```scala +//> using dep com.lihaoyi::os-lib:0.11.3 +``` +{% endtab %} +{% tab 'sbt' %} +In your `build.sbt`, you can add a dependency on the toolkit: +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0" + ) +``` +Alternatively, you can require just a specific version of OS-Lib: +```scala +libraryDependencies += "com.lihaoyi" %% "os-lib" % "0.11.3" +``` +{% endtab %} +{% tab 'Mill' %} +In your `build.sc` file, you can add a dependency on the Toolkit: +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit:0.7.0" + ) +} +``` +Alternatively, you can require just a specific version of OS-Lib: +```scala +ivy"com.lihaoyi::os-lib:0.11.3" +``` +{% endtab %} +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/_markdown/install-sttp.md b/_includes/_markdown/install-sttp.md new file mode 100644 index 0000000000..0173ec47e1 --- /dev/null +++ b/_includes/_markdown/install-sttp.md @@ -0,0 +1,47 @@ +{% altDetails install-info-box 'Getting sttp' %} + +{% tabs sttp-install-methods class=tabs-build-tool%} +{% tab 'Scala CLI' %} +You can require the entire toolkit in a single line: +```scala +//> using toolkit latest +``` + +Alternatively, you can require just a specific version of sttp: +```scala +//> using dep com.softwaremill.sttp.client4::core:4.0.0-RC1 +``` +{% endtab %} +{% tab 'sbt' %} +In your build.sbt file, you can add a dependency on the Toolkit: +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0" + ) +``` + +Alternatively, you can require just a specific version of sttp: +```scala +libraryDependencies += "com.softwaremill.sttp.client4" %% "core" % "4.0.0-RC1" +``` +{% endtab %} +{% tab 'Mill' %} +In your build.sc file, you can add a dependency on the Toolkit: +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit:0.7.0" + ) +} +``` +Alternatively, you can require just a specific version of sttp: +```scala +ivy"com.softwaremill.sttp.client4::core:4.0.0-RC1" +``` +{% endtab %} +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/_markdown/install-upickle.md b/_includes/_markdown/install-upickle.md new file mode 100644 index 0000000000..9f9cff8a62 --- /dev/null +++ b/_includes/_markdown/install-upickle.md @@ -0,0 +1,46 @@ +{% altDetails install-info-box 'Getting upickle' %} + +{% tabs upickle-install-methods class=tabs-build-tool %} +{% tab 'Scala CLI' %} +Using Scala CLI, you can require the entire toolkit in a single line: +```scala +//> using toolkit latest +``` + +Alternatively, you can require just a specific version of UPickle: +```scala +//> using dep com.lihaoyi::upickle:4.1.0 +``` +{% endtab %} +{% tab 'sbt' %} +In your build.sbt file, you can add the dependency on the Toolkit: +```scala +lazy val example = project.in(file(".")) + .settings( + scalaVersion := "3.4.2", + libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0" + ) +``` +Alternatively, you can require just a specific version of UPickle: +```scala +libraryDependencies += "com.lihaoyi" %% "upickle" % "4.1.0" +``` +{% endtab %} +{% tab 'Mill' %} +In your build.sc file, you can add the dependency to the upickle library: +```scala +object example extends ScalaModule { + def scalaVersion = "3.4.2" + def ivyDeps = + Agg( + ivy"org.scala-lang::toolkit:0.7.0" + ) +} +``` +Alternatively, you can require just a specific version of UPickle: +```scala +ivy"com.lihaoyi::upickle:4.1.0" +``` +{% endtab %} +{% endtabs %} +{% endaltDetails %} diff --git a/_includes/alert-banner.html b/_includes/alert-banner.html new file mode 100644 index 0000000000..94c5ac1273 --- /dev/null +++ b/_includes/alert-banner.html @@ -0,0 +1,10 @@ +{% comment %}use the variable 'message' to include markdown text to display in the alert.{% endcomment %} + +{% unless include.message_id == 'disabled' %} + +{% endunless %} diff --git a/_includes/carousel.html b/_includes/carousel.html new file mode 100644 index 0000000000..0a9d6c00ff --- /dev/null +++ b/_includes/carousel.html @@ -0,0 +1,219 @@ +{% assign letterstring = "a,b,c,d,e,f,g,h,i,j,k,l,m,n" %} +{% assign letters = letterstring | split: ',' %} +{% assign number = include.number | minus: 1 %} +
+ +
+ + + + diff --git a/_includes/code-snippet.html b/_includes/code-snippet.html new file mode 100644 index 0000000000..3af87d0f97 --- /dev/null +++ b/_includes/code-snippet.html @@ -0,0 +1,8 @@ +
+ {% unless include.nocopy %} +
+ +
+ {% endunless %} + 
{{include.codeSnippet}}
+
diff --git a/_includes/column-list-of-items.html b/_includes/column-list-of-items.html deleted file mode 100644 index eb9e1600be..0000000000 --- a/_includes/column-list-of-items.html +++ /dev/null @@ -1,18 +0,0 @@ -{% comment %} - Layouts using this include should pass an include variable called 'collection' referencing a collection carrying the data (i.e.: contribute_community_tickets, contribute_resources...) -{% endcomment %} -
- {% for item in include.collection %} -
-
- - -

{{item.title}}

- -
-
- {{item.content}} -
-
- {% endfor %} -
\ No newline at end of file diff --git a/_includes/discourse.html b/_includes/discourse.html deleted file mode 100644 index 1a08884791..0000000000 --- a/_includes/discourse.html +++ /dev/null @@ -1,12 +0,0 @@ -
- - diff --git a/_includes/documentation-sections.html b/_includes/documentation-sections.html new file mode 100644 index 0000000000..cac3c2d21b --- /dev/null +++ b/_includes/documentation-sections.html @@ -0,0 +1,18 @@ +
+ {% for section in include.sections %} +
+

{{ section.title }}

+ {% for link in section.links %} + +
+ +
{{link.title}}
+
+
+

{{link.description}}

+
+ + {% endfor %} +
+ {% endfor %} +
diff --git a/_includes/footer.html b/_includes/footer.html index eb38dd0cfe..82d0ba252d 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -39,22 +39,24 @@ - - - + + + - - + + + + {% if page.layout == "sips"%} @@ -101,13 +103,16 @@ - diff --git a/_includes/glossary-header.html b/_includes/glossary-header.html index 61ad5b35e9..b51facaaa5 100644 --- a/_includes/glossary-header.html +++ b/_includes/glossary-header.html @@ -75,9 +75,9 @@ diff --git a/_includes/inner-documentation-sections.html b/_includes/inner-documentation-sections.html new file mode 100644 index 0000000000..944845c156 --- /dev/null +++ b/_includes/inner-documentation-sections.html @@ -0,0 +1,29 @@ +{% comment %} + Layouts using this include should pass an include variable called 'links' referencing a list carrying the data +{% endcomment %} + +
+ {% for link in include.links %} + + + {% assign first_char = link.link | slice: 0 %} + {% if first_char == '#' %} + {% assign is_url = false %} + {% else %} + {% assign is_url = true %} + {% endif %} + + +
+ +

{{link.title}}

+
+
+

{{link.description}}

+
+ + {% endfor %} +
diff --git a/_includes/inner-page-main-content.html b/_includes/inner-page-main-content.html deleted file mode 100644 index 78a954b5ae..0000000000 --- a/_includes/inner-page-main-content.html +++ /dev/null @@ -1,14 +0,0 @@ -
-
-
-
- {{content}} - - {% include contributors-list.html %} -
-
- - - {% include sidebar-toc.html %} -
-
diff --git a/_includes/markdown.html b/_includes/markdown.html new file mode 100644 index 0000000000..886b1560cd --- /dev/null +++ b/_includes/markdown.html @@ -0,0 +1 @@ +{% capture markdown %}{% include {{include.path}} %}{% endcapture %}{{ markdown | markdownify }} diff --git a/_includes/masthead-community.html b/_includes/masthead-community.html index 1d5f4912a7..9b76636212 100644 --- a/_includes/masthead-community.html +++ b/_includes/masthead-community.html @@ -17,15 +17,15 @@

{{forum.title}}

{% endfor %} -
-

Gitter

- Real-time (topic-specialized) chat +
+

Chat

+ Real-time chat on Discord
- \ No newline at end of file + diff --git a/_includes/masthead-documentation.html b/_includes/masthead-documentation.html index a15b70e81e..c9bcf75255 100644 --- a/_includes/masthead-documentation.html +++ b/_includes/masthead-documentation.html @@ -1,34 +1,35 @@
-
- {% for section in page.sections %} -
-

{{ section.title }}

- {% for link in section.links %} - -
- -
{{link.title}}
-
-
-

{{link.description}}

-
- - {% endfor %} -
-
  - {% if section.more-resources %} - More Resources: - - {% endif %} -
- {% endfor %} + +
+
+ Language +
    +
    + + + + {% include documentation-sections.html sections=page.sections %}
    diff --git a/_includes/navbar-inner.html b/_includes/navbar-inner.html index eb64eda00d..43de59b7e4 100644 --- a/_includes/navbar-inner.html +++ b/_includes/navbar-inner.html @@ -1,40 +1,36 @@ - +{% assign navdata = site.data.doc-nav-header %} + +{% include site-header.html %} + +{% if page.scala3 %} +
    +{% else %}
    +{% endif %}
    -
    Problem with this page?
         Please help us fix it!
    +
    Problem with this page?
         Please help us fix it!
    diff --git a/_includes/sidebar-toc-multipage-overview.html b/_includes/sidebar-toc-multipage-overview.html index f454abc5e6..4f9d7cb75c 100644 --- a/_includes/sidebar-toc-multipage-overview.html +++ b/_includes/sidebar-toc-multipage-overview.html @@ -1,41 +1,63 @@ +{% assign pagetype = page.type %}
    -
    -
    Contents
    -
    diff --git a/_includes/sidebar-toc-singlepage-overview.html b/_includes/sidebar-toc-singlepage-overview.html index f605a2ae13..cead129be1 100644 --- a/_includes/sidebar-toc-singlepage-overview.html +++ b/_includes/sidebar-toc-singlepage-overview.html @@ -3,19 +3,21 @@
    Contents
    -
    Problem with this page?
         Please help us fix it!
    +
    Problem with this page?
         Please help us fix it!
    diff --git a/_includes/sidebar-toc-style.html b/_includes/sidebar-toc-style.html index eec6ffb078..b82f7974e9 100644 --- a/_includes/sidebar-toc-style.html +++ b/_includes/sidebar-toc-style.html @@ -52,7 +52,7 @@
    Contents
    {% endif %}
    -
    Problem with this page?
         Please help us fix it!
    +
    Problem with this page?
         Please help us fix it!
    {% endif %} diff --git a/_includes/sidebar-toc-tour-overview.html b/_includes/sidebar-toc-tour-overview.html index ed5f756cb2..4150ede379 100644 --- a/_includes/sidebar-toc-tour-overview.html +++ b/_includes/sidebar-toc-tour-overview.html @@ -43,6 +43,6 @@
    Contents
    {% endif %}
    -
    Problem with this page?
         Please help us fix it!
    +
    Problem with this page?
         Please help us fix it!
    diff --git a/_includes/sidebar-toc.html b/_includes/sidebar-toc.html index eec6ffb078..b82f7974e9 100644 --- a/_includes/sidebar-toc.html +++ b/_includes/sidebar-toc.html @@ -52,7 +52,7 @@
    Contents
    {% endif %}
    -
    Problem with this page?
         Please help us fix it!
    +
    Problem with this page?
         Please help us fix it!
    {% endif %} diff --git a/_includes/site-header.html b/_includes/site-header.html new file mode 100644 index 0000000000..d2583b913f --- /dev/null +++ b/_includes/site-header.html @@ -0,0 +1,19 @@ + diff --git a/_includes/tutorial-list.html b/_includes/tutorial-list.html index da4ca58923..4ed3ee1943 100644 --- a/_includes/tutorial-list.html +++ b/_includes/tutorial-list.html @@ -2,6 +2,6 @@ {% for tutorial in site.data.tutorials limit: 6 %} {% assign loopindex = forloop.index | modulo: 2 %} {% if loopindex == include.column %} -
  • {{tutorial.title | truncate: 60}}
    • +
  • {{tutorial.title | truncate: 60}}
    • {% endif %} {% endfor %} \ No newline at end of file diff --git a/_includes/tutorial-toc.html b/_includes/tutorial-toc.html index 6d34a77d95..8f54cd0a74 100644 --- a/_includes/tutorial-toc.html +++ b/_includes/tutorial-toc.html @@ -24,6 +24,6 @@
    Contents
    {% include tutorial-tour-list.txt %}
    -
    Problem with this page?
         Please help us fix it!
    +
    Problem with this page?
         Please help us fix it!
    diff --git a/_includes/upcoming-training.html b/_includes/upcoming-training.html index 7b205eb794..1609682751 100644 --- a/_includes/upcoming-training.html +++ b/_includes/upcoming-training.html @@ -33,6 +33,6 @@

    {{training.title}}

    {% endfor %}
    -

    See more training or add one to our feed

    +

    See more training or add one to our feed

    - \ No newline at end of file + diff --git a/_includes/version-specific-notice.html b/_includes/version-specific-notice.html new file mode 100644 index 0000000000..4a92f84a6d --- /dev/null +++ b/_includes/version-specific-notice.html @@ -0,0 +1,31 @@ +{% if include.language %} +
    + + {% if include.language == 'scala3' %} + {% if include.page-language == 'ru' %} + Эта страница документа относится к Scala 3 и + может охватывать новые концепции, недоступные в Scala 2. + Если не указано явно, все примеры кода на этой странице + предполагают, что вы используете Scala 3. + {% else %} + This doc page is specific to Scala 3, + and may cover new concepts not available in Scala 2. Unless + otherwise stated, all the code examples in this page assume + you are using Scala 3. + {% endif %} + {% else if include.language == 'scala2' %} + {% if include.page-language == 'ru' %} + Эта страница документа относится к функциям, представленным в Scala 2, + которые либо были удалены в Scala 3, либо заменены альтернативными. + Если не указано явно, все примеры кода на этой странице предполагают, + что вы используете Scala 2. + {% else %} + This doc page is specific to features shipped in Scala 2, + which have either been removed in Scala 3 or replaced by an + alternative. Unless otherwise stated, all the code examples + in this page assume you are using Scala 2. + {% endif %} + {% endif %} + +
    +{% endif %} diff --git a/_it/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md b/_it/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md new file mode 100644 index 0000000000..0de0347ca5 --- /dev/null +++ b/_it/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md @@ -0,0 +1,79 @@ +--- +title: Primi passi su scala e sbt con la linea di comando +layout: singlepage-overview +partof: getting-started-with-scala-and-sbt-on-the-command-line +language: it +disqus: true +next-page: /it/testing-scala-with-sbt-on-the-command-line +--- + +In questo tutorial si vedrà come creare un progetto Scala a partire da un template, che può essere usato come punto di partenza anche per progettti personali. +Lo strumento utilizzato per tale scopo è [sbt](https://www.scala-sbt.org/1.x/docs/index.html), che è lo standard di build per Scala. +sbt permette di compilare, eseguire e testare i tuoi progetti, ma permette di svolgere anche altri compiti. +Si presuppone una conoscenza dell'uso della linea di comando. + +## Installazione +1. Assicurarsi di avere la Java 8 JDK (conosciuta anche come 1.8) installata + * Per verificarlo, eseguire `javac -version` da linea di comando e controllare che nell'output sia riportato + `javac 1.8.___` + * Se non si possiede la versione 1.8 o superiore, installarla seguendo [queste indicazioni](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) +1. Installare sbt + * [Mac](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html) + * [Windows](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html) + * [Linux](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html) + +## Creare il progetto +1. Eseguire il comando `cd` specificando una cartella vuota per spostarsi in essa. +1. Eseguire il comando `sbt new scala/hello-world.g8`. Questo effettuerà una pull del template 'hello-world' da GitHub. + Si occuperà inoltre di creare la cartella `target`, che per ora può essere ignorata. +1. Quando richiesto verrà richiesto il nome dell'applicazione, indicare `hello-world`. In questo modo verrà creato un progetto chiamato "hello-world". +1. Osserviamo cosa è stato generato una volta eseguiti i passaggi sopra riportati: + +``` +- hello-world + - project (sbt usa questa cartella per installare e gestire plugins e dipendenze) + - build.properties + - src + - main + - scala (Tutto il codice scala che viene scritto dovrà andare qui) + - Main.scala (Entry point dell'applicazione) <-- per ora è tutto ciò che ci servirà + - build.sbt (il file di definizione della build interpretato da sbt) +``` + +Una volta che verrà buildato il progetto, sbt creerà diverse cartelle `target` per i file generati. Possono essere ignorate per lo scopo di questo tutorial. + +## Eseguire il progetto +1. `cd` nella cartella `hello-world`. +1. Lanciare il comando `sbt`. Questo aprirà la console di sbt. +1. Eseguire `~run`. Il carattere `~` è opzionale. Indica ad sbt di eseguirsi ad ogni salvataggio di un file, permettendo un ciclo di modifica, esecuzione e debug più veloce. sbt genererà anche una cartella chiamata `target` che può essere ignorata. + +## Modificare il codice +1. Aprire il file `src/main/scala/Main.scala` in un qualsiasi editor di testo. +1. Modificare "Hello, World!" in "Hello, New York!" +1. Se non è stato interrotto il comando sbt, dovrebbe ora apparire "Hello, New York!" sulla console. +1. Si può continuare a modificare il file, e le modifiche dovrebbero apparire a schermo se non vengono riportati errori. + +## Aggiungere una dipendenza +Vediamo ora come utilizzare librerie pubblicate da terzi per aggiungere ulteriori funzionalità alle nostre applicazioni. + +1. Aprire il file `build.sbt` con un qualsiasi editor di testo e aggiungere la seguente riga: + +``` +libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2" +``` +`libraryDependencies` è un set (un tipo di collection in scala), e utilizzando il simbolo `+=`, +si sta aggiungendo la dipendenza [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) al set di dipendenze che sbt fetcherà quando verà inizializzato. +Una volta eseguito questo passaggio, sarà possibile importare classi, object ed altro da scala-parser-combinators tramite una semplice istruzione di import. + +Ulteriori librerie pubblicate possono essere trovate sul sito +[Scaladex](https://index.scala-lang.org/), dove è possibile copiare le informazioni delle dipendenze cercate nel file `build.sbt`. + +## Next steps + +Si consiglia di continuare al tutorial successivo della serie _getting started with sbt_ , ed imparare a [testare il codice Scala con sbt tramite linea di comando](testing-scala-with-sbt-on-the-command-line.html). + +**oppure** + +- Continuare ad imparare Scala online e in maniera interattiva su + [Scala Exercises](https://www.scala-exercises.org/scala_tutorial). +- Imparare le feature di Scala tramite articoli più concisi su [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html). \ No newline at end of file diff --git a/_it/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md b/_it/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md new file mode 100644 index 0000000000..cac6f0953a --- /dev/null +++ b/_it/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md @@ -0,0 +1,101 @@ +--- +title: Testare scala con sbt da linea di comando +layout: singlepage-overview +partof: testing-scala-with-sbt-on-the-command-line +language: it +disqus: true +previous-page: /it/getting-started-with-scala-and-sbt-on-the-command-line +--- + +Ci sono diverse librerie e modalità per testare il codice Scala, ma in questo tutorial verrà mostrato come eseguire il testing usando [AnyFunSuite](https://www.scalatest.org/scaladoc/3.2.2/org/scalatest/funsuite/AnyFunSuite.html) del framework ScalaTest. +Si assume che si sappia [creare un progetto Scala con sbt](getting-started-with-scala-and-sbt-on-the-command-line.html). + +## Setup +1. Da linea di comando, creare una nuova directory in una posizione a propria scelta. +1. `cd` nella cartella appena creata ed eseguire `sbt new scala/scalatest-example.g8` +1. Quando richiesto, rinominare il progetto come `ScalaTestTutorial`. +1. Il progetto avrà già in se la libreria ScalaTest come dipendenza indicata nel file `build.sbt`. +1. `cd` nel progetto ed eseguire `sbt test`. Questo eseguirà la test suite +`CubeCalculatorTest` con un unico test chiamato `CubeCalculator.cube`. + +``` +sbt test +[info] Loading global plugins from /Users/username/.sbt/0.13/plugins +[info] Loading project definition from /Users/username/workspace/sandbox/my-something-project/project +[info] Set current project to scalatest-example (in build file:/Users/username/workspace/sandbox/my-something-project/) +[info] CubeCalculatorTest: +[info] - CubeCalculator.cube +[info] Run completed in 267 milliseconds. +[info] Total number of tests run: 1 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0 +[info] All tests passed. +[success] Total time: 1 s, completed Feb 2, 2017 7:37:31 PM +``` + +## Comprendere i test +1. In qualsiasi editor di testo aprire i seguenti due file: + * `src/main/scala/CubeCalculator.scala` + * `src/test/scala/CubeCalculatorTest.scala` +1. Nel file `CubeCalculator.scala`, è riportata la definizione della funzione `cube`. +1. Nel file `CubeCalculatorTest.scala`, è presente una classe chiamata allo stesso modo dell'oggetto che stiamo testando. + +``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite { + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } + } +``` + +Analizziamo ogni riga di codice. + +* `class CubeCalculatorTest` significa che stiamo testando l'oggetto `CubeCalculator` +* `extends AnyFunSuite` ci permette di utilizzare la funzionalità della classe AnyFunSuite, come ad esempio la funzione `test` +* `test` è una funzione proveniente da AnyFunSuite che raccoglie i risultati delle asserzioni all'interno del corpo della funzione. +* `"CubeCalculator.cube"` è il nome del test. Può essere chiamato in qualsiasi modo, ma la convenzione è "NomeClasse.nomeMetodo". +* `assert` prende una condizione booleana e stabilisce se il test è superato o no. +* `CubeCalculator.cube(3) === 27` controlla se l'output della funzione `cube` sia realmente 27. +Il simbolo `===` è parte di ScalaTest e restituisce messaggi di errore comprensibili. + +## Aggiungere un altro test case +1. Aggiungere un altro blocco di testo contenente il proprio enunciato `assert` che verificherà il cubo di `0`. + + ``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite { + test("CubeCalculator.cube 3 should be 27") { + assert(CubeCalculator.cube(3) === 27) + } + + test("CubeCalculator.cube 0 should be 0") { + assert(CubeCalculator.cube(0) === 0) + } + } + ``` + +1. Lanciare `sbt test` nuovamente e controllare i risultati. + + ``` + sbt test + [info] Loading project definition from C:\projects\scalaPlayground\scalatestpractice\project + [info] Loading settings for project root from build.sbt ... + [info] Set current project to scalatest-example (in build file:/C:/projects/scalaPlayground/scalatestpractice/) + [info] Compiling 1 Scala source to C:\projects\scalaPlayground\scalatestpractice\target\scala-2.13\test-classes ... + [info] CubeCalculatorTest: + [info] - CubeCalculator.cube 3 should be 27 + [info] - CubeCalculator.cube 0 should be 0 + [info] Run completed in 257 milliseconds. + [info] Total number of tests run: 2 + [info] Suites: completed 1, aborted 0 + [info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 0 + [info] All tests passed. + [success] Total time: 3 s, completed Dec 4, 2019 10:34:04 PM + ``` + +## Conclusioni +In questo tutorial è stato mostrato una delle modalità per testare il codice Scala. Per saperne di più su FunSuite si può consultare [il sito ufficiale](https://www.scalatest.org/getting_started_with_fun_suite). +Si possono anche consultare altri framework di testing come [ScalaCheck](https://www.scalacheck.org/) e [Specs2](https://etorreborre.github.io/specs2/). diff --git a/_it/tutorials/scala-for-java-programmers.md b/_it/tutorials/scala-for-java-programmers.md index 35205679c9..180e5795bb 100644 --- a/_it/tutorials/scala-for-java-programmers.md +++ b/_it/tutorials/scala-for-java-programmers.md @@ -3,8 +3,6 @@ layout: singlepage-overview title: Un'introduzione a Scala per programmatori Java partof: scala-for-java-programmers - -discourse: false language: it --- @@ -28,7 +26,7 @@ Scala senza richiedere troppe conoscenze del linguaggio stesso. Ecco come appeare il codice: object HelloWorld { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { println("Hello, world!") } } @@ -75,7 +73,7 @@ avrà il nome `HelloWorld.class` e conterrà una classe che può essere direttamente eseguita con il comando `scala`, come mostra la seguente sezione. -### Eseguimo l'esempio +### Eseguiamo l'esempio Una volta compilato il programma può esser facilmente eseguito con il comando scala. L'uso è molto simile al comando java ed accetta le stesse @@ -93,13 +91,13 @@ codice Java. Tutte le classi del package `java.lang` sono importate di default mentre le altre richiedono l’esplicito import. Osserviamo un esempio che lo dimostra. Vogliamo ottenere la data -corrente e formattarla in accordo con la convezione usata in uno +corrente e formattarla in accordo con la convenzione usata in uno specifico paese del mondo, diciamo la Francia. (Altre regioni, come la parte di lingua francese della Svizzera, utilizzano le stesse convenzioni.) Le librerie delle classi Java definiscono potenti classi di utilità come `Date` e `DateFormat`. Poiché Scala interagisce direttamente con Java, non -esistono le classi equivalenti nella libreria delle classi di Scala--possiamo +esistono le classi equivalenti nella libreria delle classi di Scala; possiamo semplicemente importare le classi dei corrispondenti package Java: import java.util.{Date, Locale} @@ -107,14 +105,14 @@ semplicemente importare le classi dei corrispondenti package Java: import java.text.DateFormat._ object FrenchDate { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val now = new Date val df = getDateInstance(LONG, Locale.FRANCE) println(df format now) } } -L’istruzione import di Scala è molto simile all’equivalente in Java +L’istruzione `import` di Scala è molto simile all’equivalente in Java tuttavia, risulta essere più potente. Più classi possono essere importate dallo stesso package includendole in parentesi graffe come nella prima riga di codice precedentemente riportato. Un’altra differenza è evidente @@ -132,7 +130,7 @@ Java che di default contiene la data corrente. Successivamente, definiamo il formato della data usando il metodo statico `getDateInstance` importato precedentemente. Infine, stampiamo la data corrente, formattata secondo la localizzazione scelta, con l’istanza `DateFormat`; quest’ultima linea mostra -un’importante proprietà di Scala.I metodi che prendono un argomento possono +un’importante proprietà di Scala. I metodi che prendono un argomento (ed uno soltanto) possono essere usati con una sintassi non fissa. Questa forma dell’espressione df format now @@ -168,26 +166,11 @@ un’espressione aritmetica come la seguente: consiste esclusivamente di chiamate a metodi e risulta equivalente alla seguente espressione, come visto nella sezione precedente: - (1).+(((2).*(3))./(x)) + 1.+(2.*(3)./(x)) Questo significa anche che `+`, `*`, etc. sono identificatori validi in in Scala. -Le parentesi intorno ai numeri nella seconda versione sono necessarie -perché l’analizzatore lessicale di Scala usa le regole di match più -lunghe per i token quindi, dovrebbe dividere la seguente espressione: - - 1.+(2) - -nei token `1.`, `+`, and `2`. La ragione per cui si è scelto questo tipo -di assegnazione di significato è perché `1.` è un match più lungo e valido -di `1`. Il token `1.` è interpretato come `1.0` rendendolo un `Double` e -non più un `Int`. Scrivendo l’espressione come: - - (1).+(2) - -si evita che `1` sia interpretato come un `Double`. - ### Le funzioni sono oggetti Forse per i programmatori Java è più sorprendente scoprire che in Scala @@ -221,7 +204,7 @@ frase “time flies like an arrow” ogni secondo. def timeFlies() { println("time flies like an arrow...") } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(timeFlies) } } @@ -245,7 +228,7 @@ invece di *timeFlies* e appare come di seguito: def oncePerSecond(callback: () => Unit) { while (true) { callback(); Thread sleep 1000 } } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(() => println("time flies like an arrow...")) } @@ -279,7 +262,7 @@ modo: `new Complex(1.5, 2.3)`. La classe ha due metodi, `re` e `im` che danno l’accesso rispettivamente alla parte reale e a quella immaginaria del numero complesso. -Da notare che il tipo di ritorno dei due metodi non è specificato esplicitamante. +Da notare che il tipo di ritorno dei due metodi non è specificato esplicitamente. Sarà il compilatore che lo dedurrà automaticamente osservando la parte a destra del segno uguale dei metodi e deducendo che per entrambi si tratta di valori di tipo `Double`. @@ -300,7 +283,7 @@ necessario far seguire il nome del metodo da una coppia di parentesi tonde vuote, come mostrato nel codice seguente: object ComplexNumbers { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val c = new Complex(1.2, 3.4) println("imaginary part: " + c.im()) } @@ -436,7 +419,7 @@ detto in Scala non è difficile: } Questa funzione di valutazione lavora effettuando un *pattern matching* -sull’albero `t`. Intuitivamente il significato della definizione precendente +sull’albero `t`. Intuitivamente il significato della definizione precedente dovrebbe esser chiaro: 1. prima controlla se l’albero `t` è un `Sum`; se lo è, esegue il bind del @@ -516,7 +499,7 @@ sull’espressione `(x+x)+(7+y)`: prima calcola il suo valore nell’environment `{ x -> 5, y -> 7 }`, dopo calcola la derivata relativa ad `x` e poi ad `y`. - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) val env: Environment = { case "x" => 5 case "y" => 7 } println("Expression: " + exp) @@ -574,7 +557,7 @@ dichiarazione di un trait: } Questa definizione crea un nuovo tipo chiamato `Ord` che ha lo stesso -ruolo dell’interfaccia `Comparable` in Java e, fornisce l’implementazione +ruolo dell’interfaccia `Comparable` in Java e fornisce l’implementazione di default di tre predicati in termini del quarto astraendone uno. I predicati di uguaglianza e disuguaglianza non sono presenti in questa dichiarazione poichè sono presenti di default in tutti gli oggetti. @@ -595,11 +578,11 @@ definendo la classe `Date` come segue: def year = y def month = m def day = d - override def toString(): String = year + "-" + month + "-" + day + override def toString(): String = s"$year-$month-$day" La parte importante qui è la dichiarazione `extends Ord` che segue il nome della classe e dei parametri. Dichiara che la classe `Date` eredita il -codice dal trait `extends Ord`. +codice dal trait `Ord`. Successivamente ridefiniamo il metodo `equals`, ereditato da `Object`, in modo tale che possa confrontare in modo corretto le date confrontando @@ -663,7 +646,7 @@ restrittivo. I programmatori Java hanno fatto ricorso all’uso di `Object`, che è il super-tipo di tutti gli oggetti. Questa soluzione è in ogni caso ben lontana dall’esser ideale perché non funziona per i tipi base (`int`, `long`, `float`, -ecc.) ed implica che molto type casts dinamico deve esser fatto dal +ecc.) ed implica che molto type cast dinamico deve esser fatto dal programmatore. Scala rende possibile la definizione delle classi generiche (e metodi) per @@ -695,7 +678,7 @@ per creare ed usare una cella che contiene un intero si potrebbe scrivere il seguente codice: object IntegerReference { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val cell = new Reference[Int] cell.set(13) println("Reference contains the half of " + (cell.get * 2)) @@ -711,6 +694,6 @@ poiché è stata dichiarata per memorizzare un intero. Questo documento ha fornito una veloce introduzione del linguaggio Scala e presentato alcuni esempi di base. Il lettore interessato può continuare, per -esempio, leggendo il documento *Scala By Example* che contiene esempi molti più +esempio, leggendo il documento [*Tour of Scala*](https://docs.scala-lang.org/tour/tour-of-scala.html) che contiene esempi molti più avanzati e consultare al bisogno la documentazione *Scala Language Specification*. diff --git a/_ja/cheatsheets/index.md b/_ja/cheatsheets/index.md index b133ef48e4..ac3551736c 100644 --- a/_ja/cheatsheets/index.md +++ b/_ja/cheatsheets/index.md @@ -1,11 +1,11 @@ --- layout: cheatsheet -title: Scalacheat +title: Scala Cheatsheet partof: cheatsheet by: Kenji Ohtsuka -about: Thanks to Brendan O'Connor. このチートシートは Scala 構文 のクイックリファレンスとして作成されました。 Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. +about: Thanks to Brendan O'Connor. このチートシートは Scala 構文 のクイックリファレンスとして作成された。 Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. language: ja --- @@ -13,77 +13,610 @@ language: ja ###### Contributed by {{ page.by }} {{ page.about }} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    変数 
    var x = 5

    Good
    x = 6
    		変数
    val x = 5

    Bad
    x = 6
    		定数
    var x: Double = 5
    		明示的な型
    関数
    Good
    def f(x: Int) = { x * x }

    Bad
    def f(x: Int)   { x * x }
    		関数定義
    落とし穴: = を書かないと Unit を返す手続きになり、大惨事の原因になります。 Scala 2.13 より非推奨です。
    Good
    def f(x: Any) = println(x)

    Bad
    def f(x) = println(x)
    		関数定義
    シンタックスエラー: すべての引数に型指定が必要です。
    type R = Double
    		型エイリアス
    def f(x: R)
    vs.
    def f(x: => R)
    		値渡し

    名前渡し（遅延評価パラメータ）
    (x: R) => x * x
    		無名関数
    (1 to 5).map(_ * 2)
    vs.
    (1 to 5).reduceLeft(_ + _)
    		無名関数: アンダースコアは位置に応じて引数が代入されます。
    (1 to 5).map(x => x * x)
    		無名関数: 引数を2回使用する場合は名前をつけます。
    (1 to 5).map { x =>
+  val y = x * 2
+  println(y)
+  y
+}
    		無名関数: ブロックスタイルでは最後の式の結果が戻り値になります。
    (1 to 5) filter {
+  _ % 2 == 0
+} map {
+  _ * 2
+}
    		無名関数: パイプラインスタイル (括弧でも同様) 。
    def compose(g: R => R, h: R => R) =
+  (x: R) => g(h(x))

    val f = compose(_ * 2, _ - 1)
    		無名関数: 複数のブロックを渡す場合は外側の括弧が必要です。
    val zscore =
+  (mean: R, sd: R) =>
+    (x: R) =>
+      (x - mean) / sd
    		カリー化の明示的記法
    def zscore(mean: R, sd: R) =
+  (x: R) =>
+    (x - mean) / sd
    		カリー化の明示的記法
    def zscore(mean: R, sd: R)(x: R) =
+  (x - mean) / sd
    		カリー化の糖衣構文、ただしこの場合、
    val normer =
+  zscore(7, 0.4) _
    		部分関数を取得するには末尾にアンダースコアが必要です。
    def mapmake[T](g: T => T)(seq: List[T]) =
+  seq.map(g)
    		ジェネリック型
    5.+(3); 5 + 3

    (1 to 5) map (_ * 2)
    		中間記法
    def sum(args: Int*) =
+  args.reduceLeft(_+_)
    		可変長引数
    パッケージ 
    import scala.collection._
    		ワイルドカードでインポートします。
    import scala.collection.Vector

    import scala.collection.{Vector, Sequence}
    		個別にインポートします。
    import scala.collection.{Vector => Vec28}
    		別名でインポートします。
    import java.util.{Date => _, _}
    		Dateを除いてjava.utilのすべてをインポートします。
    ファイル先頭の: 
    package pkg

    スコープによるパッケージ: 
    package pkg {
+  ...
+}

    パッケージシングルトン: 
    package object pkg {
+  ...
+}
    		パッケージ宣言
    data structures 
    (1, 2, 3)
    		タイプリテラル (Tuple3)
    var (x, y, z) = (1, 2, 3)
    		構造化代入: パターンマッチによるタプルの展開。
    Bad
    var x, y, z = (1, 2, 3)
    		落とし穴: 各変数にタプル全体が代入されます。
    var xs = List(1, 2, 3)
    		リスト (イミュータブル)
    xs(2)
    		括弧を使って添字を書きます。(slides)
    1 :: List(2, 3)
    		先頭に要素を追加
    1 to 5
    上記と同じ 
    1 until 6

    1 to 10 by 2
    		Rangeの糖衣構文
    ()
    		中身のない括弧は、Unit 型 の唯一の値です。
    CやJavaで言うvoidにあたります。
    制御構文 
    if (check) happy else sad
    		条件分岐
    if (check) happy
    +
    上記と同様
    + 
    if (check) happy else ()
    		条件分岐の省略形
    while (x < 5) {
+  println(x)
+  x += 1
+}
    		while ループ
    do {
+  println(x)
+  x += 1
+} while (x < 5)
    		do while ループ
    import scala.util.control.Breaks._
 
-|  変数                                                             |                 |
-|  `var x = 5`                                                                                             |  変数           |
-|  Good `val x = 5`
     Bad `x=6`  |  定数           |
-|  `var x: Double = 5`                                                                                     |  明示的な型     |
-|  関数                                                             |                 |
-|  Good `def f(x: Int) = { x*x }`
     Bad `def f(x: Int)   { x*x }` |  関数定義
     落とし穴: = を書かないと Unit を返す手続きになり、大惨事の原因になります。 |
-|  Good `def f(x: Any) = println(x)`
     Bad `def f(x) = println(x)` |  関数定義 
     シンタックスエラー: すべての引数に型指定が必要です。 |
-|  `type R = Double`                                                                                       |  型エイリアス   |
-|  `def f(x: R)` vs.
     `def f(x: => R)`                                                                  |  値渡し 
     名前渡し (遅延評価パラメータ) |
-|  `(x:R) => x*x`                                                                                          |  無名関数                                                      |
-|  `(1 to 5).map(_*2)` vs.
     `(1 to 5).reduceLeft( _+_ )`                                                |  無名関数: アンダースコアは位置に応じて引数が代入されます。   |
-|  `(1 to 5).map( x => x*x )`                                                                              |  無名関数: 引数を2回使用する場合は名前をつけます。             |
-|  Good `(1 to 5).map(2*)`
     Bad `(1 to 5).map(*2)` |  無名関数: 片側が束縛された中置演算。 わかりづらいので `2*_` と書くことを推奨します。 |
-|  `(1 to 5).map { val x=_*2; println(x); x }`                                                             |  無名関数: ブロックスタイルでは最後の式の結果が戻り値になります。 |
-|  `(1 to 5) filter {_%2 == 0} map {_*2}`                                                                  |  無名関数: パイプラインスタイル (括弧でも同様) 。                 |
-|  `def compose(g:R=>R, h:R=>R) = (x:R) => g(h(x))` 
     `val f = compose({_*2}, {_-1})`                   |  無名関数: 複数のブロックを渡す場合は外側の括弧が必要です。 |
-|  `val zscore = (mean:R, sd:R) => (x:R) => (x-mean)/sd`                                                   |  カリー化の明示的記法       |
-|  `def zscore(mean:R, sd:R) = (x:R) => (x-mean)/sd`                                                       |  カリー化の明示的記法       |
-|  `def zscore(mean:R, sd:R)(x:R) = (x-mean)/sd`                                                           |  カリー化の糖衣構文、ただしこの場合、 |
-|  `val normer = zscore(7, 0.4)_`                                                                          |  部分関数を取得するには末尾にアンダースコアが必要です。 |
-|  `def mapmake[T](g:T=>T)(seq: List[T]) = seq.map(g)`                                                     |  ジェネリック型                     |
-|  `5.+(3); 5 + 3` 
     `(1 to 5) map (_*2)`                                                               |  中置記法                           |
-|  `def sum(args: Int*) = args.reduceLeft(_+_)`                                                            |  可変長引数                         |
-|  パッケージ                                                        |                                     |
-|  `import scala.collection._`                                                                             |  ワイルドカードでインポートします。 |
-|  `import scala.collection.Vector` 
     `import scala.collection.{Vector, Sequence}`                      |  個別にインポートします。         |
-|  `import scala.collection.{Vector => Vec28}`                                                             |  別名でインポートします。           |
-|  `import java.util.{Date => _, _}`                                                                       |  Date を除いて java.util のすべてをインポートします。 |
-|  _(ファイル先頭の)_ `package pkg` 
     `package pkg { ... }`                                             |  パッケージ宣言                     |
-|  データ構造                                                 |                                     |
-|  `(1,2,3)`                                                                                               |  タプルリテラル (`Tuple3`)          |
-|  `var (x,y,z) = (1,2,3)`                                                                                 |  構造化代入: パターンマッチによるタプルの展開。   |
-|  Bad`var x,y,z = (1,2,3)`                                           |  隠れたエラー: 各変数にタプル全体が代入されます。 |
-|  `var xs = List(1,2,3)`                                                                                  |  リスト (イミュータブル)            |
-|  `xs(2)`                                                                                                 |  括弧を使って添字を書きます。 ([slides](http://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) |
-|  `1 :: List(2,3)`                                                                                        |  先頭に要素を追加             |
-|  `1 to 5` _(_ `1 until 6` 
     `1 to 10 by 2` _と同じ)_                                                  |  Range の糖衣構文             |
-|  `()` _(中身のない括弧)_                                                                                 |  Unit 型 の唯一の値(C/Java でいう void) 。 |
-|  制御構文                                                |                               |
-|  `if (check) happy else sad`                                                                             |  条件分岐                     |
-|  `if (check) happy` 
     _(_ `if (check) happy else ()` _と同じ)_                                          |  条件分岐の省略形             |
-|  `while (x < 5) { println(x); x += 1}`                                                                   |  while ループ                 |
-|  `do { println(x); x += 1} while (x < 5)`                                                                |  do while ループ              |
-|  `import scala.util.control.Breaks._`
    `breakable {`
    `    for (x <- xs) {`
    `        if (Math.random < 0.1) break`
    `    }`
    `}`|  break ([slides](http://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) |
-|  `for (x <- xs if x%2 == 0) yield x*10` 
    _(_ `xs.filter(_%2 == 0).map(_*10)`  _と同じ)_               |  for 内包表記: filter/map             |
-|  `for ((x,y) <- xs zip ys) yield x*y` 
    _(_ `(xs zip ys) map { case (x,y) => x*y }` _と同じ)_          |  for 内包表記: 構造化代入             |
-|  `for (x <- xs; y <- ys) yield x*y` 
    _(_ `xs flatMap {x => ys map {y => x*y}}` _と同じ)_              |  for 内包表記: 直積                   |
-|  `for (x <- xs; y <- ys) {`
        `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
    `}`                     |  for 内包表記: 命令型の記述
    [sprintf-style](http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) |
-|  `for (i <- 1 to 5) {`
        `println(i)`
    `}`                                                        |  for 内包表記: 上限を含んだ走査       |
-|  `for (i <- 1 until 5) {`
        `println(i)`
    `}`                                                     |  for 内包表記: 上限を除いた走査       |
-|  パターンマッチング                                        |                                       |
-|  Good `(xs zip ys) map { case (x,y) => x*y }`
     Bad `(xs zip ys) map( (x,y) => x*y )` |  case をパターンマッチのために関数の引数で使っています。 |
-|  Bad
    `val v42 = 42`
    `Some(3) match {`
    `  case Some(v42) => println("42")`
    `    case _ => println("Not 42")`
    `}` |  "v42" は任意の Int の値とマッチする変数名として解釈され、 "42" が表示されます。 |
-|  Good
    `val v42 = 42`
    `Some(3) match {`
    ``    case Some(`v42`) => println("42")``
    `case _ => println("Not 42")`
    `}`  | バッククオートで囲んだ "\`v42\`" は既に存在する `v42` として解釈され、 "Not 42" が表示されます。 |
-|  Good
    `val UppercaseVal = 42`
    `Some(3) match {`
    `  case Some(UppercaseVal) => println("42")`
    `    case _ => println("Not 42")`
    `}` |  大文字から始まる `UppercaseVal` は既に存在する定数として解釈され、新しい変数としては扱われません。 これにより `UppercaseVal` は `3` とは異なる値と判断され、 "Not 42" が表示されます。 |
-|  オブジェクト指向                                        |                                 |
-|  `class C(x: R)` 
    _(_ `class C(private val x: R)`
    `var c = new C(4)` _と同じ)_                     |  コンストラクタの引数 - private |
-|  `class C(val x: R)`
    `var c = new C(4)`
    `c.x`                                                      |  コンストラクタの引数 - public  |
-|  `class C(var x: R) {`
    `assert(x > 0, "positive please")`
    `var y = x`
    `val readonly = 5`
    `private var secret = 1`
    `def this = this(42)`
    `}`|
    コンストラクタはクラスの body 部分 です。
    public メンバ の宣言
    読取可能・書込不可なメンバの宣言
    private メンバ の宣言
    代替コンストラクタ |
-|  `new{ ... }`                                                                                            |  無名クラス                     |
-|  `abstract class D { ... }`                                                                              |  抽象クラスの定義 (生成不可)    |
-|  `class C extends D { ... }`                                                                             |  継承クラスの定義               |
-|  `class D(var x: R)`
    `class C(x: R) extends D(x)`                                                     |  継承とコンストラクタのパラメータ (要望: 自動的にパラメータを引き継げるようになってほしい)
-|  `object O extends D { ... }`                                                                            |  シングルトンオブジェクトの定義 (モジュールに似ている) |
-|  `trait T { ... }`
    `class C extends T { ... }`
    `class C extends D with T { ... }`                  |  トレイト
    実装を持ったインターフェースで、コンストラクタのパラメータを持つことができません。 [mixin-able]({{ site.baseurl }}/tutorials/tour/mixin-class-composition.html).
-|  `trait T1; trait T2`
    `class C extends T1 with T2`
    `class C extends D with T1 with T2`             |  複数のトレイトを組み合わせられます。              |
-|  `class C extends D { override def f = ...}`	                                                           |  メソッドの override は明示する必要があります。    |
-|  `new java.io.File("f")`                   	                                                             |  オブジェクトの生成                                |
-|  Bad `new List[Int]`
     Good `List(1,2,3)` |  型のエラー: 抽象型のオブジェクトは生成できません。
    代わりに、習慣として、型を隠蔽するファクトリを使います。 |
-|  `classOf[String]`                                                                                       |  クラスの情報取得                                  |
-|  `x.isInstanceOf[String]`                                                                                |  型のチェック (実行時)                             |
-|  `x.asInstanceOf[String]`                                                                                |  型のキャスト (実行時)                             |
-|  `x: String`                                                                                             |  型帰属 (コンパイル時)                             |
+breakable {
+  for (x <- xs) {
+    if (Math.random < 0.1)
+      break
+  }
+}
    		break (slides)
    for (x <- xs if x % 2 == 0)
+  yield x * 10
    +
    上記と同様
    + 
    xs.filter(_ % 2 == 0).map(_ * 10)
    		for 内包記法: filter/map
    for ((x, y) <- xs zip ys)
+  yield x * y
    +
    上記と同様
    + 
    (xs zip ys) map {
+  case (x, y) => x * y
+}
    		for 内包表記: 構造化代入
    for (x <- xs; y <- ys)
+  yield x * y
    +
    上記と同様
    + 
    xs flatMap { x =>
+  ys map { y =>
+    x * y
+  }
+}
    		for 内包表記: 直積
    for (x <- xs; y <- ys) {
+  val div = x / y.toFloat
+  println("%d/%d = %.1f".format(x, y, div))
+}
    		for 内包表記: 命令型の記述
    sprintf-style
    for (i <- 1 to 5) {
+  println(i)
+}
    		for 内包表記: 上限を含んだ走査
    for (i <- 1 until 5) {
+  println(i)
+}
    		for 内包表記: 上限を除いた走査
    パターンマッチング
    Good
    (xs zip ys) map {
+  case (x, y) => x * y
+}

    Bad
    (xs zip ys) map {
+  (x, y) => x * y
+}
    		case をパターンマッチのために関数の引数で使っています。
    Bad
    + 
    val v42 = 42
+3 match {
+  case v42 => println("42")
+  case _   => println("Not 42")
+}
    		v42 は任意の Int の値とマッチする変数名として解釈され、 “42” が表示されます。
    Good
    + 
    val v42 = 42
+3 match {
+  case `v42` => println("42")
+  case _     => println("Not 42")
+}
    		バッククオートで囲んだ `v42` は既に存在する v42 として解釈され、 “Not 42” が表示されます。
    Good
    + 
    val UppercaseVal = 42
+3 match {
+  case UppercaseVal => println("42")
+  case _            => println("Not 42")
+}
    		大文字から始まる UppercaseVal は既に存在する定数として解釈され、新しい変数としては扱われません。 これにより UppercaseVal は 3 とは異なる値と判断され、 “Not 42” が表示されます。
    オブジェクト指向 
    class C(x: R)
    		コンストラクタの引数。x はクラス内部からのみ利用できます。（private）
    class C(val x: R)

    var c = new C(4)

    c.x
    		コンストラクタの引数。自動的に公開メンバとして定義されます。（public）
    class C(var x: R) {
+  assert(x > 0, "positive please")
+  var y = x
+  val readonly = 5
+  private var secret = 1
+  def this = this(42)
+}
    		コンストラクタはクラスの body 部分 です。
    public メンバ の宣言
    読取可能・書込不可なメンバの宣言
    private メンバ の宣言
    代替コンストラクタ
    new {
+  ...
+}
    		無名クラス
    abstract class D { ... }
    		抽象クラスの定義 (生成不可)
    class C extends D { ... }
    		継承クラスの定義
    class D(var x: R)

    class C(x: R) extends D(x)
    		継承とコンストラクタのパラメータ (要望: 自動的にパラメータを引き継げるようになってほしい)
    object O extends D { ... }
    		シングルトンオブジェクトの定義 (モジュールに似ている)
    trait T { ... }

    class C extends T { ... }

    class C extends D with T { ... }
    		トレイト
    実装を持ったインターフェースで、コンストラクタのパラメータを持つことができません。mixin-able.
    trait T1; trait T2

    class C extends T1 with T2

    class C extends D with T1 with T2
    		複数のトレイトを組み合わせられます。
    class C extends D { override def f = ...}
    		メソッドの override は明示する必要があります。
    new java.io.File("f")
    		オブジェクトの生成
    Bad
    new List[Int]

    Good
    List(1, 2, 3)
    		型のエラー: 抽象型のオブジェクトは生成できません。
    代わりに、習慣として、型を隠蔽するファクトリを使います。
    classOf[String]
    		クラスの情報取得
    x.isInstanceOf[String]
    		型のチェック (実行時)
    x.asInstanceOf[String]
    		型のキャスト (実行時)
    x: String
    		型帰属 (コンパイル時)
    Option型 
    Some(42)
    		空ではないオプション値
    None
    		空のオプション値のシングルトン
    Option(null) == None
+Option(obj.unsafeMethod)
    + しかし以下のケースは同じではない + 
    Some(null) != None
    		Null安全なオプション値の生成
    val optStr: Option[String] = None
    + 上記と同様 + 
    val optStr = Option.empty[String]
    		空のオプション値の明示的な型
    空のオプション値の生成
    val name: Option[String] =
+  request.getParameter("name")
+val upper = name.map {
+  _.trim
+} filter {
+  _.length != 0
+} map {
+  _.toUpperCase
+}
+println(upper.getOrElse(""))
    		パイプラインスタイル
    val upper = for {
+  name <- request.getParameter("name")
+  trimmed <- Some(name.trim)
+    if trimmed.length != 0
+  upper <- Some(trimmed.toUpperCase)
+} yield upper
+println(upper.getOrElse(""))
    		for 内包表記構文
    option.map(f(_))
    + 上記と同様 + 
    option match {
+  case Some(x) => Some(f(x))
+  case None    => None
+}
    		オプション値への関数の適用
    option.flatMap(f(_))
    + 上記と同様 + 
    option match {
+  case Some(x) => f(x)
+  case None    => None
+}
    		上記のmap と同様だが、関数は戻り値としてオプション値を返す必要がある。
    optionOfOption.flatten
    + 上記と同様 + 
    optionOfOption match {
+  case Some(Some(x)) => Some(x)
+  case _             => None
+}
    		ネストされたオプション値の展開
    option.foreach(f(_))
    + 上記と同様 + 
    option match {
+  case Some(x) => f(x)
+  case None    => ()
+}
    		オプション値へのプロシージャの適用
    option.fold(y)(f(_))
    + 上記と同様 + 
    option match {
+  case Some(x) => f(x)
+  case None    => y
+}
    		オプション値への関数の適用。空であればデフォルト値（y）を返す
    option.collect {
+  case x => ...
+}
    + 上記と同様 + 
    option match {
+  case Some(x) if f.isDefinedAt(x) => ...
+  case Some(_)                     => None
+  case None                        => None
+}
    		オプション値への部分的なパターンマッチの適用
    option.isDefined
    + 上記と同様 + 
    option match {
+  case Some(_) => true
+  case None    => false
+}
    		空のオプション値でなければtrueを返す。
    option.isEmpty
    + 上記と同様 + 
    option match {
+  case Some(_) => false
+  case None    => true
+}
    		空のオプション値であればtrueを返す。
    option.nonEmpty
    + 上記と同様 + 
    option match {
+  case Some(_) => true
+  case None    => false
+}
    		空のオプション値でなければtrueを返す。
    option.size
    + 上記と同様 + 
    option match {
+  case Some(_) => 1
+  case None    => 0
+}
    		空であれば0 を返し、そうでなければ1を返す。
    option.orElse(Some(y))
    + 上記と同様 + 
    option match {
+  case Some(x) => Some(x)
+  case None    => Some(y)
+}
    		値を評価し、空のオプション値であれば代替のオプション値を返す。
    option.getOrElse(y)
    + 上記と同様 + 
    option match {
+  case Some(x) => x
+  case None    => y
+}
    		値を評価し、空のオプションであればデフォルトの値を返す。
    option.get
    + 上記と同様 + 
    option match {
+  case Some(x) => x
+  case None    => throw new Exception
+}
    		値を返すが、空であれば例外を投げる。
    option.orNull
    + 上記と同様 + 
    option match {
+  case Some(x) => x
+  case None    => null
+}
    		値を返すが、空であればnullを返す。
    option.filter(f)
    + 上記と同様 + 
    option match {
+  case Some(x) if f(x) => Some(x)
+  case _               => None
+}
    		fを満たすオプション値
    option.filterNot(f(_))
    + 上記と同様 + 
    option match {
+  case Some(x) if !f(x) => Some(x)
+  case _                => None
+}
    		fを満たさないオプション値
    option.exists(f(_))
    + 上記と同様 + 
    option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => false
+}
    		オプション値がfを満たす場合はtrueを返す。そうでない場合、あるいは空であればfalseを返す。
    option.forall(f(_))
    + 上記と同様 + 
    option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => true
+}
    		オプション値がfを満たす場合はtrueを返す。そうでない場合はfalseを返すが、空であればtrueを返す。
    option.contains(y)
    + 上記と同様 + 
    option match {
+  case Some(x) => x == y
+  case None    => false
+}
    		オプション値が値と同じか判別する。空であればfalseを返す。
    diff --git a/_ja/getting-started/install-scala.md b/_ja/getting-started/install-scala.md new file mode 100644 index 0000000000..a85f87263c --- /dev/null +++ b/_ja/getting-started/install-scala.md @@ -0,0 +1,181 @@ +--- +layout: singlepage-overview +title: 入門 +partof: getting-started +language: ja +includeTOC: true +redirect_from: + - /ja/scala3/getting-started.html # we deleted the scala 3 version of this page +--- + +このページは Scala 2と Scala 3の両方に対応しています。 + +## インストールなしで今すぐ Scala を試す！ + +Scala を今すぐ試すにはブラウザで「Scastie」を使います。 +Scastieは Scala のサンプルコードがどのように動作するかをブラウザで簡単に試すことができるオンライン「playground」で、様々なバージョンのコンパイラと公開されているライブラリが利用できます。 + +> Scastie は Scala 2と Scala 3の両方をサポートしていますが、デフォルトでは Scala 3になっています。Scala 2のスニペットをお探しの方は、[こちら](https://scastie.scala-lang.org/MHc7C9iiTbGfeSAvg8CKAA)をご覧ください。 + +## コンピューターに Scala をインストールする + +Scala をインストールすると、コンパイラやビルドツールなどの様々なコマンドラインツールが同時にインストールされます。 +私たちは必須ツール全てを確実にインストールするために「Coursier」の使用をお勧めしますが、それらを手動でインストールすることもできます。 + +### Scala インストーラーを使う（推奨） + +Scala のインストーラーは[Coursier](https://get-coursier.io/docs/cli-overview)というツールで、コマンドは`cs`です。このツールを使うと、JVM と標準 Scala ツールがシステムにインストールされます。 +以下の手順でお使いのシステムにインストールしてください。 + + +{% tabs install-cs-setup-tabs class=platform-os-options %} + + +{% tab macOS for=install-cs-setup-tabs %} +{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-brew %} +{% altDetails cs-setup-macos-nobrew "または、Homebrewを使用しない場合は" %} + {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-x86-64 %} +{% endaltDetails %} +{% endtab %} + + + +{% tab Linux for=install-cs-setup-tabs %} + {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.linux-x86-64 %} +{% endtab %} + + + +{% tab Windows for=install-cs-setup-tabs %} + [the Scala installer for Windows]({{site.data.setup-scala.windows-link}})を、ダウンロードして実行してください。 +{% endtab %} + + + +{% tab Other for=install-cs-setup-tabs defaultTab %} + + [手順に従って `cs` ランチャーをインストール](https://get-coursier.io/docs/cli-installation)し、その次に以下を実行します。`./cs setup` +{% endtab %} + + +{% endtabs %} + + +`cs setup` は JVM の管理だけでなく、便利なコマンドラインツールもインストールします: + +- JDK (インストール済みでなければ) +- [sbt](https://www.scala-sbt.org/) ビルドツール +- [Ammonite](https://ammonite.io/), 強化された REPL +- [scalafmt](https://scalameta.org/scalafmt/), コードフォーマッター +- `scalac` (Scala 2 コンパイラー) +- `scala` (Scala 2 の REPL と script runner). + +`cs`の詳細については、[ccoursier-cliのドキュメント](https://get-coursier.io/docs/cli-overview)をご覧ください。 + +> 現在`cs setup` は Scala 2 のコンパイラとランナー(それぞれ`scalac`と`scala`コマンド)をインストールします。ほとんどのプロジェクトでは Scala 2 と Scala 3 の両方に対応したビルドツールを使用しているので、通常は問題になりません。しかし、以下の追加コマンドを実行することで、Scala 3のコンパイラとランナーをコマンドラインツールとしてインストールすることができます。 +> ``` +> $ cs install scala3-compiler +> $ cs install scala3 +> ``` + +### 手動でのインストール + +Scala プロジェクトのコンパイル、実行、テスト、パッケージ化に必要なツールは Java と sbt の2つだけです。 +Java のバージョンは8または11です。 +これらを手動でインストールするには: + +1. Java 8または11がインストールされていない場合は、[Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html)、[Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html)、または[AdoptOpenJDK 8/11](https://adoptopenjdk.net/)からJavaをダウンロードしてください。Scala と Java の互換性の詳細については、[JDK Compatibility](/overviews/jdk-compatibility/overview.html)を参照してください。 +1. [sbt](https://www.scala-sbt.org/download.html)をインストールしてください。 + +## sbt で「Hello World」プロジェクトを作成する + +sbt をインストールしたら、次のセクションで説明する Scala プロジェクトを作成する準備ができました。 + +プロジェクトの作成には、コマンドラインまたはIDEを使用します。コマンドラインに慣れている方は、その方法をお勧めします。 + +### コマンドラインを使う + +sbt は、Scala のビルドツールです。sbt は、Scala のコードをコンパイルし、実行し、テストします。(sbt は、Scala コードのコンパイル、実行、テストを行います（ライブラリの公開やその他多くのタスクも可能です）。 + +sbt で新しい Scala プロジェクトを作成するには、以下の手順で行います: + +1. 空のディレクトリに`cd`する. +1. Scala 3プロジェクトを作成する場合は`sbt new scala/scala3.g8`、Scala 2プロジェクトを作成する場合は`sbt new scala/hello-world.g8`というコマンドを実行します。これは、GitHub からプロジェクトのテンプレートを引き出します。このとき"target"という名前のディレクトリが作成されますが無視してください。 +1. プロンプトが表示されたら、アプリケーションの名前を`hello-world`とします。これにより、"hello-world "というプロジェクトが作成されます。 +1. それでは、生成されたばかりのものを見てみましょう: + +``` +- hello-world + - project (sbt が利用するファイル) + - build.properties + - build.sbt (sbt のビルド定義) + - src + - main + - scala (あなたの Scala のコードはすべてここに入る) + - Main.scala (プログラムのエントリーポイント) <-- 今、必要なのはこれだけです +``` + +sbt についての詳しいドキュメントは、[Scala Book](/scala3/book/tools-sbt.html)（[Scala 2バージョンはこちら](/overviews/scala-book/scala-build-tool-sbt.html)）と、[sbt の公式ドキュメント](https://www.scala-sbt.org/1.x/docs/ja/index.html)に掲載されています。 + +### IDEを使う + +このページの残りの部分を読み飛ばして、[Building a Scala Project with IntelliJ and sbt](/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html)に進んでも問題ありません。 + +## hello-world プロジェクトを開く + +IDE を使ってプロジェクトを開いてみましょう。最もポピュラーなものは IntelliJ と VSCode です。どちらも豊富な IDE 機能を備えていますが、他にも[多くのエディタ](https://scalameta.org/metals/docs/editors/overview.html)を使うことができます。 + +### IntelliJ を使う + +1. [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)をダウンロードしてインストールします。 +1. IntelliJ プラグインのインストール方法にしたがって、[Scala プラグインをインストール](https://www.jetbrains.com/help/idea/managing-plugins.html)します。 +1. `build.sbt`ファイルを開き、*Open as a project*を選択します。 + +### VSCode で metals を使う + +1. [VSCode](https://code.visualstudio.com/Download)をダウンロードする +1. [Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals)から Metals extension をインストールする +1. 次に、build.sbt ファイルがあるディレクトリを開きます（前の指示に従った場合は、hello-world というディレクトリになるはずです）。プロンプトが表示されたら、「Import build」を選択します。 + +> +>[Metals](https://scalameta.org/metals) は、[VS Codeや Atom、Sublime Textなど](https://scalameta.org/metals/docs/editors/overview.html)のエディタで Scala のコードを書くためのサポートを提供する「Scala 言語サーバ」であり、Language Server Protocol を使用しています。 +> Metalsはバックグラウンドで[BSP（Build Server Protocol）](https://build-server-protocol.github.io/)を使用してビルドツールと通信します。Metalsの仕組みについては、[「Write Scala in VS Code, Vim, Emacs, Atom and Sublime Text with Metals」](https://www.scala-lang.org/2019/04/16/metals.html)を参照してください。 + +### ソースコードをいじってみよう + +この2つのファイルを IDE で表示します: + +- _build.sbt_ +- _src/main/scala/Main.scala_ + +次のステップでプロジェクトを実行すると、 _src/main/scala/Main.scala_ のコードを実行するために、 _build.sbt_ の設定が使われます。 + +## Hello World の実行 + +IDE の使用に慣れている場合は、IDE から _Main.scala_ のコードを実行することができます。 + +または、以下の手順でターミナルからアプリケーションを実行できます: + +1. `hello-world`ディレクトリに`cd` する +1. `sbt`コマンドを実行し、sbt console を開く +1. `~run`と打ち込む。 `~` は全てのコマンドの前に追加できるコマンドで、ファイル保存を検知してコマンドを再実行してくれるため、編集・実行・デバッグのサイクルを高速に行うことができます。sbt はここでも`target`ディレクトリを生成しますが無視してください。 + +このプロジェクトの`run`を止めたければ、`[Enter]`を押して`run`コマンドを中断します。その後`exit`と入力するか`[Ctrl+D]`を押すと sbt が終了し、コマンドラインプロンプトに戻ります。 + +## 次のステップ + +上記のチュートリアルの後は以下の教材に進んでください。 + +* [The Scala Book](/scala3/book/introduction.html) (Scala 2版は[こちら](/overviews/scala-book/introduction.html))はScalaの主な機能を紹介する短いレッスンのセットを提供します。 +* [The Tour of Scala](/tour/tour-of-scala.html) Scalaの機能を一口サイズで紹介します。 +* [Learning Courses](/online-courses.html) オンラインのインタラクティブなチュートリアルやコースです。 +* [books](/books.html) 人気のある Scalaの 書籍を紹介します +* [The migration guide](/scala3/guides/migration/compatibility-intro.html) 既存の Scala 2コードベースを Scala 3に移行する際に役立ちます。 + +## ヘルプが必要な人は +他の Scala ユーザーとすぐに連絡を取りたい場合は、多くのメーリングリストやリアルタイムのチャットルームがあります。これらのリソースのリストや、どこに問い合わせればよいかについては、[コミュニティページ](https://scala-lang.org/community/)をご覧ください。 + +### (日本語のみ追記) +Scala について日本語で質問したい場合、Twitterでつぶやくと気づいた人が教えてくれます。 diff --git a/_ja/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md b/_ja/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md new file mode 100644 index 0000000000..e701b837f0 --- /dev/null +++ b/_ja/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md @@ -0,0 +1,100 @@ +--- +title: Intellij で sbt を使って Scala プロジェクトをビルドする +layout: singlepage-overview +partof: building-a-scala-project-with-intellij-and-sbt +language: ja +disqus: true +previous-page: /ja/getting-started/intellij-track/getting-started-with-scala-in-intellij +next-page: /ja/testing-scala-in-intellij-with-scalatest +--- + +このチュートリアルでは、[sbt](https://www.scala-sbt.org/1.x/docs/index.html) を使って Scala プロジェクトをビルドする方法を見ていきます。 +sbtは、どのようなサイズの Scala プロジェクトでもコンパイル、実行、テストできる人気のツールです。 +sbt（または Maven や Gradle）のようなビルドツールの使用は、1つ以上のコードファイルや依存関係のあるプロジェクトを作ったら、絶対不可欠になります。 +[最初のチュートリアル](./getting-started-with-scala-in-intellij.html)を完了していることを前提とします。 + +## プロジェクトを作成 +このでは、Intellij でプロジェクトの作り方をお見せします。 +ですが、コマンドラインのほうが快適でしたら、[Getting +コマンドラインの sbt で Scala を始める](/ja/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html) を試して、「Scala コードを記述」節に戻ってくるのをおすすめします。 + +1. コマンドラインからプロジェクトを作っていなければ、Intellij を開き、"Create New Project" を選びます。 + * 左パネルで Scala を選び、右パネルで sbt を選びます。 + * **Next** をクリックします + * プロジェクトに **SbtExampleProject** と名前を付けます。 +1. コマンドラインですでにプロジェクトを作成していたら、Intelij を開き、**Import Project** を選んで、あなたのプロジェクトの `build.sbt` ファイルを開きます。 +1. **JDK version** が `1.8` で、**sbt version** が少なくとも `0.13.13` であることを確認します。 +1. **Use auto-import** を選びます。すると依存関係が利用可能であれば自動でダウンロードされます。 +1. **Finish** を選びます。 + +## ディレクトリ構造を理解 + +sbt は、より複雑なプロジェクトを構築すだしたら便利になるであろう多くのディレクトリを作成します。 +今はそのほとんどを無視できますが、全部が何のためかをここでちらっと見ておきましょう。 + +``` +- .idea (IntelliJ ファイル) +- project (sbt のプラグインや追加設定) +- src (ソースファイル) + - main (アプリケーションコード) + - java (Java ソースファイル) + - scala (Scala ソースファイル) + ^-- 今はこれが必要なものの全てです + - scala-2.12 (Scala 2.12 固有ファイル) + - test (ユニットテスト) +- target (生成されたファイル) +- build.sbt (sbt のためのビルド定義ファイル) +``` + + +## Scala コードを記述 +1. 左の **Project** パネルで、`SbtExampleProject` => `src` => `main` を展開します。 +1. `scala` を右クリックし、**New** => **Package** を選択します。 +1. パッケージに `example` と名前をつけ、**OK** をクリックします。 +1. パッケージ `example` を右クリックし、**New** => **Scala class** をクリックします。 +1. クラスに　`Main` と名前をつけ、**Kind** を `object` に変更します。 +1. クラスのコードを次おように変更します。 + +``` +@main def run() = + val ages = Seq(42, 75, 29, 64) + println(s"The oldest person is ${ages.max}") +``` + +注：Intellij は Scala コンパイラーの独自実装を持っており、コードが間違っていると Intellij が示しても正しい場合がときどきあります。 +コマンドラインで sbt がプロジェクトを実行できるかを常にチェックできます。。 + +## プロジェクトを実行 +1. **Run** メニューから、**Edit configurations** を選びます。 +1. **+** ボタンをクリックし、**sbt Task** を選びます +1. それに `Run the program` と名付けます。 +1. **Tasks** フィールドで、`~run` と入力します. + `~` は、プロジェクトファイルへの変更を保存するたびに sbt にプロジェクトを再ビルド、再実行させます。 +1. **OK** をクリックします。 +1. **Run** メニューで、**Run 'Run the program'** をクリックします。 +1. コードの `75` を `61` に変えて、コンソールで更新された出力を見ます。 + +## 依存関係を追加 + +趣向を少し変えて、アプリに追加機能を加えるために公開ライブラリの使い方を見てみましょう。 + +`build.sbt` を開き、以下のファイルを追加します。 + +``` +libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2" +``` + +ここで `libraryDependencies` は依存関係の集合であり、`+=` を使うことにより、[scala-parser-combinators](https://github.com/scala/scala-parser-combinators) への依存を、sbt が起動時に取得してくる依存関係の集合に加えています。 +これで、どの Scala ファイルでも、`scala-parser-combinator` にあるクラスやオブジェクトなどを通常のインポートでインポートできます。 + +さらなる公開ライブラリは、Scala ライブラリインデックス [Scaladex](https://index.scala-lang.org/) で見つけられます。 +そこでは上述のような依存関係情報をコピーでき、`build.sbt` ファイルにペーストできます。 + +## 次のステップ + +**Intellij で入門** シリーズの次のチュートリアルに進み、[Intelij で ScalaTest を使って Scala をテストする](testing-scala-in-intellij-with-scalatest.html)方法を学びます。 + +**あるいは** + +- インタラクティブなオンラインコース [Scala Exercises](https://www.scala-exercises.org/scala_tutorial) で Scala を学習します。 +- [Scala ツアー](/ja//tour/tour-of-scala.html) で Scala の特徴を一口大のサイズでステップバイステップに学びます。 diff --git a/_ja/getting-started/intellij-track/getting-started-with-scala-in-intellij.md b/_ja/getting-started/intellij-track/getting-started-with-scala-in-intellij.md new file mode 100644 index 0000000000..676c247d40 --- /dev/null +++ b/_ja/getting-started/intellij-track/getting-started-with-scala-in-intellij.md @@ -0,0 +1,73 @@ +--- +title: Intellij で Scala を始める +layout: singlepage-overview +partof: getting-started-with-scala-in-intellij +language: ja +disqus: true +next-page: /ja/building-a-scala-project-with-intellij-and-sbt +--- + +このチュートリアルでは、Intellij IDEA と Scala プラグインを使って最小限の Scala プロジェクトを作る方法を見ていきます。 +このガイドでは、Intellij があなたのために Scala をダウンロードしてくれます。 + +## インストール +1. Java 8 JDK（別名 1.8）がインストールされていることを確認します。 + * コマンドラインで `javac -version` を実行し、`javac 1.8.___` と表示されるのを確認します。 + * バージョン 1.8 かそれ以上がなければ、[JDK をインストールします](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)。 +1. [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/) をダウンロード、インストールします。 +1. それから、Intellij を起動したあと、[how to install IntelliJ plugins](https://www.jetbrains.com/help/idea/installing-updating-and-uninstalling-repository-plugins.html) の指示に従って Scala プラグインをダウンロードしてインストールできます（プラグインメニューで「Scala」と検索）。 + +プロジェクトを作るときは、Scala の最新バージョンをインストールします。 +注：存在する Scala プロジェクトを開きたければ、Intellij をスタートするときに **Open** をクリックします。 + + +## プロジェクトを作成 +1. Intellij を開き、**File** => **New** => **Project** をクリックします。 +1. 左パネルで Scala を選びます。右のパネルで IDEA を開きます。 +1. プロジェクトに **HelloWorld** と名前を付けます。 +1. 今回始めて Intellij で Scala プロジェクトを初めて作るとすれば、Scala SDK をインストールする必要があります。Scala SDK フィールドの右側にある **Create** ボタンをクリックします。 +1. 最新のバージョン番号（例 {{ site.scala-version }}）を選び、**Download**をクリックします。 + これは数分かかるかもしれませんが、今後のプロジェクトでは同じ SDK を使えます。 +1. SDK がダウンロードされたらすぐに、「New Project」ウィンドウに戻って **Finish** ボタンをクリックします。 + + +## コードを記述 + +1. 左側の **プロジェクト** ペインで、`src` ディレクトリを右クリックし、**New** => **Scala class** を選択します。 + もし、**Scala class** が見当たらなければ、**HelloWorld** を右クリックし、**Add Framework Support...** をクリックし、**Scala** を選択して進めます。 + **Error: library is not specified** が発生したら、ダウンロードボタンをクリックするか、またはライブラリパスを手動で選択します。 +1. クラスに `Hello` と名前を付けて、**Kind** を `object` に変更します。 +1. クラスのコードを次のように変更します。 + +``` +object Hello extends App { + println("Hello, World!") +} +``` + +## 実行 +* あなたのコード `Hello` で右クリックし、**Run 'Hello'** を選びます。 +* 完了です！ + +## Scala を試してみる + +コード例を試してみる良い方法は、Scala ワークシートです。 + +1. 左のプロジェクトペインで、`src` ディレクトリを右クリックし、**New** => **Scala Worksheet** を選びます。 +2. 新しい Scala ワークシートに "Mathematician" と名前を付けます。 +3. ワークシートに以下のコードを入力します。 + +``` +def square(x: Int) = x * x + +square(2) +``` + +コードを変更するにつれて、その評価結果が右ペインに現れるのに気づくでしょう。 + +## 次のステップ + +言語を学び始めるのに使える、シンプルな Scala プロジェクトの作り方を学びました。 +次のチュートリアルでは、シンプルなプロジェクトから本番アプリケーションまで使える sbt という重要なビルドツールを紹介します。 + +次: [Intellij で sbt を使って Scala プロジェクトをビルドする](building-a-scala-project-with-intellij-and-sbt.html) diff --git a/_ja/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md b/_ja/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md new file mode 100644 index 0000000000..815760672c --- /dev/null +++ b/_ja/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md @@ -0,0 +1,68 @@ +--- +title: Intelij で ScalaTest を使って Scala をテストする +layout: singlepage-overview +partof: testing-scala-in-intellij-with-scalatest +language: ja +disqus: true +previous-page: /ja/building-a-scala-project-with-intellij-and-sbt +--- + +Scala には複数のライブラリとテスト方法がありますが、このチュートリアルでは、ScalaTest フレームワークから [FunSuite](https://www.scalatest.org/getting_started_with_fun_suite) という人気のある選択肢を実演します。 + +[Intellij で sbt を使って Scala プロジェクトをビルドする方法](./building-a-scala-project-with-intellij-and-sbt.html)を知っている前提とします。 + +## セットアップ +1. Intellij で sbt プロジェクトを作成します。 +1. ScalaTest への依存を追加します。 + 1. `build.sbt` ファイルに ScalaTest への依存を追加します。 + ``` + libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test + ``` + 1. `build.sbt was changed` という通知が出たら、**auto-import** を選択します。 + 1. これらの2つのアクションにより、`sbt` が ScalaTest ライブラリをダウンロードします。 + 1. `sbt` の同期完了を待ちます。そうしなければ `FunSuite` と `test()` は認識されません。 +1. 左のプロジェクトペインで、`src` => `main` を展開します。 +1. `scala` を右クリックし、**New** => **Scala class** を選択します。 +1. クラスに `CubeCalculator` と名前をつけて、**Kind** を `object` に変更し、**OK** をクリックします。 +1. コードを次の通り置き換えます。 + ``` + object CubeCalculator: + def cube(x: Int) = + x * x * x + ``` + +## テストを作成 +1. 左のプロジェクトペインで、`src` => `test` を展開します。 +1. `scala` を右クリックし、**New** => **Scala class** を選択します。 +1. クラスに `CubeCalculatorTest` と名前を付けて、**OK** をクリックします。 +1. コードを次の通り置き換えます。 + ``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite: + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } + ``` +1. `CubeCalculatorTest` のソースコード内で右クリックし、**Run 'CubeCalculatorTest'** を選択します。 + +## コードを理解 + +一行ずつ詳細に調べていきましょう。 + +* `class CubeCalculatorTest` は、オブジェクト `CubeCalculator` をテストすることを意味します。 +* `extends FunSuite` により、ScalaTest の FunSuite クラスの機能（例えば `test` 関数）が使えるようになります。 +* `test` は FunSuite から来た関数で、関数本体内のアサーションの結果を収集します。 +* `"CubeCalculator.cube"` は、テストの名前です。 + どんな名前でもよいですが、慣例のひとつは "ClassName.methodName" です。 +* `assert` は、真偽値の条件を1つ受けとり、そのテストが合格するか失敗するかを判断します。 +* `CubeCalculator.cube(3) === 27` は `cube` 関数の結果が実際に 27 であるかどうかを調べます。 + `===` は ScalaTest の一部であり、きれいなエラーメッセージを提供します。 + +## テストケースを追加する +1. 1つ目の `assert` 句のあとにもう1つの句を追加し、`0` の3乗をチェックします。 +1. `CubeCalculatorTest` を右クリックして 'Run **CubeCalculatorTest**' を選ぶことで、テストを再実行します。 + +## 結び +Scala コードのテスト方法のひとつを見ました。 +ScalaTest の FunSuite については[公式ウェブサイト](https://www.scalatest.org/getting_started_with_fun_suite)で詳しく学べます。 diff --git a/_ja/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md b/_ja/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md new file mode 100644 index 0000000000..3684641a41 --- /dev/null +++ b/_ja/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md @@ -0,0 +1,84 @@ +--- +title: コマンドラインの sbt で Scala を始める +layout: singlepage-overview +partof: getting-started-with-scala-and-sbt-on-the-command-line +language: ja +disqus: true +next-page: /ja/testing-scala-with-sbt-on-the-command-line +--- + +このチュートリアルでは、テンプレートから Scala プロジェクトを作成する方法を見ていきます。 +あなた自身のプロジェクトを始めるスタート地点として使えます。 +Scala のデファクトのビルドツール [sbt](https://www.scala-sbt.org/1.x/docs/index.html) を用います。 +sbt はあなたのプロジェクトに関連した様々なタスク、とりわけコンパイル、実行、テストをしてくれます。 +ターミナルの使い方を知っていることを前提とします。 + +## インストール +1. Java 8 JDK（別名 1.8）がインストールされていることを確認します。 + * コマンドラインで `javac -version` を実行し、`javac 1.8.___` と表示されるのを確認します。 + * バージョン 1.8 かそれ以上がなければ、[JDK をインストールします](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)。 +1. sbt をインストールします。 + * [Mac](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html) + * [Windows](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html) + * [Linux](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html) + +## プロジェクトを作成 +1. 空のフォルダーに `cd` 。 +1. コマンド `sbt new scala/hello-world.g8` を実行します。 +これは GitHub から 'hello-world' というテンプレートを取ってきます。 +`target` フォルダーも作成しますが、無視してください。 +1. 入力をうながされたら、アプリを `hello-world` と名付けます。 +これで "hello-world" というプロジェクトが作成されます。 +1. 生成されたばかりのものを見てみましょう。 + +``` +- hello-world + - project （sbt はこのディレクトリを管理プラグインや依存関係のインストールに使います） + - build.properties + - src + - main + - scala （Scala コードはここに来ます) + -Main.scala (プログラムの入口） <-- 今のところこれこそが欲しいものです + build.sbt （sbt のビルド定義ファイル） +``` + +プロジェクトをビルドしたら、sbt は生成されるファイルのための `target` をもっと作るでしょう。 +これらは無視してください。 + +## プロジェクトを実行 +1. `hello-world` に `cd` 。 +1. `sbt` を実行します。sbt コンソールが開くでしょう。 +1. `~run` と入力します。`~` はオプションで、ファイルが保存されるたびに sbt にコマンドを再実行させるので、すばやい編集/実行/デバッグサイクルを回せます。 +sbt は `target` ディレクトリを作成しますが、無視してください。 + +## コードを修正 +1. お好きなテキストディタでファイル `src/main/scala/Main.scala` を開きます。 +1. "Hello, World!" を "Hello, New York!" に変更します。 +1. sbt コマンドを停止していなければ、コンソールに "Hello, New York!" と印字されるのが見えるでしょう。 +1. 繰り返し変更してみてコンソールが変化するのを見てみましょう。 + +## 依存関係を追加 +趣向を少し変えて、アプリに追加機能を加えるために公開ライブラリの使い方を見てみましょう。 + +`build.sbt` を開き、以下のファイルを追加します。 + +1. `build.sbt` を開き、以下の行を追加します。 + +``` +libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2" +``` + +ここで `libraryDependencies` は依存関係の集合であり、`+=` を使うことにより、[scala-parser-combinators](https://github.com/scala/scala-parser-combinators) への依存を、sbt が起動時に取得してくる依存関係の集合に加えています。 +これで、どの Scala ファイルでも、`scala-parser-combinator` にあるクラスやオブジェクトなどを通常のインポートでインポートできます。 + +さらなる公開ライブラリは、Scala ライブラリインデックス [Scaladex](https://index.scala-lang.org/) で見つけられます。 +そこでは上述のような依存関係情報をコピーでき、`build.sbt` ファイルにペーストできます。 + +## 次のステップ + +**sbt で入門** シリーズの次のチュートリアルに進み、[コマンドライン で sbt を使って Scala をテストする](testing-scala-with-sbt-on-the-command-line.html)方法を学びます。 + +**あるいは** + +- インタラクティブなオンラインコース [Scala Exercises](https://www.scala-exercises.org/scala_tutorial) で Scala を学習します。 +- [Scala ツアー](/ja//tour/tour-of-scala.html) で Scala の特徴を一口大のサイズでステップバイステップに学びます。 diff --git a/_ja/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md b/_ja/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md new file mode 100644 index 0000000000..2ef26d3cf1 --- /dev/null +++ b/_ja/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md @@ -0,0 +1,71 @@ +--- +title: コマンドラインで ScalaTest を使って Scala をテストする +layout: singlepage-overview +partof: testing-scala-with-sbt-on-the-command-line +language: ja +disqus: true +previous-page: /ja/getting-started-with-scala-and-sbt-on-the-command-line +--- + +Scala には複数のライブラリとテスト方法がありますが、このチュートリアルでは、ScalaTest フレームワークから [FunSuite](https://www.scalatest.org/getting_started_with_fun_suite) という人気のある選択肢を実演します。 + +[sbt での Scala プロジェクト作成方法](/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html)を知っている前提とします。 + +## セットアップ +1. コマンドラインで、どこかに新しいディレクトリを作成します。 +1. そのディレクトリに `cd` して、`sbt new scala/scalatest-example.g8` を実行します。 +1. プロジェクトに `ScalaTestTutorial` と名前を付けます。 +1. ScalaTest が依存関係として `build.sbt` ファイルに書かれたプロジェクトができます。. +1. そのディレクトリに `cd` して、`sbt test` を実行します。 + これは `CubeCalculator.cube` という1つのテストを含むテストスイート `CubeCalculatorTest` を実行します。 + +``` +sbt test +[info] Loading global plugins from /Users/username/.sbt/0.13/plugins +[info] Loading project definition from /Users/username/workspace/sandbox/my-something-project/project +[info] Set current project to scalatest-example (in build file:/Users/username/workspace/sandbox/my-something-project/) +[info] CubeCalculatorTest: +[info] - CubeCalculator.cube +[info] Run completed in 267 milliseconds. +[info] Total number of tests run: 1 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0 +[info] All tests passed. +[success] Total time: 1 s, completed Feb 2, 2017 7:37:31 PM +``` + +## テストを理解 +1. テキストエディタで2つのファイルを開きます。 + * `src/main/scala/CubeCalculator.scala` + * `src/test/scala/CubeCalculatorTest.scala` +1. `CubeCalculator.scala` ファイルでは、関数 `cube` がどのように定義されているかが分かります。 +1. `CubeCalculatorTest.scala` ファイルでは、テスト対象オブジェクトにちなんで名前を付けられたクラスが見えます。 + +``` + import org.scalatest.FunSuite + + class CubeCalculatorTest extends FunSuite { + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } + } +``` + +一行ずつ詳細に調べていきましょう。 + +* `class CubeCalculatorTest` は、オブジェクト `CubeCalculator` をテストすることを意味します。 +* `extends FunSuite` により、ScalaTest の FunSuite クラスの機能（例えば `test` 関数）が使えるようになります。 +* `test` は FunSuite から来た関数で、関数本体内のアサーションの結果を収集します。 +* `"CubeCalculator.cube"` は、テストの名前です。 + どんな名前でもよいですが、慣例のひとつは "ClassName.methodName" です。 +* `assert` は、真偽値の条件を1つ受けとり、そのテストが合格するか失敗するかを判断します。 +* `CubeCalculator.cube(3) === 27` は `cube` 関数の結果が実際に 27 であるかどうかを調べます。 + `===` は ScalaTest の一部であり、きれいなエラーメッセージを提供します。 + +## テストケースを追加する +1. 1つ目の `assert` 句のあとにもう1つの句を追加し、`0` の3乗をチェックします。 +1. `sbt test` を再び実行し、結果を見ます。 + +## 結び +Scala コードのテスト方法のひとつを見ました。 +ScalaTest の FunSuite については[公式ウェブサイト](https://www.scalatest.org/getting_started_with_fun_suite)で詳しく学べます。 diff --git a/_ja/index.md b/_ja/index.md new file mode 100644 index 0000000000..358ef903da --- /dev/null +++ b/_ja/index.md @@ -0,0 +1,100 @@ +--- +layout: landing-page +title: Learn Scala +language: ja +partof: documentation +more-resources-label: その他のリソース + + +# Content masthead links + +sections: + - title: "最初のステップ" + links: + - title: "入門" + description: "あなたのコンピューターに Scala をインストールして、Scala コードを書きはじめよう！" + icon: "fa fa-rocket" + link: /ja/getting-started/install-scala.html + - title: "Scala ツアー" + description: "コア言語機能をひと口大で紹介" + icon: "fa fa-flag" + link: /ja/tour/tour-of-scala.html + - title: "Scala 3 Book" + description: "主要な言語仕様のイントロダクションをオンラインブックで読む" + icon: "fa fa-book" + link: /scala3/book/introduction.html + - title: Online Courses + description: "MOOCs to learn Scala, for beginners and experienced programmers." + icon: "fa fa-cloud" + link: /online-courses.html + - title: 書籍（英語のみ） + description: "Printed and digital books about Scala." + icon: "fa fa-book" + link: /books.html + - title: Tutorials + description: "Take you by the hand through a series of steps to create Scala applications." + icon: "fa fa-tasks" + link: /tutorials.html + + - title: "リピーター向け" + links: + - title: "API" + description: "Scala の全バージョンの API ドキュメント（英語のみ）" + icon: "fa fa-file-alt" + link: /api/all.html + - title: "Overviews" + description: "Scala の多くの機能を網羅する詳細ドキュメント" + icon: "fa fa-database" + # TODO: 日本語訳はあるがリニューアル前のもの。要修正 + link: /ja/overviews/index.html + - title: "スタイルガイド" + description: "Scala らしいコードを書くための詳細なガイド（英語のみ）" + icon: "fa fa-bookmark" + link: /style/index.html + - title: "チートシート" + description: "Scala 構文の基礎を網羅する便利なチートシート" + icon: "fa fa-list" + link: /ja/cheatsheets/index.html + - title: "Scala よくある質問" + description: "Scala 言語機能についてよく聞かれる質問＆回答集（英語のみ）" + icon: "fa fa-question-circle" + link: /tutorials/FAQ/index.html + - title: "言語仕様" + description: "Scala の形式的言語仕様（英語のみ）" + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/2.13/ + - title: "Language Reference" + description: "Scala 3 の言語仕様" + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference + + - title: "Explore Scala 3" + links: + - title: "Migration Guide" + description: "Scala 2 から Scala 3 へ移行するためのガイド" + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "Scala 3 の新機能" + description: "Scala 3 で追加されたさまざまな新機能の概要" + icon: "fa fa-star" + link: /ja/scala3/new-in-scala3.html + - title: "All new Scaladoc for Scala 3" + description: "Highlights of new features for Scaladoc" + icon: "fa fa-star" + link: /scala3/scaladoc.html + - title: "Talks" + description: "Talks about Scala 3 that can be watched online" + icon: "fa fa-play-circle" + link: /scala3/talks.html + + - title: "Scala の進化" + links: + - title: "SIP" + description: "Scala Improvement Process（Scala 改善プロセス）。言語とコンパイラの進化（英語のみ）" + icon: "fa fa-cogs" + link: /sips/index.html + - title: "Become a Scala OSS Contributor" + description: "From start to finish: discover how you can help Scala's open-source ecosystem" + icon: "fa fa-code-branch" + link: /contribute/ +--- diff --git a/_ja/overviews/collections/arrays.md b/_ja/overviews/collections/arrays.md index a2b72591d8..883708eb60 100644 --- a/_ja/overviews/collections/arrays.md +++ b/_ja/overviews/collections/arrays.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 配列 - -discourse: false - partof: collections overview-name: Collections @@ -11,7 +8,7 @@ num: 10 language: ja --- -配列 ([`Array`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html)) は Scala のコレクションの中でも特殊なものだ。Scala 配列は、Java の配列と一対一で対応する。どういう事かと言うと、Scala の配列 `Array[Int]` は Java の `int[]` で実装されており、`Array[Double]` は Java の `double[]`、`Array[String]` は Java の `String[]` で実装されている。その一方で、Scala の配列は Java のそれに比べて多くの機能を提供する。まず、Scala の配列は**ジェネリック**であることができる。 つまり、型パラメータか抽象型の `T` に対する `Array[T]` を定義することができる。次に、Scala の配列は Scala の列と互換性があり、`Seq[T]` が期待されている所に `Array[T]` を渡すことができる。さらに、Scala の配列は列の演算の全てをサポートする。以下に具体例で説明する: +配列 ([`Array`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html)) は Scala のコレクションの中でも特殊なものだ。Scala 配列は、Java の配列と一対一で対応する。どういう事かと言うと、Scala の配列 `Array[Int]` は Java の `int[]` で実装されており、`Array[Double]` は Java の `double[]`、`Array[String]` は Java の `String[]` で実装されている。その一方で、Scala の配列は Java のそれに比べて多くの機能を提供する。まず、Scala の配列は**ジェネリック**であることができる。 つまり、型パラメータか抽象型の `T` に対する `Array[T]` を定義することができる。次に、Scala の配列は Scala の列と互換性があり、`Seq[T]` が期待されている所に `Array[T]` を渡すことができる。さらに、Scala の配列は列の演算の全てをサポートする。以下に具体例で説明する: scala> val a1 = Array(1, 2, 3) a1: Array[Int] = Array(1, 2, 3) @@ -81,24 +78,25 @@ Scala 2.8 の設計はより単純なものだ。ほぼ全てのコンパイラ val arr = new Array[T]((arr.length + 1) / 2) ^ -あなたがコンパイラを手伝ってあげて、`evenElems` の型パタメータの実際の型が何であるかの実行時のヒントを提供することが必要とされている。この実行時のヒントは `scala.reflect.ClassManifest` +あなたがコンパイラを手伝ってあげて、`evenElems` の型パタメータの実際の型が何であるかの実行時のヒントを提供することが必要とされている。この実行時のヒントは `scala.reflect.ClassTag` 型の**クラスマニフェスト**という形をとる。クラスマニフェストとは、型の最上位クラスが何であるかを記述する型記述オブジェクトだ。型に関するあらゆる事を記述する `scala.reflect.Manifest` 型の完全マニフェストというものもある。配列の作成にはクラスマニフェストで十分だ。 Scala コンパイラは、指示を出すだけでクラスマニフェストを自動的に構築する。「指示を出す」とは、クラスマニフェストを以下のように暗黙のパラメータ (implicit parameter) として要求することを意味する: - def evenElems[T](xs: Vector[T])(implicit m: ClassManifest[T]): Array[T] = ... + def evenElems[T](xs: Vector[T])(implicit m: ClassTag[T]): Array[T] = ... -**context bound** という、より短い別の構文を使うことで型がクラスマニフェストを連れてくることを要求できる。これは、型の後にコロン (:) とクラス名 `ClassManifest` を付けることを意味する: +**context bound** という、より短い別の構文を使うことで型がクラスマニフェストを連れてくることを要求できる。これは、型の後にコロン (:) とクラス名 `ClassTag` を付けることを意味する: + import scala.reflect.ClassTag // これは動作する - def evenElems[T: ClassManifest](xs: Vector[T]): Array[T] = { + def evenElems[T: ClassTag](xs: Vector[T]): Array[T] = { val arr = new Array[T]((xs.length + 1) / 2) for (i <- 0 until xs.length by 2) arr(i / 2) = xs(i) arr } -2つの `evenElems` の改訂版は全く同じことを意味する。どちらの場合も、`Array[T]` が構築されるときにコンパイラは型パラメータ `T` のクラスマニフェスト、つまり `ClassManifest[T]` 型の暗黙の値 (implicit value)、を検索する。暗黙の値が見つかれば、正しい種類の配列を構築するのにマニフェストが使用される。見つからなければ、その前の例のようにエラーが発生する。 +2つの `evenElems` の改訂版は全く同じことを意味する。どちらの場合も、`Array[T]` が構築されるときにコンパイラは型パラメータ `T` のクラスマニフェスト、つまり `ClassTag[T]` 型の暗黙の値 (implicit value)、を検索する。暗黙の値が見つかれば、正しい種類の配列を構築するのにマニフェストが使用される。見つからなければ、その前の例のようにエラーが発生する。 以下に `evenElems` を使った REPL のやりとりを示す。 @@ -110,15 +108,15 @@ Scala コンパイラは、指示を出すだけでクラスマニフェスト 両者の場合とも、Scala コンパイラは要素型 (`Int`、そして `String`) のクラスマニフェストを自動的に構築して、`evenElems` メソッドの暗黙のパラメータに渡した。コンパイラは全ての具象型についてクラスマニフェストを構築できるが、引数そのものがクラスマニフェストを持たない型パラメータである場合はそれができない。以下に失敗例を示す: scala> def wrap[U](xs: Vector[U]) = evenElems(xs) - :6: error: No ClassManifest available for U. + :6: error: No ClassTag available for U. def wrap[U](xs: Vector[U]) = evenElems(xs) ^ 何が起こったかというと、`evenElems` は型パラメータ `U` に関するクラスマニフェストを要求するが、見つからなかったのだ。当然この場合は、`U` に関する暗黙のクラスマニフェストを要求することで解決するため、以下は成功する: - scala> def wrap[U: ClassManifest](xs: Vector[U]) = evenElems(xs) - wrap: [U](xs: Vector[U])(implicit evidence$1: ClassManifest[U])Array[U] + scala> def wrap[U: ClassTag](xs: Vector[U]) = evenElems(xs) + wrap: [U](xs: Vector[U])(implicit evidence$1: scala.reflect.ClassTag[U])Array[U] -この例から、`U` の定義の context bound 構文は `evidence$1` と呼ばれる `ClassManifest[U]` 型の暗黙のパラメータの略記法であることが分かる。 +この例から、`U` の定義の context bound 構文は `evidence$1` と呼ばれる `ClassTag[U]` 型の暗黙のパラメータの略記法であることが分かる。 -要約すると、ジェネリックな配列の作成はクラスマニフェストを必要とする。型パラメータ `T` の配列を作成する場合、`T` に関する暗黙のクラスマニフェストも提供する必要がある。その最も簡単な方法は、`[T: ClassManifest]` のように、型パラメータを context bound 構文で `ClassManifest` と共に定義することだ。 +要約すると、ジェネリックな配列の作成はクラスマニフェストを必要とする。型パラメータ `T` の配列を作成する場合、`T` に関する暗黙のクラスマニフェストも提供する必要がある。その最も簡単な方法は、`[T: ClassTag]` のように、型パラメータを context bound 構文で `ClassTag` と共に定義することだ。 diff --git a/_ja/overviews/collections/concrete-immutable-collection-classes.md b/_ja/overviews/collections/concrete-immutable-collection-classes.md index 508ca9a227..0a7bcdca65 100644 --- a/_ja/overviews/collections/concrete-immutable-collection-classes.md +++ b/_ja/overviews/collections/concrete-immutable-collection-classes.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 具象不変コレクションクラス - -discourse: false - partof: collections overview-name: Collections @@ -16,7 +13,7 @@ Scala は様々な具象不変コレクションクラス (concrete immutable co ## リスト -リスト ([`List`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/List.html)) は有限の不変列だ。リストは最初の要素とリストの残りの部分に定数時間でアクセスでき、また、新たな要素をリストの先頭に追加する定数時間の cons 演算を持つ。他の多くの演算は線形時間で行われる。 +リスト ([`List`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/List.html)) は有限の不変列だ。リストは最初の要素とリストの残りの部分に定数時間でアクセスでき、また、新たな要素をリストの先頭に追加する定数時間の cons 演算を持つ。他の多くの演算は線形時間で行われる。 リストは Scala プログラミングの働き者であり続けてきたので、あえてここで語るべきことは多くない。Scala 2.8 での大きな変更点は `List` クラスはそのサブクラスである `::` とそのサブオブジェクトである `Nil` とともに、論理的にふさわしい `scala.collection.immutable` パッケージで定義されるようになったことだ。`scala` パッケージには `List`、`Nil`、および `::` へのエイリアスがあるため、ユーザの立場から見ると、リストは今まで通り使うことができる。 @@ -24,7 +21,7 @@ Scala は様々な具象不変コレクションクラス (concrete immutable co ## ストリーム -ストリーム ([`Stream`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Stream.html)) はリストに似ているが、要素は遅延評価される。そのため、ストリームは無限の長さをもつことができる。呼び出された要素のみが計算される。他の点においては、ストリームはリストと同じ性能特性をもつ。 +ストリーム ([`Stream`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Stream.html)) はリストに似ているが、要素は遅延評価される。そのため、ストリームは無限の長さをもつことができる。呼び出された要素のみが計算される。他の点においては、ストリームはリストと同じ性能特性をもつ。 リストは `::` 演算子によって構築されるが、ストリームはそれに似た `#::` 演算子によって構築される。以下は、整数の 1, 2, 3 からなる簡単なストリームの例だ: @@ -52,7 +49,7 @@ Scala は様々な具象不変コレクションクラス (concrete immutable co リストはアルゴリズムが慎重にリストの先頭要素 (`head`) のみを処理する場合、非常に効率的だ。`head` の読み込み、追加、および削除は一定数時間で行われるのに対して、リストの後続の要素に対する読み込みや変更は、その要素の深さに依存した線形時間で実行される。 -ベクトル ([`Vector`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html)) は、ランダムアクセス時の非効率性を解決するために Scala 2.8 から導入された新しいコレクション型だ。ベクトルはどの要素の読み込みも「事実上」定数時間で行う。リストの `head` の読み込みや配列の要素読み込みに比べると大きい定数だが、定数であることには変りない。この結果、ベクトルを使ったアルゴリズムは列の `head` のみを読み込むことに神経質にならなくていい。任意の場所の要素を読み込んだり、変更したりできるため、コードを書くのに便利だ。 +ベクトル ([`Vector`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html)) は、ランダムアクセス時の非効率性を解決するために Scala 2.8 から導入された新しいコレクション型だ。ベクトルはどの要素の読み込みも「事実上」定数時間で行う。リストの `head` の読み込みや配列の要素読み込みに比べると大きい定数だが、定数であることには変りない。この結果、ベクトルを使ったアルゴリズムは列の `head` のみを読み込むことに神経質にならなくていい。任意の場所の要素を読み込んだり、変更したりできるため、コードを書くのに便利だ。 ベクトルは、他の列と同じように作成され、変更される。 @@ -79,14 +76,14 @@ Scala は様々な具象不変コレクションクラス (concrete immutable co 最後の行が示すように、`updated` の呼び出しは元のベクトル `vec` には一切影響しない。読み込みと同様に、ベクトルの関数型更新も「事実上定数時間」で実行される。ベクトルの真ん中にある要素を更新するには、その要素を格納するノードと、木構造の根ノードからを初めとする全ての親ノードをコピーすることによって行われる。これは関数型更新は、32以内の要素か部分木を格納する 1 〜 5個の ノードを作成することを意味する。これは、可変配列の in-place での上書きに比べると、ずっと時間のかかる計算であるが、ベクトル全体をコピーするよりはずっと安いものだ。 -ベクトルは高速なランダム読み込みと高速な関数型更新の丁度いいバランスを取れているため、不変添字付き列 ([`immutable.IndexedSeq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/IndexedSeq.html)) トレイトのデフォルトの実装となっている: +ベクトルは高速なランダム読み込みと高速な関数型更新の丁度いいバランスを取れているため、不変添字付き列 ([`immutable.IndexedSeq`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/IndexedSeq.html)) トレイトのデフォルトの実装となっている: scala> collection.immutable.IndexedSeq(1, 2, 3) res2: scala.collection.immutable.IndexedSeq[Int] = Vector(1, 2, 3) ## 不変スタック -後入れ先出し (LIFO: last in first out) の列が必要ならば、スタック ([`Stack`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Stack.html)) がある。 `push` メソッドを使ってスタックに要素をプッシュ、`pop` を使ってポップ、そして`top` を使って削除することなく一番上の要素を読み込むことができる。これらの演算は、全て定数時間で行われる。 +後入れ先出し (LIFO: last in first out) の列が必要ならば、スタック ([`Stack`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Stack.html)) がある。 `push` メソッドを使ってスタックに要素をプッシュ、`pop` を使ってポップ、そして`top` を使って削除することなく一番上の要素を読み込むことができる。これらの演算は、全て定数時間で行われる。 以下はスタックに対して行われる簡単な演算の例だ: @@ -105,7 +102,7 @@ Scala は様々な具象不変コレクションクラス (concrete immutable co ## 不変キュー -キュー ([`Queue`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Queue.html)) はスタックに似ているが、後入れ先出し (LIFO: last in first out) ではなく、先入れ先出し (FIFO: +キュー ([`Queue`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Queue.html)) はスタックに似ているが、後入れ先出し (LIFO: last in first out) ではなく、先入れ先出し (FIFO: first in first out) だ。 以下に空の不変キューの作り方を示す: @@ -134,7 +131,7 @@ first in first out) だ。 ## 範囲 -範囲 ([`Range`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html)) は順序付けされた等間隔の整数の列だ。例えば、「1、2、3」は範囲であり、「5、8、11、14」も範囲だ。Scala で範囲を作成するには、予め定義された `to` メソッドと `by` メソッドを使う。 +範囲 ([`Range`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html)) は順序付けされた等間隔の整数の列だ。例えば、「1、2、3」は範囲であり、「5、8、11、14」も範囲だ。Scala で範囲を作成するには、予め定義された `to` メソッドと `by` メソッドを使う。 scala> 1 to 3 res2: scala.collection.immutable.Range.Inclusive = Range(1, 2, 3) @@ -150,7 +147,7 @@ first in first out) だ。 ## ハッシュトライ -ハッシュトライは不変集合と不変マップを効率的に実装する標準的な方法だ。ハッシュトライは、[`immutable.HashMap`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/HashMap.html) クラスによりサポートされている。データ構造は、全てのノードに 32個の要素か 32個の部分木があるという意味でベクトルに似ている。しかし、キーの選択はハッシュコードにより行われる。たとえば、マップから任意のキーを検索する場合、まずキーのハッシュコードを計算する。その後、最初の部分木を選択するのにハッシュコードの下位 5ビットが使われ、次の 5ビットで次の部分木が選択される、という具合だ。ノード内の全ての要素が、その階層までで選ばれているビット範囲内でお互いと異なるハッシュコードを持った時点で選択は終了する。 +ハッシュトライは不変集合と不変マップを効率的に実装する標準的な方法だ。ハッシュトライは、[`immutable.HashMap`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/HashMap.html) クラスによりサポートされている。データ構造は、全てのノードに 32個の要素か 32個の部分木があるという意味でベクトルに似ている。しかし、キーの選択はハッシュコードにより行われる。たとえば、マップから任意のキーを検索する場合、まずキーのハッシュコードを計算する。その後、最初の部分木を選択するのにハッシュコードの下位 5ビットが使われ、次の 5ビットで次の部分木が選択される、という具合だ。ノード内の全ての要素が、その階層までで選ばれているビット範囲内でお互いと異なるハッシュコードを持った時点で選択は終了する。 ハッシュトライは、サイズ相応の高速な検索と、相応に効率的な関数型加算 `(+)` と減算 `(-)` の調度良いバランスが取れている。そのため、ハッシュトライは Scala の不変マップと不変集合のデフォルトの実装を支えている。実は、Scala は要素が 5個未満の不変集合と不変マップに関して、更なる最適化をしている。1 〜 4個の要素を持つ集合とセットは、要素 (マップの場合は、キー/値のペア) をフィールドとして持つ単一のオブジェクトとして格納する。空の不変集合と、空の不変マップは、ぞれぞれ単一のオブジェクトである。空の不変集合や不変マップは、空であり続けるため、データ構造を複製する必要はない。 @@ -158,7 +155,7 @@ first in first out) だ。 赤黒木は、ノードが「赤」か「黒」に色付けされている平衡二分木の一種だ。他の平衡二分木と同様に演算は木のサイズのログ時間内に確実に完了する。 -Scala は内部で赤黒木を使った不変集合と不変マップの実装を提供する。[`TreeSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) と [`TreeMap`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeMap.html) クラスがそれだ。 +Scala は内部で赤黒木を使った不変集合と不変マップの実装を提供する。[`TreeSet`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/TreeSet.html) と [`TreeMap`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/TreeMap.html) クラスがそれだ。 scala> scala.collection.immutable.TreeSet.empty[Int] res11: scala.collection.immutable.TreeSet[Int] = TreeSet() @@ -170,7 +167,7 @@ Scala は内部で赤黒木を使った不変集合と不変マップの実装 ## 不変ビット集合 -ビット集合 ([`BitSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/BitSet.html)) は大きい整数のビットを小さな整数のコレクションを使って表す。例えば、3, 2, と 0 を格納するビット集合は二進法で整数の 1101、十進法で 13 を表す。 +ビット集合 ([`BitSet`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/BitSet.html)) は大きい整数のビットを小さな整数のコレクションを使って表す。例えば、3, 2, と 0 を格納するビット集合は二進法で整数の 1101、十進法で 13 を表す。 内部では、ビット集合は 64ビットの `Long` の配列を使っている。配列の最初の `Long` は 整数の 0〜63、二番目は 64〜127 という具合だ。そのため、ビット集合は最大値が数百以下の場合は非常にコンパクトだ。 @@ -187,7 +184,7 @@ Scala は内部で赤黒木を使った不変集合と不変マップの実装 ## リストマップ -リストマップ ([`ListMap`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/ListMap.html)) は、キー/値ペアの連結リスト (linked list) により実装されたマップを表す。一般的に、リストマップの演算はリスト全体を総なめする必要がある可能性がある。そのため、リストマップの演算はマップのサイズに対して線形時間をとる。標準の不変マップの方が常に高速なので Scala のリストマップが使われることはほとんど無い。唯一性能の差が出る可能性としては、マップが何らかの理由でリストの最初の要素が他の要素に比べてずっと頻繁に読み込まれるように構築された場合だ。 +リストマップ ([`ListMap`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/ListMap.html)) は、キー/値ペアの連結リスト (linked list) により実装されたマップを表す。一般的に、リストマップの演算はリスト全体を総なめする必要がある可能性がある。そのため、リストマップの演算はマップのサイズに対して線形時間をとる。標準の不変マップの方が常に高速なので Scala のリストマップが使われることはほとんど無い。唯一性能の差が出る可能性としては、マップが何らかの理由でリストの最初の要素が他の要素に比べてずっと頻繁に読み込まれるように構築された場合だ。 scala> val map = scala.collection.immutable.ListMap(1->"one", 2->"two") map: scala.collection.immutable.ListMap[Int,java.lang.String] = diff --git a/_ja/overviews/collections/concrete-mutable-collection-classes.md b/_ja/overviews/collections/concrete-mutable-collection-classes.md index 4889c7a559..e50b90a9fd 100644 --- a/_ja/overviews/collections/concrete-mutable-collection-classes.md +++ b/_ja/overviews/collections/concrete-mutable-collection-classes.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 具象可変コレクションクラス - -discourse: false - partof: collections overview-name: Collections @@ -16,7 +13,7 @@ Scala が標準ライブラリで提供する不変コレクションで最も ## 配列バッファ -配列バッファ ([`ArrayBuffer`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayBuffer.html)) は、配列とサイズを格納するバッファだ。配列バッファの演算のほとんどは、単に内部の配列にアクセスして変更するだけなので、配列の演算と同じ速さで実行される。また、配列バッファは効率的にデータをバッファの最後に追加できる。配列バッファへの要素の追加はならし定数時間 (amortized constant time) で実行される。よって、配列バッファは要素が常に最後に追加される場合、大きいコレクションを効率的に構築するのに便利だ。 +配列バッファ ([`ArrayBuffer`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ArrayBuffer.html)) は、配列とサイズを格納するバッファだ。配列バッファの演算のほとんどは、単に内部の配列にアクセスして変更するだけなので、配列の演算と同じ速さで実行される。また、配列バッファは効率的にデータをバッファの最後に追加できる。配列バッファへの要素の追加はならし定数時間 (amortized constant time) で実行される。よって、配列バッファは要素が常に最後に追加される場合、大きいコレクションを効率的に構築するのに便利だ。 scala> val buf = scala.collection.mutable.ArrayBuffer.empty[Int] buf: scala.collection.mutable.ArrayBuffer[Int] = ArrayBuffer() @@ -29,7 +26,7 @@ Scala が標準ライブラリで提供する不変コレクションで最も ## リストバッファ -リストバッファ ([`ListBuffer`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ListBuffer.html)) は、内部に配列の代わりに連結リストを使うこと以外は配列バッファに似ている。バッファを構築後にリストに変換する予定なら、配列バッファの代わりにリストバッファを使うべきだ。 +リストバッファ ([`ListBuffer`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ListBuffer.html)) は、内部に配列の代わりに連結リストを使うこと以外は配列バッファに似ている。バッファを構築後にリストに変換する予定なら、配列バッファの代わりにリストバッファを使うべきだ。 scala> val buf = scala.collection.mutable.ListBuffer.empty[Int] buf: scala.collection.mutable.ListBuffer[Int] = ListBuffer() @@ -42,7 +39,7 @@ Scala が標準ライブラリで提供する不変コレクションで最も ## 文字列ビルダ -配列バッファが配列を構築するのに便利で、リストバッファがリストを構築するのに便利なように、文字列ビルダ ([`StringBuilder`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html)) は文字列を構築するのに便利なものだ。文字列ビルダはあまりに頻繁に使われるため、デフォルトの名前空間に既にインポートされている。以下のように、単に `new StringBuilder` で文字列ビルダを作成することができる: +配列バッファが配列を構築するのに便利で、リストバッファがリストを構築するのに便利なように、文字列ビルダ ([`StringBuilder`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/StringBuilder.html)) は文字列を構築するのに便利なものだ。文字列ビルダはあまりに頻繁に使われるため、デフォルトの名前空間に既にインポートされている。以下のように、単に `new StringBuilder` で文字列ビルダを作成することができる: scala> val buf = new StringBuilder buf: StringBuilder = @@ -55,19 +52,19 @@ Scala が標準ライブラリで提供する不変コレクションで最も ## 連結リスト -連結リスト ([`LinkedList`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/LinkedList.html)) は、`next` ポインタにより連結されたノードから成る可変列だ。多くの言語では空の連結リストを表すのに `null` が選ばれるが、空の列も全ての列演算をサポートする必要があるため、Scala のコレクションでは `null` は都合が悪い。特に、`LinkedList.empty.isEmpty` は `true` を返すべきで、`NullPointerException` を発生させるべきではない。 代わりに、空の連結リストは `next` フィールドがノード自身を指すという特殊な方法で表現されている。不変リスト同様、連結リストは順列通りに探索するのに適している。また、連結リストは要素や他の連結リストを簡単に挿入できるように実装されている。 +連結リスト ([`LinkedList`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/LinkedList.html)) は、`next` ポインタにより連結されたノードから成る可変列だ。多くの言語では空の連結リストを表すのに `null` が選ばれるが、空の列も全ての列演算をサポートする必要があるため、Scala のコレクションでは `null` は都合が悪い。特に、`LinkedList.empty.isEmpty` は `true` を返すべきで、`NullPointerException` を発生させるべきではない。 代わりに、空の連結リストは `next` フィールドがノード自身を指すという特殊な方法で表現されている。不変リスト同様、連結リストは順列通りに探索するのに適している。また、連結リストは要素や他の連結リストを簡単に挿入できるように実装されている。 ## 双方向リスト -双方向リスト ([`DoubleLinkedList`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/DoubleLinkedList.html)) は、`next` の他に、現ノードの一つ前の要素を指す `prev` +双方向リスト ([`DoubleLinkedList`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/DoubleLinkedList.html)) は、`next` の他に、現ノードの一つ前の要素を指す `prev` というもう一つの可変フィールドがあることを除けば、単方向の連結リストに似ている。リンクが一つ増えたことで要素の削除が非常に高速になる。 ## 可変リスト -可変リスト ([`MutableList`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/MutableList.html)) は単方向連結リストとリスト終端の空ノードを参照するポインタから構成される。これにより、リストの最後への要素の追加が、終端ノードのためにリスト全体を探索しなくてよくなるため、定数時間の演算となる。[`MutableList`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/MutableList.html) は、現在 Scala の [`mutable.LinearSeq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/LinearSeq.html) トレイトの標準実装だ。 +可変リスト ([`MutableList`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/MutableList.html)) は単方向連結リストとリスト終端の空ノードを参照するポインタから構成される。これにより、リストの最後への要素の追加が、終端ノードのためにリスト全体を探索しなくてよくなるため、定数時間の演算となる。[`MutableList`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/MutableList.html) は、現在 Scala の [`mutable.LinearSeq`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/LinearSeq.html) トレイトの標準実装だ。 ## キュー -Scala は不変キューの他に可変キュー ([`mutable.Queue`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/Queue.html)) も提供する。可変キューは不変のものと同じように使えるが、`enqueue` の代わりに `+=` と `++=` 演算子を使って加算する。また、可変キューの `dequeue` は先頭の要素を削除して、それを返す。次に具体例で説明する: +Scala は不変キューの他に可変キュー ([`mutable.Queue`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/Queue.html)) も提供する。可変キューは不変のものと同じように使えるが、`enqueue` の代わりに `+=` と `++=` 演算子を使って加算する。また、可変キューの `dequeue` は先頭の要素を削除して、それを返す。次に具体例で説明する: scala> val queue = new scala.collection.mutable.Queue[String] queue: scala.collection.mutable.Queue[String] = Queue() @@ -84,13 +81,13 @@ Scala は不変キューの他に可変キュー ([`mutable.Queue`](http://www.s ## 配列シーケンス -配列シーケンス ([`ArraySeq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArraySeq.html)) は、内部で要素を `Array[Object]` に格納する固定長の可変列だ。 +配列シーケンス ([`ArraySeq`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ArraySeq.html)) は、内部で要素を `Array[Object]` に格納する固定長の可変列だ。 -典型的には、配列の性能特性が欲しいが、要素の型が特定できず、実行時に `ClassManifest` も無く、ジェネリックな列を作成したい場合に [`ArraySeq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArraySeq.html) を使う。この問題は後ほど[配列の節](arrays.html)で説明する。 +典型的には、配列の性能特性が欲しいが、要素の型が特定できず、実行時に `ClassTag` も無く、ジェネリックな列を作成したい場合に [`ArraySeq`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ArraySeq.html) を使う。この問題は後ほど[配列の節](arrays.html)で説明する。 ## スタック -既に不変スタックについては説明した。スタックには、[`mutable.Stack`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/Stack.html) クラスにより実装される可変バージョンもある。変更が上書き処理されるという違いの他は、不変バージョンと全く同じように動作する。 +既に不変スタックについては説明した。スタックには、[`mutable.Stack`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/Stack.html) クラスにより実装される可変バージョンもある。変更が上書き処理されるという違いの他は、不変バージョンと全く同じように動作する。 scala> val stack = new scala.collection.mutable.Stack[Int] stack: scala.collection.mutable.Stack[Int] = Stack() @@ -113,11 +110,11 @@ Scala は不変キューの他に可変キュー ([`mutable.Queue`](http://www.s ## 配列スタック -配列スタック ([`ArrayStack`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayStack.html) ) は、内部に必要に応じて大きさを変えた `Array` を使った、可変スタックの代替実装だ。配列スタックは、高速な添字読み込みを提供し、他の演算に関しても普通の可変スタックに比べて少し効率的だ。 +配列スタック ([`ArrayStack`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ArrayStack.html) ) は、内部に必要に応じて大きさを変えた `Array` を使った、可変スタックの代替実装だ。配列スタックは、高速な添字読み込みを提供し、他の演算に関しても普通の可変スタックに比べて少し効率的だ。 ## ハッシュテーブル -ハッシュテーブルは、内部で要素を配列に格納し、要素の位置はハッシュコードにより決められる。ハッシュテーブルへの要素の追加は、既に配列の中に同じハッシュコードを持つ他の要素が無い限り、定数時間で行われる。そのため、ハッシュコードの分布が適度である限り非常に高速だ。結果として、Scala の可変マップと可変集合のデフォルトの実装はハッシュテーブルに基づいており、[`mutable.HashSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashSet.html) クラスと [`mutable.HashMap`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashMap.html) クラスから直接アクセスできる。 +ハッシュテーブルは、内部で要素を配列に格納し、要素の位置はハッシュコードにより決められる。ハッシュテーブルへの要素の追加は、既に配列の中に同じハッシュコードを持つ他の要素が無い限り、定数時間で行われる。そのため、ハッシュコードの分布が適度である限り非常に高速だ。結果として、Scala の可変マップと可変集合のデフォルトの実装はハッシュテーブルに基づいており、[`mutable.HashSet`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/HashSet.html) クラスと [`mutable.HashMap`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/HashMap.html) クラスから直接アクセスできる。 ハッシュ集合とハッシュマップは他の集合やマップと変りなく使うことができる。以下に具体例で説明する: @@ -136,11 +133,11 @@ Scala は不変キューの他に可変キュー ([`mutable.Queue`](http://www.s ## ウィークハッシュマップ -ウィークハッシュマップ（[`WeakHashMap`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/WeakHashMap.html)) は、ガーベッジコレクタがマップから「弱キー」への参照を追跡しないという特殊なハッシュマップだ。他にキーを参照するものが無くなると、キーとその関連する値はマップから勝手にいなくなる。ウィークハッシュマップは、キーに対する時間のかかる計算結果を再利用するキャッシュのような用途に向いている。キーとその計算結果が普通のハッシュマップに格納された場合、そのマップは限りなく大きくなり続け、キーはガベージコレクタに永遠に回収されない。ウィークハッシュマップを使うことでこの問題を回避できる。キーオブジェクトが到達不可能になり次第、そのエントリーごとウィークハッシュマップから削除される。Scala のウィークハッシュマップは、Java による実装 `java.util.WeakHashMap` のラッパーである [`WeakHashMap`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/WeakHashMap.html) クラスにより実装されている。 +ウィークハッシュマップ（[`WeakHashMap`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/WeakHashMap.html)) は、ガーベッジコレクタがマップから「弱キー」への参照を追跡しないという特殊なハッシュマップだ。他にキーを参照するものが無くなると、キーとその関連する値はマップから勝手にいなくなる。ウィークハッシュマップは、キーに対する時間のかかる計算結果を再利用するキャッシュのような用途に向いている。キーとその計算結果が普通のハッシュマップに格納された場合、そのマップは限りなく大きくなり続け、キーはガベージコレクタに永遠に回収されない。ウィークハッシュマップを使うことでこの問題を回避できる。キーオブジェクトが到達不可能になり次第、そのエントリーごとウィークハッシュマップから削除される。Scala のウィークハッシュマップは、Java による実装 `java.util.WeakHashMap` のラッパーである [`WeakHashMap`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/WeakHashMap.html) クラスにより実装されている。 ## 並行マップ -並行マップ (`ConcurrentMap`) は複数のスレッドから同時にアクセスすることできる。通常の[マップ](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html)の演算の他に、以下のアトミックな演算を提供する: +並行マップ (`ConcurrentMap`) は複数のスレッドから同時にアクセスすることできる。通常の[マップ](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Map.html)の演算の他に、以下のアトミックな演算を提供する: ### ConcurrentMap クラスの演算 ### @@ -156,7 +153,7 @@ Scala は不変キューの他に可変キュー ([`mutable.Queue`](http://www.s ## 可変ビット集合 -可変ビット集合 ([`mutable.BitSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/BitSet.html)) は、変更が上書き処理される他は不変のものとほとんど同じだ。可変ビット集合は、変更しなかった `Long` をコピーしなくても済むぶん不変ビット集合に比べて少し効率的だ。 +可変ビット集合 ([`mutable.BitSet`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/BitSet.html)) は、変更が上書き処理される他は不変のものとほとんど同じだ。可変ビット集合は、変更しなかった `Long` をコピーしなくても済むぶん不変ビット集合に比べて少し効率的だ。 scala> val bits = scala.collection.mutable.BitSet.empty bits: scala.collection.mutable.BitSet = BitSet() diff --git a/_ja/overviews/collections/conversions-between-java-and-scala-collections.md b/_ja/overviews/collections/conversions-between-java-and-scala-collections.md index 3de4df0782..052b6db2e3 100644 --- a/_ja/overviews/collections/conversions-between-java-and-scala-collections.md +++ b/_ja/overviews/collections/conversions-between-java-and-scala-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Java と Scala 間のコレクションの変換 - -discourse: false - partof: collections overview-name: Collections @@ -15,7 +12,7 @@ language: ja Scala と同様に、Java にも豊富なコレクションライブラリがある。両者には多くの共通点がある。例えば、両方のライブラリともイテレータ、`Iterable`、集合、マップ、そして列を提供する。しかし、両者には重要な違いもある。特に、Scala では不変コレクションに要点を置き、コレクションを別のものに変換する演算も多く提供している。 -時として、コレクションを一方のフレームワークから他方へと渡す必要がある。例えば、既存の Java のコレクションを Scala のコレクションであるかのようにアクセスしたいこともあるだろう。もしくは、Scala のコレクションを Java のコレクションを期待している Java メソッドに渡したいと思うかもしれない。Scala は [JavaConverters](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) オブジェクトにより主要なコレクション間の暗黙の変換を提供するため、簡単に相互運用できる。特に以下の型に関しては、双方向変換を提供する。 +時として、コレクションを一方のフレームワークから他方へと渡す必要がある。例えば、既存の Java のコレクションを Scala のコレクションであるかのようにアクセスしたいこともあるだろう。もしくは、Scala のコレクションを Java のコレクションを期待している Java メソッドに渡したいと思うかもしれない。Scala は [JavaConverters](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) オブジェクトにより主要なコレクション間の暗黙の変換を提供するため、簡単に相互運用できる。特に以下の型に関しては、双方向変換を提供する。 Iterator <=> java.util.Iterator Iterator <=> java.util.Enumeration @@ -26,7 +23,7 @@ Scala と同様に、Java mutable.Map <=> java.util.Map mutable.ConcurrentMap <=> java.util.concurrent.ConcurrentMap -このような変換を作動させるには、[JavaConverters](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) オブジェクトからインポートするだけでいい: +このような変換を作動させるには、[JavaConverters](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) オブジェクトからインポートするだけでいい: scala> import collection.JavaConverters._ import collection.JavaConverters._ @@ -47,11 +44,11 @@ Scala と同様に、Java 他の Scala コレクションも Java に変換できるが、元の Scala 型には逆変換できない。それらは以下の通り: Seq => java.util.List - mutable.Seq => java.utl.List + mutable.Seq => java.util.List Set => java.util.Set Map => java.util.Map -Java は可変コレクションと不変コレクションを型で区別しないため、例えば `scala.immutable.List` からの変換は、上書き演算を呼び出すと `UnsupportedOperationException` を発生する `java.util.List` を返す。次に具体例で説明する: +Java は可変コレクションと不変コレクションを型で区別しないため、例えば `scala.immutable.List` からの変換は、上書き演算を呼び出すと `UnsupportedOperationException` が発生する `java.util.List` を返す。次に具体例で説明する: scala> val jul = List(1, 2, 3).asJava jul: java.util.List[Int] = [1, 2, 3] diff --git a/_ja/overviews/collections/creating-collections-from-scratch.md b/_ja/overviews/collections/creating-collections-from-scratch.md index 4544c56457..0b96900988 100644 --- a/_ja/overviews/collections/creating-collections-from-scratch.md +++ b/_ja/overviews/collections/creating-collections-from-scratch.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: コレクションの作成 - -discourse: false - partof: collections overview-name: Collections diff --git a/_ja/overviews/collections/equality.md b/_ja/overviews/collections/equality.md index 6f68fb5d90..628711de07 100644 --- a/_ja/overviews/collections/equality.md +++ b/_ja/overviews/collections/equality.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 等価性 - -discourse: false - partof: collections overview-name: Collections diff --git a/_ja/overviews/collections/introduction.md b/_ja/overviews/collections/introduction.md index af4a2bf5ee..4c1c037ec4 100644 --- a/_ja/overviews/collections/introduction.md +++ b/_ja/overviews/collections/introduction.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: はじめに - -discourse: false - partof: collections overview-name: Collections diff --git a/_ja/overviews/collections/iterators.md b/_ja/overviews/collections/iterators.md index 4c2b700761..4435171d24 100644 --- a/_ja/overviews/collections/iterators.md +++ b/_ja/overviews/collections/iterators.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: イテレータ - -discourse: false - partof: collections overview-name: Collections @@ -12,7 +9,7 @@ num: 15 language: ja --- -イテレータ ([`Iterator`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html)) はコレクションではなく、コレクションから要素を1つづつアクセスするための方法だ。イテレータ `it` に対する基本的な演算として `next` と `hasNext` の2つがある。 `it.next()` を呼び出すことで、次の要素が返り、イテレータの内部状態が前進する。よって、同じイテレータに対して `next` を再び呼び出すと、前回返したものの次の要素が得られる。返す要素が無くなると、`next` の呼び出しは `NoSuchElementException` を発生させる。返す要素が残っているかは [`Iterator`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html) の `hasNext` メソッドを使って調べることができる。 +イテレータ ([`Iterator`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html)) はコレクションではなく、コレクションから要素を1つづつアクセスするための方法だ。イテレータ `it` に対する基本的な演算として `next` と `hasNext` の2つがある。 `it.next()` を呼び出すことで、次の要素が返り、イテレータの内部状態が前進する。よって、同じイテレータに対して `next` を再び呼び出すと、前回返したものの次の要素が得られる。返す要素が無くなると、`next` の呼び出しは `NoSuchElementException` を発生させる。返す要素が残っているかは [`Iterator`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html) の `hasNext` メソッドを使って調べることができる。 イテレータ `it` が返す全ての要素を渡り歩くのに最も率直な方法は while ループを使うことだ: @@ -64,7 +61,7 @@ language: ja への呼び出しはイテレータ `it` と全く同じ要素を返すイテレータを**2つ**返す。この2つのイテレータは独立して作動するため、片方を前進しても他方は影響を受けない。一方、元のイテレータ `it` は `duplicate` により終端まで前進したため、使いものにならない。 要約すると、イテレータは**メソッドを呼び出した後、絶対にアクセスしなければ**コレクションのように振る舞う。Scala -コレクションライブラリは、[`Traversable`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Traversable.html) と [`Iterator`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html) に共通の親クラスである [`TraversableOnce`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/TraversableOnce.html) を提供することで、明示的にこれを示す。名前が示す通り、 `TraversableOnce` は `foreach` を用いて一度だけ探索することができるが、探索後のそのオブジェクトの状態は指定されていない。`TraversableOnce` オブジェクトが `Iterator` ならば、探索後はその終端にあるし、もし `Traversable` ならば、そのオブジェクトは今まで通り存在する。 `TraversableOnce` のよく使われる事例としては、イテレータか `Traversable` を受け取ることができるメソッドの引数の型だ。その例として、 `Traversable` クラスの追加メソッド `++` がある。`TraversableOnce` パラメータを受け取るため、イテレータか `Traversable` なコレクションの要素を追加することができる。 +コレクションライブラリは、[`Traversable`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html) と [`Iterator`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html) に共通の親クラスである [`TraversableOnce`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/TraversableOnce.html) を提供することで、明示的にこれを示す。名前が示す通り、 `TraversableOnce` は `foreach` を用いて一度だけ探索することができるが、探索後のそのオブジェクトの状態は指定されていない。`TraversableOnce` オブジェクトが `Iterator` ならば、探索後はその終端にあるし、もし `Traversable` ならば、そのオブジェクトは今まで通り存在する。 `TraversableOnce` のよく使われる事例としては、イテレータか `Traversable` を受け取ることができるメソッドの引数の型だ。その例として、 `Traversable` クラスの追加メソッド `++` がある。`TraversableOnce` パラメータを受け取るため、イテレータか `Traversable` なコレクションの要素を追加することができる。 イテレータの全演算は次の表にまとめられている。 @@ -158,7 +155,7 @@ language: ja しかし、このコードを慎重に見ると間違っていることが分かるはずだ。コードは確かに先頭の空白文字列の続きを読み飛ばすが、`it` は最初の非空白文字列も追い越してしまっているのだ。 -この問題はバッファ付きイテレータを使うことで解決できる。[`BufferedIterator`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BufferedIterator.html) トレイトは、`head` というメソッドを追加で提供する [`Iterator`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html) の子トレイトだ。バッファ付きイテレータに対して `head` を呼び出すことで、イテレータを前進させずに最初の要素を返すことができる。バッファ付きイテレータを使うと、空白文字列を読み飛ばすのは以下のように書ける。 +この問題はバッファ付きイテレータを使うことで解決できる。[`BufferedIterator`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/BufferedIterator.html) トレイトは、`head` というメソッドを追加で提供する [`Iterator`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html) の子トレイトだ。バッファ付きイテレータに対して `head` を呼び出すことで、イテレータを前進させずに最初の要素を返すことができる。バッファ付きイテレータを使うと、空白文字列を読み飛ばすのは以下のように書ける。 def skipEmptyWords(it: BufferedIterator[String]) = while (it.head.isEmpty) { it.next() } diff --git a/_ja/overviews/collections/maps.md b/_ja/overviews/collections/maps.md index c824f55b8d..f0f4a3f7a7 100644 --- a/_ja/overviews/collections/maps.md +++ b/_ja/overviews/collections/maps.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: マップ - -discourse: false - partof: collections overview-name: Collections @@ -12,7 +9,7 @@ num: 7 language: ja --- -マップ ([`Map`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html)) はキーと値により構成されるペアの [`Iterable`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) の一種で、**写像** (mapping) や**関連** (association) とも呼ばれる。Scala の [`Predef`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/Predef$.html) クラスは、ペアの `(key, value)` を `key -> value` と書けるような暗黙の変換を提供する。例えば、`Map("x" -> 24, "y" -> 25, "z" -> 26)` は `Map(("x", 24), ("y", 25), ("z", 26))` と全く同じことを意味するがより可読性が高い。 +マップ ([`Map`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html)) はキーと値により構成されるペアの [`Iterable`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) の一種で、**写像** (mapping) や**関連** (association) とも呼ばれる。Scala の [`Predef`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/Predef$.html) クラスは、ペアの `(key, value)` を `key -> value` と書けるような暗黙の変換を提供する。例えば、`Map("x" -> 24, "y" -> 25, "z" -> 26)` は `Map(("x", 24), ("y", 25), ("z", 26))` と全く同じことを意味するがより可読性が高い。 マップの基本的な演算は集合のものと似ている。それらは、以下の表にまとめられており、以下のカテゴリーに分類できる: @@ -51,7 +48,7 @@ language: ja | `ms filterKeys p` |キーが条件関数 `p` を満たす `ms`内の写像のみを含むマップのビュー。| | `ms mapValues f` |`ms`内のキーに関連付けられた全ての値に関数 `f` を適用して得られるマップのビュー。| -可変マップ ([`mutable.Map`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/Map.html)) は他にも以下の表にまとめた演算をサポートする。 +可変マップ ([`mutable.Map`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/Map.html)) は他にも以下の表にまとめた演算をサポートする。 ### mutable.Map トレイトの演算 ### diff --git a/_ja/overviews/collections/migrating-from-scala-27.md b/_ja/overviews/collections/migrating-from-scala-27.md index f8464de499..50dbed9723 100644 --- a/_ja/overviews/collections/migrating-from-scala-27.md +++ b/_ja/overviews/collections/migrating-from-scala-27.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Scala 2.7 からの移行 - -discourse: false - partof: collections overview-name: Collections @@ -40,7 +37,7 @@ language: ja 旧ライブラリより完全に置き換えられ、廃止予定警告を出すのが無理だったものが 2つある。 -1. 以前の `scala.collection.jcl` パッケージは撤廃された。 このパッケージは Scala 上で Java コレクションライブラリの設計を真似しようとしたが、それは多くの対称性を壊してしまった。Java コレクションが欲しい人の多くは `jcl` を飛ばして `java.util` を直接使用していた。Scala 2.8 は、`jcl` パッケージの代わりに、[`JavaConversions`](conversions-between-java-and-scala-collections.html) オブジェクトにて両方のライブラリ間の自動変換機構を提供する。 +1. 以前の `scala.collection.jcl` パッケージは撤廃された。 このパッケージは Scala 上で Java コレクションライブラリの設計を真似しようとしたが、それは多くの対称性を壊してしまった。Java コレクションが欲しい人の多くは `jcl` を飛ばして `java.util` を直接使用していた。Scala 2.8 は、`jcl` パッケージの代わりに、[`JavaConversions`](conversions-between-java-and-scala-collections.html) オブジェクトにて両方のライブラリ間の自動変換機構を提供する。 2. 投射 (projection) は一般化され、きれいにされ、現在はビューとして提供される。投射はほとんど使われていなかったようなので、この変更に影響を受けるコードは少ないはずだ。 よって、`jcl` か投射を使っている場合は多少コードの書き換えが必要になるかもしれない。 diff --git a/_ja/overviews/collections/overview.md b/_ja/overviews/collections/overview.md index 8cdae22a13..5a6dacd1e0 100644 --- a/_ja/overviews/collections/overview.md +++ b/_ja/overviews/collections/overview.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 可変コレクションおよび不変コレクション - -discourse: false - partof: collections overview-name: Collections @@ -22,8 +19,8 @@ Scala のコレクションは、体系的に可変および不変コレクシ `scala.collection.mutable` パッケージのコレクションは、コレクションを上書き変更する演算がある。 だから可変コレクションを扱うということは、どのコードが、何時どのコレクションを変更したのかということを理解する必要があることを意味する。 -`scala.collection` パッケージのコレクションは、可変か不変かのどちらでもありうる。例えば [`collection.IndexedSeq[T]`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html) -は、[`collection.immutable.IndexedSeq[T]`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/IndexedSeq.html) と [`collection.mutable.IndexedSeq[T]`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/IndexedSeq.html) 両方の親クラスだ。一般的に、`scala.collection`パッケージの基底コレクションは不変コレクションと同じインターフェイスを定義し、`scala.collection.mutable` パッケージ内の可変コレクションは、副作用を伴う変更演算を不変インターフェイスに加える。 +`scala.collection` パッケージのコレクションは、可変か不変かのどちらでもありうる。例えば [`collection.IndexedSeq[T]`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/IndexedSeq.html) +は、[`collection.immutable.IndexedSeq[T]`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/IndexedSeq.html) と [`collection.mutable.IndexedSeq[T]`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/IndexedSeq.html) 両方の親クラスだ。一般的に、`scala.collection`パッケージの基底コレクションは不変コレクションと同じインターフェイスを定義し、`scala.collection.mutable` パッケージ内の可変コレクションは、副作用を伴う変更演算を不変インターフェイスに加える。 基底コレクションと不変コレクションの違いは、不変なコレクションのクライアントは、他の誰もコレクションを変更しないという保証があるのに対し、基底コレクションのクライアントは自分ではコレクションを変更しなかったという約束しかできない。たとえ静的な型がコレクションを変更するような演算を提供していなくても、実行時の型は他のクライアントが手を加えることができる可変コレクションである可能性がある。 @@ -40,7 +37,7 @@ Scala のコレクションは、体系的に可変および不変コレクシ このパッケージには、コレクションを実装するための基本的なパーツが含まれている。 コレクションクラスがいくつかの演算を `generic` 内のクラスに委譲することはよくあるが、 フレームワークのユーザーが `generic` 内のクラスが必要になることは普通はありえない。 -利便性と後方互換性のために、いくつかの重要な型は `scala` パッケージ内に別名を定義してあるため、インポート無しで単純な名前でコレクションを使うことができる。[`List`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/List.html) 型が良い例で、以下の名前でもアクセスすることができる +利便性と後方互換性のために、いくつかの重要な型は `scala` パッケージ内に別名を定義してあるため、インポート無しで単純な名前でコレクションを使うことができる。[`List`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/List.html) 型が良い例で、以下の名前でもアクセスすることができる scala.collection.immutable.List // 定義元 scala.List // scala パッケージのエイリアス経由 @@ -48,22 +45,24 @@ Scala のコレクションは、体系的に可変および不変コレクシ // 常に自動的にインポートされるため エイリアスされているその他の型は次のとおり: -[`Traversable`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Traversable.html)、[`Iterable`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html)、[`Seq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Seq.html)、[`IndexedSeq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html)、[`Iterator`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html)、[`Stream`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Stream.html)、[`Vector`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html)、[`StringBuilder`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html)、[`Range`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html)。 +[`Traversable`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html)、[`Iterable`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterable.html)、[`Seq`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Seq.html)、[`IndexedSeq`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/IndexedSeq.html)、[`Iterator`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html)、[`Stream`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Stream.html)、[`Vector`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html)、[`StringBuilder`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/StringBuilder.html)、[`Range`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html)。 次の図は `scala.collection` パッケージ内の全てのコレクションを示す。 これらはすべて、高レベルの抽象クラスやトレイトで一般に可変と不変の両方の実装を持っている。 -[]({{ site.baseurl }}/resources/images/collections.png) +[![General collection hierarchy][1]][1] 次の図は `scala.collection.immutable` パッケージ内の全てのコレクションを示す。 -[]({{ site.baseurl }}/resources/images/collections.immutable.png) +[![Immutable collection hierarchy][2]][2] そして、次の図は `scala.collection.mutable` パッケージ内の全てのコレクションを示す。 -[]({{ site.baseurl }}/resources/images/collections.mutable.png) +[![Mutable collection hierarchy][3]][3] + +図の凡例: -(以上三つ全ての図は decodified.com の Matthias によって生成された。) +[![Graph legend][4]][4] ## コレクションAPIの概要 @@ -102,3 +101,9 @@ Scala のコレクションは、体系的に可変および不変コレクシ 唯一の例外は、可変コレクションにのみ存在する `Buffer` トレイトだ。 これより、これらのクラスを一つずつ見ていく。 + + + [1]: /resources/images/tour/collections-diagram.svg + [2]: /resources/images/tour/collections-immutable-diagram.svg + [3]: /resources/images/tour/collections-mutable-diagram.svg + [4]: /resources/images/tour/collections-legend-diagram.svg diff --git a/_ja/overviews/collections/performance-characteristics.md b/_ja/overviews/collections/performance-characteristics.md index d8fecb85ba..c9a19ab8a2 100644 --- a/_ja/overviews/collections/performance-characteristics.md +++ b/_ja/overviews/collections/performance-characteristics.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 性能特性 - -discourse: false - partof: collections overview-name: Collections diff --git a/_ja/overviews/collections/seqs.md b/_ja/overviews/collections/seqs.md index d9b392365a..85e80da053 100644 --- a/_ja/overviews/collections/seqs.md +++ b/_ja/overviews/collections/seqs.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 列トレイト Seq、IndexedSeq、および LinearSeq - -discourse: false - partof: collections overview-name: Collections @@ -12,7 +9,7 @@ num: 5 language: ja --- -列 ([`Seq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Seq.html)) トレイトは、長さ (`length`) があり、それぞれの要素に `0` から数えられた固定された添字 (index) がある `Iterable` の一種だ。 +列 ([`Seq`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Seq.html)) トレイトは、長さ (`length`) があり、それぞれの要素に `0` から数えられた固定された添字 (index) がある `Iterable` の一種だ。 以下の表にまとめられた列の演算は以下のカテゴリーに分けることができる: @@ -75,7 +72,7 @@ Scala の他の構文の例にならって、`seq(idx) = elem` は `seq.update(i | `xs union ys` |和集合; `xs ++ ys` に同じ| | `xs.distinct` |`xs` の部分列で要素の重複を一切含まないもの。 | -[`Seq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Seq.html) トレイトには [`LinearSeq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html) と [`IndexedSeq`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html) +[`Seq`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Seq.html) トレイトには [`LinearSeq`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html) と [`IndexedSeq`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html) という二つの子トレイトがある。 これらは新しい演算を定義しないが、それぞれ異なった性能特性をもつ。 線形列 (linear sequence) は効率的な `head` と `tail` 演算を持ち、一方添字付き列 (indexed sequence) は効率的な`apply`、`length`、および (可変の場合) `update` 演算を持つ。 diff --git a/_ja/overviews/collections/sets.md b/_ja/overviews/collections/sets.md index 816cb61ef6..47e7a40b62 100644 --- a/_ja/overviews/collections/sets.md +++ b/_ja/overviews/collections/sets.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 集合 - -discourse: false - partof: collections overview-name: Collections @@ -12,7 +9,7 @@ num: 6 language: ja --- -集合 ([`Set`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Set.html)) は要素の重複の無い `Iterable` だ。集合一般に定義される演算は次の表にまとめてあり、可変集合に関してはその次の表も見てほしい。これらの演算は以下のカテゴリーに分類される: +集合 ([`Set`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Set.html)) は要素の重複の無い `Iterable` だ。集合一般に定義される演算は次の表にまとめてあり、可変集合に関してはその次の表も見てほしい。これらの演算は以下のカテゴリーに分類される: * **条件演算**である `contains`、`apply`、`subsetOf`。`contains` メソッドは集合が任意の要素を含むかを調べる。集合での `apply` メソッドは `contains` と同じであるため、`set(elem)` は `set contains elem` と同じだ。これは集合が要素を含んでいれば `true` を返す関数として使えることを意味する。 @@ -107,7 +104,7 @@ language: ja 可変集合は `+=` と `-=` の別形として `add` と `remove` を提供する。違いは `add` と `remove` は集合に対して演算の効果があったかどうかを示す `Boolean` の戻り値を返すことだ。 -現在の可変集合のデフォルトの実装では要素を格納するのにハッシュテーブルを使っている。不変集合のデフォルトの実装は集合の要素数に応じて方法を変えている。空集合はシングルトンで表される。サイズが4つまでの集合は全要素をフィールドとして持つオブジェクトとして表される。それを超えたサイズの不変集合は[ハッシュトライ]()として表される。 +現在の可変集合のデフォルトの実装では要素を格納するのにハッシュテーブルを使っている。不変集合のデフォルトの実装は集合の要素数に応じて方法を変えている。空集合はシングルトンで表される。サイズが4つまでの集合は全要素をフィールドとして持つオブジェクトとして表される。それを超えたサイズの不変集合は[ハッシュトライ](concrete-immutable-collection-classes.html)として表される。 このような設計方針のため、(例えば 4以下の) 小さいサイズの集合を使う場合は、通常の場合、可変集合に比べて不変集合の方が、よりコンパクトで効率的だ。集合のサイズが小さいと思われる場合は、不変集合を試してみてはいかがだろうか。 @@ -115,10 +112,10 @@ language: ja ### 整列済み集合 ### -整列済み集合は ([`SortedSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/SortedSet.html)) -は (集合の作成時に指定された) 任意の順序で要素を (`iterator` や `foreach` を使って) 返す事ができる集合だ。[`SortedSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/SortedSet.html) クラスのデフォルトの表現は、左の子ツリー内の全ての要素が右の子ツリーの全ての要素よりも小さいという恒常条件を満たす順序付けされた二分木だ。これにより、通りがけ順 (in-order) で探索するだけで、木の全ての要素を昇順に返すことができる。Scala の[`immutable.TreeSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) クラスは **赤黒木** を使ってこの恒常条件を実装している。また、この木構造は、**平衡木**であり、ルートから全て葉のまでの長さの違いは最大で1要素しかない。 +整列済み集合は ([`SortedSet`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/SortedSet.html)) +は (集合の作成時に指定された) 任意の順序で要素を (`iterator` や `foreach` を使って) 返す事ができる集合だ。[`SortedSet`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/SortedSet.html) クラスのデフォルトの表現は、左の子ツリー内の全ての要素が右の子ツリーの全ての要素よりも小さいという恒常条件を満たす順序付けされた二分木だ。これにより、通りがけ順 (in-order) で探索するだけで、木の全ての要素を昇順に返すことができる。Scala の[`immutable.TreeSet`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) クラスは **赤黒木** を使ってこの恒常条件を実装している。また、この木構造は、**平衡木**であり、ルートから全て葉のまでの長さの違いは最大で1要素しかない。 -空の [`TreeSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) を作成するには、まず順序付けを指定する: +空の [`TreeSet`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) を作成するには、まず順序付けを指定する: scala> val myOrdering = Ordering.fromLessThan[String](_ > _) myOrdering: scala.math.Ordering[String] = ... @@ -148,6 +145,6 @@ language: ja ### ビット集合 ### -ビット集合 ([`BitSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BitSet.html)) は非負整数の要素の集合で、何ワードかのパックされたビットにより実装されている。[`BitSet`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BitSet.html) クラスは、内部で `Long` の配列を用いている。最初の `Long` は第0 〜 63 の要素を受け持ち、次のは第64 〜 127 の要素という具合だ。全ての `Long` の、それぞれの 64ビットは、対応する要素が集合に含まれる場合は 1 にセットされ、含まれない場合は 0 になる。このため、ビット集合のサイズは格納されている整数の最大値に依存する。`N` がその最大の整数値の場合、集合のサイズは `N/64` `Long` ワード、または `N/8` バイト、にステータス情報のためのバイトを追加したものだ。 +ビット集合 ([`BitSet`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BitSet.html)) は非負整数の要素の集合で、何ワードかのパックされたビットにより実装されている。[`BitSet`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BitSet.html) クラスは、内部で `Long` の配列を用いている。最初の `Long` は第0 〜 63 の要素を受け持ち、次のは第64 〜 127 の要素という具合だ。全ての `Long` の、それぞれの 64ビットは、対応する要素が集合に含まれる場合は 1 にセットされ、含まれない場合は 0 になる。このため、ビット集合のサイズは格納されている整数の最大値に依存する。`N` がその最大の整数値の場合、集合のサイズは `N/64` `Long` ワード、または `N/8` バイト、にステータス情報のためのバイトを追加したものだ。 このため、たくさんの小さい要素を含む場合、ビット集合は他の集合に比べてコンパクトである。ビット集合のもう一つの利点は `contains` を使った所属判定や、`+=` や `-=` を使った要素の追加や削除が非常に効率的であることだ。 diff --git a/_ja/overviews/collections/strings.md b/_ja/overviews/collections/strings.md index e605c099f9..1872aa602c 100644 --- a/_ja/overviews/collections/strings.md +++ b/_ja/overviews/collections/strings.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 文字列 - -discourse: false - partof: collections overview-name: Collections diff --git a/_ja/overviews/collections/trait-iterable.md b/_ja/overviews/collections/trait-iterable.md index 8b63926456..8d9aefc87b 100644 --- a/_ja/overviews/collections/trait-iterable.md +++ b/_ja/overviews/collections/trait-iterable.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Iterable トレイト - -discourse: false - partof: collections overview-name: Collections @@ -12,7 +9,7 @@ num: 4 language: ja --- -反復可能 ([`Iterable`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) トレイトはコレクション階層の上から2番目に位置する。このトレイトの全メソッドは、コレクション内の要素を1つずつ返す抽象メソッド `iterator` に基づいている。`Iterable` では、`Traversable` トレイトの `foreach` メソッドも `iterator`に基づいて実装されている。以下が実際の実装だ: +反復可能 ([`Iterable`](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) トレイトはコレクション階層の上から2番目に位置する。このトレイトの全メソッドは、コレクション内の要素を1つずつ返す抽象メソッド `iterator` に基づいている。`Iterable` では、`Traversable` トレイトの `foreach` メソッドも `iterator`に基づいて実装されている。以下が実際の実装だ: def foreach[U](f: Elem => U): Unit = { val it = iterator diff --git a/_ja/overviews/collections/trait-traversable.md b/_ja/overviews/collections/trait-traversable.md index eed29ac4de..2131d792a0 100644 --- a/_ja/overviews/collections/trait-traversable.md +++ b/_ja/overviews/collections/trait-traversable.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Traversable トレイト - -discourse: false - partof: collections overview-name: Collections @@ -12,7 +9,7 @@ num: 3 language: ja --- -走査可能 ([`Traversable`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Traversable.html))トレイトはコレクション階層の最上位に位置する。訳注: 木構造などでノードを一つづつ走査することを traverse と言う。また、-able で終わるトレイトは名詞としても使われるため、「走査可能なもの」という意味だ。 `Traversable` の抽象的な演算は `foreach` のみだ: +走査可能 ([`Traversable`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html))トレイトはコレクション階層の最上位に位置する。訳注: 木構造などでノードを一つづつ走査することを traverse と言う。また、-able で終わるトレイトは名詞としても使われるため、「走査可能なもの」という意味だ。 `Traversable` の抽象的な演算は `foreach` のみだ: def foreach[U](f: Elem => U) @@ -52,7 +49,7 @@ language: ja | **抽象メソッド:** | | | `xs foreach f` |`xs` 内の全ての要素に対して関数 `f` を実行する。 | | **加算:** | | -| `xs ++ ys` |`xs` と `ys` の両方の要素から成るコレクション。 `ys` は [`TraversableOnce`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/TraversableOnce.html) なコレクション、つまり [`Traversable`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Traversable.html) または [`Iterator`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html) だ。| +| `xs ++ ys` |`xs` と `ys` の両方の要素から成るコレクション。 `ys` は [`TraversableOnce`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/TraversableOnce.html) なコレクション、つまり [`Traversable`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html) または [`Iterator`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html) だ。| | **map 演算:** | | | `xs map f` |`xs` 内の全ての要素に関数 `f` を適用することによって得られるコレクション。| | `xs flatMap f` |`xs` 内の全ての要素に対してコレクション値を返す関数 `f` を適用し、その結果を連結したコレクション。| @@ -99,7 +96,7 @@ language: ja | **要素条件演算:** | | | `xs forall p` |`xs` 内の全ての要素に条件関数 `p` が当てはまるかを示す Boolean 値。| | `xs exists p` |`xs` 内に条件関数 `p` を満たす要素があるかどうかを示す Boolean 値。| -| `xs count p` |`xs` 内の要素で条件関数 `p` 満たすものの数。| +| `xs count p` |`xs` 内の要素で条件関数 `p` を満たすものの数。| | **fold 演算:** | | | `(z /: xs)(op)` |`z` から始めて、左から右へと `xs` 内の隣接する要素に二項演算 `op` を次々と適用したもの。| | `(xs :\ z)(op)` |`z` から始めて、右から左へと `xs` 内の隣接する要素に二項演算 `op` を次々と適用したもの。| diff --git a/_ja/overviews/collections/views.md b/_ja/overviews/collections/views.md index 650858d07e..69e851d6d4 100644 --- a/_ja/overviews/collections/views.md +++ b/_ja/overviews/collections/views.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: ビュー - -discourse: false - partof: collections overview-name: Collections diff --git a/_ja/overviews/core/futures.md b/_ja/overviews/core/futures.md index 11b88dcda3..1d0575a723 100644 --- a/_ja/overviews/core/futures.md +++ b/_ja/overviews/core/futures.md @@ -5,8 +5,6 @@ title: Future と Promise partof: futures language: ja - -discourse: false --- **Philipp Haller, Aleksandar Prokopec, Heather Miller, Viktor Klang, Roland Kuhn, Vojin Jovanovic 著**
    @@ -141,43 +139,19 @@ Future の実装の多くは、Future の結果を知りたくなったクライ } `onComplete` メソッドは、Future 計算の失敗と成功の両方の結果を扱えるため、汎用性が高い。 -成功した結果のみ扱う場合は、(部分関数を受け取る) `onSuccess` コールバックを使う: +成功した結果のみ扱う場合は、`foreach` コールバックを使う: val f: Future[List[String]] = Future { session.getRecentPosts } - f onSuccess { - case posts => for (post <- posts) println(post) + f foreach { posts => + for (post <- posts) println(post) } -失敗した結果のみ扱う場合は、`onFailure` コールバックを使う: - - val f: Future[List[String]] = Future { - session.getRecentPosts - } - - f onFailure { - case t => println("エラーが発生した: " + t.getMessage) - } - - f onSuccess { - case posts => for (post <- posts) println(post) - } - -`onFalure` コールバックは Future が失敗した場合、つまりそれが例外を保持する場合のみ実行される。 - -部分関数は `isDefinedAt` メソッドを持つため、`onFailure` メソッドはコールバックが特定の `Throwable` に対して定義されている場合のみ発火される。 -以下の例では、登録された `onFailure` コールバックは発火されない: - - val f = Future { - 2 / 0 - } - - f onFailure { - case npe: NullPointerException => - println("これが表示されているとしたらビックリ。") - } +`Future` は、失敗した結果のみを処理する方法を提供していて、 +`Failure[Throwable]` を `Success[Throwable]` へと変換する `failed` 投射を用いることができる。 +詳細は以下の投射を参照。 キーワードの初出の位置を検索する例に戻ると、キーワードの位置を画面に表示したいかもしれない: @@ -186,15 +160,12 @@ Future の実装の多くは、Future の結果を知りたくなったクライ source.toSeq.indexOfSlice("myKeyword") } - firstOccurence onSuccess { - case idx => println("キーワードの初出位置: " + idx) - } - - firstOccurence onFailure { - case t => println("ファイルの処理に失敗した: " + t.getMessage) + firstOccurence oncomplete { + case Success(idx) => println("キーワードの初出位置: " + idx) + case Failure(t) => println("処理失敗：" + t.getMessage) } -`onComplete`、`onSuccess`、および `onFailure` メソッドは全て `Unit` 型を返すため、これらの呼び出しを連鎖させることができない。 +`onComplete`、および `foreach` メソッドは全て `Unit` 型を返すため、これらの呼び出しを連鎖させることができない。 これは意図的な設計で、連鎖された呼び出しが登録されたコールバックの実行の順序を暗示しないようにしている (同じ Future に登録されたコールバックは順不同に発火される)。 @@ -214,12 +185,12 @@ Future 内の値が利用可能となることを必要とするため、Future "na" * 16 + "BATMAN!!!" } - text onSuccess { - case txt => totalA += txt.count(_ == 'a') + text.foreach { txt => + totalA += txt.count(_ == 'a') } - text onSuccess { - case txt => totalA += txt.count(_ == 'A') + text.foreach { txt => + totalA += txt.count(_ == 'A') } 2つのコールバックが順次に実行された場合は、変数 `totalA` は期待される値 `18` を持つ。 @@ -234,7 +205,7 @@ Future 内の値が利用可能となることを必要とするため、Future
    1. Future に onComplete コールバックを登録することで、対応するクロージャが Future が完了した後に eventually に実行されることが保証される。
      2. -
    2. onSuccess や onFailure コールバックを登録することは onComplete と同じ意味論を持つ。ただし、クロージャがそれぞれ成功したか失敗した場合のみに呼ばれるという違いがある。
      3. +
    3. foreach コールバックを登録することは onComplete と同じ意味論を持つ。ただし、クロージャがそれぞれ成功したか失敗した場合のみに呼ばれるという違いがある。
    4. 既に完了した Future にコールバックを登録することは (1 により) コールバックが eventually に実行されることとなる。
      5. @@ -259,33 +230,32 @@ Future 内の値が利用可能となることを必要とするため、Future connection.getCurrentValue(USD) } - rateQuote onSuccess { case quote => + for (quote <- rateQuote) { val purchase = Future { if (isProfitable(quote)) connection.buy(amount, quote) else throw new Exception("有益ではない") } - purchase onSuccess { - case _ => println(amount + " USD を購入した") - } + for (amount <- purchase) + println(amount + " USD を購入した") } まずは現在の為替相場を取得する `rateQuote` という `Future` を作る。 この値がサーバから取得できて Future が成功した場合は、計算は -`onSuccess` コールバックに進み、ここで買うかどうかの決断をすることができる。 +`foreach` コールバックに進み、ここで買うかどうかの決断をすることができる。 ここでもう 1つの Future である `purchase` を作って、有利な場合のみ買う決定をしてリクエストを送信する。 最後に、`purchase` が完了すると、通知メッセージを標準出力に表示する。 これは動作するが、2つの理由により不便だ。 -第一に、`onSuccess` を使わなくてはいけなくて、2つ目の Future である +第一に、`foreach` を使わなくてはいけなくて、2つ目の Future である `purchase` をその中に入れ子にする必要があることだ。 例えば `purchase` が完了した後に別の貨幣を売却したいとする。 -それはまた `onSuccess` の中でこのパターンを繰り返すことになり、インデントしすぎで理解しづらく肥大化したコードとなる。 +それはまた `foreach` の中でこのパターンを繰り返すことになり、インデントしすぎで理解しづらく肥大化したコードとなる。 -第二に、`purchase` は他のコードのスコープ外にあり、`onSuccess` +第二に、`purchase` は他のコードのスコープ外にあり、`foreach` コールバック内においてのみ操作することができる。 そのため、アプリケーションの他の部分は `purchase` を見ることができず、他の貨幣を売るために別の -`onSuccess` コールバックを登録することもできない。 +`foreach` コールバックを登録することもできない。 これらの 2つの理由から Future はより自然な合成を行うコンビネータを提供する。 基本的なコンビネータの 1つが `map` で、これは与えられた Future @@ -303,11 +273,11 @@ Future の投射はコレクションの投射と同様に考えることがで else throw new Exception("有益ではない") } - purchase onSuccess { - case _ => println(amount + " USD を購入した") + purchase.foreach { amount => + println(amount + " USD を購入した") } -`rateQuote` に対して `map` を使うことで `onSuccess` コールバックを一切使わないようになった。 +`rateQuote` に対して `map` を使うことで `foreach` コールバックを一切使わないようになった。 それと、より重要なのが入れ子が無くなったことだ。 ここで他の貨幣を売却したいと思えば、`purchase` に再び `map` するだけでいい。 @@ -323,7 +293,7 @@ Future の投射はコレクションの投射と同様に考えることがで この例外を伝搬させる意味論は他のコンビネータにおいても同様だ。 Future の設計指針の 1つは for 内包表記から利用できるようにすることだった。 -このため、Future は `flatMap`、`filter` そして `foreach` コンビネータを持つ。 +このため、Future は `flatMap` そして `withFilter` コンビネータを持つ。 `flatMap` メソッドは値を新しい Future `g` に投射する関数を受け取り、`g` が完了したときに完了する新たな Future を返す。 @@ -340,8 +310,8 @@ Future の設計指針の 1つは for 内包表記から利用できるように if isProfitable(usd, chf) } yield connection.buy(amount, chf) - purchase onSuccess { - case _ => println(amount + " CHF を購入した") + purchase foreach { _ => + println(amount + " CHF を購入した") } この `purchase` は `usdQuote` と `chfQuote` が完了した場合のみ完了する。 @@ -372,10 +342,6 @@ Future に関しては、`filter` の呼び出しは `withFilter` の呼び出 `collect` と `filter` コンビネータの関係はコレクション API におけるこれらのメソッドの関係に似ている。 -`foreach` コンビネータで注意しなければいけないのは値が利用可能となった場合に走査するのにブロックしないということだ。 -かわりに、`foreach` のための関数は Future が成功した場合のみ非同期に実行される。 -そのため、`foreach` は `onSuccess` コールバックと全く同じ意味を持つ。 - `Future` トレイトは概念的に (計算結果と例外という) 2つの型の値を保持することができるため、例外処理のためのコンビネータが必要となる。 `rateQuote` に基いて何らかの額を買うとする。 @@ -420,7 +386,7 @@ Future は同じ `Throwable` とともに失敗する。 val anyQuote = usdQuote fallbackTo chfQuote - anyQuote onSuccess { println(_) } + anyQuote foreach { println(_) } `andThen` コンビネータは副作用の目的のためだけに用いられる。 これは、成功したか失敗したかに関わらず現在の Future と全く同一の結果を返す新たな Future を作成する。 @@ -456,12 +422,18 @@ Future は同じ `Throwable` とともに失敗する。 } for (exc <- f.failed) println(exc) +上の例での for 内包表記は以下のように書き換えることができる: + + f.failed.foreach( exc => println(exc)) + +`f` が失敗したため、クロージャは新規に成功値を持つ `Future[Throwable]` の +`foreach` コールバックに登録される。 以下の例は画面に何も表示しない: - val f = Future { + val g = Future { 4 / 2 } - for (exc <- f.failed) println(exc) + for (exc <- g.failed) println(exc) diff --git a/_ja/overviews/macros/annotations.md b/_ja/overviews/macros/annotations.md index e609a667be..652caad33a 100644 --- a/_ja/overviews/macros/annotations.md +++ b/_ja/overviews/macros/annotations.md @@ -2,8 +2,6 @@ layout: multipage-overview language: ja -discourse: false - partof: macros overview-name: Macros diff --git a/_ja/overviews/macros/blackbox-whitebox.md b/_ja/overviews/macros/blackbox-whitebox.md index 13dcfcd921..30e582f473 100644 --- a/_ja/overviews/macros/blackbox-whitebox.md +++ b/_ja/overviews/macros/blackbox-whitebox.md @@ -2,8 +2,6 @@ layout: multipage-overview language: ja -discourse: false - partof: macros overview-name: Macros @@ -25,7 +23,7 @@ Scala 2.11.x および Scala 2.12.x 系列では、マクロ機能が blackbox エコシステムにおけるマクロがあまりにも速く重要なものとなってきているため、Scala 2.10 が実験的機能としてリリースされた数カ月後の Scala 言語チームの会議の中では、Scala 2.12 までにはマクロを標準化して Scala 言語の一人前の機能とすることが決定された。 -追記 Scala 2.12 までにマクロを安定化させるのはそう生易しいことでは無いことが分かった。この調査を受けて、Scala でメタプログラミングを行うための新たな基盤となる [scala.meta](http://scalameta.org) が生まれ、Scala 2.12 リリースと同時に最初のベータ版を出すことを目指している。これが将来の Scala に入ることになるかもしれない。今の所は、Scala 2.12 ではマクロやリフレクション関連の変更は予定されていない。全機能が Scala 2.10 と 2.11 同様に実験的機能扱いのままで、機能が削除されることもない。本稿が書かれた背景となった状況は変わったが、書かれた内容はまだ生きているのでこのまま読み進んでほしい。 +追記 Scala 2.12 までにマクロを安定化させるのはそう生易しいことでは無いことが分かった。この調査を受けて、Scala でメタプログラミングを行うための新たな基盤となる [scala.meta](https://scalameta.org) が生まれ、Scala 2.12 リリースと同時に最初のベータ版を出すことを目指している。これが将来の Scala に入ることになるかもしれない。今の所は、Scala 2.12 ではマクロやリフレクション関連の変更は予定されていない。全機能が Scala 2.10 と 2.11 同様に実験的機能扱いのままで、機能が削除されることもない。本稿が書かれた背景となった状況は変わったが、書かれた内容はまだ生きているのでこのまま読み進んでほしい。 マクロには多くの種類があるため、それぞれを注意深く調べて、どれを標準に入れるのかを厳選することを決めた。評価するときに必然として出てきた疑問がいくつかある。何故マクロ機能はこれほどまでに成功したのか? マクロが使われる理由は何か? @@ -33,9 +31,9 @@ Scala 2.11.x および Scala 2.12.x 系列では、マクロ機能が blackbox ## blackbox と whitebox マクロ -しかし、ときとして def マクロは「ただのメソッド呼び出し」という概念を超越することがある。例えば、展開されたマクロは、元のマクロの戻り値の型よりも特化された型を持つ式を返すことが可能だ。Scala 2.10 では、StackOverflow の [Static return type of Scala macros](http://stackoverflow.com/questions/13669974/static-return-type-of-scala-macros) で解説したように、そのような展開は特化された型を保持し続けることができる。 +しかし、ときとして def マクロは「ただのメソッド呼び出し」という概念を超越することがある。例えば、展開されたマクロは、元のマクロの戻り値の型よりも特化された型を持つ式を返すことが可能だ。Scala 2.10 では、StackOverflow の [Static return type of Scala macros](https://stackoverflow.com/questions/13669974/static-return-type-of-scala-macros) で解説したように、そのような展開は特化された型を保持し続けることができる。 -この興味深い機能がもたらす柔軟性によって、[偽装型プロバイダ](http://meta.plasm.us/posts/2013/07/11/fake-type-providers-part-2/)、[具現化の拡張](/sips/source-locations.html)、[関数従属性の具現化](/ja/overviews/macros/implicits.html#fundep_materialization)、抽出子マクロなどを可能とするけども、書かれたコードの明確さ (人にとってもマシンにとっても) が犠牲になるという側面がある。 +この興味深い機能がもたらす柔軟性によって、[偽装型プロバイダ](https://meta.plasm.us/posts/2013/07/11/fake-type-providers-part-2/)、[具現化の拡張](https://github.com/scala/improvement-proposals/pull/18)、[関数従属性の具現化](/ja/overviews/macros/implicits.html#関数従属性の具現化)、抽出子マクロなどを可能とするけども、書かれたコードの明確さ (人にとってもマシンにとっても) が犠牲になるという側面がある。 普通のメソッド同様に振る舞うマクロと戻り値の型を細別化 (refine) するマクロという決定的な区別を明確にするために、blackbox マクロと whitebox マクロという概念を導入することにした。型シグネチャに忠実に従うマクロは、振る舞いを理解するのに実装を知る必要が無い (ブラックボックスとして扱うことができる) ため、**blackbox マクロ** (blackbox macro) と呼ぶ。 Scala の型システムを使ってシグネチャを持つことができないマクロは **whitebox マクロ** (whitebox macro) と呼ぶ。(whitebox def マクロもシグネチャは持つが、これらのシグネチャは近似値でしかない) @@ -50,9 +48,9 @@ blackbox マクロと whitebox マクロの両方とも大切なことは認識 blackbox def マクロは Scala 2.10 の def マクロと異なる扱いとなる。Scala の型検査において以下の制限が加わる: -1. blackbox マクロが構文木 `x` に展開するとき、展開される式は型注釈 `(x: T)` でラップされる。この `T` は blackbox マクロの宣言された戻り値の型に、マクロ適用時に一貫性を持つように型引数やパス依存性を適用したものとなる。これによって、blackbox マクロを[型プロバイダ](http://meta.plasm.us/posts/2013/07/11/fake-type-providers-part-2/)のための手段としての利用は無効となる。 -1. Scala の型推論アルゴリズムが終わった後でも blackbox マクロの適用に未決定の型パラメータが残る場合、これらの型パラメータは普通のメソッドと同様に強制的に型推論が実行される。これによって blackbox マクロから型推論に影響を与えることが不可能となり、[関数従属性の具現化](/ja/overviews/macros/implicits.html#fundep_materialization)に使うことが無効となる。 -1. blackbox マクロの適用が implicit の候補として使われる場合、implicit 検索がそのマクロを選択するまでは展開は実行されない。これによって [implicit マクロの入手可能性を動的に計算する](/sips/source-locations.html)ことが無効となる。 +1. blackbox マクロが構文木 `x` に展開するとき、展開される式は型注釈 `(x: T)` でラップされる。この `T` は blackbox マクロの宣言された戻り値の型に、マクロ適用時に一貫性を持つように型引数やパス依存性を適用したものとなる。これによって、blackbox マクロを[型プロバイダ](https://meta.plasm.us/posts/2013/07/11/fake-type-providers-part-2/)のための手段としての利用は無効となる。 +1. Scala の型推論アルゴリズムが終わった後でも blackbox マクロの適用に未決定の型パラメータが残る場合、これらの型パラメータは普通のメソッドと同様に強制的に型推論が実行される。これによって blackbox マクロから型推論に影響を与えることが不可能となり、[関数従属性の具現化](/ja/overviews/macros/implicits.html#関数従属性の具現化)に使うことが無効となる。 +1. blackbox マクロの適用が implicit の候補として使われる場合、implicit 検索がそのマクロを選択するまでは展開は実行されない。これによって [implicit マクロの入手可能性を動的に計算する](https://github.com/scala/improvement-proposals/pull/18)ことが無効となる。 1. blackbox マクロの適用がパターンマッチの抽出子として使われる場合、無条件でコンパイラエラーを発生するようにして、マクロで実装されたパターンマッチングのカスタマイズを無効となる。 whitebox def マクロは Scala 2.10 での def マクロ同様に動作する。一切の制限が無いため、2.10 のマクロで出来ていたことの全てが 2.11 と 2.12 でも行えるはずだ。 diff --git a/_ja/overviews/macros/bundles.md b/_ja/overviews/macros/bundles.md index 3748fadc9d..b2c4809533 100644 --- a/_ja/overviews/macros/bundles.md +++ b/_ja/overviews/macros/bundles.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - partof: macros overview-name: Macros @@ -24,7 +21,7 @@ Scala 2.10.x においてマクロ実装は関数として表されている。
      1. 関数に制限されることで複雑なマクロのモジュール化がしづらくなる。マクロのロジックがマクロ実装外のヘルパートレイトに集中していて、マクロ実装がヘルパーをインスタンス化するだけのラッパーになってしまっているのは典型的な例だ。
        2. -
      2. さらに、マクロのパラメータがマクロのコンテキストにパス依存であるため、ヘルパーと実装をつなぐのに特殊なおまじないを必要とする。
        3. +
      3. さらに、マクロのパラメータがマクロのコンテキストにパス依存であるため、ヘルパーと実装をつなぐのに特殊なおまじないを必要とする。
      マクロバンドルは、マクロ実装を diff --git a/_ja/overviews/macros/extractors.md b/_ja/overviews/macros/extractors.md index f8f0d4d683..da0c5b9593 100644 --- a/_ja/overviews/macros/extractors.md +++ b/_ja/overviews/macros/extractors.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - partof: macros overview-name: Macros diff --git a/_ja/overviews/macros/implicits.md b/_ja/overviews/macros/implicits.md index 27f0cd430b..9119b0a5a3 100644 --- a/_ja/overviews/macros/implicits.md +++ b/_ja/overviews/macros/implicits.md @@ -2,8 +2,6 @@ layout: multipage-overview language: ja -discourse: false - partof: macros overview-name: Macros @@ -63,7 +61,7 @@ implicit マクロの拡張の 1つである関数従属性の具現化 (fundep このユースケースに限ると実行時リフレクションを用いて実装することができるが、リフレクションは往々にして型消去のために不正確すぎるか、オーバーヘッドのために遅すぎることが多い。 -Lars Hupel 氏が紹介した [`TypeClass` 型クラステクニック](http://typelevel.org/blog/2013/06/24/deriving-instances-1.html)のような型レベルプログラミングに基づいたジェネリックプログラミングという方法もあるが、やはりこれも手書きの型クラスのインスタンスに比べると性能が劣化するのが現状だ。 +Lars Hupel 氏が紹介した [`TypeClass` 型クラステクニック](https://typelevel.org/blog/2013/06/24/deriving-instances-1.html)のような型レベルプログラミングに基づいたジェネリックプログラミングという方法もあるが、やはりこれも手書きの型クラスのインスタンスに比べると性能が劣化するのが現状だ。 ### implicit の具現化 @@ -88,7 +86,6 @@ Scala implicit の標準機能である複数のパラメータや重複した この場合、必須のインスタンスである `Showable[Int]` は先に定義した具現化マクロによって生成される。つまり、マクロを implicit にすることで型クラスインスタンスの具現化を自動化すると同時にマクロを使わない implicit もシームレスに統合することができる。 -  ## 関数従属性の具現化 diff --git a/_ja/overviews/macros/inference.md b/_ja/overviews/macros/inference.md index af477dff8c..5ee7b9ee93 100644 --- a/_ja/overviews/macros/inference.md +++ b/_ja/overviews/macros/inference.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - title: 型推論補助マクロ --- EXPERIMENTAL diff --git a/_ja/overviews/macros/overview.md b/_ja/overviews/macros/overview.md index adb6eb4105..ff18d7f2b6 100644 --- a/_ja/overviews/macros/overview.md +++ b/_ja/overviews/macros/overview.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - partof: macros overview-name: Macros @@ -132,7 +129,7 @@ def マクロ機能の一部が、徹底した仕様が書かれることを条 val Literal(Constant(s_format: String)) = format.tree 典型的なマクロは Scala のコードを表す AST (抽象構文木) を作成する必要がある。(このマクロも例に漏れない) -Scala コードの生成については[リフレクションの概要](http://docs.scala-lang.org/ja/overviews/reflection/overview.html)を参照してほしい。AST の作成の他に以下のコードは型の操作も行う。 +Scala コードの生成については[リフレクションの概要](https://docs.scala-lang.org/ja/overviews/reflection/overview.html)を参照してほしい。AST の作成の他に以下のコードは型の操作も行う。 `Int` と `String` に対応する Scala 型をどうやって取得しているのかに注目してほしい。 リンクしたリフレクションの概要で型の操作の詳細を説明する。 コード生成の最終ステップでは、全ての生成されたコードを `Block` へと組み合わせる。 @@ -217,7 +214,6 @@ Scala コードの生成については[リフレクションの概要](http://d このシナリオは前節で説明したとおりだ。つまり、マクロとそれを使用するコードを別に呼び出した `scalac` によってコンパイルすることで、全てうまくいくはずだ。REPL をつかっているなら、さらに都合がいい。なぜなら REPL はそれぞれの行を独立したコンパイルとして扱うため、マクロを定義してすぐに使うことができる。 -  ### Maven か sbt を用いてマクロを使う 本稿での具体例では最もシンプルなコマンドラインのコンパイルを使っているが、マクロは Maven や sbt などのビルドツールからも使うことができる。完結した具体例としては [https://github.com/scalamacros/sbt-example](https://github.com/scalamacros/sbt-example) か [https://github.com/scalamacros/maven-example](https://github.com/scalamacros/maven-example) を見てほしいが、要点は以下の 2点だ: @@ -324,7 +320,6 @@ Scala コードの生成については[リフレクションの概要](http://d [SI-6910](https://issues.scala-lang.org/browse/SI-6910) に記述されているとおり、現時点ではある位置から複数の警告やエラーの報告はサポートされていないことに注意してほしい。そのため、ある位置で最初のエラーか警告だけが報告され他は失くなってしまう。(ただし、同じ位置で後から報告されてもエラーは警告よりも優先される) -  ### より大きなマクロを書く マクロ実装が実装メソッドの本文におさまりきらなくなって、モジュール化の必要性が出てくると、コンテキストパラメータを渡して回る必要があることに気付くだろう。マクロを定義するのに必要なもののほとんどがこのコンテキストにパス依存しているからだ。 diff --git a/_ja/overviews/macros/paradise.md b/_ja/overviews/macros/paradise.md index 47fdd6d83f..5fd8e5de7d 100644 --- a/_ja/overviews/macros/paradise.md +++ b/_ja/overviews/macros/paradise.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - partof: macros overview-name: Macros @@ -22,7 +19,7 @@ title: マクロパラダイス マクロパラダイス (Macro paradise) とは Scala の複数のバージョンをサポートするコンパイラプラグインで、一般向けにリリースされている scalac と共に正しく動作するように設計されている。 これによって、将来の Scala に取り込まれるよりもいち早く最新のマクロ機能を使えるようになっている。 [サポートされている機能とバージョンの一覧](/ja/overviews/macros/roadmap.html))に関してはロードマップページを、 -動作の保証に関しては[マクロパラダイスのアナウンスメント](http://scalamacros.org/news/2013/08/07/roadmap-for-macro-paradise.html)を参照してほしい。 +動作の保証に関しては[マクロパラダイスのアナウンスメント](hxxps://scalamacros.org/news/2013/08/07/roadmap-for-macro-paradise.html)を参照してほしい。 ~/210x $ scalac -Xplugin:paradise_*.jar -Xshow-phases phase name id description @@ -38,13 +35,13 @@ title: マクロパラダイス 詳細は[機能の一覧を](/ja/overviews/macros/roadmap.html)参照。 具体例に関しては [https://github.com/scalamacros/sbt-example-paradise](https://github.com/scalamacros/sbt-example-paradise) を参照してほしいが、要点をまとめると、マクロパラダイスを使うには以下の二行をビルド定義に加えるだけでいい -(すでに[sbt を使っている](/ja/overviews/macros/overview.html#using_macros_with_maven_or_sbt)ことが前提だが): +(すでに[sbt を使っている](/ja/overviews/macros/overview.html#maven-か-sbt-を用いてマクロを使う)ことが前提だが): resolvers += Resolver.sonatypeRepo("releases") addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.0-M4" cross CrossVersion.full) -マクロパラダイスを Maven から利用するには、Stack Overflow の [Enabling the macro-paradise Scala compiler plugin in Maven projects](http://stackoverflow.com/questions/19086241/enabling-the-macro-paradise-scala-compiler-plugin-in-maven-projects) に書かれた手順に従ってほしい。 +マクロパラダイスを Maven から利用するには、Stack Overflow の [Enabling the macro-paradise Scala compiler plugin in Maven projects](https://stackoverflow.com/questions/19086241/enabling-the-macro-paradise-scala-compiler-plugin-in-maven-projects) に書かれた手順に従ってほしい。 (Sonatype snapshots と `scala-reflect.jar` への依存性を追加することにも注意) diff --git a/_ja/overviews/macros/quasiquotes.md b/_ja/overviews/macros/quasiquotes.md index 80a155847b..e6f35a90ce 100644 --- a/_ja/overviews/macros/quasiquotes.md +++ b/_ja/overviews/macros/quasiquotes.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - partof: macros overview-name: Macros diff --git a/_ja/overviews/macros/roadmap.md b/_ja/overviews/macros/roadmap.md index 4a8c7d471d..9300672ba6 100644 --- a/_ja/overviews/macros/roadmap.md +++ b/_ja/overviews/macros/roadmap.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - partof: macros overview-name: Macros @@ -20,7 +17,7 @@ title: ロードマップ 今の所、Scala 2.12 におけるリフレクションおよびマクロ関連の新機能の導入の予定は無いため、 バグ修正や安定化を除けば Scala 2.12 とパラダイス 2.12 の機能は Scala 2.11 とパラダイス 2.11 と同じものとなる。 -機能的には、目下労力をさいているのは [scala.meta](http://scalameta.org) だ。 +機能的には、目下労力をさいているのは [scala.meta](https://scalameta.org) だ。 これは Scala のメタプログラミングの新しい土台となるもので、現行の `scala.reflect` ベースのものに比べて、よりシンプルに、堅固になり、移植性にも適したものとなる予定だ。 いつの日か scala.meta が scala.reflect を置き換えて、Scala におけるメタプログラミングの新標準となることを目指している。 @@ -30,7 +27,7 @@ title: ロードマップ | [def マクロ](/ja/overviews/macros/overview.html) | Yes | Yes 1 | Yes | Yes 1 | Yes | Yes 1 | | [マクロバンドル](/ja/overviews/macros/bundles.html) | No | No 1 | Yes | Yes 1 | Yes | Yes 1 | | [implicit マクロ](/ja/overviews/macros/implicits.html) | Yes (since 2.10.2) | Yes 1 | Yes | Yes 1 | Yes | Yes 1 | -| [関数従属性の具現化](/ja/overviews/macros/implicits.html#fundep_materialization) | No | Yes 2 | Yes | Yes 1 | Yes | Yes 1 | +| [関数従属性の具現化](/ja/overviews/macros/implicits.html#関数従属性の具現化) | No | Yes 2 | Yes | Yes 1 | Yes | Yes 1 | | [型プロバイダ](/ja/overviews/macros/typeproviders.html) | 一部サポート (see docs) | Yes 2 | 一部サポート (see docs) | Yes 2 | 一部サポート (see docs) | Yes 2 | | 準クォート | No | Yes 1 | Yes | Yes 1 | Yes | Yes 1 | | [型マクロ](/ja/overviews/macros/typemacros.html) | No | No | No | No | No | No | diff --git a/_ja/overviews/macros/typemacros.md b/_ja/overviews/macros/typemacros.md index 8a99b8d47e..0ed863eb80 100644 --- a/_ja/overviews/macros/typemacros.md +++ b/_ja/overviews/macros/typemacros.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - title: 型マクロ --- OBSOLETE @@ -12,7 +9,7 @@ title: 型マクロ **Eugene Yokota 訳** 型マクロ (type macro) は[マクロパラダイス](/ja/overviews/macros/paradise.html)の以前のバージョンから利用可能だったが、マクロパラダイス 2.0 ではサポートされなくなった。 -[the paradise 2.0 announcement](http://scalamacros.org/news/2013/08/05/macro-paradise-2.0.0-snapshot.html) に説明と移行のための戦略が書かれている。 +[the paradise 2.0 announcement](hxxps://scalamacros.org/news/2013/08/05/macro-paradise-2.0.0-snapshot.html) に説明と移行のための戦略が書かれている。 ## 直観 @@ -26,7 +23,7 @@ def マクロがコンパイラが特定をメソッドの呼び出しを見つ Db.Coffees.update(brazilian.copy(price = 10)) println(Db.Coffees.all) -`H2Db` マクロの完全なソースコードは [GitHub にて](https://github.com/xeno-by/typemacros-h2db)提供して、本稿では重要な点だけをかいつまんで説明する。まず、マクロは、コンパイル時にデータベースに接続することで静的に型付けされたデータベースのラッパーを生成する。(構文木の生成に関しては[リフレクションの概要](http://docs.scala-lang.org/ja/overviews/reflection/overview.html)にて説明する) 次に、NEW `c.introduceTopLevel` API を用いて生成されたラッパーをコンパイラによって管理されているトップレベル定義のリストに挿入する。最後に、マクロは生成されたクラスのスーパーコンストラクタを呼び出す `Apply` ノードを返す。注意 `c.Expr[T]` に展開される def マクロとちがって型マクロは `c.Tree` に展開されることに注意してほしい。これは、`Expr` が値を表すのに対して、型マクロは型に展開することによる。 +`H2Db` マクロの完全なソースコードは [GitHub にて](https://github.com/xeno-by/typemacros-h2db)提供して、本稿では重要な点だけをかいつまんで説明する。まず、マクロは、コンパイル時にデータベースに接続することで静的に型付けされたデータベースのラッパーを生成する。(構文木の生成に関しては[リフレクションの概要](https://docs.scala-lang.org/ja/overviews/reflection/overview.html)にて説明する) 次に、NEW `c.introduceTopLevel` API を用いて生成されたラッパーをコンパイラによって管理されているトップレベル定義のリストに挿入する。最後に、マクロは生成されたクラスのスーパーコンストラクタを呼び出す `Apply` ノードを返す。注意 `c.Expr[T]` に展開される def マクロとちがって型マクロは `c.Tree` に展開されることに注意してほしい。これは、`Expr` が値を表すのに対して、型マクロは型に展開することによる。 type H2Db(url: String) = macro impl @@ -99,4 +96,4 @@ Scala のプログラムにおいて型マクロは、type、applied type、pare ### クラスやオブジェクトの生成 -[StackOverflow](http://stackoverflow.com/questions/13795490/how-to-use-type-calculated-in-scala-macro-in-a-reify-clause) でも説明したが、型マクロを作っていると `reify` がどんどん役に立たなくなっていくことに気付くだろう。その場合は、手で構文木を構築するだけではなく、マクロパラダイスにあるもう1つの実験的機能である準クォートを使うことも検討してみてほしい。 +[StackOverflow](https://stackoverflow.com/questions/13795490/how-to-use-type-calculated-in-scala-macro-in-a-reify-clause) でも説明したが、型マクロを作っていると `reify` がどんどん役に立たなくなっていくことに気付くだろう。その場合は、手で構文木を構築するだけではなく、マクロパラダイスにあるもう1つの実験的機能である準クォートを使うことも検討してみてほしい。 diff --git a/_ja/overviews/macros/typeproviders.md b/_ja/overviews/macros/typeproviders.md index e708c0ee59..2d4da91da7 100644 --- a/_ja/overviews/macros/typeproviders.md +++ b/_ja/overviews/macros/typeproviders.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - partof: macros overview-name: Macros @@ -77,8 +74,8 @@ def マクロによって展開された定義群のスコープは展開され これはプロダクションで使えるバージョンの Scala で実現できるため、便利な型プロバイダの方法だと言えるが、 構造的部分型のメンバにアクセスするのに Scala はリフレクションをつかった呼び出しを生成するので、性能に問題がある。 これにもいくつかの対策があるが、この余白はそれを書くには狭すぎるので Travis Brown 氏の驚くべきブログシリーズを紹介する: -[その1](http://meta.plasm.us/posts/2013/06/19/macro-supported-dsls-for-schema-bindings/)、[その2](http://meta.plasm.us/posts/2013/07/11/fake-type-providers-part-2/)、 -[その3](http://meta.plasm.us/posts/2013/07/12/vampire-methods-for-structural-types/)。 +[その1](https://meta.plasm.us/posts/2013/06/19/macro-supported-dsls-for-schema-bindings/)、[その2](https://meta.plasm.us/posts/2013/07/11/fake-type-providers-part-2/)、 +[その3](https://meta.plasm.us/posts/2013/07/12/vampire-methods-for-structural-types/)。 ## public 型プロバイダ @@ -102,9 +99,9 @@ def マクロによって展開された定義群のスコープは展開され このテクニックは匿名と public の両方の型プロバイダにあてはまる。 object Netflix { - type Title = XmlEntity["http://.../Title".type] + type Title = XmlEntity["https://.../Title".type] def Titles: List[Title] = ... - type Director = XmlEntity["http://.../Director".type] + type Director = XmlEntity["https://.../Director".type] def Directors: List[Director] = ... ... } diff --git a/_ja/overviews/macros/untypedmacros.md b/_ja/overviews/macros/untypedmacros.md index 7bd68cfa82..7b857f783b 100644 --- a/_ja/overviews/macros/untypedmacros.md +++ b/_ja/overviews/macros/untypedmacros.md @@ -1,9 +1,6 @@ --- layout: multipage-overview language: ja - -discourse: false - title: 型指定の無いマクロ --- OBSOLETE @@ -12,7 +9,7 @@ title: 型指定の無いマクロ **Eugene Yokota 訳** 型指定の無いマクロ (untyped macro) は[マクロパラダイス](/ja/overviews/macros/paradise.html)の以前のバージョンから利用可能だったが、マクロパラダイス 2.0 ではサポートされなくなった。 -[the paradise 2.0 announcement](http://scalamacros.org/news/2013/08/05/macro-paradise-2.0.0-snapshot.html) に説明と移行のための戦略が書かれている。 +[the paradise 2.0 announcement](hxxps://scalamacros.org/news/2013/08/05/macro-paradise-2.0.0-snapshot.html) に説明と移行のための戦略が書かれている。 ## 直観 @@ -58,7 +55,7 @@ Scala 2.10.x においても `unapply` や `unaoolySeq` をマクロとして宣 明示的に渡された型引数はそのままマクロに渡される。もし型引数が渡されなかった場合は、値引数を型検査しない範囲で可能な限り型引数を推論してマクロに渡す。つまり、型引数は型検査されるということだが、この制約は将来無くなるかもしれない: [SI-6972](https://issues.scala-lang.org/browse/SI-6972)。 -もし、def マクロが型指定の無い戻り値を持つ場合、マクロ展開後に実行される 2つの型検査のうち最初のものが省略される。ここで復習しておくと、def マクロが展開されるとまずその定義の戻り値の型に対して型検査され、次に展開されたものに期待される型に対して型検査が実行される。これに関しては Stack Overflow の [Static return type of Scala macros](http://stackoverflow.com/questions/13669974/static-return-type-of-scala-macros) を参照してほしい。型マクロは最初の型検査が行われないため、何も変わらない (そもそも型マクロに戻り値の型は指定できないからだ)。 +もし、def マクロが型指定の無い戻り値を持つ場合、マクロ展開後に実行される 2つの型検査のうち最初のものが省略される。ここで復習しておくと、def マクロが展開されるとまずその定義の戻り値の型に対して型検査され、次に展開されたものに期待される型に対して型検査が実行される。これに関しては Stack Overflow の [Static return type of Scala macros](https://stackoverflow.com/questions/13669974/static-return-type-of-scala-macros) を参照してほしい。型マクロは最初の型検査が行われないため、何も変わらない (そもそも型マクロに戻り値の型は指定できないからだ)。 最後に、型指定のないマクロのパッチは `c.Expr[T]` の代わりにマクロ実装のシグネチャのどこでも `c.Tree` を使うことを可能とする。 マクロ定義の型指定なし/型付きと、構文木/式によるマクロ実装の 4通りの組み合わせ全てがパラメータと戻り値の型の両方においてサポートされている。 diff --git a/_ja/overviews/macros/usecases.md b/_ja/overviews/macros/usecases.md index c5836b3d17..5a6767e378 100644 --- a/_ja/overviews/macros/usecases.md +++ b/_ja/overviews/macros/usecases.md @@ -2,8 +2,6 @@ layout: multipage-overview language: ja -discourse: false - partof: macros overview-name: Macros @@ -22,7 +20,7 @@ Scala の商用ユーザと研究ユーザの両方がマクロを利用して ここ EPFL においても我々はマクロを活用して研究を行っている。Lightbend 社もマクロを数々のプロジェクトに採用している。 マクロはコミュニティー内でも人気があり、既にいくつかの興味深い応用が現れている。 -最近行われた講演の ["What Are Macros Good For?"](http://scalamacros.org/paperstalks/2013-07-17-WhatAreMacrosGoodFor.pdf) では Scala 2.10 ユーザのマクロの利用方法を説明し、システム化した。講演の大筋はマクロはコード生成、静的な検査、および DSL に有効であるということで、これを研究や産業からの例を交えながら説明した。 +最近行われた講演の ["What Are Macros Good For?"](https://github.com/scalamacros/scalamacros.github.com/blob/5904f7ef88a439c668204b4bf262835e89fb13cb/paperstalks/2014-02-04-WhatAreMacrosGoodFor.pdf) では Scala 2.10 ユーザのマクロの利用方法を説明し、システム化した。講演の大筋はマクロはコード生成、静的な検査、および DSL に有効であるということで、これを研究や産業からの例を交えながら説明した。 -Scala'13 ワークショップにおいて ["Scala Macros: Let Our Powers Combine!"](http://scalamacros.org/paperstalks/2013-04-22-LetOurPowersCombine.pdf) という論文を発表した。これは Scala 2.10 における最先端のマクロ論をより学問的な視点から説明した。 +Scala'13 ワークショップにおいて ["Scala Macros: Let Our Powers Combine!"](https://github.com/scalamacros/scalamacros.github.com/blob/5904f7ef88a439c668204b4bf262835e89fb13cb/paperstalks/2013-04-22-LetOurPowersCombine.pdf) という論文を発表した。これは Scala 2.10 における最先端のマクロ論をより学問的な視点から説明した。 この論文では Scala のリッチな構文と静的な型がマクロと相乗することを示し、また既存の言語機能をマクロによって新しい方法で活用できることを考察する。 diff --git a/_ja/overviews/parallel-collections/architecture.md b/_ja/overviews/parallel-collections/architecture.md index 9cce07b915..146701cecc 100644 --- a/_ja/overviews/parallel-collections/architecture.md +++ b/_ja/overviews/parallel-collections/architecture.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 並列コレクションライブラリのアーキテクチャ - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -59,7 +56,7 @@ language: ja Scala の並列コレクションは、Scala の（順次）コレクションライブラリの設計から多大な影響を受けている。 以下に示すよう、トレイト群は通常のコレクションフレームワーク内のトレイト群を鏡写しのように対応している。 -[]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png) +[Hierarchy of Scala Collections and Parallel Collections]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png)
      Scala のコレクションと並列コレクションライブラリの継承関係

      @@ -77,4 +74,4 @@ Scala の並列コレクションは、Scala の（順次）コレクション 1. [On a Generic Parallel Collection Framework, Aleksandar Prokopec, Phil Bawgell, Tiark Rompf, Martin Odersky, June 2011][1] -[1]: http://infoscience.epfl.ch/record/165523/files/techrep.pdf "flawed-benchmark" +[1]: https://infoscience.epfl.ch/record/165523/files/techrep.pdf "flawed-benchmark" diff --git a/_ja/overviews/parallel-collections/concrete-parallel-collections.md b/_ja/overviews/parallel-collections/concrete-parallel-collections.md index 1681cfa468..28236af61c 100644 --- a/_ja/overviews/parallel-collections/concrete-parallel-collections.md +++ b/_ja/overviews/parallel-collections/concrete-parallel-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 具象並列コレクションクラス - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -13,7 +10,7 @@ language: ja ## 並列配列 -並列配列 ([`ParArray`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/mutable/ParArray.html)) は、線形で連続的な要素の配列を保持する列だ。 +並列配列 ([`ParArray`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/mutable/ParArray.html)) は、線形で連続的な要素の配列を保持する列だ。 そのため、内部の配列を変更することで効率的な要素の読み込みや更新ができるようになる。 また、要素の走査も非常に効率的だ。 並列配列は、サイズが一定であるという意味で配列と似ている。 @@ -38,7 +35,7 @@ language: ja ## 並列ベクトル -並列ベクトル ([`ParVector`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParVector.html)) +並列ベクトル ([`ParVector`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParVector.html)) は、低い定数係数の対数時間で読み込みと書き込みを行う不変列だ。 scala> val pv = scala.collection.parallel.immutable.ParVector.tabulate(1000)(x => x) @@ -52,13 +49,13 @@ language: ja このため、変換メソッドは並列配列のそれに比べてスケーラビリティが低い。 ベクトルの連結が将来の Scala リリースで提供されるようになれば、コンバイナは連結を用いて合成できるようになり、変換メソッドはより効率的になる。 -並列ベクトルは、順次[ベクトル](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html)の並列版で、定数時間で一方から他方へと変換できる。 +並列ベクトルは、順次[ベクトル](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html)の並列版で、定数時間で一方から他方へと変換できる。 ## 並列範囲 -並列範囲 ([`ParRange`](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParRange.html)) +並列範囲 ([`ParRange`](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParRange.html)) は、順序付けされた等間隔の要素の列だ。 -並列範囲は、逐次版の [Range](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html) と同様に作成される: +並列範囲は、逐次版の [Range](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html) と同様に作成される: scala> 1 to 3 par res0: scala.collection.parallel.immutable.ParRange = ParRange(1, 2, 3) @@ -74,8 +71,8 @@ language: ja 並列ハッシュテーブルは要素を内部の配列に格納し、各要素のハッシュコードにより格納する位置を決定する。 並列可変ハッシュ集合 ( -[mutable.ParHashSet](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/mutable/ParHashSet.html)) -と並列可変ハッシュマップ ([mutable.ParHashMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/mutable/ParHashMap.html)) +[mutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParHashSet.html)) +と並列可変ハッシュマップ ([mutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/mutable/ParHashMap.html)) はハッシュテーブルに基づいている。 scala> val phs = scala.collection.parallel.mutable.ParHashSet(1 until 2000: _*) @@ -100,8 +97,8 @@ language: ja ## 並列ハッシュトライ 並列ハッシュトライは、不変集合と不変マップを効率的に表す不変ハッシュトライの並列版だ。 -これらは、[immutable.ParHashSet](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParHashSet.html) クラスと -[immutable.ParHashMap](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/immutable/ParHashMap.html) クラスにより提供される。 +これらは、[immutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParHashSet.html) クラスと +[immutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/immutable/ParHashMap.html) クラスにより提供される。 scala> val phs = scala.collection.parallel.immutable.ParHashSet(1 until 1000: _*) phs: scala.collection.parallel.immutable.ParHashSet[Int] = ParSet(645, 892, 69, 809, 629, 365, 138, 760, 101, 479,... @@ -115,9 +112,9 @@ language: ja ## 並列並行トライ -[concurrent.TrieMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/concurrent/TrieMap.html) +[concurrent.TrieMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/concurrent/TrieMap.html) は、複数のスレッドから同時にアクセスできる (concurrent thread-safe) マップだが、 -[mutable.ParTrieMap](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/mutable/ParTrieMap.html) +[mutable.ParTrieMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParTrieMap.html) は、その並列版だ。 並列データ構造の多くは、走査時にデータ構造が変更された場合に一貫性のある走査を保証しないが、並行トライは更新が次回の走査まで見えないことを保証する。 つまり以下の 1 から 99 の数の平方根を出力する例のように、並行トライを走査中に変更できるようになる: diff --git a/_ja/overviews/parallel-collections/configuration.md b/_ja/overviews/parallel-collections/configuration.md index abc16c8854..68333b35b2 100644 --- a/_ja/overviews/parallel-collections/configuration.md +++ b/_ja/overviews/parallel-collections/configuration.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 並列コレクションの設定 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -66,4 +63,4 @@ JVM 1.5 とその他のフォーク/ジョインプールをサポートしな 1. [On a Generic Parallel Collection Framework, June 2011][1] - [1]: http://infoscience.epfl.ch/record/165523/files/techrep.pdf "parallel-collections" + [1]: https://infoscience.epfl.ch/record/165523/files/techrep.pdf "parallel-collections" diff --git a/_ja/overviews/parallel-collections/conversions.md b/_ja/overviews/parallel-collections/conversions.md index 73345f4fd9..1127b0e9cc 100644 --- a/_ja/overviews/parallel-collections/conversions.md +++ b/_ja/overviews/parallel-collections/conversions.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 並列コレクションへの変換 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -47,16 +44,16 @@ language: ja 以下の表に全ての変換をまとめる: -| メソッド | 戻り値の型 | -| -------------- | -------------- | -| `toArray` | `Array` | -| `toList` | `List` | -| `toIndexedSeq` | `IndexedSeq` | -| `toStream` | `Stream` | -| `toIterator` | `Iterator` | -| `toBuffer` | `Buffer` | -| `toTraversable`| `GenTraverable`| -| `toIterable` | `ParIterable` | -| `toSeq` | `ParSeq` | -| `toSet` | `ParSet` | -| `toMap` | `ParMap` | +| メソッド | 戻り値の型 | +| -------------- | --------------- | +| `toArray` | `Array` | +| `toList` | `List` | +| `toIndexedSeq` | `IndexedSeq` | +| `toStream` | `Stream` | +| `toIterator` | `Iterator` | +| `toBuffer` | `Buffer` | +| `toTraversable`| `GenTraversable`| +| `toIterable` | `ParIterable` | +| `toSeq` | `ParSeq` | +| `toSet` | `ParSet` | +| `toMap` | `ParMap` | diff --git a/_ja/overviews/parallel-collections/ctries.md b/_ja/overviews/parallel-collections/ctries.md index f8144460f1..d613d0c182 100644 --- a/_ja/overviews/parallel-collections/ctries.md +++ b/_ja/overviews/parallel-collections/ctries.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 並行トライ - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -140,6 +137,6 @@ language: ja 2. [Concurrent Tries with Efficient Non-Blocking Snapshots][2] 3. [Methods of computing square roots][3] - [1]: http://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf "Ctries-techreport" + [1]: https://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf "Ctries-techreport" [2]: http://lampwww.epfl.ch/~prokopec/ctries-snapshot.pdf "Ctries-snapshot" - [3]: http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method "babylonian-method" + [3]: https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method "babylonian-method" diff --git a/_ja/overviews/parallel-collections/custom-parallel-collections.md b/_ja/overviews/parallel-collections/custom-parallel-collections.md index e02cae26b9..9f2c60b518 100644 --- a/_ja/overviews/parallel-collections/custom-parallel-collections.md +++ b/_ja/overviews/parallel-collections/custom-parallel-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: カスタム並列コレクションの作成 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections diff --git a/_ja/overviews/parallel-collections/overview.md b/_ja/overviews/parallel-collections/overview.md index c9bf8e5f57..2f84c62b60 100644 --- a/_ja/overviews/parallel-collections/overview.md +++ b/_ja/overviews/parallel-collections/overview.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 概要 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections diff --git a/_ja/overviews/parallel-collections/performance.md b/_ja/overviews/parallel-collections/performance.md index 9299680834..adfbc90eee 100644 --- a/_ja/overviews/parallel-collections/performance.md +++ b/_ja/overviews/parallel-collections/performance.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 性能の測定 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -225,5 +222,5 @@ Scala の標準ライブラリには `scala.testing.Benchmark` トレイトが 1. [Anatomy of a flawed microbenchmark, Brian Goetz][1] 2. [Dynamic compilation and performance measurement, Brian Goetz][2] - [1]: http://www.ibm.com/developerworks/java/library/j-jtp02225/index.html "flawed-benchmark" - [2]: http://www.ibm.com/developerworks/library/j-jtp12214/ "dynamic-compilation" + [1]: https://www.ibm.com/developerworks/java/library/j-jtp02225/index.html "flawed-benchmark" + [2]: https://www.ibm.com/developerworks/library/j-jtp12214/ "dynamic-compilation" diff --git a/_ja/overviews/reflection/annotations-names-scopes.md b/_ja/overviews/reflection/annotations-names-scopes.md index ad8a9322ac..8101c9d772 100644 --- a/_ja/overviews/reflection/annotations-names-scopes.md +++ b/_ja/overviews/reflection/annotations-names-scopes.md @@ -1,8 +1,5 @@ --- layout: multipage-overview - -discourse: false - partof: reflection overview-name: Reflection @@ -17,7 +14,7 @@ title: アノテーション、名前、スコープ、その他 ## アノテーション Scala において宣言は `scala.annotation.Annotation` のサブタイプを用いて注釈を付けることができる。 -さらに、Scala は [Java のアノテーションシステム](http://docs.oracle.com/javase/7/docs/technotes/guides/language/annotations.html#_top)に統合するため、標準 Java コンパイラによって生成されたアノテーションを取り扱うこともできる。 +さらに、Scala は [Java のアノテーションシステム](https://docs.oracle.com/javase/7/docs/technotes/guides/language/annotations.html#_top)に統合するため、標準 Java コンパイラによって生成されたアノテーションを取り扱うこともできる。 アノテーションは、それが永続化されていればリフレクションを使ってインスペクトすることができるため、アノテーション付きの宣言を含むクラスファイルから読み込むことができる。カスタムアノテーション型は `scala.annotation.StaticAnnotation` か @@ -56,7 +53,7 @@ Scala または Java アノテーションに対しては `scalaArgs` は空で ## 名前 **名前** (name) は文字列の簡単なラッパーだ。 -[`Name`](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Names$NameApi.html) +[`Name`](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Names$NameApi.html) には 2つのサブタイプ `TermName` と `TypeName` があり (オブジェクトやメンバーのような) 項の名前と (クラス、トレイト、型メンバのような) 型の名前を区別する。同じオブジェクト内に同名の項と型が共存することができる。別の言い方をすると、型と項は別の名前空間を持つ。 @@ -99,19 +96,19 @@ Scala のプログラムにおいて、「`_root_`」のような特定の名前 「`package`」のようないくつかの名前は型名と項名の両方が存在する。 標準名は `Universe` クラスの `termNames` と `typeNames` というメンバとして公開されている。 -全ての標準名の仕様は [API doc](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/StandardNames.html) を参照。 +全ての標準名の仕様は [API doc](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/StandardNames.html) を参照。 ## スコープ **スコープ** (scope) は一般にある構文スコープ内の名前をシンボルに関連付ける。 スコープは入れ子にすることもできる。リフレクション API -で公開されているスコープの基底型は [Symbol](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Symbols$Symbol.html) の iterable という最小限のインターフェイスのみを公開する。 +で公開されているスコープの基底型は [Symbol](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Symbols$Symbol.html) の iterable という最小限のインターフェイスのみを公開する。 追加機能は -[scala.reflect.api.Types#TypeApi](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Types$TypeApi.html) +[scala.reflect.api.Types#TypeApi](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Types$TypeApi.html) 内で定義されている `member` と `decls` が返す**メンバスコープ** (member scope) にて公開される。 -[scala.reflect.api.Scopes#MemberScope](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Scopes$MemberScope.html) +[scala.reflect.api.Scopes#MemberScope](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Scopes$MemberScope.html) は `sorted` メソッドをサポートしており、これはメンバを**宣言順に**ソートする。 以下に `List` クラスでオーバーライドされている全てのシンボルのリストを宣言順に返す具体例をみてみよう: @@ -122,11 +119,11 @@ Scala のプログラムにおいて、「`_root_`」のような特定の名前 ## Expr 構文木の基底型である `scala.reflect.api.Trees#Tree` の他に、型付けされた構文木は -[`scala.reflect.api.Exprs#Expr`](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Exprs$Expr.html) 型によっても表すことができる。 +[`scala.reflect.api.Exprs#Expr`](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Exprs$Expr.html) 型によっても表すことができる。 `Expr` は構文木と、その構文木の型に対するアクセスを提供するための型タグをラッピングする。 `Expr` は主にマクロのために便宜的に型付けられた構文木を作るために使われる。多くの場合、これは `reify` と `splice` メソッドが関わってくる。 -(詳細は[マクロ](http://docs.scala-lang.org/ja/overviews/macros/overview.html)を参照) +(詳細は[マクロ](https://docs.scala-lang.org/ja/overviews/macros/overview.html)を参照) ## フラグとフラグ集合 @@ -174,12 +171,12 @@ Scala のプログラムにおいて、「`_root_`」のような特定の名前 Scala の仕様において**定数式** (constant expression) と呼ばれる式は Scala コンパイラによってコンパイル時に評価することができる。 以下に挙げる式の種類はコンパイル時定数だ。 -([Scala 言語仕様 の 6.24](http://scala-lang.org/files/archive/spec/2.11/06-expressions.html#constant-expressions) 参照): +([Scala 言語仕様 の 6.24](https://scala-lang.org/files/archive/spec/2.11/06-expressions.html#constant-expressions) 参照): -1. プリミティブ値クラスのリテラル ([Byte](http://www.scala-lang.org/api/current/index.html#scala.Byte)、 [Short](http://www.scala-lang.org/api/current/index.html#scala.Short)、 [Int](http://www.scala-lang.org/api/current/index.html#scala.Int)、 [Long](http://www.scala-lang.org/api/current/index.html#scala.Long)、 [Float](http://www.scala-lang.org/api/current/index.html#scala.Float)、 [Double](http://www.scala-lang.org/api/current/index.html#scala.Double)、 [Char](http://www.scala-lang.org/api/current/index.html#scala.Char)、 [Boolean](http://www.scala-lang.org/api/current/index.html#scala.Boolean) および [Unit](http://www.scala-lang.org/api/current/index.html#scala.Unit))。これは直接対応する型で表される。 +1. プリミティブ値クラスのリテラル ([Byte](https://www.scala-lang.org/api/current/index.html#scala.Byte)、 [Short](https://www.scala-lang.org/api/current/index.html#scala.Short)、 [Int](https://www.scala-lang.org/api/current/index.html#scala.Int)、 [Long](https://www.scala-lang.org/api/current/index.html#scala.Long)、 [Float](https://www.scala-lang.org/api/current/index.html#scala.Float)、 [Double](https://www.scala-lang.org/api/current/index.html#scala.Double)、 [Char](https://www.scala-lang.org/api/current/index.html#scala.Char)、 [Boolean](https://www.scala-lang.org/api/current/index.html#scala.Boolean) および [Unit](https://www.scala-lang.org/api/current/index.html#scala.Unit))。これは直接対応する型で表される。 2. 文字列リテラル。これは文字列のインスタンスとして表される。 -3. 一般に [scala.Predef#classOf](http://www.scala-lang.org/api/current/index.html#scala.Predef$@classOf[T]:Class[T]) で構築されるクラスへの参照。[型](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Types$Type.html)として表される。 -4. Java の列挙要素。[シンボル](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Symbols$Symbol.html)として表される。 +3. 一般に [scala.Predef#classOf](https://www.scala-lang.org/api/current/index.html#scala.Predef$@classOf[T]:Class[T]) で構築されるクラスへの参照。[型](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Types$Type.html)として表される。 +4. Java の列挙要素。[シンボル](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Symbols$Symbol.html)として表される。 定数式の用例としては @@ -267,8 +264,8 @@ Java の列挙要素への参照はシンボル (`scala.reflect.api.Symbols#Symb ## プリティプリンタ -[`Trees`](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Trees.html) と -[`Types`](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Types.html) +[`Trees`](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Trees.html) と +[`Types`](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Types.html) を整形して表示するユーティリティを説明しよう。 ### 構文木の表示 @@ -383,7 +380,7 @@ Java の列挙要素への参照はシンボル (`scala.reflect.api.Symbols#Symb ## 位置情報 -**位置情報** ([`Position`](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Position.html)) +**位置情報** ([`Position`](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Position.html)) はシンボルや構文木のノードの出処を追跡するのに使われる。警告やエラーの表示でよく使われ、プログラムのどこが間違ったのかを正確に表示することができる。位置情報はソースファイルの列と行を表す。 (ソースファイルの初めからのオフセットは「ポイント」と呼ばれるが、これは便利ではないことがある) 位置情報はそれが指す行の内容も保持する。全ての構文木やシンボルが位置情報を持つわけではなく、ない場合は diff --git a/_ja/overviews/reflection/environment-universes-mirrors.md b/_ja/overviews/reflection/environment-universes-mirrors.md index c1c87199ef..475b7f7586 100644 --- a/_ja/overviews/reflection/environment-universes-mirrors.md +++ b/_ja/overviews/reflection/environment-universes-mirrors.md @@ -1,8 +1,5 @@ --- layout: multipage-overview - -discourse: false - partof: reflection overview-name: Reflection diff --git a/_ja/overviews/reflection/overview.md b/_ja/overviews/reflection/overview.md index 004a43795b..d884785fe5 100644 --- a/_ja/overviews/reflection/overview.md +++ b/_ja/overviews/reflection/overview.md @@ -8,8 +8,6 @@ num: 1 language: ja title: 概要 - -discourse: false --- EXPERIMENTAL @@ -56,7 +54,6 @@ Scala の式を抽象構文木へと**レイファイ** (reify) する機能 (3) ### 具体例 -  #### ランタイム型のインスペクション (実行時におけるジェネリック型も含む) 他の JVM言語同様に、Scala の型はコンパイル時に**消去** (erase) される。 @@ -84,7 +81,7 @@ Scala コンパイラが持つ型情報を全ては入手できない可能性 上の例では、まず `scala.reflect.runtime.universe` をインポートして (型タグを使うためには必ずインポートされる必要がある)、`l` という名前の `List[Int]` を作る。 -次に、context bound を持った型パラメータ `T` を持つ `getTypeTag` というメソッドは定義する +次に、context bound を持った型パラメータ `T` を持つ `getTypeTag` というメソッドを定義する (REPL が示すとおり、これは暗黙の evidence パラメータを定義することに等価であり、コンパイラは `T` に対する型タグを生成する)。 最後に、このメソッドに `l` を渡して呼び出し、`TypeTag` に格納される型を返す `tpe` を呼び出す。 見ての通り、正しい完全な型 (つまり、`List` の具象型引数を含むということ) である `List[Int]` が返ってきた。 diff --git a/_ja/overviews/reflection/symbols-trees-types.md b/_ja/overviews/reflection/symbols-trees-types.md index a2b01ce5e0..13247503b5 100644 --- a/_ja/overviews/reflection/symbols-trees-types.md +++ b/_ja/overviews/reflection/symbols-trees-types.md @@ -1,8 +1,5 @@ --- layout: multipage-overview - -discourse: false - partof: reflection overview-name: Reflection @@ -170,7 +167,7 @@ title: シンボル、構文木、型 scala> val intTpe = universe.definitions.IntTpe intTpe: scala.reflect.runtime.universe.Type = Int -標準型のリストは [`scala.reflect.api.StandardDefinitions`](http://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/StandardDefinitions$StandardTypes.html) 内の `StandardTypes` +標準型のリストは [`scala.reflect.api.StandardDefinitions`](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/StandardDefinitions$StandardTypes.html) 内の `StandardTypes` トレイトにて定義されている。 ### 型の一般的な演算 @@ -210,7 +207,7 @@ Scala の数値型は以下の順序付けに従っている (Scala 言語仕様 > Scala はいくつかの状況では、より一般的な適合性関係を用います。 もし `S <: T` であるか、あるいは、`S` と `T` 両方がプリミティブな数値型で、次の順序中で `S` が `T` の前にあるなら、型 `S` は型 `T` に弱く適合するといい、`S <:w T` と書きます。 | 弱適合性関係 | - --------------------------- +| --- | | `Byte` `<:w` `Short` | | `Short` `<:w` `Int` | | `Char` `<:w` `Int` | diff --git a/_ja/overviews/reflection/thread-safety.md b/_ja/overviews/reflection/thread-safety.md index d67254ae7a..3acb172b87 100644 --- a/_ja/overviews/reflection/thread-safety.md +++ b/_ja/overviews/reflection/thread-safety.md @@ -1,8 +1,5 @@ --- layout: multipage-overview - -discourse: false - partof: reflection overview-name: Reflection diff --git a/_ja/overviews/reflection/typetags-manifests.md b/_ja/overviews/reflection/typetags-manifests.md index c4eea9aee9..dff84bf89a 100644 --- a/_ja/overviews/reflection/typetags-manifests.md +++ b/_ja/overviews/reflection/typetags-manifests.md @@ -1,8 +1,5 @@ --- layout: multipage-overview - -discourse: false - partof: reflection overview-name: Reflection diff --git a/_ja/overviews/scala3-book/scala-for-python-devs.md b/_ja/overviews/scala3-book/scala-for-python-devs.md new file mode 100644 index 0000000000..41b7fc9f38 --- /dev/null +++ b/_ja/overviews/scala3-book/scala-for-python-devs.md @@ -0,0 +1,1383 @@ +--- +title: Scala for Python Developers +type: chapter +description: This page is for Python developers who are interested in learning about Scala 3. +languages: [zh-cn, ja] +num: 76 +previous-page: scala-for-javascript-devs +next-page: where-next +--- + +{% include_relative scala4x.css %} + +
      + +{% comment %} + +NOTE: Hopefully someone with more Python experience can give this a thorough review. + +NOTE: On this page (https://contributors.scala-lang.org/t/feedback-sought-optional-braces/4702/10), Li Haoyi comments: “Python’s success also speaks for itself; beginners certainly don’t pick Python because of performance, ease of installation, packaging, IDE support, or simplicity of the language’s runtime semantics!” I’m not a Python expert, so these points are good to know, though I don’t want to go negative in any comparisons. +It’s more like thinking, “Python developers will appreciate Scala’s performance, ease of installation, packaging, IDE support, etc.” +{% endcomment %} + +{% comment %} +TODO: We should probably go through this document and add links to our other detail pages, when time permits. +{% endcomment %} + +このセクションでは、PythonとScalaのプログラミング言語を比較します。 +Pythonに詳しくて、Scalaについて学びたいと考えているプログラマーを対象としています。具体的には、Pythonの言語機能とScalaの比較例を挙げて説明します。 + +## はじめに + +例に入る前に、この最初のセクションでは、後に続くセクションの簡単な紹介と概要を提供します。 +まず、2つの言語の概要を高レベルで比較し、その後、実践的なプログラミングでの比較を行います。 + +### 高レベルでの類似点 + +高レベルで見ると、ScalaはPythonと以下のような *類似点* を共有しています。 + +- 高水準プログラミング言語であり、ポインタや手動でのメモリ管理といった低レベルの概念を気にする必要がありません。 +- 比較的シンプルで簡潔な構文を持ちます。 +- [関数型プログラミングスタイル][fp-intro]をサポートしています。 +- オブジェクト指向プログラミング（OOP）言語です。 +- 内包表記（comprehensions）をサポートしています。Pythonにはリスト内包表記があり、Scalaには`for`内包表記があります。 +- ラムダ式と[高階関数][hofs]をサポートしています。 +- [Apache Spark](https://spark.apache.org)を用いたビッグデータ処理に使用できます。 +- 優れたライブラリが豊富に使用できます。 + +### 高レベルでの相違点 + +高レベルで見ると、PythonとScalaの間には以下のような _相違点_ があります： + +- Python は動的型付け言語であり、Scala は静的型付け言語です。 + - Pythonは動的型付けですが、型ヒントによる「段階的型付け」をサポートしており、`mypy`のような静的型チェッカーで検証できます。 + - Scalaは静的型付けですが、型推論のような機能により動的言語のような感覚で書けます。 +- Pythonはインタプリタ型で実行され、Scalaのコードはコンパイルされて _.class_ ファイルになり、Java仮想マシン（JVM）上で動作します。 +- JVMでの実行に加えて、[Scala.js](https://www.scala-js.org)によりScalaをJavaScriptの代替として使用することもできます。 +- [Scala Native](https://scala-native.org/)では、「システムレベル」のコードを記述し、ネイティブ実行ファイルにコンパイルできます。 +- Scalaではすべてが _式_ である：`if`文、`for`ループ、`match`式、さらには`try`/`catch`式でさえも、戻り値を持ちます。 +- 慣用的に Scala では不変性を基本とする：不変変数や不変コレクションを使用することが推奨されています。 +- Scalaは[並行・並列プログラミング][concurrency]のサポートが優れています。 + +### プログラミングレベルでの類似点 + +このセクションでは、実際に Python と Scala でコードを書く際に見られる類似点を紹介します。 + +- Scalaの型推論により、動的型付け言語のような感覚でコーディングできます。 +- どちらの言語も式の末尾にセミコロンを使用しません。 +- 中括弧や括弧ではなく、インデントを重要視した記述がサポートされています。 +- メソッド定義の構文が似ています。 +- 両方ともリスト、辞書（マップ）、セット、タプルをサポートしています。 +- マッピングやフィルタリングに対応した内包表記を備えています。 +- 優れたIDEサポートがあります。 +- Scala 3の[トップレベル定義][toplevel]を利用することで、メソッドやフィールド、その他の定義をどこにでも記述できます。 + - 一方で、Pythonはメソッドを1つも宣言しなくても動作できますが、Scala 3ではトップレベルですべてを実現することはできません。たとえば、Scalaアプリケーションを開始するには[mainメソッド][main-method]（`@main def`）が必要です。 + +### プログラミングレベルでの違い + +プログラミングレベルでも、コードを書く際に日常的に見られるいくつかの違いがあります： + +- Scalaでのプログラミングは非常に一貫性があります： + - フィールドやパラメータを定義する際に、`val`と`var`が一貫して使用されます + - リスト、マップ、セット、タプルはすべて同様に作成・アクセスされます。たとえば、他のScalaクラスを作成するのと同様に、すべてのタイプを作成するために括弧が使用されます---`List(1,2,3)`, `Set(1,2,3)`, `Map(1->"one")` + - [コレクションクラス][collections-classes] は一般的にほとんど同じ高階関数を持っています + - パターンマッチングは言語全体で一貫して使用されます + - メソッドに渡される関数を定義するために使用される構文は、匿名関数を定義するために使用される構文と同じです +- Scalaの変数やパラメータは`val`（不変）または `var`（可変）キーワードで定義されます +- 慣用的に、Scala では不変データ構造を使うことを良しとします。 +- コメント： Pythonはコメントに `#` を使用しますが、ScalaはC、C++、Javaスタイルの `//`、`/*...*/`、および `/**...*/` を使用します +- 命名規則： Pythonの標準は `my_list` のようにアンダースコアを使用しますが、Scalaは `myList` を使用します +- Scalaは静的型付けであるため、メソッドパラメータ、メソッドの戻り値、その他の場所で型を宣言します +- パターンマッチングと `match` 式はScalaで広範に使用されており、コードの書き方を変えるでしょう +- トレイト（Traits）： Scalaではトレイトが多用され、Pythonではインターフェースや抽象クラスがあまり使用されません +- Scalaの[コンテキスト抽象][contextual]と _型推論_ は、さまざまな機能のコレクションを提供します： + - [拡張メソッド][extension-methods] により、明確な構文を使用してクラスに新しい機能を簡単に追加できます + - [多元的等価性][multiversal] により、コンパイル時に意味のある比較にのみ等価比較を制限できます +- Scalaには最先端のオープンソース関数型プログラミングライブラリがあります（[“Awesome Scala”リスト](https://github.com/lauris/awesome-scala)を参照） +- オブジェクト、名前渡しパラメータ、中置表記、オプションの括弧、拡張メソッド、高階関数などの機能により、独自の「制御構造」やDSLを作成できます +- ScalaコードはJVM上で実行でき、[Scala Native](https://github.com/scala-native/scala-native)や[GraalVM](https://www.graalvm.org)を使用してネイティブイメージにコンパイルすることも可能で、高性能を実現します +- その他多くの機能：コンパニオンクラスとオブジェクト、マクロ、数値リテラル、複数のパラメータリスト、[交差型][intersection-types]、型レベルプログラミングなど + +### 機能の比較と例 + +この導入に基づき、以下のセクションではPythonとScalaのプログラミング言語機能を並べて比較します。 + +{% comment %} TODO: Pythonの例をスペース四つに更新します。開始しましたが、別のPRで行う方が良いと思いました。 {% endcomment %} + +## コメント + +Pythonはコメントに # を使用しますが、Scalaのコメント構文はC、C++、Javaなどの言語と同じです。 + + + + + + + + + + +
      + # a comment +
      + // a comment +
      /* ... */ +
      /** ... */       +
      + +## 変数の割り当て + +これらの例は、PythonとScalaで変数を作成する方法を示しています。 + +### 整数変数,文字列変数 + + + + + + + + + + +
      + x = 1 +
      x = "Hi" +
      y = """foo +
             bar +
             baz"""       +
      + val x = 1 +
      val x = "Hi" +
      val y = """foo +
                 bar +
                 baz"""       +
      + +### リスト + + + + + + + + + + +
      + x = [1,2,3] +
      + val x = List(1,2,3) +
      + +### 辞書/マップ + + + + + + + + + + +
      + x = { +
        "Toy Story": 8.3, +
        "Forrest Gump": 8.8, +
        "Cloud Atlas": 7.4 +
      }       +
      + val x = Map( +
        "Toy Story" -> 8.3, +
        "Forrest Gump" -> 8.8, +
        "Cloud Atlas" -> 7.4 +
      )       +
      + +### 集合 + + + + + + + + + + +
      + x = {1,2,3} +
      + val x = Set(1,2,3) +
      + +### タプル + + + + + + + + + + +
      + x = (11, "Eleven") +
      + val x = (11, "Eleven") +
      + +Scalaのフィールドが可変になる場合は、変数定義に `val` の代わりに `var` を使います。 + +```scala +var x = 1 +x += 1 +``` + +しかし、Scalaの慣習として、特に変数を変更する必要がない限り、常に`val`を使います。 + +## 関数型プログラミングスタイルのレコード + +Scalaのケース・クラスはPythonのフローズン・データクラスに似ています。 + +### 構造体の定義 + + + + + + + + + + +
      + from dataclasses import dataclass, replace +
      +
      @dataclass(frozen=True) +
      class Person: +
        name: str +
        age: int       +
      + case class Person(name: String, age: Int) +
      + +### インスタンスを作成して使用する + + + + + + + + + + +
      + p = Person("Alice", 42) +
      p.name   # Alice +
      p2 = replace(p, age=43)       +
      + val p = Person("Alice", 42) +
      p.name   // Alice +
      val p2 = p.copy(age = 43)       +
      + +## オブジェクト指向プログラミングスタイルのクラスとメソッド + +このセクションでは、オブジェクト指向プログラミングスタイルのクラスとメソッドに関する機能の比較を行います。 + +### クラスとプライマリーコンストラクタ + + + + + + + + + + +
      + class Person(object): +
        def __init__(self, name): +
          self.name = name +
      +
        def speak(self): +
          print(f'Hello, my name is {self.name}')       +
      + class Person (var name: String): +
        def speak() = println(s"Hello, my name is $name")       +
      + +### インスタンスを作成して使用する + + + + + + + + + + +
      + p = Person("John") +
      p.name   # John +
      p.name = 'Fred' +
      p.name   # Fred +
      p.speak()       +
      + val p = Person("John") +
      p.name   // John +
      p.name = "Fred" +
      p.name   // Fred +
      p.speak()       +
      + +### 1行メソッド + + + + + + + + + + +
      + def add(a, b): return a + b +
      + def add(a: Int, b: Int): Int = a + b +
      + +### 複数行のメソッド + + + + + + + + + + +
      + def walkThenRun(): +
        print('walk') +
        print('run')       +
      + def walkThenRun() = +
        println("walk") +
        println("run")       +
      + +## インターフェース、トレイト、継承 + +Java 8以降に慣れていれば、ScalaのtraitはJavaのインターフェースに良く似ていることに気づくと思います。 +Pythonのインターフェース（プロトコル）や抽象クラスがあまり使われないのに対して、Scalaではトレイトが常に使われています。 +したがって、この例では両者を比較するのではなく、Scalaのトレイトを使って数学のちょっとした問題を解く方法を紹介します： + +```scala +trait Adder: + def add(a: Int, b: Int) = a + b + +trait Multiplier: + def multiply(a: Int, b: Int) = a * b + +// create a class from the traits +class SimpleMath extends Adder, Multiplier +val sm = new SimpleMath +sm.add(1,1) // 2 +sm.multiply(2,2) // 4 +``` + +クラスやオブジェクトでtraitを使う方法は他にも[たくさんあります][modeling-intro]。 +しかし、これは概念を論理的な動作のグループに整理して、完全な解答を作成するために必要に応じてそれらを統合するために、どのように使うことができるかのちょっとしたアイデアを与えてくれます。 + +## 制御構文 + +ここではPythonとScalaの[制御構文][control-structures]を比較します。 +どちらの言語にも `if`/`else`, `while`, `for` ループ、 `try` といった構文があります。 +加えて、Scala には `match` 式があります。 + +### `if` 文, 1行 + + + + + + + + + + +
      + if x == 1: print(x) +
      + if x == 1 then println(x) +
      + +### `if` 文, 複数行 + + + + + + + + + + +
      + if x == 1: +
        print("x is 1, as you can see:") +
        print(x)       +
      + if x == 1 then +
        println("x is 1, as you can see:") +
        println(x)       +
      + +### if, else if, else: + + + + + + + + + + +
      + if x < 0: +
        print("negative") +
      elif x == 0: +
        print("zero") +
      else: +
        print("positive")       +
      + if x < 0 then +
        println("negative") +
      else if x == 0 then +
        println("zero") +
      else +
        println("positive")       +
      + +### `if` 文からの戻り値 + + + + + + + + + + +
      + min_val = a if a < b else b +
      + val minValue = if a < b then a else b +
      + +### メソッドの本体としての`if` + + + + + + + + + + +
      + def min(a, b): +
        return a if a < b else b       +
      + def min(a: Int, b: Int): Int = +
        if a < b then a else b       +
      + +### `while` ループ + + + + + + + + + + +
      + i = 1 +
      while i < 3: +
        print(i) +
        i += 1       +
      + var i = 1 +
      while i < 3 do +
        println(i) +
        i += 1       +
      + +### rangeを指定した`for` ループ + + + + + + + + + + +
      + for i in range(0,3): +
        print(i)       +
      + // preferred +
      for i <- 0 until 3 do println(i) +
      +
      // also available +
      for (i <- 0 until 3) println(i) +
      +
      // multiline syntax +
      for +
        i <- 0 until 3 +
      do +
        println(i)       +
      + +### リスト範囲内の`for` ループ + + + + + + + + + + +
      + for i in ints: print(i) +
      +
      for i in ints: +
        print(i)       +
      + for i <- ints do println(i) +
      + +### 複数行での`for` ループ + + + + + + + + + + +
      + for i in ints: +
        x = i * 2 +
        print(f"i = {i}, x = {x}")       +
      + for +
        i <- ints +
      do +
        val x = i * 2 +
        println(s"i = $i, x = $x")       +
      + +### 複数の “range” ジェネレータ + + + + + + + + + + +
      + for i in range(1,3): +
        for j in range(4,6): +
          for k in range(1,10,3): +
            print(f"i = {i}, j = {j}, k = {k}")       +
      + for +
        i <- 1 to 2 +
        j <- 4 to 5 +
        k <- 1 until 10 by 3 +
      do +
        println(s"i = $i, j = $j, k = $k")       +
      + +### ガード付きジェネレータ (`if` 式) + + + + + + + + + + +
      + for i in range(1,11): +
        if i % 2 == 0: +
          if i < 5: +
            print(i)       +
      + for +
        i <- 1 to 10 +
        if i % 2 == 0 +
        if i < 5 +
      do +
        println(i)       +
      + +### 行ごとに複数の`if`条件 + + + + + + + + + + +
      + for i in range(1,11): +
        if i % 2 == 0 and i < 5: +
          print(i)       +
      + for +
        i <- 1 to 10 +
        if i % 2 == 0 && i < 5 +
      do +
        println(i)       +
      + +### 内包表記 + + + + + + + + + + +
      + xs = [i * 10 for i in range(1, 4)] +
      # xs: [10,20,30]       +
      + val xs = for i <- 1 to 3 yield i * 10 +
      // xs: Vector(10, 20, 30)       +
      + +### `match` 条件式 + + + + + + + + + + +
      + # From 3.10, Python supports structural pattern matching +
      # You can also use dictionaries for basic “switch” functionality +
      match month: +
        case 1: +
          monthAsString = "January" +
        case 2: +
          monthAsString = "February" +
        case _: +
          monthAsString = "Other"       +
      + val monthAsString = month match +
        case 1 => "January" +
        case 2 => "February" +
        _ => "Other"       +
      + +### switch/match + + + + + + + + + + +
      + # Only from Python 3.10 +
      match i: +
        case 1 | 3 | 5 | 7 | 9: +
          numAsString = "odd" +
        case 2 | 4 | 6 | 8 | 10: +
          numAsString = "even" +
        case _: +
          numAsString = "too big"       +
      + val numAsString = i match +
        case 1 | 3 | 5 | 7 | 9 => "odd" +
        case 2 | 4 | 6 | 8 | 10 => "even" +
        case _ => "too big"       +
      + +### try, catch, finally + + + + + + + + + + +
      + try: +
        print(a) +
      except NameError: +
        print("NameError") +
      except: +
        print("Other") +
      finally: +
        print("Finally")       +
      + try +
        writeTextToFile(text) +
      catch +
        case ioe: IOException => +
          println(ioe.getMessage) +
        case fnf: FileNotFoundException => +
          println(fnf.getMessage) +
      finally +
        println("Finally")       +
      + +マッチ式とパターンマッチは、Scalaプログラミングの大きな要素ですが、ここで紹介しているのは、マッチ式の機能の一部だけです。より多くの例については、[制御構造][control-structures]のページをご覧ください。 + +## コレクションクラス + +このセクションでは、PythonとScalaで利用可能なコレクションクラス[collections classes][collections-classes]を比較します。リスト、辞書/マップ、セット、タプルなどです。 + +### リスト + +Pythonにはリストがあるように、Scalaにはニーズに応じて、可変および不可変な列(Seq)のクラスがいくつか用意されています。 +Pythonのリストは変更可能であるため、Scalaの `ArrayBuffer` によく似ています。 + +### Pythonリスト & Scalaの列(Seq) + + + + + + + + + + +
      + a = [1,2,3] +
      + // use different sequence classes +
      // as needed +
      val a = List(1,2,3) +
      val a = Vector(1,2,3) +
      val a = ArrayBuffer(1,2,3)       +
      + +### リストの要素へのアクセス + + + + + + + + + + +
      + a[0]
      a[1]       +
      + a(0)
      a(1)       // just like all other method calls +
      + +### リストの要素の更新 + + + + + + + + + + +
      + a[0] = 10 +
      a[1] = 20       +
      + // ArrayBuffer is mutable +
      a(0) = 10 +
      a(1) = 20       +
      + +### 2つのリストの結合 + + + + + + + + + + +
      + c = a + b +
      + val c = a ++ b +
      + +### リストの反復処理 + + + + + + + + + + +
      + for i in ints: print(i) +
      +
      for i in ints: +
        print(i)       +
      + // preferred +
      for i <- ints do println(i) +
      +
      // also available +
      for (i <- ints) println(i)       +
      + +Scala の主な列(Seq)クラスは `List`、`Vector`、`ArrayBuffer` です。 +`List` と `Vector` は不変な列が必要なときに使うメインクラスで、 `ArrayBuffer` は可変な列が必要なときに使うメインクラスです。 +(Scala における 「バッファ」 とは、大きくなったり小さくなったりする配列のことです。) + +### 辞書/マップ + +Python の辞書はScala の `Map` クラスのようなものです。 +しかし、Scala のデフォルトのマップは _immutable_ であり、新しいマップを簡単に作成するための変換メソッドを持っています。 + +#### 辞書/マップ の作成 + + + + + + + + + + +
      + my_dict = { +
        'a': 1, +
        'b': 2, +
        'c': 3 +
      }       +
      + val myMap = Map( +
        "a" -> 1, +
        "b" -> 2, +
        "c" -> 3 +
      )       +
      + +#### 辞書/マップの要素へのアクセス + + + + + + + + + + +
      + my_dict['a']   # 1 +
      + myMap("a")   // 1 +
      + +#### `for` ループでの辞書/マップ + + + + + + + + + + +
      + for key, value in my_dict.items(): +
        print(key) +
        print(value)       +
      + for (key,value) <- myMap do +
        println(key) +
        println(value)       +
      + +Scalaには、さまざまなニーズに対応する他の専門的な `Map` クラスがあります。 + +### 集合 + +Pythonの集合は、_mutable_ Scalaの`Set`クラスに似ています。 + +#### 集合の作成 + + + + + + + + + + +
      + set = {"a", "b", "c"} +
      + val set = Set(1,2,3) +
      + +#### 重複する要素 + + + + + + + + + + +
      + set = {1,2,1} +
      # set: {1,2}       +
      + val set = Set(1,2,1) +
      // set: Set(1,2)       +
      + +Scalaには、他にも様々なニーズに特化した`Set`クラスがあります。 + +### タプル + +PythonとScalaのタプルも似ています。 + +#### タプルの作成 + + + + + + + + + + +
      + t = (11, 11.0, "Eleven") +
      + val t = (11, 11.0, "Eleven") +
      + +#### タプルの要素へのアクセス + + + + + + + + + + +
      + t[0]   # 11 +
      t[1]   # 11.0       +
      + t(0)   // 11 +
      t(1)   // 11.0       +
      + +## コレクションクラスでのメソッド + +PythonとScalaには、同じ関数型メソッドがいくつかあります。 + +- `map` +- `filter` +- `reduce` + +Pythonのラムダ式でこれらのメソッドを使うのに慣れていれば、Scalaがコレクション・クラスのメソッドで同じようなアプローチを持っていることがわかると思います。 +この機能を実証するために、ここに2つのサンプルリストを示します。 + +```scala +numbers = [1,2,3] // python +val numbers = List(1,2,3) // scala +``` + +これらのリストは以下の表で使用され、マップ処理とフィルター処理のアルゴリズムを適用する方法を示しています。 + +### マップ処理の内包表記 + + + + + + + + + + +
      + x = [i * 10 for i in numbers] +
      + val x = for i <- numbers yield i * 10 +
      + +### フィルター処理の内包表記 + + + + + + + + + + +
      + evens = [i for i in numbers if i % 2 == 0] +
      + val evens = numbers.filter(_ % 2 == 0) +
      // or +
      val evens = for i <- numbers if i % 2 == 0 yield i       +
      + +### マップ、フィルター処理の内包表記 + + + + + + + + + + +
      + x = [i * 10 for i in numbers if i % 2 == 0] +
      + val x = numbers.filter(_ % 2 == 0).map(_ * 10) +
      // or +
      val x = for i <- numbers if i % 2 == 0 yield i * 10       +
      + +### マップ処理 + + + + + + + + + + +
      + x = map(lambda x: x * 10, numbers) +
      + val x = numbers.map(_ * 10) +
      + +### フィルター処理 + + + + + + + + + + +
      + f = lambda x: x > 1 +
      x = filter(f, numbers)       +
      + val x = numbers.filter(_ > 1) +
      + + +### Scalaのコレクションメソッド + +Scalaのコレクションクラスには100以上の関数メソッドがあり、コードを簡単にすることができます。 +Python では、これらの関数の一部は `itertools` モジュールで利用できます。 +`map`、`filter`、`reduce` に加えて、Scala でよく使われるメソッドを以下に示します。 +これらのメソッドの例では + +- `c` はコレクションです。 +- `p` は述語です。 +- `f` は関数、無名関数、またはメソッドです。 +- `n` は整数値です。 + +これらは利用可能なフィルタリング方法の一部です。 + +|メソッド|説明| +| -------------- | ------------- | +| `c1.diff(c2)` | `c1` と `c2` の要素の差分を返します。| +| `c.distinct` | `c` の重複しない要素を返します。| +| `c.drop(n)` | 最初の `n` 要素を除くコレクションのすべての要素を返します。| +| `c.filter(p)` | コレクションから、その述語が `true` となるすべての要素を返します。| +| `c.head` | コレクションの最初の要素を返します。 (コレクションが空の場合は `NoSuchElementException` をスローします。)| +| `c.tail` | コレクションから最初の要素を除くすべての要素を返します。 (コレクションが空の場合は `UnsupportedOperationException` をスローします。)| +| `c.take(n)` | コレクション `c` の最初の `n` 個の要素を返します。 +以下に、いくつかのトランスフォーマメソッドを示します。| +|メソッド| 説明 | +| --------------- | ------------- +| `c.flatten` | コレクションのコレクション（リストのリストなど）を単一のコレクション（単一のリスト）に変換します。| +| `c.flatMap(f)` | コレクション `c` のすべての要素に `f` を適用し（`map` のような動作）、その結果のコレクションの要素を平坦化して、新しいコレクションを返します。| +| `c.map(f)` | コレクション `c` のすべての要素に `f` を適用して、新しいコレクションを作成します。| +| `c.reduce(f)` | 「リダクション」関数 `f` を `c` の連続する要素に適用し、単一の値を生成します。| +| `c.sortWith(f)` | 比較関数 `f` によってソートされた `c` のバージョンを返します。| +よく使われるグループ化メソッド： +| メソッド | 説明 | +| ---------------- | ------------- +| `c.groupBy(f)` | コレクションを `f` に従って分割し、コレクションの `Map` を作成します。| +| `c.partition(p)` | 述語 `p` に従って2つのコレクションを返します。| +| `c.span(p)` | 2つのコレクションからなるコレクションを返します。1つ目は `c.takeWhile(p)` によって作成され、2つ目は `c.dropWhile(p)` によって作成されます。| +| `c.splitAt(n)` | コレクション `c` を要素 `n` で分割して、2つのコレクションからなるコレクションを返します。| +情報および数学的なメソッド： +| メソッド | 説明 | +| -------------- | ------------- | +| `c1.containsSlice(c2)` | `c1` がシーケンス `c2` を含む場合に `true` を返します。| +| `c.count(p)` | `p` が `true` である `c` の要素数を数えます。| +| `c.distinct` | `c` の一意な要素を返します。| +| `c.exists(p)` | コレクション内のいずれかの要素に対して `p` が `true` であれば `true` を返します。| +| `c.find(p)` | `p` に一致する最初の要素を返します。 要素は `Option[A]` として返されます。| +| `c.min` | コレクションから最小の要素を返します。 (_java.lang.UnsupportedOperationException_例外が発生する場合があります。)| +| `c.max` | コレクションから最大の要素を返します。 (_java.lang.UnsupportedOperationException_例外が発生する場合があります。)| +| `c slice(from, to)` | 要素 `from` から始まり、要素 `to` で終わる要素の範囲を返します。| +| `c.sum` | コレクション内のすべての要素の合計を返しますw。 (コレクション内の要素に対して `Ordering` を定義する必要があります。)| + +以下に、これらのメソッドがリスト上でどのように機能するかを説明する例をいくつか示します。 + +```scala +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.filter(_ > 100) // List() +a.find(_ > 20) // Some(30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.intersect(List(19,20,21)) // List(20) +a.last // 10 +a.lastOption // Some(10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +a.takeWhile(_ < 30) // List(10, 20) +``` + +これらのメソッドは、Scalaにおける共通のパターンを示しています。オブジェクト上で利用可能な機能メソッドです。 +これらの方法はいずれも、初期リスト `a` を変更しません。代わりに、コメントの後に示されているデータをすべて返します。 +利用可能なメソッドは他にもたくさんありますが、これらの説明と例が、組み込みのコレクションメソッドの持つ力を実感する一助となれば幸いです。 + +## 列挙 + +このセクションでは、PythonとScala 3の列挙型を比較します。 + +### 列挙型の作成 + + + + + + + + + + +
      + from enum import Enum, auto +
      class Color(Enum): +
          RED = auto() +
          GREEN = auto() +
          BLUE = auto()       +
      + enum Color: +
        case Red, Green, Blue       +
      + +### 値とその比較 + + + + + + + + + + +
      + Color.RED == Color.BLUE  # False +
      + Color.Red == Color.Blue  // false +
      + +### パラメータ化された列挙型 + + + + + + + + + + +
      + N/A +
      + enum Color(val rgb: Int): +
        case Red   extends Color(0xFF0000) +
        case Green extends Color(0x00FF00) +
        case Blue  extends Color(0x0000FF)       +
      + +### ユーザー定義による列挙メンバー + + + + + + + + + + +
      + N/A +
      + enum Planet( +
          mass: Double, +
          radius: Double +
        ): +
        case Mercury extends +
          Planet(3.303e+23, 2.4397e6) +
        case Venus extends +
          Planet(4.869e+24, 6.0518e6) +
        case Earth extends +
          Planet(5.976e+24, 6.37814e6) +
        // more planets ... +
      +
        // fields and methods +
        private final val G = 6.67300E-11 +
        def surfaceGravity = G * mass / +
          (radius * radius) +
        def surfaceWeight(otherMass: Double) +
          = otherMass * surfaceGravity       +
      + +## Scala 独自の概念 + +Scalaには、Pythonには現在同等の機能がない概念が他にもあります。 +詳細は以下のリンクを参照してください。 +- 拡張メソッド（extension methods）、型クラス（type classes）、暗黙的値（implicit values）など、文脈依存の抽象化（contextual abstractions）に関連するほとんどの概念 +- Scalaでは複数のパラメータリストを使用できるため、部分適用関数などの機能や独自のDSLを作成することが可能 +- 独自の制御構造や DSL を作成できる機能 +- [多様等価][多様等価]: どの等価比較が意味を持つかをコンパイル時に制御できる機能 +- インフィックスメソッド +- マクロ + +## Scala と仮想環境 + +Scalaでは、Pythonの仮想環境に相当するものを明示的に設定する必要はありません。デフォルトでは、Scalaのビルドツールがプロジェクトの依存関係を管理するため、ユーザーは手動でパッケージをインストールする必要がありません。例えば、`sbt`ビルドツールを使用する場合、`build.sbt`ファイルの`libraryDependencies`設定で依存関係を指定し、 + +``` +cd myapp +sbt compile +``` + +以上のコマンドを実行することで、その特定のプロジェクトに必要なすべての依存関係が自動的に解決されます。 +ダウンロードされた依存関係の場所は、主にビルドツールの実装の詳細であり、ユーザーはこれらのダウンロードされた依存関係と直接やりとりする必要はありません。 +例えば、sbtの依存関係キャッシュ全体を削除した場合、プロジェクトの次のコンパイル時には、sbtが自動的に必要な依存関係をすべて解決し、ダウンロードし直します。 +これはPythonとは異なります。Pythonではデフォルトで依存関係がシステム全体またはユーザー全体のディレクトリにインストールされるため、プロジェクトごとに独立した環境を取得するには、対応する仮想環境を作成する必要があります。 +例えば、`venv`モジュールを使用して、特定のプロジェクト用に次のように仮想環境を作成できます。 + +``` +cd myapp +python3 -m venv myapp-env +source myapp-env/bin/activate +pip install -r requirements.txt +``` + +これにより、プロジェクトの `myapp/myapp-env` ディレクトリにすべての依存関係がインストールされ、シェル環境変数 `PATH` が変更されて、依存関係が `myapp-env` から参照されるようになります。 +Scalaでは、このような手動での作業は一切必要ありません。 + +[collections-classes]: {% link _overviews/scala3-book/collections-classes.md %} +[concurrency]: {% link _overviews/scala3-book/concurrency.md %} +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[control-structures]: {% link _overviews/scala3-book/control-structures.md %} +[extension-methods]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[fp-intro]: {% link _overviews/scala3-book/fp-intro.md %} +[hofs]: {% link _overviews/scala3-book/fun-hofs.md %} +[intersection-types]: {% link _overviews/scala3-book/types-intersection.md %} +[main-method]: {% link _overviews/scala3-book/methods-main-methods.md %} +[modeling-intro]: {% link _overviews/scala3-book/domain-modeling-intro.md %} +[multiversal]: {% link _overviews/scala3-book/ca-multiversal-equality.md %} +[toplevel]: {% link _overviews/scala3-book/taste-toplevel-definitions.md %} +[type-classes]: {% link _overviews/scala3-book/ca-type-classes.md %} +[union-types]: {% link _overviews/scala3-book/types-union.md %} +
      diff --git a/_ja/overviews/scala3-book/scala4x.css b/_ja/overviews/scala3-book/scala4x.css new file mode 100644 index 0000000000..1772c03ac8 --- /dev/null +++ b/_ja/overviews/scala3-book/scala4x.css @@ -0,0 +1,54 @@ + + + diff --git a/_ja/scala3/contribute-to-docs.md b/_ja/scala3/contribute-to-docs.md new file mode 100644 index 0000000000..90b123e08f --- /dev/null +++ b/_ja/scala3/contribute-to-docs.md @@ -0,0 +1,62 @@ +--- +layout: singlepage-overview +overview-name: "Scala 3 Documentation" +title: Contributing to the Docs +language: ja +scala3: true +--- + +## 概要 +Scala 3 の高品質なドキュメンテーションを作るためのいくつかの試みが目下進行中である。 +特に次のようなドキュメントがある。 + +- Scala 3 book +- Macros tutorial +- Migration guide +- Scala 3 language reference + +ドキュメンテーションの種類に関わらずコミュニティからのコントリビューションを歓迎する。 + + +### コントリビューションの仕方 +さまざまな方法で私たちを支援することができる : +- **ドキュメントのどこかで混乱するところがある** Issue をたてる。 +- **最新の状態を反映していないドキュメントがある** Issue をたてるか、PR をつくる。 +- **タイポの修正やその他ちょっとした文章の改善** PR をつくる。 +- **なにかを新しく追加したり大きな変更を加えたい** 議論できるよう Issue をたてる。 + +通常、ドキュメントプロジェクトのそれぞれには編集・改善用のリンクが含まれている。(このドキュメントについても同様で、目次の領域にある。) また、コントリビューションをはじめるために必要な情報は以下に記載されている。 + +## Scala 3 Book +[Scala 3 Book][scala3-book] は Alvin Alexander 氏 が書いている。 この本は Scala 3 のすべての重要な機能の概説書である。これから Scala を使いはじめる読者を対象にしている。 + +- [Sources](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-book) +- [Issues](https://github.com/scala/docs.scala-lang/issues) + +## Macros Tutorial +[Macros Tutorial](/scala3/guides/macros)は Nicolas Stucki 氏 が書いている。この本では Scala 3 のマクロとそのベストプラクティスについて詳しく説明している。 + +- [Sources](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-macros) +- [Issues](https://github.com/scala/docs.scala-lang/issues) + +## Migration Guide +[Scala 3 Migration Guide](/scala3/guides/migration/compatibility-intro.html) は Scala 2 と Scala 3 の互換性、移行に役立つツールの紹介、そして詳しい移行のガイドを含んだ包括的なドキュメントである。 + +- [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration) +- [Issues](https://github.com/scalacenter/docs.scala-lang/issues) + +## Scala 3 Contributing Guide +[Scala 3 Contributing Guide](/scala3/guides/contribution/contribution-intro.html) +Scala 3 コンパイラとライブラリへの貢献と内部に関する包括的な概要が含まれています + +- [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution) +- [Issues](https://github.com/scala/docs.scala-lang/issues) + +## Scala 3 Language Reference +The [Dotty reference]({{ site.scala3ref }}/overview.html) は Scala 3 になる予定である。これにはさまざまな言語仕様に関する公式のプレゼンテーションや技術的情報が含まれている。 + +- [Sources](https://github.com/scala/scala3/tree/main/docs/_docs) +- [Issues](https://github.com/scala/scala3/issues) + + +[scala3-book]: {% link _overviews/scala3-book/introduction.md %} diff --git a/_ja/scala3/index.md b/_ja/scala3/index.md new file mode 100644 index 0000000000..31d285d6a5 --- /dev/null +++ b/_ja/scala3/index.md @@ -0,0 +1,44 @@ +--- +layout: landing-page +title: Documentation for Scala 3 +language: ja +namespace: root +scala3: true +discourse: true +# Content masthead links +more-resources-label: More Resources +sections: + + - title: "First steps" + links: + - title: "Scala 3 の新機能" + description: "Scala 3 で追加されたさまざまな新機能の概要" + icon: "fa fa-star" + link: /ja/scala3/new-in-scala3.html + - title: "入門" + description: "あなたのコンピューターにScala 3 をインストールしてScalaコードを書きはじめよう!" + icon: "fa fa-rocket" + link: /ja/scala3/getting-started.html + - title: "Scala 3 Book" + description: "主要な言語仕様のイントロダクションをオンラインブックで読む" + icon: "fa fa-book" + link: /scala3/book/introduction.html + - title: "More detailed information" + links: + - title: "Migration Guide" + description: "Scala 2 から Scala 3 へ移行するためのガイド" + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "Guides" + description: "Scala 3 の言語仕様からピックアップして解説" + icon: "fa fa-map" + link: /ja/scala3/guides.html + - title: "API" + description: "Scala 3 の全バージョンのAPIドキュメント" + icon: "fa fa-file-alt" + link: https://scala-lang.org/api/3.x/ + - title: "Language Reference" + description: "Scala 3 の言語仕様" + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference +--- diff --git a/_ja/scala3/new-in-scala3.md b/_ja/scala3/new-in-scala3.md new file mode 100644 index 0000000000..6022519757 --- /dev/null +++ b/_ja/scala3/new-in-scala3.md @@ -0,0 +1,128 @@ +--- +layout: singlepage-overview +title: New in Scala 3 +scala3: true +--- + +Scala 3 は Scala 2 から大幅な改善が行われ、さまざまな新機能が追加されている。 +ここでは Scala 3 の特に重要な変更点を概観する。 + +より詳しく知りたい方は以下の参考リンクを参照。 + +- [Scala 3 Book]({% link _overviews/scala3-book/introduction.md %}) は Scala を書いたことがない開発者向けに書かれている。 +- [Syntax Summary][syntax-summary] では Scala 3 で新しく追加されたシンタックスを解説している。 +- [Language Reference][reference] を見ればScala 2 と Scala 3 の変更点を詳しく確認できる。 +- Scala 2 から Scala 3 への移行を考えている方は[Migration Guide][migration] を参照。 +- [Scala 3 Contributing Guide][contribution] は、問題を修正するためのガイドを含め、コンパイラーをさらに深く掘り下げます。 + +## What's new in Scala 3 +Scala 3 は Scala 2 を徹底的に見直して再設計されている。核心部分で、型システムの多くの面が変更されより原理原則に基づいたものになった。この変更によって新機能(ユニオン型)が使えるようになったことにくわえて、なにより型システムがさらに使いやすくなった。 例えば、[型推論][type-inference] や overload resolution が改善された. + +### 新機能 & 特長: 文法 +(重要度の低い)多くの文法の整理に加えて、Scala 3 の文法は次のように改善された。 + +- 制御構造( `if`, `while`, や `for`)を書く際に括弧を省略してより簡潔に書けるようになった。 ([new control syntax][syntax-control]) +- `new` キーワードがオプショナルになった。 (_aka_ [creator applications][creator]) +- [Optional braces][syntax-indentation]: クロージャを中括弧`{}`ではなくインデントで表現できるようになった。 +- [ワイルドカード型][syntax-wildcard] が `_` から `?` に変更された。 +- Implicitsとその文法が [大幅に修正][implicits]された。 + +### Opinionated: Contextual Abstractions +それぞれを組み合わせることで高い(そして時には見たこともないような)表現力を発揮する一連の強力な機能をユーザーにあたえることがScalaの当初のコアコンセプトとしてあった。(これは今でもある程度は当てはまる。) 例えば _implicit_ の機能は、コンテキストの受け渡し、型レベル演算、型クラス、暗黙の変換、既存クラスの拡張メソッドなどに使われている。 + +これらのユースケースを参考にして、Scala 3 では少し違ったアプローチをとっている。Scala 3 では、`implicit`がどのようなメカニズムによるものか、ということよりもどのような意図で使われるのかに焦点を当てている。 + +Scala 3 ではひとつの強力な機能として`implicit`を提供するのではなく、開発者がその意図を表現しやすいように複数の異なる言語機能として提供している。 + +- **Abtracting over contextual information**. [Using clauses][contextual-using]を使って呼び出し時に利用可能で、暗黙に引き渡されるべき情報を抽象化することができる。Scala 2 からの改善としては、`using` 節が型だけで指定できるようになったことが挙げられる。 これによって明示的に参照されることのない関数の引数に命名する必要がなくなった。 +- **Providing Type-class instances**. [Given instances][contextual-givens] を使ってある型に対応する _canonical value_ を定義することができる。実装を公開することなく、型クラスを使ったプログラミングをよりわかりやすく書ける。 + +- **Retroactively extending classes**. Scala 2 では拡張メソッドは暗黙の変換か implicit classを使って書くことができた. 一方 Scala 3 では [extension methods][contextual-extension] が直接的に言語仕様に含まれているのでよりわかりやすいエラーメッセージを表示できる。型推論も改善された。 +- **Viewing one type as another**. 暗黙の変換は型クラス`Conversion`のインスタンスとしてゼロから [再設計][contextual-conversions]された。 +- **Higher-order contextual abstractions**. 全く新しい機能である [context functions][contextual-functions] は暗黙の引数をとる関数型を第一級オブジェクトとして扱う。この機能はライブラリ作者にとって重要である。また、簡潔なドメイン特化言語(DSL)を記述するのにも役立つ。 + +- **Actionable feedback from the compiler**. コンパイラが暗黙の引数の解決に失敗した場合、解決に役立つ [import suggestions](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html) を提示する。 + +### Say What You Mean: 型システムの改善 +型推論の大幅な改善に加えて、 Scala 3 の型システムは他にも様々な新機能がある。これらの機能は型で不変な値を静的に表現するパワフルな手段を提供する。 + +- **Enumerations**. [Enums][enums] は case class と上手く組み合わせられるよう、また代数的データ型[algebraic data types][enums-adts]の新しい標準をつくるために再設計された + +- **Opaque Types**. [opaque type aliases][types-opaque]を使うとパフォーマンス低下の懸念なしに実装の詳細を隠ぺいできる。 Opaque types は値クラスにとってかわる概念だ。Opaque types を使うと Boxing のオーバーヘッドを起こすことなく抽象化のバリアを設定できる。 + +- **Intersection and union types**. 型システムの基盤を刷新したことで、新しい型システムの機能が使えるようになった: 交差型 [intersection types][types-intersection](`A & B` と表記する)のインスタンスは `A` でありかつ `B`であるような型のインスタンスだ。 合併型[union types][types-union](`A | B` と表記する) のインスタンスは `A`または`B`のどちらか一方の型のインスタンスだ。 これらの2つの構成体は開発者が継承ヒエラルキー以外の方法で柔軟に型制約を表現できるようにする。 + +- **Dependent function types**. Scala 2 ではすでに引数の型に応じて返り値の型を変化させることができました。Scala 3 ではこのパターンをさらに抽象化することができ、[dependent function types][types-dependent]を表現することができる。 つまり `type F = (e: Entry) => e.Key` というふうに、返り値の型が引数によって変化するように書けます。 + +- **Polymorphic function types**. dependent function types のように Scala 2 では型パラメータを受け取るメソッドを定義することができました。 しかし、開発者はこれらのメソッドをさらに抽象化することはできませんでした。Scala 3 では、`[A] => List[A] => List[A]` といった書き方をする[polymorphic function types][types-polymorphic] を使って引数に加えて型引数をとるような関数を抽象化できる。 + +- **Type lambdas**. Scala 2 で[compiler plugin](https://github.com/typelevel/kind-projector)を使わないと表現できなかった型ラムダは Scala 3 では第一級の機能としてサポートされている。: 型ラムダは補助的な型を定義しないでも高階型引数として引数を受け渡せる型レベルの関数である。 +- **Match types**. 暗黙の型解決を使って型レベル演算をエンコードする代わりに、Scala 3 では型のパターンマッチング[matching on types][types-match]をサポートしている。 型レベルの演算を型チェックと統合することでエラーメッセージをわかりやすく改善し、また複雑なエンコーディングをしなくていいようにしている。 + + +### 再構想: オブジェクト指向プログラミング +Scala は常に関数型プログラミングとオブジェクト指向プログラミングの間のフロンティアにある。そして Scala 3 はその境界を両方に広げます。 +先に言及した型システムの変更と contextual abtstractions の再設計によって、関数型プログラミングを以前にも増して簡単に書けるようになった。 +同時に、次に掲げる新機能を使うと _オブジェクト指向設計_ をうまく構造化してベストプラクティスを実践しやすくなる。 +- **Pass it on**. Trait は class のように 引数をとれるようになった。詳しくは [parameters][oo-trait-parameters] をご覧ください。 これによって trait はソフトウェアをモジュールに分解するツールとしてよりいっそうパワフルになった。 +- **Plan for extension**. 継承を意図していないクラスが継承されてしまうことはオブジェクト指向設計において長年の問題でした。この問題に対処するため Scala 3 では [open classes][oo-open]の概念を導入することで _明示的に_ クラスを継承可能であるとしめすようライブラリ作者に要求するようにしました。 +- **Hide implementation details**. ふるまいを実装した Utility traits は推論される型に含まれるべきでない場合がある。Scala 3 ではそのようなtraitsに [transparent][oo-transparent] とマークすることで継承をユーザーに公開しないようにすることができる。 +- **Composition over inheritance**. このフレーズはしばしば引用されるが、実装するのは面倒だ。 しかし Scala 3 の [export clauses][oo-export]を使えば楽になる。imports と対称的に、 export clauses はオブジェクトの特定のメンバーへアクセスするためのエイリアスを定義する。 +- **No more NPEs**. Scala 3 はかつてないほど null 安全だ。: [explicit null][oo-explicit-null] によって `null` を型ヒエラルキーの外側に追い出しました。これによってエラーを静的にキャッチしやすくなる。また、 [safe initialization][oo-safe-init]の追加的なチェックで初期化されていないオブジェクトへのアクセスを検知できる。 + +### Batteries Included: メタプログラミング +Scala 2 のマクロはあくまで実験的な機能という位置づけだが、Scala 3 ではメタプログラミングに役立つ強力なツールが標準ライブラリに入っている。 + + [macro tutorial]({% link _overviews/scala3-macros/tutorial/index.md %}) のページに異なった機能についての詳しい情報がある。特に Scala 3 は次のようなメタプログラミングのための機能を提供している。 + +- **Inline**. [inline][meta-inline] を使うことで値やメソッドをコンパイル時に評価できる。 このシンプルな機能はさまざまなユースケースに対応している。また同時に`inline`はより高度な機能のエントリーポイントとしても使える。 +- **Compile-time operations**. [`scala.compiletime`][meta-compiletime] パッケージには inline method を実装するのに役立つ追加的な機能が含まれている。 +- **Quoted code blocks**. Scala 3 には [quasi-quotation][meta-quotes]という新機能がある。この機能を使えば扱いやすい高レベルなインターフェースを介してコードを組み立てたり分析したりすることができる。 `'{ 1 + 1 }` と書くだけで1 と 1 を足すASTを組み立てられる。 +- **Reflection API**. もっと高度なユースケースでは [quotes.reflect][meta-reflection]を使ってより細かくプログラムツリーを操作したり生成したりすることができる。 + + +Scala 3 のメタプログラミングについてもっと知りたいかたは、 こちらの[tutorial][meta-tutorial]を参照。 + + +[enums]: {{ site.scala3ref }}/enums/enums.html +[enums-adts]: {{ site.scala3ref }}/enums/adts.html + +[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html +[types-union]: {{ site.scala3ref }}/new-types/union-types.html +[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html +[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html +[types-match]: {{ site.scala3ref }}/new-types/match-types.html +[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html + +[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html +[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html +[reference]: {{ site.scala3ref }}/overview.html +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %} +[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %} + +[implicits]: {{ site.scala3ref }}/contextual +[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html +[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html +[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html +[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html +[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html + +[syntax-summary]: {{ site.scala3ref }}/syntax.html +[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html +[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html +[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html + +[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %} +[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %} + +[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html +[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html +[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html +[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html +[oo-export]: {{ site.scala3ref }}/other-new-features/export.html diff --git a/_ja/tour/abstract-type-members.md b/_ja/tour/abstract-type-members.md new file mode 100644 index 0000000000..af08eb5c2b --- /dev/null +++ b/_ja/tour/abstract-type-members.md @@ -0,0 +1,73 @@ +--- +layout: tour +title: 抽象型メンバー +language: ja +partof: scala-tour +num: 23 +next-page: compound-types +previous-page: inner-classes +topics: abstract type members +prerequisite-knowledge: variance, upper-type-bound +--- + +トレイトや抽象クラスのような抽象型は抽象型メンバーを持つことができます。 +これは具体的な実装で実際の型を定義するという意味です。 +こちらが例です。 + +```scala mdoc +trait Buffer { + type T + val element: T +} +``` +こちらでは、抽象型`type T`を定義しています。それは`element`の型を記述するために使われます。このトレイトを抽象クラスで継承し、より具体的にするために上限型境界を`T`に追加することができます。 + +```scala mdoc +abstract class SeqBuffer extends Buffer { + type U + type T <: Seq[U] + def length = element.length +} +``` +`T`の上限型境界の定義に出てきた、更に別の抽象型`U`の使い方に気をつけてください。この`class SeqBuffer`はこのバッファーの中にシーケンスのみを保持することができます。それは型`T`は新しい抽象型`U`を使った`Seq[U]`のサブタイプであると記述しているからです。 + +抽象型メンバーを持つトレイトと[クラス](classes.html)は無名クラスのインスタンス化と組み合わせてよく使われます。 +これを説明するために、今から整数のリストを参照するシーケンスバッファーを扱うプログラムを見てみます。 + +```scala mdoc +abstract class IntSeqBuffer extends SeqBuffer { + type U = Int +} + + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +ここで、ファクトリー`newIntSeqBuf`は抽象型`T`を具体的な型`List[Int]`に設定するために、`IntSeqBuf`(つまり`new IntSeqBuffer`)を無名クラスで実装します。 + +抽象型メンバーをクラスの型パラメータに変えることも、その逆も可能です。以下は上記コードの型パラメータのみを使うバージョンです。 + +```scala mdoc:nest +abstract class Buffer[+T] { + val element: T +} +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { + def length = element.length +} + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +ここでは(`+T <: Seq[U]`)をメソッド`newIntSeqBuf`から戻されるオブジェクトの具体的なシーケンス実装の型を隠すために [変位指定アノテーション](variances.html)を使わなければなりません。さらに、抽象型メンバをパラメータで置換することができないケースがあります。 diff --git a/_ja/tour/annotations.md b/_ja/tour/annotations.md new file mode 100644 index 0000000000..90545140fc --- /dev/null +++ b/_ja/tour/annotations.md @@ -0,0 +1,124 @@ +--- +layout: tour +title: アノテーション +language: ja +partof: scala-tour +num: 32 +next-page: packages-and-imports +previous-page: by-name-parameters +--- + +アノテーションはメタ情報と定義を関連づけます。例えば、メソッドの前のアノテーション`@deprecated`はメソッドが使われたらコンパイラに警告を出力させます。 +``` +object DeprecationDemo extends App { + @deprecated("deprecation message", "release # which deprecates method") + def hello = "hola" + + hello +} +``` +これはコンパイルされますが、コンパイラは警告"there was one deprecation warning"を出力します。 + +アノテーション句はそれに続く最初の定義か宣言に適用されます。定義と宣言の前には1つ以上のアノテーション句を置くことができます。これらの句の順番は重要ではありません。 + + +## エンコーディングの正確性を保証するアノテーション +条件が一致しない場合にコンパイルを失敗させるアノテーションもあります。例えば、アノテーション`@tailrec`はメソッドが[末尾再帰](https://en.wikipedia.org/wiki/Tail_call)であると保証します。末尾再帰ではメモリ使用量が一定になります。こちらは階乗を計算するメソッドの中での使われ方です。 +```scala mdoc +import scala.annotation.tailrec + +def factorial(x: Int): Int = { + + @tailrec + def factorialHelper(x: Int, accumulator: Int): Int = { + if (x == 1) accumulator else factorialHelper(x - 1, accumulator * x) + } + factorialHelper(x, 1) +} +``` +`factorialHelper`メソッドは`@tailrec`を持ちます。`@tailrec`はメソッドが実際に末尾再帰であると保証します。もし`factorialHelper`の実装を以下のように変更すれば、失敗し +``` +import scala.annotation.tailrec + +def factorial(x: Int): Int = { + @tailrec + def factorialHelper(x: Int): Int = { + if (x == 1) 1 else x * factorialHelper(x - 1) + } + factorialHelper(x) +} +``` +"Recursive call not in tail position"というメッセージを受け取ります。 + + +## コード生成に影響するアノテーション +`@inline`のようなアノテーションは生成されたコードに影響します(つまり、アノテーションを使わなかった場合とでjarファイルのバイト数が異なる場合があります)。インライン化とは、メソッドを呼び出している箇所にメソッド本体のコードを挿入することを意味します。結果のバイトコードはより長くなりますが、上手くいけば実行が早くなります。アノテーション`@inline`を使ってもメソッドのインライン化が保証されるわけではありません。しかし、生成されたコードのサイズに関するヒューリスティックスが満たされた場合に限りコンパイラにインライン化をさせます。 + +### Javaのアノテーション ### +Javaと相互運用するScalaのコードを書いている時、記述するアノテーション構文は少し違います。 + +**注:** Javaアノテーションを使う場合、`-target:jvm-1.8`オプションを使ってください。 + +Javaには[アノテーション](https://docs.oracle.com/javase/tutorial/java/annotations/)の形をしたユーザー定義メタデータがあります。Javaのアノテーションの特徴は、要素の初期化のために名前と値のペアを指定する必要があることです。例えば、クラスのソースを追いかけるためのアノテーションが必要なとき、以下のように定義するかもしれません。 + +``` +@interface Source { + public String URL(); + public String mail(); +} +``` + +そして、それは以下のように適用されます。 + +``` +@Source(URL = "https://coders.com/", + mail = "support@coders.com") +public class MyClass extends TheirClass ... +``` + +Scalaでのアノテーションの適用はコンストラクタの呼び出しと似ています。Javaのアノテーションをインスタンス化するためには名前付き引数を使う必要があります。 + +``` +@Source(URL = "https://coders.com/", + mail = "support@coders.com") +class MyScalaClass ... +``` + +アノテーションが(デフォルト値を除き)要素を1つだけ含む場合、この構文はかなり退屈です。そのため慣例により、名前が`value`と指定されていれば、コンストラクタのような構文でJavaに適用できます。 + +``` +@interface SourceURL { + public String value(); + public String mail() default ""; +} +``` + +そして以下のように適用します。 + +``` +@SourceURL("https://coders.com/") +public class MyClass extends TheirClass ... +``` + +この場合、Scalaでも同じことができます。 + +``` +@SourceURL("https://coders.com/") +class MyScalaClass ... +``` + +`mail`要素はデフォルト値つきで定義されているので、明示的に値を指定する必要がありません。しかしながら、もし値を指定する必要がある場合、Javaでは2つのスタイルを混ぜて組み合わせることはできません。 + +``` +@SourceURL(value = "https://coders.com/", + mail = "support@coders.com") +public class MyClass extends TheirClass ... +``` + +Scalaはこの点においてより柔軟です。 + +``` +@SourceURL("https://coders.com/", + mail = "support@coders.com") + class MyScalaClass ... +``` diff --git a/_ja/tour/basics.md b/_ja/tour/basics.md new file mode 100644 index 0000000000..1f109c930d --- /dev/null +++ b/_ja/tour/basics.md @@ -0,0 +1,307 @@ +--- +layout: tour +title: 基本 +language: ja +partof: scala-tour +num: 2 +next-page: unified-types +previous-page: tour-of-scala +--- + +このページでは、Scalaの基本を取り扱います。 + +## Scalaをブラウザで試してみる + +Scastieを利用することでブラウザ上でScalaを実行することができます。 + +1. [Scastie](https://scastie.scala-lang.org/)を開きます。 +2. 左側のパネルに`println("Hello, world!")`を貼り付けます。 +3. "Run"ボタンを押すと、右側のパネルに出力が表示されます。 + +このサイトを使えば、簡単にセットアップせずScalaのコードの一部を試すことができます。 + +## 式 + +式は計算可能な文です。 + +```scala mdoc +1 + 1 +``` +`println`を使うことで、式の結果を出力できます。 + +```scala mdoc +println(1) // 1 +println(1 + 1) // 2 +println("Hello!") // Hello! +println("Hello," + " world!") // Hello, world! +``` + +### 値 + +`val`キーワードを利用することで、式の結果に名前を付けることができます。 + +```scala mdoc +val x = 1 + 1 +println(x) // 2 +``` + +ここでいうところの `x` のように、名前をつけられた結果は 値 と呼ばれます。 +値を参照した場合、その値は再計算されません。 + +値は再代入することができません。 + +```scala mdoc:fail +x = 3 // この記述はコンパイルされません。 +``` + +値の型は推測可能ですが、このように型を明示的に宣言することもできます。 + +```scala mdoc:nest +val x: Int = 1 + 1 +``` + +型定義では`Int` は識別子`x`の後にくることに注意してください。そして`:`も必要となります。 + +### 変数 + +再代入ができることを除けば、変数は値と似ています。 +`var`キーワードを使うことで、変数は定義できます。 + +```scala mdoc:nest +var x = 1 + 1 +x = 3 // "x"は"var"キーワードで宣言されているので、これはコンパイルされます。 +println(x * x) // 9 +``` + +値と同様に、型を宣言したければ、明示的に型を宣言することができます。 + +```scala mdoc:nest +var x: Int = 1 + 1 +``` + + +## ブロック + +`{}`で囲むことで式をまとめることができます。これをブロックと呼びます。 + +ブロックの最後の式の結果はブロック全体の結果にもなります。 + +```scala mdoc +println({ + val x = 1 + 1 + x + 1 +}) // 3 +``` + +## 関数 + +関数はパラメーターを受け取る式です。 +ここでは与えられた数値に1を足す無名関数（すなわち名前が無い関数）を宣言しています。 + +```scala mdoc +(x: Int) => x + 1 +``` +`=>` の左側はパラメーターのリストです。右側はパラメーターを含む式です。 + +関数には名前をつけることもできます。 + +```scala mdoc +val addOne = (x: Int) => x + 1 +println(addOne(1)) // 2 +``` + +関数は複数のパラメーターをとることもできます。 + +```scala mdoc +val add = (x: Int, y: Int) => x + y +println(add(1, 2)) // 3 +``` + +またパラメーターを取らないこともありえます。 + +```scala mdoc +val getTheAnswer = () => 42 +println(getTheAnswer()) // 42 +``` + +## メソッド + +メソッドは関数と見た目、振る舞いがとても似ていますが、それらには違いがいくつかあります。 + +メソッドは `def` キーワードで定義されます。 `def` の後ろには名前、パラメーターリスト、戻り値の型、処理の内容が続きます。 + +```scala mdoc:nest +def add(x: Int, y: Int): Int = x + y +println(add(1, 2)) // 3 +``` + +戻り値の型は引数リストとコロンの「後ろ」に宣言することに注意してください。`: Int` + +メソッドは複数のパラメーターリストを受け取ることができます。 + +```scala mdoc +def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier +println(addThenMultiply(1, 2)(3)) // 9 +``` + +また、パラメーターリストを一切受け取らないこともあります。 + +```scala mdoc +def name: String = System.getProperty("user.name") +println("Hello, " + name + "!") +``` +メソッドと関数には他にも違いがありますが、今のところは同じようなものと考えて大丈夫です。 + +メソッドは複数行の式も持つことができます。 + +```scala mdoc +def getSquareString(input: Double): String = { + val square = input * input + square.toString +} +println(getSquareString(2.5)) // 6.25 +``` + +メソッド本体にある最後の式はメソッドの戻り値になります。(Scalaには`return`キーワードはありますが、めったに使われません。) + +## クラス + +`class` キーワードとその後ろに名前、コンストラクタパラメーターを続けることで、クラスを定義することができます。 + +```scala mdoc +class Greeter(prefix: String, suffix: String) { + def greet(name: String): Unit = + println(prefix + name + suffix) +} +``` +`greet` メソッドの戻り値の型は`Unit`です。`Unit`は戻り値として意味がないことを示します。 +それはJavaやC言語の`void`と似たような使われ方をします。（`void`との違いは、全てのScalaの式は値を持つ必要があるため、 +実はUnit型のシングルトンで`()`と書かれる値があります。その値には情報はありません。） + +`new` キーワードを使うことで、クラスのインスタンスを生成することができます。 + +```scala mdoc +val greeter = new Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` + +クラスについては[後で](classes.html)詳しく取り扱います。 + +## ケースクラス + +Scalaには"ケース"クラスという特別な種類のクラスがあります。デフォルトでケースクラスは不変であり、値で比較されます。 +`case class` キーワードを利用して、ケースクラスを定義できます。 + +```scala mdoc +case class Point(x: Int, y: Int) +``` +ケースクラスは、`new` キーワードなしでインスタンス化できます。 + +```scala mdoc +val point = Point(1, 2) +val anotherPoint = Point(1, 2) +val yetAnotherPoint = Point(2, 2) +``` + +ケースクラスは値で比較されます。 + +```scala mdoc +if (point == anotherPoint) { + println(s"$point と $anotherPoint は同じです。") +} else { + println(s"$point と $anotherPoint は異なります。") +} // Point(1,2) と Point(1,2) は同じです。 + +if (point == yetAnotherPoint) { + println(s"$point と $yetAnotherPoint は同じです。") +} else { + println(s"$point と $yetAnotherPoint は異なります。") +} // Point(1,2) と Point(2,2) は異なります。 +``` + +ケースクラスについて紹介すべきことはたくさんあり、あなたはケースクラスが大好きになると確信しています！ +それらについては[後で](case-classes.html)詳しく取り扱います。 + +## オブジェクト + +オブジェクトはそれ自体が定義である単一のインスタンスです。そのクラスのシングルトンと考えることもできます。 + +`object`キーワードを利用してオブジェクトを定義することができます。 + +```scala mdoc +object IdFactory { + private var counter = 0 + def create(): Int = { + counter += 1 + counter + } +} +``` + +名前を参照してオブジェクトにアクセスすることができます。 + +```scala mdoc +val newId: Int = IdFactory.create() +println(newId) // 1 +val newerId: Int = IdFactory.create() +println(newerId) // 2 +``` + +オブジェクトについては [後で](singleton-objects.html)詳しく取り扱います。 + +## トレイト + +トレイトはいくつかのフィールドとメソッドを含む型です。複数のトレイトを結合することもできます。 + +`trait`キーワードでトレイトを定義することができます。 + +```scala mdoc:nest +trait Greeter { + def greet(name: String): Unit +} +``` + +トレイトはデフォルトの実装を持つこともできます。 + +```scala mdoc:reset +trait Greeter { + def greet(name: String): Unit = + println("Hello, " + name + "!") +} +``` + +`extends`キーワードでトレイトを継承することも、`override` キーワードで実装をオーバーライドすることもできます。 + +```scala mdoc +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { + override def greet(name: String): Unit = { + println(prefix + name + postfix) + } +} + +val greeter = new DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = new CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` + +ここでは、`DefaultGreeter`は一つのトレイトだけを継承していますが、複数のトレイトを継承することもできます。 + +トレイトについては [後で](traits.html)詳しく取り扱います。 + +## メインメソッド + +メインメソッドはプログラムの始点になります。Javaバーチャルマシーンは`main`と名付けられたメインメソッドが必要で、 +それは文字列の配列を一つ引数として受け取ります。 + +オブジェクトを使い、以下のようにメインメソッドを定義することができます。 + +```scala mdoc +object Main { + def main(args: Array[String]): Unit = + println("Hello, Scala developer!") +} +``` diff --git a/_ja/tour/by-name-parameters.md b/_ja/tour/by-name-parameters.md new file mode 100644 index 0000000000..b88f6dd617 --- /dev/null +++ b/_ja/tour/by-name-parameters.md @@ -0,0 +1,39 @@ +--- +layout: tour +title: 名前渡しパラメータ +language: ja +partof: scala-tour +num: 31 +next-page: annotations +previous-page: operators +--- + +*名前渡しのパラメータ*は使用された時に評価されます。それらは*値渡しパラメータ*とは対照的です。名前渡しのパラメータを作るには、単純に`=>`を型の前につけます。 +```scala mdoc +def calculate(input: => Int) = input * 37 +``` + +名前渡しパラメータの利点は関数本体の中で使わなければ評価されない点です。一方で、値渡しパラメータの利点は1度しか評価されない点です。 + +こちらはwhileループをどのように実装するかの例です。 + +```scala mdoc +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if (condition) { + body + whileLoop(condition)(body) + } + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // prints 2 1 +``` + +このメソッド`whileLoop`は条件とループの本体を受け取るために複数パラメータリストを使います。もし`condition`がtrueならば、`body`が実行され、次にwhileLoopが再帰的に呼ばれます。`condition`がfalseならば、bodyは決して評価されません。それは`body`の型の前に`=>`をつけたからです。 + +ここで、`condition`に`i > 0`、`body`に`println(i); i-= 1`を渡した場合、多くの言語で一般的なwhileループと同じ振る舞いをします。 + +パラメータが使われるまで評価を遅延する機能はパフォーマンスの助けになることがあります。それはパラメータを評価するのに多くの計算が必要な場合や、URLの取得のような時間がかかるコードブロックの場合です。 diff --git a/_ja/tour/case-classes.md b/_ja/tour/case-classes.md new file mode 100644 index 0000000000..2015b843c1 --- /dev/null +++ b/_ja/tour/case-classes.md @@ -0,0 +1,60 @@ +--- +layout: tour +title: ケースクラス +language: ja +partof: scala-tour +num: 11 +next-page: pattern-matching +previous-page: multiple-parameter-lists +prerequisite-knowledge: classes, basics, mutability +--- + +ケースクラスはこれから論じるいくつかの差異はあるものの普通のクラスと似ています。 +ケースクラスは不変なデータを作るのに適しています。 +このツアーの次のステップでは、[パターンマッチング](pattern-matching.html)でのそれらの有用性を解説します。 + +## ケースクラスの宣言 + +最小のケースクラスにはキーワード`case class`、識別子、パラメータリスト(空かもしれません)が必要です。 +```scala mdoc +case class Book(isbn: String) + +val frankenstein = Book("978-0486282114") +``` +ケースクラス`Book`をインスタンス化する時キーワード`new`が使われていないことに気をつけてください。 +これはケースクラスがオブジェクトの生成を行う`apply`メソッドを標準で保有するためです。 + +パラメータ有りでケースクラスを作ると、パラメータはパブリックの`val`となります。 +``` +case class Message(sender: String, recipient: String, body: String) +val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") + +println(message1.sender) // guillaume@quebec.ca が出力されます +message1.sender = "travis@washington.us" // この行はコンパイルされません +``` +`message1.sender` に再代入することはできません、なぜなら`val`（つまりイミュータブル）だからです。 +ケースクラスでは`var`も使うことができますが、推奨されません。 + +## 比較 +ケースクラスは参照ではなく、構造で比較されます。 +``` +case class Message(sender: String, recipient: String, body: String) + +val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val messagesAreTheSame = message2 == message3 // true +``` +たとえ`message2`と`message3`が異なるオブジェクトを参照していたとしても、それぞれのオブジェクトの値は等価となります。 + +## コピー +`copy`メソッドを使うことで簡単にケースクラスのインスタンスの（浅い）コピーを作ることができます。 +必要に応じて、コンストラクタ引数を変更することもできます。 +``` +case class Message(sender: String, recipient: String, body: String) +val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") +val message5 = message4.copy(sender = message4.recipient, recipient = "claire@bourgogne.fr") +message5.sender // travis@washington.us +message5.recipient // claire@bourgogne.fr +message5.body // "Me zo o komz gant ma amezeg" +``` +`message4`のrecipientは`message5`のsenderとして使われますが、`message4`の定数`body`は直接コピーされます。 diff --git a/_ja/tour/classes.md b/_ja/tour/classes.md new file mode 100644 index 0000000000..74bd6c6997 --- /dev/null +++ b/_ja/tour/classes.md @@ -0,0 +1,126 @@ +--- +layout: tour +title: クラス +language: ja +partof: scala-tour +num: 4 +next-page: traits +previous-page: unified-types +topics: classes +prerequisite-knowledge: no-return-keyword, type-declaration-syntax, string-interpolation, procedures +--- + +Scalaにおけるクラスはオブジェクトを作るための設計図です。 +クラスはメソッド、値、変数、型、オブジェクト、トレイト、クラスを持ち、それらはまとめて _メンバー_ と呼ばれます。 +型、オブジェクト、トレイトはツアーで後ほど取り扱います。 + +## クラスを定義する + +最小のクラス定義は単純にキーワード`class`と識別子だけというものです。 +クラス名は大文字から始まるべきです。 + +```scala mdoc +class User + +val user1 = new User +``` +`new`キーワードはクラスのインスタンスを作るために使われます。 +`User`はコンストラクターが定義されていないので、引数なしのデフォルトコンストラクターを持ちます。 +しかしながら、コンストラクターとクラス本体は頻繁に欲しくなるでしょう。 +こちらは位置情報のクラス定義の例になります。 + +```scala mdoc +class Point(var x: Int, var y: Int) { + + def move(dx: Int, dy: Int): Unit = { + x = x + dx + y = y + dy + } + + override def toString: String = + s"($x, $y)" +} + +val point1 = new Point(2, 3) +point1.x // 2 +println(point1) // prints (2, 3) +``` +この`Point`クラスは4つのメンバーを持ちます。 +変数`x` と `y` そしてメソッド `move` と `toString`です。 +多くの他の言語とは異なり、プライマリコンストラクタはクラスのシグネチャ`(var x: Int, var y: Int)`です。 +`move` メソッドは2つの整数の引数を受け取り、情報を持たない Unit 値 `()` を返します。 +これは大雑把に言えば、Javaのような言語における`void`に対応します。 +その一方で`toString`は引数を受け取りませんが、`String`の値を返します。 +`toString`は[`AnyRef`](unified-types.html)の`toString`をオーバーライドしているので、`override`キーワードのタグが付いています。 + +## コンストラクター + +コンストラクターは次のようにデフォルト値を与えると省略可能なパラメーターを持つことができます。 + +```scala mdoc:reset +class Point(var x: Int = 0, var y: Int = 0) + +val origin = new Point // x と y には共に0がセットされます。 +val point1 = new Point(1) +println(point1.x) // 1 が出力されます。 +``` +このバージョンの`Point`クラスでは、`x` と `y` はデフォルト値0を持ち、引数が必須ではありません。 +しかしながらコンストラクタは引数を左から右に読み込むため、もし`y`の値だけを渡したい場合は、パラメーターに名前をつける必要があります。 + +```scala mdoc:reset +class Point(var x: Int = 0, var y: Int = 0) +val point2 = new Point(y=2) +println(point2.y) // 2 が出力されます。 +``` + +これは明快さを高めるための良い習慣でもあります。 + +## プライベートメンバーとゲッター/セッター構文 +メンバーはデフォルトではパブリックになります。 +クラスの外から隠したい場合は`private`アクセス修飾子を使いましょう。 + +```scala mdoc:reset +class Point { + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x = _x + def x_= (newValue: Int): Unit = { + if (newValue < bound) _x = newValue else printWarning + } + + def y = _y + def y_= (newValue: Int): Unit = { + if (newValue < bound) _y = newValue else printWarning + } + + private def printWarning = println("WARNING: Out of bounds") +} + +val point1 = new Point +point1.x = 99 +point1.y = 101 // 警告が出力されます。 +``` +このバージョンの`Point`クラスでは、データはプライベート変数 `_x` と `_y` に保存されます。 +プライベートなデータにアクセスするためのメソッド`def x` と `def y` があります。 +`def x_=` と `def y_=` は `_x` と `_y` の値を検証し設定するためのものになります。 +セッターのための特別な構文に注意してください。 +セッターメソッドはゲッターメソッドの識別子に`_=`を追加し、その後ろにパラメーターを取ります。 + +プライマリコンストラクタの`val` と `var` を持つパラメーターはパブリックになります。 +しかしながら`val` は不変となるため、以下のように記述することはできません。 + +```scala mdoc:fail +class Point(val x: Int, val y: Int) +val point = new Point(1, 2) +point.x = 3 // <-- コンパイルされません。 +``` + +`val` や `var` が存在しないパラメーターはクラス内でだけで参照できるプライベートな値や変数となります。 + +```scala mdoc:fail +class Point(x: Int, y: Int) +val point = new Point(1, 2) +point.x // <-- コンパイルされません。 +``` diff --git a/_ja/tour/compound-types.md b/_ja/tour/compound-types.md new file mode 100644 index 0000000000..2137ecc432 --- /dev/null +++ b/_ja/tour/compound-types.md @@ -0,0 +1,48 @@ +--- +layout: tour +title: 複合型 +language: ja +partof: scala-tour +num: 24 +next-page: self-types +previous-page: abstract-type-members +--- +ときどき、あるオブジェクトの型が、複数の他の型のサブタイプであると表現する必要が生じます。 +Scalaでは、これは*複合型*を用いて表現できます。複合型とはオブジェクトの型同士を重ねることです。 + +2つのトレイト`Cloneable`と`Resetable`があるとしましょう。 + +```scala mdoc +trait Cloneable extends java.lang.Cloneable { + override def clone(): Cloneable = { + super.clone().asInstanceOf[Cloneable] + } +} +trait Resetable { + def reset: Unit +} +``` + +今、関数`cloneAndReset`を書きたいとします。それはオブジェクトを受け取り、それをクローンして、元のオブジェクトをリセットします。 + +``` +def cloneAndReset(obj: ?): Cloneable = { + val cloned = obj.clone() + obj.reset + cloned +} +``` + +パラメータ`obj`の型は何かという疑問が生じます。もし`Cloneable`であれば、オブジェクトを`clone`することができますが、`reset`することはできません。もし`Resetable`であれば、`reset`することができますが、`clone`の操作はできません。そのような状態で型キャストを回避するために`obj`の型を`Cloneable`と`Resetable`の両方であると指定することができます。Scalaではこの複合型は`Cloneable with Resetable`のように書くことができます。 + +こちらが書き変えた関数です。 + +``` +def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { + //... +} +``` +複合型は複数のオブジェクトの型からなり、一つだけの細別型(refinement)を持てます。細別型は既存オブジェクトのメンバーのシグネチャを絞り込むのに使えます。 +一般的な形は`A with B with C ... { refinement }`です。 + +細別の使い方の例は[ミックスインを用いたクラス合成](mixin-class-composition.html)のページにあります。 diff --git a/_ja/tour/default-parameter-values.md b/_ja/tour/default-parameter-values.md new file mode 100644 index 0000000000..499f543566 --- /dev/null +++ b/_ja/tour/default-parameter-values.md @@ -0,0 +1,44 @@ +--- +layout: tour +title: デフォルト引数 +language: ja +partof: scala-tour +num: 33 +next-page: named-arguments +previous-page: annotations +prerequisite-knowledge: named-arguments, function syntax +--- + +Scalaはパラメータのデフォルト値を与えることができ、呼び出す側はこれらのパラメータを省略できます。 + +```scala mdoc +def log(message: String, level: String = "INFO") = println(s"$level: $message") + +log("System starting") // prints INFO: System starting +log("User not found", "WARNING") // prints WARNING: User not found +``` + +パラメータ`level`はデフォルト値を持つので、省略可能です。最終行では、引数`"WARNING"`はデフォルト値`"INFO"`を上書きします。Javaで同じ効果を得るのに、省略可能なパラメータをもつメソッドを複数使ってメソッドのオーバーロードをしたようなものです。しかしながら呼び出す側が引数をひとつ省略すると、以降全ての引数は名前つきにする必要があります。 + +```scala mdoc +class Point(val x: Double = 0, val y: Double = 0) + +val point1 = new Point(y = 1) +``` +ここでは、`y = 1`と書かなければなりません。 + +Scalaで定義したデフォルトパラメータはJavaのコードから呼び出される時はオプショナルではありません。 + +```scala mdoc:reset +// Point.scala +class Point(val x: Double = 0, val y: Double = 0) +``` + +```java +// Main.java +public class Main { + public static void main(String[] args) { + Point point = new Point(1); // コンパイルされません + } +} +``` diff --git a/_ja/tour/extractor-objects.md b/_ja/tour/extractor-objects.md new file mode 100644 index 0000000000..03efef77e3 --- /dev/null +++ b/_ja/tour/extractor-objects.md @@ -0,0 +1,66 @@ +--- +layout: tour +title: 抽出子オブジェクト +language: ja +partof: scala-tour +num: 16 +next-page: for-comprehensions +previous-page: regular-expression-patterns +--- + +抽出子オブジェクトは`unapply`メソッドを持つオブジェクトです。 +`apply`メソッドが引数を取り、オブジェクトを作るコンストラクタであるように、`unapply`は1つのオブジェクトを受け取り、引数を返そうとします。 +これはパターンマッチングと部分関数で最も頻繁に使われます。 + +```scala mdoc +import scala.util.Random + +object CustomerID { + + def apply(name: String) = s"$name--${Random.nextLong()}" + + def unapply(customerID: String): Option[String] = { + val stringArray: Array[String] = customerID.split("--") + if (stringArray.tail.nonEmpty) Some(stringArray.head) else None + } +} + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match { + case CustomerID(name) => println(name) // prints Sukyoung + case _ => println("Could not extract a CustomerID") +} +``` + +`apply`メソッドは`name`から`CustomerID`文字列を作ります。`unapply`は逆に`name`を返します。 + `CustomerID("Sukyoung")`は、`CustomerID.apply("Sukyoung")`を短く書く構文です。 + `case CustomerID(name) => println(name)`では、unapplyメソッドを呼んでいます。 + +値を定義する文で、パターン中に新しい変数を使うことができるので、抽出子は変数を初期化するのに使えます。この場合unapplyメソッドが初期値を与えます。 + +```scala mdoc +val customer2ID = CustomerID("Nico") +val CustomerID(name) = customer2ID +println(name) // prints Nico +``` +これは `val name = CustomerID.unapply(customer2ID).get`と同じです。 + +```scala mdoc +val CustomerID(name2) = "--asdfasdfasdf" +``` +もし一致しない場合`scala.MatchError`が投げられます。 + +```scala mdoc:crash +val CustomerID(name3) = "-asdfasdfasdf" +``` + +`unapply`の戻り値型は以下のように選ばれなければなりません。 + +* ただのテストであれば、`Boolean`を返します。例えば`case even()`。 +* T型のサブバリュー1つを返すのであれば、`Option[T]`を返します。 +* いくつかのサブバリュー`T1,...,Tn`を返したいのであれば、オプショナルタプル`Option[(T1,...,Tn)]`でグループ化します。 + +時々、抽出する値の数が確定せず、入力に応じて任意の数の値を返したいことがあります。 +この場合は、`Option[Seq[T]]`を返す`unapplySeq`メソッドを持つ抽出子を定義することができます。 +これらのパターンと同様の例として以下のものがあります。 +`case List(x, y, z) =>`を使って`List`を分解する例や`case r(name, remainingFields @ _*) =>`.のように正規表現`Regex`を使って`String`を分解する例です。 diff --git a/_ja/tour/for-comprehensions.md b/_ja/tour/for-comprehensions.md new file mode 100644 index 0000000000..1600904350 --- /dev/null +++ b/_ja/tour/for-comprehensions.md @@ -0,0 +1,71 @@ +--- +layout: tour +title: for内包表記 +language: ja +partof: scala-tour +num: 17 +next-page: generic-classes +previous-page: extractor-objects +--- + +Scalaは*シーケンス内包表記*を表現するための軽量な記法を提供します。 +内含表記は`for (enumerators) yield e`という形をとります。`enumerators`はセミコロンで区切られたEnumeratorのリストを指します。 +1つの*enumerator*は新しい変数を導き出すジェネレータかフィルタのどちらかです。 +内包表記はenumeratorsが生成する束縛一つ一つについて本体`e`を評価し、これらの値のシーケンスを返します。 + +こちらは例です。 + +```scala mdoc +case class User(name: String, age: Int) + +val userBase = List(User("Travis", 28), + User("Kelly", 33), + User("Jennifer", 44), + User("Dennis", 23)) + +val twentySomethings = for (user <- userBase if (user.age >=20 && user.age < 30)) + yield user.name // これをリストに追加する + +twentySomethings.foreach(name => println(name)) // prints Travis Dennis +``` +この`yield`文と一緒に使われている`for`ループは実際には`List`を生成します。 +`yield user.name`を返しているので、型は`List[String]`になります。 +`user <- userBase`はジェネレータであり、`if (user.age >=20 && user.age < 30)`は20代ではないユーザーをフィルターするガードです。 + +こちらは2つのジェネレータを使ったより複雑な例です。 +合計が与えられた値`v`と等しくなる、`0`から`n-1`の全てのペアを計算します。 + +```scala mdoc +def foo(n: Int, v: Int) = + for (i <- 0 until n; + j <- 0 until n if i + j == v) + yield (i, j) + +foo(10, 10) foreach { + case (i, j) => + println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) +} + +``` +この例では`n == 10`で`v == 10`です。最初のイテレーションでは`i == 0`かつ`j == 0`で、`i + j != v`となるので、何も生成されません。 +`i`が`1`にインクリメントされるまでに、`j`はあと9回インクリメントされます。`if`ガードがなければ、単純に以下の内容が表示されます。 + +``` + +(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... +``` +内包表記はリストだけのものではありません。 +操作 `withFilter`、`map`、`flatMap`を（適切な型で）サポートする全てのデータ型は、シーケンス内包表記で使うことができます。 + +内包表記の中では`yield`を省略することができます。その場合、内包表記は`Unit`を返します。 +これは副作用をもたらす必要があるときに役立ちます。 +こちらは先に出たプログラムと同等のものですが、`yield`を使っていません。 + +```scala mdoc:nest +def foo(n: Int, v: Int) = + for (i <- 0 until n; + j <- 0 until n if i + j == v) + println(s"($i, $j)") + +foo(10, 10) +``` diff --git a/_ja/tour/generic-classes.md b/_ja/tour/generic-classes.md new file mode 100644 index 0000000000..ad944b8b39 --- /dev/null +++ b/_ja/tour/generic-classes.md @@ -0,0 +1,62 @@ +--- +layout: tour +title: ジェネリッククラス +language: ja +partof: scala-tour +num: 18 +next-page: variances +previous-page: for-comprehensions +assumed-knowledge: classes unified-types +--- +ジェネリッククラスはパラメータとして型を1つ受け取るクラスです。それらはコレクションクラスで特に役立ちます。 + +## ジェネリッククラスの定義 +ジェネリッククラスは角カッコ`[]`の中にパラメータとして型を1つ受け取ります。 +型パラメータの識別子として文字`A`を使う習慣がありますが、任意のパラメータ名を使うことができます。 +```scala mdoc +class Stack[A] { + private var elements: List[A] = Nil + def push(x: A): Unit = + elements = x :: elements + def peek: A = elements.head + def pop(): A = { + val currentTop = peek + elements = elements.tail + currentTop + } +} +``` +この`Stack`クラスの実装はパラメータとして任意の型`A`を受け取ります。 +これはメンバーのリスト`var elements: List[A] = Nil`が型`A`の要素のみを格納できることを意味します。 +手続き`def push`は型`A`のオブジェクトのみを受け取ります +(注: `elements = x :: elements`は、`x`を現在の`elements`の先頭に追加した新しいリストを`elements`に割り当て直します)。 + +ここで `Nil` は空の `List` であり、 `null` と混同してはいけません。 + +## 使い方 + +ジェネリッククラスを使うには、角カッコの中に`A`の代わりに型を入れます。 +``` +val stack = new Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop) // prints 2 +println(stack.pop) // prints 1 +``` +インスタンス`stack`はIntのみを受け取ることができます。 +しかしながら、型がサブタイプを持つ場合、それらは以下のように渡すことができます。 +``` +class Fruit +class Apple extends Fruit +class Banana extends Fruit + +val stack = new Stack[Fruit] +val apple = new Apple +val banana = new Banana + +stack.push(apple) +stack.push(banana) +``` +クラス`Apple`と`Banana`は共に`Fruit`を継承しています。そのため`Fruit`のスタックには`apple`と`banana`のインスタンスを追加できます。 + +_注意: ジェネリック型のサブタイプは*非変(invariant)*です。つまり`Stack[Char]`型の文字スタックがあるとき、それを`Stack[Int]`型の整数スタックとして使うことはできません。文字スタックに整数を入れることはできるので、このことは変に思えるかもしれません。結論としては、`B = A`の場合に限り、`Stack[A]`は`Stack[B]`の唯一のサブタイプとなります。これでは制限が強いので、ジェネリック型のサブタイプの振る舞いをコントロールするために、Scalaは[型引数アノテーションの仕組み](variances.html)を提供します。_ diff --git a/_ja/tour/higher-order-functions.md b/_ja/tour/higher-order-functions.md new file mode 100644 index 0000000000..95c069dc4f --- /dev/null +++ b/_ja/tour/higher-order-functions.md @@ -0,0 +1,115 @@ +--- +layout: tour +title: 高階関数 +language: ja +partof: scala-tour +num: 8 +next-page: nested-functions +previous-page: mixin-class-composition +--- + +高階関数は他の関数をパラメーターとして受け取る、もしくは結果として関数を返します。 +このようなことができるのは、Scalaでは関数が第一級値 (first-class value) だからです。 +用語が少し紛らわしいかもしれませんが、 +ここでは"高階関数"というフレーズを関数をパラメーターとして受け取る、または関数を返すメソッドと関数の両方に対して使います。 + +もっとも一般的な例の1つは、Scalaのコレクションで利用可能な高階関数`map`です。 +```scala mdoc +val salaries = Seq(20000, 70000, 40000) +val doubleSalary = (x: Int) => x * 2 +val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) +``` +`doubleSalary`はInt`x`を1つだけ受け取り、`x * 2`を返す関数です。 +一般的に、アロー`=>`の左側のタプルは引数リストであり、右側の式の値が返されます。 +3行目で、給与のリストのそれぞれの値に`doubleSalary`が適用されます。 + +コードを減らすため、以下のように無名関数を作ることができ、引数として直接mapに渡すことができます +```scala mdoc:nest +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) +``` +上記例では`x`をIntとして宣言していないことに注意してください。 +それはmap関数が期待する型を基にコンパイラーが型を推論できるからです。 +さらに言えば、慣用的には同じコードを以下のように書きます。 + +```scala mdoc:nest +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(_ * 2) +``` +Scalaコンパイラはパラメーターの型を（Intが1つだけと）既に知っているため、関数の右側を提供するだけでよいです。 +唯一の注意点はパラメータ名の代わりに`_`を使う必要があるということです（先の例では`x`でした）。 + +## メソッドを関数に強制変換 +高階関数には引数としてメソッドを渡すことも可能で、それはScalaコンパイラがメソッドを関数に強制変換するからです。 +```scala mdoc +case class WeeklyWeatherForecast(temperatures: Seq[Double]) { + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- convertCtoFメソッドが渡されます +} +``` +ここで、メソッド`convertCtoF`が`forecastInFahrenheit`に渡されています。 +これはコンパイラが`convertCtoF`を関数`x => convertCtoF(x)`(注意点：`x`はスコープ内でユニークであることが保証された名前になります)に変換することで実現します。 + +## 関数を受け取る関数 +高階関数を使う理由の1つは余分なコードを削減することです。 +たとえば、何通りかの係数で人の給料を上げるメソッドが欲しいとしましょう。 +高階関数を作らないなら、こんな感じになるかもしれません。 + +```scala mdoc +object SalaryRaiser { + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +} +``` + +3つのメソッドはそれぞれ掛け算の係数のみ異なることに気をつけてください。 +簡潔にするため、以下のように繰り返されているコードを高階関数に抽出することができます。 + +```scala mdoc:nest +object SalaryRaiser { + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def bigPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +} +``` +新しいメソッド`promotion`はsalariesと`Double => Double`型の関数(すなわち、Doubleを受け取り、Doubleを返す関数)を受け取り、積を返します。 + +## 関数を返す関数 + +関数を生成したい場合がいくつかあります。 +こちらは関数を返すメソッドの例になります。 + +```scala mdoc +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { + val schema = if (ssl) "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" +} + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` + +urlBuilderの戻り値型`(String, String) => String`に注意してください。 +これは返される無名関数はStringを2つ受け取り、Stringを1つ返すことを意味します。 +このケースでは返される無名関数は`(endpoint: String, query: String) => s"https://www.example.com/$endpoint?$query"`です。 diff --git a/_ja/tour/implicit-conversions.md b/_ja/tour/implicit-conversions.md new file mode 100644 index 0000000000..dbf1440872 --- /dev/null +++ b/_ja/tour/implicit-conversions.md @@ -0,0 +1,56 @@ +--- +layout: tour +title: 暗黙の変換 +language: ja +partof: scala-tour +num: 27 +next-page: polymorphic-methods +previous-page: implicit-parameters +--- + +型`S`から型`T`への暗黙の変換は`S => T`という型のimplicit値や、その型に一致するimplicitメソッドで定義されます。 + +暗黙の変換は2つの状況で適用されます。 + +* もし式`e`が型`S`であり、`S`は式の期待する型`T`に適合しない場合 +* 型`S`の`e`を使う表記`e.m`があって、セレクター`m`が`S`のメンバーではない場合 + +最初のケースでは、`e`を渡せて、戻り値の型が`T`に適合するような変換`c`を検索します。 +2つ目のケースでは、`e`を渡せて、戻り値が`m`というメンバーを持つような変換`c`を検索します。 + +implicitなメソッド`List[A] => Ordered[List[A]]`と`Int => Ordered[Int]`がスコープの中にあれば、`List[Int]`型の2つのリストにおける以下の処理は正当なものになります。 + +``` +List(1, 2, 3) <= List(4, 5) +``` +implicitなメソッド`Int => Ordered[Int]`は`scala.Predef.intWrapper`を通じて自動的に提供されます。implicitなメソッドの例`List[A] => Ordered[List[A]]`は以下にあります。 + +```scala mdoc +import scala.language.implicitConversions + +implicit def list2ordered[A](x: List[A]) + (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] = + new Ordered[List[A]] { + //replace with a more useful implementation + def compare(that: List[A]): Int = 1 + } +``` +暗黙にインポートされているオブジェクト`scala.Predef`は、頻繁に使われる型（例えば`scala.collection.immutable.Map`は`Map`と別名づけられます）とメソッド（例えば`assert`）といくつかの暗黙の型変換を宣言しています。 + +例えば、`java.lang.Integer`を受け取るようなJavaのメソッドを呼び出す時、自由に`scala.Int`を代わりに渡すことができます。それはPredefオブジェクトが以下の暗黙の変換を含んでいるからです。 + +```scala mdoc +import scala.language.implicitConversions + +implicit def int2Integer(x: Int): Integer = + Integer.valueOf(x) +``` + +暗黙の変換は見境なく使われると落とし穴になり得るため、暗黙の変換の定義をコンパイルしている時にコンパイラは警告を出します。 + +警告をオフにするには、次のいずれかの措置を講じてください。 + +* 暗黙の変換定義のスコープに`scala.language.implicitConversions`をインポートする。 +* コンパイラを`-language:implicitConversions`をつけて起動する + +コンパイラにより変換が適用された時、警告は出ません。 diff --git a/_ja/tour/implicit-parameters.md b/_ja/tour/implicit-parameters.md new file mode 100644 index 0000000000..4160583a0f --- /dev/null +++ b/_ja/tour/implicit-parameters.md @@ -0,0 +1,69 @@ +--- +layout: tour +title: 暗黙のパラメータ +language: ja +partof: scala-tour +num: 26 +next-page: implicit-conversions +previous-page: self-types +--- + +メソッドは _暗黙の_ パラメータのリストを持つことができ、パラメータリストの先頭には _implicit_ キーワードで印をつけます。 +もしそのパラメータリストの中のパラメータがいつものように渡らなければ、Scalaは正しい型の暗黙値を受け取ることができるかを確認し、可能であればそれを自動的に渡します。 + +Scalaがこれらのパラメータを探す場所は2つのカテゴリに分かれます。 + +* Scalaはまず最初に暗黙のパラメータブロックを持つメソッドが呼び出されている箇所で、直接(プレフィックスなしに)アクセスできる暗黙の定義と暗黙のパラメータを探します。 +* 次に、候補となる型に関連づけられた全てのコンパニオンオブジェクトの中でimplicitと宣言されているメンバーを探します。 + +Scalaがimplicitをどこから見つけるかについてのより詳しいガイドは[FAQ](/tutorials/FAQ/finding-implicits.html)で見ることができます。 + +以下の例では、モノイドの`add`と`unit`の演算を使い、要素のリストの合計を計算するメソッド`sum`を定義しています。 +implicitの値をトップレベルには置けないことに注意してください。 + +```scala mdoc +abstract class Monoid[A] { + def add(x: A, y: A): A + def unit: A +} + +object ImplicitTest { + implicit val stringMonoid: Monoid[String] = new Monoid[String] { + def add(x: String, y: String): String = x concat y + def unit: String = "" + } + + implicit val intMonoid: Monoid[Int] = new Monoid[Int] { + def add(x: Int, y: Int): Int = x + y + def unit: Int = 0 + } + + def sum[A](xs: List[A])(implicit m: Monoid[A]): A = + if (xs.isEmpty) m.unit + else m.add(xs.head, sum(xs.tail)) + + def main(args: Array[String]): Unit = { + println(sum(List(1, 2, 3))) // intMonoidを暗に使用 + println(sum(List("a", "b", "c"))) // stringMonoidを暗に使用 + } +} +``` +`Monoid`はここでは`add`と呼ばれる処理を定義します。この処理は`A`のペアを結合して、別の`A`を返します。また、(特定の)`A`を作ることができる`unit`と呼ばれる処理も定義します。 + +暗黙のパラメータがどのように働くかを見るため、まずは文字列と整数のためにそれぞれモノイド`stringMonoid`と`intMonoid`を定義します。`implicit`キーワードは対応するオブジェクトが暗黙に使われうることを指し示します。 + +メソッド`sum`は`List[A]`を受け取り、`A`を返します。このメソッドは初期値`A`を`unit`から受け取り、リスト中の`A`を順番に`add`メソッドで結合します。ここでパラメータ`m`をimplicitにしているのは、そのメソッドを呼び出すとき、Scalaが暗黙のパラメータ`m`として暗黙の`Monoid[A]`を見つけることができるなら、私達は`xs`パラメータを提供するだけで良いということです。 + +`main`メソッドでは`sum`を2回呼んでいて、`xs`パラメータだけを渡しています。するとScalaは先に言及したスコープの中でimplicitを探します。最初の`sum`の呼び出しは`xs`として`List[Int]`を渡します。それは `A`が`Int`であることを意味します。暗黙のパラメータリスト`m`が省略されているので、Scalaは暗黙の`Monoid[Int]`を探します。最初の探索ルールはこうでした。 + +> Scalaはまず最初に暗黙のパラメータブロックを持つメソッドが呼び出されている箇所で、直接(プレフィックスなしに)アクセスできる暗黙の定義と暗黙のパラメータを探します。 + +`intMonoid`は`main`の中で直接アクセスできる暗黙の定義です。型も一致しているので、`sum`メソッドに自動的に渡されます。 + +`sum`の2回目の呼び出しは`List[String]`を渡します。それは`A`は`String`であることを意味します。暗黙の値の探索は`Int`の時と同様に動きますが、今回は `stringMonoid`を見つけ、`m`として自動的に渡します。 + +そのプログラムは以下を出力します。 +``` +6 +abc +``` diff --git a/_ja/tour/inner-classes.md b/_ja/tour/inner-classes.md new file mode 100644 index 0000000000..60916409b4 --- /dev/null +++ b/_ja/tour/inner-classes.md @@ -0,0 +1,85 @@ +--- +layout: tour +title: 内部クラス +language: ja +partof: scala-tour +num: 22 +next-page: abstract-type-members +previous-page: lower-type-bounds +--- + +Scalaではクラスが他のクラスをメンバーとして保持することが可能です。 +Javaのような、内部クラスが外側のクラスのメンバーとなる言語とは対照的に、Scalaでは、内部クラスは外側のオブジェクトに束縛されます。 +どのノードがどのグラフに属しているのかを私達が混同しないように、コンパイラがコンパイル時に防いでほしいのです。 +パス依存型はその解決策の1つです。 + +その違いを示すために、グラフデータ型の実装をさっと書きます。 + +```scala mdoc +class Graph { + class Node { + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes + } + } + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` +このプログラムはグラフをノードのリスト(`List[Node]`)で表現しています。いずれのノードも接続している他のノードへのリスト(`connectedNodes`)を保持します。`class Node`は `class Graph`の中にネストしているので、 _パス依存型_ です。 +そのため`connectedNodes`の中にある全てのノードは同じ`Graph`インスタンスから`newNode`を使用して作る必要があります。 + +```scala mdoc +val graph1: Graph = new Graph +val node1: graph1.Node = graph1.newNode +val node2: graph1.Node = graph1.newNode +val node3: graph1.Node = graph1.newNode +node1.connectTo(node2) +node3.connectTo(node1) +``` +わかりやすくするため`node1`、`node2`、`node3`の型を`graph1.Node`と明示的に宣言しましたが、なくてもコンパイラは推論できます。 +これは`new Node`を呼んでいる`graph1.newNode`を呼び出す時、メソッドが`Node`のインスタンス`graph1`を使用しているからです。 + +2つのグラフがあるとき、Scalaの型システムは1つのグラフの中で定義されたノードと別のグラフで定義されたノードを混ぜることを許しません。 +それは別のグラフのノードは別の型を持つからです。 +こちらは不正なプログラムです。 + +```scala mdoc:fail +val graph1: Graph = new Graph +val node1: graph1.Node = graph1.newNode +val node2: graph1.Node = graph1.newNode +node1.connectTo(node2) // legal +val graph2: Graph = new Graph +val node3: graph2.Node = graph2.newNode +node1.connectTo(node3) // illegal! +``` +型`graph1.Node`は`graph2.Node`とは異なります。Javaであれば先のプログラム例の最後の行は正しいでしょう。 +2つのグラフのノードに対して、Javaは同じ型`Graph.Node`を指定します。つまりクラス`Graph`は`Node`の接頭辞です。 +Scalaではそのような型も同様に表現することができ、`Graph#Node`と書きます。 +もし他のグラフのノードに接続できるようにしたければ、以下の方法で最初のグラフ実装の定義を変える必要があります。 + +```scala mdoc:nest +class Graph { + class Node { + var connectedNodes: List[Graph#Node] = Nil + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes + } + } + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` diff --git a/_ja/tour/lower-type-bounds.md b/_ja/tour/lower-type-bounds.md new file mode 100644 index 0000000000..e72a3773f8 --- /dev/null +++ b/_ja/tour/lower-type-bounds.md @@ -0,0 +1,70 @@ +--- +layout: tour +title: 下限型境界 +language: ja +partof: scala-tour +num: 21 +next-page: inner-classes +previous-page: upper-type-bounds +prerequisite-knowledge: upper-type-bounds, generics, variance +--- + + [上限型境界](upper-type-bounds.html) は型を別の型のサブタイプに制限しますが、*下限型境界*は型が別の型のスーパータイプであることを宣言します。表現`B >: A`はパラメータ`B`または抽象型`B`が型`A`のスーパータイプであることを表します。ほとんどのケースで`A`はそのクラスの型パラメータであり、`B`はメソッドの型パラメータになります。 + +以下はこれが役立つ場合の例です。 + +```scala mdoc:fail +trait Node[+B] { + def prepend(elem: B): Node[B] +} + +case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { + def prepend(elem: B): ListNode[B] = ListNode(elem, this) + def head: B = h + def tail: Node[B] = t +} + +case class Nil[+B]() extends Node[B] { + def prepend(elem: B): ListNode[B] = ListNode(elem, this) +} +``` + +このプログラムは片方向リストを実装します。`Nil`は空の要素（すなわち空のリスト）を意味します。 +`class ListNode`は型`B` (`head`)の要素と、リストの残りの部分(`tail`)への参照を持つノードです。 +`class Node`とそのサブタイプは、`+B`とあるので、共変です。 + +しかしながら、このプログラムはコンパイル _されません_。`prepend`のパラメータ`elem`が、宣言時に*共* 変と宣言した型`B`になっているからです。 +なぜ通らないかというと、関数はそれらの型パラメータに対して*反*変であり、それらの結果型に対して*共*変だからです。 + +これを解決するためには、`prepend`のパラメータ`elem`の型の変位指定を逆転させる必要があります。 +これを実現するには、下限型境界として`B`を持つ新しい型パラメータ`U`を導入します。 + +```scala mdoc +trait Node[+B] { + def prepend[U >: B](elem: U): Node[U] +} + +case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { + def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) + def head: B = h + def tail: Node[B] = t +} + +case class Nil[+B]() extends Node[B] { + def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) +} +``` + +すると、以下のようなことができます。 +```scala mdoc +trait Bird +case class AfricanSwallow() extends Bird +case class EuropeanSwallow() extends Bird + + +val africanSwallowList= ListNode[AfricanSwallow](AfricanSwallow(), Nil()) +val birdList: Node[Bird] = africanSwallowList +birdList.prepend(EuropeanSwallow()) +``` +`Node[Bird]`は`africanSwallowList`をアサインできますが、その後`EuropeanSwallow`を受け入れられます。 + diff --git a/_ja/tour/mixin-class-composition.md b/_ja/tour/mixin-class-composition.md new file mode 100644 index 0000000000..f95ab54cb9 --- /dev/null +++ b/_ja/tour/mixin-class-composition.md @@ -0,0 +1,78 @@ +--- +layout: tour +title: ミックスインを用いたクラス合成 +language: ja +partof: scala-tour +num: 7 +next-page: higher-order-functions +previous-page: tuples +prerequisite-knowledge: inheritance, traits, abstract-classes, unified-types +--- +ミックスインはクラスを構成するのに使われるトレイトです。 + +```scala mdoc +abstract class A { + val message: String +} +class B extends A { + val message = "I'm an instance of class B" +} +trait C extends A { + def loudMessage = message.toUpperCase() +} +class D extends B with C + +val d = new D +println(d.message) // I'm an instance of class B +println(d.loudMessage) // I'M AN INSTANCE OF CLASS B +``` +クラス`D`は スーパークラスを`B` とし、 ミックスイン`C`を持ちます。 +クラスは1つだけしかスーパークラスを持つことができませんが、ミックスインは複数持つことができます(キーワードはそれぞれ`extends`と`with`を使います)。 +ミックスインとスーパークラスは同じスーパータイプを持つことができます。 + +それでは抽象クラスから始まる興味深い例を見てみましょう。 + +```scala mdoc +abstract class AbsIterator { + type T + def hasNext: Boolean + def next(): T +} +``` +クラスは抽象型`T`と標準的なイテレーターのメソッドを持ちます。 +次に、（全ての抽象メンバー`T`, `hasNext`, `next`が実装を持つ）具象クラスを実装します。 + +```scala mdoc +class StringIterator(s: String) extends AbsIterator { + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = { + val ch = s charAt i + i += 1 + ch + } +} +``` +`StringIterator`は`String`を受け取り、そのStringを反復処理するために使われます。 +（例：Stringに特定の文字が含まれているかを確認するために） + +それでは`AbsIterator`を継承したトレイトも作ってみましょう。 + +```scala mdoc +trait RichIterator extends AbsIterator { + def foreach(f: T => Unit): Unit = while (hasNext) f(next()) +} +``` +このトレイトは(`while (hasNext)`で)要素がある限り、与えられた関数 `f: T => Unit`を次の要素(`next()`)に対し連続して呼び出す`foreach`メソッドを実装しています。 +`RichIterator`はトレイトなので、`RichIterator`はAbsIteratorの抽象メンバーを実装する必要がありません。 + +`StringIterator`と`RichIterator`の機能を1つのクラスに組み合わせてみましょう。 +```scala mdoc +class RichStringIter extends StringIterator("Scala") with RichIterator +val richStringIter = new RichStringIter +richStringIter foreach println +``` +新しいクラス`RichStringIter`は`StringIterator`をスーパークラスとし、`RichIterator`をミックスインとしています。 + +単一継承ではこのレベルの柔軟性を達成することはできないでしょう。 diff --git a/_ja/tour/multiple-parameter-lists.md b/_ja/tour/multiple-parameter-lists.md new file mode 100644 index 0000000000..eb8fffd6cb --- /dev/null +++ b/_ja/tour/multiple-parameter-lists.md @@ -0,0 +1,71 @@ +--- +layout: tour +title: 複数パラメータリスト(カリー化) +language: ja +partof: scala-tour +num: 10 +next-page: case-classes +previous-page: nested-functions +--- + +メソッドは複数のパラメータリストを持てます。 + +# 例 + +こちらはScalaのコレクションAPIの `TraversableOnce`トレイトで定義されている実例です。 + +```scala mdoc:fail +def foldLeft[B](z: B)(op: (B, A) => B): B +``` +`foldLeft`は、2つのパラメータを取る関数`op`を、初期値`z`とこのコレクションの全要素に対して左から右に適用していきます。 +以下はその使い方の例です。 + +初期値0から始まり、`foldLeft`はここではリスト内の各要素とその一つ前の累積値に関数`(m, n) => m + n`を適用します。 + +```scala mdoc +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val res = numbers.foldLeft(0)((m, n) => m + n) +println(res) // 55 +``` + +### ユースケース +推奨される複数パラメータリストのユースケースは次の通りです。 + +#### パラメータに関数を一つ渡す場合 +パラメータに関数を一つだけ渡すのであれば、上記の`foldLeft`のケースでの`op`のように、複数パラメータリストを利用して簡潔な構文でメソッドに無名関数を渡すことができます。 +複数パラメータリストがない場合、このコードは以下のようになります。 + + +```scala mdoc:fail +numbers.foldLeft(0, (m: Int, n: Int) => m + n) +``` + +複数パラメータリストを使うことで、Scalaの型インターフェースの利点を享受でき、以下のようにコードをより簡潔にすることができるのです。 + +```scala mdoc +numbers.foldLeft(0)(_ + _) +``` +単一のパラメータリストではScalaコンパイラが関数のパラメータを型推論できないので、このようなことはできません。 + +#### 暗黙のパラメータ +特定のパラメータだけを`implicit`として指定するには、`implicit`のパラメーターリストに入れなければなりません。 +こちらが例です。 + +```scala mdoc +def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ??? +``` + +#### 部分適用 + +メソッドが少ない数のパラメータリストで呼び出された時、不足しているパラメータリストを引数として受け取る関数が生成されます。 +これは一般的に[部分適用](https://en.wikipedia.org/wiki/Partial_application)として知られています。 + +例えば +```scala mdoc:nest +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]()) _ +val squares = numberFunc((xs, x) => xs :+ x*x) +print(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) +val cubes = numberFunc((xs, x) => xs :+ x*x*x) +print(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` diff --git a/_ja/tour/named-arguments.md b/_ja/tour/named-arguments.md new file mode 100644 index 0000000000..88bc231fda --- /dev/null +++ b/_ja/tour/named-arguments.md @@ -0,0 +1,30 @@ +--- +layout: tour +title: 名前付き引数 +language: ja +partof: scala-tour +num: 34 +next-page: packages-and-imports +previous-page: default-parameter-values +prerequisite-knowledge: function-syntax +--- + +メソッドを呼ぶ時、以下のように引数にパラメータ名でラベル付が可能です。 + +```scala mdoc +def printName(first: String, last: String): Unit = { + println(first + " " + last) +} + +printName("John", "Smith") // Prints "John Smith" +printName(first = "John", last = "Smith") // Prints "John Smith" +printName(last = "Smith", first = "John") // Prints "John Smith" +``` + +名前付き引数の順序はどのように並び替えられるかに気をつけましょう。ただし、名前つき引数と名前つきでない引数がある場合は、名前つきでない引数は引数リストの最初に置かれ、かつメソッドシグネチャのパラメーター順でなければなりません。 + +```scala mdoc:fail +printName(last = "Smith", "john") // error: positional after named argument +``` + +名前付き引数はJavaメソッドを呼び出す時には使えません。 diff --git a/_ja/tour/nested-functions.md b/_ja/tour/nested-functions.md new file mode 100644 index 0000000000..0e6980451f --- /dev/null +++ b/_ja/tour/nested-functions.md @@ -0,0 +1,32 @@ +--- +layout: tour +title: ネストしたメソッド +language: ja +partof: scala-tour +num: 9 +next-page: multiple-parameter-lists +previous-page: higher-order-functions +--- + +Scalaではメソッドの定義をネストする（_訳注：入れ子にする_）ことができます。 +以下のコードは与えられた数値の階乗を計算するための`factorial`メソッドを提供します。 + +```scala mdoc + def factorial(x: Int): Int = { + def fact(x: Int, accumulator: Int): Int = { + if (x <= 1) accumulator + else fact(x - 1, x * accumulator) + } + fact(x, 1) + } + + println("Factorial of 2: " + factorial(2)) + println("Factorial of 3: " + factorial(3)) +``` + +このプログラムの出力は以下の通りです。 + +``` +Factorial of 2: 2 +Factorial of 3: 6 +``` diff --git a/_ja/tour/operators.md b/_ja/tour/operators.md new file mode 100644 index 0000000000..398790b4e0 --- /dev/null +++ b/_ja/tour/operators.md @@ -0,0 +1,82 @@ +--- +layout: tour +title: 演算子 +language: ja +partof: scala-tour +num: 30 +next-page: by-name-parameters +previous-page: type-inference +prerequisite-knowledge: case-classes +--- +Scalaでは演算子はメソッドです。パラメータを1つだけ持つメソッドであれば*中置演算子*として使えます。例えば、`+`はドット記法で呼び出せます。 + +``` +10.+(1) +``` + +しかしながら、中置演算子の方が読みやすいです。 + +``` +10 + 1 +``` + +## 演算子の定義方法と使い方 + +有効な識別子であれば演算子として使用できます。これは `add`のような名前も`+`のような記号も含みます。 +```scala mdoc +case class Vec(x: Double, y: Double) { + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) +} + +val vector1 = Vec(1.0, 1.0) +val vector2 = Vec(2.0, 2.0) + +val vector3 = vector1 + vector2 +vector3.x // 3.0 +vector3.y // 3.0 +``` +クラスVecはメソッド`+`を持ち、 `vector1`と`vector2`を足しわせるのに使います。丸括弧を用いて、複雑な式を読みやすい構文で作ることができます。 +こちらはクラス`MyBool`の定義です。クラス`MyBool`はメソッド`and`と`or`を含みます。 + +```scala mdoc +case class MyBool(x: Boolean) { + def and(that: MyBool): MyBool = if (x) that else this + def or(that: MyBool): MyBool = if (x) this else that + def negate: MyBool = MyBool(!x) +} +``` + +この時、`and`と`or`を中置演算子として使えます。 + +```scala mdoc +def not(x: MyBool) = x.negate +def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) +``` + +これにより`xor`の定義がより読みやすくなります。 + +## 優先順位 + +式が複数の演算子を使う時、それらの演算子は最初の文字の（以下に挙げる）優先度に基づき評価されます。 +``` +(以下に表示されていない記号) +* / % ++ - +: += ! +< > +& +^ +| +(全ての文字, $, _) +``` +これはあなたが定義した関数にも適用できます。 +たとえば、以下の式 +``` +a + b ^? c ?^ d less a ==> b | c +``` +は以下と同じ意味です。 +``` +((a + b) ^? (c ?^ d)) less ((a ==> b) | c) +``` +`?^`は最も高い優先順位を持ちます。`?^`は`?`から始まるからです。`+`は二番目に高い優先順位を持ち、その後に`==>`、 `^?`、 `|`、 そして`less`が続きます。 diff --git a/_ja/tour/package-objects.md b/_ja/tour/package-objects.md new file mode 100644 index 0000000000..f2ed9b1d89 --- /dev/null +++ b/_ja/tour/package-objects.md @@ -0,0 +1,68 @@ +--- +layout: tour +title: パッケージオブジェクト +language: ja +partof: scala-tour +num: 36 +previous-page: packages-and-imports +--- + +# パッケージオブジェクト + +Scalaはパッケージ全体を通して共有される便利なコンテナとしてパッケージオブジェクトを提供します。 + +パッケージオブジェクトは、変数やメソッド定義だけでなく、任意の定義を含むことができます。 +例えば、それらはパッケージ全体で使われる型エイリアスと暗黙の変換を保有するためによく使われます。 +パッケージオブジェクトはScalaクラスやトレイトを継承することもできます。 + +慣習として、パッケージオブジェクトのソースコードは通常`package.scala`という名のソースファイルに設置されます。 + +1つのパッケージはパッケージオブジェクトを1つ持てます。パッケージオブジェクト内の全ての定義はパッケージ自体のメンバーと見なされます。 + +以下の例を見てみましょう。まず1つのクラス`Fruit`と3つの`Fruit`オブジェクトがパッケージ`gardening.fruits`にあるとします。 + +``` +// ファイル gardening/fruits/Fruit.scala の中 +package gardening.fruits + +case class Fruit(name: String, color: String) +object Apple extends Fruit("Apple", "green") +object Plum extends Fruit("Plum", "blue") +object Banana extends Fruit("Banana", "yellow") +``` + +ここで、変数`planted`とメソッド`showFruit`を直接パッケージ`gardening.fruits`内に置きたいとします。 +こちらがその方法になります。 + +``` +// ファイル gardening/fruits/package.scala の中 +package gardening +package object fruits { + val planted = List(Apple, Plum, Banana) + def showFruit(fruit: Fruit): Unit = { + println(s"${fruit.name}s are ${fruit.color}") + } +} +``` + +利用側がどのようになるかの例としては、以下のオブジェクト`PrintPlanted`は、ワイルドカードインポートでクラス`Fruit`と全く同様に`planted`と`showFruit`をインポートしています。 + +``` +// ファイル PrintPlanted.scala の中 +import gardening.fruits._ +object PrintPlanted { + def main(args: Array[String]): Unit = { + for (fruit <- planted) { + showFruit(fruit) + } + } +} +``` + +パッケージオブジェクトは他のオブジェクトのように、継承を利用して構成できます。例えば、一つのパッケージオブジェクトが２つのトレイトをミックスインしている例を示します。 + +``` +package object fruits extends FruitAliases with FruitHelpers { + // ヘルパーと変数がここに続きます。 +} +``` diff --git a/_ja/tour/packages-and-imports.md b/_ja/tour/packages-and-imports.md new file mode 100644 index 0000000000..4e94731644 --- /dev/null +++ b/_ja/tour/packages-and-imports.md @@ -0,0 +1,83 @@ +--- +layout: tour +title: パッケージとインポート +language: ja +partof: scala-tour +num: 35 +previous-page: named-arguments +next-page: package-objects +--- + +# パッケージとインポート +Scalaは名前空間を作るためにパッケージを使います。名前空間によりプログラムをモジュール化できます。 + +## パッケージの作成 +Scalaファイルの先頭で1つ以上のパッケージ名を宣言することでパッケージは作られます。 + +``` +package users + +class User +``` +パッケージとScalaファイルが含まれるディレクトリは同じ名前をつける習慣があります。しかし、Scalaはファイルのレイアウトには関知しません。`package users`を含むsbtプロジェクトのディレクトリ構成はこのようになるかもしれません。 + +``` +- ExampleProject + - build.sbt + - project + - src + - main + - scala + - users + User.scala + UserProfile.scala + UserPreferences.scala + - test +``` +`users`ディレクトリがどのように`scala`ディレクトリの中にあり、複数のScalaファイルがどのようにパッケージ内にあるのかに注意してください。パッケージ内のScalaファイルは同じパッケージ宣言を持ちます。パッケージ宣言の他の方法は波括弧を使い以下のようにします。 + +``` +package users { + package administrators { + class NormalUser + } + package normalusers { + class NormalUser + } +} +``` +見ての通り、この方法はパッケージのネストができ、スコープとカプセル化をより強くコントロールできます。 + +パッケージ名は全て小文字で書き、もしコードがwebサイトを持つ組織によって開発される場合、慣習として次のフォーマットであるべきです。`<トップレベルドメイン>.<ドメイン名>.<プロジェクト名>`。例えば、Googleが`SelfDrivingCar`と呼ばれるプロジェクトを持っている場合、パッケージ名はこんな風になるでしょう。 +``` +package com.google.selfdrivingcar.camera + +class Lens +``` +これは次のディレクトリ構成に対応します。`SelfDrivingCar/src/main/scala/com/google/selfdrivingcar/camera/Lens.scala` + +## インポート +`import`句は他パッケージのメンバー（クラス、トレイト、関数など）にアクセスするためのものです。同じパッケージのメンバーにアクセスするには`import`句は必要ありません。import句は以下のどれでも使えます。 +``` +import users._ // usersパッケージから全てをインポートする +import users.User // クラスUserをインポートする +import users.{User, UserPreferences} // 選択されたメンバーのみインポートする +import users.{UserPreferences => UPrefs} // インポートし利便性のために名前を変更する +``` +ScalaのJavaと異なる点の1つはインポートがどこでも使える点です。 + +```scala mdoc +def sqrtplus1(x: Int) = { + import scala.math.sqrt + sqrt(x) + 1.0 +} +``` +名前競合があり、プロジェクトのルートから何かをインポートする必要がある時、パッケージ名の前に`_root_`をつけます。 +``` +package accounts + +import _root_.users._ +``` + + +注：`scala`と`java.lang` パッケージは`object Predef`と同じように標準でインポートされています。 diff --git a/_ja/tour/pattern-matching.md b/_ja/tour/pattern-matching.md new file mode 100644 index 0000000000..23c997ca91 --- /dev/null +++ b/_ja/tour/pattern-matching.md @@ -0,0 +1,159 @@ +--- +layout: tour +title: パターンマッチング +language: ja +partof: scala-tour +num: 12 +next-page: singleton-objects +previous-page: case-classes +prerequisite-knowledge: case-classes, string-interpolation, subtyping +--- + +パターンマッチングは値をパターンに照合するための仕組みです。 +マッチに成功すれば、一つの値をその構成要素のパーツに分解することもできます。 +Javaの`switch`文の強化バージョンで、if/else文の連続の代わりとして同様に使うことができます。 + +## 構文 + +マッチ式は値、キーワード`match`と少なくとも1つの`case`句を持ちます。 +```scala mdoc +import scala.util.Random + +val x: Int = Random.nextInt(10) + +x match { + case 0 => "zero" + case 1 => "one" + case 2 => "two" + case _ => "other" +} +``` +上記の`val x`は0から10の間のランダムな整数です。`x`は`match`演算子の左オペランドで、右側は4つのケースを持つ式です。 +最後のケース`_`は その他の取りうる整数値のための"全てを捕捉する"ケースです。 +ケースは*オルタナティブ*とも呼ばれます。 + +マッチ式は値を持ちます。 +```scala mdoc +def matchTest(x: Int): String = x match { + case 1 => "one" + case 2 => "two" + case _ => "other" +} +matchTest(3) // other +matchTest(1) // one +``` +全てのケースでStringを返しているので、このマッチ式はString型を持ちます。 +そのため関数`matchTest`はStringを返します。 + +## ケースクラスでのマッチング + +ケースクラスはパターンマッチングで特に役立ちます。 + +```scala mdoc +abstract class Notification + +case class Email(sender: String, title: String, body: String) extends Notification + +case class SMS(caller: String, message: String) extends Notification + +case class VoiceRecording(contactName: String, link: String) extends Notification + +``` +`Notification`は抽象スーパークラスで、ケースクラスの実装`Email`、 `SMS`、 `VoiceRecording`3つの具象クラスがあります。 +今、これらのケースクラスでパターンマッチングをすることができます。 + +``` +def showNotification(notification: Notification): String = { + notification match { + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" + case VoiceRecording(name, link) => + s"you received a Voice Recording from $name! Click the link to hear it: $link" + } +} +val someSms = SMS("12345", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") + +println(showNotification(someSms)) // You got an SMS from 12345! Message: Are you there? が出力されます。 + +println(showNotification(someVoiceRecording)) // you received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123 が出力されます。 +``` +関数`showNotification`は抽象型`Notification`をパラメータとして受け取り、`Notification`の型でマッチします（すなわち`Email`、`SMS`、または `VoiceRecording`のいずれであるかを解決します）。 +`case Email(sender, title, _)` ではフィールド`sender`と`title`が戻り値として使われますが、`_`を使うことでフィールド`body`は無視されます。 + +## パターンガード +パターンガードはケースをより具体的にするために使われる簡単な真偽表現です。 +`if `をパターンの後ろに追加するだけです。 + +``` + +def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String = { + notification match { + case Email(sender, _, _) if importantPeopleInfo.contains(sender) => + "You got an email from special someone!" + case SMS(number, _) if importantPeopleInfo.contains(number) => + "You got an SMS from special someone!" + case other => + showNotification(other) // 特別なものではなく、オリジナルのshowNotification関数に委譲します。 + } +} + +val importantPeopleInfo = Seq("867-5309", "jenny@gmail.com") + +val someSms = SMS("867-5309", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") +val importantEmail = Email("jenny@gmail.com", "Drinks tonight?", "I'm free after 5!") +val importantSms = SMS("867-5309", "I'm here! Where are you?") + +println(showImportantNotification(someSms, importantPeopleInfo)) +println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) +println(showImportantNotification(importantEmail, importantPeopleInfo)) +println(showImportantNotification(importantSms, importantPeopleInfo)) +``` + +`case Email(sender, _, _) if importantPeopleInfo.contains(sender)`では、パターンは`sender`が重要な人のリストに存在して初めてマッチします。 + +## 型のみでのマッチング + +以下のように型のみでマッチすることができます。 +```scala mdoc +abstract class Device +case class Phone(model: String) extends Device { + def screenOff = "Turning screen off" +} +case class Computer(model: String) extends Device { + def screenSaverOn = "Turning screen saver on..." +} + +def goIdle(device: Device) = device match { + case p: Phone => p.screenOff + case c: Computer => c.screenSaverOn +} +``` +`def goIdle`は`Device`の型によって異なる振る舞いをします。 +これはケースがそのパターンのメソッドを呼び出す必要がある時に役立ちます。 +ケースの識別子には型の最初の一文字（この場合に`p`と`c`）を利用する慣習があります。 + +## シールドクラス +トレイトとクラスに`sealed`をつけると、全てのサブタイプは同一ファイル内で宣言されなければならないという意味になります。 +これは全てのサブタイプが既知であることを保証します。 + +```scala mdoc +sealed abstract class Furniture +case class Couch() extends Furniture +case class Chair() extends Furniture + +def findPlaceToSit(piece: Furniture): String = piece match { + case a: Couch => "Lie on the couch" + case b: Chair => "Sit on the chair" +} +``` +これは"全てに対応する"ケースを必要としなくて済むので、パターンマッチングで役立ちます。 + +## 注意 +Scalaのパターンマッチング文は[ケースクラス](case-classes.html)で表現される代数型のマッチングに最も役立ちます。 + + +Scalaでは[抽出子オブジェクト](extractor-objects.html)の`unapply`メソッドを使うと、ケースクラスのパターンを独自に定義することもできます。 diff --git a/_ja/tour/polymorphic-methods.md b/_ja/tour/polymorphic-methods.md new file mode 100644 index 0000000000..4bab5f63bd --- /dev/null +++ b/_ja/tour/polymorphic-methods.md @@ -0,0 +1,32 @@ +--- +layout: tour +title: ポリモーフィックメソッド +language: ja +partof: scala-tour +num: 28 +next-page: type-inference +previous-page: implicit-conversions +prerequisite-knowledge: unified-types +--- + +Scalaのメソッドは値と同様に型によってパラメータ化することができます。構文はジェネリッククラスの構文と似ています。 +値パラメータは丸括弧で囲まれるのに対して、型パラメータは角カッコで囲まれます。 + +こちらが例です。 + +```scala mdoc +def listOfDuplicates[A](x: A, length: Int): List[A] = { + if (length < 1) + Nil + else + x :: listOfDuplicates(x, length - 1) +} +println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3) +println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La) +``` + +メソッド`listOfDuplicates`は型パラメータ`A`と値パラメータ`x`と`length`を受け取ります。値`x`の型は`A`です。もし`length < 1`なら空のリストを返します。それ以外の場合は`x`を再帰呼び出しで返された複写リストの先頭に追加します。(`::`の意味は、左辺の要素を右辺のリストの先頭に追加することです。) + +最初の呼び出し例では、`[Int]`と書いて明示的に型引数を渡しています。そのため最初の引数は`Int`でなければならず、戻される型は`List[Int]`となります。 + +2つ目の呼び出し例では必ずしも明示的に型パラメータを渡す必要がないことを示しています。コンパイラは文脈または値引数の型に基づき、型パラメータを推論できることが多いです。この例では`"La"`が`String`なので、コンパイラは`A`が`String`に違いないことが分かります。 diff --git a/_ja/tour/regular-expression-patterns.md b/_ja/tour/regular-expression-patterns.md new file mode 100644 index 0000000000..79cf565c9f --- /dev/null +++ b/_ja/tour/regular-expression-patterns.md @@ -0,0 +1,56 @@ +--- +layout: tour +title: 正規表現パターン +language: ja +partof: scala-tour +num: 15 +next-page: extractor-objects +previous-page: singleton-objects +--- +正規表現はデータの中からパターン（またはその欠如）を探すために使うことができる文字列です。 +どんな文字列も`.r`メソッドを使うことで、正規表現に変換できます。 + +```scala mdoc +import scala.util.matching.Regex + +val numberPattern: Regex = "[0-9]".r + +numberPattern.findFirstMatchIn("awesomepassword") match { + case Some(_) => println("Password OK") + case None => println("Password must contain a number") +} +``` +上記の例では、`numberPattern`は`Regex`(正規表現)型で、パスワードに数字が含まれていることを確認するのに使います。 + +括弧を使うことで、正規表現のグループを探すこともできます。 + +```scala mdoc +import scala.util.matching.Regex + +val keyValPattern: Regex = "([0-9a-zA-Z-#() ]+): ([0-9a-zA-Z-#() ]+)".r + +val input: String = + """background-color: #A03300; + |background-image: url(img/header100.png); + |background-position: top center; + |background-repeat: repeat-x; + |background-size: 2160px 108px; + |margin: 0; + |height: 108px; + |width: 100%;""".stripMargin + +for (patternMatch <- keyValPattern.findAllMatchIn(input)) + println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}") +``` +ここでは、文字列のキーと値を解析しています。 +それぞれのマッチはサブマッチのグループを持ちます。こちらが出力結果です。 +``` +key: background-color value: #A03300 +key: background-image value: url(img/header100.png) +key: background-position value: top center +key: background-repeat value: repeat-x +key: background-size value: 2160px 108px +key: margin value: 0 +key: height value: 108px +key: width value: 100 +``` diff --git a/_ja/tour/self-types.md b/_ja/tour/self-types.md new file mode 100644 index 0000000000..7ffa6745ec --- /dev/null +++ b/_ja/tour/self-types.md @@ -0,0 +1,36 @@ +--- +layout: tour +title: 自分型 +language: ja +partof: scala-tour +num: 25 +next-page: implicit-parameters +previous-page: compound-types +topics: self-types +prerequisite-knowledge: nested-classes, mixin-class-composition +--- +自分型は、直接継承していなくてもトレイトが他のトレイトにミックスインされていることを宣言する方法です。 +これにより依存先のメンバーをimportなしで利用できます。 + +自分型は`this`、または`this`の別名となる他の識別子の型を絞り込む方法です。 +その構文は普通の関数構文のように見えますが、全く異なる意味があります。 + +トレイトで自分型を使うには、識別子、ミックスインする他のトレイトの型、`=>`を書きます(例えば `someIdentifier: SomeOtherTrait =>`)。 +```scala mdoc +trait User { + def username: String +} + +trait Tweeter { + this: User => // thisが再割り当てされます + def tweet(tweetText: String) = println(s"$username: $tweetText") +} + +class VerifiedTweeter(val username_ : String) extends Tweeter with User { // TweeterがUserを必要とするためミックスインします。 + def username = s"real $username_" +} + +val realBeyoncé = new VerifiedTweeter("Beyoncé") +realBeyoncé.tweet("Just spilled my glass of lemonade") // "real Beyoncé: Just spilled my glass of lemonade"と出力します。 +``` +`trait Tweeter`の中で`this: User =>`と記述したので、今は変数`username`は`tweet`メソッドのスコープ内にあります。これはさらに、`VerifiedTweeter`が`Tweeter`を継承する際、(`with User`を使って)`User`もミックスインしなければならないことを意味します。 diff --git a/_ja/tour/singleton-objects.md b/_ja/tour/singleton-objects.md new file mode 100644 index 0000000000..0414291909 --- /dev/null +++ b/_ja/tour/singleton-objects.md @@ -0,0 +1,116 @@ +--- +layout: tour +title: シングルトンオブジェクト +language: ja +partof: scala-tour +num: 13 +next-page: regular-expression-patterns +previous-page: pattern-matching +prerequisite-knowledge: classes, methods, private-methods, packages, option +--- +オブジェクトは丁度1つのインスタンスを持つクラスです。 +それはlazy valのように参照された際に遅れて作られます。 + +トップレベルにあるオブジェクトは、シングルトンです。 +クラスのメンバーやローカル変数としてのオブジェクトは、lazy valと全く同じように振る舞います。 + +# シングルトンオブジェクトの定義 +オブジェクトは値です。オブジェクトの定義はクラスのように見えますが、キーワード`object`を使います。 +```scala mdoc +object Box +``` +これはメソッドを持つオブジェクトの例です。 +``` +package logging + +object Logger { + def info(message: String): Unit = println(s"INFO: $message") +} +``` +`info`メソッドはプログラム上のどこからでもimportすることができます。 +このように便利なメソッドを作ることはシングルトンオブジェクトのユースケースと同じです。 + +他のパッケージで`info`がどのように使われるか見てみましょう。 + +``` +import logging.Logger.info + +class Project(name: String, daysToComplete: Int) + +class Test { + val project1 = new Project("TPS Reports", 1) + val project2 = new Project("Website redesign", 5) + info("Created projects") // Prints "INFO: Created projects" +} +``` + +import文`import logging.Logger.info`により、`info`メソッドが見えるようになります。 + +import文には取り込むシンボルへの"変動しないパス"が必要であり、オブジェクトは変動しないパスとなります。 + +注意：`object`がトップレベルではなく他のクラスやオブジェクトにネストされている時、そのオブジェクトは他のメンバーのように"経路依存性"があります。 +これは2種類の飲み物`class 牛乳`と`class オレンジジュース`が与えられた場合、クラスメンバーの`object 栄養素`はそれが属するインスタンス、すなわち牛乳またはオレンジジュースのいずれかに依存することを意味します。 +`milk.NutritionInfo`は`oj.NutritionInfo`とは全く異なります。 + +## コンパニオンオブジェクト + +クラスと同じ名前のオブジェクトは*コンパニオンオブジェクト*と呼ばれます。 +逆にそのクラスはオブジェクトのコンパニオンクラスと呼ばれます。 +コンパニオンクラスやコンパニオンオブジェクトは自身のコンパニオンのプライベートメンバーにアクセスできます。 +コンパニオンクラスのインスタンスに特定されないメソッドや値にはコンパニオンオブジェクトを使います。 + +``` +import scala.math._ + +case class Circle(radius: Double) { + import Circle._ + def area: Double = calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = Circle(5.0) + +circle1.area +``` + +`class Circle`は各インスタンスの固有のメンバー`area`を持ち、シングルトンオブジェクト`object Circle`は全てのインスタンスで利用できる`calculateArea`メソッドを持ちます。 + +コンパニオンオブジェクトはファクトリーメソッドを含むことができます。 +```scala mdoc +class Email(val username: String, val domainName: String) + +object Email { + def fromString(emailString: String): Option[Email] = { + emailString.split('@') match { + case Array(a, b) => Some(new Email(a, b)) + case _ => None + } + } +} + +val scalaCenterEmail = Email.fromString("scala.center@epfl.ch") +scalaCenterEmail match { + case Some(email) => println( + s"""Registered an email + |Username: ${email.username} + |Domain name: ${email.domainName} + """.stripMargin) + case None => println("Error: could not parse email") +} +``` +`object Email`はファクトリー`fromString`を持ち、Stringから`Email`インスタンスを作ります。 +パースエラーの場合も考えて、返り値の型を`Option[Email]`とします。 + +注意：クラスまたはオブジェクトがコンパニオンを持つ場合、クラス、オブジェクトの両方は同じファイルの中に定義されていなければなりません。 +REPL内でコンパニオンを定義する場合は、それらを同じ行で定義するか、`:paste`モードに入ります。 + +## Javaプログラマのための注意事項 ## + +Javaにおける`static`メンバーはScalaではコンパニオンオブジェクトの一般メンバーとして作られています。 + +Javaのコードからコンパニオンオブジェクトを使う場合、メンバーはコンパニオンクラス内で`static`識別子を用いて定義されます。 +これは*static forwarding*と呼ばれます。 +これはコンパニオンクラスを自分で定義していなかったとしても起きます。 diff --git a/_ja/tour/tour-of-scala.md b/_ja/tour/tour-of-scala.md new file mode 100644 index 0000000000..70c1e0f522 --- /dev/null +++ b/_ja/tour/tour-of-scala.md @@ -0,0 +1,79 @@ +--- +layout: tour +title: 前書き +language: ja +partof: scala-tour +num: 1 +next-page: basics +--- + +## ようこそツアーへ +このツアーはScalaで最もよく使う機能を一口サイズで紹介をしています。 +これらはScala初心者を対象としています。 + +これはほんの短いツアーで、完全な言語のチュートリアルではありません。 +もしそれを望むなら、[こちらの本](/books.html) を手に入れるか、 +[その他の解決手段](/online-courses.html) での相談を検討してください。 + +## Scalaとは？ +Scalaは一般的なプログラミング方法を簡潔かつエレガントかつ型安全な方法で表現するために設計されたモダンなマルチパラダイム言語です。 +それはオブジェクト指向言語と関数型言語の機能をスムーズに統合しています。 + +## Scalaはオブジェクト指向 ## +Scalaは[全ての値がオブジェクトである](unified-types.html) という意味では純粋オブジェクト指向言語です。 +型とオブジェクトの振る舞いは[クラス](classes.html) と[トレイト](traits.html) によって記述されます。 +クラスはサブクラス化と、多重継承を巧みに置き換える柔軟な[ミックスインを基にした合成](mixin-class-composition.html) 機構により拡張されます。 + +## Scalaは関数型 ## +Scalaは[すべての関数が値である](unified-types.html) という意味で関数型言語でもあります。 +Scalaは無名関数を定義するために[軽量な構文](basics.html#関数)を提供し、 +[高階関数](higher-order-functions.html) をサポートし、関数は[ネスト](nested-functions.html)しても良く、[カリー化](multiple-parameter-lists.html) をサポートします。 +Scalaの[ケースクラス](case-classes.html)には[パターンマッチング](pattern-matching.html)が組み込まれていることにより、多くの関数型プログラミング言語で使われる代数型を作ることができます。 +[シングルトンオブジェクト](singleton-objects.html) はクラスのメンバーではない関数をグループ化する便利な方法を提供します。 + +さらに、Scalaのパターンマッチングの概念は、[抽出子オブジェクト](extractor-objects.html) による一般的な拡張として、[右無視シーケンスパターン](regular-expression-patterns.html)の働きにより、自然に[XMLデータの処理](https://github.com/scala/scala-xml/wiki/XML-Processing) にまで拡張されています。 +（訳者註：現在のバージョンでは右無視シーケンスパターンの説明は正規表現のページから除かれています。[→古いバージョン](https://www.scala-lang.org/old/node/122)） +この文脈では、For内包表記はクエリの設計に役立ちます。 +これらの機能により、ScalaはWebサービスのようなアプリケーション開発に理想的なものとなっています。 + +## Scalaは静的型付け ## +Scalaは抽象化が安全で首尾一貫した方法で使われることをコンパイル時に強制する、表現力豊かな型システムを備えています。 +特にその型システムは以下をサポートします: + +* [ジェネリッククラス](generic-classes.html) +* [変位指定アノテーション](variances.html) +* [上限](upper-type-bounds.html) と [下限](lower-type-bounds.html) 型境界 +* [内部クラス](inner-classes.html) とオブジェクトメンバーとしての[抽象型メンバー](abstract-type-members.html) +* [複合型](compound-types.html) +* [明示的に型指定された自己参照](self-types.html) +* [暗黙パラメーター](implicit-parameters.html) と [暗黙の変換](implicit-conversions.html) +* [ポリモーフィックメソッド](polymorphic-methods.html) + +[型推論](type-inference.html) は、ユーザーがコードに冗長な型情報の注釈をつける必要はないことを意味します。 +これらの機能を組み合わせることにより、プログラミングの抽象化を安全に再利用でき、ソフトウェアを型安全に拡張できる強力な基盤となります。 + +## Scalaは拡張可能 ## + +実際問題として、ドメイン固有のアプリケーションの開発ではよくドメイン固有の言語拡張が必要となります。 +Scalaは言語メカニズムのユニークな組み合わせを提供します。それにより、新しい言語構成要素をライブラリという形で円滑に追加することを簡単にします。 + +多くのケースで、これはマクロのようなメタプログラミングの機能を使わずに実現できます。例えば、 + +* [暗黙のクラス](https://docs.scala-lang.org/overviews/core/implicit-classes.html) で既存の型に拡張メソッドを追加できます。 + +* [文字列補間](/ja/overviews/core/string-interpolation.html) はカスタム補間を使ってユーザー拡張可能です。 + +## Scalaの相互運用 + +Scalaは一般的なJava実行環境 (JRE) と相互運用するように設計されています。 +特に、主流であるオブジェクト指向のJavaプログラミング言語とのやり取りはできるだけスムーズになっています。 +ScalaではSAMs、[ラムダ](higher-order-functions.html) 、[アノテーション](annotations.html) 、[ジェネリクス](generic-classes.html) のようなJavaの新しい機能には直接の類似物があります。 + +[デフォルト引数](default-parameter-values.html) 、[名前付きパラメータ](named-arguments.html) +といった、Javaに類似物がないScalaの機能はできるだけ適切でJavaに近い形にコンパイルされます。 +ScalaはJavaのような同じコンパイルモデル(分割コンパイル、動的クラス読み込み) を持っており、数千の既存の高品質なライブラリにアクセスができます。 + +## ツアーを楽しんで! + +もっと読むには、目次メニューの[次のページ](basics.html) に進んでください。 + diff --git a/_ja/tour/traits.md b/_ja/tour/traits.md new file mode 100644 index 0000000000..3803005571 --- /dev/null +++ b/_ja/tour/traits.md @@ -0,0 +1,83 @@ +--- +layout: tour +title: トレイト +language: ja +partof: scala-tour +num: 5 +next-page: tuples +previous-page: classes +topics: traits +prerequisite-knowledge: expressions, classes, generics, objects, companion-objects +--- + +トレイトはクラス間でインターフェースとフィールドを共有するために使います。それらはJava 8のインターフェースと似ています。 +クラスとオブジェクトはトレイトを継承することができますが、トレイトはインスタンス化ができません、したがってパラメータを持ちません。 + +## トレイトを定義する +最小のトレイトはキーワード `trait` と識別子だけというものです。 + +```scala mdoc +trait HairColor +``` + +トレイトはジェネリック型として、抽象メソッドとあわせて使うと特に便利です。 +```scala mdoc +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} +``` + +`trait Iterator[A]` を継承することは `A` 型と、`hasNext` と `next` メソッドの実装を必要とします。 + +## トレイトの使い方 +トレイトを継承するには `extends` キーワードを使います。その際に、 `override` キーワードを利用しすべての抽象メンバーを実装します。 +```scala mdoc:nest +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} + +class IntIterator(to: Int) extends Iterator[Int] { + private var current = 0 + override def hasNext: Boolean = current < to + override def next(): Int = { + if (hasNext) { + val t = current + current += 1 + t + } else 0 + } +} + + +val iterator = new IntIterator(10) +iterator.next() // returns 0 +iterator.next() // returns 1 +``` +ここでの `IntIterator` クラスは上限として引数 `to` を取ります。 +`extends Iterator[Int]` は `next` メソッドは Int を返さなければならないことを意味します。 + +## サブタイピング +あるトレイトが必要とされている場所に、代りにそのトレイトのサブタイプを使うことができます。 + +```scala mdoc +import scala.collection.mutable.ArrayBuffer + +trait Pet { + val name: String +} + +class Cat(val name: String) extends Pet +class Dog(val name: String) extends Pet + +val dog = new Dog("Harry") +val cat = new Cat("Sally") + +val animals = ArrayBuffer.empty[Pet] +animals.append(dog) +animals.append(cat) +animals.foreach(pet => println(pet.name)) // Prints Harry Sally +``` +`trait Pet` が持つ抽象フィールド `name`は、Cat と Dog のコンストラクタで実装されています。 +最終行では、`Pet` トレイトの全てのサブタイプの中で実装される必要がある `pet.name` を呼んでいます。 diff --git a/_ja/tour/tuples.md b/_ja/tour/tuples.md new file mode 100644 index 0000000000..e3c2f1e0f7 --- /dev/null +++ b/_ja/tour/tuples.md @@ -0,0 +1,73 @@ +--- +layout: tour +title: タプル +language: ja +partof: scala-tour +num: 6 +next-page: mixin-class-composition +previous-page: traits +topics: tuples +--- + +Scalaではタプルは決まった数の要素を含む値であり、各要素はそれぞれの型を持ちます。 +タプルは不変です。 + +タプルはメソッドから複数の値を返す際に特に役立ちます。 + +2つの要素を持つタプルは以下のように作ることができます。 + +```scala mdoc +val ingredient = ("Sugar" , 25) +``` +ここでは`String`要素を1つと`Int`要素を1つ含むタプルを作っています。 + +推論される`ingredient`の型は`(String, Int)`であり、これは`Tuple2[String, Int]`の簡単な表記法です。 + +タプルを表すために、Scalaは`Tuple2`, `Tuple3` … `Tuple22`までのクラス群を使います。 +それぞれのクラスは要素の数と同じ数の型パラメータを持ちます。 + +## 要素へのアクセス + +タプルの要素へのアクセス方法の1つとして、位置があります。 +個々の要素は`_1`、`_2`などと名付けられます。 + +```scala mdoc +println(ingredient._1) // Sugar +println(ingredient._2) // 25 +``` +## タプルでのパターンマッチング +タプルはパターンマッチングを使って分解することもできます。 + +```scala mdoc +val (name, quantity) = ingredient +println(name) // Sugar +println(quantity) // 25 +``` + +ここでは`name`に推論される型は`String`で、`quantity`に推論される型は`Int`です。 + +こちらはタプルのパターンマッチングの他の例です。 + +```scala mdoc +val planets = + List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6), + ("Mars", 227.9), ("Jupiter", 778.3)) +planets.foreach{ + case ("Earth", distance) => + println(s"Our planet is $distance million kilometers from the sun") + case _ => +} +``` + +また、`for`内包表記では以下のようになります。 + +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) +for ((a, b) <- numPairs) { + println(a * b) +} +``` + +## タプルとケースクラス +ユーザーは時々、タプルとケースクラスの選択を難しいと思うかもしれません。ケースクラスには名前付き要素があります。それらの名前によってコードの可読性を改善できる場合があります。 +上記の惑星の例ではタプルを使うより、`case class Planet(name: String, distance: Double)`を定義したほうがいいかもしれません。 diff --git a/_ja/tour/type-inference.md b/_ja/tour/type-inference.md new file mode 100644 index 0000000000..5973da20a2 --- /dev/null +++ b/_ja/tour/type-inference.md @@ -0,0 +1,70 @@ +--- +layout: tour +title: 型推論 +language: ja +partof: scala-tour +num: 29 +next-page: operators +previous-page: polymorphic-methods +--- + +Scalaコンパイラが式の型を推論できることが多いので、明示的に型を宣言する必要はありません。 + +## 型の省略 + +```scala mdoc +val businessName = "Montreux Jazz Café" +``` +コンパイラは`businessName`がStringだと検知できます。これはメソッドでも同様に動きます。 + +```scala mdoc +def squareOf(x: Int) = x * x +``` +コンパイラは戻り値の型が`Int`だと推論できるので、明示的な戻り値の型は必要ありません。 + +再帰的メソッドでは、コンパイラは結果の型を推論できません。こちらはこの理由でコンパイラが失敗するプログラムです。 + +```scala mdoc:fail +def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1) +``` + +[ポリモーフィックメソッド](polymorphic-methods.html)が呼ばれる時や[ジェネリッククラス](generic-classes.html) がインスタンス化される場合も型パラメータの指定は強制ではありません。Scalaコンパイラは文脈あるいはメソッドやコンストラクタの実際の引数から、指定されていない型パラメータを推論します。 + +こちらは2つの例です。 + +```scala mdoc +case class MyPair[A, B](x: A, y: B) +val p = MyPair(1, "scala") // 型: MyPair[Int, String] + +def id[T](x: T) = x +val q = id(1) // 型: Int +``` +コンパイラは型`A`と`B`が何であるかを見つけ出すために`MyPair`の引数の型を使用します。`x`の型も同様です。 + +## パラメータ + +コンパイラはメソッドのパラメータ型を決して推論しません。しかし、関数が引数として渡されている場合は、無名関数のパラメータ型を推論できます。 + +```scala mdoc +Seq(1, 3, 4).map(x => x * 2) // List(2, 6, 8) +``` + +mapのパラメータは`f: A => B`です。`Seq`の中に整数が入っているので、コンパイラは`A`が`Int`だと知っています(つまり、この`x`は整数です)。したがってコンパイラは`x * 2`から`B`が型`Int`であると推論できます。 + +## 型推論に頼ら*ない*時 + +一般的には、パブリックなAPIで公開されているメンバーの型を宣言したほうが読みやすいと考えられています。そのため、ユーザーに公開するAPIではあなたのコードの型を明示することをお勧めします。 + +また、型推論は特定の型を推論することがあります。次のように書いたとします。 + +```scala +var obj = null +``` + +これ以上進められず、再割り当てができません。 + +```scala mdoc:fail +obj = new AnyRef +``` + +こちらはコンパイルできません。`obj`に推論された型は`Null`だからです。その型の唯一の値が`null`なので、他の値を代入できれません。 diff --git a/_ja/tour/unified-types.md b/_ja/tour/unified-types.md new file mode 100644 index 0000000000..28e44ad510 --- /dev/null +++ b/_ja/tour/unified-types.md @@ -0,0 +1,91 @@ +--- +layout: tour +title: 統合された型 +language: ja +partof: scala-tour +num: 3 +next-page: classes +previous-page: basics +prerequisite-knowledge: classes, basics +--- +Scalaでは数値や関数を含め、全ての値は型を持ちます。 +以下の図は型階層の一部を説明しています。 + +Scala Type Hierarchy + +## Scalaの型階層 ## + +[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html) は全ての型のスーパータイプであり、トップ型とも呼ばれます。 +Anyは `equals`、`hashCode`、そして `toString`のようないくつかの普遍的なメソッドを定義しています。 +そして`AnyVal`と`AnyRef` という2つの直系のサブクラスを持ちます。 + +`AnyVal` は値型に相当します。 +事前に定義された9つの値型が存在し、それら`Double`、`Float`、`Long`、`Int`、`Short`、`Byte`、`Char`、`Unit`、`Boolean`は +null非許容です。 +`Unit`は意味のある情報をもたない値型です。`Unit`型のインスタンスはただ1つだけあり、`()`というリテラルで宣言することができます。 +全ての関数は必ず何かを返さなければなりません。そのため`Unit`は戻り値の型として時々役立ちます。 + +`AnyRef` は参照型を意味します。全ての値型でない型は参照型として定義されます。Scalaでは全てのユーザー定義型は`AnyRef`のサブタイプになります。 +もしScalaがJava実行環境上で利用されるなら、`AnyRef` は `java.lang.Object` に相当します。 + +以下にstring、integer、character、boolean、関数が他のオブジェクトと同様に全てオブジェクトであるという例を示します。 + +```scala mdoc +val list: List[Any] = List( + "a string", + 732, // integer + 'c', // character + true, // boolean value + () => "文字列を返す無名関数" +) + +list.foreach(element => println(element)) +``` + +これは`List[Any]`型の`list`という値を定義します。 +このlistは様々な型の要素で初期化されています。しかしそれぞれの要素は `scala.Any` のインスタンスなのでlistに追加することができています。 + +こちらは先程のプログラムの出力です。 + +``` +a string +732 +c +true + +``` + +## 型キャスト +値型は以下の順序でキャストできます。 + +Scalaの型階層 + +例えば、 + +```scala mdoc +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 (この場合精度が落ちることに注意してください) + +val face: Char = '☺' +val number: Int = face // 9786 +``` + +型変換は一方向です。これはコンパイルができないでしょう。 + +``` +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 +val z: Long = y // 一致しない +``` + +参照型をサブタイプにキャストすることもできます。こちらはツアーの中で後ほど紹介します。 + +## Nothing と Null +`Nothing`は全ての型のサブタイプであり、ボトム型とも呼ばれます。`Nothing`型を持つ値は存在しません。 +一般的に例外のスロー、プログラム終了、無限ループなど終了していないことを示すのに使われます。 +(すなわち、値として評価されない式や正常に返らないメソッドなどです。) + + +`Null` は全ての参照型のサブタイプ(すなわち、全てのAnyRefのサブタイプ)です。`null`というキーワードリテラルが指す値を1つだけもちます。 +`Null` は、ほぼ他のJVM言語との相互運用性のためだけに提供されているので、Scalaのコード内ではほとんどの場合、使われるべきではありません。 +`null`の代替手段については、後のツアーで説明します。 diff --git a/_ja/tour/upper-type-bounds.md b/_ja/tour/upper-type-bounds.md new file mode 100644 index 0000000000..8dfe6ca8ac --- /dev/null +++ b/_ja/tour/upper-type-bounds.md @@ -0,0 +1,55 @@ +--- +layout: tour +title: 上限型境界 +language: ja +partof: scala-tour +categories: tour +num: 20 +next-page: lower-type-bounds +previous-page: variances +--- + +Scalaでは [型パラメータ](generic-classes.html)と[抽象型メンバー](abstract-type-members.html) は型境界による制約をかけることができます。 +型境界は型変数に入れられる具象型を制限して、時にはそれらの型のメンバーについてより多くの情報を与えます。 +_上限型境界_ `T <: A` は型変数`T`が型`A`のサブタイプであるという宣言です。 + +こちらはクラス`PetContainer`の型パラメータの上限型境界を実演する例です。 + +```scala mdoc +abstract class Animal { + def name: String +} + +abstract class Pet extends Animal {} + +class Cat extends Pet { + override def name: String = "Cat" +} + +class Dog extends Pet { + override def name: String = "Dog" +} + +class Lion extends Animal { + override def name: String = "Lion" +} + +class PetContainer[P <: Pet](p: P) { + def pet: P = p +} + +val dogContainer = new PetContainer[Dog](new Dog) +val catContainer = new PetContainer[Cat](new Cat) +``` + +```scala mdoc:fail +// これはコンパイルされません +val lionContainer = new PetContainer[Lion](new Lion) +``` +`class PetContainer`は型パラメータ`P`を受け取ります。それは`Pet`のサブタイプである必要があります。 + `Dog`と`Cat`は`Pet`のサブタイプなので、新たな`PetContainer[Dog]`と`PetContainer[Cat]`を作ることができます。 + しかしながら、もし`PetContainer[Lion]`を作ろうとすると、以下のエラーが返ってきます。 + +`type arguments [Lion] do not conform to class PetContainer's type parameter bounds [P <: Pet]` + +これは`Lion`は`Pet`のサブタイプではないからです。 diff --git a/_ja/tour/variances.md b/_ja/tour/variances.md new file mode 100644 index 0000000000..314f8c2e48 --- /dev/null +++ b/_ja/tour/variances.md @@ -0,0 +1,178 @@ +--- +layout: tour +title: 変位指定 +language: ja +partof: scala-tour +num: 19 +next-page: upper-type-bounds +previous-page: generic-classes +--- + +変位指定は複合型の間の継承関係とそれらの型パラメータ間の継承関係の相関です。 +Scalaは[ジェネリッククラス](generic-classes.html)の型パラメータの変位指定アノテーションをサポートしています。 +変位指定アノテーションにより共変、反変にでき、アノテーション無しなら非変になります。 +型システム上で変位指定を利用すると複合型間の直感的な繋がりを作ることができます。 +もし変位指定が無ければ、クラスを抽象化して再利用しにくくなるでしょう。 + + +```scala mdoc +class Foo[+A] // 共変クラス +class Bar[-A] // 反変クラス +class Baz[A] // 非変クラス +``` + +### 共変 + +ジェネリッククラスの型パラメータ`A`はアノテーション`+A`を使うと共変になります。 +`class List[+A]`では、`A`が共変になっているので、`A`が`B`のサブタイプであるような`A`と`B`に対して`List[A]`が`List[B]`のサブタイプであることを示します。 +これによりジェネリックを利用したとても便利で直感的なサブタイプの関係を作ることができます。 + +このシンプルなクラス構成を考えてみましょう。 + +```scala mdoc +abstract class Animal { + def name: String +} +case class Cat(name: String) extends Animal +case class Dog(name: String) extends Animal +``` +`Cat`と`Dog`は`Animal`のサブタイプです。 +Scala標準ライブラリにはイミュータブルなジェネリッククラス`sealed abstract class List[+A]`があり、型パラメータ`A`が共変です。 +これは`List[Cat]`は`List[Animal]`であり、`List[Dog]`も`List[Animal]`であることを意味します。 +猫のリストも犬のリストも動物のリストであり、どちらも`List[Animal]`の代わりにできる、というのは直感的に理解できます。 + +以下の例では、メソッド`printAnimalNames`は引数に動物のリストを受け取り、新しい行にそれらの名前をプリントします。 +もし`List[A]`が共変でなければ、最後の2つのメソッド呼び出しはコンパイルされず、`printAnimalNames`メソッドの使い勝手はひどく制限されます。 + +```scala mdoc +object CovarianceTest extends App { + def printAnimalNames(animals: List[Animal]): Unit = { + animals.foreach { animal => + println(animal.name) + } + } + + val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom")) + val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex")) + + printAnimalNames(cats) + // Whiskers + // Tom + + printAnimalNames(dogs) + // Fido + // Rex +} +``` + +### 反変 + +ジェネリッククラスの型パラメータ`A`はアノテーション`-A`を利用して反変にできます。 +これはクラスとその型パラメータの間で、共変と似ていますが反対の意味のサブタイプ関係を作ります。 + +`class Writer[-A]`では`A`が反変になっているので、`A`が`B`のサブタイプであるような`A`と`B`に対し、`Writer[B]`が`Writer[A]`のサブタイプであることを示します。 + +先に定義された`Cat`、`Dog`、`Animal`クラスを以下の例で検討してみます。 + +```scala mdoc +abstract class Printer[-A] { + def print(value: A): Unit +} +``` +`Printer[A]`はある型`A`をどのようにプリントするかを知っている簡単なクラスです。 +特定の型でいくつかのサブクラスを定義してみましょう。 + +```scala mdoc +class AnimalPrinter extends Printer[Animal] { + def print(animal: Animal): Unit = + println("The animal's name is: " + animal.name) +} + +class CatPrinter extends Printer[Cat] { + def print(cat: Cat): Unit = + println("The cat's name is: " + cat.name) +} +``` +`Printer[Cat]`はコンソールに任意の`Cat`をプリントする方法を知っています。 +そして`Printer[Animal]`はコンソールに任意の`Animal`をプリントする方法を知っています。 +それは`Printer[Animal]`も任意の`Cat`をプリントする方法を知っていることを意味します。 +逆の関係性は適用されません、それは`Printer[Cat]`がコンソールに任意の`Animal`をプリントする方法を知らないからです。 +したがって、私達は必要であれば`Printer[Animal]`を`Printer[Cat]`代わりに使うことができます。これは`Printer[A]`が反変であるからこそ可能なのです。 + +```scala mdoc +object ContravarianceTest extends App { + val myCat: Cat = Cat("Boots") + + def printMyCat(printer: Printer[Cat]): Unit = { + printer.print(myCat) + } + + val catPrinter: Printer[Cat] = new CatPrinter + val animalPrinter: Printer[Animal] = new AnimalPrinter + + printMyCat(catPrinter) + printMyCat(animalPrinter) +} +``` + +この出力結果は以下のようになります。 + +``` +The cat's name is: Boots +The animal's name is: Boots +``` + +### 非変 + +Scalaのジェネリッククラスは標準では非変です。 +これは共変でも反変でもないことを意味します。 +以下の例の状況では、`Container`クラスは非変です。`Container[Cat]`は`Container[Animal]`_ではなく_、逆もまた同様です。 + +```scala mdoc +class Container[A](value: A) { + private var _value: A = value + def getValue: A = _value + def setValue(value: A): Unit = { + _value = value + } +} +``` +`Container[Cat]`が `Container[Animal]`でもあることは自然なように思えるかもしれませんが、ミュータブルジェネリッククラスを共変にするのは安全ではありません。 +この例では、`Container`が非変であることは非常に重要です。`Container`が仮に共変だったとするとこのようなことが起こり得ます。 + +``` +val catContainer: Container[Cat] = new Container(Cat("Felix")) +val animalContainer: Container[Animal] = catContainer +animalContainer.setValue(Dog("Spot")) +val cat: Cat = catContainer.getValue // おっと、犬を猫に割り当ててしまった。 +``` + +幸いにも、実行する前にコンパイラが止めてくれます。 + +### 他の例 + +変位指定の理解を助けるもう一つの例はScala標準ライブラリの`trait Function1[-T, +R]`です。 +`Function1`は1つのパラメータを持つ関数を表します。1つ目の型パラメータ`T`はパラメータの型を表します。 +そして2つ目の型パラメータ`R`は戻り値の型を表します。 +`Function1`はその引数の型に対して反変であり、戻り値の型に対して共変です。 +この例では`Function1[A, B]`を表現するために`A => B`という文字での表記をします。 + +先ほど利用された`Cat`, `Dog`, `Animal`の継承ツリーに、以下のものを加えましょう： + +```scala mdoc +abstract class SmallAnimal extends Animal +case class Mouse(name: String) extends SmallAnimal +``` + +動物の種類を受け取り、それらが食べる食料の種類を返す関数がいくつかあるとしましょう。 +もし（猫は小動物を食べるので）`Cat => SmallAnimal`が欲しい場合に代わりに`Animal => Mouse`を与えられたとしても、私たちのプログラムはまだ動きます。 +直感的に、`Cat`は`Animal`なので、`Animal => Mouse` は`Cat`を引数として受け取ります。 +そして`SmallAnimal`である`Mouse`を返します。 + +安全に、そのままで前者に代えて後者を用いることができるため、`Animal => Mouse`は`Cat => SmallAnimal`のサブタイプと言うことができます。 + +### 他の言語との比較 + +Scalaに似たいくつかの言語で、変位指定はいろんな方法でサポートされています。 +例えば、Scalaの変位指定アノテーションはC#のそれと非常に似ています。C#ではクラスの抽象性を定義する時にアノテーションが追加されます(宣言時の変位指定)。 +しかしながら、Javaでは、クラスの抽象性を使う時に変位指定アノテーションが利用側のコードから与えられます(使用時の変位指定)。 diff --git a/_ja/tutorials/scala-for-java-programmers.md b/_ja/tutorials/scala-for-java-programmers.md new file mode 100644 index 0000000000..a2076100b1 --- /dev/null +++ b/_ja/tutorials/scala-for-java-programmers.md @@ -0,0 +1,549 @@ +--- +layout: singlepage-overview +title: JavaプログラマーのためのScalaチュートリアル +partof: scala-for-java-programmers +language: ja +--- + +原文 Michel Schinz and Philipp Haller
      +翻訳 TATSUNO Yasuhiro + +## はじめに + +この文書は、Scala 言語とコンパイラを手短に紹介します。 +ある程度プログラミング経験を持ち、Scala で何ができるかについて概要を知りたい方向けです。 +オブジェクト指向プログラミング、とりわけ Java についての基本的な知識を前提とします。 + +## 最初の例 + +最初の例として、基本的な **Hello World** プログラムを用います。 +興味をそそられるものではありませんが、言語についてほとんど知らなくてもScala ツールの使い方を実演しやすいです。 +こんな感じです: + + object HelloWorld { + def main(args: Array[String]): Unit = { + println("Hello, world!") + } + } + +このプログラムの構造は、Java プログラマにはなじみ深いはずです。 +`main` と呼ばれるメソッドがあり、それはパラメータとしてコマンドライン引数（文字列の配列）を受け取ります。 +このメソッドの本体は、事前に定義されたメソッド `println` に友好的な挨拶を引数にして、1回だけ呼び出しています。 +`main` メソッドは値を返しません（手続きメソッド）。 +そのため、その戻り値の型は `Unit` として宣言されます。 + +Java プログラマにあまりなじみがないのは、`main` メソッドを含む `object` という宣言です。 +Scala はそのような宣言によって、一般に**シングルトンオブジェクト**として知られる、インスタンスを１つだけ有するクラスを取り入れています。 +そのため先の宣言は、`HelloWorld` という名前のクラスと、そのクラスのただ1つのインスタンス（これまた `HelloWorld` という名前）両方を宣言しています。 +このインスタンスは必要に応じ、初めて使われるときに生成されます。 + +鋭い読者なら `main` メソッドが `static` として宣言されていないことに気づいたかもしれません。 +これは Scala には static メンバー（メソッドまたはフィールド）が存在しないからです。 +static メンバーを定義するよりも、Scala プログラマーはシングルトンオブジェクトにそれらメンバーを宣言します。 + +### 例をコンパイルする + +先の例をコンパイルするために、Scala コンパイラー `scalac` を使います。 +`scalac` はほとんどのコンパイラーと同様に動きます。 +ソースファイルといくつかのオプションを引数として受け取り、１つか複数のオブジェクトファイルを作ります。 +作られるオブジェクトファイルは、標準的な Java クラスファイルです。 + +上記のプログラムを `HelloWorld.scala` というファイルに保存したら、次のコマンドを発行することでコンパイルできます +（大なり記号 `>` はシェルプロンプトを表しており、入力しないでください）。 + + > scalac HelloWorld.scala + +これにより、カレントディレクトリに数個のクラスファイルが生成されます。 +そのひとつは `HelloWorld.class` というもので、`scala` コマンドを使って直接実行可能（次の章で説明）なクラスを含んでいます。 + +### 例を実行する + +一度コンパイルされると、Scala プログラムは `scala` コマンドを使って実行できます。 +その使い方は、Java プログラムの実行に使われる `java` コマンドとよく似ており、同じオプションを受け入れます。 +上の例は以下のコマンドを使って実行でき、期待される結果を生成します。 + + > scala -classpath . HelloWorld + + Hello, world! + +## Java とのインタラクション + +Scala の強みの１つは、Java コードと相互作用するのがとても簡単なことです。 +`java.lang` パッケージのすべてのクラスは初期設定でインポートされています。 +他のクラスは明示的にインポートされる必要があります。 + +これを実演する例を見てみましょう。 +現在の日付を取得し、特定の国たとえばフランスの慣例に従って書式設定したいとします +（他の地域、例えばスイスのフランス語を話す範囲も同じ慣例を使います）。 + +Java のクラスライブラリは、強力なユーティリティクラス、例えば `Date` や `DateFormat` を定義しています. +Scala は Java とシームレスに相互運用できるので、Scala クラスライブラリに同等のクラスを実装する必要はありません。 +対応する Java パッケージのクラスをただインポートするだけです。 + + import java.util.{Date, Locale} + import java.text.DateFormat._ + + object FrenchDate { + def main(args: Array[String]): Unit = { + val now = new Date + val df = getDateInstance(LONG, Locale.FRANCE) + println(df format now) + } + } + +Scala のインポート文は Java と同等のものととてもよく似ていますが、ずっと強力です。 +1行目にあるように、波括弧で囲むことで同じパッケージから複数のクラスをインポートできます。 +また別の違いとして、パッケージやクラスのすべての名前をインポートするときは、アスタリスク `*` の代わりにアンダースコア文字 `_` を使います。 +というのもアスタリスクは、あとで見るように Scala の識別子（例えばメソッド名）として有効だからです。 + +それゆえ2行目のインポート文は、`DateFormat` クラスのすべてのメンバーをインポートします。 +これによって static メソッド `getDateInstance` や static フィールド `LONG` が直接利用可能になります。 + +`main` メソッドの中では、まず Java の `Date` クラスのインスタンスを作成します。 +このインスタンスはデフォルトで現在の日時を含んでいます。 +次に、先ほどインポートした static の `getDateInstance` メソッドを使って日付の書式を定義します。 +最後に、ローカライズされた `DateFormat` インスタンスによって書式設定された現在の日付を表示します。 +この最後の行は Scala の構文の興味深い特性を表しています。 +1引数メソッドには、中置（infix）記法を用いることができます。 +つまり、式 + + df format now + +は、次の式 + + df.format(now) + +よりも少しだけ冗長でなくなった書き方です。 + +これは大したことのない構文上の詳細に思えるかもしれませんが、重要な影響をもたらします。 +その１つについては次の節で詳しく取り上げます。 + +Java との相互作用についての本節を終える前に、Scala では Java クラスを継承したり、Java インターフェースを実装できることも記しておきます。 + +## すべてがオブジェクト + +Scala は、数値や関数を含む**あらゆるもの**がオブジェクトであるという意味で、純粋なオブジェクト指向言語です。 +この点において、プリミティブ型（例えば `boolean` や `int`）を参照型と区別する Java とは異なります。 + +### 数値はオブジェクト + +数値もまたオブジェクトなのでメソッドを持っています。 +実のところ、以下のような数値計算 + + 1 + 2 * 3 / x + +は、メソッド呼び出しのみから成り立っています。 +というのもこの式は、前節で見たように以下の式に相当するからです。 + + 1.+(2.*(3)./(x)) + +これは `+` や `*` などが Scala では識別子として有効であることを意味します。 + +### 関数はオブジェクト + +Scala では関数もオブジェクトです。 +それゆえ関数を引数として渡すこと、関数を変数に格納すること、他の関数から関数を返すことができます。 +関数を値として操作できるこの能力は、**関数プログラミング**と呼ばれるとても興味深いプログラミングパラダイムにとって不可欠なものの1つです。 + +関数を値として使えることが便利であるとてもシンプルな例として、タイマー関数を考えてみましょう。 +それは毎秒何らかの動作を実行するためのものです。 +実行したい動作をどうやって渡せるでしょうか？ +当然、関数としてです。 +関数渡しのとてもシンプルな例は、多くのプログラマーになじみ深いはずです。 +ユーザーインターフェースのコードで、何かイベントが起きたら呼ばれるコールバック関数を登録するのに、よく用いられています。 + +次のプログラムでは、`oncePerSecond` というタイマー関数がコールバック関数を引数として受取ります。 +この関数の型は `() => Unit` 、つまり、引数を受け取らず何も返さない（`Unit` 型は C/C++/Java の `void` と同様）すべての関数を表す型です。 +このプログラムの `main` 関数は、ターミナルに文を印字するコールバックを与えてタイマー関数を呼ぶだけのものです。 +つまりこのプログラムは延々と `"time flies like an array"` という文を毎秒印字します。 + + object Timer { + def oncePerSecond(callback: () => Unit): Unit = { + while (true) { callback(); Thread sleep 1000 } + } + def timeFlies(): Unit = { + println("time flies like an arrow...") + } + def main(args: Array[String]): Unit = { + oncePerSecond(timeFlies) + } + } + +文字列を印字するために使われているのが事前定義された `println` メソッドで、`System.out` の `println` ではないことに注意してください。 + +#### 匿名関数 + +このプログラムは理解しやすいですが、もう少し洗練できます。 +まず第一に、関数 `timeFlies` はあとで `oncePerSecond` 関数に渡すためだけに定義されていることに気づきます。 +たった一度しか使われない関数に名前をつけるのは不必要に思えるので、要は `oncePerSecoond` に渡す関数を作れさえすればよいでしょう。 +Scala では、まさにそんな名前を持たない関数、**匿名関数**を使えます。 +`timeFlies` の代わりに匿名関数を使って改正したタイマープログラムはこんな風になります。 + + object TimerAnonymous { + def oncePerSecond(callback: () => Unit): Unit = { + while (true) { callback(); Thread sleep 1000 } + } + def main(args: Array[String]): Unit = { + oncePerSecond(() => + println("time flies like an arrow...")) + } + } + +この例で匿名関数が登場することは、関数の引数リストと本体を分ける右矢印 `=>` から分かります。 +この例では、引数リストは空で、矢印の左にある中身のない括弧によって表されています。 +関数の本体は上記の `timeFlies` のものと同じです。 + +## クラス + +上で見てきたように、Scala はクラスという概念を持っているように、オブジェクト指向言語です +（正確には、クラスという概念のないオブジェクト指向言語もありますが、Scala はそうではありません）。 +Scala におけるクラスは Java の構文に近い構文を使って宣言されます。 +1つ重要な違いは、Scala におけるクラスはパラメータを持つことができることです。 +これは以下の素数の定義に示されています。 + + class Complex(real: Double, imaginary: Double) { + def re() = real + def im() = imaginary + } + +この `Complex` クラスは2つの引数、素数の実部と虚部を受け取ります。 +これら引数は `Complex` クラスのインスタンスを作成するときに必ず、`new　Complex(1.5, 2.3)` というように渡さなければなりません +このクラスは2つのメソッド `re` と `im` を持ち、これら2つの部分へアクセスできるようにします。 + +これら2つのメソッドの戻り値の型が明示されていないことに注意してください。 +コンパイラによって自動で推論されます。 +コンパイラはこれらメソッドの右側を調べ、どちらも `Double` 型の値を返すと推論します。 + +コンパイラはここでのように型をいつでも推論できるわけではありません。 +残念ながらいつできて、いつできないかを正確に分かる簡単な規則はありません。 +実際には、コンパイラは明示的に与えられていない型を推論できないときに訴えてくるので、あまり問題になりません。 +簡単な規則として、初心者 Scala プログラマーは、文脈から推定しやすそうな型宣言を省略してみてコンパイラーが認めてくれるか試してみてください。 +しばらくすれば、いつ型を省略するか、いつ明示的に指定するか、良い感触をつかむはずです。 + +### 引数なしのメソッド + +`re` と `im` メソッドにはちょっとした問題があります。 +次の例が示すように、それらを呼ぶには名前のあとに中身のない括弧を置かねばなりません。 + + object ComplexNumbers { + def main(args: Array[String]): Unit = { + val c = new Complex(1.2, 3.4) + println("imaginary part: " + c.im()) + } + } + +実部と虚部があたかもフィールドのようにアクセスできたらすばらしいですね。 +Scala では完全にこれが可能で、**引数なしのメソッド**としてそれらを定義するだけです。 +そのようなメソッドは、名前のあとに括弧を持たない（定義場所でも使用場所でも）という点で、0引数のメソッドと区別されます。 +`Complex` クラスは次のように書き直せます。 + + class Complex(real: Double, imaginary: Double) { + def re = real + def im = imaginary + } + + +### 継承とオーバーライド + +Scala におけるすべてのクラスはスーパークラスを継承します。 +前節の `Complex` の例のように、スーパークラスが指定されていないときは、暗黙的に `scala.AnyRef` が使われます。 + +Scalaでは、スーパークラスから継承されたメソッドをオーバーライドできます。 +予想外のオーバーライドを防ぐため、メソッドがオーバーライドしていることを`override` 修飾子を使って明に指定することが必須です。 +その例として、`Object` から継承した `toString` メソッドの再定義を `Complex` クラスに追加してみます。 + + class Complex(real: Double, imaginary: Double) { + def re = real + def im = imaginary + override def toString() = + "" + re + (if (im >= 0) "+" else "") + im + "i" + } + +オーバーライドされた `toString` は以下のように呼び出せます。 + + object ComplexNumbers { + def main(args: Array[String]): Unit = { + val c = new Complex(1.2, 3.4) + println("Overridden toString(): " + c.toString) + } + } + +## ケースクラスとパターンマッチ + +プログラムによく現れる一種のデータ構造は、木（訳注：ツリー）です。 +例えば、インタープリターやコンパイラーは通例、プログラムを木として内部的に表現します。 +XMLドキュメントもツリーです。 +何種類ものコンテナーが木、例えば赤黒木をベースとしています。 + +そのような木が Scala ではどのように表現され、操作されるかを、小さい計算機プログラムを通じて見ていきます。 +このプログラムの目的は、足し算と整数の定数と変数からなる、とても単純な演算式の操作です。 +`1+2` や `(x+x)+(7+y)` は、そのような式の2つの例です。 + +はじめにそのような式の表現を決めなければいけません。 +もっとも自然なのは木構造で、ノードは操作（ここでは加算）、葉は値（ここでは定数か変数）です。 + +Java では、そのような木構造はそのための抽象スーパークラス、ノードと葉それぞれの具象クラスで表現されるでしょう。 +関数プログラミング言語では、そのような目的には代数的データ型を用います。 +Scala は、それら2つの中間のような**ケースクラス**という概念を提供します。 +ここでは、ケースクラスが例題のツリー型を定義するためにどう使えるかを示しています。 + + abstract class Tree + case class Sum(l: Tree, r: Tree) extends Tree + case class Var(n: String) extends Tree + case class Const(v: Int) extends Tree + +クラス `Sum`、`Var`、`Const` がケースクラスとして宣言されているということは、それらが通常のクラスといくつかの点で違うことを意味します。 + +- クラスインスタンスを作るにあたり `new` キーワードは必須ではありません + （例えば、`new Const(5)` の代わりに `Const(5)` と書けます) +- コンストラクターパラメーターに対するゲッター関数は自動で定義されます + （つまり、クラス `Const` のインスタンス `c` のコンストラクターパラメーター `v` の値を `c.v` と書くだけで取得できます） +- メソッド `equals` と `hashCode` のデフォルト定義が提供されます。 + それらはインスタンスの同一性ではなく**構造**をもとに動きます。 +- メソッド `toString` のデフォルト定義が提供されます。 + 「ソースの外」で値を印字します（つまり、式 `x+1` のツリーは `Sum(Var(x),Const(1))` を印字します) +- これらクラスのインスタンスは、以下で見るようにパターンマッチを使って分解できます。 + +算術式を表すデータ型を定義できたので、それらを操作する演算の定義を始められます。 +ある**環境**における式を評価する関数から始めます。 +環境の目的は、変数に値を与えるためです。 +例えば、値 `5` が変数 `x` に結び付けられた環境を`{ x -> 5 }` と表すとして、そこでは式 `x+1` は `6` という結果を出します。　 + +そのため環境を表す方法を見つけなければいけません。 +もちろん、ハッシュテーブルのような連想データ構造を使うことができますが、関数を直接使うこともできます！ +環境とは実のところ値を（変数の）名前に結びつける関数に過ぎません。 +上記の環境 `{ x -> 5 }` は Scala ではシンプルに書けます。 + + { case "x" => 5 } + +この記法は、引数として文字列 `"x"` を受けとったら整数 `5` を返し、それ以外のときは例外とともに失敗する関数を定義します。 + +評価関数を書く前に、環境の型に名前を付けましょう。 +もちろん環境には型 `String => Int` をいつでも使えますが、この型に名前を付けておけばプログラムが単純になり、将来変更しやすくなります。 +これは Scala では次の記法で達成できます。 + + type Environment = String => Int + +以降、型 `Environment` は `String` から `Int` への関数の型の別名（訳注：エイリアス）として使えます。 + +これで評価関数の定義を与えることができます。 +概念上はとても簡単です。 +2式の和の値は、単にそれら式の値の和です。 +変数の値は環境から直接得られます。 +そして定数の値はそれ自身です。 +Scala でこれを表すと、これ以上難しくならないでしょう。 + + def eval(t: Tree, env: Environment): Int = t match { + case Sum(l, r) => eval(l, env) + eval(r, env) + case Var(n) => env(n) + case Const(v) => v + } + +この評価関数は、木 `t` に**パターンマッチ**を実行することで動作します。 +直感的に、上記定義の意味は明らかです。 + +1. まず `t` が `Sum` であるかをチェックします。 + もしそうであれば、左部分木を変数 `l` 、右部分木を変数 `r` に束縛します。 + それから矢印に続く式の評価を進めます。 + この式では矢印の左側に現れるパターンに束縛された変数 `l` と `r` を使うことができ、実際にそうしています。 +2. もし最初のチェックが成功しなければ、つまり木が `Sum` でなければ、続けて `t` が `Var` であるかチェックします。 + もしそうであれば、`Var` ノードに含まれる名前を変数 `n` に束縛し、右側の式に進みます。 +3. もし2つ目のチェックが失敗すれば、つまり `t` が `Sum` でも `Var` でもなければ、`Const` であるかどうかチェックします。 + もしそうであれば、`Const` ノードに含まれる値を変数 `v` に束縛し、右側の式に進みます。 +4. 最後に、すべてのチェックが失敗すれば、パターンマッチ式の失敗を知らせるために例外が発生します。 + これは `Tree` のサブクラスが他にも宣言されているときにのみ起こりえます。 + +パターンマッチの基本的なアイデアを見てきました。 +それは連続するパターンを値にマッチさせてみて、パターンがマッチすると値を抽出してその各部に名前をつけて、通常それら名前のついた部分を活用する何らかのコードを最終的に評価するものです。 + +経験豊富なプログラマであれば、`Tree` クラスやサブクラスの**メソッド**として `eval` を定義しなかったことを不思議がっているかもしれません。 +Scala は普通のクラスと同様にケースクラスにメソッド定義を許しているので、実際にはそうすることもできました。 +それゆえ、パターンマッチを使うかメソッドを使うかを決めるのは好みの問題ではありますが、拡張性について重要な示唆があります。 + +- メソッドを使うときは、`Tree` サブクラスを定義するだけでできるので、新種のノードを足すのは簡単です。 + 一方で、木を操作する新しい処理を追加するのは、`Tree` の全サブクラスの変更が必要になってしまうので、面倒です。 +- パターンマッチを使うときは、状況が逆になります。 + 新種のノード追加は、木に対するパターンマッチを使ったすべての関数で、新しいノードを考慮した修正を必要とします。 + 一方で、新しい処理を追加するのは、独立した関数を定義するだけなので簡単です。 + +パターンマッチについてさらに知るために、演算式に対する別の処理、数式微分を定義してみましょう。 +この処理についての次のような規則をご存知かもしれません。 + +1. 和の微分係数は、微分係数の和です。 +2. 何らかの変数 `v` の微分係数は、変数 `v` に対して微分されるなら1、そうでなければ0です。 +3. 定数の微分係数は0です。 + +これら規則はほぼ文字通り Scala コードに翻訳でき、次の定義が得られます。 + + def derive(t: Tree, v: String): Tree = t match { + case Sum(l, r) => Sum(derive(l, v), derive(r, v)) + case Var(n) if (v == n) => Const(1) + case _ => Const(0) + } + +この関数はパターンマッチに関連して2つの新しい概念を紹介しています。 +はじめに、変数への `case` 式が、`if` キーワードに続く式、**ガード**を持っています。 +このガードは、その式が真でない限りパターンマッチが成功するのを防ぎます。 +ここでのガードの使用は、微分される変数の名前が微分の変数 `v` と同じときにだけ、定数`1` を返すことを保証するためです。 +ここで使われているパターンマッチの新しい特徴2つ目は、`_` で書かれている**ワイルドカード**です。 +それはどんな値にもマッチして、名前をつけないパターンです。 + +パターンマッチの全力をまだ探っていませんが、この文章を短くするためにここで止めておきます。 +実例について上の2つの関数がどのように実行するかをまだ見たいですね。 +そのために、式 `(x+x)+(7+y)` にいくつかの処理を実行する簡単な `main` 関数を書いてみましょう。 +まず環境における値 `{ x -> 5, y -> 7 }` を計算し、次に `x` そして `y` についての微分係数を計算します。 + + def main(args: Array[String]): Unit = { + val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) + val env: Environment = { case "x" => 5 case "y" => 7 } + println("Expression: " + exp) + println("Evaluation with x=5, y=7: " + eval(exp, env)) + println("Derivative relative to x:\n " + derive(exp, "x")) + println("Derivative relative to y:\n " + derive(exp, "y")) + } + +コンパイルする前に、`Environment` 型、`eval`、`derive` そして `main` メソッドを `Calc` オブジェクトで包む必要があります。 +このプログラムを実行することで、期待する結果が得られます。 + + Expression: Sum(Sum(Var(x),Var(x)),Sum(Const(7),Var(y))) + Evaluation with x=5, y=7: 24 + Derivative relative to x: + Sum(Sum(Const(1),Const(1)),Sum(Const(0),Const(0))) + Derivative relative to y: + Sum(Sum(Const(0),Const(0)),Sum(Const(0),Const(1))) + +出力を観察することで、微分係数の結果はユーザーに示されるより前にシンプルにすべきことに気づきます。 +パターンマッチを使った基本的なシンプル化の定義は興味深い（ですが驚くほど一筋縄ではいかない）問題なので、読者への練習問題として残しておきます。 + +## トレイト + +スーパークラスからコードを継承するのとは別に、Scala クラスは1つ以上の**トレイト**からコードを取り込めます。 + +おそらく Java プログラマーにとってトレイトを理解するもっとも簡単な方法は、コードを含むことができるインターフェースとしてとらえることでしょう +Scala では、クラスがトレイトから継承するとき、トレイトのインターフェースを実装し、トレイトに含まれるコードをすべて継承します。 + +（注：Java 8 からは、Java インターフェースも同様にコードを含めるようになった。`default` キーワードをつけるか、または static メソッドとして) + +トレイトの有用性を見るため、古典的な例、順序付きオブジェクトを見てみましょう。 +あるクラスのオブジェクト同士を順序比較できると、例えば並び替え（ソート）できて、便利なことが多いです。 +Java では、比較できるオブジェクトは `Comparable` インターフェースを実装します。 +Scala では、`Comparable` 相当を `Ord` という名前のトレイトとして定義することで、Java よりも少しだけ良くなっています。 + +オブジェクトを比較するとき、6つの異なる述語（より小さい、より小さいか等しい、等しい、等しくない、より大きいか等しい、より大きい）が役に立ちます。 +しかし、これらすべてを定義するのは、これら6つのうち4つは残りの2つを使って表現できるので、退屈です。 +つまり、例えば「等しい」と「より小さい」の述語があれば、他を表現できるということです。 +Scala では、これらの観察結果は以下のトレイト宣言にうまくとらえられます。 + + trait Ord { + def < (that: Any): Boolean + def <=(that: Any): Boolean = (this < that) || (this == that) + def > (that: Any): Boolean = !(this <= that) + def >=(that: Any): Boolean = !(this < that) + } + +この定義は、Java の `Comparable` インターフェースと同じ働きをする `Ord` という新しい型と、3つの述語のデフォルト実装を4つ目の抽象述語を使うことで作成しています。 +等式と不等式の述語はすべてのオブジェクトにデフォルトで存在するので、ここには現れていません。 + +上で使われた型 `Any` は、Scala における `Any` 以外すべてのクラスのスーパー型です。 +Java の `Object` 型のより一般的なものとしてとらえられます。 +というのも `Int` や `Float` など基本型のスーパー型でもあるからです +（訳注：Java では `int` や `float` などのプリミティブ型は `Object` ではない）。 + +よって、あるクラスのオブジェクトを比較可能にするには、相等・不等を検査する述語を定義し、上の `Ord` クラスを混ぜ合わせれば十分です。 +例として、グレゴリオ暦の日付を `Date` クラスを定義してみましょう。 +その日付は、日、月、年から構成され、それぞれ整数で表しましょう。 +そのため、`Date` クラスの定義は次のように始めます。 + + class Date(y: Int, m: Int, d: Int) extends Ord { + def year = y + def month = m + def day = d + override def toString(): String = s"$year-$month-$day" + +ここで重要なのは、クラス名とパラメータのあとに続く `extends Ord` という宣言です。 +`Date` クラスが `Ord` トレイトを継承していることを宣言しています。 + +次に、日付がそれらの個々のフィールドで適切に比較されるように、`Object` から継承された `equals` メソッドを再定義します。 +Java のデフォルト実装はオブジェクトを物理的に比較するので、`equals` のデフォルト実装は使えません。 +次の定義に到着します。 + + override def equals(that: Any): Boolean = + that.isInstanceOf[Date] && { + val o = that.asInstanceOf[Date] + o.day == day && o.month == month && o.year == year + } + +このメソッドはあらかじめ定義されたメソッド `isInstanceOf` と `asInstanceOf` を使っています。 +1つ目の `isInstanceOf` は Java の `instanceof` 演算子に相当し、メソッドを適用したオブジェクトが与えられた型のインスタンスであるときに限り、true を返します。 +2つ目の `asInstaceOf` は Java のキャスト演算子に相当し、オブジェクトが与えられた型のインスタンスであればその型としてみなせるようにし、そうでなければ `ClassCastException` を発生させます。 + +最後に、最後に定義するメソッドは、次のとおり下級かどうかを調べる述語です。 +`scala.sys` パッケージオブジェクトの別のメソッド `error` を使っており、これは与えられたエラーメッセージつきの例外を発生させます。 + + def <(that: Any): Boolean = { + if (!that.isInstanceOf[Date]) + sys.error("cannot compare " + that + " and a Date") + + val o = that.asInstanceOf[Date] + (year < o.year) || + (year == o.year && (month < o.month || + (month == o.month && day < o.day))) + } + +これで `Date` クラスの定義は完成です。 +このクラスのインスタンスは、日付としても比較可能なオブジェクトとしても見ることができます。 +さらに、それらはすべて上で述べた6つの比較述語を定義しています。 +`equals` と `<` は `Date` クラスの定義に直接現れているから、他はそれらが `Ord` トレイトから継承されているからです。 + +ここで示した以外の状況でもトレイトはもちろん便利ですが、その応用を長々と説明するのはこの文章の範囲外です。 + +## ジェネリクス + +（訳注：原文では genericity が使われていますが、日本語ではジェネリクスという用語が広く使われているので、ジェネリクスとします） + +このチュートリアルで探る Scala の最後の特徴はジェネリクスです。 +Java プログラマーであれば、Java 言語におけるジェネリクスの欠如がもたらした問題、Java 5 で対応された欠点について、承知しているはずでしょう。 + +ジェネリクスとは、型によってパラメータ化されたコードを書ける能力です。 +例えば、連結リストのライブラリを書くプログラマーは、リストの要素にどのような型を与えるべきかという問題に直面します。 +このリストは多くの様々な文脈で使われはずなので、要素の型が例えば `Int` であると決めつけることはできません。 +これは完全に恣意的で、あまりにも抑圧的です。 + +Java プログラマーは、すべてのオブジェクトのスーパー型 `Object` の使用に頼ります。 +しかしこの解決方法は理想からかけ離れています。 +というのも基本型（`int`、`long`、`float`など）では動かないし、プログラマー自身によって動的な型キャストをたくさん挿入することになるからです。 + +Scala は、ジェネリッククラス（とメソッド）を定義できるようにすることで、この問題を解決しています。 +もっとも単純なコンテナークラス（空、または何らかの型のオブジェクトを指し示す、参照）を例に見てみましょう。 + + class Reference[T] { + private var contents: T = _ + def set(value: T) { contents = value } + def get: T = contents + } + +クラス `Reference` は、その要素の型である `T` という型でパラメーター化されています。 +この型は `contents` 変数の型として、`set` メソッドの引数の型として、`get` メソッドの戻り値の型として、クラス本体で使われています。 + +上のコード例は、Scala における変数を紹介しましたが、さらなる説明は必要ないでしょう。 +とはいえ、デフォルトの値を表す `_` によって変数の初期値を与えられることは興味深いでしょう。 +このデフォルト値は、数値型については0、`Boolean` 型には `false`、`Unit` 型には `()`、すべてのオブジェクト型には `null` です。 + +`Reference` クラスを使うには、型パラメーター `T` つまり `cell` によって格納される要素の型について、どの型を使うか宣言する必要があります、 +例えば、整数を保持する `cell` を作成して使うには、以下のように書くことができます。 + + object IntegerReference { + def main(args: Array[String]): Unit = { + val cell = new Reference[Int] + cell.set(13) + println("Reference contains the half of " + (cell.get * 2)) + } + } + +この例から分かるように、`get` メソッドから返って来た値を整数として使う前に、キャストする必要はありません。 +この特定のセルは整数を保持すると宣言されているので、整数以外を格納できません。 + +## 結び + +この文書は Scala 言語の短い概要を説明し、基本的なコード例を示しました。 +興味のある読者は、例えば、さらなる説明やコード例がある **[Scala ツアー](https://docs.scala-lang.org/ja/tour/tour-of-scala.html)** に進んでみたり、必要なら **[Scala 言語仕様](https://www.scala-lang.org/files/archive/spec/2.13/)** を調べられます。 diff --git a/_ko/tour/abstract-types.md b/_ko/tour/abstract-type-members.md similarity index 82% rename from _ko/tour/abstract-types.md rename to _ko/tour/abstract-type-members.md index cd68969e81..b57ea05c11 100644 --- a/_ko/tour/abstract-types.md +++ b/_ko/tour/abstract-type-members.md @@ -1,9 +1,6 @@ --- layout: tour title: 추상 타입 - -discourse: false - partof: scala-tour num: 22 @@ -39,16 +36,14 @@ previous-page: inner-classes type U = Int } - object AbstractTypeTest1 extends App { - def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = - new IntSeqBuffer { - type T = List[U] - val element = List(elem1, elem2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) - } + def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } + val buf = newIntSeqBuf(7, 8) + println("length = " + buf.length) + println("content = " + buf.element) 메소드 `newIntSeqBuf`의 반환 타입은 트레잇 `Buffer`의 특수화를 따르며, 타입 `U`가 `Int`와 같아진다. 메소드 `newIntSeqBuf` 내부의 익명 클래스 인스턴스화에서도 비슷한 타입 별칭이 있다. 여기선 `T` 타입이 `List[Int]`를 가리키는 `IntSeqBuf`의 새로운 인스턴스를 생성한다. @@ -60,15 +55,13 @@ previous-page: inner-classes abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { def length = element.length } - object AbstractTypeTest2 extends App { - def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = - new SeqBuffer[Int, List[Int]] { - val element = List(e1, e2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) - } + def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } + val buf = newIntSeqBuf(7, 8) + println("length = " + buf.length) + println("content = " + buf.element) 여기선 [가변성 어노테이션](variances.html)을 사용해야만 한다는 점에 유의하자. 이를 사용하지 않으면 메소드 `newIntSeqBuf`에서 반환되는 객체의 특정 시퀀스 구현 타입을 감출 수 없게 된다. 뿐만 아니라 추상 타입을 타입 파라미터로 대체할 수 없는 경우도 있다. diff --git a/_ko/tour/annotations.md b/_ko/tour/annotations.md index 4e2cba3524..11b5da4b50 100644 --- a/_ko/tour/annotations.md +++ b/_ko/tour/annotations.md @@ -1,16 +1,13 @@ --- layout: tour title: 어노테이션 - -discourse: false - partof: scala-tour num: 31 language: ko -next-page: default-parameter-values -previous-page: automatic-closures +next-page: packages-and-imports +previous-page: operators --- 어노테이션은 메타 정보와 정의 내용을 연결해준다. @@ -23,16 +20,15 @@ previous-page: automatic-closures | Scala | Java | | ------ | ------ | -| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (필드) | -| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | +| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](https://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (필드) | +| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](https://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | | [`scala.inline`](https://www.scala-lang.org/api/current/scala/inline.html) (2.6.0 부터) | 해당 없음 | -| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (2.6.0 부터) | [`native`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | -| [`scala.remote`](https://www.scala-lang.org/api/current/scala/remote.html) | [`java.rmi.Remote`](http://java.sun.com/j2se/1.5.0/docs/api/java/rmi/Remote.html) | -| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | -| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | +| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (2.6.0 부터) | [`native`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | +| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | +| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | | [`scala.unchecked`](https://www.scala-lang.org/api/current/scala/unchecked.html) (2.4.0 부터) | 해당 없음 | -| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | -| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`디자인 패턴`](http://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | +| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (키워드) | +| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`디자인 패턴`](https://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | 다음 예제에선 자바의 메인 프로그램에서 던지는 예외를 잡기 위해, `read` 메소드에 `throws` 어노테이션을 추가했다. @@ -77,7 +73,7 @@ Reader 클래스의 `throws` 어노테이션을 주석으로 처리하면 자바 **주의:** 자바 어노테이션과 함께 `-target:jvm-1.5` 옵션을 사용해야 한다. -자바 1.5에선 [어노테이션](http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html)이란 형태로 사용자 지정 메타데이터가 추가됐다. 어노테이션의 핵심 기능은 키와 값의 쌍을 지정해 자신의 항목을 초기화하는 데 기반하고 있다. 예를 들어 클래스의 출처를 추적하고 싶다면 다음과 같이 정의할 수 있다. +자바 1.5에선 [어노테이션](https://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html)이란 형태로 사용자 지정 메타데이터가 추가됐다. 어노테이션의 핵심 기능은 키와 값의 쌍을 지정해 자신의 항목을 초기화하는 데 기반하고 있다. 예를 들어 클래스의 출처를 추적하고 싶다면 다음과 같이 정의할 수 있다. @interface Source { public String URL(); @@ -86,13 +82,13 @@ Reader 클래스의 `throws` 어노테이션을 주석으로 처리하면 자바 그리고 이를 다음과 같이 적용한다. - @Source(URL = "http://coders.com/", + @Source(URL = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... 스칼라에선 어노테이션을 적용하는 방식은 생성자 호출과 비슷한 모습을 갖고 있으며 자바 어노테이션을 인스턴스화 하기 위해선 이름을 지정한 인수를 사용해야 한다. - @Source(URL = "http://coders.com/", + @Source(URL = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... @@ -105,23 +101,23 @@ Reader 클래스의 `throws` 어노테이션을 주석으로 처리하면 자바 그리고 이를 다음과 같이 적용한다. - @SourceURL("http://coders.com/") + @SourceURL("https://coders.com/") public class MyClass extends HisClass ... 이 경우엔 스칼라도 같은 기능을 제공한다. - @SourceURL("http://coders.com/") + @SourceURL("https://coders.com/") class MyScalaClass ... `mail` 항목은 기본 값과 함께 설정됐기 때문에 이 항목에 반드시 값을 명시적으로 할당할 필요는 없다. 하지만 만약 해야만 한다면, 자바의 두 스타일을 함께 섞어서 사용할 순 없다. - @SourceURL(value = "http://coders.com/", + @SourceURL(value = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... 스칼라에선 이를 사용하는 더 유연한 방법을 제공한다. - @SourceURL("http://coders.com/", + @SourceURL("https://coders.com/", mail = "support@coders.com") class MyScalaClass ... diff --git a/_ko/tour/automatic-closures.md b/_ko/tour/automatic-closures.md deleted file mode 100644 index 17d07625db..0000000000 --- a/_ko/tour/automatic-closures.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -layout: tour -title: 타입 의존 클로저의 자동 구성 - -discourse: false - -partof: scala-tour - -num: 30 -language: ko - -next-page: annotations -previous-page: operators ---- - -스칼라에선 파라미터가 없는 함수의 이름을 메소드의 파라미터로 사용할 수 있다. 이런 메소드가 호출되면 파라미터가 없는 함수의 이름에 해당하는 실제 파라미터를 찾지 않고, 대신 해당 파라미터의 계산을 캡슐화한 무항 함수를 전달하게 된다(소위 말하는 *이름에 의한 호출* 연산). - -다음 코드는 이 방식을 사용하는 방법을 보여준다. - - object TargetTest1 extends App { - def whileLoop(cond: => Boolean)(body: => Unit): Unit = - if (cond) { - body - whileLoop(cond)(body) - } - var i = 10 - whileLoop (i > 0) { - println(i) - i -= 1 - } - } - -`whileLoop` 함수는 `cond`와 `body`라는 두 파라미터를 받는다. 이 함수가 적용될 때 실제 파라미터는 계산되지 않는다. 대신 `whileLoop`의 내부에서 이 정형 파라미터를 사용할 때마다 암시적으로 생성된 무항 함수로 처리한다. 따라서 `whileLoop` 메소드는 재귀 구현의 방식에 맞춰 자바와 같은 while 반복문을 구현한다. - -[중위/후위 연산자](operators.html)와 이 기법을 함께 사용해 좀 더 복잡한 명령문(보기 좋게 작성된)을 생성할 수 있다. - -다음은 반복문을 제거한 명령문 구현이다. - - object TargetTest2 extends App { - def loop(body: => Unit): LoopUnlessCond = - new LoopUnlessCond(body) - protected class LoopUnlessCond(body: => Unit) { - def unless(cond: => Boolean) { - body - if (!cond) unless(cond) - } - } - var i = 10 - loop { - println("i = " + i) - i -= 1 - } unless (i == 0) - } - -`loop` 함수는 단순히 반복문의 내용을 받아서 `LoopUnlessCond` 클래스의 인스턴스(반복문 내용에 해당하는 객체를 캡슐화한)를 반환한다. 해당 내용이 아직 계산되지 않았음을 유념하자. `LoopUnlessCond` 클래스는 *중위 연산자*로 사용할 수 있는 `unless`라는 메소드를 포함하고 있다. 이런 접근을 통해 상당히 자연스럽게 표현된 새로운 반복문을 완성하게 된다: `loop { < stats > } unless ( < cond > )`. - -다음은 `TargetTest2`를 실행한 출력 결과다. - - i = 10 - i = 9 - i = 8 - i = 7 - i = 6 - i = 5 - i = 4 - i = 3 - i = 2 - i = 1 - -윤창석, 이한욱 옮김 diff --git a/_ko/tour/basics.md b/_ko/tour/basics.md index 602c49e3be..b0d0fda55c 100644 --- a/_ko/tour/basics.md +++ b/_ko/tour/basics.md @@ -1,9 +1,6 @@ --- layout: tour title: 기초 - -discourse: false - partof: scala-tour num: 2 @@ -17,53 +14,49 @@ previous-page: tour-of-scala ## 브라우저에서 스칼라 사용하기 -ScalaFiddle를 사용하면 브라우저에서 스칼라를 실행해 볼 수 있다. +Scastie를 사용하면 브라우저에서 스칼라를 실행해 볼 수 있다. -1. [https://scalafiddle.io](https://scalafiddle.io) 로 간다. +1. [Scastie](https://scastie.scala-lang.org/) 로 간다. 2. 왼쪽 창에 `println("Hello, world!")` 를 붙여 넣는다. 3. 실행 버튼을 누르면 오른쪽 창에서 출력을 확인할 수 있다. 이는 설정 없이 스칼라 코드들을 손쉽게 실험할 수 있는 방법이다. -이 페이지의 많은 예제 코드가 ScalaFiddle와 통합되어 있어 간단히 실행 버튼만 눌러 직접 실험해 볼 수 있다. - ## 표현식 - + 표현식은 연산 가능한 명령문이다. -``` +```scala mdoc 1 + 1 ``` `println` 표현식을 사용해 결과를 출력할 수 있다. -{% scalafiddle %} -```tut +```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! println("Hello," + " world!") // Hello, world! ``` -{% endscalafiddle %} ### 값 `val` 키워드로 표현식의 결과에 이름을 붙인다. -```tut +```scala mdoc val x = 1 + 1 println(x) // 2 ``` `x` 같이 이름이 붙여진 결과를 값이라고 부른다. 참조된 값은 재연산하지 않으며 값을 재할당할 수 없다. -```tut:fail +```scala mdoc:fail x = 3 // This does not compile. ``` 값의 타입을 추론할 수 있지만 명시적으로 타입을 지정할 수도 있다. -```tut +```scala mdoc:nest val x: Int = 1 + 1 ``` @@ -73,7 +66,7 @@ val x: Int = 1 + 1 변수는 재할당이 가능한 것 이외에는 값과 같다. `var` 키워드로 변수를 정의한다. -```tut +```scala mdoc:nest var x = 1 + 1 x = 3 // This compiles because "x" is declared with the "var" keyword. println(x * x) // 9 @@ -81,7 +74,7 @@ println(x * x) // 9 값처럼 명시적으로 타입을 지정할 수도 있다. -```tut +```scala mdoc:nest var x: Int = 1 + 1 ``` @@ -92,7 +85,7 @@ var x: Int = 1 + 1 블록 안 마지막 표현식의 결과는 블록 전체의 결과이기도 하다. -```tut +```scala mdoc println({ val x = 1 + 1 x + 1 @@ -105,7 +98,7 @@ println({ 주어진 정수에 1을 더하는 익명 함수(이름이 없는 함수)를 정의할 수 있다. -```tut +```scala mdoc (x: Int) => x + 1 ``` @@ -113,25 +106,21 @@ println({ 함수에 이름을 지정할 수 있다. -{% scalafiddle %} -```tut +```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -{% endscalafiddle %} 함수는 여러 매개변수를 가질 수 있다. -{% scalafiddle %} -```tut +```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} 또는 매개변수를 가지지 않을 수도 있다. -```tut +```scala mdoc val getTheAnswer = () => 42 println(getTheAnswer()) // 42 ``` @@ -142,27 +131,23 @@ println(getTheAnswer()) // 42 `def` 키워드로 메소드를 정의하고 이름, 매개변수 목록, 반환 타입 그리고 본문이 뒤따른다. -{% scalafiddle %} -```tut +```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} 매개변수 목록과 `: Int` 뒤에 반환 타입이 어떻게 선언되는지 주목하자. 메소드는 여러 매개변수 목록을 가질 수 있다. -{% scalafiddle %} -```tut +```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -{% endscalafiddle %} 또는 매개변수 목록을 가지지 않을 수도 있다. -```tut +```scala mdoc def name: String = System.getProperty("user.name") println("Hello, " + name + "!") ``` @@ -171,11 +156,12 @@ println("Hello, " + name + "!") 메소드는 여러 줄의 표현식을 가질 수 있다. -```tut +```scala mdoc def getSquareString(input: Double): String = { val square = input * input square.toString } +println(getSquareString(2.5)) // 6.25 ``` 본문의 마지막 표현식은 메소드의 반환 값이다. (스칼라는 `return` 키워드가 있지만 거의 사용하지 않고 생략한다.) @@ -184,7 +170,7 @@ def getSquareString(input: Double): String = { `class` 키워드로 클래스를 정의하고 이름과 생성자 매개변수가 뒤따른다. -```tut +```scala mdoc class Greeter(prefix: String, suffix: String) { def greet(name: String): Unit = println(prefix + name + suffix) @@ -195,7 +181,7 @@ class Greeter(prefix: String, suffix: String) { `new` 키워드로 클래스의 인스턴스를 만든다. -```tut +```scala mdoc val greeter = new Greeter("Hello, ", "!") greeter.greet("Scala developer") // Hello, Scala developer! ``` @@ -206,13 +192,13 @@ greeter.greet("Scala developer") // Hello, Scala developer! 스칼라는 케이스 클래스라고 불리는 특별한 타입의 클래스를 가지고 있다. 기본적으로, 케이스 클래스는 변하지 않으며 값으로 비교한다. `case class` 키워드로 케이스 클래스를 정의한다. -```tut +```scala mdoc case class Point(x: Int, y: Int) ``` `new` 키워드 없이 케이스 클래스를 인스턴스화 할 수 있다. -```tut +```scala mdoc val point = Point(1, 2) val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) @@ -220,17 +206,17 @@ val yetAnotherPoint = Point(2, 2) 그리고 값으로 비교한다. -```tut +```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) and Point(1,2) are the same. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) and Point(2,2) are different. ``` @@ -242,7 +228,7 @@ if (point == yetAnotherPoint) { `object` 키워드로 객체를 정의한다. -```tut +```scala mdoc object IdFactory { private var counter = 0 def create(): Int = { @@ -254,7 +240,7 @@ object IdFactory { 객체 이름을 참조하여 객체에 접근할 수 있다. -```tut +```scala mdoc val newId: Int = IdFactory.create() println(newId) // 1 val newerId: Int = IdFactory.create() @@ -269,7 +255,7 @@ println(newerId) // 2 `trait` 키워드로 트레이트를 정의한다. -```tut +```scala mdoc:nest trait Greeter { def greet(name: String): Unit } @@ -277,8 +263,7 @@ trait Greeter { 또한 트레이트는 기본 구현도 가질 수 있다. -{% scalafiddle %} -```tut +```scala mdoc:reset trait Greeter { def greet(name: String): Unit = println("Hello, " + name + "!") @@ -287,7 +272,7 @@ trait Greeter { `extends` 키워드로 트레이트를 상속할 수 있고 `override` 키워드로 구현을 오버라이드할 수 있다. -```tut +```scala mdoc class DefaultGreeter extends Greeter class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { @@ -302,7 +287,6 @@ greeter.greet("Scala developer") // Hello, Scala developer! val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` -{% endscalafiddle %} `DefaultGreeter` 는 트레이트 하나만 상속하고 있지만 다중 상속도 가능하다. @@ -310,11 +294,11 @@ customGreeter.greet("Scala developer") // How are you, Scala developer? ## 메인 메소드 -메인 메소드는 프로그램의 종료 지점이다. JVM(Java Virtual Machine)에선 `main` 이라는 메인 메소드가 필요하며 인자(argument) 하나와 문자열 배열을 가진다. +메인 메소드는 프로그램의 진입 지점이다. JVM(Java Virtual Machine)에선 `main` 이라는 메인 메소드가 필요하며 문자열 배열 하나를 인자(argument)로 가진다. `object` 키워드를 사용하여 메인 메소드를 정의할 수 있다. -```tut +```scala mdoc object Main { def main(args: Array[String]): Unit = println("Hello, Scala developer!") diff --git a/_ko/tour/by-name-parameters.md b/_ko/tour/by-name-parameters.md index b4202656cd..e46ebdd725 100644 --- a/_ko/tour/by-name-parameters.md +++ b/_ko/tour/by-name-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: By-name Parameters - -discourse: false - partof: scala-tour language: ko --- diff --git a/_ko/tour/case-classes.md b/_ko/tour/case-classes.md index 6d32c6bac2..78cf439c26 100644 --- a/_ko/tour/case-classes.md +++ b/_ko/tour/case-classes.md @@ -1,12 +1,9 @@ --- layout: tour title: 케이스 클래스 - -discourse: false - partof: scala-tour -num: 10 +num: 11 language: ko next-page: pattern-matching @@ -122,4 +119,4 @@ previous-page: multiple-parameter-lists * 값을 통한 비교는 여러분이 인스턴스들을 원시 값들인 것처럼 비교할수 있게 만들어 준다 - 클래스의 인스턴스들이 값 또는 참조를 통해 비교되는지와 같은 불확실성을 제거 * 패턴매칭은 로직의 분기를 심플하게 만들어주며, 결국 적은 버그와 가독성 높은 코드로 이어진다. -고광현 옮김 \ No newline at end of file +고광현 옮김 diff --git a/_ko/tour/classes.md b/_ko/tour/classes.md index 0e3a54f558..a3635881a0 100644 --- a/_ko/tour/classes.md +++ b/_ko/tour/classes.md @@ -1,9 +1,6 @@ --- layout: tour title: 클래스 - -discourse: false - partof: scala-tour num: 4 @@ -11,41 +8,99 @@ language: ko next-page: traits previous-page: unified-types +topics: classes +prerequisite-knowledge: no-return-keyword, type-declaration-syntax, string-interpolation, procedures --- -스칼라의 클래스는 런타임에 많은 객체로 인스턴스화 될 수 있는 정적 템플릿이다. -아래는 'Point' 클래스의 정의이다. +스칼라의 클래스는 객체를 만들기 위한 설계도입니다. 클래스에는 _멤버_ 라고 통칭할 수 있는 메서드, 값, 변수, 타입, 객체, 트레잇, 클래스를 포함할 수 있습니다. 타입, 객체, 트레잇은 투어에서 나중에 다루겠습니다. + +# 클래스 정의 +가장 단순한 클래스 정의는 예약어 `class`와 식별자만 있는 것입니다. 클래스명은 대문자로 시작하는 것이 관례입니다. +```scala mdoc +class User + +val user1 = new User +``` +예약어 `new`는 클래스의 인스턴스를 만들기위해 사용합니다. `User` 클래스는 생성자를 정의하지 않았기 때문에 인자가 없는 기본 생성자를 갖습니다. 생성자와 클래스 몸체를 정의하고자 한다면, 다음의 클래스 정의 예제를 참고하십시오: + +```scala mdoc +class Point(var x: Int, var y: Int) { + + def move(dx: Int, dy: Int): Unit = { + x = x + dx + y = y + dy + } + + override def toString: String = + s"($x, $y)" +} + +val point1 = new Point(2, 3) +point1.x // 2 +println(point1) // prints (2, 3) +``` + +이 `Point` 클래스에는 네 개의 멤버가 있습니다: 변수 `x`, `y`와 메서드 `move`, `toString`. 많은 다른 언어와 달리 기본 생성자는 클래스 서명부(signature)에 있습니다 `(var x : Int, var y : Int)`. `move` 메소드는 두 개의 정수 인자를 취하여 정보를 전달하지 않는 Unit 타입의 값 `()`을 반환합니다. 이것은 자바 같은 언어의 `void`와 유사합니다. 반면에 `toString`은 인자를 취하지 않고 `String` 값을 반환합니다. `toString`은 [`AnyRef`](unified-types.html)의 `toString`을 대체하므로 `override` 예약어로 지정됩니다. + +## 생성자 + +생성자는 다음과 같은 기본 값을 제공하여 선택적 매개변수를 가질 수 있습니다: + +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) + +val origin = new Point // x and y are both set to 0 +val point1 = new Point(1) +println(point1.x) // prints 1 + +``` - class Point(xc: Int, yc: Int) { - var x: Int = xc - var y: Int = yc - def move(dx: Int, dy: Int) { - x = x + dx - y = y + dy - } - override def toString(): String = "(" + x + ", " + y + ")"; - } +이 버전의 `Point` 클래스에서 `x`와 `y` 인자는 기본 값 `0`을 가지므로 인자를 꼭 전달하지 않아도 됩니다. 생성자는 인자를 왼쪽부터 읽으므로 `y` 값만 전달하고 싶다면 매개변수의 이름을 지정해야 합니다. +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) +val point2 = new Point(y=2) +println(point2.y) // prints 2 +``` -이 클래스는 변수 'x' 와 'y' 그리고 두 메서드 `move` 와 `toString` 을 정의한다. `move`는 두 개의 정수를 인자로 받지만 값을 반환하지는 않는다 (암시적 반환 타입인 `Unit` 은 Java와 같은 언어의 `void` 에 해당한다). 반면 `toString`은 아무 파라미터도 입력받지 않지만 `String` 값을 반환한다. `toString`은 기정의된 `toString` 메서드를 오버라이드 하기 때문에 `override` 플래그로 표시되어야 한다. +이것은 명료성 향상을 위한 좋은 습관이기도 합니다. -스칼라의 클래스들은 생성자의 인자로 파라미터화 된다. 위의 코드는 두 개의 생성자 인자 `xc`와 `yc`를 정의한다. 이 두 인자는 클래스 전체에서 접근 가능하다. 예제에서 이들은 변수 `x`와 `y`를 초기화하는 데에 사용된다. +# Private 멤버와 Getter/Setter 문법 +멤버는 기본적으로 public으로 지정됩니다. `private` 접근 지시자를 사용함으로써 클래스 외부로부터 멤버를 숨길 수 있습니다. +```scala mdoc:nest +class Point { + private var _x = 0 + private var _y = 0 + private val bound = 100 -클래스들은 아래의 예제가 보여주는 것처럼 새로운 기본형으로 초기화된다. + def x = _x + def x_= (newValue: Int): Unit = { + if (newValue < bound) _x = newValue else printWarning + } - object Classes { - def main(args: Array[String]) { - val pt = new Point(1, 2) - println(pt) - pt.move(10, 10) - println(pt) - } - } + def y = _y + def y_= (newValue: Int): Unit = { + if (newValue < bound) _y = newValue else printWarning + } -이 프로그램은 `main` 메서드를 가지고 있는 최상위 싱글톤의 형태로 실행가능한 어플리케이션 클래스를 정의한다. `main` 메서드는 새로운 `Point`를 생성하고 변수 `pt`에 저장한다. `val` 키워드로 정의된 값은 변경을 허용하지 않는다는 점에서 `var` 키워드로 정의된 값(`Point` 클래스 참)과는 다르다는 점에 주의하자. 즉, 이 값은 상수이다. + private def printWarning = println("WARNING: Out of bounds") +} -이 프로그램의 결과는 아래와 같다: +val point1 = new Point +point1.x = 99 +point1.y = 101 // 경고가 출력됩니다 +``` +이 버전의 `Point` 클래스에서는 데이터가 private 변수 `_x`와 `_y`에 저장됩니다. 이 private 데이터에 접근하기 위한 메서드 `def x`와 `def y`가 있고, `_x`와 `_y` 값을 검증하고 설정하기위한 `def x_=`와 `def y_=`가 있습니다. setter 메서드를 위한 특별한 문법에 주목하십시오: getter 메서드 식별자에 `_=`를 덧붙이고 매개변수가 뒤따르는 형식입니다. - (1, 2) - (11, 12) +기본 생성자에서 `val`와 `var`로 지정된 매개변수는 public 입니다. `val`은 불변을 의미하기 때문에 다음의 예처럼 값을 변경할 수 없습니다. +```scala mdoc:fail +class Point(val x: Int, val y: Int) +val point = new Point(1, 2) +point.x = 3 // <-- 컴파일되지 않습니다 +``` -윤창석, 이한욱 옮김 +`val` 또는 `var`로 지정되지 않은 매개변수는 private 값이므로 클래스 내에서만 참조가능합니다. +```scala mdoc:fail +class Point(x: Int, y: Int) +val point = new Point(1, 2) +point.x // <-- 컴파일되지 않습니다 +``` diff --git a/_ko/tour/compound-types.md b/_ko/tour/compound-types.md index d69fa52ac7..2e3b43adc2 100644 --- a/_ko/tour/compound-types.md +++ b/_ko/tour/compound-types.md @@ -1,16 +1,13 @@ --- layout: tour title: 합성 타입 - -discourse: false - partof: scala-tour num: 23 language: ko next-page: self-types -previous-page: abstract-types +previous-page: abstract-type-members --- 때론 객체의 타입을 여러 다른 타입의 서브타입으로 표현해야 할 때가 있다. 스칼라에선 *합성 타입(Compound Types)*으로 표현될 수 있는데, 이는 객체 타입들의 교차점을 의미한다. @@ -44,6 +41,6 @@ previous-page: abstract-types 합성 타입은 여러 객체 타입으로 구성될 수 있고, 단일 리파인먼트를 가짐으로써 객체 멤버의 시그니처의 범위를 좁힐 수도 있다. 일반적인 형태는 `A with B with C ... { 리파인먼트 }`이다. -리파인먼트 사용 예제는 [추상 타입](abstract-types.html) 에 있다. +리파인먼트 사용 예제는 [추상 타입](abstract-type-members.html) 에 있다. 윤창석, 이한욱 옮김, 고광현 수정 diff --git a/_ko/tour/default-parameter-values.md b/_ko/tour/default-parameter-values.md index 983bc60d8f..0cd3bffd65 100644 --- a/_ko/tour/default-parameter-values.md +++ b/_ko/tour/default-parameter-values.md @@ -1,9 +1,6 @@ --- layout: tour title: 기본 파라미터 값 - -discourse: false - partof: scala-tour num: 32 @@ -61,6 +58,6 @@ previous-page: annotations // 이름을 지정한 인수를 통해 로드 팩터만을 오버라이드 val m4 = new HashMap[String,Int](loadFactor = 0.8) -*모든* 기본 값에 [이름을 지정한 파라미터]({{ site.baseurl }}/tutorials/tour/named-arguments.html)를 활용할 수 있음을 기억하자. +*모든* 기본 값에 [이름을 지정한 파라미터]({{ site.baseurl }}/ko/tour/named-arguments.html)를 활용할 수 있음을 기억하자. 윤창석, 이한욱 옮김 diff --git a/_ko/tour/extractor-objects.md b/_ko/tour/extractor-objects.md index fee7ae08c9..804769509c 100644 --- a/_ko/tour/extractor-objects.md +++ b/_ko/tour/extractor-objects.md @@ -1,9 +1,6 @@ --- layout: tour title: 추출자 오브젝트 - -discourse: false - partof: scala-tour num: 15 diff --git a/_ko/tour/for-comprehensions.md b/_ko/tour/for-comprehensions.md index d414c1c8f6..668b71c336 100644 --- a/_ko/tour/for-comprehensions.md +++ b/_ko/tour/for-comprehensions.md @@ -1,9 +1,6 @@ --- layout: tour title: For Comprehensions - -discourse: false - partof: scala-tour language: ko --- diff --git a/_ko/tour/generic-classes.md b/_ko/tour/generic-classes.md index fa4eeffb8e..4a7d70bf56 100644 --- a/_ko/tour/generic-classes.md +++ b/_ko/tour/generic-classes.md @@ -1,9 +1,6 @@ --- layout: tour title: 제네릭 클래스 - -discourse: false - partof: scala-tour num: 17 @@ -15,12 +12,15 @@ previous-page: extractor-objects 자바 5(다른 이름은 JDK 1.5와 같이, 스칼라는 타입으로 파라미터화된 클래스의 빌트인 지원을 제공한다. 이런 제네릭 클래스는 특히 컬렉션 클래스의 개발에 유용하다. 이에 관한 예제를 살펴보자. - class Stack[T] { - var elems: List[T] = Nil - def push(x: T) { elems = x :: elems } - def top: T = elems.head - def pop() { elems = elems.tail } - } +```scala mdoc +class Stack[T] { + var elems: List[T] = Nil + def push(x: T): Unit = + elems = x :: elems + def top: T = elems.head + def pop(): Unit = { elems = elems.tail } +} +``` 클래스 `Stack`은 임의의 타입 `T`를 항목의 타입으로 하는 명령형(변경 가능한) 스택이다. 타입 파라미터는 올바른 항목(타입 `T` 인)만을 스택에 푸시하도록 강제한다. 마찬가지로 타입 파라미터를 사용해서 메소드 `top`이 항상 지정된 타입만을 반환하도록 할 수 있다. diff --git a/_ko/tour/higher-order-functions.md b/_ko/tour/higher-order-functions.md index 40adfba248..9861419e18 100644 --- a/_ko/tour/higher-order-functions.md +++ b/_ko/tour/higher-order-functions.md @@ -1,12 +1,9 @@ --- layout: tour title: 고차 함수 - -discourse: false - partof: scala-tour -num: 7 +num: 8 language: ko next-page: nested-functions diff --git a/_ko/tour/implicit-conversions.md b/_ko/tour/implicit-conversions.md index eb42d4a0fb..d5af6dac66 100644 --- a/_ko/tour/implicit-conversions.md +++ b/_ko/tour/implicit-conversions.md @@ -1,9 +1,6 @@ --- layout: tour title: 암시적 변환 - -discourse: false - partof: scala-tour num: 26 @@ -13,50 +10,51 @@ next-page: polymorphic-methods previous-page: implicit-parameters --- -타입 `S`로부터 타입 `T`로의 암시적 변환는 함수 타입 `S => T`의 암시적 값이나 해당 타입으로 변환 가능한 암시적 메소드로 정의된다. +타입 `S`에서 타입 `T`로의 암시적 변환은 타입이 함수 `S => T`인 암시적 값이나 해당 타입으로 변환 가능한 암시적 메소드로 정의된다. 암시적 변환은 두 가지 상황에 적용된다. * 표현식 `e`의 타입이 `S`이고, `S`는 표현식의 기대 타입 `T`를 따르지 않을 때. -* `e`의 타입이 `T`인 `e.m`를 선택한 상황에서, 선택자 `m`이 `T`의 멤버가 아닐 때. +* 타입이 `S`인 `e`의 `e.m`을 선택한 상황에서, 선택자 `m`이 `S`의 멤버가 아닐 때. -첫 번째 경우에서 변환 `c`가 `e`에 적용되며, 결과 타입이 `T`를 따르는지 탐색한다. -두 번째 경우에선 변환 `c`가 `e`에 적용되며, 결과가 `m`이라는 이름의 멤버를 포함하고 있는지 탐색한다. +첫 번째 경우, `e`에 적용되며 결과 타입이 `T`인 변환 `c`를 찾는다. +두 번째 경우, `e`에 적용되며 결과에 `m`이라는 이름의 멤버를 포함하는 변환 `c`를 찾는다. -타입이 `List[Int]`인 두 리스트 xs와 ys의 아래 연산은 허용된다: +암시적 메서드인 `List[A] => Ordered[List[A]]`와 `Int => Ordered[Int]`가 범위 내에 있을 경우, 아래와 같이 타입이 `List[Int]`인 두 리스트의 연산은 허용된다: - xs <= ys + List(1, 2, 3) <= List(4, 5) -아래에 정의된 암시적 메소드 `list2ordered`와 `int2ordered`가 범위 안에 있다고 가정한다. +`scala.Predef.intWrapper`는 암시적 메서드 암시적 메서드 `Int => Ordered[Int]`를 자동으로 제공한다. 다음은 암시적 메서드 `Int => Ordered[Int]`의 예시이다. - implicit def list2ordered[A](x: List[A]) - (implicit elem2ordered: a => Ordered[A]): Ordered[List[A]] = - new Ordered[List[A]] { /* .. */ } + import scala.language.implicitConversions - implicit def int2ordered(x: Int): Ordered[Int] = - new Ordered[Int] { /* .. */ } + implicit def list2ordered[A](x: List[A]) + (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] = + new Ordered[List[A]] { + // 더 유용한 구현으로 대체하시오 + def compare(that: List[A]): Int = 1 + } -암시적으로 임포트되는 오브젝트 `scala.Predef`는 미리 정의된 여러 타입(예: `Pair`)과 메소드(예: `assert`)뿐만 아니라 여러 뷰도 함께 선언한다. +암시적으로 임포트되는 객체 `scala.Predef`는 자주 사용되는 타입의 별칭(예: `scala.collection.immutable.Map`의 별칭 `Map`)과 메소드(예: `assert`), 그리고 여러 암시적 변환을 선언한다. -예를들면, `java.lang.Integer`를 기대하는 자바 메서드를 호출할때, `scala.Int`를 대신 넘겨도 무방하다. 그 이유는 Predef가 아래 암시적 변환들을 포함하기 때문이다. +예를 들면, `java.lang.Integer`를 기대하는 자바 메서드를 호출할 때, `scala.Int`를 대신 넘겨도 된다. 그 이유는 Predef가 아래 암시적 변환을 포함하기 때문이다. -```tut +```scala mdoc import scala.language.implicitConversions -implicit def int2Integer(x: Int) = - java.lang.Integer.valueOf(x) +implicit def int2Integer(x: Int): Integer = + Integer.valueOf(x) ``` -암시적 변환이 무분별하게 사용될 경우 잠재적인 위험을 가질 수 있기 때문에, 컴파일러는 암시적 변환의 선언을 컴파일할때 경고한다. +암시적 변환이 무분별하게 사용될 경우 잠재적인 위험을 가질 수 있기 때문에, 컴파일러는 암시적 변환의 선언을 컴파일할 시 이를 경고한다. -To turn off the warnings take either of these actions: -경고를 끄기 위해서는 아래 중 하나를 선택해야 한다. +경고를 끄기 위해서는 아래 중 하나를 선택해야 한다: -* `scala.language.implicitConversions` 를 암시적 변환의 선언이 있는 범위로 import +* 암시적 변환의 정의가 있는 범위 내에서 `scala.language.implicitConversions` 임포트 * `-language:implicitConversions` 옵션으로 컴파일러 실행 -변환이 컴팡일러에 의해 적용될때 경고가 발생하지 않는다. +컴파일러가 변환을 적용할 때에는 경고가 발생하지 않는다. 윤창석, 이한욱 옮김, 고광현 업데이트 diff --git a/_ko/tour/implicit-parameters.md b/_ko/tour/implicit-parameters.md index 4c8a7bf4cf..33acd69f65 100644 --- a/_ko/tour/implicit-parameters.md +++ b/_ko/tour/implicit-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: 암시적 파라미터 - -discourse: false - partof: scala-tour num: 25 diff --git a/_ko/tour/inner-classes.md b/_ko/tour/inner-classes.md index ac0f2bba2c..309a4651a1 100644 --- a/_ko/tour/inner-classes.md +++ b/_ko/tour/inner-classes.md @@ -1,62 +1,65 @@ --- layout: tour title: 내부 클래스 - -discourse: false - partof: scala-tour num: 21 language: ko -next-page: abstract-types +next-page: abstract-type-members previous-page: lower-type-bounds --- 스칼라의 클래스는 다른 클래스를 멤버로 가질 수 있다. 자바와 같은 언어의 내부 클래스는 자신을 감싸고 있는 클래스의 멤버인 반면에, 스칼라에선 내부 클래스가 외부 객체의 경계 안에 있다. 이런 차이점을 분명히 하기 위해 그래프 데이터타입의 구현을 간단히 그려보자. - - class Graph { - class Node { - var connectedNodes: List[Node] = Nil - def connectTo(node: Node) { - if (connectedNodes.find(node.equals).isEmpty) { - connectedNodes = node :: connectedNodes - } - } - } - var nodes: List[Node] = Nil - def newNode: Node = { - val res = new Node - nodes = res :: nodes - res + +```scala mdoc +class Graph { + class Node { + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes } } - + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` + 이 프로그램에선 노드의 리스트로 그래프를 나타냈다. 노드는 내부 클래스 `Node`의 객체다. 각 노드는 리스트 `connectedNodes`에 저장되는 이웃의 목록을 갖고 있다. 이제 몇몇 노드를 선택하고 이에 연결된 노드를 추가하면서 점진적으로 그래프를 구축할 수 있다. - - object GraphTest extends App { - val g = new Graph - val n1 = g.newNode - val n2 = g.newNode - val n3 = g.newNode - n1.connectTo(n2) - n3.connectTo(n1) - } - + +```scala mdoc:nest +def graphTest: Unit = { + val g = new Graph + val n1 = g.newNode + val n2 = g.newNode + val n3 = g.newNode + n1.connectTo(n2) + n3.connectTo(n1) +} +``` + 정의된 여러 엔티티의 타입이 무엇인지 명시적으로 알려주는 타입 정보를 사용해 위의 예제를 확장해보자. - - object GraphTest extends App { - val g: Graph = new Graph - val n1: g.Node = g.newNode - val n2: g.Node = g.newNode - val n3: g.Node = g.newNode - n1.connectTo(n2) - n3.connectTo(n1) - } - + +```scala mdoc:nest +def graphTest: Unit = { + val g: Graph = new Graph + val n1: g.Node = g.newNode + val n2: g.Node = g.newNode + val n3: g.Node = g.newNode + n1.connectTo(n2) + n3.connectTo(n1) +} +``` + 이 코드는 외부 인스턴스(이 예제의 객체 `g`)를 접두어로 지정해 노드 타입을 분명히 나타내고 있다. 두 그래프가 있는 상황에서, 스칼라의 타입 시스템은 한 그래프에 정의된 노드를 다른 그래프에서도 정의해 공유하는 상황을 허용하지 않는다. 이는 다른 그래프의 노드는 다른 타입을 갖기 때문이다. 다음은 잘못된 프로그램이다. - + object IllegalGraphTest extends App { val g: Graph = new Graph val n1: g.Node = g.newNode @@ -66,14 +69,14 @@ previous-page: lower-type-bounds val n3: h.Node = h.newNode n1.connectTo(n3) // illegal! } - + 자바에선 이 예제 프로그램의 마지막 줄이 올바른 표현임을 상기하자. 자바는 두 그래프의 노드에 `Graph.Node`라는 동일한 타입을 할당한다. 즉, `Node`에는 클래스 `Graph`가 접두어로 붙는다. 스칼라에서도 이런 타입을 표현할 수 있으며, 이를 `Graph#Node`로 나타낸다. 서로 다른 그래프 간에 노드를 연결할 수 있길 원한다면 초기 그래프 구현의 정의를 다음과 같이 변경해야 한다. - + class Graph { class Node { var connectedNodes: List[Graph#Node] = Nil - def connectTo(node: Graph#Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -85,7 +88,7 @@ previous-page: lower-type-bounds res } } - + > 이 프로그램에선 하나의 노드를 서로 다른 두 그래프에 추가할 수 없음에 주의하자. 이 제약도 함께 제거하기 위해선 변수 nodes의 타입을 `Graph#Node`로 바꿔야 한다. -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/lower-type-bounds.md b/_ko/tour/lower-type-bounds.md index c36d5a43c3..718983a0a4 100644 --- a/_ko/tour/lower-type-bounds.md +++ b/_ko/tour/lower-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: 하위 타입 경계 - -discourse: false - partof: scala-tour num: 20 @@ -50,4 +47,4 @@ _주의:_ 새로운 `prepend` 메소드에선 타입의 제약이 조금 줄어 val anyList: ListNode[Any] = strList.prepend(12345) } -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/mixin-class-composition.md b/_ko/tour/mixin-class-composition.md index 262bdf5ab0..94f21d2244 100644 --- a/_ko/tour/mixin-class-composition.md +++ b/_ko/tour/mixin-class-composition.md @@ -1,16 +1,13 @@ --- layout: tour title: 믹스인 클래스 컴포지션 - -discourse: false - partof: scala-tour -num: 6 +num: 7 language: ko next-page: higher-order-functions -previous-page: traits +previous-page: tuples --- _단일 상속_ 만을 지원하는 여러 언어와는 달리, 스칼라는 더욱 일반화된 시각에서 클래스를 재사용한다. 스칼라는 새로운 클래스를 정의할 때 _클래스의 새로운 멤버 정의_ (즉, 슈퍼클래스와 비교할 때 변경된 부분)를 재사용할 수 있다. 이를 _믹스인 클래스 컴포지션_ 이라고 부른다. 이터레이터를 추상화한 다음 예제를 살펴보자. @@ -24,7 +21,7 @@ _단일 상속_ 만을 지원하는 여러 언어와는 달리, 스칼라는 더 이어서, 이터레이터가 반환하는 모든 항목에 주어진 함수를 적용해주는 `foreach` 메소드로 `AbsIterator`를 확장한 믹스인 클래스를 살펴보자. 믹스인으로 사용할 수 있는 클래스를 정의하기 위해선 `trait`이란 키워드를 사용한다. trait RichIterator extends AbsIterator { - def foreach(f: T => Unit) { while (hasNext) f(next()) } + def foreach(f: T => Unit): Unit = { while (hasNext) f(next()) } } 다음은 주어진 문자열의 캐릭터를 차례로 반환해주는 콘크리트 이터레이터 클래스다. @@ -39,7 +36,7 @@ _단일 상속_ 만을 지원하는 여러 언어와는 달리, 스칼라는 더 `StringIterator`와 `RichIterator`를 하나의 클래스로 합치고 싶다면 어떻게 할까. 두 클래스 모두는 코드가 포함된 멤버 구현을 담고 있기 때문에 단일 상속과 인터페이스 만으론 불가능한 일이다. 스칼라는 _믹스인 클래스 컴포지션_ 으로 이런 상황을 해결해준다. 프로그래머는 이를 사용해 클래스 정의에서 변경된 부분을 재사용할 수 있다. 이 기법은 주어진 문자열에 포함된 모든 캐릭터를 한 줄로 출력해주는 다음의 테스트 프로그램에서와 같이, `StringIterator`와 `RichIterator`를 통합할 수 있도록 해준다. object StringIteratorTest { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { class Iter extends StringIterator("Scala") with RichIterator val iter = new Iter iter foreach println diff --git a/_ko/tour/multiple-parameter-lists.md b/_ko/tour/multiple-parameter-lists.md index 03d6e171ec..c8cf38cfdc 100644 --- a/_ko/tour/multiple-parameter-lists.md +++ b/_ko/tour/multiple-parameter-lists.md @@ -1,12 +1,9 @@ --- layout: tour title: 커링 - -discourse: false - partof: scala-tour -num: 9 +num: 10 language: ko next-page: case-classes @@ -38,4 +35,4 @@ _주의: `modN` 메소드는 두 번의 `filter` 호출에서 부분적으로 List(2,4,6,8) List(3,6) -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/named-arguments.md b/_ko/tour/named-arguments.md index 7f13650e38..53fa5182a9 100644 --- a/_ko/tour/named-arguments.md +++ b/_ko/tour/named-arguments.md @@ -1,9 +1,6 @@ --- layout: tour title: 이름을 지정한 파라미터 - -discourse: false - partof: scala-tour num: 33 @@ -36,4 +33,4 @@ previous-page: default-parameter-values 여러분이 원하는 순서대로 파라미터를 위치시킬 수 있기 때문에 파라미터 목록 중에서 가장 중요한 파라미터부터 기본 값을 사용할 수 있다. -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/nested-functions.md b/_ko/tour/nested-functions.md index 9f55347977..a26a6a64a3 100644 --- a/_ko/tour/nested-functions.md +++ b/_ko/tour/nested-functions.md @@ -1,12 +1,9 @@ --- layout: tour title: 중첩 함수 - -discourse: false - partof: scala-tour -num: 8 +num: 9 language: ko next-page: multiple-parameter-lists @@ -32,4 +29,4 @@ _주의: 중첩 함수 `process`는 `filter`의 파라미터 값으로써 외부 List(1,2,3,4) -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/operators.md b/_ko/tour/operators.md index 4df29bb1b2..4306b08744 100644 --- a/_ko/tour/operators.md +++ b/_ko/tour/operators.md @@ -1,15 +1,12 @@ --- layout: tour title: 연산자 - -discourse: false - partof: scala-tour num: 29 language: ko -next-page: automatic-closures +next-page: annotations previous-page: type-inference --- diff --git a/_ko/tour/package-objects.md b/_ko/tour/package-objects.md new file mode 100644 index 0000000000..335f67d917 --- /dev/null +++ b/_ko/tour/package-objects.md @@ -0,0 +1,67 @@ +--- +layout: tour +title: 패키지 객체 +language: ko +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- + +# 패키지 객체 + +스칼라는 패키지 객체라는 패키지 전체에 걸쳐 공유되는 편리한 컨테이너를 제공한다. + +패키지 객체는 변수나 메서드 정의뿐 아니라 임의의 정의도 담을 수 있다. 예를 들어, 패키지 범위의 타입 별칭이나 암시적 변환을 담기 위해 패키지 객체가 종종 사용된다. 패키지 객체는 스칼라 클래스나 트레잇을 상속할 수도 있다. + +패키지 객체의 소스 코드는 `package.scala`라 명명된 소스 파일에 담는 것이 관례이다. + +각 패키지는 하나의 패키지 객체를 가질 수 있다. 패키지 객체에 정의된 것은 무엇이든 해당 패키지의 구성원으로 간주한다. + +아래 예제를 보자. 먼저 `gardening.fruits` 패키지에 `Fruit` 클래스와 세 개의 `Fruit` 객체가 있다고 가정하자: + +``` +// gardening/fruits/Fruit.scala 파일 내부 +package gardening.fruits + +case class Fruit(name: String, color: String) +object Apple extends Fruit("Apple", "green") +object Plum extends Fruit("Plum", "blue") +object Banana extends Fruit("Banana", "yellow") +``` + +이제 당신이 `planted` 변수와 `showFruit` 메서드를 바로 `gardening.fruits` 패키지에 넣고 싶다고 해보자. +이는 아래와 같이 구현된다: + +``` +// gardening/fruits/package.scala 파일 내부 +package gardening +package object fruits { + val planted = List(Apple, Plum, Banana) + def showFruit(fruit: Fruit): Unit = { + println(s"${fruit.name}s are ${fruit.color}") + } +} +``` + +아래 사용 예처럼, `PrintPlanted` 객체는 `gardening.fruits` 패키지에 와일드카드를 사용하여 임포트함으로써 `Fruit` 클래스와 함께 `planted`와 `showFruits`를 불러온다: + +``` +// PrintPlanted.scala 파일 내부 +import gardening.fruits._ +object PrintPlanted { + def main(args: Array[String]): Unit = { + for (fruit <- planted) { + showFruit(fruit) + } + } +} +``` + +패키지 객체는 구성 시 다른 객체처럼 상속을 이용할 수 있다. 다음 예시와 같이, 여러 트레잇을 혼합하여 패키지 객체를 만들 수도 있다: + +``` +package object fruits extends FruitAliases with FruitHelpers { + // 헬퍼와 변수가 이곳에 따라온다 +} +``` diff --git a/_ko/tour/packages-and-imports.md b/_ko/tour/packages-and-imports.md index 3a052dfd64..4a40cf7bf5 100644 --- a/_ko/tour/packages-and-imports.md +++ b/_ko/tour/packages-and-imports.md @@ -1,18 +1,98 @@ --- layout: tour -title: Packages and Imports -language: ko - -discourse: true - +title: 패키지와 임포트 partof: scala-tour num: 35 +language: ko + previous-page: named-arguments -next-page: type-inference +next-page: package-objects --- -# Packages and Imports +# 패키지와 임포트 + +스칼라는 패키지를 사용하여 프로그램을 모듈화할 수 있는 네임스페이스를 만든다. + +## 패키지 만들기 + +패키지는 스칼라 파일 맨 위에 하나 이상의 패키지 이름을 선언하여 만들어진다. + +``` +package users + +class User +``` + +패키지의 이름을 스칼라 파일을 담고 있는 디렉토리와 같게 하는 규칙이 있다. 하지만, 스칼라는 파일 레이아웃에 한정되지 않는다. `package users`를 위한 sbt 프로젝트의 디렉토리 구조의 한 예이다. + +``` +- ExampleProject + - build.sbt + - project + - src + - main + - scala + - users + User.scala + UserProfile.scala + UserPreferences.scala + - test +``` + +`users` 디렉토리가 `scala` 디렉토리 안에 위치하고 여러 스칼라 파일이 패키지 안에 위치하는지에 대해 주목해야 한다. 패키지 안 각 스칼라 파일은 같은 패키지 선언을 가질 수 있다. 패키지를 선언하는 다른 방법은 중괄호를 사용하는 것이다. + +``` +package users { + package administrators { + class NormalUser + } + package normalusers { + class NormalUser + } +} +``` + +보다시피 패키지 중첩을 허용하고 스코프와 캡슐화를 더 잘 제어한다. + +패키지 이름은 모두 소문자여야 하고 웹사이트를 가진 조직에서 개발된 코드라면 `<상위 도메인>.<도메인 이름>.<프로젝트 이름>` 과 같은 형식을 따라야 한다. 예를 들어, 구글에게 `SelfDrigingCar`라는 프로젝트가 있다면 패키지 이름은 아래와 같을 것이다. + +``` +package com.google.selfdrivingcar.camera + +class Lens +``` + +디렉토리 구조는 `SelfDrivingCar/src/main/scala/com/google/selfdrivingcar/camera/Lens.scala`와 같을 것이다. + +## 임포트 + +`import` 절은 다른 패키지의 멤버(클래스, 트레이트, 함수 등)에 접근하기 위해서고 같은 패키지의 멤버에 접근할 때는 필요하지 않다. 한마디로 임포트 절은 선택적이다. + +``` +import users._ // users 패키지 전부를 임포트한다 +import users.User // User 클래스를 임포트한다 +import users.{User, UserPreferences} // 선택된 멤버만 임포트한다 +import users.{UserPreferences => UPrefs} // 편의를 위해 이름을 바꾸고 임포트한다 +``` + +스칼라가 자바와 한가지 다른 점은 어디서든 임포트를 할 수 있다는 것이다. + +```scala mdoc +def sqrtplus1(x: Int) = { + import scala.math.sqrt + sqrt(x) + 1.0 +} +``` + +네이밍이 중복되거나 프로젝트의 루트에서 무언가 임포트해야 할 때, 패키지 이름 앞에 `_root_`를 붙이면 된다. + +``` +package accounts + +import _root_.users._ +``` + +`scala` 및 `java.lang` 패키지와 `object Predef` 는 기본적으로 임포트된다. -(this section of the tour has not been translated yet. pull request -with translation welcome!) +공병국 옮김 diff --git a/_ko/tour/pattern-matching.md b/_ko/tour/pattern-matching.md index 9be1ac47e4..3ee2efd1d0 100644 --- a/_ko/tour/pattern-matching.md +++ b/_ko/tour/pattern-matching.md @@ -1,12 +1,9 @@ --- layout: tour title: 패턴 매칭 - -discourse: false - partof: scala-tour -num: 11 +num: 12 language: ko next-page: singleton-objects @@ -43,4 +40,4 @@ previous-page: case-classes 스칼라의 패턴 매칭 명령문은 [케이스 클래스](case-classes.html)를 통해 표현되는 대수 타입과 매칭할 때 가장 유용하다. 또한 스칼라는 [추출자 오브젝트](extractor-objects.html)의 `unapply` 메소드를 사용해, 독립적인 케이스 클래스로 패턴을 정의할 수 있도록 해준다. -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/polymorphic-methods.md b/_ko/tour/polymorphic-methods.md index 817c6a5ae0..53652a1fe1 100644 --- a/_ko/tour/polymorphic-methods.md +++ b/_ko/tour/polymorphic-methods.md @@ -1,9 +1,6 @@ --- layout: tour title: 다형성 메소드 - -discourse: false - partof: scala-tour num: 27 diff --git a/_ko/tour/regular-expression-patterns.md b/_ko/tour/regular-expression-patterns.md index 4d1a0c00ee..4f71d15e49 100644 --- a/_ko/tour/regular-expression-patterns.md +++ b/_ko/tour/regular-expression-patterns.md @@ -1,9 +1,6 @@ --- layout: tour title: 정규 표현식 패턴 - -discourse: false - partof: scala-tour num: 14 @@ -43,4 +40,4 @@ previous-page: singleton-objects 정규 표현식 패턴이 XML 처리에 예상에 비해 그다지 유용하지 않다는 것이 우리의 의견이다. 실제 상황에서 XML를 처리해야하는 애플리케이션이라면 XPath가 더 나은 선택으로 보인다. 우리의 변환이나 정규 표현식 패턴에 드물지만 제거하기 어려운 난해한 버그가 있다는 점을 발견했을 때, 우리는 이 기회에 언어를 좀 더 단순하게 만들기로 결정했다. -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/self-types.md b/_ko/tour/self-types.md index 1cd164337f..931a5e8312 100644 --- a/_ko/tour/self-types.md +++ b/_ko/tour/self-types.md @@ -1,9 +1,6 @@ --- layout: tour title: 명시적으로 타입이 지정된 자기 참조 - -discourse: false - partof: scala-tour num: 24 @@ -28,7 +25,7 @@ previous-page: compound-types def addNode: Node } -그래프는 노드와 엣지의 리스트로 구성되며, 노드와 엣지의 타입은 모두 추상적으로 남겨뒀다. [추상 타입](abstract-types.html)을 사용해서 트레잇 Graph를 구현할 수 있도록 했고, 이를 통해 노드와 엣지에 해당하는 자신의 콘크리트 클래스를 만들 수 있다. 뿐만 아니라 `addNode`라는 메소드는 그래프에 새로운 노드를 추가해준다. 메소드 `connectWith`를 사용해 노드를 연결한다. +그래프는 노드와 엣지의 리스트로 구성되며, 노드와 엣지의 타입은 모두 추상적으로 남겨뒀다. [추상 타입](abstract-type-members.html)을 사용해서 트레잇 Graph를 구현할 수 있도록 했고, 이를 통해 노드와 엣지에 해당하는 자신의 콘크리트 클래스를 만들 수 있다. 뿐만 아니라 `addNode`라는 메소드는 그래프에 새로운 노드를 추가해준다. 메소드 `connectWith`를 사용해 노드를 연결한다. 다음 클래스는 클래스 `Graph`를 구현하는 한 예다. @@ -91,7 +88,7 @@ previous-page: compound-types 다음은 클래스 `ConcreteDirectedGraph`를 사용하는 예다. - object GraphTest extends App { + def graphTest: Unit = { val g: Graph = new ConcreteDirectedGraph val n1 = g.addNode val n2 = g.addNode @@ -101,4 +98,4 @@ previous-page: compound-types n1.connectWith(n3) } -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/singleton-objects.md b/_ko/tour/singleton-objects.md index daff154256..bc5ffaa359 100644 --- a/_ko/tour/singleton-objects.md +++ b/_ko/tour/singleton-objects.md @@ -1,12 +1,9 @@ --- layout: tour title: 싱글톤 객체 - -discourse: false - partof: scala-tour -num: 12 +num: 13 language: ko next-page: regular-expression-patterns @@ -27,7 +24,7 @@ object Blah { 싱글턴 객체는 직접 인스턴스화 될 수 없는 싱글턴 클래스를 정의하기 위한 축약형 같은 것이며, `object`의 정의 시점의 같은 이름을 가진 `val` 멤버 같은 것이다. 사실 `val`과 같이, 싱글턴 객체는 변칙적이긴 하지만 [트레잇](traits.html)이나 클래스의 멤버로서 정의될수 있다. -하나의 싱글턴 객체는 클래스와 트레잇으로 확장할수 있다. 사실, [타입 파라미터](generic-classes.html)가 없는 [케이스 클래스](case-classes.html)는 기본적으로 같은 이름의 싱글턴 객체를 생성하며, 구현된 [`Function*`](http://www.scala-lang.org/api/current/scala/Function1.html)을 가진다. +하나의 싱글턴 객체는 클래스와 트레잇으로 확장할수 있다. 사실, [타입 파라미터](generic-classes.html)가 없는 [케이스 클래스](case-classes.html)는 기본적으로 같은 이름의 싱글턴 객체를 생성하며, 구현된 [`Function*`](https://www.scala-lang.org/api/current/scala/Function1.html)을 가진다. ## 동반자(Companions) ## @@ -37,7 +34,7 @@ object Blah { 하나의 클래스와 그 동반자 객체는 어떤 경우라도, 아래와 같이 *같은* 소스파일에 정의되어야 한다. -```tut +```scala mdoc class IntPair(val x: Int, val y: Int) object IntPair { diff --git a/_ko/tour/tour-of-scala.md b/_ko/tour/tour-of-scala.md index e7bcd6b3de..0bf0b28232 100644 --- a/_ko/tour/tour-of-scala.md +++ b/_ko/tour/tour-of-scala.md @@ -1,9 +1,6 @@ --- layout: tour title: 들어가며 - -discourse: false - partof: scala-tour num: 1 @@ -12,41 +9,51 @@ language: ko next-page: basics --- -스칼라는 정확하고 명쾌하며 타입 세이프한 방식으로 일반적인 유형의 프로그래밍 패턴을 표현하기 위해 설계된 새로운 다중 패러다임 프로그래밍 언어다. 스칼라는 객체지향과 함수형 언어를 자연스럽게 통합해준다. +## 투어를 환영합니다 +이 투어에서는 스칼라에서 가장 자주 사용되는 기능을 요약하여 소개하며, 스칼라 초보자를 대상으로 합니다. + +언어 전체를 다루는 튜토리얼이 아닌 간단히 둘러보기입니다. 자세히 다루고 싶다면, [책](/books.html)을 구하거나 [다른 자료](/online-courses.html)를 찾아보세요. + +## 스칼라란? +스칼라는 일반적인 프로그래밍 패턴을 간결하고 우아하며 타입-세이프한 방식으로 표현할 수 있게 설계된 최신 멀티-패러다임 프로그래밍 언어입니다. 객체지향과 함수형 언어의 특징을 자연스럽게 통합합니다. ## 스칼라는 객체지향이다 ## -[모든 값이 객체](unified-types.html)라는 측면에서 스칼라는 순수 객체지향 언어다. 객체의 타입과 행위는 [클래스](classes.html)와 [트레잇](traits.html)으로 나타난다. 클래스는 서브클래스를 만들거나, 다중 상속을 깔끔하게 대체하는 유연한 [믹스인 기반 컴포지션](mixin-class-composition.html) 방법을 통해 확장된다. +[모든 값이 객체](unified-types.html)라는 의미에서 스칼라는 순수 객체지향 언어입니다. 객체의 타입과 행위는 [클래스](classes.html)와 [트레잇](traits.html)으로 설명됩니다. 클래스는 서브클래스를 만들거나, 다중 상속을 깔끔하게 대체하는 유연한 [믹스인 기반 컴포지션](mixin-class-composition.html)을 통해 확장 가능합니다. ## 스칼라는 함수형이다 ## -또한, 스칼라는 [모든 함수가 값](unified-types.html)이라는 측면에서 함수형 언어다. 스칼라는 익명 함수를 위한 경량 구문을 제공하고, [고차 함수](higher-order-functions.html)를 지원하며, 함수의 [중첩](nested-functions.html)을 허용하고, [커링](multiple-parameter-lists.html)을 지원한다. 스칼라의 [케이스 클래스](case-classes.html)와 케이스 클래스의 [패턴 매칭](pattern-matching.html) 빌트인 지원을 통해 여러 함수형 프로그래밍 언어에서 사용되는 대수 타입을 만들 수 있다. +또한, 스칼라는 [모든 함수가 값](unified-types.html)이라는 의미에서 함수형 언어입니다. 스칼라는 익명 함수를 위한 경량화된 구문을 제공하고, [고차 함수](higher-order-functions.html)를 지원하며, 함수의 [중첩](nested-functions.html)을 허용하고, [커링](multiple-parameter-lists.html)을 지원합니다. 스칼라의 [케이스 클래스](case-classes.html)와 케이스 클래스의 [패턴 매칭](pattern-matching.html) 빌트인 지원을 통해 여러 함수형 프로그래밍 언어에서 사용되는 대수 타입을 만들 수 있습니다. -뿐만 아니라 스칼라의 패턴 매칭 개념은 [우측 무시 시퀀스 패턴](regular-expression-patterns.html)의 도움을 받아 자연스럽게 XML 데이터의 처리로 확장된다. 이런 맥락에서 시퀀스 컴프리헨션은 쿼리를 만들 때 유용하다. 이런 기능 때문에 스칼라는 웹 서비스와 같은 애플리케이션 개발에 있어서 이상적인 선택이 될 수 있다. +또한, 스칼라의 패턴 매칭 개념은 [추출자 오브젝트](extractor-objects.html)를 이용한 일반적인 확장으로 [우측 무시 시퀀스 패턴](regular-expression-patterns.html)의 도움을 받아 XML 데이터의 처리까지 자연스럽게 확장됩니다. 이런 맥락에서 [for 컴프리헨션](for-comprehensions.html)은 쿼리를 만들어 내는데 유용합니다. 이런 기능 덕분에 스칼라는 웹 서비스와 같은 애플리케이션 개발에 있어서 이상적인 선택이 될 수 있습니다. ## 스칼라는 정적 타입이다 ## -스칼라는 안전하고 일관성 있는 추상화를 정적으로 강제하는 풍부한 타입 시스템을 장착하고 있다. 특히 타입 시스템은 다음과 같은 사항을 지원한다. +스칼라의 표현형(expressive) 타입 시스템은 컴파일 시간에 안전하고 일관된 방식의 추상화를 사용하도록 강제합니다. 타입 시스템은 다음을 지원합니다: * [제네릭 클래스](generic-classes.html) * [가변성 어노테이션](variances.html) * [상위 타입 경계](upper-type-bounds.html)와 [하위 타입 경계](lower-type-bounds.html) -* 객체 멤버로써의 [내부 클래스](inner-classes.html)와 [추상 타입](abstract-types.html) +* 객체 멤버로써의 [내부 클래스](inner-classes.html)와 [추상 타입 멤버](abstract-type-members.html) * [합성 타입](compound-types.html) * [명시적으로 타입이 지정된 자기 참조](self-types.html) -* 뷰 +* [암시적 파라미터](implicit-parameters.html)와 [변환](implicit-conversions.html) * [다형 메소드](polymorphic-methods.html) -[로컬 타입 추론 방식](type-inference.html)은 사용자가 불필요한 타입 정보를 어노테이션해야 하는 불편함을 줄여준다. 이와 함께, 이런 기능은 프로그래밍 추상화를 안전하게 재사용하고 소프트웨어를 타입 세이프하게 확장하는 강력한 기반이 된다. +[타입 추론](type-inference.html)은 사용자가 매번 불필요한 타입 정보를 코드에 언급 해야 하는 불편함을 줄여줍니다. 이러한 기능을 조합하여 사용하면, 프로그래밍 추상화를 안전하게 재사용할 수 있고, 소프트웨어를 타입-세이프하게 확장할 수 있습니다. ## 스칼라는 확장성이 높다 ## -실제 개발 상황에선, 도메인 고유 애플리케이션의 개발에 도메인 고유 언어 확장이 필요할 때가 많다. 스칼라는 라이브러리의 형태로 새로운 언어 구성을 쉽고 자연스럽게 추가할 수 있도록 고유한 언어 기능 조합을 제공한다. +실제 개발 상황에선, 도메인 기반 애플리케이션의 개발에 종종 도메인별 언어 확장이 필요할 때가 있습니다. 스칼라는 라이브러리의 형태로 새로운 언어 구성을 쉽고 자연스럽게 추가할 수 있도록 고유한 언어 기능 조합을 제공합니다. + +대부분의 경우 매크로와 같은 메타 프로그래밍 기능을 사용하지 않고도 이 작업을 수행 할 수 있습니다. 예를 들어, + + +* [Implicit classes](/overviews/core/implicit-classes.html)에서는 기존 타입에 확장 메서드를 추가할 수 있습니다. +* [문자열 보간](/overviews/core/string-interpolation.html)은 사용자정의 보간기를 사용하여 사용자가 직접 확장할 수 있습니다. -* 어떤 메소드든 [중위나 후위 연산자](operators.html)로 사용될 수 있다. -* [클로저는 기대 타입에 따라 자동으로 생성된다](automatic-closures.html)(타입이 대상에 맞춰진다). +## 스칼라 상호운용성 -두 기능을 함께 엮어서 사용하면 새로운 구문을 확장하거나 매크로 같은 메타 프로그래밍을 활용할 필요없이 명령문을 정의할 수 있도록 해준다. +스칼라는 많은 사람들이 사용하는 자바 실행 환경(JRE)과 서로 잘 호환되도록 설계되었습니다. 특히, 주류 객체지향 자바 프로그래밍 언어와의 상호작용은 가능한한 매끄럽게 작동합니다. 자바 언어의 SAMs, [람다](higher-order-functions.html), [어노테이션](annotations.html), [제네릭](generic-classes.html) 같은 최신 특성은 스칼라에서도 동일하게 발견됩니다. -스칼라는 자바와 닷넷과 상호 호환된다. -스칼라는 잘 알려진 자바 2 런타임 환경(JRE)과 상호 호환되도록 설계됐다. 특히 객체지향의 주류인 자바 프로그래밍 언어와 굉장히 자연스럽게 상호작용한다. 스칼라는 자바와 같은 컴파일 모델(컴파일 분리, 동적 클래스 로딩)을 사용하며, 현재 사용되고 있는 수많은 높은 품질의 라이브러리를 그대로 활용할 수 있도록 해준다. +[기본 파라미터](default-parameter-values.html)와 [이름 지정 파라미터](named-arguments.html) 같은 자바에 없는 기능은 적절한 자바 코드로 컴파일이 됩니다. 스칼라는 자바와 같은 컴파일 모델(분리 컴파일, 동적 클래스 로딩)을 가지고 있으며 현존하는 수 많은 높은 품질의 라이브러리들을 활용할 수 있습니다. -다음 페이지로 이동하면 더 자세한 내용을 알아보게 된다. +## 투어를 즐기세요! -윤창석, 이한욱 옮김 +자세한 내용을 보려면 Contents 메뉴의 [다음 페이지](basics.html)로 이동 하십시오. diff --git a/_ko/tour/traits.md b/_ko/tour/traits.md index a090581140..1dd3fb34d9 100644 --- a/_ko/tour/traits.md +++ b/_ko/tour/traits.md @@ -1,48 +1,80 @@ --- layout: tour title: 트레잇 - -discourse: false - partof: scala-tour num: 5 language: ko -next-page: mixin-class-composition +next-page: tuples previous-page: classes +prerequisite-knowledge: expressions, classes, generics, objects, companion-objects --- -트레잇은 자바의 인터페이스와 유사하며, 지원되는 메소드의 서명을 지정해 객체의 타입을 정의하는 데 사용한다. 자바와는 달리, 스칼라에선 트레잇의 일부만 구현할 수도 있다. 다시 말해, 일부 메소드를 선택해 기본 구현 내용을 사전에 정의할 수 있다. 클래스와는 달리, 트레잇은 생성자 파라미터를 가질 수 없다. -다음의 예를 살펴보자. - - trait Similarity { - def isSimilar(x: Any): Boolean - def isNotSimilar(x: Any): Boolean = !isSimilar(x) - } - -이 트레잇은 `isSimilar`와 `isNotSimilar`라는 두 메소드로 구성된다. 메소드 `isSimilar`의 구현은 제공되지 않지만(자바의 abstract와 같다), 메소드 `isNotSimilar`에선 실제로 구현 내용을 정의하고 있다. 그 결과, 이 트레잇과 결합되는 클래스는 오직 `isSimilar`의 실제 구현만을 제공하면 된다. `isNotSimilar`의 행위는 트레잇에서 바로 상속받는다. 일반적으로 트레잇은 [믹스인 클래스 컴포지션](mixin-class-composition.html)을 통해 [클래스](classes.html)(또는 또 다른 트레잇)와 결합된다. - - class Point(xc: Int, yc: Int) extends Similarity { - var x: Int = xc - var y: Int = yc - def isSimilar(obj: Any) = - obj.isInstanceOf[Point] && - obj.asInstanceOf[Point].x == x - } - object TraitsTest extends App { - val p1 = new Point(2, 3) - val p2 = new Point(2, 4) - val p3 = new Point(3, 3) - println(p1.isNotSimilar(p2)) - println(p1.isNotSimilar(p3)) - println(p1.isNotSimilar(2)) - } - -이 프로그램의 실행 결과는 다음과 같다. - - false - true - true - -윤창석, 이한욱 옮김 +트레잇은 클래스간에 인터페이스와 필드를 공유하는 데 사용됩니다. 그것들은 자바8의 인터페이스와 유사합니다. 클래스와 객체는 트레잇을 확장 할 수 있지만 트레잇을 인스턴스화 할 수 없으므로 매개 변수가 없습니다. + +# 트레잇 정의 +가장 단순한 트레잇 정의는 예약어 `trait`과 식별자만 있는 것입니다: + +```scala mdoc +trait HairColor +``` + +트레잇은 제네릭 타입과 추상 메서드로 특히 유용합니다. +```scala mdoc +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} +``` + +`trait Iterator[A]`를 확장하려면 `A` 타입 지정과 `hasNext`, `next` 메서드 구현이 필요합니다. + +## 트레잇 사용하기 +`extends` 예약어를 사용하여 트레잇을 확장하십시오. 그런 다음 `override` 예약어를 사용하여 트레잇의 추상 멤버를 구현하십시오: +```scala mdoc:nest +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} + +class IntIterator(to: Int) extends Iterator[Int] { + private var current = 0 + override def hasNext: Boolean = current < to + override def next(): Int = { + if (hasNext) { + val t = current + current += 1 + t + } else 0 + } +} + + +val iterator = new IntIterator(10) +iterator.next() // returns 0 +iterator.next() // returns 1 +``` +이 `IntIterator` 클래스는 상한선으로 매개변수 `to`를 취합니다. `extends Iterator[Int]`는 트레잇 `Iterator[A]`를 확장했으며 `next` 메서드는 Int 값을 반환해야 한다는 의미입니다. + +## 서브타이핑 +특정 트레잇이 필요한 곳에 그 트레잇의 서브타입을 대신 사용할 수 있습니다. +```scala mdoc +import scala.collection.mutable.ArrayBuffer + +trait Pet { + val name: String +} + +class Cat(val name: String) extends Pet +class Dog(val name: String) extends Pet + +val dog = new Dog("Harry") +val cat = new Cat("Sally") + +val animals = ArrayBuffer.empty[Pet] +animals.append(dog) +animals.append(cat) +animals.foreach(pet => println(pet.name)) // Prints Harry Sally +``` +`trait Pet`에는 Cat과 Dog의 생성자에서 구현된 추상 필드 `name`이 있습니다. 마지막 줄에서 `pet.name`을 호출하고 있는데, 이것은 트레잇 `Pet`의 서브타입에서 구현되어야 합니다. diff --git a/_ko/tour/tuples.md b/_ko/tour/tuples.md new file mode 100644 index 0000000000..e4b7ff32c0 --- /dev/null +++ b/_ko/tour/tuples.md @@ -0,0 +1,79 @@ +--- +layout: tour +title: 튜플 + +partof: scala-tour + +num: 6 +language: ko + +next-page: mixin-class-composition +previous-page: traits +topics: tuples +--- + +스칼라에서 튜플은 정해진 요소(element)를 가지는 값으로 각 요소는 고유한 타입을 가진다. 튜플은 불변적이다. + +튜플은 특히 메소드로부터 여러개의 값을 리턴하는데 편리하게 사용할 수 있다. + +두개의 엘리먼트를 갖는 튜플은 다음과 같이 생성할 수 있다: + +```scala mdoc +val ingredient = ("Sugar" , 25) +``` + +위 코드는 `String`과 `Int` 엘리먼트를 포함하는 튜플을 생성한다. + +`ingredient`의 추론된 타입은 `Tuple2[String, Int]`의 약칭인 `(String, Int)`이다. + +튜플들을 나타내기 위해서 Scala에서는 다음과 같은 형태의 클래스들을 사용한다: `Tuple2`, `Tuple3`, ... ,`Tuple22`. +각 클래스는 파라미터 타입의 갯수 만큼 엘리먼트들을 가지고 있다. + +## 엘리먼트 접근하기 + +튜플의 엘리먼트에 접근하기 위한 한가지 방법은 위치로 접근하는 것이다. 각 요소들은 `_1`, `_2`, ... 와 같은 이름을 갖는다. + +```scala mdoc +println(ingredient._1) // Sugar +println(ingredient._2) // 25 +``` + +## 튜플에서의 패턴 매칭 + +하나의 튜플은 패턴 매칭을 사용하여 분리할 수 있다: + +```scala mdoc +val (name, quantity) = ingredient +println(name) // Sugar +println(quantity) // 25 +``` + +여기에서 `name`의 추론된 타입은 `String`이고 `quantity`의 추론된 타입은 `Int`이다. + +여기 튜플을 패턴 매칭한 또 다른 예제가 있다: + +```scala mdoc +val planets = + List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6), + ("Mars", 227.9), ("Jupiter", 778.3)) +planets.foreach{ + case ("Earth", distance) => + println(s"Our planet is $distance million kilometers from the sun") + case _ => +} +``` + +또는 `for` comprehension에서: + +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) +for ((a, b) <- numPairs) { + println(a * b) +} +``` + +## 튜플과 케이스 클래스 + +때로는 튜플과 케이스 클래스 중 무엇을 사용할지 힘들 수 있다. 케이스 클래스는 이름이 있는 엘리먼트들을 갖는다. 그 엘리먼트의 이름들은 어떤 종류의 코드에서 가독성을 높일 수 있다. 위의 planet 예제에서 우리는 튜플을 사용하는 것보다 `case class Planet(name: String, distance: Double)`로 정의 하는 것이 더 나을 수도 있다. + +이한샘 옮김 diff --git a/_ko/tour/type-inference.md b/_ko/tour/type-inference.md index 421fb41036..189b334593 100644 --- a/_ko/tour/type-inference.md +++ b/_ko/tour/type-inference.md @@ -1,9 +1,6 @@ --- layout: tour title: 로컬 타입 추론 - -discourse: false - partof: scala-tour num: 28 @@ -33,7 +30,7 @@ previous-page: polymorphic-methods 다음 예제는 이를 나타낸 예제다. - case class MyPair[A, B](x: A, y: B); + case class MyPair[A, B](x: A, y: B) object InferenceTest3 extends App { def id[T](x: T) = x val p = MyPair(1, "scala") // 타입: MyPair[Int, String] @@ -54,4 +51,4 @@ previous-page: polymorphic-methods 이 프로그램은 변수 `obj`의 타입 추론이 `Null`이기 때문에 컴파일되지 않는다. 해당 타입의 유일한 값이 `null`이기 때문에 이 변수는 다른 값을 나타낼 수 없다. -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/unified-types.md b/_ko/tour/unified-types.md index 4388823679..0e12a3aaff 100644 --- a/_ko/tour/unified-types.md +++ b/_ko/tour/unified-types.md @@ -1,9 +1,6 @@ --- layout: tour title: 통합된 타입 - -discourse: false - partof: scala-tour num: 3 @@ -11,38 +8,74 @@ language: ko next-page: classes previous-page: basics + +prerequisite-knowledge: classes, basics --- -자바와는 달리, 스칼라에선 모든 값이 객체다(숫자 값과 함수를 포함해). 스칼라는 클래스 기반이기 때문에 모든 값은 클래스의 인스턴스다. 다음의 다이어그램은 클래스 계층구조를 나타낸다. - -![스칼라 타입 계층구조]({{ site.baseurl }}/resources/images/classhierarchy.img_assist_custom.png) - -## 스칼라 클래스 계층구조 ## - -모든 클래스의 슈퍼클래스인 `scala.Any`로부터 `scala.AnyVal`과 `scala.AnyRef`라는 두 서브클래스가 파생되며, 이 두 클래스는 각각 값 클래스와 참조 클래스를 대표한다. 모든 값 클래스는 미리 정의돼 있으며, 이는 자바와 같은 언어의 원시 타입에 해당한다. 다른 모든 클래스는 참조 타입으로 정의된다. 사용자 정의 클래스는 자동으로 참조 타입으로 정의되며, 이렇게 정의된 클래스는 항상 `scala.AnyRef`의 서브클래스(간접적)다. 스칼라의 모든 사용자 정의 클래스는 암시적으로 트레잇 `scala.ScalaObject`를 확장하고 있다. 스칼라가 실행되는 인프라(예, 자바 런타임 환경) 상의 클래스는 `scala.ScalaObject`를 확장하지 않는다. 스칼라를 자바 런타임 환경의 측면에 맞춰 생각해보자면 , `scala.AnyRef`는 `java.lang.Object`에 해당한다. 위의 다이어그램에는 값 클래스 사이의 암시적 변환을 의미하는 뷰도 함께 표현돼 있다. -다음은 다른 객체처럼 숫자와 문자와 불리언 값과 함수 또한 객체임을 보여주는 예제다. - - object UnifiedTypes extends App { - val set = new scala.collection.mutable.LinkedHashSet[Any] - set += "This is a string" // 문자열을 추가한다 - set += 732 // 숫자를 추가한다 - set += 'c' // 캐릭터를 추가한다 - set += true // 불리언 값을 추가한다 - set += main _ // 메인 함수를 추가한다 - val iter: Iterator[Any] = set.iterator - while (iter.hasNext) { - println(iter.next.toString()) - } - } - -이 프로그램은 `App`을 확장한 최상위 싱글턴 오브젝트로써 애플리케이션 `UnifiedTypes`를 선언했다. 애플리케이션에선 클래스 `LinkedHashSet[Any]`의 인스턴스를 가리키는 지역 변수 `set`을 정의했다. 프로그램은 이 집합에 여러 항목을 추가하는데, 해당 항목은 반드시 선언된 항목의 타입인 `Any`에 맞아야 한다. 마지막에는 모든 항목의 문자열 표현을 출력한다. - -다음은 이 프로그램의 실행 결과다. - - This is a string - 732 - c - true - - -윤창석, 이한욱 옮김 \ No newline at end of file +스칼라에서는 숫자 값과 함수를 포함한 모든 값이 타입을 가지고 있습니다. 다음의 도표는 타입 계층구조를 보여줍니다. + +스칼라 타입 계층구조 + + +## 스칼라 타입 계층구조 ## + +[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html)는 모든 타입들의 슈퍼타입이며 톱타입이라고도 합니다. `Any`에는 `equals`, `hashCode`, `toString` 같은 특정 범용 메서드가 정의되어 있으며 직접적으로 두 개의 서브클래스: `AnyVal`과 `AnyRef`를 가지고 있습니다. + +`AnyVal`은 값 타입을 대표합니다. `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit`, `Boolean`의 미리 정의된 아홉 개의 값 타입이 있으며 이 타입들은 널 값을 가질 수 없습니다. `Unit`은 의미 없는 정보를 갖는 값 타입입니다. `()`와 같이 문자 그대로 선언 할 수있는`Unit`의 인스턴스는 오직 하나만 있습니다. 모든 함수는 무언가를 반환해야하기 때문에 때때로 `Unit`은 유용한 반환 타입입니다. + +`AnyRef`는 참조 타입을 대표합니다. 값 타입이 아닌 모든 타입은 참조 타입으로 정의됩니다. 스칼라에서 모든 사용자정의 타입은 `AnyRef`의 서브타입입니다. 스칼라가 자바 실행 환경에서 사용된다면 `AnyRef`는 `java.lang.Object`에 해당합니다. + +다음 소스는 문자열 값, 정수 값, 문자 값, boolean 값과 함수 역시 모두 객체로 취급됨을 보여주는 샘플입니다: + +```scala mdoc +val list: List[Any] = List( + "a string", + 732, // 정수 값 + 'c', // 문자 값 + true, // boolean 값 + () => "an anonymous function returning a string" +) + +list.foreach(element => println(element)) +``` + +`List[Any]` 타입의 `list` 값을 정의합니다. 이 리스트는 다양한 타입의 원소들로 초기화 되었지만 각각은 `scala.Any`의 인스턴스이므로 리스트에 추가할 수가 있습니다. + +다음은 이 프로그램의 출력 결과입니다. + +``` +a string +732 +c +true + +``` + +## 타입 캐스팅 +값 타입은 다음과 같이 캐스팅할 수 있습니다: +Scala Type Hierarchy + +예제: + +```scala mdoc +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 (이 경우 일부 자리수가 소실되었음을 주의) + +val face: Char = '☺' +val number: Int = face // 9786 +``` + +캐스팅은 단방향이며 컴파일되지 않습니다: + +``` +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 +val z: Long = y // 적합하지 않음(캐스팅 불가) +``` + +참조 타입 또한 서브타입에 대하여 캐스트할 수 있습니다. 이것은 투어에서 나중에 다루겠습니다. + +# Nothing과 Null +`Nothing`은 모든 타입의 서브타입이며, 바텀타입이라고도 합니다. `Nothing`은 값이 없음을 의미하는 타입니다. 일반적으로 예외 발생, 프로그램 종료 또는 무한 루프와 같은 비 종료 신호를 보내는 용도로 사용합니다 (즉, 값으로 평가되지 않는 표현식의 타입 또는 정상적으로 반환되지 않는 메소드). + +`Null`은 모든 참조 타입의 서브타입입니다(즉, AnyRef의 모든 서브타입). 예약어 `null`로 식별되는 단일 값을 갖습니다. `Null`은 주로 다른 JVM 언어와의 상호 운용성을 위해 제공되며 스칼라 코드에서는 거의 사용되지 않아야합니다. 우리는 투어에서 나중에 `null`에 대한 대안을 다룰 것입니다. diff --git a/_ko/tour/upper-type-bounds.md b/_ko/tour/upper-type-bounds.md index 1060947f1b..a3e71d1e56 100644 --- a/_ko/tour/upper-type-bounds.md +++ b/_ko/tour/upper-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: 상위 타입 경계 - -discourse: false - partof: scala-tour num: 19 @@ -13,7 +10,7 @@ next-page: lower-type-bounds previous-page: variances --- -스칼라에선 [타입 파라미터](generic-classes.html) 와 [추상 타입](abstract-types.html)의 타입 경계를 제한할 수 있다. 이런 타입 경계는 타입 변수의 콘크리트 값을 제한하고, 해당 타입의 멤버에 관한 정보를 추가할 수도 있다. _상위 타입 경계_ `T <: A`는 타입 변수 `T`를 선언하면서 서브타입 `A`를 참조하고 있다. 다음은 다형성 메소드 `findSimilar`의 구현을 위해 상위 타입 경계를 사용한 예제다. +스칼라에선 [타입 파라미터](generic-classes.html) 와 [추상 타입](abstract-type-members.html)의 타입 경계를 제한할 수 있다. 이런 타입 경계는 타입 변수의 콘크리트 값을 제한하고, 해당 타입의 멤버에 관한 정보를 추가할 수도 있다. _상위 타입 경계_ `T <: A`는 타입 변수 `T`를 선언하면서 `A`의 서브타입을 참조하고 있다. 다음은 다형성 메소드 `findSimilar`의 구현을 위해 상위 타입 경계를 사용한 예제다. trait Similar { def isSimilar(x: Any): Boolean @@ -36,4 +33,4 @@ previous-page: variances 상위 타입 경계 어노테이션이 없었다면 메소드 `findSimilar`에서 `isSimilar` 메소드를 호출할 수 없었을 것이다. 하위 타입 경계의 사용법은 [이 곳](lower-type-bounds.html)에서 논의한다. -윤창석, 이한욱 옮김 \ No newline at end of file +윤창석, 이한욱 옮김 diff --git a/_ko/tour/variances.md b/_ko/tour/variances.md index 5e0a4d82f3..b8049a6a5c 100644 --- a/_ko/tour/variances.md +++ b/_ko/tour/variances.md @@ -1,9 +1,6 @@ --- layout: tour title: 가변성 - -discourse: false - partof: scala-tour num: 18 @@ -17,7 +14,7 @@ previous-page: generic-classes [제네릭 클래스](generic-classes.html)에 관한 페이지에선 변경 가능한 스택의 예제를 살펴보면서, 클래스 `Stack[T]`에서 정의한 타입은 타입 파라미터의 서브타입이 불변자여야 함을 설명했었다. 이는 추상화된 클래스의 재사용을 제한할 수 있다. 지금부턴 이런 제약이 없는 함수형(즉, 변경이 불가능한) 스택의 구현을 알아본다. 이 구현은 [다형성 메소드](polymorphic-methods.html), [하위 타입 경계](lower-type-bounds.html), 순가변 타입 파라미터 어노테이션 등의 중요 개념을 조합한 좀 더 어려운 예제임을 알아두자. 또한 [내부 클래스](inner-classes.html)를 사용해 명시적인 연결 없이도 스택의 항목을 서로 묶을 수 있도록 만들었다. -```tut +```scala mdoc class Stack[+T] { def push[S >: T](elem: S): Stack[S] = new Stack[S] { override def top: S = elem diff --git a/_ko/tutorials/scala-for-java-programmers.md b/_ko/tutorials/scala-for-java-programmers.md index 4342d2e9c6..1dc0358edb 100644 --- a/_ko/tutorials/scala-for-java-programmers.md +++ b/_ko/tutorials/scala-for-java-programmers.md @@ -3,8 +3,6 @@ layout: singlepage-overview title: 자바 프로그래머를 위한 스칼라 튜토리얼 partof: scala-for-java-programmers - -discourse: false language: ko --- @@ -28,7 +26,7 @@ Scala 언어를 다루는데 필요한 도구들의 사용법을 쉽게 보여 아래를 보자: object HelloWorld { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { println("Hello, world!") } } @@ -49,7 +47,7 @@ Scala 언어를 다루는데 필요한 도구들의 사용법을 쉽게 보여 똑똑한 독자들은 이미 눈치챘겠지만 위의 예제에서 `main` 함수는 `static`이 아니다. Scala에는 정적 멤버(함수든 필드든)라는 개념이 -아얘 존재하지 않는다. 클래스의 일부로 정적 멤버를 정의하는 대신에 Scala +아예 존재하지 않는다. 클래스의 일부로 정적 멤버를 정의하는 대신에 Scala 프로그래머들은 정적이기 원하는 멤버들을 싱글턴 객체안에 선언한다. ### 예제를 컴파일 하기 @@ -99,11 +97,10 @@ Java의 클래스 라이브러리는 `Date`와 `DateFormat`과 같은 이용하자. import java.util.{Date, Locale} - import java.text.DateFormat import java.text.DateFormat._ object FrenchDate { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val now = new Date val df = getDateInstance(LONG, Locale.FRANCE) println(df format now) @@ -118,7 +115,7 @@ Scala의 임포트 구문은 Java의 그것과 매우 비슷해 보이지만 사 합법적인 식별자(함수명 등에 사용 가능한)로 사용된다. 나중에 자세히 살펴 볼 것이다. -따라서 세번째 줄의 임포트 구문은 `DateFormat` 클래스의 모든 멤버를 +따라서 두번째 줄의 임포트 구문은 `DateFormat` 클래스의 모든 멤버를 불러온다. 이렇게 함으로써 정적 함수 `getDateInstance`와 정적 필드 `LONG`이 바로 사용 가능하게 된다. @@ -162,26 +159,10 @@ Java에서는 기본적인 타입(`boolean`이나 `int` 따위)과 참조 가능 오직 함수 호출로만 이루어져 있다. 우리가 이전 장에서 보았듯이, 위의 표현식은 아래의 표현식과 동일하다. - (1).+(((2).*(3))./(x)) + 1.+(2.*(3)./(x)) 위의 표현식처럼 `+`, `*` 등은 Scala에서 합법적인 식별자이다. -위의 두번째 표현식에서 괄호는 꼭 필요하다. 왜냐하면 스칼라의 렉서(lexer)는 -토큰들에 대하여 가장 긴 부분을 찾는 방법을 사용하기 때문이다. 아래의 -표현식은: - - 1.+(2) - -세개(`1.`, `+`, `2`)의 토큰들로 분리된다. 이렇게 토큰들이 -분리되는 이유는 미리 정의되어 있는 유효한 토큰 중에 `1.`이 -`1`보다 길기 때문이다. 토큰 `1.`은 리터럴 `1.0`으로 -해석 되어 `Double` 타입이 된다. 실제로 우리는 `Int` 타입을 -의도 했음에도 말이다. 표현식을 아래와 같이 쓰면: - - (1).+(2) - -토큰 `1`이 `Double`로 해석 되는 것을 방지 할 수 있다. - ### 함수마저 객체다 Java 프로그래머들에게는 놀라운 일이겠지만 Scala에서는 함수도 @@ -206,13 +187,13 @@ Java 프로그래머들에게는 놀라운 일이겠지만 Scala에서는 함수 화면에 출력하는 것이 된다. object Timer { - def oncePerSecond(callback: () => Unit) { + def oncePerSecond(callback: () => Unit): Unit = { while (true) { callback(); Thread sleep 1000 } } - def timeFlies() { + def timeFlies(): Unit = { println("time flies like an arrow...") } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(timeFlies) } } @@ -233,10 +214,10 @@ Java 프로그래머들에게는 놀라운 일이겠지만 Scala에서는 함수 대신에 무명함수를 사용한 새로운 버전의 타이머 프로그램은 아래와 같다: object TimerAnonymous { - def oncePerSecond(callback: () => Unit) { + def oncePerSecond(callback: () => Unit): Unit = { while (true) { callback(); Thread sleep 1000 } } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(() => println("time flies like an arrow...")) } @@ -288,7 +269,7 @@ Scala 클래스의 경우 파라미터들을 가질 수 있다는 것인데 아 뒤에 빈 괄호를 붙여 주어야 한다는 것이다. 아래를 보자: object ComplexNumbers { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val c = new Complex(1.2, 3.4) println("imaginary part: " + c.im()) } @@ -324,7 +305,7 @@ Scala에서는 물론 상위 클래스에 정의된 함수를 오버라이드 def re = real def im = imaginary override def toString() = - "" + re + (if (im < 0) "" else "+") + im + "i" + "" + re + (if (im >= 0) "+" else "") + im + "i" } @@ -332,7 +313,7 @@ Scala에서는 물론 상위 클래스에 정의된 함수를 오버라이드 프로그램에 자주 등장하는 데이터 구조 중의 하나는 트리이다. 인터프리터와 컴파일러는 흔히 트리를 사용하여 내부 표현을 저장하고, -XML 문서도 트리이며, 레드블랙 트리와 같은 저장구조 들도 트리에 +XML 문서도 트리이며, 레드-블랙 트리와 같은 저장구조들도 트리에 기반을 두고 있다. 작은 계산기 프로그램을 통해 Scala에서 이러한 트리들을 어떻게 @@ -483,7 +464,7 @@ Scala로 나타내는 것은 어렵지 않다: **와일드카드**이다. 밑줄 문자 `_`로 쓰며, 모든 값과 매치 되고 따로 이름을 붙이지 않는다. -매턴 매칭의 뛰어난 기능들을 모두 살펴보지는 못했지만, 문서를 너무 +패턴 매칭의 뛰어난 기능들을 모두 살펴보지는 못했지만, 문서를 너무 지루하게 만들지 않기 위하여 이쯤에서 멈추기로 한다. 이제 위에서 정의한 두 개의 예제 함수가 실제로 동작하는 모습을 보자. 산술 표현식 `(x+x)+(7+y)`에 대해 몇가지의 연산을 실행하는 간단한 `main` 함수를 @@ -491,7 +472,7 @@ Scala로 나타내는 것은 어렵지 않다: 그 값을 계산 할 것이고, 다음으로 `x`와 `y`에 대한 심볼 추출을 수행 할 것이다. - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) val env: Environment = { case "x" => 5 case "y" => 7 } println("Expression: " + exp) @@ -566,7 +547,7 @@ Java 프로그래머들이 트레잇을 이해하는 가장 쉬운 길은 코드 def year = y def month = m def day = d - override def toString(): String = year + "-" + month + "-" + day + override def toString(): String = s"$year-$month-$day" 여기서 중요한 부분은 클래스 이름과 파라미터 뒤에 따라오는 `extends Ord` 선언이다. 이 선언은 `Date` 클래스가 `Ord` @@ -663,7 +644,7 @@ Scala는 이 문제를 해결하기 위한 제네릭 클래스와 제네릭 함 사용하기 위해서는 다음과 같이 쓴다: object IntegerReference { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val cell = new Reference[Int] cell.set(13) println("Reference contains the half of " + (cell.get * 2)) @@ -676,7 +657,6 @@ Scala는 이 문제를 해결하기 위한 제네릭 클래스와 제네릭 함 ## 마치며 -우리는 지금까지 Scala 언어의 간략한 소개와 몇가지의 예제를 살펴 -보았다. 흥미가 생겼다면 *Scala By Example*도 함께 읽어보자. 더 수준 -높고 다양한 예제를 만날 수 있다. 필요 할 때마다 *Scala Language -Specification*을 참고하는 것도 좋다. +우리는 지금까지 Scala 언어의 간략한 소개와 몇가지의 예제를 살펴 보았다. +흥미가 생겼다면 *[Tour of Scala](https://docs.scala-lang.org/tour/tour-of-scala.html)*도 함께 읽어보자. +더 수준 높고 다양한 예제를 만날 수 있다. 필요 할 때마다 *Scala Language Specification*을 참고하는 것도 좋다. diff --git a/_layouts/inner-page.html b/_layouts/basic-index.html similarity index 68% rename from _layouts/inner-page.html rename to _layouts/basic-index.html index 30d6366101..901f1a4453 100644 --- a/_layouts/inner-page.html +++ b/_layouts/basic-index.html @@ -1,11 +1,11 @@ --- -layout: inner-page-parent +layout: root-index-layout ---
      -
      +
      {{content}}
      diff --git a/_layouts/blog-detail.html b/_layouts/blog-detail.html deleted file mode 100644 index 8e6419da3b..0000000000 --- a/_layouts/blog-detail.html +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-parent ---- - - -{% include inner-page-blog-detail-main-content.html %} \ No newline at end of file diff --git a/_layouts/blog-list.html b/_layouts/blog-list.html deleted file mode 100644 index d06c97051a..0000000000 --- a/_layouts/blog-list.html +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: inner-page-parent-dropdown ---- - -{% if page.category %} - {% include blog-list.html category=page.category %} -{% else %} - {% include blog-list.html %} -{% endif %} diff --git a/_layouts/cheatsheet.html b/_layouts/cheatsheet.html index 471a120c4f..8809f9cc3e 100644 --- a/_layouts/cheatsheet.html +++ b/_layouts/cheatsheet.html @@ -1,17 +1,23 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout ---
      - {{content}} +
      + {% if page.new-version %} + {% include outdated-notice.html new-version=page.new-version %} + {% endif %} + {{content}} +
      + {% if page.languages %} {% elsif page.language %} {% assign engPath = page.id | remove_first: "/" | remove_first: page.language | append: '.html' %} - {% assign engPg = site.overviews | where: 'partof', page.partof | first %} + {% assign engPg = site.cheatsheets | where: 'partof', page.partof | first %} {{ engPg.languages }}
      - - {% include paginator.html urlPath="events" %} -
      \ No newline at end of file diff --git a/_layouts/frontpage.html b/_layouts/frontpage.html deleted file mode 100644 index 86a7694ae1..0000000000 --- a/_layouts/frontpage.html +++ /dev/null @@ -1,386 +0,0 @@ ---- ---- - -{% include headertop.html %} -{% include headerbottom.html %} - -
      - - - - -
      - -
      -
      -

      {{site.data.common.texts.scalaBackendsTitle}}

      -
        - {% for backend in page.scalaBackends %} -
      • - - {{backend.description}} - -
        • - {% unless forloop.last %}
      • {% endunless %} - {% endfor %} -
      -

      - {{site.data.common.texts.scalaBackendsMore}} -

      -
      -
      - - -
      -
      -
      -

      IDEs for Scala

      -
      - -
      -
      - - -
      -
      -
      -

      Scala in a Nutshell

      -
      -

      click the boxes below to see Scala in action!

      -
      -
      -
      -
      -
      - {% for scalaItem in site.scala_items %} - {% assign loopIndexMod = forloop.index | minus: 1 | modulo: 3 %} - - {% if loopIndexMod == 0 %} - {% assign codeSnippets = '' | split: ',' %} -
      - {% endif %} - {% assign codeSnippets = codeSnippets | push: scalaItem.content %} -
      -

      {{scalaItem.shortTitle}}

      -

      {{scalaItem.shortDescription}}

      -
      - {% if loopIndexMod == 2 or forloop.last %} -
      -
      - {% for snippet in codeSnippets %} -
      {{snippet}}
      - {% endfor %} -
      - {% endif %} - {% endfor %} -
      -
      - {{page.headerButtonTitle}} -

      or visit the Scala Documentation

      -
      -
      -
      - - - - - -
      -
      - {% include online-courses.html %} - {% include upcoming-training.html %} -
      -
      - - -
      -
      -
      -

      Upcoming Events

      -
      -
      - {% assign upcomingEvents = '' | split: ',' %} - {% capture now %}{{site.time | date: '%s' | plus: 0}}{% endcapture %} - {% for event in site.events %} - {% capture date %}{{event.date|date: '%s'|plus: 86400}}{% endcapture %} - {% if now <= date %} - {% assign upcomingEvents = upcomingEvents | push: event %} - {% endif %} - {% endfor %} - {% for event in upcomingEvents limit: 6 %} -
      - - {{event.title}} -
      -

      {{event.title}}

      -
        -
      • {{event.location}}
        • -
      -
        -
      • {{event.start | date_to_string}} {% if event.start != event.end %}- {{event.end | date_to_string}}{% endif %}
        • -
      -
      -       -
      - {% endfor %} -
      -
      -

      See more events or add one to our feed

      -
      -
      -
      - -
      -
      -
      -

      {{page.ecosystemTitle}}

      -

      {{page.ecosystemDescription}}

      -
      -
      -
      - - -
      -
      -

      The Scala Library Index

      -
      - - -
      -
      -
      -
      -
      -
      -
      -
      -
      - -
      -
      -
      -
      -

      What’s New

      -
      - {% assign firstPost = site.posts | first %} -
      -

      {{firstPost.post-type|upcase}}

      -

      {{firstPost.title}}

      - {{firstPost.date | date: "%A, %B %-d, %Y"}} -

      {{firstPost.content}}

      -
      -
      -
      -
      -

      Recently

      -
      - {% for post in site.posts limit:3 offset:1 %} - -

      {{post.title}}

      -
        -
      • {{post.date | date: "%A, %B %-d, %Y"}}
        • -
      • •
        • -
      • {{post.by}}
        • -
      • {{post.post-type|upcase}}
        • -
      -

      {{post.content| strip_html | truncate:140}}

      -       - {% endfor %} -
      -
      -
      - View our blog -
      -
      - -
      -
      -
      -

      Talk to us!

      -
      -
      -

      Mailing lists / forums

      - {% for forum in site.data.chats-forums.discourseForums %} - - {{forum.title}} -

      {{forum.title}}

      -

      {{forum.subtitle}}

      -       - {% endfor %} -
      -
      -

      Real-time (topic-specialized) chat

      - {% assign modLimit = site.data.chats-forums.gitterChannels.size | modulo: 2 %} - {% capture channelLimit %} - {% if modLimit != 0 %} - {{site.data.chats-forums.gitterChannels.size | minus: 1}} - {% else %} - {{site.data.chats-forums.gitterChannels.size}} - {% endif %} - {% endcapture %} - {% for channel in site.data.chats-forums.gitterChannels limit: channelLimit %} - {% if forloop.first %} -
        - {% endif %} -
      • - - - {{channel.name}} - -
        • - - {% assign halfLength = forloop.length | divided_by: 2 | floor %} - {% if forloop.index == halfLength %} -
      -
        - {% endif %} - - {% if forloop.last %} -
      - {% endif %} - {% endfor %} -
      - {% if page.communities %} -
      -

      Communities

      -
        - {% for community in page.communities %} -
      • - {{community.name}} -
        • - {% endfor %} -
      -
      - {% endif %} - -
      -
      - - -{% include twitter-feed.html %} - - -
      - - -
      -
      -
      -

      {{site.data.common.texts.scalaMaintainersTitle}}

      -
      -
        - {% for maintainer in site.data.scala-supporters.maintainers %} -
      • {{maintainer.name}}
        • - {% endfor %} -
      -

      {{site.data.common.texts.scalaSupportersTitle}}

      -
      - {% for supporter in site.data.scala-supporters.supporters %} - {{supporter.name}} - {% endfor %} -
      -
      -
      -
      - -{% include footer.html %} \ No newline at end of file diff --git a/_layouts/glossary.html b/_layouts/glossary.html index e65a189e23..bd15a6274e 100644 --- a/_layouts/glossary.html +++ b/_layouts/glossary.html @@ -1,5 +1,5 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout includeTOC: true --- @@ -7,8 +7,33 @@
      - {{content}} - +
      + {% if page.new-version %} + {% include outdated-notice.html new-version=page.new-version %} + {% endif %} + {{content}} +
      + {% if page.languages %} + + {% elsif page.language %} + {% assign engPath = page.id | remove_first: "/" | remove_first: page.language | append: '.html' %} + {% assign engPg = site.glossary | first %} + + {% endif %} {% include contributors-list.html %}
      diff --git a/_layouts/inner-page-community.html b/_layouts/inner-page-community.html deleted file mode 100644 index f5cdb3afdb..0000000000 --- a/_layouts/inner-page-community.html +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: inner-page-parent ---- - - -{% include masthead-community.html %} - - -{% include inner-page-main-content.html %} \ No newline at end of file diff --git a/_layouts/inner-page-no-masthead.html b/_layouts/inner-page-no-masthead.html deleted file mode 100644 index 28c8fe1663..0000000000 --- a/_layouts/inner-page-no-masthead.html +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-parent ---- - - -{% include inner-page-main-content.html %} \ No newline at end of file diff --git a/_layouts/inner-page-parent.html b/_layouts/inner-page-parent.html deleted file mode 100644 index 3ed25753ca..0000000000 --- a/_layouts/inner-page-parent.html +++ /dev/null @@ -1,31 +0,0 @@ - {% include headertop.html %} {% include headerbottom.html %} - -
      - -{% include navbar-inner.html %} - -
      - - -
      -
      -
      - -

      {{page.title}}

      -
      -
      - -
      - - -
      -
      - -
      -
      - - {% comment %}Specific content from child layouts{% endcomment %} {{content}} - -
      - -{% include footer.html %} \ No newline at end of file diff --git a/_layouts/inner-page-documentation.html b/_layouts/landing-page.html similarity index 72% rename from _layouts/inner-page-documentation.html rename to _layouts/landing-page.html index 5c420b46c3..5dfce6e343 100644 --- a/_layouts/inner-page-documentation.html +++ b/_layouts/landing-page.html @@ -1,5 +1,5 @@ --- -layout: inner-page-parent +layout: root-index-layout --- diff --git a/_layouts/multipage-overview.html b/_layouts/multipage-overview.html index a98e6742e3..6ff8b3aa85 100644 --- a/_layouts/multipage-overview.html +++ b/_layouts/multipage-overview.html @@ -1,5 +1,5 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout includeTOC: true includeCollectionTOC: true --- @@ -8,7 +8,42 @@
      - {{content}} +
      + {% if page.new-version %} + {% include outdated-notice.html new-version=page.new-version %} + {% endif %} + {% if page.versionSpecific %} + {% if page.scala3 %} + {% assign versionSpecificLang = 'scala3' %} + {% else if page.scala2 %} + {% assign versionSpecificLang = 'scala2' %} + {% endif %} + {% if page.language %} + {% assign pageLanguage = page.language %} + {% else %} + {% assign pageLanguage = 'en' %} + {% endif %} + {% include version-specific-notice.html language=versionSpecificLang page-language=pageLanguage %} + {% endif %} + + {{content}} +
      + +
      + {% if page.previous-page %} + ← previous + {% else %} +
      + {% endif %} + {% if page.next-page %} + next → + {% endif %} +
      {% include contributors-list.html %}
      diff --git a/_layouts/online-courses.html b/_layouts/online-courses.html new file mode 100644 index 0000000000..45addb8dfa --- /dev/null +++ b/_layouts/online-courses.html @@ -0,0 +1,29 @@ +--- +layout: root-index-layout +--- + + +
      +
      +
      + {% include online-courses-box.html + path="_markdown/courses-coursera.md" + image="coursera.png" + link="https://www.coursera.org/learn/scala-functional-programming" + %} + {% include online-courses-box.html + path="_markdown/courses-rock-the-jvm.md" + image="rock-the-jvm.png" + link="https://rockthejvm.com" + %} + {% include online-courses-box.html + path="_markdown/courses-extension-school.md" + image="extension-school.png" + link="https://www.epfl.ch/education/continuing-education/effective-programming-in-scala/" + %} +
      + {{content}} +
      +
      +
      +
      diff --git a/_layouts/overview.html b/_layouts/overview.html deleted file mode 100644 index 2d255c52bf..0000000000 --- a/_layouts/overview.html +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: inner-page-parent -includeTOC: true -includeCollectionTOC: true ---- - -{% for pg in site.posts %} - {% if pg.overview == page.overview and pg.languages %} - {% assign languages = pg.languages %} - {% endif %} -{% endfor %} - -{% for pg in site.pages %} - {% if pg.overview == page.overview and pg.languages %} - {% assign languages = pg.languages %} - {% endif %} -{% endfor %} - -{% if page.language %} - {% capture intermediate %}{{ page.url | remove_first: page.language }}{% endcapture %} - {% capture rootTutorialURL %}{{ intermediate | remove_first: '/' }}{% endcapture %} -{% else %} - {% assign rootTutorialURL = page.url %} -{% endif %} - - -{% include inner-page-main-content.html %} diff --git a/_layouts/overviews.html b/_layouts/overviews.html index 888ffc2061..2568640141 100644 --- a/_layouts/overviews.html +++ b/_layouts/overviews.html @@ -1,12 +1,91 @@ --- -layout: inner-page-parent +layout: root-index-layout --- +{% if page.language %} + {% capture dataName %}overviews-{{page.language}}{% endcapture %} +{% else %} + {% capture dataName %}overviews{% endcapture %} +{% endif %}
      + +
      +
      + Language +
        +
        +
        + + +
        -
        - {{content}} +
        + {% for category in site.data[dataName] %} +

        {{ category.category }}

        + {% if category.description %}

        {{ category.description }}

        {% endif %} +
        + {% for overview in category.overviews %} + {% if overview.root %} + {% assign overviewroot = overview.root %} + {% else %} + {% assign overviewroot = 'overviews/' %} + {% endif %} +
        +
        +
        + {% if overview.icon %} +
        +
        +
        + {% endif %} + {% capture originalOverviewUrl %}/{{overviewroot}}{{ overview.url }}{% endcapture %} + {% capture translatedOverviewId %}/{{page.language}}/{{overviewroot}}{{ overview.url | remove_first: '.html' }}{% endcapture %} + {% assign translatedOverview = site.documents | where: 'id', translatedOverviewId | first %} +

        {{ overview.title }}

         +
        +
        + {% if overview.label-text %}
        {{ overview.label-text }}
        {% endif %} + {% if overview.by %}
        By {{ overview.by }}
        {% endif %} + {% if overview.description %}

        {{ overview.description }}

        {% endif %} + {% if overview.subdocs %} + Contents +
          + {% for doc in overview.subdocs %} + {% capture originalDocUrl %}/{{overviewroot}}{{ doc.url }}{% endcapture %} + {% capture translatedDocId %}/{{page.language}}/{{overviewroot}}{{ doc.url | remove_first: '.html' }}{% endcapture %} + {% assign translatedDoc = site.documents | where: 'id', translatedDocId | first %} +
        • {{ doc.title }}
          • + {% endfor %} +
        + {% endif %} +
        +
        +
        + Read +
        +
        + {% endfor %} +
        + {% endfor %}
        diff --git a/_layouts/inner-page-parent-dropdown.html b/_layouts/root-content-layout.html similarity index 67% rename from _layouts/inner-page-parent-dropdown.html rename to _layouts/root-content-layout.html index d2e5029f68..b45513d346 100644 --- a/_layouts/inner-page-parent-dropdown.html +++ b/_layouts/root-content-layout.html @@ -3,10 +3,11 @@
        +{% include alert-banner.html message_id='disabled' message=site.data.messages.scam-banner %} + {% include navbar-inner.html %}
        -
        @@ -21,11 +22,19 @@ {% endif %}

        {{ page.title }}

        +
        +
        + +
        + + +
        Language -
          +
            +
            diff --git a/_layouts/root-index-layout.html b/_layouts/root-index-layout.html new file mode 100644 index 0000000000..c236bb7b2f --- /dev/null +++ b/_layouts/root-index-layout.html @@ -0,0 +1,33 @@ +{% include headertop.html %} {% include headerbottom.html %} + +
            + +{% include alert-banner.html message_id='disabled' message=site.data.messages.scam-banner %} + +{% include navbar-inner.html %} + +
            + + +
            +
            +
            + +

            {{page.title}}

            +
            +
            + +
            + + +
            +
            +
            +
            + + {% comment %}Specific content from child layouts{% endcomment %} + {{content}} + +
            + +{% include footer.html %} diff --git a/_layouts/singlepage-overview.html b/_layouts/singlepage-overview.html index 72cabad3fd..867e4af164 100644 --- a/_layouts/singlepage-overview.html +++ b/_layouts/singlepage-overview.html @@ -1,5 +1,5 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout includeTOC: true --- @@ -7,7 +7,26 @@
            - {{content}} +
            + {% if page.new-version %} + {% include outdated-notice.html new-version=page.new-version %} + {% endif %} + {% if page.versionSpecific %} + {% if page.scala3 %} + {% assign versionSpecificLang = 'scala3' %} + {% else if page.scala2 %} + {% assign versionSpecificLang = 'scala2' %} + {% endif %} + {% include version-specific-notice.html language=versionSpecificLang %} + {% endif %} + + {{content}} +
            {% include contributors-list.html %}
            diff --git a/_layouts/sip-meeting-results.html b/_layouts/sip-meeting-results.html new file mode 100644 index 0000000000..92ef1999f9 --- /dev/null +++ b/_layouts/sip-meeting-results.html @@ -0,0 +1,31 @@ +--- +layout: sips +--- + +

            The Committee discussed and voted on the proposals listed below.

            + + + + + + + {% for proposal in page.proposals %} + + + + + {% endfor %} + +
            ProposalResult
            {{proposal.name}} + {% if proposal.result == 'rejected' %} + Rejected + {% elsif proposal.result == 'accepted' %} + Accepted + {% else %} + Under Review + {% endif %} +
            + +
            + {{content}} +
            diff --git a/_layouts/sip.html b/_layouts/sip.html index 0805943f08..90174048d9 100644 --- a/_layouts/sip.html +++ b/_layouts/sip.html @@ -1,12 +1,12 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout includeTOC: true ---
            -
            +
            {{content}}
            @@ -14,19 +14,32 @@
            - {% if page.vote-status %} -
            SIP Committee Decision
            -
            {{ site.data.sip-data[page.vote-status].text }}
            -

            - {% if page.vote-text %}{{ page.vote-text }}{% endif %} -

            - {% endif %} +
            Status
            + {% if page.stage == "implementation" %} +

            + This proposal has been accepted by the committee. + {% if page.status == "waiting-for-implementation" %} + An implementation is welcome in the compiler. + {% else %} + It might be available as an experimental feature in the latest version of the compiler. + {% endif %} +

            + {% else if page.stage == "completed" %} +

            + This proposal has been implemented, + {% if page.status == "accepted" %} + it will be available in the next minor release of the compiler. + {% else if page.status == "shipped" %} + it is available in the latest version of the compiler. + {% endif %} +

            + {% endif %}
            SIP Contents
            -
            Problem with this page?
                 Please help us fix it!
            +
            Problem with this page?
                 Please help us fix it!
            diff --git a/_layouts/sips.html b/_layouts/sips.html index ea2b40b2db..b7da7039b5 100644 --- a/_layouts/sips.html +++ b/_layouts/sips.html @@ -1,11 +1,11 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout ---
            -
            +
            {{content}}
            @@ -17,30 +17,20 @@
            Scala Improv -
            SIP/SPP Meetings
            +
            SIP Meetings
            -
            -
            Next meeting:
            -
              Live
            -
            -
            - Tune in and join us, live! Ask the SIP committee questions, weigh in, or just follow along. -
            Watch → -
            -
            -
            Writing a SIP
            +
            Submitting a SIP
            -
            Problem with this page?
                 Please help us fix it!
            +
            Problem with this page?
                 Please help us fix it!
            diff --git a/_layouts/style-guide.html b/_layouts/style-guide.html index ecc9a53bf2..41e39d8709 100644 --- a/_layouts/style-guide.html +++ b/_layouts/style-guide.html @@ -1,5 +1,5 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout includeCollectionTOC: true includeTOC: true --- @@ -8,7 +8,12 @@
            - {{content}} +
            + {% if page.new-version %} + {% include outdated-notice.html new-version=page.new-version %} + {% endif %} + {{content}} +
            {% include contributors-list.html %}
            diff --git a/_layouts/tour.html b/_layouts/tour.html index 9369547dd7..33e67984de 100644 --- a/_layouts/tour.html +++ b/_layouts/tour.html @@ -1,5 +1,5 @@ --- -layout: inner-page-parent-dropdown +layout: root-content-layout includeTOC: true includeCollectionTOC: true --- @@ -8,7 +8,18 @@
            - {{content}} +
            + {% if page.new-version %} + {% include outdated-notice.html new-version=page.new-version %} + {% endif %} + + {{content}} +
            {% if page.previous-page %} diff --git a/_layouts/training.html b/_layouts/training.html deleted file mode 100644 index 3274549b11..0000000000 --- a/_layouts/training.html +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: inner-page-parent ---- - -{% include events-training-list-top.html collection=paginator.trainings %} -
            - - {% include paginator.html urlPath="training" %} -
            \ No newline at end of file diff --git a/_overviews/FAQ/breakout.md b/_overviews/FAQ/breakout.md deleted file mode 100644 index 0a39214d55..0000000000 --- a/_overviews/FAQ/breakout.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -layout: multipage-overview -title: What is breakOut, and how does it work? - -discourse: true - -overview-name: FAQ -partof: FAQ - -num: 5 -permalink: /tutorials/FAQ/:title.html ---- -You might have encountered some code like the one below, and wonder what is -`breakOut`, and why is it being passed as parameter? - - import scala.collection.breakOut - val map : Map[Int,String] = List("London", "France").map(x => (x.length, x))(breakOut) - - -The answer is found on the definition of `map`: - - def map[B, That](f : (A) => B)(implicit bf : CanBuildFrom[Repr, B, That]) : That - -Note that it has two parameters. The first is your function and the second is -an implicit. If you do not provide that implicit, Scala will choose the most -_specific_ one available. - -### About breakOut - -So, what's the purpose of `breakOut`? Consider the example given at the -beginning , You take a list of strings, transform each string into a tuple -`(Int, String)`, and then produce a `Map` out of it. The most obvious way to do -that would produce an intermediary `List[(Int, String)]` collection, and then -convert it. - -Given that `map` uses a `Builder` to produce the resulting collection, wouldn't -it be possible to skip the intermediary `List` and collect the results directly -into a `Map`? Evidently, yes, it is. To do so, however, we need to pass a -proper `CanBuildFrom` to `map`, and that is exactly what `breakOut` does. - -Let's look, then, at the definition of `breakOut`: - - def breakOut[From, T, To](implicit b : CanBuildFrom[Nothing, T, To]) = - new CanBuildFrom[From, T, To] { - def apply(from: From) = b.apply() ; def apply() = b.apply() - } - -Note that `breakOut` is parameterized, and that it returns an instance of -`CanBuildFrom`. As it happens, the types `From`, `T` and `To` have already been -inferred, because we know that `map` is expecting `CanBuildFrom[List[String], -(Int, String), Map[Int, String]]`. Therefore: - - From = List[String] - T = (Int, String) - To = Map[Int, String] - -To conclude let's examine the implicit received by `breakOut` itself. It is of -type `CanBuildFrom[Nothing,T,To]`. We already know all these types, so we can -determine that we need an implicit of type -`CanBuildFrom[Nothing,(Int,String),Map[Int,String]]`. But is there such a -definition? - -Let's look at `CanBuildFrom`'s definition: - - trait CanBuildFrom[-From, -Elem, +To] - extends AnyRef - -So `CanBuildFrom` is contra-variant on its first type parameter. Because -`Nothing` is a bottom class (ie, it is a subclass of everything), that means -*any* class can be used in place of `Nothing`. - -Since such a builder exists, Scala can use it to produce the desired output. - -### About Builders - -A lot of methods from Scala's collections library consists of taking the -original collection, processing it somehow (in the case of `map`, transforming -each element), and storing the results in a new collection. - -To maximize code reuse, this storing of results is done through a _builder_ -(`scala.collection.mutable.Builder`), which basically supports two operations: -appending elements, and returning the resulting collection. The type of this -resulting collection will depend on the type of the builder. Thus, a `List` -builder will return a `List`, a `Map` builder will return a `Map`, and so on. -The implementation of the `map` method need not concern itself with the type of -the result: the builder takes care of it. - -On the other hand, that means that `map` needs to receive this builder somehow. -The problem faced when designing Scala 2.8 Collections was how to choose the -best builder possible. For example, if I were to write `Map('a' -> -1).map(_.swap)`, I'd like to get a `Map(1 -> 'a')` back. On the other hand, a -`Map('a' -> 1).map(_._1)` can't return a `Map` (it returns an `Iterable`). - -The magic of producing the best possible `Builder` from the known types of the -expression is performed through this `CanBuildFrom` implicit. - -### About CanBuildFrom - -To better explain what's going on, I'll give an example where the collection -being mapped is a `Map` instead of a `List`. I'll go back to `List` later. For -now, consider these two expressions: - - Map(1 -> "one", 2 -> "two") map Function.tupled(_ -> _.length) - Map(1 -> "one", 2 -> "two") map (_._2) - -The first returns a `Map` and the second returns an `Iterable`. The magic of -returning a fitting collection is the work of `CanBuildFrom`. Let's consider -the definition of `map` again to understand it. - -The method `map` is inherited from `TraversableLike`. It is parameterized on -`B` and `That`, and makes use of the type parameters `A` and `Repr`, which -parameterize the class. Let's see both definitions together: - -The class `TraversableLike` is defined as: - - trait TraversableLike[+A, +Repr] - extends HasNewBuilder[A, Repr] with AnyRef - - def map[B, That](f : (A) => B)(implicit bf : CanBuildFrom[Repr, B, That]) : That - - -To understand where `A` and `Repr` come from, let's consider the definition of -`Map` itself: - - trait Map[A, +B] - extends Iterable[(A, B)] with Map[A, B] with MapLike[A, B, Map[A, B]] - -Because `TraversableLike` is inherited by all traits which extend `Map`, `A` -and `Repr` could be inherited from any of them. The last one gets the -preference, though. So, following the definition of the immutable `Map` and all -the traits that connect it to `TraversableLike`, we have: - - trait Map[A, +B] - extends Iterable[(A, B)] with Map[A, B] with MapLike[A, B, Map[A, B]] - - trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]] - extends MapLike[A, B, This] - - trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]] - extends PartialFunction[A, B] with IterableLike[(A, B), This] with Subtractable[A, This] - - trait IterableLike[+A, +Repr] - extends Equals with TraversableLike[A, Repr] - - trait TraversableLike[+A, +Repr] - extends HasNewBuilder[A, Repr] with AnyRef - -If you pass the type parameters of `Map[Int, String]` all the way down the -chain, we find that the types passed to `TraversableLike`, and, thus, used by -`map`, are: - - A = (Int,String) - Repr = Map[Int, String] - -Going back to the example, the first map is receiving a function of type -`((Int, String)) => (Int, Int)` and the second map is receiving a function of -type `((Int, String)) => Int`. I use the double parenthesis to emphasize it is -a tuple being received, as that's the type of `A` as we saw. - -With that information, let's consider the other types. - - map Function.tupled(_ -> _.length): - B = (Int, Int) - - map (_._2): - B = Int - -We can see that the type returned by the first `map` is `Map[Int,Int]`, and the -second is `Iterable[String]`. Looking at `map`'s definition, it is easy to see -that these are the values of `That`. But where do they come from? - -If we look inside the companion objects of the classes involved, we see some -implicit declarations providing them. On object `Map`: - - implicit def canBuildFrom [A, B] : CanBuildFrom[Map, (A, B), Map[A, B]] - -And on object `Iterable`, whose class is extended by `Map`: - - implicit def canBuildFrom [A] : CanBuildFrom[Iterable, A, Iterable[A]] - -These definitions provide factories for parameterized `CanBuildFrom`. - -Scala will choose the most specific implicit available. In the first case, it -was the first `CanBuildFrom`. In the second case, as the first did not match, -it chose the second `CanBuildFrom`. - -### Back to the first example - -Let's see the first example, `List`'s and `map`'s definition (again) to -see how the types are inferred: - - val map : Map[Int,String] = List("London", "France").map(x => (x.length, x))(breakOut) - - sealed abstract class List[+A] - extends LinearSeq[A] with Product with GenericTraversableTemplate[A, List] with LinearSeqLike[A, List[A]] - - trait LinearSeqLike[+A, +Repr <: LinearSeqLike[A, Repr]] - extends SeqLike[A, Repr] - - trait SeqLike[+A, +Repr] - extends IterableLike[A, Repr] - - trait IterableLike[+A, +Repr] - extends Equals with TraversableLike[A, Repr] - - trait TraversableLike[+A, +Repr] - extends HasNewBuilder[A, Repr] with AnyRef - - def map[B, That](f : (A) => B)(implicit bf : CanBuildFrom[Repr, B, That]) : That - -The type of `List("London", "France")` is `List[String]`, so the types `A` and -`Repr` defined on `TraversableLike` are: - - A = String - Repr = List[String] - -The type for `(x => (x.length, x))` is `(String) => (Int, String)`, so the type -of `B` is: - - B = (Int, String) - -The last unknown type, `That` is the type of the result of `map`, and we -already have that as well: - - val map : Map[Int,String] = - -So, - - That = Map[Int, String] - -That means `breakOut` must, necessarily, return a type or subtype of -`CanBuildFrom[List[String], (Int, String), Map[Int, String]]`. - -This answer was originally submitted in response to [this question on Stack Overflow][1]. - - [1]: http://stackoverflow.com/q/1715681/53013 diff --git a/_overviews/FAQ/chaining-implicits.md b/_overviews/FAQ/chaining-implicits.md deleted file mode 100644 index 261d8b7bb7..0000000000 --- a/_overviews/FAQ/chaining-implicits.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -layout: multipage-overview -title: How can I chain/nest implicit conversions? - -discourse: true - -overview-name: FAQ -partof: FAQ - -num: 6 -permalink: /tutorials/FAQ/:title.html ---- - -The enrich-my-library pattern allows one to seemingly add a method to a class by -making available an implicit conversion from that class to one that implements -the method. - -Scala does not allow two such implicit conversions taking place, however, so -one cannot got from `A` to `C` using an implicit `A` to `B` and another -implicit `B` to `C`. Is there a way around this restriction? - -Scala has a restriction on automatic conversions to add a method, which is that -it won't apply more than one conversion in trying to find methods. For example: - - class A(val n: Int) - class B(val m: Int, val n: Int) - class C(val m: Int, val n: Int, val o: Int) { - def total = m + n + o - } - - import scala.language.implicitConversions - - // This demonstrates implicit conversion chaining restrictions - object T1 { // to make it easy to test on REPL - implicit def toA(n: Int): A = new A(n) - implicit def aToB(a: A): B = new B(a.n, a.n) - implicit def bToC(b: B): C = new C(b.m, b.n, b.m + b.n) - - // won't work - println(5.total) - println(new A(5).total) - - // works - println(new B(5, 5).total) - println(new C(5, 5, 10).total) - } - -However, if an implicit definition requires an implicit parameter itself, Scala -_will_ look for additional implicit values for as long as needed. Continuing from -the last example: - - object T2 { - implicit def toA(n: Int): A = new A(n) - implicit def aToB[A1](a: A1)(implicit f: A1 => A): B = - new B(a.n, a.n) - implicit def bToC[B1](b: B1)(implicit f: B1 => B): C = - new C(b.m, b.n, b.m + b.n) - - // works - println(5.total) - println(new A(5).total) - println(new B(5, 5).total) - println(new C(5, 5, 10).total) - } - -_"Magic!"_, you might say. Not so. Here is how the compiler would translate each -one: - - object T1Translated { - implicit def toA(n: Int): A = new A(n) - implicit def aToB(a: A): B = new B(a.n, a.n) - implicit def bToC(b: B): C = new C(b.m, b.n, b.m + b.n) - - // Scala won't do this - println(bToC(aToB(toA(5))).total) - println(bToC(aToB(new A(5))).total) - - // Just this - println(bToC(new B(5, 5)).total) - - // No implicits required - println(new C(5, 5, 10).total) - } - - object T2Translated { - implicit def toA(n: Int): A = new A(n) - implicit def aToB[A1](a: A1)(implicit f: A1 => A): B = - new B(a.n, a.n) - implicit def bToC[B1](b: B1)(implicit f: B1 => B): C = - new C(b.m, b.n, b.m + b.n) - - // Scala does this - println(bToC(5)(x => aToB(x)(y => toA(y))).total) - println(bToC(new A(5))(x => aToB(x)(identity)).total) - println(bToC(new B(5, 5))(identity).total) - - // no implicits required - println(new C(5, 5, 10).total) - } - -So, while `bToC` is being used as an implicit conversion, `aToB` and `toA` are -being passed as _implicit parameters_, instead of being chained as implicit -conversions. - -See also: - -* [Context bounds](context-bounds.html) -* [A discussion on types, origin and precedence of implicits](finding-implicits.html) - -This question and answer were originally submitted on [Stack Overflow][1]. - - [1]: http://stackoverflow.com/questions/5332801/how-can-i-chain-implicits-in-scala/5332804 diff --git a/_overviews/FAQ/collections.md b/_overviews/FAQ/collections.md deleted file mode 100644 index 97ad5520a1..0000000000 --- a/_overviews/FAQ/collections.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -layout: multipage-overview -title: How are the collections structured? Which one should I choose? - -discourse: true - -overview-name: FAQ -partof: FAQ - -num: 8 -permalink: /tutorials/FAQ/:title.html ---- -## Foreword - -There's a [2.8 collection walk-through][1] by Martin Odersky which should -probably be your first reference. It has been supplemented as well with -[architectural notes][2], which will be of particular interest to those who -want to design their own collections. - -The rest of this answer was written way before any such thing existed (in fact, -before 2.8.0 itself was released). - -You can find a paper about it as [Scala SID #3][3]. Other papers in that area -should be interesting as well to people interested in the differences between -Scala 2.7 and 2.8. - -I'll quote from the paper, selectively, and complement with some thoughts of -mine. There are also some images, generated by Matthias at decodified.com, and -the original SVG files can be found [here][4]. - -## The collection classes/traits themselves - -There are actually three hierarchies of traits for the collections: one for -mutable collections, one for immutable collections, and one which doesn't make -any assumptions about the collections. - -There's also a distinction between parallel, serial and maybe-parallel -collections, which was introduced with Scala 2.9. I'll talk about them in the -next section. The hierarchy described in this section refers _exclusively to -non-parallel collections_. - -The following image shows the non-specific hierarchy introduced with Scala 2.8: -![General collection hierarchy][5] - -All elements shown are traits. In the other two hierarchies there are also -classes directly inheriting the traits as well as classes which can be _viewed -as_ belonging in that hierarchy through implicit conversion to wrapper classes. -The legend for these graphs can be found after them. - -Graph for immutable hierarchy: - - -Graph for mutable hierarchy: - - -Legend: - -![Graph legend][8] - -Here's an abbreviated ASCII depiction of the collection hierarchy, for those who can't see the images. - - Traversable - | - | - Iterable - | - +------------------+--------------------+ - Map Set Seq - | | | - | +----+----+ +-----+------+ - Sorted Map SortedSet BitSet Buffer Vector LinearSeq - - -## Parallel Collections - -When Scala 2.9 introduced parallel collections, one of the design goals was to -make their use as seamless as possible. In the simplest terms, one can replace -a non-parallel (serial) collection with a parallel one, and instantly reap the -benefits. - -However, since all collections until then were serial, many algorithms using -them assumed and depended on the fact that they _were_ serial. Parallel -collections fed to the methods with such assumptions would fail. For this -reason, all the hierarchy described in the previous section _mandates serial -processing_. - -Two new hierarchies were created to support the parallel collections. - -The parallel collections hierarchy has the same names for traits, but preceded -with `Par`: `ParIterable`, `ParSeq`, `ParMap` and `ParSet`. Note that there is -no `ParTraversable`, since any collection supporting parallel access is capable -of supporting the stronger `ParIterable` trait. It doesn't have some of the -more specialized traits present in the serial hierarchy either. This whole -hierarchy is found under the directory `scala.collection.parallel`. - -The classes implementing parallel collections also differ, with `ParHashMap` -and `ParHashSet` for both mutable and immutable parallel collections, plus -`ParRange` and `ParVector` implementing `immutable.ParSeq` and `ParArray` -implementing `mutable.ParSeq`. - -Another hierarchy also exists that mirrors the traits of serial and parallel -collections, but with a prefix `Gen`: `GenTraversable`, `GenIterable`, -`GenSeq`, `GenMap` and `GenSet`. These traits are _parents_ to both parallel -and serial collections. This means that a method taking a `Seq` cannot receive -a parallel collection, but a method taking a `GenSeq` is expected to work with -both serial and parallel collections. - -Given the way these hierarchies were structured, code written for Scala 2.8 was -fully compatible with Scala 2.9, and demanded serial behavior. Without being -rewritten, it cannot take advantage of parallel collections, but the changes -required are very small. - -### Using Parallel Collections - -Any collection can be converted into a parallel one by calling the method `par` -on it. Likewise, any collection can be converted into a serial one by calling -the method `seq` on it. - -If the collection was already of the type requested (parallel or serial), no -conversion will take place. If one calls `seq` on a parallel collection or -`par` on a serial collection, however, a new collection with the requested -characteristic will be generated. - -Do not confuse `seq`, which turns a collection into a non-parallel collection, -with `toSeq`, which returns a `Seq` created from the elements of the -collection. Calling `toSeq` on a parallel collection will return a `ParSeq`, -not a serial collection. - -## The Main Traits - -While there are many implementing classes and subtraits, there are some basic -traits in the hierarchy, each of which providing more methods or more specific -guarantees, but reducing the number of classes that could implement them. - -In the following subsections, I'll give a brief description of the main traits -and the idea behind them. - -### Trait TraversableOnce - -This trait is pretty much like trait `Traversable` described below, but with -the limitation that you can only use it _once_. That is, any methods called on -a `TraversableOnce` _may_ render it unusable. - -This limitation makes it possible for the same methods to be shared between the -collections and `Iterator`. This makes it possible for a method that works with -an `Iterator` but not using `Iterator`-specific methods to actually be able to -work with any collection at all, plus iterators, if rewritten to accept -`TraversableOnce`. - -Because `TraversableOnce` unifies collections and iterators, and iterators are -not considered collections, it does not appear in the previous graphs, which -concern themselves only with collections. - -### Trait Traversable - -At the top of the _collection_ hierarchy is trait `Traversable`. Its only -abstract operation is - - def foreach[U](f: Elem => U) - -The operation is meant to traverse all elements of the collection, and apply -the given operation f to each element. The application is done for its side -effect only; in fact any function result of f is discarded by foreach. - -Traversible objects can be finite or infinite. An example of an infinite -traversable object is the stream of natural numbers `Stream.from(0)`. The -method `hasDefiniteSize` indicates whether a collection is possibly infinite. -If `hasDefiniteSize` returns true, the collection is certainly finite. If it -returns false, the collection has not been not fully elaborated yet, so it -might be infinite or finite. - -This class defines methods which can be efficiently implemented in terms of -`foreach` (over 40 of them). - -### Trait Iterable - -This trait declares an abstract method `iterator` that returns an iterator that -yields all the collection’s elements one by one. The `foreach` method in -`Iterable` is implemented in terms of `iterator`. Subclasses of `Iterable` -often override foreach with a direct implementation for efficiency. - -Class `Iterable` also adds some less-often used methods to `Traversable`, which -can be implemented efficiently only if an `iterator` is available. They are -summarized below. - - xs.iterator An iterator that yields every element in xs, in the same order as foreach traverses elements. - xs takeRight n A collection consisting of the last n elements of xs (or, some arbitrary n elements, if no order is defined). - xs dropRight n The rest of the collection except xs takeRight n. - xs sameElements ys A test whether xs and ys contain the same elements in the same order - -### Seq, Set and Map - -After `Iterable` there come three base traits which inherit from it: `Seq`, -`Set`, and `Map`. All three have an `apply` method and all three implement the -`PartialFunction` trait, but the meaning of `apply` is different in each case. - -I trust the meaning of `Seq`, `Set` and `Map` is intuitive. After them, the -classes break up in specific implementations that offer particular guarantees -with regards to performance, and the methods it makes available as a result of -it. Also available are some traits with further refinements, such as -`LinearSeq`, `IndexedSeq` and `SortedSet`. - -## Complete Overview - -### Base Classes and Traits - -* `TraversableOnce` -- All methods and behavior common to collections and iterators. - - * `Traversable` -- Basic collection class. Can be implemented just with `foreach`. - - * `TraversableProxy` -- Proxy for a `Traversable`. Just point `self` to the real collection. - * `TraversableView` -- A Traversable with some non-strict methods. - * `TraversableForwarder` -- Forwards most methods to `underlying`, except `toString`, `hashCode`, `equals`, `stringPrefix`, `newBuilder`, `view` and all calls creating a new iterable object of the same kind. - * `mutable.Traversable` and `immutable.Traversable` -- same thing as `Traversable`, but restricting the collection type. - * Other special-cases `Iterable` classes, such as `MetaData`, exists. - * `Iterable` -- A collection for which an `Iterator` can be created (through `iterator`). - * `IterableProxy`, `IterableView`, `mutable` and `immutable.Iterable`. - - * `Iterator` -- A trait which is not descendant of `Traversable`. Define `next` and `hasNext`. - * `CountedIterator` -- An `Iterator` defining `count`, which returns the elements seen so far. - * `BufferedIterator` -- Defines `head`, which returns the next element without consuming it. - * Other special-cases `Iterator` classes, such as `Source`, exists. - -### The Sequences - -* `Seq` -- A sequence of elements. One assumes a well-defined size and element repetition. Extends `PartialFunction` as well. - - * `IndexedSeq` -- Sequences that support O(1) element access and O(1) length computation. - * `IndexedSeqView` - * `immutable.PagedSeq` -- An implementation of `IndexedSeq` where the elements are produced on-demand by a function passed through the constructor. - * `immutable.IndexedSeq` - - * `immutable.Range` -- A delimited sequence of integers, closed on the lower end, open on the high end, and with a step. - * `immutable.Range.Inclusive` -- A `Range` closed on the high end as well. - * `immutable.NumericRange` -- A more generic version of `Range` which works with any `Integral`. - * `immutable.NumericRange.Inclusive`, `immutable.NumericRange.Exclusive`. - * `immutable.WrappedString`, `immutable.RichString` -- Wrappers which enables seeing a `String` as a `Seq[Char]`, while still preserving the `String` methods. I'm not sure what the difference between them is. - - * `mutable.IndexedSeq` - * `mutable.GenericArray` -- An `Seq`-based array-like structure. Note that the "class" `Array` is Java's `Array`, which is more of a memory storage method than a class. - * `mutable.ResizableArray` -- Internal class used by classes based on resizable arrays. - * `mutable.PriorityQueue`, `mutable.SynchronizedPriorityQueue` -- Classes implementing prioritized queues -- queues where the elements are dequeued according to an `Ordering` first, and order of queueing last. - * `mutable.PriorityQueueProxy` -- an abstract `Proxy` for a `PriorityQueue`. - - * `LinearSeq` -- A trait for linear sequences, with efficient time for `isEmpty`, `head` and `tail`. - - * `immutable.LinearSeq` - * `immutable.List` -- An immutable, singlely-linked, list implementation. - * `immutable.Stream` -- A lazy-list. Its elements are only computed on-demand, but memoized (kept in memory) afterwards. It can be theoretically infinite. - * `mutable.LinearSeq` - * `mutable.DoublyLinkedList` -- A list with mutable `prev`, `head` (`elem`) and `tail` (`next`). - * `mutable.LinkedList` -- A list with mutable `head` (`elem`) and `tail` (`next`). - * `mutable.MutableList` -- A class used internally to implement classes based on mutable lists. - * `mutable.Queue`, `mutable.QueueProxy` -- A data structure optimized for FIFO (First-In, First-Out) operations. - * `mutable.QueueProxy` -- A `Proxy` for a `mutable.Queue`. - - * `SeqProxy`, `SeqView`, `SeqForwarder` - - * `immutable.Seq` - - * `immutable.Queue` -- A class implementing a FIFO-optimized (First-In, First-Out) data structure. There is no common superclass of both `mutable` and `immutable` queues. - * `immutable.Stack` -- A class implementing a LIFO-optimized (Last-In, First-Out) data structure. There is no common superclass of both `mutable` `immutable` stacks. - * `immutable.Vector` -- ? - * `scala.xml.NodeSeq` -- A specialized XML class which extends `immutable.Seq`. - * `immutable.IndexedSeq` -- As seen above. - * `immutable.LinearSeq` -- As seen above. - - * `mutable.ArrayStack` -- A class implementing a LIFO-optimized data structure using arrays. Supposedly significantly faster than a normal stack. - * `mutable.Stack`, `mutable.SynchronizedStack` -- Classes implementing a LIFO-optimized data structure. - * `mutable.StackProxy` -- A `Proxy` for a `mutable.Stack`.. - * `mutable.Seq` - - * `mutable.Buffer` -- Sequence of elements which can be changed by appending, prepending or inserting new members. - * `mutable.ArrayBuffer` -- An implementation of the `mutable.Buffer` class, with constant amortized time for the append, update and random access operations. It has some specialized subclasses, such as `NodeBuffer`. - * `mutable.BufferProxy`, `mutable.SynchronizedBuffer`. - * `mutable.ListBuffer` -- A buffer backed by a list. It provides constant time append and prepend, with most other operations being linear. - * `mutable.ObservableBuffer` -- A *mixin* trait which, when mixed to a `Buffer`, provides notification events through a `Publisher` interfaces. - * `mutable.IndexedSeq` -- As seen above. - * `mutable.LinearSeq` -- As seen above. - -### The Sets - -* `Set` -- A set is a collection that includes at most one of any object. - - * `BitSet` -- A set of integers stored as a bitset. - * `immutable.BitSet` - * `mutable.BitSet` - - * `SortedSet` -- A set whose elements are ordered. - * `immutable.SortedSet` - * `immutable.TreeSet` -- An implementation of a `SortedSet` based on a tree. - - * `SetProxy` -- A `Proxy` for a `Set`. - - * `immutable.Set` - * `immutable.HashSet` -- An implementation of `Set` based on element hashing. - * `immutable.ListSet` -- An implementation of `Set` based on lists. - * Additional set classes exists to provide optimized implementations for sets from 0 to 4 elements. - * `immutable.SetProxy` -- A `Proxy` for an immutable `Set`. - - * `mutable.Set` - * `mutable.HashSet` -- An implementation of `Set` based on element hashing. - * `mutable.ImmutableSetAdaptor` -- A class implementing a mutable `Set` from an immutable `Set`. - * `LinkedHashSet` -- An implementation of `Set` based on lists. - * `ObservableSet` -- A *mixin* trait which, when mixed with a `Set`, provides notification events through a `Publisher` interface. - * `SetProxy` -- A `Proxy` for a `Set`. - * `SynchronizedSet` -- A *mixin* trait which, when mixed with a `Set`, provides notification events through a `Publisher` interface. - -### The Maps - -* `Map` -- An `Iterable` of `Tuple2`, which also provides methods for retrieving a value (the second element of the tuple) given a key (the first element of the tuple). Extends `PartialFunction` as well. - * `MapProxy` -- A `Proxy` for a `Map`. - * `DefaultMap` -- A trait implementing some of `Map`'s abstract methods. - * `SortedMap` -- A `Map` whose keys are sorted. - * `immutable.SortMap` - * `immutable.TreeMap` -- A class implementing `immutable.SortedMap`. - * `immutable.Map` - * `immutable.MapProxy` - * `immutable.HashMap` -- A class implementing `immutable.Map` through key hashing. - * `immutable.IntMap` -- A class implementing `immutable.Map` specialized for `Int` keys. Uses a tree based on the binary digits of the keys. - * `immutable.ListMap` -- A class implementing `immutable.Map` through lists. - * `immutable.LongMap` -- A class implementing `immutable.Map` specialized for `Long` keys. See `IntMap`. - * There are additional classes optimized for an specific number of elements. - * `mutable.Map` - * `mutable.HashMap` -- A class implementing `mutable.Map` through key hashing. - * `mutable.ImmutableMapAdaptor` -- A class implementing a `mutable.Map` from an existing `immutable.Map`. - * `mutable.LinkedHashMap` -- ? - * `mutable.ListMap` -- A class implementing `mutable.Map` through lists. - * `mutable.MultiMap` -- A class accepting more than one distinct value for each key. - * `mutable.ObservableMap` -- A *mixin* which, when mixed with a `Map`, publishes events to observers through a `Publisher` interface. - * `mutable.OpenHashMap` -- A class based on an open hashing algorithm. - * `mutable.SynchronizedMap` -- A *mixin* which should be mixed with a `Map` to provide a version of it with synchronized methods. - * `mutable.MapProxy`. - -## Bonus Questions - -* Why the Like classes exist (e.g. TraversableLike)? - -This was done to achieve maximum code reuse. The concrete *generic* -implementation for classes with a certain structure (a traversable, a map, etc) -is done in the Like classes. The classes intended for general consumption, -then, override selected methods that can be optmized. - -* What the companion methods are for (e.g. List.companion)? - -The builder for the classes, ie, the object which knows how to create instances -of that class in a way that can be used by methods like `map`, is created by a -method in the companion object. So, in order to build an object of type X, I -need to get that builder from the companion object of X. Unfortunately, there -is no way, in Scala, to get from class X to object X. Because of that, there is -a method defined in each instance of X, `companion`, which returns the -companion object of class X. - -While there might be some use for such method in normal programs, its target is -enabling code reuse in the collection library. - -* How I know what implicit objects are in scope at a given point? - -You aren't supposed to care about that. They are implicit precisely so that you -don't need to figure out how to make it work. - -These implicits exists to enable the methods on the collections to be defined -on parent classes but still return a collection of the same type. For example, -the `map` method is defined on `TraversableLike`, but if you used on a `List` -you'll get a `List` back. - -This answer was originally submitted in response to [this question][9] on Stack -Overflow. - - - [1]: http://docs.scala-lang.org/overviews/collections/introduction.html - [2]: http://docs.scala-lang.org/overviews/core/architecture-of-scala-collections.html - [3]: http://www.scala-lang.org/sid/3 - [4]: https://github.com/sirthias/scala-collections-charts/downloads - [5]: http://i.stack.imgur.com/bSVyA.png - [6]: http://i.stack.imgur.com/2fjoA.png - [7]: http://i.stack.imgur.com/Dsptl.png - [8]: http://i.stack.imgur.com/szWUr.png - [9]: http://stackoverflow.com/q/1722137/53013 diff --git a/_overviews/FAQ/context-bounds.md b/_overviews/FAQ/context-bounds.md deleted file mode 100644 index fa0beaaaa6..0000000000 --- a/_overviews/FAQ/context-bounds.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -layout: multipage-overview -title: What are Scala context bounds? - -discourse: true - -overview-name: FAQ -partof: FAQ - -num: 3 -permalink: /tutorials/FAQ/:title.html ---- - -What is a Context Bound? ------------------------- - -Context bounds were introduced in Scala 2.8.0, and are typically used with the -so-called _type class pattern_, a pattern of code that emulates the -functionality provided by Haskell type classes, though in a more verbose -manner. - -A context bound requires a _parameterized type_, such as `Ordered[A]`, -but unlike `String`. - -A context bound describes an implicit _value_. It is used to declare that for -some type `A`, there is an -implicit value of type `B[A]` available. The syntax goes like this: - - def f[A : B](a: A) = g(a) // where g requires an implicit value of type B[A] - -The common example of usage in Scala is this: - - def f[A : ClassTag](n: Int) = new Array[A](n) - -An `Array` initialization on a parameterized type requires a `ClassTag` to -be available, for arcane reasons related to type erasure and the non-erasure -nature of arrays. - -Another very common example in the library is a bit more complex: - - def f[A : Ordering](a: A, b: A) = implicitly[Ordering[A]].compare(a, b) - -Here, `implicitly` is used to retrive the implicit value we want, one of type -`Ordering[A]`, which class defines the method `compare(a: A, b: A): Int`. - -We'll see another way of doing this below. - -How are Context Bounds implemented? ---------------------------------------------------- - -It shouldn't be surprising that context bounds are -implemented with implicit parameters, given their definition. Actually, the -syntax I showed are syntactic sugars for what really happens. See below how -they de-sugar: - - def g[A : B](a: A) = h(a) - def g[A](a: A)(implicit ev: B[A]) = h(a) - -So, naturally, one can write them in their full syntax, which is specially -useful for context bounds: - - def f[A](a: A, b: A)(implicit ord: Ordering[A]) = ord.compare(a, b) - -What are Context Bounds used for? ---------------------------------- - -Context bounds are mainly used in what has become known as _typeclass pattern_, -as a reference to Haskell's type classes. Basically, this pattern implements an -alternative to inheritance by making functionality available through a sort of -implicit adapter pattern. - -The classic example is Scala 2.8's `Ordering`. The usage is: - - def f[A : Ordering](a: A, b: A) = if (implicitly[Ordering[A]].lt(a, b)) a else b - -Though you'll usually see that written like this: - - def f[A](a: A, b: A)(implicit ord: Ordering[A]) = { - import ord._ - if (a < b) a else b - } - -Which take advantage of some implicit conversions inside `Ordering` that enable -the traditional operator style. Another example in Scala 2.8 is the `Numeric`: - - def f[A : Numeric](a: A, b: A) = implicitly[Numeric[A]].plus(a, b) - -A more complex example is the new collection usage of `CanBuildFrom`, but -there's already a very long answer about that, so I'll avoid it here. And, as -mentioned before, there's the `ClassTag` usage, which is required to -initialize new arrays without concrete types. - -Though it has been possible for a long time, the use of context bounds has -really taken off in 2010, and is now found to some degree in most of Scala's -most important libraries and frameworks. The most extreme example of its usage, -though, is the Scalaz library, which brings a lot of the power of Haskell to -Scala. I recommend reading up on typeclass patterns to get more acquainted it -all the ways in which it can be used. - -Related questions of interest: - -* [A discussion on types, origin and precedence of implicits](finding-implicits.html) -* [Chaining implicits](chaining-implicits.html) - -This answer was originally submitted in response to [this question on Stack Overflow][1]. - - [1]: http://stackoverflow.com/q/4465948/53013 diff --git a/_overviews/FAQ/finding-implicits.md b/_overviews/FAQ/finding-implicits.md deleted file mode 100644 index c12d7b2748..0000000000 --- a/_overviews/FAQ/finding-implicits.md +++ /dev/null @@ -1,418 +0,0 @@ ---- -layout: multipage-overview -title: Where does Scala look for implicits? - -discourse: true - -overview-name: FAQ -partof: FAQ - -num: 7 -permalink: /tutorials/FAQ/:title.html ---- - -Newcomers to Scala often ask: Where does the compiler look for implicits? - -For example, where do the values for `integral` below come from? - - scala> import scala.math._ - import scala.math._ - - scala> def foo[T](t: T)(implicit integral: Integral[T]): Unit = { - println(integral) - } - foo: [T](t: T)(implicit integral: scala.math.Integral[T])Unit - - scala> foo(0) - scala.math.Numeric$IntIsIntegral$@3dbea611 - - scala> foo(0L) - scala.math.Numeric$LongIsIntegral$@48c610af - -The natural continuation of this line of inquiry leads to a second question: How -does the compiler choose which implicit to use, in certain situations of apparent -ambiguity (but that compile anyway)? - -For instance, `scala.Predef` defines two conversions from `String`: one to -`WrappedString` and another to `StringOps`. Both classes, however, share a lot -of methods, so why doesn't Scala complain about ambiguity when, say, calling -`map`? - -**Note:** this question was inspired by [this other question on Stack -Overflow][4], but states the problem in more general terms. The example was -copied from there, because it is referred to in the answer. - -## Types of Implicits - -Implicits in Scala refers to either a value that can be passed "automatically", -so to speak, or a conversion from one type to another that is made -automatically. - -### Implicit Conversion - -Speaking very briefly about the latter type, if one calls a method `m` on an -object `o` of a class `C`, and that class does not support method `m`, then -Scala will look for an implicit conversion from `C` to something that _does_ -support `m`. A simple example would be the method `map` on `String`: - - "abc".map(_.toInt) - -`String` does not support the method `map`, but `StringOps` does, and there's -an implicit conversion from `String` to `StringOps` available (see `implicit -def augmentString` on `Predef`). - -### Implicit Parameters - -The other kind of implicit is the implicit _parameter_. These are passed to -method calls like any other parameter, but the compiler tries to fill them in -automatically. If it can't, it will complain. One _can_ pass these parameters -explicitly, which is how one uses `breakOut`, for example (see question about -`breakOut`, on a day you are feeling up for a challenge). - -In this case, one has to declare the need for an implicit, such as the `foo` -method declaration: - - def foo[T](t: T)(implicit integral: Integral[T]): Unit = { - println(integral) - } - -### Implicit conversions as implicit parameters - -There's one situation where an implicit is both an implicit conversion and an -implicit parameter. For example: - - def getIndex[T, CC](seq: CC, value: T)(implicit conv: CC => Seq[T]) = seq.indexOf(value) - - getIndex("abc", 'a') - -The method `getIndex` can receive any object, as long as there is an implicit -conversion available from its class to `Seq[T]`. Because of that, a `String` can be -passed to `getIndex`, and it will work. - -Behind the scenes, the compiler changes `seq.IndexOf(value)` to -`conv(seq).indexOf(value)`. - -### Context Bounds - -Another common pattern in implicit parameters is the _type class pattern_. This -pattern enables the provision of common interfaces to classes which did not -declare them. It can both serve as a bridge pattern -- gaining separation of -concerns -- and as an adapter pattern. - -The `Integral` class mentioned above is a classic example of type class pattern. -Another example on Scala's standard library is `Ordering`. Scalaz is a library -that makes heavy use of this pattern. - -This is an example of its use: - - def sum[T](list: List[T])(implicit integral: Integral[T]): T = { - import integral._ // get the implicits in question into scope - list.foldLeft(integral.zero)(_ + _) - } - -There is also a syntactic sugar for it, called a _context bound_, which is made -less useful by the need to refer to the implicit. A straight conversion of that -method looks like this: - - def sum[T : Integral](list: List[T]): T = { - val integral = implicitly[Integral[T]] - import integral._ // get the implicits in question into scope - list.foldLeft(integral.zero)(_ + _) - } - -Context bounds are more useful when you just need to _pass_ them to other -methods that use them. For example, the method `sorted` on `Seq` needs an -implicit `Ordering`. To create a method `reverseSort`, one could write: - - def reverseSort[T : Ordering](seq: Seq[T]) = seq.reverse.sorted - -Because `Ordering[T]` was implicitly passed to `reverseSort`, it can then pass -it implicitly to `sorted`. - -## Where do Implicits Come From? - -As described above, there are several contexts in which an implicit value may be required -for an expression to typecheck. The required implicit type is what determines -which value is selected. That value is found either in lexical scope or, -failing that, in what is called implicit scope. - -### Implicits Defined in Lexical Scope - -When a value of a certain name is required, lexical scope is searched for -a value with that name. Similarly, when an implicit value of a certain type is required, -lexical scope is searched for a value with that type. - -Any such value which can be referenced with its "simple" name, without -selecting from another value using dotted syntax, is an eligible implicit value. - -For example, here is a function that takes an implicit scaling factor. -The function requires a parameter of type `Int`, and there is a value -of that type in scope. The variable name `n` does not matter in this -case. - - implicit val n: Int = 5 - def scale(x: Int)(implicit y: Int) = x * y - scale(5) // takes n from the current scope, with the result 25 - -The invocation can be rewritten `scale(5)(n)`. If `n` can be referenced -using its simple name, as shown here, it is eligible as an implicit value. - -An implicit value can be introduced into scope by an import statement: - - import scala.collection.JavaConverters._ - def env = System.getenv().asScala // extension method enabled by imported implicit - val term = env("TERM") // it's a Scala Map - -There may be more than one such value because they have different names. - -In that case, overload resolution is used to pick one of them. The algorithm -for overload resolution is the same used to choose the reference for a -given name, when more than one term in scope has that name. For example, -`println` is overloaded, and each overload takes a different parameter type. -An invocation of `println` requires selecting the correct overloaded method. - -In implicit search, overload resolution chooses a value among more than one -that have the same required type. Usually this entails selecting a narrower -type or a value defined in a subclass relative to other eligible values. - -The rule that the value must be accessible using its simple name means -that the normal rules for name binding apply. - -In summary, a definition for `x` shadows a definition in -an enclosing scope. But a binding for `x` can also be introduced by -local imports. Imported symbols can't override definitions of the same -name in an enclosing scope. Similarly, wildcard imports can't override -an import of a specific name, and names in the current package that are -visible from other source files can't override imports or local definitions. - -These are the normal rules for deciding what `x` means in a given context, -and also determine which value `x` is accessible by its simple name and -is eligible as an implicit. - -This means that an implicit in scope can be disabled by shadowing it with -a term of the same name. - -For example, here, `X.f` is supplied the imported `X.s`: `X.f(s)`. -The body of `f` uses an implicit `Int`, from the immediate scope, -which shadows the `n` from `Y`, which is therefore not an eligible -implicit value. The parameter `s` shadows the member `s`. - -The method `g` does not compile because the implicit `t` is shadowed -by a `t` that is not implicit, so no implicit `T` is in scope. - - object Y { - implicit val n: Int = 17 - trait T { - implicit val i: Int = 17 - implicit def t: T = ??? - } - object X extends T { - implicit val n: Int = 42 - implicit val s: String = "hello, world\n" - def f(implicit s: String) = implicitly[String] * implicitly[Int] - override def t: T = ??? - def g = implicitly[T] - } - } - import Y.X._ - f - -The invocation of `f` was enabled by importing from `Y.X.`. But it is -not convenient to require an import to access implicit values -providied by a package. - -If an implicit value is not found in lexical scope, implicit search -continues in implicit scope. - -### Implicits Defined in Implicit Scope - -Implicit syntax can avoid the [import tax][1], which of course is a "sin tax," -by leveraging "implicit scope", which depends on the type of the implicit -instead of imports in lexical scope. - -When an implicit of type `T` is required, implicit scope includes -the companion object `T`: - - trait T - object T { implicit val t: T = new T { } } - -When an `F[T]` is required, implicit scope includes both the companion -of `F` and the companion of the type argument, e.g., `object C` for `F[C]`. - -In addition, implicit scope includes the companions of the base classes -of `F` and `C`, including package objects, such as `p` for `p.F`. - -### Companion Objects of a Type - -There are two object companions of note here. First, the object companion of -the "source" type is looked into. For instance, inside the object `Option` -there is an implicit conversion to `Iterable`, so one can call `Iterable` -methods on `Option`, or pass `Option` to something expecting an `Iterable`. For -example: - - for { - x <- List(1, 2, 3) - y <- Some('x') - } yield (x, y) - -That expression is translated by the compiler into - - List(1, 2, 3).flatMap(x => Some('x').map(y => (x, y))) - -However, `List.flatMap` expects a `TraversableOnce`, which `Option` is not. The -compiler then looks inside `Option`'s object companion and finds the conversion -to `Iterable`, which is a `TraversableOnce`, making this expression correct. - -Second, the companion object of the expected type: - - List(1, 2, 3).sorted - -The method `sorted` takes an implicit `Ordering`. In this case, it looks inside -the object `Ordering`, companion to the class `Ordering`, and finds an implicit -`Ordering[Int]` there. - -Note that companion objects of super classes are also looked into. For example: - - class A(val n: Int) - object A { - implicit def str(a: A) = "A: %d" format a.n - } - class B(val x: Int, y: Int) extends A(y) - val b = new B(5, 2) - val s: String = b // s == "A: 2" - -This is how Scala found the implicit `Numeric[Int]` and `Numeric[Long]` in the -opening example, by the way, as they are found inside `Numeric`, not `Integral`. - -### Implicit scope of an argument's type - -If you have a method with an argument type `A`, then the implicit scope of type -`A` will also be considered. Here "implicit scope" means all these rules -will be applied recursively -- for example, the companion object of `A` will be -searched for implicits, as per the rule above. - -Note that this does not mean the implicit scope of `A` will be searched for -conversions of that parameter alone, but of the whole expression. For example: - - class A(val n: Int) { - def +(other: A) = new A(n + other.n) - } - object A { - implicit def fromInt(n: Int) = new A(n) - } - - // This becomes possible: - 1 + new A(1) - // because it is converted into this: - A.fromInt(1) + new A(1) - -### Implicit scope of type arguments - -This is required to make the type class pattern really work. Consider -`Ordering`, for instance... it comes with some implicits in its companion -object, but you can't add stuff to it. So how can you make an `Ordering` for -your own class that is automatically found? - -Let's start with the implementation: - - class A(val n: Int) - object A { - implicit val ord = new Ordering[A] { - def compare(x: A, y: A) = implicitly[Ordering[Int]].compare(x.n, y.n) - } - } - -So, consider what happens when you call - - List(new A(5), new A(2)).sorted - -As we saw, the method `sorted` expects an `Ordering[A]` (actually, it expects -an `Ordering[B]`, where `B >: A`). There isn't any such thing inside -`Ordering`, and there is no "source" type on which to look. Obviously, it is -finding it inside `A`, which is a _type argument_ of `Ordering`. - -This is also how various collection methods expecting `CanBuildFrom` work: the -implicits are found inside companion objects to the type parameters of -`CanBuildFrom`. - -**Note**: `Ordering` is defined as `trait Ordering[T]`, where `T` is a type -parameter. The implicit looked for above is `Ordering[A]`, where -`A` is an actual type, not type parameter: it is a _type argument_ to -`Ordering`. See section 7.2 of the [Scala Specification][6]. - -### Outer Objects for Nested Types - -The principle is simple: - - class A(val n: Int) { - class B(val m: Int) { require(m < n) } - } - object A { - implicit def bToString(b: A#B) = "B: %d" format b.m - } - val a = new A(5) - val b = new a.B(3) - val s: String = b // s == "B: 3" - -A real world example of this would be welcome. Please share your example! - -### Package Objects Can Contribute Implicit Values - -An implicit value in a package object can be made available either -in lexical scope or in implicit scope. - -To be available in lexical scope, the packages must be declared as nested packages: - - package object p { implicit val s: String = "hello, world" } - package p { - package q { - object X { def f = implicitly[String] } - } - } - -This is sensitive to name binding rules. The following example compiles -only if the package object is in a separate file, in which case the import is used: - - package object p { implicit val s: String = "hello, world" } - package p { - package q { - object Y { - implicit val s: String = "bye" - } - object X { - import Y._ - def f = implicitly[String] - } - } - } - -A package object can also offer implicit values of types in subpackages: - - package object p { implicit val c: q.C = new q.C } - package p.q { - class C - object X { def f = implicitly[C] } - } - -Here, the implicit is supplied in implicit scope of `C`. - -### Call To Action - -Avoid taking this question as being the final arbiter of what is happening. -If you do notice it has become out-of-date, do [open a ticket about it][7], or, if -you know how to correct it, please fix it. - -Related questions of interest: - -* [Context bounds](context-bounds.html) -* [Chaining implicits](chaining-implicits.html) - -This question and answer were originally submitted on [Stack Overflow][3]. - - [1]: http://jsuereth.com/scala/2011/02/18/2011-implicits-without-tax.html - [2]: https://issues.scala-lang.org/browse/SI-4427 - [3]: http://stackoverflow.com/q/5598085/53013 - [4]: http://stackoverflow.com/questions/5512397/passing-scala-math-integral-as-implicit-parameter - [5]: http://scala-lang.org/files/archive/spec/2.11/06-expressions.html - [6]: http://scala-lang.org/files/archive/spec/2.11/07-implicits.html - [7]: https://github.com/scala/docs.scala-lang/issues diff --git a/_overviews/FAQ/finding-symbols.md b/_overviews/FAQ/finding-symbols.md deleted file mode 100644 index 0512856737..0000000000 --- a/_overviews/FAQ/finding-symbols.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -layout: multipage-overview -title: How do I find what some symbol means or does? - -discourse: true - -overview-name: FAQ -partof: FAQ - -num: 1 - -permalink: /tutorials/FAQ/:title.html ---- -We can divide the operators in Scala, for the purpose of teaching, into four categories: - -* Keywords/reserved symbols -* Normal methods or values -* Methods provided by implicit conversion -* Syntactic sugars/composition - -And let's see some arbitrary examples: - - <- // Keyword - -> // Method provided by implicit conversion - <= // Common method - ++= // Can be a common method or syntactic sugar involving ++ method - :: // Common method or object - _+_ // Not really a single operator; it's parsed as _ + _ - -The exact meaning of most of these methods depends on the class they are defined -on. For example, `<=` on `Int` means _"less than or equal to"_, but it might -mean something else in another class. `::` in an expression is probably the method of the class -`List` but it can also refer to the object of the same name (and in a pattern it -definitely does). - -So, let's discuss these categories. - -Keywords/reserved symbols -------------------------- - -There are a few symbols in Scala that are special and cannot be defined or used as method names. -Two of them are considered proper keywords, while others are just "reserved". They are: - - // Keywords - <- // Used on for-comprehensions, to separate pattern from generator - => // Used for function types, function literals and import renaming - - // Reserved - ( ) // Delimit expressions and parameters - [ ] // Delimit type parameters - { } // Delimit blocks - . // Method call and path separator - // /* */ // Comments - # // Used in type notations - : // Type ascription or context bounds - <: >: // Upper and lower bounds - <% // View bounds (deprecated) - " """ // Strings - ' // Indicate symbols and characters - @ // Annotations and variable binding on pattern matching - ` // Denote constant or enable arbitrary identifiers - , // Parameter separator - ; // Statement separator - _* // vararg expansion - _ // Many different meanings - -These are all _part of the language_, and, as such, can be found in any text -that properly describe the language, such as [Scala Specification][1](PDF) -itself. - -The last one, the underscore, deserve a special description, because it is -widely used, and has different meanings depending on the context. Here's a sample: - - import scala._ // Wild card -- all of Scala is imported - import scala.{ Predef => _, _ } // Exclusion, everything except Predef - def f[M[_]] // Higher kinded type parameter - def f(m: M[_]) // Existential type - _ + _ // Anonymous function placeholder parameter - m _ // Eta expansion of method into method value - m(_) // Partial function application - _ => 5 // Discarded parameter - case _ => // Wild card pattern -- matches anything - f(xs: _*) // Sequence xs is passed as multiple parameters to f(ys: T*) - case Seq(xs @ _*) // Identifier xs is bound to the whole matched sequence - -Common methods --------------- - -Many symbols are simply methods of a class, a trait, or an object. For instance, if you do - - List(1, 2) ++ List(3, 4) - -You'll find the method `++` right on the Scaladoc for [List][5]. However, -there's one convention that you must be aware when searching for methods. -Methods ending in colon (`:`) bind _to the right_ instead of the left. In other -words, while the above method call is equivalent to: - - List(1, 2).++(List(3, 4)) - -If I had, instead `1 :: List(2, 3)`, that would be equivalent to: - - List(2, 3).::(1) - -So you need to look at the type found _on the right_ when looking for methods -ending in colon. Consider, for instance: - - 1 +: List(2, 3) :+ 4 - -The first method (`+:`) binds to the right, and is found on `List`. The second -method (`:+`) is just a normal method, and binds to the left -- again, on -`List`. - -If the name ends in `=`, look for the method called the same without `=` and -read the last section. - -If you aren't sure what the type of the receiver is, you can look up the symbol -on the Scaladoc [index page for identifiers not starting with letters][2] (for -standard Scala library; of course, third-party libraries can add their own -symbolic methods, for which you should look at the corresponding page of _their_ -Scaladoc). - -Types and objects can also have symbolic names; in particular, it should be mentioned -that for types with two type parameters the name can be written _between_ parameters, -so that e.g. `Int <:< Any` is the same as `<:<[Int, Any]`. - -Methods provided by implicit conversion ---------------------------------------- - -If you did not find the symbol you are looking for in the list of reserved symbols, then -it must be a method, or part of one. But, often, you'll see some symbol and the -documentation for the class will not have that method. When this happens, -either you are looking at a composition of one or more methods with something -else, or the method has been imported into scope, or is available through an -imported implicit conversion. - -These can also be found in Scaladoc's [index][2], as mentioned above. - -All Scala code has three automatic imports: - - // Not necessarily in this order - import java.lang._ - import scala._ - import scala.Predef._ - -The first two only make classes and singleton objects available, none of which -look like operators. [`Predef`][3] is the only interesting one for this post. - -Looking inside `Predef` shows some symbolic names: - - class <:< - class =:= - object =:= - object <%< // removed in Scala 2.10 - def ??? - -There is also `::`, which doesn't appear in the Scaladoc, but is mentioned in the comments. -In addition, `Predef` makes some methods available through _implicit conversions_. Just -look at the methods and classes with `implicit` modifier that receive, as parameter, an -object of type that is receiving the method. For example, consider `"a" -> 1`. We need -to look for an implicit which works on `"a"`, and so it can take `String`, one of its -supertypes (`AnyRef` or `Any`) or a type parameter. In this case, we find -`implicit final class ArrowAssoc[A](private val self: A)` which makes this implicit -avaialable on all types. - -Other implicit conversions may be visible in your scope depending on imports, extended types or -self-type annotations. See [Finding implicits](finding-implicits.html) for details. - -Syntactic sugars/composition ------------------------------ - -So, here's a few syntactic sugars that may hide a method: - - class Example(arr: Array[Int] = Array.fill(5)(0)) { - def apply(n: Int) = arr(n) - def update(n: Int, v: Int) = arr(n) = v - def a = arr(0); def a_=(v: Int) = arr(0) = v - def b = arr(1); def b_=(v: Int) = arr(1) = v - def c = arr(2); def c_=(v: Int) = arr(2) = v - def d = arr(3); def d_=(v: Int) = arr(3) = v - def e = arr(4); def e_=(v: Int) = arr(4) = v - def +(v: Int) = new Example(arr map (_ + v)) - def unapply(n: Int) = if (arr.indices contains n) Some(arr(n)) else None - } - - val ex = new Example - println(ex(0)) // means ex.apply(0) - ex(0) = 2 // means ex.update(0, 2) - ex.b = 3 // means ex.b_=(3) - val ex(c) = 2 // calls ex.unapply(2) and assigns result to c, if it's Some; throws MatchError if it's None - ex += 1 // means ex = ex + 1; if Example had a += method, it would be used instead - -The last one is interesting, because *any* symbolic method can be combined with `=` in that way. - -And, of course, all of the above can be combined in various combinations, e.g. - - (_+_) // An expression, or parameter, that is an anonymous function with - // two parameters, used exactly where the underscores appear, and - // which calls the "+" method on the first parameter passing the - // second parameter as argument. - -This answer was originally submitted in response to [this question on Stack Overflow][6]. - - [1]: http://scala-lang.org/files/archive/spec/2.11/ - [2]: http://www.scala-lang.org/api/current/index.html#index.index-_ - [3]: http://www.scala-lang.org/api/current/index.html#scala.Predef$ - [4]: http://www.scala-lang.org/api/current/scala/Predef$$ArrowAssoc.html - [5]: http://www.scala-lang.org/api/current/index.html#scala.collection.immutable.List - [6]: http://stackoverflow.com/q/7888944/53013 diff --git a/_overviews/FAQ/index.md b/_overviews/FAQ/index.md index 417d08280d..a3aa167c98 100644 --- a/_overviews/FAQ/index.md +++ b/_overviews/FAQ/index.md @@ -1,22 +1,374 @@ --- layout: singlepage-overview -title: Scala FAQs - -discourse: true - +title: Scala FAQ permalink: /tutorials/FAQ/index.html +redirect_from: + - "/tutorials/FAQ/breakout.html" + - "/tutorials/FAQ/chaining-implicits.html" + - "/tutorials/FAQ/collections.html" + - "/tutorials/FAQ/context-bounds.html" + - "/tutorials/FAQ/finding-implicits.html" + - "/tutorials/FAQ/finding-symbols.html" + - "/tutorials/FAQ/stream-view.html" + - "/tutorials/FAQ/yield.html" --- -A collection of frequently asked questions and their answers! Graciously -provided by Daniel Sobral, adapted from his StackOverflow posts. +Frequently asked questions, with _brief_ answers and/or links to +longer answers. + +This list only includes questions that _actually_ come up over and +over again in Scala chat rooms and forums. + +## General questions + +### Where can I ask Scala questions? + +See our [Community page](https://scala-lang.org/community/). + +### What's a good book about Scala? + +Our [Books page](https://docs.scala-lang.org/books.html) lists a few +especially popular, well-known books. + +We don't have a list of all the Scala books that +are out there; there are many. + +You can go on the \#scala-users room [on +Discord](https://discord.com/invite/scala) or another community forum and +ask for book recommendations. You'll get more helpful +answers if you provide some information about your background and your +reasons for wanting to learn Scala. + +### Should I learn Scala 2, or Scala 3? + +Don't sweat the decision too much. You can't go far wrong either +way. It isn't that hard to switch later, in either direction. + +Regardless, you should choose Scala 3 unless you have a specific reason +to need 2. Scala 3 is the future, and it's the best version for +falling in love with the language and everything it has to offer. +Scala 3 has plenty of books, plenty of libraries, and high quality +tooling. + +That said, many Scala jobs are still Scala 2 jobs. In most cases, the +cause of that is simply inertia, especially at large shops. (But it can +sometimes be due to availability of specific libraries.) + +### Where are Scala jobs advertised? + +This is addressed on our [Community page](https://scala-lang.org/community/#scala-jobs). + +In short, the only officially sanctioned place is the \#jobs channel +[on Discord](https://discord.com/invite/scala). + +### Who's behind Scala? + +This is answered [on the Governance page](https://www.scala-lang.org/governance/). + +### Can I use the Scala logo? + +See [scala/scala-lang#1040](https://github.com/scala/scala-lang/issues/1040). + +## Technical questions + +### What IDEs are available for Scala? + +See [this doc page](https://docs.scala-lang.org/getting-started/scala-ides.html). + +### What compiler flags are recommended? + +The list of available options is +[here](https://docs.scala-lang.org/overviews/compiler-options/index.html). + +What flags people choose varies widely from shop to shop and from +individual to individual. `-Xlint` is valuable to enable. Some brave +people enable `-Werror` (formerly `-Xfatal-warnings`) to make warnings +fatal. + +[sbt-tpolecat](https://github.com/typelevel/sbt-tpolecat) is an +opinionated sbt plugin that sets many options automatically, depending +on Scala version; you can see +[here](https://github.com/typelevel/sbt-tpolecat/blob/main/plugin/src/main/scala/io/github/davidgregory084/TpolecatPlugin.scala) +what it sets. Some choices it makes are oriented towards +pure-functional programmers. + +### How do I find what some symbol means or does? + +A [Stack Overflow answer](https://stackoverflow.com/a/7890032) lays +out what the different kinds of symbol in Scala are and explains the +most commonly used symbols. + +Scala allows symbolic method names. So if you see a random-looking +operator like `>=@=>` in Scala code, it might simply be a method in +some library, rather than having any special meaning in the language +itself. + +You can search for symbols on Google. For example, if you want to +know what `<:<` means, searching for `scala <:<` works fine. If you +get poor results, try surrounding the symbol with double quotes. + +### I want Scala 2.13 (or some other version); why does sbt say it's using Scala 2.12? + +sbt 1.x always uses Scala 2.12 to compile build definitions. +Your sbt 1.x build definition is always a Scala 2.12 program. + +Regardless, in your `build.sbt`, you can set `scalaVersion` to whichever +available distribution you want and your program code will be compiled with that version. + +### I want Scala 3. Why does `versionNumberString` say I'm on 2.13? + +To aid migration, Scala 3 currently uses the Scala 2.13 library as-is, +with only minor supplements. That's why `versionString` and +`versionNumberString` report that Scala 2 is in use: + +``` +Welcome to Scala 3.3.4 (17.0.3, Java OpenJDK 64-Bit Server VM). +Type in expressions for evaluation. Or try :help. + +scala> util.Properties.versionNumberString +val res0: String = 2.13.15 +``` + +Note that even the latest Scala 3 version might not use the very +latest Scala 2 standard library, since the 3 and 2 release schedules +aren't coordinated. + +So how do you ask for the Scala 3 version number? Scala 3 offers +`dotty.tools.dotc.config.Properties.versionNumberString`, but only if +you have scala3-compiler on the classpath. So that works in the Scala 3 +REPL, but won't work in typical Scala 3 application code. + +For an alternative way to detect the Scala 3 version, see +[this gist](https://gist.github.com/romanowski/de14691cab7340134e197419bc48919a). + +There is a proposal to provide something easier at [scala/scala3#22144](https://github.com/scala/scala3/issues/22144). + +### Why is my (abstract or overridden) `val` null? + + + +See [this]({{ site.baseurl }}/tutorials/FAQ/initialization-order.html). + +### Which type of collection should I choose? + +See the [Scala 2.13 Collections Guide](https://docs.scala-lang.org/overviews/collections-2.13/introduction.html). + +### What are context bounds? + +It's syntactic sugar for a context parameter (an `implicit` parameter in Scala 2, or a `using` parameter in Scala 3). + +More details in this [section of the Scala 3 Book](https://docs.scala-lang.org/scala3/book/ca-context-bounds.html) and this [Stack Overflow answer](https://stackoverflow.com/a/4467012). + +### How does `for / yield` work? + +It is syntactic sugar for nested `map`, `flatMap`, and `withFilter` calls. + +For an in-depth explanation +see this [Stack Overflow answer](https://stackoverflow.com/a/1059501). + +### What is the difference between view, stream and iterator? + +[Answer on Stack Overflow](https://stackoverflow.com/a/5159356). + +### What does `_` mean? + +Many things really, depending on the context. +[This answer on Stack Overflow](https://stackoverflow.com/a/8001065/4111404) +has a good summary of all the meanings it has. + +Note that, even if the specific meaning is different, +according to the situation, it usually means _"anything"_. + +### Why doesn't my function literal with `_` in it work? + +Not all function literals (aka lambdas) can be expressed with the `_` +syntax. + +Every occurrence of `_` introduces a new variable. So `_ + _` means +`(x, y) => x + y`, not `x => x + x`. The latter function cannot be +written using the `_` syntax. + +Also, the scope of `_` is always the smallest enclosing expression. +The scope is determined purely syntactically, during parsing, without +regard to types. So for example, `foo(_ + 1)` always means `foo(x => +x + 1)`; it never means `x => foo(x + 1)`. The latter function cannot +be written using the `_` syntax. + +See also [SLS 6.23.2](https://scala-lang.org/files/archive/spec/2.13/06-expressions.html#placeholder-syntax-for-anonymous-functions). + +### Why couldn't Scala infer the correct type in my code? + +It is difficult to generalize about type inference, because various features of the language +affect how your code is construed. There may be several ways to rewrite your code to make +the types fall out naturally. + +The most straightforward workaround is to supply explicit types in your code. + +That may involve specifying an explicit type to a definition, or a type argument to a method. + +Type inference is greatly improved in Scala 3. If Scala 2 doesn't compile your code, it's worth trying with Scala 3. + +Sometimes, using multiple parameter lists helps inference, as explained in [this section of the language tour](https://docs.scala-lang.org/tour/multiple-parameter-lists.html#drive-type-inference). + +For common questions about type inference involving `toSet`, see the discussions on [this ticket](https://github.com/scala/bug/issues/7743) and a related [Q&A](https://stackoverflow.com/questions/5544536/in-scala-2-type-inference-fails-on-set-made-with-toset). + +### Can I chain or nest implicit conversions? + +Not really, but you can [make it work](https://stackoverflow.com/a/5332804). + +However, note that implicit conversions are, in general, +[discouraged](https://contributors.scala-lang.org/t/can-we-wean-scala-off-implicit-conversions/4388). + +### Where does Scala look for implicits? + +See this [answer on Stack Overflow](https://stackoverflow.com/a/5598107). + +### Why do primitive type parameters erase to `Object`? + +So for example, a `List[Int]` in Scala code will appear to Java as a +`List[Object]`. The Java type system doesn't allow primitive types to +appear as type parameters, but couldn't they appear as their boxed +equivalents, such as `List[java.lang.Integer]`? + +One would hope so, but doing it that way was tried, and it proved impossible. +[This SO question](https://stackoverflow.com/questions/11167430/why-are-primitive-types-such-as-int-erased-to-object-in-scala) +sadly lacks a concise explanation, but it does link to past discussions. + +### What's the difference between methods and functions? + +For example, how does a method such as: + + def square(x: Int): Int = x * x + +differ from a function value such as: + + val square: Int => Int = x => x * x + +For **Scala 2**, there is a [complete answer on Stack Overflow](https://stackoverflow.com/a/2530007/4111404) +and a [summary with practical differences](https://tpolecat.github.io/2014/06/09/methods-functions.html). + +In **Scala 3**, the differences are fewer. +[Context functions]({{ site.scala3ref }}/contextual/context-functions.html) +accept given parameters and +[polymorphic functions]({{ site.scala3ref }}/new-types/polymorphic-function-types.html) +have type parameters. + +It's standard to use methods most of the time, +except when a function value is actually needed. +[Eta-expansion](https://stackoverflow.com/questions/39445018/what-is-the-eta-expansion-in-scala), +converts methods to functions when needed. +For example, a method such as `map` expects a function, +but even if you `def square` as shown above, you can +still `xs.map(square)`. + +### What's the difference between types and classes? + +Types are primarily a compile-time concept. At compile time, +every expression is assigned a type by the compiler. + +Classes are primarily a runtime concept and are platform-dependent. +At runtime on the JVM, every value is either a primitive value +or an instance of exactly one class. + +Some type information exists only at compile time, +for multiple reasons, most notoriously +[type erasure](https://en.wikipedia.org/wiki/Type_erasure). + +For an in-depth treatment of types vs. classes, see the blog post +["There are more types than classes"](https://typelevel.org/blog/2017/02/13/more-types-than-classes.html). + +### Should I declare my parameterless method with or without parentheses? + +In other words, should one write `def foo()` or just `def foo`? + +Answer: by convention, the former is used to indicate that a method +has side effects. + +For more details, see the Scala Style Guide, [here](https://docs.scala-lang.org/style/naming-conventions.html#parentheses). + +### How can a method in a superclass return a value of the “current” type? + +Using `this.type` will only work if you are returning `this` itself. +`this.type` means "the singleton type of this instance". Only `this` +itself has the type `this.type`; other instances of the same class do +not. + +What does work for returning other values of the same type? + +Possible solutions include F-bounded polymorphism _(familiar to Java +programmers)_, type members, and the [typeclass +pattern](http://tpolecat.github.io/2013/10/12/typeclass.html). + +This [blog post](http://tpolecat.github.io/2015/04/29/f-bounds.html) +argues against F-bounds and in favor of typeclasses; +see also [this Stack Overflow post](https://stackoverflow.com/questions/59813323/advantages-of-f-bounded-polymorphism-over-typeclass-for-return-current-type-prob) for some counterpoint. + +### What does `<:<` mean? + +It's a "type constraint", and it comes from the standard library, +not from the language itself. +See [this blog post](https://blog.bruchez.name/2015/11/generalized-type-constraints-in-scala.html). + +### I dislike requiring callers to wrap optional arguments in `Some(...)`; is there a better way? + +Not really. See [this answer on Stack Overflow](https://stackoverflow.com/a/65256691/4111404). + +### Why is `implicit val` usually recommended over `implicit object`? + +The latter has a singleton type, which is too specific. +See [answer on Stack Overflow](https://stackoverflow.com/a/65258340/4111404). + +### I got a `StackOverflowError` while compiling my code. Is it a compiler bug? + +It might be. + +To find out, try giving the compiler more stack and see if the +error goes away. + +It's possible for the compiler to run out of stack when compiling some +kinds of heavily nested code. The JVM's default stack size is rather +small, so this can happen sooner than you might expect. + +The stack size can be changed by passing `-Xss...` at JVM startup, for +example `-Xss16M`. How to do this depends on what IDE and/or build +tool you are using. For sbt, add it to `.jvmopts`. + +If the stack overflow doesn't go away no matter how much stack you +give the compiler, then it's a compiler bug. Please report it on the +[Scala 2 bug tracker](https://github.com/scala/bug/issues) or [Scala 3 +bug tracker](https://github.com/scala/scala3/issues), but check +first if it's a duplicate of an existing ticket. + +### I set a setting in sbt but nothing happened. Why? + +There could be a lot of reasons. An extremely common one, that +almost everyone runs into sooner or later, is that you have a bare +setting in a multi-project build. + +For example, if you add this to your `build.sbt`: + + scalaVersion := "2.13.16" + +that's a "bare" setting, and you might expect it to apply build-wide. +But it doesn't. _It only applies to the root project._ + +In many cases one should instead write: + + ThisBuild / scalaVersion := "2.13.16" + +Other possibilities include: + +* the common settings pattern, where you put shared settings + in a `val`, typically named `commonSettings`, and then + `.settings(commonSettings)` in every project you want to + apply to them to. +* in interactive usage only, `set every` -## FAQs +Here's some further reading: -{% assign overviews = site.overviews | sort: 'num' %} -
              -{% for overview in overviews %} - {% if overview.partof == "FAQ" %} -
            • {{ overview.title }}
              • - {% endif %} -{% endfor %} -
            +* [documentation on multi-project builds](https://www.scala-sbt.org/1.x/docs/Multi-Project.html#ThisBuild) +* [issue about bare settings](https://github.com/sbt/sbt/issues/6217) diff --git a/_overviews/FAQ/initialization-order.md b/_overviews/FAQ/initialization-order.md index 2c6f0b678f..ebe07308c6 100644 --- a/_overviews/FAQ/initialization-order.md +++ b/_overviews/FAQ/initialization-order.md @@ -1,79 +1,113 @@ --- layout: multipage-overview title: Why is my abstract or overridden val null? - -discourse: true - overview-name: FAQ -partof: FAQ - -num: 9 permalink: /tutorials/FAQ/:title.html --- ## Example -To understand the problem, let's pick the following concrete example. + +The following example illustrates how classes in a subclass relation +witness the initialization of two fields which are inherited from +their top-most parent. The values are printed during the constructor +of each class, that is, when an instance is initialized. abstract class A { val x1: String val x2: String = "mom" - println("A: " + x1 + ", " + x2) + println(s"A: $x1, $x2") } class B extends A { val x1: String = "hello" - println("B: " + x1 + ", " + x2) + println(s"B: $x1, $x2") } class C extends B { override val x2: String = "dad" - println("C: " + x1 + ", " + x2) + println(s"C: $x1, $x2") } -Let's observe the initialization order through the Scala REPL: +In the Scala REPL we observe: scala> new C A: null, null B: hello, null C: hello, dad -Only when we get to the constructor of `C` are both `x1` and `x2` initialized. Therefore, constructors of `A` and `B` risk running into `NullPointerException`s. +Only when we get to the constructor of `C` are both `x1` and `x2` properly initialized. +Therefore, constructors of `A` and `B` risk running into `NullPointerException`s, +since fields are null-valued until set by a constructor. ## Explanation -A 'strict' or 'eager' val is one which is not marked lazy. -In the absence of "early definitions" (see below), initialization of strict vals is done in the following order. +A "strict" or "eager" val is a `val` which is not a `lazy val`. +Initialization of strict vals is done in the following order: 1. Superclasses are fully initialized before subclasses. -2. Otherwise, in declaration order. +2. Within the body or "template" of a class, vals are initialized in declaration order, + the order in which they are written in source. + +When a `val` is overridden, it's more precise to say that its accessor method (the "getter") is overridden. +So the access to `x2` in class `A` invokes the overridden getter in class `C`. +That getter reads the underlying field `C.x2`. +This field is not yet initialized during the construction of `A`. + +## Mitigation + +The [`-Wsafe-init` compiler flag](https://docs.scala-lang.org/scala3/reference/other-new-features/safe-initialization.html) +in Scala 3 enables a compile-time warning for accesses to uninitialized fields: + + -- Warning: Test.scala:8:6 ----------------------------------------------------- + 8 | val x1: String = "hello" + | ^ + | Access non-initialized value x1. Calling trace: + | ├── class B extends A { [ Test.scala:7 ] + | │ ^ + | ├── abstract class A { [ Test.scala:1 ] + | │ ^ + | └── println(s"A: $x1, $x2") [ Test.scala:5 ] + | ^^ + +In Scala 2, the `-Xcheckinit` flag adds runtime checks in the generated bytecode to identify accesses of uninitialized fields. +That code throws an exception when an uninitialized field is referenced +that would otherwise be used as a `null` value (or `0` or `false` in the case of primitive types). +Note that these runtime checks only report code that is actually executed at runtime. +Although these checks can be helpful to find accesses to uninitialized fields during development, +it is never advisable to enable them in production code due to the performance cost. + +## Solutions -Naturally when a val is overridden, it is not initialized more than once. So though x2 in the above example is seemingly defined at every point, this is not the case: an overridden val will appear to be null during the construction of superclasses, as will an abstract val. - -There is a compiler flag which can be useful for identifying this situation: - -**-Xcheckinit**: Add runtime check to field accessors. +Approaches for avoiding null values include: -It is inadvisable to use this flag outside of testing. It adds significantly to the code size by putting a wrapper around all potentially uninitialized field accesses: the wrapper will throw an exception rather than allow a null (or 0/false in the case of primitive types) to silently appear. Note also that this adds a *runtime* check: it can only tell you anything about code paths which you exercise with it in place. +### Use class / trait parameters -Using it on the opening example: + abstract class A(val x1: String, val x2: String = "mom") { + println("A: " + x1 + ", " + x2) + } + class B(x1: String = "hello", x2: String = "mom") extends A(x1, x2) { + println("B: " + x1 + ", " + x2) + } + class C(x2: String = "dad") extends B(x2 = x2) { + println("C: " + x1 + ", " + x2) + } + // scala> new C + // A: hello, dad + // B: hello, dad + // C: hello, dad - % scalac -Xcheckinit a.scala - % scala -e 'new C' - scala.UninitializedFieldError: Uninitialized field: a.scala: 13 - at C.x2(a.scala:13) - at A.(a.scala:5) - at B.(a.scala:7) - at C.(a.scala:12) +Values passed as parameters to the superclass constructor are available in its body. -### Solutions ### +Scala 3 also [supports trait parameters](https://docs.scala-lang.org/scala3/reference/other-new-features/trait-parameters.html). -Approaches for avoiding null values include: +Note that overriding a `val` class parameter is deprecated / disallowed in Scala 3. +Doing so in Scala 2 can lead to surprising behavior. -#### Use lazy vals #### +### Use lazy vals abstract class A { - val x1: String + lazy val x1: String lazy val x2: String = "mom" println("A: " + x1 + ", " + x2) @@ -93,75 +127,54 @@ Approaches for avoiding null values include: // B: hello, dad // C: hello, dad -Usually the best answer. Unfortunately you cannot declare an abstract lazy val. If that is what you're after, your options include: +Note that abstract `lazy val`s are supported in Scala 3, but not in Scala 2. +In Scala 2, you can define an abstract `val` or `def` instead. -1. Declare an abstract strict val, and hope subclasses will implement it as a lazy val or with an early definition. If they do not, it will appear to be uninitialized at some points during construction. -2. Declare an abstract def, and hope subclasses will implement it as a lazy val. If they do not, it will be re-evaluated on every access. -3. Declare a concrete lazy val which throws an exception, and hope subclasses override it. If they do not, it will... throw an exception. +An exception during initialization of a lazy val will cause the right-hand side to be re-evaluated on the next access; see SLS 5.2. -An exception during initialization of a lazy val will cause the right hand side to be re-evaluated on the next access: see SLS 5.2. +Note that using multiple lazy vals incurs a new risk: cycles among lazy vals can result in a stack overflow on first access. +When lazy vals are annotated as thread-safe in Scala 3, they risk deadlock. -Note that using multiple lazy vals creates a new risk: cycles among lazy vals can result in a stack overflow on first access. +### Use a nested object -#### Use early definitions #### - abstract class A { - val x1: String - val x2: String = "mom" +For purposes of initialization, an object that is not top-level is the same as a lazy val. - println("A: " + x1 + ", " + x2) - } - class B extends { - val x1: String = "hello" - } with A { - println("B: " + x1 + ", " + x2) - } - class C extends { - override val x2: String = "dad" - } with B { - println("C: " + x1 + ", " + x2) - } - // scala> new C - // A: hello, dad - // B: hello, dad - // C: hello, dad +There may be reasons to prefer a lazy val, for example to specify the type of an implicit value, +or an object where it is a companion to a class. Otherwise, the most convenient syntax may be preferred. -Early definitions are a bit unwieldy, there are limitations as to what can appear and what can be referenced in an early definitions block, and they don't compose as well as lazy vals: but if a lazy val is undesirable, they present another option. They are specified in SLS 5.1.6. - -#### Use constant value definitions #### - abstract class A { - val x1: String - val x2: String = "mom" +As an example, uninitialized state in a subclass may be accessed during construction of a superclass: - println("A: " + x1 + ", " + x2) + class Adder { + var sum = 0 + def add(x: Int): Unit = sum += x + add(1) // in LogAdder, the `added` set is not initialized yet } - class B extends A { - val x1: String = "hello" - final val x3 = "goodbye" - - println("B: " + x1 + ", " + x2) + class LogAdder extends Adder { + private var added: Set[Int] = Set.empty + override def add(x: Int): Unit = { added += x; super.add(x) } } - class C extends B { - override val x2: String = "dad" - println("C: " + x1 + ", " + x2) - } - abstract class D { - val c: C - val x3 = c.x3 // no exceptions! - println("D: " + c + " but " + x3) +In this case, the state can be initialized on demand by wrapping it in a local object: + + class Adder { + var sum = 0 + def add(x: Int): Unit = sum += x + add(1) } - class E extends D { - val c = new C - println(s"E: ${c.x1}, ${c.x2}, and $x3...") + class LogAdder extends Adder { + private object state { + var added: Set[Int] = Set.empty + } + import state._ + override def add(x: Int): Unit = { added += x; super.add(x) } } - //scala> new E - //D: null but goodbye - //A: null, null - //B: hello, null - //C: hello, dad - //E: hello, dad, and goodbye... -Sometimes all you need from an interface is a compile-time constant. +### Early definitions: deprecated + +Scala 2 supports early definitions, but they are deprecated in Scala 2.13 and unsupported in Scala 3. +See the [migration guide](https://docs.scala-lang.org/scala3/guides/migration/incompat-dropped-features.html#early-initializer) for more information. + +Constant value definitions (specified in SLS 4.1 and available in Scala 2) +and inlined definitions (in Scala 3) can work around initialization order issues +because they can supply constant values without evaluating an instance that is not yet initialized. -Constant values are stricter than strict and earlier than early definitions and have even more limitations, -as they must be constants. They are specified in SLS 4.1. diff --git a/_overviews/FAQ/stream-view-iterator.md b/_overviews/FAQ/stream-view-iterator.md deleted file mode 100644 index cc6215233a..0000000000 --- a/_overviews/FAQ/stream-view-iterator.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: multipage-overview -title: What is the difference between view, stream and iterator? - -discourse: true - -overview-name: FAQ -partof: FAQ - -num: 4 -permalink: /tutorials/FAQ/:title.html ---- -First, they are all _non-strict_. That has a particular mathematical meaning -related to functions, but, basically, means they are computed on-demand instead -of in advance. - -`Stream` is a lazy list indeed. In fact, in Scala, a `Stream` is a `List` whose -`tail` is a `lazy val`. Once computed, a value stays computed and is reused. -Or, as you say, the values are cached. - -An `Iterator` can only be used once because it is a _traversal pointer_ into a -collection, and not a collection in itself. What makes it special in Scala is -the fact that you can apply transformation such as `map` and `filter` and -simply get a new `Iterator` which will only apply these transformations when -you ask for the next element. - -Scala used to provide iterators which could be reset, but that is very hard to -support in a general manner, and they didn't make version 2.8.0. - -Views are meant to be viewed much like a database view. It is a series of -transformation which one applies to a collection to produce a "virtual" -collection. As you said, all transformations are re-applied each time you need -to fetch elements from it. - -Both `Iterator` and views have excellent memory characteristics. `Stream` is -nice, but, in Scala, its main benefit is writing infinite sequences -(particularly sequences recursively defined). One _can_ avoid keeping all of -the `Stream` in memory, though, by making sure you don't keep a reference to -its `head` (for example, by using `def` instead of `val` to define the -`Stream`). - -Because of the penalties incurred by views, one should usually `force` it after -applying the transformations, or keep it as a view if only few elements are -expected to ever be fetched, compared to the total size of the view. - -This answer was originally submitted in response to [this question on Stack Overflow][1]. - - [1]: http://stackoverflow.com/q/5159000/53013 diff --git a/_overviews/FAQ/yield.md b/_overviews/FAQ/yield.md deleted file mode 100644 index 795fc6d375..0000000000 --- a/_overviews/FAQ/yield.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -layout: multipage-overview -title: How does yield work? - -discourse: true - -partof: FAQ -num: 2 -permalink: /tutorials/FAQ/:title.html ---- -Though there's a `yield` in other languages such as Python and Ruby, Scala's -`yield` does something very different from them. In Scala, `yield` is part -of for comprehensions -- a generalization of Ruby and Python's list-comprehensions. - -Scala's "for comprehensions" are equivalent to Haskell's "do" notation, and it -is nothing more than a syntactic sugar for composition of multiple monadic -operations. As this statement will most likely not help anyone who needs help, -let's try again... - -Translating for-comprehensions ------------------------------- - -Scala's "for comprehensions" are syntactic sugar for composition of multiple -operations with `foreach`, `map`, `flatMap`, `filter` or `withFilter`. -Scala actually translates a for-expression into calls to those methods, -so any class providing them, or a subset of them, can be used with for comprehensions. - -First, let's talk about the translations. There are very simple rules: - -#### Example 1 - - for(x <- c1; y <- c2; z <-c3) {...} - -is translated into - - c1.foreach(x => c2.foreach(y => c3.foreach(z => {...}))) - -#### Example 2 - - for(x <- c1; y <- c2; z <- c3) yield {...} - -is translated into - - c1.flatMap(x => c2.flatMap(y => c3.map(z => {...}))) - -#### Example 3 - - for(x <- c; if cond) yield {...} - -is translated into - - c.withFilter(x => cond).map(x => {...}) - -with a fallback into - - c.filter(x => cond).map(x => {...}) - -if method `withFilter` is not available but `filter` is. -The next chapter has more information on this. - -#### Example 4 - - for(x <- c; y = ...) yield {...} - -is translated into - - c.map(x => (x, ...)).map((x,y) => {...}) - - -When you look at very simple for comprehensions, the map/foreach alternatives -look, indeed, better. Once you start composing them, though, you can easily get -lost in parenthesis and nesting levels. When that happens, for comprehensions -are usually much clearer. - -I'll show one simple example, and intentionally omit any explanation. You can -decide which syntax is easier to understand. - - l.flatMap(sl => sl.filter(el => el > 0).map(el => el.toString.length)) - -or - - for{ - sl <- l - el <- sl - if el > 0 - } yield el.toString.length - - -About withFilter, and strictness ----------------------------------- - -Scala 2.8 introduced a method called `withFilter`, whose main difference is -that, instead of returning a new, filtered, collection, it filters on-demand. -The `filter` method has its behavior defined based on the strictness of the -collection. To understand this better, let's take a look at some Scala 2.7 with -`List` (strict) and `Stream` (non-strict): - - scala> var found = false - found: Boolean = false - - scala> List.range(1,10).filter(_ % 2 == 1 && !found).foreach(x => if (x == 5) found = true else println(x)) - 1 - 3 - 7 - 9 - - scala> found = false - found: Boolean = false - - scala> Stream.range(1,10).filter(_ % 2 == 1 && !found).foreach(x => if (x == 5) found = true else println(x)) - 1 - 3 - -The difference happens because filter is immediately applied with `List`, -returning a list of odds -- since `found` is `false`. Only then `foreach` is -executed, but, by this time, changing `found` is meaningless, as `filter` has -already executed. - -In the case of `Stream`, the condition is not immediately applied. Instead, as -each element is requested by `foreach`, `filter` tests the condition, which -enables `foreach` to influence it through `found`. Just to make it clear, here -is the equivalent for-comprehension code: - - for (x <- List.range(1, 10); if x % 2 == 1 && !found) - if (x == 5) found = true else println(x) - - for (x <- Stream.range(1, 10); if x % 2 == 1 && !found) - if (x == 5) found = true else println(x) - -This caused many problems, because people expected the `if` to be considered -on-demand, instead of being applied to the whole collection beforehand. - -Scala 2.8 introduced `withFilter`, which is _always_ non-strict, no matter the -strictness of the collection. The following example shows `List` with both -methods on Scala 2.8: - - scala> var found = false - found: Boolean = false - - scala> List.range(1,10).filter(_ % 2 == 1 && !found).foreach(x => if (x == 5) found = true else println(x)) - 1 - 3 - 7 - 9 - - scala> found = false - found: Boolean = false - - scala> List.range(1,10).withFilter(_ % 2 == 1 && !found).foreach(x => if (x == 5) found = true else println(x)) - 1 - 3 - -This produces the result most people expect, without changing how `filter` -behaves. As a side note, `Range` was changed from non-strict to strict between -Scala 2.7 and Scala 2.8. - -This answer was originally submitted in response to [this question on Stack Overflow][1]. - - [1]: http://stackoverflow.com/questions/1052476/can-someone-explain-scalas-yield/1052510#1052510 diff --git a/_overviews/cheatsheets/index.md b/_overviews/cheatsheets/index.md deleted file mode 100644 index aa27d9e403..0000000000 --- a/_overviews/cheatsheets/index.md +++ /dev/null @@ -1,358 +0,0 @@ ---- -layout: cheatsheet -title: Scalacheat - -partof: cheatsheet - -by: Brendan O'Connor -about: Thanks to Brendan O'Connor, this cheatsheet aims to be a quick reference of Scala syntactic constructions. Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. - -languages: [ba, fr, ja, pl, pt-br, zh-cn, th] -permalink: /cheatsheets/index.html ---- - - - -{{ page.about }} - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
            variables
            var x = 5variable
            Good
            val x = 5
            Bad
            x=6            		constant
            var x: Double = 5explicit type
            functions
            Good
            def f(x: Int) = { x*x }
            Bad
            def f(x: Int) { x*x }            		define function
            hidden error: without = it’s a Unit-returning procedure; causes havoc
            Good
            def f(x: Any) = println(x)
            Bad
            def f(x) = println(x)            		define function
            syntax error: need types for every arg.
            type R = Doubletype alias
            def f(x: R) vs.
            def f(x: => R)            		call-by-value
            call-by-name (lazy parameters)
            (x:R) => x*xanonymous function
            (1 to 5).map(_*2) vs.
            (1 to 5).reduceLeft( _+_ )            		anonymous function: underscore is positionally matched arg.
            (1 to 5).map( x => x*x )anonymous function: to use an arg twice, have to name it.
            Good
            (1 to 5).map(2*)
            Bad
            (1 to 5).map(*2)            		anonymous function: bound infix method. Use 2*_ for sanity’s sake instead.
            (1 to 5).map { x => val y=x*2; println(y); y }anonymous function: block style returns last expression.
            (1 to 5) filter {_%2 == 0} map {_*2}anonymous functions: pipeline style. (or parens too).
            def compose(g:R=>R, h:R=>R) = (x:R) => g(h(x))
            val f = compose({_*2}, {_-1})            		anonymous functions: to pass in multiple blocks, need outer parens.
            val zscore = (mean:R, sd:R) => (x:R) => (x-mean)/sdcurrying, obvious syntax.
            def zscore(mean:R, sd:R) = (x:R) => (x-mean)/sdcurrying, obvious syntax
            def zscore(mean:R, sd:R)(x:R) = (x-mean)/sdcurrying, sugar syntax. but then:
            val normer = zscore(7, 0.4) _need trailing underscore to get the partial, only for the sugar version.
            def mapmake[T](g:T=>T)(seq: List[T]) = seq.map(g)generic type.
            5.+(3); 5 + 3
            (1 to 5) map (_*2)            		infix sugar.
            def sum(args: Int*) = args.reduceLeft(_+_)varargs.
            packages
            import scala.collection._wildcard import.
            import scala.collection.Vector
            import scala.collection.{Vector, Sequence}            		selective import.
            import scala.collection.{Vector => Vec28}renaming import.
            import java.util.{Date => _, _}import all from java.util except Date.
            package pkg at start of file
            package pkg { ... }            		declare a package.
            data structures
            (1,2,3)tuple literal. (Tuple3)
            var (x,y,z) = (1,2,3)destructuring bind: tuple unpacking via pattern matching.
            Bad
            var x,y,z = (1,2,3)            		hidden error: each assigned to the entire tuple.
            var xs = List(1,2,3)list (immutable).
            xs(2)paren indexing. (slides)
            1 :: List(2,3)cons.
            1 to 5 same as 1 until 6
            1 to 10 by 2            		range sugar.
            () (empty parens)sole member of the Unit type (like C/Java void).
            control constructs
            if (check) happy else sadconditional.
            if (check) happy -
            same as
            - if (check) happy else ()            		conditional sugar.
            while (x < 5) { println(x); x += 1}while loop.
            do { println(x); x += 1} while (x < 5)do while loop.
            import scala.util.control.Breaks._
-breakable {
-  for (x <- xs) {
-    if (Math.random < 0.1)
-      break
-  }
-}
            		break. (slides)
            for (x <- xs if x%2 == 0) yield x*10 -
            same as
            - xs.filter(_%2 == 0).map(_*10)            		for comprehension: filter/map
            for ((x,y) <- xs zip ys) yield x*y -
            same as
            - (xs zip ys) map { case (x,y) => x*y }            		for comprehension: destructuring bind
            for (x <- xs; y <- ys) yield x*y -
            same as
            - xs flatMap {x => ys map {y => x*y}}            		for comprehension: cross product
            for (x <- xs; y <- ys) {
-  println("%d/%d = %.1f".format(x, y, x/y.toFloat))
-}
            		for comprehension: imperative-ish
            sprintf-style
            for (i <- 1 to 5) {
-  println(i)
-}
            		for comprehension: iterate including the upper bound
            for (i <- 1 until 5) {
-  println(i)
-}
            		for comprehension: iterate omitting the upper bound
            pattern matching
            Good
            (xs zip ys) map { case (x,y) => x*y }
            Bad
            (xs zip ys) map( (x,y) => x*y )            		use case in function args for pattern matching.
            Bad
            - 
            val v42 = 42
-Some(3) match {
-  case Some(v42) => println("42")
-  case _ => println("Not 42")
-}
            		“v42” is interpreted as a name matching any Int value, and “42” is printed.
            Good
            - 
            val v42 = 42
-Some(3) match {
-  case Some(`v42`) => println("42")
-  case _ => println("Not 42")
-}
            		”`v42`” with backticks is interpreted as the existing val v42, and “Not 42” is printed.
            Good
            - 
            val UppercaseVal = 42
-Some(3) match {
-  case Some(UppercaseVal) => println("42")
-  case _ => println("Not 42")
-}
            		UppercaseVal is treated as an existing val, rather than a new pattern variable, because it starts with an uppercase letter. Thus, the value contained within UppercaseVal is checked against 3, and “Not 42” is printed.
            object orientation
            class C(x: R)constructor params - x is only available in class body
            class C(val x: R)
            var c = new C(4)
            c.x            		constructor params - automatic public member defined
            class C(var x: R) {
-  assert(x > 0, "positive please")
-  var y = x
-  val readonly = 5
-  private var secret = 1
-  def this = this(42)
-}
            		constructor is class body
            declare a public member
            declare a gettable but not settable member
            declare a private member
            alternative constructor
            new{ ... }anonymous class
            abstract class D { ... }define an abstract class. (non-createable)
            class C extends D { ... }define an inherited class.
            class D(var x: R)
            class C(x: R) extends D(x)            		inheritance and constructor params. (wishlist: automatically pass-up params by default)
            object O extends D { ... }define a singleton. (module-like)
            trait T { ... }
            class C extends T { ... }
            class C extends D with T { ... }            		traits.
            interfaces-with-implementation. no constructor params. mixin-able.
            trait T1; trait T2
            class C extends T1 with T2
            class C extends D with T1 with T2            		multiple traits.
            class C extends D { override def f = ...}must declare method overrides.
            new java.io.File("f")create object.
            Bad
            new List[Int]
            Good
            List(1,2,3)            		type error: abstract type
            instead, convention: callable factory shadowing the type
            classOf[String]class literal.
            x.isInstanceOf[String]type check (runtime)
            x.asInstanceOf[String]type cast (runtime)
            x: Stringascription (compile time)
            diff --git a/_overviews/collections-2.13/arrays.md b/_overviews/collections-2.13/arrays.md new file mode 100644 index 0000000000..32f9fb0584 --- /dev/null +++ b/_overviews/collections-2.13/arrays.md @@ -0,0 +1,243 @@ +--- +layout: multipage-overview +title: Arrays +partof: collections-213 +overview-name: Collections + +num: 10 +previous-page: concrete-mutable-collection-classes +next-page: strings + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +[Array](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html) is a special kind of collection in Scala. On the one hand, Scala arrays correspond one-to-one to Java arrays. That is, a Scala array `Array[Int]` is represented as a Java `int[]`, an `Array[Double]` is represented as a Java `double[]` and a `Array[String]` is represented as a Java `String[]`. But at the same time, Scala arrays offer much more than their Java analogues. First, Scala arrays can be _generic_. That is, you can have an `Array[T]`, where `T` is a type parameter or abstract type. Second, Scala arrays are compatible with Scala sequences - you can pass an `Array[T]` where a `Seq[T]` is required. Finally, Scala arrays also support all sequence operations. Here's an example of this in action: + +{% tabs arrays_1 %} +{% tab 'Scala 2 and 3' for=arrays_1 %} +```scala +scala> val a1 = Array(1, 2, 3) +val a1: Array[Int] = Array(1, 2, 3) + +scala> val a2 = a1.map(_ * 3) +val a2: Array[Int] = Array(3, 6, 9) + +scala> val a3 = a2.filter(_ % 2 != 0) +val a3: Array[Int] = Array(3, 9) + +scala> a3.reverse +val res0: Array[Int] = Array(9, 3) +``` +{% endtab %} +{% endtabs %} + +Given that Scala arrays are represented just like Java arrays, how can these additional features be supported in Scala? The Scala array implementation makes systematic use of implicit conversions. In Scala, an array does not pretend to _be_ a sequence. It can't really be that because the data type representation of a native array is not a subtype of `Seq`. Instead there is an implicit "wrapping" conversion between arrays and instances of class `scala.collection.mutable.ArraySeq`, which is a subclass of `Seq`. Here you see it in action: + +{% tabs arrays_2 %} +{% tab 'Scala 2 and 3' for=arrays_2 %} +```scala +scala> val seq: collection.Seq[Int] = a1 +val seq: scala.collection.Seq[Int] = ArraySeq(1, 2, 3) + +scala> val a4: Array[Int] = seq.toArray +val a4: Array[Int] = Array(1, 2, 3) + +scala> a1 eq a4 +val res1: Boolean = false +``` +{% endtab %} +{% endtabs %} + +The interaction above demonstrates that arrays are compatible with sequences, because there's an implicit conversion from arrays to `ArraySeq`s. To go the other way, from an `ArraySeq` to an `Array`, you can use the `toArray` method defined in `Iterable`. The last REPL line above shows that wrapping and then unwrapping with `toArray` produces a copy of the original array. + +There is yet another implicit conversion that gets applied to arrays. This conversion simply "adds" all sequence methods to arrays but does not turn the array itself into a sequence. "Adding" means that the array is wrapped in another object of type `ArrayOps` which supports all sequence methods. Typically, this `ArrayOps` object is short-lived; it will usually be inaccessible after the call to the sequence method and its storage can be recycled. Modern VMs often avoid creating this object entirely. + +The difference between the two implicit conversions on arrays is shown in the next REPL dialogue: + +{% tabs arrays_3 %} +{% tab 'Scala 2 and 3' for=arrays_3 %} +```scala +scala> val seq: collection.Seq[Int] = a1 +val seq: scala.collection.Seq[Int] = ArraySeq(1, 2, 3) + +scala> seq.reverse +val res2: scala.collection.Seq[Int] = ArraySeq(3, 2, 1) + +scala> val ops: collection.ArrayOps[Int] = a1 +val ops: scala.collection.ArrayOps[Int] = scala.collection.ArrayOps@2d7df55 + +scala> ops.reverse +val res3: Array[Int] = Array(3, 2, 1) +``` +{% endtab %} +{% endtabs %} + +You see that calling reverse on `seq`, which is an `ArraySeq`, will give again a `ArraySeq`. That's logical, because arrayseqs are `Seqs`, and calling reverse on any `Seq` will give again a `Seq`. On the other hand, calling reverse on the ops value of class `ArrayOps` will give an `Array`, not a `Seq`. + +The `ArrayOps` example above was quite artificial, intended only to show the difference to `ArraySeq`. Normally, you'd never define a value of class `ArrayOps`. You'd just call a `Seq` method on an array: + +{% tabs arrays_4 %} +{% tab 'Scala 2 and 3' for=arrays_4 %} +```scala +scala> a1.reverse +val res4: Array[Int] = Array(3, 2, 1) +``` +{% endtab %} +{% endtabs %} + +The `ArrayOps` object gets inserted automatically by the implicit conversion. So the line above is equivalent to + +{% tabs arrays_5 %} +{% tab 'Scala 2 and 3' for=arrays_5 %} +```scala +scala> intArrayOps(a1).reverse +val res5: Array[Int] = Array(3, 2, 1) +``` +{% endtab %} +{% endtabs %} + +where `intArrayOps` is the implicit conversion that was inserted previously. This raises the question of how the compiler picked `intArrayOps` over the other implicit conversion to `ArraySeq` in the line above. After all, both conversions map an array to a type that supports a reverse method, which is what the input specified. The answer to that question is that the two implicit conversions are prioritized. The `ArrayOps` conversion has a higher priority than the `ArraySeq` conversion. The first is defined in the `Predef` object whereas the second is defined in a class `scala.LowPriorityImplicits`, which is inherited by `Predef`. Implicits in subclasses and subobjects take precedence over implicits in base classes. So if both conversions are applicable, the one in `Predef` is chosen. A very similar scheme works for strings. + +So now you know how arrays can be compatible with sequences and how they can support all sequence operations. What about genericity? In Java, you cannot write a `T[]` where `T` is a type parameter. How then is Scala's `Array[T]` represented? In fact a generic array like `Array[T]` could be at run-time any of Java's eight primitive array types `byte[]`, `short[]`, `char[]`, `int[]`, `long[]`, `float[]`, `double[]`, `boolean[]`, or it could be an array of objects. The only common run-time type encompassing all of these types is `AnyRef` (or, equivalently `java.lang.Object`), so that's the type to which the Scala compiler maps `Array[T]`. At run-time, when an element of an array of type `Array[T]` is accessed or updated there is a sequence of type tests that determine the actual array type, followed by the correct array operation on the Java array. These type tests slow down array operations somewhat. You can expect accesses to generic arrays to be three to four times slower than accesses to primitive or object arrays. This means that if you need maximal performance, you should prefer concrete to generic arrays. Representing the generic array type is not enough, however, there must also be a way to create generic arrays. This is an even harder problem, which requires a little of help from you. To illustrate the issue, consider the following attempt to write a generic method that creates an array. + +{% tabs arrays_6 class=tabs-scala-version %} +{% tab 'Scala 2' for=arrays_6 %} +```scala mdoc:fail +// this is wrong! +def evenElems[T](xs: Vector[T]): Array[T] = { + val arr = new Array[T]((xs.length + 1) / 2) + for (i <- 0 until xs.length by 2) + arr(i / 2) = xs(i) + arr +} +``` +{% endtab %} +{% tab 'Scala 3' for=arrays_6 %} +```scala +// this is wrong! +def evenElems[T](xs: Vector[T]): Array[T] = + val arr = new Array[T]((xs.length + 1) / 2) + for i <- 0 until xs.length by 2 do + arr(i / 2) = xs(i) + arr +``` +{% endtab %} +{% endtabs %} + +The `evenElems` method returns a new array that consist of all elements of the argument vector `xs` which are at even positions in the vector. The first line of the body of `evenElems` creates the result array, which has the same element type as the argument. So depending on the actual type parameter for `T`, this could be an `Array[Int]`, or an `Array[Boolean]`, or an array of some other primitive types in Java, or an array of some reference type. But these types have all different runtime representations, so how is the Scala runtime going to pick the correct one? In fact, it can't do that based on the information it is given, because the actual type that corresponds to the type parameter `T` is erased at runtime. That's why you will get the following error message if you compile the code above: + +{% tabs arrays_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=arrays_7 %} +```scala +error: cannot find class manifest for element type T + val arr = new Array[T]((arr.length + 1) / 2) + ^ +``` +{% endtab %} +{% tab 'Scala 3' for=arrays_7 %} +```scala +-- Error: ---------------------------------------------------------------------- +3 | val arr = new Array[T]((xs.length + 1) / 2) + | ^ + | No ClassTag available for T +``` +{% endtab %} +{% endtabs %} + +What's required here is that you help the compiler out by providing some runtime hint what the actual type parameter of `evenElems` is. This runtime hint takes the form of a class manifest of type `scala.reflect.ClassTag`. A class manifest is a type descriptor object which describes what the top-level class of a type is. Alternatively to class manifests there are also full manifests of type `scala.reflect.Manifest`, which describe all aspects of a type. But for array creation, only class manifests are needed. + +The Scala compiler will construct class manifests automatically if you instruct it to do so. "Instructing" means that you demand a class manifest as an implicit parameter, like this: + +{% tabs arrays_8 class=tabs-scala-version %} +{% tab 'Scala 2' for=arrays_8 %} +```scala +def evenElems[T](xs: Vector[T])(implicit m: ClassTag[T]): Array[T] = ... +``` +{% endtab %} +{% tab 'Scala 3' for=arrays_8 %} +```scala +def evenElems[T](xs: Vector[T])(using m: ClassTag[T]): Array[T] = ... +``` +{% endtab %} +{% endtabs %} + +Using an alternative and shorter syntax, you can also demand that the type comes with a class manifest by using a context bound. This means following the type with a colon and the class name `ClassTag`, like this: + +{% tabs arrays_9 class=tabs-scala-version %} +{% tab 'Scala 2' for=arrays_9 %} +```scala +import scala.reflect.ClassTag +// this works +def evenElems[T: ClassTag](xs: Vector[T]): Array[T] = { + val arr = new Array[T]((xs.length + 1) / 2) + for (i <- 0 until xs.length by 2) + arr(i / 2) = xs(i) + arr +} +``` +{% endtab %} +{% tab 'Scala 3' for=arrays_9 %} +```scala +import scala.reflect.ClassTag +// this works +def evenElems[T: ClassTag](xs: Vector[T]): Array[T] = + val arr = new Array[T]((xs.length + 1) / 2) + for i <- 0 until xs.length by 2 do + arr(i / 2) = xs(i) + arr +``` +{% endtab %} +{% endtabs %} + +The two revised versions of `evenElems` mean exactly the same. What happens in either case is that when the `Array[T]` is constructed, the compiler will look for a class manifest for the type parameter T, that is, it will look for an implicit value of type `ClassTag[T]`. If such a value is found, the manifest is used to construct the right kind of array. Otherwise, you'll see an error message like the one above. + +Here is some REPL interaction that uses the `evenElems` method. + +{% tabs arrays_10 %} +{% tab 'Scala 2 and 3' for=arrays_10 %} +```scala +scala> evenElems(Vector(1, 2, 3, 4, 5)) +val res6: Array[Int] = Array(1, 3, 5) + +scala> evenElems(Vector("this", "is", "a", "test", "run")) +val res7: Array[java.lang.String] = Array(this, a, run) +``` +{% endtab %} +{% endtabs %} + +In both cases, the Scala compiler automatically constructed a class manifest for the element type (first, `Int`, then `String`) and passed it to the implicit parameter of the `evenElems` method. The compiler can do that for all concrete types, but not if the argument is itself another type parameter without its class manifest. For instance, the following fails: + +{% tabs arrays_11 class=tabs-scala-version %} +{% tab 'Scala 2' for=arrays_11 %} +```scala +scala> def wrap[U](xs: Vector[U]) = evenElems(xs) +:6: error: No ClassTag available for U. + def wrap[U](xs: Vector[U]) = evenElems(xs) + ^ +``` +{% endtab %} +{% tab 'Scala 3' for=arrays_11 %} +```scala +-- Error: ---------------------------------------------------------------------- +6 |def wrap[U](xs: Vector[U]) = evenElems(xs) + | ^ + | No ClassTag available for U +``` +{% endtab %} +{% endtabs %} + +What happened here is that the `evenElems` demands a class manifest for the type parameter `U`, but none was found. The solution in this case is, of course, to demand another implicit class manifest for `U`. So the following works: + +{% tabs arrays_12 %} +{% tab 'Scala 2 and 3' for=arrays_12 %} +```scala +scala> def wrap[U: ClassTag](xs: Vector[U]) = evenElems(xs) +def wrap[U](xs: Vector[U])(implicit evidence$1: scala.reflect.ClassTag[U]): Array[U] +``` +{% endtab %} +{% endtabs %} + +This example also shows that the context bound in the definition of `U` is just a shorthand for an implicit parameter named here `evidence$1` of type `ClassTag[U]`. + +In summary, generic array creation demands class manifests. So whenever creating an array of a type parameter `T`, you also need to provide an implicit class manifest for `T`. The easiest way to do this is to declare the type parameter with a `ClassTag` context bound, as in `[T: ClassTag]`. diff --git a/_overviews/collections-2.13/concrete-immutable-collection-classes.md b/_overviews/collections-2.13/concrete-immutable-collection-classes.md new file mode 100644 index 0000000000..f4d746de58 --- /dev/null +++ b/_overviews/collections-2.13/concrete-immutable-collection-classes.md @@ -0,0 +1,321 @@ +--- +layout: multipage-overview +title: Concrete Immutable Collection Classes +partof: collections-213 +overview-name: Collections + +num: 8 +previous-page: maps +next-page: concrete-mutable-collection-classes + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +Scala provides many concrete immutable collection classes for you to choose from. They differ in the traits they implement (maps, sets, sequences), whether they can be infinite, and the speed of various operations. Here are some of the most common immutable collection types used in Scala. + +## Lists + +A [List](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/List.html) is a finite immutable sequence. They provide constant-time access to their first element as well as the rest of the list, and they have a constant-time cons operation for adding a new element to the front of the list. Many other operations take linear time. + +## LazyLists + +A [LazyList](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/LazyList.html) is like a list except that its elements are computed lazily. Because of this, a lazy list can be infinitely long. Only those elements requested are computed. Otherwise, lazy lists have the same performance characteristics as lists. + +Whereas lists are constructed with the `::` operator, lazy lists are constructed with the similar-looking `#::`. Here is a simple example of a lazy list containing the integers 1, 2, and 3: + +{% tabs LazyList_1 %} +{% tab 'Scala 2 and 3' for=LazyList_1 %} +~~~scala +scala> val lazyList = 1 #:: 2 #:: 3 #:: LazyList.empty +lazyList: scala.collection.immutable.LazyList[Int] = LazyList() +~~~ +{% endtab %} +{% endtabs %} + +The head of this lazy list is 1, and the tail of it has 2 and 3. None of the elements are printed here, though, because the list +hasn’t been computed yet! Lazy lists are specified to compute lazily, and the `toString` method of a lazy list is careful not to force any extra evaluation. + +Below is a more complex example. It computes a lazy list that contains a Fibonacci sequence starting with the given two numbers. A Fibonacci sequence is one where each element is the sum of the previous two elements in the series. + +{% tabs LazyList_2 %} +{% tab 'Scala 2 and 3' for=LazyList_2 %} +~~~scala +scala> def fibFrom(a: Int, b: Int): LazyList[Int] = a #:: fibFrom(b, a + b) +fibFrom: (a: Int,b: Int)LazyList[Int] +~~~ +{% endtab %} +{% endtabs %} + +This function is deceptively simple. The first element of the sequence is clearly `a`, and the rest of the sequence is the Fibonacci sequence starting with `b` followed by `a + b`. The tricky part is computing this sequence without causing an infinite recursion. If the function used `::` instead of `#::`, then every call to the function would result in another call, thus causing an infinite recursion. Since it uses `#::`, though, the right-hand side is not evaluated until it is requested. +Here are the first few elements of the Fibonacci sequence starting with two ones: + +{% tabs LazyList_3 %} +{% tab 'Scala 2 and 3' for=LazyList_3 %} +~~~scala +scala> val fibs = fibFrom(1, 1).take(7) +fibs: scala.collection.immutable.LazyList[Int] = LazyList() +scala> fibs.toList +res9: List[Int] = List(1, 1, 2, 3, 5, 8, 13) +~~~ +{% endtab %} +{% endtabs %} + +## Immutable ArraySeqs + +Lists are very efficient when the algorithm processing them is careful to only process their heads. Accessing, adding, and removing the head of a list takes only constant time, whereas accessing or modifying elements later in the list takes time linear in the depth into the list. + +[ArraySeq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/ArraySeq.html) is a +collection type (introduced in Scala 2.13) that addresses the inefficiency for random access on lists. ArraySeqs +allow accessing any element of the collection in constant time. As a result, algorithms using ArraySeqs do not +have to be careful about accessing just the head of the collection. They can access elements at arbitrary locations, +and thus they can be much more convenient to write. + +ArraySeqs are built and updated just like any other sequence. + +{% tabs ArraySeq_1 %} +{% tab 'Scala 2 and 3' for=ArraySeq_1 %} +~~~scala +scala> val arr = scala.collection.immutable.ArraySeq(1, 2, 3) +arr: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 3) +scala> val arr2 = arr :+ 4 +arr2: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 3, 4) +scala> arr2(0) +res22: Int = 1 +~~~ +{% endtab %} +{% endtabs %} + +ArraySeqs are immutable, so you cannot change an element in place. However, the `updated`, `appended` and `prepended` +operations create new ArraySeqs that differ from a given ArraySeq only in a single element: + +{% tabs ArraySeq_2 %} +{% tab 'Scala 2 and 3' for=ArraySeq_2 %} +~~~scala +scala> arr.updated(2, 4) +res26: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 4) +scala> arr +res27: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 3) +~~~ +{% endtab %} +{% endtabs %} + +As the last line above shows, a call to `updated` has no effect on the original ArraySeq `arr`. + +ArraySeqs store their elements in a private [Array]({% link _overviews/collections-2.13/arrays.md %}). This is a compact representation that supports fast +indexed access, but updating or adding one element is linear since it requires creating another array and copying all +the original array’s elements. + +## Vectors + +We have seen in the previous sections that `List` and `ArraySeq` are efficient data structures in some specific +use cases, but they are also inefficient in other use cases: for instance, prepending an element is constant for `List`, +but linear for `ArraySeq`, and, conversely, indexed access is constant for `ArraySeq` but linear for `List`. + +[Vector](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html) is a collection type that provides good performance for all its operations. Vectors allow accessing any element of the sequence in "effectively" constant time. It's a larger constant than for access to the head of a List or for reading an element of an ArraySeq, but it's a constant nonetheless. As a result, algorithms using vectors do not have to be careful about accessing just the head of the sequence. They can access and modify elements at arbitrary locations, and thus they can be much more convenient to write. + +Vectors are built and modified just like any other sequence. + +{% tabs Vector_1 %} +{% tab 'Scala 2 and 3' for=Vector_1 %} +~~~scala +scala> val vec = scala.collection.immutable.Vector.empty +vec: scala.collection.immutable.Vector[Nothing] = Vector() +scala> val vec2 = vec :+ 1 :+ 2 +vec2: scala.collection.immutable.Vector[Int] = Vector(1, 2) +scala> val vec3 = 100 +: vec2 +vec3: scala.collection.immutable.Vector[Int] = Vector(100, 1, 2) +scala> vec3(0) +res1: Int = 100 +~~~ +{% endtab %} +{% endtabs %} + +Vectors are represented as trees with a high branching factor (The branching factor of a tree or a graph is the number of children at each node). The details of how this is accomplished [changed](https://github.com/scala/scala/pull/8534) in Scala 2.13.2, but the basic idea remains the same, as follows. + +Every tree node contains up to 32 elements of the vector or contains up to 32 other tree nodes. Vectors with up to 32 elements can be represented in a single node. Vectors with up to `32 * 32 = 1024` elements can be represented with a single indirection. Two hops from the root of the tree to the final element node are sufficient for vectors with up to 215 elements, three hops for vectors with 220, four hops for vectors with 225 elements and five hops for vectors with up to 230 elements. So for all vectors of reasonable size, an element selection involves up to 5 primitive array selections. This is what we meant when we wrote that element access is "effectively constant time". + +Like selection, functional vector updates are also "effectively constant time". Updating an element in the middle of a vector can be done by copying the node that contains the element, and every node that points to it, starting from the root of the tree. This means that a functional update creates between one and five nodes that each contain up to 32 elements or subtrees. This is certainly more expensive than an in-place update in a mutable array, but still a lot cheaper than copying the whole vector. + +Because vectors strike a good balance between fast random selections and fast random functional updates, they are currently the default implementation of immutable indexed sequences: + +{% tabs Vector_2 %} +{% tab 'Scala 2 and 3' for=Vector_2 %} +~~~scala +scala> collection.immutable.IndexedSeq(1, 2, 3) +res2: scala.collection.immutable.IndexedSeq[Int] = Vector(1, 2, 3) +~~~ +{% endtab %} +{% endtabs %} + +## Immutable Queues + +A [Queue](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Queue.html) is a first-in-first-out sequence. You enqueue an element onto a queue with `enqueue`, and dequeue an element with `dequeue`. These operations are constant time. + +Here's how you can create an empty immutable queue: + +{% tabs Queue_1 %} +{% tab 'Scala 2 and 3' for=Queue_1 %} +~~~scala +scala> val empty = scala.collection.immutable.Queue[Int]() +empty: scala.collection.immutable.Queue[Int] = Queue() +~~~ +{% endtab %} +{% endtabs %} + +You can append an element to an immutable queue with `enqueue`: + +{% tabs Queue_2 %} +{% tab 'Scala 2 and 3' for=Queue_2 %} +~~~scala +scala> val has1 = empty.enqueue(1) +has1: scala.collection.immutable.Queue[Int] = Queue(1) +~~~ +{% endtab %} +{% endtabs %} + +To append multiple elements to a queue, call `enqueueAll` with a collection as its argument: + +{% tabs Queue_3 %} +{% tab 'Scala 2 and 3' for=Queue_3 %} +~~~scala +scala> val has123 = has1.enqueueAll(List(2, 3)) +has123: scala.collection.immutable.Queue[Int] + = Queue(1, 2, 3) +~~~ +{% endtab %} +{% endtabs %} + +To remove an element from the head of the queue, you use `dequeue`: + +{% tabs Queue_4 %} +{% tab 'Scala 2 and 3' for=Queue_4 %} +~~~scala +scala> val (element, has23) = has123.dequeue +element: Int = 1 +has23: scala.collection.immutable.Queue[Int] = Queue(2, 3) +~~~ +{% endtab %} +{% endtabs %} + +Note that `dequeue` returns a pair consisting of the element removed and the rest of the queue. + +## Ranges + +A [Range](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html) is an ordered sequence of integers that are equally spaced apart. For example, "1, 2, 3," is a range, as is "5, 8, 11, 14." To create a range in Scala, use the predefined methods `to` and `by`. + +{% tabs Range_1 %} +{% tab 'Scala 2 and 3' for=Range_1 %} +~~~scala +scala> 1 to 3 +res2: scala.collection.immutable.Range.Inclusive = Range(1, 2, 3) +scala> 5 to 14 by 3 +res3: scala.collection.immutable.Range = Range(5, 8, 11, 14) +~~~ +{% endtab %} +{% endtabs %} + +If you want to create a range that is exclusive of its upper limit, then use the convenience method `until` instead of `to`: + +{% tabs Range_2 %} +{% tab 'Scala 2 and 3' for=Range_2 %} +~~~scala +scala> 1 until 3 +res2: scala.collection.immutable.Range = Range(1, 2) +~~~ +{% endtab %} +{% endtabs %} + +Ranges are represented in constant space, because they can be defined by just three numbers: their start, their end, and the stepping value. Because of this representation, most operations on ranges are extremely fast. + +## Compressed Hash-Array Mapped Prefix-trees + +Hash tries are a standard way to implement immutable sets and maps efficiently. [Compressed Hash-Array Mapped Prefix-trees](https://github.com/msteindorfer/oopsla15-artifact/) are a design for hash tries on the JVM which improves locality and makes sure the trees remain in a canonical and compact representation. They are supported by class [immutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/HashMap.html). Their representation is similar to vectors in that they are also trees where every node has 32 elements or 32 subtrees. But the selection of these keys is now done based on hash code. For instance, to find a given key in a map, one first takes the hash code of the key. Then, the lowest 5 bits of the hash code are used to select the first subtree, followed by the next 5 bits and so on. The selection stops once all elements stored in a node have hash codes that differ from each other in the bits that are selected up to this level. + +Hash tries strike a nice balance between reasonably fast lookups and reasonably efficient functional insertions (`+`) and deletions (`-`). That's why they underlie Scala's default implementations of immutable maps and sets. In fact, Scala has a further optimization for immutable sets and maps that contain less than five elements. Sets and maps with one to four elements are stored as single objects that just contain the elements (or key/value pairs in the case of a map) as fields. The empty immutable set and the empty immutable map is in each case a single object - there's no need to duplicate storage for those because an empty immutable set or map will always stay empty. + +## Red-Black Trees + +Red-black trees are a form of balanced binary tree where some nodes are designated "red" and others designated "black." Like any balanced binary tree, operations on them reliably complete in time logarithmic to the size of the tree. + +Scala provides implementations of immutable sets and maps that use a red-black tree internally. Access them under the names [TreeSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) and [TreeMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeMap.html). + +{% tabs Red-Black_1 %} +{% tab 'Scala 2 and 3' for=Red-Black_1 %} +~~~scala +scala> scala.collection.immutable.TreeSet.empty[Int] +res11: scala.collection.immutable.TreeSet[Int] = TreeSet() +scala> res11 + 1 + 3 + 3 +res12: scala.collection.immutable.TreeSet[Int] = TreeSet(1, 3) +~~~ +{% endtab %} +{% endtabs %} + +Red-black trees are the standard implementation of `SortedSet` in Scala, because they provide an efficient iterator that returns all elements in sorted order. + +## Immutable BitSets + +A [BitSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/BitSet.html) represents a collection of small integers as the bits of a larger integer. For example, the bit set containing 3, 2, and 0 would be represented as the integer 1101 in binary, which is 13 in decimal. + +Internally, bit sets use an array of 64-bit `Long`s. The first `Long` in the array is for integers 0 through 63, the second is for 64 through 127, and so on. Thus, bit sets are very compact so long as the largest integer in the set is less than a few hundred or so. + +Operations on bit sets are very fast. Testing for inclusion takes constant time. Adding an item to the set takes time proportional to the number of `Long`s in the bit set's array, which is typically a small number. Here are some simple examples of the use of a bit set: + +{% tabs BitSet_1 %} +{% tab 'Scala 2 and 3' for=BitSet_1 %} +~~~scala +scala> val bits = scala.collection.immutable.BitSet.empty +bits: scala.collection.immutable.BitSet = BitSet() +scala> val moreBits = bits + 3 + 4 + 4 +moreBits: scala.collection.immutable.BitSet = BitSet(3, 4) +scala> moreBits(3) +res26: Boolean = true +scala> moreBits(0) +res27: Boolean = false +~~~ +{% endtab %} +{% endtabs %} + +## VectorMaps + +A [VectorMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/VectorMap.html) represents +a map using both a `Vector` of keys and a `HashMap`. It provides an iterator that returns all the entries in their +insertion order. + +{% tabs VectorMap_1 %} +{% tab 'Scala 2 and 3' for=VectorMap_1 %} +~~~scala +scala> val vm = scala.collection.immutable.VectorMap.empty[Int, String] +vm: scala.collection.immutable.VectorMap[Int,String] = + VectorMap() +scala> val vm1 = vm + (1 -> "one") +vm1: scala.collection.immutable.VectorMap[Int,String] = + VectorMap(1 -> one) +scala> val vm2 = vm1 + (2 -> "two") +vm2: scala.collection.immutable.VectorMap[Int,String] = + VectorMap(1 -> one, 2 -> two) +scala> vm2 == Map(2 -> "two", 1 -> "one") +res29: Boolean = true +~~~ +{% endtab %} +{% endtabs %} + +The first lines show that the content of the `VectorMap` keeps the insertion order, and the last line +shows that `VectorMap`s are comparable with other `Map`s and that this comparison does not take the +order of elements into account. + +## ListMaps + +A [ListMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/ListMap.html) represents a map as a linked list of key-value pairs. In general, operations on a list map might have to iterate through the entire list. Thus, operations on a list map take time linear in the size of the map. In fact there is little usage for list maps in Scala because standard immutable maps are almost always faster. The only possible exception to this is if the map is for some reason constructed in such a way that the first elements in the list are selected much more often than the other elements. + +{% tabs ListMap_1 %} +{% tab 'Scala 2 and 3' for=ListMap_1 %} +~~~scala +scala> val map = scala.collection.immutable.ListMap(1->"one", 2->"two") +map: scala.collection.immutable.ListMap[Int,java.lang.String] = + Map(1 -> one, 2 -> two) +scala> map(2) +res30: String = "two" +~~~ +{% endtab %} +{% endtabs %} diff --git a/_overviews/collections-2.13/concrete-mutable-collection-classes.md b/_overviews/collections-2.13/concrete-mutable-collection-classes.md new file mode 100644 index 0000000000..0de0bb1996 --- /dev/null +++ b/_overviews/collections-2.13/concrete-mutable-collection-classes.md @@ -0,0 +1,253 @@ +--- +layout: multipage-overview +title: Concrete Mutable Collection Classes +partof: collections-213 +overview-name: Collections + +num: 9 +previous-page: concrete-immutable-collection-classes +next-page: arrays + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +You've now seen the most commonly used immutable collection classes that Scala provides in its standard library. Take a look now at the mutable collection classes. + +## Array Buffers + +An [ArrayBuffer](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayBuffer.html) holds an array and a size. Most operations on an array buffer have the same speed as for an array, because the operations simply access and modify the underlying array. Additionally, array buffers can have data efficiently added to the end. Appending an item to an array buffer takes amortized constant time. Thus, array buffers are useful for efficiently building up a large collection whenever the new items are always added to the end. + +{% tabs ArrayBuffer_1 %} +{% tab 'Scala 2 and 3' for=ArrayBuffer_1 %} +~~~scala +scala> val buf = scala.collection.mutable.ArrayBuffer.empty[Int] +buf: scala.collection.mutable.ArrayBuffer[Int] = ArrayBuffer() +scala> buf += 1 +res32: buf.type = ArrayBuffer(1) +scala> buf += 10 +res33: buf.type = ArrayBuffer(1, 10) +scala> buf.toArray +res34: Array[Int] = Array(1, 10) +~~~ +{% endtab %} +{% endtabs %} + +## List Buffers + +A [ListBuffer](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ListBuffer.html) is like an array buffer except that it uses a linked list internally instead of an array. If you plan to convert the buffer to a list once it is built up, use a list buffer instead of an array buffer. + +{% tabs ListBuffer_1 %} +{% tab 'Scala 2 and 3' for=ListBuffer_1 %} +~~~scala +scala> val buf = scala.collection.mutable.ListBuffer.empty[Int] +buf: scala.collection.mutable.ListBuffer[Int] = ListBuffer() +scala> buf += 1 +res35: buf.type = ListBuffer(1) +scala> buf += 10 +res36: buf.type = ListBuffer(1, 10) +scala> buf.to(List) +res37: List[Int] = List(1, 10) +~~~ +{% endtab %} +{% endtabs %} + +## StringBuilders + +Just like an array buffer is useful for building arrays, and a list buffer is useful for building lists, a [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html) is useful for building strings. String builders are so commonly used that they are already imported into the default namespace. Create them with a simple `new StringBuilder`, like this: + +{% tabs StringBuilders_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=StringBuilders_1 %} +~~~scala +scala> val buf = new StringBuilder +buf: StringBuilder = +scala> buf += 'a' +res38: buf.type = a +scala> buf ++= "bcdef" +res39: buf.type = abcdef +scala> buf.toString +res41: String = abcdef +~~~ +{% endtab %} +{% tab 'Scala 3' for=StringBuilders_1 %} +~~~scala +scala> val buf = StringBuilder() +buf: StringBuilder = +scala> buf += 'a' +res38: buf.type = a +scala> buf ++= "bcdef" +res39: buf.type = abcdef +scala> buf.toString +res41: String = abcdef +~~~ +{% endtab %} +{% endtabs %} + +## ArrayDeque + +An [ArrayDeque](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayDeque.html) +is a sequence that supports efficient addition of elements in the front and in the end. +It internally uses a resizable array. + +If you need to append and prepend elements to a buffer, use an `ArrayDeque` instead of +an `ArrayBuffer`. + +## Queues + +Scala provides mutable queues in addition to immutable ones. You use a `mQueue` similarly to how you use an immutable one, but instead of `enqueue`, you use the `+=` and `++=` operators to append. Also, on a mutable queue, the `dequeue` method will just remove the head element from the queue and return it. Here's an example: + +{% tabs Queues_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=Queues_1 %} +~~~scala +scala> val queue = new scala.collection.mutable.Queue[String] +queue: scala.collection.mutable.Queue[String] = Queue() +scala> queue += "a" +res10: queue.type = Queue(a) +scala> queue ++= List("b", "c") +res11: queue.type = Queue(a, b, c) +scala> queue +res12: scala.collection.mutable.Queue[String] = Queue(a, b, c) +scala> queue.dequeue +res13: String = a +scala> queue +res14: scala.collection.mutable.Queue[String] = Queue(b, c) +~~~ +{% endtab %} +{% tab 'Scala 3' for=Queues_1 %} +~~~scala +scala> val queue = scala.collection.mutable.Queue[String]() +queue: scala.collection.mutable.Queue[String] = Queue() +scala> queue += "a" +res10: queue.type = Queue(a) +scala> queue ++= List("b", "c") +res11: queue.type = Queue(a, b, c) +scala> queue +res12: scala.collection.mutable.Queue[String] = Queue(a, b, c) +scala> queue.dequeue +res13: String = a +scala> queue +res14: scala.collection.mutable.Queue[String] = Queue(b, c) +~~~ +{% endtab %} +{% endtabs %} + +## Stacks + +A stack implements a data structure which allows to store and retrieve objects in a last-in-first-out (LIFO) fashion. +It is supported by class [mutable.Stack](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/Stack.html). + +{% tabs Stacks_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=Stacks_1 %} +~~~scala +scala> val stack = new scala.collection.mutable.Stack[Int] +stack: scala.collection.mutable.Stack[Int] = Stack() +scala> stack.push(1) +res0: stack.type = Stack(1) +scala> stack +res1: scala.collection.mutable.Stack[Int] = Stack(1) +scala> stack.push(2) +res0: stack.type = Stack(1, 2) +scala> stack +res3: scala.collection.mutable.Stack[Int] = Stack(2, 1) +scala> stack.top +res8: Int = 2 +scala> stack +res9: scala.collection.mutable.Stack[Int] = Stack(2, 1) +scala> stack.pop +res10: Int = 2 +scala> stack +res11: scala.collection.mutable.Stack[Int] = Stack(1) +~~~ +{% endtab %} +{% tab 'Scala 3' for=Stacks_1 %} +~~~scala +scala> val stack = scala.collection.mutable.Stack[Int]() +stack: scala.collection.mutable.Stack[Int] = Stack() +scala> stack.push(1) +res0: stack.type = Stack(1) +scala> stack +res1: scala.collection.mutable.Stack[Int] = Stack(1) +scala> stack.push(2) +res0: stack.type = Stack(1, 2) +scala> stack +res3: scala.collection.mutable.Stack[Int] = Stack(2, 1) +scala> stack.top +res8: Int = 2 +scala> stack +res9: scala.collection.mutable.Stack[Int] = Stack(2, 1) +scala> stack.pop +res10: Int = 2 +scala> stack +res11: scala.collection.mutable.Stack[Int] = Stack(1) +~~~ +{% endtab %} +{% endtabs %} + +## Mutable ArraySeqs + +Array sequences are mutable sequences of fixed size which store their elements internally in an `Array[Object]`. They are implemented in Scala by class [ArraySeq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArraySeq.html). + +You would typically use an `ArraySeq` if you want an array for its performance characteristics, but you also want to create generic instances of the sequence where you do not know the type of the elements, and you do not have a `ClassTag` to provide it at run-time. These issues are explained in the section on [arrays]({% link _overviews/collections-2.13/arrays.md %}). + +## Hash Tables + +A hash table stores its elements in an underlying array, placing each item at a position in the array determined by the hash code of that item. Adding an element to a hash table takes only constant time, so long as there isn't already another element in the array that has the same hash code. Hash tables are thus very fast so long as the objects placed in them have a good distribution of hash codes. As a result, the default mutable map and set types in Scala are based on hash tables. You can access them also directly under the names [mutable.HashSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashSet.html) and [mutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashMap.html). + +Hash sets and maps are used just like any other set or map. Here are some simple examples: + +{% tabs Hash-Tables_1 %} +{% tab 'Scala 2 and 3' for=Hash-Tables_1 %} +~~~scala +scala> val map = scala.collection.mutable.HashMap.empty[Int,String] +map: scala.collection.mutable.HashMap[Int,String] = Map() +scala> map += (1 -> "make a web site") +res42: map.type = Map(1 -> make a web site) +scala> map += (3 -> "profit!") +res43: map.type = Map(1 -> make a web site, 3 -> profit!) +scala> map(1) +res44: String = make a web site +scala> map contains 2 +res46: Boolean = false +~~~ +{% endtab %} +{% endtabs %} + +Iteration over a hash table is not guaranteed to occur in any particular order. Iteration simply proceeds through the underlying array in whichever order it happens to be in. To get a guaranteed iteration order, use a _linked_ hash map or set instead of a regular one. A linked hash map or set is just like a regular hash map or set except that it also includes a linked list of the elements in the order they were added. Iteration over such a collection is always in the same order that the elements were initially added. + +## Weak Hash Maps + +A weak hash map is a special kind of hash map where the garbage collector does not follow links from the map to the keys stored in it. This means that a key and its associated value will disappear from the map if there is no other reference to that key. Weak hash maps are useful for tasks such as caching, where you want to re-use an expensive function's result if the function is called again on the same key. If keys and function results are stored in a regular hash map, the map could grow without bounds, and no key would ever become garbage. Using a weak hash map avoids this problem. As soon as a key object becomes unreachable, it's entry is removed from the weak hashmap. Weak hash maps in Scala are implemented by class [WeakHashMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/WeakHashMap.html) as a wrapper of an underlying Java implementation `java.util.WeakHashMap`. + +## Concurrent Maps + +A concurrent map can be accessed by several threads at once. In addition to the usual [Map](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html) operations, it provides the following atomic operations: + +### Operations in Class concurrent.Map + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| `m.putIfAbsent(k, v)` |Adds key/value binding `k -> v` unless `k` is already defined in `m` | +| `m.remove(k, v)` |Removes entry for `k` if it is currently mapped to `v`. | +| `m.replace(k, old, new)` |Replaces value associated with key `k` to `new`, if it was previously bound to `old`. | +| `m.replace (k, v)` |Replaces value associated with key `k` to `v`, if it was previously bound to some value.| + +`concurrent.Map` is a trait in the Scala collections library. Currently, it has two implementations. The first one is Java's `java.util.concurrent.ConcurrentMap`, which can be converted automatically into a Scala map using the [standard Java/Scala collection conversions]({% link _overviews/collections-2.13/conversions-between-java-and-scala-collections.md %}). The second implementation is [TrieMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/concurrent/TrieMap.html), which is a lock-free implementation of a hash array mapped trie. + +## Mutable Bitsets + +A mutable bit of type [mutable.BitSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/BitSet.html) set is just like an immutable one, except that it is modified in place. Mutable bit sets are slightly more efficient at updating than immutable ones, because they don't have to copy around `Long`s that haven't changed. + +{% tabs BitSet_1 %} +{% tab 'Scala 2 and 3' for=BitSet_1 %} +~~~scala +scala> val bits = scala.collection.mutable.BitSet.empty +bits: scala.collection.mutable.BitSet = BitSet() +scala> bits += 1 +res49: bits.type = BitSet(1) +scala> bits += 3 +res50: bits.type = BitSet(1, 3) +scala> bits +res51: scala.collection.mutable.BitSet = BitSet(1, 3) +~~~ +{% endtab %} +{% endtabs %} diff --git a/_overviews/collections-2.13/conversion-between-option-and-the-collections.md b/_overviews/collections-2.13/conversion-between-option-and-the-collections.md new file mode 100644 index 0000000000..d1b2e771cf --- /dev/null +++ b/_overviews/collections-2.13/conversion-between-option-and-the-collections.md @@ -0,0 +1,81 @@ +--- +layout: multipage-overview +title: Conversion Between Option and the Collections +partof: collections-213 +overview-name: Collections + +num: 18 +previous-page: conversions-between-java-and-scala-collections + +permalink: /overviews/collections-2.13/:title.html +--- +`Option` can be seen as a collection that has zero or exactly one element, and it provides a degree of interoperability with the collection types found in the package `scala.collection`. In particular, it implements the interface `IterableOnce`, which models the simplest form of collections: something that can be iterated over, at least once. However, `Option` does not implement the more comprehensive interface of `Iterable`. Indeed, we cannot provide a sensible implementation for the operation [`fromSpecific`](https://github.com/scala/scala/blob/6c68c2825e893bb71d6dc78465ac8c6f415cbd93/src/library/scala/collection/Iterable.scala#L173), which is supposed to create an `Option` from a collection of possibly more than one element. Starting from [Scala 2.13](https://github.com/scala/scala/pull/8038), `Option` was made an `IterableOnce` but not an `Iterable`. + +Hence `Option` can be used everywhere an `IterableOnce` is expected, for example, when calling `flatMap` on a collection (or inside a for-comprehension) + +{% tabs options_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=options_1 %} +```scala mdoc +for { + a <- Set(1) + b <- Option(41) +} yield (a + b) +// : Set[Int] = Set(42) +``` +{% endtab %} +{% tab 'Scala 3' for=options_1 %} +```scala +for + a <- Set(1) + b <- Option(41) +yield (a + b) +// : Set[Int] = Set(42) +``` +{% endtab %} +{% endtabs %} + +since the operation `flatMap` on the type `Set[Int]` takes a function returning an `IterableOnce`: + +{% tabs options_2 %} +{% tab 'Scala 2 and 3' for=options_2 %} +``` +def flatMap[B](f: Int => IterableOnce[B]): Set[B] +``` +{% endtab %} +{% endtabs %} + +Although `Option` does not extend `Iterable`, there exists an [implicit conversion](https://github.com/scala/scala/blob/6c68c2825e893bb71d6dc78465ac8c6f415cbd93/src/library/scala/Option.scala#L19) between `Option` and `Iterable` + +{% tabs options_3 %} +{% tab 'Scala 2 and 3' for=options_3 %} +``` +implicit def option2Iterable[A](xo: Option[A]): Iterable[A] +``` +{% endtab %} +{% endtabs %} + +so although `Option[A]` is not a full collection it can be _viewed_ as one. For example, + +{% tabs options_4 %} +{% tab 'Scala 2 and 3' for=options_4 %} +```scala mdoc +Some(42).drop(1) +// : Iterable[Int] = List() +``` +{% endtab %} +{% endtabs %} + +expands to + +{% tabs options_5 %} +{% tab 'Scala 2 and 3' for=options_5 %} +```scala mdoc +Option.option2Iterable(Some(42)).drop(1) +// : Iterable[Int] = List() +``` +{% endtab %} +{% endtabs %} + +because `drop` is not defined on `Option`. A downside of the above implicit conversion is that instead of getting back an `Option[A]` we are left with an `Iterable[A]`. For this reason, `Option`’s documentation carries the following note: + +> Many of the methods in `Option` are duplicative with those in the `Iterable` hierarchy, but they are duplicated for a reason: the implicit conversion tends to leave one with an `Iterable` in situations where one could have retained an `Option`. diff --git a/_overviews/collections-2.13/conversions-between-java-and-scala-collections.md b/_overviews/collections-2.13/conversions-between-java-and-scala-collections.md new file mode 100644 index 0000000000..d66183d84a --- /dev/null +++ b/_overviews/collections-2.13/conversions-between-java-and-scala-collections.md @@ -0,0 +1,116 @@ +--- +layout: multipage-overview +title: Conversions Between Java and Scala Collections +partof: collections-213 +overview-name: Collections + +num: 17 +previous-page: creating-collections-from-scratch +next-page: conversion-between-option-and-the-collections + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +Like Scala, Java also has a rich collections library. There are many similarities between the two. For instance, both libraries know iterators, iterables, sets, maps, and sequences. But there are also important differences. In particular, the Scala libraries put much more emphasis on immutable collections, and provide many more operations that transform a collection into a new one. + +Sometimes you might need to pass from one collection framework to the other. For instance, you might want to access an existing Java collection as if it were a Scala collection. Or you might want to pass one of Scala's collections to a Java method that expects its Java counterpart. It is quite easy to do this, because Scala offers implicit conversions between all the major collection types in the [CollectionConverters](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/jdk/CollectionConverters$.html) object. In particular, you will find bidirectional conversions between the following types. + +``` +Iterator <=> java.util.Iterator +Iterator <=> java.util.Enumeration +Iterable <=> java.lang.Iterable +Iterable <=> java.util.Collection +mutable.Buffer <=> java.util.List +mutable.Set <=> java.util.Set +mutable.Map <=> java.util.Map +mutable.ConcurrentMap <=> java.util.concurrent.ConcurrentMap +``` + +To enable these conversions, import them from the [CollectionConverters](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/jdk/CollectionConverters$.html) object: + +{% tabs java_scala_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=java_scala_1 %} + +```scala +scala> import scala.jdk.CollectionConverters._ +import scala.jdk.CollectionConverters._ +``` + +{% endtab %} +{% tab 'Scala 3' for=java_scala_1 %} + +```scala +scala> import scala.jdk.CollectionConverters.* +import scala.jdk.CollectionConverters.* +``` + +{% endtab %} +{% endtabs %} + +This enables conversions between Scala collections and their corresponding Java collections by way of extension methods called `asScala` and `asJava`: + +{% tabs java_scala_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=java_scala_2 %} + +```scala +scala> import collection.mutable._ +import collection.mutable._ + +scala> val jul: java.util.List[Int] = ArrayBuffer(1, 2, 3).asJava +val jul: java.util.List[Int] = [1, 2, 3] + +scala> val buf: Seq[Int] = jul.asScala +val buf: scala.collection.mutable.Seq[Int] = ArrayBuffer(1, 2, 3) + +scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2).asJava +val m: java.util.Map[String,Int] = {abc=1, hello=2} +``` + +{% endtab %} +{% tab 'Scala 3' for=java_scala_2 %} + +```scala +scala> import collection.mutable.* +import collection.mutable.* + +scala> val jul: java.util.List[Int] = ArrayBuffer(1, 2, 3).asJava +val jul: java.util.List[Int] = [1, 2, 3] + +scala> val buf: Seq[Int] = jul.asScala +val buf: scala.collection.mutable.Seq[Int] = ArrayBuffer(1, 2, 3) + +scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2).asJava +val m: java.util.Map[String,Int] = {abc=1, hello=2} +``` + +{% endtab %} +{% endtabs %} + +Internally, these conversion work by setting up a "wrapper" object that forwards all operations to the underlying collection object. So collections are never copied when converting between Java and Scala. An interesting property is that if you do a round-trip conversion from, say a Java type to its corresponding Scala type, and back to the same Java type, you end up with the identical collection object you have started with. + +Certain other Scala collections can also be converted to Java, but do not have a conversion back to the original Scala type: + +``` +Seq => java.util.List +mutable.Seq => java.util.List +Set => java.util.Set +Map => java.util.Map +``` + +Because Java does not distinguish between mutable and immutable collections in their type, a conversion from, say, `scala.immutable.List` will yield a `java.util.List`, where all mutation operations throw an "UnsupportedOperationException". Here's an example: + +{% tabs java_scala_3 %} +{% tab 'Scala 2 and 3' for=java_scala_3 %} + +```scala +scala> val jul = List(1, 2, 3).asJava +val jul: java.util.List[Int] = [1, 2, 3] + +scala> jul.add(7) +java.lang.UnsupportedOperationException + at java.util.AbstractList.add(AbstractList.java:148) +``` + +{% endtab %} +{% endtabs %} diff --git a/_overviews/collections-2.13/creating-collections-from-scratch.md b/_overviews/collections-2.13/creating-collections-from-scratch.md new file mode 100644 index 0000000000..9f10410750 --- /dev/null +++ b/_overviews/collections-2.13/creating-collections-from-scratch.md @@ -0,0 +1,88 @@ +--- +layout: multipage-overview +title: Creating Collections From Scratch +partof: collections-213 +overview-name: Collections + +num: 16 +previous-page: iterators +next-page: conversions-between-java-and-scala-collections + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +You have syntax `List(1, 2, 3)` to create a list of three integers and `Map('A' -> 1, 'C' -> 2)` to create a map with two bindings. This is actually a universal feature of Scala collections. You can take any collection name and follow it by a list of elements in parentheses. The result will be a new collection with the given elements. Here are some more examples: + +{% tabs creating_1 %} +{% tab 'Scala 2 and 3' for=creating_1 %} + +```scala +val a = Iterable() // An empty collection +val b = List() // The empty list +val c = List(1.0, 2.0) // A list with elements 1.0, 2.0 +val d = Vector(1.0, 2.0) // A vector with elements 1.0, 2.0 +val e = Iterator(1, 2, 3) // An iterator returning three integers. +val f = Set(dog, cat, bird) // A set of three animals +val g = HashSet(dog, cat, bird) // A hash set of the same animals +val h = Map('a' -> 7, 'b' -> 0) // A map from characters to integers +``` + +{% endtab %} +{% endtabs %} + +"Under the covers" each of the above lines is a call to the `apply` method of some object. For instance, the third line above expands to + +{% tabs creating_2 %} +{% tab 'Scala 2 and 3' for=creating_2 %} + +```scala +val c = List.apply(1.0, 2.0) +``` + +{% endtab %} +{% endtabs %} + +So this is a call to the `apply` method of the companion object of the `List` class. That method takes an arbitrary number of arguments and constructs a list from them. Every collection class in the Scala library has a companion object with such an `apply` method. It does not matter whether the collection class represents a concrete implementation, like `List`, `LazyList` or `Vector`, or whether it is an abstract base class such as `Seq`, `Set` or `Iterable`. In the latter case, calling apply will produce some default implementation of the abstract base class. Examples: + +{% tabs creating_3 %} +{% tab 'Scala 2 and 3' for=creating_3 %} + +```scala +scala> List(1, 2, 3) +val res17: List[Int] = List(1, 2, 3) + +scala> Iterable(1, 2, 3) +val res18: Iterable[Int] = List(1, 2, 3) + +scala> mutable.Iterable(1, 2, 3) +val res19: scala.collection.mutable.Iterable[Int] = ArrayBuffer(1, 2, 3) +``` + +{% endtab %} +{% endtabs %} + +Besides `apply`, every collection companion object also defines a member `empty`, which returns an empty collection. So instead of `List()` you could write `List.empty`, instead of `Map()`, `Map.empty`, and so on. + +The operations provided by collection companion objects are summarized in the following table. In short, there's + +* `concat`, which concatenates an arbitrary number of collections together, +* `fill` and `tabulate`, which generate single or multidimensional collections of given dimensions initialized by some expression or tabulating function, +* `range`, which generates integer collections with some constant step length, and +* `iterate` and `unfold`, which generates the collection resulting from repeated application of a function to a start element or state. + +### Factory Methods for Sequences + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| `C.empty` | The empty collection. | +| `C(x, y, z)` | A collection consisting of elements `x, y, z`. | +| `C.concat(xs, ys, zs)` | The collection obtained by concatenating the elements of `xs, ys, zs`. | +| `C.fill(n){e}` | A collection of length `n` where each element is computed by expression `e`. | +| `C.fill(m, n){e}` | A collection of collections of dimension `m×n` where each element is computed by expression `e`. (exists also in higher dimensions). | +| `C.tabulate(n){f}` | A collection of length `n` where the element at each index i is computed by `f(i)`. | +| `C.tabulate(m, n){f}` | A collection of collections of dimension `m×n` where the element at each index `(i, j)` is computed by `f(i, j)`. (exists also in higher dimensions). | +| `C.range(start, end)` | The collection of integers `start` ... `end-1`. | +| `C.range(start, end, step)`| The collection of integers starting with `start` and progressing by `step` increments up to, and excluding, the `end` value. | +| `C.iterate(x, n)(f)` | The collection of length `n` with elements `x`, `f(x)`, `f(f(x))`, ... | +| `C.unfold(init)(f)` | A collection that uses a function `f` to compute its next element and state, starting from the `init` state.| diff --git a/_overviews/collections-2.13/equality.md b/_overviews/collections-2.13/equality.md new file mode 100644 index 0000000000..7fa334c8d9 --- /dev/null +++ b/_overviews/collections-2.13/equality.md @@ -0,0 +1,47 @@ +--- +layout: multipage-overview +title: Equality +partof: collections-213 +overview-name: Collections + +num: 13 +previous-page: performance-characteristics +next-page: views + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +The collection libraries have a uniform approach to equality and hashing. The idea is, first, to divide collections into sets, maps, and sequences. Collections in different categories are always unequal. For instance, `Set(1, 2, 3)` is unequal to `List(1, 2, 3)` even though they contain the same elements. On the other hand, within the same category, collections are equal if and only if they have the same elements (for sequences: the same elements in the same order). For example, `List(1, 2, 3) == Vector(1, 2, 3)`, and `HashSet(1, 2) == TreeSet(2, 1)`. + +It does not matter for the equality check whether a collection is mutable or immutable. For a mutable collection one simply considers its current elements at the time the equality test is performed. This means that a mutable collection might be equal to different collections at different times, depending on what elements are added or removed. This is a potential trap when using a mutable collection as a key in a hashmap. Example: + +{% tabs equality_1 %} +{% tab 'Scala 2 and 3' for=equality_1 %} + +```scala +scala> import collection.mutable.{HashMap, ArrayBuffer} +import collection.mutable.{HashMap, ArrayBuffer} + +scala> val buf = ArrayBuffer(1, 2, 3) +val buf: scala.collection.mutable.ArrayBuffer[Int] = + ArrayBuffer(1, 2, 3) + +scala> val map = HashMap(buf -> 3) +val map: scala.collection.mutable.HashMap[scala.collection. + mutable.ArrayBuffer[Int],Int] = Map((ArrayBuffer(1, 2, 3),3)) + +scala> map(buf) +val res13: Int = 3 + +scala> buf(0) += 1 + +scala> map(buf) + java.util.NoSuchElementException: key not found: + ArrayBuffer(2, 2, 3) +``` + +{% endtab %} +{% endtabs %} + +In this example, the selection in the last line will most likely fail because the hash-code of the array `buf` has changed in the second-to-last line. Therefore, the hash-code-based lookup will look at a different place than the one where `buf` was stored. diff --git a/_overviews/collections-2.13/introduction.md b/_overviews/collections-2.13/introduction.md new file mode 100644 index 0000000000..2e4d5f8abb --- /dev/null +++ b/_overviews/collections-2.13/introduction.md @@ -0,0 +1,100 @@ +--- +layout: multipage-overview +title: Introduction +partof: collections-213 +overview-name: Collections + +num: 1 +next-page: overview + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +The collections framework is the heart of the Scala 2.13 standard +library, also used in Scala 3.x. It provides a common, uniform, and all-encompassing +framework for collection types. This framework enables you to work +with data in memory at a high level, with the basic building blocks of +a program being whole collections, instead of individual elements. + +This style of programming requires some learning. Fortunately, +the adaptation is helped by several nice properties of the Scala +collections. They are easy to use, concise, safe, fast, universal. + +**Easy to use:** A small vocabulary of 20-50 methods is +enough to solve most collection problems in a couple of operations. No +need to wrap your head around complicated looping structures or +recursions. Persistent collections and side-effect-free operations mean +that you need not worry about accidentally corrupting existing +collections with new data. Interference between iterators and +collection updates is eliminated. + +**Concise:** You can achieve with a single word what used to +take one or several loops. You can express functional operations with +lightweight syntax and combine operations effortlessly, so that the result +feels like a custom algebra. + +**Safe:** This one has to be experienced to sink in. The +statically typed and functional nature of Scala's collections means +that the overwhelming majority of errors you might make are caught at +compile-time. The reason is that (1) the collection operations +themselves are heavily used and therefore well +tested. (2) the usages of the collection operation make inputs and +output explicit as function parameters and results. (3) These explicit +inputs and outputs are subject to static type checking. The bottom line +is that the large majority of misuses will manifest themselves as type +errors. It's not at all uncommon to have programs of several hundred +lines run at first try. + +**Fast:** Collection operations are tuned and optimized in the +libraries. As a result, using collections is typically quite +efficient. You might be able to do a little better with carefully +hand-tuned data structures and operations, but you might also do a lot +worse by making some suboptimal implementation decisions along the +way. + +**Parallel**: The +[`scala-parallel-collections` module](https://index.scala-lang.org/scala/scala-parallel-collections/scala-parallel-collections) +provides parallel execution of collections operations across multiple cores. +Parallel collections generally support the same +operations as sequential ones. You can turn a sequential collection into a +parallel one simply by invoking the `par` method. + +**Universal:** Collections provide the same operations on +any type where it makes sense to do so. So you can achieve a lot with +a fairly small vocabulary of operations. For instance, a string is +conceptually a sequence of characters. Consequently, in Scala +collections, strings support all sequence operations. The same holds +for arrays. + +**Example:** Here's one line of code that demonstrates many of the +advantages of Scala's collections. + +{% tabs introduction_1 %} +{% tab 'Scala 2 and 3' for=introduction_1 %} +``` +val (minors, adults) = people partition (_.age < 18) +``` +{% endtab %} +{% endtabs %} + +It's immediately clear what this operation does: It partitions a +collection of `people` into `minors` and `adults` depending on +their age. Because the `partition` method is defined in the root +collection type `IterableOps`, this code works for any kind of +collection, including arrays. The resulting `minors` and `adults` +collections will be of the same type as the `people` collection. + +This code is much more concise than the one to three loops required for +traditional collection processing (three loops for an array, because +the intermediate results need to be buffered somewhere else). Once +you have learned the basic collection vocabulary you will also find +writing this code is much easier and safer than writing explicit +loops. + +Furthermore, the `partition` operation is quite fast, and can +be even faster on parallel collections on multiple cores. + +This document provides an in depth discussion of the APIs of the +Scala collections classes from a user's perspective. It takes you on +a tour of all the fundamental classes and the methods they define. diff --git a/_overviews/collections-2.13/iterators.md b/_overviews/collections-2.13/iterators.md new file mode 100644 index 0000000000..a72716740d --- /dev/null +++ b/_overviews/collections-2.13/iterators.md @@ -0,0 +1,372 @@ +--- +layout: multipage-overview +title: Iterators +partof: collections-213 +overview-name: Collections + +num: 15 +previous-page: views +next-page: creating-collections-from-scratch + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +An iterator is not a collection, but rather a way to access the elements of a collection one by one. The two basic operations on an iterator `it` are `next` and `hasNext`. A call to `it.next()` will return the next element of the iterator and advance the state of the iterator. Calling `next` again on the same iterator will then yield the element one beyond the one returned previously. If there are no more elements to return, a call to `next` will throw a `NoSuchElementException`. You can find out whether there are more elements to return using [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html)'s `hasNext` method. + +The most straightforward way to "step through" all the elements returned by an iterator `it` uses a while-loop: + +{% tabs iterators_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=iterators_1 %} +```scala +while (it.hasNext) + println(it.next()) +``` +{% endtab %} +{% tab 'Scala 3' for=iterators_1 %} +```scala +while it.hasNext do + println(it.next()) +``` +{% endtab %} +{% endtabs %} + +Iterators in Scala also provide analogues of most of the methods that you find in the `Iterable` and `Seq` classes. For instance, they provide a `foreach` method which executes a given procedure on each element returned by an iterator. Using `foreach`, the loop above could be abbreviated to: + +{% tabs iterators_2 %} +{% tab 'Scala 2 and 3' for=iterators_2 %} + +```scala +it.foreach(println) +``` + +{% endtab %} +{% endtabs %} + +As always, for-expressions can be used as an alternate syntax for expressions involving `foreach`, `map`, `withFilter`, and `flatMap`, so yet another way to print all elements returned by an iterator would be: + +{% tabs iterators_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=iterators_3 %} +```scala +for (elem <- it) println(elem) +``` +{% endtab %} +{% tab 'Scala 3' for=iterators_3 %} +```scala +for elem <- it do println(elem) +``` +{% endtab %} +{% endtabs %} + +There's an important difference between the foreach method on iterators and the same method on iterable collections: When called on an iterator, `foreach` will leave the iterator at its end when it is done. So calling `next` again on the same iterator will fail with a `NoSuchElementException`. By contrast, when called on a collection, `foreach` leaves the number of elements in the collection unchanged (unless the passed function adds or removes elements, but this is discouraged, because it may lead to surprising results). + +The other operations that `Iterator` has in common with `Iterable` have the same property. For instance, iterators provide a `map` method, which returns a new iterator: + +{% tabs iterators_4 %} +{% tab 'Scala 2 and 3' for=iterators_4 %} + +```scala +scala> val it = Iterator("a", "number", "of", "words") +val it: Iterator[java.lang.String] = + +scala> it.map(_.length) +val res1: Iterator[Int] = + +scala> it.hasNext +val res2: Boolean = true + +scala> res1.foreach(println) +1 +6 +2 +5 + +scala> it.hasNext +val res4: Boolean = false +``` + +{% endtab %} +{% endtabs %} + +As you can see, after the call to `it.map`, the `it` iterator hasn’t advanced to its end, but traversing the iterator +resulting from the call to `res1.foreach` also traverses `it` and advances it to its end. + +Another example is the `dropWhile` method, which can be used to find the first elements of an iterator that has a certain property. For instance, to find the first word in the iterator above that has at least two characters you could write: + +{% tabs iterators_5 %} +{% tab 'Scala 2 and 3' for=iterators_5 %} + +```scala +scala> val it = Iterator("a", "number", "of", "words") +val it: Iterator[java.lang.String] = + +scala> it.dropWhile(_.length < 2) +val res4: Iterator[java.lang.String] = + +scala> res4.next() +val res5: java.lang.String = number +``` + +{% endtab %} +{% endtabs %} + +Note again that `it` was changed by the call to `dropWhile`: it now points to the second word "number" in the list. +In fact, `it` and the result `res4` returned by `dropWhile` will return exactly the same sequence of elements. + +One way to circumvent this behavior is to `duplicate` the underlying iterator instead of calling methods on it directly. +The _two_ iterators that result will each return exactly the same elements as the underlying iterator `it`: + +{% tabs iterators_6 %} +{% tab 'Scala 2 and 3' for=iterators_6 %} + +```scala +scala> val (words, ns) = Iterator("a", "number", "of", "words").duplicate +val words: Iterator[String] = +val ns: Iterator[String] = + +scala> val shorts = words.filter(_.length < 3).toList +val shorts: List[String] = List(a, of) + +scala> val count = ns.map(_.length).sum +val count: Int = 14 +``` + +{% endtab %} +{% endtabs %} + +The two iterators work independently: advancing one does not affect the other, so that each can be +destructively modified by invoking arbitrary methods. This creates the illusion of iterating over +the elements twice, but the effect is achieved through internal buffering. +As usual, the underlying iterator `it` cannot be used directly and must be discarded. + +In summary, iterators behave like collections _if one never accesses an iterator again after invoking a method on it_. The Scala collection libraries make this explicit with an abstraction [IterableOnce](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IterableOnce.html), which is a common superclass of [Iterable](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) and [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html). `IterableOnce[A]` only has two methods: `iterator: Iterator[A]` and `knownSize: Int`. If an `IterableOnce` object is in fact an `Iterator`, its `iterator` operation always returns itself, in its current state, but if it is an `Iterable`, its `iterator` operation always return a new `Iterator`. A common use case of `IterableOnce` is as an argument type for methods that can take either an iterator or a collection as argument. An example is the appending method `concat` in class `Iterable`. It takes an `IterableOnce` parameter, so you can append elements coming from either an iterator or a collection. + +All operations on iterators are summarized below. + +### Operations in class Iterator + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Abstract Methods:** | | +| `it.next()` | Returns next element on iterator and advances past it. | +| `it.hasNext` | Returns `true` if `it` can return another element. | +| **Variations:** | | +| `it.buffered` | A buffered iterator returning all elements of `it`. | +| `it.grouped(size)` | An iterator that yields the elements returned by `it` in fixed-sized sequence "chunks". | +| `it.sliding(size)` | An iterator that yields the elements returned by `it` in sequences representing a sliding fixed-sized window. | +| **Duplication:** | | +| `it.duplicate` | A pair of iterators that each independently return all elements of `it`. | +| **Additions:** | | +| `it.concat(jt)`
            or `it ++ jt` | An iterator returning all elements returned by iterator `it`, followed by all elements returned by iterator `jt`. | +| `it.padTo(len, x)` | The iterator that first returns all elements of `it` and then follows that by copies of `x` until length `len` elements are returned overall. | +| **Maps:** | | +| `it.map(f)` | The iterator obtained from applying the function `f` to every element returned from `it`. | +| `it.flatMap(f)` | The iterator obtained from applying the iterator-valued function `f` to every element in `it` and appending the results. | +| `it.collect(f)` | The iterator obtained from applying the partial function `f` to every element in `it` for which it is defined and collecting the results. | +| **Conversions:** | | +| `it.toArray` | Collects the elements returned by `it` in an array. | +| `it.toList` | Collects the elements returned by `it` in a list. | +| `it.toIterable` | Collects the elements returned by `it` in an iterable. | +| `it.toSeq` | Collects the elements returned by `it` in a sequence. | +| `it.toIndexedSeq` | Collects the elements returned by `it` in an indexed sequence. | +| `it.toLazyList` | Collects the elements returned by `it` in a lazy list. | +| `it.toSet` | Collects the elements returned by `it` in a set. | +| `it.toMap` | Collects the key/value pairs returned by `it` in a map. | +| **Copying:** | | +| `it.copyToArray(arr, s, n)`| Copies at most `n` elements returned by `it` to array `arr` starting at index `s`. The last two arguments are optional. | +| **Size Info:** | | +| `it.isEmpty` | Test whether the iterator is empty (opposite of `hasNext`). | +| `it.nonEmpty` | Test whether the collection contains elements (alias of `hasNext`). | +| `it.size` | The number of elements returned by `it`. Note: `it` will be at its end after this operation! | +| `it.length` | Same as `it.size`. | +| `it.knownSize` |The number of elements, if this one is known without modifying the iterator’s state, otherwise `-1`. | +| **Element Retrieval Index Search:**| | +| `it.find(p)` | An option containing the first element returned by `it` that satisfies `p`, or `None` is no element qualifies. Note: The iterator advances to after the element, or, if none is found, to the end. | +| `it.indexOf(x)` | The index of the first element returned by `it` that equals `x`. Note: The iterator advances past the position of this element. | +| `it.indexWhere(p)` | The index of the first element returned by `it` that satisfies `p`. Note: The iterator advances past the position of this element. | +| **Subiterators:** | | +| `it.take(n)` | An iterator returning of the first `n` elements of `it`. Note: it will advance to the position after the `n`'th element, or to its end, if it contains less than `n` elements. | +| `it.drop(n)` | The iterator that starts with the `(n+1)`'th element of `it`. Note: `it` will advance to the same position. | +| `it.slice(m,n)` | The iterator that returns a slice of the elements returned from it, starting with the `m`'th element and ending before the `n`'th element. | +| `it.takeWhile(p)` | An iterator returning elements from `it` as long as condition `p` is true. | +| `it.dropWhile(p)` | An iterator skipping elements from `it` as long as condition `p` is `true`, and returning the remainder. | +| `it.filter(p)` | An iterator returning all elements from `it` that satisfy the condition `p`. | +| `it.withFilter(p)` | Same as `it` filter `p`. Needed so that iterators can be used in for-expressions. | +| `it.filterNot(p)` | An iterator returning all elements from `it` that do not satisfy the condition `p`. | +| `it.distinct` | An iterator returning the elements from `it` without duplicates. | +| **Subdivisions:** | | +| `it.partition(p)` | Splits `it` into a pair of two iterators: one returning all elements from `it` that satisfy the predicate `p`, the other returning all elements from `it` that do not. | +| `it.span(p)` | Splits `it` into a pair of two iterators: one returning all elements of the prefix of `it` that satisfy the predicate `p`, the other returning all remaining elements of `it`. | +| **Element Conditions:** | | +| `it.forall(p)` | A boolean indicating whether the predicate p holds for all elements returned by `it`. | +| `it.exists(p)` | A boolean indicating whether the predicate p holds for some element in `it`. | +| `it.count(p)` | The number of elements in `it` that satisfy the predicate `p`. | +| **Folds:** | | +| `it.foldLeft(z)(op)` | Apply binary operation `op` between successive elements returned by `it`, going left to right and starting with `z`. | +| `it.foldRight(z)(op)` | Apply binary operation `op` between successive elements returned by `it`, going right to left and starting with `z`. | +| `it.reduceLeft(op)` | Apply binary operation `op` between successive elements returned by non-empty iterator `it`, going left to right. | +| `it.reduceRight(op)` | Apply binary operation `op` between successive elements returned by non-empty iterator `it`, going right to left. | +| **Specific Folds:** | | +| `it.sum` | The sum of the numeric element values returned by iterator `it`. | +| `it.product` | The product of the numeric element values returned by iterator `it`. | +| `it.min` | The minimum of the ordered element values returned by iterator `it`. | +| `it.max` | The maximum of the ordered element values returned by iterator `it`. | +| **Zippers:** | | +| `it.zip(jt)` | An iterator of pairs of corresponding elements returned from iterators `it` and `jt`. | +| `it.zipAll(jt, x, y)` | An iterator of pairs of corresponding elements returned from iterators `it` and `jt`, where the shorter iterator is extended to match the longer one by appending elements `x` or `y`. | +| `it.zipWithIndex` | An iterator of pairs of elements returned from `it` with their indices. | +| **Update:** | | +| `it.patch(i, jt, r)` | The iterator resulting from `it` by replacing `r` elements starting with `i` by the patch iterator `jt`. | +| **Comparison:** | | +| `it.sameElements(jt)` | A test whether iterators `it` and `jt` return the same elements in the same order. Note: Using the iterators after this operation is undefined and subject to change. | +| **Strings:** | | +| `it.addString(b, start, sep, end)`| Adds a string to `StringBuilder` `b` which shows all elements returned by `it` between separators `sep` enclosed in strings `start` and `end`. `start`, `sep`, `end` are all optional. | +| `it.mkString(start, sep, end)` | Converts the collection to a string which shows all elements returned by `it` between separators `sep` enclosed in strings `start` and `end`. `start`, `sep`, `end` are all optional. | + +### Laziness + +Unlike operations directly on a concrete collection like `List`, operations on `Iterator` are lazy. + +A lazy operation does not immediately compute all of its results. Instead, it computes the results as they are individually requested. + +So the expression `(1 to 10).iterator.map(println)` would not print anything to the screen. The `map` method in this case doesn't apply its argument function to the values in the range, it returns a new `Iterator` that will do this as each one is requested. Adding `.toList` to the end of that expression will actually print the elements. + +A consequence of this is that a method like `map` or `filter` won't necessarily apply its argument function to all the input elements. The expression `(1 to 10).iterator.map(println).take(5).toList` would only print the values `1` to `5`, for instance, since those are only ones that will be requested from the `Iterator` returned by `map`. + +This is one of the reasons why it's important to only use pure functions as arguments to `map`, `filter`, `fold` and similar methods. Remember, a pure function has no side-effects, so one would not normally use `println` in a `map`. `println` is used to demonstrate laziness as it's not normally visible with pure functions. + +Laziness is still valuable, despite often not being visible, as it can prevent unneeded computations from happening, and can allow for working with infinite sequences, like so: + +{% tabs iterators_7 %} +{% tab 'Scala 2 and 3' for=iterators_7 %} + +```scala +def zipWithIndex[A](i: Iterator[A]): Iterator[(Int, A)] = + Iterator.from(0).zip(i) +``` + +{% endtab %} +{% endtabs %} + +### Buffered iterators + +Sometimes you want an iterator that can "look ahead", so that you can inspect the next element to be returned without advancing past that element. Consider for instance, the task to skip leading empty strings from an iterator that returns a sequence of strings. You might be tempted to write the following + +{% tabs iterators_8 class=tabs-scala-version %} +{% tab 'Scala 2' for=iterators_8 %} +```scala mdoc +def skipEmptyWordsNOT(it: Iterator[String]) = + while (it.next().isEmpty) {} +``` +{% endtab %} +{% tab 'Scala 3' for=iterators_8 %} +```scala +def skipEmptyWordsNOT(it: Iterator[String]) = + while it.next().isEmpty do () +``` +{% endtab %} +{% endtabs %} + +But looking at this code more closely, it's clear that this is wrong: The code will indeed skip leading empty strings, but it will also advance `it` past the first non-empty string! + +The solution to this problem is to use a buffered iterator. Class [BufferedIterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BufferedIterator.html) is a subclass of [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html), which provides one extra method, `head`. Calling `head` on a buffered iterator will return its first element but will not advance the iterator. Using a buffered iterator, skipping empty words can be written as follows. + +{% tabs iterators_9 class=tabs-scala-version %} +{% tab 'Scala 2' for=iterators_9 %} +```scala +def skipEmptyWords(it: BufferedIterator[String]) = + while (it.head.isEmpty) { it.next() } +``` +{% endtab %} +{% tab 'Scala 3' for=iterators_9 %} +```scala +def skipEmptyWords(it: BufferedIterator[String]) = + while it.head.isEmpty do it.next() +``` +{% endtab %} +{% endtabs %} + +Every iterator can be converted to a buffered iterator by calling its `buffered` method. Here's an example: + +{% tabs iterators_10 %} +{% tab 'Scala 2 and 3' for=iterators_10 %} + +```scala +scala> val it = Iterator(1, 2, 3, 4) +val it: Iterator[Int] = + +scala> val bit = it.buffered +val bit: scala.collection.BufferedIterator[Int] = + +scala> bit.head +val res10: Int = 1 + +scala> bit.next() +val res11: Int = 1 + +scala> bit.next() +val res12: Int = 2 + +scala> bit.headOption +val res13: Option[Int] = Some(3) +``` + +{% endtab %} +{% endtabs %} + +Note that calling `head` on the buffered iterator `bit` does not advance it. Therefore, the subsequent call `bit.next()` returns the same value as `bit.head`. + +As usual, the underlying iterator must not be used directly and must be discarded. + +The buffered iterator only buffers the next element when `head` is invoked. Other derived iterators, +such as those produced by `duplicate` and `partition`, may buffer arbitrary subsequences of the +underlying iterator. But iterators can be efficiently joined by adding them together with `++`: + +{% tabs iterators_11 class=tabs-scala-version %} +{% tab 'Scala 2' for=iterators_11 %} + +```scala +scala> def collapse(it: Iterator[Int]) = if (!it.hasNext) Iterator.empty else { + | var head = it.next + | val rest = if (head == 0) it.dropWhile(_ == 0) else it + | Iterator.single(head) ++ rest + |} +def collapse(it: Iterator[Int]): Iterator[Int] + +scala> def collapse(it: Iterator[Int]) = { + | val (zeros, rest) = it.span(_ == 0) + | zeros.take(1) ++ rest + |} +def collapse(it: Iterator[Int]): Iterator[Int] + +scala> collapse(Iterator(0, 0, 0, 1, 2, 3, 4)).toList +val res14: List[Int] = List(0, 1, 2, 3, 4) +``` + +{% endtab %} +{% tab 'Scala 3' for=iterators_11 %} + +```scala +scala> def collapse(it: Iterator[Int]) = if !it.hasNext then Iterator.empty else + | var head = it.next + | val rest = if head == 0 then it.dropWhile(_ == 0) else it + | Iterator.single(head) ++ rest + | +def collapse(it: Iterator[Int]): Iterator[Int] + +scala> def collapse(it: Iterator[Int]) = + | val (zeros, rest) = it.span(_ == 0) + | zeros.take(1) ++ rest + | +def collapse(it: Iterator[Int]): Iterator[Int] + +scala> collapse(Iterator(0, 0, 0, 1, 2, 3, 4)).toList +val res14: List[Int] = List(0, 1, 2, 3, 4) +``` + +{% endtab %} +{% endtabs %} + +In the second version of `collapse`, the unconsumed zeros are buffered internally. +In the first version, any leading zeros are dropped and the desired result constructed +as a concatenated iterator, which simply calls its two constituent iterators in turn. diff --git a/_overviews/collections-2.13/maps.md b/_overviews/collections-2.13/maps.md new file mode 100644 index 0000000000..34d9696f19 --- /dev/null +++ b/_overviews/collections-2.13/maps.md @@ -0,0 +1,163 @@ +--- +layout: multipage-overview +title: Maps +partof: collections-213 +overview-name: Collections + +num: 7 +previous-page: sets +next-page: concrete-immutable-collection-classes + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +A [Map](https://www.scala-lang.org/api/current/scala/collection/Map.html) is an [Iterable](https://www.scala-lang.org/api/current/scala/collection/Iterable.html) consisting of pairs of keys and values (also named _mappings_ or _associations_). Scala's [Predef](https://www.scala-lang.org/api/current/scala/Predef$.html) object offers an implicit conversion that lets you write `key -> value` as an alternate syntax for the pair `(key, value)`. For instance `Map("x" -> 24, "y" -> 25, "z" -> 26)` means exactly the same as `Map(("x", 24), ("y", 25), ("z", 26))`, but reads better. + +The fundamental operations on maps are similar to those on sets. They are summarized in the following table and fall into the following categories: + +* **Lookup** operations `apply`, `get`, `getOrElse`, `contains`, and `isDefinedAt`. These turn maps into partial functions from keys to values. The fundamental lookup method for a map is: `def get(key): Option[Value]`. The operation `m.get(key)` tests whether the map contains an association for the given `key`. If so, it returns the associated value in a `Some`. If no key is defined in the map, `get` returns `None`. Maps also define an `apply` method that returns the value associated with a given key directly, without wrapping it in an `Option`. If the key is not defined in the map, an exception is raised. +* **Additions and updates** `+`, `++`, `updated`, which let you add new bindings to a map or change existing bindings. +* **Removals** `-`, `--`, which remove bindings from a map. +* **Subcollection producers** `keys`, `keySet`, `keysIterator`, `values`, `valuesIterator`, which return a map's keys and values separately in various forms. +* **Transformations** `filterKeys` and `mapValues`, which produce a new map by filtering and transforming bindings of an existing map. + +### Operations in Class Map ### + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Lookups:** | | +| `ms.get(k)` |The value associated with key `k` in map `ms` as an option, `None` if not found.| +| `ms(k)` |(or, written out, `ms.apply(k)`) The value associated with key `k` in map `ms`, or exception if not found.| +| `ms.getOrElse(k, d)` |The value associated with key `k` in map `ms`, or the default value `d` if not found.| +| `ms.contains(k)` |Tests whether `ms` contains a mapping for key `k`.| +| `ms.isDefinedAt(k)` |Same as `contains`. | +| **Subcollections:** | | +| `ms.keys` |An iterable containing each key in `ms`. | +| `ms.keySet` |A set containing each key in `ms`. | +| `ms.keysIterator` |An iterator yielding each key in `ms`. | +| `ms.values` |An iterable containing each value associated with a key in `ms`.| +| `ms.valuesIterator` |An iterator yielding each value associated with a key in `ms`.| +| **Transformation:** | | +| `ms.view.filterKeys(p)` |A map view containing only those mappings in `ms` where the key satisfies predicate `p`.| +| `ms.view.mapValues(f)` |A map view resulting from applying function `f` to each value associated with a key in `ms`.| + +Immutable maps support in addition operations to add and remove mappings by returning new `Map`s, as summarized in the following table. + +### Operations in Class immutable.Map ### + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Additions and Updates:**| | +| `ms.updated(k, v)`
            or `ms + (k -> v)` |The map containing all mappings of `ms` as well as the mapping `k -> v` from key `k` to value `v`.| +| **Removals:** | | +| `ms.removed(k)`
            or `ms - k` |The map containing all mappings of `ms` except for any mapping of key `k`.| +| `ms.removedAll(ks)`
            or `ms -- ks` |The map containing all mappings of `ms` except for any mapping with a key in `ks`.| + +Mutable maps support in addition the operations summarized in the following table. + + +### Operations in Class mutable.Map ### + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Additions and Updates:** | | +| `ms(k) = v` |(Or, written out, `ms.update(k, v)`). Adds mapping from key `k` to value `v` to map ms as a side effect, overwriting any previous mapping of `k`.| +| `ms.addOne(k -> v)`
            or `ms += (k -> v)` |Adds mapping from key `k` to value `v` to map `ms` as a side effect and returns `ms` itself.| +| `ms.addAll(kvs)`
            or `ms ++= kvs` |Adds all mappings in `kvs` to `ms` as a side effect and returns `ms` itself.| +| `ms.put(k, v)` |Adds mapping from key `k` to value `v` to `ms` and returns any value previously associated with `k` as an option.| +| `ms.getOrElseUpdate(k, d)` |If key `k` is defined in map `ms`, return its associated value. Otherwise, update `ms` with the mapping `k -> d` and return `d`.| +| **Removals:** | | +| `ms.subtractOne(k)`
            or `ms -= k` |Removes mapping with key `k` from ms as a side effect and returns `ms` itself.| +| `ms.subtractAll(ks)`
            or `ms --= ks` |Removes all keys in `ks` from `ms` as a side effect and returns `ms` itself.| +| `ms.remove(k)` |Removes any mapping with key `k` from `ms` and returns any value previously associated with `k` as an option.| +| `ms.filterInPlace(p)` |Keeps only those mappings in `ms` that have a key satisfying predicate `p`.| +| `ms.clear()` |Removes all mappings from `ms`. | +| **Transformation:** | | +| `ms.mapValuesInPlace(f)` |Transforms all associated values in map `ms` with function `f`.| +| **Cloning:** | | +| `ms.clone` |Returns a new mutable map with the same mappings as `ms`.| + +The addition and removal operations for maps mirror those for sets. A mutable map `m` is usually updated in place, using the two variants `m(key) = value` or `m += (key -> value)`. There is also the variant `m.put(key, value)`, which returns an `Option` value that contains the value previously associated with `key`, or `None` if the `key` did not exist in the map before. + +The `getOrElseUpdate` is useful for accessing maps that act as caches. Say you have an expensive computation triggered by invoking a function `f`: + +{% tabs expensive-computation-reverse class=tabs-scala-version %} + +{% tab 'Scala 2' for=expensive-computation-reverse %} +```scala +scala> def f(x: String): String = { + println("taking my time."); Thread.sleep(100) + x.reverse + } +f: (x: String)String +``` +{% endtab %} + +{% tab 'Scala 3' for=expensive-computation-reverse %} +```scala +scala> def f(x: String): String = + println("taking my time."); Thread.sleep(100) + x.reverse + +def f(x: String): String +``` +{% endtab %} + +{% endtabs %} + +Assume further that `f` has no side-effects, so invoking it again with the same argument will always yield the same result. In that case you could save time by storing previously computed bindings of argument and results of `f` in a map and only computing the result of `f` if a result of an argument was not found there. One could say the map is a _cache_ for the computations of the function `f`. + +{% tabs cache-creation %} +{% tab 'Scala 2 and 3' for=cache-creation %} +```scala +scala> val cache = collection.mutable.Map[String, String]() +cache: scala.collection.mutable.Map[String,String] = Map() +``` +{% endtab %} +{% endtabs %} + +You can now create a more efficient caching version of the `f` function: + +{% tabs cache-usage %} +{% tab 'Scala 2 and 3' for=cache-usage %} +```scala +scala> def cachedF(s: String): String = cache.getOrElseUpdate(s, f(s)) +cachedF: (s: String)String +scala> cachedF("abc") +taking my time. +res3: String = cba +scala> cachedF("abc") +res4: String = cba +``` +{% endtab %} +{% endtabs %} + +Note that the second argument to `getOrElseUpdate` is by-name, so the computation of `f("abc")` above is only performed if `getOrElseUpdate` requires the value of its second argument, which is precisely if its first argument is not found in the `cache` map. You could also have implemented `cachedF` directly, using just basic map operations, but it would take more code to do so: + +{% tabs cacheF class=tabs-scala-version %} + +{% tab 'Scala 2' for=cacheF %} +```scala +def cachedF(arg: String): String = cache.get(arg) match { + case Some(result) => result + case None => + val result = f(x) + cache(arg) = result + result +} +``` +{% endtab %} + +{% tab 'Scala 3' for=cacheF %} +```scala +def cachedF(arg: String): String = cache.get(arg) match + case Some(result) => result + case None => + val result = f(x) + cache(arg) = result + result +``` +{% endtab %} + +{% endtabs %} diff --git a/_overviews/collections-2.13/overview.md b/_overviews/collections-2.13/overview.md new file mode 100644 index 0000000000..5ef0c9b0f3 --- /dev/null +++ b/_overviews/collections-2.13/overview.md @@ -0,0 +1,181 @@ +--- +layout: multipage-overview +title: Mutable and Immutable Collections +partof: collections-213 +overview-name: Collections + +num: 2 +previous-page: introduction +next-page: trait-iterable + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +Scala collections systematically distinguish between mutable and +immutable collections. A _mutable_ collection can be updated, reduced or +extended in place. This means you can change, add, or remove elements +of a collection as a side effect. _Immutable_ collections, by +contrast, never change. You still have operations that simulate +additions, removals, or updates, but those operations will in each +case return a new collection and leave the old collection unchanged. + +All collection classes are found in the package `scala.collection` or +one of its sub-packages `mutable` and `immutable`. Most +collection classes needed by client code exist in three variants, +which are located in packages `scala.collection`, +`scala.collection.immutable`, and `scala.collection.mutable`, +respectively. Each variant has different characteristics with respect +to mutability. + +A collection in package `scala.collection.immutable` is guaranteed to +be immutable for everyone. Such a collection will never change after +it is created. Therefore, you can rely on the fact that accessing the +same collection value repeatedly at different points in time will +always yield a collection with the same elements. + +A collection in package `scala.collection.mutable` is known to have +some operations that change the collection in place. So dealing with +a mutable collection means you need to understand which code changes +which collection when. + +A collection in package `scala.collection` can be either mutable or +immutable. For instance, [collection.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html) +is a superclass of both [collection.immutable.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/IndexedSeq.html) +and +[collection.mutable.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/IndexedSeq.html). +Generally, the root collections in +package `scala.collection` support transformation operations +affecting the whole collection, the immutable +collections in package `scala.collection.immutable` typically add +operations for adding or removing single +values, and the mutable collections in package +`scala.collection.mutable` typically add some side-effecting +modification operations to the root interface. + +Another difference between root collections and immutable collections is +that clients of an immutable collection have a guarantee that nobody +can mutate the collection, whereas clients of a root collection only +promise not to change the collection themselves. Even though the +static type of such a collection provides no operations for modifying +the collection, it might still be possible that the run-time type is a +mutable collection which can be changed by other clients. + +By default, Scala always picks immutable collections. For instance, if +you just write `Set` without any prefix or without having imported +`Set` from somewhere, you get an immutable set, and if you write +`Iterable` you get an immutable iterable collection, because these +are the default bindings imported from the `scala` package. To get +the mutable default versions, you need to write explicitly +`collection.mutable.Set`, or `collection.mutable.Iterable`. + +A useful convention if you want to use both mutable and immutable +versions of collections is to import just the package +`collection.mutable`. + +{% tabs overview_1 %} +{% tab 'Scala 2 and 3' for=overview_1 %} +```scala mdoc +import scala.collection.mutable +``` +{% endtab %} +{% endtabs %} + +Then a word like `Set` without a prefix still refers to an immutable collection, +whereas `mutable.Set` refers to the mutable counterpart. + +The last package in the collection hierarchy is `scala.collection.generic`. This +package contains building blocks for abstracting over concrete collections. + +For convenience and backwards compatibility some important types have +aliases in the `scala` package, so you can use them by their simple +names without needing an import. An example is the `List` type, which +can be accessed alternatively as + +{% tabs overview_2 %} +{% tab 'Scala 2 and 3' for=overview_2 %} +```scala mdoc +scala.collection.immutable.List // that's where it is defined +scala.List // via the alias in the scala package +List // because scala._ + // is always automatically imported +``` +{% endtab %} +{% endtabs %} + +Other types aliased are +[Iterable](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html), [Seq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Seq.html), [IndexedSeq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/IndexedSeq.html), [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html), [LazyList](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/LazyList.html), [Vector](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html), [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html), and [Range](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html). + +The following figure shows all collections in package +`scala.collection`. These are all high-level abstract classes or traits, which +generally have mutable as well as immutable implementations. + +[![General collection hierarchy][1]][1] + +The following figure shows all collections in package `scala.collection.immutable`. + +[![Immutable collection hierarchy][2]][2] + +And the following figure shows all collections in package `scala.collection.mutable`. + +[![Mutable collection hierarchy][3]][3] + +Legend: + +[![Graph legend][4]][4] + +## An Overview of the Collections API ## + +The most important collection classes are shown in the figures above. There is quite a bit of commonality shared by all these classes. For instance, every kind of collection can be created by the same uniform syntax, writing the collection class name followed by its elements: + +{% tabs overview_3 %} +{% tab 'Scala 2 and 3' for=overview_3 %} +```scala +Iterable("x", "y", "z") +Map("x" -> 24, "y" -> 25, "z" -> 26) +Set(Color.red, Color.green, Color.blue) +SortedSet("hello", "world") +Buffer(x, y, z) +IndexedSeq(1.0, 2.0) +LinearSeq(a, b, c) +``` +{% endtab %} +{% endtabs %} + +The same principle also applies for specific collection implementations, such as: + +{% tabs overview_4 %} +{% tab 'Scala 2 and 3' for=overview_4 %} +```scala +List(1, 2, 3) +HashMap("x" -> 24, "y" -> 25, "z" -> 26) +``` +{% endtab %} +{% endtabs %} + +All these collections get displayed with `toString` in the same way they are written above. + +All collections support the API provided by `Iterable`, but specialize types wherever this makes sense. For instance the `map` method in class `Iterable` returns another `Iterable` as its result. But this result type is overridden in subclasses. For instance, calling `map` on a `List` yields again a `List`, calling it on a `Set` yields again a `Set` and so on. + +{% tabs overview_5 %} +{% tab 'Scala 2 and 3' for=overview_5 %} +``` +scala> List(1, 2, 3) map (_ + 1) +res0: List[Int] = List(2, 3, 4) +scala> Set(1, 2, 3) map (_ * 2) +res0: Set[Int] = Set(2, 4, 6) +``` +{% endtab %} +{% endtabs %} + +This behavior which is implemented everywhere in the collections libraries is called the _uniform return type principle_. + +Most of the classes in the collections hierarchy exist in three variants: root, mutable, and immutable. The only exception is the `Buffer` trait which only exists as a mutable collection. + +In the following, we will review these classes one by one. + + + [1]: /resources/images/tour/collections-diagram-213.svg + [2]: /resources/images/tour/collections-immutable-diagram-213.svg + [3]: /resources/images/tour/collections-mutable-diagram-213.svg + [4]: /resources/images/tour/collections-legend-diagram.svg diff --git a/_overviews/collections-2.13/performance-characteristics.md b/_overviews/collections-2.13/performance-characteristics.md new file mode 100644 index 0000000000..ed1885017a --- /dev/null +++ b/_overviews/collections-2.13/performance-characteristics.md @@ -0,0 +1,87 @@ +--- +layout: multipage-overview +title: Performance Characteristics +partof: collections-213 +overview-name: Collections + +num: 12 +previous-page: strings +next-page: equality + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +The previous explanations have made it clear that different collection types have different performance characteristics. That's often the primary reason for picking one collection type over another. You can see the performance characteristics of some common operations on collections summarized in the following two tables. + +Performance characteristics of sequence types: + +| | head | tail | apply | update| prepend | append | insert | +| -------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | +| **immutable** | | | | | | | | +| `List` | C | C | L | L | C | L | - | +| `LazyList` | C | C | L | L | C | L | - | +| `ArraySeq` | C | L | C | L | L | L | - | +| `Vector` | eC | eC | eC | eC | eC | eC | - | +| `Queue` | aC | aC | L | L | C | C | - | +| `Range` | C | C | C | - | - | - | - | +| `String` | C | L | C | L | L | L | - | +| **mutable** | | | | | | | | +| `ArrayBuffer` | C | L | C | C | L | aC | L | +| `ListBuffer` | C | L | L | L | C | C | L | +|`StringBuilder`| C | L | C | C | L | aC | L | +| `Queue` | C | L | L | L | C | C | L | +| `ArraySeq` | C | L | C | C | - | - | - | +| `Stack` | C | L | L | L | C | L | L | +| `Array` | C | L | C | C | - | - | - | +| `ArrayDeque` | C | L | C | C | aC | aC | L | + +Performance characteristics of set and map types: + +| | lookup | add | remove | min | +| -------- | ---- | ---- | ---- | ---- | +| **immutable** | | | | | +| `HashSet`/`HashMap`| eC | eC | eC | L | +| `TreeSet`/`TreeMap`| Log | Log | Log | Log | +| `BitSet` | C | L | L | eC1| +| `VectorMap` | eC | eC | aC | L | +| `ListMap` | L | L | L | L | +| **mutable** | | | | | +| `HashSet`/`HashMap`| eC | eC | eC | L | +| `WeakHashMap` | eC | eC | eC | L | +| `BitSet` | C | aC | C | eC1| +| `TreeSet` | Log | Log | Log | Log | + +Footnote: 1 Assuming bits are densely packed. + +The entries in these two tables are explained as follows: + +| | | +| --- | ---- | +| **C** | The operation takes (fast) constant time. | +| **eC** | The operation takes effectively constant time, but this might depend on some assumptions such as maximum length of a vector or distribution of hash keys.| +| **aC** | The operation takes amortized constant time. Some invocations of the operation might take longer, but if many operations are performed on average only constant time per operation is taken. | +| **Log** | The operation takes time proportional to the logarithm of the collection size. | +| **L** | The operation is linear, that is it takes time proportional to the collection size. | +| **-** | The operation is not supported. | + +The first table treats sequence types--both immutable and mutable--with the following operations: + +| | | +| --- | ---- | +| **head** | Selecting the first element of the sequence. | +| **tail** | Producing a new sequence that consists of all elements except the first one. | +| **apply** | Indexing. | +| **update** | Functional update (with `updated`) for immutable sequences, side-effecting update (with `update` for mutable sequences). | +| **prepend**| Adding an element to the front of the sequence. For immutable sequences, this produces a new sequence. For mutable sequences it modifies the existing sequence. | +| **append** | Adding an element to the end of the sequence. For immutable sequences, this produces a new sequence. For mutable sequences it modifies the existing sequence. | +| **insert** | Inserting an element at an arbitrary position in the sequence. This is only supported directly for mutable sequences. | + +The second table treats mutable and immutable sets and maps with the following operations: + +| | | +| --- | ---- | +| **lookup** | Testing whether an element is contained in set, or selecting a value associated with a key. | +| **add** | Adding a new element to a set or key/value pair to a map. | +| **remove** | Removing an element from a set or a key from a map. | +| **min** | The smallest element of the set, or the smallest key of a map. | diff --git a/_overviews/collections-2.13/seqs.md b/_overviews/collections-2.13/seqs.md new file mode 100644 index 0000000000..cabd0b8a0a --- /dev/null +++ b/_overviews/collections-2.13/seqs.md @@ -0,0 +1,123 @@ +--- +layout: multipage-overview +title: The sequence traits Seq, IndexedSeq, and LinearSeq +partof: collections-213 +overview-name: Collections + +num: 5 +previous-page: trait-iterable +next-page: sets + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +The [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) trait represents sequences. A sequence is a kind of iterable that has a `length` and whose elements have fixed index positions, starting from `0`. + +The operations on sequences, summarized in the table below, fall into the following categories: + +* **Indexing and length** operations `apply`, `isDefinedAt`, `length`, `indices`, and `lengthCompare`. For a `Seq`, the `apply` operation means indexing; hence a sequence of type `Seq[T]` is a partial function that takes an `Int` argument (an index) and which yields a sequence element of type `T`. In other words `Seq[T]` extends `PartialFunction[Int, T]`. The elements of a sequence are indexed from zero up to the `length` of the sequence minus one. The `length` method on sequences is an alias of the `size` method of general collections. The `lengthCompare` method allows you to compare the lengths of a sequences with an Int or with an `Iterable` even if the sequences has infinite length. +* **Index search operations** `indexOf`, `lastIndexOf`, `indexOfSlice`, `lastIndexOfSlice`, `indexWhere`, `lastIndexWhere`, `segmentLength`, which return the index of an element equal to a given value or matching some predicate. +* **Addition operations** `prepended`, `prependedAll`, `appended`, `appendedAll`, `padTo`, which return new sequences obtained by adding elements at the front or the end of a sequence. +* **Update operations** `updated`, `patch`, which return a new sequence obtained by replacing some elements of the original sequence. +* **Sorting operations** `sorted`, `sortWith`, `sortBy`, which sort sequence elements according to various criteria. +* **Reversal operations** `reverse`, `reverseIterator`, which yield or process sequence elements in reverse order. +* **Comparisons** `startsWith`, `endsWith`, `contains`, `containsSlice`, `corresponds`, `search`, which relate two sequences or search an element in a sequence. +* **Multiset** operations `intersect`, `diff`, `distinct`, `distinctBy`, which perform set-like operations on the elements of two sequences or remove duplicates. + +If a sequence is mutable, it offers in addition a side-effecting `update` method, which lets sequence elements be updated. As always in Scala, syntax like `seq(idx) = elem` is just a shorthand for `seq.update(idx, elem)`, so `update` gives convenient assignment syntax for free. Note the difference between `update` and `updated`. `update` changes a sequence element in place, and is only available for mutable sequences. `updated` is available for all sequences and always returns a new sequence instead of modifying the original. + +### Operations in Class Seq ### + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Indexing and Length:** | | +| `xs(i)` |(or, written out, `xs.apply(i)`). The element of `xs` at index `i`.| +| `xs.isDefinedAt(i)` |Tests whether `i` is contained in `xs.indices`.| +| `xs.length` |The length of the sequence (same as `size`).| +| `xs.lengthCompare(n)` |Returns `-1` if `xs` is shorter than `n`, `+1` if it is longer, and `0` if it is of length `n`. Works even if the sequence is infinite, for example `LazyList.from(1).lengthCompare(42)` returns a positive value.| +| `xs.indices` |The index range of `xs`, extending from `0` to `xs.length - 1`.| +| **Index Search:** | | +| `xs.indexOf(x)` |The index of the first element in `xs` equal to `x` (several variants exist).| +| `xs.lastIndexOf(x)` |The index of the last element in `xs` equal to `x` (several variants exist).| +| `xs.indexOfSlice(ys)` |The first index of `xs` such that successive elements starting from that index form the sequence `ys`.| +| `xs.lastIndexOfSlice(ys)` |The last index of `xs` such that successive elements starting from that index form the sequence `ys`.| +| `xs.indexWhere(p)` |The index of the first element in xs that satisfies `p` (several variants exist).| +| `xs.segmentLength(p, i)`|The length of the longest uninterrupted segment of elements in `xs`, starting with `xs(i)`, that all satisfy the predicate `p`.| +| **Additions:** | | +| `xs.prepended(x)`
            or `x +: xs` |A new sequence that consists of `x` prepended to `xs`.| +| `xs.prependedAll(ys)`
            or `ys ++: xs` |A new sequence that consists of all the elements of `ys` prepended to `xs`.| +| `xs.appended(x)`
            or `xs :+ x` |A new sequence that consists of `x` appended to `xs`.| +| `xs.appendedAll(ys)`
            or `xs :++ ys` |A new sequence that consists of all the elements of `ys` appended to `xs`.| +| `xs.padTo(len, x)` |The sequence resulting from appending the value `x` to `xs` until length `len` is reached.| +| **Updates:** | | +| `xs.patch(i, ys, r)` |The sequence resulting from replacing `r` elements of `xs` starting with `i` by the patch `ys`.| +| `xs.updated(i, x)` |A copy of `xs` with the element at index `i` replaced by `x`.| +| `xs(i) = x` |(or, written out, `xs.update(i, x)`, only available for `mutable.Seq`s). Changes the element of `xs` at index `i` to `x`.| +| **Sorting:** | | +| `xs.sorted` |A new sequence obtained by sorting the elements of `xs` using the standard ordering of the element type of `xs`.| +| `xs.sortWith(lt)` |A new sequence obtained by sorting the elements of `xs` using `lt` as comparison operation.| +| `xs.sortBy(f)` |A new sequence obtained by sorting the elements of `xs`. Comparison between two elements proceeds by mapping the function `f` over both and comparing the results.| +| **Reversals:** | | +| `xs.reverse` |A sequence with the elements of `xs` in reverse order.| +| `xs.reverseIterator` |An iterator yielding all the elements of `xs` in reverse order.| +| **Comparisons:** | | +| `xs.sameElements(ys)` |A test whether `xs` and `ys` contain the same elements in the same order| +| `xs.startsWith(ys)` |Tests whether `xs` starts with sequence `ys` (several variants exist).| +| `xs.endsWith(ys)` |Tests whether `xs` ends with sequence `ys` (several variants exist).| +| `xs.contains(x)` |Tests whether `xs` has an element equal to `x`.| +| `xs.search(x)` |Tests whether a sorted sequence `xs` has an element equal to `x`, possibly in a more efficient way than `xs.contains(x)`.| +| `xs.containsSlice(ys)` |Tests whether `xs` has a contiguous subsequence equal to `ys`.| +| `xs.corresponds(ys)(p)` |Tests whether corresponding elements of `xs` and `ys` satisfy the binary predicate `p`.| +| **Multiset Operations:** | | +| `xs.intersect(ys)` |The multi-set intersection of sequences `xs` and `ys` that preserves the order of elements in `xs`.| +| `xs.diff(ys)` |The multi-set difference of sequences `xs` and `ys` that preserves the order of elements in `xs`.| +| `xs.distinct` |A subsequence of `xs` that contains no duplicated element.| +| `xs.distinctBy(f)` |A subsequence of `xs` that contains no duplicated element after applying the transforming function `f`. For instance, `List("foo", "bar", "quux").distinctBy(_.length) == List("foo", "quux")`| + +Trait [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) has two subtraits [LinearSeq](https://www.scala-lang.org/api/current/scala/collection/LinearSeq.html), and [IndexedSeq](https://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html). These do not add any new operations to the immutable branch, but each offers different performance characteristics: A linear sequence has efficient `head` and `tail` operations, whereas an indexed sequence has efficient `apply`, `length`, and (if mutable) `update` operations. Frequently used linear sequences are `scala.collection.immutable.List` and `scala.collection.immutable.LazyList`. Frequently used indexed sequences are `scala.Array` and `scala.collection.mutable.ArrayBuffer`. The `Vector` class provides an interesting compromise between indexed and linear access. It has both effectively constant time indexing overhead and constant time linear access overhead. Because of this, vectors are a good foundation for mixed access patterns where both indexed and linear accesses are used. You'll learn more on vectors [later]({% link _overviews/collections-2.13/concrete-immutable-collection-classes.md %}). + +On the mutable branch, `IndexedSeq` adds operations for transforming its elements in place (by contrast with +transformation operations such as `map` and `sort`, available on the root `Seq`, which return a new collection +instance). + +#### Operations in Class mutable.IndexedSeq #### + +| WHAT IT IS | WHAT IT DOES| +| ------ | ------ | +| **Transformations:** | | +| `xs.mapInPlace(f)` |Transforms all the elements of `xs` by applying the `f` function to each of them.| +| `xs.sortInPlace()` |Sorts the collection `xs`.| +| `xs.sortInPlaceWith(c)` |Sorts the collection `xs` according to the given comparison function `c`.| +| `xs.sortInPlaceBy(f)` |Sorts the collection `xs` according to an ordering defined on the result of the application of the function `f` to each element.| + +### Buffers ### + +An important sub-category of mutable sequences is `Buffer`s. They allow not only updates of existing elements but also element additions, insertions and removals. The principal new methods supported by a buffer are `append` and `appendAll` for element addition at the end, `prepend` and `prependAll` for addition at the front, `insert` and `insertAll` for element insertions, as well as `remove`, `subtractOne` and `subtractAll` for element removal. These operations are summarized in the following table. + +Two often used implementations of buffers are `ListBuffer` and `ArrayBuffer`. As the name implies, a `ListBuffer` is backed by a `List`, and supports efficient conversion of its elements to a `List`, whereas an `ArrayBuffer` is backed by an array, and can be quickly converted into one. + +#### Operations in Class Buffer #### + +| WHAT IT IS | WHAT IT DOES| +| ------ | ------ | +| **Additions:** | | +| `buf.append(x)`
            or `buf += x` |Appends element `x` to buffer, and returns `buf` itself as result.| +| `buf.appendAll(xs)`
            or `buf ++= xs` |Appends all elements in `xs` to buffer.| +| `buf.prepend(x)`
            or `x +=: buf` |Prepends element `x` to buffer.| +| `buf.prependAll(xs)`
            or `xs ++=: buf` |Prepends all elements in `xs` to buffer.| +| `buf.insert(i, x)` |Inserts element `x` at index `i` in buffer.| +| `buf.insertAll(i, xs)` |Inserts all elements in `xs` at index `i` in buffer.| +| `buf.padToInPlace(n, x)` |Appends element `x` to buffer until it has `n` elements in total.| +| **Removals:** | | +| `buf.subtractOne(x)`
            or `buf -= x` |Removes element `x` from buffer.| +| `buf.subtractAll(xs)`
            or `buf --= xs` |Removes elements in `xs` from buffer.| +| `buf.remove(i)` |Removes element at index `i` from buffer.| +| `buf.remove(i, n)` |Removes `n` elements starting at index `i` from buffer.| +| `buf.trimStart(n)` |Removes first `n` elements from buffer.| +| `buf.trimEnd(n)` |Removes last `n` elements from buffer.| +| `buf.clear()` |Removes all elements from buffer.| +| **Replacement:** | | +| `buf.patchInPlace(i, xs, n)` |Replaces (at most) `n` elements of buffer by elements in `xs`, starting from index `i` in buffer.| +| **Cloning:** | | +| `buf.clone()` |A new buffer with the same elements as `buf`.| diff --git a/_overviews/collections-2.13/sets.md b/_overviews/collections-2.13/sets.md new file mode 100644 index 0000000000..a57814ffd1 --- /dev/null +++ b/_overviews/collections-2.13/sets.md @@ -0,0 +1,197 @@ +--- +layout: multipage-overview +title: Sets +partof: collections-213 +overview-name: Collections + +num: 6 +previous-page: seqs +next-page: maps + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +`Set`s are `Iterable`s that contain no duplicate elements. The operations on sets are summarized in the following tables for general sets, immutable sets and mutable sets. They fall into the following categories: + +* **Tests** `contains`, `apply`, `subsetOf`. The `contains` method asks whether a set contains a given element. The `apply` method for a set is the same as `contains`, so `set(elem)` is the same as `set contains elem`. That means sets can also be used as test functions that return true for the elements they contain. + +For example: + +{% tabs sets_1 %} +{% tab 'Scala 2 and 3' for=sets_1 %} +```scala +scala> val fruit = Set("apple", "orange", "peach", "banana") +fruit: scala.collection.immutable.Set[java.lang.String] = Set(apple, orange, peach, banana) +scala> fruit("peach") +res0: Boolean = true +scala> fruit("potato") +res1: Boolean = false +``` +{% endtab %} +{% endtabs %} + +* **Additions** `incl` and `concat` (or `+` and `++`, respectively), which add one or more elements to a set, yielding a new set. +* **Removals** `excl` and `removedAll` (or `-` and `--`, respectively), which remove one or more elements from a set, yielding a new set. +* **Set operations** for union, intersection, and set difference. Each of these operations exists in two forms: alphabetic and symbolic. The alphabetic versions are `intersect`, `union`, and `diff`, whereas the symbolic versions are `&`, `|`, and `&~`. In fact, the `++` that `Set` inherits from `Iterable` can be seen as yet another alias of `union` or `|`, except that `++` takes an `IterableOnce` argument whereas `union` and `|` take sets. + +### Operations in Class Set ### + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Tests:** | | +| `xs contains x` |Tests whether `x` is an element of `xs`. | +| `xs(x)` |Same as `xs contains x`. | +| `xs subsetOf ys` |Tests whether `xs` is a subset of `ys`. | +| **Addition:** | | +| `xs concat ys`
            or `xs ++ ys` |The set containing all elements of `xs` as well as all elements of `ys`.| +| **Removal:** | | +| `xs.empty` |An empty set of the same class as `xs`. | +| **Binary Operations:** | | +| `xs intersect ys`
            or `xs & ys` |The set intersection of `xs` and `ys`. | +| `xs union ys`
            or xs | ys |The set union of `xs` and `ys`. | +| `xs diff ys`
            or `xs &~ ys` |The set difference of `xs` and `ys`. | + +Immutable sets offer methods to add or remove elements by returning new `Set`s, as summarized in below. + +### Operations in Class immutable.Set ### + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Additions:** | | +| `xs incl x`
            or `xs + x` |The set containing all elements of `xs` as well as `x`.| +| **Removals:** | | +| `xs excl x`
            or `xs - x` |The set containing all elements of `xs` except `x`.| +| `xs removedAll ys`
            or `xs -- ys` |The set containing all elements of `xs` except the elements of `ys`.| + +Mutable sets offer in addition methods to add, remove, or update elements, which are summarized in below. + +### Operations in Class mutable.Set ### + +| WHAT IT IS | WHAT IT DOES | +| ------ | ------ | +| **Additions:** | | +| `xs addOne x`
            or `xs += x` |Adds element `x` to set `xs` as a side effect and returns `xs` itself.| +| `xs addAll ys`
            or `xs ++= ys` |Adds all elements in `ys` to set `xs` as a side effect and returns `xs` itself.| +| `xs add x` |Adds element `x` to `xs` and returns `true` if `x` was not previously contained in the set, `false` if it was.| +| **Removals:** | | +| `xs subtractOne x`
            or `xs -= x` |Removes element `x` from set `xs` as a side effect and returns `xs` itself.| +| `xs subtractAll ys`
            or `xs --= ys` |Removes all elements in `ys` from set `xs` as a side effect and returns `xs` itself.| +| `xs remove x` |Removes element `x` from `xs` and returns `true` if `x` was previously contained in the set, `false` if it was not.| +| `xs filterInPlace p` |Keeps only those elements in `xs` that satisfy predicate `p`.| +| `xs.clear()` |Removes all elements from `xs`.| +| **Update:** | | +| `xs(x) = b` |(or, written out, `xs.update(x, b)`). If boolean argument `b` is `true`, adds `x` to `xs`, otherwise removes `x` from `xs`.| +| **Cloning:** | | +| `xs.clone` |A new mutable set with the same elements as `xs`.| + +The operation `s += elem` adds `elem` to the set `s` as a side effect, and returns the mutated set as a result. Likewise, `s -= elem` removes `elem` from the set, and returns the mutated set as a result. Besides `+=` and `-=` there are also the bulk operations `++=` and `--=` which add or remove all elements of an iterable or an iterator. + +The choice of the method names `+=` and `-=` means that very similar code can work with either mutable or immutable sets. Consider first the following REPL dialogue which uses an immutable set `s`: + +{% tabs sets_2 %} +{% tab 'Scala 2 and 3' for=sets_2 %} +```scala +scala> var s = Set(1, 2, 3) +s: scala.collection.immutable.Set[Int] = Set(1, 2, 3) +scala> s += 4 +scala> s -= 2 +scala> s +res2: scala.collection.immutable.Set[Int] = Set(1, 3, 4) +``` +{% endtab %} +{% endtabs %} + +We used `+=` and `-=` on a `var` of type `immutable.Set`. A statement such as `s += 4` is an abbreviation for `s = s + 4`. So this invokes the addition method `+` on the set `s` and then assigns the result back to the `s` variable. Consider now an analogous interaction with a mutable set. + +{% tabs sets_3 %} +{% tab 'Scala 2 and 3' for=sets_3 %} +```scala +scala> val s = collection.mutable.Set(1, 2, 3) +s: scala.collection.mutable.Set[Int] = Set(1, 2, 3) +scala> s += 4 +res3: s.type = Set(1, 4, 2, 3) +scala> s -= 2 +res4: s.type = Set(1, 4, 3) +``` +{% endtab %} +{% endtabs %} + +The end effect is very similar to the previous interaction; we start with a `Set(1, 2, 3)` and end up with a `Set(1, 3, 4)`. However, even though the statements look the same as before, they do something different. `s += 4` now invokes the `+=` method on the mutable set value `s`, changing the set in place. Likewise, `s -= 2` now invokes the `-=` method on the same set. + +Comparing the two interactions shows an important principle. You often can replace a mutable collection stored in a `val` by an immutable collection stored in a `var`, and _vice versa_. This works at least as long as there are no alias references to the collection through which one can observe whether it was updated in place or whether a new collection was created. + +Mutable sets also provide add and remove as variants of `+=` and `-=`. The difference is that `add` and `remove` return a Boolean result indicating whether the operation had an effect on the set. + +The current default implementation of a mutable set uses a hashtable to store the set's elements. The default implementation of an immutable set uses a representation that adapts to the number of elements of the set. An empty set is represented by just a singleton object. Sets of sizes up to four are represented by a single object that stores all elements as fields. Beyond that size, immutable sets are implemented as [Compressed Hash-Array Mapped Prefix-tree]({% link _overviews/collections-2.13/concrete-immutable-collection-classes.md %}). + +A consequence of these representation choices is that, for sets of small sizes (say up to 4), immutable sets are usually more compact and also more efficient than mutable sets. So, if you expect the size of a set to be small, try making it immutable. + +Two subtraits of sets are `SortedSet` and `BitSet`. + +### Sorted Sets ### + +A [SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) is a set that produces its elements (using `iterator` or `foreach`) in a given ordering (which can be freely chosen at the time the set is created). The default representation of a [SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) is an ordered binary tree which maintains the invariant that all elements in the left subtree of a node are smaller than all elements in the right subtree. That way, a simple in order traversal can return all tree elements in increasing order. Scala's class [immutable.TreeSet](https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html) uses a _red-black_ tree implementation to maintain this ordering invariant and at the same time keep the tree _balanced_-- meaning that all paths from the root of the tree to a leaf have lengths that differ only by at most one element. + +To create an empty [TreeSet](https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html), you could first specify the desired ordering: + +{% tabs sorted-sets_1 %} +{% tab 'Scala 2 and 3' for=sorted-sets_1 %} +```scala +scala> val myOrdering = Ordering.fromLessThan[String](_ > _) +myOrdering: scala.math.Ordering[String] = ... +``` +{% endtab %} +{% endtabs %} + +Then, to create an empty tree set with that ordering, use: + +{% tabs sorted-sets_2 %} +{% tab 'Scala 2 and 3' for=sorted-sets_2 %} +```scala +scala> TreeSet.empty(myOrdering) +res1: scala.collection.immutable.TreeSet[String] = TreeSet() +``` +{% endtab %} +{% endtabs %} + +Or you can leave out the ordering argument but give an element type for the empty set. In that case, the default ordering on the element type will be used. + +{% tabs sorted-sets_3 %} +{% tab 'Scala 2 and 3' for=sorted-sets_3 %} +```scala +scala> TreeSet.empty[String] +res2: scala.collection.immutable.TreeSet[String] = TreeSet() +``` +{% endtab %} +{% endtabs %} + +If you create new sets from a tree-set (for instance by concatenation or filtering) they will keep the same ordering as the original set. For instance, + +{% tabs sorted-sets_4 %} +{% tab 'Scala 2 and 3' for=sorted-sets_4 %} +```scala +scala> res2 + "one" + "two" + "three" + "four" +res3: scala.collection.immutable.TreeSet[String] = TreeSet(four, one, three, two) +``` +{% endtab %} +{% endtabs %} + +Sorted sets also support ranges of elements. For instance, the `range` method returns all elements from a starting element up to, but excluding, an end element. Or, the `from` method returns all elements greater or equal than a starting element in the set's ordering. The result of calls to both methods is again a sorted set. Examples: + +{% tabs sorted-sets_5 %} +{% tab 'Scala 2 and 3' for=sorted-sets_5 %} +```scala +scala> res3.range("one", "two") +res4: scala.collection.immutable.TreeSet[String] = TreeSet(one, three) +scala> res3 rangeFrom "three" +res5: scala.collection.immutable.TreeSet[String] = TreeSet(three, two) +``` +{% endtab %} +{% endtabs %} + +### Bitsets ### + +Bitsets are sets of non-negative integer elements that are implemented in one or more words of packed bits. The internal representation of a [BitSet](https://www.scala-lang.org/api/current/scala/collection/BitSet.html) uses an array of `Long`s. The first `Long` covers elements from 0 to 63, the second from 64 to 127, and so on (Immutable bitsets of elements in the range of 0 to 127 optimize the array away and store the bits directly in a one or two `Long` fields). For every `Long`, each of its 64 bits is set to 1 if the corresponding element is contained in the set, and is unset otherwise. It follows that the size of a bitset depends on the largest integer that's stored in it. If `N` is that largest integer, then the size of the set is `N/64` `Long` words, or `N/8` bytes, plus a small number of extra bytes for status information. + +Bitsets are hence more compact than other sets if they contain many small elements. Another advantage of bitsets is that operations such as membership test with `contains`, or element addition and removal with `+=` and `-=` are all extremely efficient. diff --git a/_overviews/collections-2.13/strings.md b/_overviews/collections-2.13/strings.md new file mode 100644 index 0000000000..aebe244304 --- /dev/null +++ b/_overviews/collections-2.13/strings.md @@ -0,0 +1,43 @@ +--- +layout: multipage-overview +title: Strings +partof: collections-213 +overview-name: Collections + +num: 11 +previous-page: arrays +next-page: performance-characteristics + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +Like arrays, strings are not directly sequences, but they can be converted to them, and they also support all sequence operations on strings. Here are some examples of operations you can invoke on strings. + +{% tabs strings_1 %} +{% tab 'Scala 2 and 3' for=strings_1 %} + +```scala +scala> val str = "hello" +val str: java.lang.String = hello + +scala> str.reverse +val res6: String = olleh + +scala> str.map(_.toUpper) +val res7: String = HELLO + +scala> str.drop(3) +val res8: String = lo + +scala> str.slice(1, 4) +val res9: String = ell + +scala> val s: Seq[Char] = str +val s: Seq[Char] = hello +``` + +{% endtab %} +{% endtabs %} + +These operations are supported by two implicit conversions. The first, low-priority conversion maps a `String` to a `WrappedString`, which is a subclass of `immutable.IndexedSeq`, This conversion got applied in the last line above where a string got converted into a Seq. The other, high-priority conversion maps a string to a `StringOps` object, which adds all methods on immutable sequences to strings. This conversion was implicitly inserted in the method calls of `reverse`, `map`, `drop`, and `slice` in the example above. diff --git a/_overviews/collections-2.13/trait-iterable.md b/_overviews/collections-2.13/trait-iterable.md new file mode 100644 index 0000000000..21b28e2282 --- /dev/null +++ b/_overviews/collections-2.13/trait-iterable.md @@ -0,0 +1,160 @@ +--- +layout: multipage-overview +title: Trait Iterable +partof: collections-213 +overview-name: Collections + +num: 4 +previous-page: overview +next-page: seqs + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +At the top of the collection hierarchy is trait `Iterable`. All methods in this trait are defined in terms of an abstract method, `iterator`, which yields the collection's elements one by one. + +{% tabs trait-iterable_1 %} +{% tab 'Scala 2 and 3' for=trait-iterable_1 %} +```scala +def iterator: Iterator[A] +``` +{% endtab %} +{% endtabs %} + +Collection classes that implement `Iterable` just need to define this method; all other methods can be inherited from `Iterable`. + +`Iterable` also defines many concrete methods, which are all listed in the following table. These methods fall into the following categories: + +* **Addition**, `concat`, which appends two collections together, or appends all elements of an iterator to a collection. +* **Map** operations `map`, `flatMap`, and `collect`, which produce a new collection by applying some function to collection elements. +* **Conversions** `to`, `toList`, `toVector`, `toMap`, `toSet`, `toSeq`, `toIndexedSeq`, `toBuffer`, `toArray` which turn an `Iterable` collection into something more specific. If the destination is a mutable collection(`to(collection.mutable.X)`, `toArray`, `toBuffer`), a new collection is created by copying the original elements. All these conversions return their receiver argument unchanged if the run-time type of the collection already matches the demanded collection type. For instance, applying `toList` to a list will yield the list itself. +* **Copying operations** `copyToArray`. As its name implies, this copies collection elements to an array. +* **Size info** operations `isEmpty`, `nonEmpty`, `size`, `knownSize`, `sizeIs`. The number of elements of a collections can require a traversal in some cases (e.g. `List`). In other cases the collection can have an infinite number of elements (e.g. `LazyList.from(1)`). +* **Element retrieval** operations `head`, `last`, `headOption`, `lastOption`, and `find`. These select the first or last element of a collection, or else the first element matching a condition. Note, however, that not all collections have a well-defined meaning of what "first" and "last" means. For instance, a hash set might store elements according to their hash keys, which might change from run to run. In that case, the "first" element of a hash set could also be different for every run of a program. A collection is _ordered_ if it always yields its elements in the same order. Most collections are ordered, but some (_e.g._ hash sets) are not-- dropping the ordering gives a little bit of extra efficiency. Ordering is often essential to give reproducible tests and to help in debugging. That's why Scala collections give ordered alternatives for all collection types. For instance, the ordered alternative for `HashSet` is `LinkedHashSet`. +* **Sub-collection retrieval operations** `tail`, `init`, `slice`, `take`, `drop`, `takeWhile`, `dropWhile`, `filter`, `filterNot`, `withFilter`. These all return some sub-collection identified by an index range or some predicate. +* **Subdivision operations** `splitAt`, `span`, `partition`, `partitionMap`, `groupBy`, `groupMap`, `groupMapReduce`, which split the elements of this collection into several sub-collections. +* **Element tests** `exists`, `forall`, `count` which test collection elements with a given predicate. +* **Folds** `foldLeft`, `foldRight`, `reduceLeft`, `reduceRight` which apply a binary operation to successive elements. +* **Specific folds** `sum`, `product`, `min`, `max`, which work on collections of specific types (numeric or comparable). +* **String** operations `mkString` and `addString` which give alternative ways of converting a collection to a string. +* **View** operation: A view is a collection that's evaluated lazily. You'll learn more about views in [later]({% link _overviews/collections-2.13/views.md %}). + +Two more methods exist in `Iterable` that return iterators: `grouped` and `sliding`. These iterators, however, do not return single elements but whole subsequences of elements of the original collection. The maximal size of these subsequences is given as an argument to these methods. The `grouped` method returns its elements in "chunked" increments, where `sliding` yields a sliding "window" over the elements. The difference between the two should become clear by looking at the following REPL interaction: + +{% tabs trait-iterable_2 %} +{% tab 'Scala 2 and 3' for=trait-iterable_2 %} +``` +scala> val xs = List(1, 2, 3, 4, 5) +xs: List[Int] = List(1, 2, 3, 4, 5) +scala> val git = xs grouped 3 +git: Iterator[List[Int]] = non-empty iterator +scala> git.next() +res3: List[Int] = List(1, 2, 3) +scala> git.next() +res4: List[Int] = List(4, 5) +scala> val sit = xs sliding 3 +sit: Iterator[List[Int]] = non-empty iterator +scala> sit.next() +res5: List[Int] = List(1, 2, 3) +scala> sit.next() +res6: List[Int] = List(2, 3, 4) +scala> sit.next() +res7: List[Int] = List(3, 4, 5) +``` +{% endtab %} +{% endtabs %} + +### Operations in Class Iterable ### + +| WHAT IT IS | WHAT IT DOES | +|-------------------------------------------| ------ | +| **Abstract Method:** | | +| `xs.iterator` |An `iterator` that yields every element in `xs`.| +| **Other Iterators:** | | +| `xs.foreach(f)` |Executes function `f` for every element of `xs`.| +| `xs.grouped(size)` |An iterator that yields fixed-sized "chunks" of this collection.| +| `xs.sliding(size)` |An iterator that yields a sliding fixed-sized window of elements in this collection.| +| **Addition:** | | +| `xs.concat(ys)`
            (or `xs ++ ys`) |A collection consisting of the elements of both `xs` and `ys`. `ys` is a [IterableOnce](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IterableOnce.html) collection, i.e., either an [Iterable](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) or an [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html).| +| **Maps:** | | +| `xs.map(f)` |The collection obtained from applying the function f to every element in `xs`.| +| `xs.flatMap(f)` |The collection obtained from applying the collection-valued function `f` to every element in `xs` and concatenating the results.| +| `xs.collect(f)` |The collection obtained from applying the partial function `f` to every element in `xs` for which it is defined and collecting the results.| +| **Conversions:** | | +| `xs.to(SortedSet)` | Generic conversion operation that takes a collection factory as parameter. | +| `xs.toList` |Converts the collection to a list. | +| `xs.toVector` |Converts the collection to a vector. | +| `xs.toMap` |Converts the collection of key/value pairs to a map. If the collection does not have pairs as elements, calling this operation results in a static type error.| +| `xs.toSet` |Converts the collection to a set. | +| `xs.toSeq` |Converts the collection to a sequence. | +| `xs.toIndexedSeq` |Converts the collection to an indexed sequence. | +| `xs.toBuffer` |Converts the collection to a buffer. | +| `xs.toArray` |Converts the collection to an array. | +| **Copying:** | | +| `xs copyToArray(arr, s, n)` |Copies at most `n` elements of the collection to array `arr` starting at index `s`. The last two arguments are optional.| +| **Size info:** | | +| `xs.isEmpty` |Tests whether the collection is empty. | +| `xs.nonEmpty` |Tests whether the collection contains elements. | +| `xs.size` |The number of elements in the collection. | +| `xs.knownSize` |The number of elements, if this one takes constant time to compute, otherwise `-1`. | +| `xs.sizeCompare(ys)` |Returns a negative value if `xs` is shorter than the `ys` collection, a positive value if it is longer, and `0` if they have the same size. Works even if the collection is infinite, for example `LazyList.from(1) sizeCompare List(1, 2)` returns a positive value. | +| `xs.sizeCompare(n)` |Returns a negative value if `xs` is shorter than `n`, a positive value if it is longer, and `0` if it is of size `n`. Works even if the collection is infinite, for example `LazyList.from(1) sizeCompare 42` returns a positive value. | +| `xs.sizeIs < 42`, `xs.sizeIs != 42`, etc. |Provides a more convenient syntax for `xs.sizeCompare(42) < 0`, `xs.sizeCompare(42) != 0`, etc., respectively.| +| **Element Retrieval:** | | +| `xs.head` |The first element of the collection (or, some element, if no order is defined).| +| `xs.headOption` |The first element of `xs` in an option value, or None if `xs` is empty.| +| `xs.last` |The last element of the collection (or, some element, if no order is defined).| +| `xs.lastOption` |The last element of `xs` in an option value, or None if `xs` is empty.| +| `xs.find(p)` |An option containing the first element in `xs` that satisfies `p`, or `None` if no element qualifies.| +| **Subcollections:** | | +| `xs.tail` |The rest of the collection except `xs.head`. | +| `xs.init` |The rest of the collection except `xs.last`. | +| `xs.slice(from, to)` |A collection consisting of elements in some index range of `xs` (from `from` up to, and excluding `to`).| +| `xs.take(n)` |A collection consisting of the first `n` elements of `xs` (or, some arbitrary `n` elements, if no order is defined).| +| `xs.drop(n)` |The rest of the collection except `xs.take(n)`.| +| `xs.takeWhile(p)` |The longest prefix of elements in the collection that all satisfy `p`.| +| `xs.dropWhile(p)` |The collection without the longest prefix of elements that all satisfy `p`.| +| `xs.takeRight(n)` |A collection consisting of the last `n` elements of `xs` (or, some arbitrary `n` elements, if no order is defined).| +| `xs.dropRight(n)` |The rest of the collection except `xs.takeRight(n)`.| +| `xs.filter(p)` |The collection consisting of those elements of xs that satisfy the predicate `p`.| +| `xs.withFilter(p)` |A non-strict filter of this collection. Subsequent calls to `map`, `flatMap`, `foreach`, and `withFilter` will only apply to those elements of `xs` for which the condition `p` is true.| +| `xs.filterNot(p)` |The collection consisting of those elements of `xs` that do not satisfy the predicate `p`.| +| **Subdivisions:** | | +| `xs.splitAt(n)` |Split `xs` at a position, giving the pair of collections `(xs take n, xs drop n)`.| +| `xs.span(p)` |Split `xs` according to a predicate, giving the pair of collections `(xs takeWhile p, xs.dropWhile p)`.| +| `xs.partition(p)` |Split `xs` into a pair of collections; one with elements that satisfy the predicate `p`, the other with elements that do not, giving the pair of collections `(xs filter p, xs.filterNot p)`| +| `xs.groupBy(f)` |Partition `xs` into a map of collections according to a discriminator function `f`.| +| `xs.groupMap(f)(g)` |Partition `xs` into a map of collections according to a discriminator function `f`, and applies the transformation function `g` to each element in a group.| +| `xs.groupMapReduce(f)(g)(h)` |Partition `xs` according to a discriminator function `f`, and then combine the results of applying the function `g` to each element in a group using the `h` function.| +| **Element Conditions:** | | +| `xs.forall(p)` |A boolean indicating whether the predicate `p` holds for all elements of `xs`.| +| `xs.exists(p)` |A boolean indicating whether the predicate `p` holds for some element in `xs`.| +| `xs.count(p)` |The number of elements in `xs` that satisfy the predicate `p`.| +| **Folds:** | | +| `xs.foldLeft(z)(op)` |Apply binary operation `op` between successive elements of `xs`, going left to right and starting with `z`.| +| `xs.foldRight(z)(op)` |Apply binary operation `op` between successive elements of `xs`, going right to left and starting with `z`.| +| `xs.reduceLeft(op)` |Apply binary operation `op` between successive elements of non-empty collection `xs`, going left to right.| +| `xs.reduceRight(op)` |Apply binary operation `op` between successive elements of non-empty collection `xs`, going right to left.| +| **Specific Folds:** | | +| `xs.sum` |The sum of the numeric element values of collection `xs`.| +| `xs.product` |The product of the numeric element values of collection `xs`.| +| `xs.min` |The minimum of the ordered element values of collection `xs`.| +| `xs.max` |The maximum of the ordered element values of collection `xs`.| +| `xs.minOption` |Like `min` but returns `None` if `xs` is empty.| +| `xs.maxOption` |Like `max` but returns `None` if `xs` is empty.| +| **Strings:** | | +| `xs.addString(b, start, sep, end)` |Adds a string to `StringBuilder` `b` that shows all elements of `xs` between separators `sep` enclosed in strings `start` and `end`. `start`, `sep`, `end` are all optional.| +| `xs.mkString(start, sep, end)` |Converts the collection to a string that shows all elements of `xs` between separators `sep` enclosed in strings `start` and `end`. `start`, `sep`, `end` are all optional.| +| **Zippers:** | | +| `xs.zip(ys)` |A collection of pairs of corresponding elements from `xs` and `ys`.| +| `xs.zipAll(ys, x, y)` |A collection of pairs of corresponding elements from `xs` and `ys`, where the shorter sequence is extended to match the longer one by appending elements `x` or `y`.| +| `xs.zipWithIndex` |An collection of pairs of elements from `xs` with their indices.| +| **Views:** | | +| `xs.view` |Produces a view over `xs`.| + +In the inheritance hierarchy below `Iterable` you find three traits: [Seq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Seq.html), [Set](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Set.html), and [Map](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html). `Seq` and `Map` implement the [PartialFunction](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/PartialFunction.html) trait with its `apply` and `isDefinedAt` methods, each implemented differently. `Set` gets its `apply` method from [SetOps](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/SetOps.html). + +For sequences, `apply` is positional indexing, where elements are always numbered from `0`. That is, `Seq(1, 2, 3)(1)` gives `2`. For sets, `apply` is a membership test. For instance, `Set('a', 'b', 'c')('b')` gives `true` whereas `Set()('a')` gives `false`. Finally, for maps, `apply` is a selection. For instance, `Map('a' -> 1, 'b' -> 10, 'c' -> 100)('b')` gives `10`. + +In the following, we will explain each of the three kinds of collections in more detail. diff --git a/_overviews/collections-2.13/views.md b/_overviews/collections-2.13/views.md new file mode 100644 index 0000000000..6b0052c5e5 --- /dev/null +++ b/_overviews/collections-2.13/views.md @@ -0,0 +1,243 @@ +--- +layout: multipage-overview +title: Views +partof: collections-213 +overview-name: Collections + +num: 14 +previous-page: equality +next-page: iterators + +languages: [ru] +permalink: /overviews/collections-2.13/:title.html +--- + +Collections have quite a few methods that construct new collections. Examples are `map`, `filter` or `++`. We call such methods *transformers* because they take at least one collection as their receiver object and produce another collection as their result. + +There are two principal ways to implement transformers. One is _strict_, that is a new collection with all its elements is constructed as a result of the transformer. The other is non-strict or _lazy_, that is one constructs only a proxy for the result collection, and its elements get constructed only as one demands them. + +As an example of a non-strict transformer consider the following implementation of a lazy map operation: + +{% tabs views_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=views_1 %} +```scala mdoc +def lazyMap[T, U](iter: Iterable[T], f: T => U) = new Iterable[U] { + def iterator = iter.iterator.map(f) +} +``` +{% endtab %} +{% tab 'Scala 3' for=views_1 %} +```scala +def lazyMap[T, U](iter: Iterable[T], f: T => U) = new Iterable[U]: + def iterator = iter.iterator.map(f) +``` +{% endtab %} +{% endtabs %} + +Note that `lazyMap` constructs a new `Iterable` without stepping through all elements of the given collection `iter`. The given function `f` is instead applied to the elements of the new collection's `iterator` as they are demanded. + +Scala collections are by default strict in all their transformers, except for `LazyList`, which implements all its transformer methods lazily. However, there is a systematic way to turn every collection into a lazy one and _vice versa_, which is based on collection views. A _view_ is a special kind of collection that represents some base collection, but implements all transformers lazily. + +To go from a collection to its view, you can use the `view` method on the collection. If `xs` is some collection, then `xs.view` is the same collection, but with all transformers implemented lazily. To get back from a view to a strict collection, you can use the `to` conversion operation with a strict collection factory as parameter (e.g. `xs.view.to(List)`). + +Let's see an example. Say you have a vector of Ints over which you want to map two functions in succession: + +{% tabs views_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=views_2 %} + +```scala +scala> val v = Vector(1 to 10: _*) +val v: scala.collection.immutable.Vector[Int] = + Vector(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + +scala> v.map(_ + 1).map(_ * 2) +val res5: scala.collection.immutable.Vector[Int] = + Vector(4, 6, 8, 10, 12, 14, 16, 18, 20, 22) +``` + +{% endtab %} +{% tab 'Scala 3' for=views_2 %} + +```scala +scala> val v = Vector((1 to 10)*) +val v: scala.collection.immutable.Vector[Int] = + Vector(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + +scala> v.map(_ + 1).map(_ * 2) +val res5: scala.collection.immutable.Vector[Int] = + Vector(4, 6, 8, 10, 12, 14, 16, 18, 20, 22) +``` + +{% endtab %} +{% endtabs %} + +In the last statement, the expression `v map (_ + 1)` constructs a new vector which is then transformed into a third vector by the second call to `map (_ * 2)`. In many situations, constructing the intermediate result from the first call to map is a bit wasteful. In the example above, it would be faster to do a single map with the composition of the two functions `(_ + 1)` and `(_ * 2)`. If you have the two functions available in the same place you can do this by hand. But quite often, successive transformations of a data structure are done in different program modules. Fusing those transformations would then undermine modularity. A more general way to avoid the intermediate results is by turning the vector first into a view, then applying all transformations to the view, and finally forcing the view to a vector: + +{% tabs views_3 %} +{% tab 'Scala 2 and 3' for=views_3 %} + +```scala +scala> val w = v.view.map(_ + 1).map(_ * 2).to(Vector) +val w: scala.collection.immutable.Vector[Int] = + Vector(4, 6, 8, 10, 12, 14, 16, 18, 20, 22) +``` + +{% endtab %} +{% endtabs %} + +Let's do this sequence of operations again, one by one: + +{% tabs views_4 %} +{% tab 'Scala 2 and 3' for=views_4 %} + +```scala +scala> val vv = v.view +val vv: scala.collection.IndexedSeqView[Int] = IndexedSeqView() +``` + +{% endtab %} +{% endtabs %} + +The application `v.view` gives you an `IndexedSeqView[Int]`, i.e. a lazily evaluated `IndexedSeq[Int]`. Like with `LazyList`, +the `toString` operation of views does not force the view elements, that’s why the content of `vv` is shown as `IndexedSeqView()`. + +Applying the first `map` to the view gives: + +{% tabs views_5 %} +{% tab 'Scala 2 and 3' for=views_5 %} + +```scala +scala> vv.map(_ + 1) +val res13: scala.collection.IndexedSeqView[Int] = IndexedSeqView() +``` +{% endtab %} +{% endtabs %} + +The result of the `map` is another `IndexedSeqView[Int]` value. This is in essence a wrapper that *records* the fact that a `map` with function `(_ + 1)` needs to be applied on the vector `v`. It does not apply that map until the view is forced, however. Let's now apply the second `map` to the last result. + +{% tabs views_6 %} +{% tab 'Scala 2 and 3' for=views_6 %} + +```scala +scala> res13.map(_ * 2) +val res14: scala.collection.IndexedSeqView[Int] = IndexedSeqView() +``` + +{% endtab %} +{% endtabs %} + +Finally, forcing the last result gives: + +{% tabs views_7 %} +{% tab 'Scala 2 and 3' for=views_7 %} + +```scala +scala> res14.to(Vector) +val res15: scala.collection.immutable.Vector[Int] = + Vector(4, 6, 8, 10, 12, 14, 16, 18, 20, 22) +``` + +{% endtab %} +{% endtabs %} + +Both stored functions get applied as part of the execution of the `to` operation and a new vector is constructed. That way, no intermediate data structure is needed. + +In general, transformation operations applied to views never build a new data structure, and accessing the elements of a view +effectively traverses as few elements as possible of the underlying data structure. Therefore, views have the following +properties: (1) transformers have a `O(1)` complexity, and (2) element access operations have the same +complexity of the underlying data structure (for instance, indexed access on an `IndexedSeqView` is constant, otherwise +it is linear). + +There are a few exceptions to these rules, though. For instance, the `sorted` operation can not satisfy both +properties. Indeed, the whole underlying collection has to be traversed in order to find its minimum element. On one +hand, if that traversal happened at the time `sorted` was called, then the first property would be violated (`sorted` +would not be lazy on views), on the other hand, if that traversal happened at the time the resulting view elements were +accessed, then the second property would be violated. For such operations, we decided to violate the first property. +These operations are documented as “always forcing the collection elements”. + +The main reason for using views is performance. You have seen that by switching a collection to a view the construction of intermediate results can be avoided. These savings can be quite important. As another example, consider the problem of finding the first palindrome in a list of words. A palindrome is a word which reads backwards the same as forwards. Here are the necessary definitions: + +{% tabs views_8 %} +{% tab 'Scala 2 and 3' for=views_8 %} + +```scala +def isPalindrome(x: String) = x == x.reverse +def findPalindrome(s: Seq[String]) = s.find(isPalindrome) +``` + +{% endtab %} +{% endtabs %} + +Now, assume you have a very long sequence words, and you want to find a palindrome in the first million words of that sequence. Can you re-use the definition of `findPalindrome`? Of course, you could write: + +{% tabs views_9 %} +{% tab 'Scala 2 and 3' for=views_9 %} +```scala +val palindromes = findPalindrome(words.take(1000000)) +``` +{% endtab %} +{% endtabs %} + +This nicely separates the two aspects of taking the first million words of a sequence and finding a palindrome in it. But the downside is that it always constructs an intermediary sequence consisting of one million words, even if the first word of that sequence is already a palindrome. So potentially, 999'999 words are copied into the intermediary result without being inspected at all afterwards. Many programmers would give up here and write their own specialized version of finding palindromes in some given prefix of an argument sequence. But with views, you don't have to. Simply write: + +{% tabs views_10 %} +{% tab 'Scala 2 and 3' for=views_10 %} +```scala +val palindromes = findPalindrome(words.view.take(1000000)) +``` +{% endtab %} +{% endtabs %} + +This has the same nice separation of concerns, but instead of a sequence of a million elements it will only construct a single lightweight view object. This way, you do not need to choose between performance and modularity. + +After having seen all these nifty uses of views you might wonder why have strict collections at all? One reason is that performance comparisons do not always favor lazy over strict collections. For smaller collection sizes the added overhead of forming and applying closures in views is often greater than the gain from avoiding the intermediary data structures. A probably more important reason is that evaluation in views can be very confusing if the delayed operations have side effects. + +Here's an example which bit a few users of versions of Scala before 2.8. In these versions the `Range` type was lazy, so it behaved in effect like a view. People were trying to create a number of actors like this: + +{% tabs views_11 class=tabs-scala-version %} +{% tab 'Scala 2' for=views_11 %} +```scala +val actors = for (i <- 1 to 10) yield actor { ... } +``` +{% endtab %} +{% tab 'Scala 3' for=views_11 %} +```scala +val actors = for i <- 1 to 10 yield actor { ... } +``` +{% endtab %} +{% endtabs %} + +They were surprised that none of the actors was executing afterwards, even though the actor method should create and start an actor from the code that's enclosed in the braces following it. To explain why nothing happened, remember that the for expression above is equivalent to an application of map: + +{% tabs views_12 %} +{% tab 'Scala 2 and 3' for=views_12 %} + +```scala +val actors = (1 to 10).map(i => actor { ... }) +``` + +{% endtab %} +{% endtabs %} + +Since previously the range produced by `(1 to 10)` behaved like a view, the result of the map was again a view. That is, no element was computed, and, consequently, no actor was created! Actors would have been created by forcing the range of the whole expression, but it's far from obvious that this is what was required to make the actors do their work. + +To avoid surprises like this, the current Scala collections library has more regular rules. All collections except lazy lists and views are strict. The only way to go from a strict to a lazy collection is via the `view` method. The only way to go back is via `to`. So the `actors` definition above would now behave as expected in that it would create and start 10 actors. To get back the surprising previous behavior, you'd have to add an explicit `view` method call: + +{% tabs views_13 class=tabs-scala-version %} +{% tab 'Scala 2' for=views_13 %} + +```scala +val actors = for (i <- (1 to 10).view) yield actor { ... } +``` + +{% endtab %} +{% tab 'Scala 3' for=views_13 %} + +```scala +val actors = for i <- (1 to 10).view yield actor { ... } +``` + +{% endtab %} +{% endtabs %} + +In summary, views are a powerful tool to reconcile concerns of efficiency with concerns of modularity. But in order not to be entangled in aspects of delayed evaluation, you should restrict views to purely functional code where collection transformations do not have side effects. What's best avoided is a mixture of views and operations that create new collections while also having side effects. diff --git a/_overviews/collections/arrays.md b/_overviews/collections/arrays.md index 512df5e432..637806b014 100644 --- a/_overviews/collections/arrays.md +++ b/_overviews/collections/arrays.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Arrays - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/arrays.html num: 10 @@ -13,7 +11,7 @@ languages: [ja, zh-cn] permalink: /overviews/collections/:title.html --- -[Array](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html) is a special kind of collection in Scala. On the one hand, Scala arrays correspond one-to-one to Java arrays. That is, a Scala array `Array[Int]` is represented as a Java `int[]`, an `Array[Double]` is represented as a Java `double[]` and a `Array[String]` is represented as a Java `String[]`. But at the same time, Scala arrays offer much more than their Java analogues. First, Scala arrays can be _generic_. That is, you can have an `Array[T]`, where `T` is a type parameter or abstract type. Second, Scala arrays are compatible with Scala sequences - you can pass an `Array[T]` where a `Seq[T]` is required. Finally, Scala arrays also support all sequence operations. Here's an example of this in action: +[Array](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/Array.html) is a special kind of collection in Scala. On the one hand, Scala arrays correspond one-to-one to Java arrays. That is, a Scala array `Array[Int]` is represented as a Java `int[]`, an `Array[Double]` is represented as a Java `double[]` and a `Array[String]` is represented as a Java `String[]`. But at the same time, Scala arrays offer much more than their Java analogues. First, Scala arrays can be _generic_. That is, you can have an `Array[T]`, where `T` is a type parameter or abstract type. Second, Scala arrays are compatible with Scala sequences - you can pass an `Array[T]` where a `Seq[T]` is required. Finally, Scala arrays also support all sequence operations. Here's an example of this in action: scala> val a1 = Array(1, 2, 3) a1: Array[Int] = Array(1, 2, 3) @@ -26,7 +24,7 @@ permalink: /overviews/collections/:title.html Given that Scala arrays are represented just like Java arrays, how can these additional features be supported in Scala? In fact, the answer to this question differs between Scala 2.8 and earlier versions. Previously, the Scala compiler somewhat "magically" wrapped and unwrapped arrays to and from `Seq` objects when required in a process called boxing and unboxing. The details of this were quite complicated, in particular when one created a new array of generic type `Array[T]`. There were some puzzling corner cases and the performance of array operations was not all that predictable. -The Scala 2.8 design is much simpler. Almost all compiler magic is gone. Instead the Scala 2.8 array implementation makes systematic use of implicit conversions. In Scala 2.8 an array does not pretend to _be_ a sequence. It can't really be that because the data type representation of a native array is not a subtype of `Seq`. Instead there is an implicit "wrapping" conversion between arrays and instances of class `scala.collection.mutable.WrappedArray`, which is a subclass of `Seq`. Here you see it in action: +The Scala 2.8 design is much simpler. Almost all compiler magic is gone. Instead, the Scala 2.8 array implementation makes systematic use of implicit conversions. In Scala 2.8 an array does not pretend to _be_ a sequence. It can't really be that because the data type representation of a native array is not a subtype of `Seq`. Instead, there is an implicit "wrapping" conversion between arrays and instances of class `scala.collection.mutable.WrappedArray`, which is a subclass of `Seq`. Here you see it in action: scala> val seq: Seq[Int] = a1 seq: Seq[Int] = WrappedArray(1, 2, 3) @@ -62,9 +60,9 @@ The `ArrayOps` object gets inserted automatically by the implicit conversion. So scala> intArrayOps(a1).reverse res5: Array[Int] = Array(3, 2, 1) -where `intArrayOps` is the implicit conversion that was inserted previously. This raises the question how the compiler picked `intArrayOps` over the other implicit conversion to `WrappedArray` in the line above. After all, both conversions map an array to a type that supports a reverse method, which is what the input specified. The answer to that question is that the two implicit conversions are prioritized. The `ArrayOps` conversion has a higher priority than the `WrappedArray` conversion. The first is defined in the `Predef` object whereas the second is defined in a class `scala.LowPriorityImplicits`, which is inherited by `Predef`. Implicits in subclasses and subobjects take precedence over implicits in base classes. So if both conversions are applicable, the one in `Predef` is chosen. A very similar scheme works for strings. +where `intArrayOps` is the implicit conversion that was inserted previously. This raises the question of how the compiler picked `intArrayOps` over the other implicit conversion to `WrappedArray` in the line above. After all, both conversions map an array to a type that supports a reverse method, which is what the input specified. The answer to that question is that the two implicit conversions are prioritized. The `ArrayOps` conversion has a higher priority than the `WrappedArray` conversion. The first is defined in the `Predef` object whereas the second is defined in a class `scala.LowPriorityImplicits`, which is inherited by `Predef`. Implicits in subclasses and subobjects take precedence over implicits in base classes. So if both conversions are applicable, the one in `Predef` is chosen. A very similar scheme works for strings. -So now you know how arrays can be compatible with sequences and how they can support all sequence operations. What about genericity? In Java you cannot write a `T[]` where `T` is a type parameter. How then is Scala's `Array[T]` represented? In fact a generic array like `Array[T]` could be at run-time any of Java's eight primitive array types `byte[]`, `short[]`, `char[]`, `int[]`, `long[]`, `float[]`, `double[]`, `boolean[]`, or it could be an array of objects. The only common run-time type encompassing all of these types is `AnyRef` (or, equivalently `java.lang.Object`), so that's the type to which the Scala compiler maps `Array[T]`. At run-time, when an element of an array of type `Array[T]` is accessed or updated there is a sequence of type tests that determine the actual array type, followed by the correct array operation on the Java array. These type tests slow down array operations somewhat. You can expect accesses to generic arrays to be three to four times slower than accesses to primitive or object arrays. This means that if you need maximal performance, you should prefer concrete over generic arrays. Representing the generic array type is not enough, however, there must also be a way to create generic arrays. This is an even harder problem, which requires a little bit of help from you. To illustrate the problem, consider the following attempt to write a generic method that creates an array. +So now you know how arrays can be compatible with sequences and how they can support all sequence operations. What about genericity? In Java, you cannot write a `T[]` where `T` is a type parameter. How then is Scala's `Array[T]` represented? In fact a generic array like `Array[T]` could be at run-time any of Java's eight primitive array types `byte[]`, `short[]`, `char[]`, `int[]`, `long[]`, `float[]`, `double[]`, `boolean[]`, or it could be an array of objects. The only common run-time type encompassing all of these types is `AnyRef` (or, equivalently `java.lang.Object`), so that's the type to which the Scala compiler maps `Array[T]`. At run-time, when an element of an array of type `Array[T]` is accessed or updated there is a sequence of type tests that determine the actual array type, followed by the correct array operation on the Java array. These type tests slow down array operations somewhat. You can expect accesses to generic arrays to be three to four times slower than accesses to primitive or object arrays. This means that if you need maximal performance, you should prefer concrete to generic arrays. Representing the generic array type is not enough, however, there must also be a way to create generic arrays. This is an even harder problem, which requires a little of help from you. To illustrate the issue, consider the following attempt to write a generic method that creates an array. // this is wrong! def evenElems[T](xs: Vector[T]): Array[T] = { @@ -74,7 +72,7 @@ So now you know how arrays can be compatible with sequences and how they can sup arr } -The `evenElems` method returns a new array that consist of all elements of the argument vector `xs` which are at even positions in the vector. The first line of the body of `evenElems` creates the result array, which has the same element type as the argument. So depending on the actual type parameter for `T`, this could be an `Array[Int]`, or an `Array[Boolean]`, or an array of some of the other primitive types in Java, or an array of some reference type. But these types have all different runtime representations, so how is the Scala runtime going to pick the correct one? In fact, it can't do that based on the information it is given, because the actual type that corresponds to the type parameter `T` is erased at runtime. That's why you will get the following error message if you compile the code above: +The `evenElems` method returns a new array that consist of all elements of the argument vector `xs` which are at even positions in the vector. The first line of the body of `evenElems` creates the result array, which has the same element type as the argument. So depending on the actual type parameter for `T`, this could be an `Array[Int]`, or an `Array[Boolean]`, or an array of some other primitive types in Java, or an array of some reference type. But these types have all different runtime representations, so how is the Scala runtime going to pick the correct one? In fact, it can't do that based on the information it is given, because the actual type that corresponds to the type parameter `T` is erased at runtime. That's why you will get the following error message if you compile the code above: error: cannot find class manifest for element type T val arr = new Array[T]((arr.length + 1) / 2) diff --git a/_overviews/collections/concrete-immutable-collection-classes.md b/_overviews/collections/concrete-immutable-collection-classes.md index 78ca9d0857..6324128e48 100644 --- a/_overviews/collections/concrete-immutable-collection-classes.md +++ b/_overviews/collections/concrete-immutable-collection-classes.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Concrete Immutable Collection Classes - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/concrete-immutable-collection-classes.html num: 8 @@ -17,15 +15,15 @@ Scala provides many concrete immutable collection classes for you to choose from ## Lists -A [List](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/List.html) is a finite immutable sequence. They provide constant-time access to their first element as well as the rest of the list, and they have a constant-time cons operation for adding a new element to the front of the list. Many other operations take linear time. +A [List](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/List.html) is a finite immutable sequence. They provide constant-time access to their first element as well as the rest of the list, and they have a constant-time cons operation for adding a new element to the front of the list. Many other operations take linear time. Lists have always been the workhorse for Scala programming, so not much needs to be said about them here. The major change in 2.8 is that the `List` class together with its subclass `::` and its subobject `Nil` is now defined in package `scala.collection.immutable`, where it logically belongs. There are still aliases for `List`, `Nil`, and `::` in the `scala` package, so from a user perspective, lists can be accessed as before. -Another change is that lists now integrate more closely into the collections framework, and are less of a special case than before. For instance all of the numerous methods that originally lived in the `List` companion object have been deprecated. They are replaced by the [uniform creation methods]({{ site.baseurl }}/overviews/collections/creating-collections-from-scratch.html) inherited by every collection. +Another change is that lists now integrate more closely into the collections framework, and are less of a special case than before. For instance all the numerous methods that originally lived in the `List` companion object have been deprecated. They are replaced by the [uniform creation methods]({{ site.baseurl }}/overviews/collections/creating-collections-from-scratch.html) inherited by every collection. ## Streams -A [Stream](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Stream.html) is like a list except that its elements are computed lazily. Because of this, a stream can be infinitely long. Only those elements requested are computed. Otherwise, streams have the same performance characteristics as lists. +A [Stream](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Stream.html) is like a list except that its elements are computed lazily. Because of this, a stream can be infinitely long. Only those elements requested are computed. Otherwise, streams have the same performance characteristics as lists. Whereas lists are constructed with the `::` operator, streams are constructed with the similar-looking `#::`. Here is a simple example of a stream containing the integers 1, 2, and 3: @@ -52,7 +50,7 @@ Here are the first few elements of the Fibonacci sequence starting with two ones Lists are very efficient when the algorithm processing them is careful to only process their heads. Accessing, adding, and removing the head of a list takes only constant time, whereas accessing or modifying elements later in the list takes time linear in the depth into the list. -[Vector](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html) is a collection type (introduced in Scala 2.8) that addresses the inefficiency for random access on lists. Vectors allow accessing any element of the list in "effectively" constant time. It's a larger constant than for access to the head of a list or for reading an element of an array, but it's a constant nonetheless. As a result, algorithms using vectors do not have to be careful about accessing just the head of the sequence. They can access and modify elements at arbitrary locations, and thus they can be much more convenient to write. +[Vector](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html) is a collection type (introduced in Scala 2.8) that addresses the inefficiency for random access on lists. Vectors allow accessing any element of the list in "effectively" constant time. It's a larger constant than for access to the head of a list or for reading an element of an array, but it's a constant nonetheless. As a result, algorithms using vectors do not have to be careful about accessing just the head of the sequence. They can access and modify elements at arbitrary locations, and thus they can be much more convenient to write. Vectors are built and modified just like any other sequence. @@ -86,7 +84,7 @@ Because vectors strike a good balance between fast random selections and fast ra ## Immutable stacks -If you need a last-in-first-out sequence, you can use a [Stack](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Stack.html). You push an element onto a stack with `push`, pop an element with `pop`, and peek at the top of the stack without removing it with `top`. All of these operations are constant time. +If you need a last-in-first-out sequence, you can use a [Stack](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Stack.html). You push an element onto a stack with `push`, pop an element with `pop`, and peek at the top of the stack without removing it with `top`. All of these operations are constant time. Here are some simple operations performed on a stack: @@ -106,7 +104,7 @@ Immutable stacks are used rarely in Scala programs because their functionality i ## Immutable Queues -A [Queue](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Queue.html) is just like a stack except that it is first-in-first-out rather than last-in-first-out. +A [Queue](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Queue.html) is just like a stack except that it is first-in-first-out rather than last-in-first-out. Here's how you can create an empty immutable queue: @@ -134,7 +132,7 @@ Note that `dequeue` returns a pair consisting of the element removed and the res ## Ranges -A [Range](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html) is an ordered sequence of integers that are equally spaced apart. For example, "1, 2, 3," is a range, as is "5, 8, 11, 14." To create a range in Scala, use the predefined methods `to` and `by`. +A [Range](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html) is an ordered sequence of integers that are equally spaced apart. For example, "1, 2, 3," is a range, as is "5, 8, 11, 14." To create a range in Scala, use the predefined methods `to` and `by`. scala> 1 to 3 res2: scala.collection.immutable.Range.Inclusive = Range(1, 2, 3) @@ -150,15 +148,15 @@ Ranges are represented in constant space, because they can be defined by just th ## Hash Tries -Hash tries are a standard way to implement immutable sets and maps efficiently. They are supported by class [immutable.HashMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/HashMap.html). Their representation is similar to vectors in that they are also trees where every node has 32 elements or 32 subtrees. But the selection of these keys is now done based on hash code. For instance, to find a given key in a map, one first takes the hash code of the key. Then, the lowest 5 bits of the hash code are used to select the first subtree, followed by the next 5 bits and so on. The selection stops once all elements stored in a node have hash codes that differ from each other in the bits that are selected up to this level. +Hash tries are a standard way to implement immutable sets and maps efficiently. They are supported by class [immutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/HashMap.html). Their representation is similar to vectors in that they are also trees where every node has 32 elements or 32 subtrees. But the selection of these keys is now done based on hash code. For instance, to find a given key in a map, one first takes the hash code of the key. Then, the lowest 5 bits of the hash code are used to select the first subtree, followed by the next 5 bits and so on. The selection stops once all elements stored in a node have hash codes that differ from each other in the bits that are selected up to this level. -Hash tries strike a nice balance between reasonably fast lookups and reasonably efficient functional insertions (`+`) and deletions (`-`). That's why they underly Scala's default implementations of immutable maps and sets. In fact, Scala has a further optimization for immutable sets and maps that contain less than five elements. Sets and maps with one to four elements are stored as single objects that just contain the elements (or key/value pairs in the case of a map) as fields. The empty immutable set and the empty immutable map is in each case a single object - there's no need to duplicate storage for those because an empty immutable set or map will always stay empty. +Hash tries strike a nice balance between reasonably fast lookups and reasonably efficient functional insertions (`+`) and deletions (`-`). That's why they underlie Scala's default implementations of immutable maps and sets. In fact, Scala has a further optimization for immutable sets and maps that contain less than five elements. Sets and maps with one to four elements are stored as single objects that just contain the elements (or key/value pairs in the case of a map) as fields. The empty immutable set and the empty immutable map is in each case a single object - there's no need to duplicate storage for those because an empty immutable set or map will always stay empty. ## Red-Black Trees Red-black trees are a form of balanced binary tree where some nodes are designated "red" and others designated "black." Like any balanced binary tree, operations on them reliably complete in time logarithmic to the size of the tree. -Scala provides implementations of immutable sets and maps that use a red-black tree internally. Access them under the names [TreeSet](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) and [TreeMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeMap.html). +Scala provides implementations of immutable sets and maps that use a red-black tree internally. Access them under the names [TreeSet](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/TreeSet.html) and [TreeMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/TreeMap.html). scala> scala.collection.immutable.TreeSet.empty[Int] @@ -170,7 +168,7 @@ Red-black trees are the standard implementation of `SortedSet` in Scala, because ## Immutable BitSets -A [BitSet](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/BitSet.html) represents a collection of small integers as the bits of a larger integer. For example, the bit set containing 3, 2, and 0 would be represented as the integer 1101 in binary, which is 13 in decimal. +A [BitSet](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/BitSet.html) represents a collection of small integers as the bits of a larger integer. For example, the bit set containing 3, 2, and 0 would be represented as the integer 1101 in binary, which is 13 in decimal. Internally, bit sets use an array of 64-bit `Long`s. The first `Long` in the array is for integers 0 through 63, the second is for 64 through 127, and so on. Thus, bit sets are very compact so long as the largest integer in the set is less than a few hundred or so. @@ -187,7 +185,7 @@ Operations on bit sets are very fast. Testing for inclusion takes constant time. ## List Maps -A [ListMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/ListMap.html) represents a map as a linked list of key-value pairs. In general, operations on a list map might have to iterate through the entire list. Thus, operations on a list map take time linear in the size of the map. In fact there is little usage for list maps in Scala because standard immutable maps are almost always faster. The only possible exception to this is if the map is for some reason constructed in such a way that the first elements in the list are selected much more often than the other elements. +A [ListMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/ListMap.html) represents a map as a linked list of key-value pairs. In general, operations on a list map might have to iterate through the entire list. Thus, operations on a list map take time linear in the size of the map. In fact there is little usage for list maps in Scala because standard immutable maps are almost always faster. The only possible exception to this is if the map is for some reason constructed in such a way that the first elements in the list are selected much more often than the other elements. scala> val map = scala.collection.immutable.ListMap(1->"one", 2->"two") map: scala.collection.immutable.ListMap[Int,java.lang.String] = diff --git a/_overviews/collections/concrete-mutable-collection-classes.md b/_overviews/collections/concrete-mutable-collection-classes.md index f229dc818d..108b531c9a 100644 --- a/_overviews/collections/concrete-mutable-collection-classes.md +++ b/_overviews/collections/concrete-mutable-collection-classes.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Concrete Mutable Collection Classes - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/concrete-mutable-collection-classes.html num: 9 @@ -17,7 +15,7 @@ You've now seen the most commonly used immutable collection classes that Scala p ## Array Buffers -An [ArrayBuffer](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayBuffer.html) buffer holds an array and a size. Most operations on an array buffer have the same speed as for an array, because the operations simply access and modify the underlying array. Additionally, array buffers can have data efficiently added to the end. Appending an item to an array buffer takes amortized constant time. Thus, array buffers are useful for efficiently building up a large collection whenever the new items are always added to the end. +An [ArrayBuffer](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ArrayBuffer.html) buffer holds an array and a size. Most operations on an array buffer have the same speed as for an array, because the operations simply access and modify the underlying array. Additionally, array buffers can have data efficiently added to the end. Appending an item to an array buffer takes amortized constant time. Thus, array buffers are useful for efficiently building up a large collection whenever the new items are always added to the end. scala> val buf = scala.collection.mutable.ArrayBuffer.empty[Int] buf: scala.collection.mutable.ArrayBuffer[Int] = ArrayBuffer() @@ -30,7 +28,7 @@ An [ArrayBuffer](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/co ## List Buffers -A [ListBuffer](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ListBuffer.html) is like an array buffer except that it uses a linked list internally instead of an array. If you plan to convert the buffer to a list once it is built up, use a list buffer instead of an array buffer. +A [ListBuffer](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ListBuffer.html) is like an array buffer except that it uses a linked list internally instead of an array. If you plan to convert the buffer to a list once it is built up, use a list buffer instead of an array buffer. scala> val buf = scala.collection.mutable.ListBuffer.empty[Int] buf: scala.collection.mutable.ListBuffer[Int] = ListBuffer() @@ -43,7 +41,7 @@ A [ListBuffer](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/coll ## StringBuilders -Just like an array buffer is useful for building arrays, and a list buffer is useful for building lists, a [StringBuilder](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html) is useful for building strings. String builders are so commonly used that they are already imported into the default namespace. Create them with a simple `new StringBuilder`, like this: +Just like an array buffer is useful for building arrays, and a list buffer is useful for building lists, a [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/StringBuilder.html) is useful for building strings. String builders are so commonly used that they are already imported into the default namespace. Create them with a simple `new StringBuilder`, like this: scala> val buf = new StringBuilder buf: StringBuilder = @@ -56,15 +54,15 @@ Just like an array buffer is useful for building arrays, and a list buffer is us ## Linked Lists -Linked lists are mutable sequences that consist of nodes which are linked with next pointers. They are supported by class [LinkedList](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/LinkedList.html). In most languages `null` would be picked as the empty linked list. That does not work for Scala collections, because even empty sequences must support all sequence methods. In particular `LinkedList.empty.isEmpty` should return `true` and not throw a `NullPointerException`. Empty linked lists are encoded instead in a special way: Their `next` field points back to the node itself. Like their immutable cousins, linked lists are best traversed sequentially. In addition linked lists make it easy to insert an element or linked list into another linked list. +Linked lists are mutable sequences that consist of nodes which are linked with next pointers. They are supported by class [LinkedList](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/LinkedList.html). In most languages `null` would be picked as the empty linked list. That does not work for Scala collections, because even empty sequences must support all sequence methods. In particular `LinkedList.empty.isEmpty` should return `true` and not throw a `NullPointerException`. Empty linked lists are encoded instead in a special way: Their `next` field points back to the node itself. Like their immutable cousins, linked lists are best traversed sequentially. In addition, linked lists make it easy to insert an element or linked list into another linked list. ## Double Linked Lists -Double linked lists are like single linked lists, except that they have besides `next` another mutable field `prev` that points to the element preceding the current node. The main benefit of that additional link is that it makes element removal very fast. Double linked lists are supported by class [DoubleLinkedList](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/DoubleLinkedList.html). +Double linked lists are like single linked lists, except that they have besides `next` another mutable field `prev` that points to the element preceding the current node. The main benefit of that additional link is that it makes element removal very fast. Double linked lists are supported by class [DoubleLinkedList](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/DoubleLinkedList.html). ## Mutable Lists -A [MutableList](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/MutableList.html) consists of a single linked list together with a pointer that refers to the terminal empty node of that list. This makes list append a constant time operation because it avoids having to traverse the list in search for its terminal node. [MutableList](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/MutableList.html) is currently the standard implementation of [mutable.LinearSeq](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/LinearSeq.html) in Scala. +A [MutableList](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/MutableList.html) consists of a single linked list together with a pointer that refers to the terminal empty node of that list. This makes list append a constant time operation because it avoids having to traverse the list in search for its terminal node. [MutableList](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/MutableList.html) is currently the standard implementation of [mutable.LinearSeq](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/LinearSeq.html) in Scala. ## Queues @@ -85,13 +83,13 @@ Scala provides mutable queues in addition to immutable ones. You use a `mQueue` ## Array Sequences -Array sequences are mutable sequences of fixed size which store their elements internally in an `Array[Object]`. They are implemented in Scala by class [ArraySeq](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArraySeq.html). +Array sequences are mutable sequences of fixed size which store their elements internally in an `Array[Object]`. They are implemented in Scala by class [ArraySeq](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ArraySeq.html). -You would typically use an `ArraySeq` if you want an array for its performance characteristics, but you also want to create generic instances of the sequence where you do not know the type of the elements and you do not have a `ClassTag` to provide it at run-time. These issues are explained in the section on [arrays]({{ site.baseurl }}/overviews/collections/arrays.html). +You would typically use an `ArraySeq` if you want an array for its performance characteristics, but you also want to create generic instances of the sequence where you do not know the type of the elements, and you do not have a `ClassTag` to provide it at run-time. These issues are explained in the section on [arrays]({{ site.baseurl }}/overviews/collections/arrays.html). ## Stacks -You saw immutable stacks earlier. There is also a mutable version, supported by class [mutable.Stack](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/Stack.html). It works exactly the same as the immutable version except that modifications happen in place. +You saw immutable stacks earlier. There is also a mutable version, supported by class [mutable.Stack](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/Stack.html). It works exactly the same as the immutable version except that modifications happen in place. scala> val stack = new scala.collection.mutable.Stack[Int] stack: scala.collection.mutable.Stack[Int] = Stack() @@ -114,11 +112,11 @@ You saw immutable stacks earlier. There is also a mutable version, supported by ## Array Stacks -[ArrayStack](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayStack.html) is an alternative implementation of a mutable stack which is backed by an Array that gets re-sized as needed. It provides fast indexing and is generally slightly more efficient for most operations than a normal mutable stack. +[ArrayStack](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/ArrayStack.html) is an alternative implementation of a mutable stack which is backed by an Array that gets re-sized as needed. It provides fast indexing and is generally slightly more efficient for most operations than a normal mutable stack. ## Hash Tables -A hash table stores its elements in an underlying array, placing each item at a position in the array determined by the hash code of that item. Adding an element to a hash table takes only constant time, so long as there isn't already another element in the array that has the same hash code. Hash tables are thus very fast so long as the objects placed in them have a good distribution of hash codes. As a result, the default mutable map and set types in Scala are based on hash tables. You can access them also directly under the names [mutable.HashSet](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashSet.html) and [mutable.HashMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashMap.html). +A hash table stores its elements in an underlying array, placing each item at a position in the array determined by the hash code of that item. Adding an element to a hash table takes only constant time, so long as there isn't already another element in the array that has the same hash code. Hash tables are thus very fast so long as the objects placed in them have a good distribution of hash codes. As a result, the default mutable map and set types in Scala are based on hash tables. You can access them also directly under the names [mutable.HashSet](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/HashSet.html) and [mutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/HashMap.html). Hash sets and maps are used just like any other set or map. Here are some simple examples: @@ -137,11 +135,11 @@ Iteration over a hash table is not guaranteed to occur in any particular order. ## Weak Hash Maps -A weak hash map is a special kind of hash map where the garbage collector does not follow links from the map to the keys stored in it. This means that a key and its associated value will disappear from the map if there is no other reference to that key. Weak hash maps are useful for tasks such as caching, where you want to re-use an expensive function's result if the function is called again on the same key. If keys and function results are stored in a regular hash map, the map could grow without bounds, and no key would ever become garbage. Using a weak hash map avoids this problem. As soon as a key object becomes unreachable, it's entry is removed from the weak hashmap. Weak hash maps in Scala are implemented by class [WeakHashMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/WeakHashMap.html) as a wrapper of an underlying Java implementation `java.util.WeakHashMap`. +A weak hash map is a special kind of hash map where the garbage collector does not follow links from the map to the keys stored in it. This means that a key and its associated value will disappear from the map if there is no other reference to that key. Weak hash maps are useful for tasks such as caching, where you want to re-use an expensive function's result if the function is called again on the same key. If keys and function results are stored in a regular hash map, the map could grow without bounds, and no key would ever become garbage. Using a weak hash map avoids this problem. As soon as a key object becomes unreachable, it's entry is removed from the weak hashmap. Weak hash maps in Scala are implemented by class [WeakHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/WeakHashMap.html) as a wrapper of an underlying Java implementation `java.util.WeakHashMap`. ## Concurrent Maps -A concurrent map can be accessed by several threads at once. In addition to the usual [Map](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html) operations, it provides the following atomic operations: +A concurrent map can be accessed by several threads at once. In addition to the usual [Map](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Map.html) operations, it provides the following atomic operations: ### Operations in class ConcurrentMap @@ -156,7 +154,7 @@ A concurrent map can be accessed by several threads at once. In addition to the ## Mutable Bitsets -A mutable bit of type [mutable.BitSet](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/BitSet.html) set is just like an immutable one, except that it is modified in place. Mutable bit sets are slightly more efficient at updating than immutable ones, because they don't have to copy around `Long`s that haven't changed. +A mutable bit of type [mutable.BitSet](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/BitSet.html) set is just like an immutable one, except that it is modified in place. Mutable bit sets are slightly more efficient at updating than immutable ones, because they don't have to copy around `Long`s that haven't changed. scala> val bits = scala.collection.mutable.BitSet.empty bits: scala.collection.mutable.BitSet = BitSet() diff --git a/_overviews/collections/conversions-between-java-and-scala-collections.md b/_overviews/collections/conversions-between-java-and-scala-collections.md index fb184cfac2..3084038efc 100644 --- a/_overviews/collections/conversions-between-java-and-scala-collections.md +++ b/_overviews/collections/conversions-between-java-and-scala-collections.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Conversions Between Java and Scala Collections - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/conversions-between-java-and-scala-collections.html num: 17 @@ -15,7 +13,7 @@ permalink: /overviews/collections/:title.html Like Scala, Java also has a rich collections library. There are many similarities between the two. For instance, both libraries know iterators, iterables, sets, maps, and sequences. But there are also important differences. In particular, the Scala libraries put much more emphasis on immutable collections, and provide many more operations that transform a collection into a new one. -Sometimes you might need to pass from one collection framework to the other. For instance, you might want to access an existing Java collection as if it were a Scala collection. Or you might want to pass one of Scala's collections to a Java method that expects its Java counterpart. It is quite easy to do this, because Scala offers implicit conversions between all the major collection types in the [JavaConverters](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) object. In particular, you will find bidirectional conversions between the following types. +Sometimes you might need to pass from one collection framework to the other. For instance, you might want to access an existing Java collection as if it were a Scala collection. Or you might want to pass one of Scala's collections to a Java method that expects its Java counterpart. It is quite easy to do this, because Scala offers implicit conversions between all the major collection types in the [JavaConverters](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/JavaConverters$.html) object. In particular, you will find bidirectional conversions between the following types. Iterator <=> java.util.Iterator @@ -27,7 +25,7 @@ Sometimes you might need to pass from one collection framework to the other. For mutable.Map <=> java.util.Map mutable.ConcurrentMap <=> java.util.concurrent.ConcurrentMap -To enable these conversions, simply import them from the [JavaConverters](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/JavaConverters$.html) object: +To enable these conversions, simply import them from the [JavaConverters](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/JavaConverters$.html) object: scala> import collection.JavaConverters._ import collection.JavaConverters._ @@ -46,7 +44,7 @@ This enables conversions between Scala collections and their corresponding Java scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2).asJava m: java.util.Map[String,Int] = {abc=1, hello=2} -Internally, these conversion work by setting up a "wrapper" object that forwards all operations to the underlying collection object. So collections are never copied when converting between Java and Scala. An interesting property is that if you do a round-trip conversion from, say a Java type to its corresponding Scala type, and back to the same Java type, you end up with the identical collection object you have started with. +Internally, these conversions work by setting up a "wrapper" object that forwards all operations to the underlying collection object. So collections are never copied when converting between Java and Scala. An interesting property is that if you do a round-trip conversion from, say a Java type to its corresponding Scala type, and back to the same Java type, you end up with the identical collection object you have started with. Certain other Scala collections can also be converted to Java, but do not have a conversion back to the original Scala type: diff --git a/_overviews/collections/creating-collections-from-scratch.md b/_overviews/collections/creating-collections-from-scratch.md index cdff42e054..2468bf9e27 100644 --- a/_overviews/collections/creating-collections-from-scratch.md +++ b/_overviews/collections/creating-collections-from-scratch.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Creating Collections From Scratch - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/creating-collections-from-scratch.html num: 16 @@ -42,7 +40,7 @@ Besides `apply`, every collection companion object also defines a member `empty` Descendants of `Seq` classes provide also other factory operations in their companion objects. These are summarized in the following table. In short, there's * `concat`, which concatenates an arbitrary number of traversables together, -* `fill` and `tabulate`, which generate single or multi-dimensional sequences of given dimensions initialized by some expression or tabulating function, +* `fill` and `tabulate`, which generate single or multidimensional sequences of given dimensions initialized by some expression or tabulating function, * `range`, which generates integer sequences with some constant step length, and * `iterate`, which generates the sequence resulting from repeated application of a function to a start element. diff --git a/_overviews/collections/equality.md b/_overviews/collections/equality.md index 0e41a5ccd9..bb9abc6f06 100644 --- a/_overviews/collections/equality.md +++ b/_overviews/collections/equality.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Equality - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/creating-collections-from-scratch.html num: 13 @@ -15,7 +13,7 @@ permalink: /overviews/collections/:title.html The collection libraries have a uniform approach to equality and hashing. The idea is, first, to divide collections into sets, maps, and sequences. Collections in different categories are always unequal. For instance, `Set(1, 2, 3)` is unequal to `List(1, 2, 3)` even though they contain the same elements. On the other hand, within the same category, collections are equal if and only if they have the same elements (for sequences: the same elements in the same order). For example, `List(1, 2, 3) == Vector(1, 2, 3)`, and `HashSet(1, 2) == TreeSet(2, 1)`. -It does not matter for the equality check whether a collection is mutable or immutable. For a mutable collection one simply considers its current elements at the time the equality test is performed. This means that a mutable collection might be equal to different collections at different times, depending what elements are added or removed. This is a potential trap when using a mutable collection as a key in a hashmap. Example: +It does not matter for the equality check whether a collection is mutable or immutable. For a mutable collection one simply considers its current elements at the time the equality test is performed. This means that a mutable collection might be equal to different collections at different times, depending on what elements are added or removed. This is a potential trap when using a mutable collection as a key in a hashmap. Example: scala> import collection.mutable.{HashMap, ArrayBuffer} import collection.mutable.{HashMap, ArrayBuffer} diff --git a/_overviews/collections/introduction.md b/_overviews/collections/introduction.md index bf16363308..5fc2e3f301 100644 --- a/_overviews/collections/introduction.md +++ b/_overviews/collections/introduction.md @@ -1,15 +1,13 @@ --- layout: multipage-overview title: Introduction - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/introduction.html num: 1 -languages: [ja, zh-cn] +languages: [ja, zh-cn, ru] permalink: /overviews/collections/:title.html --- @@ -57,7 +55,7 @@ lines run at first try. **Fast:** Collection operations are tuned and optimized in the libraries. As a result, using collections is typically quite -efficient. You might be able to do a little bit better with carefully +efficient. You might be able to do a little better with carefully hand-tuned data structures and operations, but you might also do a lot worse by making some suboptimal implementation decisions along the way. What's more, collections have been recently adapted to parallel diff --git a/_overviews/collections/iterators.md b/_overviews/collections/iterators.md index 399243b2f6..78dfcc69f0 100644 --- a/_overviews/collections/iterators.md +++ b/_overviews/collections/iterators.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Iterators - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/iterators.html num: 15 @@ -13,7 +11,7 @@ languages: [ja, zh-cn] permalink: /overviews/collections/:title.html --- -An iterator is not a collection, but rather a way to access the elements of a collection one by one. The two basic operations on an iterator `it` are `next` and `hasNext`. A call to `it.next()` will return the next element of the iterator and advance the state of the iterator. Calling `next` again on the same iterator will then yield the element one beyond the one returned previously. If there are no more elements to return, a call to `next` will throw a `NoSuchElementException`. You can find out whether there are more elements to return using [Iterator](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html)'s `hasNext` method. +An iterator is not a collection, but rather a way to access the elements of a collection one by one. The two basic operations on an iterator `it` are `next` and `hasNext`. A call to `it.next()` will return the next element of the iterator and advance the state of the iterator. Calling `next` again on the same iterator will then yield the element one beyond the one returned previously. If there are no more elements to return, a call to `next` will throw a `NoSuchElementException`. You can find out whether there are more elements to return using [Iterator](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html)'s `hasNext` method. The most straightforward way to "step through" all the elements returned by an iterator `it` uses a while-loop: @@ -28,7 +26,7 @@ As always, for-expressions can be used as an alternate syntax for expressions in for (elem <- it) println(elem) -There's an important difference between the foreach method on iterators and the same method on traversable collections: When called on an iterator, `foreach` will leave the iterator at its end when it is done. So calling `next` again on the same iterator will fail with a `NoSuchElementException`. By contrast, when called on a collection, `foreach` leaves the number of elements in the collection unchanged (unless the passed function adds to removes elements, but this is discouraged, because it may lead to surprising results). +There's an important difference between the foreach method on iterators and the same method on traversable collections: When called on an iterator, `foreach` will leave the iterator at its end when it is done. So calling `next` again on the same iterator will fail with a `NoSuchElementException`. By contrast, when called on a collection, `foreach` leaves the number of elements in the collection unchanged (unless the passed function adds or removes elements, but this is discouraged, because it may lead to surprising results). The other operations that Iterator has in common with `Traversable` have the same property. For instance, iterators provide a `map` method, which returns a new iterator: @@ -76,7 +74,7 @@ destructively modified by invoking arbitrary methods. This creates the illusion the elements twice, but the effect is achieved through internal buffering. As usual, the underlying iterator `it` cannot be used directly and must be discarded. -In summary, iterators behave like collections _if one never accesses an iterator again after invoking a method on it_. The Scala collection libraries make this explicit with an abstraction [TraversableOnce](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/TraversableOnce.html), which is a common superclass of [Traversable](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Traversable.html) and [Iterator](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html). As the name implies, `TraversableOnce` objects can be traversed using `foreach` but the state of that object after the traversal is not specified. If the `TraversableOnce` object is in fact an `Iterator`, it will be at its end after the traversal, but if it is a `Traversable`, it will still exist as before. A common use case of `TraversableOnce` is as an argument type for methods that can take either an iterator or a traversable as argument. An example is the appending method `++` in class `Traversable`. It takes a `TraversableOnce` parameter, so you can append elements coming from either an iterator or a traversable collection. +In summary, iterators behave like collections _if one never accesses an iterator again after invoking a method on it_. The Scala collection libraries make this explicit with an abstraction [TraversableOnce](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/TraversableOnce.html), which is a common superclass of [Traversable](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html) and [Iterator](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html). As the name implies, `TraversableOnce` objects can be traversed using `foreach` but the state of that object after the traversal is not specified. If the `TraversableOnce` object is in fact an `Iterator`, it will be at its end after the traversal, but if it is a `Traversable`, it will still exist as before. A common use case of `TraversableOnce` is as an argument type for methods that can take either an iterator or a traversable as argument. An example is the appending method `++` in class `Traversable`. It takes a `TraversableOnce` parameter, so you can append elements coming from either an iterator or a traversable collection. All operations on iterators are summarized below. @@ -160,6 +158,22 @@ All operations on iterators are summarized below. | `it addString (b, start, sep, end)`| Adds a string to `StringBuilder` `b` which shows all elements returned by `it` between separators `sep` enclosed in strings `start` and `end`. `start`, `sep`, `end` are all optional. | | `it mkString (start, sep, end)` | Converts the collection to a string which shows all elements returned by `it` between separators `sep` enclosed in strings `start` and `end`. `start`, `sep`, `end` are all optional. | +### Laziness + +Unlike operations directly on a concrete collection like `List`, operations on `Iterator` are lazy. + +A lazy operation does not immediately compute all of its results. Instead, it computes the results as they are individually requested. + +So the expression `(1 to 10).iterator.map(println)` would not print anything to the screen. The `map` method in this case doesn't apply its argument function to the values in the range, it returns a new `Iterator` that will do this as each one is requested. Adding `.toList` to the end of that expression will actually print the elements. + +A consequence of this is that a method like `map` or `filter` won't necessarily apply its argument function to all the input elements. The expression `(1 to 10).iterator.map(println).take(5).toList` would only print the values `1` to `5`, for instance, since those are only ones that will be requested from the `Iterator` returned by `map`. + +This is one of the reasons why it's important to only use pure functions as arguments to `map`, `filter`, `fold` and similar methods. Remember, a pure function has no side-effects, so one would not normally use `println` in a `map`. `println` is used to demonstrate laziness as it's not normally visible with pure functions. + +Laziness is still valuable, despite often not being visible, as it can prevent unneeded computations from happening, and can allow for working with infinite sequences, like so: + + def zipWithIndex[A](i: Iterator[A]): Iterator[(Int, A)] = Stream.from(0).zip(i) + ### Buffered iterators Sometimes you want an iterator that can "look ahead", so that you can inspect the next element to be returned without advancing past that element. Consider for instance, the task to skip leading empty strings from an iterator that returns a sequence of strings. You might be tempted to write the following @@ -170,7 +184,7 @@ Sometimes you want an iterator that can "look ahead", so that you can inspect th But looking at this code more closely, it's clear that this is wrong: The code will indeed skip leading empty strings, but it will also advance `it` past the first non-empty string! -The solution to this problem is to use a buffered iterator. Class [BufferedIterator](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BufferedIterator.html) is a subclass of [Iterator](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html), which provides one extra method, `head`. Calling `head` on a buffered iterator will return its first element but will not advance the iterator. Using a buffered iterator, skipping empty words can be written as follows. +The solution to this problem is to use a buffered iterator. Class [BufferedIterator](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/BufferedIterator.html) is a subclass of [Iterator](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html), which provides one extra method, `head`. Calling `head` on a buffered iterator will return its first element but will not advance the iterator. Using a buffered iterator, skipping empty words can be written as follows. def skipEmptyWords(it: BufferedIterator[String]) = while (it.head.isEmpty) { it.next() } diff --git a/_overviews/collections/maps.md b/_overviews/collections/maps.md index 89a0663914..da373fabc9 100644 --- a/_overviews/collections/maps.md +++ b/_overviews/collections/maps.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Maps - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/maps.html num: 7 @@ -13,7 +11,7 @@ languages: [ja, zh-cn] permalink: /overviews/collections/:title.html --- -A [Map](http://www.scala-lang.org/api/current/scala/collection/Map.html) is an [Iterable](http://www.scala-lang.org/api/current/scala/collection/Iterable.html) consisting of pairs of keys and values (also named _mappings_ or _associations_). Scala's [Predef](http://www.scala-lang.org/api/current/scala/Predef$.html) object offers an implicit conversion that lets you write `key -> value` as an alternate syntax for the pair `(key, value)`. For instance `Map("x" -> 24, "y" -> 25, "z" -> 26)` means exactly the same as `Map(("x", 24), ("y", 25), ("z", 26))`, but reads better. +A [Map](https://www.scala-lang.org/api/current/scala/collection/Map.html) is an [Iterable](https://www.scala-lang.org/api/current/scala/collection/Iterable.html) consisting of pairs of keys and values (also named _mappings_ or _associations_). Scala's [Predef](https://www.scala-lang.org/api/current/scala/Predef$.html) object offers an implicit conversion that lets you write `key -> value` as an alternate syntax for the pair `(key, value)`. For instance `Map("x" -> 24, "y" -> 25, "z" -> 26)` means exactly the same as `Map(("x", 24), ("y", 25), ("z", 26))`, but reads better. The fundamental operations on maps are similar to those on sets. They are summarized in the following table and fall into the following categories: diff --git a/_overviews/collections/migrating-from-scala-27.md b/_overviews/collections/migrating-from-scala-27.md index c2c2bd9935..5e1efc7822 100644 --- a/_overviews/collections/migrating-from-scala-27.md +++ b/_overviews/collections/migrating-from-scala-27.md @@ -1,11 +1,8 @@ --- layout: multipage-overview title: Migrating from Scala 2.7 - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) num: 18 @@ -15,7 +12,7 @@ permalink: /overviews/collections/:title.html Porting your existing Scala applications to use the new collections should be almost automatic. There are only a couple of possible issues to take care of. -Generally, the old functionality of Scala 2.7 collections has been left in place. Some features have been deprecated, which means they will removed in some future release. You will get a _deprecation warning_ when you compile code that makes use of these features in Scala 2.8. In a few places deprecation was unfeasible, because the operation in question was retained in 2.8, but changed in meaning or performance characteristics. These cases will be flagged with _migration warnings_ when compiled under 2.8. To get full deprecation and migration warnings with suggestions how to change your code, pass the `-deprecation` and `-Xmigration` flags to `scalac` (note that `-Xmigration` is an extended option, so it starts with an `X`). You can also pass the same options to the `scala` REPL to get the warnings in an interactive session. Example: +Generally, the old functionality of Scala 2.7 collections has been left in place. Some features have been deprecated, which means they will be removed in some future release. You will get a _deprecation warning_ when you compile code that makes use of these features in Scala 2.8. In a few places deprecation was unfeasible, because the operation in question was retained in 2.8, but changed in meaning or performance characteristics. These cases will be flagged with _migration warnings_ when compiled under 2.8. To get full deprecation and migration warnings with suggestions how to change your code, pass the `-deprecation` and `-Xmigration` flags to `scalac` (note that `-Xmigration` is an extended option, so it starts with an `X`). You can also pass the same options to the `scala` REPL to get the warnings in an interactive session. Example: >scala -deprecation -Xmigration Welcome to Scala version 2.8.0.final @@ -41,7 +38,7 @@ Generally, the old functionality of Scala 2.7 collections has been left in place There are two parts of the old libraries which have been replaced wholesale, and for which deprecation warnings were not feasible. -1. The previous `scala.collection.jcl` package is gone. This package tried to mimick some of the Java collection library design in Scala, but in doing so broke many symmetries. Most people who wanted Java collections bypassed `jcl` and used `java.util` directly. Scala 2.8 offers automatic conversion mechanisms between both collection libraries in the [JavaConversions]({{ site.baseurl }}/overviews/collections/conversions-between-java-and-scala-collections.html) object which replaces the `jcl` package. +1. The previous `scala.collection.jcl` package is gone. This package tried to mimic aspects of the Java collection library design in Scala, but in doing so broke many symmetries. Most people who wanted Java collections bypassed `jcl` and used `java.util` directly. Scala 2.8 offers automatic conversion mechanisms between both collection libraries in the [JavaConversions]({{ site.baseurl }}/overviews/collections/conversions-between-java-and-scala-collections.html) object which replaces the `jcl` package. 2. Projections have been generalized and cleaned up and are now available as views. It seems that projections were used rarely, so not much code should be affected by this change. So, if your code uses either `jcl` or projections there might be some minor rewriting to do. diff --git a/_overviews/collections/overview.md b/_overviews/collections/overview.md index e0a7a33c29..44821b24ca 100644 --- a/_overviews/collections/overview.md +++ b/_overviews/collections/overview.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Mutable and Immutable Collections - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/overview.html num: 2 @@ -41,10 +39,10 @@ mutable collection means you need to understand which code changes which collection when. A collection in package `scala.collection` can be either mutable or -immutable. For instance, [collection.IndexedSeq\[T\]](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html) -is a superclass of both [collection.immutable.IndexedSeq\[T\]](http://www.scala-lang.org/api/current/scala/collection/immutable/IndexedSeq.html) +immutable. For instance, [collection.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/IndexedSeq.html) +is a superclass of both [collection.immutable.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/IndexedSeq.html) and -[collection.mutable.IndexedSeq\[T\]](http://www.scala-lang.org/api/current/scala/collection/mutable/IndexedSeq.html) +[collection.mutable.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/IndexedSeq.html) Generally, the root collections in package `scala.collection` define the same interface as the immutable collections, and the mutable collections in package @@ -94,23 +92,25 @@ can be accessed alternatively as // is always automatically imported Other types aliased are -[Traversable](http://www.scala-lang.org/api/current/scala/collection/Traversable.html), [Iterable](http://www.scala-lang.org/api/current/scala/collection/Iterable.html), [Seq](http://www.scala-lang.org/api/current/scala/collection/Seq.html), [IndexedSeq](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html), [Iterator](http://www.scala-lang.org/api/current/scala/collection/Iterator.html), [Stream](http://www.scala-lang.org/api/current/scala/collection/immutable/Stream.html), [Vector](http://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html), [StringBuilder](http://www.scala-lang.org/api/current/scala/collection/mutable/StringBuilder.html), and [Range](http://www.scala-lang.org/api/current/scala/collection/immutable/Range.html). +[Traversable](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html), [Iterable](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterable.html), [Seq](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Seq.html), [IndexedSeq](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/IndexedSeq.html), [Iterator](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html), [Stream](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Stream.html), [Vector](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html), [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/StringBuilder.html), and [Range](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html). The following figure shows all collections in package `scala.collection`. These are all high-level abstract classes or traits, which generally have mutable as well as immutable implementations. -[]({{ site.baseurl }}/resources/images/collections.png) +[![General collection hierarchy][1]][1] The following figure shows all collections in package `scala.collection.immutable`. -[]({{ site.baseurl }}/resources/images/collections.immutable.png) +[![Immutable collection hierarchy][2]][2] And the following figure shows all collections in package `scala.collection.mutable`. -[]({{ site.baseurl }}/resources/images/collections.mutable.png) +[![Mutable collection hierarchy][3]][3] + +Legend: -(All three figures were generated by Matthias at decodified.com). +[![Graph legend][4]][4] ## An Overview of the Collections API ## @@ -144,3 +144,9 @@ This behavior which is implemented everywhere in the collections libraries is ca Most of the classes in the collections hierarchy exist in three variants: root, mutable, and immutable. The only exception is the Buffer trait which only exists as a mutable collection. In the following, we will review these classes one by one. + + + [1]: /resources/images/tour/collections-diagram.svg + [2]: /resources/images/tour/collections-immutable-diagram.svg + [3]: /resources/images/tour/collections-mutable-diagram.svg + [4]: /resources/images/tour/collections-legend-diagram.svg diff --git a/_overviews/collections/performance-characteristics.md b/_overviews/collections/performance-characteristics.md index c43aeabb68..f3131c9274 100644 --- a/_overviews/collections/performance-characteristics.md +++ b/_overviews/collections/performance-characteristics.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Performance Characteristics - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/performance-characteristics.html num: 12 @@ -74,8 +72,8 @@ The first table treats sequence types--both immutable and mutable--with the foll | **tail** | Producing a new sequence that consists of all elements except the first one. | | **apply** | Indexing. | | **update** | Functional update (with `updated`) for immutable sequences, side-effecting update (with `update` for mutable sequences). | -| **prepend**| Adding an element to the front of the sequence. For immutable sequences, this produces a new sequence. For mutable sequences it modified the existing sequence. | -| **append** | Adding an element and the end of the sequence. For immutable sequences, this produces a new sequence. For mutable sequences it modified the existing sequence. | +| **prepend**| Adding an element to the front of the sequence. For immutable sequences, this produces a new sequence. For mutable sequences it modifies the existing sequence. | +| **append** | Adding an element and the end of the sequence. For immutable sequences, this produces a new sequence. For mutable sequences it modifies the existing sequence. | | **insert** | Inserting an element at an arbitrary position in the sequence. This is only supported directly for mutable sequences. | The second table treats mutable and immutable sets and maps with the following operations: diff --git a/_overviews/collections/seqs.md b/_overviews/collections/seqs.md index 3e12de6fc1..fcc125f300 100644 --- a/_overviews/collections/seqs.md +++ b/_overviews/collections/seqs.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: The sequence traits Seq, IndexedSeq, and LinearSeq - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/seqs.html num: 5 @@ -13,7 +11,7 @@ languages: [ja, zh-cn] permalink: /overviews/collections/:title.html --- -The [Seq](http://www.scala-lang.org/api/current/scala/collection/Seq.html) trait represents sequences. A sequence is a kind of iterable that has a `length` and whose elements have fixed index positions, starting from `0`. +The [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) trait represents sequences. A sequence is a kind of iterable that has a `length` and whose elements have fixed index positions, starting from `0`. The operations on sequences, summarized in the table below, fall into the following categories: @@ -74,7 +72,7 @@ If a sequence is mutable, it offers in addition a side-effecting `update` method | `xs union ys` |Multiset union; same as `xs ++ ys`.| | `xs.distinct` |A subsequence of `xs` that contains no duplicated element.| -Trait [Seq](http://www.scala-lang.org/api/current/scala/collection/Seq.html) has two subtraits [LinearSeq](http://www.scala-lang.org/api/current/scala/collection/LinearSeq.html), and [IndexedSeq](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html). These do not add any new operations, but each offers different performance characteristics: A linear sequence has efficient `head` and `tail` operations, whereas an indexed sequence has efficient `apply`, `length`, and (if mutable) `update` operations. Frequently used linear sequences are `scala.collection.immutable.List` and `scala.collection.immutable.Stream`. Frequently used indexed sequences are `scala.Array` and `scala.collection.mutable.ArrayBuffer`. The `Vector` class provides an interesting compromise between indexed and linear access. It has both effectively constant time indexing overhead and constant time linear access overhead. Because of this, vectors are a good foundation for mixed access patterns where both indexed and linear accesses are used. You'll learn more on vectors [later](concrete-immutable-collection-classes.html). +Trait [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) has two subtraits [LinearSeq](https://www.scala-lang.org/api/current/scala/collection/LinearSeq.html), and [IndexedSeq](https://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html). These do not add any new operations, but each offers different performance characteristics: A linear sequence has efficient `head` and `tail` operations, whereas an indexed sequence has efficient `apply`, `length`, and (if mutable) `update` operations. Frequently used linear sequences are `scala.collection.immutable.List` and `scala.collection.immutable.Stream`. Frequently used indexed sequences are `scala.Array` and `scala.collection.mutable.ArrayBuffer`. The `Vector` class provides an interesting compromise between indexed and linear access. It has both effectively constant time indexing overhead and constant time linear access overhead. Because of this, vectors are a good foundation for mixed access patterns where both indexed and linear accesses are used. You'll learn more on vectors [later](concrete-immutable-collection-classes.html). ### Buffers ### diff --git a/_overviews/collections/sets.md b/_overviews/collections/sets.md index 4b06a0501f..b475fc3fda 100644 --- a/_overviews/collections/sets.md +++ b/_overviews/collections/sets.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Sets - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/sets.html num: 6 @@ -115,9 +113,9 @@ Two subtraits of sets are `SortedSet` and `BitSet`. ### Sorted Sets ### -A [SortedSet](http://www.scala-lang.org/api/current/scala/collection/SortedSet.html) is a set that produces its elements (using `iterator` or `foreach`) in a given ordering (which can be freely chosen at the time the set is created). The default representation of a [SortedSet](http://www.scala-lang.org/api/current/scala/collection/SortedSet.html) is an ordered binary tree which maintains the invariant that all elements in the left subtree of a node are smaller than all elements in the right subtree. That way, a simple in order traversal can return all tree elements in increasing order. Scala's class [immutable.TreeSet](http://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html) uses a _red-black_ tree implementation to maintain this ordering invariant and at the same time keep the tree _balanced_-- meaning that all paths from the root of the tree to a leaf have lengths that differ only by at most one element. +A [SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) is a set that produces its elements (using `iterator` or `foreach`) in a given ordering (which can be freely chosen at the time the set is created). The default representation of a [SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) is an ordered binary tree which maintains the invariant that all elements in the left subtree of a node are smaller than all elements in the right subtree. That way, a simple in order traversal can return all tree elements in increasing order. Scala's class [immutable.TreeSet](https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html) uses a _red-black_ tree implementation to maintain this ordering invariant and at the same time keep the tree _balanced_-- meaning that all paths from the root of the tree to a leaf have lengths that differ only by at most one element. -To create an empty [TreeSet](http://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html), you could first specify the desired ordering: +To create an empty [TreeSet](https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html), you could first specify the desired ordering: scala> val myOrdering = Ordering.fromLessThan[String](_ > _) myOrdering: scala.math.Ordering[String] = ... @@ -147,6 +145,6 @@ Sorted sets also support ranges of elements. For instance, the `range` method re ### Bitsets ### -Bitsets are sets of non-negative integer elements that are implemented in one or more words of packed bits. The internal representation of a [BitSet](http://www.scala-lang.org/api/current/scala/collection/BitSet.html) uses an array of `Long`s. The first `Long` covers elements from 0 to 63, the second from 64 to 127, and so on (Immutable bitsets of elements in the range of 0 to 127 optimize the array away and store the bits directly in a one or two `Long` fields.) For every `Long`, each of its 64 bits is set to 1 if the corresponding element is contained in the set, and is unset otherwise. It follows that the size of a bitset depends on the largest integer that's stored in it. If `N` is that largest integer, then the size of the set is `N/64` `Long` words, or `N/8` bytes, plus a small number of extra bytes for status information. +Bitsets are sets of non-negative integer elements that are implemented in one or more words of packed bits. The internal representation of a [BitSet](https://www.scala-lang.org/api/current/scala/collection/BitSet.html) uses an array of `Long`s. The first `Long` covers elements from 0 to 63, the second from 64 to 127, and so on (Immutable bitsets of elements in the range of 0 to 127 optimize the array away and store the bits directly in a one or two `Long` fields.) For every `Long`, each of its 64 bits is set to 1 if the corresponding element is contained in the set, and is unset otherwise. It follows that the size of a bitset depends on the largest integer that's stored in it. If `N` is that largest integer, then the size of the set is `N/64` `Long` words, or `N/8` bytes, plus a small number of extra bytes for status information. Bitsets are hence more compact than other sets if they contain many small elements. Another advantage of bitsets is that operations such as membership test with `contains`, or element addition and removal with `+=` and `-=` are all extremely efficient. diff --git a/_overviews/collections/strings.md b/_overviews/collections/strings.md index b1729328de..68f2f72552 100644 --- a/_overviews/collections/strings.md +++ b/_overviews/collections/strings.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Strings - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/strings.html num: 11 diff --git a/_overviews/collections/trait-iterable.md b/_overviews/collections/trait-iterable.md index ed2938fe6d..ac72783f41 100644 --- a/_overviews/collections/trait-iterable.md +++ b/_overviews/collections/trait-iterable.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Trait Iterable - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/trait-iterable.html num: 4 @@ -62,8 +60,8 @@ Trait `Iterable` also adds some other methods to `Traversable` that can be imple | **Comparison:** | | | `xs sameElements ys` |A test whether `xs` and `ys` contain the same elements in the same order| -In the inheritance hierarchy below Iterable you find three traits: [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html), [Set](https://www.scala-lang.org/api/current/scala/collection/Set.html), and [Map](https://www.scala-lang.org/api/current/scala/collection/Map.html). `Seq` and `Map` implement the [PartialFunction](https://www.scala-lang.org/api/current/scala/PartialFunction.html) trait with its `apply` and `isDefinedAt` methods, each implemented differently. `Set` gets its `apply` method from [GenSetLike](https://www.scala-lang.org/api/current/scala/collection/GenSetLike.html). +In the inheritance hierarchy below Iterable you find three traits: [Seq](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Seq.html), [Set](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Set.html), and [Map](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Map.html). `Seq` and `Map` implement the [PartialFunction](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/PartialFunction.html) trait with its `apply` and `isDefinedAt` methods, each implemented differently. `Set` gets its `apply` method from [GenSetLike](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/GenSetLike.html). -For sequences, `apply` is positional indexing, where elements are always numbered from `0`. That is, `Seq(1, 2, 3)(1)` gives `2`. For sets, `apply` is a membership test. For instance, `Set('a', 'b', 'c')('b')` gives `true` whereas `Set()('a')` gives `false`. Finally for maps, `apply` is a selection. For instance, `Map('a' -> 1, 'b' -> 10, 'c' -> 100)('b')` gives `10`. +For sequences, `apply` is positional indexing, where elements are always numbered from `0`. That is, `Seq(1, 2, 3)(1)` gives `2`. For sets, `apply` is a membership test. For instance, `Set('a', 'b', 'c')('b')` gives `true` whereas `Set()('a')` gives `false`. Finally, for maps, `apply` is a selection. For instance, `Map('a' -> 1, 'b' -> 10, 'c' -> 100)('b')` gives `10`. In the following, we will explain each of the three kinds of collections in more detail. diff --git a/_overviews/collections/trait-traversable.md b/_overviews/collections/trait-traversable.md index ad749d8097..d2173cb789 100644 --- a/_overviews/collections/trait-traversable.md +++ b/_overviews/collections/trait-traversable.md @@ -1,11 +1,8 @@ --- layout: multipage-overview title: Trait Traversable - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) num: 3 @@ -28,7 +25,7 @@ The `foreach` method is meant to traverse all elements of the collection, and ap * **Conversions** `toArray`, `toList`, `toIterable`, `toSeq`, `toIndexedSeq`, `toStream`, `toSet`, `toMap`, which turn a `Traversable` collection into something more specific. All these conversions return their receiver argument unchanged if the run-time type of the collection already matches the demanded collection type. For instance, applying `toList` to a list will yield the list itself. * **Copying operations** `copyToBuffer` and `copyToArray`. As their names imply, these copy collection elements to a buffer or array, respectively. * **Size info** operations `isEmpty`, `nonEmpty`, `size`, and `hasDefiniteSize`: Traversable collections can be finite or infinite. An example of an infinite traversable collection is the stream of natural numbers `Stream.from(0)`. The method `hasDefiniteSize` indicates whether a collection is possibly infinite. If `hasDefiniteSize` returns true, the collection is certainly finite. If it returns false, the collection has not been fully elaborated yet, so it might be infinite or finite. -* **Element retrieval** operations `head`, `last`, `headOption`, `lastOption`, and `find`. These select the first or last element of a collection, or else the first element matching a condition. Note, however, that not all collections have a well-defined meaning of what "first" and "last" means. For instance, a hash set might store elements according to their hash keys, which might change from run to run. In that case, the "first" element of a hash set could also be different for every run of a program. A collection is _ordered_ if it always yields its elements in the same order. Most collections are ordered, but some (_e.g._ hash sets) are not-- dropping the ordering gives a little bit of extra efficiency. Ordering is often essential to give reproducible tests and to help in debugging. That's why Scala collections give ordered alternatives for all collection types. For instance, the ordered alternative for `HashSet` is `LinkedHashSet`. +* **Element retrieval** operations `head`, `last`, `headOption`, `lastOption`, and `find`. These select the first or last element of a collection, or else the first element matching a condition. Note, however, that not all collections have a well-defined meaning of what "first" and "last" means. For instance, a hash set might store elements according to their hash keys, which might change from run to run. In that case, the "first" element of a hash set could also be different for every run of a program. A collection is _ordered_ if it always yields its elements in the same order. Most collections are ordered, but some (_e.g._ hash sets) are not-- dropping the ordering gives a little extra efficiency. Ordering is often essential to give reproducible tests and to help in debugging. That's why Scala collections give ordered alternatives for all collection types. For instance, the ordered alternative for `HashSet` is `LinkedHashSet`. * **Sub-collection retrieval operations** `tail`, `init`, `slice`, `take`, `drop`, `takeWhile`, `dropWhile`, `filter`, `filterNot`, `withFilter`. These all return some sub-collection identified by an index range or some predicate. * **Subdivision operations** `splitAt`, `span`, `partition`, `groupBy`, which split the elements of this collection into several sub-collections. * **Element tests** `exists`, `forall`, `count` which test collection elements with a given predicate. @@ -44,7 +41,7 @@ The `foreach` method is meant to traverse all elements of the collection, and ap | **Abstract Method:** | | | `xs foreach f` |Executes function `f` for every element of `xs`.| | **Addition:** | | -| `xs ++ ys` |A collection consisting of the elements of both `xs` and `ys`. `ys` is a [TraversableOnce](http://www.scala-lang.org/api/current/scala/collection/TraversableOnce.html) collection, i.e., either a [Traversable](http://www.scala-lang.org/api/current/scala/collection/Traversable.html) or an [Iterator](http://www.scala-lang.org/api/current/scala/collection/Iterator.html).| +| `xs ++ ys` |A collection consisting of the elements of both `xs` and `ys`. `ys` is a [TraversableOnce](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/TraversableOnce.html) collection, i.e., either a [Traversable](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html) or an [Iterator](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html).| | **Maps:** | | | `xs map f` |The collection obtained from applying the function f to every element in `xs`.| | `xs flatMap f` |The collection obtained from applying the collection-valued function `f` to every element in `xs` and concatenating the results.| diff --git a/_overviews/collections/views.md b/_overviews/collections/views.md index 09e5b8f7ff..1798d77cf4 100644 --- a/_overviews/collections/views.md +++ b/_overviews/collections/views.md @@ -1,11 +1,9 @@ --- layout: multipage-overview title: Views - -discourse: true - partof: collections -overview-name: Collections +overview-name: Collections (Scala 2.8 - 2.12) +new-version: /overviews/collections-2.13/views.html num: 14 @@ -75,7 +73,7 @@ There are two reasons why you might want to consider using views. The first is p def isPalindrome(x: String) = x == x.reverse def findPalindrome(s: Seq[String]) = s find isPalindrome -Now, assume you have a very long sequence words and you want to find a palindrome in the first million words of that sequence. Can you re-use the definition of `findPalindrome`? Of course, you could write: +Now, assume you have a very long sequence of words, and you want to find a palindrome in the first million words of that sequence. Can you re-use the definition of `findPalindrome`? Of course, you could write: findPalindrome(words take 1000000) diff --git a/_overviews/compiler-options/errors.md b/_overviews/compiler-options/errors.md new file mode 100644 index 0000000000..8128ef96ae --- /dev/null +++ b/_overviews/compiler-options/errors.md @@ -0,0 +1,110 @@ +--- +layout: singlepage-overview +title: Error Formatting +--- + +# Introduction + +An advanced mechanism for formatting type errors and inspecting missing +implicits has been introduced in Scala 2.13.6. +It is based on the compiler plugin [splain](https://github.com/tek/splain). + +This tool abstracts several classes of compiler errors with simple data types +that can be processed by a few built-in routines as well as +[user-provided analyzer plugins](/overviews/plugins/index.html). + +The most significant feature is the illustration of chains of implicit instances +that allows a user to determine the root cause of an implicit error: + +![implicits](/resources/img/implicits-circe.jpg) + +# Basic Configuration + +* `-Vimplicits` enables printing of implicit chains +* `-Vtype-diffs` enables colored diffs for found/required errors + +## Additional Configuration + +`-Vimplicits-verbose-tree` shows the implicits between the error site and the +root cause, see [#implicit-resolution-chains]. + +`-Vimplicits-max-refined` reduces the verbosity of refined types, see +[#truncating-refined-types]. + +# Features + +The error formatting engine provides the following enhancements: + +## Infix Types + +Instead of `shapeless.::[A, HNil]`, prints `A :: HNil`. + +## Found/Required Types + +Rather than printing up to four types, only the dealiased types are shown as a colored diff: + +![foundreq](/resources/img/foundreq.jpg) + +## Implicit Resolution Chains + +When an implicit is not found, only the outermost error at the invocation point is printed by the regular error +reporter. +Previously, the flag `-Xlog-implicits` caused the compiler to print all information about processed implicits, but the +output was highly verbose and contained all invalid implicits for parameters that have been resolved successfully. +The flag has been renamed to `-Vimplicits` and prints a compact list of all involved implicit instances. +`-Xlog-implicits` will continue to work as a deprecated alias. + +![compact](/resources/img/implicits-compact.jpg) + +Here, `!I` stands for *could not find implicit value*, the name of the implicit +parameter is in yellow, and its type in green. + +If the parameter `-Vimplicits-verbose-tree` is given, all intermediate implicits will be +printed, potentially spanning tens of lines. +An example of this is the circe error at the top of the page. + +For comparison, this is the regular compiler output for this case: + +``` +[error] /path/Example.scala:20:5: could not find implicit value for parameter a: io.circe.Decoder[A] +[error] A.fun +[error] ^ +``` + +## Infix Type and Type Argument Line Breaking + +Types longer than 79 characters will be split into multiple lines: + +``` +implicit error; +!I e: String +f invalid because +!I impPar4: List[ + ( + VeryLongTypeName :::: + VeryLongTypeName :::: + VeryLongTypeName :::: + VeryLongTypeName + ) + :::: + (Short :::: Short) :::: + ( + VeryLongTypeName :::: + VeryLongTypeName :::: + VeryLongTypeName :::: + VeryLongTypeName + ) + :::: + VeryLongTypeName :::: + VeryLongTypeName :::: + VeryLongTypeName :::: + VeryLongTypeName +] +``` + +## Truncating Refined Types + +Refined types, like `T { type A = X; type B = Y }`, can get rather long and clutter up error messages. +The option `-Vimplicits-max-refined` controls how many characters the refinement may take up before it gets displayed as +`T {...}`. +The default is to display the unabridged type. diff --git a/_overviews/compiler-options/index.md b/_overviews/compiler-options/index.md index aa228ba67d..c4fd52f010 100644 --- a/_overviews/compiler-options/index.md +++ b/_overviews/compiler-options/index.md @@ -1,8 +1,6 @@ --- layout: singlepage-overview title: Scala Compiler Options - -discourse: true --- + + diff --git a/_overviews/scala3-book/string-interpolation.md b/_overviews/scala3-book/string-interpolation.md new file mode 100644 index 0000000000..1ba335e3b7 --- /dev/null +++ b/_overviews/scala3-book/string-interpolation.md @@ -0,0 +1,370 @@ +--- +title: String Interpolation +type: chapter +description: This page provides more information about creating strings and using string interpolation. +languages: [ru, zh-cn] +num: 18 +previous-page: first-look-at-types +next-page: control-structures +redirect_from: + - /overviews/core/string-interpolation.html +--- + +## Introduction + +String interpolation provides a way to use variables inside strings. +For instance: + +{% tabs example-1 %} +{% tab 'Scala 2 and 3' for=example-1 %} +```scala +val name = "James" +val age = 30 +println(s"$name is $age years old") // "James is 30 years old" +``` +{% endtab %} +{% endtabs %} + +Using string interpolation consists of putting an `s` in front of your string +quotes, and prefixing any variable names with a `$` symbol. + +## String Interpolators + +The `s` that you place before the string is just one possible interpolator that Scala +provides. + +Scala provides three string interpolation methods out of the box: `s`, `f` and `raw`. +Further, a string interpolator is just a special method, so it is possible to define your +own. For instance, some database libraries define a `sql` interpolator that returns a +database query. + +### The `s` Interpolator (`s`-Strings) + +Prepending `s` to any string literal allows the usage of variables directly in the string. You've already seen an example here: + +{% tabs example-2 %} +{% tab 'Scala 2 and 3' for=example-2 %} +```scala +val name = "James" +val age = 30 +println(s"$name is $age years old") // "James is 30 years old" +``` +{% endtab %} +{% endtabs %} + +Here, the `$name` and `$age` placeholders in the string are replaced by the results of +calling `name.toString` and `age.toString`, respectively. The `s`-String will have +access to all variables that are currently in scope. + +While it may seem obvious, it's important to note here that string interpolation will _not_ happen in normal string literals: + +{% tabs example-3 %} +{% tab 'Scala 2 and 3' for=example-3 %} +```scala +val name = "James" +val age = 30 +println("$name is $age years old") // "$name is $age years old" +``` +{% endtab %} +{% endtabs %} + +String interpolators can also take arbitrary expressions. For example: + +{% tabs example-4 %} +{% tab 'Scala 2 and 3' for=example-4 %} +```scala +println(s"2 + 2 = ${2 + 2}") // "2 + 2 = 4" +val x = -1 +println(s"x.abs = ${x.abs}") // "x.abs = 1" +``` +{% endtab %} +{% endtabs %} + +Any arbitrary expression can be embedded in `${}`. + +For some special characters, it is necessary to escape them when embedded within a string. +To represent an actual dollar sign you can double it `$$`, like here: + +{% tabs example-5 %} +{% tab 'Scala 2 and 3' for=example-5 %} +```scala +println(s"New offers starting at $$14.99") // "New offers starting at $14.99" +``` +{% endtab %} +{% endtabs %} + +Double quotes also need to be escaped. This can be done by using triple quotes as shown: + +{% tabs example-6 %} +{% tab 'Scala 2 and 3' for=example-6 %} +```scala +println(s"""{"name":"James"}""") // `{"name":"James"}` +``` +{% endtab %} +{% endtabs %} + +Finally, all multi-line string literals can also be interpolated + +{% tabs example-7 %} +{% tab 'Scala 2 and 3' for=example-7 %} +```scala +println(s"""name: "$name", + |age: $age""".stripMargin) +``` + +This will print as follows: + +``` +name: "James" +age: 30 +``` +{% endtab %} +{% endtabs %} + +### The `f` Interpolator (`f`-Strings) + +Prepending `f` to any string literal allows the creation of simple formatted strings, similar to `printf` in other languages. When using the `f` +interpolator, all variable references should be followed by a `printf`-style format string, like `%d`. Let's look at an example: + +{% tabs example-8 %} +{% tab 'Scala 2 and 3' for=example-8 %} +```scala +val height = 1.9d +val name = "James" +println(f"$name%s is $height%2.2f meters tall") // "James is 1.90 meters tall" +``` +{% endtab %} +{% endtabs %} + +The `f` interpolator is typesafe. If you try to pass a format string that only works for integers but pass a double, the compiler will issue an +error. For example: + +{% tabs f-interpolator-error class=tabs-scala-version %} + +{% tab 'Scala 2' for=f-interpolator-error %} +```scala +val height: Double = 1.9d + +scala> f"$height%4d" +:9: error: type mismatch; + found : Double + required: Int + f"$height%4d" + ^ +``` +{% endtab %} + +{% tab 'Scala 3' for=f-interpolator-error %} +```scala +val height: Double = 1.9d + +scala> f"$height%4d" +-- Error: ---------------------------------------------------------------------- +1 |f"$height%4d" + | ^^^^^^ + | Found: (height : Double), Required: Int, Long, Byte, Short, BigInt +1 error found + +``` +{% endtab %} +{% endtabs %} + +The `f` interpolator makes use of the string format utilities available from Java. The formats allowed after the `%` character are outlined in the +[Formatter javadoc][java-format-docs]. If there is no `%` character after a variable +definition a formatter of `%s` (`String`) is assumed. + +Finally, as in Java, use `%%` to get a literal `%` character in the output string: + +{% tabs literal-percent %} +{% tab 'Scala 2 and 3' for=literal-percent %} +```scala +println(f"3/19 is less than 20%%") // "3/19 is less than 20%" +``` +{% endtab %} +{% endtabs %} + +### The `raw` Interpolator + +The raw interpolator is similar to the `s` interpolator except that it performs no escaping of literals within the string. Here's an example processed string: + +{% tabs example-9 %} +{% tab 'Scala 2 and 3' for=example-9 %} +```scala +scala> s"a\nb" +res0: String = +a +b +``` +{% endtab %} +{% endtabs %} + +Here the `s` string interpolator replaced the characters `\n` with a return character. The `raw` interpolator will not do that. + +{% tabs example-10 %} +{% tab 'Scala 2 and 3' for=example-10 %} +```scala +scala> raw"a\nb" +res1: String = a\nb +``` +{% endtab %} +{% endtabs %} + +The raw interpolator is useful when you want to avoid having expressions like `\n` turn into a return character. + +Furthermore, the raw interpolator allows the usage of variables, which are replaced with their value, just as the s interpolator. + +{% tabs example-11 %} +{% tab 'Scala 2 and 3' for=example-11 %} +```scala +scala> val foo = 42 +scala> raw"a\n$foo" +res1: String = a\n42 +``` +{% endtab %} +{% endtabs %} + +## Advanced Usage + +In addition to the three default string interpolators, users can define their own. + +The literal `s"Hi $name"` is parsed by Scala as a _processed_ string literal. +This means that the compiler does some additional work to this literal. The specifics +of processed strings and string interpolation are described in [SIP-11][sip-11], but +here's a quick example to help illustrate how they work. + +### Custom Interpolators + +In Scala, all processed string literals are simple code transformations. Anytime the compiler encounters a processed string literal of the form: + +{% tabs example-12 %} +{% tab 'Scala 2 and 3' for=example-12 %} +```scala +id"string content" +``` +{% endtab %} +{% endtabs %} + +it transforms it into a method call (`id`) on an instance of [StringContext](https://www.scala-lang.org/api/current/scala/StringContext.html). +This method can also be available on implicit scope. +To define our own string interpolation, we need to create an implicit class (Scala 2) or an `extension` method (Scala 3) that adds a new method to `StringContext`. + +As a trivial example, let's assume we have a simple `Point` class and want to create a custom interpolator that turns `p"a,b"` into a `Point` object. + +{% tabs custom-interpolator-1 %} +{% tab 'Scala 2 and 3' for=custom-interpolator-1 %} +```scala +case class Point(x: Double, y: Double) + +val pt = p"1,-2" // Point(1.0,-2.0) +``` +{% endtab %} +{% endtabs %} + +We'd create a custom `p`-interpolator by first implementing a `StringContext` extension +with something like: + +{% tabs custom-interpolator-2 class=tabs-scala-version %} + +{% tab 'Scala 2' for=custom-interpolator-2 %} +```scala +implicit class PointHelper(val sc: StringContext) extends AnyVal { + def p(args: Any*): Point = ??? +} +``` + +**Note:** It's important to extend `AnyVal` in Scala 2.x to prevent runtime instantiation on each interpolation. See the [value class]({% link _overviews/core/value-classes.md %}) documentation for more. + +{% endtab %} + +{% tab 'Scala 3' for=custom-interpolator-2 %} +```scala +extension (sc: StringContext) + def p(args: Any*): Point = ??? +``` +{% endtab %} + +{% endtabs %} + +Once this extension is in scope and the Scala compiler encounters `p"some string"`, it +will process `some string` to turn it into String tokens and expression arguments for +each embedded variable in the string. + +For example, `p"1, $someVar"` would turn into: + +{% tabs extension-desugaring class=tabs-scala-version %} + +{% tab 'Scala 2' for=extension-desugaring %} +```scala +new StringContext("1, ", "").p(someVar) +``` + +The implicit class is then used to rewrite it to the following: + +```scala +new PointHelper(new StringContext("1, ", "")).p(someVar) +``` +{% endtab %} + +{% tab 'Scala 3' for=extension-desugaring %} +```scala +StringContext("1, ","").p(someVar) +``` +{% endtab %} + +{% endtabs %} + +As a result, each of the fragments of the processed String are exposed in the +`StringContext.parts` member, while any expressions values in the string are passed in +to the method's `args` parameter. + +### Example Implementation + +A naive implementation of our Point interpolator method might look something like below, +though a more sophisticated method may choose to have more precise control over the +processing of the string `parts` and expression `args` instead of reusing the +`s`-Interpolator. + +{% tabs naive-implementation class=tabs-scala-version %} + +{% tab 'Scala 2' for=naive-implementation %} +```scala +implicit class PointHelper(val sc: StringContext) extends AnyVal { + def p(args: Double*): Point = { + // reuse the `s`-interpolator and then split on ',' + val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } + Point(pts(0), pts(1)) + } +} + +val x=12.0 + +p"1, -2" // Point(1.0, -2.0) +p"${x/5}, $x" // Point(2.4, 12.0) +``` +{% endtab %} + +{% tab 'Scala 3' for=naive-implementation %} +```scala +extension (sc: StringContext) + def p(args: Double*): Point = { + // reuse the `s`-interpolator and then split on ',' + val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } + Point(pts(0), pts(1)) + } + +val x=12.0 + +p"1, -2" // Point(1.0, -2.0) +p"${x/5}, $x" // Point(2.4, 12.0) +``` +{% endtab %} +{% endtabs %} + +While string interpolators were originally used to create some form of a String, the use +of custom interpolators as above can allow for powerful syntactic shorthand, and the +community has already made swift use of this syntax for things like ANSI terminal color +expansion, executing SQL queries, magic `$"identifier"` representations, and many others. + +[java-format-docs]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html#detail +[value-class]: {% link _overviews/core/value-classes.md %} +[sip-11]: {% link _sips/sips/string-interpolation.md %} diff --git a/_overviews/scala3-book/taste-collections.md b/_overviews/scala3-book/taste-collections.md new file mode 100644 index 0000000000..773f823ce4 --- /dev/null +++ b/_overviews/scala3-book/taste-collections.md @@ -0,0 +1,151 @@ +--- +title: Collections +type: section +description: This page provides a high-level overview of the main features of the Scala 3 programming language. +languages: [ru, zh-cn] +num: 13 +previous-page: taste-objects +next-page: taste-contextual-abstractions +--- + + +The Scala library has a rich set of collection classes, and those classes have a rich set of methods. +Collections classes are available in both immutable and mutable forms. + +## Creating lists + +To give you a taste of how these work, here are some examples that use the `List` class, which is an immutable, linked-list class. +These examples show different ways to create a populated `List`: + +{% tabs collection_1 %} +{% tab 'Scala 2 and 3' for=collection_1 %} + +```scala +val a = List(1, 2, 3) // a: List[Int] = List(1, 2, 3) + +// Range methods +val b = (1 to 5).toList // b: List[Int] = List(1, 2, 3, 4, 5) +val c = (1 to 10 by 2).toList // c: List[Int] = List(1, 3, 5, 7, 9) +val e = (1 until 5).toList // e: List[Int] = List(1, 2, 3, 4) +val f = List.range(1, 5) // f: List[Int] = List(1, 2, 3, 4) +val g = List.range(1, 10, 3) // g: List[Int] = List(1, 4, 7) +``` + +{% endtab %} +{% endtabs %} + +## `List` methods + +Once you have a populated list, the following examples show some of the methods you can call on it. +Notice that these are all functional methods, meaning that they don’t mutate the collection they’re called on, but instead return a new collection with the updated elements. +The result that’s returned by each expression is shown in the comment on each line: + +{% tabs collection_2 %} +{% tab 'Scala 2 and 3' for=collection_2 %} + +```scala +// a sample list +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) + +a.drop(2) // List(30, 40, 10) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeWhile(_ < 30) // List(10, 20) + +// flatten +val a = List(List(1,2), List(3,4)) +a.flatten // List(1, 2, 3, 4) + +// map, flatMap +val nums = List("one", "two") +nums.map(_.toUpperCase) // List("ONE", "TWO") +nums.flatMap(_.toUpperCase) // List('O', 'N', 'E', 'T', 'W', 'O') +``` + +{% endtab %} +{% endtabs %} + +These examples show how the “foldLeft” and “reduceLeft” methods are used to sum the values in a sequence of integers: + +{% tabs collection_3 %} +{% tab 'Scala 2 and 3' for=collection_3 %} + +```scala +val firstTen = (1 to 10).toList // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + +firstTen.reduceLeft(_ + _) // 55 +firstTen.foldLeft(100)(_ + _) // 155 (100 is a “seed” value) +``` + +{% endtab %} +{% endtabs %} + +There are many more methods available to Scala collections classes, and they’re demonstrated in the [Collections chapter][collections], and in the [API Documentation][api]. + +## Tuples + +The Scala _tuple_ is a type that lets you easily put a collection of different types in the same container. +For example, given this `Person` case class: + +{% tabs collection_4 %} +{% tab 'Scala 2 and 3' for=collection_4 %} + +```scala +case class Person(name: String) +``` + +{% endtab %} +{% endtabs %} + +This is how you create a tuple that contains an `Int`, a `String`, and a custom `Person` value: + +{% tabs collection_5 %} +{% tab 'Scala 2 and 3' for=collection_5 %} + +```scala +val t = (11, "eleven", Person("Eleven")) +``` + +{% endtab %} +{% endtabs %} + +Once you have a tuple, you can access its values by binding them to variables, or access them by number: + +{% tabs collection_6 %} +{% tab 'Scala 2 and 3' for=collection_6 %} + +```scala +t(0) // 11 +t(1) // "eleven" +t(2) // Person("Eleven") +``` + +{% endtab %} +{% endtabs %} + +You can also use this _extractor_ approach to assign the tuple fields to variable names: + +{% tabs collection_7 %} +{% tab 'Scala 2 and 3' for=collection_7 %} + +```scala +val (num, str, person) = t + +// result: +// val num: Int = 11 +// val str: String = eleven +// val person: Person = Person(Eleven) +``` + +{% endtab %} +{% endtabs %} + +Tuples are nice for those times when you want to put a collection of heterogeneous types in a little collection-like structure. +See the [Reference documentation][reference] for more tuple details. + +[collections]: {% link _overviews/scala3-book/collections-intro.md %} +[api]: https://scala-lang.org/api/3.x/ +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_overviews/scala3-book/taste-contextual-abstractions.md b/_overviews/scala3-book/taste-contextual-abstractions.md new file mode 100644 index 0000000000..60d21d1643 --- /dev/null +++ b/_overviews/scala3-book/taste-contextual-abstractions.md @@ -0,0 +1,76 @@ +--- +title: Contextual Abstractions +type: section +description: This section provides an introduction to Contextual Abstractions in Scala 3. +languages: [ru, zh-cn] +num: 14 +previous-page: taste-collections +next-page: taste-toplevel-definitions +--- + + +{% comment %} +TODO: Now that this is a separate section, it needs a little more content. +{% endcomment %} + +Under certain circumstances, you can omit some parameters of method calls that are considered repetitive. + +Those parameters are called _Context Parameters_ because they are inferred by the compiler from the context surrounding the method call. + +For instance, consider a program that sorts a list of addresses by two criteria: the city name and then street name. + +{% tabs contextual_1 %} +{% tab 'Scala 2 and 3' for=contextual_1 %} + +```scala +val addresses: List[Address] = ... + +addresses.sortBy(address => (address.city, address.street)) +``` + +{% endtab %} +{% endtabs %} + +The `sortBy` method takes a function that returns, for every address, the value to compare it with the other addresses. +In this case, we pass a function that returns a pair containing the city name and the street name. + +Note that we only indicate _what_ to compare, but not _how_ to perform the comparison. +How does the sorting algorithm know how to compare pairs of `String`? + +Actually, the `sortBy` method takes a second parameter---a context parameter---that is inferred by the compiler. +It does not appear in the above example because it is supplied by the compiler. + +This second parameter implements the _how_ to compare. +It is convenient to omit it because we know `String`s are generally compared using the lexicographic order. + +However, it is also possible to pass it explicitly: + +{% tabs contextual_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=contextual_2 %} + +```scala +addresses.sortBy(address => (address.city, address.street))(Ordering.Tuple2(Ordering.String, Ordering.String)) +``` + +{% endtab %} +{% tab 'Scala 3' for=contextual_2 %} + +```scala +addresses.sortBy(address => (address.city, address.street))(using Ordering.Tuple2(Ordering.String, Ordering.String)) +``` + +in Scala 3 `using` in an argument list to `sortBy` signals passing the context parameter explicitly, avoiding ambiguity. + +{% endtab %} +{% endtabs %} + +In this case, the `Ordering.Tuple2(Ordering.String, Ordering.String)` instance is exactly the one that is otherwise inferred by the compiler. +In other words both examples produce the same program. + +_Contextual Abstractions_ are used to avoid repetition of code. +They help developers write pieces of code that are extensible and concise at the same time. + +For more details, see the [Contextual Abstractions chapter][contextual] of this book, and also the [Reference documentation][reference]. + +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_overviews/scala3-book/taste-control-structures.md b/_overviews/scala3-book/taste-control-structures.md new file mode 100644 index 0000000000..4b58abbf00 --- /dev/null +++ b/_overviews/scala3-book/taste-control-structures.md @@ -0,0 +1,541 @@ +--- +title: Control Structures +type: section +description: This section demonstrates Scala 3 control structures. +languages: [ru, zh-cn] +num: 8 +previous-page: taste-vars-data-types +next-page: taste-modeling +--- + + +Scala has the control structures you find in other programming languages, and also has powerful `for` expressions and `match` expressions: + +- `if`/`else` +- `for` loops and expressions +- `match` expressions +- `while` loops +- `try`/`catch` + +These structures are demonstrated in the following examples. + +## `if`/`else` + +Scala’s `if`/`else` control structure looks similar to other languages. + +{% tabs if-else class=tabs-scala-version %} +{% tab 'Scala 2' for=if-else %} + +```scala +if (x < 0) { + println("negative") +} else if (x == 0) { + println("zero") +} else { + println("positive") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=if-else %} + +```scala +if x < 0 then + println("negative") +else if x == 0 then + println("zero") +else + println("positive") +``` + +{% endtab %} +{% endtabs %} + +Note that this really is an _expression_---not a _statement_. +This means that it returns a value, so you can assign the result to a variable: + +{% tabs if-else-expression class=tabs-scala-version %} +{% tab 'Scala 2' for=if-else-expression %} + +```scala +val x = if (a < b) { a } else { b } +``` + +{% endtab %} + +{% tab 'Scala 3' for=if-else-expression %} + +```scala +val x = if a < b then a else b +``` + +{% endtab %} +{% endtabs %} + +As you’ll see throughout this book, _all_ Scala control structures can be used as expressions. + +> An expression returns a result, while a statement does not. +> Statements are typically used for their side-effects, such as using `println` to print to the console. + +## `for` loops and expressions + +The `for` keyword is used to create a `for` loop. +This example shows how to print every element in a `List`: + +{% tabs for-loop class=tabs-scala-version %} +{% tab 'Scala 2' for=for-loop %} + +```scala +val ints = List(1, 2, 3, 4, 5) + +for (i <- ints) println(i) +``` + +> The code `i <- ints` is referred to as a _generator_. In any generator `p <- e`, the expression `e` can generate zero or many bindings to the pattern `p`. +> The code that follows the closing parentheses of the generator is the _body_ of the loop. + +{% endtab %} + +{% tab 'Scala 3' for=for-loop %} + +```scala +val ints = List(1, 2, 3, 4, 5) + +for i <- ints do println(i) +``` + +> The code `i <- ints` is referred to as a _generator_, and the code that follows the `do` keyword is the _body_ of the loop. + +{% endtab %} +{% endtabs %} + +### Guards + +You can also use one or more `if` expressions inside a `for` loop. +These are referred to as _guards_. +This example prints all of the numbers in `ints` that are greater than `2`: + +{% tabs for-guards class=tabs-scala-version %} +{% tab 'Scala 2' for=for-guards %} + +```scala +for (i <- ints if i > 2) + println(i) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-guards %} + +```scala +for + i <- ints + if i > 2 +do + println(i) +``` + +{% endtab %} +{% endtabs %} + +You can use multiple generators and guards. +This loop iterates over the numbers `1` to `3`, and for each number it also iterates over the characters `a` to `c`. +However, it also has two guards, so the only time the print statement is called is when `i` has the value `2` and `j` is the character `b`: + +{% tabs for-guards-multi class=tabs-scala-version %} +{% tab 'Scala 2' for=for-guards-multi %} + +```scala +for { + i <- 1 to 3 + j <- 'a' to 'c' + if i == 2 + if j == 'b' +} { + println(s"i = $i, j = $j") // prints: "i = 2, j = b" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-guards-multi %} + +```scala +for + i <- 1 to 3 + j <- 'a' to 'c' + if i == 2 + if j == 'b' +do + println(s"i = $i, j = $j") // prints: "i = 2, j = b" +``` + +{% endtab %} +{% endtabs %} + +### `for` expressions + +The `for` keyword has even more power: When you use the `yield` keyword instead of `do`, you create `for` _expressions_ which are used to calculate and yield results. + +A few examples demonstrate this. +Using the same `ints` list as the previous example, this code creates a new list, where the value of each element in the new list is twice the value of the elements in the original list: + +{% tabs for-expression_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expression_1 %} + +```` +scala> val doubles = for (i <- ints) yield i * 2 +val doubles: List[Int] = List(2, 4, 6, 8, 10) +```` + +{% endtab %} + +{% tab 'Scala 3' for=for-expression_1 %} + +```` +scala> val doubles = for i <- ints yield i * 2 +val doubles: List[Int] = List(2, 4, 6, 8, 10) +```` + +{% endtab %} +{% endtabs %} + +Scala’s control structure syntax is flexible, and that `for` expression can be written in several other ways, depending on your preference: + +{% tabs for-expressioni_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_2 %} + +```scala +val doubles = for (i <- ints) yield i * 2 +val doubles = for (i <- ints) yield (i * 2) +val doubles = for { i <- ints } yield (i * 2) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_2 %} + +```scala +val doubles = for i <- ints yield i * 2 // style shown above +val doubles = for (i <- ints) yield i * 2 +val doubles = for (i <- ints) yield (i * 2) +val doubles = for { i <- ints } yield (i * 2) +``` + +{% endtab %} +{% endtabs %} + +This example shows how to capitalize the first character in each string in the list: + +{% tabs for-expressioni_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_3 %} + +```scala +val names = List("chris", "ed", "maurice") +val capNames = for (name <- names) yield name.capitalize +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_3 %} + +```scala +val names = List("chris", "ed", "maurice") +val capNames = for name <- names yield name.capitalize +``` + +{% endtab %} +{% endtabs %} + +Finally, this `for` expression iterates over a list of strings, and returns the length of each string, but only if that length is greater than `4`: + +{% tabs for-expressioni_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_4 %} + +```scala +val fruits = List("apple", "banana", "lime", "orange") + +val fruitLengths = + for (f <- fruits if f.length > 4) yield f.length + +// fruitLengths: List[Int] = List(5, 6, 6) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_4 %} + +```scala +val fruits = List("apple", "banana", "lime", "orange") + +val fruitLengths = for + f <- fruits + if f.length > 4 +yield + // you can use multiple lines + // of code here + f.length + +// fruitLengths: List[Int] = List(5, 6, 6) +``` + +{% endtab %} +{% endtabs %} + +`for` loops and expressions are covered in more detail in the [Control Structures sections][control] of this book, and in the [Reference documentation]({{ site.scala3ref }}/other-new-features/control-syntax.html). + +## `match` expressions + +Scala has a `match` expression, which in its most basic use is like a Java `switch` statement: + +{% tabs match class=tabs-scala-version %} +{% tab 'Scala 2' for=match %} + +```scala +val i = 1 + +// later in the code ... +i match { + case 1 => println("one") + case 2 => println("two") + case _ => println("other") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match %} + +```scala +val i = 1 + +// later in the code ... +i match + case 1 => println("one") + case 2 => println("two") + case _ => println("other") +``` + +{% endtab %} +{% endtabs %} + +However, `match` really is an expression, meaning that it returns a result based on the pattern match, which you can bind to a variable: + +{% tabs match-expression_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_1 %} + +```scala +val result = i match { + case 1 => "one" + case 2 => "two" + case _ => "other" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match-expression_1 %} + +```scala +val result = i match + case 1 => "one" + case 2 => "two" + case _ => "other" +``` + +{% endtab %} +{% endtabs %} + +`match` isn’t limited to working with just integer values, it can be used with any data type: + +{% tabs match-expression_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_2 %} + +```scala +val p = Person("Fred") + +// later in the code +p match { + case Person(name) if name == "Fred" => + println(s"$name says, Yubba dubba doo") + + case Person(name) if name == "Bam Bam" => + println(s"$name says, Bam bam!") + + case _ => println("Watch the Flintstones!") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match-expression_2 %} + +```scala +val p = Person("Fred") + +// later in the code +p match + case Person(name) if name == "Fred" => + println(s"$name says, Yubba dubba doo") + + case Person(name) if name == "Bam Bam" => + println(s"$name says, Bam bam!") + + case _ => println("Watch the Flintstones!") +``` + +{% endtab %} +{% endtabs %} + +In fact, a `match` expression can be used to test a variable against many different types of patterns. +This example shows (a) how to use a `match` expression as the body of a method, and (b) how to match all the different types shown: + +{% tabs match-expression_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_3 %} + +```scala +// getClassAsString is a method that takes a single argument of any type. +def getClassAsString(x: Any): String = x match { + case s: String => s"'$s' is a String" + case i: Int => "Int" + case d: Double => "Double" + case l: List[_] => "List" + case _ => "Unknown" +} + +// examples +getClassAsString(1) // Int +getClassAsString("hello") // 'hello' is a String +getClassAsString(List(1, 2, 3)) // List +``` + +Because the method `getClassAsString` takes a parameter value of type `Any`, it can be decomposed by any kind of +pattern. + +{% endtab %} +{% tab 'Scala 3' for=match-expression_3 %} + +```scala +// getClassAsString is a method that takes a single argument of any type. +def getClassAsString(x: Matchable): String = x match + case s: String => s"'$s' is a String" + case i: Int => "Int" + case d: Double => "Double" + case l: List[?] => "List" + case _ => "Unknown" + +// examples +getClassAsString(1) // Int +getClassAsString("hello") // 'hello' is a String +getClassAsString(List(1, 2, 3)) // List +``` + +The method `getClassAsString` takes as a parameter a value of type [Matchable]({{ site.scala3ref }}/other-new-features/matchable.html), which can be +any type supporting pattern matching (some types don’t support pattern matching because this could +break encapsulation). + +{% endtab %} +{% endtabs %} + +There’s _much_ more to pattern matching in Scala. +Patterns can be nested, results of patterns can be bound, and pattern matching can even be user-defined. +See the pattern matching examples in the [Control Structures chapter][control] for more details. + +## `try`/`catch`/`finally` + +Scala’s `try`/`catch`/`finally` control structure lets you catch exceptions. +It’s similar to Java, but its syntax is consistent with `match` expressions: + +{% tabs try class=tabs-scala-version %} +{% tab 'Scala 2' for=try %} + +```scala +try { + writeTextToFile(text) +} catch { + case ioe: IOException => println("Got an IOException.") + case nfe: NumberFormatException => println("Got a NumberFormatException.") +} finally { + println("Clean up your resources here.") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=try %} + +```scala +try + writeTextToFile(text) +catch + case ioe: IOException => println("Got an IOException.") + case nfe: NumberFormatException => println("Got a NumberFormatException.") +finally + println("Clean up your resources here.") +``` + +{% endtab %} +{% endtabs %} + +## `while` loops + +Scala also has a `while` loop construct. +Its one-line syntax looks like this: + +{% tabs while_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=while_1 %} + +```scala +while (x >= 0) { x = f(x) } +``` + +{% endtab %} + +{% tab 'Scala 3' for=while_1 %} + +```scala +while x >= 0 do x = f(x) +``` +Scala 3 still supports the Scala 2 syntax for the sake of compatibility. + +{% endtab %} +{% endtabs %} + +The `while` loop multiline syntax looks like this: + +{% tabs while_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=while_2 %} + +```scala +var x = 1 + +while (x < 3) { + println(x) + x += 1 +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=while_2 %} + +```scala +var x = 1 + +while + x < 3 +do + println(x) + x += 1 +``` + +{% endtab %} +{% endtabs %} + +## Custom control structures + +Thanks to features like by-name parameters, infix notation, fluent interfaces, optional parentheses, extension methods, and higher-order functions, you can also create your own code that works just like a control structure. +You’ll learn more about this in the [Control Structures][control] section. + +[control]: {% link _overviews/scala3-book/control-structures.md %} diff --git a/_overviews/scala3-book/taste-functions.md b/_overviews/scala3-book/taste-functions.md new file mode 100644 index 0000000000..e73024bca0 --- /dev/null +++ b/_overviews/scala3-book/taste-functions.md @@ -0,0 +1,78 @@ +--- +title: First-Class Functions +type: section +description: This page provides an introduction to functions in Scala 3. +languages: [ru, zh-cn] +num: 11 +previous-page: taste-methods +next-page: taste-objects +--- + + +Scala has most features you’d expect in a functional programming language, including: + +- Lambdas (anonymous functions) +- Higher-order functions (HOFs) +- Immutable collections in the standard library + +Lambdas, also known as _anonymous functions_, are a big part of keeping your code concise but readable. + +The `map` method of the `List` class is a typical example of a higher-order function---a function that takes a function as parameter. + +These two examples are equivalent, and show how to multiply each number in a list by `2` by passing a lambda into the `map` method: + + +{% tabs function_1 %} +{% tab 'Scala 2 and 3' for=function_1 %} +```scala +val a = List(1, 2, 3).map(i => i * 2) // List(2,4,6) +val b = List(1, 2, 3).map(_ * 2) // List(2,4,6) +``` +{% endtab %} +{% endtabs %} + +Those examples are also equivalent to the following code, which uses a `double` method instead of a lambda: + + +{% tabs function_2 %} +{% tab 'Scala 2 and 3' for=function_2 %} +```scala +def double(i: Int): Int = i * 2 + +val a = List(1, 2, 3).map(i => double(i)) // List(2,4,6) +val b = List(1, 2, 3).map(double) // List(2,4,6) +``` +{% endtab %} +{% endtabs %} + +> If you haven’t seen the `map` method before, it applies a given function to every element in a list, yielding a new list that contains the resulting values. + +Passing lambdas to higher-order functions on collections classes (like `List`) is a part of the Scala experience, something you’ll do every day. + +## Immutable collections + +When you work with immutable collections like `List`, `Vector`, and the immutable `Map` and `Set` classes, it’s important to know that these functions don’t mutate the collection they’re called on; instead, they return a new collection with the updated data. +As a result, it’s also common to chain them together in a “fluent” style to solve problems. + +For instance, this example shows how to filter a collection twice, and then multiply each element in the remaining collection: + + +{% tabs function_3 %} +{% tab 'Scala 2 and 3' for=function_3 %} +```scala +// a sample list +val nums = (1 to 10).toList // List(1,2,3,4,5,6,7,8,9,10) + +// methods can be chained together as needed +val x = nums.filter(_ > 3) + .filter(_ < 7) + .map(_ * 10) + +// result: x == List(40, 50, 60) +``` +{% endtab %} +{% endtabs %} + +In addition to higher-order functions being used throughout the standard library, you can also [create your own][higher-order]. + +[higher-order]: {% link _overviews/scala3-book/fun-hofs.md %} diff --git a/_overviews/scala3-book/taste-hello-world.md b/_overviews/scala3-book/taste-hello-world.md new file mode 100644 index 0000000000..52fc532e5e --- /dev/null +++ b/_overviews/scala3-book/taste-hello-world.md @@ -0,0 +1,165 @@ +--- +title: Hello, World! +type: section +description: This section demonstrates a Scala 3 'Hello, World!' example. +languages: [ru, zh-cn] +num: 5 +previous-page: taste-intro +next-page: taste-repl +--- + +> **Hint**: in the following examples try picking your preferred Scala version. + +## Your First Scala Program + + +A Scala “Hello, World!” example goes as follows. +First, put this code in a file named _hello.scala_: + + + +{% tabs hello-world-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-demo %} +```scala +object hello { + def main(args: Array[String]) = { + println("Hello, World!") + } +} +``` +> In this code, we defined a method named `main`, inside a Scala `object` named `hello`. +> An `object` in Scala is similar to a `class`, but defines a singleton instance that you can pass around. +> `main` takes an input parameter named `args` that must be typed as `Array[String]`, (ignore `args` for now). + +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} +```scala +@main def hello() = println("Hello, World!") +``` +> In this code, `hello` is a method. +> It’s defined with `def`, and declared to be a “main” method with the `@main` annotation. +> It prints the `"Hello, World!"` string to standard output (STDOUT) using the `println` method. + +{% endtab %} + +{% endtabs %} + + +Next, compile and run the code with `scala`: + +```bash +$ scala run hello.scala +``` + +The command should produce an output similar to: +``` +Compiling project (Scala {{site.scala-3-version}}, JVM (20)) +Compiled project (Scala {{site.scala-3-version}}, JVM (20)) +Hello, World! +``` + +Assuming that worked, congratulations, you just compiled and ran your first Scala application. + +> More information about sbt and other tools that make Scala development easier can be found in the [Scala Tools][scala_tools] chapter. +> The Scala CLI documentation can be found [here](https://scala-cli.virtuslab.org/). + +## Ask For User Input + +In our next example let's ask for the user's name before we greet them! + +There are several ways to read input from a command-line, but a simple way is to use the +`readLine` method in the _scala.io.StdIn_ object. To use it, you need to first import it, like this: + +{% tabs import-readline %} +{% tab 'Scala 2 and 3' for=import-readline %} +```scala +import scala.io.StdIn.readLine +``` +{% endtab %} +{% endtabs %} + +To demonstrate how this works, let’s create a little example. Put this source code in a file named _helloInteractive.scala_: + + +{% tabs hello-world-interactive class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-interactive %} +```scala +import scala.io.StdIn.readLine + +object helloInteractive { + + def main(args: Array[String]) = { + println("Please enter your name:") + val name = readLine() + + println("Hello, " + name + "!") + } + +} +``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-interactive %} +```scala +import scala.io.StdIn.readLine + +@main def helloInteractive() = + println("Please enter your name:") + val name = readLine() + + println("Hello, " + name + "!") +``` +{% endtab %} + +{% endtabs %} + + +In this code we save the result of `readLine` to a variable called `name`, we then +use the `+` operator on strings to join `"Hello, "` with `name` and `"!"`, making one single string value. + +> You can learn more about using `val` by reading [Variables and Data Types](/scala3/book/taste-vars-data-types.html). + +Then run the code with `scala`. This time the program will pause after asking for your name, +and wait until you type a name and press return on the keyboard, looking like this: + +```bash +$ scala run helloInteractive.scala +Compiling project (Scala {{site.scala-3-version}}, JVM (20)) +Compiled project (Scala {{site.scala-3-version}}, JVM (20)) +Please enter your name: +▌ +``` + +When you enter your name at the prompt, the final interaction should look like this: + +```bash +$ scala run helloInteractive.scala +Compiling project (Scala {{site.scala-3-version}}, JVM (20)) +Compiled project (Scala {{site.scala-3-version}}, JVM (20)) +Please enter your name: +Alvin Alexander +Hello, Alvin Alexander! +``` + +### A Note about Imports + +As you saw in this application, sometimes certain methods, or other kinds of definitions that we'll see later, +are not available unless you use an `import` clause like so: + +{% tabs import-readline-2 %} +{% tab 'Scala 2 and 3' for=import-readline-2 %} +```scala +import scala.io.StdIn.readLine +``` +{% endtab %} +{% endtabs %} + +Imports help you write code in a few ways: + - you can put code in multiple files, to help avoid clutter, and to help navigate large projects. + - you can use a code library, perhaps written by someone else, that has useful functionality + - you can know where a certain definition comes from (especially if it was not written in the current file). + +[scala_tools]: {% link _overviews/scala3-book/scala-tools.md %} diff --git a/_overviews/scala3-book/taste-intro.md b/_overviews/scala3-book/taste-intro.md new file mode 100644 index 0000000000..9d93b317cf --- /dev/null +++ b/_overviews/scala3-book/taste-intro.md @@ -0,0 +1,62 @@ +--- +title: A Taste of Scala +type: chapter +description: This chapter provides a high-level overview of the main features of the Scala 3 programming language. +languages: [ru, zh-cn] +num: 4 +previous-page: why-scala-3 +next-page: taste-hello-world +--- + + +This chapter provides a whirlwind tour of the main features of the Scala 3 programming language. +After this initial tour, the rest of the book provides more details on these features, and the [Reference documentation][reference] provides _many_ more details. + +## Setting Up Scala + +Throughout this chapter, and the rest of the book, we encourage you to try out the examples by either copying +them or typing them out manually. The tools necessary to follow along with the examples on your own computer +can be installed by following our [getting started guide][get-started]. + +> Alternatively you can run the examples in a web browser with [Scastie](https://scastie.scala-lang.org), a +> fully online editor and code-runner for Scala. + +## Comments + +One good thing to know up front is that comments in Scala are just like comments in Java (and many other languages): + +{% tabs comments %} +{% tab 'Scala 2 and 3' for=comments %} +```scala +// a single line comment + +/* + * a multiline comment + */ + +/** + * also a multiline comment + */ +``` +{% endtab %} +{% endtabs %} + +## IDEs + +The two main IDEs (integrated development environments) for Scala are: + +- [IntelliJ IDEA](/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html) +- [Visual Studio Code](https://scalameta.org/metals/docs/editors/vscode/) + +## Naming conventions + +Another good thing to know is that Scala naming conventions follow the same “camel case” style as Java: + +- Class names: `Person`, `StoreEmployee` +- Variable names: `name`, `firstName` +- Method names: `convertToInt`, `toUpper` + +More on conventions used while writing Scala code can be found in the [Style Guide](/style/index.html). + +[reference]: {{ site.scala3ref }}/overview.html +[get-started]: {% link _overviews/getting-started/install-scala.md %} diff --git a/_overviews/scala3-book/taste-methods.md b/_overviews/scala3-book/taste-methods.md new file mode 100644 index 0000000000..6c54818805 --- /dev/null +++ b/_overviews/scala3-book/taste-methods.md @@ -0,0 +1,159 @@ +--- +title: Methods +type: section +description: This section provides an introduction to defining and using methods in Scala 3. +languages: [ru, zh-cn] +num: 10 +previous-page: taste-modeling +next-page: taste-functions +--- + + +## Scala methods + +Scala classes, case classes, traits, enums, and objects can all contain methods. +The syntax of a simple method looks like this: + +{% tabs method_1 %} +{% tab 'Scala 2 and 3' for=method_1 %} +```scala +def methodName(param1: Type1, param2: Type2): ReturnType = + // the method body + // goes here +``` +{% endtab %} +{% endtabs %} + +Here are a few examples: + +{% tabs method_2 %} +{% tab 'Scala 2 and 3' for=method_2 %} +```scala +def sum(a: Int, b: Int): Int = a + b +def concatenate(s1: String, s2: String): String = s1 + s2 +``` +{% endtab %} +{% endtabs %} + +You don’t have to declare a method’s return type, so you can write those methods like this, if you prefer: + +{% tabs method_3 %} +{% tab 'Scala 2 and 3' for=method_3 %} +```scala +def sum(a: Int, b: Int) = a + b +def concatenate(s1: String, s2: String) = s1 + s2 +``` +{% endtab %} +{% endtabs %} + +This is how you call those methods: + +{% tabs method_4 %} +{% tab 'Scala 2 and 3' for=method_4 %} +```scala +val x = sum(1, 2) +val y = concatenate("foo", "bar") +``` +{% endtab %} +{% endtabs %} + +Here’s an example of a multiline method: + +{% tabs method_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_5 %} +```scala +def getStackTraceAsString(t: Throwable): String = { + val sw = new StringWriter + t.printStackTrace(new PrintWriter(sw)) + sw.toString +} +``` +{% endtab %} + +{% tab 'Scala 3' for=method_5 %} +```scala +def getStackTraceAsString(t: Throwable): String = + val sw = new StringWriter + t.printStackTrace(new PrintWriter(sw)) + sw.toString +``` +{% endtab %} +{% endtabs %} + +Method parameters can also have default values. +In this example, the `timeout` parameter has a default value of `5000`: + +{% tabs method_6 %} +{% tab 'Scala 2 and 3' for=method_6 %} +```scala +def makeConnection(url: String, timeout: Int = 5000): Unit = + println(s"url=$url, timeout=$timeout") +``` +{% endtab %} +{% endtabs %} + +Because a default `timeout` value is supplied in the method declaration, the method can be called in these two ways: + +{% tabs method_7 %} +{% tab 'Scala 2 and 3' for=method_7 %} +```scala +makeConnection("https://localhost") // url=http://localhost, timeout=5000 +makeConnection("https://localhost", 2500) // url=http://localhost, timeout=2500 +``` +{% endtab %} +{% endtabs %} + +Scala also supports the use of _named parameters_ when calling a method, so you can also call that method like this, if you prefer: + +{% tabs method_8 %} +{% tab 'Scala 2 and 3' for=method_8 %} +```scala +makeConnection( + url = "https://localhost", + timeout = 2500 +) +``` +{% endtab %} +{% endtabs %} + +Named parameters are particularly useful when multiple method parameters have the same type. +At a glance, with this method you may wonder which parameters are set to `true` or `false`: + +{% tabs method_9 %} +{% tab 'Scala 2 and 3' for=method_9 %} + +```scala +engage(true, true, true, false) +``` + +{% endtab %} +{% endtabs %} + +The `extension` keyword declares that you’re about to define one or more extension methods on the parameter that’s put in parentheses. +As shown with this example, the parameter `s` of type `String` can then be used in the body of your extension methods. + +This next example shows how to add a `makeInt` method to the `String` class. +Here, `makeInt` takes a parameter named `radix`. +The code doesn’t account for possible string-to-integer conversion errors, but skipping that detail, the examples show how it works: + +{% tabs extension %} +{% tab 'Scala 3 Only' %} + +```scala +extension (s: String) + def makeInt(radix: Int): Int = Integer.parseInt(s, radix) + +"1".makeInt(2) // Int = 1 +"10".makeInt(2) // Int = 2 +"100".makeInt(2) // Int = 4 +``` + +{% endtab %} +{% endtabs %} + +## See also + +Scala Methods can be much more powerful: they can take type parameters and context parameters. +They are covered in detail in the [Domain Modeling][data-1] section. + +[data-1]: {% link _overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_overviews/scala3-book/taste-modeling.md b/_overviews/scala3-book/taste-modeling.md new file mode 100644 index 0000000000..3e391d745a --- /dev/null +++ b/_overviews/scala3-book/taste-modeling.md @@ -0,0 +1,422 @@ +--- +title: Domain Modeling +type: section +description: This section provides an introduction to data modeling in Scala 3. +languages: [ru, zh-cn] +num: 9 +previous-page: taste-control-structures +next-page: taste-methods +--- + + +{% comment %} +NOTE: I kept the OOP section first, assuming that most readers will be coming from an OOP background. +{% endcomment %} + +Scala supports both functional programming (FP) and object-oriented programming (OOP), as well as a fusion of the two paradigms. +This section provides a quick overview of data modeling in OOP and FP. + +## OOP Domain Modeling + +When writing code in an OOP style, your two main tools for data encapsulation are _traits_ and _classes_. + +{% comment %} +NOTE: Julien had a comment, “in OOP we don’t really model data. +It’s more about modeling operations, imho.” + +How to resolve? Is there a good DDD term to use here? +{% endcomment %} + +### Traits + +Scala traits can be used as simple interfaces, but they can also contain abstract and concrete methods and fields, and they can have parameters, just like classes. +They provide a great way for you to organize behaviors into small, modular units. +Later, when you want to create concrete implementations of attributes and behaviors, classes and objects can extend traits, mixing in as many traits as needed to achieve the desired behavior. + +As an example of how to use traits as interfaces, here are three traits that define well-organized and modular behaviors for animals like dogs and cats: + +{% tabs traits class=tabs-scala-version %} +{% tab 'Scala 2' for=traits %} + +```scala +trait Speaker { + def speak(): String // has no body, so it’s abstract +} + +trait TailWagger { + def startTail(): Unit = println("tail is wagging") + def stopTail(): Unit = println("tail is stopped") +} + +trait Runner { + def startRunning(): Unit = println("I’m running") + def stopRunning(): Unit = println("Stopped running") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits %} + +```scala +trait Speaker: + def speak(): String // has no body, so it’s abstract + +trait TailWagger: + def startTail(): Unit = println("tail is wagging") + def stopTail(): Unit = println("tail is stopped") + +trait Runner: + def startRunning(): Unit = println("I’m running") + def stopRunning(): Unit = println("Stopped running") +``` + +{% endtab %} +{% endtabs %} + +Given those traits, here’s a `Dog` class that extends all of those traits while providing a behavior for the abstract `speak` method: + +{% tabs traits-class class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-class %} + +```scala +class Dog(name: String) extends Speaker with TailWagger with Runner { + def speak(): String = "Woof!" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-class %} + +```scala +class Dog(name: String) extends Speaker, TailWagger, Runner: + def speak(): String = "Woof!" +``` + +{% endtab %} +{% endtabs %} + +Notice how the class extends the traits with the `extends` keyword. + +Similarly, here’s a `Cat` class that implements those same traits while also overriding two of the concrete methods it inherits: + +{% tabs traits-override class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-override %} + +```scala +class Cat(name: String) extends Speaker with TailWagger with Runner { + def speak(): String = "Meow" + override def startRunning(): Unit = println("Yeah ... I don’t run") + override def stopRunning(): Unit = println("No need to stop") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-override %} + +```scala +class Cat(name: String) extends Speaker, TailWagger, Runner: + def speak(): String = "Meow" + override def startRunning(): Unit = println("Yeah ... I don’t run") + override def stopRunning(): Unit = println("No need to stop") +``` + +{% endtab %} +{% endtabs %} + +These examples show how those classes are used: + +{% tabs traits-use class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-use %} + +```scala +val d = new Dog("Rover") +println(d.speak()) // prints "Woof!" + +val c = new Cat("Morris") +println(c.speak()) // "Meow" +c.startRunning() // "Yeah ... I don’t run" +c.stopRunning() // "No need to stop" +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-use %} + +```scala +val d = Dog("Rover") +println(d.speak()) // prints "Woof!" + +val c = Cat("Morris") +println(c.speak()) // "Meow" +c.startRunning() // "Yeah ... I don’t run" +c.stopRunning() // "No need to stop" +``` + +{% endtab %} +{% endtabs %} + +If that code makes sense---great, you’re comfortable with traits as interfaces. +If not, don’t worry, they’re explained in more detail in the [Domain Modeling][data-1] chapter. + +### Classes + +Scala _classes_ are used in OOP-style programming. +Here’s an example of a class that models a “person.” In OOP, fields are typically mutable, so `firstName` and `lastName` are both declared as `var` parameters: + +{% tabs class_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=class_1 %} + +```scala +class Person(var firstName: String, var lastName: String) { + def printFullName() = println(s"$firstName $lastName") +} + +val p = new Person("John", "Stephens") +println(p.firstName) // "John" +p.lastName = "Legend" +p.printFullName() // "John Legend" +``` + +{% endtab %} + +{% tab 'Scala 3' for=class_1 %} + +```scala +class Person(var firstName: String, var lastName: String): + def printFullName() = println(s"$firstName $lastName") + +val p = Person("John", "Stephens") +println(p.firstName) // "John" +p.lastName = "Legend" +p.printFullName() // "John Legend" +``` + +{% endtab %} +{% endtabs %} + +Notice that the class declaration creates a constructor: + +{% tabs class_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=class_2 %} + +```scala +// this code uses that constructor +val p = new Person("John", "Stephens") +``` + +{% endtab %} + +{% tab 'Scala 3' for=class_2 %} + +```scala +// this code uses that constructor +val p = Person("John", "Stephens") +``` + +{% endtab %} +{% endtabs %} + +Constructors and other class-related topics are covered in the [Domain Modeling][data-1] chapter. + +## FP Domain Modeling + +{% comment %} +NOTE: Julien had a note about expecting to see sealed traits here. +I didn’t include that because I didn’t know if enums are intended +to replace the Scala2 “sealed trait + case class” pattern. How to resolve? +{% endcomment %} + +When writing code in an FP style, you’ll use these concepts: + +- Algebraic Data Types to define the data +- Traits for functionality on the data. + +### Enumerations and Sum Types + +Sum types are one way to model algebraic data types (ADTs) in Scala. + +They are used when data can be represented with different choices. + +For instance, a pizza has three main attributes: + +- Crust size +- Crust type +- Toppings + +These are concisely modeled with enumerations, which are sum types that only contain singleton values: + +{% tabs enum_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_1 %} + +In Scala 2 `sealed` classes and `case object` are combined to define an enumeration: + +```scala +sealed abstract class CrustSize +object CrustSize { + case object Small extends CrustSize + case object Medium extends CrustSize + case object Large extends CrustSize +} + +sealed abstract class CrustType +object CrustType { + case object Thin extends CrustType + case object Thick extends CrustType + case object Regular extends CrustType +} + +sealed abstract class Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping +} +``` + +{% endtab %} +{% tab 'Scala 3' for=enum_1 %} + +Scala 3 offers the `enum` construct for defining enumerations: + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +Once you have an enumeration you can import its members as ordinary values: + +{% tabs enum_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_2 %} + +```scala +import CrustSize._ +val currentCrustSize = Small + +// enums in a `match` expression +currentCrustSize match { + case Small => println("Small crust size") + case Medium => println("Medium crust size") + case Large => println("Large crust size") +} + +// enums in an `if` statement +if (currentCrustSize == Small) println("Small crust size") +``` + +{% endtab %} +{% tab 'Scala 3' for=enum_2 %} + +```scala +import CrustSize.* +val currentCrustSize = Small + +// enums in a `match` expression +currentCrustSize match + case Small => println("Small crust size") + case Medium => println("Medium crust size") + case Large => println("Large crust size") + +// enums in an `if` statement +if currentCrustSize == Small then println("Small crust size") +``` + +{% endtab %} +{% endtabs %} + +Here’s another example of how to create a sum type with Scala, this would not be called an enumeration because the `Succ` case has parameters: + +{% tabs enum_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_3 %} + +```scala +sealed abstract class Nat +object Nat { + case object Zero extends Nat + case class Succ(pred: Nat) extends Nat +} +``` + +Sum Types are covered in detail in the [Domain Modeling]({% link _overviews/scala3-book/domain-modeling-tools.md %}) section of this book. + +{% endtab %} +{% tab 'Scala 3' for=enum_3 %} + +```scala +enum Nat: + case Zero + case Succ(pred: Nat) +``` + +Enums are covered in detail in the [Domain Modeling]({% link _overviews/scala3-book/domain-modeling-tools.md %}) section of this book, and in the [Reference documentation]({{ site.scala3ref }}/enums/enums.html). + +{% endtab %} +{% endtabs %} + +### Product Types + +A product type is an algebraic data type (ADT) that only has one shape, for example a singleton object, represented in Scala by a `case` object; or an immutable structure with accessible fields, represented by a `case` class. + +A `case` class has all of the functionality of a `class`, and also has additional features baked in that make them useful for functional programming. +When the compiler sees the `case` keyword in front of a `class` it has these effects and benefits: + +- Case class constructor parameters are public `val` fields by default, so the fields are immutable, and accessor methods are generated for each parameter. +- An `unapply` method is generated, which lets you use case classes in more ways in `match` expressions. +- A `copy` method is generated in the class. + This provides a way to create updated copies of the object without changing the original object. +- `equals` and `hashCode` methods are generated to implement structural equality. +- A default `toString` method is generated, which is helpful for debugging. + +{% comment %} +NOTE: Julien had a comment about how he decides when to use case classes vs classes. Add something here? +{% endcomment %} + +You _can_ manually add all of those methods to a class yourself, but since those features are so commonly used in functional programming, using a `case` class is much more convenient. + +This code demonstrates several `case` class features: + +{% tabs case-class %} +{% tab 'Scala 2 and 3' for=case-class %} + +```scala +// define a case class +case class Person( + name: String, + vocation: String +) + +// create an instance of the case class +val p = Person("Reginald Kenneth Dwight", "Singer") + +// a good default toString method +p // : Person = Person(Reginald Kenneth Dwight,Singer) + +// can access its fields, which are immutable +p.name // "Reginald Kenneth Dwight" +p.name = "Joe" // error: can’t reassign a val field + +// when you need to make a change, use the `copy` method +// to “update as you copy” +val p2 = p.copy(name = "Elton John") +p2 // : Person = Person(Elton John,Singer) +``` + +{% endtab %} +{% endtabs %} + +See the [Domain Modeling][data-1] sections for many more details on `case` classes. + +[data-1]: {% link _overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_overviews/scala3-book/taste-objects.md b/_overviews/scala3-book/taste-objects.md new file mode 100644 index 0000000000..479182bfa2 --- /dev/null +++ b/_overviews/scala3-book/taste-objects.md @@ -0,0 +1,155 @@ +--- +title: Singleton Objects +type: section +description: This section provides an introduction to the use of singleton objects in Scala 3. +languages: [ru, zh-cn] +num: 12 +previous-page: taste-functions +next-page: taste-collections +--- + + +In Scala, the `object` keyword creates a Singleton object. +Put another way, an object defines a class that has exactly one instance. + +Objects have several uses: + +- They are used to create collections of utility methods. +- A _companion object_ is an object that has the same name as the class it shares a file with. + In this situation, that class is also called a _companion class_. +- They’re used to implement traits to create _modules_. + +## “Utility” methods + +Because an `object` is a Singleton, its methods can be accessed like `static` methods in a Java class. +For example, this `StringUtils` object contains a small collection of string-related methods: + + +{% tabs object_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_1 %} +```scala +object StringUtils { + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty + def leftTrim(s: String): String = s.replaceAll("^\\s+", "") + def rightTrim(s: String): String = s.replaceAll("\\s+$", "") +} +``` +{% endtab %} + +{% tab 'Scala 3' for=object_1 %} +```scala +object StringUtils: + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty + def leftTrim(s: String): String = s.replaceAll("^\\s+", "") + def rightTrim(s: String): String = s.replaceAll("\\s+$", "") +``` +{% endtab %} +{% endtabs %} + +Because `StringUtils` is a singleton, its methods can be called directly on the object: + +{% tabs object_2 %} +{% tab 'Scala 2 and 3' for=object_2 %} +```scala +val x = StringUtils.isNullOrEmpty("") // true +val x = StringUtils.isNullOrEmpty("a") // false +``` +{% endtab %} +{% endtabs %} + +## Companion objects + +A companion class or object can access the private members of its companion. +Use a companion object for methods and values which aren’t specific to instances of the companion class. + +This example demonstrates how the `area` method in the companion class can access the private `calculateArea` method in its companion object: + +{% tabs object_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_3 %} +```scala +import scala.math._ + +class Circle(radius: Double) { + import Circle._ + def area: Double = calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = + Pi * pow(radius, 2.0) +} + +val circle1 = new Circle(5.0) +circle1.area // Double = 78.53981633974483 +``` +{% endtab %} + +{% tab 'Scala 3' for=object_3 %} +```scala +import scala.math.* + +class Circle(radius: Double): + import Circle.* + def area: Double = calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = + Pi * pow(radius, 2.0) + +val circle1 = Circle(5.0) +circle1.area // Double = 78.53981633974483 +``` +{% endtab %} +{% endtabs %} + +## Creating modules from traits + +Objects can also be used to implement traits to create modules. +This technique takes two traits and combines them to create a concrete `object`: + +{% tabs object_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_4 %} +```scala +trait AddService { + def add(a: Int, b: Int) = a + b +} + +trait MultiplyService { + def multiply(a: Int, b: Int) = a * b +} + +// implement those traits as a concrete object +object MathService extends AddService with MultiplyService + +// use the object +import MathService._ +println(add(1,1)) // 2 +println(multiply(2,2)) // 4 +``` +{% endtab %} + +{% tab 'Scala 3' for=object_4 %} +```scala +trait AddService: + def add(a: Int, b: Int) = a + b + +trait MultiplyService: + def multiply(a: Int, b: Int) = a * b + +// implement those traits as a concrete object +object MathService extends AddService, MultiplyService + +// use the object +import MathService.* +println(add(1,1)) // 2 +println(multiply(2,2)) // 4 +``` +{% endtab %} +{% endtabs %} + +{% comment %} +NOTE: I don’t know if this is worth keeping, but I’m leaving it here as a comment for now. + +> You may read that objects are used to _reify_ traits into modules. +> _Reify_ means, “to take an abstract concept and turn it into something concrete.” This is what happens in these examples, but “implement” is a more familiar word for most people than “reify.” +{% endcomment %} diff --git a/_overviews/scala3-book/taste-repl.md b/_overviews/scala3-book/taste-repl.md new file mode 100644 index 0000000000..784eaca131 --- /dev/null +++ b/_overviews/scala3-book/taste-repl.md @@ -0,0 +1,88 @@ +--- +title: The REPL +type: section +description: This section provides an introduction to the Scala REPL. +languages: [ru, zh-cn] +num: 6 +previous-page: taste-hello-world +next-page: taste-vars-data-types +--- + + +The Scala REPL (“Read-Evaluate-Print-Loop”) is a command-line interpreter that you use as a “playground” area to test your Scala code. +You start a REPL session by running the `scala` or `scala3` command depending on your installation at your operating system command line, where you’ll see a “welcome” prompt like this: + + +{% tabs command-line class=tabs-scala-version %} + +{% tab 'Scala 2' for=command-line %} +```bash +$ scala +Welcome to Scala {{site.scala-version}} (OpenJDK 64-Bit Server VM, Java 1.8.0_342). +Type in expressions for evaluation. Or try :help. + +scala> _ +``` +{% endtab %} + +{% tab 'Scala 3' for=command-line %} +```bash +$ scala +Welcome to Scala {{site.scala-3-version}} (1.8.0_322, Java OpenJDK 64-Bit Server VM). +Type in expressions for evaluation. Or try :help. + +scala> _ +``` +{% endtab %} + +{% endtabs %} + +The REPL is a command-line interpreter, so it sits there waiting for you to type something. +Now you can type Scala expressions to see how they work: + +{% tabs expression-one %} +{% tab 'Scala 2 and 3' for=expression-one %} +```` +scala> 1 + 1 +val res0: Int = 2 + +scala> 2 + 2 +val res1: Int = 4 +```` +{% endtab %} +{% endtabs %} + +As shown in the output, if you don’t assign a variable to the result of an expression, the REPL creates variables named `res0`, `res1`, etc., for you. +You can use these variable names in subsequent expressions: + +{% tabs expression-two %} +{% tab 'Scala 2 and 3' for=expression-two %} +```` +scala> val x = res0 * 10 +val x: Int = 20 +```` +{% endtab %} +{% endtabs %} + +Notice that the REPL output also shows the result of your expressions. + +You can run all sorts of experiments in the REPL. +This example shows how to create and then call a `sum` method: + +{% tabs expression-three %} +{% tab 'Scala 2 and 3' for=expression-three %} +```` +scala> def sum(a: Int, b: Int): Int = a + b +def sum(a: Int, b: Int): Int + +scala> sum(2, 2) +val res2: Int = 4 +```` +{% endtab %} +{% endtabs %} + +If you prefer a browser-based playground environment, you can also use [scastie.scala-lang.org](https://scastie.scala-lang.org). + +If you prefer writing your code in a text editor instead of in console prompt, you can use a [worksheet]. + +[worksheet]: {% link _overviews/scala3-book/tools-worksheets.md %} diff --git a/_overviews/scala3-book/taste-summary.md b/_overviews/scala3-book/taste-summary.md new file mode 100644 index 0000000000..96c95089c3 --- /dev/null +++ b/_overviews/scala3-book/taste-summary.md @@ -0,0 +1,32 @@ +--- +title: Summary +type: section +description: This page provides a summary of the previous 'Taste of Scala' sections. +languages: [ru, zh-cn] +num: 16 +previous-page: taste-toplevel-definitions +next-page: first-look-at-types +--- + + +In the previous sections you saw: + +- How to use the Scala REPL +- How to create variables with `val` and `var` +- Some common data types +- Control structures +- How to model the real world using OOP and FP styles +- How to create and use methods +- How to use lambdas (anonymous functions) and higher-order functions +- How to use objects for several purposes +- An introduction to [contextual abstraction][contextual] + +We also mentioned that if you prefer using a browser-based playground environment instead of the Scala REPL, you can also use [Scastie](https://scastie.scala-lang.org/). + +Scala has even more features that aren’t covered in this whirlwind tour. +See the remainder of this book and the [Reference documentation][reference] for many more details. + + + +[reference]: {{ site.scala3ref }}/overview.html +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} diff --git a/_overviews/scala3-book/taste-toplevel-definitions.md b/_overviews/scala3-book/taste-toplevel-definitions.md new file mode 100644 index 0000000000..b56273945f --- /dev/null +++ b/_overviews/scala3-book/taste-toplevel-definitions.md @@ -0,0 +1,71 @@ +--- +title: Toplevel Definitions +type: section +description: This page provides an introduction to top-level definitions in Scala 3 +languages: [ru, zh-cn] +num: 15 +previous-page: taste-contextual-abstractions +next-page: taste-summary +--- + + +In Scala 3, all kinds of definitions can be written at the “top level” of your source code files. +For instance, you can create a file named _MyCoolApp.scala_ and put these contents into it: + +{% tabs toplevel_1 %} +{% tab 'Scala 3 only' for=toplevel_1 %} +```scala +import scala.collection.mutable.ArrayBuffer + +enum Topping: + case Cheese, Pepperoni, Mushrooms + +import Topping.* +class Pizza: + val toppings = ArrayBuffer[Topping]() + +val p = Pizza() + +extension (s: String) + def capitalizeAllWords = s.split(" ").map(_.capitalize).mkString(" ") + +val hwUpper = "hello, world".capitalizeAllWords + +type Money = BigDecimal + +// more definitions here as desired ... + +@main def myApp = + p.toppings += Cheese + println("show me the code".capitalizeAllWords) +``` +{% endtab %} +{% endtabs %} + +As shown, there’s no need to put those definitions inside a `package`, `class`, or other construct. + +## Replaces package objects + +If you’re familiar with Scala 2, this approach replaces _package objects_. +But while being much easier to use, they work similarly: When you place a definition in a package named _foo_, you can then access that definition under all other packages under _foo_, such as within the _foo.bar_ package in this example: + +{% tabs toplevel_2 %} +{% tab 'Scala 3 only' for=toplevel_2 %} +```scala +package foo { + def double(i: Int) = i * 2 +} + +package foo { + package bar { + @main def fooBarMain = + println(s"${double(1)}") // this works + } +} +``` +{% endtab %} +{% endtabs %} + +Curly braces are used in this example to put an emphasis on the package nesting. + +The benefit of this approach is that you can place definitions under a package named _com.acme.myapp_, and then those definitions can be referenced within _com.acme.myapp.model_, _com.acme.myapp.controller_, etc. diff --git a/_overviews/scala3-book/taste-vars-data-types.md b/_overviews/scala3-book/taste-vars-data-types.md new file mode 100644 index 0000000000..194e2d7f40 --- /dev/null +++ b/_overviews/scala3-book/taste-vars-data-types.md @@ -0,0 +1,273 @@ +--- +title: Variables and Data Types +type: section +description: This section demonstrates val and var variables, and some common Scala data types. +languages: [ru, zh-cn] +num: 7 +previous-page: taste-repl +next-page: taste-control-structures +--- + + +This section provides a look at Scala variables and data types. + +## Two types of variables + +When you create a new variable in Scala, you declare whether the variable is immutable or mutable: + + + + + + + + + + + + + + + + + + +
            Variable TypeDescription
            valCreates an immutable variable—like final in Java. You should always create a variable with val, unless there’s a reason you need a mutable variable.
            varCreates a mutable variable, and should only be used when a variable’s contents will change over time.
            + +These examples show how to create `val` and `var` variables: + +{% tabs var-express-1 %} +{% tab 'Scala 2 and 3' %} + +```scala +// immutable +val a = 0 + +// mutable +var b = 1 +``` +{% endtab %} +{% endtabs %} + +In an application, a `val` can’t be reassigned. +You’ll cause a compiler error if you try to reassign one: + +{% tabs var-express-2 %} +{% tab 'Scala 2 and 3' %} + +```scala +val msg = "Hello, world" +msg = "Aloha" // "reassignment to val" error; this won’t compile +``` +{% endtab %} +{% endtabs %} + +Conversely, a `var` can be reassigned: + +{% tabs var-express-3 %} +{% tab 'Scala 2 and 3' %} + +```scala +var msg = "Hello, world" +msg = "Aloha" // this compiles because a var can be reassigned +``` +{% endtab %} +{% endtabs %} + +## Declaring variable types + +When you create a variable you can explicitly declare its type, or let the compiler infer the type: + +{% tabs var-express-4 %} +{% tab 'Scala 2 and 3' %} + +```scala +val x: Int = 1 // explicit +val x = 1 // implicit; the compiler infers the type +``` +{% endtab %} +{% endtabs %} + +The second form is known as _type inference_, and it’s a great way to help keep this type of code concise. +The Scala compiler can usually infer the data type for you, as shown in the output of these REPL examples: + +{% tabs var-express-5 %} +{% tab 'Scala 2 and 3' %} + +```scala +scala> val x = 1 +val x: Int = 1 + +scala> val s = "a string" +val s: String = a string + +scala> val nums = List(1, 2, 3) +val nums: List[Int] = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +You can always explicitly declare a variable’s type if you prefer, but in simple assignments like these it isn’t necessary: + +{% tabs var-express-6 %} +{% tab 'Scala 2 and 3' %} + +```scala +val x: Int = 1 +val s: String = "a string" +val p: Person = Person("Richard") +``` +{% endtab %} +{% endtabs %} + +Notice that with this approach, the code feels more verbose than necessary. + +{% comment %} +TODO: Jonathan had an early comment on the text below: “While it might feel like this, I would be afraid that people automatically assume from this statement that everything is always boxed.” Suggestion on how to change this? +{% endcomment %} + +## Built-in data types + +Scala comes with the standard numeric data types you’d expect, and they’re all full-blown instances of classes. +In Scala, everything is an object. + +These examples show how to declare variables of the numeric types: + +{% tabs var-express-7 %} +{% tab 'Scala 2 and 3' %} + +```scala +val b: Byte = 1 +val i: Int = 1 +val l: Long = 1 +val s: Short = 1 +val d: Double = 2.0 +val f: Float = 3.0 +``` +{% endtab %} +{% endtabs %} + +Because `Int` and `Double` are the default numeric types, you typically create them without explicitly declaring the data type: + +{% tabs var-express-8 %} +{% tab 'Scala 2 and 3' %} + +```scala +val i = 123 // defaults to Int +val j = 1.0 // defaults to Double +``` +{% endtab %} +{% endtabs %} + +In your code you can also append the characters `L`, `D`, and `F` (and their lowercase equivalents) to numbers to specify that they are `Long`, `Double`, or `Float` values: + +{% tabs var-express-9 %} +{% tab 'Scala 2 and 3' %} + +```scala +val x = 1_000L // val x: Long = 1000 +val y = 2.2D // val y: Double = 2.2 +val z = 3.3F // val z: Float = 3.3 +``` +{% endtab %} +{% endtabs %} + +When you need really large numbers, use the `BigInt` and `BigDecimal` types: + +{% tabs var-express-10 %} +{% tab 'Scala 2 and 3' %} + +```scala +var a = BigInt(1_234_567_890_987_654_321L) +var b = BigDecimal(123_456.789) +``` +{% endtab %} +{% endtabs %} + +Where `Double` and `Float` are approximate decimal numbers, `BigDecimal` is used for precise arithmetic. + +Scala also has `String` and `Char` data types: + +{% tabs var-express-11 %} +{% tab 'Scala 2 and 3' %} + +```scala +val name = "Bill" // String +val c = 'a' // Char +``` +{% endtab %} +{% endtabs %} + +### Strings + +Scala strings are similar to Java strings, but they have two great additional features: + +- They support string interpolation +- It’s easy to create multiline strings + +#### String interpolation + +String interpolation provides a very readable way to use variables inside strings. +For instance, given these three variables: + +{% tabs var-express-12 %} +{% tab 'Scala 2 and 3' %} + +```scala +val firstName = "John" +val mi = 'C' +val lastName = "Doe" +``` +{% endtab %} +{% endtabs %} + +You can combine those variables in a string like this: + +{% tabs var-express-13 %} +{% tab 'Scala 2 and 3' %} + +```scala +println(s"Name: $firstName $mi $lastName") // "Name: John C Doe" +``` +{% endtab %} +{% endtabs %} + +Just precede the string with the letter `s`, and then put a `$` symbol before your variable names inside the string. + +To embed arbitrary expressions inside a string, enclose them in curly braces: + +{% tabs var-express-14 %} +{% tab 'Scala 2 and 3' %} + +``` scala +println(s"2 + 2 = ${2 + 2}") // prints "2 + 2 = 4" + +val x = -1 +println(s"x.abs = ${x.abs}") // prints "x.abs = 1" +``` +{% endtab %} +{% endtabs %} + +The `s` that you place before the string is just one possible interpolator. +If you use an `f` instead of an `s`, you can use `printf`-style formatting syntax in the string. +Furthermore, a string interpolator is just a special method and it is possible to define your own. +For instance, some database libraries define the very powerful `sql` interpolator. + +#### Multiline strings + +Multiline strings are created by including the string inside three double-quotes: + +{% tabs var-express-15 %} +{% tab 'Scala 2 and 3' %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` +{% endtab %} +{% endtabs %} + +> For more details on string interpolators and multiline strings, see the [“First Look at Types” chapter][first-look]. + +[first-look]: {% link _overviews/scala3-book/first-look-at-types.md %} diff --git a/_overviews/scala3-book/tools-sbt.md b/_overviews/scala3-book/tools-sbt.md new file mode 100644 index 0000000000..c17820ecf5 --- /dev/null +++ b/_overviews/scala3-book/tools-sbt.md @@ -0,0 +1,511 @@ +--- +title: Building and Testing Scala Projects with sbt +type: section +description: This section looks at a commonly-used build tool, sbt, and a testing library, ScalaTest. +languages: [ru, zh-cn] +num: 71 +previous-page: scala-tools +next-page: tools-worksheets +--- + +In this section you’ll see two tools that are commonly used in Scala projects: + +- The [sbt](https://www.scala-sbt.org) build tool +- [ScalaTest](https://www.scalatest.org), a source code testing framework + +We’ll start by showing how to use sbt to build your Scala projects, and then we’ll show how to use sbt and ScalaTest together to test your Scala projects. + +> If you want to learn about tools to help you migrate your Scala 2 code to Scala 3, see our [Scala 3 Migration Guide](/scala3/guides/migration/compatibility-intro.html). + + + +## Building Scala projects with sbt + +You can use several different tools to build your Scala projects, including Ant, Maven, Gradle, Mill, and more. +But a tool named _sbt_ was the first build tool that was specifically created for Scala. + +> To install sbt, see [its download page](https://www.scala-sbt.org/download.html) or our [Getting Started][getting_started] page. + + + +### Creating a “Hello, world” project + +You can create an sbt “Hello, world” project in just a few steps. +First, create a directory to work in, and move into that directory: + +```bash +$ mkdir hello +$ cd hello +``` + +In the directory `hello`, create a subdirectory `project`: + +```bash +$ mkdir project +``` + +Create a file named _build.properties_ in the directory `project`, with +the following content: + +```text +sbt.version=1.10.11 +``` + +Then create a file named _build.sbt_ in the project root directory that contains this line: + +```scala +scalaVersion := "{{ site.scala-3-version }}" +``` + +Now create a file named something like _Hello.scala_---the first part of the name doesn’t matter---with this line: + +```scala +@main def helloWorld = println("Hello, world") +``` + +That’s all you have to do. + +You should have a project structure like the following: + +~~~ bash +$ tree +. +├── build.sbt +├── Hello.scala +└── project + └── build.properties +~~~ + +Now run the project with this `sbt` command: + +```bash +$ sbt run +``` + +You should see output that looks like this, including the `"Hello, world"` from your program: + +```bash +$ sbt run +[info] welcome to sbt 1.5.4 (AdoptOpenJDK Java 11.x) +[info] loading project definition from project ... +[info] loading settings for project from build.sbt ... +[info] compiling 1 Scala source to target/scala-3.0.0/classes ... +[info] running helloWorld +Hello, world +[success] Total time: 2 s +``` + +The sbt launcher---the `sbt` command-line tool---loads the version of sbt set in the file _project/build.properties_, which loads the version of the Scala compiler set in the file _build.sbt_, compiles the code in the file _Hello.scala_, and runs the resulting bytecode. + +When you look at your directory, you’ll see that sbt has a directory named _target_. +These are working directories that sbt uses. + +As you can see, creating and running a little Scala project with sbt takes just a few simple steps. + +### Using sbt with larger projects + +For a little project, that’s all that sbt requires to run. +For larger projects that require many source code files, dependencies, or sbt plugins, you’ll want to create an organized directory structure. +The rest of this section demonstrates the structure that sbt uses. + + +### The sbt directory structure + +Like Maven, sbt uses a standard project directory structure. +A nice benefit of that is that once you’re comfortable with its structure, it makes it easy to work on other Scala/sbt projects. + +The first thing to know is that underneath the root directory of your project, sbt expects a directory structure that looks like this: + +```text +. +├── build.sbt +├── project/ +│ └── build.properties +├── src/ +│ ├── main/ +│ │ ├── java/ +│ │ ├── resources/ +│ │ └── scala/ +│ └── test/ +│ ├── java/ +│ ├── resources/ +│ └── scala/ +└── target/ +``` + +You can also add a _lib_ directory under the root directory if you want to add unmanaged dependencies---JAR files---to your project. + +If you’re going to create a project that has Scala source code files and tests, but won’t be using any Java source code files, and doesn’t need any “resources”---such as embedded images, configuration files, etc.---this is all you really need under the _src_ directory: + +```text +. +└── src/ + ├── main/ + │ └── scala/ + └── test/ + └── scala/ +``` + + +### “Hello, world” with an sbt directory structure + +{% comment %} +LATER: using something like `sbt new scala/scala3.g8` may eventually + be preferable, but that seems to have a few bugs atm (creates + a 'target' directory above the root; renames the root dir; + uses 'dottyVersion'; 'name' doesn’t match the supplied name; + config syntax is a little hard for beginners.) +{% endcomment %} + +Creating this directory structure is simple. +There are tools to do this for you, but assuming that you’re using a Unix/Linux system, you can use these commands to create your first sbt project directory structure: + +```bash +$ mkdir HelloWorld +$ cd HelloWorld +$ mkdir -p src/{main,test}/scala +$ mkdir project target +``` + +When you run a `find .` command after running those commands, you should see this result: + +```bash +$ find . +. +./project +./src +./src/main +./src/main/scala +./src/test +./src/test/scala +./target +``` + +If you see that, you’re in great shape for the next step. + +> There are other ways to create the files and directories for an sbt project. +> One way is to use the `sbt new` command, [which is documented here on scala-sbt.org](https://www.scala-sbt.org/1.x/docs/Hello.html). +> That approach isn’t shown here because some of the files it creates are more complicated than necessary for an introduction like this. + + +### Creating a first build.sbt file + +At this point you only need two more things to run a “Hello, world” project: + +- A _build.sbt_ file +- A _Hello.scala_ file + +For a little project like this, the _build.sbt_ file only needs a `scalaVersion` entry, but we’ll add three lines that you commonly see: + +```scala +name := "HelloWorld" +version := "0.1" +scalaVersion := "{{ site.scala-3-version }}" +``` + +Because sbt projects use a standard directory structure, sbt can find everything else it needs. + +Now you just need to add a little “Hello, world” program. + + +### A “Hello, world” program + +In large projects, all of your Scala source code files will go under the _src/main/scala_ and _src/test/scala_ directories, but for a little sample project like this, you can put your source code file in the root directory of your project. +Therefore, create a file named _HelloWorld.scala_ in the root directory with these contents: + +```scala +@main def helloWorld = println("Hello, world") +``` + +That code defines a Scala 3 “main” method that prints the `"Hello, world"` when it’s run. + +Now, use the `sbt run` command to compile and run your project: + +```bash +$ sbt run + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition +[info] loading settings for project root from build.sbt ... +[info] Compiling 1 Scala source ... +[info] running helloWorld +Hello, world +[success] Total time: 4 s +``` + +The first time you run `sbt` it downloads everything it needs, and that can take a few moments to run, but after that it gets much faster. + +Also, once you get this first step working, you’ll find that it’s much faster to run sbt interactively. +To do that, first run the `sbt` command by itself: + +```bash +$ sbt + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition ... +[info] loading settings for project root from build.sbt ... +[info] sbt server started at + local:///${HOME}/.sbt/1.0/server/7d26bae822c36a31071c/sock +sbt:hello-world> _ +``` + +Then inside this sbt shell, execute its `run` command: + +```` +sbt:hello-world> run + +[info] running helloWorld +Hello, world +[success] Total time: 0 s +```` + +There, that’s much faster. + +If you type `help` at the sbt command prompt you’ll see a list of other commands you can run. +But for now, just type `exit` (or press `CTRL-D`) to leave the sbt shell. + +### Using project templates + +Manually creating the project structure can be tedious. Thankfully, sbt can create it for you, +based on a template. + +To create a Scala 3 project from a template, run the following command in a shell: + +~~~ +$ sbt new scala/scala3.g8 +~~~ + +Sbt will load the template, ask some questions, and create the project files in a subdirectory: + +~~~ +$ tree scala-3-project-template +scala-3-project-template +├── build.sbt +├── project +│ └── build.properties +├── README.md +└── src + ├── main + │ └── scala + │ └── Main.scala + └── test + └── scala + └── Test1.scala +~~~ + +> If you want to create a Scala 3 project that cross-compiles with Scala 2, use the template `scala/scala3-cross.g8`: +> +> ~~~ +> $ sbt new scala/scala3-cross.g8 +> ~~~ + +Learn more about `sbt new` and project templates in the [documentation of sbt](https://www.scala-sbt.org/1.x/docs/sbt-new-and-Templates.html#sbt+new+and+Templates). + +### Other build tools for Scala + +While sbt is widely used, there are other tools you can use to build Scala projects: + +- [Ant](https://ant.apache.org/) +- [Gradle](https://gradle.org/) +- [Maven](https://maven.apache.org/) +- [Mill](https://com-lihaoyi.github.io/mill/) + +#### Coursier + +In a related note, [Coursier](https://get-coursier.io/docs/overview) is a “dependency resolver,” similar to Maven and Ivy in function. +It’s written from scratch in Scala, “embraces functional programming principles,” and downloads artifacts in parallel for rapid downloads. +sbt uses it to handle most dependency resolutions, and as a command-line tool, it can be used to easily install tools like sbt, Java, and Scala on your system, as shown in our [Getting Started][getting_started] page. + +This example from the `launch` web page shows that the `cs launch` command can be used to launch applications from dependencies: + +```scala +$ cs launch org.scalameta::scalafmt-cli:2.4.2 -- --help +scalafmt 2.4.2 +Usage: scalafmt [options] [...] + + -h, --help prints this usage text + -v, --version print version + more ... +``` + +See Coursier’s [launch page](https://get-coursier.io/docs/cli-launch) for more details. + + + +## Using sbt with ScalaTest + +[ScalaTest](https://www.scalatest.org) is one of the main testing libraries for Scala projects. +In this section you’ll see the steps necessary to create a Scala/sbt project that uses ScalaTest. + + +### 1) Create the project directory structure + +As with the previous lesson, create an sbt project directory structure for a project named _HelloScalaTest_ with the following commands: + +```bash +$ mkdir HelloScalaTest +$ cd HelloScalaTest +$ mkdir -p src/{main,test}/scala +$ mkdir project +``` + + +### 2) Create the build.properties and build.sbt files + +Next, create a _build.properties_ file in the _project/_ subdirectory of your project +with this line: + +```text +sbt.version=1.10.11 +``` + +Next, create a _build.sbt_ file in the root directory of your project with these contents: + +```scala +name := "HelloScalaTest" +version := "0.1" +scalaVersion := "{{site.scala-3-version}}" + +libraryDependencies ++= Seq( + "org.scalatest" %% "scalatest" % "3.2.19" % Test +) +``` + +The first three lines of this file are essentially the same as the first example. +The `libraryDependencies` lines tell sbt to include the dependencies (JAR files) that are needed to include ScalaTest. + +> The ScalaTest documentation has always been good, and you can always find the up to date information on what those lines should look like on the [Installing ScalaTest](https://www.scalatest.org/install) page. + + +### 3) Create a Scala source code file + +Next, create a Scala program that you can use to demonstrate ScalaTest. +First, create a directory under _src/main/scala_ named _math_: + +```bash +$ mkdir src/main/scala/math + ---- +``` + +Then, inside that directory, create a file named _MathUtils.scala_ with these contents: + +```scala +package math + +object MathUtils: + def double(i: Int) = i * 2 +``` + +That method provides a simple way to demonstrate ScalaTest. + + +{% comment %} +Because this project doesn’t have a `main` method, we don’t try to run it with `sbt run`; we just compile it with `sbt compile`: + +```` +$ sbt compile + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition ... +[info] loading settings for project ... +[info] Executing in batch mode. For better performance use sbt's shell +[success] Total time: 1 s +```` + +With that compiled, let’s create a ScalaTest file to test the `double` method. +{% endcomment %} + + +### 4) Create your first ScalaTest tests + +ScalaTest is very flexible, and offers several different ways to write tests. +A simple way to get started is to write tests using the ScalaTest `AnyFunSuite`. +To get started, create a directory named _math_ under the _src/test/scala_ directory: + +```bash +$ mkdir src/test/scala/math + ---- +``` + +Next, create a file named _MathUtilsTests.scala_ in that directory with the following contents: + +```scala +package math + +import org.scalatest.funsuite.AnyFunSuite + +class MathUtilsTests extends AnyFunSuite: + + // test 1 + test("'double' should handle 0") { + val result = MathUtils.double(0) + assert(result == 0) + } + + // test 2 + test("'double' should handle 1") { + val result = MathUtils.double(1) + assert(result == 2) + } + + test("test with Int.MaxValue") (pending) + +end MathUtilsTests +``` + +This code demonstrates the ScalaTest `AnyFunSuite` approach. +A few important points: + +- Your test class should extend `AnyFunSuite` +- You create tests as shown, by giving each `test` a unique name +- At the end of each test you should call `assert` to test that a condition has been satisfied +- When you know you want to write a test, but you don’t want to write it right now, create the test as “pending,” with the syntax shown + +Using ScalaTest like this is similar to JUnit, so if you’re coming to Scala from Java, hopefully this looks similar. + +Now you can run these tests with the `sbt test` command. +Skipping the first few lines of output, the result looks like this: + +```` +sbt:HelloScalaTest> test + +[info] Compiling 1 Scala source ... +[info] MathUtilsTests: +[info] - 'double' should handle 0 +[info] - 'double' should handle 1 +[info] - test with Int.MaxValue (pending) +[info] Total number of tests run: 2 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 1 +[info] All tests passed. +[success] Total time: 1 s +```` + +If everything works well, you’ll see output that looks like that. +Welcome to the world of testing Scala applications with sbt and ScalaTest. + + +### Support for many types of tests + +This example demonstrates a style of testing that’s similar to xUnit _Test-Driven Development_ (TDD) style testing, with a few benefits of the _Behavior-Driven Development_ (BDD) style. + +As mentioned, ScalaTest is flexible and you can also write tests using other styles, such as a style similar to Ruby’s RSpec. +You can also use mock objects, property-based testing, and use ScalaTest to test Scala.js code. + +See the User Guide on the [ScalaTest website](https://www.scalatest.org) for more details on the different testing styles that are available. + + + +## Where to go from here + +For more information about sbt and ScalaTest, see the following resources: + +- [The sbt documentation](https://www.scala-sbt.org/1.x/docs/) +- [The ScalaTest website](https://www.scalatest.org/) + + + +[getting_started]: {{ site.baseurl }}/scala3/getting-started.html diff --git a/_overviews/scala3-book/tools-worksheets.md b/_overviews/scala3-book/tools-worksheets.md new file mode 100644 index 0000000000..cf14935e46 --- /dev/null +++ b/_overviews/scala3-book/tools-worksheets.md @@ -0,0 +1,57 @@ +--- +title: Worksheets +type: section +description: This section looks at worksheets, an alternative to Scala projects. +languages: [ru, zh-cn] +num: 72 +previous-page: tools-sbt +next-page: interacting-with-java +--- + +A worksheet is a Scala file that is evaluated on save, and the result of each expression is shown +in a column to the right of your program. Worksheets are like a [REPL session] on steroids, and +enjoy 1st class editor support: completion, hyperlinking, interactive errors-as-you-type, etc. +Worksheets use the extension `.worksheet.sc`. + +In the following, we show how to use worksheets in IntelliJ, and in VS Code (with the Metals extension). + +1. Open a Scala project, or create one. + - To create a project in IntelliJ, select “File” -> “New” -> “Project…”, select “Scala” + in the left column, and click “Next” to set the project name and location. + - To create a project in VS Code, run the command “Metals: New Scala project”, select the + seed `scala/scala3.g8`, set the project location, open it in a new VS Code window, and + import its build. +1. Create a file named `hello.worksheet.sc` in the directory `src/main/scala/`. + - In IntelliJ, right-click on the directory `src/main/scala/`, and select “New”, and + then “File”. + - In VS Code, right-click on the directory `src/main/scala/`, and select “New File”. +1. Paste the following content in the editor: + ~~~ + println("Hello, world!") + + val x = 1 + x + x + ~~~ +1. Evaluate the worksheet. + - In IntelliJ, click on the green arrow at the top of the editor to evaluate the worksheet. + - In VS Code, save the file. + + You should see the result of the evaluation of every line on the right panel (IntelliJ), or + as comments (VS Code). + +![]({{ site.baseurl }}/resources/images/scala3-book/intellij-worksheet.png) + +A worksheet evaluated in IntelliJ. + +![]({{ site.baseurl }}/resources/images/scala3-book/metals-worksheet.png) + +A worksheet evaluated in VS Code (with the Metals extension). + +Note that the worksheet will use the Scala version defined by your project (set by the key `scalaVersion`, +in your file `build.sbt`, typically). + +Also note that worksheets don’t have a [program entry point]. Instead, top-level statements and expressions +are evaluated from top to bottom. + +[REPL session]: {% link _overviews/scala3-book/taste-repl.md %} +[program entry point]: {% link _overviews/scala3-book/methods-main-methods.md %} diff --git a/_overviews/scala3-book/types-adts-gadts.md b/_overviews/scala3-book/types-adts-gadts.md new file mode 100644 index 0000000000..356d01c16d --- /dev/null +++ b/_overviews/scala3-book/types-adts-gadts.md @@ -0,0 +1,195 @@ +--- +title: Algebraic Data Types +type: section +description: This section introduces and demonstrates algebraic data types (ADTs) in Scala 3. +languages: [ru, zh-cn] +num: 54 +previous-page: types-union +next-page: types-variance +scala3: true +versionSpecific: true +--- + + +Algebraic Data Types (ADTs) can be created with the `enum` construct, so we’ll briefly review enumerations before looking at ADTs. + +## Enumerations + +An _enumeration_ is used to define a type consisting of a set of named values: + +```scala +enum Color: + case Red, Green, Blue +``` +which can be seen as a shorthand for: +```scala +enum Color: + case Red extends Color + case Green extends Color + case Blue extends Color +``` +#### Parameters +Enums can be parameterized: + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` +This way, each of the different variants has a value member `rgb` which is assigned the corresponding value: +```scala +println(Color.Green.rgb) // prints 65280 +``` + +#### Custom Definitions +Enums can also have custom definitions: + +```scala +enum Planet(mass: Double, radius: Double): + + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity + + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Venus extends Planet(4.869e+24, 6.0518e6) + case Earth extends Planet(5.976e+24, 6.37814e6) + // 5 or 6 more planets ... +``` + +Like classes and `case` classes, you can also define a companion object for an enum: + +```scala +object Planet: + def main(args: Array[String]) = + val earthWeight = args(0).toDouble + val mass = earthWeight / Earth.surfaceGravity + for (p <- values) + println(s"Your weight on $p is ${p.surfaceWeight(mass)}") +``` + +## Algebraic Datatypes (ADTs) + +The `enum` concept is general enough to also support _algebraic data types_ (ADTs) and their generalized version (GADTs). +Here’s an example that shows how an `Option` type can be represented as an ADT: + +```scala +enum Option[+T]: + case Some(x: T) + case None +``` + +This example creates an `Option` enum with a covariant type parameter `T` consisting of two cases, `Some` and `None`. +`Some` is _parameterized_ with a value parameter `x`; this is a shorthand for writing a `case` class that extends `Option`. +Since `None` is not parameterized, it’s treated as a normal `enum` value. + +The `extends` clauses that were omitted in the previous example can also be given explicitly: + +```scala +enum Option[+T]: + case Some(x: T) extends Option[T] + case None extends Option[Nothing] +``` + +As with normal `enum` values, the cases of an `enum` are defined in the `enum`s companion object, so they’re referred to as `Option.Some` and `Option.None` (unless the definitions are “pulled out” with an import): + +```scala +scala> Option.Some("hello") +val res1: t2.Option[String] = Some(hello) + +scala> Option.None +val res2: t2.Option[Nothing] = None +``` + +As with other enumeration uses, ADTs can define additional methods. +For instance, here’s `Option` again, with an `isDefined` method and an `Option(...)` constructor in its companion object: + +```scala +enum Option[+T]: + case Some(x: T) + case None + + def isDefined: Boolean = this match + case None => false + case Some(_) => true + +object Option: + def apply[T >: Null](x: T): Option[T] = + if (x == null) None else Some(x) +``` + +Enumerations and ADTs share the same syntactic construct, so they can +be seen simply as two ends of a spectrum, and it’s perfectly possible +to construct hybrids. +For instance, the code below gives an +implementation of `Color`, either with three enum values or with a +parameterized case that takes an RGB value: + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) + case Mix(mix: Int) extends Color(mix) +``` + +#### Recursive Enumerations +So far all the enumerations that we defined consisted of different variants of values or case classes. +Enumerations can also be recursive, as illustrated in the below example of encoding natural numbers: +```scala +enum Nat: + case Zero + case Succ(n: Nat) +``` +For example the value `Succ(Succ(Zero))` represents the number `2` in an unary encoding. +Lists can be defined in a very similar way: + +```scala +enum List[+A]: + case Nil + case Cons(head: A, tail: List[A]) +``` + +## Generalized Algebraic Datatypes (GADTs) +The above notation for enumerations is very concise and serves as the perfect starting point for modeling your data types. +Since we can always be more explicit, it is also possible to express types that are much more powerful: generalized algebraic datatypes (GADTs). + +Here is an example of a GADT where the type parameter (`T`) specifies the contents stored in the box: +```scala +enum Box[T](contents: T): + case IntBox(n: Int) extends Box[Int](n) + case BoolBox(b: Boolean) extends Box[Boolean](b) +``` +Pattern matching on the particular constructor (`IntBox` or `BoolBox`) recovers the type information: +```scala +def extract[T](b: Box[T]): T = b match + case IntBox(n) => n + 1 + case BoolBox(b) => !b +``` +It is only safe to return an `Int` in the first case, since we know from pattern matching that the input was an `IntBox`. + + +## Desugaring Enumerations +_Conceptually_, enums can be thought of as defining a sealed class together with its companion object. +Let’s look at the desugaring of our `Color` enum above: +```scala +sealed abstract class Color(val rgb: Int) extends scala.reflect.Enum +object Color: + case object Red extends Color(0xFF0000) { def ordinal = 0 } + case object Green extends Color(0x00FF00) { def ordinal = 1 } + case object Blue extends Color(0x0000FF) { def ordinal = 2 } + case class Mix(mix: Int) extends Color(mix) { def ordinal = 3 } + + def fromOrdinal(ordinal: Int): Color = ordinal match + case 0 => Red + case 1 => Green + case 2 => Blue + case _ => throw new NoSuchElementException(ordinal.toString) +``` +Note that the above desugaring is simplified and we purposefully leave out [some details][desugar-enums]. + +While enums could be manually encoded using other constructs, using enumerations is more concise and also comes with a few additional utilities (such as the `fromOrdinal` method). + + +[desugar-enums]: {{ site.scala3ref }}/enums/desugarEnums.html diff --git a/_overviews/scala3-book/types-dependent-function.md b/_overviews/scala3-book/types-dependent-function.md new file mode 100644 index 0000000000..cf86880fa6 --- /dev/null +++ b/_overviews/scala3-book/types-dependent-function.md @@ -0,0 +1,149 @@ +--- +title: Dependent Function Types +type: section +description: This section introduces and demonstrates dependent function types in Scala 3. +languages: [ru, zh-cn] +num: 58 +previous-page: types-structural +next-page: types-others +scala3: true +versionSpecific: true +--- + +A *dependent function type* describes function types, where the result type may depend on the function’s parameter values. +The concept of dependent types, and of dependent function types, is more advanced and you would typically only come across it when designing your own libraries or using advanced libraries. + +## Dependent Method Types +Let's consider the following example of a heterogenous database that can store values of different types. +The key contains the information about what's the type of the corresponding value: + +```scala +trait Key { type Value } + +trait DB { + def get(k: Key): Option[k.Value] // a dependent method +} +``` +Given a key, the method `get` lets us access the map and potentially returns the stored value of type `k.Value`. +We can read this _path-dependent type_ as: "depending on the concrete type of the argument `k`, we return a matching value". + +For example, we could have the following keys: +```scala +object Name extends Key { type Value = String } +object Age extends Key { type Value = Int } +``` +The following calls to method `get` would now type check: +```scala +val db: DB = ... +val res1: Option[String] = db.get(Name) +val res2: Option[Int] = db.get(Age) +``` +Calling the method `db.get(Name)` returns a value of type `Option[String]`, while calling `db.get(Age)` returns a value of type `Option[Int]`. +The return type _depends_ on the concrete type of the argument passed to `get`---hence the name _dependent type_. + +## Dependent Function Types +As seen above, Scala 2 already had support for dependent method types. +However, creating values of type `DB` is quite cumbersome: +```scala +// a user of a DB +def user(db: DB): Unit = + db.get(Name) ... db.get(Age) + +// creating an instance of the DB and passing it to `user` +user(new DB { + def get(k: Key): Option[k.Value] = ... // implementation of DB +}) +``` +We manually need to create an anonymous inner class of `DB`, implementing the `get` method. +For code that relies on creating many different instances of `DB` this is very tedious. + +The trait `DB` only has a single abstract method `get`. +Wouldn't it be nice, if we could use lambda syntax instead? +```scala +user { k => + ... // implementation of DB +} +``` +In fact, this is now possible in Scala 3! We can define `DB` as a _dependent function type_: +```scala +type DB = (k: Key) => Option[k.Value] +// ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +// A dependent function type +``` +Given this definition of `DB` the above call to `user` type checks, as is. + +You can read more about the internals of dependent function types in the [reference documentation][ref]. + +## Case Study: Numerical Expressions +Let us assume we want to define a module that abstracts over the internal represention of numbers. +This can be useful, for instance, to implement libraries for automatic derivation. + +We start by defining our module for numbers: +```scala +trait Nums: + // the type of numbers is left abstract + type Num + + // some operations on numbers + def lit(d: Double): Num + def add(l: Num, r: Num): Num + def mul(l: Num, r: Num): Num +``` +> We omit the concrete implementation of `Nums`, but as an exercise you could implement `Nums` by assigning `type Num = Double` and implement methods accordingly. + +A program that uses our number abstraction now has the following type: + +```scala +type Prog = (n: Nums) => n.Num => n.Num + +val ex: Prog = nums => x => nums.add(nums.lit(0.8), x) +``` +The type of a function that computes the derivative of programs like `ex` is: +```scala +def derivative(input: Prog): Double +``` +Given the facility of dependent function types, calling this function with different programs is very convenient: +```scala +derivative { nums => x => x } +derivative { nums => x => nums.add(nums.lit(0.8), x) } +// ... +``` + +To recall, the same program in the encoding above would be: +```scala +derivative(new Prog { + def apply(nums: Nums)(x: nums.Num): nums.Num = x +}) +derivative(new Prog { + def apply(nums: Nums)(x: nums.Num): nums.Num = nums.add(nums.lit(0.8), x) +}) +// ... +``` + +#### Combination with Context Functions +The combination of extension methods, [context functions][ctx-fun], and dependent functions provides a powerful tool for library designers. +For instance, we can refine our library from above as follows: +```scala +trait NumsDSL extends Nums: + extension (x: Num) + def +(y: Num) = add(x, y) + def *(y: Num) = mul(x, y) + +def const(d: Double)(using n: Nums): n.Num = n.lit(d) + +type Prog = (n: NumsDSL) ?=> n.Num => n.Num +// ^^^ +// prog is now a context function that implicitly +// assumes a NumsDSL in the calling context + +def derivative(input: Prog): Double = ... + +// notice how we do not need to mention Nums in the examples below? +derivative { x => const(1.0) + x } +derivative { x => x * x + const(2.0) } +// ... +``` + + +[ref]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[ctx-fun]: {{ site.scala3ref }}/contextual/context-functions.html diff --git a/_overviews/scala3-book/types-generics.md b/_overviews/scala3-book/types-generics.md new file mode 100644 index 0000000000..84ddd4599e --- /dev/null +++ b/_overviews/scala3-book/types-generics.md @@ -0,0 +1,89 @@ +--- +title: Generics +type: section +description: This section introduces and demonstrates generics in Scala 3. +languages: [ru, zh-cn] +num: 51 +previous-page: types-inferred +next-page: types-intersection +--- + + +Generic classes (or traits) take a type as _a parameter_ within square brackets `[...]`. +The Scala convention is to use a single letter (like `A`) to name those type parameters. +The type can then be used inside the class as needed for method instance parameters, or on return types: + +{% tabs stack class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +// here we declare the type parameter A +// v +class Stack[A] { + private var elements: List[A] = Nil + // ^ + // Here we refer to the type parameter + // v + def push(x: A): Unit = + elements = elements.prepended(x) + def peek: A = elements.head + def pop(): A = { + val currentTop = peek + elements = elements.tail + currentTop + } +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +// here we declare the type parameter A +// v +class Stack[A]: + private var elements: List[A] = Nil + // ^ + // Here we refer to the type parameter + // v + def push(x: A): Unit = + elements = elements.prepended(x) + def peek: A = elements.head + def pop(): A = + val currentTop = peek + elements = elements.tail + currentTop +``` +{% endtab %} +{% endtabs %} + +This implementation of a `Stack` class takes any type as a parameter. +The beauty of generics is that you can now create a `Stack[Int]`, `Stack[String]`, and so on, allowing you to reuse your implementation of a `Stack` for arbitrary element types. + +This is how you create and use a `Stack[Int]`: + +{% tabs stack-usage class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val stack = new Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val stack = Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 +``` +{% endtab %} +{% endtabs %} + +> See the [Variance section][variance] for details on how to express variance with generic types. + + +[variance]: {% link _overviews/scala3-book/types-variance.md %} diff --git a/_overviews/scala3-book/types-inferred.md b/_overviews/scala3-book/types-inferred.md new file mode 100644 index 0000000000..92333b3735 --- /dev/null +++ b/_overviews/scala3-book/types-inferred.md @@ -0,0 +1,53 @@ +--- +title: Inferred Types +type: section +description: This section introduces and demonstrates inferred types in Scala 3 +languages: [ru, zh-cn] +num: 50 +previous-page: types-introduction +next-page: types-generics +--- + + +As with other statically typed programming languages, in Scala you can _declare_ a type when creating a new variable: + +{% tabs xy %} +{% tab 'Scala 2 and 3' %} +```scala +val x: Int = 1 +val y: Double = 1 +``` +{% endtab %} +{% endtabs %} + +In those examples the types are _explicitly_ declared to be `Int` and `Double`, respectively. +However, in Scala you generally don’t have to declare the type when defining value binders: + +{% tabs abm %} +{% tab 'Scala 2 and 3' %} +```scala +val a = 1 +val b = List(1, 2, 3) +val m = Map(1 -> "one", 2 -> "two") +``` +{% endtab %} +{% endtabs %} + +When you do this, Scala _infers_ the types, as shown in the following REPL interaction: + +{% tabs abm2 %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val a = 1 +val a: Int = 1 + +scala> val b = List(1, 2, 3) +val b: List[Int] = List(1, 2, 3) + +scala> val m = Map(1 -> "one", 2 -> "two") +val m: Map[Int, String] = Map(1 -> one, 2 -> two) +``` +{% endtab %} +{% endtabs %} + +Indeed, most variables are defined this way, and Scala’s ability to automatically infer types is one feature that makes it _feel_ like a dynamically typed language. diff --git a/_overviews/scala3-book/types-intersection.md b/_overviews/scala3-book/types-intersection.md new file mode 100644 index 0000000000..2c533ffd09 --- /dev/null +++ b/_overviews/scala3-book/types-intersection.md @@ -0,0 +1,64 @@ +--- +title: Intersection Types +type: section +description: This section introduces and demonstrates intersection types in Scala 3. +languages: [ru, zh-cn] +num: 52 +previous-page: types-generics +next-page: types-union +scala3: true +versionSpecific: true +--- + +Used on types, the `&` operator creates a so called _intersection type_. +The type `A & B` represents values that are **both** of the type `A` and of the type `B` at the same time. +For instance, the following example uses the intersection type `Resettable & Growable[String]`: + +{% tabs intersection-reset-grow %} + +{% tab 'Scala 3 Only' %} + +```scala +trait Resettable: + def reset(): Unit + +trait Growable[A]: + def add(a: A): Unit + +def f(x: Resettable & Growable[String]): Unit = + x.reset() + x.add("first") +``` + +{% endtab %} + +{% endtabs %} + +In the method `f` in this example, the parameter `x` is required to be *both* a `Resettable` and a `Growable[String]`. + +The _members_ of an intersection type `A & B` are all the members of `A` and all the members of `B`. +Therefore, as shown, `Resettable & Growable[String]` has member methods `reset` and `add`. + +Intersection types can be useful to describe requirements _structurally_. +That is, in our example `f`, we directly express that we are happy with any value for `x` as long as it’s a subtype of both `Resettable` and `Growable`. +We **did not** have to create a _nominal_ helper trait like the following: + +{% tabs normal-trait class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +trait Both[A] extends Resettable with Growable[A] +def f(x: Both[String]): Unit +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +trait Both[A] extends Resettable, Growable[A] +def f(x: Both[String]): Unit +``` +{% endtab %} +{% endtabs %} + +There is an important difference between the two alternatives of defining `f`: While both allow `f` to be called with instances of `Both`, only the former allows passing instances that are subtypes of `Resettable` and `Growable[String]`, but _not of_ `Both[String]`. + +> Note that `&` is _commutative_: `A & B` is the same type as `B & A`. diff --git a/_overviews/scala3-book/types-introduction.md b/_overviews/scala3-book/types-introduction.md new file mode 100644 index 0000000000..77a79a0844 --- /dev/null +++ b/_overviews/scala3-book/types-introduction.md @@ -0,0 +1,58 @@ +--- +title: Types and the Type System +type: chapter +description: This chapter provides an introduction to Scala 3 types and the type system. +languages: [ru, zh-cn] +num: 49 +previous-page: fp-summary +next-page: types-inferred +--- + + +Scala is a unique language in that it’s statically typed, but often _feels_ flexible and dynamic. +For instance, thanks to type inference you can write code like this without explicitly specifying the variable types: + +{% tabs hi %} +{% tab 'Scala 2 and 3' %} +```scala +val a = 1 +val b = 2.0 +val c = "Hi!" +``` +{% endtab %} +{% endtabs %} + +That makes the code feel dynamically typed. +And thanks to new features, like [union types][union-types] in Scala 3, you can also write code like the following that expresses very concisely which values are expected as arguments and which types are returned: + +{% tabs union-example %} +{% tab 'Scala 3 Only' %} +```scala +def isTruthy(a: Boolean | Int | String): Boolean = ??? +def dogCatOrWhatever(): Dog | Plant | Car | Sun = ??? +``` +{% endtab %} +{% endtabs %} + +As the example suggests, when using union types, the types don’t have to share a common hierarchy, and you can still accept them as arguments or return them from a method. + +If you’re an application developer, you’ll use features like type inference every day and generics every week. +When you read the Scaladoc for classes and methods, you’ll also need to have some understanding of _variance_. +Hopefully you’ll see that using types can be relatively simple and also offers a lot of expressive power, flexibility, and control for library developers. + + +## Benefits of types + +Statically-typed programming languages offer a number of benefits, including: + +- Helping to provide strong IDE support +- Eliminating many classes of potential errors at compile time +- Assisting in refactoring +- Providing strong documentation that cannot be outdated since it is type checked + + +## Introducing features of Scala’s type system + +Given that brief introduction, the following sections provide an overview of the features of Scala’s type system. + +[union-types]: {% link _overviews/scala3-book/types-union.md %} diff --git a/_overviews/scala3-book/types-opaque-types.md b/_overviews/scala3-book/types-opaque-types.md new file mode 100644 index 0000000000..4076749050 --- /dev/null +++ b/_overviews/scala3-book/types-opaque-types.md @@ -0,0 +1,148 @@ +--- +title: Opaque Types +type: section +description: This section introduces and demonstrates opaque types in Scala 3. +languages: [ru, zh-cn] +num: 56 +previous-page: types-variance +next-page: types-structural +scala3: true +versionSpecific: true +--- + +_Opaque type aliases_ provide type abstraction without any **overhead**. +In Scala 2, a similar result could be achieved with [value classes][value-classes]. + +## Abstraction Overhead + +Let us assume we want to define a module that offers arithmetic on numbers, which are represented by their logarithm. +This can be useful to improve precision when the numerical values involved tend to be very large, or close to zero. + +Since it is important to distinguish “regular” double values from numbers stored as their logarithm, we introduce a class `Logarithm`: + +```scala +class Logarithm(protected val underlying: Double): + def toDouble: Double = math.exp(underlying) + def + (that: Logarithm): Logarithm = + // here we use the apply method on the companion + Logarithm(this.toDouble + that.toDouble) + def * (that: Logarithm): Logarithm = + new Logarithm(this.underlying + that.underlying) + +object Logarithm: + def apply(d: Double): Logarithm = new Logarithm(math.log(d)) +``` +The apply method on the companion object lets us create values of type `Logarithm` which we can use as follows: +```scala +val l2 = Logarithm(2.0) +val l3 = Logarithm(3.0) +println((l2 * l3).toDouble) // prints 6.0 +println((l2 + l3).toDouble) // prints 4.999... +``` +While the class `Logarithm` offers a nice abstraction for `Double` values that are stored in this particular logarithmic form, it imposes severe performance overhead: For every single mathematical operation, we need to extract the underlying value and then wrap it again in a new instance of `Logarithm`. + + +## Module Abstractions +Let us consider another approach to implement the same library. +This time instead of defining `Logarithm` as a class, we define it using a _type alias_. +First, we define an abstract interface of our module: + +```scala +trait Logarithms: + + type Logarithm + + // operations on Logarithm + def add(x: Logarithm, y: Logarithm): Logarithm + def mul(x: Logarithm, y: Logarithm): Logarithm + + // functions to convert between Double and Logarithm + def make(d: Double): Logarithm + def extract(x: Logarithm): Double + + // extension methods to use `add` and `mul` as "methods" on Logarithm + extension (x: Logarithm) + def toDouble: Double = extract(x) + def + (y: Logarithm): Logarithm = add(x, y) + def * (y: Logarithm): Logarithm = mul(x, y) +``` +Now, let us implement this abstract interface by saying type `Logarithm` is equal to `Double`: +```scala +object LogarithmsImpl extends Logarithms: + + type Logarithm = Double + + // operations on Logarithm + def add(x: Logarithm, y: Logarithm): Logarithm = make(x.toDouble + y.toDouble) + def mul(x: Logarithm, y: Logarithm): Logarithm = x + y + + // functions to convert between Double and Logarithm + def make(d: Double): Logarithm = math.log(d) + def extract(x: Logarithm): Double = math.exp(x) +``` +Within the implementation of `LogarithmsImpl`, the equation `Logarithm = Double` allows us to implement the various methods. + +#### Leaky Abstractions +However, this abstraction is slightly leaky. +We have to make sure to _only_ ever program against the abstract interface `Logarithms` and never directly use `LogarithmsImpl`. +Directly using `LogarithmsImpl` would make the equality `Logarithm = Double` visible for the user, who might accidentally use a `Double` where a logarithmic double is expected. +For example: + +```scala +import LogarithmsImpl.* +val l: Logarithm = make(1.0) +val d: Double = l // type checks AND leaks the equality! +``` + +Having to separate the module into an abstract interface and implementation can be useful, but is also a lot of effort, just to hide the implementation detail of `Logarithm`. +Programming against the abstract module `Logarithms` can be very tedious and often requires the use of advanced features like path-dependent types, as in the following example: + +```scala +def someComputation(L: Logarithms)(init: L.Logarithm): L.Logarithm = ... +``` + +#### Boxing Overhead +Type abstractions, such as `type Logarithm` [erase](https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure) to their bound (which is `Any` in our case). +That is, although we do not need to manually wrap and unwrap the `Double` value, there will be still some boxing overhead related to boxing the primitive type `Double`. + +## Opaque Types +Instead of manually splitting our `Logarithms` component into an abstract part and into a concrete implementation, we can simply use opaque types in Scala 3 to achieve a similar effect: + +```scala +object Logarithms: +//vvvvvv this is the important difference! + opaque type Logarithm = Double + + object Logarithm: + def apply(d: Double): Logarithm = math.log(d) + + extension (x: Logarithm) + def toDouble: Double = math.exp(x) + def + (y: Logarithm): Logarithm = Logarithm(math.exp(x) + math.exp(y)) + def * (y: Logarithm): Logarithm = x + y +``` +The fact that `Logarithm` is the same as `Double` is only known in the scope where `Logarithm` is defined, which in the above example corresponds to the object `Logarithms`. +The type equality `Logarithm = Double` can be used to implement the methods (like `*` and `toDouble`). + +However, outside of the module the type `Logarithm` is completely encapsulated, or “opaque.” To users of `Logarithm` it is not possible to discover that `Logarithm` is actually implemented as a `Double`: + +```scala +import Logarithms.* +val log2 = Logarithm(2.0) +val log3 = Logarithm(3.0) +println((log2 * log3).toDouble) // prints 6.0 +println((log2 + log3).toDouble) // prints 4.999... + +val d: Double = log2 // ERROR: Found Logarithm required Double +``` + +Even though we abstracted over `Logarithm`, the abstraction comes for free: +Since there is only one implementation, at runtime there will be _no boxing overhead_ for primitive types like `Double`. + +### Summary of Opaque Types +Opaque types offer a sound abstraction over implementation details, without imposing performance overhead. +As illustrated above, opaque types are convenient to use, and integrate very well with the [Extension Methods][extension] feature. + + +[extension]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[value-classes]: {% link _overviews/core/value-classes.md %} diff --git a/_overviews/scala3-book/types-others.md b/_overviews/scala3-book/types-others.md new file mode 100644 index 0000000000..9419073f95 --- /dev/null +++ b/_overviews/scala3-book/types-others.md @@ -0,0 +1,31 @@ +--- +title: Other Types +type: section +description: This section mentions other advanced types in Scala 3. +languages: [ru, zh-cn] +num: 59 +previous-page: types-dependent-function +next-page: ca-contextual-abstractions-intro +scala3: true +versionSpecific: true +--- + + +Scala has several other advanced types that are not shown in this book, including: + +- Type lambdas +- Match types +- Existential types +- Higher-kinded types +- Singleton types +- Refinement types +- Kind polymorphism + +For more details on most of these types, refer to the [Scala 3 Reference documentation][reference]. +For singleton types see the [literal types](https://scala-lang.org/files/archive/spec/3.4/03-types.html#literal-types) section of the Scala 3 spec, +and for refinement types, see the [refined types](https://scala-lang.org/files/archive/spec/3.4/03-types.html) section. + + + + +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_overviews/scala3-book/types-structural.md b/_overviews/scala3-book/types-structural.md new file mode 100644 index 0000000000..afa74fe340 --- /dev/null +++ b/_overviews/scala3-book/types-structural.md @@ -0,0 +1,109 @@ +--- +title: Structural Types +type: section +description: This section introduces and demonstrates structural types in Scala 3. +languages: [ru, zh-cn] +num: 57 +previous-page: types-opaque-types +next-page: types-dependent-function +scala3: true +versionSpecific: true +--- + +{% comment %} +NOTE: It would be nice to simplify this more. +{% endcomment %} + +_Scala 2 has a weaker form of structural types based on Java reflection, achieved with `import scala.language.reflectiveCalls`_. + +## Introduction + +Some use cases, such as modeling database access, are more awkward in statically typed languages than in dynamically typed languages. +With dynamically typed languages, it’s natural to model a row as a record or object, and to select entries with simple dot notation, e.g. `row.columnName`. + +Achieving the same experience in a statically typed language requires defining a class for every possible row arising from database manipulation---including rows arising from joins and projections---and setting up a scheme to map between a row and the class representing it. + +This requires a large amount of boilerplate, which leads developers to trade the advantages of static typing for simpler schemes where column names are represented as strings and passed to other operators, e.g. `row.select("columnName")`. +This approach forgoes the advantages of static typing, and is still not as natural as the dynamically typed version. + +Structural types help in situations where you’d like to support simple dot notation in dynamic contexts without losing the advantages of static typing. +They allow developers to use dot notation and configure how fields and methods should be resolved. + +## Example + +Here’s an example of a structural type `Person`: + +```scala +class Record(elems: (String, Any)*) extends Selectable: + private val fields = elems.toMap + def selectDynamic(name: String): Any = fields(name) + +type Person = Record { + val name: String + val age: Int +} +``` + +The `Person` type adds a _refinement_ to its parent type `Record` that defines `name` and `age` fields. +We say the refinement is _structural_ since `name` and `age` are not defined in the parent type. +But they exist nevertheless as members of class `Person`. +For instance, the following program would print `"Emma is 42 years old."`: + +```scala +val person = Record( + "name" -> "Emma", + "age" -> 42 +).asInstanceOf[Person] + +println(s"${person.name} is ${person.age} years old.") +``` + +The parent type `Record` in this example is a generic class that can represent arbitrary records in its `elems` argument. +This argument is a sequence of pairs of labels of type `String` and values of type `Any`. +When you create a `Person` as a `Record` you have to assert with a typecast that the record defines the right fields of the right types. +`Record` itself is too weakly typed, so the compiler cannot know this without help from the user. +In practice, the connection between a structural type and its underlying generic representation would most likely be done by a database layer, and therefore would not be a concern of the end user. + +`Record` extends the marker trait `scala.Selectable` and defines a method `selectDynamic`, which maps a field name to its value. +Selecting a structural type member is done by calling this method. +The `person.name` and `person.age` selections are translated by the Scala compiler to: + +```scala +person.selectDynamic("name").asInstanceOf[String] +person.selectDynamic("age").asInstanceOf[Int] +``` + +## A second example + +To reinforce what you just saw, here’s another structural type named `Book` that represents a book that you might read from a database: + +```scala +type Book = Record { + val title: String + val author: String + val year: Int + val rating: Double +} +``` + +As with `Person`, this is how you create a `Book` instance: + +```scala +val book = Record( + "title" -> "The Catcher in the Rye", + "author" -> "J. D. Salinger", + "year" -> 1951, + "rating" -> 4.5 +).asInstanceOf[Book] +``` + +## Selectable class + +Besides `selectDynamic`, a `Selectable` class sometimes also defines a method `applyDynamic`. +This can then be used to translate function calls of structural members. +So, if `a` is an instance of `Selectable`, a structural call like `a.f(b, c)` translates to: + +```scala +a.applyDynamic("f")(b, c) +``` + diff --git a/_overviews/scala3-book/types-union.md b/_overviews/scala3-book/types-union.md new file mode 100644 index 0000000000..e685646608 --- /dev/null +++ b/_overviews/scala3-book/types-union.md @@ -0,0 +1,95 @@ +--- +title: Union Types +type: section +description: This section introduces and demonstrates union types in Scala 3. +languages: [ru, zh-cn] +num: 53 +previous-page: types-intersection +next-page: types-adts-gadts +scala3: true +versionSpecific: true +--- + +Used on types, the `|` operator creates a so-called _union type_. +The type `A | B` represents values that are **either** of the type `A` **or** of the type `B`. + +In the following example, the `help` method accepts a parameter named `id` of the union type `Username | Password`, that can be either a `Username` or a `Password`: + +```scala +case class Username(name: String) +case class Password(hash: Hash) + +def help(id: Username | Password) = + val user = id match + case Username(name) => lookupName(name) + case Password(hash) => lookupPassword(hash) + // more code here ... +``` +We implement the method `help` by distinguishing between the two alternatives using pattern matching. + +This code is a flexible and type-safe solution. +If you attempt to pass in a type other than a `Username` or `Password`, the compiler flags it as an error: + +```scala +help("hi") // error: Found: ("hi" : String) + // Required: Username | Password +``` + +You’ll also get an error if you attempt to add a `case` to the `match` expression that doesn’t match the `Username` or `Password` types: + +```scala +case 1.0 => ??? // ERROR: this line won’t compile +``` + +### Alternative to Union Types +As shown, union types can be used to represent alternatives of several different types, without requiring those types to be part of a custom-crafted class hierarchy, or requiring explicit wrapping. + +#### Pre-planning the Class Hierarchy +Without union types, it would require pre-planning of the class hierarchy, like the following example illustrates: + +```scala +trait UsernameOrPassword +case class Username(name: String) extends UsernameOrPassword +case class Password(hash: Hash) extends UsernameOrPassword +def help(id: UsernameOrPassword) = ... +``` + +Pre-planning does not scale very well since, for example, requirements of API users might not be foreseeable. +Additionally, cluttering the type hierarchy with marker traits like `UsernameOrPassword` also makes the code more difficult to read. + +#### Tagged Unions +Another alternative is to define a separate enumeration type like: + +```scala +enum UsernameOrPassword: + case IsUsername(u: Username) + case IsPassword(p: Password) +``` +The enumeration `UsernameOrPassword` represents a _tagged_ union of `Username` and `Password`. +However, this way of modeling the union requires _explicit wrapping and unwrapping_ and, for instance, `Username` is **not** a subtype of `UsernameOrPassword`. + +### Inference of Union Types +The compiler assigns a union type to an expression _only if_ such a type is explicitly given. +For instance, given these values: + +```scala +val name = Username("Eve") // name: Username = Username(Eve) +val password = Password(123) // password: Password = Password(123) +``` + +This REPL example shows how a union type can be used when binding a variable to the result of an `if`/`else` expression: + +```` +scala> val a = if true then name else password +val a: Object = Username(Eve) + +scala> val b: Password | Username = if true then name else password +val b: Password | Username = Username(Eve) +```` + +The type of `a` is `Object`, which is a supertype of `Username` and `Password`, but not the *least* supertype, `Password | Username`. +If you want the least supertype you have to give it explicitly, as is done for `b`. + +> Union types are duals of intersection types. +> And like `&` with intersection types, `|` is also commutative: `A | B` is the same type as `B | A`. + diff --git a/_overviews/scala3-book/types-variance.md b/_overviews/scala3-book/types-variance.md new file mode 100644 index 0000000000..f2b8e3d931 --- /dev/null +++ b/_overviews/scala3-book/types-variance.md @@ -0,0 +1,235 @@ +--- +title: Variance +type: section +description: This section introduces and demonstrates variance in Scala 3. +languages: [ru, zh-cn] +num: 55 +previous-page: types-adts-gadts +next-page: types-opaque-types +--- + +Type parameter _variance_ controls the subtyping of parameterized types (like classes or traits). + +To explain variance, let us assume the following type definitions: + +{% tabs types-variance-1 %} +{% tab 'Scala 2 and 3' %} +```scala +trait Item { def productNumber: String } +trait Buyable extends Item { def price: Int } +trait Book extends Buyable { def isbn: String } + +``` +{% endtab %} +{% endtabs %} + +Let us also assume the following parameterized types: + +{% tabs types-variance-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-2 %} +```scala +// an example of an invariant type +trait Pipeline[T] { + def process(t: T): T +} + +// an example of a covariant type +trait Producer[+T] { + def make: T +} + +// an example of a contravariant type +trait Consumer[-T] { + def take(t: T): Unit +} +``` +{% endtab %} + +{% tab 'Scala 3' for=types-variance-2 %} +```scala +// an example of an invariant type +trait Pipeline[T]: + def process(t: T): T + +// an example of a covariant type +trait Producer[+T]: + def make: T + +// an example of a contravariant type +trait Consumer[-T]: + def take(t: T): Unit +``` +{% endtab %} +{% endtabs %} + +In general there are three modes of variance: + +- **invariant**---the default, written like `Pipeline[T]` +- **covariant**---annotated with a `+`, such as `Producer[+T]` +- **contravariant**---annotated with a `-`, like in `Consumer[-T]` + +We will now go into detail on what this annotation means and why we use it. + +### Invariant Types +By default, types like `Pipeline` are invariant in their type argument (`T` in this case). +This means that types like `Pipeline[Item]`, `Pipeline[Buyable]`, and `Pipeline[Book]` are in _no subtyping relationship_ to each other. + +And rightfully so! Assume the following method that consumes two values of type `Pipeline[Buyable]`, and passes its argument `b` to one of them, based on the price: + +{% tabs types-variance-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-3 %} +```scala +def oneOf( + p1: Pipeline[Buyable], + p2: Pipeline[Buyable], + b: Buyable +): Buyable = { + val b1 = p1.process(b) + val b2 = p2.process(b) + if (b1.price < b2.price) b1 else b2 + } +``` +{% endtab %} + +{% tab 'Scala 3' for=types-variance-3 %} +```scala +def oneOf( + p1: Pipeline[Buyable], + p2: Pipeline[Buyable], + b: Buyable +): Buyable = + val b1 = p1.process(b) + val b2 = p2.process(b) + if b1.price < b2.price then b1 else b2 +``` +{% endtab %} +{% endtabs %} + +Now, recall that we have the following _subtyping relationship_ between our types: + +{% tabs types-variance-4 %} +{% tab 'Scala 2 and 3' %} +```scala +Book <: Buyable <: Item +``` +{% endtab %} +{% endtabs %} + +We cannot pass a `Pipeline[Book]` to the method `oneOf` because in its implementation, we call `p1` and `p2` with a value of type `Buyable`. +A `Pipeline[Book]` expects a `Book`, which can potentially cause a runtime error. + +We cannot pass a `Pipeline[Item]` because calling `process` on it only promises to return an `Item`; however, we are supposed to return a `Buyable`. + +#### Why Invariant? +In fact, type `Pipeline` needs to be invariant since it uses its type parameter `T` _both_ as an argument _and_ as a return type. +For the same reason, some types in the Scala collection library---like `Array` or `Set`---are also _invariant_. + +### Covariant Types +In contrast to `Pipeline`, which is invariant, the type `Producer` is marked as **covariant** by prefixing the type parameter with a `+`. +This is valid, since the type parameter is only used in a _return position_. + +Marking it as covariant means that we can pass (or return) a `Producer[Book]` where a `Producer[Buyable]` is expected. +And in fact, this is sound. The type of `Producer[Buyable].make` only promises to _return_ a `Buyable`. +As a caller of `make`, we will be happy to also accept a `Book`, which is a subtype of `Buyable`---that is, it is _at least_ a `Buyable`. + +This is illustrated by the following example, where the function `makeTwo` expects a `Producer[Buyable]`: + +{% tabs types-variance-5 %} +{% tab 'Scala 2 and 3' %} +```scala +def makeTwo(p: Producer[Buyable]): Int = + p.make.price + p.make.price +``` +{% endtab %} +{% endtabs %} + +It is perfectly fine to pass a producer for books: + +{% tabs types-variance-6 %} +{% tab 'Scala 2 and 3' %} +```scala +val bookProducer: Producer[Book] = ??? +makeTwo(bookProducer) +``` +{% endtab %} +{% endtabs %} + +The call to `price` within `makeTwo` is still valid also for books. + +#### Covariant Types for Immutable Containers +You will encounter covariant types a lot when dealing with immutable containers, like those that can be found in the standard library (such as `List`, `Seq`, `Vector`, etc.). + +For example, `List` and `Vector` are approximately defined as: + +{% tabs types-variance-7 %} +{% tab 'Scala 2 and 3' %} +```scala +class List[+A] ... +class Vector[+A] ... +``` +{% endtab %} +{% endtabs %} + +This way, you can use a `List[Book]` where a `List[Buyable]` is expected. +This also intuitively makes sense: If you are expecting a collection of things that can be bought, it should be fine to give you a collection of books. +They have an additional ISBN method in our example, but you are free to ignore these additional capabilities. + +### Contravariant Types +In contrast to the type `Producer`, which is marked as covariant, the type `Consumer` is marked as **contravariant** by prefixing the type parameter with a `-`. +This is valid, since the type parameter is only used in an _argument position_. + +Marking it as contravariant means that we can pass (or return) a `Consumer[Item]` where a `Consumer[Buyable]` is expected. +That is, we have the subtyping relationship `Consumer[Item] <: Consumer[Buyable]`. +Remember, for type `Producer`, it was the other way around, and we had `Producer[Buyable] <: Producer[Item]`. + +And in fact, this is sound. The method `Consumer[Item].take` accepts an `Item`. +As a caller of `take`, we can also supply a `Buyable`, which will be happily accepted by the `Consumer[Item]` since `Buyable` is a subtype of `Item`---that is, it is _at least_ an `Item`. + +#### Contravariant Types for Consumers +Contravariant types are much less common than covariant types. +As in our example, you can think of them as “consumers.” The most important type that you might come across that is marked contravariant is the one of functions: + +{% tabs types-variance-8 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-8 %} +```scala +trait Function[-A, +B] { + def apply(a: A): B +} +``` +{% endtab %} + +{% tab 'Scala 3' for=types-variance-8 %} +```scala +trait Function[-A, +B]: + def apply(a: A): B +``` +{% endtab %} +{% endtabs %} + +Its argument type `A` is marked as contravariant `A`---it consumes values of type `A`. +In contrast, its result type `B` is marked as covariant---it produces values of type `B`. + +Here are some examples that illustrate the subtyping relationships induced by variance annotations on functions: + +{% tabs types-variance-9 %} +{% tab 'Scala 2 and 3' %} +```scala +val f: Function[Buyable, Buyable] = b => b + +// OK to return a Buyable where a Item is expected +val g: Function[Buyable, Item] = f + +// OK to provide a Book where a Buyable is expected +val h: Function[Book, Buyable] = f +``` +{% endtab %} +{% endtabs %} + +## Summary +In this section, we have encountered three different kinds of variance: + +- **Producers** are typically covariant, and mark their type parameter with `+`. + This also holds for immutable collections. +- **Consumers** are typically contravariant, and mark their type parameter with `-`. +- Types that are **both** producers and consumers have to be invariant, and do not require any marking on their type parameter. + Mutable collections like `Array` fall into this category. diff --git a/_overviews/scala3-book/where-next.md b/_overviews/scala3-book/where-next.md new file mode 100644 index 0000000000..8eed7a163f --- /dev/null +++ b/_overviews/scala3-book/where-next.md @@ -0,0 +1,16 @@ +--- +title: Where To Go Next +type: chapter +description: Where to go next after reading the Scala Book +languages: [zh-cn] +num: 77 +previous-page: scala-for-python-devs +next-page: +--- + +We hope you enjoyed this introduction to the Scala programming language, and we also hope we were able to share some of the beauty of the language. + +As you continue working with Scala, you can find many more details at the +[Guides and Overviews section][overviews] of our website. + +[overviews]: {% link _overviews/index.md %} diff --git a/_overviews/scala3-book/why-scala-3.md b/_overviews/scala3-book/why-scala-3.md new file mode 100644 index 0000000000..639c04691e --- /dev/null +++ b/_overviews/scala3-book/why-scala-3.md @@ -0,0 +1,501 @@ +--- +title: Why Scala 3? +type: chapter +description: This page describes the benefits of the Scala 3 programming language. +languages: [ru, zh-cn] +num: 3 +previous-page: scala-features +next-page: taste-intro +--- + +{% comment %} +TODO: Is “Scala 3 Benefits” a better title? +NOTE: Could mention “grammar” as a way of showing that Scala isn’t a large language; see this slide: https://www.slideshare.net/Odersky/preparing-for-scala-3#13 +{% endcomment %} + +There are many benefits to using Scala, and Scala 3 in particular. +It’s hard to list every benefit of Scala, but a “Top Ten” list might look like this: + +1. Scala embraces a fusion of functional programming (FP) and object-oriented programming (OOP) +2. Scala is statically typed, but often feels like a dynamically typed language +3. Scala’s syntax is concise, but still readable; it’s often referred to as _expressive_ +4. _Implicits_ in Scala 2 were a defining feature, and they have been improved and simplified in Scala 3 +5. Scala integrates seamlessly with Java, so you can create projects with mixed Scala and Java code, and Scala code easily uses the thousands of existing Java libraries +6. Scala can be used on the server, and also in the browser with [Scala.js](https://www.scala-js.org) +7. The Scala standard library has dozens of pre-built, functional methods to save you time, and greatly reduce the need to write custom `for` loops and algorithms +8. “Best practices” are built into Scala, which favors immutability, anonymous functions, higher-order functions, pattern matching, classes that cannot be extended by default, and more +9. The Scala ecosystem offers the most modern FP libraries in the world +10. Strong type system + +## 1) FP/OOP fusion + +More than any other language, Scala supports a fusion of the FP and OOP paradigms. +As Martin Odersky has stated, the essence of Scala is a fusion of functional and object-oriented programming in a typed setting, with: + +- Functions for the logic, and +- Objects for the modularity + +Possibly some of the best examples of modularity are the classes in the standard library. +For instance, a `List` is defined as a class---technically it’s an abstract class---and a new instance is created like this: + +{% tabs list %} +{% tab 'Scala 2 and 3' for=list %} +```scala +val x = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +However, what appears to the programmer to be a simple `List` is actually built from a combination of several specialized types, including traits named `Iterable`, `Seq`, and `LinearSeq`. +Those types are similarly composed of other small, modular units of code. + +In addition to building a type like `List` from a series of modular traits, the `List` API also consists of dozens of other methods, many of which are higher-order functions: + +{% tabs list-methods %} +{% tab 'Scala 2 and 3' for=list-methods %} +```scala +val xs = List(1, 2, 3, 4, 5) + +xs.map(_ + 1) // List(2, 3, 4, 5, 6) +xs.filter(_ < 3) // List(1, 2) +xs.find(_ > 3) // Some(4) +xs.takeWhile(_ < 3) // List(1, 2) +``` +{% endtab %} +{% endtabs %} + +In those examples, the values in the list can’t be modified. +The `List` class is immutable, so all of those methods return new values, as shown by the data in each comment. + +## 2) A dynamic feel + +Scala’s _type inference_ often makes the language feel dynamically typed, even though it’s statically typed. +This is true with variable declaration: + +{% tabs dynamic %} +{% tab 'Scala 2 and 3' for=dynamic %} +```scala +val a = 1 +val b = "Hello, world" +val c = List(1,2,3,4,5) +val stuff = ("fish", 42, 1_234.5) +``` +{% endtab %} +{% endtabs %} + +It’s also true when passing anonymous functions to higher-order functions: + +{% tabs dynamic-hof %} +{% tab 'Scala 2 and 3' for=dynamic-hof %} +```scala +list.filter(_ < 4) +list.map(_ * 2) +list.filter(_ < 4) + .map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +and when defining methods: + +{% tabs dynamic-method %} +{% tab 'Scala 2 and 3' for=dynamic-method %} +```scala +def add(a: Int, b: Int) = a + b +``` +{% endtab %} +{% endtabs %} + +This is more true than ever in Scala 3, such as when using [union types][union-types]: + +{% tabs union %} +{% tab 'Scala 3 Only' for=union %} +```scala +// union type parameter +def help(id: Username | Password) = + val user = id match + case Username(name) => lookupName(name) + case Password(hash) => lookupPassword(hash) + // more code here ... + +// union type value +val b: Password | Username = if (true) name else password +``` +{% endtab %} +{% endtabs %} + +## 3) Concise syntax + +Scala is a low ceremony, “concise but still readable” language. For instance, variable declaration is concise: + +{% tabs concise %} +{% tab 'Scala 2 and 3' for=concise %} +```scala +val a = 1 +val b = "Hello, world" +val c = List(1,2,3) +``` +{% endtab %} +{% endtabs %} + +Creating types like traits, classes, and enumerations are concise: + +{% tabs enum %} +{% tab 'Scala 3 Only' for=enum %} +```scala +trait Tail: + def wagTail(): Unit + def stopTail(): Unit + +enum Topping: + case Cheese, Pepperoni, Sausage, Mushrooms, Onions + +class Dog extends Animal, Tail, Legs, RubberyNose + +case class Person( + firstName: String, + lastName: String, + age: Int +) +``` +{% endtab %} +{% endtabs %} + +Higher-order functions are concise: + +{% tabs list-hof %} +{% tab 'Scala 2 and 3' for=list-hof %} + +```scala +list.filter(_ < 4) +list.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +All of these expressions and many more are concise, and still very readable: what we call _expressive_. + +## 4) Implicits, simplified + +Implicits in Scala 2 were a major distinguishing design feature. +They represented _the_ fundamental way to abstract over context, with a unified paradigm that served a great variety of use cases, among them: + +- Implementing [type classes]({% link _overviews/scala3-book/ca-type-classes.md %}) +- Establishing context +- Dependency injection +- Expressing capabilities + +Since then, other languages have adopted similar concepts, all of which are variants of the core idea of _term inference_: Given a type, the compiler synthesizes a “canonical” term that has that type. + +While implicits were a defining feature in Scala 2, their design has been greatly improved in Scala 3: + +- There’s a single way to define “given” values +- There’s a single way to introduce implicit parameters and arguments +- There’s a separate way to import givens that does not allow them to hide in a sea of normal imports +- There’s a single way to define an implicit conversion, which is clearly marked as such, and does not require special syntax + +Benefits of these changes include: + +- The new design avoids feature interactions and makes the language more consistent +- It makes implicits easier to learn and harder to abuse +- It greatly improves the clarity of the 95% of Scala programs that use implicits +- It has the potential to enable term inference in a principled way that’s also accessible and friendly + +These capabilities are described in detail in other sections, so see the [Contextual Abstraction introduction][contextual], and the section on [`given` and `using` clauses][given] for more details. + +## 5) Seamless Java integration + +Scala/Java interaction is seamless in many ways. +For instance: + +- You can use all of the thousands of Java libraries that are available in your Scala projects +- A Scala `String` is essentially a Java `String`, with additional capabilities added to it +- Scala seamlessly uses the date/time classes in the Java *java.time._* package + +You can also use Java collections classes in Scala, and to give them more functionality, Scala includes methods so you can transform them into Scala collections. + +While almost every interaction is seamless, the [“Interacting with Java” chapter][java] demonstrates how to use some features together better, including how to use: + +- Java collections in Scala +- Java `Optional` in Scala +- Java interfaces in Scala +- Scala collections in Java +- Scala `Option` in Java +- Scala traits in Java +- Scala methods that throw exceptions in Java code +- Scala varargs parameters in Java + +See that chapter for more details on these features. + +## 6) Client & server + +Scala can be used on the server side with terrific frameworks: + +- The [Play Framework](https://www.playframework.com) lets you build highly scalable server-side applications and microservices +- [Akka Actors](https://akka.io) let you use the actor model to greatly simplify distributed and concurrent software applications + +Scala can also be used in the browser with the [Scala.js project](https://www.scala-js.org), which is a type-safe replacement for JavaScript. +The Scala.js ecosystem [has dozens of libraries](https://www.scala-js.org/libraries) to let you use React, Angular, jQuery, and many other JavaScript and Scala libraries in the browser. + +In addition to those tools, the [Scala Native](https://github.com/scala-native/scala-native) project “is an optimizing ahead-of-time compiler and lightweight managed runtime designed specifically for Scala.” It lets you build “systems” style binary executable applications with plain Scala code, and also lets you use lower-level primitives. + +## 7) Standard library methods + +You will rarely ever need to write a custom `for` loop again, because the dozens of pre-built functional methods in the Scala standard library will both save you time, and help make code more consistent across different applications. + +The following examples show some of the built-in collections methods, and there are many in addition to these. +While these all use the `List` class, the same methods work with other collections classes like `Seq`, `Vector`, `LazyList`, `Set`, `Map`, `Array`, and `ArrayBuffer`. + +Here are some examples: + +{% tabs list-more %} +{% tab 'Scala 2 and 3' for=list-more %} +```scala +List.range(1, 3) // List(1, 2) +List.range(start = 1, end = 6, step = 2) // List(1, 3, 5) +List.fill(3)("foo") // List(foo, foo, foo) +List.tabulate(3)(n => n * n) // List(0, 1, 4) +List.tabulate(4)(n => n * n) // List(0, 1, 4, 9) + +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.filter(_ > 100) // List() +a.find(_ > 20) // Some(30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.intersect(List(19,20,21)) // List(20) +a.last // 10 +a.lastOption // Some(10) +a.map(_ * 2) // List(20, 40, 60, 80, 20) +a.slice(2, 4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +a.takeWhile(_ < 30) // List(10, 20) +a.filter(_ < 30).map(_ * 10) // List(100, 200, 100) + +val fruits = List("apple", "pear") +fruits.map(_.toUpperCase) // List(APPLE, PEAR) +fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R) + +val nums = List(10, 5, 8, 1, 7) +nums.sorted // List(1, 5, 7, 8, 10) +nums.sortWith(_ < _) // List(1, 5, 7, 8, 10) +nums.sortWith(_ > _) // List(10, 8, 7, 5, 1) +``` +{% endtab %} +{% endtabs %} + +## 8) Built-in best practices + +Scala idioms encourage best practices in many ways. +For immutability, you’re encouraged to create immutable `val` declarations: + +{% tabs val %} +{% tab 'Scala 2 and 3' for=val %} +```scala +val a = 1 // immutable variable +``` +{% endtab %} +{% endtabs %} + +You’re also encouraged to use immutable collections classes like `List` and `Map`: + +{% tabs list-map %} +{% tab 'Scala 2 and 3' for=list-map %} +```scala +val b = List(1,2,3) // List is immutable +val c = Map(1 -> "one") // Map is immutable +``` +{% endtab %} +{% endtabs %} + +Case classes are primarily intended for use in [domain modeling]({% link _overviews/scala3-book/domain-modeling-intro.md %}), and their parameters are immutable: + +{% tabs case-class %} +{% tab 'Scala 2 and 3' for=case-class %} +```scala +case class Person(name: String) +val p = Person("Michael Scott") +p.name // Michael Scott +p.name = "Joe" // compiler error (reassignment to val name) +``` +{% endtab %} +{% endtabs %} + +As shown in the previous section, Scala collections classes support higher-order functions, and you can pass methods (not shown) and anonymous functions into them: + +{% tabs higher-order %} +{% tab 'Scala 2 and 3' for=higher-order %} +```scala +a.dropWhile(_ < 25) +a.filter(_ < 25) +a.takeWhile(_ < 30) +a.filter(_ < 30).map(_ * 10) +nums.sortWith(_ < _) +nums.sortWith(_ > _) +``` +{% endtab %} +{% endtabs %} + +`match` expressions let you use pattern matching, and they truly are _expressions_ that return values: + +{% tabs match class=tabs-scala-version %} +{% tab 'Scala 2' for=match %} +```scala +val numAsString = i match { + case 1 | 3 | 5 | 7 | 9 => "odd" + case 2 | 4 | 6 | 8 | 10 => "even" + case _ => "too big" +} +``` +{% endtab %} + +{% tab 'Scala 3' for=match %} +```scala +val numAsString = i match + case 1 | 3 | 5 | 7 | 9 => "odd" + case 2 | 4 | 6 | 8 | 10 => "even" + case _ => "too big" +``` +{% endtab %} +{% endtabs %} + +Because they can return values, they’re often used as the body of a method: + +{% tabs match-body class=tabs-scala-version %} +{% tab 'Scala 2' for=match-body %} +```scala +def isTruthy(a: Matchable) = a match { + case 0 | "" => false + case _ => true +} +``` +{% endtab %} + +{% tab 'Scala 3' for=match-body %} +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" => false + case _ => true +``` +{% endtab %} +{% endtabs %} + +## 9) Ecosystem libraries + +Scala libraries for functional programming like [Cats](https://typelevel.org/cats) and [Zio](https://zio.dev) are leading-edge libraries in the FP community. +All of the buzzwords like high-performance, type safe, concurrent, asynchronous, resource-safe, testable, functional, modular, binary-compatible, efficient, effects/effectful, and more, can be said about these libraries. + +We could list hundreds of libraries here, but fortunately they’re all listed in another location: For those details, see the [“Awesome Scala” list](https://github.com/lauris/awesome-scala). + +## 10) Strong type system + +Scala has a strong type system, and it’s been improved even more in Scala 3. +Scala 3’s goals were defined early on, and those related to the type system include: + +- Simplification +- Eliminate inconsistencies +- Safety +- Ergonomics +- Performance + +_Simplification_ comes about through dozens of changed and dropped features. +For instance, the changes from the overloaded `implicit` keyword in Scala 2 to the terms `given` and `using` in Scala 3 make the language more clear, especially for beginning developers. + +_Eliminating inconsistencies_ is related to the dozens of [dropped features][dropped], [changed features][changed], and [added features][added] in Scala 3. +Some of the most important features in this category are: + +- Intersection types +- Union types +- Implicit function types +- Dependent function types +- Trait parameters +- Generic tuples + +{% comment %} +A list of types from the Dotty documentation: + +- Inferred types +- Generics +- Intersection types +- Union types +- Structural types +- Dependent function types +- Type classes +- Opaque types +- Variance +- Algebraic Data Types +- Wildcard arguments in types: ? replacing _ +- Type lambdas +- Match types +- Existential types +- Higher-kinded types +- Singleton types +- Refinement types +- Kind polymorphism +- Abstract type members and path-dependent types +- Dependent function types +- Bounds +{% endcomment %} + +_Safety_ is related to several new and changed features: + +- Multiversal equality +- Restricting implicit conversions +- Null safety +- Safe initialization + +Good examples of _ergonomics_ are enumerations and extension methods, which have been added to Scala 3 in a very readable manner: + +{% tabs extension %} +{% tab 'Scala 3 Only' for=extension %} +```scala +// enumeration +enum Color: + case Red, Green, Blue + +// extension methods +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` +{% endtab %} +{% endtabs %} + +_Performance_ relates to several areas. +One of those is [opaque types][opaque-types]. +In Scala 2 there were several attempts to create solutions to keep with the Domain-driven design (DDD) practice of giving values more meaningful types. +These attempts included: + +- Type aliases +- Value classes +- Case classes + +Unfortunately all of these approaches had weaknesses, as described in the [_Opaque Types_ SIP](https://docs.scala-lang.org/sips/opaque-types.html). +Conversely, the goal of opaque types, as described in that SIP, is that “operations on these wrapper types must not create any extra overhead at runtime while still providing a type safe use at compile time.” + +For more type system details, see the [Reference documentation][reference]. + +## Other great features + +Scala has many great features, and choosing a Top 10 list can be subjective. +Several surveys have shown that different groups of developers love different features. +Hopefully you’ll discover more great Scala features as you use the language. + +[java]: {% link _overviews/scala3-book/interacting-with-java.md %} +[given]: {% link _overviews/scala3-book/ca-context-parameters.md %} +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[reference]: {{ site.scala3ref }} +[dropped]: {{ site.scala3ref }}/dropped-features +[changed]: {{ site.scala3ref }}/changed-features +[added]:{{ site.scala3ref }}/other-new-features + +[union-types]: {% link _overviews/scala3-book/types-union.md %} +[opaque-types]: {% link _overviews/scala3-book/types-opaque-types.md %} diff --git a/_overviews/scala3-contribution/arch-context.md b/_overviews/scala3-contribution/arch-context.md new file mode 100644 index 0000000000..cbf342703f --- /dev/null +++ b/_overviews/scala3-contribution/arch-context.md @@ -0,0 +1,5 @@ +--- +title: Contexts +description: This page describes symbols in the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/architecture/context.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/arch-intro.md b/_overviews/scala3-contribution/arch-intro.md new file mode 100644 index 0000000000..8b306a4e5c --- /dev/null +++ b/_overviews/scala3-contribution/arch-intro.md @@ -0,0 +1,5 @@ +--- +title: High Level Architecture +description: This page introduces the high level architecture of the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/architecture/index.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/arch-lifecycle.md b/_overviews/scala3-contribution/arch-lifecycle.md new file mode 100644 index 0000000000..917e5a7824 --- /dev/null +++ b/_overviews/scala3-contribution/arch-lifecycle.md @@ -0,0 +1,5 @@ +--- +title: Compiler Overview +description: This page describes the lifecycle for the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/architecture/lifecycle.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/arch-phases.md b/_overviews/scala3-contribution/arch-phases.md new file mode 100644 index 0000000000..25db11e6a3 --- /dev/null +++ b/_overviews/scala3-contribution/arch-phases.md @@ -0,0 +1,5 @@ +--- +title: Compiler Phases +description: This page describes the phases for the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/architecture/phases.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/arch-symbols.md b/_overviews/scala3-contribution/arch-symbols.md new file mode 100644 index 0000000000..5ec3408b51 --- /dev/null +++ b/_overviews/scala3-contribution/arch-symbols.md @@ -0,0 +1,5 @@ +--- +title: Symbols +description: This page describes symbols in the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/architecture/symbols.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/arch-time.md b/_overviews/scala3-contribution/arch-time.md new file mode 100644 index 0000000000..a56fed21a5 --- /dev/null +++ b/_overviews/scala3-contribution/arch-time.md @@ -0,0 +1,5 @@ +--- +title: Time in the Compiler +description: This page describes the concepts of time in the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/architecture/time.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/arch-types.md b/_overviews/scala3-contribution/arch-types.md new file mode 100644 index 0000000000..cadcee16f2 --- /dev/null +++ b/_overviews/scala3-contribution/arch-types.md @@ -0,0 +1,5 @@ +--- +title: Compiler Types +description: This page discusses the representation of types in the compiler +redirect_to: https://dotty.epfl.ch/docs/contributing/architecture/types.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/contribution-intro.md b/_overviews/scala3-contribution/contribution-intro.md new file mode 100644 index 0000000000..1708decf17 --- /dev/null +++ b/_overviews/scala3-contribution/contribution-intro.md @@ -0,0 +1,5 @@ +--- +title: Contribute to Scala 3 +description: This page describes the format of the contribution guide for the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/index.html +--- diff --git a/_overviews/scala3-contribution/procedures-areas.md b/_overviews/scala3-contribution/procedures-areas.md new file mode 100644 index 0000000000..74d593b4ac --- /dev/null +++ b/_overviews/scala3-contribution/procedures-areas.md @@ -0,0 +1,5 @@ +--- +title: Common Issue Locations +description: This page describes common areas of issues around the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/workflow/areas.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/procedures-cheatsheet.md b/_overviews/scala3-contribution/procedures-cheatsheet.md new file mode 100644 index 0000000000..fdbf2a2435 --- /dev/null +++ b/_overviews/scala3-contribution/procedures-cheatsheet.md @@ -0,0 +1,5 @@ +--- +title: Cheatsheets +description: This page describes a cheatsheet for working with the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/cheatsheet.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/procedures-checklist.md b/_overviews/scala3-contribution/procedures-checklist.md new file mode 100644 index 0000000000..6908332d2d --- /dev/null +++ b/_overviews/scala3-contribution/procedures-checklist.md @@ -0,0 +1,5 @@ +--- +title: Pull Request Checklist +description: This page describes a checklist before opening a Pull Request to the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/workflow/checklist.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/procedures-debugging.md b/_overviews/scala3-contribution/procedures-debugging.md new file mode 100644 index 0000000000..6fe158614d --- /dev/null +++ b/_overviews/scala3-contribution/procedures-debugging.md @@ -0,0 +1,5 @@ +--- +title: Debugging the Compiler +description: This page describes navigating around the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/workflow/debugging.html +--- diff --git a/_overviews/scala3-contribution/procedures-inspection.md b/_overviews/scala3-contribution/procedures-inspection.md new file mode 100644 index 0000000000..40ec4e2f92 --- /dev/null +++ b/_overviews/scala3-contribution/procedures-inspection.md @@ -0,0 +1,5 @@ +--- +title: How to Inspect Values +description: This page describes inspecting semantic values in the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/workflow/inspection.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/procedures-intro.md b/_overviews/scala3-contribution/procedures-intro.md new file mode 100644 index 0000000000..2cb292caf4 --- /dev/null +++ b/_overviews/scala3-contribution/procedures-intro.md @@ -0,0 +1,5 @@ +--- +title: Contributing to Scala 3 +description: This page introduces the compiler procedures for the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/procedures/index.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/procedures-navigation.md b/_overviews/scala3-contribution/procedures-navigation.md new file mode 100644 index 0000000000..a0e869970c --- /dev/null +++ b/_overviews/scala3-contribution/procedures-navigation.md @@ -0,0 +1,5 @@ +--- +title: Finding the Cause of an Issue +description: This page describes navigating around the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/workflow/cause.html +--- diff --git a/_overviews/scala3-contribution/procedures-reproduce.md b/_overviews/scala3-contribution/procedures-reproduce.md new file mode 100644 index 0000000000..aa31ecedde --- /dev/null +++ b/_overviews/scala3-contribution/procedures-reproduce.md @@ -0,0 +1,5 @@ +--- +title: Reproducing an Issue +description: This page describes reproducing an issue in the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/workflow/reproduce.html +--- \ No newline at end of file diff --git a/_overviews/scala3-contribution/procedures-testing.md b/_overviews/scala3-contribution/procedures-testing.md new file mode 100644 index 0000000000..7c68dc18af --- /dev/null +++ b/_overviews/scala3-contribution/procedures-testing.md @@ -0,0 +1,5 @@ +--- +title: Testing Your Changes +description: This page describes test procedures in the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/workflow/testing.html +--- diff --git a/_overviews/scala3-contribution/start-intro.md b/_overviews/scala3-contribution/start-intro.md new file mode 100644 index 0000000000..48e6100fbd --- /dev/null +++ b/_overviews/scala3-contribution/start-intro.md @@ -0,0 +1,5 @@ +--- +title: Getting Started +description: This page describes the high level architecture for the Scala 3 compiler. +redirect_to: https://dotty.epfl.ch/docs/contributing/getting-started.html +--- diff --git a/_overviews/scala3-macros/best-practices.md b/_overviews/scala3-macros/best-practices.md new file mode 100644 index 0000000000..1122c98620 --- /dev/null +++ b/_overviews/scala3-macros/best-practices.md @@ -0,0 +1,155 @@ +--- +type: chapter +title: Best Practices +num: 8 +--- +## Inline + +### Be careful when inlining for performance +To take the most advantage of the JVM JIT optimisations, you want to avoid generating large methods. + + +## Macros +**Coming soon** + + +## Quoted code + +### Keep quotes readable +* Try to avoid `${...}` with arbitrary expressions inside + * Use `$someExpr` + * Use `${ someExprFrom('localExpr) }` + +To illustrate, consider the following example: +```scala +val sc: StringContext = ... +'{ StringContext(${Varargs(sc.parts.map(Expr(_)))}: _*) } +``` +Instead, we can write the following: + +```scala +val sc: StringContext = ... +val partExprs = sc.parts.map(Expr(_)) +val partsExpr = Varargs(partExprs) +'{ StringContext($partsExpr: _*) } +``` +The contents of the quote are much more clear in the second example. + +### Avoid nested contexts + +Consider the following code: + +```scala +val y: Expr[Int] = ... +def body(x: Expr[Int])(using quotes.Nested) = '{ $x + $y } +'{ (x: Int) => ${ body('x) } } +``` + +Instead, use a normal context and pass all needed expressions. +This has also the advantage of allowing the function to not be defined locally. +```scala +def body(x: Expr[Int], y: Expr[Int])(using Quotes) = + '{ $x + $y } + +val y: Expr[Int] = ... +'{ (x: Int) => ${ body('x, y) } } +``` + +## Quotes Reflect + +For this section, consider the following setup: + +```scala +object Box: + sealed trait Base + case class Leaf(x: Int) extends Base + +// Quotes in contextual scope +val boxTpe : TypeRepr = TypeRepr.of[Box.type] +val baseTpe: TypeRepr = TypeRepr.of[Box.Base] +val baseSym: Symbol = baseTpe.typeSymbol +val leafTpe: TypeRepr = TypeRepr.of[Box.Leaf] +val leafSym: Symbol = leafTpe.typeSymbol +``` + +### Avoid `Symbol.tree` + +On an object `sym: Symbol`, `sym.tree` returns the `Tree` associated with the symbol. +Be careful when using this method, as the tree for a symbol might not be defined. +When the code associated with a symbol is defined at a different time than this access, if the `-Yretain-trees` compilation option is not used, then the `tree` of the symbol will not be available. +Symbols originating from Java code do not have an associated `tree`. + +### Obtaining a `TypeRepr` from a `Symbol` + +In the previous heading, we saw that `Symbol.tree` should be avoided and that therefore you should not use `sym.tree.tpe` on `sym: Symbol`. +Thus, to obtain the `TypeRepr` corresponding to a `Symbol`, it is recommended to use `tpe.memberType` on `tpe: TypeRepr` objects. + +We can obtain the `TypeRepr` of `Leaf` in two ways: + 1. `TypeRepr.of[Box.Leaf]` + 2. `boxTpe.memberType(leafSym)` +(In other words, we request the `TypeRepr` of the member of `Box` whose symbol is equal to the symbol of `leafSym`.) + +While the two approaches are equivalent, the first is only possible if you already know that you are looking for the type `Box.Leaf`. +The second approach allows you to explore an unknown API. + +### Use `Symbol`s to compare definitions + +Read more about Symbols [here][symbol]. + +Symbols allow you to compare definitions using `==`: +```scala +leafSym == baseSym.children.head // Is true +``` + +However, `==` on `TypeRepr`s does not produce the same result: +```scala +boxTpe.memberType(baseSym.children.head) == leafTpe // Is false +``` + +### Obtaining a Symbol for a type + +There is a handy shortcut to get the symbol for the definition of `T`. +Instead of + +```scala +TypeTree.of[T].tpe.typeSymbol +``` +you can use + +```scala +TypeRepr.of[T].typeSymbol +``` + +### Pattern match your way into the API + +Pattern matching is a very ergonomic approach to the API. Always have a look at +the `unapply` method defined in `*Module` objects. + +### Search the contextual scope in your macros + +You can search for given instances using `Implicits.search`. + +For example: + +```scala +def summonOrFail[T: Type]: Expr[T] = + val tpe = TypeRepr.of[T] + Implicits.search(tpe) match + case success: ImplicitSearchSuccess => + val implicitTerm = success.tree + implicitTerm.asExprOf[T] + case failure: ImplicitSearchFailure => + reflect.report.throwError("Could not find an implicit for " + Type.show[T]) +``` + +If you are writing a macro and prefer to handle `Expr`s, `Expr.summon` is a +convenient wrapper around `Implicits.search`: + +```scala +def summonOrFail[T: Type]: Expr[T] = + Expr.summon[T] match + case Some(imp) => imp + case None => reflect.report.throwError("Could not find an implicit for " + Type.show[T]) +``` + +[symbol]: {% link _overviews/scala3-macros/tutorial/reflection.md %} diff --git a/_overviews/scala3-macros/faq.md b/_overviews/scala3-macros/faq.md new file mode 100644 index 0000000000..7a809cdd60 --- /dev/null +++ b/_overviews/scala3-macros/faq.md @@ -0,0 +1,76 @@ +--- +type: chapter +title: FAQ +num: 7 +--- + +## Which should I use `Expr(...)` or `'{...}`? +If you can write your code using `Expr(...)`, you will evaluate more at compile time. +Only use `'{...}` if you really need to evaluate the code later at runtime, usually because it depends on runtime values. + +## Which is better between `Expr(true)` or `'{true}`? +All quotes containing a value of a primitive type is optimised to an `Expr.apply`. +Choose one in your project and stick with a single notation to avoid confusion. + +## How do I get a value out of an `Expr`? +If the expression represents a value, you can use `.value`, `.valueOrAbort` or `Expr.unapply` + +## How can I get the precise type of an `Expr`? +We can get the precise type (`Type`) of an `Expr` using the following pattern match: +```scala +val x: Expr[X] = ... +x match + case '{ $x: t } => + // `x: Expr[X & t]` where `t` is the precise type of `x` +``` + +## How do I summon all types of a tuple type? +If I have a type `(T1, T2, ...)` how do I generate the term for `(summon[T1], summon[T2], ...)` or get the individual expressions with the summoned values? + +Depending on your use case the way you will summon them will vary. +In particular, the code you will need depends on the kind of output you want (`Expr[Tuple]`, `List[Expr[Any]]`, or something else) and how you need errors to be reported. +Here are two examples that should give you the basic skeleton for two different variant of this code. + +```scala + def summonAllInList[T](using Type[T])(using Quotes): List[Expr[Any]] = { + Type.of[T] match + case '[ head *: tail ] => + Expr.summon[head] match + case Some(headExpr) => headExpr :: summonAllInList[tail] + case _ => quotes.reflect.report.throwError(s"Could not summon ${Type.show[head]}") + case '[ EmptyTuple ] => Nil + case _ => quotes.reflect.report.throwError(s"Could not `summonAllInList` of tuple with unknown size: ${Type.show[T]}") + } +``` + +```scala + def summonAll[T](using Type[T])(using Quotes): Option[Expr[Tuple]]] = { + Type.of[T] match + case '[ head *: tail ] => + for headExpr <- Expr.summon[head] + tailExpr <- summonAll[tail] + yield '{ headExpr *: tailExpr } + case '[ EmptyTuple ] => Some('{ EmptyTuple }) + case _ => None + } +``` + +## How do I summon an expression for statically unknown types? + +You can summon an expression from either a `TypeRepr` or a `Type` as shown below. + +If you have a `TypeRepr` use: +```scala +val tpe: TypeRepr = ... +Implicits.search(tpe) match + case result: ImplicitSearchSuccess => result.tree + case _ => +``` + +Instead, if you have a `Type[_]` use: +```scala +val tpe: Type[_] = ... +tpe match + // (1) Use `a` as the name of the unknown type and (2) bring a given `Type[a]` into scope + case '[a] => Expr.summon[a] +``` diff --git a/_overviews/scala3-macros/other-resources.md b/_overviews/scala3-macros/other-resources.md new file mode 100644 index 0000000000..a50aefa23e --- /dev/null +++ b/_overviews/scala3-macros/other-resources.md @@ -0,0 +1,27 @@ +--- +type: chapter +title: Other Resources +num: 9 +--- + +## Scala 2 migration + * [Scala 2 migration and cross-compilation][migration] + * [Migration status][migration-status] + +## Dotty documentation +- [Dotty Documentation]({{ site.scala3ref }}/metaprogramming) +- [Macros: The Plan For Scala 3](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html) +- [Examples](https://github.com/lampepfl/dotty-macro-examples) - a repository with small, self-contained examples of various tasks done with Dotty macros. + +## Talks +* [Scala Days - Metaprogramming in Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) + +## Projects and examples +* [dotty-macro-examples](https://github.com/lampepfl/dotty-macro-examples) +* [XML Interpolator](https://github.com/dotty-staging/xml-interpolator/tree/master) +* [Shapeless 3](https://github.com/dotty-staging/shapeless/tree/shapeless-3) +* *More Coming soon* + + +[migration]: {% link _overviews/scala3-migration/tutorial-macro-cross-building.md %} +[migration-status]: https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html#macro-libraries diff --git a/_overviews/scala3-macros/tutorial/compiletime.md b/_overviews/scala3-macros/tutorial/compiletime.md new file mode 100644 index 0000000000..0204efa4c4 --- /dev/null +++ b/_overviews/scala3-macros/tutorial/compiletime.md @@ -0,0 +1,75 @@ +--- +type: section +title: Scala Compile-time Operations +num: 3 + +previous-page: inline +next-page: macros +--- + +Operations in [scala.compiletime][compiletime-api] are metaprogramming operations that can be used within an `inline` method. +These operation do cover some common use cases of macros without you needing to define a macro. + +## Reporting + +It is possible to emit error messages when inlining code. + +```scala +inline def doSomething(inline mode: Boolean): Unit = + if mode then ... + else if !mode then ... + else error("Mode must be a known value") + +doSomething(true) +doSomething(false) +val bool: Boolean = ... +doSomething(bool) // error: Mode must be a known value +``` + +If `error` is called outside an inline method, the error will be emitted when compiling that call. +If the `error` is written inside an inline method, the error will be emitted only if, after inlining the call, it is not removed as part of a dead branch. +In the previous example, if the value of `mode` were known at compile time, we would only keep one of the first two branches. + +If we want to include part of the source code of the arguments in the error message, we can use the `codeOf` method. + +```scala +inline def doSomething(inline mode: Boolean): Unit = + if mode then ... + else if !mode then ... + else error("Mode must be a known value but got: " + codeOf(mode)) + +val bool: Boolean = ... +doSomething(bool) // error: Mode must be a known value but got: bool +``` + +## Summoning + +There are two ways to summon values in inline methods, the first is with a `using` parameter and the second is with one of `summonInline`, `summonAll` or `summonFrom`. +`using` will summon the value at call site before inlining as if the method was not `inline`. +On the other hand, `summonInline` will summon after inlining if the call is not eliminated from a dead branch. +`summonAll` provides a way to summon multiple values at the same time from a tuple type. +`summonFrom` provides a way to try several implicit searches. + +## Values +* `constValue`, `constValueOpt` and `constValueTuple` +* `S` +*Coming soon* + +## Testing +* `testing.typeChecks` and `testing.typeCheckErrors` + +## Assertions +* `byName` + +*Coming soon* + +## Inline Matching +* `erasedValue` + +*Coming soon* + +## Ops (scala.compiletime.ops) +*Coming soon* + + +[compiletime-api]: https://scala-lang.org/api/3.x/scala/compiletime.html diff --git a/_overviews/scala3-macros/tutorial/index.md b/_overviews/scala3-macros/tutorial/index.md new file mode 100644 index 0000000000..e70c39ef45 --- /dev/null +++ b/_overviews/scala3-macros/tutorial/index.md @@ -0,0 +1,36 @@ +--- +type: chapter +title: Tutorial +description: A tutorial to cover all the features involved in writing macros in Scala 3. +num: 1 + +next-page: inline +--- + +This tutorial covers all the features involved in writing macros in Scala 3. + +The metaprogramming API of Scala 3 is designed in layers to gradually +support different levels of use-cases. Each successive layer exposes additional +abstractions and offers more fine-grained control. + +- As a starting point, the new [`inline` feature][inline] allows some abstractions (values and methods) to be marked as statically reducible. + It provides the entry point for macros and other metaprogramming utilities. + +- [Compile-time operations][compiletime] offer additional metaprogramming utilities that can be used within `inline` methods (for example to improve error reporting), without having to define a macro. + +- Starting from `inline` methods, [macros][macros] are programs that explicitly operate on programs. + + - Macros can be defined in terms of a _high-level_ API of [quoted expressions][quotes], that admits simple construction and deconstruction of programs expressions. + + - Macros can also be defined in terms of a more _low-level_ API of [Reflection][reflection], that allows detailed inspection of programs. + +> The tutorial uses the API of Scala 3.0.0-RC3. The API had many small changes in this revision. + +> 🚧 We are still in the process of writing the tutorial. You can [help us][contributing] 🚧 + +[contributing]: {% link scala3/contribute-to-docs.md %} +[compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[macros]: {% link _overviews/scala3-macros/tutorial/macros.md %} +[quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %} diff --git a/_overviews/scala3-macros/tutorial/inline.md b/_overviews/scala3-macros/tutorial/inline.md new file mode 100644 index 0000000000..0fe620f162 --- /dev/null +++ b/_overviews/scala3-macros/tutorial/inline.md @@ -0,0 +1,512 @@ +--- +type: section +title: Inline +num: 2 + +previous-page: index +next-page: compiletime +--- + +Inlining is a common compile-time metaprogramming technique, typically used to achieve performance optimizations. As we will see, in Scala 3, the concept of inlining provides us with an entrypoint to programming with macros. + +1. It introduces inline as a [soft keyword][soft-modifier]. +2. It guarantees that inlining actually happens instead of being best-effort. +3. It introduces operations that are guaranteed to evaluate at compile-time. + +## Inline Constants + +The simplest form of inlining is to inline constants in programs: + + +```scala +inline val pi = 3.141592653589793 +inline val pie = "🥧" +``` + +The usage of the keyword `inline` in the _inline value definitions_ above *guarantees* that all references to `pi` and `pie` are inlined: + +```scala +val pi2 = pi + pi // val pi2 = 6.283185307179586 +val pie2 = pie + pie // val pie2 = "🥧🥧" +``` + +In the code above, the references `pi` and `pie` are inlined. +Then an optimization called "constant folding" is applied by the compiler, which computes the resulting value `pi2` and `pie2` at _compile-time_. + +> ##### Inline (Scala 3) vs. final (Scala 2) +> In Scala 2, we would have used the modifier `final` in the definition that is without a return type: +> +> ```scala +> final val pi = 3.141592653589793 +> final val pie = "🥧" +> ``` +> +> The `final` modifier will ensure that `pi` and `pie` will take a _literal type_. +> Then the constant propagation optimization in the compiler can perform inlining for such definitions. +> However, this form of constant propagation is _best-effort_ and not guaranteed. +> Scala 3.0 also supports `final val`-inlining as _best-effort_ inlining for migration purposes. + +Currently, only constant expressions may appear on the right-hand side of an inline value definition. +Therefore, the following code is invalid, though the compiler knows that the right-hand side is a compile-time constant value: + +```Scala +val pi = 3.141592653589793 +inline val pi2 = pi + pi // error +``` +Note that by defining `inline val pi`, the addition can be computed at compile time. +This resolves the above error and `pi2` will receive the literal type `6.283185307179586d`. + +## Inline Methods + +We can also use the modifier `inline` to define a method that should be inlined at the call-site: + +```scala +inline def logged[T](level: Int, message: => String)(inline op: T): T = + println(s"[$level]Computing $message") + val res = op + println(s"[$level]Result of $message: $res") + res +``` + +When an inline method like `logged` is called, its body will be expanded at the call-site at compile time! +That is, the call to `logged` will be replaced by the body of the method. +The provided arguments are statically substituted for the parameters of `logged`, correspondingly. +Therefore, the compiler inlines the following call + +```scala +logged(logLevel, getMessage()) { + computeSomething() +} +``` + +and rewrites it to: + +```Scala +val level = logLevel +def message = getMessage() + +println(s"[$level]Computing $message") +val res = computeSomething() +println(s"[$level]Result of $message: $res") +res +``` + +### Semantics of Inline Methods +Our example method `logged` uses three different kinds of parameters, illustrating +that inlining handles those parameters differently: + +1. __By-value parameters__. The compiler generates a `val` binding for *by-value* parameters. This way, the argument expression is evaluated only once before the method body is reduced. + + This can be seen in the parameter `level` from the example. + In some cases, when the arguments are pure constant values, the binding is omitted and the value is inlined directly. + +2. __By-Name parameters__. The compiler generates a `def` binding for *by-name* parameters. This way, the argument expression is evaluated every time it is used, but the code is shared. + + This can be seen in the parameter `message` from the example. + +3. __Inline parameters__. Inline parameters do not create bindings and are simply inlined. This way, their code is duplicated everywhere they are used. + + This can be seen in the parameter `op` from the example. + +The way the different parameters are translated guarantees that inlining a call **will not change** its semantics. +This implies that the initial elaboration (overloading resolution, implicit search, ...), performed while typing the body of the inline method, will not change when inlined. + +For example, consider the following code: + +```scala +class Logger: + def log(x: Any): Unit = println(x) + +class RefinedLogger extends Logger: + override def log(x: Any): Unit = println("Any: " + x) + def log(x: String): Unit = println("String: " + x) + +inline def logged[T](logger: Logger, x: T): Unit = + logger.log(x) +``` + +The separate type checking of `logger.log(x)` will resolve the call to the method `Logger.log` which takes an argument of the type `Any`. +Now, given the following code: + +```scala +logged(new RefinedLogger, "✔️") +``` + +It expands to: + +``` +val logger = new RefinedLogger +val x = "✔️" +logger.log(x) +``` +Even though now we know that `x` is a `String`, the call `logger.log(x)` still resolves to the method `Logger.log` which takes an argument of the type `Any`. Note that because of late-binding, the actual method called at runtime will be the overridden method `RefinedLogger.log`. + +> ##### Inlining preserves semantics +> Regardless of whether `logged` is defined as a `def` or `inline def`, it performs the same operations with only some differences in performance. + +### Inline Parameters + +One important application of inlining is to enable constant folding optimisation across method boundaries. +Inline parameters do not create bindings and their code is duplicated everywhere they are used. + +```scala +inline def perimeter(inline radius: Double): Double = + 2.0 * pi * radius +``` +In the above example, we expect that if the `radius` is statically known then the whole computation can be performed at compile-time. +The following call + +```scala +perimeter(5.0) +``` + +is rewritten to: + +```Scala +2.0 * pi * 5.0 +``` + +Then `pi` is inlined (we assume the `inline val` definition from the start): + +```Scala +2.0 * 3.141592653589793 * 5.0 +``` + +Finally, it is constant folded to + +``` +31.4159265359 +``` + +> ##### Inline parameters should be used only once +> We need to be careful when using an inline parameter **more than once**. +> Consider the following code: +> +> ```scala +> inline def printPerimeter(inline radius: Double): Double = +> println(s"Perimeter (r = $radius) = ${perimeter(radius)}") +> ``` +> It works perfectly fine when a constant or reference to a val is passed to it. +> ```scala +> printPerimeter(5.0) +> // inlined as +> println(s"Perimeter (r = ${5.0}) = ${31.4159265359}") +> ``` +> +> But if a larger expression (possibly with side-effects) is passed, we might accidentally duplicate work. +> +> ```scala +> printPerimeter(longComputation()) +> // inlined as +> println(s"Perimeter (r = ${longComputation()}) = ${6.283185307179586 * longComputation()}") +> ``` + +A useful application of inline parameters is to avoid the creation of _closures_, incurred by the use of by-name parameters. + +```scala +inline def assert1(cond: Boolean, msg: => String) = + if !cond then + throw new Exception(msg) + +assert1(x, "error1") +// is inlined as +val cond = x +def msg = "error1" +if !cond then + throw new Exception(msg) +``` +In the above example, we can see that the use of a by-name parameter leads to a local definition `msg`, which allocates a closure before the condition is checked. + +If we use an inline parameter instead, we can guarantee that the condition is checked before any of the code that handles the exception is reached. +In the case of an assertion, this code should never be reached. +```scala +inline def assert2(cond: Boolean, inline msg: String) = + if !cond then + throw new Exception(msg) + +assert2(x, "error2") +// is inlined as +val cond = x +if !cond then + throw new Exception("error2") +``` + +### Inline Conditionals +If the condition of an `if` is a known constant (`true` or `false`), possibly after inlining and constant folding, then the conditional is partially evaluated and only one branch will be kept. + +For example, the following power method contains some `if` that will potentially unroll the recursion and remove all method calls. + +```scala +inline def power(x: Double, inline n: Int): Double = + if (n == 0) 1.0 + else if (n % 2 == 1) x * power(x, n - 1) + else power(x * x, n / 2) +``` +Calling `power` with statically known constants results in the following code: + ```scala + power(2, 2) + // first inlines as + val x = 2 + if (2 == 0) 1.0 // dead branch + else if (2 % 2 == 1) x * power(x, 2 - 1) // dead branch + else power(x * x, 2 / 2) + // partially evaluated to + val x = 2 + power(x * x, 1) + ``` + +{::options parse_block_html="true" /} +
            + See rest of inlining steps + + +```scala +// then inlined as +val x = 2 +val x2 = x * x +if (1 == 0) 1.0 // dead branch +else if (1 % 2 == 1) x2 * power(x2, 1 - 1) +else power(x2 * x2, 1 / 2) // dead branch +// partially evaluated to +val x = 2 +val x2 = x * x +x2 * power(x2, 0) +// then inlined as +val x = 2 +val x2 = x * x +x2 * { + if (0 == 0) 1.0 + else if (0 % 2 == 1) x2 * power(x2, 0 - 1) // dead branch + else power(x2 * x2, 0 / 2) // dead branch +} +// partially evaluated to +val x = 2 +val x2 = x * x +x2 * 1.0 +``` +
            + +{::options parse_block_html="false" /} + +In contrast, let us imagine we do not know the value of `n`: + +```scala +power(2, unknownNumber) +``` +Driven by the inline annotation on the parameter, the compiler will try to unroll the recursion. +But without any success, since the parameter is not statically known. + +{::options parse_block_html="true" /} +
            + See inlining steps + + +```scala +// first inlines as +val x = 2 +if (unknownNumber == 0) 1.0 +else if (unknownNumber % 2 == 1) x * power(x, unknownNumber - 1) +else power(x * x, unknownNumber / 2) +// then inlined as +val x = 2 +if (unknownNumber == 0) 1.0 +else if (unknownNumber % 2 == 1) x * { + if (unknownNumber - 1 == 0) 1.0 + else if ((unknownNumber - 1) % 2 == 1) x2 * power(x2, unknownNumber - 1 - 1) + else power(x2 * x2, (unknownNumber - 1) / 2) +} +else { + val x2 = x * x + if (unknownNumber / 2 == 0) 1.0 + else if ((unknownNumber / 2) % 2 == 1) x2 * power(x2, unknownNumber / 2 - 1) + else power(x2 * x2, unknownNumber / 2 / 2) +} +// Oops this will never finish compiling +... +``` +
            +{::options parse_block_html="false" /} + +To guarantee that the branching can indeed be performed at compile-time, we can use the `inline if` variant of `if`. +Annotating a conditional with `inline` will guarantee that the conditional can be reduced at compile-time and emits an error if the condition is not a statically known constant. + +```scala +inline def power(x: Double, inline n: Int): Double = + inline if (n == 0) 1.0 + else inline if (n % 2 == 1) x * power(x, n - 1) + else power(x * x, n / 2) +``` + +```scala +power(2, 2) // Ok +power(2, unknownNumber) // error +``` + +We will come back to this example later and see how we can get more control on how code is generated. + + +### Inline Method Overriding + +To ensure the correct behavior of combining the static feature of `inline def` with the dynamic feature of interfaces and overriding, some restrictions have to be imposed. + +#### Effectively final +Firstly, all inline methods are _effectively final_. +This ensures that the overload resolution at compile-time behaves the same as the one at runtime. + +#### Signature preservation +Secondly, overrides must have the _exact same signature_ as the overridden method including the inline parameters. +This ensures that the call semantics are the same for both methods. + +#### Retained inline methods +It is possible to implement or override a normal method with an inline method. + +Consider the following example: + +```scala +trait Logger: + def log(x: Any): Unit + +class PrintLogger extends Logger: + inline def log(x: Any): Unit = println(x) +``` +However, calling the `log` method directly on `PrintLogger` will inline the code, while calling it on `Logger` will not. +To also admit the latter, the code of `log` must exist at runtime. +We call this a _retained inline_ method. + +For any non-retained inline `def` or `val` the code can always be fully inlined at all call sites. +Hence, those methods will not be needed at runtime and can be erased from the bytecode. +However, retained inline methods must be compatible with the case that they are not inlined. +In particular, retained inline methods cannot take any inline parameters. +Furthermore, an `inline if` (as in the `power` example) will not work, since the `if` cannot be constant folded in the retained case. +Other examples involve metaprogramming constructs that only have meaning when inlined. + +#### Abstract inline methods +It is also possible to create _abstract inline definitions_. + +```scala +trait InlineLogger: + inline def log(inline x: Any): Unit + +class PrintLogger extends InlineLogger: + inline def log(inline x: Any): Unit = println(x) +``` + +This forces the implementation of `log` to be an inline method and also allows `inline` parameters. +Counterintuitively, the `log` on the interface `InlineLogger` cannot be directly called. The method implementation is not statically known and we thus do not know what to inline. +Calling an abstract inline method thus results in an error. +The usefulness of abstract inline methods becomes apparent when used in another inline method: + +```scala +inline def logged(logger: InlineLogger, x: Any) = + logger.log(x) +``` +Let us assume a call to `logged` on a concrete instance of `PrintLogger`: +```scala +logged(new PrintLogger, "🥧") +// inlined as +val logger = new PrintLogger +val x = "🥧" +logger.log(x) +``` +After inlining, the call to `log` is de-virtualized and known to be on `PrintLogger`. +Therefore also the code of `log` can be inlined. + +#### Summary of inline methods +* All `inline` methods are final. +* Abstract `inline` methods can only be implemented by inline methods. +* If an inline method overrides/implements a normal method then it must be retained and retained methods cannot have inline parameters. +* Abstract `inline` methods cannot be called directly (except in inline code). + +## Transparent Inline Methods +Transparent inlines are a simple, yet powerful, extension to `inline` methods and unlock many metaprogramming usecases. +Calls to transparents allow for an inline piece of code to refine the return type based on the precise type of the inlined expression. +In Scala 2 parlance, transparents capture the essence of _whitebox macros_. + + +```scala +transparent inline def default(inline name: String): Any = + inline if name == "Int" then 0 + else inline if name == "String" then "" + else ... +``` + +```scala +val n0: Int = default("Int") +val s0: String = default("String") +``` + +Note that even if the return type of `default` is `Any`, the first call is typed as an `Int` and the second as a `String`. +The return type represents the upper bound of the type within the inlined term. +We could also have been more precise and have written instead +```scala +transparent inline def default(inline name: String): 0 | "" = ... +``` +While in this example it seems the return type is not necessary, it is important when the inline method is recursive. +There it should be precise enough for the recursion to type but will get more precise after inlining. + +> ##### Transparents affect binary compatibility +> It is important to note that changing the body of a `transparent inline def` will change how the call site is typed. +> This implies that the body plays a part in the binary and source compatibility of this interface. + + +## Compiletime Operations + +We also provide some operations that evaluate at compiletime. + +### Inline Matches +Like inline `if`, inline matches guarantee that the pattern matching can be statically reduced at compile time and only one branch is kept. + +In the following example, the scrutinee, `x`, is an inline parameter that we can pattern match on at compile time. + +```scala +inline def half(x: Any): Any = + inline x match + case x: Int => x / 2 + case x: String => x.substring(0, x.length / 2) + +half(6) +// expands to: +// val x = 6 +// x / 2 + +half("hello world") +// expands to: +// val x = "hello world" +// x.substring(0, x.length / 2) +``` +This illustrates that inline matches provide a way to match on the static type of some expression. +As we match on the _static_ type of an expression, the following code would fail to compile. + +```scala +val n: Any = 3 +half(n) // error: n is not statically known to be an Int or a Double +``` +Notably, The value `n` is not marked as `inline` and in consequence at compile time +there is not enough information about the scrutinee to decide which branch to take. + +### scala.compiletime +The package `scala.compiletime` provides useful metaprogramming abstractions that can be used within `inline` methods to provide custom semantics. + +## Macros +Inlining is also the core mechanism used to write macros. +Macros provide a way to control the code generation and analysis after the call is inlined. + + +```scala +inline def power(x: Double, inline n: Int) = + ${ powerCode('x, 'n) } + +def powerCode(x: Expr[Double], n: Expr[Int])(using Quotes): Expr[Double] = ... +``` + + +[soft-modifier]: {{ site.scala3ref }}/soft-modifier.html + +[contributing]: {% link scala3/contribute-to-docs.md %} +[best-practices]: {% link _overviews/scala3-macros/best-practices.md %} +[compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[faq]: {% link _overviews/scala3-macros/faq.md %} +[inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[macros]: {% link _overviews/scala3-macros/tutorial/macros.md %} +[quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[tasty]: {% link _overviews/scala3-macros/tutorial/reflection.md %} diff --git a/_overviews/scala3-macros/tutorial/macros.md b/_overviews/scala3-macros/tutorial/macros.md new file mode 100644 index 0000000000..1c90c15928 --- /dev/null +++ b/_overviews/scala3-macros/tutorial/macros.md @@ -0,0 +1,304 @@ +--- +type: section +title: Scala 3 Macros +num: 4 + +previous-page: compiletime +next-page: quotes +--- + +[Inline methods][inline] provide us with a elegant technique for metaprogramming by performing some operations at compile time. +However, sometimes inlining is not enough and we need more powerful ways to analyze and synthesize programs at compile time. +Macros enable us to do exactly this: treat **programs as data** and manipulate them. + + +## Macros Treat Programs as Values +With a macro, we can treat programs as values, which allows us to analyze and generate them at compile time. + +A Scala expression with type `T` is represented by an instance of the type `scala.quoted.Expr[T]`. + +We will dig into the details of the type `Expr[T]`, as well as the different ways of analyzing and constructing instances, when talking about [Quoted Code][quotes] and [Reflection][tasty]. +For now, it suffices to know that macros are metaprograms that manipulate expressions of type `Expr[T]`. + +The following macro implementation prints the expression of the provided argument at compile-time in the standard output of the compiler process: +```scala +import scala.quoted.* // imports Quotes, Expr + +def inspectCode(x: Expr[Any])(using Quotes): Expr[Any] = + println(x.show) + x +``` +After printing the argument expression, we return the original argument as a Scala expression of type `Expr[Any]`. + +As foreshadowed in the section on [Inline][inline], inline methods provide the entry point for macro definitions: + +```scala +inline def inspect(inline x: Any): Any = ${ inspectCode('x) } +``` +All macros are defined with an `inline def`. +The implementation of this entry point always has the same shape: + +- they only contain a single [splice][quotes] `${ ... }` +- the splice contains a single call to the method that implements the macro (for example `inspectCode`). +- the call to the macro implementation receives the _quoted_ parameters (that is `'x` instead of `x`) and a contextual `Quotes`. + +We will dig deeper into these concepts later in this and the following sections. + +Calling our `inspect` macro `inspect(sys error "abort")` prints a string representation of the argument expression at compile time: +``` +scala.sys.error("abort") +``` + + +### Macros and Type Parameters + +If the macro has type parameters, the implementation will also need to know about them. +Just like `scala.quoted.Expr[T]` represents a Scala expression of type `T`, we use `scala.quoted.Type[T]` to represent the Scala type `T`. + +```scala +inline def logged[T](inline x: T): T = ${ loggedCode('x) } + +def loggedCode[T](x: Expr[T])(using Type[T], Quotes): Expr[T] = ... +``` +Both the instance of `Type[T]` and the contextual `Quotes` are automatically provided by the splice in the corresponding inline method (that is, `logged`) and can be used by the macro implementation. + + +### Defining and Using Macros + +A key difference between inlining and macros is the way they are evaluated. +Inlining works by rewriting code and performing optimisations based on rules the compiler knows. +On the other hand, a macro executes user-written code that generates the code that the macro expands to. + +Technically, compiling the inlined code `${ inspectCode('x) }` calls the method `inspectCode` _at compile time_ (through Java reflection), and the method `inspectCode` then executes as normal code. + +To be able to execute `inspectCode`, we need to compile its source code first. +As a technical consequence, we cannot define and use a macro in the **same class/file**. +However, it is possible to have the macro definition and its call in the **same project** as long as the implementation of the macro can be compiled first. + +> ##### Suspended Files +> To allow defining and using macros in the same project, only those calls to macros that have already been compiled are expanded. +> For all other (unknown) macro calls, the compilation of the file is _suspended_. +> Suspended files are only compiled after all non suspended files have been successfully compiled. +> In some cases, you will have _cyclic dependencies_ that will block the completion of the compilation. +> To get more information on which files are suspended you can use the `-Xprint-suspension` compiler flag. + + +### Example: Statically Evaluating `power` with Macros + +Let us recall our definition of `power` from the section on [Inline][inline] that specialized the computation of `xⁿ` for statically known values of `n`. +```scala +inline def power(x: Double, inline n: Int): Double = + inline if n == 0 then 1.0 + else inline if n % 2 == 1 then x * power(x, n - 1) + else power(x * x, n / 2) +``` +In the remainder of this section, we will define a macro that computes `xⁿ` for a statically known values `x` and `n`. +While this is also possible purely with `inline`, implementing it with macros will illustrate a few things. + +```scala +inline def power(inline x: Double, inline n: Int) = + ${ powerCode('x, 'n) } + +def powerCode( + x: Expr[Double], + n: Expr[Int] +)(using Quotes): Expr[Double] = ... +``` + +## Simple Expressions + +We could implement `powerCode` as follows: +```scala +def pow(x: Double, n: Int): Double = + if n == 0 then 1 else x * pow(x, n - 1) + +def powerCode( + x: Expr[Double], + n: Expr[Int] +)(using Quotes): Expr[Double] = + val value: Double = pow(x.valueOrAbort, n.valueOrAbort) + Expr(value) +``` +Here, the `pow` operation is a simple Scala function that computes the value of `xⁿ`. +The interesting part is how we create and look into the `Expr`s. + + +### Creating Expression From Values + +Let's first look at `Expr.apply(value)`. Given a value of type `T`, this call will return an expression containing the code representing the given value (that is, of type `Expr[T]`). +The argument value to `Expr` is computed at compile-time, at runtime we only need to instantiate this value. + +Creating expressions from values works for all _primitive types_, _tuples_ of any arity, `Class`, `Array`, `Seq`, `Set`, `List`, `Map`, `Option`, `Either`, `BigInt`, `BigDecimal`, `StringContext`. +Other types can also work if a `ToExpr` is implemented for it, we will [see this later][quotes]. + + +### Extracting Values from Expressions + +The second method we use in the implementation of `powerCode` is `Expr[T].valueOrAbort`, which has an effect opposite to `Expr.apply`. +It attempts to extract a value of type `T` from an expression of type `Expr[T]`. +This can only succeed, if the expression directly contains the code of a value, otherwise, it will throw an exception that stops the macro expansion and reports that the expression did not correspond to a value. + +Instead of `valueOrAbort`, we could also use the `value` operation, which will return an `Option`. +This way we can report the error with a custom error message. + +#### Reporting Custom Error Messages + +The contextual `Quotes` parameter provides a `report` object that we can use to report a custom error message. +Within a macro implementation method, you can access the contextual `Quotes` parameter with the `quotes` method +(imported with `import scala.quoted.*`), then import the `report` object by `import quotes.reflect.report`. + +#### Providing the Custom Error + +We will provide the custom error message by calling `errorAndAbort` on the `report` object as follows: +```scala +def powerCode( + x: Expr[Double], + n: Expr[Int] +)(using Quotes): Expr[Double] = + import quotes.reflect.report + (x.value, n.value) match + case (Some(base), Some(exponent)) => + val value: Double = pow(base, exponent) + Expr(value) + case (Some(_), _) => + report.errorAndAbort("Expected a known value for the exponent, but was " + n.show, n) + case _ => + report.errorAndAbort("Expected a known value for the base, but was " + x.show, x) +``` + +Alternatively, we can also use the `Expr.unapply` extractor + +```scala + ... + (x, n) match + case (Expr(base), Expr(exponent)) => + val value: Double = pow(base, exponent) + Expr(value) + case (Expr(_), _) => ... + case _ => ... +``` +The operations `value`, `valueOrAbort`, and `Expr.unapply` will work for all _primitive types_, _tuples_ of any arity, `Option`, `Seq`, `Set`, `Map`, `Either` and `StringContext`. +Other types can also work if an `FromExpr` is implemented for it, we will [see this later][quotes]. + + +### Showing Expressions + +In the implementation of `inspectCode`, we have already seen how to convert expressions to the string representation of their _source code_ using the `.show` method. +This can be useful to perform debugging on macro implementations: + + +```scala +def debugPowerCode( + x: Expr[Double], + n: Expr[Int] +)(using Quotes): Expr[Double] = + println( + s"powerCode \n" + + s" x := ${x.show}\n" + + s" n := ${n.show}") + val code = powerCode(x, n) + println(s" code := ${code.show}") + code +``` + + +### Working with Varargs + +Varargs in Scala are represented with `Seq`, hence when we write a macro with a _vararg_, it will be passed as an `Expr[Seq[T]]`. +It is possible to recover each individual argument (of type `Expr[T]`) using the `scala.quoted.Varargs` extractor. + +```scala +import scala.quoted.* // imports `Varargs`, `Quotes`, etc. + +inline def sumNow(inline nums: Int*): Int = + ${ sumCode('nums) } + +def sumCode(nums: Expr[Seq[Int]])(using Quotes): Expr[Int] = + import quotes.reflect.report + nums match + case Varargs(numberExprs) => // numberExprs: Seq[Expr[Int]] + val numbers: Seq[Int] = numberExprs.map(_.valueOrAbort) + Expr(numbers.sum) + case _ => report.errorAndAbort( + "Expected explicit varargs sequence. " + + "Notation `args*` is not supported.", nums) +``` + +The extractor will match a call to `sumNow(1, 2, 3)` and extract a `Seq[Expr[Int]]` containing the code of each parameter. +But, if we try to match the argument of the call `sumNow(nums*)`, the extractor will not match. + +`Varargs` can also be used as a constructor. `Varargs(Expr(1), Expr(2), Expr(3))` will return an `Expr[Seq[Int]]`. +We will see how this can be useful later. + + +## Complex Expressions +So far, we have only seen how to construct and destruct expressions that correspond to simple values. +In order to work with more complex expressions, Scala 3 offers different metaprogramming facilities ranging from + +- additional constructors like `Expr.apply`, +- over [quoted pattern matching][quotes], +- to a full [reflection API][tasty]; + +each increasing in complexity and potentially losing safety guarantees. +It is generally recommended to prefer simple APIs over more advanced ones. +In the remainder of this section, we introduce some more additional constructors and destructors, +while subsequent chapters introduce the more advanced APIs. + +### Collections + +We have seen how to convert a `List[Int]` into an `Expr[List[Int]]` using `Expr.apply`. +How about converting a `List[Expr[Int]]` into an `Expr[List[Int]]`? +We mentioned that `Varargs.apply` can do this for sequences; likewise, for other collection types, corresponding methods are available: + +* `Expr.ofList`: Transform a `List[Expr[T]]` into `Expr[List[T]]` +* `Expr.ofSeq`: Transform a `Seq[Expr[T]]` into `Expr[Seq[T]]` (just like `Varargs`) +* `Expr.ofTupleFromSeq`: Transform a `Seq[Expr[T]]` into `Expr[Tuple]` +* `Expr.ofTuple`: Transform a `(Expr[T1], ..., Expr[Tn])` into `Expr[(T1, ..., Tn)]` + +### Simple Blocks + +The constructor `Expr.block` provides a simple way to create a block of code `{ stat1; ...; statn; expr }`. +Its first arguments is a list with all the statements and the second argument is the expression at the end of the block. + +```scala +inline def test(inline ignore: Boolean, computation: => Unit): Boolean = + ${ testCode('ignore, 'computation) } + +def testCode(ignore: Expr[Boolean], computation: Expr[Unit])(using Quotes) = + if ignore.valueOrAbort then Expr(false) + else Expr.block(List(computation), Expr(true)) +``` + +The `Expr.block` constructor is useful when we want to generate code contanining several side effects. +The macro call `test(false, EXPRESSION)` will generate `{ EXPRESSION; true}`, while the call `test(true, EXPRESSION)` will result in `false`. + +### Simple Matching + +The method `Expr.matches` can be used to check if one expression is equal to another. +With this method we could implement an `value` operation for `Expr[Boolean]` as follows. + +```scala +def value(boolExpr: Expr[Boolean]): Option[Boolean] = + if boolExpr.matches(Expr(true)) then Some(true) + else if boolExpr.matches(Expr(false)) then Some(false) + else None +``` + +It may also be used to compare two user written expression. +Note, that `matches` only performs a limited amount of normalization and while for instance the Scala expression `2` matches the expression `{ 2 }`, this is _not the case_ for the expression `{ val x: Int = 2; x }`. + +### Arbitrary Expressions + +Last but not least, it is possible to create an `Expr[T]` from arbitary Scala code by enclosing it in [quotes][quotes]. +For example, `'{ ${expr}; true }` will generate an `Expr[Boolean]` equivalent to `Expr.block(List(expr), Expr(true))`. +The subsequent section on [Quoted Code][quotes] presents quotes in more detail. + +[contributing]: {% link scala3/contribute-to-docs.md %} +[best-practices]: {% link _overviews/scala3-macros/best-practices.md %} +[compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[migration]: https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html +[faq]: {% link _overviews/scala3-macros/faq.md %} +[inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[macros]: {% link _overviews/scala3-macros/tutorial/macros.md %} +[quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[tasty]: {% link _overviews/scala3-macros/tutorial/reflection.md %} diff --git a/_overviews/scala3-macros/tutorial/quotes.md b/_overviews/scala3-macros/tutorial/quotes.md new file mode 100644 index 0000000000..b94d4bb6ab --- /dev/null +++ b/_overviews/scala3-macros/tutorial/quotes.md @@ -0,0 +1,605 @@ +--- +type: section +title: Quoted Code +num: 5 + +previous-page: macros +next-page: reflection +--- + +## Code blocks +A quoted code block `'{ ... }` is syntactically similar to a string quote `" ... "` with the difference that the first contains typed code. +To insert code into other code, we can use the syntax `$expr` or `${ expr }`, where `expr` is of type `Expr[T]`. +Intuitively, the code directly within the quote (`'{ ... }`) is not executed now, while the code within the splice (`${ ... }`) is evaluated and the results spliced into the surrounding expression. + +```scala +val msg = Expr("Hello") +val printHello = '{ print($msg) } +println(printHello.show) // print("Hello") +``` + +In general, the quote delays the execution while the splice makes it happen before the surrounding code. +This generalisation allows us to also give meaning to a `${ ... }` that is not within a quote. This evaluates the code within the splice at compile-time and places the result in the generated code. +Due to some technical considerations, only top-level splices are allowed directly within `inline` definitions that we call a [macro][macros]. + +It is possible to write a quote within a quote, but this pattern is not common when writing macros. + +## Level consistency +One cannot simply write any arbitrary code within quotes and within splices, as one part of the program will live at compile-time and the other will live at runtime. +Consider the following ill-constructed code: + +```scala +def myBadCounter1(using Quotes): Expr[Int] = { + var x = 0 + '{ x += 1; x } +} +``` +The problem with this code is that `x` exists during compilation, but then we try to use it after the compiler has finished (maybe even in another machine). +Clearly, it would be impossible to access its value and update it. + +Now consider the dual version, where we define the variable at runtime and try to access it at compile-time: +```scala +def myBadCounter2(using Quotes): Expr[Int] = '{ + var x = 0 + ${ x += 1; 'x } +} +``` +Clearly, this should not work as the variable does not exist yet. + +To make sure you cannot write programs that contain these kinds of problems, we restrict the kinds of references allowed in quote environments. + +We introduce _levels_ as a count of the number of quotes minus the number of splices surrounding an expression or definition. + +```scala +// level 0 +'{ // level 1 + var x = 0 + ${ // level 0 + x += 1 + 'x // level 1 + } +} +``` + +The system will allow references to global definitions such as `println` at any level, but will restrict references to local definitions. +A local definition can only be accessed if it is defined at the same level as its reference. +This will catch the errors in `myBadCounter1` and `myBadCounter2`. + +Even though we cannot refer to a variable inside of a quote, we can still pass its current value through a quote by lifting the value to an expression using `Expr.apply`. + + +## Generics + +When using type parameters or other kinds of abstract types with quoted code, we will need to keep track of some of these types explicitly. +Scala uses erased-types semantics for its generics. +This implies that types are removed from the program when compiling and the runtime does not have to track all types at runtime. + +Consider the following code: +```scala +def evalAndUse[T](x: Expr[T])(using Quotes) = '{ + val x2: T = $x // error + ... // use x2 +} +``` + +Here, we will get an error telling us that we are missing a contextual `Type[T]`. +Therefore, we can easily fix it by writing: +```scala +def evalAndUse[T](x: Expr[T])(using Type[T])(using Quotes) = '{ + val x2: T = $x + ... // use x2 +} +``` +This code will be equivalent to this more verbose version: +```scala +def evalAndUse[T](x: Expr[T])(using t: Type[T])(using Quotes) = '{ + val x2: t.Underlying = $x + ... // use x2 +} +``` +Note that `Type` has a type member called `Underlying` that refers to the type held within the `Type`; in this case, `t.Underlying` is `T`. +Even if we use the `Type` implicitly, is generally better to keep it contextual as some changes inside the quote may require it. +The less verbose version is usually the best way to write the types as it is much simpler to read. +In some cases, we will not statically know the type within the `Type` and will need to use the `t.Underlying` to refer to it. + +When do we need this extra `Type` parameter? +* When a type is abstract and it is used at a level that is higher than the current level. + +When you add a `Type` contextual parameter to a method, you will either get it from another context parameter or implicitly with a call to `Type.of`: +```scala +evalAndUse(Expr(3)) +// is equivalent to +evalAndUse[Int](Expr(3))(using Type.of[Int]) +``` +As you may have guessed, not every type can be used as a parameter to `Type.of[..]` out of the box. +For example, we cannot recover abstract types that have already been erased: +```scala +def evalAndUse[T](x: Expr[T])(using Quotes) = + given Type[T] = Type.of[T] // error + '{ + val x2: T = $x + ... // use x2 + } +``` + +But we can write more complex types that depend on these abstract types. +For example, if we look for or explicitly construct a `Type[List[T]]`, then the system will require a `Type[T]` in the current context to compile. + +Good code should only add `Type`s to the context parameters and never use them explicitly. +However, explicit use is useful while debugging, though it comes at the cost of conciseness and clarity. + + +## ToExpr +The `Expr.apply` method uses instances of `ToExpr` to generate an expression that will create a copy of the value. +```scala +object Expr: + def apply[T](x: T)(using Quotes, ToExpr[T]): Expr[T] = + summon[ToExpr[T]].apply(x) +``` + +`ToExpr` is defined as follows: +```scala +trait ToExpr[T]: + def apply(x: T)(using Quotes): Expr[T] +``` + +The `ToExpr.apply` method will take a value `T` and generate code that will construct a copy of this value at runtime. + +We can define our own `ToExpr`s like: +```scala +given ToExpr[Boolean] with { + def apply(x: Boolean)(using Quotes) = + if x then '{true} + else '{false} +} + +given ToExpr[StringContext] with { + def apply(stringContext: StringContext)(using Quotes) = + val parts = Varargs(stringContext.parts.map(Expr(_))) + '{ StringContext($parts*) } +} +``` +The `Varargs` constructor just creates an `Expr[Seq[T]]` which we can efficiently splice as a varargs. +In general, any sequence can be spliced with `$mySeq*` to splice it as a varargs. + +## Quoted patterns +Quotes can also be used to check if an expression is equivalent to another or to deconstruct an expression into its parts. + + +### Matching exact expression + +The simplest thing we can do is to check if an expression matches another known expression. +Below, we show how we can match some expressions using `case '{...} =>`. + +```scala +def valueOfBoolean(x: Expr[Boolean])(using Quotes): Option[Boolean] = + x match + case '{ true } => Some(true) + case '{ false } => Some(false) + case _ => None + +def valueOfBooleanOption(x: Expr[Option[Boolean]])(using Quotes): Option[Option[Boolean]] = + x match + case '{ Some(true) } => Some(Some(true)) + case '{ Some(false) } => Some(Some(false)) + case '{ None } => Some(None) + case _ => None +``` + +### Matching partial expression + +To make things more compact, we can also match a part of the expression using a splice (`$`) to match arbitrary code and extract it. + +```scala +def valueOfBooleanOption(x: Expr[Option[Boolean]])(using Quotes): Option[Option[Boolean]] = + x match + case '{ Some($boolExpr) } => Some(valueOfBoolean(boolExpr)) + case '{ None } => Some(None) + case _ => None +``` + +### Matching types of expression + +We can also match against code of an arbitrary type `T`. +Below, we match against `$x` of type `T` and we get out an `x` of type `Expr[T]`. + +```scala +def exprOfOption[T: Type](x: Expr[Option[T]])(using Quotes): Option[Expr[T]] = + x match + case '{ Some($x) } => Some(x) // x: Expr[T] + case '{ None } => Some(None) + case _ => None +``` + +We can also check for the type of an expression: + +```scala +def valueOf(x: Expr[Any])(using Quotes): Option[Any] = + x match + case '{ $x: Boolean } => valueOfBoolean(x) // x: Expr[Boolean] + case '{ $x: Option[Boolean] } => valueOfBooleanOption(x) // x: Expr[Option[Boolean]] + case _ => None +``` +Or similarly for a partial expression: + +```scala +case '{ Some($x: Boolean) } => // x: Expr[Boolean] +``` + +### Matching receiver of methods + +When we want to match the receiver of a method, we need to explicitly state its type: + +```scala +case '{ ($ls: List[Int]).sum } => +``` + +If we would have written `$ls.sum`, we would not have been able to know the type of `ls` and which `sum` method we are calling. + +Another common case where we need type annotations is for infix operations: +```scala +case '{ ($x: Int) + ($y: Int) } => +case '{ ($x: Double) + ($y: Double) } => +case ... +``` + +### Matching function expressions + +Let's start with the most straightforward example, matching an identity function expression: + +```scala +def matchIdentityFunction[A: Type](func: Expr[A => A])(using Quotes): Unit = + func match + case '{ (arg: A) => arg } => +``` +The above matches function expressions that just return their arguments, like: + +```scala +(value: Int) => value +``` + +We can also match more complex expressions, like method call chains: + +```scala +def matchMethodCallChain(func: Expr[String => String])(using Quotes) = + func match + case '{ (arg: String) => arg.toLowerCase.strip.trim } => +``` + +But what about the cases where we want more flexibility (eg. we know the subset of methods that will be called but not neccessarily their order)? + +#### Iterative deconstruction of a function expression + +Let's imagine we need a macro that collects names of methods used in an expression of type `FieldName => FieldName`, for a definition of `FieldName`: + +```scala +trait FieldName: + def uppercase: FieldName + def lowercase: FieldName +``` + +The implementation itself would look like this: + +```scala +def collectUsedMethods(func: Expr[FieldName => FieldName])(using Quotes): List[String] = + def recurse(current: Expr[FieldName => FieldName], acc: List[String])(using Quotes): List[String] = + current match + // $body is the next tree with the '.lowercase' call stripped away + case '{ (arg: FieldName) => ($body(arg): FieldName).lowercase } => + recurse(body, "lowercase" :: acc) // body: Expr[FieldName => FieldName] + + // $body is the next tree with the '.uppercase' call stripped away + case '{ (arg: FieldName) => ($body(arg): FieldName).uppercase } => + recurse(body, "uppercase" :: acc) // body: Expr[FieldName => FieldName] + + // this matches an identity function, i.e. the end of our loop + case '{ (arg: FieldName) => arg } => acc + end recurse + + recurse(func, Nil) +``` + +For more details on how patterns like `$body(arg)` work please refer to a docs section on [the HOAS pattern](https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html#hoas-patterns-1). + +If we were to use this on an expression like this one: +```scala +(name: FieldName) => name.lowercase.uppercase.lowercase +``` +the result would evaluate to `List("lowercase", "uppercase", "lowercase")`. + +### Matching types + +So far, we assumed that the types within quote patterns would be statically known. +Quote patterns also allow for type parameters, which we will see in this section. + +#### Type parameters in patterns + +Consider the function `exprOfOption` that we have already seen: +```scala +def exprOfOption[T: Type](x: Expr[Option[T]])(using Quotes): Option[Expr[T]] = + x match + case '{ Some($x: T) } => Some(x) // x: Expr[T] + // ^^^ type ascription with type T + ... +``` + +Note that this time we have added the `T` explicitly in the pattern, even though it could be inferred. +By referring to the type parameter `T` in the pattern, we are required to have a given `Type[T]` in scope. +This implies that `$x: T` will only match if `x` is of type `Expr[T]`. +In this particular case, this condition will always be true. + +Now consider the following variant where `x` is an optional value with a (statically) unknown element type: + +```scala +def exprOfOptionOf[T: Type](x: Expr[Option[Any]])(using Quotes): Option[Expr[T]] = + x match + case '{ Some($x: T) } => Some(x) // x: Expr[T] + case _ => None +``` +This time, the pattern `Some($x: T)` will only match if the type of the `Option` is `Some[T]`. + +```scala +exprOfOptionOf[Int]('{ Some(3) }) // Some('{3}) +exprOfOptionOf[Int]('{ Some("a") }) // None +``` + +#### Type variables in quoted patterns + +Quoted code may contain types that are not known outside of the quote. +We can match on them using pattern type variables. +Just as in a normal pattern, the type variables are written using lower case names. + +```scala +def exprOptionToList(x: Expr[Option[Any]])(using Quotes): Option[Expr[List[Any]]] = + x match + case '{ Some($x: t) } => + // ^^^ this binds the type `t` in the body of the case + Some('{ List[t]($x) }) // x: Expr[List[t]] + case '{ None } => + Some('{ Nil }) + case _ => None +``` + +The pattern `$x: t` will match an expression of any type and `t` will be bound to the type of the pattern. +This type variable is only valid in the right-hand side of the `case`. +In this example, we use it to construct the list `List[t]($x)` (`List($x)` would also work). +As this is a type that is not statically, known we need a given `Type[t]` in scope. +Luckily, the quoted pattern will automatically provide this for us. + +The simple pattern `case '{ $expr: tpe } =>` is very useful if we want to know the precise type of the expression. +```scala +val expr: Expr[Option[Int]] = ... +expr match + case '{ $expr: tpe } => + Type.show[tpe] // could be: Option[Int], Some[Int], None, Option[1], Option[2], ... + '{ val x: tpe = $expr; x } // binds the value without widening the type + ... +``` + +In some cases we need to define a pattern variable that is referenced several times or has some type bounds. +To achieve this, it is possible to create pattern variables at the start of the pattern using `type t` with a type pattern variable. + +```scala +/** + * Use: Converts a redundant `list.map(f).map(g)` to only use one call + * to `map`: `list.map(y => g(f(y)))`. + */ +def fuseMap[T: Type](x: Expr[List[T]])(using Quotes): Expr[List[T]] = x match { + case '{ + type u + type v + ($ls: List[`u`]) + .map($f: `u` => `v`) + .map($g: `v` => T) + } => + '{ $ls.map(y => $g($f(y))) } + case _ => x +} +``` + +Here, we define two type variables `u` and `v` and then refer to them using `` `u` `` and `` `v` ``. +We do not refer to them using `u` or `v` (without backticks) because those would be interpreted as new type variables with the same variable name. +This notation follows the normal [stable identifier patterns](https://www.scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#stable-identifier-patterns) syntax. +Furthermore, if the type variable needs to be constrained, we can add bounds directly on the type definition: `case '{ type u <: AnyRef; ... } =>`. + +Note that the previous case could also be written as `case '{ ($ls: List[u]).map[v]($f).map[T]($g) =>`. + +#### Quote types patterns + +Types represented with `Type[T]` can be matched on using the patten `case '[...] =>`. + +```scala +inline def mirrorFields[T]: List[String] = ${mirrorFieldsImpl[T]} + +def mirrorFieldsImpl[T: Type](using Quotes): Expr[List[String]] = + + def rec[A : Type]: List[String] = Type.of[A] match + case '[field *: fields] => + Type.show[field] :: rec[fields] + case '[EmptyTuple] => + Nil + case _ => + quotes.reflect.report.errorAndAbort("Expected known tuple but got: " + Type.show[A]) + + Expr(rec) +``` +```scala +mirrorFields[EmptyTuple] // Nil +mirrorFields[(Int, String, Int)] // List("scala.Int", "java.lang.String", "scala.Int") +mirrorFields[Tuple] // error: Expected known tuple but got: Tuple +``` + +As with expression quote patterns, type variables are represented using lower case names. + +## FromExpr + +The `Expr.value`, `Expr.valueOrAbort`, and `Expr.unapply` methods use instances of `FromExpr` to extract the value if possible. +```scala +extension [T](expr: Expr[T]): + def value(using Quotes)(using fromExpr: FromExpr[T]): Option[T] = + fromExpr.unapply(expr) + + def valueOrError(using Quotes)(using fromExpr: FromExpr[T]): T = + fromExpr.unapply(expr).getOrElse(eport.throwError("...", expr)) +end extension + +object Expr: + def unapply[T](expr: Expr[T])(using Quotes)(using fromExpr: FromExpr[T]): Option[T] = + fromExpr.unapply(expr) +``` + +`FromExpr` is defined as follows: +```scala +trait FromExpr[T]: + def unapply(x: Expr[T])(using Quotes): Option[T] +``` + +The `FromExpr.unapply` method will take a value `x` and generate code that will construct a copy of this value at runtime. + +We can define our own `FromExpr`s like so: +```scala +given FromExpr[Boolean] with { + def unapply(x: Expr[Boolean])(using Quotes): Option[Boolean] = + x match + case '{ true } => Some(true) + case '{ false } => Some(false) + case _ => None +} + +given FromExpr[StringContext] with { + def unapply(x: Expr[StringContext])(using Quotes): Option[StringContext] = x match { + case '{ new StringContext(${Varargs(Exprs(args))}*) } => Some(StringContext(args*)) + case '{ StringContext(${Varargs(Exprs(args))}*) } => Some(StringContext(args*)) + case _ => None + } +} +``` +Note that we handled two cases for `StringContext`. +As it is a `case class`, it can be created with `new StringContext` or with `StringContext.apply` from the companion object. +We also used the `Varargs` extractor to match the arguments of type `Expr[Seq[String]]` into a `Seq[Expr[String]]`. +Then we used the `Exprs` to match known constants in the `Seq[Expr[String]]` to get a `Seq[String]`. + + +## The Quotes +The `Quotes` is the main entry point for the creation of all quotes. +This context is usually just passed around through contextual abstractions (`using` and `?=>`). +Each quote scope will have its own `Quotes`. +New scopes are introduced each time a splice is introduced (`${ ... }`). +Though it looks like a splice takes an expression as argument, it actually takes a `Quotes ?=> Expr[T]`. +Therefore, we could actually write it explicitly as `${ (using q) => ... }`. +This might be useful when debugging to avoid generated names for these scopes. + +The method `scala.quoted.quotes` provides a simple way to use the current `Quotes` without naming it. +It is usually imported along with the `Quotes` using `import scala.quoted.*`. + +```scala +${ (using q1) => body(using q1) } +// equivalent to +${ body(using quotes) } +``` +Warning: If you explicitly name a `Quotes` `quotes`, you will shadow this definition. + +When we write a top-level splice in a macro, we are calling something similar to the following definition. +This splice will provide the initial `Quotes` associated with the macro expansion. +```scala +def $[T](x: Quotes ?=> Expr[T]): T = ... +``` + +When we have a splice within a quote, the inner quote context will depend on the outer one. +This link is represented using the `Quotes.Nested` type. +Users of quotes will almost never need to use `Quotes.Nested`. +These details are only useful for advanced macros that will inspect code and may encounter details of quotes and splices. + +```scala +def f(using q1: Quotes) = '{ + ${ (using q2: q1.Nested) ?=> + ... + } +} +``` + +We can imagine that a nested splice is like the following method, where `ctx` is the context received by the surrounding quote. +```scala +def $[T](using q: Quotes)(x: q.Nested ?=> Expr[T]): T = ... +``` + +## β-reduction +When we have a lambda applied to an argument in a quote `'{ ((x: Int) => x + x)(y) }`, we do not reduce it within the quote; the code is kept as-is. +There is an optimisation that will β-reduce all lambdas directly applied to parameters to avoid the creation of a closure. +This will not be visible from the quote's perspective. + +Sometimes it is useful to perform this β-reduction on the quotes directly. +We provide the function `Expr.betaReduce[T]` that receives an `Expr[T]` and β-reduces if it contains a directly-applied lambda. + +```scala +Expr.betaReduce('{ ((x: Int) => x + x)(y) }) // returns '{ val x = y; x + x } +``` + + +## Summon values +There are two ways to summon values in a macro. +The first is to have a `using` parameter in the inline method that is passed explicitly to the macro implementation. + +```scala +inline def setOf[T](using ord: Ordering[T]): Set[T] = + ${ setOfCode[T]('ord) } + +def setOfCode[T: Type](ord: Expr[Ordering[T]])(using Quotes): Expr[Set[T]] = + '{ TreeSet.empty[T](using $ord) } +``` + +In this scenario, the context parameter is found before the macro is expanded. +If not found, the macro will not be expanded. + +The second way is using `Expr.summon`. +This allows us to programatically search for distinct given expressions. +The following example is similar to the previous example: + +```scala +inline def setOf[T]: Set[T] = + ${ setOfCode[T] } + +def setOfCode[T: Type](using Quotes): Expr[Set[T]] = + Expr.summon[Ordering[T]] match + case Some(ord) => '{ TreeSet.empty[T](using $ord) } + case _ => '{ HashSet.empty[T] } +``` + +The difference is that, in the second scenario, we expand the macro before the implicit search is performed. We can therefore write arbitrary code to handle the case when an `Ordering[T]` is not found. +Here, we used `HashSet` instead of `TreeSet` because the former does not need an `Ordering`. + +## Quoted Type Classes + +In the previous example we showed how to use the `Expr[Ordering[T]]` type class explicitly by leveraging the `using` argument clause. This is perfectly fine, but it is not very convenient if we need to use the type class multiple times. To show this we will +use a `powerCode` function that can be used on any numeric type. + +First, it can be useful to make `Expr` type class can make it a given parameter. To do this we do need to explicitly in `power` to `powerCode` because we have a given `Numeric[Num]` but require an `Expr[Numeric[Num]]`. But then we can ignore it in `powerMacro` and any other place that only passes it around. + +```scala +inline def power[Num](x: Num, inline n: Int)(using num: Numeric[Num]) = + ${ powerMacro('x, 'n)(using 'num) } + +def powerMacro[Num: Type](x: Expr[Num], n: Expr[Int])(using Expr[Numeric[Num]])(using Quotes): Expr[Num] = + powerCode(x, n.valueOrAbort) +``` + +To use a this type class we need a given `Numeric[Num]` but we have a `Expr[Numeric[Num]]` and therefore we need to splice this expression in the generated code. To make it available we can just splice it in a given definition. + +```scala +def powerCode[Num: Type](x: Expr[Num], n: Int)(using num: Expr[Numeric[Num]])(using Quotes): Expr[Num] = + if (n == 0) '{ $num.one } + else if (n % 2 == 0) '{ + given Numeric[Num] = $num + val y = $x * $x + ${ powerCode('y, n / 2) } + } + else '{ + given Numeric[Num] = $num + $x * ${ powerCode(x, n - 1) } + } +``` + + + +[macros]: {% link _overviews/scala3-macros/tutorial/macros.md %} +[quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} diff --git a/_overviews/scala3-macros/tutorial/reflection.md b/_overviews/scala3-macros/tutorial/reflection.md new file mode 100644 index 0000000000..46618a1d4f --- /dev/null +++ b/_overviews/scala3-macros/tutorial/reflection.md @@ -0,0 +1,235 @@ +--- +type: section +title: Reflection +num: 6 + +previous-page: quotes +--- + +The reflection API provides a more complex and comprehensive view on the structure of the code. +It provides a view of *Typed Abstract Syntax Trees* and their properties such as types, symbols, positions and comments. + +The API can be used in macros as well as for [inspecting TASTy files][tasty inspection]. + +## How to use the API + +The reflection API is defined in the type `Quotes` as `reflect`. +The actual instance depends on the current scope, in which quotes or quoted pattern matching is used. +Hence, every macro method receives Quotes as an additional argument. +Since `Quotes` is contextual, to access its members we either need to name the parameter or summon it. +The following definition from the standard library details the canonical way of accessing it: + +```scala +package scala.quoted + +transparent inline def quotes(using inline q: Quotes): q.type = q +``` + +We can use `scala.quoted.quotes` to import the current `Quotes` in scope: + +```scala +import scala.quoted.* // Import `quotes`, `Quotes`, and `Expr` + +def f(x: Expr[Int])(using Quotes): Expr[Int] = + import quotes.reflect.* // Import `Tree`, `TypeRepr`, `Symbol`, `Position`, ..... + val tree: Tree = ... + ... +``` + +This will import all the types and modules (with extension methods) of the API. + +## How to navigate the API + +The full API can be found in the [API documentation for `scala.quoted.Quotes.reflectModule`][reflection doc]. +Unfortunately, at this stage, this automatically-generated documentation is not very easy to navigate. + +The most important element on the page is the hierarchy tree which provides a synthetic overview of the subtyping relationships of +the types in the API. For each type `Foo` in the tree: + + - the trait `FooMethods` contains the methods available on the type `Foo` + - the trait `FooModule` contains the static methods available on the object `Foo`. +Most notably, constructors (`apply/copy`) and the `unapply` method which provides the extractor(s) required for pattern matching are found here + - For all types `Upper` such that `Foo <: Upper`, the methods defined in `UpperMethods` are also available on `Foo` + +For example, [`TypeBounds`](https://scala-lang.org/api/3.x/scala/quoted/Quotes$reflectModule.html#TypeBounds-0), a subtype of `TypeRepr`, represents a type tree of the form `T >: L <: U`: a type `T` which is a super type of `L` +and a subtype of `U`. In [`TypeBoundsMethods`](https://scala-lang.org/api/3.x/scala/quoted/Quotes$reflectModule$TypeBoundsMethods.html), you will find the methods `low` and `hi`, which allow you to access the +representations of `L` and `U`. In [`TypeBoundsModule`](https://scala-lang.org/api/3.x/scala/quoted/Quotes$reflectModule$TypeBoundsModule.html), you will find the `unapply` method, which allows you to write: + +```scala +def f(tpe: TypeRepr) = + tpe match + case TypeBounds(l, u) => +``` + +Because `TypeBounds <: TypeRepr`, all the methods defined in `TypeReprMethods` are available on `TypeBounds` values: + +```scala +def f(tpe: TypeRepr) = + tpe match + case tpe: TypeBounds => + val low = tpe.low + val hi = tpe.hi +``` + +## Relation with Expr/Type + +### Expr and Term + +Expressions (`Expr[T]`) can be seen as wrappers around a `Term`, where `T` is the statically-known type of the term. +Below, we use the extension method `asTerm` to transform an expression into a term. +This extension method is only available after importing `quotes.reflect.asTerm`. +Then we use `asExprOf[Int]` to transform the term back into `Expr[Int]`. +This operation will fail if the term does not have the provided type (in this case, `Int`) or if the term is not a valid expression. +For example, an `Ident(fn)` is an invalid term if the method `fn` takes type parameters, in which case we would need an `Apply(Ident(fn), args)`. + +```scala +def f(x: Expr[Int])(using Quotes): Expr[Int] = + import quotes.reflect.* + val tree: Term = x.asTerm + val expr: Expr[Int] = tree.asExprOf[Int] + expr +``` + +### Type and TypeRepr + +Similarly, we can also see `Type[T]` as a wrapper over `TypeRepr`, with `T` being the statically-known type. +To get a `TypeRepr`, we use `TypeRepr.of[T]`, which expects a given `Type[T]` in scope (similar to `Type.of[T]`). +We can also transform it back into a `Type[?]` using the `asType` method. +As the type of `Type[?]` is not statically known, we need to name it with an existential type to use it. This can be achieved using the `'[t]` pattern. + +```scala +def g[T: Type](using Quotes) = + import quotes.reflect.* + val tpe: TypeRepr = TypeRepr.of[T] + tpe.asType match + case '[t] => '{ val x: t = ${...} } + ... +``` + +## Symbols + +The APIs of `Term` and `TypeRepr` are relatively *closed* in the sense that methods produce and accept values whose types are defined in the API. +However, you might notice the presence of `Symbol`s which identify definitions. + +Both `Term`s and `TypeRepr`s (and therefore `Expr`s and `Type`s) have an associated symbol. +`Symbol`s make it possible to compare two definitions using `==` to know if they are the same. +In addition, `Symbol` exposes and is used by many useful methods. For example: + + - `declaredFields` and `declaredMethods` allow you to iterate on the fields and members defined inside a symbol + - `flags` allows you to check multiple properties of a symbol + - `companionClass` and `companionModule` provide a way to jump to and from the companion object/class + - `TypeRepr.baseClasses` returns the list of symbols of classes extended by a type + - `Symbol.pos` gives you access to the position where the symbol is defined, the source code of the definition, and even the filename where the symbol is defined + - many others that you can find in [`SymbolMethods`](https://scala-lang.org/api/3.x/scala/quoted/Quotes$reflectModule$SymbolMethods.html) + +### To Symbol and back + +Consider an instance of the type `TypeRepr` named `val tpe: TypeRepr = ...`. Then: + + - `tpe.typeSymbol` returns the symbol of the type represented by `TypeRepr`. The recommended way to obtain a `Symbol` given a `Type[T]` is `TypeRepr.of[T].typeSymbol` + - For a singleton type, `tpe.termSymbol` returns the symbol of the underlying object or value + - `tpe.memberType(symbol)` returns the `TypeRepr` of the provided symbol + - On objects `t: Tree`, `t.symbol` returns the symbol associated with a tree. + Given that `Term <: Tree`, `Expr.asTerm.symbol` is the best way to obtain the symbol associated with an `Expr[T]` + - On objects `sym: Symbol`, `sym.tree` returns the `Tree` associated to the symbol. +Be careful when using this method as the tree for a symbol might not be defined. +Read more on the [best practices page][best practices] + +## Macro API design + +It will often be useful to create helper methods or extractors that perform some common logic of your macros. + +The simplest methods will be those that only mention `Expr`, `Type`, and `Quotes` in their signature. +Internally, they may use reflection, but this will not be seen at the use site of the method. + +```scala +def f(x: Expr[Int])(using Quotes): Expr[Int] = + import quotes.reflect.* + ... +``` + +In some cases, it may be inevitable that some methods will expect or return `Tree`s or other types in `quotes.reflect`. +For these cases, the best practice is to follow the following method signature examples: + +A method that takes a `quotes.reflect.Term` parameter +```scala +def f(using Quotes)(term: quotes.reflect.Term): String = + import quotes.reflect.* + ... +``` + +An extension method for a `quotes.reflect.Term` returning a `quotes.reflect.Tree` +```scala +extension (using Quotes)(term: quotes.reflect.Term) + def g: quotes.reflect.Tree = ... +``` + +An extractor that matches on `quotes.reflect.Term`s +```scala +object MyExtractor: + def unapply(using Quotes)(x: quotes.reflect.Term) = + ... + Some(y) +``` + +> **Avoid saving the `Quotes` context in a field.** +> `Quotes` in fields inevitably make its use harder by causing errors involving `Quotes` with different paths. +> +> Usually, these patterns have been seen in code that uses the Scala 2 ways to define extension methods or contextual unapplies. +> Now that we have `given` parameters that can be added before other parameters, all these old workarounds are not needed anymore. +> The new abstractions make it simpler both at the definition site and at the use site. + +## Debugging + +### Runtime checks + +Expressions (`Expr[T]`) can be seen as wrappers around a `Term`, where `T` is the statically-known type of the term. +Hence, these checks will be done at runtime (i.e. compile-time when the macro expands). + +It is recommended to enable the `-Xcheck-macros` flag while developing macros or on the tests for the macro. +This flag will enable extra runtime checks that will try to find ill-formed trees or types as soon as they are created. + +There is also the `-Ycheck:all` flag that checks all compiler invariants for tree well-formedness. +These checks will usually fail with an assertion error. + +### Printing the trees + +The `toString` methods on types in the `quotes.reflect` package are not great for debugging as they show the internal representation rather than the `quotes.reflect` representation. +In many cases these are similar, but they may sometimes lead the debugging process astray, so they shouldn't be relied on. + +Instead, `quotes.reflect.Printers` provides a set of useful printers for debugging. +Notably the `TreeStructure`, `TypeReprStructure`, and `ConstantStructure` classes can be quite useful. +These will print the tree structure following loosely the extractors that would be needed to match it. + +```scala +val tree: Tree = ... +println(tree.show(using Printer.TreeStructure)) +``` + +One of the most useful places where this can be added is at the end of a pattern match on a `Tree`. + +```scala +tree match + case Ident(_) => + case Select(_, _) => + ... + case _ => + throw new MatchError(tree.show(using Printer.TreeStructure)) +``` +This way, if a case is missed the error will report a familiar structure that can be copy-pasted to start fixing the issue. + +You can make this printer the default if desired: +```scala + import quotes.reflect.* + given Printer[Tree] = Printer.TreeStructure + ... + println(tree.show) +``` + +## More +*Coming soon* + +[tasty inspection]: {{ site.scala3ref }}/metaprogramming/tasty-inspect.html +[reflection doc]: https://scala-lang.org/api/3.x/scala/quoted/Quotes$reflectModule.html + +[best practices]: {% link _overviews/scala3-macros/best-practices.md %} diff --git a/_overviews/scala3-migration/compatibility-classpath.md b/_overviews/scala3-migration/compatibility-classpath.md new file mode 100644 index 0000000000..6b25280994 --- /dev/null +++ b/_overviews/scala3-migration/compatibility-classpath.md @@ -0,0 +1,141 @@ +--- +title: Classpath Level +type: section +description: This section describes the compatibility between Scala 2.13 and Scala 3 class files. +num: 3 +previous-page: compatibility-source +next-page: compatibility-runtime +--- + +In your code you can use public types and terms, and call public methods that are defined in a different module or library. +It works well as long as the type checker, which is the compiler phase that validates the semantic consistency of the code, is able to read the signatures of those types, terms and methods, from the class files containing them. + +In Scala 2 the signatures are stored in a dedicated format called the Pickle format. +In Scala 3 the story is a bit different because it relies on the TASTy format which is a lot more than a signature layout. +But, for the purpose of moving from Scala 2.13 to Scala 3, only the signatures are useful. + +## The Scala 3 Unpickler + +The first piece of good news is that the Scala 3 compiler is able to read the Scala 2.13 Pickle format and thus it can type check code that depends on modules or libraries compiled with Scala 2.13. + +The Scala 3 unpickler has been extensively tested in the community build for many years now. It is safe to use. + +### A Scala 3 module can depend on a Scala 2.13 artifact + +![Scala 3 module depending on a Scala 2.13 artifact](/resources/images/scala3-migration/compatibility-3-to-213.svg) + +As an sbt build, it looks like this: + +```scala +// build.sbt (sbt 1.5 or higher) +lazy val foo = project.in(file("foo")) + .settings(scalaVersion := "3.3.1") + .dependsOn(bar) + +lazy val bar = project.in(file("bar")) + .settings(scalaVersion := "2.13.11") +``` + +Or, in case bar is a published Scala 2.13 library, we can have: + +```scala +lazy val foo = project.in(file("foo")) + .settings( + scalaVersion := "3.3.1", + libraryDependencies += ("org.bar" %% "bar" % "1.0.0").cross(CrossVersion.for3Use2_13) + ) +``` + +We use `CrossVersion.for3Use2_13` in sbt to resolve `bar_2.13` instead of `bar_3`. + +### The Standard Library + +One notable example is the Scala 2.13 library. +We have indeed decided that the Scala 2.13 library is the official standard library for Scala 3. + +Let's note that the standard library is automatically provided by the build tool, you should not need to configure it manually. + +## The Scala 2.13 TASTy Reader + +The second piece of good news is that Scala 2.13 can consume Scala 3 libraries with `-Ytasty-reader`. + +### Supported Features + +The TASTy reader supports all the traditional language features as well as the following Scala 3 features: +- [Enumerations]({{ site.scala3ref }}/enums/enums.html) +- [Intersection Types]({{ site.scala3ref }}/new-types/intersection-types.html) +- [Opaque Type Aliases]({{ site.scala3ref }}/other-new-features/opaques.html) +- [Type Lambdas]({{ site.scala3ref }}/new-types/type-lambdas.html) +- [Contextual Abstractions]({{ site.scala3ref }}/contextual) (new syntax) +- [Open Classes]({{ site.scala3ref }}/other-new-features/open-classes.html) (and inheritance of super traits) +- [Export Clauses]({{ site.scala3ref }}/other-new-features/export.html) + +It partially supports: +- [Top-Level Definitions]({{ site.scala3ref }}/dropped-features/package-objects.html) +- [Extension Methods]({{ site.scala3ref }}/contextual/extension-methods.html) + +It does not support the more advanced features: +- [Context Functions]({{ site.scala3ref }}/contextual/context-functions.html) +- [Polymorphic Function Types]({{ site.scala3ref }}/new-types/polymorphic-function-types.html) +- [Trait Parameters]({{ site.scala3ref }}/other-new-features/trait-parameters.html) +- `@static` Annotation +- `@alpha` Annotation +- [Functions and Tuples larger than 22 parameters]({{ site.scala3ref }}/dropped-features/limit22.html) +- [Match Types]({{ site.scala3ref }}/new-types/match-types.html) +- [Union Types]({{ site.scala3ref }}/new-types/union-types.html) +- [Multiversal Equality]({{ site.scala3ref }}/contextual/multiversal-equality.html) (unless explicit) +- [Inline]({{ site.scala3ref }}/metaprogramming/inline.html) (including Scala 3 macros) +- [Kind Polymorphism]({{ site.scala3ref }}/other-new-features/kind-polymorphism.html) (the `scala.AnyKind` upper bound) + +### A Scala 2.13 module can depend on a Scala 3 artifact + +By enabling the TASTy reader with `-Ytasty-reader`, a Scala 2.13 module can depend on a Scala 3 artifact. + +![Scala 2 module depending on a Scala 3 artifact](/resources/images/scala3-migration/compatibility-213-to-3.svg) + +As an sbt build, it looks like this: + +```scala +// build.sbt (sbt 1.5 or higher) +lazy val foo = project.in.file("foo") + .settings( + scalaVersion := "2.13.11", + scalacOptions += "-Ytasty-reader" + ) + .dependsOn(bar) + +lazy val bar = project.in(file("bar")) + .settings(scalaVersion := "3.3.1") +``` + +Or, in case `bar` is a published Scala 3 library: + +```scala +lazy val foo = project.in.file("foo") + .settings( + scalaVersion := "2.13.11", + scalacOptions += "-Ytasty-reader", + libraryDependencies += ("org.bar" %% "bar" % "1.0.0").cross(CrossVersion.for2_13Use3) + ) +``` + +Similarly to `CrossVersion.for2_13Use3`, we use `CrossVersion.for3Use2_13` in sbt to resolve `bar_3` instead of `bar_2.13`. + +## Interoperability Overview + +In short, we have backward and forward compatibility and so **migration can happen gradually**. + +You can port a big Scala application one module at a time, even if its library dependencies have not yet been ported (excepting the macro libraries). + +During the transition period, you can have a Scala 3 module layered in between two 2.13 modules. + +![Sandwich pattern](/resources/images/scala3-migration/compatibility-sandwich.svg) + +This is permitted as long as all libraries are resolved to a single binary version: you can have `lib-foo_3` and `lib-bar_2.13` in the same classpath, but you cannot have `lib-foo_3` and `lib-foo_2.13`. + +The inverted pattern, with a 2.13 module in the middle, is also possible. + +> #### Disclaimer for library maintainers +> +> Unless you know exactly what you are doing, it is discouraged to publish a Scala 3 library that depends on a Scala 2.13 library (the scala-library being excluded) or vice versa. +> The reason is to prevent library users from ending up with two conflicting versions `foo_2.13` and `foo_3` of the same foo library in their classpath, this problem being unsolvable in some cases. diff --git a/_overviews/scala3-migration/compatibility-intro.md b/_overviews/scala3-migration/compatibility-intro.md new file mode 100644 index 0000000000..b511567a2b --- /dev/null +++ b/_overviews/scala3-migration/compatibility-intro.md @@ -0,0 +1,36 @@ +--- +title: Compatibility Reference +type: chapter +description: This chapter describes the compatibility between Scala 2.13 and Scala 3. +num: 1 +previous-page: +next-page: compatibility-source +--- + +Scala 3 is a game changer in terms of compatibility in the Scala ecosystem that will greatly improve the day-to-day experience of every Scala programmer. +This new compatibility era starts with the migration. + +Moving from Scala 2 to Scala 3 is a big leap forward. +Scala 3 is a shiny new compiler, built upon a complete redesign of the core foundations of the language. +Yet we claim the migration will not be harder than before, when we moved from Scala 2.12 to Scala 2.13. + +It will even be simpler in some respects, thanks to the interoperability between Scala 2.13 and Scala 3. + +This chapter details the level of compatibility between the two versions at the different stages of the program. +This is where you will find answers to the following questions: + +**[Source Level](compatibility-source.html)** +- Is Scala 3 a different language? +- How hard is it to translate a Scala 2.13 project into Scala 3? + +**[Classpath Level](compatibility-classpath.html)** +- Can we use a Scala 2.13 library in Scala 3? +- Inversely, can we use a Scala 3 library in Scala 2.13? + +**[Runtime](compatibility-runtime.html)** +- Is it safe to deploy a Scala 3 program in a production environment? +- How fast are Scala 3 programs compared to Scala 2.13? + +**[Metaprogramming](compatibility-metaprogramming.html)** +- Will my Scala 2.13 project be affected by the replacement of the Scala 2 macro feature? +- How can I port my Scala 2.13 macro library to Scala 3? diff --git a/_overviews/scala3-migration/compatibility-metaprogramming.md b/_overviews/scala3-migration/compatibility-metaprogramming.md new file mode 100644 index 0000000000..675f5fc4a3 --- /dev/null +++ b/_overviews/scala3-migration/compatibility-metaprogramming.md @@ -0,0 +1,89 @@ +--- +title: Metaprogramming +type: section +description: This section discuss the metaprogramming transition +num: 5 +previous-page: compatibility-runtime +next-page: tooling-tour +--- + +A call to a macro method is executed during the compiler phase called macro expansion to generate a part of the program---an abstract syntax tree. + +The Scala 2.13 macro API is closely tied to the Scala 2.13 compiler internals. +Therefore it is not possible for the Scala 3 compiler to expand any Scala 2.13 macro. + +In contrast, Scala 3 introduces a new principled approach of metaprogramming that is designed for stability. +Scala 3 macros, and inline methods in general, will be compatible with future versions of the Scala 3 compiler. +While this is an uncontested improvement, it also means that all Scala 2.13 macros have to be rewritten from the ground up, using the new metaprogramming features. + +## Macro Dependencies + +A Scala 3 module can depend on a Scala 2.13 artifact even if it contains a macro definition but the compiler will not be able to expand its macros. +When you try to, it simply returns an error. + +{% highlight text %} + -- Error: /src/main/scala/example/Example.scala:10:45 + 10 | val documentFormat = Json.format[Document] + | ^ + |Scala 2 macro cannot be used in Scala 3. See https://dotty.epfl.ch/docs/reference/dropped-features/macros.html + |To turn this error into a warning, pass -Xignore-scala2-macros to the compiler +{% endhighlight %} + +Let's note that using `-Xignore-scala2-macros` is helpful to type check the code but it produces incomplete class files. + +When this error appears in your project, you have eventually no other choice than upgrading to a Scala 3-compiled version of the macro artifact. + +## Porting the Macro Ecosystem + +While being experimental, the Scala community has largely adopted the Scala 2 macro feature in multiple ways: code generation, optimizations, ergonomic DSLs... + +A large part of the ecosystem now depends on Scala 2.13 macros defined in external libraries. +Identifying and porting those libraries is key to move the ecosystem forward. + +A migration status of many open-source macro libraries is available in [this page](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html). + +## Rewriting a Macro + +The new metaprogramming features are completely different from Scala 2. +They are comprised of: +- [Inline Methods][inline] +- [Compile-time operations][compiletime] +- [Macros][macros] +- [Quoted code][quotes] +- [Reflection over Abstract Syntax Trees (AST)][reflection] + +Before getting deep into reimplementing a macro you should ask yourself: +- Can I use `inline` and the `scala.compiletime` operations to reimplement my logic? +- Can I use the simpler and safer expression-based macros? +- Do I really need to access the AST? +- Can I use a [match type]({{ site.scala3ref }}/new-types/match-types.html) as return type? + +You can learn all the new metaprogramming concepts by reading the [Macros in Scala 3][scala3-macros] tutorial. + +## Cross-building a Macro Library + +You have written a wonderful macro library and you would like it to be available in Scala 2.13 and Scala 3. +There are two different approaches, the traditional cross-building technique and the more flexible macro mixing technique. + +The benefit of macro mixing is that consumers who take advantage of the `-Ytasty-reader` option can still use your macros. + +You can learn about them by reading these tutorials: +- [Cross-Building a Macro Library](tutorial-macro-cross-building.html) +- [Mixing Scala 2.13 and Scala 3 Macros](tutorial-macro-mixing.html) + +## Additional Resources + +Blog posts and talks: +- [Macros: The Plan For Scala 3](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html) +- [Scala Days - Metaprogramming in Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) + +Early-adopter projects: +- [XML Interpolator](https://github.com/dotty-staging/xml-interpolator/tree/master) +- [Shapeless 3](https://github.com/dotty-staging/shapeless/tree/shapeless-3) + +[inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[macros]: {% link _overviews/scala3-macros/tutorial/macros.md %} +[quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %} +[scala3-macros]: {% link _overviews/scala3-macros/tutorial/index.md %} diff --git a/_overviews/scala3-migration/compatibility-runtime.md b/_overviews/scala3-migration/compatibility-runtime.md new file mode 100644 index 0000000000..729faae7aa --- /dev/null +++ b/_overviews/scala3-migration/compatibility-runtime.md @@ -0,0 +1,28 @@ +--- +title: Runtime +type: section +description: This section describes the run-time characteristics of a Scala 3 program. +num: 4 +previous-page: compatibility-classpath +next-page: compatibility-metaprogramming +--- + +Scala 2.13 and Scala 3 share the same Application Binary Interface (ABI). + +> The ABI is the representation of Scala code in bytecode or Scala.js IR. +> It determines the run-time behavior of Scala programs. + +Compiling the same source code with Scala 2.13 and Scala 3 produces very similar bytecodes. +The difference being that some features have changed, for instance the initialization of lazy vals has been improved. + +Sharing the ABI also ensures that Scala 2.13 and Scala 3 class files can be loaded by the same JVM class loader. +Similarly, that Scala 2.13 and Scala 3 `sjsir` files can be linked together by the Scala.js linker. + +Furthermore it relieves us from surprising behaviors at runtime. +It makes the migration from Scala 2.13 to Scala 3 very safe in terms of run-time crashes and performance. + +At first sight the run-time characteristics of a Scala program is neither better nor worse in Scala 3 compare to Scala 2.13. +However some new features will help you optimize your program: +- [Opaque Type Aliases](http://dotty.epfl.ch/docs/reference/other-new-features/opaques.html) +- [Inline Methods](http://dotty.epfl.ch/docs/reference/metaprogramming/inline.html) +- [@threadUnsafe annotation](http://dotty.epfl.ch/docs/reference/other-new-features/threadUnsafe-annotation.html) diff --git a/_overviews/scala3-migration/compatibility-source.md b/_overviews/scala3-migration/compatibility-source.md new file mode 100644 index 0000000000..b3e4ad5c41 --- /dev/null +++ b/_overviews/scala3-migration/compatibility-source.md @@ -0,0 +1,28 @@ +--- +title: Source Level +type: section +description: This section describes the level of compatibility between Scala 2.13 and Scala 3 sources. +num: 2 +previous-page: compatibility-intro +next-page: compatibility-classpath +--- + +Scala 3 is an improved version of the Scala 2 language. + +Despite the new syntax, a very large subset of the Scala 2.13 language is still valid. +Not all of it though, some constructs have been simplified, restricted or dropped altogether. +However those decisions were made for good reasons and by taking care that a good workaround is possible. + +In general there is a straightforward cross-compiling solution to every incompatibility, so that the migration from Scala 2.13 to Scala 3 is easy and smooth. +You can find a corpus of incompatibilities in the [Incompatibility Table](incompatibility-table.html). + +There is an exception though, which is the new metaprogramming framework that replaces the Scala 2 experimental macros. +Further explanations are given at the end of this chapter in the [Metaprogramming](compatibility-metaprogramming.html) section. + +Metaprogramming aside, a Scala 2.13 source code can rather easily be ported to Scala 3. +Once done, you will be able to use the new powerful features of Scala 3, which have no equivalent in Scala 2. +The downside is those sources cannot be compiled with Scala 2.13 anymore. +But amazingly, this new Scala 3 artifact can be consumed as a dependency in Scala 2.13. + +As we will see in more detail, it permits backward and forward compatibility. +This is a breakthrough in the history of the Scala programming language. diff --git a/_overviews/scala3-migration/external-resources.md b/_overviews/scala3-migration/external-resources.md new file mode 100644 index 0000000000..1055f4bc95 --- /dev/null +++ b/_overviews/scala3-migration/external-resources.md @@ -0,0 +1,34 @@ +--- +title: External Resources +type: chapter +description: This section lists external resources about the migration to Scala 3. +num: 29 +previous-page: plugin-kind-projector +next-page: +--- + +## Courses + +### Lunatech's [_Moving from Scala 2 to Scala 3_](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course) + +If you're a Scala 2 application developer who's looking at getting up-to-speed on Scala 3 or who's considering a migration of an existing Scala 2 application to Scala 3, Lunatech's [_"Moving from Scala 2 to Scala 3"_](https://github.com/lunatech-labs/lunatech-scala-2-to-scala3-course) course is a good way to get started. + +This course guides you through a migration of a single-module Akka Typed Sudoku solver in a series of about 10 steps. It covers the practical application of the following Scala 3 features: + +- New Control Structure syntax +- Indentation Based syntax +- Syntax rewriting by the Scala 3 compiler +- Top Level definitions +- Parameter untupling +- Contextual Abstractions: + - Extension methods new syntax + - Given instances and Using clauses +- Enumerations and Export clauses +- Intersection and Union Types +- Opaque Type Aliases +- Multiversal Equality + +## Talks + +- [Scala 3: Python 3 or Easiest Upgrade Ever?](https://www.youtube.com/watch?v=jWJ5A1irH_E) by Daniel Spiewak (Weehawken-Lang) +- [Taste the difference with Scala 3: Migrating the ecosystem and more](https://www.youtube.com/watch?v=YQmVrUdx8TU) by Jamie Thompson (f(by) 2020) diff --git a/_overviews/scala3-migration/incompat-contextual-abstractions.md b/_overviews/scala3-migration/incompat-contextual-abstractions.md new file mode 100644 index 0000000000..ea5947f2e4 --- /dev/null +++ b/_overviews/scala3-migration/incompat-contextual-abstractions.md @@ -0,0 +1,150 @@ +--- +title: Contextual Abstractions +type: section +description: This chapter details all incompatibilities caused by the redesign of contextual abstractions +num: 19 +previous-page: incompat-dropped-features +next-page: incompat-other-changes +--- + +The redesign of [contextual abstractions]({{ site.scala3ref }}/contextual) brings some incompatibilities. + +|Incompatibility|Scala 2.13|Scala 3 Migration Rewrite|Scalafix Rule|Runtime Incompatibiltiy| +|--- |--- |--- |--- |--- | +|[Type of implicit def](#type-of-implicit-definition)|||[✅](https://scalacenter.github.io/scalafix/docs/rules/ExplicitResultTypes.html)|| +|[Implicit views](#implicit-views)||||**Possible**| +|[View bounds](#view-bounds)|Deprecation|||| +|[Ambiguous conversion on `A` and `=> A`](#ambiguous-conversion-on-a-and--a)||||| + +## Type Of Implicit Definition + +The type of implicit definitions (`val` or `def`) needs to be given explicitly in Scala 3. +They cannot be inferred anymore. + +The Scalafix rule named [ExplicitResultTypes](https://scalacenter.github.io/scalafix/docs/rules/ExplicitResultTypes.html) can write the missing type annotations automatically. + +## Implicit Views + +Scala 3 does not support implicit conversion from an implicit function value, of the form `implicit val ev: A => B`. + +{% tabs scala-2-implicit_1 %} +{% tab 'Scala 2 Only' %} + +The following piece of code is now invalid in Scala 3: +~~~ scala +trait Pretty { + val print: String +} + +def pretty[A](a: A)(implicit ev: A => Pretty): String = + a.print // In Scala 3, Error: value print is not a member of A +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) can warn you about those cases, but it does not try to fix it. + +Be aware that this incompatibility can produce a runtime incompatibility and break your program. +Indeed the compiler can find another implicit conversion from a broader scope, which would eventually cause an undesired behavior at runtime. + +{% tabs shared-implicit_2 %} +{% tab 'Scala 2 and 3' %} + +This example illustrates the case: +~~~ scala +trait Pretty { + val print: String +} + +implicit def anyPretty(any: Any): Pretty = new Pretty { val print = "any" } + +def pretty[A](a: A)(implicit ev: A => Pretty): String = + a.print // always print "any" +~~~ +{% endtab %} +{% endtabs %} + +The resolved conversion depends on the compiler mode: + - `-source:3.0-migration`: the compiler performs the `ev` conversion + - `-source:3.0`: the compiler cannot perform the `ev` conversion but it can perform the `anyPretty`, which is undesired + +In Scala 3, one simple fix is to supply the right conversion explicitly: + +{% highlight diff %} +def pretty[A](a: A)(implicit ev: A => Pretty): String = +- a.print ++ ev(a).print +{% endhighlight %} + +## View Bounds + +View bounds have been deprecated for a long time but they are still supported in Scala 2.13. +They cannot be compiled with Scala 3 anymore. + +{% tabs scala-2-bounds_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +def foo[A <% Long](a: A): Long = a +~~~ +{% endtab %} +{% endtabs %} + +In this example, in Scala 3, we get this following error message: + +{% highlight text %} +-- Error: src/main/scala/view-bound.scala:2:12 +2 | def foo[A <% Long](a: A): Long = a + | ^ + | view bounds `<%' are deprecated, use a context bound `:' instead +{% endhighlight %} + +The message suggests to use a context bound instead of a view bound but it would change the signature of the method. +It is probably easier and safer to preserve the binary compatibility. +To do so the implicit conversion must be declared and called explicitly. + +Be careful not to fall in the runtime incompatibility described above, in [Implicit Views](#implicit-views). + +{% highlight diff %} +-def foo[A <% Long](a: A): Long = a ++def foo[A](a: A)(implicit ev: A => Long): Long = ev(a) +{% endhighlight %} + +## Ambiguous Conversion On `A` And `=> A` + +In Scala 2.13 the implicit conversion on `A` wins over the implicit conversion on `=> A`. +It is not the case in Scala 3 anymore, and leads to an ambiguous conversion. + +For instance, in this example: + +{% tabs scala-2-ambiguous_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +implicit def boolFoo(bool: Boolean): Foo = ??? +implicit def lazyBoolFoo(lazyBool: => Boolean): Foo = ??? + +true.foo() +~~~ +{% endtab %} +{% endtabs %} + +The Scala 2.13 compiler chooses the `boolFoo` conversion but the Scala 3 compiler fails to compile. + +{% highlight text %} +-- Error: src/main/scala/ambiguous-conversion.scala:4:19 +9 | true.foo() + | ^^^^ + |Found: (true : Boolean) + |Required: ?{ foo: ? } + |Note that implicit extension methods cannot be applied because they are ambiguous; + |both method boolFoo in object Foo and method lazyBoolFoo in object Foo provide an extension method `foo` on (true : Boolean) +{% endhighlight %} + +A temporary solution is to write the conversion explicitly. + +{% highlight diff %} +implicit def boolFoo(bool: Boolean): Foo = ??? +implicit def lazyBoolFoo(lazyBool: => Boolean): Foo = ??? + +-true.foo() ++boolFoo(true).foo() +{% endhighlight %} diff --git a/_overviews/scala3-migration/incompat-dropped-features.md b/_overviews/scala3-migration/incompat-dropped-features.md new file mode 100644 index 0000000000..845a58b143 --- /dev/null +++ b/_overviews/scala3-migration/incompat-dropped-features.md @@ -0,0 +1,308 @@ +--- +title: Dropped Features +type: section +description: This chapter details all the dropped features +num: 18 +previous-page: incompat-syntactic +next-page: incompat-contextual-abstractions +--- + +Some features are dropped to simplify the language. +Most of these changes can be handled automatically during the [Scala 3 migration compilation](tooling-migration-mode.html). + +|Incompatibility|Scala 2.13|Scala 3 Migration Rewrite|Scalafix Rule| +|--- |--- |--- |--- | +|[Symbol literals](#symbol-literals)|Deprecation|✅|| +|[`do`-`while` construct](#do-while-construct)||✅|| +|[Auto-application](#auto-application)|Deprecation|✅|[✅](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNonNullaryApply.scala)| +|[Value eta-expansion](#value-eta-expansion)|Deprecation|✅|[✅](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNullaryEtaExpansion.scala)| +|[`any2stringadd` conversion](#any2stringadd-conversion)|Deprecation||[✅](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/Any2StringAdd.scala)| +|[Early initializer](#early-initializer)|Deprecation||| +|[Existential type](#existential-type)|Feature warning||| +|[@specialized](#specialized)|Deprecation||| + +## Symbol literals + +The Symbol literal syntax is deprecated in Scala 2.13 and dropped in Scala 3. +But the `scala.Symbol` class still exists so that each string literal can be safely replaced by an application of `Symbol`. + +This piece of code cannot be compiled with Scala 3: + +{% tabs scala-2-literals_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +val values: Map[Symbol, Int] = Map('abc -> 1) + +val abc = values('abc) // In Scala 3, Migration Warning: symbol literal 'abc is no longer supported +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) rewrites the code into: +{% highlight diff %} +val values: Map[Symbol, Int] = Map(Symbol("abc") -> 1) + +-val abc = values('abc) ++val abc = values(Symbol("abc")) +{% endhighlight %} + +Although the `Symbol` class is useful during the transition, beware that it is deprecated and will be removed from the `scala-library` in a future version. +You are recommended, as a second step, to replace every use of `Symbol` with a plain string literals `"abc"` or a custom dedicated class. + +## `do`-`while` construct + +The `do` keyword has acquired a different meaning in the [New Control Syntax]({{ site.scala3ref }}/other-new-features/control-syntax.html). + +To avoid confusion, the traditional `do while ()` construct is dropped. +It is recommended to use the equivalent `while ({ ; }) ()` that can be cross-compiled, or the new Scala 3 syntax `while { ; } do ()`. + +The following piece of code cannot be compiled with Scala 3. + +{% tabs scala-2-do_while_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +do { // In Scala 3, Migration Warning: `do while ` is no longer supported + i += 1 +} while (f(i) == 0) +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) rewrites it into. +{% tabs scala-3-do_while_2 %} +{% tab 'Scala 3 Only' %} +~~~ scala +while ({ { + i += 1 +} ; f(i) == 0}) () +~~~ +{% endtab %} +{% endtabs %} + +## Auto-application + +Auto-application is the syntax of calling an empty-paren method such as `def toInt(): Int` without passing an empty argument list. +It is deprecated in Scala 2.13 and dropped in Scala 3. + +The following code is invalid in Scala 3: + +{% tabs scala-2-auto_application_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +object Hello { + def message(): String = "Hello" +} + +println(Hello.message) // In Scala 3, Migration Warning: method message must be called with () argument +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) rewrites it into: +{% highlight diff %} +object Hello { + def message(): String = "Hello" +} + +-println(Hello.message) ++println(Hello.message()) +{% endhighlight %} + +Auto-application is covered in detail in [this page]({{ site.scala3ref }}/dropped-features/auto-apply.html) of the Scala 3 reference documentation. + +## Value eta-expansion + +Scala 3 introduces [Automatic Eta-Expansion]({{ site.scala3ref }}/changed-features/eta-expansion-spec.html) which will deprecate the method to value syntax `m _`. +Furthermore Scala 3 does not allow eta-expansion of values to nullary functions anymore. + +Thus, this piece of code is invalid in Scala 3: + +{% tabs scala-2-eta_expansion_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +val x = 1 +val f: () => Int = x _ // In Scala 3, Migration Warning: The syntax ` _` is no longer supported; +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) rewrites it into: +{% highlight diff %} +val x = 1 +-val f: () => Int = x _ ++val f: () => Int = (() => x) +{% endhighlight %} + +## `any2stringadd` conversion + +The implicit `Predef.any2stringadd` conversion is deprecated in Scala 2.13 and dropped in Scala 3. + +This piece of code does not compile anymore in Scala 3. + +{% tabs scala-2-any2stringadd_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +val str = new AnyRef + "foo" // In Scala 3, Error: value + is not a member of Object +~~~ +{% endtab %} +{% endtabs %} + +The conversion to `String` must be applied explicitly, for instance with `String.valueOf`. +{% highlight diff %} +-val str = new AnyRef + "foo" ++val str = String.valueOf(new AnyRef) + "foo" +{% endhighlight %} + +This rewrite can be applied by the `fix.scala213.Any2StringAdd` Scalafix rule in [`scala/scala-rewrites`](https://index.scala-lang.org/scala/scala-rewrites/scala-rewrites/0.1.2?target=_2.13). + +## Early Initializer + +Early initializers are deprecated in Scala 2.13 and dropped in Scala 3. +They were rarely used, and mostly to compensate for the lack of [Trait parameters]({{ site.scala3ref }}/other-new-features/trait-parameters.html) which are now supported in Scala 3. + +That is why the following piece of code does not compile anymore in Scala 3. + +{% tabs scala-2-initializer_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +trait Bar { + val name: String + val size: Int = name.size +} + +object Foo extends { + val name = "Foo" +} with Bar +~~~ +{% endtab %} +{% endtabs %} + +The Scala 3 compiler produces two error messages: + +{% highlight text %} +-- Error: src/main/scala/early-initializer.scala:6:19 +6 |object Foo extends { + | ^ + | `extends` must be followed by at least one parent +{% endhighlight %} +{% highlight text %} +-- [E009] Syntax Error: src/main/scala/early-initializer.scala:8:2 +8 |} with Bar + | ^^^^ + | Early definitions are not supported; use trait parameters instead +{% endhighlight %} + +It suggests to use trait parameters which would give us: + +{% tabs scala-3-initializer_2 %} +{% tab 'Scala 3 Only' %} +~~~ scala +trait Bar(name: String) { + val size: Int = name.size +} + +object Foo extends Bar("Foo") +~~~ +{% endtab %} +{% endtabs %} + +Since trait parameters are not available in Scala 2.13, it does not cross-compile. +If you need a cross-compiling solution you can use an intermediate class that carries the early initialized `val`s and `var`s as constructor parameters. + +{% tabs shared-initializer_4 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +abstract class BarEarlyInit(val name: String) extends Bar + +object Foo extends BarEarlyInit("Foo") +~~~ + +In the case of a class, it is also possible to use a secondary constructor with a fixed value, as shown by: +~~~ scala +class Fizz private (val name: String) extends Bar { + def this() = this("Fizz") +} +~~~ +{% endtab %} +{% endtabs %} + +Another use case for early initializers in Scala 2 is private state in the subclass that is accessed (through an overridden method) by the constructor of the superclass: + +{% tabs scala-2-initializer_5 %} +{% tab 'Scala 2 Only' %} +~~~ scala +class Adder { + var sum = 0 + def add(x: Int): Unit = sum += x + add(1) +} +class LogAdder extends { + private var added: Set[Int] = Set.empty +} with Adder { + override def add(x: Int): Unit = { added += x; super.add(x) } +} +~~~ +{% endtab %} +{% endtabs %} + +This case can be refactored by moving the private state into a nested `object`, which is initialized on demand: + +{% tabs shared-initializer_6 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +class Adder { + var sum = 0 + def add(x: Int): Unit = sum += x + add(1) +} +class LogAdder extends Adder { + private object state { + var added: Set[Int] = Set.empty + } + import state._ + override def add(x: Int): Unit = { added += x; super.add(x) } +} +~~~ +{% endtab %} +{% endtabs %} + +## Existential Type + +Existential type is a [dropped feature]({{ site.scala3ref }}/dropped-features/existential-types.html), which makes the following code invalid. + +{% tabs scala-2-existential_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +def foo: List[Class[T]] forSome { type T } // In Scala 3, Error: Existential types are no longer supported +~~~ +{% endtab %} +{% endtabs %} + +> Existential type is an experimental feature in Scala 2.13 that must be enabled explicitly either by importing `import scala.language.existentials` or by setting the `-language:existentials` compiler flag. + +In Scala 3, the proposed solution is to introduce an enclosing type that carries the dependent type: + +{% tabs shared-existential_1 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +trait Bar { + type T + val value: List[Class[T]] +} + +def foo: Bar +~~~ +{% endtab %} +{% endtabs %} + +Note that using a wildcard argument, `_` or `?`, is often simpler but is not always possible. +For instance you could replace `List[T] forSome { type T }` by `List[?]`. + +## Specialized + +The `@specialized` annotation from Scala 2 is ignored in Scala 3. + +However, there is limited support for specialized `Function` and `Tuple`. + +Similar benefits can be derived from `inline` declarations. + diff --git a/_overviews/scala3-migration/incompat-other-changes.md b/_overviews/scala3-migration/incompat-other-changes.md new file mode 100644 index 0000000000..a7a003d8ec --- /dev/null +++ b/_overviews/scala3-migration/incompat-other-changes.md @@ -0,0 +1,328 @@ +--- +title: Other Changed Features +type: section +description: This chapter details all incompatibilities caused by changed features +num: 20 +previous-page: incompat-contextual-abstractions +next-page: incompat-type-checker +--- + +Some other features are simplified or restricted to make the language easier, safer or more consistent. + +|Incompatibility|Scala 3 Migration Rewrite| +|--- |--- | +|[Inheritance shadowing](#inheritance-shadowing)|✅| +|[Non-private constructor in private class](#non-private-constructor-in-private-class)|Migration Warning| +|[Abstract override](#abstract-override)|| +|[Case class companion](#case-class-companion)|| +|[Explicit call to unapply](#explicit-call-to-unapply)|| +|[Invisible bean property](#invisible-bean-property)|| +|[`=>T` as type argument](#-t-as-type-argument)|| +|[Wildcard type argument](#wildcard-type-argument)|| + +## Inheritance Shadowing + +An inherited member, from a parent trait or class, can shadow an identifier defined in an outer scope. +That pattern is called inheritance shadowing. + +{% tabs shared-inheritance_1 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +object B { + val x = 1 + class C extends A { + println(x) + } +} +~~~ +{% endtab %} +{% endtabs %} + +For instance, in this preceding piece of code, the `x` term in C can refer to the `x` member defined in the outer class `B` or it can refer to a `x` member of the parent class `A`. +You cannot know until you go to the definition of `A`. + +This is known for being error prone. + +That's why, in Scala 3, the compiler requires disambiguation if the parent class `A` does actually have a member `x`. + +It prevents the following piece of code from compiling. +{% tabs scala-2-inheritance_2 %} +{% tab 'Scala 2 Only' %} +~~~ scala +class A { + val x = 2 +} + +object B { + val x = 1 + class C extends A { + println(x) + } +} +~~~ +{% endtab %} +{% endtabs %} + +But if you try to compile with Scala 3 you should see an error of the same kind as: +{% highlight text %} +-- [E049] Reference Error: src/main/scala/inheritance-shadowing.scala:9:14 +9 | println(x) + | ^ + | Reference to x is ambiguous, + | it is both defined in object B + | and inherited subsequently in class C +{% endhighlight %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) can automatically disambiguate the code by replacing `println(x)` with `println(this.x)`. + +## Non-private Constructor In Private Class + +The Scala 3 compiler requires the constructor of private classes to be private. + +For instance, in the example: +{% tabs scala-2-constructor_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +package foo + +private class Bar private[foo] () {} +~~~ +{% endtab %} +{% endtabs %} + +If you try to compile in scala 3 you should get the following error message: +{% highlight text %} +-- Error: /home/piquerez/scalacenter/scala-3-migration-guide/incompat/access-modifier/src/main/scala-2.13/access-modifier.scala:4:19 +4 | private class Bar private[foo] () + | ^ + | non-private constructor Bar in class Bar refers to private class Bar + | in its type signature (): foo.Foo.Bar +{% endhighlight %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) warns about this but no automatic rewrite is provided. + +The solution is to make the constructor private, since the class is private. + +## Abstract Override + +In Scala 3, overriding a concrete def with an abstract def causes subclasses to consider the def abstract, whereas in Scala 2 it was considered as concrete. + +In the following piece of code, the `bar` method in `C` is considered concrete by the Scala 2.13 compiler but abstract by the Scala 3 compiler, causing the following error. +{% tabs scala-2-abstract_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +trait A { + def bar(x: Int): Int = x + 3 +} + +trait B extends A { + def bar(x: Int): Int +} + +class C extends B // In Scala 3, Error: class C needs to be abstract, since def bar(x: Int): Int is not defined +~~~ +{% endtab %} +{% endtabs %} + +This behavior was decided in [Dotty issue #4770](https://github.com/scala/scala3/issues/4770). + +An easy fix is simply to remove the abstract def, since in practice it had no effect in Scala 2. + +## Case Class Companion + +The companion object of a case class does not extend any of the `Function{0-23}` traits anymore. +In particular, it does not inherit their methods: `tupled`, `curried`, `andThen`, `compose`... + +For instance, this is not permitted anymore: +{% tabs scala-2-companion_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +case class Foo(x: Int, b: Boolean) + +Foo.curried(1)(true) +Foo.tupled((2, false)) +~~~ +{% endtab %} +{% endtabs %} + +A cross-compiling solution is to explicitly eta-expand the method `Foo.apply`. +{% highlight diff %} + +-Foo.curried(1)(true) ++(Foo.apply _).curried(1)(true) + +-Foo.tupled((2, false)) ++(Foo.apply _).tupled((2, false)) +{% endhighlight %} + +Or, for performance reasons, you can introduce an intermediate function value. +{% tabs scala-3-companion_2 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +val fooCtr: (Int, Boolean) => Foo = (x, b) => Foo(x, b) + +fooCtr.curried(1)(true) +fooCtr.tupled((2, false)) +~~~ +{% endtab %} +{% endtabs %} +## Explicit Call to `unapply` + +In Scala, case classes have an auto-generated extractor method, called `unapply` in their companion object. +Its signature has changed between Scala 2.13 and Scala 3. + +The new signature is option-less (see the new [Pattern Matching]({{ site.scala3ref }}/changed-features/pattern-matching.html) reference), which causes an incompatibility when `unapply` is called explicitly. + +Note that this problem does not affect user-defined extractors, whose signature stays the same across Scala versions. + +Given the following case class definition: +{% tabs shared-unapply_1 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +case class Location(lat: Double, long: Double) +~~~ +{% endtab %} +{% endtabs %} + +The Scala 2.13 compiler generates the following `unapply` method: +{% tabs scala-2-unapply_2 %} +{% tab 'Scala 2 Only' %} +~~~ scala +object Location { + def unapply(location: Location): Option[(Double, Double)] = Some((location.lat, location.long)) +} +~~~ +{% endtab %} +{% endtabs %} + +Whereas the Scala 3 compiler generates: +{% tabs scala-3-unapply_2 %} +{% tab 'Scala 3 Only' %} +~~~ scala +object Location { + def unapply(location: Location): Location = location +} +~~~ +{% endtab %} +{% endtabs %} + +Consequently the following code does not compile anymore in Scala 3. +{% tabs scala-2-unapply_3 %} +{% tab 'Scala 2 Only' %} +~~~ scala +def tuple(location: Location): (Int, Int) = { + Location.unapply(location).get // [E008] In Scala 3, Not Found Error: value get is not a member of Location +} +~~~ +{% endtab %} +{% endtabs %} + +A possible solution, in Scala 3, is to use pattern binding: + +{% highlight diff %} +def tuple(location: Location): (Int, Int) = { +- Location.unapply(location).get ++ val Location(lat, lon) = location ++ (lat, lon) +} +{% endhighlight %} + +## Invisible Bean Property + +The getter and setter methods generated by the `BeanProperty` annotation are now invisible in Scala 3 because their primary use case is the interoperability with Java frameworks. + +For instance, the below Scala 2 code would fail to compile in Scala 3: +{% tabs scala-2-bean_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +class Pojo() { + @BeanProperty var fooBar: String = "" +} + +val pojo = new Pojo() + +pojo.setFooBar("hello") // [E008] In Scala 3, Not Found Error: value setFooBar is not a member of Pojo + +println(pojo.getFooBar()) // [E008] In Scala 3, Not Found Error: value getFooBar is not a member of Pojo +~~~ +{% endtab %} +{% endtabs %} + +In Scala 3, the solution is to call the more idiomatic `pojo.fooBar` getter and setter. + +{% highlight diff %} +val pojo = new Pojo() + +-pojo.setFooBar("hello") ++pojo.fooBar = "hello" + +-println(pojo.getFooBar()) ++println(pojo.fooBar) +{% endhighlight %} + +## `=> T` as Type Argument + +A type of the form `=> T` cannot be used as an argument to a type parameter anymore. + +This decision is explained in [this comment](https://github.com/scala/scala3/blob/0f1a23e008148f76fd0a1c2991b991e1dad600e8/compiler/src/dotty/tools/dotc/core/ConstraintHandling.scala#L144-L152) of the Scala 3 source code. + +For instance, it is not allowed to pass a function of type `Int => (=> Int) => Int` to the `uncurried` method since it would assign `=> Int` to the type parameter `T2`. + +{% highlight text %} +-- [E134] Type Mismatch Error: src/main/scala/by-name-param-type-infer.scala:3:41 +3 | val g: (Int, => Int) => Int = Function.uncurried(f) + | ^^^^^^^^^^^^^^^^^^ + |None of the overloaded alternatives of method uncurried in object Function with types + | [T1, T2, T3, T4, T5, R] + | (f: T1 => T2 => T3 => T4 => T5 => R): (T1, T2, T3, T4, T5) => R + | [T1, T2, T3, T4, R](f: T1 => T2 => T3 => T4 => R): (T1, T2, T3, T4) => R + | [T1, T2, T3, R](f: T1 => T2 => T3 => R): (T1, T2, T3) => R + | [T1, T2, R](f: T1 => T2 => R): (T1, T2) => R + |match arguments ((Test.f : Int => (=> Int) => Int)) +{% endhighlight %} + +The solution depends on the situation. In the given example, you can either: + - define your own `uncurried` method with the appropriate signature + - inline the implementation of `uncurried` locally + +## Wildcard Type Argument + +Scala 3 cannot reduce the application of a higher-kinded abstract type member to the wildcard argument. + +For instance, the below Scala 2 code would fail to compile in Scala 3: +{% tabs scala-2-wildcard_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +trait Example { + type Foo[A] + + def f(foo: Foo[_]): Unit // [E043] In Scala 3, Type Error: unreducible application of higher-kinded type Example.this.Foo to wildcard arguments +} +~~~ +{% endtab %} +{% endtabs %} + +We can fix this by using a type parameter: + +{% highlight diff %} +-def f(foo: Foo[_]): Unit ++def f[A](foo: Foo[A]): Unit +{% endhighlight %} + +But this simple solution does not work when `Foo` is itself used as a type argument. +{% tabs scala-2-wildcard_2 %} +{% tab 'Scala 2 Only' %} +~~~ scala +def g(foos: Seq[Foo[_]]): Unit +~~~ +{% endtab %} +{% endtabs %} + +In such case, we can use a wrapper class around `Foo`: + +{% highlight diff %} ++class FooWrapper[A](foo: Foo[A]) + +-def g(foos: Seq[Foo[_]]): Unit ++def g(foos: Seq[FooWrapper[_]]): Unit +{% endhighlight %} \ No newline at end of file diff --git a/_overviews/scala3-migration/incompat-syntactic.md b/_overviews/scala3-migration/incompat-syntactic.md new file mode 100644 index 0000000000..0e88e2b034 --- /dev/null +++ b/_overviews/scala3-migration/incompat-syntactic.md @@ -0,0 +1,239 @@ +--- +title: Syntactic Changes +type: section +description: This chapter details all the incompatibilities caused by syntactic changes +num: 17 +previous-page: incompatibility-table +next-page: incompat-dropped-features +--- + +Scala 3 introduces the optional-braces syntax and the new control structure syntax. +It comes at the cost of some minimal restrictions in the preexisting syntax. + +Other syntactic changes are intended to make the syntax less surprising and more consistent. + +It is worth noting that most of the changes can be automatically handled during the [Scala 3 migration compilation](tooling-migration-mode.html). + +|Incompatibility|Scala 2.13|Scala 3 Migration Rewrite|Scalafix Rule| +|--- |--- |--- |--- | +|[Restricted keywords](#restricted-keywords)||✅|| +|[Procedure syntax](#procedure-syntax)|Deprecation|✅|[✅](https://scalacenter.github.io/scalafix/docs/rules/ProcedureSyntax.html)| +|[Parentheses around lambda parameter](#parentheses-around-lambda-parameter)||✅|| +|[Open brace indentation for passing an argument](#open-brace-indentation-for-passing-an-argument)||✅|| +|[Wrong indentation](#wrong-indentation)|||| +|[`_` as a type parameter](#_-as-a-type-parameter)|||| +|[`+` and `-` as type parameters](#-and---as-type-parameters)|||| + +## Restricted Keywords + +The list of Scala 3 keywords can be found [here](https://dotty.epfl.ch/docs/internals/syntax.html#keywords). +_Regular_ keywords cannot be used as identifiers, whereas _soft_ keywords are not restricted. + +For the matter of migrating from Scala 2.13 to Scala 3, only the subset of new _regular_ keywords are problematic. +It is composed of: +- `enum` +- `export` +- `given` +- `then` +- `=>>` +- `?=>` + +{% tabs scala-2-keywords_1 %} +{% tab 'Scala 2 Only' %} + +For instance, the following piece of code can be compiled with Scala 2.13 but not with Scala 3. +~~~ scala +object given { // In Scala 3, Error: given is now a keyword. + val enum = ??? // In Scala 3, Error: enum is now a keyword. + + println(enum) // In Scala 3, Error: enum is now a keyword. +} +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) rewrites the code into: +{% highlight diff %} +-object given { ++object `given` { +- val enum = ??? ++ val `enum` = ??? + +- println(enum) ++ println(`enum`) + } +{% endhighlight %} + +## Procedure Syntax + +Procedure syntax has been deprecated for a while and it is dropped in Scala 3. + +{% tabs scala-2-procedure_1 %} +{% tab 'Scala 2 Only' %} + +The following pieces of code are now illegal: +~~~ scala +object Bar { + def print() { // In Scala 3, Error: Procedure syntax no longer supported; `: Unit =` should be inserted here. + println("bar") + } +} +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) rewrites the code into. +{% highlight diff %} + object Bar { +- def print() { ++ def print(): Unit = { + println("bar") + } + } +{% endhighlight %} + +## Parentheses Around Lambda Parameter + +When followed by its type, the parameter of a lambda is now required to be enclosed in parentheses. +The following piece of code is invalid. + +{% tabs scala-2-lambda_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +val f = { x: Int => x * x } // In Scala 3, Error: parentheses are required around the parameter of a lambda. +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compilation](tooling-migration-mode.html) rewrites the code into: +{% highlight diff %} +-val f = { x: Int => x * x } ++val f = { (x: Int) => x * x } +{% endhighlight %} + +## Open Brace Indentation For Passing An Argument + +In Scala 2 it is possible to pass an argument after a new line by enclosing it into braces. +Although valid, this style of coding is not encouraged by the [Scala style guide](https://docs.scala-lang.org/style) and is no longer supported in Scala 3. + +{% tabs scala-2-brace_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +test("my test") +{ // In Scala 3, Error: This opening brace will start a new statement. + assert(1 == 1) +} +~~~ +{% endtab %} +{% endtabs %} + +The [Scala 3 migration compiler](tooling-migration-mode.html) indents the first line of the block. +{% highlight diff %} + test("my test") +-{ ++ { + assert(1 == 1) + } +{% endhighlight %} + +This migration rule applies to other patterns as well, such as refining a type after a new line. + +{% highlight diff %} + type Bar = Foo +-{ ++ { + def bar(): Int + } +{% endhighlight %} + +A preferable solution is to write: +{% highlight diff %} +-test("my test") +-{ ++test("my test") { + assert(1 == 1) + } +{% endhighlight %} + +## Wrong indentation + +The Scala 3 compiler now requires correct indentation. +The following piece of code, that was compiled in Scala 2.13, does not compile anymore because of the indentation. + +{% tabs scala-2-indentation_1 %} +{% tab 'Scala 2 Only' %} + +~~~ scala +def bar: (Int, Int) = { + val foo = 1.0 + val bar = foo // [E050] In Scala 3, type Error: value foo does not take parameters. + (1, 1) +} // [E007] In Scala 3, type Mismatch Error: Found Unit, Required (Int, Int). +~~~ +{% endtab %} +{% endtabs %} + +The indentation must be fixed. +{% highlight diff %} + def bar: (Int, Int) = { + val foo = 1.0 + val bar = foo +- (1, 1) ++ (1, 1) + } +{% endhighlight %} + +These errors can be prevented by using a Scala formatting tool such as [scalafmt](https://scalameta.org/scalafmt/) or the [IntelliJ Scala formatter](https://www.jetbrains.com/help/idea/reformat-and-rearrange-code.html). +Beware that these tools may change the entire code style of your project. + +## `_` As A Type Parameter + +The usage of the `_` identifier as a type parameter is permitted in Scala 2.13, even if it has never been mentioned in the Scala 2 specification. +It is used in the API of [fastparse](https://index.scala-lang.org/lihaoyi/fastparse), in combination with a context bound, to declare an implicit parameter. + +{% tabs scala-2-identifier_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +def foo[_: Foo]: Unit = ??? +~~~ +{% endtab %} +{% endtabs %} + +Here, the method `foo` takes a type parameter `_` and an implicit parameter of type `Foo[_]` where `_` refers to the type parameter, not the wildcard symbol. + +Martin Odersky described this pattern as a "clever exploit of a scalac compiler bug" ([source](https://www.reddit.com/r/scala/comments/fczcvo/mysterious_context_bounds_in_fastparse_2/fjecokn/)). + +The Scala 3 compiler does not permit this pattern anymore: + +{% highlight text %} +-- [E040] Syntax Error: src/main/scala/anonymous-type-param.scala:4:10 +4 | def foo[_: Foo]: Unit = () + | ^ + | an identifier expected, but '_' found +{% endhighlight %} + +The solution is to give the parameter a valid identifier name, for instance `T`. +This will not break the binary compatibility. + +{% highlight diff %} +-def foo[_: Foo]: Unit = ??? ++def foo[T: Foo]: Unit = ??? +{% endhighlight %} + +## `+` And `-` As Type Parameters + +`+` and `-` are not valid identifiers for type parameters in Scala 3, since they are reserved for variance annotation. + +You cannot write `def foo[+]` or `def foo[-]` anymore. + +{% highlight text %} +-- Error: src/main/scala/type-param-identifier.scala:2:10 +2 | def foo[+]: + + | ^ + | no `+/-` variance annotation allowed here +{% endhighlight %} + +The solution is to choose another valid identifier, for instance `T`. + +However, `+` and `-` still are valid type identifiers in general. +You can write `type +`. diff --git a/_overviews/scala3-migration/incompat-type-checker.md b/_overviews/scala3-migration/incompat-type-checker.md new file mode 100644 index 0000000000..41afc5ebc7 --- /dev/null +++ b/_overviews/scala3-migration/incompat-type-checker.md @@ -0,0 +1,130 @@ +--- +title: Type Checker +type: section +description: This chapter details the unsoundness fixes in the type checker +num: 21 +previous-page: incompat-other-changes +next-page: incompat-type-inference +--- + +The Scala 2.13 type checker is unsound in some specific cases. +This can lead to surprising runtime errors in places we would not expect. +Scala 3 being based on stronger theoretical foundations, these unsoundness bugs in the type checker are now fixed. + +## Unsoundness Fixes in Variance checks + +In Scala 2, default parameters and inner-classes are not subject to variance checks. +It is unsound and might cause runtime failures, as demonstrated by this [test](https://github.com/scala/scala3/blob/10526a7d0aa8910729b6036ee51942e05b71abf6/tests/neg/variances.scala) in the Scala 3 repository. + +The Scala 3 compiler does not permit this anymore. + +{% tabs scala-2-unsound_vc_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +class Foo[-A](x: List[A]) { + def f[B](y: List[B] = x): Unit = ??? +} + +class Outer[+A](x: A) { + class Inner(y: A) +} +~~~ +{% endtab %} +{% endtabs %} + +So if you compile in Scala 3, you will get the following error. +{% highlight text %} +-- Error: src/main/scala/variance.scala:2:8 +2 | def f[B](y: List[B] = x): Unit = y + | ^^^^^^^^^^^^^^^^^ + |contravariant type A occurs in covariant position in type [B] => List[A] of method f$default$1 +-- Error: src/main/scala/variance.scala:6:14 +6 | class Inner(y: A) + | ^^^^ + |covariant type A occurs in contravariant position in type A of parameter y +{% endhighlight %} + +Each problem of this kind needs a specific care. +You can try the following options on a case-by-case basis: +- Make type `A` invariant +- Add a lower or an upper bound on a type parameter `B` +- Add a new method overload + +In our example, we can opt for these two solutions: + +{% highlight diff %} +class Foo[-A](x: List[A]) { +- def f[B](y: List[B] = x): Unit = ??? ++ def f[B](y: List[B]): Unit = ??? ++ def f(): Unit = f(x) +} + +class Outer[+A](x: A) { +- class Inner(y: A) ++ class Inner[B >: A](y: B) +} +{% endhighlight %} + +Or, as a temporary solution, you can also use the `uncheckedVariance` annotation: + +{% highlight diff %} +class Outer[+A](x: A) { +- class Inner(y: A) ++ class Inner(y: A @uncheckedVariance) +} +{% endhighlight %} + +## Unsoundness Fixes in Pattern Matching + +Scala 3 fixes some unsoundness bugs in pattern matching, preventing some semantically wrong match expressions to type check. + +For instance, the match expression in `combineReq` can be compiled with Scala 2.13 but not with Scala 3. + +{% tabs scala-2-unsound_pm_1 %} +{% tab 'Scala 2 Only' %} +~~~ scala +trait Request +case class Fetch[A](ids: Set[A]) extends Request + +object Request { + def combineFetch[A](x: Fetch[A], y: Fetch[A]): Fetch[A] = Fetch(x.ids ++ y.ids) + + def combineReq(x: Request, y: Request): Request = { + (x, y) match { + case (x @ Fetch(_), y @ Fetch(_)) => combineFetch(x, y) + } + } +} +~~~ +{% endtab %} +{% endtabs %} + +In Scala 3, the error message is: + +{% highlight text %} +-- [E007] Type Mismatch Error: src/main/scala/pattern-match.scala:9:59 +9 | case (x @ Fetch(_), y @ Fetch(_)) => combineFetch(x, y) + | ^ + | Found: (y : Fetch[A$2]) + | Required: Fetch[A$1] +{% endhighlight %} + + +Which is right, there is no proof that `x` and `y` have the same type parameter `A`. + +Coming from Scala 2, this is clearly an improvement to help us locate mistakes in our code. +To solve this incompatibility it is better to find a solution that can be checked by the compiler. +It is not always easy and sometimes it is even not possible, in which case the code is likely to fail at runtime. + +In this example, we can relax the constraint on `x` and `y` by stating that `A` is a common ancestor of both type arguments. +This makes the compiler type-check the code successfully. +{% tabs shared-unsound_pm_2 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +def combineFetch[A](x: Fetch[_ <: A], y: Fetch[_ <: A]): Fetch[A] = Fetch(x.ids ++ y.ids) +~~~ +{% endtab %} +{% endtabs %} + +Alternatively, a general but unsafe solution is to cast. + diff --git a/_overviews/scala3-migration/incompat-type-inference.md b/_overviews/scala3-migration/incompat-type-inference.md new file mode 100644 index 0000000000..bb6fc3052a --- /dev/null +++ b/_overviews/scala3-migration/incompat-type-inference.md @@ -0,0 +1,107 @@ +--- +title: Type Inference +type: section +description: This chapter details the incompatibilities caused by the new type inference algorithm +num: 22 +previous-page: incompat-type-checker +next-page: options-intro +--- + +The two incompatibilities described in this page are intentional changes in the type inference rules. + +Other incompatibilities could be caused by the replacement of the type inference algorithm. +The new algorithm is better than the old one, but sometime it can fail where Scala 2.13 would succeed: + +> It is always good practice to write the result types of all public values and methods explicitly. +> It prevents the public API of your library from changing with the Scala version, because of different inferred types. +> +> This can be done prior to the Scala 3 migration by using the [ExplicitResultTypes](https://scalacenter.github.io/scalafix/docs/rules/ExplicitResultTypes.html) rule in Scalafix. + +## Return Type of an Override Method + +In Scala 3 the return type of an override method is inferred by inheritance from the base method, whereas in Scala 2.13 it is inferred from the left hand side of the override method. + +{% tabs define_parent_child %} +{% tab 'Scala 2 and 3' %} +```scala +class Foo + +class RichFoo(foo: Foo) extends Foo { + def show: String = "" +} + +class Parent { + def foo: Foo = new Foo +} + +class Child extends Parent { + override def foo = new RichFoo(super.foo) +} +``` +{% endtab %} +{% endtabs %} + +In this example, `Child#foo` returns a `RichFoo` in Scala 2.13 but a `Foo` in Scala 3. +It can lead to compiler errors as demonstrated below. + +{% tabs extend_parent_child %} +{% tab 'Scala 3 Only' %} +```scala +(new Child).foo.show // Scala 3 error: value show is not a member of Foo +``` +{% endtab %} +{% endtabs %} + +In some rare cases involving implicit conversions and runtime casting it could even cause a runtime failure. + +The solution is to make the return type of the override method explicit so that it matches what is inferred in 2.13: + +{% highlight diff %} +class Child extends Parent { +- override def foo = new RichFoo(super.foo) ++ override def foo: RichFoo = new RichFoo(super.foo) +} +{% endhighlight %} + +## Reflective Type + +Scala 2 reflective calls are dropped and replaced by the broader [Programmatic Structural Types]({{ site.scala3ref }}/changed-features/structural-types.html). + +Scala 3 can imitate Scala 2 reflective calls by making `scala.reflect.Selectable.reflectiveSelectable` available wherever `scala.language.reflectiveCalls` is imported. + +{% tabs define_structural %} +{% tab 'Scala 2 and 3' %} +```scala +import scala.language.reflectiveCalls + +val foo = new { + def bar: Unit = ??? +} +``` +{% endtab %} +{% endtabs %} + +However the Scala 3 compiler does not infer structural types by default. +It infers the type `Object` for `foo` instead of `{ def bar: Unit }`. +Therefore, the following structural selection fails to compile: + +{% tabs use_structural %} +{% tab 'Scala 3 Only' %} +```scala +foo.bar // Error: value bar is not a member of Object +``` +{% endtab %} +{% endtabs %} + +The straightforward solution is to explicitly write down the structural type. + +{% highlight diff %} +import scala.language.reflectiveCalls + +- val foo = new { ++ val foo: { def bar: Unit } = new { + def bar: Unit = ??? +} + +foo.bar +{% endhighlight %} diff --git a/_overviews/scala3-migration/incompatibility-table.md b/_overviews/scala3-migration/incompatibility-table.md new file mode 100644 index 0000000000..9fc9f8bf18 --- /dev/null +++ b/_overviews/scala3-migration/incompatibility-table.md @@ -0,0 +1,126 @@ +--- +title: Incompatibility Table +type: chapter +description: This chapter list all the known incompatibilities between Scala 2.13 and Scala 3 +num: 16 +previous-page: tooling-syntax-rewriting +next-page: incompat-syntactic +--- + +An incompatibility is a piece of code that can be compiled with Scala 2.13 but not with Scala 3. +Migrating a codebase involves finding and fixing all the incompatibilities of the source code. +On rare occasions we can also have a runtime incompatibility: a piece of code that behaves differently at runtime. + +In this page we propose a classification of the known incompatibilities. +Each incompatibility is described by: + - Its short name with a link towards the detailed description and proposed solutions + - Whether the Scala 2.13 compiler emits a deprecation or a feature warning + - The existence of a [Scala 3 migration](tooling-migration-mode.html) rule for it + - The existence of a Scalafix rule that can fix it + +> #### Scala 2.13 deprecations and feature warnings +> Run the 2.13 compilation with `-Xsource:3` to locate those incompatibilities in the code. + +> #### Scala 3 migration versus Scalafix rewrites +> The Scala 3 migration mode comes out-of-the-box. +> On the contrary, Scalafix is a tool that must be installed and configured manually. +> However Scalafix has its own advantages: +> - It runs on Scala 2.13. +> - It is composed of individual rules that you can apply one at a time. +> - It is easily extensible by adding custom rules. + +### Syntactic Changes + +Some of the old syntax is not supported anymore. + +|Incompatibility|Scala 2.13|Scala 3 Migration Rewrite|Scalafix Rule| +|--- |--- |--- |--- | +|[Restricted keywords](incompat-syntactic.html#restricted-keywords)||✅|| +|[Procedure syntax](incompat-syntactic.html#procedure-syntax)|Deprecation|✅|[✅](https://scalacenter.github.io/scalafix/docs/rules/ProcedureSyntax.html)| +|[Parentheses around lambda parameter](incompat-syntactic.html#parentheses-around-lambda-parameter)||✅|| +|[Open brace indentation for passing an argument](incompat-syntactic.html#open-brace-indentation-for-passing-an-argument)||✅|| +|[Wrong indentation](incompat-syntactic.html#wrong-indentation)|||| +|[`_` as a type parameter](incompat-syntactic.html#_-as-a-type-parameter)|||| +|[`+` and `-` as type parameters](incompat-syntactic.html#-and---as-type-parameters)|||| + +### Dropped Features + +Some features are dropped to simplify the language. + +|Incompatibility|Scala 2.13|Scala 3 Migration Rewrite|Scalafix Rule| +|--- |--- |--- |--- | +|[Symbol literals](incompat-dropped-features.html#symbol-literals)|Deprecation|✅|| +|[`do`-`while` construct](incompat-dropped-features.html#do-while-construct)||✅|| +|[Auto-application](incompat-dropped-features.html#auto-application)|Deprecation|✅|[✅](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNonNullaryApply.scala)| +|[Value eta-expansion](incompat-dropped-features.html#value-eta-expansion)|Deprecation|✅|[✅](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNullaryEtaExpansion.scala)| +|[`any2stringadd` conversion](incompat-dropped-features.html#any2stringadd-conversion)|Deprecation||[✅](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/Any2StringAdd.scala)| +|[Early initializer](incompat-dropped-features.html#early-initializer)|Deprecation||| +|[Existential type](incompat-dropped-features.html#existential-type)|Feature warning||| + +### Contextual Abstractions + +The redesign of [contextual abstractions]({{ site.scala3ref }}/contextual) brings some well defined incompatibilities. + +|Incompatibility|Scala 2.13|Scala 3 Migration Rewrite|Scalafix Rule|Runtime Incompatibility| +|--- |--- |--- |--- |--- | +|[Type of implicit def](incompat-contextual-abstractions.html#type-of-implicit-definition)|||[✅](https://scalacenter.github.io/scalafix/docs/rules/ExplicitResultTypes.html)|| +|[Implicit views](incompat-contextual-abstractions.html#implicit-views)||||**Possible**| +|[View bounds](incompat-contextual-abstractions.html#view-bounds)|Deprecation|||| +|[Ambiguous conversion on `A` and `=> A`](incompat-contextual-abstractions.html#ambiguous-conversion-on-a-and--a)||||| + +Furthermore we have changed the implicit resolution rules so that they are more useful and less surprising. +The new rules are described [here]({{ site.scala3ref }}/changed-features/implicit-resolution.html). + +Because of these changes, the Scala 3 compiler could possibly fail at resolving some implicit parameters of existing Scala 2.13 code. + +### Other Changed Features + +Some other features are simplified or restricted to make the language easier, safer or more consistent. + +|Incompatibility|Scala 3 Migration Rewrite| +|--- |--- | +|[Inheritance shadowing](incompat-other-changes.html#inheritance-shadowing)|✅| +|[Non-private constructor in private class](incompat-other-changes.html#non-private-constructor-in-private-class)|Migration Warning| +|[Abstract override](incompat-other-changes.html#abstract-override)|| +|[Case class companion](incompat-other-changes.html#case-class-companion)|| +|[Explicit call to unapply](incompat-other-changes.html#explicit-call-to-unapply)|| +|[Invisible bean property](incompat-other-changes.html#invisible-bean-property)|| +|[`=>T` as type argument](incompat-other-changes.html#-t-as-type-argument)|| +|[Wildcard type argument](incompat-other-changes.html#wildcard-type-argument)|| + +### Type Checker + +The Scala 2.13 type checker is unsound in some specific cases. +This can lead to surprising runtime errors in places we would not expect. +Scala 3 being based on stronger theoretical foundations, these unsoundness bugs in the type checker are now fixed. + +|Incompatibility| +|--- | +|[Variance checks](incompat-type-checker.html#unsoundness-fixes-in-variance-checks)| +|[Pattern matching](incompat-type-checker.html#unsoundness-fixes-in-pattern-matching)| + +### Type Inference + +Some specific type inference rules have changed between Scala 2.13 and Scala 3. + +|Incompatibility| +|--- | +|[Return type of override method](incompat-type-inference.html#return-type-of-an-override-method)| +|[Reflective type](incompat-type-inference.html#reflective-type)| + +Also we have improved the type inference algorithm by redesigning it entirely. +This fundamental change leads to a few incompatibilities: +- A different type can be inferred +- A new type-checking error can appear + +> It is always good practice to write the result types of all public values and methods explicitly. +> It prevents the public API of your library from changing with the Scala version, because of different inferred types. +> +> This can be done prior to the Scala 3 migration by using the [ExplicitResultTypes](https://scalacenter.github.io/scalafix/docs/rules/ExplicitResultTypes.html) rule in Scalafix. + +### Macros + +The Scala 3 compiler is not able to expand Scala 2.13 macros. +Under such circumstances it is necessary to re-implement the Scala 2.13 macros using the new Scala 3 metaprogramming features. + +You can go back to the [Metaprogramming](compatibility-metaprogramming.html) page to learn about the new metaprogramming features. diff --git a/_overviews/scala3-migration/options-intro.md b/_overviews/scala3-migration/options-intro.md new file mode 100644 index 0000000000..9fc2d04d48 --- /dev/null +++ b/_overviews/scala3-migration/options-intro.md @@ -0,0 +1,21 @@ +--- +title: Compiler Options +type: chapter +description: This chapter shows the difference between Scala 2.13 and Scala 3 compiler options +num: 23 +previous-page: incompat-type-inference +next-page: options-lookup +--- + +The Scala 3 compiler has been rewritten from the ground up and consequently it does not offer the same options as the Scala 2.13 compiler. +Some options are available under a different name, others have just not been implemented yet. + +When porting a Scala 2.13 project to Scala 3, you will need to adapt the list of compiler options. +To do so you can refer to the [Lookup Table](options-lookup.html). + +> Passing an unavailable option to the Scala 3 compiler does not make it fail. +> It just prints a warning and ignores the option. + +You can also discover the new Scala 3 compiler options, which have no equivalent in Scala 2.13, in the [New Compiler Options](options-new.html) page. + +For Scaladoc settings reference and their compatibility with Scala2 Scaladoc, read [Scaladoc settings compatibility between Scala2 and Scala3](scaladoc-settings-compatibility.html) page. diff --git a/_overviews/scala3-migration/options-lookup.md b/_overviews/scala3-migration/options-lookup.md new file mode 100644 index 0000000000..36db00ad8e --- /dev/null +++ b/_overviews/scala3-migration/options-lookup.md @@ -0,0 +1,265 @@ +--- +title: Compiler Options Lookup Table +type: section +description: This section contains the compiler options lookup tables +num: 24 +previous-page: options-intro +next-page: options-new +--- + +This table lists the Scala 2.13 compiler options with their equivalent in Scala 3. +Some options have cross-version support, such as `-Vprint`. +Others have a close equivalent with a different name. A number of Scala 2 options +have no equivalent in Scala 3, such as options for debugging Scala 2 macros. + +The compiler options are shown as displayed by the help output `scalac -help`, `scalac -X`, etc. +A few aliases are shown here, but most older aliases, such as `-Xprint` for `-Vprint`, +or `-Ytyper-debug` for `-Vtyper`, are listed by the latest name. + +The option groups `-V` and `-W` were introduced in Scala 2.13, for "verbose" options that +request additional diagnostic output and "warnings" that request additional checks which +may or may not indicate errors in code. `-Werror` elevates warnings to errors, and `-Wconf` +allows precise control over warnings by either ignoring them or taking them as errors. +The configuration string for `-Wconf` will likely require adjustment when migrating to Scala 3, +since the configuration syntax and the error messages it matches are different. + +| Status | Meaning | +|-|-| +| | It is available in Scala 3. | +| `` | It has been renamed to ``. | +| | It is not yet available but could be added later. | + +> The current comparison is based on Scala 2.13.10 and 3.3.0. + +## Standard Settings + +| 2.13.x | 3.3.x | +|-|-| +| `-Dproperty=value` | | +| `-J` | | +| `-P::` || +| `-V` | | +| `-W` | | +| `-X` || +| `-Y` || +| `-bootclasspath` || +| `-classpath` || +| `-d` || +| `-dependencyfile` | | +| `-deprecation` || +| `-encoding` || +| `-explaintypes` | `-explain-types` | +| `-extdirs` || +| `-feature` || +| `-g` | | +| `-help` || +| `-javabootclasspath` || +| `-javaextdirs` || +| `-language` || +| `-no-specialization` | | +| `-nobootcp` | | +| `-nowarn` || +| `-opt` | | +| `-opt-inline-from` | | +| `-opt-warnings` | | +| `-optimize` | | +| `-print` || +| `-release` || +| `-rootdir` | | +| `-sourcepath` || +| `-target` | `-Xtarget` | +| `-toolcp` | | +| `-unchecked` || +| `-uniqid` || +| `-usejavacp` || +| `-usemanifestc` | | +| `-verbose` || +| `-version` || + +## Verbose Settings + +| 2.13.x | 3.3.x | +|-|-| +| `-Vbrowse:` | | +| `-Vclasspath` | `-Ylog-classpath` | +| `-Vdebug` | `-Ydebug` | +| `-Vdebug-tasty` | | +| `-Vdebug-type-error` | | +| `-Vdoc` | | +| `-Vfree-terms` | | +| `-Vfree-types` | | +| `-Vhot-statistics`| | +| `-Vide`| | +| `-Vimplicit-conversions`| | +| `-Vimplicits`| | +| `-Vimplicits-max-refined`| | +| `-Vimplicits-verbose-tree`| | +| `-Vinline ` | | +| `-Vlog:` | `-Ylog:`| +| `-Vmacro` | | +| `-Vmacro-lite` | | +| `-Vopt ` | | +| `-Vpatmat` | | +| `-Vphases` | | +| `-Vpos`| | +| `-Vprint:` | | +| `-Vprint-args ` | | +| `-Vprint-pos` | `-Yprint-pos` | +| `-Vprint-types` | `-Xprint-types` | +| `-Vquasiquote` | | +| `-Vreflective-calls` | | +| `-Vreify` | | +| `-Vshow:` | | +| `-Vshow-class ` | | +| `-Vshow-member-pos ` | | +| `-Vshow-object ` | | +| `-Vshow-symkinds` | | +| `-Vshow-symowners` | | +| `-Vstatistics ` | | +| `-Vsymbols` | | +| `-Vtype-diffs` | | +| `-Vtyper` | | + +## Warning Settings + +| 2.13.x | 3.3.x | +|-|-| +| `-Wconf` | | +| `-Wdead-code` | | +| `-Werror` | | +| `-Wextra-implicit` | | +| `-Wmacros:` | | +| `-Wnonunit-if` | | +| `-Wnonunit-statement` | | +| `-Wnumeric-widen` | | +| `-Woctal-literal` | | +| `-Wopt` | | +| `-Wperformance` | | +| `-Wself-implicit` | | +| `-Wunused:` | | +| `-Wvalue-discard`| | + +## Advanced Settings + +| 2.13.x | 3.3.x | +|-|-| +| `-Xasync` | | +| `-Xcheckinit` | `-Ysafe-init` | +| `-Xdev` | | +| `-Xdisable-assertions` | | +| `-Xelide-below` | | +| `-Xexperimental` | | +| `-Xfuture` | | +| `-Xgenerate-phase-graph` | | +| `-Xjline` | | +| `-Xlint:deprecation` | `-deprecation` | +| `-Xlint:` | | +| `-Xmacro-settings` | | +| `-Xmain-class` | | +| `-Xmaxerrs` | | +| `-Xmaxwarns` | | +| `-Xmigration` || +| `-Xmixin-force-forwarders` || +| `-Xno-forwarders` || +| `-Xno-patmat-analysis` | | +| `-Xnon-strict-patmat-analysis` | | +| `-Xnojline` | | +| `-Xplugin` || +| `-Xplugin-disable` || +| `-Xplugin-list` || +| `-Xplugin-require` || +| `-Xpluginsdir` || +| `-Xprompt` || +| `-Xreporter` | | +| `-Xresident` | | +| `-Xscript` | | +| `-Xsource` | `-source` | +| `-Xsource-reader` | | +| `-Xverify` | `-Xverify-signatures` | +| `-Xxml` | | + +## Private settings + +| 2.13.x | 3.0.x | +|-|-| +| `-Ybackend-parallelism` | | +| `-Ybackend-worker-queue` | | +| `-Ybreak-cycles` | | +| `-Ycache-macro-class-loader` | | +| `-Ycache-plugin-class-loader` | | +| `-Ycheck` || +| `-Ycompact-trees` | | +| `-Ydelambdafy` | | +| `-Ydump-classes` || +| `-Ygen-asmp` | | +| `-Yimports` | | +| `-Yissue-debug` | | +| `-Yjar-compression-level` | | +| `-YjarFactory` | | +| `-Ymacro-annotations` | | +| `-Ymacro-classpath` | | +| `-Ymacro-expand` | | +| `-Ymacro-global-fresh-names` | | +| `-Yno-completion` | | +| `-Yno-flat-classpath-cache` | | +| `-Yno-generic-signatures` || +| `-Yno-imports` || +| `-Yno-predef` || +| `-Yopt-inline-heuristics` | | +| `-Ypatmat-exhaust-depth` | | +| `-Ypresentation-any-thread` | | +| `-Ypresentation-debug` | | +| `-Ypresentation-delay` | | +| `-Ypresentation-locate-source-file` | | +| `-Ypresentation-log` | | +| `-Ypresentation-replay` | | +| `-Ypresentation-strict` | | +| `-Ypresentation-verbose` | | +| `-Yprint-trees` | | +| `-Yprofile-destination` || +| `-Yprofile-enabled` || +| `-Yprofile-external-tool` || +| `-Yprofile-run-gc` || +| `-Yprofile-trace` | | +| `-Yrangepos` | | +| `-Yrecursion` | | +| `-Yreify-copypaste` | | +| `-Yrepl-class-based` | | +| `-Yrepl-outdir` | | +| `-Yrepl-use-magic-imports` | | +| `-Yresolve-term-conflict` || +| `-Yscala3-implicit-resolution` | | +| `-Yscriptrunner` | | +| `-Yskip` || +| `-Ystop-after` || +| `-Ystop-before` || +| `-Ytasty-no-annotations` | | +| `-Ytasty-reader` | | +| `-Ytrack-dependencies` | | +| `-Yvalidate-pos` | | + +## Compiler Plugins + +Some useful Scala 2.13 compiler plugins are now shipped into the compiler. +You can enable and configure them with some new native options. + +### Scala.js + +| 2.13.x | 3.0.x | +|-|-| +| `-Xplugin:scalajs-compiler_.jar` | `-scalajs` | +| `-P:scalajs:genStaticForwardersForNonTopLevelObjects` | `-scalajs-genStaticForwardersForNonTopLevelObjects` | +| `-P:scalajs:mapSourceURI`| `-scalajs-mapSourceURI`| + +### SemanticDB + +| 2.13.x | 3.0.x | +|-|-| +| `-Xplugin:semanticdb-scalac_.jar`| `-Xsemanticdb` | +| `-P:semanticdb:targetroot:` | `-semanticdb-target:` | + +### Kind-Projector + +| 2.13.x | 3.0.x | +|-|-| +| `-Xplugin:kind-projector_.jar` | `-Ykind-projector` | diff --git a/_overviews/scala3-migration/options-new.md b/_overviews/scala3-migration/options-new.md new file mode 100644 index 0000000000..d101412f95 --- /dev/null +++ b/_overviews/scala3-migration/options-new.md @@ -0,0 +1,105 @@ +--- +title: New Compiler Options +type: section +description: This chapter lists all the new compiler options in Scala 3 +num: 25 +previous-page: options-lookup +next-page: scaladoc-settings-compatibility +--- + +The current page only contains the options that were added in Scala 3.0.x. + +## Standard settings + +| 3.0.x | description | +|-|-| +| `-color` | Colored output Default: always. | +| `-doc-snapshot` | Generate a documentation snapshot for the current Dotty version | +| `-explain` | Explain errors in more detail. | +| `-from-tasty` | Compile classes from tasty files. The arguments are .tasty or .jar files. | +| `-indent` | Together with -rewrite, remove {...} syntax when possible due to significant indentation. | +| `-new-syntax` | Require `then` and `do` in control expressions. | +| `-no-indent` | Require classical {...} syntax, indentation is not significant. | +| `-old-syntax` | Require `(...)` around conditions. | +| `-pagewidth` | Set page width Default: 80. | +| `-print-lines` | Show source code line numbers. | +| `-print-tasty` | Prints the raw tasty. | +| `-project` | The name of the project. | +| `-project-logo` | The file that contains the project's logo (in /images). | +| `-project-url` | The source repository of your project. | +| `-project-version` | The current version of your project. | +| `-rewrite` | When used in conjunction with a `...-migration` source version, rewrites sources to migrate to new version. | +| `-siteroot` | A directory containing static files from which to generate documentation. Default: ./docs. | +| `-sourceroot` | Specify workspace root directory. Default: .. | + +## Verbose settings + +| 3.2.x | description | +|-|-| +| `-Vprofile` | Show metrics about sources and internal representations to estimate compile-time complexity. | +| `-Vprofile-sorted-by:` | Show metrics about sources and internal representations sorted by given column name. | +| `-Vprofile-details N` | Like -Vprofile, but also show metrics about sources and internal representations of the N most complex methods | + +## Advanced settings + +| 3.0.x | description | +|-|-| +| `-Xignore-scala2-macros` | Ignore errors when compiling code that calls Scala2 macros, these will fail at runtime. | +| `-Ximport-suggestion-timeout` | Timeout (in ms) for searching for import suggestions when errors are reported. | +| `-Xmax-inlined-trees` | Maximal number of inlined trees. Default: 2000000 | +| `-Xmax-inlines` | Maximal number of successive inlines. Default: 32. | +| `-Xprint-diff` | Print changed parts of the tree since last print. | +| `-Xprint-diff-del` | Print changed parts of the tree since last print including deleted parts. | +| `-Xprint-inline` | Show where inlined code comes from. | +| `-Xprint-suspension` | Show when code is suspended until macros are compiled. | +| `-Xrepl-disable-display` | Do not display definitions in REPL. | +| `-Xwiki-syntax` | Retains the Scala2 behavior of using Wiki Syntax in Scaladoc. | + +## Private settings + +| 3.0.x | description | +|-|-| +| `-Ycheck-all-patmat` | Check exhaustivity and redundancy of all pattern matching (used for testing the algorithm). | +| `-Ycheck-mods` | Check that symbols and their defining trees have modifiers in sync. | +| `-Ycheck-reentrant` | Check that compiled program does not contain vars that can be accessed from a global root. | +| `-Ycook-comments` | Cook the comments (type check `@usecase`, etc.) | +| `-Ydebug-error` | Print the stack trace when any error is caught. | +| `-Ydebug-flags` | Print all flags of definitions. | +| `-Ydebug-missing-refs` | Print a stacktrace when a required symbol is missing. | +| `-Ydebug-names` | Show internal representation of names. | +| `-Ydebug-pos` | Show full source positions including spans. | +| `-Ydebug-trace` | Trace core operations. | +| `-Ydebug-tree-with-id` | Print the stack trace when the tree with the given id is created. Default: -2147483648. | +| `-Ydebug-type-error` | Print the stack trace when a TypeError is caught | +| `-Ydetailed-stats` | Show detailed internal compiler stats (needs Stats.enabled to be set to true). | +| `-YdisableFlatCpCaching` | Do not cache flat classpath representation of classpath elements from jars across compiler instances. | +| `-Ydrop-comments` | Drop comments when scanning source files. | +| `-Ydump-sbt-inc` | For every compiled foo.scala, output the API representation and dependencies used for sbt incremental compilation in foo.inc, implies -Yforce-sbt-phases. | +| `-Yerased-terms` | Allows the use of erased terms. | +| `-Yexplain-lowlevel` | When explaining type errors, show types at a lower level. | +| `-Yexplicit-nulls` | Make reference types non-nullable. Nullable types can be expressed with unions: e.g. String|Null. | +| `-Yforce-sbt-phases` | Run the phases used by sbt for incremental compilation (ExtractDependencies and ExtractAPI) even if the compiler is ran outside of sbt, for debugging. | +| `-Yfrom-tasty-ignore-list` | List of `tasty` files in jar files that will not be loaded when using -from-tasty | +| `-Yindent-colons` | Allow colons at ends-of-lines to start indentation blocks. | +| `-Yinstrument` | Add instrumentation code that counts allocations and closure creations. | +| `-Yinstrument-defs` | Add instrumentation code that counts method calls; needs -Yinstrument to be set, too. | +| `-Yno-decode-stacktraces` | how raw StackOverflow stacktraces, instead of decoding them into triggering operations. | +| `-Yno-deep-subtypes` | Throw an exception on deep subtyping call stacks. | +| `-Yno-double-bindings` | Assert no namedtype is bound twice (should be enabled only if program is error-free). | +| `-Yno-kind-polymorphism` | Disable kind polymorphism. | +| `-Yno-patmat-opt` | Disable all pattern matching optimizations. | +| `-Yplain-printer` | Pretty-print using a plain printer. | +| `-Yprint-debug` | When printing trees, print some extra information useful for debugging. | +| `-Yprint-debug-owners` | When printing trees, print owners of definitions. | +| `-Yprint-pos` | Show tree positions. | +| `-Yprint-pos-syms` | Show symbol definitions positions. | +| `-Yprint-syms` | When printing trees print info in symbols instead of corresponding info in trees. | +| `-Yrequire-targetName` | Warn if an operator is defined without a @targetName annotation | +| `-Yretain-trees` | Retain trees for top-level classes, accessible from ClassSymbol#tree | +| `-Yscala2-unpickler` | Control where we may get Scala 2 symbols from. This is either "always", "never", or a classpath. Default: always. | +| `-Yshow-print-errors` | Don't suppress exceptions thrown during tree printing. | +| `-Yshow-suppressed-errors` | Also show follow-on errors and warnings that are normally suppressed. | +| `-Yshow-tree-ids` | Uniquely tag all tree nodes in debugging output. | +| `-Yshow-var-bounds` | Print type variables with their bounds. | +| `-Ytest-pickler` | Self-test for pickling functionality; should be used with -Ystop-after:pickler. | +| `-Yunsound-match-types` | Use unsound match type reduction algorithm. | diff --git a/_overviews/scala3-migration/plugin-intro.md b/_overviews/scala3-migration/plugin-intro.md new file mode 100644 index 0000000000..96bfc18078 --- /dev/null +++ b/_overviews/scala3-migration/plugin-intro.md @@ -0,0 +1,11 @@ +--- +title: Compiler Plugins +type: chapter +description: This section shows how to migrate from using Scala 2 compiler plugins +num: 27 +previous-page: options-new +next-page: plugin-kind-projector +--- + +Scala 3 includes some features that were previously provided by a compiler plugin. +This chapter gives more detail on how to migrate from using a specific compiler plugin to Scala 3. diff --git a/_overviews/scala3-migration/plugin-kind-projector.md b/_overviews/scala3-migration/plugin-kind-projector.md new file mode 100644 index 0000000000..ab996ec586 --- /dev/null +++ b/_overviews/scala3-migration/plugin-kind-projector.md @@ -0,0 +1,173 @@ +--- +title: Kind Projector Migration +type: section +description: This section shows how to migrate from the kind-projector plugin to Scala 3 kind-projector syntax +num: 28 +previous-page: plugin-intro +next-page: external-resources +--- + +In the future, Scala 3 will use the `_` underscore symbol for placeholders in type lambdas---just as the underscore is currently used for placeholders in (ordinary) term-level lambdas. + +The new type lambda syntax is not enabled by default, to enable it, use a compiler flag `-Ykind-projector:underscores`. Note that enabling underscore type lambdas will disable usage of `_` as a wildcard, you will only be able to write wildcards using the `?` symbol. + +If you wish to cross-compile a project for Scala 2 & Scala 3 while using underscore type lambdas for both, you may do so starting with [kind-projector](https://github.com/typelevel/kind-projector) version `0.13.0` and up and Scala 2 versions `2.13.6` and `2.12.14`. +To enable it, add the compiler flags `-Xsource:3 -P:kind-projector:underscore-placeholders` to your build. +As in Scala 3, this will disable usage of `_` as a wildcard, however, the flag `-Xsource:3` will allow you to replace it with the `?` symbol. + +The following `sbt` configuration will set up the correct flags to cross-compile with new syntax: + +```scala +ThisBuild / scalacOptions ++= { + CrossVersion.partialVersion(scalaVersion.value) match { + case Some((3, _)) => Seq("-Ykind-projector:underscores") + case Some((2, 12 | 13)) => Seq("-Xsource:3", "-P:kind-projector:underscore-placeholders") + } +} +``` + +## Migrating to New Syntax + +To use underscores for type-lambdas in existing kind-projector enabled code, replace `*` or `?` type lambda placeholders with `_`. + +In turn, you will also have to rewrite all usages of `_` as the wildcard to use `?` symbol. + +For example the following usage of the wildcard: + +{% tabs wildcard_scala2 %} +{% tab 'Scala 2 Only' %} +```scala +def getWidget(widgets: Set[_ <: Widget], name: String): Option[Widget] = + widgets.find(_.name == name) +``` +{% endtab %} +{% endtabs %} + +Must be rewritten to: + +{% tabs wildcard_scala3 %} +{% tab 'Scala 3 Only' %} +```scala +def getWidget(widgets: Set[? <: Widget], name: String): Option[Widget] = + widgets.find(_.name == name) +``` +{% endtab %} +{% endtabs %} + +And the following usages of kind-projector's `*` placeholder: + +{% tabs kind_projector_scala2 %} +{% tab 'Scala 2 Only' %} +```scala +Tuple2[*, Double] // equivalent to: type R[A] = Tuple2[A, Double] +Either[Int, +*] // equivalent to: type R[+A] = Either[Int, A] +Function2[-*, Long, +*] // equivalent to: type R[-A, +B] = Function2[A, Long, B] +``` +{% endtab %} +{% endtabs %} + +Must be rewritten to: + +{% tabs kind_projector_scala3 %} +{% tab 'Scala 3 Only' %} +```scala +Tuple2[_, Double] // equivalent to: type R[A] = Tuple2[A, Double] +Either[Int, +_] // equivalent to: type R[+A] = Either[Int, A] +Function2[-_, Long, +_] // equivalent to: type R[-A, +B] = Function2[A, Long, B] +``` +{% endtab %} +{% endtabs %} + +## Compiling Existing Code + +Even without migrating to underscore type lambdas, you will likely be able to compile most of it with Scala 3 without changes. + +Use the flag `-Ykind-projector` to enable support for `*`-based type lambdas (without enabling underscore type lambdas), the following forms will now compile: + +{% tabs kind_projector_cross %} +{% tab 'Scala 2 and 3' %} +```scala +Tuple2[*, Double] // equivalent to: type R[A] = Tuple2[A, Double] +Either[Int, +*] // equivalent to: type R[+A] = Either[Int, A] +Function2[-*, Long, +*] // equivalent to: type R[-A, +B] = Function2[A, Long, B] +``` +{% endtab %} +{% endtabs %} + +## Rewriting Incompatible Constructs + +Scala 3's `-Ykind-projector` & `-Ykind-projector:underscores` implement only a subset of `kind-projector` syntax, in particular they do not implement: + +* higher-kinded type lambda placeholders +* higher-kinded named type lambda parameters +* The `Lambda` keyword (`λ` is still supported) + +You must rewrite ALL of the following forms: + +{% tabs kind_projector_illegal_scala2 %} +{% tab 'Scala 2 Only' %} +```scala +// classic +EitherT[*[_], Int, *] // equivalent to: type R[F[_], B] = EitherT[F, Int, B] +// underscores +EitherT[_[_], Int, _] // equivalent to: type R[F[_], B] = EitherT[F, Int, B] +// named λ +λ[(F[_], A) => EitherT[F, Int, A]] +// named Lambda +Lambda[(F[_], A) => EitherT[F, Int, A]] +``` +{% endtab %} +{% endtabs %} + +Into the following long-form to cross-compile with Scala 3: + +{% tabs kind_projector_illegal_cross %} +{% tab 'Scala 2 and 3' %} +```scala +type MyLambda[F[_], A] = EitherT[F, Int, A] +MyLambda +``` +{% endtab %} +{% endtabs %} + +Alternatively you may use Scala 3's [Native Type Lambdas]({{ site.scala3ref }}/new-types/type-lambdas.html) if you do not need to cross-compile: + +{% tabs kind_projector_illegal_scala3 %} +{% tab 'Scala 3 Only' %} +```scala +[F[_], A] =>> EitherT[F, Int, A] +``` +{% endtab %} +{% endtabs %} + +For `Lambda` you must rewrite the following form: + +{% tabs kind_projector_illegal_lambda_scala2 %} +{% tab 'Scala 2 Only' %} +```scala +Lambda[(`+E`, `+A`) => Either[E, A]] +``` +{% endtab %} +{% endtabs %} + +To the following to cross-compile: + +{% tabs kind_projector_illegal_lambda_cross %} +{% tab 'Scala 2 and 3' %} +```scala +λ[(`+E`, `+A`) => Either[E, A]] +``` +{% endtab %} +{% endtabs %} + +Or alternatively to Scala 3 type lambdas: + +{% tabs kind_projector_illegal_lambda_scala3 %} +{% tab 'Scala 3 Only' %} +```scala +[E, A] =>> Either[E, A] +``` +{% endtab %} +{% endtabs %} + +Note: Scala 3 type lambdas no longer need `-` or `+` variance markers on parameters, these are now inferred. diff --git a/_overviews/scala3-migration/scala3-migrate.md b/_overviews/scala3-migration/scala3-migrate.md new file mode 100644 index 0000000000..e4c66d9ac4 --- /dev/null +++ b/_overviews/scala3-migration/scala3-migrate.md @@ -0,0 +1,444 @@ +--- +title: Porting an sbt Project (using sbt-scala3-migrate) +type: section +description: This section shows how to use scala3-migrate to migrate a project +num: 11 +previous-page: tutorial-prerequisites +next-page: tutorial-sbt +--- + +`sbt-scala3-migrate` is an sbt plugin to assist you during the migration of your sbt project to Scala 3. +It consists of four sbt commands: +- `migrateDependencies` helps you update the list of `libraryDependencies` +- `migrateScalacOptions` helps you update the list of `scalacOptions` +- `migrateSyntax` fixes a number of syntax incompatibilities between Scala 2.13 and Scala 3 +- `migrateTypes` tries to compile your code to Scala 3 by infering types and resolving implicits where needed. + +Each one of these commands is described in details below. + +> #### Requirements +> - Scala 2.13, preferred 2.13.13 +> - sbt 1.5 or higher +> - **Disclaimer:** This tool cannot migrate libraries containing macros. +> +> #### Recommendation +> Before the migration, add `-Xsource:3` to your scalac options to enable Scala 3 migration warnings in the Scala 2 compiler. +> See the page [Scala 2 with -Xsource:3](tooling-scala2-xsource3.html) for more details. + +In this tutorial, we will migrate the project in [scalacenter/scala3-migration-example](https://github.com/scalacenter/scala3-migration-example). +To learn about the migration, and train yourself, you can clone this repository and follow the tutorial steps. + +## 1. Installation + +Add `sbt-scala3-migrate` in the `project/plugins.sbt` file of your sbt project. + +``` scala +// project/plugins.sbt +addSbtPlugin("ch.epfl.scala" % "sbt-scala3-migrate" % "0.6.1") +``` + +

            The latest published version is +scala3-migrate Scala version support +

            +
            + +## 2. Choose a module + +If your project contains more than one module, the first step is to choose which module to migrate first. + +Thanks to the interoperability between Scala 2.13 and Scala 3 you can start with any module. +However it is probably simpler to start with the module that has the fewest dependencies. + +> `sbt-scala3-migrate` operates on one module at a time. +> Make sure the module you choose is not an aggregate. + +## 3. Migrate the dependencies + +> All the commands in this tutorial must be run in the sbt shell. + +**Usage:** `migrateDependencies ` + +For the purpose of this tutorial we will consider the following build configuration: + +```scala +//build.sbt +lazy val main = project + .in(file(".")) + .settings( + scalaVersion := "2.13.11", + libraryDependencies ++= Seq( + "org.typelevel" %% "cats-core" % "2.4.0", + "io.github.java-diff-utils" % "java-diff-utils" % "4.12", + "org.scalameta" %% "parsers" % "4.8.9", + "org.scalameta" %% "munit" % "0.7.23" % Test, + "com.softwaremill.scalamacrodebug" %% "macros" % "0.4.1" % Test + ), + addCompilerPlugin(("org.typelevel" %% "kind-projector" % "0.13.2").cross(CrossVersion.full)), + addCompilerPlugin("com.olegpy" %% "better-monadic-for" % "0.3.1") + ) +``` + +Running `migrateDependencies main` outputs: + +
            +
+sbt:main> migrateDependencies main
+[info] 
+[info] Starting migration of libraries and compiler plugins of project main
+[info] 
+[info] Valid dependencies:
+[info] "io.github.java-diff-utils" % "java-diff-utils" % "4.12"
+
+[warn] 
+[warn] Versions to update:
+[warn] "org.typelevel" %% "cats-core" % "2.6.1" (Other versions: 2.7.0, ..., 2.10.0)
+[warn] "org.scalameta" %% "munit" % "0.7.25" % Test (Other versions: 0.7.26, ..., 1.0.0-M8)
+[warn] 
+[warn] For Scala 3 use 2.13:
+[warn] ("org.scalameta" %% "parsers" % "4.8.9").cross(CrossVersion.for3Use2_13)
+[warn] 
+[warn] Integrated compiler plugins:
+[warn] addCompilerPlugin(("org.typelevel" %% "kind-projector" % "0.13.2").cross(CrossVersion.full))
+[warn] replaced by scalacOptions += "-Ykind-projector"
+[error] 
+[error] Incompatible Libraries:
+[error] "com.softwaremill.scalamacrodebug" %% "macros" % "0.4.1" % Test (Macro Library)
+[error] addCompilerPlugin("com.olegpy" %% "better-monadic-for" % "0.3.1") (Compiler Plugin)
+[info] 
+[success] Total time: 0 s, completed Aug 28, 2023 9:18:04 AM
+
+
            + +Let's take a closer look at each part of this output message. + +### Valid dependencies + +Valid dependencies are compatible with Scala 3, either because they are standard Java libraries or because they have been cross-published to Scala 3. + +
            +
+[info] Valid dependencies:
+[info] "io.github.java-diff-utils" % "java-diff-utils" % "4.12"
+
+
            + +You can keep them as they are. + +### Versions to update + +These libraries have been cross-published to Scala 3 in later versions. +You need to update their versions. + +
            +
+[warn] Versions to update:
+[warn] "org.typelevel" %% "cats-core" % "2.6.1" (Other versions: 2.7.0, ..., 2.10.0)
+[warn] "org.scalameta" %% "munit" % "0.7.25" % Test (Other versions: 0.7.26, ..., 1.0.0-M8)
+
+
            + +In the given example we need to bump the version of cats-core to 2.6.1 and the version of munit to 0.7.25. + +> The `Other versions` part of the output message indicates which other versions are available in Scala 3. +If you wish you can bump to one of the most recent version, but take care of choosing a source compatible version. +According to [the semantic versionning scheme](https://semver.org/), a patch or minor version bump is safe but not a major version bump. + + +### For Scala 3 use 2.13 + +These libraries are not yet cross-published to Scala 3 but they are cross-compatible. +You can use their 2.13 versions to compile to Scala 3. + +Add `.cross(CrossVersion.for3Use2_13)` on the libraries to tell sbt to use the `_2.13` suffix, instead of `_3`. + +
            +
+[warn] For Scala 3 use 2.13:
+[warn] ("org.scalameta" %% "parsers" % "4.8.9").cross(CrossVersion.for3Use2_13)
+
+
            + +> #### Disclaimer about `CrossVersion.for3Use2_13`: +- It can cause a conflict on the `_2.13` and `_3` suffixes of a transitive dependency. +In such situation, sbt will fail to resolve the dependency, with a clear error message. +- It is generally not safe to publish a Scala 3 library which depends on a Scala 2.13 library. +Otherwise users of the library can have conflicting `_2.13` and `_3` suffixes on the same dependency. + +### Integrated compiler plugins + +Some compiler plugins were integrated into the Scala 3 compiler itself. +In Scala 3 you don't need to resolve them as dependencies but you can activate them with compiler flags. + +
            +
+[warn] Integrated compiler plugins:
+[warn] addCompilerPlugin(("org.typelevel" %% "kind-projector" % "0.13.2").cross(CrossVersion.full))
+[warn] replaced by scalacOptions += "-Ykind-projector"
+
+
            + +Here for instance you can activate kind-projector by adding `-Ykind-projector` to the list of `scalacOptions`. + +During the migration process, it is important to maintain the compatibility with Scala 2.13. +The later `migrateSyntax` and `migrateTypes` commands will use the Scala 2.13 compilation to rewrite some parts of the code automatically. + +You can configure kind-projector in a cross-compatible way like this: +```scala +// add kind-projector as a dependency on Scala 2 +libraryDependencies ++= { + if (scalaVersion.value.startsWith("3.")) Seq.empty + else Seq( + compilerPlugin(("org.typelevel" %% "kind-projector" % "0.13.2").cross(CrossVersion.full)) + ) +}, +// activate kind-projector in Scala 3 +scalacOptions ++= { + if (scalaVersion.value.startsWith("3.")) Seq("-Ykind-projector") + else Seq.empty +} +``` + +### Incompatible libraries + +Some macro libraries or compiler plugins are not compatible with Scala 3. + +
            +
+[error] Incompatible Libraries:
+[error] "com.softwaremill.scalamacrodebug" %% "macros" % "0.4.1" % Test (Macro Library)
+[error] addCompilerPlugin("com.olegpy" %% "better-monadic-for" % "0.3.1") (Compiler Plugin)
+
+
            + +To solve these incompatibilities, you can either: +- Check with the maintainers if they plan to port them to Scala 3, and possibly help them to do so. +- Remove these dependencies from your build and adapt the code accordingly. + +### The updated build + +After you updated the build, it should look like this: + +```scala +//build.sbt +lazy val main = project + .in(file(".")) + .settings( + scalaVersion := "2.13.11", + libraryDependencies ++= Seq( + "org.typelevel" %% "cats-core" % "2.6.1", + "io.github.java-diff-utils" % "java-diff-utils" % "4.12", + ("org.scalameta" %% "parsers" % "4.8.9").cross(CrossVersion.for3Use2_13), + "org.scalameta" %% "munit" % "0.7.25" % Test + ), + libraryDependencies ++= { + if (scalaVersion.value.startsWith("3.")) Seq.empty + else Seq( + compilerPlugin(("org.typelevel" %% "kind-projector" % "0.13.2").cross(CrossVersion.full)) + ) + }, + scalacOptions ++= { + if (scalaVersion.value.startsWith("3.")) Seq("-Ykind-projector") + else Seq.empty + } + ) +``` + +Reload sbt, check that the project compiles (to Scala 2.13), check that the tests run successfully, and commit your changes. +You are now ready to migrate the compiler options. + +## 4. Migrate the compiler options + +**Usage:** `migrateScalacOptions ` + +The Scala 3 compiler does not contain the exact same set of options as the Scala 2 compiler. +You can check out the [the Compiler Options Table](options-lookup.html) to get a full comparison of all the compilers options. + +The `migrateScalacOptions` will help you update the list of `scalacOptions` in your build. + +For the purpose of this tutorial we will consider the following build configuration: + +```scala +lazy val main = project + .in(file(".")) + .settings( + scalaVersion := "2.13.11", + scalacOptions ++= Seq( + "-encoding", + "UTF-8", + "-target:jvm-1.8", + "-Xsource:3", + "-Wunused:imports,privates,locals", + "-explaintypes" + ) + ) +``` + +Running `migrateScalacOptions main` outputs: + +
            +
+sbt:main> migrateScalacOptions main
+[info] 
+[info] Starting migration of scalacOptions in main
+[info] 
+[info] Valid scalacOptions:
+[info] -encoding UTF-8
+[info] -Wunused:imports,privates,locals
+[warn] 
+[warn] Renamed scalacOptions:
+[warn] -target:jvm-1.8 -> -Xunchecked-java-output-version:8
+[warn] -explaintypes   -> -explain
+[warn] 
+[warn] Removed scalacOptions:
+[warn] -Xsource:3
+[warn] -Yrangepos
+[success] Total time: 0 s, completed Aug 29, 2023 2:00:57 PM
+
+
            + +Some scalac options are still valid, some must be renamed and some must be removed. + +> Some options can appear in the output of `migrateScalacOptions` but not in your `build.sbt`. +> They are added by sbt or by some sbt plugins. +> Make sure to use up-to-date versions of sbt and sbt plugins. +> They should be able to adapt the added compiler options to the Scala version automatically. + +Once again, it is important to maintain the compatibility with Scala 2.13 because the `migrateSyntax` and `migrateTypes` commands will use the Scala 2.13 compilation to apply some patches automatically. + +Here is how we can update the list of scalacOptions: +```scala +lazy val main = project + .in(file(".")) + .settings( + scalaVersion := "2.13.11", + scalacOptions ++= { + if (scalaVersion.value.startsWith("3.")) scala3Options + else scala2Options + } + ) + +lazy val sharedScalacOptions = + Seq("-encoding", "UTF-8", "-Wunused:imports,privates,locals") + +lazy val scala2Options = sharedScalacOptions ++ + Seq("-target:jvm-1.8", "-Xsource:3", "-explaintypes") + +lazy val scala3Options = sharedScalacOptions ++ + Seq("-Xunchecked-java-output-version:8", "-explain") +``` + +Reload sbt, check that the project compiles (to Scala 2.13), check that the tests run successfully, and commit your changes. +You are now ready to migrate the syntax. + +## 5. Migrate the syntax + +**Usage:** `migrateSyntax ` + +This command runs a number of Scalafix rules to patch some discarded syntax. + +The list of applied Scalafix rules are: +- [ProcedureSyntax](https://scalacenter.github.io/scalafix/docs/rules/ProcedureSyntax.html) +- [fix.scala213.ExplicitNullaryEtaExpansion](https://github.com/lightbend-labs/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNullaryEtaExpansion.scala) +- [migrate.ParensAroundLambda](https://github.com/scalacenter/scala3-migrate/blob/ebb4a4087ed11899b9010f4c75eb365532694c0a/scalafix/rules/src/main/scala/migrate/ParensAroundParam.scala#L9) +- [fix.scala213.ExplicitNonNullaryApply](https://github.com/lightbend-labs/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNullaryEtaExpansion.scala) +- [fix.scala213.Any2StringAdd](https://github.com/lightbend-labs/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/Any2StringAdd.scala) +- [ExplicitResultTypes](https://scalacenter.github.io/scalafix/docs/rules/ExplicitResultTypes.html) + +For more information about the syntax changes between Scala 2.13 and Scala 3, you can refer to [the Incompatibility Table](incompatibility-table.html). + +> Some incompatibilities listed in [the Incompatibility Table](incompatibility-table.html) are not fixed by migrateSyntax. +> Most of them are not frequent and can easily be fixed by hand. +> If you want to contribute with a Scalafix rewrite rule, we will be more than happy to add it in the `migrateSyntax` command. + +Running `migrateSyntax main` outputs: +
            +
+sbt:main> migrateSyntax main
+[info] Starting migration of syntax in main
+[info] Run syntactic rules in 7 Scala sources successfully
+[info] Applied 3 patches in src/main/scala/example/SyntaxRewrites.scala
+[info] Run syntactic rules in 8 Scala sources successfully
+[info] Applied 1 patch in src/test/scala/example/SyntaxRewritesTests.scala
+[info] Migration of syntax in main succeeded.
+[success] Total time: 2 s, completed Aug 31, 2023 11:23:51 AM
+
+
            + +Take a look at the applied changes, check that the project still compiles, check that the tests run successfully and commit the changes. +The next and final step is to migrate the types. + +## 6. Migrate the types + +**Usage:** `migrateTypes ` + +The Scala 3 compiler uses a slightly different type inference algorithm. +It can sometimes fail at infering the same types as the Scala 2 compiler, which can lead to compilation errors. +This final step will add the needed type ascriptions to make the code compile to Scala 3. + +Running `migrateTypes main` outputs: +
            +
+sbt:main> migrateTypes main
+[info] compiling 8 Scala sources to /home/piquerez/github/scalacenter/scala3-migration-example/target/scala-2.13/classes ...
+[warn] 1 deprecation; re-run with -deprecation for details
+[warn] one warning found
+[info] compiling 8 Scala sources to /home/piquerez/github/scalacenter/scala3-migration-example/target/scala-2.13/test-classes ...
+[warn] 2 deprecations; re-run with -deprecation for details
+[warn] one warning found
+[success] Total time: 7 s, completed Aug 31, 2023 11:26:25 AM
+[info] Defining scalaVersion
+[info] The new value will be used by Compile / bspBuildTarget, Compile / dependencyTreeCrossProjectId and 68 others.
+[info]  Run `last` for details.
+[info] Reapplying settings...
+[info] set current project to main (in build file:/home/piquerez/github/scalacenter/scala3-migration-example/)
+[info] 
+[info] Migrating types in main / Compile
+[info] 
+[info] Found 3 patches in 1 Scala source
+[info] Starting migration of src/main/scala/example/TypeIncompat.scala
+[info] 3 remaining candidates
+[info] 1 remaining candidate
+[info] Found 1 required patch in src/main/scala/example/TypeIncompat.scala
+[info] Compiling to Scala 3 with -source:3.0-migration -rewrite
+[info] compiling 1 Scala source to /home/piquerez/github/scalacenter/scala3-migration-example/target/scala-3.3.1/classes ...
+[info] 
+[info] Migrating types in main / Test
+[info] 
+[info] Found 4 patches in 1 Scala source
+[info] Starting migration of src/test/scala/example/TypeIncompatTests.scala.scala
+[info] 4 remaining candidates
+[info] 3 remaining candidates
+[info] 2 remaining candidates
+[info] Found 1 required patch in src/test/scala/example/TypeIncompatTests.scala.scala
+[info] Compiling to Scala 3 with -source:3.0-migration -rewrite
+[info] 
+[info] You can safely upgrade main to Scala 3:
+[info] scalaVersion := "3.3.1"
+[success] Total time: 18 s, completed Aug 31, 2023 11:26:45 AM
+[info] Defining scalaVersion
+[info] The new value will be used by Compile / bspBuildTarget, Compile / dependencyTreeCrossProjectId and 68 others.
+[info]  Run `last` for details.
+[info] Reapplying settings...
+[info] set current project to main (in build file:/home/piquerez/github/scalacenter/scala3-migration-example/)
+sbt:main>
+
+
            + +`migrateTypes main` found 2 required patches: one in `src/test/scala/example/TypeIncompatTests.scala.scala` and the other in `src/main/scala/example/TypeIncompat.scala`. +It applied them, then it compiled to Scala 3 with `-source:3.0-migration -rewrite` to finalize the migration. + +Congratulations! Your project can now compile to Scala 3. + +## What to do next ? + +If you project contains only one module, you can set `scalaVersion := 3.3.1`. + +If you have more than one module, you can start again from [3. Migrate the dependencies](#3-migrate-the-dependencies) with another module. + +Once you are done with all modules, you can remove `sbt-scala3-migrate` from `project/plugins.abt`, and all Scala 2.13 related settings. + +## Feedback and contributions are welcome + +Every feedback will help us improve `sbt-scala3-migrate`: typos, clearer log messages, better documentation, +bug reports, ideas of features. +Don't hesitate to open a [GitHub issue](https://github.com/scalacenter/scala3-migrate). diff --git a/_overviews/scala3-migration/scaladoc-settings-compatibility.md b/_overviews/scala3-migration/scaladoc-settings-compatibility.md new file mode 100644 index 0000000000..7c6d63a59b --- /dev/null +++ b/_overviews/scala3-migration/scaladoc-settings-compatibility.md @@ -0,0 +1,84 @@ +--- +title: Scaladoc settings compatibility between Scala2 and Scala3 +type: section +description: This chapter lists all the scaladoc options for Scala 2 and Scala 3, and explains the relations between them. +num: 26 +previous-page: options-new +next-page: plugin-intro +--- + +The current page is stating the status of scaladoc settings. The related Github issue can be found here for [discussion](https://github.com/scala/scala3/issues/11907) + + +| Scala2 | Scala3 | Description | Comment | Is implemented? +| ------------- | ------------- | --- | --- | --- | +| -doc-format | _ | Selects in which format documentation is rendered. | Actually, old scaladoc supports only html, so it is in some way consistent with new scaladoc, which provides only html | | +| -doc-title | -project | The overall name of the Scaladoc site | Aliased in [#11965](https://github.com/scala/scala3/issues/11965) | | +| -doc-version | -project-version | | Aliased in [#11965](https://github.com/scala/scala3/issues/11965) | | +| -doc-footer | -project-footer | A footer on every Scaladoc page, by default the EPFL/Lightbend copyright notice. Can be overridden with a custom footer. | Fixed by [#11965](https://github.com/scala/scala3/issues/11965) | | +| -doc-no-compile | _ | A directory containing sources which should be parsed for docstrings without compiling (e.g. AnyRef.scala) | We don't need this as we have completely different approach to that issue using -Ydocument-synthetic-types flag for synthetic types | | +| -doc-source-url | -source-links | A URL pattern used to link to the source file, with some variables supported... | Scala3 implementation provides richer syntax. You can find migration steps below this [table](#source-links). | | +| -doc-external-doc | -external-mappings | Links describing locations of external dependencies' documentations. | Scala3 implementation provides richer syntax. You can find migration steps below this [table](#external-mappings). | | +| -jdk-api-doc-base | -external-mappings | URL used to link Java API references. | You can specify jdk via -external-mappings since they are generalized setting. You can find migration steps below this [table](#external-mappings) | | +| -doc-generator | _ | The fully qualified name of a doclet class, which will be used to generate the documentation. | We don't need this in Scala3 | | +| -doc-root-content | -doc-root-content | The file from which the root package documentation should be imported. | | | +| -implicits | _ | | We don't need this in Scala3 - Contextual extension methods are always documented in Scala 3 | | +| -implicits-debug | _ | | We don't need this in Scala3 | | +| -implicits-show-all | _ | | We don't need this in Scala3 | | +| -implicits-sound-shadowing | _ | | We don't need this in Scala3 | | +| -implicits-hide | _ | | We don't need this in Scala3 | | +| -diagrams | _ | | We don't need this in Scala3 | | +| -diagrams-debug | _ | | We don't need this in Scala3 | | +| -diagrams-dot-path | _ | | We don't need this in Scala3 | | +| -diagrams-max-classes | _ | | We don't need this in Scala3 | | +| -diagrams-max-implicits | _ | | We don't need this in Scala3 | | +| -diagrams-dot-timeout | _ | | We don't need this in Scala3 | | +| -diagrams-dot-restart | _ | | We don't need this in Scala3 | | +| -author | -author | | Fixed by [#11965](https://github.com/scala/scala3/issues/11965) | | +| -raw-output | _ | | We don't need this in Scala3 | | +| -no-prefixes | _ | | We don't need this in Scala3 | | +| -skip-packages | -skip-packages | | | | +| -no-link-warnings | _ | | Not implemented yet | | +| -expand-all-types | _ | | Setting has been removed | | +| -groups | -groups | | | | +| -no-java-comments | _ | | We don't need this in Scala3 | | +| -doc-canonical-base-url | -doc-canonical-base-url | A base URL to use as prefix and add `canonical` URLs to all pages. The canonical URL may be used by search engines to choose the URL that you want people to see in search results. If unset no canonical URLs are generated. | Fixed by [#11965](https://github.com/scala/scala3/issues/11965) | | +| -private | -private | Show all types and members. Unless specified, show only public and protected types and members. | Fixed by [#11965](https://github.com/scala/scala3/issues/11965) | | +| _ | -siteroot | | We don't backport it to old scaladoc | N/A | +| _ | -project-logo | | Should we backport it to the old scaladoc? | N/A | +| _ | -comment-syntax | | We don't backport it to the old scaladoc | N/A | +| _ | -revision | | Should we backport it to the old scaladoc? | N/A | +| _ | -social-links | | Should we backport it to the old scaladoc? | N/A | +| _ | -skip-by-id | | We don't backport it to the old scaladoc | N/A | +| _ | -skip-by-regex | | We don't backport it to the old scaladoc | N/A | +| _ | -snippet-compiler-args | | We don't backport it to the old scaladoc | N/A | +| _ | -Ydocument-synthetic-types | Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib | | | + +## Source links + +Source links are used to point to source code at some remote repository like github or bitbucket. +Hopefully, the new syntax is almost superset of the old syntax. +To migrate to the new scaladoc syntax, make sure that you don't use any of these variables: +`€{TPL_OWNER}` or `€{FILE_PATH_EXT}`. Otherwise you have to rewrite your source link, using either other `variables` or you can use new +syntax, about which you can read more in the [Scaladoc documentation]({% link _overviews/scala3-scaladoc/settings.md %}). +Note that new syntax let you specify prefixes of your files paths to match specific url in case your sources are scattered in different +directories or even different repositories. + + +## External mappings + +This setting is a generalized form of the old settings for javadoc/scaladoc. + +Example external mapping is: +``` +-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/ +``` + +A mapping is of the form '\::\[scaladoc3|scaladoc|javadoc]::\'. You can supply several mappings, separated by commas, as shown in the example. + +Given that the old syntaxes were: +- for scaladoc - `prefix#url` +- for javadoc - just URL + +one must take the regex that will match fq name (for javadoc, it can be wildcard like `java.*`), then concatenate it using double colons `::` +with one of the 3 available documentation formats, then again append `::` and then provide url for where the extednal documentation is hosted. diff --git a/_overviews/scala3-migration/tooling-migration-mode.md b/_overviews/scala3-migration/tooling-migration-mode.md new file mode 100644 index 0000000000..82c79bc695 --- /dev/null +++ b/_overviews/scala3-migration/tooling-migration-mode.md @@ -0,0 +1,61 @@ +--- +title: Scala 3 Migration Mode +type: chapter +description: This section describes the migration mode of the Scala 3 compiler +num: 8 +previous-page: tooling-scala2-xsource3 +next-page: tutorial-intro +--- + +The Scala 3 compiler provides some helpful utilities to ease the migration. + +Try running `scalac` to have a glimpse of those utilities: + +> `scalac` is the executable of the Scala compiler, it can be downloaded from [Github](https://github.com/scala/scala3/releases/). +> +> It can also be installed using Coursier with `cs install scala3-compiler`, in which case `scalac` is aliased `scala3-compiler`. + +{% highlight text %} +$ scalac +Usage: scalac +where possible standard options include: + +... +-explain Explain errors in more detail. +... +-rewrite When used in conjunction with a `...-migration` source version, rewrites sources to migrate to new version. +... +-source source version + Default: 3.0. + Choices: 3.0, future, 3.0-migration, future-migration. +... +{% endhighlight %} + +## Migration mode + +The `-source:3.0-migration` option makes the compiler forgiving on most of the dropped features, printing warnings in place of errors. +Each warning is a strong indication that the compiler is even capable of safely rewriting the deprecated pieces of code into their cross-compiling counterparts. + +We call this the **Scala 3 migration compilation**. + +## Automatic rewrites + +Once your code compiles in the migration mode, almost all warnings can be resolved automatically by the compiler itself. +To do so you just need to compile again, this time with the `-source:3.0-migration` and the `-rewrite` options. + +> Beware that the compiler will modify the code! It is intended to be safe. +> However you may want to commit the initial state so that you can print the diff applied by the compiler and revert it if necessary. + +> #### Good to know +> - The rewrites are not applied if the code compiles in error. +> - You cannot choose which rules are applied, the compiler runs all of them. + +You can refer to the [Incompatibility Table](incompatibility-table.html) to see the list of Scala 3 migration rewrites. + +## Error explanations + +The `-source:3.0-migration` mode handles many of the changed features but not all of them. +The compiler can give you more details about the remaining errors when invoked with the `-explain` and/or the `-explain-types` options. + +> The `-explain` and `-explain-types` options are not limited to the migration. +> They can, in general, assist you to learn and code in Scala 3. diff --git a/_overviews/scala3-migration/tooling-scala2-xsource3.md b/_overviews/scala3-migration/tooling-scala2-xsource3.md new file mode 100644 index 0000000000..e88f711c32 --- /dev/null +++ b/_overviews/scala3-migration/tooling-scala2-xsource3.md @@ -0,0 +1,146 @@ +--- +title: Scala 2 with -Xsource:3 +type: chapter +description: This section describes the Scala 2 compiler's -Xsource:3 flag +num: 7 +previous-page: tooling-tour +next-page: tooling-migration-mode +--- + +The Scala 2.13 compiler issues helpful migration warnings with the `-Xsource:3` flag. + +Before moving to the Scala 3 compiler, it's recommended to enable this flag in Scala 2 and address the new warnings. + +Usage information is shown with `scalac -Xsource:help`. + +## Migration vs cross-building + +With Scala 2.13.14 and newer, the `-Xsource:3` flag supports two scenarios: + + - `Xsource:3` enables warnings relevant for migrating a codebase to Scala 3. + In addition to new warnings, the flag enables certain benign Scala 3 syntaxes such as `import p.*`. + - Adding the `-Xsource-features:` flag is useful to reduce the maintenance burden of projects that cross-build between Scala 2 and 3. + Certain language constructs have been backported from Scala 3 in order to improve compatibility. + Instead of warning about a behavior change in Scala 3, it adopts the new behavior. + +## Warnings as errors, and quick fixes + +By default, Scala 3 migration warnings emitted by Scala 2.13 are reported as errors, using the default configuration, `-Wconf:cat=scala3-migration:e`. +This ensures that migration messaging is more visible. +Diagnostics can be emitted as warnings by specifying `-Wconf:cat=scala3-migration:w`. +Typically, emitting warnings instead of errors will cause more diagnostics to be reported. + +The [`@nowarn` annotation](https://www.scala-lang.org/api/current/scala/annotation/nowarn.html) can be used in program sources to suppress individual warnings. +Diagnostics are suppressed before they are promoted to errors, so that `@nowarn` takes precedence over `-Wconf` and `-Werror`. + +The Scala 2.13 compiler implements quick fixes for many Scala 3 migration warnings. +Quick fixes are displayed in Metals-based IDEs (not yet in IntelliJ), or they can be applied directly to the source code using the `-quickfix` flag, for example `-quickfix:cat=scala3-migration`. +See also `scala -quickfix:help`. + +## Enabled Scala 3 syntax + +The `-Xsource:3` flag enables the following Scala 3 syntaxes in Scala 2: + + - `import p.*` + - `import p.m as n` + - `import p.{given, *}` + - `case C(xs*)` as an alias for `case C(xs @ _*)` + - `A & B` type intersection as an alias for `A with B` + - Selecting a method `x.f` performs an eta-expansion (`x.f _`), even without an expected type + +## Scala 3 migration warnings in detail + +Many Scala 3 migration warnings are easy to understand, e.g., for implicit definitions without an explicit type: + +{% highlight scala %} +scala> object O { implicit val s = "" } + ^ + error: Implicit definition must have explicit type (inferred String) [quickfixable] +{% endhighlight %} + +## Enabling Scala 3 features with `-Xsource-features` + +Certain Scala 3 language changes have been backported and can be enabled using `-Xsource-features`; usage and available features are shown with `-Xsource-features:help`. + +When enabling a feature, the corresponding migration warning is no longer issued. + +{% highlight scala %} +scala> raw"\u0061" + ^ + warning: Unicode escapes in raw interpolations are deprecated; use literal characters instead +val res0: String = a + +scala> :setting -Xsource:3 + +scala> raw"\u0061" + ^ + error: Unicode escapes in raw interpolations are ignored in Scala 3 (or with -Xsource-features:unicode-escapes-raw); use literal characters instead + Scala 3 migration messages are errors under -Xsource:3. Use -Wconf / @nowarn to filter them or add -Xmigration to demote them to warnings. + Applicable -Wconf / @nowarn filters for this fatal warning: msg=, cat=scala3-migration, site=res1 + +scala> :setting -Xsource-features:unicode-escapes-raw + +scala> raw"\u0061" +val res1: String = \u0061 +{% endhighlight %} + +For every such language feature, a migration warning is issued under plain `-Xsource:3`. +Enabling the feature silences the warning and adopts the changed behavior. +To avoid silent language changes when upgrading to a new Scala 2.13 version, it is recommended to enable features explicitly or use a group (e.g., `-Xsource-features:v2.13.14`). + +`-Xsource:3-cross` is a shorthand for `-Xsource:3 -Xsource-features:_`. + +### Changes in language semantics + +The following table shows backported Scala 3 language semantics available in `-Xsource-features` / `-Xsource:3-cross`. + +| Feature flag | `-Xsource:3` behavior | `-Xsource-features` / `-Xsource:3-cross` behavior | +|--- |--- |--- | +| `any2stringadd`: `(x: Any) + ""` is deprecated | deprecation warning | does not compile, implicit `any2stringadd` is not inferred | +| `unicode-escapes-raw`: unicode escapes in triple-quoted strings and raw interpolations (`"""\u0061"""`) | fatal warning, escape is processed | escape is not processed | +| `leading-infix`: leading infix operators continue the previous line 1 | fatal warning, second line is a separate expression | operation continues the previous line | +| `string-context-scope`: desugaring of string interpolators using `StringContext` | fatal warning if the interpolation references a `StringContext` in scope different from `scala.StringContext` | desugaring always uses `scala.StringContext` | +| `package-prefix-implicits`: an implicit for type `p.A` is found in the package prefix `p` | fatal warning | the package prefix `p` is no longer part of the implicit search scope | +| `implicit-resolution`: specificity during implicit search | fatal warning | use Scala-3-style [downwards comparisons](https://github.com/scala/scala/pull/6037) for implicit search and overloading resolution | +| `case-apply-copy-access`: modifiers of synthetic methods | fatal warning | constructor modifiers are used for apply / copy methods of case classes | +| `case-companion-function`: companions are Functions | fatal warning at use site | synthetic case companion objects no longer extend FunctionN, but are adapted at use site with warning | +| `infer-override`: override type inference | fatal warning | inferred type of member uses type of overridden member | +| `double-definitions`: definitions differing in empty parens 2 | fatal warning | double definition error | + +Example 1: + +{% highlight scala %} + def f = + 1 + + 2 +{% endhighlight %} + +Example 2: + +{% highlight scala %} +class C(x: Int) { + def x(): Int = x // allowed in Scala 2, double definition error in Scala 3 +} +{% endhighlight %} + +### Changes affecting binary encoding + +As of Scala 2.13.15, there are 3 changes in `-Xsource-features` that affect binary encoding of classfiles: + + 1. `case-apply-copy-access`: the constructor modifiers of case classes (`case class C private[p] (x: Int)`) are copied to the synthetic `apply` and `copy` methods. + 1. `case-companion-function`: the synthetic companion objects of case classes no longer extend `FunctionN`. + 1. `infer-override`: overriding methods without an explicit return type inherit the return type from the parent (instead of using the inferred type of the method body). + +For projects that are already cross-building between Scala 2 and 3 with existing releases for both, enabling these changes breaks binary compatibility (make sure to use [MiMa to detect such changes](https://github.com/lightbend/mima)). For example, if a library defines + +{% highlight scala %} +trait A { def f: Object } +class B extends A { def f = "hi" } +{% endhighlight %} + + - enabling `-Xsource-features:infer-override` breaks binary compatibility on Scala 2.13: existing releases have `A.f: String`, the new version will have `A.f: Object` + - adding an explicit result type `A.f: String` breaks binary compatibility on Scala 3: existing releases have `A.f: Object` + +It is possible to work around this using version-dependent source files, see [scala/scala-xml#675](https://github.com/scala/scala-xml/pull/675) as an example. + +Instead of implementing such workarounds, it might be easier not to enable changes affecting binary encoding (`-Xsource-features:v2.13.14,-case-apply-copy-access,-case-companion-function,-infer-override`). diff --git a/_overviews/scala3-migration/tooling-syntax-rewriting.md b/_overviews/scala3-migration/tooling-syntax-rewriting.md new file mode 100644 index 0000000000..5cd51e0cc7 --- /dev/null +++ b/_overviews/scala3-migration/tooling-syntax-rewriting.md @@ -0,0 +1,243 @@ +--- +title: Scala 3 Syntax Rewriting +type: chapter +description: This section describes the syntax rewriting capability of the Scala 3 compiler +num: 15 +previous-page: tutorial-macro-mixing +next-page: incompatibility-table +--- + +Scala 3 extends the syntax of the Scala language with the new control structures and the significant indentation syntax. +Both are optional so that the Scala 2 code style is still perfectly valid in Scala 3. + +The new syntax for control structures makes it possible to write the condition of an `if`-expression, the condition of a `while`-loop or the generators of a `for`-expression without enclosing parentheses. + +The significant indentation syntax makes braces `{...}` not needed in many occurences: class and method bodies, `if`-expressions, `match`-expressions and more. +You can find a complete description in the [Optional Braces]({{ site.scala3ref }}/other-new-features/indentation.html) page of the Scala 3 reference website. + +Converting existing Scala code to the new syntax by hand is tedious and error-prone. +In this chapter we show how you can use the compiler to rewrite your code automatically from the classic Scala 2 style to the new style, or conversely. + +## Syntax Rewriting Options + +Let's start with showing the compiler options we have available to achieve our goal. +If we simply type `scalac` on the command line it prints all the options we have at our disposal. +For our purposes we will use the following five options: + +{% highlight text %} +$ scalac +Usage: scalac +where possible standard options include: +... +-indent Allow significant indentation +... +-new-syntax Require `then` and `do` in control expressions. +-no-indent Require classical {...} syntax, indentation is not significant. +... +-old-syntax Require `(...)` around conditions. +... +-rewrite When used in conjunction with a `...-migration` source version, + rewrites sources to migrate to new version. +... + +{% endhighlight %} + +Each of the first four options corresponds to a specific syntax: + +| Syntax | Option | +| - | - | +| New Control Structures | `-new-syntax` | +| Old Control Structures | `-old-syntax` | + +| Syntax | Compiler Option | +|-|-| +| Significant Indentation | `-indent` | +| Classical Braces | `-no-indent` | + + +As we will see in further detail these options can be used in combination with the `-rewrite` option to automate the conversion to a particular syntax. +Let's have a look at how this works in a small example. + +## The New Syntax Rewrites + +Given the following source code written in a Scala 2 style. + +{% tabs scala-2-location %} +{% tab 'Scala 2 Only' %} +```scala +case class State(n: Int, minValue: Int, maxValue: Int) { + + def inc: State = + if (n == maxValue) + this + else + this.copy(n = n + 1) + + def printAll: Unit = { + println("Printing all") + for { + i <- minValue to maxValue + j <- 0 to n + } println(i + j) + } +} +``` +{% endtab %} +{% endtabs %} + +We will be able to move it to new syntax automatically in two steps: first by using the new control structure rewrite (`-new-syntax -rewrite`) and then the significant indentation rewrite (`-indent -rewrite`). + +> The `-indent` option does not work on the classic control structures. +> So make sure to run the two steps in the correct order. + +> Unfortunately, the compiler is not able to apply both steps at the same time: `-indent -new-syntax -rewrite`. + +### New Control Structures + +We can use the `-new-syntax -rewrite` options by adding them to the list of scalac options in our build tool. + +{% tabs sbt-location %} +{% tab 'sbt' %} +```scala +// build.sbt, for Scala 3 project +scalacOptions ++= Seq("-new-syntax", "-rewrite") +``` +{% endtab %} +{% endtabs %} + +After compiling the code, the result looks as follows: + +{% tabs scala-3-location_2 %} +{% tab 'Scala 3 Only' %} +```scala +case class State(n: Int, minValue: Int, maxValue: Int) { + + def inc: State = + if n == maxValue then + this + else + this.copy(n = n + 1) + + def printAll: Unit = { + println("Printing all") + for + i <- minValue to maxValue + j <- 0 to n + do println(i + j) + } +} +``` +{% endtab %} +{% endtabs %} + +Notice that the parentheses around the `n == maxValue` disappeared, as well as the braces around the `i <- minValue to maxValue` and `j <- 0 to n` generators. + +### Significant Indentation Syntax + +After this first rewrite, we can use the significant indentation syntax to remove the remaining braces. +To do that we use the `-indent` option in combination with the `-rewrite` option. +It leads us to the following version: + +{% tabs scala-3-location_3 %} +{% tab 'Scala 3 Only' %} +```scala +case class State(n: Int, minValue: Int, maxValue: Int): + + def inc: State = + if n == maxValue then + this + else + this.copy(n = n + 1) + + def printAll: Unit = + println("Printing all") + for + i <- minValue to maxValue + j <- 0 to n + do println(i + j) +``` +{% endtab %} +{% endtabs %} + +## Moving back to the Classic syntax + +Starting from the latest state of our code sample, we can move backwards to its initial state. + +Let's rewrite the code using braces while retaining the new control structures. +After compiling with the `-no-indent -rewrite` options, we obtain the following result: + +{% tabs scala-3-location_4 %} +{% tab 'Scala 3 Only' %} +```scala +case class State(n: Int, minValue: Int, maxValue: Int) { + + def inc: State = + if n == maxValue then + this + else + this.copy(n = n + 1) + + def printAll: Unit = { + println("Printing all") + for { + i <- minValue to maxValue + j <- 0 to n + } + do println(i + j) + } +} +``` +{% endtab %} +{% endtabs %} + +Applying one more rewrite, with `-old-syntax -rewrite`, takes us back to the original Scala 2-style code. + +{% tabs shared-location %} +{% tab 'Scala 2 and 3' %} +```scala +case class State(n: Int, minValue: Int, maxValue: Int) { + + def inc: State = + if (n == maxValue) + this + else + this.copy(n = n + 1) + + def printAll: Unit = { + println("Printing all") + for { + i <- minValue to maxValue + j <- 0 to n + } + println(i + j) + } +} +``` +{% endtab %} +{% endtabs %} + +With this last rewrite, we have come full circle. + +> #### Loss of formatting when cycling through syntax versions +> +> When formatting tools such as [scalafmt](https://scalameta.org/scalafmt) are used to apply custom formatting to your code, cycling back and forth between different Scala 3 syntax variants may result in differences when going full circle. + +## Enforcing a Specific Syntax + +It is possible to mix the old and new syntax in a single code base. +Although we would advise against it, since it would reduce the readability and make the code harder to maintain. +A better approach is to choose one style and to consistently apply it to the entire code base. + +`-no-indent`, `-new-syntax` and `-old-syntax` can be used as standalone options to enforce a consistent syntax. + +For instance, with the `-new-syntax` option, the compiler issues an error when it encounters enclosing parentheses around an `if`-condition. + +{% highlight text %} +-- Error: /home/piquerez/scalacenter/syntax/example.scala:6:7 ------------------ +6 | if (n == maxValue) + | ^^^^^^^^^^^^^^^ + |This construct is not allowed under -new-syntax. + |This construct can be rewritten automatically under -new-syntax -rewrite -source 3.0-migration. +{% endhighlight %} + +> The `-indent` syntax is always optional, it cannot be enforced by the compiler. diff --git a/_overviews/scala3-migration/tooling-tour.md b/_overviews/scala3-migration/tooling-tour.md new file mode 100644 index 0000000000..5a5f1fe686 --- /dev/null +++ b/_overviews/scala3-migration/tooling-tour.md @@ -0,0 +1,128 @@ +--- +title: Tour of the Migration Tools +type: chapter +description: This chapter is a tour of the migration tooling ecosystem +num: 6 +previous-page: compatibility-metaprogramming +next-page: tooling-scala2-xsource3 +--- + +## The Scala Compilers + +The migration has been carefully prepared beforehand in each of the two compilers so that the transition is easy and smooth. + +### The Scala 2.13 Compiler + +The Scala 2.13 compiler supports `-Xsource:3`, an option that enables migration warnings and certain Scala 3 syntax and behavior. + +The [Scala 2 with -Xsource:3](tooling-scala2-xsource3.html) page explains the flag in detail. + + +### The Scala 3 Compiler + +#### Migration Mode + +Similarly the Scala 3 compiler comes with the `-source:3.0-migration` option. +From this mode, it accepts some of the old Scala 2.13 syntax and issues warnings to explain the changes. + +Even more than that, you can combine it with `-rewrite` to patch your code automatically. + +Learn more about it in the [Scala 3 Migration Mode](tooling-migration-mode.html) page. + +#### Syntax Rewriting + +Once your code is compiled in Scala 3 you can convert it to the new and optional Scala 3 syntax by using the [Syntax Rewriting](tooling-syntax-rewriting.html) options. + +## Build tools + +### sbt + +> The `sbt-dotty` plugin was needed in sbt 1.4 to get support for Scala 3. +> It is not useful anymore since sbt 1.5. + +sbt supports Scala 3 out-of-the-box. +All common tasks and settings are intended to work the same. +Many sbt plugins should also work exactly the same. + +To help with the migration, sbt 1.5 introduces new Scala 3 specific cross versions: + +```scala +// Use a Scala 2.13 library in Scala 3 +libraryDependency += ("org.foo" %% "foo" % "1.0.0").cross(CrossVersion.for3Use2_13) + +// Use a Scala 3 library in Scala 2.13 +libraryDependency += ("org.bar" %% "bar" % "1.0.0").cross(CrossVersion.for2_13Use3) +``` + +### Mill + +[Mill](https://github.com/com-lihaoyi/mill) 0.9.x supports Scala 3. + +### Maven + +The Scala Maven plugin supports Scala 3 since 4.5.1. + +## Code editors and IDEs + +### Metals + +[Metals](https://scalameta.org/metals/) is the Scala extension for VS Code. +It also works with Vim, Emacs, Sublime Text, and other editors. + +### IntelliJ IDEA + +The [Scala plugin for IntelliJ](https://plugins.jetbrains.com/plugin/1347-scala) supports Scala 3. + +## Formatting Tools + +### Scalafmt + +[Scalafmt](https://scalameta.org/scalafmt/) supports Scala 2.13 and Scala 3 since v3.0.0. + +To enable Scala 3 formatting you must set the `runner.dialect = scala3` in your `.scalafmt.conf` file. + +If you want to enable it selectively you can set a `fileOverride` configuration: + +```conf +//.scalafmt.conf +fileOverride { + "glob:**/scala-3*/**" { + runner.dialect = scala3 + } +} +``` + +Scalafmt can also enforce the new Scala 3 syntax with the [Scala 3 rewrites](https://scalameta.org/scalafmt/docs/configuration.html#scala3-rewrites). + +## Migration Tools + +### Scalafix + +[Scalafix](https://scalacenter.github.io/scalafix/) is a refactoring tool for Scala. + +The [Incompatibility Table](incompatibility-table.html) shows which incompatibility can be fixed by an existing Scalafix rule. +So far the relevant rules are: +- [Procedure Syntax](https://scalacenter.github.io/scalafix/docs/rules/ProcedureSyntax.html) +- [Explicit Result Types](https://scalacenter.github.io/scalafix/docs/rules/ExplicitResultTypes.html) +- Value Eta-Expansion: `fix.scala213.ExplicitNullaryEtaExpansion` in [scala/scala-rewrites](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNullaryEtaExpansion.scala) +- Auto Application: `fix.scala213.ExplicitNonNullaryApply` in [scala/scala-rewrites](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/ExplicitNonNullaryApply.scala) +- `any2stringadd` Conversion: `fix.scala213.Any2StringAdd` in [scala/scala-rewrites](https://github.com/scala/scala-rewrites/blob/main/rewrites/src/main/scala/fix/scala213/Any2StringAdd.scala) + +You can apply these rules in sbt using the `sbt-scalafix` plugin. +They are also used internally in `sbt-scala3-migrate` described below. + +### The Scala 3 Migration Plugin for sbt + +[Scala 3 Migrate](https://github.com/scalacenter/scala3-migrate) is an sbt plugin that can assist you during the migration to Scala 3. + +It proposes an incremental approach, based on four sbt commands: +- `migrateDependencies` helps you update the list of `libraryDependencies` +- `migrateScalacOptions` helps you update the list of `scalacOptions` +- `migrateSyntax` fixes a number of syntax incompatibilities between Scala 2.13 and Scala 3 +- `migrateTypes` tries to code compile your code to Scala 3 by infering types and resolving implicits where needed. + +The detailed instructions on how to use Scala 3 Migrate can be found [here](scala3-migrate.html). + +## Scaladex + +Check the list of Scala 3 open-source libraries in [Scaladex](https://index.scala-lang.org/). diff --git a/_overviews/scala3-migration/tutorial-intro.md b/_overviews/scala3-migration/tutorial-intro.md new file mode 100644 index 0000000000..822bfa2319 --- /dev/null +++ b/_overviews/scala3-migration/tutorial-intro.md @@ -0,0 +1,22 @@ +--- +title: Migration Tutorial +type: chapter +description: This chapter contains the tutorials for porting a Scala 2.13 project to Scala 3 +num: 9 +previous-page: tooling-migration-mode +next-page: tutorial-prerequisites +--- + +You are ready to port your project to Scala 3! + +The first step is to check that the [Prerequisites](tutorial-prerequisites.html) are met by your project. + +If you use sbt we recommend you to go to [Porting an sbt Project (using sbt-scala3-migrate)](scala3-migrate.html), or you can go to [Porting an sbt Project (by hand)](tutorial-sbt.html). + +> **You are not using sbt?** +> +> We still advise you to read the [Porting a sbt Project (by hand)](tutorial-sbt.html) tutorial since the workflow is the same in other build tools. +> Prior to that, make sure the version of your build tool is up-to-date to support Scala 3. + + +[Cross-Building a Macro Library](tutorial-macro-cross-building.html) and [Mixing Scala 2.13 and Scala 3 Macros](tutorial-macro-mixing.html) are specialized tutorials for porting Scala 2 macro libraries. diff --git a/_overviews/scala3-migration/tutorial-macro-cross-building.md b/_overviews/scala3-migration/tutorial-macro-cross-building.md new file mode 100644 index 0000000000..8d45ed3f90 --- /dev/null +++ b/_overviews/scala3-migration/tutorial-macro-cross-building.md @@ -0,0 +1,251 @@ +--- +title: Cross-Building a Macro Library +type: section +description: This section shows how to cross-build a macro library +num: 13 +previous-page: tutorial-sbt +next-page: tutorial-macro-mixing +--- + +Macro libraries must be re-implemented from the ground-up. + +Before starting you should be familiar with the Scala 3 migration as described in the [Porting an sbt Project](tutorial-sbt.html) tutorial. +The purpose of the current tutorial is to cross-build an existing Scala 2.13 macro library so that it becomes available in both Scala 3 and Scala 2.13. + +An alternative solution called *Mixing Macros* is explained in the [next tutorial](tutorial-macro-mixing.html). +You are encouraged to read both solutions to choose the technique that is best suited for your needs. + +## Introduction + +In order to exemplify this tutorial, we will consider the minimal macro library defined below. + +```scala +// build.sbt +lazy val example = project + .in(file("example")) + .settings( + scalaVersion := "2.13.11", + libraryDependencies ++= Seq( + "org.scala-lang" % "scala-reflect" % scalaVersion.value + ) + ) +``` + +{% tabs scala-2-location %} +{% tab 'Scala 2 Only' %} +```scala +// example/src/main/scala/location/Location.scala +package location + +import scala.reflect.macros.blackbox.Context +import scala.language.experimental.macros + +case class Location(path: String, line: Int) + +object Macros { + def location: Location = macro locationImpl + + private def locationImpl(c: Context): c.Tree = { + import c.universe._ + val location = typeOf[Location] + val line = Literal(Constant(c.enclosingPosition.line)) + val path = Literal(Constant(c.enclosingPosition.source.path)) + q"new $location($path, $line)" + } +} +``` +{% endtab %} +{% endtabs %} + +You should recognize some similarities with your library: +one or more macro methods, in our case the `location` method, are implemented by consuming a macro `Context` and returning a `Tree` from this context. + +We can make this library available for Scala 3 users by using the [Cross Building](https://www.scala-sbt.org/1.x/docs/Cross-Build.html) technique provided by sbt. + +The main idea is to build the artifact twice and to publish two releases: +- `example_2.13` for Scala 2.13 users +- `example_3` for Scala 3 users + +![Cross-building Architecture](/resources/images/scala3-migration/tutorial-macro-cross-building.svg) + +## 1. Set cross-building up + +You can add Scala 3 to the list of `crossScalaVersions` of your project: + +```scala +crossScalaVersions := Seq("2.13.11", "3.3.1") +``` + +The `scala-reflect` dependency won't be useful in Scala 3. +Remove it conditionally with something like: + +```scala +// build.sbt +libraryDependencies ++= { + CrossVersion.partialVersion(scalaVersion.value) match { + case Some((2, 13)) => Seq( + "org.scala-lang" % "scala-reflect" % scalaVersion.value + ) + case _ => Seq.empty + } +} +``` + +After reloading sbt, you can switch to the Scala 3 context by running `++3.3.1`. +At any point you can go back to the Scala 2.13 context by running `++2.13.11`. + +## 2. Rearrange the code in version-specific source directories + +If you try to compile with Scala 3 you should see some errors of the same kind as: + +{% highlight text %} +sbt:example> ++3.3.1 +sbt:example> example / compile +[error] -- Error: /example/src/main/scala/location/Location.scala:15:35 +[error] 15 | val location = typeOf[Location] +[error] | ^ +[error] | No TypeTag available for location.Location +[error] -- Error: /example/src/main/scala/location/Location.scala:18:4 +[error] 18 | q"new $location($path, $line)" +[error] | ^ +[error] |Scala 2 macro cannot be used in Dotty. See https://dotty.epfl.ch/docs/reference/dropped-features/macros.html +[error] |To turn this error into a warning, pass -Xignore-scala2-macros to the compiler +{% endhighlight %} + +To provide a Scala 3 alternative while preserving the Scala 2 implementation, we are going to rearrange the code in version-specific source directories. +All the code that cannot be compiled by the Scala 3 compiler goes to the `src/main/scala-2` folder. + +> Scala version-specific source directories is an sbt feature that is available by default. +> Learn more about it in the [sbt documentation](https://www.scala-sbt.org/1.x/docs/Cross-Build.html). + +In our example, the `Location` class stays in the `src/main/scala` folder but the `Macros` object is moved to the `src/main/scala-2` folder: + +{% tabs shared-location %} +{% tab 'Scala 2 and 3' %} +```scala +// example/src/main/scala/location/Location.scala +package location + +case class Location(path: String, line: Int) +``` +{% endtab %} +{% endtabs %} + +{% tabs scala-2-location_2 %} +{% tab 'Scala 2 Only' %} +```scala +// example/src/main/scala-2/location/Macros.scala +package location + +import scala.reflect.macros.blackbox.Context +import scala.language.experimental.macros + +object Macros { + def location: Location = macro locationImpl + + private def locationImpl(c: Context): c.Tree = { + import c.universe._ + val location = typeOf[Location] + val line = Literal(Constant(c.enclosingPosition.line)) + val path = Literal(Constant(c.enclosingPosition.source.path)) + q"new $location($path, $line)" + } +} +``` +{% endtab %} +{% endtabs %} + +Now we can initialize each of our Scala 3 macro definitions in the `src/main/scala-3` folder. +They must have the exact same signature than their Scala 2.13 counterparts. + +{% tabs scala-3-location_1 %} +{% tab 'Scala 3 Only' %} +```scala +// example/src/main/scala-3/location/Macros.scala +package location + +object Macros: + inline def location: Location = ??? +``` +{% endtab %} +{% endtabs %} + +## 3. Implement the Scala 3 macro + +There is no magic formula to port a Scala 2 macro into Scala 3. +One needs to learn about the new [Metaprogramming](compatibility-metaprogramming.html) features. + +We eventually come up with this implementation: + +{% tabs scala-3-location_2 %} +{% tab 'Scala 3 Only' %} +```scala +// example/src/main/scala-3/location/Macros.scala +package location + +import scala.quoted.{Quotes, Expr} + +object Macros: + inline def location: Location = ${locationImpl} + + private def locationImpl(using quotes: Quotes): Expr[Location] = + import quotes.reflect.Position + val pos = Position.ofMacroExpansion + val file = Expr(pos.sourceFile.path.toString) + val line = Expr(pos.startLine + 1) + '{new Location($file, $line)} +``` +{% endtab %} +{% endtabs %} + +## 4. Cross-validate the macro + +Adding some tests is important to check that the macro method works the same in both Scala versions. + +In our example, we add a single test. + +{% tabs shared-test %} +{% tab 'Scala 2 and 3' %} +```scala +// example/src/test/scala/location/MacrosSpec.scala +package location + +class MacrosSpec extends munit.FunSuite { + test("location") { + assertEquals(Macros.location.line, 5) + } +} +``` +{% endtab %} +{% endtabs %} + +You should now be able to run the tests in both versions. + +{% highlight text %} +sbt:example> ++2.13.11 +sbt:example> example / test +location.MacrosSpec: + + location +[info] Passed: Total 1, Failed 0, Errors 0, Passed 1 +[success] +sbt:example> ++3.3.1 +sbt:example> example / test +location.MacrosSpec: + + location +[info] Passed: Total 1, Failed 0, Errors 0, Passed 1 +[success] +{% endhighlight %} + +## Final overview + +Your macro project should now contain the following source files: +- `src/main/scala/*.scala`: Cross-compatible classes +- `src/main/scala-2/*.scala`: The Scala 2 implementation of the macro methods +- `src/main/scala-3/*.scala`: The Scala 3 implementation of the macro methods +- `src/test/scala/*.scala`: Common tests + +![Cross-building Architecture](/resources/images/scala3-migration/tutorial-macro-cross-building.svg) + +You are now ready to publish your library by creating two releases: +- `example_2.13` for Scala 2.13 users +- `example_3` for Scala 3 users diff --git a/_overviews/scala3-migration/tutorial-macro-mixing.md b/_overviews/scala3-migration/tutorial-macro-mixing.md new file mode 100644 index 0000000000..4a013b4284 --- /dev/null +++ b/_overviews/scala3-migration/tutorial-macro-mixing.md @@ -0,0 +1,221 @@ +--- +title: Mixing Scala 2.13 and Scala 3 Macros +type: section +description: This section shows how to mix Scala 2.13 and Scala 3 macros in a single artifact +num: 14 +previous-page: tutorial-macro-mixing +next-page: tooling-syntax-rewriting +--- + +This tutorial shows how to mix Scala 2.13 and Scala 3 macros in a single artifact. This means that consumers can use `-Ytasty-reader` from Scala 2.13 code that uses your macros. + +There are two main benefits of this: + +1. Making a new or existing scala 3 macro library available for Scala 2.13 users without having to provide a separate 2.13 version +2. Allowing your macros to be usable in multi-project builds that are being upgraded module by module. + +## Introduction + +The Scala 2.13 compiler can only expand Scala 2.13 macros and, conversely, the Scala 3 compiler can only expand Scala 3 macros. +The idea of mixing macros is to package both macros in a single artifact, and let the compiler choose between the two during the macro expansion phase. + +This is only possible in Scala 3, since the Scala 3 compiler can read both the Scala 3 and the Scala 2 definitions. + +Let's start by considering the following code skeleton: + +{% tabs scala-3-location_1 %} +{% tab 'Scala 3 Only' %} +```scala +// example/src/main/scala/location/Location.scala +package location + +case class Location(path: String, line: Int) + +object Macros: + def location: Location = macro ??? + inline def location: Location = ${ ??? } +``` +{% endtab %} +{% endtabs %} + +As you can see the `location` macro is defined twice: +- `def location: Location = macro ???` is a Scala 2.13 macro definition +- `inline def location: Location = ${ ??? }` is a Scala 3 macro definition + +`location` is not an overloaded method, since both signatures are strictly identical. +This is quite surprising! +How does the compiler accept two methods with the same name and signature? + +The explanation is that it recognizes the first definition is for Scala 2.13 only and the second is for Scala 3 only. + +## 1. Implement the Scala 3 macro + +You can put the Scala 3 macro implementation alongside the definition. + +{% tabs scala-3-location_2 %} +{% tab 'Scala 3 Only' %} +```scala +package location + +import scala.quoted.{Quotes, Expr} + +case class Location(path: String, line: Int) + +object Macros: + def location: Location = macro ??? + inline def location: Location = ${locationImpl} + + private def locationImpl(using quotes: Quotes): Expr[Location] = + import quotes.reflect.Position + val file = Expr(Position.ofMacroExpansion.sourceFile.jpath.toString) + val line = Expr(Position.ofMacroExpansion.startLine + 1) + '{new Location($file, $line)} +``` +{% endtab %} +{% endtabs %} + +## 2. Implement the Scala 2 macro + +The Scala 3 compiler can compile a Scala 2 macro implementation if it contains no quasiquote or reification. + +For instance this piece of code does compile with Scala 3, and so you can put it alongside the Scala 3 implementation. + +{% tabs scala-2-and-3-location %} +{% tab 'Scala 2 and 3' %} +```scala +import scala.reflect.macros.blackbox.Context + +def locationImpl(c: Context): c.Tree = { + import c.universe._ + val line = Literal(Constant(c.enclosingPosition.line)) + val path = Literal(Constant(c.enclosingPosition.source.path)) + New(c.mirror.staticClass(classOf[Location].getName()), path, line) +} +``` +{% endtab %} +{% endtabs %} + +However, in many cases you will have to move the Scala 2.13 macro implementation in a Scala 2.13 submodule. + +```scala +// build.sbt + +lazy val example = project.in(file("example")) + .settings( + scalaVersion := "3.3.1" + ) + .dependsOn(`example-compat`) + +lazy val `example-compat` = project.in(file("example-compat")) + .settings( + scalaVersion := "2.13.12", + libraryDependencies += "org.scala-lang" % "scala-reflect" % scalaVersion.value + ) +``` + +Here `example`, our main library compiled in Scala 3, depends on `example-compat` which is compiled in Scala 2.13. + +In such a case we can put the Scala 2 macro implementation in `example-compat` and use quasiquotes. + +{% tabs scala-2-location %} +{% tab 'Scala 2 Only' %} +```scala +package location + +import scala.reflect.macros.blackbox.Context +import scala.language.experimental.macros + +case class Location(path: String, line: Int) + +object Scala2MacrosCompat { + private[location] def locationImpl(c: Context): c.Tree = { + import c.universe._ + val location = typeOf[Location] + val line = Literal(Constant(c.enclosingPosition.line)) + val path = Literal(Constant(c.enclosingPosition.source.path)) + q"new $location($path, $line)" + } +} +``` +{% endtab %} +{% endtabs %} + +Note that we had to move the `Location` class downstream. + +## 3. Cross-validate the macro + +Adding some tests is important to check that the macro method works the same in both Scala versions. + +Since we want to execute the tests in Scala 2.13 and Scala 3, we create a cross-built module on the top: + +```scala +// build.sbt +lazy val `example-test` = project.in(file("example-test")) + .settings( + scalaVersion := "3.3.1", + crossScalaVersions := Seq("3.3.1", "2.13.12"), + scalacOptions ++= { + CrossVersion.partialVersion(scalaVersion.value) match { + case Some((2, 13)) => Seq("-Ytasty-reader") + case _ => Seq.empty + } + }, + libraryDependencies += "org.scalameta" %% "munit" % "0.7.26" % Test + ) + .dependsOn(example) +``` + +> `-Ytasty-reader` is needed in Scala 2.13 to consume Scala 3 artifacts + +For instance the test can be: + +{% tabs scala-2-and-3-test %} +{% tab 'Scala 2 and 3' %} +```scala +// example-test/src/test/scala/location/MacrosSpec.scala +package location + +class MacrosSpec extends munit.FunSuite { + test("location") { + assertEquals(Macros.location.line, 5) + } +} +``` +{% endtab %} +{% endtabs %} + +You should now be able to run the tests in both versions. + +{% highlight text %} +sbt:example> ++2.13.12 +sbt:example> example-test / test +location.MacrosSpec: + + location +[info] Passed: Total 1, Failed 0, Errors 0, Passed 1 +[success] +sbt:example> ++3.3.1 +sbt:example> example-test / test +location.MacrosSpec: + + location +[info] Passed: Total 1, Failed 0, Errors 0, Passed 1 +[success] +{% endhighlight %} + +## Final Overview + +You library is now composed of: +- The main Scala 3 module containing the mixed macro definitions and the Scala 3 macro implementation. +- The Scala 2.13 compatibility module containing the Scala 2.13 macro implementation. +It will only be consumed in Scala 2.13 during the macro expansion phase of the compiler. + +![Mixing-macros Architecture](/resources/images/scala3-migration/tutorial-macro-mixing.svg) + +You are now ready to publish your library. + +It can be used in Scala 3 projects, or in Scala 2.13 projects with these settings: + +```scala +scalaVersion := "2.13.12" +libraryDependencies += ("org" %% "example" % "x.y.z").cross(CrossVersion.for2_13Use3) +scalacOptions += "-Ytasty-reader" +``` diff --git a/_overviews/scala3-migration/tutorial-prerequisites.md b/_overviews/scala3-migration/tutorial-prerequisites.md new file mode 100644 index 0000000000..55c1c3fe42 --- /dev/null +++ b/_overviews/scala3-migration/tutorial-prerequisites.md @@ -0,0 +1,126 @@ +--- +title: Prerequisites +type: section +description: This section details the prerequisites of migration to Scala 3 +num: 10 +previous-page: tutorial-intro +next-page: scala3-migrate +--- + +The migration to Scala 3 is made easier thanks to the interoperability between Scala 2.13 and Scala 3, as described in the [Compatibility Reference](compatibility-intro.html) page. + +However, there are a few prerequisites that a Scala 2.13 project must meet before being ported to Scala 3: +- It must not depend on a macro library that has not yet been ported to Scala 3. +- It must not use a compiler plugin that has no equivalent in Scala 3. +- It must not depend on `scala-reflect`. + +The following paragraphs explain how to check those prerequisites and, in case they are unmet, what you can do about it. + +If you are ready to proceed with the migration you can jump straight to the [sbt Migration Tutorial](tutorial-sbt.html). + +## Macro dependencies + +A macro library is a Scala library that exposes a macro method. + +Those libraries tend to be more expressive and as such they are widely used in Scala 2. +We can mention as examples: +- [lightbend/scala-logging](https://index.scala-lang.org/lightbend/scala-logging) +- [milessabin/shapeless](https://index.scala-lang.org/milessabin/shapeless) +- [playframework/play-json](https://index.scala-lang.org/playframework/play-json) +- [scalatest/scalatest](https://index.scala-lang.org/scalatest/scalatest) + +But the Scala 3 compiler cannot expand Scala 2.13 macros. +So, before jumping to Scala 3, you should make sure that your project does not depend on a macro library that has not yet been ported. + +You can find the migration status of many macro libraries in the [Scala Macro Libraries](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html) page. +Hopefully many will already be ported by the time you read these lines. + +For each of these macro dependencies in your project, you need to upgrade it to a cross-built version---a version available on both Scala 2.13 and Scala 3. + +Let's take a quick example. + +The dependency to `"scalatest" %% "scalatest" % "3.0.9"` must be upgraded because: +- The `scalatest` API is based on some macro definitions. +- The `3.0.9` version is not published for Scala 3. + +We can upgrade it to version `3.2.19`, which is cross-published in Scala 2.13 and Scala 3. + +```scala +libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" +``` + +## Compiler plugins + +The Scala 2 compiler plugins are not compatible with Scala 3. + +Compiler plugins are generally configured in the `build.sbt` file by one of these settings: + +```scala +// build.sbt +libraryDependencies += + compilerPlugin("org.typelevel" %% "kind-projector" % "0.11.0" cross CrossVersion.full) + +addCompilerPlugin("org.typelevel" %% "kind-projector" % "0.11.0" cross CrossVersion.full) +``` + +Some compiler plugins may also be automatically added by an sbt plugin. + +You can find all configured compiler plugins by looking at the compiler options of your project. + +{% highlight text %} +sbt:example> show example / Compile / scalacOptions +[info] * -Xplugin:target/compiler_plugins/wartremover_2.13.6-2.4.15.jar +[info] * -Xplugin:target/compiler_plugins/semanticdb-scalac_2.13.6-4.4.18.jar +[info] * -Yrangepos +[info] * -P:semanticdb:targetroot:/example/target/scala-2.13/meta +{% endhighlight %} + +In the above example we can see that two compiler plugins are used: wartremover and semanticdb. +For each of these plugins, we need to check that there is an alternative solution, or we need to disable it. + +Alternative solutions to the most used compiler plugins are given below. + +### SemanticDB + +The support of [SemanticDB](https://scalameta.org/docs/semanticdb/guide.html) is now shipped into the Scala 3 compiler: +- The `-Ysemanticdb` option activates the generation of semanticDB files. +- The `-semanticdb-target` option can be used to specify the output directory of semanticDB files. + +sbt is able to configure SemanticDB automatically with this single setting: `semanticdbEnabled := true`. + +### Scala.js + +The [Scala.js](https://www.scala-js.org/) compilation on Scala 3 does not rely on a compiler plugin anymore. + +To compile your Scala.js project you can use the `sbt-scalajs` plugin version `1.5.0` or higher. + +```scala +// project/plugins.sbt +addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.5.0") +``` + +### Scala Native + +Scala 3 is supported in [Scala Native](https://scala-native.org/) since v0.4.3. + +The minimal version of Scala 3 supported by Scala Native is 3.1.0, due to fatal blockers in Scala 3.0.x + +### Kind Projector + +A subset of [the Kind Projector](https://github.com/typelevel/kind-projector) syntax is supported by Scala 3 under the `-Ykind-projector` option. + +AdditionalLy, we now have the following features that make `kind-projector` not needed in many cases: +- [Type Lambdas](http://dotty.epfl.ch/docs/reference/new-types/type-lambdas.html) +- [Polymorphic Functions](http://dotty.epfl.ch/docs/reference/new-types/polymorphic-function-types.html) +- [Kind Polymorphism](http://dotty.epfl.ch/docs/reference/other-new-features/kind-polymorphism.html) + +You can learn more about the Kind Projector migration in its [dedicated page](plugin-kind-projector.html). + +## Runtime reflection + +`scala-reflect` will not be ported to Scala 3 because it exposes Scala 2 compiler internals that do not exist in Scala 3. + +If your project depends on `scala-reflect`, or consumes instances of the `Manifest` class, it cannot be compiled by the Scala 3 compiler. +To remedy this situation, you can try to re-implement the corresponding parts of the code, using Java reflection or the [Scala 3 metaprogramming features](compatibility-metaprogramming.html). + +If `scala-reflect` is transitively added in your classpath, you probably need to upgrade the dependency that brings it. diff --git a/_overviews/scala3-migration/tutorial-sbt.md b/_overviews/scala3-migration/tutorial-sbt.md new file mode 100644 index 0000000000..67d1ffed36 --- /dev/null +++ b/_overviews/scala3-migration/tutorial-sbt.md @@ -0,0 +1,228 @@ +--- +title: Porting an sbt Project (by hand) +type: section +description: This section shows how to port an sbt project +num: 12 +previous-page: scala3-migrate +next-page: tutorial-macro-cross-building +--- + +> This tutorial is written for sbt. +> Yet the approach is very similar for any other build tool, as long as it supports Scala 3. + +Before jumping to Scala 3, make sure you are on the latest Scala 2.13.x and sbt 1.5.x versions. + +Let's now walk through the required steps to port an entire project to Scala 3. + +## 1. Check the project prerequisites + +Make sure your project is ready to be ported: +- It must not depend on a macro library that has not yet been ported to Scala 3. +- It must not use a compiler plugin that has no equivalent in Scala 3. +- It must not depend on `scala-reflect`. + +Those prerequisites are described in more details in the [preceding page](tutorial-prerequisites.html). + +## 2. Choose a module + +Thanks to the interoperability between Scala 2.13 and Scala 3 you can start with any module. +However it is probably simpler to start with the module that has the fewest dependencies. + +If you use macro definitions or macros annotations internally you will have to port them first. + +## 3. Set up cross-building + +The two main challenges of the codebase migration are: +- Make the code compile +- Make sure that the run-time behavior is unchanged + +We recommend the cross-building strategy, that is to compile the code with both Scala 3 and Scala 2.13. +The logic behind is to be able to run the tests with Scala 2.13 after each fix and thus make sure that the runtime behavior is unchanged. +This is crucial to avoid bugs that could happen when fixing the incompatibilities. + +Configuring cross-building in sbt is as short as: + +```scala +scalaVersion := "3.3.1" +crossScalaVersions ++= Seq("2.13.11", "3.3.1") +``` + +This configuration means: +- The default version is `3.3.1`. +- 2.13.11 can be loaded by running the `++2.13.11` command. +- 3.3.1 can be loaded by running the `++3.3.1` command. + +Beware that the `reload` command will always load the default version---here it is 3.3.1. + +## 4. Prepare the dependencies + +At this stage, if you run `compile`, it is likely that sbt complains about some dependencies being not found. +That is because the declared version of the dependency is not published for Scala 3. + +You either need to upgrade the dependency to a newer version or to tell sbt to use the Scala 2.13 version of the library. + +> When you change a library dependency, make sure to apply the same change in all modules of your project. + +Check if there is an available Scala 3 version of the library. +To do so, you can use the version matrix in [Scaladex](https://index.scala-lang.org/). +Go to the project page of your library, click the version matrix button, filter on Scala 3 and Scala 2.13. + +#### 1. There is a Scala 3 version of the library + +We strongly suggest to use one of the available versions. +Make sure the one you choose does not bring any breaking change. + +#### 2. There is no Scala 3 version of the library + +You can use the Scala 2.13 version of the library. The syntax is: + +```scala +("com.lihaoyi" %% "os-lib" % "0.7.7").cross(CrossVersion.for3Use2_13) +``` + +Or for a Scala.js dependencies: + +```scala +("com.lihaoyi" %%% "os-lib" % "0.7.7").cross(CrossVersion.for3Use2_13) +``` + +Once you have fixed all the unresolved dependencies, you can check that the tests are still passing in Scala 2.13: + +{% highlight text %} +sbt:example> ++2.13.11 +[info] Setting Scala version to 2.13.11 on 1 project. +... +sbt:example> example / test +... +[success] +{% endhighlight %} + +## 5. Configure the Scala 3 Compiler + +The Scala 3 compiler options are different from the Scala 2.13 ones: some have been renamed, others are not yet supported. +You can refer to the [Compiler Options Lookup](options-lookup.html) page to adapt the list of `scalacOptions` to Scala 3. + +You should come up with a list of common options, a list of Scala 2.13-specific options and a list of Scala 3-specific options. + +A typical configuration looks like this: +```scala +scalacOptions ++= { + Seq( + "-encoding", + "UTF-8", + "-feature", + "-language:implicitConversions", + // disabled during the migration + // "-Xfatal-warnings" + ) ++ + (CrossVersion.partialVersion(scalaVersion.value) match { + case Some((3, _)) => Seq( + "-unchecked", + "-source:3.0-migration" + ) + case _ => Seq( + "-deprecation", + "-Xfatal-warnings", + "-Wunused:imports,privates,locals", + "-Wvalue-discard" + ) + }) +} +``` + +Add the `-source:3.0-migration` option to turn on the [Scala 3 Migration Mode](tooling-migration-mode.html). +Also you should disable `-Xfatal-warnings` to take full advantage of the migration mode and the automatic rewrites. + +## 6. Solve the Incompatibilities + +It is now time to try compiling in Scala 3: + +{% highlight text %} +sbt:example> ++3.3.1 +[info] Setting Scala version to 3.3.1 on 1 project. +... +sbt:example> example / compile +... +sbt:example> example / Test / compile +{% endhighlight %} + +> `example / compile` compiles the `main` sources of the example project. +> It is strictly equivalent to `example / Compile / compile`. +> +> `example / Test / compile` compiles the `test` sources. + +The compiler produces diagnostics of two different levels: +- *Migration Warning*: These warnings can be automatically patched by the compiler with the `-rewrite` option. +- *Error*: A piece of code cannot be compiled anymore. + +You can ignore the migration warnings since the compiler will automatically fix them. +However the incompatibility errors must be taken care of manually. + +Many known incompatibilities are listed in the [Incompatibility Table](incompatibility-table.html). +That's where you can find a description and some proposed solutions of the errors. + +When possible you should try to find a fix that best preserves the binary compatibility of your code. +This is particularly crucial if your project is a published library. + +> The macro incompatibilities cannot be easily solved. +> A lot of code must be rewritten from the ground up. +> See [Metaprogramming](compatibility-metaprogramming.html). + +After fixing an incompatibility, you can validate the solution by running the tests in Scala 2.13. + +{% highlight text %} +sbt:example> ++2.13.11 +[info] Setting Scala version to 2.13.11 on 1 project. +... +sbt:example> example / test +... +[success] +{% endhighlight %} + +Consider committing your changes regularly. + +Once you have fixed all the errors you should be able to compile successfully in Scala 3. +Only the migration warnings are remaining. +You can patch them automatically by compiling with the `-source:3.0-migration -rewrite` options. + +{% highlight text %} +sbt:example> ++3.3.1 +sbt:example> set example / scalacOptions += "-rewrite" +sbt:example> example / compile +... +[info] [patched file /example/src/main/scala/app/Main.scala] +[warn] two warnings found +[success] +{% endhighlight %} + +You should now remove the `-source:3.0-migration` option, and you can also add the `-Xfatal-warnings` option again. +Do not forget to reload. + +## 7. Validate the migration + +On rare occasions, different implicit values could possibly be resolved and alter the runtime behavior of the program. +Good tests are the only guarantee to prevent such bugs from going unnoticed. + +Make sure that the tests are passing in both Scala 2.13 and Scala 3. + +{% highlight text %} +sbt:example> ++2.13.11 +sbt:example> example / test +... +[success] +sbt:example> ++3.3.1 +sbt:example> example / test +... +[success] +{% endhighlight %} + +If you have a continuous integration pipeline, it is time to set it up for Scala 3. + +## 8. Finalize the migration + +Congratulations! You have successfully ported a module to Scala 3. +The same process can be repeated for each module, until the project is fully migrated to Scala 3. + +You can keep or drop the Scala 2.13 cross-building configuration depending on whether you want to cross-publish your program or not. + +Here ends our walk through the migration of an sbt project. diff --git a/_overviews/scala3-scaladoc/blog.md b/_overviews/scala3-scaladoc/blog.md new file mode 100644 index 0000000000..ba845fc913 --- /dev/null +++ b/_overviews/scala3-scaladoc/blog.md @@ -0,0 +1,76 @@ +--- +layout: multipage-overview +title: Built-in blog +partof: scala3-scaladoc +languages: ["ru"] +num: 5 +previous-page: static-site +next-page: site-versioning +--- + +Scaladoc allows you to include a simple blog in your documentation. For now, it +provides only basic features. In the future, we plan to include more advanced +features like tagging or author pages. + +Blog is treated a little differently than regular static sites. This article will help you set up your own blog. + +## Proper directory setup + +All your blogposts must be put under `_blog/_posts` directory. + + +``` +├── _blog +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html +``` + +Scaladoc loads blog if the `_blog` directory exists. + +## Naming convention + +All the blogpost filenames should start with date in numeric format matching `YYYY-MM-DD`. +Example name is `2015-10-23-dotty-compiler-bootstraps.md`. + +## Page metadata + +The blog pages in scaladoc support [Yaml Frontmatter](https://assemble.io/docs/YAML-front-matter.html) which allows you to specify different values which will be used for metadata in your page. Here are the possible fields: + +``` +--- +layout: +author: +title: +subTitle: <Subtitle of the page> +date: <Date of the creation of the page>, e.g. 2016-12-05 +authorImg: <Link to the author's image> +--- +<Content of your page> +``` + +You can also find more details about the front matter on the [Jekyll documentation site](https://jekyllrb.com/docs/front-matter/). + +## Syntax of the content +Keep in mind that the writing of your blog is done with Markdown. You can find more information about the syntax in [Markdown Guide](https://www.markdownguide.org/basic-syntax/). + +## Blog configuration +When creating your blog, Scaladoc also allows you to configure it. + +In order to modify the default settings of the blog documentation, users need to create a file named `blog.yml` in the **root directory of the blog**. The file should contain the parameters that the user wants to change. For example, if a user wants to change the input directory to "my_posts", the output directory to "my_docs", and temporarily hide the blog, they can create a file with the following content: + +``` +input: my_posts +output: my_docs +hidden: true +``` + +### Parameters: + +`input`: specifies the directory containing markdown files for the blog posts (default: "_posts" in "docs"). + +`output`: specifies the folder where HTML pages will be generated (default: "blog" in "target/docs"). + +`hidden`: allows users to temporarily hide the blog (default: "false"). + +To change these settings, create a file with the parameters and save it in the blog's root directory. The next time the blog is built, the new settings will be used. \ No newline at end of file diff --git a/_overviews/scala3-scaladoc/docstrings.md b/_overviews/scala3-scaladoc/docstrings.md new file mode 100644 index 0000000000..0aed8c373f --- /dev/null +++ b/_overviews/scala3-scaladoc/docstrings.md @@ -0,0 +1,199 @@ +--- +layout: multipage-overview +title: Docstrings - specific Tags and Features +partof: scala3-scaladoc +languages: ["ru"] +num: 2 +previous-page: index +next-page: linking +--- + +This chapter describes how to correctly write docstrings and how to use all the available features of scaladoc. +Since many things are the same as in the old scaladoc, some parts are reused from this [article](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html) + + +Scaladoc extends Markdown with additional features, such as linking +to API definitions. This can be used from within static documentation and blog +posts to provide blend-in content. + + +## Where to put docstrings + +Scaladoc comments go before the items they pertain to in a special comment block that starts with a /** and ends with a */, like this: + +```scala +/** Start the comment here + * and use the left star followed by a + * white space on every line. + * + * Even on empty paragraph-break lines. + * + * Note that the * on each line is aligned + * with the second * in /** so that the + * left margin is on the same column on the + * first line and on subsequent ones. + * + * Close the comment with *\/ + * + * If you use Scaladoc tags (@param, @group, etc.), + * remember to put them at separate lines with nothing preceding. + * + * For example: + * + * Calculate the square of the given number + * + * @param d the Double to square + * @return the result of squaring d + */ + def square(d: Double): Double = d * d +``` + +In the example above, this Scaladoc comment is associated with the method square since it is right before it in the source code. + +Scaladoc comments can go before fields, methods, classes, traits, objects. +For now, scaladoc doesn't support straightforward solution to document packages. There is a dedicated github +[issue](https://github.com/scala/scala3/issues/11284), where you can check the current status of the problem. + +For class primary constructors which in Scala coincide with the definition of the class itself, a @constructor tag is used to target a comment to be put on the primary constructor documentation rather than the class overview. + +## Tags + +Scaladoc uses `@<tagname>` tags to provide specific detail fields in the comments. These include: + +### Class specific tags + +- `@constructor` placed in the class comment will describe the primary constructor. + +### Method specific tags + +- `@return` detail the return value from a method (one per method). + +### Method, Constructor and/or Class tags + +- `@throws` what exceptions (if any) the method or constructor may throw. +- `@param` detail a value parameter for a method or constructor, provide one per parameter to the method/constructor. +- `@tparam` detail a type parameter for a method, constructor or class. Provide one per type parameter. + +### Usage tags + +- `@see` reference other sources of information like external document links or related entities in the documentation. +- `@note` add a note for pre or post conditions, or any other notable restrictions or expectations. +- `@example` for providing example code or related example documentation. + + +### Member grouping tags + +These tags are well-suited to larger types or packages, with many members. They allow you to organize the Scaladoc page into distinct sections, with each one shown separately, in the order that you choose. + +These tags are not enabled by default! You must pass the -groups flag to Scaladoc in order to turn them on. Typically the sbt for this will look something like: + +```scala +Compile / doc / scalacOptions ++= Seq( + "-groups" +) +``` +Each section should have a single-word identifier that is used in all of these tags, shown as `group` below. By default, that identifier is shown as the title of that documentation section, but you can use @groupname to provide a longer title. + +Typically, you should put @groupprio (and optionally @groupname and @groupdesc) in the Scaladoc for the package/trait/class/object itself, describing what all the groups are, and their order. Then put @group in the Scaladoc for each member, saying which group it is in. + +Members that do not have a `@group` tag will be listed as “Ungrouped” in the resulting documentation. + +- `@group <group>` - mark the entity as a member of the `<group>` group. +- `@groupname <group> <name>` - provide an optional name for the group. `<name>` is displayed as the group header before the group description. +- `@groupdesc <group> <description>` - add optional descriptive text to display under the group name. Supports multiline formatted text. +- `@groupprio <group> <priority>` - control the order of the group on the page. Defaults to 0. Ungrouped elements have an implicit priority of 1000. Use a value between 0 and 999 to set a relative position to other groups. Low values will appear before high values. + +### Other tags + +- `@author` provide author information for the following entity +- `@version` the version of the system or API that this entity is a part of. +- `@since` like `@version` but defines the system or API that this entity was first defined in. +- `@deprecated` marks the entity as deprecated, providing both the replacement implementation that should be used and the version/date at which this entity was deprecated. +- `@syntax <name>` let you change the parser for docstring. The default syntax is markdown, however you can change it using this directive. Currently available syntaxes are `markdown` or `wiki`, e. g. `@syntax wiki` + +### Macros + +- `@define <name> <definition>` allows use of $name in other Scaladoc comments within the same source file which will be expanded to the contents of `<definition>`. + +If a comment is not provided for an entity at the current inheritance level, but is supplied for the overridden entity at a higher level in the inheritance hierarchy, the comment from the super-class will be used. + +Likewise if `@param`, `@tparam`, `@return` and other entity tags are omitted but available from a superclass, those comments will be used. + +### Explicit + +For explicit comment inheritance, use the @inheritdoc tag. + +### Markup + +Scaladoc provides two syntax parsers: `markdown` (default) or `wikidoc`. +It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but not necessary most of the time as markup may be used instead. + +#### Markdown + +Markdown uses [commonmark flavour](https://spec.commonmark.org/current/) with two custom extensions: +- `wikidoc` links for referencing convenience +- `wikidoc` codeblocks with curly braces syntax + + +#### Wikidoc + +Wikidoc is syntax used for scala2 scaladoc. It is supported because of many existing source code, however it is **not** recommended to use it in new projects. +Wikisyntax can be toggled on with flag `-comment-syntax wiki` globally, or with `@syntax wiki` directive in docstring. + +Some of the standard markup available: + +``` +`monospace` +''italic text'' +'''bold text''' +__underline__ +^superscript^ +,,subscript,, +[[entity link]], e.g. [[scala.collection.Seq]] +[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]] +``` + +For more info about wiki links look at this [chapter](#linking-to-api) + +Other formatting notes + +- Paragraphs are started with one (or more) blank lines. `*` in the margin for the comment is valid (and should be included) but the line should be blank otherwise. +- Headings are defined with surrounding `=` characters, with more `=` denoting subheadings. E.g. `=Heading=`, `==Sub-Heading==`, etc. +- List blocks are a sequence of list items with the same style and level, with no interruptions from other block styles. Unordered lists can be bulleted using `-`, numbered lists can be denoted using `1.`, `i.`, `I.`, or `a.` for the various numbering styles. In both cases, you must have extra space in front, and more space makes a sub-level. + +The markup for list blocks looks like: + +``` +/** Here is an unordered list: + * + * - First item + * - Second item + * - Sub-item to the second + * - Another sub-item + * - Third item + * + * Here is an ordered list: + * + * 1. First numbered item + * 1. Second numbered item + * i. Sub-item to the second + * i. Another sub-item + * 1. Third item + */ +``` + +### General Notes for Writing Scaladoc Comments + +Concise is nice! Get to the point quickly, people have limited time to spend on your documentation, use it wisely. +Omit unnecessary words. Prefer returns X rather than this method returns X, and does X,Y & Z rather than this method does X, Y and Z. +DRY - don’t repeat yourself. Resist duplicating the method description in the @return tag and other forms of repetitive commenting. + +### More details on writing Scaladoc + +Further information on the formatting and style recommendations can be found in [Scala-lang scaladoc style guide](https://docs.scala-lang.org/style/scaladoc.html). + +## Linking to API + +Scaladoc allows linking to API documentation with Wiki-style links. Linking to +`scala.collection.immutable.List` is as simple as +`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation]({% link _overviews/scala3-scaladoc/linking.md %}#definition-links). diff --git a/_overviews/scala3-scaladoc/index.md b/_overviews/scala3-scaladoc/index.md new file mode 100644 index 0000000000..c00475f4ba --- /dev/null +++ b/_overviews/scala3-scaladoc/index.md @@ -0,0 +1,12 @@ +--- +layout: multipage-overview +title: Scaladoc +partof: scala3-scaladoc +languages: ["ru"] +num: 1 +next-page: docstrings +--- + +![scaladoc logo]({{ site.baseurl }}/resources/images/scala3/scaladoc/logo.svg) + +scaladoc is a tool to generate the API documentation of your Scala 3 projects. It provides similar features to `javadoc` as well as `jekyll` or `docusaurus`. diff --git a/_overviews/scala3-scaladoc/linking.md b/_overviews/scala3-scaladoc/linking.md new file mode 100644 index 0000000000..05301d8f85 --- /dev/null +++ b/_overviews/scala3-scaladoc/linking.md @@ -0,0 +1,100 @@ +--- +layout: multipage-overview +title: Linking documentation +partof: scala3-scaladoc +languages: ["ru"] +num: 3 +previous-page: docstrings +next-page: static-site +--- + +Scaladoc's main feature is creating API documentation from code comments. + +By default, the code comments are understood as Markdown, though we also support +Scaladoc's old [Wiki syntax](https://docs.scala-lang.org/style/scaladoc.html). + +## Syntax + +### Definition links + +Our definition link syntax is quite close to Scaladoc's syntax, though we have made some +quality-of-life improvements. + +#### Basic syntax + +A definition link looks as follows: `[[scala.collection.immutable.List]]`. + +Which is to say, a definition link is a sequence of identifiers separated by +`.`. The identifiers can be separated with `#` as well for Scaladoc compatibility. + +By default, an identifier `id` references the first (in source order) entity +named `id`. An identifier can end with `$`, which forces it to refer to a value +(an object, a value, a given); an identifier can also end with `!`, which forces +it to refer to a type (a class, a type alias, a type member). + +The links are resolved relative to the current location in source. That is, when +documenting a class, the links are relative to the entity enclosing the class (a +package, a class, an object); the same applies to documenting definitions. + +Special characters in links can be backslash-escaped, which makes them part of +identifiers instead. For example, `` [[scala.collection.immutable\.List]] `` +references the class named `` `immutable.List` `` in package `scala.collection`. + +#### New syntax + +We have extended Scaladoc definition links to make them a bit more pleasant to +write and read in source. The aim was also to bring the link and Scala syntax +closer together. The new features are: + +1. `package` can be used as a prefix to reference the enclosing package + Example: + ``` + package utils + class C { + def foo = "foo". + } + /** See also [[package.C]]. */ + class D { + def bar = "bar". + } + ``` + The `package` keyword helps make links to the enclosing package shorter + and a bit more resistant to name refactorings. +1. `this` can be used as a prefix to reference the enclosing classlike + Example: + ``` + class C { + def foo = "foo" + /** This is not [[this.foo]], this is bar. */ + def bar = "bar" + } + ``` + Using a Scala keyword here helps make the links more familiar, as well as + helps the links survive class name changes. +1. Backticks can be used to escape identifiers + Example: + ``` + def `([.abusive.])` = ??? + /** TODO: Figure out what [[`([.abusive.])`]] is. */ + def foo = `([.abusive.])` + ``` + Previously (versions 2.x), Scaladoc required backslash-escaping to reference such identifiers. Now (3.x versions), + Scaladoc allows using the familiar Scala backtick quotation. + +#### Why keep the Wiki syntax for links? + +There are a few reasons why we've kept the Wiki syntax for documentation links +instead of reusing the Markdown syntax. Those are: + +1. Nameless links in Markdown are ugly: `[](definition)` vs `[[definition]]` + By far, most links in documentation are nameless. It should be obvious how to + write them. +2. Local member lookup collides with URL fragments: `[](#field)` vs `[[#field]]` +3. Overload resolution collides with MD syntax: `[](meth(Int))` vs `[[meth(Int)]]` +4. Now that we have a parser for the link syntax, we can allow spaces inside (in + Scaladoc one needed to slash-escape those), but that doesn't get recognized + as a link in Markdown: `[](meth(Int, Float))` vs `[[meth(Int, Float)]]` + +None of these make it completely impossible to use the standard Markdown link +syntax, but they make it much more awkward and ugly than it needs to be. On top +of that, Markdown link syntax doesn't even save any characters. diff --git a/_overviews/scala3-scaladoc/search-engine.md b/_overviews/scala3-scaladoc/search-engine.md new file mode 100644 index 0000000000..612972811f --- /dev/null +++ b/_overviews/scala3-scaladoc/search-engine.md @@ -0,0 +1,87 @@ +--- +layout: multipage-overview +title: Type-based search +partof: scala3-scaladoc +languages: ["ru"] +num: 7 +previous-page: site-versioning +next-page: snippet-compiler +--- + +Searching for functions by their symbolic names can be time-consuming. +That is why the new scaladoc allows searching for methods and fields by their types. + + +Consider the following extension method definition: +``` +extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ... +``` +Instead of searching for `span` we can also search for `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`. + +To use this feature, type the signature of the member you are looking for in the scaladoc searchbar. This is how it works: + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif) + +This feature is provided by the [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which works for Scala 3 and Kotlin. To be up-to-date with the development of this feature, follow the [Inkuire repository](https://github.com/VirtusLab/Inkuire). + +## Examples of queries + +Some examples of queries with intended results: +- `List[Int] => (Int => Long) => List[Long]` -> `map` +- `Seq[A] => (A => B) => Seq[B]` -> `map` +- `(A, B) => A` -> `_1` +- `Set[Long] => Long => Boolean` -> `contains` +- `Int => Long => Int` -> `const` +- `String => Int => Char` -> `apply` +- `(Int & Float) => (String | Double)` -> `toDouble`, `toString` +- `F[A] => Int` -> `length` + +## Query syntax + +In order for a scaladoc searchbar query to be searched using Inkuire instead of the default search engine, the query has to contain the `=>` character sequence. + +Accepted input is similar to a curried function signature in Scala 3. With some differences: +- AndTypes, OrTypes and Functions have to be enclosed in parentheses e.g. `(Int & Any) => String` +- fields and parameterless methods can be found by preceding their type with `=>`, e.g., `=> Int` +- A wildcard `_` can be used to indicate that we want to match any type in a given place e.g. `Long => Double => _` +- Types in the form of single letter e.g. `A` or a letter with a digit `X1` are automatically assumed to be type variables +- Other type variables can be declared just like in polymorphic functions e.g. `[AVariable, AlsoAVariable] => AVariable => AlsoAVariable => AVariable` + +### Working with type aliases and method receivers + +When it comes to how the code is mapped to InkuireDb entries, there are some transformations to make the engine more opinionated (though open to suggestions and changes). Firstly, the receiver (non-module owner) of a function can be treated as a first argument. Automatic currying is also applied, so that the results don't depend on argument lists. When finding matches, `val`s and `def`s are not distinguished. + +So the following declarations should be found by query `Num => Int => Int => Int`: +``` +class Num(): + def a(i: Int, j: Int): Int + def b(i: Int)(j: Int): Int + def c(i: Int): (Int => Int) + val d: Int => Int => Int + val e: Int => Int => Int + val f: (Int, Int) => Int +end Num + +def g(i: Num, j: Int, k: Int): Int +extension (i: Num) def h(j: Int, k: Int): Int +def i(i: Num, j: Int)(k: Int): Int +extension (i: Num) def j(j: Int)(k: Int): Int +... +``` + +When it comes to type aliases, they are desugared on both the declaration and the query signature. This means that for declarations: +``` +type Name = String + +def fromName(name: Name): String +def fromString(str: String): Name +``` +both methods, `fromName` and `fromString`, should be found for queries `Name => Name`, `String => String`, `Name => String` and `String => Name`. + +## How it works + +Inkuire works as a JavaScript worker in the browser thanks to the power of [ScalaJS](https://www.scala-js.org/). + +To enable Inkuire when running scaladoc, add the flag `-Ygenerate-inkuire`. By adding this flag two files are generated: +- `inkuire-db.json` - this is the file containing all the searchable declarations from the currently documented project in a format readable to the Inkuire search engine. +- `inkuire-config.json` - this file contains the locations of the database files that should be searchable from the documentation of the current project. By default, it will be generated with the location of the local db file as well as the default implied locations of database files in [External mappings](/scala3/guides/scaladoc/settings.html#-external-mappings). diff --git a/_overviews/scala3-scaladoc/settings.md b/_overviews/scala3-scaladoc/settings.md new file mode 100644 index 0000000000..1fae4d3d5f --- /dev/null +++ b/_overviews/scala3-scaladoc/settings.md @@ -0,0 +1,194 @@ +--- +layout: multipage-overview +title: Settings +partof: scala3-scaladoc +languages: ["ru"] +num: 9 +previous-page: snippet-compiler +--- + +This chapter lists the configuration options that can be used when calling scaladoc. Some of the information shown here can be found by calling scaladoc with the `-help` flag. + +## Parity with scaladoc for Scala 2 + +Scaladoc has been rewritten from scratch and some of the features turned out to be useless in the new context. +If you want to know what is current state of compatibility with scaladoc old flags, you can visit this issue for tracking [progress](https://github.com/scala/scala3/issues/11907). + +## Providing settings + +Supply scaladoc settings as command-line arguments, e.g., `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. If called from sbt, update the value of `Compile / doc / scalacOptions` and `Compile / doc / target` respectively, e. g. + +``` +Compile / doc / target := file("output"), +Compile / doc / scalacOptions ++= Seq("-project", "my-project"), +``` + +## Overview of all available settings + +##### -project +The name of the project. To provide compatibility with Scala2 aliases with `-doc-title` + +##### -project-version +The current version of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-version` + +##### -project-logo +The logo of your project that appears in a top left corner. A separate logo for the dark theme can be provided with the suffix `_dark`. If the logo is, for example, `mylogo.png`, then `mylogo_dark.png` is assumed for the dark theme. To provide compatibility with Scala2 aliases with `-doc-logo` + +##### -project-footer +The string message that appears in a footer section. To provide compatibility with Scala2 aliases with `-doc-footer` + +##### -comment-syntax +The styling language used for parsing comments. +Currently we support two syntaxes: `markdown` or `wiki` +If setting is not present, scaladoc defaults `markdown` + +##### -revision +Revision (branch or ref) used to build project. Useful with sourcelinks to prevent them from pointing always to the newest main that is subject to changes. + +##### -source-links +Source links provide a mapping between file in documentation and code repository. + +Example source links is: +`-source-links:docs=github://scala/scala3/main#docs` + +Accepted formats: + +`<sub-path>=<source-link>` + +where `<source-link>` is one of following: + - `github://<organization>/<repository>[/revision][#subpath]` + will match https://github.com/$organization/$repository/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber] + when revision is not provided then requires revision to be specified as argument for scaladoc + - `gitlab://<organization>/<repository>` + will match https://gitlab.com/$organization/$repository/-/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber] + when revision is not provided then requires revision to be specified as argument for scaladoc + - `<scaladoc-template>` + +`<scaladoc-template>` is a format for `doc-source-url` parameter from old scaladoc. +NOTE: We only supports `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`, + `€{FILE_PATH}`, and `€{FILE_LINE}` patterns. + + +Template can defined only by subset of sources defined by path prefix represented by `<sub-path>`. +In such case paths used in templates will be relativized against `<sub-path>` + + + +##### -external-mappings + +Mapping between regexes matching classpath entries and external documentation. + +Example external mapping is: +`-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/` + +A mapping is of the form `<regex>::[scaladoc3|scaladoc|javadoc]::<path>`. You can supply several mappings, separated by commas, as shown in the example. + +##### -social-links + +Links to social sites. For example: + +`-social-links:github::https://github.com/scala/scala3,discord::https://discord.com/invite/scala,twitter::https://x.com/scala_lang` + +Valid values are of the form: `[github|twitter|gitter|discord]::link`. Scaladoc also supports `custom::link::white_icon_name::black_icon_name`. In this case icons must be present in `images/` directory. + +##### -skip-by-id + +Identifiers of packages or top-level classes to skip when generating documentation. + +##### -skip-by-regex + +Regexes that match fully qualified names of packages or top-level classes to skip when generating documentation. + +##### -doc-root-content + +The file from which the root package documentation should be imported. + +##### -author + +Adding authors in docstring with `@author Name Surname` by default won't be included in generated html documentation. +If you would like to label classes with authors explicitly, run scaladoc with this flag. + +##### -groups + +Group similar functions together (based on the @group annotation) + +##### -private + +Show all types and members. Unless specified, show only public and protected types and members. + +##### -doc-canonical-base-url + +A base URL to use as prefix and add `canonical` URLs to all pages. The canonical URL may be used by search engines to choose the URL that you want people to see in search results. If unset no canonical URLs are generated. + +##### -siteroot + +A directory containing static files from which to generate documentation. Default directory is `./docs` + +##### -no-link-warnings + +Suppress warnings for ambiguous or incorrect links in members’ lookup. Doesn't affect warnings for incorrect links of assets etc. + +##### -versions-dictionary-url + +A URL pointing to a JSON document containing a dictionary: `version label -> documentation location`. +The JSON file has single property `versions` that holds the dictionary associating the labels of specific versions of the documentation to the URLs pointing to their index.html +Useful for libraries that maintain different versions of their documentation. + +Example JSON file: +``` +{ + "versions": { + "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", + "Nightly": "https://dotty.epfl.ch/docs/index.html" + } +} +``` + +##### -snippet-compiler + +Snippet compiler arguments provide a way to configure snippet type checking. + +This setting accepts a list of arguments in the format: +args := arg{,args} +arg := [path=]flag +where `path` is a prefix of the path to source files where snippets are located and `flag` is the mode in which snippets will be type checked. + +If the path is not present, the argument will be used as the default for all unmatched paths. + +Available flags: +- compile - Enables snippet checking. +- nocompile - Disables snippet checking. +- fail - Enables snippet checking, asserts that snippet doesn't compile. + +The fail flag comes in handy for snippets that present that some action would eventually fail during compilation, e. g. [Opaques page]({{ site.scala3ref }}/other-new-features/opaques.html) + +Example usage: + +`-snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile` + +Which means: + +- all snippets in files under directory `my/path/nc` should not be compiled at all +- all snippets in files under directory `my/path/f` should fail during compilation +- all other snippets should compile successfully + +##### -scastie-configuration + +Define the additional sbt configuration for your Scastie snippets. For example, when you import external libraries into your snippets, you need to add the related dependencies. + +``` +"-scastie-configuration", """libraryDependencies += "org.apache.commons" % "commons-lang3" % "3.12.0"""" +``` + +##### -dynamic-side-menu + +Generate the side menu (the tree-like overview of the project structure on the left-hand side) dynamically in the browser using JavaScript instead of embedding it in every HTML file. This can greatly reduce outputted HTML file sizes. Recommended for projects with 1000+ pages. For more info see [issue 18543](https://github.com/scala/scala3/issues/18543). + +##### -Ysnippet-compiler-debug + +Setting this option makes snippet compiler print the snippet as it is compiled (after wrapping). + +##### -Ydocument-synthetic-types + +Include pages providing documentation for the intrinsic types (e. g. Any, Nothing) to the docs. The setting is useful only for stdlib because scaladoc for Scala 3 relies on TASTy files, but we cannot provide them for intrinsic types since they are embedded in the compiler. +All other users should not concern with this setting. diff --git a/_overviews/scala3-scaladoc/site-versioning.md b/_overviews/scala3-scaladoc/site-versioning.md new file mode 100644 index 0000000000..910b1f77ce --- /dev/null +++ b/_overviews/scala3-scaladoc/site-versioning.md @@ -0,0 +1,40 @@ +--- +layout: multipage-overview +title: Site versioning +partof: scala3-scaladoc +languages: ["ru"] +num: 6 +previous-page: blog +next-page: search-engine +--- + +Scaladoc provides a convenient way to switch between different versions of the documentation. The feature is useful if we want to expose older docs for users that didn't migrate to the new version of our library. + +### How to setup it + +The feature was designed for easy scalability with no need to regenerate all scaladocs after adding a new version. To do so a new setting is introduced: `-versions-dictionary-url`. Its argument must be a URL to a JSON document holding information about the locations of specific versions. The JSON file has single property `versions` that holds the dictionary associating the labels of specific versions of the documentation to the URLs pointing to their index.html + +Example JSON file: +``` +{ + "versions": { + "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", + "Nightly": "https://dotty.epfl.ch/docs/index.html" + } +} +``` + +This enforce us to provide the setting while generating docs for each of the versions, however it gives us more flexibility later. If you want to add a version of the API docs next to the previous 5 versions that you have already published, then you only need to upload the new docs to a web server and add a new entry to the JSON file. All versions of the site will now become aware of the new site version. + +The important thing to note is that there is only one JSON file to avoid redundancy and each scaladoc must set up its URL location beforehand, for example, in sbt: + +``` +doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/versions.json") +``` + + +### How does it look from user perspective + +Providing a JSON file via `-versions-dictionary-url` enables scaladoc to link between versions. It is also convenient to be able to change the revision label in the drop-down menu. Everything will change automatically. + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/nightly.gif) diff --git a/_overviews/scala3-scaladoc/snippet-compiler.md b/_overviews/scala3-scaladoc/snippet-compiler.md new file mode 100644 index 0000000000..77c9497d98 --- /dev/null +++ b/_overviews/scala3-scaladoc/snippet-compiler.md @@ -0,0 +1,217 @@ +--- +layout: multipage-overview +title: Snippet checking +partof: scala3-scaladoc +languages: ["ru"] +num: 8 +previous-page: search-engine +next-page: settings +--- + +The main functionality of documentation is to help people understand and use the project properly. Sometimes a part of a project needs few words to show its usage, but every developer knows that there are moments where description is not enough and nothing is better than a good ol’ example. + +A convenient way of providing examples in documentation is to create code snippets presenting usage of given functionality. The problem with code snippets is that simultaneously with project development, they need to be updated. Sometimes changes in one part of a project may break examples in other parts. The number of snippets and the amount of time passed since they’ve been written makes it impossible to remember every place where you need to fix them. After some time you realize that your documentation is a complete mess and you need to go through all examples and rewrite them. + +Many Scala 2 projects use typechecked markdown documentation with [tut](https://tpolecat.github.io/tut/) or [mdoc](https://scalameta.org/mdoc/). Almost everyone at least heard about these tools. As they turned out to be very useful and the Scala community successfully adopted them, we’re planning to incorporate the features of tut and mdoc into the compiler so that it’s included out of the box with Scaladoc. + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-compiler3.png) + +## Getting started + +By default, snippet validation is turned off for all snippets. It can be turned on by adding the following argument to Scaladoc: + +`-snippet-compiler:compile` + +For example, in sbt the configuration looks like this: + +```scala +Compile / doc / scalacOptions ++= Seq("-snippet-compiler:compile") +``` + +This option turns on the snippet compiler for all `scala` snippets in the project documentation, and recognizes all snippets inside ```scala blocks. Currently, snippet validation works in both docstrings written in Markdown, and in static sites. +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-compiler4.png) + +If you are starting a new project, this configuration should be enough for you. However, in case you’re migrating an existing project, you might want to disable compilation for some snippets that can't currently be updated. + +To do this, add a `nocompile` flag directly to the `scala` snippet: + +```` +```scala sc:nocompile +// under the hood `map` is transformed into +List(1).map( _ + 1)(<implicits>) +``` +```` + +However, sometimes compilation failure is an intended behavior, e.g., to intentionally demonstrate an error. For this case, we expose a flag `fail` that introduces one of our features: [Assert compilation errors](#assert-compilation-errors). + +```` +```scala sc:fail +List(1,2,3).toMap +``` +```` + +For a more thorough explanation and more sophisticated configurations, such as path-based flag settings, see the [Advanced configuration](#advanced-configuration) section. + +## Features overview + +### Assert compilation errors + +Scala is a statically typed programming language. Sometimes, documentation should mention cases where code should not compile,or authors want to provide ways to recover from certain compilation errors. + +For example, this code: + +```scala +List(1,2,3).toMap +``` + +results in this output: + +```nohighlight + +At 18:21: + List(1,2,3).toMap +Error: Cannot prove that Int <:< (K, V) + +where: K is a type variable with constraint + V is a type variable with constraint +. +``` + +Examples that present code that fails at compile-time can be very important. For example, you can show how a library is secured against incorrect code. Another use case is to present common mistakes, and how to solve them. Taking these use cases into account, we decided to provide functionality to check if the marked code snippets don’t compile. + +For snippets that intentionally fail to compile, such as the following one, add the `fail` flag to the code snippet: +```` +```scala sc:fail +List(1,2,3).toMap +``` +```` +Snippet validation passes and shows expected compilation errors in documentation. +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/assert-compilation-errors.gif) + +For a snippet that compiles without error: +```` +```scala sc:fail +List((1,2), (2,3)).toMap +``` +```` +the resulting output looks like this: +```nohighlight + +In static site (./docs/docs/index.md): +Error: Snippet should not compile but compiled succesfully +``` + + +### Context + +Our goal is to make snippets behave as much as possible as if they were defined within a given scope (e.g., in a certain package, or inside a class). We believe this brings a natural feel to snippets. To achieve this, we implemented a wrapping mechanism that provides a context for each snippet. This preprocessing is done automatically for all snippets in docstrings. + +For example, let’s assume that we want to document the method `slice` in a `collection.List`. We want to explain how it works by comparing it to a combination of `drop` and `take` method so using snippet like: +```scala +slice(2, 5) == drop(2).take(3) +``` +Showing this example is one of the first things that comes to mind, but as you probably guessed, this won’t compile without a **context** feature. + +Besides our main goal, it reduces the boilerplate of a snippet, because you don’t need to import members of the same package and instantiate documented class. + +For people that are curious on how our context mechanism works, the snippet after preprocessing looks like this: +```scala +package scala.collection +trait Snippet[A] { self: List[A] => + slice(2,5) == drop(2).take(3) +} +``` + +### Hiding code + +Despite having the context feature described above, sometimes an author needs to provide more elements to a scope. However, on one hand, a big block of imports and initializations of necessary classes can result in loss of readablity. But on the other hand, we’ve read a lot of opinions that people would like to be able to see the whole code. For this second case we’ve introduced special syntax for snippets that hides certain fragments of code---`import` statements, for example---but also allows that code to be expanded in the documentation with a single click. + +Example: + +```scala +//{ +import scala.collection.immutable.List +//} +val intList: List[Int] = List(1, 2, 3) +``` + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/hiding-code.gif) + +### Snippet includes + +While writing code snippets, we often need a mechanism to reuse code from one snippet in another. For instance, take a look at the following piece of documentation: +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/documentation-snippet.png) + +To successfully compile the last snippet, we need to have previously declared definitions in scope. For this scenario---and probably many more---we added a new feature: snippet includes. This allows you to reuse code from one snippet in another, resulting in less redundancy and better maintainability. + +To configure this, just add a `sc-name` argument to the snippet that you want to include in a later code block: +```` ```scala sc-name:<snippet-name> ```` + +where `snippet-name` should be unique in file scope, and cannot contain whitespaces and commas. + +Then, in a later code block in your documentation, use a `sc-compile-with` argument in the `scala` snippet that should “include” the previous code block: +```` ```scala sc-compile-with:<snippet-name>(,<snippet-name>)+ ```` + +where `snippet-name` is the name of snippet that should be included. + +After configuring this feature in our example, the code looks like this: +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/documentation-snippet2.png) + +and the output looks like this: +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-includes.png) + +You can specify more than one include. Note that the order in which they are specified defines the order of inclusion. + +**Warning**: you can only include snippets that are defined above the target snippet. + +## Advanced configuration + +Often turning on snippet validation for _all_ snippets is not the proper level of control, as the use cases can be more sophisticated. We prepared our tool for such situations, i.e., to allow users to adjust it to their needs. + +### Available flags + +To provide more control, the snippet compiler exposes three flags that let you change its behavior: +- `compile` - turns on snippet checking +- `nocompile` - turns off snippet checking +- `fail` - turns on snippet checking with compilation error assertion + +### Path-based settings + +For more flexibility, instead of setting one flag to control all snippets in a project, it can be set for a certain path only, by adding `<path>=` prefix before flag. For example: + +`-snippet-compiler:docs=compile` - sets the `compile` flag for snippets in the `docs` file. If `docs` is a directory, the flag is set for all files inside `docs` + +Additionally, the `-snippet-compiler` option can be controlled by more than one setting, with settings delimited by commas. For example: +``` +-snippet-compiler:docs=compile,library/src=compile,library/src/scala/quoted=nocompile,library/src/scala/compiletime=fail +``` +Flags are chosen by the longest prefix match, so we can define a general setting and then change that default behavior for more specific paths. +``` +-snippet-compiler:compile,library/src/scala/quoted=nocompile,library/src/scala/compiletime=fail +``` +A flag without a path prefix---such as the `compile` flag in this example---is treated as the default. + +### Override directly in the snippet + +CLI arguments are a good mechanism for setting flags for certain files. However, this approach can’t be used to configure the snippet compiler for specific snippets. For example, an author wants to write one snippet that should fail, and other snippets that should compile. Again we took this under consideration, and added a feature to override settings directly inside snippets. These arguments are located in the snippet info part: + +```` +```scala <snippet-compiler-args> +// snippet +``` +```` + +For instance, to configure snippet checking for a specific snippet, add the following argument to its snippet info part, where `flag` is one of the available flags listed above (e.g., `compile`, `nocompile`, or `fail`): + +`sc:<flag>` + +As a specific example, this code shows how to use the `fail` flag in an individual snippet: + +```` +```scala sc:fail +val itShouldFail: Int = List(1.1, 2, 3).head +``` +```` + + + diff --git a/_overviews/scala3-scaladoc/static-site.md b/_overviews/scala3-scaladoc/static-site.md new file mode 100644 index 0000000000..763ea11fe0 --- /dev/null +++ b/_overviews/scala3-scaladoc/static-site.md @@ -0,0 +1,297 @@ +--- +layout: multipage-overview +title: Static documentation +partof: scala3-scaladoc +languages: ["ru"] +num: 4 +previous-page: linking +next-page: blog +--- + +Scaladoc can generate static sites, known from [Jekyll](http://jekyllrb.com/) or [Docusaurus](https://docusaurus.io/). +Having a combined tool allows providing interaction between static documentation and API, thus allowing the two to blend naturally. + +Creating a site is just as simple as in Jekyll. The site root contains the +the layout of the site and all files placed there will be either considered static, +or processed for template expansion. + +The files that are considered for template expansion must end in `*.{html,md}` +and will from here on be referred to as "template files" or "templates". + +A simple "hello world" site could look something like this: + +``` +. +└── <site-root>/ + └── _docs/ + ├── index.html + └── getting-started.html +``` + +This will give you a site with the following files in generated documentation: + +``` +index.html +getting-started.html +``` + +Scaladoc can transform both files and directories (to organize your documentation into a tree-like structure). By default, directories have a title based on the file name and have empty content. It is possible to provide index pages for each section by creating `index.html` or `index.md` (not both) in the dedicated directory. + +Before generating your static site you need to set the `-siteroot` value in your doc `scalacOptions`. The value of this is the directory that holds your docs. The root URL for the generated documentation will also be `<site-root>`. + +For example if you have a directory called `docs` and you'd like that to be treated as your site root: + +``` +. +└── docs/ + └── _docs/ + ├── index.html + └── getting-started.html +``` + +Then the configuration would be as follows: + +``` +Compile / doc / scalacOptions ++= Seq("-siteroot", "docs") +``` + +Keep in mind that viewing your site locally with all the features it offers, like search or snippets, require a +local server. For example if your output directory was `output` you could use a python server to view everything +by doing the following and opening `localhost:8080`: + +```sh +cd output +python3 -m http.server 8080 +``` + +## Properties + +Scaladoc uses the [Liquid](https://shopify.github.io/liquid/) templating engine +and provides several custom filters and tags specific to Scala +documentation. + +The following project related variables are available and can be accessed using +double curly braces (e.g. `{{ projectTitle }}`): + +- **projectTitle** the project title defined with the `-project` flag. +- **projectVersion** the project version defined with the `-project-version` flag. + +In Scaladoc, all templates can contain YAML front-matter. The front-matter +is parsed and put into the `page` variable available in templates via Liquid. + +Example front-matter + +``` +--- +title: My custom title +--- +``` + +Scaladoc uses some predefined properties to controls some aspects of page. + +Predefined properties: + +- **title** provide page title that will be used in navigation and HTML metadata. +- **extraCss** additional `.css` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** +- **extraJs** additional `.js` files that will be included in this page. Paths should be relative to the documentation root. **This setting is not exported to the template engine.** +- **hasFrame** when set to `false` page will not include default layout (navigation, breadcrumbs, etc.) but only token HTML wrapper to provide metadata and resources (js and css files). **This setting is not exported to the template engine.** +- **layout** - predefined layout to use, see below. **This setting is not exported to the template engine.** + +Redirection properties: + +In addition to the predefined properties, Scaladoc also supports redirection properties, which allow you to redirect from one page to another. This can be useful when you move a page to a new location but want to keep the old URL working. + +- **redirectFrom** - Specifies the URL from which you want to redirect. By using the `redirectFrom` property, Scaladoc generates an empty page at the specified URL, which includes a browser-based redirection to the new location. + +Example: + +``` +--- +redirectFrom: /absolute/path/to/old/url.html +--- +``` + +In the above example, if you move the page from `/absolute/path/to/old/url.html` to a new location, you can use `redirectFrom` to ensure that the old URL still redirects to the new location. + +Please note that the `redirectFrom` property was inspired by the Jekyll plugin called [`jekyll-redirect-from`](https://github.com/jekyll/jekyll-redirect-from) . + +- **redirectTo** - Specifies the URL to which you want to redirect. This property is useful when you want to redirect to an external page or when you can't use `redirectFrom`. + +Example: + +``` +--- +redirectTo: https://docs.scala-lang.org/ +--- +``` + +In the above example, the page will be redirected to `https://docs.scala-lang.org/`. + +## Using existing Templates and Layouts + +To perform template expansion, Dottydoc looks at the `layout` field in the front-matter. +Here's a simple example of the templating system in action, `index.html`: + +```html +--- +layout: main +--- + +<h1>Hello world!</h1> +``` + +With a simple main template like this: + +{% raw %} + +```html +<html> + <head> + <title>Hello, world! + + + {{ content }} + + +``` + +Would result in `{{ content }}` being replaced by `

            Hello world!

            ` from +the `index.html` file. +{% endraw %} + +Layouts must be placed in a `_layouts` directory in the site root: + +``` +├── _layouts +│ └── main.html +└── _docs + ├── getting-started.md + └── index.html +``` + +## Assets + +In order to render assets along with static site, they need to be placed in the `_assets` directory in the site root: + +``` +├── _assets +│ └── images +│ └── myimage.png +└── _docs + └── getting-started.md +``` + +To reference the asset on a page, one needs to create a link relative to the `_assets` directory + +``` +Take a look at the following image: [My image](images/myimage.png) +``` + +## Sidebar + +By default, Scaladoc reflects the directory structure from `_docs` directory in the rendered site. There is also the ability to override it by providing a `sidebar.yml` file in the site root directory. The YAML configuration file describes the structure of the rendered static site and the table of content: + +```yaml +index: index.html +subsection: + - title: Usage + index: usage/index.html + directory: usage + subsection: + - title: Dottydoc + page: usage/dottydoc.html + hidden: false + - title: sbt-projects + page: usage/sbt-projects.html + hidden: false +``` + +The root element needs to be a `subsection`. +Nesting subsections will result in a tree-like structure of navigation. + +`subsection` properties are: + +- `title` - Optional string - A default title of the subsection. + Front-matter titles have higher priorities. +- `index` - Optional string - A path to index page of a subsection. The path is relative to the `_docs` directory. +- `directory` - Optional string - A name of the directory that will contain the subsection in the generated site. + By default, the directory name is the subsection name converted to kebab case. +- `subsection` - Array of `subsection` or `page`. + + Either `index` or `subsection` must be defined. The subsection defined with `index` and without `subsection` will contain pages and directories loaded recursively from the directory of the index page. + +`page` properties are: + +- `title` - Optional string - A default title of the page. + Front-matter titles have higher priorities. +- `page` - String - A path to the page, relative to the `_docs` directory. +- `hidden` - Optional boolean - A flag that indicates whether the page should be visible in the navigation sidebar. By default, it is set to `false`. + +**Note**: All the paths in the YAML configuration file are relative to `/_docs`. + +## Hierarchy of title + +If the title is specified multiple times, the priority is as follows (from highest to lowest priority): + +#### Page + +1. `title` from the `front-matter` of the markdown/html file +2. `title` property from the `sidebar.yml` property +3. filename + +#### Subsection + +1. `title` from the `front-matter` of the markdown/html index file +2. `title` property from the `sidebar.yml` property +3. filename + +Note that if you skip the `index` file in your tree structure or you don't specify the `title` in the frontmatter, there will be given a generic name `index`. The same applies when using `sidebar.yml` but not specifying `title` nor `index`, just a subsection. Again, a generic `index` name will appear. + +## Blog + +Blog feature is described in [a separate document]({% link _overviews/scala3-scaladoc/blog.md %}) + +## Advanced configuration + +### Full structure of site root + +``` +. +└── / + ├── _layouts/ + │ └── ... + ├── _docs/ + │ └── ... + ├── _blog/ + │ ├── index.md + │ └── _posts/ + │ └── ... + └── _assets/ + ├── js/ + │ └── ... + ├── img/ + │ └── ... + └── ... +``` + +It results in a static site containing documents as well as a blog. It also contains custom layouts and assets. The structure of the rendered documentation can be based on the file system but it can also be overridden by YAML configuration. + +### Mapping directory structure + +Using the YAML configuration file, we can define how the source directory structure should be transformed into an outputs directory structure. + +Take a look at the following subsection definition: + +```yaml +- title: Some other subsection + index: abc/index.html + directory: custom-directory + subsection: + - page: abc2/page1.md + - page: foo/page2.md +``` + +This subsection shows the ability of YAML configuration to map the directory structure. +Even though the index page and all defined children are in different directories, they will be rendered in `custom-directory`. +The source page `abc/index.html` will generate a page `custom-directory/index.html`, the source page `abc2/page1.md` will generate a page `custom-directory/page1.html`, +and the source page `foo/page2.md` will generate a page `custom-directory/page2.html`. diff --git a/_overviews/scaladoc/basics.md b/_overviews/scaladoc/basics.md deleted file mode 100644 index 4dc91dad79..0000000000 --- a/_overviews/scaladoc/basics.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-no-masthead -sitemap: false -permalink: /overviews/scaladoc/basics.html -redirect_to: /overviews/scaladoc/for-library-authors.html ---- diff --git a/_overviews/scaladoc/contribute.md b/_overviews/scaladoc/contribute.md new file mode 100644 index 0000000000..0d8999574a --- /dev/null +++ b/_overviews/scaladoc/contribute.md @@ -0,0 +1,23 @@ +--- +layout: multipage-overview +title: Contributing to Scaladoc +partof: scaladoc +overview-name: Scaladoc +num: 5 +permalink: /overviews/scaladoc/:title.html +--- + +If you are interested in contributing to the API documentation of the Scala +standard library (the documentation generated by Scaladoc), please read +[Generating Scaladoc]({{ site.baseurl }}/overviews/scaladoc/generate.html) and +[Scaladoc for Library Authors]({{ site.baseurl }}/overviews/scaladoc/basics.html) first. + +If you'd like to contribute to the actual Scaladoc documentation generation +tool itself, then please see the +[Hacker Set Up Guide](https://scala-lang.org/contribute/hacker-guide.html#2-set-up) +which covers the steps and workflow necessary work on the Scaladoc tool. + +As of Scala 2.13, the Scaladoc tool is maintained but not actively +developed. Major development of Scaladoc will progress as a part of +Dotty for Scala 3 in the +[Scaladoc]({% link _overviews/scala3-scaladoc/index.md %}) tool. diff --git a/_overviews/scaladoc/for-library-authors.md b/_overviews/scaladoc/for-library-authors.md index a0f3639d0d..621861450e 100644 --- a/_overviews/scaladoc/for-library-authors.md +++ b/_overviews/scaladoc/for-library-authors.md @@ -1,15 +1,14 @@ --- layout: multipage-overview title: Scaladoc for Library Authors - -discourse: true - partof: scaladoc overview-name: Scaladoc -num: 2 +num: 3 permalink: /overviews/scaladoc/:title.html +redirect_from: + - /overviews/scaladoc/basics.html --- Scaladoc is a documentation system that lives in the comments of Scala source code @@ -85,7 +84,7 @@ include: ### Usage tags - `@see` reference other sources of information like external document links or related entities in the documentation. -- `@note` add a note for pre or post conditions, or any other notable restrictions +- `@note` add a note for pre- or post-conditions, or any other notable restrictions or expectations. - `@example` for providing example code or related example documentation. - `@usecase` provide a simplified method definition for when the full method @@ -94,19 +93,46 @@ include: ### Member grouping tags + +These tags are well-suited to larger types or packages, with many members. +They allow you to organize the Scaladoc page into distinct sections, with +each one shown separately, in the order that you choose. + +These tags are *not* enabled by default! You must pass the `-groups` +flag to Scaladoc in order to turn them on. Typically, the sbt for this +will look something like: +``` +scalacOptions in (Compile, doc) ++= Seq( + "-groups" +) +``` + +Each section should have a single-word identifier that is used in all of +these tags, shown as `` below. By default, that identifier is +shown as the title of that documentation section, but you can use +`@groupname` to provide a longer title. + +Typically, you should put `@groupprio` (and optionally `@groupname` and +`@groupdesc`) in the Scaladoc for the package/trait/class/object itself, +describing what all the groups are, and their order. Then put `@group` +in the Scaladoc for each member, saying which group it is in. + +Members that do not have a `@group` tag will be listed as "Ungrouped" in +the resulting documentation. + - `@group ` - mark the entity as a member of the `` group. - `@groupname ` - provide an optional name for the group. `` is displayed as the group header -- before the group description. + before the group description. - `@groupdesc ` - add optional descriptive text to display under the group name. Supports multiline - formatted text. -- `@groupprio` - control the order of the group on the page. Defaults to 0. Ungrouped elements have + formatted text. +- `@groupprio ` - control the order of the group on the page. Defaults to 0. Ungrouped elements have an implicit priority of 1000. Use a value between 0 and 999 to set a relative position to other groups. Low values will appear before high values. ### Diagram tags - `@contentDiagram` - use with traits and classes to include a content hierarchy diagram showing included types. - The diagram content can be fine tuned with additional specifiers taken from `hideNodes`, `hideOutgoingImplicits`, + The diagram content can be fine-tuned with additional specifiers taken from `hideNodes`, `hideOutgoingImplicits`, `hideSubclasses`, `hideEdges`, `hideIncomingImplicits`, `hideSuperclasses` and `hideInheritedNode`. `hideDiagram` can be supplied to prevent a diagram from being created if it would be created by default. Packages and objects have content diagrams by default. @@ -122,8 +148,6 @@ include: - `@deprecated` marks the entity as deprecated, **providing both** the replacement implementation that should be used and the version/date at which this entity was deprecated. -- `@migration` like deprecated but provides advanced warning of planned changes - ahead of deprecation. Same fields as `@deprecated`. - `@inheritdoc` take comments from a superclass as defaults if comments are not provided locally. - `@documentable` Expand a type alias and abstract type into a full template page. - TODO: Test the "abstract type" claim - no examples of this in the Scala code base @@ -146,7 +170,7 @@ If a comment is not provided for an entity at the current inheritance level, but is supplied for the overridden entity at a higher level in the inheritance hierarchy, the comment from the super-class will be used. -Likewise if `@param`, `@tparam`, `@return` and other entity tags are omitted +Likewise, if `@param`, `@tparam`, `@return` and other entity tags are omitted but available from a superclass, those comments will be used. ### Explicit @@ -158,7 +182,7 @@ For explicit comment inheritance, use the `@inheritdoc` tag. It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but not necessary most of the time as markup may be used instead. -Some of the standard markup available: +Some types of markup available: `monospace` ''italic text'' @@ -167,8 +191,8 @@ Some of the standard markup available: ^superscript^ ,,subscript,, [[entity link]], e.g. [[scala.collection.Seq]] - [[http://external.link External Link]], - e.g. [[http://scala-lang.org Scala Language Site]] + [[https://external.link External Link]], + e.g. [[https://scala-lang.org Scala Language Site]] ### Other formatting notes @@ -179,10 +203,32 @@ Some of the standard markup available: Indentation is relative to the starting `*` for the comment. - **Headings** are defined with surrounding `=` characters, with more `=` denoting subheadings. E.g. `=Heading=`, `==Sub-Heading==`, etc. +- **Tables** are defined using `|` to separate elements in a row, + as described in the [blog](https://scala-lang.org/blog/2018/10/04/scaladoc-tables.html). - **List blocks** are a sequence of list items with the same style and level, with no interruptions from other block styles. Unordered lists can be bulleted - using `-`, while numbered lists can be denoted using `1.`, `i.`, `I.`, `a.` for - the various numbering styles. + using `-`; numbered lists can be denoted using `1.`, `i.`, `I.`, or `a.` for the + various numbering styles. In both cases, you must have extra space in front, and + more space makes a sub-level. + +The markup for list blocks looks like: + + /** Here is an unordered list: + * + * - First item + * - Second item + * - Sub-item to the second + * - Another sub-item + * - Third item + * + * Here is an ordered list: + * + * 1. First numbered item + * 1. Second numbered item + * i. Sub-item to the second + * i. Another sub-item + * 1. Third item + */ ## General Notes for Writing Scaladoc Comments ## @@ -193,6 +239,63 @@ Some of the standard markup available: - DRY - don't repeat yourself. Resist duplicating the method description in the `@return` tag and other forms of repetitive commenting. +## Resolving Ambiguous Links within Scaladoc Comments +When two methods are indistinguishable from each other lexically, it can cause Scaladoc to +report that there are ambiguous methods. As an example: + +```scala +import scala.collection.mutable.ListBuffer +class bar { + def foo(x: Int): Boolean = ??? + def foo(x: ListBuffer[Int], y: String): Int = ??? +} +``` + +If one references `foo` via `[[foo]]`, then the Scaladoc will complain and offer both +alternatives. Fixing this means elaborating the signature _enough_ so that it becomes unambiguous. +There are a few things to be aware of in general: + +* You must not use a space in the description of the signature: this will cause Scaladoc to + think the link has ended and move onto its description. +* You must fully qualify any types you are using: assume that you have written your program without + any import statements! + +Then, to disambiguate between objects and types, append `$` to designate a term name +and `!` for a type name. Term names include members which are not types, such as `val`, `def`, and +`object` definitions. For example: + - `[[scala.collection.immutable.List!.apply class List's apply method]]` and + - `[[scala.collection.immutable.List$.apply object List's apply method]]` + +When dealing with ambiguous overloads, however, it gets a bit more complex: + +* You must finish the signature, complete or otherwise, with a `*`, which serves as a wildcard + that allows you to cut off the signature when it is umambiguous. +* You must specify the names of the arguments and they must be _exactly_ as written in the + function definition: + - `[[bar.foo(Int)*]]` is **illegal** (no name) + - `[[bar.foo(y:Int)*]]` is **illegal** (wrong name) + - `[[bar.foo(x: Int)*]]` is **illegal** (space! Scaladoc sees this as `bar.foo(x:`) + - `[[bar.foo(x:Int):Boolean]]` is **illegal** (no `*`) + - `[[bar.foo(x:Int)*]]` is **legal** and unambiguous + - `[[bar.foo(x:Int*]]` is **legal**, the `Int` is enough to disambiguate so no closing paren needed +* The enclosing scope (package/class/object etc) of the method must use `.`, but within the arguments + and return type `\.` must be used instead to fully qualify types: + - `[[bar.foo(x:ListBuffer[Int],y:String)*]]` is **illegal** (no qualification on `ListBuffer`) + - `[[bar.foo(x:scala.collection.mutable.ListBuffer[Int],y:String)*]]` is **illegal** (non-escaped dots!) + - `[[bar\.foo(x:scala\.collection\.mutable\.ListBuffer[Int],y:String)*]]` is **illegal** (must not escape dots in the prefix) + - `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int],y:String)*]]` is **legal** + - `[[bar.foo(x:scala\.collection\.mutable\.ListBuffer[Int]*]]` is **legal**, the first argument is + enough to disambiguate. +* When generics are involved, additional square brackets may be used to avoid the + signature accidentally closing the link. Essentially, the number of leading left brackets + determines the number of right brackets required to complete the link: + - `[[baz(x:List[List[A]])*]]` is **illegal** (it is read as `baz(x:List[List[A`) + - `[[[baz(x:List[List[A]])*]]]` is **legal** (the `]]` is no longer a terminator, `]]]` is) + +### Known Limitations + * `#` syntax does not seem to be supported for parameters and return types. + * Spaces cannot be escaped with `\ `, so `implicit` parameters seem not to be supported either. + ## More details on writing Scaladoc Further information on the formatting and style recommendations can be found in diff --git a/_overviews/scaladoc/generate.md b/_overviews/scaladoc/generate.md new file mode 100644 index 0000000000..0fbd38d533 --- /dev/null +++ b/_overviews/scaladoc/generate.md @@ -0,0 +1,50 @@ +--- +layout: multipage-overview +title: Generating Scaladoc +partof: scaladoc +overview-name: Scaladoc +num: 4 +permalink: /overviews/scaladoc/:title.html +--- + +There are two ways to generate API documentation in HTML from your Scala code. Those options are: + +* use sbt to do it, +* use the scaladoc command-line tool. + +## Using sbt + +The easiest and most commonly used way to generate API documentation from your Scala code is with the build tool [sbt](https://www.scala-sbt.org). + +In the sbt shell, generate Scaladoc by running `doc`: + + > doc + [info] Main Scala API documentation to target/scala-2.12/api... + [info] model contains 1 documentable templates + [info] Main Scala API documentation successful. + [success] Total time: 20 s + +The HTML documentation will show up in the respective `target/` directory (or directories for builds with multiple projects) that sbt prints to the console output. + +For more information on using sbt on your system, see the [download instructions](https://www.scala-lang.org/download/) for [getting started with Scala and sbt on the command line]({{site.baseurl}}/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html). + +For additional information about configuring Scaladoc in sbt, see the [Generate API documentation](https://www.scala-sbt.org/1.x/docs/Howto-Scaladoc.html) section of the sbt reference manual. + +## Using scaladoc command + +If you use Scala commands directly to start a console with `scala` or compile with `scalac`, then you should have a `scaladoc` command-line utility, as well. This is a more advanced and less commonly used method of generating Scaladoc. + + $ scaladoc src/main/scala/App.scala + model contains 1 documentable templates + +This will put the HTML in the current directory. This is probably not what you want. It's preferable to output to a subdirectory. To specify a different target directory, use the `-d` command-line option: + + $ scaladoc -d build/ src/main/scala/App.scala + +For more information on the `scaladoc` command and what other command-line options it supports, see the `scaladoc --help`. + +This command is harder to operate with more complex projects containing both multiple Scala source files and library dependencies. This is why using sbt (see above) is easier and better suited for generating Scaladoc. + +The Scaladoc command exists because it preceded the development of sbt, but also because it is useful to the Scala development team with studying bug reports for Scaladoc. + +More information on directly using the Scala commands, like `scaladoc`, is discussed at [your first lines of Scala](https://www.scala-lang.org/documentation/your-first-lines-of-scala.html). diff --git a/_overviews/scaladoc/interface.md b/_overviews/scaladoc/interface.md index f64417c2be..e985de9c3c 100644 --- a/_overviews/scaladoc/interface.md +++ b/_overviews/scaladoc/interface.md @@ -1,62 +1,34 @@ --- layout: multipage-overview title: Using the Scaladoc Interface - -discourse: true - partof: scaladoc overview-name: Scaladoc -num: 3 +num: 2 permalink: /overviews/scaladoc/:title.html +redirect_from: + - /overviews/scaladoc/usage.html --- Many Scala developers, including those with a great deal of experience, are unaware of some of the more powerful features of Scaladoc. -The quickest way to find out about some of these is to check out this -tutorial video: - - - -However, if you are in a hurry and just want a few pointers to things you -may not have known about already, here are a few key points. - ## Scaladoc Features in Brief - The latest Scaladoc for the core Scala libraries can always be found at - [http://www.scala-lang.org/api/current](http://www.scala-lang.org/api/current). -- The search box on the top left narrows the list of classes to those that - match a string search to your typing, use this to home in quickly on the class, - trait or object you are trying to find. -- The letters underneath the search box list all fields, methods and other - tokens found during the creation of the Scaladoc. E.g. if you want to find - where the `.reverse` method you are using is defined, click on **R** in the - list of letters there, and then find in page to locate the `.reverse` method and - the list of implementing classes/traits. -- The small icons on the left of the list of classes denote object `O`, class `C` - and/or trait `T`. Two icons show that this class or trait has a companion as - well. Clicking on the `O` takes you directly to the companion object instead - of the class or trait. -- The same (but larger) icons at the top of the right pane in the title indicate - the same information (i.e. you are looking at the class, trait or object). If - the icon has a "peel over" corner on it, clicking will flip you between the - class/trait and its companion. + [https://www.scala-lang.org/api/current](https://www.scala-lang.org/api/current). - Methods and values may have information folded away that can be accessed by - clicking on the triangle to the left of the definition. + activating that items box. This box is indicated by a blue stripe on the left. - In the title bar, at the very top, is a breadcrumb list of the parent packages and each package is a link to the package object documentation which sometimes holds an overview of the package or API as a whole. -- You can use the Hide and Focus links next to the packages to ignore a package - you no longer want to see in searches, or to concentrate only on that package - for searches. -- By expanding linear supertypes triangle, you can see the linearized trait +- By expanding linear supertypes section, you can see the linearized trait definitions for the current class, trait or object. - Known subclasses lists all subclasses for this entity within the current Scaladoc. - Type hierarchy shows a graphical view of this class related to its super - classes and traits, immediate sub-types, and important related entities. The + classes and traits, immediate subtypes, and important related entities. The graphics themselves are links to the various entities. - The link in the Source section takes you to the online source for the class assuming it is available (and it certainly is for the core libraries and for diff --git a/_overviews/scaladoc/overview.md b/_overviews/scaladoc/overview.md index efe893b729..5c0d2b4f28 100644 --- a/_overviews/scaladoc/overview.md +++ b/_overviews/scaladoc/overview.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Overview - -discourse: true - partof: scaladoc overview-name: Scaladoc @@ -17,18 +14,8 @@ system that lives in the comments of Scala source code and which generates documentation related to the code structure within which it is written. It is based on other comment based documentation systems like Javadoc. -There are two flavors of Scaladoc documentation: +There are three aspects of Scaladoc documentation: - **[Using the Scaladoc interface]({{ site.baseurl }}/overviews/scaladoc/interface.html)** – how to navigate and use generated Scaladoc documentation to learn more about a library. - - **[Generating documentation for your library with Scaladoc]({{ site.baseurl }}/overviews/scaladoc/for-library-authors.html)** – how to use Scaladoc to generate documentation for your library. - -### Contributing to Scaladoc - -If you are interested in contributing to the API documentation of the Scala -standard library (the documentation generated by Scaladoc), please read the -[Scaladoc for Library Authors]({{ site.baseurl }}/overviews/scaladoc/basics.html) first. - -If you'd like to contribute to the actual Scaladoc documentation generation -tool itself, then please see the -[Hacker Set Up Guide](http://scala-lang.org/contribute/hacker-guide.html#2_set_up) -which covers the steps and workflow necessary work on the Scaladoc tool. + - **[Scaladoc for Library Authors]({{ site.baseurl }}/overviews/scaladoc/for-library-authors.html)** – how to add Scaladoc comments to generate documentation for your library. + - **[Generating documentation for your library with Scaladoc]({{ site.baseurl }}/overviews/scaladoc/generate.html)** – how to use Scaladoc to generate documentation for your library. diff --git a/_overviews/scaladoc/usage.md b/_overviews/scaladoc/usage.md deleted file mode 100644 index e1efd956f5..0000000000 --- a/_overviews/scaladoc/usage.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-no-masthead -sitemap: false -permalink: /overviews/scaladoc/usage.html -redirect_to: /overviews/scaladoc/interface.html ---- diff --git a/_overviews/toolkit/OrderedListOfMdFiles b/_overviews/toolkit/OrderedListOfMdFiles new file mode 100644 index 0000000000..b2790bd58a --- /dev/null +++ b/_overviews/toolkit/OrderedListOfMdFiles @@ -0,0 +1,36 @@ +introduction.md +testing-intro.md +testing-suite.md +testing-run.md +testing-run-only.md +testing-exceptions.md +testing-asynchronous.md +testing-resources.md +testing-what-else.md +os-intro.md +os-read-directory.md +os-read-file.md +os-write-file.md +os-run-process.md +os-what-else.md +json-intro.md +json-parse.md +json-modify.md +json-deserialize.md +json-serialize.md +json-files.md +json-what-else.md +http-client-intro.md +http-client-request.md +http-client-uris.md +http-client-request-body.md +http-client-json.md +http-client-upload-file.md +http-client-what-else.md +web-server-intro.md +web-server-static.md +web-server-dynamic.md +web-server-query-parameters.md +web-server-input.md +web-server-websockets.md +web-server-cookies-and-decorators.md diff --git a/_overviews/toolkit/http-client-intro.md b/_overviews/toolkit/http-client-intro.md new file mode 100644 index 0000000000..7e8405f637 --- /dev/null +++ b/_overviews/toolkit/http-client-intro.md @@ -0,0 +1,21 @@ +--- +title: Sending HTTP requests with sttp +type: chapter +description: The introduction of the sttp library +num: 23 +languages: [ru] +previous-page: json-what-else +next-page: http-client-request +--- + +sttp is a popular and feature-rich library for making HTTP requests to web servers. + +It provides both a synchronous API and an asynchronous `Future`-based API. It also supports WebSockets. + +Extensions are available that add capabilities such as streaming, logging, telemetry, and serialization. + +sttp offers the same APIs on all platforms (JVM, Scala.js, and Scala Native). + +sttp is a good choice for small synchronous scripts as well as large-scale, highly concurrent, asynchronous applications. + +{% include markdown.html path="_markdown/install-sttp.md" %} diff --git a/_overviews/toolkit/http-client-json.md b/_overviews/toolkit/http-client-json.md new file mode 100644 index 0000000000..731c0cf0ff --- /dev/null +++ b/_overviews/toolkit/http-client-json.md @@ -0,0 +1,128 @@ +--- +title: How to send and receive JSON? +type: section +description: How to send JSON in a request and to parse JSON from the response. +num: 27 +previous-page: http-client-request-body +next-page: http-client-upload-file +--- + +{% include markdown.html path="_markdown/install-sttp.md" %} + +## HTTP and JSON + +JSON is a common format for HTTP request and response bodies. + +In the examples below, we use the [GitHub REST API](https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28). +You will need a secret [GitHub authentication token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to run the programs. +Do not share your token with anyone. + +## Sending and receiving JSON + +To send a JSON request and parse a JSON response we use sttp in combination with uJson. + +### Sending JSON + +To send JSON, you can construct a `uJson.Value` and write it as a string in the body of the request. + +In the following example we use [GitHub users endpoint](https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28) to update the profile of the authenticated user. +We provide the new location and bio of the profile in a JSON object. + +{% tabs 'json' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:compile-only +import sttp.client4.quick._ + +val json = ujson.Obj( + "location" -> "hometown", + "bio" -> "Scala programmer" +) + +val response = quickRequest + .patch(uri"https://api.github.com/user") + .auth.bearer(sys.env("GITHUB_TOKEN")) + .header("Content-Type", "application/json") + .body(ujson.write(json)) + .send() + +println(response.code) +// prints: 200 + +println(response.body) +// prints the full updated profile in JSON +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* + +val json = ujson.Obj( + "location" -> "hometown", + "bio" -> "Scala programmer" +) + +val response = quickRequest + .patch(uri"https://api.github.com/user") + .auth.bearer(sys.env("GITHUB_TOKEN")) + .header("Content-Type", "application/json") + .body(ujson.write(json)) + .send() + +println(response.code) +// prints: 200 + +println(response.body) +// prints the full updated profile in JSON +``` +{% endtab %} +{% endtabs %} + +Before running the program, set the `GITHUB_TOKEN` environment variable. +After running it, you should see your new bio and location on your GitHub profile. + +### Parsing JSON from the response + +To parse JSON from the response of a request, you can use `ujson.read`. + +Again we use the GitHub user endpoint, this time to get the authenticated user. + +{% tabs 'json-2' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:compile-only +import sttp.client4.quick._ + +val response = quickRequest + .get(uri"https://api.github.com/user") + .auth.bearer(sys.env("GITHUB_TOKEN")) + .send() + +val json = ujson.read(response.body) + +println(json("login").str) +// prints your login +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* + +val response = quickRequest + .get(uri"https://api.github.com/user") + .auth.bearer(sys.env("GITHUB_TOKEN")) + .send() + +val json = ujson.read(response.body) + +println(json("login").str) +// prints your login +``` +{% endtab %} +{% endtabs %} + +Before running the program, set the `GITHUB_TOKEN` environment variable. +Running the program should print your own login. + +## Sending and receiving Scala objects using JSON + +Alternatively, you can use uPickle to send or receive Scala objects using JSON. +Read the following to learn [*How to serialize an object to JSON*](/toolkit/json-serialize.html) and [*How to deserialize JSON to an object*](/toolkit/json-deserialize.html). diff --git a/_overviews/toolkit/http-client-request-body.md b/_overviews/toolkit/http-client-request-body.md new file mode 100644 index 0000000000..b54357e1cb --- /dev/null +++ b/_overviews/toolkit/http-client-request-body.md @@ -0,0 +1,61 @@ +--- +title: How to send a request with a body? +type: section +description: Sending a string body with sttp +num: 26 +previous-page: http-client-uris +next-page: http-client-json +--- + +{% include markdown.html path="_markdown/install-sttp.md" %} + +## Sending a request with a string body + +To send a POST request with a string body, you can chain `post` and `body` on a `quickRequest`: +{% tabs 'body' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import sttp.client4.quick._ + +val response = quickRequest + .post(uri"https://example.com/") + .body("Lorem ipsum") + .send() + +println(response.code) +// prints: 200 +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* + +val response = quickRequest + .post(uri"https://example.com/") + .body("Lorem ipsum") + .send() + +println(response.code) +// prints: 200 +``` +{% endtab %} +{% endtabs %} + +In a request with string body, sttp adds the `Content-Type: text/plain; charset=utf-8` header and computes the `Content-Length` header. + +## Binary data + +The `body` method can also take a `Array[Byte]`, a `ByteBuffer` or an `InputStream`. + +{% tabs 'binarydata' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val bytes: Array[Byte] = "john".getBytes +val request = quickRequest.post(uri"https://example.com/").body(bytes) +``` +{% endtab %} +{% endtabs %} + +The binary body of a request is sent with `Content-Type: application/octet-stream`. + +Learn more in the [sttp documentation chapter about request bodies](https://sttp.softwaremill.com/en/latest/requests/body.html). diff --git a/_overviews/toolkit/http-client-request.md b/_overviews/toolkit/http-client-request.md new file mode 100644 index 0000000000..3a63e29c45 --- /dev/null +++ b/_overviews/toolkit/http-client-request.md @@ -0,0 +1,123 @@ +--- +title: How to send a request? +type: section +description: Sending a simple HTTP request with sttp. +num: 24 +previous-page: http-client-intro +next-page: http-client-uris +--- + +{% include markdown.html path="_markdown/install-sttp.md" %} + +## Sending an HTTP request + +The simplest way to send a request with sttp is `quickRequest`. + +You can define a GET request with `.get` and send it with `.send`. + +{% tabs 'request' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import sttp.client4.quick._ +import sttp.client4.Response + +val response: Response[String] = quickRequest + .get(uri"https://httpbin.org/get") + .send() + +println(response.code) +// prints: 200 + +println(response.body) +// prints some JSON string +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* +import sttp.client4.Response + +val response: Response[String] = quickRequest + .get(uri"https://httpbin.org/get") + .send() + +println(response.code) +// prints: 200 + +println(response.body) +// prints some JSON string +``` +{% endtab %} +{% endtabs %} + +A `Response[String]` contains a status code and a string body. + +## The request definition + +### The HTTP method and URI + +To specify the HTTP method and URI of a `quickRequest`, you can use `get`, `post`, `put`, or `delete`. + +To construct a URI you can use the `uri` interpolator, for e.g. `uri"https://example.com"`. +To learn more about that, see [*How to construct URIs and query parameters?*](/toolkit/http-client-uris). + +### The headers + +By default, the `quickRequest` contains the "Accept-Encoding" and the "deflate" headers. +To add more headers, you can call one of the `header` or `headers` overloads: + +{% tabs 'headers' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:reset +import sttp.client4.quick._ + +val request = quickRequest + .get(uri"https://example.com") + .header("Origin", "https://scala-lang.org") + +println(request.headers) +// prints: Vector(Accept-Encoding: gzip, deflate, Origin: https://scala-lang.org) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* + +val request = quickRequest + .get(uri"https://example.com") + .header("Origin", "https://scala-lang.org") + +println(request.headers) +// prints: Vector(Accept-Encoding: gzip, deflate, Origin: https://scala-lang.org) +``` +{% endtab %} +{% endtabs %} + +sttp can also add "Content-Type" and "Content-Length" automatically if the request contains a body. + +## Authentication + +If you need authentication to access a resource, you can use one of the `auth.basic`, `auth.basicToken`, `auth.bearer` or `auth.digest` methods. + +{% tabs 'auth' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:reset +import sttp.client4.quick._ + +// a request with a authentication +val request = quickRequest + .get(uri"https://example.com") + .auth.basic(user = "user", password = "***") +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* + +// a request with a authentication +val request = quickRequest + .get(uri"https://example.com") + .auth.basic(user = "user", password = "***") +``` +{% endtab %} +{% endtabs %} diff --git a/_overviews/toolkit/http-client-upload-file.md b/_overviews/toolkit/http-client-upload-file.md new file mode 100644 index 0000000000..a67af28fbd --- /dev/null +++ b/_overviews/toolkit/http-client-upload-file.md @@ -0,0 +1,80 @@ +--- +title: How to upload a file over HTTP? +type: section +description: Uploading a file over HTTP with sttp. +num: 28 +previous-page: http-client-json +next-page: http-client-what-else +--- + +{% include markdown.html path="_markdown/install-sttp.md" %} + +## Uploading a file + +To upload a file, you can put a Java `Path` in the body of a request. + +You can get a `Path` directly using `Paths.get("path/to/file")` or by converting an OS-Lib path to a Java path with `toNIO`. + +{% tabs 'file' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:compile-only +import sttp.client4.quick._ + +val file: java.nio.file.Path = (os.pwd / "image.png").toNIO +val response = quickRequest.post(uri"https://example.com/").body(file).send() + +println(response.code) +// prints: 200 +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* + +val file: java.nio.file.Path = (os.pwd / "image.png").toNIO +val response = quickRequest.post(uri"https://example.com/").body(file).send() + +println(response.code) +// prints: 200 +``` +{% endtab %} +{% endtabs %} + +## Multi-part requests + +If the web server can receive multiple files at once, you can use a multipart body, as follows: + +{% tabs 'multipart' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import sttp.client4.quick._ + +val file1 = (os.pwd / "avatar1.png").toNIO +val file2 = (os.pwd / "avatar2.png").toNIO +val response = quickRequest + .post(uri"https://example.com/") + .multipartBody( + multipartFile("avatar1.png", file1), + multipartFile("avatar2.png", file2) + ) + .send() +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* + +val file1 = (os.pwd / "avatar1.png").toNIO +val file2 = (os.pwd / "avatar2.png").toNIO +val response = quickRequest + .post(uri"https://example.com/") + .multipartBody( + multipartFile("avatar1.png", file1), + multipartFile("avatar2.png", file2) + ) + .send() +``` +{% endtab %} +{% endtabs %} + +Learn more about multipart requests in the [sttp documention](https://sttp.softwaremill.com/en/latest/requests/multipart.html). diff --git a/_overviews/toolkit/http-client-uris.md b/_overviews/toolkit/http-client-uris.md new file mode 100644 index 0000000000..bfb9beb332 --- /dev/null +++ b/_overviews/toolkit/http-client-uris.md @@ -0,0 +1,128 @@ +--- +title: How to construct URIs and query parameters? +type: section +description: Using interpolation to construct URIs +num: 25 +previous-page: http-client-request +next-page: http-client-request-body +--- + +{% include markdown.html path="_markdown/install-sttp.md" %} + +## The `uri` interpolator + +`uri` is a custom [string interpolator](/overviews/core/string-interpolation.html) that allows you to create valid web addresses, also called URIs. For example, you can write `uri"https://example.com/"`. + +You can insert any variable or expression in your URI with the usual `$` or `${}` syntax. +For instance `uri"https://example.com/$name"`, interpolates the value of the variable `name` into an URI. +If `name` contains `"peter"`, the result is `https://example.com/peter`. + +`uri` escapes special characters automatically, as seen in this example: + +{% tabs 'uri' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import sttp.client4.quick._ +import sttp.model.Uri + +val book = "programming in scala" +val bookUri: Uri = uri"https://example.com/books/$book" + +println(bookUri) +// prints: https://example.com/books/programming%20in%20scala +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import sttp.client4.quick.* +import sttp.model.Uri + +val book = "programming in scala" +val bookUri: Uri = uri"https://example.com/books/$book" + +println(bookUri) +// prints: https://example.com/books/programming%20in%20scala +``` +{% endtab %} +{% endtabs %} + +## Query parameters + +A query parameter is a key-value pair that is appended to the end of a URI in an HTTP request to specify additional details about the request. +The web server can use those parameters to compute the appropriate response. + +For example, consider the following URL: + +``` +https://example.com/search?q=scala&limit=10&page=1 +``` + +It contains three query parameters: `q=scala`, `limit=10` and `page=1`. + +### Using a map of query parameters + +The `uri` interpolator can interpolate a `Map[String, String]` as query parameters: + +{% tabs 'queryparams' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val queryParams = Map( + "q" -> "scala", + "limit" -> "10", + "page" -> "1" +) +val uriWithQueryParams = uri"https://example.com/search?$queryParams" +println(uriWithQueryParams) +// prints: https://example.com/search?q=scala&limit=10&page=1 +``` +{% endtab %} +{% endtabs %} + +For safety, special characters in the parameters are automatically escaped by the interpolator. + +## Using an optional query parameter + +A query parameter might be optional. +The `uri` interpolator can interpolate `Option`s: + +{% tabs 'optional' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +def getUri(limit: Option[Int]): Uri = + uri"https://example.com/all?limit=$limit" + +println(getUri(Some(10))) +// prints: https://example.com/all?limit=100 + +println(getUri(None)) +// prints: https://example.com/all +``` +{% endtab %} +{% endtabs %} + +Notice that the query parameter disappears entirely when `limit` is `None`. + +## Using a sequence as values of a single query parameter + +A query parameter can be repeated in a URI to represent a list of values. +For example, the `version` parameter in `?version=1.0.0&version=1.0.1&version=1.1.0` contains 3 values: `1.0.0`, `1.0.1` and `1.1.0`. + +To build such query parameter in a URI, you can interpolate a `Seq` (or `List`, `Array`, etc) in a `uri"..."`. + +{% tabs 'seq' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:nest +def getUri(versions: Seq[String]): Uri = + uri"https://example.com/scala?version=$versions" + +println(getUri(Seq("3.2.2"))) +// prints: https://example.com/scala?version=3.2.2 + +println(getUri(Seq("2.13.8", "2.13.9", "2.13.10"))) +// prints: https://example.com/scala?version=2.13.8&version=2.13.9&version=2.13.10 + +println(getUri(Seq.empty)) +// prints: https://example.com/scala +``` +{% endtab %} +{% endtabs %} diff --git a/_overviews/toolkit/http-client-what-else.md b/_overviews/toolkit/http-client-what-else.md new file mode 100644 index 0000000000..c467c7687a --- /dev/null +++ b/_overviews/toolkit/http-client-what-else.md @@ -0,0 +1,112 @@ +--- +title: What else can sttp do? +type: section +description: An incomplete list of features of sttp +num: 29 +previous-page: http-client-upload-file +next-page: web-server-intro +--- + +{% include markdown.html path="_markdown/install-upickle.md" %} + +## Asynchronous requests + +To send a request asynchronously you can use a `DefaultFutureBackend`: + +{% tabs 'async' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import scala.concurrent.Future +import sttp.client4._ + +val asyncBackend = DefaultFutureBackend() +val response: Future[Response[String]] = quickRequest + .get(uri"https://example.com") + .send(asyncBackend) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import scala.concurrent.Future +import sttp.client4.* + +val asyncBackend = DefaultFutureBackend() +val response: Future[Response[String]] = quickRequest + .get(uri"https://example.com") + .send(asyncBackend) +``` +{% endtab %} +{% endtabs %} + +You can learn more about `Future`-based backends in the [sttp documentation](https://sttp.softwaremill.com/en/latest/backends/future.html). + +sttp supports other asynchronous wrappers such as Monix `Task`s, cats-effect `Effect`s, ZIO's `ZIO` type, and more. +You can see the full list of supported backends [here](https://sttp.softwaremill.com/en/latest/backends/summary.html). + +## Websockets + +You can use a `DefaultFutureBackend` to open a websocket, as follows. + +{% tabs 'ws' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:reset +import scala.concurrent.duration.Duration +import scala.concurrent.{Await, Future} +import scala.concurrent.ExecutionContext.Implicits.global + +import sttp.client4._ +import sttp.ws.WebSocket + +val asyncBackend = DefaultFutureBackend() + +def useWebSocket(ws: WebSocket[Future]): Future[Unit] = + for { + _ <- ws.sendText("Hello") + text <- ws.receiveText() + } yield { + println(text) + } + +val response = quickRequest + .get(uri"wss://ws.postman-echo.com/raw") + .response(asWebSocketAlways(useWebSocket)) + .send(asyncBackend) + +Await.result(response, Duration.Inf) +// prints: Hello +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import scala.concurrent.duration.Duration +import scala.concurrent.{Await, Future} +import scala.concurrent.ExecutionContext.Implicits.global + +import sttp.client4.* +import sttp.ws.WebSocket + +val asyncBackend = DefaultFutureBackend() + +def useWebSocket(ws: WebSocket[Future]): Future[Unit] = + for + _ <- ws.sendText("Hello") + text <- ws.receiveText() + yield + println(text) + +val response = quickRequest + .get(uri"wss://ws.postman-echo.com/raw") + .response(asWebSocketAlways(useWebSocket)) + .send(asyncBackend) + +Await.result(response, Duration.Inf) +// prints: Hello +``` +{% endtab %} +{% endtabs %} + +Learn more about WebSockets in [sttp documentation](https://sttp.softwaremill.com/en/latest/other/websockets.html). + +## More features + +You can discover many more features such as streaming, logging, timeouts, and more in [sttp documentation](https://sttp.softwaremill.com/en/latest/quickstart.html#). diff --git a/_overviews/toolkit/introduction.md b/_overviews/toolkit/introduction.md new file mode 100644 index 0000000000..4e042e3575 --- /dev/null +++ b/_overviews/toolkit/introduction.md @@ -0,0 +1,82 @@ +--- +title: Introduction +type: chapter +description: Introducing the Scala Toolkit tutorials +num: 1 +languages: [ru] +previous-page: +next-page: testing-intro +toolkit-index: + - title: Tests + description: Testing code with MUnit. + icon: "fa fa-vial-circle-check" + link: /toolkit/testing-intro.html + - title: Files and Processes + description: Writing files and running processes with OS-Lib. + icon: "fa fa-folder-open" + link: /toolkit/os-intro.html + - title: JSON + description: Parsing JSON and serializing objects to JSON with uPickle. + icon: "fa fa-file-code" + link: /toolkit/json-intro.html + - title: HTTP Requests + description: Sending HTTP requests and uploading files with sttp. + icon: "fa fa-globe" + link: /toolkit/http-client-intro.html + - title: Web servers + description: Building web servers with Cask. + icon: "fa fa-server" + link: /toolkit/web-server-intro.html +--- + +## What is the Scala Toolkit? + +The Scala Toolkit is a set of libraries designed to effectively perform common programming tasks. It includes tools for working with files and processes, parsing JSON, sending HTTP requests, and unit testing. + +The Toolkit supports: +* Scala 3 and Scala 2 +* JVM, Scala.js, and Scala Native + +Use cases for the Toolkit include: + +- short-lived programs running on the JVM, to scrape a website, to collect and transform data, or to fetch and process some files, +- frontend scripts that run on the browser and power your websites, +- command-line tools packaged as native binaries for instant startup + +{% include inner-documentation-sections.html links=page.toolkit-index %} + +## What are these tutorials? + +This series of tutorials focuses on short code examples, to help you get started quickly. + +If you need more in-depth information, the tutorials include links to further documentation for all of the libraries in the toolkit. + +## How to run the code? + +You can follow the tutorials regardless of how you choose to run your +Scala code. The tutorials focus on the code itself, not on the process +of running it. + +Ways to run Scala code include: +* in your **browser** with [Scastie](https://scastie.scala-lang.org) + * pros: zero installation, online sharing + * cons: single-file only, online-only +* interactively in the Scala **REPL** (Read/Eval/Print Loop) + * pros: interactive exploration in the terminal + * cons: doesn't save your code anywhere +* interactively in a **worksheet** in your IDE such as [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) or [Metals](http://scalameta.org/metals/) + * pros: interactive exploration in a GUI + * cons: requires worksheet environment to run +* in **scripts**, using [Scala CLI](https://scala-cli.virtuslab.com) + * pros: terminal-based workflow with little setup + * cons: may not be suitable for large projects +* using a **build tool** (such as [sbt](https://www.scala-sbt.org) or [mill](https://com-lihaoyi.github.io/mill/)) + * pros: terminal-based workflow for projects of any size + * cons: requires some additional setup and learning +* using an **IDE** such as [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) or [Metals](http://scalameta.org/metals/) + * pros: GUI based workflow for projects of any size + * cons: requires some additional setup and learning + +These choices, with their pros and cons, are common to most programing +languages. +Feel free to use whichever option you're most comfortable with. diff --git a/_overviews/toolkit/json-deserialize.md b/_overviews/toolkit/json-deserialize.md new file mode 100644 index 0000000000..23fd6391d1 --- /dev/null +++ b/_overviews/toolkit/json-deserialize.md @@ -0,0 +1,121 @@ +--- +title: How to deserialize JSON to an object? +type: section +description: Parsing JSON to a custom data type +num: 19 +previous-page: json-modify +next-page: json-serialize +--- + +{% include markdown.html path="_markdown/install-upickle.md" %} + +## Parsing vs. deserialization + +Parsing with uJson only accepts valid JSON, but it does not validate that the names and types of fields are as expected. + +Deserialization, on the other hand, transforms a JSON string to some user-specified Scala data type, if required fields are present and have the correct types. + +In this tutorial, we show how to deserialize to a `Map` and also to a custom `case class`. + +## Deserializing JSON to a `Map` + +For a type `T`, uPickle can deserialize JSON to a `Map[String, T]`, checking that all fields conform to `T`. + +We can for instance, deserialize to a `Map[String, List[Int]]`: + +{% tabs 'parsemap' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val json = """{"primes": [2, 3, 5], "evens": [2, 4, 6]} """ +val map: Map[String, List[Int]] = + upickle.default.read[Map[String, List[Int]]](json) + +println(map("primes")) +// prints: List(2, 3, 5) +``` +{% endtab %} +{% endtabs %} + +If a value is the wrong type, uPickle throws a `upickle.core.AbortException`. + +{% tabs 'parsemap-error' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:reset:crash +val json = """{"name": "Peter"} """ +upickle.default.read[Map[String, List[Int]]](json) +// throws: upickle.core.AbortException: expected sequence got string at index 9 +``` +{% endtab %} +{% endtabs %} + +### Deserializing JSON to a custom data type + +In Scala, you can use a `case class` to define your own data type. +For example, to represent a pet owner, you might: +```scala mdoc:reset +case class PetOwner(name: String, pets: List[String]) +``` + +To read a `PetOwner` from JSON, we must provide a `ReadWriter[PetOwner]`. +uPickle can do that automatically: + +{% tabs 'given' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import upickle.default._ + +implicit val ownerRw: ReadWriter[PetOwner] = macroRW[PetOwner] +``` +Some explanations: +- An `implicit val` is a value that can be automatically provided as an argument to a method or function call, without having to explicitly pass it. +- `macroRW` is a method provided by uPickle that can generate a instances of `ReadWriter` for case classes, using the information about its fields. +{% endtab %} +{% tab 'Scala 3' %} +```scala +import upickle.default.* + +case class PetOwner(name: String, pets: List[String]) + derives ReadWriter +``` +The `derives` keyword is used to automatically generate given instances. +Using the compiler's knowledge of the fields in `PetOwner`, it generates a `ReadWriter[PetOwner]`. +{% endtab %} +{% endtabs %} + +This means that you can now read (and write) `PetOwner` objects from JSON with `upickle.default.read(petOwner)`. + +Notice that you do not need to pass the instance of `ReadWriter[PetOwner]` explicitly to the `read` method. But it does, nevertheless, get it from the context, as "given" value. You may find more information about contextual abstractions in the [Scala 3 Book](https://docs.scala-lang.org/scala3/book/ca-contextual-abstractions-intro.html). + +Putting everything together you should get: + +{% tabs 'full' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:reset +import upickle.default._ + +case class PetOwner(name: String, pets: List[String]) +implicit val ownerRw: ReadWriter[PetOwner] = macroRW + +val json = """{"name": "Peter", "pets": ["Toolkitty", "Scaniel"]}""" +val petOwner: PetOwner = read[PetOwner](json) + +val firstPet = petOwner.pets.head +println(s"${petOwner.name} has a pet called $firstPet") +// prints: Peter has a pet called Toolkitty +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import upickle.default.* + +case class PetOwner(name: String, pets: List[String]) derives ReadWriter + +val json = """{"name": "Peter", "pets": ["Toolkitty", "Scaniel"]}""" +val petOwner: PetOwner = read[PetOwner](json) + +val firstPet = petOwner.pets.head +println(s"${petOwner.name} has a pet called $firstPet") +// prints: Peter has a pet called Toolkitty +``` +{% endtab %} +{% endtabs %} diff --git a/_overviews/toolkit/json-files.md b/_overviews/toolkit/json-files.md new file mode 100644 index 0000000000..53072bb2b5 --- /dev/null +++ b/_overviews/toolkit/json-files.md @@ -0,0 +1,72 @@ +--- +title: How to read and write JSON files? +type: section +description: Reading and writing JSON files using UPickle and OSLib +num: 21 +previous-page: json-serialize +next-page: json-what-else +--- + +{% include markdown.html path="_markdown/install-upickle.md" %} + +## Read and write raw JSON + +To read and write JSON files, you can use uJson and OS-Lib as follows: + +{% tabs 'raw' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:compile-only +// read a JSON file +val json = ujson.read(os.read(os.pwd / "raw.json")) + +// modify the JSON content +json("updated") = "now" + +//write to a new file +os.write(os.pwd / "raw-updated.json", ujson.write(json)) +``` +{% endtab %} +{% endtabs %} + +## Read and write Scala objects using JSON + +To read and write Scala objects to and from JSON files, you can use uPickle and OS-Lib as follows: + +{% tabs 'object' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:compile-only +import upickle.default._ + +case class PetOwner(name: String, pets: List[String]) +implicit val ownerRw: ReadWriter[PetOwner] = macroRW + +// read a PetOwner from a JSON file +val petOwner: PetOwner = read[PetOwner](os.read(os.pwd / "pet-owner.json")) + +// create a new PetOwner +val petOwnerUpdated = petOwner.copy(pets = "Toolkitty" :: petOwner.pets) + +// write to a new file +os.write(os.pwd / "pet-owner-updated.json", write(petOwnerUpdated)) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import upickle.default.* + +case class PetOwner(name: String, pets: List[String]) derives ReadWriter + +// read a PetOwner from a JSON file +val petOwner: PetOwner = read[PetOwner](os.read(os.pwd / "pet-owner.json")) + +// create a new PetOwner +val petOwnerUpdated = petOwner.copy(pets = "Toolkitty" :: petOwner.pets) + +// write to a new file +os.write(os.pwd / "pet-owner-updated.json", write(petOwnerUpdated)) +``` +{% endtab %} +{% endtabs %} + +To serialize and deserialize Scala case classes (or enums) to JSON we need an instance of `ReadWriter`. +To understand how uPickle generates it for you, you can read the [*How to deserialize JSON to an object?*](/toolkit/json-deserialize.html) or the [*How to serialize an object to JSON?*](/toolkit/json-serialize.html) tutorials. diff --git a/_overviews/toolkit/json-intro.md b/_overviews/toolkit/json-intro.md new file mode 100644 index 0000000000..9c5c789b49 --- /dev/null +++ b/_overviews/toolkit/json-intro.md @@ -0,0 +1,17 @@ +--- +title: Handling JSON with uPickle +type: chapter +description: Description of the uPickle library. +num: 16 +languages: [ru] +previous-page: os-what-else +next-page: json-parse +--- + +uPickle is a lightweight serialization library for Scala. + +It includes uJson, a JSON manipulation library that can parse JSON strings, access or mutate their values in memory, and write them back out again. + +uPickle can serialize and deserialize Scala objects directly to and from JSON. It knows how to handle the Scala collections such as `Map` and `Seq`, as well as your own data types, such as `case class`s and Scala 3 `enum`s. + +{% include markdown.html path="_markdown/install-upickle.md" %} diff --git a/_overviews/toolkit/json-modify.md b/_overviews/toolkit/json-modify.md new file mode 100644 index 0000000000..8f1cd63e6d --- /dev/null +++ b/_overviews/toolkit/json-modify.md @@ -0,0 +1,33 @@ +--- +title: How to modify JSON? +type: section +description: Modifying JSON with uPickle. +num: 18 +previous-page: json-parse +next-page: json-deserialize +--- + +{% include markdown.html path="_markdown/install-upickle.md" %} + +`ujson.read` returns a mutable representation of JSON that you can update. Fields and elemnts can be added, modified, or removed. + +First you read the JSON string, then you update it in memory, and finally you write it back out again. + +{% tabs 'modify' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +// Parse the JSON string +val json: ujson.Value = ujson.read("""{"name":"John","pets":["Toolkitty","Scaniel"]}""") + +// Update it +json("name") = "Peter" +json("nickname") = "Pete" +json("pets").arr.remove(1) + +// Write it back to a String +val result: String = ujson.write(json) +println(result) +// prints: {"name":"Peter","pets":["Toolkitty"],"nickname":"Pete"} +``` +{% endtab %} +{% endtabs %} diff --git a/_overviews/toolkit/json-parse.md b/_overviews/toolkit/json-parse.md new file mode 100644 index 0000000000..71b1fab391 --- /dev/null +++ b/_overviews/toolkit/json-parse.md @@ -0,0 +1,82 @@ +--- +title: How to access values inside JSON? +type: section +description: Accessing JSON values using ujson. +num: 17 +previous-page: json-intro +next-page: json-modify +--- + +{% include markdown.html path="_markdown/install-upickle.md" %} + +## Accessing values inside JSON + +To parse a JSON string and access fields inside it, you can use uJson, which is part of uPickle. + +The method `ujson.read` parses a JSON string into memory: +{% tabs 'read' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val jsonString = """{"name": "Peter", "age": 13, "pets": ["Toolkitty", "Scaniel"]}""" +val json: ujson.Value = ujson.read(jsonString) +println(json("name").str) +// prints: Peter +``` +{% endtab %} +{% endtabs %} + +To access the `"name"` field, we do `json("name")` and then call `str` to type it as a string. + +To access the elements by index in a JSON array, + +{% tabs 'array' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val pets: ujson.Value = json("pets") + +val firstPet: String = pets(0).str +val secondPet: String = pets(1).str + +println(s"The pets are $firstPet and $secondPet") +// prints: The pets are Toolkitty and Scaniel +``` +{% endtab %} +{% endtabs %} + +You can traverse the JSON structure as deeply as you want, to extract any nested value. +For instance, `json("field1")(0)("field2").str` is the string value of `field2` in the first element of the array in `field1`. + +## JSON types + +In the previous examples we used `str` to type a JSON value as a string. +Similar methods exist for other types of values, namely: + - `num` for numeric values, returning `Double` + - `bool` for boolean values, returning `Boolean` + - `arr` for arrays, returning a mutable `Buffer[ujson.Value]` + - `obj` for objects, returning a mutable `Map[String, ujson.Value]` + +{% tabs 'typing' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:reset +import scala.collection.mutable + +val jsonString = """{"name": "Peter", "age": 13, "pets": ["Toolkitty", "Scaniel"]}""" +val json = ujson.read(jsonString) + +val person: mutable.Map[String, ujson.Value] = json.obj +val age: Double = person("age").num +val pets: mutable.Buffer[ujson.Value] = person("pets").arr +``` +{% endtab %} +{% endtabs %} + +If a JSON value does not conform to the expected type, uJson throws a `ujson.Value.InvalidData` exception. + +{% tabs 'exception' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:crash +val name: Boolean = person("name").bool +// throws a ujson.Value.InvalidData: Expected ujson.Bool (data: "Peter") +``` +{% endtab %} +{% endtabs %} diff --git a/_overviews/toolkit/json-serialize.md b/_overviews/toolkit/json-serialize.md new file mode 100644 index 0000000000..bd3049def0 --- /dev/null +++ b/_overviews/toolkit/json-serialize.md @@ -0,0 +1,95 @@ +--- +title: How to serialize an object to JSON? +type: section +description: How to write JSON with Scala Toolkit. +num: 20 +previous-page: json-deserialize +next-page: json-files +--- + +{% include markdown.html path="_markdown/install-upickle.md" %} + +## Serializing a Map to JSON + +uPickle can serialize your Scala objects to JSON, so that you can save them in files or send them over the network. + +By default it can serialize primitive types such as `Int` or `String`, as well as standard collections such as `Map` and `List`. + +{% tabs 'array' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val map: Map[String, Int] = + Map("Toolkitty" -> 3, "Scaniel" -> 5) +val jsonString: String = upickle.default.write(map) +println(jsonString) +// prints: {"Toolkitty":3,"Scaniel":5} +``` +{% endtab %} +{% endtabs %} + +## Serializing a custom object to JSON + +In Scala, you can use a `case class` to define your own data type. +For example, to represent a pet owner with the name of its pets, you can +```scala mdoc:reset +case class PetOwner(name: String, pets: List[String]) +``` + +To be able to write a `PetOwner` to JSON we need to provide a `ReadWriter` instance for the case class `PetOwner`. +Luckily, `upickle` is able to fully automate that: + +{% tabs 'given' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import upickle.default._ + +implicit val ownerRw: ReadWriter[PetOwner] = macroRW[PetOwner] +``` +Some explanations: +- An `implicit val` is a value that can be automatically provided as an argument to a method or function call, without having to explicitly pass it. +- `macroRW` is a method provided by uPickle that can generate a instances of `ReadWriter` for case classes, using the information about its fields. +{% endtab %} +{% tab 'Scala 3' %} +```scala +import upickle.default.* + +case class PetOwner(name: String, pets: List[String]) derives ReadWriter +``` +The `derives` keyword is used to automatically generate given instances. +Using the compiler's knowledge of the fields in `PetOwner`, it generates a `ReadWriter[PetOwner]`. +{% endtab %} +{% endtabs %} + +This means that you can now write (and read) `PetOwner` objects to JSON with `upickle.default.write(petOwner)`. + +Notice that you do not need to pass the instance of `ReadWriter[PetOwner]` explicitly to the `write` method. But it does, nevertheless, get it from the context, as "given" value. You may find more information about contextual abstractions in the [Scala 3 Book](https://docs.scala-lang.org/scala3/book/ca-contextual-abstractions-intro.html). + +Putting everything together you should get: + +{% tabs 'full' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import upickle.default._ + +case class PetOwner(name: String, pets: List[String]) +implicit val ownerRw: ReadWriter[PetOwner] = macroRW + +val petOwner = PetOwner("Peter", List("Toolkitty", "Scaniel")) +val json: String = write(petOwner) +println(json) +// prints: {"name":"Peter","pets":["Toolkitty","Scaniel"]}" +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import upickle.default._ + +case class PetOwner(name: String, pets: List[String]) derives ReadWriter + +val petOwner = PetOwner("Peter", List("Toolkitty", "Scaniel")) +val json: String = write(petOwner) +println(json) +// prints: {"name":"Peter","pets":["Toolkitty","Scaniel"]}" +``` +{% endtab %} +{% endtabs %} diff --git a/_overviews/toolkit/json-what-else.md b/_overviews/toolkit/json-what-else.md new file mode 100644 index 0000000000..1f34daffe4 --- /dev/null +++ b/_overviews/toolkit/json-what-else.md @@ -0,0 +1,74 @@ +--- +title: What else can uPickle do? +type: section +description: An incomplete list of features of uPickle +num: 22 +previous-page: json-files +next-page: http-client-intro +--- + +{% include markdown.html path="_markdown/install-upickle.md" %} +## Construct a new JSON structure with uJson + +{% tabs construct%} +{% tab 'Scala 2 and Scala 3' %} +```scala mdoc +val obj: ujson.Value = ujson.Obj( + "library" -> "upickle", + "versions" -> ujson.Arr("1.6.0", "2.0.0", "3.1.0"), + "documentation" -> "https://com-lihaoyi.github.io/upickle/", +) +``` +{% endtab %} +{% endtabs %} + +Learn more about constructing JSON in the [uJson documentation](https://com-lihaoyi.github.io/upickle/#Construction). + +## Defining custom JSON serialization + +You can customize the `ReadWriter` of your data type by mapping the `ujson.Value`, like this: + +{% tabs custom-serializer class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import upickle.default._ + +case class Bar(i: Int, s: String) + +object Bar { + implicit val barReadWriter: ReadWriter[Bar] = readwriter[ujson.Value] + .bimap[Bar]( + x => ujson.Arr(x.s, x.i), + json => new Bar(json(1).num.toInt, json(0).str) + ) +} + +val bar = Bar(5, "bar") +val json = upickle.default.write(bar) +println(json) +// prints: [5, "bar"] +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import upickle.default.* + +case class Bar(i: Int, s: String) + +object Bar: + given ReadWriter[Bar] = readwriter[ujson.Value] + .bimap[Bar]( + x => ujson.Arr(x.s, x.i), + json => new Bar(json(1).num.toInt, json(0).str) + ) + +val bar = Bar(5, "bar") +val json = upickle.default.write(bar) +println(json) +// prints: [5, "bar"] +``` +{% endtab %} +{% endtabs %} + +Learn more about custom JSON serialization in the [uPickle documentation](https://com-lihaoyi.github.io/upickle/#Customization). + diff --git a/_overviews/toolkit/os-intro.md b/_overviews/toolkit/os-intro.md new file mode 100644 index 0000000000..d72387f045 --- /dev/null +++ b/_overviews/toolkit/os-intro.md @@ -0,0 +1,21 @@ +--- +title: Working with files and processes with OS-Lib +type: chapter +description: The introduction of the OS-lib library +num: 10 +languages: [ru] +previous-page: testing-what-else +next-page: os-read-directory +--- + +OS-Lib is a library for manipulating files and processes. It is part of the Scala Toolkit. + +OS-Lib aims to replace the `java.nio.file` and `java.lang.ProcessBuilder` APIs. You should not need to use any underlying Java APIs directly. + +OS-lib also aims to supplant the older `scala.io` and `scala.sys` APIs in the Scala standard library. + +OS-Lib has no dependencies. + +All of OS-Lib is in the `os.*` namespace. + +{% include markdown.html path="_markdown/install-os-lib.md" %} diff --git a/_overviews/toolkit/os-read-directory.md b/_overviews/toolkit/os-read-directory.md new file mode 100644 index 0000000000..b24b664a49 --- /dev/null +++ b/_overviews/toolkit/os-read-directory.md @@ -0,0 +1,59 @@ +--- +title: How to read a directory? +type: section +description: Reading a directory's contents with OS-Lib +num: 11 +previous-page: os-intro +next-page: os-read-file +--- + +{% include markdown.html path="_markdown/install-os-lib.md" %} + +## Paths + +A fundamental data type in OS-Lib is `os.Path`, representing a path +on the filesystem. An `os.Path` is always an absolute path. + +OS-Lib also provides `os.RelPath` (relative paths) and `os.SubPath` (a +relative path which cannot ascend to parent directories). + +Typical starting points for making paths are `os.pwd` (the +current working directory), `os.home` (the current user's home +directory), `os.root` (the root of the filesystem), or +`os.temp.dir()` (a new temporary directory). + +Paths have a `/` method for adding path segments. For example: + +{% tabs 'etc' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val etc: os.Path = os.root / "etc" +``` +{% endtab %} +{% endtabs %} + +## Reading a directory + +`os.list` returns the contents of a directory: + +{% tabs 'list-etc' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val entries: Seq[os.Path] = os.list(os.root / "etc") +``` +{% endtab %} +{% endtabs %} + +Or if we only want subdirectories: + +{% tabs 'subdirs' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val dirs: Seq[os.Path] = os.list(os.root / "etc").filter(os.isDir) +``` +{% endtab %} +{% endtabs %} + +To recursively descend an entire subtree, change `os.list` to +`os.walk`. To process results on the fly rather than reading them all +into memory first, substitute `os.walk.stream`. diff --git a/_overviews/toolkit/os-read-file.md b/_overviews/toolkit/os-read-file.md new file mode 100644 index 0000000000..bc23ca2588 --- /dev/null +++ b/_overviews/toolkit/os-read-file.md @@ -0,0 +1,64 @@ +--- +title: How to read a file? +type: section +description: Reading files from disk with OS-Lib +num: 12 +previous-page: os-read-directory +next-page: os-write-file +--- + +{% include markdown.html path="_markdown/install-os-lib.md" %} + +## Reading a file + +Supposing we have the path to a file: + +{% tabs 'path' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val path: os.Path = os.root / "usr" / "share" / "dict" / "words" +``` +{% endtab %} +{% endtabs %} + +Then we can slurp the entire file into a string with `os.read`: + +{% tabs slurp %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:compile-only +val content: String = os.read(path) +``` +{% endtab %} +{% endtabs %} + +To read the file as line at a time, substitute `os.read.lines`. + +We can find the longest word in the dictionary: + +{% tabs lines %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:compile-only +val lines: Seq[String] = os.read.lines(path) +println(lines.maxBy(_.size)) +// prints: antidisestablishmentarianism +``` +{% endtab %} +{% endtabs %} + +There's also `os.read.lines.stream` if you want to process the lines +on the fly rather than read them all into memory at once. For example, +if we just want to read the first line, the most efficient way is: + +{% tabs lines-stream %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:compile-only +val lineStream: geny.Generator[String] = os.read.lines.stream(path) +val firstLine: String = lineStream.head +println(firstLine) +// prints: A +``` +{% endtab %} +{% endtabs %} + +OS-Lib takes care of closing the file once the generator returned +by `stream` is exhausted. diff --git a/_overviews/toolkit/os-run-process.md b/_overviews/toolkit/os-run-process.md new file mode 100644 index 0000000000..7bbe4ace58 --- /dev/null +++ b/_overviews/toolkit/os-run-process.md @@ -0,0 +1,79 @@ +--- +title: How to run a process? +type: section +description: Starting external subprocesses with OS-Lib +num: 14 +previous-page: os-write-file +next-page: os-what-else +--- + +{% include markdown.html path="_markdown/install-os-lib.md" %} + +## Starting an external process + +To set up a process, use `os.proc`, then to actually start it, +`call()`: + +{% tabs 'touch' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:compile-only +val path: os.Path = os.pwd / "output.txt" +println(os.exists(path)) +// prints: false +val result: os.CommandResult = os.proc("touch", path).call() +println(result.exitCode) +// prints: 0 +println(os.exists(path)) +// prints: true +``` +{% endtab %} +{% endtabs %} + +Note that `proc` accepts both strings and `os.Path`s. + +## Reading the output of a process + +(The particular commands in the following examples might not exist on all +machines.) + +Above we saw that `call()` returned an `os.CommandResult`. We can +access the result's entire output with `out.text()`, or as lines +with `out.lines()`. + +For example, we could use `bc` to do some math for us: + +{% tabs 'bc' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:compile-only +val res: os.CommandResult = os.proc("bc", "-e", "2 + 2").call() +val text: String = res.out.text() +println(text.trim.toInt) +// prints: 4 +``` +{% endtab %} +{% endtabs %} + +Or have `cal` show us a calendar: + +{% tabs 'cal' %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:compile-only +val res: os.CommandResult = os.proc("cal", "-h", "2", "2023").call() +res.out.lines().foreach(println) +// prints: +// February 2023 +// Su Mo Tu We Th Fr Sa +// 1 2 3 4 +// ... +``` +{% endtab %} +{% endtabs %} + +## Customizing the process + +`call()` takes various optional arguments, too many to explain +individually here. For example, you can set the working directory +(`cwd = ...`), set environment variables (`env = ...`), or redirect +input and output (`stdin = ...`, `stdout = ...`, `stderr = ...`). +Find more information about the `call` method on [the README of OS-Lib](https://github.com/com-lihaoyi/os-lib#osproccall). + diff --git a/_overviews/toolkit/os-what-else.md b/_overviews/toolkit/os-what-else.md new file mode 100644 index 0000000000..886db4c81f --- /dev/null +++ b/_overviews/toolkit/os-what-else.md @@ -0,0 +1,19 @@ +--- +title: What else can OS-Lib do? +type: section +description: An incomplete list of features of OS-Lib +num: 15 +previous-page: os-run-process +next-page: json-intro +--- + +{% include markdown.html path="_markdown/install-os-lib.md" %} + +[OS-Lib on GitHub](https://github.com/com-lihaoyi/os-lib) has many additional examples of how to perform common tasks: +- creating, moving, copying, removing files and folders, +- reading filesystem metadata and permissions, +- spawning subprocesses, +- watching changes in folders, +- interoperating with `java.io.File` and `java.nio.Path`. + +See also Chapter 7 of Li Haoyi's book [_Hands-On Scala Programming_](https://www.handsonscala.com). (Li Haoyi is the author of OS-Lib.) diff --git a/_overviews/toolkit/os-write-file.md b/_overviews/toolkit/os-write-file.md new file mode 100644 index 0000000000..2bef6fff0c --- /dev/null +++ b/_overviews/toolkit/os-write-file.md @@ -0,0 +1,54 @@ +--- +title: How to write a file? +type: section +description: Writing files to disk with OS-Lib +num: 13 +previous-page: os-read-file +next-page: os-run-process +--- + +{% include markdown.html path="_markdown/install-os-lib.md" %} + +## Writing a file all at once + +`os.write` writes the supplied string to a new file: + +{% tabs write %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +val path: os.Path = os.temp.dir() / "output.txt" +os.write(path, "hello\nthere\n") +println(os.read.lines(path).size) +// prints: 2 +``` +{% endtab %} +{% endtabs %} + +## Overwriting or appending + +`os.write` throws an exception if the file already exists: + +{% tabs already-exists %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:crash +os.write(path, "this will fail") +// this exception is thrown: +// java.nio.file.FileAlreadyExistsException +``` +{% endtab %} +{% endtabs %} + +To avoid this, use `os.write.over` to replace the existing +contents. + +You can also use `os.write.append` to add more to the end: + +{% tabs append %} +{% tab 'Scala 2 and 3' %} +```scala mdoc +os.write.append(path, "two more\nlines\n") +println(os.read.lines(path).size) +// prints: 4 +``` +{% endtab %} +{% endtabs %} diff --git a/_overviews/toolkit/testing-asynchronous.md b/_overviews/toolkit/testing-asynchronous.md new file mode 100644 index 0000000000..1311af6b9b --- /dev/null +++ b/_overviews/toolkit/testing-asynchronous.md @@ -0,0 +1,88 @@ +--- +title: How to write asynchronous tests? +type: section +description: Writing asynchronous tests using MUnit +num: 7 +previous-page: testing-exceptions +next-page: testing-resources +--- + +{% include markdown.html path="_markdown/install-munit.md" %} + +## Asynchronous tests + +In Scala, it's common for an *asynchronous* method to return a `Future`. +MUnit offers special support for `Future`s. + +For example, consider an asynchronous variant of a `square` method: + +{% tabs 'async-1' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import scala.concurrent.{ExecutionContext, Future} + +object AsyncMathLib { + def square(x: Int)(implicit ec: ExecutionContext): Future[Int] = + Future(x * x) +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import scala.concurrent.{ExecutionContext, Future} + +object AsyncMathLib: + def square(x: Int)(using ExecutionContext): Future[Int] = + Future(x * x) +``` +{% endtab %} +{% endtabs %} + +A test itself can return a `Future[Unit]`. +MUnit will wait behind the scenes for the resulting `Future` to complete, failing the test if any assertion fails. + +You can therefore write the test as follows: + +{% tabs 'async-3' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +// Import the global execution context, required to call async methods +import scala.concurrent.ExecutionContext.Implicits.global + +class AsyncMathLibTests extends munit.FunSuite { + test("square") { + for { + squareOf3 <- AsyncMathLib.square(3) + squareOfMinus4 <- AsyncMathLib.square(-4) + } yield { + assertEquals(squareOf3, 9) + assertEquals(squareOfMinus4, 16) + } + } +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +// Import the global execution context, required to call async methods +import scala.concurrent.ExecutionContext.Implicits.global + +class AsyncMathLibTests extends munit.FunSuite: + test("square") { + for + squareOf3 <- AsyncMathLib.square(3) + squareOfMinus4 <- AsyncMathLib.square(-4) + yield + assertEquals(squareOf3, 9) + assertEquals(squareOfMinus4, 16) + } +``` +{% endtab %} +{% endtabs %} + +The test first asynchronously computes `square(3)` and `square(-4)`. +Once both computations are completed, and if they are both successful, it proceeds with the calls to `assertEquals`. +If any of the assertion fails, the resulting `Future[Unit]` fails, and MUnit will cause the test to fail. + +You may read more about asynchronous tests [in the MUnit documentation](https://scalameta.org/munit/docs/tests.html#declare-async-test). +It shows how to use other asynchronous types besides `Future`. diff --git a/_overviews/toolkit/testing-exceptions.md b/_overviews/toolkit/testing-exceptions.md new file mode 100644 index 0000000000..f2a880d68f --- /dev/null +++ b/_overviews/toolkit/testing-exceptions.md @@ -0,0 +1,67 @@ +--- +title: How to test exceptions? +type: section +description: Describe the intercept assertion +num: 6 +previous-page: testing-run-only +next-page: testing-asynchronous +--- + +{% include markdown.html path="_markdown/install-munit.md" %} + +## Intercepting an exception + +In a test, you can use `intercept` to check that your code throws an exception. + +{% tabs 'intercept-1' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +import java.nio.file.NoSuchFileException + +class FileTests extends munit.FunSuite { + test("read missing file") { + val missingFile = os.pwd / "missing.txt" + + intercept[NoSuchFileException] { + os.read(missingFile) + } + } +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import java.nio.file.NoSuchFileException + +class FileTests extends munit.FunSuite: + test("read missing file") { + val missingFile = os.pwd / "missing.txt" + intercept[NoSuchFileException] { + // the code that should throw an exception + os.read(missingFile) + } + } +``` +{% endtab %} +{% endtabs %} + +The type parameter of the `intercept` assertion is the expected exception. +Here it is `NoSuchFileException`. +The body of the `intercept` assertion contains the code that should throw the exception. + +The test passes if the code throws the expected exception and it fails otherwise. + +The `intercept` method returns the exception that is thrown. +You can check more assertions on it. + +{% tabs 'intercept-2' %} +{% tab 'Scala 2 and 3' %} +```scala +val exception = intercept[NoSuchFileException](os.read(missingFile)) +assert(clue(exception.getMessage).contains("missing.txt")) +``` +{% endtab %} +{% endtabs %} + +You can also use the more concise `interceptMessage` method to test the exception and its message in a single assertion. +Learn more about it in the [MUnit documentation](https://scalameta.org/munit/docs/assertions.html#interceptmessage). diff --git a/_overviews/toolkit/testing-intro.md b/_overviews/toolkit/testing-intro.md new file mode 100644 index 0000000000..4397be63b3 --- /dev/null +++ b/_overviews/toolkit/testing-intro.md @@ -0,0 +1,22 @@ +--- +title: Testing with MUnit +type: chapter +description: The introduction of the MUnit library +num: 2 +languages: [ru] +previous-page: introduction +next-page: testing-suite +--- + +MUnit is a lightweight testing library. It provides a single style for writing tests, a style that can be learned quickly. + +Despite its simplicity, MUnit has useful features such as: +- assertions to verify the behavior of the program +- fixtures to ensure that the tests have access to all the necessary resources +- asynchronous support, for testing concurrent and distributed applications. + +MUnit produces actionable error reports, with diff and source location, to help you quickly understand failures. + +Testing is essential for any software development process because it helps catch bugs early, improves code quality and facilitates collaboration. + +{% include markdown.html path="_markdown/install-munit.md" %} diff --git a/_overviews/toolkit/testing-resources.md b/_overviews/toolkit/testing-resources.md new file mode 100644 index 0000000000..50733256e7 --- /dev/null +++ b/_overviews/toolkit/testing-resources.md @@ -0,0 +1,102 @@ +--- +title: How to manage the resources of a test? +type: section +description: Describe the functional fixtures +num: 8 +previous-page: testing-asynchronous +next-page: testing-what-else +--- + +{% include markdown.html path="_markdown/install-munit.md" %} + +## `FunFixture` + +In MUnit, we use functional fixtures to manage resources in a concise and safe way. +A `FunFixture` creates one resource for each test, ensuring that each test runs in isolation from the others. + +In a test suite, you can define and use a `FunFixture` as follows: + +{% tabs 'resources-1' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +class FileTests extends munit.FunSuite { + val usingTempFile: FunFixture[os.Path] = FunFixture( + setup = _ => os.temp(prefix = "file-tests"), + teardown = tempFile => os.remove(tempFile) + ) + usingTempFile.test("overwrite on file") { tempFile => + os.write.over(tempFile, "Hello, World!") + val obtained = os.read(tempFile) + assertEquals(obtained, "Hello, World!") + } +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +class FileTests extends munit.FunSuite: + val usingTempFile: FunFixture[os.Path] = FunFixture( + setup = _ => os.temp(prefix = "file-tests"), + teardown = tempFile => os.remove(tempFile) + ) + usingTempFile.test("overwrite on file") { tempFile => + os.write.over(tempFile, "Hello, World!") + val obtained = os.read(tempFile) + assertEquals(obtained, "Hello, World!") + } +``` +{% endtab %} +{% endtabs %} + +`usingTempFile` is a fixture of type `FunFixture[os.Path]`. +It contains two functions: + - The `setup` function, of type `TestOptions => os.Path`, creates a new temporary file. + - The `teardown` function, of type `os.Path => Unit`, deletes this temporary file. + +We use the `usingTempFile` fixture to define a test that needs a temporary file. +Notice that the body of the test takes a `tempFile`, of type `os.Path`, as parameter. +The fixture automatically creates this temporary file, calls its `setup` function, and cleans it up after the test by calling `teardown`. + +In the example, we used a fixture to manage a temporary file. +In general, fixtures can manage other kinds of resources, such as a temporary folder, a temporary table in a database, a connection to a local server, and so on. + +## Composing `FunFixture`s + +In some tests, you may need more than one resource. +You can use `FunFixture.map2` to compose two functional fixtures into one. + +{% tabs 'resources-2' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val using2TempFiles: FunFixture[(os.Path, os.Path)] = + FunFixture.map2(usingTempFile, usingTempFile) + +using2TempFiles.test("merge two files") { + (file1, file2) => + // body of the test +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +val using2TempFiles: FunFixture[(os.Path, os.Path)] = + FunFixture.map2(usingTempFile, usingTempFile) + +using2TempFiles.test("merge two files") { + (file1, file2) => + // body of the test +} +``` +{% endtab %} +{% endtabs %} + +Using `FunFixture.map2` on a `FunFixture[A]` and a `FunFixture[B]` returns a `FunFixture[(A, B)]`. + +## Other fixtures + +`FunFixture` is the recommended type of fixture because: +- it is explicit: each test declares the resource they need, +- it is safe to use: each test uses its own resource in isolation. + +For more flexibility, `MUnit` contains other types of fixtures: the reusable fixture, the ad-hoc fixture and the asynchronous fixture. +Learn more about them in the [MUnit documentation](https://scalameta.org/munit/docs/fixtures.html). diff --git a/_overviews/toolkit/testing-run-only.md b/_overviews/toolkit/testing-run-only.md new file mode 100644 index 0000000000..1469fbd577 --- /dev/null +++ b/_overviews/toolkit/testing-run-only.md @@ -0,0 +1,111 @@ +--- +title: How to run a single test? +type: section +description: About testOnly in the build tool and .only in MUnit +num: 5 +previous-page: testing-run +next-page: testing-exceptions +--- + +{% include markdown.html path="_markdown/install-munit.md" %} + +## Running a single test suite + +{% tabs munit-unit-test-only class=tabs-build-tool %} +{% tab 'Scala CLI' %} +To run a single `example.MyTests` suite with Scala CLI, use the `--test-only` option of the `test` command. +``` +scala-cli test example --test-only example.MyTests +``` + +{% endtab %} +{% tab 'sbt' %} +To run a single `example.MyTests` suite in sbt, use the `testOnly` task: +``` +sbt:example> testOnly example.MyTests +``` +{% endtab %} +{% tab 'Mill' %} +To run a single `example.MyTests` suite in Mill, use the `testOnly` task: +``` +./mill example.test.testOnly example.MyTests +``` +{% endtab %} +{% endtabs %} + +## Running a single test in a test suite + +Within a test suite file, you can select individual tests to run by temporarily appending `.only`, e.g. + +{% tabs 'only-demo' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc +class MathSuite extends munit.FunSuite { + test("addition") { + assert(1 + 1 == 2) + } + test("multiplication".only) { + assert(3 * 7 == 21) + } +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +class MathSuite extends munit.FunSuite: + test("addition") { + assert(1 + 1 == 2) + } + test("multiplication".only) { + assert(3 * 7 == 21) + } +``` +{% endtab %} +{% endtabs %} + +In the above example, only the `"multiplication"` tests will run (i.e. `"addition"` is ignored). +This is useful to quickly debug a specific test in a suite. + +## Alternative: excluding specific tests + +You can exclude specific tests from running by appending `.ignore` to the test name. +For example the following ignores the `"addition"` test, and run all the others: + +{% tabs 'ignore-demo' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:reset +class MathSuite extends munit.FunSuite { + test("addition".ignore) { + assert(1 + 1 == 2) + } + test("multiplication") { + assert(3 * 7 == 21) + } + test("remainder") { + assert(13 % 5 == 3) + } +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +class MathSuite extends munit.FunSuite: + test("addition".ignore) { + assert(1 + 1 == 2) + } + test("multiplication") { + assert(3 * 7 == 21) + } + test("remainder") { + assert(13 % 5 == 3) + } +``` +{% endtab %} +{% endtabs %} + +## Use tags to group tests, and run specific tags + +MUnit lets you group and run tests across suites by tags, which are textual labels. +[The MUnit docs][munit-tags] have instructions on how to do this. + +[munit-tags]: https://scalameta.org/munit/docs/filtering.html#include-and-exclude-tests-based-on-tags diff --git a/_overviews/toolkit/testing-run.md b/_overviews/toolkit/testing-run.md new file mode 100644 index 0000000000..09bc23e73a --- /dev/null +++ b/_overviews/toolkit/testing-run.md @@ -0,0 +1,92 @@ +--- +title: How to run tests? +type: section +description: Running the MUnit tests +num: 4 +previous-page: testing-suite +next-page: testing-run-only +--- + +{% include markdown.html path="_markdown/install-munit.md" %} + +## Running the tests + +You can run all of your test suites with a single command. + +{% tabs munit-unit-test-4 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +Using Scala CLI, the following command runs all the tests in the folder `example`: +``` +scala-cli test example +# Compiling project (test, Scala 3.2.1, JVM) +# Compiled project (test, Scala 3.2.1, JVM) +# MyTests: +# + sum of two integers 0.009s +``` +{% endtab %} +{% tab 'sbt' %} +In the sbt shell, the following command runs all the tests of the project `example`: +``` +sbt:example> test +# MyTests: +# + sum of two integers 0.006s +# [info] Passed: Total 1, Failed 0, Errors 0, Passed 1 +# [success] Total time: 0 s, completed Nov 11, 2022 12:54:08 PM +``` +{% endtab %} +{% tab 'Mill' %} +In Mill, the following command runs all the tests of the module `example`: +``` +./mill example.test.test +# [71/71] example.test.test +# MyTests: +# + sum of two integers 0.008s +``` +{% endtab %} +{% endtabs %} + +The test report, printed in the console, shows the status of each test. +The `+` symbol before a test name shows that the test passed successfully. + +Add and run a failing test to see how a failure looks: + +{% tabs assertions-1 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +test("failing test") { + val obtained = 2 + 3 + val expected = 4 + assertEquals(obtained, expected) +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +test("failing test") { + val obtained = 2 + 3 + val expected = 4 + assertEquals(obtained, expected) +} +``` +{% endtab %} +{% endtabs %} + +``` +# MyTests: +# + sum of two integers 0.008s +# ==> X MyTests.failing test 0.015s munit.ComparisonFailException: ./MyTests.test.scala:13 +# 12: val expected = 4 +# 13: assertEquals(obtained, expected) +# 14: } +# values are not the same +# => Obtained +# 5 +# => Diff (- obtained, + expected) +# -5 +# +4 +# at munit.Assertions.failComparison(Assertions.scala:274) +``` + +The line starting with `==> X` indicates that the test named `failing test` fails. +The following lines show where and how it failed. +Here it shows that the obtained value is 5, where 4 was expected. diff --git a/_overviews/toolkit/testing-suite.md b/_overviews/toolkit/testing-suite.md new file mode 100644 index 0000000000..7c068edfe7 --- /dev/null +++ b/_overviews/toolkit/testing-suite.md @@ -0,0 +1,130 @@ +--- +title: How to write tests? +type: section +description: The basics of writing a test suite with MUnit +num: 3 +previous-page: testing-intro +next-page: testing-run +--- + +{% include markdown.html path="_markdown/install-munit.md" %} + +## Writing a test suite + +A group of tests in a single class is called a test class or test suite. + +Each test suite validates a particular component or feature of the software. +Typically we define one test suite for each source file or class that we want to test. + +{% tabs munit-unit-test-2 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +In Scala CLI, the test file can live in the same folder as the actual code, but the name of the file must end with `.test.scala`. +In the following, `MyTests.test.scala` is a test file. +``` +example/ +├── MyApp.scala +└── MyTests.test.scala +``` +Other valid structures and conventions are described in the [Scala CLI documentation](https://scala-cli.virtuslab.org/docs/commands/test/#test-sources). +{% endtab %} +{% tab 'sbt' %} +In sbt, test sources go in the `src/test/scala` folder. + +For instance, the following is the file structure of a project `example`: +``` +example +└── src + ├── main + │ └── scala + │ └── MyApp.scala + └── test + └── scala + └── MyTests.scala +``` +{% endtab %} +{% tab 'Mill' %} +In Mill, test sources go in the `test/src` folder. + +For instance, the following is the file structure of a module `example`: +``` +example +└── src +| └── MyApp.scala +└── test + └── src + └── MyTests.scala +``` +{% endtab %} +{% endtabs %} + +In the test source file, define a suite containing a single test: + +{% tabs munit-unit-test-3 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +package example + +class MyTests extends munit.FunSuite { + test("sum of two integers") { + val obtained = 2 + 2 + val expected = 4 + assertEquals(obtained, expected) + } +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +package example + +class MyTests extends munit.FunSuite: + test("sum of two integers") { + val obtained = 2 + 2 + val expected = 4 + assertEquals(obtained, expected) + } +``` +{% endtab %} +{% endtabs %} + +A test suite is a Scala class that extends `munit.FunSuite`. +It contains one or more tests, each defined by a call to the `test` method. + +In the previous example, we have a single test `"sum of integers"` that checks that `2 + 2` equals `4`. +We use the assertion method `assertEquals` to check that two values are equal. +The test passes if all the assertions are correct and fails otherwise. + +## Assertions + +It is important to use assertions in each and every test to describe what to check. +The main assertion methods in MUnit are: +- `assertEquals` to check that what you obtain is equal to what you expected +- `assert` to check a boolean condition + +The following is an example of a test that use `assert` to check a boolean condition on a list. + +{% tabs assertions-1 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +test("all even numbers") { + val input: List[Int] = List(1, 2, 3, 4) + val obtainedResults: List[Int] = input.map(_ * 2) + // check that obtained values are all even numbers + assert(obtainedResults.forall(x => x % 2 == 0)) +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +test("all even numbers") { + val input: List[Int] = List(1, 2, 3, 4) + val obtainedResults: List[Int] = input.map(_ * 2) + // check that obtained values are all even numbers + assert(obtainedResults.forall(x => x % 2 == 0)) +} +``` +{% endtab %} +{% endtabs %} + +MUnit contains more assertion methods that you can discover in its [documentation](https://scalameta.org/munit/docs/assertions.html): +`assertNotEquals`, `assertNoDiff`, `fail`, and `compileErrors`. diff --git a/_overviews/toolkit/testing-what-else.md b/_overviews/toolkit/testing-what-else.md new file mode 100644 index 0000000000..4c0672af1a --- /dev/null +++ b/_overviews/toolkit/testing-what-else.md @@ -0,0 +1,85 @@ +--- +title: What else can MUnit do? +type: section +description: A incomplete list of features of MUnit +num: 9 +previous-page: testing-resources +next-page: os-intro +--- + +{% include markdown.html path="_markdown/install-munit.md" %} + +## Adding clues to get better error report + +Use `clue` inside an `assert` to a get a better error report when the assertion fails. + +{% tabs clues %} +{% tab 'Scala 2 and 3' %} +```scala +assert(clue(List(a).head) > clue(b)) +// munit.FailException: assertion failed +// Clues { +// List(a).head: Int = 1 +// b: Int = 2 +// } +``` +{% endtab %} +{% endtabs %} + +Learn more about clues in the [MUnit documentation](https://scalameta.org/munit/docs/assertions.html#assert). + +## Writing environment-specific tests + +Use `assume` to write environment-specific tests. +`assume` can contain a boolean condition. You can check the operating system, the Java version, a Java property, an environment variable, or anything else. +A test is skipped if one of its assumptions isn't met. + +{% tabs assumption class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import scala.util.Properties + +test("home directory") { + assume(Properties.isLinux, "this test runs only on Linux") + assert(os.home.toString.startsWith("/home/")) +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import scala.util.Properties + +test("home directory") { + assume(Properties.isLinux, "this test runs only on Linux") + assert(os.home.toString.startsWith("/home/")) +} +``` +{% endtab %} +{% endtabs %} + +Learn more about filtering tests in the [MUnit documentation](https://scalameta.org/munit/docs/filtering.html). + +## Tagging flaky tests + +You can tag a test with `flaky` to mark it as being flaky. +Flaky tests can be skipped by setting the `MUNIT_FLAKY_OK` environment variable to `true`. + +{% tabs flaky class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +test("requests".flaky) { + // I/O heavy tests that sometimes fail +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +test("requests".flaky) { + // I/O heavy tests that sometimes fail +} +``` +{% endtab %} +{% endtabs %} + +Learn more about flaky tests in the [MUnit documentation](https://scalameta.org/munit/docs/tests.html#tag-flaky-tests) + diff --git a/_overviews/toolkit/web-server-cookies-and-decorators.md b/_overviews/toolkit/web-server-cookies-and-decorators.md new file mode 100644 index 0000000000..36caeac4de --- /dev/null +++ b/_overviews/toolkit/web-server-cookies-and-decorators.md @@ -0,0 +1,188 @@ +--- +title: How to use cookies and decorators? +type: section +description: Using cookies and decorators with Cask +num: 36 +previous-page: web-server-websockets +next-page: +--- + +{% include markdown.html path="_markdown/install-cask.md" %} + +## Using cookies + +Cookies are saved by adding them to the `cookies` parameter of the `cask.Response` constructor. + +In this example, we are building a rudimentary authentication service. The `getLogin` method provides a form where +the user can enter their username and password. The `postLogin` method reads the credentials. If they match the expected ones, it generates a session +identifier is generated, saves it in the application state, and sends back a cookie with the identifier. + +Cookies can be read either with a method parameter of `cask.Cookie` type or by accessing the `cask.Request` directly. +If using the former method, the names of parameters have to match the names of cookies. If a cookie with a matching name is not +found, an error response will be returned. In the `checkLogin` function, the former method is used, as the cookie is not +present before the user logs in. + +To delete a cookie, set its `expires` parameter to an instant in the past, for example `Instant.EPOCH`. + +{% tabs web-server-cookies-1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import java.util.UUID +import java.util.concurrent.ConcurrentHashMap + +object Example extends cask.MainRoutes { + + val sessionIds = ConcurrentHashMap.newKeySet[String]() + + @cask.get("/login") + def getLogin(): cask.Response[String] = { + val html = + """ + | + | + |
            + |
            + |
            + |
            + |

            + | + |
            + | + |""".stripMargin + + cask.Response(data = html, headers = Seq("Content-Type" -> "text/html")) + } + + @cask.postForm("/login") + def postLogin(name: String, password: String): cask.Response[String] = { + if (name == "user" && password == "password") { + val sessionId = UUID.randomUUID().toString + sessionIds.add(sessionId) + cask.Response(data = "Success!", cookies = Seq(cask.Cookie("sessionId", sessionId))) + } else { + cask.Response(data = "Authentication failed", statusCode = 401) + } + } + + @cask.get("/check") + def checkLogin(request: cask.Request): String = { + val sessionId = request.cookies.get("sessionId") + if (sessionId.exists(cookie => sessionIds.contains(cookie.value))) { + "You are logged in" + } else { + "You are not logged in" + } + } + + @cask.get("/logout") + def logout(sessionId: cask.Cookie) = { + sessionIds.remove(sessionId.value) + cask.Response(data = "Successfully logged out!", cookies = Seq(cask.Cookie("sessionId", "", expires = Instant.EPOCH))) + } + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import java.util.UUID +import java.util.concurrent.ConcurrentHashMap + +object Example extends cask.MainRoutes: + + val sessionIds = ConcurrentHashMap.newKeySet[String]() + + @cask.get("/login") + def getLogin(): cask.Response[String] = + val html = + """ + | + | + |
            + |
            + |
            + |
            + |

            + | + |
            + | + |""".stripMargin + + cask.Response(data = html, headers = Seq("Content-Type" -> "text/html")) + + @cask.postForm("/login") + def postLogin(name: String, password: String): cask.Response[String] = + if name == "user" && password == "password" then + val sessionId = UUID.randomUUID().toString + sessionIds.add(sessionId) + cask.Response(data = "Success!", cookies = Seq(cask.Cookie("sessionId", sessionId))) + else + cask.Response(data = "Authentication failed", statusCode = 401) + + @cask.get("/check") + def checkLogin(request: cask.Request): String = + val sessionId = request.cookies.get("sessionId") + if sessionId.exists(cookie => sessionIds.contains(cookie.value)) then + "You are logged in" + else + "You are not logged in" + + @cask.get("/logout") + def logout(sessionId: cask.Cookie): cask.Response[String] = + sessionIds.remove(sessionId.value) + cask.Response(data = "Successfully logged out!", cookies = Seq(cask.Cookie("sessionId", "", expires = Instant.EPOCH))) + + initialize() +``` +{% endtab %} +{% endtabs %} + +## Using decorators + +Decorators can be used for extending endpoints functionality with validation or new parameters. They are defined by extending +`cask.RawDecorator` class. They are used as annotations. + +In this example, the `loggedIn` decorator is used to check if the user is logged in before accessing the `/decorated` +endpoint. + +The decorator class can pass additional arguments to the decorated endpoint using a map. The passed arguments are available +through the last argument group. Here we are passing the session identifier to an argument named `sessionId`. + +{% tabs web-server-cookies-2 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +class loggedIn extends cask.RawDecorator { + override def wrapFunction(ctx: cask.Request, delegate: Delegate): Result[Raw] = { + ctx.cookies.get("sessionId") match { + case Some(cookie) if sessionIds.contains(cookie.value) => delegate(Map("sessionId" -> cookie.value)) + case _ => cask.router.Result.Success(cask.model.Response("You aren't logged in", 403)) + } + } +} + +@loggedIn() +@cask.get("/decorated") +def decorated()(sessionId: String): String = { + s"You are logged in with id: $sessionId" +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +class loggedIn extends cask.RawDecorator: + override def wrapFunction(ctx: cask.Request, delegate: Delegate): Result[Raw] = + ctx.cookies.get("sessionId") match + case Some(cookie) if sessionIds.contains(cookie.value) => + delegate(Map("sessionId" -> cookie.value)) + case _ => + cask.router.Result.Success(cask.model.Response("You aren't logged in", 403)) + + +@loggedIn() +@cask.get("/decorated") +def decorated()(sessionId: String): String = s"You are logged in with id: $sessionId" +``` +{% endtab %} +{% endtabs %} \ No newline at end of file diff --git a/_overviews/toolkit/web-server-dynamic.md b/_overviews/toolkit/web-server-dynamic.md new file mode 100644 index 0000000000..c7bc84ac97 --- /dev/null +++ b/_overviews/toolkit/web-server-dynamic.md @@ -0,0 +1,237 @@ +--- +title: How to serve a dynamic page? +type: section +description: Serving a dynamic page with Cask +num: 32 +previous-page: web-server-static +next-page: web-server-query-parameters +--- + +{% include markdown.html path="_markdown/install-cask.md" %} + +## Serving dynamically generated content + +You can create an endpoint returning dynamically generated content with the `@cask.get` annotation. + +{% tabs web-server-dynamic-1 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.time.ZonedDateTime + +object Example extends cask.MainRoutes { + @cask.get("/time") + def dynamic(): String = s"Current date is: ${ZonedDateTime.now()}" + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import java.time.ZonedDateTime + +object Example extends cask.MainRoutes: + @cask.get("/time") + def dynamic(): String = s"Current date is: ${ZonedDateTime.now()}" + + initialize() +``` +{% endtab %} +{% endtabs %} + +The example above creates an endpoint that returns the current date and time available at `/time`. The exact response will be +recreated every time you refresh the webpage. + +Since the endpoint method has the `String` output type, the result will be sent with the `text/plain` [content type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type). +If you want an HTML output to be interpreted by the browser, you will need to set the `Content-Type` header manually +or [use the Scalatags templating library](/toolkit/web-server-dynamic.html#using-html-templates), supported by Cask. + +### Running the example + +Run the example the same way as before, assuming you use the same project structure as described in [the static file tutorial](/toolkit/web-server-static.html). + +{% tabs web-server-dynamic-2 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +In the terminal, the following command will start the server: +``` +scala-cli run Example.scala +``` +{% endtab %} +{% tab 'sbt' %} +In the terminal, the following command will start the server: +``` +sbt example/run +``` +{% endtab %} +{% tab 'Mill' %} +In the terminal, the following command will start the server: +``` +./mill run +``` +{% endtab %} +{% endtabs %} + +Access the endpoint at [http://localhost:8080/time](http://localhost:8080/time). You should see a result similar to the one below. + +``` +Current date is: 2024-07-22T09:07:05.752534+02:00[Europe/Warsaw] +``` + +## Using path segments + +Cask gives you the ability to access segments of the URL path within the endpoint function. +Building on the example above, you can add a segment to specify that the endpoint should return the date and time +in a given city. + +{% tabs web-server-dynamic-3 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.time.{ZoneId, ZonedDateTime} + +object Example extends cask.MainRoutes { + + private def getZoneIdForCity(city: String): Option[ZoneId] = { + import scala.jdk.CollectionConverters._ + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + } + + @cask.get("/time/:city") + def dynamicWithCity(city: String): String = { + getZoneIdForCity(city) match { + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + } + } + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import java.time.{ZoneId, ZonedDateTime} + +object Example extends cask.MainRoutes: + + private def getZoneIdForCity(city: String): Option[ZoneId] = + import scala.jdk.CollectionConverters.* + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + + @cask.get("/time/:city") + def dynamicWithCity(city: String): String = + getZoneIdForCity(city) match + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + + initialize() +``` +{% endtab %} +{% endtabs %} + +In the example above, the `:city` segment in `/time/:city` is available through the `city` argument of the endpoint method. +The name of the argument must be identical to the segment name. The `getZoneIdForCity` helper method finds the timezone for +a given city, and then the current date and time are translated to that timezone. + +Accessing the endpoint at [http://localhost:8080/time/Paris](http://localhost:8080/time/Paris) will result in: +``` +Current date is: 2024-07-22T09:08:33.806259+02:00[Europe/Paris] +``` + +You can use more than one path segment in an endpoint by adding more arguments to the endpoint method. It's also possible to use paths +with an unspecified number of segments (for example `/path/foo/bar/baz/`) by giving the endpoint method an argument with `cask.RemainingPathSegments` type. +Consult the [documentation](https://com-lihaoyi.github.io/cask/index.html#variable-routes) for more details. + +## Using HTML templates + +To create an HTML response, you can combine Cask with the [Scalatags](https://com-lihaoyi.github.io/scalatags/) templating library. + +Import the Scalatags library: + +{% tabs web-server-dynamic-4 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +Add the Scalatags dependency in `Example.sc` file: +```scala +//> using dep com.lihaoyi::scalatags::0.13.1 +``` +{% endtab %} +{% tab 'sbt' %} +Add the Scalatags dependency in `build.sbt` file: +```scala +libraryDependencies += "com.lihaoyi" %% "scalatags" % "0.13.1" +``` +{% endtab %} +{% tab 'Mill' %} +Add the Scalatags dependency in `build.cs` file: +```scala +ivy"com.lihaoyi::scalatags::0.13.1" +``` +{% endtab %} +{% endtabs %} + +Now the example above can be rewritten to use a template. Cask will build a response out of the `doctype` automatically, +setting the `Content-Type` header to `text/html`. + +{% tabs web-server-dynamic-5 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.time.{ZoneId, ZonedDateTime} +import scalatags.Text.all._ + +object Example extends cask.MainRoutes { + + private def getZoneIdForCity(city: String): Option[ZoneId] = { + import scala.jdk.CollectionConverters._ + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + } + + @cask.get("/time/:city") + def dynamicWithCity(city: String): doctype = { + val text = getZoneIdForCity(city) match { + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + } + + doctype("html")( + html( + body( + p(text) + ) + ) + ) + } + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import java.time.{ZoneId, ZonedDateTime} +import scalatags.Text.all.* + +object Example extends cask.MainRoutes: + + private def getZoneIdForCity(city: String): Option[ZoneId] = + import scala.jdk.CollectionConverters.* + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + + @cask.get("/time/:city") + def dynamicWithCity(city: String): doctype = + val text = getZoneIdForCity(city) match + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + doctype("html")( + html( + body( + p(text) + ) + ) + ) + + initialize() +``` +{% endtab %} +{% endtabs %} + +Here we get the text of the response and wrap it in a Scalatags template. Notice that the return type changed from `String` +to `doctype`. diff --git a/_overviews/toolkit/web-server-input.md b/_overviews/toolkit/web-server-input.md new file mode 100644 index 0000000000..8be4c659d3 --- /dev/null +++ b/_overviews/toolkit/web-server-input.md @@ -0,0 +1,243 @@ +--- +title: How to handle user input? +type: section +description: Handling user input with Cask +num: 34 +previous-page: web-server-query-parameters +next-page: web-server-websockets +--- + +{% include markdown.html path="_markdown/install-cask.md" %} + +## Handling form-encoded input + +To create an endpoint that handles the data provided in an HTML form, use the `@cask.postForm` annotation. Add arguments to the endpoint method +with names corresponding to names of fields in the form and set the form method to `post`. + +{% tabs web-server-input-1 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object Example extends cask.MainRoutes { + + @cask.get("/form") + def getForm(): cask.Response[String] = { + val html = + """ + | + | + |
            + |
            + |
            + |
            + |

            + | + |
            + | + |""".stripMargin + + cask.Response(data = html, headers = Seq("Content-Type" -> "text/html")) + } + + @cask.postForm("/form") + def formEndpoint(name: String, surname: String): String = + "Hello " + name + " " + surname + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object Example extends cask.MainRoutes: + + @cask.get("/form") + def getForm(): cask.Response[String] = + val html = + """ + | + | + |
            + |
            + |
            + |
            + |

            + | + |
            + | + |""".stripMargin + + cask.Response(data = html, headers = Seq("Content-Type" -> "text/html")) + + @cask.postForm("/form") + def formEndpoint(name: String, surname: String): String = + "Hello " + name + " " + surname + + initialize() +``` +{% endtab %} +{% endtabs %} + +In this example we create a form asking for name and surname of a user and then redirect the user to a greeting page. Notice the +use of `cask.Response`. The `cask.Response` type allows the user to set the status code, headers and cookies. The default +content type for an endpoint method returning a `String` is `text/plain`. Set it to `text/html` in order for the browser to display the form correctly. + +The `formEndpoint` endpoint reads the form data using the `name` and `surname` parameters. The names of parameters must +be identical to the field names of the form. + +## Handling JSON-encoded input + +JSON fields are handled in the same way as form fields, except that we use the `@cask.PostJson` annotation. The fields +will be read into the endpoint method arguments. + +{% tabs web-server-input-2 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object Example extends cask.MainRoutes { + + @cask.postJson("/json") + def jsonEndpoint(name: String, surname: String): String = + "Hello " + name + " " + surname + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object Example extends cask.MainRoutes: + + @cask.postJson("/json") + def jsonEndpoint(name: String, surname: String): String = + "Hello " + name + " " + surname + + initialize() +``` +{% endtab %} +{% endtabs %} + +Send the POST request using `curl`: + +```shell +curl --header "Content-Type: application/json" \ + --data '{"name":"John","surname":"Smith"}' \ + http://localhost:8080/json +``` + +The response will be: +``` +Hello John Smith +``` + +The endpoint will accept JSONs that have only the fields with names specified as the endpoint method arguments. If there +are more fields than expected, some fields are missing or have an incorrect data type, an error message +will be returned with the response code 400. + +To handle the case when the fields of the JSON are not known in advance, you can use an argument with the `ujson.Value` type, +from uPickle library. + +{% tabs web-server-input-3 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object Example extends cask.MainRoutes { + + @cask.postJson("/json") + def jsonEndpoint(value: ujson.Value): String = + value.toString + + initialize() +} + +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object Example extends cask.MainRoutes: + + @cask.postJson("/json") + def jsonEndpoint(value: ujson.Value): String = + value.toString + + initialize() + +``` +{% endtab %} +{% endtabs %} + +In this example the JSON is merely converted to `String`. Check the [*uPickle tutorial*](/toolkit/json-intro.html) for more information +on what can be done with the `ujson.Value` type. + +Send a POST request. +```shell +curl --header "Content-Type: application/json" \ + --data '{"value":{"name":"John","surname":"Smith"}}' \ + http://localhost:8080/json2 +``` + +The server will respond with: +``` +"{\"name\":\"John\",\"surname\":\"Smith\"}" +``` + +## Handling JSON-encoded output + +Cask endpoints can return JSON objects returned by uPickle library functions. Cask will automatically handle the `ujson.Value` +type and set the `Content-Type` header to `application/json`. + +In this example, the `TimeData` case class stores the information about the time zone and current time in a chosen +location. To serialize a case class into JSON, use type class derivation or define the serializer in its companion object in the case of Scala 2. + +{% tabs web-server-input-4 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.time.{ZoneId, ZonedDateTime} + +object Example extends cask.MainRoutes { + import upickle.default.{ReadWriter, macroRW, writeJs} + case class TimeData(timezone: Option[String], time: String) + object TimeData { + implicit val rw: ReadWriter[TimeData] = macroRW + } + + private def getZoneIdForCity(city: String): Option[ZoneId] = { + import scala.jdk.CollectionConverters._ + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + } + + @cask.get("/time_json/:city") + def timeJSON(city: String): ujson.Value = { + val timezone = getZoneIdForCity(city) + val time = timezone match { + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + } + writeJs(TimeData(timezone.map(_.toString), time)) + } + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import java.time.{ZoneId, ZonedDateTime} + +object Example extends cask.MainRoutes: + import upickle.default.{ReadWriter, writeJs} + case class TimeData(timezone: Option[String], time: String) derives ReadWriter + + private def getZoneIdForCity(city: String): Option[ZoneId] = + import scala.jdk.CollectionConverters.* + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + + @cask.get("/time_json/:city") + def timeJSON(city: String): ujson.Value = + val timezone = getZoneIdForCity(city) + val time = timezone match + case Some(zoneId)=> s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + writeJs(TimeData(timezone.map(_.toString), time)) + + initialize() +``` +{% endtab %} +{% endtabs %} \ No newline at end of file diff --git a/_overviews/toolkit/web-server-intro.md b/_overviews/toolkit/web-server-intro.md new file mode 100644 index 0000000000..bf2db8a537 --- /dev/null +++ b/_overviews/toolkit/web-server-intro.md @@ -0,0 +1,24 @@ +--- +title: Building web servers with Cask +type: chapter +description: The introduction of the Cask library +num: 30 +languages: [ru] +previous-page: http-client-what-else +next-page: web-server-static +--- + +Cask is an HTTP micro-framework, providing a simple and flexible way to build web applications. + +Its main focus is on the ease of use, which makes it ideal for newcomers, at the cost of eschewing some features other +frameworks provide, like asynchronicity. + +To define an endpoint it's enough to annotate a function with an annotation specifying the request path. +Cask allows for building the response manually using tools that the library provides, specifying the content, headers, +status code, etc. An endpoint function can also return a string, a [uPickle](https://com-lihaoyi.github.io/upickle/) JSON type, or a [Scalatags](https://com-lihaoyi.github.io/scalatags/) +template. In that case, Cask will automatically create a response with the appropriate headers. + +Cask comes bundled with the uPickle library for handling JSONs, supports WebSockets and allows for extending endpoints with +decorators, which can be used to handle authentication or rate limiting. + +{% include markdown.html path="_markdown/install-cask.md" %} diff --git a/_overviews/toolkit/web-server-query-parameters.md b/_overviews/toolkit/web-server-query-parameters.md new file mode 100644 index 0000000000..8da1dc9ccc --- /dev/null +++ b/_overviews/toolkit/web-server-query-parameters.md @@ -0,0 +1,74 @@ +--- +title: How to handle query parameters? +type: section +description: Handling query parameters with Cask +num: 33 +previous-page: web-server-dynamic +next-page: web-server-input +--- + +{% include markdown.html path="_markdown/install-cask.md" %} + +Query parameters are the key-value pairs coming after the question mark in a URL. They can be used for filtering, +sorting or limiting the results provided by the server. For example, in the `/time?city=Paris` URL, the `city` part +is the name of a parameter, and `Paris` is its value. Cask allows for reading the query parameters by defining an endpoint +method with arguments matching the names of the expected parameters and not matching any of the URL segments. + +In this example, we give an `Option` type and the default value `None` to the `city` parameter. This tells Cask that it is optional. +If not provided, the time for the current timezone will be returned. + +{% tabs web-server-query-1 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.time.{ZoneId, ZonedDateTime} + +object Example extends cask.MainRoutes { + + private def getZoneIdForCity(city: String): Option[ZoneId] = { + import scala.jdk.CollectionConverters._ + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + } + + @cask.get("/time") + def dynamicWithParam(city: Option[String] = None): String = { + city match { + case Some(value) => getZoneIdForCity(value) match { + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $value" + } + case None => s"Current date is: ${ZonedDateTime.now()}" + } + } + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +import java.time.{ZoneId, ZonedDateTime} + +object Example extends cask.MainRoutes: + + private def getZoneIdForCity(city: String): Option[ZoneId] = + import scala.jdk.CollectionConverters.* + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + + @cask.get("/time") + def dynamicWithParam(city: Option[String] = None): String = + city match + case Some(value) => getZoneIdForCity(value) match + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $value" + case None => s"Current date is: ${ZonedDateTime.now()}" + + initialize() +``` +{% endtab %} +{% endtabs %} + +Run the example as before and access the endpoint at [http://localhost:8080/time?city=Paris](http://localhost:8080/time?city=Paris). +You should get a result similar to the following one. +``` +Current date is: 2024-07-22T10:08:18.218736+02:00[Europe/Paris] +``` diff --git a/_overviews/toolkit/web-server-static.md b/_overviews/toolkit/web-server-static.md new file mode 100644 index 0000000000..780941efb0 --- /dev/null +++ b/_overviews/toolkit/web-server-static.md @@ -0,0 +1,159 @@ +--- +title: How to serve a static file? +type: section +description: Serving a static file with Cask +num: 31 +previous-page: web-server-intro +next-page: web-server-dynamic +--- + +{% include markdown.html path="_markdown/install-cask.md" %} + +## Serving a static file + +An endpoint is a specific URL where a particular webpage can be accessed. In Cask, an endpoint is a function returning the +webpage data, together with an annotation describing its URL. + +To create an endpoint serving static files, we need two things: an HTML file with the page content and a function that +points to that file. + +Create a minimal HTML file named `hello.html` with the following contents. + +```html + + + + Hello World + + +

            Hello world

            + + +``` + +Place it in the `resources` directory. + +{% tabs web-server-static-1 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +``` +example +├── Example.scala +└── resources + └── hello.html +``` +{% endtab %} +{% tab 'sbt' %} +``` +example +└──src + └── main + ├── resources + │ └── hello.html + └── scala + └── Example.scala +``` +{% endtab %} +{% tab 'Mill' %} +``` +example +├── src +│ └── Example.scala +└── resources + └── hello.html +``` +{% endtab %} +{% endtabs %} + +The `@cask.staticFiles` annotation specifies at which path the webpage will be available. The endpoint function returns +the location of the file. + +{% tabs web-server-static-2 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object Example extends cask.MainRoutes { + @cask.staticFiles("/static") + def staticEndpoint(): String = "src/main/resources" // or "resources" if not using SBT + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object Example extends cask.MainRoutes: + @cask.staticFiles("/static") + def staticEndpoint(): String = "src/main/resources" // or "resources" if not using SBT + + initialize() +``` +{% endtab %} +{% endtabs %} + +In the example above, `@cask.staticFiles` instructs the server to look for files accessed at the `/static` path in the +`src/main/resources` directory. Cask will match any subpath coming after `/static` and append it to the directory path. +If you access the `/static/hello.html` file, it will serve the file available at `src/main/resources/hello.html`. +The directory path can be any path available to the server, relative or not. If the requested file cannot be found in the +specified location, the server will return a 404 response with an error message. + +The `Example` object inherits from the `cask.MainRoutes` class. It provides the main function that starts the server. The `initialize()` +method call initializes the server routes, i.e., the association between URL paths and the code that handles them. + +### Using the resources directory + +The `@cask.staticResources` annotation works in the same way as the `@cask.staticFiles` used above, with the difference that +the path returned by the endpoint method describes the location of files _inside_ the resources directory. Since the +previous example conveniently used the resources directory, it can be simplified with `@cask.staticResources`. + +{% tabs web-server-static-3 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object Example extends cask.MainRoutes { + @cask.staticResources("/static") + def staticEndpoint(): String = "." + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object Example extends cask.MainRoutes: + @cask.staticResources("/static") + def staticEndpoint(): String = "." + + initialize() +``` +{% endtab %} +{% endtabs %} + +In the endpoint method, the location is set to `"."`, telling the server that the files are available directly in the +resources directory. In general, you can use any nested location within the resources directory. For instance, you could opt +for placing your HTML files in the `static` directory inside the resources directory or using different directories to sort out +files used by different endpoints. + +## Running the example + +Run the example with the build tool of your choice. + +{% tabs munit-unit-test-4 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +In the terminal, the following command will start the server: +``` +scala run Example.scala +``` +{% endtab %} +{% tab 'sbt' %} +In the terminal, the following command will start the server: +``` +sbt example/run +``` +{% endtab %} +{% tab 'Mill' %} +In the terminal, the following command will start the server: +``` +./mill run +``` +{% endtab %} +{% endtabs %} + +The example page will be available at [http://localhost:8080/static/hello.html](http://localhost:8080/static/hello.html). diff --git a/_overviews/toolkit/web-server-websockets.md b/_overviews/toolkit/web-server-websockets.md new file mode 100644 index 0000000000..653bd7f154 --- /dev/null +++ b/_overviews/toolkit/web-server-websockets.md @@ -0,0 +1,118 @@ +--- +title: How to use websockets? +type: section +description: Using websockets with Cask +num: 35 +previous-page: web-server-input +next-page: web-server-cookies-and-decorators +--- + +{% include markdown.html path="_markdown/install-cask.md" %} + +You can create a WebSocket endpoint with the `@cask.websocket` annotation. The endpoint method should return a +`cask.WsHandler` instance defining how the communication should take place. It can also return a `cask.Response`, which rejects the +attempt at forming a WebSocket connection. + +The connection can also be closed by sending a `cask.Ws.close()` message through the WebSocket channel. + +Create an HTML file named `websockets.html` with the following content and place it in the `resources ` directory. + +```html + + + +
            + + +
            +
            + + + +``` + +The JavaScript code opens a WebSocket connection using the `ws://localhost:8080/websocket` endpoint. The `ws.onmessage` +event handler is executed when the server pushes a message to the browser and `ws.onclose` when the connection is closed. + +Create an endpoint for serving static files using the `@cask.staticResources` annotation and an endpoint for handling +the WebSocket connection. + +{% tabs web-server-websocket-1 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +@cask.staticResources("/static") +def static() = "." + +private def getZoneIdForCity(city: String): Option[ZoneId] = { + import scala.jdk.CollectionConverters._ + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) +} + +@cask.websocket("/websocket") +def websocket(): cask.WsHandler = { + cask.WsHandler { channel => + cask.WsActor { + case cask.Ws.Text("") => channel.send(cask.Ws.Close()) + case cask.Ws.Text(city) => + val text = getZoneIdForCity(city) match { + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + } + channel.send(cask.Ws.Text(text)) + } + } +} + +initialize() +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +@cask.staticResources("/static") +def static() = "." + +private def getZoneIdForCity(city: String): Option[ZoneId] = + import scala.jdk.CollectionConverters.* + ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of) + +@cask.websocket("/websocket") +def websocket(): cask.WsHandler = + cask.WsHandler { channel => + cask.WsActor { + case cask.Ws.Text("") => channel.send(cask.Ws.Close()) + case cask.Ws.Text(city) => + val text = getZoneIdForCity(city) match + case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}" + case None => s"Couldn't find time zone for city $city" + channel.send(cask.Ws.Text(text)) + } + } + +initialize() +``` +{% endtab %} +{% endtabs %} + +In the `cask.WsHandler` we define a `cask.WsActor`. It reacts to events (of type `cask.util.Ws.Event`) and uses the +WebSocket channel to send messages. In this example, we receive the name of a city and return the current time there. If the server +receives an empty message, the connection is closed. \ No newline at end of file diff --git a/_overviews/tutorials/binary-compatibility-for-library-authors.md b/_overviews/tutorials/binary-compatibility-for-library-authors.md index d8cf3002da..c3fd5467a9 100644 --- a/_overviews/tutorials/binary-compatibility-for-library-authors.md +++ b/_overviews/tutorials/binary-compatibility-for-library-authors.md @@ -52,7 +52,7 @@ Similarly to the JVM, Scala.js and Scala Native have their respective equivalent However, contrary to the JVM, Scala.js and Scala Native link their respective IR files at link time, so eagerly, instead of lazily at run-time. Failure to correctly link the entire program results in linking errors reported while trying to invoke `fastOptJS`/`fullOptJS` or `nativeLink`. -Besides that difference in the timing of linkage errors, the models are extremely similar. **Unless otherwise noted, the contents of this guide apply equally to the JVM, Scala.js and Scala Native.** +Besides, that difference in the timing of linkage errors, the models are extremely similar. **Unless otherwise noted, the contents of this guide apply equally to the JVM, Scala.js and Scala Native.** Before we look at how to avoid binary incompatibility errors, let us first establish some key terminologies we will be using for the rest of the guide. @@ -67,7 +67,7 @@ Because of this, having multiple versions of the same library in the classpath i * Unexpected runtime behavior if the order of class files changes Therefore, build tools like sbt and Gradle will pick one version and **evict** the rest when resolving JARs to use for compilation and packaging. -By default they pick the latest version of each library, but it is possible to specify another version if required. +By default, they pick the latest version of each library, but it is possible to specify another version if required. ### Source Compatibility Two library versions are **Source Compatible** with each other if switching one for the other does not incur any compile errors or unintended behavioral changes (semantic errors). @@ -79,23 +79,23 @@ Two library versions are **Binary Compatible** with each other if the compiled b ### Relationship between source and binary compatibility While breaking source compatibility often results in binary incompatibilities as well, they are actually orthogonal -- breaking one does not imply breaking the other. -#### Forwards and Backwards Compatibility +#### Forward and Backward Compatibility There are two "directions" when we describe compatibility of a library release: -**Backwards Compatible** means that a newer library version can be used in an environment where an older version is expected. When talking about binary and source compatibility, +**Backward Compatible** means that a newer library version can be used in an environment where an older version is expected. When talking about binary and source compatibility, this is the common and implied direction. -**Forwards Compatible** means that an older library can be used in an environment where a newer version is expected. +**Forward Compatible** means that an older library can be used in an environment where a newer version is expected. Forward compatibility is generally not upheld for libraries. Let's look at an example where library `A v1.0.0` is compiled with library `C v1.1.0`. -![Forwards and Backwards Compatibility]({{ site.baseurl }}/resources/images/library-author-guide/fowards_backwards_compatibility.png){: style="width: 65%; margin: auto; display: block"} +![Forward and Backward Compatibility]({{ site.baseurl }}/resources/images/library-author-guide/forward_backward_compatibility.png){: style="width: 65%; margin: auto; display: block"} `C v1.1.0 ` is **Forwards Binary Compatible** with `v1.0.0` if we can use `v1.0.0`'s JAR at runtime instead of `v1.1.0`'s JAR without any linkage errors. -`C v1.2.0 ` is **Backwards Binary Compatible** with `v1.1.0` if we can use `v1.2.0`'s JAR at runtime instead of `v1.1.0`'s JAR without any linkage errors. +`C v1.2.0 ` is **Backward Binary Compatible** with `v1.1.0` if we can use `v1.2.0`'s JAR at runtime instead of `v1.1.0`'s JAR without any linkage errors. ## Why binary compatibility matters @@ -115,7 +115,7 @@ Our application `App` depends on library `A` and `B`. Both `A` and `B` depends o ![Initial dependency graph]({{ site.baseurl }}/resources/images/library-author-guide/before_update.png){: style="width: 50%; margin: auto; display: block;"} -Sometime later, we see `B v1.1.0` is available and upgrade its version in our build. Our code compiles and seems to work so we push it to production and go home for dinner. +Sometime later, we see `B v1.1.0` is available and upgrade its version in our build. Our code compiles and seems to work, so we push it to production and go home for dinner. Unfortunately at 2am, we get frantic calls from customers saying that our application is broken! Looking at the logs, you find lots of `NoSuchMethodError` are being thrown by some code in `A`! @@ -143,11 +143,11 @@ How can we, as library authors, spare our users of runtime errors and dependency ## MiMa - Checking binary compatibility against previous library versions -The [Migration Manager for Scala](https://github.com/lightbend/migration-manager) (MiMa) is a tool for diagnosing binary incompatibilities between different library versions. +[MiMa](https://github.com/lightbend/mima) is a tool for diagnosing binary incompatibilities between different library versions. It works by comparing the class files of two provided JARs and report any binary incompatibilities found. Both backwards and forwards binary incompatibility can be detected by swapping input order of the JARs. -By incorporating MiMa's [sbt plugin](https://github.com/lightbend/migration-manager/wiki/sbt-plugin) into your sbt build, you can easily check whether +By incorporating MiMa's [sbt plugin](https://github.com/lightbend/mima#sbt) into your sbt build, you can easily check whether you have accidentally introduced binary incompatible changes. Detailed instruction on how to use the sbt plugin can be found in the link. We strongly encourage every library author to incorporate MiMa into their continuous integration and release workflow. @@ -171,11 +171,188 @@ in library releases: You can find detailed explanations, runnable examples and tips to maintain binary compatibility in [Binary Compatibility Code Examples & Explanation](https://github.com/jatcwang/binary-compatibility-guide). -Again, we recommend using MiMa to double check that you have not broken binary compatibility after making changes. +Again, we recommend using MiMa to double-check that you have not broken binary compatibility after making changes. + +### Changing a case class definition in a backwards-compatible manner + +Sometimes, it is desirable to change the definition of a case class (adding and/or removing fields) while still staying backwards-compatible with the existing usage of the case class, i.e. not breaking the so-called _binary compatibility_. The first question you should ask yourself is “do you need a _case_ class?” (as opposed to a regular class, which can be easier to evolve in a binary compatible way). A good reason for using a case class is when you need a structural implementation of `equals` and `hashCode`. + +To achieve that, follow this pattern: + * make the primary constructor private (this makes the `copy` method of the class private as well) + * define a private `unapply` function in the companion object (note that by doing that the case class loses the ability to be used as an extractor in match expressions) + * for all the fields, define `withXXX` methods on the case class that create a new instance with the respective field changed (you can use the private `copy` method to implement them) + * create a public constructor by defining an `apply` method in the companion object (it can use the private constructor) + * in Scala 2, you have to add the compiler option `-Xsource:3` + +Example: + +{% tabs case_class_compat_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} +~~~ scala +// Mark the primary constructor as private +case class Person private (name: String, age: Int) { + // Create withXxx methods for every field, implemented by using the (private) copy method + def withName(name: String): Person = copy(name = name) + def withAge(age: Int): Person = copy(age = age) +} + +object Person { + // Create a public constructor (which uses the private primary constructor) + def apply(name: String, age: Int) = new Person(name, age) + // Make the extractor private + private def unapply(p: Person): Some[Person] = Some(p) +} +~~~ +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// Mark the primary constructor as private +case class Person private (name: String, age: Int): + // Create withXxx methods for every field, implemented by using the (private) copy method + def withName(name: String): Person = copy(name = name) + def withAge(age: Int): Person = copy(age = age) + +object Person: + // Create a public constructor (which uses the private primary constructor) + def apply(name: String, age: Int): Person = new Person(name, age) + // Make the extractor private + private def unapply(p: Person) = p +``` +{% endtab %} +{% endtabs %} +This class can be published in a library and used as follows: + +{% tabs case_class_compat_2 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +// Create a new instance +val alice = Person("Alice", 42) +// Transform an instance +println(alice.withAge(alice.age + 1)) // Person(Alice, 43) +~~~ +{% endtab %} +{% endtabs %} + +If you try to use `Person` as an extractor in a match expression, it will fail with a message like “method unapply cannot be accessed as a member of Person.type”. Instead, you can use it as a typed pattern: + +{% tabs case_class_compat_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} +~~~ scala +alice match { + case person: Person => person.name +} +~~~ +{% endtab %} +{% tab 'Scala 3' %} +~~~ scala +alice match + case person: Person => person.name +~~~ +{% endtab %} +{% endtabs %} + +Later in time, you can amend the original case class definition to, say, add an optional `address` field. You + * add a new field `address` and a custom `withAddress` method, + * update the public `apply` method in the companion object to initialize all the fields, + * tell MiMa to [ignore](https://github.com/lightbend/mima#filtering-binary-incompatibilities) changes to the class constructor. This step is necessary because MiMa does not yet ignore changes in private class constructor signatures (see [#738](https://github.com/lightbend/mima/issues/738)). + +{% tabs case_class_compat_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} +~~~ scala +case class Person private (name: String, age: Int, address: Option[String]) { + ... + def withAddress(address: Option[String]) = copy(address = address) +} + +object Person { + // Update the public constructor to also initialize the address field + def apply(name: String, age: Int): Person = new Person(name, age, None) +} +~~~ +{% endtab %} +{% tab 'Scala 3' %} +```scala +case class Person private (name: String, age: Int, address: Option[String]): + ... + def withAddress(address: Option[String]) = copy(address = address) + +object Person: + // Update the public constructor to also initialize the address field + def apply(name: String, age: Int): Person = new Person(name, age, None) +``` +{% endtab %} +{% endtabs %} + +And, in your build definition: + +{% tabs case_class_compat_5 %} +{% tab 'sbt' %} +~~~ scala +import com.typesafe.tools.mima.core._ +mimaBinaryIssueFilters += ProblemFilters.exclude[DirectMissingMethodProblem]("Person.this") +~~~ +{% endtab %} +{% endtabs %} + +Otherwise, MiMa would fail with an error like “method this(java.lang.String,Int)Unit in class Person does not have a correspondent in current version”. + +> Note that an alternative solution, instead of adding a MiMa exclusion filter, consists of adding back the previous +> constructor signatures as secondary constructors: +> ~~~ scala +> case class Person private (name: String, age: Int, address: Option[String]): +> ... +> // Add back the former primary constructor signature +> private[Person] def this(name: String, age: Int) = this(name, age, None) +> ~~~ + +The original users can use the case class `Person` as before, all the methods that existed before are present unmodified after this change, thus the compatibility with the existing usage is maintained. + +The new field `address` can be used as follows: + +{% tabs case_class_compat_6 %} +{% tab 'Scala 2 and 3' %} +~~~ scala +// The public constructor sets the address to None by default. +// To set the address, we call withAddress: +val bob = Person("Bob", 21).withAddress(Some("Atlantic ocean")) +println(bob.address) +~~~ +{% endtab %} +{% endtabs %} + +A regular case class not following this pattern would break its usage, because by adding a new field changes some methods (which could be used by somebody else), for example `copy` or the constructor itself. + +Optionally, you can also add overloads of the `apply` method in the companion object to initialize more fields +in one call. In our example, we can add an overload that also initializes the `address` field: + +{% tabs case_class_compat_7 class=tabs-scala-version %} +{% tab 'Scala 2' %} +~~~ scala +object Person { + // Original public constructor + def apply(name: String, age: Int): Person = new Person(name, age, None) + // Additional constructor that also sets the address + def apply(name: String, age: Int, address: String): Person = + new Person(name, age, Some(address)) +} +~~~ +{% endtab %} +{% tab 'Scala 3' %} +~~~ scala +object Person: + // Original public constructor + def apply(name: String, age: Int): Person = new Person(name, age, None) + // Additional constructor that also sets the address + def apply(name: String, age: Int, address: String): Person = + new Person(name, age, Some(address)) +~~~ +{% endtab %} +{% endtabs %} ## Versioning Scheme - Communicating compatibility breakages -Library authors use versioning schemes to communicate compatibility guarantees between library releases to their users. Versioning schemes like [Semantic Versioning](http://semver.org/)(SemVer) allow +Library authors use versioning schemes to communicate compatibility guarantees between library releases to their users. Versioning schemes like [Semantic Versioning](https://semver.org/) (SemVer) allow users to easily reason about the impact of updating a library, without needing to read the detailed release notes. In the following section, we will outline a versioning scheme based on Semantic Versioning that we **strongly encourage** you to adopt for your libraries. The rules listed below are **in addition** to @@ -183,12 +360,16 @@ Semantic Versioning v2.0.0. ### Recommended Versioning Scheme -* If backward **binary compatibility** is broken, **major version number** must be increased. -* If backward **source compatibility** is broken, **minor version number** must be increased. -* A change in **patch version number** signals **neither binary nor source incompatibility**. +Given a version number MAJOR.MINOR.PATCH, you MUST increment the: + +1. MAJOR version if backward **binary compatibility** is broken, +2. MINOR version if backward **source compatibility** is broken, and +3. PATCH version to signal **neither binary nor source incompatibility**. + According to SemVer, patch versions should contain only bug fixes that fix incorrect behavior so major behavioral change in method/classes should result in a minor version bump. -* When major version is `0`, a minor version bump **may contain both source and binary breakages**. + +* When the major version is `0`, a minor version bump **may contain both source and binary breakages**. Some examples: @@ -200,7 +381,7 @@ Some examples: End users and library maintainers need to update all their dependency graph to remove all dependency on `v0.4.0`. * `v0.4.0 -> v0.4.1` is binary compatible. Classpath can safely contain both `v0.4.0` and `v0.4.1`. End user may need to fix minor source breaking changes introduced -Many libraries in the Scala ecosystem has adopted this versioning scheme. A few examples are [Akka](http://doc.akka.io/docs/akka/2.5/scala/common/binary-compatibility-rules.html), +Many libraries in the Scala ecosystem has adopted this versioning scheme. A few examples are [Akka](https://doc.akka.io/docs/akka/2.5/scala/common/binary-compatibility-rules.html), [Cats](https://github.com/typelevel/cats#binary-compatibility-and-versioning) and [Scala.js](https://www.scala-js.org/). ## Conclusion diff --git a/_overviews/tutorials/partest-guide.md b/_overviews/tutorials/partest-guide.md new file mode 100644 index 0000000000..a5542ad9a4 --- /dev/null +++ b/_overviews/tutorials/partest-guide.md @@ -0,0 +1,5 @@ +--- +sitemap: false +permalink: /tutorials/partest-guide.html +redirect_to: https://github.com/scala/scala-partest +--- diff --git a/_overviews/tutorials/scala-for-csharp-programmers.disabled.html b/_overviews/tutorials/scala-for-csharp-programmers.disabled.html index 593f74779e..6dfc4969ec 100644 --- a/_overviews/tutorials/scala-for-csharp-programmers.disabled.html +++ b/_overviews/tutorials/scala-for-csharp-programmers.disabled.html @@ -1,18 +1,16 @@ --- -layout: overview +layout: singlepage-overview title: A Scala Tutorial for C# Programmers - -discourse: true --- By Ivan Towlson ## Introduction -Scala is a hybrid of functional and object-oriented languages. -Its functional aspects make it very expressive when writing algorithmic -code, and play nicely with the brave new world of concurrency; its -object-oriented aspects keep it familiar and convenient when creating +Scala is a hybrid of functional and object-oriented languages. +Its functional aspects make it very expressive when writing algorithmic +code, and play nicely with the brave new world of concurrency; its +object-oriented aspects keep it familiar and convenient when creating business objects or other stateful models. ## The same concepts @@ -111,9 +109,9 @@ You can see the same principle in action for the return type of the function. `reticulate` returns a `String`. -Finally, the body of the method has been placed after an equals sign, -rather than inside braces. (Braces are only necessary when the method -body consists of multiple expressions/statements.) What's more, +Finally, the body of the method has been placed after an equals sign, +rather than inside braces. (Braces are only necessary when the method +body consists of multiple expressions/statements.) What's more, the body of the method is an expression -- that is, something with a value -- rather than a set of statements amongst which is a `return`. I'll come back to this when we look at a more realistic @@ -141,7 +139,7 @@ ### Base Types Scala's base types are pretty much the same as C#'s, except that they -are named with initial capitals, e.g. `Int` instead of `int`. (In fact +are named with initial capitals, e.g. `Int` instead of `int`. (In fact every type in Scala starts with an uppercase letter.) There are no unsigned variants, and booleans are called `Boolean` instead of `bool`. @@ -156,8 +154,8 @@ Scala has the same concept, but the function types are built into the language, rather than being library types. Function types are -spelled `(T1, T2, ...) => TR`. For example, a predicate of integers -would be type `(Int) => Boolean`. If there is only one input type, +spelled `(T1, T2, ...) => TR`. For example, a predicate of integers +would be type `(Int) => Boolean`. If there is only one input type, the parens can be left out like this: `Int => Boolean`. Effectively, Scala gets rid of all those weird custom delegate types @@ -222,7 +220,7 @@ ### Tuples -Everybody hates out parameters. We all know that code like this just +Everybody hates out parameters. We all know that code like this just isn't nice: Widget widget; @@ -231,21 +229,21 @@ widget.ReticulateSplines(); } -And once you start composing higher-level functions into the mix, it gets -positively nasty. Suppose I want to make a HTTP request. Well, that's -going to produce two outputs in itself, the success code and the response -data. But now suppose I want to time it. Writing the timing code isn't a -problem, but now I have *three* outputs, and to paraphrase *Was Not Was*, +And once you start composing higher-level functions into the mix, it gets +positively nasty. Suppose I want to make a HTTP request. Well, that's +going to produce two outputs in itself, the success code and the response +data. But now suppose I want to time it. Writing the timing code isn't a +problem, but now I have *three* outputs, and to paraphrase *Was Not Was*, I feel worse than Jamie Zawinski. -You can get around this in specific situations by creating custom types -like `DictionaryLookupResult` or `TimedHttpRequestResult`, but eventually +You can get around this in specific situations by creating custom types +like `DictionaryLookupResult` or `TimedHttpRequestResult`, but eventually the terrible allure wears off, and you just want it to work. -Enter tuples. A tuple is just a small number of values -- a single value, -a pair of values, a triplet of values, that sort of thing. You can tell -that tuples were named by mathematicians because the name only makes sense -when you look at the cases you hardly ever use (quadruple, quintuple, +Enter tuples. A tuple is just a small number of values -- a single value, +a pair of values, a triplet of values, that sort of thing. You can tell +that tuples were named by mathematicians because the name only makes sense +when you look at the cases you hardly ever use (quadruple, quintuple, sextuple, etc.). Using tuples, our timed HTTP request might look like this: public Tuple Time(Func> action) @@ -255,27 +253,27 @@ TimeSpan howLong = StopTimer(); return Tuple.Create(result.First, result.Second, howLong); } - + var result = Time(() => MakeRequest(uri)); var succeeded = result.First; var response = result.Second; var howLong = result.Third. Console.WriteLine("it took " + howLong); -The reason this keeps getting verbose on us is that C# doesn’t provide any -syntatical support for tuples. To C#, a `Tuple<>` is just another generic -type. To us, the readers, a `Tuple<>` is just another generic type with +The reason this keeps getting verbose on us is that C# doesn’t provide any +syntatical support for tuples. To C#, a `Tuple<>` is just another generic +type. To us, the readers, a `Tuple<>` is just another generic type with particularly unhelpful member names. -Really, what we're really trying to articulate by returning a `Tuple<>` is, -"this method has several outputs." So what do we want to do with those -outputs? We want to access them, for example to stash them in variables, -without having to construct and pick apart the tuple one value at a time. -That means the language has to provide some kind of syntax-level support -for tuples, instead of treating them like every other class the compiler +Really, what we're really trying to articulate by returning a `Tuple<>` is, +"this method has several outputs." So what do we want to do with those +outputs? We want to access them, for example to stash them in variables, +without having to construct and pick apart the tuple one value at a time. +That means the language has to provide some kind of syntax-level support +for tuples, instead of treating them like every other class the compiler doesn’t know about. -Many functional languages have exactly this kind of syntactical support, +Many functional languages have exactly this kind of syntactical support, and Scala is no exception. Here’s how the above pseudo-C# looks in Scala: def time(action: => (Boolean, Stream)): (Boolean, Stream, TimeSpan) = { @@ -283,23 +281,23 @@ val (succeeded, response) = action (succeeded, response, stopTimer()) } - + val (succeeded, response, timeTaken) = time(makeRequest) Console.WriteLine("it took " + timeTaken) -Notice the multiple variables on the left hand side of the time call? -Notice the `(Boolean, Stream, TimeSpan)` return type of the time method? -That return value is effectively a tuple type, but instead of having to -capture the returned tuple in a `Tuple<>` variable and extract its various -bits by hand, we are getting the Scala compiler to (in the time function) -compose the tuple implicitly for us, without us having to write the -constructor call, and (in the calling code) unpick the tuple into -meaningful, named variables for us without us having to explicitly copy +Notice the multiple variables on the left hand side of the time call? +Notice the `(Boolean, Stream, TimeSpan)` return type of the time method? +That return value is effectively a tuple type, but instead of having to +capture the returned tuple in a `Tuple<>` variable and extract its various +bits by hand, we are getting the Scala compiler to (in the time function) +compose the tuple implicitly for us, without us having to write the +constructor call, and (in the calling code) unpick the tuple into +meaningful, named variables for us without us having to explicitly copy the values one by one and by name. -(By the way, a proper implementation of the `time()` method wouldn’t be -restricted to `(Boolean, Stream)` results: we’d be looking to write a -method that could time anything. I’ve skipped that because it would +(By the way, a proper implementation of the `time()` method wouldn’t be +restricted to `(Boolean, Stream)` results: we’d be looking to write a +method that could time anything. I’ve skipped that because it would distract from the point at hand.) How would this play with the dictionary example? @@ -308,60 +306,60 @@ if (found) widget.reticulateSplines() -We don’t actually save any lines of code, what with having to now capture -the “found” value into a variable and test it separately; and it’s not as -if the original C# version was horribly unreadable anyway. So maybe this is -a matter of taste, but I find this a lot easier to read and to write: all -the outputs are on the left of the equals sign where they belong, instead -of being spread between the assignment result and the parameter list, and +We don’t actually save any lines of code, what with having to now capture +the “found” value into a variable and test it separately; and it’s not as +if the original C# version was horribly unreadable anyway. So maybe this is +a matter of taste, but I find this a lot easier to read and to write: all +the outputs are on the left of the equals sign where they belong, instead +of being spread between the assignment result and the parameter list, and we don’t have that odd Widget declaration at the top. ## New and different concepts -Scala's primary platform is the Java virtual machine, and some of the -interest in Scala comes from Java programmers' interest in features such -as type inference, comprehensions and lambdas, with which C# programmers -are already familiar. So what's left that might be of interest +Scala's primary platform is the Java virtual machine, and some of the +interest in Scala comes from Java programmers' interest in features such +as type inference, comprehensions and lambdas, with which C# programmers +are already familiar. So what's left that might be of interest specifically to C# programmers? ### Mixins and Traits #### Motivation -Interfaces in C# and Java play a dual role. -First, they are a set of capabilities that an implementer has to, well, -implement. Second, they are a feature set that a client can use. +Interfaces in C# and Java play a dual role. +First, they are a set of capabilities that an implementer has to, well, +implement. Second, they are a feature set that a client can use. -These two roles can be conflicting: The first means that interfaces want -to be minimal, so that implementers don't have to implement a whole lot -of superfluous and redundant guff. The second means that interfaces want -to be maximal, so that clients don't have to clog themselves up with +These two roles can be conflicting: The first means that interfaces want +to be minimal, so that implementers don't have to implement a whole lot +of superfluous and redundant guff. The second means that interfaces want +to be maximal, so that clients don't have to clog themselves up with boilerplate utility methods. Consider, for example, `IEnumerable` (and its sister interface `IEnumerator`). -This is a very minimal interface: implementers just need to be able to -produce values in sequence. But this minimalism means that clients of -`IEnumerable` need to write the same old boilerplate again and again and -again: foreach loops to filter, foreach loops to call a method on each -element of the sequence, foreach loops to aggregate, foreach loops to -check whether all elements meet a criterion, or to find the first member -that meets a criterion, or... - -This is frustrating because the implementations of "filter," "apply", -"aggregate," and so on are always the same. Of course, we could put -these methods into concrete types (`List` includes several), but then -those concrete types will contain duplicate code, and users who only have -an `IEnumerable` will still miss out. And yet we can't put these methods -into the interface because then every implementer of `IEnumerable` would -have to implement them -- and they'd end up writing the same boilerplate, +This is a very minimal interface: implementers just need to be able to +produce values in sequence. But this minimalism means that clients of +`IEnumerable` need to write the same old boilerplate again and again and +again: foreach loops to filter, foreach loops to call a method on each +element of the sequence, foreach loops to aggregate, foreach loops to +check whether all elements meet a criterion, or to find the first member +that meets a criterion, or... + +This is frustrating because the implementations of "filter," "apply", +"aggregate," and so on are always the same. Of course, we could put +these methods into concrete types (`List` includes several), but then +those concrete types will contain duplicate code, and users who only have +an `IEnumerable` will still miss out. And yet we can't put these methods +into the interface because then every implementer of `IEnumerable` would +have to implement them -- and they'd end up writing the same boilerplate, just now in all the zillions of `IEnumerable` classes instead of their clients. #### The C# and Scala Solutions -We could resolve this tension if we had a way for interfaces to contain -implementation: for example, if `IEnumerable` required the implementer -to provide the class-specific iteration functionality, but then provided -the standard implementations of "filter," "apply", "aggregate" and so on +We could resolve this tension if we had a way for interfaces to contain +implementation: for example, if `IEnumerable` required the implementer +to provide the class-specific iteration functionality, but then provided +the standard implementations of "filter," "apply", "aggregate" and so on automatically: public pseudo_interface IEnumerable @@ -375,24 +373,24 @@ } } -C# 3 addresses this using extension methods: the methods mentioned above -are all in fact included as extension methods on `IEnumerable` as -part of LINQ. +C# 3 addresses this using extension methods: the methods mentioned above +are all in fact included as extension methods on `IEnumerable` as +part of LINQ. -This has some advantages over the approach described above: specifically, -the "standard methods" aren't bound up in the interface, so you can add -your own methods instead of being limited to the ones that the interface +This has some advantages over the approach described above: specifically, +the "standard methods" aren't bound up in the interface, so you can add +your own methods instead of being limited to the ones that the interface author has included. -On the other hand, it means that method implementations have to be packaged +On the other hand, it means that method implementations have to be packaged in a different class from the interface, which feels less than modular. -Scala takes a different approach. A Scala trait can contain a mix of -abstract methods without implementation as well as concrete methods with -an implementation. (It can also be a pure interface, with only abstract +Scala takes a different approach. A Scala trait can contain a mix of +abstract methods without implementation as well as concrete methods with +an implementation. (It can also be a pure interface, with only abstract members.) -Here's a Scala trait that represents objects that can be compared +Here's a Scala trait that represents objects that can be compared and ordered: trait Ord { @@ -402,14 +400,14 @@ def >=(that: Any): Boolean = !(this < that) } -Orderable objects can extend `Ord`, but only need to implement the -method `<`. They then get the other operators for free, implemented +Orderable objects can extend `Ord`, but only need to implement the +method `<`. They then get the other operators for free, implemented automatically by Ord in terms of `<`. class Date extends Ord { def < (that: Any): Boolean = /* implementation */ } - + // can now write: myDate >= yourDate A similar trait, called `Ordered` already exists in Scala, so there is no @@ -417,13 +415,13 @@ #### Scala Traits vs. C# Extension Methods -Okay, so Scala has a different way of packaging standard implementations -from C#'s extension methods. It's different, but why is it interesting? -Well, there are a couple of things that you can do with Scala traits that +Okay, so Scala has a different way of packaging standard implementations +from C#'s extension methods. It's different, but why is it interesting? +Well, there are a couple of things that you can do with Scala traits that don't fall nicely out of the extension methods approach. -First, you can override the default implementations of trait members, -to take advantage of additional information or capabilities available +First, you can override the default implementations of trait members, +to take advantage of additional information or capabilities available in the implementing type. Let's look at another `IEnumerable` example, recast as a Scala trait: @@ -439,12 +437,12 @@ } } -This (ignoring style issues for now) is the only fully general -implementation we can provide for count: it will work with any `Enumerable`. -But for collections that know their sizes, such as `arrays` or `List`, -it's gruesomely inefficient. It iterates over the entire collection, -counting elements one by one, when it could just consult the `size` member -and return that. +This (ignoring style issues for now) is the only fully general +implementation we can provide for count: it will work with any `Enumerable`. +But for collections that know their sizes, such as `arrays` or `List`, +it's gruesomely inefficient. It iterates over the entire collection, +counting elements one by one, when it could just consult the `size` member +and return that. Let's fix that: @@ -454,68 +452,68 @@ override def count: Int = _size } -The `count` member of the `Enumerable` trait works like a virtual method: +The `count` member of the `Enumerable` trait works like a virtual method: it can be overridden in classes which implement/derive from `Enumerable`. -Compare this to the `Count()` extension method on `IEnumerable` in LINQ. -This achieves the same effect by trying to cast to `ICollection`, which is -fine as far as it goes but isn't extensible. +Compare this to the `Count()` extension method on `IEnumerable` in LINQ. +This achieves the same effect by trying to cast to `ICollection`, which is +fine as far as it goes but isn't extensible. -Suppose you create an enumerable class that can count itself quickly but -isn't a collection -- for example a natural numbers range object. -With a Scala trait, the `NumberRange` type could provide an efficient -override of `count`, just like any other virtual method; with C# extension -methods, `Enumerable.Count()` would have to somehow know about the +Suppose you create an enumerable class that can count itself quickly but +isn't a collection -- for example a natural numbers range object. +With a Scala trait, the `NumberRange` type could provide an efficient +override of `count`, just like any other virtual method; with C# extension +methods, `Enumerable.Count()` would have to somehow know about the `NumberRange` type in advance, or fall back on counting elements one by one. -Second, with Scala you can choose a trait implementation when you -instantiate an object, rather than having it baked in at the class level +Second, with Scala you can choose a trait implementation when you +instantiate an object, rather than having it baked in at the class level once and for all. This is called mixin-composition. -Suppose you're creating a `MyList` instance, but you want it to puff itself -up to look bigger so as to frighten other `MyList` instances off its territory. -(This example would probably work better with fish, but we're stuck with -`Enumerable`s now. Work with me here.) In C#, you'd need to create a -`PuffedUpMyList` class and override the `Count` property. +Suppose you're creating a `MyList` instance, but you want it to puff itself +up to look bigger so as to frighten other `MyList` instances off its territory. +(This example would probably work better with fish, but we're stuck with +`Enumerable`s now. Work with me here.) In C#, you'd need to create a +`PuffedUpMyList` class and override the `Count` property. In Scala, you can just mix in a `PuffedUp` version of the trait: trait PuffedUp extends Enumerable { override def count: Int = super.count + 100 } - + val normal = new MyList Console.WriteLine(normal.count) // meh val puffedUp = new MyList with PuffedUp Console.WriteLine(puffedUp.count) // eek! -As you can imagine this gives us much better granularity and composability -of traits and implementations than we get from the extension methods -approach, or indeed from single implementation inheritance type systems +As you can imagine this gives us much better granularity and composability +of traits and implementations than we get from the extension methods +approach, or indeed from single implementation inheritance type systems in general. -So Scala traits have some distinct advantages over extension methods. -The only downside appears to be the inability for clients to add their -own methods to a trait after the fact. +So Scala traits have some distinct advantages over extension methods. +The only downside appears to be the inability for clients to add their +own methods to a trait after the fact. -Fortunately, you can work around this in Scala using so-called implicit +Fortunately, you can work around this in Scala using so-called implicit conversions. They enable Scala programmers to enrich existing types with new functionality. ### Singletons -In C#, if you want to create a singleton object, you have to create a class, -then stop evildoers creating their own instances of that class, then create +In C#, if you want to create a singleton object, you have to create a class, +then stop evildoers creating their own instances of that class, then create and provide an instance of that class yourself. -While this is hardly a Burma Railway of the programming craft, it does -feel like pushing against the grain of the language. Nor is it great for -maintainers, who have to be able to recognise a singleton by its pattern -(private constructor, public static readonly field, ...), or for clients, -who have to use a slightly clumsy multipart syntax to refer to the +While this is hardly a Burma Railway of the programming craft, it does +feel like pushing against the grain of the language. Nor is it great for +maintainers, who have to be able to recognise a singleton by its pattern +(private constructor, public static readonly field, ...), or for clients, +who have to use a slightly clumsy multipart syntax to refer to the singleton (e.g. `Universe.Instance`). -What would be easier for all concerned would be if you could just declare -objects *as* singletons. That is, instead of writing class `Universe` and a +What would be easier for all concerned would be if you could just declare +objects *as* singletons. That is, instead of writing class `Universe` and a `public static readonly` instance of it, you could just write `object Universe`. And that's exactly what Scala allows you to do: @@ -523,99 +521,99 @@ object Universe { def contains(obj: Any): Boolean = true } - + val v = Universe.contains(42) -What's going on behind the scenes here? It pretty much goes without saying -that the Scala compiler is creating a new type for the singleton object. -In fact it creates two types, one for the implementation and one for the -interface. The interface looks like a .NET static class (actually, the -.NET 1.x equivalent, a sealed class with only static members). +What's going on behind the scenes here? It pretty much goes without saying +that the Scala compiler is creating a new type for the singleton object. +In fact it creates two types, one for the implementation and one for the +interface. The interface looks like a .NET static class (actually, the +.NET 1.x equivalent, a sealed class with only static members). Thus, a C# program would call the example above as `Universe.contains(42)`. -Singleton objects are first-class citizens in Scala, so they can for -example derive from classes. This is a nice way of creating special values -with custom behaviour: you don't need to create a whole new type, you just +Singleton objects are first-class citizens in Scala, so they can for +example derive from classes. This is a nice way of creating special values +with custom behaviour: you don't need to create a whole new type, you just define an instance and override methods in it: abstract class Cat { def humiliateSelf() } - + object Slats extends Cat { def humiliateSelf() { savage(this.tail) } } -Obviously this is a frivolous example, but "special singletons" turn out to -be an important part of the functional idiom, for example for bottoming out -recursion. *Scala by Example (PDF)* describes an implementation of a Set class -which is implemented as a tree-like structure ("left subset - member - right -subset"), and methods such as `contains()` work by recursing down to the -child sets. For this to work requires an `EmptySet` whose implementation -(state) and behaviour are quite different from non-empty sets -- e.g. -`contains()` just returns `false` instead of trying to delegate to -non-existent child sets. Since `EmptySet` is logically unique it is both -simpler and more efficient to represent it as a singleton: i.e. to declare +Obviously this is a frivolous example, but "special singletons" turn out to +be an important part of the functional idiom, for example for bottoming out +recursion. *Scala by Example (PDF)* describes an implementation of a Set class +which is implemented as a tree-like structure ("left subset - member - right +subset"), and methods such as `contains()` work by recursing down to the +child sets. For this to work requires an `EmptySet` whose implementation +(state) and behaviour are quite different from non-empty sets -- e.g. +`contains()` just returns `false` instead of trying to delegate to +non-existent child sets. Since `EmptySet` is logically unique it is both +simpler and more efficient to represent it as a singleton: i.e. to declare `object EmptySet` instead of `class EmptySet`. -In fact the whole thing can become alarmingly deep: *Scala by Example* -also includes a description of `Boolean` as an `abstract class`, and -`True` and `False` as singleton objects which extend `Boolean` and provide -appropriate implementations of the `ifThenElse` method. +In fact the whole thing can become alarmingly deep: *Scala by Example* +also includes a description of `Boolean` as an `abstract class`, and +`True` and `False` as singleton objects which extend `Boolean` and provide +appropriate implementations of the `ifThenElse` method. -And fans of Giuseppe Peano should definitely check out the hypothetical +And fans of Giuseppe Peano should definitely check out the hypothetical implementation of `Int`... ### Pass by Name -> You're only on chapter 3 and you're already reduced to writing about -> *calling conventions*? You suck! Do another post about chimney sweeps +> You're only on chapter 3 and you're already reduced to writing about +> *calling conventions*? You suck! Do another post about chimney sweeps > being hunted by jars of marmalade!" -Silence, cur. Pass by name is not as other calling conventions are. -Pass by name, especially in conjunction with some other rather -theoretical-sounding Scala features, is your gateway to the wonderful +Silence, cur. Pass by name is not as other calling conventions are. +Pass by name, especially in conjunction with some other rather +theoretical-sounding Scala features, is your gateway to the wonderful world of language extensibility. #### What is Passing By Name? -First, let's talk about what we mean by *calling convention*. A calling -convention describes how stuff gets passed to a method by its caller. -In the good old days, this used to mean exciting things like which -arguments got passed in registers and who was responsible for resetting -the stack pointer. Sadly, the days of being able to refer to "naked fun -calls" are consigned to history: In modern managed environments, the -runtime takes care of all this guff and the main distinction is pass -data by value or by reference. (The situation on the CLR is slightly -complicated by the need to differentiate passing values by value, values -by reference, references by value and references by reference, but I'm -not going to go into that because (a) it's irrelevant to the subject at -hand and (b) that's -[Jon Skeet](http://www.yoda.arachsys.com/csharp/parameters.html)'s turf +First, let's talk about what we mean by *calling convention*. A calling +convention describes how stuff gets passed to a method by its caller. +In the good old days, this used to mean exciting things like which +arguments got passed in registers and who was responsible for resetting +the stack pointer. Sadly, the days of being able to refer to "naked fun +calls" are consigned to history: In modern managed environments, the +runtime takes care of all this guff and the main distinction is pass +data by value or by reference. (The situation on the CLR is slightly +complicated by the need to differentiate passing values by value, values +by reference, references by value and references by reference, but I'm +not going to go into that because (a) it's irrelevant to the subject at +hand and (b) that's +[Jon Skeet](http://www.yoda.arachsys.com/csharp/parameters.html)'s turf and I don't want him to shank me. Again.) -In *pass by value*, the called method gets a copy of whatever the caller -passed in. Arguments passed by value therefore work like local variables -that are initialised before the method runs: when you do anything to them, +In *pass by value*, the called method gets a copy of whatever the caller +passed in. Arguments passed by value therefore work like local variables +that are initialised before the method runs: when you do anything to them, you're doing it to your own copy. -In *pass by reference*, the called method gets a reference to the caller's -value. When you do anything to a pass-by-reference argument, you're doing -it to the caller's data. +In *pass by reference*, the called method gets a reference to the caller's +value. When you do anything to a pass-by-reference argument, you're doing +it to the caller's data. -In *pass by name*, the called method gets... well, it's a bit messy to -explain what the called method gets. But when the called method does -anything to the argument, the argument gets evaluated and the "anything" -is done to that. Crucially, evaluation happens every time the argument +In *pass by name*, the called method gets... well, it's a bit messy to +explain what the called method gets. But when the called method does +anything to the argument, the argument gets evaluated and the "anything" +is done to that. Crucially, evaluation happens every time the argument gets mentioned, and only when the argument gets mentioned. #### Not Just Another Calling Convention -Why does this matter? It matters because there are functions you can't -implement using pass by value or pass by reference, but you can implement +Why does this matter? It matters because there are functions you can't +implement using pass by value or pass by reference, but you can implement using pass by name. -Suppose, for example, that C# didn't have the `while` keyword. +Suppose, for example, that C# didn't have the `while` keyword. You'd probably want to write a method that did the job instead: public static void While(bool condition, Action body) @@ -632,30 +630,30 @@ long x = 0; While(x < 10, () => x = x + 1); -C# evaluates the arguments to `While` and invokes the `While` method with -the arguments `true` and `() => x = x + 1`. After watching the CPU sit -on 100% for a while you might check on the value of `x` and find it's -somewhere north of a trillion. *Why?* Because the condition argument was -*passed by value*, so whenever the `While` method tests the value of -condition, it's always `true`. The `While` method doesn't know that -condition originally came from the expression `x < 10`; all `While` knows +C# evaluates the arguments to `While` and invokes the `While` method with +the arguments `true` and `() => x = x + 1`. After watching the CPU sit +on 100% for a while you might check on the value of `x` and find it's +somewhere north of a trillion. *Why?* Because the condition argument was +*passed by value*, so whenever the `While` method tests the value of +condition, it's always `true`. The `While` method doesn't know that +condition originally came from the expression `x < 10`; all `While` knows is that condition is `true`. -For the `While` method to work, we need it to re-evaluate `x < 10` every -time it hits the condition argument. While needs not the value of the -argument at the call site, nor a reference to the argument at the call -site, but the actual expression that the caller wants it to use to generate +For the `While` method to work, we need it to re-evaluate `x < 10` every +time it hits the condition argument. While needs not the value of the +argument at the call site, nor a reference to the argument at the call +site, but the actual expression that the caller wants it to use to generate a value. -Same goes for short-circuit evaluation. If you want short-circuit -evaluation in C#, your only hope if to get on the blower to Anders +Same goes for short-circuit evaluation. If you want short-circuit +evaluation in C#, your only hope if to get on the blower to Anders Hejlsberg and persuade him to bake it into the language: bool result = (a > 0 && Math.Sqrt(a) < 10); double result = (a < 0 ? Math.Sqrt(-a) : Math.Sqrt(a)); -You can't write a function like `&&` or `?:` yourself, because C# will -always try to evaluate all the arguments before calling your function. +You can't write a function like `&&` or `?:` yourself, because C# will +always try to evaluate all the arguments before calling your function. Consider a VB exile who wants to reproduce his favourite keywords in C#: @@ -677,24 +675,24 @@ bool result = AndAlso(a > 0, Math.Sqrt(a) < 10); double result = IIf(a < 0, Math.Sqrt(-a), Math.Sqrt(a)); -it would try to evaluate all the arguments at the call site, and pass the -results of those evaluations to `AndAlso` or `IIf`. There's no -short-circuiting. So the `AndAlso` call would crash if a were negative, -and the `IIf` call if a were anything other than 0. Again, what you want is -for the `condition1`, `condition2`, `ifTrue` and `ifFalse` arguments to be -evaluated by the callee if it needs them, not for the caller to evaluate +it would try to evaluate all the arguments at the call site, and pass the +results of those evaluations to `AndAlso` or `IIf`. There's no +short-circuiting. So the `AndAlso` call would crash if a were negative, +and the `IIf` call if a were anything other than 0. Again, what you want is +for the `condition1`, `condition2`, `ifTrue` and `ifFalse` arguments to be +evaluated by the callee if it needs them, not for the caller to evaluate them before making the call. -And that's what *pass by name* does. A parameter passed by name is not -evaluated when it is passed to a method. It is evaluated -- and -re-evaluated -- when the called method evaluates the parameter; -specifically when the called method requests the value of the parameter by -mentioning its name. This might sound weird and academic, but it's the key +And that's what *pass by name* does. A parameter passed by name is not +evaluated when it is passed to a method. It is evaluated -- and +re-evaluated -- when the called method evaluates the parameter; +specifically when the called method requests the value of the parameter by +mentioning its name. This might sound weird and academic, but it's the key to being able to define your own control constructs. #### Using Pass By Name in Scala -Let's see the custom while implementation again, this time with Scala +Let's see the custom while implementation again, this time with Scala *pass by name* parameters: def myWhile(condition: => Boolean)(body: => Unit): Unit = @@ -711,26 +709,26 @@ i += 1 } -Unlike the C# attempt, this prints out the numbers from 0 to 9 and then +Unlike the C# attempt, this prints out the numbers from 0 to 9 and then terminates as you'd wish. Pass by name also works for short-circuiting: import math._ - + def andAlso(condition1: => Boolean, condition2: => Boolean): Boolean = condition1 && condition2 - + val d = -1.234 val result = andAlso(d > 0, sqrt(d) < 10) -The `andAlso` call returns `false` rather than crashing, because +The `andAlso` call returns `false` rather than crashing, because `sqrt(d) < 10` never gets evaluated. -What's going on here? What's the weird colon-and-pointy-sticks syntax? +What's going on here? What's the weird colon-and-pointy-sticks syntax? What is actually getting passed to `myWhile` and `andAlso` to make this work? -The answer is a bit surprising. Nothing is going on here. This is the +The answer is a bit surprising. Nothing is going on here. This is the normal Scala function parameter syntax. There is no *pass by name* in Scala. Here's a bog-standard *pass by value* Scala function declaration: @@ -741,9 +739,9 @@ def myFunc2(f: Int => Boolean): Unit = ... -Even if you've not seen this kind of expression before, it's probably not -too hard to guess what this means. This function takes a *function from -`Int` to `Boolean`* as its argument. In C# terms, +Even if you've not seen this kind of expression before, it's probably not +too hard to guess what this means. This function takes a *function from +`Int` to `Boolean`* as its argument. In C# terms, `void MyFunc2(Func f)`. We could call this as follows: myFunc2 { (i: Int) => i > 0 } @@ -752,46 +750,46 @@ def myFunc3(f: => Boolean) : Unit = ... -Well, if `myFunc2` took an *Int-to-Boolean* function, `myFunc3` must be -taking a "blank-to-Boolean" function -- a function that takes no arguments -and returns a `Boolean`. In short, a conditional expression. So we can +Well, if `myFunc2` took an *Int-to-Boolean* function, `myFunc3` must be +taking a "blank-to-Boolean" function -- a function that takes no arguments +and returns a `Boolean`. In short, a conditional expression. So we can call `myFunc3` as follows: val j = 123 myFunc3 { j > 0 } -The squirly brackets are what we'd expect from an anonymous function, and -because the function has no arguments Scala doesn't make us write -`{ () => j > 0 }`, even though that's what it means really. The anonymous -function has no arguments because `j` is a captured local variable, not an -argument to the function. But there's more. Scala also lets us call +The squirly brackets are what we'd expect from an anonymous function, and +because the function has no arguments Scala doesn't make us write +`{ () => j > 0 }`, even though that's what it means really. The anonymous +function has no arguments because `j` is a captured local variable, not an +argument to the function. But there's more. Scala also lets us call `myFunc3` like this: val j = 123 myFunc3(j > 0) -This is normal function call syntax, but the Scala compiler realises that -`myFunc3` expects a nullary function (a function with no arguments) rather -than a `Boolean`, and therefore treats `myFunc3(j > 0)` as shorthand for -`myFunc3(() => j > 0)`. This is the same kind of logic that the C# compiler -uses when it decides whether to compile a lambda expression to a delegate +This is normal function call syntax, but the Scala compiler realises that +`myFunc3` expects a nullary function (a function with no arguments) rather +than a `Boolean`, and therefore treats `myFunc3(j > 0)` as shorthand for +`myFunc3(() => j > 0)`. This is the same kind of logic that the C# compiler +uses when it decides whether to compile a lambda expression to a delegate or an expression tree. You can probably figure out where it goes from here: def myFunc4(f1: => Boolean)(f2: => Unit): Unit = ... -This takes two functions: a conditional expression, and a function that -takes no arguments and returns no value (in .NET terms, an `Action`). -Using our powers of anticipation, we can imagine how this might be called -using some unholy combination of the two syntaxes we saw for calling +This takes two functions: a conditional expression, and a function that +takes no arguments and returns no value (in .NET terms, an `Action`). +Using our powers of anticipation, we can imagine how this might be called +using some unholy combination of the two syntaxes we saw for calling `myFunc3`: val j = 123; myFunc4(j > 0) { println(j); j -= 1; } -We can mix and match the `()` and `{}` bracketing at whim, except that we -have to use `{}` bracketing if we want to batch up multiple expressions. +We can mix and match the `()` and `{}` bracketing at whim, except that we +have to use `{}` bracketing if we want to batch up multiple expressions. For example, you could legally equally well write the following: myFunc4 { j > 0 } { println(j); j -= 1; } @@ -806,9 +804,9 @@ myFunc5(f1)(f2) } -Written like this, it's clear that `f1` is getting evaluated each time we -execute the if statement, but is getting passed (as a function) when -`myFunc5` recurses. But Scala allows us to leave the parentheses off +Written like this, it's clear that `f1` is getting evaluated each time we +execute the if statement, but is getting passed (as a function) when +`myFunc5` recurses. But Scala allows us to leave the parentheses off function calls with no arguments, so we can write the above as: def myFunc5(f1: => Boolean)(f2: => Unit): Unit = @@ -817,18 +815,18 @@ myFunc5(f1)(f2) } -Again, type inference allows Scala to distinguish the *evaluation of -`f1`* in the if statement from the *passing of `f1`* in the `myFunc5` +Again, type inference allows Scala to distinguish the *evaluation of +`f1`* in the if statement from the *passing of `f1`* in the `myFunc5` recursion. -And with a bit of renaming, that's `myWhile`. There's no separate -*pass by name* convention: just the usual closure behaviour of capturing -local variables in an anonymous method or lambda, a bit of syntactic sugar -for nullary functions (functions with no arguments), just like C#'s -syntactic sugar for property getters, and the Scala compiler's ability to +And with a bit of renaming, that's `myWhile`. There's no separate +*pass by name* convention: just the usual closure behaviour of capturing +local variables in an anonymous method or lambda, a bit of syntactic sugar +for nullary functions (functions with no arguments), just like C#'s +syntactic sugar for property getters, and the Scala compiler's ability to recognise when a closure is required instead of a value. -In fact, armed with this understanding of the Scala "syntax," we can +In fact, armed with this understanding of the Scala "syntax," we can easily map it back to C#: void While(Func condition, Action body) @@ -839,7 +837,7 @@ While(condition, body); } } - + int i = 0; While(() => i < 10, () => { @@ -847,67 +845,67 @@ ++i; }); -The implementation of the `While` method in C# is, to my eyes, a bit -clearer than the Scala version. However, the syntax for *calling* the -`While` method in C# is clearly way more complicated and less natural than -the syntax for calling `myWhile` in Scala. Calling `myWhile` in Scala was -like using a native language construct. Calling While in C# required a -great deal of clutter at the call site to prevent C# from trying to treat +The implementation of the `While` method in C# is, to my eyes, a bit +clearer than the Scala version. However, the syntax for *calling* the +`While` method in C# is clearly way more complicated and less natural than +the syntax for calling `myWhile` in Scala. Calling `myWhile` in Scala was +like using a native language construct. Calling While in C# required a +great deal of clutter at the call site to prevent C# from trying to treat `i < 10` as a once-and-for-all value, and to express the body at all. -So that's so-called "pass by name" demystified: The Scala Web site, with -crushing mundanity, demotes it to "automatic type-dependent closure -construction," which is indeed exactly how it works. As we've seen, -however, this technical-sounding feature is actually essential to -creating nice syntax for your own control constructs. We'll shortly see -how this works together with other Scala features to give you even more +So that's so-called "pass by name" demystified: The Scala Web site, with +crushing mundanity, demotes it to "automatic type-dependent closure +construction," which is indeed exactly how it works. As we've seen, +however, this technical-sounding feature is actually essential to +creating nice syntax for your own control constructs. We'll shortly see +how this works together with other Scala features to give you even more flexibility in defining your construct's syntax. ### Implicits -Scala implicits offer some features which will be familiar to the C# -programmer, but are much more general in nature and go far beyond what can +Scala implicits offer some features which will be familiar to the C# +programmer, but are much more general in nature and go far beyond what can be done in C#. #### Enriching types in C# and Scala -Scala, like C#, is statically typed: a class’ methods are compiled into the -class definition and are not open for renegotiation. You cannot, as you -might in Ruby or Python, just go ahead and declare additional methods on an +Scala, like C#, is statically typed: a class’ methods are compiled into the +class definition and are not open for renegotiation. You cannot, as you +might in Ruby or Python, just go ahead and declare additional methods on an existing class. -This is of course very inconvenient. You end up declaring a load of -`FooHelper` or `FooUtils` classes full of static methods, and having to -write verbose calling code such as `if (EnumerableUtils.IsEmpty(sequence))` +This is of course very inconvenient. You end up declaring a load of +`FooHelper` or `FooUtils` classes full of static methods, and having to +write verbose calling code such as `if (EnumerableUtils.IsEmpty(sequence))` rather than the rather more readable `if (sequence.IsEmpty())`. -C# 3 tries to address this problem by introducing extension methods. -Extension methods are static methods in a `FooHelper` or `FooUtils` kind -of class, except you’re allowed to write them using member syntax. -By defining `IsEmpty` as an extension method on `IEnumerable`, you can +C# 3 tries to address this problem by introducing extension methods. +Extension methods are static methods in a `FooHelper` or `FooUtils` kind +of class, except you’re allowed to write them using member syntax. +By defining `IsEmpty` as an extension method on `IEnumerable`, you can write `if (sequence.IsEmpty())` after all. -Scala disapproves of static classes and global methods, so it plumps for -an alternative approach. You’ll still write a `FooHelper` or `FooUtils` -kind of class, but instead of taking the `Foo` to be Helped or Utilised as -a method parameter, your class will wrap `Foo` and enrich it with -additional methods. Let’s see this in action as we try to add a method to +Scala disapproves of static classes and global methods, so it plumps for +an alternative approach. You’ll still write a `FooHelper` or `FooUtils` +kind of class, but instead of taking the `Foo` to be Helped or Utilised as +a method parameter, your class will wrap `Foo` and enrich it with +additional methods. Let’s see this in action as we try to add a method to the `Double` type: - class RicherDouble(d : Double) { + class RicherDouble(d : Double) { def toThe(exp: Double): Double = System.Math.Pow(d, exp) } -(We call the class `RicherDouble` because Scala already has a `RichDouble` +(We call the class `RicherDouble` because Scala already has a `RichDouble` class defined which provides further methods to `Double`.) -Notice that `toThe` is an instance method, and that `RicherDouble` takes a -`Double` as a constructor parameter. This seems pretty grim, because we’d +Notice that `toThe` is an instance method, and that `RicherDouble` takes a +`Double` as a constructor parameter. This seems pretty grim, because we’d normally have to access the function like this: val result = new DoubleExtensions(2.0).toThe(7.0) -Hardly readable. To make it look nice, Scala requires us to define an +Hardly readable. To make it look nice, Scala requires us to define an *implicit conversion* from `Double` to `RicherDouble`: object Implicits { @@ -922,31 +920,31 @@ val twoToTheSeven = 2.0.toThe(7.0) -and all will be well. The `Double` type has apparently been successfully +and all will be well. The `Double` type has apparently been successfully enriched with the `toThe` method. -This is, of course, just as much an illusion as the C# equivalent. -C# extension methods don’t add methods to a type, and nor do Scala -implicit conversions. What has happened here is that the Scala compiler -has looked around for implicit methods that are applicable to the type of -`2.0` (namely `Double`), and return a type that has a `toThe` method. -Our `Implicits.richerDouble` method fits the bill, so the Scala compiler -silently inserts a call to that method. At runtime, therefore, Scala calls -`Implicits.richerDouble(2.0)` and calls the `toThe` of the resulting +This is, of course, just as much an illusion as the C# equivalent. +C# extension methods don’t add methods to a type, and nor do Scala +implicit conversions. What has happened here is that the Scala compiler +has looked around for implicit methods that are applicable to the type of +`2.0` (namely `Double`), and return a type that has a `toThe` method. +Our `Implicits.richerDouble` method fits the bill, so the Scala compiler +silently inserts a call to that method. At runtime, therefore, Scala calls +`Implicits.richerDouble(2.0)` and calls the `toThe` of the resulting `RicherDouble`. -If setting this up seems a bit verbose, well, maybe. C# extension methods -are designed to be easily – one might even say implicitly – brought into -scope. That’s very important for operators like the LINQ standard query -operators, but it can result in unwanted extension methods being dragged -into scope and causing havoc. Scala requires the caller to be a bit more -explicit about implicits, which results in a slightly higher setup cost but +If setting this up seems a bit verbose, well, maybe. C# extension methods +are designed to be easily – one might even say implicitly – brought into +scope. That’s very important for operators like the LINQ standard query +operators, but it can result in unwanted extension methods being dragged +into scope and causing havoc. Scala requires the caller to be a bit more +explicit about implicits, which results in a slightly higher setup cost but gives the caller finer control over which implicit methods are considered. -But as it happens you can avoid the need for separate definitions of -`Implicits` and `RicherDouble`, and get back to a more concise -representation by using an anonymous class. (As you’d expect, Scala -anonymous classes are fully capable, like Java ones, rather than the +But as it happens you can avoid the need for separate definitions of +`Implicits` and `RicherDouble`, and get back to a more concise +representation by using an anonymous class. (As you’d expect, Scala +anonymous classes are fully capable, like Java ones, rather than the neutered C# version.) Here’s how it looks: object Implicits { @@ -955,69 +953,69 @@ } } -Well, big deal. Scala can enrich existing types with new methods just like -C#, but using a different syntax. In related news, Lisp uses a different -kind of bracket: film at eleven. Why should we be interested in Scala +Well, big deal. Scala can enrich existing types with new methods just like +C#, but using a different syntax. In related news, Lisp uses a different +kind of bracket: film at eleven. Why should we be interested in Scala implicits if they’re just another take on extension methods? #### Implicit Parameters -What we saw above was an implicit method – a method which, like a C# -implicit conversion operator, the compiler is allowed to insert a call to -without the programmer writing that call. Scala also has the idea of -implicit parameters – that is, parameters which the compiler is allowed to +What we saw above was an implicit method – a method which, like a C# +implicit conversion operator, the compiler is allowed to insert a call to +without the programmer writing that call. Scala also has the idea of +implicit parameters – that is, parameters which the compiler is allowed to insert a value for without the programmer specifying that value. -That’s just optional parameters with default values, right? Like C++ and -Visual Basic have had since “visual” meant ASCII art on a teletype, and +That’s just optional parameters with default values, right? Like C++ and +Visual Basic have had since “visual” meant ASCII art on a teletype, and like C# is about to get? Well, no. -C++, Visual Basic and C# optional parameters have fixed defaults specified +C++, Visual Basic and C# optional parameters have fixed defaults specified by the called function. For example, if you have a method like this: public void Fie(int a, int b = 123) { … } -and you call `Fie(456)`, it’s always going to be equivalent to calling +and you call `Fie(456)`, it’s always going to be equivalent to calling `Fie(456, 123)`. -A Scala implicit parameter, on the other hand, gets its value from the -calling context. That allows programmer calling the method to control the -implicit parameter value, creating an extensibility point that optional +A Scala implicit parameter, on the other hand, gets its value from the +calling context. That allows programmer calling the method to control the +implicit parameter value, creating an extensibility point that optional parameters don’t provide. -This probably all sounds a bit weird, so let’s look at an example. Consider +This probably all sounds a bit weird, so let’s look at an example. Consider the following `Concatenate` method: public T Concatenate(IEnumerable sequence, T seed, Func concatenator); -We pass this guy a sequence, a start value and a function that combines two -values into one, and it returns the result of calling that function across -the sequence. For example, you could pass a sequence of strings, a start -value of `String.Empty`, and `(s1, s2) => s1 + s2`, and it would return you +We pass this guy a sequence, a start value and a function that combines two +values into one, and it returns the result of calling that function across +the sequence. For example, you could pass a sequence of strings, a start +value of `String.Empty`, and `(s1, s2) => s1 + s2`, and it would return you all the strings concatenated together: IEnumerable sequence = new string[] { “mog”, “bites”, “man” }; string result = Concatenate(sequence, String.Empty, (s1, s2) => s1 + s2); // result is “mogbitesman” -But this is a unpleasantly verbose. We’re having to pass in `String.Empty` -and `(s1, s2) => s1 + s2` every time we want to concatenate a sequence of -strings. Not only is this tedious, it also creates the opportunity for -error when the boss decides to “help” and passes the literal -`"String.Empty"` as the seed value instead. (“Oh, and I upgraded all the -semi-colons to colons while I was in there. No, don’t thank me!”) We’d -like to just tell the Concatenate function, “Look, this is how you +But this is a unpleasantly verbose. We’re having to pass in `String.Empty` +and `(s1, s2) => s1 + s2` every time we want to concatenate a sequence of +strings. Not only is this tedious, it also creates the opportunity for +error when the boss decides to “help” and passes the literal +`"String.Empty"` as the seed value instead. (“Oh, and I upgraded all the +semi-colons to colons while I was in there. No, don’t thank me!”) We’d +like to just tell the Concatenate function, “Look, this is how you concatenate strings,” once and for all. -Let’s start out by redefining the `Concatenate` method in Scala. -I’m going to factor out the seed and the concatenator method into a trait +Let’s start out by redefining the `Concatenate` method in Scala. +I’m going to factor out the seed and the concatenator method into a trait because we’ll typically be defining them together. trait Concatenator[T] { def startValue: T def concat(x: T, y: T): T } - + object implicitParameters { def concatenate[T](xs: List[T])(c: Concatenator[T]): T = if (xs.isEmpty) c.startValue @@ -1030,7 +1028,7 @@ def startValue: String = "" def concat(x: String, y: String) = x.concat(y) } - + object implicitParameters { def main(args: Array[String]) = { val result = concatenate(List("mog", "bites", "man"))(stringConcatenator) @@ -1038,21 +1036,21 @@ } } -So far, this looks like the C# version except for the factoring out of the -`Concatenator` trait. We’re still having to pass in the +So far, this looks like the C# version except for the factoring out of the +`Concatenator` trait. We’re still having to pass in the `stringConcatenator` at the point of the call. Let’s fix that: def concatenate[T](xs: List[T])(implicit c: Concatenator[T]): T = if (xs.isEmpty) c.startValue else c.concat(xs.head, concatenate(xs.tail)) -We’ve changed two things here. First, we’ve declared c to be an *implicit -parameter*, meaning the caller can leave it out. Second, we’ve left +We’ve changed two things here. First, we’ve declared c to be an *implicit +parameter*, meaning the caller can leave it out. Second, we’ve left it out ourselves, in the recursive call to `concatenate(xs.tail)`. -Well, okay, it’s nice that `concatenate` now doesn’t have to pass the -`Concatenator` explicitly to the recursive call, but we’re still having to -pass in the `stringConcatenator` object to get things started. If only +Well, okay, it’s nice that `concatenate` now doesn’t have to pass the +`Concatenator` explicitly to the recursive call, but we’re still having to +pass in the `stringConcatenator` object to get things started. If only there were some way to make the `stringConcatenator` object itself implicit… object Implicits { @@ -1062,16 +1060,16 @@ } } -Again, we’ve done two things here. First, we’ve declared the -`stringConcatenator` object implicit. Consequently, we’ve had to move it -out of the top level, because Scala doesn’t allow implicits at the top -level (because they’d pollute the global namespace, being in scope even +Again, we’ve done two things here. First, we’ve declared the +`stringConcatenator` object implicit. Consequently, we’ve had to move it +out of the top level, because Scala doesn’t allow implicits at the top +level (because they’d pollute the global namespace, being in scope even without an explicit import statement). Now we can call `concatenate` like this: import Implicits._ - + object implicitParameters { def main(args: Array[String]) = { val result = concatenate(List("mog", "bites", "man")) @@ -1081,10 +1079,10 @@ And we’ll still get “mogbitesman” as the output. -Let’s review what’s going on here. The implicit parameter of concatenate -has been set to our `stringConcatenator`, a default value that the -`concatenate` method knew nothing about when it was compiled. This is -somewhere north of what classical optional parameters are capable of, +Let’s review what’s going on here. The implicit parameter of concatenate +has been set to our `stringConcatenator`, a default value that the +`concatenate` method knew nothing about when it was compiled. This is +somewhere north of what classical optional parameters are capable of, and we’re not finished yet. Let’s build a `listConcatenator`. object Implicits { @@ -1095,14 +1093,14 @@ implicit object stringListConcatenator extends ListConcatenator[String] { } } -This is a bit vexing. `List` in Scala is a generic type, and has a generic -concatenation method called `:::`. But we can’t create a generic object, -because an object is an instance. And implicit parameters have to be objects. -So the best we can do is build a generic `ListConcatenator` class, and then -create trivial implicit objects for each generic parameter type we might +This is a bit vexing. `List` in Scala is a generic type, and has a generic +concatenation method called `:::`. But we can’t create a generic object, +because an object is an instance. And implicit parameters have to be objects. +So the best we can do is build a generic `ListConcatenator` class, and then +create trivial implicit objects for each generic parameter type we might need. -However, let’s not worry about the implementation, and see how this is used +However, let’s not worry about the implementation, and see how this is used at the calling end: val result = concatenate(List( @@ -1110,109 +1108,109 @@ List("on", "beard") )) -This displays `List(mog, bites, man, on, beard)`; that is, it concatenates -the two `List[String]`s into one. Once again, we have not had to pass -`stringListConcatenator` explicitly: the Scala compiler has gone and found -it for us. We can use the exact same calling code to concatenate lists and +This displays `List(mog, bites, man, on, beard)`; that is, it concatenates +the two `List[String]`s into one. Once again, we have not had to pass +`stringListConcatenator` explicitly: the Scala compiler has gone and found +it for us. We can use the exact same calling code to concatenate lists and strings. #### Why Should I Care? -Isn’t this pointless? At the call site, I have access to -`stringConcatenator` and `listStringConcatenator`. I can easily pass them +Isn’t this pointless? At the call site, I have access to +`stringConcatenator` and `listStringConcatenator`. I can easily pass them in rather than relying on spooky compiler magic to do it for me. Aren’t implicit parameters just job security for compiler writers? -Yes, implicit parameters are technically unnecessary. But if we’re going -to play that game, C# is technically unnecessary. You could write all that -code in IL. Extension methods are unnecessary because you could write the -static method out longhand. Optional parameters are unnecessary because -you could read the documentation and pass them in explicitly. -Post-It notes are unnecessary because you could fire up Outlook and create +Yes, implicit parameters are technically unnecessary. But if we’re going +to play that game, C# is technically unnecessary. You could write all that +code in IL. Extension methods are unnecessary because you could write the +static method out longhand. Optional parameters are unnecessary because +you could read the documentation and pass them in explicitly. +Post-It notes are unnecessary because you could fire up Outlook and create a Note instead. -Implicit parameters are about convenience and expressiveness. Implicit -parameters give you a way of describing how a function should handle -different situations, without needing to bake those situations into the +Implicit parameters are about convenience and expressiveness. Implicit +parameters give you a way of describing how a function should handle +different situations, without needing to bake those situations into the function logic or to specify them every time you call the function. -You don’t want to have to tell the `concatenate` function whether to use -the `List` or `String` concatenator every time you call it: the compiler -knows what you’re concatenating; specifying how to concatenate it just +You don’t want to have to tell the `concatenate` function whether to use +the `List` or `String` concatenator every time you call it: the compiler +knows what you’re concatenating; specifying how to concatenate it just gives you a chance to get it wrong! -Consequently, implicit parameters – like implicit conversions – contribute -to Scala’s ability to support internal DSLs. By setting up appropriate -implicits, you can write code that reads much more naturally than if you +Consequently, implicit parameters – like implicit conversions – contribute +to Scala’s ability to support internal DSLs. By setting up appropriate +implicits, you can write code that reads much more naturally than if you had to pepper it with function objects or callbacks. #### Conclusion -Scala’s `implicit` keyword goes beyond C#’s equivalent. As in C#, it is -used for implicit conversions; unlike C#, this is the idiomatic way to add -operations to an existing type, removing the need for the separate -extension method syntax. Implicit parameters have no equivalent in C#. -They are like being able to add default values to a method: just as a C# -using statement bring implicit methods into scope, a Scala import statement -can bring default values into scope. If implicit conversions are a way of -extending classes, then implicit parameters are a way of extending methods, -creating simple, reliable shorthands for complex generic methods, and +Scala’s `implicit` keyword goes beyond C#’s equivalent. As in C#, it is +used for implicit conversions; unlike C#, this is the idiomatic way to add +operations to an existing type, removing the need for the separate +extension method syntax. Implicit parameters have no equivalent in C#. +They are like being able to add default values to a method: just as a C# +using statement bring implicit methods into scope, a Scala import statement +can bring default values into scope. If implicit conversions are a way of +extending classes, then implicit parameters are a way of extending methods, +creating simple, reliable shorthands for complex generic methods, and making up another piece of the Scala DSL jigsaw. #### Method Call Syntax -C#, like most object-oriented programming languages, is pretty strict about -how you call methods: you use the dot notation, unless the method is a -special ‘operator’ method such as `operator+`, `operator==` or a conversion -operator. The special operator methods are predefined by the compiler: you -can write your own implementation, but you can’t create your own operator -names. You can teach the `+` operator how to handle your custom type, but +C#, like most object-oriented programming languages, is pretty strict about +how you call methods: you use the dot notation, unless the method is a +special ‘operator’ method such as `operator+`, `operator==` or a conversion +operator. The special operator methods are predefined by the compiler: you +can write your own implementation, but you can’t create your own operator +names. You can teach the `+` operator how to handle your custom type, but you can’t add an exponentiation operator: int a = b ** c; -C# has three problems with this: first, it doesn’t like the method name -`**`; second, it doesn’t like that there’s no `.` before the name; and +C# has three problems with this: first, it doesn’t like the method name +`**`; second, it doesn’t like that there’s no `.` before the name; and third, it doesn’t like that there’s no brackets around the method argument. -To get around the objection to the name, let’s compromise and call it +To get around the objection to the name, let’s compromise and call it `ToThe` for now. So what C# insists on seeing is `a.ToThe(b)`. -Scala, like many functional languages, isn’t so strict. Scala allows you -to use any method with a single argument in an infix position. Before we -can see this in the exponentiation example, we will enrich the `Double` +Scala, like many functional languages, isn’t so strict. Scala allows you +to use any method with a single argument in an infix position. Before we +can see this in the exponentiation example, we will enrich the `Double` type with the `toThe` method as we learned earlier: import Implicits._ import math._ - + class RicherDouble(d: Double) { def toThe(exp: Double): Double = pow(d, exp) } - + object Implicits { implicit def richerDouble(d: Double) = new RicherDouble(d) } -Recall that this is just the Scala idiom for extension methods – it’s the -equivalent of writing -`public static ToThe(this double first, double second) { … }` in C#. -(If we were wanting to use infix notation with our own class, we wouldn’t +Recall that this is just the Scala idiom for extension methods – it’s the +equivalent of writing +`public static ToThe(this double first, double second) { … }` in C#. +(If we were wanting to use infix notation with our own class, we wouldn’t need all this malarkey.) So now we can write: val raised = 2.0.toThe(7.0) -Okay, so what do we need to do to get this to work in infix position? +Okay, so what do we need to do to get this to work in infix position? Nothing, it turns out. val raised = 2.0 toThe 8.0 // it just works -This still doesn’t look much like a built-in operator, but it turns out +This still doesn’t look much like a built-in operator, but it turns out Scala is less fussy than C# about method names too. - class DoubleExtensions(d : Double) { + class DoubleExtensions(d : Double) { def **(exp: Double): Double = Pow(d, exp) } - + val raised = 2.0 ** 9.0 // it still just works Much nicer. @@ -1222,16 +1220,15 @@ class RicherString(s: String) { def twice: String = s + s } - + val drivel = "bibble" twice -Calling methods in infix and postfix nodadion is obviously fairly simple -syntactic sugar over normal dot notation. But this seemingly minor feature -is very important in constructing DSLs, allowing Scala to do in internal -DSLs what many languages can do only using external tools. For example, -where most languages do parsing via an external file format and a tool to -translate that file format into native code (a la `lex` and `yacc`), -Scala’s parser library makes extensive use of infix and postfix methods to -provide a “traditional” syntax for describing a parser, but manages it +Calling methods in infix and postfix nodadion is obviously fairly simple +syntactic sugar over normal dot notation. But this seemingly minor feature +is very important in constructing DSLs, allowing Scala to do in internal +DSLs what many languages can do only using external tools. For example, +where most languages do parsing via an external file format and a tool to +translate that file format into native code (a la `lex` and `yacc`), +Scala’s parser library makes extensive use of infix and postfix methods to +provide a “traditional” syntax for describing a parser, but manages it entirely within the Scala language. - diff --git a/_overviews/tutorials/scala-for-java-programmers.md b/_overviews/tutorials/scala-for-java-programmers.md index d53fdb75c4..9d9264b825 100644 --- a/_overviews/tutorials/scala-for-java-programmers.md +++ b/_overviews/tutorials/scala-for-java-programmers.md @@ -4,42 +4,104 @@ title: A Scala Tutorial for Java Programmers partof: scala-for-java-programmers -discourse: true - -languages: [es, ko, de, it, zh-tw] +languages: [es, ko, de, it, ja, zh-tw] permalink: /tutorials/:title.html + +get_started_resources: + - title: "Getting Started" + description: "Install Scala on your computer and start writing some Scala code!" + icon: "fa fa-rocket" + link: /getting-started.html + - title: Scala in the Browser + description: > + To start experimenting with Scala right away, use "Scastie" in your browser. + icon: "fa fa-cloud" + link: https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw +java_resources: + - title: Scala for Java Developers + description: A cheatsheet with a comprehensive side-by-side comparison of Java and Scala. + icon: "fa fa-coffee" + link: /scala3/book/scala-for-java-devs.html +next_resources: + - title: Scala Book + description: Learn Scala by reading a series of short lessons. + icon: "fa fa-book-open" + link: /scala3/book/introduction.html + - title: Online Courses + description: MOOCs to learn Scala, for beginners and experienced programmers. + icon: "fa fa-cloud" + link: /online-courses.html --- -By Michel Schinz and Philipp Haller +If you are coming to Scala with some Java experience already, this page should give a good overview of +the differences, and what to expect when you begin programming with Scala. For best results we suggest +to either set up a Scala toolchain on your computer, or try compiling Scala snippets in the browser with Scastie: + +{% include inner-documentation-sections.html links=page.get_started_resources %} + +## At a Glance: Why Scala? + +**Java without Semicolons:** There's a saying that Scala is Java without semicolons. +There is a lot of a truth to this statement: Scala simplifies much of the noise and boilerplate of Java, +while building upon the same foundation, sharing the same underlying types and runtime. + +**Seamless Interop:** Scala can use any Java library out of the box; including the Java standard library! +And pretty much any Java program will work the same in Scala, just by converting the syntax. + +**A Scalable Language:** the name Scala comes from Scalable Language. Scala scales not only with hardware +resources and load requirements, but also with the level of programmer's skill. If you choose, Scala +rewards you with expressive additional features, which when compared to Java, boost developer productivity and +readability of code. + +**It Grows with You:** Learning these extras are optional steps to approach at your own pace. +The most fun and effective way to learn, in our opinion, is to ensure you are productive first with what knowledge +you have from Java. And then, learn one thing at a time following the [Scala Book][scala-book]. Pick the learning pace convenient for you and ensure whatever you are learning is fun. -## Introduction +**TL;DR:** You can start writing Scala as if it were Java with new syntax, then explore from there as you see fit. -This document gives a quick introduction to the Scala language and -compiler. It is intended for people who already have some programming -experience and want an overview of what they can do with Scala. A -basic knowledge of object-oriented programming, especially in Java, is -assumed. +## Next Steps -## A First Example +### Compare Java and Scala +The remainder of this tutorial expands upon some of the key differences between Java and Scala, +with further explanations. **If you only want a quick reference** between the two, read +*Scala for Java Developers*, it comes +with many snippets which you can try out in your chosen Scala setup: -As a first example, we will use the standard *Hello world* program. It +{% include inner-documentation-sections.html links=page.java_resources %} + +### Explore Further + +When you finish these guides, we recommend to continue your Scala journey by reading the +*Scala Book* or following a number of *online MOOCs*. + +{% include inner-documentation-sections.html links=page.next_resources %} + +## Your First Program + +### Writing Hello World + +As a first example, we will use the standard *Hello World* program. It is not very fascinating but makes it easy to demonstrate the use of the Scala tools without knowing too much about the language. Here is how it looks: - object HelloWorld { - def main(args: Array[String]) { - println("Hello, world!") - } - } +{% tabs hello-world-demo class=tabs-scala-version %} +{% tab 'Scala 2' for=hello-world-demo %} +```scala +object HelloWorld { + def main(args: Array[String]): Unit = { + println("Hello, World!") + } +} +``` The structure of this program should be familiar to Java programmers: -it consists of one method called `main` which takes the command -line arguments, an array of strings, as parameter; the body of this +it's entry-point consists of one method called `main` which takes the command +line arguments, an array of strings, as a parameter; the body of this method consists of a single call to the predefined method `println` with the friendly greeting as argument. The `main` method does not -return a value (it is a procedure method). Therefore, it is not necessary -to declare a return type. +return a value. Therefore, its return type is declared as `Unit` +(equivalent to `void` in Java). What is less familiar to Java programmers is the `object` declaration containing the `main` method. Such a declaration @@ -49,44 +111,102 @@ both a class called `HelloWorld` and an instance of that class, also called `HelloWorld`. This instance is created on demand, the first time it is used. -The astute reader might have noticed that the `main` method is +Another difference from Java is that the `main` method is not declared as `static` here. This is because static members (methods or fields) do not exist in Scala. Rather than defining static members, the Scala programmer declares these members in singleton objects. - -### Compiling the example - -To compile the example, we use `scalac`, the Scala compiler. `scalac` -works like most compilers: it takes a source file as argument, maybe -some options, and produces one or several object files. The object -files it produces are standard Java class files. +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} +```scala +@main def HelloWorld(args: String*): Unit = + println("Hello, World!") +``` +The structure of this program may not be familiar to Java programmers: +there is no method called `main`, instead the `HelloWorld` method is marked +as an entry-point by adding the `@main` annotation. + +program entry-points optionally take parameters, which are populated by the +command line arguments. Here `HelloWorld` captures all the arguments in +a variable-length sequence of strings called `args`. + +The body of the method consists of a single call to the +predefined method `println` with the friendly greeting as argument. +The `HelloWorld` method does not +return a value. Therefore, its return type is declared as `Unit` +(equivalent to `void` in Java). + +Even less familiar to Java programmers is that `HelloWorld` +does not need to be wrapped in a class definition. Scala 3 +supports top-level method definitions, which are ideal for +program entry-points. + +The method also does not need to be declared as `static`. +This is because static members (methods or fields) do not exist in Scala. +Instead, top-level methods and fields are members of their enclosing +package, so can be accessed from anywhere in a program. + +> **Implementation detail**: so that the JVM can execute the program, +> the `@main` annotation generates a class `HelloWorld` with a +> static `main` method which calls the `HelloWorld` method with the +> command line arguments. +> This class is only visible at runtime. +{% endtab %} + +{% endtabs %} + +### Running Hello World + +> **Note:** The following assumes you are using Scala on the command line If we save the above program in a file called -`HelloWorld.scala`, we can compile it by issuing the following +`HelloWorld.scala`, we can run it by issuing the following command (the greater-than sign `>` represents the shell prompt and should not be typed): - > scalac HelloWorld.scala +```shell +> scala run HelloWorld.scala +``` + +The program will be automatically compiled (with compiled classes somewhere in the newly created `.scala-build` directory) +and executed, producing an output similar to: +``` +Compiling project (Scala {{site.scala-3-version}}, JVM (20)) +Compiled project (Scala {{site.scala-3-version}}, JVM (20)) +Hello, World! +``` + +#### Compiling From the Command Line -This will generate a few class files in the current directory. One of +To compile the example, we use `scala compile` command, which will invoke the Scala compiler, `scalac`. `scalac` +works like most compilers: it takes a source file as argument, maybe +some options, and produces one or several output files. The outputs +it produces are standard Java class files. + +```shell +> scala compile HelloWorld.scala -d . +``` + +This will generate a few class files in the current directory (`-d` option sets the compilation output directory). One of them will be called `HelloWorld.class`, and contains a class which can be directly executed using the `scala` command, as the following section shows. -### Running the example +#### Running From the Command Line -Once compiled, a Scala program can be run using the `scala` command. +Once compiled, the program can be run using the `scala run` command. Its usage is very similar to the `java` command used to run Java -programs, and accepts the same options. The above example can be +programs, and accepts similar options. The above example can be executed using the following command, which produces the expected output: - > scala -classpath . HelloWorld - - Hello, world! +```shell +> scala run --main-class HelloWorld -classpath . +Hello, World! +``` -## Interaction with Java +## Using Java Libraries One of Scala's strengths is that it makes it very easy to interact with Java code. All classes from the `java.lang` package are @@ -98,166 +218,223 @@ specific country, say France. (Other regions such as the French-speaking part of Switzerland use the same conventions.) Java's class libraries define powerful utility classes, such as -`Date` and `DateFormat`. Since Scala interoperates -seemlessly with Java, there is no need to implement equivalent -classes in the Scala class library--we can simply import the classes +`LocalDate` and `DateTimeFormatter`. Since Scala interoperates +seamlessly with Java, there is no need to implement equivalent +classes in the Scala class library; instead, we can import the classes of the corresponding Java packages: - import java.util.{Date, Locale} - import java.text.DateFormat - import java.text.DateFormat._ - - object FrenchDate { - def main(args: Array[String]) { - val now = new Date - val df = getDateInstance(LONG, Locale.FRANCE) - println(df format now) - } - } - +{% tabs date-time-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=date-time-demo %} +```scala +import java.time.format.{DateTimeFormatter, FormatStyle} +import java.time.LocalDate +import java.util.Locale._ + +object FrenchDate { + def main(args: Array[String]): Unit = { + val now = LocalDate.now + val df = DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).withLocale(FRANCE) + println(df.format(now)) + } +} +``` Scala's import statement looks very similar to Java's equivalent, however, it is more powerful. Multiple classes can be imported from the same package by enclosing them in curly braces as on the first line. Another difference is that when importing all the names of a -package or class, one uses the underscore character (`_`) instead -of the asterisk (`*`). That's because the asterisk is a valid -Scala identifier (e.g. method name), as we will see later. +package or class, in Scala 2 we use the underscore character (`_`) instead +of the asterisk (`*`). +{% endtab %} + +{% tab 'Scala 3' for=date-time-demo %} +```scala +import java.time.format.{DateTimeFormatter, FormatStyle} +import java.time.LocalDate +import java.util.Locale.* + +@main def FrenchDate: Unit = + val now = LocalDate.now + val df = DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).withLocale(FRANCE) + println(df.format(now)) +``` +Scala's import statement looks very similar to Java's equivalent, +however, it is more powerful. Multiple classes can be imported from +the same package by enclosing them in curly braces as on the first +line. Like with Java, in Scala 3 we use the asterisk (`*`) to import all +the names of a package or class. +{% endtab %} + +{% endtabs %} The import statement on the third line therefore imports all members -of the `DateFormat` class. This makes the static method -`getDateInstance` and the static field `LONG` directly +of the `Locale` enum. This makes the static field `FRANCE` directly visible. -Inside the `main` method we first create an instance of Java's -`Date` class which by default contains the current date. Next, we -define a date format using the static `getDateInstance` method +Inside the entry-point method we first create an instance of Java's +`DateTime` class, containing today's date. Next, we +define a date format using the `DateTimeFormatter.ofLocalizedDate` method, +passing the `LONG` format style, then further passing the `FRANCE` locale that we imported previously. Finally, we print the current date -formatted according to the localized `DateFormat` instance. This -last line shows an interesting property of Scala's syntax. Methods -taking one argument can be used with an infix syntax. That is, the -expression - - df format now - -is just another, slightly less verbose way of writing the expression - - df.format(now) - -This might seem like a minor syntactic detail, but it has important -consequences, one of which will be explored in the next section. +formatted according to the localized `DateTimeFormatter` instance. To conclude this section about integration with Java, it should be noted that it is also possible to inherit from Java classes and implement Java interfaces directly in Scala. +### Sidepoint: Third-Party Libraries + +Usually the standard library is not enough. As a Java programmer, you might already know a lot of Java libraries +that you'd like to use in Scala. The good news is that, as with Java, Scala's library ecosystem is built upon Maven coordinates. + +**Most Scala projects are built with sbt:** Adding third party libraries is usually managed by a build tool. +Coming from Java you may be familiar with Maven, Gradle and other such tools. +It's still possible to [use these][maven-setup] to build Scala projects, however it's common to use sbt. +See [setup a Scala Project with sbt][sbt-setup] for a guide on how +to build a project with sbt and add some dependencies. + + ## Everything is an Object Scala is a pure object-oriented language in the sense that *everything* is an object, including numbers or functions. It differs from Java in that respect, since Java distinguishes primitive types (such as `boolean` and `int`) from reference -types, and does not enable one to manipulate functions as values. +types. ### Numbers are objects Since numbers are objects, they also have methods. And in fact, an arithmetic expression like the following: - 1 + 2 * 3 / x +{% tabs math-expression-inline %} +{% tab 'Scala 2 and 3' for=math-expression-inline %} +```scala +1 + 2 * 3 / x +``` +{% endtab %} +{% endtabs %} consists exclusively of method calls, because it is equivalent to the following expression, as we saw in the previous section: - (1).+(((2).*(3))./(x)) +{% tabs math-expression-explicit %} +{% tab 'Scala 2 and 3' for=math-expression-explicit %} +```scala +1.+(2.*(3)./(x)) +``` +{% endtab %} +{% endtabs %} -This also means that `+`, `*`, etc. are valid identifiers +This also means that `+`, `*`, etc. are valid identifiers for fields/methods/etc in Scala. -The parentheses around the numbers in the second version are necessary -because Scala's lexer uses a longest match rule for tokens. -Therefore, it would break the following expression: - - 1.+(2) - -into the tokens `1.`, `+`, and `2`. The reason that -this tokenization is chosen is because `1.` is a longer valid -match than `1`. The token `1.` is interpreted as the -literal `1.0`, making it a `Double` rather than an -`Int`. Writing the expression as: - - (1).+(2) +### Functions are objects -prevents `1` from being interpreted as a `Double`. +True to _everything_ being an object, in Scala even functions are objects, going beyond Java's support for +lambda expressions. -### Functions are objects +Compared to Java, there is very little difference between function objects and methods: you can pass methods as +arguments, store them in variables, and return them from other functions, all without special syntax. +This ability to manipulate functions as values is one of the cornerstones of a very +interesting programming paradigm called *functional programming*. -Perhaps more surprising for the Java programmer, functions are also -objects in Scala. It is therefore possible to pass functions as -arguments, to store them in variables, and to return them from other -functions. This ability to manipulate functions as values is one of -the cornerstone of a very interesting programming paradigm called -*functional programming*. - -As a very simple example of why it can be useful to use functions as -values, let's consider a timer function whose aim is to perform some -action every second. How do we pass it the action to perform? Quite -logically, as a function. This very simple kind of function passing -should be familiar to many programmers: it is often used in -user-interface code, to register call-back functions which get called -when some event occurs. +To demonstrate, consider a timer function which +performs some action every second. The action to be performed is supplied by the +caller as a function value. In the following program, the timer function is called `oncePerSecond`, and it gets a call-back function as argument. The type of this function is written `() => Unit` and is the type -of all functions which take no arguments and return nothing (the type -`Unit` is similar to `void` in C/C++). The main function of -this program simply calls this timer function with a call-back which -prints a sentence on the terminal. In other words, this program -endlessly prints the sentence "time flies like an arrow" every +of all functions which take no arguments and return no useful value +(as before, the type `Unit` is similar to `void` in Java). + +The entry-point of this program calls `oncePerSecond` by directly passing +the `timeFlies` method. + +In the end this program will infitely print the sentence `time flies like an arrow` every second. - object Timer { - def oncePerSecond(callback: () => Unit) { - while (true) { callback(); Thread sleep 1000 } - } - def timeFlies() { - println("time flies like an arrow...") - } - def main(args: Array[String]) { - oncePerSecond(timeFlies) - } - } +{% tabs callback-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=callback-demo %} +```scala +object Timer { + def oncePerSecond(callback: () => Unit): Unit = { + while (true) { callback(); Thread.sleep(1000) } + } + def timeFlies(): Unit = { + println("time flies like an arrow...") + } + def main(args: Array[String]): Unit = { + oncePerSecond(timeFlies) + } +} +``` +{% endtab %} + +{% tab 'Scala 3' for=callback-demo %} +```scala +def oncePerSecond(callback: () => Unit): Unit = + while true do { callback(); Thread.sleep(1000) } + +def timeFlies(): Unit = + println("time flies like an arrow...") + +@main def Timer: Unit = + oncePerSecond(timeFlies) +``` +{% endtab %} + +{% endtabs %} Note that in order to print the string, we used the predefined method `println` instead of using the one from `System.out`. #### Anonymous functions -While this program is easy to understand, it can be refined a bit. -First of all, notice that the function `timeFlies` is only -defined in order to be passed later to the `oncePerSecond` -function. Having to name that function, which is only used once, might -seem unnecessary, and it would in fact be nice to be able to construct -this function just as it is passed to `oncePerSecond`. This is -possible in Scala using *anonymous functions*, which are exactly -that: functions without a name. The revised version of our timer -program using an anonymous function instead of *timeFlies* looks -like that: - - object TimerAnonymous { - def oncePerSecond(callback: () => Unit) { - while (true) { callback(); Thread sleep 1000 } - } - def main(args: Array[String]) { - oncePerSecond(() => - println("time flies like an arrow...")) - } - } +In Scala, lambda expressions are known as anonymous functions. +They are useful when functions are so short it is perhaps unneccesary +to give them a name. + +Here is a revised version of the timer +program, passing an anonymous function to `oncePerSecond` instead of `timeFlies`: + +{% tabs callback-demo-refined class=tabs-scala-version %} + +{% tab 'Scala 2' for=callback-demo-refined %} +```scala +object TimerAnonymous { + def oncePerSecond(callback: () => Unit): Unit = { + while (true) { callback(); Thread.sleep(1000) } + } + def main(args: Array[String]): Unit = { + oncePerSecond(() => + println("time flies like an arrow...")) + } +} +``` +{% endtab %} + +{% tab 'Scala 3' for=callback-demo-refined %} +```scala +def oncePerSecond(callback: () => Unit): Unit = + while true do { callback(); Thread.sleep(1000) } + +@main def TimerAnonymous: Unit = + oncePerSecond(() => + println("time flies like an arrow...")) +``` +{% endtab %} + +{% endtabs %} The presence of an anonymous function in this example is revealed by -the right arrow `=>` which separates the function's argument -list from its body. In this example, the argument list is empty, as -witnessed by the empty pair of parenthesis on the left of the arrow. +the right arrow (`=>`), different from Java's thin arrow (`->`), which +separates the function's argument list from its body. +In this example, the argument list is empty, so we put empty parentheses +on the left of the arrow. The body of the function is the same as the one of `timeFlies` above. @@ -272,44 +449,88 @@ Java's syntax. One important difference is that classes in Scala can have parameters. This is illustrated in the following definition of complex numbers. - class Complex(real: Double, imaginary: Double) { - def re() = real - def im() = imaginary - } +{% tabs class-demo class=tabs-scala-version %} +{% tab 'Scala 2' for=class-demo %} +```scala +class Complex(real: Double, imaginary: Double) { + def re() = real + def im() = imaginary +} +``` +This `Complex` class takes two arguments, which are the real and +imaginary part of the complex number. These arguments must be passed when +creating an instance of class `Complex`, as follows: +```scala +new Complex(1.5, 2.3) +``` +The class contains two methods, called `re` +and `im`, which give access to these two parts. +{% endtab %} + +{% tab 'Scala 3' for=class-demo %} +```scala +class Complex(real: Double, imaginary: Double): + def re() = real + def im() = imaginary +``` This `Complex` class takes two arguments, which are the real and -imaginary part of the complex. These arguments must be passed when -creating an instance of class `Complex`, as follows: `new - Complex(1.5, 2.3)`. The class contains two methods, called `re` +imaginary part of the complex number. These arguments must be passed when +creating an instance of class `Complex`, as follows: +```scala +new Complex(1.5, 2.3) +``` +where `new` is optional. +The class contains two methods, called `re` and `im`, which give access to these two parts. +{% endtab %} + +{% endtabs %} It should be noted that the return type of these two methods is not given explicitly. It will be inferred automatically by the compiler, which looks at the right-hand side of these methods and deduces that both return a value of type `Double`. -The compiler is not always able to infer types like it does here, and -there is unfortunately no simple rule to know exactly when it will be, -and when not. In practice, this is usually not a problem since the -compiler complains when it is not able to infer a type which was not -given explicitly. As a simple rule, beginner Scala programmers should -try to omit type declarations which seem to be easy to deduce from the -context, and see if the compiler agrees. After some time, the -programmer should get a good feeling about when to omit types, and -when to specify them explicitly. +> **Important:** The inferred result type of a method can change +> in subtle ways if the implementation changes, which could have a +> knock-on effect. Hence it is a best practise to put explicit +> result types for public members of classes. + +For local values in methods, it is encouraged to infer result types. +Try to experiment by omitting type declarations when they seem to be +easy to deduce from the context, and see if the compiler agrees. +After some time, the programmer should get a good feeling about when +to omit types, and when to specify them explicitly. ### Methods without arguments A small problem of the methods `re` and `im` is that, in -order to call them, one has to put an empty pair of parenthesis after +order to call them, one has to put an empty pair of parentheses after their name, as the following example shows: - object ComplexNumbers { - def main(args: Array[String]) { - val c = new Complex(1.2, 3.4) - println("imaginary part: " + c.im()) - } - } +{% tabs method-call-with-args-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=method-call-with-args-demo %} +```scala +object ComplexNumbers { + def main(args: Array[String]): Unit = { + val c = new Complex(1.2, 3.4) + println("imaginary part: " + c.im()) + } +} +``` +{% endtab %} + +{% tab 'Scala 3' for=method-call-with-args-demo %} +```scala +@main def ComplexNumbers: Unit = + val c = Complex(1.2, 3.4) + println("imaginary part: " + c.im()) +``` +{% endtab %} + +{% endtabs %} It would be nicer to be able to access the real and imaginary parts like if they were fields, without putting the empty pair of @@ -319,10 +540,26 @@ methods with zero arguments in that they don't have parenthesis after their name, neither in their definition nor in their use. Our `Complex` class can be rewritten as follows: - class Complex(real: Double, imaginary: Double) { - def re = real - def im = imaginary - } +{% tabs class-no-method-params-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-no-method-params-demo %} +```scala +class Complex(real: Double, imaginary: Double) { + def re = real + def im = imaginary +} +``` +{% endtab %} + +{% tab 'Scala 3' for=class-no-method-params-demo %} +```scala +class Complex(real: Double, imaginary: Double): + def re = real + def im = imaginary +``` +{% endtab %} + +{% endtabs %} ### Inheritance and overriding @@ -338,19 +575,63 @@ avoid accidental overriding. As an example, our `Complex` class can be augmented with a redefinition of the `toString` method inherited from `Object`. - class Complex(real: Double, imaginary: Double) { - def re = real - def im = imaginary - override def toString() = - "" + re + (if (im < 0) "" else "+") + im + "i" - } +{% tabs class-inheritance-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-inheritance-demo %} +```scala +class Complex(real: Double, imaginary: Double) { + def re = real + def im = imaginary + override def toString() = + "" + re + (if (im >= 0) "+" else "") + im + "i" +} +``` +{% endtab %} + +{% tab 'Scala 3' for=class-inheritance-demo %} +```scala +class Complex(real: Double, imaginary: Double): + def re = real + def im = imaginary + override def toString() = + "" + re + (if im >= 0 then "+" else "") + im + "i" +``` +{% endtab %} + +{% endtabs %} + +We can call the overridden `toString` method as below: + +{% tabs class-inheritance-toString-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-inheritance-toString-demo %} +```scala +object ComplexNumbers { + def main(args: Array[String]): Unit = { + val c = new Complex(1.2, 3.4) + println("Overridden toString(): " + c.toString) + } +} +``` +{% endtab %} + +{% tab 'Scala 3' for=class-inheritance-toString-demo %} +```scala +@main def ComplexNumbers: Unit = + val c = Complex(1.2, 3.4) + println("Overridden toString(): " + c.toString) +``` +{% endtab %} + +{% endtabs %} + -## Case Classes and Pattern Matching +## Algebraic Data Types and Pattern Matching A kind of data structure that often appears in programs is the tree. For example, interpreters and compilers usually represent programs -internally as trees; XML documents are trees; and several kinds of +internally as trees; JSON payloads are trees; and several kinds of containers are based on trees, like red-black trees. We will now examine how such trees are represented and manipulated in @@ -363,29 +644,39 @@ We first have to decide on a representation for such expressions. The most natural one is the tree, where nodes are operations (here, the addition) and leaves are values (here constants or variables). -In Java, such a tree would be represented using an abstract +In Java, before the introduction of records, such a tree would be +represented using an abstract super-class for the trees, and one concrete sub-class per node or leaf. In a functional programming language, one would use an algebraic -data-type for the same purpose. Scala provides the concept of +data-type (ADT) for the same purpose. + +{% tabs algebraic-data-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=algebraic-data-demo %} +Scala 2 provides the concept of *case classes* which is somewhat in between the two. Here is how they can be used to define the type of the trees for our example: - abstract class Tree - case class Sum(l: Tree, r: Tree) extends Tree - case class Var(n: String) extends Tree - case class Const(v: Int) extends Tree +```scala +abstract class Tree +object Tree { + case class Sum(left: Tree, right: Tree) extends Tree + case class Var(n: String) extends Tree + case class Const(v: Int) extends Tree +} +``` The fact that classes `Sum`, `Var` and `Const` are declared as case classes means that they differ from standard classes in several respects: - the `new` keyword is not mandatory to create instances of - these classes (i.e., one can write `Const(5)` instead of - `new Const(5)`), + these classes (i.e., one can write `Tree.Const(5)` instead of + `new Tree.Const(5)`), - getter functions are automatically defined for the constructor parameters (i.e., it is possible to get the value of the `v` constructor parameter of some instance `c` of class - `Const` just by writing `c.v`), + `Tree.Const` just by writing `c.v`), - default definitions for methods `equals` and `hashCode` are provided, which work on the *structure* of the instances and not on their identity, @@ -394,6 +685,35 @@ in several respects: `x+1` prints as `Sum(Var(x),Const(1))`), - instances of these classes can be decomposed through *pattern matching* as we will see below. +{% endtab %} + +{% tab 'Scala 3' for=algebraic-data-demo %} +Scala 3 provides the concept of *enums* which can be used like Java's enum, +but also to implement ADTs. Here is how they can be used to define the type +of the trees for our example: +```scala +enum Tree: + case Sum(left: Tree, right: Tree) + case Var(n: String) + case Const(v: Int) +``` +The cases of the enum `Sum`, `Var` and `Const` are similar to standard classes, +but differ in several respects: +- getter functions are automatically defined for the constructor + parameters (i.e., it is possible to get the value of the `v` + constructor parameter of some instance `c` of case + `Tree.Const` just by writing `c.v`), +- default definitions for methods `equals` and + `hashCode` are provided, which work on the *structure* of + the instances and not on their identity, +- a default definition for method `toString` is provided, and + prints the value in a "source form" (e.g., the tree for expression + `x+1` prints as `Sum(Var(x),Const(1))`), +- instances of these enum cases can be decomposed through + *pattern matching* as we will see below. +{% endtab %} + +{% endtabs %} Now that we have defined the data-type to represent our arithmetic expressions, we can start defining operations to manipulate them. We @@ -407,50 +727,69 @@ We therefore have to find a way to represent environments. We could of course use some associative data-structure like a hash table, but we can also directly use functions! An environment is really nothing more than a function which associates a value to a (variable) name. The -environment `{ x -> 5 }` given above can simply be written as +environment `{ x -> 5 }` given above can be written as follows in Scala: - { case "x" => 5 } +{% tabs env-definition %} +{% tab 'Scala 2 and 3' for=env-definition %} +```scala +type Environment = String => Int +val ev: Environment = { case "x" => 5 } +``` +{% endtab %} +{% endtabs %} This notation defines a function which, when given the string `"x"` as argument, returns the integer `5`, and fails with an exception otherwise. -Before writing the evaluation function, let us give a name to the type -of the environments. We could of course always use the type -`String => Int` for environments, but it simplifies the program -if we introduce a name for this type, and makes future changes easier. -This is accomplished in Scala with the following notation: +Above we defined a _type alias_ called `Environment` which is more +readable than the plain function type `String => Int`, and makes +future changes easier. + +We can now give the definition of the evaluation function. Here is +a brief specification: the value of a `Sum` is the addition of the +evaluations of its two inner expressions; the value of a `Var` is obtained +by lookup of its inner name in the environment; and the value of a +`Const` is its inner value itself. This specification translates exactly into +Scala as follows, using a pattern match on a tree value `t`: + +{% tabs patt-match-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=patt-match-demo %} +```scala +import Tree._ - type Environment = String => Int +def eval(t: Tree, ev: Environment): Int = t match { + case Sum(left, right) => eval(left, ev) + eval(right, ev) + case Var(n) => ev(n) + case Const(v) => v +} +``` +{% endtab %} -From then on, the type `Environment` can be used as an alias of -the type of functions from `String` to `Int`. +{% tab 'Scala 3' for=patt-match-demo %} +```scala +import Tree.* -We can now give the definition of the evaluation function. -Conceptually, it is very simple: the value of a sum of two expressions -is simply the sum of the value of these expressions; the value of a -variable is obtained directly from the environment; and the value of a -constant is the constant itself. Expressing this in Scala is not more -difficult: +def eval(t: Tree, ev: Environment): Int = t match + case Sum(left, right) => eval(left, ev) + eval(right, ev) + case Var(n) => ev(n) + case Const(v) => v +``` +{% endtab %} - def eval(t: Tree, env: Environment): Int = t match { - case Sum(l, r) => eval(l, env) + eval(r, env) - case Var(n) => env(n) - case Const(v) => v - } +{% endtabs %} -This evaluation function works by performing *pattern matching* -on the tree `t`. Intuitively, the meaning of the above definition -should be clear: +You can understand the precise meaning of the pattern match as follows: 1. it first checks if the tree `t` is a `Sum`, and if it - is, it binds the left sub-tree to a new variable called `l` and - the right sub-tree to a variable called `r`, and then proceeds + is, it binds the left sub-tree to a new variable called `left` and + the right sub-tree to a variable called `right`, and then proceeds with the evaluation of the expression following the arrow; this expression can (and does) make use of the variables bound by the - pattern appearing on the left of the arrow, i.e., `l` and - `r`, + pattern appearing on the left of the arrow, i.e., `left` and + `right`, 2. if the first check does not succeed, that is, if the tree is not a `Sum`, it goes on and checks if `t` is a `Var`; if it is, it binds the name contained in the `Var` node to a @@ -468,23 +807,30 @@ a value to a series of patterns, and as soon as a pattern matches, extract and name various parts of the value, to finally evaluate some code which typically makes use of these named parts. -A seasoned object-oriented programmer might wonder why we did not -define `eval` as a *method* of class `Tree` and its -subclasses. We could have done it actually, since Scala allows method -definitions in case classes just like in normal classes. Deciding -whether to use pattern matching or methods is therefore a matter of -taste, but it also has important implications on extensibility: - -- when using methods, it is easy to add a new kind of node as this - can be done just by defining a sub-class of `Tree` for it; on - the other hand, adding a new operation to manipulate the tree is - tedious, as it requires modifications to all sub-classes of - `Tree`, +### Comparison to OOP + +A programmer familiar with the object-oriented paradigm +might wonder why define a single function for `eval` outside +the scope of `Tree`, and not make `eval` an abstract method in +`Tree`, providing overrides in each subclass of `Tree`. + +We could have done it actually, it is a choice to make, which has +important implications on extensibility: + +- when using method overriding, adding a new operation to + manipulate the tree implies far-reaching changes to the code, + as it requires to add the method in all sub-classes of `Tree`, + however, adding a new subclass only requires implementing the + operations in one place. This design favours a few core operations + and many growing subclasses, - when using pattern matching, the situation is reversed: adding a new kind of node requires the modification of all functions which do pattern matching on the tree, to take the new node into account; on - the other hand, adding a new operation is easy, by just defining it - as an independent function. + the other hand, adding a new operation only requires defining the function + in one place. If your data structure has a stable set of nodes, + it favours the ADT and pattern matching design. + +### Adding a New Operation To explore pattern matching further, let us define another operation on arithmetic expressions: symbolic derivation. The reader might @@ -499,11 +845,32 @@ remember the following rules regarding this operation: These rules can be translated almost literally into Scala code, to obtain the following definition: - def derive(t: Tree, v: String): Tree = t match { - case Sum(l, r) => Sum(derive(l, v), derive(r, v)) - case Var(n) if (v == n) => Const(1) - case _ => Const(0) - } +{% tabs derivation-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=derivation-demo %} +```scala +import Tree._ + +def derive(t: Tree, v: String): Tree = t match { + case Sum(left, right) => Sum(derive(left, v), derive(right, v)) + case Var(n) if v == n => Const(1) + case _ => Const(0) +} +``` +{% endtab %} + +{% tab 'Scala 3' for=derivation-demo %} +```scala +import Tree.* + +def derive(t: Tree, v: String): Tree = t match + case Sum(left, right) => Sum(derive(left, v), derive(right, v)) + case Var(n) if v == n => Const(1) + case _ => Const(0) +``` +{% endtab %} + +{% endtabs %} This function introduces two new concepts related to pattern matching. First of all, the `case` expression for variables has a @@ -523,25 +890,54 @@ several operations on the expression `(x+x)+(7+y)`: it first computes its value in the environment `{ x -> 5, y -> 7 }`, then computes its derivative relative to `x` and then `y`. - def main(args: Array[String]) { - val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) - val env: Environment = { case "x" => 5 case "y" => 7 } - println("Expression: " + exp) - println("Evaluation with x=5, y=7: " + eval(exp, env)) - println("Derivative relative to x:\n " + derive(exp, "x")) - println("Derivative relative to y:\n " + derive(exp, "y")) - } - -You will need to wrap the `Environment` type and `eval`, `derive`, and -`main` methods in a `Calc` object before compiling. Executing this -program, we get the expected output: - - Expression: Sum(Sum(Var(x),Var(x)),Sum(Const(7),Var(y))) - Evaluation with x=5, y=7: 24 - Derivative relative to x: - Sum(Sum(Const(1),Const(1)),Sum(Const(0),Const(0))) - Derivative relative to y: - Sum(Sum(Const(0),Const(0)),Sum(Const(0),Const(1))) +{% tabs calc-main class=tabs-scala-version %} + +{% tab 'Scala 2' for=calc-main %} +```scala +import Tree._ + +object Calc { + type Environment = String => Int + def eval(t: Tree, ev: Environment): Int = ... + def derive(t: Tree, v: String): Tree = ... + + def main(args: Array[String]): Unit = { + val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) + val env: Environment = { case "x" => 5 case "y" => 7 } + println("Expression: " + exp) + println("Evaluation with x=5, y=7: " + eval(exp, env)) + println("Derivative relative to x:\n " + derive(exp, "x")) + println("Derivative relative to y:\n " + derive(exp, "y")) + } +} +``` +{% endtab %} + +{% tab 'Scala 3' for=calc-main %} +```scala +import Tree.* + +@main def Calc: Unit = + val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) + val env: Environment = { case "x" => 5 case "y" => 7 } + println("Expression: " + exp) + println("Evaluation with x=5, y=7: " + eval(exp, env)) + println("Derivative relative to x:\n " + derive(exp, "x")) + println("Derivative relative to y:\n " + derive(exp, "y")) +``` +{% endtab %} + +{% endtabs %} + +Executing this program, we should get the following output: +``` +Expression: Sum(Sum(Var(x),Var(x)),Sum(Const(7),Var(y))) +Evaluation with x=5, y=7: 24 +Derivative relative to x: + Sum(Sum(Const(1),Const(1)),Sum(Const(0),Const(0))) +Derivative relative to y: + Sum(Sum(Const(0),Const(0)),Sum(Const(0),Const(1))) +``` By examining the output, we see that the result of the derivative should be simplified before being presented to the user. Defining a @@ -554,10 +950,13 @@ Apart from inheriting code from a super-class, a Scala class can also import code from one or several *traits*. Maybe the easiest way for a Java programmer to understand what traits -are is to view them as interfaces which can also contain code. In +are is to view them as interfaces which can also contain code. In Scala, when a class inherits from a trait, it implements that trait's interface, and inherits all the code contained in the trait. +(Note that since Java 8, Java interfaces can also contain code, either +using the `default` keyword, or as static methods.) + To see the usefulness of traits, let's look at a classical example: ordered objects. It is often useful to be able to compare objects of a given class among themselves, for example to sort them. In Java, @@ -574,12 +973,30 @@ is, given the equal and smaller predicates (for example), one can express the other ones. In Scala, all these observations can be nicely captured by the following trait declaration: - trait Ord { - def < (that: Any): Boolean - def <=(that: Any): Boolean = (this < that) || (this == that) - def > (that: Any): Boolean = !(this <= that) - def >=(that: Any): Boolean = !(this < that) - } +{% tabs ord-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=ord-definition %} +```scala +trait Ord { + def < (that: Any): Boolean + def <=(that: Any): Boolean = (this < that) || (this == that) + def > (that: Any): Boolean = !(this <= that) + def >=(that: Any): Boolean = !(this < that) +} +``` +{% endtab %} + +{% tab 'Scala 3' for=ord-definition %} +```scala +trait Ord: + def < (that: Any): Boolean + def <=(that: Any): Boolean = (this < that) || (this == that) + def > (that: Any): Boolean = !(this <= that) + def >=(that: Any): Boolean = !(this < that) +``` +{% endtab %} + +{% endtabs %} This definition both creates a new type called `Ord`, which plays the same role as Java's `Comparable` interface, and @@ -600,11 +1017,35 @@ dates are composed of a day, a month and a year, which we will all represent as integers. We therefore start the definition of the `Date` class as follows: - class Date(y: Int, m: Int, d: Int) extends Ord { - def year = y - def month = m - def day = d - override def toString(): String = year + "-" + month + "-" + day +{% tabs date-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=date-definition %} +```scala +class Date(y: Int, m: Int, d: Int) extends Ord { + def year = y + def month = m + def day = d + override def toString(): String = s"$year-$month-$day" + + // rest of implementation will go here +} +``` +{% endtab %} + +{% tab 'Scala 3' for=date-definition %} +```scala +class Date(y: Int, m: Int, d: Int) extends Ord: + def year = y + def month = m + def day = d + override def toString(): String = s"$year-$month-$day" + + // rest of implementation will go here +end Date +``` +{% endtab %} + +{% endtabs %} The important part here is the `extends Ord` declaration which follows the class name and parameters. It declares that the @@ -613,37 +1054,87 @@ follows the class name and parameters. It declares that the Then, we redefine the `equals` method, inherited from `Object`, so that it correctly compares dates by comparing their individual fields. The default implementation of `equals` is not -usable, because as in Java it compares objects physically. We arrive +usable, because as in Java it compares objects by their identity. We arrive at the following definition: - override def equals(that: Any): Boolean = - that.isInstanceOf[Date] && { - val o = that.asInstanceOf[Date] - o.day == day && o.month == month && o.year == year - } - -This method makes use of the predefined methods `isInstanceOf` -and `asInstanceOf`. The first one, `isInstanceOf`, -corresponds to Java's `instanceof` operator, and returns true -if and only if the object on which it is applied is an instance of the -given type. The second one, `asInstanceOf`, corresponds to -Java's cast operator: if the object is an instance of the given type, -it is viewed as such, otherwise a `ClassCastException` is -thrown. - -Finally, the last method to define is the predicate which tests for -inferiority, as follows. It makes use of another method, +{% tabs equals-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=equals-definition %} +```scala +class Date(y: Int, m: Int, d: Int) extends Ord { + // previous decls here + + override def equals(that: Any): Boolean = that match { + case d: Date => d.day == day && d.month == month && d.year == year + case _ => false + } + + // rest of implementation will go here +} +``` +{% endtab %} + +{% tab 'Scala 3' for=equals-definition %} +```scala +class Date(y: Int, m: Int, d: Int) extends Ord: + // previous decls here + + override def equals(that: Any): Boolean = that match + case d: Date => d.day == day && d.month == month && d.year == year + case _ => false + + // rest of implementation will go here +end Date +``` +{% endtab %} + +{% endtabs %} + +While in Java (pre 16) you might use the `instanceof` operator followed by a cast +(equivalent to calling `that.isInstanceOf[Date]` and `that.asInstanceOf[Date]` in Scala); +in Scala it is more idiomatic to use a _type pattern_, shown in the example above which checks if `that` is an +instance of `Date`, and binds it to a new variable `d`, which is then used in the right hand side of the `case`. + +Finally, the last method to define is the `<` test, as follows. It makes use of another method, `error` from the package object `scala.sys`, which throws an exception with the given error message. - def <(that: Any): Boolean = { - if (!that.isInstanceOf[Date]) - sys.error("cannot compare " + that + " and a Date") +{% tabs lt-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=lt-definition %} +```scala +class Date(y: Int, m: Int, d: Int) extends Ord { + // previous decls here + + def <(that: Any): Boolean = that match { + case d: Date => + (year < d.year) || + (year == d.year && (month < d.month || + (month == d.month && day < d.day))) + + case _ => sys.error("cannot compare " + that + " and a Date") + } +} +``` +{% endtab %} + +{% tab 'Scala 3' for=lt-definition %} +```scala +class Date(y: Int, m: Int, d: Int) extends Ord: + // previous decls here + + def <(that: Any): Boolean = that match + case d: Date => + (year < d.year) || + (year == d.year && (month < d.month || + (month == d.month && day < d.day))) + + case _ => sys.error("cannot compare " + that + " and a Date") + end < +end Date +``` +{% endtab %} - val o = that.asInstanceOf[Date] - (year < o.year) || - (year == o.year && (month < o.month || - (month == o.month && day < o.day))) - } +{% endtabs %} This completes the definition of the `Date` class. Instances of this class can be seen either as dates or as comparable objects. @@ -659,11 +1150,7 @@ scope of this document. ## Genericity The last characteristic of Scala we will explore in this tutorial is -genericity. Java programmers should be well aware of the problems -posed by the lack of genericity in their language, a shortcoming which -is addressed in Java 1.5. - -Genericity is the ability to write code parametrized by types. For +genericity. Genericity is the ability to write code parametrized by types. For example, a programmer writing a library for linked lists faces the problem of deciding which type to give to the elements of the list. Since this list is meant to be used in many different contexts, it is @@ -682,12 +1169,16 @@ solve this problem. Let us examine this with an example of the simplest container class possible: a reference, which can either be empty or point to an object of some type. - class Reference[T] { - private var contents: T = _ - def set(value: T) { contents = value } - def get: T = contents - } +{% tabs reference-definition class=tabs-scala-version %} +{% tab 'Scala 2' for=reference-definition %} +```scala +class Reference[T] { + private var contents: T = _ + def set(value: T): Unit = { contents = value } + def get: T = contents +} +``` The class `Reference` is parametrized by a type, called `T`, which is the type of its element. This type is used in the body of the class as the type of the `contents` variable, the argument of @@ -696,22 +1187,64 @@ the `set` method, and the return type of the `get` method. The above code sample introduces variables in Scala, which should not require further explanations. It is however interesting to see that the initial value given to that variable is `_`, which represents -a default value. This default value is 0 for numeric types, +a default value. This default value is `0` for numeric types, +`false` for the `Boolean` type, `()` for the `Unit` +type and `null` for all object types. +{% endtab %} + +{% tab 'Scala 3' for=reference-definition %} +```scala +import compiletime.uninitialized + +class Reference[T]: + private var contents: T = uninitialized + def set(value: T): Unit = contents = value + def get: T = contents +``` +The class `Reference` is parametrized by a type, called `T`, +which is the type of its element. This type is used in the body of the +class as the type of the `contents` variable, the argument of +the `set` method, and the return type of the `get` method. + +The above code sample introduces variables in Scala, which should not +require further explanations. It is however interesting to see that +the initial value given to that variable is `uninitialized`, which represents +a default value. This default value is `0` for numeric types, `false` for the `Boolean` type, `()` for the `Unit` type and `null` for all object types. +{% endtab %} + +{% endtabs %} To use this `Reference` class, one needs to specify which type to use for the type parameter `T`, that is the type of the element contained by the cell. For example, to create and use a cell holding an integer, one could write the following: - object IntegerReference { - def main(args: Array[String]) { - val cell = new Reference[Int] - cell.set(13) - println("Reference contains the half of " + (cell.get * 2)) - } - } +{% tabs reference-usage class=tabs-scala-version %} + +{% tab 'Scala 2' for=reference-usage %} +```scala +object IntegerReference { + def main(args: Array[String]): Unit = { + val cell = new Reference[Int] + cell.set(13) + println("Reference contains the half of " + (cell.get * 2)) + } +} +``` +{% endtab %} + +{% tab 'Scala 3' for=reference-usage %} +```scala +@main def IntegerReference: Unit = + val cell = new Reference[Int] + cell.set(13) + println("Reference contains the half of " + (cell.get * 2)) +``` +{% endtab %} + +{% endtabs %} As can be seen in that example, it is not necessary to cast the value returned by the `get` method before using it as an integer. It @@ -722,6 +1255,10 @@ particular cell, since it was declared as holding an integer. This document gave a quick overview of the Scala language and presented some basic examples. The interested reader can go on, for example, by -reading the document *Scala By Example*, which -contains much more advanced examples, and consult the *Scala +reading the *[Tour of Scala](https://docs.scala-lang.org/tour/tour-of-scala.html)*, which +contains more explanations and examples, and consult the *Scala Language Specification* when needed. + +[scala-book]: {% link _overviews/scala3-book/introduction.md %} +[maven-setup]: {% link _overviews/tutorials/scala-with-maven.md %} +[sbt-setup]: {% link _overviews/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md %}#adding-a-dependency diff --git a/_overviews/tutorials/scala-on-android.md b/_overviews/tutorials/scala-on-android.md new file mode 100644 index 0000000000..370eb72b39 --- /dev/null +++ b/_overviews/tutorials/scala-on-android.md @@ -0,0 +1,144 @@ +--- +layout: singlepage-overview +title: A Tutorial on writing Scala apps on Android + +partof: scala-on-android + +permalink: /tutorials/:title.html +--- + +By Maciej Gorywoda + +## Introduction +The Android platform runs on Android Runtime which is a virtual machine based on JVM and, although not identical, [it's very similar to it](https://www.baeldung.com/java-jvm-vs-dvm). As a consequence, it is possible to write Android apps in Scala, and in fact it's possible to do it in more than one way. Here, in this document, we will focus on how to write a modern Android app with Scala that uses GraalVM Native Image and JavaFX. At the end of this tutorial, you will find links to materials discussing other options. + +## How to build an Android app with GraalVM Native Image + +#### Requirements + +We will use Linux. On Windows, it is possible to follow this tutorial and get a working Android app [if you use WSL2](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux). For building, we will use Maven. + +Download the latest GraalVM, Community Edition based on Java 11, from [here](https://github.com/graalvm/graalvm-ce-builds/releases). Set it up as your JVM by creating an environment variable `GRAALVM_HOME` pointing to the GraalVM home directory, by setting the environment variable `JAVA_HOME` to `${GRAALVM_HOME}`, and by adding `${GRAALVM_HOME}/bin` to your `PATH`. If you are using Bash, add the following lines to your `~/.bash_profile`: + +``` +export GRAALVM_HOME= +export JAVA_HOME=$GRAALVM_HOME +export PATH=$GRAALVM_HOME/bin:$PATH +``` + +When you type in `java -version` it should display something like this now: + +``` +> java -version +openjdk version "11.0.10" 2021-01-19 +OpenJDK Runtime Environment GraalVM CE 21.0.0 (build 11.0.10+8-jvmci-21.0-b06) +OpenJDK 64-Bit Server VM GraalVM CE 21.0.0 (build 11.0.10+8-jvmci-21.0-b06, mixed mode, sharing) +``` + +(The GraalVM version may differ) + + Type `native-image` to check if it’s already there on the path. If not, install it with: + +``` +gu install native-image +``` + +`gu` should be available now in your console because of `$GRAALVM_HOME/bin` in your `PATH`. Also, [read this](https://www.graalvm.org/reference-manual/native-image/#prerequisites) and install whatever you need. + +You will need `adb`, “Android Debug Bridge”, to connect to your Android device and install the app on it. [Here you can find more on how to do it](https://www.fosslinux.com/25170/how-to-install-and-setup-adb-tools-on-linux.htm). + +Make sure your `gcc` is at least version 6. [You can try following these steps](https://tuxamito.com/wiki/index.php/Installing_newer_GCC_versions_in_Ubuntu). On top of that, you will need some specific C libraries (like GTK) to build the native image, and it varies from one computer to another, so I can’t tell you exactly what to do. But it shouldn’t be a big problem. Just follow error messages saying that you lack something and google how to install them. In my case this was the list: + +``` + libasound2-dev (for pkgConfig alsa) + libavcodec-dev (for pkgConfig libavcodec) + libavformat-dev (for pkgConfig libavformat) + libavutil-dev (for pkgConfig libavutil) + libfreetype6-dev (for pkgConfig freetype2) + libgl-dev (for pkgConfig gl) + libglib2.0-dev (for pkgConfig gmodule-no-export-2.0) + libglib2.0-dev (for pkgConfig gthread-2.0) + libgtk-3-dev (for pkgConfig gtk+-x11-3.0) + libpango1.0-dev (for pkgConfig pangoft2) + libx11-dev (for pkgConfig x11) + libxtst-dev (for pkgConfig xtst) +``` + + + +#### The example app + +if you reached this point and everything seems to work, it means you probably should be able to compile and run the example app called [HelloScala](https://github.com/makingthematrix/scalaonandroid/tree/main/helloscala). HelloScala is based on [HelloGluon](https://github.com/gluonhq/gluon-samples/tree/master/HelloGluon) from [Gluon samples](https://github.com/gluonhq/gluon-samples). Gluon is a company that maintains JavaFX and provides libraries that give us a layer of abstraction between our code and the device — be it desktop, Android, or iOS. It has some interesting implications: for example, you will see in the code that we check if we are on the desktop instead of Android, because if yes then we need to provide window size for our app. If we are on Android, we can just let the app’s window take the whole screen. If you decide to write something more complex with this tech stack, you will quickly see that you can use Gluon’s libraries and JavaFX (maybe together with [ScalaFX](https://scalafx.github.io/)) to achieve the same results other developers get by tinkering with Android SDK, while you are writing code that can be easily re-used on other platforms as well. + +In the `pom.xml` of HelloScala you will find a list of plugins and dependencies our example app uses. Let’s take a look at some of them. + +- We will use Java 16 and Scala 2.13. +- [A tiny Scala library](https://mvnrepository.com/artifact/org.scalameta/svm-subs) which resolves [this problem](https://github.com/scala/bug/issues/11634) in the interaction between Scala 2.13 and GraalVM Native Image. +- For the GUI we will use JavaFX 16. +- We will use two Gluon libraries: [Glisten](https://docs.gluonhq.com/charm/javadoc/6.0.6/com.gluonhq.charm.glisten/module-summary.html) and [Attach](https://gluonhq.com/products/mobile/attach/). Glisten enriches JavaFX with additional functionality specifically designed for mobile applications. Attach is an abstraction layer over the underlying platform. For us, it means we should be able to use it to access everything on Android from the local storage to permissions to push notifications. +- [scala-maven-plugin](https://github.com/davidB/scala-maven-plugin) lets us use Scala in Maven builds *(well, d’oh)*. Thank you, David! +- [gluonfx-maven-plugin](https://github.com/gluonhq/gluonfx-maven-plugin) lets us compile Gluon dependencies and JavaFX code into a native image. In its configuration you will find the `attachList` with Gluon Attach modules we need: `device`, `display`, `storage`, `util`, `statusbar`, and `lifecycle`. From those we will use directly only `display` (to set the dimensions of the app's windows in case we run the app on a desktop and not in the full-screen mode on a mobile) and `util` (to check if we run the app on a desktop or a mobile), but the others are needed by these two and by Gluon Glisten. +- [javafx-maven-plugin](https://github.com/openjfx/javafx-maven-plugin) which is a requirement for gluonfx-maven-plugin. + +### The code + +[HelloScala](https://github.com/makingthematrix/scalaonandroid/tree/main/helloscala) is just a simple example app — the actual Scala code only sets up a few widgets and displays them. The [`Main`](https://github.com/makingthematrix/scalaonandroid/blob/main/helloscala/src/main/scala/helloscala/Main.scala) class extends `MobileApplication` from the Glisten library and then construct the main view programmatically, in two methods: `init()` for creating the widgets, and `postInit(Scene)` for decorating them. Since we want to test the app on our laptop before we install it on a mobile, we use `postInit` also to check on which platform the app is being run, and if it's a desktop, we set the dimensions on the app's window. In the case of a mobile it's not necessary — our app will take the whole available space on the screen. + +Another way to set up and display widgets in JavaFX is to use a WYSIWYG editor called [Scene Builder](https://gluonhq.com/products/scene-builder/) which generates FXML files, a version of XML, that you can then load into your app. You can see how it is done in another example: [HelloFXML](https://github.com/makingthematrix/scalaonandroid/tree/main/HelloFXML). For more complex applications, you will probably mix those two approaches: FXML for more-or-less static views and programmatically set up widgets in places where the UI within one view changes in reaction to events (think, for example, of a scrollable list of incoming messages). + +### How to run the app + +Building an Android native image takes time, so we want to avoid doing it too often. Even before running the app for the first time, you should invest some time in unit, component, and integration tests, so that if you change something in your app you could still be sure it works correctly even before any manual testing. Then, to check how your GUI looks like and works, use: + +``` +mvn gluonfx:run +``` + +If everything looks fine, build the native image… but first, for your desktop: + +``` +mvn gluonfx:build gluonfx:nativerun +``` + +After all, we work on a cross-platform solution here. Unless you want to test features of your app that will only work on a mobile device, you can first run it as a standalone desktop application. This will again let you test some layers of the app without actually running it on an Android device. And then, if all looks good, or if you decide to skip this step: + +``` +mvn -Pandroid gluonfx:build gluonfx:package +``` + +Successful execution of this command will create an APK file in the` target/client/aarch64-android/gvm` directory. Connect your Android phone to the computer with a USB cable, give the computer permission to send files to the phone, and type `adb devices` to check if your phone is recognized. It should display something like this in the console: + +``` +> adb devices +List of devices attached +16b3a5c8 device +``` + +Now you should be able to install the app on the connected device with `adb install ` and a moment later you should see a new icon on your device’s main screen. When you click on the icon, it should open approximately the same screen as the desktop version of your app. + +Installation might not work for a number of reasons, one of the most popular being that your Android simply does not allow installing apps this way. Go to Settings, find “Developers options”, and there enable “USB debugging” and “Install via USB”. + +If everything works, and you see the app’s screen on your device, type `adb logcat | grep GraalCompiled` to see the log output. Now you can click the button with the magnifying glass icon on the app’s screen, and you should see `"log something from Scala"` printed to the console. Of course, before you write a more complex app, please look into plugins in the IDE of your choice that can display logs from `adb logcat` in a better way. For example + +* [Logcat in Android Studio](https://developer.android.com/studio/debug/am-logcat) +* [Log Viewer for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/10015-log-viewer) +* [Logcat plugin for VSCode](https://marketplace.visualstudio.com/items?itemName=abhiagr.logcat) + +Here's a [screenshot](https://github.com/makingthematrix/scalaonandroid/blob/main/helloscala/helloscala.png) of what the app looks like when you open it. + +## Next Steps and Other Useful Reading + +If you managed to build one of the example apps and want to code something more complex, there are at least a few ways you can learn how to do it: + +* Take a look at these articles about the history of Scala on Android and a discussion of other ways to write Android apps: [#1](https://makingthematrix.wordpress.com/2021/03/17/scala-on-android/), [#2](https://www.scalawilliam.com/scala-android-opportunity/). + +- Read more and experiment with [JavaFX](https://openjfx.io/). You can start with its official documentation and with [this huge list of tutorials by Jacob Jenkov](http://tutorials.jenkov.com/javafx/index.html). +- Install [Scene Builder](https://gluonhq.com/products/scene-builder/) and learn how to build GUI with it. Apart from the docs, you can find a lot of tutorials about it on YouTube. +- Look through [Gluon’s documentation of Glisten and Attach](https://docs.gluonhq.com/) to learn how to make your app look better on a mobile device, and how to get access to your device’s features. +- Download an example from [Gluon’s list of samples](https://docs.gluonhq.com/) and rewrite it to Scala. And when you do, let me know! +- Look into [ScalaFX](https://scalafx.github.io/) — a more declarative, Scala-idiomatic wrapper over JavaFX. +- Download some other examples from [the “Scala on Android” repository on GitHub](https://github.com/makingthematrix/scalaonandroid). Contact me, if you write an example app of your own and want me to include it. +- Join us on the official Scala discord — we have a [#scala-android channel](https://discord.gg/UuDawpq7) there. +- There is also an [#android channel](https://discord.gg/XHMt6Yq4) on the “Learning Scala” discord. +- Finally, if you have any questions, [you can always find me on X](https://x.com/makingthematrix). + diff --git a/_overviews/tutorials/scala-with-maven.md b/_overviews/tutorials/scala-with-maven.md index d8f8194ec5..0cdbfc990a 100644 --- a/_overviews/tutorials/scala-with-maven.md +++ b/_overviews/tutorials/scala-with-maven.md @@ -1,8 +1,6 @@ --- layout: singlepage-overview title: Scala with Maven - -discourse: true permalink: /tutorials/:title.html --- @@ -60,19 +58,10 @@ The easiest way to create new projects is using an ["archetype"][11]. An archety You run the archetype plugin like this: - mvn archetype:generate + mvn archetype:generate -DarchetypeGroupId=net.alchim31.maven -DarchetypeArtifactId=scala-archetype-simple If this is your first time, you'll notice that Maven is downloading many jar files. Maven resolves dependencies and downloads them as needed (and only once). Right now, Maven is downloading its core plugins. -Afterwards, it should give you a list of archetypes (in the hundreds). -The Scala Maven Plugin was 339 on my list: "net.alchim31.maven:scala-archetype-simple (The maven-scala-plugin is used for compiling/testing/running/documenting scala code in maven.)". -You can type "scala" (or something else) to filter the results. -As of 2015 January 27, there you can choose version 3.1.4 or 3.1.5 of this plugin; you should choose the latest - - Choose net.alchim31.maven:scala-archetype-simple version: - 1: 1.4 - 2: 1.5 - Next, Maven will ask you for a groupId, artifactId, and package. You can read the [guide to naming conventions][12], but in short: - groupId: inverted domain name (e.g. com.my-organization) @@ -119,7 +108,7 @@ Example structure: Again, you can read more about the Scala Maven Plugin at its [website][22]. ### Creating a Jar -By default the jar created by the Scala Maven Plugin doesn't include a `Main-Class` attribute in the manifest. I had to add the [Maven Assembly Plugin][19] to my `pom.xml` in order to specify custom attributes in the manifest. You can check the latest version of this plugin at the [project summary][20] or at [The Central Repository][21] +By default, the jar created by the Scala Maven Plugin doesn't include a `Main-Class` attribute in the manifest. I had to add the [Maven Assembly Plugin][19] to my `pom.xml` in order to specify custom attributes in the manifest. You can check the latest version of this plugin at the [project summary][20] or at [The Central Repository][21] X.X.X @@ -174,82 +163,6 @@ After adding this, `mvn package` will also create `[artifactId]-[version]-jar-wi - `mvn clean` - `mvn package`: compile, run tests, and create jar -### Integration with Eclipse ([Scala IDE][24]) -There are instructions at the [Scala Maven Plugin FAQs][23], but I thought I'd expand a bit. The [maven-eclipse-plugin][33] is a core plugin (all plugins prefixed with "maven" are, and are available by default) to generate Eclipse configuration files. However, this plugin does not know about our new Scala source files. We'll be using the [build-helper-maven-plugin][34] to add new source folders: - - ... - - org.codehaus.mojo - build-helper-maven-plugin - - - add-source - generate-sources - - add-source - - - - src/main/scala - - - - - add-test-source - generate-sources - - add-test-source - - - - src/test/scala - - - - - - ... - -After adding that to your `pom.xml`: - -1. Run `mvn eclipse:eclipse` - this generates the Eclipse project files (which are already ignored by our archetype's `.gitignore`) -2. Run `mvn -Declipse.workspace="path/to/your/eclipse/workspace" eclipse:configure-workspace` - this adds an `M2_REPO` classpath variable to Eclipse -3. Run `mvn package` to ensure you have all the dependencies in your local Maven repo - -Unfortunately, the integration isn't perfect. Firstly, open up the generated `.classpath` file (it will be hidden by default as it's a dotfile, but it should be in your project root directory; where you ran `mvn eclipse:eclipse`). You should see something like this near the top. - - - - -Change the `*.java` to `*.scala` (or duplicate the lines and change them to `*.scala` if you also have Java sources). - -Secondly, open the `.project` eclipse file (again, in the same folder). Change `` and `` to look like this. Now Eclipse knows to use the Scala editor and it won't think that everything is a syntax error. - - - - org.scala-ide.sdt.core.scalabuilder - - - - org.scala-ide.sdt.core.scalanature - org.eclipse.jdt.core.javanature - - -Finally, in Eclipse, under "File" choose "Import..." and find your project. - -#### Using [m2eclipse-scala][35] for Eclipse integration -m2eclipse-scala is a work in progress, and their website/repository may have updated information. -It aims to ease integration between m2eclipse and Scala IDE for Eclipse. - -Under "Help -> Install New Software", enter "http://alchim31.free.fr/m2e-scala/update-site" and hit enter. -You should see "Maven Integration for Eclipse -> Maven Integration for Scala IDE". - -Afer it installs, go to "New -> Project -> Other" and select "Maven Project". -Search fo "scala-archetype" choose the one with the group "net.alchim31.maven". -The wizard will more or less guide you through what was done with `mvn archetype:generate` above, and you should end up with a new Scala project! - -To import an existing project, simply go to "File -> Import -> Existing Maven Project" and find the directory containing your project. - ## Adding Dependencies The first thing I do is look for "Maven" in the project page. For example, Google's [Guava] page includes [Maven Central links][28]. As you can see in the previous link, The Central Repository conveniently includes the snippet you have to add to your `pom.xml` on the left sidebar. @@ -265,39 +178,36 @@ Will download any new dependencies before packaging I'm not going to explain all of Maven in this tutorial (though I hope to add more in the future, because I do feel that the resources are a bit scattered), so here are some useful articles: - [Maven Lifecycle][17] (explanation of goals like clean, package, install) -[1]: http://maven.apache.org -[2]: http://maven.org -[3]: http://maven.apache.org/download.html -[4]: http://macports.org +[1]: https://maven.apache.org +[2]: https://maven.org +[3]: https://maven.apache.org/download.html +[4]: https://macports.org [5]: https://github.com/davidB/scala-maven-plugin -[6]: http://brew.sh -[7]: http://fink.sf.net -[8]: http://7-zip.org -[9]: http://unix.stackexchange.com/questions/63531/ -[10]: http://wikipedia.org/wiki/Unix_shell#Configuration_files_for_shells -[11]: http://maven.apache.org/archetype/maven-archetype-plugin/ -[12]: http://maven.apache.org/guides/mini/guide-naming-conventions.html -[13]: http://semver.org -[14]: http://junit.org -[15]: http://scalatest.org -[16]: http://specs2.org -[17]: http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html -[18]: http://maven.apache.org/pom.html -[19]: http://maven.apache.org/plugins/maven-assembly-plugin/ -[20]: http://maven.apache.org/plugins/maven-assembly-plugin/project-summary.html -[21]: http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22maven-assembly-plugin%22 -[22]: http://davidb.github.io/scala-maven-plugin -[23]: http://davidb.github.io/scala-maven-plugin/faq.html -[24]: http://scala-ide.org -[25]: http://scala-lang.org/api/current/index.html#scala.App -[26]: http://docs.scala-lang.org/tutorials/tour/polymorphic-methods.html +[6]: https://brew.sh +[7]: https://fink.sf.net +[8]: https://7-zip.org +[9]: https://unix.stackexchange.com/questions/63531/ +[10]: https://wikipedia.org/wiki/Unix_shell#Configuration_files_for_shells +[11]: https://maven.apache.org/archetype/maven-archetype-plugin/ +[12]: https://maven.apache.org/guides/mini/guide-naming-conventions.html +[13]: https://semver.org +[14]: https://junit.org +[15]: https://scalatest.org +[16]: https://specs2.org +[17]: https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html +[18]: https://maven.apache.org/pom.html +[19]: https://maven.apache.org/plugins/maven-assembly-plugin/ +[20]: https://maven.apache.org/plugins/maven-assembly-plugin/summary.html +[21]: https://search.maven.org/#search%7Cga%7C1%7Ca%3A%22maven-assembly-plugin%22 +[22]: https://davidb.github.io/scala-maven-plugin +[23]: https://davidb.github.io/scala-maven-plugin/faq.html +[25]: https://scala-lang.org/api/current/index.html#scala.App +[26]: https://docs.scala-lang.org/tutorials/tour/polymorphic-methods.html [27]: https://code.google.com/p/guava-libraries/ -[28]: http://search.maven.org/#artifactdetails%7Ccom.google.guava%7Cguava%7C14.0.1%7Cbundle +[28]: https://search.maven.org/#artifactdetails%7Ccom.google.guava%7Cguava%7C14.0.1%7Cbundle [29]: https://github.com/scopt/scopt -[30]: http://search.maven.org/#search%7Cga%7C1%7Cscopt -[31]: http://mvnrepository.com -[32]: http://docs.scala-lang.org/contribute.html -[33]: http://maven.apache.org/plugins/maven-eclipse-plugin/ -[34]: http://www.mojohaus.org/build-helper-maven-plugin/ -[35]: https://github.com/sonatype/m2eclipse-scala +[30]: https://search.maven.org/#search%7Cga%7C1%7Cscopt +[31]: https://mvnrepository.com +[32]: https://docs.scala-lang.org/contribute.html +[34]: https://www.mojohaus.org/build-helper-maven-plugin/ [36]: https://github.com/scala/scala-module-dependency-sample diff --git a/_pl/cheatsheets/index.md b/_pl/cheatsheets/index.md index 96b924cc4e..42b34c6530 100644 --- a/_pl/cheatsheets/index.md +++ b/_pl/cheatsheets/index.md @@ -1,88 +1,627 @@ --- layout: cheatsheet -title: Scalacheat +title: Scala Cheatsheet partof: cheatsheet -by: Filip Czaplicki -about: Podziękowania dla             Brendan O'Connor. Ten cheatsheet ma być szybkim podsumowaniem konstrukcji składniowych Scali. Licencjonowany przez Brendan O'Connor pod licencją CC-BY-SA 3.0. +by: Filip Czaplicki, Konrad Klawikowski +about: Podziękowania dla Brendan O'Connor. Ten cheatsheet ma być szybkim podsumowaniem konstrukcji składniowych Scali. Licencjonowany przez Brendan O'Connor pod licencją CC-BY-SA 3.0. language: pl --- -###### Contributed by {{ page.by }} + + {{ page.about }} -| zmienne | | -| `var x = 5` | zmienna | -| Dobrze `val x = 5`
            Źle `x=6` | stała | -| `var x: Double = 5` | zmienna z podanym typem | -| funkcje | | -| Dobrze `def f(x: Int) = { x*x }`
            Źle `def f(x: Int) { x*x }` | definicja funkcji
            ukryty błąd: bez znaku = jest to procedura zwracająca Unit; powoduje to chaos | -| Dobrze `def f(x: Any) = println(x)`
            Źle `def f(x) = println(x)` | definicja funkcji
            błąd składni: potrzebne są typy dla każdego argumentu. | -| `type R = Double` | alias typu | -| `def f(x: R)` vs.
            `def f(x: => R)` | wywołanie przez wartość
            wywołanie przez nazwę (parametry leniwe) | -| `(x:R) => x*x` | funkcja anonimowa | -| `(1 to 5).map(_*2)` vs.
            `(1 to 5).reduceLeft( _+_ )` | funkcja anonimowa: podkreślenie to argument pozycjonalny | -| `(1 to 5).map( x => x*x )` | funkcja anonimowa: aby użyć argumentu dwa razy, musisz go nazwać. | -| Dobrze `(1 to 5).map(2*)`
            Źle `(1 to 5).map(*2)` | funkcja anonimowa: związana metoda infiksowa. Możesz użyć także `2*_`. | -| `(1 to 5).map { x => val y=x*2; println(y); y }` | funkcja anonimowa: z bloku zwracane jest ostatnie wyrażenie. | -| `(1 to 5) filter {_%2 == 0} map {_*2}` | funkcja anonimowa: styl potokowy. (lub ponawiasowane). | -| `def compose(g:R=>R, h:R=>R) = (x:R) => g(h(x))`
            `val f = compose({_*2}, {_-1})` | funkcja anonimowa: aby przekazać kilka bloków musisz użyć nawiasów. | -| `val zscore = (mean:R, sd:R) => (x:R) => (x-mean)/sd` | rozwijanie funkcji, oczywista składnia. | -| `def zscore(mean:R, sd:R) = (x:R) => (x-mean)/sd` | rozwijanie funkcji, oczywista składnia. | -| `def zscore(mean:R, sd:R)(x:R) = (x-mean)/sd` | rozwijanie funkcji, lukier składniowy. ale wtedy: | -| `val normer = zscore(7, 0.4) _` | potrzeba wiodącego podkreślenia, aby wydobyć funkcję częściowo zaaplikowaną, tylko dla wersji z lukrem składniowym. | -| `def mapmake[T](g:T=>T)(seq: List[T]) = seq.map(g)` | typ generyczny. | -| `5.+(3); 5 + 3`
            `(1 to 5) map (_*2)` | lukier składniowy dla operatorów infiksowych. | -| `def sum(args: Int*) = args.reduceLeft(_+_)` | zmienna liczba argumentów funkcji. | -| pakiety | | -| `import scala.collection._` | import wszystkiego z danego pakietu. | -| `import scala.collection.Vector`
            `import scala.collection.{Vector, Sequence}` | import selektywny. | -| `import scala.collection.{Vector => Vec28}` | import ze zmianą nazwy. | -| `import java.util.{Date => _, _}` | importowanie wszystkiego z java.util poza Date. | -| `package pkg` _na początku pliku_
            `package pkg { ... }` | deklaracja pakietu. | -| struktury danych | | -| `(1,2,3)` | literał krotki. (`Tuple3`) | -| `var (x,y,z) = (1,2,3)` | przypisanie z podziałem: rozpakowywanie krotki przy pomocy dopasowywania wzorca. | -| Źle`var x,y,z = (1,2,3)` | ukryty błąd: do każdego przypisana cała krotka. | -| `var xs = List(1,2,3)` | lista (niezmienna). | -| `xs(2)` | indeksowanie za pomocą nawiasów. ([slajdy](http://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) | -| `1 :: List(2,3)` | operator dołożenia elementu na początek listy. | -| `1 to 5` _to samo co_ `1 until 6`
            `1 to 10 by 2` | składnia dla przedziałów. | -| `()` _(puste nawiasy)_ | jedyny obiekt typu Unit (podobnie jak void w C/Java). | -| konstrukcje kontrolne | | -| `if (check) happy else sad` | warunek. | -| `if (check) happy` _to samo co_
            `if (check) happy else ()` | lukier składniowy dla warunku. | -| `while (x < 5) { println(x); x += 1}` | pętla while. | -| `do { println(x); x += 1} while (x < 5)` | pętla do while. | -| `import scala.util.control.Breaks._`
            `breakable {`
            ` for (x <- xs) {`
            ` if (Math.random < 0.1) break`
            ` }`
            `}`| instrukcja przerwania pętli (break). ([slides](http://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) | -| `for (x <- xs if x%2 == 0) yield x*10` _to samo co_
            `xs.filter(_%2 == 0).map(_*10)` | instrukcja for: filtrowanie / mapowanie | -| `for ((x,y) <- xs zip ys) yield x*y` _to samo co_
            `(xs zip ys) map { case (x,y) => x*y }` | instrukcja for: przypisanie z podziałem | -| `for (x <- xs; y <- ys) yield x*y` _to samo co_
            `xs flatMap {x => ys map {y => x*y}}` | instrukcja for: iloczyn kartezjański | -| `for (x <- xs; y <- ys) {`
            `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
            `}` | instrukcja for: imperatywnie
            [sprintf-style](http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | -| `for (i <- 1 to 5) {`
            `println(i)`
            `}` | instrukcja for: iterowanie aż do górnej granicy | -| `for (i <- 1 until 5) {`
            `println(i)`
            `}` | instrukcja for: iterowanie poniżej górnej granicy | -| pattern matching (dopasowywanie wzorca) | | -| Dobrze `(xs zip ys) map { case (x,y) => x*y }`
            Źle `(xs zip ys) map( (x,y) => x*y )` | używaj słowa kluczowego case w funkcjach w celu dopasowywania wzorca (pattern matching). | -| Źle
            `val v42 = 42`
            `Some(3) match {`
            ` case Some(v42) => println("42")`
            ` case _ => println("Not 42")`
            `}` | "v42" jest interpretowane jako nazwa pasująca do każdej wartości typu Int, więc "42" zostaje wypisywane. | -| Dobrze
            `val v42 = 42`
            `Some(3) match {`
            `` case Some(`v42`) => println("42")``
            `case _ => println("Not 42")`
            `}` | "\`v42\`" z grawisami jest interpretowane jako istniejąca wartość `v42`, więc "Not 42" zostaje wypisywane. | -| Dobrze
            `val UppercaseVal = 42`
            `Some(3) match {`
            ` case Some(UppercaseVal) => println("42")`
            ` case _ => println("Not 42")`
            `}` | `UppercaseVal` jest traktowane jako istniejąca wartość, nie jako zmienna wzorca, bo zaczyna się z wielkiej litery. W takim razie wartość przechowywana w `UppercaseVal` jest porównywana z `3`, więc "Not 42" zostaje wypisywane. | -| obiektowość | | -| `class C(x: R)` _to samo co_
            `class C(private val x: R)`
            `var c = new C(4)` | parametry konstruktora - prywatne | -| `class C(val x: R)`
            `var c = new C(4)`
            `c.x` | parametry konstruktora - publiczne | -| `class C(var x: R) {`
            `assert(x > 0, "positive please")`
            `var y = x`
            `val readonly = 5`
            `private var secret = 1`
            `def this = this(42)`
            `}`|

            konstruktor jest ciałem klasy
            deklaracja publicznego pola
            deklaracja publicznej stałej
            deklaracja pola prywatnego
            alternatywny konstruktor| -| `new{ ... }` | klasa anonimowa | -| `abstract class D { ... }` | definicja klasy abstrakcyjnej. (nie da się stworzyć obiektu tej klasy) | -| `class C extends D { ... }` | definicja klasy pochodnej. | -| `class D(var x: R)`
            `class C(x: R) extends D(x)` | dziedziczenie i parametry konstruktora. (wishlist: domyślne, automatyczne przekazywanie parametrów) -| `object O extends D { ... }` | definicja singletona. (w stylu modułu) | -| `trait T { ... }`
            `class C extends T { ... }`
            `class C extends D with T { ... }` | cechy.
            interface'y z implementacją. bez parametrów konstruktora. [możliwość mixin'ów]({{ site.baseurl }}/tutorials/tour/mixin-class-composition.html). -| `trait T1; trait T2`
            `class C extends T1 with T2`
            `class C extends D with T1 with T2` | wiele cech. | -| `class C extends D { override def f = ...}` | w przeciążeniach funkcji wymagane jest słowo kluczowe override. | -| `new java.io.File("f")` | tworzenie obiektu. | -| Źle `new List[Int]`
            Dobrze `List(1,2,3)` | błąd typu: typ abstrakcyjny
            zamiast tego konwencja: wywoływalna fabryka przysłaniająca typ | -| `classOf[String]` | literał klasy. | -| `x.isInstanceOf[String]` | sprawdzenie typu (w czasie wykonania) | -| `x.asInstanceOf[String]` | rzutowanie typu (w czasie wykonania) | -| `x: String` | oznaczenie typu (w czasie kompilacji) | + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            zmienne 
            var x = 5

            Dobrze
            x = 6
            		Zmienna.
            val x = 5

            Źle
            x = 6
            		Stała.
            var x: Double = 5
            		Zmienna z podanym typem.
            funkcje
            Dobrze
            def f(x: Int) = { x * x }

            Źle
            def f(x: Int)   { x * x }
            		Definiowanie funkcji.
            Ukryty błąd: bez znaku = jest procedurą zwracającą Unit; powoduje to chaos. Przestarzałe w Scali 2.13.
            Dobrze
            def f(x: Any) = println(x)

            Źle
            def f(x) = println(x)
            		Definiowanie funkcji.
            Błąd składni: wymagane są typy dla każdego argumentu.
            type R = Double
            		Alias typu.
            def f(x: R)
            vs.
            def f(x: => R)
            		Wywoływanie przez wartość.

            Wywoływanie przez nazwę (parametr leniwy).
            (x: R) => x * x
            		Funkcja anonimowa.
            (1 to 5).map(_ * 2)
            vs.
            (1 to 5).reduceLeft(_ + _)
            		Funkcja anonimowa: podkreślenie to argument pozycyjny.
            (1 to 5).map(x => x * x)
            		Funkcja anonimowa: aby użyć argumentu dwa razy, musisz go nazwać
            Dobrze
            (1 to 5).map(2*)

            Źle
            (1 to 5).map(*2)
            		Funkcja anonimowa: związana metoda infiksowa. Możesz użyć także 2 * _.
            (1 to 5).map { x =>
+  val y = x * 2
+  println(y)
+  y
+}
            		Funkcja anonimowa: z bloku zwracane jest ostatnie wyrażenie.
            (1 to 5) filter {
+  _ % 2 == 0
+} map {
+  _ * 2
+}
            		Funkcja anonimowa: styl potokowy.
            def compose(g: R => R, h: R => R) =
+  (x: R) => g(h(x))

            val f = compose(_ * 2, _ - 1)
            		Funkcja anonimowa: aby przekazać kilka bloków musisz użyć nawiasów.
            val zscore =
+  (mean: R, sd: R) =>
+    (x: R) =>
+      (x - mean) / sd
            		Rozwijanie funkcji, oczywista składnia.
            def zscore(mean: R, sd: R) =
+  (x: R) =>
+    (x - mean) / sd
            		Rozwijanie funkcji, oczywista składnia
            def zscore(mean: R, sd: R)(x: R) =
+  (x - mean) / sd
            		Rozwijanie funkcji, lukier składniowy, ale wtedy:
            val normer =
+  zscore(7, 0.4) _
            		Potrzeba podążającego podkreślenia, aby wydobyć funkcję częściowo zaaplikowaną, tylko przy wersji z lukrem składniowym.
            def mapmake[T](g: T => T)(seq: List[T]) =
+  seq.map(g)
            		Typ generyczny.
            5.+(3); 5 + 3

            (1 to 5) map (_ * 2)
            		Lukier składniowy dla operatorów infiksowych.
            def sum(args: Int*) =
+  args.reduceLeft(_+_)
            		Zmienna liczba argumentów.
            pakiety 
            import scala.collection._
            		Import wszystkiego z pakietu.
            import scala.collection.Vector

            import scala.collection.{Vector, Sequence}
            		Import selektywny.
            import scala.collection.{Vector => Vec28}
            		Import ze zmianą nazwy.
            import java.util.{Date => _, _}
            		Importowanie wszystkiego z java.util poza Date.
            Na początku pliku: 
            package pkg

            Definiowanie pakietu według zakresu: 
            package pkg {
+  ...
+}

            Singleton dla pakietu: 
            package object pkg {
+  ...
+}
            		Deklaracja pakietu.
            struktury danych 
            (1, 2, 3)
            		Literał krotki (Tuple3).
            var (x, y, z) = (1, 2, 3)
            		Przypisanie z podziałem: rozpakowywanie krotki przy pomocy dopasowywania wzorca.
            Źle
            var x, y, z = (1, 2, 3)
            		Ukryty błąd: do każdego przypisana cała krotka.
            var xs = List(1, 2, 3)
            		Lista (niezmienna).
            xs(2)
            		Indeksowanie za pomocą nawiasów (slajdy).
            1 :: List(2, 3)
            		Operator dołożenia elementu na początek listy.
            1 to 5
            to samo co: 
            1 until 6

            1 to 10 by 2
            		Składnia dla przedziałów.
            ()
            		Jedyny obiekt typu Unit.
            Identyczny do void w C i Java.
            konstrukcje kontrolne 
            if (check) happy else sad
            		Warunek.
            if (check) happy
            +
            to samo co:
            + 
            if (check) happy else ()
            		Lukier składniowy dla warunku.
            while (x < 5) {
+  println(x)
+  x += 1
+}
            		Pętla while.
            do {
+  println(x)
+  x += 1
+} while (x < 5)
            		Pętla do-while.
            import scala.util.control.Breaks._
+
+breakable {
+  for (x <- xs) {
+    if (Math.random < 0.1)
+      break
+  }
+}
            		Instrukcja przerwania pętli (slajdy).
            for (x <- xs if x % 2 == 0)
+  yield x * 10
            +
            to samo co:
            + 
            xs.filter(_ % 2 == 0).map(_ * 10)
            		Intrukcja for: filtrowanie/mapowanie.
            for ((x, y) <- xs zip ys)
+  yield x * y
            +
            to samo co:
            + 
            (xs zip ys) map {
+  case (x, y) => x * y
+}
            		Instrukcja for: przypisanie z podziałem.
            for (x <- xs; y <- ys)
+  yield x * y
            +
            to samo co:
            + 
            xs flatMap { x =>
+  ys map { y =>
+    x * y
+  }
+}
            		Instrukcja for: iloczyn kartezjański.
            for (x <- xs; y <- ys) {
+  val div = x / y.toFloat
+  println("%d/%d = %.1f".format(x, y, div))
+}
            		Instrukcja for: imperatywnie.
            sprintf style.
            for (i <- 1 to 5) {
+  println(i)
+}
            		Instrukcja for: iterowanie aż do górnej granicy włącznie.
            for (i <- 1 until 5) {
+  println(i)
+}
            		Instrukcja for: iterowanie poniżej górnej granicy.
            pattern matching (dopasowywanie wzorca)
            Dobrze
            (xs zip ys) map {
+  case (x, y) => x * y
+}

            Źle
            (xs zip ys) map {
+  (x, y) => x * y
+}
            		Używaj słowa kluczowego case w funkcjach w celu dopasowywania wzorca.
            Źle
            + 
            val v42 = 42
+3 match {
+  case v42 => println("42")
+  case _   => println("Not 42")
+}
            		v42 jest interpretowane jako nazwa pasująca do każdej wartości typu Int, więc "42" zostaje wypisywane.
            Dobrze
            + 
            val v42 = 42
+3 match {
+  case `v42` => println("42")
+  case _     => println("Not 42")
+}
            		`v42` z grawisami jest interpretowane jako istniejąca wartośćv42, więc “Not 42” zostaje wypisywane.
            Dobrze
            + 
            val UppercaseVal = 42
+3 match {
+  case UppercaseVal => println("42")
+  case _            => println("Not 42")
+}
            		UppercaseVal jest traktowane jako istniejąca wartość, nie jako zmienna wzorca, bo zaczyna się z wielkiej litery. W takim razie wartość przechowywana w UppercaseVal jest porównywana z 3, więc “Not 42” jest wypisywane.
            obiektowość 
            class C(x: R)
            		Parametry konstruktora x - prywatne.
            class C(val x: R)

            var c = new C(4)

            c.x
            		Parametry konstruktora - publiczne.
            class C(var x: R) {
+  assert(x > 0, "positive please")
+  var y = x
+  val readonly = 5
+  private var secret = 1
+  def this = this(42)
+}
            		Konstruktor jest ciałem klasy.
            Deklaracja publicznego pola.
            Deklaracja publicznej stałej.
            Deklaracja pola prywatnego.
            Alternatywny konstruktor.
            new {
+  ...
+}
            		Instancja klasy anonimowej.
            abstract class D { ... }
            		Defiicja klasy abstrakcyjnej (nie da się stworzyć obiektu tej klasy).
            class C extends D { ... }
            		Definicja klasy pochodnej.
            class D(var x: R)

            class C(x: R) extends D(x)
            		Dziedziczenie i parametry konstruktora (wishlist: domyślne, automatyczne przekazywanie parametrów).
            object O extends D { ... }
            		Definicja singletona (w stylu modułu).
            trait T { ... }

            class C extends T { ... }

            class C extends D with T { ... }
            		Cechy.
            Interface'y z implementacją. Bez parametrów konstruktora. Możliwość mixin'ów.
            trait T1; trait T2

            class C extends T1 with T2

            class C extends D with T1 with T2
            		Wiele cech.
            class C extends D { override def f = ...}
            		W przeciążeniach funkcji wymagane jest słowo kluczowe override.
            new java.io.File("f")
            		Tworzenie obiektu.
            Źle
            new List[Int]

            Dobrze
            List(1, 2, 3)
            		Błąd typu: typ abstrakcyjny.
            Zamiast tego konwencja: wywoływalna fabryka przysłaniająca typ.
            classOf[String]
            		Literał klasy.
            x.isInstanceOf[String]
            		Sprawdzanie typu (w czasie wykonania).
            x.asInstanceOf[String]
            		Rzutowanie typu (w czasie wykonania).
            x: String
            		Oznaczenie typu (w czasie kompilacji).
            opcje 
            Some(42)
            		Tworzenie niepustej wartości opcjonalnej.
            None
            		Pojedyncza pusta wartość opcjonalna.
            Option(null) == None
+Option(obj.unsafeMethod)
            + ale + 
            Some(null) != None
            		Fabryka wartości opcjonalnych null-safe.
            val optStr: Option[String] = None
            + to samo co: + 
            val optStr = Option.empty[String]
            		Jawny typ pustej wartości opcjonalnej
            Fabryka dla pustej wartości opcjonalnej.
            val name: Option[String] =
+  request.getParameter("name")
+val upper = name.map {
+  _.trim
+} filter {
+  _.length != 0
+} map {
+  _.toUpperCase
+}
+println(upper.getOrElse(""))
            		Styl potokowy (pipeline).
            val upper = for {
+  name <- request.getParameter("name")
+  trimmed <- Some(name.trim)
+    if trimmed.length != 0
+  upper <- Some(trimmed.toUpperCase)
+} yield upper
+println(upper.getOrElse(""))
            		Składnia instrukcji for.
            option.map(f(_))
            + to samo co: + 
            option match {
+  case Some(x) => Some(f(x))
+  case None    => None
+}
            		Zastosuj funkcję do wartości opcjonalnej.
            option.flatMap(f(_))
            + to samo co: + 
            option match {
+  case Some(x) => f(x)
+  case None    => None
+}
            		To samo co map, ale funkcja musi zwracać opcjonalną wartość.
            optionOfOption.flatten
            + to samo co: + 
            optionOfOption match {
+  case Some(Some(x)) => Some(x)
+  case _             => None
+}
            		Wyodrębnij opcję zagnieżdżoną.
            option.foreach(f(_))
            + to samo co: + 
            option match {
+  case Some(x) => f(x)
+  case None    => ()
+}
            		Zastosuj procedurę na wartości opcjonalnej.
            option.fold(y)(f(_))
            + to samo co: + 
            option match {
+  case Some(x) => f(x)
+  case None    => y
+}
            		Zastosuj funkcję do wartości opcjonalnej, zwróć wartość domyślną, jeśli pusta.
            option.collect {
+  case x => ...
+}
            + to samo co: + 
            option match {
+  case Some(x) if f.isDefinedAt(x) => ...
+  case Some(_)                     => None
+  case None                        => None
+}
            		Zastosuj częściowe dopasowanie do wzorca dla wartości opcjonalnej.
            option.isDefined
            + to samo co: + 
            option match {
+  case Some(_) => true
+  case None    => false
+}
            		true jeżeli nie jest puste.
            option.isEmpty
            + to samo co: + 
            option match {
+  case Some(_) => false
+  case None    => true
+}
            		true jeżeli puste.
            option.nonEmpty
            + to samo co: + 
            option match {
+  case Some(_) => true
+  case None    => false
+}
            		true jeżeli nie jest puste.
            option.size
            + to samo co: + 
            option match {
+  case Some(_) => 1
+  case None    => 0
+}
            		0 jeżeli puste, w przeciwnym razie 1.
            option.orElse(Some(y))
            + to samo co: + 
            option match {
+  case Some(x) => Some(x)
+  case None    => Some(y)
+}
            		Oblicz i zwróć alternatywną wartość opcjonalną, jeżeli pierwotna wartość jest pusta.
            option.getOrElse(y)
            + to samo co: + 
            option match {
+  case Some(x) => x
+  case None    => y
+}
            		Oblicz i zwróć wartość domyślną, jeżeli pierwotna wartość jest pusta.
            option.get
            + to samo co: + 
            option match {
+  case Some(x) => x
+  case None    => throw new Exception
+}
            		Zwróć wartość, jeżeli pusta to rzuć wyjątek.
            option.orNull
            + to samo co: + 
            option match {
+  case Some(x) => x
+  case None    => null
+}
            		Zwróć wartość, null jeżeli pusta.
            option.filter(f)
            + to samo co: + 
            option match {
+  case Some(x) if f(x) => Some(x)
+  case _               => None
+}
            		Wartość opcjonalna spełnia predyktat.
            option.filterNot(f(_))
            + to samo co: + 
            option match {
+  case Some(x) if !f(x) => Some(x)
+  case _                => None
+}
            		Wartość opcjonalna nie spełnia predyktatu.
            option.exists(f(_))
            + to samo co: + 
            option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => false
+}
            		Zastosuj predyktat na wartości lub false jeżeli pusta.
            option.forall(f(_))
            + to samo co: + 
            option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => true
+}
            		Zastosuj predyktat na opcjonalnej wartości lub true jeżeli pusta.
            option.contains(y)
            + to samo co: + 
            option match {
+  case Some(x) => x == y
+  case None    => false
+}
            		Sprawdź, czy wartość jest równa wartości opcjonalnej lub false jeżeli pusta.
            diff --git a/_pl/tour/abstract-types.md b/_pl/tour/abstract-type-members.md similarity index 78% rename from _pl/tour/abstract-types.md rename to _pl/tour/abstract-type-members.md index 5e8a9a4e36..e79d551939 100644 --- a/_pl/tour/abstract-types.md +++ b/_pl/tour/abstract-type-members.md @@ -1,12 +1,9 @@ --- layout: tour title: Typy abstrakcyjne - -discourse: false - partof: scala-tour -num: 22 +num: 24 language: pl next-page: compound-types previous-page: inner-classes @@ -16,7 +13,7 @@ W Scali klasy są parametryzowane wartościami (parametry konstruktora) oraz typ Poniższy przykład definiuje wartość określaną przez abstrakcyjny typ będący elementem [cechy](traits.html) `Buffer`: -```tut +```scala mdoc trait Buffer { type T val element: T @@ -27,7 +24,7 @@ trait Buffer { W poniższym programie definiujemy klasę `SeqBuffer`, która ogranicza możliwe typy `T` do pochodnych sekwencji `Seq[U]` dla nowego typu `U`: -```tut +```scala mdoc:nest abstract class SeqBuffer extends Buffer { type U type T <: Seq[U] @@ -37,43 +34,40 @@ abstract class SeqBuffer extends Buffer { Cechy oraz [klasy](classes.html) z abstrakcyjnymi typami są często używane w połączeniu z anonimowymi klasami. Aby to zilustrować, wykorzystamy program, w którym utworzymy bufor sekwencji ograniczony do listy liczb całkowitych: -```tut +```scala mdoc:nest abstract class IntSeqBuffer extends SeqBuffer { type U = Int } -object AbstractTypeTest1 extends App { - def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = - new IntSeqBuffer { - type T = List[U] - val element = List(elem1, elem2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) -} +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) ``` Typ zwracany przez metodę `newIntSeqBuf` nawiązuje do specjalizacji cechy `Buffer`, w której typ `U` jest równy `Int`. Podobnie w anonimowej klasie tworzonej w metodzie `newIntSeqBuf` określamy `T` jako `List[Int]`. Warto zwrócić uwagę, że często jest możliwa zamiana abstrakcyjnych typów w parametry typów klas i odwrotnie. Poniższy przykład stosuje wyłącznie parametry typów: -```tut +```scala mdoc:nest abstract class Buffer[+T] { val element: T } abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { def length = element.length } -object AbstractTypeTest2 extends App { - def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = - new SeqBuffer[Int, List[Int]] { - val element = List(e1, e2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) -} + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) ``` Należy też pamiętać o zastosowaniu [adnotacji wariancji](variances.html). Inaczej nie byłoby możliwe ukrycie konkretnego typu sekwencji obiektu zwracanego przez metodę `newIntSeqBuf`. diff --git a/_pl/tour/annotations.md b/_pl/tour/annotations.md index 65921a156f..5124e8cb73 100644 --- a/_pl/tour/annotations.md +++ b/_pl/tour/annotations.md @@ -1,14 +1,11 @@ --- layout: tour title: Adnotacje - -discourse: false - partof: scala-tour -num: 31 -next-page: default-parameter-values -previous-page: automatic-closures +num: 33 +next-page: packages-and-imports +previous-page: by-name-parameters language: pl --- @@ -22,20 +19,19 @@ Znaczenie adnotacji jest zależne od implementacji. Na platformie Java poniższe | Scala | Java | | ------ | ------ | -| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (pole) | -| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | +| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](https://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (pole) | +| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](https://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | | [`scala.inline`](https://www.scala-lang.org/api/current/scala/inline.html) (since 2.6.0) | brak odpowiednika | -| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (since 2.6.0) | [`native`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | -| [`scala.remote`](https://www.scala-lang.org/api/current/scala/remote.html) | [`java.rmi.Remote`](http://java.sun.com/j2se/1.5.0/docs/api/java/rmi/Remote.html) | -| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | -| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | +| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (since 2.6.0) | [`native`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | +| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | +| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | | [`scala.unchecked`](https://www.scala-lang.org/api/current/scala/unchecked.html) (od 2.4.0) | brak odpowiednika | -| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | -| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`Design pattern`](http://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | +| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (słowo kluczowe) | +| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`Design pattern`](https://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | W poniższym przykładzie dodajemy adnotację `throws` do definicji metody `read` w celu obsługi rzuconego wyjątku w programie w Javie. -> Kompilator Javy sprawdza, czy program zawiera obsługę dla [wyjątków kontrolowanych](http://docs.oracle.com/javase/tutorial/essential/exceptions/index.html) poprzez sprawdzenie, które wyjątki mogą być wynikiem wykonania metody lub konstruktora. Dla każdego kontrolowanego wyjątku, który może być wynikiem wykonania, adnotacja **throws** musi określić klasę tego wyjątku lub jedną z jej klas bazowych. +> Kompilator Javy sprawdza, czy program zawiera obsługę dla [wyjątków kontrolowanych](https://docs.oracle.com/javase/tutorial/essential/exceptions/index.html) poprzez sprawdzenie, które wyjątki mogą być wynikiem wykonania metody lub konstruktora. Dla każdego kontrolowanego wyjątku, który może być wynikiem wykonania, adnotacja **throws** musi określić klasę tego wyjątku lub jedną z jej klas bazowych. > Ponieważ Scala nie pozwala na definiowanie wyjątków kontrolowanych, jeżeli chcemy obsłużyć wyjątek z kodu w Scali w Javie, należy dodać jedną lub więcej adnotacji `throws` określających klasy rzucanych wyjątków. ``` @@ -92,7 +88,7 @@ Java w wersji 1.5 wprowadziła możliwość definiowania metadanych przez użytk I następnie zastosować w taki sposób: ``` -@Source(URL = "http://coders.com/", +@Source(URL = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... ``` @@ -100,7 +96,7 @@ public class MyClass extends HisClass ... Zastosowanie adnotacji w Scali wygląda podobnie jak wywołanie konstruktora, gdzie wymagane jest podanie nazwanych argumentów: ``` -@Source(URL = "http://coders.com/", +@Source(URL = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` @@ -117,21 +113,21 @@ Składnia ta może się wydawać nieco nadmiarowa, jeżeli adnotacja składa si Następnie ją można zastosować: ``` -@SourceURL("http://coders.com/") +@SourceURL("https://coders.com/") public class MyClass extends HisClass ... ``` W tym przypadku Scala daje taką samą możliwość: ``` -@SourceURL("http://coders.com/") +@SourceURL("https://coders.com/") class MyScalaClass ... ``` Element `mail` został zdefiniowany z wartością domyślną, zatem nie musimy jawnie określać wartości dla niego. Jednakże, jeżeli chcemy tego dokonać, Java nie pozwala nam na mieszanie tych styli: ``` -@SourceURL(value = "http://coders.com/", +@SourceURL(value = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... ``` @@ -139,7 +135,7 @@ public class MyClass extends HisClass ... Scala daje nam większą elastyczność w tym aspekcie: ``` -@SourceURL("http://coders.com/", +@SourceURL("https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` diff --git a/_pl/tour/automatic-closures.md b/_pl/tour/automatic-closures.md deleted file mode 100644 index ca6c14eabf..0000000000 --- a/_pl/tour/automatic-closures.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -layout: tour -title: Automatyczna konstrukcja domknięć - -discourse: false - -partof: scala-tour - -num: 30 -language: pl -next-page: annotations -previous-page: operators ---- - -Scala pozwala na przekazywanie funkcji bezparametrycznych jako argumenty dla metod. Kiedy tego typu metoda jest wywołana, właściwe parametry dla funkcji bezparametrycznych nie są ewaluowane i przekazywana jest pusta funkcja, która enkapsuluje obliczenia odpowiadającego parametru (tzw. *wywołanie-przez-nazwę*). - -Poniższy kod demonstruje działanie tego mechanizmu: - -```tut -object TargetTest1 extends App { - def whileLoop(cond: => Boolean)(body: => Unit): Unit = - if (cond) { - body - whileLoop(cond)(body) - } - var i = 10 - whileLoop (i > 0) { - println(i) - i -= 1 - } -} -``` - -Funkcja `whileLoop` pobiera dwa parametry: `cond` i `body`. Kiedy funkcja jest aplikowana, jej właściwe parametry nie są ewaluowane. Lecz gdy te parametry są wykorzystane w ciele `whileLoop`, zostanie ewaluowana niejawnie utworzona funkcja zwracająca ich prawdziwą wartość. Zatem metoda `whileLoop` implementuje rekursywnie pętlę while w stylu Javy. - -Możemy połączyć ze sobą wykorzystanie [operatorów infiksowych/postfiksowych](operators.html) z tym mechanizmem aby utworzyć bardziej złożone wyrażenia. - -Oto implementacja pętli w stylu wykonaj-dopóki: - -```tut -object TargetTest2 extends App { - def loop(body: => Unit): LoopUnlessCond = - new LoopUnlessCond(body) - protected class LoopUnlessCond(body: => Unit) { - def unless(cond: => Boolean) { - body - if (!cond) unless(cond) - } - } - var i = 10 - loop { - println("i = " + i) - i -= 1 - } unless (i == 0) -} -``` - -Funkcja `loop` przyjmuje ciało pętli oraz zwraca instancję klasy `LoopUnlessCond` (która enkapsuluje to ciało). Warto zwrócić uwagę, że ciało tej funkcji nie zostało jeszcze ewaluowane. Klasa `LoopUnlessCond` posiada metodę `unless`, którą możemy wykorzystać jako *operator infiksowy*. W ten sposób uzyskaliśmy całkiem naturalną składnię dla naszej nowej pętli: `loop { < stats > } unless ( < cond > )`. - -Oto wynik działania programu `TargetTest2`: - -``` -i = 10 -i = 9 -i = 8 -i = 7 -i = 6 -i = 5 -i = 4 -i = 3 -i = 2 -i = 1 -``` - diff --git a/_pl/tour/basics.md b/_pl/tour/basics.md index 9ca6062b48..44ea200457 100644 --- a/_pl/tour/basics.md +++ b/_pl/tour/basics.md @@ -1,9 +1,319 @@ --- layout: tour -title: Basics - -discourse: false - +title: Podstawy partof: scala-tour + +num: 2 language: pl +next-page: unified-types +previous-page: tour-of-scala --- + +Na tej stronie omówimy podstawy języka Scala. + +## Uruchamianie Scali w przeglądarce + +Dzięki Scastie możesz uruchomić Scalę w swojej przeglądarce. + +1. Przejdź do [Scastie](https://scastie.scala-lang.org/). +2. Wklej kod `println("Hello, world!")` w polu po lewej stronie. +3. Naciśnij przycisk "Run". W panelu po prawej stronie pojawi się wynik działania programu. + +Jest to prosta i niewymagająca żadnej instalacji metoda do eksperymentowania z kodem w Scali. + +## Wyrażenia + +Wyrażenia są rezultatem ewaluacji fragmentów kodu. + +```scala mdoc +1 + 1 +``` + +Wyniki wyrażeń można wyświetlić za pomocą funkcji `println`. + +```scala mdoc +println(1) // 1 +println(1 + 1) // 2 +println("Hello!") // Hello! +println("Hello," + " world!") // Hello, world! +``` + +### Wartości + +Rezultaty wyrażeń mogą zostać nazwane za pomocą słowa kluczowego `val`. + +```scala mdoc +val x = 1 + 1 +println(x) // 2 +``` + +Nazwane wyniki, tak jak `x` w ww. przykładzie, to wartości. +Odniesienie się do wartości nie powoduje jej ponownego obliczenia. + +Wartości nie można przypisać ponownie. + +```scala mdoc:fail +x = 3 // Nie kompiluje się. +``` + +Typy wartości mogą być wywnioskowane przez kompilator, ale można również wyraźnie określić type: + +```scala mdoc:nest +val x: Int = 1 + 1 +``` + +Zauważ, że deklaracja `Int` pojawia po identyfikatorze `x`, potrzebny jest rówmież dwukropek `:`. + +### Zmienne + +Zmienne są podobne do wartości, ale z tym wyjątkiem, że można je ponownie przypisywać. +Zmienną można zdefiniować używając słowa kluczowego `var`. + +```scala mdoc:nest +var x = 1 + 1 +x = 3 // Kompiluje się, ponieważ "x" jest zdefiniowane z użyciem "var". +println(x * x) // 9 +``` + +Tak jak przy wartościach, można wyraźnie zdefiniować żądany typ: + +```scala mdoc:nest +var x: Int = 1 + 1 +``` + +## Wyrażenia blokowe + +Wyrażenia mogą być łączone poprzez zamknięcie ich w nawiasie klamrowym`{}`. +Taką konstrukcję nazywamy blokiem. +Wynikiem całego bloku kodu jest wynik ostatniego wyrażenia w tym bloku. + +```scala mdoc +println({ + val x = 1 + 1 + x + 1 +}) // 3 +``` + +## Funkcje + +Funkcje to wyrażenia, które przyjmują pewne parametry. + +Poniżej zdefiniowana jest funkcja anonimowa (nieposiadająca nazwy), która zwraca liczbę całkowitą przekazaną jako parametr, zwiększoną o 1. + +```scala mdoc +(x: Int) => x + 1 +``` + +Po lewej stronie od `=>` znajduje się lista parametrów. +Po prawej stronie - wyrażenie wykorzystujące te parametry. + +Funkcje można również nazywać. + +```scala mdoc +val addOne = (x: Int) => x + 1 +println(addOne(1)) // 2 +``` + +Funkcje mogą przyjmować wiele parametrów. + +```scala mdoc +val add = (x: Int, y: Int) => x + y +println(add(1, 2)) // 3 +``` + +Mogą też wcale nie mieć parametrow. + +```scala mdoc +val getTheAnswer = () => 42 +println(getTheAnswer()) // 42 +``` + +## Metody + +Metody wyglądają i zachowują się bardzo podobnie jak funkcje, jednak jest między nimi kilka kluczowych różnic. + +Metody są definiowane z użyciem słowa kluczowego `def`. +Po `def` następuje nazwa metody, lista parametrów, zwracany typ i ciało metody. + +```scala mdoc:nest +def add(x: Int, y: Int): Int = x + y +println(add(1, 2)) // 3 +``` + +Zauważ, że zwracany typ jest zadeklarowany _po_ liście parametrów i dwukropku `: Int`. + +Metody mogą mieć wiele list parametrów. + +```scala mdoc +def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier +println(addThenMultiply(1, 2)(3)) // 9 +``` + +Mogą również wcale ich nie posiadać. + +```scala mdoc +def name: String = System.getProperty("user.name") +println("Hello, " + name + "!") +``` + +Od funkcji odróżnia je jeszcze kilka innych rzeczy, ale na razie możesz o nich myśleć jak o bardzo podobnych do funkcji. + +Metody mogą zawierać również wyrażenia wielowierszowe. + +```scala mdoc +def getSquareString(input: Double): String = { + val square = input * input + square.toString +} +println(getSquareString(2.5)) // 6.25 +``` + +Ostatnie wyrażenie w ciele metody jest wartością, jaką zwraca cała metoda. +Scala posiada słowo kluczowe `return`, ale jest ono wykorzystywane bardzo rzadko. + +## Klasy + +Klasy są definiowane za pomocą słowa kluczowego `class`, po którym następuje nazwa klasy i parametry konstruktora. + +```scala mdoc +class Greeter(prefix: String, suffix: String) { + def greet(name: String): Unit = + println(prefix + name + suffix) +} +``` + +Metoda `greet` zwraca typ `Unit` - oznacza to, że nie ma nic znaczącego do zwrócenia. +`Unit` jest używany podobnie jak `void` w językach Java i C. +Różnica polega na tym, że w Scali każde wyrażenie musi zwracać jakąś wartosć, tak naprawdę istnieje [obiekt singleton](singleton-objects.html) typu `Unit` - nie niesie on ze sobą żadnej znaczącej informacji. + +Nowe instancje klasy tworzy się za pomocą słowa kluczowego `new`. + +```scala mdoc +val greeter = new Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` + +Klasy zostaną szerzej omówione w [dalszej części](classes.html) tego przewodnika. + +## Klasy przypadku (case classes) + +W Scali istnieje spacjalny typ klasy - klasa "przypadku" (case class). +Klasy przypadku są domyślnie niezmienne i porównywane przez wartości. +Klasy te można definiować używająć słów kluczowych `case class`. + +```scala mdoc +case class Point(x: Int, y: Int) +``` + +Do utworzenia nowej instacji klasy przypadku nie jest konieczne używanie słowa kluczowego `new`. + +```scala mdoc +val point = Point(1, 2) +val anotherPoint = Point(1, 2) +val yetAnotherPoint = Point(2, 2) +``` + +Są one porównywane przez wartości - _nie_ przez referencje. + +```scala mdoc +if (point == anotherPoint) { + println(s"$point i $anotherPoint są jednakowe.") +} else { + println(s"$point i $anotherPoint są inne.") +} // Point(1,2) i Point(1,2) są jednakowe. + +if (point == yetAnotherPoint) { + println(s"$point i $yetAnotherPoint są jednakowe.") +} else { + println(s"$point i $yetAnotherPoint są inne.") +} // Point(1,2) i Point(2,2) są inne. +``` + +Klasy przypadków to dużo szerszy temat, do zapoznania z którym bardzo zachęcamy. Jesteśmy pewni, że Ci się spodoba! +Jest on dokładnie omówiony w [późniejszym rozdziale](case-classes.html). + +## Obiekty + +Obiekty to pojedyncze wystąpienia ich definicji. +Można o nich myśleć jak o instancjach ich własnych klas - singletonach. + +Objekty definiuje się z użyciem słowa kluczowego `object`. + +```scala mdoc +object IdFactory { + private var counter = 0 + def create(): Int = { + counter += 1 + counter + } +} +``` + +Aby uzyskać dostęp do obiektu używa się jego nazwy. + +```scala mdoc +val newId: Int = IdFactory.create() +println(newId) // 1 +val newerId: Int = IdFactory.create() +println(newerId) // 2 +``` + +Obiekty zostaną szerzej omówione [później](singleton-objects.html). + +## Cechy (traits) + +Cechy to typy zawierające pewne pola i metody. +Wiele cech może być łączonych. + +Cechę (trait) można zdefiniować używając słowa kluczowego `trait`. + +```scala mdoc:nest +trait Greeter { + def greet(name: String): Unit +} +``` + +Cechy mogą zawierać domyślną implementację. + +```scala mdoc:reset +trait Greeter { + def greet(name: String): Unit = + println("Hello, " + name + "!") +} +``` + +Cechy można rozszerzać używając słowa kluczowego `extends` i nadpisać implementację z użyciem `override`. + +```scala mdoc +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { + override def greet(name: String): Unit = { + println(prefix + name + postfix) + } +} + +val greeter = new DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = new CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` + +W tym przykładzie `DefaultGreeter` rozszerza tylko jedną cechę (trait), ale równie dobrze może rozszerzać ich wiele. + +Cechy zostały dokładniej opisane w jednym z [kolejnych](traits.html) rozdziałów. + +## Metoda Main + +Metoda `main` to punkt wejścia do programu. +Maszyna Wirtalna Javy (Java Virtual Machine / JVM) wymaga, aby metoda ta nazywała się "main" i posiadała jeden arguemnt - tablicę ciągów znaków. + +Z użyciem obiektu można zdefiniować metodę `main` w następujący sposób: + +```scala mdoc +object Main { + def main(args: Array[String]): Unit = + println("Hello, Scala developer!") +} +``` diff --git a/_pl/tour/by-name-parameters.md b/_pl/tour/by-name-parameters.md index d0bdd220a3..21cf9cc758 100644 --- a/_pl/tour/by-name-parameters.md +++ b/_pl/tour/by-name-parameters.md @@ -1,9 +1,41 @@ --- layout: tour -title: By-name Parameters - -discourse: false - +title: Parametry przekazywane według nazwy partof: scala-tour + +num: 32 +next-page: annotations +previous-page: operators language: pl --- + +_Parametry przekazywane według nazwy_ są ewaluowane za każdym razem gdy są używane. Nie zostaną w ogóle wyewaluowane jeśli nie będą używane. Jest to podobne do zastępowania parametrów w ciele funkcji wyrażeniami podanymi w miejscu jej wywołania. Są przeciwieństwem do _parametrów przekazywanych według wartości_. Aby utworzyć parametr przekazywany według nazwy, po prostu dodaj `=>` przed jego typem. + +```scala mdoc +def calculate(input: => Int) = input * 37 +``` + +Parametry przekazywane według nazwy mają tę zaletę że nie są ewaluowane jeśli nie są używane w treści funkcji. Z drugiej strony parametry według wartości mają tę zaletę, że są ewaluowane tylko raz. + +Oto przykład, jak możemy zaimplementować pętlę while: + +```scala mdoc +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if (condition) { + body + whileLoop(condition)(body) + } + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // prints 2 1 +``` + +Metoda `whileLoop` używa wielu list parametrów do określenia warunku i treści pętli. Jeśli `condition` (warunek) jest prawdziwy, `body` (treść) jest wykonywana a następnie wykonywane jest rekurencyjne wywołanie `whileLoop`. Jeśli `condition` jest fałszywy, treść nigdy nie jest ewaluowana, ponieważ dodaliśmy `=>` do typu `body`. + +Jeśli przekażemy `i>0` jako nasz `condition` (warunek) i `println(i); i-= 1` jako `body`, nasze wyrażenie zachowuje się jak standardowa pętla while w wielu językach. + +Ta możliwość opóźnienia ewaluacji parametru do czasu jego użycia może zwiększyć wydajność, jeśli ewaluacja parametru wymaga intensywnych obliczeń lub dłużej działającego bloku kodu, takiego jak pobieranie treści spod adresu URL. diff --git a/_pl/tour/case-classes.md b/_pl/tour/case-classes.md index 48c6683418..cc7346a277 100644 --- a/_pl/tour/case-classes.md +++ b/_pl/tour/case-classes.md @@ -1,133 +1,72 @@ --- layout: tour title: Klasy przypadków - -discourse: false - partof: scala-tour -num: 10 +num: 13 language: pl next-page: pattern-matching previous-page: multiple-parameter-lists --- -Scala wspiera mechanizm _klas przypadków_. Klasy przypadków są zwykłymi klasami z dodatkowymi założeniami: +Scala wspiera mechanizm _klas przypadków_ (ang. case class). +Są one zwykłymi klasami z dodatkowymi założeniami, przez które przejdziemy. +Klasy przypadków idealnie nadają się do modelowania niezmiennych (niemutowalnych) danych. +W dalszych rozdziałach przyjrzymy się jak przydają się w [dopasowywaniu wzorców (ang. pattern matching)](pattern-matching.html). -* Domyślnie niemutowalne -* Można je dekomponować poprzez [dopasowanie wzorca](pattern-matching.html) -* Porównywane poprzez podobieństwo strukturalne zamiast przez referencje -* Zwięzła składnia tworzenia obiektów i operacji na nich +## Definiowanie klas przypadków -Poniższy przykład obrazuje hierarchię typów powiadomień, która składa się z abstrakcyjnej klasy `Notification` oraz trzech konkretnych rodzajów zaimplementowanych jako klasy przypadków `Email`, `SMS` i `VoiceRecording`: - -```tut -abstract class Notification -case class Email(sourceEmail: String, title: String, body: String) extends Notification -case class SMS(sourceNumber: String, message: String) extends Notification -case class VoiceRecording(contactName: String, link: String) extends Notification -``` +Minimalna definicja klasy przypadku wymaga słów kluczowych `case class`, identyfikatora oraz listy parametrów (może być pusta): -Tworzenie obiektu jest bardzo proste: (Zwróć uwagę na to, że słowo `new` nie jest wymagane) +```scala mdoc +case class Book(isbn: String) -```tut -val emailFromJohn = Email("john.doe@mail.com", "Greetings From John!", "Hello World!") +val frankenstein = Book("978-0486282114") ``` -Parametry konstruktora klasy przypadków są traktowane jako publiczne wartości i można się do nich odwoływać bezpośrednio: +Zauważ, że słowo kluczowe `new` nie było konieczne do stworzenia instancji klasy przypadku `Book`. +Jest tak, ponieważ klasy przypadków posiadają domyślnie zdefiniowaną metodę `apply`, która zajmuje się tworzeniem obiektu klasy. -```tut -val title = emailFromJohn.title -println(title) // wypisuje "Greetings From John!" -``` - -W klasach przypadków nie można modyfikować wartości pól. (Z wyjątkiem sytuacji kiedy dodasz `var` przed nazwą pola) +W przypadku, kiedy tworzymy klasę przypadku zawierającą parametry, są one publiczne i stałe (`val`). -```tut:fail -emailFromJohn.title = "Goodbye From John!" // Jest to błąd kompilacji, gdyż pola klasy przypadku są domyślnie niezmienne ``` +case class Message(sender: String, recipient: String, body: String) +val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") -Zamiast tego możesz utworzyć kopię używając metody `copy`: - -```tut -val editedEmail = emailFromJohn.copy(title = "I am learning Scala!", body = "It's so cool!") - -println(emailFromJohn) // wypisuje "Email(john.doe@mail.com,Greetings From John!,Hello World!)" -println(editedEmail) // wypisuje "Email(john.doe@mail.com,I am learning Scala,It's so cool!)" +println(message1.sender) // wypisze guillaume@quebec.ca +message1.sender = "travis@washington.us" // ten wiersz nie skompiluje się ``` -Dla każdej klasy przypadku kompilator Scali wygeneruje metodę `equals` implementującą strukturalne porównanie obiektów oraz metodę `toString`. Przykład: - -```tut -val firstSms = SMS("12345", "Hello!") -val secondSms = SMS("12345", "Hello!") +Nie można ponownie przydzielić wartości do `message1.sender`, ponieważ jest to `val` (stała). +Alternatywnie, w klasach przypadków można też używać `var`, jednak stanowczo tego odradzamy. -if (firstSms == secondSms) { - println("They are equal!") -} +## Porównywanie -println("SMS is: " + firstSms) -``` +Klasy przypadków są porównywane według ich struktury, a nie przez referencje: -Wypisze: +```scala mdoc +case class Message(sender: String, recipient: String, body: String) -``` -They are equal! -SMS is: SMS(12345, Hello!) +val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val messagesAreTheSame = message2 == message3 // true ``` -Jednym z najważniejszych zastosowań klas przypadków (skąd też się wzięła ich nazwa) jest **dopasowanie wzorca**. Poniższy przykład pokazuje działanie funkcji, która zwraca różne komunikaty w zależności od rodzaju powiadomienia: - -```tut -def showNotification(notification: Notification): String = { - notification match { - case Email(email, title, _) => - "You got an email from " + email + " with title: " + title - case SMS(number, message) => - "You got an SMS from " + number + "! Message: " + message - case VoiceRecording(name, link) => - "you received a Voice Recording from " + name + "! Click the link to hear it: " + link - } -} - -val someSms = SMS("12345", "Are you there?") -val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") - -println(showNotification(someSms)) // Wypisuje "You got an SMS from 12345! Message: Are you there?" -println(showNotification(someVoiceRecording)) // Wypisuje "you received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123" -``` +Mimo, że `message1` oraz `message2` odnoszą się do innych obiektów, to ich wartości są identyczne. -Poniżej bardziej skomplikowany przykład używający `if` w celu określenia dodatkowych warunków dopasowania: - -```tut -def showNotificationSpecial(notification: Notification, specialEmail: String, specialNumber: String): String = { - notification match { - case Email(email, _, _) if email == specialEmail => - "You got an email from special someone!" - case SMS(number, _) if number == specialNumber => - "You got an SMS from special someone!" - case other => - showNotification(other) // nic szczególnego, wywołaj domyślną metodę showNotification - } -} - -val SPECIAL_NUMBER = "55555" -val SPECIAL_EMAIL = "jane@mail.com" -val someSms = SMS("12345", "Are you there?") -val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") -val specialEmail = Email("jane@mail.com", "Drinks tonight?", "I'm free after 5!") -val specialSms = SMS("55555", "I'm here! Where are you?") - -println(showNotificationSpecial(someSms, SPECIAL_EMAIL, SPECIAL_NUMBER)) // Wypisuje "You got an SMS from 12345! Message: Are you there?" -println(showNotificationSpecial(someVoiceRecording, SPECIAL_EMAIL, SPECIAL_NUMBER)) // Wypisuje "you received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123" -println(showNotificationSpecial(specialEmail, SPECIAL_EMAIL, SPECIAL_NUMBER)) // Wypisuje "You got an email from special someone!" -println(showNotificationSpecial(specialSms, SPECIAL_EMAIL, SPECIAL_NUMBER)) // Wypisuje "You got an SMS from special someone!" -``` +## Kopiowanie -Programując w Scali zachęca się, abyś jak najszerzej używał klas przypadków do modelowania danych, jako że kod, który je wykorzystuje, jest bardziej ekspresywny i łatwiejszy do utrzymania: +Możliwe jest stworzenie płytkiej kopii (ang. shallow copy) instancji klasy przypadku używając metody `copy`. +Opcjonalnie można zmienić jeszcze wybrane parametry konstruktora. -* Obiekty niemutowalne uwalniają cię od potrzeby śledzenia zmian stanu -* Porównanie przez wartość pozwala na porównywanie instancji tak, jakby były prymitywnymi wartościami -* Dopasowanie wzorca znacząco upraszcza logikę rozgałęzień, co prowadzi do mniejszej ilości błędów i czytelniejszego kodu +```scala mdoc:nest +case class Message(sender: String, recipient: String, body: String) +val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") +val message5 = message4.copy(sender = message4.recipient, recipient = "claire@bourgogne.fr") +message5.sender // travis@washington.us +message5.recipient // claire@bourgogne.fr +message5.body // "Me zo o komz gant ma amezeg" +``` +Odbiorca wiadomości 4 `message4.recipient` jest użyty jako nadawca wiadomości 5 `message5.sender`, ciało wiadomości 5 zostało skopiowane bez zmian z wiadomości 4. diff --git a/_pl/tour/classes.md b/_pl/tour/classes.md index 24a69c466c..00a4734cbd 100644 --- a/_pl/tour/classes.md +++ b/_pl/tour/classes.md @@ -1,54 +1,129 @@ --- layout: tour title: Klasy - -discourse: false - partof: scala-tour -num: 3 +num: 4 language: pl -next-page: traits +next-page: default-parameter-values previous-page: unified-types --- -Klasy w Scali określają schemat obiektów podczas wykonania programu. Oto przykład definicji klasy `Point`: +Klasy w Scali są wzorcami do tworzenia obiektów. +Klasy mogą zawierać metody, wartości, zmienne, typy, obiekty, cechy i klasy; wszystkie one są nazywane składnikami klasy (_class members_). +Typy, obiekty i cechy zostaną omówione w dalszej części przewodnika. + +## Definiowanie klasy + +Minimalna definicja klasy składa się ze słowa kluczowego `class` oraz jej identyfikatora. +Nazwy klas powinny zaczynać się z wielkiej litery. + +```scala mdoc +class User + +val user1 = new User +``` + +Do tworzenia nowych instancji klasy służy słowo kluczowe `new`. +Ponieważ żaden konstruktor nie został zdefiniowany, klasa `User` posiada konstruktor domyślny, który nie przyjmuje żadnych parametrów. +Zazwyczaj jednak definiujemy konstruktor i ciało klasy. +Poniższy przykład przedstawia definicję klasy służącej do reprezentowania punktu. -```tut +```scala mdoc class Point(var x: Int, var y: Int) { + def move(dx: Int, dy: Int): Unit = { x = x + dx y = y + dy } + override def toString: String = - "(" + x + ", " + y + ")" + s"($x, $y)" } + +val point1 = new Point(2, 3) +point1.x // 2 +println(point1) // wyświetla (2, 3) ``` -Klasy w Scali są sparametryzowane poprzez argumenty konstruktora. Powyższy kod wymaga podania dwóch argumentów konstruktora: `x` i `y`. Oba parametry są widoczne w zasięgu ciała klasy. +Klasa `Point` ma cztery składniki: zmienne `x` i `y` oraz metody `move` i `toString`. +W przeciwieństwie do innych języków programowania, główny konstruktor zawiera się w sygnaturze klasy: `(var x: Int, var y: Int)`. +Metoda `move` przyjmuje jako parametry dwie liczby całkowite i zwraca wartość `()` typu `Unit`, która nie niesie ze sobą żadnych informacji. +Odpowiada to słowu kluczowemu `void` w językach Java - podobnych. +Metoda `toString` nie przyjmuje żadnych parametrów, ale zwraca wartość typu `String`. +Ponieważ `toString` nadpisuje metodę `toString` zdefiniowaną w [`AnyRef`](unified-types.html), jest ona dodatkowo oznaczona słowem kluczowym `override`. -Klasa `Point` zawiera także dwie metody: `move` i `toString`. `move` pobiera dwa argumenty w postaci liczb całkowitych, ale nie zwraca żadnej wartości (zwracany typ `Unit` odpowiada `void` w językach takich jak Java). Z drugiej strony `toString` nie wymaga żadnych parametrów, ale zwraca łańcuch znaków typu `String`. Ponieważ `toString` przesłania predefiniowaną metodę `toString`, jest ona oznaczona słowem kluczowym `override`. +## Konstruktory -Należy dodać, że w Scali nie jest wymagane podanie słowa kluczowego `return` w celu zwrócenia wartości. Dzięki temu, że każdy blok kodu w Scali jest wyrażeniem, wartością zwracaną przez metodę jest ostatnie wyrażenie w ciele metody. Dodatkowo proste wyrażenia, takie jak zaprezentowane na przykładzie implementacji `toString` nie wymagają podania klamer, zatem można je umieścić bezpośrednio po definicji metody. +Konstruktory mogą zawierać parametry opcjonalne - wystarczy dostarczyć wartość domyślną dla takiego parametru. -Instancje klasy można tworzyć w następujący sposób: +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) + +val origin = new Point // x i y są mają wartość 0 +val point1 = new Point(1) +println(point1.x) // wyświetla 1 + +``` -```tut -object Classes { - def main(args: Array[String]) { - val pt = new Point(1, 2) - println(pt) - pt.move(10, 10) - println(pt) +W tej wersji klasy `Point`, `x` oraz `y` mają domyślną wartość `0` - dlatego nie jest wymagane przekazanie żadnych parametrów. +Jednak z powodu tego, że konstruktor jest ewaluowany od lewej do prawej strony, jeżeli chcesz przekazać parametr tylko do argumentu `y`, musisz określić nazwę tego parametru. + +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) +val point2 = new Point(y = 2) +println(point2.y) // wyświetla 2 +``` + +Jest to również dobra praktyka, która zwiększa przejrzystość kodu. + +## Prywatne składniki oraz składnia getterów i setterów + +Domyślnie wszystkie składniki klasy są publiczne. +Aby ukryć je przed zewnętrznymi klientami (wszystkim co jest poza daną klasą), należy użyć słowa kluczowego `private`. + +```scala mdoc:nest +class Point { + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x = _x + def x_= (newValue: Int): Unit = { + if (newValue < bound) _x = newValue else printWarning } + + def y = _y + def y_= (newValue: Int): Unit = { + if (newValue < bound) _y = newValue else printWarning + } + + private def printWarning = println("UWAGA: wartość poza przedziałem") } + +val point1 = new Point +point1.x = 99 +point1.y = 101 // wyświetla ostrzeżenie ``` -Program definiuje wykonywalną aplikację w postaci [obiektu singleton](singleton-objects.html) z główną metodą `main`. Metoda `main` tworzy nową instancję typu `Point` i zapisuje ją do wartości `pt`. Istotną rzeczą jest to, że wartości zdefiniowane z użyciem słowa kluczowego `val` różnią się od zmiennych określonych przez `var` (jak w klasie `Point` powyżej) tym, że nie dopuszczają aktualizacji ich wartości. +W powyższym przykładnie klasy `Point` dane przechowywane są w prywatnych zmiennych `_x` i `_y`. +Publiczne metody `def x` i `def y` istnieją w celu uzyskania dostępu do prywatnych danych - są to gettery. +Metody `def x_=` i `def y_=` (settery) służą do walidacji oraz ustawiania wartości zmiennych `_x` i `_y`. +Zwróć uwagę na specyficzną składnię dla setterów: posiadają one `_=` dołączone do nazwy, dopiero w dalszej kolejności zdefiniowane są ich parametry. -Wynik działania programu: +Parametry głównego konstruktora oznaczone przez `val` i `var` są publiczne. +Ponieważ `val` jest niezmienne, poniższy kod nie jest prawidłowy +```scala mdoc:fail +class Point(val x: Int, val y: Int) +val point = new Point(1, 2) +point.x = 3 // <-- nie kompiluje się ``` -(1, 2) -(11, 12) + +Parametry konstruktora __nie__ zawierające `val` lub `var` są prywatne - widoczne jedynie we wnętrzu klasy. + +```scala mdoc:fail +class Point(x: Int, y: Int) +val point = new Point(1, 2) +point.x // <-- nie kompiluje się ``` diff --git a/_pl/tour/compound-types.md b/_pl/tour/compound-types.md index 278efe5be4..c60b379f7b 100644 --- a/_pl/tour/compound-types.md +++ b/_pl/tour/compound-types.md @@ -1,22 +1,19 @@ --- layout: tour title: Typy złożone - -discourse: false - partof: scala-tour -num: 23 +num: 25 language: pl next-page: self-types -previous-page: abstract-types +previous-page: abstract-type-members --- Czasami konieczne jest wyrażenie, że dany typ jest podtypem kilku innych typów. W Scali wyraża się to za pomocą *typów złożonych*, które są częścią wspólną typów obiektów. Załóżmy, że mamy dwie cechy `Cloneable` i `Resetable`: -```tut +```scala mdoc trait Cloneable extends java.lang.Cloneable { override def clone(): Cloneable = { super.clone().asInstanceOf[Cloneable] @@ -50,4 +47,4 @@ def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { Typy złożone mogą składać się z kilku typów obiektów i mogą mieć tylko jedno wyrafinowanie, które może być użyte do zawężenia sygnatury istniejących elementów obiektu. Przyjmują one postać: `A with B with C ... { wyrafinowanie }` -Przykład użycia wyrafinowania typów jest pokazany na stronie o [typach abstrakcyjnych](abstract-types.html). +Przykład użycia wyrafinowania typów jest pokazany na stronie o [typach abstrakcyjnych](abstract-type-members.html). diff --git a/_pl/tour/default-parameter-values.md b/_pl/tour/default-parameter-values.md index f1eddf538f..460356deaf 100644 --- a/_pl/tour/default-parameter-values.md +++ b/_pl/tour/default-parameter-values.md @@ -1,15 +1,12 @@ --- layout: tour title: Domyślne wartości parametrów - -discourse: false - partof: scala-tour -num: 32 +num: 5 language: pl next-page: named-arguments -previous-page: annotations +previous-page: classes --- Scala zezwala na określenie domyślnych wartości dla parametrów, co pozwala wyrażeniu wywołującemu ją na pominięcie tych parametrów. @@ -53,7 +50,7 @@ Mimo że powstrzymuje to nas od powtarzania się, to podejście nie jest zbyt wy Scala wprowadza bezpośrednie wsparcie dla domyślnych parametrów: -```tut +```scala mdoc class HashMap[K,V](initialCapacity: Int = 16, loadFactor: Float = 0.75f) { } diff --git a/_pl/tour/extractor-objects.md b/_pl/tour/extractor-objects.md index 306b96d478..17fa3461d7 100644 --- a/_pl/tour/extractor-objects.md +++ b/_pl/tour/extractor-objects.md @@ -1,20 +1,17 @@ --- layout: tour title: Obiekty ekstraktorów - -discourse: false - partof: scala-tour -num: 15 +num: 17 language: pl -next-page: generic-classes +next-page: for-comprehensions previous-page: regular-expression-patterns --- W Scali wzorce mogą być zdefiniowane niezależnie od klas przypadków. Obiekt posiadający metodę `unapply` może funkcjonować jako tak zwany ekstraktor. Jest to szczególna metoda, która pozwala na odwrócenie zastosowania obiektu dla pewnych danych. Jego celem jest ekstrakcja danych, z których został on utworzony. Dla przykładu, poniższy kod definiuje ekstraktor dla [obiektu](singleton-objects.html) `Twice`: -```tut +```scala mdoc object Twice { def apply(x: Int): Int = x * 2 def unapply(z: Int): Option[Int] = if (z%2 == 0) Some(z/2) else None diff --git a/_pl/tour/for-comprehensions.md b/_pl/tour/for-comprehensions.md index 4c64e85d08..6d0c3ab0c9 100644 --- a/_pl/tour/for-comprehensions.md +++ b/_pl/tour/for-comprehensions.md @@ -1,9 +1,90 @@ --- layout: tour title: For Comprehensions - -discourse: false - partof: scala-tour + +num: 18 language: pl +next-page: generic-classes +previous-page: extractor-objects --- + +Trudno znaleźć dobre tłumaczenie _for comprehensions_ w języku polskim, dlatego stosujemy wersję angielską. + +Scala oferuje prostą w zapisie formę wyrażania _sequence comprehensions._ +_For comprehensions_ przedstawione jest w formie `for (enumerators) yield e`, gdzie `enumerators` to lista enumeratorów oddzielonych średnikami. _Enumerator_ może być zarówno generatorem nowych wartości lub filtrem dla wartości przetwarzanych. Wyrażenie to definiuje ciało `e` dla każdej wartości wywołanej przez enumerator i zwraca te wartości w postaci sekwencji. + +Poniżej znajduje się przykład, który przekształca listę osób na listę imion osób, których wiek mieści się w przedziale od 30 do 40 lat. + +```scala mdoc +case class Person(name: String, age: Int) + +val people = List( + Person("Monika", 25), + Person("Czarek", 35), + Person("Marcin", 26), + Person("Filip", 25) +) + +val names = for ( + person <- people if (person.age >=30 && person.age < 40) +) yield person.name // czyli dodaj do listy wynikowej + +names.foreach(name => println(name)) // wydrukowane zostanie: Czarek +``` + +Na początku `for` znajduje się generator `person <- people`. Następujące po tym wyrażenie warunkowe `if (person.age >=30 && person.age < 40)` odfiltrowuje wszystkie osoby poniżej 30 i powyżej 40 roku życia. W powyższym przykładzie po wyrażeniu `yield` wywołano `person.name`, `name` jest typu `String`, więc lista wynikowa będzie typu `List[String]`. W ten sposób lista typu `List[Person]` została przekształcona na listę `Lista[String]`. + +Poniżej znajduje się bardziej złożony przykład, który używa dwóch generatorów. Jego zadaniem jest sprawdzenie wszystkich par liczb od `0` do `n-1` i wybór tylko tych par, których wartości są sobie równe. + +```scala mdoc +def someTuple(n: Int) = + for ( + i <- 0 until n; + j <- 0 until n if i == j + ) yield (i, j) + +someTuple(10) foreach { + case (i, j) => + println(s"($i, $j) ") // drukuje (0, 0) (1, 1) (2, 2) (3, 3) (4, 4) (5, 5) (6, 6) (7, 7) (8, 8) (9, 9) +} +``` + +Załóżmy, że wartością początkową jest `n == 10`. W pierwszej iteracji `i` przyjmuje wartość równą `0` tak samo jak `j`, filtr `i == j` zwróci `true` więc zostanie przekazane do `yield`. W kolejnej iteracji `j` przyjmie wartość równą `1`, więc `i == j` zwróci `false`, ponieważ `0 != 1` i nie zostanie przekazane do `yield`. Kolejne osiem iteracji to zwiększanie wartości `j` aż osiągnie wartość równą `9`. W następnej iteracji `j` powraca do wartości `0`, a `i` zostaje zwiększona o `1`. Gdyby w powyższym przykładzie nie umieszczono filtra `i == j` wydrukowana zostałaby prosta sekwencja: + +``` +(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... +``` + +Bardzo istotne jest to, że comprehensions nie są ograniczone do list. Każdy typ danych, który wspiera operację `withFilter`, `map` czy `flatMap` (z odpowiednim typem) może być użyty w _sequence comprehensions_. + +Przykładem innego użycia _comprehensions_ jest jego wykorzystanie do obsługi typu `Option`. +Załóżmy, że mamy dwie wartości `Option[String]` i chcielibyśmy zwrócić obiekt `Student(imie: String, nazwisko: String` tylko gdy obie wartości są zadeklarowane - nie są `None`. + +Spójrzmy poniżej: + +```scala mdoc +case class Student(name: String, surname: String) + +val nameOpt: Option[String] = Some("John") +val surnameOpt: Option[String] = Some("Casey") + +val student = for { + name <- nameOpt + surname <- surnameOpt + } yield Student(name, surname) // wynik będzie typu Option[Student]. +``` + +Jeżeli `name` lub `surname` nie byłyby określone, np. przyjmowałyby wartość równą `None` to zmienna `student` również byłaby `None`. Powyższy przykład to przekształcenie dwóch wartości `Option[String]` na `Option[Student]`. + +Wszystkie powyższe przykłady posiadały wyrażenie `yield` na końcu _comprehensions_, jednak nie jest to obligatoryjne. Gdy `yield` nie zostanie dodanie zwrócony zostanie `Unit`. Takie rozwiązanie może być przydatne gdy chcemy uzyskać jakieś skutki uboczne. Poniższy przykład wypisuje liczby od 0 do 9 bez użycia `yield`. + + +```scala mdoc +def count(n: Int) = + for (i <- 0 until n) + println(s"$i ") + +count(10) // wyświetli "0 1 2 3 4 5 6 7 8 9 " +``` + diff --git a/_pl/tour/generic-classes.md b/_pl/tour/generic-classes.md index c570e76ecc..ac011270b3 100644 --- a/_pl/tour/generic-classes.md +++ b/_pl/tour/generic-classes.md @@ -1,27 +1,25 @@ --- layout: tour title: Klasy generyczne - -discourse: false - partof: scala-tour -num: 17 +num: 19 language: pl next-page: variances -previous-page: extractor-objects +previous-page: for-comprehensions --- Scala posiada wbudowaną obsługą klas parametryzowanych przez typy. Tego typu klasy generyczne są szczególnie użyteczne podczas tworzenia klas kolekcji. Poniższy przykład demonstruje zastosowanie parametrów generycznych: -```tut +```scala mdoc class Stack[T] { var elems: List[T] = Nil - def push(x: T) { elems = x :: elems } + def push(x: T): Unit = + elems = x :: elems def top: T = elems.head - def pop() { elems = elems.tail } + def pop(): Unit = { elems = elems.tail } } ``` @@ -29,7 +27,7 @@ Klasa `Stack` modeluje zmienny stos zawierający elementy dowolnego typu `T`. Pa Przykłady zastosowania: -```tut +```scala mdoc object GenericsTest extends App { val stack = new Stack[Int] stack.push(1) diff --git a/_pl/tour/higher-order-functions.md b/_pl/tour/higher-order-functions.md index 8d9ee188bb..2a1a919e04 100644 --- a/_pl/tour/higher-order-functions.md +++ b/_pl/tour/higher-order-functions.md @@ -1,43 +1,126 @@ --- layout: tour title: Funkcje wyższego rzędu - -discourse: false - partof: scala-tour -num: 7 +num: 10 language: pl next-page: nested-functions previous-page: mixin-class-composition --- -Scala pozwala na definiowanie funkcji wyższego rzędu. Są to funkcje, które przyjmują funkcje jako parametry lub których wynik jest też funkcją. Poniżej znajduje się przykład funkcji `apply`, która pobiera inną funkcję `f` i wartość `v` po to, by zwrócić wynik zastosowania `f` do `v`: +Scala pozwala na definiowanie funkcji wyższego rzędu. +Są to funkcje, które przyjmują funkcje jako parametry lub których wynik również jest funkcją. +Jest to możliwe, ponieważ w Scali funkcje są wartościami pierwszej kategorii (first-class values). +Terminologia może w tym momencie wydawać się niejasna, pojęcie "funkcja wyższego rzędu" będzie używane zarówno dla metod jak i funkcji przyjmujących jako parametry funkcje lub zwracających inne funkcje. + +Jednym z najczęściej spotykanych przykładów funkcji wyższego rzędu jest funkcja `map`, która dostępna jest dla kolekcji w Scali. + +```scala mdoc +val salaries = Seq(20000, 70000, 40000) +val doubleSalary = (x: Int) => x * 2 +val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) +``` + +Funkcja `doubleSalary` przyjmuje jako parametr wartość `x` typu `Int` i zwraca `x * 2`. +Ogólnie mówiąc, krotka po lewej stronie strzałki `=>` jest listą parametrów, a wartość wyrażenia po prawej stronie jest tym, co zostanie zwrócone. +W trzecim wierszu funkcja `doubleSalary` zostaje zastosowana na każdym elemencie listy `salaries`. + +Aby zredukować trochę kod, możemy dodatkowo użyć funkcji anonimowej i przekazać ją bezpośrednio jako argument do funkcji `map`: + +``` +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) +``` -```tut -def apply(f: Int => String, v: Int) = f(v) +Zauważ, że w powyższym przykładzie `x` nie jest zadeklarowane jako typ `Int`. +Dzieje się tak, ponieważ kompilator może wywnioskować typ, bazując na typie funkcji oczekiwanej przez `map`. +Poniżej jeszcze bardziej idiomatyczny sposób napisania tego kodu: + +```scala mdoc:nest +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(_ * 2) ``` -_Uwaga: metody są automatycznie zamieniane na funkcje, jeżeli wymaga tego kontekst_ +Ponieważ kompilator Scali zna typ parametru (pojedynczy Int), wystarczy jedynie dostarczyć prawą stronę funkcji. +Jedyne zastrzeżenie jest takie, że należy użyć `_` zamiast nazwy parametru (w poprzednim przykładzie było to `x`). + +## Konwertowanie metod w funkcje +Możliwe jest, aby przekazać metody jako argumenty do funkcji wyższego rzędu. +Kompilator automatycznie przekonwertuje metodę w funkcję. -Praktyczny przykład: +``` +case class WeeklyWeatherForecast(temperatures: Seq[Double]) { + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 -```tut -class Decorator(left: String, right: String) { - def layout[A](x: A) = left + x.toString() + right + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- przekazanie metody convertCtoF } +``` + +W tym przykładzie metoda `convertCtoF` jest przekazana do funkcji `forecastInFahrenheit`. +Jest to możliwe, ponieważ kompilator konwertuje metodę `convertCtoF` w funkcję `x => convertCtoF(x)` (uwaga: `x` będzie tutaj wygenerowaną nazwą, która na pewno będzie unikalna w swoim zakresie). -object FunTest extends App { - def apply(f: Int => String, v: Int) = f(v) - val decorator = new Decorator("[", "]") - println(apply(decorator.layout, 7)) +## Funkcje przyjmujące inne funkcje + +Jednym z powodów użycia funkcji wyższego rzędu jest zredukowanie nadmiarowego kodu. +Powiedzmy, że chcemy stworzyć metody, które potrafią zwiększyć czyjeś wynagrodzenie wg. jakiegoś współczynnika. +Bez użycia funkcji wyższego rzędu mogłoby to wyglądać w następujący sposób: + +```scala mdoc +object SalaryRaiser { + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) } ``` -Wykonanie zwraca poniższy wynik: +Zauważ, że każda z trzech metod różni się jedynie współczynnikiem z jakim zmienia wynagrodzenie. +Aby to uprościć, możemy wydzielić powtórzony kod do funkcji wyższego rzędu: + +```scala mdoc:nest +object SalaryRaiser { + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + def bigPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +} ``` -[7] + +Nowa metoda, `promotion`, przyjmuje jako parametr listę wynagrodzeń oraz funkcję typu `Double => Double` (funkcję, która przyjmuje jako parametr Double i zwraca Double) oraz zwraca produkt. + +## Funkcje zwracające inne funkcje + +Istnieją pewne sytuacje, kiedy chcemy wygenerować jakieś funkcje. +Oto przykład funkcji zwracającej inną funkcję. + +```scala mdoc +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { + val schema = if (ssl) "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" +} + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String ``` -W tym przykładzie metoda `decorator.layout` jest automatycznie konwertowana do funkcji typu `Int => String`, czego wymaga funkcja `apply`. Warto dodać, że metoda `decorator.layout` jest polimorficzna, co oznacza, że jej sygnatura jest odpowiednio dopasowana przez kompilator, dzięki czemu, gdy jest przekazana do funkcji `apply`, jest ona traktowana jako `Int => String`. +Zwróć uwagę na typ zwracany funkcji `urlBuilder` - jest to `(String, String) => String`. +Oznacza to, że `urlBuilder` zwraca funkcję anonimową biorącą jako parametry dwie wartości typu String i zwracającą String. +W tym wypadku zwracaną funkcją jest `(endpoint: String, query: String) => s"https://www.example.com/$endpoint?$query"`. diff --git a/_pl/tour/implicit-conversions.md b/_pl/tour/implicit-conversions.md index aea3a9df82..950bbd1458 100644 --- a/_pl/tour/implicit-conversions.md +++ b/_pl/tour/implicit-conversions.md @@ -1,12 +1,9 @@ --- layout: tour title: Konwersje niejawne - -discourse: false - partof: scala-tour -num: 26 +num: 28 language: pl next-page: polymorphic-methods previous-page: implicit-parameters @@ -43,11 +40,11 @@ Domyślnie importowany obiekt `scala.Predef` deklaruje kilka predefiniowanych ty Przykładowo, kiedy wywołujemy metodę Javy, która wymaga typu `java.lang.Integer`, dopuszczalne jest przekazanie typu `scala.Int`. Dzieje się tak ponieważ `Predef` definiuje poniższe konwersje niejawne: -```tut +```scala mdoc import scala.language.implicitConversions -implicit def int2Integer(x: Int) = - java.lang.Integer.valueOf(x) +implicit def int2Integer(x: Int): Integer = + Integer.valueOf(x) ``` Aby zdefiniować własne konwersje niejawne, należy zaimportować `scala.language.implicitConversions` (albo uruchomić kompilator z opcją `-language:implicitConversions`). Ta funkcjonalność musi być włączona jawnie ze względu na problemy, jakie mogą się wiązać z ich nadmiernym stosowaniem. diff --git a/_pl/tour/implicit-parameters.md b/_pl/tour/implicit-parameters.md index 2f84032a5d..2ce27415ea 100644 --- a/_pl/tour/implicit-parameters.md +++ b/_pl/tour/implicit-parameters.md @@ -1,12 +1,9 @@ --- layout: tour title: Parametry domniemane - -discourse: false - partof: scala-tour -num: 25 +num: 27 language: pl next-page: implicit-conversions previous-page: self-types @@ -21,7 +18,7 @@ Argumenty, które mogą być przekazywane jako parametry domniemane, można podz W poniższym przykładzie zdefiniujemy metodę `sum`, która oblicza sumę listy elementów wykorzystując operacje `add` i `unit` obiektu `Monoid`. Należy dodać, że wartości domniemane nie mogą być zdefiniowane globalnie, tylko muszą być elementem pewnego modułu. -```tut +```scala mdoc /** Ten przykład wykorzystuje strukturę z algebry abstrakcyjnej aby zilustrować działanie parametrów domniemanych. Półgrupa jest strukturą algebraiczną na zbiorze A z łączną operacją (czyli taką, która spełnia warunek: add(x, add(y, z)) == add(add(x, y), z)) nazwaną add, która łączy parę obiektów A by zwrócić inny obiekt A. */ abstract class SemiGroup[A] { def add(x: A, y: A): A diff --git a/_pl/tour/inner-classes.md b/_pl/tour/inner-classes.md index b4a8b66561..a97e798d36 100644 --- a/_pl/tour/inner-classes.md +++ b/_pl/tour/inner-classes.md @@ -1,25 +1,22 @@ --- layout: tour title: Klasy wewnętrzne - -discourse: false - partof: scala-tour -num: 21 +num: 23 language: pl -next-page: abstract-types +next-page: abstract-type-members previous-page: lower-type-bounds --- W Scali możliwe jest zdefiniowanie klasy jako element innej klasy. W przeciwieństwie do języków takich jak Java, gdzie tego typu wewnętrzne klasy są elementami ujmujących ich klas, w Scali są one związane z zewnętrznym obiektem. Aby zademonstrować tę różnicę, stworzymy teraz prostą implementację grafu: - -```tut + +```scala mdoc class Graph { class Node { var connectedNodes: List[Node] = Nil - def connectTo(node: Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -32,11 +29,11 @@ class Graph { } } ``` - + W naszym programie grafy są reprezentowane przez listę wierzchołków. Wierzchołki są obiektami klasy wewnętrznej `Node`. Każdy wierzchołek zawiera listę sąsiadów, które są przechowywane w liście `connectedNodes`. Możemy teraz skonfigurować graf z kilkoma wierzchołkami i połączyć je ze sobą: - -```tut -object GraphTest extends App { + +```scala mdoc:nest +def graphTest: Unit = { val g = new Graph val n1 = g.newNode val n2 = g.newNode @@ -45,11 +42,11 @@ object GraphTest extends App { n3.connectTo(n1) } ``` - + Teraz wzbogacimy nasz przykład o jawne typowanie, aby można było zobaczyć powiązanie typów wierzchołków z grafem: - -```tut -object GraphTest extends App { + +```scala mdoc:nest +def graphTest: Unit = { val g: Graph = new Graph val n1: g.Node = g.newNode val n2: g.Node = g.newNode @@ -58,12 +55,12 @@ object GraphTest extends App { n3.connectTo(n1) } ``` - + Ten kod pokazuje, że typ wierzchołka jest prefiksowany przez swoją zewnętrzną instancję (która jest obiektem `g` w naszym przykładzie). Jeżeli mielibyśmy dwa grafy, system typów w Scali nie pozwoli nam na pomieszanie wierzchołków jednego z wierzchołkami drugiego, ponieważ wierzchołki drugiego grafu są określone przez inny typ. Przykład niedopuszczalnego programu: - -```tut:fail + +```scala mdoc:fail object IllegalGraphTest extends App { val g: Graph = new Graph val n1: g.Node = g.newNode @@ -74,15 +71,15 @@ object IllegalGraphTest extends App { n1.connectTo(n3) // niedopuszczalne! } ``` - + Warto zwrócić uwagę na to, że ostatnia linia poprzedniego przykładu byłaby poprawnym programem w Javie. Dla wierzchołków obu grafów Java przypisałaby ten sam typ `Graph.Node`. W Scali także istnieje możliwość wyrażenia takiego typu, zapisując go w formie: `Graph#Node`. Jeżeli byśmy chcieli połączyć wierzchołki różnych grafów, musielibyśmy wtedy zmienić definicję implementacji naszego grafu w następujący sposób: - -```tut + +```scala mdoc:nest class Graph { class Node { var connectedNodes: List[Graph#Node] = Nil - def connectTo(node: Graph#Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -95,5 +92,5 @@ class Graph { } } ``` - + > Ważne jest, że ten program nie pozwala nam na dołączenie wierzchołka do dwóch różnych grafów. Jeżeli chcielibyśmy znieść to ograniczenie, należy zmienić typ zmiennej `nodes` na `Graph#Node`. diff --git a/_pl/tour/lower-type-bounds.md b/_pl/tour/lower-type-bounds.md index dd22954df8..c1a166b414 100644 --- a/_pl/tour/lower-type-bounds.md +++ b/_pl/tour/lower-type-bounds.md @@ -1,12 +1,9 @@ --- layout: tour title: Dolne ograniczenia typów - -discourse: false - partof: scala-tour -num: 20 +num: 22 language: pl next-page: inner-classes previous-page: upper-type-bounds @@ -16,7 +13,7 @@ Podczas gdy [górne ograniczenia typów](upper-type-bounds.html) zawężają typ Oto przykład, w którym jest to użyteczne: -```tut +```scala mdoc case class ListNode[T](h: T, t: ListNode[T]) { def head: T = h def tail: ListNode[T] = t @@ -27,13 +24,13 @@ case class ListNode[T](h: T, t: ListNode[T]) { Powyższy program implementuje listę jednokierunkową z operacją dodania elementu na jej początek. Niestety typ ten jest niezmienny według parametru typu klasy `ListNode`, tzn. `ListNode[String]` nie jest podtypem `ListNode[Any]`. Z pomocą [adnotacji wariancji](variances.html) możemy wyrazić semantykę podtypowania: -``` +```scala case class ListNode[+T](h: T, t: ListNode[T]) { ... } ``` Niestety ten program się nie skompiluje, ponieważ adnotacja kowariancji może być zastosowana tylko, jeżeli zmienna typu jest używana wyłącznie w pozycji kowariantnej. Jako że zmienna typu `T` występuje jako parametr typu metody `prepend`, ta zasada jest złamana. Z pomocą *dolnego ograniczenia typu* możemy jednak zaimplementować tą metodę w taki sposób, że `T` występuje tylko w pozycji kowariantnej: -```tut +```scala mdoc:nest case class ListNode[+T](h: T, t: ListNode[T]) { def head: T = h def tail: ListNode[T] = t @@ -46,7 +43,7 @@ _Uwaga:_ nowa wersja metody `prepend` ma mniej ograniczający typ. Przykładowo Przykład, który to ilustruje: -```tut +```scala mdoc:fail object LowerBoundTest extends App { val empty: ListNode[Null] = ListNode(null, null) val strList: ListNode[String] = empty.prepend("hello") diff --git a/_pl/tour/mixin-class-composition.md b/_pl/tour/mixin-class-composition.md index 5a2ec415ea..9f346fd72c 100644 --- a/_pl/tour/mixin-class-composition.md +++ b/_pl/tour/mixin-class-composition.md @@ -1,22 +1,40 @@ --- layout: tour -title: Kompozycja domieszek - -discourse: false - +title: Kompozycja klas przez domieszki partof: scala-tour -num: 5 +num: 9 language: pl next-page: higher-order-functions -previous-page: traits +previous-page: tuples --- -W przeciwieństwie do języków, które wspierają jedynie pojedyncze dziedziczenie, Scala posiada bardziej uogólniony mechanizm ponownego wykorzystania klas. Scala umożliwia wykorzystanie _nowych elementów klasy_ (różnicy w stosunku do klasy bazowej) w definicji nowej klasy. Wyraża się to przy pomocy _kompozycji domieszek_. +Domieszka (ang. mixin) to cecha (trait), która używana jest do komponowania klas. -Rozważmy poniższe uogólnienie dla iteratorów: +```scala mdoc +abstract class A { + val message: String +} +class B extends A { + val message = "Jestem instancją klasy B" +} +trait C extends A { + def loudMessage = message.toUpperCase() +} +class D extends B with C -```tut +val d = new D +println(d.message) // wyświetli "Jestem instancją klasy B" +println(d.loudMessage) // wyświetli "JESTEM INSTANCJĄ KLASY B" +``` + +Klasa `D` posiada nadklasę `B` oraz domieszkę `C`. +Klasy mogą mieć tylko jedną nadklasę, ale wiele domieszek (używając kolejno słów kluczowych `extends`, a następnie `with`). +Domieszki i nadklasy mogą posiadać tą samą nadklasę (typ bazowy). + +Spójrzmy teraz na trochę ciekawszy przykład zawierający klasę abstrakcyjną. + +```scala mdoc abstract class AbsIterator { type T def hasNext: Boolean @@ -24,35 +42,44 @@ abstract class AbsIterator { } ``` -Następnie rozważmy klasę domieszkową, która doda do klasy `AbsIterator` metodę `foreach` wykonującą podaną funkcję dla każdego elementu zwracanego przez iterator. Aby zdefiniować klasę domieszkową, użyjemy słowa kluczowego `trait`: +Klasa ta zawiera abstrakcyjny typ `type T` oraz standardowe metody iteracyjne `hasNext` i `next`. -```tut -trait RichIterator extends AbsIterator { - def foreach(f: T => Unit) { while (hasNext) f(next()) } +```scala mdoc +class StringIterator(s: String) extends AbsIterator { + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = { + val ch = s charAt i + i += 1 + ch + } } ``` -Oto przykład konkretnego iteratora, który zwraca kolejne znaki w podanym łańcuchu znaków: +Klasa `StringIterator` przyjmuje parametr typu `String`, może być ona użyta do iterowania po typach String (np. aby sprawdzić czy String zawiera daną literę). -```tut -class StringIterator(s: String) extends AbsIterator { - type T = Char - private var i = 0 - def hasNext = i < s.length() - def next() = { val ch = s charAt i; i += 1; ch } +Stwórzmy teraz cechę, która również rozszerza `AbsIterator`. + +```scala mdoc +trait RichIterator extends AbsIterator { + def foreach(f: T => Unit): Unit = while (hasNext) f(next()) } ``` -Chcielibyśmy także połączyć funkcjonalność `StringIterator` oraz `RichIterator` w jednej klasie. Z pojedynczym dziedziczeniem czy też samymi interfejsami jest to niemożliwe, gdyż obie klasy zawierają implementacje metod. Scala pozwala na rozwiązanie tego problemu z użyciem _kompozycji domieszek_. Umożliwia ona ponowne wykorzystanie różnicy definicji klas, tzn. wszystkich definicji, które nie zostały odziedziczone. Ten mechanizm pozwala nam na połączenie `StringIterator` z `RichIterator`, tak jak w poniższym przykładzie - gdzie chcielibyśmy wypisać w kolumnie wszystkie znaki z danego łańcucha: +Cecha `RichIterator` implementuje metodę `foreach`, która z kolei wywołuje przekazaną przez parametr funkcję `f: T => Unit` na kolejnym elemencie (`f(next())`) tak długo, jak dostępne są kolejne elementy (`while (hasNext)`). +Ponieważ `RichIterator` jest cechą, nie musi implementować abstrakcyjnych składników klasy `AbsIterator`. -```tut -object StringIteratorTest { - def main(args: Array[String]) { - class Iter extends StringIterator("Scala") with RichIterator - val iter = new Iter - iter foreach println - } +Spróbujmy teraz połączyć funkcjonalności `StringIterator` oraz `RichIterator` w jednej klasie. + +```scala mdoc +object StringIteratorTest extends App { + class RichStringIter extends StringIterator("Scala") with RichIterator + val richStringIter = new RichStringIter + richStringIter foreach println } ``` -Klasa `iter` w funkcji `main` jest skonstruowana wykorzystując kompozycję domieszek `StringIterator` oraz `RichIterator` z użyciem słowa kluczowego `with`. Pierwszy rodzic jest nazywany _klasą bazową_ `Iter`, podczas gdy drugi (i każdy kolejny) rodzic jest nazywany _domieszką_. +Nowo powstała `RichStringIter` posiada `StringIterator` jako nadklasę oraz `RichIterator` jako domieszkę. + +Mając do dyspozycji jedynie pojedyncze dziedziczenie, nie byli byśmy w stanie osiągnąć takiego stopnia elastyczności. diff --git a/_pl/tour/multiple-parameter-lists.md b/_pl/tour/multiple-parameter-lists.md index 29735548cc..ba88a323f8 100644 --- a/_pl/tour/multiple-parameter-lists.md +++ b/_pl/tour/multiple-parameter-lists.md @@ -1,42 +1,74 @@ --- layout: tour title: Rozwijanie funkcji (Currying) - -discourse: false - partof: scala-tour -num: 9 +num: 12 language: pl next-page: case-classes previous-page: nested-functions --- -Funkcja może określić dowolną ilość list parametrów. Kiedy jest ona wywołana dla mniejszej liczby niż zostało to zdefiniowane, zwraca funkcję pobierającą dalsze listy parametrów jako jej argument. +Metoda może określać dowolną liczbę list parametrów. +W sytuacji, kiedy jest ona wywołana dla mniejszej liczby list parametrów niż zostało to zdefiniowane, zwracana jest funkcja oczekująca pozostałych list parametrów jako argumentów. -Przykład rozwijania funkcji: +Dla przykładu przyjrzyjmy się metodzie `foldLeft` zdefiniowanej w [Traversable](/overviews/collections/trait-traversable.html) z kolekcji w Scali: -```tut -object CurryTest extends App { +``` +def foldLeft[B](z: B)(op: (B, A) => B): B +``` - def filter(xs: List[Int], p: Int => Boolean): List[Int] = - if (xs.isEmpty) xs - else if (p(xs.head)) xs.head :: filter(xs.tail, p) - else filter(xs.tail, p) +Metoda `foldLeft` stosuje binarny operator `op` na wartości początkowej `z` oraz wszystkich elementach zawartych w aktualnym obiekcie `Traversable` - idąc od lewej do prawej strony. +Poniżej omówiony jest przykład użycia. - def modN(n: Int)(x: Int) = ((x % n) == 0) +Zaczynając od początkowej wartości 0, funkcja `foldLeft` stosuje funkcję `(m, n) => m + n` na każdym elemencie listy oraz poprzedniej zakumulowanej wartości. - val nums = List(1, 2, 3, 4, 5, 6, 7, 8) - println(filter(nums, modN(2))) - println(filter(nums, modN(3))) -} +```scala mdoc +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val res = numbers.foldLeft(0)((m, n) => m + n) +println(res) // 55 ``` -_Uwaga: metoda `modN` jest częściowo zastosowana dla dwóch wywołań `filter`, gdyż jest wywołana tylko dla jej pierwszego argumentu. Wyrażenie `modN(2)` zwraca funkcję typu `Int => Boolean` - stąd też może być przekazane jako drugi argument funkcji `filter`._ +Metody z wieloma listami parametrów mają bardziej dosadną składnię wywoływania, dlatego powinny być używane oszczędnie. +Sugerowane przypadki użycia obejmują: + +#### Funkcja jako pojedynczy parametr -Wynik działania powyższego programu: +W przypadku funkcji jako pojedynczego parametru, tak jak w przypadku `op` z `foldLeft` powyżej, wiele list parametrów pozwala na bardziej zwięzłą składnię przy przekazywaniu funkcji anonimowej do metody. +Bez wielu list parametrów kod wyglądałby w następujący sposób: ``` -List(2,4,6,8) -List(3,6) +numbers.foldLeft(0, {(m: Int, n: Int) => m + n}) +``` + +Zauważ, że użycie wielu list parametrów pozwala na wykorzystanie wnioskowania typów, co z kolei czyni kod bardziej zwięzłym (jak pokazano poniżej). +Używając standardowej definicji metody, nie byłoby to możliwe. + +``` +numbers.foldLeft(0)(_ + _) +``` + +Powyższe wyrażenie `numbers.foldLeft(0)(_ + _)` pozwala trwale ustawić parametr `z` i przekazywać dalej częściową funkcję (partial function), tak jak pokazano to poniżej: + +```scala mdoc:nest +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]())_ + +val squares = numberFunc((xs, x) => xs:+ x*x) +print(squares.toString()) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) + +val cubes = numberFunc((xs, x) => xs:+ x*x*x) +print(cubes.toString()) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` + +Podsumowując, `foldLeft` oraz `foldRight` mogą być używane w dowolnej z poniższych postaci: + +```scala mdoc:nest +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + +numbers.foldLeft(0)((sum, item) => sum + item) // postać ogólna +numbers.foldRight(0)((sum, item) => sum + item) // postać ogólna + +numbers.foldLeft(0)(_+_) // postać rozwijana (curried) +numbers.foldRight(0)(_+_) // postać rozwijana (curried) ``` diff --git a/_pl/tour/named-arguments.md b/_pl/tour/named-arguments.md index 2fe636808c..bf297d982d 100644 --- a/_pl/tour/named-arguments.md +++ b/_pl/tour/named-arguments.md @@ -1,19 +1,17 @@ --- layout: tour title: Parametry nazwane - -discourse: false - partof: scala-tour -num: 33 +num: 6 language: pl +next page: traits previous-page: default-parameter-values --- Wywołując metody i funkcje, możesz użyć nazwy parametru jawnie podczas wywołania: -```tut +```scala mdoc def printName(first:String, last:String) = { println(first + " " + last) } @@ -25,7 +23,7 @@ printName(last = "Smith", first = "John") // Wypisuje "John Smith" Warto zwrócić uwagę na to, że kolejność wyboru parametrów podczas wywołania nie ma znaczenia, dopóki wszystkie parametry są nazwane. Ta funkcjonalność jest dobrze zintegrowana z [domyślnymi wartościami parametrów](default-parameter-values.html): -```tut +```scala mdoc:nest def printName(first: String = "John", last: String = "Smith") = { println(first + " " + last) } diff --git a/_pl/tour/nested-functions.md b/_pl/tour/nested-functions.md index 1839a2da62..88553a6d8e 100644 --- a/_pl/tour/nested-functions.md +++ b/_pl/tour/nested-functions.md @@ -1,36 +1,33 @@ --- layout: tour title: Funkcje zagnieżdżone - -discourse: false - partof: scala-tour -num: 8 +num: 11 language: pl next-page: multiple-parameter-lists previous-page: higher-order-functions --- -Scala pozwala na zagnieżdżanie definicji funkcji. Poniższy obiekt określa funkcję `filter`, która dla danej listy filtruje elementy większe bądź równe podanemu progowi `threshold`: +Scala pozwala na zagnieżdżanie definicji funkcji. +Poniższy obiekt określa funkcję `factorial`, która oblicza silnię dla danej liczby: -```tut -object FilterTest extends App { - def filter(xs: List[Int], threshold: Int) = { - def process(ys: List[Int]): List[Int] = - if (ys.isEmpty) ys - else if (ys.head < threshold) ys.head :: process(ys.tail) - else process(ys.tail) - process(xs) - } - println(filter(List(1, 9, 2, 8, 3, 7, 4), 5)) -} -``` +```scala mdoc + def factorial(x: Int): Int = { + def fact(x: Int, accumulator: Int): Int = { + if (x <= 1) accumulator + else fact(x - 1, x * accumulator) + } + fact(x, 1) + } -_Uwaga: zagnieżdżona funkcja `process` odwołuje się do zmiennej `threshold` określonej w zewnętrznym zasięgu jako parametr `filter`_ + println("Factorial of 2: " + factorial(2)) + println("Factorial of 3: " + factorial(3)) +``` -Wynik powyższego programu: +Wynik działania powyższego programu: ``` -List(1,2,3,4) +Factorial of 2: 2 +Factorial of 3: 6 ``` diff --git a/_pl/tour/operators.md b/_pl/tour/operators.md index 7cd7747a73..8730570849 100644 --- a/_pl/tour/operators.md +++ b/_pl/tour/operators.md @@ -1,20 +1,17 @@ --- layout: tour title: Operatory - -discourse: false - partof: scala-tour -num: 29 +num: 31 language: pl -next-page: automatic-closures +next-page: by-name-parameters previous-page: type-inference --- Każda metoda, która przyjmuje jeden parametr, może być użyta jako *operator infiksowy*. Oto definicja klasy `MyBool` która zawiera metody `and` i `or`: -```tut +```scala mdoc case class MyBool(x: Boolean) { def and(that: MyBool): MyBool = if (x) that else this def or(that: MyBool): MyBool = if (x) this else that @@ -24,7 +21,7 @@ case class MyBool(x: Boolean) { Można teraz użyć `and` i `or` jako operatory infiksowe: -```tut +```scala mdoc def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) ``` @@ -33,7 +30,7 @@ Można zauważyć, że dzięki zastosowaniu operatorów infiksowych metoda `xor` Dla porównania, oto kod który nie wykorzystuje operatorów infiksowych: -```tut +```scala mdoc:nest def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = x.or(y).and(x.and(y).negate) ``` diff --git a/_pl/tour/package-objects.md b/_pl/tour/package-objects.md new file mode 100644 index 0000000000..979acfcb66 --- /dev/null +++ b/_pl/tour/package-objects.md @@ -0,0 +1,68 @@ +--- +layout: tour +title: Obiekty pakietu +language: pl +partof: scala-tour + +num: 35 +previous-page: packages-and-imports +language: pl +--- + +# Obiekty pakietu + +Scala udostępnia obiekty pakietu jako wygodny kontener wspóldzielony w całym pakiecie. + +Obiekty pakietu mogą zawierać dowolne definicje, nie tylko definicje zmiennych i metod. Na przykład, są często używane do przechowywania aliasów typów i niejawnych konwersji. Obiekty pakietu mogą nawet dziedziczyć klasy i cechy (traits) Scali. + +Zgodnie z konwencją, kod źródłowy obiektu pakietu jest zwykle umieszczany w pliku źródłowym o nazwie `package.scala`. + +Każdy pakiet może mieć jeden obiekt pakietu. Wszelkie definicje umieszczone w obiekcie pakietu traktowane są jak członkowie samego pakietu. + +Zobacz przykład poniżej. Załóżmy najpierw, że w pakiecie `gradening.fruits` zdefiniowana jest klasa `Fruit` i trzy obiekty tej klasy: + +``` +// in file gardening/fruits/Fruit.scala +package gardening.fruits + +case class Fruit(name: String, color: String) +object Apple extends Fruit("Apple", "green") +object Plum extends Fruit("Plum", "blue") +object Banana extends Fruit("Banana", "yellow") +``` + +Teraz załóżmy, że chcesz umieścić zmienną `planted` i metodę `showFruit` bezpośrednio w pakiecie `gardening.fruits`. +Możesz zrobić to w następujący sposób: + +``` +// in file gardening/fruits/package.scala +package gardening +package object fruits { + val planted = List(Apple, Plum, Banana) + def showFruit(fruit: Fruit): Unit = { + println(s"${fruit.name}s are ${fruit.color}") + } +} +``` + +Jako przykład tego, jak wygląda użycie definicji przygorowanych w ten sposób, obiekt `PrintPlanted` importuje `planted` i `showFruit` w ten sam sposób, w jaki importuje klasę `Fruit` - używając importu wieloznacznego w pakiecie `gardening.fruits`. + +``` +// in file PrintPlanted.scala +import gardening.fruits._ +object PrintPlanted { + def main(args: Array[String]): Unit = { + for (fruit <- planted) { + showFruit(fruit) + } + } +} +``` + +Obiekty pakietu są podobne do innych obiektów, co oznacza, że można je tworzyć przy użyciu dziedziczenia. Na przykład można łączyć kilka cech: + +``` +package object fruits extends FruitAliases with FruitHelpers { + // tutaj znajdują się pomocniki (helpers) i zmienne +} +``` diff --git a/_pl/tour/packages-and-imports.md b/_pl/tour/packages-and-imports.md index 724704030b..9bcdb38fc1 100644 --- a/_pl/tour/packages-and-imports.md +++ b/_pl/tour/packages-and-imports.md @@ -1,18 +1,92 @@ --- layout: tour -title: Packages and Imports +title: Pakiety i importy language: pl - -discourse: true - partof: scala-tour -num: 35 -previous-page: named-arguments -next-page: type-inference +num: 34 +previous-page: annotations +next-page: package-objects +language: pl --- -# Packages and Imports +# Pakiety i importy +Scala używa pakietów do tworzenia przestrzeni nazw (namespaces), które umożliwiają modularyzację programów. + +## Tworzenie pakietu +Pakiety są tworzone przez zadeklarowanie jednej lub więcej nazw pakietów w górnej części pliku Scali. + +``` +package users + +class User +``` + +Jedną z konwencji jest nadawanie pakietowi takiej samej nazwy, jak nazwa katalogu zawierającego plik źródłowy. Jednak Scala jest niezależna od układu plików. Struktura katalogów projektu SBT dla `package users` może wyglądać następująco: + +``` +- ExampleProject + - build.sbt + - project + - src + - main + - scala + - users + User.scala + UserProfile.scala + UserPreferences.scala + - test +``` + +Zwróć uwagę, że katalog `users` znajduje się w katalogu `scala`, a w pakiecie znajduje się wiele plików Scali. Każdy plik Scali w pakiecie może mieć tę samą deklarację pakietu. Innym sposobem deklarowania pakietów jest użycie nawiasów klamrowych: + +``` +package users { + package administrators { + class NormalUser + } + package normalusers { + class NormalUser + } +} +``` + +Jak widać, pozwala to na zagnieżdżanie pakietów i zapewnia większą kontrolę nad zakresem i hermetyzacją. Nazwa pakietu powinna być zapisana małymi literami, a jeśli kod jest tworzony w organizacji, która posiada witrynę internetową, powinna mieć następującą konwencję formatu: `..`. Na przykład, gdyby firma Google miała projekt o nazwie `SelfDrivingCar`, nazwa pakietu wyglądałaby następująco: + +``` +package com.google.selfdrivingcar.camera + +class Lens +``` + +Może to odpowiadać następującej strukturze katalogów: `SelfDrivingCar/src/main/scala/com/google/selfdrivingcar/camera/Lens.scala`. + +## Import + +Deklaracje `import` służą do uzyskiwania dostępu do elementów składowych (members, tzn.: klasy, cechy, funkcje itp.) w innych pakietach. Aby uzyskać dostęp do elementów tego samego pakietu, nie jest wymagana deklaracja `import`. Deklaracje `import` są selektywne. + +``` +import users._ // zaimportuj wszystko z pakietu użytkowników +import users.User // zaimportuj klasę User +import users.{User, UserPreferences} // zaimportuj tylko wybrane elementy +import users.{UserPreferences => UPrefs} // zaimportuj i zmień nazwę dla wygody +``` + +Jedną z różnic w Scali od Javy jest to, że deklarację `import` można umieścić w dowolnym miejscu: + +```scala mdoc +def sqrtplus1(x: Int) = { + import scala.math.sqrt + sqrt(x) + 1.0 +} +``` + +W przypadku konfliktu nazw i konieczności podania pełnej ścieżki w hierarchii nazw pakietów, poprzedź nazwę pakietu przedrostkiem `_root_`: + +``` +package accounts + +import _root_.users._ +``` -(this section of the tour has not been translated yet. pull request -with translation welcome!) +Uwaga: pakiety `scala` i `java.lang` oraz `object Predef` są domyślnie importowane. diff --git a/_pl/tour/pattern-matching.md b/_pl/tour/pattern-matching.md index f36648439a..3b853bff1b 100644 --- a/_pl/tour/pattern-matching.md +++ b/_pl/tour/pattern-matching.md @@ -1,12 +1,9 @@ --- layout: tour title: Dopasowanie wzorców (Pattern matching) - -discourse: false - partof: scala-tour -num: 11 +num: 14 language: pl next-page: singleton-objects previous-page: case-classes @@ -14,7 +11,7 @@ previous-page: case-classes Scala posiada wbudowany mechanizm dopasowania wzorców. Umożliwia on dopasowanie dowolnego rodzaju danych, przy czym zawsze zwracamy pierwsze dopasowanie. Przykład dopasowania liczby całkowitej: -```tut +```scala mdoc object MatchTest1 extends App { def matchTest(x: Int): String = x match { case 1 => "one" @@ -29,7 +26,7 @@ Blok kodu z wyrażeniami `case` definiuje funkcję, która przekształca liczby Wzorce można także dopasowywać do różnych typów wartości: -```tut +```scala mdoc object MatchTest2 extends App { def matchTest(x: Any): Any = x match { case 1 => "one" diff --git a/_pl/tour/polymorphic-methods.md b/_pl/tour/polymorphic-methods.md index 4f8d738202..113887aeee 100644 --- a/_pl/tour/polymorphic-methods.md +++ b/_pl/tour/polymorphic-methods.md @@ -1,12 +1,9 @@ --- layout: tour title: Metody polimorficzne - -discourse: false - partof: scala-tour -num: 27 +num: 29 language: pl next-page: type-inference previous-page: implicit-conversions @@ -16,7 +13,7 @@ Metody w Scali mogą być parametryzowane zarówno przez wartości, jak i typy. Przykład poniżej: -```tut +```scala mdoc def dup[T](x: T, n: Int): List[T] = { if (n == 0) Nil diff --git a/_pl/tour/regular-expression-patterns.md b/_pl/tour/regular-expression-patterns.md index 33c42cbad7..9d8efe1cba 100644 --- a/_pl/tour/regular-expression-patterns.md +++ b/_pl/tour/regular-expression-patterns.md @@ -1,14 +1,10 @@ --- layout: tour title: Wzorce wyrażeń regularnych - -discourse: false - partof: scala-tour -num: 14 +num: 16 language: pl - next-page: extractor-objects previous-page: singleton-objects --- @@ -24,7 +20,7 @@ Elem(prefix:String, label:String, attrs:MetaData, scp:NamespaceBinding, children W tych przypadkach Scala pozwala wzorcom na zastosowanie symbolu `_*` w ostatniej pozycji, aby dopasować sekwencje dowolnej długości. Poniższy przykład demonstruje dopasowanie wzorca, który rozpoznaje początek sekwencji i wiąże resztę do zmiennej `rest`: -```tut +```scala mdoc object RegExpTest1 extends App { def containsScala(x: String): Boolean = { val z: Seq[Char] = x diff --git a/_pl/tour/self-types.md b/_pl/tour/self-types.md index 2be5e78d67..d0098d352c 100644 --- a/_pl/tour/self-types.md +++ b/_pl/tour/self-types.md @@ -1,12 +1,9 @@ --- layout: tour title: Jawnie typowane samoreferencje - -discourse: false - partof: scala-tour -num: 24 +num: 26 language: pl next-page: implicit-parameters previous-page: compound-types @@ -16,7 +13,7 @@ Dążąc do tego, aby nasze oprogramowanie było rozszerzalne, często przydatne Oto definicja opisująca grafy: -```tut +```scala mdoc abstract class Graph { type Edge type Node <: NodeIntf @@ -29,11 +26,11 @@ abstract class Graph { } ``` -Grafy składają się z listy węzłów oraz krawędzi, gdzie zarówno typ węzła jak i krawędzi jest abstrakcyjny. Użycie [typów abstrakcyjnych](abstract-types.html) pozwala implementacjom cechy `Graph` na to, by określały swoje konkretne klasy dla węzłów i krawędzi. Ponadto graf zawiera metodę `addNode`, której celem jest dodanie nowych węzłów do grafu. Węzły są połączone z użyciem metody `connectWith`. +Grafy składają się z listy węzłów oraz krawędzi, gdzie zarówno typ węzła jak i krawędzi jest abstrakcyjny. Użycie [typów abstrakcyjnych](abstract-type-members.html) pozwala implementacjom cechy `Graph` na to, by określały swoje konkretne klasy dla węzłów i krawędzi. Ponadto graf zawiera metodę `addNode`, której celem jest dodanie nowych węzłów do grafu. Węzły są połączone z użyciem metody `connectWith`. Przykład implementacji klasy `Graph`: -```tut:fail +```scala mdoc:fail abstract class DirectedGraph extends Graph { type Edge <: EdgeImpl class EdgeImpl(origin: Node, dest: Node) { @@ -67,7 +64,7 @@ Jeżeli przyjrzymy się bliżej implementacji metody `connectWith`, możemy dost Scala rozwiązuje ten problem pozwalając na powiązanie klasy z innym typem poprzez jawne typowanie samoreferencji. Możemy użyć tego mechanizmu, aby naprawić powyższy kod: -```tut +```scala mdoc abstract class DirectedGraph extends Graph { type Edge <: EdgeImpl class EdgeImpl(origin: Node, dest: Node) { @@ -98,7 +95,7 @@ W nowej definicji klasy `NodeImpl` referencja `this` jest typu `Node`. Ponieważ Oto konkretna specjalizacja `DirectedGraph`, gdzie abstrakcyjne elementy klasy mają ustalone ścisłe znaczenie: -```tut +```scala mdoc class ConcreteDirectedGraph extends DirectedGraph { type Edge = EdgeImpl type Node = NodeImpl @@ -112,8 +109,8 @@ Należy dodać, że w tej klasie możemy utworzyć `NodeImpl`, ponieważ wiemy j Poniżej przykład zastosowania klasy `ConcreteDirectedGraph`: -```tut -object GraphTest extends App { +```scala mdoc +def graphTest: Unit = { val g: Graph = new ConcreteDirectedGraph val n1 = g.addNode val n2 = g.addNode diff --git a/_pl/tour/singleton-objects.md b/_pl/tour/singleton-objects.md index 3c50539a37..14529d8993 100644 --- a/_pl/tour/singleton-objects.md +++ b/_pl/tour/singleton-objects.md @@ -1,14 +1,10 @@ --- layout: tour title: Obiekty singleton - -discourse: false - partof: scala-tour -num: 12 +num: 15 language: pl - next-page: regular-expression-patterns previous-page: pattern-matching --- @@ -27,7 +23,7 @@ Metoda `sum` jest dostępna globalnie i można się do niej odwołać lub import Obiekty singleton są swego rodzaju skrótem do definiowania pojedynczej instancji klasy, która nie powinna być bezpośrednio tworzona i która sama w sobie stanowi referencję do tego obiektu, jakby była określona jako `val`. -Obiekt singleton może rozszerzać klasę lub cechę. Przykładowo [klasa przypadku](case-classes.html) bez [parametrów typu](generic-classes.html) domyślnie generuje obiekt singleton o tej samej nazwie, który implementuje cechę [`Function*`](http://www.scala-lang.org/api/current/scala/Function1.html). +Obiekt singleton może rozszerzać klasę lub cechę. Przykładowo [klasa przypadku](case-classes.html) bez [parametrów typu](generic-classes.html) domyślnie generuje obiekt singleton o tej samej nazwie, który implementuje cechę [`Function*`](https://www.scala-lang.org/api/current/scala/Function1.html). ## Obiekt towarzyszący ## @@ -35,7 +31,7 @@ Duża część obiektów singleton nie istnieje samodzielnie, ale jest powiązan Klasa i jej obiekt towarzyszący mogą być zdefiniowane tylko w tym samym pliku, przykład: -```tut +```scala mdoc class IntPair(val x: Int, val y: Int) object IntPair { diff --git a/_pl/tour/tour-of-scala.md b/_pl/tour/tour-of-scala.md index ee1a1b9338..76bdcc7091 100644 --- a/_pl/tour/tour-of-scala.md +++ b/_pl/tour/tour-of-scala.md @@ -1,47 +1,71 @@ --- layout: tour title: Wprowadzenie - -discourse: false - partof: scala-tour num: 1 -outof: 33 language: pl -next-page: unified-types +next-page: basics --- -Scala jest nowoczesnym, wieloparadygmatowym językiem programowania zaprojektowanym do wyrażania powszechnych wzorców programistycznych w zwięzłym, eleganckim i bezpiecznie typowanym stylu. Scala płynnie integruje ze sobą cechy języków funkcyjnych i zorientowanych obiektowo. +## Witaj +Ten przewodnik składa się z drobnych wprowadzeń do najczęściej używanych funkcjonalności języka Scala. + +Jest to jedynie krótkie wprowadzenie, a nie pełny samouczek. +Jeżeli szukasz tego drugiego, rozważ jedną z [książek](/books.html) lub [inne zasoby](/online-courses.html). + +## Czym jest Scala? +Scala jest nowoczesnym, wieloparadygmatowym językiem programowania zaprojektowanym do wyrażania powszechnych wzorców programistycznych w zwięzłym, eleganckim i bezpiecznie typowanym stylu. +Scala płynnie integruje ze sobą cechy języków funkcyjnych i zorientowanych obiektowo. ## Scala jest zorientowana obiektowo ## -Scala jest czysto obiektowym językiem w tym sensie, że każda [wartość jest obiektem](unified-types.html). Typy oraz zachowania obiektów są opisane przez [klasy](classes.html) oraz [cechy](traits.html). Klasy są rozszerzane przez podtypowanie i elastyczny mechanizm [kompozycji domieszek](mixin-class-composition.html) jako zastępnik dla wielodziedziczenia. +Scala jest czysto obiektowym językiem w tym sensie, że każda [wartość jest obiektem](unified-types.html). +Typy oraz zachowania obiektów są opisane przez [klasy](classes.html) oraz [cechy](traits.html). +Klasy są rozszerzane przez podtypowanie i elastyczny mechanizm [kompozycji domieszek](mixin-class-composition.html) jako zastępstwo dla wielodziedziczenia. ## Scala jest funkcyjna ## -Scala jest też funkcyjnym językiem w tym sensie, że [każda funkcja jest wartością](unified-types.html). Scala dostarcza lekką składnię do definiowana funkcji anonimowych, wspiera [funkcje wyższego rzędu](higher-order-functions.html), pozwala funkcjom, by były [zagnieżdżone](nested-functions.html), a także umożliwia [rozwijanie funkcji](multiple-parameter-lists.html). [Klasy przypadków](case-classes.html) oraz wbudowane wsparcie dla [dopasowania wzorców](pattern-matching.html) wprowadzają do Scali mechanizm typów algebraicznych stosowany w wielu funkcyjnych językach programowania. [Obiekty singleton](singleton-objects.html) są wygodną metodą grupowania funkcji, które nie należą do żadnej klasy. +Scala jest też funkcyjnym językiem w tym sensie, że [każda funkcja jest wartością](unified-types.html). +Scala dostarcza [lekką składnię](basics.html#funkcje) do definiowana funkcji anonimowych, wspiera [funkcje wyższego rzędu](higher-order-functions.html), pozwala funkcjom, by były [zagnieżdżone](nested-functions.html), a także umożliwia [rozwijanie funkcji](multiple-parameter-lists.html). +[Klasy przypadków (case class)](case-classes.html) oraz wbudowane wsparcie dla [dopasowania wzorców (pattern matching)](pattern-matching.html) wprowadzają do Scali mechanizm typów algebraicznych stosowany w wielu funkcyjnych językach programowania. [Obiekty singleton](singleton-objects.html) są wygodną metodą grupowania funkcji, które nie należą do żadnej klasy. -Ponadto mechanizm dopasowania wzorca w naturalny sposób rozszerza się do obsługi przetwarzania danych w formacie XML z pomocą [wzorców sekwencji ignorujących prawą stronę](regular-expression-patterns.html), z wykorzystaniem rozszerzeń [obiektów ekstraktorów](extractor-objects.html). W tym kontekście instrukcje for są użyteczne w formułowaniu zapytań. Ta funkcjonalność sprawia, że Scala jest idealnym językiem do tworzenia aplikacji takich jak usługi sieciowe. +Ponadto, mechanizm dopasowania wzorców w naturalny sposób rozszerza się do obsługi [przetwarzania danych w formacie XML](https://github.com/scala/scala-xml/wiki/XML-Processing) z pomocą [wzorców sekwencji ignorujących prawą stronę](regular-expression-patterns.html), z wykorzystaniem rozszerzeń [obiektów ekstraktorów](extractor-objects.html). +W tym kontekście [wyrażenia for](for-comprehensions.html) są użyteczne w formułowaniu zapytań. +Te i inne funkcjonalności sprawiają, że Scala jest idealnym językiem do tworzenia aplikacji takich jak usługi sieciowe. ## Scala jest statycznie typowana ## -Scala posiada ekspresywny system typów zapewniający, że abstrakcje są używane w sposób zgodny oraz bezpieczny. W szczególności system typów wspiera: +Scala posiada ekspresywny system typów, który zapewnia, że abstrakcje są używane w bezpieczny i należyty sposób. +W szczególności system typów wspiera: -* [klasy generyczne](generic-classes.html) -* [adnotacje wariancji](variances.html) -* [górne](upper-type-bounds.html) oraz [dolne](lower-type-bounds.html) ograniczenia typów -* [klasy zagnieżdżone](inner-classes.html) i [typy abstrakcyjne](abstract-types.html) jako elementy obiektów -* [typy złożone](compound-types.html) -* [jawnie typowane samoreferencje](self-types.html) -* [parametry domniemane](implicit-parameters.html) i [konwersje niejawne](implicit-conversions.html) -* [metody polimorficzne](polymorphic-methods.html) +* [klasy generyczne](generic-classes.html), +* [adnotacje wariancji](variances.html), +* [górne](upper-type-bounds.html) oraz [dolne](lower-type-bounds.html) ograniczenia typów, +* [klasy zagnieżdżone](inner-classes.html) i [typy abstrakcyjne](abstract-type-members.html) jako elementy obiektów, +* [typy złożone](compound-types.html), +* [jawnie typowane samoreferencje](self-types.html), +* [parametry domniemane](implicit-parameters.html) i [konwersje niejawne](implicit-conversions.html), +* [metody polimorficzne](polymorphic-methods.html). -[Mechanizm lokalnej inferencji typów](type-inference.html) sprawia, że nie jest konieczne podawanie nadmiarowych informacji o typach w programie. W połączeniu te funkcje języka pozwalają na bezpiecznie typowane ponowne wykorzystanie programistycznych abstrakcji. +[Mechanizm lokalnej inferencji typów](type-inference.html) sprawia, że nie jest konieczne podawanie nadmiarowych informacji o typach w programie. +Wszystkie te funkcje języka pozwalają na bezpieczne ponowne użycie programistycznych abstrakcji oraz rozwijanie oprogramowania z bezpieczeństwem dla typów. ## Scala jest rozszerzalna ## -W praktyce rozwiązania specyficzne dla domeny wymagają odpowiednich rozszerzeń języka. Scala dostarcza unikalne mechanizmy, dzięki którym można łatwo dodawać nowe konstrukcje do języka w postaci bibliotek: +W praktyce rozwiązania specyficzne dla domeny często wymagają odpowiednich, również specyficznych domenowo, rozszerzeń języka. +Scala dostarcza unikalne mechanizmy, dzięki którym można łatwo dodawać nowe konstrukcje do języka w postaci bibliotek. + +W większości przypadków można to uzyskać bez potrzeby używania technik meta-programowania takich jak np. makra. +Oto kilka przykładów: + +* [Klasy domniemane](https://docs.scala-lang.org/overviews/core/implicit-classes.html) pozwalają na rozszerzanie już istniejących klas o nowe metody, +* [Interpolacja łańcuchów znaków](/overviews/core/string-interpolation.html) jest rozszerzalna o niestandardowe interpolatory użytkownika. + +## Scala współdziała z językami JVM +Scala jest zaprojektowana tak, aby jak najlepiej współpracować z popularnym środowiskiem uruchomieniowym Java Runtime Environment (JRE). +W szczególności interakcja z językiem Java jest tak płynna, jak tylko jest to możliwe. +Nowsze funkcje języka Java takie jak interfejsy funkcyjne (SAM), [funkcje anonimowe (lambda)](higher-order-functions.html), [adnotacje](annotations.html) oraz [typy generyczne](generic-classes.html) posiadają swoje bezpośrednie odwzorowania w języku Scala. -* każda metoda może być używana jako [operator infiksowy lub prefiksowy](operators.html) -* [domknięcia są konstruowane automatycznie zależnie od wymaganego typu](automatic-closures.html) +Unikalne dla Scali funkcje, które nie mają odwzorowania w Javie, jak na przykład [domyślne wartości parametrów](default-parameter-values.html) oraz [parametry nazwane](named-arguments.html), są kompilowane tak, aby zachować jak największą zgodność z Javą. +Scala posiada taki sam model kompilacji (oddzielna kompilacja, dynamiczne ładowanie klas) jak Java, dzięki czemu umożliwa korzystanie z tysięcy już istniejących, wysokiej klasy bibliotek. -Powyższe mechanizmy pozwalają na definicję nowych rodzajów wyrażeń bez potrzeby rozszerzania składni języka czy też wykorzystywania meta-programowania w postaci makr. +## Do dzieła! -Scala jest zaprojektowana tak, aby współpracować dobrze ze środowiskiem uruchomieniowym JRE oraz językiem Java. Funkcje Javy takie jak [adnotacje](annotations.html) oraz typy generyczne posiadają swoje bezpośrednie odwzorowanie w Scali. Unikalne funkcje Scali, jak na przykład [domyślne wartości parametrów](default-parameter-values.html) oraz [nazwane parametry](named-arguments.html), są kompilowane tak, aby zachować jak największą zgodność z Javą. Scala ma także taki sam model kompilacji (oddzielna kompilacja, dynamiczne ładowanie klas), dzięki czemu umożliwia korzystanie z całego ekosystemu Javy. +Przejdź do [kolejnej strony](basics.html) aby dowiedzieć się więcej. diff --git a/_pl/tour/traits.md b/_pl/tour/traits.md index 9d11ab5213..b92057aa2a 100644 --- a/_pl/tour/traits.md +++ b/_pl/tour/traits.md @@ -1,57 +1,90 @@ --- layout: tour title: Cechy - -discourse: false - partof: scala-tour -num: 4 +num: 7 language: pl -next-page: mixin-class-composition -previous-page: classes +next-page: tuples +previous-page: named-arguments --- -Zbliżone do interfejsów Javy cechy są wykorzystywane do definiowania typów obiektów poprzez określenie sygnatur wspieranych metod. Podobnie jak w Javie 8, Scala pozwala cechom na częściową implementację, tzn. jest możliwe podanie domyślnej implementacji dla niektórych metod. W przeciwieństwie do klas, cechy nie mogą posiadać parametrów konstruktora. +Cechy (Traits) są używane, aby współdzielić interfejsy i pola pomiędzy klasami. +Są bardzo podobne do interfejsów w Javie 8. +Cechy mogą być rozszerzane przez klasy i obiekty, jednak nie można stworzyć instancji danej cechy. +Z tego powodu cechy nie przyjmują parametrów wartości. + +## Definiowanie cechy + +Minimalna definicja cechy składa się ze słowa kluczowego `trait` oraz identyfikatora. + +```scala mdoc +trait HairColor +``` -Przykład definicji cechy której zadaniem jest określanie podobieństwa z innym obiektem: +Cechy są szczególnie przydatne jako generyczne typy zawierające abstrakcyjne metody. -```tut -trait Similarity { - def isSimilar(x: Any): Boolean - def isNotSimilar(x: Any): Boolean = !isSimilar(x) +```scala mdoc +trait Iterator[A] { + def hasNext: Boolean + def next(): A } ``` - -Powyższa cecha składa się z dwóch metod: `isSimilar` oraz `isNotSimilar`. Mimo że `isSimilar` nie posiada implementacji (odpowiada metodzie abstrakcyjnej w Javie), `isNotSimilar` definiuje konkretną implementację. W ten sposób klasy, które łączą tą cechę, muszą tylko zdefiniować implementacją dla metody `isSimilar`. Zachowanie `isNotSimilar` jest dziedziczone bezpośrednio z tej cechy. Cechy są zazwyczaj łączone z [klasami](classes.html) lub innymi cechami poprzez [kompozycję domieszek](mixin-class-composition.html): - -```tut -class Point(xc: Int, yc: Int) extends Similarity { - var x: Int = xc - var y: Int = yc - def isSimilar(obj: Any) = - obj.isInstanceOf[Point] && - obj.asInstanceOf[Point].x == x + +Rozszerzenie cechy `trait Iterator[A]` wymaga wskazania parametru typu `A` oraz zaimplementowania metod `hasNext` i `next`. + +## Używanie cech + +Aby rozszerzyć cechę należy użyć słowa kluczowego `extends`. +Następnie wymagane jest zaimplementowanie abstrakcyjnych składników danej cechy używając słowa kluczowego `override.` + +```scala mdoc:nest +trait Iterator[A] { + def hasNext: Boolean + def next(): A } -object TraitsTest extends App { - val p1 = new Point(2, 3) - val p2 = new Point(2, 4) - val p3 = new Point(3, 3) - val p4 = new Point(2, 3) - println(p1.isSimilar(p2)) - println(p1.isSimilar(p3)) - // Metoda isNotSimilar jest zdefiniowana w Similarity - println(p1.isNotSimilar(2)) - println(p1.isNotSimilar(p4)) +class IntIterator(to: Int) extends Iterator[Int] { + private var current = 0 + override def hasNext: Boolean = current < to + override def next(): Int = { + if (hasNext) { + val t = current + current += 1 + t + } else 0 + } } -``` - -Wynik działania programu: +val iterator = new IntIterator(10) +println(iterator.next()) // wyświetli 0 +println(iterator.next()) // wyświetli 1 ``` -true -false -true -false + +Klasa `IntIterator` przyjmuje parametr `to` (do) jako ograniczenie górne, oraz rozszerza `extends Iterator[Int]` - co oznacza, że metoda `next` musi zwrócić wartość typu Int. + +## Podtyp + +Jeżeli w jakimś miejscu wymagana jest cecha pewnego typu, to zamiast niej można użyć jej podtypu. + +```scala mdoc +import scala.collection.mutable.ArrayBuffer + +trait Pet { + val name: String +} + +class Cat(val name: String) extends Pet +class Dog(val name: String) extends Pet + +val dog = new Dog("Harry") +val cat = new Cat("Sally") + +val animals = ArrayBuffer.empty[Pet] +animals.append(dog) +animals.append(cat) +animals.foreach(pet => println(pet.name)) // wyświetli Harry Sally ``` + +Cecha `trait Pet` posiada abstrakcyjne pole `name`, które zostaje zaimplementowane przez klasy `Cat` i `Dog` w ich konstruktorach. +W ostatnim wierszu wywołujemy `pet.name` musi być ono zaimplementowane przez każdy podtyp cechy `Pet`. diff --git a/_pl/tour/tuples.md b/_pl/tour/tuples.md new file mode 100644 index 0000000000..752b3a9d41 --- /dev/null +++ b/_pl/tour/tuples.md @@ -0,0 +1,87 @@ +--- +layout: tour +title: Krotki +partof: scala-tour + +num: 8 +language: pl +next-page: mixin-class-composition +previous-page: traits + +--- + +W Scali, krotka (ang. tuple) to klasa, która przechowuje elementy różnych typów. +Krotki są niezmienne. + +Krotki przydają się, gdy chcemy, żeby funkcja zwróciła jednocześnie wiele wartości. + +Krotki tworzy się w następujący sposób: + +```scala mdoc +val ingredient = ("Sugar" , 25): Tuple2[String, Int] +``` + +Powyższy kod tworzy krotkę zawierającą element typu String oraz typu Int. + +W Scali krotki reprezentowane są przez szereg klas: Tuple2, Tuple3 itd. aż do Tuple22. +Za każdym razem, kiedy tworzymy krotkę zawierającą _n_ elementów (_n_ musi zawierać się w przedziale od 2 do 22), Scala tworzy instancję jednej z odpowiadających klas z grupy TupleN i parametryzuje ją odpowiednimi wartościami. +W ww. przykładzie jest to `Tuple2[String, Int]`. + +## Dostęp do elementów + +Krotka zapewnia dostęp do swoich elementów z użyciem składni podkreślnika (underscore). +`tuple._n` odwołuje się do n-tego elementu w kolejności (pod warunkiem, że dana krotka zawiera tyle elementów). + +```scala mdoc +println(ingredient._1) // wyświetli Sugar + +println(ingredient._2) // wyświetli 25 +``` + +## Dekonstrukcja krotki + +Krotki w Scali wspierają dekonstrukcję + +```scala mdoc +val (name, quantity) = ingredient + +println(name) // wyświetli Sugar + +println(quantity) // wyświetli 25 +``` + +Dekonstrukcja krotek może być bardzo przydatna w dopasowywaniu wzorców (ang. pattern matching) + +```scala mdoc +val planetDistanceFromSun = List( + ("Mercury", 57.9), + ("Venus", 108.2), + ("Earth", 149.6), + ("Mars", 227.9), + ("Jupiter", 778.3) +) + +planetDistanceFromSun.foreach { + case ("Mercury", distance) => println(s"Merkury jest $distance milionów km od Słońca") + case p if p._1 == "Venus" => println(s"Wenus jest ${p._2} milionów km od Słońca") + case p if p._1 == "Earth" => println(s"Niebieska Planeta jest ${p._2} milionów km od Słońca") + case _ => println("Zbyt daleko...") +} +``` + +Ma ona też zastosowanie w wyrażeniach 'for'. + +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) + +for ((a, b) <- numPairs) { + println(a * b) +} +``` + +Wartość `()` typu `Unit` jest koncepcyjnie taka sama jak wartość `()` typu `Tuple0`. +Może być tylko jedna wartość tego typu, ponieważ nie zawiera żadnych elementów. + +Użytkownicy mogą czasami mieć trudności z wyborem pomiędzy krotkami (tuple) i klasami przypadków (case class). +Zazwyczaj klasy przypadków są preferowane wtedy, kiedy elementy niosą ze sobą jakieś większe znaczenie. +`` diff --git a/_pl/tour/type-inference.md b/_pl/tour/type-inference.md index c3d057bab9..f7f0d42055 100644 --- a/_pl/tour/type-inference.md +++ b/_pl/tour/type-inference.md @@ -1,12 +1,9 @@ --- layout: tour title: Lokalna inferencja typów - -discourse: false - partof: scala-tour -num: 28 +num: 30 language: pl next-page: operators previous-page: polymorphic-methods @@ -16,7 +13,7 @@ Scala posiada wbudowany mechanizm inferencji typów, który pozwala programiści Oto przykład: -```tut +```scala mdoc object InferenceTest1 extends App { val x = 1 + 2 * 3 // typem x jest Int val y = x.toString() // typem y jest String @@ -26,7 +23,7 @@ object InferenceTest1 extends App { Dla metod rekurencyjnych kompilator nie jest w stanie określić zwracanego typu. Oto przykład programu, który zakończy się niepowodzeniem kompilacji z tego powodu: -```tut:fail +```scala mdoc:fail object InferenceTest2 { def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1) } @@ -37,7 +34,7 @@ Nie jest też konieczne określenie parametrów typu, kiedy są wywoływane [met Oto ilustrujący to przykład: ``` -case class MyPair[A, B](x: A, y: B); +case class MyPair[A, B](x: A, y: B) object InferenceTest3 extends App { def id[T](x: T) = x val p = MyPair(1, "scala") // typ: MyPair[Int, String] @@ -54,7 +51,7 @@ val y: Int = id[Int](1) W niektórych sytuacjach poleganie na inferencji typów w Scali może być niebezpieczne, tak jak demonstruje to poniższy program: -```tut:fail +```scala mdoc:fail object InferenceTest4 { var obj = null obj = new Object() diff --git a/_pl/tour/unified-types.md b/_pl/tour/unified-types.md index 103647d8e7..831b720bb8 100644 --- a/_pl/tour/unified-types.md +++ b/_pl/tour/unified-types.md @@ -1,49 +1,101 @@ --- layout: tour title: Hierarchia typów - -discourse: false - partof: scala-tour -num: 2 +num: 3 language: pl next-page: classes -previous-page: tour-of-scala +previous-page: basics --- -W przeciwieństwie do Javy wszystkie wartości w Scali są obiektami (wliczając w to wartości numeryczne i funkcje). Ponieważ Scala bazuje na klasach, wszystkie wartości są instancjami klasy. Można zatem powiedzieć, że Scala posiada zunifikowany system typów. Poniższy diagram ilustruje hierarchię klas Scali: +W Scali wszystkie wartości mają określony typ, włączając w to wartości numeryczne i funkcje. +Poniższy diagram ilustruje podzbiór hirarchii typów. + +Scala Type Hierarchy -![Scala Type Hierarchy]({{ site.baseurl }}/resources/images/classhierarchy.img_assist_custom.png) +## Hierarchia Typów Scali ## -## Hierarchia Klas Scali ## +Typem bazowym dla wszystkich klas jest `Any`, jest on też nazywany typem górnym (top type). +Definiuje on uniwersalne metody takie jak `equals`, `hashCode` oraz `toString`. +`Any` posiada dwa bezpośrednie podtypy: `AnyVal` i `AnyRef`. -Klasa bazowa dla wszystkich klas `scala.Any` posiada dwie bezpośrednie klasy pochodne: `scala.AnyVal` oraz `scala.AnyRef`, które reprezentują dwie różne rodziny klas: klasy wartości oraz klasy referencji. Klasy wartości są predefiniowane i odpowiadają one typom prymitywnym z języków takich jak Java. Wszystkie inne klasy definiują typy referencyjne. Klasy zdefiniowane przez użytkownika są domyślnie typami referencyjnymi, tzn. są one zawsze podtypem klasy `scala.AnyRef`. W kontekście maszyny wirtualnej Javy `scala.AnyRef` odpowiada typowi `java.lang.Object`. Powyższy diagram ilustruje także konwersje implicit pomiędzy klasami wartości. +`AnyVal` reprezentuje typy wartości. +Żaden z tych typów nie może przyjąć wartości `null`. +Istnieje dziewięć predefiniowanych typów wartości: `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit` oraz `Boolean`. +`Unit` to typ wartości, która nie niesie ze sobą żadnej znaczącej informacji. +Istnieje dokładnie jedna instancja typu `Unit` i jest zdefiniowana dosłownie jako: `()`. +Wszystkie funkcje muszą coś zwracać, dlatego w niektórych przypadkach trzeba użyć `Unit` do oznaczenia zwracanego typu. -Poniższy przykład pokazuje, że liczby, znaki, wartości logiczne oraz funkcje są obiektami: +`AnyRef` reprezentuje typy referencyjne. +Przez referencje mamy w tym przypadku na myśli wskaźniki do innych obiektów. +Wszystkie typy niebędące wartościami są zdefiniowane jako typy referencyjne. +Każdy typ zdefiniowany przez użytkownika jest podtypem `AnyRef`. +Jeżeli Scala użyta jest w kontekście środowiska uruchomieniowego Javy, to `AnyRef` odnosi się do `java.lang.Object`. +Poniższy przykład pokazuje, że łańcuchy znakowe, liczby całkowite, znaki, wartości logiczne oraz funkcje są obiektami tak samo jak każdy inny obiekt: -```tut -object UnifiedTypes extends App { - val fun: Int => Int = _ + 1 // deklaracja funkcji - val set = new scala.collection.mutable.LinkedHashSet[Any] - set += "To jest łańcuch znaków" // dodaj łańcuch znaków - set += 732 // dodaj liczbę - set += 'c' // dodaj znak - set += true // dodaj wartość logiczną - set += fun _ // dodaj funkcję - set foreach println -} +```scala mdoc +val list: List[Any] = List( + "Łancuch znaków", + 732, // liczba całkowita + 'c', // znak + true, // wartość Boolowska + () => "funkcja anonimowa zwracająca łańcuch znaków" +) + +list.foreach(element => println(element)) ``` -Program deklaruje aplikację `UnifiedTypes` w postaci [obiektu singleton](singleton-objects.html) rozszerzającego klasę `App`. Aplikacja definiuje zmienną lokalną `set` odwołującą się do instancji klasy `LinkedHashSet[Any]`, która reprezentuje zbiór obiektów dowolnego typu (`Any`). Ostatecznie program wypisuje wszystkie elementy tego zbioru. +Program deklaruje wartość `list` typu `List[Any]`. +Lista jest zainicjowana elementami różnego typu, ale będącymi podtypami `scala.Any` - dlatego można je umieścić na tej liście. -Wynik działania programu: +Wynik działania powyższego programu: ``` -To jest łańcuch znaków +Łancuch znaków 732 c true ``` + +## Rzutowanie typów + +Typy wartości mogą być rzutowane w następujący sposób: + +Scala Type Hierarchy + +Dla przykładu: + +```scala mdoc +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 (w tym wypadku tracimy część precyzji) + +val face: Char = '☺' +val number: Int = face // 9786 +``` + +Rzutowanie jest jednokierunkowe, następujący kod nie zadziała: + +``` +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 +val z: Long = y // Błąd: Does not conform +``` + +Możliwe jest też rzutowanie referencji typu jego podtyp. +Zostanie to dokładniej omówione w kolejnych rozdziałach. + +## Typy Nothing oraz Null + +`Nothing` jest podtypem wszystkich typów, istnieje na samym dole hierarchii i jest nazywany typem dolnym (bottom type). +Nie istnieje żadna wartość typu `Nothing`. +Częstym przykładem użycia jest zasygnalizowanie stanów nieoznaczonych np. wyrzucony wyjątek, wyjście z programu, +nieskończona pętla (ściślej mówiąc - jest to typ wyrażenia które nie ewaluuje na żadną wartość lub metoda, która nie zwraca wyniku). + +`Null` jest podtypem wszystkich typów referencyjnych (wszystkich podtypów `AnyRef`). +Ma pojedynczą wartosć identyfikowaną przez słowo kluczowe `null`. +`Null` przydaje się głównie do współpracy z innymi językami platformy JVM i nie powinien być praktycznie nigdy używany +w kodzie w jęzku Scala. +W dalszej części przewodnika omówimy alternatywy dla `null`. diff --git a/_pl/tour/upper-type-bounds.md b/_pl/tour/upper-type-bounds.md index 000cd344c0..e9e801cd66 100644 --- a/_pl/tour/upper-type-bounds.md +++ b/_pl/tour/upper-type-bounds.md @@ -1,22 +1,19 @@ --- layout: tour title: Górne ograniczenia typów - -discourse: false - partof: scala-tour -num: 19 +num: 21 language: pl next-page: lower-type-bounds previous-page: variances --- -W Scali [parametry typów](generic-classes.html) oraz [typy abstrakcyjne](abstract-types.html) mogą być warunkowane przez ograniczenia typów. Tego rodzaju ograniczenia pomagają określić konkretne wartości zmiennych typu oraz odkryć więcej informacji na temat elementów tych typów. _Ograniczenie górne typu_ `T <: A` zakładają, że zmienna `T` jest podtypem typu `A`. +W Scali [parametry typów](generic-classes.html) oraz [typy abstrakcyjne](abstract-type-members.html) mogą być warunkowane przez ograniczenia typów. Tego rodzaju ograniczenia pomagają określić konkretne wartości zmiennych typu oraz odkryć więcej informacji na temat elementów tych typów. _Ograniczenie górne typu_ `T <: A` zakładają, że zmienna `T` jest podtypem typu `A`. Poniższy przykład demonstruje zastosowanie ograniczeń górnych typu dla parametru typu klasy `Cage`: -```tut +```scala mdoc abstract class Animal { def name: String } diff --git a/_pl/tour/variances.md b/_pl/tour/variances.md index 2faedf1cdd..db0e485413 100644 --- a/_pl/tour/variances.md +++ b/_pl/tour/variances.md @@ -1,12 +1,9 @@ --- layout: tour title: Wariancje - -discourse: false - partof: scala-tour -num: 18 +num: 20 language: pl next-page: upper-type-bounds previous-page: generic-classes @@ -16,7 +13,7 @@ Scala wspiera adnotacje wariancji parametrów typów [klas generycznych](generic Na stronie o [klasach generycznych](generic-classes.html) omówiliśmy przykład zmiennego stosu. Wyjaśniliśmy, że typ definiowany przez klasę `Stack[T]` jest poddany niezmiennemu podtypowaniu w stosunku do parametru typu. Może to ograniczyć możliwość ponownego wykorzystania abstrakcji tej klasy. Spróbujemy teraz opracować funkcyjną (tzn. niemutowalną) implementację dla stosów, które nie posiadają tego ograniczenia. Warto zwrócić uwagę, że jest to zaawansowany przykład łączący w sobie zastosowanie [funkcji polimorficznych](polymorphic-methods.html), [dolnych ograniczeń typu](lower-type-bounds.html) oraz kowariantnych adnotacji parametru typu. Dodatkowo stosujemy też [klasy wewnętrzne](inner-classes.html), aby połączyć ze sobą elementy stosu bez jawnych powiązań. -```tut +```scala mdoc class Stack[+T] { def push[S >: T](elem: S): Stack[S] = new Stack[S] { override def top: S = elem diff --git a/_plugins/alt-details-lib/alt-details.rb b/_plugins/alt-details-lib/alt-details.rb new file mode 100644 index 0000000000..f7bf5058a6 --- /dev/null +++ b/_plugins/alt-details-lib/alt-details.rb @@ -0,0 +1,44 @@ +require 'erb' + +module Jekyll + module AltDetails + class AltDetailsBlock < Liquid::Block + SYNTAX = /^\s*(#{Liquid::QuotedFragment})\s+(#{Liquid::QuotedFragment})(?=\s+class=(#{Liquid::QuotedFragment}))?/o + Syntax = SYNTAX + + alias_method :render_block, :render + + def unquote(string) + string.gsub(/^['"]|['"]$/, '') + end + + def initialize(block_name, markup, tokens) + super + + if markup =~ SYNTAX + @name = unquote($1) + @title = unquote($2) + @css_classes = "" + if $3 + # append $3 to @css_classes + @css_classes = "#{@css_classes} #{unquote($3)}" + end + else + raise SyntaxError.new("Block #{block_name} requires an id and a title") + end + end + + def render(context) + site = context.registers[:site] + converter = site.find_converter_instance(::Jekyll::Converters::Markdown) + altDetailsContent = converter.convert(render_block(context)) + currentDirectory = File.dirname(__FILE__) + templateFile = File.read(currentDirectory + '/template.erb') + template = ERB.new(templateFile) + template.result(binding) + end + end + end +end + +Liquid::Template.register_tag('altDetails', Jekyll::AltDetails::AltDetailsBlock) diff --git a/_plugins/alt-details-lib/alt-details/version.rb b/_plugins/alt-details-lib/alt-details/version.rb new file mode 100644 index 0000000000..147e33df9c --- /dev/null +++ b/_plugins/alt-details-lib/alt-details/version.rb @@ -0,0 +1,5 @@ +module Jekyll + module AltDetails + VERSION = "1.1.1" + end +end diff --git a/_plugins/alt-details-lib/template.erb b/_plugins/alt-details-lib/template.erb new file mode 100644 index 0000000000..95d65eb3ef --- /dev/null +++ b/_plugins/alt-details-lib/template.erb @@ -0,0 +1,11 @@ +
            +
            + + +
            +
            + <%= altDetailsContent %> +
            +
            +
            +
            diff --git a/_plugins/alt_details.rb b/_plugins/alt_details.rb new file mode 100644 index 0000000000..57d2420105 --- /dev/null +++ b/_plugins/alt_details.rb @@ -0,0 +1 @@ +require_relative "alt-details-lib/alt-details" diff --git a/_plugins/jekyll-tabs-lib/LICENCE b/_plugins/jekyll-tabs-lib/LICENCE new file mode 100644 index 0000000000..43ae840e30 --- /dev/null +++ b/_plugins/jekyll-tabs-lib/LICENCE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2022 Baptiste Bouchereau +Copyright (c) 2022 LAMP/EPFL + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/_plugins/jekyll-tabs-lib/README.md b/_plugins/jekyll-tabs-lib/README.md new file mode 100644 index 0000000000..4e84712723 --- /dev/null +++ b/_plugins/jekyll-tabs-lib/README.md @@ -0,0 +1,8 @@ +originally sourced from https://github.com/Ovski4/jekyll-tabs. + +changes: +- template.erb adapted to match the pre-existing tab html structure for docs.scala-lang.org +- `tabs` do not use secure random uuid as the id, the `tabs` name parameter is used instead. +- for the `tabs` block, add an optional second `class='foo bar'` parameter to allow custom classes for the tabs. +- for the `tab` block, reorder the parameters: the tab label comes first, followed by the name of the parent `tabs`. +- addition of a third `defaultTab` attribute for `tab`, which defaults to the final tab if not set. diff --git a/_plugins/jekyll-tabs-lib/jekyll-tabs-4scala.rb b/_plugins/jekyll-tabs-lib/jekyll-tabs-4scala.rb new file mode 100644 index 0000000000..b592fcc7f9 --- /dev/null +++ b/_plugins/jekyll-tabs-lib/jekyll-tabs-4scala.rb @@ -0,0 +1,189 @@ +require 'erb' + +module Jekyll + module Tabs + + ScalaVersions = ['Scala 2', 'Scala 3'] + BuildTools = ['Scala CLI', 'sbt', 'Mill'] + + def self.unquote(string) + string.gsub(/^['"]|['"]$/, '') + end + + def self.asAnchor(title) + title.gsub(/[^a-zA-Z0-9\-_]/, '-').gsub(/-{2,}/, '-').downcase + end + + TabDetails = Struct.new(:label, :anchor, :defaultTab, :content, keyword_init: true) + + class TabsBlock < Liquid::Block + SYNTAX = /^\s*(#{Liquid::QuotedFragment})(?=\s+class=(#{Liquid::QuotedFragment}))?/o + Syntax = SYNTAX + + def initialize(block_name, markup, tokens) + super + + if markup =~ SYNTAX + @name = Tabs::unquote($1) + @css_classes = "" + @tab_class = "" + if $2 + css_class = Tabs::unquote($2) + css_class.strip! + @tab_class = css_class + # append $2 to @css_classes + @css_classes = " #{css_class}" + end + else + raise SyntaxError.new("Block #{block_name} requires 1 attribute") + end + end + + def render(context) + environment = context.environments.first + environment["tabs-#{@name}"] = [] # reset every time (so page translations can use the same name) + if environment["CURRENT_TABS_ENV"].nil? + environment["CURRENT_TABS_ENV"] = @name + else + raise SyntaxError.new("Nested tabs are not supported") + end + super # super call renders the internal content + environment["CURRENT_TABS_ENV"] = nil # reset after rendering + foundDefault = false + + allTabs = environment["tabs-#{@name}"] + + seenTabs = [] + + def joinTabs(tabs) + tabs.to_a.map{|item| "'#{item}'"}.join(", ") + end + + def errorInvalidTab(tab, expectedTabs) + SyntaxError.new( + "Tab label '#{tab.label}' is not valid for tabs '#{@name}' with " + + "class=#{@tab_class}. Valid tab labels are: #{joinTabs(expectedTabs)}") + end + + def errorTabWithoutClass(tab, tabClass) + SyntaxError.new( + "Tab label '#{tab.label}' is not valid for tabs '#{@name}' without " + + "class=#{tabClass}") + end + + def errorMissingTab(expectedTabs) + SyntaxError.new( + "Tabs '#{@name}' with class=#{@tab_class} must have exactly the following " + + "tab labels: #{joinTabs(expectedTabs)}") + end + + def errorDuplicateTab(tab) + SyntaxError.new("Duplicate tab label '#{tab.label}' in tabs '#{@name}'") + end + + def errorTabDefault(tab) + SyntaxError.new( + "Tab label '#{tab.label}' should not be default for tabs '#{@name}' " + + "with class=#{@tab_class}") + end + + allTabs.each do | tab | + if seenTabs.include? tab.label + raise errorDuplicateTab(tab) + end + seenTabs.push tab.label + if tab.defaultTab + foundDefault = true + end + + def checkTab(tab, tabClass, expectedTabs, raiseIfMissingClass) + isValid = expectedTabs.include? tab.label + if @tab_class == tabClass + if !isValid + raise errorInvalidTab(tab, expectedTabs) + elsif tab.defaultTab + raise errorTabDefault(tab) + end + elsif raiseIfMissingClass and isValid + raise errorTabWithoutClass(tab, tabClass) + end + end + + checkTab(tab, "tabs-scala-version", Tabs::ScalaVersions, true) + checkTab(tab, "tabs-build-tool", Tabs::BuildTools, false) + end + + def checkExhaustivity(seenTabs, tabClass, expectedTabs) + if @tab_class == tabClass and seenTabs != expectedTabs + raise errorMissingTab(expectedTabs) + end + end + + checkExhaustivity(seenTabs, "tabs-scala-version", Tabs::ScalaVersions) + checkExhaustivity(seenTabs, "tabs-build-tool", Tabs::BuildTools) + + if !foundDefault and allTabs.length > 0 + if @tab_class == "tabs-scala-version" + # set last tab to default ('Scala 3') + allTabs[-1].defaultTab = true + else + # set first tab to default + allTabs[0].defaultTab = true + end + end + + currentDirectory = File.dirname(__FILE__) + templateFile = File.read(currentDirectory + '/template.erb') + template = ERB.new(templateFile) + template.result(binding) + end + end + + class TabBlock < Liquid::Block + alias_method :render_block, :render + + SYNTAX = /^\s*(#{Liquid::QuotedFragment})\s+(?:for=(#{Liquid::QuotedFragment}))?(?:\s+(defaultTab))?/o + Syntax = SYNTAX + + def initialize(block_name, markup, tokens) + super + + if markup =~ SYNTAX + @tab = Tabs::unquote($1) + if $2 + @name = Tabs::unquote($2) + end + @anchor = Tabs::asAnchor(@tab) + if $3 + @defaultTab = true + end + else + raise SyntaxError.new("Block #{block_name} requires at least 2 attributes") + end + end + + def render(context) + site = context.registers[:site] + mdoc_converter = site.find_converter_instance(::Jekyll::MdocConverter) + converter = site.find_converter_instance(::Jekyll::Converters::Markdown) + pre_content = mdoc_converter.convert(render_block(context)) + content = converter.convert(pre_content) + tabcontent = TabDetails.new(label: @tab, anchor: @anchor, defaultTab: @defaultTab, content: content) + environment = context.environments.first + tab_env = environment["CURRENT_TABS_ENV"] + if tab_env.nil? + raise SyntaxError.new("Tab block '#{tabcontent.label}' must be inside a tabs block") + end + if !@name.nil? && tab_env != @name + raise SyntaxError.new( + "Tab block '#{@tab}' for=#{@name} does not match its enclosing tabs block #{tab_env}") + end + environment["tabs-#{tab_env}"] ||= [] + environment["tabs-#{tab_env}"] << tabcontent + end + end + end +end + +Liquid::Template.register_tag('tab', Jekyll::Tabs::TabBlock) +Liquid::Template.register_tag('tabs', Jekyll::Tabs::TabsBlock) diff --git a/_plugins/jekyll-tabs-lib/jekyll-tabs/version.rb b/_plugins/jekyll-tabs-lib/jekyll-tabs/version.rb new file mode 100644 index 0000000000..498949a13d --- /dev/null +++ b/_plugins/jekyll-tabs-lib/jekyll-tabs/version.rb @@ -0,0 +1,5 @@ +module Jekyll + module Tabs + VERSION = "1.1.1" + end +end diff --git a/_plugins/jekyll-tabs-lib/template.erb b/_plugins/jekyll-tabs-lib/template.erb new file mode 100644 index 0000000000..e9d7867102 --- /dev/null +++ b/_plugins/jekyll-tabs-lib/template.erb @@ -0,0 +1,29 @@ +
            +
            + <% environment["tabs-#{@name}"].each do | tab | %> + > + <% end %> + +
            + <% environment["tabs-#{@name}"].each do | tab | %> +
            +
            + <%= tab.content %> +
            +
            + <% end %> +
            +
            +
            diff --git a/_plugins/jekyll_tabs_4scala.rb b/_plugins/jekyll_tabs_4scala.rb new file mode 100644 index 0000000000..7470d622a7 --- /dev/null +++ b/_plugins/jekyll_tabs_4scala.rb @@ -0,0 +1 @@ +require_relative "jekyll-tabs-lib/jekyll-tabs-4scala" diff --git a/_plugins/mdoc_replace.rb b/_plugins/mdoc_replace.rb new file mode 100644 index 0000000000..7cecf73aa6 --- /dev/null +++ b/_plugins/mdoc_replace.rb @@ -0,0 +1,24 @@ +module Jekyll + class MdocConverter < Converter + safe false + priority :high + + def matches(ext) + ext =~ /^\.(md|markdown)$/i + end + + def output_ext(ext) + ".html" + end + + def convert(content) + content = content.gsub("```scala mdoc:compile-only\n", "```scala\n") + content = content.gsub("```scala mdoc:fail\n", "```scala\n") + content = content.gsub("```scala mdoc:crash\n", "```scala\n") + content = content.gsub("```scala mdoc:nest\n", "```scala\n") + content = content.gsub("```scala mdoc:reset:crash\n", "```scala\n") + content = content.gsub("```scala mdoc:reset\n", "```scala\n") + content.gsub("```scala mdoc\n", "```scala\n") + end + end +end diff --git a/_plugins/tut_replace.rb b/_plugins/tut_replace.rb deleted file mode 100644 index 06ee3c7fe9..0000000000 --- a/_plugins/tut_replace.rb +++ /dev/null @@ -1,20 +0,0 @@ -module Jekyll - class TutConverter < Converter - safe false - priority :high - - def matches(ext) - ext =~ /^\.(md|markdown)$/i - end - - def output_ext(ext) - ".html" - end - - def convert(content) - content = content.gsub("```tut:fail\n", "```scala\n") - content = content.gsub("```tut:nofail\n", "```scala\n") - content.gsub("```tut\n", "```scala\n") - end - end -end diff --git a/_pt-br/cheatsheets/index.md b/_pt-br/cheatsheets/index.md index 5d3176bda0..658bd6bfa1 100644 --- a/_pt-br/cheatsheets/index.md +++ b/_pt-br/cheatsheets/index.md @@ -1,11 +1,11 @@ --- layout: cheatsheet -title: Scalacheat +title: Scala Cheatsheet partof: cheatsheet by: Reginaldo Russinholi -about: Agradecimentos a Brendan O'Connor, este 'cheatsheet' se destina a ser uma referência rápida às construções sintáticas de Scala. Licenciado por Brendan O'Connor sobre a licença CC-BY-SA 3.0. +about: Agradecimentos a Brendan O'Connor, este 'cheatsheet' se destina a ser uma referência rápida às construções sintáticas de Scala. Licenciado por Brendan O'Connor sobre a licença CC-BY-SA 3.0. language: pt-br --- @@ -47,7 +47,7 @@ language: pt-br | `var (x,y,z) = (1,2,3)` | atribuição desestruturada: desempacotando uma tupla através de "pattern matching". | | Ruim`var x,y,z = (1,2,3)` | erro oculto: cada variável é associada a tupla inteira. | | `var xs = List(1,2,3)` | lista (imutável). | -| `xs(2)` | indexação por parênteses. ([slides](http://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) | +| `xs(2)` | indexação por parênteses. ([slides](https://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) | | `1 :: List(2,3)` | concatenação. | | `1 to 5` _o mesmo que_ `1 until 6`
            `1 to 10 by 2` | sintáxe 'sugar' para intervalo. | | `()` _(parênteses vazio)_ | um membro do tipo Unit (igual ao void de C/Java). | @@ -56,11 +56,11 @@ language: pt-br | `if (check) happy` _o mesmo que_
            `if (check) happy else ()` | condicional 'sugar'. | | `while (x < 5) { println(x); x += 1}` | while. | | `do { println(x); x += 1} while (x < 5)` | do while. | -| `import scala.util.control.Breaks._`
            `breakable {`
            ` for (x <- xs) {`
            ` if (Math.random < 0.1) break`
            ` }`
            `}`| break. ([slides](http://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) | +| `import scala.util.control.Breaks._`
            `breakable {`
            ` for (x <- xs) {`
            ` if (Math.random < 0.1) break`
            ` }`
            `}`| break. ([slides](https://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) | | `for (x <- xs if x%2 == 0) yield x*10` _o mesmo que_
            `xs.filter(_%2 == 0).map(_*10)` | for: filter/map | | `for ((x,y) <- xs zip ys) yield x*y` _o mesmo que_
            `(xs zip ys) map { case (x,y) => x*y }` | for: associação desestruturada | | `for (x <- xs; y <- ys) yield x*y` _o mesmo que_
            `xs flatMap {x => ys map {y => x*y}}` | for: produto cruzado | -| `for (x <- xs; y <- ys) {`
            `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
            `}` | for: estilo imperativo
            [sprintf-style](http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | +| `for (x <- xs; y <- ys) {`
            `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
            `}` | for: estilo imperativo
            [sprintf-style](https://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | | `for (i <- 1 to 5) {`
            `println(i)`
            `}` | for: itera incluindo o limite superior | | `for (i <- 1 until 5) {`
            `println(i)`
            `}` | for: itera omitindo o limite superior | | pattern matching | | diff --git a/_pt-br/tour/abstract-types.md b/_pt-br/tour/abstract-type-members.md similarity index 82% rename from _pt-br/tour/abstract-types.md rename to _pt-br/tour/abstract-type-members.md index 5eda5a34b9..e8dba1011c 100644 --- a/_pt-br/tour/abstract-types.md +++ b/_pt-br/tour/abstract-type-members.md @@ -1,9 +1,6 @@ --- layout: tour title: Tipos Abstratos - -discourse: false - partof: scala-tour num: 22 @@ -16,7 +13,7 @@ Em Scala, as classes são parametrizadas com valores (os parâmetros de construt Aqui está um exemplo que mostra uma definição de valor diferido e uma definição de tipo abstrato como membros de uma [trait](traits.html) chamada `Buffer`. -```tut +```scala mdoc trait Buffer { type T val element: T @@ -27,7 +24,7 @@ trait Buffer { No seguinte programa temos uma classe `SeqBuffer` que nos permite armazenar apenas as sequências no buffer ao definir que o tipo `T` precisa ser um subtipo de `Seq[U]` para um novo tipo abstrato `U`: -```tut +```scala mdoc abstract class SeqBuffer extends Buffer { type U type T <: Seq[U] @@ -37,43 +34,39 @@ abstract class SeqBuffer extends Buffer { [Traits](traits.html) ou [classes](classes.html) com membros de tipo abstratos são frequentemente utilizadas em combinação com instâncias de classe anônimas. Para ilustrar isso, agora analisamos um programa que lida com um buffer de sequência que se refere a uma lista de inteiros: -```tut +```scala mdoc abstract class IntSeqBuffer extends SeqBuffer { type U = Int } -object AbstractTypeTest1 extends App { - def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = - new IntSeqBuffer { - type T = List[U] - val element = List(elem1, elem2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) -} +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) ``` O tipo de retorno do método `newIntSeqBuf` refere-se a uma especialização da trait `Buffer` no qual o tipo `U` é agora equivalente a `Int`. Declaramos um tipo *alias* semelhante ao que temos na instanciação da classe anônima dentro do corpo do método `newIntSeqBuf`. Criamos uma nova instância de `IntSeqBuffer` na qual o tipo `T` refere-se a `List[Int]`. Observe que muitas vezes é possível transformar os membros de tipo abstrato em parâmetros de tipo de classes e vice-versa. Aqui está uma versão do código acima que usa apenas parâmetros de tipo: -```tut +```scala mdoc:nest abstract class Buffer[+T] { val element: T } abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { def length = element.length } -object AbstractTypeTest2 extends App { - def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = - new SeqBuffer[Int, List[Int]] { - val element = List(e1, e2) - } - val buf = newIntSeqBuf(7, 8) - println("length = " + buf.length) - println("content = " + buf.element) -} +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) ``` Note que temos que usar [anotação de variância](variances.html) aqui; Caso contrário, não seríamos capazes de ocultar o tipo implementado pela sequência concreta do objeto retornado pelo método `newIntSeqBuf`. Além disso, há casos em que não é possível substituir tipos abstratos com parâmetros de tipo. diff --git a/_pt-br/tour/annotations.md b/_pt-br/tour/annotations.md index 3b262897de..55d49cc441 100644 --- a/_pt-br/tour/annotations.md +++ b/_pt-br/tour/annotations.md @@ -1,14 +1,11 @@ --- layout: tour title: Anotações - -discourse: false - partof: scala-tour num: 31 -next-page: default-parameter-values -previous-page: automatic-closures +next-page: packages-and-imports +previous-page: operators language: pt-br --- @@ -22,16 +19,15 @@ O significado das cláusulas de anotação é _dependente da implementação_. N | Scala | Java | | ------ | ------ | -| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](http://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (field) | -| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | +| [`scala.SerialVersionUID`](https://www.scala-lang.org/api/current/scala/SerialVersionUID.html) | [`serialVersionUID`](https://java.sun.com/j2se/1.5.0/docs/api/java/io/Serializable.html#navbar_bottom) (field) | +| [`scala.deprecated`](https://www.scala-lang.org/api/current/scala/deprecated.html) | [`java.lang.Deprecated`](https://java.sun.com/j2se/1.5.0/docs/api/java/lang/Deprecated.html) | | [`scala.inline`](https://www.scala-lang.org/api/current/scala/inline.html) (desde 2.6.0) | não há equivalente | -| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (desde 2.6.0) | [`native`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | -| [`scala.remote`](https://www.scala-lang.org/api/current/scala/remote.html) | [`java.rmi.Remote`](http://java.sun.com/j2se/1.5.0/docs/api/java/rmi/Remote.html) | -| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | -| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | +| [`scala.native`](https://www.scala-lang.org/api/current/scala/native.html) (desde 2.6.0) | [`native`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | +| [`scala.throws`](https://www.scala-lang.org/api/current/scala/throws.html) | [`throws`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | +| [`scala.transient`](https://www.scala-lang.org/api/current/scala/transient.html) | [`transient`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | | [`scala.unchecked`](https://www.scala-lang.org/api/current/scala/unchecked.html) (since 2.4.0) | não há equivalente | -| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](http://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | -| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`Design pattern`](http://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | +| [`scala.volatile`](https://www.scala-lang.org/api/current/scala/volatile.html) | [`volatile`](https://java.sun.com/docs/books/tutorial/java/nutsandbolts/_keywords.html) (keyword) | +| [`scala.beans.BeanProperty`](https://www.scala-lang.org/api/current/scala/beans/BeanProperty.html) | [`Design pattern`](https://docs.oracle.com/javase/tutorial/javabeans/writing/properties.html) | No exemplo a seguir, adicionamos a anotação `throws` à definição do método `read` para capturar a exceção lançada no código Java. @@ -85,7 +81,7 @@ corresponding try statement **Nota:** Certifique-se de usar a opção `-target: jvm-1.5` com anotações Java. -Java 1.5 introduziu metadados definidos pelo usuário na forma de [anotações](http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html). Uma característica chave das anotações é que elas dependem da especificação de pares no formato nome-valor para inicializar seus elementos. Por exemplo, se precisamos de uma anotação para rastrear a origem de alguma classe, podemos defini-la como: +Java 1.5 introduziu metadados definidos pelo usuário na forma de [anotações](https://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html). Uma característica chave das anotações é que elas dependem da especificação de pares no formato nome-valor para inicializar seus elementos. Por exemplo, se precisamos de uma anotação para rastrear a origem de alguma classe, podemos defini-la como: ``` @interface Source { @@ -97,7 +93,7 @@ Java 1.5 introduziu metadados definidos pelo usuário na forma de [anotações]( O uso da anotação Source fica da seguinte forma ``` -@Source(URL = "http://coders.com/", +@Source(URL = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... ``` @@ -105,7 +101,7 @@ public class MyClass extends HisClass ... A uso de anotações em Scala parece uma invocação de construtor, para instanciar uma anotação Java é preciso usar argumentos nomeados: ``` -@Source(URL = "http://coders.com/", +@Source(URL = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` @@ -122,21 +118,21 @@ Esta sintaxe é bastante tediosa, se a anotação contiver apenas um parâmetro O uso da anotação SourceURL fica da seguinte forma ``` -@SourceURL("http://coders.com/") +@SourceURL("https://coders.com/") public class MyClass extends HisClass ... ``` Neste caso, a Scala oferece a mesma possibilidade ``` -@SourceURL("http://coders.com/") +@SourceURL("https://coders.com/") class MyScalaClass ... ``` O elemento `mail` foi especificado com um valor padrão, portanto não precisamos fornecer explicitamente um valor para ele. No entanto, se precisarmos fazer isso, não podemos misturar e combinar os dois estilos em Java: ``` -@SourceURL(value = "http://coders.com/", +@SourceURL(value = "https://coders.com/", mail = "support@coders.com") public class MyClass extends HisClass ... ``` @@ -144,7 +140,7 @@ public class MyClass extends HisClass ... Scala proporciona mais flexibilidade a respeito disso: ``` -@SourceURL("http://coders.com/", +@SourceURL("https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` diff --git a/_pt-br/tour/automatic-closures.md b/_pt-br/tour/automatic-closures.md deleted file mode 100644 index 3d919a9ec5..0000000000 --- a/_pt-br/tour/automatic-closures.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -layout: tour -title: Construção Automática de Closures de Tipo-Dependente - -discourse: false - -partof: scala-tour - -num: 30 -next-page: annotations -previous-page: operators -language: pt-br ---- - -_Nota de tradução: A palavra `closure` em pode ser traduzida como encerramento/fechamento, porém é preferível utilizar a notação original_ - -Scala permite funções sem parâmetros como parâmetros de métodos. Quando um tal método é chamado, os parâmetros reais para nomes de função sem parâmetros não são avaliados e uma função nula é passada em vez disso, tal função encapsula a computação do parâmetro correspondente (isso é conhecido por avaliação *call-by-name*). - -O código a seguir demonstra esse mecanismo: - -```tut -object TargetTest1 extends App { - def whileLoop(cond: => Boolean)(body: => Unit): Unit = - if (cond) { - body - whileLoop(cond)(body) - } - var i = 10 - whileLoop (i > 0) { - println(i) - i -= 1 - } -} -``` - -A função `whileLoop` recebe dois parâmetros: `cond` e `body`. Quando a função é aplicada, os parâmetros reais não são avaliados. Mas sempre que os parâmetros formais são usados no corpo de `whileLoop`, as funções nulas criadas implicitamente serão avaliadas em seu lugar. Assim, o nosso método `whileLoop` implementa um while-loop Java-like com um esquema de implementação recursiva. - -Podemos combinar o uso de [operadores infix/postfix](operators.html) com este mecanismo para criar declarações mais complexas (com uma sintaxe agradável). - -Aqui está a implementação de uma instrução que executa loop a menos que uma condição seja satisfeita: - -```tut -object TargetTest2 extends App { - def loop(body: => Unit): LoopUnlessCond = - new LoopUnlessCond(body) - protected class LoopUnlessCond(body: => Unit) { - def unless(cond: => Boolean) { - body - if (!cond) unless(cond) - } - } - var i = 10 - loop { - println("i = " + i) - i -= 1 - } unless (i == 0) -} -``` - -A função `loop` aceita apenas um corpo e retorna uma instância da classe` LoopUnlessCond` (que encapsula este objeto de corpo). Note que o corpo ainda não foi avaliado. A classe `LoopUnlessCond` tem um método `unless` que podemos usar como um *operador infix*. Dessa forma, obtemos uma sintaxe bastante natural para nosso novo loop: `loop { } unless ( )`. - -Aqui está a saída de quando o `TargetTest2` é executado: - -``` -i = 10 -i = 9 -i = 8 -i = 7 -i = 6 -i = 5 -i = 4 -i = 3 -i = 2 -i = 1 -``` diff --git a/_pt-br/tour/basics.md b/_pt-br/tour/basics.md index b61c4a110d..ccb7809155 100644 --- a/_pt-br/tour/basics.md +++ b/_pt-br/tour/basics.md @@ -1,9 +1,6 @@ --- layout: tour title: Basics - -discourse: false - partof: scala-tour language: pt-br --- diff --git a/_pt-br/tour/by-name-parameters.md b/_pt-br/tour/by-name-parameters.md index f470f57d05..d0f9f5641d 100644 --- a/_pt-br/tour/by-name-parameters.md +++ b/_pt-br/tour/by-name-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: By-name Parameters - -discourse: false - partof: scala-tour language: pt-br --- diff --git a/_pt-br/tour/case-classes.md b/_pt-br/tour/case-classes.md index 67d98d6d6d..5524865ee6 100644 --- a/_pt-br/tour/case-classes.md +++ b/_pt-br/tour/case-classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Classes Case - -discourse: false - partof: scala-tour num: 10 @@ -21,7 +18,7 @@ Scala suporta o conceito de _classes case_. Classes case são classes regulares Aqui temos um exemplo de hierarquia de tipos para *Notification* que consiste em uma super classe abstrata `Notification` e três tipos concretos de notificação implementados com classes case `Email`, `SMS`, e `VoiceRecording`. -```tut +```scala mdoc abstract class Notification case class Email(sourceEmail: String, title: String, body: String) extends Notification case class SMS(sourceNumber: String, message: String) extends Notification @@ -30,26 +27,26 @@ case class VoiceRecording(contactName: String, link: String) extends Notificatio Instânciar uma classe case é fácil: (Perceba que nós não precisamos da palavra-chave `new`) -```tut +```scala mdoc val emailDeJohn = Email("john.doe@mail.com", "Saudações do John!", "Olá Mundo") ``` Os parâmetros do construtor de uma classe case são tratados como valores públicos e podem ser acessados diretamente. -```tut +```scala mdoc val titulo = emailDeJohn.title println(titulo) // prints "Saudações do John!" ``` Com classes case, você não pode alterar seus campos diretamente. (ao menos que você declare `var` antes de um campo, mas fazê-lo geralmente é desencorajado). -```tut:fail +```scala mdoc:fail emailDeJohn.title = "Adeus do John!" // Erro the compilação. Não podemos atribuir outro valor para um campo que foi declarado como val, lembrando que todos os campos de classes case são val por padrão. ``` Ao invés disso, faça uma cópia utilizando o método `copy`. Como descrito abaixo, então você poderá substituir alguns dos campos: -```tut +```scala mdoc val emailEditado = emailDeJohn.copy(title = "Estou aprendendo Scala!", body = "É muito legal!") println(emailDeJohn) // prints "Email(john.doe@mail.com,Saudações do John!,Hello World!)" @@ -58,7 +55,7 @@ println(emailEditado) // prints "Email(john.doe@mail.com,Estou aprendendo Scala, Para cada classe case em Scala o compilador gera um método `equals` que implementa a igualdade estrutural e um método `toString`. Por exemplo: -```tut +```scala mdoc val primeiroSMS = SMS("12345", "Hello!") val segundoSMS = SMS("12345", "Hello!") @@ -78,7 +75,7 @@ SMS é: SMS(12345, Hello!) Com classes case, você pode utilizar **correspondência de padrões** para manipular seus dados. Aqui temos um exemplo de uma função que escreve como saída diferente mensagens dependendo do tipo de notificação recebida: -```tut +```scala mdoc def mostrarNotificacao(notificacao: Notification): String = { notificacao match { case Email(email, title, _) => @@ -99,7 +96,7 @@ println(mostrarNotificacao(algumaMsgVoz)) // Saída "Você recebeu uma Mensagem Aqui um exemplo mais elaborado utilizando a proteção `if`. Com a proteção `if`, o correspondência de padrão irá falhar se a condição de proteção retorna falso. -```tut +```scala mdoc:nest def mostrarNotificacaoEspecial(notificacao: Notification, emailEspecial: String, numeroEspecial: String): String = { notificacao match { case Email(email, _, _) if email == emailEspecial => diff --git a/_pt-br/tour/classes.md b/_pt-br/tour/classes.md index a3718ca93e..4683128312 100644 --- a/_pt-br/tour/classes.md +++ b/_pt-br/tour/classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Classes - -discourse: false - partof: scala-tour num: 3 @@ -15,7 +12,7 @@ language: pt-br Classes em Scala são templates estáticos que podem ser instanciados como vários objetos em tempo de execução. Aqui uma definição de classe que define a classe `Ponto`: -```tut +```scala mdoc class Ponto(var x: Int, var y: Int) { def move(dx: Int, dy: Int): Unit = { x = x + dx @@ -34,9 +31,9 @@ Perceba que em Scala, não é necessário declarar `return` para então retornar Classes são instânciadas com a primitiva `new`, por exemplo: -```tut +```scala mdoc object Classes { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val pt = new Ponto(1, 2) println(pt) pt.move(10, 10) diff --git a/_pt-br/tour/compound-types.md b/_pt-br/tour/compound-types.md index 2639ddff3d..7465bdebb4 100644 --- a/_pt-br/tour/compound-types.md +++ b/_pt-br/tour/compound-types.md @@ -1,14 +1,11 @@ --- layout: tour title: Tipos Compostos - -discourse: false - partof: scala-tour num: 23 next-page: self-types -previous-page: abstract-types +previous-page: abstract-type-members language: pt-br --- @@ -16,7 +13,7 @@ language: pt-br Suponha que temos duas traits `Cloneable` and `Resetable`: -```tut +```scala mdoc trait Cloneable extends java.lang.Cloneable { override def clone(): Cloneable = { super.clone().asInstanceOf[Cloneable] @@ -51,4 +48,4 @@ Os tipos de compostos podem consistir em vários tipos de objeto e eles podem te A forma geral é: `A with B with C ... { refinamento }` -Um exemplo para o uso de refinamentos é dado na página sobre [tipos abstratos](abstract-types.html). +Um exemplo para o uso de refinamentos é dado na página sobre [tipos abstratos](abstract-type-members.html). diff --git a/_pt-br/tour/default-parameter-values.md b/_pt-br/tour/default-parameter-values.md index 2553bc5cad..197ca5c058 100644 --- a/_pt-br/tour/default-parameter-values.md +++ b/_pt-br/tour/default-parameter-values.md @@ -1,9 +1,6 @@ --- layout: tour title: Parâmetro com Valor Padrão - -discourse: false - partof: scala-tour num: 32 @@ -53,7 +50,7 @@ Enquanto isso nos impede de nos repetir, é menos do que expressivo. Scala adiciona suporte direto para isso: -```tut +```scala mdoc class HashMap[K,V](initialCapacity:Int = 16, loadFactor:Float = 0.75f) { } diff --git a/_pt-br/tour/extractor-objects.md b/_pt-br/tour/extractor-objects.md index 4508c778a3..e91788ee9f 100644 --- a/_pt-br/tour/extractor-objects.md +++ b/_pt-br/tour/extractor-objects.md @@ -1,9 +1,6 @@ --- layout: tour title: Objetos Extratores - -discourse: false - partof: scala-tour num: 15 @@ -14,7 +11,7 @@ language: pt-br Em Scala, padrões podem ser definidos independentemente de classes case. Para este fim, um método chamado `unapply` é definido para retornar um extrator. Um extrator pode ser pensado como um método especial que inverte o efeito da aplicação de um determinado objeto em algumas entradas. Seu objetivo é "extrair" as entradas que estavam presentes antes da operação `apply`. Por exemplo, o código a seguir define um [objeto](singleton-objects.html) extrator chamado Twice. -```tut +```scala mdoc object Twice { def apply(x: Int): Int = x * 2 def unapply(z: Int): Option[Int] = if (z%2 == 0) Some(z/2) else None diff --git a/_pt-br/tour/for-comprehensions.md b/_pt-br/tour/for-comprehensions.md index a1363d1cc1..eff027b842 100644 --- a/_pt-br/tour/for-comprehensions.md +++ b/_pt-br/tour/for-comprehensions.md @@ -1,9 +1,6 @@ --- layout: tour title: For Comprehensions - -discourse: false - partof: scala-tour language: pt-br --- diff --git a/_pt-br/tour/generic-classes.md b/_pt-br/tour/generic-classes.md index 4a31269598..b81c21c1a3 100644 --- a/_pt-br/tour/generic-classes.md +++ b/_pt-br/tour/generic-classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Classes Genéricas - -discourse: false - partof: scala-tour num: 17 @@ -15,12 +12,13 @@ language: pt-br Semelhante ao Java 5 (aka. JDK 1.5), Scala tem suporte nativo para classes parametrizadas com tipos. Essas classes genéricas são particularmente úteis para o desenvolvimento de classes que representam coleções de dados. Aqui temos um exemplo que demonstra isso: -```tut +```scala mdoc class Stack[T] { var elems: List[T] = Nil - def push(x: T) { elems = x :: elems } + def push(x: T): Unit = + elems = x :: elems def top: T = elems.head - def pop() { elems = elems.tail } + def pop(): Unit = { elems = elems.tail } } ``` @@ -28,7 +26,7 @@ A classe `Stack` modela uma pilha mutável que contém elementos de um tipo arbi Aqui temos mais alguns exemplos de uso: -```tut +```scala mdoc object GenericsTest extends App { val stack = new Stack[Int] stack.push(1) diff --git a/_pt-br/tour/higher-order-functions.md b/_pt-br/tour/higher-order-functions.md index 7cb79017bf..d2549f72db 100644 --- a/_pt-br/tour/higher-order-functions.md +++ b/_pt-br/tour/higher-order-functions.md @@ -1,9 +1,6 @@ --- layout: tour title: Funções de ordem superior - -discourse: false - partof: scala-tour num: 7 @@ -14,7 +11,7 @@ language: pt-br Scala permite definir funções de ordem superior. Tais funções _recebem outras funções como parâmetros_, ou _resultam em uma função_. Por exemplo, a função `apply` recebe outra função `f` e um valor `v` então aplica a função `f` em`v`: -```tut +```scala mdoc def apply(f: Int => String, v: Int) = f(v) ``` @@ -22,7 +19,7 @@ _Nota: métodos são automaticamente convertidos em funções se o contexto dema Outro exemplo: -```tut +```scala mdoc class Decorator(left: String, right: String) { def layout[A](x: A) = left + x.toString() + right } diff --git a/_pt-br/tour/implicit-conversions.md b/_pt-br/tour/implicit-conversions.md index f4686c9001..61ee6cac54 100644 --- a/_pt-br/tour/implicit-conversions.md +++ b/_pt-br/tour/implicit-conversions.md @@ -1,9 +1,6 @@ --- layout: tour title: Conversões Implícitas - -discourse: false - partof: scala-tour num: 26 @@ -44,11 +41,11 @@ O objeto implicitamente importado `scala.Predef` declara vários tipos predefini Por exemplo, ao chamar um método Java que espera um `java.lang.Integer`, você está livre para passar um `scala.Int` em vez disso. Isso ocorre porque `Predef` inclui as seguintes conversões implícitas: -```tut +```scala mdoc import scala.language.implicitConversions -implicit def int2Integer(x: Int) = - java.lang.Integer.valueOf(x) +implicit def int2Integer(x: Int): Integer = + Integer.valueOf(x) ``` Para definir suas próprias conversões implícitas, primeiro você deve importar `scala.language.implicitConversions` (ou invocar o compilador com a opção `-language: implicitConversions`). Tal recurso deve ser explicitamente habilitado porque pode se tornar complexo se usado indiscriminadamente. diff --git a/_pt-br/tour/implicit-parameters.md b/_pt-br/tour/implicit-parameters.md index e960414647..7f1f0d0a98 100644 --- a/_pt-br/tour/implicit-parameters.md +++ b/_pt-br/tour/implicit-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: Parâmetros Implícitos - -discourse: false - partof: scala-tour num: 25 @@ -22,7 +19,7 @@ Os argumentos reais que são elegíveis para serem passados para um parâmetro i No exemplo a seguir, definimos um método `sum` que calcula a soma de uma lista de elementos usando as operações `add` e `unit` do monoide. Observe que valores implícitos não podem ser *top-level*, eles precisam ser membros de um modelo. -```tut +```scala mdoc /** Este exemplo usa uma estrutura da álgebra abstrata para mostrar como funcionam os parâmetros implícitos. Um semigrupo é uma estrutura algébrica em um conjunto A com uma operação (associativa), chamada add, que combina um par de A's e retorna um outro A. */ abstract class SemiGroup[A] { def add(x: A, y: A): A diff --git a/_pt-br/tour/inner-classes.md b/_pt-br/tour/inner-classes.md index 266b8faad3..afaed9d896 100644 --- a/_pt-br/tour/inner-classes.md +++ b/_pt-br/tour/inner-classes.md @@ -1,25 +1,22 @@ --- layout: tour title: Classes Internas - -discourse: false - partof: scala-tour num: 21 -next-page: abstract-types +next-page: abstract-type-members previous-page: lower-type-bounds language: pt-br --- Em Scala é possível declarar classes que tenham outras classes como membros. Em contraste com a linguagenm Java, onde classes internas são membros da classe em que foram declaradas, em Scala as classes internas são ligadas ao objeto exterior. Para ilustrar essa diferença, rapidamente esboçamos a implementação de grafo como um tipo de dados: -```tut +```scala mdoc class Graph { class Node { var connectedNodes: List[Node] = Nil - def connectTo(node: Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -34,9 +31,9 @@ class Graph { ``` Em nosso programa, os grafos são representados por uma lista de nós. Os nós são objetos da classe interna `Node`. Cada nó tem uma lista de vizinhos, que são armazenados na lista `connectedNodes`. Agora podemos configurar um grafo com alguns nós e conectar os nós de forma incremental: - -```tut -object GraphTest extends App { + +```scala mdoc:nest +def graphTest: Unit = { val g = new Graph val n1 = g.newNode val n2 = g.newNode @@ -47,9 +44,9 @@ object GraphTest extends App { ``` Agora melhoramos o exemplo acima com tipos, para assim declarar explicitamente qual o tipo das várias entidades definidas: - -```tut -object GraphTest extends App { + +```scala mdoc:nest +def graphTest: Unit = { val g: Graph = new Graph val n1: g.Node = g.newNode val n2: g.Node = g.newNode @@ -61,8 +58,8 @@ object GraphTest extends App { Este código mostra claramente que o tipo nó é prefixado com sua instância externa (em nosso exemplo é o objeto `g`). Se agora temos dois grafos, o sistema de tipos de Scala não nos permite misturar nós definidos dentro de um grafo com os nós de outro, já que os nós do outro grafo têm um tipo diferente. Aqui está um programa inválido: - -```tut:fail + +```scala mdoc:fail object IllegalGraphTest extends App { val g: Graph = new Graph val n1: g.Node = g.newNode @@ -75,13 +72,13 @@ object IllegalGraphTest extends App { ``` Observe que em Java a última linha no programa do exemplo anterior é válida. Para nós de ambos os grafos, Java atribuiria o mesmo tipo `Graph.Node`; isto é, `Node` é prefixado com a classe `Graph`. Em Scala, esse tipo também pode ser expresso, e é escrito `Graph#Node`. Se quisermos ser capazes de conectar nós de diferentes grafos, temos que mudar a definição inicial da nossa implementação do grafo da seguinte maneira: - -```tut + +```scala mdoc:nest class Graph { class Node { var connectedNodes: List[Graph#Node] = Nil - def connectTo(node: Graph#Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } diff --git a/_pt-br/tour/lower-type-bounds.md b/_pt-br/tour/lower-type-bounds.md index 544609d6d7..61e5553ec7 100644 --- a/_pt-br/tour/lower-type-bounds.md +++ b/_pt-br/tour/lower-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: Limitante Inferior de Tipos - -discourse: false - partof: scala-tour num: 20 @@ -16,7 +13,7 @@ Enquanto o [limitante superior de tipos](upper-type-bounds.html) limita um tipo Aqui está um exemplo onde isso é útil: -```tut +```scala mdoc case class ListNode[T](h: T, t: ListNode[T]) { def head: T = h def tail: ListNode[T] = t @@ -27,7 +24,7 @@ case class ListNode[T](h: T, t: ListNode[T]) { O programa acima implementa uma linked list com uma operação de pré-inserção. Infelizmente, esse tipo é invariante no parâmetro de tipo da classe `ListNode`; Ou seja, `ListNode [String]` não é um subtipo de `ListNode [Any]`. Com a ajuda de [anotações de variância](variances.html) podemos expressar tal semântica de subtipo: -``` +```scala case class ListNode[+T](h: T, t: ListNode[T]) { ... } ``` @@ -35,7 +32,7 @@ Infelizmente, este programa não compila, porque uma anotação de covariância Aqui está o código correspondente: -```tut +```scala mdoc:reset case class ListNode[+T](h: T, t: ListNode[T]) { def head: T = h def tail: ListNode[T] = t @@ -48,7 +45,7 @@ _Nota:_ o novo método `prepend` tem um tipo ligeiramente menos restritivo. Perm Aqui está o código que ilustra isso: -```tut +```scala object LowerBoundTest extends App { val empty: ListNode[Null] = ListNode(null, null) val strList: ListNode[String] = empty.prepend("hello") diff --git a/_pt-br/tour/mixin-class-composition.md b/_pt-br/tour/mixin-class-composition.md index 4d000b3896..e317924e0b 100644 --- a/_pt-br/tour/mixin-class-composition.md +++ b/_pt-br/tour/mixin-class-composition.md @@ -1,21 +1,18 @@ --- layout: tour title: Composição de Classes Mixin - -discourse: false - partof: scala-tour num: 5 next-page: higher-order-functions -previous-page: traits +previous-page: tuples language: pt-br --- _Nota de tradução: A palavra `mixin` pode ser traduzida como mescla, porém é preferível utilizar a notação original_ Ao contrário de linguagens que suportam somente _herança simples_, Scala tem uma noção mais abrangente sobre a reutilização de classes. Scala torna possível reutilizar a _nova definição de membros de uma classe_ (por exemplo: o relacionamento delta para com a superclasse) na definição de uma nova classe. Isso é expressado como uma _composição de classe mixin ou mixin-class composition_. Considere a seguinte abstração para iterators. -```tut +```scala mdoc abstract class AbsIterator { type T def hasNext: Boolean @@ -25,15 +22,15 @@ abstract class AbsIterator { A seguir, considere a classe mixin que estende `AbsIterator` com um método `foreach` que aplica uma dada função para cada elemento retornado pelo iterator. Para definir tal classe que será utilizada como um mixin a palavra-chave `trait` deve ser declarada. -```tut +```scala mdoc trait RichIterator extends AbsIterator { - def foreach(f: T => Unit) { while (hasNext) f(next()) } + def foreach(f: T => Unit): Unit = { while (hasNext) f(next()) } } ``` Aqui uma classes iterator concreta a qual retorna sucessivos caracteres de uma dada string: -```tut +```scala mdoc class StringIterator(s: String) extends AbsIterator { type T = Char private var i = 0 @@ -44,9 +41,9 @@ class StringIterator(s: String) extends AbsIterator { Poderíamos combinar a funcionalidade de `StringIterator` e `RichIterator` em uma só classe. Com herança simples e interfaces isso é impossível, pois ambas as classes contém implementações para seus membros. Scala nos ajuda com a sua _composição de classes mixin_. Isso permite que programadores reutilizem o delta de uma definição de uma classe, por exemplo: todas as novas definições não são herdadas. Esse mecanismo torna possível combinar `StringIterator` com `RichIterator`, como pode ser visto no programa teste a seguir, que imprime uma coluna de todos os caracteres de uma dada string. -```tut +```scala mdoc object StringIteratorTest { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { class Iter extends StringIterator("Scala") with RichIterator val iter = new Iter iter foreach println diff --git a/_pt-br/tour/multiple-parameter-lists.md b/_pt-br/tour/multiple-parameter-lists.md index 505c806734..8523bc75ba 100644 --- a/_pt-br/tour/multiple-parameter-lists.md +++ b/_pt-br/tour/multiple-parameter-lists.md @@ -1,9 +1,6 @@ --- layout: tour title: Currying - -discourse: false - partof: scala-tour num: 9 @@ -18,7 +15,7 @@ Métodos podem definir múltiplas listas de parâmetros. Quando um método é ch Aqui um exemplo: -```tut +```scala mdoc object CurryTest extends App { def filter(xs: List[Int], p: Int => Boolean): List[Int] = diff --git a/_pt-br/tour/named-arguments.md b/_pt-br/tour/named-arguments.md index f4008c9ca9..0a32847873 100644 --- a/_pt-br/tour/named-arguments.md +++ b/_pt-br/tour/named-arguments.md @@ -1,9 +1,6 @@ --- layout: tour title: Parâmetros Nomeados - -discourse: false - partof: scala-tour num: 33 @@ -13,7 +10,7 @@ language: pt-br Ao chamar métodos e funções, você pode utilizar explicitamente o nome das variáveis nas chamadas, por exemplo: -```tut +```scala mdoc def imprimeNome(nome:String, sobrenome:String) = { println(nome + " " + sobrenome) } @@ -25,7 +22,7 @@ imprimeNome(sobrenome = "Smith",nome = "John") // Imprime "John Smith" Perceba que a ordem não importa quando você utiliza parâmetros nomeados nas chamadas de métodos e funções, desde que todos os parâmetros sejam declarados. Essa funcionalidade pode ser combinada com [parâmetros com valor padrão](default-parameter-values.html): -```tut +```scala mdoc:nest def imprimeNome(nome:String = "John", sobrenome:String = "Smith") = { println(nome + " " + sobrenome) } diff --git a/_pt-br/tour/nested-functions.md b/_pt-br/tour/nested-functions.md index 527856d37d..919d6f1253 100644 --- a/_pt-br/tour/nested-functions.md +++ b/_pt-br/tour/nested-functions.md @@ -1,9 +1,6 @@ --- layout: tour title: Funções Aninhadas - -discourse: false - partof: scala-tour num: 8 @@ -14,7 +11,7 @@ language: pt-br Em scala é possível aninhar definições de funções. O objeto a seguir fornece uma função `filter` para extrair valores de uma lista de inteiros que são abaixo de um determinado valor: -```tut +```scala mdoc object FilterTest extends App { def filter(xs: List[Int], threshold: Int) = { def process(ys: List[Int]): List[Int] = diff --git a/_pt-br/tour/operators.md b/_pt-br/tour/operators.md index b9d53f1ae8..627b968e73 100644 --- a/_pt-br/tour/operators.md +++ b/_pt-br/tour/operators.md @@ -1,20 +1,17 @@ --- layout: tour title: Operadores - -discourse: false - partof: scala-tour num: 29 -next-page: automatic-closures +next-page: annotations previous-page: type-inference language: pt-br --- Qualquer método que tenha um único parâmetro pode ser usado como um *operador infix* em Scala. Aqui está a definição da classe `MyBool` que inclui os métodos `add` e `or`: -```tut +```scala mdoc case class MyBool(x: Boolean) { def and(that: MyBool): MyBool = if (x) that else this def or(that: MyBool): MyBool = if (x) this else that @@ -24,7 +21,7 @@ case class MyBool(x: Boolean) { Agora é possível utilizar as funções `and` and `or` como operadores infix: -```tut +```scala mdoc def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) ``` @@ -33,7 +30,7 @@ Isso ajuda a tornar a definição de `xor` mais legível. Aqui está o código correspondente em uma sintaxe de linguagem de programação orientada a objetos mais tradicional: -```tut +```scala mdoc:nest def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = x.or(y).and(x.and(y).negate) ``` diff --git a/_pt-br/tour/package-objects.md b/_pt-br/tour/package-objects.md new file mode 100644 index 0000000000..11aa1f783e --- /dev/null +++ b/_pt-br/tour/package-objects.md @@ -0,0 +1,14 @@ +--- +layout: tour +title: Package Objects +language: pt-br +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- + +# Package objects + +(this section of the tour has not been translated yet. pull request +with translation welcome!) diff --git a/_pt-br/tour/packages-and-imports.md b/_pt-br/tour/packages-and-imports.md index abc74a9f2a..a88c8e9198 100644 --- a/_pt-br/tour/packages-and-imports.md +++ b/_pt-br/tour/packages-and-imports.md @@ -2,14 +2,11 @@ layout: tour title: Packages and Imports language: pt-br - -discourse: true - partof: scala-tour num: 35 previous-page: named-arguments -next-page: type-inference +next-page: package-objects --- # Packages and Imports diff --git a/_pt-br/tour/pattern-matching.md b/_pt-br/tour/pattern-matching.md index 9dcd9e4d3c..1c53b3cd02 100644 --- a/_pt-br/tour/pattern-matching.md +++ b/_pt-br/tour/pattern-matching.md @@ -1,9 +1,6 @@ --- layout: tour title: Correspondência de Padrões - -discourse: false - partof: scala-tour num: 11 @@ -18,7 +15,7 @@ _Nota de tradução: A palavra cujo o significado melhor corresponde a palavra ` Scala possui mecanismo de correspondência de padrão embutido. Isso permite realizar o match de qualquer tipo de dados com a política de primeiro match. Aqui um pequeno exemplo que mostrar como realizar o match de um número inteiro: -```tut +```scala mdoc object MatchTest1 extends App { def matchTest(x: Int): String = x match { case 1 => "um" @@ -33,7 +30,7 @@ O bloco com a declaração `case` define a função que mapeia inteiros para str Aqui um segundo exemplo no qual o match é realizado em valores de diferentes tipos: -```tut +```scala mdoc object MatchTest2 extends App { def matchTest(x: Any): Any = x match { case 1 => "um" diff --git a/_pt-br/tour/polymorphic-methods.md b/_pt-br/tour/polymorphic-methods.md index 359781e966..ed0dd535f8 100644 --- a/_pt-br/tour/polymorphic-methods.md +++ b/_pt-br/tour/polymorphic-methods.md @@ -1,9 +1,6 @@ --- layout: tour title: Métodos Polimórficos - -discourse: false - partof: scala-tour num: 27 @@ -17,7 +14,7 @@ Os métodos em Scala podem ser parametrizados com valores e tipos. Como no níve Por exemplo: -```tut +```scala mdoc def dup[T](x: T, n: Int): List[T] = { if (n == 0) Nil diff --git a/_pt-br/tour/regular-expression-patterns.md b/_pt-br/tour/regular-expression-patterns.md index 2fd77422e6..9009118fc0 100644 --- a/_pt-br/tour/regular-expression-patterns.md +++ b/_pt-br/tour/regular-expression-patterns.md @@ -1,9 +1,6 @@ --- layout: tour title: Padrões de Expressões Regulares - -discourse: false - partof: scala-tour num: 14 @@ -23,7 +20,7 @@ Elem(prefix:String, label:String, attrs:MetaData, scp:NamespaceBinding, children Em tais casos, Scala permite que padrões tenham o curinga `_*` na posição mais à direita para ter lugar para sequências arbitrariamente longas. O exemplo a seguir demonstra um padrão que faz o match de um prefixo de uma sequência e vincula o resto à variável `rest`. -```tut +```scala mdoc object RegExpTest1 extends App { def containsScala(x: String): Boolean = { val z: Seq[Char] = x diff --git a/_pt-br/tour/self-types.md b/_pt-br/tour/self-types.md index 432e8061f9..de2f95ef82 100644 --- a/_pt-br/tour/self-types.md +++ b/_pt-br/tour/self-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Auto Referências Explicitamente Tipadas - -discourse: false - partof: scala-tour num: 24 @@ -16,7 +13,7 @@ Ao desenvolver um software extensível, às vezes é útil declarar explicitamen Aqui está uma definição que descreve um grafo: -```tut +```scala mdoc abstract class Graph { type Edge type Node <: NodeIntf @@ -29,11 +26,11 @@ abstract class Graph { } ``` -Um grafo consiste em uma lista de nós e arestas onde o nó e o tipo de aresta são declarados como abstratos. O uso de [tipos abstratos](abstract-types.html) permite que a implementação da trait `Graph` forneça suas próprias classes concretas para nós e arestas. Além disso, existe um método `addNode` para adicionar novos nós a um grafo. Os nós são conectados usando o método `connectWith`. +Um grafo consiste em uma lista de nós e arestas onde o nó e o tipo de aresta são declarados como abstratos. O uso de [tipos abstratos](abstract-type-members.html) permite que a implementação da trait `Graph` forneça suas próprias classes concretas para nós e arestas. Além disso, existe um método `addNode` para adicionar novos nós a um grafo. Os nós são conectados usando o método `connectWith`. Uma possível implementação de `Graph` é ilustrada na classe a seguir: -```tut:fail +```scala mdoc:fail abstract class DirectedGraph extends Graph { type Edge <: EdgeImpl class EdgeImpl(origin: Node, dest: Node) { @@ -65,7 +62,7 @@ Em Scala é possível vincular uma classe a outro tipo (que será implementado n Aqui está o programa já corrigido: -```tut +```scala mdoc abstract class DirectedGraph extends Graph { type Edge <: EdgeImpl class EdgeImpl(origin: Node, dest: Node) { @@ -96,7 +93,7 @@ Nesta nova definição de classe `NodeImpl`, `this` tem o tipo `Node`. Como o ti Aqui está uma especialização concreta de `DirectedGraph` onde todos os membros da classe abstrata são definidos: -```tut +```scala mdoc class ConcreteDirectedGraph extends DirectedGraph { type Edge = EdgeImpl type Node = NodeImpl @@ -110,8 +107,8 @@ Observe que nesta classe, podemos instanciar `NodeImpl` porque agora sabemos que Aqui está um exemplo de uso da classe `ConcreteDirectedGraph`: -```tut -object GraphTest extends App { +```scala mdoc +def graphTest: Unit = { val g: Graph = new ConcreteDirectedGraph val n1 = g.addNode val n2 = g.addNode @@ -120,4 +117,4 @@ object GraphTest extends App { n2.connectWith(n3) n1.connectWith(n3) } -``` \ No newline at end of file +``` diff --git a/_pt-br/tour/singleton-objects.md b/_pt-br/tour/singleton-objects.md index a4f7daab0e..850af29abd 100644 --- a/_pt-br/tour/singleton-objects.md +++ b/_pt-br/tour/singleton-objects.md @@ -1,9 +1,6 @@ --- layout: tour title: Objetos Singleton - -discourse: false - partof: scala-tour num: 12 @@ -27,7 +24,7 @@ O método `sum` é disponível globalmente, e pode ser referenciado ou importado Objetos Singleton são um tipo de mescla e abreviação para definir uma classe de uso único, a qual não pode ser diretamente instanciada, e um membro `val` durante a definição do `object`. De fato, como `val`, objetos singleton podem ser definidos como membros de uma [trait](traits.html) ou [classe](classes.html), porém isso não é comum. -Um objeto singleton pode estender classes e traits. Já uma [classe clase](case-classes.html) sem [parâmetros com tipo](generic-classes.html) por padrão irá criar um objeto singleton como o mesmo nome e com uma [`Função*`](http://www.scala-lang.org/api/current/scala/Function1.html) trait implementada. +Um objeto singleton pode estender classes e traits. Já uma [case class](case-classes.html) sem [parâmetros com tipo](generic-classes.html) por padrão irá criar um objeto singleton como o mesmo nome e com uma [`Função*`](https://www.scala-lang.org/api/current/scala/Function1.html) trait implementada. ## Acompanhantes ## @@ -37,7 +34,7 @@ A maioria dos objetos singleton não estão sozinhos, mas sim associados com uma Se houver um objeto acompanhante para uma classe, ambos devem ser definidos no mesmo aquivo fonte. Por exemplo: -```tut +```scala mdoc class IntPair(val x: Int, val y: Int) object IntPair { @@ -71,4 +68,4 @@ Isso demonstra outra característica: no contexto `private`, as classes e seus a Por uma melhor interoperabilidade com Java, métodos, incluindo `var`s e `val`s, definidos diretamente em um objeto singleton também têm um método estático definido na classe acompanhante, chamado *encaminhadores estáticos*. Outros membros são acessíveis por meio de campos estáticos `X$.MODULE$` para o `object X`. -Se você mover tudo para um objeto acompanhante e descobrir que tudo o que resta é uma classe que você não deseja que seja instanciada, simplesmente exclua a classe. Encaminhadores estáticos ainda serão criados. \ No newline at end of file +Se você mover tudo para um objeto acompanhante e descobrir que tudo o que resta é uma classe que você não deseja que seja instanciada, simplesmente exclua a classe. Encaminhadores estáticos ainda serão criados. diff --git a/_pt-br/tour/tour-of-scala.md b/_pt-br/tour/tour-of-scala.md index 9c724dcf1f..970b47d0c0 100644 --- a/_pt-br/tour/tour-of-scala.md +++ b/_pt-br/tour/tour-of-scala.md @@ -1,9 +1,6 @@ --- layout: tour title: Introdução - -discourse: false - partof: scala-tour num: 1 @@ -28,7 +25,7 @@ Scala é equipada com um expressivo sistema de tipos que reforça estaticamente * [Classes genéricas](generic-classes.html) * [Anotações variáveis](variances.html) * [Limites de tipos superiores](upper-type-bounds.html) e [limites de tipos inferiores](lower-type-bounds.html), -* [Classes internas](inner-classes.html) e [tipos abstratos](abstract-types.html) como membros de um objeto +* [Classes internas](inner-classes.html) e [tipos abstratos](abstract-type-members.html) como membros de um objeto * [Tipos compostos](compound-types.html) * [Auto referências explicitamente tipadas](self-types.html) * [parâmetros implícitos](implicit-parameters.html) e [conversões implícitas](implicit-conversions.html) @@ -41,7 +38,6 @@ Um [mecanismo de inferência de tipo local](type-inference.html) se encarrega pa Na prática, o desenvolvimento de aplicações de um determinado domínio geralmente requer uma linguagem de domínio específico. Scala fornece uma combinação única de mecanismos de linguagem que facilitam a adição suave de novas construções de linguagem na forma de bibliotecas: * qualquer método pode ser utilizado como um [operador infix ou postfix](operators.html) -* [closures são construídas automaticamente dependendo do tipo esperado](automatic-closures.html) (tipo alvo). Uma utilização conjunta de ambos os recursos facilita a definição de novas instruções sem estender a sintaxe e sem usar meta-programação como macros. diff --git a/_pt-br/tour/traits.md b/_pt-br/tour/traits.md index a7a750961f..23bc17e04d 100644 --- a/_pt-br/tour/traits.md +++ b/_pt-br/tour/traits.md @@ -1,13 +1,10 @@ --- layout: tour title: Traits - -discourse: false - partof: scala-tour num: 4 -next-page: mixin-class-composition +next-page: tuples previous-page: classes language: pt-br --- @@ -15,7 +12,7 @@ language: pt-br Similar a interfaces em Java, traits são utilizadas para definir tipos de objetos apenas especificando as assinaturas dos métodos suportados. Como em Java 8, Scala permite que traits sejam parcialmente implementadas; ex. é possível definir uma implementação padrão para alguns métodos. Diferentemente de classes, traits não precisam ter construtores com parâmetros. Veja o exemplo a seguir: -```tut +```scala mdoc trait Similaridade { def eSemelhante(x: Any): Boolean def naoESemelhante(x: Any): Boolean = !eSemelhante(x) @@ -24,7 +21,7 @@ trait Similaridade { Tal trait consiste em dois métodos `eSemelhante` e `naoESemelhante`. Equanto `eSemelhante` não fornece um método com implementação concreta (que é semelhante ao abstract na linguagem Java), o método `naoESemelhante` define um implementação concreta. Consequentemente, classes que integram essa trait só precisam fornecer uma implementação concreta para o método `eSemelhante`. O comportamento para `naoESemelhante` é herdado diretamente da trait. Traits são tipicamente integradas a uma [classe](classes.html) (ou outras traits) utilizando a [composição mesclada de classes](mixin-class-composition.html): -```tut +```scala mdoc class Point(xc: Int, yc: Int) extends Similaridade { var x: Int = xc var y: Int = yc diff --git a/_pt-br/tour/tuples.md b/_pt-br/tour/tuples.md new file mode 100644 index 0000000000..4f149a48b7 --- /dev/null +++ b/_pt-br/tour/tuples.md @@ -0,0 +1,75 @@ +--- +layout: tour +title: Tuplas +partof: scala-tour + +num: 6 +next-page: mixin-class-composition +previous-page: traits +language: pt-br +--- + +Em Scala, uma tupla é um valor que contém um número fixo de elementos, cada um com tipos distintos e as tuplas são imutáveis. + +Tuplas são sobretudo úteis para retornar múltiplos valores de um método. + +Uma Tupla com dois elementos pode ser criada dessa forma: + +```scala mdoc +val ingrediente = ("Açucar" , 25) +``` + +Isto cria uma tupla contendo dois elementos um `String` e o outro `Int`. + +O tipo inferido de `ingrediente` é `(String, Int)`, que é uma forma abreviada para `Tuple2[String, Int]` . + +Para representar tuplas, Scala usa uma serie de classes: `Tuple2`, `Tuple3`, etc., até `Tuple22` . Cada classe tem tantos parâmetros de tipo quanto elementos. + +## Acessando os Elementos + +Uma maneira de acessar os elementos da tupla é pela sua respectiva posição. Os elementos individuais são nomeados `_1` , `_2` , e assim por diante. + +```scala mdoc +println(ingrediente._1) // Açucar +println(ingrediente._2) // 25 +``` + +## Correspondência de padrões em tuplas + +Uma tupla pode também ser desmembrada usando correspondência de padrões: + +```scala mdoc +val (nome, quantidade) = ingrediente +println(nome) // Açucar +println(quantidade) // 25 +``` + +Aqui o tipo inferido para `nome` é `String` e para `quantidade` o tipo inferido é `Int`. + +Outro exemplo de correspondência de padrões em uma tupla: + +```scala mdoc +val planetas = + List(("Mercúrio", 57.9), ("Vênus", 108.2), ("Terra", 149.6), + ("Marte", 227.9), ("Júpiter", 778.3)) +planetas.foreach{ + case ("Terra", distancia) => + println(s"Nosso planeta está a $distancia milhões de quilômetros do sol") + case _ => +} +``` + +Ou, um exemplo com `for` : + +```scala mdoc +val numPars = List((2, 5), (3, -7), (20, 56)) +for ((a, b) <- numPars) { + println(a * b) +} +``` + +## Tuplas e classes case + +Desenvolvedores às vezes acham dificil escolher entre tuplas e classes case. Classes case têm elementos nomeados, e esses podem melhorar a leitura de alguns tipos de códigos. No exemplo dos planetas acima, nós poderiamos definir uma `case class Planeta(nome: String, distancia: Double)` ao invés de usar tuplas. + + diff --git a/_pt-br/tour/type-inference.md b/_pt-br/tour/type-inference.md index a9f5de8f54..2a32f6d124 100644 --- a/_pt-br/tour/type-inference.md +++ b/_pt-br/tour/type-inference.md @@ -1,9 +1,6 @@ --- layout: tour title: Inferência de Tipo Local - -discourse: false - partof: scala-tour num: 28 @@ -16,7 +13,7 @@ Scala tem um mecanismo nativo de inferência de tipos que permite ao programador Por exemplo: -```tut +```scala mdoc object InferenceTest1 extends App { val x = 1 + 2 * 3 // o tipo de x é Int val y = x.toString() // o tipo de y é String @@ -28,7 +25,7 @@ Para métodos recursivos, o compilador não é capaz de inferir o tipo de retorn Exemplo de um método que não irá compilar por este motivo: -```tut:fail +```scala mdoc:fail object InferenceTest2 { def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1) } @@ -39,7 +36,7 @@ Também não é obrigatório especificar os tipos dos parâmetros quando [métod Por exemplo: ``` -case class MyPair[A, B](x: A, y: B); +case class MyPair[A, B](x: A, y: B) object InferenceTest3 extends App { def id[T](x: T) = x val p = MyPair(1, "scala") // type: MyPair[Int, String] @@ -57,7 +54,7 @@ val y: Int = id[Int](1) Em algumas situações, pode ser muito perigoso confiar no mecanismo de inferência de tipos de Scala como mostra o seguinte programa: -```tut:fail +```scala mdoc:fail object InferenceTest4 { var obj = null obj = new Object() diff --git a/_pt-br/tour/unified-types.md b/_pt-br/tour/unified-types.md index d0e240261b..0cb9bb86b6 100644 --- a/_pt-br/tour/unified-types.md +++ b/_pt-br/tour/unified-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Tipos Unificados - -discourse: false - partof: scala-tour num: 2 @@ -22,7 +19,7 @@ A superclass de todas as classes `scala.Any` tem duas subclasses diretas `scala. Observe que o diagrama acima mostra implicitamente as conversões entre as classes de valores. Este exemplo demonstra que números numbers, caracteres, valores booleanos, e funções são objetos como qualquer outro objeto: -```tut +```scala object TiposUnificados extends App { val set = new scala.collection.mutable.LinkedHashSet[Any] set += "Sou uma string" // adiciona uma string ao set diff --git a/_pt-br/tour/upper-type-bounds.md b/_pt-br/tour/upper-type-bounds.md index 478b729886..b90a421850 100644 --- a/_pt-br/tour/upper-type-bounds.md +++ b/_pt-br/tour/upper-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: Limitante Superior de Tipos - -discourse: false - partof: scala-tour num: 19 @@ -12,10 +9,10 @@ previous-page: variances language: pt-br --- -Em Scala, [parâmetros de tipos](generic-classes.html) e [tipos abstratos](abstract-types.html) podem ser restringidos por um limitante de tipo. Tal limitante de tipo limita os valores concretos de uma variável de tipo e possivelmente revela mais informações sobre os membros de determinados tipos. Um _limitante superiror de tipos_ `T <: A` declare que a variável tipo `T` refere-se a um subtipo do tipo `A`. +Em Scala, [parâmetros de tipos](generic-classes.html) e [tipos abstratos](abstract-type-members.html) podem ser restringidos por um limitante de tipo. Tal limitante de tipo limita os valores concretos de uma variável de tipo e possivelmente revela mais informações sobre os membros de determinados tipos. Um _limitante superiror de tipos_ `T <: A` declare que a variável tipo `T` refere-se a um subtipo do tipo `A`. Aqui um exemplo que demonstra um limitante superior de tipo para um parâmetro de tipo da classe `Cage`: -```tut +```scala mdoc abstract class Animal { def name: String } diff --git a/_pt-br/tour/variances.md b/_pt-br/tour/variances.md index 7f10c95004..5abd635810 100644 --- a/_pt-br/tour/variances.md +++ b/_pt-br/tour/variances.md @@ -1,9 +1,6 @@ --- layout: tour title: Variâncias - -discourse: false - partof: scala-tour num: 18 @@ -16,7 +13,7 @@ Scala suporta anotações de variância de parâmetros de tipo de [classes gené Na página sobre [classes genéricas](generic-classes.html) foi dado um exemplo de uma pilha de estado mutável. Explicamos que o tipo definido pela classe `Stack [T]` está sujeito a subtipos invariantes em relação ao parâmetro de tipo. Isso pode restringir a reutilização da abstração de classe. Derivamos agora uma implementação funcional (isto é, imutável) para pilhas que não tem esta restrição. Por favor, note que este é um exemplo avançado que combina o uso de [métodos polimórficos](polymorphic-methods.html), [limites de tipo inferiores](lower-type-bounds.html) e anotações de parâmetros de tipos covariantes em um estilo não trivial. Além disso, fazemos uso de [classes internas](inner-classes.html) para encadear os elementos da pilha sem links explícitos. -```tut +```scala mdoc class Stack[+T] { def push[S >: T](elem: S): Stack[S] = new Stack[S] { override def top: S = elem diff --git a/_ru/cheatsheets/index.md b/_ru/cheatsheets/index.md new file mode 100644 index 0000000000..6ef64ea87a --- /dev/null +++ b/_ru/cheatsheets/index.md @@ -0,0 +1,357 @@ +--- +layout: cheatsheet +title: Scala Cheatsheet + +partof: cheatsheet + +by: Dima Kotobotov +about: Эта шпаргалка создана благодаря Brendan O'Connor и предназначена для быстрого ознакомления с синтаксическими конструкциями Scala. Лицензия выдана Brendan O'Connor по лицензии CC-BY-SA 3.0. + +language: ru +--- + +###### Contributed by {{ page.by }} +{{ page.about }} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            переменные
            var x = 5переменная
            Хорошо
            val x = 5
            Плохо
            x=6            		константа
            var x: Double = 5явное указание типа
            функции
            Хорошо
            def f(x: Int) = { x*x }
            Плохо
            def f(x: Int) { x*x }            		объявление функции
            незаметная ошибка: без = это процедура с возвращаемым типом "Unit". Такое может ввести в заблуждение
            Хорошо
            def f(x: Any) = println(x)
            Плохо
            def f(x) = println(x)            		объявление функции
            синтаксическая ошибка: для каждого аргумента необходимо указывать его тип.
            type R = Doubleпсевдоним для типа
            def f(x: R) vs.

            def f(x: => R)            		вызов по значению
            вызов по имени (вычисление аргумента отложено)
            (x:R) => x*xанонимная функция
            (1 to 5).map(_*2) vs.
            (1 to 5).reduceLeft( _+_ )            		анонимная функция: подчеркивание указывает место подставляемого элемента.
            (1 to 5).map( x => x*x )анонимная функция: слева от => задается имя подставляемого элемента, чтоб его можно было переиспользовать
            Хорошо
            (1 to 5).map(2*)
            Плохо
            (1 to 5).map(*2)            		анонимная функция: запись с использованием инфиксного стиля. Ради четкого понимания лучше использовать явное указание позиции подставляемого элемента в стиле 2*_.
            (1 to 5).map { x => val y=x*2; println(y); y }анонимная функция: стиль блоковой передачи (фигурные скобки обозначают блок), возвращается последнее значение (y).
            (1 to 5) filter {_%2 == 0} map {_*2}анонимные функции: конвейерный стиль. В однострочных выражениях можно использовать простые скобки.
            def compose(g:R=>R, h:R=>R) = (x:R) => g(h(x))
            val f = compose({_*2}, {_-1})            		анонимные функции: передача блоков в качестве аргументов
            val zscore = (mean:R, sd:R) => (x:R) => (x-mean)/sdкаррирование, явный синтаксис.
            def zscore(mean:R, sd:R) = (x:R) => (x-mean)/sdкаррирование, явный синтаксис
            def zscore(mean:R, sd:R)(x:R) = (x-mean)/sdкаррирование, синтаксический сахар. Но если :
            val normer = zscore(7, 0.4) _следом использовать подчеркивание, то мы получим частично определенную функцию.
            def mapmake[T](g:T=>T)(seq: List[T]) = seq.map(g)обобщенный тип.
            5.+(3); 5 + 3
            (1 to 5) map (_*2)            		инфиксный стиль.
            def sum(args: Int*) = args.reduceLeft(_+_)функция с переменным числом аргументов.
            пакеты
            import scala.collection._импорт всех членов пакета.
            import scala.collection.Vector
            import scala.collection.{Vector, Sequence}            		выборочный импорт.
            import scala.collection.{Vector => Vec28}импорт с переименованием.
            import java.util.{Date => _, _}импортировать все из java.util кроме Date.
            package pkg в самом начале файла
            package pkg { ... }            		объявление пакета.
            структуры данных
            (1,2,3)кортеж размера 3. (Tuple3)
            var (x,y,z) = (1,2,3)разложение на отдельные элементы: кортеж раскладывается на элементы x, y и z используя сопоставление с образцом.
            Плохо
            var x,y,z = (1,2,3)            		незаметная ошибка: каждой переменной будет присвоено по кортежу.
            var xs = List(1,2,3)список (неизменяемый).
            xs(2)получение элемента по индексу в скобках. (примеры)
            1 :: List(2,3)добавление к списку.
            1 to 5 тоже что и 1 until 6
            1 to 10 by 2            		задание диапазона (синтаксический сахар).
            () (пустые скобки)одиночный член типа Unit (тоже что и void в C/Java).
            управляющие структуры
            if (check) happy else sadусловие.
            if (check) happy +
            тоже что и
            + if (check) happy else ()            		синтаксический сахар (ветка else добавляется автоматически).
            while (x < 5) { println(x); x += 1}цикл с условием в блоке while .
            do { println(x); x += 1} while (x < 5)цикл с условием и обязательным исполнением в блоке do.
            import scala.util.control.Breaks._
+breakable {
+  for (x <- xs) {
+    if (Math.random < 0.1)
+      break
+  }
+}
            		выход из цикла с использованием break. (примеры)
            for (x <- xs if x%2 == 0) yield x*10 +
            тоже что и
            + xs.filter(_%2 == 0).map(_*10)            		for-выражение: выражается набором с filter/map
            for ((x,y) <- xs zip ys) yield x*y +
            тоже что и
            + (xs zip ys) map { case (x,y) => x*y }            		for-выражение: извлечение элементов с последующим вычислением
            for (x <- xs; y <- ys) yield x*y +
            тоже что и
            + xs flatMap {x => ys map {y => x*y}}            		for-выражение: перекрестное объединение
            for (x <- xs; y <- ys) {
+  println("%d/%d = %.1f".format(x, y, x/y.toFloat))
+}
            		for-выражение: императивно
            sprintf-style
            for (i <- 1 to 5) {
+  println(i)
+}
            		for-выражение: обход диапазона (от 1 до 5) включая его верхнюю границу 
            for (i <- 1 until 5) {
+  println(i)
+}
            		for-выражение: обход диапазона (от 1 до 5) не включая его верхнюю границу
            сопоставление с примером
            Хорошо
            (xs zip ys) map { case (x,y) => x*y }
            Плохо
            (xs zip ys) map( (x,y) => x*y )            		используйте ключевое слово case при передачи аргументов в функцию для запуска механизма сопоставления с примером.
            Плохо
            + 
            val v42 = 42
+Some(3) match {
+  case Some(v42) => println("42")
+  case _ => println("Not 42")
+}
            		“v42” интерпретировано как имя для новой константы любого типа, поэтому напечатано “42”.
            Хорошо
            + 
            val v42 = 42
+Some(3) match {
+  case Some(`v42`) => println("42")
+  case _ => println("Not 42")
+}
            		”`v42`” с обратными кавычками интерпретируется как указание на значение существующей константы v42, напечатано “Not 42”.
            Хорошо
            + 
            val UppercaseVal = 42
+Some(3) match {
+  case Some(UppercaseVal) => println("42")
+  case _ => println("Not 42")
+}
            		UppercaseVal однако константы, имена которых начинаются с заглавной буквы, сопоставляются по значению. Поэтому при сопоставлении UppercaseVal с 3, выводится “Not 42”.
            Работа с объектами
            class C(x: R)параметр конструктора - x доступен только внутри тела класса
            class C(val x: R)
            var c = new C(4)
            c.x            		параметр конструктора - доступен публично, автоматически
            class C(var x: R) {
+  assert(x > 0, "positive please")
+  var y = x
+  val readonly = 5
+  private var secret = 1
+  def this() = this(42)
+}
            		конструктор является телом класса
            объявление публичного члена класса
            объявление члена с гетером но без сеттера
            объявление приватного члена
            объявление альтернативного конструктора без аргумента
            new{ ... }анонимный класс
            abstract class D { ... }объявление абстрактного класса (не создаваемого, только наследуемого)
            class C extends D { ... }объявление класса с наследованием.
            class D(var x: R)
            class C(x: R) extends D(x)            		наследование класса с конструированием параметров.
            object O extends D { ... }объявление объекта одиночки (Singleton) на основе другого класса.
            trait T { ... }
            class C extends T { ... }
            class C extends D with T { ... }            		трейты
            описывают какие функции и данные должны быть в классе, возможно также указание конкретной (или общей) реализации а также указание значений переменных. + у трейта нет конструктора. их можно смешивать.
            trait T1; trait T2
            class C extends T1 with T2
            class C extends D with T1 with T2            		множественные трейты.
            class C extends D { override def f = ...}при наследовании и создании методов с одинаковыми именами необходимо указывать override.
            new java.io.File("f")создание объекта.
            Плохо
            new List[Int]
            Хорошо
            List(1,2,3)            		ошибка: List - это абстрактный класс
            по соглашению используется объект с именем как у абстрактного класса, который уже создает конкретные экземпляры
            classOf[String]описание класса.
            x.isInstanceOf[String]проверка типа (при исполнении)
            x.asInstanceOf[String]приведение типа (при исполнении)
            x: Stringприписывание типа (во время компиляции)
            diff --git a/_ru/getting-started/install-scala.md b/_ru/getting-started/install-scala.md new file mode 100644 index 0000000000..44154d2dfb --- /dev/null +++ b/_ru/getting-started/install-scala.md @@ -0,0 +1,244 @@ +--- +layout: singlepage-overview +title: Начало работы +partof: getting-started +language: ru +includeTOC: true + +newcomer_resources: + - title: Вы пришли с Java? + description: Что нужно знать, чтобы ускорить работу со Scala после первоначального запуска. + icon: "fa fa-coffee" + link: /tutorials/scala-for-java-programmers.html + - title: Scala в браузере + description: > + Чтобы сразу начать экспериментировать со Scala, используйте "Scastie" в своем браузере. + icon: "fa fa-cloud" + link: https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw +--- + +Приведенные ниже инструкции охватывают как Scala 3, так и Scala 2. + +
            +{% altDetails need-help-info-box 'Нужна помощь?' class=help-info %} +*Если у вас возникли проблемы с настройкой Scala, смело обращайтесь за помощью в канал `#scala-users` +[нашего Discord](https://discord.com/invite/scala).* +{% endaltDetails %} +
            + +## Ресурсы для новичков + +{% include inner-documentation-sections.html links=page.newcomer_resources %} + +## Установка Scala на компьютер + +Установка Scala означает установку различных инструментов командной строки, +таких как компилятор Scala и инструменты сборки. +Мы рекомендуем использовать инструмент установки "Coursier", +который автоматически устанавливает все зависимости. +Также возможно установить по отдельности каждый инструмент вручную. + +### Использование Scala Installer (рекомендованный путь) + +Установщик Scala — это инструмент [Coursier](https://get-coursier.io/docs/cli-overview), +основная команда которого называется `cs`. +Он гарантирует, что в системе установлены JVM и стандартные инструменты Scala. +Установите его в своей системе, следуя следующим инструкциям. + + +{% tabs install-cs-setup-tabs class=platform-os-options %} + + +{% tab macOS for=install-cs-setup-tabs %} +Запустите в терминале следующую команду, следуя инструкциям на экране: +{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-brew %} +{% altDetails cs-setup-macos-nobrew "В качестве альтернативы, если вы не используете Homebrew:" %} + {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-x86-64 %} +{% endaltDetails %} +{% endtab %} + + + +{% tab Linux for=install-cs-setup-tabs %} + Запустите в терминале следующую команду, следуя инструкциям на экране: + {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.linux-x86-64 %} +{% endtab %} + + + +{% tab Windows for=install-cs-setup-tabs %} + Загрузите и запустите [установщик Scala для Windows]({{site.data.setup-scala.windows-link}}) + на базе Coursier и следуйте инструкциям на экране. +{% endtab %} + + + +{% tab Иное for=install-cs-setup-tabs defaultTab %} + + Следуйте документации Coursier о том, + [как установить и запустить `cs setup`](https://get-coursier.io/docs/cli-installation). +{% endtab %} + + +{% endtabs %} + + + +{% altDetails testing-your-setup 'Тестирование установки' %} +Проверьте корректность установки с помощью команды `scala -version`, которая должна вывести: +```bash +$ scala -version +Scala code runner version: 1.4.3 +Scala version (default): {{site.scala-3-version}} +``` +Если сообщение не выдано, возможно, необходимо перезайти в терминал (или перезагрузиться), +чтобы изменения вступили в силу. +{% endaltDetails %} + + +Наряду с JVM `cs setup` также устанавливает полезные инструменты командной строки: + +| Commands | Description | +|---------------|--------------------------------------------------------------------------------------| +| `scalac` | компилятор Scala | +| `scala` | Scala REPL и средство запуска сценариев | +| `scala-cli` | [Scala CLI](https://scala-cli.virtuslab.org), интерактивный инструментарий для Scala | +| `sbt`, `sbtn` | Инструмент сборки [sbt](https://www.scala-sbt.org/) | +| `amm` | [Ammonite](https://ammonite.io/) — улучшенный REPL | +| `scalafmt` | [Scalafmt](https://scalameta.org/scalafmt/) - средство форматирования кода Scala | + +Дополнительная информация о cs [доступна по ссылке](https://get-coursier.io/docs/cli-overview). + +> `cs setup` по умолчанию устанавливает компилятор и исполняющую программу Scala 3 +> (команды `scalac` и `scala` соответственно). Независимо от того, собираетесь ли вы использовать Scala 2 или 3, +> обычно это не проблема, потому что в большинстве проектов используется инструмент сборки, +> который будет использовать правильную версию Scala независимо от того, какая версия установлена "глобально". +> Тем не менее, вы всегда можете запустить конкретную версию Scala, используя +> ``` +> $ cs launch scala:{{ site.scala-version }} +> $ cs launch scalac:{{ site.scala-version }} +> ``` +> Если предпочтительно, чтобы по умолчанию запускалась Scala 2, вы можете принудительно установить эту версию с помощью: +> ``` +> $ cs install scala:{{ site.scala-version }} scalac:{{ site.scala-version }} +> ``` + +### ...или вручную + +Для компиляции, запуска, тестирования и упаковки проекта Scala нужны только два инструмента: +Java 8 или 11 и sbt. +Чтобы установить их вручную: + +1. если не установлена Java 8 или 11, загрузите Java из + [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html), + или [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). + Подробную информацию о совместимости Scala/Java см. в разделе [Совместимость с JDK](/overviews/jdk-compatibility/overview.html). +1. установить [sbt](https://www.scala-sbt.org/download.html) + +## Создание проекта "Hello World" с помощью sbt + +В следующих разделах объясняется как создавать проект Scala после того, как установлен sbt. + +Для создания проекта можно использовать командную строку или IDE. +Мы рекомендуем командную строку, если вы с ней знакомы. + +### Использование командной строки + +sbt — это инструмент сборки для Scala. sbt компилирует, запускает и тестирует Scala код +(он также может публиковать библиотеки и выполнять множество других задач). + +Чтобы создать новый проект Scala с помощью sbt: + +1. `cd` в пустую папку. +1. Запустите команду `sbt new scala/scala3.g8`, чтобы создать проект на Scala 3, + или `sbt new scala/hello-world.g8` для создания проекта на Scala 2. + Она извлекает шаблон проекта из GitHub. + Эта команда также создает папку `target`, которую вы можете игнорировать. +1. При появлении запроса назовите приложение `hello-world`. + Это создаст проект под названием "hello-world". +1. Будет сгенерировано следующее: + +``` +- hello-world + - project (sbt использует эту папку для собственных файлов) + - build.properties + - build.sbt (файл определения сборки sbt) + - src + - main + - scala (здесь весь Scala code) + - Main.scala (точка входа в программу) <-- это все, что сейчас нужно +``` + +Дополнительную документацию по sbt можно найти в [Scala Book](/scala3/book/tools-sbt.html) +(см. [здесь](/overviews/scala-book/scala-build-tool-sbt.html) для версии Scala 2) +и в официальной [документации sbt](https://www.scala-sbt.org/1.x/docs/index.html). + +### С интегрированной средой разработки (IDE) + +Вы можете пропустить оставшуюся часть страницы и сразу перейти к [созданию проекта Scala с помощью IntelliJ и sbt](/ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html). + + +## Открыть проект hello-world + +Давайте используем IDE, чтобы открыть проект. Самые популярные из них — IntelliJ и VSCode. +Оба предлагают обширные возможности, но вы по-прежнему можете использовать [множество других редакторов](https://scalameta.org/metals/docs/editors/overview.html). + + +### Использование IntelliJ + +1. Загрузите и установите [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/) +1. Установите Scala plugin, следуя [инструкциям по установке плагинов IntelliJ](https://www.jetbrains.com/help/idea/managing-plugins.html) +1. Откройте файл `build.sbt`, затем выберете *Open as a project* + +### Использование VSCode с metals + +1. Загрузите [VSCode](https://code.visualstudio.com/Download) +1. Установите расширение Metals из [Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals) +1. Затем откройте каталог, содержащий файл `build.sbt` (это должен быть каталог `hello-world`, если вы следовали предыдущим инструкциям). Когда будет предложено, выберите *Import build*. + +> [Metals](https://scalameta.org/metals) — это “языковой сервер Scala”, обеспечивающий поддержку написания кода Scala в VS Code и других редакторах, +> таких как [Atom, Sublime Text и других](https://scalameta.org/metals/docs/editors/overview.html), использующих Language Server Protocol. +> +> Под капотом Metals взаимодействует со средством сборки с помощью +> [Build Server Protocol (BSP)](https://build-server-protocol.github.io/). +> Подробнее о том, как работает Metals, см. [“Написание Scala в VS Code, Vim, Emacs, Atom и Sublime Text с помощью Metals”](https://www.scala-lang.org/2019/04/16/metals.html). + +### Знакомство с исходным кодом + +Просмотрите эти два файла в своей IDE: + +- _build.sbt_ +- _src/main/scala/Main.scala_ + +При запуске проекта на следующем шаге, конфигурация в _build.sbt_ будет использована для запуска кода в _src/main/scala/Main.scala_. + +## Запуск Hello World + +Код в _Main.scala_ можно запускать из IDE, если удобно. + +Но вы также можете запустить приложение из терминала, выполнив следующие действия: + +1. `cd` в `hello-world`. +1. Запустить `sbt`. Эта команда открывает sbt-консоль. +1. В консоле введите `~run`. `~` является необязательным, но заставляет sbt повторно запускаться при каждом сохранении файла, + обеспечивая быстрый цикл редактирования/запуска/отладки. sbt также создаст директорию `target`, которую пока можно игнорировать. + +После окончания экспериментирования с проектом, нажмите `[Enter]`, чтобы прервать команду `run`. +Затем введите `exit` или нажмите `[Ctrl+D]`, чтобы выйти из sbt и вернуться в командную строку. + +## Следующие шаги + +После того как пройдете приведенные выше обучающие материалы, подумайте о том, чтобы проверить: + +* [The Scala Book](/scala3/book/introduction.html) (см. версию для Scala 2 [здесь](/overviews/scala-book/introduction.html)), которая содержит набор коротких уроков, знакомящих с основными функциями Scala. +* [The Tour of Scala](/ru/tour/tour-of-scala.html) для краткого ознакомления с функциями Scala. +* [Обучающие ресурсы](/online-courses.html), которые включают в себя интерактивные онлайн-учебники и курсы. +* [Наш список некоторых популярных книг по Scala](/books.html). +* [Руководство по миграции](/scala3/guides/migration/compatibility-intro.html) поможет перенести существующую кодовую базу Scala 2 на Scala 3. + +## Получение помощи + +Существует множество рассылок и real-time чатов на случай, если вы хотите быстро связаться с другими пользователями Scala. +Посетите страницу [нашего сообщества](https://scala-lang.org/community/), чтобы ознакомиться со списком этих ресурсов и узнать, куда можно обратиться за помощью. diff --git a/_ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md b/_ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md new file mode 100644 index 0000000000..dd13a44443 --- /dev/null +++ b/_ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md @@ -0,0 +1,104 @@ +--- +title: Создание проекта Scala с IntelliJ и sbt +layout: singlepage-overview +partof: building-a-scala-project-with-intellij-and-sbt +language: ru +disqus: true +previous-page: /ru/getting-started/intellij-track/getting-started-with-scala-in-intellij +next-page: /ru/testing-scala-in-intellij-with-scalatest +--- + +В этом руководстве мы увидим, как создать проект Scala с помощью [sbt](https://www.scala-sbt.org/1.x/docs/index.html). +sbt — популярный инструмент для компиляции, запуска и тестирования проектов Scala любой сложности. +Использование инструмента сборки, такого как sbt (или Maven/Gradle), становится необходимым, +если вы создаете проекты с зависимостями или несколькими файлами кода. +Мы предполагаем, что вы прочитали [первое руководство](getting-started-with-scala-in-intellij.html). + +## Создание проекта +В этом разделе мы покажем вам, как создать проект в IntelliJ. +Однако, если вы знакомы с командной строкой, мы рекомендуем вам попробовать +[Начало работы со Scala и sbt в командной строке]({{site.baseurl}}/ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html) +а затем вернуться к разделу "Написание Scala кода". + +1. Если вы не создавали проект из командной строки, откройте IntelliJ и выберите "Create New Project" + * На левой панели выберите Scala, а на правой панели - sbt + * Нажмите **Next** + * Назовите проект "SbtExampleProject" +1. Если вы уже создали проект в командной строке, откройте IntelliJ, выберите *Import Project* и откройте `build.sbt` файл вашего проекта +1. Убедитесь, что ваша **JDK version** - это 1.8, а **sbt version** не ниже 0.13.13 +1. Выберите **Use auto-import**, чтобы доступные зависимости загружались автоматически. +1. Выберите **Finish** + +## Разбор структуры каталогов +sbt создает множество каталогов, которые могут быть полезны, когда вы начнете создавать более сложные проекты. +На данный момент вы можете игнорировать большинство из них, но вот объяснение, для чего все это: + +``` +- .idea (файлы IntelliJ) +- project (плагины и дополнительные настройки sbt) +- src (исходные файлы) + - main (код приложения) + - java (исходные файлы Java) + - scala (исходные файлы Scala) <-- это все, что вам сейчас нужно + - scala-2.12 (файлы, специфичные для Scala 2.12) + - test (модульные тесты) +- target (сгенерированные файлы) +- build.sbt (файл определения сборки для sbt) +``` + + +## Написание Scala-кода +1. На панели слева **Project**, разверните `SbtExampleProject` => `src` => `main` +1. Щелкните правой кнопкой мыши на `scala` и выберете **New** => **Package** +1. Назовите пакет `example` и нажмите **OK** (или просто нажмите клавишу **Enter** или **Return**). +1. Щелкните правой кнопкой мыши на пакете `example` и выберите **New** => **Scala class** +(если вы не видите эту опцию, щелкните правой кнопкой мыши на `SbtExampleProject`, кликните на **Add Frameworks Support**, выберете **Scala** и продолжите) +1. Назовите класс `Main` и измените **Kind** на `Object`. +1. Вставьте следующий код: + +``` +@main def run() = + val ages = Seq(42, 75, 29, 64) + println(s"The oldest person is ${ages.max}") +``` + +Примечание: IntelliJ имеет собственную реализацию компилятора Scala, +и иногда ваш код верен, даже если IntelliJ указывает обратное. +Вы всегда можете проверить, может ли sbt запустить ваш проект в командной строке. + +## Запуск проекта +1. В меню **Run**, выберите **Edit configurations** +1. Нажмите кнопку **+** и выберите **sbt Task**. +1. Назовите задачу `Run the program`. +1. В поле **Tasks**, введите `~run`. `~` заставляет sbt перекомпилировать +и повторно запускать проект при каждом сохранении изменений в файле проекта. +1. Нажмите **OK**. +1. В меню **Run** нажмите **Run 'Run the program'**. +1. В коде измените `75` на `61` и посмотрите на обновленные результаты в консоли. + +## Добавление зависимости +Немного меняя тему, давайте посмотрим, как использовать опубликованные библиотеки +для добавления дополнительных функций в наши приложения. +1. Откройте `build.sbt` и добавьте следующую строку: + +``` +libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2" +``` +Здесь `libraryDependencies` представляет набор зависимостей, +и с помощью `+=` мы добавляем зависимость [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) +к набору зависимостей, которые sbt будет загружать при запуске. +Теперь в любом файле Scala можно импортировать классы, объекты и т.д. из `scala-parser-combinators` с помощью обычного импорта. + +Вы можете найти больше опубликованных библиотек на [Scaladex](https://index.scala-lang.org/), каталоге библиотек Scala, +где вы также можете скопировать указанную выше информацию о зависимостях для вставки в свой файл `build.sbt`. + +## Следующие шаги + +Перейдите к следующему руководству из серии _getting started with IntelliJ_ и узнайте, как [тестировать Scala в IntelliJ с помощью ScalaTest](testing-scala-in-intellij-with-scalatest.html). + +**или** + +* [The Scala Book](/scala3/book/introduction.html), содержащая набор коротких уроков, знакомящих с основными функциями Scala. +* [Тур по Scala](/ru/tour/tour-of-scala.html) для краткого ознакомления с возможностями Scala. +- Продолжайте изучать Scala в интерактивном режиме на + [Scala Exercises](https://www.scala-exercises.org/scala_tutorial). diff --git a/_ru/getting-started/intellij-track/getting-started-with-scala-in-intellij.md b/_ru/getting-started/intellij-track/getting-started-with-scala-in-intellij.md new file mode 100644 index 0000000000..65337bc058 --- /dev/null +++ b/_ru/getting-started/intellij-track/getting-started-with-scala-in-intellij.md @@ -0,0 +1,124 @@ +--- +title: Начало работы со Scala в IntelliJ +layout: singlepage-overview +partof: getting-started-with-scala-in-intellij +language: ru +disqus: true +next-page: /ru/building-a-scala-project-with-intellij-and-sbt +--- + +В этом руководстве мы увидим, как создать минимальный проект Scala с помощью IntelliJ IDE со Scala плагином. +В этом руководстве IntelliJ загрузит Scala за вас. + +## Установка + +1. Убедитесь, что у вас установлена Java 8 JDK (также известная как 1.8) + * Запустите `javac -version` в командной строке и убедитесь, что выдается + `javac 1.8.___` + * Если у вас нет версии 1.8 или выше, [установите JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) +1. Затем загрузите и установите [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/) +1. Затем, после запуска IntelliJ, вы можете загрузить и установить Scala плагин, следуя + [инструкции по установке плагинов IntelliJ](https://www.jetbrains.com/help/idea/installing-updating-and-uninstalling-repository-plugins.html) (найдите "Scala" в меню плагинов). + +Когда мы создадим проект, то установим последнюю версию Scala. +Примечание: Если вы хотите открыть существующий проект Scala, вы можете нажать **Open** +при запуске IntelliJ. + +## Создание проекта + +1. Откройте IntelliJ и нажмите **File** => **New** => **Project** +1. На левой панели выберите Scala. На правой панели - IDEA. +1. Назовите проект **HelloWorld** +1. Если вы впервые создаете Scala проект с помощью IntelliJ, вам необходимо установить Scala SDK. + Справа от поля Scala SDK нажмите кнопку **Create**. +1. Выберите последний номер версии (например, {{ site.scala-version }}) и нажмите **Download**. +Это может занять несколько минут, но тот же пакет SDK могут использовать последующие проекты. +1. Когда SDK будет установлен и вы вернетесь в окно "New Project", нажмите **Finish**. + +## Написание кода + +1. На левой панели **Project** щелкните правой кнопкой мыши на папке `src` и выберите +**New** => **Scala class**. Если вы не видите **Scala class**, щелкните правой кнопкой мыши на **HelloWorld** +и выберите **Add Framework Support...**, затем - **Scala** и продолжить. +Если вы видите ошибку **Error: library is not specified**, вы можете либо нажать кнопку загрузки, +либо выбрать путь к библиотеке вручную. Если вы видите только **Scala Worksheet** попробуйте развернуть папку `src` +и её подпапку `main`, а затем правой кнопкой мыши на папке `scala`. +1. Назовите класс `Hello` и измените **Kind** на `object`. +1. Вставьте следующий код: + +{% tabs hello-world-entry-point class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-entry-point %} + +``` +object Hello extends App { + println("Hello, World!") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=hello-world-entry-point %} + +``` +@main def hello(): Unit = + println("Hello, World!") +``` + +В Scala 3 вы можете удалить объект `Hello` и вместо него определить метод верхнего уровня `hello` +с аннотацией `@main`. + +{% endtab %} + +{% endtabs %} + +## Запуск + +{% tabs hello-world-run class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-run %} + +* Щелкните правой кнопкой мыши на `Hello` в своем коде и выберите **Run 'Hello'**. +* Готово! + +{% endtab %} + +{% tab 'Scala 3' for=hello-world-run %} + +* Щелкните правой кнопкой мыши на `hello` в своем коде и выберите **Run 'hello'**. +* Готово! + +{% endtab %} + +{% endtabs %} + +## Эксперименты со Скалой + +Хороший способ попробовать примеры кода — использовать Scala Worksheets. + +1. В левой панели проекта щелкните правой кнопкой мыши на +`src` и выберите **New** => **Scala Worksheet**. +2. Назовите новый Scala worksheet "Mathematician". +3. Введите следующий код в worksheet: + +{% tabs square %} +{% tab 'Scala 2 and 3' for=square %} +``` +def square(x: Int): Int = x * x + +square(2) +``` +{% endtab %} +{% endtabs %} + +После запуска кода вы заметите, что результаты его выполнения выводятся на правой панели. +Если вы не видите правую панель, щелкните правой кнопкой мыши на вашем Scala worksheet на панели "Проект" +и выберите "Evaluate Worksheet". + +## Следующие шаги + +Теперь вы знаете, как создать простой Scala проект, который можно использовать для изучения языка. +В следующем уроке мы представим важный инструмент сборки под названием sbt, +который можно использовать для простых проектов и рабочих приложений. + +Далее: [Создание проекта Scala с IntelliJ и sbt](building-a-scala-project-with-intellij-and-sbt.html) diff --git a/_ru/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md b/_ru/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md new file mode 100644 index 0000000000..7a2ffef8fe --- /dev/null +++ b/_ru/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md @@ -0,0 +1,73 @@ +--- +title: Тестирование Scala в IntelliJ с помощью ScalaTest +layout: singlepage-overview +partof: testing-scala-in-intellij-with-scalatest +language: ru +disqus: true +previous-page: /ru/building-a-scala-project-with-intellij-and-sbt +--- + +Для Scala существует множество библиотек и методологий тестирования, +но в этом руководстве мы продемонстрируем один популярный вариант из фреймворка ScalaTest +под названием [AnyFunSuite](https://www.scalatest.org/getting_started_with_fun_suite). + +Это предполагает, что вы знаете, [как создать проект в IntelliJ](building-a-scala-project-with-intellij-and-sbt.html). + +## Настройка +1. Создайте sbt проект в IntelliJ. +1. Добавьте зависимость ScalaTest: + 1. Добавьте зависимость ScalaTest в свой файл `build.sbt`: + ``` + libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test + ``` + 1. Если вы получили уведомление "build.sbt was changed", выберите **auto-import**. + 1. Эти два действия заставят `sbt` подгрузить библиотеки ScalaTest. + 1. Дождитесь окончания синхронизации `sbt`; в противном случае, `AnyFunSuite` и `test()` не будет распознаны. +1. На панели проекта слева разверните `src` => `main`. +1. Щелкните правой кнопкой мыши на `scala` и выберите **New** => **Scala class**. +1. Назовите новый класс `CubeCalculator`, измените **Kind** на `object`, или дважды щелкните на `object`. +1. Вставьте следующий код: + ``` + object CubeCalculator: + def cube(x: Int) = + x * x * x + ``` + +## Создание теста +1. На панели проекта слева разверните `src` => `test`. +1. Щелкните правой кнопкой мыши на `scala` и выберите **New** => **Scala class**. +1. Назовите новый класс `CubeCalculatorTest` и нажмите **Enter** или дважды щелкните на `class`. +1. Вставьте следующий код: + ``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite: + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } + ``` +1. В исходном коде щелкните правой кнопкой мыши на `CubeCalculatorTest` и выберите + **Run 'CubeCalculatorTest'**. + +## Разбор кода + +Давайте разберем код построчно: + +* `class CubeCalculatorTest` означает, что мы тестируем `CubeCalculator` +* `extends AnyFunSuite` позволяет нам использовать функциональность класса AnyFunSuite из ScalaTest, + такую как функция `test` +* `test` это функция из библиотеки FunSuite, которая собирает результаты проверок в теле функции. +* `"CubeCalculator.cube"` - это имя для теста. Вы можете называть тест как угодно, но по соглашению используется имя — "ClassName.methodName". +* `assert` принимает логическое условие и определяет, пройден тест или нет. +* `CubeCalculator.cube(3) === 27` проверяет, действительно ли вывод функции `cube` равен 27. + `===` является частью ScalaTest и предоставляет понятные сообщения об ошибках. + +## Добавление еще одного теста +1. Добавьте еще один оператор `assert` после первого, который проверяет 0 в кубе. +1. Перезапустите тест `CubeCalculatorTest`, кликнув правой кнопкой мыши и выбрав + **Run 'CubeCalculatorTest'**. + +## Заключение +Вы видели один из способов тестирования Scala кода. +Узнать больше о AnyFunSuite от ScalaTest можно на [официальном сайте](https://www.scalatest.org/getting_started_with_fun_suite). +Вы также можете использовать другие тестовые фреймворки, такие, как [ScalaCheck](https://www.scalacheck.org/) и [Specs2](https://etorreborre.github.io/specs2/). diff --git a/_ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md b/_ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md new file mode 100644 index 0000000000..f404e3daf8 --- /dev/null +++ b/_ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md @@ -0,0 +1,111 @@ +--- +title: Начало работы со Scala и sbt в командной строке +layout: singlepage-overview +partof: getting-started-with-scala-and-sbt-on-the-command-line +language: ru +disqus: true +next-page: /ru/testing-scala-with-sbt-on-the-command-line +--- + +В этом руководстве вы увидите, как создавать проекты Scala из шаблона. +Это можно использовать как отправную точку для своих собственных проектов. +Мы будем использовать [sbt](https://www.scala-sbt.org/1.x/docs/index.html), де-факто инструмент сборки для Scala. +sbt компилирует, запускает и тестирует ваши проекты среди других связанных задач. +Мы предполагаем, что вы знаете, как пользоваться терминалом. + +## Установка +1. Убедитесь, что у вас установлена Java 8 JDK (также известная как 1.8) + * Запустите `javac -version` в командной строке и убедитесь, что выдается + `javac 1.8.___` + * Если у вас нет версии 1.8 или выше, [установите JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) +1. Установите sbt + * [Mac](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html) + * [Windows](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html) + * [Linux](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html) + +## Создание проекта + +{% tabs sbt-welcome-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=sbt-welcome-1 %} + +1. `cd` в пустую папку. +1. Запустите следующую команду `sbt new scala/hello-world.g8`. + Она извлекает шаблон 'hello-world' из GitHub. + Она также создаст папку `target`, которую пока можно игнорировать. +1. При появлении запроса назовите приложение `hello-world`. Это создаст проект под названием "hello-world". +1. Давайте взглянем на то, что только что было сгенерировано: + +{% endtab %} +{% tab 'Scala 3' for=sbt-welcome-1 %} + +1. `cd` в пустую папку. +1. Запустите следующую команду `sbt new scala/scala3.g8`. + Она извлекает шаблон 'scala3' из GitHub. + Она также создаст папку `target`, которую пока можно игнорировать. +1. При появлении запроса назовите приложение `hello-world`. Это создаст проект под названием "hello-world". +1. Давайте взглянем на то, что только что было сгенерировано: + +{% endtab %} +{% endtabs %} + + +``` +- hello-world + - project (sbt использует эту папку для установки и настройки плагинов и зависимостей) + - build.properties + - src + - main + - scala (весь Scala код находится в этой папке) + - Main.scala (точка входа в программу) <-- это все, что вам сейчас нужно + - build.sbt (файл определения сборки для sbt) +``` + +После того как вы создадите свой проект, sbt создаст дополнительные каталоги `target` для сгенерированных файлов. +Вы можете игнорировать их. + +## Запуск проекта +1. `cd` в `hello-world`. +1. Запустите `sbt`. Эта команда запустит sbt console. +1. Запустите `~run`. `~` опциональна и заставляет sbt перекомпилировать + и повторно запускать проект при каждом сохранении изменений в файле проекта + для быстрого цикла редактирование/запуск/отладка. + sbt также сгенерит директорию `target`, которую можно игнорировать. + +## Доработка кода +1. Откройте файл `src/main/scala/Main.scala` в вашем любимом текстовом редакторе. +1. Измените "Hello, World!" на "Hello, New York!" +1. Если вы не остановили команду sbt, то должны увидеть "Hello, New York!", напечатанным в консоли. +1. Вы можете продолжить вносить изменения и видеть результаты доработки в консоли. + +## Добавление зависимости +Немного меняя тему, давайте посмотрим, как использовать опубликованные библиотеки +для добавления дополнительных функций в наши приложения. + +1. Откройте `build.sbt` и добавьте следующую строку: + +``` +libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2" +``` +Здесь `libraryDependencies` представляет набор зависимостей, +и с помощью `+=` мы добавляем зависимость [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) +к набору зависимостей, которые sbt будет загружать при запуске. +Теперь в любом файле Scala можно импортировать классы, объекты и т.д. из `scala-parser-combinators` с помощью обычного импорта. + +Вы можете найти больше опубликованных библиотек на [Scaladex](https://index.scala-lang.org/), каталоге библиотек Scala, +где вы также можете скопировать указанную выше информацию о зависимостях для вставки в свой файл `build.sbt`. + +> **Примечание для Java библиотек:** Для обычной библиотеки Java следует использовать только один знак процента (`%`) +> между названием организации и именем артефакта. Двойной процент (`%%`) — это специализация Scala библиотек. +> Подробнее об этом можно узнать в [документации sbt][sbt-docs-lib-dependencies]. + +## Следующие шаги + +Перейдите к следующему учебнику из серии _getting started with sbt_ и узнайте, как [тестировать Scala c sbt и ScalaTest в командной строке](testing-scala-with-sbt-on-the-command-line.html). + +**или** + +- Продолжайте изучать Scala в интерактивном режиме на + [Scala Exercises](https://www.scala-exercises.org/scala_tutorial). +- Узнайте о возможностях Scala с помощью небольших статей, ознакомившись с нашим [туром по Scala]({{ site.baseurl }}/ru/tour/tour-of-scala.html). + +[sbt-docs-lib-dependencies]: https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Getting+the+right+Scala+version+with diff --git a/_ru/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md b/_ru/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md new file mode 100644 index 0000000000..a74aa92a19 --- /dev/null +++ b/_ru/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md @@ -0,0 +1,105 @@ +--- +title: Тестирование Scala c sbt и ScalaTest в командной строке +layout: singlepage-overview +partof: testing-scala-with-sbt-on-the-command-line +language: ru +disqus: true +previous-page: /ru/getting-started-with-scala-and-sbt-on-the-command-line +--- + +Для Scala существует множество библиотек и методологий тестирования, +но в этом руководстве мы продемонстрируем один популярный вариант из фреймворка ScalaTest +под названием [AnyFunSuite](https://www.scalatest.org/getting_started_with_fun_suite). + +Это предполагает, что вы знаете, [как создать проект с sbt](getting-started-with-scala-and-sbt-on-the-command-line.html). + +## Настройка +1. Используя командную строку создайте новую директорию. +1. Перейдите (`cd`) в этот каталог и запустите `sbt new scala/scalatest-example.g8`. +1. Назовите проект `ScalaTestTutorial`. +1. Проект поставляется с зависимостью ScalaTest в файле `build.sbt`. +1. Перейдите (`cd`) в этот каталог и запустите `sbt test`. Это запустит набор тестов +`CubeCalculatorTest` с одним тестом под названием `CubeCalculator.cube`. + +``` +sbt test +[info] Loading global plugins from /Users/username/.sbt/0.13/plugins +[info] Loading project definition from /Users/username/workspace/sandbox/my-something-project/project +[info] Set current project to scalatest-example (in build file:/Users/username/workspace/sandbox/my-something-project/) +[info] CubeCalculatorTest: +[info] - CubeCalculator.cube +[info] Run completed in 267 milliseconds. +[info] Total number of tests run: 1 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0 +[info] All tests passed. +[success] Total time: 1 s, completed Feb 2, 2017 7:37:31 PM +``` + +## Разбор кода +1. Откройте два файла в текстовом редакторе: + * `src/main/scala/CubeCalculator.scala` + * `src/test/scala/CubeCalculatorTest.scala` +1. В файле `CubeCalculator.scala` увидите определение функции `cube`. +1. В файле `CubeCalculatorTest.scala` тестируемый класс, названный так же как и объект. + +``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite: + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } +``` + +Давайте разберем код построчно: + +* `class CubeCalculatorTest` означает, что мы тестируем `CubeCalculator` +* `extends AnyFunSuite` позволяет нам использовать функциональность класса AnyFunSuite из ScalaTest, + такую как функция `test` +* `test` это функция из библиотеки FunSuite, которая собирает результаты проверок в теле функции. +* `"CubeCalculator.cube"` - это имя для теста. Вы можете называть тест как угодно, но по соглашению используется имя — "ClassName.methodName". +* `assert` принимает логическое условие и определяет, пройден тест или нет. +* `CubeCalculator.cube(3) === 27` проверяет, действительно ли вывод функции `cube` равен 27. + `===` является частью ScalaTest и предоставляет понятные сообщения об ошибках. + +## Добавление еще одного теста +1. Добавьте еще один тестовый блок с собственным оператором assert, который проверяет 0 в кубе. + + ``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite { + test("CubeCalculator.cube 3 should be 27") { + assert(CubeCalculator.cube(3) === 27) + } + + test("CubeCalculator.cube 0 should be 0") { + assert(CubeCalculator.cube(0) === 0) + } + } + ``` + +1. Запустите `sbt test` еще раз, чтобы увидеть результаты. + + ``` + sbt test + [info] Loading project definition from C:\projects\scalaPlayground\scalatestpractice\project + [info] Loading settings for project root from build.sbt ... + [info] Set current project to scalatest-example (in build file:/C:/projects/scalaPlayground/scalatestpractice/) + [info] Compiling 1 Scala source to C:\projects\scalaPlayground\scalatestpractice\target\scala-2.13\test-classes ... + [info] CubeCalculatorTest: + [info] - CubeCalculator.cube 3 should be 27 + [info] - CubeCalculator.cube 0 should be 0 + [info] Run completed in 257 milliseconds. + [info] Total number of tests run: 2 + [info] Suites: completed 1, aborted 0 + [info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 0 + [info] All tests passed. + [success] Total time: 3 s, completed Dec 4, 2019 10:34:04 PM + ``` + +## Заключение +Вы видели один из способов тестирования Scala кода. +Узнать больше о AnyFunSuite от ScalaTest можно на [официальном сайте](https://www.scalatest.org/getting_started_with_fun_suite). +Вы также можете использовать другие тестовые фреймворки, такие, как [ScalaCheck](https://www.scalacheck.org/) и [Specs2](https://etorreborre.github.io/specs2/). diff --git a/_ru/index.md b/_ru/index.md new file mode 100644 index 0000000000..7ac8c2a455 --- /dev/null +++ b/_ru/index.md @@ -0,0 +1,104 @@ +--- +layout: landing-page +title: Изучаем Scala +language: ru +partof: documentation +more-resources-label: Дополнительные Материалы + +sections: + - title: "Первые шаги..." + links: + - title: "Приступая к работе" + description: "Установите Scala на свой компьютер и начните писать код на Scala!" + icon: "fa fa-rocket" + link: /ru/getting-started/install-scala.html + - title: "Тур по Scala" + description: "Вступительный обзор по основным возможностям языка." + icon: "fa fa-flag" + link: /ru/tour/tour-of-scala.html + - title: "Книга по Scala 3" + description: "Изучайте Scala используя серию коротких уроков." + icon: "fa fa-book-open" + link: /ru/scala3/book/introduction.html + - title: "Набор инструментов Scala" + description: "Отправка HTTP-запросов, запись файлов, запуск программ, обработка JSON..." + icon: "fa fa-toolbox" + link: /toolkit/introduction.html + - title: Онлайн Курсы, Упражнения и Блоги + description: "Обучающие курсы по Scala от новичка до продвинутого уровня." + icon: "fa fa-cloud" + link: /online-courses.html + - title: Книги + description: "Напечатанные, а также электронные книги о Scala." + icon: "fa fa-book" + link: /books.html + - title: Уроки + description: "Пройдемся по серии коротких шагов по созданию Scala приложений." + icon: "fa fa-tasks" + link: /tutorials.html + + - title: "Для опытных" + links: + - title: "API" + description: "Документация по API для каждой версии Scala." + icon: "fa fa-file-alt" + link: /api/all.html + - title: "Справочники" + description: "Подробные справочники по отдельным разделам языка." + icon: "fa fa-database" + link: /ru/overviews/index.html + - title: "Стилистика" + description: "Детальное руководство по написанию каноничного Scala кода." + icon: "fa fa-bookmark" + link: /style/index.html + - title: "Шпаргалка" + description: "Краткий справочник, охватывающий основы синтаксиса Scala." + icon: "fa fa-list" + link: /ru/cheatsheets/index.html + - title: "Вопрос-Ответ" + description: "Список по наиболее часто задаваемым вопросам с ответами по функционалу Scala." + icon: "fa fa-question-circle" + link: /tutorials/FAQ/index.html + - title: "Спецификация v2.x" + description: "Официальная спецификация языка Scala 2." + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/2.13/ + - title: "Спецификация v3.x" + description: "Официальная спецификация языка Scala 3." + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/3.4/ + - title: "Справочник по языку Scala 3" + description: "Справочник по языку Scala 3." + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference + + - title: "Исследуем Scala 3" + links: + - title: "Руководство по миграции" + description: "Руководство, которое поможет вам перейти от Scala 2 к Scala 3." + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "Новое в Scala 3" + description: "Обзор новой функциональности в Scala 3." + icon: "fa fa-star" + link: /ru/scala3/new-in-scala3.html + - title: "Новая функциональность Scaladoc для Scala 3" + description: "Ключевые особенности новой функциональности Scaladoc." + icon: "fa fa-star" + link: /ru/scala3/scaladoc.html + - title: "Выступления" + description: "Доступные онлайн выступления о Scala 3." + icon: "fa fa-play-circle" + link: /ru/scala3/talks.html + + - title: "Развитие Scala" + links: + - title: "Процесс улучшения Scala" + description: "Описание процесса развития языка и список всех предложений по улучшению Scala (SIP)." + icon: "fa fa-cogs" + link: /sips/index.html + - title: "Станьте участником развития Scala" + description: "От начала до конца: узнайте, как вы можете помочь открытой экосистеме Scala." + icon: "fa fa-code-branch" + link: /contribute/ +--- diff --git a/_ru/online-courses.md b/_ru/online-courses.md new file mode 100644 index 0000000000..2ec0c26bc9 --- /dev/null +++ b/_ru/online-courses.md @@ -0,0 +1,62 @@ +--- +title: Online ресурсы +layout: singlepage-overview +language: ru +redirect-from: + - /learn.html +--- + +## Попробуй Scala в своем браузере! + +Существует несколько веб-сайтов, на которых вы можете интерактивно запускать код Scala в своем браузере! +Взгляните на [Scastie](https://scastie.scala-lang.org/). + +## Онлайн-курсы от Scala Center + +[Scala Center](https://scala.epfl.ch) стремится создавать высококачественные и бесплатные онлайн-курсы +для изучения Scala и функционального программирования. +Уровни курса варьируются от начального до продвинутого. +Более подробная информация доступна [на следующей странице]({% link scalacenter-courses.md %}). + +## Упражнения на языке Scala + +[Scala Exercises](https://www.scala-exercises.org/) — это серия уроков и упражнений, созданных [47 Degrees](https://www.47deg.com/). +Это отличный способ получить краткое представление о Scala и одновременно проверить свои знания. + +[Tour of Scala](https://tourofscala.com) шаг за шагом знакомит вас со Scala, от новичка до эксперта. + +## Лекции доктора Mark C Lewis из Trinity University + +[Dr. Mark C Lewis](https://www.cs.trinity.edu/~mlewis/) из Университета Тринити, Сан-Антонио, Техас, +преподает курсы программирования с использованием языка Scala. +Видеокурсы доступны на YouTube бесплатно. Некоторые курсы ниже. + +- [Introduction to Programming and Problem Solving Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt9MIJ9DV4ps-_trOzWtphYO) +- [Object-Orientation, Abstraction, and Data Structures Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt8JLumqKj-3BlHmEXPIfR42) + +Вы можете посетить его [YouTube канал](https://www.youtube.com/user/DrMarkCLewis/featured), +чтобы найти больше видео. + +## Сообщество обучения Scala + +[Сообщество по изучению Scala в Discord](http://sca.la/learning-community) — растущее онлайн-сообщество, +объединяющее учащихся с онлайн-ресурсами для совместного изучения Scala. + +## allaboutscala + +[allaboutscala](https://allaboutscala.com/) предоставляет подробные руководства для начинающих. + +## DevInsideYou + +[DevInsideYou](https://youtube.com/devinsideyou) — это YouTube канал с сотнями часов бесплатного контента Scala. + +## Rock the JVM + +[Rock the JVM](https://rockthejvm.com) — это учебная платформа с бесплатными и платными курсами +по языку Scala, Akka, Cats Effect, ZIO, Apache Spark и другим инструментам экосистемы Scala. +Он также содержит сотни [бесплатных видеоуроков](https://youtube.com/rockthejvm) +и [статей](https://blog.rockthejvm.com) по различным темам, связанным со Scala. + +## Visual Scala Reference + +[Visual Scala Reference](https://superruzafa.github.io/visual-scala-reference/) — руководство по визуальному изучению концепций и функций Scala. diff --git a/_ru/overviews/collections-2.13/arrays.md b/_ru/overviews/collections-2.13/arrays.md new file mode 100644 index 0000000000..856c08002c --- /dev/null +++ b/_ru/overviews/collections-2.13/arrays.md @@ -0,0 +1,119 @@ +--- +layout: multipage-overview +title: Массивы +partof: collections-213 +overview-name: Collections +num: 10 +previous-page: concrete-mutable-collection-classes +next-page: strings +language: ru +--- + +[Массивы](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html) особый вид коллекций в Scala. +С одной стороны, Scala массивы соответствуют массивам из Java. Например, Scala массив `Array[Int]` реализован в виде Java `int[]`, а `Array[Double]` как Java `double[]` и `Array[String]` как Java `String[]`. С другой стороны, Scala массивы дают намного больше чем их Java аналоги. Во-первых, Scala массивы могут быть обобщены (_generic_). То есть вы можете описать массив как `Array[T]`, где `T` дополнительный `параметр-тип` массива или же абстрактный тип. + Во-вторых, Scala массивы совместимы со списками (`Seq`) Scala - вы можете передавать `Array[T]` на вход туда, где требуется `Seq[T]`. Ну и наконец, Scala массивы также поддерживают все операции, которые есть у списков. Вот пример: + + scala> val a1 = Array(1, 2, 3) + a1: Array[Int] = Array(1, 2, 3) + scala> val a2 = a1 map (_ * 3) + a2: Array[Int] = Array(3, 6, 9) + scala> val a3 = a2 filter (_ % 2 != 0) + a3: Array[Int] = Array(3, 9) + scala> a3.reverse + res0: Array[Int] = Array(9, 3) + +Учитывая то, что Scala массивы соответствуют массивам из Java, каким же образом реализованы остальные дополнительные возможности массивов в Scala? +Реализация массивов в Scala постоянно использует неявные преобразования. В Scala массив не пытается _притворяться_ последовательностью. Он и не может, потому что тип данных лежащий в основе массива не является подтипом `Seq`. Вместо этого, используя "упаковывание", происходит неявное преобразование между массивами и экземплярами класса `scala.collection.mutable.ArraySeq`, который является подклассом `Seq`. Вот как это работает: + + scala> val seq: collection.Seq[Int] = a1 + seq: scala.collection.Seq[Int] = ArraySeq(1, 2, 3) + scala> val a4: Array[Int] = seq.toArray + a4: Array[Int] = Array(1, 2, 3) + scala> a1 eq a4 + res1: Boolean = false + +Пример выше показывает, что массивы совместимы с последовательностями, потому как происходит неявное преобразование из массивов в `ArraySeq`ы. Чтобы перейти обратно от `ArraySeq` к `Array`, можно использовать метод `toArray`, описанный в `Iterable`. Последняя строка в консоле показывает, что упаковка и затем распаковка с помощью `toArray` создает копию исходного массива. + +Существует еще одно неявное преобразование, которое применяется к массивам. Такое преобразование просто "добавляет" все методы последовательностей (`Seq`) к массивам, но не превращает сам массив в последовательность. "Добавление" означает, что массив обернут в другой объект типа `ArrayOps`, который поддерживает все методы последовательности. Объект `ArrayOps` недолговечный, обычно он недоступен после обращения к методу последовательности и он может быть удален. Современные виртуальные машины могут избегать создания такого промежуточного объекта. + +Разница между двумя неявными преобразованиями на массивах показана в следующем примере: + + scala> val seq: collection.Seq[Int] = a1 + seq: scala.collection.Seq[Int] = ArraySeq(1, 2, 3) + scala> seq.reverse + res2: scala.collection.Seq[Int] = ArraySeq(3, 2, 1) + scala> val ops: collection.ArrayOps[Int] = a1 + ops: scala.collection.ArrayOps[Int] = scala.collection.ArrayOps@2d7df55 + scala> ops.reverse + res3: Array[Int] = Array(3, 2, 1) + +Вы видите, что вызов `reverse` на `seq`, который является `ArraySeq`, даст снова `ArraySeq`. Это логично, потому что массивы - это `Seqs`, и вызов `reverse` на любом `Seq` даст снова `Seq`. С другой стороны, вызов `reverse` на экземпляре класса `ArrayOps` даст значение `Array`, а не `Seq`. + +Пример `ArrayOps`, приведенный выше искусственный и используется лишь, чтобы показать разницу с `ArraySeq`. Обычно, вы никогда не создаете экземпляры класса `ArrayOps`. Вы просто вызываете методы `Seq` на массиве: + + scala> a1.reverse + res4: Array[Int] = Array(3, 2, 1) + +Объект `ArrayOps` автоматически вставляется через неявное преобразование. Так что строка выше эквивалентна + + scala> intArrayOps(a1).reverse + res5: Array[Int] = Array(3, 2, 1) + +где `intArrayOps` - неявное преобразование, которое было вставлено ранее. В связи с этим возникает вопрос, как компилятор выбрал `intArrayOps` вместо другого неявного преобразования в `ArraySeq` в строке выше. В конце концов, оба преобразования преобразуют массив в тип, поддерживающий метод reverse. Ответ на этот вопрос заключается в том, что два неявных преобразования имеют приоритет. Преобразование `ArrayOps` имеет больший приоритет, чем преобразование `ArraySeq`. Первый определяется в объекте `Predef`, а второй - в классе `scala.LowPriorityImplicits`, который `Predef` наследует. Неявные преобразования в дочерних классах и дочерних объектах имеют более высокий приоритет над преобразованиями в базовых классах. Таким образом, если оба преобразования применимы, выбирается вариант в `Predef`. Очень похожая схема используется для строк. + +Итак, теперь вы знаете, как массивы могут быть совместимы с последовательностями и как они могут поддерживать все операции последовательностей. А как же обобщения? В Java нельзя написать `T[]`, где `T` является параметром типа. Как же представлен Scala `Array[T]`? На самом деле обобщенный массив типа `Array[T]` может быть любым из восьми примитивных типов массивов Java `byte[]`, `short[]`, `char[]`, `int[] `, `long[] `, `float[]`, `double ` или может быть массивом объектов. Единственным общим типом, включающим все эти типы, является `AnyRef` (или, равнозначно `java.lang.Object`), так что это тот тип, в который компилятор Scala отобразит `Array[T]`. Во время исполнения, при обращении к элементу массива типа `Array[T]`, происходит последовательность проверок типов, которые определяют тип массива, за которыми следует подходящая операция на Java-массиве. Эти проверки типов замедляют работу массивов. Можно ожидать падения скорости доступа к обобщенным массивам в три-четыре раза, по сравнению с обычными массивами или массивами объектов. Это означает, что если вам нужна максимальная производительность, вам следует выбирать конкретные массивы, вместо обобщенных. Отображать обобщенный массив еще полбеды, нам нужен еще способ создания обобщенных массивов. Это куда более сложная задача, которая требует от вас небольшой помощи. Чтобы проиллюстрировать проблему, рассмотрим следующую попытку написания обобщенного метода, который создает массив. + + // это неправильно! + def evenElems[T](xs: Vector[T]): Array[T] = { + val arr = new Array[T]((xs.length + 1) / 2) + for (i <- 0 until xs.length by 2) + arr(i / 2) = xs(i) + arr + } + +Метод `evenElems` возвращает новый массив, состоящий из всех элементов аргумента вектора `xs`, находящихся в четных позициях вектора. В первой строке тела `evenElems` создается результирующий массив, который имеет тот же тип элемента, что и аргумент. Так что в зависимости от фактического типа параметра для `T`, это может быть `Array[Int]`, или `Array[Boolean]`, или массив некоторых других примитивных типов Java, или массив какого-нибудь ссылочного типа. Но эти типы имеют разные представления при исполнении программы, и как же Scala подберет правильное представление? В действительности, Scala не может сделать этого, основываясь на предоставленной информации, так как при выполнении стирается фактический тип, соответствующий параметру типа `T`. Поэтому при компиляции показанного выше кода, появится следующее сообщение об ошибке: + + error: cannot find class manifest for element type T + val arr = new Array[T]((arr.length + 1) / 2) + ^ + +Тут нужно немного помочь компилятору, указав какой в действительности тип параметра `evenElems`. Это указание во время исполнения принимает форму манифеста класса типа `scala.view.ClassTag`. _Манифест класса_ - это объект дескриптор типа, который описывает, какой тип у класса верхнего уровня. В качестве альтернативы манифестам классов существуют также _полные манифесты_ типа `scala.Refect.Manifest`, которые описывают все аспекты типа. Впрочем для создания массива требуются только _манифесты класса_. + +Компилятор Scala автоматически создаст манифесты классов, если вы проинструктируете его на это. "Инструктирование" означает, что вы требуете манифест класса в качестве неявного параметра, как в примере: + + def evenElems[T](xs: Vector[T])(implicit m: ClassTag[T]): Array[T] = ... + +Используя альтернативный и более короткий синтаксис, вы также можете потребовать, чтобы тип приходил с манифестом класса, используя _контекстное связывание_ (`context bound`). Это означает установить связь с типом `ClassTag` идущим после двоеточия в описании типа, как в примере: + + import scala.reflect.ClassTag + // так будет работать + def evenElems[T: ClassTag](xs: Vector[T]): Array[T] = { + val arr = new Array[T]((xs.length + 1) / 2) + for (i <- 0 until xs.length by 2) + arr(i / 2) = xs(i) + arr + } + +Обе показанные версии `evenElems` означают одно и то же. Что бы не случилось, когда построен `Array[T]`, компилятор будет искать манифест класса для параметра типа `T`, то есть искать неявное значение (implicit value) типа `ClassTag[T]`. Если такое значение найдено, то этот манифест будет использоваться для построения требуемого типа массива. В противном случае вы увидите сообщение об ошибке, такое же как мы показывали выше. + +Вот некоторые примеры из консоли, использующие метод `evenElems`. + + scala> evenElems(Vector(1, 2, 3, 4, 5)) + res6: Array[Int] = Array(1, 3, 5) + scala> evenElems(Vector("this", "is", "a", "test", "run")) + res7: Array[java.lang.String] = Array(this, a, run) + +В обоих случаях компилятор Scala автоматически построил манифест класса для типа элемента (сначала `Int`, затем `String`) и передал его в качестве неявного параметра метода `evenElems`. Компилятор может сделать это для всех конкретных типов, но не тогда, когда аргумент сам параметризован типом, который не содержит манифест класса. Например, следующий пример не скомпилируется: + + scala> def wrap[U](xs: Vector[U]) = evenElems(xs) + :6: error: No ClassTag available for U. + def wrap[U](xs: Vector[U]) = evenElems(xs) + ^ +В данном случае `evenElems` требует наличия класса манифеста для параметра типа `U`, однако ни одного не найдено. Чтоб решить такую проблему, конечно, необходимо запросить манифест от неявного класса `U`. Поэтому следующее будет работать: + + scala> def wrap[U: ClassTag](xs: Vector[U]) = evenElems(xs) + wrap: [U](xs: Vector[U])(implicit evidence$1: scala.reflect.ClassTag[U])Array[U] + +Этот пример также показывает, что контекстное связывание с `U`, является лишь сокращением для неявного параметра, названного здесь `evidence$1` типа `ClassTag[U]`. + +Подводя итог, можно сказать, что для создания обобщенных массивов требуются манифесты классов. Поэтому при создании массива параметризированного типом `T`, вам также необходимо предоставить неявный класс манифест для `T`. Самый простой способ сделать это - объявить параметр типа `ClassTag` с контекстной привязкой, как `[T: ClassTag]`. diff --git a/_ru/overviews/collections-2.13/concrete-immutable-collection-classes.md b/_ru/overviews/collections-2.13/concrete-immutable-collection-classes.md new file mode 100644 index 0000000000..e2f94e3455 --- /dev/null +++ b/_ru/overviews/collections-2.13/concrete-immutable-collection-classes.md @@ -0,0 +1,218 @@ +--- +layout: multipage-overview +title: Реализации Неизменяемых Коллекций +partof: collections-213 +overview-name: Collections +previous-page: maps +next-page: concrete-mutable-collection-classes +num: 8 +language: ru +--- + +Scala предлагает множество конечных реализаций неизменяемых коллекций. Они отличаются реализуемыми трейтами (мапы (map), множества(set), последовательности(seq)), они могут быть бесконечными, и различаются производительностью операций. Вот некоторые из наиболее распространенных неизменяемых типов коллекций, используемых в Scala. + +## Списки (Lists) + +[List](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/List.html) представляет из себя конечную неизменяемую последовательность. Он обеспечивает быстрый (за [постоянное время](https://ru.wikipedia.org/wiki/%D0%92%D1%80%D0%B5%D0%BC%D0%B5%D0%BD%D0%BD%D0%B0%D1%8F_%D1%81%D0%BB%D0%BE%D0%B6%D0%BD%D0%BE%D1%81%D1%82%D1%8C_%D0%B0%D0%BB%D0%B3%D0%BE%D1%80%D0%B8%D1%82%D0%BC%D0%B0)) доступ как к первому элементу, так и к остальному списку, а также быструю операцию добавления нового элемента в начало списка. Большинство оставшихся операции занимают линейное время исполнения. + +## Ленивые Списки (LazyLists) + +[LazyList](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/LazyList.html) похож на список, за исключением того, что его элементы вычисляются лениво. Поэтому ленивый список может быть бесконечно длинным. Обрабатываются только те элементы, которые запрашиваются. В остальном, у ленивых списков те же параметры производительности, что и обычных. + +Если списки создаются с помощью оператора `::`, то ленивые списки создаются схожей операцией `#::`. Вот простой пример ленивого списка с целыми числами 1, 2 и 3: + + scala> val lazyList = 1 #:: 2 #:: 3 #:: LazyList.empty + lazyList: scala.collection.immutable.LazyList[Int] = LazyList(?) + +На первом месте в этом ленивом списке - 1, а на втором - 2 и 3. Но ни один из элементов здесь не выводится, потому что список еще не вычислен! Ленивые списки задуманы обрабатываться лениво, поэтому метод `toString` не выводит всех элементов, не заставляя производить дополнительные вычисления. + +Ниже приводится более сложный пример. Вычисления ленивого списка, содержащего последовательность Фибоначчи, которая начинается с заданных двух чисел. Последовательность Фибоначчи - это последовательность, в которой каждый элемент представляет собой сумму двух предыдущих элементов в серии. + + scala> def fibFrom(a: Int, b: Int): LazyList[Int] = a #:: fibFrom(b, a + b) + fibFrom: (a: Int,b: Int)LazyList[Int] + +Эта функция обманчиво проста. Первый элемент очевидно `a`, остальная часть - это последовательность Фибоначчи, начинающаяся с `b`, за которой следует `a+b`. Сложность состоит в том, чтобы вычислить эту последовательность, не вызывая бесконечной рекурсии. Если бы функция использовала `::` вместо `#::`, то каждый вызов функции приводил бы к очередному вызову, вызывая тем самым бесконечную рекурсию. Но так как он использует `#::`, то вычисление правой части не производится до тех пор, пока она не будет запрошена. + +Ниже приведены первые элементы последовательности Фибоначчи, начиная с двух едениц: + + scala> val fibs = fibFrom(1, 1).take(7) + fibs: scala.collection.immutable.LazyList[Int] = LazyList(?) + scala> fibs.toList + res9: List[Int] = List(1, 1, 2, 3, 5, 8, 13) + +## Неизменяемые ArraySeqs + +Списки очень эффективны в алгоритмах которые активно использует `head`. Получение, добавление и удаление к переднему (`head`) элементу списка занимает постоянное время, в то время как доступ или изменение остальных элементов в списке занимает линейное время. + +[Последовательный Массив (ArraySeq)](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/ArraySeq.html) это тип коллекции + (добавленной в Scala 2.13) который решает проблему неэффективности случайного доступа к спискам. + + ArraySeq позволяют получить доступ к любому элементу коллекции за постоянное время. +В результате алгоритмы, использующие ArraySeq, могут быстро получать доступ к элементам в произвольных местах коллекции, из-за чего проще создавать эффективные алгоритмы. + +ArraySeqs создаются и изменяются также, как и любые другие последовательности. + +~~~ +scala> val arr = scala.collection.immutable.ArraySeq(1, 2, 3) +arr: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 3) +scala> val arr2 = arr :+ 4 +arr2: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 3, 4) +scala> arr2(0) +res22: Int = 1 +~~~ + +ArraySeqs являются неизменяемыми, поэтому вы не можете изменять элементы непосредственно в коллекции. Однако операции `updated`, `appended` и `prepended` создают новые ArraySeqs, которые отличаются от базового ArraySeq только в одном элементе: + +~~~ +scala> arr.updated(2, 4) +res26: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 4) +scala> arr +res27: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 3) +~~~ + +Как видно из последней строки выше, вызов `updated` не влияет на исходный ArraySeq `arr`. + +ArraySeqs хранят свои элементы в приватном [Массиве]({% link _ru/overviews/collections-2.13/arrays.md %}). Таким образом достигается компактное представление и обеспечивается быстрый индексированный доступ к элементам, но обновление или добавление одного элемента занимает линейное время, так как требует создания другого массива и копирования всех элементов исходного массива. + +## Вектора (Vectors) + +В предыдущих разделах мы увидели, что `List` и `ArraySeq` эффективные структуры данных в некоторых специфичных ситуациях, но они неэффективны в других: например, добавление элемента происходит за постоянное время для `List`, но линейно для `ArraySeq`, и наоборот, индексированный доступ является постоянным для `ArraySeq`, но линейным для `List`. + +[Вектор](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html) - тип коллекции, который обеспечивает хорошую производительность для всех своих операций. Вектора позволяют получить доступ к любому элементу последовательности за "практически" постоянное время. Это значит что константа больше, чем при получении переднего (`head`) элемента списка или при чтения элемента из ArraySeq, но, тем не менее, это константа. Избегайте использование векторов в алгоритмах базирующихся на активной работе с передними (`head`) элементами. Вектора могут получать доступ к элементам и изменять их в произвольных местах, что делает разработку более простой и удобной. + +Вектора создаются и модифицируются так же, как и другие последовательности. + + scala> val vec = scala.collection.immutable.Vector.empty + vec: scala.collection.immutable.Vector[Nothing] = Vector() + scala> val vec2 = vec :+ 1 :+ 2 + vec2: scala.collection.immutable.Vector[Int] = Vector(1, 2) + scala> val vec3 = 100 +: vec2 + vec3: scala.collection.immutable.Vector[Int] = Vector(100, 1, 2) + scala> vec3(0) + res1: Int = 100 + +Вектора представлены деревьями с высоким уровнем ветвления (уровень ветвления дерева или графа - это количество дочерних элементов у каждого узла). Каждый узел дерева содержит до 32х элементов вектора или содержит до 32х других узлов. Вектора с размером до 32х элементов могут быть представлены одним узлом. Вектора `32 * 32 = 1024` элементы могут быть представлены одним витком. +Для векторов с 215 элементами достаточно двух переходов от корня дерева до конечного элемента узла, трех переходов для векторов с 220 элементами, четырех переходов для 225 элементами и пяти переходов для 230 элементами. Таким образом, для всех векторов разумных размеров выбор элемента включает до 5 простых выборок массивов. Именно это мы подразумевали, когда писали, что доступ к элементам осуществляется с "практически постоянным временем". + +Так же как и доступ к элементу, операция обновления в векторах занимает "практически" постоянное время. Добавление элемента в середину вектора может быть выполнено через копирование узла содержащего этот элемент и каждого ссылающегося на него узла, начиная от корня дерева. Это означает, что процесс обновления элемента создает от одного до пяти узлов, каждый из которых содержит до 32 элементов или поддеревьев. Это, конечно, дороже, чем просто обновление элемента в изменяемом массиве, но все же намного дешевле, чем копирование вообще всего вектора. + +Поскольку вектора обладают хорошим балансом между быстрой случайной выборкой и быстрым случайным обновлением элементов, они используются в качестве реализации неизменяемых индексированных последовательностей: + + scala> collection.immutable.IndexedSeq(1, 2, 3) + res2: scala.collection.immutable.IndexedSeq[Int] = Vector(1, 2, 3) + +## Неизменяемые Очереди (Immutable Queues) + +[Очередь](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Queue.html) это последовательность с [FIFO](https://ru.wikipedia.org/wiki/FIFO) (первым пришёл — первым ушёл). +Вы добавляете элемент в очередь методом `enqueue` и достаете элемент из очереди используя метод `dequeue`. Эти операции - выполняются за постоянное время. + +Вот как можно создать пустую неизменяемую очередь: + + scala> val empty = scala.collection.immutable.Queue[Int]() + empty: scala.collection.immutable.Queue[Int] = Queue() + +Вы можете добавить элемент в неизменяемую очередь используя `enqueue`: + + scala> val has1 = empty.enqueue(1) + has1: scala.collection.immutable.Queue[Int] = Queue(1) + +Чтобы добавить несколько элементов в очередь, испольуйте метод `enqueueAll` с коллекцией в качестве аргумента: + + scala> val has123 = has1.enqueueAll(List(2, 3)) + has123: scala.collection.immutable.Queue[Int] + = Queue(1, 2, 3) + +Для удаления элемента из начала очереди используется команда `dequeue`: + + scala> val (element, has23) = has123.dequeue + element: Int = 1 + has23: scala.collection.immutable.Queue[Int] = Queue(2, 3) + +Обратите внимание, что `dequeue` возвращает пару, состоящую из удаленного элемента и остальной части очереди. + +## Диапазоны (Ranges) + +[Диапазон](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html) +представляет собой упорядоченную последовательность целых чисел, которые отделены друг от друга одинаковыми размерами. Например, "1, 2, 3" - это диапазон, так же как и "5, 8, 11, 14". Для создания диапазона в Scala используйте заготовленные методы `to` и `by`. + + scala> 1 to 3 + res2: scala.collection.immutable.Range.Inclusive = Range(1, 2, 3) + scala> 5 to 14 by 3 + res3: scala.collection.immutable.Range = Range(5, 8, 11, 14) + +Если вы хотите создать диапазон, исключающий верхнюю границу, то для удобства используйте метод `until` вместо `to`: + + scala> 1 until 3 + res2: scala.collection.immutable.Range = Range(1, 2) + +Диапазоны занимают константный размер, потому что они могут быть определены только тремя цифрами: их началом, концом и значением шага. Благодаря этому представлению большинство операций на диапазонах выполняется очень быстро. + +## Compressed Hash-Array Mapped Prefix-trees + +Хэш деревья - это стандартный способ эффективного создания неизменяемых множеств и ассоциативных массивов (мап). [Compressed Hash-Array Mapped Prefix-trees](https://github.com/msteindorfer/oopsla15-artifact/) - это специальные хэш деревья для JVM, которые улучшают локальность и обеспечивают компактную и элегантную реализацию деревьев. Они базируются на классе [immutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/HashMap.html). Их представление очень похоже на реализацию векторов, которые также являются деревьями, где каждый узел имеет либо 32 элемента либо 32 поддерева. Но в данном случае ключ выбирается на основе хэш-кода. Например, чтобы найти ключ на мапе, сначала берут хэш-код ключа. Затем самые младшие 5 бит хэш-кода используются для выбора первого поддерева, за которым следуют следующие 5 бит и так далее. Выбор прекращается, когда для всех битов будут найдены ключи. + +Хэш деревья пытаются предоставить разумный баланс между достаточно быстрым поиском и достаточно эффективными операциями вставки (`+`) и удаления (`-`) элементов. Именно поэтому они лежат в основе стандартных реализаций Scala неизменяемых множеств и ассоциативных массивов (мап). На самом деле, в Scala есть дополнительная оптимизация для неизменяемых множеств и мап, которые содержат менее пяти элементов. Множества и мапы от одного до четырех элементов хранятся как обычные объекты, которые содержат только элементы (или пары ключ/значение в случае мапы) как поля. Пустое неизменяемое множество и пустая неизменяемая мапа - это всегда объект-сингэлтон - нет необходимости размножать сущности для них, потому что пустое неизменяемое множество или мапа всегда будут оставаться пустыми. + +## Красно-Черные Деревья (Red-Black Trees) + +Красно-черные деревья представляют собой разновидность сбалансированного двоичного дерева, где одни узлы помечаются как "красные", а другие - как "черные". Как и любое сбалансированное двоичное дерево, операции над ним занимают по времени логарифм от количества элементов дерева. + +Scala предлагает реализацию неизменяемых множеств и мап, использующих красно-черное дерево, в классах [TreeSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeSet.html) и [TreeMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/TreeMap.html). + + + scala> scala.collection.immutable.TreeSet.empty[Int] + res11: scala.collection.immutable.TreeSet[Int] = TreeSet() + scala> res11 + 1 + 3 + 3 + res12: scala.collection.immutable.TreeSet[Int] = TreeSet(1, 3) + +Красно-черные деревья - стандартная реализацией `SortSet` в Scala, поскольку они предоставляют эффективный итератор, который выдает все элементы в отсортированном порядке. + +## Неизменяемые Битовые Наборы (Immutable BitSets) + +[BitSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/BitSet.html) +представляет собой набор маленьких целых чисел в виде набора битов большего целого числа. Например, набор битов, содержащий 3, 2 и 0, будет представлен как целое число 1101 в двоичном виде, т.е. 13 в десятичном. + +Внутри битового набора используется массив 64-битных `Long`ов. Первый `Long` в массиве для целых чисел от 0 до 63, второй для чисел от 64 до 127 и так далее. Таким образом, наборы битов очень компактны до тех пор, пока наибольшее целое число в наборе меньше нескольких сотен или около того. + +Операции с битовым набором выполняются очень быстро. Проверка на наличие занимает постоянное время. Добавление элемента в набор занимает время, пропорциональное количеству `Long`ов в массиве битов, которых обычно совсем не много. Вот несколько простых примеров использования битового набора: + + scala> val bits = scala.collection.immutable.BitSet.empty + bits: scala.collection.immutable.BitSet = BitSet() + scala> val moreBits = bits + 3 + 4 + 4 + moreBits: scala.collection.immutable.BitSet = BitSet(3, 4) + scala> moreBits(3) + res26: Boolean = true + scala> moreBits(0) + res27: Boolean = false + +## VectorMaps + +[VectorMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/VectorMap.html) +представляет собой мапу, использующую и `Vector` ключей и `HashMap`. У него есть итератор, который возвращает все записи в порядке их вставки. + +~~~ +scala> val vm = scala.collection.immutable.VectorMap.empty[Int, String] +vm: scala.collection.immutable.VectorMap[Int,String] = + VectorMap() +scala> val vm1 = vm + (1 -> "one") +vm1: scala.collection.immutable.VectorMap[Int,String] = + VectorMap(1 -> one) +scala> val vm2 = vm1 + (2 -> "two") +vm2: scala.collection.immutable.VectorMap[Int,String] = + VectorMap(1 -> one, 2 -> two) +scala> vm2 == Map(2 -> "two", 1 -> "one") +res29: Boolean = true +~~~ + +Первые строки показывают, что содержимое `VectorMap` сохраняет порядок вставки, а последняя строка показывает, что `VectorMap` сравнимы с другими `Map` и что это сравнение не учитывает порядок элементов. + +## ListMaps + +[ListMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/ListMap.html) +представляет собой мапу в виде связанного списка пар ключ-значение. В общем, операции на связанной мапе могут потребовать обхода по всему связанному списку. Таким образом, время выполнении обхода на связанной мапе линейно зависит от размера мапы. На самом деле, для связанных мапов в Scala практически нет вариантов для использования, так как стандартные мапы практически всегда быстрее. Единственным возможным исключением из этого, является то, что мапа по каким-либо причинам построена таким образом, что первые элементы в списке запрашиваются намного чаще, чем все остальные. + + scala> val map = scala.collection.immutable.ListMap(1->"one", 2->"two") + map: scala.collection.immutable.ListMap[Int,java.lang.String] = + Map(1 -> one, 2 -> two) + scala> map(2) + res30: String = "two" diff --git a/_ru/overviews/collections-2.13/concrete-mutable-collection-classes.md b/_ru/overviews/collections-2.13/concrete-mutable-collection-classes.md new file mode 100644 index 0000000000..1506db43ce --- /dev/null +++ b/_ru/overviews/collections-2.13/concrete-mutable-collection-classes.md @@ -0,0 +1,156 @@ +--- +layout: multipage-overview +title: Реализации Изменяемых Коллекций +partof: collections-213 +overview-name: Collections +num: 9 +previous-page: concrete-immutable-collection-classes +next-page: arrays +language: ru +--- + +Вы уже успели увидеть наиболее часто используемые неизменяемые типы коллекции, которые есть в стандартной библиотеке Scala. Настало время посмотреть на изменяемые (mutable) типы коллекции. + +## Array Buffers + +[ArrayBuffer](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayBuffer.html) - буферизированный массив в своем буфере хранит массив и его размер. Большинство операций с буферизированным массивом выполняются с той же скоростью, что и с массивом, так как операции просто обращаются и изменяют исходный массив. Кроме того, он может эффективно добавлять данные к своему концу. Присоединение элемента к такому массиву занимает амортизированное константное время. Поэтому буферизированные массивы будут полезны, если вы строите большую коллекцию данных регулярно добавляя новые элементы в конец. + + scala> val buf = scala.collection.mutable.ArrayBuffer.empty[Int] + buf: scala.collection.mutable.ArrayBuffer[Int] = ArrayBuffer() + scala> buf += 1 + res32: buf.type = ArrayBuffer(1) + scala> buf += 10 + res33: buf.type = ArrayBuffer(1, 10) + scala> buf.toArray + res34: Array[Int] = Array(1, 10) + +## List Buffers + +похож на буферизированный массив, за исключением того, что он базируется на связанном списке, а не массиве. Если после создания буферизированного объекта, вы планируете преобразовать его в список, то лучше используйте `ListBuffer` вместо `ArrayBuffer`. + + scala> val buf = scala.collection.mutable.ListBuffer.empty[Int] + buf: scala.collection.mutable.ListBuffer[Int] = ListBuffer() + scala> buf += 1 + res35: buf.type = ListBuffer(1) + scala> buf += 10 + res36: buf.type = ListBuffer(1, 10) + scala> buf.toList + res37: List[Int] = List(1, 10) + +## StringBuilders + +Так же как буферизированный массив полезен для создания массивов, а буферизированный список полезен для построения списков, [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html) полезен для создания строк. StringBuilders настолько широко используются, что они уже импортированы по умолчанию в стандартную область видимости. Можете создать их с помощью `new StringBuilder`, как в следующем примере: + + scala> val buf = new StringBuilder + buf: StringBuilder = + scala> buf += 'a' + res38: buf.type = a + scala> buf ++= "bcdef" + res39: buf.type = abcdef + scala> buf.toString + res41: String = abcdef + +## ArrayDeque + +[ArrayDeque](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayDeque.html) +это последовательность, поддерживающая эффективное добавление элементов как спереди, так и сзади. +Реализован на основе массива с изменяемым размером. + +Если вам нужно добавить элементы к началу или концу буфера, используйте `ArrayDeque` вместо `ArrayBuffer`. + +## Queues (Очереди) + +Scala предоставляет не только неизменяемые, но и изменяемые очереди. Работать с изменяемой очередью - `mQueue` можно аналогично неизменяемой, но вместо `enqueue` для добавления элементов используете операторы `+=` и `++=` . Кроме того, в изменяемой очереди метод `dequeue` просто удалит передний элемент из очереди, возвратив его в качестве результата работы метода. Например: + + scala> val queue = new scala.collection.mutable.Queue[String] + queue: scala.collection.mutable.Queue[String] = Queue() + scala> queue += "a" + res10: queue.type = Queue(a) + scala> queue ++= List("b", "c") + res11: queue.type = Queue(a, b, c) + scala> queue + res12: scala.collection.mutable.Queue[String] = Queue(a, b, c) + scala> queue.dequeue + res13: String = a + scala> queue + res14: scala.collection.mutable.Queue[String] = Queue(b, c) + +## Stacks (Стэки) + +Вы видели неизменяемые стэки раньше. Существует еще и изменяемая версия, предоставляемая классом [mutable.Stack](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/Stack.html). Который работает точно так же, как и неизменяемая версия, за исключением того, что изменения происходят прямо в нём самом. + + scala> val stack = new scala.collection.mutable.Stack[Int] + stack: scala.collection.mutable.Stack[Int] = Stack() + scala> stack.push(1) + res0: stack.type = Stack(1) + scala> stack + res1: scala.collection.mutable.Stack[Int] = Stack(1) + scala> stack.push(2) + res0: stack.type = Stack(1, 2) + scala> stack + res3: scala.collection.mutable.Stack[Int] = Stack(1, 2) + scala> stack.top + res8: Int = 2 + scala> stack + res9: scala.collection.mutable.Stack[Int] = Stack(1, 2) + scala> stack.pop + res10: Int = 2 + scala> stack + res11: scala.collection.mutable.Stack[Int] = Stack(1) + +## ArraySeqs (Изменяемый Последовательные Массивы) + +Последовательные массивы - это изменяемые массивы со свойствами последовательности фиксированного размера, которые хранят свои элементы внутри `Array[Object]`. Они реализованы в Scala классом [ArraySeq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArraySeq.html). + +Вам стоит использовать `ArraySeq`, если вам нужен массив из-за его показателей производительности, но вы дополнительно хотите использовать обобщеные экземпляры последовательности, в которых вы не знаете тип элементов и у которого нет `ClassTag` который будет предоставлен непосредственно во время исполнения. Эти аспекты рассматриваются в разделе [arrays]({% link _ru/overviews/collections-2.13/arrays.md %}). + +## Hash Tables (Хэш Таблицы) + +Хэш-таблица хранит свои элементы в массиве, помещая каждый элемент на ту позицию, которая определяется хэш-кодом этого элемента. Добавление элемента в хэш-таблицу занимает константное время, если в массиве ещё нет другого элемента с таким же хэш-кодом. Таким образом, хэш-таблицы работают очень быстро, до тех пор пока размещенные в них объекты имеют хорошее распределение хэш-кодов. Поэтому в Scala изменяемые мапы и множества основываются на хэш-таблицах. Чтоб получить доступ к ним, можно использовать классы - [mutable.HashSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashSet.html) и [mutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/HashMap.html). + +Хэш-таблицы и хэш-мапы используются так же, как и любая другая мапа или множество. Вот несколько простых примеров: + + scala> val map = scala.collection.mutable.HashMap.empty[Int,String] + map: scala.collection.mutable.HashMap[Int,String] = Map() + scala> map += (1 -> "make a web site") + res42: map.type = Map(1 -> make a web site) + scala> map += (3 -> "profit!") + res43: map.type = Map(1 -> make a web site, 3 -> profit!) + scala> map(1) + res44: String = make a web site + scala> map contains 2 + res46: Boolean = false + +При итерировании по хэш-таблице нет никаких гарантий по поводу порядка обхода. Итерирование проходит по базовому массиву в произвольном порядке. Чтобы получить гарантированный порядок обхода, используйте _связанную_ хэш-мапу (`linked Hashmap`) или множество (`linked Set`) вместо обычной. Связанная хэш-мапа или множество похожи на обычную, за исключением того, что между их элементами есть связь выстроенная в том порядке, в котором эти элементы были добавлены. Поэтому итерирование по такой коллекции всегда происходит в том же порядке, в котором элементы и были добавлены. + +## Weak Hash Maps (Ослабленные Хэш-Мапы) + +Ослабленный хэш-мап это специальный вид хэш-мапы, при которой сборщик мусора не ходит по ссылкам с мапы к её ключам. Это означает, что ключ и связанное с ним значение исчезнут из мапы, если на ключ не будет никаких ссылок. Ослабленные хэш-мапы полезны для таких задач, как кэширование, в которых вы можете переиспользовать результат дорогостоящей функции, сохранив результат функции и вызывая его снова используя тот же аргумент в качестве ключа. Если результаты работы будут хранить на обычной хэш-мапе, мапа будет расти без ограничений и ни один из ключей никогда не будет утилизирован сборщиком мусора. Использование ослабленной хэш-мапы позволяет избежать этой проблемы. Данные из ослабленной хэш-мапы удаляются, как только ключ становится недоступным. Ослабленные хэш-мапы в Scala реализованы классом [WeakHashMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/WeakHashMap.html), который в свою очередь является оберткой над Java `java.util.WeakHashMap`. + +## Concurrent Maps (Конкурентные Мапы) + +Несколько потоков могут получить паралелльный доступ к такой мапе на [конкуретной основе](https://en.wikipedia.org/wiki/Concurrent_data_structure). В дополнение к обычным операциям на [Map](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html) добавленны следующие атомарные операции: + +### Операции на классе concurrent.Map + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| `m.putIfAbsent(k, v)` | Добавляет пару ключа/значение `k -> v`, если `k` отсутствует в `m`. | +| `m.remove(k, v)` |Удаляет запись для `k`, если для этого ключа соответствует значение `v`. | +| `m.replace(k, old, new)` |Заменяет значение, связанное с ключом `k` на `new`, если ранее оно было равно `old`. | +| `m.replace (k, v)` | Заменяет значение, связанное с ключом `k` на `v`, если ранее значение вообще существовало.| + +`concurrent.Map` это трейт в библиотеке коллекций Scala. В настоящее время он реализуется двумя способами. Первый - через Java мапу `java.util.concurrent.ConcurrentMap`, который может быть автоматически преобразован в Scala мапу с помощью [стандартного механизма преобразования Java/Scala коллекций]({% link _ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md %}). Вторая реализация через [TrieMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/concurrent/TrieMap.html), которая представляет из себя не блокируемую хэш-таблицу привязанную к дереву. + +## Mutable Bitsets (Изменяемый Битовый Набор) + +Изменяемый набор типа [mutable.BitSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/BitSet.html) практически такой же, как и неизменяемый набор, за исключением того, что он при изменении сам меняется. Изменяемые битовые наборы немного эффективнее при обновлении, чем неизменяемые, так как им не нужно копировать `Long`, которые не изменились. + + scala> val bits = scala.collection.mutable.BitSet.empty + bits: scala.collection.mutable.BitSet = BitSet() + scala> bits += 1 + res49: bits.type = BitSet(1) + scala> bits += 3 + res50: bits.type = BitSet(1, 3) + scala> bits + res51: scala.collection.mutable.BitSet = BitSet(1, 3) diff --git a/_ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md b/_ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md new file mode 100644 index 0000000000..0320c0c59d --- /dev/null +++ b/_ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md @@ -0,0 +1,59 @@ +--- +layout: multipage-overview +title: Преобразования между Java и Scala коллекциями +partof: collections-213 +overview-name: Collections +num: 17 +previous-page: creating-collections-from-scratch +language: ru +--- + +Как и в Scala, в Java есть богатая библиотека коллекций. Между ними много общего. Например, обе библиотеки предоставляют итераторы, итерируемые сущности, множества, мапы и списки. Но есть и серьезные различия. В частности, библиотека Scala фокусируют больше внимания на неизменяемых коллекциях, предоставляя больше возможностей для преобразования исходной коллекции в новую. + +Иногда вам может понадобиться передать данные из одного фреймворка с коллекциями в другой. Например, вам может понадобиться доступ к существующей коллекции в Java, как если бы это была коллекция Scala. Или вы захотите передать одну из коллекций Scala методу в Java, который ожидает схожую коллекцию из Java. Сделать это довольно просто, потому что Scala предоставляет неявные преобразования всех основных типов коллекций используя [CollectionConverters](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/jdk/CollectionConverters$.html) объект. В частности, вы найдете двухсторннее преобразование между следующими типами: + + Iterator <=> java.util.Iterator + Iterator <=> java.util.Enumeration + Iterable <=> java.lang.Iterable + Iterable <=> java.util.Collection + mutable.Buffer <=> java.util.List + mutable.Set <=> java.util.Set + mutable.Map <=> java.util.Map + mutable.ConcurrentMap <=> java.util.concurrent.ConcurrentMap + +Чтобы задействовать эти неявные преобразования, просто импортируйте объект [CollectionConverters](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/jdk/CollectionConverters$.html) : + + scala> import scala.jdk.CollectionConverters._ + import scala.jdk.CollectionConverters._ + +Это позволит преобразовывать коллекции Scala в соответствующие коллекции Java с помощью методов расширения, называемых `asScala` и `asJava`: + + scala> import collection.mutable._ + import collection.mutable._ + + scala> val jul: java.util.List[Int] = ArrayBuffer(1, 2, 3).asJava + jul: java.util.List[Int] = [1, 2, 3] + + scala> val buf: Seq[Int] = jul.asScala + buf: scala.collection.mutable.Seq[Int] = ArrayBuffer(1, 2, 3) + + scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2).asJava + m: java.util.Map[String,Int] = {abc=1, hello=2} + +Внутри эти преобразования работают путем установки объекта "обертки", который перенаправляет все операции на базовый объект коллекции. Таким образом, коллекции никогда не копируются при конвертировании между Java и Scala. Интересным свойством является то, что если вы выполняете преобразование из типа Java в соответствующий тип Scala и обратно в тот же тип Java, вы получаете идентичный объект коллекции, с которого начали. + +Некоторые коллекции Scala могут быть преобразованы в Java, но не могут быть преобразованы обратно в исходный тип Scala: + + Seq => java.util.List + mutable.Seq => java.util.List + Set => java.util.Set + Map => java.util.Map + +Поскольку Java не различает изменяемые и неизменяемые коллекции по их типам, преобразование из, скажем, `scala.immutable.List` даст результат `java.util.List`, в котором любые операции преобразования кидают исключение "UnsupportedOperationException". Вот пример: + + scala> val jul = List(1, 2, 3).asJava + jul: java.util.List[Int] = [1, 2, 3] + + scala> jul.add(7) + java.lang.UnsupportedOperationException + at java.util.AbstractList.add(AbstractList.java:148) diff --git a/_ru/overviews/collections-2.13/creating-collections-from-scratch.md b/_ru/overviews/collections-2.13/creating-collections-from-scratch.md new file mode 100644 index 0000000000..5956c8e4a2 --- /dev/null +++ b/_ru/overviews/collections-2.13/creating-collections-from-scratch.md @@ -0,0 +1,59 @@ +--- +layout: multipage-overview +title: Создание коллекций с нуля +partof: collections-213 +overview-name: Collections +num: 16 +previous-page: iterators +next-page: conversions-between-java-and-scala-collections +language: ru +--- + +У вас есть синтаксис `List(1, 2, 3)` для создания списка из трех целых чисел и `Map('A' -> 1, 'C' -> 2)` для создания мапы с двумя элементами. На самом деле, это универсальная функциональность коллекций Scala. Можно получить любую коллекцию написав ее название и указав следом список элементов в круглых скобках. В результате получится новая коллекция с заданными элементами. Вот еще несколько примеров: + + Iterable() // Пустая коллекция + List() // Пустой список + List(1.0, 2.0) // Список с элементами 1.0, 2.0 + Vector(1.0, 2.0) // Вектор с элементами 1.0, 2.0 + Iterator(1, 2, 3) // Итератор возвращающий три целых числа. + Set(dog, cat, bird) // Множество с тремя объектами + HashSet(dog, cat, bird) // Хэш-множество с темиже объектами + Map('a' -> 7, 'b' -> 0) // Мапа с привязкой цифр к буквам + +Каждая из вышеперечисленных строк это вызов метода `apply` какого-то объекта. Например, третья строка выше разворачивается следующим образом + + List.apply(1.0, 2.0) + +Так что это вызов метода `apply` объекта-компаньона класса `List`. Этот метод берет произвольное количество аргументов и строит из них список. Каждый класс коллекций библиотеки Scala имеет объект-компаньон с таким `apply` методом. Не имеет значения, является ли класс конкретной реализацией коллекции, такой как `List`, `LazyList`, `Vector`, или это абстрактный базовый класс, такой как `Seq`, `Set` или `Iterable`. В последнем случае вызов `apply` приведет к некой реализации по умолчанию для базового абстрактного класса. Примеры: + + scala> List(1, 2, 3) + res17: List[Int] = List(1, 2, 3) + scala> Iterable(1, 2, 3) + res18: Iterable[Int] = List(1, 2, 3) + scala> mutable.Iterable(1, 2, 3) + res19: scala.collection.mutable.Iterable[Int] = ArrayBuffer(1, 2, 3) + +Помимо `apply`, каждый объект-компаньон коллекции еще определяет элемент `empty`, который возвращает пустую коллекцию. Так что вместо `List()` можно написать `List.empty`, вместо `Map()`, `Map.empty` и так далее. + +Операции, предоставляемые объектом-компаньоном коллекции, обобщены в следующей таблице. Короче говоря. + +* `concat`, которая объединяет произвольное количество коллекций, +* `fill` и `tabulate`, которые генерируют одно- или многомерные коллекции заданных размеров, инициализированные некоторой табулируемой функцией или выражением, +* `range`, которая генерирует целочисленные коллекции с постоянной длиной шага, +* `iterate` и `unfold`, который генерирует коллекцию в результате многократного применения функции к начальному элементу или состоянию. + +### Производящие методы для последовательностей + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| `C.empty` | Пустая коллекция. | +| `C(x, y, z)` | Коллекция состоящая из элементов `x, y, z`. | +| `C.concat(xs, ys, zs)` | Коллекция, полученная путем объединения элементов `xs, ys, zs`. | +| `C.fill(n){e}` | Коллекция длины `n`, где каждый элемент вычисляется выражением `e`. | +| `C.fill(m, n){e}` | Коллекция коллекций размерности `m×n`, где каждый элемент вычисляется выражением `e`. (существует и в более высоких измерениях). | +| `C.tabulate(n){f}` | Коллекция длины `n`, где элемент каждого индекса i вычисляется с помощью `f(i)`. | +| `C.tabulate(m, n){f}` | Коллекция коллекций измерений `m×n`, где элемент каждого индекса `(i, j)` вычисляется с помощью `f(i, j)`. (существует также в более высоких измерениях). | +| `C.range(start, end)` | Коллекция из целых чисел от `start` до `end-1`. | +| `C.range(start, end, step)`| Коллекция целых чисел, начиная со `start` и продвигаясь на шаг `step` увеличиваясь до конечного значения `end` (не включая его самого) . | +| `C.iterate(x, n)(f)` | Коллекция длины `n` с элементами `x`, `f(x)`, `f(f(x))`, ... | +| `C.unfold(init)(f)` | Коллекция, использующая функцию `f` для вычисления следующего элемента и состояния, начиная с начального состояния `init`.| diff --git a/_ru/overviews/collections-2.13/equality.md b/_ru/overviews/collections-2.13/equality.md new file mode 100644 index 0000000000..e05ee5ee73 --- /dev/null +++ b/_ru/overviews/collections-2.13/equality.md @@ -0,0 +1,31 @@ +--- +layout: multipage-overview +title: Равенство +partof: collections-213 +overview-name: Collections +num: 13 +previous-page: performance-characteristics +next-page: views +language: ru +--- + +Коллекции придерживаются единого подхода к определению равенства и получению хэшей. Идея состоит, во-первых, в том, чтобы разделить коллекции на группы: множества, мапы и последовательности. Коллекции в разных группах всегда различаются. Например, `Set(1,2,3)` неравнозначен списку `List(1,2,3)`, хотя они содержат одни и те же элементы. С другой стороны, в рамках одной и той же группы коллекции равны тогда и только тогда, когда они имеют одинаковые элементы (для последовательностей: одни и те же элементы в одном порядке). Например `List(1, 2, 3) == Vector(1, 2, 3)`, и `HashSet(1, 2) == TreeSet(2, 1)`. + +Для проверки на равенство не важно, является ли коллекция изменяемой или неизменяемой. Для изменяемой коллекции достаточно просто рассмотреть ее текущие элементы на момент проведения проверки на равенство. Это означает, что коллекция в разные моменты может быть эквивалентна разным коллекциям, в зависимости от того, какие элементы в неё добавляются или удаляются. В этом кроится потенциальная опасность при использовании изменяемой коллекции в качестве ключа для хэшмапы. Пример: + + scala> import collection.mutable.{HashMap, ArrayBuffer} + import collection.mutable.{HashMap, ArrayBuffer} + scala> val buf = ArrayBuffer(1, 2, 3) + buf: scala.collection.mutable.ArrayBuffer[Int] = + ArrayBuffer(1, 2, 3) + scala> val map = HashMap(buf -> 3) + map: scala.collection.mutable.HashMap[scala.collection. + mutable.ArrayBuffer[Int],Int] = Map((ArrayBuffer(1, 2, 3),3)) + scala> map(buf) + res13: Int = 3 + scala> buf(0) += 1 + scala> map(buf) + java.util.NoSuchElementException: key not found: + ArrayBuffer(2, 2, 3) + +В этом примере запрос в последней строке, скорее всего, не сработает, так как хэш-код массива `buf` изменился во второй с конца строке. Таким образом, в поиске элемента на основе хэша, будет запрашиваться совсем другой элемент, чем тот что был первоначально сохранен в `map`. diff --git a/_ru/overviews/collections-2.13/introduction.md b/_ru/overviews/collections-2.13/introduction.md new file mode 100644 index 0000000000..e97c142eb8 --- /dev/null +++ b/_ru/overviews/collections-2.13/introduction.md @@ -0,0 +1,61 @@ +--- +layout: multipage-overview +title: Введение +partof: collections-213 +overview-name: Collections +num: 1 +next-page: overview +language: ru +--- + +**Martin Odersky и Lex Spoon** + +Фреймворк коллекций является основой стандартной библиотеки Scala 2.13. Он обеспечивает общие схемы и подходы распостроняемые на все типы коллекций. +Этот фреймворк позволяет вам работать с данными на высоком уровне абстракции, в котором основными строительным блоком программы становятся коллекцкии целиком, а не её отдельные элементы. + +К такому стилю программирования необходимо небольшое привыкание. +К счастью, адаптация облегчается приятными свойствами характерными для новых коллекций Scala. +Они обладают простотой в использовании, лаконичностью, безопасностью и универсальностью. + +**Простота:** Небольшого набора из 20-50 методов достаточно для решения большинства задач. +Нет необходимости использовать запутанные циклы или рекурсии. +Персистентные коллекции и операции без побочных эффектов означают, +что вам не нужно беспокоиться о случайном повреждении существующих коллекций новыми данными. +Больше нет путаницы из-за использования итераторов и одновременного изменения коллекций. + +**Лаконичность:** Одной командой можно достичь, столько же, сколько обычно получают используя несколько вложенных операций с циклами. +Вы можете выразить функциональные операции с помощью простого синтаксиса и с легкостью сочетать операции, создавая ощущение +работы со специализированным под задачу языком. + +**Безопасность:** Требуется определенный опыт, чтоб погрузится в эту специфику. +Статически типизированная и функциональная природа коллекций Scala подразумевает, что подавляющее большинство ошибок, которые вы можете совершить, будут пойманы во время компиляции. +Это потому что: + 1. Коллекции сами по себе очень активно используются, поэтому хорошо протестированы. + 2. Использование операции в коллекциях создает явное описание того, что мы ожидаем для входящих данных и для результата. + 3. Это явное описание для входа и результата подвергается статической проверке типа. В результате подавляющее большинство проблем будет проявляться в виде ошибок типов. +Поэтому запуск программ из нескольких сотен строк, с первого раза, вполне типичная ситуация. + + +**Скорость:** Все операции в коллекциях уже настроены и оптимизированы. В результате, работа коллекций получается очень эффективной. +Можно конечно сделать немного более эффективную настройку структур данных и операций с ними, но при этом, +вероятно, вы получите хуже эффективность в непосредственной реализации и использовании. +Кроме того, коллекции оптимизированы для параллельного исполнения на нескольких ядрах. Параллельные коллекции поддерживают те же операции, что и последовательные, поэтому нет необходимости в изучении новых операций или переписывании кода. +Вы можете превратить последовательную коллекцию в параллельную просто вызвав метод `par`. + +**Универсальность:** Коллекции обеспечивают одинаковые операции на любом типе коллекций, где это имеет смысл. Таким образом, можно достичь многого, имея сравнительно небольшой набор операций. Например строка, в принципе, представляет собой последовательность символов. Следовательно, в коллекциях Scala строки поддерживают все операции которые есть у последовательностей (`Seq`). То же самое относится и к массивам. + +**Пример:** Вот лишь одна строчка кода, демонстрирующая преимущества Scala коллекций. + + val (minors, adults) = people partition (_.age < 18) + +Сразу становится понятно, что делает эта строчка: она разделяет коллекцию людей `people` на несовершеннолетних `minors` и взрослых `adults` в зависимости от возраста `age`. +Поскольку метод `partition` определен в базовом типе коллекции `TraversableLike`, этот код работает для любого типа коллекций, включая массивы. +Полученные в результате коллекции `minors` и `adults` будут иметь тот же тип, что и коллекция `people` . + +Этот код намного лаконичнее, чем несколько циклов, необходимых для того, чтоб провести обработку традиционным методом +(три цикла для массива, т.к. промежуточные результаты должны быть сохранены где-то в другом месте). +Как только вы освоите базовую схему работы с коллекциями, вы оцените на сколько проще и безопаснее написание такого кода, в отличии от более низкоуровневого кода с циклами. +Кроме того, сама операция `partition` работает довольно быстро и будет работать еще быстрее на многоядерных процессорах при использовании параллельных коллекций. (Параллельные коллекции стали частью Scala начиная с версии 2.9.) + +В этом разделе подробно рассматриваются API классов коллекций Scala с пользовательской точки зрения. +Вы также познакомитесь со всеми фундаментальными классами и методами, которые есть у коллекций. diff --git a/_ru/overviews/collections-2.13/iterators.md b/_ru/overviews/collections-2.13/iterators.md new file mode 100644 index 0000000000..3d43d76a8f --- /dev/null +++ b/_ru/overviews/collections-2.13/iterators.md @@ -0,0 +1,233 @@ +--- +layout: multipage-overview +title: Итераторы +partof: collections-213 +overview-name: Collections +num: 15 +previous-page: views +next-page: creating-collections-from-scratch +language: ru +--- + +Итератор (Iterator) - это не коллекция, а скорее способ поочередного доступа к элементам коллекции. Есть две основные операции у итератора - это `next` и `hasNext`. Вызов метода `it.next()` на итераторе `it` вернет следующий элемент и изменит его состояние. Повторный вызов `next` на том же итераторе выведит следующий элемент идущий после ранее возвращённого. Если больше нет элементов для возврата, вызов команды `next` кинет исключение `NoSuchElementException`. Вы можете узнать, есть ли еще элементы для возврата с помощью метода `hasNext` у [Итератора](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html). + +Самый простой способ "обойти" все элементы, возвращаемые итератором `it` - это использование циклов с while-loop: + + while (it.hasNext) + println(it.next()) + +У итераторов в Scala есть аналоги большинству методов, которые вы можете найдти в классах `Traversable`, `Iterable` и `Seq`. Например, метод "foreach", который на итераторе выполняет процедуру на каждом элементе, возвращаемого итератором. Используя `foreach`, описанный выше цикл можно сократить до: + + it foreach println + +Как всегда, "for выражения" могут быть использованы в качестве альтернативного синтаксиса для выражений, включающих в себя `foreach`, `map`, ` WithFilter` и `flatMap`, поэтому еще одним способом вывести все элементы, возвращаемые итератором, будет: + + for (elem <- it) println(elem) + +Существует важное различие между методом foreach на итераторах и тем же методом на _traversable_ коллекциях: При вызове метода `foreach` на итераторе, итератор остается в конце, указывая что все элементы закончились. Поэтому очередной вызов `next` на томже самом итераторе выбросит исключение `NoSuchElementException`. В отличие от этого, при обращении к коллекции, команда `foreach` оставляет количество элементов в коллекции неизменным (если только переданная функция не добавляет элементов, но это крайне не желательно, так как может привести к неожиданным результатам). + +Другие общие операции между `Iterator` и `Iterable`, имеют одни и те же свойства. Например, итераторы предоставляют метод `map`, который возвращает новый итератор: + + scala> val it = Iterator("a", "number", "of", "words") + it: Iterator[java.lang.String] = + scala> it.map(_.length) + res1: Iterator[Int] = + scala> it.hasNext + res2: Boolean = true + scala> res1 foreach println + 1 + 6 + 2 + 5 + scala> it.hasNext + res4: Boolean = false + +Как видите, после вызова функции `it.map` итератор `it` не остановился в конце, в отличии от `res1.foreach` который проходит через весь итератор, после чего `it` остается в самом конце. + +Другой пример - метод `dropWhile`, который можно использовать для поиска первых элементов итератора, соответствующих условию. Например, чтобы найти первое слово в итераторе выше, которое содержит хотя бы два символа, можно было бы написать: + + scala> val it = Iterator("a", "number", "of", "words") + it: Iterator[java.lang.String] = + scala> it dropWhile (_.length < 2) + res4: Iterator[java.lang.String] = + scala> res4.next() + res5: java.lang.String = number + +Обратите внимание еще раз, что сам итератор`it` был изменен вызовом `dropWhile`: теперь он указывает на второе слово `number` в списке. +Фактически, `it` и результат `res4` возвращаемый после`dropWhile` возвращают одну и туже последовательность элементов. + +Чтобы избежать такое поведение, как вариант можно использовать `duplicate` (дублировать используемый итератор), вызывая методы на разных итераторах. +Каждый из _двух_ итераторов будет обрабатывать точно такие же элементы, как и тот, из которого состоит итераторатор `it`: + + scala> val (words, ns) = Iterator("a", "number", "of", "words").duplicate + words: Iterator[String] = + ns: Iterator[String] = + + scala> val shorts = words.filter(_.length < 3).toList + shorts: List[String] = List(a, of) + + scala> val count = ns.map(_.length).sum + count: Int = 14 + +Оба итератора работают независимо друг от друга: продвижение одного не влияет на другого, так что каждый из них может быть модифицирован независимо от другого. +Может создаться впечатление что итератор подвергается двойному обходу над элементами, но это не так, результат достигается за счет внутреннего буферизации. +Как обычно, базовый итератор `it` не пригоден для прямого использования и должен быть исключен из дальнейших операций. + +Обобщая вышесказанное, итераторы ведут себя как коллекции, _если после вызова метода на них сам итератор больше не вызывается_. В библиотеке коллекции Scala это достигается явным образом с помощью абстракции [IterableOnce](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IterableOnce.html), который является общим суперкласом для [Iterable](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) и [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html). У `IterableOnce[A]` только два метода: `iterator: Iterator[A]` и `knownSize: Int`. + +Если объект `IterableOnce` является `Iterator`, то его операция `iterator` всегда возвращает себя, в своем текущем состоянии, но если он `Iterable`, то операция `iterator` всегда возвращает новый `Iterator`. Типовой вариант использования `IterableOnce` - в качестве типа аргумента для методов, которые могут принимать или итератор или коллекцию в качестве аргумента. Примером может служить метод соединения `concat` в классе `Iterable`. Он принимает `IterableOnce` параметр, поэтому вы можете соединять элементы, поступающие или из итератора или коллекции. + +Все операции на итераторах собраны в таблице ниже. + +### Операции на классе Iterator + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Абстрактные Методы:** | | +| `it.next()` | Возвращает следующий элемент итератора переводя его _позицию_ на следующее место. | +| `it.hasNext` | Возвращает `true` если итератор `it` может выдать следующий элемент. | +| **Варьирования:** | | +| `it.buffered` | Буффиризированный итератор возвращающий все элементы `it`. | +| `it grouped size` | Итератор, который производит элементы от `it` в последовательностях фиксированного размера ("чанках"). | +| `it sliding size` | Итератор, который производит элементы от `it` в последовательностях полученных от прохождения окна фиксированного размера над элементами итератора. | +| **Дублирования:** | | +| `it.duplicate` | Пара итераторов, каждый из которых может независимо возвращать все элементы `it`. | +| **Сложения:** | | +| `it concat jt`
            либо `it ++ jt` | Итератор, возвращающий все элементы, от итератора `it`, за которым следуют все элементы, возвращаемые итератором `jt`. | +| `it.padTo(len, x)` | Итератор, который в начале возвращает все элементы `it` а затем следуют копии `x` пока не будет достигнута длина `len`. | +| **Отображения:** | | +| `it map f` | Итератор, получаемый при применении функции `f` к каждому элементу, возвращаемому из `it`. | +| `it flatMap f` | Итератор, получаемый при применении производящей итераторы функции `f` к каждому элементу `it` с последующим объединением результатов. | +| `it collect f` | Итератор, получаемый при применении частично определенной функции `f` к каждому элементу `it` для которого она определена с последующим сбором результатов. | +| **Преобразования:** | | +| `it.toArray` | Собирает элементы, полученные от `it` в массив. | +| `it.toList` | Собирает элементы, полученные от `it` в список. | +| `it.toIterable` | Собирает элементы, полученные от `it` в итерируемую сущность. | +| `it.toSeq` | Собирает элементы, полученные от `it` в последовательность. | +| `it.toIndexedSeq` | Собирает элементы, полученные от `it` в индексируюмую последовательность. | +| `it.toLazyList` | Собирает элементы, полученные от `it` в ленивый лист. | +| `it.toSet` | Собирает элементы, полученные от `it` во множество. | +| `it.toMap` | Собирает пары ключ/значение, полученные от `it` в мапу. | +| **Копирования:** | | +| `it.copyToArray(arr, s, n)`| Копирует максимум `n` элементов, возвращаемых `it` в массив `arr`, начиная с индекса `s`. Два последних аргумента необязательные.| +| **Иформации о размере:** | | +| `it.isEmpty` | Проверяет, пуст ли итератор ( в противоположность `hasNext` ). | +| `it.nonEmpty` | Проверяет, содержит ли коллекция элементы (псевдоним для `hasNext`). | +| `it.size` | Выдает количество элементов итератора `it`. Примечание: после этой операции `it` будет находится в конце! | +| `it.length` | Тоже что и `it.size`. | +| `it.knownSize` |Выдает количество элементов итератора, если их можно узнать без изменения состояния итератора, иначе `-1`. | +| **Поиск и получение элементов:**| | +| `it find p` | Опшен возвращаемый из `it`, содержащий первый элемент, который удовлетворяет условию `p`, или `None`, если ни один из элементов не подходит. Примечание: итератор находится на следующем после найденного элемента или в конце, если ни одного не найдено. | +| `it indexOf x` | Индекс первого элемента, возвращаемого `it`, который равен `x`. Примечание: итератор перемещается в позицию после найденого элемента. | +| `it indexWhere p` | Индекс первого элемента, возвращаемого `it`, который удовлетворяет условию `p`. Примечание: итератор перемещается в позицию после этого элемента. | +| **Дочернии итераторы:** | | +| `it take n` | Итератор, возвращающий первые `n` элементов `it`. Примечание: он переместится в позицию после `n` элемента, или в конец, если содержит меньше, чем `n` элементов.| +| `it drop n` | Итератор, который начинается с `(n+1)` элемента `it`. Примечание: `it` переместится в ту же самую позицию. | +| `it.slice(m,n)` | Итератор, возвращающий фрагмент элементов из `it`, начиная с `m` элемента и заканчивая перед `n` элементом. | +| `it takeWhile p` | Итератор, возвращающий элементы из `it` до тех пор, пока условие `p` истинно. | +| `it dropWhile p` | Итератор пропускает элементы из `it` до тех пор, пока условие `p` является истинным, после чего возвращает остаток.| +| `it filter p` | Итератор, возвращающий все элементы из `it`, удовлетворяющие условию `p`. | +| `it withFilter p` | То же самое, что и `it filter p`. Требуется для возможности использовать итераторы в _for-выражениях_. | +| `it filterNot p` | Итератор, возвращающий все элементы из `it`, которые не удовлетворяют условию `p`. | +| `it.distinct` | Итератор, возвращающий элементы из `it` без дубликатов. | +| **ПодГруппы:** | | +| `it partition p` | Разделяет `it` на пару из двух итераторов: один возвращает все элементы из `it`, которые удовлетворяют предикату `p`, а другой возвращает все элементы из `it`, которые не удовлетворяют. | +| `it span p` | Разделяет `it` на пару из двух итераторов: один возвращает все начальные элементы `it`, удовлетворяющие предикату `p`, а другой возвращает все остальные элементы `it`. | +| **Сведения об элементах:** | | +| `it forall p` | Логический показатель, указывающий, все ли элементы из `it` соответствуют условию `p`. | +| `it exists p` | Логический показатель, указывающий, есть ли хоть один элемент из `it`, который соответствует условию `p`. | +| `it count p` | Возвращает количество элементов из `it`, удовлетворяющих предикату `p`.| +| **Свертки:** | | +| `it.foldLeft(z)(op)` | Применяет двустороннюю операцию `op` между последовательно идущими элементами, возвращаемыми итератором `it`, слева направо и начинающимися с `z`. | +| `it.foldRight(z)(op)` | Применяет двустороннюю операцию `op` между последовательно идущими элементами, возвращаемыми итератором `it`, справа налево и начинающимися с `z`. | +| `it reduceLeft op` | Применяет двустороннюю операцию `op` между последовательно идущими элементами, возвращаемыми итератором `it`, идущие слева направо. | +| `it reduceRight op` | Применяет двустороннюю операцию `op` между последовательно идущими элементами, возвращаемыми итератором `it`, идущие справа налево. | +| **Специальные Свертки:** | | +| `it.sum` | Сумма значений числовых элементов, возвращаемых итератором `it`. | +| `it.product` | Произведение значений числовых элементов, возвращаемых итератором `it`. | +| `it.min` | Минимальное из значений элементов у которых есть порядок, возвращаемых итератором `it`. | +| `it.max` | Максимальное из значений элементов у которых есть порядок, возвращаемых итератором `it`. | +| **Связывания:** | | +| `it zip jt` | Итератор состоящий из пар соответствующих элементов, возвращаемых итераторами `it` и `jt` | +| `it.zipAll(jt, x, y)` | Итератор состоящий из пар соответствующих элементов, возвращаемых итераторами `it` и `jt` , где более короткий итератор расширяется, чтобы соответствовать более длинному, добавляя элементы `x` или `y`. | +| `it.zipWithIndex` | Итератор состоящий из пар элементов итератора `it` и его индекса | +| **Обновления:** | | +| `it.patch(i, jt, r)` | Итератор, получаемый из `it`, заменив `r` элементов, начиная с `i` на итератор `jt`. | +| **Сравнения:** | | +| `it sameElements jt` | Проверяет, возвращают ли итераторы `it` и `jt` одни и те же элементы в одном и том же порядке. Примечание: Использование итераторов после этой операции не определено и может быть изменено в дальнейшем. | +| **Строковые:** | | +| `it.addString(b, start, sep, end)`| Добавляет строку в `StringBuilder` `b`, который выводит все элементы `it` через разделитель `sep`, заключенный между строками `start` и `end`. `start`, `sep`, `end` - необязательные параметры.| +| `it.mkString(start, sep, end)` | Преобразует коллекцию в строку, которая выводит все элементы `it` через разделитель `sep`, заключенный между строками `start` и `end`. `start`, `sep`, `end` - необязательные параметры.| + +### Ленивость + +В отличие от операций непосредственно на конкретных коллекциях типа `List`, операции на `Iterator` ленивы. + +Ленивая операция не сразу вычисляет результаты. Вместо этого она рассчитывает результаты тогда когда они непосредственно запрашиваются. + +Поэтому выражение `(1 to 10).iterator.map(println)` не выведет ничего на экран. +Метод `map` в данном случае не применяет функцию в аргументе к значениям в диапазоне, вместо этого будет возвращен новый `Iterator`, который будет выполнять операции тогда когда будет запрошен их результат. Добавление `.toList` в конец этого выражения фактически вызовет вывод элементов на печать. + +Как следствие, такие методы как `map` или `filter` не обязательно применят функцию в аргументе ко всем входным элементам. Выражение `(1 to 10).iterator.map(println).take(5).toList` выводит только значения от `1` до `5`, поскольку это те значения, которые запрашиваются у `Iterator`, возвращаемого из `map`. + +Это одна из причин, того почему важно использовать только чистые функции в качестве аргументов для `map`, `filter`, `fold` и подобных методов. Помните, что чистая функция не имеет побочных эффектов, поэтому `println` обычно не используется в `map`. Здесь `println` используется лишь для демонстрации "ленивости", которую с чистыми функциями не заметно. + +Ленивость ценна, несмотря на то, что часто невидима, так как она может предотвратить ненужные вычисления и позволить работать с бесконечными последовательностями, как в следующем примере: + + def zipWithIndex[A](i: Iterator[A]): Iterator[(Int, A)] = + Iterator.from(0).zip(i) + +### Буферезированные итераторы + +Иногда вам нужен итератор, который может "заглянуть вперед", чтобы вы могли оценить следующий элемент, который будет возвращен без перемещения позиции. Рассмотрим, например, задачу пропуска впереди идущих пустых строк из итератора, который возвращает последовательность строк. У вас может возникнуть соблазн написать следующее + + + def skipEmptyWordsNOT(it: Iterator[String]) = + while (it.next().isEmpty) {} + +Но если присмотреться к этому коду внимательнее, то становится понятно, что такой код не корректен: код действительно пропустит ведущие пустые строки, но он также пропустит первую непустую строку `it`! + +Решение этой проблемы заключается в использовании буферизированного итератора. Класс [BufferedIterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/BufferedIterator.html) базирующийся на классе [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html) предоставляет один дополнительный метод, `head`. Вызов `head` на буферизированном итераторе вернет его первый элемент, но не продвинет итератор дальше. С помощью буферизированного итератора можно пропустить пустые слова следующим образом. + + def skipEmptyWords(it: BufferedIterator[String]) = + while (it.head.isEmpty) { it.next() } + +Каждый итератор может быть преобразован в буферизированный после вызова метода `buffered`. Например: + + scala> val it = Iterator(1, 2, 3, 4) + it: Iterator[Int] = + scala> val bit = it.buffered + bit: scala.collection.BufferedIterator[Int] = + scala> bit.head + res10: Int = 1 + scala> bit.next() + res11: Int = 1 + scala> bit.next() + res12: Int = 2 + scala> bit.headOption + res13: Option[Int] = Some(3) + +Обратите внимание, что вызов метода `head` на буферизированном итераторе `bit` не продвигает его вперед. Поэтому последующий вызов `bit.next()` возвращает то же значение, что и `bit.head`. + +Как обычно, базовый итератор не должен в дальнейшем использоваться напрямую и должен быть исключен из операций. + +Буферизированный итератор буферизирует только следующий элемент, когда вызывается `head`. Другие производные итераторы, например произведенные от вызова `duplicate` и `partition`, могут буферизировать любое количество подпоследовательностей дочерних итераторов. Впрочем, итераторы могут быть эффективно объединены используя метод `++`: + + scala> def collapse(it: Iterator[Int]) = if (!it.hasNext) Iterator.empty else { + | var head = it.next + | val rest = if (head == 0) it.dropWhile(_ == 0) else it + | Iterator.single(head) ++ rest + | } + collapse: (it: Iterator[Int])Iterator[Int] + + scala> def collapse(it: Iterator[Int]) = { + | val (zeros, rest) = it.span(_ == 0) + | zeros.take(1) ++ rest + | } + collapse: (it: Iterator[Int])Iterator[Int] + + scala> collapse(Iterator(0, 0, 0, 1, 2, 3, 4)).toList + res14: List[Int] = List(0, 1, 2, 3, 4) + +В первой версии, любые встречаемые нули сбрасываются, а затем строится требуемый результат как объединенный итератор, который в свою очередь просто вызывает два входящих в него итератора. +Во втором варианте `collapse` неиспользованные нули буферизируются внутри. diff --git a/_ru/overviews/collections-2.13/maps.md b/_ru/overviews/collections-2.13/maps.md new file mode 100644 index 0000000000..a3d93834fd --- /dev/null +++ b/_ru/overviews/collections-2.13/maps.md @@ -0,0 +1,111 @@ +--- +layout: multipage-overview +title: Мапы +partof: collections-213 +overview-name: Collections +num: 7 +previous-page: sets +next-page: concrete-immutable-collection-classes +language: ru +--- + +[Map](https://www.scala-lang.org/api/current/scala/collection/Map.html) это [Iterable](https://www.scala-lang.org/api/current/scala/collection/Iterable.html) состоящее из пар ключ значение (также называемых _связкой_ или _ассоциативным массивом_). +Scala Объект [Predef](https://www.scala-lang.org/api/current/scala/Predef$.html) предоставляет неявное преобразование, позволяющее записать пару `(ключ, значение)` используя альтернативный синтаксис вида `ключ -> значение` . Например, `Map("x" -> 24, "y" -> 25, "z" -> 26)` означает тоже самое что и `Map(("x", 24), ("y", 25), ("z", 26))`, но читается лучше. + +Основные операции на мапах аналогичны темже операциям на множества. Рассмотрим в следующей таблице обобщеный и сгруппированный по категориям список методов на мапах: + +* **Запросы** операции `apply`, `get`, `getOrElse`, `contains`, и `isDefinedAt`. Они превращают мапы в частично определенные функции от ключей к значениям. Основной "запросный метод" на мапах это : `def get(key): Option[Value]`. Операция "`m get key`" проверяет содержит ли мапа связанное значение для ключа `key`. Если да, то возвращает это связанное значение обернутое в `Some`. Если же нет, то `get` возвращает `None`. На мапах еще определен метод `apply`, которое напрямую возвращает связанное с заданным ключем значение, без оборачивания его в `Option`. В этом случае, когда ключ не определен, будет брошено исключение. +* **Добавление и обновления** `+`, `++`, `updated`, которые позволяют добавлять новые пары к мапам или изменять существующие. +* **Удаления** `-`, `--`, которые позволяют удалять пары из мап. +* **Создание подколлеций** `keys`, `keySet`, `keysIterator`, `values`, `valuesIterator`, которые возвращают ключи и значения мап отдельно в различных формах. +* **Трансформации** `filterKeys` и `mapValues`, которые создают новую мапу через фильтрацию и преобразования элементов существующей мапы. + +### Операции на Классе Map ### + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Запросы:** | | +| `ms get k` |Возвращает значение связанное с ключом `k` в мапе `ms` обернутое в опшен, `None` если значение не найдено.| +| `ms(k)` |(либо эквивалент `ms apply k`) Возвращает напрямую значение, связанное с ключом `k` на мапе `ms`, или исключение, если оно не найдено.| +| `ms getOrElse (k, d)` |Значение, связанное с ключом `k` на мапе `ms`, или значением по умолчанию `d`, если не найдено.| +| `ms contains k` |Проверяет, содержит ли `ms` значение для ключа `k`.| +| `ms isDefinedAt k` |Тоже самое что и `contains`. | +| **Подколлекции:** | | +| `ms.keys` |Итерируемая коллекция, содержащая каждый ключ из мапы `ms`. | +| `ms.keySet` |Множество, содержащее каждый ключ из `ms`. | +| `ms.keysIterator` |Итератор, выдающий каждый ключ из `ms`. | +| `ms.values` |Итерируемая коллекция, содержащая каждое значение, связанное с ключом из `ms`.| +| `ms.valuesIterator` |Итератор, выдающий каждое значение, связанное с ключом из `ms`.| +| **Преобразования:** | | +| `ms.view filterKeys p` |Отображение мапы, содержащее только те пары из `ms`, в которых ключ удовлетворяет предикату `p`.| +| `ms.view mapValues f` |Представление мапы `ms` к значениям которой применена функция `f`. | + +Неизменяемые мапы поддерживают операции добавления и удаления элементов через возврат новых `Мап`ов, как описано в следующей таблице. + +### Операции на Классе immutable.Map ### + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Добавления и обновления:**| | +| `ms.updated(k, v)`
            или `ms + (k -> v)` |Мапа, содержащая все пары из `ms`, а также ассоциативную связь `k -> v` от ключа `k` к значению `v`.| +| **Удаления:** | | +| `ms remove k`
            или `ms - k` |Мапа, содержащая все пары `ms` за исключением пары с ключом `k`.| +| `ms removeAll ks`
            или `ms -- ks` | Мапа, содержащая все пары из `ms` за исключением пары с ключом из `ks`.| + +Изменяемые мапы поддерживают дополнительные операции, которые представленным в таблице ниже. + + +### Операции на Классе mutable.Map ### + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Добавления и обновления:** | | +| `ms(k) = v` |(либо эквивалент `ms.update(x, v)`). Добавляет связь от ключа `k` к значению `v` в мапе `ms` через побочный эффект, перезаписывая любую предыдущую связь с `k`.| +| `ms.addOne(k -> v)`
            либо `ms += (k -> v)` |Добавляет связь от ключа `k` к значению `v` в мапе `ms` через побочный эффект и возвращает сам `ms`.| +| `ms addAll xvs`
            либо `ms ++= kvs` |Добавляет все пары из `kvs` к `ms` через побочный эффект и возвращает сам `ms`.| +| `ms.put(k, v)` |Добавляет связь от ключа `k` к значению `v` в мапе `ms` и возвращает любое значение, которое было ранее связанно с `k` (опционально).| +| `ms getOrElseUpdate (k, d)`|Если ключ `k` определен на мапе `ms`, возвращает связанное с ним значение. В противном случае добавляет к `ms` связь вида `k -> d` и возвращает `d`.| +| **Удаления:**| | +| `ms subtractOne k`
            либо `ms -= k` |Удаляет ассоциированную связь с ключом `k` из мапы `ms` побочным эффектом и возвращает сам `ms`.| +| `ms subtractAll ks`
            либо `ms --= ks` |Удаляет все пары связанные с ключами `ks` из мапы `ms` побочным эффектом и возвращает сам `ms`.| +| `ms remove k` |Удаляет любую пару связанную с ключом `k` из `ms` и возвращает значение, которое ранее было связанное с `k` (опционально).| +| `ms filterInPlace p` |Оставляет только те пары в мапе `ms`, у которых ключ, удовлетворяет предикату `p`.| +| `ms.clear()` |Удаляет все пары из мапы `ms` | +| **Преобразования:** | | +| `ms mapValuesInPlace f` |Преобразует все значения в мапе `ms` используя функцию `f`. | +| **Клонирования:** | | +| `ms.clone` |Возвращает новую изменяемую мапу с теми же парами, что и у `ms`.| + +Операции добавления и удаления в мапах совпадают с операциями добавления и удаления у множеств. Изменяемая мапа `m` обычно обновляется через замену значений в самой себе, используя два варианта синтаксиса `m(key) = value` или `m += (key -> value)`. Существует также вариант `m.put(key, value)`, который возвращает `Option`, содержащее значение, ранее связанного с `key`, или `None`, если `key` не было в мапе. + +Функция `getOrElseUpdate` полезна для доступа к мапам, работающим в качестве кэша. Допустим, у вас есть дорогая для вычисления операция, вызываемая функцией `f`: + + scala> def f(x: String) = { + println("taking my time."); sleep(100) + x.reverse } + f: (x: String)String + +Допустим, что `f` без побочных эффектов, поэтому повторное обращение к функции с тем же аргументом всегда будет давать один и тот же результат. В этом случае можно сэкономить время, сохранив ранее вычисленное выражение связав аргумент с результатом `f` на мапе и вычислять `f` только в том случае, если результат для аргумента не находится в мапе. Можно сказать, что мапа представляет собой _кэш_ для вычислений функции `f`. + + scala> val cache = collection.mutable.Map[String, String]() + cache: scala.collection.mutable.Map[String,String] = Map() + +Теперь вы можете создать более эффективную кэшированную версию функции `f`: + + scala> def cachedF(s: String) = cache.getOrElseUpdate(s, f(s)) + cachedF: (s: String)String + scala> cachedF("abc") + taking my time. + res3: String = cba + scala> cachedF("abc") + res4: String = cba + +Обратите внимание, что второй аргумент для `getOrElseUpdate` вызывается "по имени", поэтому вычисление `f("abc")` производится только если `getOrElseUpdate` запросит значения второго аргумента, точнее если его первый аргумент не найден в мапе `cache`. Вы могли бы реализовать `cachedF` самостоятельно, используя только базовые операции с мапами, но для этого понадобилось бы больше кода: + + def cachedF(arg: String) = cache get arg match { + case Some(result) => result + case None => + val result = f(x) + cache(arg) = result + result + } diff --git a/_ru/overviews/collections-2.13/overview.md b/_ru/overviews/collections-2.13/overview.md new file mode 100644 index 0000000000..c9205aeded --- /dev/null +++ b/_ru/overviews/collections-2.13/overview.md @@ -0,0 +1,102 @@ +--- +layout: multipage-overview +title: Изменяемые и Неизменяемые Коллекции +partof: collections-213 +overview-name: Collections +num: 2 +previous-page: introduction +next-page: trait-iterable +language: ru +--- + +В коллекциях Scala постоянно проводят различие между неизменяемыми и изменяемыми коллекциями. _Изменяемые_ (mutable) коллекции могут быть изменены или дополнены. Это означает, что вы можете изменять, добавлять или удалять её элементы. _Неизменяемые_ (Immutable) коллекции, напротив, никогда не меняются. У них есть операции, имитирующие добавления, удаления или обновления, но эти операции каждый раз будут возвращать новую коллекцию и оставлять старую коллекцию без изменений. + +Все варианты коллекции находятся в пакете `scala.collection` либо в одном из его подпакетов `mutable` или `immutable`. Большинство коллекции, которые необходимы для работы с клиентским кодом, существуют в трех вариантах, +те которые находятся в пакетах `scala.collection`, `scala.collection.immutable` или `scala collection.mutable`. У каждого варианта свои особенности в работе, связанные с разным подходом к обработке изменений. + +Каждая коллекция в пакете `scala.collection.immutable` гарантированно будет неизменяемой. Такая коллекция никогда не изменится после ее создания. Поэтому, вы, можете положиться на факт того, что повторный доступ к значениям коллекции в любой момент времени приведет к одному и томуже результату. + +Известно, что у коллекции в пакете `scala.collection.mutable` есть операции, которые изменяют саму коллекцию. Поэтому, работая с изменяемой коллекцией вам нужно четко понимать, где и когда в нее вносятся изменения. + +Коллекция в пакете `scala.collection` может быть как изменяемой, так и неизменяемой. +Например, [collection.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IndexedSeq.html) +является _базовой_ для обоих коллекций [collection.immutable.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/IndexedSeq.html) +и +[collection.mutable.IndexedSeq\[T\]](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/IndexedSeq.html) +Как правило, базовые коллекции пакета `scala.collection` поддерживают операции преобразования, затрагивающие всю коллекцию, неизменяемые коллекции пакета `scala.collection.immutable` обычно добавляют операции добавления или удаления отдельных элементов, а изменяемые коллекции пакета `scala.collection.mutable` обычно добавляют к базовому интерфейсу операции модификации элементов, основанные на побочных эффектах. + +Еще одним отличием базовой коллекции от неизменяемой является то, что пользователи неизменяемой коллекции имеют гарантию, что никто не сможет изменить коллекцию, а пользователи базовой коллекции лишь обещают не менять ее самостоятельно. Даже если тип такой коллекции не предоставляет никаких операций для модификации коллекции, все равно возможно, что эта коллекция, может быть изменена какими-либо сторонними пользователями. + +По умолчанию Scala всегда выбирает неизменяемые коллекции. Например, если вы просто пишете `Set` без префикса или импортируете `Set` откуда-то, вы получаете неизменяемый Set, а если вы пишете `Iterable` - получите неизменяемую Iterable коллекцию, потому что такие связки прописаны по умолчанию, в пакете`scala`. Чтобы получить изменяемую версию необходимо явно написать `collection.mutable.Set` или `collection.mutable.Iterable`. + +Полезное соглашение, если вы хотите использовать как изменяемую, так и неизменяемую версию коллекций - импортируйте только пакет `collection.mutable`. + + import scala.collection.mutable + +Тогда указание типа `Set` без префикса по-прежнему будет относиться к неизменяемой коллекции, в то время как `mutable.Set` буде относиться к переменному аналогу. + +Последним пакетом в иерархии коллекций является `scala.collection.generic`. Этот пакет содержит строительные элементы для абстрагирования поверх конкретных коллекций. + +Для удобства и обратной совместимости некоторые важные типы имеют псевдонимы в `scala` пакете, поэтому вы можете использовать их указывая обычное имя без необходимости импорта пакета. Примером может служить тип `List`, к которому можно получить доступ следующим образом: + + scala.collection.immutable.List // Полное объявление + scala.List // объявление через псевдоним + List // т.к. scala._ всегда автоматически импортируется + // можно просто указать имя коллекции + +Другие псевдонимы для типов +[Iterable](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html), [Seq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Seq.html), [IndexedSeq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/IndexedSeq.html), [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html), [LazyList](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/LazyList.html), [Vector](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html), [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html), и [Range](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html). + +На следующем рисунке показаны все коллекции из пакета `scala.collection`. Это все абстрактные классы или трейты, у которых обычно есть, как изменяемая, так и неизменяемая реализация. + +[![Иерархия базовых коллекций][1]][1] + +На следующем рисунке показаны все коллекции из пакета `scala.collection.immutable`. + +[![Иерархия неизменяемых коллекций][2]][2] + +И на конец все коллекции из пакета `scala.collection.mutable`. + +[![Иерархия изменяемых коллекций][3]][3] + +Описания: + +[![Граф описаний][4]][4] + +## Обзор API коллекций ## + +Наиболее важные классы коллекций представлены на рисунках выше. Существует довольно много общего между всеми этими классами. Например, любая коллекция может быть создана по одному общему синтаксису, написав имя класса коллекции, а затем ее элементы: + + Iterable("x", "y", "z") + Map("x" -> 24, "y" -> 25, "z" -> 26) + Set(Color.red, Color.green, Color.blue) + SortedSet("hello", "world") + Buffer(x, y, z) + IndexedSeq(1.0, 2.0) + LinearSeq(a, b, c) + +Этот же принцип применяется и к конкретным реализациям коллекций, таким как + + List(1, 2, 3) + HashMap("x" -> 24, "y" -> 25, "z" -> 26) + +Все эти коллекции выводятся с помощью `toString`. + +Все коллекции поддерживают API, предоставляемый `Iterable`, но с определенной спецификой на разных типах, где это имеет смысл. Например, метод `map` в классе `Iterable` возвращает в результате другой `Iterable`. Но в подклассах тип результата переопределяется. Например, вызов `map` в `List` снова дает `List`, вызов на`Set` снова дает `Set` и так далее. + + scala> List(1, 2, 3) map (_ + 1) + res0: List[Int] = List(2, 3, 4) + scala> Set(1, 2, 3) map (_ * 2) + res0: Set[Int] = Set(2, 4, 6) + +Такое поведение, повсеместно реализованное для коллекций, называется _принцип единообразного типа возвращаемого значения_ (_uniform return type principles_). + +Большинство классов в иерархии коллекций существуют в трех вариантах: базовый, изменяемый и неизменяемый. Единственным исключением является трейт `Buffer`, который существует только в виде изменяемой коллекции. + +Далее мы рассмотрим все эти классы поподробнее. + + + [1]: /resources/images/tour/collections-diagram-213.svg + [2]: /resources/images/tour/collections-immutable-diagram-213.svg + [3]: /resources/images/tour/collections-mutable-diagram-213.svg + [4]: /resources/images/tour/collections-legend-diagram.svg diff --git a/_ru/overviews/collections-2.13/performance-characteristics.md b/_ru/overviews/collections-2.13/performance-characteristics.md new file mode 100644 index 0000000000..281280075b --- /dev/null +++ b/_ru/overviews/collections-2.13/performance-characteristics.md @@ -0,0 +1,84 @@ +--- +layout: multipage-overview +title: Показатели производительности +partof: collections-213 +overview-name: Collections +num: 12 +previous-page: strings +next-page: equality +language: ru +--- + +Из предыдущих объяснений стало ясно, что разные типы коллекций имеют разные показатели производительности. Что зачастую является основной причиной выбора одной коллекции вместо другой. Показатели для наиболее распространенных операций собраны в таблицах ниже. + +Показатели производительности на последовательностях: + +| | head | tail | apply | update| prepend | append | insert | +| -------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | +| **Не изменяемые** | | | | | | | | +| `List` | C | C | L | L | C | L | - | +| `LazyList` | C | C | L | L | C | L | - | +| `ArraySeq` | C | L | C | L | L | L | - | +| `Vector` | eC | eC | eC | eC | eC | eC | - | +| `Queue` | aC | aC | L | L | C | C | - | +| `Range` | C | C | C | - | - | - | - | +| `String` | C | L | C | L | L | L | - | +| **Изменяемые** | | | | | | | | +| `ArrayBuffer` | C | L | C | C | L | aC | L | +| `ListBuffer` | C | L | L | L | C | C | L | +|`StringBuilder`| C | L | C | C | L | aC | L | +| `Queue` | C | L | L | L | C | C | L | +| `ArraySeq` | C | L | C | C | - | - | - | +| `Stack` | C | L | L | L | C | L | L | +| `Array` | C | L | C | C | - | - | - | +| `ArrayDeque` | C | L | C | C | aC | aC | L | + +Показатели производительности на множествах и мапах: + +| | lookup | add | remove | min | +| -------- | ---- | ---- | ---- | ---- | +| **Не изменяемые** | | | | | +| `HashSet`/`HashMap`| eC | eC | eC | L | +| `TreeSet`/`TreeMap`| Log | Log | Log | Log | +| `BitSet` | C | L | L | eC1| +| `VectorMap` | eC | eC | aC | L | +| `ListMap` | L | L | L | L | +| **Изменяемые** | | | | | +| `HashSet`/`HashMap`| eC | eC | eC | L | +| `WeakHashMap` | eC | eC | eC | L | +| `BitSet` | C | aC | C | eC1| +| `TreeSet` | Log | Log | Log | Log | + +Примечание: 1 Предполагаем, что биты плотно упакованы. + +Объяснение записей: + +| | | +| --- | ---- | +| **C** | Операция занимает (быстрое) [постоянное время](https://ru.wikipedia.org/wiki/%D0%92%D1%80%D0%B5%D0%BC%D0%B5%D0%BD%D0%BD%D0%B0%D1%8F_%D1%81%D0%BB%D0%BE%D0%B6%D0%BD%D0%BE%D1%81%D1%82%D1%8C_%D0%B0%D0%BB%D0%B3%D0%BE%D1%80%D0%B8%D1%82%D0%BC%D0%B0). | +| **eC** | Операция занимает практически постоянное время, но может зависеть от некоторых допущений, таких как максимальная длина вектора или распределение ключей хэширования.| +| **aC** | Операция занимает постоянное амортизированное время. Некоторые вызовы операции могут занять больше времени, но если в среднем выполняется много операций, то на одну операцию приходится постоянное время. | +| **Log** | Операция занимает время, пропорциональное логарифму от размера коллекции.| +| **L** | Операция линейная, т.е. занимает время, пропорциональное размеру коллекции.| +| **-** | Операция не поддерживается. | + +В первой таблице рассматриваются типы последовательностей - как изменяемые, так и неизменяемые - со следующими операциями: + +| | | +| --- | ---- | +| **head** | Выбор первого элемента последовательности. | +| **tail** | Создание новой последовательности, состоящей из всех элементов, кроме первого. | +| **apply** | Работа с индексом. | +| **update** | Функционал обновления (с `updated`) для неизменяемых последовательностей и через сайд эффекты обновление (с `update`) для изменяемых последовательностей. +| **prepend**| Добавление элемента спереди последовательности. В неизменяемых последовательностях происходит создание новой последовательности. В изменяемых - модифицируется исходная. | +| **append** | Добавление элемента в конец последовательности. В неизменяемых последовательностях происходит создание новой последовательности. В изменяемых - модифицируется исходная. | +| **insert** | Вставка элемента в любом месте последовательности. Поддерживается только в изменяемых последовательностях. | + +Во второй таблице показаны изменяемые и неизменяемые множества и мапы со следующими операциями: + +| | | +| --- | ---- | +| **lookup** | Проверка наличия элемента во множестве или получение значения, связанного с ключом в мапе. | +| **add** | Добавление нового элемента во множество или пару ключ/значение в мапу . | +| **remove** | Удаление элемента из множества или ключа из мапы. | +| **min** | Наименьший элемент множества, или наименьший ключ в мапе. | diff --git a/_ru/overviews/collections-2.13/seqs.md b/_ru/overviews/collections-2.13/seqs.md new file mode 100644 index 0000000000..49ef6d32b6 --- /dev/null +++ b/_ru/overviews/collections-2.13/seqs.md @@ -0,0 +1,119 @@ +--- +layout: multipage-overview +title: Последовательности. Трейт Seq, IndexedSeq и LinearSeq +partof: collections-213 +overview-name: Collections +num: 5 +previous-page: trait-iterable +next-page: sets +language: ru +--- + +Трейт [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) представляет из себя последовательность. Последовательность - это своего рода итерируемая сущность, у которой есть длина (`length`) и элементы с фиксированным индексом, начинающийся от `0`. + +Операции с последовательностями, подразделяются на следующие категории, которые кратко изложенные в таблице ниже: + +* **Размера и индексации** операции `apply`, `isDefinedAt`, `length`, `indices`, и `lengthCompare`. Для `Seq`, операция `apply` означает запрос по индексу; Так как последовательность типа `Seq[T]` частично определённая функция, которая принимает в качестве аргумента `Int` (как индекс) и в результате выдает элемент последовательности типа `T`. Другими словами `Seq[T]` расширяет `PartialFunction[Int, T]`. Элементы последовательности индексируются от нуля до `length`(длинна последовательности) минус еденицу. Метод `length` на последовательностях является ссылкой на метод `size` общий коллекциях. Метод `lengthCompare` позволяет сравнивать длины последовательностей с `Int`, даже если длина последовательностей бесконечна. +* **Операции поиска индекса** `indexOf`, `lastIndexOf`, `indexOfSlice`, `lastIndexOfSlice`, `indexWhere`, `lastIndexWhere`, `segmentLength`, которые возвращают индекс элемента, равный заданному значению или совпадающий с каким-либо предикатом. +* **Операции сложения** `prepended`, `prependedAll`, `appended`, `appendedAll`, `padTo`, которые возвращают новые последовательности, полученные добавлением элементов в начале или в конце последовательности. +* **Операции обновления** `updated`, `patch`, которые возвращают новую последовательность полученную заменой некоторых элементов исходной последовательности +* **Операции сортировки** `sorted`, `sortWith`, `sortBy`, которые сортируют последовательность элементов в соответствии с различными критериями +* **Операции разворота** `reverse`, `reverseIterator`, которые выдают или обрабатывают элементы последовательности в обратном порядке. +* **Сравнения** `startsWith`, `endsWith`, `contains`, `containsSlice`, `corresponds`, `search`, которые сопоставляют две последовательности или осуществляют поиск элементов в последовательности. +* **Операции с множествами** `intersect`, `diff`, `distinct`, `distinctBy`, которые выполняют операции _как у множеств_ с элементами двух последовательностей либо удаляют дубликаты. + +Если последовательность изменяемая (мутабельная), то у нее есть операция `update` (обновления), которая обновляет элементы последовательности используя побочные эффекты. Как всегда в Scala синтаксис типа `seq(idx) = elem` - это просто сокращение от `seq.update(idx, elem)`, поэтому `update` - это просто более удобный вариант синтаксиса. Обратите внимание на разницу между `update` (обновить) и `updated` (обновленный). `updated` доступен для всех последовательностей и всегда возвращает новую последовательность вместо того, чтобы модифицировать исходную. + +### Операции на Классе Seq ### + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Размера и индексация:** | | +| `xs(i)` |(эквивалентно `xs apply i`). Выдает элемент `xs` на позиции `i`.| +| `xs isDefinedAt i` |Проверяет есть ли `i` в `xs.indices`.| +| `xs.length` |Длина последовательности (тоже самое что и `size`).| +| `xs lengthCompare n` |Возвращает `-1` если `x` короче `n`, `+1` если длиннее, и `0` такогоже размера что и `n`. Работает даже если последовательность бесконечна, например, `LazyList.from(1) lengthCompare 42` возвращает положительное значение.| +| `xs.indices` |Диапазон индексов `xs`, от `0` до `xs.length` - 1`.| +| **Поиск по индексу** | | +| `xs indexOf x` |Индекс первого элемента в `xs` равного `x`. | +| `xs lastIndexOf x` |Индекс последнего элемента в `xs` равного `x`. | +| `xs indexOfSlice ys` |Первый индекс элемента в `xs` начиная с которого можно сформировать последовательность эквивалентную `ys` (существует несколько вариантов). | +| `xs lastIndexOfSlice ys` |Последний индекс элемента в `xs` начиная с которого можно сформировать последовательность эквивалентную `ys` (существует несколько вариантов). | +| `xs indexWhere p` |Первый индекс элемента который удовлетворяет условию `p` (существует несколько вариантов). | +| `xs.segmentLength(p, i)`|Длина самого длинного непрерывного сегмента элементов в `xs`, начиная с которого удовлетворяется условие `p`.| +| **Сложения:** | | +| `xs.prepended(x)`
            либо `x +: xs` |Новая последовательность, состоящая из `x` добавленный перед `xs`.| +| `xs.prependedAll(ys)`
            либо `ys ++: xs` |Новая последовательность, состоящая из всех элементов `ys` добавленных перед `xs`.| +| `xs.appended(x)`
            либо `xs :+ x` |Новая последовательность, состоящая из `x` добавленных после `xs`.| +| `xs.appendedAll(ys)`
            либо `xs :++ ys` |Новая последовательность, состоящая из всех элементов `ys` добавленных после `xs`.| +| `xs.padTo(len, x)` |Последовательность, получаемая в результате добавления значения `x` к `xs` до тех пор пока не будет достигнута длина `len`.| +| **Обновления:** | | +| `xs.patch(i, ys, r)` |Последовательность, получаемая в результате замены `r` элементов `xs`, начиная с `i` заменяя их на `ys`.| +| `xs.updated(i, x)` |Создает копию `xs` в которой элемент с индексом `i` заменён на `x`.| +| `xs(i) = x` |(эквивалентно `xs.update(i, x)`, доступно только у `mutable.Seq`). Заменяет элемент `xs` с индексом `i` на `x`.| +| **Сортировка:** | | +| `xs.sorted` |Новая последовательность, полученная при сортировке элементов `xs` используя стардартную схему упорядочивания элементов типа `xs`.| +| `xs sortWith lt` |Новая последовательность, полученная при сортировке элементов `xs` при помощи операции сравнения `lt`.| +| `xs sortBy f` |Новая последовательность, полученная при сортировке элементов `xs`. Сравнение при сортировке происходит между двумя элементами полученных после выполнения функции `f` на исходных элементах.| +| **Развороты:** | | +| `xs.reverse` |Последовательность с элементами `xs` в обратном порядке.| +| `xs.reverseIterator` |Итератор, выдающий все элементы `xs` в обратном порядке.| +| **Сравнения:** | | +| `xs sameElements ys` |Проверка на то, содержат ли `xs` и `ys` одни и те же элементы в одном и том же порядке.| +| `xs startsWith ys` |Проверяет, начинается ли `xs` с последовательности `ys`. (существует несколько вариантов).| +| `xs endsWith ys` |Проверяет, заканчивается ли `xs` последовательностью `ys`. (существует несколько вариантов).| +| `xs contains x` |Проверяет, есть ли в `xs` элемент равный `x`.| +| `xs search x` |Проверяет, есть ли в отсортированной последовательности `xs` элемент, равный `x`, такой поиск может быть более эффективным чем `xs contains x`. | +| `xs containsSlice ys` |Проверяет, есть ли у `xs` непрерывная подпоследовательность, равная `ys`.| +| `(xs corresponds ys)(p)` |Проверяет, удовлетворяют ли соответствующие элементы `xs` и `ys` бинарному предикату `p`.| +| **Операции над множествами:** | | +| `xs intersect ys` |Операция пересечения на множестве между последовательностей `xs` и `ys`, сохраняющее порядок элементов в `xs`.| +| `xs diff ys` |Операция расхождения на множестве между последовательностей `xs` и `ys`, сохраняющее порядок элементов в `xs`.| +| `xs.distinct` |Подпоследовательность `xs`, которая не содержит дублирующих друг друга элементов.| +| `xs distinctBy f` |Подпоследовательность `xs`, которая не содержит дублирующего элемента после применения функции преобразования `f`. Например, `List("foo", "bar", "quux").distinctBy(_.length) == List("foo", "quux")`| + +У трейта [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) есть два дочерних трейта [LinearSeq](https://www.scala-lang.org/api/current/scala/collection/LinearSeq.html), и [IndexedSeq](https://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html). +Они не добавляют никаких новых операций, но у каждого из них разные характеристики производительности: у LinearSeq эффективные операции `head` и `tail`, в то время как у IndexedSeq эффективные операции `apply`, `length` и (если мутабельная) `update`. Часто используемые варианты LinearSeq - это `scala.collection.immutable.List` и `scala.collection.immutable.LazyList`. А наиболее часто используемые IndexedSeq - это `scala.Array` и `scala.collection.mutable.ArrayBuffer`. Класс `Vector` представляет собой компромисс между IndexedSeq и LinearSeq. У него эффективные как обращение по индексу, так и последовательный обход элементов. Поэтому вектора хорошая основа для смешанных моделей доступа, где используются как индексированный, так и последовательный доступ. Позже мы расскажем больше о [векторах]({% link _ru/overviews/collections-2.13/concrete-immutable-collection-classes.md %}). + +В мутабельном варианте `IndexedSeq` добавляет операции преобразования ее элементов в самой коллекции (в отличие от таких операций как `map` и `sort`, доступных на базовом трейте `Seq`, для которых результат - это новая коллекция). + +#### Операции на Классе mutable.IndexedSeq #### + +| ПРИМЕР | ЧТО ДЕЛАЕТ| +| ------ | ------ | +| **Преобразования:** | | +| `xs.mapInPlace(f)` |Преобразует все элементы `xs`, применяя функцию `f` к каждому из них.| +| `xs.sortInPlace()` |Сортирует коллекцию `xs`.| +| `xs.sortInPlaceWith(c)` |Сортирует коллекцию `xs` в соответствии с заданной функцией сравнения `c`.| +| `xs.sortInPlaceBy(f)` |Сортирует коллекцию `xs` в соответствии с порядком, определяемым на результате после применения функции `f` к каждому элементу.| + +### Буферы ### + +Важной подкатегорией мутабельных последовательностей является `Buffer`ы. Они позволяют не только изменять существующие элементы, но и добавлять, вставлять и удалять элементы. Основными новыми методами, поддерживаемыми буфером, являются `append` и `appendAll` для добавления элементов в конце, `prepend` и `prependAll` для добавления спереди, `insert` и `insertAll` для вставок элементов, а также `remove`, `subtractOne` и `subtractAll` для удаления элементов. Краткая информация об этих операциях представлена в таблице ниже. + +Два часто используемых варианта реализации буферов - `ListBuffer` и `ArrayBuffer`. Как следует из названия, `ListBuffer` основан на `List` и поддерживает эффективное преобразование его элементов в `List` (список), тогда как `ArrayBuffer` - основан на `Array` (массиве), он также может быть быстро преобразован в массив. + +#### Операции на Классе Buffer #### + +| ПРИМЕР | ЧТО ДЕЛАЕТ| +| ------ | ------ | +| **Сложения:** | | +| `buf append x`
            либо `buf += x` |Добавляет в конец буфера элемент `x` возвращая этот самый буфер `buf` в качестве результата.| +| `buf appendAll xs`
            либо`buf ++= xs` |Добавляет все элементы `xs` в конец буфер.| +| `buf prepend x`
            либо `x +=: buf` |Добавляет элемент `x` в начало буфера.| +| `buf prependAll xs`
            либо `xs ++=: buf` |Добавляет все элементы `xs` в начало буфера.| +| `buf.insert(i, x)` |Вставляет элемент `x` на позицию `i` в буфер.| +| `buf.insertAll(i, xs)` |Вставляет все элементы в `xs` на позицию `i` в буфер.| +| `buf.padToInPlace(n, x)` |Добавляет элемент `x` в буфер до тех пор, пока там не будет `n` элементов.| +| **Удаления:** | | +| `buf subtractOne x`
            либо `buf -= x` |Удаляет элемент `x` из буфера.| +| `buf subtractAll xs`
            либо `buf --= xs` |Удаляет элементы `xs` из буфера.| +| `buf remove i` |Удаляет элемент на позиции `i` из буфера.| +| `buf.remove(i, n)` |Удаляет `n` элементов начиная с позиции `i` из буфера.| +| `buf trimStart n` |Удаляет первых `n` элементов из буфера.| +| `buf trimEnd n` |Удаляет последние `n` элементов из буфера.| +| `buf.clear()` |Удаляет все элементы из буфера.| +| **Замена:** | | +| `buf.patchInPlace(i, xs, n)` |Заменяет (не более чем) `n` элементов буфера элементами из `xs`, начиная с позиции `i` в буфере.| +| **Клонирование:** | | +| `buf.clone()` |Новый буфер с теми же элементами, что и `buf`.| diff --git a/_ru/overviews/collections-2.13/sets.md b/_ru/overviews/collections-2.13/sets.md new file mode 100644 index 0000000000..d57e891797 --- /dev/null +++ b/_ru/overviews/collections-2.13/sets.md @@ -0,0 +1,149 @@ +--- +layout: multipage-overview +title: Множества +partof: collections-213 +overview-name: Collections +num: 6 +previous-page: seqs +next-page: maps +language: ru +--- + +Множества (`Set`) - это итерируемые сущности, которые не содержат дублирующих друг друга элементов. Операции с множествами описаны в таблицах ниже. Описания включают операции для базовых, неизменяемых и изменяемых множеств. Все их операции поделены на следующие категории: + +* **Проверки** `contains`, `apply`, `subsetOf`. Метод `contains` спрашивает, содержит ли множество данный элемент. Метод `apply` для множества работает также как и `contains`, поэтому `set(elem)` является тем же самым, что и `set contains elem`. Это означает, что множества могут использоваться в качестве тестовых функций, которые возвращают `true` при проверке элементов, которые они содержат. + +Например: + + + scala> val fruit = Set("apple", "orange", "peach", "banana") + fruit: scala.collection.immutable.Set[java.lang.String] = Set(apple, orange, peach, banana) + scala> fruit("peach") + res0: Boolean = true + scala> fruit("potato") + res1: Boolean = false + + +* **Сложения** `incl` и `concat` (либо `+` и `++`, соответственно), которые добавляют один или несколько элементов во множество, создавая новое множество. +* **Удаления** `excl` и `removedAll` (либо `-` и `--`, соответственно), которые удаляют один или несколько элементов из множества, образуя новое множество. +* **Операции с множествами** для объединения, пересечения и установления расхождений во множествах. Каждая из таких операций имеет две формы: словарную и символьную. Словарные версии - `intersect`, `union`, и `diff`, а символьные - `&`, `|` и `&~`. Фактически `++`, которые `Set` унаследовали от `Iterable`, можно рассматривать как еще один псевдоним `union` или `|`, за исключением того, что `++` принимает `IterableOnce` в качестве аргумента, а `union` и `|` принимают множества. + +### Операции на Классе Set ### + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Проверки:** | | +| `xs contains x` |Проверяет, является ли `x` элементом `xs`. | +| `xs(x)` |Тоже самое что и `xs contains x`. | +| `xs subsetOf ys` |Проверяет, является ли `xs` подмножеством `ys`. | +| **Добавления:** | | +| `xs concat ys`
            или `xs ++ ys` |Множество, содержащее все элементы `xs`, а также все элементы `ys`. | +| **Удаления:** | | +| `xs.empty` |Пустое множество того же класса, что и `xs`. | +| **Двуместные Операции:** | | +| `xs intersect ys`
            или `xs & ys` |Множество содержащее пересечение `xs` и `ys`. | +| `xs union ys`
            или xs | ys |Множество содержащее объединение `xs` и `ys`. | +| `xs diff ys`
            или `xs &~ ys` |Множество содержащее расхождение между `xs` и `ys`. | + +В неизменяемых множествах методы добавления или удаления элементов работают путем возврата новых множеств (`Set`), как описано ниже. + +### Операции на Классе immutable.Set ### + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Добавления:** | | +| `xs incl x`
            или `xs + x` |Множество содержащее все элементы `xs` а также элемент `x`.| +| **Удаления:** | | +| `xs excl x`
            или `xs - x` |Множество содержащее все элементы `xs` кроме `x`.| +| `xs removedAll ys`
            или `xs -- ys` |Множество содержащее все элементы `xs` кроме элементов `ys`.| + +Изменяемые множества предоставляют в дополнение к перечисленным методам еще методы добавления, удаления или обновления элементов. + +### Операции на Классе mutable.Set ### + +| ПРИМЕР | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Добавления:** | | +| `xs addOne x`
            или `xs += x` |Добавляет элемент `x` во множество `xs` побочным эффектом и возвращает сам `xs`. | +| `xs addAll ys`
            или `xs ++= ys` |Добавляет все элементы `ys` во множество `xs` побочным эффектом и возвращает сам `xs`. | +| `xs add x` |Добавляет элемент `x` к `xs` и возвращает `true`, если `x` ранее не содержался в множестве, `false` если был.| +| **Удаления:** | | +| `xs subtractOne x`
            или `xs -= x` |Удаляет элемент `x` из множества `xs` побочным эффектом и возвращает сам `xs`.| +| `xs subtractAll ys`
            или `xs --= ys` |Удаляет все элементы `ys` из множества `xs` побочным эффектом и возвращает сам `xs`. | +| `xs remove x` |Удаляет элемент `x` из `xs` и возвращает `true`, если `x` ранее не содержался в множестве, `false` если был.| +| `xs filterInPlace p` |Оставляет только те элементы в `xs` которые удовлетворяют условию `p`.| +| `xs.clear()` |Удаляет все элементы из `xs`.| +| **Обновления:** | | +| `xs(x) = b` |(тоже самое что и `xs.update(x, b)`). Если логический аргумент `b` равен `true`, то добавляет `x` к `xs`, иначе удаляет `x` из `xs`.| +| **Клонирования:** | | +| `xs.clone` |Создает новое мутабельное множество с такими же элементами как у `xs`.| + +Операции `s += elem` добавляют элемент `elem` к множеству `s` в качестве сайд эффекта, возвращая в качестве результата мутабельное множество. Точно так же, `s -= elem` удаляет `elem` из множества, и возвращает это множество в качестве результата. Помимо `+=` и `-=` есть еще пакетные операции `++=` и `--=` которые добавляют или удаляют все элементы итерируемой коллекции. + +Выбор в качестве имен методов `+=` и `-=` будет означать для вас, то что схожий код сможет работать как с изменяемыми, так и с неизменяемыми множествами. Сначала рассмотрим следующий пример в консоле, в котором используется неизменяемый набор параметров `s`: + + scala> var s = Set(1, 2, 3) + s: scala.collection.immutable.Set[Int] = Set(1, 2, 3) + scala> s += 4 + scala> s -= 2 + scala> s + res2: scala.collection.immutable.Set[Int] = Set(1, 3, 4) + +Мы использовали `+=` и `-=` на `var` типа `immutable.Set`. Выражение `s += 4` является сокращение для `s = s + 4`. Тоесть вызов метода сложения `+` на множестве `s`, а затем присвоения результата обратно в переменную `s` . Рассмотрим теперь аналогичные действия с изменяемым множеством. + + + scala> val s = collection.mutable.Set(1, 2, 3) + s: scala.collection.mutable.Set[Int] = Set(1, 2, 3) + scala> s += 4 + res3: s.type = Set(1, 4, 2, 3) + scala> s -= 2 + res4: s.type = Set(1, 4, 3) + +Конечный эффект очень похож на предыдущий результат; мы начали с `Set(1, 2, 3)` закончили с `Set(1, 3, 4)`. Несмотря на то, что выражения выглядят так же, но работают они несколько иначе. `s += 4` теперь вызывает метод `+=` на изменяемом множестве `s`, измененяет свое собственное значение. По схожей схеме работает, `s -= 2` вызывая метод `-=` на томже самом множестве. + +Сравнение этих двух подходов демонстрирует важный принцип. Часто можно заменить изменяемую коллекцию, хранящуюся в `val`, неизменяемой коллекцией, хранящейся в `var`, и _наоборот_. Это работает, по крайней мере, до тех пор, пока нет прямых отсылок на коллекцию, используя которую можно было бы определить была ли коллекция обновлена или создана заново. + +У изменяемых множеств также есть операции `add` и `remove` как эквиваленты для `+=` и `-=`. Разница лишь в том, что команды `add` и `remove` возвращают логический результат, показывающий, повлияла ли операция на само множество или нет. + +Текущая реализация изменяемого множества по умолчанию использует хэш-таблицу для хранения элементов множества. Реализация неизменяемого множества по умолчанию использует представление, которое адаптируется к количеству элементов множества. Пустое множество представлено объектом сингэлтоном. Множества размеров до четырех представлены одним объектом, в котором все элементы хранятся в виде полей. За пределами этого размера, неизменяемые множества реализованны в виде [Сжатого Отображенния Префиксного Дерева на Ассоциативном Массиве]({% link _ru/overviews/collections-2.13/concrete-immutable-collection-classes.md %}). + +Результатом такой схемы представления является то, что неизменяемые множества малых размеров (скажем, до 4), более компактны и более эффективны, чем изменяемые. Поэтому, если вы ожидаете, что размер множества будет небольшим, постарайтесь сделать его неизменяемым. + +Два дочерних трейта множеств `SortedSet` и `BitSet`. + +### Отсортированное Множество (SortedSet) ### +[SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) это множество, которое отдает свои элементы (используя `iterator` или `foreach`) в заданном порядке (который можно свободно задать в момент создания множества). Стандартное представление [SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) - это упорядоченное двоичное дерево, которое поддерживает свойство того, что все элементы левого поддерева меньше, чем все элементы правого поддерева. Таким образом, простой упорядоченный обход может вернуть все элементы дерева в возрастающем порядке. Scala класс [immutable.TreeSet](https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html) базируется на _красно-черном_ дереве, в котором сохраняется тоже свойство но при этом само дерево является _сбалансированным_ --, то есть все пути от корня дерева до листа имеют длину, которая может отличаться друг от друга максимум на единицу. + +При создании пустого [TreeSet](https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html), можно сначала указать требуемый порядок: + + scala> val myOrdering = Ordering.fromLessThan[String](_ > _) + myOrdering: scala.math.Ordering[String] = ... + +Затем, чтоб создать пустой TreeSet с определенным порядком, используйте: + + scala> TreeSet.empty(myOrdering) + res1: scala.collection.immutable.TreeSet[String] = TreeSet() + +Или можно опустить указание аргумента с функцией сравнения, но указать тип элементов множества. В таком случае будет использоваться порядок заданный по умолчанию на данном типе. + + scala> TreeSet.empty[String] + res2: scala.collection.immutable.TreeSet[String] = TreeSet() + +Если вы создаете новое множество из существующего упорядоченного множества (например, путем объединения или фильтрации), оно будет иметь ту же схему упорядочения элементов, что и исходное множество. Например + + scala> res2 + "one" + "two" + "three" + "four" + res3: scala.collection.immutable.TreeSet[String] = TreeSet(four, one, three, two) + +Упорядоченные множества также поддерживают запросы на диапазоны. Например, метод `range` возвращает все элементы от _начального_ элемента до _конечного_, но исключая конечный элемент. Или же метод `from` возвращает все элементы от _начального_ и далее все остальные элементы в порядке очередности. Результатом работы обоих методов также будет упорядоченное множество. Примеры: + + scala> res3.range("one", "two") + res4: scala.collection.immutable.TreeSet[String] = TreeSet(one, three) + scala> res3 rangeFrom "three" + res5: scala.collection.immutable.TreeSet[String] = TreeSet(three, two) + + +### Битовые Наборы (BitSet) ### + +Битовые Наборы - это множество неотрицательных целочисленных элементов, которые упаковываются в пакеты. Внутреннее представление [BitSet](https://www.scala-lang.org/api/current/scala/collection/BitSet.html) использует массив `Long`ов. Первый `Long` охватывает элементы от 0 до 63, второй от 64 до 127 и так далее (Неизменяемые наборы элементов в диапазоне от 0 до 127 оптимизированны таким образом что хранят биты непосредственно в одном или двух полях типа `Long` без использования массива). Для каждого `Long` 64 бита каждого из них устанавливается значение 1, если соответствующий элемент содержится в наборе, и сбрасывается в 0 в противном случае. Отсюда следует, что размер битового набора зависит от размера самого большого числа, которое в нем хранится. Если `N` является самым большим размером числа, то размер набора будет составлять `N/64` от размера `Long`, или `N/8` байта плюс небольшое количество дополнительных байт для информации о состоянии. + +Поэтому битовые наборы компактнее, чем другие множества, когда речь идет о хранении мелких элементов. Еще одним преимуществом битовых наборов является то, что такие операции, как проверка на наличие элемента `contains`, добавление либо удаление элементов с `+=` и `-=` черезвычайно эффективны. diff --git a/_ru/overviews/collections-2.13/strings.md b/_ru/overviews/collections-2.13/strings.md new file mode 100644 index 0000000000..141b537e76 --- /dev/null +++ b/_ru/overviews/collections-2.13/strings.md @@ -0,0 +1,27 @@ +--- +layout: multipage-overview +title: Строки +partof: collections-213 +overview-name: Collections +num: 11 +previous-page: arrays +next-page: performance-characteristics +language: ru +--- + +Как и массивы, строки не являются непосредственно последовательностями, но могут быть преобразованы в них, а также поддерживают все операции, которые есть у последовательностей. Ниже приведены некоторые примеры операций, которые можно вызывать на строках. + + scala> val str = "hello" + str: java.lang.String = hello + scala> str.reverse + res6: String = olleh + scala> str.map(_.toUpper) + res7: String = HELLO + scala> str drop 3 + res8: String = lo + scala> str.slice(1, 4) + res9: String = ell + scala> val s: Seq[Char] = str + s: Seq[Char] = hello + +Эти операции обеспечены двумя неявными преобразованиями. Первое, низкоприоритетное неявное преобразование отображает `String` в `WrappedString`, которая является подклассом `immutable.IndexedSeq`, это преобразование сделано в последней строке выше, в которой строка была преобразована в Seq. Второе, высокоприоритетное преобразование связывает строку и объект `StringOps`, который добавляет все методы на неизменяемых последовательностях. Это неявное преобразование используется при вызове методов `reverse`, `map`, `drop` и `slice` в примере выше. diff --git a/_ru/overviews/collections-2.13/trait-iterable.md b/_ru/overviews/collections-2.13/trait-iterable.md new file mode 100644 index 0000000000..3af59d11d6 --- /dev/null +++ b/_ru/overviews/collections-2.13/trait-iterable.md @@ -0,0 +1,145 @@ +--- +layout: multipage-overview +title: Трейт Iterable +partof: collections-213 +overview-name: Collections +num: 4 +previous-page: overview +next-page: seqs +language: ru +--- + +На самом верху иерархии коллекций находится трейт `Iterable`. Все методы в этого трейта описаны как абстрактные, `iterator` - это метод, который выдает элементы коллекции один за другим. + + def iterator: Iterator[A] + +Классы коллекций, которые базируются на `Iterable`, должны определять этот метод; все остальные методы могут быть просто унаследованы от `Iterable`. + +`Iterable` также определяет несколько конкретных методов, все они делятся на категории, которые опишем в следующей таблице: + +* **Сложения**, `concat`, которая объединяет две коллекции вместе либо добавляет все элементы итератора к коллекции. +* **Применения ко всем** операции `map`, `flatMap` и `collect`, которые создают новую коллекцию, применяя некую функцию к элементам коллекции. +* **Конверсии** `toArray`, `toList`, `toIterable`, `toSeq`, `toIndexedSeq`, `toStream`, `toSet`, `toMap`, которые превращают `Iterable` коллекцию во что-то более конкретное. Все эти преобразования возвращают потребляемые аргументы без изменений, если тип коллекции во время выполнения уже соответствует запрашиваемому типу коллекции. Например, применение команды `toList` к списку вернет в результате тотже самый список. +* **Копирования** `copyToArray` - как следует из названия, копирует элементы коллекции в массив. +* **Размерности** это операции `isEmpty`, `nonEmpty`, `size`, `knownSize`, `sizeIs`. Работают с количеством элементов коллекции, в некоторых случаях может потребовать обхода всех элементов (например для `List`). В других случаях коллекция может вообще иметь неограниченное количество элементов (например, `LazyList.from(1)`). +* **Выбора элементов** это операции `head`, `last`, `headOption`, `lastOption`, и `find`. Они выбирают первый или последний элемент коллекции, или же первый элемент, который соответствует условию. Обратите внимание, однако, что не все коллекции имеют четкое определенние того, что они подразумевают под "first"(первым) и "last"(последним) элементом. Например, хэши можгут хранить элементы в соответствии с их ключами, которые могут меняться от запуска к запуску. В таком случае "первый" элемент во множестве хэшей может быть разным, при каждом запуске программы. Однако если коллекция _упорядоченная_, то она всегда выдает свои элементы в одном и том же порядке. Большинство коллекций упорядоченные, но некоторые (_в том числе HashSet_) нет. Отсутствие упорядоченности дает им дополнительную эффективность работы. Упорядочивание часто необходимо для проведения воспроизводимых тестов и помощи в отладке. С этой целью коллекции Scala предоставляют упорядоченные альтернативы для всех типов коллекций. Например, упорядоченной альтернативой для `HashSet` является `LinkedHashSet`. +* **Выбора под-коллекций** `tail`, `init`, `slice`, `take`, `drop`, `takeWhile`, `dropWhile`, `filter`, `filterNot`, `withFilter`. Все они возвращают какую-то подколлекцию, определяемую индексным диапазоном или каким-либо предикатом. +* **Разделительных операций** `splitAt`, `span`, `partition`, `partitionMap`, `groupBy`, `groupMap`, `groupMapReduce`, которые разделяют элементы исходной коллекции на несколько подколлекций. +* **Проверки элементов** `exists`, `forall`, `count` которые проверяют элементы коллекции с определенным предикатом. +* **Свертки** `foldLeft`, `foldRight`, `reduceLeft`, `reduceRight` которые применяют двуместную операцию к последовательным элементам. +* **Определённых сверток** `sum`, `product`, `min`, `max`, которые работают над коллекциями конкретных типов (числовыми или сопоставимыми). +* **Строковая** операции `mkString`, `addString`, `className`, которые дают альтернативные способы преобразования коллекции в строку. +* **Отображения** - это такая коллекция, которая лениво вычисляется. Позже мы расмотрим отображения [подробнее]({% link _ru/overviews/collections-2.13/views.md %}). + +В `Iterable` есть два метода, которые возвращают итераторы: `grouped` и `sliding`. Правда, эти итераторы возвращают не отдельные элементы, а целые подпоследовательности элементов исходной коллекции. Максимальный размер таких подпоследовательностей задается аргументом. Метод `grouped` возвращает свои элементы "нарезанные" на фиксированные части, тогда как `sliding` возвращает результат "прохода окна" (заданной длинны) над элементами. Разница между ними станет очевидной, если взглянуть на следующий результат в консоли: + + scala> val xs = List(1, 2, 3, 4, 5) + xs: List[Int] = List(1, 2, 3, 4, 5) + scala> val git = xs grouped 3 + git: Iterator[List[Int]] = non-empty iterator + scala> git.next() + res3: List[Int] = List(1, 2, 3) + scala> git.next() + res4: List[Int] = List(4, 5) + scala> val sit = xs sliding 3 + sit: Iterator[List[Int]] = non-empty iterator + scala> sit.next() + res5: List[Int] = List(1, 2, 3) + scala> sit.next() + res6: List[Int] = List(2, 3, 4) + scala> sit.next() + res7: List[Int] = List(3, 4, 5) + +### Операции в Классе Iterable ### + +| НАЗВАНИЕ | ЧТО ДЕЛАЕТ | +| ------ | ------ | +| **Абстрактный Метод:** | | +| `xs.iterator` |Возвращает итератор, который выдает каждый элемент из `xs`.| +| **Другие Итераторы:** | | +| `xs foreach f` |Выполняет функцию `f` на каждом элементе `xs`.| +| `xs grouped size` |Итератор, который нарезает коллекцию на кусочки фиксированного размера. | +| `xs sliding size` |Итератор, который выдает результат прохождения окна фиксированного размера над элементами исходной коллекции. | +| **Сложения:** | | +| `xs concat ys`
            (либо `xs ++ ys`) |Результат состоит из элементов обоих коллекций `xs` и `ys`. `ys` - [IterableOnce](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/IterableOnce.html) коллекция, т. е., либо [Iterable](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterable.html) либо [Iterator](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html).| +| **Применения ко всем:** | | +| `xs map f` |Коллекция, полученная применением функции `f` к каждому элементу в `xs`.| +| `xs flatMap f` |Коллекция, полученная применением функции производящей коллекции `f` к каждому элементу в`xs` с объединением результатов в единую коллекцию.| +| `xs collect f` |Коллекция, полученная применением частично определенной функции `f` к каждому элементу в `xs`, для которого она определена, с последующем сбором результатов. | +| **Конверсии:** | | +| `xs.toArray` |Преобразует коллекцию в массив. | +| `xs.toList` |Преобразует коллекцию в список. | +| `xs.toIterable` |Преобразует коллекцию в итерабельную коллекцию. | +| `xs.toSeq` |Преобразует коллекцию в последовательность. | +| `xs.toIndexedSeq` |Преобразует коллекцию в индексированную последовательность. | +| `xs.toSet` |Преобразует коллекцию в множество. | +| `xs.toMap` |Преобразует набор пар ключ/значение в Map. Если в исходной коллекции нет пар, то вызов этой операции приведёт к ошибке при статической проверки типов.| +| `xs.to(SortedSet)` | Общая операция преобразования, в которой в качестве параметра используется производящая коллекция. | +| **Копирования:** | | +| `xs copyToArray(arr, s, n)`|Копирует не более `n` элементов коллекции в массив `arr`, начиная с индекса `s`. Два последних аргумента являются необязательными.| +| **Размерности:** | | +| `xs.isEmpty` |Проверяет, пуста ли коллекция. | +| `xs.nonEmpty` |Проверяет, содержит ли коллекция элементы. | +| `xs.size` |Количество элементов в коллекции. | +| `xs.knownSize` |Количество элементов, вычисляется только если для вычисления количества требуется константное время (`О(1)`) , иначе `-1`. | +| `xs.sizeCompare(ys)` |Возвращает отрицательное значение, если `xs` короче коллекции `ys`, положительное значение, если она длиннее, и `0` если у них одинаковый размер. Работает даже если коллекция бесконечна, например, `LazyList.from(1) sizeCompare List(1, 2)` возвращает положительное значение. | +| `xs.sizeCompare(n)` |Возвращает отрицательное значение, если `xs` короче `n`, положительное значение, если больше, и `0` если размер равен `n`. Работает даже если коллекция бесконечна, например, `LazyList.from(1) sizeCompare 42` возвращает положительное значение. | +| `xs.sizeIs < 42`, `xs.sizeIs != 42`, и так далее |Обеспечивает более удобный синтаксис для `xs.sizeCompare(42) <0`, `xs.sizeCompare(42) !=0` и т.д., соответственно.| +| **Выбора элементов:** | | +| `xs.head` |Первый элемент коллекции (или какой-то элемент, если порядок не определен).| +| `xs.headOption` |Первый элемент `xs` в опциональном значении, или None, если `xs` пуст.| +| `xs.last` |Последний элемент коллекции (или какой-то элемент, если порядок не определен).| +| `xs.lastOption` |Последний элемент `xs` в опциональном значении, или None, если `xs` пуст.| +| `xs find p` |Опциональное значение, содержащее первый элемент из `xs`, которое удовлетворяет `p`, или `None` если ни один из элементов не удовлетворяет требованиям.| +| **Выбора под-коллекций:** | | +| `xs.tail` |Оставшаяся часть коллекции, без `xs.head`. | +| `xs.init` |Оставшаяся часть коллекции, без `xs.last`. | +| `xs.slice(from, to)` |Коллекция, состоящая из элементов в определенном диапазоне `xs` (от `from` до, но не включая `to`).| +| `xs take n` |Коллекция, состоящая из первых `n` элементов `xs` (или некоторых произвольных `n` элементов, если порядок не определен).| +| `xs drop n` |Оставшаяся часть коллекции, без `xs take n`.| +| `xs takeWhile p` |Самый длинный префикс элементов в коллекции, удовлетворяющий `p`.| +| `xs dropWhile p` |Коллекция без самого длинного префикса элементов, удовлетворяющего `p`.| +| `xs takeRight n` |Коллекция, состоящая из последних `n` элементов `xs` (или некоторых произвольных `n` элементов, если порядок не определен).| +| `xs dropRight n` |Оставшаяся часть коллекции, без `xs takeRight n`.| +| `xs filter p` |Коллекция, состоящая из тех элементов `xs`, которые удовлетворяют предикату `p`.| +| `xs withFilter p` |Нестрогий фильтр коллекции. Последовательность вызовов `map`, `flatMap`, `foreach` и `withFilter`, будет применятся только к тем элементам `xs`, для которых условие `p` верно.| +| `xs filterNot p` |Коллекция, состоящая из элементов `xs`, которые не удовлетворяют предикату `p`.| +| **Разделительных Операций:** | | +| `xs splitAt n` |Разделяет `xs` на две коллекции `(xs take n, xs drop n)` | +| `xs span p` |Разделяет `xs` в соответствии с предикатом, образуя пару коллекций `(xs takeWhile p, xs.dropWhile p)`.| +| `xs partition p` |Разделяет `xs` на пару коллекций; одна с элементами, удовлетворяющими предикату `p`, другая с элементами, которые не удовлетворяют, образуя пару коллекций `(xs filter p, xs.filterNot p)`.| +| `xs groupBy f` |Разделяет `xs` на пары ключ/значение в соответствии с разделительной функцией `f`.| +| `xs.groupMap(f)(g)`|Разделяет `xs` на пары ключ/значение в соответствии с разделительной функцией `f` и применяет функцию преобразования `g` к каждому элементу в группе.| +| `xs.groupMapReduce(f)(g)(h)`|Разделяет `xs` в соответствии с разделительной функцией `f`, применяет функцию `g` к каждому элементу в группе, а затем объединяет результаты при помощи функции `h`.| +| **Сведенья об элементах:** | | +| `xs forall p` |Логическое выражение того, соответствует ли предикат `p` всем элементам `xs`.| +| `xs exists p` |Логическое выражение того, соответствует ли предикат `p` какому-либо элементу в `xs`.| +| `xs count p` |Количество элементов в `xs`, удовлетворяющих предикату `p`.| +| **Свертки:** | | +| `xs.foldLeft(z)(op)` |Применяет двуместную операцию `op` между последовательными элементами `x`, слева направо и начиная с `z`.| +| `xs.foldRight(z)(op)` |Применяет двуместную операцию `op` между последовательными элементами `x`, переходя справа налево и заканчивая `z`.| +| `xs reduceLeft op` |Применяет двуместную операцию `op` между последовательными элементами непустой коллекции `xs`, идущей слева направо.| +| `xs reduceRight op` |Применяет двуместную операцию `op` между последовательными элементами непустой коллекции `xs`, идущей справа налево.| +| **Определённых Сверток:** | | +| `xs.sum` |Сумма числовых значений элементов коллекции `xs`.| +| `xs.product` |Произведение числовых значений элементов коллекции `xs`.| +| `xs.min` |Минимальное порядковое значение элемента коллекции `xs`.| +| `xs.max` |Максимальное порядковое значение элемента коллекции `xs`.| +| `xs.minOption` |Как `min` но возвращает `None` если `xs` пустой.| +| `xs.maxOption` |Как `max` но возвращает `None` если `xs` пустой.| +| **Строковые:** | | +| `xs.addString(b, start, sep, end)`|Добавляет строку `b` в `StringBuilder`, которая показывает все элементы `xs` разделенные `sep`, окруженные строками `start` и `end`. `end`. `start`, `sep` - не обязательные параметры.| +| `xs.mkString(start, sep, end)`|Преобразовывает коллекцию в строку, которая отображает все элементы `xs` разделенные `sep`, окруженные строками `start` и `end`. `end`. `start`, `sep` - не обязательные параметры.| +| `xs.stringPrefix` |Возвращает название коллекции `xs.toString'.| +| **Связывание:** | | +| `xs zip ys` |Коллекция пар соответствующих элементов из `xs` и `ys`.| +| `xs.zipAll(ys, x, y)` |Коллекция пар соответствующих элементов из `xs`и `ys`, где более короткая последовательность расширяется, чтобы соответствовать более длинной, добавляя элементы `x` или `y`.| +| `xs.zipWithIndex` |Коллекция пар элементов из `xs` с их индексами.| +| **Отображения:** | | +| `xs.view` |Выводит ленивое отображение для коллекции `xs`.| + +В иерархии наследования сразу под `Iterable` расположены три трейта: [Seq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Seq.html), [Set](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Set.html), и [Map](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Map.html).`Seq` и `Map` реализуют [PartialFunction](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/PartialFunction.html) трейт с его `apply` и `isDefinedAt` методами, но по-своему. `Set` получил свой `apply` метод от [SetOps](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/SetOps.html). + +Для последовательностей, `apply` это указание на позицию элемента, которая указывается всегда номером от `0`. Поэтому `Seq(1, 2, 3)(1)` дает `2`. Для множеств `apply` проверка членов этого множества. Например, `Set('a', 'b', 'c')('b')` дает `true` тогда как `Set()('a')` дает `false`. И наконец, для _пар ключ-значение_, `apply` это запрос элемента. Например, `Map('a' -> 1, 'b' -> 10, 'c' -> 100)('b')` дает `10`. + +Далее мы более подробно рассмотрим каждую, из этих трех видов, коллекций. diff --git a/_ru/overviews/collections-2.13/views.md b/_ru/overviews/collections-2.13/views.md new file mode 100644 index 0000000000..135cbb0b50 --- /dev/null +++ b/_ru/overviews/collections-2.13/views.md @@ -0,0 +1,113 @@ +--- +layout: multipage-overview +title: Отображения +partof: collections-213 +overview-name: Collections +num: 14 +previous-page: equality +next-page: iterators +language: ru +--- + +У коллекций довольно много вариантов создания новых коллекций. Ну например используя операции `map`, `filter` или `++`. Мы называем такие операции *трансформерами*, потому что они берут хотя бы одну коллекцию и трансформируют её в новую коллекцию. + +Существует два основных способа реализации трансформеров. Один из них _строгий_, то есть в результате трансформации строится новая коллекция со всеми ее элементами. Другой - _не строгий_ или _ленивый_, то есть трансформер создает только соглашение для получения результата, а дальше элементы создаются только когда будут запрошены. + +В качестве примера не строгого трансформера рассмотрим следующую реализацию операции создания ленивой мапы: + + def lazyMap[T, U](iter: Iterable[T], f: T => U) = new Iterable[U] { + def iterator = iter.iterator map f + } + +Обратите внимание, что `lazyMap` создает новую `Iterable` , не обходя все элементы коллекции `iter`. Функция `f` применяется к элементам новой коллекции `iterator` по мере запроса ее элементов. + +Коллекции Scala по умолчанию используют строгий способ во всех своих трансфмерах, за исключением `LazyList`, который реализует свои трансформеры не строгими (ленивыми). Однако существует практичный способ превратить любую коллекцию в ленивую и _наоборот_, основанный на отображении коллекции. _Отображение_ представляет собой особый вид коллекции, которое реализует все трансформеры лениво. + +Для перехода от коллекции к ее отображению можно использовать метод `view` (отобразить) у коллекции. Если `xs` - это какая-то коллекция, то `xs.view` - это та же самая коллекция, но со всеми трансформерами, реализованными лениво. Чтобы вернуться от такого отображения к строгой коллекции, можно использовать операцию преобразования `to` с указанием создаваемой коллекции в качестве параметра (например, `xs.view.to(List)`). + +Давайте рассмотрим пример. Допустим, у вас есть целочисленный вектор, на котором вы хотите последовательно применить две функции: + + scala> val v = Vector(1 to 10: _*) + v: scala.collection.immutable.Vector[Int] = + Vector(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + scala> v map (_ + 1) map (_ * 2) + res5: scala.collection.immutable.Vector[Int] = + Vector(4, 6, 8, 10, 12, 14, 16, 18, 20, 22) + +В последней строчке выражение `v map (_ + 1)` создает новый вектор, который при втором вызове в `map (_ * 2)` превращается в третий вектор. Как правило, построение промежуточного результата от первого вызова мапы расточительно. В приведенном выше примере было бы быстрее составить единую мапу, состоящую из двух функций `(_ + 1)` и `(_ * 2)`. Если у вас обе функции доступны в одном и том же выражении, вы можете объединить их вручную. Но довольно часто последовательные преобразования структуры данных выполняются в различных модулях программы. Слияние этих преобразований отрицательно скажется на модульности. Более универсальным способом избежать промежуточных результатов - это превратить вектор сначало в отображение, затем применить все преобразования к отображению и, наконец, преобразовать отображение в вектор: + + scala> (v.view map (_ + 1) map (_ * 2)).to(Vector) + res12: scala.collection.immutable.Vector[Int] = + Vector(4, 6, 8, 10, 12, 14, 16, 18, 20, 22) + +Давайте повторим последовательность этих операций, одну за другой: + + scala> val vv = v.view + vv: scala.collection.IndexedSeqView[Int] = IndexedSeqView() + +Применение `v.view` дает нам `IndexedSeqView[Int]`, тоесть лениво вычисляемым `IndexedSeq[Int]`. Так же как и `LazyList`, +метод `toString` на отображении не принуждает выводить элементы, вот почему содержимое `vv` выводится как `View(?)`. + +Применение первого `map` к отображению дает: + + scala> vv map (_ + 1) + res13: scala.collection.IndexedSeqView[Int] = IndexedSeqView() + +Результатом работы `map` - еще один `IndexedSeqView[Int]`. По сути, это обёртка, которая *записывает* тот факт, что на вектор `v` необходимо наложить `map` с функцией `(_ + 1)`. Однако эта мапа не будет применяться до тех пор, пока не будет принудительно запрошена. Теперь применим вторую `map` к последнему результату. + + scala> res13 map (_ * 2) + res14: scala.collection.IndexedSeqView[Int] = IndexedSeqView() + +Наконец, принудительно запросим результат: + + scala> res14.to(Vector) + res15: scala.collection.immutable.Vector[Int] = + Vector(4, 6, 8, 10, 12, 14, 16, 18, 20, 22) + +Обе сохраненные функции применяются в процессе выполнения операции `to` и строится новый вектор. Таким образом, промежуточная структура данных не требуется. + +В целом, операции преобразования, применяемые к отображениям, никогда не создают новую структуру данных, и имеют эффективный доступ к элементам отображения, обходя как можно меньше элементов базовой структуры данных. +Таким образом, отображения имеют следующие свойства: +1. Трансформеры имеют вычислительную сложность `O(1)`. +2. Операции доступа к элементам имеют ту же сложность что и у базовой структуры данных (например, доступ по индексу на `IndexedSeqView` имеет константную сложность). + + +Однако есть несколько исключений из этих правил. Например, операция `sorted` не может удовлетворять сразу оба свойства. +В действительности, необходимо обойти всю основную коллекцию, чтобы найти ее минимальный элемент. +С одной стороны, если этот обход произошел во время вызова `sorted`, то первое свойство будет нарушено (`sorted` не будет лениво отображен), +с другой стороны, если обход произошел во время доступа к полученным элементам отображения, то второе свойство будет нарушено. +Для таких операций мы решили нарушить первое свойство. +Такие операции задокументированны как *"всегда принуждающие к сбору всех элементов"*. + +Основной причиной использования отображений - производительность. Вы видели, что переключив коллекцию в режим отображения можно избежать создания промежуточных коллекций. Такая экономия может оказаться крайне важной. В качестве другого примера рассмотрим проблему нахождения первого палиндрома в списке слов. Палиндром - это слово, которое читается одинаково как слева направо, так и справа налево. Вот необходимые объявления: + + def isPalindrome(x: String) = x == x.reverse + def findPalindrome(s: Seq[String]) = s find isPalindrome + +Теперь предположим, что у вас очень длинная последовательность слов и вы хотите найти палиндром в первых миллионах слов этой последовательности. Можете ли вы повторно переиспользовать `findPalindrome`? Конечно, вы можете написать: + + findPalindrome(words take 1000000) + +Что прекрасно разделяет два аспекта: взятие первого миллиона слов последовательности и нахождение в ней палиндрома. Недостатком является то, что создается промежуточная последовательность, состоящая из одного миллиона слов, даже если первое слово из этой последовательности уже является палиндромным. Таким образом, возможно, 999'999 слов будут скопированы в промежуточный результат без последующей обработки. Многие программисты сдались бы здесь и написали бы свою собственную специализированную версию поиска палиндромов из заданного префикса последовательности аргументов. Но теперь с отображением, это не требуется делать. Достаточно написать: + + findPalindrome(words.view take 1000000) + +Такой подход имеет такое же хорошее разделение аспектов, но вместо последовательности в миллион элементов он строит только один легковесный объект отображения. Таким образом, вам не нужно выбирать между производительностью и модульностью. + +Увидев все эти изящные свособы отображения, вы можете задаться вопросом, зачем вообще нужен строгий способ создания коллекции? Одна из причин в том, что для производительности не всегда ленивость лучше строгости. При малых размерах коллекции дополнительные накладные расходы, связанные с формированием и применением замыканий в отображениях, часто превышают выгоду от отсутствия промежуточных структур данных. Вероятно, более важной причиной является то, что вычисления в отображениях могут оказаться очень запутанными для разработчика, если отложенные операции имеют побочные эффекты. + +Приведу пример, который вызывал боль у пользователей Scala до версии 2.8. В прежних версиях тип `Range` был ленивым, он вел себя также как отображение. Люди пытались создать ряд сущностей (`actors`) как в примере: + + val actors = for (i <- 1 to 10) yield actor { ... } + +Они были озадачены тем, что ни один из actors не исполнялся, хотя их метод должен был создавать и запускать `actor` из кода, заключенного в фигурные скобки идущие следом. Чтобы объяснить, почему ничего не происходило, напомним, что выражению выше равнозначно применению мапы: + + val actors = (1 to 10) map (i => actor { ... }) + +Так как диапазон, созданный с помощью `(1 to 10)`, вел себя как отображение, результат мапы снова был отображением. То есть элемент не вычислялся, а значит `actor` не создавался! Они могли бы быть созданы путем принудительного вычисления всего диапазона, но это было не таким уж и очевидным решением. + +Чтобы избежать подобных сюрпризов, в текущей библиотеке коллекций Scala действуют более привычные правила. Все коллекции, кроме ленивых списков и отображений, строгие. Единственный способ перейти от строгой коллекции к ленивой - метод `view`. Единственный способ вернуться обратно - использовать `to`. Таким образом, приведенное в примере объявление `actors` теперь будет вести себя так, как ожидалось, создавая и запуская 10 `actors`. Чтобы вернуть прежнее неочевидное поведение, необходимо добавить явный вызов метода `view`: + + val actors = for (i <- (1 to 10).view) yield actor { ... } + +Таким образом, отображения являются мощным инструментом для совмещения аспектов эффективности кода с необходимостью сохранения модульной разработки. Но чтобы не запутаться в аспектах отложенных вычислений, следует ограничить работу отображений только чистым функциональным кодом, в которых у преобразований коллекций нет побочных эффектов. Лучше всего избегать смешения отображений с операциями, которые создают новые коллекции и в то же время имеют побочные эффекты. diff --git a/_ru/overviews/collections/introduction.md b/_ru/overviews/collections/introduction.md new file mode 100644 index 0000000000..5b996a9254 --- /dev/null +++ b/_ru/overviews/collections/introduction.md @@ -0,0 +1,65 @@ +--- +layout: multipage-overview +title: Введение +partof: collections +overview-name: Collections +num: 1 +language: ru +--- + +**Martin Odersky и Lex Spoon** + +Популярно мнение, что новые коллекции это самое значимое изменение в Scala версии 2.8. +В Scala и раньше были коллекции (и на самом деле, новая модель +во многом совместима с прежней). Но только начиная с версии 2.8 +появилась единая, общая и всеобъемлющая база для всех типов коллекций. + +Несмотря на то, что улучшения коллекций на первый взгляд едва заметны, они могут привести к существенному изменению в вашем стиле программирования. +Теперь чаще, при работе на высоком уровне, вся коллекция становится базовым строительным блоком вашей программы, а не её отдельные элементы. + +К такому стилю программирования необходимо небольшое привыкание. +К счастью, адаптация облегчается приятными свойствами характерными для новых коллекций Scala. +Они обладают простотой в использовании, лаконичностью, безопасностью и универсальностью. + +**Простота:** Небольшого набора из 20-50 методов достаточно для решения большинства задач. +Нет необходимости использовать запутанные циклы или рекурсии. +Персистентные коллекции и операции без побочных эффектов означают, +что вам не нужно беспокоиться о случайном повреждении существующих коллекций новыми данными. +Больше нет путаницы из-за использования итераторов и одновременного изменения коллекций. + +**Лаконичность:** Одной командой можно достичь, столько же, сколько обычно получают используя несколько вложенных операций с циклами. +Вы можете выразить функциональные операции с помощью простого синтаксиса и с легкостью сочетать операции, создавая ощущение +работы со специализированным под задачу языком. + +**Безопасность:** Требуется определенный опыт, чтоб погрузится в эту специфику. +Статически типизированная и функциональная природа коллекций Scala подразумевает, что подавляющее большинство ошибок, которые вы можете совершить, будут пойманы во время компиляции. +Это потому что: + 1. Коллекции сами по себе очень активно используются, поэтому хорошо протестированы. + 2. Использование операции в коллекциях создает явное описание того, что мы ожидаем для входящих данных и для результата. + 3. Это явное описание для входа и результата подвергается статической проверке типа. В результате подавляющее большинство проблем будет проявляться в виде ошибок типов. +Поэтому запуск программ из нескольких сотен строк, с первого раза, вполне типичная ситуация. + + +**Скорость:** Все операции в коллекциях уже настроены и оптимизированы. В результате, работа коллекций получается очень эффективной. +Можно конечно сделать немного более эффективную настройку структур данных и операций с ними, но при этом, +вероятно, вы получите хуже эффективность в непосредственной реализации и использовании. +Кроме того, коллекции оптимизированы для параллельного исполнения на нескольких ядрах. Параллельные коллекции поддерживают те же операции, что и последовательные, поэтому нет необходимости в изучении новых операций или переписывании кода. +Вы можете превратить последовательную коллекцию в параллельную просто вызвав метод `par`. + +**Универсальность:** Коллекции обеспечивают одинаковые операции на любом типе коллекций, где это имеет смысл. Таким образом, можно достичь многого, имея сравнительно небольшой набор операций. Например строка, в принципе, представляет собой последовательность символов. Следовательно, в коллекциях Scala строки поддерживают все операции которые есть у последовательностей (`Seq`). То же самое относится и к массивам. + +**Пример:** Вот лишь одна строчка кода, демонстрирующая преимущества Scala коллекций. + + val (minors, adults) = people partition (_.age < 18) + +Сразу становится понятно, что делает эта строчка: она разделяет коллекцию людей `people` на несовершеннолетних `minors` и взрослых `adults` в зависимости от возраста `age`. +Поскольку метод `partition` определен в базовом типе коллекции `TraversableLike`, этот код работает для любого типа коллекций, включая массивы. +Полученные в результате коллекции `minors` и `adults` будут иметь тот же тип, что и коллекция `people` . + +Этот код намного лаконичнее, чем несколько циклов, необходимых для того, чтоб провести обработку традиционным методом +(три цикла для массива, т.к. промежуточные результаты должны быть сохранены где-то в другом месте). +Как только вы освоите базовую схему работы с коллекциями, вы оцените на сколько проще и безопаснее написание такого кода, в отличии от более низкоуровневого кода с циклами. +Кроме того, сама операция `partition` работает довольно быстро и будет работать еще быстрее на многоядерных процессорах при использовании параллельных коллекций. (Параллельные коллекции стали частью Scala начиная с версии 2.9.) + +В этом разделе подробно рассматриваются API классов коллекций Scala с пользовательской точки зрения. +Вы также познакомитесь со всеми фундаментальными классами и методами, которые есть у коллекций. diff --git a/_ru/overviews/index.md b/_ru/overviews/index.md new file mode 100644 index 0000000000..6d38ca706a --- /dev/null +++ b/_ru/overviews/index.md @@ -0,0 +1,8 @@ +--- +layout: overviews +partof: overviews +title: Документация +language: ru +--- + + diff --git a/_ru/overviews/parallel-collections/architecture.md b/_ru/overviews/parallel-collections/architecture.md index d7652bb896..1e8fbbf37c 100644 --- a/_ru/overviews/parallel-collections/architecture.md +++ b/_ru/overviews/parallel-collections/architecture.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Архитектура библиотеки параллельных коллекций - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -51,7 +48,7 @@ _Примечание:_ Если есть два `Combiner`а, `c1` и `c2` гд Параллельные коллекции Scala во многом созданы под влиянием дизайна библиотеки (последовательных) коллекций Scala. На рисунке ниже показано, что их дизайн фактически отражает соответствующие трейты фреймворка обычных коллекций. -[]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png) +[parallel Collections Hierarchy]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png)
            Иерархия библиотеки Scala: коллекции и параллельные коллекции

            @@ -67,4 +64,4 @@ _Примечание:_ Если есть два `Combiner`а, `c1` и `c2` гд 1. [On a Generic Parallel Collection Framework, Aleksandar Prokopec, Phil Bawgell, Tiark Rompf, Martin Odersky, June 2011][1] -[1]: http://infoscience.epfl.ch/record/165523/files/techrep.pdf "flawed-benchmark" +[1]: https://infoscience.epfl.ch/record/165523/files/techrep.pdf "flawed-benchmark" diff --git a/_ru/overviews/parallel-collections/concrete-parallel-collections.md b/_ru/overviews/parallel-collections/concrete-parallel-collections.md index f0985016b8..1bda571a82 100644 --- a/_ru/overviews/parallel-collections/concrete-parallel-collections.md +++ b/_ru/overviews/parallel-collections/concrete-parallel-collections.md @@ -1,19 +1,15 @@ --- layout: multipage-overview title: Конкретные классы параллельных коллекций - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 2 --- ## Параллельный Массив -Последовательность [ParArray](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/mutable/ParArray.html) хранит линейный массив смежно хранимых элементов. Это означает, что получение доступа и обновление элементов эффективно, так как происходит путем изменения массива, лежащего в основе. По этой причине наиболее эффективна последовательная обработка элементов одного за другим. Параллельные массивы похожи на обычные в том отношении, что их размер постоянен. +Последовательность [ParArray](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/mutable/ParArray.html) хранит линейный массив смежно хранимых элементов. Это означает, что получение доступа и обновление элементов эффективно, так как происходит путем изменения массива, лежащего в основе. По этой причине наиболее эффективна последовательная обработка элементов одного за другим. Параллельные массивы похожи на обычные в том отношении, что их размер постоянен. scala> val pa = scala.collection.parallel.mutable.ParArray.tabulate(1000)(x => 2 * x + 1) pa: scala.collection.parallel.mutable.ParArray[Int] = ParArray(1, 3, 5, 7, 9, 11, 13,... @@ -30,7 +26,7 @@ num: 2 ## Параллельный вектор -[ParVector](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/immutable/ParVector.html) является неизменяемой последовательностью, временная сложность доступа и обновления которой является логарифмической с низкой константой-множителем. +[ParVector](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/immutable/ParVector.html) является неизменяемой последовательностью, временная сложность доступа и обновления которой является логарифмической с низкой константой-множителем. scala> val pv = scala.collection.parallel.immutable.ParVector.tabulate(1000)(x => x) pv: scala.collection.parallel.immutable.ParVector[Int] = ParVector(0, 1, 2, 3, 4, 5, 6, 7, 8, 9,... @@ -41,23 +37,23 @@ num: 2 Неизменяемые векторы представлены 32-ичными деревьями (32-way trees), поэтому [разделители]({{ site.baseurl }}/ru/overviews/parallel-collections/architecture.html) разбивают их, назначая по поддереву каждому новому разделителю. [Компоновщики]({{ site.baseurl }}/ru/overviews/parallel-collections/architecture.html) в настоящий момент хранят вектор из элементов и компонуют путем отложенного копирования. По этой причине методы трансформации менее масштабируемы по сравнению с теми же методами параллельного массива. Как только в будущем релизе Scala станет доступной операция конкатенации векторов, компоновщики станут образовываться путем конкатенации, и от этого методы трансформации станут гораздо более эффективными. -Параллельный вектор является параллельным аналогом последовательной коллекции [Vector](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html), и преобразования одного в другое занимают постоянное время. +Параллельный вектор является параллельным аналогом последовательной коллекции [Vector](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html), и преобразования одного в другое занимают постоянное время. ## Параллельный диапазон -[ParRange](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParRange.html) представляет собой упорядоченную последовательность элементов, отстоящих друг от друга на одинаковые промежутки. Параллельный диапазон создается подобно последовательному [Range](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Range.html): +[ParRange](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParRange.html) представляет собой упорядоченную последовательность элементов, отстоящих друг от друга на одинаковые промежутки. Параллельный диапазон создается подобно последовательному [Range](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html): - scala> 1 to 3 par + scala> (1 to 3).par res0: scala.collection.parallel.immutable.ParRange = ParRange(1, 2, 3) - scala> 15 to 5 by -2 par + scala> (15 to 5 by -2).par res1: scala.collection.parallel.immutable.ParRange = ParRange(15, 13, 11, 9, 7, 5) Подобно тому, как последовательные диапазоны не имеют строителей, параллельные диапазоны не имеют [компоновщиков]({{ site.baseurl }}/ru/overviews/parallel-collections/architecture.html). При создании отображения (mapping) элементов параллельного диапазона получается параллельный вектор. Последовательные и параллельные диапазоны могут эффективно преобразовываться друг в друга вызовами методов `seq` и `par`. ## Параллельные хэш-таблицы -В основе параллельной хэш-таблицы лежит массив, причем место элемента таблицы в этом массиве определяется хэш-кодом элемента. На хэш-таблицах основаны параллельные изменяемые хэш-множества ([mutable.ParHashSet](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/mutable/ParHashSet.html)) и параллельные изменяемые ассоциативные хэш-массивы (хэш-отображения) ([mutable.ParHashMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/mutable/ParHashMap.html)). +В основе параллельной хэш-таблицы лежит массив, причем место элемента таблицы в этом массиве определяется хэш-кодом элемента. На хэш-таблицах основаны параллельные изменяемые хэш-множества ([mutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParHashSet.html)) и параллельные изменяемые ассоциативные хэш-массивы (хэш-отображения) ([mutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/mutable/ParHashMap.html)). scala> val phs = scala.collection.parallel.mutable.ParHashSet(1 until 2000: _*) phs: scala.collection.parallel.mutable.ParHashSet[Int] = ParHashSet(18, 327, 736, 1045, 773, 1082,... @@ -71,12 +67,12 @@ num: 2 ## Параллельные префиксные хэш-деревья (Hash Tries) -Параллельные префиксные хэш-деревья являются параллельным аналогом неизменяемых префиксных хэш-деревьев, которые используются для эффективного представления неизменяемых множеств и ассоциативных массивов. Последние представлены классами [immutable.ParHashSet](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/parallel/immutable/ParHashSet.html) и [immutable.ParHashMap](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/immutable/ParHashMap.html). +Параллельные префиксные хэш-деревья являются параллельным аналогом неизменяемых префиксных хэш-деревьев, которые используются для эффективного представления неизменяемых множеств и ассоциативных массивов. Последние представлены классами [immutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParHashSet.html) и [immutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/immutable/ParHashMap.html). scala> val phs = scala.collection.parallel.immutable.ParHashSet(1 until 1000: _*) phs: scala.collection.parallel.immutable.ParHashSet[Int] = ParSet(645, 892, 69, 809, 629, 365, 138, 760, 101, 479,... - scala> phs map { x => x * x } sum + scala> phs.map(x => x * x).sum res0: Int = 332833500 [Компоновщики]({{ site.baseurl }}/overviews/parallel-collections/architecture.html) параллельных хэш-деревьев действуют аналогично компоновщикам хэш-таблиц, а именно предварительно распределяют элементы по блокам, а после этого параллельно составляют результирующее хэш-дерево, назначая обработку различных блоков разным процессорам, каждый из которых независимо собирает свое поддерево. @@ -85,26 +81,26 @@ num: 2 ## Параллельные многопоточные префиксные деревья (Concurrent Tries) -Параллельным аналогом коллекции [concurrent.TrieMap](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/concurrent/TrieMap.html), представляющей собой многопоточный и потокозащищеный ассоциативный массив, является коллекция [mutable.ParTrieMap](http://www.scala-lang.org/api/{{ site.scala-version}}/scala/collection/parallel/mutable/ParTrieMap.html). В то время, как большинство многопоточных структур данных не гарантируют правильного перебора элементов в случае, если эта структура данных была изменена во время ее прохождения, многопоточные деревья `Ctries` гарантируют, что обновленные данные станут видны только при следующем прохождении. Это означает, что можно изменять многопоточное дерево прямо во время прохождения, как в следующем примере, в котором выводятся квадратные корни от 1 до 99: +Параллельным аналогом коллекции [concurrent.TrieMap](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/concurrent/TrieMap.html), представляющей собой многопоточный и потокозащищеный ассоциативный массив, является коллекция [mutable.ParTrieMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParTrieMap.html). В то время, как большинство многопоточных структур данных не гарантируют правильного перебора элементов в случае, если эта структура данных была изменена во время ее прохождения, многопоточные деревья `Ctries` гарантируют, что обновленные данные станут видны только при следующем прохождении. Это означает, что можно изменять многопоточное дерево прямо во время прохождения, как в следующем примере, в котором выводятся квадратные корни от 1 до 99: scala> val numbers = scala.collection.parallel.mutable.ParTrieMap((1 until 100) zip (1 until 100): _*) map { case (k, v) => (k.toDouble, v.toDouble) } numbers: scala.collection.parallel.mutable.ParTrieMap[Double,Double] = ParTrieMap(0.0 -> 0.0, 42.0 -> 42.0, 70.0 -> 70.0, 2.0 -> 2.0,... scala> while (numbers.nonEmpty) { | numbers foreach { case (num, sqrt) => - | val nsqrt = 0.5 * (sqrt + num / sqrt) - | numbers(num) = nsqrt - | if (math.abs(nsqrt - sqrt) < 0.01) { - | println(num, nsqrt) - | numbers.remove(num) - | } - | } - | } - (1.0,1.0) + | val nsqrt = 0.5 * (sqrt + num / sqrt) + | numbers(num) = nsqrt + | if (math.abs(nsqrt - sqrt) < 0.01) { + | println(num, nsqrt) + | numbers.remove(num) + | } + | } + | } + (1.0,1.0) (2.0,1.4142156862745097) (7.0,2.64576704419029) (4.0,2.0000000929222947) - ... + ... [Компоновщики]({{ site.baseurl }}/ru/overviews/parallel-collections/architecture.html) реализованы как `TrieMap`-- так как эта структура является многопоточной, при вызове метода трансформации создается только один компоновщик, разделяемый всеми процессорами. @@ -114,53 +110,52 @@ num: 2 Характеристики производительности последовательных типов (sequence types): -| | head | tail | apply | update| prepend | append | insert | -| -------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | -| `ParArray` | C | L | C | C | L | L | L | -| `ParVector` | eC | eC | eC | eC | eC | eC | - | -| `ParRange` | C | C | C | - | - | - | - | +| | head | tail | apply | update | prepend | append | insert | +| ----------- | ---- | ---- | ----- | ------ | ------- | ------ | ------ | +| `ParArray` | C | L | C | C | L | L | L | +| `ParVector` | eC | eC | eC | eC | eC | eC | - | +| `ParRange` | C | C | C | - | - | - | - | Характеристики производительности множеств (set) и ассоциативных массивов (map): -| | lookup | add | remove | -| -------- | ---- | ---- | ---- | -| **неизменяемые** | | | | -| `ParHashSet`/`ParHashMap`| eC | eC | eC | -| **изменяемые** | | | | -| `ParHashSet`/`ParHashMap`| C | C | C | -| `ParTrieMap` | eC | eC | eC | - +| | lookup | add | remove | +| ------------------------- | ------ | --- | ------ | +| **неизменяемые** | | | | +| `ParHashSet`/`ParHashMap` | eC | eC | eC | +| **изменяемые** | | | | +| `ParHashSet`/`ParHashMap` | C | C | C | +| `ParTrieMap` | eC | eC | eC | ### Расшифровка Обозначения в двух представленных выше таблицах означают следующее: -| | | -| --- | ---- | -| **C** | Операция (быстрая) выполняется за постоянное время. | -| **eC** | Операция выполняется за фактически постоянное время, но только при соблюдении некоторых предположений, например о максимальной длине вектора или распределении хэш-кодов.| +| | | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **C** | Операция (быстрая) выполняется за постоянное время. | +| **eC** | Операция выполняется за фактически постоянное время, но только при соблюдении некоторых предположений, например о максимальной длине вектора или распределении хэш-кодов. | | **aC** | Операция выполняется за амортизированное постоянное время. Некоторые вызовы операции могут выполняться медленнее, но при подсчете времени выполнения большого количества операций выходит, что в среднем на операцию требуется постоянное время. | -| **Log** | Операция занимает время, пропорциональное логарифму размера коллекции. | -| **L** | Операция линейна, то есть занимает время, пропорциональное размеру коллекции. | -| **-** | Операция не поддерживается. | +| **Log** | Операция занимает время, пропорциональное логарифму размера коллекции. | +| **L** | Операция линейна, то есть занимает время, пропорциональное размеру коллекции. | +| **-** | Операция не поддерживается. | Первая таблица трактует последовательные типы-- изменяемые и неизменяемые-- в контексте выполнения следующих операций: -| | | -| --- | ---- | -| **head** | Получение первого элемента последовательности. | -| **tail** | Получение новой последовательности, состоящей из всех элементов исходной, кроме первого. | -| **apply** | Индексирование. | -| **update** | Функциональное обновление (с помощью `updated`) для неизменяемых последовательностей, обновление с побочными действиями (с помощью `update`) для изменяемых. | -| **prepend**| Добавление элемента в начало последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | -| **append** | Добавление элемента в конец последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | -| **insert** | Вставка элемента в выбранную позицию последовательности. Поддерживается только изменяемыми последовательностями. | +| | | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **head** | Получение первого элемента последовательности. | +| **tail** | Получение новой последовательности, состоящей из всех элементов исходной, кроме первого. | +| **apply** | Индексирование. | +| **update** | Функциональное обновление (с помощью `updated`) для неизменяемых последовательностей, обновление с побочными действиями (с помощью `update`) для изменяемых. | +| **prepend** | Добавление элемента в начало последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | +| **append** | Добавление элемента в конец последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | +| **insert** | Вставка элемента в выбранную позицию последовательности. Поддерживается только изменяемыми последовательностями. | Вторая таблица рассматривает изменяемые и неизменяемые множества и ассоциативные массивы в контексте следующих операций: -| | | -| --- | ---- | +| | | +| ---------- | ---------------------------------------------------------------------------------------------- | | **lookup** | Проверка принадлежности элемента множеству, или получение значения, ассоциированного с ключом. | -| **add** | Добавление нового элемента во множество или новой пары ключ/значение в ассоциативный массив. | -| **remove** | Удаление элемента из множества или ключа из ассоциативного массива. | -| **min** | Минимальный элемент множества или минимальный ключ ассоциативного массива. | +| **add** | Добавление нового элемента во множество или новой пары ключ/значение в ассоциативный массив. | +| **remove** | Удаление элемента из множества или ключа из ассоциативного массива. | +| **min** | Минимальный элемент множества или минимальный ключ ассоциативного массива. | diff --git a/_ru/overviews/parallel-collections/configuration.md b/_ru/overviews/parallel-collections/configuration.md index 9b616f8367..253c4c30d5 100644 --- a/_ru/overviews/parallel-collections/configuration.md +++ b/_ru/overviews/parallel-collections/configuration.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Конфигурирование параллельных коллекций - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 7 --- @@ -57,4 +53,4 @@ num: 7 1. [On a Generic Parallel Collection Framework, June 2011][1] - [1]: http://infoscience.epfl.ch/record/165523/files/techrep.pdf "parallel-collections" + [1]: https://infoscience.epfl.ch/record/165523/files/techrep.pdf "parallel-collections" diff --git a/_ru/overviews/parallel-collections/conversions.md b/_ru/overviews/parallel-collections/conversions.md index 8579774ec9..f001762841 100644 --- a/_ru/overviews/parallel-collections/conversions.md +++ b/_ru/overviews/parallel-collections/conversions.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Преобразования параллельных коллекций - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 3 --- @@ -38,16 +34,16 @@ num: 3 Ниже приведена сводная таблица всех методов преобразования: -| Метод | Тип возвращаемого значения | -| -------------- | -------------------------- | -| `toArray` | `Array` | -| `toList` | `List` | -| `toIndexedSeq` | `IndexedSeq` | -| `toStream` | `Stream` | -| `toIterator` | `Iterator` | -| `toBuffer` | `Buffer` | -| `toTraversable`| `GenTraverable` | -| `toIterable` | `ParIterable` | -| `toSeq` | `ParSeq` | -| `toSet` | `ParSet` | -| `toMap` | `ParMap` | +| Метод | Тип возвращаемого значения | +| -------------- | --------------------------- | +| `toArray` | `Array` | +| `toList` | `List` | +| `toIndexedSeq` | `IndexedSeq` | +| `toStream` | `Stream` | +| `toIterator` | `Iterator` | +| `toBuffer` | `Buffer` | +| `toTraversable`| `GenTraversable` | +| `toIterable` | `ParIterable` | +| `toSeq` | `ParSeq` | +| `toSet` | `ParSet` | +| `toMap` | `ParMap` | diff --git a/_ru/overviews/parallel-collections/ctries.md b/_ru/overviews/parallel-collections/ctries.md index b463a48e21..640ac7e8b9 100644 --- a/_ru/overviews/parallel-collections/ctries.md +++ b/_ru/overviews/parallel-collections/ctries.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Многопоточные префиксные деревья - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 4 --- @@ -117,7 +113,7 @@ num: 4 3. [Методы вычисления квадратных корней][3] 4. [Симуляция игры "Жизнь"][4] - [1]: http://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf "Ctries-techreport" + [1]: https://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf "Ctries-techreport" [2]: http://lampwww.epfl.ch/~prokopec/ctries-snapshot.pdf "Ctries-snapshot" - [3]: http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method "babylonian-method" + [3]: https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method "babylonian-method" [4]: https://github.com/axel22/ScalaDays2012-TrieMap "game-of-life-ctries" diff --git a/_ru/overviews/parallel-collections/custom-parallel-collections.md b/_ru/overviews/parallel-collections/custom-parallel-collections.md index 6fd6fa9f58..4dbcdf7e96 100644 --- a/_ru/overviews/parallel-collections/custom-parallel-collections.md +++ b/_ru/overviews/parallel-collections/custom-parallel-collections.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Создание пользовательской параллельной коллекции - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 6 --- diff --git a/_ru/overviews/parallel-collections/overview.md b/_ru/overviews/parallel-collections/overview.md index 2d68d91d8d..e2b4bbcd7d 100644 --- a/_ru/overviews/parallel-collections/overview.md +++ b/_ru/overviews/parallel-collections/overview.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Обзор - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - num: 1 language: ru --- diff --git a/_ru/overviews/parallel-collections/performance.md b/_ru/overviews/parallel-collections/performance.md index f1ae027304..64e533e359 100644 --- a/_ru/overviews/parallel-collections/performance.md +++ b/_ru/overviews/parallel-collections/performance.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Измерение производительности - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - num: 8 language: ru --- @@ -184,5 +180,5 @@ language: ru 1. [Anatomy of a flawed microbenchmark, Brian Goetz][1] 2. [Dynamic compilation and performance measurement, Brian Goetz][2] - [1]: http://www.ibm.com/developerworks/java/library/j-jtp02225/index.html "flawed-benchmark" - [2]: http://www.ibm.com/developerworks/library/j-jtp12214/ "dynamic-compilation" + [1]: https://www.ibm.com/developerworks/java/library/j-jtp02225/index.html "flawed-benchmark" + [2]: https://www.ibm.com/developerworks/library/j-jtp12214/ "dynamic-compilation" diff --git a/_ru/scala3/book/ca-context-bounds.md b/_ru/scala3/book/ca-context-bounds.md new file mode 100644 index 0000000000..91c18c5101 --- /dev/null +++ b/_ru/scala3/book/ca-context-bounds.md @@ -0,0 +1,141 @@ +--- +layout: multipage-overview +title: Контекстные границы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлены контекстные границы в Scala 3. +language: ru +num: 62 +previous-page: ca-context-parameters +next-page: ca-given-imports +--- + +Во многих ситуациях имя [контекстного параметра]({% link _overviews/scala3-book/ca-context-parameters.md %}#context-parameters) +не нужно указывать явно, поскольку оно используется компилятором только в синтезированных аргументах для других параметров контекста. +В этом случае вам не нужно определять имя параметра, а можно просто указать тип. + +## Предыстория + +Например, рассмотрим метод `maxElement`, возвращающий максимальное значение в коллекции: + +{% tabs context-bounds-max-named-param class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +```scala +def maxElement[A](as: List[A])(implicit ord: Ord[A]): A = + as.reduceLeft(max(_, _)(ord)) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +def maxElement[A](as: List[A])(using ord: Ord[A]): A = + as.reduceLeft(max(_, _)(using ord)) +``` + +{% endtab %} + +{% endtabs %} + +Метод `maxElement` принимает _контекстный параметр_ типа `Ord[A]` только для того, +чтобы передать его в качестве аргумента методу `max`. + +Для полноты приведем определения `max` и `Ord` +(обратите внимание, что на практике мы будем использовать существующий метод `max` для `List`, +но мы создали этот пример для иллюстрации): + +{% tabs context-bounds-max-ord class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +```scala +/** Определяет, как сравнивать значения типа `A` */ +trait Ord[A] { + def greaterThan(a1: A, a2: A): Boolean +} + +/** Возвращает максимальное из двух значений */ +def max[A](a1: A, a2: A)(implicit ord: Ord[A]): A = + if (ord.greaterThan(a1, a2)) a1 else a2 +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +/** Определяет, как сравнивать значения типа `A` */ +trait Ord[A]: + def greaterThan(a1: A, a2: A): Boolean + +/** Возвращает максимальное из двух значений */ +def max[A](a1: A, a2: A)(using ord: Ord[A]): A = + if ord.greaterThan(a1, a2) then a1 else a2 +``` + +{% endtab %} + +{% endtabs %} + +Обратите внимание, что метод `max` принимает контекстный параметр типа `Ord[A]`, как и метод `maxElement`. + +## Пропуск контекстных аргументов + +Так как `ord` - это контекстный параметр в методе `max`, +компилятор может предоставить его для нас в реализации `maxElement` при вызове `max`: + +{% tabs context-bounds-context class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +```scala +def maxElement[A](as: List[A])(implicit ord: Ord[A]): A = + as.reduceLeft(max(_, _)) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +def maxElement[A](as: List[A])(using Ord[A]): A = + as.reduceLeft(max(_, _)) +``` + +Обратите внимание: поскольку нам не нужно явно передавать его методу `max`, +мы можем не указывать его имя в определении метода `maxElement`. +Это _анонимный параметр контекста_. + +{% endtab %} + +{% endtabs %} + +## Границы контекста + +Учитывая написанное выше, _привязка к контексту_ — это сокращенный синтаксис +для выражения шаблона "параметр контекста, применяемый к параметру типа". + +Используя привязку к контексту, метод `maxElement` можно записать следующим образом: + +{% tabs context-bounds-max-rewritten %} + +{% tab 'Scala 2 и 3' %} + +```scala +def maxElement[A: Ord](as: List[A]): A = + as.reduceLeft(max(_, _)) +``` + +{% endtab %} + +{% endtabs %} + +Привязка типа `: Ord` к параметру типа `A` метода или класса указывает на параметр контекста с типом `Ord[A]`. +Под капотом компилятор преобразует этот синтаксис в тот, который показан в разделе "Предыстория". + +Дополнительные сведения о границах контекста см. в разделе ["Что такое границы контекста?"]({% link _overviews/FAQ/index.md %}#what-are-context-bounds) раздел FAQ по Scala. diff --git a/_ru/scala3/book/ca-context-parameters.md b/_ru/scala3/book/ca-context-parameters.md new file mode 100644 index 0000000000..dc66f2fc98 --- /dev/null +++ b/_ru/scala3/book/ca-context-parameters.md @@ -0,0 +1,196 @@ +--- +layout: multipage-overview +title: Параметры контекста +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как объявлять параметры контекста и как компилятор выводит их на стороне вызова. +language: ru +num: 61 +previous-page: ca-extension-methods +next-page: ca-context-bounds +--- + +Scala предлагает две важные функции для контекстной абстракции: + +- **Параметры контекста** позволяют указать параметры, которые на стороне вызова могут быть опущены программистом + и должны автоматически предоставляться контекстом. +- **Экземпляры given** (в Scala 3) или **неявные определения** (в Scala 2) — это термины, + которые компилятор Scala может использовать для заполнения отсутствующих аргументов. + +## Параметры контекста + +При проектировании системы зачастую необходимо предоставлять контекстную информацию, +такую как конфигурация или настройки, различным компонентам вашей системы. +Одним из распространенных способов добиться этого является передача конфигурации +в качестве дополнительного аргумента методам. + +В следующем примере мы определяем кейс класс `Config` для моделирования некоторой конфигурации веб-сайта +и передаем ее в различных методах. + +{% tabs example %} +{% tab 'Scala 2 и 3' %} + +```scala +case class Config(port: Int, baseUrl: String) + +def renderWebsite(path: String, config: Config): String = + "" + renderWidget(List("cart"), config) + "" + +def renderWidget(items: List[String], config: Config): String = ??? + +val config = Config(8080, "docs.scala-lang.org") +renderWebsite("/home", config) +``` + +{% endtab %} +{% endtabs %} + +Предположим, что конфигурация не меняется на протяжении большей части нашей кодовой базы. +Передача `config` каждому вызову метода (например `renderWidget`) становится очень утомительной +и делает нашу программу более трудной для чтения, поскольку нам нужно игнорировать аргумент `config`. + +### Установка параметров как контекстных + +Мы можем пометить некоторые параметры наших методов как _контекстные_. + +{% tabs 'contextual-parameters' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def renderWebsite(path: String)(implicit config: Config): String = + "" + renderWidget(List("cart")) + "" + // ^ + // аргумент config больше не требуется + +def renderWidget(items: List[String])(implicit config: Config): String = ??? +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def renderWebsite(path: String)(using config: Config): String = + "" + renderWidget(List("cart")) + "" + // ^ + // аргумент config больше не требуется + +def renderWidget(items: List[String])(using config: Config): String = ??? +``` + +{% endtab %} +{% endtabs %} + +Начав секцию параметров с ключевого слова `using` в Scala 3 или `implicit` в Scala 2, мы сообщаем компилятору, +что на стороне вызова он должен автоматически найти аргумент с необходимым типом. +Таким образом, компилятор Scala выполняет **вывод термов**. + +При вызове `renderWidget(List("cart"))` компилятор Scala увидит, что в области видимости есть терм типа `Config` +(в нашем случае - `config`) и автоматически предоставит его для `renderWidget`. +Таким образом, программа эквивалентна приведенной выше. + +На самом деле, поскольку в реализации `renderWebsite` больше не нужно ссылаться на `config`, +мы можем даже опустить его имя в подписи в Scala 3: + +{% tabs 'anonymous' %} +{% tab 'Только в Scala 3' %} + +```scala +// нет необходимости придумывать имя параметра +// vvvvvvvvvvvvv +def renderWebsite(path: String)(using Config): String = + "" + renderWidget(List("cart")) + "" +``` + +{% endtab %} +{% endtabs %} + +В Scala 2 именовать неявные параметры по-прежнему необходимо. + +### Явное указание контекстных параметров + +Мы увидели, как _абстрагироваться_ от контекстных параметров +и что компилятор Scala может автоматически предоставлять нам аргументы. +Но как мы можем указать, какую конфигурацию использовать для нашего вызова `renderWebsite`? + +{% tabs 'explicit' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +Мы явно указываем значение аргумента, как если бы это был обычный аргумент: + +```scala +renderWebsite("/home")(config) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +Подобно тому, как мы указали наш раздел параметров с помощью `using`, +мы также можем явно указать контекстные параметры с помощью `using`: + +```scala +renderWebsite("/home")(using config) +``` + +{% endtab %} +{% endtabs %} + +Явное предоставление контекстных параметров может быть полезно, +когда у нас в области видимости есть несколько разных значений, +подходящих по типу, и мы хотим убедиться в корректности передачи параметра методу. + +Для всех остальных случаев, как мы увидим в следующем разделе, +есть еще один способ ввести контекстуальные значения в область видимости. + +## Экземпляры given (определения implicit в Scala 2) + +Мы видели, что можем явно передавать аргументы в качестве контекстных параметров. +Однако, если для определенного типа существует _единственное каноническое значение_, +есть другой предпочтительный способ сделать его доступным для компилятора Scala: +пометив его как `given` в Scala 3 или `implicit` в Scala 2. + +{% tabs 'instances' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +implicit val config: Config = Config(8080, "docs.scala-lang.org") +// ^^^^^^ +// это значение, которое выведет компилятор Scala +// в качестве аргумента контекстного параметра типа Config +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val config = Config(8080, "docs.scala-lang.org") + +// это тип, который мы хотим предоставить для канонического значения +// vvvvvv +given Config = config +// ^^^^^^ +// это значение, которое выведет компилятор Scala +// в качестве аргумента контекстного параметра типа Config +``` + +{% endtab %} +{% endtabs %} + +В приведенном выше примере мы указываем, что всякий раз, +когда в текущей области видимости опущен контекстный параметр типа `Config`, +компилятор должен вывести `config` в качестве аргумента. + +Определив каноническое значение для типа `Config`, +мы можем вызвать `renderWebsite` следующим образом: + +```scala +renderWebsite("/home") +// ^ +// снова без аргумента +``` + +Подробное руководство о том, где Scala ищет канонические значения, можно найти в [FAQ]({% link _overviews/FAQ/index.md %}#where-does-scala-look-for-implicits). + +[reference]: {{ site.scala3ref }}/overview.html +[blog-post]: /2020/11/06/explicit-term-inference-in-scala-3.html diff --git a/_ru/scala3/book/ca-contextual-abstractions-intro.md b/_ru/scala3/book/ca-contextual-abstractions-intro.md new file mode 100644 index 0000000000..eef3910c30 --- /dev/null +++ b/_ru/scala3/book/ca-contextual-abstractions-intro.md @@ -0,0 +1,96 @@ +--- +layout: multipage-overview +title: Контекстные абстракции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе представлено введение в концепцию контекстных абстракций Scala 3. +language: ru +num: 59 +previous-page: types-others +next-page: ca-extension-methods +--- + +## Предпосылка + +Контекстные абстракции — это способ абстрагироваться от контекста. +Они представляют собой единую парадигму с большим разнообразием вариантов использования, среди которых: + +- реализация тайп классов (_type classes_) +- установление контекста +- внедрение зависимости (_dependency injection_) +- выражение возможностей +- вычисление новых типов и доказательство взаимосвязей между ними + +В этом отношении Scala оказала влияние на другие языки. Например, трейты в Rust или protocol extensions Swift. +Предложения по дизайну также представлены для Kotlin в качестве разрешения зависимостей во время компиляции, +для C# в качестве Shapes и Extensions или для F# в качестве Traits. +Контекстные абстракции также являются общей особенностью средств доказательства теорем, таких как Coq или Agda. + +Несмотря на то, что в этих проектах используется разная терминология, +все они являются вариантами основной идеи вывода терминов (term inference): +учитывая тип, компилятор синтезирует "канонический" термин, который имеет этот тип. + +## Редизайн в Scala 3 + +В Scala 2 контекстные абстракции поддерживаются пометкой `implicit` определений (методов и значений) или параметров +(см. [Параметры контекста]({% link _overviews/scala3-book/ca-context-parameters.md %})). + +Scala 3 включает в себя переработку контекстных абстракций. +Хотя эти концепции постепенно "открывались" в Scala 2, теперь они хорошо известны и понятны, и редизайн использует эти знания. + +Дизайн Scala 3 фокусируется на **намерении**, а не на **механизме**. +Вместо того, чтобы предлагать одну очень мощную функцию имплицитов, +Scala 3 предлагает несколько функций, ориентированных на варианты использования: + +- **Расширение классов задним числом**. + В Scala 2 методы расширения должны были кодироваться с использованием [неявных преобразований][implicit-conversions] или [неявных классов]({% link _overviews/core/implicit-classes.md %}). + Напротив, в Scala 3 [методы расширения][extension-methods] теперь встроены непосредственно в язык, что приводит к улучшению сообщений об ошибках и улучшению вывода типов. + +- **Абстрагирование контекстной информации**. + [Предложения Using][givens] позволяют программистам абстрагироваться от информации, + которая доступна в контексте вызова и должна передаваться неявно. + В качестве улучшения по сравнению со Scala 2 подразумевается, что предложения using могут быть указаны по типу, + освобождая сигнатуры функций от имен переменных, на которые никогда не ссылаются явно. + +- **Предоставление экземпляров тайп-классов**. + [Given экземпляры][givens] позволяют программистам определять _каноническое значение_ определенного типа. + Это делает программирование с [тайп-классами][type-classes] более простым без утечек деталей реализации. + +- **Неявное преобразование одного типа в другой**. + Неявное преобразование было [переработано с нуля][implicit-conversions] как экземпляры тайп-класса `Conversion`. + +- **Контекстные абстракции высшего порядка**. + _Совершенно новая_ функция [контекстных функций][contextual-functions] делает контекстные абстракции объектами первого класса. + Они являются важным инструментом для авторов библиотек и позволяют выражать лаконичный DSL. + +- **Полезная обратная связь от компилятора**. + Если компилятор не может разрешить неявный параметр, теперь он предлагает [предложения по импорту](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html), которые могут решить проблему. + +## Преимущества + +Эти изменения в Scala 3 обеспечивают лучшее разделение вывода терминов от остального языка: + +- существует единственный способ определить данные +- существует единственный способ ввести неявные параметры и аргументы +- существует отдельный способ [импорта givens][given-imports], который не позволяет им прятаться в море обычного импорта +- существует единственный способ определить [неявное преобразование][implicit-conversions], которое четко обозначено как таковое и не требует специального синтаксиса + +К преимуществам этих изменений относятся: + +- новый дизайн позволяет избежать взаимодействия функций и делает язык более согласованным +- implicits становятся более легкими для изучения и более сложными для злоупотреблений +- значительно улучшается ясность 95% программ Scala, использующих implicits +- есть потенциал, чтобы сделать вывод термов однозначным способом, который также доступен и удобен. + +В этой главе в следующих разделах представлены многие из этих новых функций. + +[givens]: {% link _overviews/scala3-book/ca-context-parameters.md %} +[given-imports]: {% link _overviews/scala3-book/ca-given-imports.md %} +[implicit-conversions]: {% link _overviews/scala3-book/ca-implicit-conversions.md %} +[extension-methods]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[context-bounds]: {% link _overviews/scala3-book/ca-context-bounds.md %} +[type-classes]: {% link _overviews/scala3-book/ca-type-classes.md %} +[equality]: {% link _overviews/scala3-book/ca-multiversal-equality.md %} +[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html diff --git a/_ru/scala3/book/ca-extension-methods.md b/_ru/scala3/book/ca-extension-methods.md new file mode 100644 index 0000000000..6f530b141f --- /dev/null +++ b/_ru/scala3/book/ca-extension-methods.md @@ -0,0 +1,145 @@ +--- +layout: multipage-overview +title: Методы расширения +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлена работа методов расширения в Scala 3. +language: ru +num: 60 +previous-page: ca-contextual-abstractions-intro +next-page: ca-context-parameters +versionSpecific: true +--- + +В Scala 2 аналогичного результата можно добиться с помощью [неявных классов]({% link _overviews/core/implicit-classes.md %}). + +--- + +Методы расширения позволяют добавлять методы к типу после того, как он был определен, +т.е. они позволяют добавлять новые методы в закрытые классы. +Например, представьте, что кто-то создал класс `Circle`: + +{% tabs ext1 %} +{% tab 'Scala 2 и 3' %} + +```scala +case class Circle(x: Double, y: Double, radius: Double) +``` + +{% endtab %} +{% endtabs %} + +Теперь представим, что необходим метод `circumference`, но нет возможности изменить исходный код `Circle`. +До того как концепция вывода терминов была введена в языки программирования, +единственное, что можно было сделать, это написать метод в отдельном классе или объекте, подобном этому: + +{% tabs ext2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object CircleHelpers { + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object CircleHelpers: + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +``` + +{% endtab %} +{% endtabs %} + +Затем этот метод можно было использовать следующим образом: + +{% tabs ext3 %} +{% tab 'Scala 2 и 3' %} + +```scala +val aCircle = Circle(2, 3, 5) + +// без использования метода расширения +CircleHelpers.circumference(aCircle) +``` + +{% endtab %} +{% endtabs %} + +Но методы расширения позволяют создать метод `circumference` для работы с экземплярами `Circle`: + +{% tabs ext4 %} +{% tab 'Только в Scala 3' %} + +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 +``` + +{% endtab %} +{% endtabs %} + +В этом коде: + +- `Circle` — это тип, к которому будет добавлен метод расширения `circumference` +- Синтаксис `c: Circle` позволяет ссылаться на переменную `c` в методах расширения + +Затем в коде метод `circumference` можно использовать так же, как если бы он был изначально определен в классе `Circle`: + +{% tabs ext5 %} +{% tab 'Только в Scala 3' %} + +```scala +aCircle.circumference +``` + +{% endtab %} +{% endtabs %} + +### Импорт методов расширения + +Представим, что `circumference` определен в пакете `lib` - его можно импортировать с помощью + +{% tabs ext6 %} +{% tab 'Только в Scala 3' %} + +```scala +import lib.circumference + +aCircle.circumference +``` + +{% endtab %} +{% endtabs %} + +Если импорт отсутствует, то компилятор выводит подробное сообщение об ошибке, подсказывая возможный импорт, например так: + +```text +value circumference is not a member of Circle, but could be made available as an extension method. + +The following import might fix the problem: + + import lib.circumference +``` + +## Обсуждение + +Ключевое слово `extension` объявляет о намерении определить один или несколько методов расширения для типа, заключенного в круглые скобки. +Чтобы определить для типа несколько методов расширения, используется следующий синтаксис: + +{% tabs ext7 %} +{% tab 'Только в Scala 3' %} + +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` + +{% endtab %} +{% endtabs %} diff --git a/_ru/scala3/book/ca-given-imports.md b/_ru/scala3/book/ca-given-imports.md new file mode 100644 index 0000000000..41439a27be --- /dev/null +++ b/_ru/scala3/book/ca-given-imports.md @@ -0,0 +1,54 @@ +--- +layout: multipage-overview +title: Given импорты +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как работают операторы импорта 'given' в Scala 3. +language: ru +num: 63 +previous-page: ca-context-bounds +next-page: ca-type-classes +versionSpecific: true +--- + +Для большей ясности, откуда берутся данные в текущей области видимости, +для импорта экземпляров `given` используется специальная форма оператора `import`. +Базовая форма показана в этом примере: + +```scala +object A: + class TC + given tc: TC = ??? + def f(using TC) = ??? + +object B: + import A.* // импорт всех не-given элементов + import A.given // импорт экземпляров given +``` + +В этом коде предложение `import A.*` объекта `B` импортирует все элементы `A`, _кроме_ `given` экземпляра `tc`. +И наоборот, второй импорт, `import A.given`, импортирует _только_ экземпляр `given`. +Два предложения импорта также могут быть объединены в одно: + +```scala +object B: + import A.{given, *} +``` + +## Обсуждение + +Селектор с подстановочным знаком `*` помещает в область видимости все определения, кроме given-ов или расширений, +тогда как селектор `given` помещает в область видимости _все_ given-ы, включая те, которые являются результатом расширений. + +Эти правила имеют два основных преимущества: + +- понятнее, откуда берутся данные в текущей области видимости. + В частности, невозможно скрыть импортированные given-ы в длинном списке других импортов. +- есть возможность импортировать все given, не импортируя ничего другого. + Это важно, потому что given-ы могут быть анонимными, поэтому обычное использование именованного импорта нецелесообразно. + +Дополнительные примеры синтаксиса "import given" показаны в главе ["Пакеты и импорт"][imports]. + +[imports]: {% link _overviews/scala3-book/packaging-imports.md %} diff --git a/_ru/scala3/book/ca-implicit-conversions.md b/_ru/scala3/book/ca-implicit-conversions.md new file mode 100644 index 0000000000..f4703dc075 --- /dev/null +++ b/_ru/scala3/book/ca-implicit-conversions.md @@ -0,0 +1,236 @@ +--- +layout: multipage-overview +title: Неявное преобразование типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице демонстрируется, как реализовать неявное преобразование типов в Scala 3. +language: ru +num: 66 +previous-page: ca-multiversal-equality +next-page: ca-summary +--- + +Неявные преобразования — это мощная функция Scala, позволяющая пользователям предоставлять аргумент одного типа, +как если бы он был другого типа, чтобы избежать шаблонного преобразования. + +> Обратите внимание, что в Scala 2 неявные преобразования также использовались для предоставления дополнительных членов +> запечатанным классам (см. [Неявные классы]({% link _overviews/core/implicit-classes.md %})). +> В Scala 3 мы рекомендуем использовать эту функциональность, определяя методы расширения вместо неявных преобразований +> (хотя стандартная библиотека по-прежнему полагается на неявные преобразования по историческим причинам). + +## Пример + +Рассмотрим, например, метод `findUserById`, принимающий параметр типа `Long`: + +{% tabs implicit-conversions-1 %} +{% tab 'Scala 2 и 3' %} + +```scala +def findUserById(id: Long): Option[User] +``` + +{% endtab %} +{% endtabs %} + +Для краткости опустим определение типа `User` - это не имеет значения для нашего примера. + +В Scala есть возможность вызвать метод `findUserById` с аргументом типа `Int` вместо ожидаемого типа `Long`, +потому что аргумент будет неявно преобразован в тип `Long`: + +{% tabs implicit-conversions-2 %} +{% tab 'Scala 2 и 3' %} + +```scala +val id: Int = 42 +findUserById(id) // OK +``` + +{% endtab %} +{% endtabs %} + +Этот код не упадет с ошибкой компиляции “type mismatch: expected `Long`, found `Int`”, +потому что есть неявное преобразование, которое преобразует аргумент `id` в значение типа `Long`. + +## Детальное объяснение + +В этом разделе описывается, как определять и использовать неявные преобразования. + +### Определение неявного преобразования + +{% tabs implicit-conversions-3 class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +В Scala 2 неявное преобразование из типа `S` в тип `T` определяется [неявным классом]({% link _overviews/core/implicit-classes.md %}) `T`, +который принимает один параметр конструктора типа `S`, [неявное значение]({% link _overviews/scala3-book/ca-context-parameters.md %}) +типа функции `S => T` или неявный метод, преобразуемый в значение этого типа. + +Например, следующий код определяет неявное преобразование из `Int` в `Long`: + +```scala +import scala.language.implicitConversions + +implicit def int2long(x: Int): Long = x.toLong +``` + +Это неявный метод, преобразуемый в значение типа `Int => Long`. + +См. раздел "Остерегайтесь силы неявных преобразований" ниже для объяснения пункта `import scala.language.implicitConversions` в начале. +{% endtab %} + +{% tab 'Scala 3' %} +В Scala 3 неявное преобразование типа `S` в тип `T` определяется [`given` экземпляром]({% link _overviews/scala3-book/ca-context-parameters.md %}) +типа `scala.Conversion[S, T]`. +Для совместимости со Scala 2 его также можно определить неявным методом (подробнее читайте во вкладке Scala 2). + +Например, этот код определяет неявное преобразование из `Int` в `Long`: + +```scala +given int2long: Conversion[Int, Long] with + def apply(x: Int): Long = x.toLong +``` + +Как и другие given определения, неявные преобразования могут быть анонимными: + +```scala +given Conversion[Int, Long] with + def apply(x: Int): Long = x.toLong +``` + +Используя псевдоним, это можно выразить более кратко: + +```scala +given Conversion[Int, Long] = (x: Int) => x.toLong +``` + +{% endtab %} + +{% endtabs %} + +### Использование неявного преобразования + +Неявные преобразования применяются в двух случаях: + +1. Если выражение `e` имеет тип `S` и `S` не соответствует ожидаемому типу выражения `T`. +2. В выборе `e.m` с `e` типа `S`, где `S` не определяет `m` + (для поддержки [методов расширения][extension methods] в стиле Scala-2). + +В первом случае ищется конверсия `c`, применимая к `e` и тип результата которой соответствует `T`. + +В примере выше, когда мы передаем аргумент `id` типа `Int` в метод `findUserById`, +вставляется неявное преобразование `int2long(id)`. + +Во втором случае ищется преобразование `c`, применимое к `e` и результат которого содержит элемент с именем `m`. + +Примером является сравнение двух строк `"foo" < "bar"`. +В этом случае `String` не имеет члена `<`, поэтому вставляется неявное преобразование `Predef.augmentString("foo") < "bar"` +(`scala.Predef` автоматически импортируется во все программы Scala.). + +### Как неявные преобразования становятся доступными? + +Когда компилятор ищет подходящие преобразования: + +- во-первых, он смотрит в текущую лексическую область + - неявные преобразования, определенные в текущей области или во внешних областях + - импортированные неявные преобразования + - неявные преобразования, импортированные с помощью импорта подстановочных знаков (только в Scala 2) +- затем он просматривает [сопутствующие объекты][companion objects], _связанные_ с типом аргумента `S` или ожидаемым типом `T`. + Сопутствующие объекты, связанные с типом `X`: + - сам объект-компаньон `X` + - сопутствующие объекты, связанные с любым из унаследованных типов `X` + - сопутствующие объекты, связанные с любым аргументом типа в `X` + - если `X` - это внутренний класс, внешние объекты, в которые он встроен + +Например, рассмотрим неявное преобразование `fromStringToUser`, определенное в объекте `Conversions`: + +{% tabs implicit-conversions-4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.language.implicitConversions + +object Conversions { + implicit def fromStringToUser(name: String): User = (name: String) => User(name) +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object Conversions: + given fromStringToUser: Conversion[String, User] = (name: String) => User(name) +``` + +{% endtab %} +{% endtabs %} + +Следующие операции импорта эквивалентно передают преобразование в область действия: + +{% tabs implicit-conversions-5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import Conversions.fromStringToUser +// или +import Conversions._ +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import Conversions.fromStringToUser +// или +import Conversions.given +// или +import Conversions.{given Conversion[String, User]} +``` + +Обратите внимание, что в Scala 3 импорт с подстановочными знаками (т.е. `import Conversions.*`) +не импортирует given определения. + +{% endtab %} +{% endtabs %} + +Во вводном примере преобразование из `Int` в `Long` не требует импорта, поскольку оно определено в объекте `Int`, +который является сопутствующим объектом типа `Int`. + +Дополнительная литература: +[Где Scala ищет неявные значения? (в Stackoverflow)](https://stackoverflow.com/a/5598107). + +### Остерегайтесь силы неявных преобразований + +{% tabs implicit-conversions-6 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +Поскольку неявные преобразования могут иметь подводные камни, если используются без разбора, +компилятор предупреждает при компиляции определения неявного преобразования. + +Чтобы отключить предупреждения, выполните одно из следующих действий: + +- Импорт `scala.language.implicitConversions` в область определения неявного преобразования +- Вызвать компилятор с командой `-language:implicitConversions` + +Предупреждение не выдается, когда компилятор применяет преобразование. +{% endtab %} +{% tab 'Scala 3' %} +Поскольку неявные преобразования могут иметь подводные камни, если они используются без разбора, +компилятор выдает предупреждение в двух случаях: + +- при компиляции определения неявного преобразования в стиле Scala 2. +- на стороне вызова, где given экземпляр `scala.Conversion` вставляется как конверсия. + +Чтобы отключить предупреждения, выполните одно из следующих действий: + +- Импортировать `scala.language.implicitConversions` в область: + - определения неявного преобразования в стиле Scala 2 + - стороны вызова, где given экземпляр `scala.Conversion` вставляется как конверсия. +- Вызвать компилятор с командой `-language:implicitConversions` + {% endtab %} + {% endtabs %} + +[extension methods]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[companion objects]: {% link _overviews/scala3-book/domain-modeling-tools.md %}#companion-objects diff --git a/_ru/scala3/book/ca-multiversal-equality.md b/_ru/scala3/book/ca-multiversal-equality.md new file mode 100644 index 0000000000..19960bc97a --- /dev/null +++ b/_ru/scala3/book/ca-multiversal-equality.md @@ -0,0 +1,207 @@ +--- +layout: multipage-overview +title: Многостороннее равенство +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице демонстрируется, как реализовать многостороннее равенство в Scala 3. +language: ru +num: 65 +previous-page: ca-type-classes +next-page: ca-implicit-conversions +versionSpecific: true +--- + +Раньше в Scala было _универсальное равенство_ (_universal equality_): +два значения любых типов можно было сравнивать друг с другом с помощью `==` и `!=`. +Это произошло из-за того факта, что `==` и `!=` реализованы в терминах метода `equals` Java, +который также может сравнивать значения любых двух ссылочных типов. + +Универсальное равенство удобно, но оно также опасно, поскольку подрывает безопасность типов. +Например, предположим, что после некоторого рефакторинга осталась ошибочная программа, +в которой значение `y` имеет тип `S` вместо правильного типа `T`: + +```scala +val x = ... // типа T +val y = ... // типа S, но должно быть типа T +x == y // результат проверки типов всегда будет false +``` + +Если `y` сравнивается с другими значениями типа `T`, программа все равно будет проверять тип, +так как значения всех типов можно сравнивать друг с другом. +Но это, вероятно, даст неожиданные результаты и завершится ошибкой во время выполнения. + +Типобезопасный язык программирования может работать лучше, а многостороннее равенство — +это дополнительный способ сделать универсальное равенство более безопасным. +Он использует класс двоичного типа `CanEqual`, чтобы указать, что значения двух заданных типов можно сравнивать друг с другом. + +## Разрешение сравнения экземпляров класса + +По умолчанию в Scala 3 все ещё можно сравнивать на равенство следующим образом: + +```scala +case class Cat(name: String) +case class Dog(name: String) +val d = Dog("Fido") +val c = Cat("Morris") + +d == c // false, но он компилируется +``` + +Но в Scala 3 такие сравнения можно отключить. +При (а) импорте `scala.language.strictEquality` или (б) использовании флага компилятора `-language:strictEquality` +это сравнение больше не компилируется: + +```scala +import scala.language.strictEquality + +val rover = Dog("Rover") +val fido = Dog("Fido") +println(rover == fido) // ошибка компиляции + +// сообщение об ошибке компиляции: +// Values of types Dog and Dog cannot be compared with == or != +``` + +## Включение сравнений + +Есть два способа включить сравнение с помощью класса типов `CanEqual`. +Для простых случаев класс может _выводиться_ (_derive_) от класса `CanEqual`: + +```scala +// Способ 1 +case class Dog(name: String) derives CanEqual +``` + +Как вы вскоре увидите, когда нужна большая гибкость, вы также можете использовать следующий синтаксис: + +```scala +// Способ 2 +case class Dog(name: String) +given CanEqual[Dog, Dog] = CanEqual.derived +``` + +Любой из этих двух подходов позволяет сравнивать экземпляры `Dog` друг с другом. + +## Более реалистичный пример + +В более реалистичном примере представим, что есть книжный интернет-магазин +и мы хотим разрешить или запретить сравнение бумажных, печатных и аудиокниг. +В Scala 3 для начала необходимо включить многостороннее равенство: + +```scala +// [1] добавить этот импорт или command line flag: -language:strictEquality +import scala.language.strictEquality +``` + +Затем создать объекты домена: + +```scala +// [2] создание иерархии классов +trait Book: + def author: String + def title: String + def year: Int + +case class PrintedBook( + author: String, + title: String, + year: Int, + pages: Int +) extends Book + +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book +``` + +Наконец, используем `CanEqual`, чтобы определить, какие сравнения необходимо разрешить: + +```scala +// [3] создайте экземпляры класса типов, чтобы определить разрешенные сравнения. +// разрешено `PrintedBook == PrintedBook` +// разрешено `AudioBook == AudioBook` +given CanEqual[PrintedBook, PrintedBook] = CanEqual.derived +given CanEqual[AudioBook, AudioBook] = CanEqual.derived + +// [4a] сравнение двух печатных книг разрешено +val p1 = PrintedBook("1984", "George Orwell", 1961, 328) +val p2 = PrintedBook("1984", "George Orwell", 1961, 328) +println(p1 == p2) // true + +// [4b] нельзя сравнивать печатную книгу и аудиокнигу +val pBook = PrintedBook("1984", "George Orwell", 1961, 328) +val aBook = AudioBook("1984", "George Orwell", 2006, 682) +println(pBook == aBook) // ошибка компиляции +``` + +Последняя строка кода приводит к следующему сообщению компилятора об ошибке: + +``` +Values of types PrintedBook and AudioBook cannot be compared with == or != +``` + +Вот как многостороннее равенство отлавливает недопустимые сравнения типов во время компиляции. + +### Включение “PrintedBook == AudioBook” + +Если есть необходимость разрешить сравнение "печатной книги" (`PrintedBook`) с аудио-книгой (`AudioBook`), +то достаточно создать следующие два дополнительных сравнения равенства: + +```scala +// разрешить `PrintedBook == AudioBook` и `AudioBook == PrintedBook` +given CanEqual[PrintedBook, AudioBook] = CanEqual.derived +given CanEqual[AudioBook, PrintedBook] = CanEqual.derived +``` + +Теперь можно сравнивать печатную книгу с аудио-книгой без ошибки компилятора: + +```scala +println(pBook == aBook) // false +println(aBook == pBook) // false +``` + +#### Внедрите "equals", чтобы они действительно работали + +Хотя эти сравнения теперь разрешены, они всегда будут ложными, +потому что их методы `equals` не знают, как проводить подобные сравнения. +Чтобы доработать сравнение, можно переопределить методы `equals` для каждого класса. +Например, если переопределить метод `equals` для `AudioBook`: + +```scala +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book: + // переопределить, чтобы разрешить сравнение AudioBook с PrintedBook + override def equals(that: Any): Boolean = that match + case a: AudioBook => + this.author == a.author + && this.title == a.title + && this.year == a.year + && this.lengthInMinutes == a.lengthInMinutes + case p: PrintedBook => + this.author == p.author && this.title == p.title + case _ => + false +``` + +Теперь можно сравнить `AudioBook` с `PrintedBook`: + +```scala +println(aBook == pBook) // true (работает из-за переопределенного `equals` в `AudioBook`) +println(pBook == aBook) // false +``` + +Книга `PrintedBook` не имеет метода `equals`, поэтому второе сравнение возвращает `false`. +Чтобы включить это сравнение, достаточно переопределить метод `equals` в `PrintedBook`. + +Вы можете найти дополнительную информацию о [многостороннем равенстве][ref-equal] в справочной документации. + +[ref-equal]: {{ site.scala3ref }}/contextual/multiversal-equality.html diff --git a/_ru/scala3/book/ca-summary.md b/_ru/scala3/book/ca-summary.md new file mode 100644 index 0000000000..f3b68b7211 --- /dev/null +++ b/_ru/scala3/book/ca-summary.md @@ -0,0 +1,38 @@ +--- +layout: multipage-overview +title: Обзор +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлен краткий обзор уроков по контекстуальным абстракциям. +language: ru +num: 67 +previous-page: ca-implicit-conversions +next-page: concurrency +--- + +В этой главе представлено введение в большинство тем контекстных абстракций, в том числе: + +- [Методы расширения](ca-extension-methods.html) +- [Экземпляры given и параметры контекста](ca-context-parameters.html) +- [Контекстные границы](ca-context-bounds.html) +- [Импорт given](ca-given-imports.html) +- [Классы типов](ca-type-classes.html) +- [Многостороннее равенство](ca-multiversal-equality.html) +- [Неявные преобразования](ca-implicit-conversions.html) + +Все эти функции являются вариантами основной идеи **вывода термов**: +учитывая тип, компилятор синтезирует “канонический” терм, который имеет этот тип. + +Несколько более сложных тем здесь не рассматриваются, в том числе: + +- Условные given экземпляры +- Вывод класса типов +- Контекстные функции +- Контекстные параметры по имени +- Связь с имплицитами Scala 2 + +Эти темы подробно обсуждаются в [справочной документации][ref]. + +[ref]: {{ site.scala3ref }}/contextual diff --git a/_ru/scala3/book/ca-type-classes.md b/_ru/scala3/book/ca-type-classes.md new file mode 100644 index 0000000000..5da4f9468f --- /dev/null +++ b/_ru/scala3/book/ca-type-classes.md @@ -0,0 +1,230 @@ +--- +layout: multipage-overview +title: Классы типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе демонстрируется создание и использование классов типов. +language: ru +num: 64 +previous-page: ca-given-imports +next-page: ca-multiversal-equality +--- + +Класс типов (_type class_) — это абстрактный параметризованный тип, +который позволяет добавлять новое поведение к любому закрытому типу данных без использования подтипов. +Если вы пришли с Java, то можно думать о классах типов как о чем-то вроде [`java.util.Comparator[T]`][comparator]. + +> В статье ["Type Classes as Objects and Implicits"][typeclasses-paper] (2010 г.) обсуждаются основные идеи, +> лежащие в основе классов типов в Scala. +> Несмотря на то, что в статье используется более старая версия Scala, идеи актуальны и по сей день. + +Этот стиль программирования полезен во многих случаях, например: + +- выражение того, как тип, которым вы не владеете, например, из стандартной или сторонней библиотеки, соответствует такому поведению +- добавление поведения к нескольким типам без введения отношений подтипов между этими типами (например, когда один расширяет другой) + +Классы типов — это трейты с одним или несколькими параметрами, +реализации которых предоставляются в виде экземпляров `given` в Scala 3 или `implicit` значений в Scala 2. + +## Пример + +Например, `Show` - хорошо известный класс типов в Haskell, и в следующем коде показан один из способов его реализации в Scala. +Если предположить, что классы Scala не содержат метода `toString`, то можно определить класс типов `Show`, +чтобы добавить это поведение к любому типу, который вы хотите преобразовать в пользовательскую строку. + +### Класс типов + +Первым шагом в создании класса типов является объявление параметризованного trait, содержащего один или несколько абстрактных методов. +Поскольку `Showable` содержит только один метод с именем `show`, он записывается так: + +{% tabs 'definition' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// класс типов +trait Showable[A] { + def show(a: A): String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// класс типов +trait Showable[A]: + extension (a: A) def show: String +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что этот подход близок к обычному объектно-ориентированному подходу, +когда обычно trait `Show` определяется следующим образом: + +{% tabs 'trait' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// a trait +trait Show { + def show: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// a trait +trait Show: + def show: String +``` + +{% endtab %} +{% endtabs %} + +Следует отметить несколько важных моментов: + +1. Классы типов, например, `Showable` принимают параметр типа `A`, чтобы указать, для какого типа мы предоставляем реализацию `show`; + в отличие от классических трейтов, наподобие `Show`. +2. Чтобы добавить функциональность `show` к определенному типу `A`, классический трейт требует наследования `A extends Show`, + в то время как для классов типов нам требуется реализация `Showable[A]`. +3. В Scala 3, чтобы разрешить один и тот же синтаксис вызова метода в обоих случаях `Showable`, + который имитирует синтаксис `Show`, мы определяем `Showable.show` как метод расширения. + +### Реализация конкретных экземпляров + +Следующий шаг — определить, какие классы `Showable` должны работать в вашем приложении, а затем реализовать для них это поведение. +Например, для реализации `Showable` следующего класса `Person`: + +{% tabs 'person' %} +{% tab 'Scala 2 и 3' %} + +```scala +case class Person(firstName: String, lastName: String) +``` + +{% endtab %} +{% endtabs %} + +необходимо определить одно _каноническое значение_ типа `Showable[Person]`, т.е. экземпляр `Showable` для типа `Person`, +как показано в следующем примере кода: + +{% tabs 'instance' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +implicit val showablePerson: Showable[Person] = new Showable[Person] { + def show(p: Person): String = + s"${p.firstName} ${p.lastName}" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +given Showable[Person] with + extension (p: Person) def show: String = + s"${p.firstName} ${p.lastName}" +``` + +{% endtab %} +{% endtabs %} + +### Использование класса типов + +Теперь вы можете использовать этот класс типов следующим образом: + +{% tabs 'usage' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val person = Person("John", "Doe") +println(showablePerson.show(person)) +``` + +Обратите внимание, что на практике классы типов обычно используются со значениями, тип которых неизвестен, +в отличие от type `Person`, как показано в следующем разделе. + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val person = Person("John", "Doe") +println(person.show) +``` + +{% endtab %} +{% endtabs %} + +Опять же, если бы в Scala не было метода `toString`, доступного для каждого класса, вы могли бы использовать эту технику, +чтобы добавить поведение `Showable` к любому классу, который вы хотите преобразовать в `String`. + +### Написание методов, использующих класс типов + +Как и в случае с наследованием, вы можете определить методы, которые используют `Showable` в качестве параметра типа: + +{% tabs 'method' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def showAll[A](as: List[A])(implicit showable: Showable[A]): Unit = + as.foreach(a => println(showable.show(a))) + +showAll(List(Person("Jane"), Person("Mary"))) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def showAll[A: Showable](as: List[A]): Unit = + as.foreach(a => println(a.show)) + +showAll(List(Person("Jane"), Person("Mary"))) +``` + +{% endtab %} +{% endtabs %} + +### Класс типов с несколькими методами + +Обратите внимание: если вы хотите создать класс типов с несколькими методами, исходный синтаксис выглядит следующим образом: + +{% tabs 'multiple-methods' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasLegs[A] { + def walk(a: A): Unit + def run(a: A): Unit +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait HasLegs[A]: + extension (a: A) + def walk(): Unit + def run(): Unit +``` + +{% endtab %} +{% endtabs %} + +### Пример из реального мира + +В качестве примера из реального мира, как классы типов используются в Scala 3, +см. обсуждение `CanEqual` в [разделе Multiversal Equality][multiversal]. + +[typeclasses-paper]: https://infoscience.epfl.ch/record/150280/files/TypeClasses.pdf + +[typeclasses-chapter]: {% link _overviews/scala3-book/ca-type-classes.md %} +[comparator]: https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html +[multiversal]: {% link _overviews/scala3-book/ca-multiversal-equality.md %} diff --git a/_ru/scala3/book/collections-classes.md b/_ru/scala3/book/collections-classes.md new file mode 100644 index 0000000000..80fcf30248 --- /dev/null +++ b/_ru/scala3/book/collections-classes.md @@ -0,0 +1,971 @@ +--- +layout: multipage-overview +title: Типы коллекций +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлены общие типы коллекций Scala 3 и некоторые из их методов. +language: ru +num: 38 +previous-page: collections-intro +next-page: collections-methods +--- + + +На этой странице показаны общие коллекции Scala 3 и сопутствующие им методы. +Scala поставляется с большим количеством типов коллекций, на изучение которых может уйти время, +поэтому желательно начать с нескольких из них, а затем использовать остальные по мере необходимости. +Точно так же у каждого типа коллекции есть десятки методов, облегчающих разработку, +поэтому лучше начать изучение лишь с небольшого количества. + +В этом разделе представлены наиболее распространенные типы и методы коллекций, +которые вам понадобятся для начала работы. + +В конце этого раздела представлены дополнительные ссылки, для более глубокого изучения коллекций. + +## Три основные категории коллекций + +Для коллекций Scala можно выделить три основные категории: + +- **Последовательности** (**Sequences**/**Seq**) представляют собой последовательный набор элементов + и могут быть _индексированными_ (как массив) или _линейными_ (как связанный список) +- **Мапы** (**Maps**) содержат набор пар ключ/значение, например Java `Map`, Python dictionary или Ruby `Hash` +- **Множества** (**Sets**) — это неупорядоченный набор уникальных элементов + +Все они являются базовыми типами и имеют подтипы подходящие под конкретные задачи, +таких как параллелизм (concurrency), кэширование (caching) и потоковая передача (streaming). +В дополнение к этим трем основным категориям существуют и другие полезные типы коллекций, +включая диапазоны (ranges), стеки (stacks) и очереди (queues). + + +### Иерархия коллекций + +В качестве краткого обзора следующие три рисунка показывают иерархию классов и трейтов в коллекциях Scala. + +На первом рисунке показаны типы коллекций в пакете _scala.collection_. +Все это высокоуровневые абстрактные классы или трейты, которые обычно имеют _неизменяемые_ и _изменяемые_ реализации. + +![General collection hierarchy][collections1] + +На этом рисунке показаны все коллекции в пакете _scala.collection.immutable_: + +![Immutable collection hierarchy][collections2] + +А на этом рисунке показаны все коллекции в пакете _scala.collection.mutable_: + +![Mutable collection hierarchy][collections3] + +В следующих разделах представлены некоторые из распространенных типов. + +## Общие коллекции + +Основные коллекции, используемые чаще всего: + +| Тип коллекции | Неизменяемая | Изменяемая | Описание | +|----------------|--------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `List` | ✓ | | Линейная неизменяемая последовательность (связный список) | +| `Vector` | ✓ | | Индексированная неизменяемая последовательность | +| `LazyList` | ✓ | | Ленивый неизменяемый связанный список, элементы которого вычисляются только тогда, когда они необходимы; подходит для больших или бесконечных последовательностей. | +| `ArrayBuffer` | | ✓ | Подходящий тип для изменяемой индексированной последовательности | +| `ListBuffer` | | ✓ | Используется, когда вам нужен изменяемый список; обычно преобразуется в `List` | +| `Map` | ✓ | ✓ | Итерируемая коллекция, состоящая из пар ключей и значений | +| `Set` | ✓ | ✓ | Итерируемая коллекция без повторяющихся элементов | + +Как показано, `Map` и `Set` бывают как изменяемыми, так и неизменяемыми. + +Основы каждого типа демонстрируются в следующих разделах. + +> В Scala _буфер_ (_buffer_), такой как `ArrayBuffer` или `ListBuffer`, представляет собой последовательность, +> которая может увеличиваться и уменьшаться. + +### Примечание о неизменяемых коллекциях + +В последующих разделах всякий раз, когда используется слово _immutable_, можно с уверенностью сказать, +что тип предназначен для использования в стиле _функционального программирования_ (ФП). +С помощью таких типов коллекция не меняется, +а при вызове функциональных методов возвращается новый результат - новая коллекция. + +## Выбор последовательности + +При выборе _последовательности_ (последовательной коллекции элементов) нужно руководствоваться двумя основными вопросами: + +- должна ли последовательность индексироваться (как массив), обеспечивая быстрый доступ к любому элементу, + или она должна быть реализована как линейный связанный список? +- необходима изменяемая или неизменяемая коллекция? + +Рекомендуемые универсальные последовательности: + +| Тип\Категория | Неизменяемая | Изменяемая | +|-----------------------------|--------------|---------------| +| индексируемая | `Vector` | `ArrayBuffer` | +| линейная (связанный список) | `List` | `ListBuffer` | + +Например, если нужна неизменяемая индексированная коллекция, в общем случае следует использовать `Vector`. +И наоборот, если нужна изменяемая индексированная коллекция, используйте `ArrayBuffer`. + +> `List` и `Vector` часто используются при написании кода в функциональном стиле. +> `ArrayBuffer` обычно используется при написании кода в императивном стиле. +> `ListBuffer` используется тогда, когда стили смешиваются, например, при создании списка. + +Следующие несколько разделов кратко демонстрируют типы `List`, `Vector` и `ArrayBuffer`. + + +## `List` + +[List](https://www.scala-lang.org/api/current/scala/collection/immutable/List.html) +представляет собой линейную неизменяемую последовательность. +Каждый раз, когда в список добавляются или удаляются элементы, по сути создается новый список из существующего. + +### Создание списка + +`List` можно создать различными способами: + +{% tabs list-creation %} + +{% tab 'Scala 2 и 3' %} +```scala +val ints = List(1, 2, 3) +val names = List("Joel", "Chris", "Ed") + +// другой путь создания списка List +val namesAgain = "Joel" :: "Chris" :: "Ed" :: Nil +``` +{% endtab %} + +{% endtabs %} + +При желании тип списка можно объявить, хотя обычно в этом нет необходимости: + +{% tabs list-type %} + +{% tab 'Scala 2 и 3' %} +```scala +val ints: List[Int] = List(1, 2, 3) +val names: List[String] = List("Joel", "Chris", "Ed") +``` +{% endtab %} + +{% endtabs %} + +Одно исключение — когда в коллекции смешанные типы; в этом случае тип желательно указывать явно: + +{% tabs list-mixed-types class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val things: List[Any] = List(1, "two", 3.0) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val things: List[String | Int | Double] = List(1, "two", 3.0) // с типами объединения +val thingsAny: List[Any] = List(1, "two", 3.0) // с Any +``` +{% endtab %} + +{% endtabs %} + +### Добавление элементов в список + +Поскольку `List` неизменяем, в него нельзя добавлять новые элементы. +Вместо этого создается новый список с добавленными к существующему списку элементами. +Например, учитывая этот `List`: + +{% tabs adding-elements-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = List(1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +Для _добавления_ (_prepend_) к началу списка одного элемента используется метод `::`, для добавления нескольких — `:::`, как показано здесь: + +{% tabs adding-elements-example %} + +{% tab 'Scala 2 и 3' %} +```scala +val b = 0 :: a // List(0, 1, 2, 3) +val c = List(-1, 0) ::: a // List(-1, 0, 1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +Также можно _добавить_ (_append_) элементы в конец `List`, но, поскольку `List` является односвязным, +следует добавлять к нему элементы только в начало; +добавление элементов в конец списка — относительно медленная операция, +особенно при работе с большими последовательностями. + +> Совет: если необходимо добавлять к неизменяемой последовательности элементы в начало и конец, используйте `Vector`. + +Поскольку `List` является связанным списком, +крайне нежелательно пытаться получить доступ к элементам больших списков по значению их индекса. +Например, если есть `List` с миллионом элементов, доступ к такому элементу, как `myList(999_999)`, +займет относительно много времени, потому что этот запрос должен пройти почти через все элементы. +Если есть большая коллекция и необходимо получать доступ к элементам по их индексу, то +вместо `List` используйте `Vector` или `ArrayBuffer`. + +### Как запомнить названия методов + +В методах Scala символ `:` представляет сторону, на которой находится последовательность, +поэтому, когда используется метод `+:`, список нужно указывать справа: + +{% tabs list-prepending %} + +{% tab 'Scala 2 и 3' %} +```scala +0 +: a +``` +{% endtab %} + +{% endtabs %} + +Аналогично, если используется `:+`, список должен быть слева: + +{% tabs list-appending %} + +{% tab 'Scala 2 и 3' %} +```scala +a :+ 4 +``` +{% endtab %} + +{% endtabs %} + +Хорошей особенностью таких символических имен у методов является то, что они стандартизированы. + +Те же имена методов используются с другими неизменяемыми последовательностями, такими как `Seq` и `Vector`. +Также можно использовать несимволические имена методов для добавления элементов в начало (`a.prepended(4)`) +или конец (`a.appended(4)`). + +### Как пройтись по списку + +Представим, что есть `List` имён: + +{% tabs list-loop-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val names = List("Joel", "Chris", "Ed") +``` +{% endtab %} + +{% endtabs %} + +Напечатать каждое имя можно следующим способом: + +{% tabs list-loop-example class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +for (name <- names) println(name) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +for name <- names do println(name) +``` +{% endtab %} + +{% endtabs %} + +Вот как это выглядит в REPL: + +{% tabs list-loop-repl class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +scala> for (name <- names) println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for name <- names do println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% endtabs %} + + +Преимуществом использования выражений вида `for` с коллекциями в том, что Scala стандартизирован, +и один и тот же подход работает со всеми последовательностями, +включая `Array`, `ArrayBuffer`, `List`, `Seq`, `Vector`, `Map`, `Set` и т.д. + +### Немного истории + +Список Scala подобен списку из языка программирования [Lisp](https://en.wikipedia.org/wiki/Lisp_(programming_language)), +который был впервые представлен в 1958 году. +Действительно, в дополнение к привычному способу создания списка: + +{% tabs list-history-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +точно такой же список можно создать следующим образом: + +{% tabs list-history-init2 %} + +{% tab 'Scala 2 и 3' %} +```scala +val list = 1 :: 2 :: 3 :: Nil +``` +{% endtab %} + +{% endtabs %} + +REPL показывает, как это работает: + +{% tabs list-history-repl %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> val list = 1 :: 2 :: 3 :: Nil +list: List[Int] = List(1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +Это работает, потому что `List` — односвязный список, оканчивающийся элементом `Nil`, +а `::` — это метод `List`, работающий как оператор “cons” в Lisp. + + +### Отступление: LazyList + +Коллекции Scala также включают [LazyList](https://www.scala-lang.org/api/current/scala/collection/immutable/LazyList.html), +который представляет собой _ленивый_ неизменяемый связанный список. +Он называется «ленивым» — или нестрогим — потому что вычисляет свои элементы только тогда, когда они необходимы. + +Вы можете увидеть отложенное вычисление `LazyList` в REPL: + +{% tabs lazylist-example %} + +{% tab 'Scala 2 и 3' %} +```scala +val x = LazyList.range(1, Int.MaxValue) +x.take(1) // LazyList() +x.take(5) // LazyList() +x.map(_ + 1) // LazyList() +``` +{% endtab %} + +{% endtabs %} + +Во всех этих примерах ничего не происходит. +Действительно, ничего не произойдет, пока вы не заставите это произойти, например, вызвав метод `foreach`: + +{% tabs lazylist-evaluation-example %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> x.take(1).foreach(println) +1 +``` +{% endtab %} + +{% endtabs %} + +Дополнительные сведения об использовании, преимуществах и недостатках строгих и нестрогих (ленивых) коллекций +см. в обсуждениях “строгих” и “нестрогих” на странице [Архитектура коллекции в Scala 2.13][strict]. + +## Vector + +[Vector](https://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html) - это индексируемая неизменяемая последовательность. +“Индексируемая” часть описания означает, что она обеспечивает произвольный доступ +и обновление за практически постоянное время, +поэтому можно быстро получить доступ к элементам `Vector` по значению их индекса, +например, получить доступ к `listOfPeople(123_456_789)`. + +В общем, за исключением той разницы, что (а) `Vector` индексируется, а `List` - нет, +и (б) `List` имеет метод `::`, эти два типа работают одинаково, +поэтому мы быстро пробежимся по следующим примерам. + +Вот несколько способов создания `Vector`: + +{% tabs vector-creation %} + +{% tab 'Scala 2 и 3' %} +```scala +val nums = Vector(1, 2, 3, 4, 5) + +val strings = Vector("one", "two") + +case class Person(name: String) +val people = Vector( + Person("Bert"), + Person("Ernie"), + Person("Grover") +) +``` +{% endtab %} + +{% endtabs %} + +Поскольку `Vector` неизменяем, в него нельзя добавить новые элементы. +Вместо этого создается новая последовательность, с добавленными к существующему `Vector` в начало или в конец элементами. + +Например, так элементы добавляются в конец: + +{% tabs vector-appending %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = Vector(1,2,3) // Vector(1, 2, 3) +val b = a :+ 4 // Vector(1, 2, 3, 4) +val c = a ++ Vector(4, 5) // Vector(1, 2, 3, 4, 5) +``` +{% endtab %} + +{% endtabs %} + +А так - в начало Vector-а: + +{% tabs vector-prepending %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = Vector(1,2,3) // Vector(1, 2, 3) +val b = 0 +: a // Vector(0, 1, 2, 3) +val c = Vector(-1, 0) ++: a // Vector(-1, 0, 1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +В дополнение к быстрому произвольному доступу и обновлениям, `Vector` обеспечивает быстрое добавление в начало и конец. + +> Подробную информацию о производительности `Vector` и других коллекций +> см. [в характеристиках производительности коллекций](https://docs.scala-lang.org/overviews/collections-2.13/performance-characteristics.html). + +Наконец, `Vector` в выражениях вида `for` используется точно так же, как `List`, `ArrayBuffer` или любая другая последовательность: + +{% tabs vector-loop class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +scala> val names = Vector("Joel", "Chris", "Ed") +val names: Vector[String] = Vector(Joel, Chris, Ed) + +scala> for (name <- names) println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> val names = Vector("Joel", "Chris", "Ed") +val names: Vector[String] = Vector(Joel, Chris, Ed) + +scala> for name <- names do println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% endtabs %} + + +## ArrayBuffer + +`ArrayBuffer` используется тогда, когда нужна изменяемая индексированная последовательность общего назначения. +Поскольку `ArrayBuffer` индексирован, произвольный доступ к элементам выполняется быстро. + +### Создание ArrayBuffer + +Чтобы использовать `ArrayBuffer`, его нужно вначале импортировать: + +{% tabs arraybuffer-import %} + +{% tab 'Scala 2 и 3' %} +```scala +import scala.collection.mutable.ArrayBuffer +``` +{% endtab %} + +{% endtabs %} + +Если необходимо начать с пустого `ArrayBuffer`, просто укажите его тип: + +{% tabs arraybuffer-creation %} + +{% tab 'Scala 2 и 3' %} +```scala +var strings = ArrayBuffer[String]() +var ints = ArrayBuffer[Int]() +var people = ArrayBuffer[Person]() +``` +{% endtab %} + +{% endtabs %} + +Если известен примерный размер `ArrayBuffer`, его можно задать: + +{% tabs list-creation-with-size %} + +{% tab 'Scala 2 и 3' %} +```scala +// готов вместить 100 000 чисел +val buf = new ArrayBuffer[Int](100_000) +``` +{% endtab %} + +{% endtabs %} + +Чтобы создать новый `ArrayBuffer` с начальными элементами, +достаточно просто указать начальные элементы, как для `List` или `Vector`: + +{% tabs arraybuffer-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val nums = ArrayBuffer(1, 2, 3) +val people = ArrayBuffer( + Person("Bert"), + Person("Ernie"), + Person("Grover") +) +``` +{% endtab %} + +{% endtabs %} + +### Добавление элементов в ArrayBuffer + +Новые элементы добавляются в `ArrayBuffer` с помощью методов `+=` и `++=`. +Также можно использовать текстовый аналог: `append`, `appendAll`, `insert`, `insertAll`, `prepend` и `prependAll`. +Вот несколько примеров с `+=` и `++=`: + +{% tabs arraybuffer-add %} + +{% tab 'Scala 2 и 3' %} +```scala +val nums = ArrayBuffer(1, 2, 3) // ArrayBuffer(1, 2, 3) +nums += 4 // ArrayBuffer(1, 2, 3, 4) +nums ++= List(5, 6) // ArrayBuffer(1, 2, 3, 4, 5, 6) +``` +{% endtab %} + +{% endtabs %} + +### Удаление элементов из ArrayBuffer + +`ArrayBuffer` является изменяемым, +поэтому у него есть такие методы, как `-=`, `--=`, `clear`, `remove` и другие. +Примеры с `-=` и `--=`: + +{% tabs arraybuffer-remove %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = ArrayBuffer.range('a', 'h') // ArrayBuffer(a, b, c, d, e, f, g) +a -= 'a' // ArrayBuffer(b, c, d, e, f, g) +a --= Seq('b', 'c') // ArrayBuffer(d, e, f, g) +a --= Set('d', 'e') // ArrayBuffer(f, g) +``` +{% endtab %} + +{% endtabs %} + +### Обновление элементов в ArrayBuffer + +Элементы в `ArrayBuffer` можно обновлять, либо переназначать: + +{% tabs arraybuffer-update %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = ArrayBuffer.range(1,5) // ArrayBuffer(1, 2, 3, 4) +a(2) = 50 // ArrayBuffer(1, 2, 50, 4) +a.update(0, 10) // ArrayBuffer(10, 2, 50, 4) +``` +{% endtab %} + +{% endtabs %} + + + +## Maps + +`Map` — это итерируемая коллекция, состоящая из пар ключей и значений. +В Scala есть как изменяемые, так и неизменяемые типы `Map`. +В этом разделе показано, как использовать _неизменяемый_ `Map`. + +### Создание неизменяемой Map + +Неизменяемая `Map` создается следующим образом: + +{% tabs map-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AZ" -> "Arizona" +) +``` +{% endtab %} + +{% endtabs %} + +Перемещаться по элементам `Map` используя выражение `for` можно следующим образом: + +{% tabs map-loop class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +for ((k, v) <- states) println(s"key: $k, value: $v") +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +for (k, v) <- states do println(s"key: $k, value: $v") +``` +{% endtab %} + +{% endtabs %} + +REPL показывает, как это работает: + +{% tabs map-repl class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +scala> for ((k, v) <- states) println(s"key: $k, value: $v") +key: AK, value: Alaska +key: AL, value: Alabama +key: AZ, value: Arizona +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for (k, v) <- states do println(s"key: $k, value: $v") +key: AK, value: Alaska +key: AL, value: Alabama +key: AZ, value: Arizona +``` +{% endtab %} + +{% endtabs %} + +### Доступ к элементам Map + +Доступ к элементам `Map` осуществляется через указание в скобках значения ключа: + +{% tabs map-access-element %} + +{% tab 'Scala 2 и 3' %} +```scala +val ak = states("AK") // ak: String = Alaska +val al = states("AL") // al: String = Alabama +``` +{% endtab %} + +{% endtabs %} + +На практике также используются такие методы, как `keys`, `keySet`, `keysIterator`, `for` выражения +и функции высшего порядка, такие как `map`, для работы с ключами и значениями `Map`. + +### Добавление элемента в Map + +При добавлении элементов в неизменяемую мапу с помощью `+` и `++`, создается новая мапа: + +{% tabs map-add-element %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = Map(1 -> "one") // a: Map(1 -> one) +val b = a + (2 -> "two") // b: Map(1 -> one, 2 -> two) +val c = b ++ Seq( + 3 -> "three", + 4 -> "four" +) +// c: Map(1 -> one, 2 -> two, 3 -> three, 4 -> four) +``` +{% endtab %} + +{% endtabs %} + +### Удаление элементов из Map + +Элементы удаляются с помощью методов `-` или `--`. +В случае неизменяемой `Map` создается новый экземпляр, который нужно присвоить новой переменной: + +{% tabs map-remove-element %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = Map( + 1 -> "one", + 2 -> "two", + 3 -> "three", + 4 -> "four" +) + +val b = a - 4 // b: Map(1 -> one, 2 -> two, 3 -> three) +val c = a - 4 - 3 // c: Map(1 -> one, 2 -> two) +``` +{% endtab %} + +{% endtabs %} + +### Обновление элементов в Map + +Чтобы обновить элементы на неизменяемой `Map`, используется метод `update` (или оператор `+`): + +{% tabs map-update-element %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = Map( + 1 -> "one", + 2 -> "two", + 3 -> "three" +) + +val b = a.updated(3, "THREE!") // b: Map(1 -> one, 2 -> two, 3 -> THREE!) +val c = a + (2 -> "TWO...") // c: Map(1 -> one, 2 -> TWO..., 3 -> three) +``` +{% endtab %} + +{% endtabs %} + +### Перебор элементов в Map + +Элементы в `Map` можно перебрать с помощью выражения `for`, как и для остальных коллекций: + +{% tabs map-traverse class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AZ" -> "Arizona" +) + +for ((k, v) <- states) println(s"key: $k, value: $v") +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AZ" -> "Arizona" +) + +for (k, v) <- states do println(s"key: $k, value: $v") +``` +{% endtab %} + +{% endtabs %} + +Существует _много_ способов работы с ключами и значениями на `Map`. +Общие методы `Map` включают `foreach`, `map`, `keys` и `values`. + +В Scala есть много других специализированных типов `Map`, +включая `CollisionProofHashMap`, `HashMap`, `LinkedHashMap`, `ListMap`, `SortedMap`, `TreeMap`, `WeakHashMap` и другие. + + +## Работа с множествами + +Множество ([Set]({{site.baseurl}}/overviews/collections-2.13/sets.html)) - итерируемая коллекция без повторяющихся элементов. + +В Scala есть как изменяемые, так и неизменяемые типы `Set`. +В этом разделе демонстрируется _неизменяемое_ множество. + +### Создание множества + +Создание нового пустого множества: + +{% tabs set-creation %} + +{% tab 'Scala 2 и 3' %} +```scala +val nums = Set[Int]() +val letters = Set[Char]() +``` +{% endtab %} + +{% endtabs %} + +Создание множества с исходными данными: + +{% tabs set-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val nums = Set(1, 2, 3, 3, 3) // Set(1, 2, 3) +val letters = Set('a', 'b', 'c', 'c') // Set('a', 'b', 'c') +``` +{% endtab %} + +{% endtabs %} + + +### Добавление элементов в множество + +В неизменяемое множество новые элементы добавляются с помощью `+` и `++`, результат присваивается новой переменной: + +{% tabs set-add-element %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = Set(1, 2) // Set(1, 2) +val b = a + 3 // Set(1, 2, 3) +val c = b ++ Seq(4, 1, 5, 5) // HashSet(5, 1, 2, 3, 4) +``` +{% endtab %} + +{% endtabs %} + +Стоит отметить, что повторяющиеся элементы не добавляются в множество, +а также, что порядок элементов произвольный. + + +### Удаление элементов из множества + +Элементы из множества удаляются с помощью методов `-` и `--`, результат также должен присваиваться новой переменной: + +{% tabs set-remove-element %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = Set(1, 2, 3, 4, 5) // HashSet(5, 1, 2, 3, 4) +val b = a - 5 // HashSet(1, 2, 3, 4) +val c = b -- Seq(3, 4) // HashSet(1, 2) +``` +{% endtab %} + +{% endtabs %} + + + +## Диапазон (Range) + +`Range` часто используется для заполнения структур данных и для `for` выражений. +Эти REPL примеры демонстрируют, как создавать диапазоны: + +{% tabs range-init %} + +{% tab 'Scala 2 и 3' %} +```scala +1 to 5 // Range(1, 2, 3, 4, 5) +1 until 5 // Range(1, 2, 3, 4) +1 to 10 by 2 // Range(1, 3, 5, 7, 9) +'a' to 'c' // NumericRange(a, b, c) +``` +{% endtab %} + +{% endtabs %} + +Range можно использовать для заполнения коллекций: + +{% tabs range-conversion %} + +{% tab 'Scala 2 и 3' %} +```scala +val x = (1 to 5).toList // List(1, 2, 3, 4, 5) +val x = (1 to 5).toBuffer // ArrayBuffer(1, 2, 3, 4, 5) +``` +{% endtab %} + +{% endtabs %} + +Они также используются в `for` выражениях: + +{% tabs range-iteration class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +scala> for (i <- 1 to 3) println(i) +1 +2 +3 +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for i <- 1 to 3 do println(i) +1 +2 +3 +``` +{% endtab %} + +{% endtabs %} + +Во многих коллекциях есть метод `range`: + +{% tabs range-methods %} + +{% tab 'Scala 2 и 3' %} +```scala +Vector.range(1, 5) // Vector(1, 2, 3, 4) +List.range(1, 10, 2) // List(1, 3, 5, 7, 9) +Set.range(1, 10) // HashSet(5, 1, 6, 9, 2, 7, 3, 8, 4) +``` +{% endtab %} + +{% endtabs %} + +Диапазоны также полезны для создания тестовых коллекций: + +{% tabs range-tests %} + +{% tab 'Scala 2 и 3' %} +```scala +val evens = (0 to 10 by 2).toList // List(0, 2, 4, 6, 8, 10) +val odds = (1 to 10 by 2).toList // List(1, 3, 5, 7, 9) +val doubles = (1 to 5).map(_ * 2.0) // Vector(2.0, 4.0, 6.0, 8.0, 10.0) + +// Создание Map +val map = (1 to 3).map(e => (e,s"$e")).toMap +// map: Map[Int, String] = Map(1 -> "1", 2 -> "2", 3 -> "3") +``` +{% endtab %} + +{% endtabs %} + + +## Больше деталей + +Если вам нужна дополнительная информация о специализированных коллекциях, см. следующие ресурсы: + +- [Конкретные неизменяемые классы коллекций](https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html) +- [Конкретные изменяемые классы коллекций](https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html) +- [Как устроены коллекции? Какую из них следует выбрать?](https://docs.scala-lang.org/tutorials/FAQ/collections.html) + + + +[strict]: {% link _overviews/core/architecture-of-scala-213-collections.md %} +[collections1]: /resources/images/tour/collections-diagram-213.svg +[collections2]: /resources/images/tour/collections-immutable-diagram-213.svg +[collections3]: /resources/images/tour/collections-mutable-diagram-213.svg diff --git a/_ru/scala3/book/collections-intro.md b/_ru/scala3/book/collections-intro.md new file mode 100644 index 0000000000..c29c5ecc29 --- /dev/null +++ b/_ru/scala3/book/collections-intro.md @@ -0,0 +1,22 @@ +--- +layout: multipage-overview +title: Коллекции в Scala +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице представлено введение в общие классы коллекций и их методы в Scala 3. +language: ru +num: 37 +previous-page: packaging-imports +next-page: collections-classes +--- + +В этой главе представлены наиболее распространенные коллекции Scala 3 и сопутствующие им методы. +Scala поставляется с множеством типов коллекций, +Вы можете многого добиться, начав использовать лишь небольшое количество типов, а затем, по мере необходимости, начать применять остальные. +Точно так же у каждого типа есть десятки методов, +облегчающих разработку, но можно многого добиться, начав лишь с нескольких. + +Поэтому в этом разделе представлены наиболее распространенные типы и методы коллекций, +которые вам понадобятся для начала работы. diff --git a/_ru/scala3/book/collections-methods.md b/_ru/scala3/book/collections-methods.md new file mode 100644 index 0000000000..a11cdd1738 --- /dev/null +++ b/_ru/scala3/book/collections-methods.md @@ -0,0 +1,662 @@ +--- +layout: multipage-overview +title: Методы в коллекциях +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показаны общие методы классов коллекций Scala 3. +language: ru +num: 39 +previous-page: collections-classes +next-page: collections-summary +--- + + + +Важным преимуществом коллекций Scala является то, что они поставляются с десятками методов “из коробки”, +которые доступны как для неизменяемых, так и для изменяемых типов коллекций. +Больше нет необходимости писать пользовательские циклы `for` каждый раз, когда нужно работать с коллекцией. +При переходе от одного проекта к другому, можно обнаружить, что используются одни и те же методы. + +В коллекциях доступны _десятки_ методов, поэтому здесь показаны не все из них. +Показаны только некоторые из наиболее часто используемых методов, в том числе: + +- `map` +- `filter` +- `foreach` +- `head` +- `tail` +- `take`, `takeWhile` +- `drop`, `dropWhile` +- `reduce` + +Следующие методы работают со всеми типами последовательностей, включая `List`, `Vector`, `ArrayBuffer` и т.д. +Примеры рассмотрены на `List`-е, если не указано иное. + +> Важно напомнить, что ни один из методов в `List` не изменяет список. +> Все они работают в функциональном стиле, то есть возвращают новую коллекцию с измененными результатами. + +## Примеры распространенных методов + +Для общего представления в примерах ниже показаны некоторые из наиболее часто используемых методов коллекций. +Вот несколько методов, которые не используют лямбда-выражения: + +{% tabs common-method-examples %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) + +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.intersect(List(19,20,21)) // List(20) +a.last // 10 +a.lastOption // Some(10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +``` +{% endtab %} + +{% endtabs %} + + +### Функции высшего порядка и лямбда-выражения + +Далее будут показаны некоторые часто используемые функции высшего порядка (HOF), +которые принимают лямбды (анонимные функции). +Для начала приведем несколько вариантов лямбда-синтаксиса, +начиная с самой длинной формы, поэтапно переходящей к наиболее сжатой: + +{% tabs higher-order-functions-example %} + +{% tab 'Scala 2 и 3' %} +```scala +// все эти функции одинаковые и возвращают +// одно и тоже: List(10, 20, 10) + +a.filter((i: Int) => i < 25) // 1. наиболее расширенная форма +a.filter((i) => i < 25) // 2. `Int` необязателен +a.filter(i => i < 25) // 3. скобки можно опустить +a.filter(_ < 25) // 4. `i` необязателен +``` +{% endtab %} + +{% endtabs %} + +В этих примерах: + +1. Первый пример показывает самую длинную форму. + Такое многословие требуется _редко_, только в самых сложных случаях. +2. Компилятор знает, что `a` содержит `Int`, поэтому нет необходимости повторять это в функции. +3. Если в функции только один параметр, например `i`, то скобки не нужны. +4. В случае одного параметра, если он появляется в анонимной функции только раз, его можно заменить на `_`. + +В главе [Анонимные функции][lambdas] представлена более подробная информация +и примеры правил, связанных с сокращением лямбда-выражений. + +Примеры других HOF, использующих краткий лямбда-синтаксис: + +{% tabs anonymous-functions-example %} + +{% tab 'Scala 2 и 3' %} +```scala +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ > 100) // List() +a.filterNot(_ < 25) // List(30, 40) +a.find(_ > 20) // Some(30) +a.takeWhile(_ < 30) // List(10, 20) +``` +{% endtab %} + +{% endtabs %} + +Важно отметить, что HOF также принимают в качестве параметров методы и функции, а не только лямбда-выражения. +Вот несколько примеров, в которых используется метод с именем `double`. +Снова показаны несколько вариантов лямбда-выражений: + +{% tabs method-as-parameter-example %} + +{% tab 'Scala 2 и 3' %} +```scala +def double(i: Int) = i * 2 + +// these all return `List(20, 40, 60, 80, 20)` +a.map(i => double(i)) +a.map(double(_)) +a.map(double) +``` +{% endtab %} + +{% endtabs %} + +В последнем примере, когда анонимная функция состоит из одного вызова функции, принимающей один аргумент, +нет необходимости указывать имя аргумента, поэтому даже `_` не требуется. + +Наконец, HOF можно комбинировать: + +{% tabs higher-order-functions-combination-example %} + +{% tab 'Scala 2 и 3' %} +```scala +// выдает `List(100, 200)` +a.filter(_ < 40) + .takeWhile(_ < 30) + .map(_ * 10) +``` +{% endtab %} + +{% endtabs %} + + +## Пример данных + +В следующих разделах используются такие списки: + +{% tabs sample-data %} + +{% tab 'Scala 2 и 3' %} +```scala +val oneToTen = (1 to 10).toList +val names = List("adam", "brandy", "chris", "david") +``` +{% endtab %} + +{% endtabs %} + + +## `map` + +Метод `map` проходит через каждый элемент в списке, применяя переданную функцию к элементу, по одному за раз; +затем возвращается новый список с измененными элементами. + +Вот пример применения метода `map` к списку `oneToTen`: + +{% tabs map-example %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> val doubles = oneToTen.map(_ * 2) +doubles: List[Int] = List(2, 4, 6, 8, 10, 12, 14, 16, 18, 20) +``` +{% endtab %} + +{% endtabs %} + +Также можно писать анонимные функции, используя более длинную форму, например: + +{% tabs map-example-anonymous %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> val doubles = oneToTen.map(i => i * 2) +doubles: List[Int] = List(2, 4, 6, 8, 10, 12, 14, 16, 18, 20) +``` +{% endtab %} + +{% endtabs %} + +Однако в этом документе будет всегда использоваться первая, более короткая форма. + +Вот еще несколько примеров применения метода `map` к `oneToTen` и `names`: + +{% tabs few-more-examples %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> val capNames = names.map(_.capitalize) +capNames: List[String] = List(Adam, Brandy, Chris, David) + +scala> val nameLengthsMap = names.map(s => (s, s.length)).toMap +nameLengthsMap: Map[String, Int] = Map(adam -> 4, brandy -> 6, chris -> 5, david -> 5) + +scala> val isLessThanFive = oneToTen.map(_ < 5) +isLessThanFive: List[Boolean] = List(true, true, true, true, false, false, false, false, false, false) +``` +{% endtab %} + +{% endtabs %} + +Как показано в последних двух примерах, совершенно законно (и распространено) использование `map` для возврата коллекции, +которая имеет тип, отличный от исходного типа. + + +## `filter` + +Метод `filter` создает новый список, содержащий только те элементы, которые удовлетворяют предоставленному предикату. +Предикат или условие — это функция, которая возвращает `Boolean` (`true` или `false`). +Вот несколько примеров: + +{% tabs filter-example %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> val lessThanFive = oneToTen.filter(_ < 5) +lessThanFive: List[Int] = List(1, 2, 3, 4) + +scala> val evens = oneToTen.filter(_ % 2 == 0) +evens: List[Int] = List(2, 4, 6, 8, 10) + +scala> val shortNames = names.filter(_.length <= 4) +shortNames: List[String] = List(adam) +``` +{% endtab %} + +{% endtabs %} + +Отличительной особенностью функциональных методов коллекций является то, +что их можно объединять вместе для решения задач. +Например, в этом примере показано, как связать `filter` и `map`: + +{% tabs filter-example-anonymous %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.filter(_ < 4).map(_ * 10) +``` +{% endtab %} + +{% endtabs %} + +REPL показывает результат: + +{% tabs filter-example-anonymous-repl %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> oneToTen.filter(_ < 4).map(_ * 10) +val res1: List[Int] = List(10, 20, 30) +``` +{% endtab %} + +{% endtabs %} + + +## `foreach` + +Метод `foreach` используется для перебора всех элементов коллекции. +Стоит обратить внимание, что `foreach` используется для побочных эффектов, таких как печать информации. +Вот пример с `names`: + +{% tabs foreach-example %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> names.foreach(println) +adam +brandy +chris +david +``` +{% endtab %} + +{% endtabs %} + + + +## `head` + +Метод `head` взят из Lisp и других более ранних языков функционального программирования. +Он используется для доступа к первому элементу (головному (_head_) элементу) списка: + +{% tabs head-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.head // 1 +names.head // adam +``` +{% endtab %} + +{% endtabs %} + +`String` можно рассматривать как последовательность символов, т.е. строка также является коллекцией, +а значит содержит соответствующие методы. +Вот как `head` работает со строками: + +{% tabs string-head-example %} + +{% tab 'Scala 2 и 3' %} +```scala +"foo".head // 'f' +"bar".head // 'b' +``` +{% endtab %} + +{% endtabs %} + +`head` — отличный метод для работы, но в качестве предостережения следует помнить, что +он также может генерировать исключение при вызове для пустой коллекции: + +{% tabs head-error-example %} + +{% tab 'Scala 2 и 3' %} +```scala +val emptyList = List[Int]() // emptyList: List[Int] = List() +emptyList.head // java.util.NoSuchElementException: head of empty list +``` +{% endtab %} + +{% endtabs %} + +Чтобы не натыкаться на исключение вместо `head` желательно использовать `headOption`, +особенно при разработке в функциональном стиле: + +{% tabs head-option-example %} + +{% tab 'Scala 2 и 3' %} +```scala +emptyList.headOption // None +``` +{% endtab %} + +{% endtabs %} + +`headOption` не генерирует исключение, а возвращает тип `Option` со значением `None`. +Более подробно о функциональном стиле программирования будет рассказано [в соответствующей главе][fp-intro]. + + +## `tail` + +Метод `tail` также взят из Lisp и используется для вывода всех элементов в списке после `head`. + +{% tabs tail-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.head // 1 +oneToTen.tail // List(2, 3, 4, 5, 6, 7, 8, 9, 10) + +names.head // adam +names.tail // List(brandy, chris, david) +``` +{% endtab %} + +{% endtabs %} + +Так же, как и `head`, `tail` можно использовать со строками: + +{% tabs string-tail-example %} + +{% tab 'Scala 2 и 3' %} +```scala +"foo".tail // "oo" +"bar".tail // "ar" +``` +{% endtab %} + +{% endtabs %} + +`tail` выбрасывает исключение _java.lang.UnsupportedOperationException_, если список пуст, +поэтому, как и в случае с `head` и `headOption`, существует также метод `tailOption`, +который предпочтительнее в функциональном программировании. + +Список матчится, поэтому можно использовать такие выражения: + +{% tabs tail-match-example %} + +{% tab 'Scala 2 и 3' %} +```scala +val x :: xs = names +``` +{% endtab %} + +{% endtabs %} + +Помещение этого кода в REPL показывает, что `x` назначается заглавному элементу списка, а `xs` назначается "хвосту": + +{% tabs tail-match-example-repl %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> val x :: xs = names +val x: String = adam +val xs: List[String] = List(brandy, chris, david) +``` +{% endtab %} + +{% endtabs %} + +Подобное сопоставление с образцом полезно во многих случаях, например, при написании метода `sum` с использованием рекурсии: + +{% tabs tail-match-sum-example class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +def sum(list: List[Int]): Int = list match { + case Nil => 0 + case x :: xs => x + sum(xs) +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def sum(list: List[Int]): Int = list match + case Nil => 0 + case x :: xs => x + sum(xs) +``` +{% endtab %} + +{% endtabs %} + + + +## `take`, `takeRight`, `takeWhile` + +Методы `take`, `takeRight` и `takeWhile` предоставляют удобный способ “брать” (_taking_) элементы из списка для создания нового. +Примеры `take` и `takeRight`: + +{% tabs take-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.take(1) // List(1) +oneToTen.take(2) // List(1, 2) + +oneToTen.takeRight(1) // List(10) +oneToTen.takeRight(2) // List(9, 10) +``` +{% endtab %} + +{% endtabs %} + +Обратите внимание, как эти методы работают с «пограничными» случаями, +когда запрашивается больше элементов, чем есть в последовательности, +или запрашивается ноль элементов: + +{% tabs take-edge-cases-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.take(Int.MaxValue) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.takeRight(Int.MaxValue) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.take(0) // List() +oneToTen.takeRight(0) // List() +``` +{% endtab %} + +{% endtabs %} + +А это `takeWhile`, который работает с функцией-предикатом: + +{% tabs take-while-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.takeWhile(_ < 5) // List(1, 2, 3, 4) +names.takeWhile(_.length < 5) // List(adam) +``` +{% endtab %} + +{% endtabs %} + + +## `drop`, `dropRight`, `dropWhile` + +`drop`, `dropRight` и `dropWhile` удаляют элементы из списка +и, по сути, противоположны своим аналогам “take”. +Вот некоторые примеры: + +{% tabs drop-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.drop(1) // List(2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.drop(5) // List(6, 7, 8, 9, 10) + +oneToTen.dropRight(8) // List(1, 2) +oneToTen.dropRight(7) // List(1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +Пограничные случаи: + +{% tabs drop-edge-cases-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.drop(Int.MaxValue) // List() +oneToTen.dropRight(Int.MaxValue) // List() +oneToTen.drop(0) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.dropRight(0) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +``` +{% endtab %} + +{% endtabs %} + +А это `dropWhile`, который работает с функцией-предикатом: + +{% tabs drop-while-example %} + +{% tab 'Scala 2 и 3' %} +```scala +oneToTen.dropWhile(_ < 5) // List(5, 6, 7, 8, 9, 10) +names.dropWhile(_ != "chris") // List(chris, david) +``` +{% endtab %} + +{% endtabs %} + + +## `reduce` + +Метод `reduce` позволяет свертывать коллекцию до одного агрегируемого значения. +Он принимает функцию (или анонимную функцию) и последовательно применяет эту функцию к элементам в списке. + +Лучший способ объяснить `reduce` — создать небольшой вспомогательный метод. +Например, метод `add`, который складывает вместе два целых числа, +а также предоставляет хороший вывод отладочной информации: + +{% tabs reduce-example class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +def add(x: Int, y: Int): Int = { + val theSum = x + y + println(s"received $x and $y, their sum is $theSum") + theSum +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def add(x: Int, y: Int): Int = + val theSum = x + y + println(s"received $x and $y, their sum is $theSum") + theSum +``` +{% endtab %} + +{% endtabs %} + +Рассмотрим список: + +{% tabs reduce-example-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = List(1,2,3,4) +``` +{% endtab %} + +{% endtabs %} + +вот что происходит, когда в `reduce` передается метод `add`: + +{% tabs reduce-example-evaluation %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> a.reduce(add) +received 1 and 2, their sum is 3 +received 3 and 3, their sum is 6 +received 6 and 4, their sum is 10 +res0: Int = 10 +``` +{% endtab %} + +{% endtabs %} + +Как видно из результата, функция `reduce` использует `add` для сокращения списка `a` до единственного значения, +в данном случае — суммы всех чисел в списке. + +`reduce` можно использовать с анонимными функциями: + +{% tabs reduce-example-sum %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> a.reduce(_ + _) +res0: Int = 10 +``` +{% endtab %} + +{% endtabs %} + +Аналогично можно использовать другие функции, например, умножение: + +{% tabs reduce-example-multiply %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> a.reduce(_ * _) +res1: Int = 24 +``` +{% endtab %} + +{% endtabs %} + +> Важная концепция, которую следует знать о `reduce`, заключается в том, что, как следует из ее названия +> (_reduce_ - сокращать), она используется для сокращения коллекции до одного значения. + + +## Дальнейшее изучение коллекций + +В коллекциях Scala есть десятки дополнительных методов, которые избавляют от необходимости писать еще один цикл `for`. +Более подробную информацию о коллекциях Scala см. +в разделе [Изменяемые и неизменяемые коллекции][mut-immut-colls] +и [Архитектура коллекций Scala][architecture]. + +> В качестве последнего примечания, при использовании Java-кода в проекте Scala, +> коллекции Java можно преобразовать в коллекции Scala. +> После этого, их можно использовать в выражениях `for`, +> а также воспользоваться преимуществами методов функциональных коллекций Scala. +> Более подробную информацию можно найти в разделе [Взаимодействие с Java][interacting]. + + +[interacting]: {% link _overviews/scala3-book/interacting-with-java.md %} +[lambdas]: {% link _overviews/scala3-book/fun-anonymous-functions.md %} +[fp-intro]: {% link _overviews/scala3-book/fp-intro.md %} +[mut-immut-colls]: {% link _overviews/collections-2.13/overview.md %} +[architecture]: {% link _overviews/core/architecture-of-scala-213-collections.md %} + diff --git a/_ru/scala3/book/collections-summary.md b/_ru/scala3/book/collections-summary.md new file mode 100644 index 0000000000..7d89b4961c --- /dev/null +++ b/_ru/scala3/book/collections-summary.md @@ -0,0 +1,35 @@ +--- +layout: multipage-overview +title: Обзор +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлен краткий итог главы «Коллекции». +language: ru +num: 40 +previous-page: collections-methods +next-page: fp-intro +--- + +В этой главе представлен обзор общих коллекций Scala 3 и сопутствующих им методов. +Как было показано, Scala поставляется с множеством коллекций и методов. + +Если вам нужно увидеть более подробную информацию о типах коллекций, +показанных в этой главе, см. их Scaladoc страницы: + +- [List](https://www.scala-lang.org/api/current/scala/collection/immutable/List.html) +- [Vector](https://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html) +- [ArrayBuffer](https://www.scala-lang.org/api/current/scala/collection/mutable/ArrayBuffer.html) +- [Range](https://www.scala-lang.org/api/current/scala/collection/immutable/Range.html) + +Также упоминавшиеся неизменяемые `Map` и `Set`: + +- [Map](https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html) +- [Set](https://www.scala-lang.org/api/current/scala/collection/immutable/Set.html) + +и изменяемые `Map` и `Set`: + +- [Map](https://www.scala-lang.org/api/current/scala/collection/mutable/Map.html) +- [Set](https://www.scala-lang.org/api/current/scala/collection/mutable/Set.html) + diff --git a/_ru/scala3/book/concurrency.md b/_ru/scala3/book/concurrency.md new file mode 100644 index 0000000000..ec43810bfa --- /dev/null +++ b/_ru/scala3/book/concurrency.md @@ -0,0 +1,333 @@ +--- +layout: multipage-overview +title: Параллелизм +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице обсуждается, как работает параллелизм в Scala, с упором на Scala Futures. +language: ru +num: 68 +previous-page: ca-summary +next-page: scala-tools +--- + +Для написания параллельных приложений на Scala, _можно_ использовать нативный Java `Thread`, +но Scala [Future](https://www.scala-lang.org/api/current/scala/concurrent/Future$.html) предлагает более высокоуровневый +и идиоматический подход, поэтому он предпочтителен и рассматривается в этой главе. + +## Введение + +Вот описание Scala `Future` из его Scaladoc: + +> "`Future` представляет собой значение, которое может быть или не быть доступным _в настоящее время_, +> но будет доступно в какой-то момент, или вызовет исключение, если это значение не может быть сделано доступным". + +Чтобы продемонстрировать, что это значит, сначала рассмотрим однопоточное программирование. +В однопоточном мире результат вызова метода привязывается к переменной следующим образом: + +```scala +def aShortRunningTask(): Int = 42 +val x = aShortRunningTask() +``` + +В этом коде значение `42` сразу привязывается к `x`. + +При работе с `Future` процесс назначения выглядит примерно так: + +```scala +def aLongRunningTask(): Future[Int] = ??? +val x = aLongRunningTask() +``` + +Но главное отличие в этом случае заключается в том, что, поскольку `aLongRunningTask` возвращает неопределенное время, +значение `x` может быть доступно или недоступно _в данный момент_, но оно будет доступно в какой-то момент — в будущем. + +Другой способ взглянуть на это с точки зрения блокировки. +В этом однопоточном примере оператор `println` не печатается до тех пор, пока не завершится выполнение `aShortRunningTask`: + +```scala +def aShortRunningTask(): Int = + Thread.sleep(500) + 42 +val x = aShortRunningTask() +println("Here") +``` + +И наоборот, если `aShortRunningTask` создается как `Future`, оператор `println` печатается почти сразу, +потому что `aShortRunningTask` порождается в другом потоке — он не блокируется. + +В этой главе будет рассказано, как использовать `Future`, +в том числе как запускать несколько `Future` параллельно и объединять их результаты в выражении `for`. +Также будут показаны примеры методов, которые используются для обработки значения `Future` после его возврата. + +> О `Future`, важно знать, что они задуманы как одноразовая конструкция +> "Обработайте это относительно медленное вычисление в каком-нибудь другом потоке и верните мне результат, когда закончите". +> В отличие от этого, акторы [Akka](https://akka.io) предназначены для работы в течение длительного времени +> и отвечают на множество запросов в течение своей жизни. +> В то время как субъект может жить вечно, `Future` в конечном итоге содержит результат вычисления, +> которое выполнялось только один раз. + +## Пример в REPL + +`Future` используется для создания временного кармана параллелизма. +Например, можно использовать `Future`, когда нужно вызвать алгоритм, +который выполняется неопределенное количество времени — например, вызов удаленного микросервиса, — +поэтому его желательно запустить вне основного потока. + +Чтобы продемонстрировать, как это работает, начнем с примера `Future` в REPL. +Во-первых, вставим необходимые инструкции импорта: + +```scala +import scala.concurrent.Future +import scala.concurrent.ExecutionContext.Implicits.global +import scala.util.{Failure, Success} +``` + +Теперь можно создать `Future`. +Для этого примера сначала определим долговременный однопоточный алгоритм: + +```scala +def longRunningAlgorithm() = + Thread.sleep(10_000) + 42 +``` + +Этот причудливый алгоритм возвращает целочисленное значение `42` после десятисекундной задержки. +Теперь вызовем этот алгоритм, поместив его в конструктор `Future` и присвоив результат переменной: + +```scala +scala> val eventualInt = Future(longRunningAlgorithm()) +eventualInt: scala.concurrent.Future[Int] = Future() +``` + +Вычисления начинают выполняться после вызова `longRunningAlgorithm()`. +Если сразу проверить значение переменной `eventualInt`, то можно увидеть, что `Future` еще не завершен: + +```scala +scala> eventualInt +val res1: scala.concurrent.Future[Int] = Future() +``` + +Но если проверить через десять секунд ещё раз, то можно увидеть, что оно выполнено успешно: + +```scala +scala> eventualInt +val res2: scala.concurrent.Future[Int] = Future(Success(42)) +``` + +Хотя это относительно простой пример, он демонстрирует основной подход: +просто создайте новое `Future` с помощью своего долговременного алгоритма. + +Одна вещь, на которую следует обратить внимание - +это то, что ожидаемый результат `42` обернут в `Success`, который обернут в `Future`. +Это ключевая концепция для понимания: значение `Future` всегда является экземпляром одного из `scala.util.Try`: `Success` или `Failure`. +Поэтому, при работе с результатом `Future`, используются обычные методы обработки `Try`. + +### Использование `map` с `Future` + +`Future` содержит метод `map`, который используется точно так же, как метод `map` для коллекций. +Вот как выглядит результат, при вызове `map` сразу после создания переменной `a`: + +```scala +scala> val a = Future(longRunningAlgorithm()).map(_ * 2) +a: scala.concurrent.Future[Int] = Future() +``` + +Как показано, для `Future`, созданного с помощью `longRunningAlgorithm`, первоначальный вывод показывает `Future()`. +Но если проверить значение `a` через десять секунд, то можно увидеть, что оно содержит ожидаемый результат `84`: + +```scala +scala> a +res1: scala.concurrent.Future[Int] = Future(Success(84)) +``` + +Еще раз, успешный результат обернут внутри `Success` и `Future`. + +### Использование методов обратного вызова с `Future` + +В дополнение к функциям высшего порядка, таким как `map`, с `Future` также можно использовать методы обратного вызова. +Одним из часто используемых методов обратного вызова является `onComplete`, принимающий _частично определенную функцию_, +в которой обрабатываются случаи `Success` и `Failure`: + +```scala +Future(longRunningAlgorithm()).onComplete { + case Success(value) => println(s"Got the callback, value = $value") + case Failure(e) => e.printStackTrace +} +``` + +Если вставить этот код в REPL, то в конечном итоге придет результат: + +```scala +Got the callback, value = 42 +``` + +## Другие методы `Future` + +Класс `Future` содержит некоторые методы, которые можно найти в классах коллекций Scala, в том числе: + +- `filter` +- `flatMap` +- `map` + +Методы обратного вызова: + +- `onComplete` +- `andThen` +- `foreach` + +Другие методы трансформации: + +- `fallbackTo` +- `recover` +- `recoverWith` + +См. страницу [Futures and Promises][futures] для обсуждения дополнительных методов, доступных для `Future`. + +## Запуск нескольких `Future` и объединение результатов + +Чтобы запустить несколько вычислений параллельно и соединить их результаты после завершения всех `Future`, +можно использовать выражение `for`. + +Правильный подход такой: + +1. Запустить вычисления, которые возвращают `Future` результаты +2. Объединить их результаты в выражении `for` +3. Извлечь объединенный результат, используя `onComplete` или аналогичный метод + +### Пример + +Три шага правильного подхода показаны в следующем примере. +Ключевой момент - сначала запускаются вычисления, возвращающие `Future`, а затем они объединяются в выражении `for`: + +```scala +import scala.concurrent.Future +import scala.concurrent.ExecutionContext.Implicits.global +import scala.util.{Failure, Success} + +val startTime = System.currentTimeMillis() +def delta() = System.currentTimeMillis() - startTime +def sleep(millis: Long) = Thread.sleep(millis) + +@main def multipleFutures1 = + + println(s"creating the futures: ${delta()}") + + // (1) запуск вычислений, возвращающих Future + val f1 = Future { sleep(800); 1 } // в конце концов возвращается 1 + val f2 = Future { sleep(200); 2 } // в конце концов возвращается 2 + val f3 = Future { sleep(400); 3 } // в конце концов возвращается 3 + + // (2) объединение нескольких Future в выражении `for` + val result = + for + r1 <- f1 + r2 <- f2 + r3 <- f3 + yield + println(s"in the 'yield': ${delta()}") + (r1 + r2 + r3) + + // (3) обработка результата + result.onComplete { + case Success(x) => + println(s"in the Success case: ${delta()}") + println(s"result = $x") + case Failure(e) => + e.printStackTrace + } + + println(s"before the 'sleep(3000)': ${delta()}") + + // важно для небольшой параллельной демонстрации: не глушить jvm + sleep(3000) +``` + +После запуска этого приложения, вывод выглядит следующим образом: + +``` +creating the futures: 1 +before the 'sleep(3000)': 2 +in the 'yield': 806 +in the Success case: 806 +result = 6 +``` + +Как показывает вывод, `Future` создаются очень быстро, +и всего за две миллисекунды достигается оператор печати непосредственно перед операцией `sleep(3000)` в конце метода. +Весь этот код выполняется в основном потоке JVM. Затем, через 806 мс, три `Future` завершаются, и выполняется код в блоке `yield`. +Затем код немедленно переходит к варианту `Success` в методе `onComplete`. + +Вывод 806 мс является ключом к тому, чтобы убедиться, что три вычисления выполняются параллельно. +Если бы они выполнялись последовательно, общее время составило бы около 1400 мс — сумма времени ожидания трех вычислений. +Но поскольку они выполняются параллельно, общее время чуть больше, чем у самого продолжительного вычисления `f1`, +которое составляет 800 мс. + +> Обратите внимание, что если бы вычисления выполнялись в выражении `for`, +> они выполнялись бы последовательно, а не параллельно: +> +> ``` +> // последовательное выполнение (без параллелизма!) +> for +> r1 <- Future { sleep(800); 1 } +> r2 <- Future { sleep(200); 2 } +> r3 <- Future { sleep(400); 3 } +> yield +> r1 + r2 + r3 +> ``` +> +> Итак, если необходимо, чтобы вычисления выполнялись параллельно, не забудьте запустить их вне выражения `for`. + +### Метод, возвращающий Future + +Было показано, как передавать однопоточный алгоритм в конструктор `Future`. +Ту же технику можно использовать для создания метода, который возвращает `Future`: + +```scala +// моделируем медленно работающий метод +def slowlyDouble(x: Int, delay: Long): Future[Int] = Future { + sleep(delay) + x * 2 +} +``` + +Как и в предыдущих примерах, достаточно просто присвоить результат вызова метода новой переменной. +Тогда, если сразу проверить результат, то можно увидеть, что он не завершен, +но по истечении времени задержки в `Future` результат будет выдан: + +``` +scala> val f = slowlyDouble(2, 5_000L) +val f: concurrent.Future[Int] = Future() + +scala> f +val res0: concurrent.Future[Int] = Future() + +scala> f +val res1: concurrent.Future[Int] = Future(Success(4)) +``` + +## Ключевые моменты о Future + +Надеюсь, эти примеры дадут вам представление о том, как работает Scala `Future`. +Подводя итог, несколько ключевых моментов о `Future`: + +- `Future` создается для запуска задач вне основного потока +- `Future` предназначены для одноразовых, потенциально длительных параллельных задач, которые _в конечном итоге_ возвращают значение; + они создают временный карман параллелизма +- `Future` начинает работать в момент построения +- преимущество `Future` над потоками заключается в том, что они работают с выражениями `for` + и имеют множество методов обратного вызова, упрощающих процесс работы с параллельными потоками +- при работе с `Future` не нужно беспокоиться о низкоуровневых деталях управления потоками +- результат `Future` обрабатывается с помощью методов обратного вызова, таких как `onComplete` и `andThen`, + или методов преобразования, таких как `filter`, `map` и т.д. +- значение внутри `Future` всегда является экземпляром одного из типов `Try`: `Success` или `Failure` +- при использовании нескольких `Future` для получения одного результата, они объединяются в выражении `for` + +Кроме того, как было видно по операторам `import`, Scala `Future` зависит от `ExecutionContext`. + +Дополнительные сведения о `Future` см. в статье [Futures and Promises][futures], +в которой обсуждаются futures, promises и execution contexts. +В ней также обсуждается, как выражение `for` транслируется в операцию `flatMap`. + +[futures]: {% link _overviews/core/futures.md %} diff --git a/_ru/scala3/book/control-structures.md b/_ru/scala3/book/control-structures.md new file mode 100644 index 0000000000..41b5e0646f --- /dev/null +++ b/_ru/scala3/book/control-structures.md @@ -0,0 +1,1016 @@ +--- +layout: multipage-overview +title: Структуры управления +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице представлено введение в структуры управления Scala, включая if/then/else, циклы for, выражения for, выражения match, try/catch/finally и циклы while. +language: ru +num: 19 +previous-page: string-interpolation +next-page: domain-modeling-intro +--- + + +В Scala есть все структуры управления, которые вы ожидаете найти в языке программирования, в том числе: + +- `if`/`then`/`else` +- циклы `for` +- циклы `while` +- `try`/`catch`/`finally` + +Здесь также есть две другие мощные конструкции, которые вы, возможно, не видели раньше, +в зависимости от вашего опыта программирования: + +- `for` выражения (также известные как _`for` comprehensions_) +- `match` выражения + +Все они продемонстрированы в следующих разделах. + + +## Конструкция if/then/else + +Однострочный Scala оператор `if` выглядит так: + +{% tabs control-structures-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-1 %} +```scala +if (x == 1) println(x) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-1 %} +```scala +if x == 1 then println(x) +``` +{% endtab %} +{% endtabs %} + +Когда необходимо выполнить несколько строк кода после `if`, используется синтаксис: + +{% tabs control-structures-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-2 %} +```scala +if (x == 1) { + println("x is 1, as you can see:") + println(x) +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-2 %} +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +``` +{% endtab %} +{% endtabs %} + +`if`/`else` синтаксис выглядит так: + +{% tabs control-structures-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-3 %} +```scala +if (x == 1) { + println("x is 1, as you can see:") + println(x) +} else { + println("x was not 1") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-3 %} +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +else + println("x was not 1") +``` +{% endtab %} +{% endtabs %} + +А это синтаксис `if`/`else if`/`else`: + +{% tabs control-structures-4 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-4 %} +```scala +if (x < 0) + println("negative") +else if (x == 0) + println("zero") +else + println("positive") +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-4 %} +```scala +if x < 0 then + println("negative") +else if x == 0 then + println("zero") +else + println("positive") +``` +{% endtab %} +{% endtabs %} + +### Утверждение `end if` + +
            +  Это новое в Scala 3 и не поддерживается в Scala 2. +
            + +При желании можно дополнительно включить оператор `end if` в конце каждого выражения: +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +end if +``` + +### `if`/`else` выражения всегда возвращают результат + +Сравнения `if`/`else` образуют _выражения_ - это означает, что они возвращают значение, которое можно присвоить переменной. +Поэтому нет необходимости в специальном тернарном операторе: + +{% tabs control-structures-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-6 %} +```scala +val minValue = if (a < b) a else b +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-6 %} +```scala +val minValue = if a < b then a else b +``` +{% endtab %} +{% endtabs %} + + +Поскольку эти выражения возвращают значение, то выражения `if`/`else` можно использовать в качестве тела метода: + +{% tabs control-structures-7 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-7 %} +```scala +def compare(a: Int, b: Int): Int = + if (a < b) + -1 + else if (a == b) + 0 + else + 1 +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-7 %} +```scala +def compare(a: Int, b: Int): Int = + if a < b then + -1 + else if a == b then + 0 + else + 1 +``` +{% endtab %} +{% endtabs %} + +### В сторону: программирование, ориентированное на выражения + +Кратко о программировании в целом: когда каждое написанное вами выражение возвращает значение, +такой стиль называется _программированием, ориентированным на выражения_, +или EOP (_expression-oriented programming_). +Например, это _выражение_: + +{% tabs control-structures-8 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-8 %} +```scala +val minValue = if (a < b) a else b +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-8 %} +```scala +val minValue = if a < b then a else b +``` +{% endtab %} +{% endtabs %} + +И наоборот, строки кода, которые не возвращают значения, называются _операторами_ +и используются для получения _побочных эффектов_. +Например, эти строки кода не возвращают значения, поэтому они используются для побочных эффектов: + +{% tabs control-structures-9 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-9 %} +```scala +if (a == b) action() +println("Hello") +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-9 %} +```scala +if a == b then action() +println("Hello") +``` +{% endtab %} +{% endtabs %} + +В первом примере метод `action` запускается как побочный эффект, когда `a` равно `b`. +Второй пример используется для побочного эффекта печати строки в STDOUT. +Когда вы узнаете больше о Scala, то обнаружите, что пишете больше _выражений_ и меньше _операторов_. + +## Циклы `for` + +В самом простом случае цикл `for` в Scala можно использовать для перебора элементов в коллекции. +Например, имея последовательность целых чисел, +вы можете перебрать ее элементы и вывести их значения следующим образом: + +{% tabs control-structures-10 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-10 %} +```scala +val ints = Seq(1, 2, 3) +for (i <- ints) println(i) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-10 %} +```scala +val ints = Seq(1, 2, 3) +for i <- ints do println(i) +``` +{% endtab %} +{% endtabs %} + + +Код `i <- ints` называется _генератором_. + +Вот как выглядит результат в Scala REPL: + +{% tabs control-structures-11 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for (i <- ints) println(i) +1 +2 +3 +```` +{% endtab %} +{% tab 'Scala 3' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for i <- ints do println(i) +1 +2 +3 +```` +{% endtab %} +{% endtabs %} + + +Если вам нужен многострочный блок кода после генератора `for`, используйте следующий синтаксис: + +{% tabs control-structures-12 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-12 %} +```scala +for (i <- ints) { + val x = i * 2 + println(s"i = $i, x = $x") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-12 %} +```scala +for i <- ints +do + val x = i * 2 + println(s"i = $i, x = $x") +``` +{% endtab %} +{% endtabs %} + + +### Несколько генераторов + +Циклы `for` могут иметь несколько генераторов, как показано в этом примере: + +{% tabs control-structures-13 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-13 %} +```scala +for { + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +} { + println(s"i = $i, j = $j, k = $k") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-13 %} +```scala +for + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +do + println(s"i = $i, j = $j, k = $k") +``` +{% endtab %} +{% endtabs %} + + +Это выражение выводит следующее: + +```` +i = 1, j = a, k = 1 +i = 1, j = a, k = 6 +i = 1, j = b, k = 1 +i = 1, j = b, k = 6 +i = 2, j = a, k = 1 +i = 2, j = a, k = 6 +i = 2, j = b, k = 1 +i = 2, j = b, k = 6 +```` + +### "Ограничители" + +Циклы `for` также могут содержать операторы `if`, известные как _ограничители_ (_guards_): + +{% tabs control-structures-14 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-14 %} +```scala +for { + i <- 1 to 5 + if i % 2 == 0 +} { + println(i) +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-14 %} +```scala +for + i <- 1 to 5 + if i % 2 == 0 +do + println(i) +``` +{% endtab %} +{% endtabs %} + + +Результат этого цикла: + +```` +2 +4 +```` + +Цикл `for` может содержать столько стражников, сколько необходимо. +В этом примере показан один из способов печати числа `4`: + +{% tabs control-structures-15 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-15 %} +```scala +for { + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +} { + println(i) +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-15 %} +```scala +for + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +do + println(i) +``` +{% endtab %} +{% endtabs %} + +### Использование `for` с Maps + +Вы также можете использовать циклы `for` с `Map`. +Например, если задана такая `Map` с аббревиатурами штатов и их полными названиями: + +{% tabs map %} +{% tab 'Scala 2 и 3' for=map %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AR" -> "Arizona" +) +``` +{% endtab %} +{% endtabs %} + +, то можно распечатать ключи и значения, используя `for`. Например: + +{% tabs control-structures-16 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-16 %} +```scala +for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-16 %} +```scala +for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +``` +{% endtab %} +{% endtabs %} + +Вот как это выглядит в REPL: + +{% tabs control-structures-17 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-17 %} +```scala +scala> for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-17 %} +```scala +scala> for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` +{% endtab %} +{% endtabs %} + +Когда цикл `for` перебирает мапу, каждая пара ключ/значение привязывается +к переменным `abbrev` и `fullName`, которые находятся в кортеже: + +```scala +(abbrev, fullName) <- states +``` + +По мере выполнения цикла переменная `abbrev` принимает значение текущего _ключа_ в мапе, +а переменная `fullName` - соответствующему ключу _значению_. + +## Выражение `for` + +В предыдущих примерах циклов `for` все эти циклы использовались для _побочных эффектов_, +в частности для вывода этих значений в STDOUT с помощью `println`. + +Важно знать, что вы также можете создавать _выражения_ `for`, которые возвращают значения. +Вы создаете выражение `for`, добавляя ключевое слово `yield` и возвращаемое выражение, например: + +{% tabs control-structures-18 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-18 %} +```scala +val list = + for (i <- 10 to 12) + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-18 %} +```scala +val list = + for i <- 10 to 12 + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` +{% endtab %} +{% endtabs %} + + +После выполнения этого выражения `for` переменная `list` содержит `Vector` с отображаемыми значениями. +Вот как работает выражение: + +1. Выражение `for` начинает перебирать значения в диапазоне `(10, 11, 12)`. + Сначала оно работает со значением `10`, умножает его на `2`, затем выдает результат - `20`. +2. Далее берет `11` — второе значение в диапазоне. Умножает его на `2`, а затем выдает значение `22`. + Можно представить эти полученные значения как накопление во временном хранилище. +3. Наконец, цикл берет число `12` из диапазона, умножает его на `2`, получая число `24`. + Цикл завершается в этой точке и выдает конечный результат - `Vector(20, 22, 24)`. + +Хотя целью этого раздела является демонстрация выражений `for`, полезно знать, +что показанное выражение `for` эквивалентно вызову метода `map`: + +{% tabs map-call %} +{% tab 'Scala 2 и 3' for=map-call %} +```scala +val list = (10 to 12).map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +Выражения `for` можно использовать в любой момент, когда вам нужно просмотреть все элементы в коллекции +и применить алгоритм к этим элементам для создания нового списка. + +Вот пример, который показывает, как использовать блок кода после `yield`: + +{% tabs control-structures-19 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-19 %} +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for (name <- names) yield { + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName +} + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-19 %} +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for name <- names yield + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` +{% endtab %} +{% endtabs %} + +### Использование выражения `for` в качестве тела метода + + +Поскольку выражение `for` возвращает результат, его можно использовать в качестве тела метода, +который возвращает полезное значение. +Этот метод возвращает все значения в заданном списке целых чисел, которые находятся между `3` и `10`: + +{% tabs control-structures-20 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-20 %} +```scala +def between3and10(xs: List[Int]): List[Int] = + for { + x <- xs + if x >= 3 + if x <= 10 + } yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-20 %} +```scala +def between3and10(xs: List[Int]): List[Int] = + for + x <- xs + if x >= 3 + if x <= 10 + yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` +{% endtab %} +{% endtabs %} + +## Циклы `while` + +Синтаксис цикла `while` в Scala выглядит следующим образом: + +{% tabs control-structures-21 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-21 %} +```scala +var i = 0 + +while (i < 3) { + println(i) + i += 1 +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-21 %} +```scala +var i = 0 + +while i < 3 do + println(i) + i += 1 +``` +{% endtab %} +{% endtabs %} + +## `match` выражения + +Сопоставление с образцом (_pattern matching_) является основой функциональных языков программирования. +Scala включает в себя pattern matching, обладающий множеством возможностей. + +В самом простом случае можно использовать выражение `match`, подобное оператору Java `switch`, +сопоставляя на основе целочисленного значения. +Как и предыдущие структуры, сопоставление с образцом - это действительно выражение, поскольку оно вычисляет результат: + +{% tabs control-structures-22 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-22 %} +```scala +// `i` is an integer +val day = i match { + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // по умолчанию, перехватывает остальное +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-22 %} +```scala +// `i` is an integer +val day = i match + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // по умолчанию, перехватывает остальное +``` +{% endtab %} +{% endtabs %} + + +В этом примере переменная `i` сопоставляется с заданными числами. +Если она находится между `0` и `6`, `day` принимает значение строки, представляющей день недели. +В противном случае она соответствует подстановочному знаку, представленному символом `_`, +и `day` принимает значение строки `"invalid day"`. + +Поскольку сопоставляемые значения рассматриваются в том порядке, в котором они заданы, +и используется первое совпадение, +случай по умолчанию, соответствующий любому значению, должен идти последним. +Любые сопоставляемые случаи после значения по умолчанию будут помечены как недоступные и будет выведено предупреждение. + +> При написании простых выражений соответствия, подобных этому, рекомендуется использовать аннотацию `@switch` для переменной `i`. +> Эта аннотация содержит предупреждение во время компиляции, если switch не может быть скомпилирован в `tableswitch` +> или `lookupswitch`, которые лучше подходят с точки зрения производительности. + + +### Использование значения по умолчанию + +Когда необходимо получить доступ к универсальному значению по умолчанию в `match` выражении, +просто укажите вместо `_` имя переменной в левой части оператора `case`, +а затем используйте это имя переменной в правой части оператора при необходимости: + +{% tabs control-structures-23 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-23 %} +```scala +i match { + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-23 %} +```scala +i match + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what") +``` +{% endtab %} +{% endtabs %} + +Имя, используемое в шаблоне, должно начинаться со строчной буквы. +Имя, начинающееся с заглавной буквы, не представляет собой новую переменную, +но соответствует значению в области видимости: + +{% tabs control-structures-24 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-24 %} +```scala +val N = 42 +i match { + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-24 %} +```scala +val N = 42 +i match + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +``` +{% endtab %} +{% endtabs %} + +Если `i` равно `42`, то оно будет соответствовать `case N` и напечатает строку `"42"`. +И не достигнет случая по умолчанию. + +### Обработка нескольких возможных совпадений в одной строке + +Как уже упоминалось, `match` выражения многофункциональны. +В этом примере показано, как в каждом операторе `case` использовать несколько возможных совпадений: + +{% tabs control-structures-25 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-25 %} +```scala +val evenOrOdd = i match { + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-25 %} +```scala +val evenOrOdd = i match + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +``` +{% endtab %} +{% endtabs %} + +### Использование `if` стражников в `case` предложениях + +В case выражениях также можно использовать стражников. +В этом примере второй и третий case используют стражников для сопоставления нескольких целочисленных значений: + +{% tabs control-structures-26 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-26 %} +```scala +i match { + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-26 %} +```scala +i match + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +``` +{% endtab %} +{% endtabs %} + + +Вот еще один пример, который показывает, как сопоставить заданное значение с диапазоном чисел: + +{% tabs control-structures-27 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-27 %} +```scala +i match { + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-27 %} +```scala +i match + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +``` +{% endtab %} +{% endtabs %} + + +#### Case классы и сопоставление с образцом + +Вы также можете извлекать поля из `case` классов — и классов, которые имеют корректно написанные методы `apply`/`unapply` — +и использовать их в своих условиях. +Вот пример использования простого case класса `Person`: + +{% tabs control-structures-28 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-28 %} +```scala +case class Person(name: String) + +def speak(p: Person) = p match { + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") +} + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-28 %} +```scala +case class Person(name: String) + +def speak(p: Person) = p match + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` +{% endtab %} +{% endtabs %} + +### Использование `match` выражения в качестве тела метода + +Поскольку `match` выражения возвращают значение, их можно использовать в качестве тела метода. +Метод `isTruthy` принимает в качестве входного параметра значение `Matchable` +и возвращает `Boolean` на основе сопоставления с образцом: + +{% tabs control-structures-29 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-29 %} +```scala +def isTruthy(a: Matchable) = a match { + case 0 | "" | false => false + case _ => true +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-29 %} +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" | false => false + case _ => true +``` +{% endtab %} +{% endtabs %} + +Входной параметр `a` имеет [тип `Matchable`][matchable], являющийся основой всех типов Scala, +для которых может выполняться сопоставление с образцом. +Метод реализован путем сопоставления на входе в метод, обрабатывая два варианта: +первый проверяет, является ли заданное значение целым числом `0`, пустой строкой или `false` и в этом случае возвращается `false`. +Для любого другого значения в случае по умолчанию мы возвращаем `true`. +Примеры ниже показывают, как работает этот метод: + +{% tabs is-truthy-call %} +{% tab 'Scala 2 и 3' for=is-truthy-call %} +```scala +isTruthy(0) // false +isTruthy(false) // false +isTruthy("") // false +isTruthy(1) // true +isTruthy(" ") // true +isTruthy(2F) // true +``` +{% endtab %} +{% endtabs %} + +Использование сопоставления с образцом в качестве тела метода очень распространено. + +#### Использование различных шаблонов в сопоставлении с образцом + +Для выражения `match` можно использовать множество различных шаблонов. +Например: + +- Сравнение с константой (такое как `case 3 =>`) +- Сравнение с последовательностями (такое как `case List(els : _*) =>`) +- Сравнение с кортежами (такое как `case (x, y) =>`) +- Сравнение с конструктором класса (такое как `case Person(first, last) =>`) +- Сравнение по типу (такое как `case p: Person =>`) + +Все эти виды шаблонов показаны в следующем методе `pattern`, +который принимает входной параметр типа `Matchable` и возвращает `String`: + +{% tabs control-structures-30 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-30 %} +```scala +def pattern(x: Matchable): String = x match { + + // сравнение с константой + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // сравнение с последовательностями + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // сравнение с кортежами + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // сравнение с конструктором класса + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // сравнение по типу + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // значение по умолчанию с подстановочным знаком + case _ => "Unknown" +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-30 %} +```scala +def pattern(x: Matchable): String = x match + + // сравнение с константой + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // сравнение с последовательностями + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // сравнение с кортежами + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // сравнение с конструктором класса + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // сравнение по типу + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // значение по умолчанию с подстановочным знаком + case _ => "Unknown" +``` +{% endtab %} +{% endtabs %} + +## try/catch/finally + +Как и в Java, в Scala есть конструкция `try`/`catch`/`finally`, позволяющая перехватывать исключения и управлять ими. +Для обеспечения согласованности Scala использует тот же синтаксис, что и выражения `match`, +и поддерживает сопоставление с образцом для различных возможных исключений. + +В следующем примере `openAndReadAFile` - это метод, который выполняет то, что следует из его названия: +он открывает файл и считывает из него текст, присваивая результат изменяемой переменной `text`: + +{% tabs control-structures-31 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-31 %} +```scala +var text = "" +try { + text = openAndReadAFile(filename) +} catch { + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +} finally { + // здесь необходимо закрыть ресурсы + println("Came to the 'finally' clause.") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-31 %} +```scala +var text = "" +try + text = openAndReadAFile(filename) +catch + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +finally + // здесь необходимо закрыть ресурсы + println("Came to the 'finally' clause.") +``` +{% endtab %} +{% endtabs %} + +Предполагая, что метод `openAndReadAFile` использует Java `java.io.*` классы для чтения файла +и не перехватывает его исключения, попытка открыть и прочитать файл может привести как к `FileNotFoundException`, +так и к `IOException`, и эти два исключения перехватываются в блоке `catch` этого примера. + +[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html diff --git a/_ru/scala3/book/domain-modeling-fp.md b/_ru/scala3/book/domain-modeling-fp.md new file mode 100644 index 0000000000..a5bdb326c5 --- /dev/null +++ b/_ru/scala3/book/domain-modeling-fp.md @@ -0,0 +1,825 @@ +--- +layout: multipage-overview +title: Моделирование ФП +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлено введение в моделирование предметной области с использованием ФП в Scala 3. +language: ru +num: 23 +previous-page: domain-modeling-oop +next-page: methods-intro +--- + + +В этой главе представлено введение в моделирование предметной области +с использованием функционального программирования (ФП) в Scala 3. +При моделировании окружающего нас мира с помощью ФП обычно используются следующие конструкции Scala: + +- Перечисления +- Case классы +- Trait-ы + +> Если вы не знакомы с алгебраическими типами данных (ADT) и их обобщенной версией (GADT), +> то можете прочитать главу ["Алгебраические типы данных"][adts], прежде чем читать этот раздел. + +## Введение + +В ФП *данные* и *операции над этими данными* — это две разные вещи; вы не обязаны инкапсулировать их вместе, как в ООП. + +Концепция аналогична числовой алгебре. +Когда вы думаете о целых числах, больших либо равных нулю, +у вас есть *набор* возможных значений, который выглядит следующим образом: + +```` +0, 1, 2 ... Int.MaxValue +```` + +Игнорируя деление целых чисел, возможные *операции* над этими значениями такие: + +```` ++, -, * +```` + +Схема ФП реализуется аналогичным образом: + +- описывается свой набор значений (данные) +- описываются операции, которые работают с этими значениями (функции) + +> Как будет видно, рассуждения о программах в этом стиле сильно отличаются от объектно-ориентированного программирования. +> Проще говоря о данных в ФП: +> Отделение функциональности от данных позволяет проверять свои данные, не беспокоясь о поведении. + +В этой главе мы смоделируем данные и операции для “пиццы” в пиццерии. +Будет показано, как реализовать часть “данных” модели Scala/ФП, +а затем - несколько различных способов организации операций с этими данными. + +## Моделирование данных + +В Scala достаточно просто описать модель данных: + +- если необходимо смоделировать данные с различными вариантами, то используется конструкция `enum` (или `case object` в Scala 2) +- если необходимо только сгруппировать сущности (или нужен более детальный контроль), то используются case class-ы + +### Описание вариантов + +Данные, которые просто состоят из различных вариантов, таких как размер корочки, тип корочки и начинка, +кратко моделируются с помощью перечислений: + +{% tabs data_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_1 %} + +В Scala 2 перечисления выражаются комбинацией `sealed class` и нескольких `case object`, которые расширяют класс: + +```scala +sealed abstract class CrustSize +object CrustSize { + case object Small extends CrustSize + case object Medium extends CrustSize + case object Large extends CrustSize +} + +sealed abstract class CrustType +object CrustType { + case object Thin extends CrustType + case object Thick extends CrustType + case object Regular extends CrustType +} + +sealed abstract class Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_1 %} + +В Scala 3 перечисления кратко выражаются конструкцией `enum`: + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +> Типы данных, которые описывают различные варианты (например, `CrustSize`), +> также иногда называются суммированными типами (_sum types_). + +### Описание основных данных + +Пиццу можно рассматривать как _составной_ контейнер с различными атрибутами, указанными выше. +Мы можем использовать `case class`, чтобы описать, +что `Pizza` состоит из `crustSize`, `crustType` и, возможно, нескольких `toppings`: + +{% tabs data_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_2 %} + +```scala +import CrustSize._ +import CrustType._ +import Topping._ + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% tab 'Scala 3' for=data_2 %} + +```scala +import CrustSize.* +import CrustType.* +import Topping.* + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% endtabs %} + +> Типы данных, объединяющие несколько компонентов (например, `Pizza`), также иногда называют типами продуктов (_product types_). + +И все. Это модель данных для системы доставки пиццы в стиле ФП. +Решение очень лаконично, поскольку оно не требует объединения модели данных с операциями с пиццей. +Модель данных легко читается, как объявление дизайна для реляционной базы данных. +Также очень легко создавать значения нашей модели данных и проверять их: + +{% tabs data_3 %} +{% tab 'Scala 2 и 3' for=data_3 %} + +```scala +val myFavPizza = Pizza(Small, Regular, Seq(Cheese, Pepperoni)) +println(myFavPizza.crustType) // печатает Regular +``` + +{% endtab %} +{% endtabs %} + +#### Подробнее о модели данных + +Таким же образом можно было бы смоделировать всю систему заказа пиццы. +Вот несколько других `case class`-ов, которые используются для моделирования такой системы: + +{% tabs data_4 %} +{% tab 'Scala 2 и 3' for=data_4 %} + +```scala +case class Address( + street1: String, + street2: Option[String], + city: String, + state: String, + zipCode: String +) + +case class Customer( + name: String, + phone: String, + address: Address +) + +case class Order( + pizzas: Seq[Pizza], + customer: Customer +) +``` + +{% endtab %} +{% endtabs %} + +#### “Узкие доменные объекты” + +В своей книге *Functional and Reactive Domain Modeling*, Debasish Ghosh утверждает, +что там, где специалисты по ООП описывают свои классы как “широкие модели предметной области”, +которые инкапсулируют данные и поведение, +модели данных ФП можно рассматривать как “узкие объекты предметной области”. +Это связано с тем, что, как показано выше, модели данных определяются как `case` классы с атрибутами, +но без поведения, что приводит к коротким и лаконичным структурам данных. + +## Моделирование операций + +Возникает интересный вопрос: поскольку ФП отделяет данные от операций над этими данными, +то как эти операции реализуются в Scala? + +Ответ на самом деле довольно прост: пишутся функции (или методы), работающие со значениями смоделированных данных. +Например, можно определить функцию, которая вычисляет цену пиццы. + +{% tabs data_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match { + case Pizza(crustSize, crustType, toppings) => { + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match + case Pizza(crustSize, crustType, toppings) => + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops +``` + +{% endtab %} +{% endtabs %} + +Можно заметить, что реализация функции просто повторяет форму данных: поскольку `Pizza` является case class-ом, +используется сопоставление с образцом для извлечения компонентов, +а затем вызываются вспомогательные функции для вычисления отдельных цен. + +{% tabs data_6 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match { + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +``` + +{% endtab %} +{% endtabs %} + +Точно так же, поскольку `Topping` является перечислением, +используется сопоставление с образцом, чтобы разделить варианты. +Сыр и лук продаются по 50 центов за штуку, остальные — по 75. + +{% tabs data_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match { + // если размер корочки маленький или средний, тип не важен + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 + } +``` + +{% endtab %} + +{% tab 'Scala 3' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match + // если размер корочки маленький или средний, тип не важен + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 +``` + +{% endtab %} +{% endtabs %} + +Чтобы рассчитать цену корки, мы одновременно сопоставляем образцы как по размеру, так и по типу корки. + +> Важным моментом во всех показанных выше функциях является то, что они являются чистыми функциями (_pure functions_): +> они не изменяют данные и не имеют других побочных эффектов (таких, как выдача исключений или запись в файл). +> Всё, что они делают - это просто получают значения и вычисляют результат. + +## Как организовать функциональность? + +При реализации функции `pizzaPrice`, описанной выше, не было сказано, _где_ ее определять. +Scala предоставляет множество отличных инструментов для организации логики в различных пространствах имен и модулях. + +Существует несколько способов реализации и организации поведения: + +- определить функции в сопутствующих объектах (companion object) +- использовать модульный стиль программирования +- использовать подход “функциональных объектов” +- определить функциональность в методах расширения + +Эти различные решения показаны в оставшейся части этого раздела. + +### Сопутствующий объект + +Первый подход — определить поведение (функции) в сопутствующем объекте. + +> Как обсуждалось в разделе [“Инструменты”][modeling-tools], +> _сопутствующий объект_ — это `object` с тем же именем, что и у класса, и объявленный в том же файле, что и класс. + +При таком подходе в дополнение к `enum` или `case class` также определяется сопутствующий объект с таким же именем, +который содержит поведение (функции). + +{% tabs org_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// сопутствующий объект для case class Pizza +object Pizza { + // тоже самое, что и `pizzaPrice` + def price(p: Pizza): Double = ... +} + +sealed abstract class Topping + +// сопутствующий объект для перечисления Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping + + // тоже самое, что и `toppingPrice` + def price(t: Topping): Double = ... +} +``` + +{% endtab %} +{% tab 'Scala 3' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// сопутствующий объект для case class Pizza +object Pizza: + // тоже самое, что и `pizzaPrice` + def price(p: Pizza): Double = ... + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions + +// сопутствующий объект для перечисления Topping +object Topping: + // тоже самое, что и `toppingPrice` + def price(t: Topping): Double = ... +``` + +{% endtab %} +{% endtabs %} + +При таком подходе можно создать `Pizza` и вычислить ее цену следующим образом: + +{% tabs org_2 %} +{% tab 'Scala 2 и 3' for=org_2 %} + +```scala +val pizza1 = Pizza(Small, Thin, Seq(Cheese, Onions)) +Pizza.price(pizza1) +``` + +{% endtab %} +{% endtabs %} + +Группировка функциональности с помощью сопутствующих объектов имеет несколько преимуществ: + +- связывает функциональность с данными и облегчает их поиск программистам (и компилятору). +- создает пространство имен и, например, позволяет использовать `price` в качестве имени метода, не полагаясь на перегрузку. +- реализация `Topping.price` может получить доступ к значениям перечисления, таким как `Cheese`, без необходимости их импорта. + +Однако также есть несколько компромиссов, которые следует учитывать: + +- модель данных тесно связывается с функциональностью. + В частности, сопутствующий объект должен быть определен в том же файле, что и `case class`. +- неясно, где определять такие функции, как `crustPrice`, + которые с одинаковым успехом можно поместить в сопутствующий объект `CrustSize` или `CrustType`. + +## Модули + +Второй способ организации поведения — использование “модульного” подхода. +В книге _“Программирование на Scala”_ _модуль_ определяется как +“небольшая часть программы с четко определенным интерфейсом и скрытой реализацией”. +Давайте посмотрим, что это значит. + +### Создание интерфейса `PizzaService` + +Первое, о чем следует подумать, — это “поведение” `Pizza`. +Делая это, определяем `trait PizzaServiceInterface` следующим образом: + +{% tabs module_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_1 %} + +```scala +trait PizzaServiceInterface { + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_1 %} + +```scala +trait PizzaServiceInterface: + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +``` + +{% endtab %} +{% endtabs %} + +Как показано, каждый метод принимает `Pizza` в качестве входного параметра вместе с другими параметрами, +а затем возвращает экземпляр `Pizza` в качестве результата. + +Когда пишется такой чистый интерфейс, можно думать о нем как о контракте, +в котором говорится: “Все неабстрактные классы, расширяющие этот trait, должны предоставлять реализацию этих сервисов”. + +На этом этапе также можно представить, что вы являетесь потребителем этого API. +Когда вы это сделаете, будет полезно набросать некоторый пример “потребительского” кода, +чтобы убедиться, что API выглядит так, как хотелось: + +{% tabs module_2 %} +{% tab 'Scala 2 и 3' for=module_2 %} + +```scala +val p = Pizza(Small, Thin, Seq(Cheese)) + +// как вы хотите использовать методы в PizzaServiceInterface +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) +``` + +{% endtab %} +{% endtabs %} + +Если с этим кодом все в порядке, как правило, можно начать набрасывать другой API, например API для заказов, +но, поскольку сейчас рассматривается только `Pizza`, перейдем к созданию конкретной реализации этого интерфейса. + +> Обратите внимание, что обычно это двухэтапный процесс. +> На первом шаге набрасывается контракт API в качестве _интерфейса_. +> На втором шаге создается конкретная _реализация_ этого интерфейса. +> В некоторых случаях в конечном итоге создается несколько конкретных реализаций базового интерфейса. + +### Создание конкретной реализации + +Теперь, когда известно, как выглядит `PizzaServiceInterface`, можно создать конкретную реализацию, +написав тело для всех методов, определенных в интерфейсе: + +{% tabs module_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface { + + def price(p: Pizza): Double = + ... // реализация была дана выше + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface: + + def price(p: Pizza): Double = + ... // реализация была дана выше + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) + +end PizzaService +``` + +{% endtab %} +{% endtabs %} + +Хотя двухэтапный процесс создания интерфейса с последующей реализацией не всегда необходим, +явное продумывание API и его использования — хороший подход. + +Когда все готово, можно использовать `Pizza` и `PizzaService`: + +{% tabs module_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_4 %} + +```scala +import PizzaService._ + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// использование методов PizzaService +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // печатает 8.75 +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_4 %} + +```scala +import PizzaService.* + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// использование методов PizzaService +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // печатает 8.75 +``` + +{% endtab %} +{% endtabs %} + +### Функциональные объекты + +В книге _“Программирование на Scala”_ авторы определяют термин “Функциональные объекты” как +“объекты, которые не имеют никакого изменяемого состояния”. +Это также относится к типам в `scala.collection.immutable`. +Например, методы в `List` не изменяют внутреннего состояния, а вместо этого в результате создают копию `List`. + +Об этом подходе можно думать, как о “гибридном дизайне ФП/ООП”, потому что: + +- данные моделируются, используя неизменяемые `case` классы. +- определяется поведение (методы) _того же типа_, что и данные. +- поведение реализуется как чистые функции: они не изменяют никакого внутреннего состояния; скорее - возвращают копию. + +> Это действительно гибридный подход: как и в **дизайне ООП**, методы инкапсулированы в класс с данными, +> но, как это обычно бывает **в дизайне ФП**, методы реализованы как чистые функции, которые данные не изменяют. + +#### Пример + +Используя этот подход, можно напрямую реализовать функциональность пиццы в `case class`: + +{% tabs module_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) { + + // операции этой модели данных + def price: Double = + pizzaPrice(this) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +): + + // операции этой модели данных + def price: Double = + pizzaPrice(this) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что в отличие от предыдущих подходов, поскольку это методы класса `Pizza`, +они не принимают ссылку `Pizza` в качестве входного параметра. +Вместо этого у них есть собственная ссылка на текущий экземпляр пиццы - `this`. + +Теперь можно использовать этот новый дизайн следующим образом: + +{% tabs module_6 %} +{% tab 'Scala 2 и 3' for=module_6 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +### Методы расширения + +Методы расширения - подход, который находится где-то между первым (определение функций в сопутствующем объекте) +и последним (определение функций как методов самого типа). + +Методы расширения позволяют создавать API, похожий на API функционального объекта, +без необходимости определять функции как методы самого типа. +Это может иметь несколько преимуществ: + +- модель данных снова _очень лаконична_ и не упоминает никакого поведения. +- можно _задним числом_ развить функциональность типов дополнительными методами, не изменяя исходного определения. +- помимо сопутствующих объектов или прямых методов типов, методы расширения могут быть определены _извне_ в другом файле. + +Вернемся к примеру: + +{% tabs module_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +implicit class PizzaOps(p: Pizza) { + def price: Double = + pizzaPrice(p) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` +В приведенном выше коде мы определяем различные методы для пиццы как методы в _неявном классе_ (_implicit class_). +С `implicit class PizzaOps(p: Pizza)` тогда, где бы `PizzaOps` ни был импортирован, +его методы будут доступны в экземплярах `Pizza`. +Получатель в этом случае `p`. + +{% endtab %} +{% tab 'Scala 3' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +extension (p: Pizza) + def price: Double = + pizzaPrice(p) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +``` +В приведенном выше коде мы определяем различные методы для пиццы как _методы расширения_ (_extension methods_). +С помощью `extension (p: Pizza)` мы говорим, что хотим сделать методы доступными для экземпляров `Pizza`. +Получатель в этом случае `p`. + +{% endtab %} +{% endtabs %} + +Используя наши методы расширения, мы можем получить тот же API, что и раньше: + +{% tabs module_8 %} +{% tab 'Scala 2 и 3' for=module_8 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +При этом методы расширения можно определить в любом другом модуле. +Как правило, если вы являетесь разработчиком модели данных, то определяете свои методы расширения в сопутствующем объекте. +Таким образом, они уже доступны всем пользователям. +В противном случае методы расширения должны быть импортированы явно, чтобы их можно было использовать. + +## Резюме функционального подхода + +Определение модели данных в Scala/ФП, как правило, простое: +моделируются варианты данных с помощью перечислений и составных данных с помощью `case` классов. +Затем, чтобы смоделировать поведение, определяются функции, которые работают со значениями модели данных. +Были рассмотрены разные способы организации функций: + +- можно поместить методы в сопутствующие объекты +- можно использовать модульный стиль программирования, разделяющий интерфейс и реализацию +- можно использовать подход “функциональных объектов” и хранить методы в определенном типе данных +- можно использовать методы расширения, чтобы снабдить модель данных функциональностью + +[adts]: {% link _overviews/scala3-book/types-adts-gadts.md %} +[modeling-tools]: {% link _overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_ru/scala3/book/domain-modeling-intro.md b/_ru/scala3/book/domain-modeling-intro.md new file mode 100644 index 0000000000..79828b6d84 --- /dev/null +++ b/_ru/scala3/book/domain-modeling-intro.md @@ -0,0 +1,19 @@ +--- +layout: multipage-overview +title: Моделирование предметной области +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе показано, как можно моделировать предметную область с помощью Scala 3. +language: ru +num: 20 +previous-page: control-structures +next-page: domain-modeling-tools +--- + +В этой главе показано, как можно смоделировать предметную область с помощью Scala 3: + +- В разделе "Инструменты" представлены доступные вам инструменты, включая классы, трейты, перечисления и многое другое. +- В разделе "Моделирование ООП" рассматриваются атрибуты и поведение моделирования в стиле объектно-ориентированного программирования (ООП). +- В разделе "Моделирование ФП" рассматривается моделирование предметной области в стиле функционального программирования (ФП). diff --git a/_ru/scala3/book/domain-modeling-oop.md b/_ru/scala3/book/domain-modeling-oop.md new file mode 100644 index 0000000000..f9de517ddd --- /dev/null +++ b/_ru/scala3/book/domain-modeling-oop.md @@ -0,0 +1,602 @@ +--- +layout: multipage-overview +title: Моделирование ООП +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлено введение в моделирование предметной области с использованием ООП в Scala 3. +language: ru +num: 22 +previous-page: domain-modeling-tools +next-page: domain-modeling-fp +--- + +В этой главе представлено введение в моделирование предметной области с использованием +объектно-ориентированного программирования (ООП) в Scala 3. + +## Введение + +Scala предоставляет все необходимые инструменты для объектно-ориентированного проектирования: + +- **Traits** позволяют указывать (абстрактные) интерфейсы, а также конкретные реализации. +- **Mixin Composition** предоставляет инструменты для создания компонентов из более мелких деталей. +- **Классы** могут реализовывать интерфейсы, заданные трейтами. +- **Экземпляры** классов могут иметь свое собственное приватное состояние. +- **Subtyping** позволяет использовать экземпляр одного класса там, где ожидается экземпляр его суперкласса. +- **Модификаторы доступа** позволяют управлять, к каким членам класса можно получить доступ с помощью какой части кода. + +## Трейты + +В отличие от других языков с поддержкой ООП, таких как Java, возможно, +основным инструментом декомпозиции в Scala являются не классы, а трейты. +Они могут служить для описания абстрактных интерфейсов, таких как: + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String +``` +{% endtab %} +{% endtabs %} + +а также могут содержать конкретные реализации: + +{% tabs traits_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String + def showHtml = "

            " + show + "

            " +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String + def showHtml = "

            " + show + "

            " +``` +{% endtab %} +{% endtabs %} + +На примере видно, что метод `showHtml` определяется в терминах абстрактного метода `show`. + +[Odersky и Zenger][scalable] представляют _сервис-ориентированную компонентную модель_ и рассматривают: + +- **абстрактные члены** как _требуемые_ службы: их все еще необходимо реализовать в подклассе. +- **конкретные члены** как _предоставляемые_ услуги: они предоставляются подклассу. + +Это видно на примере со `Showable`: определяя класс `Document`, который расширяет `Showable`, +все еще нужно определить `show`, но `showHtml` уже предоставляется: + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Document(text: String) extends Showable { + def show = text +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Document(text: String) extends Showable: + def show = text +``` + +{% endtab %} +{% endtabs %} + +#### Абстрактные члены + +Абстрактными в `trait` могут оставаться не только методы. +`trait` может содержать: + +- абстрактные методы (`def m(): T`) +- абстрактные переменные (`val x: T`) +- абстрактные типы (`type T`), потенциально с ограничениями (`type T <: S`) +- абстрактные given (`given t: T`) только в Scala 3 + +Каждая из вышеперечисленных функций может быть использована для определения той или иной формы требований к реализатору `trait`. + +## Смешанная композиция + +Кроме того, что `trait`-ы могут содержать абстрактные и конкретные определения, +Scala также предоставляет мощный способ создания нескольких `trait`: +структура, которую часто называют _смешанной композицией_. + +Предположим, что существуют следующие два (потенциально независимо определенные) `trait`-а: + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait GreetingService { + def translate(text: String): String + def sayHello = translate("Hello") +} + +trait TranslationService { + def translate(text: String): String = "..." +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait GreetingService: + def translate(text: String): String + def sayHello = translate("Hello") + +trait TranslationService: + def translate(text: String): String = "..." +``` + +{% endtab %} +{% endtabs %} + +Чтобы скомпоновать два сервиса, можно просто создать новый `trait`, расширяющий их: + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait ComposedService extends GreetingService with TranslationService +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait ComposedService extends GreetingService, TranslationService +``` + +{% endtab %} +{% endtabs %} + +Абстрактные элементы в одном `trait`-е (например, `translate` в `GreetingService`) +автоматически сопоставляются с конкретными элементами в другом `trait`-е. +Это работает не только с методами, как в этом примере, но и со всеми другими абстрактными членами, +упомянутыми выше (то есть типами, переменными и т.д.). + +## Классы + +`trait`-ы отлично подходят для модуляции компонентов и описания интерфейсов (обязательных и предоставляемых). +Но в какой-то момент возникнет необходимость создавать их экземпляры. +При разработке программного обеспечения в Scala часто бывает полезно рассмотреть возможность +использования классов только на начальных этапах модели наследования: + +{% tabs table-traits-cls-summary class=tabs-scala-version %} +{% tab 'Scala 2' %} +| Трейты | `T1`, `T2`, `T3` +| Составные трейты | `S1 extends T1 with T2`, `S2 extends T2 with T3` +| Классы | `C extends S1 with T3` +| Экземпляры | `new C()` +{% endtab %} +{% tab 'Scala 3' %} +| Трейты | `T1`, `T2`, `T3` +| Составные трейты | `S1 extends T1, T2`, `S2 extends T2, T3` +| Классы | `C extends S1, T3` +| Экземпляры | `C()` +{% endtab %} +{% endtabs %} + +Это еще более актуально в Scala 3, где трейты теперь также могут принимать параметры конструктора, +что еще больше устраняет необходимость в классах. + +#### Определение класса + +Подобно `trait`-ам, классы могут расширять несколько `trait`-ов (но только один суперкласс): + +{% tabs class_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class MyService(name: String) extends ComposedService with Showable { + def show = s"$name says $sayHello" +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class MyService(name: String) extends ComposedService, Showable: + def show = s"$name says $sayHello" +``` + +{% endtab %} +{% endtabs %} + +#### Подтипы + +Экземпляр `MyService` создается следующим образом: + +{% tabs class_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1: MyService = new MyService("Service 1") +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s1: MyService = MyService("Service 1") +``` + +{% endtab %} +{% endtabs %} + +С помощью подтипов экземпляр `s1` можно использовать везде, где ожидается любое из расширенных свойств: + +{% tabs class_3 %} +{% tab 'Scala 2 и 3' %} + +```scala +val s2: GreetingService = s1 +val s3: TranslationService = s1 +val s4: Showable = s1 +// ... и так далее ... +``` +{% endtab %} +{% endtabs %} + +#### Планирование расширения + +Как упоминалось ранее, можно расширить еще один класс: + +{% tabs class_4 %} +{% tab 'Scala 2 и 3' %} + +```scala +class Person(name: String) +class SoftwareDeveloper(name: String, favoriteLang: String) + extends Person(name) +``` + +{% endtab %} +{% endtabs %} + +Однако, поскольку `trait`-ы разработаны как основное средство декомпозиции, +то не рекомендуется расширять класс, определенный в одном файле, из другого файла. + +
            Открытые классы только в Scala 3
            + +В Scala 3 расширение неабстрактных классов в других файлах ограничено. +Чтобы разрешить это, базовый класс должен быть помечен как `open`: + +{% tabs class_5 %} +{% tab 'Только в Scala 3' %} + +```scala +open class Person(name: String) +``` +{% endtab %} +{% endtabs %} + +Маркировка классов с помощью [`open`][open] - это новая функция Scala 3. +Необходимость явно помечать классы как открытые позволяет избежать многих распространенных ошибок в ООП. +В частности, это требует, чтобы разработчики библиотек явно планировали расширение +и, например, документировали классы, помеченные как открытые. + +## Экземпляры и приватное изменяемое состояние + +Как и в других языках с поддержкой ООП, трейты и классы в Scala могут определять изменяемые поля: + +{% tabs instance_6 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Counter { + // получить значение можно только с помощью метода `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Counter: + // получить значение можно только с помощью метода `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +``` + +{% endtab %} +{% endtabs %} + +Каждый экземпляр класса `Counter` имеет собственное приватное состояние, +которое можно получить только через метод `count`, как показано в следующем взаимодействии: + +{% tabs instance_7 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val c1 = new Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val c1 = Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% endtabs %} + +#### Модификаторы доступа + +По умолчанию все определения элементов в Scala общедоступны. +Чтобы скрыть детали реализации, можно определить элементы (методы, поля, типы и т.д.) в качестве `private` или `protected`. +Таким образом, вы можете управлять доступом к ним или их переопределением. +Закрытые (`private`) элементы видны только самому классу/трейту и его сопутствующему объекту. +Защищенные (`protected`) элементы также видны для подклассов класса. + +## Дополнительный пример: сервис-ориентированный дизайн + +Далее будут проиллюстрированы некоторые расширенные возможности Scala и показано, +как их можно использовать для структурирования более крупных программных компонентов. +Примеры взяты из статьи Мартина Одерски и Маттиаса Зенгера ["Scalable Component Abstractions"][scalable]. +Пример в первую очередь предназначен для демонстрации того, +как использовать несколько функций типа для создания более крупных компонентов. + +Цель состоит в том, чтобы определить программный компонент с семейством типов, +которые могут быть уточнены позже при реализации компонента. +Конкретно, следующий код определяет компонент `SubjectObserver` как `trait` с двумя членами абстрактного типа, +`S` (для субъектов) и `O` (для наблюдателей): + +{% tabs example_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait SubjectObserver { + + type S <: Subject + type O <: Observer + + trait Subject { self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = { + observers = obs :: observers + } + def publish() = { + for ( obs <- observers ) obs.notify(this) + } + } + + trait Observer { + def notify(sub: S): Unit + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait SubjectObserver: + + type S <: Subject + type O <: Observer + + trait Subject: + self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = + observers = obs :: observers + def publish() = + for obs <- observers do obs.notify(this) + + trait Observer: + def notify(sub: S): Unit +``` + +{% endtab %} +{% endtabs %} + +Есть несколько вещей, которые нуждаются в объяснении. + +#### Члены абстрактного типа + +Тип объявления `S <: Subject` говорит, что внутри trait `SubjectObserver` можно ссылаться на +некоторый _неизвестный_ (то есть абстрактный) тип, который называется `S`. +Однако этот тип не является полностью неизвестным: мы знаем, по крайней мере, что это какой-то подтип `Subject`. +Все trait-ы и классы, расширяющие `SubjectObserver`, могут свободно выбирать любой тип для `S`, +если выбранный тип является подтипом `Subject`. +Часть `<: Subject` декларации также упоминается как верхняя граница на `S`. + +#### Вложенные trait-ы + +_В рамках_ trait-а `SubjectObserver` определяются два других trait-а. +trait `Observer`, который определяет только один абстрактный метод `notify` с одним аргументом типа `S`. +Как будет видно, важно, чтобы аргумент имел тип `S`, а не тип `Subject`. + +Второй trait, `Subject`, определяет одно приватное поле `observers` для хранения всех наблюдателей, +подписавшихся на этот конкретный объект. Подписка на объект просто сохраняет объект в списке. +Опять же, тип параметра `obs` - это `O`, а не `Observer`. + +#### Аннотации собственного типа + +Наконец, что означает `self: S =>` в trait-е `Subject`? Это называется аннотацией собственного типа. +И требует, чтобы подтипы `Subject` также были подтипами `S`. +Это необходимо, чтобы иметь возможность вызывать `obs.notify` с `this` в качестве аргумента, +поскольку для этого требуется значение типа `S`. +Если бы `S` был конкретным типом, аннотацию собственного типа можно было бы заменить на `trait Subject extends S`. + +### Реализация компонента + +Теперь можно реализовать вышеуказанный компонент и определить члены абстрактного типа как конкретные типы: + +{% tabs example_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object SensorReader extends SubjectObserver { + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject { + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = { + currentValue = v + publish() + } + } + + class Display extends Observer { + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +object SensorReader extends SubjectObserver: + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject: + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = + currentValue = v + publish() + + class Display extends Observer: + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") +``` + +{% endtab %} +{% endtabs %} + +В частности, мы определяем _singleton_ `object SensorReader`, который расширяет `SubjectObserver`. +В реализации `SensorReader` говорится, что тип `S` теперь определяется как тип `Sensor`, +а тип `O` определяется как тип `Display`. +И `Sensor`, и `Display` определяются как вложенные классы в `SensorReader`, +реализующие trait-ы `Subject` и `Observer` соответственно. + +Помимо того, что этот код является примером сервис-ориентированного дизайна, +он также освещает многие аспекты объектно-ориентированного программирования: + +- Класс `Sensor` вводит свое собственное частное состояние (`currentValue`) + и инкапсулирует изменение состояния за методом `changeValue`. +- Реализация `changeValue` использует метод `publish`, определенный в родительском trait-е. +- Класс `Display` расширяет trait `Observer` и реализует отсутствующий метод `notify`. + +Важно отметить, что реализация `notify` может безопасно получить доступ только к `label` и значению `sub`, +поскольку мы изначально объявили параметр типа `S`. + +### Использование компонента + +Наконец, следующий код иллюстрирует, как использовать компонент `SensorReader`: + +{% tabs example_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import SensorReader._ + +// настройка сети +val s1 = new Sensor("sensor1") +val s2 = new Sensor("sensor2") +val d1 = new Display() +val d2 = new Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// распространение обновлений по сети +s1.changeValue(2) +s2.changeValue(3) + +// печатает: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 + +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import SensorReader.* + +// настройка сети +val s1 = Sensor("sensor1") +val s2 = Sensor("sensor2") +val d1 = Display() +val d2 = Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// распространение обновлений по сети +s1.changeValue(2) +s2.changeValue(3) + +// печатает: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 +``` + +{% endtab %} +{% endtabs %} + +Имея под рукой все утилиты объектно-ориентированного программирования, в следующем разделе будет продемонстрировано, +как разрабатывать программы в функциональном стиле. + +[scalable]: https://doi.org/10.1145/1094811.1094815 +[open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_ru/scala3/book/domain-modeling-tools.md b/_ru/scala3/book/domain-modeling-tools.md new file mode 100644 index 0000000000..ec35430443 --- /dev/null +++ b/_ru/scala3/book/domain-modeling-tools.md @@ -0,0 +1,1175 @@ +--- +layout: multipage-overview +title: Инструменты +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлено введение в доступные инструменты моделирования предметной области в Scala 3, включая классы, трейты, перечисления и многое другое. +language: ru +num: 21 +previous-page: domain-modeling-intro +next-page: domain-modeling-oop +--- + + +Scala предоставляет множество различных конструкций для моделирования предметной области: + +- Классы +- Объекты +- Сопутствующие объекты +- Трейты +- Абстрактные классы +- Перечисления только в Scala 3 +- Case классы +- Case объекты + +В этом разделе кратко представлена каждая из этих языковых конструкций. + + +## Классы + +Как и в других языках, _класс_ в Scala — это шаблон для создания экземпляров объекта. +Вот несколько примеров классов: + +{% tabs class_1 %} +{% tab 'Scala 2 и 3' %} + +```scala +class Person(var name: String, var vocation: String) +class Book(var title: String, var author: String, var year: Int) +class Movie(var name: String, var director: String, var year: Int) +``` + +{% endtab %} +{% endtabs %} + +Эти примеры показывают, что в Scala есть очень легкий способ объявления классов. + +Все параметры в примерах наших классов определены как `var` поля, а значит, они изменяемы: их можно читать, а также изменять. +Если вы хотите, чтобы они были неизменяемыми — только для чтения — создайте их как `val` поля или используйте case класс. + +До Scala 3 для создания нового экземпляра класса использовалось ключевое слово `new`: + +{% tabs class_2 %} +{% tab 'Scala 2 и 3' %} + +```scala +val p = new Person("Robert Allen Zimmerman", "Harmonica Player") +// --- +``` + +{% endtab %} +{% endtabs %} + +Однако с [универсальными apply методами][creator] в Scala 3 этого больше не требуется: только в Scala 3. + +{% tabs class_3 %} +{% tab 'Только в Scala 3' %} + +```scala +val p = Person("Robert Allen Zimmerman", "Harmonica Player") +``` + +{% endtab %} +{% endtabs %} + +Если у вас есть экземпляр класса, такой как `p`, то вы можете получить доступ к полям экземпляра, +которые в этом примере являются параметрами конструктора: + +{% tabs class_4 %} +{% tab 'Scala 2 и 3' %} + +```scala +p.name // "Robert Allen Zimmerman" +p.vocation // "Harmonica Player" +``` + +{% endtab %} +{% endtabs %} + +Как уже упоминалось, все эти параметры были созданы как `var` поля, поэтому они изменяемые: + +{% tabs class_5 %} +{% tab 'Scala 2 и 3' %} + +```scala +p.name = "Bob Dylan" +p.vocation = "Musician" +``` + +{% endtab %} +{% endtabs %} + +### Поля и методы + +Классы также могут содержать методы и дополнительные поля, не являющиеся частью конструкторов. +Они определены в теле класса. +Тело инициализируется как часть конструктора по умолчанию: + +{% tabs method class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person(var firstName: String, var lastName: String) { + + println("initialization begins") + val fullName = firstName + " " + lastName + + // метод класса + def printFullName: Unit = + // обращение к полю `fullName`, определенному выше + println(fullName) + + printFullName + println("initialization ends") +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Person(var firstName: String, var lastName: String): + + println("initialization begins") + val fullName = firstName + " " + lastName + + // метод класса + def printFullName: Unit = + // обращение к полю `fullName`, определенному выше + println(fullName) + + printFullName + println("initialization ends") +``` + +{% endtab %} +{% endtabs %} + +Следующая сессия REPL показывает, как создать новый экземпляр `Person` с этим классом: + +{% tabs demo-person class=tabs-scala-version %} +{% tab 'Scala 2' %} +````scala +scala> val john = new Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` +{% endtab %} +{% tab 'Scala 3' %} +````scala +scala> val john = Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` +{% endtab %} +{% endtabs %} + +Классы также могут расширять трейты и абстрактные классы, которые мы рассмотрим в специальных разделах ниже. + +### Значения параметров по умолчанию + +В качестве беглого взгляда на некоторые другие функции, +параметры конструктора класса также могут иметь значения по умолчанию: + +{% tabs default-values_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000) { + override def toString = s"timeout: $timeout, linger: $linger" +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000): + override def toString = s"timeout: $timeout, linger: $linger" +``` + +{% endtab %} +{% endtabs %} + +Отличительной особенностью этой функции является то, что она позволяет потребителям вашего кода +создавать классы различными способами, как если бы у класса были альтернативные конструкторы: + +{% tabs default-values_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s = new Socket() // timeout: 5000, linger: 5000 +val s = new Socket(2_500) // timeout: 2500, linger: 5000 +val s = new Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = new Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = new Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s = Socket() // timeout: 5000, linger: 5000 +val s = Socket(2_500) // timeout: 2500, linger: 5000 +val s = Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% endtabs %} + +При создании нового экземпляра класса вы также можете использовать именованные параметры. +Это особенно полезно, когда несколько параметров имеют одинаковый тип, как показано в этом сравнении: + +{% tabs default-values_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// пример 1 +val s = new Socket(10_000, 10_000) + +// пример 2 +val s = new Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// пример 1 +val s = Socket(10_000, 10_000) + +// пример 2 +val s = Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% endtabs %} + +### Вспомогательные конструкторы + +Вы можете определить класс с несколькими конструкторами, +чтобы клиенты вашего класса могли создавать его различными способами. +Например, предположим, что вам нужно написать код для моделирования студентов в системе приема в колледж. +При анализе требований вы увидели, что необходимо создавать экземпляр `Student` тремя способами: + +- С именем и государственным удостоверением личности, когда они впервые начинают процесс приема +- С именем, государственным удостоверением личности и дополнительной датой подачи заявки, когда они подают заявку +- С именем, государственным удостоверением личности и студенческим билетом после того, как они будут приняты + +Один из способов справиться с этой ситуацией в стиле ООП - с помощью нижеследующего кода: + +{% tabs structor_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import java.time._ + +// [1] основной конструктор +class Student( + var name: String, + var govtId: String +) { + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] конструктор для студента, подавшего заявку + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = { + this(name, govtId) + _applicationDate = Some(applicationDate) + } + + // [3] конструктор, когда учащийся принят и теперь имеет студенческий билет + def this( + name: String, + govtId: String, + studentId: Int + ) = { + this(name, govtId) + _studentId = studentId + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import java.time.* + +// [1] основной конструктор +class Student( + var name: String, + var govtId: String +): + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] конструктор для студента, подавшего заявку + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = + this(name, govtId) + _applicationDate = Some(applicationDate) + + // [3] конструктор, когда учащийся принят и теперь имеет студенческий билет + def this( + name: String, + govtId: String, + studentId: Int + ) = + this(name, govtId) + _studentId = studentId +``` + +{% endtab %} +{% endtabs %} + +Класс содержит три конструктора, обозначенных комментариями в коде: + +1. Первичный конструктор, заданный `name` и `govtId` в определении класса +2. Вспомогательный конструктор с параметрами `name`, `govtId` и `applicationDate` +3. Другой вспомогательный конструктор с параметрами `name`, `govtId` и `studentId` + +Эти конструкторы можно вызывать следующим образом: + +{% tabs structor_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1 = new Student("Mary", "123") +val s2 = new Student("Mary", "123", LocalDate.now) +val s3 = new Student("Mary", "123", 456) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +val s1 = Student("Mary", "123") +val s2 = Student("Mary", "123", LocalDate.now) +val s3 = Student("Mary", "123", 456) +``` + +{% endtab %} +{% endtabs %} + +Хотя этот метод можно использовать, имейте в виду, что параметры конструктора также могут иметь значения по умолчанию, +из-за чего создается впечатление, что класс содержит несколько конструкторов. +Это показано в предыдущем примере `Socket`. + +## Объекты + +Объект — это класс, который имеет ровно один экземпляр. +Инициализируется он лениво, тогда, когда на его элементы ссылаются, подобно `lazy val`. +Объекты в Scala позволяют группировать методы и поля в одном пространстве имен, аналогично тому, +как вы используете `static` члены в классе в Java, Javascript (ES6) или `@staticmethod` в Python. + +Объявление `object` аналогично объявлению `class`. +Вот пример объекта “строковые утилиты”, который содержит набор методов для работы со строками: + +{% tabs object_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object StringUtils { + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +object StringUtils: + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +``` + +{% endtab %} +{% endtabs %} + +Мы можем использовать объект следующим образом: + +{% tabs object_2 %} +{% tab 'Scala 2 и 3' %} + +```scala +StringUtils.truncate("Chuck Bartowski", 5) // "Chuck" +``` + +{% endtab %} +{% endtabs %} + +Импорт в Scala очень гибкий и позволяет импортировать _все_ члены объекта: + +{% tabs object_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import StringUtils._ +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import StringUtils.* +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} +{% endtabs %} + +или только _некоторые_: + +{% tabs object_4 %} +{% tab 'Scala 2 и 3' %} + +```scala +import StringUtils.{truncate, containsWhitespace} +truncate("Charles Carmichael", 7) // "Charles" +containsWhitespace("Captain Awesome") // true +isNullOrEmpty("Morgan Grimes") // Not found: isNullOrEmpty (error) +``` + +{% endtab %} +{% endtabs %} + +Объекты также могут содержать поля, доступ к которым также осуществляется как к статическим элементам: + +{% tabs object_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object MathConstants { + val PI = 3.14159 + val E = 2.71828 +} + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +object MathConstants: + val PI = 3.14159 + val E = 2.71828 + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} +{% endtabs %} + +## Сопутствующие объекты + +Объект `object`, имеющий то же имя, что и класс, и объявленный в том же файле, что и класс, +называется _"сопутствующим объектом"_. Точно так же соответствующий класс называется сопутствующим классом объекта. +Сопутствующие класс или объект могут получить доступ к закрытым членам своего “соседа”. + +Сопутствующие объекты используются для методов и значений, не относящихся к экземплярам сопутствующего класса. +Например, в следующем примере у класса `Circle` есть элемент с именем `area`, специфичный для каждого экземпляра, +а у его сопутствующего объекта есть метод с именем `calculateArea`, +который (а) не специфичен для экземпляра и (б) доступен для каждого экземпляра: + +{% tabs companion class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.math._ + +class Circle(val radius: Double) { + def area: Double = Circle.calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = new Circle(5.0) +circle1.area +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import scala.math.* + +class Circle(val radius: Double): + def area: Double = Circle.calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) + +val circle1 = Circle(5.0) +circle1.area +``` + +{% endtab %} +{% endtabs %} + +В этом примере метод `area`, доступный для каждого экземпляра `Circle`, +использует метод `calculateArea`, определенный в сопутствующем объекте. +Кроме того, поскольку `calculateArea` является приватным, к нему нельзя получить доступ с помощью другого кода, +но, как показано, его могут видеть экземпляры класса `Circle`. + +### Другие виды использования сопутствующих объектов + +Сопутствующие объекты могут использоваться для нескольких целей: + +- их можно использовать для группировки “статических” методов в пространстве имен, как в примере выше + - эти методы могут быть `public` или `private` + - если бы `calculateArea` был `public`, к нему можно было бы получить доступ из любого места как `Circle.calculateArea` +- они могут содержать методы `apply`, которые — благодаря некоторому синтаксическому сахару — + работают как фабричные методы для создания новых экземпляров +- они могут содержать методы `unapply`, которые используются для деконструкции объектов, например, с помощью сопоставления с шаблоном + +Вот краткий обзор того, как методы `apply` можно использовать в качестве фабричных методов для создания новых объектов: + +{% tabs companion-use class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person { + var name = "" + var age = 0 + override def toString = s"$name is $age years old" +} + +object Person { + // фабричный метод с одним аргументом + def apply(name: String): Person = { + var p = new Person + p.name = name + p + } + + // фабричный метод с двумя аргументами + def apply(name: String, age: Int): Person = { + var p = new Person + p.name = name + p.age = age + p + } +} + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +Метод `unapply` здесь не рассматривается, но описан в [Спецификации языка](https://scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns). + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Person: + var name = "" + var age = 0 + override def toString = s"$name is $age years old" + +object Person: + + // фабричный метод с одним аргументом + def apply(name: String): Person = + var p = new Person + p.name = name + p + + // фабричный метод с двумя аргументами + def apply(name: String, age: Int): Person = + var p = new Person + p.name = name + p.age = age + p + +end Person + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +Метод `unapply` здесь не рассматривается, но описан в [справочной документации]({{ site.scala3ref }}/changed-features/pattern-matching.html). + +{% endtab %} +{% endtabs %} + +## Трейты + +Если провести аналогию с Java, то Scala `trait` похож на интерфейс в Java 8+. +Trait-ы могут содержать: + +- абстрактные методы и поля +- конкретные методы и поля + +В базовом использовании `trait` может использоваться как интерфейс, определяющий только абстрактные члены, +которые будут реализованы другими классами: + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Employee { + def id: Int + def firstName: String + def lastName: String +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait Employee: + def id: Int + def firstName: String + def lastName: String +``` + +{% endtab %} +{% endtabs %} + +Однако трейты также могут содержать конкретные члены. +Например, следующий трейт определяет два абстрактных члена — `numLegs` и `walk()` — +а также имеет конкретную реализацию метода `stop()`: + +{% tabs traits_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasLegs { + def numLegs: Int + def walk(): Unit + def stop() = println("Stopped walking") +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait HasLegs: + def numLegs: Int + def walk(): Unit + def stop() = println("Stopped walking") +``` + +{% endtab %} +{% endtabs %} + +Вот еще один трейт с абстрактным членом и двумя конкретными реализациями: + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasTail { + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait HasTail: + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что каждый трейт обрабатывает только очень специфичные атрибуты и поведение: +`HasLegs` имеет дело только с "лапами", а `HasTail` имеет дело только с функциональностью, связанной с хвостом. +Трейты позволяют создавать такие небольшие модули. + +Позже в вашем коде классы могут смешивать несколько трейтов для создания более крупных компонентов: + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class IrishSetter(name: String) extends HasLegs with HasTail { + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class IrishSetter(name: String) extends HasLegs, HasTail: + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что класс `IrishSetter` реализует абстрактные члены, определенные в `HasLegs` и `HasTail`. +Теперь вы можете создавать новые экземпляры `IrishSetter`: + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val d = new IrishSetter("Big Red") // "Big Red is a Dog" +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val d = IrishSetter("Big Red") // "Big Red is a Dog" +``` + +{% endtab %} +{% endtabs %} + +Это всего лишь пример того, чего можно добиться с помощью trait-ов. +Дополнительные сведения см. в остальных уроках по моделированию. + +## Абстрактные классы + +Когда необходимо написать класс, но известно, что в нем будут абстрактные члены, можно создать либо `trait`, либо абстрактный класс. +В большинстве случаев желательно использовать `trait`, но исторически сложилось так, что было две ситуации, +когда предпочтительнее использование абстрактного класса: + +- необходимо создать базовый класс, который принимает аргументы конструктора +- код будет вызван из Java-кода + +### Базовый класс, который принимает аргументы конструктора + +До Scala 3, когда базовому классу нужно было принимать аргументы конструктора, он объявлялся как `abstract class`: + +{% tabs abstract_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +abstract class Pet(name: String) { + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" +} + +class Dog(name: String, var age: Int) extends Pet(name) { + val greeting = "Woof" +} + +val d = new Dog("Fido", 1) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +abstract class Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, var age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +

            Параметры в trait только в Scala 3

            + +Однако в Scala 3 трейты теперь могут иметь [параметры][trait-params], +так что теперь вы можете использовать трейты в той же ситуации: + +{% tabs abstract_2 %} + +{% tab 'Только в Scala 3' %} + +```scala +trait Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, var age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +Trait-ы более гибки в составлении, потому что можно смешивать (наследовать) несколько trait-ов, но только один класс. +В большинстве случаев trait-ы следует предпочитать классам и абстрактным классам. +Правило выбора состоит в том, чтобы использовать классы всякий раз, когда необходимо создавать экземпляры определенного типа, +и trait-ы, когда желательно разложить и повторно использовать поведение. + +

            Перечисления только в Scala 3

            + +Перечисление (_an enumeration_) может быть использовано для определения типа, +состоящего из конечного набора именованных значений (в разделе, посвященном [моделированию ФП][fp-modeling], +будут показаны дополнительные возможности перечислений). +Базовые перечисления используются для определения наборов констант, +таких как месяцы в году, дни в неделе, направления, такие как север/юг/восток/запад, и многое другое. + +В качестве примера, рассмотрим перечисления, определяющие наборы атрибутов, связанных с пиццами: + +{% tabs enum_1 %} +{% tab 'Только в Scala 3' %} + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +Для использования в коде в первую очередь перечисление нужно импортировать, а затем - использовать: + +{% tabs enum_2 %} +{% tab 'Только в Scala 3' %} + +```scala +import CrustSize.* +val currentCrustSize = Small +``` + +{% endtab %} +{% endtabs %} + +Значения перечислений можно сравнивать (`==`) и использовать в сопоставлении: + +{% tabs enum_3 %} +{% tab 'Только в Scala 3' %} + +```scala +// if/then +if currentCrustSize == Large then + println("You get a prize!") + +// match +currentCrustSize match + case Small => println("small") + case Medium => println("medium") + case Large => println("large") +``` + +{% endtab %} +{% endtabs %} + +### Дополнительные функции перечисления + +Перечисления также могут быть параметризованы: + +{% tabs enum_4 %} +{% tab 'Только в Scala 3' %} + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` + +{% endtab %} +{% endtabs %} + +И они также могут содержать элементы (например, поля и методы): + +{% tabs enum_5 %} +{% tab 'Только в Scala 3' %} + +```scala +enum Planet(mass: Double, radius: Double): + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = + otherMass * surfaceGravity + + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Earth extends Planet(5.976e+24, 6.37814e6) + // далее идут остальные планеты ... +``` + +{% endtab %} +{% endtabs %} + +### Совместимость с перечислениями Java + +Если вы хотите использовать перечисления, определенные в Scala, как перечисления Java, +то можете сделать это, расширив класс `java.lang.Enum` (импортированный по умолчанию) следующим образом: + +{% tabs enum_6 %} +{% tab 'Только в Scala 3' %} + +```scala +enum Color extends Enum[Color] { case Red, Green, Blue } +``` + +{% endtab %} +{% endtabs %} + +Параметр типа берется из определения Java `enum` и должен совпадать с типом перечисления. +Нет необходимости предоставлять аргументы конструктора (как определено в документации Java API) для `java.lang.Enum` +при его расширении — компилятор генерирует их автоматически. + +После такого определения `Color` вы можете использовать его так же, как перечисление Java: + +```` +scala> Color.Red.compareTo(Color.Green) +val res0: Int = -1 +```` + +В разделе об [алгебраических типах данных][adts] и [справочной документации][ref-enums] перечисления рассматриваются более подробно. + +## Case class-ы + +Case class используются для моделирования неизменяемых структур данных. +Возьмем следующий пример: + +{% tabs case-classes_1 %} +{% tab 'Scala 2 и 3' %} + +```scala: +case class Person(name: String, relation: String) +``` + +{% endtab %} +{% endtabs %} + +Поскольку мы объявляем `Person` как `case class`, поля `name` и `relation` по умолчанию общедоступны и неизменяемы. +Мы можем создавать экземпляры case классов следующим образом: + +{% tabs case-classes_2 %} +{% tab 'Scala 2 и 3' %} + +```scala +val christina = Person("Christina", "niece") +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что поля не могут быть изменены: + +{% tabs case-classes_3 %} +{% tab 'Scala 2 и 3' %} + +```scala +christina.name = "Fred" // ошибка: reassignment to val +``` + +{% endtab %} +{% endtabs %} + +Поскольку предполагается, что поля case класса неизменяемы, +компилятор Scala может сгенерировать для вас множество полезных методов: + +- Генерируется метод `unapply`, позволяющий выполнять сопоставление с образцом case класса (то есть `case Person(n, r) => ...`). +- В классе генерируется метод `copy`, полезный для создания модифицированных копий экземпляра. +- Генерируются методы `equals` и `hashCode`, использующие структурное равенство, + что позволяет использовать экземпляры case классов в `Map`-ах. +- Генерируется дефолтный метод `toString`, полезный для отладки. + +Эти дополнительные функции показаны в следующем примере: + +{% tabs case-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// Case class-ы можно использовать в качестве шаблонов +christina match { + case Person(n, r) => println("name is " + n) +} + +// для вас генерируются методы `equals` и `hashCode` +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// метод `toString` +println(christina) // Person(Christina,niece) + +// встроенный метод `copy` +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// в результате: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) + +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +// Case class-ы можно использовать в качестве шаблонов +christina match + case Person(n, r) => println("name is " + n) + +// для вас генерируются методы `equals` и `hashCode` +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// метод `toString` +println(christina) // Person(Christina,niece) + +// встроенный метод `copy` +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// в результате: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) +``` + +{% endtab %} +{% endtabs %} + +### Поддержка функционального программирования + +Как уже упоминалось ранее, case class-ы поддерживают функциональное программирование (ФП): + +- ФП избегает изменения структур данных. + Поэтому поля конструктора по умолчанию имеют значение `val`. + Поскольку экземпляры case class не могут быть изменены, ими можно легко делиться, не опасаясь мутаций или условий гонки. +- вместо изменения экземпляра можно использовать метод `copy` в качестве шаблона для создания нового (потенциально измененного) экземпляра. + Этот процесс можно назвать “обновлением по мере копирования”. +- наличие автоматически сгенерированного метода `unapply` позволяет использовать case class в сопоставлении шаблонов. + +## Case object-ы + +Case object-ы относятся к объектам так же, как case class-ы относятся к классам: +они предоставляют ряд автоматически генерируемых методов, чтобы сделать их более мощными. +Case object-ы особенно полезны тогда, когда необходим одноэлементный объект, +который нуждается в небольшой дополнительной функциональности, +например, для использования с сопоставлением шаблонов в выражениях `match`. + +Case object-ы полезны, когда необходимо передавать неизменяемые сообщения. +Например, представим проект музыкального проигрывателя, и создадим набор команд или сообщений: + +{% tabs case-objects_1 %} +{% tab 'Scala 2 и 3' %} + +```scala +sealed trait Message +case class PlaySong(name: String) extends Message +case class IncreaseVolume(amount: Int) extends Message +case class DecreaseVolume(amount: Int) extends Message +case object StopPlaying extends Message +``` + +{% endtab %} +{% endtabs %} + +Затем в других частях кода можно написать методы, которые используют сопоставление с образцом +для обработки входящего сообщения +(при условии, что методы `playSong`, `changeVolume` и `stopPlayingSong` определены где-то еще): + +{% tabs case-objects_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def handleMessages(message: Message): Unit = message match { + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +def handleMessages(message: Message): Unit = message match + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +``` + +{% endtab %} +{% endtabs %} + +[ref-enums]: {{ site.scala3ref }}/enums/enums.html +[adts]: {% link _overviews/scala3-book/types-adts-gadts.md %} +[fp-modeling]: {% link _overviews/scala3-book/domain-modeling-fp.md %} +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[unapply]: {{ site.scala3ref }}/changed-features/pattern-matching.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_ru/scala3/book/first-look-at-types.md b/_ru/scala3/book/first-look-at-types.md new file mode 100644 index 0000000000..5873df07f7 --- /dev/null +++ b/_ru/scala3/book/first-look-at-types.md @@ -0,0 +1,354 @@ +--- +layout: multipage-overview +title: Первый взгляд на типы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице представлено краткое введение во встроенные типы данных Scala, включая Int, Double, String, Long, Any, AnyRef, Nothing и Null. +language: ru +num: 17 +previous-page: taste-summary +next-page: string-interpolation +--- + +## Все значения имеют тип + +В Scala все значения имеют тип, включая числовые значения и функции. +На приведенной ниже диаграмме показано подмножество иерархии типов. + +Scala 3 Type Hierarchy + +## Иерархия типов Scala + +`Any` - это супертип всех типов, также называемый **верхним типом** (**the top type**). +Он определяет универсальные методы, такие как `equals`, `hashCode` и `toString`. + +У верхнего типа `Any` есть подтип [`Matchable`][matchable], который используется для обозначения всех типов, +для которых возможно выполнить pattern matching (сопоставление с образцом). +Важно гарантировать вызов свойства _“параметричность”_, что вкратце означает, +что мы не можем сопоставлять шаблоны для значений типа `Any`, а только для значений, которые являются подтипом `Matchable`. +[Справочная документация][matchable] содержит более подробную информацию о `Matchable`. + +`Matchable` содержит два важных подтипа: `AnyVal` и `AnyRef`. + +_`AnyVal`_ представляет типы значений. +Существует несколько предопределенных типов значений, и они non-nullable: +`Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit` и `Boolean`. +`Unit` - это тип значения, который не несет никакой значимой информации. Существует ровно один экземпляр `Unit` - `()`. + +_`AnyRef`_ представляет ссылочные типы. Все типы, не являющиеся значениями, определяются как ссылочные типы. +Каждый пользовательский тип в Scala является подтипом `AnyRef`. +Если Scala используется в контексте среды выполнения Java, `AnyRef` соответствует `java.lang.Object`. + +В языках, основанных на операторах, `void` используется для методов, которые ничего не возвращают. +В Scala для методов, которые не имеют возвращаемого значения, +такие как следующий метод, для той же цели используется `Unit`: + +{% tabs unit %} +{% tab 'Scala 2 и 3' for=unit %} + +```scala +def printIt(a: Any): Unit = println(a) +``` + +{% endtab %} +{% endtabs %} + +Вот пример, демонстрирующий, что строки, целые числа, символы, логические значения и функции являются экземплярами `Any` +и могут обрабатываться так же, как и любой другой объект: + +{% tabs any %} +{% tab 'Scala 2 и 3' for=any %} + +```scala +val list: List[Any] = List( + "a string", + 732, // число + 'c', // буква + '\'', // Экранированный символ + true, // булево значение + () => "an anonymous function returning a string" +) + +list.foreach(element => println(element)) +``` + +{% endtab %} +{% endtabs %} + +Код определяет список значений типа `List[Any]`. +Список инициализируется элементами различных типов, но каждый из них является экземпляром `scala.Any`, +поэтому мы можем добавить их в список. + +Вот вывод программы: + +``` +a string +732 +c +' +true + +``` + +## Типы значений в Scala + +Как показано выше, числовые типы Scala расширяют `AnyVal`, и все они являются полноценными объектами. +В этих примерах показано, как объявлять переменные этих числовых типов: + +{% tabs anyval %} +{% tab 'Scala 2 и 3' for=anyval %} + +```scala +val b: Byte = 1 +val i: Int = 1 +val l: Long = 1 +val s: Short = 1 +val d: Double = 2.0 +val f: Float = 3.0 +``` + +{% endtab %} +{% endtabs %} + +В первых четырех примерах, если явно не указать тип, то тип числа `1` по умолчанию будет равен `Int`, +поэтому, если нужен один из других типов данных — `Byte`, `Long` или `Short` — необходимо явно объявить эти типы. +Числа с десятичной дробью (например, `2.0`) по умолчанию будут иметь тип `Double`, +поэтому, если необходим `Float`, нужно объявить `Float` явно, как показано в последнем примере. + +Поскольку `Int` и `Double` являются числовыми типами по умолчанию, их можно создавать без явного объявления типа данных: + +{% tabs anynum %} +{% tab 'Scala 2 и 3' for=anynum %} + +```scala +val i = 123 // по умолчанию Int +val x = 1.0 // по умолчанию Double +``` + +{% endtab %} +{% endtabs %} + +Также можно добавить символы `L`, `D`, and `F` (или их эквивалент в нижнем регистре) +для того, чтобы задать `Long`, `Double` или `Float` значения: + +{% tabs type-post %} +{% tab 'Scala 2 и 3' for=type-post %} + +```scala +val x = 1_000L // val x: Long = 1000 +val y = 2.2D // val y: Double = 2.2 +val z = -3.3F // val z: Float = -3.3 +``` + +Вы также можете использовать шестнадцатеричное представление для форматирования целых чисел +(обычно это `Int`, но также поддерживается суффикс `L` для указания `Long`): + +```scala +val a = 0xACE // val a: Int = 2766 +val b = 0xfd_3aL // val b: Long = 64826 +``` + +Scala поддерживает множество различных способов форматирования одного и того же числа с плавающей запятой, +например: + +```scala +val q = .25 // val q: Double = 0.25 +val r = 2.5e-1 // val r: Double = 0.25 +val s = .0025e2F // val s: Float = 0.25 +``` + +{% endtab %} +{% endtabs %} + +В Scala также есть типы `String` и `Char`, которые обычно можно объявить в неявной форме: + +{% tabs type-string %} +{% tab 'Scala 2 и 3' for=type-string %} + +```scala +val s = "Bill" +val c = 'a' +``` + +{% endtab %} +{% endtabs %} + +Как показано, заключайте строки в двойные кавычки или тройные кавычки для многострочных строк, +а одиночный символ заключайте в одинарные кавычки. + +Типы данных и их диапазоны: + +| Тип данных | Возможные значения | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Boolean | `true` или `false` | +| Byte | 8-битное целое число в дополнении до двух со знаком (от -2^7 до 2^7-1 включительно)
            от -128 до 127 | +| Short | 16-битное целое число в дополнении до двух со знаком (от -2^15 до 2^15-1 включительно)
            от -32 768 до 32 767 | +| Int | 32-битное целое число с дополнением до двух со знаком (от -2^31 до 2^31-1 включительно)
            от -2 147 483 648 до 2 147 483 647 | +| Long | 64-битное целое число с дополнением до двух со знаком (от -2^63 до 2^63-1 включительно)
            (от -2^63 до 2^63-1 включительно) | +| Float | 32-разрядный IEEE 754 одинарной точности с плавающей точкой
            от 1,40129846432481707e-45 до 3,40282346638528860e+38 | +| Double | 64-битный IEEE 754 двойной точности с плавающей запятой
            от 4,94065645841246544e-324 до 1,79769313486231570e+308 | +| Char | 16-битный символ Unicode без знака (от 0 до 2^16-1 включительно)
            от 0 до 65 535 | +| String | последовательность `Char` | + +## Строки + +Строки Scala похожи на строки Java, +хотя в отличие от Java (по крайней мере, до Java 15) +в Scala легко создавать многострочные строки с тройными кавычками: + +{% tabs string-mlines1 %} +{% tab 'Scala 2 и 3' for=string-mlines1 %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` + +{% endtab %} +{% endtabs %} + +Одним из недостатков этого базового подхода является то, +что строки после первой строки содержат отступ и выглядят следующим образом: + +{% tabs string-mlines2 %} +{% tab 'Scala 2 и 3' for=string-mlines2 %} + +```scala +"The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +Если важно исключить отступ, можно поставить символ `|` перед всеми строками после первой +и вызвать метод `stripMargin` после строки: + +{% tabs string-mlines3 %} +{% tab 'Scala 2 и 3' for=string-mlines3 %} + +```scala +val quote = """The essence of Scala: + |Fusion of functional and object-oriented + |programming in a typed setting.""".stripMargin +``` + +{% endtab %} +{% endtabs %} + +Теперь все строки выравниваются по левому краю: + +{% tabs string-mlines4 %} +{% tab 'Scala 2 и 3' for=string-mlines4 %} + +```scala +"The essence of Scala: +Fusion of functional and object-oriented +programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +Строки Scala также поддерживают мощные методы интерполяции строк, +о которых мы поговорим [в следующей главе][string-interpolation]. + +## `BigInt` и `BigDecimal` + +Для действительно больших чисел можно использовать типы `BigInt` и `BigDecimal`: + +{% tabs type-bigint %} +{% tab 'Scala 2 и 3' for=type-bigint %} + +```scala +val a = BigInt(1_234_567_890_987_654_321L) +val b = BigDecimal(123456.789) +``` + +{% endtab %} +{% endtabs %} + +Где `Double` и `Float` являются приблизительными десятичными числами, +а `BigDecimal` используется для точной арифметики, например, при работе с валютой. + +`BigInt` и `BigDecimal` поддерживают все привычные числовые операторы: + +{% tabs type-bigint2 %} +{% tab 'Scala 2 и 3' for=type-bigint2 %} + +```scala +val b = BigInt(1234567890) // scala.math.BigInt = 1234567890 +val c = b + b // scala.math.BigInt = 2469135780 +val d = b * b // scala.math.BigInt = 1524157875019052100 +``` + +{% endtab %} +{% endtabs %} + +## Приведение типов + +Типы значений могут быть приведены следующим образом: + +Scala Type Hierarchy + +Например: + +{% tabs cast1 %} +{% tab 'Scala 2 и 3' for=cast1 %} + +```scala +val b: Byte = 127 +val i: Int = b // 127 + +val face: Char = '☺' +val number: Int = face // 9786 +``` + +{% endtab %} +{% endtabs %} + +Вы можете привести к типу, только если нет потери информации. +В противном случае вам нужно четко указать приведение типов: + +{% tabs cast2 %} +{% tab 'Scala 2 и 3' for=cast2 %} + +```scala +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 (обратите внимание, что требуется `.toFloat`, потому что приведение приводит к потере точности) +val z: Long = y // Ошибка +``` + +{% endtab %} +{% endtabs %} + +Вы также можете привести ссылочный тип к подтипу. +Это будет рассмотрено в книге позже. + +## `Nothing` и `null` + +`Nothing` является подтипом всех типов, также называемым **нижним типом** (**the bottom type**). +Нет значения, которое имело бы тип `Nothing`. +Он обычно сигнализирует о прекращении, таком как thrown exception, выходе из программы или бесконечном цикле - +т.е. это тип выражения, который не вычисляется до определенного значения, или метод, который нормально не возвращается. + +`Null` - это подтип всех ссылочных типов (т.е. любой подтип `AnyRef`). +Он имеет единственное значение, определяемое ключевым словом `null`. +В настоящее время применение `null` считается плохой практикой. +Его следует использовать в основном для взаимодействия с другими языками JVM. +Опция компилятора `opt-in` изменяет статус `Null`, делая все ссылочные типы non-nullable. +Этот параметр может [стать значением по умолчанию][safe-null] в будущей версии Scala. + +В то же время `null` почти никогда не следует использовать в коде Scala. +Альтернативы `null` обсуждаются в главе о [функциональном программировании][fp] и в [документации API][option-api]. + +[reference]: {{ site.scala3ref }}/overview.html +[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html +[fp]: {% link _overviews/scala3-book/fp-intro.md %} +[string-interpolation]: {% link _overviews/scala3-book/string-interpolation.md %} +[option-api]: https://scala-lang.org/api/3.x/scala/Option.html +[safe-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html diff --git a/_ru/scala3/book/fp-functional-error-handling.md b/_ru/scala3/book/fp-functional-error-handling.md new file mode 100644 index 0000000000..ca3f7857eb --- /dev/null +++ b/_ru/scala3/book/fp-functional-error-handling.md @@ -0,0 +1,436 @@ +--- +layout: multipage-overview +title: Функциональная обработка ошибок +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлено введение в функциональную обработку ошибок в Scala 3. +language: ru +num: 46 +previous-page: fp-functions-are-values +next-page: fp-summary +--- + + + +Функциональное программирование похоже на написание ряда алгебраических уравнений, +и поскольку алгебра не имеет null значений или исключений, они не используются и в ФП. +Что поднимает интересный вопрос: как быть в ситуациях, в которых вы обычно используете null значение или исключение программируя в ООП стиле? + +Решение Scala заключается в использовании конструкций, основанных на классах типа `Option`/`Some`/`None`. +Этот урок представляет собой введение в использование такого подхода. + +Примечание: + +- классы `Some` и `None` являются подклассами `Option` +- вместо того чтобы многократно повторять “`Option`/`Some`/`None`”, + следующий текст обычно просто ссылается на “`Option`” или на “классы `Option`” + + +## Первый пример + +Хотя этот первый пример не имеет дело с `null` значениями, это хороший способ познакомиться с классами `Option`. + +Представим, что нужно написать метод, который упрощает преобразование строк в целочисленные значения. +И нужен элегантный способ обработки исключения, которое возникает, +когда метод получает строку типа `"Hello"` вместо `"1"`. +Первое предположение о таком методе может выглядеть следующим образом: + +{% tabs fp-java-try class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +def makeInt(s: String): Int = + try { + Integer.parseInt(s.trim) + } catch { + case e: Exception => 0 + } +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def makeInt(s: String): Int = + try + Integer.parseInt(s.trim) + catch + case e: Exception => 0 +``` +{% endtab %} + +{% endtabs %} + +Если преобразование работает, метод возвращает правильное значение `Int`, но в случае сбоя метод возвращает `0`. +Для некоторых целей это может быть хорошо, но не совсем точно. +Например, метод мог получить `"0"`, но мог также получить `"foo"`, `"bar"` +или бесконечное количество других строк, которые выдадут исключение. +Это реальная проблема: как определить, когда метод действительно получил `"0"`, а когда получил что-то еще? +При таком подходе нет способа узнать правильный ответ наверняка. + + +## Использование Option/Some/None + +Распространенным решением этой проблемы в Scala является использование классов, +известных как `Option`, `Some` и `None`. +Классы `Some` и `None` являются подклассами `Option`, поэтому решение работает следующим образом: + +- объявляется, что `makeInt` возвращает тип `Option` +- если `makeInt` получает строку, которую он _может_ преобразовать в `Int`, ответ помещается внутрь `Some` +- если `makeInt` получает строку, которую _не может_ преобразовать, то возвращает `None` + +Вот доработанная версия `makeInt`: + +{% tabs fp--try-option class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +def makeInt(s: String): Option[Int] = + try { + Some(Integer.parseInt(s.trim)) + } catch { + case e: Exception => None + } +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def makeInt(s: String): Option[Int] = + try + Some(Integer.parseInt(s.trim)) + catch + case e: Exception => None +``` +{% endtab %} + +{% endtabs %} + +Этот код можно прочитать следующим образом: +“Когда данная строка преобразуется в целое число, верните значение `Int`, заключенное в `Some`, например `Some(1)`. +Когда строка не может быть преобразована в целое число и генерируется исключение, метод возвращает значение `None`.” + +Эти примеры показывают, как работает `makeInt`: + +{% tabs fp-try-option-example %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = makeInt("1") // Some(1) +val b = makeInt("one") // None +``` +{% endtab %} + +{% endtabs %} + +Как показано, строка `"1"` приводится к `Some(1)`, а строка `"one"` - к `None`. +В этом суть альтернативного подхода к обработке ошибок. +Данная техника используется для того, чтобы методы могли возвращать _значения_ вместо _исключений_. +В других ситуациях значения `Option` также используются для замены `null` значений. + +Примечание: + +- этот подход используется во всех классах библиотеки Scala, а также в сторонних библиотеках Scala. +- ключевым моментом примера является то, что функциональные методы не генерируют исключения; + вместо этого они возвращают такие значения, как `Option`. + + +## Потребитель makeInt + +Теперь представим, что мы являемся потребителем метода `makeInt`. +Известно, что он возвращает подкласс `Option[Int]`, поэтому возникает вопрос: +как работать с такими возвращаемыми типами? + +Есть два распространенных ответа, в зависимости от потребностей: + +- использование `match` выражений +- использование `for` выражений + +## Использование `match` выражений + +Одним из возможных решений является использование выражения `match`: + +{% tabs fp-option-match class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +makeInt(x) match { + case Some(i) => println(i) + case None => println("That didn’t work.") +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +makeInt(x) match + case Some(i) => println(i) + case None => println("That didn’t work.") +``` +{% endtab %} + +{% endtabs %} + +В этом примере, если `x` можно преобразовать в `Int`, вычисляется первый вариант в правой части предложения `case`; +если `x` не может быть преобразован в `Int`, вычисляется второй вариант в правой части предложения `case`. + + +## Использование `for` выражений + +Другим распространенным решением является использование выражения `for`, то есть комбинации `for`/`yield`. +Например, представим, что необходимо преобразовать три строки в целочисленные значения, а затем сложить их. +Решение задачи с использованием выражения `for`: + +{% tabs fp-for-comprehension class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val y = for { + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +} yield { + a + b + c +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val y = for + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +yield + a + b + c +``` +{% endtab %} + +{% endtabs %} + +После выполнения этого выражения `y` может принять одно из двух значений: + +- если _все_ три строки конвертируются в значения `Int`, `y` будет равно `Some[Int]`, т.е. целым числом, обернутым внутри `Some` +- если _какая-либо_ из трех строк не может быть преобразована в `Int`, `y` равен `None` + +Это можно проверить на примере: + +{% tabs fp-for-comprehension-evaluation class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val stringA = "1" +val stringB = "2" +val stringC = "3" + +val y = for { + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +} yield { + a + b + c +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val stringA = "1" +val stringB = "2" +val stringC = "3" + +val y = for + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +yield + a + b + c +``` +{% endtab %} + +{% endtabs %} + +С этими демонстрационными данными переменная `y` примет значение `Some(6)`. + +Чтобы увидеть негативный кейс, достаточно изменить любую из строк на что-то, что нельзя преобразовать в целое число. +В этом случае `y` равно `None`: + +{% tabs fp-for-comprehension-failure-result %} + +{% tab 'Scala 2 и 3' %} +```scala +y: Option[Int] = None +``` +{% endtab %} + +{% endtabs %} + + +## Восприятие Option, как контейнера + +Для лучшего восприятия `Option`, его можно представить как _контейнер_: + +- `Some` представляет собой контейнер с одним элементом +- `None` не является контейнером, в нем ничего нет + +Если предпочтительнее думать об `Option` как о ящике, то `None` подобен пустому ящику. +Что-то в нём могло быть, но нет. + + +## Использование `Option` для замены `null` + +Возвращаясь к значениям `null`, место, где `null` значение может незаметно проникнуть в код, — класс, подобный этому: + +{% tabs fp=case-class-nulls %} + +{% tab 'Scala 2 и 3' %} +```scala +class Address( + var street1: String, + var street2: String, + var city: String, + var state: String, + var zip: String +) +``` +{% endtab %} + +{% endtabs %} + +Хотя каждый адрес имеет значение `street1`, значение `street2` не является обязательным. +В результате полю `street2` можно присвоить значение `null`: + +{% tabs fp-case-class-nulls-example class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val santa = new Address( + "1 Main Street", + null, // <-- О! Значение null! + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val santa = Address( + "1 Main Street", + null, // <-- О! Значение null! + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} + +{% endtabs %} + +Исторически сложилось так, что в этой ситуации разработчики использовали пустые строки и значения `null`, +оба варианта это “костыль” для решения основной проблемы: `street2` - _необязательное_ поле. +В Scala и других современных языках правильное решение состоит в том, +чтобы заранее объявить, что `street2` является необязательным: + + +{% tabs fp-case-class-with-options %} + +{% tab 'Scala 2 и 3' %} +```scala +class Address( + var street1: String, + var street2: Option[String], // необязательное значение + var city: String, + var state: String, + var zip: String +) +``` +{% endtab %} + +{% endtabs %} + +Теперь можно написать более точный код: + +{% tabs fp-case-class-with-options-example-none class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val santa = new Address( + "1 Main Street", + None, // 'street2' не имеет значения + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val santa = Address( + "1 Main Street", + None, // 'street2' не имеет значения + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} + +{% endtabs %} + +или так: + +{% tabs fp-case-class-with-options-example-some class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val santa = new Address( + "123 Main Street", + Some("Apt. 2B"), + "Talkeetna", + "Alaska", + "99676" +) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val santa = Address( + "123 Main Street", + Some("Apt. 2B"), + "Talkeetna", + "Alaska", + "99676" +) +``` +{% endtab %} + +{% endtabs %} + + + +## `Option` — не единственное решение + +В этом разделе основное внимание уделялось `Option` классам, но у Scala есть несколько других альтернатив. + +Например, три класса, известные как `Try`/`Success`/`Failure`, работают также, +но (а) эти классы в основном используются, когда код может генерировать исключения, +и (б) когда желательно использовать класс `Failure`, потому что он дает доступ к сообщению об исключении. +Например, классы `Try` обычно используются при написании методов, которые взаимодействуют с файлами, +базами данных или интернет-службами, поскольку эти функции могут легко создавать исключения. + + +## Краткое ревью + +Этот раздел был довольно большим, поэтому давайте подведем краткое ревью: + +- функциональные программисты не используют `null` значения +- основной заменой `null` значениям является использование классов `Option` +- функциональные методы не выдают исключений; вместо этого они возвращают такие значения, как `Option`, `Try` или `Either` +- распространенными способами работы со значениями `Option` являются выражения `match` и `for` +- `Option` можно рассматривать как контейнеры с одним элементом (`Some`) и без элементов (`None`) +- `Option` также можно использовать для необязательных параметров конструктора или метода diff --git a/_ru/scala3/book/fp-functions-are-values.md b/_ru/scala3/book/fp-functions-are-values.md new file mode 100644 index 0000000000..9a6cd6c423 --- /dev/null +++ b/_ru/scala3/book/fp-functions-are-values.md @@ -0,0 +1,161 @@ +--- +layout: multipage-overview +title: Функции — это значения +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе рассматривается использование функций в качестве значений в функциональном программировании. +language: ru +num: 45 +previous-page: fp-pure-functions +next-page: fp-functional-error-handling +--- + + +Хотя каждый когда-либо созданный язык программирования, вероятно, позволяет писать чистые функции, +вторая важная особенность ФП на Scala заключается в том, что _функции можно создавать как значения_, +точно так же, как создаются значения `String` и `Int`. + +Эта особенность даёт много преимуществ, опишем наиболее распространенные из них: +(a) можно определять методы, принимающие в качестве параметров функции +и (b) можно передавать функции в качестве параметров в методы. + +Такой подход можно было наблюдать в предыдущих главах, когда демонстрировались такие методы, как `map` и `filter`: + +{% tabs fp-function-as-values-anonymous %} + +{% tab 'Scala 2 и 3' %} +```scala +val nums = (1 to 10).toList + +val doubles = nums.map(_ * 2) // удваивает каждое значение +val lessThanFive = nums.filter(_ < 5) // List(1,2,3,4) +``` +{% endtab %} + +{% endtabs %} + +В этих примерах анонимные функции передаются в `map` и `filter`. + +> Анонимные функции также известны как _лямбды_ (_lambdas_). + +Помимо передачи анонимных функций в `filter` и `map`, в них также можно передать _методы_: + +{% tabs fp-function-as-values-defined %} + +{% tab 'Scala 2 и 3' %} +```scala +// два метода +def double(i: Int): Int = i * 2 +def underFive(i: Int): Boolean = i < 5 + +// передача этих методов в filter и map +val doubles = nums.filter(underFive).map(double) +``` +{% endtab %} + +{% endtabs %} + +Возможность обращаться с методами и функциями как со значениями — мощное свойство, +предоставляемое языками функционального программирования. + +> Технически функция, которая принимает другую функцию в качестве входного параметра, известна как _функция высшего порядка_. +> (Если вам нравится юмор, как кто-то однажды написал, это все равно, что сказать, +> что класс, который принимает экземпляр другого класса в качестве параметра конструктора, +> является классом высшего порядка.) + + +## Функции, анонимные функции и методы + +В примерах выше анонимная функция это: + +{% tabs fp-anonymous-function-short %} + +{% tab 'Scala 2 и 3' %} +```scala +_ * 2 +``` +{% endtab %} + +{% endtabs %} + +Как было показано в обсуждении [функций высшего порядка][hofs], `_ * 2` - сокращенная версия синтаксиса: + +{% tabs fp-anonymous-function-full %} + +{% tab 'Scala 2 и 3' %} +```scala +(i: Int) => i * 2 +``` +{% endtab %} + +{% endtabs %} + +Такие функции называются “анонимными”, потому что им не присваивается определенное имя. +Для того чтобы это имя задать, достаточно просто присвоить его переменной: + +{% tabs fp-function-assignement %} + +{% tab 'Scala 2 и 3' %} +```scala +val double = (i: Int) => i * 2 +``` +{% endtab %} + +{% endtabs %} + +Теперь появилась именованная функция, назначенная переменной `double`. +Можно использовать эту функцию так же, как используется метод: + +{% tabs fp-function-used-like-method %} + +{% tab 'Scala 2 и 3' %} +```scala +double(2) // 4 +``` +{% endtab %} + +{% endtabs %} + +В большинстве случаев не имеет значения, является ли `double` функцией или методом; +Scala позволяет обращаться с ними одинаково. +За кулисами технология Scala, которая позволяет обращаться с методами так же, +как с функциями, известна как [Eta Expansion][eta]. + +Эта способность беспрепятственно передавать функции в качестве переменных +является отличительной чертой функциональных языков программирования, таких как Scala. +И, как было видно на примерах `map` и `filter`, +возможность передавать функции в другие функции помогает создавать код, +который является кратким и при этом читабельным — _выразительным_. + +Вот еще несколько примеров: + +{% tabs fp-function-as-values-example %} + +{% tab 'Scala 2 и 3' %} +```scala +List("bob", "joe").map(_.toUpperCase) // List(BOB, JOE) +List("bob", "joe").map(_.capitalize) // List(Bob, Joe) +List("plum", "banana").map(_.length) // List(4, 6) + +val fruits = List("apple", "pear") +fruits.map(_.toUpperCase) // List(APPLE, PEAR) +fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R) + +val nums = List(5, 1, 3, 11, 7) +nums.map(_ * 2) // List(10, 2, 6, 22, 14) +nums.filter(_ > 3) // List(5, 11, 7) +nums.takeWhile(_ < 6) // List(5, 1, 3) +nums.sortWith(_ < _) // List(1, 3, 5, 7, 11) +nums.sortWith(_ > _) // List(11, 7, 5, 3, 1) + +nums.takeWhile(_ < 6).sortWith(_ < _) // List(1, 3, 5) +``` +{% endtab %} + +{% endtabs %} + + +[hofs]: {% link _overviews/scala3-book/fun-hofs.md %} +[eta]: {% link _overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_ru/scala3/book/fp-immutable-values.md b/_ru/scala3/book/fp-immutable-values.md new file mode 100644 index 0000000000..53f63d0b26 --- /dev/null +++ b/_ru/scala3/book/fp-immutable-values.md @@ -0,0 +1,109 @@ +--- +layout: multipage-overview +title: Неизменяемые значения +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе рассматривается использование неизменяемых значений в функциональном программировании. +language: ru +num: 43 +previous-page: fp-what-is-fp +next-page: fp-pure-functions +--- + +В чистом функциональном программировании используются только неизменяемые значения. +В Scala это означает: + +- все переменные создаются как поля `val` +- используются только неизменяемые классы коллекций, такие как `List`, `Vector` и неизменяемые классы `Map` и `Set` + +Использование только неизменяемых переменных поднимает интересный вопрос: если все статично, как вообще что-то меняется? + +Когда дело доходит до использования коллекций, один из ответов заключается в том, +что существующая коллекция не меняется; вместо этого функция применяется к коллекции, чтобы создать новую. +Именно здесь вступают в действие функции высшего порядка, такие как `map` и `filter`. + +Например, представим, что есть список имен в нижнем регистре — `List[String]`, +и необходимо найти все имена, начинающиеся с буквы `"j"`, чтобы затем сделать первые буквы заглавными. +В ФП код будет выглядеть так: + +{% tabs fp-list %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = List("jane", "jon", "mary", "joe") +val b = a.filter(_.startsWith("j")) + .map(_.capitalize) +``` +{% endtab %} + +{% endtabs %} + +Как показано, исходный список `a` не меняется. +Вместо этого к `a` применяется функция фильтрации и преобразования, чтобы создать новую коллекцию, +и результат присваивается неизменяемой переменной `b`. + +Точно так же в ФП не используются классы с изменяемыми параметрами конструктора `var`. +В ФП создание такого класса не привествуется: + +{% tabs fp--class-variables %} + +{% tab 'Scala 2 и 3' %} +```scala +// не стоит этого делать в ФП +class Person(var firstName: String, var lastName: String) + --- --- +``` +{% endtab %} + +{% endtabs %} + +Вместо этого обычно создаются `case` классы, чьи параметры конструктора по умолчанию неизменяемые (`val`): + +{% tabs fp-immutable-case-class %} + +{% tab 'Scala 2 и 3' %} +```scala +case class Person(firstName: String, lastName: String) +``` +{% endtab %} + +{% endtabs %} + +Теперь можно создать экземпляр `Person` как поле `val`: + +{% tabs fp-case-class-creation %} + +{% tab 'Scala 2 и 3' %} +```scala +val reginald = Person("Reginald", "Dwight") +``` +{% endtab %} + +{% endtabs %} + +Затем, при необходимости внести изменения в данные, используется метод `copy`, +который поставляется с `case` классом, чтобы “обновлять данные через создание копии”, +например так: + +{% tabs fp-case-class-copy %} + +{% tab 'Scala 2 и 3' %} +```scala +val elton = reginald.copy( + firstName = "Elton", // обновить имя + lastName = "John" // обновить фамилию +) +``` +{% endtab %} + +{% endtabs %} + +Существуют множество других приёмов работы с неизменяемыми коллекциями и переменными. + +> В зависимости от задач вместо `case` классов можно создавать перечисления, trait-ы или классы. +> Для более подробной информации см. главу [“Моделирование данных”][modeling]. + + +[modeling]: {% link _overviews/scala3-book/domain-modeling-intro.md %} diff --git a/_ru/scala3/book/fp-intro.md b/_ru/scala3/book/fp-intro.md new file mode 100644 index 0000000000..5c9b3f5fad --- /dev/null +++ b/_ru/scala3/book/fp-intro.md @@ -0,0 +1,30 @@ +--- +layout: multipage-overview +title: Функциональное программирование +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе представлено введение в функциональное программирование в Scala 3. +language: ru +num: 41 +previous-page: collections-summary +next-page: fp-what-is-fp +--- + +Scala позволяет писать код в стиле объектно-ориентированного программирования (ООП), +в стиле функционального программирования (ФП), а также в гибридном стиле, используя оба подхода в комбинации. +По словам Martin Odersky, +сущность Scala — это слияние функционального и объектно-ориентированного программирования в типизированной среде: + +- Функции для логики +- Объекты для модульности + +В этой главе предполагается, что вы знакомы с ООП и менее знакомы с ФП, +поэтому в ней представлено краткое введение в несколько основных концепций функционального программирования: + +- Что такое функциональное программирование? +- Неизменяемые значения +- Чистые функции +- Функции — это значения +- Функциональная обработка ошибок diff --git a/_ru/scala3/book/fp-pure-functions.md b/_ru/scala3/book/fp-pure-functions.md new file mode 100644 index 0000000000..47a277a858 --- /dev/null +++ b/_ru/scala3/book/fp-pure-functions.md @@ -0,0 +1,153 @@ +--- +layout: multipage-overview +title: Чистые функции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе рассматривается использование чистых функций в функциональном программировании. +language: ru +num: 44 +previous-page: fp-immutable-values +next-page: fp-functions-are-values +--- + + +Еще одна концепция, которую Scala предлагает для помощи в написании функционального кода, — это возможность писать чистые функции. +_Чистая функция_ (_pure function_) может быть определена следующим образом: + +- функция `f` является чистой, если при одних и тех же входных данных `x` она всегда возвращает один и тот же результат `f(x)` +- результат функции зависит _только_ от входных данных и её реализации +- чистые функции только вычисляют результат, ничего не меняя за пределами этих функций + +Из этого следует: + +- чистая функция не изменяет свои входные параметры +- она не мутирует какое-либо скрытое состояние +- у неё нет “черных ходов”: он не читает данные из внешнего мира (включая консоль, веб-сервисы, базы данных, файлы и т.д.) + и не записывает данные вовне + +В результате этого определения каждый раз, когда вызывается чистая функция с одним и тем же входным значением (значениями), +всегда будет выдаваться один и тот же результат. +Например, можно вызывать функцию `double` бесконечное число раз с входным значением `2`, и всегда получать результат `4`. + + +## Примеры чистых функций + +Учитывая это определение, методы в пакете `scala.math._` являются чистыми функциями: + +- `abs` +- `ceil` +- `max` + +Эти методы `String` также являются чистыми функциями: + +- `isEmpty` +- `length` +- `substring` + +Большинство методов в классах коллекций Scala также работают как чистые функции, +включая `drop`, `filter`, `map` и многие другие. + +> В Scala _функции_ и _методы_ почти полностью взаимозаменяемы, +> поэтому, хотя здесь используется общепринятый отраслевой термин “чистая функция”, +> этот термин можно использовать как для описания функций, так и методов. +> Как методы могут использоваться подобно функциям описано в главе [Eta расширение][eta]. + + +## Примеры “грязных” функций + +И наоборот, следующие функции “_грязные_” (_impure_), потому что они нарушают определение pure function: + +- `println` — методы, взаимодействующие с консолью, файлами, базами данных, веб-сервисами и т.д., “грязные” +- `currentTimeMillis` — все методы, связанные с датой и временем, “грязные”, + потому что их вывод зависит от чего-то другого, кроме входных параметров +- `sys.error` — методы генерации исключений “грязные”, потому что они не “просто возвращают результат” + +“Грязные” функции часто делают одно из следующего: + +- читают из скрытого состояния, т.е. обращаются к параметрам и данным, + не переданным в функцию явным образом в качестве входных параметров +- запись в скрытое состояние +- изменяют заданные им параметры или изменяют скрытые переменные, например, поля в содержащем их классе +- выполняют какой-либо ввод-вывод с внешним миром + +> В общем, следует остерегаться функций с возвращаемым типом `Unit`. +> Поскольку эти функции ничего не возвращают, логически единственная причина, по которой они когда-либо вызываются, - +> это достижение какого-то побочного эффекта. +> Как следствие, часто использование этих функций является “грязным”. + + +## Но грязные функции все же необходимы ... + +Конечно, приложение не очень полезно, если оно не может читать или писать во внешний мир, поэтому рекомендуется следующее: + +> Напишите ядро вашего приложения, используя только “чистые” функции, +> а затем напишите “грязную” “оболочку” вокруг этого ядра для взаимодействия с внешним миром. +> Как кто-то однажды сказал, это все равно, что положить слой нечистой глазури на чистый торт. + +Важно отметить, что есть способы сделать “нечистое” взаимодействие с внешним миром более “чистым”. +Например, можно услышать об использовании `IO` монады для обработки ввода-вывода. +Эти темы выходят за рамки данного документа, поэтому для простоты можно думать, +что ФП приложения имеют ядро из “чистых” функций, +которые объединены с другими функциями для взаимодействия с внешним миром. + + +## Написание “чистых” функций + +**Примечание**: в этом разделе для обозначения методов Scala часто используется общепринятый в отрасли термин “чистая функция”. + +Для написания чистых функций на Scala, достаточно писать их, +используя синтаксис методов Scala (хотя также можно использовать и синтаксис функций Scala). +Например, вот чистая функция, которая удваивает заданное ей входное значение: + +{% tabs fp-pure-function %} + +{% tab 'Scala 2 и 3' %} +```scala +def double(i: Int): Int = i * 2 +``` +{% endtab %} + +{% endtabs %} + +Вот чистая функция, которая вычисляет сумму списка целых чисел с использованием рекурсии: + +{% tabs fp-pure-recursive-function class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +def sum(xs: List[Int]): Int = xs match { + case Nil => 0 + case head :: tail => head + sum(tail) +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def sum(xs: List[Int]): Int = xs match + case Nil => 0 + case head :: tail => head + sum(tail) +``` +{% endtab %} + +{% endtabs %} + +Вышеописанные функции соответствуют определению “чистых”. + + +## Ключевые моменты + +Первым ключевым моментом этого раздела является определение чистой функции: + +> _Чистая функция_ — это функция, которая зависит только от своих объявленных входных данных +> и своей реализации для получения результата. +> Она только вычисляет свой результат, не завися от внешнего мира и не изменяя его. + +Второй ключевой момент заключается в том, что каждое реальное приложение взаимодействует с внешним миром. +Таким образом, упрощенный способ представления о функциональных программах состоит в том, +что они состоят из ядра чистых функций, которые обернуты другими функциями, взаимодействующими с внешним миром. + + +[eta]: {% link _overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_ru/scala3/book/fp-summary.md b/_ru/scala3/book/fp-summary.md new file mode 100644 index 0000000000..0e18a20356 --- /dev/null +++ b/_ru/scala3/book/fp-summary.md @@ -0,0 +1,31 @@ +--- +layout: multipage-overview +title: Обзор +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: Этот раздел суммирует предыдущие разделы функционального программирования. +language: ru +num: 47 +previous-page: fp-functional-error-handling +next-page: types-introduction +--- + + +В этой главе представлено общее введение в функциональное программирование на Scala. +Охвачены следующие темы: + +- Что такое функциональное программирование? +- Неизменяемые значения +- Чистые функции +- Функции — это значения +- Функциональная обработка ошибок + +Как уже упоминалось, функциональное программирование — обширная тема, +поэтому все, что мы можем сделать в этой книге, — это коснуться перечисленных вводных понятий. +Дополнительные сведения см. [в справочной документации][reference]. + + +[reference]: {{ site.scala3ref }}/overview.html + diff --git a/_ru/scala3/book/fp-what-is-fp.md b/_ru/scala3/book/fp-what-is-fp.md new file mode 100644 index 0000000000..8b624b5415 --- /dev/null +++ b/_ru/scala3/book/fp-what-is-fp.md @@ -0,0 +1,48 @@ +--- +layout: multipage-overview +title: Что такое функциональное программирование? +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: Этот раздел дает ответ на вопрос, что такое функциональное программирование? +language: ru +num: 42 +previous-page: fp-intro +next-page: fp-immutable-values +--- + + +[Wikipedia](https://ru.wikipedia.org/wiki/%D0%A4%D1%83%D0%BD%D0%BA%D1%86%D0%B8%D0%BE%D0%BD%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B5_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5) +определяет _функциональное программирование_ следующим образом: + +
            +

            +Функциональное программирование — парадигма программирования, +в которой процесс вычисления трактуется как вычисление значений функций в математическом понимании последних. +Функциональное программирование предполагает обходиться вычислением результатов функций от исходных данных +и результатов других функций, и не предполагает явного хранения состояния программы. +Соответственно, не предполагает оно и изменяемость этого состояния. +

            +

             

            +

            +В функциональном программировании функции рассматриваются как “граждане первого класса”, +что означает, что они могут быть привязаны к именам (включая локальные идентификаторы), +передаваться в качестве аргументов и возвращаться из других функций, как и любой другой тип данных. +Это позволяет писать программы в декларативном и составном стиле, где небольшие функции объединяются модульным образом. +

            +
            + +Также полезно знать, что опытные функциональные программисты рассматривают свой код математически, +что объединение чистых функций вместе похоже на объединение ряда алгебраических уравнений. + +Когда пишется функциональный код, вы чувствуете себя математиком, и как только понимаете парадигму, +то хотите писать только чистые функции, которые всегда возвращают _значения_, а не исключения или null, +чтобы можно было комбинировать чистые функции вместе. +Ощущение, что вы пишете математические уравнения (выражения), является движущим желанием, +заставляющим использовать _только_ чистые функции и неизменяемые значения - +это то, что используется в алгебре и других формах математики. + +Функциональное программирование - это большая тема, и нет простого способа сжать её всю в одну главу. +В следующих разделах будет представлен обзор основных тем и показаны некоторые инструменты, +предоставляемые Scala для написания функционального кода. diff --git a/_ru/scala3/book/fun-anonymous-functions.md b/_ru/scala3/book/fun-anonymous-functions.md new file mode 100644 index 0000000000..98b7158e8f --- /dev/null +++ b/_ru/scala3/book/fun-anonymous-functions.md @@ -0,0 +1,214 @@ +--- +layout: multipage-overview +title: Анонимные функции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как использовать анонимные функции в Scala, включая примеры с функциями map и filter класса List. +language: ru +num: 29 +previous-page: fun-intro +next-page: fun-function-variables +--- + +Анонимная функция, также известная как _лямбда_, представляет собой блок кода, +который передается в качестве аргумента функции высшего порядка. +Википедия определяет [анонимную функцию](https://en.wikipedia.org/wiki/Anonymous_function) +как “определение функции, не привязанное к идентификатору”. + +Например, возьмем коллекцию: + +{% tabs fun-anonymous-1 %} +{% tab 'Scala 2 и 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +Можно создать новый список, удвоив каждый элемент в целых числах, используя метод `map` класса `List` +и свою пользовательскую анонимную функцию: + +{% tabs fun-anonymous-2 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map(_ * 2) // List(2, 4, 6) +``` +{% endtab %} +{% endtabs %} + +Как видно из комментария, `doubleInts` содержит список `List(2, 4, 6)`. +В этом примере анонимной функцией является часть кода: + +{% tabs fun-anonymous-3 %} +{% tab 'Scala 2 и 3' %} +```scala +_ * 2 +``` +{% endtab %} +{% endtabs %} + +Это сокращенный способ сказать: “Умножить данный элемент на 2”. + +## Более длинные формы + +Когда вы освоитесь со Scala, то будете постоянно использовать эту форму для написания анонимных функций, +использующих одну переменную в одном месте функции. +Но при желании можете также написать их, используя более длинные формы, +поэтому в дополнение к написанию этого кода: + +{% tabs fun-anonymous-4 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +вы также можете написать его, используя такие формы: + +{% tabs fun-anonymous-5 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +val doubledInts = ints.map((i) => i * 2) +val doubledInts = ints.map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +Все эти строки имеют одно и то же значение: удваивайте каждый элемент `ints`, чтобы создать новый список, `doubledInts` +(синтаксис каждой формы объясняется ниже). + +Если вы знакомы с Java, вам будет полезно узнать, что эти примеры `map` эквивалентны следующему Java коду: + +{% tabs fun-anonymous-5-b %} +{% tab 'Java' %} +```java +List ints = List.of(1, 2, 3); +List doubledInts = ints.stream() + .map(i -> i * 2) + .collect(Collectors.toList()); +``` +{% endtab %} +{% endtabs %} + +## Сокращение анонимных функций + +Если необходимо явно указать анонимную функцию, можно использовать следующую длинную форму: + +{% tabs fun-anonymous-6 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +``` +{% endtab %} +{% endtabs %} + +Анонимная функция в этом выражении такова: + +{% tabs fun-anonymous-7 %} +{% tab 'Scala 2 и 3' %} +```scala +(i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +Если незнаком данный синтаксис, то можно воспринимать символ `=>` как преобразователь, +потому что выражение _преобразует_ список параметров в левой части символа (переменная `Int` с именем `i`) +в новый результат, используя алгоритм справа от символа `=>` +(в данном случае выражение, которое удваивает значение `Int`). + + +### Сокращение выражения + +Эту длинную форму можно сократить, как будет показано в следующих шагах. +Во-первых, вот снова самая длинная и явная форма: + +{% tabs fun-anonymous-8 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +``` +{% endtab %} +{% endtabs %} + +Поскольку компилятор Scala может сделать вывод из данных в `ints` о том, что `i` - это `Int`, +`Int` объявление можно удалить: + +{% tabs fun-anonymous-9 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map((i) => i * 2) +``` +{% endtab %} +{% endtabs %} + +Поскольку есть только один аргумент, круглые скобки вокруг параметра `i` не нужны: + +{% tabs fun-anonymous-10 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +Поскольку Scala позволяет использовать символ `_` вместо имени переменной, +когда параметр появляется в функции только один раз, код можно упростить еще больше: + +{% tabs fun-anonymous-11 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +### Ещё короче + +В других примерах можно еще больше упростить анонимные функции. +Например, начиная с самой явной формы, можно распечатать каждый элемент в `ints`, +используя эту анонимную функцию с методом `foreach` класса `List`: + +{% tabs fun-anonymous-12 %} +{% tab 'Scala 2 и 3' %} +```scala +ints.foreach((i: Int) => println(i)) +``` +{% endtab %} +{% endtabs %} + +Как и раньше, объявление `Int` не требуется, а поскольку аргумент всего один, скобки вокруг `i` не нужны: + +{% tabs fun-anonymous-13 %} +{% tab 'Scala 2 и 3' %} +```scala +ints.foreach(i => println(i)) +``` +{% endtab %} +{% endtabs %} + +Поскольку `i` используется в теле функции только один раз, выражение можно еще больше упростить с помощью символа `_`: + +{% tabs fun-anonymous-14 %} +{% tab 'Scala 2 и 3' %} +```scala +ints.foreach(println(_)) +``` +{% endtab %} +{% endtabs %} + +Наконец, если анонимная функция состоит из одного вызова метода с одним аргументом, +нет необходимости явно называть и указывать аргумент, +можно написать только имя метода (здесь, `println`): + +{% tabs fun-anonymous-15 %} +{% tab 'Scala 2 и 3' %} +```scala +ints.foreach(println) +``` +{% endtab %} +{% endtabs %} diff --git a/_ru/scala3/book/fun-eta-expansion.md b/_ru/scala3/book/fun-eta-expansion.md new file mode 100644 index 0000000000..1cbbc3255a --- /dev/null +++ b/_ru/scala3/book/fun-eta-expansion.md @@ -0,0 +1,92 @@ +--- +layout: multipage-overview +title: Eta расширение +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице обсуждается Eta Expansion, технология Scala, которая автоматически и прозрачно преобразует методы в функции. +language: ru +num: 31 +previous-page: fun-function-variables +next-page: fun-hofs +--- + + +Если посмотреть на Scaladoc для метода `map` в классах коллекций Scala, +то можно увидеть, что метод определен для приема _функции_: + +```scala +def map[B](f: (A) => B): List[B] + ----------- +``` + +Действительно, в Scaladoc сказано: “`f` — это _функция_, применяемая к каждому элементу”. +Но, несмотря на это, каким-то образом в `map` можно передать _метод_, и он все еще работает: + +```scala +def times10(i: Int) = i * 10 // метод +List(1, 2, 3).map(times10) // List(10,20,30) +``` + +Как это работает? Как можно передать _метод_ в `map`, который ожидает _функцию_? + +Технология, стоящая за этим, известна как _Eta Expansion_. +Она преобразует выражение _типа метода_ в эквивалентное выражение _типа функции_, и делает это легко и незаметно. + + +## Различия между методами и функциями + +Исторически _методы_ были частью определения класса, хотя в Scala 3 методы могут быть вне классов, +такие как [определения верхнего уровня][toplevel] и [методы расширения][extension]. + +В отличие от методов, _функции_ сами по себе являются полноценными объектами, что делает их объектами первого класса. + +Их синтаксис также отличается. +В этом примере показано, как задать метод и функцию, которые выполняют одну и ту же задачу, +определяя, является ли заданное целое число четным: + +```scala +def isEvenMethod(i: Int) = i % 2 == 0 // метод +val isEvenFunction = (i: Int) => i % 2 == 0 // функция +``` + +Функция действительно является объектом, поэтому ее можно использовать так же, +как и любую другую переменную, например, помещая в список: + +```scala +val functions = List(isEvenFunction) +``` + +И наоборот, технически метод не является объектом, поэтому в Scala 2 метод нельзя было поместить в `List`, +по крайней мере, напрямую, как показано в этом примере: + +```scala +// В этом примере показано сообщение об ошибке в Scala 2 +val methods = List(isEvenMethod) + ^ +error: missing argument list for method isEvenMethod +Unapplied methods are only converted to functions when a function type is expected. +You can make this conversion explicit by writing `isEvenMethod _` or `isEvenMethod(_)` instead of `isEvenMethod`. +``` + +Как показано в этом сообщении об ошибке, в Scala 2 существует ручной способ преобразования метода в функцию, +но важной частью для Scala 3 является то, что технология Eta Expansion улучшена, +поэтому теперь, когда попытаться использовать метод в качестве переменной, +он просто работает — не нужно самостоятельно выполнять ручное преобразование: + +```scala +val functions = List(isEvenFunction) // работает +val methods = List(isEvenMethod) // работает +``` + +Для целей этой вводной книги важно знать следующее: + +- Eta Expansion — технология Scala, позволяющая использовать методы так же, как и функции +- Технология была улучшена в Scala 3, чтобы быть почти полностью бесшовной + +Дополнительные сведения о том, как это работает, см. на [странице Eta Expansion][eta_expansion] в справочной документации. + +[eta_expansion]: {{ site.scala3ref }}/changed-features/eta-expansion.html +[extension]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[toplevel]: {% link _overviews/scala3-book/taste-toplevel-definitions.md %} diff --git a/_ru/scala3/book/fun-function-variables.md b/_ru/scala3/book/fun-function-variables.md new file mode 100644 index 0000000000..667d4e7c30 --- /dev/null +++ b/_ru/scala3/book/fun-function-variables.md @@ -0,0 +1,172 @@ +--- +layout: multipage-overview +title: Параметры функции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как использовать параметры функции в Scala. +language: ru +num: 30 +previous-page: fun-anonymous-functions +next-page: fun-eta-expansion +--- + + +Вернемся к примеру из предыдущего раздела: + +{% tabs fun-function-variables-1 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +``` +{% endtab %} +{% endtabs %} + +Анонимной функцией является следующая часть: + +{% tabs fun-function-variables-2 %} +{% tab 'Scala 2 и 3' %} +```scala +(i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +Причина, по которой она называется _анонимной_ (_anonymous_), заключается в том, +что она не присваивается переменной и, следовательно, не имеет имени. + +Однако анонимная функция, также известная как _функциональный литерал_ (_function literal_), +может быть назначена переменной для создания _функциональной переменной_ (_function variable_): + +{% tabs fun-function-variables-3 %} +{% tab 'Scala 2 и 3' %} +```scala +val double = (i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +Код выше создает функциональную переменную с именем `double`. +В этом выражении исходный литерал функции находится справа от символа `=`: + +{% tabs fun-function-variables-4 %} +{% tab 'Scala 2 и 3' %} +```scala +val double = (i: Int) => i * 2 + ----------------- +``` +{% endtab %} +{% endtabs %} + +, а новое имя переменной - слева: + +{% tabs fun-function-variables-5 %} +{% tab 'Scala 2 и 3' %} +```scala +val double = (i: Int) => i * 2 + ------ +``` +{% endtab %} +{% endtabs %} + +список параметров функции подчеркнут: + +{% tabs fun-function-variables-6 %} +{% tab 'Scala 2 и 3' %} +```scala +val double = (i: Int) => i * 2 + -------- +``` +{% endtab %} +{% endtabs %} + +Как и список параметров для метода, список параметров функции означает, +что функция `double` принимает один параметр с типом `Int` и именем `i`. +Как можно видеть ниже, `double` имеет тип `Int => Int`, +что означает, что он принимает один параметр `Int` и возвращает `Int`: + +{% tabs fun-function-variables-7 %} +{% tab 'Scala 2 и 3' %} +```scala +scala> val double = (i: Int) => i * 2 +val double: Int => Int = ... +``` +{% endtab %} +{% endtabs %} + + +### Вызов функции + +Функция `double` может быть вызвана так: + +{% tabs fun-function-variables-8 %} +{% tab 'Scala 2 и 3' %} +```scala +val x = double(2) // 4 +``` +{% endtab %} +{% endtabs %} + +`double` также можно передать в вызов `map`: + +{% tabs fun-function-variables-9 %} +{% tab 'Scala 2 и 3' %} +```scala +List(1, 2, 3).map(double) // List(2, 4, 6) +``` +{% endtab %} +{% endtabs %} + +Кроме того, когда есть другие функции типа `Int => Int`: + +{% tabs fun-function-variables-10 %} +{% tab 'Scala 2 и 3' %} +```scala +val triple = (i: Int) => i * 3 +``` +{% endtab %} +{% endtabs %} + +можно сохранить их в `List` или `Map`: + +{% tabs fun-function-variables-11 %} +{% tab 'Scala 2 и 3' %} +```scala +val functionList = List(double, triple) + +val functionMap = Map( + "2x" -> double, + "3x" -> triple +) +``` +{% endtab %} +{% endtabs %} + +Если вы вставите эти выражения в REPL, то увидите, что они имеют следующие типы: + +{% tabs fun-function-variables-12 %} +{% tab 'Scala 2 и 3' %} +```` +// список, содержащий функции типа `Int => Int` +functionList: List[Int => Int] + +// Map, ключи которой имеют тип `String`, +// а значения имеют тип `Int => Int` +functionMap: Map[String, Int => Int] +```` +{% endtab %} +{% endtabs %} + + + +## Ключевые моменты + +Ключевыми моментами здесь являются: + +- чтобы создать функциональную переменную, достаточно присвоить имя переменной функциональному литералу +- когда есть функция, с ней можно обращаться как с любой другой переменной, то есть как со `String` или `Int` переменной + +А благодаря улучшенной функциональности [Eta Expansion][eta_expansion] в Scala 3 с _методами_ можно обращаться точно так же. + +[eta_expansion]: {% link _overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_ru/scala3/book/fun-hofs.md b/_ru/scala3/book/fun-hofs.md new file mode 100644 index 0000000000..805f243533 --- /dev/null +++ b/_ru/scala3/book/fun-hofs.md @@ -0,0 +1,389 @@ +--- +layout: multipage-overview +title: Функции высшего порядка +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как создавать и использовать функции высшего порядка в Scala. +language: ru +num: 32 +previous-page: fun-eta-expansion +next-page: fun-write-map-function +--- + + +Функция высшего порядка (HOF - higher-order function) часто определяется как функция, которая + +- принимает другие функции в качестве входных параметров или +- возвращает функцию в качестве результата. + +В Scala HOF возможны, потому что функции являются объектами первого класса. + +В качестве важного примечания: хотя в этом документе используется общепринятый термин “функция высшего порядка”, +в Scala эта фраза применима как к методам, так и к функциям. +Благодаря [технологии Eta Expansion][eta_expansion] их, как правило, можно использовать в одних и тех же местах. + + +## От потребителя к разработчику + +В примерах, приведенных ранее в документации, было видно, как _пользоваться_ методами, +которые принимают другие функции в качестве входных параметров, например, `map` и `filter`. + +В следующих разделах будет показано, как _создавать_ HOF, в том числе: + +- как писать методы, принимающие функции в качестве входных параметров +- как возвращать функции из методов + +В процессе будет видно: + +- синтаксис, который используется для определения входных параметров функции +- как вызвать функцию, если есть на нее ссылка + +В качестве полезного побочного эффекта, как только синтаксис станет привычным, +его можно начать использовать для определения параметров функций, анонимных функций и функциональных переменных, +а также станет легче читать Scaladoc для функций высшего порядка. + + +## Понимание Scaladoc метода filter + +Чтобы понять, как работают функции высшего порядка, рассмотрим пример: +определим, какой тип функций принимает `filter`, взглянув на его Scaladoc. +Вот определение `filter` в классе `List[A]`: + +{% tabs filter-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def filter(p: A => Boolean): List[A] +``` +{% endtab %} +{% endtabs %} + +Это определение указывает на то, что `filter` - метод, который принимает параметр функции с именем `p`. +По соглашению, `p` обозначает _предикат_, который представляет собой просто функцию, возвращающую `Boolean`. +Таким образом, `filter` принимает предикат `p` в качестве входного параметра и возвращает `List[A]`, +где `A` - тип, содержащийся в списке; если `filter` вызывается для `List[Int]`, то `A` - это тип `Int`. + +На данный момент, если не учитывать назначение метода `filter`, +все, что известно, так это то, что алгоритм каким-то образом использует предикат `p` для создания и возврата `List[A]`. + +Если посмотреть конкретно на параметр функции `p`: + +```scala +p: A => Boolean +``` + +, то эта часть описания `filter` означает, что любая передаваемая функция +должна принимать тип `A` в качестве входного параметра и возвращать `Boolean`. +Итак, если список представляет собой список `List[Int]`, +то можно заменить универсальный тип `A` на `Int` и прочитать эту подпись следующим образом: + +```scala +p: Int => Boolean +``` + +Поскольку `isEven` имеет такой же тип — преобразует входное значение `Int` в результирующее `Boolean` — +его можно использовать с `filter`. + + +## Написание методов, которые принимают параметры функции + +Рассмотрим пример написания методов, которые принимают функции в качестве входных параметров. + +**Примечание:** для определенности, будем называть код, который пишется, _методом_, +а код, принимаемый в качестве входного параметра, — _функцией_. + +### Пример + +Чтобы создать метод, который принимает функцию в качестве параметра, необходимо: + +1. в списке параметров метода определить сигнатуру принимаемой функции +2. использовать эту функцию внутри метода + +Чтобы продемонстрировать это, вот метод, который принимает входной параметр с именем `f`, где `f` — функция: + + +{% tabs sayHello-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def sayHello(f: () => Unit): Unit = f() +``` +{% endtab %} +{% endtabs %} + +Эта часть кода — _сигнатура типа (type signature)_ — утверждает, что `f` является функцией, +и определяет типы функций, которые будет принимать метод `sayHello`: + +```scala +f: () => Unit +``` + +Как это работает: + +- `f` — имя входного параметра функции. + Аналогично тому, как параметр `String` обычно называется `s` или параметр `Int` - `i` +- сигнатура типа `f` определяет _тип_ функций, которые будет принимать метод +- часть `()` подписи `f` (слева от символа `=>`) указывает на то, что `f` не принимает входных параметров +- часть сигнатуры `Unit` (справа от символа `=>`) указывает на то, что функция `f` не должна возвращать осмысленный результат +- в теле метода `sayHello` (справа от символа `=`) оператор `f()` вызывает переданную функцию + +Теперь, когда `sayHello` определен, создадим функцию, соответствующую сигнатуре `f`, чтобы ее можно было проверить. +Следующая функция не принимает входных параметров и ничего не возвращает, поэтому она соответствует сигнатуре типа `f`: + +{% tabs helloJoe-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def helloJoe(): Unit = println("Hello, Joe") +``` +{% endtab %} +{% endtabs %} + + +Поскольку сигнатуры типов совпадают, можно передать `helloJoe` в `sayHello`: + +{% tabs sayHello-usage %} +{% tab 'Scala 2 и 3' %} +```scala +sayHello(helloJoe) // печатает "Hello, Joe" +``` +{% endtab %} +{% endtabs %} + +Если вы никогда этого не делали раньше, поздравляем: +был определен метод с именем `sayHello`, который принимает функцию в качестве входного параметра, +а затем вызывает эту функцию в теле своего метода. + + +### sayHello может принимать разные функции + +Важно знать, что преимущество этого подхода заключается не в том, +что `sayHello` может принимать одну функцию в качестве входного параметра; +преимущество в том, что `sayHello` может принимать любую функцию, соответствующую сигнатуре `f`. +Например, поскольку следующая функция не принимает входных параметров и ничего не возвращает, она также работает с `sayHello`: + +{% tabs bonjourJulien-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def bonjourJulien(): Unit = println("Bonjour, Julien") +``` +{% endtab %} +{% endtabs %} + +Вот что выводится в REPL: + +{% tabs bonjourJulien-usage %} +{% tab 'Scala 2 и 3' %} +```` +scala> sayHello(bonjourJulien) +Bonjour, Julien +```` +{% endtab %} +{% endtabs %} + +Это отличный старт. +Рассмотрим ещё несколько примеров того, как определять сигнатуры различных типов для параметров функции. + + +## Общий синтаксис для определения входных параметров функции + +В методе: + +{% tabs sayHello-definition-2 %} +{% tab 'Scala 2 и 3' %} +```scala +def sayHello(f: () => Unit): Unit +``` +{% endtab %} +{% endtabs %} + +сигнатурой типа для `f` является: + +```scala +() => Unit +``` + +Это сигнатура означает “функцию, которая не принимает входных параметров и не возвращает ничего значимого (`Unit`)”. + +Вот сигнатура функции, которая принимает параметр `String` и возвращает `Int`: + +```scala +f: String => Int +``` + +Какие функции принимают строку и возвращают целое число? +Например, такие, как “длина строки” и контрольная сумма. + +Эта функция принимает два параметра `Int` и возвращает `Int`: + +```scala +f: (Int, Int) => Int +``` + +Какие функции соответствуют данной сигнатуре? + +Любая функция, которая принимает два входных параметра `Int` и возвращает `Int`, +соответствует этой сигнатуре, поэтому все “функции” ниже (точнее, методы) подходят: + +{% tabs add-sub-mul-definitions %} +{% tab 'Scala 2 и 3' %} +```scala +def add(a: Int, b: Int): Int = a + b +def subtract(a: Int, b: Int): Int = a - b +def multiply(a: Int, b: Int): Int = a * b +``` +{% endtab %} +{% endtabs %} + +Из примеров выше можно сделать вывод, что общий синтаксис сигнатуры функций такой: + +```scala +variableName: (parameterTypes ...) => returnType +``` + +> Поскольку функциональное программирование похоже на создание и объединение ряда алгебраических уравнений, +> обычно _много думают_ о типах при разработке функций и приложений. +> Можно сказать, что “думают типами”. + + +## Параметр функции вместе с другими параметрами + +Чтобы HOFs стали действительно полезными, им также нужны некоторые данные для работы. +Для класса, подобного `List`, в его методе `map` уже есть данные для работы: элементы в `List`. +Но для автономного приложения, у которого нет собственных данных, +метод также должен принимать в качестве других входных параметров данные. + +Рассмотрим пример метода с именем `executeNTimes`, который имеет два входных параметра: функцию и `Int`: + +{% tabs executeNTimes-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def executeNTimes(f: () => Unit, n: Int): Unit = + for (i <- 1 to n) f() +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def executeNTimes(f: () => Unit, n: Int): Unit = + for i <- 1 to n do f() +``` +{% endtab %} +{% endtabs %} + +Как видно из кода, `executeNTimes` выполняет функцию `f` `n` раз. +Поскольку простой цикл `for`, подобный этому, не имеет возвращаемого значения, `executeNTimes` возвращает `Unit`. + +Чтобы протестировать `executeNTimes`, определим метод, соответствующий сигнатуре `f`: + +{% tabs helloWorld-definition %} +{% tab 'Scala 2 и 3' %} +```scala +// тип метода - `() => Unit` +def helloWorld(): Unit = println("Hello, world") +``` +{% endtab %} +{% endtabs %} + +Затем передадим этот метод в `executeNTimes` вместе с `Int`: + +{% tabs helloWorld-usage %} +{% tab 'Scala 2 и 3' %} +``` +scala> executeNTimes(helloWorld, 3) +Hello, world +Hello, world +Hello, world +``` +{% endtab %} +{% endtabs %} + + +Великолепно. +Метод `executeNTimes` трижды выполняет функцию `helloWorld`. + + +### Столько параметров, сколько необходимо + +Методы могут усложняться по мере необходимости. +Например, этот метод принимает функцию типа `(Int, Int) => Int` вместе с двумя входными параметрами: + +{% tabs executeAndPrint-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def executeAndPrint(f: (Int, Int) => Int, i: Int, j: Int): Unit = + println(f(i, j)) +``` +{% endtab %} +{% endtabs %} + + +Поскольку методы `sum` и `multiply` соответствуют сигнатуре `f`, +их можно передать в `executeAndPrint` вместе с двумя значениями `Int`: + +{% tabs executeAndPrint-usage %} +{% tab 'Scala 2 и 3' %} +```scala +def sum(x: Int, y: Int) = x + y +def multiply(x: Int, y: Int) = x * y + +executeAndPrint(sum, 3, 11) // печатает 14 +executeAndPrint(multiply, 3, 9) // печатает 27 +``` +{% endtab %} +{% endtabs %} + + +## Согласованность подписи типа функции + +Самое замечательное в изучении сигнатур типов функций Scala заключается в том, +что синтаксис, используемый для определения входных параметров функции, — +это тот же синтаксис, что используется для написания литералов функций. + +Например, если необходимо написать функцию, вычисляющую сумму двух целых чисел, её можно было бы написать так: + +{% tabs f-val-definition %} +{% tab 'Scala 2 и 3' %} +```scala +val f: (Int, Int) => Int = (a, b) => a + b +``` +{% endtab %} +{% endtabs %} + +Этот код состоит из сигнатуры типа: + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ----------------- +```` + +входных параметров: + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ------ +```` + +и тела функции: + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ----- +```` + +Согласованность Scala состоит в том, что тип функции: + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ----------------- +```` + +совпадает с сигнатурой типа, используемого для определения входного параметра функции: + +```` +def executeAndPrint(f: (Int, Int) => Int, ... + ----------------- +```` + +По мере освоения этого синтаксиса, становится привычным его использование для определения параметров функций, +анонимных функций и функциональных переменных, а также становится легче читать Scaladoc для функций высшего порядка. + +[eta_expansion]: {% link _overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_ru/scala3/book/fun-intro.md b/_ru/scala3/book/fun-intro.md new file mode 100644 index 0000000000..01d2080096 --- /dev/null +++ b/_ru/scala3/book/fun-intro.md @@ -0,0 +1,17 @@ +--- +layout: multipage-overview +title: Функции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе рассматриваются темы, связанные с функциями в Scala 3. +language: ru +num: 28 +previous-page: methods-summary +next-page: fun-anonymous-functions +--- + +Если в предыдущей главе были представлены Scala _методы_, то в этой главе мы углубимся в _функции_. +Рассматриваемые темы включают анонимные функции, функциональные переменные и функции высшего порядка (HOF), +в том числе способы создания собственных HOF. diff --git a/_ru/scala3/book/fun-summary.md b/_ru/scala3/book/fun-summary.md new file mode 100644 index 0000000000..20391f5af9 --- /dev/null +++ b/_ru/scala3/book/fun-summary.md @@ -0,0 +1,41 @@ +--- +layout: multipage-overview +title: Обзор +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлен обзор предыдущего раздела 'Функции'. +language: ru +num: 35 +previous-page: fun-write-method-returns-function +next-page: packaging-imports +--- + +Это была длинная глава, поэтому давайте рассмотрим ключевые моменты, которые мы прошли. + +Функция высшего порядка (HOF) часто определяется как функция, +которая принимает другие функции в качестве входных параметров или возвращает функцию в качестве своего значения. +В Scala это возможно, потому что функции являются объектами первого класса. + +Двигаясь по разделам, сначала вы узнали: + +- Как писать анонимные функции в виде небольших фрагментов кода. +- Как передать их десяткам HOF (методов) в классах коллекций, т.е. таким методам, как `filter`, `map` и т.д. +- Как с помощью этих небольших фрагментов кода и мощных HOF создавать множество функций с помощью небольшого кода. + +Изучив анонимные функции и HOF, вы узнали: + +- Функциональные переменные — это просто анонимные функции, привязанные к переменной. + +Увидев, как быть потребителем HOF, вы увидели, как стать создателем HOF. +В частности, вы узнали: + +- Как писать методы, принимающие функции в качестве входных параметров +- Как вернуть функцию из метода + +Полезным побочным эффектом этой главы является то, +что вы увидели много примеров того, как объявлять сигнатуры типов для функций. +Преимущество этого заключается в том, что вы используете один и тот же синтаксис +для определения параметров функций, анонимных функций и функциональных переменных, +а также становится легче читать Scaladoc для функций высшего порядка, таких как `map`, `filter` и другие. diff --git a/_ru/scala3/book/fun-write-map-function.md b/_ru/scala3/book/fun-write-map-function.md new file mode 100644 index 0000000000..f7b6a0f63e --- /dev/null +++ b/_ru/scala3/book/fun-write-map-function.md @@ -0,0 +1,141 @@ +--- +layout: multipage-overview +title: Собственный map +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице описано, как создать свой собственный метод map +language: ru +num: 33 +previous-page: fun-hofs +next-page: fun-write-method-returns-function +--- + + +Теперь, когда известно, как писать собственные функции высшего порядка, рассмотрим более реальный пример. + +Представим, что у класса `List` нет метода `map`, и есть необходимость его написать. +Первым шагом при создании функций является точное определение проблемы. +Сосредоточившись только на `List[Int]`, получаем: + +> Необходимо написать метод `map`, который можно использовать для применения функции к каждому элементу в `List[Int]`, +> возвращая преобразованные элементы в виде нового списка. + +Учитывая это утверждение, начнем писать сигнатуру метода. +Во-первых, известно, что функция должна приниматься в качестве параметра, +и эта функция должна преобразовать `Int` в какой-то общий тип `A`, поэтому получаем: + +{% tabs map-accept-func-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def map(f: (Int) => A) +``` +{% endtab %} +{% endtabs %} + +Синтаксис использования универсального типа требует объявления этого символа типа перед списком параметров, +поэтому добавляем объявление типа: + +{% tabs map-type-symbol-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def map[A](f: (Int) => A) +``` +{% endtab %} +{% endtabs %} + +Далее известно, что `map` также должен принимать `List[Int]`: + +{% tabs map-list-int-param-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]) +``` +{% endtab %} +{% endtabs %} + +Наконец, также известно, что `map` возвращает преобразованный список, содержащий элементы универсального типа `A`: + +{% tabs map-with-return-type-definition %} +{% tab 'Scala 2 и 3' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]): List[A] = ??? +``` +{% endtab %} +{% endtabs %} + +Теперь все, что нужно сделать, это написать тело метода. +Метод `map` применяет заданную им функцию к каждому элементу в заданном списке для создания нового преобразованного списка. +Один из способов сделать это - использовать выражение `for`: + +{% tabs for-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +for (x <- xs) yield f(x) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +for x <- xs yield f(x) +``` +{% endtab %} +{% endtabs %} + +`for` выражения зачастую делают код удивительно простым, и в данном случае - это все тело метода. + +Объединив `for` с сигнатурой метода, получим автономный метод `map`, который работает с `List[Int]`: + +{% tabs map-function class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]): List[A] = + for (x <- xs) yield f(x) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]): List[A] = + for x <- xs yield f(x) +``` +{% endtab %} +{% endtabs %} + + +### Обобщим метод map + +Обратим внимание, что выражение `for` не делает ничего, что зависит от типа `Int` внутри списка. +Следовательно, можно заменить `Int` в сигнатуре типа параметром универсального типа `B`: + +{% tabs map-function-full-generic class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def map[A, B](f: (B) => A, xs: List[B]): List[A] = + for (x <- xs) yield f(x) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def map[A, B](f: (B) => A, xs: List[B]): List[A] = + for x <- xs yield f(x) +``` +{% endtab %} +{% endtabs %} + +Получился метод `map`, который работает с любым списком. + +Демонстрация работы получившегося `map`: + +{% tabs map-use-example %} +{% tab 'Scala 2 и 3' %} +```scala +def double(i : Int): Int = i * 2 +map(double, List(1, 2, 3)) // List(2, 4, 6) + +def strlen(s: String): Int = s.length +map(strlen, List("a", "bb", "ccc")) // List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +Теперь, когда рассмотрены методы, принимающие функции в качестве входных параметров, перейдем к методам, возвращающим функции. diff --git a/_ru/scala3/book/fun-write-method-returns-function.md b/_ru/scala3/book/fun-write-method-returns-function.md new file mode 100644 index 0000000000..a2bb66c69c --- /dev/null +++ b/_ru/scala3/book/fun-write-method-returns-function.md @@ -0,0 +1,176 @@ +--- +layout: multipage-overview +title: Создание метода, возвращающего функцию +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как создавать методы, возвращающие функции, в Scala. +language: ru +num: 34 +previous-page: fun-write-map-function +next-page: fun-summary +--- + + +Благодаря согласованности Scala написание метода, возвращающего функцию, похоже на то, что было описано в предыдущих разделах. +Например, представьте, что вы хотите написать метод `greet`, возвращающий функцию. +Еще раз начнем с постановки проблемы: + +> Необходимо создать метод greet, возвращающий функцию. +> Эта функция должна принимать строковый параметр и печатать его с помощью `println`. +> Начнем с простого шага: `greet` не принимает никаких входных параметров, а просто создает функцию и возвращает её. + +Учитывая это утверждение, можно начать создавать `greet`. +Известно, что это будет метод: + +```scala +def greet() +``` + +Также известно, что этот метод должен возвращать функцию, которая (a) принимает параметр `String` и +(b) печатает эту строку с помощью `println`. + +Следовательно, эта функция имеет тип `String => Unit`: + +```scala +def greet(): String => Unit = ??? + ---------------- +``` + +Теперь нужно просто создать тело метода. +Известно, что метод должен возвращать функцию, и эта функция принимает `String` и печатает ее. +Эта анонимная функция соответствует следующему описанию: + +```scala +(name: String) => println(s"Hello, $name") +``` + +Теперь вы просто возвращаете эту функцию из метода: + +```scala +// метод, который возвращает функцию +def greet(): String => Unit = + (name: String) => println(s"Hello, $name") +``` + +Поскольку этот метод возвращает функцию, вы получаете функцию, вызывая `greet()`. +Это хороший шаг для проверки в REPL, потому что он проверяет тип новой функции: + +```` +scala> val greetFunction = greet() +val greetFunction: String => Unit = Lambda.... + ----------------------------- +```` + +Теперь можно вызвать `greetFunction`: + +```scala +greetFunction("Joe") // печатает "Hello, Joe" +``` + +Поздравляем, вы только что создали метод, возвращающий функцию, а затем запустили её. + + +## Доработка метода + +Метод `greet` был бы более полезным, если бы была возможность задавать приветствие. +Например, передать его в качестве параметра методу `greet` и использовать внутри `println`: + +```scala +def greet(theGreeting: String): String => Unit = + (name: String) => println(s"$theGreeting, $name") +``` + +Теперь, при вызове этого метода, процесс становится более гибким, потому что приветствие можно изменить. +Вот как это выглядит, когда создается функция из этого метода: + +```` +scala> val sayHello = greet("Hello") +val sayHello: String => Unit = Lambda..... + ------------------------ +```` + +Выходные данные подписи типа показывают, что `sayHello` — это функция, +которая принимает входной параметр `String` и возвращает `Unit` (ничего). +Так что теперь, при передаче `sayHello` строки, печатается приветствие: + +```scala +sayHello("Joe") // печатает "Hello, Joe" +``` + +Приветствие можно менять для создания новых функций: + +```scala +val sayCiao = greet("Ciao") +val sayHola = greet("Hola") + +sayCiao("Isabella") // печатает "Ciao, Isabella" +sayHola("Carlos") // печатает "Hola, Carlos" +``` + + +## Более реалистичный пример + +Этот метод может быть еще более полезным, когда возвращает одну из многих возможных функций, +например, фабрику пользовательских функций. + +Например, представим, что необходимо написать метод, который возвращает функции, приветствующие людей на разных языках. +Ограничим это функциями, которые приветствуют на английском или французском языках, +в зависимости от параметра, переданного в метод. + +Созданный метод должен: (a) принимать “желаемый язык” в качестве входных данных +и (b) возвращать функцию в качестве результата. +Кроме того, поскольку эта функция печатает заданную строку, известно, что она имеет тип `String => Unit`. +С помощью этой информации сигнатура метода должна выглядеть так: + +```scala +def createGreetingFunction(desiredLanguage: String): String => Unit = ??? +``` + +Далее, поскольку возвращаемые функции, берут строку и печатают ее, +можно прикинуть две анонимные функции для английского и французского языков: + +```scala +(name: String) => println(s"Hello, $name") +(name: String) => println(s"Bonjour, $name") +``` + +Для большей читабельности дадим этим анонимным функциям имена и назначим двум переменным: + +```scala +val englishGreeting = (name: String) => println(s"Hello, $name") +val frenchGreeting = (name: String) => println(s"Bonjour, $name") +``` + +Теперь все, что осталось, это (a) вернуть `englishGreeting`, если `desiredLanguage` — английский, +и (b) вернуть `frenchGreeting`, если `desiredLanguage` — французский. +Один из способов сделать это - выражение `match`: + +```scala +def createGreetingFunction(desiredLanguage: String): String => Unit = + val englishGreeting = (name: String) => println(s"Hello, $name") + val frenchGreeting = (name: String) => println(s"Bonjour, $name") + desiredLanguage match + case "english" => englishGreeting + case "french" => frenchGreeting +``` + +И это последний метод. +Обратите внимание, что возврат значения функции из метода ничем не отличается от возврата строкового или целочисленного значения. + +Вот как `createGreetingFunction` создает функцию приветствия на французском языке: + +```scala +val greetInFrench = createGreetingFunction("french") +greetInFrench("Jonathan") // печатает "Bonjour, Jonathan" +``` + +И вот как - на английском: + +```scala +val greetInEnglish = createGreetingFunction("english") +greetInEnglish("Joe") // печатает "Hello, Joe" +``` + +Если вам понятен этот код — поздравляю — теперь вы знаете, как писать методы, возвращающие функции. diff --git a/_ru/scala3/book/interacting-with-java.md b/_ru/scala3/book/interacting-with-java.md new file mode 100644 index 0000000000..86f3268d46 --- /dev/null +++ b/_ru/scala3/book/interacting-with-java.md @@ -0,0 +1,560 @@ +--- +layout: multipage-overview +title: Взаимодействие с Java +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице показано, как код Scala может взаимодействовать с Java и как код Java может взаимодействовать с кодом Scala. +language: ru +num: 72 +previous-page: tools-worksheets +next-page: +--- + +## Введение + +В этом разделе рассматривается, как использовать код Java в Scala и, наоборот, как использовать код Scala в Java. + +В целом, использование Java-кода в Scala довольно простое. +Есть лишь несколько моментов, +когда может появиться желание использовать утилиты Scala для преобразования концепций Java в Scala, +в том числе: + +- Классы коллекций Java +- Java класс `Optional` + +Аналогично, если вы пишете код Java и хотите использовать концепции Scala, +вам потребуется преобразовать коллекции Scala и Scala класс `Option`. + +В следующих разделах демонстрируются наиболее распространенные преобразования, которые вам могут понадобиться: + +- Как использовать коллекции Java в Scala +- Как использовать Java `Optional` в Scala +- Расширение Java интерфейсов в Scala +- Как использовать коллекции Scala в Java +- Как использовать Scala `Option` в Java +- Как использовать трейты Scala в Java +- Как обрабатывать методы Scala, которые вызывают исключения в коде Java +- Как использовать vararg-параметры Scala в Java +- Создание альтернативных имен для использования методов Scala в Java + +> Обратите внимание: примеры Java в этом разделе предполагают, что вы используете Java 11 или более позднюю версию. + +## Как использовать коллекции Java в Scala + +Когда вы пишете код на Scala, а API либо требует, либо создает класс коллекции Java (из пакета `java.util`), +тогда допустимо напрямую использовать или создавать коллекцию, как в Java. + +Однако для идиоматического использования в Scala, например, для циклов `for` по коллекции +или для применения функций высшего порядка, таких как `map` и `filter`, +вы можете создать прокси, который будет вести себя как коллекция Scala. + +Вот пример того, как это работает. +Учитывая следующий API, который возвращает `java.util.List[String]`: + +{% tabs foo-definition %} +{% tab Java %} + +```java +public interface Foo { + static java.util.List getStrings() { + return List.of("a", "b", "c"); + } +} +``` + +{% endtab %} +{% endtabs %} + +Вы можете преобразовать этот Java список в Scala `Seq`, +используя утилиты преобразования из Scala объекта `scala.jdk.CollectionConverters`: + +{% tabs foo-usage class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.jdk.CollectionConverters._ +import scala.collection.mutable + +def testList() = { + println("Using a Java List in Scala") + val javaList: java.util.List[String] = Foo.getStrings() + val scalaSeq: mutable.Seq[String] = javaList.asScala + for (s <- scalaSeq) println(s) +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import scala.jdk.CollectionConverters.* +import scala.collection.mutable + +def testList() = + println("Using a Java List in Scala") + val javaList: java.util.List[String] = Foo.getStrings() + val scalaSeq: mutable.Seq[String] = javaList.asScala + for s <- scalaSeq do println(s) +``` + +{% endtab %} +{% endtabs %} + +В приведенном выше коде создается оболочка `javaList.asScala`, +которая адаптирует `java.util.List` к коллекции Scala `mutable.Seq`. + +## Как использовать Java `Optional` в Scala + +Когда вы взаимодействуете с API, который использует класс `java.util.Optional` в коде Scala, +его можно создавать и использовать, как в Java. + +Однако для идиоматического использования в Scala, например использования в `for`, +вы можете преобразовать его в Scala `Option`. + +Чтобы продемонстрировать это, вот Java API, который возвращает значение типа `Optional[String]`: + +{% tabs bar-definition %} +{% tab Java %} + +```java +public interface Bar { + static java.util.Optional optionalString() { + return Optional.of("hello"); + } +} +``` + +{% endtab %} +{% endtabs %} + +Сначала импортируйте всё из объекта `scala.jdk.OptionConverters`, +а затем используйте метод `toScala` для преобразования `Optional` значения в Scala `Option`: + +{% tabs bar-usage class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import java.util.Optional +import scala.jdk.OptionConverters._ + +val javaOptString: Optional[String] = Bar.optionalString +val scalaOptString: Option[String] = javaOptString.toScala +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import java.util.Optional +import scala.jdk.OptionConverters.* + +val javaOptString: Optional[String] = Bar.optionalString +val scalaOptString: Option[String] = javaOptString.toScala +``` + +{% endtab %} +{% endtabs %} + +## Расширение Java интерфейсов в Scala + +Если вам нужно использовать Java интерфейсы в коде Scala, расширяйте их так, как если бы они были трейтами Scala. +Например, учитывая эти три Java интерфейса: + +{% tabs animal-definition %} +{% tab Java %} + +```java +public interface Animal { + void speak(); +} + +public interface Wagging { + void wag(); +} + +public interface Running { + // an implemented method + default void run() { + System.out.println("I’m running"); + } +} +``` + +{% endtab %} +{% endtabs %} + +вы можете создать класс `Dog` в Scala так же, как если бы вы использовали трейты. +Поскольку у `run` есть реализация по умолчанию, вам нужно реализовать только методы `speak` и `wag`: + +{% tabs animal-usage class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Dog extends Animal with Wagging with Running { + def speak = println("Woof") + def wag = println("Tail is wagging") +} + +def useJavaInterfaceInScala = { + val d = new Dog() + d.speak + d.wag + d.run +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Dog extends Animal, Wagging, Running: + def speak = println("Woof") + def wag = println("Tail is wagging") + +def useJavaInterfaceInScala = + val d = Dog() + d.speak + d.wag + d.run +``` + +{% endtab %} +{% endtabs %} + +Также обратите внимание, что в Scala методы Java, определенные с пустыми списками параметров, +можно вызывать либо так же, как в Java, `.wag()`, +либо вы можете отказаться от использования круглых скобок `.wag`. + +## Как использовать коллекции Scala в Java + +Если вам нужно использовать класс коллекции Scala в своем Java-коде, +используйте методы Scala объекта `scala.jdk.javaapi.CollectionConverters` в своем Java-коде, +для корректной работы конверсии. + +Например, предположим, что Scala API возвращает `List[String]`, как следующем примере: + +{% tabs baz-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object Baz { + val strings: List[String] = List("a", "b", "c") +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object Baz: + val strings: List[String] = List("a", "b", "c") +``` + +{% endtab %} +{% endtabs %} + +Вы можете получить доступ к Scala `List` в Java-коде следующим образом: + +{% tabs baz-usage %} +{% tab Java %} + +```java +import scala.jdk.javaapi.CollectionConverters; + +// получить доступ к методу `strings` с помощью `Baz.strings()` +scala.collection.immutable.List xs = Baz.strings(); + +java.util.List listOfStrings = CollectionConverters.asJava(xs); + +for (String s: listOfStrings) { + System.out.println(s); +} +``` + +{% endtab %} +{% endtabs %} + +Этот код можно сократить, но показаны полные шаги, чтобы продемонстрировать, как работает процесс. +Обязательно обратите внимание, что хотя `Baz` имеет поле с именем `strings`, +в Java оно отображается как метод, поэтому его следует вызывать в круглых скобках `.strings()`. + +## Как использовать Scala `Option` в Java + +Если вам нужно использовать Scala `Option` в коде Java, +вы можете преобразовать значение `Option` в значение Java `Optional`, +используя метод `toJava` объекта Scala `scala.jdk.javaapi.OptionConverters`. + +Например, предположим, что Scala API возвращает `Option[String]`, как следующем примере: + +{% tabs qux-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object Qux { + val optString: Option[String] = Option("hello") +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object Qux: + val optString: Option[String] = Option("hello") +``` + +{% endtab %} +{% endtabs %} + +Затем вы можете получить доступ к Scala `Option` в своем Java-коде следующим образом: + +{% tabs qux-usage %} +{% tab Java %} + +```java +import java.util.Optional; +import scala.Option; +import scala.jdk.javaapi.OptionConverters; + +Option scalaOptString = Qux.optString(); +Optional javaOptString = OptionConverters.toJava(scalaOptString); +``` + +{% endtab %} +{% endtabs %} + +Этот код можно сократить, но показаны полные шаги, чтобы продемонстрировать, как работает процесс. +Обязательно обратите внимание, что хотя `Qux` имеет поле с именем `optString`, +в Java оно отображается как метод, поэтому его следует вызывать в круглых скобках `.optString()`. + +## Как использовать трейты Scala в Java + +Начиная с Java 8, вы можете использовать трейт Scala точно так же, как Java интерфейс, +даже если этот трейт реализует методы. +Например, учитывая эти два трейта Scala, один с реализованным методом, а другой только с интерфейсом: + +{% tabs scala-trait-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait ScalaAddTrait { + def sum(x: Int, y: Int) = x + y // реализован +} + +trait ScalaMultiplyTrait { + def multiply(x: Int, y: Int): Int // абстрактный +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait ScalaAddTrait: + def sum(x: Int, y: Int) = x + y // реализован + +trait ScalaMultiplyTrait: + def multiply(x: Int, y: Int): Int // абстрактный +``` + +{% endtab %} +{% endtabs %} + +Класс Java может реализовать оба этих интерфейса и определить метод `multiply`: + +{% tabs scala-trait-usage %} +{% tab Java %} + +```java +class JavaMath implements ScalaAddTrait, ScalaMultiplyTrait { + public int multiply(int a, int b) { + return a * b; + } +} + +JavaMath jm = new JavaMath(); +System.out.println(jm.sum(3,4)); // 7 +System.out.println(jm.multiply(3,4)); // 12 +``` + +{% endtab %} +{% endtabs %} + +## Как обрабатывать методы Scala, которые вызывают исключения в коде Java + +Когда вы пишете код на Scala, используя идиомы программирования Scala, +вы никогда не напишете метод, который генерирует исключение. +Но если по какой-то причине у вас есть метод Scala, который генерирует исключение, +и вы хотите, чтобы разработчики Java могли использовать этот метод, +добавьте аннотацию `@throws` к вашему методу Scala, +чтобы Java потребители знали, какие исключения он может генерировать. + +Например, следующий Scala метод `exceptionThrower` аннотирован, чтобы объявить, что он выдает `Exception`: + +{% tabs except-throw-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object SExceptionThrower { + @throws[Exception] + def exceptionThrower = + throw new Exception("Idiomatic Scala methods don’t throw exceptions") +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object SExceptionThrower: + @throws[Exception] + def exceptionThrower = + throw Exception("Idiomatic Scala methods don’t throw exceptions") +``` + +{% endtab %} +{% endtabs %} + +В результате вам придется обрабатывать исключение в своем Java-коде. +Например, этот код не скомпилируется из-за необработанного исключения: + +{% tabs except-throw-usage %} +{% tab Java %} + +```java +// не скомпилируется, потому что исключение не обработано +public class ScalaExceptionsInJava { + public static void main(String[] args) { + SExceptionThrower.exceptionThrower(); + } +} +``` + +{% endtab %} +{% endtabs %} + +Компилятор выдает следующую ошибку: + +```plain +[error] ScalaExceptionsInJava: unreported exception java.lang.Exception; + must be caught or declared to be thrown +[error] SExceptionThrower.exceptionThrower() +``` + +Хорошо — это то, что вы хотите: аннотация сообщает компилятору Java, что `exceptionThrower` может выдать исключение. +Теперь, когда вы пишете код на Java, вы должны обрабатывать исключение с помощью блока `try` +или объявлять, что ваш Java метод генерирует исключение. + +И наоборот, если вы укажите аннотацию Scala метода `exceptionThrower`, код Java _будет скомпилирован_. +Вероятно, это не то, что вам нужно, поскольку Java код может не учитывать метод Scala, выдающий исключение. + +## Как использовать vararg-параметры Scala в Java + +Если метод Scala имеет неопределенное количество параметров и вы хотите использовать этот метод в Java, +отметьте Scala метод аннотацией `@varargs`. +Например, метод `printAll` в этом Scala классе объявляет vararg-поле `String*`: + +{% tabs vararg-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.annotation.varargs + +object VarargsPrinter { + @varargs def printAll(args: String*): Unit = args.foreach(println) +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import scala.annotation.varargs + +object VarargsPrinter: + @varargs def printAll(args: String*): Unit = args.foreach(println) +``` + +{% endtab %} +{% endtabs %} + +Поскольку `printAll` объявлен с аннотацией `@varargs`, его можно вызвать из Java программы +с переменным количеством параметров, как показано в этом примере: + +{% tabs vararg-usage %} +{% tab Java %} + +```java +public class JVarargs { + public static void main(String[] args) { + VarargsPrinter.printAll("Hello", "world"); + } +} +``` + +{% endtab %} +{% endtabs %} + +Запуск кода приводит к следующему выводу: + +```plain +Hello +world +``` + +## Создание альтернативных имен для использования методов Scala в Java + +В Scala вы можете создать имя метода, используя символический знак: + +{% tabs add-definition %} +{% tab 'Scala 2 и 3' %} + +```scala +def +(a: Int, b: Int) = a + b +``` + +{% endtab %} +{% endtabs %} + +Такое имя метода корректно работать в Java не будет, +но в Scala вы можете предоставить "альтернативное" имя метода с аннотацией `targetName`, +которая будет именем метода при использовании из Java: + +{% tabs add-2-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.annotation.targetName + +object Adder { + @targetName("add") def +(a: Int, b: Int) = a + b +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import scala.annotation.targetName + +object Adder: + @targetName("add") def +(a: Int, b: Int) = a + b +``` + +{% endtab %} +{% endtabs %} + +Теперь в вашем Java-коде вы можете использовать псевдоним метода `add`: + +{% tabs add-2-usage %} +{% tab Java %} + +```java +int x = Adder.add(1,1); +System.out.printf("x = %d\n", x); +``` + +{% endtab %} +{% endtabs %} diff --git a/_ru/scala3/book/introduction.md b/_ru/scala3/book/introduction.md new file mode 100644 index 0000000000..ae23a36516 --- /dev/null +++ b/_ru/scala3/book/introduction.md @@ -0,0 +1,38 @@ +--- +layout: multipage-overview +title: Введение +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице начинается обзорная документация по языку Scala 3. +language: ru +num: 1 +previous-page: +next-page: scala-features +--- + +Добро пожаловать в книгу по Scala 3. +Цель этой книги — предоставить неформальное введение в язык Scala. +Она относительно легко затрагивает все темы Scala. +Если в какой-то момент во время чтения этой книги вы захотите получить дополнительную информацию о конкретной функции, +можете воспользоваться ссылкой на нашу [Справочную документацию][reference], +в которой более подробно рассматриваются многие новые функции языка Scala. + +
            +  Если вас интересует заархивированное издание книги для Scala 2, +доступ к нему можно получить здесь. +В настоящее время мы находимся в процессе слияния двух книг, и вы можете нам помочь. +
            + +В этой книге мы надеемся продемонстрировать, что Scala — это красивый, выразительный язык программирования с чистым современным синтаксисом, +который поддерживает и функциональное программирование (ФП), и объектно-ориентированное программирование (ООП), +а также обеспечивает безопасную статическую систему типов. +Синтаксис, грамматика и функции Scala были переосмыслены, открыто обсуждались и были обновлены в 2020 году, +чтобы стать яснее и проще для понимания, чем когда-либо прежде. + +Книга начинается с беглого обзора возможностей Scala в [разделе “Почувствуй Scala”][taste]. +После этого обзора в следующих разделах содержится более подробная информация о рассмотренных языковых функциях. + +[reference]: {{ site.scala3ref }}/overview.html +[taste]: {% link _overviews/scala3-book/taste-intro.md %} diff --git a/_ru/scala3/book/methods-intro.md b/_ru/scala3/book/methods-intro.md new file mode 100644 index 0000000000..de34fc1166 --- /dev/null +++ b/_ru/scala3/book/methods-intro.md @@ -0,0 +1,22 @@ +--- +layout: multipage-overview +title: Методы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе представлены методы в Scala 3. +language: ru +num: 24 +previous-page: domain-modeling-fp +next-page: methods-most +--- + + +В Scala 2 _методы_ могут быть определены внутри классов, трейтов, объектов, `case` классов и `case` объектов. +Но стало еще лучше: в Scala 3 они также могут быть определены вне любой из этих конструкций; +мы говорим, что это определения "верхнего уровня", поскольку они не вложены в другое определение. +Короче говоря, теперь методы можно определять где угодно. + +Многие особенности методов демонстрируются в следующем разделе. +Поскольку `main` методы требуют немного больше пояснений, они описаны в одном из следующих разделов отдельно. diff --git a/_ru/scala3/book/methods-main-methods.md b/_ru/scala3/book/methods-main-methods.md new file mode 100644 index 0000000000..cd6342216a --- /dev/null +++ b/_ru/scala3/book/methods-main-methods.md @@ -0,0 +1,205 @@ +--- +layout: multipage-overview +title: Main методы в Scala 3 +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице описывается, как основные методы и аннотация @main работают в Scala 3. +language: ru +num: 26 +previous-page: methods-most +next-page: methods-summary +--- + +
            Написание однострочных программ только в Scala 3
            + +Scala 3 предлагает следующий способ определения программ, которые можно вызывать из командной строки: +добавление аннотации `@main` к методу превращает его в точку входа исполняемой программы: + +{% tabs method_1 %} +{% tab 'Только в Scala 3' for=method_1 %} + +```scala +@main def hello() = println("Hello, World") +``` + +{% endtab %} +{% endtabs %} + +Для запуска программы достаточно сохранить эту строку кода в файле с именем, например, _Hello.scala_ +(имя файла необязательно должно совпадать с именем метода) и запустить с помощью `scala`: + +```bash +$ scala Hello.scala +Hello, World +``` + +Аннотированный метод `@main` может быть написан либо на верхнем уровне (как показано), +либо внутри статически доступного объекта. +В любом случае имя программы - это имя метода без каких-либо префиксов объектов. + +Узнайте больше об аннотации `@main`, прочитав следующие разделы или посмотрев это видео: + +
            + +
            + +### Аргументы командной строки + +Метод `@main` может обрабатывать аргументы командной строки с различными типами. +Например, данный метод `@main`, который принимает параметры `Int`, `String` и дополнительные строковые параметры: + +{% tabs method_2 %} +{% tab 'Только в Scala 3' for=method_2 %} + +```scala +@main def happyBirthday(age: Int, name: String, others: String*) = + val suffix = (age % 100) match + case 11 | 12 | 13 => "th" + case _ => (age % 10) match + case 1 => "st" + case 2 => "nd" + case 3 => "rd" + case _ => "th" + + val sb = StringBuilder(s"Happy $age$suffix birthday, $name") + for other <- others do sb.append(" and ").append(other) + println(sb.toString) +``` + +{% endtab %} +{% endtabs %} + +После компиляции кода создается основная программа с именем `happyBirthday`, которая вызывается следующим образом: + +``` +$ scala happyBirthday 23 Lisa Peter +Happy 23rd Birthday, Lisa and Peter! +``` + +Как показано, метод `@main` может иметь произвольное количество параметров. +Для каждого типа параметра должен существовать [given экземпляр][given] +класса типа `scala.util.CommandLineParser.FromString`, который преобразует аргумент из `String` в требуемый тип параметра. +Также, как показано, список параметров основного метода может заканчиваться повторяющимся параметром типа `String*`, +который принимает все оставшиеся аргументы, указанные в командной строке. + +Программа, реализованная с помощью метода `@main`, проверяет, +что в командной строке достаточно аргументов для заполнения всех параметров, +и что строки аргументов могут быть преобразованы в требуемые типы. +Если проверка завершается неудачей, программа завершается с сообщением об ошибке: + +``` +$ scala happyBirthday 22 +Illegal command line after first argument: more arguments expected + +$ scala happyBirthday sixty Fred +Illegal command line: java.lang.NumberFormatException: For input string: "sixty" +``` + +## Пользовательские типы как параметры + +Как упоминалось выше, компилятор ищет заданный экземпляр класса типов `scala.util.CommandLineParser.FromString` +для типа аргумента. Например, предположим, что у вас есть собственный тип `Color`, +который вы хотите использовать в качестве параметра. +Вы можете сделать это, как показано ниже: + +{% tabs method_3 %} +{% tab 'Только в Scala 3' for=method_3 %} + +```scala +enum Color: + case Red, Green, Blue + +given ComamndLineParser.FromString[Color] with + def fromString(value: String): Color = Color.valueOf(value) + +@main def run(color: Color): Unit = + println(s"The color is ${color.toString}") +``` + +{% endtab %} +{% endtabs %} + +Это работает одинаково для ваших собственных пользовательских типов в вашей программе, +а также для типов, которые можно использовать из другой библиотеки. + +## Детали + +Компилятор Scala генерирует программу из `@main` метода `f` следующим образом: + +- он создает класс с именем `f` в пакете, где был найден метод `@main`. +- класс имеет статический метод `main` с обычной сигнатурой Java `main` метода: + принимает `Array[String]` в качестве аргумента и возвращает `Unit`. +- сгенерированный `main` метод вызывает метод `f` с аргументами, + преобразованными с помощью методов в объекте `scala.util.CommandLineParser.FromString`. + +Например, приведенный выше метод `happyBirthday` генерирует дополнительный код, эквивалентный следующему классу: + +{% tabs method_4 %} +{% tab 'Только в Scala 3' for=method_4 %} + +```scala +final class happyBirthday { + import scala.util.{CommandLineParser as CLP} + def main(args: Array[String]): Unit = + try + happyBirthday( + CLP.parseArgument[Int](args, 0), + CLP.parseArgument[String](args, 1), + CLP.parseRemainingArguments[String](args, 2)*) + catch { + case error: CLP.ParseError => CLP.showError(error) + } +} +``` + +> Примечание: В этом сгенерированном коде модификатор `` выражает, +> что `main` метод генерируется как статический метод класса `happyBirthday`. +> Эта функция недоступна для пользовательских программ в Scala. +> Вместо неё обычные “статические” члены генерируются в Scala с использованием `object`. + +{% endtab %} +{% endtabs %} + +## Обратная совместимость со Scala 2 + +`@main` методы — это рекомендуемый способ создания программ, вызываемых из командной строки в Scala 3. +Они заменяют предыдущий подход, который заключался в создании `object`, расширяющего класс `App`: + +Прежняя функциональность `App`, основанная на "волшебном" `DelayedInit trait`, больше недоступна. +`App` все еще существует в ограниченной форме, но не поддерживает аргументы командной строки и будет объявлен устаревшим в будущем. + +Если программам необходимо выполнять перекрестную сборку между Scala 2 и Scala 3, +вместо этого рекомендуется использовать `object` с явным методом `main` и одним аргументом `Array[String]`: + +{% tabs method_5 %} +{% tab 'Scala 2 и 3' %} + +```scala +object happyBirthday { + private def happyBirthday(age: Int, name: String, others: String*) = { + ... // тоже, что и раньше + } + def main(args: Array[String]): Unit = + happyBirthday(args(0).toInt, args(1), args.drop(2).toIndexedSeq:_*) +} +``` + +> обратите внимание, что здесь мы используем `:_*` для передачи переменного числа аргументов, +> который остается в Scala 3 для обратной совместимости. + +{% endtab %} +{% endtabs %} + +Если вы поместите этот код в файл с именем _happyBirthday.scala_, то сможете скомпилировать его с `scalac` +и запустить с помощью `scala`, как показывалось ранее: + +```bash +$ scalac happyBirthday.scala + +$ scala happyBirthday 23 Lisa Peter +Happy 23rd Birthday, Lisa and Peter! +``` + +[given]: {% link _overviews/scala3-book/ca-context-parameters.md %} diff --git a/_ru/scala3/book/methods-most.md b/_ru/scala3/book/methods-most.md new file mode 100644 index 0000000000..b3d8f6ed81 --- /dev/null +++ b/_ru/scala3/book/methods-most.md @@ -0,0 +1,712 @@ +--- +layout: multipage-overview +title: Особенности методов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены методы Scala 3, включая main методы, методы расширения и многое другое. +language: ru +num: 25 +previous-page: methods-intro +next-page: methods-main-methods +--- + +В этом разделе представлены различные аспекты определения и вызова методов в Scala 3. + +## Определение методов + +В Scala методы обладают множеством особенностей, в том числе: + +- Generic (типовые) параметры +- Значения параметров по умолчанию +- Несколько групп параметров +- Контекстные параметры +- Параметры по имени +- и другие… + +Некоторые из этих функций демонстрируются в этом разделе, но когда вы определяете “простой” метод, +который не использует эти функции, синтаксис выглядит следующим образом: + +{% tabs method_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_1 %} + +```scala +def methodName(param1: Type1, param2: Type2): ReturnType = { + // тело метода + // находится здесь +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_1 %} + +```scala +def methodName(param1: Type1, param2: Type2): ReturnType = + // тело метода + // находится здесь +end methodName // опционально +``` + +{% endtab %} +{% endtabs %} + +В этом синтаксисе: + +- ключевое слово `def` используется для определения метода +- для наименования методов согласно стандартам Scala используется camel case convention +- у параметров метода необходимо всегда указывать тип +- возвращаемый тип метода указывать необязательно +- методы могут состоять как только из одной строки, так и из нескольких строк +- метку окончания метода `end methodName` указывать необязательно, её рекомендуется указывать только для длинных методов + +Вот два примера однострочного метода с именем `add`, который принимает два входных параметра `Int`. +Первая версия явно показывает возвращаемый тип метода - `Int`, а вторая - нет: + +{% tabs method_2 %} +{% tab 'Scala 2 и 3' for=method_2 %} + +```scala +def add(a: Int, b: Int): Int = a + b +def add(a: Int, b: Int) = a + b +``` + +{% endtab %} +{% endtabs %} + +У публичных методов рекомендуется всегда указывать тип возвращаемого значения. +Объявление возвращаемого типа может упростить его понимание при просмотре кода другого человека +или своего кода спустя некоторое время. + +## Вызов методов + +Вызов методов прост: + +{% tabs method_3 %} +{% tab 'Scala 2 и 3' for=method_3 %} + +```scala +val x = add(1, 2) // 3 +``` + +{% endtab %} +{% endtabs %} + +Коллекции Scala имеют десятки встроенных методов. +Эти примеры показывают, как их вызывать: + +{% tabs method_4 %} +{% tab 'Scala 2 и 3' for=method_4 %} + +```scala +val x = List(1, 2, 3) + +x.size // 3 +x.contains(1) // true +x.map(_ * 10) // List(10, 20, 30) +``` + +{% endtab %} +{% endtabs %} + +Внимание: + +- `size` не принимает аргументов и возвращает количество элементов в списке +- метод `contains` принимает один аргумент — значение для поиска +- `map` принимает один аргумент - функцию; в данном случае в него передается анонимная функция + +## Многострочные методы + +Если метод длиннее одной строки, начинайте тело метода со второй строки с отступом вправо: + +{% tabs method_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_5 %} + +```scala +def addThenDouble(a: Int, b: Int): Int = { + // представим, что это тело метода требует несколько строк + val sum = a + b + sum * 2 +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_5 %} + +```scala +def addThenDouble(a: Int, b: Int): Int = + // представим, что это тело метода требует несколько строк + val sum = a + b + sum * 2 +``` + +{% endtab %} +{% endtabs %} + +В этом методе: + +- `sum` — неизменяемая локальная переменная; к ней нельзя получить доступ вне метода +- последняя строка удваивает значение `sum` - именно это значение возвращается из метода + +Когда вы вставите этот код в REPL, то увидите, что он работает как требовалось: + +{% tabs method_6 %} +{% tab 'Scala 2 и 3' for=method_6 %} + +```scala +scala> addThenDouble(1, 1) +res0: Int = 4 +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что нет необходимости в операторе `return` в конце метода. +Поскольку почти все в Scala является _выражением_ — то это означает, +что каждая строка кода возвращает (или _вычисляет_) значение — нет необходимости использовать `return`. + +Это видно на примере того же метода, но в более сжатой форме: + +{% tabs method_7 %} +{% tab 'Scala 2 и 3' for=method_7 %} + +```scala +def addThenDouble(a: Int, b: Int): Int = (a + b) * 2 +``` + +{% endtab %} +{% endtabs %} + +В теле метода можно использовать все возможности Scala: + +- `if`/`else` выражения +- `match` выражения +- циклы `while` +- циклы `for` и `for` выражения +- присвоение переменных +- вызовы других методов +- определения других методов + +В качестве ещё одного примера многострочного метода, +`getStackTraceAsString` преобразует свой входной параметр `Throwable` в правильно отформатированную строку: + +{% tabs method_8 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_8 %} + +```scala +def getStackTraceAsString(t: Throwable): String = { + val sw = new StringWriter() + t.printStackTrace(new PrintWriter(sw)) + sw.toString +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_8 %} + +```scala +def getStackTraceAsString(t: Throwable): String = + val sw = StringWriter() + t.printStackTrace(PrintWriter(sw)) + sw.toString +``` + +{% endtab %} +{% endtabs %} + +В этом методе: + +- в первой строке переменная `sw` принимает значение нового экземпляра `StringWriter` +- вторая строка сохраняет содержимое трассировки стека в `StringWriter` +- третья строка возвращает строковое представление трассировки стека + +## Значения параметров по умолчанию + +Параметры метода могут иметь значения по умолчанию. +В этом примере для параметров `timeout` и `protocol` заданы значения по умолчанию: + +{% tabs method_9 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_9 %} + +```scala +def makeConnection(timeout: Int = 5_000, protocol: String = "http") = { + println(f"timeout = ${timeout}%d, protocol = ${protocol}%s") + // здесь ещё какой-то код ... +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_9 %} + +```scala +def makeConnection(timeout: Int = 5_000, protocol: String = "http") = + println(f"timeout = ${timeout}%d, protocol = ${protocol}%s") + // здесь ещё какой-то код ... +``` + +{% endtab %} +{% endtabs %} + +Поскольку параметры имеют значения по умолчанию, метод можно вызвать следующими способами: + +{% tabs method_10 %} +{% tab 'Scala 2 и 3' for=method_10 %} + +```scala +makeConnection() // timeout = 5000, protocol = http +makeConnection(2_000) // timeout = 2000, protocol = http +makeConnection(3_000, "https") // timeout = 3000, protocol = https +``` + +{% endtab %} +{% endtabs %} + +Вот несколько ключевых моментов об этих примерах: + +- В первом примере аргументы не предоставляются, поэтому метод использует значения параметров по умолчанию: `5_000` и `http` +- Во втором примере для параметра `timeout` указывается значение `2_000`, + поэтому оно используется вместе со значением по умолчанию для `protocol` +- В третьем примере значения указаны для обоих параметров, поэтому используются они. + +Обратите внимание, что при использовании значений параметров по умолчанию потребителю кажется, +что он может работать с тремя разными переопределенными методами. + +## Именованные параметры + +При желании вы также можете использовать имена параметров метода при его вызове. +Например, `makeConnection` может также вызываться следующими способами: + +{% tabs method_11 %} +{% tab 'Scala 2 и 3' for=method_11 %} + +```scala +makeConnection(timeout=10_000) +makeConnection(protocol="https") +makeConnection(timeout=10_000, protocol="https") +makeConnection(protocol="https", timeout=10_000) +``` + +{% endtab %} +{% endtabs %} + +В некоторых фреймворках именованные параметры используются постоянно. +Они также очень полезны, когда несколько параметров метода имеют один и тот же тип: + +{% tabs method_12 %} +{% tab 'Scala 2 и 3' for=method_12 %} + +```scala +engage(true, true, true, false) +``` + +{% endtab %} +{% endtabs %} + +Без помощи IDE этот код может быть трудночитаемым, но так он становится намного понятнее и очевиднее: + +{% tabs method_13 %} +{% tab 'Scala 2 и 3' for=method_13 %} + +```scala +engage( + speedIsSet = true, + directionIsSet = true, + picardSaidMakeItSo = true, + turnedOffParkingBrake = false +) +``` + +{% endtab %} +{% endtabs %} + +## Рекомендации о методах, которые не принимают параметров + +Когда метод не принимает параметров, говорят, что он имеет _arity_ уровень 0 (_arity-0_). +Аналогично, если метод принимает один параметр - это метод с _arity-1_. + +Когда создаются методы _arity-0_: + +- если метод выполняет побочные эффекты, такие как вызов `println`, метод объявляется с пустыми скобками. +- если метод не выполняет побочных эффектов, например, получение размера коллекции, + что аналогично доступу к полю в коллекции, круглые скобки опускаются. + +Например, этот метод выполняет побочный эффект, поэтому он объявлен с пустыми скобками: + +{% tabs method_14 %} +{% tab 'Scala 2 и 3' for=method_14 %} + +```scala +def speak() = println("hi") +``` + +{% endtab %} +{% endtabs %} + +При вызове метода нужно обязательно указывать круглые скобки, если он был объявлен с ними: + +{% tabs method_15 %} +{% tab 'Scala 2 и 3' for=method_15 %} + +```scala +speak // ошибка: "method speak must be called with () argument" +speak() // печатает "hi" +``` + +{% endtab %} +{% endtabs %} + +Хотя это всего лишь соглашение, его соблюдение значительно улучшает читаемость кода: +с первого взгляда становится понятно, что метод с arity-0 имеет побочные эффекты. + +## Использование `if` в качестве тела метода + +Поскольку выражения `if`/`else` возвращают значение, их можно использовать в качестве тела метода. +Вот метод с именем `isTruthy`, реализующий Perl-определения `true` и `false`: + +{% tabs method_16 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_16 %} + +```scala +def isTruthy(a: Any) = { + if (a == 0 || a == "" || a == false) + false + else + true +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_16 %} + +```scala +def isTruthy(a: Any) = + if a == 0 || a == "" || a == false then + false + else + true +``` + +{% endtab %} +{% endtabs %} + +Примеры показывают, как работает метод: + +{% tabs method_17 %} +{% tab 'Scala 2 и 3' for=method_17 %} + +```scala +isTruthy(0) // false +isTruthy("") // false +isTruthy("hi") // true +isTruthy(1.0) // true +``` + +{% endtab %} +{% endtabs %} + +## Использование `match` в качестве тела метода + +Довольно часто в качестве тела метода используются `match`-выражения. +Вот еще одна версия `isTruthy`, написанная с `match` выражением: + +{% tabs method_18 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_18 %} + +```scala +def isTruthy(a: Any) = a match { + case 0 | "" | false => false + case _ => true +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_18 %} + +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" | false => false + case _ => true +``` + +> Этот метод работает точно так же, как и предыдущий, в котором использовалось выражение `if`/`else`. +> Вместо `Any` в качестве типа параметра используется `Matchable`, чтобы принять любое значение, +> поддерживающее сопоставление с образцом (pattern matching). + +> См. дополнительную информацию о trait `Matchable` в [Справочной документации][reference_matchable]. + +[reference_matchable]: {{ site.scala3ref }}/other-new-features/matchable.html +{% endtab %} +{% endtabs %} + +## Контроль видимости методов в классах + +В классах, объектах, trait-ах и enum-ах методы Scala по умолчанию общедоступны, +поэтому созданный здесь экземпляр `Dog` может получить доступ к методу `speak`: + +{% tabs method_19 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_19 %} + +```scala +class Dog { + def speak() = println("Woof") +} + +val d = new Dog +d.speak() // печатает "Woof" +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_19 %} + +```scala +class Dog: + def speak() = println("Woof") + +val d = new Dog +d.speak() // печатает "Woof" +``` + +{% endtab %} +{% endtabs %} + +Также методы можно помечать как `private`. +Это делает их закрытыми в текущем классе, поэтому их нельзя вызвать или переопределить в подклассах: + +{% tabs method_20 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_20 %} +```scala +class Animal { + private def breathe() = println("I’m breathing") +} + +class Cat extends Animal { + // этот метод не скомпилируется + override def breathe() = println("Yo, I’m totally breathing") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_20 %} + +```scala +class Animal: + private def breathe() = println("I’m breathing") + +class Cat extends Animal: + // этот метод не скомпилируется + override def breathe() = println("Yo, I’m totally breathing") +``` + +{% endtab %} +{% endtabs %} + +Если необходимо сделать метод закрытым в текущем классе, но разрешить подклассам вызывать или переопределять его, +метод помечается как `protected`, как показано в примере с методом `speak`: + +{% tabs method_21 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_21 %} + +```scala +class Animal { + private def breathe() = println("I’m breathing") + def walk() = { + breathe() + println("I’m walking") + } + protected def speak() = println("Hello?") +} + +class Cat extends Animal { + override def speak() = println("Meow") +} + +val cat = new Cat +cat.walk() +cat.speak() +cat.breathe() // не скомпилируется, потому что private +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_21 %} + +```scala +class Animal: + private def breathe() = println("I’m breathing") + def walk() = + breathe() + println("I’m walking") + protected def speak() = println("Hello?") + +class Cat extends Animal: + override def speak() = println("Meow") + +val cat = new Cat +cat.walk() +cat.speak() +cat.breathe() // не скомпилируется, потому что private +``` + +{% endtab %} +{% endtabs %} + +Настройка `protected` означает: + +- к методу (или полю) могут обращаться другие экземпляры того же класса +- метод (или поле) не виден в текущем пакете +- он доступен для подклассов + +## Методы в объектах + +Ранее было показано, что trait-ы и классы могут иметь методы. +Ключевое слово `object` используется для создания одноэлементного класса, и объект также может содержать методы. +Это хороший способ сгруппировать набор “служебных” методов. +Например, этот объект содержит набор методов, которые работают со строками: + +{% tabs method_22 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_22 %} + +```scala +object StringUtils { + + /** + * Returns a string that is the same as the input string, but + * truncated to the specified length. + */ + def truncate(s: String, length: Int): String = s.take(length) + + /** + * Returns true if the string contains only letters and numbers. + */ + def lettersAndNumbersOnly_?(s: String): Boolean = + s.matches("[a-zA-Z0-9]+") + + /** + * Returns true if the given string contains any whitespace + * at all. Assumes that `s` is not null. + */ + def containsWhitespace(s: String): Boolean = + s.matches(".*\\s.*") + +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=method_22 %} + +```scala +object StringUtils: + + /** + * Returns a string that is the same as the input string, but + * truncated to the specified length. + */ + def truncate(s: String, length: Int): String = s.take(length) + + /** + * Returns true if the string contains only letters and numbers. + */ + def lettersAndNumbersOnly_?(s: String): Boolean = + s.matches("[a-zA-Z0-9]+") + + /** + * Returns true if the given string contains any whitespace + * at all. Assumes that `s` is not null. + */ + def containsWhitespace(s: String): Boolean = + s.matches(".*\\s.*") + +end StringUtils +``` + +{% endtab %} +{% endtabs %} + +## Методы расширения + +Есть много ситуаций, когда необходимо добавить функциональность к закрытым классам. +Например, представьте, что у вас есть класс `Circle`, но вы не можете изменить его исходный код. +Это может быть определено в сторонней библиотеке так: + +{% tabs method_23 %} +{% tab 'Scala 2 и 3' for=method_23 %} + +```scala +case class Circle(x: Double, y: Double, radius: Double) +``` + +{% endtab %} +{% endtabs %} + +Если вы хотите добавить методы в этот класс, то можете определить их как методы расширения, например: + +{% tabs method_24 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_24 %} + +```scala +implicit class CircleOps(c: Circle) { + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +} +``` +В Scala 2 используйте `implicit class`, подробности [здесь](/overviews/core/implicit-classes.html). + +{% endtab %} +{% tab 'Scala 3' for=method_24 %} + +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` +В Scala 3 используйте новую конструкцию `extension`. +Дополнительные сведения см. [в главах этой книги][extension] или [в справочнике по Scala 3][reference-ext]. + +[reference-ext]: {{ site.scala3ref }}/contextual/extension-methods.html +[extension]: {% link _overviews/scala3-book/ca-extension-methods.md %} +{% endtab %} +{% endtabs %} + +Теперь, когда у вас есть экземпляр `Circle` с именем `aCircle`, +то вы можете вызывать эти методы следующим образом: + +{% tabs method_25 %} +{% tab 'Scala 2 и 3' for=method_25 %} + +```scala +aCircle.circumference +aCircle.diameter +aCircle.area +``` + +{% endtab %} +{% endtabs %} + +## Дальнейшее изучение + +Есть много чего, что можно узнать о методах, в том числе: + +- Вызов методов в суперклассах +- Определение и использование параметров по имени +- Написание метода, который принимает параметр функции +- Создание встроенных методов +- Обработка исключений +- Использование входных параметров vararg +- Написание методов с несколькими группами параметров (частично применяемые функции). +- Создание методов с параметрами универсального типа. + +Дополнительные сведения об этих функциях см. в других главах этой книги. + +[reference_extension_methods]: {{ site.scala3ref }}/contextual/extension-methods.html +[reference_matchable]: {{ site.scala3ref }}/other-new-features/matchable.html diff --git a/_ru/scala3/book/methods-summary.md b/_ru/scala3/book/methods-summary.md new file mode 100644 index 0000000000..029c4de687 --- /dev/null +++ b/_ru/scala3/book/methods-summary.md @@ -0,0 +1,30 @@ +--- +layout: multipage-overview +title: Обзор +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: Эта страница подводит итог предыдущим разделам о методах в Scala 3. +language: ru +num: 27 +previous-page: methods-main-methods +next-page: fun-intro +--- + + +Есть ещё много чего, что можно узнать о методах, в том числе: + +- Вызов методов в суперклассах +- Определение и использование параметров по имени +- Создание метода, который принимает функцию в качестве параметра +- Создание встроенных (_inline_) методов +- Обработка исключений +- Использование переменного числа входных параметров +- Создание методов с несколькими группами параметров (частично применяемые функции) +- Создание методов с параметрами универсального типа + +Дополнительные сведения об этих функциях доступны в [справочной документации][reference]. + + +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_ru/scala3/book/packaging-imports.md b/_ru/scala3/book/packaging-imports.md new file mode 100644 index 0000000000..49b5da759d --- /dev/null +++ b/_ru/scala3/book/packaging-imports.md @@ -0,0 +1,418 @@ +--- +layout: multipage-overview +title: Пакеты и импорт +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: Обсуждение использования пакетов и импорта для организации кода, создания связанных модулей кода, управления областью действия и предотвращения конфликтов пространств имен. +language: ru +num: 36 +previous-page: fun-summary +next-page: collections-intro +--- + + +Scala использует _packages_ для создания пространств имен, которые позволяют модульно разбивать программы. +Scala поддерживает стиль именования пакетов, используемый в Java, а также нотацию пространства имен “фигурные скобки”, +используемую такими языками, как C++ и C#. + +Подход Scala к импорту похож на Java, но более гибкий. +С помощью Scala можно: + +- импортировать пакеты, классы, объекты, trait-ы и методы +- размещать операторы импорта в любом месте +- скрывать и переименовывать участников при импорте + +Эти особенности демонстрируются в следующих примерах. + + +## Создание пакета + +Пакеты создаются путем объявления одного или нескольких имен пакетов в начале файла Scala. +Например, если ваше доменное имя _acme.com_ и вы работаете с пакетом _model_ приложения с именем _myapp_, +объявление пакета выглядит следующим образом: + +```scala +package com.acme.myapp.model + +class Person ... +``` + +По соглашению все имена пакетов должны быть строчными, +а формальным соглашением об именах является _\.\.\.\_. + +Хотя это и не обязательно, имена пакетов обычно совпадают с именами иерархии каталогов. +Поэтому, если следовать этому соглашению, класс `Person` в этом проекте будет найден +в файле _MyApp/src/main/scala/com/acme/myapp/model/Person.scala_. + + +### Использование нескольких пакетов в одном файле + +Показанный выше синтаксис применяется ко всему исходному файлу: +все определения в файле `Person.scala` принадлежат пакету `com.acme.myapp.model` +в соответствии с предложением `package` в начале файла. + +В качестве альтернативы можно написать `package`, которые применяются только к содержащимся в них определениям: + +```scala +package users: + + package administrators: // полное имя пакета - users.administrators + class AdminUser // полное имя класса - users.administrators.AdminUser + + package normalusers: // полное имя пакета - users.normalusers + class NormalUser // полное имя класса - users.normalusers.NormalUser +``` + +Обратите внимание, что за именами пакетов следует двоеточие, а определения внутри пакета имеют отступ. + +Преимущество этого подхода заключается в том, что он допускает вложение пакетов +и обеспечивает более очевидный контроль над областью видимости и инкапсуляцией, особенно в пределах одного файла. + + +## Операторы импорта + +Операторы импорта используются для доступа к сущностям в других пакетах. +Операторы импорта делятся на две основные категории: + +- импорт классов, трейтов, объектов, функций и методов +- импорт `given` предложений + +Первая категория операторов импорта аналогична тому, что использует Java, +с немного другим синтаксисом, обеспечивающим большую гибкость. +Пример: + +```` +import users.* // импортируется все из пакета `users` +import users.User // импортируется только класс `User` +import users.{User, UserPreferences} // импортируются только два члена пакета +import users.{UserPreferences as UPrefs} // переименование импортированного члена +```` + +Эти примеры предназначены для того, чтобы дать представление о том, как работает первая категория операторов `import`. +Более подробно они объясняются в следующих подразделах. + +Операторы импорта также используются для импорта `given` экземпляров в область видимости. +Они обсуждаются в конце этой главы. + +> import не требуется для доступа к членам одного и того же пакета. + + +### Импорт одного или нескольких членов + +В Scala импортировать один элемент из пакета можно следующим образом: + +```scala +import scala.concurrent.Future +``` + +несколько: + +```scala +import scala.concurrent.Future +import scala.concurrent.Promise +import scala.concurrent.blocking +``` + +При импорте нескольких элементов их можно импортировать более лаконично: + +```scala +import scala.concurrent.{Future, Promise, blocking} +``` + +Если необходимо импортировать все из пакета _scala.concurrent_, используется такой синтаксис: + +```scala +import scala.concurrent.* +``` + + +### Переименование элементов при импорте + +Иногда необходимо переименовать объекты при их импорте, чтобы избежать конфликтов имен. +Например, если нужно использовать Scala класс `List` вместе с `java.util.List`, +то можно переименовать `java.util.List` при импорте: + +```scala +import java.util.{List as JavaList} +``` + +Теперь имя `JavaList` можно использовать для ссылки на класс `java.util.List` +и использовать `List` для ссылки на Scala класс `List`. + +Также можно переименовывать несколько элементов одновременно, используя следующий синтаксис: + +```scala +import java.util.{Date as JDate, HashMap as JHashMap, *} +``` + +В этой строке кода говорится следующее: “Переименуйте классы `Date` и `HashMap`, как показано, +и импортируйте все остальное из пакета `java.util`, не переименовывая”. + + +### Скрытие членов при импорте + +При импорте часть объектов можно _скрывать_. +Следующий оператор импорта скрывает класс `java.util.Random`, +в то время как все остальное в пакете `java.util` импортируется: + +```scala +import java.util.{Random as _, *} +``` + +Если попытаться получить доступ к классу `Random`, то выдается ошибка, +но есть доступ ко всем остальным членам пакета `java.util`: + +```scala +val r = new Random // не скомпилируется +new ArrayList // доступ есть +``` + +#### Скрытие нескольких элементов + +Чтобы скрыть в import несколько элементов, их можно перечислить перед использованием постановочного знака: + +```scala +scala> import java.util.{List as _, Map as _, Set as _, *} +``` + +Перечисленные классы скрыты, но можно использовать все остальное в _java.util_: + +```scala +scala> new ArrayList[String] +val res0: java.util.ArrayList[String] = [] +``` + +Поскольку эти Java классы скрыты, можно использовать классы Scala `List`, `Set` и `Map` без конфликта имен: + +```scala +scala> val a = List(1, 2, 3) +val a: List[Int] = List(1, 2, 3) + +scala> val b = Set(1, 2, 3) +val b: Set[Int] = Set(1, 2, 3) + +scala> val c = Map(1 -> 1, 2 -> 2) +val c: Map[Int, Int] = Map(1 -> 1, 2 -> 2) +``` + + +### Импорт можно использовать в любом месте + +В Scala операторы `import` могут быть объявлены где угодно. +Их можно использовать в верхней части файла исходного кода: + +```scala +package foo + +import scala.util.Random + +class ClassA: + def printRandom(): Unit = + val r = new Random // класс Random здесь доступен + // ещё код... +``` + +Также операторы `import` можно использовать ближе к тому месту, где они необходимы: + +```scala +package foo + +class ClassA: + import scala.util.Random // внутри ClassA + def printRandom(): Unit = + val r = new Random + // ещё код... + +class ClassB: + // класс Random здесь невидим + val r = new Random // этот код не скомпилится +``` + + +### “Статический” импорт + +Если необходимо импортировать элементы способом, аналогичным подходу “статического импорта” в Java, +то есть для того, чтобы напрямую обращаться к членам класса, не добавляя к ним префикс с именем класса, +используется следующий подход. + +Синтаксис для импорта всех статических членов Java класса `Math`: + +```scala +import java.lang.Math.* +``` + +Теперь можно получить доступ к статическим методам класса `Math`, +таким как `sin` и `cos`, без необходимости предварять их именем класса: + +```scala +import java.lang.Math.* + +val a = sin(0) // 0.0 +val b = cos(PI) // -1.0 +``` + + +### Пакеты, импортированные по умолчанию + +Два пакета неявно импортируются во все файлы исходного кода: + +- `java.lang.*` +- `scala.*` + +Члены object `Predef` также импортируются по умолчанию. + +> Например, такие классы, как `List`, `Vector`, `Map` и т.д. можно использовать явно, не импортируя их - +> они доступны, потому что определены в object `Predef` + + +### Обработка конфликтов имен + +Если необходимо импортировать что-то из корня проекта и возникает конфликт имен, +достаточно просто добавить к имени пакета префикс `_root_`: + +``` +package accounts + +import _root_.accounts.* +``` + + +## Импорт экземпляров `given` + +Как будет показано в главе [“Контекстные абстракции”][contextual], +для импорта экземпляров `given` используется специальная форма оператора `import`. +Базовая форма показана в этом примере: + +```scala +object A: + class TC + given tc: TC + def f(using TC) = ??? + +object B: + import A.* // импорт всех non-given членов + import A.given // импорт экземпляров given +``` + +В этом коде предложение `import A.*` объекта `B` импортирует все элементы `A`, _кроме_ `given` экземпляра `tc`. +И наоборот, второй импорт, `import A.given`, импортирует _только_ `given` экземпляр. +Два предложения импорта также могут быть объединены в одно: + +```scala +object B: + import A.{given, *} +``` + +### Обсуждение + +Селектор с подстановочным знаком `*` помещает в область видимости все определения, кроме `given`, +тогда как селектор выше помещает в область действия все данные, включая те, которые являются результатом расширений. + +Эти правила имеют два основных преимущества: + +- более понятно, откуда берутся данные given. + В частности, невозможно скрыть импортированные given в длинном списке других импортируемых подстановочных знаков. +- есть возможность импортировать все given, не импортируя ничего другого. + Это особенно важно, поскольку given могут быть анонимными, поэтому обычное использование именованного импорта нецелесообразно. + + +### Импорт по типу + +Поскольку given-ы могут быть анонимными, не всегда практично импортировать их по имени, +и вместо этого обычно используется импорт подстановочных знаков. +_Импорт по типу_ предоставляет собой более конкретную альтернативу импорту с подстановочными знаками, +делая понятным то, что импортируется. + +```scala +import A.{given TC} +``` + +Этот код импортирует из `A` любой `given` тип, соответствующий `TC`. +Импорт данных нескольких типов `T1,...,Tn` выражается несколькими `given` селекторами: + +```scala +import A.{given T1, ..., given Tn} +``` + +Импорт всех `given` экземпляров параметризованного типа достигается аргументами с подстановочными знаками. +Например, есть такой `объект`: + +```scala +object Instances: + given intOrd: Ordering[Int] + given listOrd[T: Ordering]: Ordering[List[T]] + given ec: ExecutionContext = ... + given im: Monoid[Int] +``` + +Оператор `import` ниже импортирует экземпляры `intOrd`, `listOrd` и `ec`, но пропускает экземпляр `im`, +поскольку он не соответствует ни одному из указанных шаблонов: + +```scala +import Instances.{given Ordering[?], given ExecutionContext} +``` + +Импорт по типу можно смешивать с импортом по имени. +Если оба присутствуют в предложении import, импорт по типу идет последним. +Например, это предложение импорта импортирует `im`, `intOrd` и `listOrd`, но не включает `ec`: + +```scala +import Instances.{im, given Ordering[?]} +``` + + +### Пример + +В качестве конкретного примера представим, что у нас есть объект `MonthConversions`, +который содержит два определения `given`: + +```scala +object MonthConversions: + trait MonthConverter[A]: + def convert(a: A): String + + given intMonthConverter: MonthConverter[Int] with + def convert(i: Int): String = + i match + case 1 => "January" + case 2 => "February" + // остальные случаи здесь ... + + given stringMonthConverter: MonthConverter[String] with + def convert(s: String): String = + s match + case "jan" => "January" + case "feb" => "February" + // остальные случаи здесь ... +``` + +Чтобы импортировать эти given-ы в текущую область, используем два оператора `import`: + +```scala +import MonthConversions.* +import MonthConversions.{given MonthConverter[?]} +``` + +Теперь создаем метод, использующий эти экземпляры: + +```scala +def genericMonthConverter[A](a: A)(using monthConverter: MonthConverter[A]): String = + monthConverter.convert(a) +``` + +Вызов метода: + +```scala +@main def main = + println(genericMonthConverter(1)) // January + println(genericMonthConverter("jan")) // January +``` + +Как уже упоминалось ранее, одно из ключевых преимуществ синтаксиса “import given” состоит в том, +чтобы прояснить, откуда берутся данные в области действия, +и в `import` операторах выше ясно, что данные поступают из объекта `MonthConversions`. + + +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} diff --git a/_ru/scala3/book/scala-features.md b/_ru/scala3/book/scala-features.md new file mode 100644 index 0000000000..5a0f3b50e5 --- /dev/null +++ b/_ru/scala3/book/scala-features.md @@ -0,0 +1,485 @@ +--- +layout: multipage-overview +title: Возможности Scala +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице рассматриваются основные возможности языка программирования Scala. +language: ru +num: 2 +previous-page: introduction +next-page: why-scala-3 +--- + + +Название _Scala_ происходит от слова _scalable_, и в соответствии с этим названием язык Scala используется для +поддержки загруженных веб-сайтов и анализа огромных наборов данных. +В этом разделе представлены функции, которые делают Scala масштабируемым языком. +Эти функции разделены на три раздела: + +- Функции высокоуровневого языка программирования +- Функции низкоуровневого языка программирования +- Особенности экосистемы Scala + + + +## Высокоуровневые функции + +Глядя на Scala с пресловутого “вида с высоты 30 000 фунтов”, вы можете сделать о нем следующие утверждения: + +- Это высокоуровневый язык программирования +- Он имеет краткий, читаемый синтаксис +- Он статически типизирован (но кажется динамичным) +- Имеет выразительную систему типов +- Это язык функционального программирования (ФП) +- Это язык объектно-ориентированного программирования (ООП) +- Он поддерживает слияние ФП и ООП +- Контекстные абстракции обеспечивают понятный способ реализации _вывода терминов_ (_term inference_) +- Он работает на JVM (и в браузере) +- Беспрепятственно взаимодействует с Java кодом +- Он используется для серверных приложений (включая микросервисы), приложений для работы с большими данными, а также может использоваться в браузере с помощью Scala.js + +Эти функции кратко рассматриваются в следующих разделах. + + +### Высокоуровневый язык + +Scala считается высокоуровневым языком как минимум по двум причинам. +Во-первых, подобно Java и многим другим современным языкам, вы не имеете дело с низкоуровневыми понятиями, +такими как указатели и управление памятью. + +Во-вторых, с использованием лямбда-выражений и функций высшего порядка вы пишете свой код на очень высоком уровне. +Как говорится в функциональном программировании, в Scala вы пишете то, _что_ хотите, а не то, _как_ этого добиться. +То есть мы не пишем императивный код вот так: + +{% tabs scala-features-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=scala-features-1 %} +```scala +import scala.collection.mutable.ListBuffer + +def double(ints: List[Int]): List[Int] = { + val buffer = new ListBuffer[Int]() + for (i <- ints) { + buffer += i * 2 + } + buffer.toList +} + +val oldNumbers = List(1, 2, 3) +val newNumbers = double(oldNumbers) +``` +{% endtab %} +{% tab 'Scala 3' for=scala-features-1 %} +```scala +import scala.collection.mutable.ListBuffer + +def double(ints: List[Int]): List[Int] = + val buffer = new ListBuffer[Int]() + for i <- ints do + buffer += i * 2 + buffer.toList + +val oldNumbers = List(1, 2, 3) +val newNumbers = double(oldNumbers) +``` +{% endtab %} +{% endtabs %} + +Этот код шаг за шагом указывает компилятору, что делать. +Вместо этого мы пишем высокоуровневый функциональный код, используя функции высшего порядка и лямбда-выражения, +подобные этому, для вычисления того же результата: + +{% tabs scala-features-2 %} +{% tab 'Scala 2 и 3' for=scala-features-2 %} +```scala +val newNumbers = oldNumbers.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + + +Как видите, этот код намного лаконичнее, его легче читать и легче поддерживать. + + +### Лаконичный синтаксис + +Scala имеет краткий, удобочитаемый синтаксис. +Например, переменные создаются лаконично, а их типы понятны: + +{% tabs scala-features-3 %} +{% tab 'Scala 2 и 3' for=scala-features-3 %} +```scala +val nums = List(1,2,3) +val p = Person("Martin", "Odersky") +``` +{% endtab %} +{% endtabs %} + + +Функции высшего порядка и лямбда-выражения делают код кратким и удобочитаемым: + +{% tabs scala-features-4 %} +{% tab 'Scala 2 и 3' for=scala-features-4 %} +```scala +nums.map(i => i * 2) // длинная форма +nums.map(_ * 2) // краткая форма + +nums.filter(i => i > 1) +nums.filter(_ > 1) +``` +{% endtab %} +{% endtabs %} + +Трэйты, классы и методы определяются с помощью простого и легкого синтаксиса: + +{% tabs scala-features-5 class=tabs-scala-version %} +{% tab 'Scala 2' for=scala-features-5 %} +```scala mdoc +trait Animal { + def speak(): Unit +} + +trait HasTail { + def wagTail(): Unit +} + +class Dog extends Animal with HasTail { + def speak(): Unit = println("Woof") + def wagTail(): Unit = println("⎞⎜⎛ ⎞⎜⎛") +} +``` +{% endtab %} +{% tab 'Scala 3' for=scala-features-5 %} +```scala +trait Animal: + def speak(): Unit + +trait HasTail: + def wagTail(): Unit + +class Dog extends Animal, HasTail: + def speak(): Unit = println("Woof") + def wagTail(): Unit = println("⎞⎜⎛ ⎞⎜⎛") +``` +{% endtab %} +{% endtabs %} + + +Исследования показали, что время, которое разработчик тратит на _чтение_ и _написание_ кода, составляет как минимум 10:1, +поэтому важно писать краткий и читабельный код. + + +### Ощущение динамики + +Scala — это язык со статической типизацией, но благодаря своим возможностям вывода типов он кажется динамичным. +Все эти выражения выглядят как языки с динамической типизацией, такие как Python или Ruby, но это все Scala: + +{% tabs scala-features-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=scala-features-6 %} +```scala +val s = "Hello" +val p = Person("Al", "Pacino") +val sum = nums.reduceLeft(_ + _) +val y = for (i <- nums) yield i * 2 +val z = nums + .filter(_ > 100) + .filter(_ < 10_000) + .map(_ * 2) +``` +{% endtab %} +{% tab 'Scala 3' for=scala-features-6 %} +```scala +val s = "Hello" +val p = Person("Al", "Pacino") +val sum = nums.reduceLeft(_ + _) +val y = for i <- nums yield i * 2 +val z = nums + .filter(_ > 100) + .filter(_ < 10_000) + .map(_ * 2) +``` +{% endtab %} +{% endtabs %} + + +Как утверждает Heather Miller, Scala считается [сильным языком со статической типизацией](https://heather.miller.am/blog/types-in-scala.html), +и вы получаете все преимущества статических типов: + +- Корректность: вы обнаруживаете большинство ошибок во время компиляции +- Отличная поддержка IDE + - Надежное автодополнение кода + - Отлов ошибок во время компиляции означает отлов ошибок по мере написания + - Простой и надежный рефакторинг +- Вы можете уверенно рефакторить свой код +- Объявления типов методов сообщают читателям, что делает метод, и помогают служить документацией +- Масштабируемость и удобство обслуживания: типы помогают обеспечить корректность в произвольно больших приложениях и командах разработчиков +- Строгая типизация в сочетании с превосходным выводом типов позволяет использовать такие механизмы, как [контекстная абстракция]({{ site.scala3ref }}/contextual), которая позволяет вам опускать шаблонный код. Часто этот шаблонный код может быть выведен компилятором на основе определений типов и заданного контекста. + + +### Выразительная система типов + +Система типов в Scala во время компиляции обеспечивает безопасное и согласованное использование абстракций. +В частности, система типов поддерживает: + +- [Выводимые типы]({% link _overviews/scala3-book/types-inferred.md %}) +- [Generic классы]({% link _overviews/scala3-book/types-generics.md %}) +- [Аннотации вариантности]({% link _overviews/scala3-book/types-variance.md %}) +- [Верхняя](/tour/upper-type-bounds.html) и [нижняя](/tour/lower-type-bounds.html) границы типов +- [Полиморфные методы](/tour/polymorphic-methods.html) +- [Типы пересечения]({% link _overviews/scala3-book/types-intersection.md %}) +- [Типы объединения]({% link _overviews/scala3-book/types-union.md %}) +- [Лямбда-типы]({{ site.scala3ref }}/new-types/type-lambdas.html) +- [Экземпляры `given` и предложения `using`]({% link _overviews/scala3-book/ca-context-parameters.md %}) +- [Методы расширения]({% link _overviews/scala3-book/ca-extension-methods.md %}) +- [Типовые классы]({% link _overviews/scala3-book/ca-type-classes.md %}) +- [Многостороннее равенство]({% link _overviews/scala3-book/ca-multiversal-equality.md %}) +- [Псевдонимы непрозрачного типа]({% link _overviews/scala3-book/types-opaque-types.md %}) +- [Открытые классы]({{ site.scala3ref }}/other-new-features/open-classes.html) +- [Типы соответствия]({{ site.scala3ref }}/new-types/match-types.html) +- [Зависимые типы функций]({{ site.scala3ref }}/new-types/dependent-function-types.html) +- [Полиморфные функциональные типы]({{ site.scala3ref }}/new-types/polymorphic-function-types.html) +- [Контекстные границы]({{ site.scala3ref }}/contextual/context-bounds.html) +- [Контекстные функции]({{ site.scala3ref }}/contextual/context-functions.html) +- [Внутренние классы](/tour/inner-classes.html) и [элементы абстрактного типа](/tour/abstract-type-members.html) как элементы объекта + +В сочетании эти функции обеспечивают мощную основу для безопасного повторного использования программных абстракций +и для безопасного расширения программного обеспечения. + + +### Язык функционального программирования + +Scala — это язык функционального программирования (ФП), что означает: + +- Функции — это значения, и их можно передавать, как и любое другое значение +- Напрямую поддерживаются функции высшего порядка +- Встроенные лямбда +- Все в Scala — это выражение, возвращающее значение +- Синтаксически легко использовать неизменяемые переменные, и их использование приветствуется +- В стандартной библиотеке языка содержится множество неизменяемых классов коллекций +- Эти классы коллекций поставляются с десятками функциональных методов: они не изменяют коллекцию, вместо этого возвращая обновленную копию данных + + +### Объектно-ориентированный язык + +Scala — это язык объектно-ориентированного программирования (ООП). +Каждое значение — это экземпляр класса, а каждый “оператор” — это метод. + +В Scala все типы наследуются от класса верхнего уровня `Any`, чьими непосредственными дочерними элементами являются `AnyVal` (_типы значений_, такие как `Int` и `Boolean`) и `AnyRef` (_ссылочные типы_, как в Java). +Это означает, что различие в Java между примитивными и упакованными типами (например, `int` против `Integer`) отсутствует в Scala. +Упаковка и распаковка полностью прозрачны для пользователя. + + +### Поддерживает слияние ФП/ООП + + +Суть Scala заключается в слиянии функционального программирования и объектно-ориентированного программирования в типизированной среде: + +- Функции для логики +- Объекты для модульности + +[Как заявил Мартин Одерски](https://jaxenter.com/current-state-scala-odersky-interview-129495.html), “Scala был разработан, чтобы показать, что слияние функционального и объектно-ориентированного программирования возможно и практично”. + + +### Вывод терминов стал более понятным + +После Haskell Scala был вторым популярным языком, в котором была некоторая форма неявных (_implicits_) выражений. +В Scala 3 эти концепции были полностью переосмыслены и реализованы более четко. + +Основная идея заключается в _выводе терминов_: на основе заданного, компилятор синтезирует “канонический” термин, который имеет этот тип. +В Scala параметр контекста напрямую ведет к выводимому термину аргумента, который также может быть записан явно. + +Примеры использования этой концепции включают реализацию [типовых классов]({% link _overviews/scala3-book/ca-type-classes.md %}), +установление контекста, внедрение зависимостей, выражение возможностей, вычисление новых типов и доказательство отношений между ними. + +Scala 3 делает этот процесс более понятным, чем когда-либо прежде. +О контекстных абстракциях можно прочесть в [Справочной документации]({{ site.scala3ref }}/contextual). + + +### Клиент & сервер + +Код Scala работает на виртуальной машине Java (JVM), поэтому вы получаете все ее преимущества: + +- Безопасность +- Производительность +- Управление памятью +- Портативность и независимость от платформы +- Возможность использовать множество существующих Java и JVM библиотек + +Помимо работы на JVM, Scala также работает в браузере с помощью Scala.js (и сторонних инструментов с открытым исходным кодом для интеграции популярных библиотек JavaScript), а собственные исполняемые файлы могут быть созданы с помощью Scala Native и GraalVM. + + +### Беспрепятственное взаимодействие с Java + +Вы можете использовать Java классы и библиотеки в своих приложениях Scala, а также код Scala в приложениях Java. +Что касается второго пункта, большие библиотеки, такие как [Akka](https://akka.io) и [Play Framework](https://www.playframework.com) написаны на Scala и могут использоваться в приложениях Java. + +Что касается первого пункта, классы и библиотеки Java используются в приложениях Scala каждый день. +Например, в Scala вы можете читать файлы с помощью `BufferedReader` и `FileReader` из Java: + +{% tabs scala-features-7 %} +{% tab 'Scala 2 и 3' for=scala-features-7 %} +```scala +import java.io.* +val br = BufferedReader(FileReader(filename)) +// чтение файла в `br` ... +``` +{% endtab %} +{% endtabs %} + +Использование Java-кода в Scala, как правило, не вызывает затруднений. + +В Scala также можно использовать коллекции Java, и если вы хотите использовать с ними богатый набор методов классов коллекций Scala, +то можете преобразовать их с помощью всего нескольких строк кода: + +{% tabs scala-features-8 %} +{% tab 'Scala 2 и 3' for=scala-features-8 %} +```scala +import scala.jdk.CollectionConverters.* +val scalaList: Seq[Integer] = JavaClass.getJavaList().asScala.toSeq +``` +{% endtab %} +{% endtabs %} + + +### Богатство библиотек + +Как будет видно в третьем разделе этой страницы, библиотеки и фреймворки Scala, подобные нижеследующим, +были написаны для поддержки загруженных веб-сайтов и работы с огромными наборами данных: + +1. [Play Framework](https://www.playframework.com) — это легкая, без сохранения состояния, удобная для web, удобная для разработчиков архитектура для создания масштабируемых приложений +2. [Apache Spark](https://spark.apache.org) — это унифицированный аналитический механизм для обработки больших данных со встроенными модулями для потоковой передачи, SQL, машинного обучения и обработки графиков + +В [списке Awesome Scala](https://github.com/lauris/awesome-scala) представлены десятки дополнительных инструментов +с открытым исходным кодом, созданных разработчиками для создания приложений Scala. + +В дополнение к программированию на стороне сервера, [Scala.js](https://www.scala-js.org) представляет собой +строго типизированную замену для написания JavaScript со сторонними библиотеками с открытым исходным кодом, +которые включают инструменты для интеграции с библиотекой Facebook React, jQuery и т.д. + + +## Функции низкоуровневого языка + +Хотя в предыдущем разделе были рассмотрены высокоуровневые функции Scala, интересно отметить, +что на высоком уровне вы можете делать одни и те же утверждения как о Scala 2, так и о Scala 3. +Десять лет назад Scala начиналась с прочного фундамента желаемых функций, и вы увидите в этом разделе, +что в Scala 3 эти преимущества были улучшены. + +С точки зрения деталей “на уровне моря” — то есть функций языка, которые программисты используют каждый день — +Scala 3 имеет значительные преимущества по сравнению со Scala 2: + +- Возможность более лаконично создавать алгебраические типы данных (ADT) с перечислениями +- Еще более лаконичный и читаемый синтаксис: + - Синтаксис “тихой” структуры управления легче читать + - Опциональные фигурные скобки + - Меньшее количество символов в коде создает меньше визуального шума, что упрощает его чтение + - Ключевое слово `new` обычно больше не требуется при создании экземпляров класса + - Формальность объектов пакета была заменена более простыми определениями “верхнего уровня” +- Более понятная грамматика: + - Несколько различных вариантов использования ключевого слова `implicit` были удалены; это использование заменено более очевидными ключевыми словами, такими как `given`, `using`, и `extension`, фокусирующихся на намерении, а не механизме (подробности см. в разделе [Givens][givens]) + - [Методы расширения][extension] заменяют неявные классы более понятным и простым механизмом + - Добавление модификатора `open` для классов заставляет разработчика намеренно объявить, что класс открыт для модификации, тем самым ограничивая специальные расширения кодовой базы + - [Многостороннее равенство][multiversal] исключает бессмысленные сравнения с `==` и `!=` (т.е. попытки сравнить `Person` с `Planet`) + - Гораздо проще реализуются макросы + - Объединение и пересечение предлагают гибкий способ моделирования типов + - Параметры трейтов заменяют и упрощают ранние инициализаторы + - [Псевдонимы непрозрачных типов][opaque_types] заменяют большинство случаев использования классов значений, гарантируя при этом отсутствие упаковки + - Export предложения обеспечивают простой и общий способ выражения агрегации, который может заменить предыдущий шаблон фасада объектов пакета, наследуемых от классов + - Синтаксис procedure был удален, а синтаксис varargs - изменен, чтобы сделать язык более согласованным + - `@infix` аннотация делает очевидным желаемое применение метода + - Аннотация метода [`@targetName`]({{ site.scala3ref }}/other-new-features/targetName.html) определяет альтернативное имя метода, улучшая совместимость с Java и позволяя указывать псевдонимы для символических операторов + +Демонстрация всех этих функций заняла бы слишком много места, но перейдите по ссылкам в пунктах выше, чтобы увидеть эти функции в действии. +Все эти функции подробно обсуждаются на страницах *New*, *Changed* и *Dropped* функций в [обзорной документации][reference]. + + +## Экосистема Scala + + +У Scala динамичная экосистема с библиотеками и фреймворками под любые требования. +[Список “Awesome Scala”](https://github.com/lauris/awesome-scala) содержит список сотен проектов с открытым исходным кодом, +доступных разработчикам Scala, а [Scaladex](https://index.scala-lang.org) предоставляет доступный для поиска индекс библиотек Scala. +Некоторые из наиболее известных библиотек перечислены ниже. + + + +### Web разработка + +- [Play Framework](https://www.playframework.com) следует модели Ruby on Rails, чтобы стать легкой, не сохраняющей состояния, + удобной для разработчиков и web архитектурой для высокомасштабируемых приложений +- [Scalatra](https://scalatra.org) — небольшой высокопроизводительный асинхронный web framework, вдохновленный Sinatra +- [Finatra](https://twitter.github.io/finatra) — это сервисы Scala, построенные на TwitterServer и Finagle +- [Scala.js](https://www.scala-js.org) — это строго типизированная замена JavaScript, обеспечивающая более безопасный способ создания надежных интерфейсных web-приложений +- [ScalaJs-React](https://github.com/japgolly/scalajs-react) поднимает библиотеку Facebook React на Scala.js и пытается сделать ее максимально безопасной для типов и удобной для Scala + + +HTTP(S) библиотеки: + +- [Akka-http](https://akka.io) +- [Finch](https://github.com/finagle/finch) +- [Http4s](https://github.com/http4s/http4s) +- [Sttp](https://github.com/softwaremill/sttp) + +JSON библиотеки: + +- [Argonaut](https://github.com/argonaut-io/argonaut) +- [Circe](https://github.com/circe/circe) +- [Json4s](https://github.com/json4s/json4s) +- [Play-JSON](https://github.com/playframework/play-json) + +Сериализация: + +- [ScalaPB](https://github.com/scalapb/ScalaPB) + +### Наука и анализ данных: + +- [Algebird](https://github.com/twitter/algebird) +- [Spire](https://github.com/typelevel/spire) +- [Squants](https://github.com/typelevel/squants) + + +### Большие данные + +- [Apache Spark](https://github.com/apache/spark) +- [Apache Flink](https://github.com/apache/flink) + + +### ИИ, машинное обучение + +- [BigDL](https://github.com/intel-analytics/BigDL) (Распределенная среда глубокого обучения для Apache Spark) +- [TensorFlow Scala](https://github.com/eaplatanios/tensorflow_scala) + + +### Функциональное программирование & Функциональное реактивное программирование + +ФП: + +- [Cats](https://github.com/typelevel/cats) +- [Zio](https://github.com/zio/zio) + +Функциональное реактивное программирование (ФРП): + +- [fs2](https://github.com/typelevel/fs2) +- [monix](https://github.com/monix/monix) + + +### Инструменты сборки + +- [sbt](https://www.scala-sbt.org) +- [Gradle](https://gradle.org) +- [Mill](https://github.com/lihaoyi/mill) + + + +## Подведем итоги + +Как показано на этой странице, Scala обладает множеством замечательных функций высокоуровневого языка программирования, +низкоуровневого языка программирования и богатой экосистемой разработчиков. + + +[reference]: {{ site.scala3ref }}/overview.html +[multiversal]: {% link _overviews/scala3-book/ca-multiversal-equality.md %} +[extension]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[givens]: {% link _overviews/scala3-book/ca-context-parameters.md %} +[opaque_types]: {% link _overviews/scala3-book/types-opaque-types.md %} + diff --git a/_ru/scala3/book/scala-tools.md b/_ru/scala3/book/scala-tools.md new file mode 100644 index 0000000000..e58bfb2e64 --- /dev/null +++ b/_ru/scala3/book/scala-tools.md @@ -0,0 +1,18 @@ +--- +layout: multipage-overview +title: Scala утилиты +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе рассматриваются два широко используемых инструмента Scala sbt и ScalaTest. +language: ru +num: 69 +previous-page: concurrency +next-page: tools-sbt +--- + +В этой главе представлены два способа написания и запуска программ в Scala: + +- создавая Scala проекты, возможно, содержащие несколько файлов, и определяя точку входа в программу, +- путем взаимодействия с worksheet, который представляет собой программу, определенную в одном файле и выполняемую построчно. diff --git a/_ru/scala3/book/string-interpolation.md b/_ru/scala3/book/string-interpolation.md new file mode 100644 index 0000000000..9e37b526fa --- /dev/null +++ b/_ru/scala3/book/string-interpolation.md @@ -0,0 +1,413 @@ +--- +layout: multipage-overview +title: Интерполяция строк +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице представлена дополнительная информация о создании строк и использовании интерполяции строк. +language: ru +num: 18 +previous-page: first-look-at-types +next-page: control-structures +--- + +## Введение + +Интерполяция строк позволяет использовать внутри строк переменные. +Например: + +{% tabs example-1 %} +{% tab 'Scala 2 и 3' for=example-1 %} + +```scala +val name = "James" +val age = 30 +println(s"$name is $age years old") // "James is 30 years old" +``` + +{% endtab %} +{% endtabs %} + +Использование интерполяции строк заключается в том, что перед строковыми кавычками ставится символ `s`, +а перед любыми именами переменных ставится символ `$`. + +### Другие интерполяторы + +То `s`, что вы помещаете перед строкой, является лишь одним из возможных интерполяторов, предоставляемых Scala. + +Scala по умолчанию предоставляет три метода интерполяции строк: `s`, `f` и `raw`. +Кроме того, строковый интерполятор — это всего лишь специальный метод, и вы можете определить свой собственный. +Например, некоторые библиотеки баз данных определяют интерполятор `sql`, возвращающий запрос к базе данных. + +## Интерполятор `s` (`s`-строки) + +Добавление `s` перед любым строковым литералом позволяет использовать переменные непосредственно в строке. +Вы уже здесь видели пример: + +{% tabs example-2 %} +{% tab 'Scala 2 и 3' for=example-2 %} + +```scala +val name = "James" +val age = 30 +println(s"$name is $age years old") // "James is 30 years old" +``` + +{% endtab %} +{% endtabs %} + +Здесь переменные `$name` и `$age` заменяются в строке результатами вызова `name.toString` и `age.toString` соответственно. +`s`-строка будет иметь доступ ко всем переменным, в настоящее время находящимся в области видимости. + +Хотя это может показаться очевидным, важно здесь отметить, +что интерполяция строк _не_ будет выполняться в обычных строковых литералах: + +{% tabs example-3 %} +{% tab 'Scala 2 и 3' for=example-3 %} + +```scala +val name = "James" +val age = 30 +println("$name is $age years old") // "$name is $age years old" +``` + +{% endtab %} +{% endtabs %} + +Строковые интерполяторы также могут принимать произвольные выражения. +Например: + +{% tabs example-4 %} +{% tab 'Scala 2 и 3' for=example-4 %} + +```scala +println(s"2 + 2 = ${2 + 2}") // "2 + 2 = 4" +val x = -1 +println(s"x.abs = ${x.abs}") // "x.abs = 1" +``` + +{% endtab %} +{% endtabs %} + +Любое произвольное выражение может быть встроено в `${}`. + +Некоторые специальные символы необходимо экранировать при встраивании в строку. +Чтобы указать символ "знак доллара", вы можете удвоить его `$$`, как показано ниже: + +{% tabs example-5 %} +{% tab 'Scala 2 и 3' for=example-5 %} + +```scala +println(s"New offers starting at $$14.99") // "New offers starting at $14.99" +``` + +{% endtab %} +{% endtabs %} + +Двойные кавычки также необходимо экранировать. +Это можно сделать с помощью тройных кавычек, как показано ниже: + +{% tabs example-6 %} +{% tab 'Scala 2 и 3' for=example-6 %} + +```scala +println(s"""{"name":"James"}""") // `{"name":"James"}` +``` + +{% endtab %} +{% endtabs %} + +Наконец, все многострочные строковые литералы также могут быть интерполированы. + +{% tabs example-7 %} +{% tab 'Scala 2 и 3' for=example-7 %} + +```scala +println(s"""name: "$name", + |age: $age""".stripMargin) +``` + +Строка будет напечатана следующим образом: + +``` +name: "James" +age: 30 +``` + +{% endtab %} +{% endtabs %} + +## Интерполятор `f` (`f`-строки) + +Добавление `f` к любому строковому литералу позволяет создавать простые отформатированные строки, +аналогичные `printf` в других языках. +При использовании интерполятора `f` за всеми ссылками на переменные должна следовать строка формата в стиле `printf`, например `%d`. +Давайте посмотрим на пример: + +{% tabs example-8 %} +{% tab 'Scala 2 и 3' for=example-8 %} + +```scala +val height = 1.9d +val name = "James" +println(f"$name%s is $height%2.2f meters tall") // "James is 1.90 meters tall" +``` + +{% endtab %} +{% endtabs %} + +Интерполятор `f` типобезопасен. +Если вы попытаетесь передать в строку формата, который работает только для целых чисел, +значение `double`, компилятор выдаст ошибку. Например: + +{% tabs f-interpolator-error class=tabs-scala-version %} + +{% tab 'Scala 2' for=f-interpolator-error %} + +```scala +val height: Double = 1.9d + +scala> f"$height%4d" +:9: error: type mismatch; + found : Double + required: Int + f"$height%4d" + ^ +``` + +{% endtab %} + +{% tab 'Scala 3' for=f-interpolator-error %} + +```scala +val height: Double = 1.9d + +scala> f"$height%4d" +-- Error: ---------------------------------------------------------------------- +1 |f"$height%4d" + | ^^^^^^ + | Found: (height : Double), Required: Int, Long, Byte, Short, BigInt +1 error found + +``` + +{% endtab %} +{% endtabs %} + +Интерполятор `f` использует утилиты форматирования строк, доступные в Java. +Форматы, разрешенные после символа `%`, описаны в [Formatter javadoc][java-format-docs]. +Если после определения переменной нет символа `%`, предполагается форматирование `%s` (`String`). + +Наконец, как и в Java, используйте `%%` для получения буквенного символа `%` в итоговой строке: + +{% tabs literal-percent %} +{% tab 'Scala 2 и 3' for=literal-percent %} + +```scala +println(f"3/19 is less than 20%%") // "3/19 is less than 20%" +``` + +{% endtab %} +{% endtabs %} + +### Интерполятор `raw` + +Интерполятор `raw` похож на интерполятор `s`, +за исключением того, что он не выполняет экранирование литералов внутри строки. +Вот пример обработанной строки: + +{% tabs example-9 %} +{% tab 'Scala 2 и 3' for=example-9 %} + +```scala +scala> s"a\nb" +res0: String = +a +b +``` + +{% endtab %} +{% endtabs %} + +Здесь строковый интерполятор `s` заменил символы `\n` символом переноса строки. +Интерполятор `raw` этого не делает. + +{% tabs example-10 %} +{% tab 'Scala 2 и 3' for=example-10 %} + +```scala +scala> raw"a\nb" +res1: String = a\nb +``` + +{% endtab %} +{% endtabs %} + +Интерполятор `raw` полезен тогда, когда вы хотите избежать преобразования таких выражений, как `\n`, в символ переноса строки. + +В дополнение к трем строковым интерполяторам пользователи могут определить свои собственные. + +## Расширенное использование + +Литерал `s"Hi $name"` анализируется Scala как _обрабатываемый_ строковый литерал. +Это означает, что компилятор выполняет некоторую дополнительную работу с этим литералом. +Особенности обработанных строк и интерполяции строк описаны в [SIP-11][sip-11]. +Вот краткий пример, который поможет проиллюстрировать, как они работают. + +### Пользовательские интерполяторы + +В Scala все обрабатываемые строковые литералы представляют собой простые преобразования кода. +Каждый раз, когда компилятор встречает обрабатываемый строковый литерал вида: + +{% tabs example-11 %} +{% tab 'Scala 2 и 3' for=example-11 %} + +```scala +id"string content" +``` + +{% endtab %} +{% endtabs %} + +он преобразует его в вызов метода (`id`) для экземпляра [StringContext](https://www.scala-lang.org/api/current/scala/StringContext.html). +Этот метод также может быть доступен в неявной области видимости. +Чтобы определить собственную интерполяцию строк, нужно создать неявный класс (Scala 2) +или метод расширения (Scala 3), который добавляет новый метод для `StringContext`. + +В качестве простого примера предположим, что у нас есть простой класс `Point` +и мы хотим создать собственный интерполятор, который преобразует `p"a,b"` в объект `Point`. + +{% tabs custom-interpolator-1 %} +{% tab 'Scala 2 и 3' for=custom-interpolator-1 %} + +```scala +case class Point(x: Double, y: Double) + +val pt = p"1,-2" // Point(1.0,-2.0) +``` + +{% endtab %} +{% endtabs %} + +Мы бы создали собственный интерполятор `p`, +сначала внедрив расширение `StringContext`, например, так: + +{% tabs custom-interpolator-2 class=tabs-scala-version %} + +{% tab 'Scala 2' for=custom-interpolator-2 %} + +```scala +implicit class PointHelper(val sc: StringContext) extends AnyVal { + def p(args: Any*): Point = ??? +} +``` + +**Примечание**. Важно расширить `AnyVal` в Scala 2.x, +чтобы предотвратить создание экземпляра класса во время выполнения при каждой интерполяции. +Дополнительную информацию см. в документации по [value class]({% link _overviews/core/value-classes.md %}). + +{% endtab %} + +{% tab 'Scala 3' for=custom-interpolator-2 %} + +```scala +extension (sc: StringContext) + def p(args: Any*): Point = ??? +``` + +{% endtab %} + +{% endtabs %} + +Как только это расширение окажется в области видимости и компилятор Scala обнаружит `p"some string"`, +то превратит `some string` в токены String, а каждую встроенную переменную в аргументы выражения. + +Например, `p"1, $someVar"` превратится в: + +{% tabs extension-desugaring class=tabs-scala-version %} + +{% tab 'Scala 2' for=extension-desugaring %} + +```scala +new StringContext("1, ", "").p(someVar) +``` + +Затем неявный класс используется для перезаписи следующим образом: + +```scala +new PointHelper(new StringContext("1, ", "")).p(someVar) +``` + +{% endtab %} + +{% tab 'Scala 3' for=extension-desugaring %} + +```scala +StringContext("1, ", "").p(someVar) +``` + +{% endtab %} + +{% endtabs %} + +В результате каждый из фрагментов обработанной строки отображается в элементе `StringContext.parts`, +а любые значения выражений в строке передаются в параметр метода `args`. + +### Пример реализации + +Простая реализация метода интерполяции для нашего `Point` может выглядеть примерно так, как показано ниже, +хотя более детализированный метод может иметь более точный контроль +над обработкой строки `parts` и выражения `args` вместо повторного использования интерполятора `s`. + +{% tabs naive-implementation class=tabs-scala-version %} + +{% tab 'Scala 2' for=naive-implementation %} + +```scala +implicit class PointHelper(val sc: StringContext) extends AnyVal { + def p(args: Double*): Point = { + // переиспользование интерполятора `s` и затем разбиение по ',' + val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } + Point(pts(0), pts(1)) + } +} + +val x=12.0 + +p"1, -2" // Point(1.0, -2.0) +p"${x/5}, $x" // Point(2.4, 12.0) +``` + +{% endtab %} + +{% tab 'Scala 3' for=naive-implementation %} + +```scala +extension (sc: StringContext) + def p(args: Double*): Point = { + // переиспользование интерполятора `s` и затем разбиение по ',' + val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } + Point(pts(0), pts(1)) + } + +val x=12.0 + +p"1, -2" // Point(1.0, -2.0) +p"${x/5}, $x" // Point(2.4, 12.0) +``` + +{% endtab %} +{% endtabs %} + +Хотя строковые интерполяторы изначально использовались для создания нескольких строковых форм, +использование пользовательских интерполяторов, как указано выше, +может обеспечить более мощное синтаксическое сокращение, +и сообщество уже использует этот синтаксис для таких вещей, +как расширение цвета терминала ANSI, выполнение SQL-запросов, +магические представления `$"identifier"` и многие другие. + +[java-format-docs]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html#detail + +[value-class]: {% link _overviews/core/value-classes.md %} +[sip-11]: {% link _sips/sips/string-interpolation.md %} diff --git a/_ru/scala3/book/taste-collections.md b/_ru/scala3/book/taste-collections.md new file mode 100644 index 0000000000..672e5158af --- /dev/null +++ b/_ru/scala3/book/taste-collections.md @@ -0,0 +1,161 @@ +--- +layout: multipage-overview +title: Коллекции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлен обзор основных коллекций в Scala 3. +language: ru +num: 13 +previous-page: taste-objects +next-page: taste-contextual-abstractions +--- + + +Библиотека Scala поставляется с богатым набором классов коллекций, и эти классы содержат множество методов. +Классы коллекций доступны как в неизменяемой, так и в изменяемой форме. + +## Создание списков + +Чтобы дать вам представление о том, как они работают, вот несколько примеров, в которых используется класс `List`, +являющийся неизменяемым классом связанного списка. +В этих примерах показаны различные способы создания заполненного `List`: + +{% tabs collection_1 %} +{% tab 'Scala 2 и 3' for=collection_1 %} + +```scala +val a = List(1, 2, 3) // a: List[Int] = List(1, 2, 3) + +// методы Range +val b = (1 to 5).toList // b: List[Int] = List(1, 2, 3, 4, 5) +val c = (1 to 10 by 2).toList // c: List[Int] = List(1, 3, 5, 7, 9) +val e = (1 until 5).toList // e: List[Int] = List(1, 2, 3, 4) +val f = List.range(1, 5) // f: List[Int] = List(1, 2, 3, 4) +val g = List.range(1, 10, 3) // g: List[Int] = List(1, 4, 7) +``` + +{% endtab %} +{% endtabs %} + +## Методы `List` + +В следующих примерах показаны некоторые методы, которые можно вызывать для заполненного списка. +Обратите внимание, что все эти методы являются функциональными, +а это означает, что они не изменяют коллекцию, на которой вызываются, +а вместо этого возвращают новую коллекцию с обновленными элементами. +Результат, возвращаемый каждым выражением, отображается в комментарии к каждой строке: + +{% tabs collection_2 %} +{% tab 'Scala 2 и 3' for=collection_2 %} + +```scala +// a sample list +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) + +a.drop(2) // List(30, 40, 10) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeWhile(_ < 30) // List(10, 20) + +// flatten +val a = List(List(1,2), List(3,4)) +a.flatten // List(1, 2, 3, 4) + +// map, flatMap +val nums = List("one", "two") +nums.map(_.toUpperCase) // List("ONE", "TWO") +nums.flatMap(_.toUpperCase) // List('O', 'N', 'E', 'T', 'W', 'O') +``` + +{% endtab %} +{% endtabs %} + +Эти примеры показывают, как методы “foldLeft” и “reduceLeft” используются +для суммирования значений в последовательности целых чисел: + +{% tabs collection_3 %} +{% tab 'Scala 2 и 3' for=collection_3 %} + +```scala +val firstTen = (1 to 10).toList // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + +firstTen.reduceLeft(_ + _) // 55 +firstTen.foldLeft(100)(_ + _) // 155 (100 является “начальным” значением) +``` + +{% endtab %} +{% endtabs %} + +Для классов коллекций Scala доступно гораздо больше методов, +и они продемонстрированы в главе ["Коллекции"][collections] и в [API документации][api]. + +## Кортежи + +В Scala _кортеж_ (_tuple_) — это тип, позволяющий легко поместить набор различных типов в один и тот же контейнер. +Например, используя данный case класс `Person`: + +{% tabs collection_4 %} +{% tab 'Scala 2 и 3' for=collection_4 %} + +```scala +case class Person(name: String) +``` + +{% endtab %} +{% endtabs %} + +Вот как вы создаете кортеж, который содержит `Int`, `String` и пользовательское значение `Person`: + +{% tabs collection_5 %} +{% tab 'Scala 2 и 3' for=collection_5 %} + +```scala +val t = (11, "eleven", Person("Eleven")) +``` + +{% endtab %} +{% endtabs %} + +Когда у вас есть кортеж, вы можете получить доступ к его значениям, привязав их к переменным, +или получить к ним доступ по номеру: + +{% tabs collection_6 %} +{% tab 'Scala 2 и 3' for=collection_6 %} + +```scala +t(0) // 11 +t(1) // "eleven" +t(2) // Person("Eleven") +``` + +{% endtab %} +{% endtabs %} + +Вы также можете использовать этот метод _извлечения_, чтобы присвоить поля кортежа именам переменных: + +{% tabs collection_7 %} +{% tab 'Scala 2 и 3' for=collection_7 %} + +```scala +val (num, str, person) = t + +// в результате: +// val num: Int = 11 +// val str: String = eleven +// val person: Person = Person(Eleven) +``` + +{% endtab %} +{% endtabs %} + +Кортежи хороши в тех случаях, когда вы хотите поместить коллекцию разнородных типов в небольшую структуру, похожую на коллекцию. +Дополнительные сведения о кортежах см. ["в справочной документации"][reference]. + +[collections]: {% link _overviews/scala3-book/collections-intro.md %} +[api]: https://scala-lang.org/api/3.x/ +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_ru/scala3/book/taste-contextual-abstractions.md b/_ru/scala3/book/taste-contextual-abstractions.md new file mode 100644 index 0000000000..fea81bbb84 --- /dev/null +++ b/_ru/scala3/book/taste-contextual-abstractions.md @@ -0,0 +1,79 @@ +--- +layout: multipage-overview +title: Контекстные абстракции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлено введение в контекстные абстракции в Scala 3. +language: ru +num: 14 +previous-page: taste-collections +next-page: taste-toplevel-definitions +--- + + +При определенных обстоятельствах вы можете опустить некоторые параметры вызовов методов, которые считаются повторяющимися. + +Эти параметры называются _параметрами контекста_ (_Context Parameters_), +поскольку они выводятся компилятором из контекста, окружающего вызов метода. + +Например, рассмотрим программу, которая сортирует список адресов по двум критериям: +название города, а затем название улицы. + +{% tabs contextual_1 %} +{% tab 'Scala 2 и 3' for=contextual_1 %} + +```scala +val addresses: List[Address] = ... + +addresses.sortBy(address => (address.city, address.street)) +``` + +{% endtab %} +{% endtabs %} + +Метод `sortBy` принимает функцию, которая возвращает для каждого адреса значение, чтобы сравнить его с другими адресами. +В этом случае мы передаем функцию, которая возвращает пару, содержащую название города и название улицы. + +Обратите внимание, что мы только указываем, _что_ сравнивать, но не _как_ выполнять сравнение. +Откуда алгоритм сортировки знает, как сравнивать пары `String`? + +На самом деле метод `sortBy` принимает второй параметр — параметр контекста, который выводится компилятором. +Его нет в приведенном выше примере, поскольку он предоставляется компилятором. + +Этот второй параметр реализует _способ_ сравнения. +Его удобно опустить, потому что мы знаем, что `String`-и обычно сравниваются в лексикографическом порядке. + +Однако также возможно передать параметр явно: + +{% tabs contextual_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=contextual_2 %} + +```scala +addresses.sortBy(address => (address.city, address.street))(Ordering.Tuple2(Ordering.String, Ordering.String)) +``` + +{% endtab %} +{% tab 'Scala 3' for=contextual_2 %} + +```scala +addresses.sortBy(address => (address.city, address.street))(using Ordering.Tuple2(Ordering.String, Ordering.String)) +``` + +в Scala 3 `using` в списке аргументов сигнализирует `sortBy` о явной передаче параметра контекста, избегая двусмысленности. + +{% endtab %} +{% endtabs %} + +В этом случае экземпляр `Ordering.Tuple2(Ordering.String, Ordering.String)` — это именно тот экземпляр, +который в противном случае выводится компилятором. +Другими словами, оба примера создают одну и ту же программу. + +_Контекстные абстракции_ используются, чтобы избежать повторения кода. +Они помогают разработчикам писать фрагменты кода, которые являются расширяемыми и в то же время лаконичными. + +Дополнительные сведения см. в [главе "Контекстные абстракции"][contextual] этой книги, а также в [справочной документации][reference]. + +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_ru/scala3/book/taste-control-structures.md b/_ru/scala3/book/taste-control-structures.md new file mode 100644 index 0000000000..7da0940a4f --- /dev/null +++ b/_ru/scala3/book/taste-control-structures.md @@ -0,0 +1,555 @@ +--- +layout: multipage-overview +title: Структуры управления +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: Этот раздел демонстрирует структуры управления в Scala 3. +language: ru +num: 8 +previous-page: taste-vars-data-types +next-page: taste-modeling +--- + + +В Scala есть все структуры управления, которые вы найдете в других языках программирования, +а также мощные `for` и `match` выражения: + +- `if`/`else` +- `for` циклы и выражения +- `match` выражения +- `while` циклы +- `try`/`catch` + +Эти структуры демонстрируются в следующих примерах. + +## `if`/`else` + +В Scala структура управления `if`/`else` похожа на аналогичные структуры в других языках. + +{% tabs if-else class=tabs-scala-version %} +{% tab 'Scala 2' for=if-else %} + +```scala +if (x < 0) { + println("negative") +} else if (x == 0) { + println("zero") +} else { + println("positive") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=if-else %} + +```scala +if x < 0 then + println("negative") +else if x == 0 then + println("zero") +else + println("positive") +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что это действительно _выражение_, а не _утверждение_. +Это означает, что оно возвращает значение, поэтому вы можете присвоить результат переменной: + +{% tabs if-else-expression class=tabs-scala-version %} +{% tab 'Scala 2' for=if-else-expression %} + +```scala +val x = if (a < b) { a } else { b } +``` + +{% endtab %} + +{% tab 'Scala 3' for=if-else-expression %} + +```scala +val x = if a < b then a else b +``` + +{% endtab %} +{% endtabs %} + +Как вы увидите в этой книге, _все_ управляющие структуры Scala могут использоваться как выражения. + +> Выражение возвращает результат, а утверждение — нет. +> Утверждения обычно используются для их побочных эффектов, таких как использование `println` для печати на консоли. + +## `for` циклы и выражения + +Ключевое слово `for` используется для создания цикла `for`. +В этом примере показано, как напечатать каждый элемент в `List`: + +{% tabs for-loop class=tabs-scala-version %} +{% tab 'Scala 2' for=for-loop %} + +```scala +val ints = List(1, 2, 3, 4, 5) + +for (i <- ints) println(i) +``` + +> Код `i <- ints` называется _генератором_, а код, следующий за закрывающими скобками генератора, является _телом_ цикла. + +{% endtab %} + +{% tab 'Scala 3' for=for-loop %} + +```scala +val ints = List(1, 2, 3, 4, 5) + +for i <- ints do println(i) +``` + +> Код `i <- ints` называется _генератором_, а код, следующий за ключевым словом `do`, является _телом_ цикла. + +{% endtab %} +{% endtabs %} + +### Guards + +Вы также можете использовать одно или несколько `if` выражений внутри цикла `for`. +Их называют _ограничители_ (_guards_). +В этом примере выводятся все числа `ints`, большие `2`: + +{% tabs for-guards class=tabs-scala-version %} +{% tab 'Scala 2' for=for-guards %} + +```scala +for (i <- ints if i > 2) + println(i) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-guards %} + +```scala +for + i <- ints + if i > 2 +do + println(i) +``` + +{% endtab %} +{% endtabs %} + +Вы можете использовать несколько генераторов и стражников. +Этот цикл перебирает числа от `1` до `3`, и для каждого числа также перебирает символы от `a` до `c`. +Однако у него также есть два стражника, поэтому оператор печати вызывается только тогда, +когда `i` имеет значение `2` и `j` является символом `b`: + +{% tabs for-guards-multi class=tabs-scala-version %} +{% tab 'Scala 2' for=for-guards-multi %} + +```scala +for { + i <- 1 to 3 + j <- 'a' to 'c' + if i == 2 + if j == 'b' +} { + println(s"i = $i, j = $j") // печатает: "i = 2, j = b" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-guards-multi %} + +```scala +for + i <- 1 to 3 + j <- 'a' to 'c' + if i == 2 + if j == 'b' +do + println(s"i = $i, j = $j") // печатает: "i = 2, j = b" +``` + +{% endtab %} +{% endtabs %} + +### Выражения `for` + +Ключевое слово `for` содержит в себе еще большую силу: +когда вы используете ключевое слово `yield` вместо `do`, то создаете _выражения_ `for`, +которые используются для вычислений и получения результатов. + +Несколько примеров демонстрируют это. +Используя тот же список `ints`, что и в предыдущем примере, этот код создает новый список, +в котором значение каждого элемента в новом списке в два раза превышает значение элементов в исходном: + +{% tabs for-expression_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expression_1 %} + +```` +scala> val doubles = for (i <- ints) yield i * 2 +val doubles: List[Int] = List(2, 4, 6, 8, 10) +```` + +{% endtab %} + +{% tab 'Scala 3' for=for-expression_1 %} + +```` +scala> val doubles = for i <- ints yield i * 2 +val doubles: List[Int] = List(2, 4, 6, 8, 10) +```` + +{% endtab %} +{% endtabs %} + +Синтаксис структуры управления Scala является гибким, +и это `for` выражение может быть записано несколькими другими способами, в зависимости от ваших предпочтений: + +{% tabs for-expressioni_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_2 %} + +```scala +val doubles = for (i <- ints) yield i * 2 +val doubles = for (i <- ints) yield (i * 2) +val doubles = for { i <- ints } yield (i * 2) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_2 %} + +```scala +val doubles = for i <- ints yield i * 2 // стиль показан выше +val doubles = for (i <- ints) yield i * 2 +val doubles = for (i <- ints) yield (i * 2) +val doubles = for { i <- ints } yield (i * 2) +``` + +{% endtab %} +{% endtabs %} + +В этом примере показано, как сделать первый символ в каждой строке списка заглавными: + +{% tabs for-expressioni_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_3 %} + +```scala +val names = List("chris", "ed", "maurice") +val capNames = for (name <- names) yield name.capitalize +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_3 %} + +```scala +val names = List("chris", "ed", "maurice") +val capNames = for name <- names yield name.capitalize +``` + +{% endtab %} +{% endtabs %} + +Наконец, нижеследующее выражение `for` перебирает список строк +и возвращает длину каждой строки, но только если эта длина больше `4`: + +{% tabs for-expressioni_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_4 %} + +```scala +val fruits = List("apple", "banana", "lime", "orange") + +val fruitLengths = + for (f <- fruits if f.length > 4) yield f.length + +// fruitLengths: List[Int] = List(5, 6, 6) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_4 %} + +```scala +val fruits = List("apple", "banana", "lime", "orange") + +val fruitLengths = for + f <- fruits + if f.length > 4 +yield + // здесь можно использовать + // несколько строк кода + f.length + +// fruitLengths: List[Int] = List(5, 6, 6) +``` + +{% endtab %} +{% endtabs %} + +`for` циклы и выражения более подробно рассматриваются в разделах этой книги ["Структуры управления"][control] +и в [справочной документации]({{ site.scala3ref }}/other-new-features/control-syntax.html). + +## `match` выражения + +В Scala есть выражение `match`, которое в своем самом простом использовании похоже на `switch` оператор Java: + +{% tabs match class=tabs-scala-version %} +{% tab 'Scala 2' for=match %} + +```scala +val i = 1 + +// позже в этом коде ... +i match { + case 1 => println("one") + case 2 => println("two") + case _ => println("other") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match %} + +```scala +val i = 1 + +// позже в этом коде ... +i match + case 1 => println("one") + case 2 => println("two") + case _ => println("other") +``` + +{% endtab %} +{% endtabs %} + +Однако `match` на самом деле это выражение, означающее, +что оно возвращает результат на основе совпадения с шаблоном, который вы можете привязать к переменной: + +{% tabs match-expression_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_1 %} + +```scala +val result = i match { + case 1 => "one" + case 2 => "two" + case _ => "other" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match-expression_1 %} + +```scala +val result = i match + case 1 => "one" + case 2 => "two" + case _ => "other" +``` + +{% endtab %} +{% endtabs %} + +`match` не ограничивается работой только с целочисленными значениями, его можно использовать с любым типом данных: + +{% tabs match-expression_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_2 %} + +```scala +val p = Person("Fred") + +// позже в этом коде ... +p match { + case Person(name) if name == "Fred" => + println(s"$name says, Yubba dubba doo") + + case Person(name) if name == "Bam Bam" => + println(s"$name says, Bam bam!") + + case _ => println("Watch the Flintstones!") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match-expression_2 %} + +```scala +val p = Person("Fred") + +// позже в этом коде ... +p match + case Person(name) if name == "Fred" => + println(s"$name says, Yubba dubba doo") + + case Person(name) if name == "Bam Bam" => + println(s"$name says, Bam bam!") + + case _ => println("Watch the Flintstones!") +``` + +{% endtab %} +{% endtabs %} + +На самом деле `match` выражение можно использовать для проверки переменной на множестве различных типов шаблонов. +В этом примере показано (а) как использовать `match` выражение в качестве тела метода и (б) как сопоставить все показанные различные типы: + +{% tabs match-expression_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_3 %} + +```scala +// getClassAsString - метод, принимающий один параметр любого типа. +def getClassAsString(x: Any): String = x match { + case s: String => s"'$s' is a String" + case i: Int => "Int" + case d: Double => "Double" + case l: List[_] => "List" + case _ => "Unknown" +} + +// примеры +getClassAsString(1) // Int +getClassAsString("hello") // 'hello' is a String +getClassAsString(List(1, 2, 3)) // List +``` + +Поскольку метод `getClassAsString` принимает значение параметра типа `Any`, его можно разложить по любому шаблону. + +{% endtab %} +{% tab 'Scala 3' for=match-expression_3 %} + +```scala +// getClassAsString - метод, принимающий один параметр любого типа. +def getClassAsString(x: Matchable): String = x match + case s: String => s"'$s' is a String" + case i: Int => "Int" + case d: Double => "Double" + case l: List[?] => "List" + case _ => "Unknown" + +// примеры +getClassAsString(1) // Int +getClassAsString("hello") // 'hello' is a String +getClassAsString(List(1, 2, 3)) // List +``` + +Метод `getClassAsString` принимает в качестве параметра значение типа [Matchable]({{ site.scala3ref }}/other-new-features/matchable.html), +которое может быть любым типом, поддерживающим сопоставление с образцом +(некоторые типы не поддерживают сопоставление с образцом, поскольку это может нарушить инкапсуляцию). + +{% endtab %} +{% endtabs %} + +Сопоставление с образцом в Scala гораздо _шире_. +Шаблоны могут быть вложены друг в друга, результаты шаблонов могут быть связаны, +а сопоставление шаблонов может даже определяться пользователем. +Дополнительные сведения см. в примерах сопоставления с образцом в главе ["Структуры управления"][control]. + +## `try`/`catch`/`finally` + +Структура управления Scala `try`/`catch`/`finally` позволяет перехватывать исключения. +Она похожа на аналогичную структуру в Java, но её синтаксис соответствует `match` выражениям: + +{% tabs try class=tabs-scala-version %} +{% tab 'Scala 2' for=try %} + +```scala +try { + writeTextToFile(text) +} catch { + case ioe: IOException => println("Got an IOException.") + case nfe: NumberFormatException => println("Got a NumberFormatException.") +} finally { + println("Clean up your resources here.") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=try %} + +```scala +try + writeTextToFile(text) +catch + case ioe: IOException => println("Got an IOException.") + case nfe: NumberFormatException => println("Got a NumberFormatException.") +finally + println("Clean up your resources here.") +``` + +{% endtab %} +{% endtabs %} + +## Циклы `while` + +В Scala также есть конструкция цикла `while`. +Его однострочный синтаксис выглядит так: + +{% tabs while_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=while_1 %} + +```scala +while (x >= 0) { x = f(x) } +``` + +{% endtab %} + +{% tab 'Scala 3' for=while_1 %} + +```scala +while x >= 0 do x = f(x) +``` +Scala 3 по-прежнему поддерживает синтаксис Scala 2 для обратной совместимости. + +{% endtab %} +{% endtabs %} + +Синтаксис `while` многострочного цикла выглядит следующим образом: + +{% tabs while_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=while_2 %} + +```scala +var x = 1 + +while (x < 3) { + println(x) + x += 1 +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=while_2 %} + +```scala +var x = 1 + +while + x < 3 +do + println(x) + x += 1 +``` + +{% endtab %} +{% endtabs %} + +## Пользовательские структуры управления + +Благодаря таким функциям, как параметры по имени, инфиксная нотация, плавные интерфейсы, необязательные круглые скобки, +методы расширения и функции высшего порядка, вы также можете создавать свой собственный код, +который работает так же, как управляющая структура. +Вы узнаете об этом больше в разделе ["Структуры управления"][control]. + +[control]: {% link _overviews/scala3-book/control-structures.md %} diff --git a/_ru/scala3/book/taste-functions.md b/_ru/scala3/book/taste-functions.md new file mode 100644 index 0000000000..f83da448e7 --- /dev/null +++ b/_ru/scala3/book/taste-functions.md @@ -0,0 +1,90 @@ +--- +layout: multipage-overview +title: Функции первого класса +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлено введение в функции в Scala 3. +language: ru +num: 11 +previous-page: taste-methods +next-page: taste-objects +--- + +Scala обладает большинством возможностей, которые вы ожидаете от функционального языка программирования, в том числе: + +- Lambdas (анонимные функции) +- Функции высшего порядка (HOF) +- Неизменяемые коллекции в стандартной библиотеке + +Лямбда-выражения, также известные как _анонимные функции_, играют важную роль в том, чтобы ваш код был кратким, но удобочитаемым. + +Метод `map` класса `List` является типичным примером функции высшего порядка — +функции, которая принимает функцию в качестве параметра. + +Эти два примера эквивалентны и показывают, как умножить каждое число в списке на `2`, передав лямбда в метод `map`: + + +{% tabs function_1 %} +{% tab 'Scala 2 и 3' for=function_1 %} +```scala +val a = List(1, 2, 3).map(i => i * 2) // List(2,4,6) +val b = List(1, 2, 3).map(_ * 2) // List(2,4,6) +``` +{% endtab %} +{% endtabs %} + +Примеры выше также эквивалентны следующему коду, в котором вместо лямбда используется метод `double`: + + +{% tabs function_2 %} +{% tab 'Scala 2 и 3' for=function_2 %} +```scala +def double(i: Int): Int = i * 2 + +val a = List(1, 2, 3).map(i => double(i)) // List(2,4,6) +val b = List(1, 2, 3).map(double) // List(2,4,6) +``` +{% endtab %} +{% endtabs %} + +> Если вы еще раньше не видели метод `map`, он применяет заданную функцию к каждому элементу в списке, +> создавая новый список, содержащий результирующие значения. + +Передача лямбда-выражений функциям высшего порядка в классах коллекций (таких, как `List`) — +это часть работы со Scala, которую вы будете делать каждый день. + + +## Неизменяемые коллекции + +Когда вы работаете с неизменяемыми коллекциями, такими как `List`, `Vector`, +а также с неизменяемыми классами `Map` и `Set`, важно знать, +что эти функции не изменяют коллекцию, для которой они вызываются; +вместо этого они возвращают новую коллекцию с обновленными данными. +В результате также принято объединять их вместе в “свободном” стиле для решения проблем. + +Например, в этом примере показано, как отфильтровать коллекцию дважды, +а затем умножить каждый элемент в оставшейся коллекции: + + +{% tabs function_3 %} +{% tab 'Scala 2 и 3' for=function_3 %} +```scala +// пример списка +val nums = (1 to 10).toList // List(1,2,3,4,5,6,7,8,9,10) + +// методы могут быть сцеплены вместе +val x = nums.filter(_ > 3) + .filter(_ < 7) + .map(_ * 10) + +// result: x == List(40, 50, 60) +``` +{% endtab %} +{% endtabs %} + +В дополнение к функциям высшего порядка, используемым в стандартной библиотеке, +вы также можете [создавать свои собственные функции][higher-order]. + +[higher-order]: {% link _overviews/scala3-book/fun-hofs.md %} diff --git a/_ru/scala3/book/taste-hello-world.md b/_ru/scala3/book/taste-hello-world.md new file mode 100644 index 0000000000..77442e43ca --- /dev/null +++ b/_ru/scala3/book/taste-hello-world.md @@ -0,0 +1,205 @@ +--- +layout: multipage-overview +title: Пример 'Hello, World!' +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом примере демонстрируется пример 'Hello, World!' на Scala 3. +language: ru +num: 5 +previous-page: taste-intro +next-page: taste-repl +--- + +> **Подсказка**: в следующих примерах попробуйте выбрать предпочтительную для вас версию Scala. +> + +## Ваша первая Scala-программа + + +Пример “Hello, World!” на Scala выглядит следующим образом. +Сначала поместите этот код в файл с именем _hello.scala_: + + +{% tabs hello-world-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-demo %} +```scala +object hello { + def main(args: Array[String]) = { + println("Hello, World!") + } +} +``` +> В этом коде мы определили метод с именем `main` внутри Scala `object`-а с именем `hello`. +> `object` в Scala похож на `class`, но определяет экземпляр singleton, который можно передать. +> `main` принимает входной параметр с именем `args`, который должен иметь тип `Array[String]` +> (`args` пока можно игнорировать). + +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} +```scala +@main def hello() = println("Hello, World!") +``` +> В этом коде `hello` - это метод. +> Он определяется с помощью `def` и объявляется в качестве основного метода с помощью аннотации `@main`. +> Он выводит строку "Hello, World!" на стандартный вывод (STDOUT) с помощью метода `println`. + +{% endtab %} + +{% endtabs %} + + +Затем скомпилируйте код с помощью `scalac`: + +```bash +$ scalac hello.scala +``` + +Если вы переходите на Scala с Java: `scalac` похоже на `javac`, эта команда создает несколько файлов: + + +{% tabs hello-world-outputs class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-outputs %} +```bash +$ ls -1 +hello$.class +hello.class +hello.scala +``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-outputs %} +```bash +$ ls -1 +hello$package$.class +hello$package.class +hello$package.tasty +hello.scala +hello.class +hello.tasty +``` +{% endtab %} + +{% endtabs %} + + +Как и Java, файлы _.class_ представляют собой файлы байт-кода, и они готовы к запуску в JVM. + +Теперь вы можете запустить метод `hello` командой `scala`: + +```bash +$ scala hello +Hello, World! +``` + +Если запуск прошел успешно, поздравляем, вы только что скомпилировали и запустили свое первое приложение Scala. + +> Дополнительную информацию о sbt и других инструментах, упрощающих разработку на Scala, можно найти в главе [Инструменты Scala][scala_tools]. + +## Запрос пользовательского ввода + +В нашем следующем примере давайте спросим имя пользователя, прежде чем приветствовать его! + +Есть несколько способов прочитать ввод из командной строки, но самый простой способ — +использовать метод `readLine` из объекта _scala.io.StdIn_. +Чтобы использовать этот метод, вам нужно сначала его импортировать, например: + +{% tabs import-readline %} +{% tab 'Scala 2 и 3' for=import-readline %} +```scala +import scala.io.StdIn.readLine +``` +{% endtab %} +{% endtabs %} + +Чтобы продемонстрировать, как это работает, давайте создадим небольшой пример. +Поместите этот исходный код в файл с именем _helloInteractive.scala_: + + +{% tabs hello-world-interactive class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-interactive %} +```scala +import scala.io.StdIn.readLine + +object helloInteractive { + + def main(args: Array[String]) = { + println("Please enter your name:") + val name = readLine() + + println("Hello, " + name + "!") + } + +} +``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-interactive %} +```scala +import scala.io.StdIn.readLine + +@main def helloInteractive() = + println("Please enter your name:") + val name = readLine() + + println("Hello, " + name + "!") +``` +{% endtab %} + +{% endtabs %} + + +В этом коде мы сохраняем результат из `readLine` в переменную с именем `name`, +затем используем оператор над строками `+` для соединения `"Hello, "` с `name` и `"!"`, создавая одно единственное строковое значение. + +> Вы можете узнать больше об использовании val, прочитав главу [Переменные и типы данных](/scala3/book/taste-vars-data-types.html). + +Затем скомпилируйте код с помощью `scalac`: + +```bash +$ scalac helloInteractive.scala +``` + +Затем запустите его с помощью `scala helloInteractive`. На этот раз программа сделает паузу после запроса вашего имени +и подождет, пока вы не наберете имя и не нажмете клавишу возврата на клавиатуре. +Выглядит это так: + +```bash +$ scala helloInteractive +Please enter your name: +▌ +``` + +Когда вы вводите свое имя в "приглашении", окончательное взаимодействие должно выглядеть так: + +```bash +$ scala helloInteractive +Please enter your name: +Alvin Alexander +Hello, Alvin Alexander! +``` + +### Примечание об импорте + +Как вы ранее видели, иногда определенные методы или другие типы определений, которые мы увидим позже, недоступны, +если вы не используете подобное предложение `import`: + +{% tabs import-readline-2 %} +{% tab 'Scala 2 и 3' for=import-readline-2 %} +```scala +import scala.io.StdIn.readLine +``` +{% endtab %} +{% endtabs %} + +Импорт помогает писать и распределять код несколькими способами: + - вы можете поместить код в несколько файлов, чтобы избежать беспорядка и облегчить навигацию в больших проектах. + - вы можете использовать библиотеку кода, возможно, написанную кем-то другим, которая имеет полезную функциональность. + - вы видите, откуда берется определенное определение (особенно если оно не было записано в текущем файле). + +[scala_tools]: {% link _overviews/scala3-book/scala-tools.md %} diff --git a/_ru/scala3/book/taste-intro.md b/_ru/scala3/book/taste-intro.md new file mode 100644 index 0000000000..58e15d8e22 --- /dev/null +++ b/_ru/scala3/book/taste-intro.md @@ -0,0 +1,31 @@ +--- +layout: multipage-overview +title: Почувствуй Scala +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе представлен общий обзор основных возможностей языка программирования Scala 3. +language: ru +num: 4 +previous-page: why-scala-3 +next-page: taste-hello-world +--- + + +В этой главе представлен краткий обзор основных возможностей языка программирования Scala 3. +После начального ознакомления остальная часть книги содержит более подробную информацию об описанных функциях, +а [справочная документация][reference] содержит массу подробностей. + +## Настройка Скала + +На протяжении этой главы и остальной части книги мы рекомендуем вам пробовать примеры, скопировав их или набрав вручную. +Инструменты, необходимые для работы с примерами на вашем компьютере, можно установить, +следуя нашему [руководству для началы работы со Scala][get-started]. + +> В качестве альтернативы вы можете запустить примеры в веб-браузере с помощью [Scastie](https://scastie.scala-lang.org), +> полного онлайн-редактора и исполнителя кода для Scala. + + +[reference]: {{ site.scala3ref }}/overview.html +[get-started]: {% link _overviews/getting-started/install-scala.md %} diff --git a/_ru/scala3/book/taste-methods.md b/_ru/scala3/book/taste-methods.md new file mode 100644 index 0000000000..c881761826 --- /dev/null +++ b/_ru/scala3/book/taste-methods.md @@ -0,0 +1,167 @@ +--- +layout: multipage-overview +title: Методы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлено введение в определение и использование методов в Scala 3. +language: ru +num: 10 +previous-page: taste-modeling +next-page: taste-functions +--- + + +## Методы в Scala + +Классы Scala, case-классы, трейты, перечисления и объекты могут содержать методы. +Синтаксис простого метода выглядит так: + +{% tabs method_1 %} +{% tab 'Scala 2 и 3' for=method_1 %} +```scala +def methodName(param1: Type1, param2: Type2): ReturnType = + // тело метода + // находится здесь +``` +{% endtab %} +{% endtabs %} + +Вот несколько примеров: + +{% tabs method_2 %} +{% tab 'Scala 2 и 3' for=method_2 %} +```scala +def sum(a: Int, b: Int): Int = a + b +def concatenate(s1: String, s2: String): String = s1 + s2 +``` +{% endtab %} +{% endtabs %} + +Вам не нужно объявлять возвращаемый тип метода, поэтому можно написать эти методы следующим образом, если хотите: + +{% tabs method_3 %} +{% tab 'Scala 2 и 3' for=method_3 %} +```scala +def sum(a: Int, b: Int) = a + b +def concatenate(s1: String, s2: String) = s1 + s2 +``` +{% endtab %} +{% endtabs %} + +Вот как эти методы вызываются: + +{% tabs method_4 %} +{% tab 'Scala 2 и 3' for=method_4 %} +```scala +val x = sum(1, 2) +val y = concatenate("foo", "bar") +``` +{% endtab %} +{% endtabs %} + +Вот пример многострочного метода: + +{% tabs method_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_5 %} +```scala +def getStackTraceAsString(t: Throwable): String = { + val sw = new StringWriter + t.printStackTrace(new PrintWriter(sw)) + sw.toString +} +``` +{% endtab %} + +{% tab 'Scala 3' for=method_5 %} +```scala +def getStackTraceAsString(t: Throwable): String = + val sw = new StringWriter + t.printStackTrace(new PrintWriter(sw)) + sw.toString +``` +{% endtab %} +{% endtabs %} + +Параметры метода также могут иметь значения по умолчанию. +В этом примере параметр `timeout` имеет значение по умолчанию `5000`: + +{% tabs method_6 %} +{% tab 'Scala 2 и 3' for=method_6 %} +```scala +def makeConnection(url: String, timeout: Int = 5000): Unit = + println(s"url=$url, timeout=$timeout") +``` +{% endtab %} +{% endtabs %} + +Поскольку в объявлении метода указано значение по умолчанию для `timeout`, метод можно вызывать двумя способами: + +{% tabs method_7 %} +{% tab 'Scala 2 и 3' for=method_7 %} +```scala +makeConnection("https://localhost") // url=http://localhost, timeout=5000 +makeConnection("https://localhost", 2500) // url=http://localhost, timeout=2500 +``` +{% endtab %} +{% endtabs %} + +Scala также поддерживает использование _именованных параметров_ при вызове метода, +поэтому вы можете вызвать этот метод, если хотите, вот так: + +{% tabs method_8 %} +{% tab 'Scala 2 и 3' for=method_8 %} +```scala +makeConnection( + url = "https://localhost", + timeout = 2500 +) +``` +{% endtab %} +{% endtabs %} + +Именованные параметры особенно полезны, когда несколько параметров метода имеют один и тот же тип. +Глядя на этот метод можно задаться вопросом, +какие параметры установлены в `true` или `false`: + +{% tabs method_9 %} +{% tab 'Scala 2 и 3' for=method_9 %} + +```scala +engage(true, true, true, false) +``` + +{% endtab %} +{% endtabs %} + +Ключевое слово `extension` объявляет о намерении определить один или несколько методов расширения для параметра, +заключенного в круглые скобки. +Как показано в этом примере, параметр `s` типа `String` можно затем использовать в теле методов расширения. + +В следующем примере показано, как добавить метод `makeInt` в класс `String`. +Здесь `makeInt` принимает параметр с именем `radix`. +Код не учитывает возможные ошибки преобразования строки в целое число, +но, опуская эту деталь, примеры показывают, как работают методы расширения: + +{% tabs extension %} +{% tab 'Только в Scala 3' %} + +```scala +extension (s: String) + def makeInt(radix: Int): Int = Integer.parseInt(s, radix) + +"1".makeInt(2) // Int = 1 +"10".makeInt(2) // Int = 2 +"100".makeInt(2) // Int = 4 +``` + +{% endtab %} +{% endtabs %} + +## Смотрите также + +Методы Scala могут быть гораздо более мощными: они могут принимать параметры типа и параметры контекста. +Методы подробно описаны в разделе ["Моделирование предметной области"][data-1]. + +[data-1]: {% link _overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_ru/scala3/book/taste-modeling.md b/_ru/scala3/book/taste-modeling.md new file mode 100644 index 0000000000..deede29e6a --- /dev/null +++ b/_ru/scala3/book/taste-modeling.md @@ -0,0 +1,421 @@ +--- +layout: multipage-overview +title: Моделирование данных +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлено введение в моделирование данных в Scala 3. +language: ru +num: 9 +previous-page: taste-control-structures +next-page: taste-methods +--- + + +Scala поддерживает как функциональное программирование (ФП), так и объектно-ориентированное программирование (ООП), +а также слияние этих двух парадигм. В этом разделе представлен краткий обзор моделирования данных в ООП и ФП. + +## Моделирование данных в ООП + +При написании кода в стиле ООП двумя вашими основными инструментами для инкапсуляции данных будут _трейты_ и _классы_. + +### Трейты + +Трейты Scala можно использовать как простые интерфейсы, +но они также могут содержать абстрактные и конкретные методы и поля, а также параметры, как и классы. +Они предоставляют вам отличный способ организовать поведение в небольшие модульные блоки. +Позже, когда вы захотите создать конкретные реализации атрибутов и поведения, +классы и объекты могут расширять трейты, смешивая столько трейтов, +сколько необходимо для достижения желаемого поведения. + +В качестве примера того, как использовать трейты в качестве интерфейсов, +вот три трейта, которые определяют хорошо организованное и модульное поведение для животных, таких как собаки и кошки: + +{% tabs traits class=tabs-scala-version %} +{% tab 'Scala 2' for=traits %} + +```scala +trait Speaker { + def speak(): String // тело метода отсутствует, поэтому метод абстрактный +} + +trait TailWagger { + def startTail(): Unit = println("tail is wagging") + def stopTail(): Unit = println("tail is stopped") +} + +trait Runner { + def startRunning(): Unit = println("I’m running") + def stopRunning(): Unit = println("Stopped running") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits %} + +```scala +trait Speaker: + def speak(): String // тело метода отсутствует, поэтому метод абстрактный + +trait TailWagger: + def startTail(): Unit = println("tail is wagging") + def stopTail(): Unit = println("tail is stopped") + +trait Runner: + def startRunning(): Unit = println("I’m running") + def stopRunning(): Unit = println("Stopped running") +``` + +{% endtab %} +{% endtabs %} + +Учитывая эти трейты, вот класс `Dog`, который их все расширяет, +обеспечивая при этом поведение для абстрактного метода `speak`: + +{% tabs traits-class class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-class %} + +```scala +class Dog(name: String) extends Speaker with TailWagger with Runner { + def speak(): String = "Woof!" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-class %} + +```scala +class Dog(name: String) extends Speaker, TailWagger, Runner: + def speak(): String = "Woof!" +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, как класс расширяет трейты с помощью ключевого слова `extends`. + +Точно так же вот класс `Cat`, реализующий те же трейты, +а также переопределяющий два конкретных метода, которые он наследует: + +{% tabs traits-override class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-override %} + +```scala +class Cat(name: String) extends Speaker with TailWagger with Runner { + def speak(): String = "Meow" + override def startRunning(): Unit = println("Yeah ... I don’t run") + override def stopRunning(): Unit = println("No need to stop") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-override %} + +```scala +class Cat(name: String) extends Speaker, TailWagger, Runner: + def speak(): String = "Meow" + override def startRunning(): Unit = println("Yeah ... I don’t run") + override def stopRunning(): Unit = println("No need to stop") +``` + +{% endtab %} +{% endtabs %} + +Примеры ниже показывают, как используются эти классы: + +{% tabs traits-use class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-use %} + +```scala +val d = new Dog("Rover") +println(d.speak()) // печатает "Woof!" + +val c = new Cat("Morris") +println(c.speak()) // "Meow" +c.startRunning() // "Yeah ... I don’t run" +c.stopRunning() // "No need to stop" +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-use %} + +```scala +val d = Dog("Rover") +println(d.speak()) // печатает "Woof!" + +val c = Cat("Morris") +println(c.speak()) // "Meow" +c.startRunning() // "Yeah ... I don’t run" +c.stopRunning() // "No need to stop" +``` + +{% endtab %} +{% endtabs %} + +Если этот код имеет смысл — отлично, вам удобно использовать трейты в качестве интерфейсов. +Если нет, не волнуйтесь, они более подробно описаны в главе ["Моделирование предметной области"][data-1]. + + +### Классы + +Классы Scala используются в программировании в стиле ООП. +Вот пример класса, который моделирует "человека". +В ООП поля обычно изменяемы, поэтому оба, `firstName` и `lastName` объявлены как `var` параметры: + +{% tabs class_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=class_1 %} + +```scala +class Person(var firstName: String, var lastName: String) { + def printFullName() = println(s"$firstName $lastName") +} + +val p = new Person("John", "Stephens") +println(p.firstName) // "John" +p.lastName = "Legend" +p.printFullName() // "John Legend" +``` + +{% endtab %} + +{% tab 'Scala 3' for=class_1 %} + +```scala +class Person(var firstName: String, var lastName: String): + def printFullName() = println(s"$firstName $lastName") + +val p = Person("John", "Stephens") +println(p.firstName) // "John" +p.lastName = "Legend" +p.printFullName() // "John Legend" +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что объявление класса создает конструктор: + +{% tabs class_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=class_2 %} + +```scala +// код использует конструктор из объявления класса +val p = new Person("John", "Stephens") +``` + +{% endtab %} + +{% tab 'Scala 3' for=class_2 %} + +```scala +// код использует конструктор из объявления класса +val p = Person("John", "Stephens") +``` + +{% endtab %} +{% endtabs %} + +Конструкторы и другие темы, связанные с классами, рассматриваются в главе ["Моделирование предметной области"][data-1]. + +## Моделирование данных в ФП + +При написании кода в стиле ФП вы будете использовать следующие понятия: + +- Алгебраические типы данных для определения данных. +- Трейты для функциональности данных. + +### Перечисления и суммированные типы + +Суммированные типы (_sum types_) — это один из способов моделирования алгебраических типов данных (ADT) в Scala. + +Они используются, когда данные могут быть представлены с различными вариантами. + +Например, у пиццы есть три основных атрибута: + +- Размер корки +- Тип корки +- Начинки +- +Они кратко смоделированы с помощью перечислений, +которые представляют собой суммированные типы, содержащие только одноэлементные значения: + +{% tabs enum_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_1 %} + +В Scala 2 `sealed` классы и `case object` объединяются для определения перечисления: + +```scala +sealed abstract class CrustSize +object CrustSize { + case object Small extends CrustSize + case object Medium extends CrustSize + case object Large extends CrustSize +} + +sealed abstract class CrustType +object CrustType { + case object Thin extends CrustType + case object Thick extends CrustType + case object Regular extends CrustType +} + +sealed abstract class Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping +} +``` + +{% endtab %} +{% tab 'Scala 3' for=enum_1 %} + +Scala 3 предлагает конструкцию `enum` для определения перечислений: + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +Когда у вас есть перечисление, вы можете импортировать его элементы как обычные значения: + +{% tabs enum_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_2 %} + +```scala +import CrustSize._ +val currentCrustSize = Small + +// перечисления в сопоставлении с шаблоном +currentCrustSize match { + case Small => println("Small crust size") + case Medium => println("Medium crust size") + case Large => println("Large crust size") +} + +// перечисления в операторе `if` +if (currentCrustSize == Small) println("Small crust size") +``` + +{% endtab %} +{% tab 'Scala 3' for=enum_2 %} + +```scala +import CrustSize.* +val currentCrustSize = Small + +// перечисления в сопоставлении с шаблоном +currentCrustSize match + case Small => println("Small crust size") + case Medium => println("Medium crust size") + case Large => println("Large crust size") + +// перечисления в операторе `if` +if currentCrustSize == Small then println("Small crust size") +``` + +{% endtab %} +{% endtabs %} + +Вот еще один пример того, как создать суммированные типы с помощью Scala, +это не будет называться перечислением, потому что у случая `Succ` есть параметры: + +{% tabs enum_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_3 %} + +```scala +sealed abstract class Nat +object Nat { + case object Zero extends Nat + case class Succ(pred: Nat) extends Nat +} +``` + +Суммированные типы подробно рассматриваются в разделе ["Моделирование предметной области"]({% link _overviews/scala3-book/domain-modeling-tools.md %}) этой книги. + +{% endtab %} +{% tab 'Scala 3' for=enum_3 %} + +```scala +enum Nat: + case Zero + case Succ(pred: Nat) +``` + +Перечисления подробно рассматриваются в разделе ["Моделирование предметной области"]({% link _overviews/scala3-book/domain-modeling-tools.md %}) этой книги +и в [справочной документации]({{ site.scala3ref }}/enums/enums.html). + +{% endtab %} +{% endtabs %} + +### Продуктовые типы + +Тип продукта — это алгебраический тип данных (ADT), который имеет только одну форму, +например, одноэлементный объект, представленный в Scala `case object`; +или неизменяемая структура с доступными полями, представленная `case class`. + +`case class` обладает всеми функциями класса, а также содержит встроенные дополнительные функции, +которые делают его полезным для функционального программирования. +Когда компилятор видит ключевое слово `case` перед `class`, то применяет следующие эффекты и преимущества: + +- Параметры конструктора `case class` по умолчанию являются общедоступными полями `val`, поэтому поля неизменяемы, + а методы доступа генерируются для каждого параметра. +- Генерируется метод `unapply`, который позволяет использовать `case class` в выражениях match различными способами. +- В классе создается метод `copy`. Он позволяет создавать копии объекта без изменения исходного. +- Создаются методы `equals` и `hashCode` для реализации структурного равенства. +- Генерируется метод по умолчанию `toString`, полезный для отладки. + +Вы _можете_ вручную добавить все эти методы в класс самостоятельно, +но, поскольку эти функции так часто используются в функциональном программировании, +использование case класса гораздо удобнее. + +Этот код демонстрирует несколько функций `case class`: + +{% tabs case-class %} +{% tab 'Scala 2 и 3' for=case-class %} + +```scala +// определение case class +case class Person( + name: String, + vocation: String +) + +// создание экземпляра case class +val p = Person("Reginald Kenneth Dwight", "Singer") + +// полезный метод toString +p // : Person = Person(Reginald Kenneth Dwight,Singer) + +// можно получить доступ к неизменяемым полям +p.name // "Reginald Kenneth Dwight" +p.name = "Joe" // error: can’t reassign a val field + +// при необходимости внести изменения используйте метод `copy` +// для “update as you copy” +val p2 = p.copy(name = "Elton John") +p2 // : Person = Person(Elton John,Singer) +``` + +{% endtab %} +{% endtabs %} + +Дополнительные сведения о `case` классах см. в разделах ["Моделирование предметной области"][data-1]. + +[data-1]: {% link _overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_ru/scala3/book/taste-objects.md b/_ru/scala3/book/taste-objects.md new file mode 100644 index 0000000000..a244c7cfa2 --- /dev/null +++ b/_ru/scala3/book/taste-objects.md @@ -0,0 +1,153 @@ +--- +layout: multipage-overview +title: Одноэлементные объекты +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлено введение в использование одноэлементных объектов в Scala 3. +language: ru +num: 12 +previous-page: taste-functions +next-page: taste-collections +--- + + +В Scala ключевое слово `object` создает объект Singleton (паттерн проектирования "Одиночка"). +Другими словами, объект определяет класс, который имеет только один экземпляр. + +Объекты имеют несколько применений: + +- Они используются для создания коллекций служебных методов. +- _Сопутствующий объект_ — это объект с тем же именем, что и у класса, определенного в этом же файле. + В этой ситуации такой класс также называется _сопутствующим классом_. +- Они используются для реализации трейтов для создания _модулей_. + + +## “Полезные” методы + +Поскольку `object` является "одиночкой", к его методам можно обращаться так же, как к статичным методам в Java классе. +Например, этот объект `StringUtils` содержит небольшой набор методов, связанных со строками: + +{% tabs object_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_1 %} +```scala +object StringUtils { + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty + def leftTrim(s: String): String = s.replaceAll("^\\s+", "") + def rightTrim(s: String): String = s.replaceAll("\\s+$", "") +} +``` +{% endtab %} + +{% tab 'Scala 3' for=object_1 %} +```scala +object StringUtils: + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty + def leftTrim(s: String): String = s.replaceAll("^\\s+", "") + def rightTrim(s: String): String = s.replaceAll("\\s+$", "") +``` +{% endtab %} +{% endtabs %} + +Поскольку `StringUtils` - это "одиночка", его методы можно вызывать непосредственно для объекта: + +{% tabs object_2 %} +{% tab 'Scala 2 и 3' for=object_2 %} +```scala +val x = StringUtils.isNullOrEmpty("") // true +val x = StringUtils.isNullOrEmpty("a") // false +``` +{% endtab %} +{% endtabs %} + +## Сопутствующие объекты + +Сопутствующие класс или объект могут получить доступ к закрытым членам своего компаньона. +Используйте сопутствующий объект для методов и значений, которые не относятся к экземплярам сопутствующего класса. + +В этом примере показано, как метод `area` в сопутствующем классе +может получить доступ к приватному методу `calculateArea` в своем сопутствующем объекте: + +{% tabs object_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_3 %} +```scala +import scala.math._ + +class Circle(radius: Double) { + import Circle._ + def area: Double = calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = + Pi * pow(radius, 2.0) +} + +val circle1 = new Circle(5.0) +circle1.area // Double = 78.53981633974483 +``` +{% endtab %} + +{% tab 'Scala 3' for=object_3 %} +```scala +import scala.math.* + +class Circle(radius: Double): + import Circle.* + def area: Double = calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = + Pi * pow(radius, 2.0) + +val circle1 = Circle(5.0) +circle1.area // Double = 78.53981633974483 +``` +{% endtab %} +{% endtabs %} + +## Создание модулей из трейтов + +Объекты также можно использовать для реализации трейтов для создания модулей. +Эта техника берет две трейта и объединяет их для создания конкретного `object`-а: + +{% tabs object_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_4 %} +```scala +trait AddService { + def add(a: Int, b: Int) = a + b +} + +trait MultiplyService { + def multiply(a: Int, b: Int) = a * b +} + +// реализация трейтов выше в качестве конкретного объекта +object MathService extends AddService with MultiplyService + +// использование объекта +import MathService._ +println(add(1,1)) // 2 +println(multiply(2,2)) // 4 +``` +{% endtab %} + +{% tab 'Scala 3' for=object_4 %} +```scala +trait AddService: + def add(a: Int, b: Int) = a + b + +trait MultiplyService: + def multiply(a: Int, b: Int) = a * b + +// реализация трейтов выше в качестве конкретного объекта +object MathService extends AddService, MultiplyService + +// использование объекта +import MathService.* +println(add(1,1)) // 2 +println(multiply(2,2)) // 4 +``` +{% endtab %} +{% endtabs %} diff --git a/_ru/scala3/book/taste-repl.md b/_ru/scala3/book/taste-repl.md new file mode 100644 index 0000000000..e45dc0e8cc --- /dev/null +++ b/_ru/scala3/book/taste-repl.md @@ -0,0 +1,93 @@ +--- +layout: multipage-overview +title: REPL +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлено введение в Scala REPL. +language: ru +num: 6 +previous-page: taste-hello-world +next-page: taste-vars-data-types +--- + +Scala REPL (“Read-Evaluate-Print-Loop”) - это интерпретатор командной строки, +который используется в качестве “игровой площадки” для тестирования Scala кода. +Для того чтобы запустить сеанс REPL, надо выполнить команду `scala` или `scala3` в зависимости от операционной системы, +затем будет выведено приглашение “Welcome”, подобное этому: + +{% tabs command-line class=tabs-scala-version %} + +{% tab 'Scala 2' for=command-line %} +```bash +$ scala +Welcome to Scala {{site.scala-version}} (OpenJDK 64-Bit Server VM, Java 1.8.0_342). +Type in expressions for evaluation. Or try :help. + +scala> _ +``` +{% endtab %} + +{% tab 'Scala 3' for=command-line %} +```bash +$ scala +Welcome to Scala {{site.scala-3-version}} (1.8.0_322, Java OpenJDK 64-Bit Server VM). +Type in expressions for evaluation. Or try :help. + +scala> _ +``` +{% endtab %} + +{% endtabs %} + +REPL — это интерпретатор командной строки, поэтому он ждет, пока вы что-нибудь наберете. +Теперь можно вводить выражения Scala, чтобы увидеть, как они работают: + +{% tabs expression-one %} +{% tab 'Scala 2 и 3' for=expression-one %} +```` +scala> 1 + 1 +val res0: Int = 2 + +scala> 2 + 2 +val res1: Int = 4 +```` +{% endtab %} +{% endtabs %} + +Как показано в выводе, если не присваивать переменную результату выражения, +REPL автоматически создает для вас переменные с именами `res0`, `res1` и т.д. +Эти имена переменных можно использовать в последующих выражениях: + +{% tabs expression-two %} +{% tab 'Scala 2 и 3' for=expression-two %} +```` +scala> val x = res0 * 10 +val x: Int = 20 +```` +{% endtab %} +{% endtabs %} + +Обратите внимание, что в REPL output также показываются результаты выражений. + +В REPL можно проводить всевозможные эксперименты. +В этом примере показано, как создать, а затем вызвать метод `sum`: + +{% tabs expression-three %} +{% tab 'Scala 2 и 3' for=expression-three %} +```` +scala> def sum(a: Int, b: Int): Int = a + b +def sum(a: Int, b: Int): Int + +scala> sum(2, 2) +val res2: Int = 4 +```` +{% endtab %} +{% endtabs %} + +Также можно использовать игровую среду на основе браузера [scastie.scala-lang.org](https://scastie.scala-lang.org). + +Если вы предпочитаете писать код в текстовом редакторе, а не в консоли, то можно использовать [worksheet]. + +[worksheet]: {% link _overviews/scala3-book/tools-worksheets.md %} diff --git a/_ru/scala3/book/taste-summary.md b/_ru/scala3/book/taste-summary.md new file mode 100644 index 0000000000..f2ca4e86da --- /dev/null +++ b/_ru/scala3/book/taste-summary.md @@ -0,0 +1,35 @@ +--- +layout: multipage-overview +title: Обзор +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлен краткий обзор предыдущих разделов 'Taste of Scala'. +language: ru +num: 16 +previous-page: taste-toplevel-definitions +next-page: first-look-at-types +--- + + +В предыдущих разделах вы видели: + +- Как использовать Scala REPL +- Как создавать переменные с помощью `val` и `var` +- Некоторые распространенные типы данных +- Структуры управления +- Как моделировать реальный мир, используя стили ООП и ФП +- Как создавать и использовать методы +- Как использовать лямбды (анонимные функции) и функции высшего порядка +- Как использовать объекты для нескольких целей +- Введение в [контекстную абстракцию][contextual] + +Мы также упоминали, что если вы предпочитаете использовать игровую среду на основе браузера вместо Scala REPL, +вы также можете использовать [Scastie](https://scastie.scala-lang.org/). + +Scala включает в себя еще больше возможностей, которые не рассматриваются в этом кратком обзоре. +Дополнительную информацию см. в оставшейся части этой книги и [в справочной документации][reference]. + +[reference]: {{ site.scala3ref }}/overview.html +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} diff --git a/_ru/scala3/book/taste-toplevel-definitions.md b/_ru/scala3/book/taste-toplevel-definitions.md new file mode 100644 index 0000000000..3d15f774a8 --- /dev/null +++ b/_ru/scala3/book/taste-toplevel-definitions.md @@ -0,0 +1,79 @@ +--- +layout: multipage-overview +title: Верхнеуровневые определения +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлено введение в определения верхнего уровня в Scala 3. +language: ru +num: 15 +previous-page: taste-contextual-abstractions +next-page: taste-summary +--- + + +В Scala 3 все виды определений могут быть записаны на “верхнем уровне” ваших файлов с исходным кодом. +Например, вы можете создать файл с именем _MyCoolApp.scala_ и поместить в него следующее содержимое: + +{% tabs toplevel_1 %} +{% tab 'Только в Scala 3' for=toplevel_1 %} +```scala +import scala.collection.mutable.ArrayBuffer + +enum Topping: + case Cheese, Pepperoni, Mushrooms + +import Topping.* +class Pizza: + val toppings = ArrayBuffer[Topping]() + +val p = Pizza() + +extension (s: String) + def capitalizeAllWords = s.split(" ").map(_.capitalize).mkString(" ") + +val hwUpper = "hello, world".capitalizeAllWords + +type Money = BigDecimal + +// по желанию здесь можно указать ещё больше определений ... + +@main def myApp = + p.toppings += Cheese + println("show me the code".capitalizeAllWords) +``` +{% endtab %} +{% endtabs %} + +Как показано, нет необходимости помещать эти определения внутрь конструкции `package`, `class` или иной конструкции. + +## Заменяет объекты пакета + +Если вы знакомы со Scala 2, этот подход заменяет _объекты пакета_ (_package objects_). +Но, будучи намного проще в использовании, они работают одинаково: +когда вы помещаете определение в пакет с именем `foo`, +вы можете получить доступ к этому определению во всех других пакетах в `foo`, например, в пакете `foo.bar`, +как в этом примере: + +{% tabs toplevel_2 %} +{% tab 'Только в Scala 3' for=toplevel_2 %} +```scala +package foo { + def double(i: Int) = i * 2 +} + +package foo { + package bar { + @main def fooBarMain = + println(s"${double(1)}") // это работает + } +} +``` +{% endtab %} +{% endtabs %} + +Фигурные скобки используются в этом примере, чтобы подчеркнуть вложенность пакета. + +Преимуществом такого подхода является то, что можно размещать определения в пакете с именем `com.acme.myapp`, +а затем можно ссылаться на эти определения в `com.acme.myapp.model`, `com.acme.myapp.controller` и т.д. diff --git a/_ru/scala3/book/taste-vars-data-types.md b/_ru/scala3/book/taste-vars-data-types.md new file mode 100644 index 0000000000..7409db07b4 --- /dev/null +++ b/_ru/scala3/book/taste-vars-data-types.md @@ -0,0 +1,276 @@ +--- +layout: multipage-overview +title: Переменные и типы данных +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе демонстрируются переменные val и var, а также некоторые распространенные типы данных Scala. +language: ru +num: 7 +previous-page: taste-repl +next-page: taste-control-structures +--- + + +В этом разделе представлен обзор переменных и типов данных Scala. + +## Два вида переменных + +Когда вы создаете новую переменную в Scala, то объявляете, является ли переменная неизменяемой или изменяемой: + + + + + + + + + + + + + + + + + + +
            Тип переменнойОписание
            valСоздает неизменяемую переменную — как final в Java. Вы всегда должны создавать переменную с val, если нет причины, по которой вам нужна изменяемая переменная.
            varСоздает изменяемую переменную и должна использоваться только в том случае, если содержимое переменной будет меняться с течением времени.
            + +Эти примеры показывают, как создавать `val` и `var` переменные: + +{% tabs var-express-1 %} +{% tab 'Scala 2 и 3' %} + +```scala +// неизменяемая +val a = 0 + +// изменяемая +var b = 1 +``` +{% endtab %} +{% endtabs %} + +В программе `val` переназначить нельзя. +Появится ошибка компилятора, если попытаться её изменить: + +{% tabs var-express-2 %} +{% tab 'Scala 2 и 3' %} + +```scala +val msg = "Hello, world" +msg = "Aloha" // ошибка "reassignment to val"; этот код не скомпилируется +``` +{% endtab %} +{% endtabs %} + +И наоборот, `var` можно переназначить: + +{% tabs var-express-3 %} +{% tab 'Scala 2 и 3' %} + +```scala +var msg = "Hello, world" +msg = "Aloha" // этот код скомпилируется, потому что var может быть переназначена +``` +{% endtab %} +{% endtabs %} + +## Объявление типов переменных + +Когда вы создаете переменную, то можете явно объявить ее тип или позволить компилятору его вывести: + +{% tabs var-express-4 %} +{% tab 'Scala 2 и 3' %} + +```scala +val x: Int = 1 // явно +val x = 1 // неявно; компилятор выводит тип +``` +{% endtab %} +{% endtabs %} + +Вторая форма известна как _вывод типа_, и это отличный способ сделать кратким код такого типа. +Компилятор Scala обычно может определить тип данных за вас, как показано в выводе этих примеров REPL: + +{% tabs var-express-5 %} +{% tab 'Scala 2 и 3' %} + +```scala +scala> val x = 1 +val x: Int = 1 + +scala> val s = "a string" +val s: String = a string + +scala> val nums = List(1, 2, 3) +val nums: List[Int] = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +Вы всегда можете явно объявить тип переменной, если хотите, +но в простых присваиваниях, подобных нижеследующим, в этом нет необходимости: + +{% tabs var-express-6 %} +{% tab 'Scala 2 и 3' %} + +```scala +val x: Int = 1 +val s: String = "a string" +val p: Person = Person("Richard") +``` +{% endtab %} +{% endtabs %} + +Обратите внимание, что при таком подходе код кажется более многословным, чем необходимо. + +## Встроенные типы данных + +Scala поставляется со стандартными числовыми типами данных, которые вы ожидаете, +и все они являются полноценными экземплярами классов. +В Scala все является объектом. + +Эти примеры показывают, как объявлять переменные числовых типов: + +{% tabs var-express-7 %} +{% tab 'Scala 2 и 3' %} + +```scala +val b: Byte = 1 +val i: Int = 1 +val l: Long = 1 +val s: Short = 1 +val d: Double = 2.0 +val f: Float = 3.0 +``` +{% endtab %} +{% endtabs %} + +Поскольку `Int` и `Double` являются числовыми типами по умолчанию, то обычно они создаются без явного объявления типа: + +{% tabs var-express-8 %} +{% tab 'Scala 2 и 3' %} + +```scala +val i = 123 // по умолчанию Int +val j = 1.0 // по умолчанию Double +``` +{% endtab %} +{% endtabs %} + +В своем коде вы также можете добавлять символы `L`, `D` и `F` (и их эквиваленты в нижнем регистре) к числам, +чтобы указать, что они являются `Long`, `Double` или `Float` значениями: + +{% tabs var-express-9 %} +{% tab 'Scala 2 и 3' %} + +```scala +val x = 1_000L // val x: Long = 1000 +val y = 2.2D // val y: Double = 2.2 +val z = 3.3F // val z: Float = 3.3 +``` +{% endtab %} +{% endtabs %} + +Когда вам нужны действительно большие числа, используйте типы `BigInt` и `BigDecimal`: + +{% tabs var-express-10 %} +{% tab 'Scala 2 и 3' %} + +```scala +var a = BigInt(1_234_567_890_987_654_321L) +var b = BigDecimal(123_456.789) +``` +{% endtab %} +{% endtabs %} + +Где `Double` и `Float` - это приблизительные десятичные числа, а `BigDecimal` используется для точной арифметики. + +В Scala также есть типы данных `String` и `Char`: + +{% tabs var-express-11 %} +{% tab 'Scala 2 и 3' %} + +```scala +val name = "Bill" // String +val c = 'a' // Char +``` +{% endtab %} +{% endtabs %} + +### Строки + +Строки Scala похожи на строки Java, но у них есть две замечательные дополнительные функции: + +- Они поддерживают интерполяцию строк +- Легко создавать многострочные строки + +#### Строковая интерполяция + +Интерполяция строк обеспечивает очень удобный способ использования переменных внутри строк. +Например, учитывая эти три переменные: + +{% tabs var-express-12 %} +{% tab 'Scala 2 и 3' %} + +```scala +val firstName = "John" +val mi = 'C' +val lastName = "Doe" +``` +{% endtab %} +{% endtabs %} + +Вы можете объединить эти переменные в строку следующим образом: + +{% tabs var-express-13 %} +{% tab 'Scala 2 и 3' %} + +```scala +println(s"Name: $firstName $mi $lastName") // "Name: John C Doe" +``` +{% endtab %} +{% endtabs %} + +Просто поставьте перед строкой букву `s`, а затем поставьте символ `$` перед именами переменных внутри строки. + +Чтобы вставить произвольные выражения в строку, заключите их в фигурные скобки: + +{% tabs var-express-14 %} +{% tab 'Scala 2 и 3' %} + +``` scala +println(s"2 + 2 = ${2 + 2}") // prints "2 + 2 = 4" + +val x = -1 +println(s"x.abs = ${x.abs}") // prints "x.abs = 1" +``` +{% endtab %} +{% endtabs %} + +Символ `s`, помещенный перед строкой, является лишь одним из возможных интерполяторов. +Если использовать `f` вместо `s`, можно использовать синтаксис форматирования в стиле `printf` в строке. +Кроме того, интерполятор строк - это всего лишь специальный метод, и его можно определить самостоятельно. +Например, некоторые библиотеки баз данных определяют очень мощный интерполятор `sql`. + +#### Многострочные строки + +Многострочные строки создаются путем включения строки в три двойные кавычки: + +{% tabs var-express-15 %} +{% tab 'Scala 2 и 3' %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` +{% endtab %} +{% endtabs %} + +> Дополнительные сведения о строковых интерполяторах и многострочных строках см. в главе [“Первое знакомство с типами”][first-look]. + +[first-look]: {% link _overviews/scala3-book/first-look-at-types.md %} diff --git a/_ru/scala3/book/tools-sbt.md b/_ru/scala3/book/tools-sbt.md new file mode 100644 index 0000000000..2dcb91b7de --- /dev/null +++ b/_ru/scala3/book/tools-sbt.md @@ -0,0 +1,488 @@ +--- +layout: multipage-overview +title: Сборка и тестирование проектов Scala с помощью Sbt +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе рассматриваются широко используемый инструмент сборки sbt и библиотека тестирования ScalaTest. +language: ru +num: 70 +previous-page: scala-tools +next-page: tools-worksheets +--- + +В этом разделе будут показаны два инструмента, которые обычно используются в проектах Scala: + +- инструмент сборки [sbt](https://www.scala-sbt.org) +- [ScalaTest](https://www.scalatest.org) - среда тестирования исходного кода + +Начнем с использования sbt для создания Scala-проектов, а затем рассмотрим, как использовать sbt и ScalaTest вместе для тестирования. + +> Если вы хотите узнать об инструментах, которые помогут вам перенести код Scala 2 на Scala 3, +> ознакомьтесь с нашим [Руководством по миграции на Scala 3](/scala3/guides/migration/compatibility-intro.html). + +## Создание проектов Scala с помощью sbt + +Можно использовать несколько различных инструментов для создания проектов Scala, включая Ant, Maven, Gradle, Mill и другие. +Но инструмент под названием _sbt_ был первым инструментом сборки, специально созданным для Scala. + +> Чтобы установить sbt, см. [страницу загрузки](https://www.scala-sbt.org/download.html) или нашу страницу ["Начало работы"][getting_started]. + +### Создание проекта "Hello, world" + +Вы можете создать sbt проект "Hello, world" всего за несколько шагов. +Сначала создайте каталог для работы и перейдите в него: + +```bash +$ mkdir hello +$ cd hello +``` + +В каталоге `hello` создайте подкаталог `project`: + +```bash +$ mkdir project +``` + +Создайте файл с именем _build.properties_ в каталоге `project` со следующим содержимым: + +```text +sbt.version=1.10.11 +``` + +Затем создайте файл с именем _build.sbt_ в корневом каталоге проекта, содержащий следующую строку: + +```scala +scalaVersion := "{{ site.scala-3-version }}" +``` + +Теперь создайте файл с именем _Hello.scala_ (первая часть имени не имеет значения) со следующей строкой: + +```scala +@main def helloWorld = println("Hello, world") +``` + +Это все, что нужно сделать. + +Должна получиться следующая структура проекта: + +```bash +$ tree +. +├── build.sbt +├── Hello.scala +└── project + └── build.properties +``` + +Теперь запустите проект с помощью команды `sbt`: + +```bash +$ sbt run +``` + +Вы должны увидеть вывод, который выглядит следующим образом, включая `"Hello, world"` из программы: + +```bash +$ sbt run +[info] welcome to sbt 1.6.1 (AdoptOpenJDK Java 11.x) +[info] loading project definition from project ... +[info] loading settings for project from build.sbt ... +[info] compiling 1 Scala source to target/scala-3.0.0/classes ... +[info] running helloWorld +Hello, world +[success] Total time: 2 s +``` + +Программа запуска — средство командной строки `sbt` - загружает версию sbt, установленную в файле _project/build.properties_, +которая загружает версию компилятора Scala, установленную в файле _build.sbt_, +компилирует код в файле _Hello.scala_ и запускает результирующий байт-код. + +Если посмотреть на корневой каталог, то можно увидеть, что появилась папка с именем _target_. +Это рабочие каталоги, которые использует sbt. + +Создание и запуск небольшого проекта Scala с помощью sbt занимает всего несколько простых шагов. + +### Использование sbt в более крупных проектах + +Для небольшого проекта это все, что требует sbt для запуска. +Для более крупных проектов с большим количеством файлов исходного кода, зависимостей или плагинов, +потребуется создать организованную структуру каталогов. +Остальная часть этого раздела демонстрирует структуру, которую использует sbt. + +### Структура каталогов sbt + +Как и Maven, sbt использует стандартную структуру каталогов проекта. +Преимуществом стандартизации является то, что, как только структура станет привычной, +станет легко работать с другими проектами Scala/sbt. + +Первое, что нужно знать - это то, что под корневым каталогом проекта sbt ожидает структуру каталогов, +которая выглядит следующим образом: + +```text +. +├── build.sbt +├── project/ +│ └── build.properties +├── src/ +│ ├── main/ +│ │ ├── java/ +│ │ ├── resources/ +│ │ └── scala/ +│ └── test/ +│ ├── java/ +│ ├── resources/ +│ └── scala/ +└── target/ +``` + +Также в корневой каталог можно добавить каталог _lib_, +если необходимо в свой проект добавить внешние зависимости — файлы JAR. + +Если достаточно создать проект, который имеет только файлы исходного кода Scala и тесты, +но не будет использовать Java файлы и не нуждается в каких-либо "ресурсах" (встроенные изображения, файлы конфигурации и т.д.), +то в каталоге _src_ можно оставить только: + +```text +. +└── src/ + ├── main/ + │ └── scala/ + └── test/ + └── scala/ +``` + +### "Hello, world" со структурой каталогов sbt + +Создать такую структуру каталогов просто. +Существуют инструменты, которые сделают это за вас, но если вы используете систему Unix/Linux, +можно использовать следующие команды для создания структуры каталогов проекта sbt: + +```bash +$ mkdir HelloWorld +$ cd HelloWorld +$ mkdir -p src/{main,test}/scala +$ mkdir project target +``` + +После запуска этих команд, по запросу `find .` вы должны увидеть такой результат: + +```bash +$ find . +. +./project +./src +./src/main +./src/main/scala +./src/test +./src/test/scala +./target +``` + +Если вы это видите, отлично, вы готовы для следующего шага. + +> Существуют и другие способы создания файлов и каталогов для проекта sbt. +> Один из способов - использовать команду sbt new, которая [задокументирована на scala-sbt.org](https://www.scala-sbt.org/1.x/docs/Hello.html). +> Этот подход здесь не показан, поскольку некоторые из создаваемых им файлов более сложны, чем необходимо для такого введения. + +### Создание первого файла build.sbt + +На данный момент нужны еще две вещи для запуска проекта "Hello, world": + +- файл _build.sbt_ +- файл _Hello.scala_ + +Для такого небольшого проекта файлу _build.sbt_ нужна только запись `scalaVersion`, но мы добавим три строки: + +```scala +name := "HelloWorld" +version := "0.1" +scalaVersion := "{{ site.scala-3-version }}" +``` + +Поскольку проекты sbt используют стандартную структуру каталогов, sbt может найти все, что ему нужно. + +Теперь осталось просто добавить небольшую программу "Hello, world". + +### Программа "Hello, world" + +В больших проектах все файлы исходного кода будут находиться в каталогах _src/main/scala_ и _src/test/scala_, +но для небольшого примера, подобного этому, можно поместить файл исходного кода в корневой каталог. +Поэтому создайте файл с именем _HelloWorld.scala_ в корневом каталоге со следующим содержимым: + +```scala +@main def helloWorld = println("Hello, world") +``` + +Этот код определяет "main" метод, который печатает `"Hello, world"` при запуске. + +Теперь используйте команду `sbt run` для компиляции и запуска проекта: + +```bash +$ sbt run + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition +[info] loading settings for project root from build.sbt ... +[info] Compiling 1 Scala source ... +[info] running helloWorld +Hello, world +[success] Total time: 4 s +``` + +При первом запуске `sbt` загружает все, что ему нужно (это может занять несколько секунд), +но после первого раза запуск становится намного быстрее. + +Кроме того, после выполнения первого шага можно обнаружить, что гораздо быстрее запускать sbt в интерактивном режиме. +Для этого вначале отдельно запустите команду `sbt`: + +```bash +$ sbt + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition ... +[info] loading settings for project root from build.sbt ... +[info] sbt server started at + local:///${HOME}/.sbt/1.0/server/7d26bae822c36a31071c/sock +sbt:hello-world> _ +``` + +Затем внутри этой оболочки выполните команду `run`: + +``` +sbt:hello-world> run + +[info] running helloWorld +Hello, world +[success] Total time: 0 s +``` + +Так намного быстрее. + +Если вы наберете `help` в командной строке sbt, то увидите список других команд, доступных для запуска. +Введите `exit` (или нажмите `CTRL-D`), чтобы выйти из оболочки sbt. + +### Использование шаблонов проектов + +Ручное создание структуры проекта может быть утомительным. К счастью, sbt может создать структуру на основе шаблона. + +Чтобы создать проект Scala 3 из шаблона, выполните следующую команду в оболочке: + +``` +$ sbt new scala/scala3.g8 +``` + +Sbt загрузит шаблон, задаст несколько вопросов и создаст файлы проекта в подкаталоге: + +``` +$ tree scala-3-project-template +scala-3-project-template +├── build.sbt +├── project +│ └── build.properties +├── README.md +└── src + ├── main + │ └── scala + │ └── Main.scala + └── test + └── scala + └── Test1.scala +``` + +> Если вы хотите создать проект Scala 3, который кросс-компилируется со Scala 2, используйте шаблон `scala/scala3-cross.g8`: +> +> ``` +> $ sbt new scala/scala3-cross.g8 +> ``` + +Узнайте больше о `sbt new` и шаблонах проектов в [документации sbt](https://www.scala-sbt.org/1.x/docs/sbt-new-and-Templates.html#sbt+new+and+Templates). + +### Другие инструменты сборки для Scala + +Хотя sbt широко используется, есть и другие инструменты, которые можно использовать для создания проектов Scala: + +- [Ant](https://ant.apache.org/) +- [Gradle](https://gradle.org/) +- [Maven](https://maven.apache.org/) +- [Mill](https://com-lihaoyi.github.io/mill/) + +#### Coursier + +[Coursier](https://get-coursier.io/docs/overview) - это "преобразователь зависимостей", похожий по функциям на Maven и Ivy. +Он написан на Scala с нуля, "охватывает принципы функционального программирования" +и для быстроты параллельно загружает артефакты. +sbt использует Coursier для обработки большинства разрешений зависимостей, +а в качестве инструмента командной строки его можно использовать для простой установки таких инструментов, +как sbt, Java и Scala, как показано на странице ["С чего начать?"][getting_started]. + +Этот пример со страницы `launch` показывает, что команда `cs launch` может использоваться для запуска приложений из зависимостей: + +```scala +$ cs launch org.scalameta::scalafmt-cli:2.4.2 -- --help +scalafmt 2.4.2 +Usage: scalafmt [options] [...] + + -h, --help prints this usage text + -v, --version print version + more ... +``` + +Подробнее см. на странице [запуска Coursier](https://get-coursier.io/docs/cli-launch). + +## Использование sbt со ScalaTest + +[ScalaTest](https://www.scalatest.org) — одна из основных библиотек тестирования для проектов Scala. +В этом разделе рассмотрим шаги, необходимые для создания проекта Scala/sbt, использующего ScalaTest. + +### 1) Создание структуры каталогов проекта + +Как и в предыдущем уроке, создаем структуру каталогов sbt для проекта с именем _HelloScalaTest_ с помощью следующих команд: + +```bash +$ mkdir HelloScalaTest +$ cd HelloScalaTest +$ mkdir -p src/{main,test}/scala +$ mkdir project +``` + +### 2) Создание файлов build.properties и build.sbt + +Затем создаем файл _build.properties_ в подкаталоге _project/_ проекта с такой строкой: + +```text +sbt.version=1.10.11 +``` + +Создаем файл _build.sbt_ в корневом каталоге проекта со следующим содержимым: + +```scala +name := "HelloScalaTest" +version := "0.1" +scalaVersion := "{{site.scala-3-version}}" + +libraryDependencies ++= Seq( + "org.scalatest" %% "scalatest" % "3.2.19" % Test +) +``` + +Первые три строки этого файла практически такие же, как и в первом примере. +Строки `libraryDependencies` сообщают sbt о включении зависимостей (файлов JAR), которые необходимы для добавления ScalaTest. + +> Документация по ScalaTest всегда была хорошей, и вы всегда можете найти актуальную информацию о том, +> как должны выглядеть эти строки, на странице ["Установка ScalaTest"](https://www.scalatest.org/install). + +### 3) Создание файла исходного кода Scala + +Затем создаем программу Scala, которую можно использовать для демонстрации ScalaTest. +Сначала создайте каталог в _src/main/scala_ с именем _math_: + +```bash +$ mkdir src/main/scala/math + ---- +``` + +Внутри этого каталога создайте файл _MathUtils.scala_ со следующим содержимым: + +```scala +package math + +object MathUtils: + def double(i: Int) = i * 2 +``` + +Этот метод обеспечивает простой способ демонстрации ScalaTest. + +### 4) Создание первых тестов ScalaTest + +ScalaTest очень гибок и предлагает несколько различных способов написания тестов. +Простой способ начать работу — написать тесты с помощью `AnyFunSuite`. +Для начала создайте каталог с именем _math_ в каталоге _src/test/scala_: + +```bash +$ mkdir src/test/scala/math + ---- +``` + +Затем создайте в этом каталоге файл с именем _MathUtilsTests.scala_ со следующим содержимым: + +```scala +package math + +import org.scalatest.funsuite.AnyFunSuite + +class MathUtilsTests extends AnyFunSuite: + + // test 1 + test("'double' should handle 0") { + val result = MathUtils.double(0) + assert(result == 0) + } + + // test 2 + test("'double' should handle 1") { + val result = MathUtils.double(1) + assert(result == 2) + } + + test("test with Int.MaxValue") (pending) + +end MathUtilsTests +``` + +Этот код демонстрирует `AnyFunSuite` подход. +Несколько важных моментов: + +- тестовый класс должен расширять `AnyFunSuite` +- тесты создаются, задавая каждому `test` уникальное имя +- в конце каждого теста необходимо вызвать `assert`, чтобы проверить, выполнено ли условие +- когда вы знаете, что хотите написать тест, но не хотите писать его прямо сейчас, + создайте тест как "pending" (ожидающий) с показанным синтаксисом + +Подобное использование ScalaTest напоминает JUnit, так что если вы переходите с Java на Scala, это должно показаться знакомым. + +Теперь можно запустить эти тесты с помощью команды `sbt test`. +Пропуская первые несколько строк вывода, результат выглядит следующим образом: + +``` +sbt:HelloScalaTest> test + +[info] Compiling 1 Scala source ... +[info] MathUtilsTests: +[info] - 'double' should handle 0 +[info] - 'double' should handle 1 +[info] - test with Int.MaxValue (pending) +[info] Total number of tests run: 2 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 1 +[info] All tests passed. +[success] Total time: 1 s +``` + +Если все работает хорошо, вы увидите примерно такой результат. +Добро пожаловать в мир тестирования приложений Scala с помощью sbt и ScalaTest. + +### Поддержка различных видов тестов + +В этом примере демонстрируется стиль тестирования, аналогичный стилю xUnit _Test-Driven Development_ (TDD), +с некоторыми преимуществами _Behavior-Driven Development_ (BDD). + +Как уже упоминалось, ScalaTest является гибким, и вы также можете писать тесты, используя другие стили, +такие как стиль, похожий на RSpec Ruby. +Вы также можете использовать моканные объекты, тестирование на основе свойств +и использовать ScalaTest для тестирования кода Scala.js. + +Дополнительные сведения о различных доступных стилях тестирования +см. в Руководстве пользователя на [веб-сайте ScalaTest](https://www.scalatest.org). + +## Что дальше? + +Дополнительные сведения о sbt и ScalaTest см. в следующих ресурсах: + +- [The sbt documentation](https://www.scala-sbt.org/1.x/docs/) +- [The ScalaTest website](https://www.scalatest.org/) + +[getting_started]: {{ site.baseurl }}/ru/getting-started/install-scala.html diff --git a/_ru/scala3/book/tools-worksheets.md b/_ru/scala3/book/tools-worksheets.md new file mode 100644 index 0000000000..5409c5ad40 --- /dev/null +++ b/_ru/scala3/book/tools-worksheets.md @@ -0,0 +1,63 @@ +--- +layout: multipage-overview +title: Рабочие листы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе рассматриваются рабочие листы — альтернатива проектам Scala. +language: ru +num: 71 +previous-page: tools-sbt +next-page: interacting-with-java +--- + +Worksheet - это файл Scala, который вычисляется при сохранении, +и результат каждого выражения отображается в столбце справа от программы. +Рабочие листы похожи на [сеанс REPL][REPL session] на стероидах +и имеют поддержку редактора 1-го класса: завершение, гиперссылки, интерактивные ошибки при вводе и т.д. +Рабочие листы используют расширение `.worksheet.sc`. + +Далее покажем, как использовать рабочие листы в IntelliJ и в VS Code (с расширением Metals). + +1. Откройте проект Scala или создайте его: + - чтобы создать проект в IntelliJ, выберите "File" -> "New" -> "Project...", + выберите "Scala" в левой колонке и нажмите "Далее", чтобы задать название проекта и каталог. + - чтобы создать проект в VS Code, выполните команду "Metals: New Scala project", + выберите начальный `scala/scala3.g8`, задайте местоположение проекта, + откройте его в новом окне VS Code и импортируйте сборку. +1. Создайте файл с именем `hello.worksheet.sc` в каталоге `src/main/scala/`. + - в IntelliJ щелкните правой кнопкой мыши на каталоге `src/main/scala/` и выберите "New", а затем "File". + - в VS Code щелкните правой кнопкой мыши на каталоге `src/main/scala/` и выберите "New File". +1. Вставьте следующее содержимое в редактор: + + ``` + println("Hello, world!") + + val x = 1 + x + x + ``` + +1. Запустите worksheet: + + - в IntelliJ щелкните зеленую стрелку в верхней части редактора, чтобы запустить worksheet. + - в VS Code сохраните файл. + + Вы должны увидеть результат выполнения каждой строки на правой панели (IntelliJ) или в виде комментариев (VS Code). + +![]({{ site.baseurl }}/resources/images/scala3-book/intellij-worksheet.png) + +Рабочий лист, выполненный в IntelliJ. + +![]({{ site.baseurl }}/resources/images/scala3-book/metals-worksheet.png) + +Рабочий лист, выполненный в VS Code (с расширением Metals). + +Обратите внимание, что worksheet будет использовать версию Scala, +определенную проектом (обычно задается ключом `scalaVersion` в файле `build.sbt`). + +Также обратите внимание, что worksheet не имеют [точек входа в программу][program entry point]. +Вместо этого операторы и выражения верхнего уровня оцениваются сверху вниз. + +[REPL session]: {{ site.baseurl }}/ru/scala3/book/taste-repl.html +[program entry point]: {{ site.baseurl }}/ru/scala3/book/methods-main-methods.html diff --git a/_ru/scala3/book/types-adts-gadts.md b/_ru/scala3/book/types-adts-gadts.md new file mode 100644 index 0000000000..50091980e3 --- /dev/null +++ b/_ru/scala3/book/types-adts-gadts.md @@ -0,0 +1,223 @@ +--- +layout: multipage-overview +title: Алгебраические типы данных +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены и демонстрируются алгебраические типы данных (ADT) в Scala 3. +language: ru +num: 53 +previous-page: types-union +next-page: types-variance +versionSpecific: true +--- + +Только в Scala 3 + +Алгебраические типы данных (ADT) могут быть созданы с помощью конструкции `enum`, +поэтому кратко рассмотрим перечисления, прежде чем рассматривать ADT. + +## Перечисления + +_Перечисление_ используется для определения типа, состоящего из набора именованных значений: + +```scala +enum Color: + case Red, Green, Blue +``` + +который можно рассматривать как сокращение для: + +```scala +enum Color: + case Red extends Color + case Green extends Color + case Blue extends Color +``` + +#### Параметры + +Перечисления могут быть параметризованы: + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` + +Таким образом, каждый из различных вариантов содержит параметр `rgb`, +которому присваивается соответствующее значение: + +```scala +println(Color.Green.rgb) // выводит 65280 +``` + +#### Пользовательские определения + +Перечисления также могут содержать пользовательские определения: + +```scala +enum Planet(mass: Double, radius: Double): + + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity + + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Venus extends Planet(4.869e+24, 6.0518e6) + case Earth extends Planet(5.976e+24, 6.37814e6) + // остальные 5 или 6 планет ... +``` + +Подобно классам и `case` классам, вы также можете определить сопутствующий объект для перечисления: + +```scala +object Planet: + def main(args: Array[String]) = + val earthWeight = args(0).toDouble + val mass = earthWeight / Earth.surfaceGravity + for (p <- values) + println(s"Your weight on $p is ${p.surfaceWeight(mass)}") +``` + +## Алгебраические типы данных (ADTs) + +Концепция `enum` является достаточно общей, +чтобы также поддерживать _алгебраические типы данных_ (ADT) и их обобщенную версию (GADT). +Вот пример, показывающий, как тип `Option` может быть представлен в виде АТД: + +```scala +enum Option[+T]: + case Some(x: T) + case None +``` + +В этом примере создается перечисление `Option` с параметром ковариантного типа `T`, +состоящим из двух вариантов `Some` и `None`. +`Some` _параметризуется_ значением параметра `x`; +это сокращение для написания `case` класса, расширяющего `Option`. +Поскольку `None` не параметризуется, то он считается обычным enum значением. + +Предложения `extends`, которые были опущены в предыдущем примере, также могут быть указаны явно: + +```scala +enum Option[+T]: + case Some(x: T) extends Option[T] + case None extends Option[Nothing] +``` + +Как и в случае с обычным `enum` значениями, варианты enum определяются в его сопутствующем объекте, +поэтому они называются `Option.Some` и `Option.None` (если только определения не «вытягиваются» при импорте): + +```scala +scala> Option.Some("hello") +val res1: t2.Option[String] = Some(hello) + +scala> Option.None +val res2: t2.Option[Nothing] = None +``` + +Как и в других случаях использования перечисления, АТД могут определять дополнительные методы. +Например, вот снова `Option`, с методом `isDefined` и конструктором `Option(...)` в сопутствующем объекте: + +```scala +enum Option[+T]: + case Some(x: T) + case None + + def isDefined: Boolean = this match + case None => false + case Some(_) => true + +object Option: + def apply[T >: Null](x: T): Option[T] = + if (x == null) None else Some(x) +``` + +Перечисления и АТД используют одну и ту же синтаксическую конструкцию, +поэтому их можно рассматривать просто как два конца спектра, и вполне допустимо создавать гибриды. +Например, приведенный ниже код реализует `Color` либо с тремя значениями перечисления, +либо с параметризованным вариантом, принимающим значение RGB: + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) + case Mix(mix: Int) extends Color(mix) +``` + +#### Рекурсивные перечисления + +До сих пор все перечисления, которые мы определяли, состояли из различных вариантов значений или case классов. +Перечисления также могут быть рекурсивными, как показано в приведенном ниже примере кодирования натуральных чисел: + +```scala +enum Nat: + case Zero + case Succ(n: Nat) +``` + +Например, значение `Succ(Succ(Zero))` представляет число `2` в унарной кодировке. +Списки могут быть определены похожим образом: + +```scala +enum List[+A]: + case Nil + case Cons(head: A, tail: List[A]) +``` + +## Обобщенные алгебраические типы данных (GADT) + +Приведенная выше нотация для перечислений очень краткая +и служит идеальной отправной точкой для моделирования ваших типов данных. +Поскольку мы всегда можем быть более подробными, то можем выразить гораздо более мощные типы: +обобщенные алгебраические типы данных (GADT). + +Вот пример GADT, в котором параметр типа (`T`) указывает на тип содержимого, хранящегося в `Box`: + +```scala +enum Box[T](contents: T): + case IntBox(n: Int) extends Box[Int](n) + case BoolBox(b: Boolean) extends Box[Boolean](b) +``` + +Сопоставление с образцом с конкретным конструктором (`IntBox` или `BoolBox`) восстанавливает информацию о типе: + +```scala +def extract[T](b: Box[T]): T = b match + case IntBox(n) => n + 1 + case BoolBox(b) => !b +``` + +Безопасно возвращать `Int` в первом случае, так как мы знаем из сопоставления с образцом, что ввод был `IntBox`. + +## Дешугаризация перечислений + +_Концептуально_ перечисления можно рассматривать как определение запечатанного класса вместе с сопутствующим ему объектом. +Давайте посмотрим на дешугаризацию нашего перечисления `Color`: + +```scala +sealed abstract class Color(val rgb: Int) extends scala.reflect.Enum +object Color: + case object Red extends Color(0xFF0000) { def ordinal = 0 } + case object Green extends Color(0x00FF00) { def ordinal = 1 } + case object Blue extends Color(0x0000FF) { def ordinal = 2 } + case class Mix(mix: Int) extends Color(mix) { def ordinal = 3 } + + def fromOrdinal(ordinal: Int): Color = ordinal match + case 0 => Red + case 1 => Green + case 2 => Blue + case _ => throw new NoSuchElementException(ordinal.toString) +``` + +Заметьте, что вышеописанная дешугаризация упрощена, и мы намеренно опускаем [некоторые детали][desugar-enums]. + +В то время как перечисления можно кодировать вручную с помощью других конструкций, +использование перечислений является более кратким, +а также включает несколько дополнительных утилит (таких, как метод `fromOrdinal`). + +[desugar-enums]: {{ site.scala3ref }}/enums/desugarEnums.html diff --git a/_ru/scala3/book/types-dependent-function.md b/_ru/scala3/book/types-dependent-function.md new file mode 100644 index 0000000000..88750e2ec5 --- /dev/null +++ b/_ru/scala3/book/types-dependent-function.md @@ -0,0 +1,179 @@ +--- +layout: multipage-overview +title: Зависимые типы функций +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены и демонстрируются зависимые типы функций в Scala 3. +language: ru +num: 57 +previous-page: types-structural +next-page: types-others +versionSpecific: true +--- + +_Зависимый тип функции_ (_dependent function type_) описывает типы функций, +где тип результата может зависеть от значений параметров функции. +Концепция зависимых типов и типов зависимых функций является более продвинутой, +и обычно с ней сталкиваются только при разработке собственных библиотек или использовании расширенных библиотек. + +## Зависимые типы методов + +Рассмотрим следующий пример гетерогенной базы данных, в которой могут храниться значения разных типов. +Ключ содержит информацию о типе соответствующего значения: + +```scala +trait Key { type Value } + +trait DB { + def get(k: Key): Option[k.Value] // зависимый метод +} +``` + +Получив ключ, метод `get` предоставляет доступ к карте и потенциально возвращает сохраненное значение типа `k.Value`. +Мы можем прочитать этот _path-dependent type_ как: +"в зависимости от конкретного типа аргумента `k` возвращается соответствующее значение". + +Например, у нас могут быть следующие ключи: + +```scala +object Name extends Key { type Value = String } +object Age extends Key { type Value = Int } +``` + +Вызовы метода `get` теперь будут возвращать такие типы: + +```scala +val db: DB = ... +val res1: Option[String] = db.get(Name) +val res2: Option[Int] = db.get(Age) +``` + +Вызов метода `db.get(Name)` возвращает значение типа `Option[String]`, +а вызов `db.get(Age)` возвращает значение типа `Option[Int]`. +Тип возвращаемого значения _зависит_ от конкретного типа аргумента, переданного для `get` — отсюда и название _dependent type_. + +## Зависимые типы функций + +Как видно выше, в Scala 2 уже была поддержка зависимых типов методов. +Однако создание значений типа `DB` довольно громоздко: + +```scala +// создание пользователя DB +def user(db: DB): Unit = + db.get(Name) ... db.get(Age) + +// создание экземпляра DB и передача его `user` +user(new DB { + def get(k: Key): Option[k.Value] = ... // реализация DB +}) +``` + +Необходимо вручную создать анонимный внутренний класс `DB`, реализующий метод `get`. +Для кода, основанного на создании множества различных экземпляров `DB`, это очень утомительно. + +Трейт `DB` имеет только один абстрактный метод `get`. +Было бы неплохо использовать в этом месте лямбда-синтаксис? + +```scala +user { k => + ... // реализация DB +} +``` + +На самом деле, в Scala 3 теперь это возможно! Можно определить `DB` как _зависимый тип функции_: + +```scala +type DB = (k: Key) => Option[k.Value] +// ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +// зависимый тип функции +``` + +Учитывая это определение `DB`, можно использовать приведенный выше вызов `user`. + +Подробнее о внутреннем устройстве зависимых типов функций можно прочитать в [справочной документации][ref]. + +## Практический пример: числовые выражения + +Предположим, что необходимо определить модуль, который абстрагируется от внутреннего представления чисел. +Это может быть полезно, например, для реализации библиотек для автоматического дифференцирования. + +Начнем с определения модуля для чисел: + +```scala +trait Nums: + // тип Num оставлен абстрактным + type Num + + // некоторые операции над числами + def lit(d: Double): Num + def add(l: Num, r: Num): Num + def mul(l: Num, r: Num): Num +``` + +> Здесь опускается конкретная реализация `Nums`, но в качестве упражнения можно реализовать `Nums`, +> назначив тип `Num = Double` и реализуя соответствующие методы. + +Программа, использующая числовую абстракцию, теперь имеет следующий тип: + +```scala +type Prog = (n: Nums) => n.Num => n.Num + +val ex: Prog = nums => x => nums.add(nums.lit(0.8), x) +``` + +Тип функции, которая вычисляет производную, наподобие `ex`: + +```scala +def derivative(input: Prog): Double +``` + +Учитывая удобство зависимых типов функций, вызов этой функции в разных программах прост: + +```scala +derivative { nums => x => x } +derivative { nums => x => nums.add(nums.lit(0.8), x) } +// ... +``` + +Напомним, что та же программа в приведенной выше кодировке будет выглядеть так: + +```scala +derivative(new Prog { + def apply(nums: Nums)(x: nums.Num): nums.Num = x +}) +derivative(new Prog { + def apply(nums: Nums)(x: nums.Num): nums.Num = nums.add(nums.lit(0.8), x) +}) +// ... +``` + +#### Комбинация с контекстными функциями + +Комбинация методов расширения, [контекстных функций][ctx-fun] и зависимых функций обеспечивает мощный инструмент для разработчиков библиотек. +Например, мы можем уточнить нашу библиотеку, как указано выше, следующим образом: + +```scala +trait NumsDSL extends Nums: + extension (x: Num) + def +(y: Num) = add(x, y) + def *(y: Num) = mul(x, y) + +def const(d: Double)(using n: Nums): n.Num = n.lit(d) + +type Prog = (n: NumsDSL) ?=> n.Num => n.Num +// ^^^ +// prog теперь - контекстная функция, +// которая неявно предполагает NumsDSL в контексте вызова + +def derivative(input: Prog): Double = ... + +// теперь нам не нужно упоминать Nums в приведенных ниже примерах +derivative { x => const(1.0) + x } +derivative { x => x * x + const(2.0) } +// ... +``` + +[ref]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[ctx-fun]: {{ site.scala3ref }}/contextual/context-functions.html diff --git a/_ru/scala3/book/types-generics.md b/_ru/scala3/book/types-generics.md new file mode 100644 index 0000000000..5ece10b356 --- /dev/null +++ b/_ru/scala3/book/types-generics.md @@ -0,0 +1,103 @@ +--- +layout: multipage-overview +title: Параметризованные типы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены параметризованные типы в Scala 3. +language: ru +num: 50 +previous-page: types-inferred +next-page: types-intersection +--- + +Универсальные (_generic_) классы (или trait-ы) принимают тип в качестве _параметра_ в квадратных скобках `[...]`. +Для обозначения параметров типа согласно конвенции Scala используется одна заглавная буква (например, `A`). +Затем этот тип можно использовать внутри класса по мере необходимости +для параметров экземпляра метода или для возвращаемых типов: + +{% tabs stack class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +```scala +// здесь мы объявляем параметр типа A +// v +class Stack[A] { + private var elements: List[A] = Nil + // ^ + // здесь мы ссылаемся на этот тип + // v + def push(x: A): Unit = + elements = elements.prepended(x) + def peek: A = elements.head + def pop(): A = { + val currentTop = peek + elements = elements.tail + currentTop + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +// здесь мы объявляем параметр типа A +// v +class Stack[A]: + private var elements: List[A] = Nil + // ^ + // здесь мы ссылаемся на этот тип + // v + def push(x: A): Unit = + elements = elements.prepended(x) + def peek: A = elements.head + def pop(): A = + val currentTop = peek + elements = elements.tail + currentTop +``` + +{% endtab %} +{% endtabs %} + +Эта реализация класса `Stack` принимает любой тип в качестве параметра. +Прелесть параметризованных типов состоит в том, +что теперь можно создавать `Stack[Int]`, `Stack[String]` и т.д., +что позволяет повторно использовать реализацию `Stack` для произвольных типов элементов. + +Пример создания и использования `Stack[Int]`: + +{% tabs stack-usage class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val stack = new Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // выводит 2 +println(stack.pop()) // выводит 1 +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +val stack = Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // выводит 2 +println(stack.pop()) // выводит 1 +``` + +{% endtab %} +{% endtabs %} + +> Подробности о том, как выразить вариантность с помощью универсальных типов, +> см. в разделе ["Вариантность"][variance]. + +[variance]: {% link _overviews/scala3-book/types-variance.md %} diff --git a/_ru/scala3/book/types-inferred.md b/_ru/scala3/book/types-inferred.md new file mode 100644 index 0000000000..cadedc1ca0 --- /dev/null +++ b/_ru/scala3/book/types-inferred.md @@ -0,0 +1,65 @@ +--- +layout: multipage-overview +title: Определение типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены и демонстрируются выводимые типы в Scala 3. +language: ru +num: 49 +previous-page: types-introduction +next-page: types-generics +--- + +Как и в других статически типизированных языках программирования, +в Scala тип можно _объявить_ при создании новой переменной: + +{% tabs xy %} +{% tab 'Scala 2 и 3' %} + +```scala +val x: Int = 1 +val y: Double = 1 +``` + +{% endtab %} +{% endtabs %} + +В этих примерах типы _явно_ объявлены как `Int` и `Double` соответственно. +Однако в Scala обычно необязательно указывать тип при объявлении переменной: + +{% tabs abm %} +{% tab 'Scala 2 и 3' %} + +```scala +val a = 1 +val b = List(1, 2, 3) +val m = Map(1 -> "one", 2 -> "two") +``` + +{% endtab %} +{% endtabs %} + +Когда вы это сделаете, Scala сама _выведет_ типы, как показано в следующей сессии REPL: + +{% tabs abm2 %} +{% tab 'Scala 2 и 3' %} + +```scala +scala> val a = 1 +val a: Int = 1 + +scala> val b = List(1, 2, 3) +val b: List[Int] = List(1, 2, 3) + +scala> val m = Map(1 -> "one", 2 -> "two") +val m: Map[Int, String] = Map(1 -> one, 2 -> two) +``` + +{% endtab %} +{% endtabs %} + +Действительно, большинство переменных определяются без указания типа, +и способность Scala автоматически определять его — это одна из особенностей, +которая делает Scala _похожим_ на язык с динамической типизацией. diff --git a/_ru/scala3/book/types-intersection.md b/_ru/scala3/book/types-intersection.md new file mode 100644 index 0000000000..759855824b --- /dev/null +++ b/_ru/scala3/book/types-intersection.md @@ -0,0 +1,76 @@ +--- +layout: multipage-overview +title: Пересечение типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены пересечение типов в Scala 3. +language: ru +num: 51 +previous-page: types-generics +next-page: types-union +--- + +Только в Scala 3 + +Используемый для типов оператор `&` создает так называемый _тип пересечения_ (_intersection type_). +Тип `A & B` представляет собой значения, которые **одновременно** относятся как к типу `A`, так и к типу `B`. +Например, в следующем примере используется тип пересечения `Resettable & Growable[String]`: + +{% tabs intersection-reset-grow %} + +{% tab 'Только в Scala 3' %} + +```scala +trait Resettable: + def reset(): Unit + +trait Growable[A]: + def add(a: A): Unit + +def f(x: Resettable & Growable[String]): Unit = + x.reset() + x.add("first") +``` + +{% endtab %} + +{% endtabs %} + +В методе `f` в этом примере параметр `x` должен быть _одновременно_ как `Resettable`, так и `Growable[String]`. + +Все _члены_ типа пересечения `A & B` являются типом `A` и типом `B`. +Следовательно, как показано, для `Resettable & Growable[String]` доступны методы `reset` и `add`. + +Пересечение типов может быть полезно для _структурного_ описания требований. +В примере выше для `f` мы прямо заявляем, что нас устраивает любое значение для `x`, +если оно является подтипом как `Resettable`, так и `Growable`. +**Нет** необходимости создавать _номинальный_ вспомогательный trait, подобный следующему: + +{% tabs normal-trait class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Both[A] extends Resettable with Growable[A] +def f(x: Both[String]): Unit +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait Both[A] extends Resettable, Growable[A] +def f(x: Both[String]): Unit +``` + +{% endtab %} +{% endtabs %} + +Существует важное различие между двумя вариантами определения `f`: +в то время как оба позволяют вызывать `f` с экземплярами `Both`, +только первый позволяет передавать экземпляры, +которые являются подтипами `Resettable` и `Growable[String]`, _но не_ `Both[String]`. + +> Обратите внимание, что `&` _коммутативно_: `A & B` имеет тот же тип, что и `B & A`. diff --git a/_ru/scala3/book/types-introduction.md b/_ru/scala3/book/types-introduction.md new file mode 100644 index 0000000000..65ecf50ebf --- /dev/null +++ b/_ru/scala3/book/types-introduction.md @@ -0,0 +1,68 @@ +--- +layout: multipage-overview +title: Типы и система типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе представлено введение в типы и систему типов Scala 3. +language: ru +num: 48 +previous-page: fp-summary +next-page: types-inferred +--- + +Scala — уникальный язык, поскольку он статически типизирован, но часто кажется гибким и динамичным. +Например, благодаря выводу типов можно писать код без явного указания типов переменных: + +{% tabs hi %} +{% tab 'Scala 2 и 3' %} + +```scala +val a = 1 +val b = 2.0 +val c = "Hi!" +``` + +{% endtab %} +{% endtabs %} + +Это делает код динамически типизированным. +А благодаря новым функциям в Scala 3, таким как [объединение типов][union-types], +также можно писать код, подобный следующему, +который кратко выражает, какие значения ожидаются в качестве аргументов и какие типы возвращаются: + +{% tabs union-example %} +{% tab 'Только в Scala 3' %} + +```scala +def isTruthy(a: Boolean | Int | String): Boolean = ??? +def dogCatOrWhatever(): Dog | Plant | Car | Sun = ??? +``` + +{% endtab %} +{% endtabs %} + +Как видно из примера, при использовании объединения типы необязательно должны иметь общую иерархию, +и их по-прежнему можно принимать в качестве аргументов или возвращать из метода. + +При разработке приложений такие функции, как вывод типов, +используются каждый день, а generics - каждую неделю. +При чтении Scaladoc для классов и методов, также необходимо иметь некоторое представление о _ковариантности_. +Использование типов может быть относительно простым, +а также обеспечивает большую выразительность, гибкость и контроль для разработчиков библиотек. + +## Преимущества типов + +Языки программирования со статической типизацией предлагают ряд преимуществ, в том числе: + +- помощь IDE в обеспечении надежной поддержки +- устранение многих классов потенциальных ошибок во время компиляции +- помощь в рефакторинге +- предоставление надежной документации, которая не может быть нерелевантной, поскольку проверена на тип + +## Знакомство с особенностями системы типов в Scala + +Учитывая это краткое введение, в следующих разделах представлен обзор особенностей системы типов в Scala. + +[union-types]: {% link _overviews/scala3-book/types-union.md %} diff --git a/_ru/scala3/book/types-opaque-types.md b/_ru/scala3/book/types-opaque-types.md new file mode 100644 index 0000000000..f6942738a9 --- /dev/null +++ b/_ru/scala3/book/types-opaque-types.md @@ -0,0 +1,178 @@ +--- +layout: multipage-overview +title: Непрозрачные типы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены и демонстрируются непрозрачные типы в Scala 3. +language: ru +num: 55 +previous-page: types-variance +next-page: types-structural +versionSpecific: true +--- + +_Непрозрачные псевдонимы типов_ (_opaque type aliases_) обеспечивают абстракцию типов без каких-либо **накладных расходов**. + +В Scala 2 аналогичный результат можно получить с помощью [классов значений][value-classes]. + +## Накладные расходы на абстракцию + +Предположим, что необходимо определить модуль, +предлагающий арифметические операции над числами, которые представлены их логарифмами. +Это может быть полезно для повышения точности, когда числовые значения очень большие или близкие к нулю. + +Поскольку важно отличать "обычные" `Double` от чисел, хранящихся в виде их логарифмов, введем класс `Logarithm`: + +```scala +class Logarithm(protected val underlying: Double): + def toDouble: Double = math.exp(underlying) + def + (that: Logarithm): Logarithm = + // здесь используется метод apply сопутствующего объекта + Logarithm(this.toDouble + that.toDouble) + def * (that: Logarithm): Logarithm = + new Logarithm(this.underlying + that.underlying) + +object Logarithm: + def apply(d: Double): Logarithm = new Logarithm(math.log(d)) +``` + +Метод `apply` сопутствующего объекта позволяет создавать значения типа `Logarithm`, +которые можно использовать следующим образом: + +```scala +val l2 = Logarithm(2.0) +val l3 = Logarithm(3.0) +println((l2 * l3).toDouble) // выводит 6.0 +println((l2 + l3).toDouble) // выводит 4.999... +``` + +В то время как класс `Logarithm` предлагает хорошую абстракцию для значений `Double`, +которые хранятся в этой конкретной логарифмической форме, +это накладывает серьезные накладные расходы на производительность: +для каждой отдельной математической операции нужно извлекать значение `underlying`, +а затем снова обернуть его в новый экземпляр `Logarithm`. + +## Модульные абстракции + +Рассмотрим другой подход к реализации той же библиотеки. +На этот раз вместо того, чтобы определять `Logarithm` как класс, определяем его с помощью _псевдонима типа_. +Во-первых, зададим абстрактный интерфейс модуля: + +```scala +trait Logarithms: + + type Logarithm + + // операции на Logarithm + def add(x: Logarithm, y: Logarithm): Logarithm + def mul(x: Logarithm, y: Logarithm): Logarithm + + // функции конвертации между Double и Logarithm + def make(d: Double): Logarithm + def extract(x: Logarithm): Double + + // методы расширения, для вызова `add` и `mul` в качестве "методов" на Logarithm + extension (x: Logarithm) + def toDouble: Double = extract(x) + def + (y: Logarithm): Logarithm = add(x, y) + def * (y: Logarithm): Logarithm = mul(x, y) +``` + +Теперь давайте реализуем этот абстрактный интерфейс, задав тип `Logarithm` равным `Double`: + +```scala +object LogarithmsImpl extends Logarithms: + + type Logarithm = Double + + // операции на Logarithm + def add(x: Logarithm, y: Logarithm): Logarithm = make(x.toDouble + y.toDouble) + def mul(x: Logarithm, y: Logarithm): Logarithm = x + y + + // функции конвертации между Double и Logarithm + def make(d: Double): Logarithm = math.log(d) + def extract(x: Logarithm): Double = math.exp(x) +``` + +В рамках реализации `LogarithmsImpl` уравнение `Logarithm = Double` позволяет реализовать различные методы. + +#### Дырявые абстракции + +Однако эта абстракция немного "дырява". +Мы должны убедиться, что всегда программируем _только_ с абстрактным интерфейсом `Logarithms` +и никогда не используем `LogarithmsImpl` напрямую. +Прямое использование `LogarithmsImpl` сделало бы равенство `Logarithm = Double` видимым для пользователя, +который может случайно использовать `Double` там, где ожидается логарифмическое удвоение. +Например: + +```scala +import LogarithmsImpl.* +val l: Logarithm = make(1.0) +val d: Double = l // проверка типов ДОЗВОЛЯЕТ равенство! +``` + +Необходимость разделения модуля на абстрактный интерфейс и реализацию может быть полезной, +но также требует больших усилий, чтобы просто скрыть детали реализации `Logarithm`. +Программирование с использованием абстрактного модуля `Logarithms` может быть очень утомительным +и часто требует использования дополнительных функций, таких как типы, зависящие от пути, как в следующем примере: + +```scala +def someComputation(L: Logarithms)(init: L.Logarithm): L.Logarithm = ... +``` + +#### Накладные расходы упаковки/распаковки + +Абстракции типов, такие как `type Logarithm`, [стираются](https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure) +в соответствии с их привязкой (`Any` - в нашем случае). +То есть, хотя нам не нужно вручную переносить и разворачивать значение `Double`, +все равно будут некоторые накладные расходы, связанные с упаковкой примитивного типа `Double`. + +## Непрозрачные типы + +Вместо того чтобы вручную разбивать компонент `Logarithms` на абстрактную часть и на конкретную реализацию, +можно просто использовать opaque типы для достижения аналогичного эффекта: + +```scala +object Logarithms: +//vvvvvv это важное различие! + opaque type Logarithm = Double + + object Logarithm: + def apply(d: Double): Logarithm = math.log(d) + + extension (x: Logarithm) + def toDouble: Double = math.exp(x) + def + (y: Logarithm): Logarithm = Logarithm(math.exp(x) + math.exp(y)) + def * (y: Logarithm): Logarithm = x + y +``` + +Тот факт, что `Logarithm` совпадает с `Double`, известен только в области, где он определен, +которая в приведенном выше примере соответствует объекту `Logarithms`. +Равенство `Logarithm = Double` может использоваться для реализации методов (например, `*` и `toDouble`). + +Однако вне модуля тип `Logarithm` полностью инкапсулирован или «непрозрачен». +Для пользователей `Logarithm`-а невозможно обнаружить, что `Logarithm` на самом деле реализован как `Double`: + +```scala +import Logarithms.* +val log2 = Logarithm(2.0) +val log3 = Logarithm(3.0) +println((log2 * log3).toDouble) // выводит 6.0 +println((log2 + log3).toDouble) // выводит 4.999... + +val d: Double = log2 // ERROR: Found Logarithm required Double +``` + +Несмотря на то, что мы абстрагировались от `Logarithm`, абстракция предоставляется бесплатно: +поскольку существует только одна реализация, во время выполнения не будет накладных расходов +на упаковку для примитивных типов, таких как `Double`. + +### Обзор непрозрачных типов + +Непрозрачные типы предлагают надежную абстракцию над деталями реализации, не накладывая расходов на производительность. +Как показано выше, непрозрачные типы удобны в использовании и очень хорошо интегрируются с [функцией методов расширения][extension]. + +[extension]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[value-classes]: {% link _overviews/core/value-classes.md %} diff --git a/_ru/scala3/book/types-others.md b/_ru/scala3/book/types-others.md new file mode 100644 index 0000000000..131bdd403b --- /dev/null +++ b/_ru/scala3/book/types-others.md @@ -0,0 +1,30 @@ +--- +layout: multipage-overview +title: Другие типы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе упоминаются другие расширенные типы в Scala 3. +language: ru +num: 58 +previous-page: types-dependent-function +next-page: ca-contextual-abstractions-intro +versionSpecific: true +--- + +В Scala есть несколько других расширенных типов, которые не показаны в этой книге, в том числе: + +- Лямбда-типы +- Типы соответствия +- Экзистенциальные типы +- Типы высшего порядка +- Синглтон-типы +- Типы уточнения +- Вид полиморфизма + +Дополнительные сведения об этих типах см. в [Справочной документации Scala 3][reference]. +Для singleton типов см. раздел [literal types](https://scala-lang.org/files/archive/spec/3.4/03-types.html#literal-types) +спецификации Scala 3, а для уточненных типов — раздел [refined types](https://scala-lang.org/files/archive/spec/3.4/03-types.html). + +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_ru/scala3/book/types-structural.md b/_ru/scala3/book/types-structural.md new file mode 100644 index 0000000000..103e6db389 --- /dev/null +++ b/_ru/scala3/book/types-structural.md @@ -0,0 +1,120 @@ +--- +layout: multipage-overview +title: Структурные типы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены и демонстрируются структурные типы в Scala 3. +language: ru +num: 56 +previous-page: types-opaque-types +next-page: types-dependent-function +versionSpecific: true +--- + +_Scala 2 содержит более слабую форму структурных типов, основанную на Java reflection, +достигаемую с помощью `import scala.language.reflectiveCalls`_. + +## Введение + +Некоторые варианты использования, такие как моделирование доступа к базе данных, +более удобны в динамически типизированных языках, чем в статически типизированных языках. +С динамически типизированными языками естественно моделировать строку как запись или объект +и выбирать записи с помощью простых точечных обозначений, например `row.columnName`. + +Достижение того же результата в статически типизированном языке требует определения класса для каждой возможной строки, +возникающей в результате манипуляций с базой данных, включая строки, возникающие в результате `join` и проектирования, +и настройки схемы для сопоставления между строкой и представляющим ее классом. + +Это требует большого количества шаблонов, +что заставляет разработчиков менять преимущества статической типизации на более простые схемы, +в которых имена столбцов представляются в виде строк и передаются другим операторам, например `row.select("columnName")`. +Этот подход лишен преимуществ статической типизации и все еще не так естественен, как динамически типизируемая версия. + +Структурные типы (structural types) помогают в ситуациях, +когда желательно поддерживать простую точечную нотацию в динамических контекстах, не теряя преимуществ статической типизации. +Они также позволяют разработчикам настраивать, как должны определяться поля и методы. + +## Пример + +Вот пример структурного типа `Person`: + +```scala +class Record(elems: (String, Any)*) extends Selectable: + private val fields = elems.toMap + def selectDynamic(name: String): Any = fields(name) + +type Person = Record { + val name: String + val age: Int +} +``` + +Тип `Person` добавляет _уточнение_ (_refinement_) к своему родительскому типу `Record`, которое определяет поля `name` и `age`. +Говорится, что уточнение носит _структурный_ (_structural_) характер, +поскольку `name` и `age` не определены в родительском типе. +Но тем не менее они существуют как члены класса `Person`. +Например, следующая программа напечатала бы `"Emma is 42 years old."`: + +```scala +val person = Record( + "name" -> "Emma", + "age" -> 42 +).asInstanceOf[Person] + +println(s"${person.name} is ${person.age} years old.") +``` + +Родительский тип `Record` в этом примере представляет собой универсальный класс, +который может в своем аргументе `elems` принимать произвольные записи. +Этот аргумент - последовательность пар ключей типа `String` и значений типа `Any`. +Когда создается `Person` как `Record`, необходимо с помощью приведения типов задать, +что запись определяет правильные поля правильных типов. +Сама `Record` слишком слабо типизирована, поэтому компилятор не может знать об этом без помощи пользователя. +На практике связь между структурным типом и его базовым общим представлением, скорее всего, +будет выполняться на уровне базы данных и, следовательно, не будет беспокоить конечного пользователя. + +`Record` расширяет маркер `trait scala.Selectable` и определяет метод `selectDynamic`, +который сопоставляет имя поля с его значением. +Выбор элемента структурного типа выполняется путем вызова соответствующего метода. +`person.name` и `person.age` преобразуются компилятором Scala в: + +```scala +person.selectDynamic("name").asInstanceOf[String] +person.selectDynamic("age").asInstanceOf[Int] +``` + +## Второй пример + +Чтобы закрепить сказанное, вот еще один структурный тип с именем `Book`, представляющий книгу, доступную в базе данных: + +```scala +type Book = Record { + val title: String + val author: String + val year: Int + val rating: Double +} +``` + +Как и в случае с `Person`, экземпляр `Book` создается следующим образом: + +```scala +val book = Record( + "title" -> "The Catcher in the Rye", + "author" -> "J. D. Salinger", + "year" -> 1951, + "rating" -> 4.5 +).asInstanceOf[Book] +``` + +## Класс Selectable + +Помимо `selectDynamic` класс `Selectable` иногда также определяет метод `applyDynamic`, +который можно использовать для замены вызовов функций на вызов структурных элементов. +Таким образом, если `a` является экземпляром `Selectable`, структурный вызов типа `a.f(b, c)` преобразуется в: + +```scala +a.applyDynamic("f")(b, c) +``` diff --git a/_ru/scala3/book/types-union.md b/_ru/scala3/book/types-union.md new file mode 100644 index 0000000000..5c3a089488 --- /dev/null +++ b/_ru/scala3/book/types-union.md @@ -0,0 +1,110 @@ +--- +layout: multipage-overview +title: Объединение типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлены объединение типов в Scala 3. +language: ru +num: 52 +previous-page: types-intersection +next-page: types-adts-gadts +versionSpecific: true +--- + +Используемый для типов `|` оператор создает так называемый _тип объединения_ (_union type_). +Тип `А | B` представляет значения, которые относятся **либо** к типу `A`, **либо** к типу `B`. + +В следующем примере метод `help` принимает параметр с именем `id` типа объединения `Username | Password`, +который может быть либо `Username`, либо `Password`: + +```scala +case class Username(name: String) +case class Password(hash: Hash) + +def help(id: Username | Password) = + val user = id match + case Username(name) => lookupName(name) + case Password(hash) => lookupPassword(hash) + // дальнейший код ... +``` + +Мы реализуем метод `help`, разделяя две альтернативы с использованием сопоставления с образцом. + +Этот код является гибким и типобезопасным решением. +Если попытаться передать тип, отличный от `Username` или `Password`, компилятор пометит это как ошибку: + +```scala +help("hi") // error: Found: ("hi" : String) + // Required: Username | Password +``` + +Ошибка также будет получена, если попытаться добавить `case` в выражение `match`, +которое не соответствует типам `Username` или `Password`: + +```scala +case 1.0 => ??? // Ошибка: это строка не компилируется +``` + +### Альтернатива объединенным типам + +Как показано, объединенные типы могут использоваться для представления вариантов нескольких разных типов, +не требуя, чтобы эти типы были частью специально созданной иерархии классов. + +#### Предварительное планирование иерархии классов + +Другие языки требуют предварительного планирования иерархии классов, как показано в следующем примере: + +```scala +trait UsernameOrPassword +case class Username(name: String) extends UsernameOrPassword +case class Password(hash: Hash) extends UsernameOrPassword +def help(id: UsernameOrPassword) = ... +``` + +Предварительное планирование не очень хорошо масштабируется, +поскольку, например, требования пользователей API могут быть непредсказуемыми. +Кроме того, загромождение иерархии типов маркерами типа `UsernameOrPassword` затрудняет чтение кода. + +#### Теговые объединения + +Другой альтернативой является задание отдельного типа перечисления, например: + +```scala +enum UsernameOrPassword: + case IsUsername(u: Username) + case IsPassword(p: Password) +``` + +Перечисление `UsernameOrPassword` представляет собой _помеченное_ (_tagged_) объединение `Username` и `Password`. +Однако этот способ моделирования объединения требует _явной упаковки и распаковки_, +и, например, `Username` **не** является подтипом `UsernameOrPassword`. + +### Вывод типов объединения + +Компилятор присваивает типу объединения выражение, _только если_ такой тип явно задан. +Например, рассмотрим такие значения: + +```scala +val name = Username("Eve") // name: Username = Username(Eve) +val password = Password(123) // password: Password = Password(123) +``` + +В этом REPL примере показано, +как можно использовать тип объединения при привязке переменной к результату выражения `if`/`else`: + +``` +scala> val a = if true then name else password +val a: Object = Username(Eve) + +scala> val b: Password | Username = if true then name else password +val b: Password | Username = Username(Eve) +``` + +Типом `a` является `Object`, который является супертипом `Username` и `Password`, +но не _наименьшим_ супертипом, `Password | Username`. +Если необходим наименьший супертип, его нужно указать явно, как это делается для `b`. + +> Типы объединения являются двойственными типам пересечения. +> И как `&` с типами пересечения, `|` также коммутативен: `A | B` того же типа, что и `B | А`. diff --git a/_ru/scala3/book/types-variance.md b/_ru/scala3/book/types-variance.md new file mode 100644 index 0000000000..fa2d409364 --- /dev/null +++ b/_ru/scala3/book/types-variance.md @@ -0,0 +1,283 @@ +--- +layout: multipage-overview +title: Вариантность +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этом разделе представлена и демонстрируется вариантность в Scala 3. +language: ru +num: 54 +previous-page: types-adts-gadts +next-page: types-opaque-types +--- + +_Вариантность_ (_variance_) параметра типа управляет подтипом параметризованных типов (таких, как классы или трейты). + +Чтобы объяснить вариантность, давайте рассмотрим следующие определения типов: + +{% tabs types-variance-1 %} +{% tab 'Scala 2 и 3' %} + +```scala +trait Item { def productNumber: String } +trait Buyable extends Item { def price: Int } +trait Book extends Buyable { def isbn: String } + +``` + +{% endtab %} +{% endtabs %} + +Предположим также следующие параметризованные типы: + +{% tabs types-variance-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-2 %} + +```scala +// пример инвариантного типа +trait Pipeline[T] { + def process(t: T): T +} + +// пример ковариантного типа +trait Producer[+T] { + def make: T +} + +// пример контрвариантного типа +trait Consumer[-T] { + def take(t: T): Unit +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=types-variance-2 %} + +```scala +// пример инвариантного типа +trait Pipeline[T]: + def process(t: T): T + +// пример ковариантного типа +trait Producer[+T]: + def make: T + +// пример контрвариантного типа +trait Consumer[-T]: + def take(t: T): Unit +``` + +{% endtab %} +{% endtabs %} + +В целом существует три режима вариантности (variance): + +- **инвариант** (invariant) — значение по умолчанию, написанное как `Pipeline[T]` +- **ковариантный** (covariant) — помечен знаком `+`, например `Producer[+T]` +- **контравариантный** (contravariant) — помечен знаком `-`, как в `Consumer[-T]` + +Подробнее рассмотрим, что означает и как используется эта аннотация. + +### Инвариантные типы + +По умолчанию такие типы, как `Pipeline`, инвариантны в своем аргументе типа (в данном случае `T`). +Это означает, что такие типы, как `Pipeline[Item]`, `Pipeline[Buyable]` и `Pipeline[Book]`, _не являются подтипами_ друг друга. + +И это правильно! Предположим, что следующий метод использует два значения (`b1`, `b2`) типа `Pipeline[Buyable]` +и передает свой аргумент `b` методу `process` при его вызове на `b1` и `b2`: + +{% tabs types-variance-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-3 %} + +```scala +def oneOf( + p1: Pipeline[Buyable], + p2: Pipeline[Buyable], + b: Buyable +): Buyable = { + val b1 = p1.process(b) + val b2 = p2.process(b) + if (b1.price < b2.price) b1 else b2 + } +``` + +{% endtab %} + +{% tab 'Scala 3' for=types-variance-3 %} + +```scala +def oneOf( + p1: Pipeline[Buyable], + p2: Pipeline[Buyable], + b: Buyable +): Buyable = + val b1 = p1.process(b) + val b2 = p2.process(b) + if b1.price < b2.price then b1 else b2 +``` + +{% endtab %} +{% endtabs %} + +Теперь вспомните, что у нас есть следующие _отношения подтипов_ между нашими типами: + +{% tabs types-variance-4 %} +{% tab 'Scala 2 и 3' %} + +```scala +Book <: Buyable <: Item +``` + +{% endtab %} +{% endtabs %} + +Мы не можем передать `Pipeline[Book]` методу `oneOf`, +потому что в реализации `oneOf` мы вызываем `p1` и `p2` со значением типа `Buyable`. +`Pipeline[Book]` ожидает `Book`, что потенциально может вызвать ошибку времени выполнения. + +Мы не можем передать `Pipeline[Item]`, потому что вызов `process` обещает вернуть `Item`; +однако мы должны вернуть `Buyable`. + +#### Почему Инвариант? + +На самом деле тип `Pipeline` должен быть инвариантным, +так как он использует свой параметр типа `T` _и в качестве_ аргумента, _и в качестве_ типа возвращаемого значения. +По той же причине некоторые типы в библиотеке коллекций Scala, такие как `Array` или `Set`, также являются _инвариантными_. + +### Ковариантные типы + +В отличие от `Pipeline`, который является инвариантным, +тип `Producer` помечается как **ковариантный** (covariant) путем добавления к параметру типа префикса `+`. +Это допустимо, так как параметр типа используется только в качестве типа _возвращаемого_ значения. + +Пометка типа как ковариантного означает, что мы можем передать (или вернуть) `Producer[Book]` там, +где ожидается `Producer[Buyable]`. И на самом деле, это разумно. +Тип `Producer[Buyable].make` только обещает _вернуть_ `Buyable`. +Но для пользователей `make`, так же допустимо принять `Book`, который является подтипом `Buyable`, +то есть это _по крайней мере_ `Buyable`. + +Это иллюстрируется следующим примером, где функция `makeTwo` ожидает `Producer[Buyable]`: + +{% tabs types-variance-5 %} +{% tab 'Scala 2 и 3' %} + +```scala +def makeTwo(p: Producer[Buyable]): Int = + p.make.price + p.make.price +``` + +{% endtab %} +{% endtabs %} + +Допустимо передать в `makeTwo` производителя книг: + +{% tabs types-variance-6 %} +{% tab 'Scala 2 и 3' %} + +```scala +val bookProducer: Producer[Book] = ??? +makeTwo(bookProducer) +``` + +{% endtab %} +{% endtabs %} + +Вызов `price` в рамках `makeTwo` по-прежнему действителен и для `Book`. + +#### Ковариантные типы для неизменяемых контейнеров + +Ковариантность чаще всего встречается при работе с неизменяемыми контейнерами, такими как `List`, `Seq`, `Vector` и т.д. + +Например, `List` и `Vector` определяются приблизительно так: + +{% tabs types-variance-7 %} +{% tab 'Scala 2 и 3' %} + +```scala +class List[+A] ... +class Vector[+A] ... +``` + +{% endtab %} +{% endtabs %} + +Таким образом, можно использовать `List[Book]` там, где ожидается `List[Buyable]`. +Это также интуитивно имеет смысл: если ожидается коллекция вещей, которые можно купить, +то вполне допустимо получить коллекцию книг. +В примере выше у книг есть дополнительный метод `isbn`, но дополнительные возможности можно игнорировать. + +### Контравариантные типы + +В отличие от типа `Producer`, который помечен как ковариантный, +тип `Consumer` помечен как **контравариантный** (contravariant) путем добавления к параметру типа префикса `-`. +Это допустимо, так как параметр типа используется только _в позиции аргумента_. + +Пометка его как контравариантного означает, что можно передать (или вернуть) `Consumer[Item]` там, +где ожидается `Consumer[Buyable]`. +То есть у нас есть отношение подтипа `Consumer[Item] <: Consumer[Buyable]`. +Помните, что для типа `Producer` все было наоборот, и у нас был `Producer[Buyable] <: Producer[Item]`. + +И в самом деле, это разумно. Метод `Consumer[Item].take` принимает `Item`. +Как вызывающий `take`, мы также можем предоставить `Buyable`, который будет с радостью принят `Consumer[Item]`, +поскольку `Buyable` — это подтип `Item`, то есть, _по крайней мере_, `Item`. + +#### Контравариантные типы для потребителей + +Контравариантные типы встречаются гораздо реже, чем ковариантные типы. +Как и в нашем примере, вы можете думать о них как о «потребителях». +Наиболее важным типом, помеченным как контравариантный, с которым можно столкнуться, является тип функций: + +{% tabs types-variance-8 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-8 %} + +```scala +trait Function[-A, +B] { + def apply(a: A): B +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=types-variance-8 %} + +```scala +trait Function[-A, +B]: + def apply(a: A): B +``` + +{% endtab %} +{% endtabs %} + +Тип аргумента `A` помечен как контравариантный `A` — он использует значения типа `A`. +Тип результата `B`, напротив, помечен как ковариантный — он создает значения типа `B`. + +Вот несколько примеров, иллюстрирующих отношения подтипов, вызванные аннотациями вариантности функций: + +{% tabs types-variance-9 %} +{% tab 'Scala 2 и 3' %} + +```scala +val f: Function[Buyable, Buyable] = b => b + +// OK - допустимо вернуть Buyable там, где ожидается Item +val g: Function[Buyable, Item] = f + +// OK - допустимо передать аргумент Book туда, где ожидается Buyable +val h: Function[Book, Buyable] = f +``` + +{% endtab %} +{% endtabs %} + +## Резюме + +В этом разделе были рассмотрены три различных вида вариантности: + +- **Producers** обычно ковариантны и помечают свой параметр типа со знаком `+`. + Это справедливо и для неизменяемых коллекций. +- **Consumers** обычно контравариантны и помечают свой параметр типа со знаком `-`. +- Типы, которые являются **одновременно** производителями и потребителями, + должны быть инвариантными и не требуют какой-либо маркировки для параметра своего типа. + В эту категорию, в частности, попадают изменяемые коллекции, такие как `Array`. diff --git a/_ru/scala3/book/why-scala-3.md b/_ru/scala3/book/why-scala-3.md new file mode 100644 index 0000000000..6f2d7eb1a1 --- /dev/null +++ b/_ru/scala3/book/why-scala-3.md @@ -0,0 +1,492 @@ +--- +layout: multipage-overview +title: Почему Scala 3? +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице описаны преимущества языка программирования Scala 3. +language: ru +num: 3 +previous-page: scala-features +next-page: taste-intro +--- + +Использование Scala, и Scala 3 в частности, дает много преимуществ. +Трудно перечислить их все, но “топ десять” может выглядеть так: + +1. Scala сочетает в себе функциональное программирование (ФП) и объектно-ориентированное программирование (ООП) +2. Scala статически типизирован, но часто ощущается как язык с динамической типизацией +3. Синтаксис Scala лаконичен, но все же удобочитаем; его часто называют _выразительным_ +4. _Implicits_ в Scala 2 были определяющей функцией, а в Scala 3 они были улучшены и упрощены +5. Scala легко интегрируется с Java, поэтому вы можете создавать проекты со смешанным кодом Scala и Java, а код Scala легко использует тысячи существующих библиотек Java +6. Scala можно использовать на сервере, а также в браузере со [Scala.js](https://www.scala-js.org) +7. Стандартная библиотека Scala содержит десятки готовых функциональных методов, позволяющих сэкономить ваше время и значительно сократить потребность в написании пользовательских циклов `for` и алгоритмов +8. “Best practices”, встроенные в Scala, поддерживают неизменность, анонимные функции, функции высшего порядка, сопоставление с образцом, классы, которые не могут быть расширены по умолчанию, и многое другое +9. Экосистема Scala предлагает самые современные ФП библиотеки в мире +10. Сильная система типов + + +## 1) Слияние ФП/ООП + +Больше, чем любой другой язык, Scala поддерживает слияние парадигм ФП и ООП. +Как заявил Мартин Одерски, сущность Scala — это слияние функционального и объектно-ориентированного программирования в типизированной среде, где: + +- Функции для логики +- Объекты для модульности + +Возможно, одними из лучших примеров модульности являются классы стандартной библиотеки. +Например, `List` определяется как класс---технически это абстрактный класс---и новый экземпляр создается следующим образом: + +{% tabs list %} +{% tab 'Scala 2 и 3' for=list %} +```scala +val x = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +Однако то, что кажется программисту простым `List`, на самом деле построено из комбинации нескольких специализированных типов, +включая трейты с именами `Iterable`, `Seq` и `LinearSeq`. +Эти типы также состоят из других небольших модульных единиц кода. + +В дополнение к построению типа наподобие `List` из серии модульных трейтов, +`List` API также состоит из десятков других методов, многие из которых являются функциями высшего порядка: + +{% tabs list-methods %} +{% tab 'Scala 2 и 3' for=list-methods %} +```scala +val xs = List(1, 2, 3, 4, 5) + +xs.map(_ + 1) // List(2, 3, 4, 5, 6) +xs.filter(_ < 3) // List(1, 2) +xs.find(_ > 3) // Some(4) +xs.takeWhile(_ < 3) // List(1, 2) +``` +{% endtab %} +{% endtabs %} + +В этих примерах значения в списке не могут быть изменены. +Класс `List` неизменяем, поэтому все эти методы возвращают новые значения, как показано в каждом комментарии. + +## 2) Ощущение динамики + +_Вывод типов_ (_type inference_) в Scala часто заставляет язык чувствовать себя динамически типизированным, даже если он статически типизирован. +Это верно для объявления переменной: + +{% tabs dynamic %} +{% tab 'Scala 2 и 3' for=dynamic %} +```scala +val a = 1 +val b = "Hello, world" +val c = List(1,2,3,4,5) +val stuff = ("fish", 42, 1_234.5) +``` +{% endtab %} +{% endtabs %} + +Это также верно при передаче анонимных функций функциям высшего порядка: + +{% tabs dynamic-hof %} +{% tab 'Scala 2 и 3' for=dynamic-hof %} +```scala +list.filter(_ < 4) +list.map(_ * 2) +list.filter(_ < 4) + .map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +и при определении методов: + +{% tabs dynamic-method %} +{% tab 'Scala 2 и 3' for=dynamic-method %} +```scala +def add(a: Int, b: Int) = a + b +``` +{% endtab %} +{% endtabs %} + +Это как никогда верно для Scala 3, например, при использовании [типов объединения][union-types]: + +{% tabs union %} +{% tab 'Только в Scala 3' for=union %} +```scala +// параметр типа объединения +def help(id: Username | Password) = + val user = id match + case Username(name) => lookupName(name) + case Password(hash) => lookupPassword(hash) + // дальнейший код ... + +// значение типа объединения +val b: Password | Username = if (true) name else password +``` +{% endtab %} +{% endtabs %} + +## 3) Лаконичный синтаксис + +Scala — это неформальный, “краткий, но все же читабельный“ язык. Например, объявление переменной лаконично: + +{% tabs concise %} +{% tab 'Scala 2 и 3' for=concise %} +```scala +val a = 1 +val b = "Hello, world" +val c = List(1,2,3) +``` +{% endtab %} +{% endtabs %} + +Создание типов, таких как трейты, классы и перечисления, является кратким: + +{% tabs enum %} +{% tab 'Только в Scala 3' for=enum %} +```scala +trait Tail: + def wagTail(): Unit + def stopTail(): Unit + +enum Topping: + case Cheese, Pepperoni, Sausage, Mushrooms, Onions + +class Dog extends Animal, Tail, Legs, RubberyNose + +case class Person( + firstName: String, + lastName: String, + age: Int +) +``` +{% endtab %} +{% endtabs %} + +Функции высшего порядка кратки: + +{% tabs list-hof %} +{% tab 'Scala 2 и 3' for=list-hof %} + +```scala +list.filter(_ < 4) +list.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +Все эти и многие другие выражения кратки и при этом очень удобочитаемы: то, что мы называем _выразительным_ (_expressive_). + +## 4) Implicits, упрощение + +Implicits в Scala 2 были главной отличительной особенностью дизайна. +Они представляли собой фундаментальный способ абстрагирования от контекста с единой парадигмой, +обслуживающей множество вариантов использования, среди которых: + +- Реализация [типовых классов]({% link _overviews/scala3-book/ca-type-classes.md %}) +- Установление контекста +- Внедрение зависимости +- Выражение возможностей + +С тех пор другие языки внедрили аналогичные концепции, все из которых являются вариантами основной идеи _вывода терминов_: +при заданном типе компилятор синтезирует “канонический” термин этого типа. + +Хотя implicits были определяющей функцией в Scala 2, их дизайн был значительно улучшен в Scala 3: + +- Есть единственный способ определить значения “given” +- Есть единственный способ ввести неявные параметры и аргументы +- Есть отдельный способ импорта givens, который не позволяет им потеряться в море обычного импорта +- Существует единственный способ определить неявное преобразование, которое четко обозначено как таковое и не требует специального синтаксиса + +К преимуществам этих изменений относятся: + +- Новый дизайн позволяет избежать взаимодействия функциональностей и делает язык более согласованным +- Это делает implicits более простыми для изучения и более сложными для злоупотребления +- Это значительно улучшает ясность 95% программ Scala, использующих implicits +- У него есть потенциал, чтобы сделать вывод терминов принципиальным способом, который также доступен и удобен + +Эти возможности подробно расписаны в соответствующих разделах, таких как [введение в контекстную абстракцию][contextual], а также раздел о [`given` и предложениях `using`][given] для получения более подробной информации. + +## 5) Полная интеграция с Java + +Взаимодействие между Scala и Java не вызывает затруднений во многих ситуациях. +Например: + +- Вы можете использовать все тысячи библиотек Java, доступных в ваших проектах Scala +- Scala `String` — это, по сути, Java `String` с дополнительными возможностями +- Scala легко использует классы даты/времени из Java пакета *java.time._* + +Вы также можете использовать классы коллекций Java в Scala, а для придания им большей функциональности Scala включает методы, +позволяющие преобразовывать их в коллекции Scala. + +Несмотря на то, что почти каждое взаимодействие является бесшовным, +в [главе “Взаимодействие с Java”][java] показано, как лучше использовать некоторые функции вместе, +в том числе как использовать: + +- Коллекции Java в Scala +- Java `Optional` в Scala +- Интерфейсы Java в Scala +- Коллекции Scala в Java +- Scala `Option` в Java +- Scala traits в Java +- Методы Scala, вызывающие исключения в Java коде +- Scala varargs параметры в Java + +Подробнее об этих функциях см. в этой главе. + +## 6) Клиент & сервер + +Scala можно использовать на стороне сервера с потрясающими фреймворками: + +- [Play Framework](https://www.playframework.com) позволяет создавать масштабируемые серверные приложения и микросервисы +- [Akka Actors](https://akka.io) позволяет использовать модель акторов для значительного упрощения распределенных и параллельных программных приложений + +Scala также можно использовать в браузере с [проектом Scala.js](https://www.scala-js.org), который является безопасной заменой JavaScript. +В экосистеме Scala.js есть [десятки библиотек](https://www.scala-js.org/libraries), позволяющих использовать React, Angular, jQuery +и многие другие библиотеки JavaScript и Scala в браузере. + +В дополнение к этим инструментам проект [Scala Native](https://github.com/scala-native/scala-native) +“представляет собой оптимизирующий опережающий компилятор и облегченную управляемую среду выполнения, разработанную специально для Scala”. +Он позволяет создавать бинарные исполняемые приложения в “системном” стиле с помощью простого кода Scala, а также позволяет использовать низкоуровневые примитивы. + +## 7) Стандартные библиотечные методы + +Вам довольно редко понадобится писать пользовательский цикл `for`, +потому что десятки готовых функциональных методов в стандартной библиотеке Scala сэкономят ваше время +и помогут сделать код более согласованным в разных приложениях. + +В следующих примерах показаны некоторые из встроенных методов коллекций, а также многие другие. +Хотя все они используют класс `List`, одни и те же методы работают с другими классами коллекций, +такими как `Seq`, `Vector`, `LazyList`, `Set`, `Map`, `Array` и `ArrayBuffer`. + +Вот некоторые примеры: + +{% tabs list-more %} +{% tab 'Scala 2 и 3' for=list-more %} +```scala +List.range(1, 3) // List(1, 2) +List.range(start = 1, end = 6, step = 2) // List(1, 3, 5) +List.fill(3)("foo") // List(foo, foo, foo) +List.tabulate(3)(n => n * n) // List(0, 1, 4) +List.tabulate(4)(n => n * n) // List(0, 1, 4, 9) + +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.filter(_ > 100) // List() +a.find(_ > 20) // Some(30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.intersect(List(19,20,21)) // List(20) +a.last // 10 +a.lastOption // Some(10) +a.map(_ * 2) // List(20, 40, 60, 80, 20) +a.slice(2, 4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +a.takeWhile(_ < 30) // List(10, 20) +a.filter(_ < 30).map(_ * 10) // List(100, 200, 100) + +val fruits = List("apple", "pear") +fruits.map(_.toUpperCase) // List(APPLE, PEAR) +fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R) + +val nums = List(10, 5, 8, 1, 7) +nums.sorted // List(1, 5, 7, 8, 10) +nums.sortWith(_ < _) // List(1, 5, 7, 8, 10) +nums.sortWith(_ > _) // List(10, 8, 7, 5, 1) +``` +{% endtab %} +{% endtabs %} + +## 8) Встроенные "best practices" + +Идиомы Scala поощряют "best practices" во многих ситуациях. +Для неизменяемости рекомендуется создавать неизменяемые val переменные: + +{% tabs val %} +{% tab 'Scala 2 и 3' for=val %} +```scala +val a = 1 // неизменяемая переменная +``` +{% endtab %} +{% endtabs %} + +Вам также рекомендуется использовать неизменяемые классы коллекций, такие как `List` и `Map`: + +{% tabs list-map %} +{% tab 'Scala 2 и 3' for=list-map %} +```scala +val b = List(1,2,3) // List неизменяем +val c = Map(1 -> "one") // Map неизменяема +``` +{% endtab %} +{% endtabs %} + +Case классы в первую очередь предназначены для использования в [моделировании предметной области]({% link _overviews/scala3-book/domain-modeling-intro.md %}), и их параметры также неизменяемы: + +{% tabs case-class %} +{% tab 'Scala 2 и 3' for=case-class %} +```scala +case class Person(name: String) +val p = Person("Michael Scott") +p.name // Michael Scott +p.name = "Joe" // compiler error (переназначение val name) +``` +{% endtab %} +{% endtabs %} + +Как показано в предыдущем разделе, классы коллекций Scala поддерживают функции высшего порядка, +и вы можете передавать в них методы (не показаны) и анонимные функции: + +{% tabs higher-order %} +{% tab 'Scala 2 и 3' for=higher-order %} +```scala +a.dropWhile(_ < 25) +a.filter(_ < 25) +a.takeWhile(_ < 30) +a.filter(_ < 30).map(_ * 10) +nums.sortWith(_ < _) +nums.sortWith(_ > _) +``` +{% endtab %} +{% endtabs %} + +Выражения `match` позволяют использовать сопоставление с образцом, и они действительно являются _выражениями_, которые возвращают значения: + +{% tabs match class=tabs-scala-version %} +{% tab 'Scala 2' for=match %} +```scala +val numAsString = i match { + case 1 | 3 | 5 | 7 | 9 => "odd" + case 2 | 4 | 6 | 8 | 10 => "even" + case _ => "too big" +} +``` +{% endtab %} + +{% tab 'Scala 3' for=match %} +```scala +val numAsString = i match + case 1 | 3 | 5 | 7 | 9 => "odd" + case 2 | 4 | 6 | 8 | 10 => "even" + case _ => "too big" +``` +{% endtab %} +{% endtabs %} + +Поскольку они могут возвращать значения, их часто используют в качестве тела метода: + +{% tabs match-body class=tabs-scala-version %} +{% tab 'Scala 2' for=match-body %} +```scala +def isTruthy(a: Matchable) = a match { + case 0 | "" => false + case _ => true +} +``` +{% endtab %} + +{% tab 'Scala 3' for=match-body %} +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" => false + case _ => true +``` +{% endtab %} +{% endtabs %} + +## 9) Библиотеки экосистемы + +Библиотеки Scala для функционального программирования, такие как [Cats](https://typelevel.org/cats) и [Zio](https://zio.dev), +являются передовыми библиотеками в сообществе ФП. +Об этих библиотеках можно сказать все модные словечки, такие как высокопроизводительная, типобезопасная, параллельная, асинхронная, ресурсобезопасная, тестируемая, функциональная, модульная, бинарно-совместимая, эффективная, эффектная и т.д. + +Мы могли бы перечислить здесь сотни библиотек, но, к счастью, все они перечислены в другом месте: подробности см. в списке [“Awesome Scala”](https://github.com/lauris/awesome-scala). + +## 10) Сильная система типов + +В Scala есть сильная система типов, и она была еще больше улучшена в Scala 3. +Цели Scala 3 были определены на раннем этапе, и к ним относятся: + +- Упрощение +- Устранение несоответствий +- Безопасность +- Эргономика +- Производительность + +_Упрощение_ достигается за счет десятков измененных и удаленных функций. +Например, изменения перегруженного ключевого слова `implicit` в Scala 2 на термины `given` и `using` в Scala 3 делает язык более понятным, особенно для начинающих разработчиков. + +_Устранение несоответствий_ связано с десятками [удаленных функций][dropped], [измененных функций][changed], и [добавленных функций][added] в Scala 3. +Некоторые из наиболее важных функций в этой категории: + +- Типы пересечения +- Типы объединения +- Неявные функциональные типы +- Зависимые функциональные типы +- Параметры трейтов +- Generic кортежи + +_Безопасность_ связана с несколькими новыми и измененными функциями: + +- Мультиверсальное равенство +- Ограничение неявных преобразований +- Null безопасность +- Безопасная инициализация + +Хорошими примерами _эргономики_ являются перечисления и методы расширения, +добавленные в Scala 3 довольно удобочитаемым образом: + +{% tabs extension %} +{% tab 'Только в Scala 3' for=extension %} +```scala +// перечисления +enum Color: + case Red, Green, Blue + +// методы расширения +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` +{% endtab %} +{% endtabs %} + +_Производительность_ относится к нескольким областям. +Одним из них являются [непрозрачные типы][opaque-types]. +В Scala 2 было несколько попыток создать решения, соответствующие практике проектирования, управляемого предметной областью (DDD), +когда значениям присваивались более осмысленные типы. +Эти попытки включали: + +- Псевдонимы типов +- Классы значений +- Case классы + +К сожалению, у всех этих подходов были недостатки, как описано в [SIP непрозрачных типов](https://docs.scala-lang.org/sips/opaque-types.html). +И наоборот, цель непрозрачных типов, как описано в этом SIP, заключается в том, что “операции с этими типами-оболочками не должны создавать дополнительных накладных расходов во время выполнения, но при этом обеспечивать безопасное использование типов во время компиляции”. + +Дополнительные сведения о системе типов см. в [справочной документации][reference]. + +## Другие замечательные функции + +Scala обладает множеством замечательных функций, и выбор Топ-10 может быть субъективным. +Несколько опросов показали, что разные группы разработчиков ценят разные функции. +Надеемся, вы откроете для себя больше замечательных возможностей Scala по мере использования языка. + +[java]: {% link _overviews/scala3-book/interacting-with-java.md %} +[given]: {% link _overviews/scala3-book/ca-context-parameters.md %} +[contextual]: {% link _overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[reference]: {{ site.scala3ref }} +[dropped]: {{ site.scala3ref }}/dropped-features +[changed]: {{ site.scala3ref }}/changed-features +[added]:{{ site.scala3ref }}/other-new-features + +[union-types]: {% link _overviews/scala3-book/types-union.md %} +[opaque-types]: {% link _overviews/scala3-book/types-opaque-types.md %} diff --git a/_ru/scala3/contribute-to-docs.md b/_ru/scala3/contribute-to-docs.md new file mode 100644 index 0000000000..d01570ac6e --- /dev/null +++ b/_ru/scala3/contribute-to-docs.md @@ -0,0 +1,68 @@ +--- +layout: singlepage-overview +title: Вклад в документацию +partof: scala3-scaladoc +scala3: true +language: ru +--- + +## Обзор +В настоящее время предпринимается множество усилий по созданию высококачественной документации для Scala 3. +В частности, это следующие документы: + +- Книга Scala 3 +- Учебник по макросам +- Руководство по миграции +- Справочник по языку Scala 3 + +Мы приветствуем вклад сообщества в каждый аспект документации. + + +### Как я могу внести свой вклад? +В целом, есть много способов, которыми вы можете нам помочь: + +- **Запутались в чем-то в любом из документов?** Откройте issue. +- **Нашли что-то неактуальное?** Откройте issue или создайте PR. +- **Опечатки и другие мелкие улучшения текста?** Создайте PR. +- **Хотите добавить что-то новое или внести большие изменения?** Отлично! Пожалуйста, откройте issue и давайте обсудим это. + +Как правило, каждый из различных проектов документации содержит ссылки +(как и этот документ на панели оглавления — пока видимые только в desktop view) для их редактирования и улучшения. +Кроме того, ниже мы предоставим вам всю необходимую информацию для начала работы. + + +## Книга Scala 3 +[Книга Scala 3][scala3-book] написана Alvin Alexander и содержит обзор всех важных функций Scala 3. +Она предназначена для читателей, которые только знакомятся со Scala. + +- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-book) +- [Вопросы](https://github.com/scala/docs.scala-lang/issues) + +## Учебник по макросам +[Учебник по макросам](/scala3/guides/macros) написан Nicolas Stucki и содержит подробную информацию о макросах в Scala 3 и best-practices. + +- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-macros) +- [Вопросы](https://github.com/scala/docs.scala-lang/issues) + +## Руководство по миграции +[Руководство по миграции на Scala 3](/scala3/guides/migration/compatibility-intro.html) содержит исчерпывающий обзор +совместимости между Scala 2 и Scala 3, презентацию по инструментам миграции и подробные руководства по миграции. + +- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration) +- [Вопросы](https://github.com/scala/docs.scala-lang/issues) + +## Руководство по содействию в разработке Scala 3 +[Руководство по содействию в разработке Scala 3](/scala3/guides/contribution/contribution-intro.html) +содержит исчерпывающий обзор вклада в разработку и внутреннего устройства компилятора и библиотек Scala 3. + +- [Исходники](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution) +- [Вопросы](https://github.com/scala/docs.scala-lang/issues) + +## Справочник по языку Scala 3 +[Справочник по Scala 3]({{ site.scala3ref }}) содержит формальное представление и подробную техническую информацию о различных возможностях языка. + +- [Исходники](https://github.com/scala/scala3/tree/main/docs/_docs) +- [Вопросы](https://github.com/scala/scala3/issues) + + +[scala3-book]: {% link _overviews/scala3-book/introduction.md %} diff --git a/_ru/scala3/guides/scaladoc/blog.md b/_ru/scala3/guides/scaladoc/blog.md new file mode 100644 index 0000000000..540a05bd03 --- /dev/null +++ b/_ru/scala3/guides/scaladoc/blog.md @@ -0,0 +1,87 @@ +--- +layout: multipage-overview +title: Встроенный блог +partof: scala3-scaladoc +language: ru +num: 5 +previous-page: static-site +next-page: site-versioning +--- + +Scaladoc позволяет включить в документацию простой блог. +На данный момент предоставляются только основные функции. +В будущем мы планируем включить более продвинутые функции, такие как теги или авторские страницы. + +К блогу относятся немного иначе, чем к обычным статическим сайтам. +Эта статья поможет вам создать свой собственный блог. + +## Правильная настройка каталога + +Статьи в блоге должны быть помещены в каталог `_blog/_posts`. + +``` +├── _blog +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html +``` + +Scaladoc загружает блог, если существует каталог `_blog`. + +## Соглашение об именовании + +Все имена файлов сообщений блога должны начинаться с даты в числовом формате, соответствующем `YYYY-MM-DD`. +Пример имени - `2022-06-17-dotty-compiler-bootstraps.md`. + +## Метаданные страницы + +Страницы блога в scaladoc поддерживают [Yaml Frontmatter](https://assemble.io/docs/YAML-front-matter.html), +что позволяет указывать различные значения, которые будут использоваться для метаданных на вашей странице. +Вот возможные поля: + +``` +--- +layout: <Ссылка на макет страницы для страницы блога> +author: <Автор страницы> +title: <Заголовок страницы> +subTitle: <Подзаголовок страницы> +date: <Дата создания страницы>, например, 2016-12-05 +authorImg: <Ссылка на картинку автора> +--- +<Содержимое страницы> +``` + +Вы также можете найти более подробную информацию о метаданных [на сайте документации Jekyll](https://jekyllrb.com/docs/front-matter/). + +## Синтаксис содержимого + +Имейте в виду, что для записи вашего блога необходимо использовать формат Markdown. +Более детальная информация о синтаксисе доступна в [Руководстве по Markdown](https://www.markdownguide.org/basic-syntax/). + +## Конфигурация блога + +Scaladoc позволяет настраивать блог, при его создании. + +Чтобы изменить настройки документации блога по умолчанию, +пользователям необходимо создать файл с именем `blog.yml` в **корневом каталоге блога**. +Этот файл должен содержать параметры, которые пользователь хочет изменить. +Например, если пользователь хочет изменить исходный каталог на "my_posts", +исходящий каталог на "my_docs" и временно скрыть блог, +то можно создать файл со следующим содержимым: + +``` +input: my_posts +output: my_docs +hidden: true +``` + +### Параметры: + +`input`: указывает каталог, содержащий markdown-файлы для постов блога (по умолчанию: "\_posts" в "docs"). + +`output`: указывает папку, в которой будут созданы HTML-страницы (по умолчанию: "blog" в "target/docs"). + +`hidden`: позволяет пользователям временно скрывать блог (по умолчанию: "false"). + +Чтобы изменить эти настройки, создайте файл с параметрами и сохраните его в корневом каталоге блога. +При следующей сборке блога будут использоваться новые параметры. diff --git a/_ru/scala3/guides/scaladoc/docstrings.md b/_ru/scala3/guides/scaladoc/docstrings.md new file mode 100644 index 0000000000..6ba32d082e --- /dev/null +++ b/_ru/scala3/guides/scaladoc/docstrings.md @@ -0,0 +1,222 @@ +--- +layout: multipage-overview +title: Docstrings - специфичные теги и особенности +partof: scala3-scaladoc +language: ru +num: 2 +previous-page: index +next-page: linking +--- + +В этой главе описывается, как правильно писать строки документации и как использовать все доступные функции scaladoc. +Так как многое осталось таким же, как и в старом scaladoc, некоторые детали взяты из этой +[статьи](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html). + +Scaladoc расширяет возможности Markdown дополнительными функциями, такими как ссылки на определения API. +Это можно использовать в статической документации и постах в блогах для создания смешанного контента. + +## Куда поместить строки документации + +Комментарии Scaladoc идут перед элементами, к которым они относятся, в специальном блоке комментариев, +который начинается с `/**` и заканчивается `*/`, например: + +```scala +/** Комментарий начинается здесь. + * Левая "звезда", за которой следует пробел в каждой строке, + * позволяет продолжить комментарий. + * + * Даже на пустых строках разрыва абзаца. + * + * Обратите внимание, что '*' в каждой строке выровнена + * со вторым '*' в '/**' так, чтобы + * левое поле находилось в том же столбце, где + * первая строка и последующие. + * + * Комментарий закрывается с помощью '*' и обратного слэша. + * + * Если используются теги Scaladoc (@param, @group и т.д.), + * не забудьте поместить их в отдельные строки без предшествующих им строк. + * + * Например: + * + * Рассчитать квадрат заданного числа + * + * @param d the Double to square + * @return the result of squaring d + */ + def square(d: Double): Double = d * d +``` + +В приведенном выше примере этот комментарий Scaladoc связан с методом square, +поскольку он находится прямо перед ним в исходном коде. + +Комментарии Scaladoc могут идти перед полями, методами, классами, трейтами, объектами. +На данный момент scaladoc не поддерживает прямое решение для документирования пакетов. +На гитхабе есть специальный [issue](https://github.com/scala/scala3/issues/11284), где вы можете проверить текущий статус проблемы. + +Для первичных конструкторов класса, которые в Scala совпадают с определением самого класса, +тег @constructor используется для указания комментария, помещаемого в документацию первичных конструкторов, а не в обзор класса. + +## Теги + +Scaladoc использует теги `@`для предоставления определенных подробностей полей в комментариях. +Теги включают: + +### Теги, специфичные для класса + +- `@constructor` помещенный в комментарий класса, будет описывать первичный конструктор. + +### Теги, специфичные для метода + +- `@return` для детализации возвращаемого значения из метода (по одному на метод). + +### Теги метода, конструктора и/или класса + +- `@throws` какие исключения (если есть) может генерировать метод или конструктор. +- `@param` детализация параметра метода или конструктора, предоставляется по одному `@param` для каждого параметра метода/конструктора. +- `@tparam` детализация параметра типа для метода, конструктора или класса. Указывается по одному для каждого параметра типа. + +### Теги использования + +- `@see` ссылки на другие источники информации, такие как ссылки на внешние документы или связанные объекты в документации. +- `@note` добавление примечания о предварительных или последующих условиях или любых других заметных ограничениях или ожиданиях. +- `@example` предоставление примера кода или соответствующей документации. + + +### Теги группировки + +Эти теги хорошо подходят для больших типов или пакетов со многими элементами. +Они позволяют организовать страницу Scaladoc в отдельные разделы, каждый из которых отображается отдельно в выбранном порядке. + +Эти теги не включены по умолчанию! Необходимо передать флаг `-groups` в Scaladoc, чтобы включить их. +В sbt это обычно выглядит примерно так: + +```scala +Compile / doc / scalacOptions ++= Seq( + "-groups" +) +``` + +Каждый раздел должен иметь идентификатор из одного слова, который используется во всех этих тегах, как показано ниже в `group`. +По умолчанию этот идентификатор отображается как заголовок раздела документации, +но можно использовать `@groupname`, чтобы указать более длинный заголовок. + +Как правило, необходимо поместить `@groupprio` (и, возможно, `@groupname` и `@groupdesc`) в Scaladoc для самого пакета/трейта/класса/объекта, +описывая все группы и их порядок. Затем поместить `@group` в Scaladoc для каждого члена, указав, в какой группе он находится. + +Члены, у которых нет тега `@group`, будут перечислены в результирующей документации как “Ungrouped”. + +- `@group ` - пометить сущность как члена `` группы +- `@groupname ` - указание необязательного имени для группы. `` отображается как заголовок группы перед её описанием. +- `@groupdesc ` - добавление необязательного описания для отображения под именем группы. Поддерживает многострочный форматированный текст. +- `@groupprio ` - управление порядком группы на странице. По умолчанию 0. Несгруппированные элементы имеют неявный приоритет 1000. + Используются значения от 0 до 999, чтобы задать положение относительно других групп. Малые значения появятся перед большими значениями. + +### Другие теги + +- `@author` предоставление информации об авторе для следующего объекта. +- `@version` версия системы или API, частью которой является этот объект. +- `@since` похож на `@version`, но определяет систему или API, в котором эта сущность была впервые определена. +- `@deprecated` помечает объект как устаревший, предоставляя как замену реализации, которую следует использовать, + так и версию/дату, когда этот объект устарел. +- `@syntax ` позволяет изменить парсер для docstring. Синтаксис по умолчанию — markdown, + однако можно изменить его с помощью этой директивы. В настоящее время доступны синтаксисы `markdown` или `wiki`. + Пример использования: `@syntax wiki`. + +### Макросы + +- `@define ` позволяет использовать $name в других комментариях Scaladoc в том же исходном файле, который будет заменен на ``. + +Если комментарий не предоставляется для объекта на текущем уровне наследования, +но предоставляется для переопределенного объекта на более высоком уровне иерархии наследования, +будет использоваться комментарий из суперкласса. + +Аналогично, если `@param`, `@tparam`, `@return` и другие теги сущностей опущены, но доступны из суперкласса, будут использоваться из суперкласса. + +### Явный + +Для явного наследования комментариев используется тег `@inheritdoc`. + +### Разметка + +Scaladoc предоставляет два анализатора синтаксиса: `markdown` (по умолчанию) или `wikidoc`. +В Scaladoc по-прежнему можно встраивать теги HTML (как и в Javadoc), но в большинстве случаев это не обязательно, +поскольку вместо этого может использоваться разметка. + +#### Markdown + +Markdown использует [вариант commonmark](https://spec.commonmark.org/current/) с двумя пользовательскими расширениями: +- `wikidoc` ссылки для удобства +- `wikidoc`кодовые блоки с синтаксисом фигурных скобок + +#### Wikidoc + +Wikidoc — это синтаксис, используемый для scala2 scaladoc. +Он поддерживается из-за многих существующих исходников, однако **не** рекомендуется его использование в новых проектах. +Синтаксис вики можно включить с помощью глобального флага `-comment-syntax wiki` или с помощью `@syntax wiki` директивы в строке документации. + +Некоторые из стандартных доступных разметок: + +``` +`monospace` +''italic text'' +'''bold text''' +__underline__ +^superscript^ +,,subscript,, +[[entity link]], e.g. [[scala.collection.Seq]] +[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]] +``` + +Для получения дополнительной информации о вики-ссылках см. [эту главу](#связывание-с-api). + +Другие примечания по форматированию + +- Абзацы начинаются с одной (или нескольких) пустых строк. `*` на полях для комментария допустимо (и должно быть включено), + в противном случае строка должна оставаться пустой. +- Заголовки определяются окружающими символами `=` с большим количеством `=` для обозначения подзаголовков. + Например `=Heading=`, `==Sub-Heading==` и т.д. +- Блоки списка представляют собой последовательность элементов списка с одинаковым стилем и уровнем, + без прерываний от других стилей блоков. Неупорядоченные списки можно маркировать с помощью `-`, + нумерованные списки можно обозначать с помощью `1.`, `i.`, `I.` или `a.` для различных стилей нумерации. + В обоих случаях должно быть дополнительное пространство впереди, а большее пространство создает подуровень. + +Разметка для блоков списка выглядит так: + +``` +/** Вот неупорядоченный список: + * + * - Первый элемент + * - Второй элемент + * - Подпункт ко второму + * - Еще один подпункт + * - Третий пункт + * + * Вот упорядоченный список: + * + * 1. Первый пронумерованный элемент + * 1. Второй номер позиции + * i. Подпункт ко второму + * i. Еще один подпункт + * 1. Третий пункт + */ +``` + +### Общие примечания по написанию комментариев к Scaladoc + +Краткость - это хорошо! Быстро переходите к сути, у людей ограничено время, которое они могут потратить на вашу документацию, +используйте его с умом. Опустите ненужные слова. "Prefer возвращает X", а не "этот метод возвращает X", +и "X, Y и Z", а не "этот метод возвращает X, Y и Z". +Принцип DRY (_Don’t repeat yourself_) - не повторяйтесь. +Не дублируйте описание метода в теге `@return` и других формах повторяющихся комментариев. + +### Подробнее о написании Scaladoc + +Дополнительную информацию о рекомендациях по форматированию и стилю можно найти +в [руководстве по стилю Scala-lang scaladoc](https://docs.scala-lang.org/style/scaladoc.html). + +## Связывание с API + +Scaladoc позволяет ссылаться на документацию по API с помощью ссылок в стиле Wiki. +Связать с `scala.collection.immutable.List` так же просто, как указать `[[scala.collection.immutable.List]]`. +Для получения дополнительной информации о точном синтаксисе см. [ссылки в документации](/ru/scala3/guides/scaladoc/linking.html#определение-ссылок). diff --git a/_ru/scala3/guides/scaladoc/index.md b/_ru/scala3/guides/scaladoc/index.md new file mode 100644 index 0000000000..048272f371 --- /dev/null +++ b/_ru/scala3/guides/scaladoc/index.md @@ -0,0 +1,13 @@ +--- +layout: multipage-overview +title: Scaladoc +partof: scala3-scaladoc +language: ru +num: 1 +next-page: docstrings +--- + +![scaladoc logo]({{ site.baseurl }}/resources/images/scala3/scaladoc/logo.svg) + +Scaladoc — это инструмент для создания API документации ваших проектов Scala 3. +Он предоставляет функциональность, аналогичную `javadoc`, а также `jekyll` или `docusaurus`. diff --git a/_ru/scala3/guides/scaladoc/linking.md b/_ru/scala3/guides/scaladoc/linking.md new file mode 100644 index 0000000000..fd0670ba65 --- /dev/null +++ b/_ru/scala3/guides/scaladoc/linking.md @@ -0,0 +1,94 @@ +--- +layout: multipage-overview +title: Ссылки в документации +partof: scala3-scaladoc +language: ru +num: 3 +previous-page: docstrings +next-page: static-site +--- + +Основная функция Scaladoc — создание API документации из комментариев к коду. + +По умолчанию комментарии к коду понимаются как Markdown, хотя мы также поддерживаем старый Scaladoc синтаксис +[Wiki](https://docs.scala-lang.org/style/scaladoc.html). + +## Синтаксис + +### Определение ссылок + +Наш синтаксис определения ссылки очень близок к синтаксису Scaladoc, хотя мы внесли некоторые улучшения. + +#### Основной синтаксис + +Определение ссылки выглядит следующим образом: `[[scala.collection.immutable.List]]`. + +Другими словами, определение ссылки представляет собой последовательность идентификаторов, разделенных знаком `.`. +Идентификаторы также могут быть разделены с помощью `#`. + +По умолчанию идентификатор `id` ссылается на первую (в исходном порядке) сущность с именем `id`. +Идентификатор может заканчиваться на `$`, что заставляет его ссылаться на значение (объект, значение, given); +идентификатор также может заканчиваться на `!`, что заставляет его ссылаться на тип (класс, псевдоним типа, член типа). + +Ссылки рассчитываются относительно текущего местоположения в источнике. +То есть при документировании класса ссылки относятся к сущности, включающей класс (пакет, класс, объект); +то же самое относится к документированию определений. + +Специальные символы в ссылках могут быть экранированы обратной косой чертой, что вместо этого делает их частью идентификаторов. +Например, `` [[scala.collection.immutable\.List]] `` ссылается на класс `` `immutable.List` ``, указанный в package `scala.collection`. + +#### Новый синтаксис + +Определение ссылок Scaladoc было расширено, чтобы сделать их более удобными для записи и чтения в исходном коде. +Также целью было сблизить связь и синтаксис Scala. Новые функции: + +1. `package` может использоваться в качестве префикса для ссылки на прилагаемый пакет. + Пример: + ``` + package utils + class C { + def foo = "foo". + } + /** See also [[package.C]]. */ + class D { + def bar = "bar". + } + ``` + Ключевое слово `package` помогает сделать ссылки на прилагаемый пакет короче + и немного более устойчивым к рефакторингу имен. +1. `this` может использоваться в качестве префикса для ссылки на прилагаемый классоподобный пример: + ``` + class C { + def foo = "foo" + /** This is not [[this.foo]], this is bar. */ + def bar = "bar" + } + ``` + Использование здесь ключевого слова помогает сделать ссылки более привычными, + а также помогает ссылкам "пережить" изменения имени класса. +1. Обратные кавычки могут использоваться для экранирования идентификаторов. + Пример: + ``` + def `([.abusive.])` = ??? + /** TODO: Figure out what [[`([.abusive.])`]] is. */ + def foo = `([.abusive.])` + ``` + Ранее (в версиях 2.x) для ссылки на такие идентификаторы в Scaladoc требовалось экранирование обратной косой чертой. + Теперь (в версиях 3.x) Scaladoc позволяет использовать знакомую обратную кавычку Scala. + +#### Зачем сохранять синтаксис Wiki для ссылок? + +Есть несколько причин, по которым синтаксис Wiki сохранен для ссылок на документацию +вместо повторного использования синтаксиса Markdown. Это: + +1. Безымянные ссылки в Markdown уродливы: `[](definition)` против `[[definition]]` + Безусловно, большинство ссылок в документации безымянные. Должно быть очевидно, как их писать. +2. Поиск локального члена конфликтует с фрагментами URL: `[](#field)` против `[[#field]]` +3. Разрешение перегрузки противоречит синтаксису MD: `[](meth(Int))` против `[[meth(Int)]]` +4. Теперь, когда есть парсер для синтаксиса ссылок, можно разрешить пробелы внутри + (в Scaladoc нужно было экранировать их косой чертой), но это не распознается как ссылка в Markdown: + `[](meth(Int, Float))` против `[[meth(Int, Float)]]` + +Ни одна из этих причин не делает полностью невозможным использование стандартного синтаксиса ссылок Markdown, +но они делают его гораздо более неуклюжим и уродливым, чем нужно. +Кроме того, синтаксис ссылок Markdown даже не сохраняет никаких символов. diff --git a/_ru/scala3/guides/scaladoc/search-engine.md b/_ru/scala3/guides/scaladoc/search-engine.md new file mode 100644 index 0000000000..9ef88e0630 --- /dev/null +++ b/_ru/scala3/guides/scaladoc/search-engine.md @@ -0,0 +1,102 @@ +--- +layout: multipage-overview +title: Поиск по типу +partof: scala3-scaladoc +language: ru +num: 7 +previous-page: site-versioning +next-page: snippet-compiler +--- + +Поиск функций по их символическим именам может занять много времени. +Именно поэтому новый scaladoc позволяет искать методы и поля по их типам. + +Рассмотрим следующее определение метода расширения: +``` +extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ... +``` +Вместо поиска `span` также можно искать по `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`. + +Чтобы использовать эту функцию, введите сигнатуру искомого элемента в строке поиска scaladoc. +Вот как это работает: + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif) + +Эта функция предоставляется поисковой системой [Inkuire](https://github.com/VirtusLab/Inkuire), которая работает для Scala 3 и Kotlin. +Чтобы быть в курсе развития этой функции, следите за репозиторием [Inkuire](https://github.com/VirtusLab/Inkuire). + +## Примеры запросов + +Некоторые примеры запросов с предполагаемыми результатами: +- `List[Int] => (Int => Long) => List[Long]` -> `map` +- `Seq[A] => (A => B) => Seq[B]` -> `map` +- `(A, B) => A` -> `_1` +- `Set[Long] => Long => Boolean` -> `contains` +- `Int => Long => Int` -> `const` +- `String => Int => Char` -> `apply` +- `(Int & Float) => (String | Double)` -> `toDouble`, `toString` +- `F[A] => Int` -> `length` + +## Синтаксис запроса + +Для того чтобы запрос панели поиска scaladoc выполнялся с использованием Inkuire вместо поисковой системы по умолчанию, +запрос должен содержать последовательность символов `=>`. + +Принятый ввод аналогичен сигнатуре каррированной функции в Scala 3. С некоторыми отличиями: +- AndTypes, OrTypes и Functions должны быть заключены в круглые скобки, например, `(Int & Any) => String` +- поля и методы без параметров можно найти, указав перед их типом `=>`, например, `=> Int` +- Можно использовать подстановочный знак `_`, чтобы указать, что необходимо сопоставить любой тип в данном месте, + например, `Long => Double => _` +- Типы в виде одной буквы, например `A`, или буквы с цифрой `X1`, автоматически считаются переменными типа. +- Другие переменные типа могут быть объявлены так же, как и в полиморфных функциях, + например `[AVariable, AlsoAVariable] => AVariable => AlsoAVariable => AVariable` + +### Работа с псевдонимами типов и приемниками методов + +Когда дело доходит до того, как код сопоставляется с записями InkuireDb, есть некоторые преобразования, +чтобы сделать движок более самостоятельным (хотя и открытым для предложений и изменений). +Во-первых, получатель (не владелец модуля) функции может рассматриваться как первый аргумент. +Также применяется автоматическое каррирование, чтобы результаты не зависели от списков аргументов. +При поиске совпадений `val` и `def` не различаются. + +Итак, по запросу `Num => Int => Int => Int` должны быть найдены следующие объявления: +``` +class Num(): + def a(i: Int, j: Int): Int + def b(i: Int)(j: Int): Int + def c(i: Int): (Int => Int) + val d: Int => Int => Int + val e: Int => Int => Int + val f: (Int, Int) => Int +end Num + +def g(i: Num, j: Int, k: Int): Int +extension (i: Num) def h(j: Int, k: Int): Int +def i(i: Num, j: Int)(k: Int): Int +extension (i: Num) def j(j: Int)(k: Int): Int +... +``` + +Когда дело доходит до псевдонимов типов, они дешугаризуются как в объявлении, так и в подписи запроса. +Это означает, что для объявлений: +``` +type Name = String + +def fromName(name: Name): String +def fromString(str: String): Name +``` +оба метода `fromName` и `fromString`, должны быть найдены по запросам `Name => Name`, `String => String`, `Name => String` и `String => Name`. + +## Как это работает + +Inkuire работает как рабочий JavaScript в браузере благодаря мощи [ScalaJS](https://www.scala-js.org/). + +Чтобы включить Inkuire при запуске scaladoc, добавьте флаг `-Ygenerate-inkuire`. +При добавлении этого флага создаются два файла: +- `inkuire-db.json` - это файл, содержащий все доступные для поиска объявления из текущего документированного проекта в формате, + читаемом поисковой системой Inkuire. +- `inkuire-config.json` - этот файл содержит расположение файлов базы данных, + которые должны быть доступны для поиска в документации текущего проекта. + По умолчанию он будет сгенерирован с расположением локального файла базы данных, + а также с подразумеваемыми по умолчанию расположениями файлов базы данных во внешних сопоставлениях + [`-external-mappings`](/ru/scala3/guides/scaladoc/settings.html#-external-mappings). diff --git a/_ru/scala3/guides/scaladoc/settings.md b/_ru/scala3/guides/scaladoc/settings.md new file mode 100644 index 0000000000..942e88342b --- /dev/null +++ b/_ru/scala3/guides/scaladoc/settings.md @@ -0,0 +1,218 @@ +--- +layout: multipage-overview +title: Настройки +partof: scala3-scaladoc +language: ru +num: 9 +previous-page: snippet-compiler +--- + +В этой главе перечислены параметры конфигурации, которые можно использовать при вызове scaladoc. +Некоторую информацию, показанную здесь, можно получить, вызвав scaladoc с флагом `-help`. + +## Изменения scaladoc по сравнению со Scala 2 + +Scaladoc был переписан с нуля, и некоторые функции оказались бесполезными в новом контексте. +Текущее состояние совместимости со старыми флагами scaladoc можно увидеть [здесь](https://github.com/scala/scala3/issues/11907). + +## Указание настроек + +Настройки scaladoc можно указывать в качестве аргументов командной строки, +например, `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. +При вызове из sbt, обновите значение `Compile / doc / scalacOptions` и `Compile / doc / target` соответственно, например + +``` +Compile / doc / target := file("output"), +Compile / doc / scalacOptions ++= Seq("-project", "my-project"), +``` + +## Обзор всех доступных настроек + +##### -project + +Название проекта. Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-title` + +##### -project-version + +Текущая версия проекта, которая отображается в верхнем левом углу. +Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-version` + +##### -project-logo + +Логотип проекта, который появляется в верхнем левом углу. +Для темной темы можно выделить отдельный логотип с суффиксом `_dark`. +Например, если есть логотип `mylogo.png`, то для темной темы предполагается `mylogo_dark.png`. +Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-logo` + +##### -project-footer + +Строковое сообщение, которое отображается в разделе нижнего колонтитула. +Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-footer` + +##### -comment-syntax + +Язык стилей, используемый для разбора комментариев. +В настоящее время поддерживается два синтаксиса: `markdown` или `wiki`. +Если настройка отсутствует, по умолчанию - `markdown`. + +##### -revision + +Редакция (ветвь или ссылка), используемая для создания проекта. +Полезно с исходными ссылками, чтобы они не всегда указывали на последний `main`, который может быть изменен. + +##### -source-links + +Ссылки на источники обеспечивают сопоставление между файлом в документации и репозиторием кода. + +Примеры исходных ссылок: +`-source-links:docs=github://scala/scala3/main#docs` + +Принимаемые форматы: + +`=` + +где `` является одним из следующих: + +- `github:///[/revision][#subpath]` + будет соответствовать https://github.com/$organization/$repository/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber], + если редакция не указана, тогда требуется указать редакцию в качестве аргумента для Scaladoc +- `gitlab:///` + будет соответствовать https://gitlab.com/$organization/$repository/-/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber], + если редакция не указана, тогда требуется, чтобы редакция была указана как аргумент в Scaladoc +- `` + +`` — это формат параметра `doc-source-url` из старого scaladoc. +ПРИМЕЧАНИЕ. Поддерживаются только шаблоны `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`, `€{FILE_PATH}` и `€{FILE_LINE}`. + +Шаблон может быть определен только подмножеством источников, определенных префиксом пути, представленным ``. +В этом случае пути, используемые в шаблонах, будут относительны к ``. + +##### -external-mappings + +Сопоставление регулярных выражений, соответствующих записям пути к классам, и внешней документации. + +Пример внешнего сопоставления: +`-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/` + +Отображение имеет вид `::[scaladoc3|scaladoc|javadoc]::`. +Можно указать несколько сопоставлений, разделенных запятыми, как показано в примере. + +##### -social-links + +Ссылки на социальные сети. Например: + +`-social-links:github::https://github.com/scala/scala3,discord::https://discord.com/invite/scala,twitter::https://x.com/scala_lang` + +Допустимые значения имеют вид: `[github|twitter|gitter|discord]::link`. +Scaladoc также поддерживает `custom::link::white_icon_name::black_icon_name`. +В этом случае иконки должны находиться в каталоге `images/`. + +##### -skip-by-id + +Идентификаторы пакетов или классов верхнего уровня, которые следует пропускать при создании документации. + +##### -skip-by-regex + +Регулярные выражения, соответствующие полным именам пакетов или классов верхнего уровня, +которые следует пропускать при создании документации. + +##### -doc-root-content + +Файл, из которого следует импортировать документацию корневого пакета. + +##### -author + +Добавление авторов в строку документации `@author Name Surname` по умолчанию не будет включено в сгенерированную html-документацию. +Если необходимо явно пометить классы авторами, scaladoc запускается с данным флагом. + +##### -groups + +Группировка похожих функций вместе (на основе аннотации `@group`) + +##### -private + +Показать все типы и члены. Если параметр не указан, показывать только `public` и `protected` типы и члены. + +##### -doc-canonical-base-url + +Базовый URL-адрес для использования в качестве префикса и добавления `canonical` URL-адресов на все страницы. +Канонический URL-адрес может использоваться поисковыми системами для выбора URL-адреса, +который вы хотите, чтобы люди видели в результатах поиска. +Если не установлено, канонические URL-адреса не генерируются. + +##### -siteroot + +Каталог, содержащий статические файлы, из которых создается документация. Каталог по умолчанию - `./docs` + +##### -no-link-warnings + +Подавить предупреждения для двусмысленных или невалидных ссылок. +Не влияет на предупреждения о некорректных ссылках ресурсов и т. д. + +##### -versions-dictionary-url + +URL-адрес, указывающий на документ JSON, содержащий словарь: `version label -> documentation location`. +Файл JSON имеет единственное поле `versions`, которое содержит словарь, +связывающий метки определенных версий документации с URL-адресами, указывающими на их `index.html`. +Полезно для библиотек, которые поддерживают разные версии документации. + +Пример JSON-файла: + +``` +{ + "versions": { + "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", + "Nightly": "https://dotty.epfl.ch/docs/index.html" + } +} +``` + +##### -snippet-compiler + +Аргументы компилятора фрагментов, позволяющие настроить проверку типа сниппета. + +Этот параметр принимает список аргументов в формате: +`args := arg{,args} arg := [path=]flag` +, где `path` - префикс пути к исходным файлам, в которых находятся сниппеты, +и `flag` - режим проверки типов. + +Если `path` отсутствует, аргумент будет использоваться по умолчанию для всех несопоставленных путей. + +Доступные флаги: + +- `compile` — включает проверку фрагментов. +- `nocompile` — отключает проверку сниппетов. +- `fail` — включает проверку фрагмента, утверждает, что сниппет не компилируется. + +Флаг `fail` удобен для фрагментов, которые показывают, +что какое-то действие в конечном итоге завершится ошибкой во время компиляции. + +Пример использования: + +`-snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile` + +Что значит: + +- все фрагменты в файлах в каталоге `my/path/nc` вообще не должны рассматриваться снипеттом +- все фрагменты в файлах в каталоге `my/path/f` не должны компилироваться во время компиляции +- все остальные фрагменты должны компилироваться успешно + +#### -scastie-configuration + +Определите дополнительную sbt конфигурацию для Scastie фрагментов кода. +Например, когда вы импортируете внешние библиотеки в свои фрагменты, +необходимо добавить соответствующие зависимости. + +``` +"-scastie-configuration", """libraryDependencies += "org.apache.commons" % "commons-lang3" % "3.12.0"""" +``` + +##### -Ysnippet-compiler-debug + +Установка этого параметра заставляет компилятор фрагментов печатать сниппет по мере его компиляции (после упаковки). + +##### -Ydocument-synthetic-types + +Включение в документацию страниц с документацией по встроенным типам (например, `Any`, `Nothing`). +Этот параметр полезен только для stdlib, поскольку scaladoc для Scala 3 использует файлы TASTy. +Все остальные пользователи не должны касаться этой настройки. diff --git a/_ru/scala3/guides/scaladoc/site-versioning.md b/_ru/scala3/guides/scaladoc/site-versioning.md new file mode 100644 index 0000000000..fac5266a7c --- /dev/null +++ b/_ru/scala3/guides/scaladoc/site-versioning.md @@ -0,0 +1,51 @@ +--- +layout: multipage-overview +title: Версионирование сайта +partof: scala3-scaladoc +language: ru +num: 6 +previous-page: blog +next-page: search-engine +--- + +Scaladoc предоставляет удобный способ переключения между различными версиями документации. +Эта функция полезна, когда желательно оставить старые версии документации пользователям, +которые ещё не перешли на новую версию библиотеки. + +### Как это настроить + +Эта функция была разработана для легкой масштабируемости без необходимости повторного создания всех scaladocs +после добавления новой версии. Для этого вводится новая настройка: `-versions-dictionary-url`. +Его аргумент должен быть URL-адресом документа JSON, содержащего информацию о расположении конкретных версий. +Файл JSON должен содержать свойство `versions` со словарём, +связывающий метки определенных версий документации с URL-адресами, указывающими на их `index.html`. + +Пример JSON-файла: +``` +{ + "versions": { + "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html", + "Nightly": "https://dotty.epfl.ch/docs/index.html" + } +} +``` + +Такие документы необходимо указывать для каждой из версий, однако позже это дает больше гибкости. +Если необходимо добавить версию документов API рядом с предыдущими 5 версиями, которые уже опубликованы, +нужно только загрузить новые документы на веб-сервер и добавить новую запись в файл JSON. +Все версии сайта теперь узнают о новой версии. + +Важно отметить, что существует только один файл JSON, чтобы избежать избыточности, +и каждый scaladoc должен заранее настроить свой URL-адрес, например, в sbt: + +``` +doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/versions.json") +``` + + +### Как это выглядит с точки зрения пользователя + +Предоставление файла JSON через `-versions-dictionary-url` позволяет scaladoc связывать версии. +Также удобно иметь возможность изменить метку ревизии в выпадающем меню. Все изменится автоматически. + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/nightly.gif) diff --git a/_ru/scala3/guides/scaladoc/snippet-compiler.md b/_ru/scala3/guides/scaladoc/snippet-compiler.md new file mode 100644 index 0000000000..adb2c0932c --- /dev/null +++ b/_ru/scala3/guides/scaladoc/snippet-compiler.md @@ -0,0 +1,261 @@ +--- +layout: multipage-overview +title: Проверка фрагмента +partof: scala3-scaladoc +language: ru +num: 8 +previous-page: search-engine +next-page: settings +--- + +Основная функциональность документации — помочь пользователям понять и правильно использовать проект. +Иногда часть проекта нуждается в нескольких словах, чтобы показать ее использование, +но бывают моменты, когда описания недостаточно, и нет ничего лучше, чем подробный пример. + +Удобный способ предоставления примеров в документации — создание фрагментов кода, +представляющих использование заданной функциональности. Проблема фрагментов кода в том, +что одновременно с разработкой проекта их нужно обновлять. +Иногда изменения в одной части проекта могут нарушить работу примеров в других частях. +Количество фрагментов и количество времени, прошедшего с момента их написания, не позволяет запомнить каждое место, +где нужно их исправить. Через какое-то время наступает понимание, что документация — полный бардак +и нужно пройтись по всем примерам и переписать их. + +Многие проекты Scala 2 используют markdown документацию с проверкой типов с помощью [tut](https://tpolecat.github.io/tut/) +или [mdoc](https://scalameta.org/mdoc/). Почти все хотя бы слышали об этих инструментах. +Поскольку они оказались очень полезными и сообщество Scala их успешно приняло, +планируется включить функции tut и mdoc в компилятор, чтобы он был готов к включению в Scaladoc. + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-compiler3.png) + +## Начало работы + +По умолчанию проверка фрагментов отключена. +Её можно включить, добавив в Scaladoc следующий аргумент: + +`-snippet-compiler:compile` + +Например, в sbt конфигурация выглядит так: + +```scala +Compile / doc / scalacOptions ++= Seq("-snippet-compiler:compile") +``` + +Эта опция включает компилятор фрагментов для всех scala фрагментов в проектной документации и распознает все фрагменты внутри ``` блоков scala. +В настоящее время проверка фрагментов работает как в строках документации, написанных в Markdown, так и на статических сайтах. +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-compiler4.png) + +Для нового проекта этой конфигурации должно хватить. +Однако, если вы переносите существующий проект, можно отключить компиляцию для некоторых фрагментов, +которые в настоящее время не могут быть обновлены. + +Для этого добавьте `nocompile` флаг прямо в scala фрагмент: + +```` +```scala sc:nocompile +// under the hood `map` is transformed into +List(1).map( _ + 1)() +``` +```` + +Однако иногда сбой компиляции является преднамеренным поведением, например, для демонстрации ошибки. +В этом случае выставляется флаг `fail`, который представляет одну из функций: [Assert compilation errors](#assert-compilation-errors). + +```` +```scala sc:fail +List(1,2,3).toMap +``` +```` + +Более подробное объяснение и более сложные настройки, такие как настройки флагов на основе пути, +см. в разделе ["Расширенная конфигурация"](#расширенная-конфигурация). + +## Обзор функций + +### Assert compilation errors + +Scala — это язык программирования со статической типизацией. +Иногда в документации должны упоминаться случаи, когда код не должен компилироваться, +или авторы хотят предоставить способы восстановления после определенных ошибок компиляции. + +Например, этот код: + +```scala +List(1,2,3).toMap +``` + +приводит к результату: + +```nohighlight + +At 18:21: + List(1,2,3).toMap +Error: Cannot prove that Int <:< (K, V) + +where: K is a type variable with constraint + V is a type variable with constraint +. +``` + +Примеры, представляющие код, который дает сбой во время компиляции, могут быть очень важными. +Например, можно показать, как библиотека защищена от неправильного кода. +Другой вариант использования — представить распространенные ошибки и способы их решения. +Принимая во внимание эти варианты использования, предоставляется функция проверки того, компилируются ли отмеченные фрагменты кода. + +Для фрагментов кода, которые намеренно не компилируются, например следующего, добавьте флаг `fail` во фрагмент кода: + +```` +```scala sc:fail +List(1,2,3).toMap +``` +```` +Проверка фрагмента проходит успешно и показывает ожидаемые ошибки компиляции в документации. +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/assert-compilation-errors.gif) + +Для фрагмента, который компилируется без ошибок: +```` +```scala sc:fail +List((1,2), (2,3)).toMap +``` +```` +результирующий вывод выглядит следующим образом: +```nohighlight + +In static site (./docs/docs/index.md): +Error: Snippet should not compile but compiled succesfully +``` + + +### Контекст + +В Scaladoc внедрён механизм переноса, предоставляющий контекст для каждого фрагмента. +Эта предварительная обработка выполняется автоматически для всех фрагментов в строках документации. + +Например, предположим, что необходимо задокументировать метод `slice` в файле `collection.List` для того, +чтобы объяснить, как он работает, сравнив его с комбинацией методов `drop` и `take`, используя такой фрагмент кода: +```scala +slice(2, 5) == drop(2).take(3) +``` +Показ этого примера — одна из первых вещей, которые приходят на ум, но он не скомпилируется без функции контекста. + +Помимо основной цели, это уменьшает шаблон фрагмента, потому что не нужно импортировать элементы одного и того же пакета +и создавать экземпляры документированного класса. + +Фрагмент кода после предварительной обработки выглядит так: +```scala +package scala.collection +trait Snippet[A] { self: List[A] => + slice(2,5) == drop(2).take(3) +} +``` + +### Скрытие кода + +Несмотря на наличие контекстной функции, описанной выше, иногда автору необходимо предоставить больше элементов +для области действия. Однако, с одной стороны, большой блок импортов и инициализаций необходимых классов +может привести к потере читабельности. Но с другой стороны, хотелось бы иметь возможность видеть весь код. +Для второго случая введен специальный синтаксис для фрагментов, +который скрывает определенные фрагменты `import` кода — операторы, например, — но также позволяет +расширить этот код в документации одним щелчком мыши. + +Пример: + +```scala +//{ +import scala.collection.immutable.List +//} +val intList: List[Int] = List(1, 2, 3) +``` + +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/hiding-code.gif) + +### Включенные фрагменты + +При написании фрагментов кода часто требуется механизм повторного использования кода из одного фрагмента в другом. +Например, взгляните на следующий фрагмент документации: +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/documentation-snippet.png) + +Чтобы успешно скомпилировать последний фрагмент, нужно иметь ранее объявленные определения в области видимости. +Для этого сценария — и, возможно, для многих других — добавлена новая функция: включение фрагмента. +Она позволяет повторно использовать код из одного фрагмента в другом, что снижает избыточность и повышает удобство сопровождения. + +Чтобы настроить это, добавьте аргумент `sc-name` к фрагменту, который необходимо включить в более поздний блок кода: +```` ```scala sc-name: ```` + +, где `snippet-name` должен быть уникальным в пределах файла и не может содержать пробелы и запятые. + +Затем в более позднем блоке кода в документации используйте аргумент `sc-compile-with` в scala фрагменте, +который должен “включать” предыдущий блок кода: +```` ```scala sc-compile-with:(,)+ ```` + +, где `snippet-name` - имя фрагмента, который должен быть включен. + +После настройки этой функции в примере код выглядит так: +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/documentation-snippet2.png) + +и вывод выглядит так: +![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-includes.png) + +Можно указать более одного включения. Обратите внимание, что порядок, в котором они указаны, определяет порядок включения. + +**Замечание**: можно включать только фрагменты, определенные над целевым фрагментом. + +## Расширенная конфигурация + +Часто включение проверки фрагментов для _всех_ фрагментов не является желаемым уровнем контроля, +поскольку варианты использования могут быть более сложными. Для таких ситуаций подготовлен инструмент, +чтобы пользователи могли настроить его под свои нужды. + +### Доступные флаги + +Чтобы обеспечить больший контроль, компилятор фрагмента предоставляет три флага, которые позволяют изменить его поведение: +- `compile` - включает проверку фрагментов +- `nocompile` - отключает проверку фрагментов +- `fail` - включает проверку фрагментов с подтверждением ошибки компиляции + +### Настройки на основе пути + +Для большей гибкости вместо установки одного флага для управления всеми фрагментами кода в проекте +его можно установить только для определенного пути, добавив префикс `=` перед флагом. Например: + +`-snippet-compiler:docs=compile` - устанавливает флаг `compile` для фрагментов в `docs`. + +Если `docs` - это каталог, флаг устанавливается для всех файлов внутри `docs`. + +Кроме того, `-snippet-compiler` может управляться более чем одним параметром, при этом параметры разделяются запятыми. +Например: +``` +-snippet-compiler:docs=compile,library/src=compile,library/src/scala/quoted=nocompile,library/src/scala/compiletime=fail +``` +Флаги выбираются по самому длинному совпадению префикса, поэтому можно определить общую настройку, +а затем изменить это поведение по умолчанию для более конкретных путей. +``` +-snippet-compiler:compile,library/src/scala/quoted=nocompile,library/src/scala/compiletime=fail +``` +Флаг без префикса пути, такой как флаг `compile` в этом примере, считается значением по умолчанию. + +### Переопределение прямо во фрагменте + +Аргументы CLI — хороший механизм для установки флагов для определенных файлов. +Однако этот подход нельзя использовать для настройки определенных фрагментов. +Допустим, необходимо написать один фрагмент кода, который должен потерпеть неудачу, +и другие фрагменты, которые должны скомпилироваться. +Эти аргументы находятся в информационной части блока кода: + +```` +```scala +// snippet +``` +```` + +Например, чтобы настроить проверку для определенного фрагмента, добавьте следующий аргумент в его информационную часть фрагмента, +где `flag` - один из доступных флагов, перечисленных выше (например, `compile`, `nocompile` или `fail`): + +`sc:` + +В качестве конкретного примера этот код показывает, как использовать флаг `fail` в отдельном фрагменте: + +```` +```scala sc:fail +val itShouldFail: Int = List(1.1, 2, 3).head +``` +```` diff --git a/_ru/scala3/guides/scaladoc/static-site.md b/_ru/scala3/guides/scaladoc/static-site.md new file mode 100644 index 0000000000..2249f88ffe --- /dev/null +++ b/_ru/scala3/guides/scaladoc/static-site.md @@ -0,0 +1,296 @@ +--- +layout: multipage-overview +title: Статическая документация +partof: scala3-scaladoc +language: ru +num: 4 +previous-page: linking +next-page: blog +--- + +Scaladoc умеет генерировать статические сайты, известные по [Jekyll](http://jekyllrb.com/) или [Docusaurus](https://docusaurus.io/). +Наличие комбинированного инструмента позволяет обеспечить взаимодействие между статической документацией +и API, что позволяет им естественным образом сочетаться. + +Создать сайт так же просто, как и в Jekyll. Корень сайта содержит макет сайта, +и все файлы, размещенные там, будут либо считаться статическими, либо обрабатываться для расширения шаблона. + +Файлы, которые рассматриваются для расширения шаблона, должны заканчиваться на `*.{html,md}` +и в дальнейшем будут называться "файлами шаблонов" или "шаблонами". + +Простой сайт "Hello World" может выглядеть примерно так: + +``` +. +└── / + └── _docs/ + ├── index.html + └── getting-started.html +``` + +Что даст сайт со следующими файлами в сгенерированной документации: + +``` +index.html +getting-started.html +``` + +Scaladoc может преобразовывать как файлы, так и каталоги (чтобы организовать документацию в древовидную структуру). +По умолчанию каталоги имеют заголовок, основанный на имени файла, с пустым содержимым. +Можно предоставить индексные страницы для каждого раздела, создав `index.html` или `index.md` (но не одновременно) в выделенном каталоге. + +Имейте в виду, что для локального просмотра вашего сайта со всеми его функциями, такими как поиск или фрагменты, +требуется локальный сервер. Например, если ваш выходной каталог - `output`, +вы можете использовать python сервер для просмотра всего, выполнив следующие действия и открыв `localhost:8080`: + +```sh +cd output +python3 -m http.server 8080 +``` + +## Характеристики + +Scaladoc использует механизм шаблонов [Liquid](https://shopify.github.io/liquid/) +и предоставляет несколько настраиваемых фильтров и тегов, характерных для документации Scala. + +В Scaladoc все шаблоны могут содержать вступительную часть YAML. +Передняя часть анализируется и помещается в переменную `page`, доступную в шаблонах через Liquid. + +Пример вступительной статьи: + +``` +--- +title: My custom title +--- +``` + +Scaladoc использует некоторые предопределенные свойства для управления аспектами страницы. + +Предустановленные свойства: + +- **title** - обеспечивает заголовок страницы, который будет использоваться в навигации и метаданных HTML. +- **extraCss** - дополнительные файлы `.css`, которые будут включены в эту страницу. + Пути должны указываться относительно корня документации. **Этот параметр не экспортируется в механизм шаблонов.** +- **extraJs** - дополнительные файлы `.js`, которые будут включены в эту страницу. + Пути должны указываться относительно корня документации. **Этот параметр не экспортируется в механизм шаблонов.** +- **hasFrame** - если установлено значение `false`, страница не будет включать макет по умолчанию (навигацию, breadcrumbs и т.д.), + а только токен-оболочку HTML для предоставления метаданных и ресурсов (файлы js и css). **Этот параметр не экспортируется в механизм шаблонов.** +- **layout** - предопределенный макет для использования, см. ниже. **Этот параметр не экспортируется в механизм шаблонов.** + +Свойства перенаправления: + +В дополнение к предустановленным свойствам, Scaladoc также поддерживает свойства перенаправления, +которые позволяют вам перенаправлять с одной страницы на другую. +Это может быть полезно, когда вы перемещаете страницу на новое место, +но хотите, чтобы старый URL-адрес работал. + +- **redirectFrom** - указывает на URL-адрес, с которого вы хотите выполнить перенаправление. + Используя свойство `redirectFrom`, Scaladoc создает пустую страницу по этому URL-адресу, + который включает браузерное перенаправление на текущую страницу. + +Пример: + +``` +--- +redirectFrom: /absolute/path/to/old/url.html +--- +``` + +В приведенном выше примере, +если вы перемещаете страницу из `/absolute/path/to/old/url.html` на новое место, +то вы можете использовать `redirectFrom`, чтобы убедиться, +что старый URL-адрес по-прежнему перенаправляет на новое место. + +Обратите внимание, что свойство `redirectFrom` было вдохновлено плагином Jekyll под названием +[`jekyll-redirect-from`](https://github.com/jekyll/jekyll-redirect-from). + +- **redirectTo** — указывает URL-адрес, на который вы хотите перенаправить с текущей страницы. + Это свойство полезно, когда вы хотите перенаправить на внешнюю страницу + или когда нельзя использовать `redirectFrom`. + +Пример: + +``` +--- +redirectTo: https://docs.scala-lang.org/ +--- +``` + +В приведенном выше примере страница будет перенаправлена на https://docs.scala-lang.org/. + +## Использование существующих шаблонов и макетов + +Чтобы выполнить расширение шаблона, Dottydoc просматривает поле `layout` во вступительной части. +Вот простой пример системы шаблонов в действии `index.html`: + +```html +--- +layout: main +--- + +

            Hello world!

            +``` + +С таким простым основным шаблоном, как этот: + +{% raw %} + +```html + + + Hello, world! + + + {{ content }} + + +``` + +`{{ content }}` будет заменен на `

            Hello world!

            ` в файле `index.html`. +{% endraw %} + +Макеты должны быть размещены в каталоге `_layouts` в корне сайта: + +``` +├── _layouts +│ └── main.html +└── _docs + ├── getting-started.md + └── index.html +``` + +## Ресурсы + +Чтобы рендерить ассеты вместе со статическим сайтом, их нужно поместить в директорию `_assets` в корне сайта: + +``` +├── _assets +│ └── images +│ └── myimage.png +└── _docs + └── getting-started.md +``` + +Чтобы сослаться на ресурс на странице, необходимо создать ссылку относительно каталога `_assets`. + +``` +Take a look at the following image: [My image](images/myimage.png) +``` + +## Боковая панель + +По умолчанию Scaladoc отображает структуру каталогов из каталога `_docs` на визуализируемом сайте. +Существует также возможность переопределить его, предоставив файл `sidebar.yml` в корневом каталоге сайта. +Конфигурационный файл YAML описывает структуру отображаемого статического сайта и оглавление: + +```yaml +index: index.html +subsection: + - title: Usage + index: usage/index.html + directory: usage + subsection: + - title: Dottydoc + page: usage/dottydoc.html + hidden: false + - title: sbt-projects + page: usage/sbt-projects.html + hidden: false +``` + +Корневой элемент должен быть `subsection`. +Вложенные подразделы приведут к древовидной структуре навигации. + +Свойства `subsection`: + +- `title` - Необязательная строка - заголовок подраздела по умолчанию. + Вступительные заголовки имеют более высокий приоритет. +- `index` - Необязательная строка - Путь к индексной странице подраздела. Путь указан относительно каталога `_docs`. +- `directory` - Необязательная строка - Имя каталога, в котором будет находиться подраздел сгенерированного сайта. + По умолчанию именем каталога является имя подраздела, преобразованное в kebab case. +- `subsection` - Массив `subsection` или `page`. + +Либо `index`, либо `subsection` должны быть определены. Подраздел, определенный с `index` и без `subsection`, +будет содержать страницы и каталоги, загружаемые рекурсивно из каталога индексной страницы. + +Свойства `page`: + +- `title` - Необязательная строка - заголовок страницы по умолчанию. Вступительные заголовки имеют более высокий приоритет. +- `page` - Строка - Путь к странице относительно каталога `_docs`. +- `hidden` - Необязательное логическое значение. Флаг, указывающий, должна ли страница отображаться на боковой панели навигации. + По умолчанию установлено значение `false`. + +**Заметка**: Все пути в файле конфигурации YAML относятся к `/_docs`. + +## Иерархия title + +Если заголовок указан несколько раз, приоритет будет следующим (от высшего к низшему приоритету): + +#### Страница + +1. `title` из `front-matter` файла markdown/html +2. `title` свойство из `sidebar.yml` +3. имя файла + +#### Подраздел + +1. `title` из `front-matter` индексного файла markdown/html +2. `title` свойство из `sidebar.yml` +3. имя файла + +Обратите внимание, что если пропустить `index` файл в древовидной структуре или не указать `title` во вступительной части, +ему будет присвоено общее имя `index`. То же самое относится к использованию `sidebar.yml`, +но не указанию ни `title`, ни `index`, а только подраздела. Снова появится общее имя `index`. + +## Блог + +Функция блога описана в [отдельном документе](/ru/scala3/guides/scaladoc/blog.html). + +## Расширенная конфигурация + +### Полная структура корня сайта + +``` +. +└── / + ├── _layouts/ + │ └── ... + ├── _docs/ + │ └── ... + ├── _blog/ + │ ├── index.md + │ └── _posts/ + │ └── ... + └── _assets/ + ├── js/ + │ └── ... + ├── img/ + │ └── ... + └── ... +``` + +В результате получается статический сайт, содержащий документы, а также блог. +Он также содержит пользовательские макеты и ассеты. +Структура визуализируемой документации может быть основана на файловой системе, но также может быть переопределена конфигурацией YAML. + +### Структура каталогов сопоставления + +Используя файл конфигурации YAML, можно определить, как структура исходного каталога должна быть преобразована в структуру выходного каталога. + +Взглянем на следующее определение подраздела: + +```yaml +- title: Some other subsection + index: abc/index.html + directory: custom-directory + subsection: + - page: abc2/page1.md + - page: foo/page2.md +``` + +В этом подразделе показана возможность конфигурации YAML отображать структуру каталогов. +Несмотря на то, что индексная страница и все определенные дочерние элементы находятся в разных каталогах, +они будут рендериться в `custom-directory`. +Исходная страница `abc/index.html` будет генерировать страницу `custom-directory/index.html`, +исходная страница `abc2/page1.md` - `custom-directory/page1.html`, +а исходная страница `foo/page2.md` - `custom-directory/page2.html`. diff --git a/_ru/scala3/new-in-scala3.md b/_ru/scala3/new-in-scala3.md new file mode 100644 index 0000000000..d4d4ce0773 --- /dev/null +++ b/_ru/scala3/new-in-scala3.md @@ -0,0 +1,184 @@ +--- +layout: singlepage-overview +title: Новое в Scala 3 +partof: scala3-scaladoc +scala3: true +language: ru +--- + +Захватывающая новая версия Scala 3 содержит множество новых функций и улучшений. +Здесь мы представляем вам краткий обзор наиболее важных изменений. +Если вы хотите копнуть глубже, то в вашем распоряжении несколько ссылок: + +- [Книга Scala 3]({% link _overviews/scala3-book/introduction.md %}) предназначена для разработчиков, только знакомящихся с языком Scala. +- [Обзор синтаксиса][syntax-summary] содержит формальное описание нового синтаксиса. +- [Справочник по языку][reference] дает подробное описание изменений Scala 3 по сравнению со Scala 2. +- [Руководство по миграции][migration] содержит всю информацию, необходимую для перехода со Scala 2 на Scala 3. +- [Scala 3 Contributing Guide][contribution] более подробно рассказывает о компиляторе, включая руководство по исправлению проблем. + +## Что нового Scala 3 +Scala 3 — это полная переработка языка Scala. +По сути, многие аспекты системы типов были изменены, чтобы сделать их более последовательными. +Хотя эта версия также приносит интересные новые функции (например, типы объединения), +в первую очередь это означает, что система типов становится (даже) малозаметнее на вашем пути, +и, например, [вывод типов][type-inference] с перегрузкой значительно улучшаются. + +### Новое и яркое: синтаксис +Помимо многих (незначительных) чисток, синтаксис Scala 3 предлагает следующие улучшения: + +- Новый "тихий" синтаксис для структур управления, таких как `if`, `while` и `for` ([новый синтаксис управления][syntax-control]) +- Ключевое слово `new` теперь является необязательным (_например_ [для создания экземпляров][creator]) +- [Опциональные фигурные скобки][syntax-indentation] поддерживающие стиль программирования, не отвлекающий внимание и чувствительный к отступам +- Изменение [подстановочных знаков типа][syntax-wildcard] с `_` на `?`. +- Имплициты (и их синтаксис) были [значительно переработаны][implicits]. + +### Последовательное: контекстуальные абстракции +Одной из основных концепций Scala было (и до некоторой степени до сих пор является) +предоставление пользователям небольшого набора мощных функций, +которые можно комбинировать для достижения большей (а иногда даже непредусмотренной) выразительности. +Например, функциональность _имплицитов_ использовалась для моделирования контекстной абстракции, +для выражения вычислений на уровне типов, моделирования классов типов, выполнения неявных преобразований, +кодирования методов расширения и многого другого. +Извлекая уроки из этих вариантов использования, Scala 3 использует несколько иной подход +и фокусируется на **намерении**, а не на **механизме**. +Вместо того чтобы предлагать одну очень мощную функцию, +Scala 3 предлагает несколько специализированных языковых функций, +позволяющих программистам напрямую выражать свои намерения: + +- **Абстрагирование контекстной информации**. [Using предложения][contextual-using] позволяют программистам абстрагироваться от информации, + которая доступна в контексте вызова и должна передаваться неявно. + В качестве улучшения по сравнению с имплицитами в Scala 2 предложения _using_ могут указываться по типу, + освобождая сигнатуры функций от имен переменных, если на них не ссылаются явно. + +- **Предоставление экземпляров классов типов**. [Экземпляры given][contextual-givens] позволяют программистам определять + каноническое значение определенного типа. Это делает программирование с классами типов более простым без распространения деталей реализации. + +- **Расширение классов задним числом**. В Scala 2 методы расширения должны были быть закодированы с использованием + неявных преобразований или неявных классов. Напротив, в Scala 3 [методы расширения][contextual-extension] + теперь встроены непосредственно в язык, что приводит к более качественным сообщениям об ошибках и улучшенному выводу типов. + +- **Просмотр одного типа как другого**. Неявные преобразования между типами были [переработаны][contextual-conversions] с нуля как экземпляры класса типов `Conversion`. + +- **Высокоуровневые контекстные абстракции**. _Совершенно новая_ особенность [контекстных функций][contextual-functions] делает контекстные абстракции функциями первого класса. + Они являются важным инструментом для авторов библиотек и позволяют кратко выражать предметно-ориентированные языки. + +- **Полезная обратная связь от компилятора**. Если компилятор не может разрешить неявный параметр, + теперь он предоставляет [предложения по импорту](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html), которые могут решить проблему. + +### Говори, что имеешь в виду: улучшения системы типов +Помимо значительно улучшенного вывода типов, система типов Scala 3 также предлагает множество новых функций, +предоставляя вам мощные инструменты для статического выражения инвариантов в типах: + +- **Перечисления**. [Enums][enums] были переработаны, чтобы хорошо сочетаться с case-классами + и формировать новый стандарт для выражения [алгебраических типов данных][enums-adts]. + +- **Непрозрачные типы**. Скройте детали реализации за [непрозрачными псевдонимами типов][types-opaque], не платя за это производительностью! + Непрозрачные типы заменяют классы значений и позволяют установить барьер абстракции, не вызывая дополнительных накладных расходов на упаковку. + +- **Типы пересечения и объединения**. Основание системы типов на новом фундаменте привело к введению новых функций системы типов: + экземпляры [типов-пересечений][types-intersection], например `A & B`, являются экземплярами обоих типов `A` и `B`. + Экземпляры [типов объединения][types-union], например `A | B`, являются экземплярами либо `A`, либо `B`. + Обе конструкции позволяют программистам гибко выражать ограничения типов вне иерархии наследования. + +- **Зависимые типы функций**. Scala 2 уже позволяла возвращаемым типам зависеть от (значения) аргументов. + В Scala 3 теперь можно абстрагироваться от этого шаблона и выразить [зависимые типы функций][types-dependent]. + В типе `type F = (e: Entry) => e.Key` тип результата зависит от аргумента! + +- **Полиморфные типы функций**. Как и в случае с зависимыми типами функций, Scala 2 поддерживала методы, + допускающие параметры типа, но не позволяла программистам абстрагироваться от этих методов. + В Scala 3 [полиморфные типы функций][types-polymorphic], например, `[A] => List[A] => List[A]` + могут абстрагироваться от функций, которые принимают аргументы типа в дополнение к своим аргументам значения. + +- **Лямбда-типы**. То, что нужно было выразить с помощью [плагина компилятора](https://github.com/typelevel/kind-projector) в Scala 2, + теперь является функцией первого класса в Scala 3: лямбда-выражения типов — это функции уровня типа, + которые можно передавать как аргументы (более высокого типа), не требуя определения вспомогательного типа. + +- **Сопоставление типов**. Вместо кодирования вычислений на уровне типов с использованием неявного разрешения, + Scala 3 предлагает прямую поддержку [сопоставления типов][types-match]. + Интеграция вычислений на уровне типов в средство проверки типов позволяет улучшить сообщения об ошибках + и устраняет необходимость в сложных кодировках. + + +### Переосмысление: объектно-ориентированное программирование +Scala всегда была на границе между функциональным программированием и объектно-ориентированным программированием, +а Scala 3 расширяет границы в обоих направлениях! +Вышеупомянутые изменения системы типов и редизайн контекстных абстракций делают _функциональное программирование_ проще, чем раньше. +В то же время следующие новые функции позволяют создавать хорошо структурированные _объектно-ориентированные проекты_ +и поддерживают best practices. + +- **Передача параметров**. Трейты становятся ближе к классам и теперь также могут принимать [параметры][oo-trait-parameters], + что делает их еще более мощным средством модульной декомпозиции программного обеспечения. +- **Планирование расширения**. Наследование классов, которые не предназначены для расширения, + является давней проблемой объектно-ориентированного проектирования. + Чтобы решить эту проблему, [открытые классы][oo-open] требуют, чтобы разработчики библиотек _явно_ помечали классы как открытые. +- **Скрытие деталей реализации**. Вспомогательные трейты, которые реализуют поведение, иногда не должны быть частью вывода типов. + В Scala 3 эти трейты могут быть помечены как [прозрачные][oo-transparent], скрывающие наследование от пользователя (в выводимых типах). +- **Композиция над наследованием**. Эта фраза часто цитируется, но утомительна для реализации. + Не так обстоит дело с [export предложениями][oo-export] в Scala 3 : симметричные по отношению к импорту, + предложения export позволяют пользователю определять псевдонимы для выбранных членов объекта. +- **Больше никаких NullPointerException (экспериментально)**. Scala 3 безопаснее, чем когда-либо: + [явное значение null][oo-explicit-null] выводит `null` из иерархии типов, помогая статически отлавливать ошибки; + дополнительные проверки для [безопасной инициализации][oo-safe-init] обнаруживают попытки доступа к неинициализированным объектам. + +### Зарядка в комплекте: метапрограммирование +В то время как макросы в Scala 2 были только экспериментальной функцией, +Scala 3 поставляется с мощным арсеналом инструментов для метапрограммирования. +[Учебник по макросам]({% link _overviews/scala3-macros/tutorial/index.md %}) содержит подробную информацию о различных возможностях. +В частности, Scala 3 предлагает следующие функциональности для метапрограммирования: + +- **Inline**. В качестве базовой отправной точки [функция inline][meta-inline] позволяет редуцировать значения и методы во время компиляции. + Эта простая функция уже охватывает множество вариантов использования + и в то же время обеспечивает отправную точку для более продвинутых функций. +- **Операции времени компиляции**. Пакет [`scala.compiletime`][meta-compiletime] содержит дополнительные функции, + которые можно использовать для реализации inline методов. +- **Блоки кода Quoted**. В Scala 3 добавлена новая функция [квазицитирования кода][meta-quotes], + обеспечивающая удобный высокоуровневый интерфейс для создания и анализа кода. + Создать код для добавления единицы к единице так же просто, как `'{ 1 + 1 }`. +- **Reflection API**. Для более продвинутых вариантов использования [quotes.reflect][meta-reflection] + предоставляет более детализированный контроль для проверки и создания деревьев программ. + +Если вы хотите узнать больше о метапрограммировании в Scala 3, приглашаем вас пройти наш [tutorial][meta-tutorial]. + + +[enums]: {{ site.scala3ref }}/enums/enums.html +[enums-adts]: {{ site.scala3ref }}/enums/adts.html + +[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html +[types-union]: {{ site.scala3ref }}/new-types/union-types.html +[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html +[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html +[types-match]: {{ site.scala3ref }}/new-types/match-types.html +[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html + +[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html +[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html +[reference]: {{ site.scala3ref }}/overview.html +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %} +[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %} + +[implicits]: {{ site.scala3ref }}/contextual +[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html +[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html +[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html +[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html +[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html + +[syntax-summary]: {{ site.scala3ref }}/syntax.html +[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html +[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html +[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html + +[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %} +[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %} + +[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html +[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html +[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html +[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html +[oo-export]: {{ site.scala3ref }}/other-new-features/export.html diff --git a/_ru/scala3/scaladoc.md b/_ru/scala3/scaladoc.md new file mode 100644 index 0000000000..9c3df2e7fe --- /dev/null +++ b/_ru/scala3/scaladoc.md @@ -0,0 +1,108 @@ +--- +layout: singlepage-overview +title: Новые возможности Scaladoc +partof: scala3-scaladoc +scala3: true +language: ru +--- + +Новая версия Scala 3 поставляется со совершенно новой реализацией генератора документации _Scaladoc_, переписанной с нуля. +В этой статье вы можете найти основные сведения о новых функциях, которые уже есть или будут представлены в Scaladoc. +Для общей справки см. руководство по [Scaladoc][scaladoc]. + +## Новая функциональность + +### Markdown синтаксис + +Самым большим изменением, представленным в новой версии Scaladoc, является изменение языка по умолчанию для строк документации. +До сих пор Scaladoc поддерживал только синтаксис Wikidoc. +Новый Scaladoc по-прежнему может анализировать устаревший синтаксис `Wikidoc`, +однако Markdown был выбран в качестве основного языка для форматирования комментариев. +Чтобы переключиться обратно на `Wikidoc`, можно передать глобальный параметр перед запуском задачи `doc` +или определить его для конкретных комментариев с помощью директивы `@syntax wiki`. + +Для получения дополнительной информации о том, как использовать все возможности документации, +ознакомьтесь с [документацией Scaladoc][scaladoc-docstrings]. + +### Статический сайт + +Scaladoc также предоставляет простой способ создания **статических сайтов** как для документации, +так и для сообщений в блогах, подобно тому, как это делает Jekyll. +Благодаря этой функциональности вы можете очень удобно хранить свою документацию вместе со сгенерированным Scaladoc API. + +Для получения дополнительной информации о том, как настроить создание статических сайтов, +ознакомьтесь с главой [Статическая документация][static-documentation]. + +![](../../resources/images/scala3/scaladoc/static-site.png) + +### Посты в блоге + +Посты в блогах — это особый тип статических сайтов. В руководстве по работе со Scaladoc +вы можете найти дополнительную информацию о том, как работать с [сообщениями в блогах][built-in-blog]. + +![](../../resources/images/scala3/scaladoc/blog-post.png) + +### Ссылки на соцсети + +Кроме того, Scaladoc предоставляет простой способ настроить [ссылки на социальные сети][social-links], например Twitter или Discord. + +![](../../resources/images/scala3/scaladoc/social-links.png){: style="width: 180px"} + +## Экспериментальные функции + +Следующие функции в настоящее время (май 2021 г.) не являются стабильными для выпуска в scaladoc, +однако мы рады услышать ваши отзывы. +У каждой функции есть отдельная ветка на сайте авторов scala-lang, где вы можете поделиться своим мнением. + +### Компиляция фрагментов + +Одной из экспериментальных возможностей Scaladoc является компилятор фрагментов кода. +Этот инструмент позволит вам компилировать фрагменты, которые вы прикрепляете к своей строке документации, +чтобы проверить, действительно ли они ведут себя так, как предполагалось, например, правильно ли компилируются. +Эта функция очень похожа на инструменты `tut` или `mdoc`, но будет поставляться вместе со Scaladoc, +что упрощает настройку и интеграцию в ваш проект. +Создание интерактивных фрагментов — например, предоставление пользователям возможности редактировать +и компилировать их в браузере — находится на рассмотрении. Но в настоящее время эта функция пока не рассматривается. + +Демонстрация: +* Скрытие кода ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/hiding-code.gif) +* Проверка ошибок компиляции ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/assert-compilation-errors.gif) +* Включение фрагментов ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-includes.png) + +Для получения дополнительной информации см. [Руководства][snippet-compiler] +или следите за этой веткой [Scala Contributors](https://contributors.scala-lang.org/t/snippet-validation-in-scaladoc-for-scala-3/4976). + +### Поиск по типу + +Поиск функций по их символическим именам может занять много времени. +Вот почему новый scaladoc позволяет искать методы и поля по их типам. + +Итак, для объявления: + +``` +extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ... +``` + +Вместо поиска по `span` мы также можем искать по `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`. + +Чтобы использовать эту функциональность, просто введите сигнатуру функции, которую ищете, в строке поиска scaladoc. +Вот как это работает: + +![](../../resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif) + +Эта функция предоставляется поисковой системой [Inkuire](https://github.com/VirtusLab/Inkuire), которая работает для Scala 3 и Kotlin. +Чтобы быть в курсе развития этой функции, следите за репозиторием [Inkuire](https://github.com/VirtusLab/Inkuire). + +Для получения дополнительной информации см. [соответствующую главу][search-engine] + +Обратите внимание, что эта функция все еще находится в разработке, поэтому в нее могут быть внесены значительные изменения. +Если вы столкнулись с ошибкой или у вас есть идея для улучшения, не стесняйтесь создавать issue на +[Inkuire](https://github.com/VirtusLab/Inkuire/issues/new) или [dotty](https://github.com/scala/scala3/issues/new). + +[scaladoc]: /ru/scala3/guides/scaladoc/index.html +[scaladoc-docstrings]: /ru/scala3/guides/scaladoc/docstrings.html +[static-documentation]: /ru/scala3/guides/scaladoc/static-site.html +[built-in-blog]: /ru/scala3/guides/scaladoc/blog.html +[social-links]: /ru/scala3/guides/scaladoc/settings.html#-social-links +[search-engine]: /ru/scala3/guides/scaladoc/search-engine.html +[snippet-compiler]: /ru/scala3/guides/scaladoc/snippet-compiler.html diff --git a/_ru/scala3/talks.md b/_ru/scala3/talks.md new file mode 100644 index 0000000000..25fce82809 --- /dev/null +++ b/_ru/scala3/talks.md @@ -0,0 +1,73 @@ +--- +layout: singlepage-overview +title: Обсуждения +partof: scala3-scaladoc +scala3: true +language: ru +versionSpecific: true +--- + +Серия "Давайте поговорим о Scala 3" +------------------------------- + +[Давайте поговорим о Scala 3](https://www.youtube.com/playlist?list=PLTx-VKTe8yLxYQfX_eGHCxaTuWvvG28Ml) — это серия +коротких (около 15 минут) докладов о Scala 3. Они охватывают различные темы, например, как начать работу, +как воспользоваться преимуществами новых языковых функций или как перейти со Scala 2. + +Обсуждения Scala 3 +---------------- +- (ScalaDays 2019, Lausanne) [Тур по Scala 3](https://www.youtube.com/watch?v=_Rnrx2lo9cw) от [Martin Odersky](http://x.com/odersky) + +- (ScalaDays 2016, Berlin) [Развитие Scala](https://www.youtube.com/watch?v=GHzWqJKFCk4) от [Martin Odersky](http://x.com/odersky) [\[слайды\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016) + +- (JVMLS 2015) [Компиляторы — это базы данных](https://www.youtube.com/watch?v=WxyyJyB_Ssc) от [Martin Odersky](http://x.com/odersky) [\[слайды\]](http://www.slideshare.net/Odersky/compilers-are-databases) + +- (Scala World 2015) [Dotty: изучение будущего Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) от [Dmitry Petrashko](http://x.com/darkdimius) [\[слайды\]](https://d-d.me/scalaworld2015/#/). + Дмитрий рассказывает о многих новых функциях, которые предлагает Dotty, таких как типы пересечения и объединения, + улучшенная инициализация lazy val и многое другое. Дмитрий также рассказывает о внутреннем устройстве Dotty + и, в частности, о высоком уровне контекстных абстракций Dotty. + Вы познакомитесь со многими основными понятиями, такими как `Denotations`, их эволюция во времени (компиляции), + их преобразования и многое другое. + +Глубокое погружение в Scala 3 +---------------------- +- (ScalaDays 2019, Lausanne) [Метапрограммирование в Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) от [Nicolas Stucki](https://github.com/nicolasstucki). + +- (ScalaDays 2019, Lausanne) [Scala, ориентированная на будущее: промежуточное представление TASTY](https://www.youtube.com/watch?v=zQFjC3zLYwo) от [Guillaume Martres](http://guillaume.martres.me/). + +- (Mar 21, 2017) [Dotty Internals 1: Trees & Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8) от [Dmitry Petrashko](http://x.com/darkdimius) [\[заметки\]](https://dotty.epfl.ch/docs/internals/dotty-internals-1-notes.html). + Это записанная встреча между EPFL и Waterloo, на которой мы представляем первые понятия внутри Dotty: деревья и символы. + +- (Mar 21, 2017) [Dotty Internals 2: Types](https://www.youtube.com/watch?v=3gmLIYlGbKc) от [Martin Odersky](http://x.com/odersky) и [Dmitry Petrashko](http://x.com/darkdimius). + Это записанная встреча между EPFL и Waterloo, на которой мы рассказываем, как типы представлены внутри Dotty. + +- (Jun 15, 2017) [Dotty Internals 3: Denotations](https://youtu.be/9iPA7zMRGKY) от [Martin Odersky](http://x.com/odersky) и [Dmitry Petrashko](http://x.com/darkdimius). + Это записанная встреча между EPFL и Waterloo, где мы вводим обозначения в Dotty. + +- (JVM Language Summit) [How do we make the Dotty compiler fast](https://www.youtube.com/watch?v=9xYoSwnSPz0) от [Dmitry Petrashko](http://x.com/darkdimius). + [Dmitry Petrashko](http://x.com/darkdimius) в общих чертах рассказывает о том, что было сделано для создания Dotty. + +- (Typelevel Summit Oslo, May 2016) [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) от + Guillaume Martres [\[слайды\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/). + Guillaume сосредоточился на некоторых практических улучшениях системы типов, реализованных в Dotty, + таких как новый алгоритм вывода параметров типа, + который может принимать решения о безопасности типов в большем количестве ситуаций, чем scalac. + +- (flatMap(Oslo) 2016) [AutoSpecialization in Dotty](https://vimeo.com/165928176) от [Dmitry Petrashko](http://x.com/darkdimius) [\[слайды\]](https://d-d.me/talks/flatmap2016/#/). + Dotty Linker анализирует вашу программу и ее зависимости, чтобы применить новую схему специализации. + Он основан на нашем опыте Specialization, Miniboxing и проекта Valhalla и значительно уменьшает размер создаваемого байт-кода. + И, что лучше всего, он всегда включен, выполняется за кулисами без аннотаций и приводит к ускорению более чем в 20 раз. + Кроме того, он "просто работает" с коллекциями Scala. + +- (ScalaSphere 2016) [Hacking on Dotty: A live demo](https://www.youtube.com/watch?v=0OOYGeZLHs4) от Guillaume Martres [\[слайды\]](http://guillaume.martres.me/talks/dotty-live-demo/). + Guillaume взламывает Dotty: живая демонстрация, во время которой он создает простую фазу компиляции + для трассировки вызовов методов во время выполнения. + +- (Scala By the Bay 2016) [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) от Guillaume + Martres [\[слайды\]](http://guillaume.martres.me/talks/dotty-tutorial/#/). + Guillaume предоставляет высокоуровневое представление о конвейере компиляции Dotty. + +- (ScalaDays 2015, Amsterdam) [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) от Dmitry Petrashko [\[слайды\]](https://d-d.me/scaladays2015/#/). + Дмитрий представляет алгоритм анализа графа вызовов, который реализует Dotty, и преимущества производительности, + которые мы можем получить с точки зрения количества методов, размера байт-кода, размера кода JVM + и количества объектов, выделенных в конце. diff --git a/_ru/scalacenter-courses.md b/_ru/scalacenter-courses.md new file mode 100644 index 0000000000..efa09f8254 --- /dev/null +++ b/_ru/scalacenter-courses.md @@ -0,0 +1,166 @@ +--- +title: Онлайн курсы (MOOCs) от Scala Center +layout: singlepage-overview +language: ru +testimonials: +- /resources/images/scalacenter-courses/testimonial000.jpg +- /resources/images/scalacenter-courses/testimonial001.jpg +- /resources/images/scalacenter-courses/testimonial002.jpg +- /resources/images/scalacenter-courses/testimonial003.jpg +- /resources/images/scalacenter-courses/testimonial004.jpg +- /resources/images/scalacenter-courses/testimonial005.jpg +- /resources/images/scalacenter-courses/testimonial006.jpg +- /resources/images/scalacenter-courses/testimonial007.jpg +- /resources/images/scalacenter-courses/testimonial008.jpg +- /resources/images/scalacenter-courses/testimonial009.jpg +- /resources/images/scalacenter-courses/testimonial010.jpg +- /resources/images/scalacenter-courses/testimonial011.jpg +- /resources/images/scalacenter-courses/testimonial012.jpg +- /resources/images/scalacenter-courses/testimonial013.jpg +- /resources/images/scalacenter-courses/testimonial014.jpg +--- + +[Scala Center] создает онлайн-курсы (также известные как МООК) различного уровня: от начального до продвинутого. + +**Если вы программист и хотите изучить Scala**, рекомендуется использовать два подхода. +Быстрый путь состоит в прохождении курса ["Эффективное программирование на Scala"](#effective-programming-in-scala). +В противном случае вы можете пройти полную [специализацию Scala][Scala Specialization], +состоящую из четырех курсов (охватывающих сложные темы, такие как анализ больших данных и параллельное программирование) +и завершающего проекта. + +Подробнее о курсах вы можете узнать из следующего видео: + +
            + +
            + +## Путь обучения Scala + +На диаграмме ниже показаны возможные пути обучения на наших курсах: + +![](/resources/images/learning-path.png) + +"Базовые" курсы предназначены для программистов без предварительного опыта работы со Scala, +тогда как "углубленные" курсы направлены на укрепление навыков программирования на Scala в конкретной области +(например, параллельном программировании). + +Мы рекомендуем начать с "Эффективного программирования на Scala" (Effective Programming in Scala) +или "Принципов функционального программирования на Scala" (Functional Programming Principles in Scala), +а затем с "Проектирования функциональных программ" (Functional Program Design). +Затем вы можете дополнить свои навыки Scala, +пройдя любой из курсов "Программирование реактивных систем" (Programming Reactive Systems), +"Параллельное программирование" (Parallel Programming) +или "Анализ больших данных с помощью Scala и Spark" (Big Data Analysis with Scala and Spark). +Если вы выберете специализацию Scala, то последним проектом будет Scala Capstone. + +## Учебные платформы + +В настоящее время все наши МООК доступны на платформе [Coursera](https://coursera.org), +а некоторые из них доступны на [edX](https://edx.org) или [Extension School](https://extensionschool.ch). +В этом разделе объясняются различия между этими учебными платформами. + +На всех платформах полный материал всегда доступен онлайн. +Он включает в себя видеолекции, текстовые статьи, опросники и домашние задания с автоматической оценкой. +Все платформы также предоставляют дискуссионные форумы, где вы можете общаться с другими учащимися. + +Отличие Extension School от других платформ заключается в том, +что она проводит живые встречи с инструкторами и обзоры кода экспертами Scala. + +С другой стороны, на Coursera или edX наши курсы можно пройти бесплатно (режим "audit"). +При желании подписка дает вам доступ к сертификату об окончании, подтверждающему ваши результаты. + +Узнайте больше о [сертификатах Coursera](https://learners.coursera.help/hc/en-us/articles/209819053-Get-a-Course-Certificate), +[сертификатах edX](https://support.edx.org/hc/en-us/categories/115002269627-Certificates) +или [сертификатах Extension School](https://www.extensionschool.ch/faqs#certifying-coursework). +Обратите внимание, что ваши подписки также поддерживают работу [Scala Center], +миссией которого является создание качественных учебных материалов. + +Если вы предпочитаете самостоятельное обучение, мы рекомендуем вам выбрать платформу Coursera или edX, +но если вам нужна дополнительная поддержка, рекомендуем вам выбрать Extension School. +Ниже приведена таблица, в которой сравниваются платформы обучения: + +| | Coursera / edX (аудит) | Coursera / edX (подписка) | Extension School | +| ------------------------------------------------ | ---------------------- | ------------------------- | ---------------- | +| Видео-лекции, тесты | Да | Да | Да | +| Домашние задания с автоматической оценкой | Да | Да | Да | +| Дискуссионные форумы | Да | Да | Да | +| Самостоятельный темп | Да | Да | Да | +| Стоимость | $0 | от $50 до $100 за курс | $420 в месяц | +| Сертификат об окончании | Нет | Да | Да | +| Поддерживает Scala Center | Нет | Да | Да | +| 30 минут живого занятия с инструкторами в неделю | Нет | Нет | Да | +| Code reviews экспертами Scala | Нет | Нет | Да | + +## Effective Programming in Scala + +Этот курс доступен на [Coursera](https://coursera.org/learn/effective-scala) и [Extension School](https://extensionschool.ch/learn/effective-programming-in-scala). +Пожалуйста, обратитесь к [этому разделу](#учебные-платформы), чтобы узнать о различиях между обеими учебными платформами. + +["Эффективное программирование на Scala"][Effective Programming in Scala] обучает программистов, не владеющих Scala, +всему, что им нужно для подготовки к работе в Scala. +В конце этого практического курса вы узнаете, как решать общие задачи программирования на Scala +(например, моделирование бизнес-областей, реализацию бизнес-логики, +проектирование больших систем, состоящих из компонентов, +обработку ошибок, обработка данных, параллельное выполнение задач, тестирование вашего кода). +Подробнее об этом курсе вы можете узнать из следующего видео: + +
            + +
            + +Этот курс также является хорошим способом улучшить свои знания Scala 2 до Scala 3. + +После прохождения этого курса вам может быть интересно улучшить свои навыки в конкретных областях, +пройдя курсы ["Параллельное программирование"][Parallel Programming], +["Анализ больших данных с помощью Scala и Spark"][Big Data Analysis with Scala and Spark] +или ["Программирование реактивных систем"][Programming Reactive Systems]. + +## Специализация Scala + +[Специализация Scala][Scala Specialization] обеспечивает практическое введение в функциональное программирование с использованием Scala. +Вы можете получить доступ к материалам и упражнениям курса, зарегистрировавшись на специализацию или прослушав курсы индивидуально. +Специализация состоит из следующих курсов: + +- [Принципы функционального программирования на Scala][Functional Programming Principles in Scala], +- [Функциональный дизайн программ на Scala][Functional Program Design in Scala], +- [Параллельное программирование][Parallel programming], +- [Анализ больших данных с помощью Scala и Spark][Big Data Analysis with Scala and Spark], +- [Функциональное программирование в Scala Capstone][Functional Programming in Scala Capstone]. + +Эти курсы обеспечивают глубокое понимание самого языка Scala, а также погружаются в более конкретные темы, +такие как параллельное программирование и Spark. + +## Программирование реактивных систем + +[Программирование реактивных систем][Programming Reactive Systems] +(также доступно на [edX](https://www.edx.org/course/scala-akka-reactive)) +обучает писать адаптивные, масштабируемые и отказоустойчивые системы с помощью библиотеки Akka. + +## Курсы по Скала 2 + +Все вышеперечисленные курсы используют Scala 3. +При необходимости вы можете найти (устаревшую) версию наших курсов Scala 2 здесь: + +- [Принципы функционального программирования на Scala (версия Scala 2)](https://www.coursera.org/learn/scala2-functional-programming) +- [Функциональный дизайн программ на Scala (версия Scala 2)](https://www.coursera.org/learn/scala2-functional-program-design) +- [Параллельное программирование (версия Scala 2)](https://www.coursera.org/learn/scala2-parallel-programming) +- [Анализ больших данных с помощью Scala и Spark (версия Scala 2)](https://www.coursera.org/learn/scala2-spark-big-data) +- [Программирование реактивных систем (версия Scala 2)](https://www.coursera.org/learn/scala2-akka-reactive) + +## Отзывы + +{% include carousel.html images=page.testimonials number=0 height="50" unit="%" duration="10" %} + +## Другие онлайн-ресурсы + +[На этой странице]({% link online-courses.md %}) вы можете найти другие онлайн-ресурсы, предоставленные сообществом. + +[Scala Center]: https://scala.epfl.ch +[Scala Specialization]: https://www.coursera.org/specializations/scala +[Effective Programming in Scala]: https://www.coursera.org/learn/effective-scala +[Functional Programming Principles in Scala]: https://www.coursera.org/learn/scala-functional-programming +[Functional Program Design in Scala]: https://www.coursera.org/learn/scala-functional-program-design +[Parallel programming]: https://www.coursera.org/learn/scala-parallel-programming +[Big Data Analysis with Scala and Spark]: https://www.coursera.org/learn/scala-spark-big-data +[Functional Programming in Scala Capstone]: https://www.coursera.org/learn/scala-capstone +[Programming Reactive Systems]: https://www.coursera.org/learn/scala-akka-reactive diff --git a/_ru/toolkit/OrderedListOfMdFiles b/_ru/toolkit/OrderedListOfMdFiles new file mode 100644 index 0000000000..b2790bd58a --- /dev/null +++ b/_ru/toolkit/OrderedListOfMdFiles @@ -0,0 +1,36 @@ +introduction.md +testing-intro.md +testing-suite.md +testing-run.md +testing-run-only.md +testing-exceptions.md +testing-asynchronous.md +testing-resources.md +testing-what-else.md +os-intro.md +os-read-directory.md +os-read-file.md +os-write-file.md +os-run-process.md +os-what-else.md +json-intro.md +json-parse.md +json-modify.md +json-deserialize.md +json-serialize.md +json-files.md +json-what-else.md +http-client-intro.md +http-client-request.md +http-client-uris.md +http-client-request-body.md +http-client-json.md +http-client-upload-file.md +http-client-what-else.md +web-server-intro.md +web-server-static.md +web-server-dynamic.md +web-server-query-parameters.md +web-server-input.md +web-server-websockets.md +web-server-cookies-and-decorators.md diff --git a/_ru/toolkit/http-client-intro.md b/_ru/toolkit/http-client-intro.md new file mode 100644 index 0000000000..6e552acecd --- /dev/null +++ b/_ru/toolkit/http-client-intro.md @@ -0,0 +1,24 @@ +--- +layout: multipage-overview +partof: toolkit +overview-name: "Scala инструментарий" +title: Отправка HTTP-запросов с помощью sttp +type: chapter +description: Введение в библиотеку sttp +language: ru +num: 23 +previous-page: +next-page: +--- + +sttp — популярная и многофункциональная библиотека для выполнения HTTP-запросов к веб-серверам. + +Она предоставляет как синхронный API, так и асинхронный API, основанный на `Future`. Она также поддерживает WebSockets. + +Доступны расширения, добавляющие такие возможности, как потоковая передача, логирование, телеметрия и сериализация. + +sttp предлагает одинаковые API на всех платформах (JVM, Scala.js и Scala Native). + +sttp — хороший выбор для небольших синхронных скриптов, а также для крупномасштабных, высококонкурентных, асинхронных приложений. + +{% include markdown.html path="_markdown/_ru/install-sttp.md" %} diff --git a/_ru/toolkit/introduction.md b/_ru/toolkit/introduction.md new file mode 100644 index 0000000000..f6a216e298 --- /dev/null +++ b/_ru/toolkit/introduction.md @@ -0,0 +1,88 @@ +--- +layout: multipage-overview +partof: toolkit +overview-name: "Scala инструментарий" +title: Введение +type: chapter +description: Знакомство с учебными пособиями по Scala инструментариям +language: ru +num: 1 +previous-page: +next-page: testing-intro +toolkit-index: + - title: Тесты + description: Тестирование кода с помощью MUnit. + icon: "fa fa-vial-circle-check" + link: /ru/toolkit/testing-intro.html + - title: Файлы и процессы + description: Запись файлов и запуск процессов с помощью OS-Lib. + icon: "fa fa-folder-open" + link: /ru/toolkit/os-intro.html + - title: JSON + description: Парсинг JSON и сериализация объектов в JSON с помощью uPickle. + icon: "fa fa-file-code" + link: /ru/toolkit/json-intro.html + - title: HTTP-запросы + description: Отправка HTTP-запросов и загрузка файлов с помощью sttp. + icon: "fa fa-globe" + link: /ru/toolkit/http-client-intro.html + - title: Веб-серверы + description: Создание веб-серверов с помощью Cask. + icon: "fa fa-server" + link: /ru/toolkit/web-server-intro.html +--- + +## Что такое набор инструментов Scala? + +Scala Toolkit — это набор библиотек, предназначенных для эффективного выполнения типичных задач программирования. +Он включает в себя инструменты для работы с файлами и процессами, парсинга JSON, отправки HTTP-запросов и модульного тестирования. + +Инструментарий поддерживает: + +- Scala 3 и Scala 2 +- JVM, Scala.js и Scala Native + +Варианты использования набора инструментов включают в себя: + +- кратковременные программы, работающие на JVM, для сканирования веб-сайта, сбора и преобразования данных + или для извлечения и обработки некоторых файлов, +- скрипты интерфейса, которые запускаются в браузере и обеспечивают работу ваших веб-сайтов, +- инструменты командной строки, упакованные в виде собственных двоичных файлов для мгновенного запуска + +{% include inner-documentation-sections.html links=page.toolkit-index %} + +## Что это за руководства? + +В этой серии руководств основное внимание уделяется кратким примерам кода, которые помогут вам быстро приступить к работе. + +Если вам нужна более подробная информация, в руководствах содержатся ссылки на дополнительную документацию +по всем библиотекам в наборе инструментов. + +## Как запустить код? + +Вы можете следовать руководствам независимо от того, как решите запустить свой Scala код. +Руководства фокусируются на самом коде, а не на процессе его запуска. + +Способы запуска кода на Scala включают: + +- В вашем **браузере** с помощью [Scastie](https://scastie.scala-lang.org) + - Плюсы: не требует установки, возможность делиться кодом онлайн + - Минусы: только один файл, доступно только онлайн +- Интерактивно в **REPL** Scala (Read/Eval/Print/Loop) + - Плюсы: интерактивное исследование в терминале + - Минусы: не сохраняет ваш код +- Интерактивно в **worksheet** в вашей IDE, например [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) или [Metals](http://scalameta.org/metals/) + - Плюсы: интерактивное исследование в графическом интерфейсе + - Минусы: требует для запуска среды worksheet +- В **скриптах** с использованием [Scala CLI](https://scala-cli.virtuslab.com) + - Плюсы: рабочий процесс в терминале с минимальной настройкой + - Минусы: может не подходить для крупных проектов +- С использованием **инструмента сборки** (например, [sbt](https://www.scala-sbt.org) или [mill](https://com-lihaoyi.github.io/mill/)) + - Плюсы: рабочий процесс в терминале для проектов любого размера + - Минусы: требует дополнительной настройки и обучения +- С использованием **IDE**, например [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) или [Metals](http://scalameta.org/metals/) + - Плюсы: рабочий процесс в графическом интерфейсе для проектов любого размера + - Минусы: требует дополнительной настройки и обучения + +Эти варианты, с их плюсами и минусами, характерны для большинства языков программирования. +Вы можете использовать любой из них, в зависимости от того варианта, который вам удобен. diff --git a/_ru/toolkit/json-intro.md b/_ru/toolkit/json-intro.md new file mode 100644 index 0000000000..c91f04b075 --- /dev/null +++ b/_ru/toolkit/json-intro.md @@ -0,0 +1,23 @@ +--- +layout: multipage-overview +partof: toolkit +overview-name: "Scala инструментарий" +title: Обработка JSON с помощью uPickle +type: chapter +description: Описание библиотеки uPickle. +language: ru +num: 16 +previous-page: +next-page: +--- + +uPickle — это облегченная библиотека сериализации для Scala. + +В его состав входит uJson — библиотека для работы с JSON, которая может анализировать строки JSON, +получать доступ к их значениям в памяти или изменять их, а также записывать их обратно. + +uPickle может сериализовать и десериализовать объекты Scala напрямую в JSON и из него. +Он знает, как обрабатывать коллекции Scala, такие как `Map` и `Seq`, +а также ваши собственные типы данных, такие как case class-ы и перечисления Scala 3. + +{% include markdown.html path="_markdown/_ru/install-upickle.md" %} diff --git a/_ru/toolkit/os-intro.md b/_ru/toolkit/os-intro.md new file mode 100644 index 0000000000..4e5cb4fd2a --- /dev/null +++ b/_ru/toolkit/os-intro.md @@ -0,0 +1,25 @@ +--- +layout: multipage-overview +partof: toolkit +overview-name: "Scala инструментарий" +title: Работа с файлами и процессами с помощью OS-Lib +type: chapter +description: Введение в библиотеку OS-lib +language: ru +num: 10 +previous-page: +next-page: +--- + +OS-Lib — это библиотека для работы с файлами и процессами. Она является частью Scala Toolkit. + +OS-Lib стремится заменить API `java.nio.file` и `java.lang.ProcessBuilder`. +Скорее всего, вам не понадобиться напрямую использовать какие-либо низкоуровневые Java API. + +OS-Lib также нацелена на то, чтобы вытеснить устаревшие API `scala.io` и `scala.sys` из стандартной библиотеки Scala. + +OS-Lib не имеет зависимостей. + +Весь функционал OS-Lib находится в пространстве имён `os.*`. + +{% include markdown.html path="_markdown/_ru/install-os-lib.md" %} diff --git a/_ru/toolkit/testing-intro.md b/_ru/toolkit/testing-intro.md new file mode 100644 index 0000000000..3fa905ddb3 --- /dev/null +++ b/_ru/toolkit/testing-intro.md @@ -0,0 +1,28 @@ +--- +layout: multipage-overview +partof: toolkit +overview-name: "Scala инструментарий" +title: Тестирование с помощью MUnit +type: chapter +description: Введение в библиотеку MUnit +language: ru +num: 2 +previous-page: introduction +next-page: +--- + +MUnit — легковесная библиотека для тестирования. Она предоставляет единый стиль написания тестов, который можно быстро освоить. + +Несмотря на свою простоту, MUnit обладает такими полезными функциями, как: + +- **утверждения (assertions)** для проверки поведения программы, +- **фикстуры (fixtures)**, чтобы гарантировать, что тесты имеют доступ ко всем необходимым ресурсам, +- **поддержка асинхронности** для тестирования параллельных (concurrent) и распределённых приложений. + +MUnit создаёт полезные отчёты об ошибках с указанием различий и местоположения в исходном коде, что помогает быстро понять причины сбоев. + +Тестирование является важной частью любого процесса разработки программного обеспечения, +так как оно помогает находить ошибки на ранних этапах, +улучшает качество кода и облегчает совместную работу. + +{% include markdown.html path="_markdown/_ru/install-munit.md" %} diff --git a/_ru/toolkit/web-server-intro.md b/_ru/toolkit/web-server-intro.md new file mode 100644 index 0000000000..6afdebab4f --- /dev/null +++ b/_ru/toolkit/web-server-intro.md @@ -0,0 +1,30 @@ +--- +layout: multipage-overview +partof: toolkit +overview-name: "Scala инструментарий" +title: Создание веб-серверов с помощью Cask +type: chapter +description: Введение в библиотеку Cask +language: ru +num: 30 +previous-page: +next-page: +--- + +Cask — это микрофреймворк HTTP, предоставляющий простой и гибкий способ создания веб-приложений. + +Основное внимание уделяется простоте использования, что делает его идеальным для новичков, +но при этом приходится отказываться от некоторых функций, предоставляемых другими фреймворками, например, асинхронности. + +Чтобы определить endpoint, достаточно аннотировать функцию аннотацией, указывающей путь запроса. +Cask позволяет вручную строить ответ с помощью инструментов, предоставляемых библиотекой, +указывая содержимое, заголовки, код статуса и т.д. +Функция endpoint также может возвращать строку, JSON тип [uPickle](https://com-lihaoyi.github.io/upickle/) +или шаблон [Scalatags](https://com-lihaoyi.github.io/scalatags/). +В этом случае Cask автоматически создаст ответ с соответствующими заголовками. + +Cask поставляется в комплекте с библиотекой uPickle для обработки JSON, поддерживает WebSockets +и позволяет расширять конечные точки с помощью декораторов, +которые можно использовать для обработки аутентификации или ограничения скорости. + +{% include markdown.html path="_markdown/_ru/install-cask.md" %} diff --git a/_ru/tour/abstract-type-members.md b/_ru/tour/abstract-type-members.md new file mode 100644 index 0000000000..537ebf80f4 --- /dev/null +++ b/_ru/tour/abstract-type-members.md @@ -0,0 +1,154 @@ +--- +layout: tour +title: Члены Абстрактного Типа +partof: scala-tour +num: 23 +language: ru +next-page: compound-types +previous-page: inner-classes +topics: abstract type members +prerequisite-knowledge: variance, upper-type-bound +--- + +Абстрактные типы, такие как трейты и абстрактные классы, могут содержать члены абстрактного типа. +Абстрактный означает, что только конкретный экземпляр определяет, каким именно будет тип. +Вот пример: + +{% tabs abstract-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_1 %} + +```scala mdoc +trait Buffer { + type T + val element: T +} +``` + +{% endtab %} +{% tab 'Scala 3' for=abstract-types_1 %} + +```scala +trait Buffer: + type T + val element: T +``` + +{% endtab %} +{% endtabs %} + +Здесь мы определили абстрактный тип `T`, который используется для описания типа члена `element`. Мы можем расширить его в абстрактном классе, добавив верхнюю границу нового типа `U`, связанного с `T`, делая описание типа более конкретным. + +{% tabs abstract-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_2 %} + +```scala mdoc +abstract class SeqBuffer extends Buffer { + type U + type T <: Seq[U] + def length = element.length +} +``` + +{% endtab %} +{% tab 'Scala 3' for=abstract-types_2 %} + +```scala +abstract class SeqBuffer extends Buffer: + type U + type T <: Seq[U] + def length = element.length +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, как мы можем использовать новый абстрактный тип `U` в качестве верхней границы типа. Класс `SeqBuffer` позволяет хранить в буфере только последовательности, указывая, что тип `T` должен быть подтипом `Seq[U]` для нового абстрактного типа `U`. + +[Трейты](traits.html) или [классы](classes.html) с членами абстрактного типа часто используются в сочетании с анонимными экземплярами классов. Чтобы проиллюстрировать это рассмотрим программу, имеющую дело с буфером, который ссылается на список целых чисел: + +{% tabs abstract-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_3 %} + +```scala mdoc +abstract class IntSeqBuffer extends SeqBuffer { + type U = Int +} + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` + +{% endtab %} +{% tab 'Scala 3' for=abstract-types_3 %} + +```scala +abstract class IntSeqBuffer extends SeqBuffer: + type U = Int + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer: + type T = List[U] + val element = List(elem1, elem2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` + +{% endtab %} +{% endtabs %} + +Здесь метод `newIntSeqBuf` создает экземпляры `IntSeqBuffer`, используя анонимную реализацию класса `IntSeqBuffer` (т.е. `new IntSeqBuffer`), устанавливая тип `T` как `List[Int]`. + +Мы можем вывести тип класса из типа его членов и наоборот. Приведем версию кода, в которой выводится тип класса из типов его члена: + +{% tabs abstract-types_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_4 %} + +```scala mdoc:nest +abstract class Buffer[+T] { + val element: T +} +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { + def length = element.length +} + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` + +{% endtab %} +{% tab 'Scala 3' for=abstract-types_4 %} + +```scala +abstract class Buffer[+T]: + val element: T + +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T]: + def length = element.length + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]]: + val element = List(e1, e2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что здесь необходимо использовать [вариантность в описании типа](variances.html) (`+T <: Seq[U]`) для того, чтобы скрыть конкретный тип реализации списка, возвращаемого из метода `newIntSeqBuf`. diff --git a/_ru/tour/annotations.md b/_ru/tour/annotations.md new file mode 100644 index 0000000000..0af144139d --- /dev/null +++ b/_ru/tour/annotations.md @@ -0,0 +1,247 @@ +--- +layout: tour +title: Аннотации +partof: scala-tour +num: 32 +language: ru +next-page: packages-and-imports +previous-page: by-name-parameters +--- + +Аннотации используются для передачи метаданных при объявлении. Например, аннотация `@deprecated` перед объявлением метода, заставит компилятор вывести предупреждение, если этот метод будет использован. + +{% tabs annotations_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_1 %} + +```scala mdoc:fail +object DeprecationDemo extends App { + @deprecated("deprecation message", "release # which deprecates method") + def hello = "hola" + + hello +} +``` + +{% endtab %} +{% tab 'Scala 3' for=annotations_1 %} + +```scala +object DeprecationDemo extends App: + @deprecated("deprecation message", "release # which deprecates method") + def hello = "hola" + + hello +``` + +{% endtab %} +{% endtabs %} + +Такой код скомпилируется, но компилятор выдаст предупреждение: "there was one deprecation warning". + +Аннотация применяется к первому идущему после нее объявлению или определению. Допускается использование сразу нескольких аннотаций следующих друг за другом. Порядок, в котором приводятся аннотации, не имеет значения. + +## Аннотации, обеспечивающие корректность работы кода + +Некоторые аннотации приводят к невозможности компиляции, если условие (условия) не выполняется. Например, аннотация `@tailrec` гарантирует, что метод является [хвостовой рекурсией](https://ru.wikipedia.org/wiki/%D0%A5%D0%B2%D0%BE%D1%81%D1%82%D0%BE%D0%B2%D0%B0%D1%8F_%D1%80%D0%B5%D0%BA%D1%83%D1%80%D1%81%D0%B8%D1%8F). Хвостовая рекурсия помогает держать потребление памяти на постоянном уровне. Вот как она используется в методе, который вычисляет факториал: + +{% tabs annotations_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_2 %} + +```scala mdoc +import scala.annotation.tailrec + +def factorial(x: Int): Int = { + + @tailrec + def factorialHelper(x: Int, accumulator: Int): Int = { + if (x == 1) accumulator else factorialHelper(x - 1, accumulator * x) + } + factorialHelper(x, 1) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=annotations_2 %} + +```scala +import scala.annotation.tailrec + +def factorial(x: Int): Int = + + @tailrec + def factorialHelper(x: Int, accumulator: Int): Int = + if x == 1 then accumulator else factorialHelper(x - 1, accumulator * x) + factorialHelper(x, 1) +``` + +{% endtab %} +{% endtabs %} + +Метод `factorialHelper` имеет аннотацию `@tailrec`, которая гарантирует, что метод действительно является хвостовой рекурсией. Если бы мы изменили реализацию `factorialHelper` так как указано далее, то компиляция бы провалилась: + +{% tabs annotations_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_3 %} + +```scala mdoc:fail +import scala.annotation.tailrec + +def factorial(x: Int): Int = { + @tailrec + def factorialHelper(x: Int): Int = { + if (x == 1) 1 else x * factorialHelper(x - 1) + } + factorialHelper(x) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=annotations_3 %} + +```scala +import scala.annotation.tailrec + +def factorial(x: Int): Int = + @tailrec + def factorialHelper(x: Int): Int = + if x == 1 then 1 else x * factorialHelper(x - 1) + factorialHelper(x) +``` + +{% endtab %} +{% endtabs %} + +Мы бы получили сообщение "Recursive call not in tail position"(Рекурсивный вызов не в хвостовой позиции). + +## Аннотации, влияющие на генерацию кода + +{% tabs annotations_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_4 %} + +Некоторые аннотации типа `@inline` влияют на сгенерированный код (т.е. в результате сам код вашего jar-файл может отличаться). Такая аннотация означает вставку всего кода в тело метода вместо вызова. Полученный байт-код длиннее, но, надеюсь, работает быстрее. Использование аннотации `@inline` не гарантирует, что метод будет встроен, но заставит компилятор сделать это, если и только если будут соблюдены некоторые разумные требования к размеру сгенерированного кода. + +{% endtab %} +{% tab 'Scala 3' for=annotations_4 %} + +Некоторые аннотации типа `@main` влияют на сгенерированный код (т.е. в результате сам код вашего jar-файл может отличаться). +Аннотация `@main` к методу создает исполняемую программу, которая вызывает метод как точку входа. + +{% endtab %} +{% endtabs %} + +### Java аннотации + +Есть некоторые отличия синтаксиса аннотаций, если пишется Scala код, который взаимодействует с Java. + +**Примечание:**Убедитесь, что вы используете опцию `-target:jvm-1.8` с аннотациями Java. + +Java имеет определяемые пользователем метаданные в виде [аннотаций](https://docs.oracle.com/javase/tutorial/java/annotations/). Ключевой особенностью аннотаций является то, что они задаются в виде пар ключ-значение для инициализации своих элементов. Например, если нам нужна аннотация для отслеживания источника какого-то класса, мы можем определить её как + +{% tabs annotations_5 %} +{% tab 'Java' for=annotations_5 %} + +```java +@interface Source { + public String url(); + public String mail(); +} +``` + +{% endtab %} +{% endtabs %} + +А затем использовать следующим образом + +{% tabs annotations_6 %} +{% tab 'Java' for=annotations_6 %} + +```java +@Source(url = "https://coders.com/", + mail = "support@coders.com") +public class MyJavaClass extends TheirClass ... +``` + +{% endtab %} +{% endtabs %} + +Использование аннотации в Scala похоже на вызов конструктора. Для создания экземпляра из Java аннотации необходимо использовать именованные аргументы: + +{% tabs annotations_7 %} +{% tab 'Scala 2 и 3' for=annotations_7 %} + +```scala +@Source(url = "https://coders.com/", + mail = "support@coders.com") +class MyScalaClass ... +``` + +{% endtab %} +{% endtabs %} + +Этот синтаксис достаточно перегруженный, если аннотация содержит только один элемент (без значения по умолчанию), поэтому, если имя указано как `value`, оно может быть применено в Java с помощью конструктора-подобного синтаксиса: + +{% tabs annotations_8 %} +{% tab 'Java' for=annotations_8 %} + +```java +@interface SourceURL { + public String value(); + public String mail() default ""; +} +``` + +{% endtab %} +{% endtabs %} + +А затем можно использовать следующим образом + +{% tabs annotations_9 %} +{% tab 'Java' for=annotations_9 %} + +```java +@SourceURL("https://coders.com/") +public class MyJavaClass extends TheirClass ... +``` + +{% endtab %} +{% endtabs %} + +В этом случае Scala предоставляет такую же возможность + +{% tabs annotations_10 %} +{% tab 'Scala 2 и 3' for=annotations_10 %} + +```scala +@SourceURL("https://coders.com/") +class MyScalaClass ... +``` + +{% endtab %} +{% endtabs %} + +Элемент `mail` был указан со значением по умолчанию, поэтому нам не нужно явно указывать его значение. Мы не можем смешивать эти два стиля в Java: + +{% tabs annotations_11 %} +{% tab 'Java' for=annotations_11 %} + +```java +@SourceURL(value = "https://coders.com/", + mail = "support@coders.com") +public class MyJavaClass extends TheirClass ... +``` + +{% endtab %} +{% endtabs %} + +Scala обеспечивает большую гибкость в этом отношении + +{% tabs annotations_12 %} +{% tab 'Scala 2 и 3' for=annotations_12 %} + +```scala +@SourceURL("https://coders.com/", + mail = "support@coders.com") +class MyScalaClass ... +``` + +{% endtab %} +{% endtabs %} diff --git a/_ru/tour/basics.md b/_ru/tour/basics.md new file mode 100644 index 0000000000..3d8590bfe7 --- /dev/null +++ b/_ru/tour/basics.md @@ -0,0 +1,601 @@ +--- +layout: tour +title: Основы +partof: scala-tour +num: 2 +language: ru +next-page: unified-types +previous-page: tour-of-scala +--- + +На этой странице мы расскажем об основах Scala. + +## Попробовать Scala в браузере. + +Вы можете запустить Scala в браузере с помощью Scastie. + +1. Зайдите на [Scastie](https://scastie.scala-lang.org/). +2. Вставьте `println("Hello, world!")` в левую панель. +3. Нажмите кнопку "Run". Вывод отобразится в правой панели. + +Это простой способ поэкспериментировать со Scala кодом без всяких настроек. + +## Выражения + +Выражения — это вычислимые утверждения. + +{% tabs expression %} +{% tab 'Scala 2 и 3' for=expression %} + +```scala mdoc +1 + 1 +``` + +{% endtab %} +{% endtabs %} + +Вы можете выводить результаты выражений, используя `println`. + +{% tabs println %} +{% tab 'Scala 2 и 3' for=println %} + +```scala mdoc +println(1) // 1 +println(1 + 1) // 2 +println("Hello!") // Hello! +println("Hello," + " world!") // Hello, world! +``` + +{% endtab %} +{% endtabs %} + +### Значения + +Результаты выражений можно присваивать именам с помощью ключевого слова `val`. + +{% tabs val %} +{% tab 'Scala 2 и 3' for=val %} + +```scala mdoc +val x = 1 + 1 +println(x) // 2 +``` + +{% endtab %} +{% endtabs %} + +Названные результаты, такие как `x` в примере, называются значениями. +Вызов значения не приводит к его повторному вычислению. + +Значения не изменяемы и не могут быть переназначены. + +{% tabs val-error %} +{% tab 'Scala 2 и 3' for=val-error %} + +```scala mdoc:fail +x = 3 // Не компилируется. +``` + +{% endtab %} +{% endtabs %} + +Типы значений могут быть выведены автоматически, но можно и явно указать тип, как показано ниже: + +{% tabs type-inference %} +{% tab 'Scala 2 и 3' for=type-inference %} + +```scala mdoc:nest +val x: Int = 1 + 1 +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что объявление типа `Int` происходит после идентификатора `x`, следующим за `:`. + +### Переменные + +Переменные похожи на значения константы, за исключением того, что их можно присваивать заново. Вы можете объявить переменную с помощью ключевого слова `var`. + +{% tabs var %} +{% tab 'Scala 2 и 3' for=var %} + +```scala mdoc:nest +var x = 1 + 1 +x = 3 // Компилируется потому что "x" объявлен с ключевым словом "var". +println(x * x) // 9 +``` + +{% endtab %} +{% endtabs %} + +Как и в случае со значениями, вы можете явно указать тип, если захотите: + +{% tabs type-inference-2 %} +{% tab 'Scala 2 и 3' for=type-inference-2 %} + +```scala mdoc:nest +var x: Int = 1 + 1 +``` + +{% endtab %} +{% endtabs %} + +## Блоки + +Вы можете комбинировать выражения, окружая их `{}`. Мы называем это блоком. + +Результат последнего выражения в блоке будет результатом всего блока в целом. + +{% tabs blocks %} +{% tab 'Scala 2 и 3' for=blocks %} + +```scala mdoc +println({ + val x = 1 + 1 + x + 1 +}) // 3 +``` + +{% endtab %} +{% endtabs %} + +## Функции + +Функции — это выражения, которые принимают параметры. + +Вы можете определить анонимную функцию (т.е. без имени), которая возвращает переданное число, прибавив к нему единицу: + +{% tabs anonymous-function %} +{% tab 'Scala 2 и 3' for=anonymous-function %} + +```scala mdoc +(x: Int) => x + 1 +``` + +{% endtab %} +{% endtabs %} + +Слева от `=>` находится список параметров. Справа — выражение, связанное с параметрами. + +Вы также можете назвать функции. + +{% tabs named-function %} +{% tab 'Scala 2 и 3' for=named-function %} + +```scala mdoc +val addOne = (x: Int) => x + 1 +println(addOne(1)) // 2 +``` + +{% endtab %} +{% endtabs %} + +Функции могут принимать множество параметров. + +{% tabs multiple-parameters %} +{% tab 'Scala 2 и 3' for=multiple-parameters %} + +```scala mdoc +val add = (x: Int, y: Int) => x + y +println(add(1, 2)) // 3 +``` + +{% endtab %} +{% endtabs %} + +Или вообще не принимать никаких параметров. + +{% tabs no-parameters %} +{% tab 'Scala 2 и 3' for=no-parameters %} + +```scala mdoc +val getTheAnswer = () => 42 +println(getTheAnswer()) // 42 +``` + +{% endtab %} +{% endtabs %} + +## Методы + +Методы выглядят и ведут себя очень похоже на функции, но между ними есть несколько принципиальных различий. + +Методы задаются ключевым словом `def`. За `def` следует имя, список параметров, возвращаемый тип и тело. + +{% tabs method %} +{% tab 'Scala 2 и 3' for=method %} + +```scala mdoc:nest +def add(x: Int, y: Int): Int = x + y +println(add(1, 2)) // 3 +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, как объявлен возвращаемый тип сразу _после_ списка параметров и двоеточия `: Int`. + +Методы могут принимать несколько списков параметров. + +{% tabs multiple-parameter-lists %} +{% tab 'Scala 2 и 3' for=multiple-parameter-lists %} + +```scala mdoc +def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier +println(addThenMultiply(1, 2)(3)) // 9 +``` + +{% endtab %} +{% endtabs %} + +Или вообще ни одного списка параметров. + +{% tabs no-parameter-lists %} +{% tab 'Scala 2 и 3' for=no-parameter-lists %} + +```scala mdoc +def name: String = System.getProperty("user.name") +println("Hello, " + name + "!") +``` + +{% endtab %} +{% endtabs %} + +Есть некоторые отличия от функций, но пока что их можно рассматривать как нечто похожее. + +Методы также могут иметь многострочные выражения. + +{% tabs get-square-string class=tabs-scala-version %} + +{% tab 'Scala 2' for=get-square-string %} + +```scala mdoc +def getSquareString(input: Double): String = { + val square = input * input + square.toString +} +println(getSquareString(2.5)) // 6.25 +``` + +{% endtab %} + +{% tab 'Scala 3' for=get-square-string %} + +```scala +def getSquareString(input: Double): String = + val square = input * input + square.toString + +println(getSquareString(2.5)) // 6.25 +``` + +{% endtab %} + +{% endtabs %} + +Последнее выражение в теле становится возвращаемым значением метода (у Scala есть ключевое слово `return`, но оно практически не используется). + +## Классы + +Вы можете объявлять классы используя ключевое слово `class`, за которым следует его имя и параметры конструктора. + +{% tabs greeter-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-definition %} + +```scala mdoc +class Greeter(prefix: String, suffix: String) { + def greet(name: String): Unit = + println(prefix + name + suffix) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=greeter-definition %} + +```scala +class Greeter(prefix: String, suffix: String): + def greet(name: String): Unit = + println(prefix + name + suffix) +``` + +{% endtab %} + +{% endtabs %} + +Возвращаемый тип метода `greet` это `Unit`, используется тогда, когда не имеет смысла что-либо возвращать. Аналогично `void` в Java и C. Поскольку каждое выражение Scala должно иметь какое-то значение, то при отсутствии возвращающегося значения возвращается экземпляр типа Unit. Явным образом его можно задать как `()`, он не несет какой-либо информации. + +Вы можете создать экземпляр класса, используя ключевое слово `new`. + +{% tabs greeter-usage class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-usage %} + +```scala mdoc:nest +val greeter = new Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` + +{% endtab %} + +{% tab 'Scala 3' for=greeter-usage %} + +```scala +val greeter = Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` + +{% endtab %} + +{% endtabs %} + +Позже мы рассмотрим классы [подробнее](classes.html). + +## Классы-образцы (Case Class) + +В Scala есть специальный тип класса, который называется классом-образцом (case class). По умолчанию такие классы неизменны и сравниваются по значению из конструктора. Вы можете объявлять классы-образцы с помощью ключевых слов `case class`. + +{% tabs case-class-definition %} +{% tab 'Scala 2 и 3' for=case-class-definition %} + +```scala mdoc +case class Point(x: Int, y: Int) +``` + +{% endtab %} +{% endtabs %} + +Можно создавать экземпляры класса-образца без использования ключевого слова `new`. + +{% tabs case-class-creation %} +{% tab 'Scala 2 и 3' for=case-class-creation %} + +```scala mdoc +val point = Point(1, 2) +val anotherPoint = Point(1, 2) +val yetAnotherPoint = Point(2, 2) +``` + +{% endtab %} +{% endtabs %} + +Они сравниваются по значению. + +{% tabs compare-case-class-equality class=tabs-scala-version %} + +{% tab 'Scala 2' for=compare-case-class-equality %} + +```scala mdoc +if (point == anotherPoint) { + println(s"$point and $anotherPoint are the same.") +} else { + println(s"$point and $anotherPoint are different.") +} // Point(1,2) и Point(1,2) одни и те же. + +if (point == yetAnotherPoint) { + println(s"$point and $yetAnotherPoint are the same.") +} else { + println(s"$point and $yetAnotherPoint are different.") +} // Point(1,2) и Point(2,2) разные. +``` + +{% endtab %} + +{% tab 'Scala 3' for=compare-case-class-equality %} + +```scala +if point == anotherPoint then + println(s"$point and $anotherPoint are the same.") +else + println(s"$point and $anotherPoint are different.") +// Point(1,2) и Point(1,2) одни и те же. + +if point == yetAnotherPoint then + println(s"$point and $yetAnotherPoint are the same.") +else + println(s"$point and $yetAnotherPoint are different.") +// Point(1,2) и Point(2,2) разные. +``` + +{% endtab %} + +{% endtabs %} + +Есть еще много деталей, которые мы бы хотели рассказать про классы-образцы; мы уверены, что вы влюбитесь в них! Обязательно рассмотрим их [позже](case-classes.html). + +## Объекты + +Объекты задаются и существуют в единственном экземпляре. Вы можете думать о них как об одиночках (синглтонах) своего собственного класса. + +Вы можете задать объекты при помощи ключевого слова `object`. + +{% tabs id-factory-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=id-factory-definition %} + +```scala mdoc +object IdFactory { + private var counter = 0 + def create(): Int = { + counter += 1 + counter + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=id-factory-definition %} + +```scala +object IdFactory: + private var counter = 0 + def create(): Int = + counter += 1 + counter +``` + +{% endtab %} + +{% endtabs %} + +Вы можете сразу получить доступ к объекту, ссылаясь на его имя. + +{% tabs id-factory-usage %} +{% tab 'Scala 2 и 3' for=id-factory-usage %} + +```scala mdoc +val newId: Int = IdFactory.create() +println(newId) // 1 +val newerId: Int = IdFactory.create() +println(newerId) // 2 +``` + +{% endtab %} +{% endtabs %} + +Позже мы рассмотрим объекты [подробнее](singleton-objects.html). + +## Трейты + +Трейты — как типы описывают характеристики классов, в нем могут объявляться определенные поля и методы. Трейты можно комбинировать. + +Объявить трейт можно с помощью ключевого слова `trait`. + +{% tabs greeter-trait-def class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-trait-def %} + +```scala mdoc:nest +trait Greeter { + def greet(name: String): Unit +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def %} + +```scala +trait Greeter: + def greet(name: String): Unit +``` + +{% endtab %} + +{% endtabs %} + +Трейты также могут иметь реализации методов и полей, которые предполагается использовать умолчанию. + +{% tabs greeter-trait-def-impl class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-trait-def-impl %} + +```scala mdoc:reset +trait Greeter { + def greet(name: String): Unit = + println("Hello, " + name + "!") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def-impl %} + +```scala +trait Greeter: + def greet(name: String): Unit = + println("Hello, " + name + "!") +``` + +{% endtab %} + +{% endtabs %} + +Вы можете наследовать свойства трейтов, используя ключевое слово `extends` и переопределять реализацию с помощью ключевого слова `override`. + +{% tabs greeter-implementations class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-implementations %} + +```scala mdoc +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { + override def greet(name: String): Unit = { + println(prefix + name + postfix) + } +} + +val greeter = new DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = new CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` + +{% endtab %} + +{% tab 'Scala 3' for=greeter-implementations %} + +```scala +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter: + override def greet(name: String): Unit = + println(prefix + name + postfix) + +val greeter = DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` + +{% endtab %} + +{% endtabs %} + +Здесь `DefaultGreeter` наследуется только от одного трейта, но можно наследоваться от нескольких. + +Позже мы рассмотрим трейты [подробнее](traits.html). + +## Главный метод + +Главный метод является отправной точкой в программе. +Для Виртуальной Машины Java требуется, чтобы главный метод назывался `main` и принимал один аргумент, массив строк. + +Используя объект, можно задать главный метод следующим образом: + +{% tabs hello-world-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-demo %} + +In Scala 2 you must define a main method manually. Using an object, you can define the main method as follows: + +```scala mdoc +object Main { + def main(args: Array[String]): Unit = + println("Hello, Scala developer!") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} + +In Scala 3, with the `@main` annotation, a main method is automatically generated from a method as follows: + +```scala +@main def hello() = println("Hello, Scala developer!") +``` + +{% endtab %} + +{% endtabs %} + +## Дополнительные ресурсы + +- Обзор [Scala book](/ru/scala3/book/taste-intro.html) diff --git a/_ru/tour/by-name-parameters.md b/_ru/tour/by-name-parameters.md new file mode 100644 index 0000000000..06c9a32063 --- /dev/null +++ b/_ru/tour/by-name-parameters.md @@ -0,0 +1,69 @@ +--- +layout: tour +title: Вызов по имени +partof: scala-tour +num: 31 +language: ru +next-page: annotations +previous-page: operators +--- + +_Вызов параметров по имени_ - это когда значение параметра вычисляется только в момент вызова параметра. Этот способ противоположен _вызову по значению_. Чтоб вызов параметра был по имени, необходимо просто указать `=>` перед его типом. + +{% tabs by-name-parameters_1 %} +{% tab 'Scala 2 и 3' for=by-name-parameters_1 %} + +```scala mdoc +def calculate(input: => Int) = input * 37 +``` + +{% endtab %} +{% endtabs %} + +Преимущество вызова параметров по имени заключается в том, что они не вычисляются если не используются в теле функции. С другой стороны плюсы вызова параметров по значению в том, что они вычисляются только один раз. + +Вот пример того, как мы можем реализовать условный цикл: + +{% tabs by-name-parameters_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=by-name-parameters_2 %} + +```scala mdoc +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if (condition) { + body + whileLoop(condition)(body) + } + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // выведет 2 1 +``` + +{% endtab %} +{% tab 'Scala 3' for=by-name-parameters_2 %} + +```scala +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if condition then + body + whileLoop(condition)(body) + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // выведет 2 1 +``` + +{% endtab %} +{% endtabs %} + +Метод `whileLoop` использует несколько списков параметров - условие и тело цикла. Если `condition` является верным, выполняется `body`, а затем выполняется рекурсивный вызов whileLoop. Если `condition` является ложным, то тело никогда не вычисляется, тк у нас стоит `=>` перед типом `body`. + +Теперь, когда мы передаем `i > 0` как наше условие `condition` и `println(i); i-= 1` как тело `body`, код ведет себя также как обычный цикл в большинстве языков программирования. + +Такая возможность откладывать вычисления параметра до его использования может помочь повысить производительность, отсекая не нужные вычисления при определенных условиях. diff --git a/_ru/tour/case-classes.md b/_ru/tour/case-classes.md new file mode 100644 index 0000000000..467fc0655e --- /dev/null +++ b/_ru/tour/case-classes.md @@ -0,0 +1,105 @@ +--- +layout: tour +title: Классы Образцы +partof: scala-tour +num: 11 +language: ru +next-page: pattern-matching +previous-page: multiple-parameter-lists +prerequisite-knowledge: classes, basics, mutability +--- + +Классы образцы (Case classes) похожи на обычные классы с несколькими ключевыми отличиями, о которых мы поговорим ниже. +Классы образцы хороши для моделирования неизменяемых данных. +На следующей странице обзора вы увидите, насколько они полезны для участия в [сопоставлении с примером](pattern-matching.html). + +## Объявление класса образца + +Минимальный вариант объявления класса образца: указание ключевого слова `case class`, название и список параметров (которые могут быть пустыми). Пример: + +{% tabs case-classe_Book %} + +{% tab 'Scala 2 и 3' for=case-classe_Book %} + +```scala mdoc +case class Book(isbn: String) + +val frankenstein = Book("978-0486282114") +``` + +{% endtab %} + +{% endtabs %} + +Обратите внимание, что ключевое слово `new` не было использовано для создания экземпляра класса `Book`. +Это связано с тем, что классы образцы по умолчанию имеют объект компаньон с методом `apply`, +который берет на себя заботу о создании экземпляра класса. + +При создании класса образца с параметрами, эти параметры являются публичными и неизменяемыми. + +{% tabs case-classe_Message_define %} + +{% tab 'Scala 2 и 3' for=case-classe_Message_define %} + +``` +case class Message(sender: String, recipient: String, body: String) +val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") + +println(message1.sender) // печатает guillaume@quebec.ca +message1.sender = "travis@washington.us" // эта строка не компилируется +``` + +{% endtab %} + +{% endtabs %} + +Вы не можете переназначить `message1.sender`, потому что это `val` (т.е. константа). Возможно использовать `var` в классах образцах, но это не рекомендуется. + +## Сравнение + +Классы образцы сравниваются по структуре, а не по ссылкам: + +{% tabs case-classe_Message_compare %} + +{% tab 'Scala 2 и 3' for=case-classe_Message_compare %} + +```scala mdoc +case class Message(sender: String, recipient: String, body: String) + +val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val messagesAreTheSame = message2 == message3 // true +``` + +{% endtab %} + +{% endtabs %} + +Даже если `message2` и `message3` ссылаются на разные объекты, значения каждого из них равны. + +## Копирование + +Вы можете создать копию экземпляра класса образца, просто воспользовавшись методом `copy`. При этом по желанию можно изменить аргументы конструктора. + +{% tabs case-classe_Message_copy %} + +{% tab 'Scala 2 и 3' for=case-classe_Message_copy %} + +``` +case class Message(sender: String, recipient: String, body: String) +val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") +val message5 = message4.copy(sender = message4.recipient, recipient = "claire@bourgogne.fr") +message5.sender // travis@washington.us +message5.recipient // claire@bourgogne.fr +message5.body // "Me zo o komz gant ma amezeg" +``` + +{% endtab %} + +{% endtabs %} + +Получатель `message4` использует в качестве отправителя `message5`, кроме параметра `body` который был скопирован из `message4`. + +## Дополнительные ресурсы + +- Дополнительная информация о классах образцах доступна в [Scala Book](/ru/scala3/book/domain-modeling-tools.html#case-class-ы) diff --git a/_ru/tour/classes.md b/_ru/tour/classes.md new file mode 100644 index 0000000000..75701bb107 --- /dev/null +++ b/_ru/tour/classes.md @@ -0,0 +1,289 @@ +--- +layout: tour +title: Классы +partof: scala-tour +num: 4 +language: ru +next-page: traits +previous-page: unified-types +topics: classes +prerequisite-knowledge: no-return-keyword, type-declaration-syntax, string-interpolation, procedures +--- + +Классы в Scala являются основами для создания объектов. Они могут содержать методы, константы, переменные, типы, объекты, трейты и классы, которые в совокупности называются _членами_. Типы, объекты и трейты будут рассмотрены позже в ходе нашего обзора. + +## Объявление класса + +Минимальное объявление класса - это просто ключевое слово `class` и его имя. Имена классов должны быть написаны с заглавной буквы. + +{% tabs class-minimal-user class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-minimal-user %} + +```scala mdoc +class User + +val user1 = new User +``` + +Ключевое слово `new` используется для создания экземпляра класса. +{% endtab %} + +{% tab 'Scala 3' for=class-minimal-user %} + +```scala +class User + +val user1 = User() +``` + +Чтобы создать экземпляр класса, мы вызываем его как функцию: `User()`. +Также можно явно использовать ключевое слово `new`: `new User()` - хотя обычно это опускается. +{% endtab %} + +{% endtabs %} + +`User` имеет конструктор по умолчанию, который не принимает аргументов, так как конструктор не был определен. Однако обычно используется и конструктор, и тело класса. Пример объявления класса Point приведен ниже: + +{% tabs class-point-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-example %} + +```scala mdoc +class Point(var x: Int, var y: Int) { + + def move(dx: Int, dy: Int): Unit = { + x = x + dx + y = y + dy + } + + override def toString: String = + s"($x, $y)" +} + +val point1 = new Point(2, 3) +println(point1.x) // выводит 2 +println(point1) // выводит (2, 3) +``` + +{% endtab %} + +{% tab 'Scala 3' for=class-point-example %} + +```scala +class Point(var x: Int, var y: Int): + + def move(dx: Int, dy: Int): Unit = + x = x + dx + y = y + dy + + override def toString: String = + s"($x, $y)" +end Point + +val point1 = Point(2, 3) +println(point1.x) // выводит 2 +println(point1) // выводит (2, 3) +``` + +{% endtab %} + +{% endtabs %} + +В этом классе у `Point` есть четыре члена: переменные `x` и `y` и методы `move` и `toString`. +В отличие от многих других языков, основной конструктор находится в сигнатуре класса `(var x: Int, var y: Int)`. Метод `move` принимает два целочисленных аргумента и возвращает значение Unit `()` - это пустое множество, которое не содержит никакой информации. Примерно соответствует `void` в Java-подобных языках. С другой стороны, `toString` не принимает никаких аргументов, а возвращает значение `String`. Поскольку `toString` переопределяет `toString` из [`AnyRef`](unified-types.html), он помечается ключевым словом `override`. + +## Конструкторы + +Конструкторы могут иметь необязательные параметры, если указать их значения по умолчанию как в примере: + +{% tabs class-point-with-default-values class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-with-default-values %} + +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) + +val origin = new Point // x и y оба равны 0 +val point1 = new Point(1) // x равен 1, а y равен 0 +println(point1) // выводит (1, 0) +``` + +{% endtab %} + +{% tab 'Scala 3' for=class-point-with-default-values %} + +```scala +class Point(var x: Int = 0, var y: Int = 0) + +val origin = Point() // x и y оба равны 0 +val point1 = Point(1) // x равен 1, а y равен 0 +println(point1) // выводит (1, 0) +``` + +{% endtab %} + +{% endtabs %} + +В этой версии класса `Point`, `x` и `y` имеют значение по умолчанию `0`, поэтому аргументов не требуется. Однако, поскольку конструктор считывает аргументы слева направо, если вы просто хотите передать значение `y`, то вам нужно будет указать задаваемый параметр. + +{% tabs class-point-named-argument class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-named-argument %} + +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) +val point2 = new Point(y = 2) +println(point2) // выводит (0, 2) +``` + +{% endtab %} + +{% tab 'Scala 3' for=class-point-named-argument %} + +```scala +class Point(var x: Int = 0, var y: Int = 0) +val point2 = Point(y = 2) +println(point2) // выводит (0, 2) +``` + +{% endtab %} + +{% endtabs %} + +Что также является хорошей практикой для повышения ясности кода. + +## Скрытые члены и синтаксис Геттер/Сеттер (получатель/установщик значений) + +По умолчанию члены класса являются открытыми для внешнего доступа (публичными). Используйте модификатор `private`, чтобы скрыть их от внешнего доступа. + +{% tabs class-point-private-getter-setter class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-private-getter-setter %} + +```scala mdoc:reset +class Point { + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x: Int = _x + def x_=(newValue: Int): Unit = { + if (newValue < bound) + _x = newValue + else + printWarning() + } + + def y: Int = _y + def y_=(newValue: Int): Unit = { + if (newValue < bound) + _y = newValue + else + printWarning() + } + + private def printWarning(): Unit = + println("WARNING: Out of bounds") +} + +val point1 = new Point +point1.x = 99 +point1.y = 101 // выводит предупреждение (printWarning) +``` + +{% endtab %} + +{% tab 'Scala 3' for=class-point-private-getter-setter %} + +```scala +class Point: + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x: Int = _x + def x_=(newValue: Int): Unit = + if newValue < bound then + _x = newValue + else + printWarning() + + def y: Int = _y + def y_=(newValue: Int): Unit = + if newValue < bound then + _y = newValue + else + printWarning() + + private def printWarning(): Unit = + println("WARNING: Out of bounds") +end Point + +val point1 = Point() +point1.x = 99 +point1.y = 101 // выводит предупреждение (printWarning) +``` + +{% endtab %} + +{% endtabs %} + +В данной версии класса `Point` данные хранятся в скрытых переменных `_x` и `_y`. Существуют методы `def x` и `def y` для доступа к скрытым данным. Методы `def x_=` и `def y_=` (сеттеры) предназначены для проверки и установки значения `_x` и `_y`. Обратите внимание на специальный синтаксис для сеттеров: метод `_=` применяется к имени геттера. + +Первичные параметры конструктора с параметрами `val` и `var` являются общедоступными. Однако, поскольку `val` - это константа, то нельзя писать следующее. + +{% tabs class-point-cannot-set-val class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-cannot-set-val %} + +```scala mdoc:fail +class Point(val x: Int, val y: Int) +val point = new Point(1, 2) +point.x = 3 // <-- не компилируется +``` + +{% endtab %} + +{% tab 'Scala 3' for=class-point-cannot-set-val %} + +```scala +class Point(val x: Int, val y: Int) +val point = Point(1, 2) +point.x = 3 // <-- не компилируется +``` + +{% endtab %} + +{% endtabs %} + +Параметры без `val` или `var` являются скрытыми от внешнего доступа и видимы только внутри класса. + +{% tabs class-point-non-val-ctor-param class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-non-val-ctor-param %} + +```scala mdoc:fail +class Point(x: Int, y: Int) +val point = new Point(1, 2) +point.x // <-- не компилируется +``` + +{% endtab %} + +{% tab 'Scala 3' for=class-point-non-val-ctor-param %} + +```scala +class Point(x: Int, y: Int) +val point = Point(1, 2) +point.x // <-- не компилируется +``` + +{% endtab %} + +{% endtabs %} + +## Дополнительные ресурсы + +- Узнайте больше о классах в [Scala Book](/ru/scala3/book/domain-modeling-tools.html#классы) +- Как использовать [вспомогательные конструкторы классов](/ru/scala3/book/domain-modeling-tools.html#вспомогательные-конструкторы) diff --git a/_ru/tour/compound-types.md b/_ru/tour/compound-types.md new file mode 100644 index 0000000000..876bbaf42a --- /dev/null +++ b/_ru/tour/compound-types.md @@ -0,0 +1,104 @@ +--- +layout: tour +title: Составные Типы +partof: scala-tour +num: 24 +language: ru +next-page: self-types +previous-page: abstract-type-members +--- + +Иногда необходимо выразить, то что тип объекта является подтипом нескольких других типов. + +В Scala это можно выразить с помощью _типов пересечений_ (или _составных типов_ в Scala 2), +которые являются объединением нескольких типов объектов. + +Предположим, у нас есть два трейта: `Cloneable` и `Resetable`: + +{% tabs compound-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_1 %} + +```scala mdoc +trait Cloneable extends java.lang.Cloneable { + override def clone(): Cloneable = { // создает публичный метод 'clone' + super.clone().asInstanceOf[Cloneable] + } +} +trait Resetable { + def reset: Unit +} +``` + +{% endtab %} +{% tab 'Scala 3' for=compound-types_1 %} + +```scala +trait Cloneable extends java.lang.Cloneable: + override def clone(): Cloneable = // создает публичный метод 'clone' + super.clone().asInstanceOf[Cloneable] +trait Resetable: + def reset: Unit +``` + +{% endtab %} +{% endtabs %} + +Теперь предположим, что мы хотим написать функцию `cloneAndReset`, которая берет объект, клонирует его и сбрасывает (Reset) состояние исходного объекта: + +{% tabs compound-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_2 %} + +```scala mdoc:fail +def cloneAndReset(obj: ?): Cloneable = { + val cloned = obj.clone() + obj.reset + cloned +} +``` + +{% endtab %} +{% tab 'Scala 3' for=compound-types_2 %} + +```scala +def cloneAndReset(obj: ?): Cloneable = + val cloned = obj.clone() + obj.reset + cloned +``` + +{% endtab %} +{% endtabs %} + +Возникает вопрос, какой тип параметра `obj` должна принимать наша объединённая функция. Если это `Cloneable`, то объект может использовать метод `clone`, но не `reset`; если это `Resetable` мы можем использовать метод `reset`, но нет операции `clone`. Чтобы избежать приведения типа в такой ситуации, мы можем указать, что тип `obj` является и `Cloneable`, и `Resetable`. + +{% tabs compound-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_3 %} +Этот совместный тип в Scala записывается как: `Cloneable with Resetable`. + +Вот обновленная функция: + +```scala mdoc:fail +def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { + //... +} +``` + +Обратите внимание, что у вас может быть более двух типов: `A with B with C with ...`. +Это означает то же самое, что и: `(...(A with B) with C) with ... )` + +{% endtab %} +{% tab 'Scala 3' for=compound-types_3 %} +Этот совместный тип в Scala записывается как: `Cloneable & Resetable`. + +Вот обновленная функция: + +```scala +def cloneAndReset(obj: Cloneable & Resetable): Cloneable = { + //... +} +``` + +Обратите внимание, что у вас может быть более двух типов: `A & B & C & ...`. +`&` является ассоциативным, поэтому скобки могут быть добавлены вокруг любой части без изменения значения. +{% endtab %} +{% endtabs %} diff --git a/_ru/tour/default-parameter-values.md b/_ru/tour/default-parameter-values.md new file mode 100644 index 0000000000..c45b5dd419 --- /dev/null +++ b/_ru/tour/default-parameter-values.md @@ -0,0 +1,100 @@ +--- +layout: tour +title: Значения Параметров По умолчанию +partof: scala-tour +num: 33 +language: ru +next-page: named-arguments +previous-page: classes +prerequisite-knowledge: named-arguments, function syntax +--- + +Scala предоставляет возможность задавать значения параметров по умолчанию, что позволяет лишний раз не указывать параметры. + +{% tabs default-parameter-values-1 %} +{% tab 'Scala 2 и 3' for=default-parameter-values-1 %} + +```scala mdoc +def log(message: String, level: String = "INFO") = println(s"$level: $message") + +log("System starting") // выведет "INFO: System starting" +log("User not found", "WARNING") // выведет "WARNING: User not found" +``` + +{% endtab %} +{% endtabs %} + +У параметра `level` есть значение по умолчанию, поэтому он необязателен. В последней строке аргумент `"WARNING"` переназначает аргумент по умолчанию `"INFO"`. Вместо того чтоб использовать перегруженные методы в Java, вы можете просто указать дополнительные параметры как параметры по умолчанию для достижения того же эффекта. Однако, если при вызове пропущен хотя бы один аргумент, все остальные аргументы должны вызываться с указанием конкретного имени аргумента. + +{% tabs default-parameter-values-2 %} +{% tab 'Scala 2 и 3' for=default-parameter-values-2 %} + +```scala mdoc +class Point(val x: Double = 0, val y: Double = 0) + +val point1 = new Point(y = 1) +``` + +{% endtab %} +{% endtabs %} + +Так мы можем указать что `y = 1`. + +Обратите внимание, что параметры по умолчанию в Scala, при вызове из Java кода, являются обязательными: + +{% tabs default-parameter-values-3 %} +{% tab 'Scala 2 и 3' for=default-parameter-values-3 %} + +```scala mdoc:reset +// Point.scala +class Point(val x: Double = 0, val y: Double = 0) +``` + +{% endtab %} +{% endtabs %} + +{% tabs default-parameter-values-4 %} +{% tab 'Java' for=default-parameter-values-4 %} + +```java +// Main.java +public class Main { + public static void main(String[] args) { + Point point = new Point(1); // не скомпилируется + } +} +``` + +{% endtab %} +{% endtabs %} + +### Параметры по умолчанию для перегруженных методов + +Scala не позволяет определять два метода с параметрами по умолчанию и с одинаковым именем (перегруженные методы). +Важная причина этого - избежание двусмысленности, которая может быть вызвана наличием параметров по умолчанию. +Чтобы проиллюстрировать проблему, давайте рассмотрим определение методов, представленных ниже: + +{% tabs default-parameter-values-5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala mdoc:fail +object A { + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object A: + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +``` + +{% endtab %} +{% endtabs %} + +Если мы вызываем `A.func()`, компилятор не может узнать, +намеревался ли программист вызвать `func(x: Int = 34)` или `func(y: String = "abc")`. diff --git a/_ru/tour/extractor-objects.md b/_ru/tour/extractor-objects.md new file mode 100644 index 0000000000..f93981cd6c --- /dev/null +++ b/_ru/tour/extractor-objects.md @@ -0,0 +1,114 @@ +--- +layout: tour +title: Объект Экстрактор +partof: scala-tour +num: 16 +language: ru +next-page: for-comprehensions +previous-page: regular-expression-patterns +--- + +Объект Экстрактор (объект распаковщик или extractor object) - это объект с методом `unapply`. В то время как метод `apply` обычно действует как конструктор, который принимает аргументы и создает объект, метод `unapply` действует обратным образом, он принимает объект и пытается извлечь и вернуть аргументы из которых он (возможно) был создан. Чаще всего этот метод используется в функциях сопоставления с примером и в частично определенных функциях. + +{% tabs extractor-objects_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=extractor-objects_definition %} + +```scala mdoc +import scala.util.Random + +object CustomerID { + + def apply(name: String) = s"$name--${Random.nextLong()}" + + def unapply(customerID: String): Option[String] = { + val stringArray: Array[String] = customerID.split("--") + if (stringArray.tail.nonEmpty) Some(stringArray.head) else None + } +} + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match { + case CustomerID(name) => println(name) // выведет Sukyoung + case _ => println("Could not extract a CustomerID") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=extractor-objects_definition %} + +```scala +import scala.util.Random + +object CustomerID: + + def apply(name: String) = s"$name--${Random.nextLong()}" + + def unapply(customerID: String): Option[String] = + val stringArray: Array[String] = customerID.split("--") + if stringArray.tail.nonEmpty then Some(stringArray.head) else None + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match + case CustomerID(name) => println(name) // выведет Sukyoung + case _ => println("Could not extract a CustomerID") +``` + +{% endtab %} + +{% endtabs %} + +Метод `apply` создает `CustomerID` из строки `name`. `unapply` делает обратное, чтобы вернуть `name` обратно. Когда мы вызываем `CustomerID("Sukyoung")`, это сокращенный синтаксис вызова `CustomerID.apply("Sukyoung")`. Когда мы вызываем `case CustomerID(name) => println(name)`, мы на самом деле вызываем метод `unapply`. + +При объявлении нового значения можно использовать пример, в котором значение для инициализации переменной получается через извлечение, используя метод `unapply`. + +{% tabs extractor-objects_use-case-1 %} + +{% tab 'Scala 2 и 3' for=extractor-objects_use-case-1 %} + +```scala mdoc +val customer2ID = CustomerID("Nico") +val CustomerID(name) = customer2ID +println(name) // выведет Nico +``` + +{% endtab %} + +{% endtabs %} + +Что эквивалентно `val name = CustomerID.unapply(customer2ID).get`. + +{% tabs extractor-objects_use-case-2 %} + +{% tab 'Scala 2 и 3' for=extractor-objects_use-case-2 %} + +```scala mdoc +val CustomerID(name2) = "--asdfasdfasdf" +``` + +{% endtab %} + +{% endtabs %} + +Если совпадений нет, то бросается `scala.MatchError`: + +{% tabs extractor-objects_use-case-3 %} + +{% tab 'Scala 2 и 3' for=extractor-objects_use-case-3 %} + +```scala mdoc:crash +val CustomerID(name3) = "-asdfasdfasdf" +``` + +{% endtab %} + +{% endtabs %} + +Возвращаемый тип `unapply` выбирается следующим образом: + +- Если это всего лишь тест, возвращается `Boolean`. Например `case even()`. +- Если в результате найдено одно значение типа `T`, то возвращается `Option[T]`. +- Если вы хотите получить несколько значений `T1,..., Tn`, то ответ необходимо группировать в дополнительный кортеж `Option[(T1,..., Tn)]`. + +Иногда количество извлекаемых значений не является фиксированным. Если в зависимости от входа мы хотим вернуть произвольное количество значений, то для этого случая мы можем определить экстрактор методом `unapplySeq`, который возвращает `Option[Seq[T]]`. Характерным примером такого подхода является разложение `List` с помощью `case List(x, y, z) =>` и разложение `String` с помощью регулярного выражения `Regex`, такого как `case r(name, remainingFields @ _*) =>`. diff --git a/_ru/tour/for-comprehensions.md b/_ru/tour/for-comprehensions.md new file mode 100644 index 0000000000..8f6ae91bba --- /dev/null +++ b/_ru/tour/for-comprehensions.md @@ -0,0 +1,132 @@ +--- +layout: tour +title: Сложные for-выражения +partof: scala-tour +num: 17 +language: ru +next-page: generic-classes +previous-page: extractor-objects +--- + +Scala предлагает простую запись для выражения _последовательных преобразований_. Эти преобразования можно упростить используя специальный синтаксис `for выражения` (for comprehension), который записывается как `for (enumerators) yield e`, где `enumerators` относятся к списку перечислителей, разделенных точкой с запятой. Где отдельный такой "перечислитель" (_enumerator_) является либо генератором, который вводит новые переменные, либо фильтром. For-выражение вычисляет тело `e` (которое связанно с тем что генерирует _enumerator_) и возвращает последовательность вычислений. + +Вот пример: + +{% tabs for-comprehensions-01 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-01 %} + +```scala mdoc +case class User(name: String, age: Int) + +val userBase = List( + User("Travis", 28), + User("Kelly", 33), + User("Jennifer", 44), + User("Dennis", 23)) + +val twentySomethings = + for (user <- userBase if user.age >=20 && user.age < 30) + yield user.name // т. е. добавить результат к списку + +twentySomethings.foreach(println) // выводит "Travis Dennis" +``` + +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-01 %} + +```scala +case class User(name: String, age: Int) + +val userBase = List( + User("Travis", 28), + User("Kelly", 33), + User("Jennifer", 44), + User("Dennis", 23)) + +val twentySomethings = + for user <- userBase if user.age >=20 && user.age < 30 + yield user.name // т. е. добавить результат к списку + +twentySomethings.foreach(println) // выводит "Travis Dennis" +``` + +{% endtab %} +{% endtabs %} + +`for`-выражение, используется с оператором `yield`, на самом деле создает `List`. Потому что мы указали `yield user.name` (то есть вывести имя пользователя), получаем `List[String]`. `user <- userBase` и есть наш генератор, а `if (user.age >=20 && user.age < 30)` - это фильтр который отфильтровывает пользователей, не достигших 30-летнего возраста. + +Ниже приведен более сложный пример использования двух генераторов. Он вычисляет все пары чисел между `0` и `n-1`, сумма которых равна заданному значению `v`: + +{% tabs for-comprehensions-02 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-02 %} + +```scala mdoc +def foo(n: Int, v: Int) = + for (i <- 0 until n; + j <- 0 until n if i + j == v) + yield (i, j) + +foo(10, 10).foreach { + case (i, j) => + println(s"($i, $j) ") // выводит (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-02 %} + +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + yield (i, j) + +foo(10, 10).foreach { + (i, j) => println(s"($i, $j) ") // выводит (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) +} +``` + +{% endtab %} +{% endtabs %} + +Здесь `n == 10` и `v == 10`. На первой итерации `i == 0` и `j == 0` так `i + j != v` и поэтому ничего не выдается. `j` увеличивается еще в 9 раз, прежде чем `i` увеличивается до `1`. Без фильтра `if` будет просто напечатано следующее: + +```scala +(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... +``` + +Обратите внимание, что for-выражение не ограничивается только работой со списками. Каждый тип данных, поддерживающий операции `withFilter`, `map`, and `flatMap` (с соответствующими типами), может быть использован в for-выражении. + +Вы можете обойтись без `yield` в for-выражении. В таком случае, результатом будет `Unit`. Это может быть полезным для выполнения кода основанного на побочных эффектах. Вот программа, эквивалентная предыдущей, но без использования `yield`: + +{% tabs for-comprehensions-03 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-03 %} + +```scala mdoc:nest +def foo(n: Int, v: Int) = + for (i <- 0 until n; + j <- 0 until n if i + j == v) + println(s"($i, $j)") + +foo(10, 10) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-comprehensions-03 %} + +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + do println(s"($i, $j)") + +foo(10, 10) +``` + +{% endtab %} +{% endtabs %} + +## Дополнительные ресурсы + +- Другие примеры "For comprehension" доступны [в книге Scala](/ru/scala3/book/control-structures.html#выражение-for) diff --git a/_ru/tour/generic-classes.md b/_ru/tour/generic-classes.md new file mode 100644 index 0000000000..591f810cfd --- /dev/null +++ b/_ru/tour/generic-classes.md @@ -0,0 +1,124 @@ +--- +layout: tour +title: Обобщенные Классы +partof: scala-tour +num: 18 +language: ru +next-page: variances +previous-page: for-comprehensions +assumed-knowledge: classes unified-types +--- + +Обобщенные классы (Generic classes) - это классы, обладающие параметрическим полиморфизмом (т. е. классы, которые изменяют свое поведение в зависимости от приписываемого им типа. Этот тип указывается в квадратных скобках `[]` сразу после имени класса). Они особенно полезны для создания коллекций. + +## Объявление обобщенного класса + +Для объявления обобщенного класса необходимо после имени добавить тип в квадратных скобках `[]` как еще один параметр класса. По соглашению обычно используют заглавные буквы `A`, хотя можно использовать любые имена. + +{% tabs generic-classes-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-1 %} + +```scala mdoc +class Stack[A] { + private var elements: List[A] = Nil + def push(x: A): Unit = + elements = x :: elements + def peek: A = elements.head + def pop(): A = { + val currentTop = peek + elements = elements.tail + currentTop + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=generic-classes-1 %} + +```scala +class Stack[A]: + private var elements: List[A] = Nil + def push(x: A): Unit = + elements = x :: elements + def peek: A = elements.head + def pop(): A = + val currentTop = peek + elements = elements.tail + currentTop +``` + +{% endtab %} +{% endtabs %} + +Данная реализация класса `Stack` принимает в качестве параметра любой тип `A`. Это означает что список, `var elements: List[A] = Nil`, может хранить только элементы типа `A`. Процедура `def push` принимает только объекты типа `A` (примечание: `elements = x :: elements` переназначает `elements` в новый список, созданный путем добавления `x` к текущим `elements`). + +Здесь `Nil` — это пустой `List`, и его не следует путать с `null`. + +## Использование + +Чтобы использовать обобщенный класс, поместите конкретный тип в квадратные скобки вместо `A`. + +{% tabs generic-classes-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-2 %} + +```scala mdoc +val stack = new Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // выведет 2 +println(stack.pop()) // выведет 1 +``` + +{% endtab %} +{% tab 'Scala 3' for=generic-classes-2 %} + +```scala +val stack = Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // выведет 2 +println(stack.pop()) // выведет 1 +``` + +{% endtab %} +{% endtabs %} + +Экземпляр `stack` может принимать элементы типа `Int`. Однако, если тип имеет подтипы, то они также могут быть приняты: + +{% tabs generic-classes-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-3 %} + +```scala mdoc:nest +class Fruit +class Apple extends Fruit +class Banana extends Fruit + +val stack = new Stack[Fruit] +val apple = new Apple +val banana = new Banana + +stack.push(apple) +stack.push(banana) +``` + +{% endtab %} +{% tab 'Scala 3' for=generic-classes-3 %} + +```scala +class Fruit +class Apple extends Fruit +class Banana extends Fruit + +val stack = Stack[Fruit] +val apple = Apple() +val banana = Banana() + +stack.push(apple) +stack.push(banana) +``` + +{% endtab %} +{% endtabs %} +Классы `Apple` и `Banana` наследуются от `Fruit` так, что мы можем засунуть экземпляры `Apple` и `Banana` в пачку `Fruit`. + +_Примечание: подтипы обобщенных типов - *инвариантны*. Это означает, что если у нас есть стэк символов типа `Stack[Char]`, то он не может быть использован как стек интов типа `Stack[Int]`. Это нежелательное поведение, потому как позволило бы нам добавлять в стек символов целые числа. В заключение, `Stack[A]` является подтипом `Stack[B]` тогда и только тогда, когда `B = A`. Поскольку это может быть довольно строгим ограничением, Scala предлагает [механизм вариативного описания параметров типа](variances.html) для контроля за поведением подтипов._ diff --git a/_ru/tour/higher-order-functions.md b/_ru/tour/higher-order-functions.md new file mode 100644 index 0000000000..b55b4d9b24 --- /dev/null +++ b/_ru/tour/higher-order-functions.md @@ -0,0 +1,242 @@ +--- +layout: tour +title: Функции Высшего Порядка +partof: scala-tour +num: 8 +language: ru +next-page: nested-functions +previous-page: mixin-class-composition +--- + +Функции высшего порядка могут принимать другие функции в качестве параметров или возвращать функцию в качестве результата. +Такое возможно поскольку функции являются объектами первого класса в Scala. +На текущем этапе терминология может казаться немного запутанной, мы используем следующую фразу "функция высшего порядка" как для методов, так и для функций, которые могут принимать другие функции в качестве параметров, или возвращать функции в качестве результата. + +В чисто объектно-ориентированном мире рекомендуется избегать раскрытия методов, +параметризованных функциями, которые могут привести к утечке внутреннего состояния объекта. +Утечка внутреннего состояния может нарушить инварианты самого объекта, тем самым нарушив инкапсуляцию. + +Одним из наиболее распространенных примеров функции высшего порядка +является функция `map`, которая доступна в коллекциях Scala. + +{% tabs map_example_1 %} + +{% tab 'Scala 2 и 3' for=map_example_1 %} + +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) +val doubleSalary = (x: Int) => x * 2 +val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) +``` + +{% endtab %} + +{% endtabs %} + +`doubleSalary` - это функция, которая принимает один Int `x` и возвращает `x * 2`. В общем случае, кортеж (список имен в скобках) слева от стрелки `=>` - это список параметров, а значение выражения следует справа. Это же значение возвращается в качестве результата. В строке 3 к каждому элементу списка зарплат (salaries) применяется функция `doubleSalary`. + +Чтобы сократить код, мы можем сделать функцию анонимной и передать ее напрямую в качестве аргумента в map: + +{% tabs map_example_2 %} + +{% tab 'Scala 2 и 3' for=map_example_2 %} + +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) +val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) +``` + +{% endtab %} + +{% endtabs %} + +Обратите внимание, что в приведенном выше примере `x`не объявлен как `Int`. Это потому, что компилятор может вывести тип, основываясь на типе который ожидает функция map. Еще более элегантным способом написания этого же кода было бы таким: + +{% tabs map_example_3 %} + +{% tab 'Scala 2 и 3' for=map_example_3 %} + +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) +val newSalaries = salaries.map(_ * 2) +``` + +{% endtab %} + +{% endtabs %} + +Поскольку компилятор Scala уже знает тип параметров (Int), вам нужно только указать правую часть функции. Единственное условие заключается в том, что вместо имени параметра необходимо использовать `_` (в предыдущем примере это было `x`). + +## Преобразование методов в функции + +Также возможно передавать методы в качестве аргументов функциям более высокого порядка, поскольку компилятор Scala может преобразовать метод в функцию. + +{% tabs Coercing_methods_into_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Coercing_methods_into_functions %} + +```scala mdoc +case class WeeklyWeatherForecast(temperatures: Seq[Double]) { + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- передается метод convertCtoF +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=Coercing_methods_into_functions %} + +```scala +case class WeeklyWeatherForecast(temperatures: Seq[Double]): + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- передается метод convertCtoF +``` + +{% endtab %} + +{% endtabs %} + +Здесь метод `convertCtoF` передается в `forecastInFahrenheit`. Это возможно, потому что компилятор преобразовывает `convertCtoF` в функцию `x => ConvertCtoF(x)` (примечание: `x` будет сгенерированным именем, которое гарантированно будет уникальным в рамках своей области видимости). + +## Функции, которые принимают функции + +Одной из причин использования функций высшего порядка является сокращение избыточного кода. Допустим, вам нужны какие-то методы, которые могли бы повышать чью-то зарплату по разным условиям. Без создания функции высшего порядка это могло бы выглядеть примерно так: + +{% tabs Functions_that_accept_functions_1 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_1 %} + +```scala mdoc +object SalaryRaiser { + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_1 %} + +```scala +object SalaryRaiser: + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +``` + +{% endtab %} + +{% endtabs %} + +Обратите внимание, что каждый из этих трех методов отличается только коэффициентом умножения. Для упрощения можно перенести повторяющийся код в функцию высшего порядка: + +{% tabs Functions_that_accept_functions_2 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_2 %} + +```scala mdoc:nest +object SalaryRaiser { + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_2 %} + +```scala +object SalaryRaiser: + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +``` + +{% endtab %} + +{% endtabs %} + +Новый метод, `promotion`, берет зарплату и функцию типа `Double => Double` (т.е. функция, которая берет Double и возвращает Double) и возвращает их произведение. + +Методы и функции обычно выражают поведение или преобразование данных, поэтому наличие функций, +которые компонуются на основе других функций, может помочь в создании общих механизмов. +Эти типовые функции откладывают блокировку всего поведения операции, +предоставляя клиентам возможность контролировать или дополнительно настраивать части самой операции. +## Функции, возвращающие функции + +Есть определенные случаи, когда вы хотите сгенерировать функцию. Вот пример метода, который возвращает функцию. + +{% tabs Functions_that_return_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_return_functions %} + +```scala mdoc +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { + val schema = if (ssl) "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" +} + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` + +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_return_functions %} + +```scala +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = + val schema = if ssl then "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` + +{% endtab %} + +{% endtabs %} + +Обратите внимание, что возвращаемый тип urlBuilder`(String, String) => String`. Это означает, что возвращаемая анонимная функция принимает две строки и возвращает строку. В нашем случае возвращаемая анонимная функция `(endpoint: String, query: String) => s"https://www.example.com/$endpoint?$query"`. diff --git a/_ru/tour/implicit-conversions.md b/_ru/tour/implicit-conversions.md new file mode 100644 index 0000000000..5e3001862d --- /dev/null +++ b/_ru/tour/implicit-conversions.md @@ -0,0 +1,52 @@ +--- +layout: tour +title: Неявные Преобразования +partof: scala-tour +num: 27 +language: ru +next-page: polymorphic-methods +previous-page: implicit-parameters +--- + +Неявные преобразования — это мощная функция Scala, применяемая в двух распространенных вариантах: + +- разрешить пользователям предоставлять аргумент одного типа так, как если бы это был другой тип, чтобы избежать шаблонного. +- в Scala 2 для предоставления дополнительных членов запечатанным классам (заменены [методами расширения][exts] в Scala 3). + +### Детальный разбор + +{% tabs implicit-conversion-defn class=tabs-scala-version %} +{% tab 'Scala 2' %} + +В Scala 2 неявное преобразование из типа `S` в тип `T` определяется либо [неявным классом]({% link _overviews/core/implicit-classes.md %}) `T` +с одним параметром типа `S`, [неявным значением](implicit-parameters.html), которое имеет тип функции `S => T`, +либо неявным методом, преобразуемым в значение этого типа. + +{% endtab %} +{% tab 'Scala 3' %} + +В Scala 3 неявное преобразование из типа `S` в тип `T` определяется [экземпляром `given`](implicit-parameters.html), который имеет тип `scala.Conversion[S, T]`. +Для совместимости со Scala 2 их также можно определить неявным методом (подробнее читайте во вкладке Scala 2). + +{% endtab %} +{% endtabs %} + +Неявные преобразования применяются в двух случаях: + +1. Если выражение `e` имеет тип `S` и `S` не соответствует ожидаемому типу выражения `T`. +2. При выборе `e.m`, где `e` типа `S`, если селектор `m` не указывает на элемент `S`. + +В первом случае ищется конверсия `c`, применимая к `e` и тип результата которой соответствует `T`. + +Примером является передача `scala.Int`, например `x`, методу, который ожидает `scala.Long`. +В этом случае вставляется неявное преобразование `Int.int2long(x)`. + +Во втором случае ищется преобразование `c`, применимое к `e` и результат которого содержит элемент с именем `m`. + +Примером является сравнение двух строк `"foo" < "bar"`. +В этом случае `String` не имеет члена `<`, поэтому вставляется неявное преобразование `Predef.augmentString("foo") < "bar"` +(`scala.Predef` автоматически импортируется во все программы Scala). + +Дополнительная литература: [Неявные преобразования (в книге Scala)](/ru/scala3/book/ca-implicit-conversions.html). + +[exts]: /ru/scala3/book/ca-extension-methods.html diff --git a/_ru/tour/implicit-parameters.md b/_ru/tour/implicit-parameters.md new file mode 100644 index 0000000000..14f11c299c --- /dev/null +++ b/_ru/tour/implicit-parameters.md @@ -0,0 +1,111 @@ +--- +layout: tour +title: Контекстные параметры, также известные, как неявные параметры +partof: scala-tour +num: 26 +language: ru +next-page: implicit-conversions +previous-page: self-types +--- + +Метод может иметь список _контекстных параметров_ (_contextual parameters_), +также называемых _неявными параметрами_ (_implicit parameters_) или, точнее, _имплицитами_ (_implicits_). +Списки параметров, начинающиеся с ключевого слова `using` (или `implicit` в Scala 2), задают контекстные параметры. +Если сторона вызова явно не предоставляет аргументы для таких параметров, +Scala будет искать неявно доступные `given` (или `implicit` в Scala 2) значения правильного типа. +Если можно найти подходящие значения, то они автоматически передаются. + +Лучше всего вначале показать это на небольшом примере. +Мы определяем интерфейс `Comparator[A]`, который может сравнивать элементы типа `A`, +и предоставляем две реализации для `Int`-ов и `String`-ов. +Затем мы определяем метод `max[A](x: A, y: A)`, который возвращает больший из двух аргументов. +Так как `x` и `y` имеют абстрактный тип, в общем случае мы не знаем, как их сравнивать, но можем запросить соответствующий компаратор. +Поскольку обычно для любого заданного типа существует канонический компаратор `A`, +то мы можем объявить их как _заданные_ (_given_) или _неявно_ (_implicitly_) доступные. + +{% tabs implicits-comparator class=tabs-scala-version %} + +{% tab 'Scala 2' for=implicits-comparator %} + +```scala mdoc +trait Comparator[A] { + def compare(x: A, y: A): Int +} + +object Comparator { + implicit object IntComparator extends Comparator[Int] { + def compare(x: Int, y: Int): Int = Integer.compare(x, y) + } + + implicit object StringComparator extends Comparator[String] { + def compare(x: String, y: String): Int = x.compareTo(y) + } +} + +def max[A](x: A, y: A)(implicit comparator: Comparator[A]): A = + if (comparator.compare(x, y) >= 0) x + else y + +println(max(10, 6)) // 10 +println(max("hello", "world")) // world +``` + +```scala mdoc:fail +// не компилируется: +println(max(false, true)) +// ^ +// error: could not find implicit value for parameter comparator: Comparator[Boolean] +``` + +Параметр `comparator` автоматически заполняется значением `Comparator.IntComparator` для `max(10, 6)` +и `Comparator.StringComparator` для `max("hello", "world")`. +Поскольку нельзя найти неявный `Comparator[Boolean]`, вызов `max(false, true)` не компилируется. + +{% endtab %} + +{% tab 'Scala 3' for=implicits-comparator %} + +```scala +trait Comparator[A]: +def compare(x: A, y: A): Int + +object Comparator: +given Comparator[Int] with +def compare(x: Int, y: Int): Int = Integer.compare(x, y) + +given Comparator[String] with +def compare(x: String, y: String): Int = x.compareTo(y) +end Comparator + +def max[A](x: A, y: A)(using comparator: Comparator[A]): A = + if comparator.compare(x, y) >= 0 then x + else y + +println(max(10, 6)) // 10 +println(max("hello", "world")) // world +``` + +```scala +// не компилируется: +println(max(false, true)) +-- Error: ---------------------------------------------------------------------- +1 |println(max(false, true)) + | ^ + |no given instance of type Comparator[Boolean] was found for parameter comparator of method max +``` + +Параметр `comparator` автоматически заполняется значением `given Comparator[Int]` для `max(10, 6)` +и `given Comparator[String]` для `max("hello", "world")`. +Поскольку нельзя найти `given Comparator[Boolean]`, вызов `max(false, true)` не компилируется. + +{% endtab %} + +{% endtabs %} + +Места, где Scala будет искать эти параметры, делятся на две категории: + +- Вначале Scala будет искать `given` параметры, доступ к которым можно получить напрямую (без префикса) в месте вызова `max`. +- Затем он ищет членов, помеченных как given/implicit во всех объектах компаньонах, + связанных с типом неявного параметра (например: `object Comparator` для типа-кандидата `Comparator[Int]`). + +Более подробное руководство, о том где scala ищет неявные значения можно найти в [FAQ](/tutorials/FAQ/finding-implicits.html) diff --git a/_ru/tour/inner-classes.md b/_ru/tour/inner-classes.md new file mode 100644 index 0000000000..15a1a2882d --- /dev/null +++ b/_ru/tour/inner-classes.md @@ -0,0 +1,139 @@ +--- +layout: tour +title: Внутренние классы +partof: scala-tour +num: 22 +language: ru +next-page: abstract-type-members +previous-page: lower-type-bounds +--- + +В Scala классам можно иметь в качестве членов другие классы. В отличие от Java-подобных языков, где такие внутренние классы являются членами окружающего класса, в Scala такие внутренние классы привязаны к содержащему его объекту. Предположим, мы хотим, чтобы компилятор не позволял нам на этапе компиляции смешивать узлы этого графа. Для решения этой задачи нам подойдут типы, зависящие от своего расположения. + +Чтобы проиллюстрировать суть подхода, мы быстро набросаем реализацию такого графа: + +{% tabs inner-classes_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_1 %} + +```scala mdoc +class Graph { + class Node { + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes + } + } + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=inner-classes_1 %} + +```scala +class Graph: + class Node: + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` + +{% endtab %} +{% endtabs %} + +Данная программа представляет собой граф в составленного из списка узлов (`List[Node]`). Каждый узел имеет список других узлов, с которым он связан (`connectedNodes`). Класс `Node` является _зависимым от месторасположения типом_, поскольку он вложен в `Class Graph`. Поэтому все узлы в `connectedNodes` должны быть созданы с использованием `newNode` из одного и того же экземпляра `Graph`. + +{% tabs inner-classes_2 %} +{% tab 'Scala 2 и 3' for=inner-classes_2 %} + +```scala mdoc +val graph1: Graph = new Graph +val node1: graph1.Node = graph1.newNode +val node2: graph1.Node = graph1.newNode +val node3: graph1.Node = graph1.newNode +node1.connectTo(node2) +node3.connectTo(node1) +``` + +{% endtab %} +{% endtabs %} + +Мы явно объявили тип `node1`, `node2` и `node3` как `graph1.Node` для ясности, хотя компилятор мог определить это самостоятельно. Это потому, что когда мы вызываем `graph1.newNode`, вызывающий `new Node`, метод использует экземпляр `Node`, специфичный экземпляру `graph1`. + +Если у нас есть два графа, то система типов Scala не позволит смешивать узлы, определенные в рамках одного графа, с узлами другого, так как узлы другого графа имеют другой тип. +Вот некорректная программа: + +{% tabs inner-classes_3 %} +{% tab 'Scala 2 и 3' for=inner-classes_3 %} + +```scala mdoc:fail +val graph1: Graph = new Graph +val node1: graph1.Node = graph1.newNode +val node2: graph1.Node = graph1.newNode +node1.connectTo(node2) // работает +val graph2: Graph = new Graph +val node3: graph2.Node = graph2.newNode +node1.connectTo(node3) // не работает! +``` + +{% endtab %} +{% endtabs %} + +Тип `graph1.Node` отличается от типа `graph2.Node`. В Java последняя строка в предыдущем примере программы была бы правильной. Для узлов обоих графов Java будет присваивать один и тот же тип `Graph.Node`, т.е. `Node` имеет префикс класса `Graph`. В Скале такой тип также может быть выражен, он записывается `Graph#Node`. Если мы хотим иметь возможность соединять узлы разных графов, то вам нужно изменить описание первоначальной реализации графов следующим образом: + +{% tabs inner-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_4 %} + +```scala mdoc:nest +class Graph { + class Node { + var connectedNodes: List[Graph#Node] = Nil + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes + } + } + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=inner-classes_4 %} + +```scala +class Graph: + class Node: + var connectedNodes: List[Graph#Node] = Nil + def connectTo(node: Graph#Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` + +{% endtab %} +{% endtabs %} diff --git a/_ru/tour/lower-type-bounds.md b/_ru/tour/lower-type-bounds.md new file mode 100644 index 0000000000..3d3b22edb9 --- /dev/null +++ b/_ru/tour/lower-type-bounds.md @@ -0,0 +1,115 @@ +--- +layout: tour +title: Нижнее Ограничение Типа +partof: scala-tour +num: 21 +language: ru +next-page: inner-classes +previous-page: upper-type-bounds +prerequisite-knowledge: upper-type-bounds, generics, variance +--- + +В то время как [верхнее ограничение типа](upper-type-bounds.html) ограничивает тип до подтипа стороннего типа, _нижнее ограничение типа_ объявляют тип супертипом стороннего типа. Термин `B >: A` выражает, то что параметр типа `B` или абстрактный тип `B` относится к супертипу типа `A`. В большинстве случаев `A` будет задавать тип класса, а `B` задавать тип метода. + +Вот пример, где это полезно: + +{% tabs upper-type-bounds_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_1 %} + +```scala mdoc:fail +trait List[+A] { + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) +} + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] +``` + +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_1 %} + +```scala +trait List[+A]: + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] +``` + +{% endtab %} +{% endtabs %} + +В данной программе реализован связанный список. `Nil` представляет пустой список. Класс `NonEmptyList` - это узел, который содержит элемент типа `A` (`head`) и ссылку на остальную часть списка (`tail`). `trait List` и его подтипы ковариантны, потому что у нас указанно `+A`. + +Однако эта программа _не компилируется_, потому что параметр `elem` в `prepend` имеет тип `A`, который мы объявили *ко*вариантным. Так это не работает, потому что функции *контр*вариантны в типах своих параметров и *ко*вариантны в типах своих результатов. + +Чтобы исправить это, необходимо перевернуть вариантность типа параметра `elem` в `prepend`. Для этого мы вводим новый тип для параметра `B`, у которого тип `A` указан в качестве нижней границы типа. + +{% tabs upper-type-bounds_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_2 %} + +```scala mdoc +trait List[+A] { + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) +} + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] +``` + +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_2 %} + +```scala +trait List[+A]: + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] +``` + +{% endtab %} +{% endtabs %} + +Теперь мы можем сделать следующее: + +{% tabs upper-type-bounds_3 %} +{% tab 'Scala 2 и 3' for=upper-type-bounds_3 %} + +```scala mdoc +trait Bird +case class AfricanSwallow() extends Bird +case class EuropeanSwallow() extends Bird + +val africanSwallows: List[AfricanSwallow] = Nil.prepend(AfricanSwallow()) +val swallowsFromAntarctica: List[Bird] = Nil +val someBird: Bird = EuropeanSwallow() + +// присвоить птицам (birds) африканских ласточек (swallows) +val birds: List[Bird] = africanSwallows + +// добавляем новую птицу к африканским ласточкам, `B` - это `Bird` +val someBirds = africanSwallows.prepend(someBird) + +// добавляем европейскую ласточку к птицам +val moreBirds = birds.prepend(EuropeanSwallow()) + +// соединяем вместе различных ласточек, `B` - это `Bird`, потому что это общий супертип для обоих типов ласточек +val allBirds = africanSwallows.prepend(EuropeanSwallow()) + +// но тут ошибка! добавление списка птиц слишком расширяет тип аргументов. -Xlint предупредит! +val error = moreBirds.prepend(swallowsFromAntarctica) // List[Object] +``` + +{% endtab %} +{% endtabs %} + +Параметр ковариантного типа позволяет `birds` получать значение `africanSwallows`. + +Тип, связанный с параметром типа `prepend`, позволяет добавлять различные разновидности ласточек и получать более абстрактный тип: вместо `List[AfricanSwallow]`, мы получаем `List[Bird]`. + +Используйте `-Xlint`, чтобы предупредить, если аргумент предполагаемого типа слишком абстрактен. diff --git a/_ru/tour/mixin-class-composition.md b/_ru/tour/mixin-class-composition.md new file mode 100644 index 0000000000..d8cbb24f30 --- /dev/null +++ b/_ru/tour/mixin-class-composition.md @@ -0,0 +1,198 @@ +--- +layout: tour +title: Композиция классов с трейтами +partof: scala-tour +num: 7 +language: ru +next-page: higher-order-functions +previous-page: tuples +prerequisite-knowledge: inheritance, traits, abstract-classes, unified-types +--- + +Примеси (Mixin) - это трейты, которые используются для создания класса. + +{% tabs mixin-first-exemple class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-first-exemple %} + +```scala mdoc +abstract class A { + val message: String +} +class B extends A { + val message = "I'm an instance of class B" +} +trait C extends A { + def loudMessage = message.toUpperCase() +} +class D extends B with C + +val d = new D +println(d.message) // I'm an instance of class B +println(d.loudMessage) // I'M AN INSTANCE OF CLASS B +``` + +У класса `D` есть суперкласс `B` и трейт `C`. +Классы могут иметь только один суперкласс, но много трейтов (используя ключевое слово `extends` и `with` соответственно). +Трейты и суперкласс могут иметь один и тот же супертип. + +{% endtab %} + +{% tab 'Scala 3' for=mixin-first-exemple %} + +```scala +abstract class A: + val message: String +class B extends A: + val message = "I'm an instance of class B" +trait C extends A: + def loudMessage = message.toUpperCase() +class D extends B, C + +val d = D() +println(d.message) // I'm an instance of class B +println(d.loudMessage) // I'M AN INSTANCE OF CLASS B +``` + +У класса `D` есть суперкласс `B` и трейт `C`. +Классы могут иметь только один суперкласс, но много трейтов +(используя ключевое слово `extends` и разделитель `,` соответственно). +Трейты и суперкласс могут иметь один и тот же супертип. + +{% endtab %} + +{% endtabs %} + +Теперь давайте рассмотрим более интересный пример, начиная с абстрактного класса: + +{% tabs mixin-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-abstract-iterator %} + +```scala mdoc +abstract class AbsIterator { + type T + def hasNext: Boolean + def next(): T +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=mixin-abstract-iterator %} + +```scala +abstract class AbsIterator: + type T + def hasNext: Boolean + def next(): T +``` + +{% endtab %} + +{% endtabs %} + +Класс имеет абстрактный тип `T` и методы стандартного итератора. + +Далее создаем конкретную реализацию класса (все абстрактные члены `T`, `hasNext`, и `next` должны быть реализованы): + +{% tabs mixin-concrete-string-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-concrete-string-iterator %} + +```scala mdoc +class StringIterator(s: String) extends AbsIterator { + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = { + val ch = s charAt i + i += 1 + ch + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=mixin-concrete-string-iterator %} + +```scala +class StringIterator(s: String) extends AbsIterator: + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = + val ch = s charAt i + i += 1 + ch +``` + +{% endtab %} + +{% endtabs %} + +`StringIterator` принимает `String` и может быть использован для обхода по строке (например, чтоб проверить содержит ли строка определенный символ). + +Теперь давайте создадим трейт который тоже наследуется от `AbsIterator`. + +{% tabs mixin-extended-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-extended-abstract-iterator %} + +```scala mdoc +trait RichIterator extends AbsIterator { + def foreach(f: T => Unit): Unit = while (hasNext) f(next()) +} +``` + +У этого трейта реализован метод `foreach`, который постоянно вызывает переданную ему функцию `f: T => Unit` +на каждом новом элементе (`next()`) до тех пор пока в итераторе содержатся элементы (`while (hasNext)`). +Поскольку `RichIterator` - это трейт, ему не нужно реализовывать элементы абстрактного класса `AbsIterator`. + +{% endtab %} + +{% tab 'Scala 3' for=mixin-extended-abstract-iterator %} + +```scala +trait RichIterator extends AbsIterator: + def foreach(f: T => Unit): Unit = while hasNext do f(next()) +``` + +У этого трейта реализован метод `foreach`, который постоянно вызывает переданную ему функцию `f: T => Unit` +на каждом новом элементе (`next()`) до тех пор пока в итераторе содержатся элементы (`while hasNext`). +Поскольку `RichIterator` - это трейт, ему не нужно реализовывать элементы абстрактного класса `AbsIterator`. + +{% endtab %} + +{% endtabs %} + +Мы бы хотели объединить функциональность `StringIterator` и `RichIterator` в один класс. + +{% tabs mixin-combination-class class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-combination-class %} + +```scala mdoc +class RichStringIter extends StringIterator("Scala") with RichIterator +val richStringIter = new RichStringIter +richStringIter.foreach(println) +``` + +{% endtab %} + +{% tab 'Scala 3' for=mixin-combination-class %} + +```scala +class RichStringIter extends StringIterator("Scala"), RichIterator +val richStringIter = RichStringIter() +richStringIter.foreach(println) +``` + +{% endtab %} + +{% endtabs %} + +Новый класс `RichStringIter` включает `StringIterator` как суперкласс и `RichIterator` как трейт. + +Используя только одиночное наследование мы бы не смогли добиться того же уровня гибкости. diff --git a/_ru/tour/multiple-parameter-lists.md b/_ru/tour/multiple-parameter-lists.md new file mode 100644 index 0000000000..99f84700d5 --- /dev/null +++ b/_ru/tour/multiple-parameter-lists.md @@ -0,0 +1,231 @@ +--- +layout: tour +title: Множественные списки параметров (Каррирование) +partof: scala-tour +num: 10 +language: ru +next-page: case-classes +previous-page: nested-functions +--- + +Методы могут объявляться с несколькими списками параметров. + +### Пример + +Вот пример, определенный для трейта `Iterable` из API Scala коллекций: + +{% tabs foldLeft_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=foldLeft_definition %} + +```scala +trait Iterable[A] { + ... + def foldLeft[B](z: B)(op: (B, A) => B): B + ... +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=foldLeft_definition %} + +```scala +trait Iterable[A]: +... +def foldLeft[B](z: B)(op: (B, A) => B): B +... +``` + +{% endtab %} + +{% endtabs %} + +`foldLeft` применяет бинарный оператор `op` к начальному значению `z` и ко всем остальным элементам коллекции слева направо. +Ниже приведен пример его использования. + +Начиная с начального значения `0`, `foldLeft` применяет функцию `(m, n) => m + n` к каждому элементу списка +и предыдущему накопленному значению. + +{% tabs foldLeft_use %} + +{% tab 'Scala 2 и 3' for=foldLeft_use %} + +```scala mdoc +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val res = numbers.foldLeft(0)((m, n) => m + n) +println(res) // 55 +``` + +{% endtab %} + +{% endtabs %} + +### Варианты для использования + +Предлагаемые варианты для использования множественных списков параметров включают: + +#### Вывод типа + +Исторически сложилось, что в Scala вывод типов происходит по одному списку параметров за раз. +Скажем, у вас есть следующий метод: + +{% tabs foldLeft1_definition %} + +{% tab 'Scala 2 и 3' for=foldLeft1_definition %} + +```scala mdoc +def foldLeft1[A, B](as: List[A], b0: B, op: (B, A) => B) = ??? +``` + +{% endtab %} + +{% endtabs %} + +Затем при желании вызвать его следующим образом, можно обнаружить, что метод не компилируется: + +{% tabs foldLeft1_wrong_use %} + +{% tab 'Scala 2 и 3' for=foldLeft1_wrong_use %} + +```scala mdoc:fail +def notPossible = foldLeft1(numbers, 0, _ + _) +``` + +{% endtab %} + +{% endtabs %} + +вам нужно будет вызвать его одним из следующих способов: + +{% tabs foldLeft1_good_use %} + +{% tab 'Scala 2 и 3' for=foldLeft1_good_use %} + +```scala mdoc +def firstWay = foldLeft1[Int, Int](numbers, 0, _ + _) +def secondWay = foldLeft1(numbers, 0, (a: Int, b: Int) => a + b) +``` + +{% endtab %} + +{% endtabs %} + +Это связано с тем, что Scala не может вывести тип функции `_ + _`, так как она все еще выводит `A` и `B`. +Путем перемещения параметра `op` в собственный список параметров, `A` и `B` выводятся в первом списке. +Затем эти предполагаемые типы будут доступны для второго списка параметров +и `_ + _` станет соответствовать предполагаемому типу `(Int, Int) => Int`. + +{% tabs foldLeft2_definition_and_use %} + +{% tab 'Scala 2 и 3' for=foldLeft2_definition_and_use %} + +```scala mdoc +def foldLeft2[A, B](as: List[A], b0: B)(op: (B, A) => B) = ??? +def possible = foldLeft2(numbers, 0)(_ + _) +``` + +{% endtab %} + +{% endtabs %} + +Последнее определение метода не нуждается в подсказках типа и может вывести все типы своих параметров. + +#### Неявные параметры + +Чтоб указать что параметр используется [_неявно_ (_implicit_)](/ru/tour/implicit-parameters.html) +необходимо задавать несколько списков параметров. +Примером может служить следующее: + +{% tabs execute_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=execute_definition %} + +```scala mdoc +def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ??? +``` + +{% endtab %} + +{% tab 'Scala 3' for=execute_definition %} + +```scala +def execute(arg: Int)(using ec: scala.concurrent.ExecutionContext) = ??? +``` + +{% endtab %} + +{% endtabs %} + +#### Частичное применение + +Методы могут объявляться с несколькими списками параметров. +При этом когда такой метод вызывается с меньшим количеством списков параметров, +это приводит к созданию новой функции, +которая ожидает на вход недостающий список параметров. +Формально это называется [частичное применение](https://ru.wikipedia.org/wiki/%D0%A7%D0%B0%D1%81%D1%82%D0%B8%D1%87%D0%BD%D0%BE%D0%B5_%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5). + +Например, + +{% tabs foldLeft_partial %} + +{% tab 'Scala 2 и 3' for=foldLeft_partial %} + +```scala mdoc:nest +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]()) _ + +val squares = numberFunc((xs, x) => xs :+ x*x) +println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) + +val cubes = numberFunc((xs, x) => xs :+ x*x*x) +println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` + +{% endtab %} + +{% endtabs %} + +### Сравнение с «каррированием» + +Иногда можно встретить, что метод с несколькими списками параметров называется «каррированный». + +Как говорится [в статье на Википедии о каррировании](https://ru.wikipedia.org/wiki/%D0%9A%D0%B0%D1%80%D1%80%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5), + +> Каррирование — преобразование функции от многих аргументов в набор вложенных функций, +> каждая из которых является функцией от одного аргумента. + +Мы не рекомендуем использовать слово «каррирование» в отношении множественных списков параметров Scala по двум причинам: + +1. В Scala множественные параметры и множественные списки параметров задаются + и реализуются непосредственно как часть языка, а не преобразуются из функций с одним параметром. + +2. Существует опасность путаницы с методами из стандартной Scala библиотеки + [`curried`]() + и [`uncurried`](), + которые вообще не включают множественные списки параметров. + +Тем не менее, несомненно, есть сходство между множественными списками параметров и каррированием. +Хотя они различаются в месте определения, +в месте вызова могут тем не менее выглядеть одинаково, как в этом примере: + +{% tabs about_currying %} + +{% tab 'Scala 2 и 3' for=about_currying %} + +```scala mdoc +// версия с множественными списками параметров +def addMultiple(n1: Int)(n2: Int) = n1 + n2 +// два различных способа получить каррированную версию +def add(n1: Int, n2: Int) = n1 + n2 +val addCurried1 = (add _).curried +val addCurried2 = (n1: Int) => (n2: Int) => n1 + n2 +// независимо от определения, вызов всех трех идентичен +addMultiple(3)(4) // 7 +addCurried1(3)(4) // 7 +addCurried2(3)(4) // 7 +``` + +{% endtab %} + +{% endtabs %} diff --git a/_ru/tour/named-arguments.md b/_ru/tour/named-arguments.md new file mode 100644 index 0000000000..da9202a051 --- /dev/null +++ b/_ru/tour/named-arguments.md @@ -0,0 +1,61 @@ +--- +layout: tour +title: Именованные Аргументы +partof: scala-tour +num: 34 +language: ru +next-page: packages-and-imports +previous-page: default-parameter-values +prerequisite-knowledge: function-syntax +--- + +При вызове методов можно конкретно указывать название задаваемого аргумента следующим образом: + +{% tabs named-arguments-when-good %} + +{% tab 'Scala 2 и 3' for=named-arguments-when-good %} + +```scala mdoc +def printName(first: String, last: String): Unit = + println(s"$first $last") + +printName("John", "Public") // выводит "John Public" +printName(first = "John", last = "Public") // выводит "John Public" +printName(last = "Public", first = "John") // выводит "John Public" +printName("Elton", last = "John") // выводит "Elton John" +``` + +{% endtab %} + +{% endtabs %} + +Это полезно, когда два параметра имеют один и тот же тип и аргументы могут быть случайно перепутаны. + +Обратите внимание, что именованные аргументы могут быть указаны в любом порядке. +Однако, если аргументы расположены не в порядке параметров метода (читается слева направо), +остальные аргументы должны быть названы. + +В следующем примере именованные аргументы позволяют опустить параметр `middle`. +В случае ошибки, если первый аргумент не на своем месте, необходимо будет указать второй аргумент. + +{% tabs named-arguments-when-error %} + +{% tab 'Scala 2 и 3' for=named-arguments-when-error %} + +```scala mdoc:fail +def printFullName(first: String, middle: String = "Q.", last: String): Unit = + println(s"$first $middle $last") + +printFullName(first = "John", last = "Public") // выводит "John Q. Public" +printFullName("John", last = "Public") // выводит "John Q. Public" +printFullName("John", middle = "Quincy", "Public") // выводит "John Quincy Public" +printFullName(last = "Public", first = "John") // выводит "John Q. Public" +printFullName(last = "Public", "John") // ошибка: позиция после именованного аргумента +``` + +{% endtab %} + +{% endtabs %} + +Именованные аргументы работают при вызове Java методов, но только в том случае, +если используемая Java библиотека была скомпилирована с флагом `-parameters`. diff --git a/_ru/tour/nested-functions.md b/_ru/tour/nested-functions.md new file mode 100644 index 0000000000..8bc05a9d70 --- /dev/null +++ b/_ru/tour/nested-functions.md @@ -0,0 +1,63 @@ +--- +layout: tour +title: Вложенные Методы +partof: scala-tour +num: 9 +language: ru +next-page: multiple-parameter-lists +previous-page: higher-order-functions +--- + +В Scala возможно объявление метода вкладывать в тело другого метода. Это реализовано в следующем примере, в котором метод `factorial` используется для вычисления факториала заданного числа: + +{% tabs Nested_functions_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=Nested_functions_definition %} + +```scala mdoc +def factorial(x: Int): Int = { + def fact(x: Int, accumulator: Int): Int = { + if (x <= 1) accumulator + else fact(x - 1, x * accumulator) + } + fact(x, 1) +} + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) +``` + +{% endtab %} + +{% tab 'Scala 3' for=Nested_functions_definition %} + +```scala +def factorial(x: Int): Int = + def fact(x: Int, accumulator: Int): Int = + if x <= 1 then accumulator + else fact(x - 1, x * accumulator) + fact(x, 1) + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) + +``` + +{% endtab %} + +{% endtabs %} + +{% tabs Nested_functions_result %} + +{% tab 'Scala 2 и 3' for=Nested_functions_result %} + +Результат выполнения программы: + +``` +Factorial of 2: 2 +Factorial of 3: 6 +``` + +{% endtab %} + +{% endtabs %} diff --git a/_ru/tour/operators.md b/_ru/tour/operators.md new file mode 100644 index 0000000000..c8ec47bb3e --- /dev/null +++ b/_ru/tour/operators.md @@ -0,0 +1,156 @@ +--- +layout: tour +title: Операторы +partof: scala-tour +num: 30 +language: ru +next-page: by-name-parameters +previous-page: type-inference +prerequisite-knowledge: case-classes +--- + +В Скале операторы - это обычные методы. В качестве _инфиксного оператора_ может быть использован любой метод с одним параметром. Например, `+` может вызываться с использованием точки: + +{% tabs operators_1 %} +{% tab 'Scala 2 и 3' for=operators_1 %} + +``` +10.+(1) +``` + +{% endtab %} +{% endtabs %} + +Однако легче воспринимать код, когда такие методы записаны как инфиксный оператор: + +{% tabs operators_2 %} +{% tab 'Scala 2 и 3' for=operators_2 %} + +``` +10 + 1 +``` + +{% endtab %} +{% endtabs %} + +## Создание и использование операторов + +В качестве оператора можно использовать любой допустимый символ. Включая имена на подобии `add` или символ (символы) типа `+`. + +{% tabs operators_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_3 %} + +```scala mdoc +case class Vec(x: Double, y: Double) { + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) +} + +val vector1 = Vec(1.0, 1.0) +val vector2 = Vec(2.0, 2.0) + +val vector3 = vector1 + vector2 +vector3.x // 3.0 +vector3.y // 3.0 +``` + +{% endtab %} +{% tab 'Scala 3' for=operators_3 %} + +```scala +case class Vec(x: Double, y: Double): + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) + +val vector1 = Vec(1.0, 1.0) +val vector2 = Vec(2.0, 2.0) + +val vector3 = vector1 + vector2 +vector3.x // 3.0 +vector3.y // 3.0 +``` + +{% endtab %} +{% endtabs %} + +У класса Vec есть метод `+`, который мы использовали для добавления `vector1` и `vector2`. Используя круглые скобки, можно строить сложные выражения с читаемым синтаксисом. Пример создания класса `MyBool`, которое включает в себя методы `and` и `or` + +{% tabs operators_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_4 %} + +```scala mdoc +case class MyBool(x: Boolean) { + def and(that: MyBool): MyBool = if (x) that else this + def or(that: MyBool): MyBool = if (x) this else that + def negate: MyBool = MyBool(!x) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=operators_4 %} + +```scala +case class MyBool(x: Boolean): + def and(that: MyBool): MyBool = if x then that else this + def or(that: MyBool): MyBool = if x then this else that + def negate: MyBool = MyBool(!x) +``` + +{% endtab %} +{% endtabs %} + +Теперь можно использовать операторы `and` и `or` в качестве инфиксных операторов: + +{% tabs operators_5 %} +{% tab 'Scala 2 и 3' for=operators_5 %} + +```scala mdoc +def not(x: MyBool) = x.negate +def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) +``` + +{% endtab %} +{% endtabs %} + +Это помогает сделать объявление `xor` более читабельным. + +## Порядок очередности + +Когда выражение использует несколько операторов, операторы оцениваются на основе приоритета первого символа. Таблица приоритетов символов: + +``` +(символы которых нет снизу) +* / % ++ - +: += ! +< > +& +^ +| +(буквы, $, _) +``` + +Такой приоритет распространяется на любые функции, которые вы задаете. Например, следующее выражение: + +{% tabs operators_7 %} +{% tab 'Scala 2 и 3' for=operators_7 %} + +``` +a + b ^? c ?^ d less a ==> b | c +``` + +{% endtab %} +{% endtabs %} + +эквивалентно + +{% tabs operators_8 %} +{% tab 'Scala 2 и 3' for=operators_8 %} + +``` +((a + b) ^? (c ?^ d)) less ((a ==> b) | c) +``` + +{% endtab %} +{% endtabs %} + +`?^` имеет высший приоритет, потому что начинается с символа `?`. Второй по старшинству приоритет имеет `+`, за которым следуют `==>`, `^?`, `|`, и `less`. diff --git a/_ru/tour/package-objects.md b/_ru/tour/package-objects.md new file mode 100644 index 0000000000..89c392ea46 --- /dev/null +++ b/_ru/tour/package-objects.md @@ -0,0 +1,169 @@ +--- +layout: tour +title: Объекты Пакета +partof: scala-tour +num: 36 +language: ru +previous-page: packages-and-imports +--- + +Часто бывает удобно иметь определения, доступные для всего пакета, +когда не нужно придумывать имя для оболочки `object`, которая их содержит. + +{% tabs pkg-obj-vs-top-lvl_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_1 %} + +Scala 2 предоставляет _объекты пакета_ (_package objects_) в виде удобного контейнера, общего для всего пакета. + +Объекты пакета могут содержать произвольные виды выражений, а не только переменные и методы. +Например, они часто используются для хранения псевдонимов типа и наборов неявных преобразований доступных всему пакету. +Объекты пакета могут также наследоваться от классов и трейтов Scala. + +> В будущей версии Scala 3 объекты пакета будут удалены в пользу определений верхнего уровня. + +По соглашению, исходный код объекта пакета обычно помещается в файл под названием `package.scala`. + +Каждому пакету разрешено иметь один объект пакета. +Любые выражения, содержащиеся в объекте пакета, считаются членами самого пакета. + +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_1 %} + +В Scala 3 любое определение может быть объявлено на верхнем уровне пакета. +Например, классы, перечисления, методы и переменные. + +Любые определения, размещенные на верхнем уровне пакета, считаются членами самого пакета. + +> В Scala 2 верхнеуровневый метод, определения типов и переменных должны были быть заключены в **объект пакета**. +> Их все еще можно использовать в Scala 3 для обратной совместимости. +> Вы можете увидеть, как они работают, переключая вкладки. + +{% endtab %} +{% endtabs %} + +См. пример ниже. Предположим, есть старший класс `Fruit` и три наследуемых от него объекта `Fruit` в пакете. + +`gardening.fruits`: + +{% tabs pkg-obj-vs-top-lvl_2 %} +{% tab 'Scala 2 и 3' for=pkg-obj-vs-top-lvl_2 %} + +``` +// в файле gardening/fruits/Fruit.scala +package gardening.fruits + +case class Fruit(name: String, color: String) +object Apple extends Fruit("Apple", "green") +object Plum extends Fruit("Plum", "blue") +object Banana extends Fruit("Banana", "yellow") +``` + +{% endtab %} +{% endtabs %} + +Теперь предположим, что мы хотим поместить переменную `planted` и метод `showFruit` непосредственно в пакет `gardening`. +Вот как это делается: + +{% tabs pkg-obj-vs-top-lvl_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_3 %} + +``` +// в файле gardening/fruits/package.scala +package gardening +package object fruits { + val planted = List(Apple, Plum, Banana) + def showFruit(fruit: Fruit): Unit = { + println(s"${fruit.name}s are ${fruit.color}") + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_3 %} + +``` +// в файле gardening/fruits/package.scala +package gardening.fruits + +val planted = List(Apple, Plum, Banana) +def showFruit(fruit: Fruit): Unit = + println(s"${fruit.name}s are ${fruit.color}") +``` + +{% endtab %} +{% endtabs %} + +Для примера, следующий объект `PrintPlanted` импортирует `planted` и `showFruit` точно так же, как с вариантом импорта класса `Fruit`, +используя групповой стиль импорта пакета `gardening.fruits`: + +{% tabs pkg-obj-vs-top-lvl_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_4 %} + +``` +// в файле PrintPlanted.scala +import gardening.fruits._ + +object PrintPlanted { + def main(args: Array[String]): Unit = { + for (fruit <- planted) { + showFruit(fruit) + } + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_4 %} + +``` +// в файле PrintPlanted.scala +import gardening.fruits.* + +@main def printPlanted(): Unit = + for fruit <- planted do + showFruit(fruit) +``` + +{% endtab %} +{% endtabs %} + +### Объединение нескольких определений на уровне пакета + +Часто в вашем проекте может быть несколько повторно используемых определений, +заданных в различных модулях, которые вы хотите агрегировать на верхнем уровне пакета. + +Например, некоторые вспомогательные методы в трейте `FruitHelpers` +и некоторые псевдонимы терминов/типов в свойстве `FruitAliases`. +Вот как вы можете разместить все их определения на уровне пакета `fruit`: + +{% tabs pkg-obj-vs-top-lvl_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_5 %} + +Объекты пакета ведут себя также, как и любые другие объекты. +Это означает, что вы можете использовать наследование, при этом сразу нескольких трейтов: + +``` +package gardening + +// `fruits` наследует свои элементы от родителей. +package object fruits extends FruitAliases with FruitHelpers +``` + +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_5 %} + +В Scala 3 предпочтительно использовать `export` для объединения членов из нескольких объектов в единую область видимости. +Здесь мы определяем приватные объекты, которые смешиваются с вспомогательными трейтами, +а затем экспортируют их элементы на верхнем уровне: + +``` +package gardening.fruits + +private object FruitAliases extends FruitAliases +private object FruitHelpers extends FruitHelpers + +export FruitHelpers.*, FruitAliases.* +``` + +{% endtab %} +{% endtabs %} diff --git a/_ru/tour/packages-and-imports.md b/_ru/tour/packages-and-imports.md new file mode 100644 index 0000000000..4624fa7238 --- /dev/null +++ b/_ru/tour/packages-and-imports.md @@ -0,0 +1,173 @@ +--- +layout: tour +title: Пакеты и Импорт +partof: scala-tour +num: 35 +language: ru +previous-page: annotations +next-page: package-objects +--- + +# Пакеты и Импорт + +Scala использует пакеты для указания пространства имен, они позволяют создавать модульную структуру кода. + +## Создание пакета + +Пакеты создаются путем объявления одного или нескольких имен пакетов в верхней части файла Scala. + +{% tabs packages-and-imports_1 %} +{% tab 'Scala 2 и 3' for=packages-and-imports_1 %} + +``` +package users + +class User +``` + +{% endtab %} +{% endtabs %} + +По соглашению пакеты называют тем же именем, что и каталог, содержащий файл Scala. Однако Scala не обращает внимания на расположение файлов. Структура каталогов sbt-проекта для `package users` может выглядеть следующим образом: + +``` +- ExampleProject + - build.sbt + - project + - src + - main + - scala + - users + User.scala + UserProfile.scala + UserPreferences.scala + - test +``` + +Обратите внимание, что каталог `users` находится внутри каталога `scala` и как в пакете содержатся несколько файлов Scala. +Каждый файл Scala в пакете может иметь одно и то же объявление пакета. +Другой способ объявления пакетов - вложить их друг в друга:: + +{% tabs packages-and-imports_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_2 %} + +```scala +package users { + package administrators { + class NormalUser + } + package normalusers { + class NormalUser + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_2 %} + +```scala +package users: + package administrators: + class NormalUser + + package normalusers: + class NormalUser +``` + +{% endtab %} +{% endtabs %} + +Как видите, такой способ позволяет вкладывать пакеты друг в друга, а также обеспечивает отличный контроль за областью видимости и возможностью изоляции. + +Имя пакета должно быть все в нижнем регистре, и если код разрабатывается в организации имеющей сайт, то следует использовать имя следующего формата: `<домен-верхнего-уровня>.<доменное-имя>.<название-проекта>`. Например, если бы у Google был проект под названием `SelfDrivingCar`, название пакета выглядело бы следующим образом: + +{% tabs packages-and-imports_3 %} +{% tab 'Scala 2 и 3' for=packages-and-imports_3 %} + +```scala +package com.google.selfdrivingcar.camera + +class Lens +``` + +{% endtab %} +{% endtabs %} + +Что может соответствовать следующей структуре каталога: `SelfDrivingCar/src/main/scala/com/google/selfdrivingcar/camera/Lens.scala`. + +## Импорт + +Указание `import` открывает доступ к членам (классам, трейтам, функциям и т.д.) в других пакетах. Указание `import` не требуется для доступа к членам одного и того же пакета. Указание `import` избирательны: + +{% tabs packages-and-imports_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_4 %} + +``` +import users._ // групповой импорт всего пакета users +import users.User // импортировать только User +import users.{User, UserPreferences} // импортировать только User, UserPreferences +import users.{UserPreferences => UPrefs} // импортировать и переименовать +``` + +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_4 %} + +``` +import users.* // групповой импорт всего пакета users, кроме given +import users.given // импорт всех given пакета users +import users.User // импортировать только User +import users.{User, UserPreferences} // импортировать только User, UserPreferences +import users.UserPreferences as UPrefs // импортировать и переименовать +``` + +{% endtab %} +{% endtabs %} + +Одним из отличий Scala от Java является то, что импорт можно использовать где угодно: + +{% tabs packages-and-imports_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_5 %} + +```scala mdoc +def sqrtplus1(x: Int) = { + import scala.math.sqrt + sqrt(x) + 1.0 +} +``` + +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_5 %} + +```scala +def sqrtplus1(x: Int) = + import scala.math.sqrt + sqrt(x) + 1.0 +``` + +{% endtab %} +{% endtabs %} + +В случае возникновения конфликта имен и необходимости импортировать что-либо из корня проекта, имя пакета должно начинаться с префикса `_root_`: + +{% tabs packages-and-imports_6 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_6 %} + +```scala +package accounts + +import _root_.users._ +``` + +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_6 %} + +```scala +package accounts + +import _root_.users.* +``` + +{% endtab %} +{% endtabs %} + +Примечание: Пакеты `scala` и `java.lang`, а также `object Predef` импортируются по умолчанию. diff --git a/_ru/tour/pattern-matching.md b/_ru/tour/pattern-matching.md new file mode 100644 index 0000000000..b46810564b --- /dev/null +++ b/_ru/tour/pattern-matching.md @@ -0,0 +1,335 @@ +--- +layout: tour +title: Сопоставление с примером +partof: scala-tour +num: 12 +language: ru +next-page: singleton-objects +previous-page: case-classes +prerequisite-knowledge: case-classes, string-interpolation, subtyping +--- + +Сопоставление с примером (Pattern matching) - это механизм сравнения значений с определенным примером. При успешном совпадении значение может быть разложено на составные части. Мы рассматриваем сопоставление с примером, как более мощную версию `switch` оператора из Java. Eго также можно использовать вместо серии if/else выражений. + +## Синтаксис + +Синтаксис сопоставления с примером состоит из значения, ключевого слова `match` (сопоставить) и по крайней мере, одного пункта с примером `case`, с которым мы хотим сопоставить наше значение. + +{% tabs pattern-matching-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-1 %} + +```scala mdoc +import scala.util.Random + +val x: Int = Random.nextInt(10) + +x match { + case 0 => "zero" + case 1 => "one" + case 2 => "two" + case _ => "other" +} +``` + +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-1 %} + +```scala +import scala.util.Random + +val x: Int = Random.nextInt(10) + +x match + case 0 => "zero" + case 1 => "one" + case 2 => "two" + case _ => "other" +``` + +{% endtab %} +{% endtabs %} + +Значение константы `x` выше представляет собой случайное целое число от 0 до 9. `x` становится левым операндом оператора `match`, а справа - выражением с четырьмя примерами (называемые еще _вариантами_). Последний вариант `_` - позволяет "поймать все оставшиеся варианты" т. е. для любого числа больше 2. + +Сопоставление с примером возвращает значение. + +{% tabs pattern-matching-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-2 %} + +```scala mdoc +def matchTest(x: Int): String = x match { + case 1 => "one" + case 2 => "two" + case _ => "other" +} +matchTest(3) // выводит "other" +matchTest(1) // выводит "one" +``` + +{% endtab %} + +{% tab 'Scala 3' for=pattern-matching-2 %} + +```scala +def matchTest(x: Int): String = x match + case 1 => "one" + case 2 => "two" + case _ => "other" + +matchTest(3) // выводит "other" +matchTest(1) // выводит "one" +``` + +{% endtab %} +{% endtabs %} + +Это сопоставляющее выражение имеет тип String, так как все варианты сопоставления возвращают String. Поэтому функция `matchTest` возвращает String. + +## Сопоставление с классами образцами + +Классы образцы особенно полезны для сопоставления. + +{% tabs notification %} +{% tab 'Scala 2 и 3' for=notification %} + +```scala mdoc +sealed trait Notification + +case class Email(sender: String, title: String, body: String) extends Notification + +case class SMS(caller: String, message: String) extends Notification + +case class VoiceRecording(contactName: String, link: String) extends Notification +``` + +{% endtab %} +{% endtabs %} + +`Notification` - запечатанный трейт, от которого наследуются три конкретных типа реализаций классов образцов `Email`, `SMS`, и `VoiceRecording`. Теперь мы можем делать сопоставление с примером используя в качестве примера один из этих классов образцов. +При сопоставлении с классом образцом мы можем сразу извлекать параметры из которых состоит класс (благодаря автоматическому использованию [объекта экстрактора](extractor-objects.html)): + +{% tabs pattern-matching-4 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-4 %} + +```scala +def showNotification(notification: Notification): String = { + notification match { + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" + case VoiceRecording(name, link) => + s"You received a Voice Recording from $name! Click the link to hear it: $link" + } +} +val someSms = SMS("12345", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") + +println(showNotification(someSms)) // выводит "You got an SMS from 12345! Message: Are you there?" + +println(showNotification(someVoiceRecording)) // выводит "You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123" +``` + +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-4 %} + +```scala +def showNotification(notification: Notification): String = + notification match + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" + case VoiceRecording(name, link) => + s"You received a Voice Recording from $name! Click the link to hear it: $link" + +val someSms = SMS("12345", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") + +println(showNotification(someSms)) // выводит "You got an SMS from 12345! Message: Are you there?" + +println(showNotification(someVoiceRecording)) // выводит "You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123" +``` + +{% endtab %} +{% endtabs %} + +Функция `showNotification` принимает в качестве параметра абстрактный тип `Notification` который проверяет по образцам (т.е. выясняет, является ли он классом `Email`, `SMS` или `VoiceRecording`). В `case Email(email, title, _)`поля `email` и `title` используются в возвращаемом значении, а вот поле `body` игнорируется благодаря символу `_`. + +## Ограждения примеров + +Ограждения примеров - это просто логические выражения, которые используются для того, чтобы сделать выбор более специфичным (убрать лишние варианты). Просто добавьте `if <логическое выражение>` после примера. + +{% tabs pattern-matching-5 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-5 %} + +```scala +def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String = { + notification match { + case Email(sender, _, _) if importantPeopleInfo.contains(sender) => + "You got an email from special someone!" + case SMS(number, _) if importantPeopleInfo.contains(number) => + "You got an SMS from special someone!" + case other => + showNotification(other) // в этом варианте считается подходящими параметры любого типа. Значит этот вариант выполняется во всех случаях и передает исходный параметр в функцию showNotification + } +} + +val importantPeopleInfo = Seq("867-5309", "jenny@gmail.com") + +val someSms = SMS("123-4567", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") +val importantEmail = Email("jenny@gmail.com", "Drinks tonight?", "I'm free after 5!") +val importantSms = SMS("867-5309", "I'm here! Where are you?") + +println(showImportantNotification(someSms, importantPeopleInfo)) // выводит "You got an SMS from 123-4567! Message: Are you there?" +println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) // выводит "You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123" +println(showImportantNotification(importantEmail, importantPeopleInfo)) // выводит "You got an email from special someone!" + +println(showImportantNotification(importantSms, importantPeopleInfo)) // выводит "You got an SMS from special someone!" +``` + +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-5 %} + +```scala +def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String = + notification match + case Email(sender, _, _) if importantPeopleInfo.contains(sender) => + "You got an email from special someone!" + case SMS(number, _) if importantPeopleInfo.contains(number) => + "You got an SMS from special someone!" + case other => + showNotification(other) // в этом варианте считается подходящими параметры любого типа. Значит этот вариант выполняется во всех случаях и передает исходный параметр в функцию showNotification + +val importantPeopleInfo = Seq("867-5309", "jenny@gmail.com") + +val someSms = SMS("123-4567", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") +val importantEmail = Email("jenny@gmail.com", "Drinks tonight?", "I'm free after 5!") +val importantSms = SMS("867-5309", "I'm here! Where are you?") + +println(showImportantNotification(someSms, importantPeopleInfo)) // выводит "You got an SMS from 123-4567! Message: Are you there?" +println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) // выводит "You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123" +println(showImportantNotification(importantEmail, importantPeopleInfo)) // выводит "You got an email from special someone!" + +println(showImportantNotification(importantSms, importantPeopleInfo)) // выводит "You got an SMS from special someone!" +``` + +{% endtab %} +{% endtabs %} + +В варианте `case Email(email, _, _) if importantPeopleInfo.contains(email)`, пример сравнивается только если `email` находится в списке `importantPeopleInfo`. + +## Сопоставление только с типом + +Вы можете сопоставлять только по типу как в примере: + +{% tabs pattern-matching-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-6 %} + +```scala mdoc +sealed trait Device +case class Phone(model: String) extends Device { + def screenOff = "Turning screen off" +} +case class Computer(model: String) extends Device { + def screenSaverOn = "Turning screen saver on..." +} + +def goIdle(device: Device): String = device match { + case p: Phone => p.screenOff + case c: Computer => c.screenSaverOn +} +``` + +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-6 %} + +```scala +sealed trait Device +case class Phone(model: String) extends Device: + def screenOff = "Turning screen off" + +case class Computer(model: String) extends Device: + def screenSaverOn = "Turning screen saver on..." + + +def goIdle(device: Device): String = device match + case p: Phone => p.screenOff + case c: Computer => c.screenSaverOn +``` + +{% endtab %} +{% endtabs %} + +метод `goIdle` реализует изменение поведения в зависимости от типа `Device`. По соглашению в качестве названия варианта используется первая буква типа (в данном случае `p` и `c`). + +## Запечатанные типы + +Вы могли заметить, что в приведенных выше примерах базовые типы уточняются с помощью ключевого слова `sealed`. +Это обеспечивает дополнительную безопасность, поскольку компилятор проверяет, +указаны ли все случаи в выражении `match`, если базовым типом является `sealed`. + +Например, в методе `showNotification`, определенном выше, +если мы "забудем" один пример, скажем, `VoiceRecording`, +компилятор выдаст предупреждение: + +{% tabs pattern-matching-7 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-7 %} + +```scala +def showNotification(notification: Notification): String = { + notification match { + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-7 %} + +```scala +def showNotification(notification: Notification): String = + notification match + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" +``` + +{% endtab %} +{% endtabs %} + +Это определение выдает следующее предупреждение: + +``` +match may not be exhaustive. + +It would fail on pattern case: VoiceRecording(_, _) +``` + +Компилятор даже предоставляет примеры входных данных, которые потерпят неудачу при сопоставлении! + +С другой стороны, проверка полноты требует, чтобы вы определили все подтипы базового типа в том же файле, +что и базовый тип (иначе бы компилятор не знал все возможные варианты). +Например, если вы попытаетесь определить новый тип `Notification` вне файла, +который определяет `sealed trait Notification`, это приведет к ошибке компиляции: + +``` +case class Telepathy(message: String) extends Notification + ^ + Cannot extend sealed trait Notification in a different source file +``` + +## Замечания + +Сопоставление с примером наиболее полезно для сопоставления алгебраических типов, выраженных через [классы образцы](case-classes.html). +Scala также позволяет создавать образцы независимо от классов образцов, через использование метода `unapply` в [объектах экстракторах](extractor-objects.html). + +## Дополнительные ресурсы + +- Дополнительная информация о сопоставлении с примером доступна [в книге Scala](/ru/scala3/book/control-structures.html#match-выражения). diff --git a/_ru/tour/polymorphic-methods.md b/_ru/tour/polymorphic-methods.md new file mode 100644 index 0000000000..115cec0d94 --- /dev/null +++ b/_ru/tour/polymorphic-methods.md @@ -0,0 +1,51 @@ +--- +layout: tour +title: Полиморфные методы +partof: scala-tour +num: 28 +language: ru +next-page: type-inference +previous-page: implicit-conversions +prerequisite-knowledge: unified-types +--- + +Также как и у обобщенных классов, у методов есть полиморфизм по типу, с таким же синтаксисом (параметр типа указывается в квадратных скобках сразу после названия метода). + +Вот пример: + +{% tabs polymorphic-methods_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=polymorphic-methods_1 %} + +```scala mdoc +def listOfDuplicates[A](x: A, length: Int): List[A] = { + if (length < 1) + Nil + else + x :: listOfDuplicates(x, length - 1) +} +println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3) +println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La) +``` + +{% endtab %} +{% tab 'Scala 3' for=polymorphic-methods_1 %} + +```scala +def listOfDuplicates[A](x: A, length: Int): List[A] = + if length < 1 then + Nil + else + x :: listOfDuplicates(x, length - 1) + +println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3) +println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La) +``` + +{% endtab %} +{% endtabs %} + +Метод `listOfDuplicates` принимает параметр типа `A` и параметры значений `x` и `length`. Значение `x` имеет тип `A`. Если `length < 1` мы возвращаем пустой список. В противном случае мы добавляем `x`к списку, которые возвращаем через рекурсивный вызовов. (Обратите внимание, что `::` означает добавление элемента слева к списку справа). + +В первом вызове метода мы явно указываем параметр типа, записывая `[Int]`. Поэтому первым аргументом должен быть `Int` и тип возвращаемого значения будет `List[Int]`. + +Во втором вызове показано, что вам не всегда нужно явно указывать параметр типа. Часто компилятор сам может вывести тип исходя из контекста или типа передаваемых аргументов. В этом варианте `"La"` - это `String`, поэтому компилятор знает, что `A` должен быть `String`. diff --git a/_ru/tour/regular-expression-patterns.md b/_ru/tour/regular-expression-patterns.md new file mode 100644 index 0000000000..2058d76ee7 --- /dev/null +++ b/_ru/tour/regular-expression-patterns.md @@ -0,0 +1,176 @@ +--- +layout: tour +title: Регулярные Выражения +partof: scala-tour +num: 15 +language: ru +next-page: extractor-objects +previous-page: singleton-objects +--- + +Регулярные выражения (Regular expression) - это специальный шаблон для поиска данных, задаваемый в виде текстовой строки. Любая строка может быть преобразована в регулярное выражение методом `.r`. + +{% tabs regex-patterns_numberPattern class=tabs-scala-version %} + +{% tab 'Scala 2' for=regex-patterns_numberPattern %} + +```scala mdoc +import scala.util.matching.Regex + +val numberPattern: Regex = "[0-9]".r + +numberPattern.findFirstMatchIn("awesomepassword") match { + case Some(_) => println("Password OK") + case None => println("Password must contain a number") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=regex-patterns_numberPattern %} + +```scala +import scala.util.matching.Regex + +val numberPattern: Regex = "[0-9]".r + +numberPattern.findFirstMatchIn("awesomepassword") match + case Some(_) => println("Password OK") + case None => println("Password must contain a number") +``` + +{% endtab %} + +{% endtabs %} + +В приведенном выше примере `numberPattern` - это `Regex` (регулярное выражение), которое мы используем, чтобы убедиться, что пароль содержит число. + +Используя круглые скобки можно объединять сразу несколько групп регулярных выражений. + +{% tabs regex-patterns_keyValPattern class=tabs-scala-version %} + +{% tab 'Scala 2' for=regex-patterns_keyValPattern %} + +```scala mdoc +import scala.util.matching.Regex + +val keyValPattern: Regex = "([0-9a-zA-Z- ]+): ([0-9a-zA-Z-#()/. ]+)".r + +val input: String = + """background-color: #A03300; + |background-image: url(img/header100.png); + |background-position: top center; + |background-repeat: repeat-x; + |background-size: 2160px 108px; + |margin: 0; + |height: 108px; + |width: 100%;""".stripMargin + +for (patternMatch <- keyValPattern.findAllMatchIn(input)) + println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}") +``` + +{% endtab %} + +{% tab 'Scala 3' for=regex-patterns_keyValPattern %} + +```scala +import scala.util.matching.Regex + +val keyValPattern: Regex = "([0-9a-zA-Z- ]+): ([0-9a-zA-Z-#()/. ]+)".r + +val input: String = + """background-color: #A03300; + |background-image: url(img/header100.png); + |background-position: top center; + |background-repeat: repeat-x; + |background-size: 2160px 108px; + |margin: 0; + |height: 108px; + |width: 100%;""".stripMargin + +for patternMatch <- keyValPattern.findAllMatchIn(input) do + println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}") +``` + +{% endtab %} + +{% endtabs %} + +Здесь мы обработали сразу и ключи и значения строки. В каждом совпадении есть подгруппа совпадений. Вот как выглядит результат: + +``` +key: background-color value: #A03300 +key: background-image value: url(img +key: background-position value: top center +key: background-repeat value: repeat-x +key: background-size value: 2160px 108px +key: margin value: 0 +key: height value: 108px +key: width value: 100 +``` + +Кроме того, регулярные выражения можно использовать в качестве шаблонов (в выражениях `match`) +для удобного извлечения совпавших групп: + +{% tabs regex-patterns_saveContactInformation class=tabs-scala-version %} + +{% tab 'Scala 2' for=regex-patterns_saveContactInformation %} + +```scala mdoc +def saveContactInformation(contact: String): Unit = { + import scala.util.matching.Regex + + val emailPattern: Regex = """^(\w+)@(\w+(.\w+)+)$""".r + val phonePattern: Regex = """^(\d{3}-\d{3}-\d{4})$""".r + + contact match { + case emailPattern(localPart, domainName, _) => + println(s"Hi $localPart, we have saved your email address.") + case phonePattern(phoneNumber) => + println(s"Hi, we have saved your phone number $phoneNumber.") + case _ => + println("Invalid contact information, neither an email address nor phone number.") + } +} + +saveContactInformation("123-456-7890") +saveContactInformation("JohnSmith@sample.domain.com") +saveContactInformation("2 Franklin St, Mars, Milky Way") +``` + +{% endtab %} + +{% tab 'Scala 3' for=regex-patterns_saveContactInformation %} + +```scala +def saveContactInformation(contact: String): Unit = + import scala.util.matching.Regex + + val emailPattern: Regex = """^(\w+)@(\w+(.\w+)+)$""".r + val phonePattern: Regex = """^(\d{3}-\d{3}-\d{4})$""".r + + contact match + case emailPattern(localPart, domainName, _) => + println(s"Hi $localPart, we have saved your email address.") + case phonePattern(phoneNumber) => + println(s"Hi, we have saved your phone number $phoneNumber.") + case _ => + println("Invalid contact information, neither an email address nor phone number.") + +saveContactInformation("123-456-7890") +saveContactInformation("JohnSmith@sample.domain.com") +saveContactInformation("2 Franklin St, Mars, Milky Way") +``` + +{% endtab %} + +{% endtabs %} + +Вот как выглядит результат: + +``` +Hi, we have saved your phone number 123-456-7890. +Hi JohnSmith, we have saved your email address. +Invalid contact information, neither an email address nor phone number. +``` diff --git a/_ru/tour/self-types.md b/_ru/tour/self-types.md new file mode 100644 index 0000000000..06597bfe70 --- /dev/null +++ b/_ru/tour/self-types.md @@ -0,0 +1,63 @@ +--- +layout: tour +title: Самоописываемые типы +partof: scala-tour +num: 25 +language: ru +next-page: implicit-parameters +previous-page: compound-types +topics: self-types +prerequisite-knowledge: nested-classes, mixin-class-composition +--- + +Самоописываемый тип (Self type) - это способ объявить, что трейт должен быть смешан с другим трейтом, даже если он не расширяет его напрямую. Что открывает доступ к членам зависимости без импортирования. + +Самоописываемый тип - это способ сузить тип `this` или другого идентификатора, который ссылается на `this`. Синтаксис похож на синтаксис обычной функции, но означает кое-что иное. + +Чтобы использовать самоописываемый тип в трейте напишите: идентификатор, тип другого трейта, который хотите добавить и `=>` (например, `someIdentifier: SomeOtherTrait =>`). + +{% tabs self-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=self-types_1 %} + +```scala mdoc +trait User { + def username: String +} + +trait Tweeter { + this: User => // переназначил this + def tweet(tweetText: String) = println(s"$username: $tweetText") +} + +class VerifiedTweeter(val username_ : String) extends Tweeter with User { // Мы добавили User потому этого требует Tweeter + def username = s"real $username_" +} + +val realBeyoncé = new VerifiedTweeter("Beyoncé") +realBeyoncé.tweet("Just spilled my glass of lemonade") // выведет "real Beyoncé: Just spilled my glass of lemonade" +``` + +Поскольку мы указали `this: User =>` в трейте `Tweeter`, теперь переменная `username` находится в пределах видимости для метода `tweet`. Это также означает что `VerifiedTweeter` при наследовании от `Tweeter` должен быть смешан с `User` (используя `with User`). + +{% endtab %} +{% tab 'Scala 3' for=self-types_1 %} + +```scala +trait User: + def username: String + +trait Tweeter: + this: User => // переназначил this + def tweet(tweetText: String) = println(s"$username: $tweetText") + +class VerifiedTweeter(val username_ : String) extends Tweeter, User: // Мы добавили User потому этого требует Tweeter + def username = s"real $username_" + +val realBeyoncé = VerifiedTweeter("Beyoncé") +realBeyoncé.tweet("Just spilled my glass of lemonade") // выведет "real Beyoncé: Just spilled my glass of lemonade" +``` + +Поскольку мы указали `this: User =>` в трейте `Tweeter`, теперь переменная `username` находится в пределах видимости для метода `tweet`. Это также означает что `VerifiedTweeter` при наследовании от `Tweeter` должен быть смешан с `User` (используя `, User`). + +{% endtab %} +{% endtabs %} diff --git a/_ru/tour/singleton-objects.md b/_ru/tour/singleton-objects.md new file mode 100644 index 0000000000..5a0da42d5c --- /dev/null +++ b/_ru/tour/singleton-objects.md @@ -0,0 +1,229 @@ +--- +layout: tour +title: Объекты Одиночки +partof: scala-tour +num: 13 +language: ru +next-page: regular-expression-patterns +previous-page: pattern-matching +prerequisite-knowledge: classes, methods, private-methods, packages, option +--- + +Все объекты являются одиночками (Singleton Object) - то есть существуют в единственном экземпляре. Он создается лениво, когда на него ссылаются, также как ленивые значения (lazy val). + +На самом верхнем уровне объект является одиночкой. + +Как член класса или как локальная переменная, он ведет себя точно так же как ленивое значение (lazy val). + +# Объявление одиночного объекта + +Объект - является значением. Объявление объекта происходит схожим с классом образом, но используется ключевое слово `object`: + +{% tabs object-definition-box %} + +{% tab 'Scala 2 и 3' for=object-definition-box %} + +```scala mdoc +object Box +``` + +{% endtab %} + +{% endtabs %} + +Вот пример объекта с методом: + +{% tabs singleton-logger-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=singleton-logger-example %} + +```scala +package logging + +object Logger { + def info(message: String): Unit = println(s"INFO: $message") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=singleton-logger-example %} + +```scala +package logging + +object Logger: + def info(message: String): Unit = println(s"INFO: $message") +``` + +{% endtab %} + +{% endtabs %} + +Метод `info` может быть импортирован в любом месте программы. Создание подобных методов является распространенным вариантом использования одиночных объектов. + +Давайте посмотрим, как использовать `info` в другом пакете: + +{% tabs singleton-usage-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=singleton-usage-example %} + +```scala +import logging.Logger.info + +class Project(name: String, daysToComplete: Int) + +class Test { + val project1 = new Project("TPS Reports", 1) + val project2 = new Project("Website redesign", 5) + info("Created projects") // Prints "INFO: Created projects" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=singleton-usage-example %} + +```scala +import logging.Logger.info + +class Project(name: String, daysToComplete: Int) + +class Test: + val project1 = Project("TPS Reports", 1) + val project2 = Project("Website redesign", 5) + info("Created projects") // Prints "INFO: Created projects" +``` + +{% endtab %} + +{% endtabs %} + +Метод `info` виден благодаря указанию импорта `import logging.Logger.info`. +Для импорта требуется "постоянный путь" к импортируемому символу, а путь к объекту неизменен. + +Замечание: Если `object` не является объектом верхнего уровня, но вложен в другой класс или объект, +то объект, как и любой другой член, "зависим от пути". +Это означает, что для двух видов напитков, `class Milk` и `class OrangeJuice`, +элемент класса `object NutritionInfo` "зависит" от включающего его экземпляра, будь то `Milk` или `OrangeJuice`. +`milk.NutritionInfo` полностью отличается от `oj.NutritionInfo`. + +## Объекты компаньоны + +Объект с тем же именем, что и класс называется _объект компаньон_ (companion object). И наоборот, класс является классом-компаньоном объекта. Класс или объект компаньон может получить доступ к приватным членам своего спутника. Используйте объект компаньон для методов и значений, которые не специфичны для экземпляров класса компаньона. + +{% tabs companion-object-circle class=tabs-scala-version %} + +{% tab 'Scala 2' for=companion-object-circle %} + +```scala +import scala.math.pow + +case class Circle(radius: Double) { + import Circle._ + def area: Double = calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = Circle(5.0) + +circle1.area +``` + +{% endtab %} + +{% tab 'Scala 3' for=companion-object-circle %} + +```scala +import scala.math.pow + +case class Circle(radius: Double): + import Circle.* + def area: Double = calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) + + +val circle1 = Circle(5.0) + +circle1.area +``` + +{% endtab %} + +{% endtabs %} + +Класс `Circle` имеет член `area`, который специфичен для каждого конкретного экземпляра, а метод `calculateArea` одиночного объекта `Circle`, доступен для каждого экземпляра класса `Circle`. + +Объект компаньон может также содержать методы создающие конкретные экземпляры класса спутника: +{% tabs companion-object-email class=tabs-scala-version %} + +{% tab 'Scala 2' for=companion-object-email %} + +```scala mdoc +class Email(val username: String, val domainName: String) + +object Email { + def fromString(emailString: String): Option[Email] = { + emailString.split('@') match { + case Array(a, b) => Some(new Email(a, b)) + case _ => None + } + } +} + +val scalaCenterEmail = Email.fromString("scala.center@epfl.ch") +scalaCenterEmail match { + case Some(email) => println( + s"""Registered an email + |Username: ${email.username} + |Domain name: ${email.domainName} + """.stripMargin) + case None => println("Error: could not parse email") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=companion-object-email %} + +```scala +class Email(val username: String, val domainName: String) + +object Email: + def fromString(emailString: String): Option[Email] = + emailString.split('@') match + case Array(a, b) => Some(Email(a, b)) + case _ => None + +val scalaCenterEmail = Email.fromString("scala.center@epfl.ch") +scalaCenterEmail match + case Some(email) => println( + s"""Registered an email + |Username: ${email.username} + |Domain name: ${email.domainName} + """.stripMargin) + case None => println("Error: could not parse email") +``` + +{% endtab %} + +{% endtabs %} + +`object Email` содержит производящий метод `fromString`, который создает экземпляр `Email` из строки. Мы возвращаем результат как `Option[Email]` на случай возникновения ошибок парсинга. + +Примечание: Если у класса или объекта есть компаньон, они должны быть размещены в одном и том же файле. Чтобы задать компаньонов в REPL, либо определите их на той же строке, либо перейдите в режим `:paste`. + +## Примечания для Java-программистов + +`static` члены в Java смоделированы как обычные члены объекта компаньона в Scala. + +При использовании объекта компаньона из Java-кода, члены будут определены в сопутствующем классе компаньоне с `static` модификатором. Это называется _пробрасывание статики_. Такое происходит, даже если вы сами не определили класс компаньон. + +## Дополнительные ресурсы + +- Узнайте больше об объектах компаньонах в [Scala Book](/ru/scala3/book/domain-modeling-tools.html#сопутствующие-объекты) diff --git a/_ru/tour/tour-of-scala.md b/_ru/tour/tour-of-scala.md new file mode 100644 index 0000000000..62f9fbe592 --- /dev/null +++ b/_ru/tour/tour-of-scala.md @@ -0,0 +1,65 @@ +--- +layout: tour +title: Введение +partof: scala-tour +num: 1 +language: ru +next-page: basics +--- + +## Добро пожаловать к обзору + +Здесь вы увидите вводное описание наиболее часто используемых возможностей Scala. +Этот обзор предназначен для новичков в изучении языка. + +Это лишь небольшая экскурсия, а не полный курс освоения языка. Для глубокого погружения рекомендуем почитать [книги](/books.html) или воспользоваться курсами +[на других ресурсах](/online-courses.html). + +## Что такое Scala? + +Scala - это современный мультипарадигмальный язык программирования, разработанный для выражения общих концепций программирования в простой, удобной и типобезопасной манере. Элегантно объединяя особенности объектно-ориентированных и функциональных языков. + +## Scala объектно ориентированный + +Scala - это чистый объектно-ориентированный язык в том смысле, что [каждое значение - это объект](unified-types.html). Типы и поведение объектов описаны в [классах](classes.html) и [трейтах](traits.html)(характеристиках объектов). Классы расширяются за счет механизма наследования и гибкого [смешивания классов](mixin-class-composition.html), который используется для замены множественного наследования. + +## Scala функциональный + +Scala также является функциональным языком в том смысле, что [каждая функция - это значение](unified-types.html). Scala предоставляет [легкий синтаксис](basics.html) для определения анонимных функций, поддерживает [функции высшего порядка](higher-order-functions.html), поддерживает [вложенные функции](nested-functions.html), а также [каррирование](multiple-parameter-lists.html). Scala имеют встроенную поддержку алгебраических типов данных, которые используются в большинстве функциональных языках программирования (эта поддержка базируется на механизме [сопоставления с примером](pattern-matching.html), где в качестве примера выступают [классы образцы](case-classes.html) ). [Объекты](singleton-objects.html) предоставляют удобный способ группировки функций, не входящих в класс. + +Вдобавок к этому, концепция сопоставления с примером логично переносится на [обработку XML-данных](https://github.com/scala/scala-xml/wiki/XML-Processing) используя в качестве примера [регулярные выражения](regular-expression-patterns.html), при поддержке функционала [объектов экстракторов](extractor-objects.html). Для еще большего удобства обработки данных представлена схема формирования запросов с использованием [for-выражения](for-comprehensions.html). Такие возможности делают Scala идеальным решением для разработки приложений по типу веб-сервисов. + +## Scala статически типизированный + +Scala оснащен выразительной системой типов, которая обеспечивает безопасное и гармоничное использование абстракций. В частности, система типов поддерживает: + +- [обобщенные классы](generic-classes.html) +- [вариантность типов](variances.html) +- [верхние](upper-type-bounds.html) и [нижние](lower-type-bounds.html) границы типов +- [внутренние классы](inner-classes.html) и [члены абстрактного типа](abstract-type-members.html), как часть объектов +- [составные типы](compound-types.html) +- [самоописываемые типы](self-types.html) +- [неявные параметры](implicit-parameters.html) и [неявные преобразования](implicit-conversions.html) +- [полиморфные методы](polymorphic-methods.html) + +[Выведение типов](type-inference.html) означает, что разработчику не обязательно добавлять в код избыточную информацию о типах. +Такой функционал обеспечивает основу для безопасного переиспользования абстракций и типобезопасного развития программного обеспечения. + +## Scala расширяемый + +Зачастую разработка приложений для очень специфичных областей требует специфичных для этих областей языковых возможностей, либо отдельных специализированных языков программирования. Вместо этого Scala предлагает уникальные механизмы, для легкой модификации и расширения самого языка. + +Во многих случаях такое можно сделать без использования средств мета-программирования, таких как макросы. Например: + +- [Неявные классы](https://docs.scala-lang.org/overviews/core/implicit-classes.html) позволяют добавлять новые методы к уже существующим. +- [Интерполяция строк](/ru/scala3/book/string-interpolation.html) позволяет добавлять обработку строк (расширяется разработчиком с помощью интерполяторов). + +## Scala совместимый + +Scala полностью совместим с популярной средой Java Runtime Environment (JRE). Взаимодействие с основным объектно-ориентированным языком программирования Java происходит максимально гладко. Новые функции Java, такие как SAM, [лямбды](higher-order-functions.html), [аннотации](annotations.html) и [дженерики](generic-classes.html), имеют прямые аналоги в Scala. + +Те функции Scala, которые не имеют аналогов в Java, такие как [параметры по умолчанию](default-parameter-values.html) и [именованные параметры](named-arguments.html), компилируются как можно ближе к Java. Scala имеет такую же компиляционную модель (отдельная компиляция, динамическая загрузка классов), как у Java, что позволяет получить доступ к тысячам уже существующих высококачественных библиотек. + +## Наслаждайтесь туром! + +Для продолжения знакомства предлагаю перейти на [следующую страницу](basics.html) нашего тура. diff --git a/_ru/tour/traits.md b/_ru/tour/traits.md new file mode 100644 index 0000000000..ef958c94cf --- /dev/null +++ b/_ru/tour/traits.md @@ -0,0 +1,179 @@ +--- +layout: tour +title: Трейты +partof: scala-tour +num: 5 +language: ru +next-page: tuples +previous-page: named-arguments +topics: traits +prerequisite-knowledge: expressions, classes, generics, objects, companion-objects +--- + +Трейты (Traits) используются, чтобы обмениваться между классами информацией о структуре и полях. Они похожи на интерфейсы из Java 8. Классы и объекты могут расширять трейты, но трейты не могут быть созданы и поэтому не имеют параметров. + +## Объявление трейта + +Минимальное объявление трейта - это просто ключевое слово `trait` и его имя: + +{% tabs trait-hair-color %} +{% tab 'Scala 2 и 3' for=trait-hair-color %} + +```scala mdoc +trait HairColor +``` + +{% endtab %} +{% endtabs %} + +Трейты наиболее полезны в качестве обобщенного типа с абстрактными методами. + +{% tabs trait-iterator-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=trait-iterator-definition %} + +```scala mdoc +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=trait-iterator-definition %} + +```scala +trait Iterator[A]: + def hasNext: Boolean + def next(): A +``` + +{% endtab %} + +{% endtabs %} + +При наследовании от трейта `Iterator[A]` требует указание типа `A` а также реализация методов `hasNext` и `next`. + +## Использование трейтов + +Чтобы использовать трейты, необходимо наследовать класс от него, используя ключевое слово `extends`. Затем необходимо реализовать все абстрактные члены трейта, используя ключевое слово `override`: + +{% tabs trait-intiterator-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=trait-intiterator-definition %} + +```scala mdoc:nest +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} + +class IntIterator(to: Int) extends Iterator[Int] { + private var current = 0 + override def hasNext: Boolean = current < to + override def next(): Int = { + if (hasNext) { + val t = current + current += 1 + t + } else 0 + } +} + +val iterator = new IntIterator(10) +iterator.next() // вернет 0 +iterator.next() // вернет 1 +``` + +{% endtab %} + +{% tab 'Scala 3' for=trait-intiterator-definition %} + +```scala +trait Iterator[A]: + def hasNext: Boolean + def next(): A + +class IntIterator(to: Int) extends Iterator[Int]: + private var current = 0 + override def hasNext: Boolean = current < to + override def next(): Int = + if hasNext then + val t = current + current += 1 + t + else + 0 +end IntIterator + +val iterator = new IntIterator(10) +iterator.next() // вернет 0 +iterator.next() // вернет 1 +``` + +{% endtab %} + +{% endtabs %} + +Этот класс `IntIterator` использует параметр `to` в качестве верхней границы. Он наследуется от `Iterator[Int]`, что означает, что метод `next` должен возвращать Int. + +## Подтипы + +Туда, где требуется определенный тип трейта, мы можем передавать любой наследованный от требуемого трейта класс + +{% tabs trait-pet-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=trait-pet-example %} + +```scala mdoc +import scala.collection.mutable.ArrayBuffer + +trait Pet { + val name: String +} + +class Cat(val name: String) extends Pet +class Dog(val name: String) extends Pet + +val dog = new Dog("Harry") +val cat = new Cat("Sally") + +val animals = ArrayBuffer.empty[Pet] +animals.append(dog) +animals.append(cat) +animals.foreach(pet => println(pet.name)) // выведет "Harry" и "Sally" +``` + +{% endtab %} + +{% tab 'Scala 3' for=trait-pet-example %} + +```scala +import scala.collection.mutable.ArrayBuffer + +trait Pet: + val name: String + +class Cat(val name: String) extends Pet +class Dog(val name: String) extends Pet + +val dog = Dog("Harry") +val cat = Cat("Sally") + +val animals = ArrayBuffer.empty[Pet] +animals.append(dog) +animals.append(cat) +animals.foreach(pet => println(pet.name)) // выведет "Harry" и "Sally" +``` + +{% endtab %} + +{% endtabs %} + +У трейта `Pet` есть абстрактное поле `name`, которое реализовано в классах `Cat` and `Dog`. В последней строке мы вызываем `pet.name`, который должен быть реализован в любом подтипе, унаследованном от трейта `Pet`. + +## Дополнительные ресурсы + +- Узнайте больше о трейтах в [Scala Book](/ru/scala3/book/domain-modeling-tools.html#трейты) +- Использование трейтов для определения [Enum](/ru/scala3/book/domain-modeling-fp.html#моделирование-данных) diff --git a/_ru/tour/tuples.md b/_ru/tour/tuples.md new file mode 100644 index 0000000000..8f1550c473 --- /dev/null +++ b/_ru/tour/tuples.md @@ -0,0 +1,142 @@ +--- +layout: tour +title: Кортежи +partof: scala-tour +num: 6 +language: ru +next-page: mixin-class-composition +previous-page: traits +topics: tuples +--- + +В Scala, кортеж (Тuple) - это контейнер содержащий упорядоченный набор элементов различного типа. +Кортежи неизменяемы. + +Кортежи могут пригодиться, когда нам нужно вернуть сразу несколько значений из функции. + +Кортеж может быть создан как: + +{% tabs tuple-construction %} + +{% tab 'Scala 2 и 3' for=tuple-construction %} + +```scala mdoc +val ingredient = ("Sugar", 25) +``` + +{% endtab %} + +{% endtabs %} + +Такая запись создает кортеж, содержащий пару элементов `String` и `Int`. + +Выводимый тип `ingredient` - это `(String, Int)`. + +## Доступ к элементам + +{% tabs tuple-indexed-access class=tabs-scala-version %} + +{% tab 'Scala 2' for=tuple-indexed-access %} + +Один из способов доступа к элементам кортежа — по их позиции. +`tuple._n` дает n-ый элемент (столько, сколько существует элементов). + +```scala mdoc +println(ingredient._1) // Sugar +println(ingredient._2) // 25 +``` + +{% endtab %} + +{% tab 'Scala 3' for=tuple-indexed-access %} + +Один из способов доступа к элементам кортежа — по их позиции. +Доступ к отдельным элементам осуществляется с помощью `tuple(0)`, `tuple(1)` и так далее. + +```scala +println(ingredient(0)) // Sugar +println(ingredient(1)) // 25 +``` + +{% endtab %} + +{% endtabs %} + +## Сопоставление с образцом для кортежей + +Кортеж также можно распаковать с помощью сопоставления с образцом: + +{% tabs tuple-extraction %} + +{% tab 'Scala 2 и 3' for=tuple-extraction %} + +```scala mdoc +val (name, quantity) = ingredient +println(name) // Sugar +println(quantity) // 25 +``` + +{% endtab %} + +{% endtabs %} + +Здесь выводимый тип `name` - `String` и выводимый тип `quantity` - `Int`. + +Вот еще один пример сопоставления с образцом кортежа: + +{% tabs tuple-foreach-patmat %} + +{% tab 'Scala 2 и 3' for=tuple-foreach-patmat %} + +```scala mdoc +val planets = + List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6), + ("Mars", 227.9), ("Jupiter", 778.3)) +planets.foreach { + case ("Earth", distance) => + println(s"Our planet is $distance million kilometers from the sun") + case _ => +} +``` + +{% endtab %} + +{% endtabs %} + +Или, в _for-comprehension_: + +{% tabs tuple-for-extraction class=tabs-scala-version %} + +{% tab 'Scala 2' for=tuple-for-extraction %} + +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) +for ((a, b) <- numPairs) { + println(a * b) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=tuple-for-extraction %} + +```scala +val numPairs = List((2, 5), (3, -7), (20, 56)) +for (a, b) <- numPairs do + println(a * b) +``` + +{% endtab %} + +{% endtabs %} + +## Кортежи и кейс-классы + +Иногда бывает трудно выбирать между кортежами и кейс-классами. +Кейс-классы содержат именованные элементы. Имена могут улучшить читаемость некоторых типов кода. +В приведенном выше примере мы могли бы определить планеты, как `case class Planet(name: String, distance: Double)`, +а не использовать кортежи. + +## Дополнительные ресурсы + +- Дополнительная информация о кортежах - в книге [Scala Book](/ru/scala3/book/taste-collections.html#кортежи) diff --git a/_ru/tour/type-inference.md b/_ru/tour/type-inference.md new file mode 100644 index 0000000000..52f0836467 --- /dev/null +++ b/_ru/tour/type-inference.md @@ -0,0 +1,122 @@ +--- +layout: tour +title: Выведение Типа +partof: scala-tour +num: 29 +language: ru +next-page: operators +previous-page: polymorphic-methods +--- + +Компилятор Scala часто может вывести тип выражения, так что вам не нужно указывать его явным образом. + +## Не указывая тип + +{% tabs type-inference_1 %} +{% tab 'Scala 2 и 3' for=type-inference_1 %} + +```scala mdoc +val businessName = "Montreux Jazz Café" +``` + +{% endtab %} +{% endtabs %} + +Компилятор может определить, что тип константы `businessName` является `String`. Аналогичным образом это работает и для методов: + +{% tabs type-inference_2 %} +{% tab 'Scala 2 и 3' for=type-inference_2 %} + +```scala mdoc +def squareOf(x: Int) = x * x +``` + +{% endtab %} +{% endtabs %} + +Компилятор может определить, что возвращаемый тип является `Int`, поэтому явного указания типа не требуется. + +Для рекурсивных методов компилятор не в состоянии вывести тип. Вот программа, которая не скомпилируется по этой причине: + +{% tabs type-inference_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=type-inference_3 %} + +```scala mdoc:fail +def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1) +``` + +{% endtab %} +{% tab 'Scala 3' for=type-inference_3 %} + +```scala +def fac(n: Int) = if n == 0 then 1 else n * fac(n - 1) +``` + +{% endtab %} +{% endtabs %} + +Также необязательно указывать параметры типа при вызове [полиморфных методов](polymorphic-methods.html) или [обобщенных классов](generic-classes.html). Компилятор Scala определит тип параметра из контекста и из типов фактически передаваемых параметров метода/конструктора. + +Вот два примера: + +{% tabs type-inference_4 %} +{% tab 'Scala 2 и 3' for=type-inference_4 %} + +```scala mdoc +case class MyPair[A, B](x: A, y: B) +val p = MyPair(1, "scala") // тип: MyPair[Int, String] + +def id[T](x: T) = x +val q = id(1) // тип: Int +``` + +{% endtab %} +{% endtabs %} + +Компилятор использует типы аргументов `MyPair` для определения типа `A` и `B`. Тоже самое для типа `x`. + +## Параметры + +Для параметров компилятор никогда не выводит тип. Однако, в некоторых случаях, он может вывести типы для параметров анонимной функции при передаче ее в качестве аргумента. + +{% tabs type-inference_5 %} +{% tab 'Scala 2 и 3' for=type-inference_5 %} + +```scala mdoc +Seq(1, 3, 4).map(x => x * 2) // List(2, 6, 8) +``` + +{% endtab %} +{% endtabs %} + +Параметр у map - `f: A => B` (функциональный параметр переводящий тип из A в B). Поскольку мы разместили целые числа в нашей последовательности `Seq`, компилятор знает, что элемент `A` является `Int` (т.е. `x` является целым числом). Поэтому компилятор может определить из выражения `x * 2`, что результат (`B`) является типом `Int`. + +## Когда _не следует_ полагаться на выведение типа + +Обычно считается, наиболее удобочитаемым объявить тип членов, которые открыты для публичного использования через API. Поэтому мы рекомендуем вам явно указывать тип для любых API, которые будут доступны пользователям вашего кода. + +Кроме того, выведение может иногда приводить к слишком специфичному типу. Предположим, мы напишем: + +{% tabs type-inference_6 %} +{% tab 'Scala 2 и 3' for=type-inference_6 %} + +```scala +var obj = null +``` + +{% endtab %} +{% endtabs %} + +Тогда мы не сможем далее сделать это переназначение: + +{% tabs type-inference_7 %} +{% tab 'Scala 2 и 3' for=type-inference_7 %} + +```scala mdoc:fail +obj = new AnyRef +``` + +{% endtab %} +{% endtabs %} + +Такое не будет компилироваться, потому что для `obj` предполагался тип `Null`. Поскольку единственным значением этого типа является `null`, то невозможно присвоить другое значение. diff --git a/_ru/tour/unified-types.md b/_ru/tour/unified-types.md new file mode 100644 index 0000000000..e5f947ed89 --- /dev/null +++ b/_ru/tour/unified-types.md @@ -0,0 +1,97 @@ +--- +layout: tour +title: Единобразие типов +partof: scala-tour +num: 3 +language: ru +next-page: classes +previous-page: basics +prerequisite-knowledge: classes, basics +--- + +В Scala все значения имеют тип, включая числовые значения и функции. Диаграмма ниже иллюстрирует подмножество иерархии типов. + +Scala Type Hierarchy + +## Иерархия типов Scala + +[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html) это супертип всех типов, также называемый верхним типом. Он определяет несколько универсальных методов, таких как `equals`, `hashCode` и `toString`. У `Any` есть два прямых подкласса: `AnyVal` и `AnyRef`. + +`AnyVal` представляет числовые типы. Существует девять предварительно определенных числовых типов и они никогда не могут быть равны 'null': `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit`, и `Boolean`. `Unit` - это числовой тип, который не содержит значимой информации (также обозначает пустое множество). Есть только один представитель типа `Unit`, который можно объявить вот так: `()`. Все функции должны возвращать что-то, поэтому иногда `Unit` полезный для возврата тип. + +`AnyRef` представляет ссылочные типы. Все типы, не относящиеся к "числовым типам", называются ссылочными типами. Каждый объявляемый пользователем тип в Scala является подтипом `AnyRef`. Если в Scala исходить из контекста среды исполнения Java, `AnyRef` соответствует `java.lang.Object`. + +Вот пример, демонстрирующий, что строки, целые числа, символы, логические значения и функции являются объектами, как и любой другой объект: + +{% tabs unified-types-1 %} +{% tab 'Scala 2 и 3' for=unified-types-1 %} + +```scala mdoc +val list: List[Any] = List( + "a string", + 732, // целое число + 'c', // символ + true, // логическое значение + () => "анонимная функция возвращающая строку" +) + +list.foreach(element => println(element)) +``` + +{% endtab %} +{% endtabs %} + +Объявляем переменную `list` типа `List[Any]`. Список инициализируется элементами различных типов, но все они являются экземпляром `scala.Any`, так что вы можете добавить их в список. + +Ниже приведен вывод программы: + +``` +a string +732 +c +true + +``` + +## Приведение типа + +Числовые типы могут быть приведены следующим образом: +Scala Type Hierarchy + +Например: + +{% tabs unified-types-2 %} +{% tab 'Scala 2 и 3' for=unified-types-2 %} + +```scala mdoc +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 (заметьте, что некоторая точность теряется в этом случае.) + +val face: Char = '☺' +val number: Int = face // 9786 +``` + +{% endtab %} +{% endtabs %} + +Приведение типа - однонаправленно. Следующий пример не скомпилируется: + +{% tabs unified-types-3 %} +{% tab 'Scala 2 и 3' for=unified-types-3 %} + +``` +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 +val z: Long = y // обратно не подходит +``` + +{% endtab %} +{% endtabs %} + +Вы также можете приводить к своему подтипу. Об этом мы поговорим позже в ходе нашего обзора. + +## Nothing и Null + +`Nothing` является подтипом всех типов, также называемым нижним типом. Нет значения, которое имеет тип `Nothing`. Обычно он используется чтоб дать сигнал о не вычислимости, например брошено исключение, выход из программы, бесконечное зацикливание (т.е. это тип выражения, которое не вычисляется). + +`Null` подтип всех ссылочных типов (т.е. любой подтип AnyRef). Он имеет одно значение, определяемое ключевым словом литерала `null`. `Null` предоставляется в основном для функциональной совместимости с другими языками JVM и почти никогда не должен использоваться в коде Scala. Об альтернативах `null` мы поговорим позднее. diff --git a/_ru/tour/upper-type-bounds.md b/_ru/tour/upper-type-bounds.md new file mode 100644 index 0000000000..7a9238016e --- /dev/null +++ b/_ru/tour/upper-type-bounds.md @@ -0,0 +1,96 @@ +--- +layout: tour +title: Верхнее Ограничение Типа +partof: scala-tour +categories: tour +num: 20 +language: ru +next-page: lower-type-bounds +previous-page: variances +--- + +В Scala [параметры типа](generic-classes.html) и [члены абстрактного типа](abstract-type-members.html) могут быть ограничены определенными диапазонами. Такие диапазоны ограничивают конкретные значение типа и, возможно, предоставляют больше информации о членах таких типов. _Верхнее ограничение типа_ `T <: A` указывает на то что тип `T` относится к подтипу типа `A`. +Приведем пример, демонстрирующий верхнее ограничение для типа класса `PetContainer`: + +{% tabs upper-type-bounds class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds %} + +```scala mdoc +abstract class Animal { + def name: String +} + +abstract class Pet extends Animal {} + +class Cat extends Pet { + override def name: String = "Cat" +} + +class Dog extends Pet { + override def name: String = "Dog" +} + +class Lion extends Animal { + override def name: String = "Lion" +} + +class PetContainer[P <: Pet](p: P) { + def pet: P = p +} + +val dogContainer = new PetContainer[Dog](new Dog) +val catContainer = new PetContainer[Cat](new Cat) +``` + +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds %} + +```scala +abstract class Animal: + def name: String + +abstract class Pet extends Animal + +class Cat extends Pet: + override def name: String = "Cat" + +class Dog extends Pet: + override def name: String = "Dog" + +class Lion extends Animal: + override def name: String = "Lion" + +class PetContainer[P <: Pet](p: P): + def pet: P = p + +val dogContainer = PetContainer[Dog](Dog()) +val catContainer = PetContainer[Cat](Cat()) +``` + +{% endtab %} +{% endtabs %} + +{% tabs upper-type-bounds_error class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_error %} + +```scala mdoc:fail +// это не скомпилируется +val lionContainer = new PetContainer[Lion](new Lion) +``` + +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_error %} + +```scala +// это не скомпилируется +val lionContainer = PetContainer[Lion](Lion()) +``` + +{% endtab %} +{% endtabs %} + +Класс `PetContainer` принимает тип `P`, который должен быть подтипом `Pet`. `Dog` и `Cat` - это подтипы `Pet`, поэтому мы можем создать новые `PetContainer[Dog]` и `PetContainer[Cat]`. Однако, если мы попытаемся создать `PetContainer[Lion]`, то получим следующую ошибку: + +`type arguments [Lion] do not conform to class PetContainer's type parameter bounds [P <: Pet]` + +Это потому, что `Lion` не является подтипом `Pet`. diff --git a/_ru/tour/variances.md b/_ru/tour/variances.md new file mode 100644 index 0000000000..c122728f51 --- /dev/null +++ b/_ru/tour/variances.md @@ -0,0 +1,294 @@ +--- +layout: tour +title: Вариантность +partof: scala-tour +num: 19 +language: ru +next-page: upper-type-bounds +previous-page: generic-classes +--- + +Вариантность (Variances) - это указание определенной специфики взаимосвязи между связанными типами. +Scala поддерживает вариантную аннотацию типов у [обобщенных классов](generic-classes.html), +что позволяет им быть ковариантными, контрвариантными или инвариантными (если нет никакого указания на вариантность). +Использование вариантности в системе типов позволяет устанавливать понятные взаимосвязи между сложными типами, +в то время как отсутствие вариантности может ограничить повторное использование абстракции класса. + +{% tabs variances_1 %} +{% tab 'Scala 2 и 3' for=variances_1 %} + +```scala mdoc +class Foo[+A] // ковариантный класс +class Bar[-A] // контравариантный класс +class Baz[A] // инвариантный класс +``` + +{% endtab %} +{% endtabs %} + +### Инвариантность + +По умолчанию параметры типа в Scala инвариантны: отношения подтипа между параметрами типа не отражаются в параметризованном типе. +Чтобы понять, почему это работает именно так, рассмотрим простой параметризованный тип, изменяемый контейнер. + +{% tabs invariance_1 %} +{% tab 'Scala 2 и 3' for=invariance_1 %} + +```scala mdoc +class Box[A](var content: A) +``` + +{% endtab %} +{% endtabs %} + +Мы собираемся поместить в него значения типа `Animal` (животное). Этот тип определяется следующим образом: + +{% tabs invariance_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=invariance_2 %} + +```scala mdoc +abstract class Animal { + def name: String +} +case class Cat(name: String) extends Animal +case class Dog(name: String) extends Animal +``` + +{% endtab %} +{% tab 'Scala 3' for=invariance_2 %} + +```scala +abstract class Animal: + def name: String + +case class Cat(name: String) extends Animal +case class Dog(name: String) extends Animal +``` + +{% endtab %} +{% endtabs %} + +Можно сказать, что `Cat` (кот) - это подтип `Animal`, `Dog` (собака) - также подтип `Animal`. +Это означает, что следующее допустимо и пройдет проверку типов: + +{% tabs invariance_3 %} +{% tab 'Scala 2 и 3' for=invariance_3 %} + +```scala mdoc +val myAnimal: Animal = Cat("Felix") +``` + +{% endtab %} +{% endtabs %} + +А контейнеры? +Является ли `Box[Cat]` подтипом `Box[Animal]`, как `Cat` подтип `Animal`? +На первый взгляд может показаться, что это правдоподобно, +но если мы попытаемся это сделать, компилятор сообщит об ошибке: + +{% tabs invariance_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=invariance_4 %} + +```scala mdoc:fail +val myCatBox: Box[Cat] = new Box[Cat](Cat("Felix")) +val myAnimalBox: Box[Animal] = myCatBox // не компилируется +val myAnimal: Animal = myAnimalBox.content +``` + +{% endtab %} +{% tab 'Scala 3' for=invariance_4 %} + +```scala +val myCatBox: Box[Cat] = Box[Cat](Cat("Felix")) +val myAnimalBox: Box[Animal] = myCatBox // не компилируется +val myAnimal: Animal = myAnimalBox.content +``` + +{% endtab %} +{% endtabs %} + +Почему это может быть проблемой? +Мы можем достать из контейнера кота, и это все еще животное, не так ли? Ну да. +Но это не все, что мы можем сделать. Мы также можем заменить в контейнере кота другим животным. + +{% tabs invariance_5 %} +{% tab 'Scala 2 и 3' for=invariance_5 %} + +```scala + myAnimalBox.content = Dog("Fido") +``` + +{% endtab %} +{% endtabs %} + +Теперь в контейнере для животных есть собака. +Все в порядке, вы можете поместить собак в контейнеры для животных, потому что собаки — это животные. +Но наш контейнер для животных — это контейнер для котов! Нельзя поместить собаку в контейнер с котом. +Если бы мы могли, а затем попытались достать кота из нашего кошачьего контейнера, +он оказался бы собакой, нарушающей целостность типа. + +{% tabs invariance_6 %} +{% tab 'Scala 2 и 3' for=invariance_6 %} + +```scala + val myCat: Cat = myCatBox.content // myCat стал бы собакой Fido! +``` + +{% endtab %} +{% endtabs %} + +Из этого мы должны сделать вывод, что между `Box[Cat]` и `Box[Animal]` не может быть отношения подтипа, +хотя между `Cat` и `Animal` это отношение есть. + +### Ковариантность + +Проблема, с которой мы столкнулись выше, заключается в том, +что, поскольку мы можем поместить собаку в контейнер для животных, +контейнер для кошек не может быть контейнером для животных. + +Но что, если мы не сможем поместить собаку в контейнер? +Тогда мы бы могли просто вернуть нашего кота, и это не проблема, чтобы можно было следовать отношениям подтипа. +Оказывается, это действительно то, что мы можем сделать. + +{% tabs covariance_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=covariance_1 %} + +```scala mdoc +class ImmutableBox[+A](val content: A) +val catbox: ImmutableBox[Cat] = new ImmutableBox[Cat](Cat("Felix")) +val animalBox: ImmutableBox[Animal] = catbox // теперь код компилируется +``` + +{% endtab %} +{% tab 'Scala 3' for=covariance_1 %} + +```scala +class ImmutableBox[+A](val content: A) +val catbox: ImmutableBox[Cat] = ImmutableBox[Cat](Cat("Felix")) +val animalBox: ImmutableBox[Animal] = catbox // теперь код компилируется +``` + +{% endtab %} +{% endtabs %} + +Мы говорим, что `ImmutableBox` _ковариантен_ в `A` - на это указывает `+` перед `A`. + +Более формально это дает нам следующее отношение: +если задано некоторое `class Cov[+T]`, то если `A` является подтипом `B`, то `Cov[A]` является подтипом `Cov[B]`. +Это позволяет создавать очень полезные и интуитивно понятные отношения подтипов с помощью обобщения. + +В следующем менее надуманном примере метод `printAnimalNames` принимает список животных в качестве аргумента +и печатает их имена с новой строки. +Если бы `List[A]` не был бы ковариантным, последние два вызова метода не компилировались бы, +что сильно ограничивало бы полезность метода `printAnimalNames`. + +{% tabs covariance_2 %} +{% tab 'Scala 2 и 3' for=covariance_2 %} + +```scala mdoc +def printAnimalNames(animals: List[Animal]): Unit = + animals.foreach { + animal => println(animal.name) + } + +val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom")) +val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex")) + +// печатает: "Whiskers", "Tom" +printAnimalNames(cats) + +// печатает: "Fido", "Rex" +printAnimalNames(dogs) +``` + +{% endtab %} +{% endtabs %} + +### Контрвариантность + +Мы видели, что можем достичь ковариантности, убедившись, что не сможем поместить что-то в ковариантный тип, а только что-то получить. +Что, если бы у нас было наоборот, что-то, что можно положить, но нельзя вынуть? +Такая ситуация возникает, если у нас есть что-то вроде сериализатора, который принимает значения типа `A` +и преобразует их в сериализованный формат. + +{% tabs contravariance_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=contravariance_1 %} + +```scala mdoc +abstract class Serializer[-A] { + def serialize(a: A): String +} + +val animalSerializer: Serializer[Animal] = new Serializer[Animal] { + def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }""" +} +val catSerializer: Serializer[Cat] = animalSerializer +catSerializer.serialize(Cat("Felix")) +``` + +{% endtab %} +{% tab 'Scala 3' for=contravariance_1 %} + +```scala +abstract class Serializer[-A]: + def serialize(a: A): String + +val animalSerializer: Serializer[Animal] = Serializer[Animal](): + def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }""" + +val catSerializer: Serializer[Cat] = animalSerializer +catSerializer.serialize(Cat("Felix")) +``` + +{% endtab %} +{% endtabs %} + +Мы говорим, что `Serializer` _контравариантен_ в `A`, и на это указывает `-` перед `A`. +Более общий сериализатор является подтипом более конкретного сериализатора. + +Более формально это дает нам обратное отношение: если задано некоторое `class Contra[-T]`, +то если `A` является подтипом `B`, `Contra[B]` является подтипом `Contra[A]`. + +### Неизменность и вариантность + +Неизменяемость является важной частью проектного решения, связанного с использованием вариантности. +Например, коллекции Scala систематически различают [изменяемые и неизменяемые коллекции](https://docs.scala-lang.org/ru/overviews/collections-2.13/overview.html). +Основная проблема заключается в том, что ковариантная изменяемая коллекция может нарушить безопасность типов. +Вот почему `List` - ковариантная коллекция, а `scala.collection.mutable.ListBuffer` - инвариантная коллекция. +`List` - это коллекция в `package scala.collection.immutable`, поэтому она гарантированно будет неизменяемой для всех. +Принимая во внимание, что `ListBuffer` изменяем, то есть вы можете обновлять, добавлять или удалять элементы `ListBuffer`. + +Чтобы проиллюстрировать проблему ковариантности и изменчивости, предположим, +что `ListBuffer` ковариантен, тогда следующий проблемный пример скомпилируется (на самом деле он не компилируется): + +{% tabs immutability_and_variance_2 %} +{% tab 'Scala 2 и 3' %} + +```scala mdoc:fail +import scala.collection.mutable.ListBuffer + +val bufInt: ListBuffer[Int] = ListBuffer[Int](1,2,3) +val bufAny: ListBuffer[Any] = bufInt +bufAny(0) = "Hello" +val firstElem: Int = bufInt(0) +``` + +{% endtab %} +{% endtabs %} + +Если бы приведенный выше код был бы возможен, то вычисление `firstElem` завершилась бы ошибкой с `ClassCastException`, +потому что `bufInt(0)` теперь содержит `String`, а не `Int`. + +Инвариантность `ListBuffer` означает, что `ListBuffer[Int]` не является подтипом `ListBuffer[Any]`, +несмотря на то, что `Int` является подтипом `Any`, +и поэтому `bufInt` не может быть присвоен в качестве значения `bufAny`. + +### Сравнение с другими языками + +В языках, похожих на Scala, разные способы поддержки вариантности. +Например, указания вариантности в Scala очень похожи на то, как это делается в C#, +где такие указания добавляются при объявлении абстракции класса (вариантность при объявлении). +Однако в Java, указание вариантности задается непосредственно при использовании абстракции класса (вариантность при использовании). + +Тенденция Scala к неизменяемым типам делает ковариантные и контравариантные типы более распространенными, +чем в других языках, поскольку изменяемый универсальный тип должен быть инвариантным. diff --git a/_sass/base/helper.scss b/_sass/base/helper.scss index 1b32d31165..8b6f9c46d2 100755 --- a/_sass/base/helper.scss +++ b/_sass/base/helper.scss @@ -3,12 +3,50 @@ //------------------------------------------------ .wrap { - @include outer-container; - @include padding(0 20px); + @include outer-container; + @include padding(0 20px); +} + +.place-inline { + // add vertical margin + @include outer-container; + @include margin(20px 0); +} + +.inline-sticky-top { + position: sticky; + top: 15px; + margin-bottom: 25px; + background: #fff; + -webkit-box-shadow: 0 0 18px 20px #fff; + -moz-box-shadow: 0 0 18px 20px #fff; + box-shadow: 0 0 18px 20px #fff; + z-index: 5; +} + +.inline-sticky-top.inline-sticky-top-higher { + z-index: 7; +} + +.wrap-inline { + // add vertical padding + @include outer-container; + @include padding(20px 0); +} + +.wrap-tab { + @extend .wrap-narrow; + margin-top: 20px; + margin-bottom: 20px; +} + +.wrap-narrow { + @include outer-container; + @include padding(0 10px); } .dot { - font-size: 10px; - color: rgba($base-font-color-light, 0.6); - margin: 0 3px; + font-size: 10px; + color: rgba($base-font-color-light, 0.6); + margin: 0 3px; } diff --git a/_sass/components/alt-details.scss b/_sass/components/alt-details.scss new file mode 100644 index 0000000000..c86febae5d --- /dev/null +++ b/_sass/components/alt-details.scss @@ -0,0 +1,83 @@ +// ALT-DETAILS +//------------------------------------------------ +//------------------------------------------------ + +.alt-details.help-info { + .alt-details-toggle { + background-color: $brand-primary; + color: white; + + &:hover { + background-color: darken($brand-primary, 15%); + } + } + + .alt-details-detail { + background: #fae6e6 + } +} + +.alt-details { + @include span-columns(12); + + .alt-details-toggle { + @include span-columns(12); + font-family: $base-font-family; + line-height: normal; + text-align: center; + border: none; + background-color: $brand-tertiary; + padding: 5px 10px; + border-radius: $border-radius-large; + font-size: $font-size-medium; + cursor: pointer; + font-weight: 500; + color: $gray-dark; + + &:hover { + background-color: darken($brand-tertiary, 15%); + } + + &:after { + // show a right arrow at the end of the toggle element + content: "\f138"; // + font-family: "Font Awesome 5 Free"; + font-weight: 900; + font-size: 15px; + float: right; + margin-top: 2px; + } + + } + + .alt-details-control { + margin: 0; + } + + .alt-details-control+.alt-details-toggle+.alt-details-detail { + // by default, hide the details + position: absolute; + top: -999em; + left: -999em; + } + + .alt-details-control:checked+.alt-details-toggle+.alt-details-detail { + // show the details when the control is checked + position: static; + } + + .alt-details-control:checked+.alt-details-toggle:after { + // change the marker on the toggle label to a down arrow + content: "\f13a"; // + } + + .alt-details-detail { + // The detail box appears to be underneath the toggle button + // so we add a padding to the top and push it up. + border-bottom: $base-border-gray; + border-left: $base-border-gray; + border-right: $base-border-gray; + padding-top: 15px; + margin-top: 15px; + } +} diff --git a/_sass/components/code.scss b/_sass/components/code.scss index e771eb6ad1..15e8c641e3 100755 --- a/_sass/components/code.scss +++ b/_sass/components/code.scss @@ -23,3 +23,45 @@ } } + +.code-snippet-area { + width: 100%; + margin-top: 1em; + margin-bottom: 1em; + position: relative; // so we can position the buttons + + &:hover { + + // display the copy buttons on hover of the whole area + .code-snippet-buttons { + opacity: 0.95; + + &:active { + transition: none; + opacity: 0.7; + } + } + } + + .code-snippet-buttons { + opacity: 0; // default invisible until hover + transition: $base-transition; + position: absolute; // so we can position the buttons + right: 3px; + top: 5px; + + button { + border: none; + background: #fff; + font-size: $font-size-medium; + color: $gray-darker; + cursor: pointer; + } + } + + .code-snippet-display { + margin-top: 0px; + margin-bottom: 0px; + width: 100%; + } +} diff --git a/_sass/components/dropdown.scss b/_sass/components/dropdown.scss index 30f41cb713..b656233a34 100644 --- a/_sass/components/dropdown.scss +++ b/_sass/components/dropdown.scss @@ -2,6 +2,8 @@ //------------------------------------------------ //------------------------------------------------ +$border-1-grey: 1px solid rgba(128, 128, 128, 0.5); + .language-dropdown { position: relative; margin-top: 50px; @@ -17,6 +19,12 @@ // width: 100%; // } float: right; + padding-right: 6px; // leave space for the search bar + + .table-of-content & { + margin-top: 0; + margin-right: 0; + } .wrapper-dropdown { padding: 8px 18px 8px 40px; @@ -25,6 +33,17 @@ border-radius: $border-radius-base; box-sizing: border-box; + .table-of-content & { + border: $border-1-grey; + } + + .full-width & { + border: $border-1-grey; + } + + .table-of-content &:focus { + } + &:focus { outline: none; background: rgba(#fff, 0.9); diff --git a/_sass/components/heading-anchor.scss b/_sass/components/heading-anchor.scss new file mode 100644 index 0000000000..a38b6d96bf --- /dev/null +++ b/_sass/components/heading-anchor.scss @@ -0,0 +1,12 @@ +// HEADING ANCHOR +//------------------------------------------------ +//------------------------------------------------ + +.heading-anchor { + visibility: hidden; + padding-left: 0.5em; + + &:hover { + text-decoration: none; + } +} diff --git a/_sass/components/search.scss b/_sass/components/search.scss index de18915531..5a25704964 100755 --- a/_sass/components/search.scss +++ b/_sass/components/search.scss @@ -2,6 +2,19 @@ //------------------------------------------------ //------------------------------------------------ +// Override the styles below to style the search container +// when it is shown on a specific page (as opposed to the +// landing page) +.titles + .search-container { + @include span-columns(3); + @include bp(medium) { + display: none; + } + float: right; + margin-top: 50px; + margin-right: 0; +} + .search-container { position: relative; margin-top: 20px; diff --git a/_sass/components/tab.scss b/_sass/components/tab.scss index b5a9bb89c3..8207f3eb52 100755 --- a/_sass/components/tab.scss +++ b/_sass/components/tab.scss @@ -2,15 +2,21 @@ //------------------------------------------------ //------------------------------------------------ +// dynamic tab switching based on https: //levelup.gitconnected.com/tabbed-interfaces-without-javascript-661bab1eaec8 + .nav-tab { border-bottom: $base-border-gray; @include display(flex); @include align-items(center); @include justify-content(flex-start); - margin-bottom: 10px; + overflow-x: auto; // scrollbar when width is too small. + overflow-y: hidden; .item-tab { + + label, a { + transition: none; // do not animate the transition to active color: $base-font-color-light; display: block; padding: 0 20px 10px; @@ -23,21 +29,107 @@ color: $base-font-color; } - &.active { - border-bottom: 2px solid $brand-primary; - color: $brand-primary; - pointer-events: none; + &:hover { + cursor: pointer; } } + label { + -webkit-touch-callout: none; + -webkit-user-select: none; + -khtml-user-select: none; + -moz-user-select: none; + -ms-user-select: none; + user-select: none; + } + } + @include bp(small) { @include justify-content(space-between); + .item-tab { - a { - padding: 0 10px 10px; - font-size: $font-size-medium; + label, + a { + transition: none; // do not animate the transition to active + padding: 0 10px 10px; + font-size: $font-size-medium; + } } + } +} + +/* Active Tabs for standard screen size */ +.nav-tab>.item-tab>a.active, // used in the blog +.tabsection>input:nth-child(1):checked~.nav-tab .item-tab:nth-child(1) label, +.tabsection>input:nth-child(2):checked~.nav-tab .item-tab:nth-child(2) label, +.tabsection>input:nth-child(3):checked~.nav-tab .item-tab:nth-child(3) label, +.tabsection>input:nth-child(4):checked~.nav-tab .item-tab:nth-child(4) label, +.tabsection>input:nth-child(5):checked~.nav-tab .item-tab:nth-child(5) label, +.tabsection>input:nth-child(6):checked~.nav-tab .item-tab:nth-child(6) label, +.tabsection>input:nth-child(7):checked~.nav-tab .item-tab:nth-child(7) label, +.tabsection>input:nth-child(8):checked~.nav-tab .item-tab:nth-child(8) label, +.tabsection>input:nth-child(9):checked~.nav-tab .item-tab:nth-child(9) label { + border-bottom: 2px solid $brand-primary; + padding: 0 20px 8px; // so text does not jump up when active + color: $brand-primary; + pointer-events: none; +} + +/* Active Tabs for small screen size */ +@include bp(small) { + .nav-tab>.item-tab>a.active, + .tabsection>input:nth-child(1):checked~.nav-tab .item-tab:nth-child(1) label, + .tabsection>input:nth-child(2):checked~.nav-tab .item-tab:nth-child(2) label, + .tabsection>input:nth-child(3):checked~.nav-tab .item-tab:nth-child(3) label, + .tabsection>input:nth-child(4):checked~.nav-tab .item-tab:nth-child(4) label, + .tabsection>input:nth-child(5):checked~.nav-tab .item-tab:nth-child(5) label, + .tabsection>input:nth-child(6):checked~.nav-tab .item-tab:nth-child(6) label, + .tabsection>input:nth-child(7):checked~.nav-tab .item-tab:nth-child(7) label, + .tabsection>input:nth-child(8):checked~.nav-tab .item-tab:nth-child(8) label, + .tabsection>input:nth-child(9):checked~.nav-tab .item-tab:nth-child(9) label { + padding: 0 10px 8px; // match narrower padding for inactive tabs + } +} + +.tabsection { + padding: 0.1px 0; // ensure inner content is correctly padded + border-left: 2px solid $base-border-color-gray; + + .nav-tab { + padding-left: 0; + margin-bottom: 0; + + .item-tab { + padding: 0; + margin-bottom: 0; + list-style: none; } } + + input { // hide the input because they are not interactive + display: block; /* "enable" hidden elements in IE/edge */ + position: absolute; /* then hide them off-screen */ + left: -100%; + } + + .tabcontent { + section { // by default, hide all sections until the user clicks on the associated label + position: absolute; + top: -999em; + left: -999em; + } + } +} + +.tabsection>input:nth-child(1):checked~.tabcontent section:nth-child(1), +.tabsection>input:nth-child(2):checked~.tabcontent section:nth-child(2), +.tabsection>input:nth-child(3):checked~.tabcontent section:nth-child(3), +.tabsection>input:nth-child(4):checked~.tabcontent section:nth-child(4), +.tabsection>input:nth-child(5):checked~.tabcontent section:nth-child(5), +.tabsection>input:nth-child(6):checked~.tabcontent section:nth-child(6), +.tabsection>input:nth-child(7):checked~.tabcontent section:nth-child(7), +.tabsection>input:nth-child(8):checked~.tabcontent section:nth-child(8), +.tabsection>input:nth-child(9):checked~.tabcontent section:nth-child(9) { + position: static; } diff --git a/_sass/components/wip-notice.scss b/_sass/components/wip-notice.scss new file mode 100644 index 0000000000..3c84c75ac0 --- /dev/null +++ b/_sass/components/wip-notice.scss @@ -0,0 +1,12 @@ +.wip-notice { + position: relative; + top: 1em; + padding: 1em; + border-radius: 5px; + background: $gray-light; + + a { + color: $brand-primary; + font-weight: 700; + } +} diff --git a/_sass/layout/details-summary.scss b/_sass/layout/details-summary.scss new file mode 100644 index 0000000000..1f18d4cd64 --- /dev/null +++ b/_sass/layout/details-summary.scss @@ -0,0 +1,3 @@ +details > summary > p { + display: inline; +} diff --git a/_sass/layout/doc-navigation.scss b/_sass/layout/doc-navigation.scss index 1d11f17010..7539881c3f 100644 --- a/_sass/layout/doc-navigation.scss +++ b/_sass/layout/doc-navigation.scss @@ -4,6 +4,7 @@ $nav-height: 46px; + .doc-navigation { padding: 10px 20px; @include display(flex); @@ -18,6 +19,23 @@ $nav-height: 46px; display: none; } } + .doc-language-version { + font-size: 1.6em; + font-family: $heading-font-family; + font-weight: bold; + color: rgb(134,161,166); + @include bp(large) { + display: none; + } + } + a, + a:hover, + a:active, + a:focus, + a:hover, + a.active { + text-decoration: none; + } } .navigation-ellipsis { display: none; @@ -47,7 +65,7 @@ $nav-height: 46px; position: absolute; margin-top: 10px; display: none; - z-index: 1; + z-index: 40; box-shadow: 0 3px 12px rgba(0, 0, 0, 0.15); @include bp(medium) { diff --git a/_sass/layout/documentation.scss b/_sass/layout/documentation.scss index 9a04495b27..c4e56bd3d4 100644 --- a/_sass/layout/documentation.scss +++ b/_sass/layout/documentation.scss @@ -9,7 +9,7 @@ .content-title-documentation { .titles { - @include span-columns(9); + @include span-columns(6); @include bp(medium) { @include span-columns(12); } @@ -17,15 +17,17 @@ max-height: 160px; margin-top: 30px; margin-bottom: 100px; - @include bp(medium) { - margin-bottom: 0; - } + // this causes issues on mobile with the header being hidden behind + // the contents: + // @include bp(medium) { + // margin-bottom: 0; + //} .supertitle { text-transform: uppercase; font-weight: $font-black; font-size: 20px; - color: darken(#53b6d3, 15%); + color: rgba(0, 0, 0, 0.2); } h1 { @@ -42,6 +44,10 @@ .content-primary.documentation { line-height: 1.3; + p { + line-height: 1.5; + } + ol { margin-bottom: 18px; } @@ -56,4 +62,43 @@ font-weight: $font-bold; padding: 1px 5px; } + + .tag-inline { + float: none; + } + + h1, + h3, + h4, + h5, + h6 { + .heading-anchor { + color: $base-font-color; + } + + &:hover { + .heading-anchor { + visibility: visible; + } + } + } + + h2 { + .heading-anchor { + color: $brand-tertiary; + } + + &:hover { + .heading-anchor { + visibility: visible; + } + } + } +} + +a.new-version-notice { + display: block; + background: rgb(255, 255, 200); + font-size: large; + text-align: center; } diff --git a/_sass/layout/footer.scss b/_sass/layout/footer.scss index d21eb9e50e..e6f690fd4e 100755 --- a/_sass/layout/footer.scss +++ b/_sass/layout/footer.scss @@ -84,7 +84,7 @@ text-align: center; z-index: 2; color: #f0f3f3; - background-color: #dc322f; + background-color: $brand-primary; border-radius: 50%; display: none; diff --git a/_sass/layout/glossary.scss b/_sass/layout/glossary.scss index e55ef1c9aa..8346ea1b40 100644 --- a/_sass/layout/glossary.scss +++ b/_sass/layout/glossary.scss @@ -55,7 +55,7 @@ } li { - h4 { + h3 { text-transform: none; margin-bottom: 2px; font-weight: $font-black; diff --git a/_sass/layout/header.scss b/_sass/layout/header.scss index ab392dfd77..ff1b4fdb70 100755 --- a/_sass/layout/header.scss +++ b/_sass/layout/header.scss @@ -18,6 +18,23 @@ padding: 10px 40px; } + &.alert-warning { + background: $warning-bg; + color: $warning-text; + + a { + color: $warning-link; + font-weight: bold; + text-decoration: underline; + + &:active, + &:focus, + &:hover { + text-decoration: none; + } + } + } + span { position: absolute; right: 20px; diff --git a/_sass/layout/inner-main.scss b/_sass/layout/inner-main.scss index 5361b48902..64074851c8 100755 --- a/_sass/layout/inner-main.scss +++ b/_sass/layout/inner-main.scss @@ -2,17 +2,21 @@ //------------------------------------------------ //------------------------------------------------ +#inner-main>section:nth-child(2) { + // corresponds to area with the content below the title + position: relative; + top: -80px; // have it overlap with the title area +} + #inner-main { background: $gray-lighter; padding-bottom: $padding-xlarge; - - section:nth-child(2) { - position: relative; - top: -80px; - } - .inner-box { + margin-bottom: 30px; + &:last-child { + margin-bottom: 0; + } padding: $padding-medium; background: #fff; @include border-radius($border-radius-base); @@ -43,6 +47,10 @@ order: 1; margin-bottom: 30px; } + + @include bp(medium) { + order: 3; // move TOC to the bottom on mobile + } } .content-nav-blog { @@ -77,13 +85,6 @@ &:nth-child(2n) { clear: none; } - - &:active, - &:focus, - &:hover { - text-decoration: none; - background: none; - } } } } @@ -96,6 +97,15 @@ margin-top: 10px; line-height: 1.2; + &.type-chapter { + margin-top: 15px; + } + + &.type-section { + margin-top: 5px; + margin-left: 15px; + } + .active { font-weight: $font-black; color: $hover-link-color; diff --git a/_sass/layout/online-courses.scss b/_sass/layout/online-courses.scss new file mode 100644 index 0000000000..e9410fcf02 --- /dev/null +++ b/_sass/layout/online-courses.scss @@ -0,0 +1,45 @@ +.online-courses { + margin-bottom: 30px; +} + +.online-courses-wrapper { + @include clearfix; +} + +.online-courses-image { + @include span-columns(5); + @include bp(medium) { + @include span-columns(12); + } + + img { + margin-bottom: 0; + } +} + +.online-courses-content { + @include span-columns(7); + @include bp(medium) { + @include span-columns(12); + } + + h2 { + margin-top: 16px; + margin-bottom: 16px; + } + + blockquote, + p, + pre, + table, + ul { + margin-bottom: 8px; + } + + ol, + ul { + li { + margin-bottom: 4px; + } + } +} diff --git a/_sass/layout/overviews.scss b/_sass/layout/overviews.scss index 930502116b..39058ef40f 100644 --- a/_sass/layout/overviews.scss +++ b/_sass/layout/overviews.scss @@ -47,12 +47,10 @@ position: relative; flex: 0 1 calc(50% - 1em); margin-bottom: 2em; - transition: max-height .3s ease-out; text-decoration: none; border-radius: 2px; box-shadow: 0 1px 3px 0 rgba(0,0,0,.2), 0 1px 1px 0 rgba(0,0,0,.14), 0 2px 1px -1px rgba(0,0,0,.12); background: #fff; - max-height: 400px; overflow: hidden; @include bp(medium) { @@ -76,7 +74,7 @@ .card-content { padding: 20px; padding-top: 0px; - padding-bottom: 0px; + padding-bottom: 60px; } h2 { @@ -160,25 +158,23 @@ position: absolute; bottom: 0; width: 100%; - padding: 20px; - height: 66px; - background: #fff; - border-top: 1px solid lighten($base-font-color-light, 35%); - - &:hover { - cursor: pointer; - background: $brand-primary; - .expand-btn, - .go-btn { - color: #fff; - } - } - .expand-btn, .go-btn { - color: lighten($base-font-color-light, 15%); + display: block; + padding: 20px; + height: 66px; + background: #fff; + border-top: 1px solid lighten($base-font-color-light, 35%); + color: lighten($base-font-color-light, 10%); font-weight: $font-regular; font-size: $font-regular; + text-decoration: none; + + &:hover { + cursor: pointer; + background: $brand-primary; + color: #fff; + } } } } diff --git a/_sass/layout/sips.scss b/_sass/layout/sips.scss index 12e351ee5c..7fa2d5114e 100644 --- a/_sass/layout/sips.scss +++ b/_sass/layout/sips.scss @@ -103,40 +103,29 @@ .sips { - .pending, - .completed, - .rejected { - .date { - display: block; - font-size: $font-size-small; - text-transform: uppercase; - font-weight: $font-bold; - color: $base-font-color-light; - margin-top: 4px; - } + .sip-list { strong { font-weight: $font-black; + display: block; + } + + .no-fragmentation { + break-inside: avoid; } .tag { float: left; - position: relative; display: block; - top: 3px; color: #fff; text-transform: uppercase; font-size: 11px; font-weight: 700; padding: 1px 5px; + margin-left: 1px; + margin-top: 1px; } - } - .pending { - display: flex; - // flex-direction: column; - // flex-wrap: wrap; - // max-height: 400px; ul { list-style: inside disc; -webkit-column-count: 2; /* Chrome, Safari, Opera */ @@ -162,40 +151,4 @@ } } - .other-sips { - @include display(flex); - @include flex-direction(row); - @include flex-wrap(wrap); - @include justify-content(space-between); - - .completed, - .rejected { - display: flex; - flex-direction: column; - // justify-content: flex-end; - position: relative; - flex: 0 1 calc(50% - 1em); - - @include bp(medium) { - flex: 0 1 calc(100% - 0.5em); - } - - ul { - // padding-left: 0px; - - li { - // margin-left: 1em; - padding-bottom: 24px; - line-height: 1; - } - - a { - color: $gray-darker; - &:hover { - color: $brand-primary; - } - } - } - } - } } diff --git a/_sass/layout/table-of-content.scss b/_sass/layout/table-of-content.scss index 5dca9f7945..e846256f73 100755 --- a/_sass/layout/table-of-content.scss +++ b/_sass/layout/table-of-content.scss @@ -65,7 +65,9 @@ @include justify-content(flex-start); margin-bottom: 10px; - .fa { + .fa, + .fa-regular, + .fa-brands { font-size: 1.563rem; margin-right: 14px; color: $brand-primary; @@ -92,9 +94,9 @@ } } - &:active, - &:focus, - &:hover { + &.doc-item-link:active, + &.doc-item-link:focus, + &.doc-item-link:hover { text-decoration: none; background: $gray-lighter; } @@ -109,7 +111,7 @@ @include clearfix; padding-bottom: $padding-small; .discourse, - .gitter { + .discord { h3 { margin-top: 0; } @@ -168,7 +170,7 @@ } } - .gitter { + .discord { ul { li { @include span-columns(3 of 6); diff --git a/_sass/layout/talk-to-us.scss b/_sass/layout/talk-to-us.scss index ca83f9676e..94c6a147e3 100755 --- a/_sass/layout/talk-to-us.scss +++ b/_sass/layout/talk-to-us.scss @@ -25,7 +25,7 @@ } .discourse, - .gitter { + .discord { margin-bottom: 50px; @include clearfix; } @@ -76,7 +76,7 @@ } } - .gitter { + .discord { ul.first { @include shift(2); diff --git a/_sass/layout/title-page.scss b/_sass/layout/title-page.scss index 44a33f8621..208f0b9565 100755 --- a/_sass/layout/title-page.scss +++ b/_sass/layout/title-page.scss @@ -2,6 +2,10 @@ //------------------------------------------------ //------------------------------------------------ +.outdated-page .title-page { + background: $brand-tertiary-outdated; +} + .title-page { background: $brand-tertiary; // height: 200px; diff --git a/_sass/layout/toc.scss b/_sass/layout/toc.scss index a457ce903d..dfacedd379 100644 --- a/_sass/layout/toc.scss +++ b/_sass/layout/toc.scss @@ -3,8 +3,12 @@ //------------------------------------------------ .sidebar-toc-wrapper { - @include bp(medium) { - display: none; + position: -webkit-sticky; + position: sticky; + top: 0; + + @include bp(large) { + position: relative; } .contents { @@ -12,6 +16,16 @@ } } +.inner-toc { + max-height: 60vh; + overflow-y: auto; + position: relative; + + @include bp(large) { + max-height: none; + } +} + #toc { ul { list-style: none; @@ -52,6 +66,44 @@ margin-bottom: 0; margin-top: 0; line-height: 1.2; + + ul { + margin-top: 1px; + } + } + } + } + } +} + +.book #toc { + ul { + margin-top: 5px; + margin-bottom: 10px; + margin-left: 0px; + + a { + color: $base-link-color; + font-weight: normal; + } + + li { + margin-left: 10px; + margin-top: 5px; + + ul { + margin-left: 20px; + margin-top: -5px; + margin-bottom: 0px; + + a { + line-height: 1.3; + font-weight: normal; + } + + li { + margin-top: 0px; + margin-left: 10px; } } } diff --git a/_sass/layout/type-md.scss b/_sass/layout/type-md.scss index 38b09dbbd4..6548b1ff60 100755 --- a/_sass/layout/type-md.scss +++ b/_sass/layout/type-md.scss @@ -43,9 +43,8 @@ h4, h5 { - font-size: 1.063rem; + font-size: 1.0rem; font-family: $base-font-family; - text-transform: uppercase; font-weight: $font-bold; } } @@ -74,13 +73,12 @@ .text-step { h2 { margin-bottom: 24px; - + } + h3 { + margin-bottom: 0.5rem; } blockquote, - h3, - h4, - h5, img, p, pre, @@ -89,6 +87,15 @@ margin-bottom: 18px; } + p + .code-snippet-area { + // remove the margin-top for code snippet following a paragraph + margin-top: 0px; + } + + h4, h5 { + margin-bottom: 0.5rem; + } + ol, ul { padding-left: 18px; @@ -142,35 +149,52 @@ li, p, - tr, - td, + dt, + dd, + pre { + // common code for all code (inline and blocks) + code { + border: $base-border-gray; + } + } + + li, + p, dt, dd { code { font-family: 'Consolas'; - @include border-radius($border-radius-small); - font-size: $font-size-medium; - background: $gray-lighter; - color: #667b83; - // border: 1px solid #ced7d7; - padding: 0 6px; - margin: 0 4px; + background-color: #fff; + color: #859900; + @include border-radius($border-radius-medium); + padding: 2px 6px; } } - pre { - margin-bottom: 36px; + tr, + td{ + code { + font-family: 'Consolas'; + font-size: 0.9375rem; + } + } + + + pre { code { - padding: 20px; + overflow-x: auto; + display: block; font-size: $font-size-medium; @include border-radius($border-radius-base); + padding: 10px 7px; } } table { width: 100%; text-align: left; + border-collapse: collapse; thead { font-weight: $font-bold; @@ -178,8 +202,8 @@ td, th { - border-bottom: $base-border-gray; - padding: 6px 0; + border: $base-border-gray; + padding: 6px; } } @@ -195,6 +219,11 @@ font-style: italic; @include border-radius($border-radius-base); + &.help-info { + border: 2px dashed $brand-tertiary-dotty; + color: $brand-tertiary-dotty; + } + p { margin: 0; } diff --git a/_sass/utils/_variables.scss b/_sass/utils/_variables.scss index b40b379981..d018dbae37 100755 --- a/_sass/utils/_variables.scss +++ b/_sass/utils/_variables.scss @@ -7,6 +7,8 @@ $brand-primary: #DC322F; $brand-secondary: #859900; $brand-tertiary: #5CC6E4; +$brand-tertiary-outdated: #a9c0c6; +$brand-tertiary-dotty: #E45C77; //------------------------------------------------- $gray-darker: #002B36; $gray-dark: #073642; @@ -15,6 +17,11 @@ $gray-li: #244E58; $gray-light: #E5EAEA; $gray-lighter: #F0F3F3; $apple-blue: #6dccf5; + +$warning-bg: #FFA500; +$warning-link: #185eb3; +$warning-text: #000; + //------------------------------------------------- $headings-font-color: $gray-dark; $base-font-color: #4A5659; @@ -72,6 +79,8 @@ $padding-small: 20px; //------------------------------------------------ $border-radius-base: 3px; $border-radius-small: 2px; +$border-radius-medium: 10px; +$border-radius-large: 15px; // Breakpoints //------------------------------------------------ diff --git a/_sass/vendors/neat/settings/_grid.scss b/_sass/vendors/neat/settings/_grid.scss index fad1e9a445..d2c3639ff8 100755 --- a/_sass/vendors/neat/settings/_grid.scss +++ b/_sass/vendors/neat/settings/_grid.scss @@ -22,7 +22,7 @@ $grid-columns: 12 !default; /// /// @type Number (Unit) /// -$max-width: 1000px !default; +$max-width: 1280px!default; /// When set to true, it sets the box-sizing property of all elements to `border-box`. Set with a `!global` flag. /// diff --git a/_sips/all.md b/_sips/all.md index 50b6f94479..befff8ec61 100644 --- a/_sips/all.md +++ b/_sips/all.md @@ -2,55 +2,97 @@ layout: sips title: List of All SIPs -redirect_from: "/sips/sip-list.html" -redirect_from: "/sips/pending/index.html" +redirect_from: + - "/sips/sip-list.html" + - "/sips/pending/index.html" --- +{% assign sips = site.sips | sort: title %} +{% assign sipData = site.data.sip-data %} + +## Pre-SIP Discussions + +You can find so-called “pre-SIP discussions” in the Scala Contributors forum, under +the category [Scala Improvement Process](https://contributors.scala-lang.org/c/sip/13). +The goal of pre-SIP discussions is to gather initial community feedback and support. ## Pending SIPs -
            +Proposals that are at the design or implementation stage, and that are actively +discussed by the committee and the proposals’ authors. Click on a proposal to +read its content, or the corresponding discussions on GitHub if its design has +not been accepted yet. + +
              - {% assign sips = site.sips | sort: date | reverse %} {% for sip in sips %} - {% if sip.vote-status == "under-review" or sip.vote-status == "pending" or sip.vote-status == "dormant" or sip.vote-status == "under-revision" %} -
            • - {{ sip.title }} -
              {{ sip.date | date: '%B %Y' }}
              -
              {{ site.data.sip-data[sip.vote-status].text }}
              + {% if sip.stage == "design" or sip.stage == "implementation" %} +
            • + + + {{ sip.title }} + + +
              Stage: {{ sipData[sip.stage].text }}
              +
              Status: {{ sipData[sip.status].text }}
              + {% if sip.recommendation %} +
              Recommendation: {{ sipData[sip.recommendation].text }}
              + {% endif %}
              • {% endif %} {% endfor %}
            -
            -
            -

            Completed

            -
              - {% for sip in sips %} - {% if sip.vote-status == "complete" or sip.vote-status == "accepted" %} -
            • - {{ sip.title }} -
              {{ sip.date | date: '%B %Y' }}
              -
              {{ site.data.sip-data[sip.vote-status].text }}
              -
              • - {% endif %} - {% endfor %} -
            -
            -
            -

            Rejected

            -
              - {% for sip in sips %} - {% if sip.vote-status == "rejected" %} -
            • - {{ sip.title }} -
              {{ sip.date | date: '%B %Y' }}
              -
              {{ site.data.sip-data[sip.vote-status].text }}
              -
              • - {% endif %} - {% endfor %} -
            -
            +## Completed SIPs + +Proposals that have been implemented in the compiler and that are available as a stable +feature of the compiler (shipped), or that will be available in the next minor release +of the compiler (accepted). Click on a proposal to read its content. + +
            +
              + {% for sip in sips %} + {% if sip.stage == "completed" %} +
            • + {{ sip.title }} +
              {{ sipData[sip.status].text }}
              +
              • + {% endif %} + {% endfor %} +
            +
            + +## Rejected SIPs + +Proposals that have been rejected by the committee. Click on a proposal to read the +corresponding discussions on GitHub. + +
            +
              + {% for sip in sips %} + {% if sip.status == "rejected" %} +
            • + {{ sip.title }} +
              • + {% endif %} + {% endfor %} +
            +
            + +## Withdrawn SIPs + +Proposals that have been withdrawn by their authors. Click on a proposal to read the +corresponding discussions on GitHub. + +
            +
              + {% for sip in sips %} + {% if sip.status == "withdrawn" %} +
            • + {{ sip.title }} +
              • + {% endif %} + {% endfor %} +
            diff --git a/_sips/index.md b/_sips/index.md index bdb8fee062..87dc975d0c 100644 --- a/_sips/index.md +++ b/_sips/index.md @@ -3,24 +3,17 @@ layout: sips title: Scala Improvement Process --- - -Two separate processes govern changes to Scala: - -1. The **Scala Improvement Process** (SIP) covers changes to the Scala +The **Scala Improvement Process** covers changes to the Scala language, the Scala compiler, and the core of the Scala standard library. -2. The **Scala Platform Process** (SPP) aims to establish a stable -collection of libraries suitable for widespread use, with a low barrier -to entry for newcomers. +## Scala Improvement Process -## Scala Improvement Process (SIP) - -The **SIP** (_Scala Improvement Process_) is a process for submitting +The _Scala Improvement Process_ is a process for submitting changes to the Scala language. This process aims to evolve Scala openly and collaboratively. -The SIP process covers the Scala language and compiler and the core of +The process covers the Scala language and compiler and the core of the Scala standard library. (The core is anything that is unlikely to be spun off into a separate module.) @@ -28,24 +21,21 @@ A proposed change requires a design document, called a Scala Improvement Proposal (SIP). The SIP committee meets monthly to discuss, and eventually vote upon, proposals. -A SIP is subject to a [review process](./sip-submission.html). +A SIP is subject to a [review process]({% link _sips/process-specification.md %}). Proposals normally include proposed changes to the -[Scala language specification](http://www.scala-lang.org/files/archive/spec/2.12/). +[Scala language specification](https://www.scala-lang.org/files/archive/spec/2.13/). Before reaching the committee, a proposal normally receives community discussion and review on the [Scala Contributors](https://contributors.scala-lang.org/) forum. -Please read [Submitting a SIP](./sip-submission.html) and our -[SIP tutorial](./sip-tutorial.html) for more information. +Please read the [SIP tutorial]({% link _sips/sip-tutorial.md %}) or +[the process specification]({% link _sips/process-specification.md %}) for more +information. + +The aim of the Scala Improvement Process is to apply the openness and +collaboration that have shaped Scala's documentation and implementation to the +process of evolving the language. The linked documents capture our guidelines, +commitments and expectations regarding this process. > Historical note: The SIP replaces the older SID (Scala Improvement Document) process. > Completed SID documents remain available in the > [completed section of the SIP list](all.html). - -## Scala Platform Process (SPP) - -The Scala Platform aims to be a stable collection of libraries with widespread -use and a low barrier to entry for beginners and intermediate users. The -Platform consists of several independent modules that solve specific problems. -The Scala community sets the overall direction of the Platform. - -Learn more about the Scala Platform diff --git a/_sips/meeting-results.md b/_sips/meeting-results.md new file mode 100644 index 0000000000..4a44ee7c1b --- /dev/null +++ b/_sips/meeting-results.md @@ -0,0 +1,32 @@ +--- +layout: sips +title: SIP Meeting Results +redirect_from: /sips/minutes-list.html +--- + +This page lists the results of every SIP meeting, starting from July 2016. + +### Meetings ### + +
              + {% assign sips = site.sips | sort: 'date' | reverse %} + {% for page in sips %} + {% if page.partof == 'results' %} +
            • {{ page.date | date_to_long_string }}
              • + {% endif %} + {% endfor %} +
            + +### Meeting Minutes ### + +Before 2022, we hosted the complete meeting notes (minutes). Some +meetings were also [recorded on YouTube](https://www.youtube.com/channel/UCn_8OeZlf5S6sqCqntAvaIw/videos?view=2&sort=dd&shelf_id=1&live_view=502). + +
              + {% assign sips = site.sips | sort: 'date' | reverse %} + {% for pg in sips %} + {% if pg.partof == 'minutes' %} +
            • {{ pg.title }}
              • + {% endif %} + {% endfor %} +
            diff --git a/_sips/minutes-list.md b/_sips/minutes-list.md deleted file mode 100644 index ff651a8a46..0000000000 --- a/_sips/minutes-list.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: sips -title: SIP Meeting Minutes ---- - -This page hosts all the meeting notes (minutes) of the SIP meetings, starting -from July 2016. - -### Minutes ### -
              - {% assign sips = site.sips | sort: 'date' | reverse %} - {% for pg in sips %} - {% if pg.partof == 'minutes' %} -
            • {{ pg.title }}
              • - {% endif %} - {% endfor %} -
            diff --git a/_sips/minutes/2016-07-15-sip-minutes.md b/_sips/minutes/2016-07-15-sip-minutes.md index 40d2083b5f..1f29d94957 100644 --- a/_sips/minutes/2016-07-15-sip-minutes.md +++ b/_sips/minutes/2016-07-15-sip-minutes.md @@ -11,11 +11,11 @@ The following agenda was distributed to attendees: | Topic | Reviewer | | --- | --- | -| [Discussion of the new SIP process](http://docs.scala-lang.org/sips/sip-submission.html) | Jorge Vicente Cantero | -| [SIP 25 - Trait parameters](http://docs.scala-lang.org/sips/trait-parameters.html) | Adriaan Moors | +| [Discussion of the new SIP process](https://docs.scala-lang.org/sips/sip-submission.html) | Jorge Vicente Cantero | +| [SIP 25 - Trait parameters](https://docs.scala-lang.org/sips/trait-parameters.html) | Adriaan Moors | | [SIP 26 - Unsigned Integer Data Types](https://github.com/scala/slip/pull/30) | Martin Odersky | -| [SIP 22 - Async](http://docs.scala-lang.org/sips/async.html) | Eugene Burmako | -| [SIP 20 - Improved lazy val initialization](http://docs.scala-lang.org/sips/improved-lazy-val-initialization.html) | Sébastien Doeraene | +| [SIP 22 - Async](https://github.com/scala/improvement-proposals/pull/21) | Eugene Burmako | +| [SIP 20 - Improved lazy val initialization](https://github.com/scala/improvement-proposals/pull/19) | Sébastien Doeraene | | [Trailing commas SIP](https://github.com/scala/docs.scala-lang/pull/533) | Eugene Burmako | Quick iteration through all the SLIPs: diff --git a/_sips/minutes/2016-08-16-sip-10th-august-minutes.md b/_sips/minutes/2016-08-16-sip-10th-august-minutes.md index 9971d5810c..b0009109a0 100644 --- a/_sips/minutes/2016-08-16-sip-10th-august-minutes.md +++ b/_sips/minutes/2016-08-16-sip-10th-august-minutes.md @@ -11,11 +11,11 @@ The following agenda was distributed to attendees: | Topic | Reviewer | | --- | --- | -| [SIP-12: Uncluttering Scala's syntax for control structures](http://docs.scala-lang.org/sips/uncluttering-control.html) | Seth Tisue | -| [SIP-16: Self-cleaning macros](http://docs.scala-lang.org/sips/self-cleaning-macros.html) | Eugene Burmako | -| [SIP-21: Spores](http://docs.scala-lang.org/sips/spores.html) | Martin Odersky | -| [SIP-23: Literal-based singleton types](http://docs.scala-lang.org/sips/42.type.html) | Adriaan Moors | -| [SIP-24: Repeated by-name parameters](http://docs.scala-lang.org/sips/repeated-byname.html) | Andrew Marki | +| [SIP-12: Uncluttering Scala's syntax for control structures](https://github.com/scala/improvement-proposals/pull/12) | Seth Tisue | +| [SIP-16: Self-cleaning macros](https://github.com/scala/improvement-proposals/pull/15) | Eugene Burmako | +| [SIP-21: Spores](https://github.com/scala/improvement-proposals/pull/20) | Martin Odersky | +| [SIP-23: Literal-based singleton types](https://docs.scala-lang.org/sips/42.type.html) | Adriaan Moors | +| [SIP-24: Repeated by-name parameters](https://github.com/scala/improvement-proposals/pull/23) | Andrew Marki | | [SIP-27: Trailing commas](https://github.com/scala/docs.scala-lang/pull/533#issuecomment-232959066) | Eugene Burmako | Jorge Vicente Cantero was the Process Lead and acting secretary of the meeting. @@ -116,7 +116,7 @@ overdesigned for its purpose). As these are problems present in the very foundations of macros, he proposes to reject the SIP and commits to write up a new proposal based on [Scala -Meta](http://scalameta.org/), the successor of the old Scala macros, redesigned +Meta](https://scalameta.org/), the successor of the old Scala macros, redesigned from the ground up to overcome the current metaprogramming shortcomings. Josh agrees that macros are very useful but, as in their existing form, not @@ -164,7 +164,7 @@ proposal or study it further. **Conclusion**: The Committee asks Dale to explicitly summarize the potential conflicts with tuple syntax, review the initial [HList proposal in -Dotty](https://github.com/lampepfl/dotty/issues/964) to figure out potential +Dotty](https://github.com/scala/scala3/issues/964) to figure out potential conflicts with his proposal. Eugene also proposes Dale to consider whether the Committee can salvage non-controversial parts of this proposal and reduce this SIP just to them, as well as discussing the utility of having two ways of doing diff --git a/_sips/minutes/2016-09-20-sip-20th-september-minutes.md b/_sips/minutes/2016-09-20-sip-20th-september-minutes.md index fe5bd46fe5..2d65bd1856 100644 --- a/_sips/minutes/2016-09-20-sip-20th-september-minutes.md +++ b/_sips/minutes/2016-09-20-sip-20th-september-minutes.md @@ -12,7 +12,7 @@ The following agenda was distributed to attendees: | Topic | Reviewer | | --- | --- | | [SIP-NN: Scala Meta SIP](https://github.com/scala/docs.scala-lang/pull/567) | Iulian Dragos and Josh Suereth | -| [SIP-21: Spores](http://docs.scala-lang.org/sips/spores.html) | Martin Odersky | +| [SIP-21: Spores](https://github.com/scala/improvement-proposals/pull/20) | Martin Odersky | | [SIP-26: Unsigned Integer Data Types](https://github.com/scala/slip/pull/30) | Martin Odersky | | [SIP-27: Trailing commas](https://github.com/scala/docs.scala-lang/pull/533#issuecomment-232959066) | Eugene Burmako | @@ -154,12 +154,12 @@ issue, two things are required: The second option is not feasible because unsigned numbers are AnyVals, and they can only extend `Object`. Working around this in the backend is, in Sébastien's opinion, not an exciting adventure to embark on: a lot of patches and quirky -fixes are required in the compiler. Sébastien, recognizing his unability to fix +fixes are required in the compiler. Sébastien, recognizing his inability to fix the issue, recommends to reject the proposal. Josh needs to leave. Eugene wonders if these problems are only JVM-specific. Sébastien replies that both yes and no, and he confirms that unsigned integers -will be implemented in Scalajs alone, so the implementation won't be +will be implemented in Scala.js alone, so the implementation won't be platform-independent. Eugene is interested in knowing if there will be any code duplication in the implementation, and Sébastien doesn't think so, since Scala Native implements unsigned integer in a different way. diff --git a/_sips/minutes/2016-10-25-sip-minutes.md b/_sips/minutes/2016-10-25-sip-minutes.md index e4db397ee6..7c2d98abe2 100644 --- a/_sips/minutes/2016-10-25-sip-minutes.md +++ b/_sips/minutes/2016-10-25-sip-minutes.md @@ -12,7 +12,7 @@ The following agenda was distributed to attendees: | Topic | Reviewer | | --- | --- | | Discussion of the voting system | N/A | -| [SIP-20: Improved Lazy Val Initialization](http://docs.scala-lang.org/sips/improved-lazy-val-initialization.html) | Sébastien Doeraene | +| [SIP-20: Improved Lazy Val Initialization](https://github.com/scala/improvement-proposals/pull/19) | Sébastien Doeraene | | [SIP-27: Trailing commas](https://github.com/scala/docs.scala-lang/pull/533#issuecomment-232959066) | Eugene Burmako | Jorge Vicente Cantero was the Process Lead and acting secretary of the meeting. @@ -145,9 +145,9 @@ Dotty, in which the championed scheme is already implemented. There are no clear winner in the case of local lazy vals, but there seems to be two clear candidates for the non-local lazy vals -([V4](http://docs.scala-lang.org/sips/pending/improved-lazy-val-initialization.html) +([V4](https://github.com/scala/improvement-proposals/pull/19) and -[V6](http://docs.scala-lang.org/sips/pending/improved-lazy-val-initialization.html)). +[V6](https://github.com/scala/improvement-proposals/pull/19)). Both are faster than the existing implementation in the contended case but V4 general is 4x and V6 is only 2x. However, for the uncontended case V4 general is 30% slower than the existing implementation, while V6 is on par, up to +-5%. diff --git a/_sips/minutes/2016-11-29-sip-minutes.md b/_sips/minutes/2016-11-29-sip-minutes.md index 81b1e6e3e0..bc1d3c3452 100644 --- a/_sips/minutes/2016-11-29-sip-minutes.md +++ b/_sips/minutes/2016-11-29-sip-minutes.md @@ -11,10 +11,10 @@ The following agenda was distributed to attendees: |Topic|Reviewers| Accepted/Rejected | | --- | --- | --- | -| [SIP-28 and SIP-29 - Inline and meta](http://docs.scala-lang.org/sips/inline-meta.html) | Josh Suereth and Iulian Dragos | Pending | -| [SIP-24 - Repeated By Name Parameters](http://docs.scala-lang.org/sips/repeated-byname.html) | Heather Miller | Pending | -| [SIP-25:Static](https://github.com/scala/docs.scala-lang/pull/491/files)| Adriaan Moors | Pending | -|[SIP-27: Trailing commas](http://docs.scala-lang.org/sips/completed/trailing-commas.html)|Eugene Burkamo| Accepted | +| [SIP-28 and SIP-29 - Inline and meta](https://github.com/scala/improvement-proposals/pull/28) | Josh Suereth and Iulian Dragos | Pending | +| [SIP-24 - Repeated By Name Parameters](https://github.com/scala/improvement-proposals/pull/23) | Heather Miller | Pending | +| [SIP-30 - Static members](https://github.com/scala/docs.scala-lang/pull/491/files) | Adriaan Moors | Pending | +| [SIP-27 - Trailing commas](https://docs.scala-lang.org/sips/trailing-commas.html) |Eugene Burkamo | Accepted | Jorge Vicente Cantero was the Process Lead and Travis Lee was the secretary. @@ -42,7 +42,7 @@ Minutes were taken by Travis Lee. **Jorge** We'll talk about the SIPS for Scala Meta. Eugene will start. -### [SIP-28 and SIP-29 - Inline and meta](http://docs.scala-lang.org/sips/inline-meta.html) +### [SIP-28 and SIP-29 - Inline and meta](https://github.com/scala/improvement-proposals/pull/28) Eugene and co have been working hard for two months on inline and Scala Meta. Previously discussed new macro system with new inline and meta features. Inline provides a facility to declare methods with inline right hand side into call side (0:01:24) and meta implements compile-time function execution to do meta-programming. Martin implemented inline mechanism in Dotty. Eugene worked on macro notations. New style macros will integrate with tools. Eugene shows how it works in IntelliJ. For example, you can print the value of the parameters. Meta blocks supported by IntelliJ. So are quasi-quotes. You can also expand macros. Will greatly help debugability. @@ -52,7 +52,7 @@ The spec needs to be updated based on Martin's Dotty implementation. We need to **Conclusion** This proposal needs at least another iteration to shape up and provide concrete implementation and specification details. This proposal is therefore under revision -- Eugene, the author, will gather and address more feedback and will resubmit the proposal to analysis when it's ready. -### [SIP-24 - Repeated By Name Parameters](http://docs.scala-lang.org/sips/repeated-byname.html) +### [SIP-24 - Repeated By Name Parameters](https://github.com/scala/improvement-proposals/pull/23) Heather says the debate is about the semantics or translation rules. All arguments are evaluated each time the parameter is referenced in the method. This is implemented in Dotty. Should this be implemented in Scalac? @@ -66,7 +66,7 @@ The main motivation is to prepare for inline. Inline won't work very well withou ### [SIP-NN:Static](https://github.com/scala/docs.scala-lang/pull/491/files) -Iulian says too much code is generated by annotations. We could solve name clashes the way ScalaJS does by specifying the exported name. How can we wake code generation predictable without looking at annotations? How do we emit public static field without accessors? Having everything emitted as static and object where possible is going to simplify reasoning about how things are initialized. +Iulian says too much code is generated by annotations. We could solve name clashes the way Scala.js does by specifying the exported name. How can we wake code generation predictable without looking at annotations? How do we emit public static field without accessors? Having everything emitted as static and object where possible is going to simplify reasoning about how things are initialized. How should a user decide when to use static? It is platform-dependent. @@ -84,7 +84,7 @@ Sébastien says binary compatibility is also an argument in favor of having expl **Conclusion** There are a lot of edge cases when not using annotations. The authors need time to work on the specifics of the proposal and address the Committee's feedback. We need to think about cases around initialization to simplify it. Why do statics need to go first? Show surprising results. There are different implementation strategies. Is this more like @tailrec or does it change generated code? This is the first review iteration of this proposal. -### [SIP-27: Trailing commas](http://docs.scala-lang.org/sips/completed/trailing-commas.html) +### [SIP-27: Trailing commas](https://docs.scala-lang.org/sips/trailing-commas.html) Dale talks about how we wanted trailing commas for multi-line elements. Should be easy. Need to discuss which parts of the syntax can use trailing commas. There are two variants of the SIP to vote on. The first is _parameters and arguments_. The other variant is _everywhere_ for consistency. Dale implemented the first one. The second one shouldn't be more hard to implement except for tuples. It needs to fail compilation somehow. diff --git a/_sips/minutes/2017-02-14-sip-minutes.md b/_sips/minutes/2017-02-14-sip-minutes.md index b58ea431f5..1738cdc5ca 100644 --- a/_sips/minutes/2017-02-14-sip-minutes.md +++ b/_sips/minutes/2017-02-14-sip-minutes.md @@ -11,10 +11,10 @@ The following agenda was distributed to attendees: | Topic | Reviewer | | --- | --- | -| [SIP-XX: Improving binary compatibility with @stableABI](http://docs.scala-lang.org/sips/binary-compatibility.html) | Dmitry Petrashko | -| [SIP-NN - Allow referring to other arguments in default parameters](http://docs.scala-lang.org/sips/refer-other-arguments-in-args.html) | Pathikrit Bhowmick | -| [SIP 25 - @static fields and methods in Scala objects(SI-4581)](http://docs.scala-lang.org/sips/static-members.html) | Dmitry Petrashko, Sébastien Doeraene and Martin Odersky | -| [SIP-33 - Match infix & prefix types to meet expression rules](http://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) | Oron Port | +| [SIP-XX - Improving binary compatibility with @stableABI](https://github.com/scala/improvement-proposals/pull/30) | Dmitry Petrashko | +| [SIP-NN - Allow referring to other arguments in default parameters](https://github.com/scala/improvement-proposals/pull/29) | Pathikrit Bhowmick | +| [SIP-30 - @static fields and methods in Scala objects(SI-4581)](https://github.com/scala/improvement-proposals/pull/25) | Dmitry Petrashko, Sébastien Doeraene and Martin Odersky | +| [SIP-33 - Match infix & prefix types to meet expression rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) | Oron Port | Jorge Vicente Cantero was the Process Lead. Travis (@travissarles) was acting secretary of the meeting. @@ -46,7 +46,7 @@ Absent: ### Opening Remarks -### SIP 25 - @static fields and methods in Scala objects(SI-4581) +### SIP 30 - @static fields and methods in Scala objects (SI-4581) Jorge asks Dmitry to explain the biggest changes since the last proposal. The biggest changes were addressing the feedback of the reader. **Dmitry** First, he covers whether the static annotation can behave like the tail recursive annotation, which doesn't actually impact compilation but only warns if it isn't possible to make something static. Dmitry doesn't think the static annotation should have the same semantics because it affects binary compatibility. @@ -147,7 +147,7 @@ The current SIP tries to make it behave as expected by the users in common cases **Jorge** We have to pass here both on this proposal as is right now but I think this could be dangerous in the case where we don't have an implementation for Scalac because maybe the details change and assume something in Scalac that the SIP is not able to predict or guard against it. Let's wait until next month and I will double check whether this is possible or not. Then I will get in touch with the Lightbend team to see whether this can be implemented or not. We'll decide in a month whether it should be accepted. -**Sébastien** ScalaJS already implemented it under another name but it's supposed to be conservative with respect to the aesthetic SIP in the sense that things that are allowed now with @jsstatic will also be allowed with @static. @static might open up a little bit more. +**Sébastien** Scala.js already implemented it under another name but it's supposed to be conservative with respect to the aesthetic SIP in the sense that things that are allowed now with @jsstatic will also be allowed with @static. @static might open up a little bit more. **Conclusion** The static SIP proposal has to be implemented in Scala, as it's already present in Dotty. Triplequote (Iulian Dragos and Mirco Dotta) has offered to provide an implementation targeting 2.12.3. @@ -221,7 +221,7 @@ There are multiple use cases covered by this SIP. I think the two most important **Martin** If you don't emit a Scala signature then you can't have a co- or contravariant type parameter because they are only expressed in Scala signatures, in Java it's not there. I don't see how that follows from the current proposal. Also, isn't it platform dependent? -**Sébastien** We do have a Java signature. Scala-JS doesn't disable classfile emission. When you say quickly compile, it uses the classfiles to quickly compile. when you use macros, it will extend from those classfiles. When you use an IDE it reduces the classfiles to identify things. When you use sbt, it uses classfiles to detect the changes. However, they aren't used by the ScalaJS linker. +**Sébastien** We do have a Java signature. Scala.js doesn't disable classfile emission. When you say quickly compile, it uses the classfiles to quickly compile. when you use macros, it will extend from those classfiles. When you use an IDE it reduces the classfiles to identify things. When you use sbt, it uses classfiles to detect the changes. However, they aren't used by the Scala.js linker. **Seth** Does this need to be part of the compiler or can it move forward as a plugin or just as a check performed in MiMa? MiMa just compares two different APIs. Can it have this other job as well: seeing if it does anything outside of the boundaries. diff --git a/_sips/minutes/2017-05-08-sip-minutes.md b/_sips/minutes/2017-05-08-sip-minutes.md index e5d2e52ccf..f2da50701b 100644 --- a/_sips/minutes/2017-05-08-sip-minutes.md +++ b/_sips/minutes/2017-05-08-sip-minutes.md @@ -11,8 +11,8 @@ The following agenda was distributed to attendees: |Topic|Reviewers| Accepted/Rejected | | --- | --- | --- | -| [SIP-NN - comonadic-comprehensions](http://docs.scala-lang.org/sips/comonadic-comprehensions.html) | Shimi Bandiel | Rejected | -| [SIP-33 - Match infix & prefix types to meet expression rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html)| Oron Port | Pending | +| [SIP-NN - comonadic-comprehensions](https://github.com/scala/improvement-proposals/pull/32) | Shimi Bandiel | Rejected | +| [SIP-33 - Match infix & prefix types to meet expression rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html)| Oron Port | Pending | |[Scala Library Changes](https://github.com/scala/scala-dev/issues/323)|Adriaan Moors| Scala-dev proposal | Jorge Vicente Cantero was the Process Lead. @@ -41,22 +41,22 @@ Minutes were taken by Darja Jovanovic. **Jorge** going over the agenda, points out that the second item will be skipped because they are waiting for the prototype from the author of the proposal. -### [SIP-NN - comonadic-comprehensions](http://docs.scala-lang.org/sips/comonadic-comprehensions.html) +### [SIP-NN - comonadic-comprehensions](https://github.com/scala/improvement-proposals/pull/32) [YouTube time: 1:39](https://youtu.be/6rKa4OV7GfM?t=99) Proposal aims to introduce new syntax from comprehension for monads to comonads. Martin is the reviewer. He asks others attendees for their opinion on this. Everyone had read the SIP. -**Eugene** referred to original proposal and wishes to see a better motivation for this language feature encouraging use of “plain English” to simplify the use of Scala as practice oriented language. He believes that it could be critical how this SIP can be improved. During the recent conference, organized by Facebook, he spoke with typescript guys that are developing idiomic solutions that would benefit typescript and javascript and allow community users to give their inputs. +**Eugene** referred to original proposal and wishes to see a better motivation for this language feature encouraging use of “plain English” to simplify the use of Scala as practice oriented language. He believes that it could be critical how this SIP can be improved. During the recent conference, organized by Facebook, he spoke with TypeScript guys that are developing idiomatic solutions that would benefit TypeScript and JavaScript and allow community users to give their inputs. Refers to the paper “Denotation” he linked in a proposal, that is not enough for Scala, but a good start. **Jorge** is getting back discussion on voting on this proposal and he mentioned that Josh insisted on more examples and suggestions on motivation of this SIP. -**Eugene** wanted to add more syntax (map and flatmap), but **Martin** opposed to that saying that Scala is quite serious program and needs more reason to add any additional syntax to it. **Martin** would like to see more widespread use of comonadic constructs and Libraries, and before doing that, he wouldn’t consider any further change. **Sebastian** agrees with Martin and says that he doesn’t really understand Josh’s and Eugene’s proposal. **Iulian** agrees that the proposal is quite complicated and he wonders how it can be useful. He believes that it is an interesting research direction, but that it needs more users feedbacks in aim to be included in the Scala, therefore questioning if the proposal should be numbered in the current form. Seth and Adriaan agree with Martin and Iulian. +**Eugene** wanted to add more syntax (map and flatMap), but **Martin** opposed to that saying that Scala is quite serious program and needs more reason to add any additional syntax to it. **Martin** would like to see more widespread use of comonadic constructs and Libraries, and before doing that, he wouldn’t consider any further change. **Sebastian** agrees with Martin and says that he doesn’t really understand Josh’s and Eugene’s proposal. **Iulian** agrees that the proposal is quite complicated and he wonders how it can be useful. He believes that it is an interesting research direction, but that it needs more users feedback in aim to be included in the Scala, therefore questioning if the proposal should be numbered in the current form. Seth and Adriaan agree with Martin and Iulian. **Conclusion** Proposal discarded unanimously. They will send the feedback to the author. -### [SIP-33 - Match infix & prefix types to meet expression rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html) +### [SIP-33 - Match infix & prefix types to meet expression rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) Skipped since they are waiting for the prototype from the author of the proposal. diff --git a/_sips/minutes/2017-09-21-sip-minutes.md b/_sips/minutes/2017-09-21-sip-minutes.md index 62e862a24a..8d32e2421f 100644 --- a/_sips/minutes/2017-09-21-sip-minutes.md +++ b/_sips/minutes/2017-09-21-sip-minutes.md @@ -11,10 +11,10 @@ The following agenda was distributed to attendees: |Topic|Reviewers| Accepted/Rejected | | --- | --- | --- | -| [SIP-NN: Right-Associative By-Name Operators](http://docs.scala-lang.org/sips/right-associative-by-name-operators.html) | Adriaan Moors | Pending | -| [SIP-ZZ: Opaque types](http://docs.scala-lang.org/sips/opaque-types.html) | Sébastien Doeraene | Pending | -| [SIP-33: Match infix and prefix types to meet expression rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html)| Josh Suereth | Pending | -|[SIP-28 and SIP-29: Inline meta](http://docs.scala-lang.org/sips/inline-meta.html)|Josh Suereth and Iulian Dragos| Pending | +| [SIP-NN: Right-Associative By-Name Operators](https://docs.scala-lang.org/sips/right-associative-by-name-operators.html) | Adriaan Moors | Pending | +| [SIP-ZZ: Opaque types](https://docs.scala-lang.org/sips/opaque-types.html) | Sébastien Doeraene | Pending | +| [SIP-33: Match infix and prefix types to meet expression rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html)| Josh Suereth | Pending | +|[SIP-28 and SIP-29: Inline meta](https://github.com/scala/improvement-proposals/pull/28)|Josh Suereth and Iulian Dragos| Pending | Jorge Vicente Cantero was the Process Lead and Darja Jovanovic as secretary. @@ -47,7 +47,7 @@ Minutes were taken by Darja Jovanovic. **Darja** introduces herself as a Scala Center's Communication Manager to the Committee and the Community. [YouTube time: 00 - 2'50''](https://youtu.be/yzTpVbTUj18) -### [SIP-NN: Right-Associative By-Name Operators](http://docs.scala-lang.org/sips/right-associative-by-name-operators.html) (Numbered: SIP-34) +### [SIP-NN: Right-Associative By-Name Operators](https://docs.scala-lang.org/sips/right-associative-by-name-operators.html) (Numbered: SIP-34) [YouTube time: 2'50''- 8'26''](https://youtu.be/yzTpVbTUj18?t=169) **Jorge** opens the meeting and gives the word to **Adriaan**, the the reviewer. @@ -61,7 +61,7 @@ After a short discussion about the protocol, mainly about skipping the numbering **Conclusion**: The SIP is numbered as "SIP-34", by unanimity and it will be at disposal for a month for the community comments. -### [SIP-ZZ: Opaque types](http://docs.scala-lang.org/sips/opaque-types.html) (Numbered: SIP-35) +### [SIP-ZZ: Opaque types](https://docs.scala-lang.org/sips/opaque-types.html) (Numbered: SIP-35) [YouTube time: 8'27''-51'13''](https://youtu.be/yzTpVbTUj18?t=507) **Sébastien**, as a reviewer, is asked to present the SIP to the Committee and Public. @@ -83,11 +83,11 @@ Syntax "new" "type" **Conclusion**: The SIP is numbered as "SIP 35" by unanimous vote. The above mentioned should to be addressed for the next meeting. -### [SIP-33: Match infix and prefix types to meet expression rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html) +### [SIP-33: Match infix and prefix types to meet expression rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) Still waiting on the implementation updates, therefore this item will be discussed in the next SIP Meeting. -### [SIP-28 and SIP-29: Inline and meta](http://docs.scala-lang.org/sips/inline-meta.html) +### [SIP-28 and SIP-29: Inline and meta](https://github.com/scala/improvement-proposals/pull/28) [YouTube time: 51'40'' until the end](https://youtu.be/yzTpVbTUj18?t=3100) **Eugene** gives a brief history of this SIP development, shares the good news and suggests how to proceed. diff --git a/_sips/minutes/2017-10-24-sip-minutes.md b/_sips/minutes/2017-10-24-sip-minutes.md index f821138c57..4d65067a48 100644 --- a/_sips/minutes/2017-10-24-sip-minutes.md +++ b/_sips/minutes/2017-10-24-sip-minutes.md @@ -11,10 +11,10 @@ The following agenda was distributed to attendees: |Topic|Reviewers| Accepted/Rejected | | --- | --- | --- | -| [SIP-34: Right-Associative By-Name Operators](http://docs.scala-lang.org/sips/right-associative-by-name-operators.html) | Adriaan Moors | Accepted | -| [SIP-35: Opaque types](http://docs.scala-lang.org/sips/opaque-types.html) | Sébastien Doeraene | Pending | -| [SIP-33: Match infix and prefix types to meet expression rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html)| Josh Suereth | Pending | -|[SIP-28 and SIP-29: Inline meta](http://docs.scala-lang.org/sips/inline-meta.html)|Josh Suereth and Iulian Dragos| Pending | +| [SIP-34: Right-Associative By-Name Operators](https://docs.scala-lang.org/sips/right-associative-by-name-operators.html) | Adriaan Moors | Accepted | +| [SIP-35: Opaque types](https://docs.scala-lang.org/sips/opaque-types.html) | Sébastien Doeraene | Pending | +| [SIP-33: Match infix and prefix types to meet expression rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html)| Josh Suereth | Pending | +|[SIP-28 and SIP-29: Inline meta](https://github.com/scala/improvement-proposals/pull/28)|Josh Suereth and Iulian Dragos| Pending | Jorge Vicente Cantero was the Process Lead and Darja Jovanovic as secretary. @@ -46,7 +46,7 @@ Minutes were taken by Darja Jovanovic. **Jorge** opens the meeting and introduces Olaf as a guest presenter for the SIP 28 and 29. Goes on to the first item on the agenda. -### [SIP-34: Right-Associative By-Name Operators](http://docs.scala-lang.org/sips/right-associative-by-name-operators.html) +### [SIP-34: Right-Associative By-Name Operators](https://docs.scala-lang.org/sips/right-associative-by-name-operators.html) [YouTube time: 00.31''- 2'03''](https://youtu.be/aIc-o1pcRhw?t=32) **Jorge** states that this SIP is uncontroversial and that Committee should vote, if there are no further comments. **Sébastien** adds that community didn't have any comments either. @@ -54,7 +54,7 @@ The Committee votes. **Conclusion**: The SIP is accepted by unanimity. -### [SIP-35: Opaque types](http://docs.scala-lang.org/sips/opaque-types.html) +### [SIP-35: Opaque types](https://docs.scala-lang.org/sips/opaque-types.html) [YouTube time: 02'03''- 03'10''](https://youtu.be/aIc-o1pcRhw?t=122) **Jorge** gives a brief update about the stage of the SIP-35, says that both community and the committee members gave a lot of feedback. @@ -62,7 +62,7 @@ They are working on updates, but don't have any to share for this meeting. **Conclusion**: The SIP-35 will be proposed on the agenda once the updates are provided. -### [SIP-33: Match infix and prefix types to meet expression rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html) +### [SIP-33: Match infix and prefix types to meet expression rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) [YouTube time: 03'12''- 10'04''](https://youtu.be/aIc-o1pcRhw?t=194) **Jorge** introduces the SIP adding that **Oron** provided the implementation for associativity of the infix type, not for the prefix type. **Martin** makes the remark that Dotty does the same thing. He continues by saying he is "skeptical" about *prefix* types, as it seems to be another feature and "a necessary compromise to the mathematical conventions". On the other hand, he believes that once the rules for associativity are fixed then types and terms will be consistent. @@ -75,7 +75,7 @@ The feedback will be given to the author. -### [SIP-28 and SIP-29: Inline and meta](http://docs.scala-lang.org/sips/inline-meta.html) +### [SIP-28 and SIP-29: Inline and meta](https://github.com/scala/improvement-proposals/pull/28) [YouTube time: 10'05'' until the end](https://youtu.be/aIc-o1pcRhw?t=605) **Jorge** introduces **Olaf** as a new Team Lead of SIP-28 and SIP-29. diff --git a/_sips/minutes/2017-12-06-sip-minutes.md b/_sips/minutes/2017-12-06-sip-minutes.md index 14fead9104..29f2aaafbd 100644 --- a/_sips/minutes/2017-12-06-sip-minutes.md +++ b/_sips/minutes/2017-12-06-sip-minutes.md @@ -12,10 +12,10 @@ The following agenda was distributed to attendees: |Topic|Reviewers| Accepted/Rejected | | --- | --- | --- | |Discussion and voting on Miles Sabin (Typelevel representative) joining the Committee | | Accepted -|[SIP 23: Literal-based singleton types](http://docs.scala-lang.org/sips/42.type.html) | Adriaan Moors | Accepted -|[SIP-33: Priority-based infix type precedence rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html) | Josh Suereth | Accepted | -|[SIP-NN: Adding prefix types](http://docs.scala-lang.org/sips/adding-prefix-types.html) | Josh Suereth | Pending | -|[SIP-35: Opaque types](http://docs.scala-lang.org/sips/opaque-types.html) | Sébastien Doeraene | Not discussed | +|[SIP 23: Literal-based singleton types](https://docs.scala-lang.org/sips/42.type.html) | Adriaan Moors | Accepted +|[SIP-33: Priority-based infix type precedence rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) | Josh Suereth | Accepted | +|[SIP-NN: Adding prefix types](https://github.com/scala/improvement-proposals/pull/35) | Josh Suereth | Pending | +|[SIP-35: Opaque types](https://docs.scala-lang.org/sips/opaque-types.html) | Sébastien Doeraene | Not discussed | |Discussion about the future of Scala 2.13 and 2.14 | | Not discussed | @@ -45,7 +45,7 @@ Minutes were taken by Darja Jovanovic. **Jorge** opens up the meeting by announcing **Miles Sabin** as a new Committee member, **Miles** joins the Committee meeting. -### [SIP 23: Literal-based singleton types](http://docs.scala-lang.org/sips/42.type.html) +### [SIP 23: Literal-based singleton types](https://docs.scala-lang.org/sips/42.type.html) [YouTube time 6'44''](https://youtu.be/Mhwf15gjL9s?t=402) **Miles** introduces the SIP, giving a progress overview after taking charge of the SIP and about its implementation in Typelevel Scala. @@ -66,14 +66,14 @@ The Committee members agree the SIP is ready to be voted for, given the track re *See also*: Brief explanation about the "The presence of an upper bound of Singleton on a formal type parameter 3rd point in the SIP [YouTube time 14' to 15'35''](https://www.youtube.com/watch?v=Mhwf15gjL9s) and [YouTube Time 17'42'' to 18'20'']( https://youtu.be/Mhwf15gjL9s?t=1069) -### [SIP-33: Priority-based infix type precedence rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html) +### [SIP-33: Priority-based infix type precedence rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) [YouTube time from 1'34'' - 6'45''](https://youtu.be/Mhwf15gjL9s?t=96) **Jorge** shortly introduces the SIP and notifies the Committee that the author has amended all the changes as per Committee suggestions. The SIP-33 was split in two SIPs as follows: -a) [SIP-33: Priority-based infix type precedence rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html) +a) [SIP-33: Priority-based infix type precedence rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) -b) [SIP-NN: Adding prefix types](http://docs.scala-lang.org/sips/adding-prefix-types.html) +b) [SIP-NN: Adding prefix types](https://github.com/scala/improvement-proposals/pull/35) **Seth** asks about the implementation status in Dotty and if there are any crucial differences in Scala 2 and Dotty? **Martin** and **Sebastien** agree there are none in regards to this SIP. @@ -82,7 +82,7 @@ The members are all in favour for this change and proceed to voting. **Conclusion** : The SIP-33 is accepted by unanimity. -### [SIP-NN: Adding prefix types](http://docs.scala-lang.org/sips/adding-prefix-types.html) +### [SIP-NN: Adding prefix types](https://github.com/scala/improvement-proposals/pull/35) [YouTube time: 25'00 until the end](https://youtu.be/Mhwf15gjL9s?t=1503) **Jorge** introduces the SIP's development, based on the idea @@ -104,7 +104,7 @@ The Committee proceeds with voting on numbering the SIP. Other announced agenda items were not discussed in this meeting because of the lack of time. They will be addressed in the next meeting. -- [SIP-35: Opaque types](http://docs.scala-lang.org/sips/opaque-types.html) +- [SIP-35: Opaque types](https://docs.scala-lang.org/sips/opaque-types.html) - Discussion about the future of Scala 2.13 and 2.14. In concrete, the following ideas that Adriaan has presented publicly in his talk, [the link](https://adriaanm.github.io/reveal.js/scala-2.13-beyond.html#/) Some examples of his ideas: diff --git a/_sips/minutes/2018-03-08-sip-minutes.md b/_sips/minutes/2018-03-08-sip-minutes.md new file mode 100644 index 0000000000..33f16d241e --- /dev/null +++ b/_sips/minutes/2018-03-08-sip-minutes.md @@ -0,0 +1,328 @@ +--- +layout: sips +title: SIP Meeting Minutes - 8th March 2018 + +partof: minutes +--- + +# Minutes + +The following agenda was distributed to attendees: + +|Topic|Reviewers| Accepted/Rejected | +| --- | --- | --- | +|[SIP-35: Opaque types: updates on the proposal](http://docs.scala-lang.org/sips/opaque-types.html) | Sébastien Doeraene | N/A +|[SIP-NN: Byname implicit arguments](http://docs.scala-lang.org/sips/byname-implicits.html) | Martin Odersky | N/A +|Discussions about the future of Scala 2.13 and 2.14 | | | + + +Jorge Vicente Cantero was the Process Lead and Darja Jovanovic as secretary. + +## Date and Location +The meeting took place on the 8th March 2018 at 5 PM CEST via Google Hangouts at EPFL in Lausanne, Switzerland. + +[Watch on Scala Center YouTube channel](https://youtu.be/dFEkS71rbW8) + +Minutes were taken by Jamie Thompson. + +## Attendees +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Jorge Vicente Cantero ([@jvican](https://github.com/jvican)), Scala Center +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), EPFL +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Scala Center + +## Joined Online +* Eugene Burmako ([@xeno-by](https://github.com/xeno-by)), Twitter +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Miles Sabin ([@milessabin](https://github.com/milessabin)], Independent +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend + +## Guest +* Erik Osheim, SIP-35 author. + +## Not present +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU + +## Proceedings + +### Opening Remarks + +[YouTube time 0'00'' - 1'20''](https://youtu.be/dFEkS71rbW8): **Jorge** introduces the meeting by outlining the three +items on the agenda, the first two being SIP proposals and the third being an overview of potential features for Scala +2.13 which may lead to more concrete proposals. +Beginning with point three, **Jorge** explains that three ideas are scheduled for discussion at the meeting, +and invites **Adriaan** to open with the first of them. + +### Discussion about the future of Scala 2.13 and 2.14 +[YouTube time 1'23'' - 23'31''](https://youtu.be/dFEkS71rbW8?t=83) + +#### [Proposal to Drop Package Objects with Inheritance](https://github.com/scala/scala-dev/issues/441) + +This was an open discussion. + +**Adriaan** introduces the idea that package objects should no longer support +inheritance, and possibly be replaced altogether with top level definitions. + +#### Questions about Package Objects + +1) **Miles** asks for clarification on what is problematic with the current implementation of package objects and if it + is worth the cost of creating a new feature to replace them. + + **Adriaan** responds: + - Inheritance from a parent in the same package creates problems. + - package objects already carry a lot of constraints compared to ordinary objects. + - They are worth changing to simplify the implementation. + - Simple migration for package object with extends clauses: change to a regular object and import its definitions. + +2) **Miles** asks if replacing package objects with top level definitions puts an end to the + long standing goal of replacing packages by objects. + + **Adriaan** agrees that is what he is suggesting, motivated by the many issues that + have been discovered with the current implementation in the context of incremental compilation, IDE's and more. + + **Iulian** adds to **Adriaan's** comment: he believes the implementation is too complicated and not correct, with + many workarounds leading to brittle compilation, such as cyclic references between a package object and its parents + if one is the same package. + + **Martin** in response to **Iulian** suggests that the issues experienced with package objects are only due to the + implementation, suggesting that in Dotty, he does not recall many special cases. He suggests that package objects + should behave like ordinary objects and reject parents in the same package. + +3) **Iulian** asks what is the extra benefit of a package object over wrappers for top level definitions. + + **Miles** highlights that they are first class values. + + **Erik** shares examples of uses at his workplace for package objects: access to members without + imports, such as implicit definitions, similar to a Prelude. + + **Sébastien** suggests that a package object may contain another package, which is not possible in an ordinary object + +#### In Favour of Top Level Definitions + +1) **Adriaan**: in his experience package objects are usually + aggregates for new definitions, without extends clauses, which **Miles** agrees is his typical usage of them. + +2) **Sébastien** believes that the extends clause in typical code is used only to inherit from a class in the same + package, so concludes that given the known issues with inheritence, it should be dropped in favour of top level + definitions. + + ([YouTube time from 2'35'' - 3'50''](https://youtu.be/dFEkS71rbW8?t=155)) He proposes two solutions for their + implementation: + + 1) The Kotlin way, which is to create a single wrapper object for each file, with a name derived from the file. + - **Drawback**: a name change to the file breaks binary compatibility. + 2) Individual wrapper classes for each definition, with a name derived from the definition and any parameters. + - **Benefit**: no binary compatibility issue as names are fully qualified. + - **Drawback**: many more class files generated. + + **Sébastien** believes that these solutions do not introduce new issues for type checking. + +3) **Martin** believes that top level definitions are simpler to understand than package objects and is in favour. + +#### Implementation of Top Level Definitions + +- **Erik** is concerned with the impact of top level definitions in multiple files on incremental compilation. +- **Martin** is concerned about how to reason about overloaded and conflicting top level definitions in different files. + +**Sébastien** believes that both concerns above are not issues, proceding to outline how it is similar to regular member +scoping. After some discussion, **Martin** believes that an implementation is possible in Dotty. + +#### Skepticism Around Top Level Definitions + +1) **Seth** would like to keep package objects, but improve safety by adding some restrictions + + He suggests that investigating code and communicating with users will likely have the least disruptive change, + favouring the most popular use-cases. + +2) **Eugene** asks if the behaviour of package objects could be documented, as + currently there is no formal specification except for the implementation. + He is concerned that changes could being made without considering the wider industry, as they will have large code + bases that will need to migrate package objects if they break. + + **Sébastien** answers by suggesting that package objects with no parents can be automatically rewritten to top level + definitions, however, further thought would be required to deal with package objects that have extends clauses. + +>#### YouTube Comment +>[YouTube time from 17'06'' to 18'02''](https://youtu.be/dFEkS71rbW8?t=1026) +> +>**Sébastien** addresses a comment on the stream about which kinds of definitions are safe to be allowed at the top +>level and there is some discussion. +> +>Overall, it is believed that defs can be at the top level, but vals are order +>dependent so might not be allowed. + +**Jorge** notes that there is no longer enough time to discuss the other two ideas for 2.13. + +**Adriaan** finishes by inviting participation in the discussion of the remaining issues in the +[Scala 2.14 milestone on GitHub](https://github.com/scala/scala-dev/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.14). + +#### Conclusion +The committee members are overall in agreement that package objects are a pain point, and there are mixed opinions as to +whether they become further restricted for safety, or replaced with top level definitions which raised concerns for +migration. + +### [SIP-35: Opaque types: updates on the proposal](http://docs.scala-lang.org/sips/opaque-types.html) +[YouTube time from 23'31'' - 43'02''](https://youtu.be/dFEkS71rbW8?t=1411) + +**Jorge** introduces the proposal, noting that it had been updated in the morning before the meeting and directs +**Sébastien**, the reviewer, to begin the discussion on the high level parts of the proposal. + +#### Concerns About The Motivation + +1) **Sébastien** believes that the current wording of the proposal could lead to wrong expectations, + mostly in the meaning of "boxing" (i.e. primitive boxing vs an instance of a user defined wrapper class). + + **Erik** agrees that further clarification is needed, giving specific examples on when a value is left unboxed, + concluding that the value of an opaque type will have semantics of the underlying type. + +2) **Sébastien** points out that some examples claim to not box, but do in fact, for example in the tagging + demonstration, the tag method is generic and will box the Double value passed in the code. + + **Erik** clarifies that a specialised annotation was intended to be on that method, which would avoid the boxing + but was cut for readability. + + **Sébastien** concludes by stating that examples must agree with any claims made about them. + +3) **Sébastien** suggests that most of the examples in the motivation are not not have advantageous runtime performance + over the existing value class feature. + +4) **Miles** suggests that the performance benefits of avoiding boxing is a secondary concern to the semantics that + opaque type aliases bring to the language and asks which is the primary motivation. + + **Erik** answers that both are really key motivations. Originally, the idea was to create a replacement for the + current value class implementation that was a less leaky abstraction, but as use cases were discovered, + the motivation grew to include them as the more obvious method for information hiding. On the other hand, + opaque type aliases are more future proof against changes to the JVM as the feature has no runtime footprint. + + **Jorge** agrees that the feature is good for information hiding and believes the feature will enable many more + library designs that benefit from this style of programming. + +5) **Adriaan** suggests that the proposal could clarify the language used to explain boxing by simplification to + emphasise that values of opaque type aliases share the runtime behaviour of the underlying type. + + **Jorge** believes that the point is already made in the document, but wants to make it clear that an extra layer of + indirection at runtime is avoided for opaque type aliases to subtypes of AnyRef. + +**Sébastien** concludes that action should be taken to further emphasise in the proposal the semantics of the feature +over its performance benefits. + +#### In Favour of the Proposal + +1) **Sébastien** highlights examples of opaque types in the proposal that are advantageous over value classes: + - Primitive arrays will be chosen if the underlying type is primitive. + - Specialised methods will be selected if the underlying type is primitive. + - In generic contexts, allocations of wrappers are avoided for opaque types aliasing reference types. + +2) **Miles** is in favour for the feature because it would be a safer intrinsic replacement for the tagging used in + Shapeless, as in his opinion it is an accident that the implementation of tagging can work in the current version of + Scala. + + **Erik** agrees that the current solution for tagging is not idiomatic and points out that value classes are not a + correct replacement either. + +#### Concerns With the Proposal + +1) **Martin** raises that an issue has been found with the proposals inclusion of recursive opaque type aliases, and is + skeptical that they can be allowed as they introduce a fundamentally new kind of recursion to the language. + + **Jorge** asks for clarification if this is referring to the example for a Fix point type given in the proposal. + + **Martin** confirms and suggests an alternative version could be achieved with conversions, but believes that the + idea implies too many changes to the language than the non-recursive cases. + + **Adriaan** asks the authors how importantly they value the recursive example. + + **Erik** answers that it he wouldn't mind if that part was dropped. The example was included because the methods + used in present Scala to get the same result again rely on "compiler tricks". + He clarifies that it was added under the assumption that if it is possible then it should be documented. + + **Jorge** agrees. + + **Adriaan** suggests that the recursive example is quite niche and could be postponed until a later time, as the rest + of the proposal is favoured by the committee. + +#### Other Remarks +> [YouTube time from 38'25'' - 41'54''](https://youtu.be/dFEkS71rbW8?t=2305) +> +>**Miles** asks **Martin** why he thinks that the fix type example is an entirely new kind of recursion. +> +>**Martin** answers that there is not a clear mapping to the DOT calculus, where recursion over types is through the +>self type of the current object. On the other hand, the fix example is recursion over a type parameter. +> +>**Miles** responds by questioning if this is so different because the fix example syntactically maps directly to an +>equivalent class-based implementation. +> +>**Martin** then offers a solution to fix that does not require recursion: two type aliases representing `Fix[F]` and +>`F[Fix[F]]` with conversions between the two. He summarises that the problem with the opaque types proposal is that it +>suggests that +>these two types are the same type, which is not friendly to a compiler. + +**Jorge** ends the item by clarifying that an implementation is available in Dotty in a pull request where +discussion is also taking place. + +#### Conclusion + +Opaque types are a method of hiding the right hand side of a type alias, with the runtime semantics of the underlying +type. It is discussed as an idiomatic method for tagging, and possibly a fixed point type, with performance benefits +over value classes. +The committee members who commented are in favour of the feature, with concerns for the semantics of recursive +types and the precision of the language used in the proposal. + +**Actions:** + - Emphasise semantics over performance benefits in document. + - Postpone the inclusion of recursive opaque types. + +### [SIP-NN: Byname implicit arguments](http://docs.scala-lang.org/sips/byname-implicits.html) +[YouTube time from 43'02'' - end](https://youtu.be/dFEkS71rbW8?t=2582) + +**Jorge** explains that the committee are waiting for an implementation in Scalac, and are currently acting on the +proposal alone. At the end of the discussion the comittee will vote on whether or not to number the proposal. He also +suggests that Martin will review the proposal. + +**Miles** introduces Byname implicits as a feature that adds the functionality of the Lazy macro in Shapeless as an +intrinsic part of the Scala language, with the added motivation that the macro implementation in Scala 2 is very high +maintenance, with unsafe casts to compiler internal classes. +He explains that byname implicits are intended to be used to derive recursive implicit parameters, +for example type class derivation for recursive types such as List. The SIP proposal is simplified when compared to the +Lazy macro implementation and reuses exisiting byname parameter syntax. +He explains that it is advantageous over the exisiting macro because it supports detection of implicit divergence. + +**Jorge** asks if this feature is desirable because users of Lazy have reported long compilation times with stack +overflows. + +**Miles** answers by proposing that these cases are likely due to undetected implicit divergence, as the Lazy +macro implementation turns off the implicit divergence checks, which is not an issue in the implementation for this SIP +proposal. He clarifies that in any case, there is still performance overhead that could be improved for the +intrinsic implementation, highlighting the high rate of creation of thunks, but proposed that the SIP should not add +additional overhead to what is already given by using the Lazy macro. + +**Jorge** asks for comments from the other committee members. + +**Sébastien** offers that he has been convinced by the motivation section of the SIP, despite never personally requiring +the feature. However he disagrees that the parameters should desugar to lazy vals after implicit +expansion. Apart from concerns about performance, he suggests that the semantics are also surprising compared to +ordinary byname parameters. + +After unproductive discussions about the correct encoding for the desugaring, **Adriaan** suggests that discussion +should be taken to the pull request for the SIP. + +**Jorge** proceeds to introduce voting on numbering the issue, but notes that at this point **Iulian** has left the +meeting, so there is no quorum. Therefore, the votes for him and the other members will be collected after the meeting. + +Votes of those present in favour of numbering: +- **Sébastien** +- **Martin** +- **Adriaan** +- **Miles** +- **Seth** +- **Eugene** + +No votes against from present members. + +#### Conclusion + +Byname implicits are a feature to construct recursive implicit parameters, replacing a brittle macro implementation but +with idiomatic syntax and improved behaviour. +The committee seems in favour of the feature, with some concerns for performance. All members +present chose to number the proposal, but a quorum was not reached at the time. diff --git a/_sips/minutes/2018-05-18-sip-minutes.md b/_sips/minutes/2018-05-18-sip-minutes.md index 3f4c390f78..b707f52f73 100644 --- a/_sips/minutes/2018-05-18-sip-minutes.md +++ b/_sips/minutes/2018-05-18-sip-minutes.md @@ -62,7 +62,7 @@ Given the short time and amount of decisions that need to be made, the Committee *Structure* a) Have a **list of changes**, grouped in batches that would be decided within the next year, meeting once a month -b) **Plan** - full and strucutured list of changes that need to be implemented consolidated between the Committee members using a shared a Google doc +b) **Plan** - full and structured list of changes that need to be implemented consolidated between the Committee members using a shared a Google doc c) **Public comments** - each batch should be published on the Contributors thread, for a month at a time in order to have community involved, share their opinion and contribute. Advise was proposed - each thread should clearly point out start and end date of collecting the comments/suggestions. *Organisation* @@ -80,10 +80,10 @@ The above mentioned structure and organisation was gathered throughout the meeti 4. Other: spec, quorum -**Heather** bings up an important question "What about Scala spec" ([YouTube time: 4'49''](https://youtu.be/q2LVmTe9qmU?t=289)) to which **Martin** responds within the next year we should know which features are included as a first priority but that spec should not be left for the last minute. +**Heather** brings up an important question "What about Scala spec" ([YouTube time: 4'49''](https://youtu.be/q2LVmTe9qmU?t=289)) to which **Martin** responds within the next year we should know which features are included as a first priority but that spec should not be left for the last minute. **Miles** ([YouTube time: 8'45](https://youtu.be/q2LVmTe9qmU?t=525))suggested that SIP proposals should include draft specification changes to save time and effort pulling the eventual spec update together. **Martin** ([YouTube time: 37'59''](https://youtu.be/q2LVmTe9qmU?t=2279)) also raised a question about the decision making process, asking if it would be better to change to simple majority when it comes to voting. This was rejected by most of the Members and agreed it should be discussed in a different meeting or time. -**Conclusion** The first batch should be agreed upon, posted on the Contributors thread for public comments. Such discussion should be summaraized and included in the next meeting (22nd June 2018, after ScalaDays NewYork). +**Conclusion** The first batch should be agreed upon, posted on the Contributors thread for public comments. Such discussion should be summarized and included in the next meeting (22nd June 2018, after ScalaDays NewYork). diff --git a/_sips/minutes/2018-08-30-sip-minutes.md b/_sips/minutes/2018-08-30-sip-minutes.md new file mode 100644 index 0000000000..218877a1db --- /dev/null +++ b/_sips/minutes/2018-08-30-sip-minutes.md @@ -0,0 +1,298 @@ +--- +layout: sips +title: SIP Meeting Minutes - 30th August 2018 + +partof: minutes +--- + +# Minutes + +The following agenda was distributed to attendees: + +|Topic|Reviewers| Accepted/Rejected | +| --- | --- | --- | +|Summary of the Contributors thread [“Proposal to remove auto application from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-auto-application-from-the-language/2145) | Miles Sabin | Pending +|Summary of the Contributors thread [“Proposal to remove XML literals from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-xml-literals-from-the-language/2146) | Sébastien Doeraene | Pending +|Summary of the Contributors thread [“Proposal to remove the procedure Syntax”](https://contributors.scala-lang.org/t/proposal-to-remove-procedure-syntax/2143) | Josh Suereth | Pending | +|Summary of the Contributors thread [“Proposal to remove early initializers from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-early-initializers-from-the-language/2144) | Adriaan Moors | Pending | +|Summary of the Contributors thread [“DelayedInit or OnCreate, any solution?”](https://contributors.scala-lang.org/t/delayedinit-or-oncreate-any-solution/1748) | Adriaan Moors | pending | + +Jorge Vicente Cantero was the Process Lead and Darja Jovanovic was the secretary. + + +## Date and Location +The meeting took place on the 30th August 2018 at 5 PM CEST via Google Hangouts at EPFL in Lausanne, Switzerland as well as other locations. + +[Watch on Scala Center YouTube channel](https://youtu.be/gnlL4PlstFY) + + +Minutes were taken by Darja Jovanovic. + +## Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Jorge Vicente Cantero ([@jvican](https://github.com/jvican)), Process Lead +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Eugene Burmako ([@xeno-by](https://github.com/xeno-by)), Twitter +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), Independent +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Miles Sabin ([@milessabin](https://github.com/milessabin)), Independent +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Scala Center + +## Not present +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU + + + +## Proceedings +### Opening Remarks + +**Jorge** opens the meeting, explains SIP dynamics: + +Selected batches (proposals for language change in Scala 3) are published on Contributors + +Community has 1 month deadline to discuss the proposals + +Committee summarises the comments and discusses during the meeting + +Decision / voting / postponing the discussion + +[More in May 2018 minutes](https://docs.scala-lang.org/sips/minutes/2018-05-18-sip-minutes.html) + +### Summaries of discussions of the First Scala 3 batch + +### [“Proposal to remove auto application from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-auto-application-from-the-language/2145) +([YouTube time: 2’15’’ - 11’22’’ ](https://youtu.be/gnlL4PlstFY?t=136)) + +**Miles Sabin** summarised discussion on Contributors thread. +- Focuses on the Contributors discussion rather than on the proposal itself +- Underlines a lack of motivation in the light of a separate issue from [Dotty: Weak eta-expansion](https://github.com/scala/scala3/issues/2570) +- Concludes that this proposal should be aligned with eta-extension issue + +Summary: + +References + ++ [Scala Contributors thread](https://contributors.scala-lang.org/t/proposal-to-remove-auto-application-from-the-language/2145). + ++ [Dotty issue: Weak eta-expansion](https://github.com/scala/scala3/issues/2570). + ++ [Martin's comment on the issue above](https://github.com/scala/scala3/issues/2570#issuecomment-306202339). + +Comments + ++ One comment to the effect that the motivation doesn't actually provide any + motivating reasons. + + Commenter is pointed to the Dotty issue referenced above. The issue is a + request to make eta expansion more uniform and predictable, and is addressed + in Martin's comment linked to above. This proposal would appear to be a + corrolary of of that comment. + ++ Some questions about parentheses and implicit argument lists. + + Resolution from Sébastiane: implicit argument application syntax unaffected + by this proposal. + ++ A request for clarification about Java/Scala 2/3 mixed overrides, given the + Java exception. + + Resolution from Martin: "As long as there is a Scala-2 or Java version in the + set of overridden variants, the rule is relaxed" + ++ Some discussion of the use of "()" to indicate effects. + ++ Comment about interaction with type parameter lists, eg. `Promise[Unit]` vs. + `Promise[Unit]()`. + ++ Comment about interaction with methods returning values with an `apply` + method. How does a programmer tell whether the following are equivalent or not? + + ```scala + f()() + f.apply().apply() + f().apply() + ``` ++ Counter proposal from Rex following from the above, + + 1. Empty parameter lists, whether implicit or explicit, whether + zero-parameter or filled completely with default parameters, may be elided. + This matches what you’re allowed to do with overriding vs overloading anyway + at the JVM level. + + 2. Ambiguous parses are forbidden at the use-site. If `foo()` may be elided to + foo, then if its return value has an apply method, that apply method cannot + be called using foo(). + + 3. `.()` is another synonym for .apply(), so you can compactly disambiguate + parses. + ++ Comment from Gabriele, + + > I’m very much in favor of the spirit of this change, but a bit worried + > about the actual result. + > + > The idea is to normalize things, which makes total sense, but after this + > change we end up with more inconsistencies than before, due to the backward + > compatibility towards Scala 2. + ++ Interaction with nullary constructors. Currently `class Foo` is interpreted as + `class Foo()`. Mutatis mutandis for case class `apply` methods. + +**Martin** ([Youtube time: 11.37](https://youtu.be/gnlL4PlstFY?t=688)) mentioned that this proposal also came about due to New collection usecases that surfaced in recent work - showing that without a strict rule there is a high amount of "un-disciplined" use of (). But he agrees with Miles about merging the two proposals together. + +**Conclusion** **Jorge** takes the task to merge the proposals and extend the motivation. + + +### [“Proposal to remove XML literals from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-xml-literals-from-the-language/2146) + +**Sébastien** ([YouTube time” 14’53’ - 40’10’’](https://youtu.be/gnlL4PlstFY?t=891)) summarised discussion on Contributors thread. + +Summary: + +In favor of the removal: + +- Significant language specification weight, as well as compiler implementation. The whole XML spec must be embedded in Scala! + +- scala-xml is very complicated, and has serious usability problems + +- Adding the extra xml"""...""" shouldn’t be a bother + - For JSX-style support, maybe a jsx"" interpolator could have the same semantics as JSX, rather than that of scala-xml +- Direct language support for XML only existed because string interpolators did not exist back then (supposedly). It seems to be an obviously better design to build on string interpolators. +- Removes XML as a special case. With interpolators, one can embed arbitrary languages within Scala. + - Similar argument: XML should have no higher place in the language than YAML, JSON, etc. +- JSX-style use cases should use ScalaTags-style libraries anyway. +- XML being part of the language is the reason that XML libraries have stalled, and that JSON ones have flourished + - Counter-argument: lib stalling is due to the “symbol”-based translation. A name-based translation would not have this issue. + +Against the removal + +- Difficulty of syntax highlighting + - Shouldn’t be a real issue as long as editors are on board +- The promised XML interpolator was never materialized +- JSX is now in widespread use in languages for front-end development. It is ironic that Scala would drop support for a similar feature now. It is even built in some languages, e.g., TypeScript. + - JSX is simpler than scala-xml, though: no namespace support, in particular. +- For front-end devs looking at Scala/Scala.js, string interpolators will look horrible compared to JSX, and it might be one of those “no-no” things that will push them away. +- Being able to just copy-paste examples from the Net is nice. (8 Likes on this one) +- No one uses XML anymore, right? + - Some answer that they do. Especially in non-greenfield projects. + - Kojo uses XML literals as building blocks for the Storytelling feature. + +Counter-proposal + +Named-based XML desugaring: https://contributors.scala-lang.org/t/pre-sip-name-based-xml-literals/2175 + +- Less complexity in the language/compiler +- Open for library competition +- Compared to a string interpolator, flavors can be implemented using normal library code, without (whitebox) macros. + - Whiteboxness is necessary for xml”””””” to return a more precise type such as `xml.tags.Button` rather than `xml.Node` + +Other ideas +- Can it be a compiler plugin or a macro? + - No, a compiler plugin cannot hook into the parser, neither can a macro. + +Related links + +- Other XML libraries: + - https://note.github.io/xml-lens/ + - One in scalaz-deriving: https://gitlab.com/fommil/scalaz-deriving/tree/master/examples/xmlformat/src/main/scala/xmlformat (link behind a login wall, it seems) +- JSX-style libraries for Scala: + - https://github.com/OlivierBlanvillain/monadic-html + - Binding.scala, +- Ammonite script to convert HTML to the VDOM DSL of scalajs-react (a ScalaTags flavor): +https://gist.github.com/nafg/112bf83e5676ed316f17cea505ea5d93 + +Discussion: + +**Eugene** ([YouTube time: 25’30’]( https://youtu.be/gnlL4PlstFY?t=1530)) thinks that the proposal needs to be cleared about the impact, referring to possible replacements with string literals that might never happen. Suggests to position this proposal as simply removing the feature and leaving it up to the community to decide and implement the replacements. + +**Josh** ([YouTube time: 27’16’’](https://youtu.be/gnlL4PlstFY?t=1636)) clarifies that in order to replace the libraries one would need a proof of concept, and currently there is none. + +**Adriaan** ([YouTube time 30’](https://youtu.be/gnlL4PlstFY?t=1796)) summarises the discussion, pointing out that Committee needs to answer a question *will we support XML in some way* and *what would be the most "Scala-like" way to do so* and *who will be maintaining it*. + +**Seth** ([YouTube time 35’57’’](https://youtu.be/gnlL4PlstFY?t=2157)) is under the impression that large portion of XML user base are the ones using it to do generation and rarer to be reading in XML using the existing Scala XML support and asks others to share their impressions. +**Martin** re-phrases it as “using XML for pattern matching”. +**Sébastien** says it is super rare. +**Iulian** says it is used more than we think in pattern matching and in value definitions he seen in not OS projects; they can be found in old, large code basis; probably decreasing. +He suggests to ask IntelliJ to collect and share the XML usage patterns. + +### [“Proposal to remove the procedure Syntax”](https://contributors.scala-lang.org/t/proposal-to-remove-procedure-syntax/2143) + +([YouTube time: 40’13’’ - 52’10](https://youtu.be/gnlL4PlstFY?t=2404 )) + +**Josh Suereth** summarised the discussion on Contributors thread: + +- Underlines the general concern about the lack of motivation part of the proposal; +- Notes that in the Contributors discussion, ones that were for the removal would mostly put “+1” while ones against the removal would be more elaborate, that gives a false impression there were more arguments against the removal; +- Structures his presentation around community’s points in a light of better motivation adding his opinion after each +- Concludes that that going forward procedure syntax should be removed because in the long run it helps new developers learn Scala faster and better (more details below). + +Summary + **Josh’s** comments: + +Fixable/Addressable Concerns +- Concerned that rewrite tools (and people) would use def foo() = {} syntax instead of def foo(): Unit = {} + +Pros + +- Clean up inconsistency in the language +- Dropping return value is dangerous, in general +*Experience teaching Scala gave an insight to how often the return value is dropped which leads to broken code leaving students confused* + +Cons +- More verbose syntax to safely ignore return values +*Semi legitimate concern; developers need to change their habits and annotate return values when it’s important* +- Lazy people will just write def foo() = {} and get bad behavior. +*The way it is written leads to a confusion and should be removed from the proposal why: https://youtu.be/gnlL4PlstFY?t=2795 * + +Not well motivated Pros + +- Safer +*We need to detail “why” it is safer* + +- Cleaner for refactoring tools to treat methods of this sort. +*Given the way things are structured, this issue comes down to the way the methods are parsed => change the parser betters the refactoring tools. This point needs to be clear in the proposal* + +Not well motivated Cons + +- People have to change their habits +- Proposal coming from people who don't mutate state +*After analyzing two of his “side-effecty” codebases, looking to find where he uses the most procedure syntaxes, Josh concluded that there are many : Unit* +- Call into question authority/judgement of proposer +*Josh doesn’t find it appropriate and will ignore such comments stating that “...it is not a legitimate way to make a technical argument.” [YouTube time 42’07’’](https://youtu.be/gnlL4PlstFY?t=2522)* + +Counter Proposals + +- Effect tracking +*A bit of an “overkill”* +- Multiple "def" keywords, one which would mean side-effecting function +:= for side effects + +**Josh** concludes: big point to debate would the language consistency be worth the change to more verbose expression. + +**Iulian** ([You/tube time: ]( https://youtu.be/gnlL4PlstFY?t=2928)) adds that 1. last 5 years Syntax procedure was anyway deprecated; 2. going forward we should consider Scala 3 in a light of next 15 years, now is the right moment to clean up the language and 3. this is “the easiest refactoring to automate the code base” that could be a “zero cost migration” + + +**Josh** points out that current developers would need to change their habits but motivation lies in introducing new developers to Scala and having this consistency to help them stay, given that as it is now it takes longer to learn and making mistakes here is bad. + +**Jorge** says IntelliJ already warns developer whenever they use procedure syntax, and suggests them to rewrite it with an automatic rewrite. It’s true that not all Scala developers use IntelliJ, but a big part of do, and thanks to IntelliJ they are strictly discouraged to use procedure syntax. + +**Eugene** ([YouTube time: 50’49’’](https://youtu.be/gnlL4PlstFY?t=3049)) asks what is the migration strategy; is it possible to do a batch migration for the big code base or would it be necessary to go through your code in IntelliJ? + +**Seth** reminds the viewers/Committee that it was deprecated only in 2.13 OM4, which is probably why this proposal got so many responses. + +**Conclusion** Before making a final decision, the proposal needs a better motivation 1. Why it is safer 2. Refactoring tools / parsing 3. IntelliJ tool explained? + + +### [“Proposal to remove early initializers from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-early-initializers-from-the-language/2144) +([YouTube time: 54’12’’ - 59’35’](https://youtu.be/gnlL4PlstFY?t=3250)) + +**Adriaan’s** best summarised in comment: https://contributors.scala-lang.org/t/proposal-to-remove-early-initializers-from-the-language/2144/24?u=adriaanm + +### [“DelayedInit or OnCreate, any solution?”](https://contributors.scala-lang.org/t/delayedinit-or-oncreate-any-solution/1748) +([YouTube time: 59’35’’ - end ’](https://youtu.be/gnlL4PlstFY?t=3575)) + +**Adriaan’s** best summarised in comment: https://contributors.scala-lang.org/t/delayedinit-or-oncreate-any-solution/1748/36 + +**Conclusion** 14 days left on the Contributors thread, Committee should revisit this topic later on. diff --git a/_sips/minutes/2018-09-24-sip-minutes.md b/_sips/minutes/2018-09-24-sip-minutes.md new file mode 100644 index 0000000000..4a33926b50 --- /dev/null +++ b/_sips/minutes/2018-09-24-sip-minutes.md @@ -0,0 +1,216 @@ +--- +layout: sips +title: SIP Meeting Minutes - 24th September 2018 + +partof: minutes +--- + +# Minutes + +The following agenda was distributed to attendees: + +|Topic|Reviewers| Accepted/Rejected | +| --- | --- | --- | +| Summary of the Contributors thread [“Proposal to remove XML literals from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-xml-literals-from-the-language/2146) | Sébastien Doeraene | Pending +| Summary of the Contributors thread [“Proposal to remove the procedure Syntax”](https://contributors.scala-lang.org/t/proposal-to-remove-procedure-syntax/2143) | Josh Suereth | Pending | +| [Proposal to add Intersection Types to the Language](https://dotty.epfl.ch/docs/reference/new-types/intersection-types.html) | Martin Odersky | Discussion opened until the 25th October 2018, comments welcomed [here](https://contributors.scala-lang.org/t/proposal-to-add-intersection-types-to-the-language/2351) | +| [Proposal to Add Union Types to the Language](https://dotty.epfl.ch/docs/reference/new-types/union-types.html) | Martin Odersky | Discussion opened until the 25th October 2018, comments welcomed [here](https://contributors.scala-lang.org/t/proposal-to-add-union-types-to-the-language/2352) | +| Proposal to add Implicit Function Types to the Language | Martin Odersky | Discussion opened until the 25th October 2018, comments welcomed [here](https://contributors.scala-lang.org/t/proposal-to-add-implicit-function-types-to-the-language/2353) | +| [Proposal to add Dependent Function Types to the Language](https://dotty.epfl.ch/docs/reference/new-types/dependent-function-types.html) | Martin Odersky | Discussion opened until the 25th October 2018, comments welcomed [here](https://contributors.scala-lang.org/t/proposal-to-add-dependent-function-types-to-the-language/2354/1) | +| [Proposal to add Trait Parameters to the Language](https://dotty.epfl.ch/docs/reference/other-new-features/trait-parameters.html) | Martin Odersky | Discussion opened until the 25th October 2018, comments welcomed [here](https://contributors.scala-lang.org/t/proposal-to-add-trait-parameters-to-the-language/2356) | + +Jorge Vicente Cantero was the Process Lead and Darja Jovanovic was the secretary. + + +## Date and Location +The meeting took place on the 24th September 2018 at 5 PM CEST via Google Hangouts at EPFL in Lausanne, Switzerland as well as other locations. + +[Watch on Scala Center YouTube channel](https://youtu.be/tEb4UF6RJrM) + + +Minutes were taken by Darja Jovanovic and Jorge Vicente Cantero. + +## Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Jorge Vicente Cantero ([@jvican](https://github.com/jvican)), Process Lead +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Eugene Burmako ([@xeno-by](https://github.com/xeno-by)), Twitter +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), Independent +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Scala Center + +## Not present +* Miles Sabin ([@milessabin](https://github.com/milessabin)), Independent +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU + +## Proceedings +### Opening Remarks + +Jorge opens the meeting, explains SIP dynamics: +Finalising discussion about the 1st batch, action points +Introducing batch two +Decision / voting / postponing the discussion + +### Discussion of the first Scala 3 batch + +#### [“Proposal to remove XML literals from the language”](https://contributors.scala-lang.org/t/proposal-to-remove-xml-literals-from-the-language/2146) +([YouTube time 3’ - 16’50’’](https://youtu.be/gnlL4PlstFY?t=891)) + +**Sébastien** suggests to postpone the removal of XML and Procedure syntax, because when +the removal takes place it will be a code breaking change, not a binary or +tasty one. Adds it would be better to focus on changes that have an impact on +tasty and binary format and deal with these later. + +**Seth** ([YouTube time:4’54](https://youtu.be/tEb4UF6RJrM?t=294)) suggests to have a warning +notes that it will eventually be removed. + +**Eugene** asks what would be the positive effect of that change? And that we +need to vote on it first. + +**Iulian** asks what are the promises with regards to binary-compatible and +source-compatible releases in Scala 3. To him it looks weird that we could +break the source between 3.0 and 3.1. + +**Josh** notes that by enforcing binary compatibility across Scala 2 and Scala +3 we are sacrificing source compatibility. He asks for this decision to be +more thought over as it is a big decision with lots of impact for Scala +tooling. He agrees we can make source-breaking releases nicer to use in +source-based build tools like Pants or Bazel, but trading off binary +compatibility by source compatibility is not a decision to take lightly [more]( +https://youtu.be/tEb4UF6RJrM?t=612). + +**Martin** thinks that no matter what trade-offs we do with regards to +compatibility, he'd like to be able to remove XML literals in the first +release of Scala 3.0 because having the XML spec inside the Scala spec gives +a bad impression of complexity of the language, where he believes Scala is +instead a more lightweight language than its competitors. There is no way he +can make this argument if the XML spec continues to be in the relatively +simple Scala language specification [more](https://youtu.be/tEb4UF6RJrM?t=916). + +(The discussion with regards to binary compatibility and source compatibility trade-offs is postponed.) + +#### [“Proposal to remove the procedure Syntax”](https://contributors.scala-lang.org/t/proposal-to-remove-procedure-syntax/2143) + +([YouTube time: 16’50’’ - 19.28’’](https://youtu.be/tEb4UF6RJrM?t=1010)) + +**Jorge** reminds that in the last meeting we agreed that before moving forward with the change we needed: +1. A better motivation +2. A good explanation of why this change promotes the use of types (making it safer) +3. A removal of the examples that were misleading +4. A link to a Scalafix rewrite that could make a migration. + +**Jorge** then points out that the changes need to be done in order to move +forward, but is asking a Committee to voice their opinion about removing this +feature in Scala 3. +**Josh** underlines that there were 2 parts in the debate +1) Are procedures different than a method, do we want them visually +distinctive? +2) Other issues listed by **Jorge** above. In particular, the fact that we want people to explicitly annotate the unit in their methods because it makes code more readable. + +A decision will be taken into the future when all those items are acted on. + +### Discussion of the second Scala 3 batch + +An overview of the second batch can be found [in this Scala Contributors thread](https://contributors.scala-lang.org/t/second-batch-of-scala-3-sips-additions-to-scalas-type-system/2376). The batches under discussion are: + +1. https://contributors.scala-lang.org/t/proposal-to-add-trait-parameters-to-the-language/2356 +2. https://contributors.scala-lang.org/t/proposal-to-add-intersection-types-to-the-language/2351 +3. https://contributors.scala-lang.org/t/proposal-to-add-union-types-to-the-language/2352 +4. https://contributors.scala-lang.org/t/proposal-to-add-dependent-function-types-to-the-language/2354 +5. https://contributors.scala-lang.org/t/proposal-to-add-implicit-function-types-to-the-language/2353 + +Feedback on these proposals is open until the 25th October 2018, as describe +in the linked Scala Contributors thread. + +#### [Proposal to add Intersection Types](https://dotty.epfl.ch/docs/reference/new-types/intersection-types.html) and [Union Types](https://dotty.epfl.ch/docs/reference/new-types/union-types.html) to the language + + ([YouTube time: 20’49’’ - 24'01](https://youtu.be/tEb4UF6RJrM?t=1250)) + +**Martin** presents the intersection types as per doc. He does a basic +description of the feature and points out that intersection types are the +duals of union types. He points out that union types have helped replace most +of the lubbing mechanism and early precocious lubbing that happened in Scala +2 (which happens in less degree in the current implementation of Scala 3 but +could be improved in future releases). **Martin** also thinks that union +types are useful for null safety, where any type coming from Java could be +annotated as `T | Null`. He then goes on describing further implementation +details and trade-offs that Scala 3 does in this space. **Adriaan** asks what +are the trade-offs between the encoding of union types that we have in Scala +and the one they use in other languages like Typescript. **Martin** points +out that performance-wise Scala union types would be more performant because +`T | Null` wouldn't box if `T` is a primitive type. + +**Sebastien** ([YouTube time: 30’03’’](https://youtu.be/tEb4UF6RJrM?t=1803)) +gives his input based on the fact that Scala.js already has Union Types in +Scala 2. He states that they are very limited; they were introduced for +modeling because some libraries “desperately needed” them but turned out they +were overused for no apparent reason. He advises to document the Union Types +proper usage well and not get discouraged by the possible “overusage”. + +There is some back-and-forth between **Sebastien** and **Josh** with +regards to performance of union types and their boxing (especially in the +presence of specialization). [More](https://youtu.be/tEb4UF6RJrM?t=1913) + +#### Proposal to add Implicit Function Types to the Language + +URL: https://dotty.epfl.ch/docs/reference/instances/implicit-function-types.html + +([YouTube time: 39’01’’ - 43’11’’](https://youtu.be/tEb4UF6RJrM?t=2341)) + +**Martin** explains what implicit function types are about and points out it's +a pretty “hot” feature that was published in POPL 2018. +He underlines the advantages of implicit function types (like further +abstraction of code that depends on a notion/representation of a context, +like Scala 3's compiler) and points out that implicit function types can +replace the reader monad, even though it's about 10x faster than the reader monad +is. A comprehensive explanation of what implicit function types can do can be +found in [Olivier's Blainvillain talk at +ScalaDays, Berlin 2018](https://slideslive.com/38908156/applications-of-implicit-function-types). +**Martin** thinks that implicit function types should be seen as the +canonical way of doing scope injection, which gives you a lot of +expressivity, to which **Sebastien** adds that what Martin means by canonical +scope injection doesn't necessarily correspond with the way people do normal +scope injection, because in normal scope injection you can't refer to +identifier or parent scopes. **Martin** clarifies that for him comonadic +abstraction are the classical way of scope injection in which we inject +things into an environment, hence the use of canonical scope injection when +referring to implicit function types which allow you to do the same. His +definition of scope injection comes more from a typing rules perspective +rather than the lexical point of view. **Martin** agrees that if there is a +name clash with implicit function types there is a problem indeed. + +#### [Proposal to add Dependent Function Types to the Language](https://dotty.epfl.ch/docs/reference/new-types/dependent-function-types.html) + ([YouTube time: 43’11’’ - 44’40’’](https://youtu.be/tEb4UF6RJrM?t=2591)) + +**Martin** mentions that dependent function types is the last big addition to Scala's type checker. The reason why they are added is because Scala has dependent methods and there is a need for dependent functions (the same rationale has been doing with regards to implicit methods and implicit function types). It's an obvious win because dependent function types allow us to abstract over the idea of implicit methods in functions, so the more we can do the better. Initially he was afraid of the feature because he thought it violated this Scala principle that in the end anything is an instance of a class in some way and it turned out that a new encoding of dependent function types made this initial argument moot. Dependent function types are now encoded as implicit function types with type refinements, so this way it doesn't violate that principle. +**Adriaan** mentions that the last missing bit is polymorphic function types +and Martin agrees and says that they are looking into that, but maybe not for +Scala 3.0 (Guillaume Martres is pushing for polymorphic function types). + +#### [Proposal to add Trait Parameters to the Language](https://dotty.epfl.ch/docs/reference/other-new-features/trait-parameters.html) + +([YouTube time: 44’42’’ - end ](https://youtu.be/tEb4UF6RJrM?t=2682)) + +**Martin** describes trait parameters and says that they subsume a large number of use +cases of early initializers. They were not added to Scala from the start because of +uncertainty in the way they would work with regards to linearization and +initialization of parameters. The way they solved this problem is by +enforcing the rule that only the class extending a trait with parameters can +pass the parameters. The motivation to add trait parameters is to regularize +the language and get rid of early initializers which are an ad-hoc feature +and are much harder to understand how to use correctly. Afterward, the +Committee discusses some of the limitations of trait parameters. +**Josh** ([YouTube time: 48’40’’](https://youtu.be/tEb4UF6RJrM?t=2920) +suggests he will find one of his libraries that uses a lot of early +initializers and see if trait parameters allow him to replace them. He's +curious about how clean would the code look after the change. + +**Jorge** then wraps up the meeting, points out how feedback on these +proposals would work (check the following link +*https://contributors.scala-lang.org/t/second-batch-of-scala-3-sips-additions-to-scalas-type-system/2376*) +and finalizes the discussion. + +**Conclusion** Next meeting will be dedicated to the Second Batch disscusion. diff --git a/_sips/minutes/2018-11-26-sip-minutes.md b/_sips/minutes/2018-11-26-sip-minutes.md new file mode 100644 index 0000000000..776257508a --- /dev/null +++ b/_sips/minutes/2018-11-26-sip-minutes.md @@ -0,0 +1,166 @@ +--- +layout: sips +title: SIP Meeting Minutes - November 1-3 2018 + +partof: minutes +--- + +# Minutes + +The following agenda distributed to attendees is [here](https://docs.google.com/spreadsheets/d/1JdTyAxqqKqXtiXnZBPTaesMrWk7lyTWna1VPL3N5KWo/edit?usp=sharing). + + +Jorge Vicente Cantero and Darja Jovanovic were the Process Leads. + + +## Date and Location +The meeting took place on November 1-3 2018, during the working hours 9 AM - 5 PM CET, at EPFL in Lausanne, Switzerland as well as other locations. + +The meeting was not recorded. + + +## Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Jorge Vicente Cantero ([@jvican](https://github.com/jvican)), Process Lead +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), Independent +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Miles Sabin ([@milessabin](https://github.com/milessabin)), Independent +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Scala Center + +## Joined online + +* Eugene Burmako ([@xeno-by](https://github.com/xeno-by)), Twitter + +## Not present + +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU + +## Proceedings +### Opening Remarks + +The SIP Committee gathered for the first time face-to-face, for an extensive 3-day SIP meeting. The main goals and achievements of these meetings were: + +- Understand better the upcoming changes to Scala; +- Agree about the role of the Committee in the Scala 2 to Scala 3 transition; +- Outline an action plan within a set time-frame; +- Other: Unanimously voted for Guillaume Martres to join the Committee. + +*Better understanding* was enabled by in depth presentations and Q&As with the EPFL Dotty team; *the Approach* was agreed upon the first day which resulted in creating “FAQs about Scala 3” (see below) and *the Action Plan* was outlined and is still under construction; several issues were opened (please see the list at the end of this document) and a project plan ["Meta-programming in Scala 3"](https://github.com/scala/scala3/issues/5489) has been developed. + +As the most important points and summary is reflected in “FAQs about Scala 3”, it will stand as an official “minutes” for this unique SIP meeting. + +The following document is not intended to fully answer the listed questions, but to acknowledge them; the SIP Committee is outlining a frame and will pursue answers moving forward. Answers may change down the line, as the Process evolves. + +## Frequently Asked Questions about Scala 3 + +### What is the goal of Scala 3? +This new iteration of the language will be focused on simplification, ergonomics, and on creating a stronger foundation for future evolution. +In addition, the goal is for Scala 3 to be friendlier to newcomers with a swift onboarding experience. +As usual, existing Scala code should be able to transition to Scala 3 with minimum pain. + + +### What’s the timeline for Scala 3? + Scala 3 is planned to be released in 2020. There will be two phases. +The first phase will end in 2019 with a feature freeze. Before the feature freeze, the SIP Committee and the Scala 3 team will focus on ironing out the set of language features and concrete semantics. +The second phase will continue into 2020, where the focus will shift to hardening, tooling and polishing documentation to ensure a smooth migration. + +### Who’s behind Scala 3? +Over the last five years, Prof. Martin Odersky and his team at EPFL have developed Scala 3. (Also, several Scala 2 features were first incubated in Scala 3.) +Scala 3 will continue to leverage this collaboration with the Scala 2 team at Lightbend to improve the language for existing Scala users and ease migration. + + +### What’s the role of the SIP Committee in the Scala 3 migration? +The SIP Committee takes account of the interests of the varied stakeholders of the Scala language. Regarding the transition to Scala 3, the Committee is tasked with: +1. Curating language changes in the Scala specification; +2. Providing recommendations for migration from Scala 2 to Scala 3; +3. Work with the Scala Center to be a point of reference during the transition to Scala 3, incorporating feedback from implementation experience and from the community. + +The Committee came up with the curated list, based on 3 categories, "core", "essential", and "not core". + +"Core" are well-defined features or changes that are already designed and implemented. They have been accepted on principle, but the finer details are still up for discussion. + +"Essential" are wide, unsolved areas for which the Committee recognizes that it cannot decently ship Scala 3.0 without a final design and implementation to solve them. Nothing has been accepted yet because they're not even fully designed yet. + +"Not core" + +Please see the [full list here](https://docs.google.com/spreadsheets/d/1GWJUo0U3JbBtrfg5vqgb6H5S6wlU5HnTxebLcHwD1zw/edit?usp=sharing), naming the "core" features as follows: + +[Early Initializers](https://dotty.epfl.ch/docs/reference/dropped-features/early-initializers.html) + +[Trait Parameters](https://dotty.epfl.ch/docs/reference/other-new-features/trait-parameters.html) + +[Intersection Types](https://dotty.epfl.ch/docs/reference/new-types/intersection-types.html) + +[Union Types](https://dotty.epfl.ch/docs/reference/new-types/union-types.html) + +[Dependent Function Types](https://dotty.epfl.ch/docs/reference/new-types/dependent-function-types.html) + +Implicit Function Types (https://dotty.epfl.ch/docs/reference/instances/implicit-function-types.html) + +[Weak Conformance](https://dotty.epfl.ch/docs/reference/dropped-features/weak-conformance.html) + +[Type Lambdas](https://dotty.epfl.ch/docs/reference/new-types/type-lambdas.html) + +Type Checking + +[Type Inference](https://dotty.epfl.ch/docs/reference/changed-features/type-inference.html) + +[Implicit Resolution](https://dotty.epfl.ch/docs/reference/changed-features/implicit-resolution.html) + +[Pattern matching](https://dotty.epfl.ch/docs/reference/changed-features/pattern-matching.html) + +[Existential Types](https://dotty.epfl.ch/docs/reference/dropped-features/existential-types.html) + +[Type Projection](https://dotty.epfl.ch/docs/reference/dropped-features/type-projection.html) + +[Class Shadowing](https://dotty.epfl.ch/docs/reference/dropped-features/class-shadowing.html) + + + +### What’s the plan for keeping the migration period as short as possible? +A smooth migration process is key for the success of Scala 3. We have learned from our own past experience as well as that of other language communities (for example, Python 3) to recommend the following plan. + +These are the key properties of a successful upgrade plan that we recommend to incorporate in the migration to Scala 3. + +1. **Static types.** Most Scala code leverages static types which makes migrating safer and easier. +2. **Tooling to ease upgrades.** There should be a rewriting tool for automatic migrations and changes in the current Scala tooling. This tool should accommodate most of the needed changes. +3. **Shared standard library.** Scala 2.14 and Scala 3.0 should share the same Scala standard library. + +In addition, Scala community has a culture of upgrading the ecosystem on every major version of Scala through the community build. We recommend to leverage the same mechanism to vet Scala upgrades with the migration to Scala 3. + +**Incremental.** Instead of a one-time big upgrade, users should be able to adopt Scala 3 at their own pace. + + a) Compatibility and cross-building. Users should be able to use a common subset of Scala to mix Scala 2 and Scala 3 projects (to be determined after the feature freeze) in the same codebase. Scala 2 should guide users towards this subset through deprecation warnings. + + b) [Tasty](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html) compatibility. Scala 2 and Scala 3 should converge on the use of Tasty, an intermediate representation format, that will have a strong backwards compatibility policy. + +### How will the transition to Scala 3 affect users of Scala 2 macros and reflection? + +The dependency of Scala 2 macros and reflection on internal implementation details of the Scala 2 compiler means that significant change is inevitable if Scala is to evolve. +We recognize that important parts of the Scala ecosystem have made essential use of the Scala 2 facilities and that it is vital that as many as possible of these use cases be accommodated in Scala 3 in some form or another. This will be disruptive, but we hope to mitigate the disruption by providing facilities which make the more straightforward and important scenarios simpler while still leaving others possible. +Our direction is still evolving; however we believe that replacing the current excessively general and expressive macro system with a suite of less powerful but complementary tools is the way forward. +Currently we are exploring options which range from improved support for type level programming in the language itself (eg. specialized inline, match types, stable definitions, GADT improvements); intrinsifying certain features currently supported by macros (eg. by-name implicits, generic programming primitives); through to less general forms of metaprogramming (quote/splice and staging) and portable reflection via Tasty (which we [recommend](https://github.com/scalacenter/advisoryboard/pull/40)) to support in both Scala 2/3 and via compiler-independent libraries and tools. We recommend that most current uses of Scala macros and reflection can be accommodated by some combination of these tools. +For more about the project's progress, please see https://github.com/scala/scala3/issues/5489 + +### How do we plan to address language experimentation? +We acknowledge that language experimentation is necessary for improving the language. We also believe it requires a different vehicle than stable Scala releases. We don’t have a concrete solution for now, but we’re working on one. + +### Other “documents” created during the meetings: + +[SIP: Structural Types](https://github.com/scala/scala3/issues/5372) + +[SIP: TASTY changes](https://github.com/scala/scala3/issues/5378) + +[SIP: Underscore Syntax for Type Lambdas](https://github.com/scala/scala3/issues/5379) + +[Should we bring back rewrite methods?](https://github.com/scala/scala3/issues/5381) + +[Features work progress overview](https://docs.google.com/spreadsheets/d/1GWJUo0U3JbBtrfg5vqgb6H5S6wlU5HnTxebLcHwD1zw/edit?usp=sharing) + +For more info please consult the Dotty documentation: +https://dotty.epfl.ch/docs/reference/overview.html + diff --git a/_sips/minutes/2019-03-13-sip-minutes.md b/_sips/minutes/2019-03-13-sip-minutes.md new file mode 100644 index 0000000000..80854b32e3 --- /dev/null +++ b/_sips/minutes/2019-03-13-sip-minutes.md @@ -0,0 +1,645 @@ +--- +layout: sips +title: SIP Meeting Minutes - March 13-15 2019 + +partof: minutes +--- + +# Minutes + +The agenda distributed to the attendees is [here](https://contributors.scala-lang.org/t/third-batch-of-scala-3-sips/2862). + +13-15 March 2019 the SIP Committee met for the second time in person for a 3-day intense SIP meetings to discuss the upcoming changes proposed by the Dotty team. + +In [2018 November’s meeting](https://docs.scala-lang.org/sips/minutes/2018-11-26-sip-minutes.html) the SIP Committee agreed to treat the Dotty proposals as an exception to the standard process. Change is in that the Committee would focus on Dotty proposals for the next year, analyse the proposed changes one by one, include the community feedback, and publicly discuss the pros and cons of each. + +The purpose would be to help the Committee and the community get familiarized with all the changes and features, share their experiences, comments & concerns, and in turn help the Dotty team to integrate the feedback before the Scala 3 release. + +To be able to assimilate all proposed changes (~30), the Committee agreed to adapt the process as follows: the Committee would propose the batches (4-6 features) for discussion in the community for a month, in monthly SIP meetings each feature would be discussed by the Committee and a summary of the Community discussion would be included. Voting was preliminary, no final decisions were made during this period. + +Committee also agreed to have intensive 3-day meetings once a quarter in order to cover the numerous changes, understanding that one hour meeting a month would not suffice. + +## Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Sebastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center +* Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Miles Sabin ([@milessabin](https://github.com/milessabin)), Independent +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Scala Center + +## Proceedings + +Committee was faced with about 30 features they needed to go over, discuss, and have action points or conclusions come out of it. The following minutes are a summary of what was said during 3-day meetings, they are not exhaustive or to be taken ad-verbatim, they serve as a record and a situation at the current state. + +There’s a total of ~30 features to be discussed and decided upon. + +We started with a quick run through all the issues and discussed what would take less or more than 30 min. Starting with the "fast" ones. + +### Class Shadowing + +Surprisingly many objections on the contributors thread. + +**Conclusion:** We go as planned, class shadowing goes away + +Deprecation in 2.14 or 2.13? Depends if this affects TASTY, but it can be deprecated later in the 2.13 section. + +### Existential types + +What do we do about them in TASTY, since they remain in Scala 2, and TASTY needs to be the common format between Scala 2 and 3. + +`Map[Class[_], Class[_]]` will be encoded as is. + +What about pairs where the existential type should be the same, `(T, T) forSome T`? They can be encoded as a type alias with a refinement. This seems like a common case. + +Adriaan mentions wildcard capture as the hardest thing about Java wildcards, and seems harder to understand than existentials. If the removal of existentials leads to wildcard capture, it’s not a clear win. + +Martin is not convinced that existentials interaction with the rest of the type-system is sound. Rebinding is the crux of the problem. They are also related to dependent types, and we already have that. + +Miles: leave the door open to re-introduce them later in the 3-series. + +Adriaan wants to spec wildcard capture as a way forward. It would also make it easier to interop with Java and the Streams collection, where wildcard capture is very common and currently it’s hard to use from Scala 2. + +Martin on the flip chart: + +~~~ +def f[X](x: C[X]) + +f(C[_]) +~~~ + +Here the compiler needs to add a skolem for `C[X1]` and use it as a type arg for `f`, or else the types don’t match. Later it needs to be removed or else unsoundness ensues. + +**Conclusion**: needs spec for what "capture" does. When do skolems get created, reused or removed. + +**Deprecation:** Can we deprecate only the syntax, but leave the inference as-is? Several options: + +* Deprecate in 2.14 + +* Warning only with -Xsource:3 + +### Weak Conformance + +Scala Contributors feedback: only literals should be converted, not "constant types". + +An inline val is a ConstantType which carries the exact value (inline val three = 3) is the type Int(3). Discussion revolves around whether List(three, 2.0) should promote three to Double, if three is a constant type. Seb is concerned about this, since three has a type Int, and this will change it to Double. + +What about def f = 3, f has a constant type but it may have side-effects. Currently Dotty will still inline and promote it to Double. This should be done only for pure expressions? + +Martin feels strongly about keeping `inline` as clean as possible, and less about the actual weak conformance rules. + +**The decision is**: inline vals are going to be transparent and weak conformance happens just like if they were literals. + +### Auto application + +Adriaan: we should allow overriding a Java-defined method without a parameter list. Then auto-application only happens for Java-defined methods. + +Martin tried that but lots of stuff broke and decided not to go that way. Even the standard library is inconsistent. For instance, Iterator.next. Seb might want to take a shot at it and see what breaks. + +What about the convention that () is used to indicate that the method is impure? + +Starting point to experiment in Dotty compiler: Method `isAutoApplied` in Typer.scala + +### Delayed Init + +We should delay until we know more about meta-programming. We need a credible replacement. + +### Opaque Type Aliases + +Adriaan would like them in 2.13, but there is a part that relies on having union types and it didn’t work. But there is a way to implement this in the 2 series. + +Guillaume thinks opaque type aliases shouldn’t be there. People want it for performance, but this is for semantics. Compared to value classes, which give you similar benefits, the only difference is performance. + +Adriaan believes opaque type aliases are `newtype` and that’s useful on its own. + +Seb: opaque type give you better interoperability with the platform (Java, JS, C). + +When Java adds value classes Scala will have to have that too, and we’re left with two concepts for the same use-case. + +Seth: implicit classes are not widely used in Scala. One use-case is for extension methods, and that has a specific replacement in Scala 3. + +Miles: value classes may be avoided because they’re buggy and performance is unpredictable. + +**Conclusion:** We should emphasize the interop aspects. + +### Eta expansion + +All methods are eta-expanded to a function type. Same goes for SAM types, but they need to be annotated with @FunctionalInterface (or gives a warning). + +The vote is YES. + +Seth makes the larger point: where should documentation go? There’s a gap between the Scala Language Tour and the Scala Spec. + +### Union Types + +Martin: it still requires some work and experimentation, but the current status is the most restricted version possible, so we can open it up more in subsequent releases. + +Seb: union types exist and work well in Scala.js. If it’s too restricted in 3.0 it may break a lot of Scala.js code. + +Miles: there is a distinction between how typing works, and how typing inference works, w.r.t to explicit types the user wrote -- widening vs not-widening. + +Singleton types have a similar issue w.r.t. to widening, Miles is going to work on a proposal. + +### Symbol Literals + +They are deprecated in 2.13, they’re going away. + +### Type Lambdas + +There’s been some waiting on kind-projector by Erik Osheim. + +Guillaume: They can be curried. Is that a good idea? + +Miles found a use of these in translating a macro from the Monocle library. + +**Conclusion**: They are in, but do we want to restrict currying? + +#### Syntax of type lambdas and existentials + +Discussion on syntax, and whether we should use ? for existential wildcards (conflicts with kind-projector) and __ for type lambdas.** ** + +Conclusion: + +* In the 2 series already, ? can be used interchangeably with _ for existentials + +* In the 3 series, __ is used for type lambdas + +* Later in the 3 series we move to _ for type lambdas + +See also: Dotty issue #5739. + +### Dependent function types + +Miles discusses some implementation details on how functions are represented in the Dotty compiler. + +Guillaume explains that `compose` is a tricky case to encode in the current state with dependent function types. + +**Conclusion:** YES + +### Name based pattern matching + +Miles discusses Boolean-extractors and the fact that the only way to bind on the match is using an @ binder, which seems too verbose. Martin insists that the return type of the unapply should tell you all you need to know about what to bind variables too, and Boolean doesn’t give any of that. + +Miles asked about the relation to his issue(/PR?) about boolean extractors, there was one use case + +So we intend to accept the proposal as-is, with just an addition that we are explicitly excluding implicits, and leaving that to a possible future separate SIP, but note that to support implicits, we would have to re-architect the compiler, the implementation would be complicated. + +Miles expressed some doubt about the proposal, but he's not going to make a stand about it. + +Martin: The text at [https://dotty.epfl.ch/docs/reference/changed-features/pattern-matching.html](https://dotty.epfl.ch/docs/reference/changed-features/pattern-matching.html) needs to be updated (in other respects than just the implicits question) before we vote on it. (Maybe there's an inflight PR about it? Not sure.) + +### **structural types** + +Adriaan: you want to support records, where you can represent a selection of fields, and a smaller selection will be a subtype. + +There is existing art in Shapeless, Miles says. + +Martin: SAP has settled on structural types for this (HLists? too slow, Martin: maybe we can make it faster? but no). Adriaan: we need to have it say so then, if that's the motivation. + +Iulian asked about overlap between selectable and applyDynamic. Martin says he intentionally made them nearly isomorphic, and with similar naming, but says there are separate things. + +Seb: scala.Dynamic is an empty trait. Martin: that's because we wanted to allow the methods to come in through implicits. + +Martin: we should read the paper by Philipp about the records (Miles & I haven't read it either, maybe none of us have yet?) to understand that use case better. Let's read the paper and then see if we need more use cases, there are people we could talk to who have them. + +Adriaan: can we model this with applyDynamic and an appropriate implicit, or does this really need to be separate. + +Martin: Chisel is another important use case where they need structural types. If we use applyDynamic we won't get that. + +Adriaan and Miles suspect, but are not yet sure, these can still be combined, using structural types, via match types. But there might still need to be a new compiler feature, perhaps via typeclass derivation? + +Martin: the members don't exist as members of a class, so it has to take the form of a normal refinement or Chisel won't work. + +Adriaan: the core distinction is: dynamic says if there's no member, you get the rewrite. This thing says if there *is* a member, you get the rewrite. Maybe these two opposite sides of the coin could be subsumed in something more general, and maybe that would open up even more interesting uses. + +Adriaan: Without having more methods on Dynamic, we just allow the existing methods to take implicits, so they can witness that (e.g.) the right fields are present. + +Adriaan: is this a good stepping stone to the eventual generalized form? It seems yes, I think we could generalize it later. Miles: I'd need to read Philipp's paper first to be sure. + +Seb: separately, there is one change in the existing proposal we should consider instead of always ascribing simply Selectable, we should allow a more specific subtype of Selectable to arise, by trying to adapt v to Selectable via implicits and if that results in a more specific type, use it. + +Adriaan: let's look at the typing rule in the proposal and see if we can refine it further, as Seb suggests. The group collectively revised the rule. Get the resulting rule from Adriaan's own notes? + +Seb: with the new rule, Selectable becomes an empty trait. + +Then Adriaan also put up the existing rule for Dynamic, to explore the possibility of unifying the two rules. + +What about the ClassTags in the new proposal? Do we even need them? The ClassTags could come in instead via the implicit? + +Instead of adding a cast that supplies the types of all the arguments. But we don't have vararg type parameters, so we would need to pass an HList type (which Scala 3 stdlib has) to represent the argument types. Different use cases would be free to also require ClassTag or any other such type that would be needed later at runtime; Miles and Seb agree this could be done with match types. + +Martin's conclusion: let's try it, I would support it if it works. + +Seb: "I can try to put that on my plate." + +Here's the notes from Adriaan: + +Selectable as marker trait similar to Dynamic + +~~~ +G |- v.a : U ~> (v': Q).a Q =:= C { ... a: U ... } - Member(C, a, _) G |- v' : Selectable ~> v'' +~~~ + +~~~ +G |- v.a : U ~> v''.selectDynamic[U]("a") + +G |- v.m(ai...) : U ~> (v': Q).a Q =:= C { ... m: (ai: Ai)U ... } - Member(C, m, _) G |- v' : Selectable ~> v'' +~~~ + +~~~ +G |- v.m(ai...) : U ~> v''.applyDynamic[(A1,...An), U]("m") +~~~ + +Java-reflect based Selectable: + +~~~ + def applyDynamic[Ai, U](name: String)(implicit ev: SummonAll[Ai, ClassTag]) +~~~ + +~~~ +G |- v ~> v': Q - Member(Q, a, U) G |- Q <: Dynamic +~~~ + +~~~ +G |- v.a : U ~> v'.selectDynamic("a") +~~~ + +Guillaume called our attention to this Chisel example that relies heavily on structural types: [https://contributors.scala-lang.org/t/better-type-inference-for-scala-send-us-your-problematic-cases/2410/88](https://contributors.scala-lang.org/t/better-type-inference-for-scala-send-us-your-problematic-cases/2410/88) , which links to [https://github.com/freechipsproject/chisel-template/blob/release/src/main/scala/gcd/GCD.scala#L13](https://github.com/freechipsproject/chisel-template/blob/release/src/main/scala/gcd/GCD.scala#L13) + +Guillaume's response is here [https://contributors.scala-lang.org/t/better-type-inference-for-scala-send-us-your-problematic-cases/2410/90](https://contributors.scala-lang.org/t/better-type-inference-for-scala-send-us-your-problematic-cases/2410/90) + +Guillaume a somewhat conservative option to satisfy Chisel would be: provide a trait that Chisel could mix in to Bundle. We already have a class scala.reflect.Selectable, it uses Java reflection to support structural access. And you also get inference of anonymous subclasses that works like Scala 2. reflectiveSelectable + +Martin: go back to the Scala 2 behavior where we always keep the members of anonymous subclasses as part of a type refinement. + +Scala 2 has reflectiveCalls, Scala 3 has reflectiveSelectable, Scala 3 could make the former an alias to the latter, to support cross-compilation. But then the discussion on this got complicated, Martin suggested to Guillaume that they work it out later. + +### **Extension methods** + +Martin: the this-based syntax "felt weird". but Adriaan thinks the def (c: Circle) circumference: Double = ...syntax is weird. Martin says he thought so initially but after a few months of experience, came around. "I tried it, I gave talks about it, it just didn't feel right." + +Miles: this is fine for single extension methods, but if you want to define a group of related methods, it gets repetitive. + +So if you want to avoid the repetitiveness, you can use the existing mechanism (implicit class ... extends AnyVal), do we want to continue to support both? + +Martin: the infix syntax works well with right-associative (ends with colon) methods + +Martin mentioned that Jon Pretty thought the colon thing ought to be for extension methods *only* + +Seb is concerned that if visibility of extension methods is sometimes based on whether the simple name of the method is visible, that accidental shadowing will become more common. + +Martin: implicit class will be deprecated. + +Miles asks what about: + +~~~ +extends (x: A) { + + def foo(y: A) = ... + +} +~~~ + +Adriaan dislikes losing the regularity of our syntax for definition, Seth has the same feeling. To argue for it, Martin showed the "semigroups and monoids" example from the document; he thinks it shows that extension methods are core to typeclass support, which helps us think of them as something core enough to the language to make it plausible to have an unusual new syntax for them. + +Adriaan: can we summarize as, the syntax does take some getting used to, but it's the outcome of a long design process where the alternatives were all weighed (and even, in the case of this syntax, implemented); as a compromise, we might consider offering something like the extends syntax to avoid having to write the first argument over and over again. (But Seb objects it looks like a block but isn't.) + +### **Implicit resolution** + +Background in "Changes in Implicit Resolution". We went down the points in this document one by one; Martin offered the motivation for each point. Seth suggests that the motivations be added to the document, to help the community understand the changes. (I didn't have time to summarize all the motivations for these notes.) + +Martin: implicits were designed to have as short as spec as possible, by saying either the name is visible or it isn't. But it's "pretty unusable". + +The "A takes more inferable parameters than B" clause of point 7 is under discussion; Martin currently intends to drop that rule (inverting it was also considered). + +### **Implicits redesign** + +Note that for compatibility, 3.0 will still have to allow implicit def for conversions, for cross-building. See "relationship with Scala 2 implicits" section on the Dotty site, under "Contextual" (add link). + +Guillaume is uncomfortable with implied mapping to different underlying semantics (points 1, 2, 3 at [https://dotty.epfl.ch/docs/reference/contextual/relationship-implicits.html](https://dotty.epfl.ch/docs/reference/contextual/relationship-implicits.html)). Will users think of these things in terms of the desugaring into Scala 2 implicits (as Guillaume is doing), or will they understand them directly (as Martin hopes)? + +Miles shares Guillaume's worry about implied mapping down to different underlying constructs/semantics. + +Adriaan this is a core principle we have to agree on before we can agree on the syntax changes. This is a change of philosophy for Scala, we are trying to make Scala more approachable. If we are successful, then users shouldn't *need* to understand these things by mentally mapping onto Scala 2 implicits. Martin: don't read this "comparison with Scala 2 page" with the idea that this is what users will read in order to understand the new system. + +Adriaan is worried about the TASTy-compat implications of the naming rule for the anonymous implied instances, could we support this directly in TASTy so that the names don't get baked in to the TASTy files? + +Perhaps we don't need both the and implicitly, we could deprecate and get rid of one of them. + +Martin: motivation. I invented implicits, why turn away? There have been negative reactions, specific uses of implicits have a good reputation. For example, Kotlin copies everything about Scala except implicits. Implicits as a general mechanism have a poor reputation are not obviously a coherent single concept. + +Martin is quite passionate about not understanding the new constructs primarily by mentally mapping them onto Scala 2. + +Miles sees a different criticism coming from the Haskell direction, which he doesn't agree with but considers better motivated than the Kotlin direction one. "The really nice thing Scala has done is to treat typeclasses as types and instances as values." + +So Miles likes the use sites, but he's not happy with the definition sites, "it's obscuring what the definitions actually are" (agreeing with Guillaume). "You're adding magic to appease the Haskellers" when what we had was already coherent. + +Martin is "100% convinced this *is* the syntax". "It's an eye-opener, these things are so clear now!" <-- example feedback + +"The whole point of implicits is synthesizing terms from types. You, compiler, you do that, you synthesize the terms for me, it's tedious." Martin: The new syntax allows the definition site to "go straight to the point" and "specify the minimum needed" to do the synthesis. + +(At some point there was a discussion involving Miles where it was suggested that Cats needs to be ported to this new stuff, not all of Cats immediately but the kernel, to see how it looks and make sure it works.) + +Seb: there are two widely different things in this proposal that are mixed together, we don't know how to talk about them separately. One is, what is the real new expressive power, what can I write, how do I write it. Two, there is the names of things, implied and given, not so much as syntax, but as the names of the concepts. + +Martin: avoiding the word implicit was something of an exercise, to avoid confusing the old system and new system in the minds of people who know the old system. In the long run, it might be better to just go ahead and talk about "implicits". + +Seth: how will we teach this from scratch? Martin: pages like [https://dotty.epfl.ch/docs/reference/contextual/givens.html](https://dotty.epfl.ch/docs/reference/contextual/givens.html) actually are an attempt at this. + +Miles: in the `ListOrd[T]` example, it's essentially a function definition, a function from `Ord[T]` to `Ord[List[T]]`, why doesn't it look like I'm writing a function? + +Seb: could we do implied def..? (But we're introducing a new type (ListOrd), where does that go?) + +Martin: because "it doesn't work for anonymous and most people will want to write it anonymous. this is the one syntax that works for both named and anonymous." + +Guillaume: do we need anonymous? "I'm not a fan" of anonymous things. In UX, there's the concept of affordance, how do you interact with a thing, like a door with a handle? If I write an implied thing, it has an effect on other parts of my program. How do I "find all references"? In my IDE, if I ask to see what the use site expands to, what does it show me? What does an error message say when it needs to refer to this thing? + +Martin: the way we produce anonymous named instances is spec'ed and is intended to produce halfway usable names, in the cases where they're needed. Martin feels very strongly it's "so much more beautiful" if you allow anonymous (and he mentioned similar feedback from one of Kotlin's designers). + +Guillaume: it's spooky action at a distance. (But I [Seth] don't understand why the presence or absence of a name is what makes it spooky or not.) + +Seth: there are names, they're just automatically generated. Guillaume: but there's no name in my source code I can ask for "Find All References" on. + +Miles: "all of my concerns are at the definition site" + +### **Querying implied instances** + +discussion between Adriaan, Martin, and Miles about the `implied [T] given (x: X) for T = e` syntax, Miles wishes it were more like function definition syntax, as mentioned above. + +what about context bounds? that's covered in the comparison-with-Scala-2 document, Miles and I asked Martin about it, he said maybe we could later decide it's unnecessary sugar, no rush + +### **Implicit conversions** + +Everyone in the room agrees that it's good to make implicit conversions a separate concept and not allow them to just be function values in implicit scope. Instead they're now scala.Conversions in implicit scope. + +Discussion about whether the additional performance cost of requiring scala.Conversion objects is worth it, and/or can it be mitigated? + +Miles finds the syntax clunky. Do we care, if this is a feature we don't expect or want to be used much? + +Adriaan suggests using SAM syntax, the example on the Implicit Conversions page would be shorter that way. But Seb points out it will increase the runtime cost... unless we can optimize it away? Unclear. (Miles wondered if there might be primitive-boxing overhead, but Seb thought not, but there is definitely allocation unless we optimize it away.) + +Guillaume: it's hard to talk about this separately from the rest of the implied/given stuff. + +Are we fine with requiring Conversion? Yes, we are. implicit def for conversions will be deprecated and go away at some point (post-3.0, iiuc). + +### **Inferrable parameters** + +We all like the concept. (The syntax questions are mixed up with the other implicits changes.) + +### **Implied instances** + +Adriaan: people are currently writing implicit val which doesn't allocate every time, but the new syntax desugars to implicit def which will allocate unless you make a separate val. + +Martin: could we say if it's a val if it doesn't take parameters...? I had decided earlier that it was better to always desugar to def and say if you want a val, make one and have the def forward to it. + +Miles really wants to see how this would play out in a real codebase before voting. Currently he could "at best abstain". Guillaume feels the same way. + +### **Implied imports** + +~~~ +import implied +~~~ + +Martin: there's a PR, not yet merged, that refines this rule considerably compared to what's on the Dotty feature page? + +It's [https://github.com/scala/scala3/pull/6041](https://github.com/scala/scala3/pull/6041) -- it has the new impl as well as the changes to the web page. + +Martin: we now have a custom error message so if something fails but changing import to import implied would fix it, the compiler will tell you. + +Miles: in e.g. a Show typeclass you might have a fallback instance (e.g. one that calls `toString). The typeclass is provided by one person, the data class is provided by another, a third person is writing the instance. This change, combined with changes to implicit priorities, makes Miles worried this pattern won't work. + +Miles: do we still need this in *addition* to the scoping rules? Martin: it wasn't motivated by that, the motivation here is different, it's as listed on the web page. + +Martin: People have big lists of imports`, it's important to call out the ones that bring in implicits, those are the ones you really need to know about when you're reading code. + +Seb is really against this, he thinks it's wishful thinking that it solves anything that isn't already solved by IDEs. + +Anyone else against? Iulian is a little iffy. + +Miles: "Bringing implicits into scope should be done *explicitly*." + +Martin: there is a new idea, neither spec'ed nor implemented yet, to simplify lookup? (I didn't catch what the idea was.) + +Martin: there's only one namespace, but names have a flag of whether they're implicit or not, determining which form of import will import them. + +Seb: we already have a way to do this in user space, which is to put implicits in an object, e.g. Implicits, but people don't do it, our recommendation hasn't been followed. You can't tell people what to do... but this proposal will successfully do that, won't it? Martin thinks it does. Seb asks, do we know whether the *users* of the libraries who *have* followed the recommendation are happier? + +Miles points out the grossness that even import cats.Implicits._ imports a bunch of irrelevant identifiers like toString and hashCode. + +Martin: "Implicits are much more dangerous than normal names." + +Seb: This solves nothing, you will *still* need to use your IDE to find out where something comes from, *always*. + +Guillaume: people just add imports until their code compiles, and then a bunch of extra implicits can easily come along for the ride, this will really cut back on that. + +Martin: part of the reason the implicits changes are more than just marketing is that we're trying to take away sharp edges, this and conversions are the two biggest sharp edges. + +Seth to Seb: it doesn't help, does it hurt? Seb: well basically migration pain. Iulian: well, and there's a thing where before you could get by with one import and now you'll often need two? + +Seb: usually implicits come in via other avenues anyway, so even if this helps, it helps in the relatively unusual cases where you're getting implicits via an explicit import. + +Guillaume: what about import all which does both? Martin: let's do the restrictive version first and then see if it turns out that import all is really common and we ought to support it after all. + +### **Toplevel definitions** + +Miles: when is a val evaluated? Martin: implementation is that it's wrapped in an enclosing object, so it's whenever anything in that object is accessed. Seb: this rule is consistent with the rest of the language. + +Iulian: separate compilation will be trickier, because you have to look at all the source files? Martin: but an outliner would tell you. Somebody: and anyway in general we can't count on people following the conventions that tell an IDE where to look. Guillaume: maybe we should come back to it. + +Guillaume: everybody keeps asking, what about main? Can I put def main somewhere that doesn't make it hard to call from java? Guillaume: well if you use scala (/dotr) to run it and not java, it could find it. + +Martin: we'll also need to consider main as part of DelayedInit, so maybe let's talk about it then. + +Guillaume: can we unify several concepts: the REPL wraps things in object, in worksheet mode also, now we're doing that in toplevel definitions too? Can we have toplevel definitions also be how the REPL and worksheets are implemented? + +Guillaume: .sc, even before Ammonite the ScalaIDE worksheet used .sc files, so the convention is at least somewhat established. So only .sc files would allow statements at the top level, and the script runnner would know about them. + +Should statements be allowed in top level files? Seth: yeah, why not, seems natural? Seb: but they'll only run if you reference something that's *next* to them, and there's no way to explicitly run them. Miles: isn't object already weird in exactly the same way? + +If I have + +~~~ +package p + +val a = (1, 2) + +def b = a._2 +~~~ + +in a._2, is it this.a._2, and then this is a value? + +Iulian: so if I have top-level object, is it a nested object? But then if you remove all the top-level definitions, it's not a nested object anymore? It might especially matter if you have an implicit object, Martin: except implicit objectcan't stand on its own, because for package objects, the compiler can look for all the $package files only. + +What if I have a type Foo and an object Foo, the former will be lifted into a wrapper object and the latter won't...? + +Seth: is this merely implemented as involving a wrapper object, or is that actually the spec? Martin: it's the spec. + +Seb: the web page says "the wrapping is transparent", but Seb thinks we should add "except for binary compatibility", because of e.g. the object vs implicit object example. + +Miles: opaque type can have a companion, why doesn't or shouldn't ordinary type have a companion? Martin, Guillaume: we haven't tried that, maybe we should? (This sparked some technical discussion about dealiasing in typer.) + +Miles: what if I want to have two source files that add top level definitions to the same package, e.g. one of the source files is Scala version independent and one is independent, but they both want to add top level things. Guillaume: "Don't do that. You'll get a redefinition error." Seth: it'll be enough to just rename one of the source files? Guillaume: yes, and the compiler will tell you that. + +Nobody's against this *in some form*, details. + +### **Runtime reflection** + +Guillaume is supporting some form of runtime reflection (other than Java runtime reflection; analogous to scala.reflect) explicitly a non-goal of Scala 3? For 3.0, or for all 3.x versions? + +Can we finally deprecate Manifest in 2.14? Because it's going to go away in 3. It's been marked as TODO to deprecate since 2.10, Guillaume observes. + +So Dotty does have something like TypeTag internally (core.Type), but we do restrict it to be compile-time-only? + +"Runtime reflection" should be on the list of dropped features (is it already?). + +Miles: let's offer deriving Typeable instead (like Shapeless's Typeable). + +Adriaan: no we have to offer something like TypeTag? But what? And on what calendar? Unclear answer. Oh, never mind, he ended with "well, okay" (maybe he thought ClassTag was going away). + +To be clear, ClassTag isn't going anywhere. + +Martin: let's wait to SIP the removal of runtime reflection until the metaprogramming story is clear. (Perhaps it will end up offering something in this area.) + +### **Metaprograming** + +What's the metaprogramming status? + +Martin: quote and splice are stable, but don't support pattern matching yet. TASTY reflection is not complete yet and is still undergoing revisions based on use cases that are being tried. + +No one has done any meaningful whitebox macros yet in the new system, but the door is now open. (<-- not sure if I should include this in the notes without understanding in what context we want to allow whitebox macros?) This only got merged "last week". The relevant PR is [https://github.com/scala/scala3/pull/5846](https://github.com/scala/scala3/pull/5846) "The main motivation for moving staging to typer is to support whitebox macros" but it's still very early days, no one has tried to actually use this. + +# **Kind polymorphism** + +Martin: the page doesn't have motivation. But we do have a strong motivation now, which is staging: + +~~~ +type T + +'T +~~~ + +What happens at runtime? It becomes `'the[quoted.Type[T]]`, that's how lifting types into quoted contexts work. + +But what if you have `F[_]` instead? It didn't work before, but with kind polymorphism it does. + +Miles: I tried for a long time to encode kind polymorphism in a way that would help typeclass derivation. The truth was, I thought AnyKind would give us all sorts of capabilities, but it turned out not. It turns out you need much more, you need the ability to abstract over method signatures. + +But "where it's useful it's really useful". Seth: is it okay to add the limited version in the meantime? Miles: sure. + +Seth: will it still be experimental in 3.0? Martin: if it's a part of metaprogramming, it can't be experimental. (So the web page should be updated at some point.) + +Guillaume: it really needs examples. (Miles: Typelevel can help with that.) + +### **Enums** + +We discussed this last time (in November). The main area of change we decided on then is to support Java style enums with extends java.lang.Enum or whatever it is. The work on this hasn't been done yet. + +Martin: we need to represent this in a way that doesn't pull in the collections API, we'll need a lightweight interface, probably using an immutable array which erases to Array. + +Guillaume: the dividing line of what can or can't be a Java enum is fuzzy, and perhaps changing...? We may have to do some experimentation with what javac recogniaes, what IntelliJ and Eclipse recognize, and so forth. + +The "perhaps changing" part is JEP 301 which hasn't been updated recently, is it still active? Seb: it's fine if we need to change further later if those changes happen. + +### **ADTs** + +[https://dotty.epfl.ch/docs/reference/enums/adts.html](https://dotty.epfl.ch/docs/reference/enums/adts.html) + +Guillaume & Martin: this went through many iterations, there were hundreds of comments, we're pretty sure this is the design. + +Adriaan is skeptical this matters so much, it doesn't let you do anything new you couldn't do before. Several other committee members think it's important, both because Java interop on the enum side, *and* to make plain ADTs more convenient. + +Questions about the magic automatic extends clauses, how does the compiler know, in the Option example, that Someis [T] and None is [Nothing]? Adriaan: okay, as long as the rules are clear...? + +"Generally, all covariant type parameters of the enum class are minimized in a compiler-generated extends clause whereas all contravariant type parameters are maximized", says the doc + +There was some discussion of the details of the rules for type parameters -- this then erupted into a full-on debate. e.g. isn't it weird that if you add an extends clause, suddenly T isn't in scope any more? see [https://github.com/scala/scala3/pull/6095](https://github.com/scala/scala3/pull/6095) + +conclusion: Martin: I'll try to update the rules to reflect the behavior of the compiler. + +### **Volatile lazy vals** + +In current implementation, lazy vals only have synchronization if you explicitly declare it as volatile. + +But this is a breaking change. + +Seth: can we get there gradually, by migration stages? + +Guillaume: I don't know if it's worth it. + +The concern isn't only accidental deadlocks, it's also performance, you don't want to pay for locking if you don't need it. + +Seth: isn't it just strange that a core language construct includes this locking, thread-safety baggage by default? + +Martin: like var, it's unsafe unless you declare it volatile. + +Iulian argues that it makes sense because it's a val. + +Guillaume had an example of when this bit them in practice when copying code from scalac. + +Seth: can we agree this shouldn't happen unless it's done in migration stages? And that it isn't required for 3.0, it's not tied to anything else? + +Guillaume: even supposing we change the default, do we still want to offer the non-volatile version? + +Seth: I find that quite appealing, yes. I always see people advising beginners about lazy vals, look out for locking, look out for performance, maybe don't use it. + +Iulian: no, let's not have this knob, let's do one thing and do it right. "The unsafe version is super easy to code yourself if you need it." + +Martin: but it matters because lazy val is stable, if you code it yourself it'll be a def and then it's not stable. (But, not clear how big a deal that is.) + +If changing anything in this area, check on the status of local lazy vals, there is a separate implementation. + +### Typeclass Derivation + +Can we move shapeless into the stdlib given enough compiler support? + +Fix following restrictions in shapeless: + +* Implicits to encode type-level folds +* Lots of boilerplate for users (e.g. in writing these folds) +* Ad-hoc handling of type constructors of various shapes +* Distinction between Generic and LabelGeneric (can be unified thanks to match types) + +Needs polymorphic functions + +What does the compiler need to generate in the companion object? + +* Which companion object? Just the top type or each subclass (too much codegen?) +* Type members for T, Repr, Name, Labels + * They could also be baked in: `type ReprOf[T]` = + * Don’t use `Either` for Repr (would pull in stdlib) +* def select for coproduct that maps each subclass to an index into "instances" + +Differences with Martin’s proposal + +* Names are different, but they work the same way: + * case = product (types for nested entities) + * Cases = coproduct + +Criteria + +* Generate least amount of code +* Can erasedApply be unified with companion-object’s implementation of FunctionN’s apply (maybe not, since users can implement it themselves). Do we even need it? (just saves one eta-expansion) + +Product element names duplicates? Mostly run-time facility. + +Can we derive the case class methods? + +### Specialization + +Need something to deal with boxing. What’s the subset that 3.0 should support for biggest bang for buck? FunctionN / TupleN / all final classes? + +An inline method can override a concrete method. Would require changes to design of the collections. + +Hard parts of specialization: + +* fields of non-final classes +* Traits (e.g. superaccessors) +* Overriding specialized methods + +If you can limit it to final classes. + +### Multi-versal equality + +Needs more thinking & community feedback. Can we come up with rules for a single-param variant? diff --git a/_sips/minutes/2019-06-08-sip-minutes.md b/_sips/minutes/2019-06-08-sip-minutes.md new file mode 100644 index 0000000000..247472ece1 --- /dev/null +++ b/_sips/minutes/2019-06-08-sip-minutes.md @@ -0,0 +1,293 @@ +--- +layout: sips +title: SIP Meeting Minutes - June 08 2019 + +partof: minutes +--- + +# Minutes + +The agenda distributed to the attendees is [here](https://docs.google.com/document/d/14Cby0d5t2CFnM76sEs9B6cI8rYxe218cyNjOPZ3kD1E/edit). + +## Proceedings + +### Implicit conversions + +[https://dotty.epfl.ch/docs/reference/contextual/conversions.html](https://dotty.epfl.ch/docs/reference/contextual/conversions.html) + +Mostly an uncontroversial change. + +Someone: Do we want it as an abstract class, not a trait? +Someone: Yes, because we actively want to discourage it being used as a mixin. + +Miles: There are lots of function types, could it be a refinement of Function1? +Someone: No, because it's not structural. + +Seth: But it still needs a contributors.scala-lang.org thread for discussion outside by itself, +apart from the other implicits changes + +### Auto-tupling + +Implemented but not merged: [https://github.com/scala/scala3/pull/4311](https://github.com/scala/scala3/pull/4311) + +The problem is when using infix (e.g. an operator method) there's confusion between a 1-argument tuple2 method +and a 2-argument method, of which there are a few in the standard library. + +Someone asks: should we drop auto-tuple completely? (unanswered, I believe) + +One example is += on Map, which was deprecated in 2.13. + +We could deprecate the definition of such methods in 2.14. + +Adriaan: why, outside of overloads, can't auto-tupling kick in for 1-argument tuple2 methods? +Decision: let's try that + +### Exports + +[https://dotty.epfl.ch/docs/reference/other-new-features/export.html](https://dotty.epfl.ch/docs/reference/other-new-features/export.html) + +The motivation is the same as package objects, and is by-and-large replaced by top-level definitions. + +What's left over is: how do we compose namespaces? Export is the answer there. + +(It's also one of the longest standing feature requests of Scala.) + +Seb: is wildcard exporting a good idea? Maybe just name them (without full definitions). + +Iulian: Does export fix the package object inheritance problem? Yes, because export can be top-level. + +Seth: What's the impact on Scaladoc? Shared concerns with what the UX should be, maybe just forward references +instead of copying the Scaladoc. + +Miles: Does this fix Daniel Spiewak's Monad/Traverse issue? +The issue is you want to implement the intersection by exporting monad instance methods and traverse instance methods +but sometimes you want to be selective on exporting ("every method that isn't (something something)") +for now you just name them + +Martin(?): Export is entirely implemented in namer, it's a simple implementation, no types. + +Josh: What about incremental compilation impact? +Answer: We'll treat it like a variant of inheritance. + +Seth: Can this wait for 3.1 or later? + * Martin argument 1: deprecate package object replacement + * Martin argument 2: simpler structure, Scala 3 books should promote this instead of package objects + +Seb: back to no-wildcard / named exports only: we can loosen it later to allow for wildcards + +Miles/Seth: can we make the export relative to the type? "Export everything in monadInstance from Traverse"? + * Martin: it's meant to mirror import + * Seb: but we have import implied for types in the talks... + * Martin: it's not the same thing + * Seb: but it is, kind of... + * (someone): just ascribe the type "val monadInstance: Functor" and export from that + +Adriaan: (using the Printer/Scanner example) method in scanner won't call method in printer + * Martin: yeah it's not inheritance + * Adriaan: right, we should make that clear + +Seb: Javascript supports wildcard exports + +Adriaan: we need to give good error messages in export conflicts + +Adriaan: Also let's not forget the big Scaladoc impact, can't copy because of the type parameter and other different names + * Martin: we should be able to use Scaladoc's variable redefining system + * Adriaan: Scaladoc is very important to users, so let's not forget this issue + +### Polymorphic function types + +Merged but not documented: [https://github.com/scala/scala3/pull/4672](https://github.com/scala/scala3/pull/4672) + +Presented by Guillaume. + +First type lambda syntax was `type A = [T] => List[T]` +But we need term-level syntax and `=>` is taken by Function1 +So switched type lambda to `type A = [T] =>> List[T]` +So the identity function can be `def id: [T] => T => T` + +Miles(?): and now we have lots of function type (dependent functions, implicit functions, ...) +Miles: we should definitely lose the FunctionN types, if possible +Guillaume: should we eta-expand to polymorphic code? does it break existing code? + * Martin: yeah it does +Miles: (summarising) it's lovely, we should have it (it's currently entirely experimental) +Martin: let's discuss if can we do it later + * Miles: I need it for typeclass derivation, so no + * Martin: ... Right, that clears that up + +Seb: there's confusion in arrows between type parameters and term parameters + * (lots of chat) + * Adriaan: we'll need to decide the syntax later + * Adriaan: maybe instead of `[T] =>> List[T]` use `List[__]` + +No-one is expressly against including it, but details will need to be finalised later. + +### @infix and @alpha + +Presented by Sébastien. + +The goal is to ensure all operators always have a name, for documentation purposes, IDE hover display, +googleable. + +Also @alpha defines the JVM name of the method. +But it's a design decision to only have 1 way to call the method. + +Nicolas: why not the other way round, have an `@op` annotation with the infix operator name? + Seb(?): Because you can't call the alpha numeric name (e.g. `.append`) + +Seth: Also having two methods (`+=` and `append`) interferes with overriding: you want one to alias the other, +but you want to be able to override to refine the result type of both methods. + +Seb: And then there's @infix, to be prescriptive about methods that should only be used infix +Seb: it's a controversial issue +Seb: the plan is for now you can choose, then you'll get a warning, then it will error (forcing you to infix) + +Seth: the hardcore infix fans is small + +Iulian: I don't like the forcing from @infix either + +Martin: There are too many choices with infix and non-infix usage + +Adriaan: should this be in 2.14? + * No definitive answer, there's no reason not to, outside of the already full roadmap plans + +Also mentioned are the non-operator methods that are really designed for infix usage: `eq`, `is`(?), +Range's `to` and `be`. + +Martin: this is already implemented, and forced with `-strict` + +### Creator Applications + +Presented by Martin. + +Iulian: can you do both? `new Foo(x, y)` and `Foo(x, y)` + * Martin: yes + * Iulian: but that's inconsistent with the previous discussion about infix/non-infix + * Martin: people will converge to not writing "new" (because it's shorter) + * Iulian: so kill new + * Martin: you need new for edge-cases + * Seth: .new instead of prefix new? + * Martin: also you need new for anonymous classes + * Martin: it's important in chisel (spelling? It's some framework) + +Martin: people define classes as case classes for it, so let's give it to classes + +Josh: dart has this with builders and constructors, and it works out nicely +Josh: but dart has it so builders can't call builders and it's confusing so let's keep new + +Adriaan: we should limit use of "new", lint thing or other compiler help +Seth: e.g. under -strict it warns if using unnecessary new (for some definition unnecessary) +Adriaan: figure out where new is absolutely needed and restrict to that +Adriaan: continue Scala 3's mantra of being more opinionated + +### Nullability + +If we get nullability over the summer, then we'll try to land it in Scala 3 + +### Inline + +[https://dotty.epfl.ch/docs/reference/metaprogramming/inline.html](https://dotty.epfl.ch/docs/reference/metaprogramming/inline.html) + +Presented by Nicolas + +`inline` is guaranteed inline (unlike `final`) + +Miles shared (unclear) concerns about limitations with literal types (42.type) + +Miles: could we have a "fuel" (sp?) integer? That is, an integer that goes down to 0. + * (many): no, it's hard to prove these things in the compiler (and other implementation details) + +Martin: Or could we just disallow recursion? + * Nicolas: yeah, we could, and tell users to use staging for that (Olivier approves :D) + +Martin: Hmm, we might not need inline on parameters + * Nicolas: I agree, just can just use staging instead + +### Staging + +[https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html](https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html) + +Presented by Olivier + +Miles: the example is too basic, no recursion: can we do typeclass derivation with this? (need recursion) + +Adriaan: how staging works must be clear to the SIP committee and to users, even if it targets advanced users +Adriaan has concerns about sneaking whitebox macro style problems back into the compiler +Adriaan/Seb: inline is simpler + * Olivier: I disagree, you can't understand a large inline method, because it's entangled with the optimizer + * Martin: with staging you can println half-way into staging + * Martin: the ideal is that inline desugars to staging + * Nicolas: except staging requires separate compilation (because we have no interpreter), inline doesn't + * (Miles: or we can make an interpreter for a subset of the language) + * Nicolas also has some ingenious half-way between inline and staging, that he mentioned (too) quickly + +### More general meta-programming talks + +Nicolas/Olivier present 3 "tiers" of meta-programming: inline, staging, dotty reflect + +At the end it becomes clear that these aren't desugarings from one to another (e.g. staging doesn't desugar +to dotty reflect, it's its own thing, idem for inline to staging). + +But even at the most powerful, dotty reflect, you cannot typecheck (or untypecheck), you only have typed trees. + +No precise hanging questions, follow-up work or decisions, except: + +Miles: how long to finish everything? + Nicholas: hopefully by the end of the summer + +### Typeclass Derivation + +[https://dotty.epfl.ch/docs/reference/contextual/derivation.html](https://dotty.epfl.ch/docs/reference/contextual/derivation.html) + +Presented by Miles. + +For typeclasses that are monoidal (e.g. Monoid, Eq/Eqv, Show) just pass the summoned TC instances to the erased +infrastructure. + +There is a "derived" magic method name on TC companions that matches the "derives" keyword that you can put at +the end of your case class. + +Seth: no handling of higher-kinded types? + * Miles: no need at the compiler/scala.deriving level, just a small kernel, and a veneer in Shapeless 3 + * Miles: AnyKind is not enough to do the necessary kind-polymorphism + +Martin: But we said we weren't adding anything to the standard library in 3.0 + * (Someone): We can still add it to the 2.14 and 3.0 standard library + +### Erased Terms + +[https://dotty.epfl.ch/docs/reference/experimental/erased-defs.html](https://dotty.epfl.ch/docs/reference/experimental/erased-defs.html) + +Olivier: Are they necessary? + * Yes's and No's + * Seb: in Scala.js I could use them + * Seth: should we ask the community? + * Miles: no, because you'll always find someone that says yes + +Decision: Find use cases and test performance + +Seth: Defer to 3.1+? + +(Someone): Yes, it doesn't need to be in 3.0 + +(Someone): Maybe it's superseded by @compileTimeOnly, that's already in 2.13? + +(A few): Should we delete the code or put it under a flag? + +Guillaume: If we don't delete it it'll be in TASTY forever + +Decision: delete the code, strive to make @compileTimeOnly its replacement + +### Runtime reflection + +Drop it, and push the problem to the community to experiment solutions. + +### Enum + +Update: if an enum extends java.lang.Enum, it's a Java enum! +Without extending it has a subset of java.lang.Enum's API. + +### -strict vs -relaxed vs -Xsource + +You use `-Xsource V` and `-migration` to help get to version V +Martin: I'd like a way to do it file-by-file + * (Many): having different files use different versions of Scala sounds very confusing diff --git a/_sips/minutes/2019-11-27-sip-minutes.md b/_sips/minutes/2019-11-27-sip-minutes.md new file mode 100644 index 0000000000..7fb8fec083 --- /dev/null +++ b/_sips/minutes/2019-11-27-sip-minutes.md @@ -0,0 +1,153 @@ +--- +layout: sips +title: SIP Meeting Minutes - November 27 2019 + +partof: minutes +--- + +# Minutes + +The following agenda was distributed to attendees: + +1. Re-visiting what SIP Committee's role is given the Scala 2 to 3 transition +2. Dotty feature freeze is coming soon - what does that mean? +3. Review the "Curried varargs" SIP +4. Review the "Name-based XML literals" SIP +5. The priority of Dotty features the SIP Committee has to discuss + +## Date and Location + +The meeting took place on the 27th November 2019 at 17:00 CET via Zoom at EPFL in Lausanne, Switzerland, as well as other locations. + +The meeting was broadcast and recorded on the Scala Process's YouTube channel, but due to technical difficulties +that broadcast had to be restarted half-way through and therefore there are two videos: + +* part 1 (16:56): +* part 2 (06:43): + +Minutes were taken by Dale Wijnand. + +## Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Process Lead +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center +* Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Miles Sabin ([@milessabin](https://github.com/milessabin)), Independent +* Lukas Rytz ([@lrytz](https://twitter.com/lrytz)), visiting from Lightbend +* Dale Wijnand ([@dwijnand](https://twitter.com/dwijnand)), secretary + +## Not present + +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), Independent + +## Proceedings + +### Re-visiting what SIP Committee's role is given the Scala 2 to 3 transition + +* What happens to the current SIPs? +* What is the timeline for them? +* Who can make new proposals? +* Which changes to the process were made in November 2018? +* And which changes should be made going forward? + +Darja presented the topic. The background is that in November 2018 the SIP Committee accepted the "Dotty team +proposal of changes", which wasn't like the regular SIP proposals but is more like a large number of proposals +for Scala 3. Those individual proposals still need to be individually reviewed, but doing so will take time. + +During that time many pre-existing SIPs didn't progress in any way, some remained "open" when they should've +been closed a long time ago and, more generally, the status of them and the Dotty features SIPs wasn't clear or +well tracked. + +Therefore the SIP Committee has decided to: + +1. Make a commitment to update the state of all SIPs by March 2020; +2. Change the process to introduce the concept of a "SIP Champion", which is a member of the SIP Committee that + a contributor finds to progress a Pre-SIP idea into a SIP and to champion the SIP through the process + +### Dotty feature freeze is coming soon - what does that mean? + +Guillaume presented. + +A month ago a thread was created on the [Contributors forum announcing that the next Dotty release][freeze] will +initiate a feature freeze. What that means is that new things won't be added, instead existing changes will +be refined. That doesn't mean that new SIPs can't be proposed, but it does mean that such SIPs should adjust +their expectations that its very unlikely they'll be able to target Scala 3.0 and would have to wait for some +future 3.x release. + +[freeze]: https://contributors.scala-lang.org/t/preparing-for-feature-freeze/3780 + +### Discuss the priority of Dotty features the SIP Committee has to discuss + +Darja briefly mentioned this task the Committee has, but the discussion itself deferred to expedite the later +topics. + +In order to discuss and make decisions on the features coming in Scala 3, the Committee has been looking at how +to prioritise such discussions. Sebastien has started exploring the timing impacts of each change (related to +how they impact rewriting books/MOOCs, impact source and TASTy compatibility) and experimenting with different +logistical proposals. + +This is still pending, but in the December SIP meeting the Committee will have features it's ready to discuss +and vote upon. + +### Review the "Curried varargs" SIP + +Link: + +Sebastien presented. + +The proposal highlighted 2 issues with the current implementation of varargs: + +1. Arguments LUB together, such as an `Int`, a `String`, and a user's `Foo` will LUB to `Any`, this means that + one cannot make use of implicit lookup to summon typeclass instances for the specific types of the arguments +2. The current varargs use `Seq` which is an extra allocation that may be costly + +The proposal is to add a builder-like interface (perhaps like a typeclass?) that avoid the type widening and the +intermediate `Seq` by building instead the desired data structure. + +Martin believes that it should be possible to implement such a proposal with Dotty's meta-programming features, +specifically inline methods. This would avoid having to "burn it into the language", particularly avoid adding +to the already complex aspects of parameter application. + +Guillaume adds that that area also includes method overloading that is very complicated and already requires +attention. He also adds that it might be that use cases that call for this proposals should look at Dotty's +union types, as he thinks that some of them might be satisfied by having a varargs of union types. + +In response to the "but with macros it will be slow" pushback, Guillaume invites users to check the performance +of the Dotty-based implementation, and/or the union type-based solution. Additionally he and Sebastien say how +making it part of the language (instead of just where the meta-programming solution is used) it would probably +make the whole compiler slower for everyone. + +### Review the "Name-based XML literals" SIP + +Link: + +Sebastien presented. + +The proposal is for a way to extend XML literals, perhaps allowing alternative implementation with a somewhat +similar API. In general there is a resistence to keeping XML literals in the language at all, though the +front-end community has exhibited support for XML literals as it's a convenience that Scala.js brings. + +The feedback from the Committee is (similarly to the previous SIP) to attempt to implement it using Dotty's +meta-programming facilities, so a meta-programming backed string interpolator. + +Guillaume mentions that there is an interpolator at , which +implements all of the XML literals except for pattern matching (which just needs attention) and invites the SIP +authors to adapt that to the behaviour described in their SIP. + +### Update on the "Revised implicits" SIP + +Guillaume gave a quick update: a new thread was created on the Contributors forum to discuss how Scala's +implicits are being revised in Scala 3: + +Because the discussion has returned to debating the naming change, he intends to split the thread so that +also-important discussions around the semantics changes aren't drowned out. + +## Next + +The next meeting will be December 18th at 5 PM CET, but also the Committee intends to have another retreat in +March 2020. diff --git a/_sips/minutes/2019-12-18-sip-minutes.md b/_sips/minutes/2019-12-18-sip-minutes.md new file mode 100644 index 0000000000..f3ea7d1a23 --- /dev/null +++ b/_sips/minutes/2019-12-18-sip-minutes.md @@ -0,0 +1,290 @@ +--- +layout: sips +title: SIP Meeting Minutes - December 18 2019 + +partof: minutes +--- + +# Minutes + +The following agenda was distributed to attendees: + +Review the following SIPs: + +1. Open classes (aka "sealed classes by default") - Seb +2. Explicit Nulls - Seb +3. Main functions - needs a champion + +## Date and Location + +The meeting took place on the 18th December 2019 at 17:00 CET via Zoom at EPFL in Lausanne, Switzerland, as well as other locations. + +The meeting was broadcast and recorded on the Scala Process's YouTube channel: +[SIP meeting December 2019](https://www.youtube.com/watch?v=ZUHmo1MXhRA) [58:37]. + +Minutes were taken by Dale Wijnand. + +## Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Process Lead +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center +* Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Lukas Rytz ([@lrytz](https://twitter.com/lrytz)), visiting from Lightbend +* Dale Wijnand ([@dwijnand](https://twitter.com/dwijnand)), secretary + +## Not present + +* Miles Sabin ([@milessabin](https://github.com/milessabin)), Independent +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), Independent + +## Proceedings + +### Organisational changes + +Darja gave an update on some recently agreed upon changes to help streamline the SIP process for Scala 3. Each +member of the committee will "own" a certain number of features, which they will either champion to the +committee and/or which they will spend time investigating and trying to poke holes into. The goals are: + +1. make sure that a good number of people exercise the feature, try to break it, refine it and raise any red + flags about it; +2. provide a detailed review of the feature, especially for the contentious ones; and, finally +3. straw poll will be taken on each feature, as a smoke test for the real vote + +Note that the feature review will still involve the community; it will not be done in a vacuum. + +### Quick update on the "given" redesign + +Sébastien gave a quick, side-line, update on the "given" redesign thread +([link](https://contributors.scala-lang.org/t/updated-proposal-revisiting-implicits/3821)) stating how the +discussion is still ongoing and how some changes were done on it recently (particularly around conditional given +instances), so invites any interested parties to have a look at it. + +### Review the "Open classes" / "sealed classes by default" SIP + +Thread: + +Sébastien championing and presenting. + +The gist of the proposal is we currently have 3 kinds of classes: +* sealed classes, which can only be extended in the same file; +* final classes, cannot be extended at all; and +* non-final, non-sealed classes, which can be extended from anywhere + +This situation is typically problematic for library authors who can accidentally leave a class open, which means +that those classes can't be evolved in any way without breaking someone's code somewhere. So the idea is to +introduce a 4th option: explicitly open classes. This would be a strong signal to say "I have intended this +class to be open and extended, and I have a contract for extension". And, therefore, not having any modifier +would be taken to mean "I haven't done all the effort to make sure it makes sense to extend this class, but I'm +not preventing anyone from doing it". Then the compiler would emit a warning when you extend the class and you +can disable the warning with a language import/flag. + +The feedback from the contributors thread could be summarised as comprising of 2 categories of people: + +* people that like the feature very much, which Sébastien thinks are all library authors; +* people who are concerned that this is removing their ability to patch up libraries by extending and + overrinding some methods, which seem to be application developers + +Sébastien's response to the feedback is that you can still patch up libraries, as it just emits a warning, which +you can also suppress, and therefore he summises that it's overwhelmingly in favour. + +Iulian shared that he believes there is a lot more application code than library code and so application +developers' concerns should be weighed a bit more than libraries authors, particularly given library authors are +more advanced language users, and so they can just use final and sealed when needed. He also wonders: if +everyone's going to add this flag, is that a good default? But it's good that there's a way to keep exisiting +behaviour, like the precedent in Kotlin. As a second remark, he sees enums/ADTs as being a large percentage of +the target of this problem, as in sealed and final is used for ADTs, so he wonders maybe the feature should be +just for those, and not for the other classes. + +Martin said he's not sure as he thinks that most people will continue to use normal classes and that there are a +lot of application areas where people use normal classes. His impression is that a good compromise has been +found with the language import as library writers are protected, it clearly communicates what could be +overriden and what couldn't, and users who still want to override can. Today either a library writer has to +accept that people could override the class, so any change could break, or they have to be paranoid and make +everything final and some possibly good use cases, such as mocking, can't be done. So the proposal make the +default that someone didn't write an inheritance contract, which is 95% of the time. + +Sébastien goes further on the topic of inheritance contracts, explaining how they are much more difficult to +write and think about than usage contracts. In a usage contract you have to define what happens when you call a +method in every public method; while in an inheritence contract you have to define not only that but also very +precisely describe, for every public or protected method, when will those be called and what it means to +override them... in the flow of internal things that can happen inside the class. They are so many moving +parts, and it's really crazy. So typically people don't think about inheritence contract at all. + +Dale mentions he has a quick question and a comment. The question is whether classes with no modifiers are +considered by the exhaustivity checker as sealed. The comment is: as a library author, if I don't have final, +isn't adding final a breaking change? Because he sees it as a breaking change for any of his users that use the +language flag, so it's just as breaking as it is today. + +Sébastien first answers the question stating the exhaustivity checker can't change: no modifier classes aren't +considered sealed. With regards to making something final is breaking, he agrees, but suggests you could +explicitly make it sealed, which is source-breaking but not binary-breaking. The point of the feature is the +signal to the user that extending a non-open class is "exploiting" something that was not intended, exposing +themselves to a risk. + +Guillaume has 2 comments: + +1. The proposal is that no modifier classes are extendable within the same file as the class (with no warnings), + much like sealed classes are only extendable within the same file. This makes sense for sealed, for + implementation reasons, but the examples in the proposal are more project/package level concerns, about a + user in another codebase extending, so it's not really a file-level concern. It would be nicer if this were + at project level rather than file level (but harder to implement). + +2. He also has a concern over the introduction/usage of language flags/imports, as typically people see a + warning, silence it, and never see the warning ever again. You end up with language dialects. So one idea + he had was that when you extend you have to do something more explicit, like a "force extends" - some kind + of keyword or syntax - at the extension point. Then you wouldn't create a new language dialect, and wouldn't + need to introduce a new import/flag. + +* Seb: that wouldn't work for mocking library, where you would typically just enable it for the +compilation of test sources. +* Gui: if mocking libraries work with macros, then the macro can just write the right tree, with the force extends +* Seb: yeah, maybe + +Seth comments that he find the whole thing so questionable. To him it seems like an area where everything was +fine, and there wasn't a big pain point. Sébastien says that this is a big pain point for him, along with +nulls, and that every time he writes a library this trips him up, every single time. Martin mentions how there +are public code guides that state "you must put final on every case class" which is bad as it promotes a very +verbose and boilerplate-y style, due to the lack of this feature. Seth counter-responds that he would then like +to see this explore how the feature can be restricted to just case classes, as he's seen people often talk about +the fact that case classes aren't final, but not so much about normal classes. + +Sébastien wraps up and, together with Guillaume and Seth, decides that, given the proposal has evolved throughout +the original contributors thread, to open a new contributors thread, stating the current status and some of the +alternatives discussed in this SIP meeting, formally opening a round of public review. + +New thread: [SIP public review: Open classes](https://contributors.scala-lang.org/t/sip-public-review-open-classes/3888) + +### Review the "Explicit nulls" SIP + +Thread: <{{ site.scala3ref }}/experimental/explicit-nulls.html> + +Sébastien championing and presenting. + +The feature was just merged into Dotty (at the time of the meeting). + +Sébastien explains how null is an issue, given every reference type is nullable. The Scala type system doesn't +protect you from NullPointerException's coming up anywhere. So the goal of this proposal is to fix this. The +basic idea is that a reference type like String is not nullable, so you can't assign null to something that is +of type String. So how would one write a nullable type? To Sébastien the obvious answer is using a union type: +String | Null. + +That's it... basically. Then there's the tail of consequences from that. + +One big consequence is Java interop, obviously. Because if you want to talk to a Java library any reference +type might be a null and the library might even use nulls as signals. But at the same time many Java types are +not, in fact, nullable, in practice, in the API. So there is a tricky balance: do you translate every reference +type to String | Null and deal with it with ifs and pattern matching or some flatMap-y API/syntax, every time, +evne when you know it's not nullable? Or you can just say if it comes from Java then you just accept it might +be a null, but then you don't have any checks any more in practice. So here the proposal - and it's one of the +more delicate points - says that things that come from Java are a bit special. A String that comes from Java is +neither String nor String | Null, it's String | UncheckedNull. That type has some special properties, like you +can dot-select on it, for example. It's something in the middle. + +Guillaume asks: how in the middle? What can you _not_ do? + +Seb: when it becomes something that is just String it will eagerly fail there. So if your Scala API declares +something is a String, and you use a Java API that returns String | UncheckedNull, it will throw in the body of +your method. It can't "give the null away". + +The other big thing in the proposal is that there's a lot of code that writes "if x == null do something else do +something with x" that assumes x is not null. Here the idea is to introduce some form of flow typing, that can +prove that in the else branch x is a String. + +Seth mentions how he's really enthusiastic about this proposal, with the exception of the flow typing. It seems +odd to him to introduce that in such a limited way. To him it seems like something that either the language +should go all in on or not do at all. Sébastien responds that that's a valid concern, sharing he's not entirely +convinced himself. He mentions how the question is how inconvenient would it be if we didn't have the flow +typing for all the legacy code that has that kind of code. Martin shares that every other language that +introduced explicit nulls has some form of flow typing - he doesn't think there are any exception - you +basically need to do that. + +Guillaume asks: flow typing or the elvis operator? + +Iulian mentions how he wanted to talk about the elvis operator. He asks: what is the recommended way to call +methods on nullable types? What is the equivalent of the elvis operator? + +Seb: you don't call methods on nullable types, you have to first test if it's null. The problem with the elvis +operator is that it looks like flatMap but it's not. It's unboxed, so it confuses the equivalent of None and +Some(None). That seems theoretical but it's not - it boils down to practical things. For instance, Map#get +returns null - if the Map's value type is itself nullable you can't distinguish if the key is set in the Map to +null, or if the Map is signalling it doesn't contain the key. You really need to just write the if/elses or +flatMap. Sébastien doesn't think this will happen very often in typical Scala code. Iulian says he thinks this +feature is very useful as it adds null safety, but he would guess that users would want the elvis operator. + +Sébastien, responding to YouTube chat comments, shares that Option.apply is changed to take A | Null and return +Option[A], so it continues to be the direct way to deal with nulls. + +Sébastien is reminded that he hasn't yet talked about `.nn`. `nn` is an extension method added to `A | Null` +that, when invoked, is an assertiong that a value is not null (thus "nn") and will throw a NPE if it is and +return `A` if it's not. + +Sébastien shares he doesn't like that `.nn` is available everywhere, without even an import. Guillaume says +it's a bit like `.get` on Option. Martin says he would defend .get and .nn, say that users should not use them +if they don't like them. Martin also says that maybe after the Scala 3 transition we could deprecate it and/or +move it, but for now he thinks it's good to have universally available. + +* Seth asks Martin: is null only for performance-critical code, or is that just one of the use cases? +* Martin: Java interop or performance-critical code +* Seth: Doesn't the UncheckedNull cover the Java case? +* Martin: well, no, you might want to use A | Null in some code adjacent to some Java interop code, which wouldn't +be terribly low level code. So in that case you might continue to use null. +* Seb: an easier way to answer is that UncheckedNull is only to select a member. You cannot assign a String | +UncheckedNull to a String. If you want to store the value in a String, it will be checked then, at runtime. + +Iulian comments: UncheckedNull seems to exist to allow unsafe selection, I think the elvis operator is slightly +better for that. Martin shares how Kotlin went through all that. They initially had the elvis operator but it +meant you had to write `System.out?.print` and no one was prepared to do that. So they relented and come up +with something similar called "platform types" which is their analog of our UncheckedNull. Iulian says that he +still finds that UncheckedNull is a very easy way to turn a blind eye on nulls and fears its existing will +continue to allow lots of NPEs to be generated. He thinks it's very easy not to realise that these are +unchecked nulls, using a Java method, and you don't get any warnings. Martin says how no, as soon as you +typecheck it in Scala as String, then that means String, not String | UncheckedNull, so that's theoretically +your firewall. + +Guillaume also shares how with the proposal also come a bunch of annotations for the Java standard library that +are supposed to know which methods take or return null, so for thins that return null Scala could make it type +as `A | Null` instead of `A | UncheckedNull`. + +Sébastien shares that some users don't like the magic of UncheckedNull, so maybe that could be behind a language +flag, though there are language dialect concerns with language flags. + +Seth then asks about the status of the -Y flag associated with this feature: is the intention of the feature to +be on by default? Sébastien says: hopefully, if it all works out. Martin says maybe it could be turned on by +default by Scala 3.1. Guillaume says he's confused what it means for some libraries to enable the flag and some not to. +Martin summarises that, basically, we need to get to the point where we have it on by default. + +Sébastien, looking at the YouTube chat, shares Eugene Yokota's question: "what about `var x: String = _`?" +Sébastien shares how it's "evil" and how it should've been removed a long time ago. Martin counters that it's +quite the opposite: it should not be taken to mean that it's assigning null, it should be taken to mean that the +variable is unassigned and the initialisation checker should check that before each usage. That's better than +assigning null. + +Dale states how it seems there aren't any good ergonomics for using a value of type `A | Null`. Sébastien says +that's a good thing: use if/else or Option. Dale clarifies that he was trying to make a case for promoting +`UOption` (from [sjrd/scala-unboxed-option](https://github.com/sjrd/scala-unboxed-option)). Sébastien says that +the meeting is running out of time, but he has a solution with UOption. Martin seems pleased and ask "Can we +get it, please, for 3.0?". Seth comments how Sébastien comment sounds like "too long to fit in this margin". :D + +### Review the "main functions" SIP + +Docs: + +Sébastien shares that there are only a few minutes left in the meeting but the gist is that DelayedInit is gone +(so far) and the obvious question is: what do you do for a simple main method? The idea for now is to have an +`@main` annotation and you can write a `def foo`, which takes parameters, and you write the body inside, and, +since we have top level functions, you can write that at the top level, which is even better and everyone is +happy. But there are details, of course. + +Martin states it lacks a champion and asks if anyone wants to champion it. Seth agrees and, so, Sébastien asks +him to open a contributors thread on it. + +## Next + +The next meeting will be on the last week of January, at 17:00 CET. The same will happen in February. In March +the Committee will meet for a 3 day retreat but it will still come online for an hour, to provide a summary +of what happened. diff --git a/_sips/minutes/2020-01-27-sip-minutes.md b/_sips/minutes/2020-01-27-sip-minutes.md new file mode 100644 index 0000000000..3b5c439826 --- /dev/null +++ b/_sips/minutes/2020-01-27-sip-minutes.md @@ -0,0 +1,137 @@ +--- +layout: sips +title: SIP Meeting Minutes - January 27 2020 + +partof: minutes +--- + +# Minutes + +The meeting took place without a pre-defined agenda, but with the overall goal of reviewing progress and +updating the status of features in the Scala 3 feature list +([link](https://dotty.epfl.ch/docs/reference/overview.html)). + +The topics that were discussed were: + +* Binary Integer Literal +* Open Classes +* Explicit Nullability +* Enumerations +* TASTy + +## Date and Location + +The meeting took place on the 27th January 2020 at 17:00 CET via Zoom at EPFL in Lausanne, Switzerland, as well +as other locations. + +The meeting was broadcast and recorded on the Scala Process's YouTube channel: +[SIP meeting January 2020](https://www.youtube.com/watch?v=ws2AaDUg-6E) [1:00:53]. + +Minutes were taken by Dale Wijnand. + +## Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center +* Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), independent +* Dale Wijnand ([@dwijnand](https://twitter.com/dwijnand)), secretary + +## Not present + +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Process Lead +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Lukas Rytz ([@lrytz](https://twitter.com/lrytz)), Lightbend +* Miles Sabin ([@milessabin](https://github.com/milessabin)), independent +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU + +## Proceedings + +(Unfortunately, while the lovely external microphone was fully functional for the Zoom call, unknowing to +everyone at the meeting (until near the end), the laptop microphone was what was being used for the YouTube OBS +capture. Therefore, it is near impossible to hear what was said from the YouTube recording, so the minutes this +month will be an opinionated executive summary of only the highlights.) + +### Binary Integer Literal + +Thread: + +The committee feels that, despite the benefits outlined in the proposal in this Pre-SIP, it doesn't fit the +criteria for inclusion in the initial release of Scala 3 (that is, Scala 3.0), specifically given it can be +added later without technical breakages or changes in understanding of Scala ("book breaking"). However it +might come up again when Dotty's `FromDigits` is discussed (in some future meeting). + +### Open Classes + +Thread: + +After Seb initially summarises the public review contributors' thread, some more technical details are +discussed. + +One suggestion from the thread was that instead of being a new keyword it could be an `@open` annotation that +users can opt-in to. Martin responds that an `@open` annotation doesn't make the language any simpler, and +it's a bit of a cop-out to use an annotation instead of a keyword, particularly as the principle is that +annotations shouldn't change semantics (and it's intended that `open` does). + +It's also highlighted that perhaps one of the biggest motivations for this proposal is to make the default +`class Foo` be the right choice most of the time, countering the blog and conference talk advice that unless +they're doing `final class Foo` (particularly `final case class Foo()`) then their code is "broken" or "not +professional". + +Finally, a strawpoll was taken, with the committee members present, with the following results: + * Aye, by Martin + * Aye, by Sébastien + * Aye, by Guillaume + * Aye, by Adriaan + * Unsure, by Seth, but strongly in favour for just case classes + * Aye, by Josh, but with some nuance on some technical details + +### Explicit Nullability + +Thread: + +Again, after some initial review of the thread feedback and chatting about some of that feedback, one of the +highlights is that roughly Kotlin's platform types are very similar to Dotty's union type implementation, but +that it would be worth comparing more closely to understand where they're different. + +The general update on the proposal is that there are some concerns, and both the proposal and the implementation +require more work and more study. Particularly there are implementation concerns with how unchecked null is +handled, which has consequences on what code is consider valid. As there are other paths to handle Java interop +(including reviewing how platform types work), the proposal is going be somewhat withdrawn, so that the Dotty +team can work on it some more and come back to this SIP proposal. + +Anyone interested in participating in experimentation is very welcome, as experimentation at this point would +be very, very valuable. + +### enum + +Dotty's enum proposal is ready for public review, so Josh will open a thread. + +There are specific topics that need discussing: +* the type of the enum (e.g. is `Some(5)` a `Some[Int]` or a `Option[Int]`) +* details of the Java enum aspect +* some implementation details, like the `toString` of enum variants + +Enums will be discussed at the next SIP meeting. + +Here's the public review thread, by Josh: + +### TASTy + +The TASTy format isn't really a SIP, but it should be one. + +Seb explains how it has mostly been discussed in terms of a new "binary format" for Scala. But he believes that +it instead should be considered as an intermediate language, with a spec, and the golden standard for what Scala +is and means, and what it means for compatibility in the future. + +He continues that up to now the JVM bytecode was considered as the compatibility, and that we have tools like +MiMa to verify backwards compatibility. The TASTy proposal is to change that and use TASTy for that very +purpose. Under that idea, a breaking change to TASTy would mean a breaking change to Scala, and should +therefore mean a new major version (such as Scala 4). + +## Next + +The next meeting will be on the last week of February, at 17:00 CET. In March the Committee will meet for a 3 +day retreat but it will still come online for an hour, to provide a summary of what happened. diff --git a/_sips/minutes/2020-03-11-minutes.md b/_sips/minutes/2020-03-11-minutes.md new file mode 100644 index 0000000000..0228bf43e4 --- /dev/null +++ b/_sips/minutes/2020-03-11-minutes.md @@ -0,0 +1,240 @@ +--- +layout: sips +title: SIP Meeting Minutes - March 11 2020 + +partof: minutes +--- + +# Minutes + +The meeting took place with the following agenda: + +1. Quick setup, reviewing expectations for the retreat +2. Review a list of "easy" dotty features/changes (see section below) +3. Review enums +4. Review creator applications +5. Review `@infix` and `@alpha` +6. Review dependent and polymorphic function types + +## Date and Location + +The meeting took place on the 11th March 2020 throughout the day at EPFL in Lausanne, Switzerland, and Zoom. + +The meeting wasn't broadcast. + +Minutes were taken by Dale Wijnand. + +## Committee Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center + +## Sitting in + +* Jamie Thompson ([@bishabosha](https://github.com/bishabosha)), Scala Center +* Lukas Rytz ([@lrytz](https://twitter.com/lrytz)), Lightbend +* Nicolas Stucki ([@nicolasstucki](https://github.com/nicolasstucki)), EPFL +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Process Lead +* Dale Wijnand ([@dwijnand](https://twitter.com/dwijnand)), secretary + +## Not present + +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), independent +* Miles Sabin ([@milessabin](https://github.com/milessabin)), independent + +Miles notified the committee that he wouldn't be available. Josh, Heather, and Iulian were all unable to +participate because of coronavirus-related travel restrictions and disruptions. + +## Proceedings + +### Expectations + +* Martin: The plan is still to release Scala 3 this year, at the end of December. +* Martin: However, TASTy won't be stable until 3.1 - it won't be a 3.0 promise. +* Martin: Ideally the features would be voted on with the following 3 outcomes + +* accepted, either for 3.0, or some future 3.x release, depending +* accepted, but put behind some kind of "preview" flag, like Java is doing +* rejected +* postponed to after 3.0 + +### Review a "easy" dotty features/changes + +This is the list, with any notable comments added. + +We called features 'easy' if there was already substantial agreement in the pre-retreat straw poll we conducted +beforehand, and if no one present felt that feature needed extended in-person discussion. + +* Context functions +* Drop auto application +* Drop auto tupling + * Martin: this is probably the most breaking change, so weakly against it + * Seth: could it be behind `-Scala2`? Martin: no, that would be difficult + * There's some difficulties in implementing a rewrite rule for it +* Drop class shadowing + * Seb: this is binary breaking for existing libraries + * Seth: it's already deprecated in 2.13.2, which ships shortly + * Seth: so let's make it strong (not under -Xlint) w/ opt-out +* Drop compound types +* Drop DelayedInit + * most of the committee is for dropping it + * but a number of usages of it have been reported + * Guillaume: the implementation isn't a big deal, but it affects TASTy + * ScalaTest, specs2, and cats-effect use it, but our understanding is that they can work around it + * Let's drop it and hopefully someone can write a compiler plugin for it + * Lukas: DelayedInit was the source of lots of bugs in nsc, most fixed by now, though +* Drop do..while + * Seb: it's added because of indentation syntax; how many more like this one? + * Martin: actually it's mainly because of the new control syntax +* Drop early initializers +* Drop existential types + * Guillaume: some cases can be replaced by using opaque types, with explicit wrap and unwrapping +* Drop non-local returns +* Drop package objects + * Lukas: what's wrong with package objects, or it having parents? Don't exports suffer the same problems? + * Seb: package objects are the only thing where you can extend something "in you". Exports don't have that. + * Lukas: what about implicit prioritisation w/ exports? + * Martin: there's a change in implicit resolution so you can add dummy implicit parameters and prioritise those (with companion object prioritisation) +* Drop procedure syntax + * Guillaume: it's dead +* Drop Symbol literals + * Seb: it's basically done +* Drop XML literals + * Guillaume: Dotty supports XML literals (under `-Scala2` flag?) + * Seb: it doesn't leak into binaries/TASTy, can remove later + * Nic: we have a replacement but just without unapply/pattern matching + * Martin: and that isn't used much, so you'd just need to do something else there +* Eta expansion + * no `_` any more + * Gui: issue with println, you `println(myMethod)` and it's not a type error (b/c no args) it prints the function + * Martin: multiversal equality fixes `==` for functions, previously always `false` +* Implicit conversions with Conversion + * Gui: from threads, used a lot by DSL libraries + * Seth: but that was in reference to the explicit-only option, which doesn't have committee support. + * Seth: most DSLs should be fine under the proposal + * +* Implicit resolution changes + * Seb: so many changes + * Gui: need to discuss them 1 by 1, important to discuss them individually + * Gui: some are common sense, some are for ambiguity, adding parameters (prioritisation) + * Martin: would be good to discuss the details with Miles + * Seb: shouldn't be in the "easy" list, then +* Intersection/union + * Seb: no choice, and it's good +* Opaque type aliases + * Seth: pushback from at least some users, don't ship, wait for Valhalla + * Seb: they're not to replace value classes. They have the runtime characteristics of type aliases. + * Lukas: can it be ported back to nsc? Gui: no, sadly +* Open classes + * Seb: summary: overall seems good, but details + * Seb: should it be scoped at the package? when should we warn/error? + * Gui, Seth: seems not easy + * Martin is against the counter-proposal of having it as an opt-in annotation +* Parameter untupling + * Gui: the strong version is that anything on the left is a pattern (rather than just tuple) + * Seth: not crazy about it, seems like another thing you need to learn + * Gui: on the contrary, the status quo (having to add a `case`) forces you to learn this detail early + * Seb: but we're dropping auto-tupling? + * Martin: it's related to the pattern bindings changes (below) +* Pattern bindings + * Martin: `for (case Foo(a, b) <- ...)` for filtering, and val pattern, same + * `case` is now be required whenever the pattern is refutable (🎉) + * +* Toplevel definitions + * Gui: details around `private`. top-level `private type` and `private class`, the type is in a synthetic object, the class is really top level + * that also impacts opaque types + * Seb: then let's force users to put in object and export instead + * but, boilerplate... +* Trait parameters + * Gui/Seb: yes, everyone wants them + * Gui: something about mixing in multiple traits and them having implicit parameters (that need hand-wiring?) +* Type lambdas + * Gui/Seb: yes, everyone wants them + * Gui: something about variance + * Seth: I'll look into whether kind-projector is on track with the changes on their end +* Drop type projection (over abstract types) + * Gui: it's unsound + * Martin: Under `-strict` (i.e. how Scala 3.1 will behave by default) it's a compile error. Will migrate from `-strict` to `-Xsource:3.1` + * Gui: we might change it so it's just lower-bounded, not upper-bounded, proposed by Lionel + * Martin: actually, let's put that change under a `-Y` option + * Seb: Seems to me match types are the replacement for this +* Weak conformance -> harmonization + * Seb: with overloading weak conformance is back + * Seb: Long and Any overloading, nsc conforms Int to Long, dotc picks Any + * Seb: JUnit assertEquals overloads, and Integer/Long aren't equals + * Seb: two parts to this change: the List case (inference) and overloading when primitives are present + * Seth, Adriaan: some people weren't happy with weak conformance, but it's unclear this is really the right thing either, is it progress or mostly sideways motion? + * Seth: I need to re-study this in light of the new numeric-literals proposal +* Wildcard types + * `?` instead of `_` + +### Review enums + +Martin: most seem happy with the current design decisions + +two pushbacks: +1. should apply return the precise type? +2. support nested enums + +Martin says he's received a lot of feedback about the apply question that isn't reflected in the forum discussion. Guillaume says he'll post something. + +Seb: these conflict. If `apply` returns the wide type, then enums can never have nested enums. + +Most of the committee don't feel strongly for hierachical enums ("nested" enums). + +Disallow extending java.lang.Enum outside of enums. + +### Review creator applications + +Seb: what's the point? Martin: avoid having to explain the difference + +Aka "optional `new`". + +Seb and Seth have misgivings and are at least somewhat attached to using `new C` to indicate things that have identity (e.g. ordinary classes), but `C(...)` for things with value semantics. Martin: that sail has shipped - there are many mutable classes with a case class-like companion `def apply`. + +### Review `@infix` and `@alpha` + +* `@infix`: you are allowed and encouraged to call infix +* `@alpha`: very different. 2 things: + +1. it gives the platform encoded (simple) name of the method +2. canonical name of the method (it's "Googleable" name) + +But you can't invoke that alpha name. It's just for reference, like documentation. (So why not just use scaladoc?) + +`@alpha` is trying to address the problem of overuse of symbolic methods. + +Martin: so, 2 questions: + +* should it be mandatory? +* is it useful? + +Most believe it to be useful, but multiple committee members vocally opposed making it mandatory. + +Also can it be merged with `@jsName`? Seb: Yes, but Scala.js's symbol variant of that would have to remain separate. Seth et al considered that sufficient unification. + +No one in the committee who has registered an opinion is against `@infix`, but there is a question of whether to allow non-`@infix`-annotated methods to still be used infix before a curly brace, e.g. `xs map { ....`. + +Conclusion: allow that in 3.0, maybe crack down harder later. + +### Review dependent and polymorphic function types + +* Seb: Dependent function types are good, probably will be accepted. +* Seb: it uses existing concepts (namely refinement types) and adds syntax sugar +* Seb: it's in a more restricted form at the moment, but it can be made more generic later +* Martin: and we fixed a problem with variance + +* Seb: polymorphic function types, on the other hand, are in a completely different realm because "function type" would no longer just be sugar for `trait`+`apply`, they become an independent concept. +* Seb: It's a new encoding. Should we support all sorts of methods? It opens an entirely new world. +* Seb: IMO if we do them, we should go all the way, in 1 go. In particular vararg function types, for Scala.js. +* Gui: even with limitations, they're really useful +* Gui: I have a prototype for this + +## Next + +The next meeting will be tomorrow, 12 March. diff --git a/_sips/minutes/2020-03-12-minutes.md b/_sips/minutes/2020-03-12-minutes.md new file mode 100644 index 0000000000..4e40af5e32 --- /dev/null +++ b/_sips/minutes/2020-03-12-minutes.md @@ -0,0 +1,167 @@ +--- +layout: sips +title: SIP Meeting Minutes - March 12 2020 + +partof: minutes +--- + +# Minutes + +The meeting took place with the following agenda: + +1. Review given instances and context parameters +2. Review given imports +3. Extension methods +4. Export clauses +5. Review metaprogramming +6. Review match types + +## Date and Location + +The meeting took place on the 12th March 2020 throughout the day at EPFL in Lausanne, Switzerland, and Zoom. + +The meeting wasn't broadcast. + +Minutes were taken by Dale Wijnand. + +## Committee Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center + +## Sitting in + +* Lukas Rytz ([@lrytz](https://twitter.com/lrytz)), Lightbend +* Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend +* Jamie Thompson ([@bishabosha](https://github.com/bishabosha)), Scala Center +* Nicolas Stucki ([@nicolasstucki](https://github.com/nicolasstucki)), EPFL +* Olivier Blanvillain ([@OlivierBlanvillain](https://github.com/OlivierBlanvillain)) +* Aggelos Biboudis ([@biboudis](https://github.com/biboudis)) + +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Process Lead +* Dale Wijnand ([@dwijnand](https://twitter.com/dwijnand)), secretary + +## Not present + +* Heather Miller ([@heathermiller](https://github.com/heathermiller)), CMU +* Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote +* Josh Suereth ([@jsuereth](https://github.com/jsuereth)), independent +* Miles Sabin ([@milessabin](https://github.com/milessabin)), independent + +Miles notified the committee that he wouldn't be available. Josh, Heather, and Iulian were all unable to +participate because of coronavirus-related travel restrictions and disruptions. + +## Proceedings + +### Review given instances and context parameters + +* Martin: syntax wise, happy with what we have now +* Martin likes `?=>` instead of `using` +* Gui: but `using` is better for literal (expression level), and then for consistency should be for the type too +* Seb: could use `?=>` at the literal side too, no? +* Martin: we tried, but `using` felt more natural; there was pushback + +Seb: the features are in good shape + +* Gui: a summary from the implicit threads, kind of things people talked about +* Gui: on the contributors threads on implicits there've been a lot of quesitons like "why do we have to the these set of changes? why are these the correct set of changes?" +* Gui: in the docs we don't justify the changes, we don't have design decisions +* Martin: that's because the docs target users +* Gui: but for the SIP process we should +* Gui: also users ask "why can't we just 'fix' the existing stuff?" +* Gui: why instead of a big redesign let's just, for example, fix mulit-parameter implicit classes? +* Martin: we need a fresh start that fixes the 6 different aspects systematically +* Martin: some of the existing problems/bugs are just not fixable +* Gui: people are uneasy with not knowing how things desugar +* Martin: I still think this is within the bandwidth of what Scala's always done +* Gui: another concern is for anonymous things, the compiler has to come up with a name, should we specify that scheme? +* Seb: it's too fragile, for instance if you rename a type, the name changes, or a type parameter name, or whether it's fully qualified or partially imported +* Martin: and the names are optimised to be short, and not optimised not to clash +* Seb: we should highlight that well in the docs: library authors, name your instances (and your method extension given instances) + +### Review given imports + +* Gui: one inconsistency is that doing a named import of a given is without the `given` keyword: `import A.foo` +* Gui: and IDEs will want to import the most specific thing, so the synthetic name of anonymous instances, particularly extension names +* Gui/Seb: we could add `extension` to the import syntax +* Dale: the previous discussion about libraries always wanting to name their given instances and extensions, most things will have good names +* Dale: so if IDEs add imports with synthetic names in apps, doesn't seem to really matter + +### Extension methods + +* Gui: one difference between infix extension methods and grouped extension methods is that grouped they live in a given instance +* Martin: people like the `extension` keyword, when we have it as only `given` people were confused by what these things were +* Gui: one big difference with the status quo (Scala 2) of extension methods is you can't have two sets of type parameters, on the class and on the def, and people aren't pleased with that +* Martin: eventually that will go when we have curried type parameters, which isn't a 3.0 thing +* Gui: could we add `private` support to extension methods? +* Martin: Actually I just tried it, we do allow private + +### Export clauses + +* Martin: addressing the problem that Scala don't assist encouraging composition (over inheritance) +* Martin: side reasons are package object inhertance and exporting enum cases +* Martin: the feedback is some want it to do more, some want it to do less +* Martin: I feel good about how it is now, I wouldn't change any detail on it +* Adriaan: it would be good to add a type ascription when exporting (`export A.T: Foo` to only export Foo's methods) +* Martin: that wouldn't be big, we could add that +* Gui: we could add refinements to the export, to select exactly the method (`export A.T: { def foo(x: Int): Int }`) +* Martin: or users could just do it with a val `val x: Any { def a(x: Int): Int }` +* Adriaan: I'm symapthetic to only allowing to export from static paths, we can always extend it to non static paths +* Seb: the question is does the restriction buy us anything +* Martin: importantly the forwarders are final, you can't overriden them +* Gui: In TASTy should adding a method be TASTy compatible? +* Seb: if we consider them implementation details, then no, you defined your API once, adding a method to the exported thing shouldn't propagate to where you previously exported it +* Gui: export also "interacts" with visibility +* Martin: so you can do `private export foo._`, but in order to you need access to foo at the definition point of the export +* Gui: but now it's `export foo._` which includes all the package private things in `foo` +* Dale: there's a precedent there with current (term and type) forwarders, but with this you can do lots at once, which aggravates the problem + +### Review meta programming + +(**Note: most of the time was spent going over the various feature changes, through the docs.**) + +Run through https://dotty.epfl.ch/docs/reference/metaprogramming/inline.html + +* Gui: why `inline msg: String`? Seeing as the semantics match just use `msg: => String`, just as the syntax, with the current codegen implementation. +* Gui: inline interacts with overriding +* Nic: if in a subclass (say Range) you override a method (say foreach) with `inline` it only inlines if the type is cast +* Seb: I need both, inline if statically the type is Range, and use the optimised override if it's a Seq that's a Range at runtime +* (After the meeting, this led to [scala/scala3#8543](https://github.com/scala/scala3/pull/8543) and [scala/scala3#8564](https://github.com/scala/scala3/issues/8564).) +* Lukas: `inline` is perfect for macros, but it shouldn't exist for performance. The runtime is where performance should be fixed (and it's in a better position to do it) +* Lukas: inlining isn't on by default (in Scala 2) because it interacts with binary compatibility in non-obvious ways, and `inline` in Dotty does the same + +Run through https://dotty.epfl.ch/docs/reference/metaprogramming/macros.html + +Run through https://dotty.epfl.ch/docs/reference/metaprogramming/staging.html, which adds a bit on top of the macro framework above, but can be compiled (and executed) at runtime + +Run through https://dotty.epfl.ch/docs/reference/metaprogramming/reflection.html + +* Gui: concerned how many compiler implementation details TASTy reflect exposes +* Gui: should try to reduce it to the minimum of what users care about, for example, opaque types, and maintain backwards compatibility +* Seb: I think we need to change things and, ultimately, things will have to change, so we can't ship this with API stability guarantees + +### Review match types + +Review https://github.com/dotty-staging/dotty/blob/fix-6709/docs/docs/reference/new-types/match-types.md (part of https://github.com/scala/scala3/pull/8024) + +```scala +type LeafElem[X] = X match { + case String => Char + case Array[t] => LeafElem[t] + case Iterable[t] => LeafElem[t] + case AnyVal => X +} +``` + +* Olivier: The order of match type definitions is significant +* Olivier: The disjointness is between `X` and `String`, not between `String` and `Array` +* Olivier: See https://github.com/scala/scala3/issues/8493 as an example of disjointness requirement (can't use traits) +* Martin: Currently the use-cases can be implemented like Generic +* Olivier: Put at a very high level, the intent is to remove some of the computation that happens in implicits and do it (better) in match types +* Olivier: another problem is that when you type-check a type you can stackoverflow, which has bad UX, particularly given we have recursive types + +## Next + +The next meeting will be tomorrow, 13 March. diff --git a/_sips/minutes/2020-03-13-sip-minutes.md b/_sips/minutes/2020-03-13-sip-minutes.md new file mode 100644 index 0000000000..7e394ea557 --- /dev/null +++ b/_sips/minutes/2020-03-13-sip-minutes.md @@ -0,0 +1,555 @@ +--- +layout: sips +title: SIP Meeting Minutes - March 13 2020 + +partof: minutes +--- + +# Minutes + +The meeting took place with the following agenda: + +1. Review `@main` functions and numeric literals +2. Review indentation syntax changes +3. Review implicit resolution changes +4. Review autotupling, multiversal equality, name based pattern matching and finally structural types + +## Date and Location + +The meeting took place on the 13th March 2020 throughout the day on Zoom. + +The meeting wasn't broadcast. + +Minutes were taken by Jamie Thompson. + +## Committee Attendees + +* Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +* Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend +* Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +* Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center + +## Sitting in + +* Lukas Rytz ([@lrytz](https://twitter.com/lrytz)), Lightbend +* Jamie Thompson ([@bishabosha](https://github.com/bishabosha)), Scala Center +* Nicolas Stucki ([@nicolasstucki](https://github.com/nicolasstucki)), EPFL +* Olivier Blanvillain ([@OlivierBlanvillain](https://github.com/OlivierBlanvillain)) +* Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Process Lead + +### Revisiting Whitebox Inline Definitions + +Martin had an idea for a potential cleanup of syntax for whitebox inline definitions: + +Currently in Dotty: +```scala +inline def f() <: T = … +inline given C as _ <: T = … +``` +Downsides to this approach: +- Differences between `def` and `given` +- Obscure syntax is bad for teaching. +- Hard to Google. + +He suggested to use a modifier instead: +```scala +inline flextype def f(): T = … +inline flextype given C as T = … +``` +Benefits: + +- `flextype` is more searchable. + +Adrian likes the idea from `inline given` to represent the return type as a bounded existential. + +#### Other considerations: + +Nicolas: + +- 1: `whitebox[T]`, where Martins' response was: specialised syntax is harder to swallow, when its specific only to the whitebox and doesn't extend to other types. +- 2: Maybe a new modifier to represent both inline and whitebox? + +### @main functions + +Martin presented `@main` functions: + +- Motivation is replacement for behaviour of DelayedInit: + - Initialisation code in object can cause problems for thread safety. +- Because we have top level definitions, it makes perfect sense to allow program entrypoint to be method at the top level. +- What should the program be called? We use the `@main` annotation to capture the method name and create a wrapper class of the same name in the package containing the method. +- Also provide minimal commandline argument processing to map directly to method parameters, using the `FromString` type class. + +#### Concerns with Commandline Argument Processing + +Jamie: Should it allow named arguments? + +Sébastien: + +- How far should the language go to support command line parsing? + - Should the language go all the way to a bespoke solution, because the potential use cases are unknown. + - Or just stick to basic primitives with no pluggability. +- Problematic to avoid optional flags + +Guillaume: All large programs need a `-help` flag + +Addressing the above, Martin suggests that the intended use case for argument mapping is as follows: + +- Ideal for test programs, simple scripts + - e.g. data science +- Any program needing more sophisticated processing should probably use `String*` + - avoids mutable array + - processing can then be delegated to a library like Scopt + +#### Concern with FromString Type Class + +Sébastien: +- FromString is very general, but the usecase presented is just for CLI, falls apart too quickly due to custom formatting and expressing multi-argument structures such as ranges etc. +- He would stop at `@main` methods with `String*` + +Adriaan: + +- Is `FromString` too general to use for CLI processing, it could make evolution harder if people use it for other cases. +- Lots of options for the problem of structuring unstructured data, such as `:` separated lists for class paths. A general type class is too basic for this situation. +- However, it is easier to make a local specific `FromString` just for CLI than in haskell where you must consider global importance. +- Agrees that whatever argument processing should be able to map directly to method arguments, but something more specialised than `FromString` should be used. +- Alternatively the current proposal could go ahead, but removing hooks for extension in the StdLib. + +Martin, addressing these concerns: + +- Haskell uses `Read` everywhere, if we have `toString`, we should have a general `fromString` method. +- Maybe `@main` methods should have a single argument with type class to parse all command line arguments into it, which is one step removal from single argument of `String*`. +- We must have support for the simple case, `@main` is about boilerplate free work, if you have a need for complex args, the complexity of the program has grown too much for this concern. + +Adriaan suggests that maybe someone can try a new proposal for argument parsing. + +#### Concern for Use Case + +Sébastien: How many programs are so trivial that they dont need argument processing? + +Martin: + +- 99% in his estimate. +- For most people, e.g. simple scripting, these just need either none or few primitive args. + +Guillaume: What's the story for refactoring from the simple case to the more complex cases? + +Martin: + +- We should look into this +- But transitioning to full cli parser is huge step, it will be complex to join the dots. + +#### Existing Solutions Suggested in the meeting + +[1. Swift Argument Parser](https://swift.org/blog/argument-parser/) + +Guillaume: Simple, but it allows validation + +[2. Ammonite Scripts](http://ammonite.io/#ScriptArguments): + +Guillaume: `@main` from ammonite is more complicated (than the SIP proposal) but scales. + +Sébastien: Overloaded mains look more complicated + +Guillaume: + +- It generates help text if args are not correct +- We should be able to document args to main, and support should be in StdLib + +#### Summary + +The main concerns with the proposal are the interactions between the intended use case and the pressure it imposes on the Standard Library. If it is only intended for very simple ordered arguments then perhaps a pluggable `FromString` type class is too simple to include in the standard library. If the language should support more complicated processing, then `FromString` is too basic to be pluggable. + +In a straw poll the present members of the committee were in favour of having the `@main` annotation for program entry points, but perhaps someone could come up with a proposal for a more sophisticated processing solution. + +### Numeric Literals + +Sébastien presented the proposal: + +- Uses a type class which is very similar to `FromString`, with several sub-types for different kinds of literals. +- takes string representation of literal, and converts to an expected type. +- the expected type also specialises which type class instance to search for. + +#### Concerns with Requiring an Expected Type + +Jamie: + +- Only works well for named constants, or passing to unambiguous method arguments. + +Sébastien: + +- In Scala we often lack a concrete expected type, e.g. the left hand side of an operation. +- How well does this scale +- Concerns for loss of precision, e.g. different behaviour of adding different numeric types etc. + +Lukas in chat, to demonstrate lack of inference on LHS of an expression: + +```scala +scala> val x: Long = 10_000_000_000 +val x: Long = 10000000000 +scala> val x: Long = 10_000_000_000 + 1 +1 |val x: Long = 10_000_000_000 + 1 + | ^^^^^^^^^^^^^^ + | number too large +``` + +Martin in response to concerns: +- By default, each sub expression of an expression of an expected type will have the same behaviour as without generic literals, +- More specific behaviour is only activated with an expected type, making this feature perfect for named constants, (which should have an expected type if public). + +#### Concerns for Aesthetics + +Martin: +- Using a string literal constant as a number would look embarassing to introduce to a Python programmer. +- Especially the `BigInt` constructor, its really ugly. + +Guillaume: In Python there is no syntactic overhead for BigInt, Scala would add noise with the expected type. + +Sébastien: +- Its already embarassing enough to explain the different numeric types. +- The situation of overflow in smaller types will not be solved by generic literals, therefore you must explain the existance of `BigInt`, so may as well explain its `String` argument constructor. + +#### Concerns for Use Case + +Adriaan: Will this work well in specific use cases, such as + - Data Science + - REPL + +#### Concerns with Behaviour + +Jamie: There is a problem with failure of conversion with `fromDigits`, if literal format doesnt match defined type class, then there is silent failure + +Nicolas: What can we do with final vals and constant types. + +Martin, in response: +- We can take another look at the specific implementation for activating conversions, and even the type classes in the library. +- Open question: should we have a user pluggable notion of constant type for generic literals. + +#### Alternatives + +#### 1. Numeric Suffixes + +Guillaume: +- Suffixes may be more suited to Scala as an expected type only works well when the whole expression is a simple literal. +- Precedent with prefixes for string interpolator, numeric suffixes could have similar pluggable implementation. + +Martin: +- Suffix is ad-hoc and visually ugly +- Not so bad if its a general pluggable solution, but we can have leaner syntax rules by using types. +- In general, non trivial literals shouldn't be used inline, we should write a named constant. +- Guy Steele suggested it as a more beautiful solution. + +#### 2. Special case Factory Methods + +Olivier: +- The less inference on things, the better +- Python behaviour of conversions is confusing to data scientists, so literals are not always clear to understand + +Sébastien: + +- Assume magical way to pass any literal to an apply method on a companion object of a numeric type. Works for custom types + +#### Scheduling Of Release Discussion + +Martin suggested this was not urgent to ship in 3.0, and asks if it could be put under a flag to ensure it gets tested. + +Guillaume: +- Its tricky because it adds a lot of noise to the std lib and we must be careful what is included there. +- Could we ship it in separate library? + +Adriaan: +- The more we can delay from all proposals, the better. + +#### Conclusion + +There has been little testing in applications of this feature, not enough to make a judgement on its utility. With more consultation from potential users, the SIP committee can gather conclusive evidence. + +There are several concerns, relating to the scope of where this feature makes sense, due to limited type inference, and the verbosity required in inline expressions. It is suggested that this is a non-issue because by default, `Long` literals can't be inferred on the LHS of an addition expression without an expected type, and non-trivial literals should be lifted to named constants. + +Alternatives suggested have been user-defined numeric suffixes, and specialised factory methods for user defined types. + +### Indentation Syntax + +Martin presents the proposal as consisting of several parts: + +- New control syntax (`if then`, `for do`, drop `do while`) +- Optional braces for control expressions if you indent on new line after specific token. +- Optional braces are extended to named definitions: + - Experience showed that without a marker, indentation of 2 spaces was no longer enough to clearly distinguish member definitions. + - `with` worked as a marker for a while but had some disambiguation issues. + - colon marker is settled as the proposal + +#### Usability Anecdotes + +Martin: +- Totally sold as a productivity boost +- Used widely in compiler codebase for 6 months + - Does find is necessary to have vertical bars in editor for indentation +- Examples at: + - https://github.com/scala/scala3/blob/main/compiler/src/dotty/tools/dotc/semanticdb/ExtractSemanticDB.scala + - https://github.com/scala/scala3/blob/main/compiler/src/dotty/tools/dotc/typer/Nullables.scala +- `then` in if expression was harder to get used to + +Guillaume: +- `then` feels like noise but then with multiline conditions is harder to read without it, but was fine with the original parens on condition. +- `end` marker, by being optional, leads to too much bikeshedding + +Martin: +- we can rely on style guides to enforce consistency in a codebase. +- In general, a 10 line block with any empty lines should have an end marker. +- recommends this style for class with companion: +```scala +class Foo: + + def foo = ??? + +object Foo: + + def bar = ??? + +end Foo +``` + +#### On Composability of Features + +Sébastien asks: +- If the implementation of the separate features are orthogonal +- As a consequence, who then has experience using the old control syntax with optional braces, as originally it was thought that indentation was dependent on the new control syntax. + +Martin: +- The features are independent. +- However it seems natural to transition to use them together in 1 step. + +Sebastien had a concern about the performance for parsing, compared to old style code, eg: +```scala +if (x || y) + && (a || b) then foo() +``` + +Martin: Lookahead in the parser is necessary, but this is possible due to operators being accepted on new lines + +#### On Enforcing One Style + +Adriaan: +- Main worry with the whole proposal is too much choice, which could have negative feedback. +- Dotty should enforce one syntactic style, with leniency under the Scala2 language mode + +Guillaume, in disagreement: +- Today its easy to port to Dotty by copy pasting code, or just changing a version number. +- e.g. StackOverflow answers wont work + +Sébastien: +- We need to decide on one choice +- Too many ways to do `if`. +- Dotty supposed to be about simplification, but this makes one of the most basic things complex +- perhaps the compiler should flag if styles are mixed + +#### Conclusion + +No one present at the meeting showed outright objection to the specific new syntax changes. Comments given suggest that for users in the meeting, overall there is a boost to productivity. + +The main objection to the proposal is the amount of choice the user has in the syntax they may choose to use. And there is an open question of what should be restricted in the launch of Scala 3. + +### Implicit Resolution changes + +Martin outines the rules in the [documentation](http://dotty.epfl.ch/docs/reference/changed-features/implicit-resolution.html): + +#### 1) Types must be explicit for implicit vals and results of defs +- Exception for local block + +#### 2) Nesting of implicits is significant +- Implicits look from inside out +- Now resolution of a symbol, not a name +- No more shadowing, but nesting is important + +#### Concerns with Nesting rule + +Guillaume: +- We should be careful with what code from Scala 2 will change under the new rules. +- Concretely in the community build, compilation of Scalacheck inferred a different `map` method for `String` then the one under Scala 2. +- There can be new ambiguities when mixing lexical scope with inheritance scope rules +- People probably do not check that the semantics have changed if you were to change the Scala version and it compiles. +- But perhaps for this meeting we should not focus on migration, just the objective quality of the changes. + +Sébastien, in response: +- if this is dangerous to change, we could delay the changes beyond 3.0 +- Migration is important + +Adriaan, in response: +- I don't think we should be concerned about laziness to read new rules + +Guillaume: +- When looking for an implicit conversion to add a method, the innermost match way not type check, should we look in the outer scope for an objectively better definition? + +Martin, in response: +- This could be problematic because of performance cost of backtracking. We have caches of innermost to outermost. +- Because of cost of new types such as union and intersection, we need savings elsewhere + +Martin, concluding: +- In terms of standardisation, is this acceptable as is to go in? + +#### 3) package prefix no longer contributes to implicit scope + +Martin: Motivation is that it is too easy to pollute everywhere with implicit definitions. + +Guillaume: Doesn't appear to break much code so it seems ok so far. + +#### 4-5) clean up surprising behaviour of divergence or ambiguity + +- in Scala 2 ambiguity wasnt fatal in the presence of an alternative, now it is fails immediately. +- This breaks `Not[T]` encodings, which is now special cased in compiler. + +Sébastien: +- Why are the new rules better? +- My experience in Scala 2 is that diverging implicits are not very easy to understand + +Guillaume: Is the specification of Scala 2 divergence in user documentation? + +Martin: problem with fatal divergence now is that it seems underspecified, e.g. visitation order of search has an effect. + +#### 6) Implicit Conversions with By-Name Parameters Now Have the Same Priority + +Martin: In Scala 2, by-name conversions were added in a "bolt on" fashion, making spec strange for no principled reason. + +#### 7) Context Parameters Lower Specificity of Implicits + +Guillaume: +- Worst feature change as it is seems the most arbitrary +- It may be better for reducing ambiguity, but is more complex. + +Martin believes the inheritance model is very fragile, but this version is more modular. + +Sébastien: +- Believes the older version leads to easier evolution of a library in a binary compatible fashion. +- Demonstrates Scala.js [Union Types](https://github.com/scala-js/scala-js/blob/master/library/src/main/scala/scala/scalajs/js/Union.scala) as a way to evolve priorities with a new base type. +- Asks if the new rules allow to add an implicit definition of a priority in-between two other definitions while preserving binary compatability? + +Martin, in response: +- Shows a [demo](https://github.com/scala/scala3/blob/main/tests/run/implied-priority.scala) of how to insert a new implicit in between existing definitions. +- The new scheme of priorities is more simple to grow than before because inheritance is fragile + +Sébastien is satisfied with the demo, is fine either way to add to 3.0 or later. Someone should champion it. + +Guillaume: +- Will support if library authors are behind it like Cats. +- It's hard to teach and hard to understand. +- Is it really better than status quo? Yes the old system is clunky but is well understood. +- So is it worth it? + +Martin, in response: +- Yes, it's better for the small number of library authors who really need it. +- The old way with traits is a hack, this has principles, why should we deprive ourselves of the correct solution? +- It would be a pity to remove, it took a lot of thought, and is an objectively better design. +- We should have a tutorial documentation for the new rules + +#### Conclusion + +There is fair skepticism for introducing the changes immediately, as the migration path from Scala 2 can be complicated if runtime behaviour changes undetected without a warning or error at compile time. Additionally there are concerns about the effort required to re-educate users with the new rules. + +### Drop Autotupling + +Sébastien: The main challenge is migration, what is the ideal scenario? + +Martin: In the future, there is no autotupling, and then any parens following an infix operator is the start of a tuple and not an argument list. + +Sébastien: +- It looks like most of the use cases for requiring the extra parens have been dropped in 2.13 +- What is the state of deprecation in 2.13 + +Martin: +- Symbolic operators with multiple arguments +- We could delay beyond 3.0, and migration concerns will be less. + +Sébastien: +- It sounds reasonable to delay, and definitely warn/error at definition infix ops with multiple arguments. +- Coupled with ensuring the definitions of infix calls have the infix annotation. + +#### Conclusion +There is general favorability of the proposal from present members, the main concerns are whether or not to delay the feature to aid migration. + +### Multiversal Equality + +Sébastien: has this changed since last discussion? + +Guillaume: +- not changed in very long time +- `strictEquality` probably not tested in the wild much. + +Martin: There has been concern about why we have two type parameters, which was resolved with the people concerned. + +Adriaan: +- Highlights an issue with `strictEquality` and not compiling the standard library: +```scala +$ dotr -language:strictEquality +Starting dotty REPL... +scala> Some(1) == Some(2) +1 |Some(1) == Some(2) + |^^^^^^^^^^^^^^^^^^ + |Values of types Some[Int] and Some[Int] cannot be compared with == or != +``` +- Asks if is this crucial for 3.0 + +Martin: Scala 2 has some checks which give a warning on comparing nonsensical types, which do not exist in dotty. So he would be uncomfortable to ship without a similar feature. + +Guillaume: one solution to the warning could be disjoint checking, like implemented for match types. + +Martin: highlights that the match type implementation doesnt work for traits. + +Guillaume: +- `Eql` doesn't help against comparing two values of statically disjoint subtypes of an ADT, if they have the same type parameter. +- Could we combine warning on disjoint with `Eql`? +- Or possibly a `Disjoint[A,B]` type class which could feed into warnings? + +Martin: There are far more cases where things are disjoint than not so there would be much more noise. + +#### Conclusion +There is mixed favorability for the proposal as is, with concern for precision of errors in the presence of known static divergence and the timing of release. + +### Name based pattern matching + +Name based pattern matching is presented as a formalisation of the rules included in Scala 2, with a few new ones. It is used as the implementation of pattern matching for case classes in Dotty. + +Sébastien: should we use `Product` as a marker trait for this? + +Olivier: We use it to reduce the noise in the LUB of case classes. + +Sébastien demonstrates how [scala-unboxed-option](https://github.com/sjrd/scala-unboxed-option/blob/master/src/main/scala/uoption/package.scala) uses name based patten matching on a value class to achieve matching with no allocations. + +Nicolas: Can we use extension methods to do name based pattern match? (Rather than extend `AnyVal`) + +Guillaume: No because this is run at a later phase that does not resolve dotty extension methods. + +#### On the concern of case class unapply + +(This concern is separate to the SIP proposal) + +Guillaume: +- Some people rely on `unapply` of case class companion to extract an `Option` of some tuple, in Dotty, the `unapply` method is the identity. +- One solution is to special-case case classes in patterns, like Scala 2. + +Martin in response: +- Is it worth the effort to make the compiler more complex for the sake of binary compatability? + +#### Conclusion + +The main concern is the use of `Product` as a marker trait, and the current inability of Dotty extension methods to be used for name-based extractors. But overall everyone present is in favour. + +### Structural Types + +Sébastien: should `Selectable` become a marker trait rather than require specific methods? + +Guillaume: +- Not seen any real-world usage, can some existing "Record" Style macros benefit from this. +- Seems ugly and we need to prove it can be used equivalently to `HMap` in all use cases. + +Martin: Performance concerns with using `HMap`. + +Guillaume: Whatever we propose, it needs to be convenient for calling. + +Martin: We need something to support Chisel in Scala 3. + +Guillaume, in response: +- This is more complicated as Dotty breaks their use case. +- We really need to see it tried in a real application for its intended use case. + +Martin: +- To get people to really try it out, it seems you need a full tutorial. And current docs seems lacking. diff --git a/_sips/process-specification.md b/_sips/process-specification.md new file mode 100644 index 0000000000..93a15ce812 --- /dev/null +++ b/_sips/process-specification.md @@ -0,0 +1,342 @@ +--- +layout: sips +title: Process Specification +redirect_from: /sips/sip-submission.html +--- + +The Scala Improvement Process (sometimes called SIP process) is a process for +submitting changes to the Scala language. This process aims to evolve Scala +openly and collaboratively. + +The SIP process covers the Scala language (syntax, type system and semantics) +and the core of the Scala standard library. The core is anything that is +referenced from the language spec (such as primitive types or the definition +of `Seq`). The SIP process is not concerned with compiler changes that do not +affect the language (including but not limited to linting warnings, +optimizations, quality of error messages). + +A proposed change requires a design document, called a Scala Improvement +Proposal (SIP). The committee meets monthly to discuss, and eventually vote +upon, proposals. + +The committee follows the following process when evaluating SIP documents, +from an idea to the inclusion in the language. + +## Definitions + +- SIP (Scala Improvement Proposal): a particular proposal for changing the Scala + language (additions, changes, and/or removals). +- Committee: a group of experienced Scala practitioners and language designers, + who evaluate changes to the Scala programming language. It consists of a + Secretary, a Chairperson, and Members. +- Chairperson: person in charge of executing the process. They organize and + chair the meetings of the Committee, and generally make sure the process is + followed, but do not vote on proposals. The Chairperson is an appointed + employee of the Scala Center. +- Committee Member: member of the Committee with voting rights. The Chairperson + cannot be a Member at the same time. +- Secretary: person attending the regular meetings and responsible for writing + notes of the discussions. +- SIP Author: any individual or group of people who writes a SIP for submission + to the Committee. The Chairperson and Committee Members may also be SIP Authors. + Authors are responsible for building consensus within the community and + documenting dissenting opinions before the SIP is officially discussed by the + SIP Committee. Their goal is to convince the committee that their proposal is + useful and addresses pertinent problems in the language as well as interactions + with already existing features. Authors can change over the life-cycle of the + SIP. +- SIP Reviewers: a subset of Committee Members assigned by the Chairperson to + review in detail a particular SIP. The same person cannot be both a SIP Author + and a SIP Reviewer for the same SIP. +- SIP Manager: one of the SIP Reviewers who is responsible for all the + communications related to the SIP, throughout its entire life-cycle. This includes requesting a vote on the SIP from the whole Committee, presenting the SIP to the Committee at the plenary meetings, merging or closing the corresponding PR, reporting to the community on the vote outcome, and announcing when it is available for testing. + +## Stages + +From being an idea to being part of the language, a SIP goes through several +Stages that indicate the "maturity" level of the SIP. The following table +summarizes the intent of the various stages. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            StagePurposeEntry criteriaPost-entry changes expected
            Pre-SIPGather initial community feedback and support.N/A. Opening a "Pre-SIP" post on the Scala Contributors forum can be done by anyone at any timeN/A
            DesignMake the case for the proposal. Make the design of the feature precise. Evaluate the solution among other possible solutions. Identify potential challenges.Community support was demonstrated in the Pre-SIP forum post. This is loosely defined.Major changes expected.
            ImplementationProvide an Experimental implementation of the changes in the compiler. Evaluate how they hold up in practice. Get feedback from implementers and users.The SIP contains a precise specification for the changes and how they should interact with the rest of the language.
            + The Committee votes in favor of the SIP to be "Accepted for implementation".            		Minor changes based on feedback from implementers and early users.
            CompletedShip the feature. Once accepted, the feature will ship as stable in the next Minor release of the Scala language.A complete implementation, with tests, was merged in the mainline compiler and shipped as Experimental. Implementers do not have any concerns left wrt. the implementation of the feature and its interactions.
            + The Committee votes in favor of the SIP to be "Accepted".            		No changes allowed.
            + +### The process in one graph + +![](/resources/images/sip/process-chart.png) + +### Pre-SIP Stage + +To initiate a discussion, any individual opens a "Pre-SIP" post in the Scala +Contributors forum. The post should be in the +[Scala Improvement Process](https://contributors.scala-lang.org/c/sip/13) +category, and its title should start with "Pre-SIP:". The purpose of the Pre-SIP +post is to present an idea to the Scala community: a Pre-SIP should present a +problem that needs solving (i.e., motivate the changes) and present possible +solutions with pros and cons. The community is encouraged to engage in the +discussions by voicing support, comments and concerns. + +During the Pre-SIP stage, the Committee is not required to be involved. +Committee Members and the Chairperson are expected to follow Pre-SIP +discussions, but not required to engage. + +Once at least one month has passed and the author has built some community +support for their Pre-SIP, they can Submit a SIP for discussion by the +Committee. "Community support" is loosely defined. It involves a mix of positive +comments, likes, etc. Generally, the Chairperson or a Committee member will post +a comment on the thread suggesting to submit a SIP when they see that a Pre-SIP +is ready to enter the process. + +### Entry into the process (SIP Submission) + +To submit a SIP, a SIP Author writes a pull request to the +[scala/improvement-proposals](https://github.com/scala/improvement-proposals) +repository, following the [tutorial]({% link _sips/sip-tutorial.md %}), and +pointing to the Pre-SIP discussion. If the proposal correctly follows the +template, and the Pre-SIP discussion seems to show some community support, +the Chairperson will accept the SIP for review, assign a SIP number, assign +3 reviewers to the SIP among the Committee Members, and assign one of the reviewers +to be the Manager of that SIP. Since "community support" is +loosely defined, any Committee Member can also comment on the PR to accept the +SIP for review (this is meant mostly as an escape hatch to prevent the +Chairperson from unilaterally blocking a SIP from entering the process). From +that point onwards, the SIP has entered the Design Stage. + +If the template has not been correctly followed, or if none of the Committee +Members nor the Chairperson think that the Pre-SIP has gathered enough support, +the PR may be closed after 2 weeks. + +### PR states and GitHub labels + +As soon as a SIP PR is opened, the GitHub labels `stage:pre-sip` and +`status:submitted` are applied to it. At any given moment, a SIP PR will have as +labels one of the following possibilities: + +| | | | +|------------------------|-------------------------------------|-------------------------| +| `stage:pre-sip` | `status:submitted` | | +| `stage:design` | `status:under-review` | | +| `stage:design` | `status:vote-requested` | `recommendation:accept` | +| `stage:design` | `status:vote-requested` | `recommendation:reject` | +| `stage:implementation` | `status:waiting-for-implementation` | | +| `stage:implementation` | `status:under-review ` | | +| `stage:implementation` | `status:vote-requested` | `recommendation:accept` | +| `stage:implementation` | `status:vote-requested` | `recommendation:reject` | +| `stage:completed` | `status:accepted` | | +| `stage:completed` | `status:shipped` | | +| | `status:rejected` | | +| | `status:withdrawn` | | + +### Design Stage -- Review + +Once a SIP has entered the Design Stage, the assigned reviewers will review (as +a GitHub Review on the SIP PR) the proposal within 3 weeks. The authors may then +address the concerns by pushing additional commits and ask for a new review. +This phase is iterative, like any pull request to an implementation repository. +After each request for a new review, the reviewers have 3 weeks to do another +round. + +When the reviewers are confident that the SIP is in good shape to be discussed +with the full Committee, the Manager sets its status to "Vote Requested" and decide on a +Vote Recommendation that they will bring to the Committee. A Vote Recommendation +is either "Recommend Accept" or "Recommend Reject". The proposal is then +scheduled on the agenda of the next Committee meeting (which happens once a +month). + +At any time, the SIP Author may voluntarily Withdraw their SIP, in which case it +exits the process. It is possible for someone else (or the same person) to +become the new SIP Author for that SIP, and therefore bring it back to the +process. If a SIP Author does not follow up on Reviewers' comments for 2 months, +the SIP will automatically be considered to be Withdrawn. + +### Design Stage -- Vote + +During the Committee meeting, the Managers of any scheduled SIP present the SIP +to the Committee, their recommendation, and explain why they made that +recommendation. After discussion, the Committee votes for advancing the SIP to +the Implementation Stage. There are three possible outcomes: + +- Accept for implementation: the proposal then advances to the Implementation + Stage, and therefore becomes a formal recommendation to be implemented as an + Experimental feature into the compiler. +- Reject: the proposal is rejected and the PR closed. It exits the process at + this point. The reviewers will communicate on the PR the reason(s) for the + rejection. +- Keep: the proposal remains in the Design Stage for further iterations. The + reviewers will communicate on the PR the current concerns raised by the + Committee. + +In order to be accepted for implementation and advance to the next stage, a SIP +must gather strictly more than 50% of "Advance" votes among the whole Committee. This means that an abstention is equivalent to "Do not advance" for this purpose, biasing the process in favor of the status quo. Furthermore, if more than half of the Committee members are absent at the meeting, the vote is cancelled. + +For instance, if the Committee is made of 11 members, at least 6 members have to vote "Advance" for the SIP to move to the next stage. + +If there was a strict majority in favor of "Advance", the PR for the SIP is Merged at this point by its Manager. +Otherwise, a second vote between +Reject and Keep will be used. A proposal needs more than 50% "Reject" votes to +be rejected in that case. Otherwise, it is kept. + +The SIP Manager shares the outcome of the vote with the community by posting a comment to proposal’s Pre-SIP discussion. + +### Implementation Stage + +Once in the implementation stage, the Committee is not concerned with the SIP +anymore, until new concerns are discovered or until the implementation is ready. +The SIP is now a recommendation for the compiler team or any other individual or +group of people to provide an implementation of the proposal, as a pull request +to the Scala 3 compiler repository. There is no set timeline for this phase. + +Often, proposals not only need to be implemented in the compiler, but also in +several other tools (IDEs, syntax highlighters, code formatters, etc.). As soon +as a proposal reaches the implementation stage, the Chairperson notifies the +impacted tools that they should start implementing support for it. A list of +tools of the ecosystem is maintained in [this document][tooling ecosystem]. + +An implementation will be reviewed by the compiler team, and once the +implementation is deemed good enough, it can ship as an Experimental feature in +the next release of the compiler where it's practical to do so. At that point, the SIP Manager posts a follow-up comment on the Pre-SIP discussion to invite the community to test the feature and provide feedback. + +The implementers may hit challenges that were not foreseen by the Committee. +Early users may also provide feedback based on practical experience with the +Experimental feature. This feedback can be sent back to the Committee by +implementers. This is done with a PR to the SIP repository, amending the +previously merged SIP document or raising questions for challenges. In that +case, the SIP Author and Reviewers will work together with the implementers to +address the feedback. This is again an iterative process. Reviewers may merge +changes to the proposal at their discretion during this phase. + +Once the implementation is deemed stable, including appropriate tests and +sufficient support by the tooling ecosystem, the implementers and reviewers can +schedule the SIP to the next Committee meeting for final approval. Once again, a +SIP needs to gather strictly more than 50% "Accept" votes to be Completed. If +that is not achieved, it may likewise be sent back for refinements, or be +rejected, with the same rules as in the "Design Stage -- Vote" section. + +### Completed Stage + +Once a SIP is accepted for shipping, it will be enabled by default (as +non-Experimental) in the next practical Minor release of the language. + +From this point onwards, the feature is stable and cannot be changed anymore. +Any further changes would have to come as an entirely new SIP. + +## The SIP Committee + +The current committee members are: + +- Björn Regnell ([@bjornregnell](https://github.com/bjornregnell)), Lund University +- Chris Andrews ([@chrisandrews-ms](https://github.com/chrisandrews-ms)), Morgan Stanley +- Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL +- Haoyi Li ([@lihaoyi](https://github.com/lihaoyi)), Databricks +- Lukas Rytz ([@lrytz](https://github.com/lrytz)), Lightbend +- Martin Odersky ([@odersky](https://github.com/odersky)), EPFL +- Oron Port ([@soronpo](https://github.com/soronpo)), DFiant Inc +- Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center + +The current Chairperson is: + +- Dimi Racordon ([@kyouko-taiga](https://github.com/kyouko-taiga)), EPFL + +The current Secretary is: + +- Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend + +### Committee Meetings + +The plenary Committee Meetings are scheduled monthly by the Chairperson. They +have the following purposes: + +- Vote to accept, keep or reject SIPs that are in a "Vote Requested" state +- Be aware of the list of SIPs that are "Under review". If a SIP stays too long + under review, Committee Members may request for it to be put to discussion + and/or vote in a subsequent plenary meeting, even if the Reviewers do not + think it is ready. This is meant primarily as an escape hatch, preventing + Reviewers from blocking a SIP by infinitely stalling it. +- Make any exception to the process that they judge necessary to unblock a + situation. + +If a Committee Member cannot attend a meeting, they are welcome to share their feedback about the proposals listed in the agenda of the meeting with the Chairperson, who will relate it during the meeting. A Committee Member cannot give their voting power to someone else. If a Committee Member misses more than 2 meetings within a year, they lose their seat. + +### Responsibilities of the Committee Members + +- Review the proposals they are assigned to: + 1. Discuss unclear points with the authors, + 2. Help them address their issues and questions, + 3. Provide them feedback from the discussions in the meetings, and + 4. Explain the latest progress in every meeting. +- Play a role in the discussions, learn in advance about the topic if needed, + and make up their mind in the voting process. +- Establish communication channels with the community to share updates about the evolution of proposals and collect feedback. + +### Guests + +Experts in some fields of the compiler may be invited to concrete meetings as +guests when discussing related SIPs. Their input would be important to discuss +the current state of the proposal, both its design and implementation. + +### On what basis are proposals evaluated? + +The Committee ultimately decides how to evaluate proposals, and on what grounds. +The Committee does not need to justify its decisions, although it is highly +encouraged to provide reasons. + +Nevertheless, here is a non-exhaustive list of things that the Reviewers and +Committee are encouraged to take into account: + +- The proposal follows the "spirit" of Scala +- The proposal is well motivated; it solves a recurring problem +- The proposal evaluates the pros and cons of its solution; the solution put + forward is believed to be the best one +- The proposal can be implemented in a way that does not break backward binary + nor TASTy compatibility +- The proposal makes an effort not to break backward source compatibility +- The proposal does not change the meaning of existing programs +- The proposal can be implemented on all major platforms (JVM, JS and Native) + +## Exceptions and changes + +The present document tries to account for most situations that could occur in +the lifetime of SIPs. However, it does not pretend to be an ultimate solution to +all cases. At any time, the Committee can decide, by consensus, to make +exceptions to the process, or to refine the process. + +## How do I submit? + +Follow the [submission tutorial]({% link _sips/sip-tutorial.md %}). + +[tooling ecosystem]: https://github.com/scala/improvement-proposals/blob/main/tooling-ecosystem.md diff --git a/_sips/results/2022-08-26-meeting.md b/_sips/results/2022-08-26-meeting.md new file mode 100644 index 0000000000..efec513d6c --- /dev/null +++ b/_sips/results/2022-08-26-meeting.md @@ -0,0 +1,25 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 26th August 2022 +partof: results +proposals: + - url: https://github.com/scala/improvement-proposals/pull/29 + name: SIP-32 - Allow referring to other arguments in default parameters + result: rejected + - url: https://github.com/scala/improvement-proposals/pull/37 + name: SIP-39 - Uncluttering Abuse of Match + result: rejected + - url: https://docs.scala-lang.org/sips/binary-integer-literals.html + name: SIP-42 - Binary Integer Literals + result: accepted + - url: https://github.com/scala/improvement-proposals/pull/42 + name: SIP-40 - Name Based XML Literals + result: rejected + - url: https://github.com/scala/improvement-proposals/pull/41 + name: SIP-45 - Curried varargs + result: rejected + - url: https://docs.scala-lang.org/sips/fewer-braces.html + name: SIP-44 - Fewer braces + result: accepted +--- + diff --git a/_sips/results/2022-09-16-meeting.md b/_sips/results/2022-09-16-meeting.md new file mode 100644 index 0000000000..e18fd2a2da --- /dev/null +++ b/_sips/results/2022-09-16-meeting.md @@ -0,0 +1,13 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 16th September 2022 +partof: results +proposals: + - url: https://github.com/scala/improvement-proposals/pull/47 + name: SIP-47 - Clause Interleaving + result: under-review + - url: https://github.com/scala/improvement-proposals/pull/46 + name: SIP-46 - Use Scala CLI to implement the 'scala' command + result: under-review +--- + diff --git a/_sips/results/2022-10-21-meeting.md b/_sips/results/2022-10-21-meeting.md new file mode 100644 index 0000000000..41347c6274 --- /dev/null +++ b/_sips/results/2022-10-21-meeting.md @@ -0,0 +1,16 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 21st October 2022 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/fewer-braces.html + name: SIP-44 - Fewer braces + result: accepted + - url: https://docs.scala-lang.org/sips/scala-cli.html + name: SIP-46 - Use Scala CLI to implement the 'scala' command + result: accepted + - url: https://docs.scala-lang.org/sips/clause-interleaving.html + name: SIP-47 - Clause Interleaving + result: accepted +--- + diff --git a/_sips/results/2022-11-18-meeting.md b/_sips/results/2022-11-18-meeting.md new file mode 100644 index 0000000000..035164ad8b --- /dev/null +++ b/_sips/results/2022-11-18-meeting.md @@ -0,0 +1,9 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 18th November 2022 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/polymorphic-eta-expansion.html + name: SIP-49 - Polymorphic Eta-Expansion + result: accepted +--- diff --git a/_sips/results/2023-02-17-meeting.md b/_sips/results/2023-02-17-meeting.md new file mode 100644 index 0000000000..ede0dfc5bf --- /dev/null +++ b/_sips/results/2023-02-17-meeting.md @@ -0,0 +1,9 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 17th February 2023 +partof: results +proposals: + - url: https://github.com/scala/improvement-proposals/pull/54 + name: SIP-51 - Drop Forwards Binary Compatibility of the Scala 2.13 Standard Library + result: accepted +--- diff --git a/_sips/results/2023-03-17-meeting.md b/_sips/results/2023-03-17-meeting.md new file mode 100644 index 0000000000..7c1ef1e50f --- /dev/null +++ b/_sips/results/2023-03-17-meeting.md @@ -0,0 +1,9 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 17th March 2023 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/scala-cli.html + name: SIP-46 - Scala CLI as default Scala command + result: accepted +--- diff --git a/_sips/results/2023-04-21-meeting.md b/_sips/results/2023-04-21-meeting.md new file mode 100644 index 0000000000..b522759d88 --- /dev/null +++ b/_sips/results/2023-04-21-meeting.md @@ -0,0 +1,12 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 21st April 2023 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/quote-pattern-type-variable-syntax.html + name: SIP-53 - Quote pattern explicit type variable syntax + result: accepted + - url: https://docs.scala-lang.org/sips/multi-source-extension-overloads.html + name: SIP-54 - Multi-Source Extension Overloads + result: accepted +--- diff --git a/_sips/results/2023-06-16-meeting.md b/_sips/results/2023-06-16-meeting.md new file mode 100644 index 0000000000..0ad96e5ffb --- /dev/null +++ b/_sips/results/2023-06-16-meeting.md @@ -0,0 +1,9 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 16th June 2023 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/multi-source-extension-overloads.html + name: SIP-54 - Multi-Source Extension Overloads + result: accepted +--- diff --git a/_sips/results/2023-07-21-meeting.md b/_sips/results/2023-07-21-meeting.md new file mode 100644 index 0000000000..6d873e6717 --- /dev/null +++ b/_sips/results/2023-07-21-meeting.md @@ -0,0 +1,7 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 21st July 2023 +partof: results +proposals: [] +--- +No voting was held on this meeting. \ No newline at end of file diff --git a/_sips/results/2023-09-11-meeting.md b/_sips/results/2023-09-11-meeting.md new file mode 100644 index 0000000000..c7231e6d9b --- /dev/null +++ b/_sips/results/2023-09-11-meeting.md @@ -0,0 +1,7 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 11th September 2023 +partof: results +proposals: [] +--- +No voting was held on this meeting. \ No newline at end of file diff --git a/_sips/results/2023-10-20-meeting.md b/_sips/results/2023-10-20-meeting.md new file mode 100644 index 0000000000..33abe5c90a --- /dev/null +++ b/_sips/results/2023-10-20-meeting.md @@ -0,0 +1,9 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 20th October 2023 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/binary-api.html + name: SIP-52 - Binary APIs + result: accepted +--- diff --git a/_sips/results/2023-11-17-meeting.md b/_sips/results/2023-11-17-meeting.md new file mode 100644 index 0000000000..fcb63c9e26 --- /dev/null +++ b/_sips/results/2023-11-17-meeting.md @@ -0,0 +1,9 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 17th November 2023 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/match-types-spec.html + name: SIP-56 - Proper Specification for Match Types + result: accepted +--- diff --git a/_sips/results/2023-12-15-meeting.md b/_sips/results/2023-12-15-meeting.md new file mode 100644 index 0000000000..647b689123 --- /dev/null +++ b/_sips/results/2023-12-15-meeting.md @@ -0,0 +1,7 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 12th December 2023 +partof: results +proposals: [] +--- +No voting was held on this meeting. \ No newline at end of file diff --git a/_sips/results/2024-01-19-meeting.md b/_sips/results/2024-01-19-meeting.md new file mode 100644 index 0000000000..23f2f49c6a --- /dev/null +++ b/_sips/results/2024-01-19-meeting.md @@ -0,0 +1,9 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 19th January 2024 +partof: results +proposals: + - url: https://docs.scala-lang.org/sips/match-types-spec.html + name: SIP-56 - Proper Specification for Match Types + result: accepted as completed +--- diff --git a/_sips/results/2024-04-19-meeting.md b/_sips/results/2024-04-19-meeting.md new file mode 100644 index 0000000000..b5db00bc7a --- /dev/null +++ b/_sips/results/2024-04-19-meeting.md @@ -0,0 +1,16 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 19th April 2024 +partof: results +proposals: + - url: https://github.com/scala/improvement-proposals/pull/72 + name: SIP-58 - Named Tuples + result: accepted + - url: https://github.com/scala/improvement-proposals/pull/79 + name: SIP-62 - For comprehension improvements + result: accepted + - url: https://github.com/scala/improvement-proposals/pull/81 + name: SIP-64 - Improve the syntax of context bounds and givens + result: accepted +--- +SIP-61 and SIP-63 were discussed but no vote was held. diff --git a/_sips/results/2024-05-24-meeting.md b/_sips/results/2024-05-24-meeting.md new file mode 100644 index 0000000000..51bf1e0a34 --- /dev/null +++ b/_sips/results/2024-05-24-meeting.md @@ -0,0 +1,10 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 24th May 2024 +partof: results +proposals: + - url: https://github.com/scala/improvement-proposals/pull/78 + name: SIP-61 - Unroll default arguments for binary compatibility + result: accepted +--- +SIP-64 was discussed but no vote was held. diff --git a/_sips/results/2024-06-21-meeting.md b/_sips/results/2024-06-21-meeting.md new file mode 100644 index 0000000000..9ebb1ca250 --- /dev/null +++ b/_sips/results/2024-06-21-meeting.md @@ -0,0 +1,10 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 21st June 2024 +partof: results +proposals: + - url: https://github.com/scala/improvement-proposals/pull/47 + name: SIP-47 - Clause interleaving + result: accepted +--- +SIP-55, SIP-58, SIP-60, SIP-62, and SIP-64 were discussed but no vote was held. diff --git a/_sips/results/2024-08-16-meeting.md b/_sips/results/2024-08-16-meeting.md new file mode 100644 index 0000000000..73361aa923 --- /dev/null +++ b/_sips/results/2024-08-16-meeting.md @@ -0,0 +1,7 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 16th August 2024 +partof: results +proposals: [] +--- +SIP-49, SIP-52, SIP-57, SIP-58, SIP-61, SIP-62, SIP-64, and SIP-66 were discussed but no vote was held. diff --git a/_sips/results/2024-09-27-meeting.md b/_sips/results/2024-09-27-meeting.md new file mode 100644 index 0000000000..bbb0bb8b81 --- /dev/null +++ b/_sips/results/2024-09-27-meeting.md @@ -0,0 +1,13 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 27th September 2024 +partof: results +proposals: + - url: https://github.com/scala/improvement-proposals/pull/72 + name: SIP-58 - Named Tuples + result: accepted + - url: https://github.com/scala/improvement-proposals/pull/81 + name: SIP-64 - Improve the syntax of context bounds and givens + result: accepted +--- +SIP-62 was discussed but no vote was held. diff --git a/_sips/results/2024-11-15-meeting.md b/_sips/results/2024-11-15-meeting.md new file mode 100644 index 0000000000..1a5da82052 --- /dev/null +++ b/_sips/results/2024-11-15-meeting.md @@ -0,0 +1,7 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 15th November 2024 +partof: results +proposals: [] +--- +SIP-66 was discussed but no vote was held. diff --git a/_sips/results/2024-12-20-meeting.md b/_sips/results/2024-12-20-meeting.md new file mode 100644 index 0000000000..a9454f3250 --- /dev/null +++ b/_sips/results/2024-12-20-meeting.md @@ -0,0 +1,7 @@ +--- +layout: sip-meeting-results +title: SIP Meeting Results - 20th December 2024 +partof: results +proposals: [] +--- +SIP-62 and SIP-67 were discussed but no vote was held. diff --git a/_sips/sip-submission.md b/_sips/sip-submission.md deleted file mode 100644 index bffbc2eda9..0000000000 --- a/_sips/sip-submission.md +++ /dev/null @@ -1,329 +0,0 @@ ---- -layout: sips -title: SIP Specification and Submission ---- - -A **SIP** (_Scala Improvement Process_) is a process for submitting changes to -the Scala language. Its main motivation is to become the primary mechanism to -propose, discuss and implement language changes. In this process, all changes to -the language go through design documents, called Scala Improvement Proposals -(SIPs), which are openly discussed by a committee and only upon reaching a -consensus are accepted to be merged into the Scala compiler. - -The aim of the Scala Improvement Process is to apply the openness and -collaboration that have shaped Scala's documentation and implementation to the -process of evolving the language. This document captures our guidelines, -commitments and expectations regarding this process. - -## Why write a SIP? - -SIPs are key to making Scala better for the good of everyone. If you decide to -invest the time and effort of putting a SIP forward and seeing it through, your -efforts and time will shape and improve the language, which means that your -proposal may impact the life of a myriad of developers all over the world, -including those on your own team. For many, this aspect alone can be quite -worthwhile. - -However, it's important to note that seeing a SIP through to its conclusion is -an involved task. On the one hand, it takes time to convince people that your -suggestions are a worthwhile change for hundreds of thousands of developers to -accept. Particularly given the sheer volume of developers that could be affected -by your SIP, SIP acceptance is conservative and carefully thought through. -Typically, this includes many rounds of discussion with core Scala maintainers -and the overall community, several iterations on the design of the SIP, and some -effort at prototyping the proposed change. Often, it takes months of discussion, -re-design, and prototyping for a SIP to be accepted and included in the Scala -compiler. It is, therefore important to note that seeing a SIP through to its -conclusion can be time-consuming and not all SIPs may end up in the Scala -compiler, although they may teach us all something! - -If you’re motivated enough to go through this involved but rewarding process, go -on with writing and keep on reading. - -## What's the process for submitting a SIP? - -There are four major steps in the SIP process: - -1. Initial informal discussion (2 weeks) -2. Submission -3. Formal presentation (up to 1 month) -4. Formal evaluation (up to 6 months) - -### Initial informal discussion (2 weeks) - -Before submitting a SIP, it is required that you perform necessary preparations: - -Discuss your idea on the [Scala Contributors Page](https://contributors.scala-lang.org/) (currently, we suggest -cross-posting on -[Scala Improvement Process](https://contributors.scala-lang.org/c/sip) and -[Language Design](https://contributors.scala-lang.org/c/language-design). This -may change in the future.) Create a topic that starts with “Pre-SIP” and briefly -describe what you would like to change and why you think it’s a good idea. - -Proposing your ideas on the mailing list is not an optional step. For every -change to the language, it is important to gauge interest from the compiler -maintainers and the community. Use this step to promote your idea and gather -early feedback on your informal proposal. It may happen that experts and -community members may have tried something similar in the past and may offer -valuable advice. - -Within two weeks after your submission of the pre-SIP to the mailing list, the -Process Lead will intervene and advise you whether your idea can be submitted as -a SIP or needs more work. - -### Submission - -After receiving the green light from the Process Lead, you can write up your -idea and submit it as a SIP. - -A SIP is a Markdown document written in conformance with the [process template](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md). -It ought to contain a clear specification of the proposed changes. When such -changes significantly alter the compiler internals, the author is invited to -provide a proof of concept. Delivering a basic implementation can speed up the -process dramatically. Even compiler hackers find very difficult to predict the -interaction between the design and the implementation, so the sooner we have an -evidence of a working prototype that interacts with all the features in Scala, -the better. Otherwise, committee members may feel that the proposed changes are -impossible and automatically dismiss them. If your changes are big or somewhat -controversial, don’t let people hypothesize about them and show results upfront. - -A SIP is submitted as a pull request against [the official Scala website -repo](https://github.com/scala/docs.scala-lang). Within a week of receiving the -pull request, the Process Lead will acknowledge your submission, validate it and -engage into some discussions with the author to improve the overall quality of -the document (if necessary). - -When you and the Process Lead agree on the final document, it is formally -accepted for review: assigned a reviewer and scheduled for formal presentation. - -### Formal presentation (up to 1 month) - -During the next available SIP Committee meeting, the appointed reviewer presents -the SIP to the committee and kick starts the initial discussion. - -If the committee agrees that following through the SIP is a good idea, then the -following happens: - -1. The SIP is assigned a number. -2. The SIP pull request is merged into the official Scala website repo, and the -merged document becomes the official webpage of the proposal. -3. An issue to discuss the SIP is opened at the official Scala website repo. Then, -the reviewer submits the initial feedback from the committee. -4. An implementation is requested (if not already present). - -Otherwise, the SIP is rejected. The reviewer submits the collected feedback as a -comment to the pull request, and the pull request is closed. - -### Formal evaluation (up to 6 iterations) - -Evaluation of a SIP is done in iterations. The maximum number of iterations is -six. These iterations take place in the SIP meetings and are usually monthly. -However, they can last longer, in which case the author has more time to -implement all the required changes. - -The committee decides the duration of the next iteration depending upon the -feedback and complexity of the SIP. Consequently, authors have more time to -prepare all the changes. If they finish their revision before the scheduled -iteration, the Process Lead will reschedule it for the next available meeting. - -During every iteration, the appointed reviewer presents the changes (updated -design document, progress with the implementation, etc) to the SIP Committee. -Based on the feedback, the SIP is either: - -1. Accepted, in which case the committee asks the compiler maintainers to - indicate the earliest version of Scala that can include the language change. -2. Rejected, in which case the SIP is closed and no longer evaluated in the - future. -3. Under revision, in which case the author needs to continue the formal - evaluation and address all the committee's feedback. Thus, the follow-up - discussion is scheduled for the next iteration. -3. Postponed, in which case the committee does not evaluate the proposal anymore - and sets it aside under some conditions are met. Then, the SIP will be - resubmitted. This situation happens when proposals entirely depend on another - pending proposals and need their admission. In such cases, the dependent - proposal is postponed until the Committee votes on the other one. - -If no changes have been made to a SIP in two iterations, it’s marked as dormant -and both the PR and issue are closed. Dormant SIPs can be reopened by any -person, be it the same or different authors, at which point it will start from -the formal evaluation phase. - -### Merging the proposal - -If the SIP is accepted, the committee will propose a release date to the -compiler maintainers, where the role of the committee ends. Accepted SIPs will -then be merged under a flag. When SIPs introduce intricate changes and they -cannot be merged under a flag, the compiler maintainers will merge it directly. - -## Structure of the process - -The SIP process involves the following parties: - -1. The SIP Author(s) -2. The Process Lead -3. The SIP Committee - -### The SIP Author(s) - -Authors are responsible for building consensus within the community and -documenting dissenting opinions before the SIP is officially discussed by the -SIP Committee. Their goal is to convince the committee that their proposal is -useful and addresses pertinent problems in the language as well as interactions -with already existing features. Authors can change over the life-cycle of the -SIP. - -### The Process Lead - -The Process Lead is the responsible of the smooth running of SIPs and SLIPs. He -or she appoints the committee members, calls the meetings monthly, assigns new -proposals to the members, and ensures that all of them are discussed within a -short period of time. - -### The SIP Committee - -The SIP Committee is an experienced group of people with knowledge of the -compiler internals, responsible for the strategic direction of Scala. Members -are tasked with (a) communicating with the community, (b) weighing in pros and -cons of every proposal, and (c) accepting, postponing or rejecting the proposal. - -Committee members should be either individuals responsible for a specific part -of the Scala codebase, committers or contributors of the Scala compiler. -Exceptionally, members may also be important representatives of the community -with a high technical knowledge to understand the implications of every proposal -and participate into the discussions. The members are elected by the Process -Lead based on their expertise and implication in the community. - -The current committee members are: - -- Martin Odersky ([@odersky](https://github.com/odersky)), EPFL -- Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend -- Heather Miller ([@heathermiller](https://github.com/heathermiller)), Scala Center -- Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend -- Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), EPFL -- Eugene Burmako ([@xeno-by](https://github.com/xeno-by)), Twitter -- Josh Suereth ([@jsuereth](https://github.com/jsuereth)), Google -- Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote - -The current Process Lead is: - -- Jorge Vicente Cantero ([@jvican](https://github.com/jvican)), Scala Center - -### Reviewers - -The Process Lead assigns every proposal to a member of the committee, who -becomes the reviewer. The main tasks of the reviewer are the following: - -1. Discuss unclear points with the authors, -2. Help them address their issues and questions, -3. Provide them feedback from the discussions in the meetings, and -4. Explain the latest progress in every meeting. - -### SIP meetings - -SIP meetings are scheduled monthly by the Process Lead, and require a quorum of -two-thirds (2/3) of the committee members. If the quorum is not reached the -meeting is rescheduled. - -### Voting - -All SIP Committee members vote. They can either vote in the meeting or by -casting their vote via email to the SIP Process Lead before the set deadline. - -SIP Committee members can vote "in favor", "against" or "abstain". - -For a SIP to be accepted, the following three requirements must be met: - -- At least 50% of the committee members vote in favor. -- There are at least two-thirds "in favor" versus "against" votes. -- Martin Odersky does not veto it. - -An alternative way to think of the two-thirds requirement is that the number of -votes in favor must be at least twice the number of votes against. Abstentions -are excluded in calculating a two-thirds vote. - -Note that, when calculating the lower bound, numbers round up. Therefore for a -committee of 9 members, at least 50% means at least 5 members. - -The deadline to vote a proposal is decided on a case-by-case basis. The deadline -will be decided by the committee members present at the last meeting and the SIP -Process Lead, and will be made public right after the meeting. - -#### Examples - -Several voting situations are explained next. - -All of them assume that there are 9 committee members. The 50% requirement -requires at least 5 members to vote in favor. We also assume that Martin does -not veto them. - -| In favor | Against | Abstentions | Voting members | Result | -| -------- | ------- | ----------- | -------------- | ------------ | -| 6 | 2 | 1 | 8 | Accepted | -| 5 | 3 | 1 | 8 | Not Accepted | -| 5 | 2 | 2 | 7 | Accepted | - -In the first situation, the proposal is accepted because 6 is both greater than -the 50% (5) and more than twice the votes against (2). In the second situation, -the proposal meets the 50% requirement but fails the two-thirds requirement -since 5 is less than twice the number of votes against, 3, therefore the -proposal is not accepted. In the third situation, the proposal is accepted -because 5 is equal to 50% of all the committee members and is greater than twice -the number of votes against (2). - -### Responsibilities of the members - -- Review the proposals they are assigned to. The Process Lead will always notify -them two weeks in advance, at minimum. -- Play a role in the discussions, learn in advance about the topic if needed, and -make up their mind in the voting process. -- Decide which utilities should be inside the core module and are required by the -compiler. The goal is to shrink it over time, and, where possible, move modules -to the platform, that will be managed by the SLIP process. - -### Guests - -Experts in some fields of the compiler may be invited to concrete meetings as -guests when discussing related SIPs. Their input would be important to discuss -the current state of the proposal, both its design and implementation. - -## Proposal states - -The state of a proposal changes over time depending on the phase of the process -and the decisions taken by the committee. A given proposal can be in one of -several states: - -1. **Validated:** The Process Lead has validated the proposal and checked that -meets all the formal requirements. -2. **Numbered:** The committee agrees that the proposal is a valid document and -it’s worth considering it. Then, the Process Lead gives it a number. -3. **Awaiting review:** The proposal has been scheduled to be reviewed for a -concrete date. -4. **Under review:** Once the author has delivered a new version, the proposal will -be under review until the next available SIP meeting takes place. -5. **Under revision:** Authors are addressing the issues pinpointed by the -committee or working on the implementation. -6. **Dormant:** When a SIP has been under revision for more than two iterations - and no progress has been made, the Process Lead will mark it as dormant (note - that the committee does not have such privilege). This status means that the - Process Lead will not assign its review in future meetings until authors - provide the requested feedback or progress. Also, authors can also mark their - proposals as dormant, and they are encouraged to do so if they think they - will not have time for their update. -7. **Postponed:** The SIP has been postponed under some concrete conditions. When these -are met, the SIP can be resubmitted. -8. **Rejected:** The SIP has been rejected with a clear and full explanation. -9. **Accepted:** The SIP has been accepted and it’s waiting for the merge into the -Scala compiler. - -## How do I submit? ## - -The process to submit is simple: - -* Fork the Scala documentation repository, [http://github.com/scala/docs.scala-lang](http://github.com/scala/docs.scala-lang). -* Create a new SIP file in the `_sips/sips/`. Use the [S(L)IP template](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md) - * Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`. - * Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP. - * Follow the instructions in the [README](https://github.com/scala/docs.scala-lang/) to build your SIP locally so you can ensure that it looks correct on the website. -* Create a link to your SIP in the "pending sips" section of `index.md` -* Commit your changes to your forked repository -* Create a new [pull request](https://github.com/scala/docs.scala-lang/pull/new/gh-pages). This will notify the Scala SIP team. diff --git a/_sips/sip-template.md b/_sips/sip-template.md deleted file mode 100644 index 0781e987b3..0000000000 --- a/_sips/sip-template.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -layout: sips -discourse: true -title: SIP-NN - SIP Title ---- - -**By: Author 1 and Author 2 and Author 3** - -This document is provided as a template to get you started. Feel free to add, augment, -remove, restructure and otherwise adapt the structure for what you need after cloning it. -The cloned document should be placed in sips/pending/_posts according to the naming -conventions described in the [SIP tutorial](./sip-tutorial.html). - -## History - -| Date | Version | -|---------------|---------------| -| Feb 19th 2015 | Initial Draft | -| Feb 20th 2015 | Alteration Details | - -## Introduction/Motivation/Abstract - -(feel free to rename this section to Introduction, Motivation, Abstract, whatever best suits - your library proposal.) - -A high level overview of the library with: - -* Description of the scope/features of the library. -* An explanation of the reason the library is needed, what's missing in the core libs - that is supplied. -* Simple code examples if they help clarify, note that there will be ample opportunity - for more detailed code examples later in the SIP - -Think of the introduction as serving to describe the library addition in a way -that lets a reader decide if this is what they are looking for, whether they think -this is the right approach to supply the extra functionality, and whether they might -want to get involved. - -## Motivating Examples - -### Examples - -Code heavy description of how the library functionality can be used. - -{% highlight scala %} -// here is some example scala code, highlighted nicely -import scala.concurrent._ - -class Foo extends Bar { - val x = 10 - def yo(name: String): String = s"hello $name" -} -{% endhighlight %} - -### Comparison Examples - -Code demonstrating why the library is needed, how equivalent functionality -might be provided without it. - -### Counter-Examples - -What the library is not intended to be used for. Examples of what to avoid and -why. - -## Design - -Discuss design decisions (including, as examples): - -* Reason about correctness of the implementation. -* "Feel and fit" with existing core libraries. -* Performance and threading considerations. -* Naming of classes, traits, methods. -* Footprint of API. -* Potential conflicts with existing libraries, e.g. name clashes, IDE auto-import friction, etc. - -## Implementation - -Include consideration of the following: - -* Is this library intended to be bundled with the current core libs, or (recommended) live in -a separate module distributed with the core distribution of Scala -(e.g. parser combinators, reflection, etc.) -* **Existing implementation(s)** (e.g. donor library, github project, etc.). Note that -having an existing implementation library from which this will be drawn, and that people -can download and try now, is highly recommended. -* Time frame, target Scala version for inclusion. -* Roll-out plan (start with external module, include in std distribution, move to core). -* Other volunteers/contributors (with areas of expertise, github contact info, etc.) - -## Counter-Examples - -What the library is not intended to be used for. Examples of what to avoid and -why. - -## Drawbacks - -Why should we *not* do this. Be honest, these questions will come out during the -process anyway so it's better to get them out up front. - -## Alternatives - -* What other possibilities have been examined? -* What is the impact of not implementing this proposal? - -## References - -1. [Existing (Donor) Project][1] -2. [API Documentation][2] -3. [Academic/Research papers/supporting material][3] -4. [Alternative Libraries/Implementations][4] -5. [Discussion forum/post/gitter/IRC][5] - -[1]: http://github.com "GitHub" -[2]: http://www.scala-lang.org/api/ "Scaladoc" -[3]: http://en.wikipedia.org/wiki/Academic_publishing "Academic/Research" -[4]: https://github.com/dogescript/dogescript "Alternatives" -[5]: https://gitter.im "Gitter" diff --git a/_sips/sip-tutorial.md b/_sips/sip-tutorial.md index 680eee2d73..95bb45b053 100644 --- a/_sips/sip-tutorial.md +++ b/_sips/sip-tutorial.md @@ -1,51 +1,90 @@ --- layout: sips title: Writing a new SIP +redirect_from: /sips/sip-template.html --- -This tutorial details of how to write a new SIP and adding it to the website. +This tutorial details of how to write a new Scala Improvement Proposal (SIP) and how to submit it. + +## Why write a SIP? + +SIPs are key to making Scala better for the good of everyone. If you decide to +invest the time and effort of putting a SIP forward and seeing it through, your +efforts and time will shape and improve the language, which means that your +proposal may impact the life of a myriad of developers all over the world, +including those on your own team. For many, this aspect alone can be quite +worthwhile. + +However, it's important to note that seeing a SIP through to its conclusion is +an involved task. On the one hand, it takes time to convince people that your +suggestions are a worthwhile change for hundreds of thousands of developers to +accept. Particularly given the sheer volume of developers that could be affected +by your SIP, SIP acceptance is conservative and carefully thought through. + +It is important to note that seeing a SIP through to its +conclusion can be time-consuming and not all SIPs may end up in the Scala +compiler, although they may teach us all something! + +Last, but not least, delivering a basic implementation can speed up the +process dramatically. Even compiler hackers find very difficult to predict the +interaction between the design and the implementation, so the sooner we have an +evidence of a working prototype that interacts with all the features in Scala, +the better. + +If you’re motivated enough to go through this involved but rewarding process, go +on with writing and keep on reading. + +The following sections provide an overview of the process, and guidelines on +how to submit a proposal. The detailed process specification is available +[here]({% link _sips/process-specification.md %}). + +## Overview of the process + +From being an idea to being part of the language, a SIP goes through several +*stages* that indicate the “maturity” level of the SIP. The following diagram +summarizes the purpose of each stage: + +![](/resources/images/sip/sip-stages.png) + +0. **Pre-SIP** You should start by creating a discussion thread in the + [Scala Improvement Process](https://contributors.scala-lang.org/c/sip/13) + category of the Scala Contributors forum to gather initial community feedback + and support. The title of your discussion should start with "Pre-SIP". In + this discussion, the community might bring you alternative solutions to + the problem you want to solve, or possible bad interactions with other + features of the language. Eventually, these discussions may help you polish + your proposal. +1. **Design** The next stage consists of submitting a detailed description of + your proposal for approval to the SIP Committee. See the section + [How do I submit?](#how-do-i-submit) to know the procedure and expected + format. Your proposal will first be reviewed by a small group of reviewers, + and eventually the full Committee will either approve it or reject it. +2. **Implementation** If the Committee approved your proposal, you are + welcome to provide an implementation of it in the compiler so that it can + be shipped as an experimental feature. You may hit new challenges during the + implementation of the feature, or when testing it in practice. In such a + case, you should amend the proposal, which will be reviewed again by the + reviewers from the SIP Committee. Once the implementation is deemed stable, + the full Committee will vote again on the final state of the proposal. +3. **Completed** If the Committee accepted the proposal, it will be shipped as + a stable feature in the next minor release of the compiler. The content of + the proposal may not change anymore. ## How do I submit? ## -The process to submit is simple: +The process to submit is the following: -* Fork the [Scala documentation repository](http://github.com/scala/docs.scala-lang) and clone it. -* Create a new SIP file in the `sips/pending/_posts/`. Use the [S(L)IP template](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md) - * Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`. - * Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP. - * Follow the instructions in the [README](https://github.com/scala/docs.scala-lang/blob/master/README.md) to build your SIP locally so you can ensure that it looks correct on the website. -* Create a link to your SIP in the "pending sips" section of `index.md`. +* Fork the [Scala improvement proposals repository](https://github.com/scala/improvement-proposals) and clone it. +* Create a new branch off the `main` branch. +* Copy the [SIP template](https://github.com/scala/improvement-proposals/blob/main/sip-template.md) into the directory `content/` + * Give a meaningful name to the file (e.g., `eta-expansion-of-polymorphic-functions.md`). + * Use the [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax) to write your SIP. + * The template is provided to help you get started. Feel free to add, augment, remove, restructure and otherwise adapt the structure for what you need. * Commit your changes and push them to your forked repository. -* Create a new pull request. This will notify the Scala SIP team. - - -## SIP Post Format ## - -First, create a new SIP file in the `pending/_posts` directory. Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Where: -* `YYYY` is the current year when the proposal originated. -* `MM` is the current month (`01` = January, `12` = December) when the proposal originated. -* `dd` is the day of the month when the proposal originated. -* `{title}` is the title for the SIP. +* Create a new pull request. This will notify the Scala SIP team, which will get back to you within a couple of weeks. ### Markdown formatting ### -Use the [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax) to write your SIP. - -If you would like a starting point, clone the [SIP Template](./sip-template.html) in -`sips/pending/sip-template.md` and use that. - -See the [source](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md) for this document (`sip-tutorial.md`) for how to do syntax highlighting. - -{% highlight scala %} -class Foo -{% endhighlight %} - - -## Testing changes ## - -Testing changes requires installing [Jekyll](http://jekyllrb.com/docs/installation/). Since this site is hosted on github pages, make sure you have [whatever version of Jekyll that github is running](https://help.github.com/articles/using-jekyll-with-pages#troubleshooting). As of the writing of this README, that is version >= 1.0.x. +Use the [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax) to write your SIP. -After the installation, you need to start up the local server. The -[README](https://github.com/scala/docs.scala-lang/blob/master/README.md) gives -a concise explanation on how to do it. When the server is running, view your -changes at [http://localhost:4000/sips](http://localhost:4000/sips). +See the content of the [SIP template](https://github.com/scala/improvement-proposals/blob/main/sip-template.md) as a starting point, and for various examples, including syntax highlighting of code snippets. diff --git a/_sips/sips/2009-06-02-early-member-definitions.md b/_sips/sips/2009-06-02-early-member-definitions.md deleted file mode 100644 index 3b4847be44..0000000000 --- a/_sips/sips/2009-06-02-early-member-definitions.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: sip -title: SID-4 - Early Member Definitions -vote-status: complete -vote-text: This SIP has already been accepted and completed. -permalink: /sips/:title.html -redirect_from: /sips/pending/early-member-definitions.html ---- - -This was an older SID that can be found [here](http://www.scala-lang.org/sid/4) diff --git a/_sips/sips/2009-11-02-scala-swing-overview.md b/_sips/sips/2009-11-02-scala-swing-overview.md deleted file mode 100644 index 30cc03d95f..0000000000 --- a/_sips/sips/2009-11-02-scala-swing-overview.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: sip -title: SID-8 - Scala Swing Overview -vote-status: complete -vote-text: This SIP has already been accepted and completed. -permalink: /sips/:title.html -redirect_from: /sips/pending/scala-swing-overview.html ---- - -This was an older SID that can be found [here](http://www.scala-lang.org/sid/8) diff --git a/_sips/sips/2010-01-27-internals-of-scala-annotations.md b/_sips/sips/2010-01-27-internals-of-scala-annotations.md deleted file mode 100644 index 747c9af8b7..0000000000 --- a/_sips/sips/2010-01-27-internals-of-scala-annotations.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: sip -title: SID-5 - Internals of Scala Annotations -vote-status: complete -vote-text: This SIP has already been accepted and completed. -permalink: /sips/:title.html -redirect_from: /sips/pending/internals-of-scala-annotations.html ---- - -This was an older SID that can be found [here](http://www.scala-lang.org/sid/5) diff --git a/_sips/sips/2010-05-06-scala-specialization.md b/_sips/sips/2010-05-06-scala-specialization.md deleted file mode 100644 index 3acdeab4b0..0000000000 --- a/_sips/sips/2010-05-06-scala-specialization.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: sip -title: SID-9 - Scala Specialization -vote-status: complete -vote-text: This SIP has already been accepted and completed. -permalink: /sips/:title.html -redirect_from: /sips/pending/scala-specialization.html ---- - -This was an older SID that can be found [here](http://www.scala-lang.org/sid/9) diff --git a/_sips/sips/2010-07-20-new-collection-classes.md b/_sips/sips/2010-07-20-new-collection-classes.md deleted file mode 100644 index 4144a639b8..0000000000 --- a/_sips/sips/2010-07-20-new-collection-classes.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: sip -title: SID-3 - New Collection classes -vote-status: complete -vote-text: This SIP has already been accepted and completed. -permalink: /sips/:title.html -redirect_from: /sips/pending/new-collection-classes.html ---- - -This was an older SID that can be found [here](http://www.scala-lang.org/sid/3) diff --git a/_sips/sips/2011-10-13-uncluttering-control.md b/_sips/sips/2011-10-13-uncluttering-control.md deleted file mode 100644 index 5f4dea8d64..0000000000 --- a/_sips/sips/2011-10-13-uncluttering-control.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -layout: sip -title: SIP-12 - Uncluttering Scala’s syntax for control structures. - -vote-status: rejected -vote-text: The committee votes unanimously to reject the change. The conclusion is that there is not a clear benefit for it and the required invested time and efforts would be too high. For more explanation, read the minutes. -permalink: /sips/:title.html -redirect_from: /sips/pending/uncluttering-control.html ---- - -**By: Martin Odersky** - -## Motivation ## - -The more Scala code I write the more I get tripped up by the need to write conditions in if-then-else expressions and other control constructs in parentheses. I normally would not advocate syntax changes at this level, except that this has been the single syntax decision that feels worse for me the longer I use it. - -## Part 1: if ## - -Having to write parentheses is an unfortunate inheritance from C via Java. It makes code more cluttered than it could be. In C/C++/Java this was no big deal, but because Scala is much cleaner syntactically than these languages it starts to stick out like a sore thumb. This in particular because only one form of `if` comes with parentheses; if you use an if as a filter in a for expression or as a guard in a pattern, no parentheses are required. - -So, here is the proposal (for Scala 2.10): - -1. Introduce a new keyword, `then`. - -2. Allow the following alternative syntax form: - - if expression then expression [else expression] - -3. At some point in the future (there’s no rush) we could deprecate the form - - if (expression) expression else expression - - and then remove it. - - -Once we have dealt with if, we should do the same thing with while, do-while and for. - -## Part 2: do-while ## - -do-while is easy. Simply do the following: - -1. Allow - - do expression while expression - - as syntax (i.e. drop the required parentheses around the condition). - -While loops and for loops are more tricky. - -## Part 3: while ## - -For while loops: - -1. Allow - - while expression do expression - - as syntax.We then have to deal with an ambiguity: What should we do with - - while (expression1) do expression2 while (expression3) - - ? I.e. a `do-while` loop inside an old-style `while` loop? Here’s a possible migration strategy. - -2. In Scala 2.10: Introduce - - while expression1 do expression2 - - where `expression1` is not allowed to have parentheses at the outermost level (there’s no need to have them anyway). Also, emit a deprecation warning if the compiler comes across a do-while nested directly in an old-style while: - - while (expression1) do expression2 while expression3 - - To write a `do-while` inside a `while` loop you will need braces, like this: - - while (expression1) { do expression2 while epression3 } - -3. In Scala 2.11: Disallow - - while (expression1) do expression2 while expression3 - -4. In Scala 2.12: Drop the restriction introduced in 2.10. Conditions in a `while-do` can now be arbitrary expressions including with parentheses at the outside. - -## Part 4: for ## - -For-loops and for expressions can be handled similarly: - -1. Allow - - for enumerators yield expression - - as syntax. Enumerators are treated as if they were in braces, i.e. newlines can separate generators without the need for additional semicolons. - -2. Allow - - for enumerators do expression - - as syntax. Treat `do-while` ambiguities as in the case for `while`. - -3. At some point in the future: deprecate, and then drop the syntax - - for (enumerators) expression - for {enumerators} expression - for (enumerators) yield expression - for {enumerators} yield expression - -## Examples ## - -Here are some examples of expressions enabled by the changes. - - if x < y then x else y - - while x >= y do x /= 2 - - for x <- 1 to 10; y <- 1 to 10 do println(x * y) - - for - x <- 0 until N - y <- 0 until N - if isPrime(x + y) - yield (x, y) - -## Discussion ## - -The new syntax removes more cases than it introduces. It also removes several hard to remember and non-orthogonal rules where you need parentheses, where you can have braces, and what the difference is. It thus makes the language simpler, more regular, and more pleasant to use. Some tricky situations with migration can be dealt with; and should apply anyway only in rare cases. diff --git a/_sips/sips/2012-03-09-self-cleaning-macros.md b/_sips/sips/2012-03-09-self-cleaning-macros.md deleted file mode 100644 index 32d50df49f..0000000000 --- a/_sips/sips/2012-03-09-self-cleaning-macros.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: sip -title: SIP-16 - Self-cleaning Macros - -vote-status: rejected -vote-text: The proposal is rejected unanimously because Scala Meta, the successor metaprogramming tool, is coming soon. For more explanation, read the minutes. -permalink: /sips/:title.html -redirect_from: /sips/pending/self-cleaning-macros.html ---- - - -This SIP is an embedded google document. If you have trouble with this embedded document, you can visit the [document on Google Docs](https://docs.google.com/document/d/1O879Iz-567FzVb8kw6N5OBpei9dnbW0ZaT7-XNSa6Cs/edit?hl=en_US). - - diff --git a/_sips/sips/2012-03-30-source-locations.md b/_sips/sips/2012-03-30-source-locations.md deleted file mode 100644 index a326ebbd1b..0000000000 --- a/_sips/sips/2012-03-30-source-locations.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-19 - Implicit Source Locations - -vote-status: rejected -vote-text: The proposal is rejected. We expect this to be easily implemented using macros without going through a full SIP. A modern implementation can be found here. -permalink: /sips/:title.html -redirect_from: /sips/pending/source-locations.html ---- - -**Philipp Haller** - -**30 March 2012** - -## Motivation ## - -The Scala compiler's error messages would be nearly useless if they wouldn't provide the corresponding source location, that is, file name, line number, and (some representation of the) character offset, of each error. However, source locations are also very useful outside of the compiler. Libraries and frameworks routinely deal with application- or system-level errors (usually in the form of exceptions), logging, debugging support through tracing, etc. All of these aspects greatly benefit from source location information. - -Moreover, embedded domain-specific languages often depend upon source location information for providing useful error messages. Domain-specific languages that employ staging for code generation can use source locations for debug information in the generated code. - -This proposal discusses a minimal extension of Scala's implicit parameters to provide access to the source location of method invocations. The design is analogous to the way manifests are generated by the compiler, and should therefore be natural to anyone familiar with manifests in Scala. - -## Example ## - -To obtain the source location for each invocation of a method `debug`, say, one adds an implicit parameter of type `SourceLocation`: - - def debug(message: String)(implicit loc: SourceLocation): Unit = { - println("@" + loc.fileName + ":" + loc.line + ": " + message) - } - -This means that inside the body of the `debug` method, we can access the source location of its current invocation through the `loc` parameter. For example, suppose -we are invoking `debug` on line `34` in a file `"MyApp.scala"`: - - 34: if (debugEnabled) debug("debug message") - -Assuming `debugEnabled` evaluates to `true`, the above expression would lead to the following output: - - @MyApp.scala:34: debug message - -## The SourceLocation Trait ## - -The `SourceLocation` trait is a new type member of the `scala.reflect` package. It has the following members: - - trait SourceLocation { - /** The name of the source file */ - def fileName: String - - /** The line number */ - def line: Int - - /** The character offset */ - def charOffset: Int - } - -## Specification ## - -Implicit source locations are supported through the following small addition to Scala's implicit rules. - -If an implicit parameter of a method or constructor is of type `SourceLocation`, a source location object is determined according to the following rules. - -First, if there is already an implicit argument of type `SourceLocation`, this argument is selected. Otherwise, an instance of `SourceLocation` is generated by invoking the `apply` method of the object `scala.reflect.SourceLocation`, passing the components of the source location as arguments. - -## Implementation ## - -An implementation of this proposal can be found at: [https://github.com/phaller/scala/tree/topic/source-location](https://github.com/phaller/scala/tree/topic/source-location) - -An extension of this proposal is also part of Scala-Virtualized. The extension adds a subtrait `SourceContext` which in addition provides access to information, such as variable names in the context of a method invocation. More information can be found at: [https://github.com/TiarkRompf/scala-virtualized/wiki/SourceLocation-and-SourceContext](https://github.com/TiarkRompf/scala-virtualized/wiki/SourceLocation-and-SourceContext) diff --git a/_sips/sips/2013-05-31-improved-lazy-val-initialization.md b/_sips/sips/2013-05-31-improved-lazy-val-initialization.md deleted file mode 100644 index b3fc711ced..0000000000 --- a/_sips/sips/2013-05-31-improved-lazy-val-initialization.md +++ /dev/null @@ -1,751 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-20 - Improved Lazy Vals Initialization - -vote-status: dormant -vote-text: This proposal lacks an implementation for Scalac and is looking for a new owner. -permalink: /sips/:title.html -redirect_from: /sips/pending/improved-lazy-val-initialization.html ---- - -**By: Aleksandar Prokopec, Dmitry Petrashko, Miguel Garcia, Jason Zaugg, Hubert Plociniczak, Viktor Klang, Martin Odersky** - - -## Abstract ## - -This SIP describes the changes in the lazy vals initialization mechanism that address some of the unnecessary deadlock scenarios. The newly proposed lazy val initialization mechanism aims to eliminate the acquisition of resources during the execution of the lazy val initializer block, thus reducing the possibility of a deadlock. The concrete deadlock scenarios that the new lazy val initialization scheme eliminates are summarized below. - -The changes in this SIP have previously been discussed in depth on the mailing lists \[[1][1]\] \[[2][2]\] \[[9][9]\] \[[10][10]\]. - - -## Description ## - -The current lazy val initialization scheme uses double-checked locking to initialize the lazy val only once. A separate volatile bitmap field is used to store the state of the lazy val - a single bit in this bitmap denotes whether the lazy val is initialized or not. -Assume we have the following declaration. - - final class LazyCell { - lazy val value = - } - -Here is an example of a manually written implementation equivalent to what the compiler currently does: - - final class LazyCell { - @volatile var bitmap_0: Boolean = false - var value_0: Int = _ - private def value_lzycompute(): Int = { - this.synchronized { - if (!bitmap_0) { - value_0 = - bitmap_0 = true - } - } - value_0 - } - def value = if (bitmap_0) value_0 else value_lzycompute() - } - -We now describe several deadlock scenarios in an attempt to classify deadlocks related to the current lazy val initialization implementation. - -### No circular dependencies ### - -Assume there are two objects A and B with lazy vals `a0` and `a1`, and `b`, respectively: - - object A { - lazy val a0 = B.b - lazy val a1 = 17 - } - - object B { - lazy val b = A.a1 - } - -The initialization block of `a0` above refers to `b` in B, and the initialization of `B.b` refers to `A.a1`. While a circular dependency exists between these two objects, there is no circular dependency **between specific lazy vals** `a0`, `a1` and `b`. - -In the scheme, there exists a possibility of a deadlock if thread Ta attempts to initialize `A.a0` and thread Tb attempts to initialize `B.b`. Assume that both Ta and Tb start their synchronized blocks simultaneously. A deadlock can occur due to each thread trying to grab the lock of the other object, while holding their own lock until the initialization completes. - -This SIP attempts to address this issue. - -### Circular dependencies ### - -Assume there are two objects A and B with lazy vals `a` and `b` respectively, where `a` needs `b` for initialization and vice versa. The current implementation scheme can cause a deadlock in this situation. Furthermore: in a single threaded scenario, circular dependencies between lazy vals lead to stack overflows with the current implementation: - - scala> object Test { - | object A { lazy val a: Int = B.b } - | object B { lazy val b: Int = A.a } - | } - defined object Test - - scala> Test - res0: Test.type = Test$@6fd1046d - - scala> Test.A.a - java.lang.StackOverflowError - -This is considered erroneous code, and this SIP does not attempt to address this. - -### No circular dependencies with other synchronization constructs ### - -Consider the declaration of the following lazy val: - - class A { self => - lazy val x: Int = { - val t = new Thread() { - override def run() { self.synchronized {} } - } - t.start() - t.join() - 1 - } - } - -In the source there appears to be no circular dependency between the lazy val initialization block and the other synchronization construct, so there should be no reason for deadlock. As long as thread `t` completes a condition that the caller depends on and eventually lets go of the current object `self`, the lazy val should be able to initialize itself. - -With the current initialization scheme, however, initializing `x` causes a deadlock. The calling thread initializing `x`, holds the monitor of the current object `self`. The same monitor is needed by thread `t`, since it also synchronizes on `self`, thus causing a deadlock. - -This SIP attempts to address this issue. - -The thread that fulfills the condition that the lazy val initializer block suspends on could on the other hand permanently grab a hold of the monitor of the `self` object. Although this is not strictly speaking a deadlock, it is worth mentioning that the current lazy val initialization implementation might not complete in the following scenario case. - - class A { self => - val latch = new java.util.concurrent.CountDownLatch(1) - val t = new Thread() { - override def run() { - latch.countDown() - self.synchronized { while (true) {} } - } - } - t.start() - lazy val x: Int = { - latch.await() - 1 - } - x - } - -This SIP does not attempt to solve this issue - lazy val initialization semantics assume that the `self` object monitor is available or can be made available throughout the lazy val initialization. - -### Circular dependencies with other synchronization constructs ### - -Consider the declaration of the following lazy val: - - lazy val x: Int = { - val t = new Thread() { - override def run() { println(x) } - } - t.start() - t.join() - 1 - } - -In this code, the lazy val initialization block suspends until a condition is fulfilled. This condition can only be fulfilled by reading the value of lazy val `x` - another thread that is supposed to complete this condition cannot do so. Thus, a circular dependency is formed, and the lazy val cannot be initialized. Similar problems can arise with Scala singleton object initialization \[[3][3]\] when creating threads from the singleton object constructor and waiting for their completion, and with static initializer blocks in Java \[[4][4]\] \[[5][5]\]. - -Note that this problem can also happen if two separate threads try to initialize two singleton objects that refer to each other, which is somewhat more severe. The rule of the thumb for programmers should be - singleton objects should not refer to each other during initialization. - -This is considered an anti-pattern, and this SIP does not attempt to address these issues. - -## Implementation ## - -The solution to the problems that this SIP attempts to address is based on avoiding the acquisition of the current object monitor during the time that the lazy val initializer block executes. Instead of executing the initializer block from within a synchronized block, the synchronized block is run twice, once at the beginning to publicize the information that the initializer block is being run and once after the initializer block to publicize the information that the lazy val field has been computed and assigned. The new scheme will require maintaining 2 bits per lazy field instead of 1, as in the current implementation. -We will refer to the existing, current lazy val initialization implementation as V1. - -### Version V2 ### - -Here is an example of manually written implementation for the `LazyCell` class from the previous section: - - class LazyCell { - @volatile var bitmap_0: Int = 0 - var value_0: Int = _ - private def value_lzycompute(): Int = { - this.synchronized { - if (bitmap_0 == 0) { - bitmap_0 = 1 - } else { - while (bitmap_0 == 1) { - this.wait() - } - return value_0 - } - } - val result = - this.synchronized { - value_0 = result - bitmap_0 = 3 - this.notifyAll() - } - value_0 - } - def value = if (bitmap_0 == 3) value_0 else value_lzycompute() - } - -The state of the lazy val is represented with 3 values: 0, 1 and 3. Note that only 2 bits are sufficient to represent them but we use an entire integer here for purposes of clarity. The state 0 represents a non-initialized lazy val. The state 1 represents the lazy val that is currently being initialized by some thread. The state 3 represents the lazy val that has been initialized. - -The first-arriving thread sets the state 1 from the synchronized block, leaves the synchronized block and proceeds by executing the initializer block. Subsequently arriving threads enter the synchronized block, see state 1 and `wait` until they are notified that the lazy val has been assigned. The first-arriving thread sets the state to 3 and notifies them after it computes the result and enters the second synchronized block. - -### Version V3 - the `notifyAll` improvement ### - -As noted in the previous discussions \[[1][1]\] \[[2][2]\] \[[6][6]\] \[[7][7]\], the `notifyAll` call in the proposed implementation bears a significant cost - in the uncontended case it slows down the initialization by a factor of at least 4x measured on a 3.4 GHz i7-2600 and JDK 7 update 4. - -Therefore, we propose the following implementation that avoids calling `notifyAll` unless the first-arriving thread knows that there are concurrent readers of the lazy val. We introduce the fourth state corresponding to the bitmap value 2, that denotes that there are concurrent readers of the lazy val. The first-arriving thread only calls the `notifyAll` if it finds state 2 in the second synchronized block. - - class LazyCell { - @volatile var bitmap_0 = 0 - var value_0: Int = _ - private def value_lzycompute(): Int = { - this.synchronized { - (bitmap_0: @annotation.switch) match { - case 0 => - bitmap_0 = 1 - case 1 => - bitmap_0 = 2 - do this.wait() while (bitmap_0 == 2.toByte) - return value_0 - case 2 => - do this.wait() while (bitmap_0 == 2.toByte) - return value_0 - case 3 => - return value_0 - } - } - val result = - this.synchronized { - val oldstate = bitmap_0 - value_0 = result - bitmap_0 = 3 - if (oldstate == 2) this.notifyAll() - } - value_0 - } - def value = if (bitmap_0 == 3) value_0 else value_lzycompute() - } - -Measured on the same machine, this change seems to be 50% slower than the current lazy val implementation for the uncontended case. - -### Version V4 - the CAS improvement ### - -Each exit or entrance to a synchronized block in principle requires one atomic instruction, amounting to roughly 4 atomic instructions per lazy val initialization. This can be reduced by using the CAS instruction to switch between lazy val states. -Here is an example of a simple implementation obtained by extending the `AtomicInteger` class: - - class LazyCell - extends java.util.concurrent.atomic.AtomicInteger { - var value_0: Int = _ - @tailrec final def value(): Int = (get: @switch) match { - case 0 => - if (compareAndSet(0, 1)) { - val result = - value_0 = result - if (getAndSet(3) != 1) synchronized { notify() } - result - } else value() - case 1 => - compareAndSet(1, 2) - synchronized { - while (get != 3) wait() - notify() - } - value_0 - case 2 => - synchronized { - while (get != 3) wait() - notify() - } - value_0 - case 3 => value_0 - } - } - -This implementation has the following advantages: -- it seems to have the same initialization performance as the current implementation, in the uncontended case -- it relies less on synchronized blocks, needing them only in case of contention, thus being less prone to deadlocks - -Some disadvantages: -- we cannot always extend `AtomicInteger`, some classes already inherit something else -- in the contended worst-case, this scheme is equally prone to deadlocks, because it needs to acquire the synchronized block - -However, in the more general setting where there are two or more lazy val fields in an object: -- the overall memory footprint could possibly increase - we would spend a minimum of 4 bytes per bitmap on first lazy val, where this was previously 1 byte -- in a setting with multiple bitmaps or an existing base class, we cannot extend `AtomicInteger` (which internally uses `Unsafe` directly), and instead need to use `AtomicIntegerFieldUpdater`s that are slower due to extra checks -- in a setting with multiple lazy val fields, we can no longer use `getAndSet` in the initialization (concurrent accesses to other lazy fields may modify the bitmap - we have to read and recompute the expected bitmap state) - we need a `compareAndSet` and have some retry-logic (see the `complete` method below), which is slower -- due to the restrictions on the `AtomicIntegerFieldUpdater`s, we would need to make the `bitmap_0` field publicly visible on the byte-code level, which might be an issue for Java code interfacing with Scala code -- it is much more complicated than the 2 synchronized blocks implementation - -Here is a more general implementation(V4-general), that is slower in the uncontended case than both the current implementation (V1) and the proposed implementation with synchronized blocks (V3). This implementation is, however, in the contended case twice as fast than the current implementation (V1). -See the evaluation section for more information. - - class LazyCellBase { // in a Java file - we need a public bitmap_0 - public static AtomicIntegerFieldUpdater arfu_0 = - AtomicIntegerFieldUpdater.newUpdater(LazyCellBase.class, "bitmap_0"); - public volatile int bitmap_0 = 0; - } - - final class LazyCell extends LazyCellBase { - import LazyCellBase._ - var value_0: Int = _ - @tailrec final def value(): Int = (arfu_0.get(this): @switch) match { - case 0 => - if (arfu_0.compareAndSet(this, 0, 1)) { - val result = - value_0 = result - - @tailrec def complete(): Unit = (arfu_0.get(this): @switch) match { - case 1 => - if (!arfu_0.compareAndSet(this, 1, 3)) complete() - case 2 => - if (arfu_0.compareAndSet(this, 2, 3)) { - synchronized { notifyAll() } - } else complete() - } - - complete() - result - } else value() - case 1 => - arfu_0.compareAndSet(this, 1, 2) - synchronized { - while (arfu_0.get(this) != 3) wait() - } - value_0 - case 2 => - synchronized { - while (arfu_0.get(this) != 3) wait() - } - value_0 - case 3 => value_0 - } - } - - -### Version 5 - retry in case of failure ### - -The current Scala semantics demand retrying the initialization in case of failure. -The four versions presented above provide good performance characteristics in benchmarks, but may leave threads waiting forever due to failed initializations, thus leaking threads. Consider this example: - - class LazyCell { - private var counter = -1 - lazy val value = { - counter = counter + 1 - if(counter < 42) - throw null - else 0 - } - } - -In this case, the first attempt to initialize the cell would fail. In version 4 this will leave the bitmap with a value still indicating that there's a thread currently computing the value. All the threads trying to access the value would wait for this (non-existent) thread to finish computation, causing the application to leak threads. - -In order to maintain current Scala semantics, we need to correctly handle failed initializations. Version 5 presented below, does this correctly: - - - class LazyCellBase { // in a Java file - we need a public bitmap_0 - public static AtomicIntegerFieldUpdater arfu_0 = - AtomicIntegerFieldUpdater.newUpdater(LazyCellBase.class, "bitmap_0"); - public volatile int bitmap_0 = 0; - } - - final class LazyCell extends LazyCellBase { - import LazyCellBase._ - var value_0: Int = _ - @tailrec final def value(): Int = (arfu_0.get(this): @switch) match { - case 0 => - if (arfu_0.compareAndSet(this, 0, 1)) { - val result = - try {} catch { - case x: Throwable => - complete(0); - throw x - } - value_0 = result - - @tailrec def complete(newState: Int): Unit = (arfu_0.get(this): @switch) match { - case 1 => - if (!arfu_0.compareAndSet(this, 1, newState)) complete() - case 2 => - if (arfu_0.compareAndSet(this, 2, newState)) { - synchronized { notifyAll() } - } else complete() - } - - complete(3) - result - } else value() - case 1 => - arfu_0.compareAndSet(this, 1, 2) - synchronized { - while (arfu_0.get(this) != 3) wait() - } - value_0 - case 2 => - synchronized { - while (arfu_0.get(this) != 3) wait() - } - value_0 - case 3 => value_0 - } - } - -This version is basically the same as Version 4, but it handles retries in accordance with current Scala specification. -Unfortunately, this comes with a slight performance slowdown. See the evaluation section for more information. - - -### Version 6 - No synchronization on `this` and concurrent initialization of fields ### - -Note that the current lazy val initialization implementation is robust against the following scenario, in which the initialization block starts an asynchronous computation attempting to indefinitely grab the monitor of the current object. - - class A { self => - lazy val x: Int = { - (new Thread() { - override def run() = self.synchronized { while (true) {} } - }).start() - 1 - } - } - -In the current implementation, the monitor is held throughout the lazy val initialization and released once the initialization block completes. -All versions proposed above, release the monitor during the initialization block execution and re-acquire it back, so the code above could stall indefinitely. - -Additionally, usage of `this` as synchronization point may disallow concurrent initialization of different lazy vals in the same object. Consider the example below: - - class TwoLazies { - lazy val slow = { Thread.sleep(100000); 0} - lazy val fast = 1 - lazy val bad: Int = { - (new Thread() { - override def run() = self.synchronized { while (true) {} } - }).start() - 1 - } - } - -Although the two `slow` and `fast` vals are independent, `fast` is required to -wait for `slow` to be computed. This is due to the fact that they both -synchronize on `this` for the entire initialization in the current -implementation. - -In the versions presented above, a single call to `bad` may lead to the monitor -for `this` being held forever, making calls to `slow` and `fast` also block -forever. - -Note that these interactions are very surprising to users as they leak the -internal limitations of the lazy val implementation. - -To overcome these limitations we propose a version that does not synchronize on -`this` and instead uses external monitor-objects that are used solely for -synchronization. - - final class LazyCell { - import dotty.runtime.LazyVals - var value_0: Int = _ - private var bitmap = 0 - @static private bitmap_offset = LazyVals.getOffset(classOf[LazyCell], "bitmap") - def value(): Int = { - var result: Int = 0 - var retry: Boolean = true - val fieldId: Int = 0 // id of lazy val - var flag: Long = 0L - while retry do { - flag = LazyVals.get(this, bitmap_offset) - LazyVals.STATE(flag, 0) match { - case 0 => - if LazyVals.CAS(this, bitmap_offset, flag, 1) { - try {result = } catch { - case x: Throwable => - LazyVals.setFlag(this, bitmap_offset, 0, fieldId) - throw x - } - value_0 = result - LazyVals.setFlag(this, bitmap_offset, 3, fieldId) - retry = false - } - case 1 => - LazyVals.wait4Notification(this, bitmap_offset, flag, fieldId) - case 2 => - LazyVals.wait4Notification(this, bitmap_offset, flag, fieldId) - case 3 => - retry = false - result = $target - } - } - result - } - } - -This implementation relies on the helper functions provided in \[[11][11]\] -module. The most important of these functions, `wait4Notification` and -`setFlag`, are presented below: - - def setFlag(t: Object, offset: Long, v: Int, fieldId: Int) = { - var retry = true - while (retry) { - val cur = get(t, offset) - if (STATE(cur) == 1) retry = CAS(t, offset, cur, v) - else { - // cur == 2, somebody is waiting on monitor - if (CAS(t, offset, cur, v)) { - val monitor = getMonitor(t, fieldId) - monitor.synchronized { - monitor.notifyAll() - } - retry = false - } - } - } - } - - def wait4Notification(t: Object, offset: Long, cur: Long, fieldId: Int) = { - var retry = true - while (retry) { - val cur = get(t, offset) - val state = STATE(cur) - if (state == 1) CAS(t, offset, cur, 2) - else if (state == 2) { - val monitor = getMonitor(t, fieldId) - monitor.synchronized { - monitor.wait() - } - } - else retry = false - } - } - - val processors: Int = java.lang.Runtime.getRuntime.availableProcessors() - val base: Int = 8 * processors * processors - val monitors: Array[Object] = (0 to base).map { - x => new Object() - }.toArray - - def getMonitor(obj: Object, fieldId: Int = 0) = { - var id = (java.lang.System.identityHashCode(obj) + fieldId) % base - if (id < 0) id += base - monitors(id) - } - -This implementation has the following advantages compared to previous version: -- it allows concurrent initialization of independent fields -- it does not interact with user-written code that synchronizes on `this` -- it does not require expanding monitor on the object to support `notifyAll` - -Some disadvantages: -- the `Unsafe` class, used internally has a disadvantage that it can be disallowed with a custom `SecurityManager`. -Note that this class is extracted from other place in standard library that uses it: scala.concurrent.util.Unsafe.instance -- it requires usage of `identityHashCode` that is stored for every object inside object header. -- as global arrays are used to store monitors, seemingly unrelated things may create contention. This is addressed in detail in evaluation section. - -Both absence of monitor expansion and usage of `idetityHashCode` interact with -each other, as both of them operate on the object header. \[[12][12]\] presents -the complete graph of transitions between possible states of the object header. -What can be seen from this transition graph is that in the contended case, -versions V2-V5 were promoting object into the worst case, the `heavyweight -monitor` object, while the new scheme only disables biasing. - -Note that under the schemes presented here, V2-V5, this change only happens in -the event of contention and happens per-object. - -### Non-thread-safe lazy vals ### -While the new versions introduce speedups in the contended case, they do -generate complex byte-code and this may lead to the new scheme being less -appropriate for lazy vals that are not used in concurrent setting. In order to -perfectly fit this use-case we propose to introduce an encoding for -single-threaded lazy vals that is very simple and efficient: - - final class LazyCell { - var value_0 = 0 - var flag = false - def value = - if (flag) value_0 - else { - value_0 = ; - flag = true; - } - } - -This version is faster than all other versions on benchmarks but does not correctly handle safe publication in the case of multiple threads. It can be used in applications that utilize multiple threads if some other means of safe publication is used instead. - -### Elegant Local lazy vals ### -Aside from lazy vals that are fields of objects, scala supports local lazy vals, defined inside methods: - - def method = { - lazy val s = - s - } - -Currently, they use such encoding(we will call it L1): - - def method = { - var @volatile flag: Byte = 0.toByte - var s_0 = 0 - def s = { - if(flag == 0){ - this.synchronized{ - if (flag == 0) { - s_0 = - flag = 1 - } - } - s_0 - } - s - } - -Which is later translated by subsequent phases to: - - private def method$s(flag: VolatileByteRef, s_0: IntRef) = { - if(flag.value == 0){ - this.synchronized{ - if (flag.value == 0) { - s_0.value = - flag.value = 1 - } - } - s_0.value - } - - def method = { - var flag = new VolatileByteRef(0) - var s_0 = new IntRef(0) - method$s(flag, s_0) - } - - - -The current implementation has several shortcomings: - - it allocates two boxes - - it synchronizes on `this`. This is most severe in case of lambdas, as lambdas do not introduce a new `this`. - -We propose a new scheme, that is both simpler in implementation and is more efficient and slightly more compact. -The scheme introduces new helper classes to the standard library: such as `dotty.runtime.LazyInt`\[[17][17]\] and uses them to implement the local lazy val behavior. - - class LazyInt { - var value: Int = _ - @volatile var initialized: Boolean = false - } - - private def method$s(holder: LazyInt) = { - if(!holder.initialized){ - holder.synchronized{ - if (!holder.initialized) { - holder.value = - holder.initialized = true - } - } - holder.value - } - - def method = { - var holder = new LazyInt() - method$s(holder) - } - -This solves the problem with deadlocks introduced by using java8 lambdas.\[[14][14]\] - - -### Language change ### -To address the fact that we now have both thread safe and single-threaded lazy vals, -we propose to bring lazy vals in sync with normal vals with regards to usage of `@volatile` annotation. - -In order to simplify migration, Scalafix the migration tool that will be used to migrate between versions of Scala, including Dotty, supports a `VolatileLazyVal` rewrite that adds `@volatile` to all `lazy vals` present in the codebase. - - -## Evaluation ## - -We focus on the memory footprint increase, the performance comparison and byte-code size. Note that the fast path (i.e. the cost of accessing a lazy val after it has been initialized) stays the same as in the current implementation. Thus, the focus of our measurements is on the overheads in the lazy val initialization in both the uncontended and the contended case. -The micro-benchmarks used for evaluation are available in a GitHub repo \[[6][6]\] and the graphs of the evaluation results are available online \[[7][7]\], \[[18][18]\], \[[19][19]\] . We used the ScalaMeter tool for measurements \[[9][9]\]. - -### Memory usage footprint ### - -We expect that the proposed changes will not change the memory footprint for most objects that contain lazy vals. Each lazy val currently requires 4 or 8 bytes for the field, and an additional bit in the bitmap. As soon as the first bit is introduced into the bitmap, 1 additional byte is allocated for the object. - -Since we now use 2 bits per lazy val field instead of 1, for classes having 4 or less lazy val field declarations the memory footprint per instance will thus not grow. For classes having more lazy val field declarations the memory footprint per instance will in most cases not grow since the objects have to be aligned to an 8 byte boundary anyway. - -We measured the memory footprint of an array of objects with single lazy val fields. The memory footprint did not change with respect to the current version \[[6][6]\] \[[7][7]\]. -The detailed experimental measurements graphs of memory footprint can be seen in graphs.\[[18][18]\] - -### Performance ### - -We measured performance in both the uncontended and the contended case. We measured on an i7-2600, a 64-bit Oracle JVM, version 1.7 update 4. - -For the uncontended case, we measure the cost of creating N objects and initializing their lazy val fields. The measurement includes both the object creation times and their initialization, where the initialization is the dominant factor. - -For the contended case, we measure the cost of initializing the lazy fields of N objects, previously created and stored in an array, by 4 different threads that linearly try to read the lazy field of an object before proceeding to the next one. The goal of this test is to asses the effect of entering the synchronized block and notifying the waiting threads - since the slow path is slower, the threads that “lag” behind should quickly reach the first object with an uninitialized lazy val, causing contention. - -The current lazy val implementation (V1) seems to incur initialization costs that are at least 6 times greater compared to referencing a regular val. The handwritten implementation produces identical byte-code, with the difference that the calls are virtual instead of just querying the field value; this is probably the reason as to why it is up to 50% slower. The 2 synchronized blocks design with an eager notify (V2) is 3-4 times slower than the current implementation - just adding the `notifyAll` call changes things considerably. The 4 state/2 synchronized blocks approach (V3) is only 33-50% slower than the current implementation (V1). The CAS-based approach where `AtomicInteger`s are extended is as fast as the current lazy val initialization (V1), but when generalized and replaced with `AtomicReferenceFieldUpdater`s as discussed before, it is almost 50% slower than the current implementation (V1). The final version, V6 uses `Unsafe` to bring back performance and is as around twice as fast as current implementation (V1) while maintaining correct semantics. - -The CAS-based approaches (V4, V5 and V6) appear to offer the best performance here, being twice as fast than the current implementation (V1). - -The proposed solution with (V6) is 50% faster\[[19][19]\] than the current lazy val implementation in the contended case. This comes at a price of synchronizing on a global array of monitors, which may create contention between seemingly unrelated things. The more monitors that are created, the less is the probability of such contention. There's also a positive effect though, the reuse of global objects for synchronization allows the monitors on the instances containing lazy vals to not be expanded, saving on non-local memory allocation. The current implementation uses `8 * processorCount * processorCount` monitors and the benchmarks and by-hand study with "Vtune Amplifier XE" demonstrate that the positive effect dominates, introducing a 2% speedup\[[13][13]\]. It’s worth mentioning that this is not a typical use-case that reflects a practical application, but rather a synthetic edge case designed to show the worst-case comparison demonstrating cache contention. - -The local lazy vals implementation is around 6x faster than the current version, as it eliminates the need for boxing and reduces the number of allocations from 2 to 1. - -The concrete micro-benchmark code is available as a GitHub repo \[[6][6]\]. It additionally benchmarks many other implementations that are not covered in the text of this SIP, in particular it tests versions based on MethodHandles and runtime code generation as well as versions that use additional spinning before synchronizing on the monitor. -For those wishing to reproduce the results, the benchmarking suite takes 90 minutes to run on contemporary CPUs. Enabling all the disabled benchmarks, in particular those that evaluate the `invokeDynamic` based implementation, will make the benchmarks take around 5 hours. - -The final result of those benchmarks is that amount proposed versions, the two that worth considering are (V4-general) and (V6). -They both perform better than the current implementation in all the contended case. -Specifically, in the contended case, V6 is 2 times fater than V1, while V4-general is 4 times faster. -Unfortunately V4-general is 30% slower in the uncontended case than current implementation(V1), while V6 is in the same ballpark, being up to 5% slower or faster depending on the setup of the benchmark. - -Based on this, we propose V6 to be used as default in future versions of Scala. - -### Code size ### -The versions presented in V2-V6 have a lot more complex implementation and this shows up the size of the byte-code. In the worst-case scenario, when the `` value is a constant, the current scheme (V1) creates an initializer method that has a size of 34 bytes, while dotty creates a version that is 184 bytes long. Local optimizations present in dotty linker\[[14][14]\] are able to reduce this size down to 160 bytes, but this is still substantially more than the current version. - -On the other hand, the single-threaded version does not need separate initializer method and is around twice smaller than the current scheme (V1). - -The proposed local lazy val transformation scheme also creates less byte-code, introducing 34 bytes instead of 42 bytes, mostly due to reduction in constant table size. - -## Current status ## -Version V6 is implemented and used in Dotty, together with language change that makes lazy vals thread-unsafe if `@volatile` annotation is not specified. -Dotty implementation internally uses `@static` proposed in \[[16][16]\]. - -Both Dotty and released Scala 2.12 already implement "Elegant Local lazy vals". This was incorporated in the 2.12 release before this SIP was considered, as it was fixing a bug that blocked release\[[14][14]\]. - -### Unsafe ### -The proposed version, V6 relies on `sun.misc.Unsafe` in order to implement it's behaviour. -While `sun.misc.Unsafe` will remain availabe in Java9 there's an intention to deprecate it and replace it with VarHandles.\[[20][20]\]. -The proposed version V6 can be implemented with using functionality present in Var Handles. - -## Acknowledgements ## - -We would like to thank Peter Levart and the other members of the concurrency-interest mailing list for their suggestions, as well as the members of the scala-internals mailing list for the useful discussions and input. - - -## References ## -1. [Summary of lazy vals discussions, Scala Internals Mailing list, May 2013][1] -2. [The cost of `notifyAll`, Concurrency Interest Mailing List, May 2013][2] -3. [Scala Parallel Collection in Object Initializer Causes a Program to Hang][3] -4. [Program Hangs If Thread Is Created In Static Initializer Block][4] -5. [Java Language Specification, 12.4.2][5] -6. [GitHub Repo with Microbenchmarks][6] -7. [Uncontended Performance Evaluation Results][7] -8. [ScalaMeter GitHub Repo][8] -9. [Lazy Vals in Dotty, Scala Internals Mailing list, February 2014][9] -10. [Lazy Vals in Dotty, Dotty Internals Mailing list, February 2014][10] -11. [LazyVals runtime module, Dotty sourcecode, February 2014][11] -12. [Synchronization, HotSpot internals wiki, April 2008][12] -13. [Lazy Vals in Dotty, cache contention discussion, February 2014][13] -14. [SI-9824 SI-9814 proper locking scope for lazy vals in lambdas, April 2016][14] -15. [Introducing Scalafix: a migration tool for Scalac to Dotty, October 2016][15] -16. [@static sip, January 2016][16] -17. [LazyVal Holders in Dotty][17] -18. [Memory Footprint Evaluation Results][18] -19. [Contended Performance Evaluation Results][19] -20. [JEP 193: Variable Handles][20] - - [1]: https://groups.google.com/forum/#!topic/scala-internals/cCgBMp5k8R8 "scala-internals" - [2]: http://cs.oswego.edu/pipermail/concurrency-interest/2013-May/011354.html "concurrency-interest" - [3]: http://stackoverflow.com/questions/15176199/scala-parallel-collection-in-object-initializer-causes-a-program-to-hang "pc-object-hang" - [4]: http://stackoverflow.com/questions/7517964/program-hangs-if-thread-is-created-in-static-initializer-block "static-init-hang" - [5]: http://docs.oracle.com/javase/specs/jls/se7/html/jls-12.html#jls-12.4.2 "jls-spec" - [6]: https://github.com/DarkDimius/lazy-val-bench/blob/CallSites/src/test/scala/example/package.scala "lazy-val-bench-code" - [7]: https://d-d.me/tnc/30/lazy-sip-perf/report/#config=%7B%22filterConfig%22%3A%7B%22curves%22%3A%5B%220%22%2C%221%22%2C%225%22%2C%226%22%2C%227%22%2C%228%22%2C%2210%22%2C%2212%22%5D%2C%22order%22%3A%5B%22param-size%22%2C%22date%22%5D%2C%22filters%22%3A%5B%5B%22100000%22%2C%22300000%22%2C%22500000%22%2C%221000000%22%2C%223000000%22%2C%225000000%22%5D%2C%5B%221477397877000%22%5D%5D%7D%2C%22chartConfig%22%3A%7B%22type%22%3A0%2C%22showCI%22%3Afalse%7D%7D "lazy-val-bench-report" - [8]: http://axel22.github.io/scalameter/ "scalameter-code" - [9]: https://groups.google.com/forum/#!msg/scala-internals/4sjw8pcKysg/GlXYDDzCgI0J "scala-internals" - [10]: https://groups.google.com/forum/#!topic/dotty-internals/soWIWr3bRk8 "dotty-internals" - [11]: https://github.com/lampepfl/dotty/blob/5cbd2fbc8409b446f8751792b006693e1d091055/src/dotty/runtime/LazyVals.scala - [12]: https://wiki.openjdk.java.net/display/HotSpot/Synchronization - [13]: https://groups.google.com/d/msg/scala-internals/4sjw8pcKysg/gD0au4dmTAsJ - [14]: https://github.com/scala/scala-dev/issues/133 - [15]: http://scala-lang.org/blog/2016/10/24/scalafix.html - [16]: https://github.com/scala/docs.scala-lang/pull/491 - [17]: https://github.com/lampepfl/dotty/blob/f92f278ab686ab218e841082dcb026c6c8ef89b7/library/src/dotty/runtime/LazyHolders.scala - [18]: https://d-d.me/tnc/30/lazy-mem/report/#config=%7B%22filterConfig%22%3A%7B%22curves%22%3A%5B%22-1%22%2C%220%22%2C%221%22%2C%222%22%2C%223%22%2C%224%22%2C%225%22%2C%226%22%2C%227%22%2C%228%22%5D%2C%22order%22%3A%5B%22param-size%22%2C%22date%22%5D%2C%22filters%22%3A%5B%5B%221000000%22%2C%222000000%22%2C%223000000%22%2C%224000000%22%2C%225000000%22%5D%2C%5B%221477396691000%22%5D%5D%7D%2C%22chartConfig%22%3A%7B%22type%22%3A0%2C%22showCI%22%3Afalse%7D%7D - [19]: https://d-d.me/tnc/30/lazy-sip-perf/report/#config=%7B%22filterConfig%22%3A%7B%22curves%22%3A%5B%2216%22%2C%2217%22%2C%2218%22%2C%2219%22%2C%2221%22%2C%2222%22%2C%2223%22%5D%2C%22order%22%3A%5B%22param-size%22%2C%22date%22%5D%2C%22filters%22%3A%5B%5B%22100000%22%2C%22300000%22%2C%22500000%22%2C%221000000%22%2C%223000000%22%2C%225000000%22%5D%2C%5B%221477397877000%22%5D%5D%7D%2C%22chartConfig%22%3A%7B%22type%22%3A0%2C%22showCI%22%3Afalse%7D%7D - [20]: http://openjdk.java.net/jeps/193 diff --git a/_sips/sips/2013-06-10-spores.md b/_sips/sips/2013-06-10-spores.md deleted file mode 100644 index d182e7d026..0000000000 --- a/_sips/sips/2013-06-10-spores.md +++ /dev/null @@ -1,461 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-21 - Spores - -vote-status: "under-review" -vote-text: Next iteration takes place in January/February 2017 by request of the authors. -permalink: /sips/:title.html -redirect_from: /sips/pending/spores.html ---- - -**By: Heather Miller, Martin Odersky, and Philipp Haller** - -Updated September 15th, 2013 - -  - -Functional programming languages are regularly touted as an enabling force, as -an increasing number of applications become concurrent and distributed. -However, managing closures in a concurrent or distributed environment, or -writing APIs to be used by clients in such an environment, remains -considerably precarious-- complicated environments can be captured by these -closures, which regularly leads to a whole host of potential hazards across -libraries/frameworks in Scala's standard library and its ecosystem. - -Potential hazards when using closures incorrectly: - -- Memory leaks -- Race conditions, due to capturing mutable references -- Runtime serialization errors, due to unintended capture of references - -This SIP outlines an abstraction, called _spores_, which enables safer use of -closures in concurrent and distributed environments. This is achieved by -controlling the environment which a spore can capture. Using an -_assignment-on-capture_ semantics, certain concurrency bugs due to capturing mutable -references can be avoided. - -## Motivating Examples - -### Futures and Akka Actors - -In the following example, an Akka actor spawns a future to concurrently -process incoming requests. - -**Example 1:** - - def receive = { - case Request(data) => - Future { - val result = transform(data) - sender ! Response(result) - } - } - -Capturing `sender` in the above example is problematic, since it does not -return a stable value. It is possible that the future's body is executed at a -time when the actor has started processing the next `Request` message which -could be originating from a different actor. As a result, the `Response` -message of the future might be sent to the wrong receiver. - - -### Serialization - -The following example uses Java Serialization to serialize a closure. However, -serialization fails with a `NotSerializableException` due to the unintended -capture of a reference to an enclosing object. - -**Example 2:** - - case class Helper(name: String) - - class Main { - val helper = Helper("the helper") - - val fun: Int => Unit = (x: Int) => { - val result = x + " " + helper.toString - println("The result is: " + result) - } - } - -Given the above class definitions, serializing the `fun` member of an instance -of `Main` throws a `NotSerializableException`. This is unexpected, since `fun` -refers only to serializable objects: `x` (an `Int`) and `helper` (an instance -of a case class). - -Here is an explanation of why the serialization of `fun` fails: since `helper` -is a field, it is not actually copied when it is captured by the closure. -Instead, when accessing helper its getter is invoked. This can be made -explicit by replacing `helper.toString` by the invocation of its getter, -`this.helper.toString`. Consequently, the `fun` closure captures `this`, not -just a copy of `helper`. However, `this` is a reference to class `Main` which -is not serializable. - -The above example is not the only possible situation in which a closure can -capture a reference to `this` or to an enclosing object in an unintended way. -Thus, runtime errors when serializing closures are common. - -## Basic Usage - -Spores have a few modes of usage. The simplest form is: - - val s = spore { - val h = helper - (x: Int) => { - val result = x + " " + h.toString - println("The result is: " + result) - } - } - -In this example, no transformation is actually performed. Instead, the -compiler simply ensures that the spore is _well-formed_, i.e., anything that's -captured is explicitly listed as a value definition before the spore's -closure. This ensures that the enclosing `this` instance is not accidentally -captured, in this example. - -Spores can also be used in for-comprehensions: - - for { i <- collection - j <- doSomething(i) - } yield s"${capture(i)}: result: $j" - -Here, the fact that a spore is created is implicit, that is, the `spore` -marker is not used explicitly. Spores come into play because the underlying -`map` method of the type of `doSomething(i)` takes a spore as a parameter. The -`capture(i)` syntax is an alternative way of declaring captured variables, in -particular for use in for-comprehensions. - -Finally, a regular function literal can be used as a spore. That is, a method -that expects a spore can be passed a function literal so long as the function -literal is well-formed. - - def sendOverWire(s: Spore[Int, Int]): Unit = ... - sendOverWire((x: Int) => x * x - 2) - -## Design - -The main idea behind spores is to provide an alternative way to create -closure-like objects, in a way where the environment is controlled. - -A spore is created as follows. - -**Example 3:** - - val s = spore { - val h = helper - (x: Int) => { - val result = x + " " + h.toString - println("The result is: " + result) - } - } - -The body of a spore consists of two parts: - -1. **the spore header:** a sequence of local value (val) declarations only, and -2. **the closure**. - -In general, a `spore { ... }` expression has the following shape. - -Note that the value declarations described in point 1 above can be `implicit` -but not `lazy`. - -**Figure 1:** - - spore { - val x_1: T_1 = init_1 - ... - val x_n: T_n = init_n - (p_1: S_1, ..., p_m: S_m) => { - - } - } - -The types `T_1, ..., T_n` can also be inferred. - -The closure of a spore has to satisfy the following rule. All free variables -of the closure body have to be either - -1. parameters of the closure, or -2. declared in the preceding sequence of local value declarations, or -3. marked using `capture` (see corresponding section below). - -**Example 4:** - - case class Person(name: String, age: Int) - val outer1 = 0 - val outer2 = Person("Jim", 35) - val s = spore { - val inner = outer2 - (x: Int) => { - s"The result is: ${x + inner.age + outer1}" - } - } - -In the above example, the spore's closure is invalid, and would be rejected -during compilation. The reason is that the variable `outer1` is neither a -parameter of the closure nor one of the spore's value declarations (the only -value declaration is: `val inner = outer2`). - -### Evaluation Semantics - -In order to make the runtime behavior of a spore as intuitive as possible, the -design leaves the evaluation semantics unchanged compared to regular closures. -Basically, leaving out the `spore` marker results in a closure with the same -runtime behavior. - -For example, - - spore { - val l = this.logger - () => new LoggingActor(l) - } - -and - - { - val l = this.logger - () => new LoggingActor(l) - } - -have the same behavior at runtime. The rationale for this design decision is -that the runtime behavior of closure-heavy code can already be hard to reason -about. It would become even more difficult if we would introduce additional -rules for spores. - -### Spore Type - -The type of the spore is determined by the type and arity of the closure. If -the closure has type `A => B`, then the spore has type `Spore[A, B]`. For -convenience we also define spore types for two or more parameters. - -In example 3, the type of s is `Spore[Int, Unit]`. -Implementation -The spore construct is a macro which - -- performs the checking described above, and which -- replaces the spore body so that it creates an instance of one of the Spore traits, according to the arity of the closure of the spore. - -The `Spore` trait for spores of arity 1 is declared as follows: - - trait Spore[-T, +R] extends Function1[T, R] - -For each function arity there exists a corresponding `Spore` trait of the same -arity (called `Spore2`, `Spore3`, etc.) - -### Implicit Conversion - -Regular function literals can be implicitly converted to spores. This implicit -conversion has two benefits: - -1. it enables the use of spores in for-comprehensions. -2. it makes the spore syntax more lightweight, which is important in frameworks such as [Spark](http://spark.incubator.apache.org/) where users often create many small function literals. - -This conversion is defined as a member of the `Spore` companion object, so -it's always in the implicit scope when passing a function literal as a method -argument when a `Spore` is expected. For example, one can do the following: - - def sendOverWire(s: Spore[Int, Int]): Unit = ... - sendOverWire((x: Int) => x * x - 2) - -This is arguably much lighter-weight than having to declare a spore before -passing it to `sendOverWire`. - -In general, the implicit conversion will be successful if and only if the -function literal is well-formed according to the spore rules (defined above in -the _Design_ section). Note that _only function literals can be converted to spores_. -This is due to the fact that the body of the function literal has to be checked -by the spore macro to make sure that the conversion is safe. For _named_ function -values (i.e., not literals) on the other hand, it's not guaranteed that the -function value's body is available for the spore macro to check. - -### Capture Syntax and For-Comprehensions - -To enable the use of spores with for-comprehensions, a `capture` syntax has -been introduced to assist in the spore checking. - -To see why this is necessary, let's start with an example. Suppose we have a -type for distributed collections: - - trait DCollection[A] { - def map[B](sp: Spore[A, B]): DCollection[B] - def flatMap[B](sp: Spore[A, DCollection[B]]): DCollection[B] - } - -This type, `DCollection`, might be implemented in a way where the data is -distributed across machines in a cluster. Thus, the functions passed to `map`, -`flatMap`, etc. have to be serializable. A simple way to ensure this is to -require these arguments to be spores. However, we also would like for-comprehensions -like the following to work: - - def lookup(i: Int): DCollection[Int] = ... - val indices: DCollection[Int] = ... - - for { i <- indices - j <- lookup(i) - } yield j + i - -A problem here is that the desugaring done by the compiler for -for-comprehensions doesn't know anything about spores. This is what -the compiler produces from the above expression: - - indices.flatMap(i => lookup(i).map(j => j + i)) - -The problem is that `(j => j + i)` is not a spore. Furthermore, making it a -spore is not straightforward, as we can't change the way for-comprehensions -are translated. - -We can overcome this by using the implicit conversion introduced in the -previous section to convert the function literal implicitly to a spore. - -However, in continuing to look at this example, it's evident that the lambda -still has the wrong shape. The captured variable `i` is not declared in the -spore header (the list of value definitions preceding the closure within the -spore), like a spore demands. - -We can overcome this using the `capture` syntax – an alternative way of -capturing paths. That is, instead of having to write: - - { - val captured = i - j => j + i - } - -One can also write: - - (j => j + capture(i)) - -Thus, the above for-comprehension can be rewritten using spores and `capture` -as follows: - - for { i <- indices - j <- lookup(i) - } yield j + capture(i) - -Here, `i` is "captured" as it occurs syntactically after the arrow of another -generator (it occurs after `j <- lookup(i)`, the second generator in the -for-comprehension). - -**Note:** anything that is "captured" using `capture` may only be a path. - -**A path** (as defined by the Scala Language Specification, section 3.1) is: - -- The empty path ε (which cannot be written explicitly in user programs). -- `C.this`, where `C` references a class. -- `p.x` where `p` is a path and `x` is a stable member of `p`. -- `C.super.x` or `C.super[M].x` where `C` references a class and `x` references a stable member of the super class or designated parent class `M` of `C`. - -The reason why captured expressions are restricted to paths is that otherwise -the two closures - - (x => + capture()) - -and - - (x => + ) - -(where `` and `` are not just paths) would not have the same -runtime behavior, because in the first case, the closure would have to be -transformed in a way that would evaluate `` "outside of the closure". -Not only would this complicate the reasoning about spore-based code (see the -section Evaluation Semantics above), but it's not clear what "outside of the -closure" even means in a context such as for-comprehensions. - -### Macro Expansion - -An invocation of the spore macro expands the spore's body as follows. Given -the general shape of a spore as shown above, the spore macro produces the -following code: - - new [S_1, ..., S_m, R]({ - val x_1: T_1 = init_1 - ... - val x_n: T_n = init_n - (p_1: S_1, ..., p_m: S_m) => { - - } - }) - -Note that, after checking, the spore macro need not do any further -transformation, since implementation details such as unneeded remaining outer -references are removed by the new backend intended for inclusion in Scala -2.11. It's also useful to note that in some cases these unwanted outer -references are already removed by the existing backend. - -The spore implementation classes follow a simple pattern. For example, for -arity 1, the implementation class is declared as follows: - - class SporeImpl[-T, +R](f: T => R) extends Spore[T, R] { - def apply(x: T): R = f(x) - } - -### Type Inference - -Similar to regular functions and closures, the type of a spore should be -inferred. Inferring the type of a spore amounts to inferring the type -arguments when instantiating a spore implementation class: - - new [S_1, ..., S_m, R]({ - // ... - }) - -In the above expression, the type arguments `S_1, ..., S_m`, and `R` should be -inferred from the expected type. - -Our current proposal is to solve this type inference problem in the context of -the integration of Java SAM closures into Scala. Given that it is planned to -eventually support such closures, and to support type inference for these -closures as well, we plan to piggyback on the work done on type inference for -SAMs in general to achieve type inference for spores. - -## Motivating Examples, Revisited - -We now revisit the motivating examples we described in the above section, this -time in the context of spores. - -### Futures and Akka actors - -The safety of futures can be improved by requiring the body of a new future to -be a nullary spore (a spore with an empty parameter list). - -Using spores, example 1 can be re-written as follows: - - def receive = { - case Request(data) => - future(spore { - val from = sender - val d = data - () => { - val result = transform(d) - from ! Response(result) - } - }) - } - -In this case, the problematic capturing of `this` is avoided, since the result -of `this.sender` is assigned to the spore's local value `from` when the spore -is created. The spore conformity checking ensures that within the spore's -closure, only `from` and `d` are used. - -### Serialization - -Using spores, example 2 can be re-written as follows: - - case class Helper(name: String) - - class Main { - val helper = Helper("the helper") - - val fun: Spore[Int, Unit] = spore { - val h = helper - (x: Int) => { - val result = x + " " + h.toString - println("The result is: " + result) - } - } - } - -Similar to example 1, the problematic capturing of `this` is avoided, since -`helper` has to be assigned to a local value (here, `h`) so that it can be -used inside the spore's closure. As a result, `fun` can now be serialized -without runtime errors, since `h` refers to a serializable object (a case -class instance). diff --git a/_sips/sips/2013-06-30-async.md b/_sips/sips/2013-06-30-async.md deleted file mode 100644 index 90d602e27e..0000000000 --- a/_sips/sips/2013-06-30-async.md +++ /dev/null @@ -1,300 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-22 - Async - -vote-status: dormant -vote-text: Authors have marked this proposal as dormant. Details in the implementation need to be figured out. Check July 2016's minutes. -permalink: /sips/:title.html -redirect_from: /sips/pending/async.html ---- - -**By: Philipp Haller and Jason Zaugg** - -## Introduction - -This is a proposal to add constructs that simplify asynchronous and concurrent programming in Scala. The main constructs, async and await, are inspired by similar constructs introduced in C# 5.0. The main purpose of async/await is to make it possible to express efficient asynchronous code in a familiar direct style (where suspending operations look as if they were blocking). As a result, non-blocking code using Scala’s futures API \[[1][1]\] can be expressed without using higher-order functions, such as map and flatMap, or low-level callbacks. - -On the level of types, async and await are methods with simple, intuitive types: - - def async[T](body: => T): Future[T] - def await[T](future: Future[T]): T - -Here, `Future[T]` refers to the `Future` trait in package `scala.concurrent`. (The system can be adapted to other implementations of future-like abstractions; at the moment the API with the required extension points is internal, though.) The above methods are used as follows: - - val fut = async { - slowComputation() - } - -The async construct marks a block of asynchronous code, and returns a future. Depending on the execution context in the implicit scope (see \[[1][1]\]), the block of asynchronous code is either executed on the current thread or in a thread pool. The async block can contain calls to await: - - val futureDOY: Future[Response] = - WS.url("http://api.day-of-year/today").get - - val futureDaysLeft: Future[Response] = - WS.url("http://api.days-left/today").get - - val respFut = async { - val dayOfYear = await(futureDOY).body - val daysLeft = await(futureDaysLeft).body - Ok(s"$dayOfYear: $daysLeft days left!") - } - -Line 1 and 4 define two futures obtained as results of asynchronous requests to two hypothetical web services using an API inspired by Play Framework \[[2][2]\] (for the purpose of this example, the definition of type `Response` is unimportant). The `await` on line 8 causes the execution of the `async` block to suspend until `futureDOY` is completed (with a successful result or with an exception). When the future is completed successfully, its result is bound to the `dayOfYear` val, and the execution of the `async` block is resumed. When the future is completed with an exception (for example, because of a timeout), the invocation of `await` re-throws the exception that the future was completed with. In turn, this completes future respFut with the same exception. Likewise, the `await` on line 9 suspends the execution of the `async` block until futureDaysLeft is completed. - -## Comparison with Scala’s Futures API - -The provided async and await constructs can significantly simplify code coordinating multiple futures. Consider the following example, written using Scala’s futures API together with for-comprehensions: - - def nameOfMonth(num: Int): Future[String] = ... - val date = “““(\d+)/(\d+)“““.r - - for { doyResponse <- futureDOY - dayOfYear = doyResponse.body - response <- dayOfYear match { - case date(month, day) => - for (name <- nameOfMonth(month.toInt)) - yield Ok(s“It’s $name!“) - case _ => - Future.successful(NotFound(“Not a...“)) - } - } yield response - -Line 1 defines an asynchronous method that converts an integer representing the number of a month to the name of the month (for example, the integer 2 is converted to "February"). Since the method is asynchronous, it returns a `Future[String]`. Line 2 defines a regular expression used to extract the month from a date string such as "07/24". The for-comprehension starting on line 4 first awaits the result of `futureDOY` (the example re-uses the definition of `futureDOY` shown earlier). Scala's futures provide methods like `map` and `flatMap`, and can thus be used as generators in for-comprehensions (for a more in-depth introduction of this feature see the official documentation \[[1][1]\]). The use of for-comprehensions can help make future-based code more clear, but in many cases it requires a significant amount of unnatural clutter and workarounds. The above example suffers from the following issues: - -- To extract `dayOfYear`, we are forced to introduce the name `doyResponse`, a useless intermediate result (line 4); -- to await the completion of the future returned by `nameOfMonth`, we are forced to use a nested for-comprehension (line 8); -- the nested for-comprehension forces us to bind the result of nameOfMonth to name, a useless intermediate variable (line 8); -- the nested for-comprehension forces us to introduce an artificial future that's completed upon creation (line 11); -- the artificial future introduces additional overhead and garbage (line 11); -- finally, the use of for-yield might obscure the actual domain which is asynchronous computations with non-blocking awaits. - -The same example can be written using async/await as follows: - - async { - await(futureDOY).body match { - case date(month, day) => - Ok(s“It’s ${await(nameOfMonth(month.toInt))}!“) - case _ => - NotFound(“Not a date, mate!“) - } - } - -This version avoids all drawbacks of the previous version listed above. In addition, the generated code is more efficient, because it creates fewer closures. - -## Illegal Uses - -The following uses of await are illegal and are reported as errors: -- await requires a directly-enclosing async; this means await must not be used inside a closure nested within an async block, or inside a nested object, trait, or class. -- await must not be used inside an expression passed as an argument to a by-name parameter. -- await must not be used inside a Boolean short-circuit argument. -- return expressions are illegal inside an async block. - -## Implementation - -We have implemented the present proposal using the macro system which has been introduced in Scala 2.10 as an experimental feature. Our implementation \[[3][3]\] is targeted at Scala 2.11.0, but runs on using Scala 2.10.1 without any limitations. - -## Async Transform Specification - -In the following we consider the transformation of an invocation `async { }` of the async macro. -Before the block of code (``) is transformed, it is normalized into a form amenable to a transformation into a state machine. This form is called the "A-Normal Form" (ANF), and roughly means that: - -- `if`, `match`, and other control-flow constructs are only used as statements; they cannot be used as expressions; -- calls to `await` are not allowed in compound expressions. - -After the ANF transform, the async macro prepares the state machine -transformation by identifying vals, vars and defs that are accessed -from multiple states. These will be lifted out to fields in the state -machine object. - -The next step of the transformation breaks the code into "chunks." -Each chunk contains a linear sequence of statements that concludes -with a branching decision, or with the registration of a subsequent -state handler as the continuation (the "on-completion handler"). Once -all chunks have been built, the macro synthesizes a class representing -the state machine. The class contains: - -- an integer representing the current state ID -- the lifted definitions -- an `apply(value: Try[Any]): Unit` method that will be called on completion of each future. The behavior of this method is determined by the current state. It records the downcast result of the future in a field, and calls the `resume()` method. -- the `resume(): Unit` method that switches on the current state and runs the users code for one "chunk," and either: (a) registers the state machine as the handler for the next future, or (b) completes the result promise of the async block, if at the terminal state. -- an `apply(): Unit` method that starts the evaluation of the async block's body. - -### Example - - val future = async { - val f1 = async { true } - val x = 1 - def inc(t: Int) = t + x - val t = 0 - val f2 = async { 42 } - if (await(f1)) await(f2) else { val z = 1; inc(t + z) } - } - -After the ANF transform: -- `await` calls are moved to only appear on the RHS of a value definition; -- `if` is no longer used as an expression; instead each branch writes its result to a synthetic var; -- the `ExecutionContext` used to run the async block is obtained as an implicit argument. - -Follows the end result of the ANF transform (with very minor -simplifications). - - { - (); - val f1: scala.concurrent.Future[Boolean] = { - scala.concurrent.Future.apply[Boolean](true)(scala.concurrent.ExecutionContext.Implicits.global) - }; - val x: Int = 1; - def inc(t: Int): Int = t.+(x); - val t: Int = 0; - val f2: scala.concurrent.Future[Int] = { - scala.concurrent.Future.apply[Int](42)(scala.concurrent.ExecutionContext.Implicits.global) - }; - val await$1: Boolean = scala.async.Async.await[Boolean](f1); - var ifres$1: Int = 0; - if (await$1) - { - val await$2: Int = scala.async.Async.await[Int](f2); - ifres$1 = await$2 - } - else - { - ifres$1 = { - val z: Int = 1; - inc(t.+(z)) - } - }; - ifres$1 - } - -After the full async transform: - -- one class is synthesized that represents the state machine. Its `apply()` method is used to start the computation (even the code before the first await call is executed asynchronously), and the `apply(tr: scala.util.Try[Any])` method will continue after each completed future that the async block awaits; - -- each chunk of code is moved into the a branch of the pattern match in `resume$async`; - -- value and function definitions accessed from multiple states are lifted to be members of class `stateMachine`; others remain local, e.g. `val z`; - -- `result$async` holds the promise which is completed with the result of the async block; - -- `execContext$async` holds the `ExecutionContext` that has been inferred. - -Follows the end result of the full async transform (with very minor -simplifications). - - { - class stateMachine$7 extends StateMachine[scala.concurrent.Promise[Int], scala.concurrent.ExecutionContext] { - var state$async: Int = 0; - val result$async: scala.concurrent.Promise[Int] = scala.concurrent.Promise.apply[Int](); - val execContext$async = scala.concurrent.ExecutionContext.Implicits.global; - var x$1: Int = 0; - def inc$1(t: Int): Int = t.$plus(x$1); - var t$1: Int = 0; - var f2$1: scala.concurrent.Future[Int] = null; - var await$1: Boolean = false; - var ifres$1: Int = 0; - var await$2: Int = 0; - def resume$async(): Unit = try { - state$async match { - case 0 => { - (); - val f1 = { - scala.concurrent.Future.apply[Boolean](true)(scala.concurrent.ExecutionContext.Implicits.global) - }; - x$1 = 1; - t$1 = 0; - f2$1 = { - scala.concurrent.Future.apply[Int](42)(scala.concurrent.ExecutionContext.Implicits.global) - }; - f1.onComplete(this)(execContext$async) - } - case 1 => { - ifres$1 = 0; - if (await$1) - { - state$async = 2; - resume$async() - } - else - { - state$async = 3; - resume$async() - } - } - case 2 => { - f2$1.onComplete(this)(execContext$async); - () - } - case 5 => { - ifres$1 = await$2; - state$async = 4; - resume$async() - } - case 3 => { - ifres$1 = { - val z = 1; - inc$1(t$1.$plus(z)) - }; - state$async = 4; - resume$async() - } - case 4 => { - result$async.complete(scala.util.Success.apply(ifres$1)); - () - } - } - } catch { - case NonFatal((tr @ _)) => { - { - result$async.complete(scala.util.Failure.apply(tr)); - () - }; - () - } - }; - def apply(tr: scala.util.Try[Any]): Unit = state$async match { - case 0 => { - if (tr.isFailure) - { - result$async.complete(tr.asInstanceOf[scala.util.Try[Int]]); - () - } - else - { - await$1 = tr.get.asInstanceOf[Boolean]; - state$async = 1; - resume$async() - }; - () - } - case 2 => { - if (tr.isFailure) - { - result$async.complete(tr.asInstanceOf[scala.util.Try[Int]]); - () - } - else - { - await$2 = tr.get.asInstanceOf[Int]; - state$async = 5; - resume$async() - }; - () - } - }; - def apply: Unit = resume$async() - }; - val stateMachine$7: StateMachine[scala.concurrent.Promise[Int], scala.concurrent.ExecutionContext] = new stateMachine$7(); - scala.concurrent.Future.apply(stateMachine$7.apply())(scala.concurrent.ExecutionContext.Implicits.global); - stateMachine$7.result$async.future - } - -## References - -1. [The Scala Futures API][1] -2. [The Play! Framework][2] -3. [Scala Async on GitHub][3] - - [1]: http://docs.scala-lang.org/overviews/core/futures.html "ScalaFutures" - [2]: http://www.playframework.com/ "Play" - [3]: https://github.com/scala/async "ScalaAsync" diff --git a/_sips/sips/2015-6-18-repeated-byname.md b/_sips/sips/2015-6-18-repeated-byname.md deleted file mode 100644 index 382767a741..0000000000 --- a/_sips/sips/2015-6-18-repeated-byname.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: sip -title: SIP-24 - Repeated By Name Parameters -discourse: true - -vote-status: dormant -vote-text: Looking for a new owner. This proposal needs to be updated according to the SIP meeting in November 2016. -permalink: /sips/:title.html -redirect_from: /sips/pending/repeated-byname.html - ---- - -**By: Martin Odersky** - -## Motivation - -Scala so far does not allow by-name repeated parameters. But I can't see a good reason why this combination should be disallowed. Also, the combination is necessary to allow vararg parameters that are passed as expressions to inline methods (instead of being lifted out). - -## Syntax - -The syntax for `ParamType` becomes - - ParamType ::= [`=>'] ParamValueType - ParamValueType ::= Type [`*'] - -The syntax implies that a type such as `=> T*`, which is both by-name and repeated is interpreted as `=> (T*)`, that is, as a by-name type of a repeated type. - -## Translation Rules - -If a parameter has a by-name repeated type `=> T*` it matches an arbitrary number of actual arguments of type `T`. As usual for by-name parameters, the arguments are not evaluated at the point of call. Instead, all arguments are evaluated each time the parameter is referenced in the called method. - -The same holds for an vararg argument of the form `e: _*`. The argument expression `e` is evaluated each time the parameter is referenced in the called method. - -## See also - -[Dotty Issue #499](https://github.com/lampepfl/dotty/issues/499) diff --git a/_sips/sips/2016-07-25-unsigned-integers.md b/_sips/sips/2016-07-25-unsigned-integers.md deleted file mode 100644 index 8ac64cb337..0000000000 --- a/_sips/sips/2016-07-25-unsigned-integers.md +++ /dev/null @@ -1,636 +0,0 @@ ---- -layout: sip -title: SIP-26 - Unsigned Integers - -vote-status: rejected -vote-text: The committee votes to reject the proposal because of a 6% performance hit on the provided implementation by the authors. -permalink: /sips/:title.html -redirect_from: /sips/pending/unsigned-integers.html ---- - -__Sébastien Doeraene and Denys Shabalin__ - -**Summary**: We propose the addition of 4 "primitive" types to represent -unsigned integers: `UByte`, `UShort`, `UInt` and `ULong`. - -A prototype implementation of this proposal, with unit tests and benchmarks, -can be found [here](https://github.com/scala/scala/compare/2.12.x...sjrd:uints). - -## History - -| Date | Version | -|--------------|---------------| -| Nov 9th 2015 | Initial Draft | - -## Introduction - Motivation - Abstract - -Scala was initially designed to target the JVM, and, as such, defines exactly -9 primitive types corresponding to the 9 primitive types of the JVM (including -`void`): - -* `Boolean` -* `Char` -* `Byte` -* `Short` -* `Int` -* `Long` -* `Float` -* `Double` -* `Unit` - -Compared to other languages, especially those in the tradition of -compile-to-machine code, this list is missing types for unsigned integer types. - -When compiling Scala to other platforms than the JVM, such as JavaScript with -Scala.js or native code/LLVM with the upcoming ScalaNative, the missing unsigned -integer types are a liability, especially when it comes to *interoperability -with host language libraries*. - -For example, if a C library defines a function accepting a `uint32_t`, how would -we type it in a FFI definition? Even in JavaScript, which supposedly has only -`Double`s, there are APIs working with unsigned integers. The most well-known -one is -[the TypedArray API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray). -Currently, because of the lack of unsigned integers in Scala, the -[facade types for `Uint8Array` in Scala.js](https://github.com/scala-js/scala-js/blob/v0.6.5/library/src/main/scala/scala/scalajs/js/typedarray/Uint8Array.scala) -is forced to use `Short` elements instead of a more appropriate `UByte`. Worse, -[the one for `Uint32Array`](https://github.com/scala-js/scala-js/blob/v0.6.5/library/src/main/scala/scala/scalajs/js/typedarray/Uint32Array.scala) -has to work with *Doubles*, because there is no signed integer type existing on -JavaScript that can represent all values of a 32-bit unsigned int. - -On the JVM, interoperability is not an issue. However, it is still sometimes -useful to manipulate unsigned integers. An evidence of this fact is that Java 8 -has added methods in the JDK to *manipulate* signed integers *as if* they were -unsigned. One example is -[`java.lang.Integer.divideUnsigned`](http://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#divideUnsigned-int-int-). -Using signed integer types but interpreting them as unsigned is an obvious lack -of type safety, however. Java cannot decently add new primitive types for -compatibility reasons, but Scala has custom-made `AnyVal`s and other -Object-Oriented abstractions on top of primitive types that can allow for -additional, zero-overhead "primitive" types. - -We therefore propose to extend the Scala programming language with 4 new -primitive data types, representing unsigned integer types: - -* `scala.UByte`, an unsigned 8-bit integer -* `scala.UShort`, an unsigned 16-bit integer -* `scala.UInt`, an unsigned 32-bit integer -* `scala.ULong`, an unsigned 64-bit integer - -These data types will support a set of operations similar to their signed -counterparts, except that they will obviously encode the unsigned behavior. - -For example: - -```scala -val x = Int.MaxValue.toUInt + 1.toUInt // 2147483648 -assert(x.toString == "2147483648") -val y = Int.MaxValue.toUInt + 5.toUInt // 2147483652 -val z = x / y // unsigned division of 2147483652 by 2147483648 -assert(z == 1.toUInt) -assert(x % y == 4.toUInt) -``` - -## Motivating Examples - -### Examples - -#### Interoperability with host language unsigned integers - -The most important use case for true unsigned integers specified by the -language is interoperability with host languages with unsigned data types. - -If we try to manipulate an `Uint32Array` in Scala.js as currently defined, we -end up manipulating `Double`s, which can become extremely confusing: - -```scala -val array = new Uint32Array(js.Array(5, 7, 6, 98)) -val x = array(3) / array(0) -println(x) // 19.6 (!) -``` - -This also causes type safety issues, since nothing prevents the developer from -introducing a non-integer `Double` into such an array: - -```scala -array(2) = 6.4 // compiles, silent drop of precision -println(array(2)) // 6 -``` - -If we can define `Uint32Array` as an array of `UInt` instead, our problems are -solved: - -```scala -val array = new Uint32Array(js.Array(5, 7, 6, 98).map(_.toUInt)) -val x = array(3) / array(0) -println(x) // 19, as expected - -array(2) = 6.4 // does not compile, yeah! -``` - -#### Implementation of algorithms requiring unsigned operations - -No matter the platform, even on the JVM, we sometimes have to implement -algorithms that are best defined in terms of unsigned operations. Particularly, -more often than not, we want to treat bytes in a buffer as unsigned. - -For example, here is a (buggy) algorithm to decode text encoded in ISO-8859-1 -(latin1) into Unicode code points. Can you spot the issue? - -```scala -def decodeISO88591(buffer: Array[Byte]): String = { - val result = new StringBuilder(buffer.length) - for (i <- 0 until buffer.length) - result.append(buffer(i).toChar) - result.toString() -} -``` - -The problem is that `buffer(i).toChar` will first *sign-extend* the signed -`Byte` to an `Int`, then cut off the 16 most significant bits. If the initial -`Byte` was ">= 0x80", it was actually *negative*, and therefore the resulting -`Char` will have its 8 most significant bits set to 1, which is a bug. - -Fixing the algorithm requires knowledge of 2's complement properties and how -the bits are affected by arithmetic operations. The solution is -`(buffer(i) & 0xff).toChar`, which is totally non-obvious. - -With unsigned bytes, the problem does not happen by construction, and the -algorithm is straightforward: - -```scala -def decodeISO88591(buffer: Array[UByte]): String = { - val result = new StringBuilder(buffer.length) - for (i <- 0 until buffer.length) - result.append(buffer(i).toChar) // correct: UByte.toChar does not sign-extend - result.toString() -} -``` - -### Comparison Examples - -The blog post -[Unsigned int considered harmful for Java](http://www.nayuki.io/page/unsigned-int-considered-harmful-for-java) -explains in detail how to correctly manipulate signed integer types to make -them behave as unsigned. - -There are two main problems with this, considering only the JVM target: - -* We have to remember what operations need dedicated methods to deal with the - unsigned case. -* We cannot express in the type of a value whether it is to be interpreted as - a signed or unsigned integer. Effectively, we're back to *Assembly*-grade - weak typing. - -In addition, those separate manipulations do not allow back-ends to other -targets to effectively interoperate with host language unsigned data types. - -### Counter-Examples - -We do not intend to generalize unsigned numbers to Big integers nor to -floating-point numbers. - -Also, it is out of the scope of this proposal to provide literal constant -notations for unsigned integers. They should be constructed from their -corresponding signed literals, and reinterpreted using `.toUInt` and similar. - -## Drawbacks - -### Performance of arrays - -Unless the implementation of unsigned integer types is very much special-cased -in the compiler, arrays of unsigned integer types will likely suffer from the -same performance penalty as arrays of user-defined `AnyVal`s, because the -elements will be boxed. - -This might cause unexpected performance issues, as developers will think that -`Array[UByte]` is as fast as `Array[Byte]`, when in fact it is not. -Performance-critical code should still use `Array[Byte]`, and reinterpret the -bytes into unsigned bytes and back using `sb.toUByte` and `ub.toByte`, -respectively. - -## Alternatives - -The only other alternative is the status quo, where no unsigned integer types -exist, and difficult 2's complement-aware manipulations must be done when we -need them. - -## Design - -Naively, the design of the API is straightforward. We would define 4 new -data types `UByte`, `UShort`, `UInt` and `ULong`, corresponding to the 4 -signed integer data types. They feature the same set of arithmetic and logic -operations, as well as comparisons. However, such a naive design causes -several issues, especially when signed integers and unsigned integers interact -in operations. - -Here, we discuss the set of operations available, and their semantics. - -### No arithmetic/logic operations between signed and unsigned integers - -To prevent typical caveats when mixing signed and unsigned integers in most -languages, we simply *forbid* any arithmetic or logic operations with operands -of different signedness. - -### Universal equality, and hash codes - -The universal equality operators (`==` and `!=`) should behave consistently -across signed and unsigned types. Since `5.toByte == 5` in Scala, we should -also have `5.toUInt == 5`. This requires to modify the `==` implementation -(in `BoxesRunTime`) to implement cooperative equality checks between all -combinations of signed and unsigned values. - -Negative values of signed integers are *not* equal to any unsigned integer -value. For example, this means that `(-1).toUInt != -1`. This is very simply -explained by the fact that the mathematical value of `(-1).toUInt` is -4294967295. - -Because of transitivity of equality, it must be the case that a large value of -an unsigned integer (whose signed reinterpretation is negative, such as -`0xffffffff.toUInt`) *is* equal to values of a larger signed integer types -(such as `0xffffffffL`). - -Hash codes, as computed by `##`, must be made consistent with the generalized -form of universal equality. - -Note that this definition of universal equality is *essential* for these new -primitives to be usable for interoperability scenarios in Scala.js. This is -because, at runtime, "boxed" versions of numeric types loose their type -information, as they are all stuffed into primitive JavaScript numbers. -Therefore, `0xffff.toUShort` is indistinguishable from `0xffff`, and they must -be equal for this "non-boxing" to be valid. - -### Operations on `UByte` and `UShort` - -By analogy to the fact that operations on `Byte`s and `Short` start by -converting their operands to `Int`s (using sign-extend), operations on `UByte`s -and `UShort`s convert their operands to `UInt`s (without sign-extend, -obviously). - -### Arithmetic operations on `UInt`s and `ULong`s. - -For two operands of the same unsigned integer type with N bits, `a + b`, -`a - b`, `a * b`, `a / b` and `a % b` are computed modulo `2^N`. -For `+`, `-` and `*`, this boils down to a primitive (signed) equivalent -operations, on the JVM. `/` and `%` correspond to -`java.lang.{Integer,Long}.divideUnsigned` and `remainderUnsigned`. - -If one of the operand is a `ULong` but the other isn't, the latter is converted -to a `ULong` before performing the operation. - -There is no `unary_-`, because unsigned integers have no opposite. It could be -argued that `-x` could be useful for low-level bit-twiddling-based algorithms. -However, in that case, `~x + 1.toUInt` can be used instead. A basic peephole -optimizer can simplify the latter as `-x` on platforms where this is relevant. - -### Logic (bitwise) operations on `UInt`s and `ULong`s - -`unary_~`, `|`, `&` and `^` behave in the obvious way. If you want a precise -spec, they always behave as if the operand was reinterpreted into its signed -equivalent, then the operation performed, then the result reinterpreted back -into unsigned. - -### Bit shifting operations on `UInt`s and `ULong`s - -Shift left `<<` and shift logical right `>>>` behave in the obvious way. - -The case of shift arithmetic right `>>` is debatable. We argue that it should -*not* be available on unsigned integers for two reasons. - -First, a shift arithmetic right does not appear to have any *meaning* on -unsigned integers. The correct *arithmetic* shift if `>>>`. Therefore, -similarly to `unary_-`, it should not be introduced. - -Second, existing languages that do have unsigned integer types, such as the C -family, actually give different semantics to `>>` depending on whether it has -a signed or unsigned operand: a `>>` on an unsigned operand does *not* -sign-extend. It would be confusing to a C developer for `x >> 3` to sign-extend -in Scala, but it would be equally confusing to a Scala developer that `x >> 3` -*not* sign-extend. Therefore, we prefer to leave it out completely, and let a -compiler error be raised. - -If a bit-twiddling-based algorithm needs the sign-extending shift right, it is -always possible to reinterpret as signed, do the operation, and reinterpret -back as unsigned: `(x.toInt >> 3).toUInt`. - -Note: the current implementation does provide `>>`, until we agree on this -point. - -### Inequality operators - -`<`, `<=`, `>`, `>=` perform unsigned comparisons. On the JVM, they correspond -to `java.lang.{Integer,Long}.compareUnsigned`. - -### String representation - -The string representation is similar to that of signed integers, except that -all numbers are positive, obviously. On the JVM, they correspond to -`java.lang.{Integer,Long}.toUnsignedString`. - -### Implicit widening conversions - -Unsigned integers can be implicitly widened to "larger" unsigned integer types. -For example, `UShort` can be implicitly converted to `UInt` and `ULong`. - -There are no implicit conversions between signed and unsigned integers. It might -be tempting to allow unsigned integers to be widened to larger signed integer -types, since they can always accommodate their mathematical values. However, -this consequently allows operations between signed and unsigned integers, such -as `5L + 4.toUInt`, because of the conversion from `UInt` to `Long`. Since we -want to disallow those to prevent caveats, we do not allow the implicit -conversions. - -### Explicit conversions between signed and unsigned - -We have already extensively used explicit conversions between signed and -unsigned integer types *of the same size* in this document, such as -`someInt.toUInt`. These are specified as reinterpreting the bit pattern into -the other type, with the common specification that integer types are represented -in 2's complement. - -*Narrowing* conversions are also allowed in both directions, such as -`someInt.toUByte` or `someUInt.toByte`. They are equally well specified as -either `someInt.toUInt.toUByte` or `someInt.toByte.toUByte`, with the same -results, and therefore no ambiguity exists. - -*Widening* conversions from unsigned integers to larger signed integers is -allowed, and is specified by conserving the mathematical value, i.e., the -widening does *not* sign-extend. - -Finally, widening conversions from signed integers to larger unsigned integers -is *disallowed*, because both interpretations are equally valid, and therefore -half of the developers will have the wrong expectation. For example, -`someInt.toULong` can be equally validly specified as `someInt.toUInt.toULong` -or `someInt.toLong.toULong`, but those do not yield the same result (the former -does not sign-extend while the latter does). - -### Consequences on other parts of the library - -`scala.math` should receive new overloads of `max` and `min`, taking unsigned -integer types as parameters, and performing the comparisons with unsigned -semantics. - -There should be instances of the `Ordering` typeclass for unsigned integer -types. - -There should *not* be instances of the `Numeric` and `Integral` typeclasses -for unsigned integer types, since they do not support `unary_-`. - -It might be tempting to define `Range`s over unsigned integers, but we do not -want to go there. - -### Performance considerations - -Since they will inevitably be "branded" as primitive data types, unsigned -integer types should be as efficient as signed integer types. - -Fortunately, the JDK 8 added the necessary methods in the standard JDK to -trivially implement all the operations on unsigned integers. It is expected -that these methods be as fast primitive operations, since they can be -intrinsified easily. - -There also exist efficient implementations of these methods in Scala.js. LLVM -supports the relevant operations by default for ScalaNative, obviously. - -The implementations in `BoxesRunTime` for universal equality and hash codes -receives additional cases, which could slow down `==` on `Any`s and generic -values. However, if a codebase does not use any unsigned integer, the JVM, -using global knowledge, can statically determine that the new type tests are -always `false` and therefore remove them. There should be no performance -penalty on such codebases. - -## Implementation - -Because of the cooperative equality with primitive signed integers, the -addition of unsigned integers must necessarily integrate the core library. - -Besides that, there are two major strategies for the implementation: mostly -user-space or mostly in compiler-space. - -### Mostly user-space vs compiler-space - -An existing implementation living mostly in user-space can be found at -https://github.com/scala/scala/compare/2.12.x...sjrd:uints - -In this approach, unsigned integer types are user-defined `AnyVal`s, and all -the new methods are implemented in the library. The compiler needs very little -adaptations; basically only to dispatch `==` of unsigned integers to -`BoxesRunTime` (otherwise, it is "optimized" as directly calling `equals()`). - -This approach has obvious advantages: -* Little room for mistakes -* Very simple implementation -* Minimal impact on the compiler - -However, it also suffers from a couple of limitations, because the new -"primitive" data types are not really primitive, and do not receive some of the -semantic treatment of primitives. - -First, unboxing from `null`: a primitive data type unboxes `null` to its zero, -but user-defined `AnyVal`s throw in those situations. One way to fix this would -be to "fix" the behavior on `AnyVal`s in general, which we think would be a good -idea on its own anyway. - -Second, weak conformance: unsigned integers don't receive the weak conformance -properties. However, we argue that this is no big deal. The main use case for -weak conformance is so that `List(1, 5, 3.5)` can be inferred as a -`List[Double]` instead of a `List[AnyVal]`. The problem initially happens -because of the way we write literal integers and literal doubles. Since unsigned -integers have no literal notation, and are not implicitly compatible with -signed integers nor doubles, this point is moot. - -In the short term, these limitations do not appear important, and we could live -with them. - -More importantly, however, this implementation prevents specialization to be -applied on unsigned integers, and imposes harsh constraints on how back-ends -can implement unsigned integers. - -In Scala.js these constraints are not too hard from the point of view of -interoperability scenarios, although they could limit the performance we can -get out of unsigned integers. Since interoperability is paramount, we can again -live with the constraints for the time being. - -For ScalaNative, the consequences of these constraints are, as of yet, unknown, -but they could affect interoperability scenarios, and will most probably affect -performance. - -In the longer term, we should therefore consider more tightly integrating -unsigned integer types as true primitives of the compiler. - -Such a strategy will however be much riskier, and will take much more time to -get right. - -### Performance evaluation - -To evaluate performance of our prototype we've implemented a simple jmh -benchmark generator that checks composite performance of evaluation of complex -arithmetic expressions for all number types (both primitive signed ones and -user-defined unsigned ones.) - -For each type we've generated 4 benchmarks that use `+, -, *` ops (fastops) -and 4 benchmarks that use `+, -, *, /, %` (allops). Each of the 4 benchmarks uses exactly -the same arithmetic expressions for all types. Benchmarks on bytes and shorts wrap back -to corresponding type after each operation. - -The split between fastops and allops is important because unsigned division is -quite a bit slower than signed one on latest release of JDK 8: - - Benchmark Type Score Error Units - - division Int 289644141.092 ± 1544.707 ops/s - division UInt 129838344.866 ± 95523.094 ops/s - division Long 129839962.558 ± 90581.655 ops/s - division ULong 116493219.034 ± 67688.631 ops/s - - remainder Int 289454769.011 ± 94380.057 ops/s - remainder UInt 111032938.420 ± 679921.289 ops/s - remainder Long 128315753.345 ± 35932.509 ops/s - remainder ULong 97470062.788 ± 346773.054 ops/s - -And here are the results of composite benchmarks. - - Benchmark Type Score Error Units - - allop0 Byte 76612958.318 ± 97814.015 ops/s - allop0 UByte 26160709.822 ± 2098.556 ops/s - allop0 Short 76800575.238 ± 75373.970 ops/s - allop0 UShort 27172978.979 ± 3244.075 ops/s - allop0 Int 82816920.142 ± 50194.565 ops/s - allop0 UInt 27232792.726 ± 5116.920 ops/s - allop0 Long 28648964.226 ± 6115.162 ops/s - allop0 ULong 29657228.040 ± 159758.363 ops/s - - allop1 Byte 73715102.215 ± 17282.291 ops/s - allop1 UByte 26490808.836 ± 86628.862 ops/s - allop1 Short 73718029.884 ± 19413.132 ops/s - allop1 UShort 27041330.181 ± 4533.663 ops/s - allop1 Int 83239625.538 ± 13575.756 ops/s - allop1 UInt 28425497.966 ± 10927.728 ops/s - allop1 Long 29251967.961 ± 8278.100 ops/s - allop1 ULong 30537156.474 ± 14283.996 ops/s - - allop2 Byte 53138040.117 ± 7692.219 ops/s - allop2 UByte 19912528.484 ± 104896.763 ops/s - allop2 Short 52989318.748 ± 10075.293 ops/s - allop2 UShort 19828139.740 ± 217.796 ops/s - allop2 Int 60104405.263 ± 1888.322 ops/s - allop2 UInt 20576204.367 ± 446.445 ops/s - allop2 Long 20752333.428 ± 789.741 ops/s - allop2 ULong 22949083.651 ± 5766.597 ops/s - - allop3 Byte 68147811.661 ± 7349.838 ops/s - allop3 UByte 28016596.929 ± 4795.992 ops/s - allop3 Short 68147020.665 ± 8444.864 ops/s - allop3 UShort 29092855.210 ± 12323.477 ops/s - allop3 Int 93592095.470 ± 2970.030 ops/s - allop3 UInt 33298135.046 ± 15681.174 ops/s - allop3 Long 32276341.887 ± 3748.706 ops/s - allop3 ULong 53345993.564 ± 5486.483 ops/s - - fastop0 Byte 174384841.686 ± 13685.151 ops/s - fastop0 UByte 172490336.775 ± 42178.142 ops/s - fastop0 Short 174388762.469 ± 10303.837 ops/s - fastop0 UShort 172545184.374 ± 37150.012 ops/s - fastop0 Int 335919041.150 ± 121423.806 ops/s - fastop0 UInt 335925277.378 ± 120408.170 ops/s - fastop0 Long 339125057.494 ± 71538.513 ops/s - fastop0 ULong 339306595.964 ± 70387.619 ops/s - - fastop1 Byte 174736448.461 ± 9934.579 ops/s - fastop1 UByte 173817403.787 ± 20752.221 ops/s - fastop1 Short 174734415.599 ± 9850.473 ops/s - fastop1 UShort 173460828.250 ± 18068.154 ops/s - fastop1 Int 285178506.838 ± 129027.835 ops/s - fastop1 UInt 285137070.275 ± 145958.174 ops/s - fastop1 Long 285590926.722 ± 147048.419 ops/s - fastop1 ULong 274695574.679 ± 4878290.228 ops/s - - fastop2 Byte 168971931.233 ± 40481.486 ops/s - fastop2 UByte 169665745.096 ± 27401.842 ops/s - fastop2 Short 168979347.127 ± 11033.548 ops/s - fastop2 UShort 169675543.605 ± 19494.266 ops/s - fastop2 Int 287563728.176 ± 122987.272 ops/s - fastop2 UInt 287559086.868 ± 126833.074 ops/s - fastop2 Long 296129286.397 ± 171488.897 ops/s - fastop2 ULong 296142819.979 ± 167330.949 ops/s - - fastop3 Byte 333536457.973 ± 63928.967 ops/s - fastop3 UByte 339343014.623 ± 119819.041 ops/s - fastop3 Short 333535961.005 ± 69587.789 ops/s - fastop3 UShort 339354474.225 ± 121131.393 ops/s - fastop3 Int 475167307.642 ± 140060.266 ops/s - fastop3 UInt 475181473.416 ± 116982.494 ops/s - fastop3 Long 487109297.325 ± 580807.835 ops/s - fastop3 ULong 487190439.786 ± 737565.041 ops/s - -As you can see, fastops results have statistically insignificant differences -between signed and unsigned numbers. The same is true for allops for `Long` vs -`ULong`. - -Allops are 2-3x slower for `Byte`s, `Short`s and `Int`s, due to the fact that -unsigned division isn't as well optimised. We can probably make divisions for -`UByte` and `UShort` faster by using the regular division at the `Int` level, -but the current implementation does not do that yet. - -### Time frame - -We propose that unsigned integers be integrated in their user-space form as -early as possible, ideally in Scala 2.12, should this proposal be accepted in -time. An implementation is already available for Scalac, and it comes with an -exhaustive unit test suite. - -In the longer term, for 2.13 or 2.14, we propose to evaluate whether the -benefits of a compiler-space implementation outweigh the risks. The existing -test suite will make sure that the behavior of operations is unchanged. This -second phase should probably be studied jointly with the developments of -ScalaNative. - -## Previous discussions and implementations - -When -[Value Classes (SIP-15)](http://docs.scala-lang.org/sips/completed/value-classes.html) -were first introduced, the possibility to have new numeric types such as -unsigned integers was mentioned as a motivation. Subsequently, several people -[came up with implementations](https://groups.google.com/forum/#!topic/scala-sips/xtmUjsY9gTY) -of unsigned Ints and Longs. Those implementations were however more hacky -proofs of concept than a really thought-out proposal. - -Our proposal improves on those early attempts in several aspects: - -* Comprehensive but curated set of operations that are available on unsigned - integers, in particular no mixing signed and unsigned integers (avoid common - pitfalls found in other languages) -* Precise semantics for all operations (a specification) -* A meaningful notion of equality, which works well with other primitive types -* Use JDK 8 methods to implement operations that are specific to unsigned - integers, such as division -* Complete implementation with a test and benchmark suites - -## Out of scope - -The following related aspects are out of the scope of this proposal: - -### Literal notation for unsigned integers - -This proposal does not introduce any literal notation for unsigned integers. -Instead, we always convert from signed literals, e.g., `5.toUInt`. - -Providing literal notation should be done in the context of a SIP for -generalized user-defined literals. - -### Efficient arrays of unsigned integers - -We do not plan to address the issue of efficient arrays of unsigned integers. -Solving this should be part of a broader context for efficient arrays of -user-defined value classes in general, such as the encoding used in Dotty. - -## Unresolved questions - -* Should `>>` be available on unsigned integers? -* Should `null` unbox to 0 for unsigned integers even in their user-space - implementation? This would require some more changes to the compiler. - -## References - -1. [Implementation mostly in user-space for scalac/JVM](https://github.com/scala/scala/compare/2.12.x...sjrd:uints) diff --git a/_sips/sips/2016-09-09-inline-meta.md b/_sips/sips/2016-09-09-inline-meta.md deleted file mode 100644 index 803d6dfc05..0000000000 --- a/_sips/sips/2016-09-09-inline-meta.md +++ /dev/null @@ -1,1026 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-28 and SIP-29 - Inline meta - -vote-status: "under-revision" -vote-text: The following proposal has been split and numbered as SIP-28 (Inline) and SIP-29 (Meta). For more information on this decision, check the minutes. The authors need to split the proposal and update it. -permalink: /sips/:title.html -redirect_from: /sips/pending/inline-meta.html ---- - -**By: Eugene Burmako, Sébastien Doeraene, Vojin Jovanovic, Martin Odersky, Dmitry Petrashko, Denys Shabalin** - -## History - -| Date | Version | -| ---------------|----------------------------------------------| -| Aug 22nd 2016 | Initial Pre-SIP | -| Sep 9th 2016 | Initial SIP | - -## Preface - -This document represents the culmination of a design process that spans several years. -We did our best to extensively evaluate the design space and comprehensively document our findings. - -As a result, this is going to be a very long read. If you're just interested in getting a quick idea -of the proposal, you can read just the ["Intuition"][Intuition] section. - -If you have any questions, feedback or ideas regarding this document, use the link provided -in the ["Feedback"][FeedbackSection] section to join the public discussion. - -## Motivation - -Def macros and macro annotations have become an integral -part of the Scala ecosystem. They marry metaprogramming with types -and work in synergy with other language features, enabling [practically important use cases][MacroUsecases]. - -However, in addition to having the reputation of an indispensable tool, Scala macros have also gained notoriety -as an arcane and brittle technology. The most common criticisms of Scala macros concern their -subpar tool support and overcomplicated metaprogramming API powered by scala.reflect. - -While trying to fix these problems via evolutionary changes to the current macro system, -we have realized that they are all caused by the decision to use compiler internals as the underlying metaprogramming API. -Extensive use of desugarings and existence of multiple independent program representations may have worked well -for compiler development, but they turned out to be inadequate for a public API. - -The realization that we cannot make meaningful progress while staying within the confines of scala.reflect -meant that our macro system needs a redesign. We took the best part of the current macros - their smooth integration -into the language - and discarded the rest, replacing scala.reflect with a better metaprogramming API -and coming up with a lightweight declaration syntax. In this document, we present the current version of the design. - -## Table of contents - - * [Intuition](#intuition) - * [Def macros](#def-macros) - * [Discussion](#discussion) - * [Inline/meta](#inlinemeta) - * [Language features](#language-features) - * [Inline definitions](#inline-definitions) - * [Inline reduction](#inline-reduction) - * [Meta expressions](#meta-expressions) - * [Meta expansion](#meta-expansion) - * [Meta APIs](#meta-apis) - * [Design considerations](#design-considerations) - * [Scala.meta](#scalameta) - * [Tool support](#tool-support) - * [Losing whiteboxity](#losing-whiteboxity) - * [Losing compiler internals](#losing-compiler-internals) - * [Macro annotations](#macro-annotations) - * [Why inline](#why-inline) - * [Out of scope](#out-of-scope) - * [Conclusion](#conclusion) - * [Credits](#credits) - * [Feedback](#feedback) - -## Intuition - -In this section, we will walk through writing and using compile-time metaprograms that implement a subset of functionality -expected of language-integrated queries. Without going into much detail, -we will obtain high-level intuition behind the underlying mechanisms - -[Language-integrated query][Linq] is a technique that achieves smooth integration of database queries with programming languages. -A common approach to LINQ, popularized by .NET Framework 3.5, consists in representing datasources -by collection-like library types and then allowing users to write queries as series of calls to these types -using familiar higher-order methods like `map`, `filter` and others. - -We will now develop a sketch of a database access library built in the spirit of LINQ. -In this sketch, we will intentionally forgo the practicalities of building a LINQ library -(e.g. mapping from classes to datasources, design of internal ASTs, error reporting, etc.) -in order to clearly illustrate the role played by compile-time metaprogramming. - -Below we define a trait `Query[T]` that encapsulates a query returning a collection -of objects of type `T`. Next to it, we define its children `Table` and `Map` that represent -particular types of queries. `Table` stands for a datasource that knows about the underlying type -(in this sketch, we use an imaginary typeclass `TypeInfo` for that purpose). -`Map` models a restricted subset of SQL SELECT statements via a simple `Node` AST. - -``` -trait Query[T] -case class Table[T: TypeInfo]() extends Query[T] -case class Select[T, U](q: Query[T], fn: Node[U]) extends Query[U] - -trait Node[T] -case class Ref[T](name: String) extends Node[T] - -object Database { - def execute[T](q: Query[T]): List[T] = { ... } -} -``` - -In this model, a SQL query string `"SELECT name FROM users"` is represented as `Select(Table[User](), Ref[String]("name"))`. -Queries like the one just mentioned can be run via `Database.execute` that translates them into SQL, sends the SQL to the database, -receives the response and finally translates it to data objects. For the sake of simplicity, we will assume such implementation as a given. - -The key aspect of a LINQ facility is a convenient notation for queries. -Arguably, none of the aforementioned ways to write queries can be called convenient. -SQL, as any string-based representation, is prone to syntax errors, type errors and injections. -Explicit instantiation of `Query` objects is very verbose, and still doesn't solve all type errors. - -In this sketch, we define a LINQ API in the form of methods that mirror the collection API -from the standard library. We would like our users to be able to encode queries in intuitively looking, -statically typed calls to this API, e.g. `users.map(u => u.name)`, and then have our library translate these -calls into calls to `Query` constructors. - -``` -object Query { - implicit class QueryApi[T](q: Query[T]) { - def map[U](fn: T => U): Query[U] = { ... } - } -} - -case class User(name: String) -val users = Table[User]() -users.map(u => u.name) -// translated to: Select(users, Ref[String]("name")) -``` - -Among other ways, the desired effect can be achieved with compile-time metaprogramming. -A metaprogram that runs at compile time can detect all calls to `Query.map` and rewrite them -to invocations of `Select` with parameters of `map` transformed to corresponding instances of `Node`. - -### Def macros - -Before looking into the design of the new macro system, let's see how the problem at hand -can be solved using the currently available macro system. - -``` -import scala.language.experimental.macros - -object Query { - implicit class QueryApi[T](q: Query[T]) { - def map[U](fn: T => U): Query[U] = macro QueryMacros.map - } -} -``` - -`QueryApi.map` is called a macro def. Since macros are experimental, -in order to define a macro def, it is required to either have `import scala.language.experimental.macros` -in the lexical scope of the definition or to enable the corresponding setting in compiler flags. -This is only necessary to define a macro def, not to use it. - -Macro defs look like normal methods in the sense that -they can have term parameters, type parameters and return types. -Just like regular methods, macro defs can be declared either inside or outside of classes, -can be monomorphic or polymorphic, and can participate in type inference and implicit search. -Refer to [Appendix A][AppendixInteraction] for a detailed account of differences -between macro defs and regular defs. - -Bodies of macro defs have an unusual syntax. The body of a macro def starts with the conditional keyword `macro` and -is followed by a possibly qualified identifier that refers to a macro impl, -an associated metaprogram run by the compiler when it encounters corresponding macro applications. -Macro impls are defined as shown below. - -``` -import scala.reflect.macros.blackbox.Context - -object QueryMacros { - def map(c: Context)(fn: c.Tree): c.Tree = { - import c.universe._ - ... - } -} -``` - -Macro impls take a compiler context that represents the entry point into the macro API. -The macro API consists of a general-purpose metaprogramming toolkit provided by scala.reflect -and several specialized facilities exclusive to macro expansion. -A typical first line of a macro impl is `import c.universe._` that makes the entire scala.reflect API available to the metaprogrammer. - -In addition to the compiler context, for every term parameter of a macro def, its macro impl -takes a term parameter that carries a representation of the corresponding argument of the macro application. -Macro impls can also get ahold of representation of type arguments, but this functionality is unnecessary for this example. - -A macro impl returns an abstract syntax tree, and this AST replaces the original macro application in the compilation pipeline. -This is how we're going to perform the LINQ translation of calls to `Query.map`. - -``` -import scala.reflect.macros.blackbox.Context - -object QueryMacros { - def map(c: Context)(fn: c.Tree): c.Tree = { - import c.universe._ - - // c.prefix looks like: - // Query.QueryApi[]() - val q"$_.$_[$_]($prefix)" = c.prefix - - val node: Tree = fn match { - case q"($param) => $body" => - val sym = param.symbol - body match { - case q"$qual.$_" if qual.symbol == sym => - q"Ref[${body.tpe}](${sym.name.decodedName.toString})" - } - } - - q"Select($prefix, $node)" - } -} -``` - -In the listing above, we handle several challenges of macro writing. -First, we get ahold of the prefix of the application, i.e. the `users` part of `users.map(u => u.name)`. -Unlike macro arguments, prefixes aren't mapped onto parameters of macro impls, -so we need to use the dedicated `c.prefix` API. - -The next challenge is to extract the prefix from the macro application. -Since `Query.map` is an extension method, the actual prefix is going to be `QueryApi(users)`, not `users`, -therefore we need to apply some non-trivial effort. - -One way of getting to the query is to access the corresponding field of the implicit class, -doing something like `QueryApi(users).q`. Unfortunately, this is out of the question, because `q` is private, -and we cannot make it public without adding an extension method called `q` to `Query`. - -Another way of achieving the desired result is to take apart the abstract syntax tree representing `QueryApi(users)`, -extracting `users` as the argument of the application. -It looks like quasiquotes, -which are supposed to provide a convenient WYSIWYG interface to deconstructing Scala code, -are going to be a perfect fit. - -Unfortunately for macro writers, the Scala compiler heavily desugars code during compilation, -so even the modest `QueryApi(users)` -will get to the macro impl in the form of `Query.QueryApi[User](users)`. -Therefore the naive `q"$_($query)"` quasiquote is not going to work, -and we need to apply additional effort. With a bit of knowledge about compiler internals, -we take care of this. - -The final challenge is code generation. -The pattern match in listing above transforms the user-provided lambda expression into an equivalent `Node`. -Since our sketch only supports `Ref`, we only support simple lambdas that select a field from a parameter. -Finally, we produce the macro expansion that has the desired shape. - -### Discussion - -Note how the ability of def macros to access types dramatically improves user experience in comparison with purely syntactic translation. -First, even before `Query.map` gets to expand, the compiler typechecks its argument, making sure that -queries are well-typed. Secondly, we have a way to reliably check the shape of the supported lambda. -The symbol comparison in the nested pattern match makes sure that -the qualifier of field selection refers precisely to the parameter of the lambda -and not to something else accidentally having the same name. Finally, we use information about the type of the body -in order to figure our the mandatory type parameter of `Ref`. - -Also note another piece of knowledge about compiler internals that was essential to robust operation of the macro. -When generating a `Ref`, we can't simply call `sym.name.toString`, because the Scala compiler internally mangles non-alphanumeric names. -If the parameter of the lambda has such a name, a simple `toString` will produce unsatisfying results, -which is why we have to call `Name.decodedName` first. - -Before we conclude, let's highlight a very common metaprogramming mistake that we've just made in `QueryMacros.map`. -Def macros are unhygienic, which means that they don't prevent inadvertent name capture, i.e. scenarios like the following. - -``` -val Select = "hijacked!" -users.map(u => u.name) - -// error: too many arguments for -// method apply: (index: Int)Char in class StringOps -// users.map(u => u.name) -// ^ -``` - -If the macro user accidentally defines a term called `Select` or `Ref`, our macro is going to stop working -with what looks like a nonsensical error message. Because principled tool support wasn't among the design goals of -our macro system, a macro user getting this error is mostly helpless apart from trying to use internal compiler options -that print all macro expansions and then going through the resulting wall of text. - -One reliable approach to prevent hygiene errors is to use fully-qualified names for external references and -to generate unique names for local variables. A somewhat more concise, but potentially much more laborious approach is to explicitly -assign symbols to references and definitions emitted in macro expansions. -This approach often requires extensive knowledge of compiler internals, so it is less frequent in the wild. -Common to both of these approaches is that they require explicit attention from metaprogrammers and -failures to apply them typically go unnoticed. - -To sum it up, even in this simple macro we encountered situations where knowledge of compiler internals -(the desugaring of the `QueryApi` application, the fact that non-alphanumeric names are encoded) was essential. -We also ran into problems with tool support and hygiene, which demonstrates how important they are to a macro system. -These are all common criticisms of def macros. - -### Inline/meta - -User interface of def macros is a seamless extension to the existing language interface. -Thanks to macro defs looking like regular methods and macro applications looking like regular method applications, -macro users are likely to not even realize that they are using macros. - -Unfortunately, metaprogrammer interface leaves much to be desired. First, in the current macro system, -metaprograms have to be defined separately from their signatures, typically involving helper objects and -duplication of parameters. Secondly, the underlying metaprogramming API requires -knowing bits and pieces of compiler internals. For example, in the case of `Query.map`, -the metaprogrammer had to know the internal representation of the `QueryApi` application -and internal details of how names are represented. - -New-style macros provide the same user interface, and at the same time significantly improve metaprogrammer -interface by enabling lightweight macro declaration syntax and using a better metaprogramming API. - -``` -object Query { - implicit class QueryApi[T](q: Query[T]) { - inline def map[U](fn: T => U): Query[U] = meta { - import scala.meta._ - - val q"$_($prefix)" = this - - val node: Tree = fn match { - case q"($name: $_) => $body" => - body match { - case q"$qual.$_" if qual =:= name => - q"Ref[${body.tpe}](${name.toString})" - } - } - - q"Select($prefix, $node)" - } - } -} -``` - -At a glance, new-style macros simply forgo a noticeable amount of ceremony, -merging the previously disparate macro defs and macro impls as well as swapping around a few keywords in the process. -The underlying metaprogram doesn't seem to have changed much, -still using quasiquotes and key APIs like `Tree.tpe` and `Name.toString`. - -First impression notwithstanding, the new design revamps a lot of underlying mechanisms. -Below we provide a high-level overview of our new approach to compile-time metaprogramming, -and refer curious readers to ["Language features"][LanguageFeatures] for information concerning the new expansion mechanism -and to ["Scala.meta"][ScalaMetaSection] for details about the new metaprogramming API. - -**Expansion mechanism**. The new design takes the notions of inlining and compile-time execution -from the current macro system and turns them into separate language features. - -The goal of the `inline` modifier on `Query.map` is to signify that applications of this method are inlined, -i.e. replaced with the method body, in which references to enclosing `this`, self, and formal parameters are rewritten accordingly -(see ["Inline reduction"][InlineExpansion] for details). - -The goal of the `meta` keyword is to demarcate code that executes at compile time and to provide -that code with [scala.meta capabilities][MetaApis]. -The metaprogram written inside the meta scope has access to multiple implicit capabilities -and can get ahold of representations of certain values and types from lexical scope. -The compiler runs this metaprogram, interprets its result as an abstract syntax tree -and replaces the meta expression with that tree (see ["Meta expansion"][MetaExpansion] for details). - -When the compiler encounters a call to `Query.map`, -it simply inlines the body of `map` into the callsite without performing any compile-time function execution. -For the running example of `users.map(u => u.name)`, -this inlining produces the result illustrated in the listing below. - -``` -{ - val prefix$1: QueryApi = QueryApi(users) - val fn$1: User => String = u => u.name - meta { - import scala.meta._ - - val q"$_($prefix)" = q"QueryApi(users)" - - val node: Tree = q"u => u.name" match { - case q"($name: $_) => $body" => - body match { - case q"$qual.$_" if qual =:= name => - q"Ref[${body.tpe}](${name.toString})" - } - } - - q"Select($prefix, $node)" - } -} -``` - -Before inlining a method application, the compiler first hoists the prefix and by-value arguments of the application -into temporary variables. This is done in order to guarantee that applications of inline methods -are semantically equivalent to applications of regular methods. - -Afterwards, the compiler replaces the application with a block that consists of hoisted values and the transformed method body. -In the method body, all regular references to `this` and self as well as -by-value parameters are rewritten to references to the corresponding temporary variables. -If such references are part of a meta scope, they are replaced with scala.meta-based representations of -the prefix and the corresponding arguments, without going into temporary variables. - -When the compiler comes across a meta expression that isn't part of an inline method, -it executes the code inside the expression and replaces the expression with the result of execution. -For our running example, this produces the desired expansion that invokes query constructors corresponding -to the LINQ notation. - -**New metaprogramming API**. Scala.meta noticeably improves on scala.reflect in the convenience of the API -and no longer requires metaprogrammers to understand compiler internals in order to write macros. - -In particular, we don't need to know that construction of the implicit class involves -expanding the reference to `QueryApi` into a fully-qualified name and inferring the missing type argument. -The particular implementation of the scala.meta API that runs the meta expression may or may not -do these desugarings, and scala.meta shields us from this fact. -We can use the WYSIWYG pattern `q"$_($prefix)"` in order to unwrap the original prefix of the call. - -Moreover, we don't have to worry about the compiler internally mangling non-alphanumeric names. -Again, even if the underlying macro engine internally does name mangling, scala.meta abstracts away such implementation details. - -Finally, we are able to improve on scala.reflect thanks to more precise quasiquotes. -If in the current macro system, we used `q"($name: $_) => ..."` to match the `fn` argument, -`name` would capture a scala.reflect `Name` that doesn't carry any semantic information. -In scala.meta, names are full-fledged trees, so we can use `Tree.=:=` to semantically compare the name -with the qualifier of the field selection. - -In order to use semantic APIs, scala.meta metaprograms need the [mirror capability][ScalaMetaSection], -so it is implicitly provided inside meta scopes. As a result, meta expressions can use the full spectrum -of APIs available in scala.meta. - -**To put it in a nutshell**, the new-style macro system combines two language features: -[inline definitions][InlineDefs] and [meta expressions][MetaExprs] -in order to provide a more lightweight syntax for the current def macros. Moreover, this macro system -does a switchover from scala.reflect to scala.meta, featuring a new API that is more convenient and -doesn't require compiler knowledge to be utilized effectively. - -## Language features - -### Inline definitions - -We introduce a new reserved word: `inline`, which can be used as a modifier for -concrete vals, concrete methods and parameters of inline methods, as illustrated in the listing below. - -``` -inline val x = 4 - -inline def square(x: Double) = x * x - -inline def pow(b: Double, inline n: Int): Double = { - if (n == 0) 1 - else b * pow(b, n - 1) -} -``` - -Inline vals are guaranteed to be compile-time constants, superseding the existing approach -of declaring such constants with `final val`. Inline parameters get the same treatment, adding a previously -non-existent functionality of guaranteeing that an argument of a method is a compile-time constant. - -A value is considered to be a compile-time constant if it is a Scala literal, -or it is equivalent to one by the means of inline/meta expansion and constant folding. -Future work may extend this notion to custom classes, but this discussion lies outside the scope of this proposal. - -Inline defs are guaranteed to be inlined at compile time, superseding the existing approach of -annotating methods with the `@inline` annotation. After introducing `inline`, we expect to deprecate and phase out `@inline`. - -The problem with `@inline` is that it doesn't provide guarantees. -As specified in documentation, -`@inline` tells the compiler to "try especially hard to inline the annotated method". -However, different backends interpret this request differently. -The JVM backend ignores this annotation if optimizations are disabled and sometimes skips inlining even when optimizations are enabled. -Both Scala.js and Scala Native always inline methods that are marked with this annotation. -In contrast, `inline` achieves guaranteed inlining, regardless of the backend. - -Inline defs are very similar to macro defs in the sense that they look like regular defs and that they expand at compile time. -As a result, the rules in [Appendix A][AppendixInteraction] also apply to inline defs with three exceptions. - - 1. Inline defs are effectively final; they cannot be overridden. Inline members also never override other members. -The idea of allowing macro defs to override regular defs didn't find compelling use cases, so we prohibit this for inline defs. - - 1. Inline defs can have default parameters. Not supporting default parameters for macro defs was an oversight -of the initial design, so now we fix this oversight in the new macro system. - - 1. Inline defs have regular bodies, just like regular defs. When an inline def is typechecked, its body -is typechecked according to the usual rules, which means that inline defs are eligible for return type inference. If an inline def -doesn't explicitly specify its result type, the result type gets inferred from the type of its body. - -### Inline reduction - -When the compiler encounters certain patterns of code that involve references to inline vals and applications of inline defs, -it will perform the rewritings provided below, if and only if these patterns appear outside the bodies of inline vals and defs. - - 1. If `prefix.v` refers to an inline value, replace the expression with the body of `v`. - - 1. If `prefix.f[Ts](args1)...(argsN)` refers to a fully applied inline method, hoist the prefix and the arguments -into temporary variables with fresh names and then replace the expression with the method body. In the body, replace parameter references -with references to temporary variables created for the corresponding arguments. Also, replace enclosing `this` -and self references with references to the temporary variable created for the prefix. - - ``` - { - val prefix$1 = prefix - val param1$1 = arg1 - ... - val paramN$1 = argN - - } - ``` - - The hoisting is intended to preserve the semantics of method applications under inlining. - A method call should have the same semantics with respect to side effects independently - on whether the method was made inline or not. - If an inline method has by-name parameters, then corresponding arguments are not hoisted. - - The rewriting is done in accordance with hygiene. Any references from the method body to its lexical scope - will be kept in the rewritten code. If the result of the rewriting references private or protected definitions - in the class that defines the inline method, these references will be changed to use accessors generated automatically by the compiler. - To ensure that the rewriting works in the separate compilation setting, - it is critical for the compiler to generate the accessors in advance. - Most of these accessors can be pregenerated by analyzing the bodies of inline methods, - except for members that are referred to inside meta scopes. - Such references are disallowed, because it is impossible to generate them in advance. - - 1. If `prefix.f[Ts](args1)...(argsN)` refers to a partially applied inline method, an error is raised. -Eta expansion of inline methods is prohibited. - -The rules of inline reduction are similar to the rules of feature interaction for macro applications ([Appendix A][AppendixInteraction]) -as well as relevant parts of the rules of def macro expansion ([Appendix B][AppendixExpansion]) with four exceptions. - - 1. Inline reductions in their current form preclude whitebox expansion. -Since bodies of inline vals and defs are typechecked when their definitions are typechecked, -potential meta expansions that may happen afterwards won't be able to change their types. -Implications of this are discussed in ["Losing whiteboxity"][Whiteboxity]. - - 1. By-value and by-name arguments behave differently. By-value arguments are hoisted in temporary variables, -while by-name arguments remain as they were. This doesn't affect meta expansions, -but it does make a semantic difference for parts of inline definitions that are not inside meta scopes. -Note that `this` and self references always follow the by-value scheme, -because there is no syntax in Scala that allows to define them as by-name. - - 1. Named and default arguments are fully supported. Again, not including them in the initial release of def macros -was an oversight, which is now fixed. - - 1. The rules of rewriting mandate the "outside in" style, i.e. calls to inline methods are expanded before possible calls -to inline methods in their prefixes and arguments. This is different from how the "inside out" style of def macros, -where prefixes and arguments are expanded first. Previously, it was very challenging to -take a look at unexpanded trees, but now the metaprogrammer can switch between unexpanded and expanded views using scala.meta. - -From the discussion above, we can see that inline reduction closely resembles the inlining aspect of the current macro system. -The only significant difference is lack of support for whitebox expansion, which will be discussed in ["Losing whiteboxity"][Whiteboxity]. - -### Meta expressions - -A meta expression is an expression of the form `meta { ... }`, where `{ ... }` is some block of Scala code, called meta scope. -(In fact, `meta` may prefix arbitrary expressions, but blocks are expected to be used most commonly). - -Meta expressions can appear both -in the bodies of inline methods (then their expansion is going to be deferred until the enclosing method expands) -and in normal code (in that case, their expansion will take place immediately at the place where the meta expression is written). - -Meta scopes can contain arbitrary code, but they must return values that are either of type `scala.meta.Term` or are convertible -to it via the `scala.meta.Lift` typeclass. There are standard instances of the typeclass that lift simple values to literals -as well as ones that support frequently used collections of liftable values. Metaprogrammers may define and use their own instances -as long as they are available in corresponding meta scopes. - -Inside meta scopes, metaprogrammers can use a combination of general-purpose and expansion-specific metaprogramming facilities. -Refer to ["Meta APIs"][MetaApis] for more information. - -Since meta scopes must return scala.meta trees, and scala.meta trees are by design statically untyped, -the type of meta expressions can't be computed from the inside -and has to come from the outside. Therefore, meta expressions can only be used in contexts that specify an expected type. - -``` -// allowed, expected type provided by the return type -inline def map[U](fn: T => U): Query[U] = meta { ... } - -// not allowed, no explicit return type -val x = meta { ... } - -// allowed, expected type of a condition is Boolean -if (meta(T.isPrimitive)) { ... } -``` - -Meta scopes can reference names in their lexical scope outside the enclosing meta expression. -While crossing the `meta` boundary, references change their meaning. -Concretely, here's how the transformation works for different references: - -**Inline vals and inline parameters**. These are guaranteed to be compile-time constants, -so an inline value of type `T` is available inside a meta scope as a regular value of type `T`. - -**Inline defs**. When viewed from within a meta scope, inline defs become tree transformers. -Types of their inline parameters are unchanged, their non-inline parameters and return type become typed as `scala.meta.Term`. -For example, `inline def pow(b: Double, inline n: Int): Double` transforms into -`def pow(b: scala.meta.Term, n: Int): scala.meta.Term`. - -**Term parameters of an inline method**. References to statically known term parameters, -enclosing `this` or self become values of type `scala.meta.Term`. This is similar to `c.Expr`/`c.Tree` -parameters of macro impls, but more lightweight, because there's no need -to declare these parameters explicitly. - -**Type parameters of an inline method**. References to statically known type parameters become values -of type `scala.meta.Type`. This is similar to `c.WeakTypeTag` parameters of macro impls, -but more lightweight, because metaprogrammers don't need to explicitly manifest their interest in given type parameters -in order to get access to their representations. - -This rule can create clashes between term and type namespaces. -If such a clash happens, i.e. if a reference to a type parameter is ambiguous with an eponymous term, -the compiler emits an error. This is regrettable, but Scala naming conventions make this situation unlikely, -and there is always a workaround of renaming the type parameter. - -**Global definitions**. Statically available types and terms, e.g. `List` or `Int`, -are usable inside meta scopes as themselves. This means that meta expressions, just like macro impls, -can use the standard library and arbitrary third-party libraries. - -**Other definitions**. Macro scopes cannot reference definitions that don't fall into one of the categories mentioned above. -This outlaws usages of local definitions - both terms and types. Such definitions may refer to state that only -exists at runtime, so we prohibit them altogether. This has no analogues in the current macro system, because macro impls -must be defined in static methods, which means that by definition their scope cannot contain local definitions. - -In other words, definitions that are statically available outside meta scopes remain available in meta scopes, -term and type arguments of inline methods become available as their representations, -while signatures of inline methods are recursively transformed according to the rules above. - -From the discussion above, we can see that meta expressions provide an analogue of the compile-time execution part -of the current macro system. In addition to achieving feature parity, meta expressions also improve on the corresponding part of def macros -by allowing metaprograms to easily obtain representations of their term and type parameters and -making it possible to run anonymous snippets of metaprogramming code without wrapping them in a dedicated macro. - -### Meta expansion - -When the compiler encounters a meta expression that appears outside the bodies of inline vals and defs, -it expands that expression as described below. - -A meta expression is expanded by evaluating its body and replacing the original meta expression with an expression -that represents the result of the evaluation. The compiler is responsible for providing [the capabilities][MetaApis] -necessary for meta scopes to evaluate and for converting between its internal representation for language model elements -and representations defined in scala.meta, such as `scala.meta.Term` and `scala.meta.Type`. - -Meta expansion works very similarly to the relevant part of the def macro expansion pipeline ([Appendix B][AppendixExpansion]). -Code in the meta scope is precompiled and then reflectively invoked by the compiler, sharing the class loader with other -metaprograms run inside the compiler. Expansion can return normally or can be interrupted with an exception. Expansion results -are typechecked against the expected type of the meta expression. Typecheck results are upcast to the expected type in blackbox style, -as discussed in ["Losing whiteboxity"][Whiteboxity]. - -Another practicality of meta expansion is the protocol of communication between `inline` and `meta`. -On the one hand, a reasonable default for inlining that doesn't involve meta expressions is to hoist prefixes and by-value arguments -as described in ["Inline reduction"][InlineExpansion]. On the other hand, macro writers default to having unfettered access to -abstract syntax trees without needing to write additional boilerplate. -These two design preferences are at odds with each other. - -Therefore, in our design `inline` both hoists eligible components of inline applications and passes their original -representations into meta expressions. This way, both defaults are satisfied and, additionally, if meta expressions need -to hoist something, they can use the new `hoist` API. - -In the case when an inline method consists in a single meta expression, the new macro engine removes temporary variables -that are produced by hoisting and aren't claimed by `hoist`. In the case when an inline method doesn't contain -meta expressions, all temporary variables are retained, because they are necessary to express method application semantics. -Finally, in the case of a hybrid inline method, meta expressions can look into representations of hoisted expressions, -but they cannot use them in their expansions without calling `hoist` first in order to avoid reordering or duplicating side effects. - -In a nutshell, meta expansion closely resembles the compile-time execution aspect of the current macro system. -The only nuance is the interaction with hoisting performed by the mechanism of inline reduction. - -### Meta APIs - -In scala.meta, all APIs are available out of the box after doing `import scala.meta._`. -However, in order to use most of them, metaprogrammers must have access to certain capabilities -(see ["Scala.meta"][ScalaMetaSection] for details). - -Meta scopes provide two different capabilities. First, there are general-purpose metaprogramming facilities, -enabled by a `Mirror`. Secondly, there are expansion-specific facilities enabled via a newly introduced `Expansion`. - -Mirrors are explained in ["Scala.meta"][ScalaMetaSection], and in this section -we will cover the functionality enabled by expansions. We will also compare this functionality -with macro APIs from the current macro system. - -First, `Context.prefix` is no longer necessary, -because meta expressions can refer to prefixes of enclosing inline definitions via `this`. -`Context.macroApplication` is unnecessary as well, because meta expressions may be written outside inline vals and defs, -which means that they won't have a corresponding application at all. In the rare cases when it is useful to know -the position that spans the entire inline application, it can be obtained by traversing prefixes or arguments via `Tree.parent`. - -Secondly, much like their counterparts in the current macro system, meta APIs support diagnostic messages. -Since the only prevalent macro APIs in this group is `Context.abort`, with `Context.error`, `Context.warning` -and others seeing rare use, we only expose `abort` that works similarly to its predecessor. - -Thirdly, we no longer expose APIs that tightly integrate with compiler internals. Most of these APIs take care -of the limitations of the scala.reflect language model, so in the new metaprogramming framework based on scala.meta -they are simply unnecessary. Others feature advanced functionality that accesses or manipulates internal compiler state, -and this exactly the kind of thing that we would like to avoid in the macro system. We discuss the implications in -["Losing compiler internals"][CompilerInternals]. - -Finally, we also support `hoist`, which takes a `scala.meta.Term`, precomputes it in a temporary variable -outside the meta expansion and returns a reference to it. -Apart from `inline`-compatible precomputation of prefixes and arguments, -this functionality seems relevant to solving the problem of sharing expansions of [implicit materializers][Materialization], -so we are confident that it's a useful addition to the macro API. - -## Design considerations - -### Scala.meta - -Scala.meta is a clean-room implementation of a metaprogramming toolkit for Scala, -designed to be simple, robust and portable. We are striving for scala.meta to become a successor of scala.reflect, -the current de facto standard in the Scala ecosystem. - -We have recently released Scala.meta 1.0.0 that features support for syntactic APIs, such as parsing, tokenization, -quasiquotes and prettyprinting. We are currently working on Scala.meta v2 that will enable semantic APIs, such as -typechecking, name resolution and others. - -In [Appendix C][AppendixMeta], we provide a high-level overview of the architecture of scala.meta -along with several practical examples that illustrate its functionality. - -### Tool support - -The key innovation of the new macro system is the fact that it's based on scala.meta, which finally makes it feasible to -provide third-party implementations of mirrors. - -There now exists a prototype implementation of an IntelliJ mirror, and, in further effort of Mikhail Mutcianko from the IntelliJ team, -this mirror has become the foundation for [an interactive expander of new-style macro annotations][PrototypeIntellij]. -This recent advancement strongly suggests that it was the right choice to bet on scala.meta to fix -code compehension and error reporting issues with the current macro system. - -This takes some pressure off whitebox macros. In the current macro system, there is a preference towards blackbox macros, -because they are much friendlier to IntelliJ. Once we have a fully-working mirror for IntelliJ, user experience of blackbox -and whitebox macros should be equivalent. For additional discussion of whiteboxity from a language design and compiler development -perspective, refer to ["Losing whiteboxity"][Whiteboxity]. - -Improvements in support for incremental compilation, testing and debugging also hinge on a capability of scala.meta -to enable custom mirror implementations. -However, they also require significant new functionality to be developed in the corresponding tools -([additional dependency tracking mechanisms for the incremental compiler][SbtMacroSupport] and changes to the vanilla debugger in IDEs). - -### Losing whiteboxity - -It is desirable for the new design to provide reasonable feature parity with the -current macro system. So far, the biggest digression from this course is giving up whitebox expansion. -In this section, we discuss what it will cost us to follow this through, identify the aspects of the new design that -prevent whiteboxity and propose alternatives. - -The main motivation for getting rid of whitebox expansion is simplification - both of the macro expansion pipeline -and the typechecker. Currently, they are inseparably intertwined, complicating both compiler evolution and tool support. -Therefore, the new design tries to disentangle these systems. - -Let's recapitulate the limitations that def macro expansion applies to applications of blackbox macros, -outlining the most important use cases that blackboxity cannot express. This won't give us the full picture, -because there are many macros in the wild that we haven't classified, but nonetheless it will provide an understanding -of the significant chunk of the Scala macros ecosystem. - - 1. When an application of a blackbox macro expands into a tree `x`, the expansion is wrapped into a type ascription `(x: T)`, -where `T` is the declared return type of the blackbox macro def with type arguments and path dependencies applied in consistency -with the particular macro application being expanded. -This invalidates blackbox macros as an implementation vehicle for [anonymous type providers][AnonymousTypeProviders]. - - 1. When an application of a blackbox macro is used as an implicit candidate, no expansion is performed until the macro -is selected as the result of the implicit search. -This makes it impossible to dynamically calculate availability of implicit macros, -precluding some advanced aspects of [materialization][Materialization]. - - 1. When an application of a blackbox macro still has undetermined type parameters after the Scala type inference algorithm has finished -working, these type parameters are inferred forcibly, in exactly the same manner as type inference happens for normal methods. -This makes it impossible for blackbox macros to influence type inference, prohibiting [fundep materialization][Materialization]. - - 1. When an application of a blackbox macro is used as an extractor in a pattern match, -it triggers an unconditional compiler error, preventing [customizations of pattern matching implemented with macros][ExtractorMacros]. -This precludes blackbox macros from providing precise types to values extracted from patterns written in external DSLs, -preventing a library-based implementation of quasiquotes. - -As we can see, whitebox expansion plays an important role in several use cases, the most practically significant -of them being fundep materialization and quasiquote patterns. Fundep materialization is paramount to the design of Shapeless. -Quasiquote patterns are an integral part of writing any kinds of macros - both blackbox and whitebox - which is the main -reason to use scala.reflect. - -It is now clear that our desire for simplification is at odds with the ways how the Scala community uses macros. -In order to resolve the apparent conflict, we outline several solutions, whose evaluation we leave for later. - -**Give up on simplification**. This is probably the most obvious approach, in which we admit -that tight coupling with the typechecker is intrinsic to the essence of Scala macros and change the new design -to enable whitebox expansion. - -Concretely, accommodating whiteboxity in the new macro system requires changing the aspects of the new design -specified in ["Inline reduction"][InlineExpansion] and ["Meta expansion"][MetaExpansion] according to the -plan provided below. - - * Force inline reductions and meta expansions inside the typechecker. Currently, both the rules of inline reduction -and the rules of meta expansion are intentionally vague about the exact point in the compilation pipeline that does expansions, -but whiteboxity will leave us no room for that. - * Delay typechecking of the bodies of inline vals and defs until their expansion. Meta expressions inside inline definitions -are not expanded, which means that eager typechecking of these definitions precludes whitebox expansion. - * Allow using meta expressions without expected type. This captures the main idea of whitebox expansion, in which compile-time -metaprogramming has the final say about the type of transformed snippets of code. - -**Assimilate the most popular use cases**. Instead of supporting the general notion of whiteboxity, -we can introduce dedicated compiler support for the most popular uses cases including the `Generic` -mechanism in Shapeless and quasiquote patterns in scala.reflect. - -This is an attempt at a compromise. On the one hand, this approach allows us to follow through with simplification. -On the other hand, it significantly minimizes the impact on the existing users of whitebox macros. - -The downside of this solution is that it requires an extensive design process (because it involves adding new language features to Scala) -and assumes that the internalized techniques have reached their final form. If a new version of Shapeless -or a new version of scala.reflect (read: scala.meta) decide to adapt their designs after these designs have been assimilated, -they will have a very hard time doing that. - -**Dedicated support for type-level computations**. Manifestations of whiteboxity are quite diverse, -but a lot of them are reducible to type-level computations. - -For example, let's take a macro `join` that takes two objects and outputs an object that -has fields of both. Since Scala doesn't have row polymorphism, it is impossible to write a type signature -for this macro, so we have to declare it as whitebox. - -``` -scala> def join(x: Any, y: Any): Any = macro ... -defined term macro join: (x: Any, y: Any)Any - -scala> join(new { val x = 2 }, new { val y = 3 }) -res0: AnyRef{val x: Int; val y: Int} = $anon$1@64af328d -``` - -Here we can see how the whitebox macro encapsulates a type-level computation that takes -the types of both arguments (`AnyRef{ val x: Int }` and `AnyRef{ val y: Int }`) -and merges them into the result type. Since this computation doesn't involve the abstract syntax trees -of the arguments, the whitebox part of the macro can be extracted into a helper, making the macro itself -blackbox. - -``` -scala> :paste -// Entering paste mode (ctrl-D to finish) - -trait Join[T, U, V] -object Join { - implicit def materialize[T, U, V]: Join[T, U, V] = macro ... -} - -// Exiting paste mode, now interpreting. - -defined trait Join -defined object Join - -scala> def join[T, U, V](x: T, y: U) - | (implicit ev: Join[T, U, V]): V = macro ... -defined term macro join: [T, U, V](x: T, y: U)... -``` - -This approach can express some macros that refine their return type, all fundep materialization macros, -and even some macros that dynamically compute availability of implicits (such macros can be modified to take -an additional implicit parameter whose failure to materialize can be used to control availability of the enclosing implicit) - -that is, all macros whose whiteboxity depends only on types of their prefix and arguments. - -Now, after eligible whitebox macros are rewritten this way, we can replace the whitebox materializers -that compute types, e.g. `Join.materialize`, with a dedicated language feature that natively expresses them. -The listing below provides a sketch of an imaginary syntax that assumes inline types and type-generating meta expressions. - -``` -inline type Join[T, U] = meta { - import scala.meta._ - val jointVals = union(T, U) - t"{ ..$jointVals }" -} - -inline def join[T, U](x: T, y: U): Join[T, U] = meta { ... } -``` - -From the discussion above, we can see that whiteboxity is an important feature of the current macro system -and is used in multiple highly popular open-source libraries. As a result, giving up whiteboxity -may lead to undesired practical consequences. - -More work is needed to reconcile the design of the new macro system -and existing use cases, and in this section we provided several approaches to addressing this need. In the opinion of the author, -the approach that involves dedicated support to type-level computations is the most promising, because it both simplifies -the macro system and provides support for the most important use cases of whiteboxity. - -### Losing compiler internals - -One of the main goals of this proposal is to stop exposing overcomplicated and brittle compiler internal APIs -in order to make macros more accessible and more robust. - -However, some of the compiler APIs may actually capture useful idioms that we may be able to expose in a principled fashion. -`c.internal.enclosingOwner` immediately comes to mind here. - -More work in collaboration with macro authors is needed to make sure that we don't unnecessarily break existing macros -in the name of elusive conceptual purity. - -### Macro annotations - -Much like the current macro system can get extended to support macro annotations, -the new macro system can get extended to support new-style macro annotations that provide similar functionality. - -``` -import scala.annotation.StaticAnnotation - -class h2db(url: String) extends StaticAnnotation { - inline def apply(defns: Any): Any = meta { - ... - } -} - -object Test { - def main(args: Array[String]): Unit = { - @h2db("coffees") object Db - val brazilian = Db.Coffees.insert("Brazilian", 99.0) - Db.Coffees.update(brazilian.copy(price = 100.0)) - println(Db.Coffees.all) - } -} -``` - -In the current macro system, a macro annotation is a subclass of `StaticAnnotation` that define -a macro def called `macroTransform`. - -Analogously, in the new design, a macro annotation is a subclass of `StaticAnnotation` -that defines an inline def called `apply`. We decided to change the magic name, because the old one no longer applies. -We also simplified the signature to take a block wrapping the definitions being expanded and returns a block wrapping expansion results, -i.e. `Any => Any`, as opposed to having `Any* => Any` in the current system. - -Expansion of new-style macro annotations is very similar to expansion of vanilla macro annotations. -The only difference is that we only provide syntactic APIs, informed about [the limitations][AnnotationsTypecheck] -brought by exposing semantic APIs in macros that generate top-level definitions. -Concretely, meta scopes in macro annotations expose a `Dialect` capability instead of a `Mirror`. -As a result, we can afford to expand on enter without any limitations to the shape of expansion. - -### Why inline - -The main motivation behind inline is to provide a templating system that can express simple use cases -of compile-time metaprogramming in an lightweight declarative style that minimizes explicit introspection. - -For example, in one of the code snippets that illustrates inline defs and inline parameters, we can use the newly -introduced mechanism to express partial evaluation. Thanks to constant folding facilities built into the compiler, -usages of the `pow` method provided below will expand into a sequence of multiplications - all that without -a single line of macro code. - -``` -inline def pow(b: Double, inline n: Int): Double = { - if (n == 0) 1 - else b * pow(b, n - 1) -} -``` - -### Out of scope - -This proposal addresses a lot of pain points of the current macro system, but it doesn't talk about two very common -problems: lack of hygiene and presence of the separate compilation restriction. - -These two problems have a lot in common: we have experimented with both of them, our initial results are promising but insufficient, -both of them can be developed independently of inline/meta. - -Given that both hygiene and joint compilation still require significant research to materialize, -we decided not to include them in this proposal. We think that even without these features, inline/meta represents a significant -improvement over the state of the art, so we leave them for future work that may be submitted in follow-up SIPs when it's done. - -## Conclusion - -Pioneered by def macros and macro annotations, -the area of language-integrated compile-time metaprogramming in Scala has shown significant practical value. - -During the last several years, we have been utilizing and maintaining the current macro system in industrial projects. -Learning from this experience, we have created a new design based on `inline` and `meta` that provides -comparable functionality and avoids the most common pitfalls of existing macros. - -The user interface of the new system is a conservative evolution of def macros. -[Inline defs][InlineDefs] work similarly to macro defs, and -[meta expressions][MetaExprs] play the compile-time execution role of macro impls. -These new language features are designed to be used together, -and in this capacity their look and feel can hardly be distinguished from that of def macros. - -The metaprogrammer interface of the new system is a drastic redesign. We have merged macro defs and macro impls, -and, more importantly, we have switched the underlying metaprogramming API from scala.reflect to [scala.meta][ScalaMetaSection]. -This has allowed us to make significant improvements in robustness and tool support. - -The main open question of the new design is [whether whiteboxity will stay or will be removed][Whiteboxity] from the new macro system. -We also need to figure out [which internal compiler APIs we may want to approximate][CompilerInternals] in the new macro system. -Future work outside the scope of this proposal includes -hygiene and lifting the separate compilation restriction. - -At the time of writing, `inline` and `meta` are partially implemented in [a prototype compiler plugin for Scala 2.11][PrototypeScalac] -and [an accompanying experimental branch of IntelliJ][PrototypeIntellij]. -We are excited with our initial results and are planning to develop the new design further. - -## Credits - -This design was created by Eugene Burmako, Denys Shabalin and Martin Odersky -and was further elaborated together with other members of the inline working group at EPFL: -Sébastien Doeraene, Vojin Jovanovic and Dmitry Petrashko. - -Over time, the ideas behind the design were refined based on experiments carried out by: -Uladzimir Abramchuk, Igor Bogomolov, Mathieu Demarne, Martin Duhem, Adrien Ghosn, Zhivka Gucevska, -Mikhail Mutcianko, Dmitry Naydanov, Artem Nikiforov, Vladimir Nikolaev, Jatin Puri and Valentin Rutz. - -The prototype of scalac integration was developed by Eugene Burmako with open-source contributions from -Tamer Mohammed Abdul-Radi, David Dudson, Takeshi D. Itoh, Oleksandr Olgashko and Hiroshi Yamaguchi. - -The prototype of IntelliJ integration was developed by Mikhail Mutcianko. - -## Feedback - -In order to centralize the discussion, post your feedback and ideas to [http://gitter.im/scalameta/sips][FeedbackWebsite]. -Once we submit this document as a full-fledged SIP, we will update this section to include the official discussion forum -mandated by the SIP process. - -## References - - 1. [Prototype of scalac integration][PrototypeScalac] - 1. [Prototype of IntelliJ integration][PrototypeIntellij] - 1. [(Appendix A) Def macros: feature interaction][AppendixInteraction] - 1. [(Appendix B) Def macros: macro expansion][AppendixExpansion] - 1. [(Appendix C) Scala.meta: high-level overview][AppendixMeta] - -[ScalaMetaSection]: #scalameta -[ScalaMetaWebsite]: http://scalameta.org/ -[MacroUsecases]: http://scalamacros.org/paperstalks/2014-02-04-WhatAreMacrosGoodFor.pdf -[PrototypeScalac]: https://github.com/scalameta/paradise -[PrototypeIntellij]: https://www.youtube.com/watch?v=IPnd_SZJ1nM&feature=youtu.be&t=1360 -[Intuition]: #intuition -[LanguageFeatures]: #language-features -[InlineDefs]: #inline-definitions -[InlineExpansion]: #inline-reduction -[MetaExprs]: #meta-expressions -[MetaExpansion]: #meta-expansion -[MetaApis]: #meta-apis -[Whiteboxity]: #losing-whiteboxity -[CompilerInternals]: #losing-compiler-internals -[Hygiene]: #hygiene -[SeparateCompilation]: #separate-compilation-restriction -[Linq]: http://dl.acm.org/citation.cfm?id=1142552 -[Materialization]: http://docs.scala-lang.org/overviews/macros/implicits.html -[SbtMacroSupport]: https://github.com/sbt/sbt/issues/1729 -[AnonymousTypeProviders]: http://docs.scala-lang.org/overviews/macros/typeproviders.html#anonymous-type-providers -[ExtractorMacros]: https://docs.scala-lang.org/overviews/macros/extractors.html -[AnnotationsTypecheck]: https://github.com/scalamacros/paradise/issues/75 -[FeedbackSection]: #feedback -[FeedbackWebsite]: http://gitter.im/scalameta/sips -[AppendixInteraction]: https://gist.github.com/xeno-by/e26a904051a171e4bc8b9096630220a7 -[AppendixExpansion]: https://gist.github.com/xeno-by/5dde62aedcc23afc85ecf4d795ac67c2 -[AppendixMeta]: https://gist.github.com/xeno-by/9741ce7532cb30368b3753521bbfce4e diff --git a/_sips/sips/2017-01-11-refer-other-arguments-in-args.md b/_sips/sips/2017-01-11-refer-other-arguments-in-args.md deleted file mode 100644 index ee6c66f91c..0000000000 --- a/_sips/sips/2017-01-11-refer-other-arguments-in-args.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-NN - Allow referring to other arguments in default parameters - -vote-status: pending -permalink: /sips/:title.html -redirect_from: /sips/pending/refer-other-arguments-in-args.html ---- - -**By: Pathikrit Bhowmick** - -## History - -| Date | Version | -|---------------|------------------| -| Jan 11th 2017 | Initial Draft | -| Jan 12th 2017 | Initial Feedback | -| Jan 16th 2017 | Minor Changes | - -## Introduction -Currently there is no way to refer to other arguments in the default parameters list: - -Does not compile: -```scala -def substring(s: String, start: Int = 0, end: Int = s.length): String -``` - -The workaround to achieve this is by using a curried-function: -```scala -def substring(s: String, start: Int = 0)(end: Int = s.length): String -``` - -However, the above workaround is not always suitable in all situations since you may not want a curried function. - -The other more verbose alternative is by overloading: -```scala -def substring(s: String, start: Int): String - = substring(s, start = 0, end = s.length) -def substring(s: String, start: Int = 0, end: Int): String -``` - -The above is quite verbose as it required 1 extra function definition per argument that refers other args. - -### Proposal -Allow to refer to ***any*** parameters in the same (or left) curried parameter list: -```scala -def substring(s: String, start: Int = 0, end: Int = s.length) // Legal -def substring(start: Int = 0, end: Int = s.length, s: String) // Legal !!! -def substring(s: String, start: Int = 0)(end: Int = s.length) // Legal (works currently) -def substring(start: Int = 0, end: Int = s.length)(s: String) // Illegal -``` - -The same applies for class arguments: -```scala -class Substring(s: String, start: Int = 0, end: Int = s.length) // Legal -class Substring(start: Int = 0, end: Int = s.length, s: String) // Legal -class Substring(s: String, start: Int = 0)(end: Int = s.length) // Legal -class Substring(start: Int = 0, end: Int = s.length)(s: String) // Illegal -``` - -We should also be able to refer to ***multiple*** parameters: -```scala -def binarySearch(start: Int, end: Int, middle: Int = (start + end)/2) // Legal -``` - -# Motivating examples: - -TBD - -## Interactions with other syntax - -#### Partially Applied Functions: -Works as expected: -```scala -def substring(s: String, start: Int = 0, end: Int = s.length) - -substring(_, start = 0, end = 5) // Legal -substring(_, end = 5) // Legal (start = 0) -substring(_, start = 5) // Legal (same as s => substring(s, start = 5, end = s.length) -``` - -#### Multiple Implicit Parameters -[Multiple implicit parameters](https://github.com/scala/docs.scala-lang/pull/520) should also be allowed to refer to one another (left to right): -```scala -def codec[A](data: A)(implicit encoder: Encoder[A])(implicit decoder: Decoder[A] = encoder.reverse) // Legal -``` - -#### Referring to type members: -The default parameters should be able to refer to type members of other arguments e.g.: -```scala -trait Codec { - type Input - type Output -} - -def codec(codec: Codec, in: codec.Input, out: codec.Output) // Legal !!! -``` - -### Other languages -The following languages allow referring to previously declared arguments in the function signature: -* [CoffeeScript](http://coffeescript.org/) -* [Kotlin](http://kotlinlang.org) -* [TypeScript](https://www.typescriptlang.org/) - -AFAIK, there are no major languages where referring to parameters declared to the ***right*** is allowed. - -### Discussions -[Scala Lang Forum](https://contributors.scala-lang.org/t/refer-to-previous-argument-in-default-argument-list/215/6) diff --git a/_sips/sips/2017-01-13-binary-compatibility.md b/_sips/sips/2017-01-13-binary-compatibility.md deleted file mode 100644 index f860dbc678..0000000000 --- a/_sips/sips/2017-01-13-binary-compatibility.md +++ /dev/null @@ -1,300 +0,0 @@ ---- -layout: sip -title: SIP-NN - Improving binary compatibility with @stableABI -discourse: true - -vote-status: pending -permalink: /sips/:title.html -redirect_from: /sips/pending/binary-compatibility.html ---- - -__Dmitry Petrashko__ - -__first submitted 13 January 2017__ - -## Introduction - -Scala is a language which evolves fast and thus made a decision to only promise binary compatibility across minor releases\[[3]\]. -At the same time, there is a demand to develop APIs that live longer than a major release cycle of Scala. -This SIP introduces an annotation `@stableABI` that checks that `what you write is what you get`. - -`@stableABI` is a linter, that does not change binary output, but will fail compilation if Public API of a class uses features -of Scala that are desugared by compiler and may be binary incompatible across major releases. - -As long as declarations in source have not changed, `@stableABI` annotated classes will be compatible across major versions of Scala. -It complements MiMa\[[2]\] in indicating if a class will remain binary compatible across major Scala releases. - -## Term definitions - -* ##### Binary descriptors - -As defined by the JVM spec\[[4]\]: - - > A descriptor is a string representing the type of a field or method. Descriptors are represented in the class file format using modified UTF-8 strings (§4.4.7) - > and thus may be drawn, where not further constrained, from the entire Unicode codespace. - > - > A method descriptor contains zero or more parameter descriptors, representing the types of parameters that the method takes, and a return descriptor, representing the type of the value (if any) that the method returns. - - Binary descriptors are used in the bytecode to indicate what fields and methods are accessed or invoked. - If a method or field has its descriptor changed, previously compiled classes that used different descriptor will fail in - runtime as they no longer link to the changed field. - - In this document we use the term `binary descriptor` to refer to both method and field descriptors used by the JVM. - -* ##### Public API - - Methods and fields marked with `ACC_PUBLIC`\[[5]\] may be accessed from any class and package. - This loosely corresponds to absence of AccessModifier\[[6]\] in Scala source. - Changing a binary descriptor of a method or a field marked with `ACC_PUBLIC` is a binary incompatible change - which may affect all classes in all packages leading to a runtime linkage failure. - - Methods and fields marked with `ACC_PROTECTED`\[[5]\] may be accessed within subclasses. - This loosely corresponds to presence of `protected` AccessModifier\[[6]\] in Scala source. - Changing a binary descriptor of a method or a field marked with `ACC_PROTECTED` is a binary incompatible change - which may affect all subclasses of this class leading to a runtime linkage failure. - - In this document we use the term `Public API` to refer both to methods and fields defined as `ACC_PUBLIC` and `ACC_PROTECTED`. - Changes do binary descriptors of Public API may lead to runtime linkage failures. - -* ##### Binary compatibility - - Two versions of the same class are called binary compatible if there are no changes to the Public API of this class, - meaning that those two classes can be substituted in runtime without linkage errors. - -## Use cases - -1. Publishing a library that would work across major Scala versions, such as 2.12 & 2.13 and Dotty. -2. Defining a class which is supposed to be used from other JVM languages such as Java\Kotlin. -`@stableABI` will ensure both binary compatibility and that there are no unexpected methods - that would show up in members of a class or an interface. -3. Library authors can take advantage of language features introduced in new major versions of Scala - while still serving users on older language versions by defining their Public API as `@stableABI`. - -The important use-case envisioned here by the authors is migration to Dotty. -We envision that there might be code-bases that for some reason don't compile either with Dotty or with Scalac. -This can be either because they rely on union types, only present in Dotty, -or because they need early initializers, which are only supported by Scalac. - -At the same time, by marking either those classes themselves or their parents as `@stableABI`, -the compiled artifacts could be used in both Dotty-compiled and Scalac-compiled projects. - - -## Current Status -In case there's a need to develop an API that will be used by clients compiled using different major versions of Scala, -the current approach is to either develop them in Java or to use best guess to restrict what Scala features should be used. - -There's also a different approach which is used by sbt: instead of publishing a binary `compiler-interface`, sources are published instead that would be locally compiled. - -Examples: - - 1. Zinc\[[8]\] is writing their interfaces in Java because the interface has to be Scala version agnostic, as it is shipped in every sbt release, independently of Scala version that was used to compile zinc or will be used in to compile the project. -sbt additionally compiles on demand the compiler bridge, which implements this Java interface. - - 2. Dotty\[[7]\] currently uses java defined interfaces as public API for IntelliJ in order to ensure binary compatibility. -These interfaces can be replaced by `@stableABI` annotated traits to reach the same goal. - -## Design Guidelines -`@stableABI` is a feature which is supposed to be used by a small subset of the ecosystem to be binary compatible across major versions of Scala. -Thus this is designed as an advanced feature that is used rarely and thus is intentionally verbose. -It's designed to provide strong guarantees, in some cases sacrificing ease of use and to be used in combination with MiMa\[[2]\] - -The limitations enforced by `@stableABI` are designed to be an overapproximation: -instead of permitting a list of features known to be compatible, `@stableABI` enforces a stronger -check which is sufficient to promise binary compatibility. - -This SIP intentionally follows a very conservative approach. -This is because we will be able to allow more features later, but we won't have an opportunity to remove them. - -## Overview ## -In order for a class, trait or an object to succeed compilation with the `@stableABI` annotation it has to be: - - - defined on the top level; - - if a class or an object has a companion annotated with `@stableABI`, than annotation applies to both of them; - - use a subset of Scala that during compilation does not require changes to public API of the class, including - - synthesizing new members, either concrete or abstract; - - changing binary descriptors of existing members, either concrete or abstract; - -`@stableABI` does not change the compilation scheme of a class: - compiling a class previously annotated with the `@stableABI`, will produce the same bytecode with or without `@stableABI` annotation. - -Below are several examples of classes and traits that succeed compilation with `@stableABI` - -{% highlight scala %} -@stableABI -trait AbstractFile { - def name(): String - - def path(): String - - def jfile(): Optional[File] -} - -@stableABI -trait SourceFile extends AbstractFile { - def content(): Array[Char] -} - -@stableABI -trait Diagnostic { - def message(): String - - def level(): Int - - def position(): Optional[SourcePosition] -} - -@stableABI -object Diagnostic { - @static final val ERROR: Int = 2 - @static final val WARNING: Int = 1 - @static final val INFO: Int = 0 -} - -@stableABI -class FeaturesInBodies { - def apiMethod: Int = { - // as body of the method isn't part of the public interface, one can use all features of Scala here. - lazy val result = 0 // while lazy vals are prohibited in the class, they are allowed in the bodies of methods - result - } -} -{% endhighlight %} - -## Features that will fail compilation with `@stableABI` -The features listed below have complex encodings that may change in future versions. We prefer not to compromise on them. -Most of those features can be simulated in a binary compatible way by writing a verbose re-implementation -which won't rely on desugaring performed inside compiler. -Note that while those features are prohibited in the public API, they can be safely used inside bodies of the methods. - - - public fields. Can be simulated by explicitly defining public getters and setters that access a private field; - - lazy vals. Can be simulated by explicitly writing an implementation in source; - - case classes. Can be simulated by explicitly defining getters and other members synthesized for a case class(`copy`, `productArity`, `apply`, `unapply`, etc). - -The features listed below cannot be easily re-implemented in a class or trait annotated with `@stableABI`. - - - default arguments; - - default methods. See Addendum; - - constant types(both explicit and inferred); - - inline. - -## Binary compatibility and transitivity ## -Consider a class, that is binary compatible but takes a non-binary compatible argument: - -{% highlight scala %} -@stableABI -class Example { - def foo[T](a: MyOption[T]): T = a.get -} - -trait MyOption[T]{ - lazy val get: T = ??? -} -{% endhighlight %} - - -Consider a situation when we re-compile `MyOption` using a different major compiler version than the one used to compile `Example`. -Let's assume the new major version of compile has changing binary descriptor of method `get`. - -While the code in runtime would still successfully invoke the method `Example.foo`, this method will fail in execution, -as it will itself call a `MyOption.get` using an outdated descriptor. - -While in perfect world it would be nice to require all `@stableABI` classes and traits to only take `@stableABI` arguments -and only return `@stableABI` values, we believe that all-or-nothing system will be a lot harder to adopt and migrate to. - -Because of this we propose to emmit warnings in those cases: - - - non-`@stableABI` value is returned from a method or field defined inside a `@stableABI` class or trait; - - an invocation to a method not-defined inside a `@stableABI` class is used in - implementation of a method or a field initializer inside a `@stableABI` class or trait. - -Those warnings can be suppressed using an `@unchecked` annotations or made fatal using `+Xfatal-warnings`. - -## The case of the standard library ## -The Standard library defines types commonly used as arguments or return types such as `Option` and `List`, -as well as methods and implicit conversions imported from `scala` and `Predef`. - -As such Standard library is expected to be the biggest source of warnings defined in previous section. - -We propose to consider either making some classes in standard library use `@stableABI` or define new `@stableABI` -super-interfaces for them that should be used in `@stableABI` classes. -This would also allow to consume Scala classes from other JVM languages such as Kotlin and Java. -## `@stableABI` and Scala.js - -Allowing to write API-defining classes in Scala instead of Java will allow them to compile with Scala.js, -which would have benefit of sharing the same source for two ecosystems. - -Scala.js currently is binary compatible as long as original bytecode compiled by Scala JVM is binary compatible. -Providing stronger binary compatibility guarantees for JVM will automatically provide stronger guarantees for Scala.js. - - -## Comparison with MiMa ## -The Migration Manager for Scala (MiMa in short) is a tool for diagnosing binary incompatibilities for Scala libraries. -MiMa allows to compare binary APIs of two already compiled classfiles and reports errors if APIs do not match perfectly. - -MiMa and `@stableABI` complement each other, as `@stableABI` helps to develop APIs that stay compatible -across major versions, while MiMa checks that previously published artifacts indeed have the same API. - -`@stableABI` does not compare the currently compiled class or trait against previous version, -so introduction of new members won't be prohibited. This is a use-case for MiMa. - -MiMa does not indicate how hard, if possible, would it be to maintain compatibility of a class across future versions of Scala. -Multiple features of Scala, most notably lazy vals and traits, have been compiled differently by different Scala versions -making porting existing compiled bytecode across versions very hard. -MiMa will complain retroactively that the new version is incompatible with the old one. -`@stableABI` will instead indicate at compile time that the old version used features whose encoding is prone to change. -This provides early guidance and warning when designing long-living APIs before they are publicly released. - -## Compilation scheme ## -No modification of typer or any existing phase is planned. The current proposed scheme introduces a late phase that runs before the very bytecode emission that checks that: - - - classes, traits and objects annotated as `@stableABI` are on the top level; - - compiler did not introduce new Public API methods or fields inside `@stableABI` classes, traits and objects; - - compiler did not change descriptors of existing Public API methods or fields inside `@stableABI` classes, traits and objects. - -This phase additionally warns if Public API method or field takes an argument or returns a value that isn't marked as `@stableABI`. -This warning can be suppressed by annotating with `@unchecked`. - -The current prototype is implemented for Dotty and supports everything described in this SIP, except warnings. -The implementation is simple with less than 50 lines of non-boilerplate code. -The current implementation has a scope for improvement of error messages that will report domain specific details for disallowed features, -but it already prohibits them. - -## Addendum: Default methods ## -By `default methods` we mean non-abstract methods defined and implemented by a trait. - -The way how those methods are implemented by compiler has changed substantially over years. -At the same time, `invokeinterface` has always been a reliable way to invoke such a method, -independently from how it was implemented under the hood. - -One might reason that, as there has been a reliable way to call methods on the binary level, -it should be allowed to use them in binary compatible APIs. - -At the same time, the mixin composition protocol that is followed when a class inherits those traits has also -changed substantially. -The classes which have been correctly inheriting those traits compiled by previous versions of Scala -may need recompilation if trait has been recompiled with a new major version of Scala. - -Thus, the authors of this SIP has decided not to allow default methods in the -`@stableABI` traits. - -## See Also ## - - 1. [dotty#1900][1] - 2. [MiMa][2] - 3. [releases-compatibility][3] - 4. [Descriptor definition in JVM Specification][4] - 5. [JVM access flags][5] - 6. [Scala AccessModifiers][6] - 7. [Dotty interfaces][7] - 8. [Zinc interfaces][8] - - -[1]: https://github.com/lampepfl/dotty/pull/1900 "an implementation for Dotty" -[2]: https://github.com/typesafehub/migration-manager "MiMa" -[3]: http://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html "Binary compatibility of Scala releases" -[4]: http://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.3 "Descriptor definition in JVM Specification" -[5]: http://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.6-200-A.1 "JVM access flags" -[6]: http://www.scala-lang.org/files/archive/spec/2.11/05-classes-and-objects.html#modifiers "Scala AccessModifiers" -[7]: https://github.com/lampepfl/dotty/tree/master/interfaces/src/dotty/tools/dotc/interfaces "Dotty interfaces" -[8]: https://github.com/sbt/zinc/tree/v1.0.0/internal/compiler-interface/src/main/java/xsbti "zinc interfaces" - diff --git a/_sips/sips/2017-02-22-comonadic-comprehensions.md b/_sips/sips/2017-02-22-comonadic-comprehensions.md deleted file mode 100644 index 3b56dacf2b..0000000000 --- a/_sips/sips/2017-02-22-comonadic-comprehensions.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-NN - comonadic-comprehensions - -vote-status: rejected -permalink: /sips/:title.html -redirect_from: /sips/pending/comonadic-comprehensions.html ---- - -**By: Shimi Bandiel** - -## History - -| Date | Version | -|---------------|---------------| -| Feb 22nd 2017 | Initial Draft | - -## Motivation - -Scala provides a concise syntax for working with Monads(map & flatMap): -the for comprehension. - -Following is a proposal for a concise syntax for working with Comonads(map, extract & coflatMap): -the cofor comprehension. - -The proposal has an existing implementation in PR 5725 - -## Motivating Examples - -### Examples - -Consider the following class: - -{% highlight scala %} - -case class StreamZipper[A](left: Stream[A], focus: A, right: Stream[A]) { - def map[B](f: A => B): StreamZipper[B] = - StreamZipper(left.map(f), f(focus), right.map(f)) - def extract: A = - focus - def coflatMap(f: StreamZipper[A] => B): StreamZipper[B] = - ??? -} - -{% endhighlight %} - -StreamZipper[A] represents a non-empty Stream of As with a cursor (focus). - -
              -
            • The map method invokes f on every element and produces a StreamZipper of -the results.
              • -
            • The extract method returns the value at the cursor
              • -
            • The coflatMap method invokes f on every cursor (all possible zippers) providing a contextual global operation. -The result is a StreamZipper[B] of the results with a cursor pointing at the same location as this. -
              • -
            - -The above implementation for `coflatMap` was left out for brevity. See [3]. - -Now, consider the following methods: -{% highlight scala %} - - // returns whether the current cursor in a zipper of ints is between the previous - // and the next numbers. - def isInTheMiddle(z : StreamZipper[Int]): Boolean = - z match { - case StreamZipper(pi +: _, i, ni +: _) if (pi < i && i < ni) => true - case _ => false - } - - // counts how many consecutive values of true starting from the cursor - def numberOfTrues(z: StreamZipper[Boolean]) : Int = - if (z.focus) 1 + z.right.takeWhile(true ==).size else 0 - -{% endhighlight %} - -And, let's say we have a StreamZipper[Person]: -{% highlight scala %} - case class Person(name: String, age: Int) - - // a given stream with cursor at some position - val people: StreamZipper[Person] = ??? -{% endhighlight %} - -We would like to get the following: -{% highlight scala %} - - /* - * A StreamZipper of triplets containing: - * _1 -- the original Person value. - * _2 -- whether this Person's age is higher than the previous and lower than the next. - * We'll call this boolean TAG. - * _3 -- how many consecutive TAGs with value "true" starting from current cursor. - */ - val goal: StreamZipper[(Person, Boolean, Int)] = ??? - -{% endhighlight %} - -It seems we can re-use the isInTheMiddle and numberOfTrues methods. -However, without the proposed cofor syntax we'll probably end with: -{% highlight scala %} - val goal = people.map(p => (p, p.age)).coflatMap { zipperOfTuple => - val ages = zipperOfTuple.map(_._2) - (zipperOfTuple.extract._1, isInTheMiddle(ages)) - }.coflatMap { zipperOfTuple => - val tags = zipperOfTuple.map(_._2) - val persons = zipperOfTuple.map(_._1) - val trues = numberOfTrues(tags) - persons.extract, tags.extract, trues) - } -{% endhighlight %} -From the code above, you can see that it is quite cumbersome to handle the passing of -the context between the invocations of coflatMap. - -The proposed syntax allows for the following usage: -{% highlight scala %} - val flow : StreamZipper[Person] => (Person, Boolean, Int) = - cofor (p @ Person(_, age)) { - tag <- isInTheMiddle(age) - count <- numberOfTrues(tag) - } yield (p.extract, tag.extract, count.extract) - - val goal = people.coflatMap(flow) -{% endhighlight %} - - -## Syntax - -The proposed syntax is based on the paper by Dominic Orchard and Alan Mycroft [1]. - -The syntax for `cofor` is defined as: -{% highlight scala %} - cofor (pattern0) { - pattern1 <- generator1 - pattern2 <- generator2 - ... - } yield body - - patternN = regular case patterns - generatorN = expr - body = expr - -{% endhighlight %} - -The result type of a `cofor` expression is a function from the comonad type to -a result (`T[A] => B`). -This means that the return type must be available at call-site! -Note that unlike `for`, guards and assignments are not supported. - -## Desugaring - -A `cofor` desugaring is much more complex than the respective `for`. - -Desugaring example: - -{% highlight scala %} - val flow : StreamZipper[Person] => (Person, Boolean, Int) = - cofor (p @ Person(_, age)) { - tag <- isInTheMiddle(age) - count <- numberOfTrues(tag) - } yield (p.extract, tag.extract, count.extract) - - val goal = people.coflatMap(flow) -{% endhighlight %} - -The above `cofor` expression will be desugared into the following function: -{% highlight scala %} - input => { - // desugaring the generators - val enums = - // assign values to input variables - // actual assignment is done through pattern matching - input.map(p => ( - p match { - case p @ Person(_, age) => p - } - , (p match { - case p @ Person(_, age) => age - }, ()))). - coflatMap(env => { - // extracting collected values from the context - val p = env.map(env => env._1) - val age = env.map(env => env._2._1) - // now we pass the current context and the generator result - (isInTheMiddle(age), env.extract) - }).coflatMap(env => { - // extracting collected values from the context - val tag = env.map(env => env._1) - val p = env.map(env => env._2._1) - val age = env.map(env => env._2._2._1) - // now we pass the current context and the generator result - (numberOfTrues(tag), env.extract) - }) - // the body phase (yield) - { - // deconstructing the collected context - val count = enums.map(env => env._1) - val tag = enums.map(env => env._2._1) - val p = enums.map(env => env._2._2._1) - val age = enums.map(env => env._2._2._2._1) - (p.extract, tag.extract, count.extract) - } - } -{% endhighlight %} - -## Drawbacks - -
              -
            1. Adding a new keyword to the language makes it more complex
              2. -
            2. Understanding the desugaring and concept behind cofor is not -trivial and it's much more complex than for (which many developers still -don't feel at ease with).
              3. -
            - - -## References - -1. [A Notation for Comonads][1] -2. [Implementation Pull-Request][2] -3. [StreamZipper Example][3] - -[1]: https://www.cl.cam.ac.uk/~dao29/publ/codo-notation-orchard-ifl12.pdf "codo-notation" -[2]: https://github.com/scala/scala/pull/5725 -[3]: https://github.com/shimib/scala/blob/5e257cd4b371769deafba2be1ae3932d772ca67d/test/files/neg/cofor.scala diff --git a/_sips/sips/2017-10-25-adding-prefix-types.md b/_sips/sips/2017-10-25-adding-prefix-types.md deleted file mode 100644 index 1c9d1aa347..0000000000 --- a/_sips/sips/2017-10-25-adding-prefix-types.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -layout: sip -discourse: true -title: SIP-36 - Adding prefix types - -vote-status: pending -permalink: /sips/:title.html -redirect_from: /sips/pending/adding-prefix-types.html ---- - -**By: Oron Port** - -## History - -| Date | Version | -| ------------- | ---------------------------------------- | -| Oct 25th 2017 | Split prefix types from [SIP33](http://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html), and emphasize motivation | -| Nov 29th 2017 | Updated SIP according to feedback in the PR, and recent update to SIP23 | -| Dec 1st 2017 | Added another use-case for prefix type `~` | - -Your feedback is welcome! If you're interested in discussing this proposal, head over to [this](https://contributors.scala-lang.org/t/sip-nn-make-infix-type-alias-precedence-like-expression-operator-precedence/471) Scala Contributors thread and let me know what you think. - ---- - -## Introduction -Currently scala supports unary prefix operators (`-`, `+`, `~`, `!`) for expressions (e.g., `def unary_-`) and does not support prefix types. See the Scala specification [Prefix Operations](http://scala-lang.org/files/archive/spec/2.12/06-expressions.html#prefix-operations) section. - -**Prefix expression vs. prefix type example**: - -```scala -object PrefixExpression { - case class Nummy(expand : String) { - def unary_- : Nummy = Nummy(s"-$this") - def unary_~ : Nummy = Nummy(s"~$this") - def unary_! : Nummy = Nummy(s"!$this") - def unary_+ : Nummy = Nummy(s"+$this") - } - object N extends Nummy("N") - val n1 = -N - val n2 = ~N - val n3 = !N - val n4 = +N -} -object NonExistingPrefixTypes { - trait unary_-[A] - trait unary_~[A] - trait unary_![A] - trait unary_+[A] - trait N - type N1 = -N //Not working - type N2 = ~N //Not working - type N3 = !N //Not working - type N4 = +N //Not working -} -``` - ---- - -## Motivation -It is easier to reason about the language when mathematical and logical operations for both terms and types are expressed the same. The proposal is relevant solely for projects which utilize numeric literal type operations (supported by SIP23, which was not yet accepted into Lightbend Scala). However, the SIP's implementation is very small and should have minor effect on compiler performance. - -### Motivating examples - -#### Splice prefix types for meta-programming -A requirement for `unary_~` is described by Martin Odersky at [this proposal](https://gist.github.com/odersky/f91362f6d9c58cc1db53f3f443311140). - -#### Singleton-ops library example - -The [singleton-ops library](https://github.com/fthomas/singleton-ops) with [Typelevel Scala](https://github.com/typelevel/scala) (which implemented [SIP-23](http://docs.scala-lang.org/sips/pending/42.type.html)) enable developers to express literal type operations more intuitively. - -Consider the following example, where `foo` has two equivalent implementations, one using types, while the other uses terms: - -```scala -import singleton.ops._ - -object PrefixExample { - /* - We would much rather write the following to acheive more clarity and shorter code: - type Foo[Cond1, Cond2, Num] = ITE[Cond1 && !Cond2, -Num, Num] - */ - type Foo[Cond1, Cond2, Num] = ITE[Cond1 && ![Cond2], Negate[Num], Num] - //foo executes typelevel operations by using singleton-ops - def foo[Cond1, Cond2, Num](implicit f : Foo[Cond1, Cond2, Num]) : f.Out = f.value - //foo executes term operations - def foo(cond1 : Boolean, cond2 : Boolean, num : Int) : Int = - if (cond1 && !cond2) -num else num -} - -import PrefixExample._ - -foo[true, false, 3] //returns -3 -foo(true, false, 3) //returns -3 -``` - -Note: `type ![A]` is possible to define, but `type -[A]` is not due to collision with infix type parsing. - -#### DFiant library example - -DFiant is a domain specific language for hardware description I (Oron) am developing. Hardware interfaces have a direction annotation (e.g., `vec : DFBits[8] <> IN`). Sometime interfaces have multiple ports, in different directions. E.g.: - -```scala -trait MyInterface { - val data : DFBits[32] <> IN - val address : DFBits[32] <> OUT -} -``` - -To be able to use the same interface in reverse, we need the ability to easily express it as: - -```scala -trait MyReversableInterface[D <: Direction] { - val data : DFBits[32] <> D - val address : DFBits[32] <> ~D -} -``` - -An implicit conversion can then assure that `~IN` is translated to `OUT` and vice-versa. - -Interfaces may possess dozens of ports, thus without prefix types can be quite cumbersome. - ---- - -## Proposal - -Add support for prefix types, which is equivalent to the prefix operations for expressions. - -``` -PrefixType ::= [`-' | `+' | `~' | `!'] SimpleType -CompoundType ::= PrefixType - | AnnotType {with AnnotType} [Refinement] - | Refinement -``` - ------- - -## Implementation - -A PR for this SIP is available at: [https://github.com/scala/scala/pull/6148](https://github.com/scala/scala/pull/6148) - ------- - -### Interactions with other language features - -#### Variance Annotation -Variance annotation uses the `-` and `+` symbols to annotate contravariant and covariant subtyping, respectively. Introducing unary prefix types may lead to some developer confusion. However, such interaction is very unlikely to occur. E.g.: - -```scala -trait Negate[A] -trait Positive[A] -type unary_-[A] = Negate[A] -type unary_+[A] = Positive[A] -trait Contravariant[B, -A <: +B] //contravariant A subtype upper-bounded by Positive[B] -trait Covariant[B, +A <: -B] //covariant A subtype upper-bounded by Negative[B] -``` - -#### Negative Literal Types -Negative literal types are annotated using the `-` symbol. This can lead to the following confusion: - -```scala -trait Negate[A] -type unary_-[A] = Negate[A] -trait MyTrait[B] - -type MinusFortyTwo = MyTrait[-42] -type NegateFortyTwo = MyTrait[Negate[42]] -``` - -The above example demonstrates a case of two types `MinusFortyTwo` and `NegateFortyTwo` which are different. They may be equivalent in view (implicit conversion between the two type instances), but they are not equal. - -Note: It is not possible to annotate a positive literal type in Scala (checked both in TLS and Dotty): - -```scala -val a : 42 = +42 //works -val b : -42 = -42 //works -val c : +42 = 42 //error: ';' expected but integer literal found -``` - -This means that if unary prefix types are added, then `+42` will be a type expansion of `unary_+[42]`. - -**Related Issues** -* [Dotty Issue #2783](https://github.com/lampepfl/dotty/issues/2783) -* [Typelevel Scala Issue #157](https://github.com/typelevel/scala/issues/157) (Resolved in recent update to SIP23) - -Dotty's implementation of literal types currently fail compilation when infix types interact with a negative literal type. -```scala -type ~~[A, B] -type good = 2 ~~ 2 -type bad = 2 ~~ -2 //Error:(9, 20) ';' expected but integer literal found. -type work_around = 2 ~~ (-2) //Error in Dotty -``` ----- - -### Bibliography -[Scala Contributors](https://contributors.scala-lang.org/t/sip-nn-make-infix-type-alias-precedence-like-expression-operator-precedence/471) - -[scala-sips](https://groups.google.com/forum/#!topic/scala-sips/ARVf1RLDw9U) diff --git a/_sips/sips/2018-05-26-case-if.md b/_sips/sips/2018-05-26-case-if.md deleted file mode 100644 index b9e6200671..0000000000 --- a/_sips/sips/2018-05-26-case-if.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -layout: sips -discourse: true -title: SIP-NN - Uncluttering Abuse of Match - -vote-status: new -vote-text: -permalink: /sips/:title.html -redirect_from: /sips/pending/case-if.html - ---- - -**By: Som Snytt and A. P. Marki** - -## History - -| Date | Version | -|---------------|----------------| -| May 26th 2018 | Initial Draft | -| May 28th 2018 | Underscoreless | - -## Motivation - -Since the demise of SIP-12, we have relied on Marie Kondo to declutter -what remains of our lives. But we can do better. - -Currently, `case` syntax requires an underscore to represent a pattern, -even if the code of interest is the guard that follows. - -Anxiety over this underscore is expressed in [a StackOverflow question][1] -in which a programmer mulls the question of "Abuse of Match" and whether -it actually makes you go blind. - -We propose to go underscoreless, pace the famous consultancy. - -If we can't have SIP-12 then we can have tidy syntax for `if-then` in `case` blocks. - -Since `Scala <3` abhors two ways of doing a thing, we eliminate underscore -as a pattern. Underscore as a subpattern, that is, as a `pattern2`, is patterned -after placeholder syntax in expressions, just as constructor patterns are patterned -after constructor invocations. We read `C(_)` and `case C(_) =>` to mean construction -of `C` with an argument unspecified. Similarly, just as placeholder syntax is -restricted, so that an underscore is never an `Expr`, pattern syntax must disallow -underscore as a `Pattern` production. - -In fact, underscore never quite functioned that way, since the definition - - val _ = 42 - -has always incorrectly introduced a variable named `_`. - -Suggestions have surfaced that this syntax should mean something entirely different, -namely, the introduction of a freshly named variable which cannot be named in -source code, but induces the evaluation of the RHS of the definition, and which -can be accessed implicitly if defined as an implicit value. - -However that may be, underscore must first be disallowed as a `Pattern`. - -The only way to coherently define a `case` for which no pattern is applied is to omit -the pattern. And in the absence of alternative semantics, `val _` is not meaningful. -Underscore on the RHS of `var` definitions has already been deprecated, and it is -expected that that syntax will also be removed. - -## Syntax - -In lieu of - - 42 match { - case _ if now isAfter midnight => nothingGoodHappens() - case _ => () - } - -we write - - 42 match { - case if now isAfter midnight => nothingGoodHappens() - case => () - } - -The syntax accepts either a pattern with optional guard, or a guard with no pattern: - - CaseClause ::= ‘case’ (Pattern [Guard] | Guard) ‘=>’ Block - Guard ::= ‘if’ PostfixExpr - -## Further Justifications - -In a respected online [forum][2] which brooks no fools, [Mulliganaceous][3] has posted -an "accepted" answer using the idiom, "in case if". This supports `case if` as -a natural locution. - -In a response to one judgment about abuse of match, [one Scala user][4] whose handle I can -never spell quite right let alone pronounce finds the match version -"clearer and visually more pleasant" than the cluttered `if` expression. - -From the beginning, Scala has made great strides in reducing vertical space in source code. -However, we are still constrained horizontally, despite curved OLED screens. -Recently, [a suggested edit][5] was declined because of maximum line length restrictions. -Every wasted character brings us closer to an unfortunate line break. - -## Implementation - -An implementation is [available][6]. It's pretty slick. - -## References - -1. [Abuse of Match?][1] -2. [Reputation requirements for creating tags and tag synonyms][2] -3. [Mulliganaceous user profile][3] -4. [huynhjl user profile][4] -5. [Sample line length limitation in a Scala project][5] -6. [Implementation][6] - -[1]: https://stackoverflow.com/questions/12556236/abuse-of-match "Abuse of Match?" -[2]: https://meta.stackoverflow.com/a/368537/1296806 "Reputation requirements for creating tags and tag synonyms" -[3]: https://meta.stackoverflow.com/users/8242447/mulliganaceous "Mulliganaceous" -[4]: https://stackoverflow.com/users/257449/huynhjl "huynhjl" -[5]: https://github.com/apache/spark/pull/21369/files#r189794046 "scala-style enforces a max of 100 chars per line" -[6]: https://github.com/scala/scala/pull/6241 "Implementation PR 6241" - diff --git a/_sips/sips/2014-06-27-42.type.md b/_sips/sips/42.type.md similarity index 78% rename from _sips/sips/2014-06-27-42.type.md rename to _sips/sips/42.type.md index 3cc6aa6db1..861505d42e 100644 --- a/_sips/sips/2014-06-27-42.type.md +++ b/_sips/sips/42.type.md @@ -1,9 +1,8 @@ --- layout: sip -discourse: true title: SIP-23 - Literal-based singleton types - -vote-status: complete +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/42.type.html --- @@ -23,6 +22,7 @@ Sabin** | Feb 9th 2017 | New author volunteered to update the SIP for review | | Nov 16th 2017 | Updated following implementation experience in Typelevel Scala | | Aug 7th 2018 | Updated to remove Symbol literals, which won't be supported in 3 | +| Jul 4th 2019 | Drop behaviour spec around asInstanceOf, which is a user assertion | ## Introduction @@ -33,23 +33,23 @@ their role is to give the meaning of paths selecting types and terms from nested paths have an intuitive meaning to programmers from a wide range of backgrounds which belies their underpinning by a somewhat "advanced" concept in type theory. -Nevertheless, by pairing a type with it's unique inhabitant, singleton types bridge the gap between -types and values, and their presence in Scala has over the years allowed Scala programmers to explore -techniques which would typically only be available in languages, such as Agda or Idris, with support +Nevertheless, by pairing a type with its unique inhabitant, singleton types bridge the gap between +types and values, and their presence in Scala has, over the years, allowed Scala programmers to explore +techniques which would typically only be available in languages such as Agda or Idris, with support for full-spectrum dependent types. Scala's semantics have up until now been richer than its syntax. The only singleton types which are currently _directly_ expressible are those of the form `p.type` where `p` is a path pointing to a value of some subtype of `AnyRef`. Internally the Scala compiler also represents singleton types for -individual values of subtypes of `AnyVal`, such as `Int` or values of type `String` which don't +individual values of subtypes of `AnyVal`, such as `Int` or values of type `String`, which don't correspond to paths. These types are inferred in some circumstances, notably as the types of `final` -vals. Their primary purpose has been to represent compile time constants (see [6.24 Constant -Expressions](http://scala-lang.org/files/archive/spec/2.12/06-expressions.html#constant-expressions) +vals. Their primary purpose has been to represent compile-time constants (see [6.24 Constant +Expressions](https://scala-lang.org/files/archive/spec/2.12/06-expressions.html#constant-expressions) and the discussion of "constant value definitions" in [4.1 Value Declarations and -Definitions](http://scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#value-declarations-and-definitions)). +Definitions](https://scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#value-declarations-and-definitions)). The types here correspond to _literal_ values (ie. values which programmers can directly write as terms, see [1.3 -Literals](http://scala-lang.org/files/archive/spec/2.12/01-lexical-syntax.html#literals)) such as +Literals](https://scala-lang.org/files/archive/spec/2.12/01-lexical-syntax.html#literals)) such as `23`, `true` or `"foo"` of the larger non-singleton types they inhabit (`Int`, `Boolean` or `String` respectively). However, there is no surface syntax to express these types. @@ -59,7 +59,7 @@ many important Scala libraries. The lack of first class syntax for literal types authors to use the experimental Scala macro system to provide a means to express them. Whilst this has proved to be extremely successful, it has poor ergonomics (although this can typically be hidden from library _users_) and is not portable -- because Scala macros in general and the mechanisms used -to expose literal types to Scala programmes in particular depend on internal implementation details +to expose literal types to Scala programs in particular depend on internal implementation details of the current Scala compiler. The poor ergonomics of macro-based exposure of literal types was the original motivation for this @@ -69,7 +69,7 @@ more urgent. ### Implementation status Literal types have been implemented in both [Typelevel Scala](https://github.com/typelevel/scala) -and [Dotty](http://dotty.epfl.ch/). +and [Dotty](https://dotty.epfl.ch/). There has been a great deal of useful experience with the Typelevel Scala implementation in [a variety of projects](https://github.com/search?p=1&q=-Yliteral-types&type=Code) which has @@ -89,38 +89,39 @@ Lightbend Scala compiler. foo(1: 1) // type ascription ``` -+ The `.type` singleton type forming operator can be applied to values of all subtypes of `Any`. ++ The `.type` singleton-type-forming operator can be applied to values of all subtypes of `Any`. + To prevent the compiler from widening our return type, we assign to a final val. ``` def foo[T](t: T): t.type = t - foo(23) // result is 23: 23 + final val bar = foo(23) // result is bar: 23 ``` + The presence of an upper bound of `Singleton` on a formal type parameter indicates that - singleton types should be inferred for type parameters at call sites. + singleton types should be inferred for type parameters at call sites. To help see this, + we introduce type constructor `Id` to prevent the compiler from widening our return type. ``` - def wide[T](t: T): T = t - wide(13) // result is 13: Int - def narrow[T <: Singleton](t: T): T = t - narrow(23) // result is 23: 23 + type Id[A] = A + def wide[T](t: T): Id[T] = t + wide(23) // result is 23: Id[Int] + def narrow[T <: Singleton](t: T): Id[T] = t + narrow(23) // result is 23: Id[23] ``` -+ Pattern matching against literal types and `isInstanceOf`/`asInstanceOf` tests/conversions are ++ Pattern matching against literal types and `isInstanceOf` tests are implemented via equality/identity tests of the corresponding values. ``` (1: Any) match { case one: 1 => true case _ => false - } // result is true - (1: Any).isInstanceOf[1] // result is true - (1: Any).asInstanceOf[1] // result is 1: 1 - (1: Any).asInstanceOf[2] // ClassCastException + } // result is true: Boolean + (1: Any).isInstanceOf[1] // result is true: Boolean ``` + A `scala.ValueOf[T]` type class and corresponding `scala.Predef.valueOf[T]` operator has been - added yielding the unique value of types with a single inhabitant. + added, yielding the unique value of types with a single inhabitant. ``` def foo[T](implicit v: ValueOf[T]): T = v.value - foo[13] // result is 13: 13 + foo[13] // result is 13: Int ``` @@ -128,13 +129,13 @@ Lightbend Scala compiler. Many of the examples below use primitives provided by the Scala generic programming library [shapeless](https://github.com/milessabin/shapeless/). It provides a `Witness` type class and a -family of Scala macro based methods and conversions for working with singleton types and shifting +family of Scala-macro-based methods and conversions for working with singleton types and shifting from the value to the type level and vice versa. One of the goals of this SIP is to enable Scala programmers to achieve similar results without having to rely on a third party library or fragile and non-portable macros. The relevant parts of shapeless are excerpted in [Appendix 1](#appendix-1--shapeless-excerpts). -Given the definitions there, some of forms summarized above can be expressed in current Scala, +Given the definitions there, some of the forms summarized above can be expressed in current Scala, ``` val wOne = Witness(1) val one: wOne.T = wOne.value // wOne.T is the type 1 @@ -146,13 +147,13 @@ foo[wOne.T] // result is 1: 1 "foo" ->> 23 // shapeless record field constructor // result type is FieldType["foo", Int] ``` -The syntax is awkward and hiding it from library users is challenging. Nevertheless they enable many +The syntax is awkward, and hiding it from library users is challenging. Nevertheless they enable many constructs which have proven valuable in practice. #### shapeless records shapeless models records as HLists (essentially nested pairs) of record values with their types -tagged with the singleton types of their keys. The library provides user friendly mechanisms for +tagged with the singleton types of their keys. The library provides user-friendly mechanisms for constructing record _values_, however it is extremely laborious to express the corresponding _types_. Consider the following record value, ``` @@ -164,7 +165,7 @@ val book = HNil ``` -Using shapeless and current Scala the following would be required to give `book` an explicit type +Using shapeless and current Scala, the following would be required to give `book` an explicit type annotation, ``` val wAuthor = Witness("author") @@ -207,7 +208,7 @@ val book: Book = shapeless enables generic programming and type class derivation by providing a mechanism for mapping a value of a standard Scala algebraic data type onto a sum of products representation type, -essentially nested labelled `Either`'s of the records discussed above. Techniques of this sort are +essentially nested labelled `Either`s of the records discussed above. Techniques of this sort are widely used, and removing the incidental complexity that comes with encoding via macros will improve the experience for many users across a wide variety of domains. @@ -217,7 +218,7 @@ the experience for many users across a wide variety of domains. [singleton-ops](https://github.com/fthomas/singleton-ops) are two libraries which build on shapeless's `Witness` to support refinement types for Scala. A refinement is a type-level predictate which constrains a set of values relative to some base type, for example, the type of integers -greater thar 5. +greater than 5. refined allows such types to be expressed in Scala using shapeless's `Witness`, ``` @@ -240,20 +241,20 @@ val c: Int Refined Greater[w6.T] = a ^ ``` -Under this proposal we can express these refinements much more succinctly, +Under this proposal, we can express these refinements much more succinctly, ``` val a: Int Refined Greater[5] = 10 val b: Int Refined Greater[4] = a ``` -Type level predicates of this kind have proved to be useful in practice and are supported by modules +Type-level predicates of this kind have proved to be useful in practice and are supported by modules of a [number of important libraries](https://github.com/fthomas/refined#external-modules). Experience with those libraries has led to a desire to compute directly over singleton types, in -effect to lift whole term-level expressions to the type-level which has resulted in the development +effect to lift whole term-level expressions to the type level, which has resulted in the development of the [singleton-ops](https://github.com/fthomas/singleton-ops) library. singleton-ops is built -with Typelevel Scala which allows it to use literal types as discussed in this SIP. +with Typelevel Scala, which allows it to use literal types, as discussed in this SIP. ``` import singleton.ops._ @@ -278,7 +279,7 @@ singleton-ops is used by a number of libraries, most notably our next motivating [Libra](https://github.com/to-ithaca/libra) is a a dimensional analysis library based on shapeless, spire and singleton-ops. It support SI units at the type level for all numeric types. Like -singleton-ops Libra is built using Typelevel Scala and so is able to use literal types as discussed +singleton-ops, Libra is built using Typelevel Scala and so is able to use literal types, as discussed in this SIP. Libra allows numeric computations to be checked for dimensional correctness as follows, @@ -323,8 +324,8 @@ case class Residue[M <: Int](n: Int) extends AnyVal { } ``` -Given this definition we can work with modular numbers without any danger of mixing numbers with -different modulii, +Given this definition, we can work with modular numbers without any danger of mixing numbers with +different moduli, ``` val fiveModTen = Residue[10](5) @@ -341,13 +342,13 @@ fiveModTen + fourModEleven ``` Also note that the use of `ValueOf` as an implicit argument of `+` means that the modulus does not -need to be stored along with the `Int` in the `Residue` value which could be beneficial in +need to be stored along with the `Int` in the `Residue` value, which could be beneficial in applications which work with large datasets. ### Proposal details + Literals can now appear in type position, designating the corresponding singleton type. The - [`SimpleType`](http://scala-lang.org/files/archive/spec/2.12/03-types.html) production is extended + [`SimpleType`](https://scala-lang.org/files/archive/spec/2.12/03-types.html) production is extended to include syntactic literals. ``` @@ -359,7 +360,7 @@ applications which work with large datasets. | ‘(’ Types ‘)’ ``` - Examples, + Examples: ``` val one: 1 = 1 // val declaration def foo(x: 1): Option[1] = Some(x) // param type, type arg @@ -367,10 +368,10 @@ applications which work with large datasets. foo(1: 1) // type ascription ``` -+ The restriction that the singleton type forming operator `.type` can only be appended to ++ The restriction that the singleton-type-forming operator `.type` can only be appended to stable paths designating a value which conforms to `AnyRef` is dropped -- the path may now conform to `Any`. Section - [3.2.1](http://scala-lang.org/files/archive/spec/2.12/03-types.html#singleton-types) of the SLS is + [3.2.1](https://scala-lang.org/files/archive/spec/2.12/03-types.html#singleton-types) of the SLS is updated as follows, > **Singleton Types** @@ -384,10 +385,10 @@ applications which work with large datasets. > denoted by `p` (i.e., the value `v` for which `v eq p`). Where the path does not conform to > `scala.AnyRef` the type denotes the set consisting of only the value denoted by `p`. - Example, + Example: ``` def foo[T](t: T): t.type = t - foo(23) // result is 23: 23 + final val bar = foo(23) // result is bar: 23 ``` + The presence of an upper bound of `Singleton` on a formal type parameter indicates that @@ -438,7 +439,7 @@ applications which work with large datasets. sites of the form in the above example would currently be rejected as invalid. Whilst type inference in Scala is not fully specified, section [6.26.4 Local Type - Inference](http://scala-lang.org/files/archive/spec/2.12/06-expressions.html#local-type-inference) + Inference](https://scala-lang.org/files/archive/spec/2.12/06-expressions.html#local-type-inference) contains language which explicitly excludes the inference of singleton types (see cases 2 and 3, "None of the inferred types Ti is a singleton type"). This does not match the current Scala or Dotty compiler implementations, where singleton types are inferred where a definition is final, @@ -448,14 +449,14 @@ applications which work with large datasets. ``` final val narrow = 23 // inferred type of narrow: 23 - class Widen + class Wide object Narrow extends Wide def id[T](t: T): T = t id(Narrow) // result is Narrow: Narrow.type ``` This SIP updates the specification to match the current implementation and then adds the further - refinement that an explict upper bound of `Singleton` indicates that a singleton type should be + refinement that an explicit upper bound of `Singleton` indicates that a singleton type should be inferred. Given, @@ -470,26 +471,29 @@ applications which work with large datasets. > corresponding to a singleton-apt definition, or (2) The upper bound Ui of Ti conforms to > `Singleton`. - Example, + Example: ``` - def wide[T](t: T): T = t - wide(13) // result is 13: Int - def narrow[T <: Singleton](t: T): T = t - narrow(23) // result is 23: 23 + type Id[A] = A + def wide[T](t: T): Id[T] = t + wide(23) // result is 23: Id[Int] + def narrow[T <: Singleton](t: T): Id[T] = t + narrow(23) // result is 23: Id[23] ``` + Note that we introduce the type constructor `Id` simply to avoid widening of the return type. + + A `scala.ValueOf[T]` type class and corresponding `scala.Predef.valueOf[T]` operator has been - added yielding the unique value of types with a single inhabitant. + added, yielding the unique value of types with a single inhabitant. Type inference allows us to infer a singleton type from a literal value. It is natural to want to be able to go in the other direction and infer a value from a singleton type. This latter capability was exploited in the motivating `Residue` example given earlier, and is widely relied - on in current Scala in uses of shapeless's records, and `LabelledGeneric` based type class + on in current Scala in uses of shapeless's records, and `LabelledGeneric`-based type class derivation. - Implicit resolution is Scala's mechanism for inferring values from types and in current Scala + Implicit resolution is Scala's mechanism for inferring values from types, and in current Scala, shapeless provides a macro-based materializer for instances of its `Witness` type class. This SIP - adds a directly compiler supported type class as a replacement, + adds a directly compiler-supported type class as a replacement: ``` final class ValueOf[T](val value: T) extends AnyVal @@ -498,75 +502,78 @@ applications which work with large datasets. Instances are automatically provided for all types with a single inhabitant, which includes literal and non-literal singleton types and `Unit`. - Example, + Example: ``` def foo[T](implicit v: ValueOf[T]): T = v.value - foo[13] // result is 13: 13 + foo[13] // result is 13: Int ``` - A method `valueOf` is also added to `scala.Predef` analogously to existing operators such as + A method `valueOf` is also added to `scala.Predef`, analogously to existing operators such as `classOf`, `typeOf` etc. ``` def valueOf[T](implicit vt: ValueOf[T]): T = vt.value ``` - Example, + Example: ``` object Foo valueOf[Foo.type] // result is Foo: Foo.type - valueOf[23] // result is 23: 23 + valueOf[23] // result is 23: Int ``` -+ Pattern matching against literal types and `isInstanceOf`/`asInstanceOf` tests/conversions are ++ Pattern matching against literal types and `isInstanceOf` tests are implemented via equality/identity tests of the corresponding values. Pattern matching against typed patterns (see [8.1.2 Typed - Patterns](http://scala-lang.org/files/archive/spec/2.12/08-pattern-matching.html#typed-patterns)) + Patterns](https://scala-lang.org/files/archive/spec/2.12/08-pattern-matching.html#typed-patterns)) where the `TypePat` is a literal type is translated as a match against the subsuming non-singleton type followed by an equality test with the value corresponding to the literal type. - Where applied to literal types `isInstanceOf` and `asInstanceOf` are translated to a test against + Where applied to literal types, `isInstanceOf` is translated to a test against the subsuming non-singleton type and an equality test with the value corresponding to the literal - type. In the case of `asInstanceOf` a `ClassCastException` is thrown if the test fails. + type. - Examples, + Examples: ``` (1: Any) match { case one: 1 => true case _ => false - } // result is true - (1: Any).isInstanceOf[1] // result is true - (1: Any).asInstanceOf[1] // result is 1: 1 - (1: Any).asInstanceOf[2] // ClassCastException + } // result is true: Boolean + (1: Any).isInstanceOf[1] // result is true: Boolean ``` + Importantly, that doesn't include `asInstanceOf`, as that is a user assertion to the compiler, with + the compiler inserting in the generated code just enough code for the underlying runtime to not + give a `ValidationError`. The compiler should not, for instance, generate code such that an + expression like `(1: Any).asInstanceOf[2]` would throw a `ClassCastException`. + + Default initialization for vars with literal types is forbidden. - The default initializer for a var is already mandated to be it's natural zero element (`0`, - `false`, `null` etc.). This is inconsistent with the var being given a non-zero literal type, + The default initializer for a var is already mandated to be its natural zero element (`0`, + `false`, `null` etc.). This is inconsistent with the var being given a non-zero literal type: ``` var bad: 1 = _ ``` - Whilst we could, in principle, provide an implicit non-default initializer for cases such as these + Whilst we could, in principle, provide an implicit non-default initializer for cases such as these, it is the view of the authors of this SIP that there is nothing to be gained from enabling this - construction and that default initializer should be forbidden. + construction, and that default initializer should be forbidden. -## Follow on work from this SIP +## Follow-on work from this SIP Whilst the authors of this SIP believe that it stands on its own merits, we think that there are two -areas where follow on work is desirable, and one area where another SIP might improve the implementation of SIP-23. +areas where follow-on work is desirable, and one area where another SIP might improve the implementation of SIP-23. ### Infix and prefix types -[SIP-33 Match Infix and Prefix Types to Meet Expression Rules](http://docs.scala-lang.org/sips/make-types-behave-like-expressions.html) +[SIP-33 Match Infix and Prefix Types to Meet Expression Rules](https://docs.scala-lang.org/sips/priority-based-infix-type-precedence.html) has emerged from the work on refined types and computation over singleton types mentioned in the motivation section above. -Once literal types are available it is natural to want to lift entire expressions to the type level +Once literal types are available, it is natural to want to lift entire expressions to the type level as is done already in libraries such as [singleton-ops](https://github.com/fthomas/singleton-ops). However, the precedence and associativity of symbolic infix _type constructors_ don't match the precedence and associativity of symbolic infix _value operators_, and prefix type constructors don't @@ -575,13 +582,13 @@ terms. ### Byte and short literals -`Byte` and `Short` have singleton types, but lack any corresponding syntax either at the type or at the term level. -These types are important in libraries which deal with low level numerics and protocol implementation +`Byte` and `Short` have singleton types, but lack any corresponding syntax either at the type or at the term level. +These types are important in libraries which deal with low-level numerics and protocol implementation (see eg. [Spire](https://github.com/non/spire) and [Scodec](https://github.com/scodec/scodec)) and elsewhere, and the ability to, for instance, index a type class by a byte or short literal would be valuable. -A prototype of this syntax extension existed at an early stage in the development of Typelevel Scala +A prototype of this syntax extension existed at an early stage in the development of Typelevel Scala, but never matured. The possibility of useful literal types adds impetus. ### Opaque types @@ -592,7 +599,7 @@ the singleton types). This is desirable, but due to value class restrictions, en primitive types (such as `Int`). If we implemented `ValueOf[A]` as an opaque type instead of a value class, then this boxing -would be ellided, and the `valueOf[A]` method would be compiled to an identity function. +would be elided, and the `valueOf[A]` method would be compiled to an identity function. ## Related Scala issues resolved by the literal types implementation @@ -603,7 +610,7 @@ would be ellided, and the `valueOf[A]` method would be compiled to an identity f ## Appendix 1 -- shapeless excerpts -Extracts from shapeless relevant to the motivating examples for this SIP, +Extracts from shapeless relevant to the motivating examples for this SIP: ``` trait Witness { diff --git a/_sips/sips/adding-prefix-types.md b/_sips/sips/adding-prefix-types.md new file mode 100644 index 0000000000..611baff9c0 --- /dev/null +++ b/_sips/sips/adding-prefix-types.md @@ -0,0 +1,6 @@ +--- +title: SIP-36 - Adding prefix types +status: withdrawn +pull-request-number: 35 + +--- diff --git a/_sips/sips/allow-referring-to-other-arguments-in-default-parameters.md b/_sips/sips/allow-referring-to-other-arguments-in-default-parameters.md new file mode 100644 index 0000000000..9eaec18d7b --- /dev/null +++ b/_sips/sips/allow-referring-to-other-arguments-in-default-parameters.md @@ -0,0 +1,6 @@ +--- +title: SIP-32 - Allow referring to other arguments in default parameters +status: rejected +pull-request-number: 29 + +--- diff --git a/_sips/sips/alternative-bind-variables.md b/_sips/sips/alternative-bind-variables.md new file mode 100644 index 0000000000..ab6899a026 --- /dev/null +++ b/_sips/sips/alternative-bind-variables.md @@ -0,0 +1,331 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: implementation +status: waiting-for-implementation +presip-thread: https://contributors.scala-lang.org/t/pre-sip-bind-variables-for-alternative-patterns/6321/13 +title: SIP-60 - Bind variables within alternative patterns +--- + +**By: Yilin Wei** + +## History + +| Date | Version | +|---------------|--------------------| +| Sep 17th 2023 | Initial Draft | +| Jan 16th 2024 | Amendments | + +## Summary + +Pattern matching is one of the most commonly used features in Scala by beginners and experts alike. Most of +the features of pattern matching compose beautifully — for example, a user who learns about bind variables +and guard patterns can mix the two features intuitively. + +One of the few outstanding cases where this is untrue, is when mixing bind variables and alternative patterns. The part of +current [specification](https://scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html) which we are concerned with is under section **8.1.12** and is copied below, with the relevant clause +highlighted. + +> … All alternative patterns are type checked with the expected type of the pattern. **They may not bind variables other than wildcards**. The alternative … + +We propose that this restriction be lifted and this corner case be eliminated. + +Removing the corner case would make the language easier to teach, reduce friction and allow users to express intent in a more natural manner. + +## Motivation + +## Scenario + +The following scenario is shamelessly stolen from [PEP 636](https://peps.python.org/pep-0636), which introduces pattern matching to the +Python language. + +Suppose a user is writing classic text adventure game such as [Zork](https://en.wikipedia.org/wiki/Zork). For readers unfamiliar with +text adventure games, the player typically enters freeform text into the terminal in the form of commands to interact with the game +world. Examples of commands might be `"pick up rabbit"` or `"open door"`. + +Typically, the commands are tokenized and parsed. After a parsing stage we may end up with a encoding which is similar to the following: + +```scala +enum Word + case Get, North, Go, Pick, Up + case Item(name: String) + + case class Command(words: List[Word]) +``` + +In this encoding, the string `pick up jar`, would be parsed as `Command(List(Pick, Up, Item("jar")))`. + +Once the command is parsed, we want to actually *do* something with the command. With this particular encoding, +we would naturally reach for a pattern match — in the simplest case, we could get away with a single recursive function for +our whole program. + +Suppose we take the simplest example where we want to match on a command like `"north"`. The pattern match consists of +matching on a single stable identifier, `North` and the code would look like this: + +~~~ scala +import Command.* + +def loop(cmd: Command): Unit = + cmd match + case Command(North :: Nil) => // Code for going north +~~~ + +However as we begin play-testing the actual text adventure, we observe that users type `"go north"`. We decide +our program should treat the two distinct commands as synonyms. At this point we would reach for an alternative pattern `|` and +refactor the code like so: + +~~~ scala + case Command(North :: Nil | Go :: North :: Nil) => // Code for going north +~~~ + +This clearly expresses our intent that the two commands map to the same underlying logic. + +Later we decide that we want more complex logic in our game; perhaps allowing the user to pick up +items with a command like `pick up jar`. We would then extend our function with another case, binding the variable `name`: + +~~~ scala + case Command(Pick :: Up :: Item(name) :: Nil) => // Code for picking up items +~~~ + +Again, we might realise through our play-testing that users type `get` as a synonym for `pick up`. After playing around +with alternative patterns, we may reasonably write something like: + +~~~ scala + case Command(Pick :: Up :: Item(name) :: Nil | Get :: Item(name) :: Nil) => // Code for picking up items +~~~ + +Unfortunately at this point, we are stopped in our tracks by the compiler. The bind variable for `name` cannot be used in conjunction with alternative patterns. +We must either choose a different encoding. We carefully consult the specification and that this is not possible. + +We can, of course, work around it by hoisting the logic to a helper function to the nearest scope which function definitions: + +~~~ scala +def loop(cmd: Cmd): Unit = + def pickUp(item: String): Unit = // Code for picking up item + cmd match + case Command(Pick :: Up :: Item(name)) => pickUp(name) + case Command(Get :: Item(name)) => pickUp(name) +~~~ + +Or any number of different encodings. However, all of them are less intuitive and less obvious than the code we tried to write. + +## Commentary + +Removing the restriction leads to more obvious encodings in the case of alternative patterns. Arguably, the language +would be simpler and easier to teach — we do not have to remember that bind patterns and alternatives +do not mix and need to teach newcomers the workarounds. + +For languages which have pattern matching, a significant number also support the same feature. Languages such as [Rust](https://github.com/rust-lang/reference/pull/957) and [Python](https://peps.python.org/pep-0636/#or-patterns) have +supported it for some time. While +this is not a great reason for Scala to do the same, having the feature exist in other languages means that users +that are more likely to expect the feature. + +A smaller benefit for existing users, is that removing the corner case leads to code which is +easier to review; the absolute code difference between adding a bind variable within an alternative versus switching to a different +encoding entirely is smaller and conveys the intent of such changesets better. + +It is acknowledged, however, that such cases where we share the same logic with an alternative branches are relatively rare compared to +the usage of pattern matching in general. The current restrictions are not too arduous to workaround for experienced practitioners, which +can be inferred from the relatively low number of comments from the original [issue](https://github.com/scala/bug/issues/182) first raised in 2007. + +To summarize, the main arguments for the proposal are to make the language more consistent, simpler and easier to teach. The arguments +against a change are that it will be low impact for the majority of existing users. + +## Proposed solution + +Removing the alternative restriction means that we need to specify some additional constraints. Intuitively, we +need to consider the restrictions on variable bindings within each alternative branch, as well as the types inferred +for each binding within the scope of the pattern. + +## Bindings + +The simplest case of mixing an alternative pattern and bind variables, is where we have two `UnApply` methods, with +a single alternative pattern. For now, we specifically only consider the case where each bind variable is of the same +type, like so: + +~~~ scala +enum Foo: + case Bar(x: Int) + case Baz(y: Int) + + def fun = this match + case Bar(z) | Baz(z) => ... // z: Int +~~~ + +For the expression to make sense with the current semantics around pattern matches, `z` must be defined in both branches; otherwise the +case body would be nonsensical if `z` was referenced within it (see [missing variables](#missing-variables) for a proposed alternative). + +Removing the restriction would also allow recursive alternative patterns: + +~~~ scala +enum Foo: + case Bar(x: Int) + case Baz(x: Int) + +enum Qux: + case Quux(y: Int) + case Corge(x: Foo) + + def fun = this match + case Quux(z) | Corge(Bar(z) | Baz(z)) => ... // z: Int +~~~ + +Using an `Ident` within an `UnApply` is not the only way to introduce a binding within the pattern scope. +We also expect to be able to use an explicit binding using an `@` like this: + +~~~ scala +enum Foo: + case Bar() + case Baz(bar: Bar) + + def fun = this match + case Baz(x) | x @ Bar() => ... // x: Foo.Bar +~~~ + +## Types + +We propose that the type of each variable introduced in the scope of the pattern be the least upper-bound of the type +inferred within within each branch. + +~~~ scala +enum Foo: + case Bar(x: Int) + case Baz(y: String) + + def fun = this match + case Bar(x) | Baz(x) => // x: Int | String +~~~ + +We do not expect any inference to happen between branches. For example, in the case of a GADT we would expect the second branch of +the following case to match all instances of `Bar`, regardless of the type of `A`. + +~~~ scala +enum Foo[A]: + case Bar(a: A) + case Baz(i: Int) extends Foo[Int] + + def fun = this match + case Baz(x) | Bar(x) => // x: Int | A +~~~ + +### Given bind variables + +It is possible to introduce bindings to the contextual scope within a pattern match branch. + +Since most bindings will be anonymous but be referred to within the branches, we expect the _types_ present in the contextual scope for each branch to be the same rather than the _names_. + +~~~ scala + case class Context() + + def run(using ctx: Context): Unit = ??? + + enum Foo: + case Bar(ctx: Context) + case Baz(i: Int, ctx: Context) + + def fun = this match + case Bar(given Context) | Baz(_, given Context) => run // `Context` appears in both branches +~~~ + +This begs the question of what to do in the case of an explicit `@` binding where the user binds a variable to the same _name_ but to different types. We can either expose a `String | Int` within the contextual scope, or simply reject the code as invalid. + +~~~ scala + enum Foo: + case Bar(s: String) + case Baz(i: Int) + + def fun = this match + case Bar(x @ given String) | Baz(x @ given Int) => ??? +~~~ + +To be consistent with the named bindings, we argue that the code should compile and a contextual variable added to the scope with the type of `String | Int`. + +### Quoted patterns + +[Quoted patterns](https://docs.scala-lang.org/scala3/guides/macros/quotes.html#quoted-patterns) will not be supported in this SIP and the behaviour of quoted patterns will remain the same as currently i.e. any quoted pattern appearing in an alternative pattern binding a variable or type variable will be rejected as illegal. + +### Alternatives + +#### Enforcing a single type for a bound variable + +We could constrain the type for each bound variable within each alternative branch to be the same type. Notably, this is what languages such as Rust, which do not have sub-typing do. + +However, since untagged unions are part of Scala 3 and the fact that both are represented by the `|`, it felt more natural to discard this restriction. + +#### Type ascriptions in alternative branches + +Another suggestion is that an _explicit_ type ascription by a user ought to be defined for all branches. For example, in the currently proposed rules, the following code would infer the return type to be `Int | A` even though the user has written the statement `id: Int`. + +~~~scala +enum Foo[A]: + case Bar[A](a: A) + case Baz[A](a: A) + + def test = this match + case Bar(id: Int) | Baz(id) => id +~~~ + +In the author's subjective opinion, it is more natural to view the alternative arms as separate branches — which would be equivalent to the function below. + +~~~scala +def test = this match + case Bar(id: Int) => id + case Baz(id) => id +~~~ + +On the other hand, if it is decided that each bound variable ought to be the same type, then arguably "sharing" explicit type ascriptions across branches would reduce boilerplate. + +#### Missing variables + +Unlike in other languages, we could assign a type, `A | Null`, to a bind variable which is not present in all of the alternative branches. Rust, for example, is constrained by the fact that the size of a variable must be known and untagged unions do not exist. + +Arguably, missing a variable entirely is more likely to be an error — the absence of a requirement for `var` declarations before assigning variables in Python means that beginners can easily assign variables to the wrong variable. + +It may be, that the enforcement of having to have the same bind variables within each branch ought to be left to a linter rather thana a hard restriction within the language itself. + +## Specification + +We do not believe there are any syntax changes since the current specification already allows the proposed syntax. + +We propose that the following clauses be added to the specification: + +Let $`p_1 | \ldots | p_n`$ be an alternative pattern at an arbitrary depth within a case pattern and $`\Gamma_n`$ is the named scope associated with each alternative. + +If `p_i` is a quoted pattern binding a variable or type variable, the alternative pattern is considered invalid. Otherwise, let the named variables introduced within each alternative $`p_n`$, be $`x_i \in \Gamma_n`$ and the unnamed contextual variables within each alternative have the type $`T_i \in \Gamma_n`$. + +Each $`p_n`$ must introduce the same set of bindings, i.e. for each $`n`$, $`\Gamma_n`$ must have the same **named** members $`\Gamma_{n+1}`$ and the set of $`{T_0, ... T_n}`$ must be the same. + +If $`X_{n,i}`$, is the type of the binding $`x_i`$ within an alternative $`p_n`$, then the consequent type, $`X_i`$, of the +variable $`x_i`$ within the pattern scope, $`\Gamma`$ is the least upper-bound of all the types $`X_{n, i}`$ associated with +the variable, $`x_i`$ within each branch. + +## Compatibility + +We believe the changes would be backwards compatible. + +# Related Work + +The language feature exists in multiple languages. Of the more popular languages, Rust added the feature in [2021](https://github.com/rust-lang/reference/pull/957) and +Python within [PEP 636](https://peps.python.org/pep-0636/#or-patterns), the pattern matching PEP in 2020. Of course, Python is untyped and Rust does not have sub-typing +but the semantics proposed are similar to this proposal. + +Within Scala, the [issue](https://github.com/scala/bug/issues/182) first raised in 2007. The author is also aware of attempts to fix this issue by [Lionel Parreaux](https://github.com/dotty-staging/dotty/compare/main...LPTK:dotty:vars-in-pat-alts) and the associated [feature request](https://github.com/lampepfl/dotty-feature-requests/issues/12) which +was not submitted to the main dotty repository. + +The associated [thread](https://contributors.scala-lang.org/t/pre-sip-bind-variables-for-alternative-patterns/6321) has some extra discussion around semantics. Historically, there have been multiple similar suggestions — in [2023](https://contributors.scala-lang.org/t/qol-sound-binding-in-pattern-alternatives/6226) by Quentin Bernet and in [2021](https://contributors.scala-lang.org/t/could-it-be-possible-to-allow-variable-binging-in-patmat-alternatives-for-scala-3-x/5235) by Alexey Shuksto. + +## Implementation + +The author has a current in-progress implementation focused on the typer which compiles the examples with the expected types. Interested + parties are welcome to see the WIP [here](https://github.com/scala/scala3/compare/main...yilinwei:dotty:main). + +### Further work + +#### Quoted patterns + +More investigation is needed to see how quoted patterns with bind variables in alternative patterns could be supported. + +## Acknowledgements + +Many thanks to **Zainab Ali** for proof-reading the draft, **Nicolas Stucki** and **Guillaume Martres** for their pointers on the dotty +compiler codebase. diff --git a/_sips/sips/async.md b/_sips/sips/async.md new file mode 100644 index 0000000000..49448af0cb --- /dev/null +++ b/_sips/sips/async.md @@ -0,0 +1,6 @@ +--- +title: SIP-22 - Async +status: withdrawn +pull-request-number: 21 + +--- diff --git a/_sips/sips/better-fors.md b/_sips/sips/better-fors.md new file mode 100644 index 0000000000..10cfa733ea --- /dev/null +++ b/_sips/sips/better-fors.md @@ -0,0 +1,481 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: implementation +status: under-review +title: SIP-62 - For comprehension improvements +--- + +**By: Kacper Korban (VirtusLab)** + +## History + +| Date | Version | +|---------------|------------------------| +| June 6th 2023 | Initial Draft | +| Feb 15th 2024 | Reviewed Version | +| Nov 21th 2024 | Addendum for change 3. | + +## Summary + +`for`-comprehensions in Scala 3 improved their usability in comparison to Scala 2, but there are still some pain points relating both usability of `for`-comprehensions and simplicity of their desugaring. + +This SIP tries to address some of those problems, by changing the specification of `for`-comprehensions. From user perspective, the biggest change is allowing aliases at the start of the `for`-comprehensions. e.g. + +``` +for { + x = 1 + y <- Some(2) +} yield x + y +``` + +## Motivation + +There are some clear pain points related to Scala'3 `for`-comprehensions and those can be divided into two categories: + +1. User-facing and code simplicity problems + + Specifically, for the following example written in a Haskell-style do-comprehension + + ```haskell + do + a = largeExpr(arg) + b <- doSth(a) + combineM(a, b) + ``` + in Scala we would have to write + + ```scala + val a = largeExpr(b) + for + b <- doSth(a) + x <- combineM(a, b) + yield x + ``` + + This complicates the code, even in this simple example. +2. The simplicity of desugared code + + The second pain point is that the desugared code of `for`-comprehensions can often be surprisingly complicated. + + e.g. + ```scala + for + a <- doSth(arg) + b = a + yield a + b + ``` + + Intuition would suggest for the desugared code will be of the form + + ```scala + doSth(arg).map { a => + val b = a + a + b + } + ``` + + But because of the possibility of an `if` guard being immediately after the pure alias, the desugared code is of the form + + ```scala + doSth(arg).map { a => + val b = a + (a, b) + }.map { case (a, b) => + a + b + } + ``` + + These unnecessary assignments and additional function calls not only add unnecessary runtime overhead but can also block other optimizations from being performed. + +## Proposed solution + +This SIP suggests the following changes to `for` comprehensions: + +1. Allow `for` comprehensions to start with pure aliases + + e.g. + ```scala + for + a = 1 + b <- Some(2) + c <- doSth(a) + yield b + c + ``` +2. Simpler conditional desugaring of pure aliases. i.e. whenever a series of pure aliases is not immediately followed by an `if`, use a simpler way of desugaring. + + e.g. + ```scala + for + a <- doSth(arg) + b = a + yield a + b + ``` + + will be desugared to + + ```scala + doSth(arg).map { a => + val b = a + a + b + } + ``` + + but + + ```scala + for + a <- doSth(arg) + b = a + if b > 1 + yield a + b + ``` + + will be desugared to + + ```scala + doSth(arg).map { a => + val b = a + (a, b) + }.withFilter { case (a, b) => + b > 1 + }.map { case (a, b) => + a + b + } + ``` + +3. Avoiding redundant `map` calls if the yielded value is the same as the last bound value. + + e.g. + ```scala + for + a <- List(1, 2, 3) + yield a + ``` + + will just be desugared to + + ```scala + List(1, 2, 3) + ``` + +### Detailed description + +#### Ad 1. Allow `for` comprehensions to start with pure aliases + +Allowing `for` comprehensions to start with pure aliases is a straightforward change. + +The Enumerators syntax will be changed from: + +``` +Enumerators ::= Generator {semi Enumerator | Guard} +``` + +to + +``` +Enumerators ::= {Pattern1 `=' Expr semi} Generator {semi Enumerator | Guard} +``` + +Which will allow adding 0 or more aliases before the first generator. + +When desugaring is concerned, a for comprehension starting with pure aliases will generate a block with those aliases as `val` declarations and the rest of the desugared `for` as an expression. Unless the aliases are followed by a guard, then the desugaring should result in an error. + +New desugaring rule will be added: + +```scala +For any N: + for (P_1 = E_1; ... P_N = E_N; ...) + ==> + { + val x_2 @ P_2 = E_2 + ... + val x_N @ P_N = E_N + for (...) + } +``` + +e.g. + +```scala +for + a = 1 + b <- Some(2) + c <- doSth(a) +yield b + c +``` + +will desugar to + +```scala +{ + val a = 1 + for + b <- Some(2) + c <- doSth(a) + yield b + c +} +``` + +#### Ad 2. Simpler conditional desugaring of pure aliases. i.e. whenever a series of pure aliases is not immediately followed by an `if`, use a simpler way of desugaring. + +Currently, for consistency, all pure aliases are desugared as if they are followed by an `if` condition. Which makes the desugaring more complicated than expected. + +e.g. + +The following code: + +```scala +for + a <- doSth(arg) + b = a +yield a + b +``` + +will be desugared to: + +```scala +doSth(arg).map { a => + val b = a + (a, b) +}.map { case (a, b) => + a + b +} +``` + +The proposed change is to introduce a simpler desugaring for common cases, when aliases aren't followed by a guard, and keep the old desugaring method for the other cases. + +A new desugaring rules will be introduced for simple desugaring. + +```scala +For any N: + for (P <- G; P_1 = E_1; ... P_N = E_N; ...) + ==> + G.flatMap (P => for (P_1 = E_1; ... P_N = E_N; ...)) + +And: + + for () yield E ==> E + +(Where empty for-comprehensions are excluded by the parser) +``` + +It delegares desugaring aliases to the newly introduced rule from the previous impreovement. i.e. + +```scala +For any N: + for (P_1 = E_1; ... P_N = E_N; ...) + ==> + { + val x_2 @ P_2 = E_2 + ... + val x_N @ P_N = E_N + for (...) + } +``` + +One other rule also has to be changed, so that the current desugaring method, of passing all the aliases in a tuple with the result, will only be used when desugaring a generator, followed by some aliases, followed by a guard. + +```scala +For any N: + for (P <- G; P_1 = E_1; ... P_N = E_N; if E; ...) + ==> + for (TupleN(P, P_1, ... P_N) <- + for (x @ P <- G) yield { + val x_1 @ P_1 = E_2 + ... + val x_N @ P_N = E_N + TupleN(x, x_1, ..., x_N) + }; if E; ...) +``` + +This changes will make the desugaring work in the following way: + +```scala +for + a <- doSth(arg) + b = a +yield a + b +``` + +will be desugared to + +```scala +doSth(arg).map { a => + val b = a + a + b +} +``` + +but + +```scala +for + a <- doSth(arg) + b = a + if b > 1 +yield a + b +``` + +will be desugared to + +```scala +doSth(arg).map { a => + val b = a + (a, b) +}.withFilter { case (a, b) => + b > 1 +}.map { case (a, b) => + a + b +} +``` + +#### Ad 3. Avoiding redundant `map` calls if the yielded value is the same as the last bound value. + +This change is strictly an optimization. This allows for the compiler to get rid of the final `map` call, if the yielded value is the same as the last bound pattern. The pattern can be either a single variable binding or a tuple. + +This optimization should be done after type checking (e.g. around first transform). See the reasons to why it cannot be done in desugaring in [here](#previous-design-in-desugaring). + +We propose an approach where an attachment (`TrailingForMap`) is attached to the last `map` `Apply` node. After that, a later phase will look for `Apply` nodes with this attachment and possibly remove the `map` call. + +The condition for allowing to remove the last map call (for a binding `pat <- gen yield pat1`) are as follows: +- `pat` is (syntactically) equivalent to `pat1` ($pat =_{s} pat1$) + + where + + $x =_{s} x, \text{if x is a variable reference}$ + + $x =_{s} (), \text{if x is a variable reference of type Unit}$ + + $(x_1, ..., x_n) =_{s} (y_1, ..., y_n) \iff \forall i \in n.\; x_i =_{s} y_i$ + + This means that the two patterns are equivalent if they are the same variable, if they are tuples of the same variables, or if one is a variable reference of type `Unit` and the other is a `Unit` literal. +- `pat` and `pat1` have the same types (`pat.tpe` =:= `pat1.tpe`) + +##### Changes discussion + +This adresses the problem of changing the resulting type after removing trailing `map` calls. + +There are two main changes compared to the previous design: +1. Moving the implementation to the later phase, to be able to use the type information and explicitly checking that the types are the same. +2. Allowing to remove the last `map` call if the yielded value is a `Unit` literal (and obviously the type doesn't change). + +The motivation for the second change is to avoid potential memory leaks in effecting loops. e.g. + +```scala +//> using scala 3.3.3 +//> using lib "dev.zio::zio:2.1.5" + +import zio.* + +def loop: Task[Unit] = + for + _ <- Console.print("loop") + _ <- loop + yield () + +@main +def run = + val runtime = Runtime.default + Unsafe.unsafe { implicit unsafe => + runtime.unsafe.run(loop).getOrThrowFiberFailure() + } +``` + +This kind of effect loop is pretty commonly used in Scala FP programs and often ends in `yield ()`. + +The problem with the desugaring of this for-comprehensions is that it leaks memory because the result of `loop` has to be mapped over with `_ => ()`, which often does nothing. + +##### Previous design (in desugaring) + +One desugaring rule has to be modified for this purpose. + +```scala + for (P <- G) yield P ==> G +If P is a variable or a tuple of variables and G is not a withFilter. + + for (P <- G) yield E ==> G.map (P => E) +Otherwise +``` + +e.g. +```scala +for + a <- List(1, 2, 3) +yield a +``` + +will just be desugared to + +```scala +List(1, 2, 3) +``` + +**Cause of change** + +This design ended up breaking quite a few existing projects in the open community build run. + +For example, consider the following code: + +```scala +//> using scala 3.nightly + +import scala.language.experimental.betterFors + +case class Container[A](val value: A) { + def map[B](f: A => B): Container[B] = Container(f(value)) +} + +sealed trait Animal +case class Dog() extends Animal + +def opOnDog(dog: Container[Dog]): Container[Animal] = + for + v <- dog + yield v +``` + +With the new desugaring, the code gave an error about type mismatch. + +```scala +-- [E007] Type Mismatch Error: /home/kpi/bugs/better-fors-bug.scala:13:2 ------- +13 | for + | ^ + | Found: (dog : Container[Dog]) + | Required: Container[Animal] +14 | v <- dog +15 | yield v + | + | longer explanation available when compiling with `-explain` +``` + +This is because the container is invariant. And even though the last `map` was an identity function, it was used to upcast `Dog` to `Animal`. + +### Compatibility + +This change may change the semantics of some programs. It may remove some `map` calls in the desugared code, which may change the program semantics (if the `map` implementation was side-effecting). + +For example the following code will now have only one `map` call, instead of two: +```scala +for + a <- doSth(arg) + b = a +yield a + b +``` + +### Other concerns + +As far as I know, there are no widely used Scala 3 libraries that depend on the desugaring specification of `for`-comprehensions. + +The only Open community build library that failed because of the change to the desugaring specification is [`avocADO`](https://github.com/VirtusLab/avocado). + +## Links + +1. Scala contributors discussion thread (pre-SIP): https://contributors.scala-lang.org/t/pre-sip-improve-for-comprehensions-functionality/3509/51 +2. Github issue discussion about for desugaring: https://github.com/scala/scala3/issues/2573 +3. Scala 2 implementation of some of the improvements: https://github.com/oleg-py/better-monadic-for +4. Implementation of one of the simplifications: https://github.com/scala/scala3/pull/16703 +5. Draft implementation branch: https://github.com/dotty-staging/dotty/tree/improved-fors +6. Minimized issue reproducing the problem with the current desugaring: https://github.com/scala/scala3/issues/21804 +7. (empty :sad:) Contributors thread about better effect loops with for-comprehensions: https://contributors.scala-lang.org/t/pre-sip-sip-62-addition-proposal-better-effect-loops-with-for-comprehensions/6759 +8. Draft implementation of dropping the last map call after type checking (only for `Unit` literals): https://github.com/KacperFKorban/dotty/commit/31cbd4744b9375443a0770a8b8a9d16de694c6bb#diff-ed248bb93940ea4f38e6da698051f882e81df6f33fea91a046d1d4f6af506296R2066 diff --git a/_sips/sips/binary-api.md b/_sips/sips/binary-api.md new file mode 100644 index 0000000000..e94bf85a54 --- /dev/null +++ b/_sips/sips/binary-api.md @@ -0,0 +1,279 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: implementation +status: under-review +title: SIP-52 - Binary APIs +--- + +**By: Author Nicolas Stucki** + +## History + +| Date | Version | +|---------------|------------------------| +| Feb 27 2023 | Initial Draft | +| Aug 16 2023 | Single Annotation | +| Aug 24 2023 | Change Annotation Name | +| Jan 09 2024 | Change Overload Rules | +| Feb 29 2024 | Experimental in [Scala 3.4.0](https://www.scala-lang.org/blog/2024/02/29/scala-3.4.0-and-3.3.3-released.html) | + +## Summary + +The purpose of binary APIs is to have publicly accessible definitions in generated bytecode for definitions that are package private or protected. +This proposal introduces the `@publicInBinary` annotation on term definitions and the `-WunstableInlineAccessors` linting flag. + + +## Motivation + +### Provide a sound way to refer to private members in inline definitions + +Currently, the compiler automatically generates accessors for references to private members in inline definitions. This scheme interacts poorly with binary compatibility. It causes the following three unsoundness in the system: +* Changing any definition from private to public is a binary incompatible change +* Changing the implementation of an inline definition can be a binary incompatible change +* Removing final from a class is a binary incompatible change + +You can find more details in [https://github.com/scala/scala3/issues/16983](https://github.com/scala/scala3/issues/16983) + +### Avoid duplication of inline accessors + +Ideally, private definitions should have a maximum of one inline accessor, which is not the case now. +When an inline method accesses a private/protected definition that is defined outside of its class, we generate an inline in the class of the inline method. This implies that accessors might be duplicated if a private/protected definition is accessed from different classes. + +### Removing deprecated APIs + +There is no precise mechanism to remove a deprecated method from a library without causing binary incompatibilities. We should have a straightforward way to indicate that a method is no longer publicly available but still available in the generated code for binary compatibility. + +```diff +- @deprecated(...) def myOldAPI: T = ... ++ private[C] def myOldAPI: T = ... +``` + +Related to discussion in [https://github.com/lightbend/mima/discussions/724](https://github.com/lightbend/mima/discussions/724). + +### No way to inline reference to private constructors + +It is currently impossible to refer to private constructors in inline methods. +```scala +class C private() +object C: + inline def newC: C = new C() // Implementation restriction: cannot use private constructors in inline methods +``` +If users want to access one of those, they must write an accessor explicitly. This extra indirection is undesirable. +```scala +class C private() +object C: + private def newCInternal: C = new C() + inline def newC: C = newCInternal +``` + +## Proposed solution + +### High-level overview + +This proposal introduces the `@publicInBinary` annotation, and adds a migration path to inline methods in libraries (requiring binary compatibility). + +#### `@publicInBinary` annotation + +A binary API is a definition that is annotated with `@publicInBinary`. +This annotation can be placed on `def`, `val`, `lazy val`, `var`, `object`, and `given` definitions. +A binary API will be publicly available in the bytecode. + +This annotation cannot be used on `private`/`private[this]` definitions. With the exception of class constructors. + +Removing this annotation from a non-public definition is a binary incompatible change. + +Example: + +~~~ scala +class C { + @publicInBinary private[C] def packagePrivateAPI: Int = ... + @publicInBinary protected def protectedAPI: Int = ... + @publicInBinary def publicAPI: Int = ... // warn: `@publicInBinary` has no effect on public definitions +} +~~~ +will generate the following bytecode signatures +~~~ java +public class C { + public C(); + public int packagePrivateAPI(); + public int protectedAPI(); + public int publicAPI(); +} +~~~ + +In the bytecode, `@publicInBinary` definitions will have the [ACC_PUBLIC](https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.1-200-E.1) flag. + + +#### Binary API and inlining + +A non-public reference in an inline method is handled as follows: + - if the reference is a `@publicInBinary` the reference is used; + - otherwise, an accessor is automatically generated and used. + +Example: +~~~ scala +import scala.annotation.publicInBinary +class C { + @publicInBinary private[C] def a: Int = ... + private[C] def b: Int = ... + @publicInBinary protected def c: Int = ... + protected def d: Int = ... + inline def foo: Int = a + b + c + d +} +~~~ +before inlining the compiler will generate the accessors for inlined definitions +~~~ scala +class C { + @publicInBinary private[C] def a: Int = ... + private[C] def b: Int = ... + @publicInBinary protected def c: Int = ... + protected def d: Int = ... + final def C$$inline$b: Int = ... + final def C$$inline$d: Int = ... + inline def foo: Int = a + C$$inline$b + c + C$$inline$d +} +~~~ + +##### `-WunstableInlineAccessors` + +In addition we introduce the `-WunstableInlineAccessors` flag to allow libraries to detect when the compiler generates unstable accessors. +The previous code would show a linter warning that looks like this: + +~~~ +-- [E...] Compatibility Warning: C.scala ----------------------------- + | inline def foo: Int = a + b + c + d + | ^ + | Unstable inline accessor C$$inline$b was generated in class C. + | + | longer explanation available when compiling with `-explain` +-- [E...] Compatibility Warning: C.scala ----------------------------- + | inline def foo: Int = a + b + c + d + | ^ + | Unstable inline accessor C$$inline$d was generated in class C. + | + | longer explanation available when compiling with `-explain` +~~~ + +When an accessor is detected we can tell the user how to fix the issue. For example we could use the `-explain` flag to add the following details to the message. + +
            +With `-WunstableInlineAccessors -explain` + +~~~ +-- [E...] Compatibility Warning: C.scala ----------------------------- + | inline def foo: Int = a + b + c + d + | ^ + | Unstable inline accessor C$$inline$b was generated in class C. + |----------------------------------------------------------------------------- + | Explanation (enabled by `-explain`) + |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + | Access to non-public method b causes the automatic generation of an accessor. + | This accessor is not stable, its name may change or it may disappear + | if not needed in a future version. + | + | To make sure that the inlined code is binary compatible you must make sure that + | method b is public in the binary API. + | * Option 1: Annotate method b with @publicInBinary + | * Option 2: Make method b public + | + | This change may break binary compatibility if a previous version of this + | library was compiled with generated accessors. Binary compatibility should + | be checked using MiMa. If binary compatibility is broken, you should add the + | old accessor explicitly in the source code. The following code should be + | added to class C: + | @publicInBinary private[C] def C$$inline$b: Int = this.b + ----------------------------------------------------------------------------- +-- [E...] Compatibility Warning: C.scala ----------------------------- + | inline def foo: Int = a + b + c + d + | ^ + | Unstable inline accessor C$$inline$d was generated in class C. + |----------------------------------------------------------------------------- + | Explanation (enabled by `-explain`) + |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + | Access to non-public method d causes the automatic generation of an accessor. + | This accessor is not stable, its name may change or it may disappear + | if not needed in a future version. + | + | To make sure that the inlined code is binary compatible you must make sure that + | method d is public in the binary API. + | * Option 1: Annotate method d with @publicInBinary + | * Option 2: Make method d public + | + | This change may break binary compatibility if a previous version of this + | library was compiled with generated accessors. Binary compatibility should + | be checked using MiMa. If binary compatibility is broken, you should add the + | old accessor explicitly in the source code. The following code should be + | added to class C: + | @publicInBinary private[C] def C$$inline$d: Int = this.d + ----------------------------------------------------------------------------- +~~~ + +
            + +### Specification + +We must add `publicInBinary` to the standard library. + +```scala +package scala.annotation + +final class publicInBinary extends scala.annotation.StaticAnnotation +``` + +#### `@publicInBinary` annotation + +* Only valid on `def`, `val`, `lazy val`, `var`, `object`, and `given`. +* If a definition overrides a `@publicInBinary` definition, it must also be annotated with `@publicInBinary`. +* TASTy will contain references to non-public definitions that are out of scope but `@publicInBinary`. TASTy already allows those references. +* The annotated definitions will be public in the generated bytecode. Definitions should be made public as early as possible in the compiler phases, as this can remove the need to create other accessors. It should be done after we check the accessibility of references. + +#### Inline + +* Inlining will not require the generation of an inline accessor for binary APIs. +* The user will be warned if a new inline accessor is automatically generated under `-WunstableInlineAccessors`. + The message will suggest `@publicInBinary` and how to fix potential incompatibilities. + +### Compatibility + +The introduction of the `@publicInBinary` do not introduce any binary incompatibility. + +Using references to `@publicInBinary` in inline code can cause binary incompatibilities. These incompatibilities are equivalent to the ones that can occur due to the unsoundness we want to fix. When migrating to binary APIs, the compiler will show the implementation of accessors that the users need to add to keep binary compatibility with pre-publicInBinary code. + +### Other concerns + +* Tools that analyze inlined TASTy code will need to know about `@publicInBinary`. For example [MiMa](https://github.com/lightbend/mima/) and [TASTy MiMa](https://github.com/scalacenter/tasty-mima). + +## Alternatives + +### Add a `@binaryAccessor` +This annotation would generate an stable accessor. This annotation could be used on `private` definition. It would also mitigate [migration costs](https://gist.github.com/nicolasstucki/003f7293941836b08a0d53dbcb913e3c) for library authors that have published unstable accessors. + +* Implementation https://github.com/scala/scala3/pull/16992 + + +### Make all `private[C]` part of the binary API + +Currently, we already make `private[C]` public in the binary API but do not have the same guarantees regarding binary compatibility. +For example, the following change is binary compatible but would remove the existence of the `private[C]` definition in the bytecode. +```diff +class C: +- private[C] def f: T = ... +``` +We could change the rules to make all `private[C]` part of binary compatible to flag such a change as binary incompatible. This would imply that all these +methods can be accessed directly from inline methods without generating an accessor. + +The drawback of this approach is that that we would need to force users to keep their `private[C]` methods even if they never used inline methods. + + +## Related work + +* Initial discussions: [https://github.com/scala/scala3/issues/16983](https://github.com/scala/scala3/issues/16983) +* Initial proof of concept (outdated): [https://github.com/scala/scala3/pull/16992](https://github.com/scala/scala3/pull/16992) +* Single annotation proof of concept: [https://github.com/scala/scala3/pull/18402](https://github.com/scala/scala3/pull/18402) +* Community migration analysis: [Gist](https://gist.github.com/nicolasstucki/003f7293941836b08a0d53dbcb913e3c) +* Kotlin: [PublishedApi](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-published-api/) plays the same role as `@publicInBinary` + but its interaction with (inline definitions)[https://kotlinlang.org/docs/inline-functions.html#restrictions-for-public-api-inline-functions] + is stricter as they do not support automatic accessor generation. + + diff --git a/_sips/sips/binary-integer-literals.md b/_sips/sips/binary-integer-literals.md new file mode 100644 index 0000000000..ef761601fb --- /dev/null +++ b/_sips/sips/binary-integer-literals.md @@ -0,0 +1,33 @@ +--- +layout: sip +title: SIP-42 - Support Binary Integer Literals +stage: completed +status: shipped +permalink: /sips/:title.html +--- + +**By: NthPortal** + +## History + +| Date | Version | +|---------------|--------------------------| +| Jul 27th 2019 | Initial Draft | + +Your feedback is welcome! If you're interested in discussing this proposal, head over to [this](https://contributors.scala-lang.org/t/pre-sip-binary-literals/3559) Scala Contributors thread and let me know what you think. + +## Proposal + +Support binary integer literals. For example, the binary literal `0b00101010` would have the integer value `42`. + +## Motivation + +Several other major languages support binary integer literals, including [Java](https://docs.oracle.com/javase/specs/jls/se12/html/jls-3.html#jls-3.10.1) (as of [Java 7](https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.1)), [Kotlin](https://kotlinlang.org/docs/reference/basic-types.html#literal-constants), [Python](https://docs.python.org/3/reference/lexical_analysis.html#integer-literals) and [Rust](https://doc.rust-lang.org/stable/reference/tokens.html#number-literals). + +## Interactions with Other Language Features + +Like other integer literals, binary integer literals support separators (`_`), which can greatly enhance the readability of larger values (e.g. `0b_1110_1101_1011_0111`). + +## Implementation + +The implementation of binary integer literals is quite simple, and can be found at . diff --git a/_sips/sips/2017-11-20-byname-implicits.md b/_sips/sips/byname-implicits.md similarity index 99% rename from _sips/sips/2017-11-20-byname-implicits.md rename to _sips/sips/byname-implicits.md index f2bbffe911..fd63269068 100644 --- a/_sips/sips/2017-11-20-byname-implicits.md +++ b/_sips/sips/byname-implicits.md @@ -1,13 +1,14 @@ --- layout: sip -discourse: true -title: SIP-NN - Byname implicit arguments - -vote-status: pending +title: SIP-31 - Byname implicit arguments +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/byname-implicits.html --- +> This proposal has been implemented in Scala 2.13.0 and Scala 3.0.0. + **Author: Miles Sabin** **Supervisor and advisor: Martin Odersky** @@ -38,7 +39,7 @@ the knot" implicitly. ### Implementation status -Byname implicits have been implemented in [Dotty](https://github.com/lampepfl/dotty/issues/1998) +Byname implicits have been implemented in [Dotty](https://github.com/scala/scala3/issues/1998) with an earlier iteration of the divergence checking algorithm described below. A full implementation of this proposal exists as a [pull request](https://github.com/scala/scala/pull/6050) relative to the 2.13.x branch of the Lightbend Scala compiler and it is scheduled to be included in @@ -166,7 +167,7 @@ object Semigroup { } } ``` - + then we can manually write instances for, for example, tuples of types which have `Semigroup` instances, @@ -386,7 +387,7 @@ val showListInt: Show[List[Int]] = showUnit ) ) -``` +``` where at least one argument position between the val definition and the recursive occurrence of `showListInt` is byname. @@ -498,16 +499,16 @@ any _Tj_, where _i_ < _j_. The essence of the algorithm described in the Scala Language Specification is as follows, > Call the sequence of open implicit types _O_. This is initially empty. -> -> To resolve an implicit of type _T_ given stack of open implicits _O_, -> +> +> To resolve an implicit of type _T_ given stack of open implicits _O_, +> > + Identify the definition _d_ which satisfies _T_. -> +> > + If the core type of _T_ dominates any element of _O_ then we have observed divergence and we're > done. -> +> > + If _d_ has no implicit arguments then the result is the value yielded by _d_. -> +> > + Otherwise for each implicit argument _a_ of _d_, resolve _a_ against _O+T_, and the result is the > value yielded by _d_ applied to its resolved arguments. @@ -549,15 +550,15 @@ divergence check across the set of relevant implicit definitions. This gives us the following, -> To resolve an implicit of type _T_ given stack of open implicits _O_, -> +> To resolve an implicit of type _T_ given stack of open implicits _O_, +> > + Identify the definition _d_ which satisfies _T_. -> +> > + If the core type of _T_ dominates the type _U_ of some element __ of _O_ then we have > observed divergence and we're done. -> +> > + If _d_ has no implicit arguments then the result is the value yielded by _d_. -> +> > + Otherwise for each implicit argument _a_ of _d_, resolve _a_ against _O+_, and the result is > the value yielded by _d_ applied to its resolved arguments. @@ -645,8 +646,8 @@ larger than _U_ despite using only elements that are present in _U_. This gives us the following, -> To resolve an implicit of type _T_ given stack of open implicits _O_, -> +> To resolve an implicit of type _T_ given stack of open implicits _O_, +> > + Identify the definition _d_ which satisfies _T_. > > + if there is an element _e_ of _O_ of the form __ such that at least one element between _e_ @@ -657,7 +658,7 @@ This gives us the following, > observed divergence and we're done. > > + If _d_ has no implicit arguments then the result is the value yielded by _d_. -> +> > + Otherwise for each implicit argument _a_ of _d_, resolve _a_ against _O+_, and the result is > the value yielded by _d_ applied to its resolved arguments. @@ -850,7 +851,7 @@ object Test { because the path `foo` in `foo.Out` is not stable. Full parity with shapeless's `Lazy` would require lazy (rather than byname) implicit parameters (see [this Dotty -ticket](https://github.com/lampepfl/dotty/issues/3005) for further discussion) and is orthogonal to +ticket](https://github.com/scala/scala3/issues/3005) for further discussion) and is orthogonal to this SIP in that they would drop out of support for lazy parameters more generally, as described in [this Scala ticket](https://github.com/scala/bug/issues/240). diff --git a/_sips/sips/clause-interleaving.md b/_sips/sips/clause-interleaving.md new file mode 100644 index 0000000000..e9809815e2 --- /dev/null +++ b/_sips/sips/clause-interleaving.md @@ -0,0 +1,173 @@ +--- +layout: sip +title: SIP-47 - Clause Interleaving +stage: completed +status: shipped +permalink: /sips/:title.html +--- + +**By: Quentin Bernet and Guillaume Martres and Sébastien Doeraene** + +## History + +| Date | Version | +|---------------|-----------------------| +| May 5th 2022 | Initial Draft | +| Aug 17th 2022 | Formatting | +| Sep 22th 2022 | Type Currying removed | + +## Summary + +We propose to generalize method signatures to allow any number of type parameter lists, interleaved with term parameter lists and using parameter lists. As a simple example, it would allow to define +~~~ scala +def pair[A](a: A)[B](b: B): (A, B) = (a, b) +~~~ +Here is also a more complicated and contrived example that highlights all the possible interactions: +~~~ scala +def foo[A](using a: A)(b: List[A])[C <: a.type, D](cd: (C, D))[E]: Foo[A, B, C, D, E] +~~~ + + +## Motivation + +Consider an API for a heterogenous key-value store, where keys know what type of value they must be associated to: +~~~ scala +trait Key: + type Value + +class Store: + def get(key: Key): key.Value = … + def put(key: Key)(value: => key.Value): Unit = … +~~~ +We want to provide a method `getOrElse`, taking a default value to be used if the key is not present. Such a method could look like +~~~ scala +def getOrElse(key: Key)(default: => key.Value): key.Value = … +~~~ +However, at call site, it would prevent from using as default value a value that is not a valid `key.Value`. This is a limitation compared to other `getOrElse`-style methods such as that of `Option`, which allow passing any supertype of the element type. + +In current Scala, there is no way to define `Store.getOrElse` in a way that supports this use case. We may try to define it as +~~~ scala +def getOrElse[V >: key.Value](key: Key)(default: => V): V = … +~~~ +but that is not valid because the declaration of `V` needs to refer to the path-dependent type `key.Value`, which is defined in a later parameter list. + +We might also try to move the type parameter list after `key` to avoid that problem, as +~~~ scala +def getOrElse(key: Key)[V >: key.Value](default: => V): V = … +~~~ +but that is also invalid because type parameter lists must always come first. + +A workaround is to return an intermediate object with an `apply` method, as follows: +~~~ scala +class Store: + final class StoreGetOrElse[K <: Key](val key: K): + def apply[V >: key.Value](default: => V): V = … + def getOrElse(key: Key): StoreGetOrElse[key.type] = StoreGetOrElse(key) +~~~ +This definition provides the expected source API at call site, but it has two issues: +* It is more complex than expected, forcing a user looking at the API to navigate to the definition of `StoreGetOrElse` to make sense of it. +* It is inefficient, as an intermediate instance of `StoreGetOrElse` must be created for each call to `getOrElse`. +* Overloading resolution looks at clauses after the first one, but only in methods, the above is ambiguous with any `def getOrElse(k:Key): ...`, whereas the proposed signature is not ambiguous with for example `def getOrElse(k:Key)[A,B](x: A, y: B)` + +Another workaround is to return a polymorphic function, for example: +~~~scala +def getOrElse(k:Key): [V >: k.Value] => (default: V) => V = + [V] => (default: V) => ??? +~~~ +While again, this provides the expected API at call site, it also has issues: +* The behavior is not the same, as `default` has to be a by-value parameter +* The definition is hard to visually parse, as users are more used to methods (and it is our opinion this should remain so) +* The definition is cumbersome to write, especially if there are a lot of term parameters +* It is inefficient, as many closures must be created for each call to `getOrElse` (one per term clause to the right of the first non-initial type clause). +* Same problem as above with overloading + +## Proposed solution +### High-level overview + +To solve the above problems, we propose to generalize method signatures so that they can have multiple type parameter lists, interleaved with term parameter lists and using parameter lists. + +For the heterogeneous key-value store example, this allows to define `getOrElse` as follows: +~~~ scala +def getOrElse(key: Key)[V >: key.Value](default: => V): V = … +~~~ +It provides the best of all worlds: +* A convenient API at call site +* A single point of documentation +* Efficiency, since the method erases to a single JVM method with signature `getOrElse(Object,Object)Object` + +### Specification +We amend the syntax of def parameter clauses as follows: +~~~ +DefDcl ::= DefSig ‘:’ Type +DefDef ::= DefSig [‘:’ Type] ‘=’ Expr +DefSig ::= id [DefParamClauses] [DefImplicitClause] +DefParamClauses ::= DefParamClause { DefParamClause } -- and two DefTypeParamClause cannot be adjacent +DefParamClause ::= DefTypeParamClause + | DefTermParamClause + | UsingParamClause +DefTypeParamClause ::= [nl] ‘[’ DefTypeParam {‘,’ DefTypeParam} ‘]’ +DefTypeParam ::= {Annotation} id [HkTypeParamClause] TypeParamBounds +DefTermParamClause ::= [nl] ‘(’ [DefTermParams] ‘)’ +UsingParamClause ::= [nl] ‘(’ ‘using’ (DefTermParams | FunArgTypes) ‘)’ +DefImplicitClause ::= [nl] ‘(’ ‘implicit’ DefTermParams ‘)’ +DefTermParams ::= DefTermParam {‘,’ DefTermParam} +DefTermParam ::= {Annotation} [‘inline’] Param +Param ::= id ‘:’ ParamType [‘=’ Expr] +~~~ + +The main rules of interest are `DefParamClauses` and `DefParamClauseChunk`, which now allow any number of type parameter clauses, term parameter clauses and using parameter clauses, in any order as long as there are no two adjacent type clauses. + +Note that these are also used for the right-hand side of extension methods, thus clause interleaving also applies to them. + +It is worth pointing out that there can still only be at most one implicit parameter clause, which, if present, must be at the end. + +The type system and semantics naturally generalize to these new method signatures. + +### Restrictions + +#### Type Currying +Currying type clauses enables partial type inference, as the left clause can be specified while the right one is not. +As this is a very useful feature, we expect people would use it liberally, and recommending the curried form. +We are uncertain about the readability of the resulting methods, we have therefore decided to not include type currying as part of this proposal. + +Note however that, if absolutely necessary, it is still possible to curry type parameters as such: `def foo[A](using DummyImplicit)[B]`, since the implicit search for `DummyImplicit` will always succeed. +This is sufficiently unwieldy that it is unlikely the above becomes the norm. + +#### Class Signatures +Class signatures are unchanged. Classes can still only have at most one type parameter list, which must come first. For example, the following definition is still invalid: +~~~ scala +class Pair[+A](val a: A)[+B](val b: B) +~~~ +Class signatures already have limitations compared to def signatures. For example, they must have at least one term parameter list. There is therefore precedent for limiting their expressiveness compared to def parameter lists. + +The rationale for this restriction is that classes also define associated types. It is unclear what the type of an instance of `Pair` with `A` and `B` should be. It could be defined as `Foo[A][B]`. That still leaves holes in terms of path-dependent types, as `B`'s definition could not depend on the path `a`. Allowing interleaved type parameters for class definitions is therefore restricted for now. It could be allowed with a follow-up proposal. + +Note: As `apply` is a normal method, it is totally possible to define a method `def apply[A](a: A)[B](b: B)` on `Pair`'s companion object, allowing to create instances with `Pair[Int](4)[Char]('c')`. + +#### LHS of extension methods +The left hand side of extension methods remains unchanged, since they only have one explicit term clause, and since the type parameters are very rarely passed explicitly, it is not as necessary to have multiple type clauses there. + +Currently, Scala 2 can only call/override methods with at most one leading type parameter clause, which already forbids calling extension methods like `extension (x: Int) def bar[A](y: A)`, which desugars to `def bar(x: Int)[A](y: A)`. This proposal does not change this, so methods like `def foo[A](x: A)[B]` will not be callable from Scala 2. + +### Compatibility +The proposal is expected to be backward source compatible. New signatures currently do not parse, and typing rules are unchanged for existing signatures. + +Backward binary compatibility is straightforward. + +Backward TASTy compatibility should be straightforward. The TASTy format is such that we can extend it to support interleaved type parameter lists without added complexity. If necessary, a version check can decide whether to read signatures in the new or old format. For typechecking, like for source compatibility, the typing rules are unchanged for signatures that were valid before. + +Of course, libraries that choose to evolve their public API to take advantage of the new signatures may expose incompatibilities. + +## Alternatives +The proposal is a natural generalization of method signatures. +We could have extended the proposal to type currying (allowing partial type inference), but have not due to the concerns mentionned in [Restrictions](#restrictions). +This might be the subject of a follow up proposal, if the concerns can be addressed. + +As discussed above, we may want to consider generalizing class parameter lists as well. However, we feel it is better to leave that extension to a follow-up proposal, if required. + +## Related work +* Pre-SIP: [https://contributors.scala-lang.org/t/clause-interweaving-allowing-def-f-t-x-t-u-y-u/5525](https://contributors.scala-lang.org/t/clause-interweaving-allowing-def-f-t-x-t-u-y-u/5525) +* An implementation of the proposal is available as a pull request at [https://github.com/scala/scala3/pull/14019](https://github.com/scala/scala3/pull/14019) + +## FAQ +Currently empty. diff --git a/_sips/sips/comonadic-comprehensions.md b/_sips/sips/comonadic-comprehensions.md new file mode 100644 index 0000000000..d668fc4d78 --- /dev/null +++ b/_sips/sips/comonadic-comprehensions.md @@ -0,0 +1,6 @@ +--- +title: SIP-NN - comonadic-comprehensions +status: rejected +pull-request-number: 32 + +--- diff --git a/_sips/sips/concurrency-with-higher-order-coroutines.md b/_sips/sips/concurrency-with-higher-order-coroutines.md new file mode 100644 index 0000000000..837df46236 --- /dev/null +++ b/_sips/sips/concurrency-with-higher-order-coroutines.md @@ -0,0 +1,7 @@ +--- +title: SIP-55 - Concurrency with Higher-Order Coroutines +status: under-review +pull-request-number: 63 +stage: design + +--- diff --git a/_sips/sips/2018-08-20-converters-among-optional-functions-partialfunctions-and-extractor-objects.md b/_sips/sips/converters-among-optional-functions-partialfunctions-and-extractor-objects.md similarity index 91% rename from _sips/sips/2018-08-20-converters-among-optional-functions-partialfunctions-and-extractor-objects.md rename to _sips/sips/converters-among-optional-functions-partialfunctions-and-extractor-objects.md index 0e2b8e9ca5..cad08453c3 100644 --- a/_sips/sips/2018-08-20-converters-among-optional-functions-partialfunctions-and-extractor-objects.md +++ b/_sips/sips/converters-among-optional-functions-partialfunctions-and-extractor-objects.md @@ -1,9 +1,14 @@ --- -layout: sips -discourse: true -title: SIP-NN - Converters among optional Functions, PartialFunctions and extractor objects +layout: sip +title: SIP-38 - Converters among optional Functions, PartialFunctions and extractor objects +stage: completed +status: shipped +permalink: /sips/:title.html +redirect_from: /sips/pending/converters-among-optional-functions-partialfunctions-and-extractor-object.html --- +> This proposal has been implemented in Scala 2.13.0 and Scala 3.0.0. + **By: Yang Bo** @@ -144,4 +149,4 @@ The new implementation aims to become part of core library. The pull request can 2. [Related Pull Request][2] [1]: https://github.com/ThoughtWorksInc/Extractor.scala "Extractor.scala" -[2]: https://github.com/scala/scala/pull/7111 "#7111" \ No newline at end of file +[2]: https://github.com/scala/scala/pull/7111 "#7111" diff --git a/_sips/sips/curried-varargs.md b/_sips/sips/curried-varargs.md new file mode 100644 index 0000000000..402630e152 --- /dev/null +++ b/_sips/sips/curried-varargs.md @@ -0,0 +1,6 @@ +--- +title: SIP-45 - Curried varargs +status: rejected +pull-request-number: 41 + +--- diff --git a/_sips/sips/drop-stdlib-forwards-bin-compat.md b/_sips/sips/drop-stdlib-forwards-bin-compat.md new file mode 100644 index 0000000000..771804f668 --- /dev/null +++ b/_sips/sips/drop-stdlib-forwards-bin-compat.md @@ -0,0 +1,315 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: implementation +status: under-review +title: SIP-51 - Drop Forwards Binary Compatibility of the Scala 2.13 Standard Library +--- + +**By: Lukas Rytz** + + +## History + +| Date | Version | +|----------------|--------------------| +| Dec 8, 2022 | Initial Version | + + +## Summary + +I propose to drop the forwards binary compatibility requirement that build tools enforce on the Scala 2.13 standard library. +This will allow implementing performance optimizations of collection operations that are currently not possible. +It also unblocks adding new classes and new members to existing classes in the standard library. + + +## Backwards and Forwards Compatibility + +A library is backwards binary compatible if code compiled against an old version works with a newer version on the classpath. +Forwards binary compatibility requires the opposite: code compiled against a new version of a library needs to work with an older version on the classpath. +A more in-depth explanation of binary compatibility is available on the [Scala documentation site](https://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html). + +Scala build tools like sbt automatically update dependencies on the classpath to the latest patch version that any other dependency on the classpath requires. +For example, with the following definition + +~~~ scala +libraryDependencies ++= List( + "com.softwaremill.sttp.client3" %% "core" % "3.8.3", // depends on ws 1.3.10 + "com.softwaremill.sttp.shared" %% "ws" % "1.2.7", // for demonstration +) +~~~ + +sbt updates the `ws` library to version 1.3.10. +Running the `evicted` command in sbt displays all dependencies whose version were changed. + +This build tool feature allows library authors to only maintain backwards binary compatibility in new versions, they don't need to maintain forwards binary compatibility. +Backwards binary compatible changes include the addition of new methods in existing classes and the addition of new classes. +Such additions don't impact existing code that was compiled against an older version, all definitions that were previously present are still there. + +### The Standard Library + +The Scala standard library is treated specially by sbt and other build tools, its version is always pinned to the `scalaVersion` of the build definition and never updated automatically. + +For example, the `"com.softwaremill.sttp.client3" %% "core" % "3.8.3"` library has a dependency on `"org.scala-lang" % "scala-library" % "2.13.10"` in its POM file. +When a project uses this version of the sttp client in a project with `scalaVersion` 2.13.8, sbt will put the Scala library version 2.13.8 on the classpath. + +This means that the standard library is required to remain both backwards and forwards binary compatible. +The implementation of sttp client 3.8.3 can use any feature available in Scala 2.13.10, and that compiled code needs to work correctly with the Scala 2.13.8 standard library. + +The suggested change of this SIP is to drop this special handling of the Scala standard library and therefore lift the forwards binary compatibility requirement. + + +## Motivation + +### Adding Overrides for Performance + +The forwards binary compatibility constraint regularly prevents adding optimized overrides to collection classes. +The reason is that the bytecode signature of an overriding method is not necessarily identical to the signature of the overridden method. +Example: + +~~~ scala +class A { def f: Object = "" } +class B extends A { override def f: String = "" } +~~~ + +The bytecode signature of `B.f` has return type `String`. +(In order to implement dynamic dispatch at run time (overriding), the compiler generates a "bridge" method `B.f` with return type `Object` which forwards to the other `B.f` method.) +Adding such an override is not forwards binary compatible, because code compiled against `B` can link to the `B.f` method with return type `String`, which would not exist in the previous version. + +It's common that forwards binary compatibility prevents adding optimizing overrides, most recently in [LinkedHashMap](https://github.com/scala/scala/pull/10235#issuecomment-1336781619). + +Sometimes, if an optimization is considered important, a type test is added to the existing implementation to achieve the same effect. +These workarounds could be cleaned up. +Examples are [`mutable.Map.mapValuesInPlace`](https://github.com/scala/scala/blob/v2.13.10/src/library/scala/collection/mutable/Map.scala#L201-L204), [`IterableOnce.foldLeft`](https://github.com/scala/scala/blob/v2.13.10/src/library/scala/collection/IterableOnce.scala#L669-L670), [`Set.concat`](https://github.com/scala/scala/blob/v2.13.10/src/library/scala/collection/Set.scala#L226-L227), and many more. + +### Adding Functionality + +Dropping forwards binary compatiblity allows adding new methods to existing classes, as well as adding new classes. +While this opens a big door in principle, I am certain that stability, consistency and caution will remain core considerations when discussing additions to the standard library. +However, I believe that allowing to (carefully) evolve the standard library is greatly beneficial for the Scala community. + +Examples that came up in the past + - various proposals for new operations are here: https://github.com/scala/scala-library-next/issues and https://github.com/scala/scala-library-next/pulls + - addition of `ExecutionContext.opportunistic` in 2.13.4, which could not be made public: https://github.com/scala/scala/pull/9270 + - adding `ByteString`: https://contributors.scala-lang.org/t/adding-akkas-bytestring-as-a-scala-module-and-or-stdlib/5967 + - new string interpolators: https://github.com/scala/scala/pull/8654 + +## Alternatives and Related Work + +For binary compatible overrides, it was considered to add an annotation that would enforce the existing signature in bytecode. +However, this approach turned out to be too complex in the context of further overrides and Java compatibility. +Details are in the [corresponding pull request](https://github.com/scala/scala/pull/9141). + +Extensions to the standard library can be implemented in a separate library, and such a library exists since 2020 as [scala-library-next](https://github.com/scala/scala-library-next). +This library has seen very little adoption so far, and I personally don't think this is likely going (or possible) to change. +One serious drawback of an external library is that operations on existing classes can only be added as extension methods, which makes them less discoverable and requires adding an import. +This drawback could potentially be mitigated with improvements in Scala IDEs. + +An alternative to `scala-library-next` would be to use the Scala 3 library (`"org.scala-lang" % "scala3-library_3"`) which is published with Scala 3 releases. +This library is handled by build tools like any other library and therefore open for backwards binary compatible additions. +Until now, the Scala 3 library is exclusively used as a "runtime" library for Scala 3, i.e., it contanis definitions that are required for running code compiled with Scala 3. +Additions to the Scala 3 library would not be available to the still very large userbase of Scala 2.13. +Like for `scala-library-next`, additions to existing classes can again only be done in the form of extension methods. +Also, I believe that there is great value in keeping the Scala 2.13 and 3 standard libraries aligned for now. + + +## Implications + +### Possible Linkage Errors + +The policy change can only be implemented in new build tool releases, which makes it possible that projects run into linkage errors at run time. +Concretely, a project might update one of its dependencies to a new version which requires a more recent Scala library than the one defined in the project's `scalaVersion`. +If the project continues using an old version of sbt, the build tool will keep the Scala library pinned. +The new library might reference definitions that don't exist in the older Scala library, leading to linkage errors. + +### Scala.js and Scala Native + +Scala.js distributes a JavaScript version of the Scala library. +This artifact is currently released once per Scala.js version. +When a new Scala version comes out, a new Scala.js compiler is released, but the Scala library artifact continues to be used until the next Scala.js version. +This scheme does not work if the new Scala version has new definitions, so it needs to be adjusted. +Finding a solution for this problem is necessary and part of the implementation phase. + +A similar situation might exist for Scala Native. + +### Compiler and Library Version Mismatch + +Defining the `scalaVersion` in a project would no longer pin the standard library to that exact version. +The Scala compiler on the other hand would be kept at the specified version. +This means that Scala compilers will need to be able to run with a newer version of the Scala library, e.g., the Scala compiler 2.13.10 needs to be able to run with a 2.13.11 standard library on the compilation classpath. +I think this will not cause any issues. + +Note that there are two classpaths at play here: the runtime classpath of the JVM that is running the Scala compiler, and the compilation classpath in which the compiler looks up symbols that are referenced in the source code being compiled. +The Scala library on the JVM classpath could remain in sync with the compiler version. +The Scala library on the compilation classpath would be updated by the build tool according to the dependency graph. + +### Newer than Expected Library + +Because the build tool can update the Scala library version, a project might accidentally use / link to new API that does not yet exist in the `scalaVersion` that is defined in the build definition. +This is safe, as the project's POM file will have a dependency on the newer version of the Scala library. +The same situation can appear with any other dependency of a project. + +### Applications with Plugin Systems + +In applications where plugins are dynamically loaded, plugins compiled with a new Scala library could fail to work correctly if the application is running with an older Scala library. + +This is however not a new issue, the proposed change would just extend the existing problem to the Scala library. + +## Limitations + +Adding new methods or fields to existing traits remains a binary incompatible change. +This is unrelated to the Standard library, the same is true for other libraries. +[MiMa](https://github.com/lightbend/mima) is a tool for ensuring changes are binary compatible. + + +## Build Tools + +### Mill + +In my testing, Mill has the same behavior as sbt, the Scala library version is pinned to the project's `scalaVersion`. + +
            + +~~~ +$> cat build.sc +import mill._, scalalib._ +object proj extends ScalaModule { + def scalaVersion = "2.13.8" + def ivyDeps = Agg( + ivy"com.softwaremill.sttp.client3::core:3.8.3", + ivy"com.softwaremill.sttp.shared::ws:1.2.7", + ) +} +$> mill show proj.runClasspath +[1/1] show > [37/37] proj.runClasspath +[ + "qref:868554b6:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/client3/core_2.13/3.8.3/core_2.13-3.8.3.jar", + "qref:f3ba6af6:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/shared/ws_2.13/1.3.10/ws_2.13-1.3.10.jar", + "qref:438104da:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/org/scala-lang/scala-library/2.13.8/scala-library-2.13.8.jar", + "qref:0c9ef1ab:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/model/core_2.13/1.5.2/core_2.13-1.5.2.jar", + "qref:9b3d3f7d:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/shared/core_2.13/1.3.10/core_2.13-1.3.10.jar" +] +~~~ + +
            + +### Gradle + +Gradle handles the Scala library the same as other dependencies, so it already implements the behavior proposed by this SIP. + +
            + +~~~ +$> cat build.gradle +plugins { + id 'scala' +} +repositories { + mavenCentral() +} +dependencies { + implementation 'org.scala-lang:scala-library:2.13.8' + implementation 'com.softwaremill.sttp.client3:core_2.13:3.8.3' + implementation 'com.softwaremill.sttp.shared:ws_2.13:1.2.7' +} +$> gradle dependencies --configuration runtimeClasspath + +> Task :dependencies + +------------------------------------------------------------ +Root project 'proj' +------------------------------------------------------------ + +runtimeClasspath - Runtime classpath of source set 'main'. ++--- org.scala-lang:scala-library:2.13.8 -> 2.13.10 ++--- com.softwaremill.sttp.client3:core_2.13:3.8.3 +| +--- org.scala-lang:scala-library:2.13.10 +| +--- com.softwaremill.sttp.model:core_2.13:1.5.2 +| | \--- org.scala-lang:scala-library:2.13.8 -> 2.13.10 +| +--- com.softwaremill.sttp.shared:core_2.13:1.3.10 +| | \--- org.scala-lang:scala-library:2.13.9 -> 2.13.10 +| \--- com.softwaremill.sttp.shared:ws_2.13:1.3.10 +| +--- org.scala-lang:scala-library:2.13.9 -> 2.13.10 +| +--- com.softwaremill.sttp.shared:core_2.13:1.3.10 (*) +| \--- com.softwaremill.sttp.model:core_2.13:1.5.2 (*) +\--- com.softwaremill.sttp.shared:ws_2.13:1.2.7 -> 1.3.10 (*) + +(*) - dependencies omitted (listed previously) +~~~ + +
            + +### Maven + +Maven [does not update](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html) versions of dependencies that are explicitly listed in the `pom.xml` file, so it's possible to run into linkage errors at run time already now. +The maven versions plugin can display and update dependencies to newer versions. + +
            + +~~~ +$> cat pom.xml + + + 4.0.0 + a.b + proj + 1.0.0-SNAPSHOT + + UTF-8 + UTF-8 + 1.8 + 2.13.8 + + + + org.scala-lang + scala-library + ${scala.version} + + + com.softwaremill.sttp.client3 + core_2.13 + 3.8.3 + + + com.softwaremill.sttp.shared + ws_2.13 + 1.2.7 + + + + + + net.alchim31.maven + scala-maven-plugin + 4.8.0 + + + + +$> mvn dependency:build-classpath +[INFO] --- maven-dependency-plugin:2.8:build-classpath (default-cli) @ proj --- +[INFO] Dependencies classpath: +/Users/luc/.m2/repository/org/scala-lang/scala-library/2.13.8/scala-library-2.13.8.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/client3/core_2.13/3.8.3/core_2.13-3.8.3.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/model/core_2.13/1.5.2/core_2.13-1.5.2.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/shared/core_2.13/1.3.10/core_2.13-1.3.10.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/shared/ws_2.13/1.2.7/ws_2.13-1.2.7.jar +$> mvn versions:display-dependency-updates +[INFO] --- versions-maven-plugin:2.13.0:display-dependency-updates (default-cli) @ proj --- +[INFO] The following dependencies in Dependencies have newer versions: +[INFO] com.softwaremill.sttp.client3:core_2.13 ............... 3.8.3 -> 3.8.5 +[INFO] com.softwaremill.sttp.shared:ws_2.13 ................. 1.2.7 -> 1.3.12 +[INFO] org.scala-lang:scala-library ....................... 2.13.8 -> 2.13.10 +~~~ + +
            + +### Bazel + +I have never used bazel and did not manage set up / find a sample build definition to test its behavior. +Help from someone knowing bazel would be appreciated. + +### Pants + +As with bazel, I did not yet manage to set up / find an example project. + +### Other Tools + +The SIP might also require changes in other tools such as scala-cli, coursier or bloop. diff --git a/_sips/sips/early-member-definitions.md b/_sips/sips/early-member-definitions.md new file mode 100644 index 0000000000..244b7c15b3 --- /dev/null +++ b/_sips/sips/early-member-definitions.md @@ -0,0 +1,10 @@ +--- +layout: sip +title: SID-4 - Early Member Definitions +stage: completed +status: shipped +permalink: /sips/:title.html +redirect_from: /sips/pending/early-member-definitions.html +--- + +This was an older SID that can be found [here](https://www.scala-lang.org/sid/4) diff --git a/_sips/sips/eference-able-package-objects.md b/_sips/sips/eference-able-package-objects.md new file mode 100644 index 0000000000..cfba956529 --- /dev/null +++ b/_sips/sips/eference-able-package-objects.md @@ -0,0 +1,7 @@ +--- +title: 'SIP-68: Reference-able Package Objects' +status: under-review +pull-request-number: 100 +stage: implementation + +--- diff --git a/_sips/sips/fewer-braces.md b/_sips/sips/fewer-braces.md new file mode 100644 index 0000000000..321f665233 --- /dev/null +++ b/_sips/sips/fewer-braces.md @@ -0,0 +1,296 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: completed +status: shipped +title: SIP-44 - Fewer Braces +--- + +**By: Martin Odersky** + +## History + +| Date | Version | +|----------------|--------------------| +| July 1st 2022 | Initial Draft | +| July 21st 2022 | Expanded Other Conerns Section | + +## Summary + +The current state of Scala 3 makes braces optional around blocks and template definitions (i.e. bodies of classes, objects, traits, enums, or givens). This SIP proposes to allow optional braces also for function arguments. +The advantages of doing so is that the language feels more systematic, and programs become typographically cleaner. +The changes have been implemented and and made available under the language import `language.experimental.fewerBraces`. The proposal here is to make them available without a language import instead. + + +## Motivation + +After extensive experience with the current indentation rules I conclude that they are overall a big success. +However, they still feel incomplete and a bit unsystematic since we can replace `{...}` in the majority of situations, but there are also important classes of situations where braces remain mandatory. In particular, braces are currently needed around blocks as function arguments. + +It seems very natural to generalize the current class syntax indentation syntax to function arguments. In both cases, an indentation block is started by a colon at the end of a line. Doing so will bring two major benefits: + + - Better _consistency_, since we avoid the situation where braces are sometimes optional and in other places mandatory. + - Better _readability_ in many common use cases, similar to why current + optional braces lead to better readability. + +## Proposed solution + +The proposed solution is described in detail in https://dotty.epfl.ch/docs/reference/other-new-features/indentation.html#variant-indentation-marker--for-arguments. I inline the relevant sections here: + +First, here is the spec for colons at ends of lines for template bodies. This is part of official Scala 3. I cited it here for context. + +> A template body can alternatively consist of a colon followed by one or more indented statements. To this purpose we introduce a new `` token that reads as +the standard colon "`:`" but is generated instead of it where `` +is legal according to the context free syntax, but only if the previous token +is an alphanumeric identifier, a backticked identifier, or one of the tokens `this`, `super`, "`)`", and "`]`". + +> An indentation region can start after a ``. A template body may be either enclosed in braces, or it may start with +` ` and end with ``. +Analogous rules apply for enum bodies, type refinements, and local packages containing nested definitions. + +Generally, the possible indentation regions coincide with those regions where braces `{...}` are also legal, no matter whether the braces enclose an expression or a set of definitions. There is so far one exception, though: Arguments to functions can be enclosed in braces but they cannot be simply indented instead. Making indentation always significant for function arguments would be too restrictive and fragile. + +To allow such arguments to be written without braces, a variant of the indentation scheme is implemented under language import +```scala +import language.experimental.fewerBraces +``` +This SIP proposes to make this variant the default, so no language import is needed to enable it. +In this variant, a `` token is also recognized where function argument would be expected. Examples: + +```scala +times(10): + println("ah") + println("ha") +``` + +or + +```scala +credentials `++`: + val file = Path.userHome / ".credentials" + if file.exists + then Seq(Credentials(file)) + else Seq() +``` + +or + +```scala +xs.map: + x => + val y = x - 1 + y * y +``` +What's more, a `:` in these settings can also be followed on the same line by the parameter part and arrow of a lambda. So the last example could be compressed to this: + +```scala +xs.map: x => + val y = x - 1 + y * y +``` +and the following would also be legal: +```scala +xs.foldLeft(0): (x, y) => + x + y +``` + +The grammar changes for this variant are as follows. + +``` +SimpleExpr ::= ... + | SimpleExpr ColonArgument +InfixExpr ::= ... + | InfixExpr id ColonArgument +ColonArgument ::= colon [LambdaStart] + indent (CaseClauses | Block) outdent +LambdaStart ::= FunParams (‘=>’ | ‘?=>’) + | HkTypeParamClause ‘=>’ +``` +## Compatibility + +The proposed solution changes the meaning of the following code fragments: +```scala + val x = y: + Int + + val y = (xs.map: (Int => Int) => + Int) +``` +In the first case, we have a type ascription where the type comes after the `:`. In the second case, we have +a type ascription in parentheses where the ascribing function type is split by a newline. Note that we have not found examples like this in the dotty codebase or in the community build. We verified this by compiling everything with success with `fewerBraces` enabled. So we conclude that incompatibilities like these would be very rare. +If there would be code using these idioms, it can be rewritten quite simply to avoid the problem. For instance, the following fragments would be legal (among many other possible variations): +```scala + val x = y + : Int + + val y = (xs.map: (Int => Int) + => Int) +``` + +## Other concerns + +### Tooling + +Since this affects parsing, the scalameta parser and any other parser used in an IDE will also need to be updated. The necessary changes to the Scala 3 parser were made here: https://github.com/scala/scala3/pull/15273/commits. The commit that embodies the core change set is here: https://github.com/scala/scala3/pull/15273/commits/421bdd660b0456c2ff1ae386f032c41bb1e0212a. + +### Handling Edge Cases + +The design intentionally does not allow `:` to be placed after an infix operator or after a previous indented argument. This is a consequence of the following clause in the spec above: + +> To this purpose we introduce a new `` token that reads as +the standard colon "`:`" but is generated instead of it where `` +is legal according to the context free syntax, but only if the previous token +is an alphanumeric identifier, a backticked identifier, or one of the tokens `this`, `super`, "`)`", and "`]`". + +This was done to prevent hard-to-decypher symbol salad as in the following cases: (1) +```scala +a < b || : // illegal + val x = f(c) + x > 0 +``` +or (2) +```scala +source --> : x => // illegal + val y = x * x + println(y) +``` +or (3) +```scala +xo.fold: + defaultValue +: // illegal + x => f(x) +``` +or (4) +```scala +xs.groupMapReduce: item => + key(item) +: item => // illegal + value(item) +: (value1, value2) => // illegal + reduce(value1, value2) +``` + +I argue that the language already provides mechanisms to express these examples without having to resort to braces. (Aside: I don't think that resorting to braces occasionally is a bad thing, but some people argue that it is, so it's good to have alternatives). Basically, we have three options + + - Use parentheses. + - Use an explicit `apply` method call. + - Use a `locally` call. + +Here is how the examples above can be rewritten so that they are legal but still don't use braces: + +For (1), use `locally`: +```scala +a < b || locally: + val x = f(c) + x > 0 +``` +For (2), use parentheses: +```scala +source --> ( x => + val y = x * x + println(y) +) +``` +For (3) and (4), use `apply`: +```scala +xo.fold: + defaultValue +.apply: + x => f(x) + +xs.groupMapReduce: item => + key(item) +.apply: item => + value(item) +.apply: (value1, value2) => + reduce(value1, value2) +``` +**Note 1:** I don't argue that this syntax is _more readable_ than braces, just that it is reasonable. The goal of this SIP is to have the nicer syntax for +all common cases and to not be atrocious for edge cases. I think this +goal is achieved by the presented design. + +**Note 2:** The Scala compiler should add a peephole optimization +that elides an eta expansion in front of `.apply`. E.g. the `fold` example should be compiled to the same code as `xs.fold(defaultValue)(x => f(x))`. + +**Note 3:** To avoid a runtime footprint, the `locally` method should be an inline method. We can achieve that by shadowing the stdlib, or else we can decide on a different name. `nested` or `block` have been proposed. In any case this could be done in a separate step. + +### Syntactic confusion with type ascription + +A frequently raised concern against using `:` as an indentation marker is that it is too close to type ascription and therefore might be confusing. + +However, I have seen no evidence so far that this is true in practice. Of course, one can make up examples that look ambiguous. But as outlined, the community build and the dotty code base do not contain a single case where +a type ascription is now accidentally interpreted as an argument. + +Also the fact that Python chose `:` for type ascription even though it was already used as an indentation marker should give us confidence. + +In well written future Scala code we can use visual keys that would tell us immediately which is which. Namely: + +> If the `:` or `=>` is at the end of a line, it's an argument, otherwise it's a type ascription. + +According to the current syntax, if you want a multi-line type ascription, you _cannot_ write +```scala +anExpr: + aType +``` +It _must be_ rewritten to +```scala +anExpr + : aType +``` +(But, as stated above, it seems nobody actually writes code like that). +Similarly, it is _recommended_ that you put `=>` in a multi-line function type at the start of lines instead of at the end. I.e. this code does not follow the guidelines (even though it is technically legal): +```scala +xs.map: ((x: Int) => + Int) +``` +You should reformat it like this: +```scala +val y = xs.map: ((x: Int) + => Int) +``` +If we propose these guidelines then the only problem that remains is that if one intentionally writes confusing layout _and_ one reads only superficially then things can be confusing. But that's really nothing out of the ordinary. + + +## Open questions + +None directly related to the SIP. As mentioned above we should decide eventually whether we should stick with `locally` or replace it by something else. But that is unrelated to the SIP proper and can be decided independently. + +## Alternatives + +I considered two variants: + +The first variant would allow lambda parameters without preceding colons. E.g. +```scala +xs.foldLeft(z)(a, b) => + a + b +``` +We concluded that this was visually less good since it looks too much like a function call `xs.foldLeft(z)(a, b)`. + +The second variant would always require `(...)` around function types in ascriptions (which is in fact what the official syntax requires). That would have completely eliminated the second ambiguity above since +```scala +val y = (xs.map: (Int => Int) => + Int) +``` +would then not be legal anyway. But it turned out that there were several community projects that were using function types in ascriptions without enclosing parentheses, so this change was deemed to break too much code. + +@sjrd proposed in a [feature request](https://github.com/lampepfl/dotty-feature-requests/issues/299) that the `:` could be left out when +followed by `case` on the next line. Example: +```scala + val xs = List((1, "hello"), (true, "bar"), (false, "foo")) + val ys = xs.collect // note: no ':' here + case (b: Boolean, s) if b => s + println(ys) +``` +This is a tradeoff between conciseness and consistency. In the interest of minimality, I would leave it out of the first version of the implementation. We can always add it later if we feel a need for it. + +## Related work + + - Doc page for proposed change: https://dotty.epfl.ch/docs/reference/other-new-features/indentation.html#variant-indentation-marker--for-arguments + + - Merged PR implementing the proposal under experimental flag: https://github.com/scala/scala3/pull/15273/commits/421bdd660b0456c2ff1ae386f032c41bb1e0212a + + - Latest discussion on contributors (there were several before when we discussed indentation in general): https://contributors.scala-lang.org/t/make-fewerbraces-available-outside-snapshot-releases/5024/166 + +## FAQ + diff --git a/_sips/sips/2012-01-21-futures-promises.md b/_sips/sips/futures-promises.md similarity index 97% rename from _sips/sips/2012-01-21-futures-promises.md rename to _sips/sips/futures-promises.md index a1b8d43666..26e067bfaa 100644 --- a/_sips/sips/2012-01-21-futures-promises.md +++ b/_sips/sips/futures-promises.md @@ -1,10 +1,8 @@ --- layout: sip -discourse: true title: SIP-14 - Futures and Promises - -vote-status: complete -vote-text: This SIP has already been accepted and completed. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/futures-promises.html --- @@ -109,7 +107,7 @@ We do so by calling the method `getRecentPosts` which returns a `List[String]`: f onComplete { case Right(posts) => for (post <- posts) render(post) - case Left(t) => render("An error has occured: " + t.getMessage) + case Left(t) => render("An error has occurred: " + t.getMessage) } The `onComplete` method is general in the sense that it allows the @@ -387,16 +385,16 @@ multiple `andThen` calls are ordered, as in the following example which stores the recent posts from a social network to a mutable set and then renders all the posts to the screen: - val allposts = mutable.Set[String]() + val allPosts = mutable.Set[String]() Future { session.getRecentPosts } andThen { - case Success(posts) => allposts ++= posts + case Success(posts) => allPosts ++= posts } andThen { case _ => clearAll() - for (post <- allposts) render(post) + for (post <- allPosts) render(post) } In summary, the combinators on futures are purely functional. @@ -716,19 +714,19 @@ Examples: ## References -1. [The Task-Based Asynchronous Pattern, Stephen Toub, Microsoft, April 2011][1] +1. [The Task-Based Asynchronous Pattern, Stephen Toub, Microsoft, February 2012][1] 2. [Finagle Documentation][2] 3. [Akka Documentation: Futures][3] 4. [Scala Actors Futures][4] 5. [Scalaz Futures][5] - [1]: http://www.microsoft.com/download/en/details.aspx?id=19957 "NETAsync" - [2]: http://twitter.github.com/scala_school/finagle.html "Finagle" + [1]: https://download.microsoft.com/download/5/B/9/5B924336-AA5D-4903-95A0-56C6336E32C9/TAP.docx "NETAsync" + [2]: https://twitter.github.io/scala_school/finagle.html "Finagle" [3]: https://doc.akka.io/docs/akka/current/futures.html "AkkaFutures" - [4]: http://www.scala-lang.org/api/2.9.3/scala/actors/Future.html "SActorsFutures" - [5]: http://code.google.com/p/scalaz/ "Scalaz" + [4]: https://web.archive.org/web/20140814211520/https://www.scala-lang.org/api/2.9.3/scala/actors/Future.html "SActorsFutures" + [5]: https://code.google.com/p/scalaz/ "Scalaz" ## Appendix A: API Traits -An implementation is available at [http://github.com/phaller/scala](https://github.com/phaller/scala/tree/execution-context/src/library/scala/concurrent). (Reasonably stable implementation, though possibility of flux.) +An implementation is available at [https://github.com/phaller/scala](https://github.com/phaller/scala/tree/execution-context/src/library/scala/concurrent). (Reasonably stable implementation, though possibility of flux.) diff --git a/_sips/sips/2011-10-12-implicit-classes.md b/_sips/sips/implicit-classes.md similarity index 92% rename from _sips/sips/2011-10-12-implicit-classes.md rename to _sips/sips/implicit-classes.md index e8757e4c72..495bcadf23 100644 --- a/_sips/sips/2011-10-12-implicit-classes.md +++ b/_sips/sips/implicit-classes.md @@ -1,10 +1,8 @@ --- layout: sip -discourse: true title: SIP-13 - Implicit classes - -vote-status: complete -vote-text: This SIP has already been accepted and completed. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/implicit-classes.html --- @@ -13,7 +11,7 @@ redirect_from: /sips/pending/implicit-classes.html This SIP is based on [this pre-draft](https://docs.google.com/document/d/1k-aGAGmbrDB-2pJ3uDPpHVKno6p-XbnkVHDc07zPrzQ/edit?hl=en_US). -Material adapted from [http://jorgeortiz85.github.com/ImplicitClassSIP.xhtml](http://jorgeortiz85.github.com/ImplicitClassSIP.xhtml) which is Copyright © 2009, Jorge Ortiz and David Hall +Material adapted from [https://jorgeortiz85.github.io/ImplicitClassSIP.xhtml](https://jorgeortiz85.github.io/ImplicitClassSIP.xhtml) which is Copyright © 2009, Jorge Ortiz and David Hall ## Abstract ## diff --git a/_sips/sips/implicit-macro-conversions.md b/_sips/sips/implicit-macro-conversions.md new file mode 100644 index 0000000000..82e7ab2ff5 --- /dev/null +++ b/_sips/sips/implicit-macro-conversions.md @@ -0,0 +1,7 @@ +--- +title: SIP-66 - Implicit macro conversions +status: under-review +pull-request-number: 86 +stage: design + +--- diff --git a/_sips/sips/implicit-source-locations.md b/_sips/sips/implicit-source-locations.md new file mode 100644 index 0000000000..a51a574f5d --- /dev/null +++ b/_sips/sips/implicit-source-locations.md @@ -0,0 +1,6 @@ +--- +title: SIP-19 - Implicit Source Locations +status: rejected +pull-request-number: 18 + +--- diff --git a/_sips/sips/improve-strictequality-feature-for-better-compatibility-with-existing-code-bases.md b/_sips/sips/improve-strictequality-feature-for-better-compatibility-with-existing-code-bases.md new file mode 100644 index 0000000000..29276bba12 --- /dev/null +++ b/_sips/sips/improve-strictequality-feature-for-better-compatibility-with-existing-code-bases.md @@ -0,0 +1,8 @@ +--- +title: SIP-67 - Improve strictEquality feature for better compatibility with existing + code bases +status: waiting-for-implementation +pull-request-number: 97 +stage: implementation + +--- diff --git a/_sips/sips/improved-lazy-vals-initialization.md b/_sips/sips/improved-lazy-vals-initialization.md new file mode 100644 index 0000000000..efb891962b --- /dev/null +++ b/_sips/sips/improved-lazy-vals-initialization.md @@ -0,0 +1,7 @@ +--- +title: SIP-20 - Improved Lazy Vals Initialization +status: shipped +pull-request-number: 19 +stage: completed + +--- diff --git a/_sips/sips/improving-binary-compatibility-with-stableabi.md b/_sips/sips/improving-binary-compatibility-with-stableabi.md new file mode 100644 index 0000000000..6e48e46553 --- /dev/null +++ b/_sips/sips/improving-binary-compatibility-with-stableabi.md @@ -0,0 +1,6 @@ +--- +title: SIP-34 - Improving binary compatibility with @stableABI +status: withdrawn +pull-request-number: 30 + +--- diff --git a/_sips/sips/inline-meta.md b/_sips/sips/inline-meta.md new file mode 100644 index 0000000000..c27ee3530a --- /dev/null +++ b/_sips/sips/inline-meta.md @@ -0,0 +1,6 @@ +--- +title: SIP-28 - Inline meta +status: withdrawn +pull-request-number: 28 + +--- diff --git a/_sips/sips/internals-of-scala-annotations.md b/_sips/sips/internals-of-scala-annotations.md new file mode 100644 index 0000000000..792f7ee8ee --- /dev/null +++ b/_sips/sips/internals-of-scala-annotations.md @@ -0,0 +1,10 @@ +--- +layout: sip +title: SID-5 - Internals of Scala Annotations +stage: completed +status: shipped +permalink: /sips/:title.html +redirect_from: /sips/pending/internals-of-scala-annotations.html +--- + +This was an older SID that can be found [here](https://www.scala-lang.org/sid/5) diff --git a/_sips/sips/2018-07-31-interpolation-quote-escape.md b/_sips/sips/interpolation-quote-escape.md similarity index 67% rename from _sips/sips/2018-07-31-interpolation-quote-escape.md rename to _sips/sips/interpolation-quote-escape.md index bd5658d618..6f0398ce33 100644 --- a/_sips/sips/2018-07-31-interpolation-quote-escape.md +++ b/_sips/sips/interpolation-quote-escape.md @@ -1,9 +1,14 @@ --- -layout: sips -discourse: true -title: SIP-NN - Quote escapes for interpolations +layout: sip +title: SIP-37 - Quote escapes for interpolations +stage: completed +status: shipped +permalink: /sips/:title.html +redirect_from: /sips/pending/interpolation-quote-escape.html --- +> This proposal has been implemented in Scala 2.13.6 and Scala 3.0.0. + **By: Martijn Hoekstra** ## History @@ -12,6 +17,7 @@ title: SIP-NN - Quote escapes for interpolations |---------------|-----------------------| | Jul 31th 2018 | Initial Draft | | Aug 1st 2018 | Process lead comments | +| Nov 2nd 2019 | Link dotty impl | ## Introduction @@ -21,7 +27,7 @@ rather passes the raw string to the interpolator, which then has the option to process escapes itself as it sees fit. That means there are no lexing rules that process the escape, and the sequence `\"` simply terminates the interpolation. -Interpolations have a different meta-charcter -- the `$` character -- which is +Interpolations have a different meta-character -- the `$` character -- which is treated specially. Interpolations use this escape to splice in arguments, and it can also be used to escape itself as the sequence `$$` to represent a literal `$` character. @@ -32,8 +38,8 @@ escape a `"` character to represent a literal `"` withing a string. ## Motivating Example That the `"` character can't be easily escaped in interpolations has been an -open issue since [at least 2012][1], and how to deal with this issue is a -[somewhat common][2] [SO question][3] +open issue since at least 2012[^1], and how to deal with this issue is a +somewhat common SO question[^2][^3] {% highlight Scala %} s"A common question for Scala programmers is "How can I represent a literal " character in Scala interpolations?"" @@ -84,15 +90,17 @@ interpolator. ## Design This is a non-breaking change. Currently the sequence `$"` within an -interpolation is a syntax error, as [has already been noted][4] -on the original ticket +interpolation is a syntax error, as has already been noted[^4] +on the original ticket. ## Implementation The implementation is simple to the point of being trivial: see -[the implementation][5] for the actual change in functonality and the rest of +the implementation [^5] for the actual change in functionality and the rest of that PR for the spec and test changes. +There is also an implementation for Dotty.[^7] + ## Drawbacks Adding this feature makes the language just a bit more irregular. There already @@ -101,13 +109,13 @@ the language. An argument could be made that this change makes that worse rather than better. Because it affects parsing, this change may affect syntax highlighters. Syntax -highlighters tend to already stuggle around "funky" strings and interpolations. +highlighters tend to already struggle around "funky" strings and interpolations. ## Alternatives More ambitious proposals around interpolations are possible, and have been -propsed in different forms before. [This PR][6] in particular shows more options -around using `\` as a meta character in interpolations. It stranded somewhere +proposed in different forms before. For example, there was a PR thatshows more options +around using `\` as a meta character in interpolations[^6]. It stranded somewhere between red tape, ambition and changing processes. I suspect the last word about interpolations hasn't been spoken, and that later @@ -115,9 +123,10 @@ proposals may still make interpolations more regular. This proposal is deliberately small, and intends not to be in the way of any potential further proposals. -[1]: https://github.com/Scala/bug/issues/6476 "\\\" escape does not work with string interpolation" -[2]: https://stackoverflow.com/questions/31366563/string-interpolation-escaping-quotation-mark/31366588 "" -[3]: https://stackoverflow.com/questions/17085354/escaping-quotation-marks-in-f-string-interpolation "" -[4]: https://github.com/scala/bug/issues/6476#issuecomment-292412577 "@retronym said: +1 to s"$"". Because it doesn't compile today, we don't risk changing the meaning of existing programs." -[5]: https://github.com/Scala/Scala/pull/6953/files#diff-0023b3bfa053fb16603156b785efa7ad "" -[6]: https://github.com/Scala/Scala/pull/4308 "SI-6476 Accept escaped quotes in interp strings" +[^1]: https://github.com/Scala/bug/issues/6476 "\\\" escape does not work with string interpolation" +[^2]: https://stackoverflow.com/questions/31366563/string-interpolation-escaping-quotation-mark/31366588 "" +[^3]: https://stackoverflow.com/questions/17085354/escaping-quotation-marks-in-f-string-interpolation "" +[^4]: https://github.com/scala/bug/issues/6476#issuecomment-292412577 "@retronym said: +1 to s"$"". Because it doesn't compile today, we don't risk changing the meaning of existing programs." +[^5]: https://github.com/Scala/Scala/pull/6953/files#diff-0023b3bfa053fb16603156b785efa7ad "" +[^6]: https://github.com/Scala/Scala/pull/4308 "SI-6476 Accept escaped quotes in interp strings" +[^7]: https://github.com/scala/scala3/pull/7486 "PR in dotty" diff --git a/_sips/sips/match-types-spec.md b/_sips/sips/match-types-spec.md new file mode 100644 index 0000000000..049fad9415 --- /dev/null +++ b/_sips/sips/match-types-spec.md @@ -0,0 +1,590 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: completed +status: shipped +title: SIP-56 - Proper Specification for Match Types +--- + +**By: Sébastien Doeraene** + +## History + +| Date | Version | +|---------------|--------------------| +| Aug 11th 2023 | Initial Draft | + +## Summary + +Currently, match type reduction is not specified, and its implementation is by nature not specifiable. +This is an issue because match type reduction spans across TASTy files (unlike, for example, type inference or GADTs), which can and will lead to old TASTy files not to be linked again in future versions of the compiler. + +This SIP proposes a proper specification for match types, which does not involve type inference. +It is based on `baseType` computations and subtype tests involving only fully-defined types. +That is future-proof, because `baseType` and subtyping are defined in the specification of the language. + +The proposed specification defines a subset of current match types that are considered legal. +Legal match types use the new, specified reduction rules. +Illegal match types are rejected, which is a breaking change, and can be recovered under `-source:3.3`. + +In addition, the proposal gives a specification for `provablyDisjoint` and for the reduction algorithm. + +## Motivation + +Currently, match type reduction is implementation-defined. +The core of the logic is matching a scrutinee type `X` against a pattern `P` with captures `ts`. +Captures are similar to captures in term-level pattern matching: in the type-level `case List[t] =>`, `t` is a (type) capture, just like in the term-level `case List(x) =>`, `x` is a (term) capture. +Matching works as follows: + +1. we create new type variables for the captures `ts'` giving a pattern `P'`, +2. we ask the compiler's `TypeComparer` (the type inference black box) to "try and make it so" that `X <:< P'`, +3. if it manages to do so, we get constraints for `ts'`; we then have a match, and we instantiate the body of the pattern with the received constraints for `ts`. + +The problem with this approach is that, by essence, type inference is an unspecified black box. +There are *guidelines* about how it should behave in common cases, but no actual guarantee. +This is fine everywhere else in the language, because what type inference comes up with is stored once and for all in TASTy. +When we read TASTy files, we do not have to perform the work of type inference again; we reuse what was already computed. +When a new version of the compiler changes type inference, it does not change what was computed and stored in TASTy files by previous versions of the compiler. + +For match types, this is a problem, because reduction spans across TASTy files. +Given some match type `type M[X] = X match { ... }`, two codebases may refer to `M[SomeType]`, and they must reduce it in the same way. +If they don't, hard incompatibilities can appear, such as broken subtyping, broken overriding relationships, or `AbstractMethodError`s due to inconsistent erasure. + +In order to guarantee compatibility, we must ensure that, for any given match type: + +* if it reduces in a given way in version 1 of the compiler, it still reduces in the same way in version 2, and +* if it does not reduce in version 1 of the compiler, it still does not reduce in version 2. +* (it is possible for version 1 to produce an *error* while version 2 successfully reduces or does not reduce) + +Reduction depends on two decision produces: + +* *matching* a scrutinee `X` against a pattern `P` (which we mentioned above), and +* deciding whether a scrutinee `X` is *provably disjoint* from a pattern `P`. + +When a scrutinee does not match a given pattern and cannot be proven disjoint from it either, the match type is "stuck" and does not reduce. + +If matching is delegated to the `TypeComparer` black box, then it is impossible in practice to guarantee the first compatibility property. + +In addition to the compatibility properties above, there is also a soundness property that we need to uphold: + +* if `X match { ... }` reduces to `R` and `Y <: X`, then `Y match { ... }` also reduces to `R`. + +This requires both that *matching* with a tighter scrutinee gives the same result, and that `provablyDisjoint(X, P)` implies `provablyDisjoint(Y, P)`. +(Those properties must be relaxed when `Y <: Nothing`, in order not to create more problems; see Olivier Blanvillain's thesis section 4.4.2 for details.) +With the existing implementation for `provablyDisjoint`, there are reasonable, non-contrived examples that violate this property. + +In order to solve these problems, this SIP provides a specification for match type reduction that is independent of the `TypeComparer` black box. +It defines a subset of match type cases that are considered legal. +Legal cases get a specification for when and how they should reduce for any scrutinee. +Illegal cases are rejected as being outside of the language. + +For compatibility reasons, such now-illegal cases will still be accepted under `-source:3.3`; in that case, they reduce using the existing, unspecified (and prone to breakage) implementation. +Due to practical reasons (see "Other concerns"), doing so does *not* emit any warning. +Eventually, support for this fallback may be removed if the compiler team decides that its maintenance burden is too high. +As usual, this SIP does not by itself provide any specific timeline. +In particular, there is no relationship with 3.3 being an "LTS"; it just happens to be the latest "Next" as well at the time of this writing (the changes in this SIP will only ever apply to 3.4 onwards, so the LTS is not affected in any way). + +For legal cases, the proposed reduction specification should reduce in the same way as the current implementation for all but the most obscure cases. +Our tests, including the entire dotty CI and its community build, did not surface any such incompatibility. +It is however not possible to guarantee that property for *all* cases, since the existing implementation is not specified in the first place. + +## Proposed solution + +### Specification + +#### Preamble + +Some of the concepts mentioned here are defined in the existing Scala 3 specification draft. +That draft can be found in the dotty repository at https://github.com/scala/scala3/tree/main/docs/_spec. +It is not rendered anywhere yet, though. + +Here are some of the relevant concepts that are perhaps lesser-known: + +* Chapter 3, section "Internal types": concrete v abstract syntax of types. +* Chapter 3, section "Base Type": the `baseType` function. +* Chapter 3, section "Definitions": whether a type is concrete or abstract (unrelated to the concrete or abstract *syntax*). + +#### Syntax + +Syntactically, nothing changes. +The way that a pattern is parsed and type captures identified is kept as is. + +Once type captures are identified, we can represent the *abstract* syntax of a pattern as follows: + +``` +// Top-level pattern +MatchTypePattern ::= TypeWithoutCapture + | MatchTypeAppliedPattern + +// A type that does not contain any capture, such as `Int` or `List[String]` +TypeWithoutCapture ::= Type // `Type` is from the "Internal types" section of the spec + +// Applied type pattern with at least one capture, such as `List[Seq[t]]` or `*:[Int, t]` +MatchTypeAppliedPattern ::= TyconWithoutCapture ‘[‘ MatchTypeSubPattern { ‘,‘ MatchTypeSubPattern } ‘]‘ + +// The type constructor of a MatchTypeAppliedPattern never contains any captures +TyconWithoutCapture ::= Type + +// Type arguments can be captures, types without captures, or nested applied patterns +MatchTypeSubPattern ::= TypeCapture + | TypeWithoutCapture + | MatchTypeAppliedPattern + +TypeCapture ::= NamedTypeCapture // e.g., `t` + | WildcardTypeCapture // `_` (with inferred bounds) +``` + +In the concrete syntax, `MatchTypeAppliedPattern`s can take the form of `InfixType`s. +A common example is `case h *: t =>`, which is desugared into `case *:[h, t] =>`. + +The cases `MatchTypeAppliedPattern` are only chosen if they contain at least one `TypeCapture`. +Otherwise, they are considered `TypeWithoutCapture` instead. +Each named capture appears exactly once. + +#### Legal patterns + +A `MatchTypePattern` is legal if and only if one of the following is true: + +* It is a `TypeWithoutCapture`, or +* It is a `MatchTypeAppliedPattern` with a legal `TyconWithoutCapture` and each of its arguments is either: + * A `TypeCapture`, or + * A `TypeWithoutCapture`, or + * The type constructor is *covariant* in that parameter, and the argument is recursively a legal `MatchTypeAppliedPattern`. + +A `TyconWithoutCapture` is legal if one of the following is true: + +* It is a *class* type constructor, or +* It is the `scala.compiletime.ops.int.S` type constructor, or +* It is an *abstract* type constructor, or +* It is a refined type of the form `Base { type Y = t }` where: + * `Base` is a `TypeWithoutCapture`, + * There exists a type member `Y` in `Base`, and + * `t` is a `TypeCapture`. +* It is a type alias to a type lambda such that: + * Its bounds contain all possible values of its arguments, and + * When applied to the type arguments, it beta-reduces to a new legal `MatchTypeAppliedPattern` that contains exactly one instance of every type capture present in the type arguments. + +#### Examples of legal patterns + +Given the following definitions: + +```scala +class Inv[A] +class Cov[+A] +class Contra[-A] + +class Base { + type Y +} + +type YExtractor[t] = Base { type Y = t } +type ZExtractor[t] = Base { type Z = t } + +type IsSeq[t <: Seq[Any]] = t +``` + +Here are examples of legal patterns: + +```scala +// TypeWithoutCapture's +case Any => // also the desugaring of `case _ =>` when the _ is at the top-level +case Int => +case List[Int] => +case Array[String] => + +// Class type constructors with direct captures +case scala.collection.immutable.List[t] => // not Predef.List; it is a type alias +case Array[t] => +case Contra[t] => +case Either[s, t] => +case Either[s, Contra[Int]] => +case h *: t => +case Int *: t => + +// The S type constructor +case S[n] => + +// An abstract type constructor +// given a [F[_]] or `type F[_] >: L <: H` in scope +case F[t] => + +// Nested captures in covariant position +case Cov[Inv[t]] => +case Cov[Cov[t]] => +case Cov[Contra[t]] => +case Array[h] *: t => // sugar for *:[Array[h], t] +case g *: h *: EmptyTuple => + +// Type aliases +case List[t] => // which is Predef.List, itself defined as `type List[+A] = scala.collection.immutable.List[A]` + +// Refinements (through a type alias) +case YExtractor[t] => +``` + +The following patterns are *not* legal: + +```scala +// Type capture nested two levels below a non-covariant type constructor +case Inv[Cov[t]] => +case Inv[Inv[t]] => +case Contra[Cov[t]] => + +// Type constructor with bounds that do not contain all possible instantiations +case IsSeq[t] => + +// Type refinement where the refined type member is not a member of the parent +case ZExtractor[t] => +``` + +#### Matching + +Given a scrutinee `X` and a match type case `case P => R` with type captures `ts`, matching proceeds in three steps: + +1. Compute instantiations for the type captures `ts'`, and check that they are *specific* enough. +2. If successful, check that `X <:< [ts := ts']P`. +3. If successful, reduce to `[ts := ts']R`. + +The instantiations are computed by the recursive function `matchPattern(X, P, variance, scrutIsWidenedAbstract)`. +At the top level, `variance = 1` and `scrutIsWidenedAbstract = false`. + +`matchPattern` behaves according to what kind is `P`: + +* If `P` is a `TypeWithoutCapture`: + * Do nothing (always succeed). +* If `P` is a `WildcardCapture` `ti = _`: + * Instantiate `ti` so that the subtype test in Step (2) above always succeeds: + * If `X` is of the form `_ >: L <: H`, instantiate `ti := H` (resp. `L`, `X`) if `variance = 1` (resp. `-1`, `0`). + * Otherwise, instantiate `ti := X`. +* If `P` is a `TypeCapture` `ti`: + * If `X` is of the form `_ >: L <: H`, + * If `scrutIsWidenedAbstract` is `true`, fail as not specific. + * Otherwise, if `variance = 1`, instantiate `ti := H`. + * Otherwise, if `variance = -1`, instantiate `ti := L`. + * Otherwise, fail as not specific. + * Otherwise, if `variance = 0` or `scrutIsWidenedAbstract` is `false`, instantiate `ti := X`. + * Otherwise, fail as not specific. +* If `P` is a `MatchTypeAppliedPattern` of the form `T[Qs]`: + * Assert: `variance = 1` (from the definition of legal patterns). + * If `T` is a class type constructor of the form `p.C`: + * If `baseType(X, C)` is not defined, fail as not matching. + * Otherwise, it is of the form `q.C[Us]`. + * If `p =:= q` is false, fail as not matching. + * Let `innerScrutIsWidenedAbstract` be true if either `scrutIsWidenedAbstract` or `X` is not a concrete type. + * For each pair of `(Ui, Qi)`, compute `matchPattern(Ui, Qi, vi, innerScrutIsWidenedAbstract)` where `vi` is the variance of the `i`th type parameter of `T`. + * If `T` is `scala.compiletime.ops.int.S`: + * If `n = natValue(X)` is undefined or `n <= 0`, fail as not matching. + * Otherwise, compute `matchPattern(n - 1, Q1, 1, scrutIsWidenedAbstract)`. + * If `T` is an abstract type constructor: + * If `X` is not of the form `F[Us]` or `F =:= T` is false, fail as not matching. + * Otherwise, for each pair of `(Ui, Qi)`, compute `matchPattern(Ui, Qi, vi, scrutIsWidenedAbstract)` where `vi` is the variance of the `i`th type parameter of `T`. + * If `T` is a refined type of the form `Base { type Y = ti }`: + * Let `q` be `X` if `X` is a stable type, or the skolem type `∃α:X` otherwise. + * If `q` does not have a type member `Y`, fail as not matching (that implies that `X <:< Base` is false, because `Base` must have a type member `Y` for the pattern to be legal). + * If `q.Y` is abstract, fail as not specific. + * If `q.Y` is a class member: + * If `q` is a skolem type `∃α:X`, fail as not specific. + * Otherwise, compute `matchPattern(ti, q.Y, 0, scrutIsWidenedAbstract)`. + * Otherwise, the underlying type definition of `q.Y` is of the form `= U`: + * If `q` is not a skolem type `∃α:X`, compute `matchPattern(ti, U, 0, scrutIsWidenedAbstract)`. + * Otherwise, let `U' = dropSkolem(U)` be computed as follow: + * `dropSkolem(q)` is undefined. + * `dropSkolem(p.T) = p'.T` where `p' = dropSkolem(p)` if the latter is defined. Otherwise: + * If the underlying type of `p.T` is of the form `= V`, then `dropSkolem(V)`. + * Otherwise `dropSkolem(p.T)` is undefined. + * `dropSkolem(p.x) = p'.x` where `p' = dropSkolem(p)` if the latter is defined. Otherwise: + * If the dealiased underlying type of `p.x` is a singleton type `r.y`, then `dropSkolem(r.y)`. + * Otherwise `dropSkolem(p.x)` is undefined. + * For all other types `Y`, `dropSkolem(Y)` is the type formed by replacing each component `Z` of `Y` by `dropSkolem(Z)`. + * If `U'` is undefined, fail as not specific. + * Otherwise, compute `matchPattern(ti, U', 0, scrutIsWidenedAbstract)`. + * If `T` is a concrete type alias to a type lambda: + * Let `P'` be the beta-reduction of `P`. + * Compute `matchPattern(P', X, variance, scrutIsWidenedAbstract)`. + +#### Disjointness + +This proposal initially did not include a discussion of disjointness. +After initial review, it became apparent that it should also provide a specification for the "provably disjoint" test involved in match type reduction. +Additional study revealed that, while *specifiable*, the current algorithm is very ad hoc and severely lacks desirable properties such as preservation along subtyping (see towards the end of this section). + +Therefore, this proposal now also includes a proposed specification for "provably disjoint". +To the best of our knowledge, it is strictly stronger than what is currently implemented, with one exception. + +The current implementation considers that `{ type A = Int }` is provably disjoint from `{ type A = Boolean }`. +However, it is not able to prove disjointness between any of the following: + +* `{ type A = Int }` and `{ type A = Boolean; type B = String }` (adding another type member) +* `{ type A = Int; type B = Int }` and `{ type B = String; type A = String }` (switching the order of type members) +* `{ type A = Int }` and class `C` that defines a member `type A = String`. + +Therefore, we drop the very ad hoc case of one-to-one type member refinements. + +On to the specification. + +A scrutinee `X` is *provably disjoint* from a pattern `P` iff it is provably disjoint from the type `P'` obtained by replacing every type capture in `P` by a wildcard type argument with the same bounds. + +We note `X ⋔ Y` to say that `X` and `Y` are provably disjoint. +Intuitively, that notion is based on the following properties of the Scala language: + +* Single inheritance of classes +* Final classes cannot be extended +* Sealed traits have a known set of direct children +* Constant types with distinct values are nonintersecting +* Singleton paths to distinct `enum` case values are nonintersecting + +However, a precise definition of provably-disjoint is complicated and requires some helpers. +We start with the notion of "simple types", which are a minimal subset of Scala types that capture the concepts mentioned above. + +A "simple type" is one of: + +* `Nothing` +* `AnyKind` +* `p.C[...Xi]` a possibly parameterized class type, where `p` and `...Xi` are arbitrary types (not just simple types) +* `c` a literal type +* `p.C.x` where `C` is an `enum` class and `x` is one of its value `case`s +* `X₁ & X₂` where `X₁` and `X₂` are both simple types +* `X₁ | X₂` where `X₁` and `X₂` are both simple types +* `[...ai] =>> X₁` where `X₁` is a simple type + +We define `⌈X⌉` a function from a full Scala type to a simple type. +Intuitively, it returns the "smallest" simple type that is a supertype of `X`. +It is defined as follows: + +* `⌈X⌉ = X` if `X` is a simple type +* `⌈X⌉ = ⌈U⌉` if `X` is a stable type but not a simple type and its underlying type is `U` +* `⌈X⌉ = ⌈H⌉` if `X` is a non-class type designator with upper bound `H` +* `⌈X⌉ = ⌈η(X)⌉` if `X` is a polymorphic class type designator, where `η(X)` is its eta-expansion +* `⌈X⌉ = ⌈Y⌉` if `X` is a match type that reduces to `Y` +* `⌈X⌉ = ⌈H⌉` if `X` is a match type that does not reduce and `H` is its upper bound +* `⌈X[...Ti]⌉ = ⌈Y⌉` where `Y` is the beta-reduction of `X[...Ti]` if `X` is a type lambda +* `⌈X[...Ti]⌉ = ⌈⌈X⌉[...Ti⌉` if `X` is neither a type lambda nor a class type designator +* `⌈X @a⌉ = ⌈X⌉` +* `⌈X { R }⌉ = ⌈X⌉` +* `⌈{ α => X } = ⌈X⌉⌉` +* `⌈X₁ & X₂⌉ = ⌈X₁⌉ & ⌈X₂⌉` +* `⌈X₁ | X₂⌉ = ⌈X₁⌉ | ⌈X₂⌉` +* `⌈[...ai] =>> X₁⌉ = [...ai] =>> ⌈X₁⌉` + +The following properties hold about `⌈X⌉` (we have paper proofs for those): + +* `X <: ⌈X⌉` for all type `X`. +* If `S <: T`, and the subtyping derivation does not use the "lower-bound rule" of `<:` anywhere, then `⌈S⌉ <: ⌈T⌉`. + +The "lower-bound rule" states that `S <: T` if `T = q.X `and `q.X` is a non-class type designator and `S <: L` where `L` is the lower bound of the underlying type definition of `q.X`". +That rule is known to break transitivy of subtyping in Scala already. + +Second, we define the relation `⋔` on *classes* (including traits and hidden classes of objects) as: + +* `C ⋔ D` if `C ∉ baseClasses(D)` and `D` is `final` +* `C ⋔ D` if `D ∉ baseClasses(C)` and `C` is `final` +* `C ⋔ D` if there exists `class`es `C' ∈ baseClasses(C)` and `D' ∈ baseClasses(D)` such that `C' ∉ baseClasses(D')` and `D' ∉ baseClasses(C')`. +* `C ⋔ D` if `C` is `sealed` without anonymous child and `Ci ⋔ D` for all direct children `Ci` of `C` +* `C ⋔ D` if `D` is `sealed` without anonymous child and `C ⋔ Di` for all direct children `Di` of `D` + +We can now define `⋔` for *types*. + +For arbitrary types `X` and `Y`, we define `X ⋔ Y` as `⌈X⌉ ⋔ ⌈Y⌉`. + +Two simple types `S` and `T` are provably disjoint if there is a finite derivation tree for `S ⋔ T` using the following rules. +Most rules go by pair, which makes the whole relation symmetric: + +* `Nothing` is disjoint from everything (including itself): + * `Nothing ⋔ T` + * `S ⋔ Nothing` +* A union type is disjoint from another type if both of its parts are disjoint from that type: + * `S ⋔ T1 | T2` if `S ⋔ T1` and `S ⋔ T2` + * `S1 | S2 ⋔ T` if `S1 ⋔ T` and `S2 ⋔ T` +* An intersection type is disjoint from another type if at least one of its parts is disjoint from that type: + * `S ⋔ T1 & T2` if `S ⋔ T1` or `S ⋔ T2` + * `S1 & S2 ⋔ T` if `S1 ⋔ T` or `S1 ⋔ T` +* A type lambda is disjoint from any other type that is not a type lambda with the same number of parameters: + * `[...ai] =>> S1 ⋔ q.D.y` + * `[...ai] =>> S1 ⋔ d` + * `[...ai] =>> S1 ⋔ q.D[...Ti]` + * `p.C.x ⋔ [...bi] =>> T1` + * `c ⋔ [...bi] =>> T1` + * `p.C[...Si] ⋔ [...bi] =>> T1` + * `[a1, ..., an] =>> S1 ⋔ [b1, ..., bm] =>> T1` if `m != n` +* Two type lambdas with the same number of type parameters are disjoint if their result types are disjoint: + * `[a1, ..., an] =>> S1 ⋔ [b1, ..., bn] =>> T1` if `S1 ⋔ T1` +* An `enum` value case is disjoint from any other `enum` value case (identified by either not being in the same `enum` class, or having a different name): + * `p.C.x ⋔ q.D.y` if `C != D` or `x != y` +* Two literal types are disjoint if they are different: + * `c ⋔ d` if `c != d` +* An `enum` value case is always disjoint from a literal type: + * `c ⋔ q.D.y` + * `p.C.x ⋔ d` +* An `enum` value case or a constant is disjoint from a class type if it does not extend that class (because it's essentially final): + * `p.C.x ⋔ q.D[...Ti]` if `baseType(p.C.x, D)` is not defined + * `p.C[...Si] ⋔ q.D.y` if `baseType(q.D.y, C)` is not defined + * `c ⋔ q.D[...Ti]` if `baseType(c, D)` is not defined + * `p.C[...Si] ⋔ d` if `baseType(d, C)` is not defined +* Two class types are disjoint if the classes themselves are disjoint, or if there exist a common super type with conflicting type arguments. + * `p.C[...Si] ⋔ q.D[...Ti]` if `C ⋔ D` + * `p.C[...Si] ⋔ q.D[...Ti]` if there exists a class `E` such that `baseType(p.C[...Si], E) = a.E[...Ai]` and `baseType(q.D[...Ti], E) = b.E[...Bi]` and there exists a pair `(Ai, Bi)` such that + * `Ai ⋔ Bi` and it is in invariant position, or + * `Ai ⋔ Bi` and it is in covariant position and there exists a field of that type parameter in `E` + +It is worth noting that this definition disregards prefixes entirely. +`p.C` and `q.C` are never provably disjoint, even if `p` could be proven disjoint from `q`. +It also disregards type members. + +We have a proof sketch of the following property for `⋔`: + +* If `S <: T` and `T ⋔ U`, then `S ⋔ U`. + +This is a very desirable property, which does not hold at all for the current implementation of match types. +It means that if we make the scrutinee of a match type more precise (a subtype) through substitution, and the match type previously reduced, then the match type will still reduce to the same case. + +Note: if `⋔` were a "true" disjointness relationship, and not a *provably*-disjoint relationship, that property would trivially hold based on elementary set theoretic properties. +It would amount to proving that if `S ⊆ T` and `T ⋂ U = ∅`, then `S ⋂ U = ∅`. + +#### Reduction + +The final piece of the match types puzzle is to define the reduction as a whole. + +In addition to matching and `provablyDisjoint`, the existing algorithm relies on a `provablyEmpty` property for a single type. +It was added a safeguard against matching an empty (`Nothing`) scrutinee. +The problem with doing so is that an empty scrutinee will be considered *both* as matching the pattern *and* as provably disjoint from the pattern. +This can result in the match type reducing to different cases depending on the context. +To sidestep this issue, the current algorithm refuses to consider a scrutinee that is `provablyEmpty`. + +If we wanted to keep that strategy, we would also have to specify `provablyEmpty` and prove some properties about it. +Instead, we choose a much simpler and safer strategy: we always test both matching *and* `provablyDisjoint`. +When both apply, we deduce that the scrutinee is empty is refuse to reduce the match type. + +Therefore, in summary, the whole reduction algorithm works as follows. +The result of reducing `X match { case P1 => R1; ...; case Pn => Rn }` can be a type, undefined, or a compile error. +For `n >= 1`, it is specified as: + +* If `X` matches `P1` with type capture instantiations `[...ts => ts']`: + * If `X ⋔ P1`, do not reduce. + * Otherwise, reduce as `[...ts => ts']R1`. +* Otherwise, + * If `X ⋔ P1`, the result of reducing `X match { case P2 => R2; ...; case Pn => Rn }` (i.e., proceed with subsequent cases). + * Otherwise, do not reduce. + +The reduction of an "empty" match type `X match { }` (which cannot be written in user programs) is a compile error. + +#### Subtyping + +As is already the case in the existing system, match types tie into subtyping as follows: + +* `X match { ... } <: T` if `X match { ... }` reduces to `S1` and `S1 <: T` +* `S <: X match { ... }` if `X match { ... }` reduces to `T1` and `S <: T1` +* `X match { ... } <: T` if `X match { ... }` has the upper bound `H` and `H <: T` +* `X match { case P1 => A1; ...; case Pn => An } <: Y match { case Q1 => B1; ...; Qn => Bn }` if `X =:= Y` and `Pi =:= Qi` for each `i` and `Ai <: Bi` for each `i` + +### Compatibility + +Compatibility is inherently tricky to evaluate for this proposal, and even to define. +One could argue that, from a pure specification point of view, it breaks nothing since it only specifies things that were unspecified before. +However, that is not very practical. +In practice, this proposal definitely breaks some code that compiled before, due to making some patterns illegal. +In exchange, it promises that all the patterns that are considered legal will keep working in the future; which is not the case with the current implementation, even for the legal subset. + +In order to evaluate the practical impact of this proposal, we conducted a quantitative analysis of *all* the match types found in Scala 3 libraries published on Maven Central. +We used [Scaladex](https://index.scala-lang.org/) to list all Scala 3 libraries, [coursier](https://get-coursier.io/docs/api) to resolve their classpaths, and [tasty-query](https://github.com/scalacenter/tasty-query) to semantically analyze the patterns of all the match types they contain. + +Out of 4,783 libraries, 49 contained at least one match type definition. +These 49 libraries contained a total of 779 match type `case`s. +Of those, there were 8 `case`s that would be flagged as not legal by the current proposal. + +These can be categorized as follows: + +* 2 libraries with 1 type member extractor each where the `Base` does not contain `Y`; they are both to extract `SomeEnumClass#Value` (from Scala 2 `scala.Enumeration`-based "enums"). + * https://github.com/iheartradio/ficus/blob/dcf39d6cd2dcde49b093ba5d1507ca478ec28dac/src/main/scala-3/net/ceedubs/ficus/util/EnumerationUtil.scala#L4-L8 + * https://github.com/json4s/json4s/blob/5e0b92a0ca59769f3130e081d0f53089a4785130/ext/src/main/scala-3/org/json4s/ext/package.scala#L4-L8 + * the maintainers of `json4s` already accepted a PR with a workaround at https://github.com/json4s/json4s/pull/1347 +* 1 library used to have 2 cases of the form `case HKExtractor[f] =>` with `type KHExtractor[f[_, _]] = Base { type Y[a, b] = f[a, b] }`. + * Those used to be at https://github.com/7mind/idealingua-v1/blob/48d35d53ce1c517f9f0d5341871e48749644c105/idealingua-v1/idealingua-v1-runtime-rpc-http4s/src/main/scala-3/izumi/idealingua/runtime/rpc/http4s/package.scala#L10-L15 but they do not exist in the latest version of the library. +* 1 library used to have 1 `&`-type extractor (which "worked" who knows how?): + https://github.com/Katrix/perspective/blob/f1643ac7a4e6a0d8b43546bf7b9e6219cc680dde/dotty/derivation/src/main/scala/perspective/derivation/Helpers.scala#L15-L18 + but the author already accepted a change with a workaround at + https://github.com/Katrix/perspective/pull/1 +* 1 library has 3 occurrences of using an abstract type constructor too "concretely": + https://github.com/kory33/s2mc-test/blob/d27c6e85ad292f8a96d7d51af7ddc87518915149/protocol-core/src/main/scala/io/github/kory33/s2mctest/core/generic/compiletime/Tuple.scala#L16 + defined at https://github.com/kory33/s2mc-test/blob/d27c6e85ad292f8a96d7d51af7ddc87518915149/protocol-core/src/main/scala/io/github/kory33/s2mctest/core/generic/compiletime/Generic.scala#L12 + It could be replaced by a concrete `class Lock[A](phantom: A)` instead. + +All the existing use cases therefore have either already disappeared or have a workaround. + +### Other concerns + +Ideally, this proposal would be first implemented as *warnings* about illegal cases, and only later made errors. +Unfortunately, the presence of the abstract type constructor case makes that impossible. +Indeed, because of it, a pattern that is legal at definition site may become illegal after some later substitution. + +Consider for example the standard library's very own `Tuple.InverseMap`: + +```scala +/** Converts a tuple `(F[T1], ..., F[Tn])` to `(T1, ... Tn)` */ +type InverseMap[X <: Tuple, F[_]] <: Tuple = X match { + case F[x] *: t => x *: InverseMap[t, F] + case EmptyTuple => EmptyTuple +} +``` + +If we instantiate `InverseMap` with a class type parameter, such as `InverseMap[X, List]`, the first case gets instantiated to +```scala +case List[x] *: t => x *: InverseMap[t, List] +``` +which is legal. + +However, nothing prevents us a priori to instantiate `InverseMap` with an illegal type constructor, for example +```scala +type IsSeq[t <: Seq[Any]] = t +InverseMap[X, IsSeq] +``` +which gives +```scala +case IsSeq[x] *: t => x *: InverseMap[t, IsSeq] +``` + +These instantiatiations happen deep inside the type checker, during type computations. +Since types are cached, shared and reused in several parts of the program, by construction, we do not have any source code position information at that point. +That means that we cannot report *warnings*. + +We can in fact report *errors* by reducing to a so-called `ErrorType`, which is aggressively propagated. +This is what we do in the proposed implementation (unless using `-source:3.3`). + +### Open questions + +None at this point. + +## Alternatives + +The specification is more complicated than we initially wanted. +At the beginning, we were hoping that we could restrict match cases to class type constructors only. +The quantitative study however revealed that we had to introduce support for abstract type constructors and for type member extractors. + +As already mentioned, the standard library itself contains an occurrence of an abstract type constructor in a pattern. +If we made that an error, we would have a breaking change to the standard library itself. +Some existing libraries would not be able to retypecheck again. +Worse, it might not be possible for them to change their code in a way that preserves their own public APIs. + +We tried to restrict abstract type constructors to never match on their own. +Instead, we wanted them to stay "stuck" until they could be instantiated to a concrete type constructor. +However, that led some existing tests to fail even for match types that were declared legal, because they did not reduce anymore in some places where they reduced before. + +Type member extractors are our biggest pain point. +Their specification is complicated, and the implementation as well. +Our quantitative study showed that they were however used at least somewhat often (10 occurrences spread over 4 libraries). +In each case, they seem to be a way to express what Scala 2 type projections (`A#T`) could express. +While not quite as powerful as type projections (which were shown to be unsound), match types with type member extractors delay things enough for actual use cases to be meaningful. + +As far as we know, those use cases have no workaround if we make type member extractors illegal. + +## Related work + +Notable prior work related to this proposal includes: + +- [Current reference page for Scala 3 match types](https://dotty.epfl.ch/docs/reference/new-types/match-types.html) +- [Abstractions for Type-Level Programming](https://infoscience.epfl.ch/record/294024), Olivier Blanvillain, Chapter 4 (Match Types) +- ["Pre-Sip" discussion in the Contributors forum](https://contributors.scala-lang.org/t/pre-sip-proper-specification-for-match-types/6265) (submitted at the same time as this SIP document) +- [PR with the proposed implementation](https://github.com/scala/scala3/pull/18262) + +## FAQ + +None at this point. diff --git a/_sips/sips/2012-03-17-modularizing-language-features.md b/_sips/sips/modularizing-language-features.md similarity index 86% rename from _sips/sips/2012-03-17-modularizing-language-features.md rename to _sips/sips/modularizing-language-features.md index b3178ba83f..4de88d18be 100644 --- a/_sips/sips/2012-03-17-modularizing-language-features.md +++ b/_sips/sips/modularizing-language-features.md @@ -1,9 +1,8 @@ --- layout: sip title: SIP-18 - Modularizing Language Features - -vote-status: complete -vote-text: This SIP has already been accepted and completed. Let the record show Paul is against it. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/modularizing-language-features.html --- diff --git a/_sips/sips/multi-source-extension-overloads.md b/_sips/sips/multi-source-extension-overloads.md new file mode 100644 index 0000000000..fdcfd7050b --- /dev/null +++ b/_sips/sips/multi-source-extension-overloads.md @@ -0,0 +1,233 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: completed +status: shipped +title: SIP-54 - Multi-Source Extension Overloads +--- + +**By: Sébastien Doeraene and Martin Odersky** + +## History + +| Date | Version | +|---------------|--------------------| +| Mar 10th 2023 | Initial Draft | + +## Summary + +We propose to allow overload resolution of `extension` methods with the same name but imported from several sources. +For example, given the following definitions: + +```scala +class Foo +class Bar + +object A: + extension (foo: Foo) def meth(): Foo = foo + def normalMeth(foo: Foo): Foo = foo + +object B: + extension (bar: Bar) def meth(): Bar = bar + def normalMeth(bar: Bar): Bar = bar +``` + +and the following use site: + +```scala +import A.* +import B.* + +val foo: Foo = ??? +foo.meth() // works with this SIP; "ambiguous import" without it + +// unchanged: +meth(foo)() // always ambiguous, just like +normalMeth(foo) // always ambiguous +``` + +## Motivation + +Extension methods are a great, straightforward way to extend external classes with additional methods. +One classical example is to add a `/` operation to `Path`: + +```scala +import java.nio.file.* + +object PathExtensions: + extension (path: Path) + def /(child: String): Path = path.resolve(child).nn + +def app1(): Unit = + import PathExtensions.* + val projectDir = Paths.get(".") / "project" +``` + +However, as currently specified, they do not compose, and effectively live in a single flat namespace. +This is understandable from the spec--the *mechanism**, which says that they are just regular methods, but is problematic from an intuitive point of view--the *intent*. + +For example, if we also use another extension that provides `/` for `URI`s, we can use it in a separate scope as follows: + +```scala +import java.net.URI + +object URIExtensions: + extension (uri: URI) + def /(child: String): URI = uri.resolve(child) + +def app2(): Unit = + import URIExtensions.* + val rootURI = new URI("https://www.example.com/") + val projectURI = rootURI / "project/" +``` + +The above does not work anymore if we need to use *both* extensions in the same scope. +The code below does not compile: + +```scala +def app(): Unit = + import PathExtensions.* + import URIExtensions.* + + val projectDir = Paths.get(".") / "project" + val rootURI = new URI("https://www.example.com/") + val projectURI = rootURI / "project/" + println(s"$projectDir -> $projectURI") +end app +``` + +*Both* attempts to use `/` result in error messages of the form + +``` +Reference to / is ambiguous, +it is both imported by import PathExtensions._ +and imported subsequently by import URIExtensions._ +``` + +### Workarounds + +The only workarounds that exist are unsatisfactory. + +We can avoid using extensions with the same name in the same scope. +In the above example, that would be annoying enough to defeat the purpose of the extensions in the first place. + +Another possibility is to *define* all extension methods of the same name in the same `object` (or as top-level definitions in the same file). +This is possible, although cumbersome, if they all come from the same library. +However, it is impossible to combine extension methods coming from separate libraries in this way. + +Finally, there exists a trick with `given`s of empty refinements: + +```scala +object PathExtensions: + given pathExtensions: {} with + extension (path: Path) + def /(child: String): Path = path.resolve(child).nn + +object URIExtensions: + given uriExtensions: {} with + extension (uri: URI) + def /(child: String): URI = uri.resolve(child) +``` + +The empty refinement `: {}` prevents those `given`s from polluting the actual implicit scope. +`extension`s defined inside `given`s that are in scope can be used, so this trick allows to use `/` with the imports of `PathExtensions.*` and `URIExtensions.*`. +The `given`s must still have different names for the trick to work. +This workaround is however quite obscure. +It hides intent behind a layer of magic (and an additional indirection at run-time). + +### Problem for migrating off of implicit classes + +Scala 2 implicit classes did not suffer from the above issues, because they were disambiguated by the name of the implicit class (not the name of the method). +This means that there are libraries that cannot migrate off of implicit classes to use `extension` methods without significantly degrading their usability. + +## Proposed solution + +We propose to relax the resolution of extension methods, so that they can be resolved from multiple imported sources. +Instead of rejecting the `/` call outright because of ambiguous imports, the compiler should try the resolution from all the imports, and keep the only one (if any) for which the receiver type matches. + +Practically speaking, this means that the above `app()` example would compile and behave as expected. + +### Non-goals + +It is *not* a goal of this proposal to allow resolution of arbitrary overloads of regular methods coming from multiple imports. +Only `extension` method calls are concerned by this proposal. +The complexity budget of relaxing *all* overloads in this way is deemed too high, whereas it is acceptable for `extension` method calls. + +For the same reason, we do not propose to change regular calls of methods that happen to be `extension` methods. + +### Specification + +We make two changes to the [specification of extension methods](https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html). + +In the section [Translation of Extension Methods](https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html#translation-of-extension-methods), we make it clearer that the "desugared" version of the call site may require an explicit qualifier. +This is not strictly a novelty of this SIP, since it could already happen with `given`s and implicit scopes, but this SIP adds one more case where this can happen. + +Previously: + +> So, the definition of circumference above translates to the following method, and can also be invoked as such: +> +> ` def circumference(c: Circle): Double = c.radius * math.Pi * 2` +> +> `assert(circle.circumference == circumference(circle))` + +With this SIP: + +> So, the definition of circumference above translates to the following method, and can also be invoked as such: +> +> ` def circumference(c: Circle): Double = c.radius * math.Pi * 2` +> +> `assert(circle.circumference == circumference(circle))` +> +> or +> +> `assert(circle.circumference == qualifierPath.circumference(circle))` +> +> for some `qualifierPath` in which `circumference` is actually declared. +> Explicit qualifiers may be required when the extension method is resolved through `given` instances, implicit scopes, or disambiguated from several imports. + +--- + +In the section [Translation of Calls to Extension Methods](https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html#translation-of-calls-to-extension-methods), we amend step 1. of "The precise rules for resolving a selection to an extension method are as follows." + +Previously: + +> Assume a selection `e.m[Ts]` where `m` is not a member of `e`, where the type arguments `[Ts]` are optional, and where `T` is the expected type. +> The following two rewritings are tried in order: +> +> 1. The selection is rewritten to `m[Ts](e)`. + +With this SIP: + +> 1. The selection is rewritten to `m[Ts](e)` and typechecked, using the following slight modification of the name resolution rules: +> +> - If `m` is imported by several imports which are all on the same nesting level, try each import as an extension method instead of failing with an ambiguity. +> If only one import leads to an expansion that typechecks without errors, pick that expansion. +> If there are several such imports, but only one import which is not a wildcard import, pick the expansion from that import. +> Otherwise, report an ambiguous reference error. + +### Compatibility + +The proposal only alters situations where the previous specification would reject the program with an ambiguous import. +Therefore, we expect it to be backward source compatible. + +The resolved calls could previously be spelled out by hand (with fully-qualified names), so binary compatibility and TASTy compatibility are not affected. + +### Other concerns + +With this SIP, some calls that would be reported as *ambiguous* in their "normal" form can actually be written without ambiguity if used as extensions. +That may be confusing to some users. +Although specific error messages are not specified and therefore outside the SIP scope, we encourage the compiler implementation to enhance the "ambiguous" error message to address this confusion. +If some or all of the involved ambiguous targets are `extension` methods, the compiler should point out that the call might be resolved unambiguously if used as an extension. + +## Alternatives + +A number of alternatives were mentioned in [the Contributors thread](https://contributors.scala-lang.org/t/change-shadowing-mechanism-of-extension-methods-for-on-par-implicit-class-behavior/5831), but none that passed the bar of "we think this is actually implementable". + +## Related work + +- [Contributors thread acting as de facto Pre-SIP](https://contributors.scala-lang.org/t/change-shadowing-mechanism-of-extension-methods-for-on-par-implicit-class-behavior/5831) +- [Pull Request in dotty](https://github.com/scala/scala3/pull/17050) to support it under an experimental import + +## FAQ + +This section will probably initially be empty. As discussions on the proposal progress, it is likely that some questions will come repeatedly. They should be listed here, with appropriate answers. diff --git a/_sips/sips/multiple-assignments.md b/_sips/sips/multiple-assignments.md new file mode 100644 index 0000000000..b55044b7d9 --- /dev/null +++ b/_sips/sips/multiple-assignments.md @@ -0,0 +1,331 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: implementation +status: under-review +presip-thread: https://contributors.scala-lang.org/t/pre-sip-multiple-assignments/6425 +title: SIP-59 - Multiple Assignments +--- + +**By: Dimi Racordon** + +## History + +| Date | Version | +|---------------|--------------------| +| Jan 17th 2024 | Initial Draft | + +## Summary + +This proposal discusses the syntax and semantics of a construct to assign multiple variables with a single expression. +This feature would simplify the implementation of operations expressed in terms of relationships between multiple variables, such as [`std::swap`](https://en.cppreference.com/w/cpp/algorithm/swap) in C++. + +## Motivation + +It happens that one has to assign multiple variables "at once" in an algorithm. +For example, let's consider the Fibonacci sequence: + +```scala +class FibonacciIterator() extends Iterator[Int]: + + private var a: Int = 0 + private var b: Int = 1 + + def hasNext = true + def next() = + val r = a + val n = a + b + a = b + b = n + r +``` + +The same iterator could be rewritten more concisely if we could assign multiple variables at once. +For example, we can write the following in Swift: + +```swift +struct FibonacciIterator: IteratorProtocol { + + private var a: Int = 0 + private var b: Int = 1 + init() {} + + mutating func next() -> Int? { + defer { (a, b) = (b, a + b) } + return a + } + +} +``` + +Though the differences may seem frivolous at first glance, they are in fact important. +If we look at a formal definition of the Fibonacci sequence (e.g., on [Wikipedia](https://en.wikipedia.org/wiki/Fibonacci_sequence)), we might see something like: + +> The Fibonacci sequence is given by *F(n) = F(n-1) + F(n+1)* where *F(0) = 0* and *F(1) = 1*. + +Although this declarative description says nothing about an evaluation order, it becomes a concern in our Scala implementation as we must encode the relationship into multiple operational steps. +This decomposition offers opportunities to get things wrong: + +```scala +def next() = + val r = a + a = b + b = a + b // invalid semantics, the value of `a` changed "too early" + r +``` + +In contrast, our Swift implementation can remain closer to the formal definition and is therefore more legible and less error-prone. + +Multiple assignments show up in many general-purpose algorithms (e.g., insertion sort, partition, min-max element, ...). +But perhaps the most fundamental one is `swap`, which consists of exchanging two values. + +We often swap values that are stored in some collection. +In this particular case, all is well in Scala because we can ask the collection to swap elements at given positions: + +```scala +extension [T](self: mutable.ArrayBuffer[T]) + def swapAt(i: Int, j: Int) = + val t = self(i) + self(i) = self(j) + self(j) = t + +val a = mutable.ArrayBuffer(1, 2, 3) +a.swapAt(0, 2) +println(a) // ArrayBuffer(3, 2, 1) +``` + +Sadly, one can't implement a generic swap method that wouldn't rely on the ability to index a container. +The only way to express this operation in Scala is to "inline" the pattern implemented by `swapAt` every time we need to swap two values. + +Having to rewrite this boilerplate is unfortunate. +Here is an example in a realistic algorithm: + +```scala +extension [T](self: Seq[T])(using Ordering[T]) + def minMaxElements: Option[(T, T)] = + import math.Ordering.Implicits.infixOrderingOps + + // Return None for collections smaller than 2 elements. + var i = self.iterator + if (!i.hasNext) { return None } + var l = i.next() + if (!i.hasNext) { return None } + var h = i.next() + + // Confirm the initial bounds. + if (h < l) { val t = l; l = h; h = l } + + // Process the remaining elements. + def loop(): Option[(T, T)] = + if (i.hasNext) { + val n = i.next() + if (n < l) { l = n } else if (n > h) { h = n } + loop() + } else { + Some((l, h)) + } + loop() +``` + +*Note: implementation shamelessly copied from [swift-algorithms](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/MinMax.swift).* + +The swap occurs in the middle of the method with the sequence of expressions `val t = l; l = h; h = l`. +To borrow from the words of Edgar Dijskstra [1, Chapter 11]: + +> [that] is combersome and ugly compared with the [multiple] assignment. + +While `swap` is a very common operation, it's only an instance of a more general class of operations that are expressed in terms of relationships between multiple variables. +The definition of the Fibonacci sequence is another example. + +## Proposed solution + +The proposed solution is to add a language construct to assign multiple variables in a single expression. +Using this construct, swapping two values can be written as follows: + +```scala +var a = 2 +var b = 4 +(a, b) = (b, a) +println(s"$a$b") // 42 +``` + +The above Fibonacci iterator can be rewritten as follows: + +```scala +class FibonacciIterator() extends Iterator[Int]: + + private var a: Int = 0 + private var b: Int = 1 + + def hasNext = true + def next() = + val r = a + (a, b) = (b, a + b) + r +``` + +Multiple assignments also alleviate the need for a swap method on collections, as the same idiomatic pattern can be reused to exchange elements at given indices: + +```scala +val a = mutable.ArrayBuffer(1, 2, 3) +(a(0), a(2)) = (a(2), a(0)) +println(a) // ArrayBuffer(3, 2, 1) +``` + +### Specification + +A multiple assignment is an expression of the form `AssignTarget ‘=’ Expr` where: + +``` +AssignTarget ::= ‘(’ AssignTargetNode {‘,’ AssignTargetNode} ‘)’ +AssignTargetNode ::= Expr | AssignTarget +``` + +An assignment target describes a structural pattern that can only be matched by a compatible composition of tuples. +For example, the following program is legal. + +```scala +def f: (Boolean, Int) = (true, 42) +val a = mutable.ArrayBuffer(1, 2, 3) +def b = a +var x = false + +(x, a(0)) = (false, 1337) +(x, a(1)) = f +((x, a(1)), b(2)) = (f, 9000) +(x) = Tuple1(false) +``` + +A mismatch between the structure of a multiple assignment's target and the result of its RHS is a type error. +It cannot be detected during parsing because at this stage the compiler would not be able to determine the shape of an arbitrary expression's result. +For example, all multiple assignments in the following program are ill-typed: + +```scala +def f: (Boolean, Int) = (true, 42) +val a = mutable.ArrayBuffer(1, 2, 3) +def b = a +var x = false + +(a(1), x) = f // type mismatch +(x, a(1), b(2)) = (f, 9000) // structural mismatch +(x) = false // structural mismatch +(x) = (1, 2) // structural mismatch +``` + +Likewise, `(x) = Tuple1(false)` is _not_ equivalent to `x = Tuple1(false)`. +The former is a multiple assignment while the latter is a regular assignment, as described by the [current grammar](https://docs.scala-lang.org/scala3/reference/syntax.html) (see `Expr1`). +Though this distinction is subtle, multiple assignments involving unary tuples should be rare. + +The operational semantics of multiple assignments (aka concurrent assignments) have been studied extensively in scienific literature (e.g., [1, 2]). +A first intuition is that the most desirable semantics can be achieved by fully evaluating the RHS of the assignment before assigning any expression in the LHS [1]. +However, additional considerations must be given w.r.t. the independence of the variables on the LHS to guarantee deterministic results. +For example, consider the following expression: + +```scala +(x, x) = (1, 2) +``` + +While one may conclude that such an expression should be an error [1], it is in general difficult to guarantee value independence in a language with pervasive reference semantics. +Further, it is desirable to write expressions of the form `(a(0), a(2)) = (a(2), a(0))`, as shown in the previous section. +Another complication is that multiple assignments should uphold the general left-to-right evaluation semantics of the Scala language. +For example, `a.b = c` requires `a` to be evaluated _before_ `c`. + +Note that regular assignments desugar to function calls (e.g., `a(b) = c` is sugar for `a.update(b, c)`). +One property of these desugarings is always the last expression being evaluated before the method performing the assignment is called. +Given this observation, we address the abovementioned issues by defining the following algorithm: + +1. Traverse the LHS structure in inorder and for each leaf: + - Evaluate each outermost subexpression to its value + - Form a closure capturing these values and accepting a single argument to perform the desugared assignment + - Associate that closure to the leaf +2. Compute the value of the RHS, which forms a tree +3. Traverse the LHS and RHS structures pairwise in inorder and for each leaf: + - Apply the closure formerly associated to the LHS on RHS value + +For instance, consider the following definitions. + +```scala +def f: (Boolean, Int) = (true, 42) +val a = mutable.ArrayBuffer(1, 2, 3) +def b = a +var x = false +``` + +The evaluation of the expression `((x, a(a(0))), b(2)) = (f, 9000)` is as follows: + +1. form a closure `f0 = (rhs) => x_=(rhs)` +2. evaluate `a(0)`; result is `1` +3. form a closure `f1 = (rhs) => a.update(1, rhs)` +4. evaluate `b`; result is `a` +5. evaluate `2` +6. form a closure `f2 = (rhs) => a.update(2, rhs)` +7. evaluate `(f, 9000)`; result is `((true, 42), 9000)` +8. evaluate `f0(true)` +9. evaluate `f1(42)` +10. evaluate `f2(9000)` + +After the assignment, `x == true` and `a == List(1, 42, 9000)`. + +The compiler is allowed to ignore this procedure and generate different code for optimization purposes as long as it can guarantee that such a change is not observable. +For example, given two local variables `x` and `y`, their assignments in `(x, y) = (1, 2)` can be reordered or even performed in parallel. + +### Compatibility + +This proposal is purely additive and have no backward binary or TASTy compatibility consequences. +The semantics of the proposed new construct is fully expressible in terms of desugaring into current syntax, interpreteted with current semantics. + +The proposed syntax is not currently legal Scala. +Therefore no currently existing program could be interpreted with different semantics using a newer compiler version supporting multiple assignments. + +### Other concerns + +One understandable concern of the proposed syntax is that the semantics of multiple assignments resembles that of pattern matching, yet it has different semantics. +For example: + +```scala +val (a(x), b) = (true, "!") // 1 + +(a(x), b) = (true, "!") // 2 +``` + +If `a` is instance of a type with a companion extractor object, the two lines above have completely different semantics. +The first declares two local bindings `x` and `b`, applying pattern matching to determine their value from the tuple `(true, "!")`. +The second is assigning `a(x)` and `b` to the values `true` and `"!"`, respectively. + +Though possibly surprising, the difference in behavior is easy to explain. +The first line applies pattern matching because it starts with `val`. +The second doesn't because it involves no pattern matching introducer. +Further, note that a similar situation can already be reproduced in current Scala: + +```scala +val a(x) = true // 1 + +a(x) = true // 2 +``` + +## Alternatives + +The current proposal supports arbitrary tree structures on the LHS of the assignment. +A simpler alternative would be to only support flat sequences, allowing the syntax to dispense with parentheses. + +```scala +a, b = b, a +``` + +While this approach is more lightweight, the reduced expressiveness inhibits potentially interesting use cases. +Further, consistently using tuple syntax on both sides of the equality operator clearly distinguishes regular and multiple assignments. + +## Related work + +A Pre-SIP discussion took place prior to this proposal (see [here](https://contributors.scala-lang.org/t/pre-sip-multiple-assignments/6425/1)). + +Multiple assignments are present in many contemporary languages. +This proposal already illustrated them in Swift, but they are also commonly used in Python. +Multiple assigments have also been studied extensively in scienific literature (e.g., [1, 2]). + +## FAQ + +## References + +1. Edsger W. Dijkstra: A Discipline of Programming. Prentice-Hall 1976, ISBN 013215871X +2. Ralph-Johan Back, Joakim von Wright: Refinement Calculus - A Systematic Introduction. Graduate Texts in Computer Science, Springer 1998, ISBN 978-0-387-98417-9 diff --git a/_sips/sips/name-based-xml-literals.md b/_sips/sips/name-based-xml-literals.md new file mode 100644 index 0000000000..1b3e699b01 --- /dev/null +++ b/_sips/sips/name-based-xml-literals.md @@ -0,0 +1,6 @@ +--- +title: SIP-40 - Name Based XML Literals +status: rejected +pull-request-number: 42 + +--- diff --git a/_sips/sips/2010-01-22-named-and-default-arguments.md b/_sips/sips/named-and-default-arguments.md similarity index 86% rename from _sips/sips/2010-01-22-named-and-default-arguments.md rename to _sips/sips/named-and-default-arguments.md index fecaed1b71..3d56605ad7 100644 --- a/_sips/sips/2010-01-22-named-and-default-arguments.md +++ b/_sips/sips/named-and-default-arguments.md @@ -1,8 +1,8 @@ --- layout: sip title: SID-1 Named and Default Arguments -vote-status: complete -vote-text: This SIP has already been accepted and completed. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/named-and-default-arguments.html --- @@ -16,13 +16,13 @@ The second language feature discussed in this document, default arguments, in ge ## Named Arguments -In Scala 2.8, method arguments can be specified in _named style_ using the same syntax as variable assignments: +In Scala 2.8, method arguments can be specified in _named style_ using the same syntax as variable assignments: def f[T](a: Int, b: T) f(b = getT(), a = getInt()) -The argument expressions are evaluated in call-site order, so in the above example `getT()` is executed before `getInt()`f. Mixing named and positional arguments is allowed as long as the positional part forms a prefix of the argument list: +The argument expressions are evaluated in call-site order, so in the above example `getT()` is executed before `getInt()`f. Mixing named and positional arguments is allowed as long as the positional part forms a prefix of the argument list: f(0, b = "1") // valid f(b = "1", a = 0) // valid @@ -51,7 +51,7 @@ The following list shows how named arguments interfere with other language featu **By-Name Parameters** continue to work as expected when using named arguments. The expression is only (and repeatedly) evaluated when the body of the method accesses the parameter. -**Repeated Parameters** When an application uses named arguments, the repeated parameter has to be specified exactly once. Using the same parameter name multiple times is disallowed. +**Repeated Parameters** When an application uses named arguments, the repeated parameter has to be specified exactly once. Using the same parameter name multiple times is disallowed. **Functional values** A functional value in Scala is an instance of a class which implements a method called apply. One can use the parameter names of that apply method for a named application. For functional values whose static type is scala.FunctionN, the parameter names of that apply method can be used. @@ -68,17 +68,17 @@ The following list shows how named arguments interfere with other language featu val a: A = new B a.f(a = 1) // OK -**Overloading Resolution** When a method application refers to an overloaded method, first the set of applicable alternatives is determined and then the most specific alternative is chosen (see [1], Chapter 6.26.3). +**Overloading Resolution** When a method application refers to an overloaded method, first the set of applicable alternatives is determined and then the most specific alternative is chosen (see [1], Chapter 6.26.3). -The presence of named argument influences the set of applicable alternatives, the argument types have to be matched against the corresponding parameter types based on the names. In the following example, the second alternative is applicable: +The presence of named argument influences the set of applicable alternatives, the argument types have to be matched against the corresponding parameter types based on the names. In the following example, the second alternative is applicable: def f() // #1 def f(a: Int, b: String) // #2 f(b = "someString", a = 1) // using #2 -If multiple alternatives are applicable, the most specific one is determined. This process is independent of the argument names used in a specific application and only looks at the method signature (for a detailed description, see [1], Chapter 6.26.3). +If multiple alternatives are applicable, the most specific one is determined. This process is independent of the argument names used in a specific application and only looks at the method signature (for a detailed description, see [1], Chapter 6.26.3). -In the following example, both alternatives are applicable, but none of them is more specific than the other because the argument types are compared based on their position, not on the argument name: +In the following example, both alternatives are applicable, but none of them is more specific than the other because the argument types are compared based on their position, not on the argument name: def f(a: Int, b: String) // #1 def f(b: Object, a: Int) // #2 @@ -113,7 +113,7 @@ A default argument may be an arbitrary expression. Since the scope of a paramete // def f(a: Int = 0, b: Int = a + 1) // "error: not found: value a" f(10)() // returns 11 (not 1) -A special expected type is used for type-checking the default argument `expr` of a method parameter `”x: T = expr”`: it is obtained by replacing all occurrences of type parameters of the method (type parameters of the class for constructors) with the undefined type. This allows specifying default arguments for polymorphic methods and classes: +A special expected type is used for type-checking the default argument `expr` of a method parameter `”x: T = expr”`: it is obtained by replacing all occurrences of type parameters of the method (type parameters of the class for constructors) with the undefined type. This allows specifying default arguments for polymorphic methods and classes: def f[T](a: T = 1) = a f() // returns 1: Int @@ -157,7 +157,7 @@ During type-checking, the static type is used to determine whether a parameter h def f(a: String, b: Int = 1) // #2 f("str") // both are applicable, #1 is selected -**Case Classes** For every case class, a method named `”copy”` is now generated which allows to easily create modified copies of the class’s instances. The copy method takes the same type and value parameters as the primary constructor of the case class, and every parameter defaults to the corresponding constructor parameter. +**Case Classes** For every case class, a method named `”copy”` is now generated which allows to easily create modified copies of the class’s instances. The copy method takes the same type and value parameters as the primary constructor of the case class, and every parameter defaults to the corresponding constructor parameter. case class A[T](a: T, b: Int) { // def copy[T’](a’: T’ = a, b’: Int = b): A[T’] = @@ -215,4 +215,4 @@ For constructor defaults, these methods are added to the companion object of the // } ## References -1. Odersky, M. _The Scala Language Specification, Version 2.11_. Available online at [http://www.scala-lang.org/files/archive/spec/2.11/](http://www.scala-lang.org/files/archive/spec/2.11/) +1. Odersky, M. _The Scala Language Specification, Version 2.11_. Available online at [https://www.scala-lang.org/files/archive/spec/2.11/](https://www.scala-lang.org/files/archive/spec/2.11/) diff --git a/_sips/sips/named-tuples.md b/_sips/sips/named-tuples.md new file mode 100644 index 0000000000..431107cd14 --- /dev/null +++ b/_sips/sips/named-tuples.md @@ -0,0 +1,777 @@ +--- +layout: sip +permalink: /sips/named-tuples.html +stage: completed +status: shipped +presip-thread: https://contributors.scala-lang.org/t/pre-sip-named-tuples/6403/164 +title: SIP-58 - Named Tuples +--- + +**By: Martin Odersky** + +## History + +| Date | Version | +|---------------|--------------------| +| Jan 13th 2024 | Initial Draft | + +## Summary + +We propose to add new form of tuples where the elements are named. +Named tuples can be types, terms, or patterns. Syntax examples: +```scala +type Person = (name: String, age: Int) +val Bob: Person = (name = "Bob", age = 33) + +Bob match + case (name = n, age = 22) => ... +``` + +We also propose to revive SIP 43 to support patterns with named fields. Named pattern fields for case classes are analogous to named patterns for tuple elements. User-defined named pattern matching is supported since named tuples can be results of extractor methods. + +## Motivation + + 1. Named tuples are a convenient lightweight way to return multiple results from a function. But the absence of names obscures their meaning, and makes decomposition with _1, _2 ugly and hard to read. The existing alternative is to define a class instead. This does name fields, but is more heavy-weight, both in terms of notation and generated bytecode. Named tuples give the same convenience of definition as regular tuples at far better readability. + + 1. Named tuples are an almost ideal substrate on which to implement relational algebra and other database oriented operations. They are a good representation of database rows and allow the definition of generic operations such as projections and joins since they can draw on Scala 3’s existing generic machinery for tuples based on match types. + + 1. Named tuples make named pattern matching trivial to implement. The discussion on SIP 43 showed that without them it’s unclear how to implement named pattern matching at all. + +## Proposed solution + +The elements of a tuple can now be named. Example: +```scala +type Person = (name: String, age: Int) +val Bob: Person = (name = "Bob", age = 33) + +Bob match + case (name, age) => + println(s"$name is $age years old") + +val persons: List[Person] = ... +val minors = persons.filter: p => + p.age < 18 +``` +Named bindings in tuples are similar to function parameters and arguments. We use `name: Type` for element types and `name = value` for element values. It is illegal to mix named and unnamed elements in a tuple, or to use the same same +name for two different elements. + +Fields of named tuples can be selected by their name, as in the line `p.age < 18` above. + +Example: + +~~~ scala +// This is an @main method +@main def foo(x: Int): Unit = + println(x) +~~~ + +### Conformance and Convertibility + +The order of names in a named tuple matters. For instance, the type `Person` above and the type `(age: Int, name: String)` would be different, incompatible types. + +Values of named tuple types can also be be defined using regular tuples. For instance: +```scala +val Laura: Person = ("Laura", 25) + +def register(person: Person) = ... +register(person = ("Silvain", 16)) +register(("Silvain", 16)) +``` +This follows since a regular tuple `(T_1, ..., T_n)` is treated as a subtype of a named tuple `(N_1 = T_1, ..., N_n = T_n)` with the same element types. + +In the other direction, one can convert a named tuple to an unnamed tuple with the `toTuple` method. Example: +```scala +val x: (String, Int) = Bob.toTuple // ok +``` +`toTuple` is defined as an extension method in the `NamedTuple` object. +It returns the given tuple unchanged and simply "forgets" the names. + +A `.toTuple` selection is inserted implicitly by the compiler if it encounters a named tuple but the expected type is a regular tuple. So the following works as well: +```scala +val x: (String, Int) = Bob // works, expanded to Bob.toTuple +``` +The difference between subtyping in one direction and automatic `.toTuple` conversions in the other is relatively minor. The main difference is that `.toTuple` conversions don't work inside type constructors. So the following is OK: +```scala + val names = List("Laura", "Silvain") + val ages = List(25, 16) + val persons: List[Person] = names.zip(ages) +``` +But the following would be illegal. +```scala + val persons: List[Person] = List(Bob, Laura) + val pairs: List[(String, Int)] = persons // error +``` +We would need an explicit `_.toTuple` selection to express this: +```scala + val pairs: List[(String, Int)] = persons.map(_.toTuple) +``` +Note that conformance rules for named tuples are analogous to the rules for named parameters. One can assign parameters by position to a named parameter list. +```scala + def f(param: Int) = ... + f(param = 1) // OK + f(2) // Also OK +``` +But one cannot use a name to pass an argument to an unnamed parameter: +```scala + val f: Int => T + f(2) // OK + f(param = 2) // Not OK +``` +The rules for tuples are analogous. Unnamed tuples conform to named tuple types, but the opposite requires a conversion. + +### Pattern Matching + +When pattern matching on a named tuple, the pattern may be named or unnamed. +If the pattern is named it needs to mention only a subset of the tuple names, and these names can come in any order. So the following are all OK: +```scala +Bob match + case (name, age) => ... + +Bob match + case (name = x, age = y) => ... + +Bob match + case (age = x) => ... + +Bob match + case (age = x, name = y) => ... +``` + +### Expansion + +Named tuples are in essence just a convenient syntax for regular tuples. In the internal representation, a named tuple type is represented at compile time as a pair of two tuples. One tuple contains the names as literal constant string types, the other contains the element types. The runtime representation of a named tuples consists of just the element values, whereas the names are forgotten. This is achieved by declaring `NamedTuple` +in package `scala` as an opaque type as follows: +```scala + opaque type NamedTuple[N <: Tuple, +V <: Tuple] >: V = V +``` +For instance, the `Person` type would be represented as the type +```scala +NamedTuple[("name", "age"), (String, Int)] +``` +`NamedTuple` is an opaque type alias of its second, value parameter. The first parameter is a string constant type which determines the name of the element. Since the type is just an alias of its value part, names are erased at runtime, and named tuples and regular tuples have the same representation. + +A `NamedTuple[N, V]` type is publicly known to be a supertype (but not a subtype) of its value paramater `V`, which means that regular tuples can be assigned to named tuples but not _vice versa_. + +The `NamedTuple` object contains a number of extension methods for named tuples hat mirror the same functions in `Tuple`. Examples are +`apply`, `head`, `tail`, `take`, `drop`, `++`, `map`, or `zip`. +Similar to `Tuple`, the `NamedTuple` object also contains types such as `Elem`, `Head`, `Concat` +that describe the results of these extension methods. + +The translation of named tuples to instances of `NamedTuple` is fixed by the specification and therefore known to the programmer. This means that: + + - All tuple operations also work with named tuples "out of the box". + - Macro libraries can rely on this expansion. + +### Computed Field Names + +The `Selectable` trait now has a `Fields` type member that can be instantiated +to a named tuple. + +```scala +trait Selectable: + type Fields <: NamedTuple.AnyNamedTuple +``` + +If `Fields` is instantiated in a subclass of `Selectable` to some named tuple type, +then the available fields and their types will be defined by that type. Assume `n: T` +is an element of the `Fields` type in some class `C` that implements `Selectable`, +that `c: C`, and that `n` is not otherwise legal as a name of a selection on `c`. +Then `c.n` is a legal selection, which expands to `c.selectDynamic("n").asInstanceOf[T]`. + +It is the task of the implementation of `selectDynamic` in `C` to ensure that its +computed result conforms to the predicted type `T` + +As an example, assume we have a query type `Q[T]` defined as follows: + +```scala +trait Q[T] extends Selectable: + type Fields = NamedTuple.Map[NamedTuple.From[T], Q] + def selectDynamic(fieldName: String) = ... +``` + +Assume in the user domain: +```scala +case class City(zipCode: Int, name: String, population: Int) +val city: Q[City] +``` +Then +```scala +city.zipCode +``` +has type `Q[Int]` and it expands to +```scala +city.selectDynamic("zipCode").asInstanceOf[Q[Int]] +``` + +### The NamedTuple.From Type + +The `NamedTuple` object contains a type definition +```scala + type From[T] <: AnyNamedTuple +``` +`From` is treated specially by the compiler. When `NamedTuple.From` is applied to +an argument type that is an instance of a case class, the type expands to the named +tuple consisting of all the fields of that case class. +Here, _fields_ means: elements of the first parameter section. For instance, assuming +```scala +case class City(zip: Int, name: String, population: Int) +``` +then `NamedTuple.From[City]` is the named tuple +```scala +(zip: Int, name: String, population: Int) +``` +The same works for enum cases expanding to case classes, abstract types with case classes as upper bound, alias types expanding to case classes +and singleton types with case classes as underlying type (in terms of the implementation, the `classSymbol` of a type must be a case class). + +`From` is also defined on named tuples. If `NT` is a named tuple type, then `From[NT] = NT`. + +### Pattern Matching with Named Fields in General + +We allow named patterns not just for named tuples but also for case classes. For instance: +```scala +city match + case c @ City(name = "London") => println(c.population) + case City(name = n, zip = 1026, population = pop) => println(pop) +``` + +Named constructor patterns are analogous to named tuple patterns. In both cases + + - every name must match the name some field of the selector, + - names can come in any order, + - not all fields of the selector need to be matched. + +This revives SIP 43, with a much simpler desugaring than originally proposed. +Named patterns are compatible with extensible pattern matching simply because +`unapply` results can be named tuples. + +### Operations on Named Tuples + +The operations on named tuples are defined in object `scala.NamedTuple`. The current version of this object is listed in Appendix A. + +### Restrictions + +The following restrictions apply to named tuples and named pattern arguments: + + 1. Either all elements of a tuple or constructor pattern are named or none are named. It is illegal to mix named and unnamed elements in a tuple. For instance, the following is in error: + ```scala + val illFormed1 = ("Bob", age = 33) // error + ``` + 2. Each element name in a named tuple or constructor pattern must be unique. For instance, the following is in error: + ```scala + val illFormed2 = (name = "", age = 0, name = true) // error + ``` + 3. Named tuples and case classes can be matched with either named or regular patterns. But regular tuples and other selector types can only be matched with regular tuple patterns. For instance, the following is in error: + ```scala + (tuple: Tuple) match + case (age = x) => // error + ``` + +### Use Case + +As a a use case showing some advanced capabilities of named tuples (including computed field names and the `From` type), +we show an implementation of embedded queries in Scala. For expressions that look like working with collections are instead +used to directly generate a query AST that can be further optimized and mapped to a variety of query languages. The code +is given in Appendix B. + +### Syntax Changes + +The syntax of Scala is extended as follows to support named tuples and +named constructor arguments: +``` +SimpleType ::= ... + | ‘(’ NameAndType {‘,’ NameAndType} ‘)’ +NameAndType ::= id ':' Type + +SimpleExpr ::= ... + | '(' NamedExprInParens {‘,’ NamedExprInParens} ')' +NamedExprInParens ::= id '=' ExprInParens + +Patterns ::= Pattern {‘,’ Pattern} + | NamedPattern {‘,’ NamedPattern} +NamedPattern ::= id '=' Pattern +``` + +### Compatibility + +Named tuple types and expressions are simply desugared to types and trees already known to Scala. The desugaring happens before the checking, so does not influence Tasty generation. + +Pattern matching with named fields requires some small additions to Typer and the PatternMatcher phase. It does not change the Tasty format, though. + +Backward source compatibility is partially preserved since additions to types and patterns come with new syntax that was not expressible before. When looking at tuple expressions, we have two instances of a source incompatibility: + +```scala +var age: Int +(age = 1) +``` +This was an assignment in parentheses before, and is a named tuple of arity one now. It is however not idiomatic Scala code, since assignments are not usually enclosed in parentheses. + +Also, if we have +```scala +class C: + infix def f(age: Int) +val c: C +``` +then +```scala +c f (age = 1) +``` +will now construct a tuple as second operand instead of passing a named parameter. + +These problems can be detected and diagnosed fairly straightforwardly: When faced with a unary named tuple, try to interpret it as an assignment, and if that succeeds, issue a migration error and suggest a workaround of these kinds: +```scala + {age = 1} // ok + c.f(age = 1) // ok +``` + +### Open questions + + 1. What is the precise set of types and operations we want to add to `NamedTuple`. This could also evolve after this SIP is completed. + + 2. Should there be an implicit conversion from named tuples to ordinary tuples? + +## Alternatives + +### Structural Types + +We also considered to expand structural types. Structural types allow to abstract over existing classes, but require reflection or some other library-provided mechanism for element access. By contrast, named tuples have a separate representation as tuples, which can be manipulated directly. Since elements are ordered, traversals can be defined, and this allows the definition of type generic algorithms over named tuples. Structural types don’t allow such generic algorithms directly. Be could define mappings between structural types and named tuples, which could be used to implement such algorithms. These mappings would certainly become simpler if they map to/from named tuples than if they had to map to/from user-defined "HMap"s. + +By contrast to named tuples, structural types are unordered and have width subtyping. This comes with the price that no natural element ordering exist, and that one usually needs some kind of dictionary structure for access. We believe that the following advantages of named tuples over structural types outweigh the loss of subtyping flexibility: + + - Better integration since named tuples and normal tuples share the same representation. + - Better efficiency, since no dictionary is needed. + - Natural traversal order allows the formulation of generic algorithms such as projections and joins. + +### Conformance + +A large part of Pre-SIP discussion centered around subtyping rules, whether ordinary tuples should subtype named-tuples (as in this proposal) or _vice versa_ or maybe no subtyping at all. + +Looking at precedent in other languages it feels like we we do want some sort of subtyping for easy convertibility and an implicit conversion in the other direction. This proposal picks _unnamed_ <: _named_ for the subtyping and _named_ -> _unnamed_ for the conversion. + +The discussion established that both forms of subtyping are sound. My personal opinion is that the subtyping of this proposal is both more useful and safer than the one in the other direction. There is also the problem that changing the subtyping direction would be incompatible with the current structure of `Tuple` and `NamedTuple` since for instance `zip` is already an inline method on `Tuple` so it could not be overridden in `NamedTuple`. To make this work requires a refactoring of `Tuple` to use more extension methods, and the questions whether this is feasible and whether it can be made binary backwards compatible are unknown. I personally will not work on this, if others are willing to make the effort we can discuss the alternative subtyping as well. + +_Addendum:_ Turning things around, adopting _named_ <: _unnamed_ for the subtyping and `_unnamed_ -> _named_ for the conversion leads to weaker typing with undetected errors. Consider: +```scala +type Person = (name: String, age: Int) +val bob: Person +bob.zip((firstName: String, agee: Int)) +``` +This should report a type error. +But in the alternative scheme, we'd have `(firstName: String, agee: Int) <: (String, Int)` by subtyping and then +`(String, Int) -> (name: String, age: Int)` by implicit naming conversion. This is clearly not what we want. + +By contrast, in the implemented scheme, we will not convert `(firstName: String, agee: Int)` to `(String, Int)` since a conversion is only attempted if the expected type is a regular tuple, and in our scenario it is a named tuple instead. + +My takeaway is that these designs have rather subtle consequences and any alterations would need a full implementation before they can be judged. For instance, the situation with `zip` was a surprise to me, which came up since I first implemented `_.toTuple` as a regular implicit conversion instead of a compiler adaptation. + +A possibly simpler design would be to drop all conformance and conversion rules. The problem with this approach is worse usability and problems with smooth migration. Migration will be an issue since right now everything is a regular tuple. If we make it hard to go from there to named tuples, everything will tend to stay a regular tuple and named tuples will be much less used than we would hope for. + + +### Spread Operator + +An idea I was thinking of but that I did not include in this proposal highlights another potential problem with subtyping. Consider adding a _spread_ operator `*` for tuples and named tuples. if `x` is a tuple then `f(x*)` is `f` applied to all fields of `x` expanded as individual arguments. Likewise, if `y` is a named tuple, then `f(y*)` is `f` applied to all elements of `y` as named arguments. +Now, if named tuples would be subtypes of tuples, this would actually be ambiguous since widening `y` in `y*` to a regular tuple would yield a different call. But with the subtyping direction we have, this would work fine. + +I believe tuple spread is a potentially useful addition that would fit in well with Scala. But it's not immediately relevant to this proposal, so is left out for now. + + +## Related work + +This section should list prior work related to the proposal, notably: + +- [Pre-SIP Discussion](https://contributors.scala-lang.org/t/pre-sip-named-tuples/6403) + +- [SIP 43 on Pattern Matching with Named Fields](https://github.com/scala/improvement-proposals/pull/44) + +- [Experimental Implementation](https://github.com/scala/scala3/pull/19174) + +## FAQ + +## Appendix A: NamedTuple Definition + +Here is the current definition of `NamedTuple`. This is part of the library and therefore subject to future changes and additions. + +```scala +package scala +import annotation.experimental +import compiletime.ops.boolean.* + +@experimental +object NamedTuple: + + opaque type AnyNamedTuple = Any + opaque type NamedTuple[N <: Tuple, +V <: Tuple] >: V <: AnyNamedTuple = V + + def apply[N <: Tuple, V <: Tuple](x: V): NamedTuple[N, V] = x + + def unapply[N <: Tuple, V <: Tuple](x: NamedTuple[N, V]): Some[V] = Some(x) + + extension [V <: Tuple](x: V) + inline def withNames[N <: Tuple]: NamedTuple[N, V] = x + + export NamedTupleDecomposition.{Names, DropNames} + + extension [N <: Tuple, V <: Tuple](x: NamedTuple[N, V]) + + /** The underlying tuple without the names */ + inline def toTuple: V = x + + /** The number of elements in this tuple */ + inline def size: Tuple.Size[V] = toTuple.size + + // This intentionally works for empty named tuples as well. I think NnEmptyTuple is a dead end + // and should be reverted, justy like NonEmptyList is also appealing at first, but a bad idea + // in the end. + + /** The value (without the name) at index `n` of this tuple */ + inline def apply(n: Int): Tuple.Elem[V, n.type] = + inline toTuple match + case tup: NonEmptyTuple => tup(n).asInstanceOf[Tuple.Elem[V, n.type]] + case tup => tup.productElement(n).asInstanceOf[Tuple.Elem[V, n.type]] + + /** The first element value of this tuple */ + inline def head: Tuple.Elem[V, 0] = apply(0) + + /** The tuple consisting of all elements of this tuple except the first one */ + inline def tail: Tuple.Drop[V, 1] = toTuple.drop(1) + + /** The last element value of this tuple */ + inline def last: Tuple.Last[V] = apply(size - 1).asInstanceOf[Tuple.Last[V]] + + /** The tuple consisting of all elements of this tuple except the last one */ + inline def init: Tuple.Init[V] = toTuple.take(size - 1).asInstanceOf[Tuple.Init[V]] + + /** The tuple consisting of the first `n` elements of this tuple, or all + * elements if `n` exceeds `size`. + */ + inline def take(n: Int): NamedTuple[Tuple.Take[N, n.type], Tuple.Take[V, n.type]] = + toTuple.take(n) + + /** The tuple consisting of all elements of this tuple except the first `n` ones, + * or no elements if `n` exceeds `size`. + */ + inline def drop(n: Int): NamedTuple[Tuple.Drop[N, n.type], Tuple.Drop[V, n.type]] = + toTuple.drop(n) + + /** The tuple `(x.take(n), x.drop(n))` */ + inline def splitAt(n: Int): NamedTuple[Tuple.Split[N, n.type], Tuple.Split[V, n.type]] = + toTuple.splitAt(n) + + /** The tuple consisting of all elements of this tuple followed by all elements + * of tuple `that`. The names of the two tuples must be disjoint. + */ + inline def ++ [N2 <: Tuple, V2 <: Tuple](that: NamedTuple[N2, V2])(using Tuple.Disjoint[N, N2] =:= true) + : NamedTuple[Tuple.Concat[N, N2], Tuple.Concat[V, V2]] + = toTuple ++ that.toTuple + + // inline def :* [L] (x: L): NamedTuple[Append[N, ???], Append[V, L] = ??? + // inline def *: [H] (x: H): NamedTuple[??? *: N], H *: V] = ??? + + /** The named tuple consisting of all element values of this tuple mapped by + * the polymorphic mapping function `f`. The names of elements are preserved. + * If `x = (n1 = v1, ..., ni = vi)` then `x.map(f) = `(n1 = f(v1), ..., ni = f(vi))`. + */ + inline def map[F[_]](f: [t] => t => F[t]): NamedTuple[N, Tuple.Map[V, F]] = + toTuple.map(f).asInstanceOf[NamedTuple[N, Tuple.Map[V, F]]] + + /** The named tuple consisting of all elements of this tuple in reverse */ + inline def reverse: NamedTuple[Tuple.Reverse[N], Tuple.Reverse[V]] = + toTuple.reverse + + /** The named tuple consisting of all elements values of this tuple zipped + * with corresponding element values in named tuple `that`. + * If the two tuples have different sizes, + * the extra elements of the larger tuple will be disregarded. + * The names of `x` and `that` at the same index must be the same. + * The result tuple keeps the same names as the operand tuples. + */ + inline def zip[V2 <: Tuple](that: NamedTuple[N, V2]): NamedTuple[N, Tuple.Zip[V, V2]] = + toTuple.zip(that.toTuple) + + /** A list consisting of all element values */ + inline def toList: List[Tuple.Union[V]] = toTuple.toList.asInstanceOf[List[Tuple.Union[V]]] + + /** An array consisting of all element values */ + inline def toArray: Array[Object] = toTuple.toArray + + /** An immutable array consisting of all element values */ + inline def toIArray: IArray[Object] = toTuple.toIArray + + end extension + + /** The size of a named tuple, represented as a literal constant subtype of Int */ + type Size[X <: AnyNamedTuple] = Tuple.Size[DropNames[X]] + + /** The type of the element value at position N in the named tuple X */ + type Elem[X <: AnyNamedTuple, N <: Int] = Tuple.Elem[DropNames[X], N] + + /** The type of the first element value of a named tuple */ + type Head[X <: AnyNamedTuple] = Elem[X, 0] + + /** The type of the last element value of a named tuple */ + type Last[X <: AnyNamedTuple] = Tuple.Last[DropNames[X]] + + /** The type of a named tuple consisting of all elements of named tuple X except the first one */ + type Tail[X <: AnyNamedTuple] = Drop[X, 1] + + /** The type of the initial part of a named tuple without its last element */ + type Init[X <: AnyNamedTuple] = + NamedTuple[Tuple.Init[Names[X]], Tuple.Init[DropNames[X]]] + + /** The type of the named tuple consisting of the first `N` elements of `X`, + * or all elements if `N` exceeds `Size[X]`. + */ + type Take[X <: AnyNamedTuple, N <: Int] = + NamedTuple[Tuple.Take[Names[X], N], Tuple.Take[DropNames[X], N]] + + /** The type of the named tuple consisting of all elements of `X` except the first `N` ones, + * or no elements if `N` exceeds `Size[X]`. + */ + type Drop[X <: AnyNamedTuple, N <: Int] = + NamedTuple[Tuple.Drop[Names[X], N], Tuple.Drop[DropNames[X], N]] + + /** The pair type `(Take(X, N), Drop[X, N]). */ + type Split[X <: AnyNamedTuple, N <: Int] = (Take[X, N], Drop[X, N]) + + /** Type of the concatenation of two tuples `X` and `Y` */ + type Concat[X <: AnyNamedTuple, Y <: AnyNamedTuple] = + NamedTuple[Tuple.Concat[Names[X], Names[Y]], Tuple.Concat[DropNames[X], DropNames[Y]]] + + /** The type of the named tuple `X` mapped with the type-level function `F`. + * If `X = (n1 : T1, ..., ni : Ti)` then `Map[X, F] = `(n1 : F[T1], ..., ni : F[Ti])`. + */ + type Map[X <: AnyNamedTuple, F[_ <: Tuple.Union[DropNames[X]]]] = + NamedTuple[Names[X], Tuple.Map[DropNames[X], F]] + + /** A named tuple with the elements of tuple `X` in reversed order */ + type Reverse[X <: AnyNamedTuple] = + NamedTuple[Tuple.Reverse[Names[X]], Tuple.Reverse[DropNames[X]]] + + /** The type of the named tuple consisting of all element values of + * named tuple `X` zipped with corresponding element values of + * named tuple `Y`. If the two tuples have different sizes, + * the extra elements of the larger tuple will be disregarded. + * The names of `X` and `Y` at the same index must be the same. + * The result tuple keeps the same names as the operand tuples. + * For example, if + * ``` + * X = (n1 : S1, ..., ni : Si) + * Y = (n1 : T1, ..., nj : Tj) where j >= i + * ``` + * then + * ``` + * Zip[X, Y] = (n1 : (S1, T1), ..., ni: (Si, Ti)) + * ``` + * @syntax markdown + */ + type Zip[X <: AnyNamedTuple, Y <: AnyNamedTuple] = + Tuple.Conforms[Names[X], Names[Y]] match + case true => + NamedTuple[Names[X], Tuple.Zip[DropNames[X], DropNames[Y]]] + + type From[T] <: AnyNamedTuple + +end NamedTuple + +/** Separate from NamedTuple object so that we can match on the opaque type NamedTuple. */ +@experimental +object NamedTupleDecomposition: + import NamedTuple.* + + /** The names of a named tuple, represented as a tuple of literal string values. */ + type Names[X <: AnyNamedTuple] <: Tuple = X match + case NamedTuple[n, _] => n + + /** The value types of a named tuple represented as a regular tuple. */ + type DropNames[NT <: AnyNamedTuple] <: Tuple = NT match + case NamedTuple[_, x] => x +``` + +## Appendix B: Embedded Queries Case Study + +```scala +import language.experimental.namedTuples +import NamedTuple.{NamedTuple, AnyNamedTuple} + +/* This is a demonstrator that shows how to map regular for expressions to + * internal data that can be optimized by a query engine. It needs NamedTuples + * and type classes but no macros. It's so far very provisional and experimental, + * intended as a basis for further exploration. + */ + +/** The type of expressions in the query language */ +trait Expr[Result] extends Selectable: + + /** This type is used to support selection with any of the field names + * defined by Fields. + */ + type Fields = NamedTuple.Map[NamedTuple.From[Result], Expr] + + /** A selection of a field name defined by Fields is implemented by `selectDynamic`. + * The implementation will add a cast to the right Expr type corresponding + * to the field type. + */ + def selectDynamic(fieldName: String) = Expr.Select(this, fieldName) + + /** Member methods to implement universal equality on Expr level. */ + def == (other: Expr[?]): Expr[Boolean] = Expr.Eq(this, other) + def != (other: Expr[?]): Expr[Boolean] = Expr.Ne(this, other) + +object Expr: + + /** Sample extension methods for individual types */ + extension (x: Expr[Int]) + def > (y: Expr[Int]): Expr[Boolean] = Gt(x, y) + def > (y: Int): Expr[Boolean] = Gt(x, IntLit(y)) + extension (x: Expr[Boolean]) + def &&(y: Expr[Boolean]): Expr[Boolean] = And(x, y) + def || (y: Expr[Boolean]): Expr[Boolean] = Or(x, y) + + // Note: All field names of constructors in the query language are prefixed with `$` + // so that we don't accidentally pick a field name of a constructor class where we want + // a name in the domain model instead. + + // Some sample constructors for Exprs + case class Gt($x: Expr[Int], $y: Expr[Int]) extends Expr[Boolean] + case class Plus(x: Expr[Int], y: Expr[Int]) extends Expr[Int] + case class And($x: Expr[Boolean], $y: Expr[Boolean]) extends Expr[Boolean] + case class Or($x: Expr[Boolean], $y: Expr[Boolean]) extends Expr[Boolean] + + // So far Select is weakly typed, so `selectDynamic` is easy to implement. + // Todo: Make it strongly typed like the other cases + case class Select[A]($x: Expr[A], $name: String) extends Expr + + case class Single[S <: String, A]($x: Expr[A]) + extends Expr[NamedTuple[S *: EmptyTuple, A *: EmptyTuple]] + + case class Concat[A <: AnyNamedTuple, B <: AnyNamedTuple]($x: Expr[A], $y: Expr[B]) + extends Expr[NamedTuple.Concat[A, B]] + + case class Join[A <: AnyNamedTuple](a: A) + extends Expr[NamedTuple.Map[A, StripExpr]] + + type StripExpr[E] = E match + case Expr[b] => b + + // Also weakly typed in the arguents since these two classes model universal equality */ + case class Eq($x: Expr[?], $y: Expr[?]) extends Expr[Boolean] + case class Ne($x: Expr[?], $y: Expr[?]) extends Expr[Boolean] + + /** References are placeholders for parameters */ + private var refCount = 0 + + case class Ref[A]($name: String = "") extends Expr[A]: + val id = refCount + refCount += 1 + override def toString = s"ref$id(${$name})" + + /** Literals are type-specific, tailored to the types that the DB supports */ + case class IntLit($value: Int) extends Expr[Int] + + /** Scala values can be lifted into literals by conversions */ + given Conversion[Int, IntLit] = IntLit(_) + + /** The internal representation of a function `A => B` + * Query languages are ususally first-order, so Fun is not an Expr + */ + case class Fun[A, B](param: Ref[A], f: B) + + type Pred[A] = Fun[A, Expr[Boolean]] + + /** Explicit conversion from + * (name_1: Expr[T_1], ..., name_n: Expr[T_n]) + * to + * Expr[(name_1: T_1, ..., name_n: T_n)] + */ + extension [A <: AnyNamedTuple](x: A) def toRow: Join[A] = Join(x) + + /** Same as _.toRow, as an implicit conversion */ + given [A <: AnyNamedTuple]: Conversion[A, Expr.Join[A]] = Expr.Join(_) + +end Expr + +/** The type of database queries. So far, we have queries + * that represent whole DB tables and queries that reify + * for-expressions as data. + */ +trait Query[A] + +object Query: + import Expr.{Pred, Fun, Ref} + + case class Filter[A]($q: Query[A], $p: Pred[A]) extends Query[A] + case class Map[A, B]($q: Query[A], $f: Fun[A, Expr[B]]) extends Query[B] + case class FlatMap[A, B]($q: Query[A], $f: Fun[A, Query[B]]) extends Query[B] + + // Extension methods to support for-expression syntax for queries + extension [R](x: Query[R]) + + def withFilter(p: Ref[R] => Expr[Boolean]): Query[R] = + val ref = Ref[R]() + Filter(x, Fun(ref, p(ref))) + + def map[B](f: Ref[R] => Expr[B]): Query[B] = + val ref = Ref[R]() + Map(x, Fun(ref, f(ref))) + + def flatMap[B](f: Ref[R] => Query[B]): Query[B] = + val ref = Ref[R]() + FlatMap(x, Fun(ref, f(ref))) +end Query + +/** The type of query references to database tables */ +case class Table[R]($name: String) extends Query[R] + +// Everything below is code using the model ----------------------------- + +// Some sample types +case class City(zipCode: Int, name: String, population: Int) +type Address = (city: City, street: String, number: Int) +type Person = (name: String, age: Int, addr: Address) + +@main def Test = + + val cities = Table[City]("cities") + + val q1 = cities.map: c => + c.zipCode + val q2 = cities.withFilter: city => + city.population > 10_000 + .map: city => + city.name + + val q3 = + for + city <- cities + if city.population > 10_000 + yield city.name + + val q4 = + for + city <- cities + alt <- cities + if city.name == alt.name && city.zipCode != alt.zipCode + yield + city + + val addresses = Table[Address]("addresses") + val q5 = + for + city <- cities + addr <- addresses + if addr.street == city.name + yield + (name = city.name, num = addr.number) + + val q6 = + cities.map: city => + (name = city.name, zipCode = city.zipCode) + + def run[T](q: Query[T]): Iterator[T] = ??? + + def x1: Iterator[Int] = run(q1) + def x2: Iterator[String] = run(q2) + def x3: Iterator[String] = run(q3) + def x4: Iterator[City] = run(q4) + def x5: Iterator[(name: String, num: Int)] = run(q5) + def x6: Iterator[(name: String, zipCode: Int)] = run(q6) +``` diff --git a/_sips/sips/new-collection-classes.md b/_sips/sips/new-collection-classes.md new file mode 100644 index 0000000000..d8bb9b8047 --- /dev/null +++ b/_sips/sips/new-collection-classes.md @@ -0,0 +1,10 @@ +--- +layout: sip +title: SID-3 - New Collection classes +stage: completed +status: shipped +permalink: /sips/:title.html +redirect_from: /sips/pending/new-collection-classes.html +--- + +This was an older SID that can be found [here](https://www.scala-lang.org/sid/3) diff --git a/_sips/sips/2017-09-20-opaque-types.md b/_sips/sips/opaque-types.md similarity index 96% rename from _sips/sips/2017-09-20-opaque-types.md rename to _sips/sips/opaque-types.md index 7c8d5e3444..a33083181d 100644 --- a/_sips/sips/2017-09-20-opaque-types.md +++ b/_sips/sips/opaque-types.md @@ -1,12 +1,14 @@ --- layout: sip title: SIP-35 - Opaque types - -vote-status: pending +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/opaque-types.html --- +> This proposal has been implemented with some changes in Scala 3.0.0. + **Authors: Erik Osheim and Jorge Vicente Cantero** **Supervisor and advisor: Sébastien Doeraene** @@ -50,11 +52,8 @@ For a definition of boxing and previous state-of-the-art, we recommend reading [ ### Implementation note -The proposal is currently in an early stage. -[It’s being implemented](https://github.com/scalacenter/scala/tree/opaque-type), -but the proposed implementation strategy is not detailed enough to be able -to predict with certainty that it will work as specified. Consequently, -details of the proposal might change driven by implementation concerns. +Opaque types have been implemented in Scala 3.0.0 with +[some changes compared to this proposal]({{ site.scala3ref }}/other-new-features/opaques-details.html#relationship-to-sip-35). ## Opaque types @@ -122,7 +121,7 @@ signature of `apply` is redefined as `def apply(x: Double): Double` and that `val x: Logarithm = Logarithm(1e7)` is instead `val x: Double = Logarithm.apply(1e7)`. -Value classes can rewrite many instances `Logarithm` in terms of +Value classes can rewrite many instances of `Logarithm` in terms of `Double`, including local variables, method parameters, return types, and most fields. SIP-15 lays out the exact circumstances when these rules occur, and extension methods ensure that boxing and unboxing @@ -293,7 +292,7 @@ package object usesites { } ``` -Note that the rational for this encoding is to allow users to convert from the opaque type +Note that the rationale for this encoding is to allow users to convert from the opaque type and the underlying type in constant time. Users have to be able to tag complex type structures without having to reallocate, iterate over or inspect it. @@ -482,7 +481,7 @@ opaque type `Fix`: ```scala package object fixed { - opaque type Fix[F_]] = F[Fix[F]] + opaque type Fix[F[_]] = F[Fix[F]] object Fix { def fix[F[_]](unfixed: F[Fix[F]]): Fix[F] = unfixed @@ -564,7 +563,7 @@ libraries). Unlike a value class, we can guarantee that there will never be a wrapper around the raw values (or raw nulls). Notice that `Nullable[Nullable[B]]` is not a valid type, because -`Nullalbe[B]` is not known to be `<: AnyRef`. This is a key difference +`Nullable[B]` is not known to be `<: AnyRef`. This is a key difference between a type like `Option` (which is parametric and can easily wrap itself) and a type like `Nullable` (which only has one `null` value to use). @@ -670,8 +669,8 @@ package object groups { opaque type Unordered[A] = A object Unordered extends Wrapper[Unordered] { - def wraps[G[_], A](ga: G[A]): G[Reversed[A]] = ga - def unwrap[G[_], A](gfa: G[Reversed[A]]): G[A] = gfa + def wraps[G[_], A](ga: G[A]): G[Unordered[A]] = ga + def unwrap[G[_], A](gfa: G[Unordered[A]]): G[A] = gfa implicit def unorderedOrdering[A]: Ordering[Unordered[A]] = Ordering.by(_ => ()) } @@ -693,7 +692,7 @@ example `Int`). ### Probability interval Here's an example that demonstrates how opaque types can limit the -underlying type's range of values in a way that minimizes the require +underlying type's range of values in a way that minimizes the required error-checking: ```scala @@ -885,7 +884,7 @@ there will certainly be an impact on the bytecode produced (and possibly the runtime performance). By contrast, replacing `String` with `Digits` is guaranteed to have no -impact (all occurances of `Digits` are guaranteed to be erased to +impact (all occurrences of `Digits` are guaranteed to be erased to `String`). Aside from the ergonomics of calling the `fromString` and `asString` methods, there's no runtime impact versus using the underlying type. @@ -953,7 +952,7 @@ but it is *not* a `List[AnyVal]`. Since value classes do have a runtime representation, they do increase the size of runtime artifacts produced (whether a JAR file, a -javascript file, or something else). Their methods are also compiled +JavaScript file, or something else). Their methods are also compiled to multiple representations (i.e. they support both the boxed and unboxed forms via extensions methods). Again, this comes at a cost. @@ -1020,10 +1019,10 @@ As a summary, opaque types are: [Appendix A]: https://failex.blogspot.ch/2017/04/the-high-cost-of-anyval-subclasses.html [Scala Language Specification]: https://www.scala-lang.org/files/archive/spec/2.12/ -[type alias]: http://www.scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#type-declarations-and-type-aliases -[5.5. Object definitions]: http://www.scala-lang.org/files/archive/spec/2.12/05-classes-and-objects.html#object-definitions -[3.5.1. Equivalence]: http://www.scala-lang.org/files/archive/spec/2.12/03-types.html#equivalence +[type alias]: https://www.scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#type-declarations-and-type-aliases +[5.5. Object definitions]: https://www.scala-lang.org/files/archive/spec/2.12/05-classes-and-objects.html#object-definitions +[3.5.1. Equivalence]: https://www.scala-lang.org/files/archive/spec/2.12/03-types.html#equivalence [Scala.js]: https://www.scala-js.org/ [Scala Native]: https://github.com/scala-native/scala-native [beta reducing]: https://en.wikipedia.org/wiki/Beta_normal_form -[SIP-15]: http://docs.scala-lang.org/sips/value-classes.html +[SIP-15]: https://docs.scala-lang.org/sips/value-classes.html diff --git a/_sips/sips/pattern-matching-with-named-fields.md b/_sips/sips/pattern-matching-with-named-fields.md new file mode 100644 index 0000000000..c1c304a61f --- /dev/null +++ b/_sips/sips/pattern-matching-with-named-fields.md @@ -0,0 +1,6 @@ +--- +title: SIP-43 - Pattern matching with named fields +status: withdrawn +pull-request-number: 44 + +--- diff --git a/_sips/sips/2010-06-01-picked-signatures.md b/_sips/sips/picked-signatures.md similarity index 50% rename from _sips/sips/2010-06-01-picked-signatures.md rename to _sips/sips/picked-signatures.md index cffc271a45..12f205a4e1 100644 --- a/_sips/sips/2010-06-01-picked-signatures.md +++ b/_sips/sips/picked-signatures.md @@ -1,10 +1,10 @@ --- layout: sip title: SID-10 - Storage of pickled Scala signatures in class files -vote-status: complete -vote-text: This SIP has already been accepted and completed. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/picked-signatures.html --- -This was an older SID that can be found [here](http://www.scala-lang.org/sid/10) +This was an older SID that can be found [here](https://www.scala-lang.org/sid/10) diff --git a/_sips/sips/polymorphic-eta-expansion.md b/_sips/sips/polymorphic-eta-expansion.md new file mode 100644 index 0000000000..4099e05cc8 --- /dev/null +++ b/_sips/sips/polymorphic-eta-expansion.md @@ -0,0 +1,429 @@ +--- +layout: sip +title: SIP-49 - Polymorphic Eta-Expansion +stage: implementation +status: waiting-for-implementation +permalink: /sips/:title.html +--- + +**By: Quentin Bernet and Guillaume Martres** + +## History + +| Date | Version | +|---------------|--------------------| +| Sep 23th 2022 | Initial Draft | + +## Summary + + + +We propose to extend eta-expansion to polymorphic methods. +This means automatically transforming polymorphic methods into corresponding polymorphic functions when required, for example: + +~~~ scala +def f1[A](x: A): A = ??? +val v1_1: [B] => B => B = f1 // f1 becomes [B'] => (y: B') => f1[B'](y) +~~~ + +Returning readers, for a quick glance at a wide array of examples illustrated like the above, go to [High-level overview](#high-level-overview). + +In the following, "Note" never introduces new concepts, it points out a non-obvious consequence, and/or reminds the reader of a pertinent fact about Scala. + +## Motivation + + + +Regular eta-expansion is so ubiquitous that most users are not aware of it, for them it is intuitive and obvious that methods can be passed where functions are expected. + +When manipulating polymorphic methods, we wager that most users find it confusing not to be able to do the same. +This is the main motivation of this proposal. + +It however remains to be demonstrated that such cases appear often enough for time and maintenance to be devoted to fixing it. +To this end, the remainder of this section will show a manufactured example with tuples, as well as real-world examples taken from the [Shapeless-3](https://index.scala-lang.org/typelevel/shapeless-3) and [kittens](https://index.scala-lang.org/typelevel/kittens) libraries. + + +#### Tuples + +~~~ scala +List(1, 2, 3).map(Some.apply) // works + +("Hello", 2, 'u').map(Some.apply) // error: +// Found: Any => Some[Any], Required: [t] => (t) => Nothing +~~~ + +As tuples are becoming a powerful part of metaprogramming through `Mirror` instances, we expect these kinds of cases to become more and more frequent. + +#### Shapeless ([source](https://github.com/typelevel/shapeless-3/blob/8b1bbc651618e77e0bd7c2433b79e46adafa4506/modules/deriving/src/test/scala/shapeless3/deriving/type-classes.scala#L651-L665)) + + +In the shapeless library, polymorphic functions are used relatively often, but they are usually small and unique, making them not very suitable for refactoring. +There is however the following case, where a function is very large: + +~~~ scala +... + def readElems(s: String): Option[(T, String)] = { + type Acc = (String, Seq[String], Boolean) + inst.unfold[Acc]((s, labelling.elemLabels, true))( + [t] => (acc: Acc, rt: Read[t]) => { + val (s, labels, first) = acc + (for { + (_, tl0) <- if(first) Some(("", s)) else head(s, "(,)(.*)".r) + (_, tl1) <- head(tl0, s"(${labels.head}):(.*)".r) + (t, tl2) <- rt.read(tl1) + } yield (t, tl2)) match { + case Some(t, tl2) => ((tl2, labels.tail, false), Some(t)) + case None => ((s, labels, first), None) + } + } + ) match { + case (s, None) => None + case (acc, Some(t)) => Some((t, acc._1)) + } + } +~~~ + +By factoring out the function, it is possible to make the code more readable: + +~~~ scala +... + def readElems(s: String): Option[(T, String)] = { + type Acc = (String, Seq[String], Boolean) + val unfolder = [t] => (acc: Acc, rt: Read[t]) => { + val (s, labels, first) = acc + (for { + (_, tl0) <- if(first) Some(("", s)) else head(s, "(,)(.*)".r) + (_, tl1) <- head(tl0, s"(${labels.head}):(.*)".r) + (t, tl2) <- rt.read(tl1) + } yield (t, tl2)) match { + case Some(t, tl2) => ((tl2, labels.tail, false), Some(t)) + case None => ((s, labels, first), None) + } + } + inst.unfold[Acc]((s, labelling.elemLabels, true))(unfolder) match { + case (s, None) => None + case (acc, Some(t)) => Some((t, acc._1)) + } + } +~~~ + +It is natural at this point to want to transform the function into a method, as the syntax for the latter is more familiar, and more readable: + +~~~ scala +... + def readElems(s: String): Option[(T, String)] = { + type Acc = (String, Seq[String], Boolean) + def unfolder[T](acc: Acc, rt: Read[T]): Acc = { + val (s, labels, first) = acc + (for { + (_, tl0) <- if(first) Some(("", s)) else head(s, "(,)(.*)".r) + (_, tl1) <- head(tl0, s"(${labels.head}):(.*)".r) + (t, tl2) <- rt.read(tl1) + } yield (t, tl2)) match { + case Some(t, tl2) => ((tl2, labels.tail, false), Some(t)) + case None => ((s, labels, first), None) + } + } + inst.unfold[Acc]((s, labelling.elemLabels, true))(unfolder) match { + case (s, None) => None + case (acc, Some(t)) => Some((t, acc._1)) + } + } +~~~ + +However, this does not compile. +Only monomorphic eta-expansion is applied, leading to the same issue as with our previous `Tuple.map` example. + +#### Kittens ([source](https://github.com/typelevel/kittens/blob/e10a03455ac3dd52096a1edf0fe6d4196a8e2cad/core/src/main/scala-3/cats/derived/DerivedTraverse.scala#L44-L48)) + +In `Kittens`, there is a case of particularly obvious eta-expansion done by hand (comments by me): + +~~~ scala +... + final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B]) + (using G: Applicative[G]): G[F[B]] = + val pure = [a] => (x: a) => G.pure(x) // eta-expansion + val map = [a, b] => (ga: G[a], f: a => b) => G.map(ga)(f) // ~eta-expansion + val ap = [a, b] => (gf: G[a => b], ga: G[a]) => G.ap(gf)(ga) // ~eta-expansion + inst.traverse[A, G, B](fa)(map)(pure)(ap)([f[_]] => (tf: T[f], fa: f[A]) => tf.traverse(fa)(f)) + +~~~ + +Sadly since `map` and `ap` are curried, assuming this proposal, only `pure` can be eliminated: + +~~~ scala +... + final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B]) + (using G: Applicative[G]): G[F[B]] = + val map = [a, b] => (ga: G[a], f: a => b) => G.map(ga)(f) + val ap = [a, b] => (gf: G[a => b], ga: G[a]) => G.ap(gf)(ga) + inst.traverse[A, G, B](fa)(map)(G.pure)(ap)([f[_]] => (tf: T[f], fa: f[A]) => tf.traverse(fa)(f)) + +~~~ + +This already helps with readability, but we can postulate that given cases like this, an uncurried variant of `map` and `ap` would be implemented, allowing us to write: + +~~~ scala +... + final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B]) + (using G: Applicative[G]): G[F[B]] = + inst.traverse[A, G, B](fa)(G.map)(G.pure)(G.ap)([f[_]] => (tf: T[f], fa: f[A]) => tf.traverse(fa)(f)) +~~~ + +If wanted, we can then factor the function into a method: + +~~~ scala +... + final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B]) + (using G: Applicative[G]): G[F[B]] = + def traverser[F[_]](tf: T[F], fa: F[A]) = tf.traverse(fa)(f) + inst.traverse[A, G, B](fa)(G.map)(G.pure)(G.ap)(traverser) +~~~ + +## Proposed solution + + + +### High-level overview + +As the previous section already describes how polymorphic eta-expansion affects the examples, we will use this section to give quantity of small, illustrative, examples, that should cover most of the range of this proposal. + +In the following `id'` means a copy of `id` with a fresh name, and `//reminder:` sections are unchanged by this proposal. +#### Explicit parameters: +~~~ scala +def f1[A](x: A): A = ??? +val v1_1: [B] => B => B = f1 // f1 becomes [B'] => (y: B') => f1[B'](y) + +def f2[A]: A => A = ??? +val v2_1: [B] => B => B = f2 // f2 becomes [B'] => (y: B') => f2[B'](y) + +type F[C] = C => C +def f3[A]: F[A] = ??? +val v3_1: [B] => B => B = f3 // f3 becomes [B'] => (y: B') => f3[B'](y) + +//reminder: +val vErr: [B] => B = ??? // error: polymorphic function types must have a value parameter +~~~ + +#### Extension/Interleaved method: +~~~ scala +extension (x: Int) + def extf1[A](x: A): A = ??? + +val extv1_1: [B] => B => B = extf1(4) // extf1(4) becomes [B'] => (y: B') => extf1(4)[B'](y) + +val extv1_3: Int => [B] => B => B = extf1 // extf1 becomes (i: Int) => [B'] => (y: B') => extf1(i)[B'](y) + +// See https://docs.scala-lang.org/sips/clause-interleaving.html +def interleaved(key: Key)[V >: key.Value](default: V): V = ??? +val someKey: Key = ??? +val interleaved_1: [A >: someKey.Value] => A => A = interleaved(someKey) +// interleaved(someKey) becomes [A' >: someKey.Value] => (default: A') => interleaved(someKey)[A'](default) +~~~ + +#### Implicit parameters: +~~~ scala +def uf1[A](using x: A): A = ??? +val vuf1_1: [B] => B ?=> B = uf1 // uf1 becomes [B'] => (y: B') ?=> uf1[B'] + + +def uf2[A]: A = ??? +val vuf2: [B] => B ?=> B = uf2 // uf2 becomes [B'] => (y: B') ?=> uf2[B'] + +//reminder: +val get: (String) ?=> Int = 22 // 22 becomes (s: String) ?=> 22 +val err: () ?=> Int = ?? // error: context functions require at least one parameter +~~~ + +### Specification + + + +Before we go on, it is important to clarify what we mean by "polymorphic method", we do not mean, as one would expect, "a method taking at least one type parameter clause", but rather "a (potentially partially applied) method whose next clause is a type clause", here is an example to illustrate: + +~~~ scala +extension (x: Int) + def poly[T](x: T): T = x +// signature: (Int)[T](T): T + +poly(4) // polymorphic method: takes a [T] +poly // monomorphic method: takes an (Int) +~~~ + +Note: Since typechecking is recursive, eta-expansion of a monomorphic method like `poly` can still trigger polymorphic eta-expansion, for example: + +~~~ scala +val voly: Int => [T] => T => T = poly +// poly expands to: (x: Int) => [T] => (y: T) => poly(x)[T](y) +~~~ + +As this feature only provides a shortcut to express already definable objects, the only impacted area is the type system. + +When typing a polymorphic method `m` there are two cases to consider: + +#### Polymorphic expected type +If the expected type is a polymorphic function taking `[T_1 <: U_1 >: L_1, ..., T_n <: U_n >: L_n]` as type parameters, `(A_1, ..., A_k)` as term parameters and returning `R`, we proceed as follows: + +Note: Polymorphic functions always take term parameters (but `k` can equal zero if the clause is explicit: `[T] => () => T`). + +1. Copies of `T_i`s are created, and replaced in `U_i`s, `L_i`s, `A_i`s and `R`, noted respectively `T'_i`, `U'_i`, `L'_i`, `A'_i` and `R'`. + +2. Is the expected type a polymorphic context function ? +* 1. If yes then `m` is replaced by the following: +~~~ scala +[T'_1 <: U'_1 >: L'_1, ... , T'_n <: U'_n >: L'_n] + => (a_1: A'_1 ..., a_k: A'_k) + ?=> m[T'_1, ..., T'_n] +~~~ +* 2. If no then `m` is replaced by the following: +~~~ scala +[T'_1 <: U'_1 >: L'_1, ... , T'_n <: U'_n >: L'_n] + => (a_1: A'_1 ..., a_k: A'_k) + => m[T'_1, ..., T'_n](a_1, ..., a_k) +~~~ + +3. the application of `m` is type-checked with expected type `R'` +* 1. If it succeeds, the above is the created tree. +* 2. If it fails, go to Default. + +At 3.ii. if the cause of the error is such that [Non-polymorphic expected type](#non-polymorphic-expected-type) will never succeed, we might return that error directly, this is at the discretion of the implementation, to make errors as clear as possible. + +Note: Type checking will be in charge of overloading resolution, as well as term inference, so the following will work: +~~~ scala +def f[A](using Int)(x: A)(using String): A +def f[B](x: B, y: B): B + +given i: Int = ??? +given s: String = ??? +val v: [T] => T => T = f +// f expands to: [T'] => (t: T') => f[T'](t) +// and then to: [T'] => (t: T') => f[T'](using i)(t)(using s) + +def g[C](using C): C +val vg: [T] => T ?=> T = g +// g expands to: [T'] => (t: T') ?=> g[T'] +// and then to: [T'] => (t: T') ?=> g[T'](using t) +~~~ + +Note: Type checking at 3. will have to recursively typecheck `m[T'_1, ..., T'_n](a_1, ..., a_k)` with expected type `R`, this can lead to further eta-expansion: +~~~ scala +extension [A](x: A) + def foo[B](y: B) = (x, y) + +val voo: [T] => T => [U] => U => (T, U) = foo +// foo expands to: +// [T'] => (t: T') => ( foo[T'](t) with expected type [U] => U => (T', U) ) +// [T'] => (t: T') => [U'] => (u: U') => foo[T'](t)[U'](u) +~~~ + +#### Non-polymorphic expected type + +No polymorphic eta-expansion is performed, this corresponds to the old behaviour, written here as a reminder: + +Fresh variables are applied to `m`, typing constraints are generated, and typing continues, for example: + +~~~ scala +def ident[T](x: T): T = x + +val idInt: Int => Int = ident +// ident becomes: +// ident[X] with expected type Int => Int +// (x: X) => ident[X](x) of type X => X with expected type Int => Int +// therefore X := Int +// (x: Int) => ident[Int](x) +~~~ + +### Compatibility + + + +#### Binary and TASTy + +As this proposal never generates code that couldn't have been written by hand before, these changes are binary and TASTy compatible. + +#### Source + +This proposal conserves source compatibility when a non-polymorphic expected type is present, or when there is no expected type, since by definition the behaviour is the same. + +In the case the expected type is polymorphic, either the code did not compile before, or there was an implicit conversion from the inferred monomorphic function to the expected polymorphic function. In the latter case, source compatibility is broken, since polymorphic eta-expansion will apply before search for implicit conversions, for example: + +```scala +import scala.language.implicitConversions + +given conv: Conversion[Any => Any, [T] => T => T] = f => ([T] => (x: T) => x) + +def method[T](x: T): T = x + +val function: [T] => T => T = method +// before: method is eta-expanded to Any => Any, and then converted using conv to [T] => T => T +// now: method is eta-expanded to [T] => T => T (conv is not called) +``` + +### Restrictions + +Not included in this proposal are: + +* Applying polymorphic eta-expansion when there is no return type +* Expanding `[T] => T => T` to `[T] => T => Id[T]` to make `tuple.map(identity)` work (might work out of the box anyways, but not guaranteed) +* Expanding `x => x` to `[T] => (x: T) => x` if necessary (and generalizations) +* Expanding `_` to `[T] => (x: T) => x` if necessary (and generalizations) +* Polymorphic SAM conversion +* Polymorphic functions from wildcard: `foo[_](_)` + +While all of the above could be argued to be valuable, we deem they are out of the scope of this proposal. + +We encourage the creation of follow-up proposals to motivate their inclusion. + + + +### Open questions + + + + + + +## Related work + + + +* Pre-SIP: https://contributors.scala-lang.org/t/polymorphic-eta-expansion/5516 +* A naive implementation can be found at https://github.com/scala/scala3/pull/14015 (it is more general than this proposal and thus breaks compatibility) +* A compatibility-preserving implementation is in development. + + +## FAQ + + diff --git a/_sips/sips/precise-type-modifier.md b/_sips/sips/precise-type-modifier.md new file mode 100644 index 0000000000..9c316bbd8c --- /dev/null +++ b/_sips/sips/precise-type-modifier.md @@ -0,0 +1,6 @@ +--- +title: SIP-48 - Precise Type Modifier +status: withdrawn +pull-request-number: 48 + +--- diff --git a/_sips/sips/2017-02-07-priority-based-infix-type-precedence.md b/_sips/sips/priority-based-infix-type-precedence.md similarity index 82% rename from _sips/sips/2017-02-07-priority-based-infix-type-precedence.md rename to _sips/sips/priority-based-infix-type-precedence.md index 95c73ab90d..a67d84dbb5 100644 --- a/_sips/sips/2017-02-07-priority-based-infix-type-precedence.md +++ b/_sips/sips/priority-based-infix-type-precedence.md @@ -1,9 +1,8 @@ --- layout: sip -discourse: true title: SIP-33 - Priority-based infix type precedence - -vote-status: complete +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/priority-based-infix-type-precedence.html --- @@ -19,7 +18,7 @@ redirect_from: /sips/pending/priority-based-infix-type-precedence.html | Feb 10th 2017 | Updates from feedback | | Aug 8th 2017 | Numbered SIP, improve view, fixed example, and added related issues | | Oct 20th 2017 | Added implementation link | -| Oct 25th 2017 | Moved prefix types to [another SIP](http://docs.scala-lang.org/sips/adding-prefix-types.html), changed title and PR | +| Oct 25th 2017 | Moved prefix types to [another SIP](https://github.com/scala/improvement-proposals/pull/35), changed title and PR | | Nov 29th 2017 | Updated SIP according to feedback in the PR | @@ -29,7 +28,7 @@ Your feedback is welcome! If you're interested in discussing this proposal, head ## Introduction Currently scala allows symbol operators (`-`, `*`, `~~>`, etc.) for both type names and definition names. -Unfortunately, there is a 'surprise' element since the two differ in behavior. While infix types are 'mostly' left-associative, the expression operation precedence is determined by the operator's first character (e.g., `/` is precedent to `+`). Please see [Infix Types](http://scala-lang.org/files/archive/spec/2.12/03-types.html#infix-types) and [Infix Operations](http://scala-lang.org/files/archive/spec/2.12/06-expressions.html#infix-operations) sections of the Scala specifications for more details. +Unfortunately, there is a 'surprise' element since the two differ in behavior. While infix types are 'mostly' left-associative, the expression operation precedence is determined by the operator's first character (e.g., `/` is precedent to `+`). Please see [Infix Types](https://scala-lang.org/files/archive/spec/2.12/03-types.html#infix-types) and [Infix Operations](https://scala-lang.org/files/archive/spec/2.12/06-expressions.html#infix-operations) sections of the Scala specifications for more details. **Infix expression precedence vs. infix type precedence example**: @@ -76,7 +75,7 @@ No documentation available to prove this, but the infix example above works perf Dotty has no prefix types, same as Scalac. #### Singleton-ops library example -The [singleton-ops library](https://github.com/fthomas/singleton-ops) with [Typelevel Scala](https://github.com/typelevel/scala) (which implemented [SIP-23](http://docs.scala-lang.org/sips/pending/42.type.html)) enable developers to express literal type operations more intuitively. For example: +The [singleton-ops library](https://github.com/fthomas/singleton-ops) with [Typelevel Scala](https://github.com/typelevel/scala) (which implemented [SIP-23](https://docs.scala-lang.org/sips/pending/42.type.html)) enable developers to express literal type operations more intuitively. For example: ```scala import singleton.ops._ @@ -104,7 +103,7 @@ val fails : 1 + 2 * 3 + 4 = 11 //left associative:(((1+2)*3)+4))) = 13 ``` #### Developer issues example -[This](http://stackoverflow.com/questions/23333882/scala-infix-type-aliasing-for-2-type-parameters) stackoverflow question demonstrate developers are 'surprised' by the difference in infix precedence, expecting infix type precedence to act the same as expression operations. +[This](https://stackoverflow.com/questions/23333882/scala-infix-type-aliasing-for-2-type-parameters) Stack Overflow question demonstrate developers are 'surprised' by the difference in infix precedence, expecting infix type precedence to act the same as expression operations. --- @@ -122,9 +121,9 @@ A PR for this SIP is available at: [https://github.com/scala/scala/pull/6147](ht ### Interactions with other language features -#### Star `*` infix type interaction with repeated parameters -The [repeated argument symbol `*`](https://www.scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#repeated-parameters) may create confusion with the infix type `*`. -Please note that this feature interaction already exists within the current specification. +#### Star `*` infix type interaction with repeated parameters +The [repeated argument symbol `*`](https://www.scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#repeated-parameters) may create confusion with the infix type `*`. +Please note that this feature interaction already exists within the current specification. ```scala trait +[N1, N2] @@ -138,11 +137,11 @@ However, it is very unlikely that such interaction would occur. **Related Issues** -* [Dotty Issue #1961](https://github.com/lampepfl/dotty/issues/1961) +* [Dotty Issue #1961](https://github.com/scala/scala3/issues/1961) ## Backward Compatibility -Changing infix type associativity and precedence affects code that uses type operations and conforms to the current specification. +Changing infix type associativity and precedence affects code that uses type operations and conforms to the current specification. Note: changing the infix precedence didn't fail any scalac test. diff --git a/_sips/sips/quote-pattern-type-variable-syntax.md b/_sips/sips/quote-pattern-type-variable-syntax.md new file mode 100644 index 0000000000..64f58fafb8 --- /dev/null +++ b/_sips/sips/quote-pattern-type-variable-syntax.md @@ -0,0 +1,145 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: completed +status: shipped +title: SIP-53 - Quote pattern explicit type variable syntax +--- + +**By: Nicolas Stucki** + +## History + +| Date | Version | +|---------------|--------------------| +| Feb 28th 2022 | Initial Draft | +| Oct 6th 2022 | [Stabilize implementation](https://github.com/scala/scala3/pull/18574) | +| Feb 29th 2023 | Available in [Scala 3.4.0](https://www.scala-lang.org/blog/2024/02/29/scala-3.4.0-and-3.3.3-released.html) | + +## Summary + +This SIP proposes additions to the syntax of type variable definitions to bring quoted type matching to par with quoted expression matching. +Specifically, the ability to declare type variables explicitly and define them with bounds. + +It also proposes some enhancements to make the use of type variables simpler. +The idea is to reduce the number of cases where we need to write backticks around type variable name references. +Namely when using explicit type variable definitions. + +## Motivation + +### Background + +* [Reference Documentation](http://dotty.epfl.ch/docs/reference/metaprogramming/macros.html#type-variables) + +Quoted expressions support two ways of defining type variables: explicit and nested. + +##### Explicit type variables +The initial `type` declarations in the pattern with a type variable name (lowercase names as with normal pattern type variables) are type variable definitions. Type variable references need to be in backticks. Otherwise, we assume they are nested type variables and emit an error. These definitions can have bounds defined on them. +```scala +case '{ type t; $x: `t` } => f[t](x: Expr[t]) +case '{ type u; ($ls: List[`u`]).map($f: `u` => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int]) +case '{ type tail <: Tuple; $x: *:[Int, `tail`] } => h[tail](x: Expr[*:[Int, tail]) +``` + +##### Nested type variable +Types with a type variable name introduce a new type variable. These cannot be references with a backticked reference due to their scope. We cannot add explicit bounds to them, but in certain cases we can infer their some bounds. These variables become explicit type variables in the internal representation after typing. +```scala +case '{ $x: t } => f[t](x: Expr[t]) +``` + + +##### Type Patterns +Quoted type patterns only support nested type variable definitions. Explicit type variables are not supported in the source due to an oversight. These variables become explicit type variables in the internal representation after typing. The bounds of the type variable are `Any` and `Nothing`. +```scala +case '[ t ] => f[t] +case '[ List[t] ] => g[t] +``` + +### Support type bounds in quoted type patterns + +We want to be able to set the bounds of type variables to be able to match against type constructors that have type bounds. For example, the tuple `*:` type. +```scala +case '[ head *: tail ] => h[tail] +``` +See [https://github.com/scala/scala3/issues/11738](https://github.com/scala/scala3/issues/11738). + +### Support matching on any kind of type +We want to match against higher-kinded (or `AnyKind`) types. This is not possible due to the default upper bound of `Any`. +See [https://github.com/scala/scala3/issues/10864](https://github.com/scala/scala3/issues/10864). + +### Support multiple references to the same type in quoted type patterns +We want to be able to match using several references to the same type variable. +```scala +case '[ (t, t, t) ] => f[t] // t is going to match the glb of the tuple T1, T2, T3 +``` + +### Simplify the use of explicit type variables +It is inconsistent to need to use backticks for references to explicit type variables in the quote but not outside. +We want to be able to refer to the variable by its non-backticked name uniformly. +```diff +- case '{ type u; ($ls: List[`u`]).map($f: `u` => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int]) ++ case '{ type u; ($ls: List[u]).map($f: u => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int]) +``` + +## Proposed solution + +### High-level overview + +We first want to introduce syntax for explicit type variable definitions in quoted type patterns that aligns with expression quoted patterns. We can use the syntax described in [explicit type variables](#explicit-type-variables). + +```scala +case '[ type t; List[`t`] ] => f[t] +case '[ type tail <: Tuple; *:[Int, `tail`] ] => g[tail] +``` + +Second, we want the remove the need for backticks for references to explicit type variable definitions. If we have an explicit type variable definition and a type variable with the same name, we can syntactically assume these are the same and not introduce a new nested type variable. +```scala +case '{ type t; $x: t } => f[t](x: Expr[t]) +case '{ type u; ($ls: List[u]).map($f: u => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int]) +case '{ type tail <: Tuple; $x: *:[Int, tail] } => h[tail](x: Expr[*:[Int, tail]) +``` +```scala +case '[ type t; List[t] ] => f[t] +case '[ type tail <: Tuple; *:[Int, tail] ] => g[tail] +``` + +### Specification + +Adding the explicit type variable definition to quoted type patterns is relatively straightforward as nested type variables become explicit ones internally. We would only need to update the parser to accept a new kind of type in the syntax. This type would only be used in the quote type pattern syntax, which is self-contained in the language's grammar. + +```diff +Quoted ::= ‘'’ ‘{’ Block ‘}’ +- | ‘'’ ‘[’ Type ‘]’ ++ | ‘'’ ‘[’ TypeBlock ‘]’ ++TypeBlock ::= {TypeBlockStat semi} Type ++TypeBlockStat ::= ‘type’ {nl} TypeDcl +``` + +Allowing non-backticked references to explicit type variable definitions would not create any conflict, as these would currently cause a double definition error. The grammar would not need to change. This would only interact with the process of typing quoted patterns. + +### Compatibility + +There are no compatibility issues because the parser or typer rejected all these cases. + +TASTy only contains explicit type variable definitions, and this encoding would not change. Note that TASTy supports _type blocks_ using the regular `Block` AST. These contain type declaration in their statements and a type instead of the expression. + +### Other concerns + +* Tools that parse Scala code must be updated with this new grammar. +* Tools that use TASTy would not be affected. + + + +## Alternatives + +* We could find a different syntax for explicit type variables in quoted type patterns. The drawback is that we need to specify and explain a secondary syntax. +* Don't include the backticks improvements. + +## Related work + +* Proof of concept of type variable syntax: [https://github.com/scala/scala3/pull/16910](https://github.com/scala/scala3/pull/16910) +* Proof of concept of backticks (only interested in the first bullet point): [https://github.com/scala/scala3/pull/16935](https://github.com/scala/scala3/pull/16935) +* Implementation: [https://github.com/scala/scala3/pull/17362](https://github.com/scala/scala3/pull/17362) +* Stabilized implementation: [https://github.com/scala/scala3/pull/18574](https://github.com/scala/scala3/pull/18574) + + diff --git a/_sips/sips/repeated-by-name-parameters.md b/_sips/sips/repeated-by-name-parameters.md new file mode 100644 index 0000000000..6949fcf87c --- /dev/null +++ b/_sips/sips/repeated-by-name-parameters.md @@ -0,0 +1,6 @@ +--- +title: SIP-24 - Repeated By Name Parameters +status: withdrawn +pull-request-number: 23 + +--- diff --git a/_sips/sips/replace-nonsensical-unchecked-annotation.md b/_sips/sips/replace-nonsensical-unchecked-annotation.md new file mode 100644 index 0000000000..3bb8609940 --- /dev/null +++ b/_sips/sips/replace-nonsensical-unchecked-annotation.md @@ -0,0 +1,260 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: implementation +status: under-review +presip-thread: https://contributors.scala-lang.org/t/pre-sip-replace-non-sensical-unchecked-annotations/6342 +title: SIP-57 - Replace non-sensical @unchecked annotations +--- + +**By: Martin Odersky and Jamie Thompson** + +## History + +| Date | Version | +|---------------|--------------------| +| Dec 8th 2023 | Initial Draft | +| Jan 19th 2024 | Clarification about current @unchecked behavior | + +## Summary + +We propose to replace the mechanism to silence warnings for "unchecked" patterns, in the cases where silencing the warning will still result in the pattern being checked at runtime. + +Currently, a user can silence warnings that a scrutinee may not be matched by a pattern, by annotating the scrutinee with the `@unchecked` annotation. This SIP proposes to use a new annotation `@RuntimeCheck` to replace `@unchecked` for this purpose. For convenience, an extension method will be added to `Predef` that marks the receiver with the annotation (used as follows: `foo.runtimeCheck`). Functionally it behaves the same as the old annotation, but improves readability at the callsite. + +## Motivation + +As described in [Scala 3 Reference: Pattern Bindings](https://docs.scala-lang.org/scala3/reference/changed-features/pattern-bindings.html), under `-source:future` it is an error for a pattern definition to be refutable. For instance, consider: +```scala +def xs: List[Any] = ??? +val y :: ys = xs +``` + +This compiled without warning in 3.0, became a warning in 3.2, and we would like to make it an error by default in a future 3.x version. +As an escape hatch we recommend to use `@unchecked`: +``` +-- Warning: ../../new/test.scala:6:16 ------------------------------------------ +6 | val y :: ys = xs + | ^^ + |pattern's type ::[Any] is more specialized than the right hand side expression's type List[Any] + | + |If the narrowing is intentional, this can be communicated by adding `: @unchecked` after the expression, + |which may result in a MatchError at runtime. +``` +Similarly for non-exhaustive `match` expressions, where we also recommend to put `@unchecked` on the scrutinee. + +But `@unchecked` has several problems. First, it is ergonomically bad. For instance to fix the exhaustivity warning in +```scala +xs match + case y :: ys => ... +``` +we'd have to write +``` +(xs: @unchecked) match + case y :: ys => ... +``` +Having to wrap the `@unchecked` in parentheses requires editing in two places, and arguably harms readability: both due to the churn in extra symbols, and because in this use case the `@unchecked` annotation poorly communicates intent. + +Nominally, the purpose of the annotation is to silence warnings (_from the [API docs](https://www.scala-lang.org/api/3.3.1/scala/unchecked.html#)_): +> An annotation to designate that the annotated entity should not be considered for additional compiler checks. + +_The exact meaning of this description is open to interpretation, leading to differences between Scala 2.13 and Scala 3.x. See the [misinterpretation](#misinterpretation-of-unchecked) annex for more._ + + +In the following code however, the word `unchecked` is a misnomer, so could be confused for another meaning by an inexperienced user: + +```scala +def xs: List[Any] = ??? +val y :: ys = xs: @unchecked +``` + After all, the pattern `y :: ys` _is_ checked, but it is done at runtime (by looking at the runtime class), rather than statically. + +As a direct contradiction, in the following usage of `unchecked`, the meaning is the opposite: +```scala +xs match + case ints: List[Int @unchecked] => +``` +Here, `@unchecked` means that the `Int` parameter will _not_ be checked at runtime: The compiler instead trusts the user that `ints` is a `List[Int]`. This could lead to a `ClassCastException` in an unrelated piece of code that uses `ints`, possibly without leaving a clear breadcrumb trail of where the faulty cast originally occurred. + +## Proposed solution + +### High-level overview + +This SIP proposes to fix the ergnomics and readability of `@unchecked` in the usage where it means "checked at runtime", by instead adding a new annotation `scala.internal.RuntimeCheck`. + +```scala +package scala.annotation.internal + +final class RuntimeCheck extends Annotation +``` + +In all usages where the compiler looks for `@unchecked` for this purpose, we instead change to look for `@RuntimeCheck`. + +By placing the annotation in the `internal` package, we communicate that the user is not meant to directly use the annotation. + +Instead, for convenience, we provide an extension method `Predef.runtimeCheck`, which can be applied to any expression. + +The new usage to assert that a pattern is checked at runtime then becomes as follows: +```scala +def xs: List[Any] = ??? +val y :: ys = xs.runtimeCheck +``` + +We also make `runtimeCheck` a transparent inline method. This ensures that the elaboration of the method defines its semantics. (i.e. `runtimeCheck` is not meaningful because it is immediately inlined at type-checking). + +### Specification + +The addition of a new `scala.Predef` method: + +```scala +package scala + +import scala.annotation.internal.RuntimeCheck + +object Predef: + extension [T](x: T) + transparent inline def runtimeCheck: x.type = + x: @RuntimeCheck +``` + +### Compatibility + +This change carries the usual backward binary and TASTy compatibility concerns as any other standard library addition to the Scala 3 only library. + +Considering backwards source compatibility, the following situation will change: + +```scala +// source A.scala +package example + +extension (predef: scala.Predef.type) + transparent inline def runtimeCheck[T](x: T): x.type = + println("fake runtimeCheck") + x +``` +```scala +// source B.scala +package example + +@main def Test = + val xs = List[Any](1,2,3) + val y :: ys = Predef.runtimeCheck(xs) + assert(ys == List(2, 3)) +``` + +Previously this code would print `fake runtimeCheck`, however with the proposed change then recompiling this code will _succeed_ and no longer will print. + +Potentially we could mitigate this if necessary with a migration warning when the new method is resolved (`@experimental` annotation would be a start) + + +In general however, the new `runtimeCheck` method will not change any previously linking method without causing an ambiguity compilation error. + +### Other concerns + +In 3.3 we already require the user to put `@unchecked` to avoid warnings, there is likely a significant amount of existing code that will need to migrate to the new mechanism. (We can leverage already exisiting mechanisms help migrate code automatically). + +### Open questions + +1) A large question was should the method or annotation carry semantic weight in the language. In this proposal we weigh towards the annotation being the significant element. +The new method elaborates to an annotated expression before the associated pattern exhaustivity checks occur. +2) Another point, where should the helper method go? In Predef it requires no import, but another possible location was the `compiletime` package. Requiring the extra import could discourage usage without consideration - however if the method remains in `Predef` the name itself (and documentation) should signal danger, like with `asInstanceOf`. + +3) Should the `RuntimeCheck` annotation be in the `scala.annotation.internal` package? + +### Misinterpretation of unchecked + +We would further like to highlight that the `unchecked` annotation is unspecified except for its imprecise API documentation. This leads to a crucial difference in its behavior between Scala 2.13 and the latest Scala 3.3.1 release. + +#### Scala 3 semantics + +Say you have the following: +```scala +val xs = List(1: Any) +``` + +The following expression in Scala 3.3.1 yields two warnings: +```scala +xs match { + case is: ::[Int] => is.head +} +``` + +```scala +2 warnings found +-- [E029] Pattern Match Exhaustivity Warning: ---------------------------------- +1 |xs match { + |^^ + |match may not be exhaustive. + | + |It would fail on pattern case: List(_, _*), Nil + | + | longer explanation available when compiling with `-explain` +val res0: Int = 1 +-- Unchecked Warning: ---------------------------------------------------------- +2 | case is: ::[Int] => is.head + | ^ + |the type test for ::[Int] cannot be checked at runtime because its type arguments can't be determined from List[Any] +``` + +using `@unchecked` on `xs` has the effect of silencing any warnings that depend on checking `xs`, so no warnings will be emitted for the following change: + +```scala +(xs: @unchecked) match { + case is: ::[Int] => is.head +} +``` + +#### Scala 2.13 semantics + +However, in Scala 2.13, this will only silence the `match may not be exhaustive` warning, and the user will still see the `type test for ::[Int] cannot be checked at runtime` warning: + +```scala +scala> (xs: @unchecked) match { + | case is: ::[Int] => is.head + | } ^ +On line 2: warning: non-variable type argument Int in type pattern scala.collection.immutable.::[Int] (the underlying of ::[Int]) is unchecked since it is eliminated by erasure +val res2: Int = 1 +``` + +#### Aligning to Scala 2.13 semantics with runtimeCheck + +with `xs.runtimeCheck` we should still produce an unchecked warning for `case is: ::[Int] =>` +```scala +scala> xs.runtimeChecked match { + | case is: ::[Int] => is.head + | } +1 warning found +-- Unchecked Warning: ---------------------------------------------------------- +2 | case is: ::[Int] => is.head + | ^ + |the type test for ::[Int] cannot be checked at runtime because its type arguments can't be determined from List[Any] +val res13: Int = 1 +``` +This is because `xs.runtimeChecked` means trust the user as long as the pattern can be checked at runtime. + +To fully avoid warnings, the `@unchecked` will be put on the type argument: +```scala +scala> xs.runtimeChecked match { + | case is: ::[Int @unchecked] => is.head + | } +val res14: Int = 1 +``` +This has a small extra migration cost because if the scrutinee changes from `(xs: @unchecked)` to `xs.runtimeCheck` now some individual cases might need to add `@unchecked` on type arguments to avoid creating new warnings - however this cost is offset by perhaps revealing unsafe patterns previously unaccounted for. + +Once again `@nowarn` can be used to fully restore any old behavior + +## Alternatives + +1) make `runtimeCheck` a method on `Any` that returns the receiver (not inline). The compiler would check for presence of a call to this method when deciding to perform static checking of pattern exhaustivity. This idea was criticised for being brittle with respect to refactoring, or automatic code transformations via macro. + +2) `runtimeCheck` should elaborate to code that matches the expected type, e.g. to heal `t: Any` to `Int` when the expected type is `Int`. The problem is that this is not useful for patterns that can not be runtime checked by type alone. Also, it implies a greater change to the spec, because now `runtimeCheck` would have to be specially treated. + +## Related work + +- [Pre SIP thread](https://contributors.scala-lang.org/t/pre-sip-replace-non-sensical-unchecked-annotations/6342) +- [Scala 3 Reference: Pattern Bindings](https://docs.scala-lang.org/scala3/reference/changed-features/pattern-bindings.html), +- None of OCaml, Rust, Swift, or Java offer explicit escape hatches for non-exhaustive pattern matches (Haskell does not even warn by default). Instead the user must add a default case, (making it exhaustive) or use the equivalent of `@nowarn` when they exist. + +## FAQ + +N/A so far. diff --git a/_sips/sips/2017-07-12-right-associative-by-name-operators.md b/_sips/sips/right-associative-by-name-operators.md similarity index 96% rename from _sips/sips/2017-07-12-right-associative-by-name-operators.md rename to _sips/sips/right-associative-by-name-operators.md index bf85d747a7..3d247af33d 100644 --- a/_sips/sips/2017-07-12-right-associative-by-name-operators.md +++ b/_sips/sips/right-associative-by-name-operators.md @@ -1,13 +1,14 @@ --- layout: sip -discourse: true -title: SIP-34 - Right-Associative By-Name Operators - -vote-status: accepted +title: SIP-39 - Right-Associative By-Name Operators +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/right-associative-by-name-operators.html --- +> This proposal has been implemented in Scala 2.13.0 and Scala 3.0.0. + **By: Stefan Zeiger** ## History diff --git a/_sips/sips/2010-01-22-scala-2-8-arrays.md b/_sips/sips/scala-2-8-arrays.md similarity index 95% rename from _sips/sips/2010-01-22-scala-2-8-arrays.md rename to _sips/sips/scala-2-8-arrays.md index 407dc19bf1..7f5999d651 100644 --- a/_sips/sips/2010-01-22-scala-2-8-arrays.md +++ b/_sips/sips/scala-2-8-arrays.md @@ -1,13 +1,13 @@ --- layout: sip title: SID-7 - Scala 2.8 Arrays -vote-status: complete -vote-text: This SIP has already been accepted and completed. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/scala-2-8-arrays.html --- -*(This is an older SID, its original PDF can be found [here](http://www.scala-lang.org/sid/7))* +*(This is an older SID, its original PDF can be found [here](https://www.scala-lang.org/sid/7))* **Martin Odersky** @@ -26,8 +26,8 @@ First, there’s actually not a single array type representation in Java but nine different ones: One representation for arrays of reference type and another eight for arrays of each of the primitive types `byte`, `char`, `short`, `int`, `long`, `float`, `double`, and `boolean`. There is no common -type for these different representations which is more specific than just -`java.lang.Object`, even though there are some reflective methods to deal with +type for these different representations which is more specific than just +`java.lang.Object`, even though there are some reflective methods to deal with arrays of arbitrary type in `java.lang.reflect.Array`. Second, there’s no way to create an array of a generic type; only monomorphic array creations are allowed. Third, the only operations supported by arrays are indexing, updates, @@ -35,14 +35,14 @@ and get length. Contrast this with what we would like to have in Scala: Arrays should slot into the collections hierarchy, supporting the hundred or so methods that are -defined on sequences. And they should certainly be generic, so that one can +defined on sequences. And they should certainly be generic, so that one can create an `Array[T]` where `T` is a type variable. ### The Past How to combine these desirables with the representation restrictions imposed by Java interoperability and performance? There’s no easy answer, and I -believe we got it wrong the first time when we designed Scala. The Scala +believe we got it wrong the first time when we designed Scala. The Scala language up to 2.7.x “magically” wrapped and unwrapped arrays when required in a process called boxing and unboxing, similarly to what is done to treat primitive numeric types as objects. “Magically” means: the compiler generated @@ -89,7 +89,7 @@ proposal is that one would not normally refer to Scala native arrays in user code, just as one rarely referred to RichString in Scala. One would only rely on the implicit conversion to add the necessary methods and traits to Java arrays. Unfortunately, the String/RichString experience has shown that this is -also problematic. In par- ticular, in pre 2.8 versions of Scala, one had the +also problematic. In particular, in pre 2.8 versions of Scala, one had the non-intuitive property that "abc".reverse.reverse == "abc" //, yet @@ -281,5 +281,5 @@ three language features will be described in more detail in separate notes. 2. [Matt Malone. The mystery of the parameterized array. Blog, August 2009.][2] 3. David MacIver. Refactoring scala.array. Pre-SIP (Scala Improvement Proposal), October 2008. - [1]: http://www.drmaciver.com/2008/06/scala-arrays - [2]: http://oldfashionedsoftware.com/2009/08/05/the-mystery-of-the-parameterized-array + [1]: https://www.drmaciver.com/2008/06/scala-arrays + [2]: https://oldfashionedsoftware.com/2009/08/05/the-mystery-of-the-parameterized-array diff --git a/_sips/sips/scala-3-macro-annotations.md b/_sips/sips/scala-3-macro-annotations.md new file mode 100644 index 0000000000..497a56896e --- /dev/null +++ b/_sips/sips/scala-3-macro-annotations.md @@ -0,0 +1,7 @@ +--- +title: SIP-63 - Scala 3 Macro Annotations +status: under-review +pull-request-number: 80 +stage: design + +--- diff --git a/_sips/sips/scala-cli.md b/_sips/sips/scala-cli.md new file mode 100644 index 0000000000..de9aaece39 --- /dev/null +++ b/_sips/sips/scala-cli.md @@ -0,0 +1,681 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: completed +status: shipped +title: SIP-46 - Scala CLI as default Scala command +--- + +**By: Krzysztof Romanowski and Scala CLI team** + +## History + +| Date | Version | +|---------------|--------------------| +| July 15th 2022 | Initial Draft | + +## Summary + +We propose to replace current script that is installed as `scala` with Scala CLI - a batteries included tool to interact with Scala. Scala CLI brings all the features that the commands above provide and expand them with incremental compilation, dependency management, packaging and much more. + +Even though Scala CLI could replace `scaladoc` and `scalac` commands as well for now, we do not propose to replace them. + + +## Motivation + +The current default `scala` script is quite limited since it can only start repl or run pre-compile Scala code. + +The current script are lacking basic features such as support for resolving dependencies, incremental compilation or support for outputs other than JVM. This forces any user that wants to do anything more than just basic things to learn and use SBT, Mill or an other build tool and that adds to the complexity of learning Scala. + +We observe that the current state of tooling in Scala is limiting creativity, with quite a high cost to create e.g. an application or a script with some dependencies that target Node.js. Many Scala developers are not choosing Scala for their personal projects, scripts, or small applications and we believe that the complexity of setting up a build tool is one of the reasons. + +With this proposal our main goal is to turn Scala into a language with "batteries included" that will also respect the community-first aspect of our ecosystem. + +### Why decided to work on Scala CLI rather then improve existing tools like sbt or Mill? + +Firstly, Scala CLI is in no way an actual replacement for SBT or Mill - nor was it ever meant to be. We do not call it a build tool, even though it does share some similarities with build tools. It doesn't aim at supporting multi-module +projects, nor to be extended via a task system. The main advantages of SBT and Mill: multi-module support and plugin ecosystem in the use cases for Scala CLI and scala command can often be disadvantages as it affects performance: configuration needs to be compiled, plugins resolved etc. + +Mill and SBT uses turing complete configuration for build so the complexity of build scripts in theory is unlimited. Scala CLI is configuration-only and that limits the complexity what put a hard cap how complex Scala CLI builds can be. + +`scala` command should be first and foremost a command line tool. Requirements for a certain project structure or presence configuration files limit SBT and Mill usability certain use cases related to command line. + +One of the main requirements for the new `scala` commands was speed, flexibility and focus on command-line use cases. Initially, we were considering improving SBT or Mill as well as building Scala CLI on top one. We have quickly realized that getting Mill or SBT to reply within Milliseconds (for cases where no hard work like compilation is require) would be pretty much out of reach. Mill and SBT's codebases are too big to compile them to native image using GraalVM, not to mention problems with dynamic loading and reflection. Adding flexibility when in comes to input sources (e.g. support for Gists) and making the tool that can accept most of the configuration using simple command-line parameters would involve writhing a lot of glue code. That is why we decided to build the tool from scratch based on existing components like coursier, bloop or scalafmt. + +## Proposed solution + +We propose to gradually replace the current `scala`, `scalac` and `scaladoc` commands by single `scala` command that under the hood will be `scala-cli`. We could also add wrapper scripts for `scalac` and `scaladoc` that will mimic the functionality that will use `scala-cli` under the hood. + +The complete set of `scala-cli` features can be found in [its documentation](https://scala-cli.virtuslab.org/docs/overview). + +Scala CLI brings many features like testing, packaging, exporting to sbt / Mill or upcoming support for publishing micro-libraries. Initially, we propose to limit the set of features available in the `scala` command by default. Scala CLI is a relatively new project and we should battle-proof some of its features before we commit to support them as part of the official `scala` command. + +Scala CLI offers [multiple native ways to be installed](https://scala-cli.virtuslab.org/install#advanced-installation) so most users should find a suitable method. We propose that these packages to become the default `scala` package in most repositories, often replacing existing `scala` packages but the fact how new `scala` command would be installed is not intended to be a part of this SIP. + +### High-level overview + +Let us show a few examples where adopting Scala CLI as `scala` command would be a significant improvement over current scripts. For this, we have assumed a minimal set of features (described as MUST have and SHOULD have). Each additional Scala CLI feature included in the future, such as `package`, would add more and more use cases. + +**Using REPL with a 3rd-party dependency** + +Currently, to start a Scala REPL with a dependency on the class path, users need to resolve this dependency with all its transitive dependencies (coursier can help here) and pass those to the `scala` command using the `--cp` option. Alternatively, one can create an sbt project including a single dependency and use the `sbt console` task. Ammonite gives a better experience with its magic imports. + +With Scala CLI, starting a REPL with a given dependency is as simple as running: + +``` +scala-cli repl --dep com.lihaoyi::os-lib:0.7.8 +``` + +Compared to Ammonite, default Scala REPLs provided by Scala 2 and 3 - that Scala CLI uses by default - are somewhat limited. However, Scala CLI also offers to start Ammonite instead of the default Scala REPL, by passing `--ammonite` (or `--amm`) option to `scala-cli repl` but we do not propose to include `--ammonite` to the `scala` command not to commit to its maintenance. + +Additionally, `scala-cli repl` can also put code from given files / directories / snippets on the class path by just providing their locations as arguments. Running `scala-cli repl foo.scala baz` will compile code from `foo.scala` and the `baz` directory, and put their classes on the REPL class path (including their dependencies, scalac options etc. defined within those files). + +Compilation (and running scaladoc as well) benefit in a similar way from the ability to manage dependencies. + +** Providing reproductions of bugs ** + +Currently, when reporting a bug in the compiler (or any other Scala-related) repository, users need to provide dependencies, compiler options etc. in comments, create a repository containing a projet with a Mill / sbt configuration to reproduce. In general, testing the reproduction or working on further minimization is not straightforward. + +"Using directives", provided by Scala CLI give the ability to include the whole configuration in single file, for example: + +```scala +//> using platform "native" +//> using "com.lihaoyi::os-lib:0.7.8" +//> using options "-Xfatal-warnings" + +def foo = println("") +``` + +The snippet above when run with Scala CLI without any configuration provided will use Scala Native, resolve and include `os-lib` and provide `-Xfatal-warnings` to the compiler. Even things such as the runtime JVM version can be configured with using directives. + +Moreover, Scala CLI provides the ability to run GitHub gists (including multi-file ones), and more. + +** Watch mode ** + +When working on a piece of code, it is often useful to have it compiled/run every time the file is changed, and build tools offer a watch mode for that. This is how most people are using watch mode through a build tool. Scala CLI offers a watch mode for most of its commands (by using `--watch` / `-w` flags). + + +### Specification + + In order to be able to expand the functionality of Scala CLI and yet use the same core to power the `scala` command, we propose to include both `scala` and `scala-cli` commands in the installation package. Scala CLI already has a feature to limit accessible sub-commands based the binary name (all sub-commands in `scala-cli`, and a curated list in `scala`). On later date, more features from `scala-cli` could be included into `scala` command by additional SIPs or similar processes. + +These sub-commands MUST be included in the the specification of the new `scala` command: + + - compile: Compile Scala code + - doc: Generate Scaladoc documentation + - repl: Fire-up a Scala REPL + - run: Compile and run Scala code. + - shebang: Like `run`, but more handy from shebang scripts + +These sub-commands SHOULD be included in the the specification of the new `scala` command: + + - fmt: Format Scala code + - test: Compile and test Scala code + - version: Print `scala-cli` version + + +The subcommand that MAY be included in the specification of the new `scala` command. Those sub-commands are specific to implementation of Scala CLI and provide important, user-facing features like integration with IDE or cleaning up incremental compilation state: + + - about: Print details about this application + - bsp: Start BSP server + - clean: Clean the workspace + - doctor: Print details about this application + - help: Print help message + - install-completions: Installs completions into your shell + - install-home: Install `scala-cli` in a sub-directory of the home directory + - setup-ide: Generate a BSP file that you can import into your IDE + - uninstall: Uninstall scala-cli - only works when installed by the installation script + - uninstall-completions: Uninstalls completions from your shell + - update: Update scala-cli - only works when installed by the installation script + +Last section of this proposal is the list of options that each sub-command MUST HAVE and SHOULD HAVE for each sub-commands that MUST or SHOULD be included in the specification of the new `scala` command. The options that are specific to the implementation (MAY have) as well as options for implementation specific sub-commands (MAY have) are included in [full specification](https://romanowski.github.io/scala-cli/docs/reference/scala-command/runner-specification). + +Scala CLI can also be configured with ["using directives"](https://scala-cli.virtuslab.org/docs/guides/introduction/using-directives) - a comment-based configuration syntax that should be placed at the top of Scala files. This allows for self-containing examples within one file since most of the configuration can be provided either from the command line or via using directives (command line has precedence). This is a game changer for use cases like scripting, reproduction, or within the academic scope. + +We have described the motivation, syntax and implementation basis in the [dedicated pre-SIP](https://contributors.scala-lang.org/t/pre-sip-using-directives/5700). Currently, we recommend to write using directives as comments, so making them part of the language specification is not necessary at this stage. Moreover, the new `scala` command could ignore using directives in the initial version, however we strongly suggest to include comment-based using directives from the start. + +Last section of this proposal contains a sumamry of Using Directives syntax as well as list of directives that MUST and SHOULD be supported. + +### Compatibility + +Adopting Scala CLI as the new `scala` command, as is, will change some of the behavior of today's scripts. Some examples: + +- Scala CLI recognizes tests based on the extension used (`*.test.scala`) so running `scala compile a.scala a.test.scala` will only compile `a.scala` +- Scala CLI has its own versioning scheme, that is not related to the Scala compiler. Default version used may dynamically change when new Scala version is released. Similarly to Scala 3, we intend for Scala CLI to be backward compatible and this should help mitigate this risk. +- By default, Scala CLI manages its own dependencies (e.g. scalac, zinc, Bloop) and resolves them lazily. This means that the first run of Scala CLI resolves quite some dependencies. Moreover, Scala CLI periodically checks for updates, new defaults accessing online resources (but it is not required to work, so Scala CLI can work in offline environment once setup) +- Scala CLI can also be configured via using directives. Command line options have precedence over using directives, however using directives override defaults. Compiling a file starting with `//> using scala 2.13.8`, without providing a Scala version on the command line, will result in using `2.13.8` rather than the default Scala version. We consider this a feature. However, technically, this is a breaking change. + +### Other concerns + +Scala CLI brings [using directives](https://scala-cli.virtuslab.org/docs/guides/introduction/using-directives) and [conventions to mark the test files](https://scala-cli.virtuslab.org/docs/commands/test#test-sources). We suggest to accept both accepted as a part of this SIP but we are ready to open dedicated SIPs for both (we have opened a [pre-SIP for using directives](https://contributors.scala-lang.org/t/pre-sip-using-directives/5700/15)) + +Scala CLI is an ambitious project and may seem hard to maintain in the long-run. + + +### Open questions + +The release cadence: should the new `scala` command follow the current release cadence for Scala CLI (every 2 weeks) or stick to Scala one (every 6 weeks)? + +## Alternatives + +Scala CLI has many alternatives. The most obvious ones are sbt, Mill, or other build tools. However, these are more complicated than Scala CLI, and what is more important they are not designed as command-line first tools. Ammonite, is another alternative, however it covers only part of the Scala CLI features (REPL and scripting), and lacks many of the Scala CLI features (incremental compilation, Scala version selection, support for Scala.js and Scala Native, just to name a few). + +## Related work + +- [Scala CLI website](https://scala-cli.virtuslab.org/) and [road map](https://github.com/VirtusLab/scala-cli/discussions/1101) +- [Pre-SIP](https://contributors.scala-lang.org/t/pre-sip-scala-cli-as-new-scala-command/5628/22) +- [leiningen](https://leiningen.org/) - a similar tool from Closure, but more configuration-oriented + +## FAQ + +This section will probably initially be empty. As discussions on the proposal progress, it is likely that some questions will come repeatedly. They should be listed here, with appropriate answers. + +# Scala Runner Specification + +This section describes proposed Scala Runner specification and was generated from Scala CLI documentation. It contains `MUST` have and `SHOULD` have commands (each with complete list of MUST have and SHOULD have options) followed by a list of using directives. + +## Scalac options + +Scala Runner MUST support following options from Scala Compiler directly: + - `-encoding` + - `-release` + - `-color` + - `-nowarn` + - `-feature` + - `-deprecation` + + + Additionally, all options that start with: +- `-g` +- `-language` +- `-opt` +- `-P` +- `-target` +- `-V` +- `-W` +- `-X` +- `-Y` + +SHOULD be treated as be Scala compiler options and be propagated to Scala Compiler. This applies to all commands that uses compiler directly or indirectly. + +# MUST have commands + +## `compile` command + +Compile Scala code + +### MUST have options + +- `--dependency`, `--dep`: Add dependencies +- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies +- `--scala-version`, `--scala`, `-S`: Set the Scala version +- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version +- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path +- `--resource-dirs`, `--resource-dir`: Add a resource directory +- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path +### SHOULD have options + +- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js` +- `--js-version`: The Scala.js version +- `--js-mode`: The Scala.js mode, either `dev` or `release` +- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none +- `--js-check-ir`: +- `--js-emit-source-maps`: Emit source maps +- `--js-source-maps-path`: Set the destination path of source maps +- `--js-dom`: Enable jsdom +- `--js-header`: A header that will be added at the top of generated .js files +- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021 +- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native` +- `--native-version`: Set the Scala Native version +- `--native-mode`: Set Scala Native compilation mode +- `--native-gc`: Set the Scala Native garbage collector +- `--native-linking`: Extra options passed to `clang` verbatim during linking +- `--native-compile`: List of compile options +- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API) +- `--repository`, `--repo`, `-r`: Add repositories +- `--debug`: Turn debugging on +- `--debug-port`: Debug port (5005 by default) +- `--debug-mode`: Debug mode (attach by default) +- `--java-home`: Set the Java home directory +- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` +- `--javac-plugin`: Javac plugin dependencies or files +- `--javac-option`, `--javac-opt`: Javac options +- `--script-snippet`: Allows to execute a passed string as a Scala script +- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly +- `--scala-snippet`: Allows to execute a passed string as Scala code +- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath. +- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs +- `--platform`: Specify platform +- `--semantic-db`: Generate SemanticDBs +- `--watch`, `-w`: Watch source files for changes +- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed +- `--test`: Compile test scope +--- + +## `doc` command + +Generate Scaladoc documentation + +### MUST have options + +- `--dependency`, `--dep`: Add dependencies +- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies +- `--scala-version`, `--scala`, `-S`: Set the Scala version +- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version +- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path +- `--resource-dirs`, `--resource-dir`: Add a resource directory +- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path +- `--output`, `-o`: Set the destination path +- `--force`, `-f`: Overwrite the destination directory, if it exists +### SHOULD have options + +- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js` +- `--js-version`: The Scala.js version +- `--js-mode`: The Scala.js mode, either `dev` or `release` +- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none +- `--js-check-ir`: +- `--js-emit-source-maps`: Emit source maps +- `--js-source-maps-path`: Set the destination path of source maps +- `--js-dom`: Enable jsdom +- `--js-header`: A header that will be added at the top of generated .js files +- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021 +- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native` +- `--native-version`: Set the Scala Native version +- `--native-mode`: Set Scala Native compilation mode +- `--native-gc`: Set the Scala Native garbage collector +- `--native-linking`: Extra options passed to `clang` verbatim during linking +- `--native-compile`: List of compile options +- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API) +- `--repository`, `--repo`, `-r`: Add repositories +- `--debug`: Turn debugging on +- `--debug-port`: Debug port (5005 by default) +- `--debug-mode`: Debug mode (attach by default) +- `--java-home`: Set the Java home directory +- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` +- `--javac-plugin`: Javac plugin dependencies or files +- `--javac-option`, `--javac-opt`: Javac options +- `--script-snippet`: Allows to execute a passed string as a Scala script +- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly +- `--scala-snippet`: Allows to execute a passed string as Scala code +- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath. +- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs +- `--platform`: Specify platform +- `--semantic-db`: Generate SemanticDBs +- `--default-scaladoc-options`, `--default-scaladoc-opts`: Control if scala CLI should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options. +--- + +## `repl` command + +Aliases: `console` + +Fire-up a Scala REPL + +### MUST have options + +- `--dependency`, `--dep`: Add dependencies +- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies +- `--scala-version`, `--scala`, `-S`: Set the Scala version +- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version +- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path +- `--resource-dirs`, `--resource-dir`: Add a resource directory +- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path +- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g` +- `--java-prop`: Set Java properties + +### SHOULD have options + +- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js` +- `--js-version`: The Scala.js version +- `--js-mode`: The Scala.js mode, either `dev` or `release` +- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none +- `--js-check-ir`: +- `--js-emit-source-maps`: Emit source maps +- `--js-source-maps-path`: Set the destination path of source maps +- `--js-dom`: Enable jsdom +- `--js-header`: A header that will be added at the top of generated .js files +- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021 +- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native` +- `--native-version`: Set the Scala Native version +- `--native-mode`: Set Scala Native compilation mode +- `--native-gc`: Set the Scala Native garbage collector +- `--native-linking`: Extra options passed to `clang` verbatim during linking +- `--native-compile`: List of compile options +- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API) +- `--repository`, `--repo`, `-r`: Add repositories +- `--debug`: Turn debugging on +- `--debug-port`: Debug port (5005 by default) +- `--debug-mode`: Debug mode (attach by default) +- `--java-home`: Set the Java home directory +- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` +- `--javac-plugin`: Javac plugin dependencies or files +- `--javac-option`, `--javac-opt`: Javac options +- `--script-snippet`: Allows to execute a passed string as a Scala script +- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly +- `--scala-snippet`: Allows to execute a passed string as Scala code +- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath. +- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs +- `--platform`: Specify platform +- `--semantic-db`: Generate SemanticDBs +- `--watch`, `-w`: Watch source files for changes +- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed + +--- + +## `run` command + +Compile and run Scala code. + +To pass arguments to the application, just add them after `--`, like: + +```sh +scala-cli MyApp.scala -- first-arg second-arg +``` + +### MUST have options + +- `--dependency`, `--dep`: Add dependencies +- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies +- `--scala-version`, `--scala`, `-S`: Set the Scala version +- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version +- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path +- `--resource-dirs`, `--resource-dir`: Add a resource directory +- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path +- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g` +- `--java-prop`: Set Java properties +- `--main-class`, `-M`: Specify which main class to run + +### SHOULD have options + +- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js` +- `--js-version`: The Scala.js version +- `--js-mode`: The Scala.js mode, either `dev` or `release` +- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none +- `--js-check-ir`: +- `--js-emit-source-maps`: Emit source maps +- `--js-source-maps-path`: Set the destination path of source maps +- `--js-dom`: Enable jsdom +- `--js-header`: A header that will be added at the top of generated .js files +- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021 +- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native` +- `--native-version`: Set the Scala Native version +- `--native-mode`: Set Scala Native compilation mode +- `--native-gc`: Set the Scala Native garbage collector +- `--native-linking`: Extra options passed to `clang` verbatim during linking +- `--native-compile`: List of compile options +- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API) +- `--repository`, `--repo`, `-r`: Add repositories +- `--debug`: Turn debugging on +- `--debug-port`: Debug port (5005 by default) +- `--debug-mode`: Debug mode (attach by default) +- `--java-home`: Set the Java home directory +- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` +- `--javac-plugin`: Javac plugin dependencies or files +- `--javac-option`, `--javac-opt`: Javac options +- `--script-snippet`: Allows to execute a passed string as a Scala script +- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly +- `--scala-snippet`: Allows to execute a passed string as Scala code +- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath. +- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs +- `--platform`: Specify platform +- `--semantic-db`: Generate SemanticDBs +- `--watch`, `-w`: Watch source files for changes +- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed +- `--main-class-ls`, `--main-class-list`, `--list-main-class`, `--list-main-classes`: List main classes available in the current context +- `--command`: Print the command that would have been run (one argument per line), rather than running it + +--- + +## `shebang` command + +Like `run`, but more handy from shebang scripts + +This command is equivalent to `run`, but it changes the way +`scala-cli` parses its command-line arguments in order to be compatible +with shebang scripts. + +Normally, inputs and scala-cli options can be mixed. Program have to be specified after `--` + +```sh +scala-cli [command] [scala_cli_options | input]... -- [program_arguments]... +``` + +Contrary, for shebang command, only a single input file can be set, all scala-cli options +have to be set before the input file, and program arguments after the input file +```sh +scala-cli shebang [scala_cli_options]... input [program_arguments]... +``` + +Using this, it is possible to conveniently set up Unix shebang scripts. For example: +```sh +#!/usr/bin/env -S scala-cli shebang --scala-version 2.13 +println("Hello, world) +``` + +### MUST have options + +- `--dependency`, `--dep`: Add dependencies +- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies +- `--scala-version`, `--scala`, `-S`: Set the Scala version +- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version +- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path +- `--resource-dirs`, `--resource-dir`: Add a resource directory +- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path +- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g` +- `--java-prop`: Set Java properties +- `--main-class`, `-M`: Specify which main class to run + +### SHOULD have options + +- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js` +- `--js-version`: The Scala.js version +- `--js-mode`: The Scala.js mode, either `dev` or `release` +- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none +- `--js-check-ir`: +- `--js-emit-source-maps`: Emit source maps +- `--js-source-maps-path`: Set the destination path of source maps +- `--js-dom`: Enable jsdom +- `--js-header`: A header that will be added at the top of generated .js files +- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021 +- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native` +- `--native-version`: Set the Scala Native version +- `--native-mode`: Set Scala Native compilation mode +- `--native-gc`: Set the Scala Native garbage collector +- `--native-linking`: Extra options passed to `clang` verbatim during linking +- `--native-compile`: List of compile options +- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API) +- `--repository`, `--repo`, `-r`: Add repositories +- `--debug`: Turn debugging on +- `--debug-port`: Debug port (5005 by default) +- `--debug-mode`: Debug mode (attach by default) +- `--java-home`: Set the Java home directory +- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` +- `--javac-plugin`: Javac plugin dependencies or files +- `--javac-option`, `--javac-opt`: Javac options +- `--script-snippet`: Allows to execute a passed string as a Scala script +- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly +- `--scala-snippet`: Allows to execute a passed string as Scala code +- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath. +- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs +- `--platform`: Specify platform +- `--semantic-db`: Generate SemanticDBs +- `--watch`, `-w`: Watch source files for changes +- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed +- `--main-class-ls`, `--main-class-list`, `--list-main-class`, `--list-main-classes`: List main classes available in the current context +- `--command`: Print the command that would have been run (one argument per line), rather than running it + +--- + +# SHOULD have commands + +## `fmt` command + +Aliases: `format`, `scalafmt` + +Format Scala code + +### MUST have options + +- `--dependency`, `--dep`: Add dependencies +- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies +- `--scala-version`, `--scala`, `-S`: Set the Scala version +- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version +- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path +- `--resource-dirs`, `--resource-dir`: Add a resource directory +- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path +### SHOULD have options + +- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js` +- `--js-version`: The Scala.js version +- `--js-mode`: The Scala.js mode, either `dev` or `release` +- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none +- `--js-check-ir`: +- `--js-emit-source-maps`: Emit source maps +- `--js-source-maps-path`: Set the destination path of source maps +- `--js-dom`: Enable jsdom +- `--js-header`: A header that will be added at the top of generated .js files +- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021 +- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native` +- `--native-version`: Set the Scala Native version +- `--native-mode`: Set Scala Native compilation mode +- `--native-gc`: Set the Scala Native garbage collector +- `--native-linking`: Extra options passed to `clang` verbatim during linking +- `--native-compile`: List of compile options +- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API) +- `--repository`, `--repo`, `-r`: Add repositories +- `--debug`: Turn debugging on +- `--debug-port`: Debug port (5005 by default) +- `--debug-mode`: Debug mode (attach by default) +- `--java-home`: Set the Java home directory +- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` +- `--javac-plugin`: Javac plugin dependencies or files +- `--javac-option`, `--javac-opt`: Javac options +- `--script-snippet`: Allows to execute a passed string as a Scala script +- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly +- `--scala-snippet`: Allows to execute a passed string as Scala code +- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath. +- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs +- `--platform`: Specify platform +- `--semantic-db`: Generate SemanticDBs +- `--check`: Check if sources are well formatted + +--- + +## `test` command + +Compile and test Scala code + +### MUST have options + +- `--dependency`, `--dep`: Add dependencies +- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies +- `--scala-version`, `--scala`, `-S`: Set the Scala version +- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version +- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path +- `--resource-dirs`, `--resource-dir`: Add a resource directory +- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path +- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g` +- `--java-prop`: Set Java properties +### SHOULD have options + +- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js` +- `--js-version`: The Scala.js version +- `--js-mode`: The Scala.js mode, either `dev` or `release` +- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none +- `--js-check-ir`: +- `--js-emit-source-maps`: Emit source maps +- `--js-source-maps-path`: Set the destination path of source maps +- `--js-dom`: Enable jsdom +- `--js-header`: A header that will be added at the top of generated .js files +- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021 +- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native` +- `--native-version`: Set the Scala Native version +- `--native-mode`: Set Scala Native compilation mode +- `--native-gc`: Set the Scala Native garbage collector +- `--native-linking`: Extra options passed to `clang` verbatim during linking +- `--native-compile`: List of compile options +- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API) +- `--repository`, `--repo`, `-r`: Add repositories +- `--debug`: Turn debugging on +- `--debug-port`: Debug port (5005 by default) +- `--debug-mode`: Debug mode (attach by default) +- `--java-home`: Set the Java home directory +- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system` +- `--javac-plugin`: Javac plugin dependencies or files +- `--javac-option`, `--javac-opt`: Javac options +- `--script-snippet`: Allows to execute a passed string as a Scala script +- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly +- `--scala-snippet`: Allows to execute a passed string as Scala code +- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath. +- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs +- `--platform`: Specify platform +- `--semantic-db`: Generate SemanticDBs +- `--watch`, `-w`: Watch source files for changes +- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed +- `--test-framework`: Name of the test framework's runner class to use while running tests +- `--require-tests`: Fail if no test suites were run +--- + +# Using Directives + + +As a part of this SIP we propose to introduce Using Directives, a special comments containing configuration. Withing Scala CLI and by extension `scala` command, the command line arguments takes precedence over using directives. + +Using directives can be place on only top of the file (above imports, package definition etx.) and can be proceed only by plain comments (e.g. to comment out an using directive) + +Comments containing directives needs to start by `//>`, for example: + +``` +//> using scala 3 +//> using platform scala-js +//> using options -Xasync +``` + +We propose following sytax for Using Directives (within special comments described above): + +``` +UsingDirective ::= "using" Setting +Setting ::= Ident ( Value | Values ) +Ident ::= ScalaIdent { "." ScalaIdent } +Values ::= Value { " " [","] Values } +Value ::= Ident | stringLiteral | numericLiteral | true | false +``` + +Where: + +- Ident is the standard Scala identifier or list of identifiers separated by dots: + +``` +foo + +foo.bar + +`foo-bar`.bazz +``` + +- String literals and numeric literals are similar to Scala. +- No value after the identifier is treated as true value: `using scalaSettings.fatalWarnings` +- Specifying a setting with the same path more than once and specifying the same setting with a list of values are equivalent + +The list of proposed directives split into MUST have and SHOULD have groups: + +## MUST have directives: + + - `option`, `options`: Add Scala compiler options + - `plugin`, `plugins`: Adds compiler plugins + - `lib`, `libs`: Add dependencies + - `javaOpt`, `javaOptions`, `java-opt`, `java-options`: Add Java options which will be passed when running an application. + - `javaProp`: Add Java properties + - `main-class`, `mainClass`: Specify default main class + - `scala`: Set the default Scala version +## SHOULD have directives: + + - `jar`, `jars`: Manually add JAR(s) to the class path + - `file`, `files`: Manually add sources to the Scala CLI project + - `java-home`, `javaHome`: Sets Java home used to run your application or tests + - `javacOpt`, `javacOptions`, `javac-opt`, `javac-options`: Add Javac options which will be passed when compiling sources. + - `platform`, `platforms`: Set the default platform to Scala.js or Scala Native + - `repository`, `repositories`: Add a repository for dependency resolution + - `resourceDir`, `resourceDirs`: Manually add a resource directory to the class path + - `native-gc`, `native-mode`, `native-version`, `native-compile`, `native-linking`, `native-clang`, `native-clang-pp`, `native-no-embed`, `nativeGc`, `nativeMode`, `nativeVersion`, `nativeCompile`, `nativeLinking`, `nativeClang`, `nativeClangPP`, `nativeEmbedResources`: Add Scala Native options + - `jsVersion`, `jsMode`, `jsModuleKind`, `jsCheckIr`, `jsEmitSourceMaps`, `jsSmallModuleForPackage`, `jsDom`, `jsHeader`, `jsAllowBigIntsForLongs`, `jsAvoidClasses`, `jsAvoidLetsAndConsts`, `jsModuleSplitStyleStr`, `jsEsVersionStr`: Add Scala.js options + - `test-framework`, `testFramework`: Set the test framework diff --git a/_sips/sips/2009-05-28-scala-compiler-phase-plugin-in.md b/_sips/sips/scala-compiler-phase-plugin-in.md similarity index 53% rename from _sips/sips/2009-05-28-scala-compiler-phase-plugin-in.md rename to _sips/sips/scala-compiler-phase-plugin-in.md index 264be3bab5..24f0330e91 100644 --- a/_sips/sips/2009-05-28-scala-compiler-phase-plugin-in.md +++ b/_sips/sips/scala-compiler-phase-plugin-in.md @@ -1,10 +1,10 @@ --- layout: sip title: SID-2 Scala Compiler Phase and Plug-In Initialization for Scala 2.8 -vote-status: complete -vote-text: This SIP has already been accepted and completed. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/scala-compiler-phase-plugin-in.html --- -This was an older SID that can be found [here](http://www.scala-lang.org/sid/2) +This was an older SID that can be found [here](https://www.scala-lang.org/sid/2) diff --git a/_sips/sips/scala-specialization.md b/_sips/sips/scala-specialization.md new file mode 100644 index 0000000000..d9bd06e36e --- /dev/null +++ b/_sips/sips/scala-specialization.md @@ -0,0 +1,10 @@ +--- +layout: sip +title: SID-9 - Scala Specialization +stage: completed +status: shipped +permalink: /sips/:title.html +redirect_from: /sips/pending/scala-specialization.html +--- + +This was an older SID that can be found [here](https://www.scala-lang.org/sid/9) diff --git a/_sips/sips/scala-swing-overview.md b/_sips/sips/scala-swing-overview.md new file mode 100644 index 0000000000..a539dc352c --- /dev/null +++ b/_sips/sips/scala-swing-overview.md @@ -0,0 +1,10 @@ +--- +layout: sip +title: SID-8 - Scala Swing Overview +stage: completed +status: shipped +permalink: /sips/:title.html +redirect_from: /sips/pending/scala-swing-overview.html +--- + +This was an older SID that can be found [here](https://www.scala-lang.org/sid/8) diff --git a/_sips/sips/sealed-types.md b/_sips/sips/sealed-types.md new file mode 100644 index 0000000000..04754c6be7 --- /dev/null +++ b/_sips/sips/sealed-types.md @@ -0,0 +1,6 @@ +--- +title: SIP-41 - Sealed Types +status: withdrawn +pull-request-number: 43 + +--- diff --git a/_sips/sips/self-cleaning-macros.md b/_sips/sips/self-cleaning-macros.md new file mode 100644 index 0000000000..056a674a38 --- /dev/null +++ b/_sips/sips/self-cleaning-macros.md @@ -0,0 +1,6 @@ +--- +title: SIP-16 - Self-cleaning Macros +status: rejected +pull-request-number: 15 + +--- diff --git a/_sips/sips/spores.md b/_sips/sips/spores.md new file mode 100644 index 0000000000..2b9c51d5a3 --- /dev/null +++ b/_sips/sips/spores.md @@ -0,0 +1,6 @@ +--- +title: SIP-21 - Spores +status: withdrawn +pull-request-number: 20 + +--- diff --git a/_sips/sips/2016-01-11-static-members.md b/_sips/sips/static-members.md similarity index 92% rename from _sips/sips/2016-01-11-static-members.md rename to _sips/sips/static-members.md index e9c3395d11..1c0df79d75 100644 --- a/_sips/sips/2016-01-11-static-members.md +++ b/_sips/sips/static-members.md @@ -1,15 +1,15 @@ --- layout: sip -title: SIP 25 - @static fields and methods in Scala objects(SI-4581) -discourse: true - -vote-status: "under-review" -vote-text: Authors need to update the proposal before the next review. +title: SIP-30 - @static fields and methods in Scala objects (SI-4581) +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/static-members.html --- -__Dmitry Petrashko, Sébastien Doeraene and Martin Odersky__ +> This proposal has been implemented in Scala 3.0.0 + +**Authors: Dmitry Petrashko, Sébastien Doeraene and Martin Odersky** __first submitted 11 January 2016__ @@ -23,9 +23,9 @@ Some JVM and JavaScript frameworks require classes to have specific static field For example, classes extending `android.os.Parcelable` are required to have a static field named `CREATOR` of type `android.os.Parcelable$Creator`. -Another example is using an [`AtomicReferenceFieldUpdater`](http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.html). +Another example is using an [`AtomicReferenceFieldUpdater`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.html). -On the JavaScript side, one example is [Relay Route Definitions](https://facebook.github.io/relay/docs/en/routing.html), whose subclasses must define static fields such as `queries`. +On the JavaScript side, one example is [Relay Route Definitions](https://web.archive.org/web/20180718024336/https://facebook.github.io/relay/docs/en/routing.html), whose subclasses must define static fields such as `queries`. Static methods and fields for JavaScript classes are one of the very few things (if not the only thing) that Scala.js "cannot do" at the moment, at least not declaratively. ## Overview ## @@ -97,7 +97,7 @@ object O { } {% endhighlight %} -Under the proposed scheme users will be able to opt-in to have the field `f` defined in the inner object `I` emited as a static field. +Under the proposed scheme users will be able to opt-in to have the field `f` defined in the inner object `I` emitted as a static field. In case `O.d` is annotated with `@static` the field will be created as a static field `d` in `class O`. If not annotated, it will be created in the companion module with a static forwarder `d` in `class O`. @@ -109,7 +109,7 @@ The following rules ensure that methods can be correctly compiled into static me 2. The fields annotated with `@static` should precede any non-`@static` fields. This ensures that we do not introduce surprises for users in initialization order of this class. -3. The right hand side of a method or field annotated with `@static` can only refer to top-level classes, members of globally accessible objects and `@static` members. In particular, for non-static objects `this` is not accesible. `super` is never accessible. +3. The right hand side of a method or field annotated with `@static` can only refer to top-level classes, members of globally accessible objects and `@static` members. In particular, for non-static objects `this` is not accessible. `super` is never accessible. 4. If a member `foo` of an `object C` is annotated with `@static`, the companion class `C` is not allowed to define term members with name `foo`. @@ -131,7 +131,7 @@ If implemented in the dotty code base, the following modifications would be need - extend `GenBCode` to emit static fields and methods in companion classes and forwarders to them in companion modules. ## Overriding & Hiding ## -Java allows classes to define static methods with the same name and signature as a static method of a superclass. In order to define the semantics of such cases, the Java Specification introduces the notion of [hiding](http://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.4.8.2). +Java allows classes to define static methods with the same name and signature as a static method of a superclass. In order to define the semantics of such cases, the Java Specification introduces the notion of [hiding](https://docs.oracle.com/javase/specs/jls/se8/html/jls-8.html#jls-8.4.8.2). This is required because in Java calling a `static` method on a class instance is supported. This proposal does not need to introduce this notion as we do not support such calls. @@ -153,7 +153,7 @@ This means that no code precedes the `@static` field initialization which makes since fields are initialized in the order `as written`, similar to how normal fields are initialized. The `@static` proposal is similar to `@tailrec` in a sense that it fails compilation in the case where the user did not write code that follows the aforementioned rules. -These rules exist to enforce the unlikelyhood of an observable difference in semantics if `@static` annotations are dropped; +These rules exist to enforce the unlikelihood of an observable difference in semantics if `@static` annotations are dropped; The restrictions in this SIP make it hard to observe changes in initialization within the same object. It is still possible to observe those changes using multiple classes and side effects within initializers: diff --git a/_sips/sips/2011-10-13-string-interpolation.md b/_sips/sips/string-interpolation.md similarity index 69% rename from _sips/sips/2011-10-13-string-interpolation.md rename to _sips/sips/string-interpolation.md index 69b807a6da..f1343fdb22 100644 --- a/_sips/sips/2011-10-13-string-interpolation.md +++ b/_sips/sips/string-interpolation.md @@ -1,9 +1,9 @@ --- layout: sip title: SIP-11 - String Interpolation - +stage: completed +status: shipped vote-status: complete -vote-text: This SIP has already been accepted and completed. We expect a SIP for 2.11 that will allow the desugared form of interpolated strings in the pattern matcher to become valid syntax. This SIP only allows the sugared interpolated strings to work. permalink: /sips/:title.html redirect_from: /sips/pending/string-interpolation.html --- diff --git a/_sips/sips/struct-classes.md b/_sips/sips/struct-classes.md new file mode 100644 index 0000000000..a9109fd45b --- /dev/null +++ b/_sips/sips/struct-classes.md @@ -0,0 +1,6 @@ +--- +title: SIP-50 - Struct Classes +status: withdrawn +pull-request-number: 50 + +--- diff --git a/_sips/sips/2016-06-25-trailing-commas.md b/_sips/sips/trailing-commas.md similarity index 97% rename from _sips/sips/2016-06-25-trailing-commas.md rename to _sips/sips/trailing-commas.md index 9b9023718a..7eef93dd03 100644 --- a/_sips/sips/2016-06-25-trailing-commas.md +++ b/_sips/sips/trailing-commas.md @@ -1,14 +1,14 @@ --- -layout: inner-page-no-masthead -discourse: true +layout: sip title: SIP-27 - Trailing Commas - -vote-status: complete -vote-text: This SIP has already been accepted and completed, and is a part of Scala 2.12.2. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/trailing-commas.html --- +> This proposal has been shipped in Scala 2.12.2. + **By: Dale Wijnand** ## History diff --git a/_sips/sips/2015-6-18-trait-parameters.md b/_sips/sips/trait-parameters.md similarity index 89% rename from _sips/sips/2015-6-18-trait-parameters.md rename to _sips/sips/trait-parameters.md index 59b0338140..633f0c0b73 100644 --- a/_sips/sips/2015-6-18-trait-parameters.md +++ b/_sips/sips/trait-parameters.md @@ -1,14 +1,14 @@ --- layout: sip -title: SIP 25 - Trait Parameters -discourse: true - -vote-status: "under-review" -vote-text: The board agreed to schedule the next iteration of the evaluation process in 6 months, since there’s no implementation yet and the authors need time to produce one. +title: SIP-25 - Trait Parameters +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/trait-parameters.html --- +> This proposal has been implemented in Scala 3.0. + __Martin Odersky__ __first submitted 18 June 2015__ @@ -69,4 +69,4 @@ the evaluation order would be `e1`, initializer of `T`, `e2`, initializer of `V` ## See Also ## -[Dotty Issue #640](https://github.com/lampepfl/dotty/issues/640) +[Dotty Issue #640](https://github.com/scala/scala3/issues/640) diff --git a/_sips/sips/2012-03-13-type-dynamic.md b/_sips/sips/type-dynamic.md similarity index 85% rename from _sips/sips/2012-03-13-type-dynamic.md rename to _sips/sips/type-dynamic.md index 37385c3c02..c359ec0627 100644 --- a/_sips/sips/2012-03-13-type-dynamic.md +++ b/_sips/sips/type-dynamic.md @@ -1,9 +1,8 @@ --- layout: sip title: SIP-17 - Type Dynamic - -vote-status: complete -vote-text: This SIP has already been accepted and completed. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/type-dynamic.html --- diff --git a/_sips/sips/typeclasses-syntax.md b/_sips/sips/typeclasses-syntax.md new file mode 100644 index 0000000000..38dcba9293 --- /dev/null +++ b/_sips/sips/typeclasses-syntax.md @@ -0,0 +1,685 @@ +--- +layout: sip +stage: completed +status: shipped +presip-thread: https://contributors.scala-lang.org/t/pre-sip-improve-syntax-for-context-bounds-and-givens/6576/97 +title: SIP-64 - Improve Syntax for Context Bounds and Givens +--- + +**By: Martin Odersky** + +## History + +| Date | Version | +|---------------|--------------------| +| March 11, 2024| Initial Draft | +| July 18, 2024 | Revised Draft | + +## Summary + +We propose some syntactic improvements that make context bounds and given clauses more +expressive and easier to read. The proposed additions and changes comprise: + + - naming context bounds, as in `A: Monoid as a`, + - a new syntax for multiple context bounds, as in `A: {Monoid, Ord}`, + - context bounds for type members, + - replacing abstract givens with a more powerful and convenient mechanism, + - a cleaner syntax for given definitions that eliminates some syntactic warts. + +## Motivation + +This SIP is part of an effort to get state-of-the art typeclasses and generic in Scala. It fixes several existing pain points: + + - The inability to name context bounds causes awkward and obscure workarounds in practice. + - The syntax for multiple context bounds is not very clear or readable. + - The existing syntax for givens is unfortunate, which hinders learning and adoption. + - Abstract givens are hard to specify and implement and their syntax is easily confused + with simple concrete givens. + +These pain points are worth fixing on their own, independently of any other proposed improvements to typeclass support. What's more, the changes +are time sensitive since they affect existing syntax that was introduced in 3.0, so it's better to make the change at a time when not that much code using the new syntax is written yet. + +## Proposed Solution + +### 1. Naming Context Bounds + +Context bounds are a convenient and legible abbreviation. A problem so far is that they are always anonymous, one cannot name the implicit parameter to which a context bound expands. For instance, consider the classical pair of type classes +```scala + trait SemiGroup[A]: + extension (x: A) def combine(y: A): A + + trait Monoid[A] extends SemiGroup[A]: + def unit: A +``` +and a `reduce` method defined like this: +```scala +def reduce[A : Monoid](xs: List[A]): A = ??? +``` +Since we don't have a name for the `Monoid` instance of `A`, we need to resort to `summon` in the body of `reduce`: +```scala +def reduce[A : Monoid](xs: List[A]): A = + xs.foldLeft(summon[Monoid[A]].unit)(_ `combine` _) +``` +That's generally considered too painful to write and read, hence people usually adopt one of two alternatives. Either, eschew context bounds and switch to using clauses: +```scala +def reduce[A](xs: List[A])(using m: Monoid[A]): A = + xs.foldLeft(m.unit)(_ `combine` _) +``` +Or, plan ahead and define a "trampoline" method in `Monoid`'s companion object: +```scala + trait Monoid[A] extends SemiGroup[A]: + def unit: A + object Monoid: + def unit[A](using m: Monoid[A]): A = m.unit + ... + def reduce[A : Monoid](xs: List[A]): A = + xs.foldLeft(Monoid.unit)(_ `combine` _) +``` +This is all accidental complexity which can be avoided by the following proposal. + +**Proposal:** Allow to name a context bound, like this: +```scala + def reduce[A : Monoid as m](xs: List[A]): A = + xs.foldLeft(m.unit)(_ `combine` _) +``` + +We use `as x` after the type to bind the instance to `x`. This is analogous to import renaming, which also introduces a new name for something that comes before. + +**Benefits:** The new syntax is simple and clear. It avoids the awkward choice between concise context bounds that can't be named and verbose using clauses that can. + +### 2. New Syntax for Aggregate Context Bounds + +Aggregate context bounds like `A : X : Y` are not obvious to read, and it becomes worse when we add names, e.g. `A : X as x : Y as y`. + +**Proposal:** Allow to combine several context bounds inside `{...}`, analogous +to import clauses. Example: + +```scala + trait A: + def showMax[X : {Ordering, Show}](x: X, y: X): String + class B extends A: + def showMax[X : {Ordering as ordering, Show as show}](x: X, y: X): String = + show.asString(ordering.max(x, y)) +``` + +The old syntax with multiple `:` should be phased out over time. There's more about migration at the end of this SIP. + + +### 3. Expansion of Context Bounds + +With named context bounds, we need a revision to how the witness parameters of such bounds are added. Context bounds are currently translated to implicit parameters in the last parameter list of a method or class. This is a problem if a context bound is mentioned in one of the preceding parameter types. For example, consider a type class of parsers with associated type members `Input` and `Result` describing the input type on which the parsers operate and the type of results they produce: +```scala +trait Parser[P]: + type Input + type Result +``` +Here is a method `run` that runs a parser on an input of the required type: +```scala +def run[P : Parser as p](in: p.Input): p.Result +``` +With the current translation this does not work since it would be expanded to: +```scala + def run[P](x: p.Input)(using p: Parser[P]): p.Result +``` +Note that the `p` in `p.Input` refers to the `p` introduced in the using clause, which comes later. So this is ill-formed. + +This problem would be fixed by changing the translation of context bounds so that they expand to using clauses immediately after the type parameter. But such a change is infeasible, for two reasons: + + 1. It would be a source- and binary-incompatible change. We cannot simply change the expansion of existing using clauses because + then clients that pass explicit using arguments would no longer work. + 2. Putting using clauses earlier can impair type inference. A type in + a using clause can be constrained by term arguments coming before that + clause. Moving the using clause first would miss those constraints, which could cause ambiguities in implicit search. + +But there is an alternative which is feasible: + +**Proposal:** Map the context bounds of a method or class as follows: + + 1. If one of the bounds is referred to by its term name in a subsequent parameter clause, the context bounds are mapped to a using clause immediately preceding the first such parameter clause. + 2. Otherwise, if the last parameter clause is a using (or implicit) clause, merge all parameters arising from context bounds in front of that clause, creating a single using clause. + 3. Otherwise, let the parameters arising from context bounds form a new using clause at the end. + +Rules (2) and (3) are the status quo, and match Scala 2's rules. Rule (1) is new but since context bounds so far could not be referred to, it does not apply to legacy code. Therefore, binary compatibility is maintained. + +**Discussion** More refined rules could be envisaged where context bounds are spread over different using clauses so that each comes as late as possible. But it would make matters more complicated and the gain in expressiveness is not clear to me. + + +### 4. Context Bounds for Type Members, Deferred Givens + +It's not very orthogonal to allow subtype bounds for both type parameters and abstract type members, but context bounds only for type parameters. What's more, we don't even have the fallback of an explicit using clause for type members. The only alternative is to also introduce a set of abstract givens that get implemented in each subclass. This is extremely heavyweight and opaque to newcomers. + +**Proposal**: Allow context bounds for type members. Example: + +```scala + class Collection: + type Element : Ord +``` + +The question is how these bounds are expanded. Context bounds on type parameters +are expanded into using clauses. But for type members this does not work, since we cannot refer to a member type of a class in a parameter type of that class. What we are after is an equivalent of using parameter clauses but represented as class members. + +**Proposal:** +Introduce a new way to implement a given definition in a trait like this: +```scala +given T = deferred +``` +`deferred` is a new method in the `scala.compiletime` package, which can appear only as the right hand side of a given defined in a trait. Any class implementing that trait will provide an implementation of this given. If a definition is not provided explicitly, it will be synthesized by searching for a given of type `T` in the scope of the inheriting class. Specifically, the scope in which this given will be searched is the environment of that class augmented by its parameters but not containing its members (since that would lead to recursive resolutions). If an implementation _is_ provided explicitly, it counts as an override of a concrete definition and needs an `override` modifier. + +Deferred givens allow a clean implementation of context bounds in traits, +as in the following example: +```scala +trait Sorted: + type Element : Ord + +class SortedSet[A : Ord] extends Sorted: + type Element = A +``` +The compiler expands this to the following implementation. +```scala +trait Sorted: + type Element + given Ord[Element] = compiletime.deferred + +class SortedSet[A](using evidence$0: Ord[A]) extends Sorted: + type Element = A + override given Ord[Element] = evidence$0 +``` + +The using clause in class `SortedSet` provides an implementation for the deferred given in trait `Sorted`. + +**Benefits:** + + - Better orthogonality, type parameters and abstract type members now accept the same kinds of bounds. + - Better ergonomics, since deferred givens get naturally implemented in inheriting classes, no need for boilerplate to fill in definitions of abstract givens. + +**Alternative:** It was suggested that we use a modifier for a deferred given instead of a `= deferred`. Something like `deferred given C[T]`. But a modifier does not suggest the concept that a deferred given will be implemented automatically in subclasses unless an explicit definition is written. In a sense, we can see `= deferred` as the invocation of a magic macro that is provided by the compiler. So from a user's point of view a given with `deferred` right hand side is not abstract. +It is a concrete definition where the compiler will provide the correct implementation. And if users want to provide their own overriding +implementations, they will need an explicit `override` modifier. + +### 5. Abolish Abstract Givens + +With `deferred` givens there is no need anymore to also define abstract givens. The two mechanisms are very similar, but the user experience for +deferred givens is generally more ergonomic. Abstract givens also are uncomfortably close to concrete class instances. Their syntax clashes +with the quite common case where we want to establish a given without any nested definitions. For instance, consider a given that constructs a type tag: +```scala +class Tag[T] +``` +Then this works: +```scala +given Tag[String]() +given Tag[String] with {} +``` +But the following more natural syntax fails: +```scala +given Tag[String] +``` +The last line gives a rather cryptic error: +``` +1 |given Tag[String] + | ^ + | anonymous given cannot be abstract +``` +The underlying problem is that abstract givens are very rare (and should become completely unnecessary once deferred givens are introduced), yet occupy a syntax that looks very close to the more common case of concrete +typeclasses without nested definitions. + +**Proposal:** In the future, let the `= deferred` mechanism be the only way to deliver the functionality of abstract givens. Deprecate the current version of abstract givens, and remove them in a future Scala version. + +**Benefits:** + + - Simplification of the language since a feature is dropped + - Eliminate non-obvious and misleading syntax. + +The only downside is that deferred givens are restricted to be used in traits, whereas abstract givens are also allowed in abstract classes. But I would be surprised if actual code relied on that difference, and such code could in any case be easily rewritten to accommodate the restriction. + + +### 6. Context Bounds for Polymorphic Functions + +Currently, context bounds can be used in methods, but not in function types or function literals. It would be nice propose to drop this irregularity and allow context bounds also in these places. Example: + +```scala +type Comparer = [X: Ord] => (x: X, y: X) => Boolean +val less: Comparer = [X: Ord as ord] => (x: X, y: X) => + ord.compare(x, y) < 0 +``` + +The expansion of such context bounds is analogous to the expansion in method types, except that instead of adding a using clause in a method, we insert a context function type. + +For instance, the `type` and `val` definitions above would expand to +```scala +type Comparer = [X] => (x: X, y: X) => Ord[X] ?=> Boolean +val less: Comparer = [X] => (x: X, y: X) => (ord: Ord[X]) ?=> + ord.compare(x, y) < 0 +``` + +The expansion of using clauses does look inside alias types. For instance, +here is a variation of the previous example that uses a parameterized type alias: +```scala +type Cmp[X] = (x: X, y: X) => Ord[X] ?=> Boolean +type Comparer2 = [X: Ord] => Cmp[X] +``` +The expansion of the right hand side of `Comparer2` expands the `Cmp[X]` alias +and then inserts the context function at the same place as what's done for `Comparer`. + +### 7. Cleanup of Given Syntax + +A good language syntax is like a Bach fugue: A small set of motifs is combined in a multitude of harmonic ways. Dissonances and irregularities should be avoided. + +When designing Scala 3, I believe that, by and large, we achieved that goal, except in one area, which is the syntax of givens. There _are_ some glaring dissonances, as seen in this code for defining an ordering on lists: +```scala +given [A](using Ord[A]): Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... +``` +The `:` feels utterly foreign in this position. It's definitely not a type ascription, so what is its role? Just as bad is the trailing `with`. Everywhere else we use braces or trailing `:` to start a scope of nested definitions, so the need of `with` sticks out like a sore thumb. + +Sometimes unconventional syntax grows on you and becomes natural after a while. But here it was unfortunately the opposite. The longer I used given definitions in this style the more awkward they felt, in particular since the rest of the language seemed so much better put together by comparison. And I believe many others agree with me on this. Since the current syntax is unnatural and esoteric, this means it's difficult to discover and very foreign even after that. This makes it much harder to learn and apply givens than it need be. + +The previous conditional given syntax was inspired by method definitions. If we add the optional name to the previous example, we obtain something akin to an implicit method in Scala 2: +```scala +given listOrd[A](using Ord[A]): Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... +``` +The anonymous syntax was then obtained by simply dropping the name. +But without a name, the syntax looks weird and inconsistent. + +This is a problem since at least for typeclasses, anonymous givens should be the norm. +Givens are like extends clauses. We state a _fact_, that a +type implements a type class, or that a value can be used implicitly. We don't need a name for that fact. It's analogous to extends clauses, where we state that a class is a subclass of some other class or trait. We would not think it useful to name an extends clause, it's simply a fact that is stated. +It's also telling that every other language that defines type classes uses anonymous syntax. Somehow, nobody ever found it necessary to name these instances. + +A more intuitive and in my opinion cleaner alternative is to decree that a given should always look like it _implements a type_. Conditional givens should look like they implement function types. The `Ord` typeclass instances for `Int` and `List` would then look like this: +```scala +given Ord[String]: + def compare(x: String, y: String) = ... + +given [A : Ord] => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... +``` +The second, conditional instance looks like it implements the function type +```scala +[A : Ord] => Ord[List[A]] +``` +Another way to see this is as an implication: +If `A` is a type that is `Ord`, then `List[A]` is `Ord` (and the rest of the given clause gives the implementation that makes it so). +Equivalently, `A` is `Ord` _implies_ `List[A]` is `Ord`, hence the `=>`. + +Yet another related meaning is that the given clause establishes a _context function_ of type `[A: Ord] ?=> Ord[List[A]]` that is automatically applied to evidence arguments of type `Ord[A]` and that yields instances of type `Ord[List[A]]`. Since givens are in any case applied automatically to all their arguments, we don't need to specify that separately with `?=>`, a simple `=>` arrow is sufficiently clear and is easier to read. + +All these viewpoints are equivalent, in a deep sense. This is exactly the Curry Howard isomorphism, which equates function types and implications. + +**Proposal:** Change the syntax for given clauses so that a `given` clause consists of the following elements: + + - An optional name binding `id :` + - Zero or more _conditions_, which introduce type or value parameters. Each precondition ends in a `=>`. + - the implemented _type_, + - an implementation which consists of either an `=` and an expression, + or a template body. + +**Examples:** + +Here is an enumeration of common forms of given definitions in the new syntax. We show the following use cases: + + 1. A simple typeclass instance, such as `Ord[Int]`. + 2. A parameterized type class instance, such as `Ord` for lists. + 3. A type class instance with an explicit context parameter. + 4. A type class instance with a named eexplicit context parameter. + 4. A simple given alias. + 5. A parameterized given alias + 6. A given alias with an explicit context parameter. + 8. An abstract or deferred given + 9. A by-name given, e.g. if we have a given alias of a mutable variable, and we + want to make sure that it gets re-evaluated on each access. +```scala + // Simple typeclass + given Ord[Int]: + def compare(x: Int, y: Int) = ... + + // Parameterized typeclass with context bound + given [A: Ord] => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with context parameter + given [A] => Ord[A] => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with named context parameter + given [A] => (ord: Ord[A]) => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Simple alias + given Ord[Int] = IntOrd() + + // Parameterized alias with context bound + given [A: Ord] => Ord[List[A]] = + ListOrd[A] + + // Parameterized alias with context parameter + given [A] => Ord[A] => Ord[List[A]] = + ListOrd[A] + + // Abstract or deferred given + given Context = deferred + + // By-name given + given () => Context = curCtx +``` +Here are the same examples, with optional names provided: +```scala + // Simple typeclass + given intOrd: Ord[Int]: + def compare(x: Int, y: Int) = ... + + // Parameterized typeclass with context bound + given listOrd: [A: Ord] => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with context parameter + given listOrd: [A] => Ord[A] => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with named context parameter + given listOrd: [A] => (ord: Ord[A]) => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Simple alias + given intOrd: Ord[Int] = IntOrd() + + // Parameterized alias with context bound + given listOrd: [A: Ord] => Ord[List[A]] = + ListOrd[A] + + // Parameterized alias with context parameter + given listOrd: [A] => Ord[A] => Ord[List[A]] = + ListOrd[A] + + // Abstract or deferred given + given context: Context = deferred + + // By-name given + given context: () => Context = curCtx +``` + +**By Name Givens** + +We sometimes find it necessary that a given alias is re-evaluated each time it is called. For instance, say we have a mutable variable `curCtx` and we want to define a given that returns the current value of that variable. A normal given alias will not do since by default given aliases are mapped to +lazy vals. + +In general, we want to avoid re-evaluation of the given. But there are situations like the one above where we want to specify _by-name_ evaluation instead. The proposed new syntax for this is shown in the last clause above. This is arguably the a natural way to express by-name givens. We want to use a conditional given, since these map to methods, but the set of preconditions is empty, hence the `()` parameter. Equivalently, under the context function viewpoint, we are defining a context function of the form `() ?=> T`, and these are equivalent to by-name parameters. + +Compare with the current best way to do achieve this, which is to use a dummy type parameter. +```scala + given [DummySoThatItsByName]: Context = curCtx +``` +This has the same effect, but feels more like a hack than a clean solution. + +**Dropping `with`** + +In the new syntax, all typeclass instances introduce definitions like normal +class bodies, enclosed in braces `{...}` or following a `:`. The irregular +requirement to use `with` is dropped. In retrospect, the main reason to introduce `with` was since a definition like + +```scala +given [A](using Ord[A]): Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... +``` +was deemed to be too cryptic, with the double meaning of colons. But since that syntax is gone, we don't need `with` anymore. There's still a double meaning of colons, e.g. in +```scala +given intOrd: Ord[Int]: + ... +``` +but since now both uses of `:` are very familiar (type ascription _vs_ start of nested definitions), it's manageable. Besides, the problem occurs only for named typeclass instances, which should be the exceptional case anyway. + + +**Possible ambiguities** + +If one wants to define a given for an a actual function type (which is probably not advisable in practice), one needs to enclose the function type in parentheses, i.e. `given ([A] => F[A])`. This is true in the currently implemented syntax and stays true for all discussed change proposals. + +The double meaning of : with optional prefix names is resolved as usual. A : at the end of a line starts a nested definition block. If for some obscure reason one wants to define a named given on multiple lines, one has to format it as follows: +```scala + given intOrd + : Ord = ... +``` +**Comparison with Status Quo** + +To facilitate a systematic comparison, here is the listing of all 9x2 cases discussed previously with the current syntax. + +Unnamed: +```scala + // Simple typeclass + given Ord[Int] with + def compare(x: Int, y: Int) = ... + + // Parameterized typeclass with context bound + given [A: Ord]: Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with context parameter + given [A](using Ord[A]): Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with named context parameter + given [A](using ord: Ord[A]): Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... + + // Simple alias + given Ord[Int] = IntOrd() + + // Parameterized alias with context bound + given [A: Ord]: Ord[List[A]] = + ListOrd[A] + + // Parameterized alias with context parameter + given [A](using Ord[A]): Ord[List[A]] = + ListOrd[A] + + // Abstract or deferred given: no unnamed form possible + + // By-name given + given [DummySoItsByName]: Context = curCtx +``` +Named: +```scala + // Simple typeclass + given intOrd: Ord[Int] with + def compare(x: Int, y: Int) = ... + + // Parameterized typeclass with context bound + given listOrd[A: Ord]: Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with context parameter + given listOrd[A](using Ord[A]): Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... + + // Parameterized typeclass with named context parameter + given listOrd[A](using ord: Ord[A]): Ord[List[A]] with + def compare(x: List[A], y: List[A]) = ... + + // Simple alias + given intOrd: Ord[Int] = IntOrd() + + // Parameterized alias with context bound + given listOrd[A: Ord]: Ord[List[A]] = + ListOrd[A] + + // Parameterized alias with context parameter + given listOrd[A](using Ord[A]): Ord[List[A]] = + ListOrd[A] + + // Abstract or deferred given + given context: Context + + // By-name given + given context[DummySoItsByName]: Context = curCtx +``` + +**Summary** + +This will be a fairly significant change to the given syntax. I believe there's still a possibility to do this. Not so much code has migrated to new style givens yet, and code that was written can be changed fairly easily. Specifically, there are about a 900K definitions of `implicit def`s +in Scala code on Github and about 10K definitions of `given ... with`. So about 1% of all code uses the Scala 3 syntax, which would have to be changed again. + +Changing something introduced just recently in Scala 3 is not fun, +but I believe these adjustments are preferable to let bad syntax +sit there and fester. The cost of changing should be amortized by improved developer experience over time, and better syntax would also help in migrating Scala 2 style implicits to Scala 3. But we should do it quickly before a lot more code +starts migrating. + +Migration to the new syntax is straightforward, and can be supported by automatic rewrites. For a transition period we can support both the old and the new syntax. It would be a good idea to backport the new given syntax to the LTS version of Scala so that code written in this version can already use it. The current LTS would then support old and new-style givens indefinitely, whereas new Scala 3.x versions would phase out the old syntax over time. + + +## Summary of Syntax Changes + +Here is the complete context-free syntax for all proposed features. +``` +TmplDef ::= 'given' GivenDef +GivenDef ::= [id ':'] GivenSig +GivenSig ::= GivenImpl + | '(' ')' '=>' GivenImpl + | GivenConditional '=>' GivenSig +GivenImpl ::= GivenType ([‘=’ Expr] | TemplateBody) + | ConstrApps TemplateBody +GivenConditional ::= DefTypeParamClause + | DefTermParamClause + | '(' FunArgTypes ')' + | GivenType +GivenType ::= AnnotType1 {id [nl] AnnotType1} + +TypeDef ::= id [TypeParamClause] TypeAndCtxBounds +TypeParamBounds ::= TypeAndCtxBounds +TypeAndCtxBounds ::= TypeBounds [‘:’ ContextBounds] +ContextBounds ::= ContextBound | '{' ContextBound {',' ContextBound} '}' +ContextBound ::= Type ['as' id] + +FunType ::= FunTypeArgs (‘=>’ | ‘?=>’) Type + | DefTypeParamClause '=>' Type +FunExpr ::= FunParams (‘=>’ | ‘?=>’) Expr + | DefTypeParamClause ‘=>’ Expr +``` + +## Compatibility + +All additions are fully compatible with existing Scala 3. The prototype implementation contains a parser that accepts both old and new idioms. That said, we would +want to deprecate and remove over time the following existing syntax: + + 1. Multiple context bounds of the form `X : A : B : C`. + 2. The previous syntax for given clauses which required a `:` in front of the implemented type and a `with` after it. + 3. Abstract givens + +The changes under (1) and (2) can be automated using existing rewrite technology in the compiler or Scalafix. The changes in (3) are more global in nature but are still straightforward. + +## Alternatives + +One alternative put forward in the Pre-SIP was to deprecate context bounds altogether and only promote using clauses. This would still be a workable system and arguably lead to a smaller language. On the other hand, dropping context bounds for using clauses worsens +some of the ergonomics of expressing type classes. First, it is longer. Second, it separates the introduction of a type name and the constraints on that type name. Typically, there can be many normal parameters between a type parameter and the using clause that characterized it. By contrast, context bounds follow the +general principle that an entity should be declared together with its type, and in a very concrete sense context bounds define types of types. So I think context bounds are here to stay, and improvements to the ergonomics of context bounds will be appreciated. + +The Pre-SIP also contained a proposal for a default naming convention of context bounds. If no explicit `as` clause is given, the name of the witness for +`X : C` would be `X`, instead of a synthesized name as is the case now. This led to extensive discussions how to accommodate multiple context bounds. +I believe that a default naming convention for witnesses will be very beneficial in the long run, but as of today there are several possible candidate solutions, including: + + 1. Use default naming for single bounds only. + 2. If there are multiple bounds, as in `X: {A, B, C}` create a synthetic companion object `X` where selections `X.m` translate into + witness selections `A.m`, `B.m`, or `C.m`. Disallow any references to the companion that remain after that expansion. + 3. Like (2), but use the synthetic companion approach also for single bounds. + 4. Create real aggregate given objects that represent multiple bounds. + +Since it is at present not clear what the best solution would be, I decided to defer the question of default names to a later SIP. + +This SIP proposed originally a different syntax for givens that made use +of postfix `as name` for optional names and still followed method syntax in some elements. The 9x2 variants of the original proposal are as follows. + +```scala + // Simple typeclass + given Ord[Int]: + def compare(x: Int, y: Int) = ... + + // Parameterized typeclass + given [A: Ord] => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Typeclass with context parameter + given [A](using Ord[A]) => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Typeclass with named context parameter + given [A](using ord: Ord[A]) => Ord[List[A]]: + def compare(x: List[A], y: List[A]) = ... + + // Simple alias + given Ord[Int] = IntOrd() + + // Parameterized alias + given [A: Ord] => Ord[List[A]] = + ListOrd[A] + + // Alias with explicit context parameter + given [A](using Ord[A]) => Ord[List[A]] = + ListOrd[A] + + // Abstract or deferred given + given Context = deferred + + // By-name given + given => Context = curCtx +``` +Named: + +```scala + // Simple typeclass + given Ord[Int] as intOrd: + def compare(x: Int, y: Int) = ... + + // Parameterized typeclass + given [A: Ord] => Ord[List[A]] as listOrd: + def compare(x: List[A], y: List[A]) = ... + + // Typeclass with context parameter + given [A](using Ord[A]) => Ord[List[A]] as listOrd: + def compare(x: List[A], y: List[A]) = ... + + // Typeclass with named context parameter + given [A](using ord: Ord[A]) => Ord[List[A]] as listOrd: + def compare(x: List[A], y: List[A]) = ... + + // Simple alias + given Ord[Int] as intOrd = IntOrd() + + // Parameterized alias + given [A: Ord] => Ord[List[A]] as listOrd = + ListOrd[A] + + // Alias with using clause + given [A](using Ord[A]) => Ord[List[A]] as listOrd = + ListOrd[A] + + // Abstract or deferred given + given Context as context = deferred + + // By-name given + given => Context as context = curCtx +``` + +The discussion on contributors raised some concerns with that original proposal. One concern was that changing to postfix `as` for optional names +would be too much of a change, in particular for simple given aliases. Another concern was that the `=>` felt unfamiliar in this place since it resembled a function type yet other syntactic elements followed method syntax. The revised proposal given here addresses these points by +going back to the usual `name:` syntax for optional names and doubling down +on function syntax to reinforce the intuition that givens implement types. + + +## Summary + +The proposed set of changes removes awkward syntax and makes dealing with context bounds and givens a lot more regular and pleasant. In summary, the main proposed changes are: + + 1. Allow to name context bounds with `as` clauses. + 2. Introduce a less cryptic syntax for multiple context bounds. + 3. Refine the rules how context bounds are expanded to account for explicit names. + 4. Allow context bounds on type members which expand to deferred givens. + 5. Drop abstract givens since they are largely redundant with deferred givens. + 6. Allow context bounds for polymorphic functions. + 7. Introduce a more regular and clearer syntax for givens. + +These changes were implemented under the experimental language import +```scala +import language.experimental.modularity +``` +which also covers some other prospective changes slated to be proposed future SIPs. The new system has proven to work well and to address several fundamental issues people were having with +existing implementation techniques for type classes. + +The changes proposed in this SIP are time-sensitive since we would like to correct some awkward syntax choices in Scala 3 before more code migrates to the new constructs (so far, it seems most code still uses Scala 2 style implicits, which will eventually be phased out). It is easy to migrate to the new syntax and to support both old and new for a transition period. diff --git a/_sips/sips/uncluttering-abuse-of-match.md b/_sips/sips/uncluttering-abuse-of-match.md new file mode 100644 index 0000000000..49f004f812 --- /dev/null +++ b/_sips/sips/uncluttering-abuse-of-match.md @@ -0,0 +1,6 @@ +--- +title: SIP-39 - Uncluttering Abuse of Match +status: rejected +pull-request-number: 37 + +--- diff --git a/_sips/sips/uncluttering-scalas-syntax-for-control-structures.md b/_sips/sips/uncluttering-scalas-syntax-for-control-structures.md new file mode 100644 index 0000000000..a4c9d95a95 --- /dev/null +++ b/_sips/sips/uncluttering-scalas-syntax-for-control-structures.md @@ -0,0 +1,6 @@ +--- +title: SIP-12 - Uncluttering Scala’s syntax for control structures. +status: rejected +pull-request-number: 12 + +--- diff --git a/_sips/sips/unroll-default-arguments.md b/_sips/sips/unroll-default-arguments.md new file mode 100644 index 0000000000..6d90188b57 --- /dev/null +++ b/_sips/sips/unroll-default-arguments.md @@ -0,0 +1,934 @@ +--- +layout: sip +permalink: /sips/:title.html +stage: implementation +status: under-review +title: SIP-61 - Unroll Default Arguments for Binary Compatibility +--- + +**By: Li Haoyi** + +## History + +| Date | Version | +|---------------|--------------------| +| Feb 14th 2024 | Initial Draft | + +## Summary + +This SIP proposes an `@unroll` annotation lets you add additional parameters +to method `def`s,`class` construtors, or `case class`es, without breaking binary +compatibility. `@unroll` works by generating "unrolled" or "telescoping" forwarders: + +```scala +// Original +def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l + +// Generated +def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0) +def foo(s: String, n: Int) = foo(s, n, true, 0) +``` + +In contrast to most existing or proposed alternatives that require you to contort your +code to become binary compatible (see [Major Alternatives](#major-alternatives)), +`@unroll` allows you to write Scala with vanilla `def`s/`class`es/`case class`es, add +a single annotation, and your code will maintain binary compatibility as new default +parameters and fields are added over time. + +`@unroll`'s only constraints are that: + +1. New parameters need to have a default value +2. New parameters can only be added on the right +3. The `@unroll`ed methods must be abstract or final + +These are both existing industry-wide standard when dealing with data and schema evolution +(e.g. [Schema evolution in Avro, Protocol Buffers and Thrift — Martin Kleppmann’s blog](https://martin.kleppmann.com/2012/12/05/schema-evolution-in-avro-protocol-buffers-thrift.html)), +and are also the way the new parameters interact with _source compatibility_ in +the Scala language. Thus these constraints should be immediately familiar to any +experienced programmers, and would be easy to follow without confusion. + +Prior Discussion can be found [here](https://contributors.scala-lang.org/t/can-we-make-adding-a-parameter-with-a-default-value-binary-compatible/6132) + +## Motivation + +Maintaining binary compatibility of Scala libraries as they evolve over time is +difficult. Although tools like https://github.com/lightbend/mima help _surface_ +issues, actually _resolving_ those issues is a different challenge. + +Some kinds of library changes are fundamentally impossible to make compatible, +e.g. removing methods or classes. But there is one big class of binary compatibility +issues that are "spurious": adding default parameters to methods, `class` constructors, +or `case class`es. + +Adding a default parameter is source-compatible, but not binary compatible: a user +downstream of a library that adds a default parameter does not need to make any +changes to their code, but _does_ need to re-compile it. This is "spurious" because +there is no _fundamental_ incompatibility here: semantically, a new default parameter +is meant to be optional! Old code invoking that method without a new default parameter +is exactly the user intent, and works just fine if the downstream code is re-compiled. + +Other languages, such as Python, have the same default parameter language feature but face +no such compatibility issues with their use. Even Scala codebases compiled from source +do not suffer these restrictions: adding a default parameter to the right side of a parameter +list is for all intents and purposes backwards compatible in a mono-repo setup. +The fact that such addition is binary incompatible is purely an implementation restriction +of Scala's binary artifact format and distribution strategy. + +**Binary compatibility is generally more important than Source compatibility**. When +you hit a source compatibility issue, you can always change the source code you are +compiling, whether manually or via your build tool. In contrast, when you hit binary +compatibility issues, it can come in the form of diamond dependencies that would require +_re-compiling all of your transitive dependencies_, a task that is far more difficult and +often impractical. + +There are many approaches to resolving these "spurious" binary compatibility issues, +but most of them involve either tremendous amounts of boilerplate writing +binary-compatibility forwarders, giving up on core language features like Case Classes +or Default Parameters, or both. Consider the following code snippet +([link](https://github.com/com-lihaoyi/mainargs/blob/1d04a6bd19aaca401d11fe26da31615a8bc9213c/mainargs/src/Parser.scala)) +from the [com-lihaoyi/mainargs](https://github.com/com-lihaoyi/mainargs) library, which +duplicates the parameters of `def constructEither` no less than five times in +order to maintain binary compatibility as the library evolves and more default +parameters are added to `def constructEither`: + +```scala + def constructEither( + args: Seq[String], + allowPositional: Boolean, + allowRepeats: Boolean, + totalWidth: Int, + printHelpOnExit: Boolean, + docsOnNewLine: Boolean, + autoPrintHelpAndExit: Option[(Int, PrintStream)], + customName: String, + customDoc: String, + sorted: Boolean, + ): Either[String, T] = constructEither( + args, + allowPositional, + allowRepeats, + totalWidth, + printHelpOnExit, + docsOnNewLine, + autoPrintHelpAndExit, + customName, + customDoc, + sorted, + ) + + def constructEither( + args: Seq[String], + allowPositional: Boolean = false, + allowRepeats: Boolean = false, + totalWidth: Int = 100, + printHelpOnExit: Boolean = true, + docsOnNewLine: Boolean = false, + autoPrintHelpAndExit: Option[(Int, PrintStream)] = Some((0, System.out)), + customName: String = null, + customDoc: String = null, + sorted: Boolean = true, + nameMapper: String => Option[String] = Util.kebabCaseNameMapper + ): Either[String, T] = ??? + + /** binary compatibility shim. */ + private[mainargs] def constructEither( + args: Seq[String], + allowPositional: Boolean, + allowRepeats: Boolean, + totalWidth: Int, + printHelpOnExit: Boolean, + docsOnNewLine: Boolean, + autoPrintHelpAndExit: Option[(Int, PrintStream)], + customName: String, + customDoc: String, + nameMapper: String => Option[String] + ): Either[String, T] = constructEither( + args, + allowPositional, + allowRepeats, + totalWidth, + printHelpOnExit, + docsOnNewLine, + autoPrintHelpAndExit, + customName, + customDoc, + sorted = true, + nameMapper = nameMapper + ) +``` + +Apart from being extremely verbose and full of boilerplate, like any boilerplate this is +also extremely error-prone. Bugs like [com-lihaoyi/mainargs#106](https://github.com/com-lihaoyi/mainargs/issues/106) +slip through when a mistake is made in that boilerplate. These bugs are impossible to catch +using a normal test suite, as they only appear in the presence of version skew. The above code +snippet actually _does_ have such a bug, that the test suite _did not_ catch. See if you can +spot it! + +Sebastien Doraene's talk [Designing Libraries for Source and Binary Compatibility](https://www.youtube.com/watch?v=2wkEX6MCxJs) +explores some of the challenges, and discusses the workarounds. + + +## Requirements + +### Backwards Compatibility + +Given: + +* Two libraries, **Upstream** and **Downstream**, where **Downstream** depends on **Upstream** + +* If we use a _newer_ version of **Upstream** which contains an added + default parameter together with an _older_ version of **Downstream** compiled + against an _older_ version of **Upstream** before that default parameter was added + +* The behavior should be binary compatible and semantically indistinguishable from using + a verion of **Downstream** compiled against the _newer_ version of **Upstream** + +**Note:** we do not aim for _Forwards_ compatibility. Using an _older_ +version of **Upstream** with a _newer_ version of **Downstream** compiled against a +_newer_ version of **Upstream** is not a use case we want to support. The vast majority +of OSS software does not promise forwards compatibility, including software such as +the JVM, so we should just follow suite + +### All Overrides Are Equivalent + +All versions of an `@unroll`ed method `def foo` should have the same semantics when called +with the same parameters. We must be careful to ensure: + +1. All our different method overrides point at the same underlying implementation +2. Abstract methods are properly implemented, and no method would fail with an + `AbstractMethodError` when called +3. We properly forward the necessary argument and default parameter values when + calling the respective implementation. + +## Proposed solution + + +The proposed solution is to provide a `scala.annotation.unroll` annotation, that +can be applied to methods `def`s, `class` constructors, or `case class`es to generate +"unrolled" or "telescoping" versions of a method that forward to the primary implementation: + +```scala + def constructEither( + args: Seq[String], + allowPositional: Boolean = false, + allowRepeats: Boolean = false, + totalWidth: Int = 100, + printHelpOnExit: Boolean = true, + docsOnNewLine: Boolean = false, + autoPrintHelpAndExit: Option[(Int, PrintStream)] = Some((0, System.out)), + customName: String = null, + customDoc: String = null, + @unroll sorted: Boolean = true, + @unroll nameMapper: String => Option[String] = Util.kebabCaseNameMapper + ): Either[String, T] = ??? +``` + +This allows the developer to write the minimal amount of code they _want_ to write, +and add a single annotation to allow binary compatibility to old versions. In this +case, we annotated `sorted` and `nameMapper` with `@unroll`, which generates forwarders that make +`def constructEither` binary compatible with older versions that have fewer parameters, +up to a version before `sorted` or `nameMapper` was added. Any existing method `def`, `class`, or +`case class` can be evolved in this way, by addition of `@unroll` the first time +a default argument is added to their signature after its initial definition. + +### Unrolling `def`s + +Consider a library that is written as follows: + +```scala +object Unrolled{ + def foo(s: String, n: Int = 1) = s + n + b + l +} +``` + +If over time a new default parameter is added: + +```scala +object Unrolled{ + def foo(s: String, n: Int = 1, b: Boolean = true) = s + n + b + l +} +``` + +And another + +```scala +object Unrolled{ + def foo(s: String, n: Int = 1, b: Boolean = true, l: Long = 0) = s + n + b + l +} +``` + +This is a source-compatible change, but not binary-compatible: JVM bytecode compiled against an +earlier version of the library would be expecting to call `def foo(String, Int)`, but will fail +because the signature is now `def foo(String, Int, Boolean)` or `def foo(String, Int, Boolean, Long)`. +On the JVM this will result in a `MethodNotFoundError` at runtime, a common experience for anyone +who upgrading the versions of their dependencies. Similar concerns are present with Scala.js and +Scala-Native, albeit the failure happens at link-time rather than run-time + +`@unroll` is an annotation that can be applied as follows, to the first "additional" default +parameter that was added in each published version of the library (in this case, +`b: Boolean = true` and `l: Long = 0`) + + +```scala +import scala.annotation.unroll + +object Unrolled{ + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l +} +``` + +The `@unroll` annotation takes `def foo` and generates synthetic forwarders for the purpose +of maintaining binary compatibility for old callers who may be expecting the previous signature. +These forwarders do nothing but forward the call to the current implementation, using the +given default parameter values: + +```scala +object Unrolled{ + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l + + def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0) + def foo(s: String, n: Int) = foo(s, n, true, 0) +} +``` + +As a result, old callers who expect `def foo(String, Int, Boolean)` or `def foo(String, Int, Boolean, Long)` +can continue to work, even as new parameters are added to `def foo`. The only restriction is that +new parameters can only be added on the right, and they must be provided with a default value. + +If multiple default parameters are added at once (e.g. `b` and `l` below) you can also +choose to only `@unroll` the first default parameter of each batch, to avoid generating +unnecessary forwarders: + +```scala +object Unrolled{ + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, l: Long = 0) = s + n + b + l + + def foo(s: String, n: Int) = foo(s, n, true, 0) +} +``` + +If there are multiple parameter lists (e.g. for curried methods or methods taking implicits) only one +parameter list can be unrolled (though it does not need to be the first one). e.g. this works: + +```scala +object Unrolled{ + def foo(s: String, + n: Int = 1, + @unroll b: Boolean = true, + @unroll l: Long = 0) + (implicit blah: Blah) = s + n + b + l +} +``` + +As does this + +```scala +object Unrolled{ + def foo(blah: Blah) + (s: String, + n: Int = 1, + @unroll b: Boolean = true, + @unroll l: Long = 0) = s + n + b + l +} +``` + +`@unroll`ed methods can be defined in `object`s, `class`es, or `trait`s. Other cases are shown below. + +### Unrolling `class`es + +Class constructors and secondary constructors are treated by `@unroll` just like any +other method: + +```scala +class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0){ + def foo = s + n + b + l +} +``` + +Unrolls to: + +```scala +class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0){ + def foo = s + n + b + l + + def this(s: String, n: Int, b: Boolean) = this(s, n, b, 0) + def this(s: String, n: Int) = this(s, n, true, 0) +} +``` + +### Unrolling `class` secondary constructors + +```scala +class Unrolled() { + var foo = "" + + def this(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = { + this() + foo = s + n + b + l + } +} +``` + +Unrolls to: + +```scala +class Unrolled() { + var foo = "" + + def this(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = { + this() + foo = s + n + b + l + } + + def this(s: String, n: Int, b: Boolean) = this(s, n, b, 0) + def this(s: String, n: Int) = this(s, n, true, 0) +} +``` + +### Case Classes + +`case class`es can also be `@unroll`ed. Unlike normal `class` constructors +and method `def`s, `case class`es have several generated methods (`apply`, `copy`) +that need to be kept in sync with their primary constructor. `@unroll` thus +generates forwarders for those methods as well, based on the presence of the +`@unroll` annotation in the primary constructor: + +```scala +case class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true){ + def foo = s + n + b +} +``` + +Unrolls to: + +```scala +case class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0L){ + def this(s: String, n: Int) = this(s, n, true, 0L) + def this(s: String, n: Int, b: Boolean) = this(s, n, b, 0L) + + def copy(s: String, n: Int) = copy(s, n, this.b, this.l) + def copy(s: String, n: Int, b: Boolean) = copy(s, n, b, this.l) + + def foo = s + n + b +} +object Unrolled{ + def apply(s: String, n: Int) = apply(s, n, true, 0L) + def apply(s: String, n: Int, b: Boolean) = apply(s, n, b, 0L) +} +``` + +Notes: + +1. `@unroll`ed `case class`es are fully binary and backwards compatible in Scala 3, but not in Scala 2 + +2. `.unapply` does not need to be duplicated in Scala 3.x, as its signature + `def unapply(x: Unrolled): Unrolled` does not change when new `case class` fields are + added. + +3. Even in Scala 2.x, where `def unapply(x: Unrolled): Option[TupleN]` is not + binary compatible, pattern matching on `case class`es is already binary compatible + to addition of new fields due to + [Option-less Pattern Matching](https://docs.scala-lang.org/scala3/reference/changed-features/pattern-matching.html). + Thus, only calls to `.tupled` or `.curried` on the `case class` companion `object`, or direct calls + to `.unapply` on an unrolled `case class` in Scala 2.x (shown below) + will cause a crash if additional fields were added: + +```scala +def foo(t: (String, Int)) = println(t) +Unrolled.unapply(unrolled).map(foo) +``` + +In Scala 3, `@unroll`ing a `case class` also needs to generate a `fromProduct` +implementation in the companion object, as shown below: + +```scala +def fromProduct(p: Product): CaseClass = p.productArity match + case 2 => + CaseClass( + p.productElement(0).asInstanceOf[...], + p.productElement(1).asInstanceOf[...], + ) + case 3 => + CaseClass( + p.productElement(0).asInstanceOf[...], + p.productElement(1).asInstanceOf[...], + p.productElement(2).asInstanceOf[...], + ) + ... +``` + +This is not necessary for preserving binary compatibility - the method signature of +`def fromProduct` does not change depending on the number of fields - but it is +necessary to preserve semantic compatibility. `fromProduct` by default does not +take into account field default values, and this change is necessary to make it +use them when the given `p: Product` has a smaller `productArity` than the current +`CaseClass` implementation + + +### Hiding Generated Forwarder Methods + +As the generated forwarder methods are intended only for binary compatibility purposes, +we should generally hide them: IDEs, downstream compilers, ScalaDoc, etc. should behave as +if the generated methods do not exist. + +This is done in two different ways: + +1. In Scala 2, we generate the methods in a post-`pickler` phase. This ensures they do + not appear in the scala signature, and thus are not exposed to downstream tooling + +2. In Scala 3, the generated methods are flagged as `Invisible` + +## Limitations + +### Only the one parameter list of multi-parameter list methods can be `@unroll`ed. + +Unrolling multiple parameter lists would generate a number +of forwarder methods exponential with regard to the number of parameter lists unrolled, +and the generated forwarders may begin to conflict with each other. We can choose to spec +this out and implement it later if necessary, but for 99% of use cases `@unroll`ing one +parameter list should be enough. Typically, only one parameter list in a method has default +arguments, with other parameter lists being `implicit`s or a single callback/blocks, neither +of which usually has default values. + +### Unrolled forwarder methods can collide with manually-defined overrides + +This is similar to any other generated methods. We can raise an error to help users +debug such scenarios, but such name collisions are inevitably possible given how binary +compatibility on the JVM works. + +### `@unroll`ed case classes are only fully binary compatible in Scala 3 + + +They are _almost_ binary compatible in Scala 2. Direct calls to `unapply` are binary +incompatible, but most common pattern matching of `case class`es goes through a different +code path that _is_ binary compatible. There are also the `AbstractFunctionN` traits, from +which the companion object inherits `.curried` and `.tupled` members. Luckily, `unapply` +was made binary compatible in Scala 3, and `AbstractFunctionN`, `.curried`, and `.tupled` +were removed + +### While `@unroll`ed `case class`es are *not* fully _source_ compatible + +This is due to the fact that pattern matching requires all arguments to +be specified. This proposal does not change that. Future improvements related to +[Pattern Matching on Named Fields](https://github.com/scala/improvement-proposals/pull/44) +may bring improvements here. But as we discussed earlier, binary compatibility is generally +more important than source compatibility, and so we do not need to wait for any source +compatibility improvements to land before proceeding with these binary compatibility +improvements. + +### Binary and semantic compatibility for macro-derived derive typeclasses is out of scope + + +This propsosal does not have any opinion on whether or not macro-derivation is be binary/source/semantically +compatible. That is up to the +individual macro implementations to decide. e.g., [uPickle](https://github.com/com-lihaoyi/upickle) +has a very similar rule about adding `case class` fields, except that field ordering +does not matter. Trying to standardize this across all possible macros and all possible +typeclasses is out of scope + +### `@unroll` generates a quadratic amount of generated bytecode as more default parameters are added + +Each forwarder has `O(num-params)` size, and there are `O(num-default-params)` +forwarders. We do not expect this to be a problem in practice, as the small size of the +generated forwarder methods means the constant factor is small, but one could imagine +the `O(n^2)` asymptotic complexity becoming a problem if a method accumulates hundreds of +default parameters over time. In such extreme scenarios, some kind of builder pattern +(such as those listed in [Major Alternatives](#major-alternatives)) may be preferable. + +### `@unroll` only supports `final` methods. + +`object` methods and constructors are naturally +final, but `class` or `trait` methods that are `@unroll`ed need to be explicitly marked `final`. +It has proved difficult to implement the semantics of `@unroll` in the presence of downstream +overrides, `super`, etc. where the downstream overrides can be compiled against by different +versions of the upstream code. If we can come up with some implementation that works, we can +lift this restriction later, but for now I have not managed to do so and so this restriction +stays. + +### Challenges of Non-Final Methods and Overriding + +To elaborate a bit on the issues with non-final methods and overriding, consider the following +case with four classes, `Upstream`, `Downstream`, `Main1` and `Main2`, each of which is compiled +against different versions of each other (hence the varying number of parameters for `foo`): + +```scala +class Upstream{ // V2 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l +} +``` + +```scala +class Downstream extends Upstream{ // compiled against Upstream V1 + override def foo(s: String, n: Int = 1) = super.foo(s, n) + s + n +} +``` + +```scala +object Main1 { // compiled against Upstream V2 + def main(args: Array[String]): Unit = { + new Downstream().foo("hello", 123, false, 456L) + } +} +``` + +```scala +object Main2 { // compiled against Upstream V1 + def main(args: Array[String]): Unit = { + new Downstream().foo("hello", 123) + } +} +``` + + +The challenge here is: how do we make sure that `Main1` and `Main2`, who call +`new Downstream().foo`, correctly pick up the version of `def foo` that is +provided by `Downstream`? + +With the current implementation, the `override def foo` inside `Downstream` would only +override one of `Upstream`'s synthetic forwarders, but would not override the actual +primary implementation. As a result, we would see `Main1` calling the implementation +of `foo` from `Upstream`, while `Main2` calls the implementation of `foo` from +`Downstream`. So even though both `Main1` and `Main2` have the same +`Upstream` and `Downstream` code on the classpath, they end up calling different +implementations based on what they were compiled against. + +We cannot perform the method search and dispatch _within_ the `def foo` methods, +because it depends on exactly _how_ `foo` is called: the `InvokeVirtual` call from +`Main1` is meant to resolve to `Downstream#foo`, while the `InvokeSpecial` call +from `Downstream#foo`'s `super.foo` is meant to resolve to `Upstream#foo`. But a +method implementation cannot know how it was called, and thus it is impossible +for `def foo` to forward the call to the right place. + +Like our treatment of [Abstract Methods](#abstract-methods), this scenario can never +happen according to what version combinations are supported by our definition of +[Backwards Compatibility](#backwards-compatibility), but nevertheless is a real +concern due to the requirement that [All Overrides Are Equivalent](#all-overrides-are-equivalent). + +It may be possible to loosen this restriction to also allow abstract methods that +are implemented only once by a final method. See the section about +[Abstract Methods](#abstract-methods) for details. + +## Major Alternatives + +The major alternatives to `@unroll` are listed below: + +1. [data-class](https://index.scala-lang.org/alexarchambault/data-class) +2. [SBT Contrabad](https://www.scala-sbt.org/contraband/) +3. [Structural Data Structures](https://contributors.scala-lang.org/t/pre-sip-structural-data-structures-that-can-evolve-in-a-binary-compatible-way/5684) +4. Avoiding language features like `case class`es or default parameters, as suggested by the + [Binary Compatibility for Library Authors](https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html) documentation. + +While those alternate approaches _do work_ - `data-class` and `SBT Datatype` are used heavily +in various open-source projects - I believe they are inferior to the approach that `@unroll` +takes: + +### Case Class v.s. not-a-Case-Class + +The first major difference between `@unroll` and the above alternatives is that these alternatives +all introduce something new: some kind of _not-a-case-class_ `class` that is to be used +when binary compatibility is desired. This _not-a-case-class_ has different syntax from +`case class`es, different semantics, different methods, and so on. + +In contrast, `@unroll` does not introduce any new language-level or library-level constructs. +The `@unroll` annotation is purely a compiler-backend concern for maintaining binary +compatibility. At a language level, `@unroll` allows you to keep using normal method `def`s, +`class`es and `case class`es with exactly the same syntax and semantics you have been using +all along. + +Having people be constantly choosing between _case-class_ and _not-a-case-class_ when +designing their data types, is inferior to simply using `case class`es all the time + + +### Scala Syntax v.s. Java-esque Syntax + + +The alternatives linked above all build a +Java-esque "[inner platform](https://en.wikipedia.org/wiki/Inner-platform_effect)" +on top of the Scala language, with its own conventions like `.withFoo` methods. + +In contrast, `@unroll` makes use of the existing Scala language's default parameters +to achieve the same effect. + +If we think Scala is nicer to write then Java due to its language +features, then `@unroll`'s approach of leveraging those language features is nicer +to use than the alternative's Java-esque syntax. + +Having implementation-level problems - which is what binary compatibility across version +skew is - bleed into the syntax and semantics of the language is also inferior to having it +be controlled by an annotation. Martin Odersky has said that annotations are intended for +things that do not affect typechecking, and `@unroll` fits the bill perfectly. + + +### Evolving Any Class v.s. Evolving Pre-determined Classes + +The alternatives given require that the developer has to decide _up front_ whether their +data type needs to be evolved while maintaining binary compatibility. + +In contrast, `@unroll` allows you to evolve any existing `class` or `case class`. + +In general, trying to decide which classes _will need to evolve later on_ is a difficult +task that is easy to get wrong. `@unroll` totally removes that requirement, allowing +you to take _any_ `class` or `case class` and evolve it later in a binary compatible way. + + +### Binary Compatibility for Methods and Classes + +Lastly, the above alternatives only solve _half_ the problem: how to evolve `case class`es. +This is _schema evolution_. + +Binary compatility is not just a problem for `case class`es adding new fields: normal +`class` constructors, instance method `def`s, static method `def`s, etc. have default +parameters added all the time as well. + +In contrast, `@unroll` allows the evolution of `def`s and normal `class`es, in addition +to `case class`es, all using the same approach: + +1. `@unroll`ing `case class`es is about _schema evolution_ +2. `@unroll`ing concrete method `def`s is about _API evolution_ +3. `@unroll`ing abstract method `def`s is about _protocol evolution_ + +All three cases above have analogous best practices in the broader software engineering +world: whether you are adding an optional column to a database table, adding an +optional flag to a command-line tool, are extending an existing protocol with optional +fields that may need handling by both clients and servers implementing that protocol. + +`@unroll` solves all three problems at once - schema evolution, API evolution, and protocol +evolution. It does so with the same Scala-level syntax and semantics, with the same requirements +and limitations that common schema/API/protocol-evolution best-practices have in the broader +software engineering community. + +### Abstract Methods + +Apart from `final` methods, `@unroll` also supports purely abstract methods. Consider +the following example with a trait `Unrolled` and an implementation `UnrolledObj`: + +```scala +trait Unrolled{ // version 3 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0): String +} +``` +```scala +object UnrolledObj extends Unrolled{ // version 3 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b +} +``` + +This unrolls to: +```scala +trait Unrolled{ // version 3 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0): String = foo(s, n, b) + def foo(s: String, n: Int, b: Boolean): String = foo(s, n) + def foo(s: String, n: Int): String +} +``` +```scala +object UnrolledObj extends Unrolled{ // version 3 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l + def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0) + def foo(s: String, n: Int) = foo(s, n, true) +} +``` + +Note that both the abstract methods from `trait Unrolled` and the concrete methods +from `object UnrolledObj` generate forwarders when `@unroll`ed, but the forwarders +are generated _in opposite directions_! Unrolled concrete methods forward from longer +parameter lists to shorter parameter lists, while unrolled abstract methods forward +from shorter parameter lists to longer parameter lists. For example, we may have a +version of `object UnrolledObj` that was compiled against an earlier version of `trait Unrolled`: + + +```scala +object UnrolledObj extends Unrolled{ // version 2 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true) = s + n + b + def foo(s: String, n: Int) = foo(s, n, true) +} +``` + +But further downstream code calling `.foo` on `UnrolledObj` may expect any of the following signatures, +depending on what version of `Unrolled` and `UnrolledObj` it was compiled against: + +```scala +UnrolledObj.foo(String, Int) +UnrolledObj.foo(String, Int, Boolean) +UnrolledObj.foo(String, Int, Boolean, Long) +``` + +Because such downstream code cannot know which version of `Unrolled` that `UnrolledObj` +was compiled against, we need to ensure all such calls find their way to the correct +implementation of `def foo`, which may be at any of the above signatures. This "double +forwarding" strategy ensures that regardless of _which_ version of `.foo` gets called, +it ends up eventually forwarding to the actual implementation of `foo`, with +the correct combination of passed arguments and default arguments + +```scala +UnrolledObj.foo(String, Int) // forwards to UnrolledObj.foo(String, Int, Boolean) +UnrolledObj.foo(String, Int, Boolean) // actual implementation +UnrolledObj.foo(String, Int, Boolean, Long) // forwards to UnrolledObj.foo(String, Int, Boolean) +``` + +As is the case for `@unroll`ed methods on `trait`s and `class`es, `@unroll`ed +implementations of an abtract method must be final. + +#### Are Reverse Forwarders Really Necessary? + +This "double forwarding" strategy is not strictly necessary to support +[Backwards Compatibility](#backwards-compatibility): the "reverse" forwarders +generated for abstract methods are only necessary when a downstream callsite +of `UnrolledObj.foo` is compiled against a newer version of the original +`trait Unrolled` than the `object UnrolledObj` was, as shown below: + +```scala +trait Unrolled{ // version 3 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0): String = foo(s, n, b) + // generated + def foo(s: String, n: Int, b: Boolean): String = foo(s, n) + def foo(s: String, n: Int): String +} +``` +```scala +object UnrolledObj extends Unrolled{ // version 2 + def foo(s: String, n: Int = 1, @unroll b: Boolean = true) = s + n + b + // generated + def foo(s: String, n: Int) = foo(s, n, true) +} +``` +```scala +// version 3 +UnrolledObj.foo("hello", 123, true, 456L) +``` + +If we did not have the reverse forwarder from `foo(String, Int, Boolean, Long)` to +`foo(String, Int, Boolean)`, this call would fail at runtime with an `AbstractMethodError`. +It also will get caught by MiMa as a `ReversedMissingMethodProblem`. + +This configuration of version is not allowed given our definition of backwards compatibility: +that definition assumes that `Unrolled` must be of a greater or equal version than `UnrolledObj`, +which itself must be of a greater or equal version than the final call to `UnrolledObj.foo`. However, +the reverse forwarders are needed to fulfill our requirement +[All Overrides Are Equivalent](#all-overrides-are-equivalent): +looking at `trait Unrolled // version 3` and `object UnrolledObj // version 2` in isolation, +we find that without the reverse forwarders the signature `foo(String, Int, Boolean, Long)` +is defined but not implemented. Such an un-implemented abstract method is something +we want to avoid, even if our artifact version constraints mean it should technically +never get called. + +## Minor Alternatives: + + +### `@unrollAll` + +Currently, `@unroll` generates a forwarder only for the annotated default parameter; +if you want to generate multiple forwarders, you need to `@unroll` each one. In the +vast majority of scenarios, we want to unroll every default parameters we add, and in +many cases default parameters are added one at a time. In this case, an `@unrollAll` +annotation may be useful, a shorthand for applying `@unroll` to the annotated default +parameter and every parameter to the right of it: + +```scala +object Unrolled{ + def foo(s: String, n: Int = 1, @unrollAll b: Boolean = true, l: Long = 0) = s + n + b + l +} +``` +```scala +object Unrolled{ + def foo(s: String, n: Int = 1, b: Boolean = true, l: Long = 0) = s + n + b + l + + def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0) + def foo(s: String, n: Int) = foo(s, n, true, 0) +} +``` + + + +### Generating Forwarders For Parameter Type Widening or Result Type Narrowing + +While this proposal focuses on generating forwarders for addition of default parameters, +you can also imagine similar forwarders being generated if method parameter types +are widened or if result types are narrowed: + +```scala +// Before +def foo(s: String, n: Int = 1, b: Boolean = true) = s + n + b + l + +// After +def foo(@unrollType[String] s: Object, n: Int = 1, b: Boolean = true) = s.toString + n + b + l + +// Generated +def foo(s: Object, n: Int = 1, b: Boolean = true) = s.toString + n + b + l +def foo(s: String, n: Int = 1, b: Boolean = true) = foo(s, n, b) +``` + +This would follow the precedence of how Java's and Scala's covariant method return +type overrides are implemented: when a class overrides a method with a new +implementation with a narrower return type, a forwarder method is generated to +allow anyone calling the original signature \to be forwarded to the narrower signature. + +This is not currently implemented in `@unroll`, but would be a straightforward addition. + +### Incremental Forwarders or Direct Forwarders + +Given this: + +```scala +def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l +``` + +There are two ways to do the forwarders. First option, which I used in above, is +to have each forwarder directly call the primary method: + +```scala +def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0) +def foo(s: String, n: Int) = foo(s, n, true, 0) +``` + +Second option is to have each forwarder incrementally call the next forwarder, which +will eventually end up calling the primary method: + +```scala +def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0) +def foo(s: String, n: Int) = foo(s, n, true) +``` + +The first option results in shorter stack traces, while the second option results in +roughly half as much generated bytecode in the method bodies (though it's still `O(n^2)`). + +In order to allow `@unroll`ing of [Abstract Methods](#abstract-methods), we had to go with +the second option. This is because when an abstract method is overriden, it is not necessarily +true that the longest override that contains the implementation. Thus we need to forward +between the different `def foo` overrides one at a time until the override containing the +implementation is found. + + + +## Implementation & Testing + +This SIP has a full implementation for Scala {2.12, 2.13, 3} X {JVM, JS, Native} +in the following repository, as a compiler plugin: + +- https://github.com/com-lihaoyi/unroll + +As the `@unroll` annotation is purely a compile-time construct and does not need to exist +at runtime, `@unroll` can be added to Scala 2.13.x without breaking forwards compatibility. + +The linked repo also contains an extensive test suite that uses both MIMA as well +as classpath-mangling to validate that it provides both the binary and semantic +compatibility benefits claimed in this document. In fact, it has even discovered +bugs in the upstream Scala implementation related to binary compatibility, e.g. +[scala-native/scala-native#3747](https://github.com/scala-native/scala-native/issues/3747) + +I have also opened pull requests to a number of popular OSS Scala libraries, +using `@unroll` as a replacement for manually writing binary compatibility stubs, +and the 100s of lines of boilerplate reduction can be seen in the links below: + +- https://github.com/com-lihaoyi/mainargs/pull/113/files +- https://github.com/com-lihaoyi/mill/pull/3008/files +- https://github.com/com-lihaoyi/upickle/pull/555/files +- https://github.com/com-lihaoyi/os-lib/pull/254 + +These pull requests all pass both the test suite as well as the MIMA +`check-binary-compatibility` job, demonstrating that this approach does work +in real-world codebases. At time of writing, these are published under the following +artifacts and can be used in your own projects already: + +- Compiler Plugin: `ivy"com.lihaoyi::unroll-plugin:0.1.12"` +- Annotation: `ivy"com.lihaoyi::unroll-annotation:0.1.12"` diff --git a/_sips/sips/unsigned-integers.md b/_sips/sips/unsigned-integers.md new file mode 100644 index 0000000000..4cfa9995db --- /dev/null +++ b/_sips/sips/unsigned-integers.md @@ -0,0 +1,6 @@ +--- +title: SIP-26 - Unsigned Integers +status: rejected +pull-request-number: 27 + +--- diff --git a/_sips/sips/2012-01-30-value-classes.md b/_sips/sips/value-classes.md similarity index 96% rename from _sips/sips/2012-01-30-value-classes.md rename to _sips/sips/value-classes.md index cf8ac211db..48ad643281 100644 --- a/_sips/sips/2012-01-30-value-classes.md +++ b/_sips/sips/value-classes.md @@ -1,15 +1,16 @@ --- layout: sip title: SIP-15 - Value Classes - -vote-status: complete -vote-text: This SIP has already been accepted and completed. There has been concern for numerical computing. We think future SIP(s), using work from SIP-15, can provide more benefit to numerical computing users. The SIP as it exists benefits all users of implicit enrichment classes, and takes us much further to unboxed high performance code. This SIP does not exclude further work towards improving numerical computing in Scala. +stage: completed +status: shipped permalink: /sips/:title.html redirect_from: /sips/pending/value-classes.html --- **By: Martin Odersky and Jeff Olson and Paul Phillips and Joshua Suereth** +> Note from the SIP Committee: we think future SIP(s), using work from SIP-15, can provide more benefit to numerical computing users. The SIP as it exists benefits all users of implicit enrichment classes, and takes us much further to unboxed high performance code. This SIP does not exclude further work towards improving numerical computing in Scala. + ## History | Date | Version | @@ -163,7 +164,7 @@ In our example, the `Meter` class would be expanded as follows: override def toString: String = Meter.extension$toString(this) override def equals(other: Any) = - Meter.extension$equals(this) + Meter.extension$equals(this, other) override def hashCode = Meter.extension$hashCode(this) } @@ -333,7 +334,7 @@ After all 4 steps the `Meter` class is translated to the following code. override def toString: String = Meter.extension$toString(this.underlying) override def equals(other: Any) = - Meter.extension$equals(this) + Meter.extension$equals(this, other) override def hashCode = Meter.extension$hashCode(this) } diff --git a/_sips/sips/wildcard-context-bounds.md b/_sips/sips/wildcard-context-bounds.md new file mode 100644 index 0000000000..7ef71f1f61 --- /dev/null +++ b/_sips/sips/wildcard-context-bounds.md @@ -0,0 +1,6 @@ +--- +title: SIP-52 - Wildcard context bounds +status: withdrawn +pull-request-number: 55 + +--- diff --git a/_sips/sips/xistential-containers.md b/_sips/sips/xistential-containers.md new file mode 100644 index 0000000000..a3f4764c3e --- /dev/null +++ b/_sips/sips/xistential-containers.md @@ -0,0 +1,7 @@ +--- +title: 'SIP-69: Existential containers' +status: under-review +pull-request-number: 101 +stage: design + +--- diff --git a/_style/control-structures.md b/_style/control-structures.md index df74036aee..7a746c46bd 100644 --- a/_style/control-structures.md +++ b/_style/control-structures.md @@ -7,7 +7,7 @@ overview-name: "Style Guide" num: 7 -previous-page: files +previous-page: declarations next-page: method-invocation --- diff --git a/_style/declarations.md b/_style/declarations.md index ca6c389d5c..06fbfadcb7 100644 --- a/_style/declarations.md +++ b/_style/declarations.md @@ -5,48 +5,54 @@ title: Declarations partof: style overview-name: "Style Guide" -num: 9 +num: 6 -previous-page: method-invocation -next-page: scaladoc +previous-page: nested-blocks +next-page: control-structures --- ## Classes -Class/Object/Trait constructors should be declared all on one line, +Class, object, and trait constructors should be declared all on one line, unless the line becomes "too long" (about 100 characters). In that case, -put each constructor argument on its own line, indented **four** spaces: +put each constructor argument on its own line with +[trailing commas](https://docs.scala-lang.org/sips/trailing-commas.html#motivation): class Person(name: String, age: Int) { + … } class Person( - name: String, - age: Int, - birthdate: Date, - astrologicalSign: String, - shoeSize: Int, - favoriteColor: java.awt.Color) { - def firstMethod: Foo = ... + name: String, + age: Int, + birthdate: Date, + astrologicalSign: String, + shoeSize: Int, + favoriteColor: java.awt.Color, + ) { + def firstMethod: Foo = … } If a class/object/trait extends anything, the same general rule applies, put it on one line unless it goes over about 100 characters, and then -indent **four** spaces with each item being on its own line and **two** -spaces for extensions; this provides visual separation between -constructor arguments and extensions: +put each item on its own line with +[trailing commas](https://docs.scala-lang.org/sips/trailing-commas.html#motivation); +closing parenthesis provides visual separation between constructor arguments and extensions; +empty line should be added to further separate extensions from class implementation: class Person( - name: String, - age: Int, - birthdate: Date, - astrologicalSign: String, - shoeSize: Int, - favoriteColor: java.awt.Color) - extends Entity + name: String, + age: Int, + birthdate: Date, + astrologicalSign: String, + shoeSize: Int, + favoriteColor: java.awt.Color, + ) extends Entity with Logging with Identifiable with Serializable { + + def firstMethod: Foo = … } ### Ordering Of Class Elements @@ -96,7 +102,7 @@ Local methods or private methods may omit their return type: #### Procedure Syntax -Avoid the procedure syntax, as it tends to be confusing for very little gain in brevity. +Avoid the (now deprecated) procedure syntax, as it tends to be confusing for very little gain in brevity. // don't do this def printBar(bar: Baz) { @@ -154,7 +160,7 @@ or is of a non-functional nature (some mutable state, local or otherwise), the body must be enclosed in braces: def sum(ls: List[String]): Int = { - val ints = ls map (_.toInt) + val ints = ls.map(_.toInt) ints.foldLeft(0)(_ + _) } @@ -191,7 +197,8 @@ There are three main reasons you should do this: Multiple parameter lists allow you to create your own "control structures": - def unless(exp: Boolean)(code: => Unit): Unit = if (!exp) code + def unless(exp: Boolean)(code: => Unit): Unit = + if (!exp) code unless(x < 5) { println("x was not less than five") } @@ -214,19 +221,36 @@ There are three main reasons you should do this: // If, instead: def foldLeft[B](z: B, op: (B, A) => B): B // above won't work, you must specify types - List("").foldLeft(0, (b: Int, a: String) => a + b.length) + List("").foldLeft(0, (b: Int, a: String) => b + a.length) List("").foldLeft[Int](0, _ + _.length) -For complex DSLs, or with type-names that are long, it can be difficult -to fit the entire signature on one line. In those cases, align the -open-paren of the parameter lists, one list per line (i.e. if you can't -put them all on one line, put one each per line): +For complex DSLs, or with type names that are long, it can be difficult +to fit the entire signature on one line. For those cases there are several +different styles in use: + +1. Split the parameter lists, one parameter per line with +[trailing commas](https://docs.scala-lang.org/sips/trailing-commas.html#motivation) +and parentheses being on separate lines adding to visual separation between +the lists: + + protected def forResource( + resourceInfo: Any, + )( + f: (JsonNode) => Any, + )(implicit + urlCreator: URLCreator, + configurer: OAuthConfiguration, + ): Any = { + ... + } - protected def forResource(resourceInfo: Any) - (f: (JsonNode) => Any) - (implicit urlCreator: URLCreator, configurer: OAuthConfiguration): Any = { - ... - } +2. Or align the open-paren of the parameter lists, one list per line: + + protected def forResource(resourceInfo: Any) + (f: (JsonNode) => Any) + (implicit urlCreator: URLCreator, configurer: OAuthConfiguration): Any = { + ... + } #### Higher-Order Functions @@ -280,11 +304,11 @@ function value. When styles (1) and (4) are used exclusively, it becomes very easy to distinguish places in the source code where function values are used. -Both styles make use of parentheses, since they look clean on a single line. +Both styles make use of parentheses, since they look clean on a single line. ### Spacing -There should be no space between parentheses and the code they contain. +There should be no space between parentheses and the code they contain. Curly braces should be separated from the code within them by a one-space gap, to give the visually busy braces "breathing room". diff --git a/_style/files.md b/_style/files.md index 668ac3c82b..704948ab32 100644 --- a/_style/files.md +++ b/_style/files.md @@ -5,39 +5,38 @@ title: Files partof: style overview-name: "Style Guide" -num: 6 +num: 9 -previous-page: nested-blocks -next-page: control-structures +previous-page: method-invocation +next-page: scaladoc --- -As a rule, files should contain a *single* logical compilation unit. By -"logical" I mean a class, trait or object. One exception to this -guideline is for classes or traits which have companion objects. -Companion objects should be grouped with their corresponding class or -trait in the same file. These files should be named according to the -class, trait or object they contain: +The unit of work for the compiler is a "compilation unit", +which is usually just an ordinary file. +The Scala language places few restrictions on how code is organized across files. +The definition of a class, or equivalently a trait or object, can't be split over multiple files, +so it must be contained within a single file. +A class and its companion object must be defined together in the same file. +A sealed class can be extended only in the same file, so all its subclasses must be defined there. - package com.novell.coolness +Similarly, there are no restrictions on the name of a source file or where it is located in the file system, +although certain conventions are broadly honored in practice. +Generally, the file is named after the class it contains, +or if it has more than one class, the parent class. + +For example, a file, `Inbox.scala`, is expected to contain `Inbox` and its companion: + + package org.coolness class Inbox { ... } // companion object object Inbox { ... } -These compilation units should be placed within a file named -`Inbox.scala` within the `com/novell/coolness` directory. In short, the -Java file naming and positioning conventions should be preferred, -despite the fact that Scala allows for greater flexibility in this -regard. - -## Multi-Unit Files +The file may be located in a directory, `org/coolness`, following Java tooling conventions, +but this is at the discretion of the developer and for their convenience. -Despite what was said above, there are some important situations which -warrant the inclusion of multiple compilation units within a single -file. One common example is that of a sealed trait and several -sub-classes (often emulating the ADT language feature available in -functional languages): +It is natural to put the following `Option` ADT in a file, `Option.scala`: sealed trait Option[+A] @@ -45,26 +44,11 @@ functional languages): case object None extends Option[Nothing] -Because of the nature of sealed superclasses (and traits), all subtypes -*must* be included in the same file. Thus, such a situation definitely -qualifies as an instance where the preference for single-unit files -should be ignored. - -Another case is when multiple classes logically form a single, cohesive -group, sharing concepts to the point where maintenance is greatly served -by containing them within a single file. These situations are harder to -predict than the aforementioned sealed supertype exception. Generally -speaking, if it is *easier* to perform long-term maintenance and -development on several units in a single file rather than spread across -multiple, then such an organizational strategy should be preferred for -these classes. However, keep in mind that when multiple units are -contained within a single file, it is often more difficult to find -specific units when it comes time to make changes. - -**All multi-unit files should be given camelCase names with a lower-case -first letter.** This is a very important convention. It differentiates -multi- from single-unit files, greatly easing the process of finding -declarations. These filenames may be based upon a significant type which -they contain (e.g. `option.scala` for the example above), or may be -descriptive of the logical property shared by all units within (e.g. -`ast.scala`). +The related elements, `Some` and `None`, are easily discoverable, even in the absence of tooling. + +When unrelated classes are grouped together, perhaps because they implement a feature or a model a domain, +the source file receives a descriptive `camelCase` name. +Some prefer this naming scheme for top-level terms. For example, `object project` would be found in `project.scala`. +Similarly, a package object defined as `package object model` is located in `package.scala` in the `model` source directory. + +Files created just for quick testing can have arbitrary names, such as `demo-bug.scala`. diff --git a/_style/index.md b/_style/index.md index 29ae8d16b5..9c126423ca 100644 --- a/_style/index.md +++ b/_style/index.md @@ -20,7 +20,7 @@ This document is intended to outline some basic Scala stylistic guidelines which - [Accessors/Mutators](naming-conventions.html#accessorsmutators) - [Parentheses](naming-conventions.html#parentheses) - [Symbolic Method Names](naming-conventions.html#symbolic-method-names) - - [Constants, Values, Variable and Methods](naming-conventions.html#constants-values-variable-and-methods) + - [Constants, Values and Variables](naming-conventions.html#constants-values-and-variables) - [Type Parameters (generics)](naming-conventions.html#type-parameters-generics) - [Higher-Kinds and Parameterized Type parameters](naming-conventions.html#higher-kinds-and-parameterized-type-parameters) - [Annotations](naming-conventions.html#annotations) @@ -31,7 +31,7 @@ This document is intended to outline some basic Scala stylistic guidelines which - [Annotations](types.html#annotations) - [Ascription](types.html#ascription) - [Functions](types.html#functions) - - [Arity-1](types.html) + - [Arity-1](types.html#arity-1) - [Structural Types](types.html#structural-types) - [Nested Blocks](nested-blocks.html) - [Curly Braces](nested-blocks.html#curly-braces) @@ -40,10 +40,11 @@ This document is intended to outline some basic Scala stylistic guidelines which - [Classes](declarations.html#classes) - [Ordering Of Class Elements](declarations.html#ordering-of-class-elements) - [Methods](declarations.html#methods) + - [Procedure Syntax](declarations.html#procedure-syntax) - [Modifiers](declarations.html#modifiers) - [Body](declarations.html#body) - [Multiple Parameter Lists](declarations.html#multiple-parameter-lists) - - [Higher-Order Functions](declarations.html) + - [Higher-Order Functions](declarations.html#higher-order-functions) - [Fields](declarations.html#fields) - [Function Values](declarations.html#function-values) - [Spacing](declarations.html#spacing) @@ -54,13 +55,10 @@ This document is intended to outline some basic Scala stylistic guidelines which - [Trivial Conditionals](control-structures.html#trivial-conditionals) - [Method Invocation](method-invocation.html) - [Arity-0](method-invocation.html#arity-0) - - [Infix Notation](method-invocation.html#infix-notation) - - [Postfix Notation](method-invocation.html) - - [Arity-1](method-invocation.html) - - [Higher-Order Functions](method-invocation.html) - - [Symbolic methods/Operators](method-invocation.html) + - [Arity-1 (Infix Notation)](method-invocation.html#arity-1-infix-notation) + - [Symbolic Methods/Operators](method-invocation.html#symbolic-methodsoperators) + - [Higher-Order Functions](method-invocation.html#higher-order-functions) - [Files](files.html) - - [Multi-Unit Files](files.html#multi-unit-files) - [Scaladoc](scaladoc.html) - [General Style](scaladoc.html#general-style) - [Packages](scaladoc.html#packages) @@ -72,4 +70,4 @@ This document is intended to outline some basic Scala stylistic guidelines which ### Thanks to ### -[Daniel Spiewak](http://www.codecommit.com/) and [David Copeland](http://www.naildrivin5.com/) for putting this style guide together, and Simon Ochsenreither for converting it to Markdown. +[Daniel Spiewak](https://www.codecommit.com/) and [David Copeland](https://www.naildrivin5.com/) for putting this style guide together, and Simon Ochsenreither for converting it to Markdown. diff --git a/_style/method-invocation.md b/_style/method-invocation.md index bb9fdb3fb9..eb1e548785 100644 --- a/_style/method-invocation.md +++ b/_style/method-invocation.md @@ -8,7 +8,7 @@ overview-name: "Style Guide" num: 8 previous-page: control-structures -next-page: declarations +next-page: files --- Generally speaking, method invocation in Scala follows Java conventions. @@ -51,70 +51,69 @@ acceptable to omit parentheses when calling `queue.size`, but not when calling `println()`. This convention mirrors the method declaration convention given above. -Religiously observing this convention will *dramatically* improve code +Observing this convention improves code readability and will make it much easier to understand at a glance the most basic operation of any given method. Resist the urge to omit parentheses simply to save two characters! -## Infix notation +## Arity-1 (Infix Notation) -Scala has a special punctuation-free syntax for invoking methods that -take one argument. Many Scala programmers use this notation for -symbolic-named methods: +Scala has a special punctuation-free syntax for invoking methods of arity-1 +(one argument). This should generally be avoided, but with the following +exceptions for operators and higher-order functions. In these cases it should +only be used for purely-functional methods (methods with no side-effects). // recommended - a + b + names.mkString(",") - // legal, but less readable - a+b + // also sometimes seen; controversial + names mkString "," - // legal, but definitely strange - a.+(b) + // wrong - has side-effects + javaList add item -but avoid it for almost all alphabetic-named methods: +### Symbolic Methods/Operators - // recommended - names.mkString(",") +Symbolic methods (operators) should always be invoked using infix notation with +spaces separating the target, the operator, and the parameter: - // also sometimes seen; controversial - names mkString "," + // right! + "daniel" + " " + "spiewak" + a + b + + // wrong! + "daniel"+" "+"spiewak" + a+b + a.+(b) -A gray area is short, operator-like methods like `max`, -especially if commutative: +For the most part, this idiom follows Java and Haskell syntactic conventions. A +gray area is short, operator-like methods like `max`, especially if commutative: // fairly common a max b -Symbolic methods which take more than one parameter (they do exist!) -may still be invoked using infix notation, delimited by spaces: +Symbolic methods which take more than one parameter are discouraged. +When they exist, they may still be invoked using infix notation, delimited by spaces: foo ** (bar, baz) -Such methods are fairly rare, however, and should normally be avoided -during API design. For example, the use of the `/:` and `:\` methods -should be avoided in preference to their better-known names, -`foldLeft` and `foldRight`. - -## Postfix Notation +Such methods are fairly rare, however, and should normally be avoided during API +design. For example, the use of the (now deprecated) `/:` and `:\` methods should be avoided in +preference to their better-known names, `foldLeft` and `foldRight`. -Scala allows methods that take no arguments to be invoked using postfix notation: - - // recommended - names.toList +### Higher-Order Functions - // discourage - names toList +Invoking higher-order functions may use parens or braces, but in +either case, use dot notation and omit any space after the method name: -This style is unsafe, and should not be used. Since semicolons are -optional, the compiler will attempt to treat it as an infix method -if it can, potentially taking a term from the next line. + names.map(_.toUpperCase) - names toList - val answer = 42 // will not compile! +These are not recommended: -This may result in unexpected compile errors at best, and happily -compiled faulty code at worst. Although the syntax is used by some -DSLs, it should be considered deprecated, and avoided. + // wrong! missing dot + names map (_.toUpperCase) + // wrong! extra space + names.map (_.toUpperCase) -Since Scala 2.10, using postfix operator notation will result in a -compiler warning. +Experience has shown that these styles make code harder to read, +especially when multiple such method calls are chained. diff --git a/_style/naming-conventions.md b/_style/naming-conventions.md index 6293ee55b0..9ea2bd8084 100644 --- a/_style/naming-conventions.md +++ b/_style/naming-conventions.md @@ -17,6 +17,16 @@ each word is capitalized, except possibly the first word: UpperCamelCase lowerCamelCase +Acronyms should be treated as normal words: + + xHtml + maxId + +instead of: + + XHTML + maxID + Underscores in names (`_`) are not actually forbidden by the compiler, but are strongly discouraged as they have special meaning within the Scala syntax. (But see below @@ -30,6 +40,12 @@ Classes should be named in upper camel case: This mimics the Java naming convention for classes. +Sometimes traits and classes as well as their members are used to describe +formats, documentation or protocols and generate/derive them. +In these cases it is desirable to be close to a 1:1 relation to the output format +and the naming conventions don't apply. In this case, they should only be used +for that specific purpose and not throughout the rest of the code. + ## Objects Object names are like class names (upper camel case). @@ -103,7 +119,7 @@ conventions are used: - In some instances, it is acceptable to prepend "\`is\`" on a boolean accessor (e.g. `isEmpty`). This should only be the case when no corresponding mutator is provided. Please note that the - [Lift](http://liftweb.net) convention of appending "`_?`" to boolean + [Lift](https://liftweb.net) convention of appending "`_?`" to boolean accessors is non-standard and not used outside of the Lift framework. - For mutators, the name of the method should be the name of the @@ -179,44 +195,36 @@ getter and setter. For example: ### Parentheses -Unlike Ruby, Scala attaches significance to whether or not a method is -*declared* with parentheses (only applicable to methods of -[arity](http://en.wikipedia.org/wiki/Arity)-0). For example: +Scala allows a parameterless, zero-[arity](https://en.wikipedia.org/wiki/Arity) +method to be declared with an empty parameter list: def foo1() = ... +or with no parameter lists at all: + def foo2 = ... -These are different methods at compile-time. While `foo1` can be called -with or without the parentheses, `foo2` *may not* be called *with* -parentheses. - -Thus, it is actually quite important that proper guidelines be observed -regarding when it is appropriate to declare a method without parentheses -and when it is not. - -Methods which act as accessors of any sort (either encapsulating a field -or a logical property) should be declared *without* parentheses except -if they have side effects. While Ruby and Lift use a `!` to indicate -this, the usage of parens is preferred (please note that fluid APIs and -internal domain-specific languages have a tendency to break the -guidelines given below for the sake of syntax. Such exceptions should -not be considered a violation so much as a time when these rules do not -apply. In a DSL, syntax should be paramount over convention). - -Further, the callsite should follow the declaration; if declared with -parentheses, call with parentheses. While there is temptation to save a -few characters, if you follow this guideline, your code will be *much* -more readable and maintainable. - - // doesn't change state, call as birthdate - def birthdate = firstName - - // updates our internal state, call as age() - def age() = { - _age = updateAge(birthdate) - _age - } +By convention, parentheses are used to indicate that a method has +side effects, such as altering the receiver. + +On the other hand, the absence of parentheses indicates that a +method is like an accessor: it returns a value without altering the +receiver, and on the same receiver in the same state, it always +returns the same answer. + +The callsite should follow the declaration; if declared with +parentheses, call with parentheses. + +These conventions are followed in the Scala standard library and +you should follow them in your own code as well. + +Additional notes: + +* Scala 3 errors if you leave out the parentheses at the call site. Scala 2 merely warns. +* Scala 3 and 2 both error if the call site has parentheses where the definition doesn't. +* Java-defined methods are exempt from this distinction and may be called either way. +* If a method _does_ take parameters, there isn't any convention for indicating whether it also has side effects. +* Creating an object isn't considered a side effect. So for example, Scala collections have an `iterator` method with no parens. Yes, you get a new iterator each time. And yes, iterators are mutable. But every fresh iterator is the same until it has been altered by calling a side-effecting method such as `Iterator#next()`, which _is_ declared with parentheses. See this [2018 design discussion](https://github.com/scala/collection-strawman/issues/520). ### Symbolic Method Names @@ -250,7 +258,7 @@ advanced feature in Scala, to be used only by those most well-versed in its pitfalls. Without care, excessive use of symbolic method names can easily transform even the simplest code into symbolic soup. -## Constants, Values, Variable and Methods +## Constants, Values and Variables Constant names should be in upper camel case. Similar to Java's `static final` members, if the member is final, immutable and it belongs to a package @@ -262,10 +270,9 @@ object or an object, it may be considered a constant: The value: `Pi` in `scala.math` package is another example of such a constant. -Method, Value and variable names should be in lower camel case: +Value and variable names should be in lower camel case: val myValue = ... - def myMethod = ... var myVariable ## Type Parameters (generics) @@ -306,7 +313,7 @@ used in place of a longer, descriptive name: Higher-kinds are theoretically no different from regular type parameters (except that their -[kind](http://en.wikipedia.org/wiki/Kind_(type_theory)) is at least +[kind](https://en.wikipedia.org/wiki/Kind_(type_theory)) is at least `*=>*` rather than simply `*`). The naming conventions are generally similar, however it is preferred to use a descriptive name rather than a single letter, for clarity: @@ -349,8 +356,7 @@ for local names to be very short: def add(a: Int, b: Int) = a + b -This would be bad practice in languages like Java, but it is *good* -practice in Scala. This convention works because properly-written Scala +This convention works because properly-written Scala methods are quite short, only spanning a single expression and rarely going beyond a few lines. Few local names are used (including parameters), and so there is no need to contrive long, descriptive diff --git a/_style/nested-blocks.md b/_style/nested-blocks.md index 3c489da966..6970f050f9 100644 --- a/_style/nested-blocks.md +++ b/_style/nested-blocks.md @@ -8,7 +8,7 @@ overview-name: "Style Guide" num: 5 previous-page: types -next-page: files +next-page: declarations --- ## Curly Braces diff --git a/_style/scaladoc.md b/_style/scaladoc.md index 6ce4b63fef..12dc9528a5 100644 --- a/_style/scaladoc.md +++ b/_style/scaladoc.md @@ -7,7 +7,7 @@ overview-name: "Style Guide" num: 10 -previous-page: declarations +previous-page: files --- It is important to provide documentation for all packages, classes, @@ -208,7 +208,7 @@ sure to indicate the actual method names: * @return a new Person instance with the age determined by the * birthdate and current date. */ - def apply(name: String, birthDate: java.util.Date) = {} + def apply(name: String, birthDate: java.time.LocalDate) = {} } If your object holds implicit conversions, provide an example in the diff --git a/_style/types.md b/_style/types.md index 87b9a1eb3d..67df05af71 100644 --- a/_style/types.md +++ b/_style/types.md @@ -38,7 +38,7 @@ Function values support a special case of type inference which is worth calling out on its own: val ls: List[String] = ... - ls map (str => str.toInt) + ls.map(str => str.toInt) In cases where Scala already knows the type of the function value we are declaring, there is no need to annotate the parameters (in this case, diff --git a/_th/cheatsheets/index.md b/_th/cheatsheets/index.md index 0b2faca68b..b59cf817a3 100644 --- a/_th/cheatsheets/index.md +++ b/_th/cheatsheets/index.md @@ -1,11 +1,11 @@ --- layout: cheatsheet -title: Scalacheat +title: Scala Cheatsheet partof: cheatsheet by: Brendan O'Connor -about: ขอบคุณ Brendan O'Connor, สำหรับ cheatsheet นี้มีวัตถุประสงค์เพื่ออ้างอิงอย่างง่ายสำหรับโครงสร้างประโยคของ Scala, Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. +about: ขอบคุณ Brendan O'Connor, สำหรับ cheatsheet นี้มีวัตถุประสงค์เพื่ออ้างอิงอย่างง่ายสำหรับโครงสร้างประโยคของ Scala, Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. language: "th" --- @@ -57,18 +57,18 @@ language: "th" | `if (check) happy` _เหมือนกับ_
            `if (check) happy else ()` | เงื่อนไข sugar | | `while (x < 5) { println(x); x += 1}` | ทำซ้ำ while | | `do { println(x); x += 1} while (x < 5)` | ทำซ้ำ do while | -| `import scala.util.control.Breaks._`
            `breakable {`
            ` for (x <- xs) {`
            ` if (Math.random < 0.1) break`
            ` }`
            `}`| หยุด [(slides)](http://www.slideshare.net/Odersky/fosdem-2009-1013261/21) | +| `import scala.util.control.Breaks._`
            `breakable {`
            ` for (x <- xs) {`
            ` if (Math.random < 0.1) break`
            ` }`
            `}`| หยุด [(slides)](https://www.slideshare.net/Odersky/fosdem-2009-1013261/21) | | `for (x <- xs if x%2 == 0) yield x*10`
            _เหมือนกับ_
            `xs.filter(_%2 == 0).map(_*10)` | ทำความเข้าใจ for : filter/map | | `for ((x,y) <- xs zip ys) yield x*y`
            _เหมือนกับ_
            `(xs zip ys) map { case (x,y) => x*y }` | ทำความเข้าใจ for : การเชื่อมโยงโครงสร้างใหม่ | | `for (x <- xs; y <- ys) yield x*y`
            _เหมือนกับ_
            `xs flatMap {x => ys map {y => x*y}}` | ทำความเข้าใจ for : ข้ามผลคูณ | -| `for (x <- xs; y <- ys) {`
            `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
            `}` | ทำความเข้าใจ for : คำอธิบายประเภทจำเป็น [sprintf-style](http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | +| `for (x <- xs; y <- ys) {`
            `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
            `}` | ทำความเข้าใจ for : คำอธิบายประเภทจำเป็น [sprintf-style](https://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | | `for (i <- 1 to 5) {`
            `println(i)`
            `}` | ทำความเข้าใจ for : ทำซ้ำโดยรวมขอบเขตบน | | `for (i <- 1 until 5) {`
            `println(i)`
            `}` | ทำความเข้าใจ for : ทำซ้ำโดยละเว้นขอบเขตบน | | จับคู่รูปแบบ | | | Good
            `(xs zip ys) map { case (x,y) => x*y }`
            Bad
            `(xs zip ys) map( (x,y) => x*y )` | ใช้ case ใน arg ของฟังก์ชันสำหรับ จับคู่รูปแบบ (pattern maching) | -| Bad
            `val v42 = 42`
            `Some(3) match {`
            ` case Some(v42) => println("42")`
            ` case _ => println("Not 42")`
            `}` | "v42" ถูกตีความว่าเป็นชื่อที่ตรงกับค่า Int และพิมพ์ "42" | -| Good
            `val v42 = 42`
            `Some(3) match {`
            `` case Some(`v42`) => println("42")``
            `case _ => println("Not 42")`
            `}` | "v42" กับ backticks ถูกตีความว่าเป็น v42 val ที่มีอยู่และ
            พิมพ์ "Not 42" | -| Good
            `val UppercaseVal = 42`
            `Some(3) match {`
            ` case Some(UppercaseVal) => println("42")`
            ` case _ => println("Not 42")`
            `}` | UppercaseVal ถือว่าเป็น val ที่มีอยู่ไม่ใช่ตัวแปรรูปแบบใหม่
            เพราะมันเริ่มต้นด้วยตัวอักษรตัวพิมพ์ใหญ่ ดังนั้นค่าที่มีอยู่ใน
            UppercaseVal จะถูกตรวจสอบเทียบกับ 3 และพิมพ์ "Not 42" | +| Bad
            `val v42 = 42`
            `Some(3) match {`
            ` case Some(v42) => println("42")`
            ` case _ => println("Not 42")`
            `}` | "v42" ถูกตีความว่าเป็นชื่อที่ตรงกับค่า Int และแสดงค่า "42" | +| Good
            `val v42 = 42`
            `Some(3) match {`
            `` case Some(`v42`) => println("42")``
            `case _ => println("Not 42")`
            `}` | "v42" กับ backticks ถูกตีความว่าเป็น v42 val ที่มีอยู่และ
            แสดงค่า "Not 42" | +| Good
            `val UppercaseVal = 42`
            `Some(3) match {`
            ` case Some(UppercaseVal) => println("42")`
            ` case _ => println("Not 42")`
            `}` | UppercaseVal ถือว่าเป็น val ที่มีอยู่ไม่ใช่ตัวแปรรูปแบบใหม่
            เพราะมันเริ่มต้นด้วยตัวอักษรตัวพิมพ์ใหญ่ ดังนั้นค่าที่มีอยู่ใน
            UppercaseVal จะถูกตรวจสอบเทียบกับ 3 และแสดงค่า "Not 42" | | การใช้งาน object | | | `class C(x: R)` _เหมือนกับ_
            `class C(private val x: R)`
            `var c = new C(4)` | ตัวสร้างพารามิเตอร์ - x มีเฉพาะในคลาส body เท่านั้น | | `class C(val x: R)`
            `var c = new C(4)`
            `c.x` | ตัวสร้างพารามิเตอร์ - กำหนดสมาชิกสาธารณะโดยอัตโนมัติ | diff --git a/_th/tour/abstract-types.md b/_th/tour/abstract-type-members.md similarity index 74% rename from _th/tour/abstract-types.md rename to _th/tour/abstract-type-members.md index e15725cb96..d7f7f51235 100644 --- a/_th/tour/abstract-types.md +++ b/_th/tour/abstract-type-members.md @@ -1,9 +1,6 @@ --- layout: tour -title: Abstract Types - -discourse: false - +title: Abstract Type Members partof: scala-tour num: 21 diff --git a/_th/tour/annotations.md b/_th/tour/annotations.md index f835d5c504..fb171607d0 100644 --- a/_th/tour/annotations.md +++ b/_th/tour/annotations.md @@ -1,15 +1,12 @@ --- layout: tour title: Annotations - -discourse: false - partof: scala-tour num: 30 language: th -next-page: default-parameter-values +next-page: packages-and-imports previous-page: by-name-parameters --- diff --git a/_th/tour/automatic-closures.md b/_th/tour/automatic-closures.md deleted file mode 100644 index 10719b7591..0000000000 --- a/_th/tour/automatic-closures.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: tour -title: Automatic Closures - -discourse: false - -partof: scala-tour - -language: th ---- diff --git a/_th/tour/basics.md b/_th/tour/basics.md index d127d94613..273161fd6a 100644 --- a/_th/tour/basics.md +++ b/_th/tour/basics.md @@ -1,9 +1,6 @@ --- layout: tour -title: Basics - -discourse: false - +title: พื้นฐาน partof: scala-tour num: 2 @@ -13,4 +10,298 @@ next-page: unified-types previous-page: tour-of-scala --- +ในหน้านี้ เราจะครอบคลุมพื้นฐานของ Scala +In this page, we will cover basics of Scala. + +## ทดลอง Scala ในเว็บบราวเซอร์ + +เราสามารถรัน Scala ในเว็บเบราว์เซอร์ด้วย Scastie + +1. ไปที่ [Scastie](https://scastie.scala-lang.org/). +2. วาง `println("Hello, world!")` ในด้านซ้าย. +3. กดที่ปุ่ม "Run" . output จะแสดงในด้านขวา + +ในขั้นตอนนี้ง่ายมาก ที่จะได้ประสบการณ์ของเรากับ Scala + +## Expressions + +Expression หรือ นิพจน์ เป็นโค้ดที่ทำการคำนวนได้ +```scala mdoc +1 + 1 +``` +เราสามารถแสดงผลลัพธ์ของ Expression ด้วยการใช้ `println` + +```scala mdoc +println(1) // 1 +println(1 + 1) // 2 +println("Hello!") // Hello! +println("Hello," + " world!") // Hello, world! +``` + +### Values + +เราสามารถตั้งชื่อของผลลัพธ์ของ expression ด้วย keyword `val` + +```scala mdoc +val x = 1 + 1 +println(x) // 2 +``` + +ตั้งชื่อผลลัพธ์ อย่างเช่น `x` จะเรียก value การอ้างอิง value จะไม่มีการคำนวณอีกครั้ง + +Value ไม่สามารถกำหนดค่าใหม่ได้ + +```scala mdoc:fail +x = 3 // ตรงนี้ไม่ compile. +``` + +type (ชนิด) ของ value สามารถ inferred (อนุมาน) ได้ แต่เราสามารถกำหนดชนิดของ type อย่างชัดเจนได้ แบบนี้ + +```scala mdoc:nest +val x: Int = 1 + 1 +``` + +สังเกตว่า การประกาศชนิดของ type `Int` จะระบุหลังจาก indentifier `x` เราจำเป็นต้องมี `:` + +### Variables + +ตัวแปรเหมือนกับ value ยกเว้นแต่ว่าเราสามารถกำหนดค่าใหม่ได้ เราสามารถกำหนดตัวแปรด้วย keyword `var` + +```scala mdoc:nest +var x = 1 + 1 +x = 3 // ตรงนี้ compile เพราะว่า "x" ถูกประกาศด้วย keyword "var" +println(x * x) // 9 +``` + +เราสามารถกำหนด type ได้ตามที่เราต้องการ: + +```scala mdoc:nest +var x: Int = 1 + 1 +``` + + +## Blocks + +เราสามารถรวมหลายๆ expression ไว้ด้วยกันด้วยการครอบด้วย `{}` เรียกมันว่า block + +ผลลัพธ์ของ expression สุดท้ายใน block จะเป็นผลลัพธ์ของ block ทั้งหมดด้วย + +```scala mdoc +println({ + val x = 1 + 1 + x + 1 +}) // 3 +``` + ## Functions + +function เป็น expression ที่รับ parameter ได้ + +เราสามารถกำหนด anonymous function (เป็น function ที่ไม่มีชื่อ) ที่ return ค่าตัวเลขบวกหนึ่ง: + +```scala mdoc +(x: Int) => x + 1 +``` + +ในด้านซ้ายของ `=>` คือรายการของ parameter ในด้านขวาเป็น expression ที่นำ parameter มาใช้ + +เราสามารถตั้งชื่อของ function ได้ดังนี้ + +```scala mdoc +val addOne = (x: Int) => x + 1 +println(addOne(1)) // 2 +``` + +function สามารถรับ parameter ได้หลายตัว + +```scala mdoc +val add = (x: Int, y: Int) => x + y +println(add(1, 2)) // 3 +``` + +หรือ เราจะไม่รับ parameter เลยก็ได้ + +```scala mdoc +val getTheAnswer = () => 42 +println(getTheAnswer()) // 42 +``` + +## Methods + +Method มีลักษณะเหมือนกับ function มาก แต่ว่าจะมีบางสิ่งที่แตกต่างกันระหว่าง method และ function + +Method จะประกาศได้ด้วย keyword `def` ตามด้วยชื่อของ function, รายการ parameter, return type และ body ของ function + +```scala mdoc:nest +def add(x: Int, y: Int): Int = x + y +println(add(1, 2)) // 3 +``` + +สังเกตว่า การ return type จะประกาศ _หลังจาก_ รายการ parameter และ colon `: Int` + +Method ยังสามารถรับรายการ parameter ได้หลายรายการ + +```scala mdoc +def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier +println(addThenMultiply(1, 2)(3)) // 9 +``` + +หรือ ไม่มีรายการ parameter เลยก็ได้ อย่างเช่น + +```scala mdoc +def name: String = System.getProperty("user.name") +println("Hello, " + name + "!") +``` + +และยังมีบางสิ่งที่แตกต่างกัน แต่ตอนนี้เราจะคิดว่า method มีความเหมือนกับ function + +Method สามารถมี expression ได้หลายบรรทัด + +```scala mdoc +def getSquareString(input: Double): String = { + val square = input * input + square.toString +} +println(getSquareString(2.5)) // 6.25 +``` + +expression สุดท้ายใน body เป็น expression ที่ return value ของ method (Scala ก็มี keyword `return` แต่ว่าไม่ค่อยได้ใช้) + +## Classes + +เราสามารถประกาศ class ได้ด้วย keyword `class` ตามด้วยชื่อของ class และ constructor parameters + +```scala mdoc +class Greeter(prefix: String, suffix: String) { + def greet(name: String): Unit = + println(prefix + name + suffix) +} +``` +return type ของ method `greet` เป็น `Unit` ซึ่งอาจจะกล่าวได้ว่าไม่มีการ return มันใช้เหมือน `void` ใน Java และ C (ความแตกต่างคือทุกๆ expression ของ Scala จำเป็นต้องมีค่า ซึ่งเป็น singleton vlaue จริงๆ ของ Unit เขียนด้วย () ซึ่งไม่มีข้อมูลใดๆ) + +เราสามารถสร้าง instance ของ class ได้ด้วย keyword `new` + +```scala mdoc +val greeter = new Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` + +เราจะครอบคลุมเรื่องของ class ในเชิงลึก [ภายหลัง](classes.html) + +## Case Classes + +Scala มี type ชนิดพิเศษของ class เรียกว่า "case" class โดยเริ่มต้นแล้ว case class เป็นค่าที่เปลี่ยนแปลงไม่ได้ (immutable) และสามารถเปลียบเทียบด้วย value เราสามารถประกาศ case class ด้วย keyword `case class` + +```scala mdoc +case class Point(x: Int, y: Int) +``` + +เราสามารถสร้าง instant ของ case class โดยไม่ต้องใช้ keyword `new` + +```scala mdoc +val point = Point(1, 2) +val anotherPoint = Point(1, 2) +val yetAnotherPoint = Point(2, 2) +``` + +และสามารถเปรียบเทียบค่าของ case class ได้ + +```scala mdoc +if (point == anotherPoint) { + println(s"$point and $anotherPoint are the same.") +} else { + println(s"$point and $anotherPoint are different.") +} // Point(1,2) and Point(1,2) are the same. + +if (point == yetAnotherPoint) { + println(s"$point and $yetAnotherPoint are the same.") +} else { + println(s"$point and $yetAnotherPoint are different.") +} // Point(1,2) and Point(2,2) are different. +``` + +เป็นตัวอย่างการใช้งานของ case class ที่เราอยากจะแนะนำ และอยากให้คุณตกหลุมรักมัน เราจะครอบคลุมในเชิงชึกใน [ภายหลัง](case-classes.html) + +## Objects + +Object เป็น instance เดี่ยวของ definition ของมัน เราสามารถคิดว่ามันเป็น singleton ของ class ที่มันเป็นเจ้าของ + +เราสามารถประกาศ object ได้ด้วย keyword `object` + +```scala mdoc +object IdFactory { + private var counter = 0 + def create(): Int = { + counter += 1 + counter + } +} +``` + +เราสามารถเข้าถึง object ด้วยการอ้างอิงถึงชื่อของมัน + +```scala mdoc +val newId: Int = IdFactory.create() +println(newId) // 1 +val newerId: Int = IdFactory.create() +println(newerId) // 2 +``` + +เราจะครอบคลุมในเชิงลึกใน [ภายหลัง](singleton-objects.html) + +## Traits + +Trait เป็น type ที่บรรจุ field และ method ที่แน่นอน เราสามารถรวม trait หลายๆ trait เข้าด้วยกันได้ + +เราสามารถประกาศ trait ได้ด้วย keyword `trait` + +```scala mdoc:nest +trait Greeter { + def greet(name: String): Unit +} +``` + +Trait สามารถมี default implementation ได้ + +```scala mdoc:reset +trait Greeter { + def greet(name: String): Unit = + println("Hello, " + name + "!") +} +``` + +เราสามารถขยาย traint ได้ด้วย keyword `extents` และ overrid implementation ด้วย keyword `override` + +```scala mdoc +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { + override def greet(name: String): Unit = { + println(prefix + name + postfix) + } +} + +val greeter = new DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = new CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` + +จากตัวอย่างนี้ `defaultGreeter` ขยายเพียง trait เดียว แต่มันสามารถขยายหลาย trait + +เราจะครอบคลุมในเชิงลึกใน [ภายหลัง](traits.html) + +## Main Method + +main method เป็น entry point หรือจุดเริ่มต้นของโปรแกรม ใน ​Java Virtual Machine +ต้องการ main method ชื่อว่า `main` และสามารถรับ argument ที่เป็น array ของ string + +ใช้ object เราสามารถประกาศ main method ได้ดังนี้: + +```scala mdoc +object Main { + def main(args: Array[String]): Unit = + println("Hello, Scala developer!") +} +``` diff --git a/_th/tour/by-name-parameters.md b/_th/tour/by-name-parameters.md index b49e03a9f8..c6f5a71225 100644 --- a/_th/tour/by-name-parameters.md +++ b/_th/tour/by-name-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: By-name Parameters - -discourse: false - partof: scala-tour num: 29 diff --git a/_th/tour/case-classes.md b/_th/tour/case-classes.md index d223a96564..0ac30b5bd8 100644 --- a/_th/tour/case-classes.md +++ b/_th/tour/case-classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Case Classes - -discourse: false - partof: scala-tour num: 10 diff --git a/_th/tour/classes.md b/_th/tour/classes.md index f77415a2e9..3054dbcc8d 100644 --- a/_th/tour/classes.md +++ b/_th/tour/classes.md @@ -1,9 +1,6 @@ --- layout: tour -title: Classes - -discourse: false - +title: คลาส partof: scala-tour num: 4 @@ -13,3 +10,109 @@ language: th next-page: traits previous-page: unified-types --- + +คลาสใน Scala เป็นพิมพ์เขียวสำหรับสร้าง object ในคลาสสามารถมี method, value, ตัวแปร, type, object, +trait และคลาส ซึ่งเรียกรวมๆ กันว่า _members_ หรือ _สมาชิก_ ของคลาส type, object และ trait จะกล่าวถึงภายหลัง + +## การกำหนดคลาส +วิธีการที่ง่ายที่สุดในการกำหนดคลาสด้วยการใช้ keyword `class` และ +identifier ชื่อของคลาสควรจะขึ้นต้นด้วยตัวพิมพ์ใหญ่ +```scala mdoc +class User + +val user1 = new User +``` +keyword `new` ใช้เพื่อสร้าง instance ของคลาส `User` มี constructor เริ่มต้นซึ่งไม่รับค่า argument เพราะว่าไม่ได้กำหนด constructor ไว้ตอนประกาสคลาส + +อย่างไรก็ตาม, เราอาจจะมี constructor และ body ของคลาส +ตัวอย่างดังนี้ เป็นการประกาศคลาสสำหรับจุด (point): + +```scala mdoc +class Point(var x: Int, var y: Int) { + + def move(dx: Int, dy: Int): Unit = { + x = x + dx + y = y + dy + } + + override def toString: String = + s"($x, $y)" +} + +val point1 = new Point(2, 3) +point1.x // 2 +println(point1) // แสดงค่า (2, 3) +``` + +คลาส `Point` นี้มีสมาชิก 4 ตัว คือ ตัวแปร `x` และ `y` และ method `move` และ `toString` +ไม่เหมือนภาษาอื่นๆ, ซึ่ง constructor หลักจะอยู่ใน class signature `(var x: Int, var y: Int)` +method `move` รับ argument ชนิดตัวเลข 2 ตัว และ return เป็นค่า Unit `()` ซึ่งไม่มีค่า +จะมีผลลัพธ์คลายกับ `void` ในภาษาที่เหมือน Java, `toString` ในทางกลับกัน ไม่รับ argument ใดๆ แต่ return เป็นค่า `String` ซึ่งแทนที่ method `toString` จาก [`AnyRef`](unified-types.html) โดยจะมี keyword `override` + +## Constructors + +​Constructor สามารถมี parameter ตัวเลือกได้ โดยกำหนดค่าเริ่มต้นดังนี้: + +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) + +val origin = new Point // x and y are both set to 0 +val point1 = new Point(1) +println(point1.x) // แสดงค่า 1 + +``` + +ในคลาส `Point` ดังกล่าว `x` และ `y` มีค่าเริ่มต้นเป็น `0` ดังนั้นเราสามาถไม่ใส่ argument ก็ได้ +อย่างไรก็ตาม เพราะว่า constructor อ่าน argument จากซ้ายไปขวา ถ้าเราต้องการใส่ค่าใน `y` ไปในคลาส +เราจำเป็นต้องระบุชื่อของ parameter ด้วย +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) +val point2 = new Point(y=2) +println(point2.y) // แสดงค่า 2 +``` + +นี้เป็นวิธีปฏิบัติที่ดีเพื่อจะทำให้โค้ดชัดเจนมากขึ้น + +## Private Members และ Getter/Setter +สมาชิกของคลาสจะเป็น public โดยค่าเริ่มต้น ใช้ access modifier `private` +เพื่อซ่อนสมาชิกนั้นจากภายนอกของคลาส +```scala mdoc:reset +class Point { + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x = _x + def x_= (newValue: Int): Unit = { + if (newValue < bound) _x = newValue else printWarning + } + + def y = _y + def y_= (newValue: Int): Unit = { + if (newValue < bound) _y = newValue else printWarning + } + + private def printWarning = println("WARNING: Out of bounds") +} + +val point1 = new Point +point1.x = 99 +point1.y = 101 // แสดงค่า "WARNING: Out of bounds" +``` +คลาส `Point` เวอร์ชันนี้ ข้อมูลจะถูกเก็บไว้ในตัวแปรชนิด private ที่ชื่อว่า `_x` และ `_y` และมี method ที่ชื่อว่า `def x` และ `def y` ทีจะใช้ในการเข้าถึงข้อมูล private เป็น getter, `def x_=` และ `def y=` +เป็น method สำหรับตรวจสอบข้อมูลและ setting ค่าของตัวแปร `_x` และ `_y` +สังเกตว่า syntax พิเศษนี้สำหรับ setter: คือ method ที่ตามด้วย `_=` ไปยังตัวระบุของ setter และ parameter ตามหลังมา + +constructor หลักกำหนด parameter ด้วย `val` และ `var` เป็น public อย่างไรก็ตามเพราะว่า `val` เป็นตัวแปรที่เปลี่ยนแปลงไม่ได้ (immutable) เราไม่สามารถเขียบแบบนี้ได้ +```scala mdoc:fail +class Point(val x: Int, val y: Int) +val point = new Point(1, 2) +point.x = 3 // <-- ตรงนี้ไม่ compile +``` + +parameter ที่ไม่มี `val` หรือ `var` เป็นค่า private จะมองเห็นได้เพียงข้างในคลาส +```scala mdoc:fail +class Point(x: Int, y: Int) +val point = new Point(1, 2) +point.x // <-- ตรงนี้ไม่ compile +``` diff --git a/_th/tour/compound-types.md b/_th/tour/compound-types.md index cd5f0c5097..fe85ba68f3 100644 --- a/_th/tour/compound-types.md +++ b/_th/tour/compound-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Compound Types - -discourse: false - partof: scala-tour num: 22 @@ -11,5 +8,5 @@ num: 22 language: th next-page: self-types -previous-page: abstract-types +previous-page: abstract-type-members --- diff --git a/_th/tour/default-parameter-values.md b/_th/tour/default-parameter-values.md index e084e0056d..a1165ca22d 100644 --- a/_th/tour/default-parameter-values.md +++ b/_th/tour/default-parameter-values.md @@ -1,9 +1,6 @@ --- layout: tour title: Default Parameter Values - -discourse: false - partof: scala-tour num: 31 diff --git a/_th/tour/extractor-objects.md b/_th/tour/extractor-objects.md index 8bc5a85c51..59f36ca9d8 100644 --- a/_th/tour/extractor-objects.md +++ b/_th/tour/extractor-objects.md @@ -1,9 +1,6 @@ --- layout: tour title: Extractor Objects - -discourse: false - partof: scala-tour num: 14 diff --git a/_th/tour/for-comprehensions.md b/_th/tour/for-comprehensions.md index f9f7bb884c..ee8f42ec44 100644 --- a/_th/tour/for-comprehensions.md +++ b/_th/tour/for-comprehensions.md @@ -1,9 +1,6 @@ --- layout: tour title: For Comprehensions - -discourse: false - partof: scala-tour num: 15 diff --git a/_th/tour/generic-classes.md b/_th/tour/generic-classes.md index 4c6e0a3737..972a1fb018 100644 --- a/_th/tour/generic-classes.md +++ b/_th/tour/generic-classes.md @@ -1,9 +1,6 @@ --- layout: tour title: Generic Classes - -discourse: false - partof: scala-tour num: 16 diff --git a/_th/tour/higher-order-functions.md b/_th/tour/higher-order-functions.md index 2e4c011ebf..24393a6f1f 100644 --- a/_th/tour/higher-order-functions.md +++ b/_th/tour/higher-order-functions.md @@ -1,9 +1,6 @@ --- layout: tour title: Higher-order Functions - -discourse: false - partof: scala-tour num: 7 diff --git a/_th/tour/implicit-conversions.md b/_th/tour/implicit-conversions.md index 4c90f6a68a..600bbb97fa 100644 --- a/_th/tour/implicit-conversions.md +++ b/_th/tour/implicit-conversions.md @@ -1,9 +1,6 @@ --- layout: tour title: Implicit Conversions - -discourse: false - partof: scala-tour num: 25 diff --git a/_th/tour/implicit-parameters.md b/_th/tour/implicit-parameters.md index bfb4694abd..6c908dff73 100644 --- a/_th/tour/implicit-parameters.md +++ b/_th/tour/implicit-parameters.md @@ -1,9 +1,6 @@ --- layout: tour title: Implicit Parameters - -discourse: false - partof: scala-tour num: 24 diff --git a/_th/tour/inner-classes.md b/_th/tour/inner-classes.md index 238772bbbc..82c6164860 100644 --- a/_th/tour/inner-classes.md +++ b/_th/tour/inner-classes.md @@ -1,15 +1,12 @@ --- layout: tour title: Inner Classes - -discourse: false - partof: scala-tour num: 20 language: th -next-page: abstract-types +next-page: abstract-type-members previous-page: lower-type-bounds --- diff --git a/_th/tour/lower-type-bounds.md b/_th/tour/lower-type-bounds.md index 0952413579..6c4e0bf2fe 100644 --- a/_th/tour/lower-type-bounds.md +++ b/_th/tour/lower-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: Lower Type Bounds - -discourse: false - partof: scala-tour num: 19 diff --git a/_th/tour/mixin-class-composition.md b/_th/tour/mixin-class-composition.md index de57c2e0d7..5fe2dfff75 100644 --- a/_th/tour/mixin-class-composition.md +++ b/_th/tour/mixin-class-composition.md @@ -1,9 +1,6 @@ --- layout: tour title: Class Composition with Mixins - -discourse: false - partof: scala-tour num: 6 @@ -11,5 +8,5 @@ num: 6 language: th next-page: higher-order-functions -previous-page: traits +previous-page: tuples --- diff --git a/_th/tour/multiple-parameter-lists.md b/_th/tour/multiple-parameter-lists.md index fea4c0ba20..299bff74a8 100644 --- a/_th/tour/multiple-parameter-lists.md +++ b/_th/tour/multiple-parameter-lists.md @@ -1,9 +1,6 @@ --- layout: tour title: Multiple Parameter Lists (Currying) - -discourse: false - partof: scala-tour num: 9 diff --git a/_th/tour/named-arguments.md b/_th/tour/named-arguments.md index 8a1ace0ff3..0257732c5d 100644 --- a/_th/tour/named-arguments.md +++ b/_th/tour/named-arguments.md @@ -1,9 +1,6 @@ --- layout: tour title: Named Arguments - -discourse: false - partof: scala-tour num: 32 @@ -13,3 +10,56 @@ language: th next-page: packages-and-imports previous-page: default-parameter-values --- + +เมื่อเราเรียกใช้ method แล้วเราสามารถระบุชื่อ argument (label the argument) สำหรับ parameter ใดๆ ได้ดังนี้: + +{% tabs named-arguments-when-good %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-good %} + +```scala mdoc +def printName(first: String, last: String): Unit = + println(s"$first $last") + +printName("John", "Public") // แสดงค่า "John Public" +printName(first = "John", last = "Public") // แสดงค่า "John Public" +printName(last = "Public", first = "John") // แสดงค่า "John Public" +printName("Elton", last = "John") // แสดงค่า "Elton John" +``` + +{% endtab %} + +{% endtabs %} + +named argument นั้นมีประโยชน์เมื่อ parameter 2 ตัวมี type เดียวกัน\ +ทำให้ argument ที่เราส่งไปให้ function อาจถูกสลับกันโดยไม่ได้ตั้งใจ + +สังเกตว่าเราจะเขียน argument ที่ระบุชื่อในลำดับใดก็ได้\ +แต่ถ้า argument ไม่ได้อยู่ในลำดับของ parameter ใน function จากซ้ายไปขวา แล้ว argument ที่เหลือจะต้องระบุชื่อทั้งหมด + +ในตัวอย่างข้างล่างนี้ named argument ทำให้เราสามารถเว้น parameter `middle` ได้\ +แต่ในกรณีที่เกิด `error: positional after named argument`\ +เนื่องจาก argument ตัวแรกไม่ได้เรียงตามลำดับของ parameter (ตัวแรกไม่ใช่ parameter `first` และ argument ตัวที่ 2 เป็นต้นไปก็ไม่ได้ระบุชื่อด้วย)\ +ดังนั้น เราจะต้องระบุชื่อ argument ตั้งแต่ตัวที่ 2 เป็นต้นไป + +{% tabs named-arguments-when-error %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-error %} + +```scala mdoc:fail +def printFullName(first: String, middle: String = "Q.", last: String): Unit = + println(s"$first $middle $last") + +printFullName(first = "John", last = "Public") // แสดงค่า "John Q. Public" +printFullName("John", last = "Public") // แสดงค่า "John Q. Public" +printFullName("John", middle = "Quincy", "Public") // แสดงค่า "John Quincy Public" +printFullName(last = "Public", first = "John") // แสดงค่า "John Q. Public" +printFullName(last = "Public", "John") // error: positional after named argument +``` + +{% endtab %} + +{% endtabs %} + +เราสามารถใช้ Named Argument กับการเรียกใช้ method ของ Java ได้\ +แต่ทำได้เฉพาะในกรณีที่ Java library นั้นถูกคอมไพล์ด้วยออพชั่น `-parameters` เท่านั้น diff --git a/_th/tour/nested-functions.md b/_th/tour/nested-functions.md index 1c4815bd23..c8259de068 100644 --- a/_th/tour/nested-functions.md +++ b/_th/tour/nested-functions.md @@ -1,9 +1,6 @@ --- layout: tour title: Nested Methods - -discourse: false - partof: scala-tour num: 8 diff --git a/_th/tour/operators.md b/_th/tour/operators.md index 1882299bbe..00ddbd248a 100644 --- a/_th/tour/operators.md +++ b/_th/tour/operators.md @@ -1,9 +1,6 @@ --- layout: tour title: Operators - -discourse: false - partof: scala-tour num: 28 diff --git a/_th/tour/package-objects.md b/_th/tour/package-objects.md new file mode 100644 index 0000000000..239fe52468 --- /dev/null +++ b/_th/tour/package-objects.md @@ -0,0 +1,14 @@ +--- +layout: tour +title: Package Objects +language: th +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- + +# Package objects + +(this section of the tour has not been translated yet. pull request +with translation welcome!) diff --git a/_th/tour/packages-and-imports.md b/_th/tour/packages-and-imports.md index 4f6d714a25..fa4dadff53 100644 --- a/_th/tour/packages-and-imports.md +++ b/_th/tour/packages-and-imports.md @@ -1,9 +1,6 @@ --- layout: tour title: Packages and Imports - -discourse: false - partof: scala-tour num: 33 @@ -11,4 +8,5 @@ num: 33 language: th previous-page: named-arguments +next-page: package-objects --- diff --git a/_th/tour/pattern-matching.md b/_th/tour/pattern-matching.md index 08fff9a57a..ceb61f929e 100644 --- a/_th/tour/pattern-matching.md +++ b/_th/tour/pattern-matching.md @@ -1,9 +1,6 @@ --- layout: tour title: Pattern Matching - -discourse: false - partof: scala-tour num: 11 diff --git a/_th/tour/polymorphic-methods.md b/_th/tour/polymorphic-methods.md index 36f0b4f203..c2a0d1c59f 100644 --- a/_th/tour/polymorphic-methods.md +++ b/_th/tour/polymorphic-methods.md @@ -1,9 +1,6 @@ --- layout: tour title: Polymorphic Methods - -discourse: false - partof: scala-tour num: 26 diff --git a/_th/tour/regular-expression-patterns.md b/_th/tour/regular-expression-patterns.md index c6604c0275..c11cf82f35 100644 --- a/_th/tour/regular-expression-patterns.md +++ b/_th/tour/regular-expression-patterns.md @@ -1,9 +1,6 @@ --- layout: tour title: Regular Expression Patterns - -discourse: false - partof: scala-tour num: 13 diff --git a/_th/tour/self-types.md b/_th/tour/self-types.md index 5788e2c1d2..5ba9fc4de1 100644 --- a/_th/tour/self-types.md +++ b/_th/tour/self-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Self-types - -discourse: false - partof: scala-tour num: 23 diff --git a/_th/tour/singleton-objects.md b/_th/tour/singleton-objects.md index a6a1115a77..ba1b910e36 100644 --- a/_th/tour/singleton-objects.md +++ b/_th/tour/singleton-objects.md @@ -1,9 +1,6 @@ --- layout: tour title: Singleton Objects - -discourse: false - partof: scala-tour num: 12 diff --git a/_th/tour/tour-of-scala.md b/_th/tour/tour-of-scala.md index 592e77b4b4..ab75a7d541 100644 --- a/_th/tour/tour-of-scala.md +++ b/_th/tour/tour-of-scala.md @@ -1,9 +1,6 @@ --- layout: tour title: บทนำ - -discourse: false - partof: scala-tour num: 1 @@ -16,7 +13,7 @@ next-page: basics ## ยินดีต้อนรับสู่การเดินทาง การเดินทางครั้งนี้ประกอบด้วยการแนะนำแบบสั้นๆ สำหรับแต่ล่ะคุณสมบัติของ Scala ที่ใช้บ่อยที่สุด และมีมีความตั้งใจเพื่อสำหรับผู้ที่เรียนรู้ภาษา Scala ใหม่ -และนี่ก็เป็นเพียงบทความสั้นๆ ที่ไม่ใช้การสอนเต็มรูปแบบของภาษา Scala หากต้องการเรียนรู้มากขึ้นให้พิจารณา[หนังสือ](/books.html) หรือขอคำปรึกษาจาก[แหล่งอื่นๆ](/learn.html) +และนี่ก็เป็นเพียงบทความสั้นๆ ที่ไม่ใช้การสอนเต็มรูปแบบของภาษา Scala หากต้องการเรียนรู้มากขึ้นให้พิจารณา[หนังสือ](/books.html) หรือขอคำปรึกษาจาก[แหล่งอื่นๆ](/online-courses.html) ## อะไรคือ Scala? Scala เป็นภาษาเขียนโปรแกรมแบบหลากหลายกระบวนทัศน์ที่ทันสมัย ที่ออกแบบมาเพื่อแสดงรูปแบบการเขียนโปรแกรมโดยทั่วไปที่กระชับ สง่างาม และมีชนิดข้อมูลที่ปลอดภัย (type-safe) ซึ่งผสานคุณสมบัติของภาษาเชิงวัตถุและภาษาเชิงฟังก์ชัน @@ -35,7 +32,7 @@ Scala เป็นระบบที่มีลักษณะของชน * [คลาสทั่วไป](generic-classes.html) * [คำอธิบายประกอบผันแปร](variances.html) * ขอบเขตชนิดข้อมูล [ข้างบน](upper-type-bounds.html) และ [ข้างล่าง](lower-type-bounds.html) -* [คลาสภายใน](inner-classes.html) และ [ชนิดข้อมูลนามธรรม](abstract-types.html) เป็นสมาชิกของวัตถุ +* [คลาสภายใน](inner-classes.html) และ [ชนิดข้อมูลนามธรรม](abstract-type-members.html) เป็นสมาชิกของวัตถุ * [ชนิดข้อมูลผสม](compound-types.html) * [อ้างอิงตัวเองของชนิดข้อมูลอย่างชัดเจน](self-types.html) * [พารามิเตอร์ปริยาย](implicit-parameters.html) และ [การเปลี่ยนปริยาย](implicit-conversions.html) @@ -49,7 +46,7 @@ Scala เป็นระบบที่มีลักษณะของชน ในหลายกรณีสามารถทำได้โดยไม่ปราศจากสิ่งอำนวยความสะดวกเมตาดาต้าโปรแกรม อย่างเช่น มาโคร, ตัวอย่างเช่น -* [คลาสโดยปริยาย](http://docs.scala-lang.org/overviews/core/implicit-classes.html) อนุญาติให้เพิ่มขยายเมธอดกับชนิดข้อมูลที่มีอยู่ +* [คลาสโดยปริยาย](https://docs.scala-lang.org/overviews/core/implicit-classes.html) อนุญาติให้เพิ่มขยายเมธอดกับชนิดข้อมูลที่มีอยู่ * [สอดแทรกสตริงตัวอักษร](/overviews/core/string-interpolation.html) คือการขยายโดยผู้ใช้ด้วยตัวสอดแทรกที่กำหนดเอง. ## Scala ทำงานร่วมกันได้ diff --git a/_th/tour/traits.md b/_th/tour/traits.md index 87f1277df6..92dc07597c 100644 --- a/_th/tour/traits.md +++ b/_th/tour/traits.md @@ -1,15 +1,81 @@ --- layout: tour title: Traits - -discourse: false - partof: scala-tour num: 5 language: th -next-page: mixin-class-composition +next-page: tuples previous-page: classes --- + +Trait ใช้เพื่อแชร์ interface และ field ระหว่างคลาส มันจะเหมือนกับ interface ใน Java 8 +คลาส และ object สามารถขยาย trait ได้แต่ trait ไม่สามารถ instant เป็น object และไม่สามารถมี parameter ได้ + +## การกำหนด trait +วิธีที่ง่ายที่สุดในการกำหนด trait คือการประกาศด้วย keyword `trait` และ indentifier: + +```scala mdoc +trait HairColor +``` +trait จะมีประโยชน์อย่างยิ่งด้วยการเป็น generic type และเป็น abstract method +```scala mdoc +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} +``` + +การขยาย `trait Iterator[A]` ต้องการ type `A` และ implementation ของ method `hasNext` และ `next` + +## การใช้ traits +ใช้ keyword `extends` เพื่อขยาย trait ดังนั้นจะ implement abstract member ใดๆ ของ trait โดยใช้ keyword `override`: +```scala mdoc:nest +trait Iterator[A] { + def hasNext: Boolean + def next(): A +} + +class IntIterator(to: Int) extends Iterator[Int] { + private var current = 0 + override def hasNext: Boolean = current < to + override def next(): Int = { + if (hasNext) { + val t = current + current += 1 + t + } else 0 + } +} + + +val iterator = new IntIterator(10) +iterator.next() // returns 0 +iterator.next() // returns 1 +``` +คลาส `IntIterator` นี้รับค่า parameter `to` เป็น upper bound มัน `extends Iterator[Int]` ซึ่งหมายความว่า method `next` จะต้อง return เป็น Int + +## Subtyping +ในเมื่อ trait ที่ให้มานั้น required, subtype ของ trait สามารถถูกใช้แทนที่ได้ +```scala mdoc +import scala.collection.mutable.ArrayBuffer + +trait Pet { + val name: String +} + +class Cat(val name: String) extends Pet +class Dog(val name: String) extends Pet + +val dog = new Dog("Harry") +val cat = new Cat("Sally") + +val animals = ArrayBuffer.empty[Pet] +animals.append(dog) +animals.append(cat) +animals.foreach(pet => println(pet.name)) // แสดงค่า Harry Sally +``` +`trait Pet` มี abstract field `name` ซึ่ง implement โดย Cat และ Dog ใน constructor ของมัน +ในบรรทัดสุดท้าย เราเรียก `pet.name` ซึ่งจะต้องถูก implement แล้วใน subtype ใดๆ ของ trait `Pet` diff --git a/_th/tour/tuples.md b/_th/tour/tuples.md new file mode 100644 index 0000000000..16ae8432df --- /dev/null +++ b/_th/tour/tuples.md @@ -0,0 +1,15 @@ +--- +layout: tour +title: Tuples +partof: scala-tour + +num: + +language: th + +next-page: mixin-class-composition +previous-page: traits +--- + +(this section of the tour has not been translated yet. pull request +with translation welcome!) diff --git a/_th/tour/type-inference.md b/_th/tour/type-inference.md index e10033ab14..f26b01b694 100644 --- a/_th/tour/type-inference.md +++ b/_th/tour/type-inference.md @@ -1,9 +1,6 @@ --- layout: tour title: Type Inference - -discourse: false - partof: scala-tour num: 27 diff --git a/_th/tour/unified-types.md b/_th/tour/unified-types.md index 234932259c..4c2b24c48a 100644 --- a/_th/tour/unified-types.md +++ b/_th/tour/unified-types.md @@ -1,9 +1,6 @@ --- layout: tour -title: Unified Types - -discourse: false - +title: ชนิดข้อมูล partof: scala-tour num: 3 @@ -13,3 +10,70 @@ language: th next-page: classes previous-page: basics --- + +ใน Scala, value ทั้งหมดมี type รวมทั้ง value ที่เป็นตัวเลขและ function ในแผนภาพด้านล่างแสดงให้เห็นโครงสร้างของ type ใน Scala + +Scala Type Hierarchy + +## โครงสร้างของ Type ใน Scala ## + +[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html) เป็น supertype ของ type ทั้งหมด และยังเรียกว่า type บนสุด มันจะกำหนด method ที่ใช้งานร่วมกันอย่างเช่น `equals`, `hashCode` และ `toString` ซึ่ง `Any` มี subclass โดยตรง 2 subclass คือ `AnyVal` และ `AnyRef` + +`AnyVal` แทน value type หรือชนิดข้อมูลที่มีค่า ซึ่งมี 9 value type และเป็นค่าที่ไม่สามารถเป็น null (non-nullable): `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit` และ `Boolean` ซึ่ง `Unit` เป็น value type ที่แทนค่าที่ไม่มีข้อมูล โดยที่มีหนึ่งค่า instance ของ `Unit` ซึ่งสามารถประกาศด้วย `()` ทุก function จำเป็นต้องมีการ return บางสิ่งบางอย่าง ซึ่งก็ `Unit` ก็เป็นค่าที่ใช้เป็น return type + +`AnyREf` แทน reference type หรือชนิดข้อมูลที่ใช้อ้างอิง ทั้งหมดของ type ที่ไม่มี value จะเป็น reference type ทุกๆ type ที่ผู้ใช้งานกำหนด (user-defined) ใน Scal เป็น subtype ของ `AnyRef` ใน Scala ถูกใช้ในบริบทของ Java runtime environment ซึ่ง `AnyRef` จะสอดคล้องกับ `java.lang.Object` ใน Java + +นี่เป็นตัวอย่างที่แสดงให้เห็นการใช้งาน string, integer, charecter, boolean value และ function เป็น object ทั้งหมดที่เหมือนกับ obejct อื่น: + +```scala mdoc +val list: List[Any] = List( + "a string", + 732, // an integer + 'c', // a character + true, // a boolean value + () => "an anonymous function returning a string" +) + +list.foreach(element => println(element)) +``` + +จะกำหนดตัวแปร `list` ของ type `List[Any]` ซึ่งเป็น list ที่สร้างขึ้นด้วยองค์ประกอบของหลายๆ type แต่ว่าทั้งหมดจะเป็น instance ของ `scala.Any` ดังนั้นเราสามารถเพิ่มมันเข้าไปใน list ได้ + +นี่เป็น output ของโปรแกรม: + +``` +a string +732 +c +true + +``` + +## การแปลง Type +Value type สามารถแปลได้ด้วยวิธีดังนี้: +Scala Type Hierarchy + +ตัวอย่างเช่น: + +```scala mdoc +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 (หมายเหตุว่าค่าความละเอียดจะสูญหายไปในกรณีนี้) + +val face: Char = '☺' +val number: Int = face // 9786 +``` + +การแปลงค่าทิศทางเดียว ซึ่งตังอย่างเหล่านี้จะไม่ compile และจะฟ้อง error: + +``` +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 +val z: Long = y // ไม่เป็นไปตามที่ต้องการ +``` + +เราสามารถแปลง reference type ไปเป็น subtype ได้ โดยจะครอบคลุมในภายหลัง + +## Nothing และ Null +`Nothing` เป็น subtype ของ value type ทั้งหมด และยังเรียกว่าเป็น type ล่างสุด ค่าที่ไม่มีค่าจะเป็น type `Nothing` ส่วนมากจะใช้ในกรณี single non-termination อย่างเช่น throw exception, program exit หรือ infinite loop (นั้นคือ มันเป็น type ของ expression ที่ไม่มีการประเมินค่าของ value หรือ method ที่ไม่มีการ return ค่าในแบบปรกติ) + +`Null` เป็น subtype ของ reference type ทั้งหมด (นั้นคือ เป็น subtype ของ AnyRef) มันมีการระบุ value เดียวด้วย keyword `null` ซึ่ง `Null` ใช้ส่วนใหญ่สำหรับการทำงานร่วมกันกับภาษา JVM และไม่ควรใช้ในโค้ดของ Scala เราจะครอบคลุมวิธีการอื่นแทน `null` ในภายหลัง diff --git a/_th/tour/upper-type-bounds.md b/_th/tour/upper-type-bounds.md index a5a0c58d37..9f6fc0dbce 100644 --- a/_th/tour/upper-type-bounds.md +++ b/_th/tour/upper-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour title: Upper Type Bounds - -discourse: false - partof: scala-tour num: 18 diff --git a/_th/tour/variances.md b/_th/tour/variances.md index 497ce5a2fd..0fadcf6471 100644 --- a/_th/tour/variances.md +++ b/_th/tour/variances.md @@ -1,9 +1,6 @@ --- layout: tour title: Variance - -discourse: false - partof: scala-tour num: 17 diff --git a/_tour/abstract-type-members.md b/_tour/abstract-type-members.md new file mode 100644 index 0000000000..aef46a52b2 --- /dev/null +++ b/_tour/abstract-type-members.md @@ -0,0 +1,141 @@ +--- +layout: tour +title: Abstract Type Members +partof: scala-tour +num: 25 +next-page: compound-types +previous-page: inner-classes +topics: abstract type members +prerequisite-knowledge: variance, upper-type-bound + +redirect_from: + - "/tutorials/tour/abstract-types.html" + - "/tour/abstract-types.html" +--- + +Abstract types, such as traits and abstract classes, can in turn have abstract type members. +This means that the concrete implementations define the actual types. +Here's an example: + +{% tabs abstract-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_1 %} +```scala mdoc +trait Buffer { + type T + val element: T +} +``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_1 %} +```scala +trait Buffer: + type T + val element: T +``` +{% endtab %} +{% endtabs %} + +Here we have defined an abstract `type T`. It is used to describe the type of `element`. We can extend this trait in an abstract class, adding an upper-type-bound to `T` to make it more specific. + +{% tabs abstract-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_2 %} +```scala mdoc +abstract class SeqBuffer extends Buffer { + type U + type T <: Seq[U] + def length = element.length +} +``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_2 %} +```scala +abstract class SeqBuffer extends Buffer: + type U + type T <: Seq[U] + def length = element.length +``` +{% endtab %} +{% endtabs %} + +Notice how we can use yet another abstract type `U` in the specification of an upper-type-bound for `T`. This `class SeqBuffer` allows us to store only sequences in the buffer by stating that type `T` has to be a subtype of `Seq[U]` for a new abstract type `U`. + +Traits or [classes](classes.html) with abstract type members are often used in combination with anonymous class instantiations. To illustrate this, we now look at a program which deals with a sequence buffer that refers to a list of integers: + +{% tabs abstract-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_3 %} +```scala mdoc +abstract class IntSeqBuffer extends SeqBuffer { + type U = Int +} + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_3 %} +```scala +abstract class IntSeqBuffer extends SeqBuffer: + type U = Int + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer: + type T = List[U] + val element = List(elem1, elem2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% endtabs %} + +Here the factory `newIntSeqBuf` uses an anonymous class implementation of `IntSeqBuffer` (i.e. `new IntSeqBuffer`) to set the abstract type `T` to the concrete type `List[Int]`. + +It is also possible to turn abstract type members into type parameters of classes and vice versa. Here is a version of the code above which only uses type parameters: + +{% tabs abstract-types_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_4 %} +```scala mdoc:nest +abstract class Buffer[+T] { + val element: T +} +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { + def length = element.length +} + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_4 %} +```scala +abstract class Buffer[+T]: + val element: T + +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T]: + def length = element.length + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]]: + val element = List(e1, e2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% endtabs %} + +Note that we have to use [variance annotations](variances.html) here (`+T <: Seq[U]`) in order to hide the concrete sequence implementation type of the object returned from method `newIntSeqBuf`. Furthermore, there are cases where it is not possible to replace abstract type members with type parameters. diff --git a/_tour/abstract-types.md b/_tour/abstract-types.md deleted file mode 100644 index aded7a17a9..0000000000 --- a/_tour/abstract-types.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -layout: tour -title: Abstract Types - -discourse: true - -partof: scala-tour -num: 23 -next-page: compound-types -previous-page: inner-classes -topics: abstract types -prerequisite-knowledge: variance, upper-type-bound - -redirect_from: "/tutorials/tour/abstract-types.html" ---- - -Traits and abstract classes can have an abstract type member. This means that the concrete implementations define the actual type. Here's an example: - -```tut -trait Buffer { - type T - val element: T -} -``` -Here we have defined an abstract `type T`. It is used to describe the type of `element`. We can extend this trait in an abstract class, adding an upper-type-bound to `T` to make it more specific. - -```tut -abstract class SeqBuffer extends Buffer { - type U - type T <: Seq[U] - def length = element.length -} -``` -Notice how we can use yet another abstract `type U` as an upper-type-bound. This `class SeqBuffer` allows us to store only sequences in the buffer by stating that type `T` has to be a subtype of `Seq[U]` for a new abstract type `U`. - -Traits or [classes](classes.html) with abstract type members are often used in combination with anonymous class instantiations. To illustrate this, we now look at a program which deals with a sequence buffer that refers to a list of integers: - -```tut -abstract class IntSeqBuffer extends SeqBuffer { - type U = Int -} - - -def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = - new IntSeqBuffer { - type T = List[U] - val element = List(elem1, elem2) - } -val buf = newIntSeqBuf(7, 8) -println("length = " + buf.length) -println("content = " + buf.element) -``` -Here the factory `newIntSeqBuf` uses an anonymous class implementation of `IntSeqBuf` (i.e. `new IntSeqBuffer`), setting `type T` to a `List[Int]`. - -It is also possible to turn abstract type members into type parameters of classes and vice versa. Here is a version of the code above which only uses type parameters: - -```tut -abstract class Buffer[+T] { - val element: T -} -abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { - def length = element.length -} - -def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = - new SeqBuffer[Int, List[Int]] { - val element = List(e1, e2) - } - -val buf = newIntSeqBuf(7, 8) -println("length = " + buf.length) -println("content = " + buf.element) -``` - -Note that we have to use [variance annotations](variances.html) here (`+T <: Seq[U]`) in order to hide the concrete sequence implementation type of the object returned from method `newIntSeqBuf`. Furthermore, there are cases where it is not possible to replace abstract types with type parameters. diff --git a/_tour/annotations.md b/_tour/annotations.md index b486d7b806..a9876fab42 100644 --- a/_tour/annotations.md +++ b/_tour/annotations.md @@ -1,27 +1,39 @@ --- layout: tour title: Annotations - -discourse: true - partof: scala-tour -num: 32 -next-page: default-parameter-values +num: 34 +next-page: packages-and-imports previous-page: by-name-parameters redirect_from: "/tutorials/tour/annotations.html" --- Annotations associate meta-information with definitions. For example, the annotation `@deprecated` before a method causes the compiler to print a warning if the method is used. -``` + +{% tabs annotations_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_1 %} +```scala mdoc:fail object DeprecationDemo extends App { @deprecated("deprecation message", "release # which deprecates method") def hello = "hola" - hello + hello } ``` +{% endtab %} +{% tab 'Scala 3' for=annotations_1 %} +```scala +object DeprecationDemo extends App: + @deprecated("deprecation message", "release # which deprecates method") + def hello = "hola" + + hello +``` +{% endtab %} +{% endtabs %} + This will compile but the compiler will print a warning: "there was one deprecation warning". An annotation clause applies to the first definition or declaration following it. More than one annotation clause may precede a definition and declaration. The order in which these clauses are given does not matter. @@ -29,7 +41,10 @@ An annotation clause applies to the first definition or declaration following it ## Annotations that ensure correctness of encodings Certain annotations will actually cause compilation to fail if a condition(s) is not met. For example, the annotation `@tailrec` ensures that a method is [tail-recursive](https://en.wikipedia.org/wiki/Tail_call). Tail-recursion can keep memory requirements constant. Here's how it's used in a method which calculates the factorial: -```tut + +{% tabs annotations_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_2 %} +```scala mdoc import scala.annotation.tailrec def factorial(x: Int): Int = { @@ -41,8 +56,26 @@ def factorial(x: Int): Int = { factorialHelper(x, 1) } ``` -The `factorialHelper` method has the `@tailrec` which ensures the method is indeed tail-recursive. If we were to change the implementation of `factorialHelper` to the following, it would fail: +{% endtab %} +{% tab 'Scala 3' for=annotations_2 %} +```scala +import scala.annotation.tailrec + +def factorial(x: Int): Int = + + @tailrec + def factorialHelper(x: Int, accumulator: Int): Int = + if x == 1 then accumulator else factorialHelper(x - 1, accumulator * x) + factorialHelper(x, 1) ``` +{% endtab %} +{% endtabs %} + +The `factorialHelper` method has the `@tailrec` which ensures the method is indeed tail-recursive. If we were to change the implementation of `factorialHelper` to the following, it would fail: + +{% tabs annotations_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_3 %} +```scala mdoc:fail import scala.annotation.tailrec def factorial(x: Int): Int = { @@ -53,76 +86,134 @@ def factorial(x: Int): Int = { factorialHelper(x) } ``` -We would get the message "Recursive call not in tail position". +{% endtab %} +{% tab 'Scala 3' for=annotations_3 %} +```scala +import scala.annotation.tailrec +def factorial(x: Int): Int = + @tailrec + def factorialHelper(x: Int): Int = + if x == 1 then 1 else x * factorialHelper(x - 1) + factorialHelper(x) +``` +{% endtab %} +{% endtabs %} + +We would get the message "Recursive call not in tail position". ## Annotations affecting code generation + +{% tabs annotations_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_4 %} + Some annotations like `@inline` affect the generated code (i.e. your jar file might have different bytes than if you hadn't used the annotation). Inlining means inserting the code in a method's body at the call site. The resulting bytecode is longer, but hopefully runs faster. Using the annotation `@inline` does not ensure that a method will be inlined, but it will cause the compiler to do it if and only if some heuristics about the size of the generated code are met. +{% endtab %} +{% tab 'Scala 3' for=annotations_4 %} + +Some annotations like `@main` affect the generated code (i.e. your jar file might have different bytes than if you hadn't used the annotation). A `@main` annotation on a method generates an executable program that calls the method as an entry point. + +{% endtab %} +{% endtabs %} + ### Java Annotations ### When writing Scala code which interoperates with Java, there are a few differences in annotation syntax to note. **Note:** Make sure you use the `-target:jvm-1.8` option with Java annotations. Java has user-defined metadata in the form of [annotations](https://docs.oracle.com/javase/tutorial/java/annotations/). A key feature of annotations is that they rely on specifying name-value pairs to initialize their elements. For instance, if we need an annotation to track the source of some class we might define it as -``` +{% tabs annotations_5 %} +{% tab 'Java' for=annotations_5 %} +```java @interface Source { - public String URL(); + public String url(); public String mail(); } ``` +{% endtab %} +{% endtabs %} And then apply it as follows -``` -@Source(URL = "http://coders.com/", +{% tabs annotations_6 %} +{% tab 'Java' for=annotations_6 %} +```java +@Source(url = "https://coders.com/", mail = "support@coders.com") -public class MyClass extends HisClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -An annotation application in Scala looks like a constructor invocation, for instantiating a Java annotation one has to use named arguments: +An annotation application in Scala looks like a constructor invocation, but to instantiate a Java annotation one has to use named arguments: -``` -@Source(URL = "http://coders.com/", +{% tabs annotations_7 %} +{% tab 'Scala 2 and 3' for=annotations_7 %} +```scala +@Source(url = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} This syntax is quite tedious if the annotation contains only one element (without default value) so, by convention, if the name is specified as `value` it can be applied in Java using a constructor-like syntax: -``` +{% tabs annotations_8 %} +{% tab 'Java' for=annotations_8 %} +```java @interface SourceURL { public String value(); public String mail() default ""; } ``` +{% endtab %} +{% endtabs %} -And then apply it as follows +And then apply it as follows: +{% tabs annotations_9 %} +{% tab 'Java' for=annotations_9 %} +```java +@SourceURL("https://coders.com/") +public class MyJavaClass extends TheirClass ... ``` -@SourceURL("http://coders.com/") -public class MyClass extends HisClass ... -``` +{% endtab %} +{% endtabs %} -In this case, Scala provides the same possibility +In this case, Scala provides the same possibility: -``` -@SourceURL("http://coders.com/") +{% tabs annotations_10 %} +{% tab 'Scala 2 and 3' for=annotations_10 %} +```scala +@SourceURL("https://coders.com/") class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} -The `mail` element was specified with a default value so we need not explicitly provide a value for it. However, if we need to do it we can not mix-and-match the two styles in Java: +The `mail` element was specified with a default value so we need not explicitly provide a value for it. +However, if we need to provide one then in Java we must also explicitly name the `value` parameter: -``` -@SourceURL(value = "http://coders.com/", +{% tabs annotations_11 %} +{% tab 'Java' for=annotations_11 %} +```java +@SourceURL(value = "https://coders.com/", mail = "support@coders.com") -public class MyClass extends HisClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -Scala provides more flexibility in this respect +Scala provides more flexibility in this respect, so we can choose to only name the `mail` parameter: -``` -@SourceURL("http://coders.com/", +{% tabs annotations_12 %} +{% tab 'Scala 2 and 3' for=annotations_12 %} +```scala +@SourceURL("https://coders.com/", mail = "support@coders.com") - class MyScalaClass ... +class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} diff --git a/_tour/automatic-closures.md b/_tour/automatic-closures.md deleted file mode 100644 index 37b82524ef..0000000000 --- a/_tour/automatic-closures.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -layout: tour -title: Automatic Type-Dependent Closure Construction - -discourse: true - -partof: scala-tour ---- - -Scala allows parameterless function names as parameters of methods. When such a method is called, the actual parameters for parameterless function names are not evaluated and a nullary function is passed instead which encapsulates the computation of the corresponding parameter (so-called *call-by-name* evalutation). - -The following code demonstrates this mechanism: - - object TargetTest1 extends Application { - def whileLoop(cond: => Boolean)(body: => Unit): Unit = - if (cond) { - body - whileLoop(cond)(body) - } - var i = 10 - whileLoop (i > 0) { - println(i) - i -= 1 - } - } - -The function whileLoop takes two parameters `cond` and `body`. When the function is applied, the actual parameters do not get evaluated. But whenever the formal parameters are used in the body of `whileLoop`, the implicitly created nullary functions will be evaluated instead. Thus, our method `whileLoop` implements a Java-like while-loop with a recursive implementation scheme. - -We can combine the use of [infix/postfix operators](operators.html) with this mechanism to create more complex statements (with a nice syntax). - -Here is the implementation of a loop-unless statement: - - object TargetTest2 extends Application { - def loop(body: => Unit): LoopUnlessCond = - new LoopUnlessCond(body) - protected class LoopUnlessCond(body: => Unit) { - def unless(cond: => Boolean) { - body - if (!cond) unless(cond) - } - } - var i = 10 - loop { - println("i = " + i) - i -= 1 - } unless (i == 0) - } -The `loop` function just accepts a body of a loop and returns an instance of class `LoopUnlessCond` (which encapsulates this body object). Note that the body didn't get evaluated yet. Class `LoopUnlessCond` has a method `unless` which we can use as a *infix operator*. This way, we achieve a quite natural syntax for our new loop: `loop { < stats > } unless ( < cond > )`. - -Here's the output when `TargetTest2` gets executed: - - i = 10 - i = 9 - i = 8 - i = 7 - i = 6 - i = 5 - i = 4 - i = 3 - i = 2 - i = 1 diff --git a/_tour/basics.md b/_tour/basics.md index c9a0486c27..ccfb324feb 100644 --- a/_tour/basics.md +++ b/_tour/basics.md @@ -1,9 +1,6 @@ --- layout: tour title: Basics - -discourse: true - partof: scala-tour num: 2 @@ -13,235 +10,364 @@ previous-page: tour-of-scala redirect_from: "/tutorials/tour/basics.html" --- -In this page, we will cover basics of Scala. +In this page, we will cover the basics of Scala. ## Trying Scala in the Browser -You can run Scala in your browser with ScalaFiddle. +You can run Scala in your browser with _Scastie_. This is an easy, zero-setup way to experiment with pieces of Scala code: -1. Go to [https://scalafiddle.io](https://scalafiddle.io). +1. Go to [Scastie](https://scastie.scala-lang.org/). 2. Paste `println("Hello, world!")` in the left pane. -3. Hit "Run" button. Output appears in the right pane. - -This is an easy, zero-setup way to experiment with pieces of Scala code. - -Many of the code examples in this documentation are also integrated with ScalaFiddle, so you -can directly experiment with them simply by clicking the Run-button. +3. Click __Run__. The output appears in the right pane. ## Expressions -Expressions are computable statements. -``` +Expressions are computable statements: + +{% tabs expression %} +{% tab 'Scala 2 and 3' for=expression %} +```scala mdoc 1 + 1 ``` -You can output results of expressions using `println`. +{% endtab %} +{% endtabs %} + +You can output the results of expressions using `println`: -{% scalafiddle %} -```tut +{% tabs println %} +{% tab 'Scala 2 and 3' for=println %} +```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! println("Hello," + " world!") // Hello, world! ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} ### Values -You can name results of expressions with the `val` keyword. +You can name the results of expressions using the `val` keyword: -```tut +{% tabs val %} +{% tab 'Scala 2 and 3' for=val %} +```scala mdoc val x = 1 + 1 println(x) // 2 ``` +{% endtab %} +{% endtabs %} Named results, such as `x` here, are called values. Referencing a value does not re-compute it. -Values cannot be re-assigned. +Values cannot be re-assigned: -```tut:fail +{% tabs val-error %} +{% tab 'Scala 2 and 3' for=val-error %} +```scala mdoc:fail x = 3 // This does not compile. ``` +{% endtab %} +{% endtabs %} -Types of values can be inferred, but you can also explicitly state the type, like this: +The type of a value can be omitted and [inferred](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated: -```tut +{% tabs type-inference %} +{% tab 'Scala 2 and 3' for=type-inference %} +```scala mdoc:nest val x: Int = 1 + 1 ``` +{% endtab %} +{% endtabs %} -Notice how the type declaration `Int` comes after the identifier `x`. You also need a `:`. +Notice how the type declaration `Int` comes after the identifier `x`. You also need a `:`. ### Variables Variables are like values, except you can re-assign them. You can define a variable with the `var` keyword. -```tut +{% tabs var %} +{% tab 'Scala 2 and 3' for=var %} +```scala mdoc:nest var x = 1 + 1 x = 3 // This compiles because "x" is declared with the "var" keyword. println(x * x) // 9 ``` +{% endtab %} +{% endtabs %} -As with values, you can explicitly state the type if you want: +As with values, the type of a variable can be omitted and [inferred](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated: -```tut +{% tabs type-inference-2 %} +{% tab 'Scala 2 and 3' for=type-inference-2 %} +```scala mdoc:nest var x: Int = 1 + 1 ``` +{% endtab %} +{% endtabs %} ## Blocks You can combine expressions by surrounding them with `{}`. We call this a block. -The result of the last expression in the block is the result of the overall block, too. +The result of the last expression in the block is the result of the overall block, too: -```tut +{% tabs blocks %} +{% tab 'Scala 2 and 3' for=blocks %} +```scala mdoc println({ val x = 1 + 1 x + 1 }) // 3 ``` +{% endtab %} +{% endtabs %} ## Functions -Functions are expressions that take parameters. +Functions are expressions that have parameters, and take arguments. -You can define an anonymous function (i.e. no name) that returns a given integer plus one: +You can define an anonymous function (i.e., a function that has no name) that returns a given integer plus one: -```tut +{% tabs anonymous-function %} +{% tab 'Scala 2 and 3' for=anonymous-function %} +```scala mdoc (x: Int) => x + 1 ``` +{% endtab %} +{% endtabs %} On the left of `=>` is a list of parameters. On the right is an expression involving the parameters. -You can also name functions. +You can also name functions: -{% scalafiddle %} -```tut +{% tabs named-function %} +{% tab 'Scala 2 and 3' for=named-function %} +```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} -Functions may take multiple parameters. +A function can have multiple parameters: -{% scalafiddle %} -```tut +{% tabs multiple-parameters %} +{% tab 'Scala 2 and 3' for=multiple-parameters %} +```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} -Or it can take no parameters. +Or it can have no parameters at all: -```tut +{% tabs no-parameters %} +{% tab 'Scala 2 and 3' for=no-parameters %} +```scala mdoc val getTheAnswer = () => 42 println(getTheAnswer()) // 42 ``` +{% endtab %} +{% endtabs %} ## Methods Methods look and behave very similar to functions, but there are a few key differences between them. -Methods are defined with the `def` keyword. `def` is followed by a name, parameter lists, a return type, and a body. +Methods are defined with the `def` keyword. `def` is followed by a name, parameter list(s), a return type, and a body: -{% scalafiddle %} -```tut +{% tabs method %} +{% tab 'Scala 2 and 3' for=method %} +```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} -Notice how the return type is declared _after_ the parameter list and a colon `: Int`. +Notice how the return type `Int` is declared _after_ the parameter list and a `:`. -Methods can take multiple parameter lists. +A method can take multiple parameter lists: -{% scalafiddle %} -```tut +{% tabs multiple-parameter-lists %} +{% tab 'Scala 2 and 3' for=multiple-parameter-lists %} +```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} -Or no parameter lists at all. +Or no parameter lists at all: -```tut +{% tabs no-parameter-lists %} +{% tab 'Scala 2 and 3' for=no-parameter-lists %} +```scala mdoc def name: String = System.getProperty("user.name") println("Hello, " + name + "!") ``` +{% endtab %} +{% endtabs %} + +There are some other differences, but for now, you can think of methods as something similar to functions. + +Methods can have multi-line expressions as well: -There are some other differences, but for now, you can think of them as something similar to functions. +{% tabs get-square-string class=tabs-scala-version %} -Methods can have multi-line expressions as well. -```tut +{% tab 'Scala 2' for=get-square-string %} +```scala mdoc def getSquareString(input: Double): String = { val square = input * input square.toString } +println(getSquareString(2.5)) // 6.25 ``` -The last expression in the body is the method's return value. (Scala does have a `return` keyword, but it's rarely used.) +{% endtab %} + +{% tab 'Scala 3' for=get-square-string %} +```scala +def getSquareString(input: Double): String = + val square = input * input + square.toString + +println(getSquareString(2.5)) // 6.25 +``` +{% endtab %} + +{% endtabs %} + +The last expression in the body is the method's return value. (Scala does have a `return` keyword, but it is rarely used.) ## Classes -You can define classes with the `class` keyword followed by its name and constructor parameters. +You can define classes with the `class` keyword, followed by its name and constructor parameters: -```tut +{% tabs greeter-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-definition %} +```scala mdoc class Greeter(prefix: String, suffix: String) { def greet(name: String): Unit = println(prefix + name + suffix) } ``` -The return type of the method `greet` is `Unit`, which says there's nothing meaningful to return. It's used similarly to `void` in Java and C. (A difference is that because every Scala expression must have some value, there is actually a singleton value of type Unit, written (). It carries no information.) +{% endtab %} -You can make an instance of a class with the `new` keyword. +{% tab 'Scala 3' for=greeter-definition %} +```scala +class Greeter(prefix: String, suffix: String): + def greet(name: String): Unit = + println(prefix + name + suffix) +``` +{% endtab %} + +{% endtabs %} + +The return type of the method `greet` is `Unit`, which signifies that there is nothing meaningful to return. It is used similarly to `void` in Java and C. (A difference is that, because every Scala expression must have some value, there is actually a singleton value of type Unit, written (). It carries no information.) + +In Scala 2 you can make an instance of a class with the `new` keyword. In Scala 3, however, the `new` keyword is not needed thanks to [universal apply methods](https://docs.scala-lang.org/scala3/reference/other-new-features/creator-applications.html): -```tut +{% tabs greeter-usage class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-usage %} +```scala mdoc:nest val greeter = new Greeter("Hello, ", "!") greeter.greet("Scala developer") // Hello, Scala developer! ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-usage %} +```scala +val greeter = Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` +{% endtab %} + +{% endtabs %} We will cover classes in depth [later](classes.html). ## Case Classes -Scala has a special type of class called a "case" class. By default, case classes are immutable and compared by value. You can define case classes with the `case class` keywords. +Scala has a special type of class called a "case" class. By default, instances of case classes are immutable, and they are compared by value (unlike classes, whose instances are compared by reference). This makes them additionally useful for [pattern matching](https://docs.scala-lang.org/tour/pattern-matching.html#matching-on-case-classes). + +You can define case classes with the `case class` keywords: -```tut +{% tabs case-class-definition %} +{% tab 'Scala 2 and 3' for=case-class-definition %} +```scala mdoc case class Point(x: Int, y: Int) ``` +{% endtab %} +{% endtabs %} -You can instantiate case classes without `new` keyword. +You can instantiate case classes without the `new` keyword: -```tut +{% tabs case-class-creation %} +{% tab 'Scala 2 and 3' for=case-class-creation %} +```scala mdoc val point = Point(1, 2) val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) ``` +{% endtab %} +{% endtabs %} -And they are compared by value. +Instances of case classes are compared by value, not by reference: -```tut +{% tabs compare-case-class-equality class=tabs-scala-version %} + +{% tab 'Scala 2' for=compare-case-class-equality %} +```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) and Point(1,2) are the same. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) and Point(2,2) are different. ``` +{% endtab %} + +{% tab 'Scala 3' for=compare-case-class-equality %} +```scala +if point == anotherPoint then + println(s"$point and $anotherPoint are the same.") +else + println(s"$point and $anotherPoint are different.") +// ==> Point(1,2) and Point(1,2) are the same. + +if point == yetAnotherPoint then + println(s"$point and $yetAnotherPoint are the same.") +else + println(s"$point and $yetAnotherPoint are different.") +// ==> Point(1,2) and Point(2,2) are different. +``` +{% endtab %} -There is a lot more to case classes that we'd like to introduce, and we are convinced you will fall in love with them! We will cover them in depth [later](case-classes.html). +{% endtabs %} + +There is a lot more to case classes that we would like to introduce, and we are convinced you will fall in love with them! We will cover them in depth [later](case-classes.html). ## Objects Objects are single instances of their own definitions. You can think of them as singletons of their own classes. -You can define objects with the `object` keyword. +You can define objects with the `object` keyword: + +{% tabs id-factory-definition class=tabs-scala-version %} -```tut +{% tab 'Scala 2' for=id-factory-definition %} +```scala mdoc object IdFactory { private var counter = 0 def create(): Int = { @@ -250,43 +376,89 @@ object IdFactory { } } ``` +{% endtab %} + +{% tab 'Scala 3' for=id-factory-definition %} +```scala +object IdFactory: + private var counter = 0 + def create(): Int = + counter += 1 + counter +``` +{% endtab %} -You can access an object by referring to its name. +{% endtabs %} -```tut +You can access an object by referring to its name: + +{% tabs id-factory-usage %} +{% tab 'Scala 2 and 3' for=id-factory-usage %} +```scala mdoc val newId: Int = IdFactory.create() println(newId) // 1 val newerId: Int = IdFactory.create() println(newerId) // 2 ``` +{% endtab %} +{% endtabs %} We will cover objects in depth [later](singleton-objects.html). ## Traits -Traits are types containing certain fields and methods. Multiple traits can be combined. +Traits are abstract data types containing certain fields and methods. In Scala inheritance, a class can only extend one other class, but it can extend multiple traits. + +You can define traits with the `trait` keyword: -You can define traits with `trait` keyword. +{% tabs greeter-trait-def class=tabs-scala-version %} -```tut +{% tab 'Scala 2' for=greeter-trait-def %} +```scala mdoc:nest trait Greeter { def greet(name: String): Unit } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def %} +```scala +trait Greeter: + def greet(name: String): Unit +``` +{% endtab %} + +{% endtabs %} -Traits can also have default implementations. +Traits can also have default implementations: -{% scalafiddle %} -```tut +{% tabs greeter-trait-def-impl class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-trait-def-impl %} +```scala mdoc:reset trait Greeter { def greet(name: String): Unit = println("Hello, " + name + "!") } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def-impl %} +```scala +trait Greeter: + def greet(name: String): Unit = + println("Hello, " + name + "!") +``` +{% endtab %} -You can extend traits with the `extends` keyword and override an implementation with the `override` keyword. +{% endtabs %} -```tut +You can extend traits with the `extends` keyword and override an implementation with the `override` keyword: + +{% tabs greeter-implementations class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-implementations %} +```scala mdoc class DefaultGreeter extends Greeter class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { @@ -301,23 +473,61 @@ greeter.greet("Scala developer") // Hello, Scala developer! val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` -{% endscalafiddle %} +{% endtab %} -Here, `DefaultGreeter` extends only a single trait, but it could extend multiple traits. +{% tab 'Scala 3' for=greeter-implementations %} +```scala +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter: + override def greet(name: String): Unit = + println(prefix + name + postfix) + +val greeter = DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` +{% endtab %} + +{% endtabs %} + +Here, `DefaultGreeter` extends only one single trait, but it could extend multiple traits. We will cover traits in depth [later](traits.html). -## Main Method +## Program Entry Point + +The main method is the entry point of a Scala program. The Java Virtual +Machine requires a main method, named `main`, that takes one +argument: an array of strings. -The main method is an entry point of a program. The Java Virtual -Machine requires a main method to be named `main` and take one -argument, an array of strings. +{% tabs hello-world-demo class=tabs-scala-version %} -Using an object, you can define a main method as follows: +{% tab 'Scala 2' for=hello-world-demo %} -```tut +In Scala 2 you must define a main method manually. Using an object, you can define the main method as follows: + +```scala mdoc object Main { def main(args: Array[String]): Unit = println("Hello, Scala developer!") } ``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} + +In Scala 3, with the `@main` annotation, a main method is automatically generated from a method as follows: + +```scala +@main def hello() = println("Hello, Scala developer!") +``` +{% endtab %} + +{% endtabs %} + +## More resources + +* [Scala book](/scala3/book/taste-intro.html) overview diff --git a/_tour/by-name-parameters.md b/_tour/by-name-parameters.md index b9648a21f4..441aefa597 100644 --- a/_tour/by-name-parameters.md +++ b/_tour/by-name-parameters.md @@ -1,27 +1,33 @@ --- layout: tour title: By-name Parameters - -discourse: true - partof: scala-tour -num: 31 +num: 33 next-page: annotations previous-page: operators redirect_from: "/tutorials/tour/by-name-parameters.html" +redirect_from: "/tutorials/tour/automatic-closures.html" --- -_By-name parameters_ are only evaluated when used. They are in contrast to _by-value parameters_. To make a parameter called by-name, simply prepend `=>` to its type. -```tut +_By-name parameters_ are evaluated every time they are used. They won't be evaluated at all if they are unused. This is similar to replacing the by-name parameters with the passed expressions. They are in contrast to _by-value parameters_. To make a parameter called by-name, simply prepend `=>` to its type. + +{% tabs by-name-parameters_1 %} +{% tab 'Scala 2 and 3' for=by-name-parameters_1 %} +```scala mdoc def calculate(input: => Int) = input * 37 ``` +{% endtab %} +{% endtabs %} + By-name parameters have the advantage that they are not evaluated if they aren't used in the function body. On the other hand, by-value parameters have the advantage that they are evaluated only once. Here's an example of how we could implement a while loop: -```tut +{% tabs by-name-parameters_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=by-name-parameters_2 %} +```scala mdoc def whileLoop(condition: => Boolean)(body: => Unit): Unit = if (condition) { body @@ -35,6 +41,24 @@ whileLoop (i > 0) { i -= 1 } // prints 2 1 ``` +{% endtab %} +{% tab 'Scala 3' for=by-name-parameters_2 %} +```scala +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if condition then + body + whileLoop(condition)(body) + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // prints 2 1 +``` +{% endtab %} +{% endtabs %} + The method `whileLoop` uses multiple parameter lists to take a condition and a body of the loop. If the `condition` is true, the `body` is executed and then a recursive call to whileLoop is made. If the `condition` is false, the body is never evaluated because we prepended `=>` to the type of `body`. Now when we pass `i > 0` as our `condition` and `println(i); i-= 1` as the `body`, it behaves like the standard while loop in many languages. diff --git a/_tour/case-classes.md b/_tour/case-classes.md index 607e449d0e..889f8e98bc 100644 --- a/_tour/case-classes.md +++ b/_tour/case-classes.md @@ -1,12 +1,9 @@ --- layout: tour title: Case Classes - -discourse: true - partof: scala-tour -num: 11 +num: 13 next-page: pattern-matching previous-page: multiple-parameter-lists prerequisite-knowledge: classes, basics, mutability @@ -18,14 +15,26 @@ Case classes are like regular classes with a few key differences which we will g ## Defining a case class A minimal case class requires the keywords `case class`, an identifier, and a parameter list (which may be empty): -```tut + +{% tabs case-classe_Book %} + +{% tab 'Scala 2 and 3' for=case-classe_Book %} +```scala mdoc case class Book(isbn: String) val frankenstein = Book("978-0486282114") ``` -Notice how the keyword `new` was not used to instantiate the `Book` case class. This is because case classes have an `apply` method by default which takes care of object construction. +{% endtab %} + +{% endtabs %} + +Although that is usually left out, it is possible to explicitly use the `new` keyword, as `new Book()`. This is because case classes have an `apply` method by default which takes care of object construction. When you create a case class with parameters, the parameters are public `val`s. + +{% tabs case-classe_Message_define %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_define %} ``` case class Message(sender: String, recipient: String, body: String) val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") @@ -33,22 +42,38 @@ val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") println(message1.sender) // prints guillaume@quebec.ca message1.sender = "travis@washington.us" // this line does not compile ``` +{% endtab %} + +{% endtabs %} + You can't reassign `message1.sender` because it is a `val` (i.e. immutable). It is possible to use `var`s in case classes but this is discouraged. ## Comparison -Case classes are compared by structure and not by reference: -``` +Instances of case classes are compared by structure and not by reference: + +{% tabs case-classe_Message_compare %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_compare %} +```scala mdoc case class Message(sender: String, recipient: String, body: String) val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") val messagesAreTheSame = message2 == message3 // true ``` +{% endtab %} + +{% endtabs %} + Even though `message2` and `message3` refer to different objects, the value of each object is equal. ## Copying You can create a (shallow) copy of an instance of a case class simply by using the `copy` method. You can optionally change the constructor arguments. -``` + +{% tabs case-classe_Message_copy %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_copy %} +```scala mdoc:nest case class Message(sender: String, recipient: String, body: String) val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") val message5 = message4.copy(sender = message4.recipient, recipient = "claire@bourgogne.fr") @@ -56,4 +81,12 @@ message5.sender // travis@washington.us message5.recipient // claire@bourgogne.fr message5.body // "Me zo o komz gant ma amezeg" ``` +{% endtab %} + +{% endtabs %} + The recipient of `message4` is used as the sender of `message5` but the `body` of `message4` was copied directly. + +## More resources + +* Learn more about case classes in the [Scala Book](/scala3/book/domain-modeling-tools.html#case-classes) diff --git a/_tour/classes.md b/_tour/classes.md index 1f4b80b59e..683ae049cf 100644 --- a/_tour/classes.md +++ b/_tour/classes.md @@ -1,13 +1,10 @@ --- layout: tour title: Classes - -discourse: true - partof: scala-tour num: 4 -next-page: traits +next-page: default-parameter-values previous-page: unified-types topics: classes prerequisite-knowledge: no-return-keyword, type-declaration-syntax, string-interpolation, procedures @@ -21,14 +18,38 @@ values, variables, types, objects, traits, and classes which are collectively ca ## Defining a class A minimal class definition is simply the keyword `class` and an identifier. Class names should be capitalized. -```tut + +{% tabs class-minimal-user class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-minimal-user %} +```scala mdoc class User val user1 = new User ``` -The keyword `new` is used to create an instance of the class. `User` has a default constructor which takes no arguments because no constructor was defined. However, you'll often want a constructor and class body. Here is an example class definition for a point: -```tut +The keyword `new` is used to create an instance of the class. +{% endtab %} + +{% tab 'Scala 3' for=class-minimal-user %} +```scala +class User + +val user1 = User() +``` + +We call the class like a function, as `User()`, to create an instance of the class. +It is also possible to explicitly use the `new` keyword, as `new User()`, although that is usually left out. +{% endtab %} + +{% endtabs %} + +`User` has a default constructor which takes no arguments because no constructor was defined. However, you'll often want a constructor and class body. Here is an example class definition for a point: + +{% tabs class-point-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-example %} +```scala mdoc class Point(var x: Int, var y: Int) { def move(dx: Int, dy: Int): Unit = { @@ -41,73 +62,205 @@ class Point(var x: Int, var y: Int) { } val point1 = new Point(2, 3) -point1.x // 2 -println(point1) // prints (2, 3) +println(point1.x) // prints 2 +println(point1) // prints (2, 3) ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-example %} +```scala +class Point(var x: Int, var y: Int): + + def move(dx: Int, dy: Int): Unit = + x = x + dx + y = y + dy + + override def toString: String = + s"($x, $y)" +end Point + +val point1 = Point(2, 3) +println(point1.x) // prints 2 +println(point1) // prints (2, 3) +``` +{% endtab %} + +{% endtabs %} This `Point` class has four members: the variables `x` and `y` and the methods `move` and -`toString`. Unlike many other languages, the primary constructor is in the class signature `(var x: Int, var y: Int)`. The `move` method takes two integer arguments and returns the Unit value `()`, which carries no information. This corresponds roughly with `void` in Java-like languages. `toString`, on the other hand, does not take any arguments but returns a `String` value. Since `toString` overrides `toString` from [`AnyRef`](unified-types.html), it is tagged with the `override` keyword. +`toString`. Unlike many other languages, the primary constructor is in the class signature `(var x: Int, var y: Int)`. The `move` method takes two integer arguments and returns the Unit value `()`, which carries no information. This corresponds roughly to `void` in Java-like languages. `toString`, on the other hand, does not take any arguments but returns a `String` value. Since `toString` overrides `toString` from [`AnyRef`](unified-types.html), it is tagged with the `override` keyword. ## Constructors Constructors can have optional parameters by providing a default value like so: -```tut +{% tabs class-point-with-default-values class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-with-default-values %} +```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) -val origin = new Point // x and y are both set to 0 -val point1 = new Point(1) -println(point1.x) // prints 1 +val origin = new Point // x and y are both set to 0 +val point1 = new Point(1) // x is set to 1 and y is set to 0 +println(point1) // prints (1, 0) +``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-with-default-values %} +```scala +class Point(var x: Int = 0, var y: Int = 0) +val origin = Point() // x and y are both set to 0 +val point1 = Point(1) // x is set to 1 and y is set to 0 +println(point1) // prints (1, 0) ``` +{% endtab %} + +{% endtabs %} In this version of the `Point` class, `x` and `y` have the default value `0` so no arguments are required. However, because the constructor reads arguments left to right, if you just wanted to pass in a `y` value, you would need to name the parameter. + +{% tabs class-point-named-argument class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-named-argument %} +```scala mdoc:nest +class Point(var x: Int = 0, var y: Int = 0) +val point2 = new Point(y = 2) +println(point2) // prints (0, 2) ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-named-argument %} +```scala class Point(var x: Int = 0, var y: Int = 0) -val point2 = new Point(y=2) -println(point2.y) // prints 2 +val point2 = Point(y = 2) +println(point2) // prints (0, 2) ``` +{% endtab %} + +{% endtabs %} This is also a good practice to enhance clarity. ## Private Members and Getter/Setter Syntax Members are public by default. Use the `private` access modifier to hide them from outside of the class. -```tut + +{% tabs class-point-private-getter-setter class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-private-getter-setter %} +```scala mdoc:reset class Point { private var _x = 0 private var _y = 0 private val bound = 100 - def x = _x - def x_= (newValue: Int): Unit = { - if (newValue < bound) _x = newValue else printWarning + def x: Int = _x + def x_=(newValue: Int): Unit = { + if (newValue < bound) + _x = newValue + else + printWarning() } - def y = _y - def y_= (newValue: Int): Unit = { - if (newValue < bound) _y = newValue else printWarning + def y: Int = _y + def y_=(newValue: Int): Unit = { + if (newValue < bound) + _y = newValue + else + printWarning() } - private def printWarning = println("WARNING: Out of bounds") + private def printWarning(): Unit = + println("WARNING: Out of bounds") } val point1 = new Point point1.x = 99 point1.y = 101 // prints the warning ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-private-getter-setter %} +```scala +class Point: + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x: Int = _x + def x_=(newValue: Int): Unit = + if newValue < bound then + _x = newValue + else + printWarning() + + def y: Int = _y + def y_=(newValue: Int): Unit = + if newValue < bound then + _y = newValue + else + printWarning() + + private def printWarning(): Unit = + println("WARNING: Out of bounds") +end Point + +val point1 = Point() +point1.x = 99 +point1.y = 101 // prints the warning +``` +{% endtab %} + +{% endtabs %} + In this version of the `Point` class, the data is stored in private variables `_x` and `_y`. There are methods `def x` and `def y` for accessing the private data. `def x_=` and `def y_=` are for validating and setting the value of `_x` and `_y`. Notice the special syntax for the setters: the method has `_=` appended to the identifier of the getter and the parameters come after. Primary constructor parameters with `val` and `var` are public. However, because `val`s are immutable, you can't write the following. -``` + +{% tabs class-point-cannot-set-val class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-cannot-set-val %} +```scala mdoc:fail class Point(val x: Int, val y: Int) val point = new Point(1, 2) point.x = 3 // <-- does not compile ``` +{% endtab %} -Parameters without `val` or `var` are private values, visible only within the class. +{% tab 'Scala 3' for=class-point-cannot-set-val %} +```scala +class Point(val x: Int, val y: Int) +val point = Point(1, 2) +point.x = 3 // <-- does not compile ``` +{% endtab %} + +{% endtabs %} + +Parameters without `val` or `var` are private values, visible only within the class. + +{% tabs class-point-non-val-ctor-param class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-non-val-ctor-param %} +```scala mdoc:fail class Point(x: Int, y: Int) val point = new Point(1, 2) point.x // <-- does not compile ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-non-val-ctor-param %} +```scala +class Point(x: Int, y: Int) +val point = Point(1, 2) +point.x // <-- does not compile +``` +{% endtab %} + +{% endtabs %} + +## More resources + +* Learn more about Classes in the [Scala Book](/scala3/book/domain-modeling-tools.html#classes) +* How to use [Auxiliary Class Constructors](/scala3/book/domain-modeling-tools.html#auxiliary-constructors) diff --git a/_tour/compound-types.md b/_tour/compound-types.md index 30e78c8b3e..2c12773600 100644 --- a/_tour/compound-types.md +++ b/_tour/compound-types.md @@ -1,25 +1,27 @@ --- layout: tour -title: Compound Types - -discourse: true - +title: Intersection Types, aka Compound Types partof: scala-tour -num: 24 +num: 26 next-page: self-types -previous-page: abstract-types +previous-page: abstract-type-members redirect_from: "/tutorials/tour/compound-types.html" --- -Sometimes it is necessary to express that the type of an object is a subtype of several other types. In Scala this can be expressed with the help of *compound types*, which are intersections of object types. +Sometimes it is necessary to express that the type of an object is a subtype of several other types. + +In Scala this can be expressed with the help of *intersection types*, (or *compound types* in +Scala 2) which are types that behave like any part of the intersection. Suppose we have two traits `Cloneable` and `Resetable`: -```tut +{% tabs compound-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_1 %} +```scala mdoc trait Cloneable extends java.lang.Cloneable { - override def clone(): Cloneable = { + override def clone(): Cloneable = { // makes clone public super.clone().asInstanceOf[Cloneable] } } @@ -27,28 +29,67 @@ trait Resetable { def reset: Unit } ``` +{% endtab %} +{% tab 'Scala 3' for=compound-types_1 %} +```scala +trait Cloneable extends java.lang.Cloneable: + override def clone(): Cloneable = // makes clone public + super.clone().asInstanceOf[Cloneable] +trait Resetable: + def reset: Unit +``` +{% endtab %} +{% endtabs %} Now suppose we want to write a function `cloneAndReset` which takes an object, clones it and resets the original object: -``` +{% tabs compound-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_2 %} +```scala mdoc:fail def cloneAndReset(obj: ?): Cloneable = { val cloned = obj.clone() obj.reset cloned } ``` +{% endtab %} +{% tab 'Scala 3' for=compound-types_2 %} +```scala +def cloneAndReset(obj: ?): Cloneable = + val cloned = obj.clone() + obj.reset + cloned +``` +{% endtab %} +{% endtabs %} -The question arises what the type of the parameter `obj` is. If it's `Cloneable` then the object can be `clone`d, but not `reset`; if it's `Resetable` we can `reset` it, but there is no `clone` operation. To avoid type casts in such a situation, we can specify the type of `obj` to be both `Cloneable` and `Resetable`. This compound type is written like this in Scala: `Cloneable with Resetable`. +The question arises what the type of the parameter `obj` is. If it's `Cloneable` then the object can be `clone`d, but not `reset`; if it's `Resetable` we can `reset` it, but there is no `clone` operation. To avoid type casts in such a situation, we can specify the type of `obj` to be both `Cloneable` and `Resetable`. +{% tabs compound-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_3 %} +This compound type is written in Scala as `Cloneable with Resetable`. Here's the updated function: - -``` +```scala mdoc:fail def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { //... } ``` +Note that you can have more than two types: `A with B with C with ...`. +This means the same as thing as `(...(A with B) with C) with ... )` +{% endtab %} +{% tab 'Scala 3' for=compound-types_3 %} +This intersection type is written in Scala as `Cloneable & Resetable`. -Compound types can consist of several object types and they may have a single refinement which can be used to narrow the signature of existing object members. -The general form is: `A with B with C ... { refinement }` +Here's the updated function: +```scala +def cloneAndReset(obj: Cloneable & Resetable): Cloneable = { + //... +} +``` + +Note that you can have more than two types: `A & B & C & ...`. +And `&` is associative, so parentheses can be added around any part without changing the meaning. +{% endtab %} +{% endtabs %} -An example for the use of refinements is given on the page about [abstract types](abstract-types.html). + diff --git a/_tour/default-parameter-values.md b/_tour/default-parameter-values.md index bd98bb6e91..96b28f278a 100644 --- a/_tour/default-parameter-values.md +++ b/_tour/default-parameter-values.md @@ -1,14 +1,11 @@ --- layout: tour title: Default Parameter Values - -discourse: true - partof: scala-tour -num: 33 +num: 5 next-page: named-arguments -previous-page: annotations +previous-page: classes prerequisite-knowledge: named-arguments, function syntax redirect_from: "/tutorials/tour/default-parameter-values.html" @@ -16,29 +13,45 @@ redirect_from: "/tutorials/tour/default-parameter-values.html" Scala provides the ability to give parameters default values that can be used to allow a caller to omit those parameters. -```tut +{% tabs default-parameter-values-1 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-1 %} +```scala mdoc def log(message: String, level: String = "INFO") = println(s"$level: $message") log("System starting") // prints INFO: System starting log("User not found", "WARNING") // prints WARNING: User not found ``` +{% endtab %} +{% endtabs %} + The parameter `level` has a default value so it is optional. On the last line, the argument `"WARNING"` overrides the default argument `"INFO"`. Where you might do overloaded methods in Java, you can use methods with optional parameters to achieve the same effect. However, if the caller omits an argument, any following arguments must be named. -```tut +{% tabs default-parameter-values-2 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-2 %} +```scala mdoc class Point(val x: Double = 0, val y: Double = 0) val point1 = new Point(y = 1) ``` +{% endtab %} +{% endtabs %} + Here we have to say `y = 1`. Note that default parameters in Scala are not optional when called from Java code: -```tut +{% tabs default-parameter-values-3 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-3 %} +```scala mdoc:reset // Point.scala class Point(val x: Double = 0, val y: Double = 0) ``` +{% endtab %} +{% endtabs %} +{% tabs default-parameter-values-4 %} +{% tab 'Java' for=default-parameter-values-4 %} ```java // Main.java public class Main { @@ -47,3 +60,30 @@ public class Main { } } ``` +{% endtab %} +{% endtabs %} + +### Default Parameters for Overloaded Methods + +Scala doesn't allow having two methods with default parameters and with the same name (overloaded). +An important reason why is to avoid the ambiguity that can be caused due to the existence of default parameters. To illustrate the problem, let's consider the method declarations provided below: + +{% tabs default-parameter-values-5 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:fail +object A { + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object A: + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +``` +{% endtab %} +{% endtabs %} + +If we call `A.func()`, compiler cannot know whether the programmer intended to call `func(x: Int = 34)` or `func(y: String = "abc")`. diff --git a/_tour/extractor-objects.md b/_tour/extractor-objects.md index a1cd0b2fae..a859d6cdda 100644 --- a/_tour/extractor-objects.md +++ b/_tour/extractor-objects.md @@ -1,12 +1,9 @@ --- layout: tour title: Extractor Objects - -discourse: true - partof: scala-tour -num: 16 +num: 18 next-page: for-comprehensions previous-page: regular-expression-patterns @@ -15,12 +12,15 @@ redirect_from: "/tutorials/tour/extractor-objects.html" An extractor object is an object with an `unapply` method. Whereas the `apply` method is like a constructor which takes arguments and creates an object, the `unapply` takes an object and tries to give back the arguments. This is most often used in pattern matching and partial functions. -```tut +{% tabs extractor-objects_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=extractor-objects_definition %} +```scala mdoc import scala.util.Random object CustomerID { - def apply(name: String) = s"$name--${Random.nextLong}" + def apply(name: String) = s"$name--${Random.nextLong()}" def unapply(customerID: String): Option[String] = { val stringArray: Array[String] = customerID.split("--") @@ -34,28 +34,68 @@ customer1ID match { case _ => println("Could not extract a CustomerID") } ``` +{% endtab %} -The `apply` method creates a `CustomerID` string from a `name`. The `unapply` does the inverse to get the `name` back. When we call `CustomerID("Sukyoung")`, this is shorthand syntax for calling `CustomerID.apply("Sukyoung")`. When we call `case CustomerID(name) => println(name)`, we're calling the unapply method. +{% tab 'Scala 3' for=extractor-objects_definition %} +```scala +import scala.util.Random + +object CustomerID: -The unapply method can also be used to assign a value. + def apply(name: String) = s"$name--${Random.nextLong()}" -```tut + def unapply(customerID: String): Option[String] = + val stringArray: Array[String] = customerID.split("--") + if stringArray.tail.nonEmpty then Some(stringArray.head) else None + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match + case CustomerID(name) => println(name) // prints Sukyoung + case _ => println("Could not extract a CustomerID") +``` +{% endtab %} + +{% endtabs %} + +The `apply` method creates a `CustomerID` string from a `name`. The `unapply` does the inverse to get the `name` back. When we call `CustomerID("Sukyoung")`, this is shorthand syntax for calling `CustomerID.apply("Sukyoung")`. When we call `case CustomerID(name) => println(name)`, we're calling the unapply method with `CustomerID.unapply(customer1ID)`. + +Since a value definition can use a pattern to introduce a new variable, an extractor can be used to initialize the variable, where the unapply method supplies the value. + +{% tabs extractor-objects_use-case-1 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-1 %} +```scala mdoc val customer2ID = CustomerID("Nico") val CustomerID(name) = customer2ID println(name) // prints Nico ``` +{% endtab %} + +{% endtabs %} This is equivalent to `val name = CustomerID.unapply(customer2ID).get`. -```tut +{% tabs extractor-objects_use-case-2 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-2 %} +```scala mdoc val CustomerID(name2) = "--asdfasdfasdf" ``` +{% endtab %} + +{% endtabs %} If there is no match, a `scala.MatchError` is thrown: -```tut:fail +{% tabs extractor-objects_use-case-3 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-3 %} +```scala mdoc:crash val CustomerID(name3) = "-asdfasdfasdf" ``` +{% endtab %} + +{% endtabs %} The return type of an `unapply` should be chosen as follows: @@ -63,4 +103,4 @@ The return type of an `unapply` should be chosen as follows: * If it returns a single sub-value of type T, return an `Option[T]`. * If you want to return several sub-values `T1,...,Tn`, group them in an optional tuple `Option[(T1,...,Tn)]`. -Sometimes, the number of sub-values isn't fixed and we would like to return a sequence. For this reason, you can also define patterns through `unapplySeq` which returns `Option[Seq[T]]` This mechanism is used for instance in pattern `case List(x1, ..., xn)`. +Sometimes, the number of values to extract isn't fixed and we would like to return an arbitrary number of values, depending on the input. For this use case, you can define extractors with an `unapplySeq` method which returns an `Option[Seq[T]]`. Common examples of these patterns include deconstructing a `List` using `case List(x, y, z) =>` and decomposing a `String` using a regular expression `Regex`, such as `case r(name, remainingFields @ _*) =>`. diff --git a/_tour/for-comprehensions.md b/_tour/for-comprehensions.md index 85f5730cd0..a97758d8b3 100644 --- a/_tour/for-comprehensions.md +++ b/_tour/for-comprehensions.md @@ -1,66 +1,136 @@ --- layout: tour title: For Comprehensions - -discourse: true - partof: scala-tour -num: 17 +num: 19 next-page: generic-classes previous-page: extractor-objects -redirect_from: "/tutorials/tour/for-comprehensions.html" +redirect_from: + - "/tutorials/tour/for-comprehensions.html" + - "/tutorials/tour/sequence-comprehensions.html" --- -Scala offers a lightweight notation for expressing *sequence comprehensions*. Comprehensions have the form `for (enumerators) yield e`, where `enumerators` refers to a semicolon-separated list of enumerators. An *enumerator* is either a generator which introduces new variables, or it is a filter. A comprehension evaluates the body `e` for each binding generated by the enumerators and returns a sequence of these values. +Scala offers a lightweight notation for expressing _sequence comprehensions_. Comprehensions have the form `for (enumerators) yield e`, where `enumerators` refers to a list of enumerators. An _enumerator_ is either a generator, or it is a guard (see: [Control Structures](/scala3/book/control-structures.html#for-loops)). A comprehension evaluates the body `e` for each binding generated by the enumerators and returns a sequence of these values. Here's an example: -```tut +{% tabs for-comprehensions-01 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-01 %} + +```scala mdoc case class User(name: String, age: Int) -val userBase = List(User("Travis", 28), +val userBase = List( + User("Travis", 28), User("Kelly", 33), User("Jennifer", 44), User("Dennis", 23)) -val twentySomethings = for (user <- userBase if (user.age >=20 && user.age < 30)) +val twentySomethings = + for (user <- userBase if user.age >=20 && user.age < 30) yield user.name // i.e. add this to a list -twentySomethings.foreach(name => println(name)) // prints Travis Dennis +twentySomethings.foreach(println) // prints Travis Dennis ``` -The `for` loop used with a `yield` statement actually creates a `List`. Because we said `yield user.name`, it's a `List[String]`. `user <- userBase` is our generator and `if (user.age >=20 && user.age < 30)` is a guard that filters out users who are not in their 20s. + +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-01 %} + +```scala +case class User(name: String, age: Int) + +val userBase = List( + User("Travis", 28), + User("Kelly", 33), + User("Jennifer", 44), + User("Dennis", 23)) + +val twentySomethings = + for user <- userBase if user.age >=20 && user.age < 30 + yield user.name // i.e. add this to a list + +twentySomethings.foreach(println) // prints Travis Dennis +``` + +{% endtab %} +{% endtabs %} + +A `for` loop with a `yield` statement returns a result, the container type of which is determined by the first generator. `user <- userBase` is a `List`, and because we said `yield user.name` where `user.name` is a `String`, the overall result is a `List[String]`. And `if user.age >=20 && user.age < 30` is a guard that filters out users who are not in their twenties. Here is a more complicated example using two generators. It computes all pairs of numbers between `0` and `n-1` whose sum is equal to a given value `v`: -```tut +{% tabs for-comprehensions-02 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-02 %} + +```scala mdoc def foo(n: Int, v: Int) = for (i <- 0 until n; - j <- i until n if i + j == v) + j <- 0 until n if i + j == v) yield (i, j) -foo(10, 10) foreach { +foo(10, 10).foreach { case (i, j) => - println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) + println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) } +``` + +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-02 %} +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + yield (i, j) + +foo(10, 10).foreach { + (i, j) => println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) +} ``` + +{% endtab %} +{% endtabs %} + Here `n == 10` and `v == 10`. On the first iteration, `i == 0` and `j == 0` so `i + j != v` and therefore nothing is yielded. `j` gets incremented 9 more times before `i` gets incremented to `1`. Without the `if` guard, this would simply print the following: -``` -(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 1) ... +```scala +(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... ``` Note that comprehensions are not restricted to lists. Every datatype that supports the operations `withFilter`, `map`, and `flatMap` (with the proper types) can be used in sequence comprehensions. You can omit `yield` in a comprehension. In that case, comprehension will return `Unit`. This can be useful in case you need to perform side-effects. Here's a program equivalent to the previous one, but without using `yield`: -```tut +{% tabs for-comprehensions-03 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-03 %} + +```scala mdoc:nest def foo(n: Int, v: Int) = for (i <- 0 until n; - j <- i until n if i + j == v) + j <- 0 until n if i + j == v) println(s"($i, $j)") foo(10, 10) ``` + +{% endtab %} + +{% tab 'Scala 3' for=for-comprehensions-03 %} + +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + do println(s"($i, $j)") + +foo(10, 10) +``` + +{% endtab %} +{% endtabs %} + +## More resources + +- Other examples of "For comprehension" in the [Scala Book](/scala3/book/control-structures.html#for-expressions) diff --git a/_tour/generic-classes.md b/_tour/generic-classes.md index 2433cd6b45..5dbb8990d8 100644 --- a/_tour/generic-classes.md +++ b/_tour/generic-classes.md @@ -1,26 +1,28 @@ --- layout: tour title: Generic Classes - -discourse: true - partof: scala-tour -num: 18 +num: 20 next-page: variances previous-page: for-comprehensions assumed-knowledge: classes unified-types redirect_from: "/tutorials/tour/generic-classes.html" --- + Generic classes are classes which take a type as a parameter. They are particularly useful for collection classes. ## Defining a generic class Generic classes take a type as a parameter within square brackets `[]`. One convention is to use the letter `A` as type parameter identifier, though any parameter name may be used. -```tut + +{% tabs generic-classes-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-1 %} +```scala mdoc class Stack[A] { private var elements: List[A] = Nil - def push(x: A) { elements = x :: elements } + def push(x: A): Unit = + elements = x :: elements def peek: A = elements.head def pop(): A = { val currentTop = peek @@ -29,20 +31,56 @@ class Stack[A] { } } ``` +{% endtab %} +{% tab 'Scala 3' for=generic-classes-1 %} +```scala +class Stack[A]: + private var elements: List[A] = Nil + def push(x: A): Unit = + elements = x :: elements + def peek: A = elements.head + def pop(): A = + val currentTop = peek + elements = elements.tail + currentTop +``` +{% endtab %} +{% endtabs %} + This implementation of a `Stack` class takes any type `A` as a parameter. This means the underlying list, `var elements: List[A] = Nil`, can only store elements of type `A`. The procedure `def push` only accepts objects of type `A` (note: `elements = x :: elements` reassigns `elements` to a new list created by prepending `x` to the current `elements`). +`Nil` here is an empty `List` and is not to be confused with `null`. + ## Usage To use a generic class, put the type in the square brackets in place of `A`. -``` + +{% tabs generic-classes-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-2 %} +```scala mdoc val stack = new Stack[Int] stack.push(1) stack.push(2) -println(stack.pop) // prints 2 -println(stack.pop) // prints 1 +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 ``` -The instance `stack` can only take Ints. However, if the type argument had subtypes, those could be passed in: +{% endtab %} +{% tab 'Scala 3' for=generic-classes-2 %} +```scala +val stack = Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 ``` +{% endtab %} +{% endtabs %} + +The instance `stack` can only take Ints. However, if the type argument had subtypes, those could be passed in: + +{% tabs generic-classes-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-3 %} +```scala mdoc:nest class Fruit class Apple extends Fruit class Banana extends Fruit @@ -54,6 +92,23 @@ val banana = new Banana stack.push(apple) stack.push(banana) ``` +{% endtab %} +{% tab 'Scala 3' for=generic-classes-3 %} +```scala +class Fruit +class Apple extends Fruit +class Banana extends Fruit + +val stack = Stack[Fruit] +val apple = Apple() +val banana = Banana() + +stack.push(apple) +stack.push(banana) +``` +{% endtab %} +{% endtabs %} + Class `Apple` and `Banana` both extend `Fruit` so we can push instances `apple` and `banana` onto the stack of `Fruit`. _Note: subtyping of generic types is *invariant*. This means that if we have a stack of characters of type `Stack[Char]` then it cannot be used as an integer stack of type `Stack[Int]`. This would be unsound because it would enable us to enter true integers into the character stack. To conclude, `Stack[A]` is only a subtype of `Stack[B]` if and only if `B = A`. Since this can be quite restrictive, Scala offers a [type parameter annotation mechanism](variances.html) to control the subtyping behavior of generic types._ diff --git a/_tour/higher-order-functions.md b/_tour/higher-order-functions.md index efc8d37db2..7dc08ea005 100644 --- a/_tour/higher-order-functions.md +++ b/_tour/higher-order-functions.md @@ -1,12 +1,9 @@ --- layout: tour title: Higher-order Functions - -discourse: true - partof: scala-tour -num: 8 +num: 10 next-page: nested-functions previous-page: mixin-class-composition @@ -19,29 +16,54 @@ The terminology can get a bit confusing at this point, and we use the phrase "higher order function" for both methods and functions that take functions as parameters or that return a function. +In a pure Object Oriented world, a good practice is to avoid exposing methods parameterised with functions that might leak an object's internal state. Leaking internal state might break the invariants of the object itself, thus violating encapsulation. + One of the most common examples is the higher-order function `map` which is available for collections in Scala. -```tut -val salaries = Seq(20000, 70000, 40000) + +{% tabs map_example_1 %} + +{% tab 'Scala 2 and 3' for=map_example_1 %} +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) val doubleSalary = (x: Int) => x * 2 val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) ``` +{% endtab %} + +{% endtabs %} + `doubleSalary` is a function which takes a single Int, `x`, and returns `x * 2`. In general, the tuple on the left of the arrow `=>` is a parameter list and the value of the expression on the right is what gets returned. On line 3, the function `doubleSalary` gets applied to each element in the list of salaries. To shrink the code, we could make the function anonymous and pass it directly as an argument to map: -``` -val salaries = Seq(20000, 70000, 40000) + +{% tabs map_example_2 %} + +{% tab 'Scala 2 and 3' for=map_example_2 %} +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) ``` +{% endtab %} + +{% endtabs %} + Notice how `x` is not declared as an Int in the above example. That's because the -compiler can infer the type based on the type of function map expects. An even more idiomatic way to write the same piece of code would be: +compiler can infer the type based on the type of function `map` expects (see [Currying](/tour/multiple-parameter-lists.html)). An even more idiomatic way to write the same piece of code would be: + +{% tabs map_example_3 %} -```tut -val salaries = Seq(20000, 70000, 40000) +{% tab 'Scala 2 and 3' for=map_example_3 %} +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) val newSalaries = salaries.map(_ * 2) ``` +{% endtab %} + +{% endtabs %} + Since the Scala compiler already knows the type of the parameters (a single Int), you just need to provide the right side of the function. The only caveat is that you need to use `_` in place of a parameter name (it was `x` in @@ -50,7 +72,11 @@ the previous example). ## Coercing methods into functions It is also possible to pass methods as arguments to higher-order functions because the Scala compiler will coerce the method into a function. -``` + +{% tabs Coercing_methods_into_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Coercing_methods_into_functions %} +```scala mdoc case class WeeklyWeatherForecast(temperatures: Seq[Double]) { private def convertCtoF(temp: Double) = temp * 1.8 + 32 @@ -58,14 +84,31 @@ case class WeeklyWeatherForecast(temperatures: Seq[Double]) { def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF } ``` -Here the method `convertCtoF` is passed to `forecastInFahrenheit`. This is possible because the compiler coerces `convertCtoF` to the function `x => convertCtoF(x)` (note: `x` will +{% endtab %} + +{% tab 'Scala 3' for=Coercing_methods_into_functions %} +```scala +case class WeeklyWeatherForecast(temperatures: Seq[Double]): + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF +``` +{% endtab %} + +{% endtabs %} + +Here the method `convertCtoF` is passed to the higher order function `map`. This is possible because the compiler coerces `convertCtoF` to the function `x => convertCtoF(x)` (note: `x` will be a generated name which is guaranteed to be unique within its scope). ## Functions that accept functions One reason to use higher-order functions is to reduce redundant code. Let's say you wanted some methods that could raise someone's salaries by various factors. Without creating a higher-order function, it might look something like this: -```tut +{% tabs Functions_that_accept_functions_1 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_1 %} +```scala mdoc object SalaryRaiser { def smallPromotion(salaries: List[Double]): List[Double] = @@ -78,11 +121,32 @@ object SalaryRaiser { salaries.map(salary => salary * salary) } ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_1 %} +```scala +object SalaryRaiser: + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +``` +{% endtab %} + +{% endtabs %} Notice how each of the three methods vary only by the multiplication factor. To simplify, you can extract the repeated code into a higher-order function like so: -```tut +{% tabs Functions_that_accept_functions_2 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_2 %} +```scala mdoc:nest object SalaryRaiser { private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = @@ -91,23 +155,49 @@ object SalaryRaiser { def smallPromotion(salaries: List[Double]): List[Double] = promotion(salaries, salary => salary * 1.1) - def bigPromotion(salaries: List[Double]): List[Double] = + def greatPromotion(salaries: List[Double]): List[Double] = promotion(salaries, salary => salary * math.log(salary)) def hugePromotion(salaries: List[Double]): List[Double] = promotion(salaries, salary => salary * salary) } ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_2 %} +```scala +object SalaryRaiser: + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +``` +{% endtab %} + +{% endtabs %} The new method, `promotion`, takes the salaries plus a function of type `Double => Double` (i.e. a function that takes a Double and returns a Double) and returns the product. +Methods and functions usually express behaviours or data transformations. Therefore, having functions that compose based on other functions can allow us to build more generic mechanisms. Such generic operations avoid completely locking down their behaviour in order to give clients a way to control or further customize parts of those operations. + ## Functions that return functions There are certain cases where you want to generate a function. Here's an example of a method that returns a function. -```tut +{% tabs Functions_that_return_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_return_functions %} +```scala mdoc def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { val schema = if (ssl) "https://" else "http://" (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" @@ -119,6 +209,23 @@ val endpoint = "users" val query = "id=1" val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_return_functions %} +```scala +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = + val schema = if ssl then "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` +{% endtab %} + +{% endtabs %} Notice the return type of urlBuilder `(String, String) => String`. This means that the returned anonymous function takes two Strings and returns a String. In this case, diff --git a/_tour/implicit-conversions.md b/_tour/implicit-conversions.md index 840c7cec07..7c0b5840e4 100644 --- a/_tour/implicit-conversions.md +++ b/_tour/implicit-conversions.md @@ -1,63 +1,43 @@ --- layout: tour title: Implicit Conversions - -discourse: true - partof: scala-tour -num: 27 +num: 29 next-page: polymorphic-methods previous-page: implicit-parameters redirect_from: "/tutorials/tour/implicit-conversions.html" --- -An implicit conversion from type `S` to type `T` is defined by an implicit value which has function type `S => T`, or by an implicit method convertible to a value of that type. - -Implicit conversions are applied in two situations: - -* If an expression `e` is of type `S`, and `S` does not conform to the expression's expected type `T`. -* In a selection `e.m` with `e` of type `S`, if the selector `m` does not denote a member of `S`. +Implicit conversions are a powerful Scala feature that enable two common use cases: +- allow users to supply an argument of one type, as if it were another type, to avoid boilerplate. +- in Scala 2, to provide additional members to closed classes (replaced by [extension methods][exts] in Scala 3). -In the first case, a conversion `c` is searched for which is applicable to `e` and whose result type conforms to `T`. -In the second case, a conversion `c` is searched for which is applicable to `e` and whose result contains a member named `m`. +### Detailed Explanation +{% tabs implicit-conversion-defn class=tabs-scala-version %} +{% tab 'Scala 2' %} +In Scala 2, an implicit conversion from type `S` to type `T` is defined by either an [implicit class]({% link _overviews/core/implicit-classes.md %}) `T` that has a single parameter of type `S`, an [implicit value]({% link _tour/implicit-parameters.md %}) which has function type `S => T`, or by an implicit method convertible to a value of that type. +{% endtab %} +{% tab 'Scala 3' %} +In Scala 3, an implicit conversion from type `S` to type `T` is defined by a [given instance]({% link _tour/implicit-parameters.md %}) which has type `scala.Conversion[S, T]`. For compatibility with Scala 2, they can also be defined by an implicit method (read more in the Scala 2 tab). +{% endtab %} +{% endtabs %} -If an implicit method `List[A] => Ordered[List[A]]` is in scope, as well as an implicit method `Int => Ordered[Int]`, the following operation on the two lists of type `List[Int]` is legal: - -``` -List(1, 2, 3) <= List(4, 5) -``` - -An implicit method `Int => Ordered[Int]` is provided automatically through `scala.Predef.intWrapper`. An example of an implicit method `List[A] => Ordered[List[A]]` is provided below. - -```tut -import scala.language.implicitConversions - -implicit def list2ordered[A](x: List[A]) - (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] = - new Ordered[List[A]] { - //replace with a more useful implementation - def compare(that: List[A]): Int = 1 - } -``` +Implicit conversions are applied in two situations: -The implicitly imported object `scala.Predef` declares several predefined types (e.g. `Pair`) and methods (e.g. `assert`) but also several implicit conversions. +1. If an expression `e` is of type `S`, and `S` does not conform to the expression's expected type `T`. +2. In a selection `e.m` with `e` of type `S`, if the selector `m` does not denote a member of `S`. -For example, when calling a Java method that expects a `java.lang.Integer`, you are free to pass it a `scala.Int` instead. That's because Predef includes the following implicit conversions: +In the first case, a conversion `c` is searched for, which is applicable to `e` and whose result type conforms to `T`. -```tut -import scala.language.implicitConversions +An example is to pass a `scala.Int`, e.g. `x`, to a method that expects `scala.Long`. In this case, the implicit conversion `Int.int2long(x)` is inserted. -implicit def int2Integer(x: Int) = - java.lang.Integer.valueOf(x) -``` -Because implicit conversions can have pitfalls if used indiscriminately the compiler warns when compiling the implicit conversion definition. +In the second case, a conversion `c` is searched for, which is applicable to `e` and whose result contains a member named `m`. -To turn off the warnings take either of these actions: +An example is to compare two strings `"foo" < "bar"`. In this case, `String` has no member `<`, so the implicit conversion `Predef.augmentString("foo") < "bar"` is inserted. (`scala.Predef` is automatically imported into all Scala programs.) -* Import `scala.language.implicitConversions` into the scope of the implicit conversion definition -* Invoke the compiler with `-language:implicitConversions` +Further reading: [Implicit Conversions (in the Scala book)]({% link _overviews/scala3-book/ca-implicit-conversions.md %}). -No warning is emitted when the conversion is applied by the compiler. +[exts]: {% link _overviews/scala3-book/ca-extension-methods.md %} diff --git a/_tour/implicit-parameters.md b/_tour/implicit-parameters.md index f06da371a9..4d5977f242 100644 --- a/_tour/implicit-parameters.md +++ b/_tour/implicit-parameters.md @@ -1,73 +1,102 @@ --- layout: tour -title: Implicit Parameters - -discourse: true - +title: Contextual Parameters, aka Implicit Parameters partof: scala-tour -num: 26 +num: 28 next-page: implicit-conversions previous-page: self-types redirect_from: "/tutorials/tour/implicit-parameters.html" --- -A method can have an _implicit_ parameter list, marked by the _implicit_ keyword at the start of the parameter list. If the parameters in that parameter list are not passed as usual, Scala will look if it can get an implicit value of the correct type, and if it can, pass it automatically. - -The places Scala will look for these parameters fall into two categories: - -* Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called. -* Then it looks for members marked implicit in all the companion objects associated with the implicit candidate type. +A method can have *contextual parameters*, also called *implicit parameters*, or more concisely *implicits*. +Parameter lists starting with the keyword `using` (or `implicit` in Scala 2) mark contextual parameters. +Unless the call site explicitly provides arguments for those parameters, Scala will look for implicitly available `given` (or `implicit` in Scala 2) values of the correct type. +If it can find appropriate values, it automatically passes them. -A more detailed guide to where scala looks for implicits can be found in [the FAQ](//docs.scala-lang.org/tutorials/FAQ/finding-implicits.html) +This is best shown using a small example first. +We define an interface `Comparator[A]` that can compare elements of type `A`, and provide two implementations, for `Int`s and `String`s. +We then define a method `max[A](x: A, y: A)` that returns the greater of the two arguments. +Since `x` and `y` are generically typed, in general we do not know how to compare them, but we can ask for an appropriate comparator. +As there is typically a canonical comparator for any given type `A`, we can declare them as *given*s, or *implicitly* available. -In the following example we define a method `sum` which computes the sum of a list of elements using the monoid's `add` and `unit` operations. Please note that implicit values can not be top-level. +{% tabs implicits-comparator class=tabs-scala-version %} -```tut -abstract class Monoid[A] { - def add(x: A, y: A): A - def unit: A +{% tab 'Scala 2' for=implicits-comparator %} +```scala mdoc +trait Comparator[A] { + def compare(x: A, y: A): Int } -object ImplicitTest { - implicit val stringMonoid: Monoid[String] = new Monoid[String] { - def add(x: String, y: String): String = x concat y - def unit: String = "" +object Comparator { + implicit object IntComparator extends Comparator[Int] { + def compare(x: Int, y: Int): Int = Integer.compare(x, y) } - - implicit val intMonoid: Monoid[Int] = new Monoid[Int] { - def add(x: Int, y: Int): Int = x + y - def unit: Int = 0 - } - - def sum[A](xs: List[A])(implicit m: Monoid[A]): A = - if (xs.isEmpty) m.unit - else m.add(xs.head, sum(xs.tail)) - - def main(args: Array[String]): Unit = { - println(sum(List(1, 2, 3))) // uses IntMonoid implicitly - println(sum(List("a", "b", "c"))) // uses StringMonoid implicitly + + implicit object StringComparator extends Comparator[String] { + def compare(x: String, y: String): Int = x.compareTo(y) } } -``` -`Monoid` defines an operation called `add` here, that combines a pair of `A`s and returns another `A`, together with an operation called `unit` that is able to create some (specific) `A`. +def max[A](x: A, y: A)(implicit comparator: Comparator[A]): A = + if (comparator.compare(x, y) >= 0) x + else y + +println(max(10, 6)) // 10 +println(max("hello", "world")) // world +``` -To show how implicit parameters work, we first define monoids `StringMonoid` and `IntMonoid` for strings and integers, respectively. The `implicit` keyword indicates that the corresponding object can be used implicitly. +```scala mdoc:fail +// does not compile: +println(max(false, true)) +// ^ +// error: could not find implicit value for parameter comparator: Comparator[Boolean] +``` -The method `sum` takes a `List[A]` and returns an `A`, which takes the initial `A` from `unit`, and combines each next `A` in the list to that with the `add` method. Making the parameter `m` implicit here means we only have to provide the `xs` parameter when we call the method if Scala can find a an implict `Monoid[A]` to use for the implicit `m` parameter. +The `comparator` parameter is automatically filled in with `Comparator.IntComparator` for `max(10, 6)`, and with `Comparator.StringComparator` for `max("hello", "world")`. +Since no implicit `Comparator[Boolean]` can be found, the call `max(false, true)` fails to compile. +{% endtab %} -In our `main` method we call `sum` twice, and only provide the `xs` parameter. Scala will now look for an implicit in the scope mentioned above. The first call to `sum` passes a `List[Int]` for `xs`, which means that `A` is `Int`. The implicit parameter list with `m` is left out, so Scala will look for an implicit of type `Monoid[Int]`. The first lookup rule reads +{% tab 'Scala 3' for=implicits-comparator %} +```scala +trait Comparator[A]: + def compare(x: A, y: A): Int -> Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called. +object Comparator: + given Comparator[Int] with + def compare(x: Int, y: Int): Int = Integer.compare(x, y) -`intMonoid` is an implicit definition that can be accessed directly in `main`. It is also of the correct type, so it's passed to the sum method automatically. + given Comparator[String] with + def compare(x: String, y: String): Int = x.compareTo(y) +end Comparator -The second call to `sum` passes a `List[String]`, which means that `A` is `String`. Implicit lookup will go the same way as with `Int`, but will this time find `stringMonoid`, and passes that automatically as `m`. +def max[A](x: A, y: A)(using comparator: Comparator[A]): A = + if comparator.compare(x, y) >= 0 then x + else y -The program will output +println(max(10, 6)) // 10 +println(max("hello", "world")) // world ``` -6 -abc + +```scala +// does not compile: +println(max(false, true)) +-- Error: ---------------------------------------------------------------------- +1 |println(max(false, true)) + | ^ + |no given instance of type Comparator[Boolean] was found for parameter comparator of method max ``` + +The `comparator` parameter is automatically filled in with the `given Comparator[Int]` for `max(10, 6)`, and with the `given Comparator[String]` for `max("hello", "world")`. +Since no `given Comparator[Boolean]` can be found, the call `max(false, true)` fails to compile. +{% endtab %} + +{% endtabs %} + +Scala will look for available given values in two places: + +* Scala will first look for given definitions and using parameters that can be accessed directly (without a prefix) at the call site of `max`. +* Then it looks for members marked `given`/`implicit` in the companion objects associated with the implicit candidate type (for example: `object Comparator` for the candidate type `Comparator[Int]`). + +A more detailed guide to where Scala looks for implicits can be found in [the FAQ](/tutorials/FAQ/finding-implicits.html). diff --git a/_tour/inner-classes.md b/_tour/inner-classes.md index c88181fb84..e2d94542b4 100644 --- a/_tour/inner-classes.md +++ b/_tour/inner-classes.md @@ -1,13 +1,10 @@ --- layout: tour title: Inner Classes - -discourse: true - partof: scala-tour -num: 22 -next-page: abstract-types +num: 24 +next-page: abstract-type-members previous-page: lower-type-bounds redirect_from: "/tutorials/tour/inner-classes.html" @@ -17,12 +14,14 @@ In Scala it is possible to let classes have other classes as members. As opposed To illustrate the difference, we quickly sketch the implementation of a graph datatype: -```tut +{% tabs inner-classes_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_1 %} +```scala mdoc class Graph { class Node { var connectedNodes: List[Node] = Nil - def connectTo(node: Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -35,9 +34,30 @@ class Graph { } } ``` +{% endtab %} +{% tab 'Scala 3' for=inner-classes_1 %} +```scala +class Graph: + class Node: + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` +{% endtab %} +{% endtabs %} + This program represents a graph as a list of nodes (`List[Node]`). Each node has a list of other nodes it's connected to (`connectedNodes`). The `class Node` is a _path-dependent type_ because it is nested in the `class Graph`. Therefore, all nodes in the `connectedNodes` must be created using the `newNode` from the same instance of `Graph`. -```tut +{% tabs inner-classes_2 %} +{% tab 'Scala 2 and 3' for=inner-classes_2 %} +```scala mdoc val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode val node2: graph1.Node = graph1.newNode @@ -45,12 +65,17 @@ val node3: graph1.Node = graph1.newNode node1.connectTo(node2) node3.connectTo(node1) ``` +{% endtab %} +{% endtabs %} + We have explicitly declared the type of `node1`, `node2`, and `node3` as `graph1.Node` for clarity but the compiler could have inferred it. This is because when we call `graph1.newNode` which calls `new Node`, the method is using the instance of `Node` specific to the instance `graph1`. If we now have two graphs, the type system of Scala does not allow us to mix nodes defined within one graph with the nodes of another graph, since the nodes of the other graph have a different type. Here is an illegal program: -``` +{% tabs inner-classes_3 %} +{% tab 'Scala 2 and 3' for=inner-classes_3 %} +```scala mdoc:fail val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode val node2: graph1.Node = graph1.newNode @@ -59,14 +84,19 @@ val graph2: Graph = new Graph val node3: graph2.Node = graph2.newNode node1.connectTo(node3) // illegal! ``` +{% endtab %} +{% endtabs %} + The type `graph1.Node` is distinct from the type `graph2.Node`. In Java, the last line in the previous example program would have been correct. For nodes of both graphs, Java would assign the same type `Graph.Node`; i.e. `Node` is prefixed with class `Graph`. In Scala such a type can be expressed as well, it is written `Graph#Node`. If we want to be able to connect nodes of different graphs, we have to change the definition of our initial graph implementation in the following way: -```tut +{% tabs inner-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_4 %} +```scala mdoc:nest class Graph { class Node { var connectedNodes: List[Graph#Node] = Nil - def connectTo(node: Graph#Node) { - if (connectedNodes.find(node.equals).isEmpty) { + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { connectedNodes = node :: connectedNodes } } @@ -79,3 +109,21 @@ class Graph { } } ``` +{% endtab %} +{% tab 'Scala 3' for=inner-classes_4 %} +```scala +class Graph: + class Node: + var connectedNodes: List[Graph#Node] = Nil + def connectTo(node: Graph#Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` +{% endtab %} +{% endtabs %} diff --git a/_tour/lower-type-bounds.md b/_tour/lower-type-bounds.md index 47acb7664c..bac1883358 100644 --- a/_tour/lower-type-bounds.md +++ b/_tour/lower-type-bounds.md @@ -1,12 +1,9 @@ --- layout: tour title: Lower Type Bounds - -discourse: true - partof: scala-tour -num: 21 +num: 23 next-page: inner-classes previous-page: upper-type-bounds prerequisite-knowledge: upper-type-bounds, generics, variance @@ -18,53 +15,93 @@ While [upper type bounds](upper-type-bounds.html) limit a type to a subtype of a Here is an example where this is useful: -```tut:fail -trait Node[+B] { - def prepend(elem: B): Node[B] +{% tabs upper-type-bounds_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_1 %} +```scala mdoc:fail +trait List[+A] { + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) } -case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { - def prepend(elem: B): ListNode[B] = ListNode(elem, this) - def head: B = h - def tail: Node[B] = t -} +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] -case class Nil[+B]() extends Node[B] { - def prepend(elem: B): ListNode[B] = ListNode(elem, this) -} +object Nil extends List[Nothing] +``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_1 %} +```scala +trait List[+A]: + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] ``` +{% endtab %} +{% endtabs %} -This program implements a singly-linked list. `Nil` represents an empty element (i.e. an empty list). `class ListNode` is a node which contains an element of type `B` (`head`) and a reference to the rest of the list (`tail`). The `class Node` and its subtypes are covariant because we have `+B`. +This program implements a singly-linked list. `Nil` represents an empty list with no elements. `class NonEmptyList` is a node which contains an element of type `A` (`head`) and a reference to the rest of the list (`tail`). The `trait List` and its subtypes are covariant because we have `+A`. -However, this program does _not_ compile because the parameter `elem` in `prepend` is of type `B`, which we declared *co*variant. This doesn't work because functions are *contra*variant in their parameter types and *co*variant in their result types. +However, this program does _not_ compile because the parameter `elem` in `prepend` is of type `A`, which we declared *co*variant. This doesn't work because functions are *contra*variant in their parameter types and *co*variant in their result types. -To fix this, we need to flip the variance of the type of the parameter `elem` in `prepend`. We do this by introducing a new type parameter `U` that has `B` as a lower type bound. +To fix this, we need to flip the variance of the type of the parameter `elem` in `prepend`. We do this by introducing a new type parameter `B` that has `A` as a lower type bound. -```tut -trait Node[+B] { - def prepend[U >: B](elem: U): Node[U] +{% tabs upper-type-bounds_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_2 %} +```scala mdoc +trait List[+A] { + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) } -case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { - def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) - def head: B = h - def tail: Node[B] = t -} +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] -case class Nil[+B]() extends Node[B] { - def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) -} +object Nil extends List[Nothing] +``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_2 %} +```scala +trait List[+A]: + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] ``` +{% endtab %} +{% endtabs %} Now we can do the following: -```tut + +{% tabs upper-type-bounds_3 %} +{% tab 'Scala 2 and 3' for=upper-type-bounds_3 %} +```scala mdoc trait Bird case class AfricanSwallow() extends Bird case class EuropeanSwallow() extends Bird +val africanSwallows: List[AfricanSwallow] = Nil.prepend(AfricanSwallow()) +val swallowsFromAntarctica: List[Bird] = Nil +val someBird: Bird = EuropeanSwallow() + +// assign swallows to birds +val birds: List[Bird] = africanSwallows + +// add some bird to swallows, `B` is `Bird` +val someBirds = africanSwallows.prepend(someBird) -val africanSwallowList= ListNode[AfricanSwallow](AfricanSwallow(), Nil()) -val birdList: Node[Bird] = africanSwallowList -birdList.prepend(new EuropeanSwallow) +// add a swallow to birds +val moreBirds = birds.prepend(EuropeanSwallow()) + +// add disparate swallows together, `B` is `Bird` because that is the supertype common to both swallows +val allBirds = africanSwallows.prepend(EuropeanSwallow()) + +// but this is a mistake! adding a list of birds widens the type arg too much. -Xlint will warn! +val error = moreBirds.prepend(swallowsFromAntarctica) // List[Object] ``` -The `Node[Bird]` can be assigned the `africanSwallowList` but then accept `EuropeanSwallow`s. +{% endtab %} +{% endtabs %} + +The covariant type parameter allows `birds` to get the value of `africanSwallows`. + +The type bound on the type parameter for `prepend` allows adding different varieties of swallows and getting a wider type: instead of `List[AfricanSwallow]`, we get a `List[Bird]`. + +Use `-Xlint` to warn if the inferred type arg is widened too much. diff --git a/_tour/mixin-class-composition.md b/_tour/mixin-class-composition.md index 67a32ee27a..27eeafbf61 100644 --- a/_tour/mixin-class-composition.md +++ b/_tour/mixin-class-composition.md @@ -1,21 +1,21 @@ --- layout: tour title: Class Composition with Mixins - -discourse: true - partof: scala-tour -num: 6 +num: 9 next-page: higher-order-functions -previous-page: traits +previous-page: tuples prerequisite-knowledge: inheritance, traits, abstract-classes, unified-types redirect_from: "/tutorials/tour/mixin-class-composition.html" --- Mixins are traits which are used to compose a class. -```tut +{% tabs mixin-first-exemple class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-first-exemple %} +```scala mdoc abstract class A { val message: String } @@ -33,20 +33,61 @@ println(d.loudMessage) // I'M AN INSTANCE OF CLASS B ``` Class `D` has a superclass `B` and a mixin `C`. Classes can only have one superclass but many mixins (using the keywords `extends` and `with` respectively). The mixins and the superclass may have the same supertype. +{% endtab %} + +{% tab 'Scala 3' for=mixin-first-exemple %} +```scala +abstract class A: + val message: String +class B extends A: + val message = "I'm an instance of class B" +trait C extends A: + def loudMessage = message.toUpperCase() +class D extends B, C + +val d = D() +println(d.message) // I'm an instance of class B +println(d.loudMessage) // I'M AN INSTANCE OF CLASS B +``` +Class `D` has a superclass `B` and a mixin `C`. Classes can only have one superclass but many mixins (using the keyword `extends` and the separator `,` respectively). The mixins and the superclass may have the same supertype. + +{% endtab %} + +{% endtabs %} + Now let's look at a more interesting example starting with an abstract class: -```tut +{% tabs mixin-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-abstract-iterator %} +```scala mdoc abstract class AbsIterator { type T def hasNext: Boolean def next(): T } ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-abstract-iterator %} +```scala +abstract class AbsIterator: + type T + def hasNext: Boolean + def next(): T +``` +{% endtab %} + +{% endtabs %} + The class has an abstract type `T` and the standard iterator methods. Next, we'll implement a concrete class (all abstract members `T`, `hasNext`, and `next` have implementations): -```tut +{% tabs mixin-concrete-string-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-concrete-string-iterator %} +```scala mdoc class StringIterator(s: String) extends AbsIterator { type T = Char private var i = 0 @@ -58,26 +99,72 @@ class StringIterator(s: String) extends AbsIterator { } } ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-concrete-string-iterator %} +```scala +class StringIterator(s: String) extends AbsIterator: + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = + val ch = s charAt i + i += 1 + ch +``` +{% endtab %} + +{% endtabs %} + `StringIterator` takes a `String` and can be used to iterate over the String (e.g. to see if a String contains a certain character). Now let's create a trait which also extends `AbsIterator`. -```tut +{% tabs mixin-extended-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-extended-abstract-iterator %} +```scala mdoc trait RichIterator extends AbsIterator { def foreach(f: T => Unit): Unit = while (hasNext) f(next()) } ``` This trait implements `foreach` by continually calling the provided function `f: T => Unit` on the next element (`next()`) as long as there are further elements (`while (hasNext)`). Because `RichIterator` is a trait, it doesn't need to implement the abstract members of AbsIterator. +{% endtab %} + +{% tab 'Scala 3' for=mixin-extended-abstract-iterator %} +```scala +trait RichIterator extends AbsIterator: + def foreach(f: T => Unit): Unit = while hasNext do f(next()) +``` +This trait implements `foreach` by continually calling the provided function `f: T => Unit` on the next element (`next()`) as long as there are further elements (`while hasNext`). Because `RichIterator` is a trait, it doesn't need to implement the abstract members of AbsIterator. + +{% endtab %} + +{% endtabs %} + We would like to combine the functionality of `StringIterator` and `RichIterator` into a single class. -```tut -object StringIteratorTest extends App { - class RichStringIter extends StringIterator("Scala") with RichIterator - val richStringIter = new RichStringIter - richStringIter foreach println -} +{% tabs mixin-combination-class class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-combination-class %} +```scala mdoc +class RichStringIter extends StringIterator("Scala") with RichIterator +val richStringIter = new RichStringIter +richStringIter.foreach(println) +``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-combination-class %} +```scala +class RichStringIter extends StringIterator("Scala"), RichIterator +val richStringIter = RichStringIter() +richStringIter.foreach(println) ``` +{% endtab %} + +{% endtabs %} + The new class `RichStringIter` has `StringIterator` as a superclass and `RichIterator` as a mixin. With single inheritance we would not be able to achieve this level of flexibility. diff --git a/_tour/multiple-parameter-lists.md b/_tour/multiple-parameter-lists.md index 7d4ae731e1..324795b6c0 100644 --- a/_tour/multiple-parameter-lists.md +++ b/_tour/multiple-parameter-lists.md @@ -1,81 +1,218 @@ --- layout: tour -title: Multiple Parameter Lists (Currying) - -discourse: true - +title: Multiple Parameter Lists partof: scala-tour -num: 10 +num: 12 next-page: case-classes previous-page: nested-functions redirect_from: "/tutorials/tour/multiple-parameter-lists.html" --- -Methods may define multiple parameter lists. When a method is called with a fewer number of parameter lists, then this will yield a function taking the missing parameter lists as its arguments. This is formally known as [currying](https://en.wikipedia.org/wiki/Currying). +Methods may have multiple parameter lists. + +### Example + +Here is an example, as defined on the `Iterable` trait in Scala's collections API: -Here is an example, defined in [Traversable](/overviews/collections/trait-traversable.html) trait from Scala collections: +{% tabs foldLeft_definition class=tabs-scala-version %} +{% tab 'Scala 2' for=foldLeft_definition %} +```scala +trait Iterable[A] { + ... + def foldLeft[B](z: B)(op: (B, A) => B): B + ... +} ``` -def foldLeft[B](z: B)(op: (B, A) => B): B +{% endtab %} + +{% tab 'Scala 3' for=foldLeft_definition %} +```scala +trait Iterable[A]: + ... + def foldLeft[B](z: B)(op: (B, A) => B): B + ... ``` +{% endtab %} -`foldLeft` applies a binary operator `op` to an initial value `z` and all elements of this traversable, going left to right. Shown below is an example of its usage. +{% endtabs %} + +`foldLeft` applies a two-parameter function `op` to an initial value `z` and all elements of this collection, going left to right. Shown below is an example of its usage. Starting with an initial value of 0, `foldLeft` here applies the function `(m, n) => m + n` to each element in the List and the previous accumulated value. -```tut +{% tabs foldLeft_use %} + +{% tab 'Scala 2 and 3' for=foldLeft_use %} +```scala mdoc val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) val res = numbers.foldLeft(0)((m, n) => m + n) -print(res) // 55 +println(res) // 55 ``` +{% endtab %} + +{% endtabs %} -Multiple parameter lists have a more verbose invocation syntax; and hence should be used sparingly. Suggested use cases include: +### Use cases -#### Single functional parameter - In case of a single functional parameter, like `op` in the case of `foldLeft` above, multiple parameter lists allow a concise syntax to pass an anonymous function to the method. Without multiple parameter lists, the code would look like this: +Suggested use cases for multiple parameter lists include: +#### Drive type inference + +It so happens that in Scala, type inference proceeds one parameter list at a time. +Say you have the following method: + +{% tabs foldLeft1_definition %} + +{% tab 'Scala 2 and 3' for=foldLeft1_definition %} +```scala mdoc +def foldLeft1[A, B](as: List[A], b0: B, op: (B, A) => B) = ??? ``` -numbers.foldLeft(0, {(m: Int, n: Int) => m + n}) +{% endtab %} + +{% endtabs %} + +Then you'd like to call it in the following way, but will find that it doesn't compile: + +{% tabs foldLeft1_wrong_use %} + +{% tab 'Scala 2 and 3' for=foldLeft1_wrong_use %} +```scala mdoc:fail +def notPossible = foldLeft1(numbers, 0, _ + _) ``` - - Note that the use of multiple parameter lists here also allows us to take advantage of Scala type inference to make the code more concise as shown below; which would not be possible in a non-curried definition. - +{% endtab %} + +{% endtabs %} + +you will have to call it like one of the below ways: + +{% tabs foldLeft1_good_use %} + +{% tab 'Scala 2 and 3' for=foldLeft1_good_use %} +```scala mdoc +def firstWay = foldLeft1[Int, Int](numbers, 0, _ + _) +def secondWay = foldLeft1(numbers, 0, (a: Int, b: Int) => a + b) ``` -numbers.foldLeft(0)(_ + _) +{% endtab %} + +{% endtabs %} + +That's because Scala won't be able to infer the type of the function `_ + _`, as it's still inferring `A` and `B`. By moving the parameter `op` to its own parameter list, `A` and `B` are inferred in the first parameter list. These inferred types will then be available to the second parameter list and `_ + _` will match the inferred type `(Int, Int) => Int` + +{% tabs foldLeft2_definition_and_use %} + +{% tab 'Scala 2 and 3' for=foldLeft2_definition_and_use %} +```scala mdoc +def foldLeft2[A, B](as: List[A], b0: B)(op: (B, A) => B) = ??? +def possible = foldLeft2(numbers, 0)(_ + _) ``` - Above statement `numbers.foldLeft(0)(_ + _)` allows us to fix the parameter `z` and pass around a partial function and reuse it as shown below: -```tut -val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) -val numberFunc = numbers.foldLeft(List[Int]())_ +{% endtab %} + +{% endtabs %} + +This definition doesn't need any type hints and can infer all of its type parameters. + -val squares = numberFunc((xs, x) => xs:+ x*x) -print(squares.toString()) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) +#### Implicit parameters + +To specify only certain parameters as [`implicit`](https://docs.scala-lang.org/tour/implicit-parameters.html), they must be placed in their own `implicit` parameter list. + +An example of this is: + +{% tabs execute_definition class=tabs-scala-version %} -val cubes = numberFunc((xs, x) => xs:+ x*x*x) -print(cubes.toString()) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +{% tab 'Scala 2' for=execute_definition %} +```scala mdoc +def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ??? ``` +{% endtab %} + +{% tab 'Scala 3' for=execute_definition %} +```scala +def execute(arg: Int)(using ec: scala.concurrent.ExecutionContext) = ??? +``` +{% endtab %} + +{% endtabs %} - Finally, `foldLeft` and `foldRight` can be used in any of the following terms, -```tut +#### Partial application + +When a method is called with a fewer number of parameter lists, then this will yield a function taking the missing parameter lists as its arguments. This is formally known as [partial application](https://en.wikipedia.org/wiki/Partial_application). + +For example, + +{% tabs foldLeft_partial class=tabs-scala-version %} + +{% tab 'Scala 2' for=foldLeft_partial %} +```scala mdoc:nest val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]()) _ -numbers.foldLeft(0)((sum, item) => sum + item) // Generic Form -numbers.foldRight(0)((sum, item) => sum + item) // Generic Form +val squares = numberFunc((xs, x) => xs :+ x*x) +println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) -numbers.foldLeft(0)(_+_) // Curried Form -numbers.foldRight(0)(_+_) // Curried Form +val cubes = numberFunc((xs, x) => xs :+ x*x*x) +println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` +{% endtab %} -(0 /: numbers)(_+_) // Used in place of foldLeft -(numbers :\ 0)(_+_) // Used in place of foldRight -``` +{% tab 'Scala 3' for=foldLeft_partial %} +```scala +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]()) - -#### Implicit parameters - To specify certain parameters in a parameter list as `implicit`, multiple parameter lists should be used. An example of this is: +val squares = numberFunc((xs, x) => xs :+ x*x) +println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) +val cubes = numberFunc((xs, x) => xs :+ x*x*x) +println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) ``` -def execute(arg: Int)(implicit ec: ExecutionContext) = ??? +{% endtab %} + +{% endtabs %} + +### Comparison with "currying" + +You may sometimes see a method with multiple parameter lists referred to as "curried". + +As the [Wikipedia article on currying](https://en.wikipedia.org/wiki/Currying) states, + +> Currying is the technique of converting a function that takes +> multiple arguments into a sequence of functions that each takes a +> single argument + +We discourage the use of the word "curry" in reference to Scala's multiple parameter lists, for two reasons: + +1) In Scala, multiple parameters and multiple parameter lists are +specified and implemented directly, as part of the language, rather +being derived from single-parameter functions. + +2) There is danger of confusion with the Scala standard library's +[`curried`](https://www.scala-lang.org/api/current/scala/Function2.html#curried:T1=%3E(T2=%3ER)) +and [`uncurried`](https://www.scala-lang.org/api/current/scala/Function$.html#uncurried[T1,T2,R](f:T1=%3E(T2=%3ER)):(T1,T2)=%3ER) methods, which don't involve multiple parameter lists at all. + +Regardless, there are certainly similarities to be found between +multiple parameter lists and currying. Though they are different at +the definition site, the call site might nonetheless look identical, +as in this example: + +{% tabs about_currying %} + +{% tab 'Scala 2 and 3' for=about_currying %} +```scala mdoc +// version with multiple parameter lists +def addMultiple(n1: Int)(n2: Int) = n1 + n2 +// two different ways of arriving at a curried version instead +def add(n1: Int, n2: Int) = n1 + n2 +val addCurried1 = (add _).curried +val addCurried2 = (n1: Int) => (n2: Int) => n1 + n2 +// regardless, all three call sites are identical +addMultiple(3)(4) // 7 +addCurried1(3)(4) // 7 +addCurried2(3)(4) // 7 ``` - +{% endtab %} + +{% endtabs %} diff --git a/_tour/named-arguments.md b/_tour/named-arguments.md index d8d1d7a88e..cec14a5ebf 100644 --- a/_tour/named-arguments.md +++ b/_tour/named-arguments.md @@ -1,34 +1,57 @@ --- layout: tour title: Named Arguments - -discourse: true - partof: scala-tour -num: 34 -next-page: packages-and-imports +num: 6 +next-page: traits previous-page: default-parameter-values prerequisite-knowledge: function-syntax -redirect_from: "/tutorials/tour/named-arguments.html" +redirect_from: + - "/tutorials/tour/named-arguments.html" + - "/tutorials/tour/named-parameters.html" --- When calling methods, you can label the arguments with their parameter names like so: -```tut -def printName(first: String, last: String): Unit = { - println(first + " " + last) -} +{% tabs named-arguments-when-good %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-good %} +```scala mdoc +def printName(first: String, last: String): Unit = + println(s"$first $last") -printName("John", "Smith") // Prints "John Smith" -printName(first = "John", last = "Smith") // Prints "John Smith" -printName(last = "Smith", first = "John") // Prints "John Smith" +printName("John", "Public") // Prints "John Public" +printName(first = "John", last = "Public") // Prints "John Public" +printName(last = "Public", first = "John") // Prints "John Public" +printName("Elton", last = "John") // Prints "Elton John" ``` -Notice how the order of named arguments can be rearranged. However, if some arguments are named and others are not, the unnamed arguments must come first and in the order of their parameters in the method signature. +{% endtab %} + +{% endtabs %} + +This is useful when two parameters have the same type and the arguments could be accidentally swapped. -```tut:fail -printName(last = "Smith", "john") // error: positional after named argument +Notice that named arguments can be written in any order. However, once the arguments are not in parameter order, reading from left to right, then the rest of the arguments must be named. + +In the following example, named arguments enable the middle parameter to be omitted. But in the error case, the first argument is out of order, so the second argument must be named. + +{% tabs named-arguments-when-error %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-error %} +```scala mdoc:fail +def printFullName(first: String, middle: String = "Q.", last: String): Unit = + println(s"$first $middle $last") + +printFullName(first = "John", last = "Public") // Prints "John Q. Public" +printFullName("John", last = "Public") // Prints "John Q. Public" +printFullName("John", middle = "Quincy", "Public") // Prints "John Quincy Public" +printFullName(last = "Public", first = "John") // Prints "John Q. Public" +printFullName(last = "Public", "John") // error: positional after named argument ``` +{% endtab %} + +{% endtabs %} -Note that named arguments do not work with calls to Java methods. +Named arguments work with calls to Java methods, but only if the Java library in question was compiled with the `-parameters` flag. diff --git a/_tour/nested-functions.md b/_tour/nested-functions.md index 9ec45648d3..45d00e2db6 100644 --- a/_tour/nested-functions.md +++ b/_tour/nested-functions.md @@ -1,12 +1,9 @@ --- layout: tour title: Nested Methods - -discourse: true - partof: scala-tour -num: 9 +num: 11 next-page: multiple-parameter-lists previous-page: higher-order-functions @@ -15,22 +12,48 @@ redirect_from: "/tutorials/tour/nested-functions.html" In Scala it is possible to nest method definitions. The following object provides a `factorial` method for computing the factorial of a given number: -```tut - def factorial(x: Int): Int = { - def fact(x: Int, accumulator: Int): Int = { - if (x <= 1) accumulator - else fact(x - 1, x * accumulator) - } - fact(x, 1) - } - - println("Factorial of 2: " + factorial(2)) - println("Factorial of 3: " + factorial(3)) +{% tabs Nested_functions_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=Nested_functions_definition %} +```scala mdoc +def factorial(x: Int): Int = { + def fact(x: Int, accumulator: Int): Int = { + if (x <= 1) accumulator + else fact(x - 1, x * accumulator) + } + fact(x, 1) +} + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) ``` +{% endtab %} + +{% tab 'Scala 3' for=Nested_functions_definition %} +```scala +def factorial(x: Int): Int = + def fact(x: Int, accumulator: Int): Int = + if x <= 1 then accumulator + else fact(x - 1, x * accumulator) + fact(x, 1) + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) + +``` +{% endtab %} + +{% endtabs %} The output of this program is: +{% tabs Nested_functions_result %} + +{% tab 'Scala 2 and 3' for=Nested_functions_result %} ``` Factorial of 2: 2 Factorial of 3: 6 ``` +{% endtab %} + +{% endtabs %} diff --git a/_tour/operators.md b/_tour/operators.md index b3ad662813..fb157ce334 100644 --- a/_tour/operators.md +++ b/_tour/operators.md @@ -1,12 +1,9 @@ --- layout: tour title: Operators - -discourse: true - partof: scala-tour -num: 30 +num: 32 next-page: by-name-parameters previous-page: type-inference prerequisite-knowledge: case-classes @@ -14,20 +11,33 @@ prerequisite-knowledge: case-classes redirect_from: "/tutorials/tour/operators.html" --- In Scala, operators are methods. Any method with a single parameter can be used as an _infix operator_. For example, `+` can be called with dot-notation: + +{% tabs operators_1 %} +{% tab 'Scala 2 and 3' for=operators_1 %} ``` 10.+(1) ``` +{% endtab %} +{% endtabs %} However, it's easier to read as an infix operator: + +{% tabs operators_2 %} +{% tab 'Scala 2 and 3' for=operators_2 %} ``` 10 + 1 ``` +{% endtab %} +{% endtabs %} ## Defining and using operators You can use any legal identifier as an operator. This includes a name like `add` or a symbol(s) like `+`. -```tut -case class Vec(val x: Double, val y: Double) { - def +(that: Vec) = new Vec(this.x + that.x, this.y + that.y) + +{% tabs operators_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_3 %} +```scala mdoc +case class Vec(x: Double, y: Double) { + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) } val vector1 = Vec(1.0, 1.0) @@ -37,22 +47,54 @@ val vector3 = vector1 + vector2 vector3.x // 3.0 vector3.y // 3.0 ``` +{% endtab %} +{% tab 'Scala 3' for=operators_3 %} +```scala +case class Vec(x: Double, y: Double): + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) + +val vector1 = Vec(1.0, 1.0) +val vector2 = Vec(2.0, 2.0) + +val vector3 = vector1 + vector2 +vector3.x // 3.0 +vector3.y // 3.0 +``` +{% endtab %} +{% endtabs %} + The class Vec has a method `+` which we used to add `vector1` and `vector2`. Using parentheses, you can build up complex expressions with readable syntax. Here is the definition of class `MyBool` which includes methods `and` and `or`: -```tut +{% tabs operators_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_4 %} +```scala mdoc case class MyBool(x: Boolean) { def and(that: MyBool): MyBool = if (x) that else this def or(that: MyBool): MyBool = if (x) this else that def negate: MyBool = MyBool(!x) } ``` +{% endtab %} +{% tab 'Scala 3' for=operators_4 %} +```scala +case class MyBool(x: Boolean): + def and(that: MyBool): MyBool = if x then that else this + def or(that: MyBool): MyBool = if x then this else that + def negate: MyBool = MyBool(!x) +``` +{% endtab %} +{% endtabs %} It is now possible to use `and` and `or` as infix operators: -```tut +{% tabs operators_5 %} +{% tab 'Scala 2 and 3' for=operators_5 %} +```scala mdoc def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) ``` +{% endtab %} +{% endtabs %} This helps to make the definition of `xor` more readable. @@ -63,19 +105,31 @@ When an expression uses multiple operators, the operators are evaluated based on * / % + - : -= ! < > += ! & ^ | -(all letters) +(all letters, $, _) ``` This applies to functions you define. For example, the following expression: + +{% tabs operators_7 %} +{% tab 'Scala 2 and 3' for=operators_7 %} ``` a + b ^? c ?^ d less a ==> b | c ``` +{% endtab %} +{% endtabs %} + Is equivalent to + +{% tabs operators_8 %} +{% tab 'Scala 2 and 3' for=operators_8 %} ``` ((a + b) ^? (c ?^ d)) less ((a ==> b) | c) ``` +{% endtab %} +{% endtabs %} + `?^` has the highest precedence because it starts with the character `?`. `+` has the second highest precedence, followed by `==>`, `^?`, `|`, and `less`. diff --git a/_tour/package-objects.md b/_tour/package-objects.md new file mode 100644 index 0000000000..8be239c933 --- /dev/null +++ b/_tour/package-objects.md @@ -0,0 +1,156 @@ +--- +layout: tour +title: Top Level Definitions in Packages +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- + +Often, it is convenient to have definitions accessible across an entire package, and not need to invent a +name for a wrapper `object` to contain them. + +{% tabs pkg-obj-vs-top-lvl_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_1 %} +Scala 2 provides _package objects_ as a convenient container shared across an entire package. + +Package objects +can contain arbitrary definitions, not just variable and method definitions. For instance, they are frequently +used to hold package-wide type aliases and implicit conversions. Package objects can even inherit +Scala classes and traits. + +> In a future version of Scala 3, package objects will be removed in favor of top level definitions. + +By convention, the source code for a package object is usually put in a source file named `package.scala`. + +Each package is allowed to have one package object. Any definitions placed in a package object are considered +members of the package itself. + +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_1 %} +In Scala 3, any kind of definition can be declared at the top level of a package. For example, classes, enums, +methods and variables. + +Any definitions placed at the top level of a package are considered members of the package itself. + +> In Scala 2, top-level method, type and variable definitions had to be wrapped in a **package object**. +> These are still usable in Scala 3 for backwards compatibility. You can see how they work by switching tabs. + +{% endtab %} +{% endtabs %} + +See example below. Assume first a class `Fruit` and three `Fruit` objects in a package +`gardening.fruits`: + + +{% tabs pkg-obj-vs-top-lvl_2 %} +{% tab 'Scala 2 and 3' for=pkg-obj-vs-top-lvl_2 %} +``` +// in file gardening/fruits/Fruit.scala +package gardening.fruits + +case class Fruit(name: String, color: String) +object Apple extends Fruit("Apple", "green") +object Plum extends Fruit("Plum", "blue") +object Banana extends Fruit("Banana", "yellow") +``` +{% endtab %} +{% endtabs %} + +Now assume you want to place a variable `planted` and a method `showFruit` directly into package `gardening.fruits`. +Here's how this is done: + +{% tabs pkg-obj-vs-top-lvl_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_3 %} + +``` +// in file gardening/fruits/package.scala +package gardening +package object fruits { + val planted = List(Apple, Plum, Banana) + def showFruit(fruit: Fruit): Unit = { + println(s"${fruit.name}s are ${fruit.color}") + } +} +``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_3 %} + +``` +// in file gardening/fruits/package.scala +package gardening.fruits + +val planted = List(Apple, Plum, Banana) +def showFruit(fruit: Fruit): Unit = + println(s"${fruit.name}s are ${fruit.color}") +``` +{% endtab %} +{% endtabs %} + +As an example of how to use this, the following program imports `planted` and `showFruit` in exactly the same +way it imports class `Fruit`, using a wildcard import on package `gardening.fruits`: + +{% tabs pkg-obj-vs-top-lvl_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_4 %} +``` +// in file PrintPlanted.scala +import gardening.fruits._ + +object PrintPlanted { + def main(args: Array[String]): Unit = { + for (fruit <- planted) { + showFruit(fruit) + } + } +} +``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_4 %} +``` +// in file printPlanted.scala +import gardening.fruits.* + +@main def printPlanted(): Unit = + for fruit <- planted do + showFruit(fruit) +``` +{% endtab %} +{% endtabs %} + +### Aggregating Several Definitions at the Package Level + +Often, your project may have several reusable definitions defined in various modules, that you +wish to aggregate at the top level of a package. + +For example, some helper methods in the trait `FruitHelpers` and +some term/type aliases in trait `FruitAliases`. Here is how you can put all their definitions at the level of the `fruit` +package: + +{% tabs pkg-obj-vs-top-lvl_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_5 %} + +Package objects are like other objects, which means you can use inheritance for building them. +So here we mix in the helper traits as parents of the package object. + +``` +package gardening + +// `fruits` instead inherits its members from its parents. +package object fruits extends FruitAliases with FruitHelpers +``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_5 %} + +In Scala 3, it is preferred to use `export` to compose members from several objects into a single scope. +Here we define private objects that mix in the helper traits, then export their members at the top level: + +``` +package gardening.fruits + +private object FruitAliases extends FruitAliases +private object FruitHelpers extends FruitHelpers + +export FruitHelpers.*, FruitAliases.* +``` +{% endtab %} +{% endtabs %} diff --git a/_tour/packages-and-imports.md b/_tour/packages-and-imports.md index 35c9b198b2..3f07344f32 100644 --- a/_tour/packages-and-imports.md +++ b/_tour/packages-and-imports.md @@ -1,13 +1,11 @@ --- layout: tour title: Packages and Imports - -discourse: true - partof: scala-tour num: 35 -previous-page: named-arguments +next-page: package-objects +previous-page: annotations --- # Packages and Imports @@ -16,11 +14,16 @@ Scala uses packages to create namespaces which allow you to modularize programs. ## Creating a package Packages are created by declaring one or more package names at the top of a Scala file. +{% tabs packages-and-imports_1 %} +{% tab 'Scala 2 and 3' for=packages-and-imports_1 %} ``` package users class User ``` +{% endtab %} +{% endtabs %} + One convention is to name the package the same as the directory containing the Scala file. However, Scala is agnostic to file layout. The directory structure of an sbt project for `package users` might look like this: ``` - ExampleProject @@ -35,8 +38,11 @@ One convention is to name the package the same as the directory containing the S UserPreferences.scala - test ``` -Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by using braces: -``` +Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by nesting them inside each other: + +{% tabs packages-and-imports_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_2 %} +```scala package users { package administrators { class NormalUser @@ -46,39 +52,95 @@ package users { } } ``` +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_2 %} +```scala +package users: + package administrators: + class NormalUser + + package normalusers: + class NormalUser +``` +{% endtab %} +{% endtabs %} + As you can see, this allows for package nesting and provides greater control for scope and encapsulation. The package name should be all lower case and if the code is being developed within an organization which has a website, it should be the following format convention: `..`. For example, if Google had a project called `SelfDrivingCar`, the package name would look like this: -``` + +{% tabs packages-and-imports_3 %} +{% tab 'Scala 2 and 3' for=packages-and-imports_3 %} +```scala package com.google.selfdrivingcar.camera class Lens ``` +{% endtab %} +{% endtabs %} + This could correspond to the following directory structure: `SelfDrivingCar/src/main/scala/com/google/selfdrivingcar/camera/Lens.scala`. ## Imports `import` clauses are for accessing members (classes, traits, functions, etc.) in other packages. An `import` clause is not required for accessing members of the same package. Import clauses are selective: + +{% tabs packages-and-imports_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_4 %} ``` import users._ // import everything from the users package import users.User // import the class User import users.{User, UserPreferences} // Only imports selected members import users.{UserPreferences => UPrefs} // import and rename for convenience ``` +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_4 %} +``` +import users.* // import everything from the users package except given +import users.given // import all given from the users package +import users.User // import the class User +import users.{User, UserPreferences} // Only imports selected members +import users.UserPreferences as UPrefs // import and rename for convenience +``` +{% endtab %} +{% endtabs %} One way in which Scala is different from Java is that imports can be used anywhere: -```tut +{% tabs packages-and-imports_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_5 %} +```scala mdoc def sqrtplus1(x: Int) = { import scala.math.sqrt sqrt(x) + 1.0 } ``` -In the event there is a naming conflict and you need to import something from the root of the project, prefix the package name with `_root_`: +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_5 %} +```scala +def sqrtplus1(x: Int) = + import scala.math.sqrt + sqrt(x) + 1.0 ``` +{% endtab %} +{% endtabs %} + +In the event there is a naming conflict and you need to import something from the root of the project, prefix the package name with `_root_`: + +{% tabs packages-and-imports_6 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_6 %} +```scala package accounts import _root_.users._ ``` +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_6 %} +```scala +package accounts +import _root_.users.* +``` +{% endtab %} +{% endtabs %} Note: The `scala` and `java.lang` packages as well as `object Predef` are imported by default. diff --git a/_tour/pattern-matching.md b/_tour/pattern-matching.md index 5a6d4969c4..f48682afea 100644 --- a/_tour/pattern-matching.md +++ b/_tour/pattern-matching.md @@ -1,13 +1,9 @@ --- layout: tour title: Pattern Matching - -discourse: true - partof: scala-tour -num: 12 - +num: 14 next-page: singleton-objects previous-page: case-classes prerequisite-knowledge: case-classes, string-interpolation, subtyping @@ -19,7 +15,9 @@ Pattern matching is a mechanism for checking a value against a pattern. A succes ## Syntax A match expression has a value, the `match` keyword, and at least one `case` clause. -```tut +{% tabs pattern-matching-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-1 %} +```scala mdoc import scala.util.Random val x: Int = Random.nextInt(10) @@ -28,49 +26,85 @@ x match { case 0 => "zero" case 1 => "one" case 2 => "two" - case _ => "many" + case _ => "other" } ``` -The `val x` above is a random integer between 0 and 10. `x` becomes the left operand of the `match` operator and on the right is an expression with four cases. The last case `_` is a "catch all" case for any number greater than 2. Cases are also called _alternatives_. +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-1 %} +```scala +import scala.util.Random + +val x: Int = Random.nextInt(10) + +x match + case 0 => "zero" + case 1 => "one" + case 2 => "two" + case _ => "other" +``` +{% endtab %} +{% endtabs %} +The `val x` above is a random integer between 0 and 9. `x` becomes the left operand of the `match` operator and on the right is an expression with four cases. The last case `_` is a "catch all" case for any other possible `Int` values. Cases are also called _alternatives_. Match expressions have a value. -```tut +{% tabs pattern-matching-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-2 %} +```scala mdoc def matchTest(x: Int): String = x match { case 1 => "one" case 2 => "two" - case _ => "many" + case _ => "other" } -matchTest(3) // many -matchTest(1) // one +matchTest(3) // returns other +matchTest(1) // returns one +``` +{% endtab %} + +{% tab 'Scala 3' for=pattern-matching-2 %} +```scala +def matchTest(x: Int): String = x match + case 1 => "one" + case 2 => "two" + case _ => "other" + +matchTest(3) // returns other +matchTest(1) // returns one ``` +{% endtab %} +{% endtabs %} This match expression has a type String because all of the cases return String. Therefore, the function `matchTest` returns a String. ## Matching on case classes Case classes are especially useful for pattern matching. -```tut -abstract class Notification +{% tabs notification %} +{% tab 'Scala 2 and 3' for=notification %} +```scala mdoc +sealed trait Notification case class Email(sender: String, title: String, body: String) extends Notification case class SMS(caller: String, message: String) extends Notification case class VoiceRecording(contactName: String, link: String) extends Notification - - ``` -`Notification` is an abstract super class which has three concrete Notification types implemented with case classes `Email`, `SMS`, and `VoiceRecording`. Now we can do pattern matching on these case classes: +{% endtab %} +{% endtabs %} -``` +`Notification` is a sealed trait which has three concrete Notification types implemented with case classes `Email`, `SMS`, and `VoiceRecording`. (A [sealed trait](/tour/pattern-matching.html#sealed-types) can be extended only in the same file as its declaration.) Now we can do pattern matching on these case classes: + +{% tabs pattern-matching-4 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-4 %} +```scala def showNotification(notification: Notification): String = { notification match { - case Email(email, title, _) => - s"You got an email from $email with title: $title" + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" case SMS(number, message) => s"You got an SMS from $number! Message: $message" case VoiceRecording(name, link) => - s"you received a Voice Recording from $name! Click the link to hear it: $link" + s"You received a Voice Recording from $name! Click the link to hear it: $link" } } val someSms = SMS("12345", "Are you there?") @@ -78,17 +112,104 @@ val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") println(showNotification(someSms)) // prints You got an SMS from 12345! Message: Are you there? -println(showNotification(someVoiceRecording)) // you received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123 +println(showNotification(someVoiceRecording)) // prints You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123 ``` -The function `showNotification` takes as a parameter the abstract type `Notification` and matches on the type of `Notification` (i.e. it figures out whether it's an `Email`, `SMS`, or `VoiceRecording`). In the `case Email(email, title, _)` the fields `email` and `title` are used in the return value but the `body` field is ignored with `_`. +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-4 %} +```scala +def showNotification(notification: Notification): String = + notification match + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" + case VoiceRecording(name, link) => + s"You received a Voice Recording from $name! Click the link to hear it: $link" -## Pattern guards -Pattern guards are simply boolean expressions which are used to make cases more specific. Just add `if ` after the pattern. +val someSms = SMS("12345", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") + +println(showNotification(someSms)) // prints You got an SMS from 12345! Message: Are you there? + +println(showNotification(someVoiceRecording)) // prints You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123 +``` +{% endtab %} +{% endtabs %} + +The function `showNotification` takes as a parameter the abstract type `Notification` and matches on the type of `Notification` (i.e. it figures out whether it's an `Email`, `SMS`, or `VoiceRecording`). In the `case Email(sender, title, _)` the fields `sender` and `title` are used in the return value but the `body` field is ignored with `_`. + +## Matching on string + +The `s`-interpolator allows embedding variables in strings and is also useful for pattern matching. + +{% tabs s-interpolator-pattern-matching class=tabs-scala-version %} +{% tab 'Scala 2' for=s-interpolator-pattern-matching %} +```scala +val input: String = "Alice is 25 years old" + +input match { + case s"$name is $age years old" => s"$name's age is $age" + case _ => "No match" +} +// Result: "Alice's age is 25" ``` +{% endtab %} +{% tab 'Scala 3' for=s-interpolator-pattern-matching %} +```scala +val input: String = "Alice is 25 years old" + +input match + case s"$name is $age years old" => s"$name's age is $age" + case _ => "No match" +// Result: "Alice's age is 25" +``` +{% endtab %} +{% endtabs %} + +In this example, name and age extract parts of the string based on the pattern. This is helpful for parsing structured text. + +We can also use extractor objects for string pattern matching. + +{% tabs s-interpolator-pattern-matching-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=s-interpolator-pattern-matching-2 %} +```scala +object Age { + def unapply(s: String): Option[Int] = s.toIntOption +} + +val input: String = "Alice is 25 years old" + +val (name, age) = input match { + case s"$name is ${Age(age)} years old" => (name, age) +} +// name: String = Alice +// age: Int = 25 +``` +{% endtab %} +{% tab 'Scala 3' for=s-interpolator-pattern-matching-2 %} +```scala +object Age: + def unapply(s: String): Option[Int] = s.toIntOption + +val input: String = "Alice is 25 years old" + +val (name, age) = input match + case s"$name is ${Age(age)} years old" => (name, age) +// name: String = Alice +// age: Int = 25 +``` +{% endtab %} +{% endtabs %} + +## Pattern guards +Pattern guards are boolean expressions which are used to make cases more specific. Just add `if ` after the pattern. +{% tabs pattern-matching-5 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-5 %} +```scala def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String = { notification match { - case Email(email, _, _) if importantPeopleInfo.contains(email) => + case Email(sender, _, _) if importantPeopleInfo.contains(sender) => "You got an email from special someone!" case SMS(number, _) if importantPeopleInfo.contains(number) => "You got an SMS from special someone!" @@ -99,53 +220,168 @@ def showImportantNotification(notification: Notification, importantPeopleInfo: S val importantPeopleInfo = Seq("867-5309", "jenny@gmail.com") -val someSms = SMS("867-5309", "Are you there?") +val someSms = SMS("123-4567", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") +val importantEmail = Email("jenny@gmail.com", "Drinks tonight?", "I'm free after 5!") +val importantSms = SMS("867-5309", "I'm here! Where are you?") + +println(showImportantNotification(someSms, importantPeopleInfo)) // prints You got an SMS from 123-4567! Message: Are you there? +println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) // prints You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123 +println(showImportantNotification(importantEmail, importantPeopleInfo)) // prints You got an email from special someone! + +println(showImportantNotification(importantSms, importantPeopleInfo)) // prints You got an SMS from special someone! +``` +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-5 %} +```scala +def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String = + notification match + case Email(sender, _, _) if importantPeopleInfo.contains(sender) => + "You got an email from special someone!" + case SMS(number, _) if importantPeopleInfo.contains(number) => + "You got an SMS from special someone!" + case other => + showNotification(other) // nothing special, delegate to our original showNotification function + +val importantPeopleInfo = Seq("867-5309", "jenny@gmail.com") + +val someSms = SMS("123-4567", "Are you there?") val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") val importantEmail = Email("jenny@gmail.com", "Drinks tonight?", "I'm free after 5!") val importantSms = SMS("867-5309", "I'm here! Where are you?") -println(showImportantNotification(someSms, importantPeopleInfo)) -println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) -println(showImportantNotification(importantEmail, importantPeopleInfo)) -println(showImportantNotification(importantSms, importantPeopleInfo)) +println(showImportantNotification(someSms, importantPeopleInfo)) // prints You got an SMS from 123-4567! Message: Are you there? +println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) // prints You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123 +println(showImportantNotification(importantEmail, importantPeopleInfo)) // prints You got an email from special someone! + +println(showImportantNotification(importantSms, importantPeopleInfo)) // prints You got an SMS from special someone! ``` +{% endtab %} +{% endtabs %} -In the `case Email(email, _, _) if importantPeopleInfo.contains(email)`, the pattern is matched only if the `email` is in the list of important people. +In the `case Email(sender, _, _) if importantPeopleInfo.contains(sender)`, the pattern is matched only if the `sender` is in the list of important people. ## Matching on type only You can match on the type like so: -```tut -abstract class Device -case class Phone(model: String) extends Device{ +{% tabs pattern-matching-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-6 %} +```scala mdoc +sealed trait Device +case class Phone(model: String) extends Device { def screenOff = "Turning screen off" } case class Computer(model: String) extends Device { def screenSaverOn = "Turning screen saver on..." } -def goIdle(device: Device) = device match { +def goIdle(device: Device): String = device match { case p: Phone => p.screenOff case c: Computer => c.screenSaverOn } ``` +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-6 %} +```scala +sealed trait Device +case class Phone(model: String) extends Device: + def screenOff = "Turning screen off" + +case class Computer(model: String) extends Device: + def screenSaverOn = "Turning screen saver on..." + + +def goIdle(device: Device): String = device match + case p: Phone => p.screenOff + case c: Computer => c.screenSaverOn +``` +{% endtab %} +{% endtabs %} + `def goIdle` has a different behavior depending on the type of `Device`. This is useful when the case needs to call a method on the pattern. It is a convention to use the first letter of the type as the case identifier (`p` and `c` in this case). -## Sealed classes -Traits and classes can be marked `sealed` which means all subtypes must be declared in the same file. This assures that all subtypes are known. +## Binding matched patterns to variables +You can use variable binding to get type-dependent behavior while simultaneously extracting fields from the matched pattern. + +{% tabs pattern-matching-variable-binding class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-variable-binding %} +```scala mdoc +def goIdleWithModel(device: Device): String = device match { + case p @ Phone(model) => s"$model: ${p.screenOff}" + case c @ Computer(model) => s"$model: ${c.screenSaverOn}" +} +``` +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-variable-binding %} +```scala +def goIdleWithModel(device: Device): String = device match + case p @ Phone(model) => s"$model: ${p.screenOff}" + case c @ Computer(model) => s"$model: ${c.screenSaverOn}" +``` +{% endtab %} +{% endtabs %} + +## Sealed types -```tut -sealed abstract class Furniture -case class Couch() extends Furniture -case class Chair() extends Furniture +You may have noticed that in the examples above the base types are qualified +with the keyword `sealed`. This provides extra safety because the compiler +checks that the `cases` of a `match` expression are exhaustive when the base +type is `sealed`. -def findPlaceToSit(piece: Furniture): String = piece match { - case a: Couch => "Lie on the couch" - case b: Chair => "Sit on the chair" +For instance, in the method `showNotification` defined above, if we forget +one case, say, `VoiceRecording`, the compiler emits a warning: + +{% tabs pattern-matching-7 class=tabs-scala-version %} +{% tab 'Scala 2' for=pattern-matching-7 %} +```scala +def showNotification(notification: Notification): String = { + notification match { + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" + } } ``` -This is useful for pattern matching because we don't need a "catch all" case. +{% endtab %} +{% tab 'Scala 3' for=pattern-matching-7 %} +```scala +def showNotification(notification: Notification): String = + notification match + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" +``` +{% endtab %} +{% endtabs %} + +This definition produces the following warning: + +~~~ +match may not be exhaustive. + +It would fail on pattern case: VoiceRecording(_, _) +~~~ + +The compiler even provides examples of input that would fail! + +On the flip side, exhaustivity checking requires you to define all the subtypes +of the base type in the same file as the base type (otherwise, the compiler +would not know what are all the possible cases). For instance, if you try +to define a new type of `Notification` outside of the file that defines +the `sealed trait Notification`, it will produce a compilation error: + +~~~ +case class Telepathy(message: String) extends Notification + ^ + Cannot extend sealed trait Notification in a different source file +~~~ ## Notes Scala's pattern matching statement is most useful for matching on algebraic types expressed via [case classes](case-classes.html). Scala also allows the definition of patterns independently of case classes, using `unapply` methods in [extractor objects](extractor-objects.html). + +## More resources + +* More details on match expressions in the [Scala Book](/scala3/book/control-structures.html#match-expressions) diff --git a/_tour/polymorphic-methods.md b/_tour/polymorphic-methods.md index 8f9cb4525f..e8f99858e9 100644 --- a/_tour/polymorphic-methods.md +++ b/_tour/polymorphic-methods.md @@ -1,12 +1,9 @@ --- layout: tour title: Polymorphic Methods - -discourse: true - partof: scala-tour -num: 28 +num: 30 next-page: type-inference previous-page: implicit-conversions @@ -15,11 +12,13 @@ prerequisite-knowledge: unified-types redirect_from: "/tutorials/tour/polymorphic-methods.html" --- -Methods in Scala can be parameterized by type as well as value. The syntax is similar to that of generic classes. Type parameters are enclosed in square brackets, while value parameters are enclosed in parentheses. +Methods in Scala can be parameterized by type as well as by value. The syntax is similar to that of generic classes. Type parameters are enclosed in square brackets, while value parameters are enclosed in parentheses. Here is an example: -```tut +{% tabs polymorphic-methods_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=polymorphic-methods_1 %} +```scala mdoc def listOfDuplicates[A](x: A, length: Int): List[A] = { if (length < 1) Nil @@ -29,9 +28,23 @@ def listOfDuplicates[A](x: A, length: Int): List[A] = { println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3) println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La) ``` +{% endtab %} +{% tab 'Scala 3' for=polymorphic-methods_1 %} +```scala +def listOfDuplicates[A](x: A, length: Int): List[A] = + if length < 1 then + Nil + else + x :: listOfDuplicates(x, length - 1) + +println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3) +println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La) +``` +{% endtab %} +{% endtabs %} -The method `listOfDuplicates` takes a type parameter `A` and value parameters `x` and `length`. Value `x` is of type `A`. If `length < 1` we return an empty list. Otherwise we prepend `x` to the the list of duplicates returned by the recursive call. (Note that `::` means prepend an element on the left to a list on the right.) +The method `listOfDuplicates` takes a type parameter `A` and value parameters `x` and `length`. Value `x` is of type `A`. If `length < 1` we return an empty list. Otherwise we prepend `x` to the list of duplicates returned by the recursive call. (Note that `::` means prepend an element on the left to a list on the right.) -In first example call, we explicitly provide the type parameter by writing `[Int]`. Therefore the first argument must be an `Int` and the return type will be `List[Int]`. +In the first example call, we explicitly provide the type parameter by writing `[Int]`. Therefore the first argument must be an `Int` and the return type will be a `List[Int]`. -The second example call shows that you don't always need to explicitly provide the type parameter. The compiler can often infer it based on context or on the types of the value arguments. In this example, `"La"` is a `String` so the compiler knows `A` must be `String`. +The second example call shows that you don't always need to explicitly provide the type parameter. The compiler can often infer it based on context or on the types of the value arguments. In this example, `"La"` is a `String` so the compiler knows that `A` must be a `String`. diff --git a/_tour/regular-expression-patterns.md b/_tour/regular-expression-patterns.md index ec07f9f368..40d12e5003 100644 --- a/_tour/regular-expression-patterns.md +++ b/_tour/regular-expression-patterns.md @@ -1,12 +1,9 @@ --- layout: tour title: Regular Expression Patterns - -discourse: true - partof: scala-tour -num: 15 +num: 17 next-page: extractor-objects previous-page: singleton-objects @@ -16,7 +13,10 @@ redirect_from: "/tutorials/tour/regular-expression-patterns.html" Regular expressions are strings which can be used to find patterns (or lack thereof) in data. Any string can be converted to a regular expression using the `.r` method. -```tut +{% tabs regex-patterns_numberPattern class=tabs-scala-version %} + +{% tab 'Scala 2' for=regex-patterns_numberPattern %} +```scala mdoc import scala.util.matching.Regex val numberPattern: Regex = "[0-9]".r @@ -26,16 +26,34 @@ numberPattern.findFirstMatchIn("awesomepassword") match { case None => println("Password must contain a number") } ``` +{% endtab %} + +{% tab 'Scala 3' for=regex-patterns_numberPattern %} +```scala +import scala.util.matching.Regex + +val numberPattern: Regex = "[0-9]".r + +numberPattern.findFirstMatchIn("awesomepassword") match + case Some(_) => println("Password OK") + case None => println("Password must contain a number") +``` +{% endtab %} + +{% endtabs %} In the above example, the `numberPattern` is a `Regex` (regular expression) which we use to make sure a password contains a number. You can also search for groups of regular expressions using parentheses. -```tut +{% tabs regex-patterns_keyValPattern class=tabs-scala-version %} + +{% tab 'Scala 2' for=regex-patterns_keyValPattern %} +```scala mdoc import scala.util.matching.Regex -val keyValPattern: Regex = "([0-9a-zA-Z-#() ]+): ([0-9a-zA-Z-#() ]+)".r +val keyValPattern: Regex = "([0-9a-zA-Z- ]+): ([0-9a-zA-Z-#()/. ]+)".r val input: String = """background-color: #A03300; @@ -50,10 +68,35 @@ val input: String = for (patternMatch <- keyValPattern.findAllMatchIn(input)) println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}") ``` +{% endtab %} + +{% tab 'Scala 3' for=regex-patterns_keyValPattern %} +```scala +import scala.util.matching.Regex + +val keyValPattern: Regex = "([0-9a-zA-Z- ]+): ([0-9a-zA-Z-#()/. ]+)".r + +val input: String = + """background-color: #A03300; + |background-image: url(img/header100.png); + |background-position: top center; + |background-repeat: repeat-x; + |background-size: 2160px 108px; + |margin: 0; + |height: 108px; + |width: 100%;""".stripMargin + +for patternMatch <- keyValPattern.findAllMatchIn(input) do + println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}") +``` +{% endtab %} + +{% endtabs %} + Here we parse out the keys and values of a String. Each match has a group of sub-matches. Here is the output: ``` key: background-color value: #A03300 -key: background-image value: url(img +key: background-image value: url(img/header100.png) key: background-position value: top center key: background-repeat value: repeat-x key: background-size value: 2160px 108px @@ -61,3 +104,63 @@ key: margin value: 0 key: height value: 108px key: width value: 100 ``` + +Moreover, regular expressions can be used as patterns (in `match` expressions) to conveniently extract the matched groups: + +{% tabs regex-patterns_saveContactInformation class=tabs-scala-version %} + +{% tab 'Scala 2' for=regex-patterns_saveContactInformation %} +```scala mdoc +def saveContactInformation(contact: String): Unit = { + import scala.util.matching.Regex + + val emailPattern: Regex = """^(\w+)@(\w+(.\w+)+)$""".r + val phonePattern: Regex = """^(\d{3}-\d{3}-\d{4})$""".r + + contact match { + case emailPattern(localPart, domainName, _) => + println(s"Hi $localPart, we have saved your email address.") + case phonePattern(phoneNumber) => + println(s"Hi, we have saved your phone number $phoneNumber.") + case _ => + println("Invalid contact information, neither an email address nor phone number.") + } +} + +saveContactInformation("123-456-7890") +saveContactInformation("JohnSmith@sample.domain.com") +saveContactInformation("2 Franklin St, Mars, Milky Way") +``` +{% endtab %} + +{% tab 'Scala 3' for=regex-patterns_saveContactInformation %} +```scala +def saveContactInformation(contact: String): Unit = + import scala.util.matching.Regex + + val emailPattern: Regex = """^(\w+)@(\w+(.\w+)+)$""".r + val phonePattern: Regex = """^(\d{3}-\d{3}-\d{4})$""".r + + contact match + case emailPattern(localPart, domainName, _) => + println(s"Hi $localPart, we have saved your email address.") + case phonePattern(phoneNumber) => + println(s"Hi, we have saved your phone number $phoneNumber.") + case _ => + println("Invalid contact information, neither an email address nor phone number.") + +saveContactInformation("123-456-7890") +saveContactInformation("JohnSmith@sample.domain.com") +saveContactInformation("2 Franklin St, Mars, Milky Way") +``` +{% endtab %} + +{% endtabs %} + +The output would be: + +``` +Hi, we have saved your phone number 123-456-7890. +Hi JohnSmith, we have saved your email address. +Invalid contact information, neither an email address nor phone number. +``` diff --git a/_tour/self-types.md b/_tour/self-types.md index f54e62ae18..f209fd5101 100644 --- a/_tour/self-types.md +++ b/_tour/self-types.md @@ -1,12 +1,9 @@ --- layout: tour title: Self-type - -discourse: true - partof: scala-tour -num: 25 +num: 27 next-page: implicit-parameters previous-page: compound-types topics: self-types @@ -19,7 +16,10 @@ Self-types are a way to declare that a trait must be mixed into another trait, e A self-type is a way to narrow the type of `this` or another identifier that aliases `this`. The syntax looks like normal function syntax but means something entirely different. To use a self-type in a trait, write an identifier, the type of another trait to mix in, and a `=>` (e.g. `someIdentifier: SomeOtherTrait =>`). -```tut + +{% tabs self-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=self-types_1 %} +```scala mdoc trait User { def username: String } @@ -30,11 +30,31 @@ trait Tweeter { } class VerifiedTweeter(val username_ : String) extends Tweeter with User { // We mixin User because Tweeter required it - def username = s"real $username_" + def username = s"real $username_" } val realBeyoncé = new VerifiedTweeter("Beyoncé") realBeyoncé.tweet("Just spilled my glass of lemonade") // prints "real Beyoncé: Just spilled my glass of lemonade" ``` - Because we said `this: User =>` in `trait Tweeter`, now the variable `username` is in scope for the `tweet` method. This also means that since `VerifiedTweeter` extends `Tweeter`, it must also mix-in `User` (using `with User`). + +{% endtab %} +{% tab 'Scala 3' for=self-types_1 %} +```scala +trait User: + def username: String + +trait Tweeter: + this: User => // reassign this + def tweet(tweetText: String) = println(s"$username: $tweetText") + +class VerifiedTweeter(val username_ : String) extends Tweeter, User: // We mixin User because Tweeter required it + def username = s"real $username_" + +val realBeyoncé = VerifiedTweeter("Beyoncé") +realBeyoncé.tweet("Just spilled my glass of lemonade") // prints "real Beyoncé: Just spilled my glass of lemonade" +``` +Because we said `this: User =>` in `trait Tweeter`, now the variable `username` is in scope for the `tweet` method. This also means that since `VerifiedTweeter` extends `Tweeter`, it must also mix-in `User` (using `, User`). + +{% endtab %} +{% endtabs %} diff --git a/_tour/singleton-objects.md b/_tour/singleton-objects.md index 2e05c851f2..828d49a38a 100644 --- a/_tour/singleton-objects.md +++ b/_tour/singleton-objects.md @@ -1,13 +1,9 @@ --- layout: tour title: Singleton Objects - -discourse: true - partof: scala-tour -num: 13 - +num: 15 next-page: regular-expression-patterns previous-page: pattern-matching redirect_from: "/tutorials/tour/singleton-objects.html" @@ -20,23 +16,52 @@ As a top-level value, an object is a singleton. As a member of an enclosing class or as a local value, it behaves exactly like a lazy val. # Defining a singleton object An object is a value. The definition of an object looks like a class, but uses the keyword `object`: -```tut + + +{% tabs object-definition-box %} + +{% tab 'Scala 2 and 3' for=object-definition-box %} +```scala mdoc object Box ``` +{% endtab %} + +{% endtabs %} Here's an example of an object with a method: -``` +{% tabs singleton-logger-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=singleton-logger-example %} + +```scala package logging object Logger { def info(message: String): Unit = println(s"INFO: $message") } ``` +{% endtab %} + +{% tab 'Scala 3' for=singleton-logger-example %} + +```scala +package logging + +object Logger: + def info(message: String): Unit = println(s"INFO: $message") +``` +{% endtab %} + +{% endtabs %} + The method `info` can be imported from anywhere in the program. Creating utility methods like this is a common use case for singleton objects. Let's see how to use `info` in another package: +{% tabs singleton-usage-example class=tabs-scala-version %} -``` +{% tab 'Scala 2' for=singleton-usage-example %} + +```scala import logging.Logger.info class Project(name: String, daysToComplete: Int) @@ -47,6 +72,24 @@ class Test { info("Created projects") // Prints "INFO: Created projects" } ``` +{% endtab %} + +{% tab 'Scala 3' for=singleton-usage-example %} + +```scala +import logging.Logger.info + +class Project(name: String, daysToComplete: Int) + +class Test: + val project1 = Project("TPS Reports", 1) + val project2 = Project("Website redesign", 5) + info("Created projects") // Prints "INFO: Created projects" +``` +{% endtab %} + +{% endtabs %} + The `info` method is visible because of the import statement, `import logging.Logger.info`. @@ -57,8 +100,11 @@ Note: If an `object` is not top-level but is nested in another class or object, ## Companion objects An object with the same name as a class is called a _companion object_. Conversely, the class is the object's companion class. A companion class or object can access the private members of its companion. Use a companion object for methods and values which are not specific to instances of the companion class. -``` -import scala.math._ +{% tabs companion-object-circle class=tabs-scala-version %} + +{% tab 'Scala 2' for=companion-object-circle %} +```scala +import scala.math.{Pi, pow} case class Circle(radius: Double) { import Circle._ @@ -69,15 +115,39 @@ object Circle { private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) } -val circle1 = new Circle(5.0) +val circle1 = Circle(5.0) circle1.area ``` +{% endtab %} + +{% tab 'Scala 3' for=companion-object-circle %} +```scala +import scala.math.{Pi, pow} + +case class Circle(radius: Double): + import Circle.* + def area: Double = calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) + + +val circle1 = Circle(5.0) + +circle1.area +``` +{% endtab %} + +{% endtabs %} The `class Circle` has a member `area` which is specific to each instance, and the singleton `object Circle` has a method `calculateArea` which is available to every instance. The companion object can also contain factory methods: -```tut +{% tabs companion-object-email class=tabs-scala-version %} + +{% tab 'Scala 2' for=companion-object-email %} +```scala mdoc class Email(val username: String, val domainName: String) object Email { @@ -95,12 +165,45 @@ scalaCenterEmail match { s"""Registered an email |Username: ${email.username} |Domain name: ${email.domainName} - """) + """.stripMargin) case None => println("Error: could not parse email") } ``` +{% endtab %} + +{% tab 'Scala 3' for=companion-object-email %} +```scala +class Email(val username: String, val domainName: String) + +object Email: + def fromString(emailString: String): Option[Email] = + emailString.split('@') match + case Array(a, b) => Some(Email(a, b)) + case _ => None + +val scalaCenterEmail = Email.fromString("scala.center@epfl.ch") +scalaCenterEmail match + case Some(email) => println( + s"""Registered an email + |Username: ${email.username} + |Domain name: ${email.domainName} + """.stripMargin) + case None => println("Error: could not parse email") +``` +{% endtab %} + +{% endtabs %} + The `object Email` contains a factory `fromString` which creates an `Email` instance from a String. We return it as an `Option[Email]` in case of parsing errors. +A note about `Option`, `Some`, and `None` in the code above: +* `Option` is a data type which allows for optionality. It has two cases: `Some` and `None` + * `Some` above represents a match: the emailString, when split by a @, returns an array with two components. This allows creation of a valid instance of class Email. + * `None` above represents no match: the emailString, when split by a @, did not return an array with two components. It could not allow creation of a valid instance of class Email. +* The `Option` return type can then be used in a match/case: + * For a `Some` result, the match knows the returned value is an instance of `Email`, so it can access the inner `username` and `domainName`. + * For a `None` result, the match knows the returned value is not an instance of `Email`, so it prints an appropriate error message. + Note: If a class or object has a companion, both must be defined in the same file. To define companions in the REPL, either define them on the same line or enter `:paste` mode. ## Notes for Java programmers ## @@ -108,3 +211,7 @@ Note: If a class or object has a companion, both must be defined in the same fil `static` members in Java are modeled as ordinary members of a companion object in Scala. When using a companion object from Java code, the members will be defined in a companion class with a `static` modifier. This is called _static forwarding_. It occurs even if you haven't defined a companion class yourself. + +## More resources + +* Learn more about Companion objects in the [Scala Book](/scala3/book/domain-modeling-tools.html#companion-objects) diff --git a/_tour/tour-of-scala.md b/_tour/tour-of-scala.md index b99ce9f8cb..16052b51f8 100644 --- a/_tour/tour-of-scala.md +++ b/_tour/tour-of-scala.md @@ -1,16 +1,16 @@ --- layout: tour title: Introduction - -discourse: true - partof: scala-tour num: 1 next-page: basics -redirect_from: "/tutorials/tour/tour-of-scala.html" +redirect_from: + - "/tutorials/tour/tour-of-scala.html" + - "/tutorials/tour/anonymous-function-syntax.html" + - "/tutorials/tour/explicitly-typed-self-references.html" --- ## Welcome to the tour @@ -18,49 +18,47 @@ This tour contains bite-sized introductions to the most frequently used features of Scala. It is intended for newcomers to the language. This is just a brief tour, not a full language tutorial. If -you want that, consider obtaining [a book](/books.html) or consulting -[other resources](/learn.html). +you want a more detailed guide, consider obtaining [a book](/books.html) or taking +[an online courses](/online-courses.html). ## What is Scala? -Scala is a modern multi-paradigm programming language designed to express common programming patterns in a concise, elegant, and type-safe way. It smoothly integrates features of object-oriented and functional languages. +Scala is a modern multi-paradigm programming language designed to express common programming patterns in a concise, elegant, and type-safe way. It seamlessly integrates features of object-oriented and functional languages. ## Scala is object-oriented ## -Scala is a pure object-oriented language in the sense that [every value is an object](unified-types.html). Types and behavior of objects are described by [classes](classes.html) and [traits](traits.html). Classes are extended by subclassing and a flexible [mixin-based composition](mixin-class-composition.html) mechanism as a clean replacement for multiple inheritance. +Scala is a pure object-oriented language in the sense that [every value is an object](unified-types.html). Types and behaviors of objects are described by [classes](classes.html) and [traits](traits.html). Classes can be extended by subclassing, and by using a flexible [mixin-based composition](mixin-class-composition.html) mechanism as a clean replacement for multiple inheritance. ## Scala is functional ## -Scala is also a functional language in the sense that [every function is a value](unified-types.html). Scala provides a [lightweight syntax](basics.html#functions) for defining anonymous functions, it supports [higher-order functions](higher-order-functions.html), it allows functions to be [nested](nested-functions.html), and supports [currying](multiple-parameter-lists.html). Scala's [case classes](case-classes.html) and its built-in support for [pattern matching](pattern-matching.html) model algebraic types used in many functional programming languages. [Singleton objects](singleton-objects.html) provide a convenient way to group functions that aren't members of a class. - -Furthermore, Scala's notion of pattern matching naturally extends to the [processing of XML data](https://github.com/scala/scala-xml/wiki/XML-Processing) with the help of [right-ignoring sequence patterns](regular-expression-patterns.html), by way of general extension via [extractor objects](extractor-objects.html). In this context, [for comprehensions](for-comprehensions.html) are useful for formulating queries. These features make Scala ideal for developing applications like web services. +Scala is also a functional language in the sense that [every function is a value](unified-types.html). Scala provides a [lightweight syntax](basics.html#functions) for defining anonymous functions, supports [higher-order functions](higher-order-functions.html), allows functions to be [nested](nested-functions.html), and supports [currying](multiple-parameter-lists.html). Scala's [case classes](case-classes.html) and its built-in support for [pattern matching](pattern-matching.html) provide the functionality of algebraic types, which are used in many functional languages. [Singleton objects](singleton-objects.html) provide a convenient way to group functions that aren't members of a class. ## Scala is statically typed ## -Scala is equipped with an expressive type system that enforces statically that abstractions are used in a safe and coherent manner. In particular, the type system supports: +Scala's expressive type system enforces, at compile-time, that abstractions are used in a safe and coherent manner. In particular, the type system supports: -* [generic classes](generic-classes.html) -* [variance annotations](variances.html) -* [upper](upper-type-bounds.html) and [lower](lower-type-bounds.html) type bounds, -* [inner classes](inner-classes.html) and [abstract types](abstract-types.html) as object members -* [compound types](compound-types.html) -* [explicitly typed self references](self-types.html) -* [implicit parameters](implicit-parameters.html) and [conversions](implicit-conversions.html) -* [polymorphic methods](polymorphic-methods.html) +* [Generic classes](generic-classes.html) +* [Variance annotations](variances.html) +* [Upper](upper-type-bounds.html) and [lower](lower-type-bounds.html) type bounds +* [Inner classes](inner-classes.html) and [abstract type members](abstract-type-members.html) as object members +* [Compound types](compound-types.html) +* [Explicitly typed self references](self-types.html) +* [Implicit parameters](implicit-parameters.html) and [conversions](implicit-conversions.html) +* [Polymorphic methods](polymorphic-methods.html) [Type inference](type-inference.html) means the user is not required to annotate code with redundant type information. In combination, these features provide a powerful basis for the safe reuse of programming abstractions and for the type-safe extension of software. ## Scala is extensible ## -In practice, the development of domain-specific applications often requires domain-specific language extensions. Scala provides a unique combination of language mechanisms that make it easy to smoothly add new language constructs in the form of libraries. +In practice, the development of domain-specific applications often requires domain-specific language extensions. Scala provides a unique combination of language mechanisms that make it straightforward to add new language constructs in the form of libraries. -In many cases, this can be done without using meta-programming facilities such as macros. For example, +In many cases, this can be done without using meta-programming facilities such as macros. For example: -* [Implicit classes](http://docs.scala-lang.org/overviews/core/implicit-classes.html) allow adding extension methods to existing types. +* [Implicit classes](/overviews/core/implicit-classes.html) allow adding extension methods to existing types. * [String interpolation](/overviews/core/string-interpolation.html) is user-extensible with custom interpolators. ## Scala interoperates -Scala is designed to interoperate well with the popular Java Runtime Environment (JRE). In particular, the interaction with the mainstream object-oriented Java programming language is as smooth as possible. Newer Java features like SAMs, [lambdas](higher-order-functions.html), [annotations](annotations.html), and [generics](generic-classes.html) have direct analogues in Scala. +Scala is designed to interoperate well with the popular Java Runtime Environment (JRE). In particular, the interaction with the mainstream object-oriented Java programming language is as seamless as possible. Newer Java features like SAMs, [lambdas](higher-order-functions.html), [annotations](annotations.html), and [generics](generic-classes.html) have direct analogues in Scala. -Those Scala features without Java analogues, such as [default](default-parameter-values.html) and [named parameters](named-arguments.html), compile as close to Java as they can reasonably come. Scala has the same compilation model (separate compilation, dynamic class loading) like Java and allows access to thousands of existing high-quality libraries. +Those Scala features without Java analogues, such as [default](default-parameter-values.html) and [named parameters](named-arguments.html), compile as closely to Java as reasonably possible. Scala has the same compilation model (separate compilation, dynamic class loading) as Java and allows access to thousands of existing high-quality libraries. ## Enjoy the tour! -Please continue to the [next page](basics.html) in the Contents menu to read more. +Please continue to the [next page](basics.html) to read more. diff --git a/_tour/traits.md b/_tour/traits.md index bc01ac1f2d..f719f96744 100644 --- a/_tour/traits.md +++ b/_tour/traits.md @@ -1,42 +1,62 @@ --- layout: tour title: Traits - -discourse: true - partof: scala-tour -num: 5 -next-page: mixin-class-composition -previous-page: classes +num: 7 +next-page: tuples +previous-page: named-arguments topics: traits prerequisite-knowledge: expressions, classes, generics, objects, companion-objects redirect_from: "/tutorials/tour/traits.html" --- -Traits are used to share interfaces and fields between classes. They are similar to Java 8's interfaces. Classes and objects can extend traits but traits cannot be instantiated and therefore have no parameters. +Traits are used to share interfaces and fields between classes. They are similar to Java 8's interfaces. Classes and objects can extend traits, but traits cannot be instantiated and therefore have no parameters. ## Defining a trait A minimal trait is simply the keyword `trait` and an identifier: -```tut +{% tabs trait-hair-color %} +{% tab 'Scala 2 and 3' for=trait-hair-color %} +```scala mdoc trait HairColor ``` +{% endtab %} +{% endtabs %} Traits become especially useful as generic types and with abstract methods. -```tut + +{% tabs trait-iterator-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=trait-iterator-definition %} +```scala mdoc trait Iterator[A] { def hasNext: Boolean def next(): A } ``` +{% endtab %} + +{% tab 'Scala 3' for=trait-iterator-definition %} +```scala +trait Iterator[A]: + def hasNext: Boolean + def next(): A +``` +{% endtab %} + +{% endtabs %} Extending the `trait Iterator[A]` requires a type `A` and implementations of the methods `hasNext` and `next`. ## Using traits Use the `extends` keyword to extend a trait. Then implement any abstract members of the trait using the `override` keyword: -```tut + +{% tabs trait-intiterator-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=trait-intiterator-definition %} +```scala mdoc:nest trait Iterator[A] { def hasNext: Boolean def next(): A @@ -45,7 +65,7 @@ trait Iterator[A] { class IntIterator(to: Int) extends Iterator[Int] { private var current = 0 override def hasNext: Boolean = current < to - override def next(): Int = { + override def next(): Int = { if (hasNext) { val t = current current += 1 @@ -54,16 +74,47 @@ class IntIterator(to: Int) extends Iterator[Int] { } } - val iterator = new IntIterator(10) iterator.next() // returns 0 iterator.next() // returns 1 ``` +{% endtab %} + +{% tab 'Scala 3' for=trait-intiterator-definition %} +```scala +trait Iterator[A]: + def hasNext: Boolean + def next(): A + +class IntIterator(to: Int) extends Iterator[Int]: + private var current = 0 + override def hasNext: Boolean = current < to + override def next(): Int = + if hasNext then + val t = current + current += 1 + t + else + 0 +end IntIterator + +val iterator = IntIterator(10) +iterator.next() // returns 0 +iterator.next() // returns 1 +``` +{% endtab %} + +{% endtabs %} + This `IntIterator` class takes a parameter `to` as an upper bound. It `extends Iterator[Int]` which means that the `next` method must return an Int. ## Subtyping Where a given trait is required, a subtype of the trait can be used instead. -```tut + +{% tabs trait-pet-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=trait-pet-example %} +```scala mdoc import scala.collection.mutable.ArrayBuffer trait Pet { @@ -81,4 +132,34 @@ animals.append(dog) animals.append(cat) animals.foreach(pet => println(pet.name)) // Prints Harry Sally ``` -The `trait Pet` has an abstract field `name` which gets implemented by Cat and Dog in their constructors. On the last line, we call `pet.name` which must be implemented in any subtype of the trait `Pet`. +{% endtab %} + +{% tab 'Scala 3' for=trait-pet-example %} +```scala +import scala.collection.mutable.ArrayBuffer + +trait Pet: + val name: String + +class Cat(val name: String) extends Pet +class Dog(val name: String) extends Pet + +val dog = Dog("Harry") +val cat = Cat("Sally") + +val animals = ArrayBuffer.empty[Pet] +animals.append(dog) +animals.append(cat) +animals.foreach(pet => println(pet.name)) // Prints Harry Sally +``` +{% endtab %} + +{% endtabs %} + +The `trait Pet` has an abstract field `name` that gets implemented by Cat and Dog in their constructors. On the last line, we call `pet.name`, which must be implemented in any subtype of the trait `Pet`. + + +## More resources + +* Learn more about traits in the [Scala Book](/scala3/book/domain-modeling-tools.html#traits) +* Use traits to define [Enum](/scala3/book/domain-modeling-fp.html#modeling-the-data) diff --git a/_tour/tuples.md b/_tour/tuples.md new file mode 100644 index 0000000000..19166098fb --- /dev/null +++ b/_tour/tuples.md @@ -0,0 +1,129 @@ +--- +layout: tour +title: Tuples +partof: scala-tour + +num: 8 +next-page: mixin-class-composition +previous-page: traits +topics: tuples + +redirect_from: "/tutorials/tour/tuples.html" +--- + +In Scala, a tuple is a value that contains a fixed number of elements, each +with its own type. Tuples are immutable. + +Tuples are especially handy for returning multiple values from a method. + +A tuple with two elements can be created as follows: + +{% tabs tuple-construction %} + +{% tab 'Scala 2 and 3' for=tuple-construction %} +```scala mdoc +val ingredient = ("Sugar", 25) +``` +{% endtab %} + +{% endtabs %} + +This creates a tuple containing a `String` element and an `Int` element. + +The inferred type of `ingredient` is `(String, Int)`. + +## Accessing the elements + +{% tabs tuple-indexed-access class=tabs-scala-version %} + +{% tab 'Scala 2' for=tuple-indexed-access %} +One way of accessing tuple elements is their positions. +The individual elements are named `_1`, `_2`, and so forth. + +```scala mdoc +println(ingredient._1) // Sugar +println(ingredient._2) // 25 +``` +{% endtab %} + +{% tab 'Scala 3' for=tuple-indexed-access %} +One way of accessing tuple elements is their positions. +The individual elements are accessed with `tuple(0)`, `tuple(1)`, and so forth. + +```scala +println(ingredient(0)) // Sugar +println(ingredient(1)) // 25 +``` +{% endtab %} + +{% endtabs %} + +## Pattern matching on tuples + +A tuple can also be taken apart using pattern matching: + +{% tabs tuple-extraction %} + +{% tab 'Scala 2 and 3' for=tuple-extraction %} +```scala mdoc +val (name, quantity) = ingredient +println(name) // Sugar +println(quantity) // 25 +``` +{% endtab %} + +{% endtabs %} + +Here `name`'s inferred type is `String` and `quantity`'s inferred type +is `Int`. + +Here is another example of pattern-matching a tuple: + +{% tabs tuple-foreach-patmat %} + +{% tab 'Scala 2 and 3' for=tuple-foreach-patmat %} +```scala mdoc +val planets = + List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6), + ("Mars", 227.9), ("Jupiter", 778.3)) +planets.foreach { + case ("Earth", distance) => + println(s"Our planet is $distance million kilometers from the sun") + case _ => +} +``` +{% endtab %} + +{% endtabs %} + +Or, in a `for` comprehension: + +{% tabs tuple-for-extraction class=tabs-scala-version %} + +{% tab 'Scala 2' for=tuple-for-extraction %} +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) +for ((a, b) <- numPairs) { + println(a * b) +} +``` +{% endtab %} + +{% tab 'Scala 3' for=tuple-for-extraction %} +```scala +val numPairs = List((2, 5), (3, -7), (20, 56)) +for (a, b) <- numPairs do + println(a * b) +``` +{% endtab %} + +{% endtabs %} + +## Tuples and case classes + +Users may sometimes find it hard to choose between tuples and case classes. Case classes have named elements. The names can improve the readability of some kinds of code. In the planet example above, we might define `case class Planet(name: String, distance: Double)` rather than using tuples. + + +## More resources + +* Learn more about tuples in the [Scala Book](/scala3/book/taste-collections.html#tuples) diff --git a/_tour/type-inference.md b/_tour/type-inference.md index d949fc4f4b..3b5ea38cc0 100644 --- a/_tour/type-inference.md +++ b/_tour/type-inference.md @@ -1,12 +1,9 @@ --- layout: tour title: Type Inference - -discourse: true - partof: scala-tour -num: 29 +num: 31 next-page: operators previous-page: polymorphic-methods --- @@ -15,33 +12,56 @@ The Scala compiler can often infer the type of an expression so you don't have t ## Omitting the type -```tut +{% tabs type-inference_1 %} +{% tab 'Scala 2 and 3' for=type-inference_1 %} +```scala mdoc val businessName = "Montreux Jazz Café" ``` +{% endtab %} +{% endtabs %} + The compiler can detect that `businessName` is a String. It works similarly with methods: -```tut +{% tabs type-inference_2 %} +{% tab 'Scala 2 and 3' for=type-inference_2 %} +```scala mdoc def squareOf(x: Int) = x * x ``` +{% endtab %} +{% endtabs %} + The compiler can infer that the return type is an `Int`, so no explicit return type is required. For recursive methods, the compiler is not able to infer a result type. Here is a program which will fail the compiler for this reason: -```tut:fail +{% tabs type-inference_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=type-inference_3 %} +```scala mdoc:fail def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1) ``` +{% endtab %} +{% tab 'Scala 3' for=type-inference_3 %} +```scala +def fac(n: Int) = if n == 0 then 1 else n * fac(n - 1) +``` +{% endtab %} +{% endtabs %} It is also not compulsory to specify type parameters when [polymorphic methods](polymorphic-methods.html) are called or [generic classes](generic-classes.html) are instantiated. The Scala compiler will infer such missing type parameters from the context and from the types of the actual method/constructor parameters. Here are two examples: -```tut -case class MyPair[A, B](x: A, y: B); +{% tabs type-inference_4 %} +{% tab 'Scala 2 and 3' for=type-inference_4 %} +```scala mdoc +case class MyPair[A, B](x: A, y: B) val p = MyPair(1, "scala") // type: MyPair[Int, String] def id[T](x: T) = x val q = id(1) // type: Int ``` +{% endtab %} +{% endtabs %} The compiler uses the types of the arguments of `MyPair` to figure out what type `A` and `B` are. Likewise for the type of `x`. @@ -49,26 +69,38 @@ The compiler uses the types of the arguments of `MyPair` to figure out what type The compiler never infers method parameter types. However, in certain cases, it can infer anonymous function parameter types when the function is passed as argument. -```tut +{% tabs type-inference_5 %} +{% tab 'Scala 2 and 3' for=type-inference_5 %} +```scala mdoc Seq(1, 3, 4).map(x => x * 2) // List(2, 6, 8) ``` +{% endtab %} +{% endtabs %} The parameter for map is `f: A => B`. Because we put integers in the `Seq`, the compiler knows that `A` is `Int` (i.e. that `x` is an integer). Therefore, the compiler can infer from `x * 2` that `B` is type `Int`. ## When _not_ to rely on type inference -It is generally considered more readable to declare the type of members exposed in a public API. Therefore, we recommended that you make the type explicit for any APIs that will be exposed to users of your code. +It is generally considered more readable to declare the type of members exposed in a public API. Therefore, we recommend that you make the type explicit for any APIs that will be exposed to users of your code. Also, type inference can sometimes infer a too-specific type. Suppose we write: -```tut +{% tabs type-inference_6 %} +{% tab 'Scala 2 and 3' for=type-inference_6 %} +```scala var obj = null ``` +{% endtab %} +{% endtabs %} We can't then go on and make this reassignment: -```tut:fail +{% tabs type-inference_7 %} +{% tab 'Scala 2 and 3' for=type-inference_7 %} +```scala mdoc:fail obj = new AnyRef ``` +{% endtab %} +{% endtabs %} It won't compile, because the type inferred for `obj` was `Null`. Since the only value of that type is `null`, it is impossible to assign a different value. diff --git a/_tour/unified-types.md b/_tour/unified-types.md index 2c4d5bb239..a6f0e9c0dd 100644 --- a/_tour/unified-types.md +++ b/_tour/unified-types.md @@ -1,9 +1,6 @@ --- layout: tour title: Unified Types - -discourse: true - partof: scala-tour num: 3 @@ -20,15 +17,17 @@ In Scala, all values have a type, including numerical values and functions. The ## Scala Type Hierarchy ## -[`Any`](http://www.scala-lang.org/api/2.12.1/scala/Any.html) is the supertype of all types, also called the top type. It defines certain universal methods such as `equals`, `hashCode`, and `toString`. `Any` has two direct subclasses: `AnyVal` and `AnyRef`. +[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html) is the supertype of all types, also called the top type. It defines certain universal methods such as `equals`, `hashCode`, and `toString`. `Any` has two direct subclasses: `AnyVal` and `AnyRef`. `AnyVal` represents value types. There are nine predefined value types and they are non-nullable: `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit`, and `Boolean`. `Unit` is a value type which carries no meaningful information. There is exactly one instance of `Unit` which can be declared literally like so: `()`. All functions must return something so sometimes `Unit` is a useful return type. `AnyRef` represents reference types. All non-value types are defined as reference types. Every user-defined type in Scala is a subtype of `AnyRef`. If Scala is used in the context of a Java runtime environment, `AnyRef` corresponds to `java.lang.Object`. -Here is an example that demonstrates that strings, integers, characters, boolean values, and functions are all objects just like every other object: +Here is an example that demonstrates that strings, integers, characters, boolean values, and functions are all of type `Any` just like every other object: -```tut +{% tabs unified-types-1 %} +{% tab 'Scala 2 and 3' for=unified-types-1 %} +```scala mdoc val list: List[Any] = List( "a string", 732, // an integer @@ -39,8 +38,10 @@ val list: List[Any] = List( list.foreach(element => println(element)) ``` +{% endtab %} +{% endtabs %} -It defines a variable `list` of type `List[Any]`. The list is initialized with elements of various types, but they all are instance of `scala.Any`, so you can add them to the list. +It defines a value `list` of type `List[Any]`. The list is initialized with elements of various types, but each is an instance of `scala.Any`, so you can add them to the list. Here is the output of the program: @@ -56,23 +57,35 @@ true Value types can be cast in the following way: Scala Type Hierarchy +Note that `Long` to `Float` conversion is deprecated in new versions of Scala, because of the potential precision lost. + For example: -```tut +{% tabs unified-types-2 %} +{% tab 'Scala 2 and 3' for=unified-types-2 %} +```scala mdoc val x: Long = 987654321 -val y: Float = x // 9.8765434E8 (note that some precision is lost in this case) +val y: Float = x.toFloat // 9.8765434E8 (note that some precision is lost in this case) val face: Char = '☺' val number: Int = face // 9786 ``` +{% endtab %} +{% endtabs %} + Casting is unidirectional. This will not compile: -``` +{% tabs unified-types-3 %} +{% tab 'Scala 2 and 3' for=unified-types-3 %} +```scala val x: Long = 987654321 -val y: Float = x // 9.8765434E8 +val y: Float = x.toFloat // 9.8765434E8 val z: Long = y // Does not conform ``` +{% endtab %} +{% endtabs %} + You can also cast a reference type to a subtype. This will be covered later in the tour. diff --git a/_tour/upper-type-bounds.md b/_tour/upper-type-bounds.md index 5ab82eca74..e49f86dc3f 100644 --- a/_tour/upper-type-bounds.md +++ b/_tour/upper-type-bounds.md @@ -1,22 +1,21 @@ --- layout: tour title: Upper Type Bounds - -discourse: true - partof: scala-tour categories: tour -num: 20 +num: 22 next-page: lower-type-bounds previous-page: variances redirect_from: "/tutorials/tour/upper-type-bounds.html" --- -In Scala, [type parameters](generic-classes.html) and [abstract types](abstract-types.html) may be constrained by a type bound. Such type bounds limit the concrete values of the type variables and possibly reveal more information about the members of such types. An _upper type bound_ `T <: A` declares that type variable `T` refers to a subtype of type `A`. +In Scala, [type parameters](generic-classes.html) and [abstract type members](abstract-type-members.html) may be constrained by a type bound. Such type bounds limit the concrete values of the type variables and possibly reveal more information about the members of such types. An _upper type bound_ `T <: A` declares that type variable `T` refers to a subtype of type `A`. Here is an example that demonstrates upper type bound for a type parameter of class `PetContainer`: -```tut +{% tabs upper-type-bounds class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds %} +```scala mdoc abstract class Animal { def name: String } @@ -42,11 +41,48 @@ class PetContainer[P <: Pet](p: P) { val dogContainer = new PetContainer[Dog](new Dog) val catContainer = new PetContainer[Cat](new Cat) ``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds %} +```scala +abstract class Animal: + def name: String + +abstract class Pet extends Animal + +class Cat extends Pet: + override def name: String = "Cat" + +class Dog extends Pet: + override def name: String = "Dog" -```tut:fail -val lionContainer = new PetContainer[Lion](new Lion) // this would not compile +class Lion extends Animal: + override def name: String = "Lion" + +class PetContainer[P <: Pet](p: P): + def pet: P = p + +val dogContainer = PetContainer[Dog](Dog()) +val catContainer = PetContainer[Cat](Cat()) ``` -The `class PetContainer` take a type parameter `P` which must be a subtype of `Pet`. `Dog` and `Cat` are subtypes of `Pet` so we can create a new `PetContainer[Dog]` and `PetContainer[Cat]`. However, if we tried to create a `PetContainer[Lion]`, we would get the following Error: +{% endtab %} +{% endtabs %} + +{% tabs upper-type-bounds_error class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_error %} +```scala mdoc:fail +// this would not compile +val lionContainer = new PetContainer[Lion](new Lion) +``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_error %} +```scala +// this would not compile +val lionContainer = PetContainer[Lion](Lion()) +``` +{% endtab %} +{% endtabs %} + +The `class PetContainer` takes a type parameter `P` which must be a subtype of `Pet`. `Dog` and `Cat` are subtypes of `Pet` so we can create a new `PetContainer[Dog]` and `PetContainer[Cat]`. However, if we tried to create a `PetContainer[Lion]`, we would get the following Error: `type arguments [Lion] do not conform to class PetContainer's type parameter bounds [P <: Pet]` diff --git a/_tour/variances.md b/_tour/variances.md index e5f6187032..14f40fb893 100644 --- a/_tour/variances.md +++ b/_tour/variances.md @@ -1,154 +1,222 @@ --- layout: tour title: Variances - -discourse: true - partof: scala-tour -num: 19 +num: 21 next-page: upper-type-bounds previous-page: generic-classes redirect_from: "/tutorials/tour/variances.html" --- -Variance is the correlation of subtyping relationships of complex types and the subtyping relationships of their component types. Scala supports variance annotations of type parameters of [generic classes](generic-classes.html), to allow them to be covariant, contravariant, or invariant if no annotations are used. The use of variance in the type system allows us to make intuitive connections between complex types, whereas the lack of variance can restrict the reuse of a class abstraction. +Variance lets you control how type parameters behave with regard to subtyping. Scala supports variance annotations of type parameters of [generic classes](generic-classes.html), to allow them to be covariant, contravariant, or invariant if no annotations are used. The use of variance in the type system allows us to make intuitive connections between complex types. -```tut +{% tabs variances_1 %} +{% tab 'Scala 2 and 3' for=variances_1 %} +```scala mdoc class Foo[+A] // A covariant class class Bar[-A] // A contravariant class class Baz[A] // An invariant class ``` +{% endtab %} +{% endtabs %} -### Covariance +### Invariance + +By default, type parameters in Scala are invariant: subtyping relationships between the type parameters aren't reflected in the parameterized type. To explore why this works the way it does, we look at a simple parameterized type, the mutable box. -A type parameter `A` of a generic class can be made covariant by using the annotation `+A`. For some `class List[+A]`, making `A` covariant implies that for two types `A` and `B` where `A` is a subtype of `B`, then `List[A]` is a subtype of `List[B]`. This allows us to make very useful and intuitive subtyping relationships using generics. +{% tabs invariance_1 %} +{% tab 'Scala 2 and 3' for=invariance_1 %} +```scala mdoc +class Box[A](var content: A) +``` +{% endtab %} +{% endtabs %} -Consider this simple class structure: +We're going to be putting values of type `Animal` in it. This type is defined as follows: -```tut +{% tabs invariance_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=invariance_2 %} +```scala mdoc abstract class Animal { def name: String } case class Cat(name: String) extends Animal case class Dog(name: String) extends Animal ``` +{% endtab %} +{% tab 'Scala 3' for=invariance_2 %} +```scala +abstract class Animal: + def name: String -Both `Cat` and `Dog` are subtypes of `Animal`. The Scala standard library has a generic immutable `sealed abstract class List[+A]` class, where the type parameter `A` is covariant. This means that a `List[Cat]` is a `List[Animal]` and a `List[Dog]` is also a `List[Animal]`. Intuitively, it makes sense that a list of cats and a list of dogs are each lists of animals, and you should be able to substitute either of them for a `List[Animal]`. - -In the following example, the method `printAnimalNames` will accept a list of animals as an argument and print their names each on a new line. If `List[A]` were not covariant, the last two method calls would not compile, which would severely limit the usefulness of the `printAnimalNames` method. +case class Cat(name: String) extends Animal +case class Dog(name: String) extends Animal +``` +{% endtab %} +{% endtabs %} -```tut -object CovarianceTest extends App { - def printAnimalNames(animals: List[Animal]): Unit = { - animals.foreach { animal => - println(animal.name) - } - } +We can say that `Cat` is a subtype of `Animal`, and that `Dog` is also a subtype of `Animal`. That means that the following is well-typed: - val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom")) - val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex")) +{% tabs invariance_3 %} +{% tab 'Scala 2 and 3' for=invariance_3 %} +```scala mdoc +val myAnimal: Animal = Cat("Felix") +``` +{% endtab %} +{% endtabs %} - printAnimalNames(cats) - // Whiskers - // Tom +What about boxes? Is `Box[Cat]` a subtype of `Box[Animal]`, like `Cat` is a subtype of `Animal`? At first sight, it looks like that may be plausible, but if we try to do that, the compiler will tell us we have an error: - printAnimalNames(dogs) - // Fido - // Rex -} +{% tabs invariance_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=invariance_4 %} +```scala mdoc:fail +val myCatBox: Box[Cat] = new Box[Cat](Cat("Felix")) +val myAnimalBox: Box[Animal] = myCatBox // this doesn't compile +val myAnimal: Animal = myAnimalBox.content +``` +{% endtab %} +{% tab 'Scala 3' for=invariance_4 %} +```scala +val myCatBox: Box[Cat] = Box[Cat](Cat("Felix")) +val myAnimalBox: Box[Animal] = myCatBox // this doesn't compile +val myAnimal: Animal = myAnimalBox.content ``` +{% endtab %} +{% endtabs %} -### Contravariance +Why could this be a problem? We can get the cat from the box, and it's still an Animal, isn't it? Well, yes. But that's not all we can do. We can also replace the cat in the box with a different animal -A type parameter `A` of a generic class can be made contravariant by using the annotation `-A`. This creates a subtyping relationship between the class and its type parameter that is similar, but opposite to what we get with covariance. That is, for some `class Writer[-A]`, making `A` contravariant implies that for two types `A` and `B` where `A` is a subtype of `B`, `Writer[B]` is a subtype of `Writer[A]`. +{% tabs invariance_5 %} +{% tab 'Scala 2 and 3' for=invariance_5 %} +```scala + myAnimalBox.content = Dog("Fido") +``` +{% endtab %} +{% endtabs %} -Consider the `Cat`, `Dog`, and `Animal` classes defined above for the following example: +There now is a Dog in the Animal box. That's all fine, you can put Dogs in Animal boxes, because Dogs are Animals. But our Animal Box is a Cat Box! You can't put a Dog in a Cat box. If we could, and then try to get the cat from our Cat Box, it would turn out to be a dog, breaking type soundness. -```tut -abstract class Printer[-A] { - def print(value: A): Unit -} +{% tabs invariance_6 %} +{% tab 'Scala 2 and 3' for=invariance_6 %} +```scala + val myCat: Cat = myCatBox.content //myCat would be Fido the dog! ``` +{% endtab %} +{% endtabs %} -A `Printer[A]` is a simple class that knows how to print out some type `A`. Let's define some subclasses for specific types: +From this, we have to conclude that `Box[Cat]` and `Box[Animal]` can't have a subtyping relationship, even though `Cat` and `Animal` do. -```tut -class AnimalPrinter extends Printer[Animal] { - def print(animal: Animal): Unit = - println("The animal's name is: " + animal.name) -} +### Covariance -class CatPrinter extends Printer[Cat] { - def print(cat: Cat): Unit = - println("The cat's name is: " + cat.name) -} +The problem we ran in to above, is that because we could put a Dog in an Animal Box, a Cat Box can't be an Animal Box. + +But what if we couldn't put a Dog in the box? Then, we could just get our Cat back out without a problem, and it would adhere to the subtyping relationship. It turns out that that's possible to do. + +{% tabs covariance_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=covariance_1 %} +```scala mdoc +class ImmutableBox[+A](val content: A) +val catbox: ImmutableBox[Cat] = new ImmutableBox[Cat](Cat("Felix")) +val animalBox: ImmutableBox[Animal] = catbox // now this compiles +``` +{% endtab %} +{% tab 'Scala 3' for=covariance_1 %} +```scala +class ImmutableBox[+A](val content: A) +val catbox: ImmutableBox[Cat] = ImmutableBox[Cat](Cat("Felix")) +val animalBox: ImmutableBox[Animal] = catbox // now this compiles ``` +{% endtab %} +{% endtabs %} -If a `Printer[Cat]` knows how to print any `Cat` to the console, and a `Printer[Animal]` knows how to print any `Animal` to the console, it makes sense that a `Printer[Animal]` would also know how to print any `Cat`. The inverse relationship does not apply, because a `Printer[Cat]` does not know how to print any `Animal` to the console. Therefore, we should be able to substitute a `Printer[Animal]` for a `Printer[Cat]`, if we wish, and making `Printer[A]` contravariant allows us to do exactly that. +We say that `ImmutableBox` is *covariant* in `A`, and this is indicated by the `+` before the `A`. -```tut -object ContravarianceTest extends App { - val myCat: Cat = Cat("Boots") +More formally, that gives us the following relationship: given some `class Cov[+T]`, then if `A` is a subtype of `B`, `Cov[A]` is a subtype of `Cov[B]`. This allows us to make very useful and intuitive subtyping relationships using generics. - def printMyCat(printer: Printer[Cat]): Unit = { - printer.print(myCat) +In the following less contrived example, the method `printAnimalNames` will accept a list of animals as an argument and print their names each on a new line. If `List[A]` were not covariant, the last two method calls would not compile, which would severely limit the usefulness of the `printAnimalNames` method. + +{% tabs covariance_2 %} +{% tab 'Scala 2 and 3' for=covariance_2 %} +```scala mdoc +def printAnimalNames(animals: List[Animal]): Unit = + animals.foreach { + animal => println(animal.name) } - val catPrinter: Printer[Cat] = new CatPrinter - val animalPrinter: Printer[Animal] = new AnimalPrinter +val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom")) +val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex")) - printMyCat(catPrinter) - printMyCat(animalPrinter) -} -``` +// prints: Whiskers, Tom +printAnimalNames(cats) -The output of this program will be: - -``` -The cat's name is: Boots -The animal's name is: Boots +// prints: Fido, Rex +printAnimalNames(dogs) ``` +{% endtab %} +{% endtabs %} -### Invariance +### Contravariance -Generic classes in Scala are invariant by default. This means that they are neither covariant nor contravariant. In the context of the following example, `Container` class is invariant. A `Container[Cat]` is _not_ a `Container[Animal]`, nor is the reverse true. +We've seen we can accomplish covariance by making sure that we can't put something in the covariant type, but only get something out. What if we had the opposite, something you can put something in, but can't take out? This situation arises if we have something like a serializer, that takes values of type A, and converts them to a serialized format. -```tut -class Container[A](value: A) { - private var _value: A = value - def getValue: A = _value - def setValue(value: A): Unit = { - _value = value - } +{% tabs contravariance_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=contravariance_1 %} +```scala mdoc +abstract class Serializer[-A] { + def serialize(a: A): String +} + +val animalSerializer: Serializer[Animal] = new Serializer[Animal] { + def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }""" } +val catSerializer: Serializer[Cat] = animalSerializer +catSerializer.serialize(Cat("Felix")) ``` +{% endtab %} +{% tab 'Scala 3' for=contravariance_1 %} +```scala +abstract class Serializer[-A]: + def serialize(a: A): String -It may seem like a `Container[Cat]` should naturally also be a `Container[Animal]`, but allowing a mutable generic class to be covariant would not be safe. In this example, it is very important that `Container` is invariant. Supposing `Container` was actually covariant, something like this could happen: +val animalSerializer: Serializer[Animal] = new Serializer[Animal](): + def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }""" +val catSerializer: Serializer[Cat] = animalSerializer +catSerializer.serialize(Cat("Felix")) ``` -val catContainer: Container[Cat] = new Container(Cat("Felix")) -val animalContainer: Container[Animal] = catContainer -animalContainer.setValue(Dog("Spot")) -val cat: Cat = catContainer.getValue // Oops, we'd end up with a Dog assigned to a Cat -``` +{% endtab %} +{% endtabs %} + +We say that `Serializer` is *contravariant* in `A`, and this is indicated by the `-` before the `A`. A more general serializer is a subtype of a more specific serializer. -Fortunately, the compiler stops us long before we could get this far. +More formally, that gives us the reverse relationship: given some `class Contra[-T]`, then if `A` is a subtype of `B`, `Contra[B]` is a subtype of `Contra[A]`. -### Other Examples +### Immutability and Variance +Immutability constitutes an important part of the design decision behind using variance. For example, Scala's collections systematically distinguish between [mutable and immutable collections](https://docs.scala-lang.org/overviews/collections-2.13/overview.html). The main issue is that a covariant mutable collection can break type safety. This is why `List` is a covariant collection, while `scala.collection.mutable.ListBuffer` is an invariant collection. `List` is a collection in package `scala.collection.immutable`, therefore it is guaranteed to be immutable for everyone. Whereas, `ListBuffer` is mutable, that is, you can change, add, or remove elements of a `ListBuffer`. -Another example that can help one understand variance is `trait Function1[-T, +R]` from the Scala standard library. `Function1` represents a function with one argument, where the first type parameter `T` represents the argument type, and the second type parameter `R` represents the return type. A `Function1` is contravariant over its argument type, and covariant over its return type. For this example we'll use the literal notation `A => B` to represent a `Function1[A, B]`. +To illustrate the problem of covariance and mutability, suppose that `ListBuffer` was covariant, then the following problematic example would compile (in reality it fails to compile): -Assume the similar `Cat`, `Dog`, `Animal` inheritance tree used earlier, plus the following: +{% tabs immutability_and_variance_2 %} +{% tab 'Scala 2 and 3' %} +```scala mdoc:fail +import scala.collection.mutable.ListBuffer -```tut -abstract class SmallAnimal extends Animal -case class Mouse(name: String) extends SmallAnimal +val bufInt: ListBuffer[Int] = ListBuffer[Int](1,2,3) +val bufAny: ListBuffer[Any] = bufInt +bufAny(0) = "Hello" +val firstElem: Int = bufInt(0) ``` +{% endtab %} +{% endtabs %} -Suppose we're working with functions that accept types of animals, and return the types of food they eat. If we would like a `Cat => SmallAnimal` (because cats eat small animals), but are given a `Animal => Mouse` instead, our program will still work. Intuitively an `Animal => Mouse` will still accept a `Cat` as an argument, because a `Cat` is an `Animal`, and it returns a `Mouse`, which is also a `SmallAnimal`. Since we can safely and invisibly substitute the former for the latter, we can say `Animal => Mouse` is a subtype of `Cat => SmallAnimal`. +If the above code was possible then evaluating `firstElem` would fail with `ClassCastException`, because `bufInt(0)` now contains a `String`, not an `Int`. + +The invariance of `ListBuffer` means that `ListBuffer[Int]` is not a subtype of `ListBuffer[Any]`, despite the fact that `Int` is a subtype of `Any`, and so `bufInt` cannot be assigned as the value of `bufAny`. ### Comparison With Other Languages Variance is supported in different ways by some languages that are similar to Scala. For example, variance annotations in Scala closely resemble those in C#, where the annotations are added when a class abstraction is defined (declaration-site variance). In Java, however, variance annotations are given by clients when a class abstraction is used (use-site variance). + +Scala's tendency towards immutable types makes it that covariant and contravariant types are more common than in other languages, since a mutable generic type must be invariant. diff --git a/_uk/cheatsheets/index.md b/_uk/cheatsheets/index.md new file mode 100644 index 0000000000..24412df349 --- /dev/null +++ b/_uk/cheatsheets/index.md @@ -0,0 +1,624 @@ +--- +layout: cheatsheet +title: Scala Cheatsheet + +partof: cheatsheet + +by: Dmytro Kazanzhy +about: Ця шпаргалка створена завдяки Brendan O'Connor, та призначена для швидкого ознайомлення з синтаксичними конструкціями Scala. Ліцензовано Brendan O'Connor за ліцензією CC-BY-SA 3.0. + +language: uk +--- + +###### Contributed by {{ page.by }} + +{{ page.about }} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            змінні 
            var x = 5

            Вірно
            x = 6
            		Змінна.
            val x = 5

            Невірно
            x = 6
            		Константа (значення).
            var x: Double = 5
            		Явне вказання типу.
            функції
            Вірно
            def f(x: Int) = { x * x }

            Невірно
            def f(x: Int)   { x * x }
            		Визначення функції.
            Прихована помилка: без = це процедура, що повертає Unit та може ввести в оману. Не підтримується зі Scala 2.13.
            Вірно
            def f(x: Any) = println(x)

            Невірно
            def f(x) = println(x)
            		Визначення функції.
            Синтаксична помилка: для кожного аргументу має бути вказано тип.
            type R = Double
            		Псевдонім (синонім) типу.
            def f(x: R)
            vs.
            def f(x: => R)
            		Виклик-за-значенням.

            Виклик-за-іменем (аргумент обчислюється кожен раз як до нього звертаються).
            (x: R) => x * x
            		Анонімна функція.
            (1 to 5).map(_ * 2)
            vs.
            (1 to 5).reduceLeft(_ + _)
            		Анонімна функція: підкреслення це позиційний аргумент, тобто місце, куди буде підставлено аргумент функції.
            (1 to 5).map(x => x * x)
            		Анонімна функція: щоб використати аргумент двічі, треба його назвати. Зліва від => задається ім'я змінної, якій буде присвоєно аргумент та яку можна використати справа.
            (1 to 5).map { x =>
+  val y = x * 2
+  println(y)
+  y
+}
            		Анонімна функція: блоковий стиль (фігурні дужки означають блок) повертає останній вираз.
            (1 to 5) filter {
+  _ % 2 == 0
+} map {
+  _ * 2
+}
            		Анонімна функція: конвеєрний стиль.
            def compose(g: R => R, h: R => R) =
+  (x: R) => g(h(x))

            val f = compose(_ * 2, _ - 1)
            		Анонімна функція: для передачі кількох блоків потрібні зовнішні дужки.
            val zscore =
+  (mean: R, sd: R) =>
+    (x: R) =>
+      (x - mean) / sd
            		Каррування, явний синтакси.
            def zscore(mean: R, sd: R) =
+  (x: R) =>
+    (x - mean) / sd
            		Каррування, явний синтаксис.
            def zscore(mean: R, sd: R)(x: R) =
+  (x - mean) / sd
            		Каррування, синтаксичний цукор. Але:
            val normer =
+  zscore(7, 0.4) _
            		Потрібне кінцеве підкреслення, щоб отримати частково застосовану функцію (лише для версії з синтаксичним цукром).
            def mapmake[T](g: T => T)(seq: List[T]) =
+  seq.map(g)
            		Узагальнений тип (параметричний поліморфізм).
            5.+(3); 5 + 3

            (1 to 5) map (_ * 2)
            		Інфіксний цукор (метод з одним аргументом може бути викликано як оператор).
            def sum(args: Int*) =
+  args.reduceLeft(_+_)
            		Varargs (аргументи змінної довжини).
            пакети 
            import scala.collection._
            		Імпорт всього вмісту пакету.
            import scala.collection.Vector

            import scala.collection.{Vector, Sequence}
            		Вибірковий імпорт.
            import scala.collection.{Vector => Vec28}
            		Імпорт з перейменуванням.
            import java.util.{Date => _, _}
            		Імпорт всього з java.util окрім Date.
            На початку файлу: 
            package pkg

            Пакет в певних межах: 
            package pkg {
+  ...
+}

            Пакет одиночка (singleton): 
            package object pkg {
+  ...
+}
            		Оголошення пакету.
            структури даних 
            (1, 2, 3)
            		Кортеж (Tuple). Трансформується у виклик Tuple3.
            var (x, y, z) = (1, 2, 3)
            		Деструктивна прив'язка: кортеж розпаковується через зіставлення зі зразком (pattern matching).
            Невірно
            var x, y, z = (1, 2, 3)
            		Прихована помилка: кожна змінна прив'язана до всього кортежу.
            var xs = List(1, 2, 3)
            		Список (імутабельний, тобто такий, що не змінюється).
            xs(2)
            		Індексація через дужки (slides).
            1 :: List(2, 3)
            		Додавання елементу до голови списку.
            1 to 5
            так само, як і 
            1 until 6

            1 to 10 by 2
            		Синтаксичний цукор для діапазонів.
            ()
            		Пусті дужки це єдине значення для типу Unit.
            Еквівалентно до void у C та Java.
            управляючі конструкти 
            if (check) happy else sad
            		Умовний конструкт.
            if (check) happy
            +
            так само, як і
            + 
            if (check) happy else ()
            		Умовний конструкт (синтаксичний цукор).
            while (x < 5) {
+  println(x)
+  x += 1
+}
            		Цикл while.
            do {
+  println(x)
+  x += 1
+} while (x < 5)
            		Цикл do-while.
            import scala.util.control.Breaks._
+breakable {
+  for (x <- xs) {
+    if (Math.random < 0.1)
+      break
+  }
+}
            		Break (slides).
            for (x <- xs if x % 2 == 0)
+  yield x * 10
            +
            так само, як і
            + 
            xs.filter(_ % 2 == 0).map(_ * 10)
            		Цикл for: filter/map.
            for ((x, y) <- xs zip ys)
+  yield x * y
            +
            так само, як і
            + 
            (xs zip ys) map {
+  case (x, y) => x * y
+}
            		Цикл for: деструктивна прив'язка.
            for (x <- xs; y <- ys)
+  yield x * y
            +
            так само, як і
            + 
            xs flatMap { x =>
+  ys map { y =>
+    x * y
+  }
+}
            		Цикл for: декартів добуток.
            for (x <- xs; y <- ys) {
+  val div = x / y.toFloat
+  println("%d/%d = %.1f".format(x, y, div))
+}
            		Цикл for: імперативізм.
            стильsprintf.
            for (i <- 1 to 5) {
+  println(i)
+}
            		Цикл for: ітерація з включенням верхньої межі.
            for (i <- 1 until 5) {
+  println(i)
+}
            		Цикл for: ітерація без включення верхньої межі.
            зіставлення із зразком (pattern matching)
            Вірно
            (xs zip ys) map {
+  case (x, y) => x * y
+}

            Невірно
            (xs zip ys) map {
+  (x, y) => x * y
+}
            		Для зіставлення зі зразком необхідно використати case перед аргументами анонімної функції.
            Невірно
            + 
            val v42 = 42
+24 match {
+  case v42 => println("42")
+  case _   => println("Not 42")
+}
            		v42 буде інтерпретовано як ім'я змінної у зразку, яка буде вірно зіставлена з будь-яким Int значенням, і буде виведено “42”.
            Вірно
            + 
            val v42 = 42
+24 match {
+  case `v42` => println("42")
+  case _     => println("Not 42")
+}
            		`v42` у зворотних галочках буде інтерпретовано як значення наявної змінної v42, і буде виведено “Not 42”.
            Вірно
            + 
            val UppercaseVal = 42
+24 match {
+  case UppercaseVal => println("42")
+  case _            => println("Not 42")
+}
            		UppercaseVal буде інтерпретовано так само як наявна змінна, а не нова змінна в патерні. Тому значення, що міститься в UppercaseVal буде порівняно з 24, і буде виведено “Not 42”.
            об'єктна орієнтація 
            class C(x: R)
            		Параметри конструктора - тільки x доступний в тілі класу.
            class C(val x: R)

            var c = new C(4)

            c.x
            		Параметри конструктора - автоматичне створення публічного об'єкта.
            class C(var x: R) {
+  assert(x > 0, "positive please")
+  var y = x
+  val readonly = 5
+  private var secret = 1
+  def this = this(42)
+}
            		Тіло класу є конструктором.
            Оголосити відкритий (public) атрибут.
            Оголосити атрибут, доступний тільки на читання.
            Оголосити закритий (private) атрибут.
            Альтернативний конструктор.
            new {
+  ...
+}
            		Анонімний клас.
            abstract class D { ... }
            		Визначити абстрактний клас (без можливості створення об'єкту).
            class C extends D { ... }
            		Визначити клас, що наслідує інший.
            class D(var x: R)

            class C(x: R) extends D(x)
            		Наслідування та параметри конструктора (за замовчуванням відбувається передача аргументів).
            object O extends D { ... }
            		Визначити єдиний екземпляр (singleton).
            trait T { ... }

            class C extends T { ... }

            class C extends D with T { ... }
            		Риси - трейти (traits).
            Інтерфейси-з-імплементацією. У трейту немає параметрів конструктора. композиція з домішками (mixin).
            trait T1; trait T2

            class C extends T1 with T2

            class C extends D with T1 with T2
            		Множинні трейти.
            class C extends D { override def f = ...}
            		При реалізації вже наявного методу необхідно вказати overrides.
            new java.io.File("f")
            		Створення об'єкту.
            Невірно
            new List[Int]

            Вірно
            List(1, 2, 3)
            		Помилка типу: абстрактний тип.
            Натомість, існує конвенція у таких випадках використовувати фабричний метод обʼєкту компаньйону, що приховує конкретний тип.
            classOf[String]
            		Літерал класу (Class[String] = class java.lang.String).
            x.isInstanceOf[String]
            		Перевірка типу під час виконання (runtime).
            x.asInstanceOf[String]
            		Приведення типу під час виконання (runtime).
            x: String
            		Приписування типу під час компіляції (compile time).
            опції (options) 
            Some(42)
            		Конструктор для непустого опціонального значення (тип Some[T]).
            None
            		Одинак (Singleton) пустого опціонального значення (тип None).
            Option(null) == None
+Option(24) == Some(24)
            + 
            obj.unsafeMethod // number or null
+Option(obj.unsafeMethod) // Some or None
            + проте + 
            Some(null) != None
            		Null-safe фабрика опціональних значень.
            val optStr: Option[String] = None
            + так само, як і + 
            val optStr = Option.empty[String]
            		Явна типізація опціонального значення.
            Фабричний метод для створення пустих опціональних значень.
            val name: Option[String] =
+  request.getParameter("name")
+val upper = name.map {
+  _.trim
+} filter {
+  _.length != 0
+} map {
+  _.toUpperCase
+}
+println(upper.getOrElse(""))
            		Конвеєрний стиль.
            val upper = for {
+  name <- request.getParameter("name")
+  trimmed <- Some(name.trim)
+    if trimmed.length != 0
+  upper <- Some(trimmed.toUpperCase)
+} yield upper
+println(upper.getOrElse(""))
            		Синтаксис for-виразу.
            option.map(f(_))
            + так само, як і + 
            option match {
+  case Some(x) => Some(f(x))
+  case None    => None
+}
            		Застосування функції до опціонального значення.
            option.flatMap(f(_))
            + так само, як і + 
            option match {
+  case Some(x) => f(x)
+  case None    => None
+}
            		Так само, як і mapб але функція має повернути опціональне значення.
            optionOfOption.flatten
            + так само, як і + 
            optionOfOption match {
+  case Some(Some(x)) => Some(x)
+  case _             => None
+}
            		Вилучення вкладених опціональних значень.
            option.foreach(f(_))
            + так само, як і + 
            option match {
+  case Some(x) => f(x)
+  case None    => ()
+}
            		Застосувати процедуру на опціональному значенні.
            option.fold(y)(f(_))
            + так само, як і + 
            option match {
+  case Some(x) => f(x)
+  case None    => y
+}
            		Застосувати функцію на опціональному значенні та повернути значення, якщо воно порожнє.
            option.collect {
+  case x => ...
+}
            + так само, як і + 
            option match {
+  case Some(x) if f.isDefinedAt(x) => ...
+  case Some(_)                     => None
+  case None                        => None
+}
            		Виконати часткове зіставлення зі зразком опціонального значення.
            option.isDefined
            + так само, як і + 
            option match {
+  case Some(_) => true
+  case None    => false
+}
            		true якщо не порожнє.
            option.isEmpty
            + так само, як і + 
            option match {
+  case Some(_) => false
+  case None    => true
+}
            		true якщо порожнє.
            option.nonEmpty
            + так само, як і + 
            option match {
+  case Some(_) => true
+  case None    => false
+}
            		true якщо не порожнє.
            option.size
            + так само, як і + 
            option match {
+  case Some(_) => 1
+  case None    => 0
+}
            		0 якщо порожнє, інакше 1.
            option.orElse(Some(y))
            + так само, як і + 
            option match {
+  case Some(x) => Some(x)
+  case None    => Some(y)
+}
            		Обчислити та повернути альтернативне опціональне значення, якщо порожнє.
            option.getOrElse(y)
            + так само, як і + 
            option match {
+  case Some(x) => x
+  case None    => y
+}
            		Обчислити та повернути значення за замовчуванням, якщо порожнє.
            option.get
            + так само, як і + 
            option match {
+  case Some(x) => x
+  case None    => throw new Exception
+}
            		Повернути значення, або згенерувати виключення, якщо порожнє.
            option.orNull
            + так само, як і + 
            option match {
+  case Some(x) => x
+  case None    => null
+}
            		Повернути значення, null якщо порожнє.
            option.filter(f)
            + так само, як і + 
            option match {
+  case Some(x) if f(x) => Some(x)
+  case _               => None
+}
            		Фільтрація опціонального значення. Повернути значення, якщо предикат істинний.
            option.filterNot(f(_))
            + так само, як і + 
            option match {
+  case Some(x) if !f(x) => Some(x)
+  case _                => None
+}
            		Фільтрація опціонального значення. Повернути значення, якщо предикат хибний.
            option.exists(f(_))
            + так само, як і + 
            option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => false
+}
            		Повернути значення предикату на опціональному значенні або false якщо порожнє.
            option.forall(f(_))
            + так само, як і + 
            option match {
+  case Some(x) if f(x) => true
+  case Some(_)         => false
+  case None            => true
+}
            		Повернути значення предикату на опціональному значенні або true якщо порожнє..
            option.contains(y)
            + так само, як і + 
            option match {
+  case Some(x) => x == y
+  case None    => false
+}
            		Перевіряє чи дорівнює опціональне значення параметру, false якщо порожнє.
            diff --git a/_uk/getting-started/install-scala.md b/_uk/getting-started/install-scala.md new file mode 100644 index 0000000000..d8ae3efbd9 --- /dev/null +++ b/_uk/getting-started/install-scala.md @@ -0,0 +1,221 @@ +--- +layout: singlepage-overview +title: Перші кроки +partof: getting-started +language: uk +includeTOC: true +redirect_from: + - /uk/scala3/getting-started.html # we deleted the scala 3 version of this page +--- + +Інструкції нижче стосуються як Scala 2 так, і та Scala 3. + +## Спробуйте Scala без інсталяції + +Щоб швидко почати експериментувати зі Scala, відкрийте “Scastie” у вашому браузері. +_Scastie_ це онлайн “пісочниця”, де ви можете експериментувати з прикладами на Scala та подивитись як все працює, з доступом до всіх компіляторів Scala та доступних бібліотек. + +> Scastie підтримує як Scala 2 так, і Scala 3, але за замовчування +> використовується Scala 3. Якщо ж ви шукаєте приклади на Scala 2, +> [натисніть тут](https://scastie.scala-lang.org/MHc7C9iiTbGfeSAvg8CKAA). + +## Встановіть Scala на ваш комп'ютер + +Інсталяція Scala означає встановлення різних command-line інструментів, таких як компілятор Scala та інструменти для збірки. +Ми радимо використовувати інсталятор "Coursier", який автоматично встановить всі необхідні залежності, але ви можете встановити окремо кожен інструмент. + +### За допомогою інсталятора Scala (рекомендовано) + +Інсталятор Scala називається [Coursier](https://get-coursier.io/docs/cli-overview), а його основна команда має назву `cs`. +Він гарантує, що JVM та стандартні інструменти Scala встановлені на вашій системі. +Щоб встановити його на вашій системі виконайте наступні інструкції. + + +{% tabs install-cs-setup-tabs class=platform-os-options %} + + +{% tab macOS for=install-cs-setup-tabs %} +Виконайте наступну команду в терміналі, виконуючи всі спливаючі інструкції: +{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-brew %} +{% altDetails cs-setup-macos-nobrew "Якщо ви не використовуєте Homebrew:" %} +{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-x86-64 %} +{% endaltDetails %} +{% endtab %} + + + +{% tab Linux for=install-cs-setup-tabs %} +Виконайте наступну команду в терміналі, виконуючи всі спливаючі інструкції: +{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.linux-x86-64 %} +{% endtab %} + + + +{% tab Windows for=install-cs-setup-tabs %} +Завантажте та запустіть [the Scala installer for Windows]({{site.data.setup-scala.windows-link}}) +інсталятор на основі Coursier, виконуючи всі спливаючі інструкції. +{% endtab %} + + + +{% tab Other for=install-cs-setup-tabs defaultTab %} + +Дотримуйтесь документації від Coursier з того, +[як встановити і запустити `cs setup`](https://get-coursier.io/docs/cli-installation). +{% endtab %} + + +{% endtabs %} + + + +{% altDetails testing-your-setup 'Перевірити налаштування' %} +Перевірте ваші налаштування виконавши команду `scala -version`, яка має вивести: +```bash +$ scala -version +Scala code runner version: 1.4.3 +Scala version (default): {{site.scala-3-version}} +``` +Якщо це не спрацювало, необхідно завершити сеанс та зайти в систему знову (або перезавантажити), щоб зміни застосувались на вашій системі. +{% endaltDetails %} + + + +Разом з менеджментом JVM-ів, `cs setup` також встановлює корисні command-line інструменти: + +| Команда | Опис | +|---------------|----------------------------------------------------------------------------------------| +| `scalac` | компілятор Scala | +| `scala` | інтерактивне середовище Scala та інструмент для запуску скриптів | +| `scala-cli` | [Scala CLI](https://scala-cli.virtuslab.org), інтерактивні інструменти для Scala | +| `sbt`, `sbtn` | Інструмент збірки [sbt](https://www.scala-sbt.org/) | +| `amm` | [Ammonite](https://ammonite.io/) розширене інтерактивне середовище (REPL) | +| `scalafmt` | [Scalafmt](https://scalameta.org/scalafmt/) призначений для форматування коду на Scala | + +Для більш детальної інформації про `cs`, прочитайте +[документацію coursier-cli](https://get-coursier.io/docs/cli-overview). + +> `cs setup` встановлює компілятор Scala 3 та інтерактивне середовище за замовчування (команди `scalac` та +> `scala` відповідно). Незалежно від того, чи збираєтеся ви використовувати Scala 2 чи 3, +> тому що більшість проєктів використовує інструменти для збірки, +> які використовують правильні версії Scala незалежно від того, яка встановлена "глобально". +> Однак, ви завжди можете запустити певну версію Scala за допомогою +> ``` +> $ cs launch scala:{{ site.scala-version }} +> $ cs launch scalac:{{ site.scala-version }} +> ``` +> Якщо ви надаєте перевагу Scala 2 за замовчуванням, ви можете примусово встановити певну версію: +> ``` +> $ cs install scala:{{ site.scala-version }} scalac:{{ site.scala-version }} +> ``` + +### ...або вручну + +Вам необхідно лише два інструменти, для того, щоб скомпілювати, запустити, протестувати й упакувати Scala проєкт: Java 8 або 11, і sbt. +Щоб встановити їх вручну: + +1. Якщо Java 8 або 11 не встановлені, необхідно завантажити + Java з [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html), + або [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Перевірте [сумісність JDK](/overviews/jdk-compatibility/overview.html) для Scala/Java. +1. Встановіть [sbt](https://www.scala-sbt.org/download.html) + +## Створити проєкт "Hello World" з sbt + +Після встановлення sbt ви готові до створення проєкту на Scala, який ми розглянемо в подальших розділах. + +Щоб створити проєкт, ви можете використати або термінал, або IDE. +Якщо ви знайомі з командним рядком, ми рекомендуємо такий підхід. + +### За допомогою командного рядка + +Інструмент sbt призначений для збірки проєкту на Scala. sbt компілює, запускає, +та тестує ваш код на Scala. (Також він публікує бібліотеки та виконує багато інших задач.) + +Щоб створити новий Scala проєкт за допомогою sbt: + +1. Перейдіть (`cd`) в пусту директорію. +1. Виконайте команду `sbt new scala/scala3.g8`, щоб створити проєкт на Scala 3, або `sbt new scala/hello-world.g8`, щоб створити проєкт на Scala 2. + Команда завантажує шаблон проєкту з GitHub. + Також, створює директорію `target`, яку ви можете проігнорувати. +1. Коли буде запропоновано, оберіть назву програми `hello-world`. В результаті буде створено проєкт "hello-world". +1. Подивимося, що щойно було створено: + +``` +- hello-world + - project (sbt uses this for its own files) + - build.properties + - build.sbt (sbt's build definition file) + - src + - main + - scala (весь ваш код на Scala буде тут) + - Main.scala (Точка входу в програму) <-- це все, що потрібно наразі +``` + +Більше документації про sbt можна знайти у [Книзі по Scala](/scala3/book/tools-sbt.html) (див. [тут](/overviews/scala-book/scala-build-tool-sbt.html) версію для Scala 2) +та в офіційній [документації](https://www.scala-sbt.org/1.x/docs/index.html) sbt + +### За допомогою IDE + +Ви можете пропустити подальші кроки та перейти до [Створення Scala проєкту з IntelliJ і sbt](/uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html) + + +## Відкрити проєкт hello-world + +Використаймо IDE, щоб відкрити проєкт. Найбільш популярними є IntelliJ та VSCode. +Обидва з них мають багатий функціонал, але ви також можете використати [багато інших редакторів.](https://scalameta.org/metals/docs/editors/overview.html) + +### За допомогою IntelliJ + +1. Завантажте та встановіть [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/) +1. Встановіть плагін Scala дотримуючись [інструкції з встановлення плагінів в IntelliJ](https://www.jetbrains.com/help/idea/managing-plugins.html) +1. Відкрийте файл `build.sbt` та оберіть *Відкрити як проєкт* (*Open as a project*) + +### За допомогою VSCode та metals + +1. Завантажте [VSCode](https://code.visualstudio.com/Download) +1. Встановіть розширення Metals з [the Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals) +1. Відкрийте директорію, що містить файл `build.sbt` (це має бути директорія `hello-world` якщо ви виконали попередні інструкції). Коли буде запропоновано, оберіть *Імпортувати збірку* (*Import build*). + +>[Metals](https://scalameta.org/metals) це “Сервер мови Scala” який забезпечує можливість написання коду на Scala в VS Code та інших редакторах на кшталт [Atom, Sublime Text, and more](https://scalameta.org/metals/docs/editors/overview.html), використовуючи Language Server Protocol. +> +> Під капотом, Metals комунікує з інструментом збірки використовуючи +> [Build Server Protocol (BSP)](https://build-server-protocol.github.io/). Більш детально про те, як працює Metals, можна подивитись на [“Write Scala in VS Code, Vim, Emacs, Atom and Sublime Text with Metals”](https://www.scala-lang.org/2019/04/16/metals.html). + +### Внесення змін в початковий код + +Перегляньте ці два файли у вашому IDE: + +- _build.sbt_ +- _src/main/scala/Main.scala_ + +Коли ви будете запускати ваш проєкт у наступному кроці, то будуть використані конфігурації з _build.sbt_ для запуску коду в _src/main/scala/Main.scala_. + +## Запустити Hello World + +Якщо вам зручно користуватися IDE, ви можете запустити код в _Main.scala_ з вашого IDE. + +В іншому випадку ви можете запустити програму через термінал, виконавши такі дії: + +1. `cd` в `hello-world`. +1. Запустіть `sbt`. Це відкриє консоль sbt. +1. Наберіть `~run`. Символ `~` опціональний і змушує sbt повторно запускатися після кожного збереження файлу, + що забезпечує швидкий цикл редагування/запуск/налагодження. sbt також створить директорію `target`, яку ви можете проігнорувати. + +Коли ви закінчите експериментувати з вашим проєктом, натисніть `[Enter]` щоб перервати команду `run`. +Потім наберіть `exit` або затисніть `[Ctrl+D]` щоб вийти з sbt та повернутись до вашого командного рядка. + +## Наступні кроки + +Після того, як ви закінчите наведені вище посібники, спробуйте пройти: + +* [Книга по Scala](/scala3/book/introduction.html) (версія по Scala 2 [тут](/overviews/scala-book/introduction.html)), яка містить коротких ознайомчих уроків з основних можливостей Scala. +* [Тур по Scala](/tour/tour-of-scala.html) for bite-sized introductions to Scala's features. +* [Навчальні ресурси](/online-courses.html), що містять інтерактивні онлайн путівники та курси. +* [Наш список деяких популярних книжок по Scala](/books.html). +* [Посібник з міграції](/scala3/guides/migration/compatibility-intro.html) допомагає перевести ваш наявний проєкт зі Scala 2 на Scala 3. + +## Отримати допомогу +Існує безліч поштових розсилок та чатів в режимі реального часу, якщо ви захочете зв'язатися з іншими користувачами Scala. Перейдіть на сторінку нашої [спільноти](https://scala-lang.org/community/), щоб побачити перелік можливих способів та попросити про допомогу. + diff --git a/_uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md b/_uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md new file mode 100644 index 0000000000..9a9d303f47 --- /dev/null +++ b/_uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md @@ -0,0 +1,100 @@ +--- +title: Створення проєкту на Scala з IntelliJ і sbt +layout: singlepage-overview +partof: building-a-scala-project-with-intellij-and-sbt +language: uk +disqus: true +previous-page: /uk/getting-started/intellij-track/getting-started-with-scala-in-intellij +next-page: /uk/testing-scala-in-intellij-with-scalatest +--- + +В цьому посібнику ми побачимо як будувати Scala проєкти використовуючи [sbt](https://www.scala-sbt.org/1.x/docs/index.html). +sbt — популярний інструмент для компіляції, запуску та тестування проєктів Scala будь-якої складності. +Використання інструменту збірки, такого як sbt (або Maven/Gradle), стає необхідним, коли ви створюєте проєкти із залежностями або кількома файлами коду. +Ми припускаємо, що ви завершили [перший посібник](./getting-started-with-scala-in-intellij.html). + +## Створення проєкту +У цьому розділі ми покажемо вам, як створити проєкт в IntelliJ. Однак, якщо вам +комфортніше працювати у терміналі, ми рекомендуємо подивитись [початок роботи зі Scala і sbt у командному рядку](/uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html) +і потім повернутися сюди до розділу «Написання коду на Scala». + +1. Якщо ви ще не створили проєкт у терміналі, запустіть IntelliJ та оберіть "Створити новий проєкт (Create New Project)" + * На панелі зліва оберіть Scala, а на панелі справа оберіть sbt + * Натисніть **Next** + * Назвіть ваш проєкт "SbtExampleProject" +1. Якщо ви вже створили проєкт через термінал, запустіть IntelliJ, оберіть *Імпортувати проєкт (Import Project)* та відкрийте файл `build.sbt` вашого проєкту +1. Впевніться, що **версія JDK** 1.8 або вище, та **версія sbt** 0.13.13 та вище +1. Натисніть **Use auto-import**, щоб залежності автоматично завантажились +1. Натисніть **Finish** + +## Розуміння структури директорій +Завдяки sbt створюються директорії, які можуть бути корисні у разі розробки складніших проєктів. +Поки що ви можете проігнорувати більшість із них, але ось для чого це все: + +``` +- .idea (IntelliJ files) +- project (plugins and additional settings for sbt) +- src (source files) + - main (application code) + - java (Java source files) + - scala (Scala source files) <-- This is all we need for now + - scala-2.12 (Scala 2.12 specific files) + - test (unit tests) +- target (generated files) +- build.sbt (build definition file for sbt) +``` + + +## Написання коду на Scala +1. На панелі **Project** зліва розкрийте `SbtExampleProject` => `src` => `main` +1. Натисніть праву кнопку миші, `scala` та оберіть **New** => **Package** +1. Назвіть пакет `example` та натисніть **OK** (або просто натисніть клавішу Enter або Return). +1. Натисніть праву кнопку миші на пакет `example` та оберіть **New** => **Scala class** (якщо ви не бачите цю опцію, натисніть праву кнопку миші на `SbtExampleProject`, натисніть **Add Frameworks Support**, оберіть **Scala** та продовжить) +1. Назвіть клас `Main` та змініть **Kind** на `Object`. +1. Змініть код у класі на наступний: + +``` +@main def run() = + val ages = Seq(42, 75, 29, 64) + println(s"The oldest person is ${ages.max}") +``` + +Примітка: IntelliJ має власну реалізацію компілятора Scala, тому іноді ваш код є правильним, навіть якщо IntelliJ вказує інше. +Ви завжди можете перевірити у командному рядку, чи може sbt запустити ваш проєкт. + +## Запуск проєкту +1. З меню **Run** оберіть **Edit configurations** +1. Натисніть кнопку **+** та оберіть **sbt Task**. +1. Назвіть його `Run the program`. +1. В полі **Tasks** наберіть `~run`. Опція `~` змушує sbt перебудовувати та перезапускати проєкт, коли ви зберігаєте зміни у файлі проєкту. +1. Натисніть **OK**. +1. В меню **Run** натисніть **Run 'Run the program'**. +1. В коді змініть `75` на `61` та подивіться оновлений результат в консолі. + +## Додавання залежностей +Давайте ненадовго змістимо фокус на використання опублікованих бібліотек для забезпечення додаткової функціональності ваших програм. +1. Відкрийте `build.sbt` та додайте наступний рядок: + +``` +libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2" +``` + +Тут `libraryDependencies` є набором залежностей та використовуючи `+=`, +ми додаємо залежність [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) до набору залежностей, +які необхідні для sbt та які завантажаться при його запуску. Тепер в будь-якому Scala файлі ви можете використати +класи, об'єкти тощо з scala-parser-combinators через звичайний "import". + +Більше опублікованих бібліотек можна знайти на +[Scaladex](https://index.scala-lang.org/) - індекс бібліотек Scala, місце куди ви можете зайти, щоб скопіювати інформацію про бібліотеку +та додати у ваш `build.sbt` файл. + +## Наступні кроки + +Перейдіть до наступного навчального матеріалу з серії _початок роботи з IntelliJ_, та дізнайтесь про [тестування Scala в IntelliJ зі ScalaTest](testing-scala-in-intellij-with-scalatest.html). + +**або** + +* [Книга по Scala](/scala3/book/introduction.html), що є набором коротких вступних уроків з основних особливостей. +* [Тур по Scala](/tour/tour-of-scala.html) серія коротких оглядових статей про можливості Scala. +* Продовжить вчити Scala інтерактивно виконуючи + [вправи зі Scala](https://www.scala-exercises.org/scala_tutorial). \ No newline at end of file diff --git a/_uk/getting-started/intellij-track/getting-started-with-scala-in-intellij.md b/_uk/getting-started/intellij-track/getting-started-with-scala-in-intellij.md new file mode 100644 index 0000000000..2d44b3ef34 --- /dev/null +++ b/_uk/getting-started/intellij-track/getting-started-with-scala-in-intellij.md @@ -0,0 +1,77 @@ +--- +title: Перші кроки зі Scala в IntelliJ +layout: singlepage-overview +partof: getting-started-with-scala-in-intellij +language: uk +disqus: true +next-page: /uk/building-a-scala-project-with-intellij-and-sbt +--- + +У цьому посібнику буде розглянемо як створити мінімальний проєкт Scala за допомогою IntelliJ IDE з плагіном Scala. +У цьому посібнику IntelliJ завантажить для вас Scala. + +## Встановлення +1. Впевніться, що ви вже встановили Java 8 JDK (також відому як 1.8) + * Запустіть `javac -version` у командному рядку і впевніться, що бачите + `javac 1.8.___` + * Якщо у вас не встановлена версія 1.8 або вище, [встановіть JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) +1. Далі, завантажте та встановіть [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/) +1. Після того, як ви запустили IntelliJ, ви можете завантажити й встановити плагін Scala за інструкцією + [як встановлювати плагіни IntelliJ](https://www.jetbrains.com/help/idea/installing-updating-and-uninstalling-repository-plugins.html) (шукайте "Scala" в меню плагінів.) + +Під час створення проєкту встановиться остання версія Scala. +Примітка: якщо ви хочете відкрити наявний проєкт Scala, ви можете натиснути **Open** під час запуску IntelliJ. + +## Створення проєкту +1. Запустіть IntelliJ та натисніть **File** => **New** => **Project** +1. На панелі зліва оберіть Scala, а на панелі справа - IDEA. +1. Назвіть проєкт **HelloWorld** +1. Припускаємо, що ви вперше створюєте проєкт Scala за допомогою IntelliJ, + вам потрібно буде встановити Scala SDK. В полі праворуч від Scala SDK натисніть **Create**. +1. Оберіть останню версію (наприклад, {{ site.scala-version }}) та натисніть **Download**. Це може зайняти декілька хвилин, але наступні проєкти зможуть використати той же SDK. +1. Після того як створена SDK та ви повернулись до вікна "New Project", натисніть **Finish**. + + +## Написання коду + +1. Зліва, на панелі **Project** клацніть кнопкою миші на `src` та оберіть **New** => **Scala class**. + Якщо ви не бачите **Scala class**, клацніть правою кнопкою миші на **HelloWorld** та оберіть **Add Framework Support...**, натисніть **Scala** та продовжить. + Якщо ви бачите **Error: library is not specified**, ви можете або натиснути на кнопку завантаження або обрати шлях бібліотеки вручну. + Якщо ви бачите тільки **Scala Worksheet** спробуйте розкрити директорію `src` та піддиректорію `main` та клацніть правою кнопкою миші на теку `scala`. +1. Назвіть клас `Hello` та змініть його **Kind** на `object`. +1. Змініть код класу на наступний: + +``` +object Hello extends App { + println("Hello, World!") +} +``` + +## Запуск +* Клацніть правою кнопкою миші `Hello` та оберіть **Run 'Hello'**. +* Готово! + +## Експерименти зі Scala +Хорошим способом випробувати код є Scala Worksheets + +1. Зліва, на панелі проєкту, клацніть правою кнопкою миші на `src` та оберіть **New** => **Scala Worksheet**. +2. Назвіть робочий лист Scala "Mathematician". +3. Впишіть наступний код в робочий лист: + +``` +def square(x: Int) = x * x + +square(2) +``` + +Коли ви змінюєте свій код, ви побачите, як він виконується на панелі справа. +Якщо ви не бачите правої панелі, клацніть правою кнопкою миші на робочому аркуші Scala на панелі проєкту та натисніть Evaluate Worksheet. + + +## Наступні кроки + +Тепер ви знаєте, як створити простий проєкт Scala, який можна використовувати, +щоб почати вивчати мову. У наступному уроці ми познайомимося з важливим інструментом збірки під назвою sbt, +який можна використовувати як для простих проєктів, так і продакшн програм. + +Наступне: [Створення проєкту на Scala з IntelliJ і sbt](building-a-scala-project-with-intellij-and-sbt.html) diff --git a/_uk/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md b/_uk/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md new file mode 100644 index 0000000000..b2e1a9f801 --- /dev/null +++ b/_uk/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md @@ -0,0 +1,70 @@ +--- +title: Тестування Scala в IntelliJ зі ScalaTest +layout: singlepage-overview +partof: testing-scala-in-intellij-with-scalatest +language: uk +disqus: true +previous-page: /uk/building-a-scala-project-with-intellij-and-sbt +--- + +Існує кілька бібліотек і методологій тестування для Scala, +але в цьому посібнику ми продемонструємо один популярний варіант для фреймворку ScalaTest, +що називається [FunSuite](https://www.scalatest.org/getting_started_with_fun_suite). + +Ми припускаємо, що ви знаєте [як створити проєкт з IntelliJ](building-a-scala-project-with-intellij-and-sbt.html). + +## Налаштування +1. Створіть sbt проєкт в IntelliJ. +1. Додайте залежність ScalaTest: + 1. Додайте залежність ScalaTest у файл `build.sbt` вашого проєкту: + ``` + libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test + ``` + 1. Ви побачите сповіщення "build.sbt was changed", оберіть **auto-import**. + 1. Ці дві дії призведуть до того, що `sbt` завантажить бібліотеку ScalaTest. + 1. Зачекайте завершення синхронізації `sbt`; інакше `AnyFunSuite` та `test()` не розпізнаються. +1. На панелі проєкту розкрийте `src` => `main`. +1. Клацніть правою кнопкою миші на `scala` та оберіть **New** => **Scala class**. +1. Назвіть його `CubeCalculator` та змініть **Kind** на `object` та натисніть Enter або двічі клацніть на `object`. +1. Замініть код на наступний: + ``` + object CubeCalculator: + def cube(x: Int) = + x * x * x + ``` + +## Створення тесту +1. Зліва на панелі проєкту розкрийте `src` => `test`. +1. Клацніть правою кнопкою миші на `scala` та оберіть **New** => **Scala class**. +1. Назвіть клас `CubeCalculatorTest` та натисніть Enter або двічі клацніть на `class`. +1. Замініть код на наступний: + ``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite: + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } + ``` +1. У початковому коді клацніть правою кнопкою миші на `CubeCalculatorTest` та оберіть **Run 'CubeCalculatorTest'**. + +## Розуміння коду + +Переглянемо кожний рядок окремо. + +* `class CubeCalculatorTest` означає, що ми тестуємо об'єкт `CubeCalculator` +* `extends AnyFunSuite` використовуємо функціональність класу AnyFunSuite з ScalaTest, насамперед функцію `test` +* `test` функція з AnyFunSuite, що збирає результати тверджень (assertions) у тілі функції. +* `"CubeCalculator.cube"` назва тесту. Ви можете обрати будь-яку назву, але існує домовленість називати "ClassName.methodName". +* `assert` приймає булеву умову і визначає, пройшов тест чи не пройшов. +* `CubeCalculator.cube(3) === 27` перевіряє чи дорівнює результат функції `cube` значенню 27. + Оператор `===` є частиною ScalaTest та надає чисті повідомлення про помилки. + +## Додати інший тест-кейс +1. Додайте інший тестовий блок з власним `assert`, що перевіряє значення куба `0`. +1. Виконайте `sbt test` знову, двічі клацнувши правою кнопкою миші на `CubeCalculatorTest` та обравши 'Run **CubeCalculatorTest**'. + +## Висновок +Ви побачили один шлях тестування вашого Scala коду. Більше про +FunSuite ScalaTest на [офіційному вебсайті](https://www.scalatest.org/getting_started_with_fun_suite). +Ви можете проглянути інші фреймворки для тестування такі як [ScalaCheck](https://www.scalacheck.org/) та [Specs2](https://etorreborre.github.io/specs2/). diff --git a/_uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md b/_uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md new file mode 100644 index 0000000000..58adf6baf9 --- /dev/null +++ b/_uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md @@ -0,0 +1,84 @@ +--- +title: Початок роботи зі Scala і sbt у командному рядку +layout: singlepage-overview +partof: getting-started-with-scala-and-sbt-on-the-command-line +language: uk +disqus: true +next-page: /uk/testing-scala-with-sbt-on-the-command-line +--- + +У цьому посібнику ви дізнаєтесь, як створити проєкт Scala шаблон. +Ви можете використовувати це як відправну точку для власного проєкту. +Ми використаємо [sbt](https://www.scala-sbt.org/1.x/docs/index.html), що де-факто є основним інструментом збірки для Scala. +sbt компілює, запускає, та тестує ваші проєкти поміж інших корисних задач. +Ми припускаємо, що ви знаєте, як користуватися терміналом. + +## Встановлення +1. Впевніться, що ви вже встановили Java 8 JDK (також відому як 1.8) + * Запустіть `javac -version` у командному рядку і впевніться, що бачите + `javac 1.8.___` + * Якщо у вас не встановлена версія 1.8 або вище, [встановіть JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) +1. Встановіть sbt + * [Mac](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html) + * [Windows](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html) + * [Linux](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html) + +## Створити проєкт +1. Перейдіть (`cd`) у пусту директорію. +1. Виконайте наступну команду `sbt new scala/hello-world.g8`. +Це завантажує шаблон 'hello-world' з GitHub. +Також буде створена директорія `target`, яку можна ігнорувати. +1. Коли буде запропоновано, назвіть застосунок `hello-world`. Це створить проєкт з назвою "hello-world". +1. А тепер подивимось що було згенеровано: + +``` +- hello-world + - project (sbt uses this to install and manage plugins and dependencies) + - build.properties + - src + - main + - scala (All of your scala code goes here) + - Main.scala (Entry point of program) <-- this is all we need for now + - build.sbt (sbt's build definition file) +``` + +Після збірки вашого проєкту, sbt створить більше `target` директорій для згенерованих файлів. + +## Запуск проєкту +1. Перейдіть (`cd`) у `hello-world`. +1. Виконайте `sbt`. Це запустить sbt консоль. +1. Наберіть `~run`. Символ `~` є опціональним та означає перебудову при кожному збереженні файлу, + що дає можливість пришвидшити цикл редагування/запуск/відлагодження. + +## Модифікація коду +1. Відкрийте файл `src/main/scala/Main.scala` у вашому текстовому редакторі. +1. Змініть "Hello, World!" на "Hello, New York!" +1. Якщо ви не зупинили роботу sbt, ви побачите як на консолі з'явиться "Hello, New York!". +1. Ви можете продовжити робити зміни та бачити результати на консолі. + +## Додання залежностей +Давайте ненадовго змістимо фокус на використання опублікованих бібліотек для забезпечення додаткової функціональності ваших програм. + +1. Відкрийте `build.sbt` та додайте наступний рядок: + +``` +libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2" +``` + +Тут `libraryDependencies` є набором залежностей та використовуючи `+=`, +ми додаємо залежність [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) до набору залежностей, +які необхідні для sbt та які завантажаться при його запуску. Тепер в будь-якому Scala файлі ви можете використати +класи, об'єкти тощо з scala-parser-combinators через звичайний "import". + +Більше опублікованих бібліотек можна знайти на +[Scaladex](https://index.scala-lang.org/) - індекс бібліотек Scala, місце куди ви можете зайти, щоб скопіювати інформацію про бібліотеку +та додати у ваш `build.sbt` файл. + +## Наступні кроки + +Перейдіть до наступного посібника з серії _початок роботи з sbt_, та дізнайтесь про [тестування Scala з sbt та ScalaTest в командному рядку](testing-scala-with-sbt-on-the-command-line.html). + +**або** + +- Продовжить вивчати Scala інтерактивно нам [Вправи зі Scala](https://www.scala-exercises.org/scala_tutorial). +- Дізнайтеся про можливості Scala у коротких статтях, переглянувши наш [Тур по Scala]({{ site.baseurl }}/tour/tour-of-scala.html). diff --git a/_uk/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md b/_uk/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md new file mode 100644 index 0000000000..fc0a6e62ac --- /dev/null +++ b/_uk/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md @@ -0,0 +1,104 @@ +--- +title: Тестування Scala з sbt та ScalaTest в командному рядку +layout: singlepage-overview +partof: testing-scala-with-sbt-on-the-command-line +language: uk +disqus: true +previous-page: /uk/getting-started-with-scala-and-sbt-on-the-command-line +--- + +Існує кілька бібліотек і методологій тестування для Scala, +але в цьому посібнику ми продемонструємо один популярний варіант для фреймворку ScalaTest, +що називається [AnyFunSuite](https://www.scalatest.org/scaladoc/3.2.2/org/scalatest/funsuite/AnyFunSuite.html). + +Ми припускаємо, що ви знаєте [як створити проєкт Scala за допомогою sbt](getting-started-with-scala-and-sbt-on-the-command-line.html). + +## Налаштування +1. Створіть десь новий каталог через командний рядок. +1. Перейдіть (`cd`) в директорію та запустіть `sbt new scala/scalatest-example.g8` +1. Назвіть проєкт `ScalaTestTutorial`. +1. Проєкт вже має ScalaTest як залежність у файлі `build.sbt`. +1. Перейдіть (`cd`) в директорію та запустіть `sbt test`. Це запустить тестове середовище `CubeCalculatorTest` з єдиним тестом `CubeCalculator.cube`. + +``` +sbt test +[info] Loading global plugins from /Users/username/.sbt/0.13/plugins +[info] Loading project definition from /Users/username/workspace/sandbox/my-something-project/project +[info] Set current project to scalatest-example (in build file:/Users/username/workspace/sandbox/my-something-project/) +[info] CubeCalculatorTest: +[info] - CubeCalculator.cube +[info] Run completed in 267 milliseconds. +[info] Total number of tests run: 1 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0 +[info] All tests passed. +[success] Total time: 1 s, completed Feb 2, 2017 7:37:31 PM +``` + +## Розуміння тестів +1. Відкрийте два файли в текстовому редакторі: + * `src/main/scala/CubeCalculator.scala` + * `src/test/scala/CubeCalculatorTest.scala` +1. У файлі `CubeCalculator.scala`, визначте функцію `cube`. +1. У файлі `CubeCalculatorTest.scala`, ви побачите, що клас, що названий так само як і об'єкт, що ми тестуємо. + +``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite { + test("CubeCalculator.cube") { + assert(CubeCalculator.cube(3) === 27) + } + } +``` + +Переглянемо кожний рядок окремо. + +* `class CubeCalculatorTest` означає, що ми тестуємо об'єкт `CubeCalculator` +* `extends AnyFunSuite` використовуємо функціональність класу AnyFunSuite з ScalaTest, насамперед функцію `test` +* `test` функція з AnyFunSuite, що збирає результати тверджень (assertions) у тілі функції. +* `"CubeCalculator.cube"` назва тесту. Ви можете обрати будь-яку назву, але існує домовленість називати "ClassName.methodName". +* `assert` приймає булеву умову і визначає, пройшов тест чи не пройшов. +* `CubeCalculator.cube(3) === 27` перевіряє чи дорівнює результат функції `cube` значенню 27. + Оператор `===` є частиною ScalaTest та надає чисті повідомлення про помилки. + +## Додати інший тест-кейс +1. Додайте інший тестовий блок з власним `assert`, що перевіряє значення куба '0'. + + ``` + import org.scalatest.funsuite.AnyFunSuite + + class CubeCalculatorTest extends AnyFunSuite { + test("CubeCalculator.cube 3 should be 27") { + assert(CubeCalculator.cube(3) === 27) + } + + test("CubeCalculator.cube 0 should be 0") { + assert(CubeCalculator.cube(0) === 0) + } + } + ``` + +1. Виконайте `sbt test` знову, щоб побачити результати. + + ``` + sbt test + [info] Loading project definition from C:\projects\scalaPlayground\scalatestpractice\project + [info] Loading settings for project root from build.sbt ... + [info] Set current project to scalatest-example (in build file:/C:/projects/scalaPlayground/scalatestpractice/) + [info] Compiling 1 Scala source to C:\projects\scalaPlayground\scalatestpractice\target\scala-2.13\test-classes ... + [info] CubeCalculatorTest: + [info] - CubeCalculator.cube 3 should be 27 + [info] - CubeCalculator.cube 0 should be 0 + [info] Run completed in 257 milliseconds. + [info] Total number of tests run: 2 + [info] Suites: completed 1, aborted 0 + [info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 0 + [info] All tests passed. + [success] Total time: 3 s, completed Dec 4, 2019 10:34:04 PM + ``` + +## Висновок +Ви побачили один шлях тестування вашого Scala коду. Більше про +FunSuite ScalaTest на [офіційному вебсайті](https://www.scalatest.org/getting_started_with_fun_suite). +Ви можете проглянути інші фреймворки для тестування такі як [ScalaCheck](https://www.scalacheck.org/) та [Specs2](https://etorreborre.github.io/specs2/). diff --git a/_uk/index.md b/_uk/index.md new file mode 100644 index 0000000000..6242b6e807 --- /dev/null +++ b/_uk/index.md @@ -0,0 +1,105 @@ +--- +layout: landing-page +title: Документація +language: uk +partof: documentation +discourse: true +more-resources-label: Додаткові Матеріали + + +# Content masthead links + + +sections: + - title: "Перші кроки..." + links: + - title: "Початок роботи" + description: "Встанови Scala на свій комп'ютер і почни писати код Scala!" + icon: "fa fa-rocket" + link: /uk/getting-started/install-scala.html + - title: "Екскурсія по Скала" + description: "Короткі введення в основні особливості мови." + icon: "fa fa-flag" + link: /tour/tour-of-scala.html + - title: "Книга по Scala 3" + description: "Вивчи Scala, прочитавши серію коротких уроків." + icon: "fa fa-book-open" + link: /scala3/book/introduction.html + - title: "Онлайн курси" + description: "MOOC для вивчення Scala для початківців і досвідчених програмістів." + icon: "fa fa-cloud" + link: /online-courses.html + - title: "Книги" + description: "Друковані та цифрові книги по Scala." + icon: "fa fa-book" + link: /books.html + - title: "Посібники" + description: "Путівник з серії кроків для створення програм на Scala." + icon: "fa fa-tasks" + link: /tutorials.html + + - title: "Для досвічених" + links: + - title: "API" + description: "Документація API для кожної версії Scala." + icon: "fa fa-file-alt" + link: /api/all.html + - title: "Посібники та огляди" + description: "Поглиблена документація, що покриває багато особливостей Scala." + icon: "fa fa-database" + link: /uk/overviews/index.html + - title: "Довідник по стилю" + description: "Поглиблений посібник з написання ідіоматичного коду на Scala." + icon: "fa fa-bookmark" + link: /style/index.html + - title: "Шпаргалка" + description: "Зручна шпаргалка з основ синтаксису Scala." + icon: "fa fa-list" + link: /uk/cheatsheets/index.html + - title: "Питання-Відповіді" + description: "Відповіді на часті запитання про Scala." + icon: "fa fa-question-circle" + link: /tutorials/FAQ/index.html + - title: "Специфікація мови" + description: "Специфікація формальної мови Scala." + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/2.13/ + - title: "Довідник про мову" + description: "Довідкова інформація про мову Scala 3." + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference + + - title: "Дослідіть Scala 3" + links: + - title: "Посібник з міграції" + description: "Посібник, що допоможе перейти від Scala 2 до Scala 3." + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "Нове у Scala 3" + description: "Огляд нових функцій у Scala 3." + icon: "fa fa-star" + link: /uk/scala3/new-in-scala3.html + - title: "Новий Scaladoc для Scala 3" + description: "Основні характеристики нових функцій у Scaladoc." + icon: "fa fa-star" + link: /uk/scala3/scaladoc.html + - title: "Доповіді" + description: "Онлайн доповіді про Scala 3." + icon: "fa fa-play-circle" + link: /uk/scala3/talks.html + + - title: "Еволюція Scala" + links: + - title: "SIPs" + description: "Процес удосконалення Scala (Scala Improvement Process). Еволюція мови та компілятора." + icon: "fa fa-cogs" + link: /sips/index.html + - title: "Внесок у Scala" + description: "Повний посібник із участі в проекті Scala." + icon: "fa fa-cogs" + link: /contribute/ + - title: "Посібник з внесення змін у Scala 3" + description: "Посібник з компілятора Scala 3 та вирішення проблем." + icon: "fa fa-cogs" + link: /scala3/guides/contribution/contribution-intro.html +--- diff --git a/_uk/overviews/index.md b/_uk/overviews/index.md new file mode 100644 index 0000000000..355fc560fa --- /dev/null +++ b/_uk/overviews/index.md @@ -0,0 +1,8 @@ +--- +layout: overviews +partof: overviews +title: Документація +language: uk +--- + + diff --git a/_uk/scala3/guides/tasty-overview.md b/_uk/scala3/guides/tasty-overview.md new file mode 100644 index 0000000000..53eed66f34 --- /dev/null +++ b/_uk/scala3/guides/tasty-overview.md @@ -0,0 +1,164 @@ +--- +layout: singlepage-overview +title: Огляд TASTy +partof: tasty-overview +language: uk +scala3: true +versionSpecific: true +--- +Створіть файл вихідного коду Scala 3 _Hello.scala_: + +```scala +@main def hello = println("Hello, world") +``` + +і скомпілюйте файл з `scalac`: + +```bash +$ scalac Hello.scala +``` + +ви помітите, що серед інших отриманих файлів, `scalac` створює файли з розширенням _.tasty_: + +```bash +$ ls -1 +Hello$package$.class +Hello$package.class +Hello$package.tasty +Hello.scala +hello.class +hello.tasty +``` + +Виникає питання: «Що таке tasty?» + + + +## Що таке TASTy? + +TASTy це акронім терміну, _Типізоване абстрактне синтаксичне дерево (Typed Abstract Syntax Trees)_. +Це високорівневий формат для Scala 3, і в цьому документі ми називатимемо його як _Tasty_. + +Перше, що важливо знати, це те, що файли Tasty генеруються компілятором `scalac`, +та містять _всю_ інформацію про ваш вихідний код, включаючи синтаксичну структуру вашої програми, +і _повну_ інформацію про типи, позицію та навіть документацію. +Файли Tasty містять набагато більше інформації, ніж файли _.class_, які створюються для роботи на JVM. (Детальніше далі.) + +У Scala 3 процес компіляції виглядає так: + +```text + +-------------+ +-------------+ +-------------+ +$ scalac | Hello.scala | -> | Hello.tasty | -> | Hello.class | + +-------------+ +-------------+ +-------------+ + ^ ^ ^ + | | | + Ваш вихідний Файл TASTy Файл класу + код для scalac для JVM + (містить повну (неповна + інформацію) інформація) +``` + +Ви можете переглянути вміст файлу _.tasty_ у зрозумілій формі, запустивши на ньому компілятор із прапорцем `-print-tasty`. +Ви також можете переглянути вміст, декомпільований у формі, подібній до вихідного коду Scala, використовуючи прапор `-decompile`. +```bash +$ scalac -print-tasty hello.tasty +$ scalac -decompile hello.tasty +``` + +### Проблеми з файлами _.class_ + +Через проблему [стирання типів][erasure], файли _.class_ містять неповне представлення про ваш код. +Простий спосіб продемонструвати це приклад з `List`. + +_Стирання типів_ означає, що коли ви пишете наступний код Scala: + +```scala +val xs: List[Int] = List(1, 2, 3) +``` + +цей код компілюється у файл _.class_, який має бути сумісним із JVM. Результатом цієї вимоги сумісності код всередині цього файлу класу — який ви можете побачити за допомогою команди `javap` — виглядає так: + +```java +public scala.collection.immutable.List xs(); +``` + +Результат команди `javap` показує Java-уявлення того, що міститься у файлі класу. Зверніть увагу, що `xs` більше _не_ визначений як `List[Int]`; він по суті представлений як `List[java.lang.Object]`. Щоб ваш код Scala працював із JVM, тип `Int` має бути стертим. + +Далі, коли ви отримуєте елемент вашого `List[Int]` у вашому Scala коді, наприклад: + +```scala +val x = xs(0) +``` + +отриманий файл класу матиме операцію перетворення для цього рядка коду, яку ви можете уявити так: + +``` +int x = (Int) xs.get(0) // Java-подібно +val x = xs.get(0).asInstanceOf[Int] // більш Scala-подібно +``` + +Знову ж таки, це зроблено для сумісності, щоб ваш код Scala міг працювати на JVM. +Однак, інформація про те, що ми вже мали список цілих чисел, втрачається у файлах класу. +Це створює проблеми під час спроби збірки Scala програми з уже скомпільованою бібліотекою. +Для цього нам потрібно більше інформації, ніж зазвичай міститься у файлах класу. + +Ця дискусія охоплює лише тему стирання типу. +Існують подібні проблеми для кожної іншої конструкції Scala, про які JVM не знає, включно з union, intersection, trait with parameters та багатьма іншими відмінностями Scala 3. + +### На допомогу приходить TASTy +Таким чином, на відміну від відсутньої інформації про вихідні типи у _.class_ файлах або тільки публічного API (як у «Pickle» форматі Scala 2.13), формат TASTy зберігає повне абстрактне синтаксичне дерево (AST) після перевірки типів. +Зберігання всього AST має багато переваг: воно дає можливість окремої компіляції, перекомпіляції для іншої версії JVM, статичного аналізу програм і багато іншого. + +### Ключові моменти + +Отже, це перший висновок з цього розділу: типи, які ви вказуєте у своєму коді Scala, не зовсім точно представлені у файлах _.class_. + +Другим ключовим моментом є розуміння того, що існують відмінності між інформацією, яка доступна під час _компіляції_ та _виконання_: + +- Під **час компіляції**, `scalac` читає та аналізує ваш код, він знає, що `xs` є `List[Int]` +- Коли компілятор записує ваш код у файл класу, він записує `xs` як `List[Object]`, та додає інформацію про перетворення усюди, де йде звернення до `xs` +- Потім під **час виконання** — коли ваш код працює в JVM — JVM не знає, що ваш список є `List[Int]` + +Зі Scala 3 та Tasty, є ще одна важлива примітка про час компіляції: + +- Коли ви пишете код на Scala 3, що використовує інші Scala 3 бібліотеки, `scalac` більше не має читати їх _.class_ файли; + він може прочитати їх _.tasty_ файли, які, як згадувалось, є _точним_ представленням вашого коду. + Це важливо для забезпечення окремої компіляції та сумісності між Scala 2.13 і Scala 3. + + +## Переваги Tasty + +Як ви можете зрозуміти, доступ до повного представлення вашого коду має [багато переваг][benefits]: + +- Компілятор використовує його для підтримки окремої компіляції. +- Сервер мови, що базується на _Мовному серверному протоколі (Language Server Protocol)_ використовує його для підтримки гіперпосилань, завершення команд, документації, та таких глобальних операцій як, пошук звернень та перейменування. +- Tasty створює чудову основу для нового покоління [макросів основаних на рефлексії][macros]. +- Оптимізатори та аналізатори можуть використовувати його для глибокого аналізу коду та розширеної генерації коду. + +У відповідній примітці, Scala 2.13.6 має програму для читання TASTy, а компілятор Scala 3 також може читати формат 2.13 «Pickle». +У [сторінці з classpath сумісності][compatibility-ref] посібнику з міграції на Scala 3 пояснюється перевага можливості крос-компіляції. + + + +## Більше інформації + +Підсумовуючи, Tasty — це високорівневий формат обміну для Scala 3, а файли _.tasty_ містять повне представлення вашого вихідного коду, що надає до переваги, описані у попередніх розділах. +Щоб дізнатися більше, перегляньте ці ресурси: + +- У [цьому відео](https://www.youtube.com/watch?v=YQmVrUdx8TU), Jamie Thompson зі Scala Center детально розповідає про те, як працює Tasty, та його переваги +- Статті з [Бінарної сумісності для авторів бібліотек][binary] розглядаються теми бінарної сумісності, сумісності джерел та модель виконання JVM +- [Подальша сумісність для Scala 3](https://www.scala-lang.org/blog/2020/11/19/scala-3-forward-compat.html) демонструє методи використання Scala 2.13 і Scala 3 в одному проєкті + +Ці статті містять додаткову інформацію про макроси Scala 3: + +- [Бібліотеки макросів Scala](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html) +- [Макроси: плани для Scala 3](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html) +- [Довідник по рефлексії цитат (Quotes Reflect)][quotes-reflect] +- [Довідник по макросах](/scala3/guides/macros) + +[benefits]: https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html +[erasure]: https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure +[binary]: {% link _overviews/tutorials/binary-compatibility-for-library-authors.md %} +[compatibility-ref]: {% link _overviews/scala3-migration/compatibility-classpath.md %} +[quotes-reflect]: {{ site.scala3ref }}/metaprogramming/reflection.html +[macros]: {{ site.scala3ref }}/metaprogramming/macros.html diff --git a/_uk/scala3/new-in-scala3.md b/_uk/scala3/new-in-scala3.md new file mode 100644 index 0000000000..0b00d60ca5 --- /dev/null +++ b/_uk/scala3/new-in-scala3.md @@ -0,0 +1,139 @@ +--- +layout: singlepage-overview +title: Нове в Scala 3 +scala3: true +language: uk +--- +Нова версія Scala 3 принесла багато покращень і нові можливості. +Тут наведено короткий огляд найважливіших змін. +Якщо ви хочете розібратись детальніше глибше, у вашому розпорядженні є наступні посилання: + +- [Книга по Scala 3]({% link _overviews/scala3-book/introduction.md %}) націлений на розробників-початківців мови Scala. +- [Конспект синтаксису][syntax-summary] надає формальний опис нового синтаксису. +- [Довідник з мови][reference] дає детальний опис змін від Scala 2 до Scala 3. +- [Посібник з міграції][migration] надає вам всю інформацію, необхідну для переходу від Scala 2 до Scala 3. +- [Посібник для внесення змін в Scala 3][contribution] глибше занурюється в компілятор, включаючи посібник із розв'язання проблем. + +## Що нового в Scala 3 +Scala 3 - це повне перероблення мови Scala. Було змінено багато аспектів +системи типів на більш принципові. Хоч це і надає нові можливості (наприклад, об’єднання типів), +але в першу чергу це означає, що у вашій роботі стає менше системи типів та [наведення типів][type-inference]. +Також значно покращено процес перевантаження. + +### Нове і яскраве: Синтаксис +Окрім багатьох (невеликих) очищень, синтаксис Scala 3 пропонує такі покращення: + +- Новий «тихий» синтаксис для керуючих структур, таких як `if`, `while` та `for` ([новий синтаксис керуючих структур][syntax-control]) +- Ключеве слово `new` тепер опціональне (_або_ [creator applications][creator]) +- [Опціональні дужки][syntax-indentation] привертають до стилю програмування на основі відступів +- Зміна [символу підстановки типів][syntax-wildcard] з `_` на `?`. +- Імплісіти (та їх синтаксис) були [ґрунтовно переглянуті][implicits]. + +### Впертість: контекстні абстракції +Одним з основних концептів Scala було (і залишається певною мірою) +надання користувачам невеликого набору потужних можливостей, які можна комбінувати +заради великої (а іноді навіть непередбачуваної) виразності. Наприклад, _implicits_ +використовувалися для моделювання контекстної абстракції, для вираження обчислення +на рівні типів, моделювання типів-класів, виконання неявних приведень, кодування +розширення методів та багато іншого. +Базуючись на цих прикладах використання, Scala 3 використовує дещо інший підхід +і фокусується на **намірі**, а не на **механізмі**. +Замість того, щоб пропонувати одну дуже потужну функцію, Scala 3 пропонує кілька +спеціальних мовних конструкцій, що дозволяють програмістам прямо висловлювати свої наміри: + +- **Абстрагування над контекстною інформацією**. [Ключове слово using][contextual-using] дозволяє програмістам абстрагуватися від інформації, яка доступна в контексті виклику і повинна передаватися неявно. Конструкція using є удосконаленням implicit зі Scala 2 та може бути визначена за типом, звільняючи сигнатури функцій від термів, на які ніколи не посилаються явно. + +- **Надання екземплярів класів типів**. [Наведені екземпляри][contextual-givens] дозволяють програмістам визначати _канонічне значення_ певного типу. Це робить програмування з класами типів простішим без витоку деталей реалізації. + +- **Ретроспективне розширення класів**. У Scala 2 методи розширення повинні бути закодовані за допомогою неявних перетворень або неявних класів. На відміну від цього, у Scala 3 [методи розширення][contextual-extension] тепер безпосередньо вбудовані в мову, що призводить до кращих повідомлень про помилки та покращеного виведення типу. + +- **Відображення одного типу як іншого**. Неявні перетворення були [перероблені][contextual-conversions] з нуля як екземпляри класу типів `Conversion`. + +- **Контекстні абстракції вищого порядку**. _Абсолютно нова_ можливість [контекстних функцій][contextual-functions] робить контекстні абстракції first-class citizen. Вони є важливим інструментом для авторів бібліотек і дозволяють стисло виразити домен-специфічні мови. + +- **Дієвий відгук від компілятора**. Якщо неявний параметр не може бути розв'язаний компілятором, то надаються [пропозиції імпорту](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html), що можуть розв'язувати проблему. + +### Скажи що маєш на увазі: покращення системи типів +Окрім значно покращеного виведення типів, система типів Scala 3 також пропонує багато нових функцій, надаючи вам потужні інструменти для статичного вираження інваріантів у типах: + +- **Перерахування**. [Enum][enums] був перероблений, щоб добре поєднуватися з кейс-класами та сформувати новий стандарт для вираження [алгебраїчних типів даних][enums-adts]. + +- **Непрозорі типи**. Сховайте деталі реалізації за [псевдонімом непрозорого типу][types-opaque] без зниження перфомансу! Непрозорі типи замінюють класи значень і дозволяють налаштувати бар'єр абстракції без додаткових накладних витрат. + +- **Типи перетину та об'єднання**. Нові засади системи типів призвели до введення нових можливостей системи типів: екземпляр [типу Intersection][types-intersection], як `A & B`, є екземпляром _обох_ типів і `A` і `B`. Екземпляр [типу Union][types-union], як `A | B`, є екземпляром _або_ `A` або `B`. Обидві конструкції дозволяють програмістам гнучко обмежувати типи поза межами ієрархії наслідування. + +- **Залежні типи функцій**. Scala 2 вже дозволяє типам результату залежати від (значення) аргументів. У Scala 3 тепер можна абстрагуватися над цим шаблоном і виразити [залежні типи функцій][types-dependent]. В типі `type F = (e: Entry) => e.Key` результат _залежить_ від аргументу! + +- **Поліморфні типи функцій**. Як і типи функцій залежності, Scala 2 підтримувала методи, які дозволяють параметри типу, але не дозволяла абстрагуватися над цими методами. У Scala 3, [поліморфні типи функцій][types-polymorphic], наприклад `[A] => List[A] => List[A]` абстрагується над функцією, що приймає _аргумент типу_ на додачу до аргументів значень. + +- **Лямбда типу**. Те, що виражалося з використанням [плагіна компілятора](https://github.com/typelevel/kind-projector) в Scala 2 тепер є першокласною особливістю в Scala 3: Лямбда типу — це функції рівня типів, які можна передавати як аргументи типу (вищого роду) без визначення допоміжного типу. + +- **Відповідність типів**. Замість того, щоб кодувати обчислення на рівні типу з використанням імплісітів, Scala 3 пропонує пряму підтримку [відповідності за типами][types-match]. Інтеграція обчислень на рівні типів у процес перевірки типів дозволяє покращити повідомлення про помилки та усуває необхідність у складному кодуванні. + + +### Переосмислено: об'єктно-орієнтоване програмування +Scala завжди була на межі між функціональним програмуванням та об'єктноорієнтованим програмуванням -- і Scala 3 розширює межі в обох напрямках! +Вищезгадані зміни в системі типів і перероблення контекстних абстракцій роблять _функціональне програмування_ легшим, ніж раніше. +Водночас наступні нові функції дозволяють добре структурувати _об'єктноорієнтовані проєкти_ та підтримують найкращі практики. + +- **Pass it on**. Трейти наближаються до класів і тепер також можуть приймати [параметри][oo-trait-parameters], що робить їх ще більш потужними як інструмент для модульної декомпозиції. +- **План розширення**. Класи розширення, які не призначені для наслідування, є давньою проблемою в об'єктноорієнтованому програмуванні. Для розв'язання цього питання, [відкриті класи][oo-open] вимагають у розробників бібліотек _явно_ позначити класи як відкриті. +- **Приховати деталі реалізації**. Утилітні трейти, які іноді реалізують поведінку, не повинні входити до складу виведених типів. У Scala 3, такі трейти можуть бути позначені як [прозорі][oo-transparent] приховуючи наслідування від користувача (у виведених типах). +- **Композиція понад спадковістю**. Це поняття широко згадується, але є важким у реалізації. Але не з [export][oo-export] у Scala 3's: симетричні до імпорту, експорти дозволяють користувачеві визначати псевдоніми для вибраних членів об'єкта. +- **Більше без NPE**. Scala 3 безпечніша, ніж будь-коли: [явний null][oo-explicit-null] виводить `null` з ієрархії типів, допомагаючи статично виловлювати помилки; додаткові перевірки для [безпечної ініціалізації][oo-safe-init] виявляють доступ до неініціалізованих об'єктів. + + +### Батарейки в комплекті: метапрограмування +Хоча макроси в Scala 2 були лише експериментальною функцією, Scala 3 поставляється з потужним арсеналом інструментів для метапрограмування. +[Посібник по макросах]({% link _overviews/scala3-macros/tutorial/index.md %}) містить детальну інформацію про різні об'єкти. Зокрема, Scala 3 пропонує наступні можливості для метапрограмування: + +- **Inline**. Як відправна точка, [inline][meta-inline] дозволяє редукувати значення та методи під час компіляції. Ця проста функція вже охоплює багато варіантів використання і в той же час є точкою входу для більш розширених функцій. +- **Операції під час компіляції**. Пакет [`scala.compiletime`][meta-compiletime] містить додаткову функціональність, яку можна використовувати для реалізації вбудованих методів. +- **Цитування блоків коду**. Scala 3 додає нову можливість [квазі-цитування][meta-quotes] коду, що надає зручний інтерфейс високого рівня для побудови та аналізу коду. Побудувати код для додавання одиниці до одиниці так само просто, як і `'{ 1 + 1 }`. +- **API рефлексії**. Для більш просунутих випадків використання [quotes.reflect][meta-reflection] забезпечує більш детальний контроль для перевірки та створення дерев програм. + +Якщо ви хочете дізнатися більше про метапрограмування в Scala 3, пропонуємо подивитись на наш [посібник][meta-tutorial]. + + +[enums]: {{ site.scala3ref }}/enums/enums.html +[enums-adts]: {{ site.scala3ref }}/enums/adts.html + +[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html +[types-union]: {{ site.scala3ref }}/new-types/union-types.html +[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html +[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html +[types-match]: {{ site.scala3ref }}/new-types/match-types.html +[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html + +[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html +[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html +[reference]: {{ site.scala3ref }}/overview.html +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %} +[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %} + +[implicits]: {{ site.scala3ref }}/contextual +[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html +[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html +[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html +[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html +[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html + +[syntax-summary]: {{ site.scala3ref }}/syntax.html +[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html +[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html +[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html + +[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %} +[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %} + +[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html +[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html +[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html +[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html +[oo-export]: {{ site.scala3ref }}/other-new-features/export.html diff --git a/_uk/scala3/scaladoc.md b/_uk/scala3/scaladoc.md new file mode 100644 index 0000000000..66a6d12805 --- /dev/null +++ b/_uk/scala3/scaladoc.md @@ -0,0 +1,89 @@ +--- +layout: singlepage-overview +title: Нові можливості в Scaladoc +partof: scala3-scaladoc +language: uk +scala3: true +--- + +Нова версія Scala 3 поставляється з абсолютно новою реалізацією генератора документації _Scaladoc_, переписаною з нуля. +У цій статті ви можете знайти огляд нових функцій, які є або будуть представлені в Scaladoc. +Для загальної довідки відвідайте [посібник Scaladoc]({% link _overviews/scala3-scaladoc/index.md %}). + +## Нові можливості + +### Синтаксис Markdown + +Найбільшою зміною, внесеною в нову версію Scaladoc, є зміна мови за замовчуванням для docstrings. Поки що Scaladoc підтримував лише синтаксис Wikidoc. +Новий Scaladoc все ще може аналізувати застарілий синтаксис `Wikidoc`, однак Markdown вибрано як основну мову для форматування коментарів. +Щоб повернутися до `Wikidoc`, можна передати глобальний прапор перед запуском `doc` або визначити його для конкретних коментарів за допомогою директиви `@syntax wiki`. + +Щоб отримати додаткову інформацію про те, як використовувати повну силу документації, перегляньте [Scaladoc docstrings][scaladoc-docstrings] + + +### Статичні вебсайти + +Scaladoc також забезпечує простий спосіб створення **статичних сайтів** як для документації, так і для публікацій у блозі, подібно до того, як це робить Jekyll. +Завдяки цій функції ви можете зберігати свою документацію разом зі згенерованим API Scaladoc дуже зручним способом. + +Щоб отримати додаткову інформацію про те, як налаштувати генерацію статичних сайтів, перегляньте абзац [Статична документація][static-documentation] + +![](/resources/images/scala3/scaladoc/static-site.png) + +### Публікації в блозі + +Дописи в блозі – це особливий тип статичних сайтів. У посібнику Scaladoc ви можете знайти додаткову інформацію про те, як працювати з [публікаціями в блозі][built-in-blog]. + +![](/resources/images/scala3/scaladoc/blog-post.png) + +### Посилання на соціальні мережі + +Крім того, Scaladoc надає простий спосіб налаштувати [посилання на соціальні мережі][social-links], наприклад Twitter чи Discord. + +![](/resources/images/scala3/scaladoc/social-links.png){: style="width: 180px"} + +## Експериментальні особливості + +На поточний час (травень 2021 р.) перелічені нижче функції не можуть бути випущені разом із Scaladoc, однак ми будемо раді почути ваші відгуки. +Кожна функція має власний розділ на сайті учасників scala-lang, де ви можете поділитися своїми думками. + +### Компіляція фрагментів + +Одним з експериментальних особливостей Scaladoc є компілятор фрагментів (snippets compiler). +Цей інструмент дозволить вам компілювати фрагменти, які ви додаєте до docstring, щоб перевірити, чи вони насправді поводяться належним чином. +Ця функція дуже схожа на інструменти `tut` або `mdoc`, але буде поставлятися разом із Scaladoc для легкого налаштування та інтеграції у ваш проєкт. +Зробити фрагменти інтерактивними, наприклад, дозволити користувачам редагувати та компілювати їх у браузері, наразі розглядається. + +Вітрина: +* Приховування коду ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/hiding-code.gif) +* Виявлення помилок компіляції ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/assert-compilation-errors.gif) +* Включення фрагментів ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-includes.png) + +Для більш детальної інформації дивіться [Посібники](/scala3/guides/scaladoc/snippet-compiler.html), або перейдіть у [тред Scala Contributors](https://contributors.scala-lang.org/t/snippet-validation-in-scaladoc-for-scala-3/4976) + +### Пошук, оснований на типах + +Пошук функцій за їх символьними назвами може зайняти багато часу. +Саме тому новий Scaladoc дозволяє шукати методи та поля за їх типами. + +Тому для декларації: +``` +extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ... +``` +Замість того, щоб шукати `span`, ми можемо шукати `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`. + +Щоб скористатися цією функцією, просто введіть підпис функції, яку ви шукаєте, на панелі пошуку scaladoc. Ось як це працює: + +![](/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif) + +Ця функція забезпечується пошуковою системою [Inkuire](https://github.com/VirtusLab/Inkuire), яка працює для Scala 3 і Kotlin. Щоб бути в курсі розвитку цього інструменту, підпишіться на оновлення [репозиторію Inkuire](https://github.com/VirtusLab/Inkuire). + +Для отримання додаткової інформації дивіться [Посібники](/scala3/guides/scaladoc/search-engine.html) + +Зауважте, що ця функція все ще знаходиться на стадії розробки, тому вона може зазнати значних змін. +Якщо ви зіткнулися з помилкою або маєте ідею щодо покращення, не соромтеся створювати проблему на [Inkuire](https://github.com/VirtusLab/Inkuire/issues/new) або [dotty](https://github.com/scala/scala3/issues/new). + +[scaladoc-docstrings]: {% link _overviews/scala3-scaladoc/docstrings.md %} +[static-documentation]: {% link _overviews/scala3-scaladoc/static-site.md %} +[built-in-blog]: {% link _overviews/scala3-scaladoc/blog.md %} +[social-links]: {% link _overviews/scala3-scaladoc/settings.md %}#-social-links diff --git a/_uk/scala3/talks.md b/_uk/scala3/talks.md new file mode 100644 index 0000000000..01087ab671 --- /dev/null +++ b/_uk/scala3/talks.md @@ -0,0 +1,90 @@ +--- +layout: singlepage-overview +title: Розмови +partof: scala3-talks +language: uk +scala3: true +versionSpecific: true +--- + +Серія "Поговорімо про Scala 3" +------------------------------- + +[Поговорімо про Scala 3](https://www.youtube.com/playlist?list=PLTx-VKTe8yLxYQfX_eGHCxaTuWvvG28Ml) є серією +коротких (близько 15 хвилин) розмов про Scala 3. Він охоплює різноманітні теми, наприклад, як почати, як застосувати +переваги нових функцій мови, або як перейти з Scala 2. + +Talks on Scala 3 +---------------- +- (ScalaDays 2019, Lausanne) [Тур по Scala 3](https://www.youtube.com/watch?v=_Rnrx2lo9cw) + від [Martin Odersky](http://x.com/odersky) + +- (ScalaDays 2016, Berlin) [Попереду дорога Scala](https://www.youtube.com/watch?v=GHzWqJKFCk4) + від [Martin Odersky](http://x.com/odersky) + [\[слайди\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016) + +- (JVMLS 2015) [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc) + від [Martin Odersky](http://x.com/odersky) + [\[слайди\]](http://www.slideshare.net/Odersky/compilers-are-databases) + +- (Scala World 2015) [Dotty: Досліджуємо майбутнє Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) + від [Dmitry Petrashko](http://x.com/darkdimius) + [\[слайди\]](https://d-d.me/scalaworld2015/#/). + Розповідь Дмітрія охоплює багато нових функцій, які приносить Dotty, наприклад типи Intersection та Union, покращена ініціалізація lazy val тощо. + Дмітрій також розповідає внутрішню архітектуру Dotty і, зокрема, високий рівень контекстуальних абстракцій Dotty. Ви + ознайомитесь з багатьма базовими поняттями, такими як «Denotations» та їх особливостями. + +Deep Dive with Scala 3 +---------------------- +- (ScalaDays 2019, Lausanne) [Метапрограмування in Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) + від [Nicolas Stucki](https://github.com/nicolasstucki). + +- (ScalaDays 2019, Lausanne) [Future-proofing в Scala: проміжна репрезентація TASTY](https://www.youtube.com/watch?v=zQFjC3zLYwo) + від [[Guillaume Martres](http://guillaume.martres.me/)](http://guillaume.martres.me/). + +- (Mar 21, 2017) [Dotty Internals 1: Trees та Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8) + від [Dmitry Petrashko](http://x.com/darkdimius) + [\[meeting notes\]](https://dotty.epfl.ch/docs/internals/dotty-internals-1-notes.html). + Це запис зустрічі EPFL та Waterloo, де були представлені перші нотатки про Dotty: Trees та Symbols. + +- (Mar 21, 2017) [Dotty Internals 2: Types](https://www.youtube.com/watch?v=3gmLIYlGbKc) + від [Martin Odersky](http://x.com/odersky) та [Dmitry Petrashko](http://x.com/darkdimius). + Це запис зустрічі EPFL та Waterloo, де були представлено як представлені типи всередині Dotty. + +- (Jun 15, 2017) [Dotty Internals 3: Denotations](https://youtu.be/9iPA7zMRGKY) + від [Martin Odersky](http://x.com/odersky) та [Dmitry Petrashko](http://x.com/darkdimius). + Це запис зустрічі EPFL та Waterloo, де були представлена денотація в Dotty. + +- (JVM Language Summit) [Як зробити компілятор Dotty швидким](https://www.youtube.com/watch?v=9xYoSwnSPz0) + від [Dmitry Petrashko](http://x.com/darkdimius). + Дмітрій дає високорівневий вступ до того, що було зроблено для створення Dotty . + +- (Typelevel Summit Oslo, May 2016) [Dotty та типи: поки що історія](https://www.youtube.com/watch?v=YIQjfCKDR5A) + від [Guillaume Martres](http://guillaume.martres.me/) + [\[слайди\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/). + Гійом зосередився на деяких практичних вдосконаленнях системи типів, які робить Dotty. Це новий алгоритм параметру типу, + який здатний робити висновки про безпеку типів для більшої кількості ситуацій ніж scalac. + +- (flatMap(Oslo) 2016) [AutoSpecialization в Dotty](https://vimeo.com/165928176) + від [Dmitry Petrashko](http://x.com/darkdimius) + [\[слайди\]](https://d-d.me/talks/flatmap2016/#/). + Компонувальник Dotty аналізує вашу програму та її залежності, щоб застосувати нову схему спеціалізації. + Віна ґрунтується на нашому досвіді з Specialization, Miniboxing та Valhalla Project, + і різко зменшує розмір байт-коду. І, що найкраще, це завжди ввімкнено, відбувається за кулісами без анотацій, + що призводить до прискорення понад 20 разів. Крім того, він «просто працює» на колекціях Scala. + +- (ScalaSphere 2016) [Hacking on Dotty: жива демонстрація](https://www.youtube.com/watch?v=0OOYGeZLHs4) + від [Guillaume Martres](http://guillaume.martres.me/) + [\[слайди\]](http://guillaume.martres.me/talks/dotty-live-demo/). + Прийоми Гійома для Dotty: демонстрація в реальному часі, під час якої він створює просту фазу компілятора для відстеження викликів методів під час виконання. + +- (Scala By the Bay 2016) [Dotty: що це і як працює](https://www.youtube.com/watch?v=wCFbYu7xEJA) + від [Guillaume Martres](http://guillaume.martres.me/) + [\[слайди\]](http://guillaume.martres.me/talks/dotty-tutorial/#/). + Гійом демонструє високорівневе представлення пайплайну компіляції в Dotty. + +- (ScalaDays 2015, Amsterdam) [Як зробити ваші програми на Scala меншими та швидшими за допомогою компонувальника Dotty](https://www.youtube.com/watch?v=xCeI1ArdXM4) + від [Dmitry Petrashko](http://x.com/darkdimius) + [\[слайди\]](https://d-d.me/scaladays2015/#/). + Дмитрій представляє алгоритм аналізу графу виклик у Dotty та переваги продуктивності, які ми можемо отримати з точки зору кількості методів, + розміру байт-коду, розміру коду JVM і кількість об'єктів, виділених в кінці. diff --git a/_zh-cn/cheatsheets/index.md b/_zh-cn/cheatsheets/index.md index 0559d37acd..c9fd0e7557 100644 --- a/_zh-cn/cheatsheets/index.md +++ b/_zh-cn/cheatsheets/index.md @@ -1,11 +1,11 @@ --- layout: cheatsheet -title: Scalacheat +title: Scala Cheatsheet partof: cheatsheet by: Brendan O'Connor -about: 感谢 Brendan O'Connor, 本速查表可以用于快速地查找Scala语法结构。Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. +about: 感谢 Brendan O'Connor，本速查表可以用于快速地查找Scala语法结构。Licensed by Brendan O'Connor under a CC-BY-SA 3.0 license. language: "zh-cn" --- @@ -15,40 +15,40 @@ language: "zh-cn" | 变量 | | -|  `var x = 5`                                                                                             | 可变量       | +|  `var x = 5`                                                                                             | 可变变量       | | Good `val x = 5`
            Bad `x=6` | 常量 | |  `var x: Double = 5`                                                                                     | 显式类型 | | 函数 | | -|  Good `def f(x: Int) = { x*x }`
            Bad `def f(x: Int)   { x*x }` | 定义函数
            隐藏出错: 不加“=”号将会是一段返回Unit类型的过程，这将会导致意想不到的错误。 | +|  Good `def f(x: Int) = { x*x }`
            Bad `def f(x: Int)   { x*x }` | 定义函数
            潜在风险: 不加“=”号将会是一段返回Unit类型的过程，这将会导致意想不到的错误。 | | Good `def f(x: Any) = println(x)`
            Bad `def f(x) = println(x)` | 定义函数
            语法错误: 每个参数都需要指定类型。 | | `type R = Double` | 类型别名 | |  `def f(x: R)` vs.
            `def f(x: => R)`                                                                 | 传值调用
            传名调用 （惰性参数） | | `(x:R) => x*x` | 匿名函数 | -| `(1 to 5).map(_*2)` vs.
            `(1 to 5).reduceLeft( _+_ )` | 匿名函数: 下划线是arg参数的占位符。 | -| `(1 to 5).map( x => x*x )` | 匿名函数: 必须命名以后才可以使用一个arg参数两次。 | -|  Good `(1 to 5).map(2*)`
            Bad `(1 to 5).map(*2)` | 匿名函数: 绑定前缀方法，理智的方法是`2*_`。 | -|  `(1 to 5).map { x => val y=x*2; println(y); y }`                                                             | 匿名函数: 程序块风格，最后一个表达式作为返回值。 | +| `(1 to 5).map(_*2)` vs.
            `(1 to 5).reduceLeft( _+_ )` | 匿名函数: 下划线是参数的占位符。 | +| `(1 to 5).map( x => x*x )` | 匿名函数: 必须命名以后才可以多次使用同一个参数。 | +|  Good `(1 to 5).map(2*)`
            Bad `(1 to 5).map(*2)` | 匿名函数: 绑定中缀方法，明智的做法是`2*_`。 | +|  `(1 to 5).map { x => val y=x*2; println(y); y }`                                                             | 匿名函数: 代码块风格，最后一个表达式作为返回值。 | |  `(1 to 5) filter {_%2 == 0} map {_*2}`                                                                 | 匿名函数: 管道风格（或者用圆括号）。 | -|  `def compose(g:R=>R, h:R=>R) = (x:R) => g(h(x))`
            `val f = compose({_*2}, {_-1})`                   | 匿名函数: 要传入多个程序块的话，需要外围括号。 | +|  `def compose(g:R=>R, h:R=>R) = (x:R) => g(h(x))`
            `val f = compose({_*2}, {_-1})`                   | 匿名函数: 要传入多个代码块的话，需要使用花括号。 | | `val zscore = (mean:R, sd:R) => (x:R) => (x-mean)/sd` | 柯里化, 显然的语法。 | | `def zscore(mean:R, sd:R) = (x:R) => (x-mean)/sd` | 柯里化, 显然的语法。 | |  `def zscore(mean:R, sd:R)(x:R) = (x-mean)/sd`                                                           | 柯里化，语法糖。然后:) | |  `val normer = zscore(7, 0.4) _`                                                                         | 需要在尾部加下划线来变成偏函数（只对语法糖版本适用）。 | | `def mapmake[T](g:T=>T)(seq: List[T]) = seq.map(g)` | 泛型 | |  `5.+(3); 5 + 3`
            `(1 to 5) map (_*2)`                                                               | 中缀语法糖 | -| `def sum(args: Int*) = args.reduceLeft(_+_)` | 可变参数 | +| `def sum(args: Int*) = args.reduceLeft(_+_)` | 变长参数 | | 包 | | | `import scala.collection._` | 通配符导入 | | `import scala.collection.Vector`
            `import scala.collection.{Vector, Sequence}` | 选择性导入 | | `import scala.collection.{Vector => Vec28}` | 重命名导入 | -| `import java.util.{Date => _, _}` | 导入java.util包里除Date之外的所有文件. | +| `import java.util.{Date => _, _}` | 导入java.util包里除Date之外的一切。 | |  `package pkg` _at start of file_
            `package pkg { ... }`                                             | 声明这是一个包 | | 数据结构 | | |  `(1,2,3)`                                                                                               | 元组字面量 (`Tuple3`) | | `var (x,y,z) = (1,2,3)` | 解构绑定：通过模式匹配来解构元组。 | -|  Bad`var x,y,z = (1,2,3)`                                           | 隐藏出错：每一个变量都被赋值了整个元组。 | -| `var xs = List(1,2,3)` | 列表 (不可变). | -| `xs(2)` | 用括号索引 ([slides](http://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) | +|  Bad`var x,y,z = (1,2,3)`                                           | 潜在风险：整个元组被赋值给了每一个变量。 | +| `var xs = List(1,2,3)` | 列表 (不可变)。 | +| `xs(2)` | 用括号索引 ([slides](https://www.slideshare.net/Odersky/fosdem-2009-1013261/27)) | |  `1 :: List(2,3)`                                                                                       | Cons（构成） | |  `1 to 5` _等价于_ `1 until 6`
            `1 to 10 by 2`                                                     | Range类型（语法糖） | |  `()` _(空括号)_                                                                                   | Unit类型的唯一成员 (相当于 C/Java 里的void). | @@ -57,13 +57,13 @@ language: "zh-cn" | `if (check) happy` _same as_
            `if (check) happy else ()` | 条件（语法糖） | | `while (x < 5) { println(x); x += 1}` | while循环 | | `do { println(x); x += 1} while (x < 5)` | do while循环 | -| `import scala.util.control.Breaks._`
            `breakable {`
            ` for (x <- xs) {`
            ` if (Math.random < 0.1) break`
            ` }`
            `}`| break. ([slides](http://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) | -|  `for (x <- xs if x%2 == 0) yield x*10` _等价于_
            `xs.filter(_%2 == 0).map(_*10)`                   | for comprehension （for 导出）: filter/map | -|  `for ((x,y) <- xs zip ys) yield x*y` _等价于_
            `(xs zip ys) map { case (x,y) => x*y }`             | for comprehension （for 导出）: 解构绑定 | -| `for (x <- xs; y <- ys) yield x*y` _等价于_
            `xs flatMap {x => ys map {y => x*y}}` | for comprehension （for 导出）: 叉乘 | -|  `for (x <- xs; y <- ys) {`
               `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
            `}`                     | for comprehension （for 导出）: 不可避免的格式
            [sprintf-style](http://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | -| `for (i <- 1 to 5) {`
            `println(i)`
            `}` | for comprehension （for 导出）: 包括上边界的遍历 | -| `for (i <- 1 until 5) {`
            `println(i)`
            `}` | for comprehension （for 导出）: 忽略上边界的遍历 | +| `import scala.util.control.Breaks._`
            `breakable {`
            ` for (x <- xs) {`
            ` if (Math.random < 0.1) break`
            ` }`
            `}`| break. ([slides](https://www.slideshare.net/Odersky/fosdem-2009-1013261/21)) | +|  `for (x <- xs if x%2 == 0) yield x*10` _等价于_
            `xs.filter(_%2 == 0).map(_*10)`                   | for 表达式: filter/map | +|  `for ((x,y) <- xs zip ys) yield x*y` _等价于_
            `(xs zip ys) map { case (x,y) => x*y }`             | for 表达式: 解构绑定 | +| `for (x <- xs; y <- ys) yield x*y` _等价于_
            `xs flatMap {x => ys map {y => x*y}}` | for 表达式: 叉乘 | +|  `for (x <- xs; y <- ys) {`
               `println("%d/%d = %.1f".format(x, y, x/y.toFloat))`
            `}`                     | for 表达式: 不可避免的格式
            [sprintf-style](https://java.sun.com/javase/6/docs/api/java/util/Formatter.html#syntax) | +| `for (i <- 1 to 5) {`
            `println(i)`
            `}` | for 表达式: 包括上边界的遍历 | +| `for (i <- 1 until 5) {`
            `println(i)`
            `}` | for 表达式: 忽略上边界的遍历 | | 模式匹配 | | |  Good `(xs zip ys) map { case (x,y) => x*y }`
            Bad `(xs zip ys) map( (x,y) => x*y )` | 在函数的参数中使用模式匹配的例子。 | | Bad
            `val v42 = 42`
            `Some(3) match {`
            ` case Some(v42) => println("42")`
            ` case _ => println("Not 42")`
            `}` | "v42" 被解释为可以匹配任何Int类型值的名称，打印输出"42"。 | diff --git a/_zh-cn/glossary/index.md b/_zh-cn/glossary/index.md new file mode 100644 index 0000000000..055eff8026 --- /dev/null +++ b/_zh-cn/glossary/index.md @@ -0,0 +1,396 @@ +--- +layout: glossary +title: Glossary + +language: zh-cn +--- + +
            该术语表摘自Scala权威书籍《Programming in Scala》
            + +
            +
            + +
            + + +   +
            + +* ### 代数数据类型（algebraic data type） +通过提供若干个带有独立构造器的备选项来定义的类型。它一般通过模式匹配的方式来结构类型，在规约语言和函数式编程语言中常见到这个概念。Scala可通过样例类来模拟代数数据类型。 + +* ### 备选项（alternative） +match表达式的一个分支，形如 “`case` _pattern_ => _expression_”。备选项的别名是 _案例_（_case_）。 + +* ### 注解（annotation） +注解一般出现在源码中，并附加到语法的某个部分。注解对于计算机来说都是可处理的，所以可以用来有效的增加Scala扩展。 + +* ### 匿名类（anonymous class） +匿名类是由Scala编译器根据一种new表达式生成的合成子类，这种new表达式由类名或特质名后面紧跟一对花括号组成。花括号内包含了匿名子类的构造体，可为空，不过一旦跟在new后面名称指向的特质或类包含了抽象成员，则这些抽象成员就必须在其匿名子类的构造体内具化，即在花括号内要实现这些成员。 + +* ### 匿名函数（anonymous function） +[函数字面量](#函数字面量function-literal)的另一种叫法。 + +* ### 应用（apply） +方法、函数或闭包应用于参数，意思是说通过这些实参来调用方法、函数或闭包。 + +* ### 实参（argument） +在函数调用过程中实参被传给函数的各个参数，其中参数就是指向实参的变量，实参则是调用发生时被传入的对象。另外，应用程序都可以获取被传入单例对象的main方法且类型为`Array[String]`的实参（来自命令行）。 + +* ### 赋值（assign） +可把对象赋值给变量，之后，变量就会指向对象。 + +* ### 辅助构造器（auxiliary constructor） +在类定义体花括号里面定义的所有附加构造器，其形似名为`this`但无结果类型的方法定义。 + +* ### 块（block） +被花括号围起来的一个或多个表达式和声明。求值块的时候，块内所有表达式和声明会被顺序处理，然后会返回最后一个表达式的值作为其自身的值。块通常被用来作为构造体，诸如函数、[for表达式](#for表达式for-expression)、`while`循环以及其他任何需要把语句组织到一起的地方，都会用到块。更正式点说，块是一个只其副作用和结果值对外可见的封装构造体。因此，类或对象的花括号是不会形成块的，因其内部定义字段和方法均对外可见。这样的花括号形成的是模板。 + +* ### 绑定变量（bound variable） +表达式的绑定变量是定义和使用都在表达式内部的变量。例如，在函数字面量表达式`(x: Int) => (x, y)`里面，`x`和`y`都被用到了，但只有`x`被绑定了，因为它在表达式中被定义为一个`Int`变量，并且它也是表达式所描述函数的唯一实参。 + +* ### 传名参数（by-name parameter） +参数类型前面带有`=>`的参数，如`(x: => Int)`。传名参数对应的实参求值不在方法被调用前，而是在每次方法通过名称引用到参数的时候。参数若不是传名的，则定是传值的。 + +* ### 传值参数（by-value parameter） +参数类型前面不带`=>`的参数，如`(x: Int)`。传值参数对应的实参是在方法调用前被求值的。传值参数是相对传名参数而言的。 + +* ### 类（class） +通过关键字`class`来定义的类，可抽象可具体，且在实例化时可用类型和值对其进行参数化处理。比如`new Array[String](2)`，被实例化的类是`Array`，产生的值类型为`Array[String]`。带有类型参数的类被称为 _类型构造器_ ，也可说成是类型具有类属性，如：类型`Array[String]`具有的类属性是`Array`。 + +* ### 闭包（closure） +可以捕获自由变量，或者说"关闭"函数创建时可见变量的函数对象。 + +* ### 伴生类（companion class） +和定义在相同源文件中的单例对象共享同一个名称的类，这样的类就叫做那个单例对象的伴生类。 + +* ### 伴生对象（companion object） +和定义在相同源文件中的类共享同一个名称的单例对象。伴生对象和伴生类具备访问彼此私有成员的能力。另外，类不管被用在何处，其伴生对象中定义的任何隐式转换都在其作用域内。 + +* ### 逆变（contravariant） +逆变标注可应用于类或特质的类型参数上，把减号（-）置于类型参数前即可。标注为逆变后类或特质的子类型将逆向（向相反的方向）协变于类型标注的参数。比如，`Function1`的第一个类型参数就是逆变的，所以`Function1[Any, Any]`是`Function1[String, Any]`的子类。 + +* ### 协变（covariant） +协变标注可应用于类或特质的类型参数上，把加号（+）置于类型参数前即可。标注为协变后类或特质的子类型将正向（向相同的方向）协变于类型标注的参数。比如，`List`的类型参数是协变的，所以`List[String]`是`List[Any]`的子类。 + +* ### 柯里化（currying） +把函数写成多个参数列表的方式。例如：`def f(x: Int)(y: Int)`是一个带有两个参数列表的柯里化函数。应用柯里化函数时需传入若干个实参列表，像`f(3)(4)`这样。不过也可以写成柯里化函数的 _部分应用_（partial application），像`f(3)`这样。 + +* ### 声明（declare） +可以通过 _声明_ 抽象的字段、方法或类型来赋给实体一个名称，但是没有具体实现。声明和定义最关键的差异就是定义会为命名实体创建具体实现，而声明则不会。 + +* ### 定义（define） +在Scala程序中若提到 _定义_ 什么东西，就是说给它赋个名称并给出实现。可以定义的东西包括类、特质、单例对象、字段、方法、局部函数、局部变量等。由于提到定义常常会涉及到某种具体实现，故而抽象成员应为声明而非定义。 + +* ### 直接子类（direct subclass） +类是其 _直接子类_ 的直接超类。 + +* ### 直接超类（direct superclass） +从某个类直接衍生出类或特质，或者说在继承层级结构最接近自己的上层的某个类，这样的类就是直接超类。若类`Child`的可选的extends子句中含有类`Parent`，则`Parent`就是`Child`的直接超类。若`Child`的可选extends子句中含有特质，则特质的直接超类也是`Child`的直接超类。若`Child`没有extends子句，则`AnyRef`就是`Child`的直接超类。若类的直接超类带有类型参数，比如`Child extends Parent[String]`，`Child`的直接超类依旧是`Parent`，而不是`Parent[String]`。另一方面，`Parent[String]`应该叫做`Child`的直接超类型。参见[超类型](#超类型supertype)了解更多关于类和类型间的区别。 + +* ### 相等性（equality） +在没有条件限制的情况下使用时，_相等性_ 就是`==`所表达的两个值之间的关系。参见[引用相等性](#引用相等性reference-equality)。 + +* ### 存在类型（existential type） +存在类型包含未知类型变量的引用。比如：`Array[T] forSome { type T }`是个存在类型，是`T`的数组，而`T`是某个完全未知的类型，关于`T`唯一能够假定的是它是确定存在的。尽管这个假定很虚，但是至少意味着`Array[T] forSome { type T }`确实是个数组，而不是香蕉什么的东西。 + +* ### 表达式（expression） +任何能够得到结果的Scala代码，也可说成表达式求值为某个结果或结果为某个值。 + +* ### 过滤器（filter） +[for表达式](#for表达式for-expression)中的`if`及跟在其后的布尔表达式。在`for(i <- 1 to 10; if i % 2 == 0)`中，过滤器为"`if i % 2 == 0`"。`if`右边的值就是[过滤器表达式](#过滤器表达式filter-expression)，也称为守卫。 + +* ### 过滤器表达式（filter expression） +过滤器表达式就是[for表达式](#for表达式for-expression)里面跟在`if`后面的布尔表达式。`for( i <- 1 to 10 ; if i % 2 == 0)`的过滤器表达式为"`i % 2 == 0`"。 + +* ### 头等函数（first-class function） +Scala支持 _头等函数_ ，意味着可以通过函数字面量语法来表达函数。如：`(x: Int) => x + 1`，并且函数可由对象来表达，叫做[函数值](#函数值function-value)。 + +* ### for推解式（for comprehension） +_for推解式_ 是[for表达式](#for表达式for-expression)的一种，一般用来创建新的集合。对`for`推解式的每次迭代，[yield](#产生yield)子句都会定义新集合的一个元素。比如：`for (i <- (0 until 2); j <- (2 until 4)) yield (i, j)`将返回集合`Vector((0,2), (0,3), (1,2), (1,3))`。 + +* ### for表达式（for expression） +_for表达式_ 要么是个[for循环](#for循环for-loop)，可以迭代一个或多个集合，要么是个[for推解式](#for推解式for-comprehension)，可以从一个或多个集合的元素中推解出一个新的集合。`for`表达式建于[生成器](#生成器generator)、[过滤器](#过滤器filter)、变量定义和[yield](#产生yield)子句（针对[for推解式](#for推解式for-comprehension)）基础之上， + +* ### for循环（for loop） +_for循环_ 是[for表达式](#for表达式for-expression)的一种，一般用来循环迭代一个或多个集合。因为`for`循环返回unit，所以经常被用来产生副作用。比如：`for (i <- 0 until 100) println(i)`打印数字0到99。 + +* ### 自由变量（free variable） +一个表达式的 _自由变量_ 指的是在表达式中使用但不定义在其中的变量。例如，在函数字面量表达式`(x: Int) => (x, y)`中，变量`x`和`y`都被用到了，但只有`y`是自由变量，因其未在表达式中定义。 + +* ### 函数（function） +_函数_ 可通过一列实参来[调用](#调用invoke)然后产生结果。函数一般具有参数列表、函数体和结果类型。作为类、特质或单例对象的函数叫做[方法](#方法method)。定义在其他函数内部的函数叫做[局部函数](#局部函数local-function)。结果类型为`Unit`的函数叫做[过程](#过程procedure)。源码里面的匿名函数叫做[函数字面量](#函数字面量function-literal)。运行时，函数字面量被实例化为对象，叫做[函数值](#函数值function-value)。 + +* ### 函数字面量（function literal） +在Scala源码中的无名函数，通过函数字面量语法来特别对待。比如：`(x: Int, y: Int) => x + y`。 + +* ### 函数值（function value） +可以像其他函数一样被调用的函数对象。函数值的类一般是继承了`scala`包中的`FunctionN`（比如`Function0`，`Function1`等）这类特质的其中之一，且在源码中常通过[函数字面量](#函数字面量function-literal)语法来表示。当函数值的apply方法被调用时就说这个函数值被调用。捕获自由变量的函数值为[闭包](#闭包closure)。 + +* ### 函数式风格（functional style） +_函数式风格_ 编程注重函数和求值结果而非操作发生的顺序。这种风格的特征是可传递函数值给循环方法、不可变数据、方法无副作用，是像Haskell和Erlang等这些语言的主要范式，与[命令式风格](#命令式风格imperative-style)相对应。 + +* ### 生成器（generator） +生成器在[for表达式](#for表达式for-expression)中定义一个命名的val变量并赋予其一系列值。比如：`for(i <- 1 to 10)`的生成器是"`i <- 1 to 10`"，`<-`右边的值是[生成器表达式](#生成器表达式generator-expression)。 + +* ### 生成器表达式（generator expression） +生成器表达式在[for表达式](#for表达式for-expression)中生成一些列值。比如：`for(i <- 1 to 10)`的生成器表达式是"`1 to 10`"。 + +* ### 泛型类（generic class） +带有类型参数的类。例如，因`scala.List`带一类型参数，故其为泛型类。 + +* ### 泛型特质（generic trait） +带有类型参数的特质。例如，因`scala.collection.Set`带一类型参数，故其为泛型特质。 + +* ### 守卫（guard） +参见[过滤器](#过滤器filter). + +* ### 辅助函数（helper function） +目的是为一个或多个其他邻近函数提供服务的函数。辅助函数常实现为局部函数。 + +* ### 辅助方法（helper method） +作为类成员的[辅助函数](#辅助函数helper-function)。辅助方法常为私有方法。 + +* ### 不可变（immutable） +若对象的值在任何对客户端可见的方式下创建后不会被修改则称对象是 _不可变_ 的。对象既可以是不可变的，也可以是可变的。 + +* ### 命令式风格（imperative style） +_命令式风格_ 编程强调严谨的操作序列以令效用能在正确的顺序发生。这种风格的特征是循环迭代、适当变更数据、方法有副作用，是像C, C++, C#和Java等这些语言的主要范式，与[函数式风格](#函数式风格functional-style)相对应。 + +* ### 初始化（initialize） +变量在Scala源码中被定义时，必须用对象对其进行初始化。 + +* ### 实例（instance） +_实例_ ，或叫类实例，是个对象，是个仅在运行时存在的概念 + +* ### 实例化（instantiate） +_实例化_ 类是根据类创建一个新对象，是仅在运行时发生的动作。 + +* ### 不变性（invariant） +_不变性_ 用在两个地方。首先在数据结构组织良好的情况下它可以表示某个属性始终为真。比如，若排序二叉树具有右子节点，则其各节点就会在其右子节点前完成排序，这就属于排序二叉树的不变性。其次有时不变性也作为非协变的同义词，如："类`Array`在类型参数上具备不变性"。 + +* ### 调用（invoke） +在实参上 _调用_ 方法、函数或闭包，意即其方法体会在指定实参上执行。 + +* ### Java虚拟机（JVM） +_JVM_ 是Java虚拟机(#runtime)的缩写，或叫[运行时](#运行时runtime)，是运行Scala程序的宿主。 + +* ### 字面量（literal） +`1`，`"One"`，和`(x: Int) => x + 1`是 _字面量_ 的例子，字面量是描述对象的便捷方式，便捷在这种方式正好反映了所创建对象的结构。 + +* ### 局部函数（local function） +_局部函数_ 是块内`def`定义的，作为对比，同为`def`定义的作为类、特质或单例对象的成员则被称作[方法](#方法method)。 + +* ### 局部变量（local variable） +_局部变量_ 是块内`val`或`var`定义的。尽管函数参数和[局部变量](#局部变量local-variable)类似，但并不叫局部变量，而是去掉"局部"直接叫"参数"或"变量"。 + +* ### 成员（member） +_成员_ 是类、特质或单例对象模板中被命名的元素。成员可通过所有者名称，点及其简名访问。例如，定义在类的最顶层字段和方法是这个类的成员。定义在类中的特质是包围它的类的成员。类中通过type关键字定义的类型是这个类的成员。类是其定义所在的包的成员。相比之下，局部变量或局部函数就不是包围他们的块的成员。 + +* ### 消息（message） +Actor是通过给彼此之间发送 _消息_ 来进行通信的。发送消息不会打断接收者正在处理的事情，接收者可一直等到当前活动结束且其不变性被重建之后。 + +* ### 元编程（meta-programming） +元编程程序是指其输入是其自身程序的程序。编译器都是元程序，像`scaladoc`这样的工具也是。要用注解做任何事都需要元编程程序。 + +* ### 方法（method） +_方法_ 就是类、特质或单例对象的成员函数。 + +* ### 混入（mixin） +_混入_ 就是特质用在混入组合时的名称。换言之，在"`trait Hat`"里面，`Hat`仅为特质，而"`new Cat extends AnyRef with Hat`"里面的`Hat`就可叫混入。用作动词时，"混"和"入"（"mix in"）是两个词。比如，可 _混_ 特质 _入_ 至类或其他特质。 + +* ### 混入组合（mixin composition） +把特质混入类或其他特质的过程。_混入组合_ 与传统的多重继承不同之处在于父级引用的类型不是在特质定义时已知的，而是在每次特质每次混入到类或其他特质时才被重新确定。 + +* ### 修饰符（modifier） +用来以某种方式限定类、特质、字段或方法等的定义的关键字。比如，`private`修饰符表明被定义的类、特质、字段或方法是私有的。 + +* ### 多重定义（multiple definitions） +通过使用类似这样的语法`val v1, v2, v3 = exp`，同一个表达式根据 _多重定义_ 概念可被赋值给多个变量。 + +* ### 非协变（nonvariant） +类或特质的类型参数默认是 _非协变_ 的，故而参数变化并不会子类化相应的类或特质。比如，因类`Array`非协变于其类型参数，故`Array[String]`既非`Array[Any]`之子类，亦非其超类。 + +* ### 操作（operation） +在Scala中，每个 _操作_ 都是一个方法调用。方法也可以 _操作符符号_ 的方式被调用，像在`b + 2`里面符号`+`就是一个 _操作符_。 + +* ### 参数（parameter） +函数可带有零至多个 _参数_，每个参数都有名称和类型。参数与实参之间的区别在于函数调用时实参指向具体的对象，参数则是指向这些传入实参的变量。 + +* ### 无参函数（parameterless function） +不带参数的函数，其定义时没有任何空括号。无参函数可不带括号调用，这种方式符合[统一访问原则](#统一访问原则uniform-access-principle)，就是在客户端不改变任何代码的情况下把`def`改成`val`。 + +* ### 无参方法（parameterless method） +_无参方法_ 就是作为类、特质或单例对象成员的无参函数。 + +* ### 参数化字段（parametric field） +定义为类参数的字段。 + +* ### 偏应用函数（部分应用函数）（partially applied function） +用在表达式中，省掉某些参数的函数。例如：若函数`f`的类型为`Int => Int => Int`，则`f`和`f(1)`就是 _偏应用函数_。 + +* ### 路径依赖类型（path-dependent type） +类似`swiss.cow.Food`的一种类型，`swiss.cow`部分形成一个对象引用的路径。这种类型的含义对于用来访问它的路径是敏感的，比如，`swiss.cow.Food`和`fish.Food`这两个是不同的类型。 + +* ### 模式（pattern） +在`match`表达式的某个备选项中，_模式_ 跟在`case`关键字后，先于 _模式守卫_ 或`=>`符号二者之一。 + +* ### 模式守卫（pattern guard） +在`match`表达式的某个备选项中，_模式守卫_ 可跟在某个[模式](#模式pattern)后面。比如，"`case x if x % 2 == 0 => x + 1`"中的模式守卫为"`if x % 2 == 0`"。带有模式守卫的备选项（case）仅当其模式匹配了并且模式守卫为真的时候才会被选中。 + +* ### 断言（predicate） +断言是结果类型为`Boolean`的函数。 + +* ### 主构造器（primary constructor） +类的主要构造器，会调用超类构造器，如果有必要，也会初始化字段进行传值，并且会执行类的花括号内定义的的顶层（top-level）代码。字段仅由不传给超类构造器的值参数做初始化，那些类构造体内因未用到而被优化掉的除外。 + +* ### 过程（procedure） +_过程_ 是结果类型为`Unit`的函数，其存在的理由仅为产生副作用。 + +* ### 可重新赋值（reassignable） +变量可以是可重新赋值的，也可以不是可重新赋值的。`var`是可重新赋值的，而`val`则不是。 + +* ### 递归的（recursive） +若函数可调用自身就说它是 _递归的_。若函数调用自身的唯一位置是函数的最后一个表达式，则函数是[尾递归](#尾递归tail-recursive)的。 + +* ### 引用（reference） +_引用_ 是指针的Java抽象，可唯一确定存在JVM堆中的对象。引用类型变量持有对象的引用，因为引用类型（`AnyRef`的实例）是存在JVM堆上的Java对象实现的。相比之下，值类型变量有时会持有一个（装箱类型的）引用，也有时（当对象表示基础类型值的时候）不会。一般说来，Scala变量[指向](#指向refers)对象。术语"指向"比"持有引用"更加抽象。如果类型为`scala.Int`的变量当前代表Java基础类型`int`的值，则这个变量仍然指向`Int`对象，但并不涉及任何引用。 + +* ### 引用相等性（reference equality） +_引用相等性_ 意思是两个引用指向同一个Java对象。引用相等性仅针对引用类型有意义，是可以通过调用`AnyRef`中的`eq`来确定的（在Java程序中，引用相等性通过在Java[引用类型](#引用类型reference-type)上调用`==`来确定）。 + +* ### 引用类型（reference type） +_引用类型_ 是`AnyRef`的子类。在运行时，引用类型的实例常驻JVM堆中。 + +* ### 引用透明（referential transparency） +独立于临时上下文且无副作用的函数属性。对于特定输入，引用透明函数的调用可由其结果替换而不改变程序语义。 + +* ### 指向（refers） +运行的Scala程序中的变量常 _指向_ 某个对象。变量即使被赋为`null`，概念上也是指向`Null`对象。在运行时，对象可由Java对象或基础类型值来实现，不过Scala允许程序员在更高层次抽象代码以他们设想的方式运行。参见[引用](#引用reference). + +* ### 精化类型（refinement type） +通过提供基础类型及其构造体花括号内若干成员而形成的类型。花括号内的成员精细化了基础类型所体现的类型。比如，"食草动物"（animal that eats grass）的类型为`Animal { type SuitableFood = Grass }`。 +A type formed by supplying a base type a number of members inside curly braces. The members in the curly braces refine the types that are present in the base type. For example, the type of “animal that eats grass” is `Animal { type SuitableFood = Grass }`. + +* ### 结果（result） +Scala程序中的表达式会产生 _结果_。Scala中的每个表达式的结果都是对象。 + +* ### 结果类型（result type） +方法的 _结果类型_ 是调用方法所产生的值的类型。（在Java中，这个概念被称为返回类型） + +* ### 返回（return） +Scala程序中的函数会 _返回_ 值，可把这个值叫做函数的[结果](#结果result)。也可以说函数 _结果是_ 某个值。Scala中的每个函数结果都是一个对象。 + +* ### 运行时（runtime） +正在运行Scala程序的宿主Java虚拟机，或宿主[JVM](#java虚拟机jvm)。运行时这个概念包含了Java虚拟机规范中定义的虚拟机以及Java API和标准Scala API的运行时库。在运行时的这个阶段，意味着程序正在运行中，与编译时是相对的概念。 + +* ### 运行时类型（runtime type） +对象在运行时的类型。相比之下，[静态类型](#静态类型static-type)指的是表达式在编译时的类型。多数运行时类型都是无类型参数的裸类，比如，`"Hi"`的运行时类型是`String`，`(x: Int) => x + 1`的运行时类型是`Function1`。运行时类型可通过`isInstanceOf`来检测。 + +* ### 脚本（script） +包含顶层定义和语句，可直接通过`scala`命令来跑而无需显式编译的文件就是脚本，脚本结尾必须是表达式，而不能是定义。 + +* ### 选择器（selector） +`match`表达式中被匹配的值。比如，在"`s match { case _ => }`"中，选择器是`s`。 + +* ### 自身类型（self type） +特质的 _自身类型_ 是特质中用到的接收者`this`的假想类型。任何混入特质的具体类必须要确保其类型符合特质的自身类型。自身类型常被用来把大类分解为若干个特质（[Programming in Scala](https://www.artima.com/shop/programming_in_scala)第29章有述）。 + +* ### 半结构化数据（semi-structured data） +XML数据就是半结构化的，因其相比于普通的二进制文件或文本文件更加结构化，而又不像编程语言的数据结构具备完全结构化。 + +* ### 序列化（serialization） +可把对象 _序列化_ 成字节流，以便将其保存至文件或通过网络传输。之后可对字节流进行 _反序列化_ （可发生在不同计算机上）来获取和原始被序列化的对象一样的对象。 + +* ### 遮掩（shadow） +局部变量的重新声明会 _遮掩_ 作用域内相同名称的变量声明。 + +* ### 签名（signature） +_签名_ 是[类型签名](#类型签名type-signature)的简写。 + +* ### 单例对象（singleton object） +由object关键字定义的对象。每个单例对象有且仅有一个实例。与某个类共享名称且与这个类定义在同一源文件中的单例对象，叫这个类的[伴生对象](#伴生对象companion-object)，类则叫单列对象的[伴生类](#伴生类companion-class)。无伴随类的单例对象叫[独立对象](#独立对象standalone-object)。 + +* ### 独立对象（standalone object） +没有[伴生类](#伴生类companion-class)的[单例对象](#单例对象singleton-object)。 + +* ### 语句（statement） +指的是表达式、定义或包导入等这些可放到Scala源码的模板或块中的东西。 + +* ### 静态类型（static type） +参见[类型](#类型type)。 + +* ### 结构类型（structural type） +也是一种[精化类型](#精化类型refinement-type)，只是精化的目标是未在基类型中的成员。比如`{ def close(): Unit }`就是结构类型，因其基类型是`AnyRef`，而`AnyRef`并无名为`close`的成员。 + +* ### 子类（subclass） +一个类是其所有[超类](#超类superclass)和[超特质](#超特质supertrait)的 _子类_。 + +* ### 子特质（subtrait） +一个特质是其所有[超特质](#超特质supertrait)的 _子特质_。 + +* ### 子类型（subtype） +Scala编译器允许任何类型在需要该类型的地方使用其 _子类型_ 作为替代。对不带类型参数的类和特质来说，子类型的关系会反映子类的关系。比如，若类`Cat`是抽象类`Animal`的子类，且也不带类型参数，则类型`Cat`就是类型`Animal`的子类型。同样，若特质`Apple`是特质`Fruit`的子特质且无类型参数，则类型`Apple`就是类型`Fruit`的子类型。而对于带有类型参数的类和特质来说，协变就起作用了。比如，由于抽象类`List`被声明为在其长类型参数上是协变的（例，`List`被声明为`List[+A]`），`List[Cat]`是`List[Animal]`的子类型，`List[Apple]`是`List[Fruit]`的子类型。尽管这些类型的类都是`List`，但其子类型的关系依旧是存在的。对比来看，因为`Set`未被声明在其类型参数上是协变的（例，`Set`被声明为`Set[A]`，不带加号），所以`Set[Cat]`并不是`Set[Animal]`的子类型。子类型应该正确实现其超类型的契约，以便应用里氏替换原则（Liskov Substitution Principle），不过编译器仅会在类型检查级别核验此属性。 + +* ### 超类（superclass） +一个类的 _超类_ 包括其直接超类，其直接超类的直接超类，等等一直到`Any`。 + +* ### 超特质（supertrait） +类或特质的 _超特质_，如果有的话，就包括所有直接混入类或特质或其任意超类的特质，以及这些特质的所有超特质。 + +* ### 超类型（supertype） +类型是其所有子类型的 _超类型_。 + +* ### 合成类（synthetic class） +合成类是编译器自动生成的而不是程序员手写的。 + +* ### 尾递归（tail recursive） +函数是 _尾递归_ 的，仅当函数调用自身的地方是函数的最后一条操作。 + +* ### 目标类型化（target typing） +_目标类型化_ 是参考所需类型来进行类型推导的一种形式。比如在`nums.filter((x) => x > 0)`中，Scala编译器能推导出`x`的类型是`nums`的元素类型，因为`filter`方法会在`nums`的每个元素上调用函数。 + +* ### 模板（template） +_模板_ 是类、特质或单例对象定义体，它定义了类、特质或对象的类型签名，行为以及初始状态。 + +* ### 特质（trait） +_特质_ 通过`trait`关键字定义，是像抽象类一样不带任何值参数，并且可通过被称为[混入组合](#混入组合mixin-composition)的过程"混入到"类或其他特质。当某个特质被混入到其他类或特质，它就被叫做[混入](#混入mixin)。特质可通过一个或多个类型参数化。用类型来参数化后，特质就形成了类型。比如，`Set`是带有单类型参数的特质，而`Set[Int]`却是一个类型。`Set`也被说成是类型`Set[Int]`的"特质"。 + +* ### 类型（type） +Scala程序中每个变量和表达式都有编译时确定的 _类型_。类型可以在运行时限定变量能指向的值和表达式所能产生的值。如果有必要从对象的[运行时类型](#运行时类型runtime-type)的角度对变量和表达式的类型进行区分的话，他们也被称为 _静态类型_。换句话说，"类型"这个词本身意味着静态类型。类型与类是区分开的因为带有类型参数的类可以构成许多类型。比如，`List`是类不是类型，`List[T]`则是一个带有自由类型参数的类型，`List[Int]`和`List[String]`也是类型（称为实类型因为他们没有自由类型参数）。类型可以有"[类](#类class)"或"[特质](#特质trait)"，比如类型`List[Int]`的类是`List`，类型`Set[String]`的特质是`Set`。 + +* ### 类型约束（type constraint） +有些[注解](#注解annotation)是 _类型约束_，意味着他们会对类型能够包含的取值增加额外的限制或约束。比如，`@positive`可以是类型`Int`的类型约束，用来限制32位整型的取值为正的整数。类型约束虽然不会被标准Scala编译器检查，但相应的必须可被额外的工具或编译器插件检查。 + +* ### 类型构造器（type constructor） +带类型参数的类或特质。 + +* ### 类型参数（type parameter） +必须被填入类型的泛型类或泛型方法的参数。比如，类`List`定义为"`class List[T] { . . . `"，对象`Predef`的一个成员方法`identity`定义为"`def identity[T](x:T) = x`"，二者定义中的`T`就是类型参数。 + +* ### 类型签名（type signature） +方法的 _类型签名_ 包括名称，参数（如果有的话）的数量、顺序和类型，以及结果类型。类、特质或单例对象的类型签名包括名称，所有成员和构造器的类型签名，及其声明的继承和混入关系。 + +* ### 统一访问原则（uniform access principle） +_统一访问原则_ 指的是变量和无参函数应以相同的语法来访问。Scala通过不允许在无参函数的调用点放置括号来支持该原则。这样的话，无参函数定义就可以改成`val`而不影响客户端代码，_反之亦然_。 + +* ### 不可达（unreachable） +在Scala层面，对象可以是 _不可达_ 的，此时其所占据的内存可被运行时回收。不可达并不一定意味着未被引用。引用类型（`AnyRef`的实例）被实现为驻于JVM堆上的对象。当引用类型的实例不可达后，它也确实不被引用了，且可被垃圾回收。值类型（`AnyVal`的实例）可被实现为驻于堆中的基础类型值或Java包装类型实例（如`java.lang.Integer`）。值类型实例可在指向他们的变量的整个生命周期内被装箱（从基础类型值转成包装类型对象）或拆箱（从包装类型对象转成基础类型值）。若表现为JVM堆上的包装类型对象的值类型实例不可达，那就确实不会被引用并且可被垃圾回收。但是若正在表现为基础类型值的值类型不可达，则其仍可被引用，因为此时它并不会以作为对象驻于JVM堆上。运行时可回收不可达对象所占据的内存，但是假如一个Int在运行时被实现为Java基础类型int，在一个运行中的方法的栈帧上占据了一些内存，则这个对象的内存将在方法运行完成且栈帧弹出时才被回收。引用类型的内存，比如`Strings`，可在不可达之后由JVM的垃圾收集器回收。 + +* ### 未引用（unreferenced） +参见[不可达](#不可达unreachable)。 + +* ### 值（value） +Scala中的任何计算或表达式的结果都是一个 _值_，而Scala中的每个值都是一个对象。值这个术语本质上是指对象在内存中（在JVM堆或栈上）的镜像。 + +* ### 值类型（value type） +_值类型_ 是`AnyVal`的任意子类，像`Int`，`Double`或`Unit`。该术语具有Scala源码级别的意味。在运行时，对应于Java基础类型的值类型实例可由基础类型值或包装类型实例来实现，比如`java.lang.Integer`。在值类型实例的整个生命周期内，运行时可将其在基础类型和包装类型间来回转换（如，对其装箱和拆箱）。 + +* ### 变量（variable） +指向对象的命名实体。变量要么是`val`，要么是 `var`，`val`变量和`var`变量在定义时都必须被初始化，但仅`var`变量可被重新赋值来指向不同对象。 + +* ### 型变（variance） +类或特质的类型参数可用 _型变_ 标号来做标记，即[协变](#协变covariant)（+）或[逆变](#逆变contravariant)（-）。这样的型变标号表明了泛型类或特质的子类化是如何开展的，比如，泛型类`List`在其类型参数上是协变的，因此`List[String]`就是`List[Any]`的子类型。默认情况下，即缺少标号`+`或`-`的类型参数是[非协变](#非协变nonvariant)的。 + +* ### 产生（yield） +表达式可以 _产生_ 结果。`yield`关键字指定了[for推解式](#for推解式for-comprehension)的结果。 diff --git a/_zh-cn/index.md b/_zh-cn/index.md new file mode 100644 index 0000000000..53df7a316e --- /dev/null +++ b/_zh-cn/index.md @@ -0,0 +1,110 @@ +--- +layout: landing-page +language: zh-cn + +title: 学习 Scala +namespace: root +discourse: true +partof: documentation +more-resources-label: 更多资源 +redirect_from: + - /scala3/ + - /scala3/index.html + +sections: + - title: "第一步..." + links: + - title: "快速开始" + description: "在电脑上安装 Scala 然后开始写些 Scala 代码吧！" + icon: "fa fa-rocket" + link: /getting-started.html + - title: "scala之旅" + description: "核心语言特性简介" + icon: "fa fa-flag" + link: /zh-cn/tour/tour-of-scala.html + - title: "Scala 3 册子" + description: "通过一系列小课程来学习 Scala。" + icon: "fa fa-book" + link: /zh-cn/scala3/book/introduction.html + - title: "Scala 工具箱" + description: "发送 HTTP 请求，写文件，运行进程，解析 JSON... " + icon: "fa fa-toolbox" + link: /toolkit/introduction.html + - title: "在线课程" + description: "新手和有经验的程序员在 MOOCS 学习 Scala。" + icon: "fa fa-cloud" + link: /online-courses.html + - title: 书籍 + description: "有关 Scala 的印刷和数字化的书籍。" + icon: "fa fa-book" + link: /books.html + - title: 教程 + description: "通过一系列步骤，手把手教你创建 Scala 应用。" + icon: "fa fa-tasks" + link: /tutorials.html + + - title: "回归用户" + links: + - title: "api" + description: "各个 Scala 版本的 api 文档" + icon: "fa fa-file-alt" + link: /api/all.html + - title: "导引和总览" + description: "涵盖 Scala 各种特性的深度分析文档" + icon: "fa fa-database" + link: /zh-cn/overviews/index.html + - title: "风格引导" + description: "深度指导如何写出地道的 Scala 代码" + icon: "fa fa-bookmark" + link: /style/index.html + - title: "速查" + description: "包含 Scala 基础语法的速查手册" + icon: "fa fa-list" + link: /zh-cn/cheatsheets/index.html + - title: "Scala 常见问题" + description: "Scala 语言特性的常见问题及答案。" + icon: "fa fa-question-circle" + link: /tutorials/FAQ/index.html + - title: "语言规范 v2.x" + description: "Scala 2 正式的语言规范。" + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/2.13/ + - title: "语言规范 v3.x" + description: "Scala 3 正式的语言规范。" + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/3.4/ + - title: "Scala 3 语言参考" + description: "Scala 3 语言参考" + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference + + - title: "探索 Scala 3" + links: + - title: "迁移指引" + description: "一份帮你从 Scala 2 迁移到 Scala 3 的指引。" + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "Scala 3 中的新东西" + description: "Scala 3 中令人兴奋的新特性概览" + icon: "fa fa-star" + link: /zh-cn/scala3/new-in-scala3.html + - title: "Scala 3 全新的 Scaladoc" + description: "Scaladoc 新特性重点介绍" + icon: "fa fa-star" + link: /scala3/scaladoc.html + - title: "演讲" + description: "可在线观看的关于 Scala 3 的演讲" + icon: "fa fa-play-circle" + link: /scala3/talks.html + + - title: "Scala 进展" + links: + - title: "Scala 改进过程" + description: "描述涉及语言的过程，和所有 Scala 改进提案(SIPs)的列表。" + icon: "fa fa-cogs" + link: /sips/index.html + - title: "成为 Scala OSS 贡献者" + description: "从头到尾：发现你如何帮助 Scala 开源生态系统。" + icon: "fa fa-code-branch" + link: /contribute/ +--- diff --git a/_zh-cn/overviews/collections/arrays.md b/_zh-cn/overviews/collections/arrays.md index 900dd0fa16..2debfa28ab 100644 --- a/_zh-cn/overviews/collections/arrays.md +++ b/_zh-cn/overviews/collections/arrays.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 数组 - -discourse: false - partof: collections overview-name: Collections @@ -11,7 +8,7 @@ num: 10 language: zh-cn --- -在Scala中，[数组](http://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html)是一种特殊的collection。一方面，Scala数组与Java数组是一一对应的。即Scala数组Array[Int]可看作Java的Int[]，Array[Double]可看作Java的double[]，以及Array[String]可看作Java的String[]。但Scala数组比Java数组提供了更多内容。首先，Scala数组是一种泛型。即可以定义一个Array[T]，T可以是一种类型参数或抽象类型。其次，Scala数组与Scala序列是兼容的 - 在需要Seq[T]的地方可由Array[T]代替。最后，Scala数组支持所有的序列操作。这里有个实际的例子： +在Scala中，[数组](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html)是一种特殊的collection。一方面，Scala数组与Java数组是一一对应的。即Scala数组Array[Int]可看作Java的Int[]，Array[Double]可看作Java的double[]，以及Array[String]可看作Java的String[]。但Scala数组比Java数组提供了更多内容。首先，Scala数组是一种泛型。即可以定义一个Array[T]，T可以是一种类型参数或抽象类型。其次，Scala数组与Scala序列是兼容的 - 在需要Seq[T]的地方可由Array[T]代替。最后，Scala数组支持所有的序列操作。这里有个实际的例子： scala> val a1 = Array(1, 2, 3) a1: Array[Int] = Array(1, 2, 3) diff --git a/_zh-cn/overviews/collections/concrete-immutable-collection-classes.md b/_zh-cn/overviews/collections/concrete-immutable-collection-classes.md index f7ae54da96..70575300d5 100644 --- a/_zh-cn/overviews/collections/concrete-immutable-collection-classes.md +++ b/_zh-cn/overviews/collections/concrete-immutable-collection-classes.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 具体的不可变集实体类 - -discourse: false - partof: collections overview-name: Collections @@ -16,7 +13,7 @@ Scala中提供了多种具体的不可变集类供你选择，这些类(maps, se ## List（列表） -列表[List](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/List.html)是一种有限的不可变序列式。提供了常数时间的访问列表头元素和列表尾的操作，并且提供了常数时间的构造新链表的操作，该操作将一个新的元素插入到列表的头部。其他许多操作则和列表的长度成线性关系。 +列表[List](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/List.html)是一种有限的不可变序列式。提供了常数时间的访问列表头元素和列表尾的操作，并且提供了常数时间的构造新链表的操作，该操作将一个新的元素插入到列表的头部。其他许多操作则和列表的长度成线性关系。 List通常被认为是Scala中最重要的数据结构，所以我们在此不必过于赘述。版本2.8中主要的变化是，List类和其子类::以及其子对象Nil都被定义在了其逻辑上所属的scala.collection.immutable包里。scala包中仍然保留了List，Nil和::的别名，所以对于用户来说可以像原来一样访问List。 @@ -24,7 +21,7 @@ List通常被认为是Scala中最重要的数据结构，所以我们在此不 ## Stream（流） -流[Stream](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/Stream.html)与List很相似，只不过其中的每一个元素都经过了一些简单的计算处理。也正是因为如此，stream结构可以无限长。只有那些被要求的元素才会经过计算处理，除此以外stream结构的性能特性与List基本相同。 +流[Stream](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/Stream.html)与List很相似，只不过其中的每一个元素都经过了一些简单的计算处理。也正是因为如此，stream结构可以无限长。只有那些被要求的元素才会经过计算处理，除此以外stream结构的性能特性与List基本相同。 鉴于List通常使用 `:: `运算符来进行构造，stream使用外观上很相像的`#::`。这里用一个包含整数1，2和3的stream来做一个简单的例子： @@ -49,7 +46,7 @@ List通常被认为是Scala中最重要的数据结构，所以我们在此不 对于只需要处理数据结构头结点的算法来说，List非常高效。可是相对于访问、添加和删除List头结点只需要固定时间，访问和修改头结点之后元素所需要的时间则是与List深度线性相关的。 -向量[Vector](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/Vector.html)是用来解决列表(list)不能高效的随机访问的一种结构。Vector结构能够在“更高效”的固定时间内访问到列表中的任意元素。虽然这个时间会比访问头结点或者访问某数组元素所需的时间长一些，但至少这个时间也是个常量。因此，使用Vector的算法不必仅是小心的处理数据结构的头结点。由于可以快速修改和访问任意位置的元素，所以对Vector结构做写操作很方便。 +向量[Vector](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/Vector.html)是用来解决列表(list)不能高效的随机访问的一种结构。Vector结构能够在“更高效”的固定时间内访问到列表中的任意元素。虽然这个时间会比访问头结点或者访问某数组元素所需的时间长一些，但至少这个时间也是个常量。因此，使用Vector的算法不必仅是小心的处理数据结构的头结点。由于可以快速修改和访问任意位置的元素，所以对Vector结构做写操作很方便。 Vector类型的构建和修改与其他的序列结构基本一样。 @@ -82,7 +79,7 @@ Vector结构通常被表示成具有高分支因子的树（树或者图的分 ## Immutable stacks（不可变栈） -如果您想要实现一个后入先出的序列，那您可以使用[Stack](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/Stack.html)。您可以使用push向栈中压入一个元素，用pop从栈中弹出一个元素，用top查看栈顶元素而不用删除它。所有的这些操作都仅仅耗费固定的运行时间。 +如果您想要实现一个后入先出的序列，那您可以使用[Stack](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/Stack.html)。您可以使用push向栈中压入一个元素，用pop从栈中弹出一个元素，用top查看栈顶元素而不用删除它。所有的这些操作都仅仅耗费固定的运行时间。 这里提供几个简单的stack操作的例子： @@ -101,7 +98,7 @@ Vector结构通常被表示成具有高分支因子的树（树或者图的分 ## Immutable Queues（不可变队列） -[Queue](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/Queue.html)是一种与stack很相似的数据结构，除了与stack的后入先出不同，Queue结构的是先入先出的。 +[Queue](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/Queue.html)是一种与stack很相似的数据结构，除了与stack的后入先出不同，Queue结构的是先入先出的。 这里给出一个创建空不可变queue的例子： @@ -145,7 +142,7 @@ Range类的空间复杂度是恒定的，因为只需要三个数字就可以定 ## Hash Tries -Hash try是高效实现不可变集合和关联数组(maps)的标准方法，[immutable.HashMap](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/HashMap.html)类提供了对Hash Try的支持。从表现形式上看，Hash Try和Vector比较相似，都是树结构，且每个节点包含32个元素或32个子树，差别只是用不同的hash code替换了指向各个节点的向量值。举个例子吧：当您要在一个映射表里找一个关键字，首先需要用hash code值替换掉之前的向量值；然后用hash code的最后5个bit找到第一层子树，然后每5个bit找到下一层子树。当存储在一个节点中所有元素的代表他们当前所在层的hash code位都不相同时，查找结束。 +Hash try是高效实现不可变集合和关联数组(maps)的标准方法，[immutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/HashMap.html)类提供了对Hash Try的支持。从表现形式上看，Hash Try和Vector比较相似，都是树结构，且每个节点包含32个元素或32个子树，差别只是用不同的hash code替换了指向各个节点的向量值。举个例子吧：当您要在一个映射表里找一个关键字，首先需要用hash code值替换掉之前的向量值；然后用hash code的最后5个bit找到第一层子树，然后每5个bit找到下一层子树。当存储在一个节点中所有元素的代表他们当前所在层的hash code位都不相同时，查找结束。 Hash Try对于快速查找和函数式的高效添加和删除操作上取得了很好的平衡，这也是Scala中不可变映射和集合采用Hash Try作为默认实现方式的原因。事实上，Scala对于大小小于5的不可变集合和映射做了更进一步的优化。只有1到4个元素的集合和映射被在现场会被存储在一个单独仅仅包含这些元素（对于映射则只是包含键值对）的对象中。空集合和空映射则视情况不同作为一个单独的对象，空的一般情况下就会一直空下去，所以也没有必要为他们复制一份拷贝。 @@ -153,7 +150,7 @@ Hash Try对于快速查找和函数式的高效添加和删除操作上取得了 红黑树是一种平衡二叉树，树中一些节点被设计成红节点，其余的作为黑节点。同任何平衡二叉树一样，对红黑树的最长运行时间随树的节点数成对数(logarithmic)增长。 -Scala隐含的提供了不可变集合和映射的红黑树实现，您可以在[TreeSet](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/TreeSet.html)和[TreeMap](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/TreeMap.html)下使用这些方法。 +Scala隐含的提供了不可变集合和映射的红黑树实现，您可以在[TreeSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/TreeSet.html)和[TreeMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/TreeMap.html)下使用这些方法。 ## scala> scala.collection.immutable.TreeSet.empty[Int] res11: scala.collection.immutable.TreeSet[Int] = TreeSet() @@ -164,7 +161,7 @@ Scala隐含的提供了不可变集合和映射的红黑树实现，您可以在 ## Immutable BitSets（不可变位集合） -[BitSet](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/BitSet.html)代表一个由小整数构成的容器，这些小整数的值表示了一个大整数被置1的各个位。比如说，一个包含3、2和0的bit集合可以用来表示二进制数1101和十进制数13. +[BitSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/BitSet.html)代表一个由小整数构成的容器，这些小整数的值表示了一个大整数被置1的各个位。比如说，一个包含3、2和0的bit集合可以用来表示二进制数1101和十进制数13. BitSet内部的使用了一个64位long型的数组。数组中的第一个long表示整数0到63，第二个表示64到27，以此类推。所以只要集合中最大的整数在千以内BitSet的压缩率都是相当高的。 @@ -181,7 +178,7 @@ BitSet操作的运行时间是非常快的。查找测试仅仅需要固定时 ## List Maps -[ListMap](http://www.scala-lang.org/api/2.10.0/scala/collection/immutable/ListMap.html)被用来表示一个保存键-值映射的链表。一般情况下，ListMap操作都需要遍历整个列表，所以操作的运行时间也同列表长度成线性关系。实际上ListMap在Scala中很少使用，因为标准的不可变映射通常速度会更快。唯一的例外是，在构造映射时由于某种原因，链表中靠前的元素被访问的频率大大高于其他的元素。 +[ListMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/immutable/ListMap.html)被用来表示一个保存键-值映射的链表。一般情况下，ListMap操作都需要遍历整个列表，所以操作的运行时间也同列表长度成线性关系。实际上ListMap在Scala中很少使用，因为标准的不可变映射通常速度会更快。唯一的例外是，在构造映射时由于某种原因，链表中靠前的元素被访问的频率大大高于其他的元素。 scala> val map = scala.collection.immutable.ListMap(1->"one", 2->"two") map: scala.collection.immutable.ListMap[Int,java.lang.String] = diff --git a/_zh-cn/overviews/collections/concrete-mutable-collection-classes.md b/_zh-cn/overviews/collections/concrete-mutable-collection-classes.md index 8b12f7e319..9464f466f4 100644 --- a/_zh-cn/overviews/collections/concrete-mutable-collection-classes.md +++ b/_zh-cn/overviews/collections/concrete-mutable-collection-classes.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 具体的可变容器类 - -discourse: false - partof: collections overview-name: Collections @@ -16,7 +13,7 @@ language: zh-cn ## Array Buffers -一个[ArrayBuffer](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/ArrayBuffer.html)缓冲包含数组和数组的大小。对数组缓冲的大多数操作，其速度与数组本身无异。因为这些操作直接访问、修改底层数组。另外，数组缓冲可以进行高效的尾插数据。追加操作均摊下来只需常量时间。因此，数组缓冲可以高效的建立一个有大量数据的容器，无论是否总有数据追加到尾部。 +一个[ArrayBuffer](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/ArrayBuffer.html)缓冲包含数组和数组的大小。对数组缓冲的大多数操作，其速度与数组本身无异。因为这些操作直接访问、修改底层数组。另外，数组缓冲可以进行高效的尾插数据。追加操作均摊下来只需常量时间。因此，数组缓冲可以高效的建立一个有大量数据的容器，无论是否总有数据追加到尾部。 scala> val buf = scala.collection.mutable.ArrayBuffer.empty[Int] buf: scala.collection.mutable.ArrayBuffer[Int] = ArrayBuffer() @@ -29,7 +26,7 @@ language: zh-cn ## List Buffers -[ListBuffer](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/ListBuffer.html) 类似于数组缓冲。区别在于前者内部实现是链表， 而非数组。如果你想把构造完的缓冲转换为列表，那就用列表缓冲，别用数组缓冲。 +[ListBuffer](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/ListBuffer.html) 类似于数组缓冲。区别在于前者内部实现是链表， 而非数组。如果你想把构造完的缓冲转换为列表，那就用列表缓冲，别用数组缓冲。 scala> val buf = scala.collection.mutable.ListBuffer.empty[Int] buf: scala.collection.mutable.ListBuffer[Int] = ListBuffer() @@ -42,7 +39,7 @@ language: zh-cn ## StringBuilders -数组缓冲用来构建数组，列表缓冲用来创建列表。类似地，[StringBuilder](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/StringBuilder.html) 用来构造字符串。作为常用的类，字符串构造器已导入到默认的命名空间。直接用 new StringBuilder就可创建字符串构造器 ，像这样： +数组缓冲用来构建数组，列表缓冲用来创建列表。类似地，[StringBuilder](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/StringBuilder.html) 用来构造字符串。作为常用的类，字符串构造器已导入到默认的命名空间。直接用 new StringBuilder就可创建字符串构造器 ，像这样： scala> val buf = new StringBuilder buf: StringBuilder = @@ -55,17 +52,17 @@ language: zh-cn ## 链表 -链表是可变序列，它由一个个使用next指针进行链接的节点构成。它们的支持类是[LinkedList](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/LinkedList.html)。在大多数的编程语言中，null可以表示一个空链表，但是在Scalable集合中不是这样。因为就算是空的序列，也必须支持所有的序列方法。尤其是 `LinkedList.empty.isEmpty` 必须返回`true`，而不是抛出一个 `NullPointerException` 。空链表用一种特殊的方式编译： +链表是可变序列，它由一个个使用next指针进行链接的节点构成。它们的支持类是[LinkedList](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/LinkedList.html)。在大多数的编程语言中，null可以表示一个空链表，但是在Scalable集合中不是这样。因为就算是空的序列，也必须支持所有的序列方法。尤其是 `LinkedList.empty.isEmpty` 必须返回`true`，而不是抛出一个 `NullPointerException` 。空链表用一种特殊的方式编译： 它们的 next 字段指向它自身。链表像他们的不可变对象一样，是最佳的顺序遍历序列。此外，链表可以很容易去插入一个元素或链接到另一个链表。 ## 双向链表 -双向链表和单向链表相似，只不过它们除了具有 next字段外，还有一个可变字段 prev用来指向当前节点的上一个元素 。这个多出的链接的好处主要在于可以快速的移除元素。双向链表的支持类是[DoubleLinkedList](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/DoubleLinkedList.html). +双向链表和单向链表相似，只不过它们除了具有 next字段外，还有一个可变字段 prev用来指向当前节点的上一个元素 。这个多出的链接的好处主要在于可以快速的移除元素。双向链表的支持类是[DoubleLinkedList](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/DoubleLinkedList.html). ## 可变列表 -[MutableList](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/MutableList.html) 由一个单向链表和一个指向该链表终端空节点的指针构成。因为避免了贯穿整个列表去遍历搜索它的终端节点，这就使得列表压缩了操作所用的时间。MutableList 目前是Scala中[mutable.LinearSeq](http://www.scala-lang.org/api/2.10.0/scala/collection/LinearSeq.html) 的标准实现。 +[MutableList](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/MutableList.html) 由一个单向链表和一个指向该链表终端空节点的指针构成。因为避免了贯穿整个列表去遍历搜索它的终端节点，这就使得列表压缩了操作所用的时间。MutableList 目前是Scala中[mutable.LinearSeq](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/LinearSeq.html) 的标准实现。 ## 队列 @@ -87,13 +84,13 @@ Scala除了提供了不可变队列之外，还提供了可变队列。你可以 ## 数组序列 -Array Sequences 是具有固定大小的可变序列。在它的内部，用一个 `Array[Object]`来存储元素。在Scala 中，[ArraySeq](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/ArraySeq.html) 是它的实现类。 +Array Sequences 是具有固定大小的可变序列。在它的内部，用一个 `Array[Object]`来存储元素。在Scala 中，[ArraySeq](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/ArraySeq.html) 是它的实现类。 -如果你想拥有 Array 的性能特点，又想建立一个泛型序列实例，但是你又不知道其元素的类型，在运行阶段也无法提供一个`ClassTag` ，那么你通常可以使用 `ArraySeq` 。这些问题在[arrays](http://docs.scala-lang.org/overviews/collections/arrays.html)一节中有详细的说明。 +如果你想拥有 Array 的性能特点，又想建立一个泛型序列实例，但是你又不知道其元素的类型，在运行阶段也无法提供一个`ClassTag` ，那么你通常可以使用 `ArraySeq` 。这些问题在[arrays](https://docs.scala-lang.org/overviews/collections/arrays.html)一节中有详细的说明。 ## 堆栈 -你已经在前面看过了不可变栈。还有一个可变栈，支持类是[mutable.Stack](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/Stack.html)。它的工作方式与不可变栈相同，只是适当的做了修改。 +你已经在前面看过了不可变栈。还有一个可变栈，支持类是[mutable.Stack](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/Stack.html)。它的工作方式与不可变栈相同，只是适当的做了修改。 scala> val stack = new scala.collection.mutable.Stack[Int] stack: scala.collection.mutable.Stack[Int] = Stack() @@ -116,11 +113,11 @@ Array Sequences 是具有固定大小的可变序列。在它的内部，用一 ## 数组堆栈 -[ArrayStack](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/ArrayStack.html) 是另一种可变栈的实现，用一个可根据需要改变大小的数组做为支持。它提供了快速索引，使其通常在大多数的操作中会比普通的可变堆栈更高效一点。 +[ArrayStack](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/ArrayStack.html) 是另一种可变栈的实现，用一个可根据需要改变大小的数组做为支持。它提供了快速索引，使其通常在大多数的操作中会比普通的可变堆栈更高效一点。 ## 哈希表 -Hash Table 用一个底层数组来存储元素，每个数据项在数组中的存储位置由这个数据项的Hash Code 来决定。添加一个元素到Hash Table不用花费多少时间，只要数组中不存在与其含有相同Hash Code的另一个元素。因此，只要Hash Table能够根据一种良好的hash codes分配机制来存放对象，Hash Table的速度会非常快。所以在Scala中默认的可变map和set都是基于Hash Table的。你也可以直接用[mutable.HashSet](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/HashSet.html) 和 [mutable.HashMap](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/HashMap.html) 来访问它们。 +Hash Table 用一个底层数组来存储元素，每个数据项在数组中的存储位置由这个数据项的Hash Code 来决定。添加一个元素到Hash Table不用花费多少时间，只要数组中不存在与其含有相同Hash Code的另一个元素。因此，只要Hash Table能够根据一种良好的hash codes分配机制来存放对象，Hash Table的速度会非常快。所以在Scala中默认的可变map和set都是基于Hash Table的。你也可以直接用[mutable.HashSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/HashSet.html) 和 [mutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/HashMap.html) 来访问它们。 Hash Set 和 Map 的使用和其他的Set和Map是一样的。这里有一些简单的例子： @@ -139,11 +136,11 @@ Hash Table的迭代并不是按特定的顺序进行的。它是按任何可能 ## Weak Hash Maps -Weak Hash Map 是一种特殊的Hash Map，垃圾回收器会忽略从Map到存储在其内部的Key值的链接。这也就是说，当一个key不再被引用的时候，这个键和对应的值会从map中消失。Weak Hash Map 可以用来处理缓存，比如当一个方法被同一个键值重新调用时，你想重用这个大开销的方法返回值。如果Key值和方法返回值存储在一个常规的Hash Map里，Map会无限制的扩展，Key值也永远不会被垃圾回收器回收。用Weak Hash Map会避免这个问题。一旦有一个Key对象不再被引用，那它的实体会从Weak Hash Map中删除。在Scala中，[WeakHashMap](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/WeakHashMap.html)类是Weak Hash Map的实现类，封装了底层的Java实现类`java.util.WeakHashMap`。 +Weak Hash Map 是一种特殊的Hash Map，垃圾回收器会忽略从Map到存储在其内部的Key值的链接。这也就是说，当一个key不再被引用的时候，这个键和对应的值会从map中消失。Weak Hash Map 可以用来处理缓存，比如当一个方法被同一个键值重新调用时，你想重用这个大开销的方法返回值。如果Key值和方法返回值存储在一个常规的Hash Map里，Map会无限制的扩展，Key值也永远不会被垃圾回收器回收。用Weak Hash Map会避免这个问题。一旦有一个Key对象不再被引用，那它的实体会从Weak Hash Map中删除。在Scala中，[WeakHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/WeakHashMap.html)类是Weak Hash Map的实现类，封装了底层的Java实现类`java.util.WeakHashMap`。 ## Concurrent Maps -Concurrent Map可以同时被多个线程访问。除了[Map](http://www.scala-lang.org/api/2.10.0/scala/collection/Map.html)的通用方法，它提供了下列的原子方法： +Concurrent Map可以同时被多个线程访问。除了[Map](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/Map.html)的通用方法，它提供了下列的原子方法： ### Concurrent Map类中的方法： @@ -155,11 +152,11 @@ Concurrent Map可以同时被多个线程访问。除了[Map](http://www.scala-l |m replace (k, v) | 如果k先前绑定的是其他值，则把键k对应的值替换为v | -`ConcurrentMap`体现了Scala容器库的特性。目前，它的实现类只有Java的`java.util.concurrent.ConcurrentMap`, 它可以用[standard Java/Scala collection conversions](http://docs.scala-lang.org/overviews/collections/conversions-between-java-and-scala-collections.html)(标准的java/Scala容器转换器)来自动转换成一个Scala map。 +`ConcurrentMap`体现了Scala容器库的特性。目前，它的实现类只有Java的`java.util.concurrent.ConcurrentMap`, 它可以用[standard Java/Scala collection conversions](https://docs.scala-lang.org/overviews/collections/conversions-between-java-and-scala-collections.html)(标准的java/Scala容器转换器)来自动转换成一个Scala map。 ## Mutable Bitsets -一个类型为[mutable.BitSet](http://www.scala-lang.org/api/2.10.0/scala/collection/mutable/BitSet.html)的可变bit集合和不可变的bit集合很相似，它只是做了适当的修改。Mutable bit sets在更新的操作上比不可变bit set 效率稍高，因为它不必复制没有发生变化的 Long值。 +一个类型为[mutable.BitSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/mutable/BitSet.html)的可变bit集合和不可变的bit集合很相似，它只是做了适当的修改。Mutable bit sets在更新的操作上比不可变bit set 效率稍高，因为它不必复制没有发生变化的 Long值。 scala> val bits = scala.collection.mutable.BitSet.empty bits: scala.collection.mutable.BitSet = BitSet() diff --git a/_zh-cn/overviews/collections/conversions-between-java-and-scala-collections.md b/_zh-cn/overviews/collections/conversions-between-java-and-scala-collections.md index af302dd49f..c63b024585 100644 --- a/_zh-cn/overviews/collections/conversions-between-java-and-scala-collections.md +++ b/_zh-cn/overviews/collections/conversions-between-java-and-scala-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Java和Scala容器的转换 - -discourse: false - partof: collections overview-name: Collections @@ -16,44 +13,49 @@ language: zh-cn 某些时候，你需要将一种容器类型转换成另外一种类型。例如，你可能想要像访问Scala容器一样访问某个Java容器，或者你可能想将一个Scala容器像Java容器一样传递给某个Java方法。在Scala中，这是很容易的，因为Scala提供了大量的方法来隐式转换所有主要的Java和Scala容器类型。其中提供了如下的双向类型转换： - Iterator <=> java.util.Iterator - Iterator <=> java.util.Enumeration - Iterable <=> java.lang.Iterable - Iterable <=> java.util.Collection - mutable.Buffer <=> java.util.List - mutable.Set <=> java.util.Set - mutable.Map <=> java.util.Map - mutable.ConcurrentMap <=> java.util.concurrent.ConcurrentMap -使用这些转换很简单，只需从JavaConversions对象中import它们即可。 + Iterator <=> java.util.Iterator + Iterator <=> java.util.Enumeration + Iterable <=> java.lang.Iterable + Iterable <=> java.util.Collection + mutable.Buffer <=> java.util.List + mutable.Set <=> java.util.Set + mutable.Map <=> java.util.Map + mutable.ConcurrentMap <=> java.util.concurrent.ConcurrentMap - scala> import collection.JavaConversions._ - import collection.Java.Conversions._ +使用这些转换很简单，只需从JavaConverters对象中import它们即可。 -import之后，就可以在Scala容器和与之对应的Java容器之间进行隐式转换了 + scala> import collection.JavaConverters._ + import collection.JavaConverters._ + +import之后，通过扩展方法 asScala 和 asJava 就可以在Scala容器和与之对应的Java容器之间进行隐式转换了 scala> import collection.mutable._ import collection.mutable._ - scala> val jul: java.util.List[Int] = ArrayBuffer(1, 2, 3) + + scala> val jul: java.util.List[Int] = ArrayBuffer(1, 2, 3).asJava jul: java.util.List[Int] = [1, 2, 3] - scala> val buf: Seq[Int] = jul + + scala> val buf: Seq[Int] = jul.asScala buf: scala.collection.mutable.Seq[Int] = ArrayBuffer(1, 2, 3) - scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2) - m: java.util.Map[String, Int] = {hello=2, abc=1} + + scala> val m: java.util.Map[String, Int] = HashMap("abc" -> 1, "hello" -> 2).asJava + m: java.util.Map[String,Int] = {abc=1, hello=2} 在Scala内部，这些转换是通过一系列“包装”对象完成的，这些对象会将相应的方法调用转发至底层的容器对象。所以容器不会在Java和Scala之间拷贝来拷贝去。一个值得注意的特性是，如果你将一个Java容器转换成其对应的Scala容器，然后再将其转换回同样的Java容器，最终得到的是一个和一开始完全相同的容器对象（译注：这里的相同意味着这两个对象实际上是指向同一片内存区域的引用，容器转换过程中没有任何的拷贝发生）。 还有一些Scala容器类型可以转换成对应的Java类型，但是并没有将相应的Java类型转换成Scala类型的能力，它们是： - Seq => java.util.List - mutable.Seq => java.util.List - Set => java.util.Set - Map => java.util.Map + Seq => java.util.List + mutable.Seq => java.util.List + Set => java.util.Set + Map => java.util.Map 因为Java并未区分可变容器不可变容器类型，所以，虽然能将`scala.immutable.List`转换成`java.util.List`，但所有的修改操作都会抛出“UnsupportedOperationException”。参见下例： - scala> jul = List(1, 2, 3) + scala> val jul = List(1, 2, 3).asJava jul: java.util.List[Int] = [1, 2, 3] + scala> jul.add(7) java.lang.UnsupportedOperationException - at java.util.AbstractList.add(AbstractList.java:131) + at java.util.AbstractList.add(AbstractList.java:148) diff --git a/_zh-cn/overviews/collections/creating-collections-from-scratch.md b/_zh-cn/overviews/collections/creating-collections-from-scratch.md index 3d9df97e09..793e324ec7 100644 --- a/_zh-cn/overviews/collections/creating-collections-from-scratch.md +++ b/_zh-cn/overviews/collections/creating-collections-from-scratch.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 从头定义新容器 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/equality.md b/_zh-cn/overviews/collections/equality.md index 39eedc64dd..365318998c 100644 --- a/_zh-cn/overviews/collections/equality.md +++ b/_zh-cn/overviews/collections/equality.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 等价性 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/introduction.md b/_zh-cn/overviews/collections/introduction.md index 1cad8b7988..b038d5f66b 100644 --- a/_zh-cn/overviews/collections/introduction.md +++ b/_zh-cn/overviews/collections/introduction.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 简介 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/iterators.md b/_zh-cn/overviews/collections/iterators.md index 4325c15710..68da25ed2b 100644 --- a/_zh-cn/overviews/collections/iterators.md +++ b/_zh-cn/overviews/collections/iterators.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Iterators - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/maps.md b/_zh-cn/overviews/collections/maps.md index 13cc40a543..d0e7d83d67 100644 --- a/_zh-cn/overviews/collections/maps.md +++ b/_zh-cn/overviews/collections/maps.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 映射 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/migrating-from-scala-27.md b/_zh-cn/overviews/collections/migrating-from-scala-27.md index 016fc7ce69..3511b46a8f 100644 --- a/_zh-cn/overviews/collections/migrating-from-scala-27.md +++ b/_zh-cn/overviews/collections/migrating-from-scala-27.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Scala 2.7迁移指南 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/overview.md b/_zh-cn/overviews/collections/overview.md index 526d6c658f..d5bf0f71fa 100644 --- a/_zh-cn/overviews/collections/overview.md +++ b/_zh-cn/overviews/collections/overview.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Mutable和Immutable集合 - -discourse: false - partof: collections overview-name: Collections @@ -16,11 +13,11 @@ Scala 集合类系统地区分了可变的和不可变的集合。可变集合 所有的集合类都可以在包`scala.collection` 或`scala.collection.mutable`，`scala.collection.immutable`，`scala.collection.generic`中找到。客户端代码需要的大部分集合类都独立地存在于3种变体中，它们位于`scala.collection`, `scala.collection.immutable`, `scala.collection.mutable`包。每一种变体在可变性方面都有不同的特征。 -`scala.collection.immutable`包是的集合类确保不被任何对象改变。例如一个集合创建之后将不会改变。因此，你可以相信一个事实，在不同的点访问同一个集合的值，你将总是得到相同的元素。。 +`scala.collection.immutable`包的集合类确保不被任何对象改变。例如一个集合创建之后将不会改变。因此，你可以相信一个事实，在不同的点访问同一个集合的值，你将总是得到相同的元素。。 `scala.collection.mutable`包的集合类则有一些操作可以修改集合。所以处理可变集合意味着你需要去理解哪些代码的修改会导致集合同时改变。 -`scala.collection`包中的集合，既可以是可变的，也可以是不可变的。例如：[collection.IndexedSeq[T]](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html)] 就是 [collection.immutable.IndexedSeq[T]](http://www.scala-lang.org/api/current/scala/collection/immutable/IndexedSeq.html) 和[collection.mutable.IndexedSeq[T]](http://www.scala-lang.org/api/current/scala/collection/mutable/IndexedSeq.html)这两类的超类。`scala.collection`包中的根集合类中定义了相同的接口作为不可变集合类，同时，`scala.collection.mutable`包中的可变集合类代表性的添加了一些有辅助作用的修改操作到这个immutable 接口。 +`scala.collection`包中的集合，既可以是可变的，也可以是不可变的。例如：[collection.IndexedSeq[T]](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/IndexedSeq.html)] 就是 [collection.immutable.IndexedSeq[T]](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/IndexedSeq.html) 和[collection.mutable.IndexedSeq[T]](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/IndexedSeq.html)这两类的超类。`scala.collection`包中的根集合类中定义了相同的接口作为不可变集合类，同时，`scala.collection.mutable`包中的可变集合类代表性的添加了一些有辅助作用的修改操作到这个immutable 接口。 根集合类与不可变集合类之间的区别是不可变集合类的客户端可以确保没有人可以修改集合。然而，根集合类的客户端仅保证不修改集合本身。即使这个集合类没有提供修改集合的静态操作，它仍然可能在运行时作为可变集合被其它客户端所修改。 @@ -32,30 +29,31 @@ Scala 集合类系统地区分了可变的和不可变的集合。可变集合 然而，像没有前缀的Set这样的关键字， 仍然指的是一个不可变集合，然而`mutable.Set`指的是可变的副本（可变集合）。 -集合树的最后一个包是`collection.generic`。这个包包含了集合的构建块。集合类延迟了`collection.generic`类中的部分操作实现，另一方面集合框架的用户需要引用`collection.generic`中类在异常情况中。 +集合树的最后一个包是`collection.generic`。这个包包含了集合的构建块。集合类延迟了`collection.generic`类中的部分操作实现，另一方面，集合框架的用户只需要在特殊情况下引用`collection.generic`。 -为了方便和向后兼容性，一些导入类型在包scala中有别名，所以你能通过简单的名字使用它们而不需要import。这有一个例子是List 类型，它可以用以下两种方法使用，如下： +为了方便和向后兼容性，一些导入类型在包scala中有别名，所以你能通过简单的名字使用它们而不需要import。这有一个例子是`List`类型，它可以用以下两种方法使用，如下： scala.collection.immutable.List // 这是它的定义位置 scala.List //通过scala 包中的别名 - List // 因为scala._ - // 总是是被自动导入。 + List // 因为scala._ 总是被自动导入。 + +其它类型的别名有： [Traversable](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Traversable.html), [Iterable](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterable.html), [Seq](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Seq.html), [IndexedSeq](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/IndexedSeq.html), [Iterator](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/Iterator.html), [Stream](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Stream.html), [Vector](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Vector.html), [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/mutable/StringBuilder.html), [Range](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html)。 -其它类型的别名有： [Traversable](http://www.scala-lang.org/api/current/scala/collection/Traversable.html), [Iterable](http://www.scala-lang.org/api/current/scala/collection/Iterable.html), [Seq](http://www.scala-lang.org/api/current/scala/collection/Seq.html), [IndexedSeq](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html), [Iterator](http://www.scala-lang.org/api/current/scala/collection/Iterator.html), [Stream](http://www.scala-lang.org/api/current/scala/collection/immutable/Stream.html), [Vector](http://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html), [StringBuilder](http://www.scala-lang.org/api/current/scala/collection/mutable/StringBuilder.html), [Range](http://www.scala-lang.org/api/current/scala/collection/immutable/Range.html)。 +下图显示了`scala.collection`包中所有的集合类。这些都是高级抽象类或特质，它们通常具备和不可变实现一样的可变实现。 -下面的图表显示了`scala.collection`包中所有的集合类。这些都是高级抽象类或特性，它们通常具备和不可变实现一样的可变实现。 +[![General collection hierarchy][1]][1] -[]({{ site.baseurl }}/resources/images/collections.png) +下图显示了`scala.collection.immutable`中所有的集合类。 -下面的图表显示scala.collection.immutable中的所有集合类。 +[![Immutable collection hierarchy][2]][2] -[]({{ site.baseurl }}/resources/images/collections.immutable.png) +下图显示了`scala.collection.mutable`中所有的集合类。 -下面的图表显示scala.collection.mutable中的所有集合类。 +[![Mutable collection hierarchy][3]][3] -[]({{ site.baseurl }}/resources/images/collections.mutable.png) +图例: -（以上三个图表由Matthias生成， 来自decodified.com）。 +[![Graph legend][4]][4] ## 集合API概述 @@ -77,7 +75,7 @@ Scala 集合类系统地区分了可变的和不可变的集合。可变集合 所有这些集合类都通过相同的途径，用toString方法展示出来。 -Traversable类提供了所有集合支持的API，同时，对于特殊类型也是有意义的。例如，Traversable类 的map方法会返回另一个Traversable对象作为结果，但是这个结果类型在子类中被重写了。例如，在一个List上调用map会又生成一个List，在Set上调用会再生成一个Set，以此类推。 +Traversable类提供了所有集合支持的API，同时，对于特殊类型也是有意义的。例如，`Traversable`类的`map`方法会返回另一个`Traversable`对象作为结果，但是这个结果的类型在子类中被重写了。例如，在一个`List`上调用`map`会又生成一个`List`，在`Set`上调用会再生成一个`Set`，以此类推。 scala> List(1, 2, 3) map (_ + 1) res0: List[Int] = List(2, 3, 4) @@ -86,6 +84,12 @@ Traversable类提供了所有集合支持的API，同时，对于特殊类型也 在集合类库中，这种在任何地方都实现了的行为，被称之为返回类型一致原则。 -大多数类在集合树中存在这于三种变体：root, mutable 和immutable。唯一的例外是缓冲区特征，它仅在于mutable集合。 +大多数类在集合树中存在这于三种变体：root, mutable和immutable。唯一的例外是缓冲区特质，它仅在于mutable集合。 下面我们将一个个的回顾这些类。 + + + [1]: /resources/images/tour/collections-diagram.svg + [2]: /resources/images/tour/collections-immutable-diagram.svg + [3]: /resources/images/tour/collections-mutable-diagram.svg + [4]: /resources/images/tour/collections-legend-diagram.svg diff --git a/_zh-cn/overviews/collections/performance-characteristics.md b/_zh-cn/overviews/collections/performance-characteristics.md index b9e5719a68..9fc1a69ed1 100644 --- a/_zh-cn/overviews/collections/performance-characteristics.md +++ b/_zh-cn/overviews/collections/performance-characteristics.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 性能特点 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/seqs.md b/_zh-cn/overviews/collections/seqs.md index c9640efd99..17861ce403 100644 --- a/_zh-cn/overviews/collections/seqs.md +++ b/_zh-cn/overviews/collections/seqs.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 序列trait：Seq、IndexedSeq及LinearSeq - -discourse: false - partof: collections overview-name: Collections @@ -12,7 +9,7 @@ language: zh-cn --- -[Seq](http://www.scala-lang.org/api/current/scala/collection/Seq.html) trait用于表示序列。所谓序列，指的是一类具有一定长度的可迭代访问的对象，其中每个元素均带有一个从0开始计数的固定索引位置。 +[Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) trait用于表示序列。所谓序列，指的是一类具有一定长度的可迭代访问的对象，其中每个元素均带有一个从0开始计数的固定索引位置。 序列的操作有以下几种，如下表所示： @@ -27,7 +24,7 @@ language: zh-cn 如果一个序列是可变的，它提供了另一种更新序列中的元素的，但有副作用的update方法，Scala中常有这样的语法，如seq(idx) = elem。它只是seq.update(idx, elem)的简写，所以update 提供了方便的赋值语法。应注意update 和updated之间的差异。update 再原来基础上更改序列中的元素，并且仅适用于可变序列。而updated 适用于所有的序列，它总是返回一个新序列，而不会修改原序列。 -## Seq类的操作 +### Seq类的操作 | WHAT IT IS | WHAT IT DOES | |------------------ | -------------------| @@ -41,7 +38,7 @@ language: zh-cn | xs indexOf x | 返回序列xs中等于x的第一个元素的索引（存在多种变体）。 | | xs lastIndexOf x | 返回序列xs中等于x的最后一个元素的索引（存在多种变体）。 | | xs indexOfSlice ys | 查找子序列ys，返回xs中匹配的第一个索引。 | -| xs indexOfSlice ys | 查找子序列ys，返回xs中匹配的倒数一个索引。 | +| xs lastIndexOfSlice ys | 查找子序列ys，返回xs中匹配的倒数一个索引。 | | xs indexWhere p | xs序列中满足p的第一个元素。（有多种形式） | | xs segmentLength (p, i) | xs中，从xs(i)开始并满足条件p的元素的最长连续片段的长度。 | | xs prefixLength p | xs序列中满足p条件的先头元素的最大个数。 | @@ -75,17 +72,17 @@ language: zh-cn | | | -特性（trait) [Seq](http://www.scala-lang.org/api/current/scala/collection/Seq.html) 具有两个子特征（subtrait） [LinearSeq](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html)和[IndexedSeq](http://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html)。它们不添加任何新的操作，但都提供不同的性能特点：线性序列具有高效的 head 和 tail 操作，而索引序列具有高效的apply, length, 和 (如果可变) update操作。 +特性（trait) [Seq](https://www.scala-lang.org/api/current/scala/collection/Seq.html) 具有两个子特征（subtrait） [LinearSeq](https://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html)和[IndexedSeq](https://www.scala-lang.org/api/current/scala/collection/IndexedSeq.html)。它们不添加任何新的操作，但都提供不同的性能特点：线性序列具有高效的 head 和 tail 操作，而索引序列具有高效的apply, length, 和 (如果可变) update操作。 常用线性序列有 `scala.collection.immutable.List`和`scala.collection.immutable.Stream`。常用索引序列有 `scala.Array scala.collection.mutable.ArrayBuffer`。Vector 类提供一个在索引访问和线性访问之间有趣的折中。它同时具有高效的恒定时间的索引开销，和恒定时间的线性访问开销。正因为如此，对于混合访问模式，vector是一个很好的基础。后面将详细介绍vector。 -## 缓冲器 +### 缓冲器 Buffers是可变序列一个重要的种类。它们不仅允许更新现有的元素，而且允许元素的插入、移除和在buffer尾部高效地添加新元素。buffer 支持的主要新方法有：用于在尾部添加元素的 `+=` 和 `++=`；用于在前方添加元素的`+=: `和` ++=:` ；用于插入元素的 `insert`和`insertAll`；以及用于删除元素的` remove` 和 `-=`。如下表所示。 ListBuffer和ArrayBuffer是常用的buffer实现 。顾名思义，ListBuffer依赖列表（List），支持高效地将它的元素转换成列表。而ArrayBuffer依赖数组（Array），能快速地转换成数组。 -## Buffer类的操作 +#### Buffer类的操作 | WHAT IT IS | WHAT IT DOES | |--------------------- | -----------------------| diff --git a/_zh-cn/overviews/collections/sets.md b/_zh-cn/overviews/collections/sets.md index 6694dfb2cc..acce968199 100644 --- a/_zh-cn/overviews/collections/sets.md +++ b/_zh-cn/overviews/collections/sets.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 集合 - -discourse: false - partof: collections overview-name: Collections @@ -114,9 +111,9 @@ language: zh-cn ## 有序集（SortedSet） - [SortedSet](http://www.scala-lang.org/api/current/scala/collection/SortedSet.html) 是指以特定的顺序（这一顺序可以在创建集合之初自由的选定）排列其元素（使用iterator或foreach）的集合。 [SortedSet](http://www.scala-lang.org/api/current/scala/collection/SortedSet.html) 的默认表示是有序二叉树，即左子树上的元素小于所有右子树上的元素。这样，一次简单的顺序遍历能按增序返回集合中的所有元素。Scala的类 `immutable.TreeSet` 使用红黑树实现，它在维护元素顺序的同时，也会保证二叉树的平衡，即叶节点的深度差最多为1。 + [SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) 是指以特定的顺序（这一顺序可以在创建集合之初自由的选定）排列其元素（使用iterator或foreach）的集合。 [SortedSet](https://www.scala-lang.org/api/current/scala/collection/SortedSet.html) 的默认表示是有序二叉树，即左子树上的元素小于所有右子树上的元素。这样，一次简单的顺序遍历能按增序返回集合中的所有元素。Scala的类 `immutable.TreeSet` 使用红黑树实现，它在维护元素顺序的同时，也会保证二叉树的平衡，即叶节点的深度差最多为1。 -创建一个空的 [TreeSet](http://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html) ，可以先定义排序规则： +创建一个空的 [TreeSet](https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSet.html) ，可以先定义排序规则： scala> val myOrdering = Ordering.fromLessThan[String](_ > _) myOrdering: scala.math.Ordering[String] = ... diff --git a/_zh-cn/overviews/collections/strings.md b/_zh-cn/overviews/collections/strings.md index 2743dc3481..43346b67d8 100644 --- a/_zh-cn/overviews/collections/strings.md +++ b/_zh-cn/overviews/collections/strings.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 字符串 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/trait-iterable.md b/_zh-cn/overviews/collections/trait-iterable.md index d04a568b5b..5de8f05086 100644 --- a/_zh-cn/overviews/collections/trait-iterable.md +++ b/_zh-cn/overviews/collections/trait-iterable.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Trait Iterable - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/trait-traversable.md b/_zh-cn/overviews/collections/trait-traversable.md index d239bcadb4..a713376a51 100644 --- a/_zh-cn/overviews/collections/trait-traversable.md +++ b/_zh-cn/overviews/collections/trait-traversable.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: Trait Traversable - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/collections/views.md b/_zh-cn/overviews/collections/views.md index a7e076c5eb..df945d1dce 100644 --- a/_zh-cn/overviews/collections/views.md +++ b/_zh-cn/overviews/collections/views.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 视图 - -discourse: false - partof: collections overview-name: Collections diff --git a/_zh-cn/overviews/core/actors-migration-guide.md b/_zh-cn/overviews/core/actors-migration-guide.md deleted file mode 100644 index a7c6b76a17..0000000000 --- a/_zh-cn/overviews/core/actors-migration-guide.md +++ /dev/null @@ -1,465 +0,0 @@ ---- -layout: singlepage-overview -title: Scala Actors迁移指南 - -partof: actor-migration - -language: zh-cn - -discourse: false ---- - -**Vojin Jovanovic 和 Philipp Haller 著** - -## 概述 - -从Scala的2.11.0版本开始，Scala的Actors库已经过时了。早在Scala2.10.0的时候，默认的actor库即是Akka。 - -为了方便的将Scala Actors迁移到Akka，我们提供了Actor迁移工具包（AMK）。通过在一个项目的类路径中添加scala-actors-migration.jar，AMK包含了一个针对Scala Actors扩展。此外，Akka 2.1包含一些特殊功能，比如ActorDSL singleton，可以实现更简单的转换功能，使Scala Actors代码变成Akka代码。本章内容的目的是用来指导用户完成迁移过程，并解释如何使用AMK。 - -本指南包括以下内容：在“迁移工具的局限性”章节中，我们在此概述了迁移工具的主要局限性。在“迁移概述”章节中我们描述了迁移过程和谈论了Scala的变化分布，使得迁移成为一种可能。最后，在“一步一步指导迁移到Akka”章节里，我们展示了一些迁移工作的例子，以及各个步骤，如果需要从Scala Actors迁移至Akka's actors，本节是推荐阅读的。 - -免责声明:并发代码是臭名昭著的，当出现bug时很难调试和修复。由于两个actor的不同实现，这种差异导致可能出现错误。迁移过程每一步后都建议进行完全的代码测试。 - -## 迁移工具的局限性 - -由于Akka和Scala的actor模型的完整功能不尽相同导致两者之间不能平滑地迁移。下面的列表解释了很难迁移的部分行为： - -1. 依靠终止原因和双向行为链接方法 - Scala和Akka actors有不同的故障处理和actor monitoring模型。在Scala actors模型中，如果一个相关联部分异常终止，相关联的actors终止。如果终止是显式跟踪(通过self.trapExit)，actor可以从失败的actor收到终止的原因。通过Akka这个功能不能迁移到AMK。AMK允许迁移的只是[Akka monitoring](http://doc.akka.io/docs/akka/2.1.0/general/supervision.html#What_Lifecycle_Monitoring_Means)机制。Monitoring不同于连接,因为它是单向(unindirectional)的并且终止的原因是现在已知的。如果仅仅是monitoring机制是无法满足需求的,迁移的链接必须推迟到最后一刻(步骤5的迁移)。然后,当迁移到Akka,用户必须创建一个[监督层次(supervision hierarchy)](http://doc.akka.io/docs/akka/2.1.0/general/supervision.html),处理故障。 - -2. 使用restart方法——Akka不提供显式的重启actors，因此上述例子我们不能提供平滑迁移。用户必须更改系统,所以没有使用重启方法(restart method)。 - -3. 使用getState方法 - Akka actors没有显式状态,此功能无法迁移。用户代码必须没有getState调用。 - -4. 实例化后没有启动actors - Akka actors模型会在实例化后自动启动actors，所以用户不需要重塑系统来显式的在实例化后启动actors。 - -5. mailboxSize方法不存在Akka中,因此不能迁移。这种方法很少使用,很容易被删除。 - -## 迁移概述 - -### 迁移工具 - -在Scal 2.10.0 actors 是在[Scala distribution](http://www.scala-lang.org/downloads)中作为一个单独包（scala-actors.jar）存在的，并且他们的接口已被弃用。这种分布也包含在Akka actors的akka-actor.jar里。AMK同时存在Scala actors 和 akka-actor.jar之中。未来的主要版本的Scala将不包含Scala actors和AMK。 - -开始迁移，用户需要添加scala-actors.jar和scala-actors-migration.jar来构建他们的项目。添加scala-actors.jar和scala-actors-migration.jar允许使用下面描述的AMK。这些jar位于Scala Tools库和[Scala distribution](http://www.scala-lang.org/downloads)库中。 - -### 一步一步来迁移 - -Actor迁移工具使用起来应该有5步骤。每一步都设计为引入的基于代码的最小变化。在前四个迁移步骤的代码中将使用Scala actors来实现，并在该步完成后运行所有的系统测试。然而,方法和类的签名将被转换为与Akka相似。迁移工具在Scal方面引入了一种新的actor类型（ActWithStash）和强制执行actors的ActorRef接口。 - -该结果同样强制通过一个特殊的方法在ActorDSL 对象上创建actors。在这些步骤可以每次迁移一个actor。这降低了在同一时刻引入多个bug的可能性，同样降低了bug的复杂程度。 - -在Scala方面迁移完成后，用户应该改变import语句并变成使用Akka库。在Akka方面，ActorDSL和ActWithStash允许对Scala Actors和他们的生态系的react construct进行建模。这个步骤迁移所有actors到Akka的后端，会在系统中引入bug。一旦代码迁移到Akka,用户将能够使用Akka的所有的功能的。 - -### 一步一步指导迁移到Akka - -在这一章中,我们将通过actor迁移的5个步骤。在每一步之后的代码都要为可能的错误进行检测。在前4个步骤中可以一边迁移一个actor和一边测试功能。然而,最后一步迁移所有actors到Akka后它只能作为一个整体进行测试。在这个步骤之后系统应该具有和之前一样相同的功能，不过它将使用Akka actor库。 - -### 步骤1——万物皆是Actor - -Scala actors库提供了公共访问多个类型的actors。他们被组织在类层次结构和每个子类提供了稍微更丰富的功能。为了进一步的使迁移步骤更容易，我们将首先更改Actor类型系统中的每一个actor。这种迁移步骤很简单，因为Actor类位于层次结构的底部，并提供了广泛的功能。 - -来自Scala库的Actors应根据以下规则进行迁移： - -1. class MyServ extends Reactor[T] -> class MyServ extends Actor - -注意,反应器提供了一个额外的类型参数代表了类型的消息收到。如果用户代码中使用这些信息，那么一个需要：i）应用模式匹配与显式类型,或者ii）做一个向下的消息来自任何泛型T。 - -1. class MyServ extends ReplyReactor -> class MyServ extends Actor - -2. class MyServ extends DaemonActor -> class MyServ extends Actor - -为了为DaemonActor提供配对功能，将下列代码添加到类的定义。 - - override def scheduler: IScheduler = DaemonScheduler - -### 步骤2 - 实例化 - -在Akka中,actors可以访问只有通过ActorRef接口。ActorRef的实例可以通过在ActorDSL对象上调用actor方法或者通过调用ActorRefFactory实例的actorOf方法来获得。在Scala的AMK工具包中，我们提供了Akka ActorRef和ActorDSL的一个子集，该子集实际上是Akka库的一个单例对象(singleton object)。 - -这一步的迁移使所有actors访问通过ActorRefs。首先，我们现实如何迁移普通模式的实例化Sacla Actors。然后，我们将展示如何分别克服问题的ActorRef和Actor的不同接口。 - -#### Actor实例化 - -actor实例的转换规则（以下规则需要import scala.actors.migration._）： - -1. 构造器调用实例化 - - val myActor = new MyActor(arg1, arg2) - myActor.start() - -应该被替换 - - ActorDSL.actor(new MyActor(arg1, arg2)) - -2. 用于创建Actors的DSL(译注：领域专用语言(Domain Specific Language)) - - val myActor = actor { - // actor 定义 - } -应该被替换 - - val myActor = ActorDSL.actor(new Actor { - def act() { - // actor 定义 - } - }) - -3. 从Actor Trait扩展来的对象 - - object MyActor extends Actor { - // MyActor 定义 - } - MyActor.start() -应该被替换 - - class MyActor extends Actor { - // MyActor 定义 - } - - object MyActor { - val ref = ActorDSL.actor(new MyActor) - } -所有的MyActor地想都应该被替换成MyActor.ref。 - -需要注意的是Akka actors在实例化的同时开始运行。actors创建并开始在迁移的系统的情况下，actors在不同的位置以及改变这可能会影响系统的行为，用户需要更改代码，以使得actors在实例化后立即开始执行。 - -远程actors也需要被获取作为ActorRefs。为了得到一个远程actor ActorRef需使用方法selectActorRef。 - -#### 不同的方法签名(signatures) - -至此为止我们已经改变了所有的actor实例化，返回ActorRefs，然而，我们还没有完成迁移工作。有不同的接口在ActorRefs和Actors中，因此我们需要改变在每个迁移实例上触发的方法。不幸的是，Scala Actors提供的一些方法不能迁移。对下列方法的用户需要找到一个解决方案: - -1. getState()——Akka中的actors 默认情况下由其监管actors(supervising actors)负责管理和重启。在这种情况下,一个actor的状态是不相关的。 - -2. restart() - 显式的重启一个Scala actor。在Akka中没有相应的功能。 - -所有其他Actor方法需要转换为两个ActorRef中的方法。转换是通过下面描述的规则。请注意,所有的规则需要导入以下内容: - - import scala.concurrent.duration._ - import scala.actors.migration.pattern.ask - import scala.actors.migration._ - import scala.concurrent._ -额外规则1-3的作用域定义在无限的时间需要一个隐含的超时。然而，由于Akka不允许无限超时，我们会使用100年。例如： - - implicit val timeout = Timeout(36500 days) - -规则： - -1. !!(msg: Any): Future[Any] 被？替换。这条规则会改变一个返回类型到scala.concurrent.Future这可能导致类型不匹配。由于scala.concurrent.Future比过去的返回值具有更广泛的功能，这种类型的错误可以很容易地固定在与本地修改： - - actor !! message -> respActor ? message - -2. !![A] (msg: Any, handler: PartialFunction[Any, A]): Future[A] 被？取代。处理程序可以提取作为一个单独的函数，并用来生成一个future对象结果。处理的结果应给出另一个future对象结果,就像在下面的例子: - - val handler: PartialFunction[Any, T] = ... // handler - actor !! (message, handler) -> (respActor ? message) map handler - -3. !? (msg: Any):任何被？替换都将阻塞在返回的future对象上 - - actor !? message -> - Await.result(respActor ? message, Duration.Inf) - -4. !? (msec: Long, msg: Any): Option[Any]任何被？替换都将显式的阻塞在future对象 - - actor !? (dur, message) -> - val res = respActor.?(message)(Timeout(dur milliseconds)) - val optFut = res map (Some(_)) recover { case _ => None } - Await.result(optFut, Duration.Inf) - -这里没有提到的公共方法是为了actors DSL被申明为公共的。他们只能在定义actor时使用，所以他们的这一步迁移是不相关的。 - -###第3步 - 从Actor 到 ActWithStash - -到目前为止，所有的控制器都继承自Actor trait。我们通过指定的工厂方法来实例化控制器，所有的控制器都可以通过接口ActorRef 来进行访问。现在我们需要把所有的控制器迁移的AMK 的 ActWithStash 类上。这个类的行为方式和Scala的Actor几乎完全一致，它提供了另外一些方法，对应于Akka的Actor trait。这使得控制器更易于逐步的迁移到Akka。 - -为了达到这个目的，所有的从Actor继承的类，按照下列的方式，需要改为继承自ActWithStash： - - class MyActor extends Actor -> class MyActor extends ActWithStash - -经过这样修改以后，代码会无法通过编译。因为ActWithStash中的receive 方法不能在act中像原来那样使用。要使代码通过编译，需要在所有的 receive 调用中加上类型参数。例如： - - receive { case x: Int => "Number" } -> - receive[String] { case x: Int => "Number" } - -另外，要使代码通过编译，还要在act方法前加上 override关键字，并且定义一个空的receive方法。act方法需要被重写，因为它在ActWithStash 的实现中模拟了Akka的消息处理循环。需要修改的地方请看下面的例子： - - class MyActor extends ActWithStash { - - // 空的 receive 方法 (现在还没有用) - def receive = {case _ => } - - override def act() { - // 原来代码中的 receive 方法改为 react。 - } - } -ActWithStash 的实例中，变量trapExit 的缺省值是true。如果希望改变，可以在初始化方法中把它设置为false。 - -远程控制器在ActWithStash 下无法直接使用，register('name, this)方法需要被替换为： - - registerActorRef('name, self) - -在后面的步骤中， registerActorRef 和 alive 方法的调用与其它方法一样。 - -现在，用户可以测试运行，整个系统的运行会和原来一样。ActWithStash 和Actor 拥有相同的基本架构，所以系统的运行会与原来没有什么区别。 - -### 第4步 - 去掉act 方法 - -在这一节，我们讨论怎样从ActWithStash中去掉act方法，以及怎样修改其他方法，使它与Akka更加契合. 这一环节会比较繁杂，所以我们建议最好一次只修改一个控制器。在Scala中，控制器的行为主要是在act方法的中定义。逻辑上来说，控制器是一个并发执行act方法的过程，执行完成后过程终止。在Akka中，控制器用一个全局消息处理器来依次处理它的的消息队列中的消息。这个消息处理器是一个receive函数返回的偏函数(partial function)，该偏函数被应用与每一条消息上。 - -因为ActWithStash中Akka方法的行为依赖于移除的act方法，所以我们首先要做的是去掉act方法。然后，我们需要按照给定的规则修改scala.actors.Actor中每个方法的。 - -#### 怎样去除act 方法 - -在下面的列表中，我们给出了通用消息处理模式的修改规则。这个列表并不包含所有的模式，它只是覆盖了其中一些通用的模式。然而用户可以通过参考这些规则，通过扩展简单规则，将act方法移植到Akka。 - -嵌套调用react/reactWithin需要注意：消息处理偏函数需要做结构扩展，使它更接近Akka模式。尽管这种修改会很复杂，但是它允许任何层次的嵌套被移植。下面有相关的例子。 - -在复杂控制流中使用receive/receiveWithin需要注意：这个移植会比较复杂，因为它要求重构act方法。在消息处理偏函数中使用react 和 andThen可以使receive的调用模型化。下面是一些简单的例子。 - -1. 如果在act方法中有一些代码在第一个包含react的loop之前被执行，那么这些代码应该被放在preStart方法中。 - - def act() { - //初始化的代码放在这里 - loop { - react { ... } - } - } -应该被替换 - - override def preStart() { - //初始化的代码放在这里 - } - - def act() { - loop { - react{ ... } - } - } -其他的模式，如果在第一个react 之前有一些代码，也可以使用这个规则。 - -2. 当act 的形式为：一个简单loop循环嵌套react，用下面的方法。 - - def act() = { - loop { - react { - // body - } - } - } -应该被替换 - - def receive = { - // body - } - -3. 当act包含一个loopWhile 结构，用下面的方法。 - - def act() = { - loopWhile(c) { - react { - case x: Int => - // do task - if (x == 42) { - c = false - } - } - } - } -应该被替换 - - def receive = { - case x: Int => - // do task - if (x == 42) { - context.stop(self) - } - } - -4. 当act包含嵌套的react，用下面的规则： - - def act() = { - var c = true - loopWhile(c) { - react { - case x: Int => - // do task - if (x == 42) { - c = false - } else { - react { - case y: String => - // do nested task - } - } - } - } - } -应该被替换 - - def receive = { - case x: Int => - // do task - if (x == 42) { - context.stop(self) - } else { - context.become(({ - case y: String => - // do nested task - }: Receive).andThen(x => { - unstashAll() - context.unbecome() - }).orElse { case x => stash(x) }) - } - } - -5. reactWithin方法使用下面的修改规则： - - loop { - reactWithin(t) { - case TIMEOUT => // timeout processing code - case msg => // message processing code - } - } -应该被替换 - - import scala.concurrent.duration._ - - context.setReceiveTimeout(t millisecond) - def receive = { - case ReceiveTimeout => // timeout processing code - case msg => // message processing code - } - -6. 在Akka中，异常处理用另一种方式完成。如果要模拟Scala控制器的方式，那就用下面的方法 - - def act() = { - loop { - react { - case msg => - // 可能会失败的代码 - } - } - } - - override def exceptionHandler = { - case x: Exception => println("got exception") - } -应该被替换 - - def receive = PFCatch({ - case msg => - // 可能会失败的代码 - }, { case x: Exception => println("got exception") }) - PFCatch 的定义 - - class PFCatch(f: PartialFunction[Any, Unit], - handler: PartialFunction[Exception, Unit]) - extends PartialFunction[Any, Unit] { - - def apply(x: Any) = { - try { - f(x) - } catch { - case e: Exception if handler.isDefinedAt(e) => - handler(e) - } - } - - def isDefinedAt(x: Any) = f.isDefinedAt(x) - } - - object PFCatch { - def apply(f: PartialFunction[Any, Unit], - handler: PartialFunction[Exception, Unit]) = - new PFCatch(f, handler) - } - -PFCatch并不包含在AMK之中，所以它可以保留在移植代码中，AMK将会在下一版本中被删除。当整个移植完成后，错误处理也可以改由Akka来监管。 - -#### 修改Actor的方法 - -当我们移除了act方法以后，我们需要替换在Akka中不存在，但是有相似功能的方法。在下面的列表中，我们给出了两者的区别和替换方法： - -1. exit()/exit(reason) - 需要由 context.stop(self) 替换 - -2. receiver - 需要由 self 替换 - -3. reply(msg) - 需要由 sender ! msg 替换 - -4. link(actor) - 在Akka中，控制器之间的链接一部分由[supervision](http://doc.akka.io/docs/akka/2.1.0/general/supervision.html#What_Supervision_Means)来完成，一部分由[actor monitoring](http://doc.akka.io/docs/akka/2.1.0/general/supervision.html#What_Lifecycle_Monitoring_Means)来完成。在AMK中，我们只支持监测方法。因此，这部分Scala功能可以被完整的移植。 - -linking 和 watching 之间的区别在于：watching actor总是接受结束通知。然而，不像Scala的Exit消息包含结束的原因，Akka的watching 返回Terminated(a: ActorRef)消息，只包含ActorRef。获取结束原因的功能无法被移植。在Akka中，这一步骤可以在第4步之后，通过组织控制器的监管层级 [supervision hierarchy](http://doc.akka.io/docs/akka/2.1.0/general/supervision.html)来完成。 - -如果watching actors收到的消息不撇陪结束消息，控制器会被终止并抛出DeathPactException异常。注意就算watching actors正常的结束，也会发生这种情况。在Scala中，linked actors只要一方不正常的终止，另一方就会以相同的原因终止。 - -如果系统不能单独的用 watch actors来 移植，用户可以像原来那样用link和exit(reason)来使用。然而，因为act()重载了Exit消息，需要做如下的修改： - - case Exit(actor, reason) => - println("sorry about your " + reason) - ... -应该被替换 - - case t @ Terminated(actorRef) => - println("sorry about your " + t.reason) - ... -注意：在Scala和Akka的actor之间有另一种细微的区别：在Scala， link/watch 到已经终止的控制器不会有任何影响。在Akka中，看管已经终止的控制器会导致发送终止消息。这会在系统移植的第5 步导致不可预料的结果。 - -### 第5步 - Akka后端的移植 - -到目前为止，用户代码已经做好了移植到Akka actors的准备工作。现在我们可以把Scala actors迁移到Akka actor上。为了完成这一目标，需要配置build，去掉scala-actors.jar 和 scala-actors-migration.jar，把 akka-actor.jar 和 typesafe-config.jar加进来。AMK只能在Akka actor 2.1下正常工作，Akka actor 2.1已经包含在分发包 [Scala distribution](http://www.scala-lang.org/downloads)中， 可以用这样的方法配置。 - -经过这一步骤以后，因为包名的不同和API之间的细微差别，编译会失败。我们必须将每一个导入的actor从scala 修改为Akka。下列是部分需要修改的包名： - - scala.actors._ -> akka.actor._ - scala.actors.migration.ActWithStash -> akka.actor.ActorDSL._ - scala.actors.migration.pattern.ask -> akka.pattern.ask - scala.actors.migration.Timeout -> akka.util.Timeout - -当然，ActWithStash 中方法的声明 def receive = 必须加上前缀override。 - -在Scala actor中，stash 方法需要一个消息做为参数。例如： - - def receive = { - ... - case x => stash(x) - } - -在Akka中，只有当前处理的消息可以被隐藏(stashed)。因此，上面的例子可以替换为： - - def receive = { - ... - case x => stash() - } - -#### 添加Actor System - -Akka actor 组织在[Actor systems](http://doc.akka.io/docs/akka/2.1.0/general/actor-systems.html)系统中。每一个被实例化的actor必须属于某一个ActorSystem。因此，要添加一个ActorSystem 实例作为每个actor 实例调用的第一个参数。下面给出了例子。 - -为了完成该转换，你需要有一个actor system 实例。例如： - - val system = ActorSystem("migration-system") - -然后，做如下转换： - - ActorDSL.actor(...) -> ActorDSL.actor(system)(...) - -如果对actor 的调用都使用同一个ActorSystem ，那么它可以作为隐式参数来传递。例如： - - ActorDSL.actor(...) -> - import project.implicitActorSystem - ActorDSL.actor(...) - -当所有的主线程和actors结束后，Scala程序会终止。迁移到Akka后，当所有的主线程结束，所有的actor systems关闭后，程序才会结束。Actor systems 需要在程序退出前明确的中止。这需要通过在Actor system中调用shutdown 方法来完成。 - -#### 远程 Actors - -当代码迁移到Akka，远程actors就不再工作了。 registerActorFor 和 alive 方法需要被移除。 在Akka中，远程控制通过配置独立的完成。更多细节请参考[Akka remoting documentation](http://doc.akka.io/docs/akka/2.1.0/scala/remoting.html)。 - -#### 样例和问题 - -这篇文档中的所有程序片段可以在[Actors Migration test suite](http://github.com/scala/actors-migration/tree/master/src/test/)中找到，这些程序做为测试文件，前缀为actmig。 - -这篇文档和Actor移植组件由 [Vojin Jovanovic](http://people.epfl.ch/vojin.jovanovic)和[Philipp Haller](http://lampwww.epfl.ch/~phaller/)编写。 - -如果你发现任何问题或不完善的地方，请把它们报告给 [Scala Bugtracker](https://github.com/scala/actors-migration/issues)。 diff --git a/_zh-cn/overviews/core/actors.md b/_zh-cn/overviews/core/actors.md deleted file mode 100644 index bdcfc6bbcb..0000000000 --- a/_zh-cn/overviews/core/actors.md +++ /dev/null @@ -1,308 +0,0 @@ ---- -layout: singlepage-overview -title: The Scala Actors API - -partof: actors - -language: zh-cn - -discourse: false ---- - -**Philipp Haller 和 Stephen Tu 著** - -## 简介 - -本指南介绍了Scala 2.8和2.9中`scala.actors`包的API。这个包的内容因为逻辑上相通，所以放到了同一个类型的包内。这个trait在每个章节里面都会有所涉及。这章的重点在于这些traits所定义的各种方法在运行状态时的行为，由此来补充现有的Scala基础API。 - -注意：在Scala 2.10版本中这个Actors库将是过时的，并且在未来Scala发布的版本中将会被移除。开发者应该使用在`akka.actor`包中[Akka](http://akka.io/) actors来替代它。想了解如何将代码从Scala actors迁移到Akka请参考[Actors 迁移指南](http://docs.scala-lang.org/overviews/core/actors-migration-guide.html)章节。 - -## Actor trait：Reactor, ReplyReactor和Actor - -### Reactor trait - -Reactor 是所有`actor trait`的父级trait。扩展这个trait可以定义actor，其具有发送和接收消息的基本功能。 - -Reactor的行为通过实现其act方法来定义。一旦调用start方法启动Reactor，这个act方法便会执行，并返回这个Reactor对象本身。start方法是具有等幂性的，也就是说，在一个已经启动了的actor对象上调用它（start方法）是没有作用的。 - -Reactor trait 有一个Msg 的类型参数，这个参数指明这个actor所能接收的消息类型。 - -调用Reactor的!方法来向接收者发送消息。用!发送消息是异步的，这样意味着不会等待消息被接收——它在发送消息后便立刻往下执行。例如：`a ! msg`表示向`a`发送`msg`。每个actor都有各自的信箱（mailbox）作为缓冲来存放接收到的消息，直至这些消息得到处理。 - -Reactor trait中也定义了一个forward方法，这个方法继承于OutputChannel。它和!（感叹号，发送方法）有同样的作用。Reactor的SubTrait（子特性）——特别是`ReplyReactor trait`——覆写了此方法，使得它能够隐式地回复目标。（详细地看下面的介绍） - -一个Reactor用react方法来接收消息。react方法需要一个PartialFunction[Msg, Unit]类型的参数，当消息到达actor的邮箱之后，react方法根据这个参数来确定如何处理消息。在下面例子中，当前的actor等待接收一个“Hello”字符串，然后打印一句问候。 - - react { - case "Hello" => println("Hi there") - } - -调用react没有返回值。因此，在接收到一条消息后，任何要执行的代码必须被包含在传递给react方法的偏函数（partial function）中。举个例子，通过嵌套两个react方法调用可以按顺序接收到两条消息： - - react { - case Get(from) => - react { - case Put(x) => from ! x - } - } - -Reactor trait 也提供了控制结构，简化了react方法的代码。 - -### 终止和执行状态 - -当Reactor的act方法完整执行后， Reactor则随即终止执行。Reactor也可以显式地使用exit方法来终止自身。exit方法的返回值类型为Nothing，因为它总是会抛出异常。这个异常仅在内部使用，并且不应该去捕捉这个异常。 - -一个已终止的Reactor可以通过它的restart方法使它重新启动。对一个未终止的Reactor调用restart方法则会抛出`IllegalStateException`异常。重新启动一个已终止的actor则会使它的act方法重新运行。 - -Reactor定义了一个getState方法，这个方法可以将actor当前的运行状态作为Actor.State枚举的一个成员返回。一个尚未运行的actor处于`Actor.State.New`状态。一个能够运行并且不在等待消息的actor处于`Actor.State.Runnable`状态。一个已挂起，并正在等待消息的actor处于`Actor.State.Suspended`状态。一个已终止的actor处于`Actor.State.Terminated`状态。 - -### 异常处理 - -exceptionHandler成员允许定义一个异常处理程序，其在Reactor的整个生命周期均可用。 - - def exceptionHandler: PartialFunction[Exception, Unit] - -exceptionHandler返回一个偏函数，它用来处理其他没有被处理的异常。每当一个异常被传递到Reactor的act方法体之外时，这个成员函数就被应用到该异常，以允许这个actor在它结束前执行清理代码。注意：`exceptionHandler`的可见性为protected。 - -用exceptionHandler来处理异常并使用控制结构对与react的编程是非常有效的。每当exceptionHandler返回的偏函数处理完一个异常后，程序会以当前的后续闭包（continuation closure）继续执行。 - - loop { - react { - case Msg(data) => - if (cond) // 数据处理代码 - else throw new Exception("cannot process data") - } - } - -假设Reactor覆写了exceptionHandler，在处理完一个在react方法体内抛出的异常后，程序将会执行下一个循环迭代。 - -### ReplyReactor trait - -`ReplyReactor trait`扩展了`Reactor[Any]`并且增加或覆写了以下方法： - -！方法被覆写以获得一个当前actor对象（发送方）的引用，并且，这个发送方引用和实际的消息一起被传递到接收actor的信箱（mail box）中。接收方通过其sender方法访问消息的发送方（见下文）。 - -forward方法被覆写以获得一个引用，这个引用指向正在被处理的消息的发送方。引用和实际的消息一起作为当前消息的发送方传递。结果，forward方法允许代表不同于当前actor对象的actor对象转发消息。 - -增加的sender方法返回正被处理的消息的发送方。考虑到一个消息可能已经被转发，发送方可能不会返回实际发送消息的actor对象。 - -增加的reply方法向最后一个消息的发送方回复消息。reply方法也被用作回复一个同步消息发送或者一个使用future的消息发送（见下文）。 - -增加的!?方法提供同步消息发送。调用!?方法会引起发送方actor对象等待，直到收到一个响应，然后返回这个响应。重载的变量有两个。这个双参数变量需要额外的超时参数（以毫秒计），并且，它的返回类型是Option[Any]而不是Any。如果发送方在指定的超时期间没有收到一个响应，!?方法返回None，否则它会返回由Some包裹的响应。 - -增加的!!方法与同步消息发送的相似点在于，它们都允许从接收方传递一个响应。然而，它们返回Future实例，而不是阻塞发送中的actor对象直到接收响应。一旦Future对象可用，它可以被用来重新获得接收方的响应，还可以在不阻塞发送方的情况下，用于获知响应是否可用。重载的变量有两个。双参数变量需要额外的PartialFunction[Any,A]类型的参数。这个偏函数用于对接收方响应进行后处理。本质上，!!方法返回一个future对象，一旦响应被接收，这个future对象把偏函数应用于响应。future对象的结果就是后处理的结果。 - -增加的reactWithin方法允许在一段给定的时间段内接收消息。相对于react方法，这个方法需要一个额外的msec参数，用来指示在这个时间段（以毫秒计）直到匹配指定的TIMEOUT模式为止（TIMEOUT是包scala.actors中的用例对象（case object））。例如： - -reactWithin(2000) { case Answer(text) => // process text case TIMEOUT => println("no answer within 2 seconds") } - -reactWithin方法也允许以非阻塞方式访问信箱。当指定一个0毫秒的时间段时，首先会扫描信箱以找到一个匹配消息。如果在第一次扫描后没有匹配的消息，这个TIMEOUT模式将会匹配。例如，这使得接收某些消息会比其他消息有较高的优先级： - -reactWithin(0) { case HighPriorityMsg => // ... case TIMEOUT => react { case LowPriorityMsg => // ... } } - -在上述例子中，即使在信箱里有一个先到达的低优先级的消息，actor对象也会首先处理下一个高优先级的消息。actor对象只有在信箱里没有高优先级消息时才会首先处理一个低优先级的消息。 - -另外，ReplyReactor 增加了`Actor.State.TimedSuspended`执行状态。一个使用`reactWithin`方法等待接收消息而挂起的actor对象，处在` Actor.State.TimedSuspended `状态。 - -### Actor trait - -Actor trait扩展了`ReplyReactor`并增加或覆写了以下成员： - -增加的receive方法的行为类似react方法，但它可以返回一个结果。这可以在它的类型上反映——它的结果是多态的：def receive[R](f: PartialFunction[Any, R]): R。然而，因为actor对象挂起并等待消息时，receive方法会阻塞底层线程（underlying thread），使用receive方法使actor对象变得更加重量级。直到receive方法的调用返回，阻塞的线程将不能够执行其他actor对象。 - -增加的link和unlink方法允许一个actor对象将自身链接到另一个actor对象，或将自身从另一个actor对象断开链接。链接可以用来监控或对另一个actor对象的终止做出反应。特别要注意的是，正如在Actor trait的API文档中的解释，链接影响调用exit方法的行为。 - -trapExit成员允许对链接的actor对象的终止做出反应而无关其退出的原因（即，无关是否正常退出）。如果一个actor对象的trapExit成员被设置为true，则这个actor对象会因链接的actor对象而永远不会终止。相反，每当其中一个链接的actor对象个终止了，它将会收到类型为Exit的消息。这个Exit case class 有两个成员：from指终止的actor对象；reason指退出原因。 - -### 终止和执行状态 - -当终止一个actor对象的执行时，可以通过调用以下exit方法的变体，显式地设置退出原因： - - def exit(reason: AnyRef): Nothing -当一个actor对象以符号'normal以外的原因退出，会向所有链接到它的atocr对象传递其退出原因。如果一个actor对象由于一个未捕获异常终止，它的退出原因则为一个UncaughtException case class的实例。 - -Actor trait增加了两个新的执行状态。使用receive方法并正在等待接收消息的actor处在`Actor.State.Blocked`状态。使用receiveWithin方法并正在等待接收消息的actor处在`Actor.State.TimedBlocked`状态。 - -## 控制结构 - -Reactor trait定义了控制结构，它简化了无返回的react操作的编程。一般来说，一个react方法调用并不返回。如果actor对象随后应当执行代码，那么，或者显式传递actor对象的后续代码给react方法，或者可以使用下述控制结构，达到隐藏这些延续代码的目的。 - -最基础的控制结构是andThen，它允许注册一个闭包。一旦actor对象的所有其他代码执行完毕，闭包就会被执行。 - - actor { - { - react { - case "hello" => // 处理 "hello" - }: Unit - } andThen { - println("hi there") - } - } - -例如，上述actor实例在它处理了“hello”消息之后，打印一句问候。虽然调用react方法不会返回，我们仍然可以使用andThen来注册这段输出问候的代码（作为actor的延续）。 - -注意：在react方法的调用（: Unit）中存在一种类型归属。总而言之，既然表达式的结果经常可以被忽略，react方法的结果就可以合法地作为Unit类型来处理。andThen方法无法成为Nothing类型（react方法的结果类型）的一个成员，所以在这里有必要这样做。把react方法的结果类型当作Unit，允许实现一个隐式转换的应用，这个隐式转换使得andThen成员可用。 - -API还提供一些额外的控制结构： - -loop { ... }。无限循环，在每一次迭代中，执行括号中的代码。调用循环体内的react方法，actor对象同样会对消息做出反应。而后，继续执行这个循环的下次迭代。 - -loopWhile (c) { ... }。当条件c返回true，执行括号中的代码。调用循环体中的react方法和使用loop时的效果一样。 - -continue。继续执行当前的接下来的后续闭包（continuation closure）。在loop或loopWhile循环体内调用continue方法将会使actor对象结束当前的迭代并继续执行下次迭代。如果使用andThen注册了当前的后续代码，这个闭包会作为第二个参数传给andThen，并以此继续执行。 - -控制结构可以在Reactor对象的act方法中，以及在act方法（传递地）调用的方法中任意处使用。对于用actor{...}这样的缩略形式创建的actor，控制结构可以从Actor对象导入。 - -### Future - -ReplyReactor和Actor trait支持发送带有结果的消息（!!方法），其立即返回一个future实例。一个future即Future trait的一个实例，即可以用来重新获取一个send-with-future消息的响应的句柄。 - -一个send-with-future消息的发送方可以通过应用future来等待future的响应。例如，使用val fut = a !! msg 语句发送消息，允许发送方等待future的结果。如：val res = fut()。 - -另外，一个Future可以在不阻塞的情况下，通过isSet方法来查询并获知其结果是否可用。 - -send-with-future的消息并不是获得future的唯一的方法。future也可以通过future方法计算而得。下述例子中，计算体会被并行地启动运行，并返回一个future实例作为其结果： - - val fut = Future { body } - // ... - fut() // 等待future - -能够通过基于actor的标准接收操作（例如receive方法等）来取回future的结果，使得future实例在actor上下文中变得特殊。此外，也能够通过使用基于事件的操作（react方法和ractWithin方法）。这使得一个actor实例在等待一个future实例结果时不用阻塞它的底层线程。 - -通过future的inputChannel，使得基于actor的接收操作方法可用。对于一个类型为`Future[T]`的future对象而言，它的类型是`InputChannel[T]`。例如： - - val fut = a !! msg - // ... - fut.inputChannel.react { - case Response => // ... - } - -## Channel（通道） - -channnel可以用来对发送到同一actor的不同类型消息的处理进行简化。channel的层级被分为OutputChannel和InputChannel。 - -OutputChannel可用于发送消息。OutputChannel的out方法支持以下操作。 - -out ! msg。异步地向out方法发送msg。当msg直接发送给一个actor，一个发送中的actor的引用会被传递。 - -out forward msg。异步地转发msg给out方法。当msg被直接转发给一个actor，发送中的actor会被确定。 - -out.receiver。返回唯一的actor，其接收发送到out channel（通道）的消息。 - -out.send(msg, from)。异步地发送msg到out，并提供from作为消息的发送方。 - -注意：OutputChannel trait有一个类型参数，其指定了可以被发送到channel（通道）的消息类型（使用!、forward和send）。这个类型参数是逆变的： - - trait OutputChannel[-Msg] - -Actor能够从InputChannel接收消息。就像OutputChannel，InputChannel trait也有一个类型参数，用于指定可以从channel（通道）接收的消息类型。这个类型参数是协变的： - - trait InputChannel[+Msg] - -An` InputChannel[Msg] `in支持下列操作。 - -in.receive { case Pat1 => ... ; case Patn => ... }（以及类似的 in.receiveWithin）。从in接收一个消息。在一个输入channel（通道）上调用receive方法和actor的标准receive操作具有相同的语义。唯一的区别是，作为参数被传递的偏函数具有PartialFunction[Msg, R]类型，此处R是receive方法的返回类型。 - -in.react { case Pat1 => ... ; case Patn => ... }（以及类似的in.reactWithin）通过基于事件的react操作，从in方法接收一个消息。就像actor的react方法，返回类型是Nothing。这意味着此方法的调用不会返回。就像之前的receive操作，作为参数传递的偏函数有一个更具体的类型：PartialFunction[Msg, Unit] - -### 创建和共享channel - -channel通过使用具体的Channel类创建。它同时扩展了InputChannel和OutputChannel。使channel在多个actor的作用域（Scope）中可见，或者将其在消息中发送，都可以实现channel的共享。 - -下面的例子阐述了基于作用域（scope）的共享。 - - actor { - var out: OutputChannel[String] = null - val child = actor { - react { - case "go" => out ! "hello" - } - } - val channel = new Channel[String] - out = channel - child ! "go" - channel.receive { - case msg => println(msg.length) - } - } - -运行这个例子将输出字符串“5”到控制台。注意：子actor对out（一个OutputChannel[String]）具有唯一的访问权。而用于接收消息的channel的引用则被隐藏了。然而，必须要注意的是，在子actor向输出channel发送消息之前，确保输出channel被初始化到一个具体的channel。通过使用“go”消息来完成消息发送。当使用channel.receive来从channel接收消息时，因为消息是String类型的，可以使用它提供的length成员。 - -另一种共享channel的可行的方法是在消息中发送它们。下面的例子对此作了阐述。 - - case class ReplyTo(out: OutputChannel[String]) - - val child = actor { - react { - case ReplyTo(out) => out ! "hello" - } - } - - actor { - val channel = new Channel[String] - child ! ReplyTo(channel) - channel.receive { - case msg => println(msg.length) - } - } - -ReplyTo case class是一个消息类型，用于分派一个引用到OutputChannel[String]。当子actor接收一个ReplyTo消息时，它向它的输出channel发送一个字符串。第二个actor则像以前一样接收那个channel上的消息。 - -## Scheduler - -scheduler用于执行一个Reactor实例（或子类型的一个实例）。Reactor trait引入了scheduler成员，其返回常用于执行Reactor实例的scheduler。 - - def scheduler: IScheduler - -运行时系统通过使用在IScheduler trait中定义的execute方法之一，向scheduler提交任务来执行actor。只有在完整实现一个新的scheduler时（但没有必要），此trait的大多数其他方法才是相关的。 - -默认的scheduler常用于执行Reactor实例，而当所有的actor完成其执行时，Actor则会检测环境。当这发生时，scheduler把它自己关闭（终止scheduler使用的任何线程）。然而，一些scheduler，比如SingleThreadedScheduler（位于scheduler包）必须要通过调用它们的shutdown方法显式地关闭。 - -创建自定义scheduler的最简单方法是通过扩展SchedulerAdapter，实现下面的抽象成员： - - def execute(fun: => Unit): Unit - -典型情况下，一个具体的实现将会使用线程池来执行它的按名参数fun。 - -## 远程Actor - -这一段描述了远程actor的API。它的主要接口是scala.actors.remote包中的RemoteActor对象。这个对象提供各种方法来创建和连接到远程actor实例。在下面的代码段中我们假设所有的RemoteActor成员都已被导入，所使用的完整导入列表如下： - - import scala.actors._ - import scala.actors.Actor._ - import scala.actors.remote._ - import scala.actors.remote.RemoteActor._ - -### 启动远程Actor - -远程actor由一个Symbol唯一标记。在这个远程Actor所执行JVM上，这个符号对于JVM实例是唯一的。由名称'myActor标记的远程actor可按如下方法创建。 - - class MyActor extends Actor { - def act() { - alive(9000) - register('myActor, self) - // ... - } - } - -记住：一个名字一次只能标记到一个单独的（存活的）actor。例如，想要标记一个actorA为'myActor，然后标记另一个actorB为'myActor。这种情况下，必须等待A终止。这个要求适用于所有的端口，因此简单地将B标记到不同的端口来作为A是不能满足要求的。 - -### 连接到远程Actor - -连接到一个远程actor也同样简单。为了获得一个远程Actor的远程引用（运行于机器名为myMachine，端口为8000，名称为'anActor），可按下述方式使用select方法： - - val myRemoteActor = select(Node("myMachine", 8000), 'anActor) - -从select函数返回的actor具有类型AbstractActor，这个类型本质上提供了和通常actor相同的接口，因此支持通常的消息发送操作： - - myRemoteActor ! "Hello!" - receive { - case response => println("Response: " + response) - } - myRemoteActor !? "What is the meaning of life?" match { - case 42 => println("Success") - case oops => println("Failed: " + oops) - } - val future = myRemoteActor !! "What is the last digit of PI?" - -记住：select方法是惰性的，它不实际初始化任何网络连接。仅当必要时（例如，调用!时），它会单纯地创建一个新的，准备好初始化新网络连接的AbstractActor实例。 diff --git a/_zh-cn/overviews/core/architecture-of-scala-collections.md b/_zh-cn/overviews/core/architecture-of-scala-collections.md index df77d22150..c038d02e03 100644 --- a/_zh-cn/overviews/core/architecture-of-scala-collections.md +++ b/_zh-cn/overviews/core/architecture-of-scala-collections.md @@ -5,15 +5,13 @@ title: Scala容器类体系结构 partof: collections-architecture language: zh-cn - -discourse: false --- **Martin Odersky 和 Lex Spoon 著** -本篇详细的介绍了Scala 容器类(collections)框架。通过与 [Scala 2.8 的 Collection API](http://docs.scala-lang.org/overviews/collections/introduction.html) 的对比，你会了解到更多框架的内部运作方式，同时你也将学习到如何通过几行代码复用这个容器类框架的功能来定义自己的容器类。 +本篇详细的介绍了Scala 容器类(collections)框架。通过与 [Scala 2.8 的 Collection API](https://docs.scala-lang.org/overviews/collections/introduction.html) 的对比，你会了解到更多框架的内部运作方式，同时你也将学习到如何通过几行代码复用这个容器类框架的功能来定义自己的容器类。 -[Scala 2.8 容器API](http://docs.scala-lang.org/overviews/collections/introduction.html) 中包含了大量的 容器(collection)操作，这些操作在不同的许多容器类上表现为一致。假设，为每种 Collection 类型都用不同的方法代码实现，那么将导致代码的异常臃肿，很多代码将会仅仅是别处代码的拷贝。随着时间的推移，这些重复的代码也会带来不一致的问题，试想，相同的代码，在某个地方被修改了，而另外的地方却被遗漏了。而新的 容器类（collections）框架的设计原则目标就是尽量的避免重复，在尽可能少的地方定义操作（理想情况下，只在一处定义，当然也会有例外的情况存在）。设计中使用的方法是，在 Collection 模板中实现大部分的操作，这样就可以灵活的从独立的基类和实现中继承。后面的部分，我们会来详细阐述框架的各组成部分：模板(templates)、类(classes)以及trait(译注：类似于java里接口的概念)，也会说明他们所支持的构建原则。 +[Scala 2.8 容器API](https://docs.scala-lang.org/overviews/collections/introduction.html) 中包含了大量的 容器(collection)操作，这些操作在不同的许多容器类上表现为一致。假设，为每种 Collection 类型都用不同的方法代码实现，那么将导致代码的异常臃肿，很多代码将会仅仅是别处代码的拷贝。随着时间的推移，这些重复的代码也会带来不一致的问题，试想，相同的代码，在某个地方被修改了，而另外的地方却被遗漏了。而新的 容器类（collections）框架的设计原则目标就是尽量的避免重复，在尽可能少的地方定义操作（理想情况下，只在一处定义，当然也会有例外的情况存在）。设计中使用的方法是，在 Collection 模板中实现大部分的操作，这样就可以灵活的从独立的基类和实现中继承。后面的部分，我们会来详细阐述框架的各组成部分：模板(templates)、类(classes)以及trait(译注：类似于java里接口的概念)，也会说明他们所支持的构建原则。 ## Builders @@ -149,7 +147,7 @@ CanBuildFrom trait： ### 集成序列（Sequence） -RNA（核糖核酸）碱基（译者注：RNA链即很多不同RNA碱基的序列，RNA参考资料：http://zh.wikipedia.org/wiki/RNA）： +RNA（核糖核酸）碱基（译者注：RNA链即很多不同RNA碱基的序列，RNA参考资料：https://zh.wikipedia.org/wiki/RNA）： abstract class Base case object A extends Base @@ -540,4 +538,4 @@ prefix map的伴生对象： ### 致谢 -这些页面的素材改编自，由Odersky，Spoon和Venners编写的[Scala编程](http://www.artima.com/shop/programming_in_scala)第2版 。感谢Artima 对于出版的大力支持。 +这些页面的素材改编自，由Odersky，Spoon和Venners编写的[Scala编程](https://www.artima.com/shop/programming_in_scala)第2版 。感谢Artima 对于出版的大力支持。 diff --git a/_zh-cn/overviews/core/futures.md b/_zh-cn/overviews/core/futures.md index 1a23602965..97f64ed7aa 100644 --- a/_zh-cn/overviews/core/futures.md +++ b/_zh-cn/overviews/core/futures.md @@ -5,499 +5,1260 @@ title: Future和Promise partof: futures language: zh-cn - -discourse: false --- **Philipp Haller, Aleksandar Prokopec, Heather Miller, Viktor Klang, Roland Kuhn, and Vojin Jovanovic 著** ## 简介 -Future提供了一套高效便捷的非阻塞并行操作管理方案。其基本思想很简单，所谓Future，指的是一类占位符对象，用于指代某些尚未完成的计算的结果。一般来说，由Future指代的计算都是并行执行的，计算完毕后可另行获取相关计算结果。以这种方式组织并行任务，便可以写出高效、异步、非阻塞的并行代码。 +Future提供了一套高效便捷的非阻塞并行操作管理方案。其基本思想很简单，所谓 [`Future`](https://www.scala-lang.org/api/current/scala/concurrent/Future.html)，指的是一类占位符对象，用于指代某些尚未完成的计算的结果。一般来说，由Future指代的计算都是并行执行的，计算完毕后可另行获取相关计算结果。以这种方式组织并行任务，便可以写出高效、异步、非阻塞的并行代码。 + +默认情况下，future和promise并不采用一般的阻塞操作，而是依赖回调进行非阻塞操作。为了在语法和概念层面更加简明扼要地使用这些回调，Scala还提供了 `flatMap`、`foreach` 和 `filter` 等算子，使得我们能够以非阻塞的方式对future进行组合。 +当然，future仍然支持阻塞操作——必要时，可以阻塞等待future（不过并不鼓励这样做）。 + + + +典型的 future 像这样： + +{% tabs futures-00 %} +{% tab 'Scala 2 and 3' for=futures-00 %} + +```scala +val inverseFuture: Future[Matrix] = Future { + fatMatrix.inverse() // non-blocking long lasting computation +}(executionContext) +``` + +{% endtab %} +{% endtabs %} + +或者更习惯的用法： + +{% tabs futures-01 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-01 %} + +```scala +implicit val ec: ExecutionContext = ... +val inverseFuture : Future[Matrix] = Future { + fatMatrix.inverse() +} // ec is implicitly passed +``` + +{% endtab %} + +{% tab 'Scala 3' for=futures-01 %} + +```scala +given ExecutionContext = ... +val inverseFuture : Future[Matrix] = Future { + fatMatrix.inverse() +} // execution context is implicitly passed +``` + +{% endtab %} +{% endtabs %} + +这两个代码片段都将 `fatMatrix.inverse()` 的执行委托给 `ExecutionContext`，并在 `inverseFuture` 中体现计算结果。 + +## 执行上下文 + +Future 和 Promises 围绕 [`ExecutionContext`s](https://www.scala-lang.org/api/current/scala/concurrent/ExecutionContext.html) 展开，负责执行计算。 + +`ExecutionContext` 类似于 [Executor](https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executor.html)： +它可以在新线程、线程池或当前线程中自由地执行计算（尽管不鼓励在当前线程中执行计算 -- 更多内容见下文）。 + +`scala.concurrent` 包是开箱即用的，它带有 `ExecutionContext` 实现，一个全局静态线程池。 +它也可以将 `Exector` 转换为 `ExecutionContext`。 +最后，用户可以自由扩展 `ExecutionContext` trait来实现自己的执行上下文，但只有极少数情况下需要这么做。 + +### 全局执行上下文 + +`ExecutionContext.global` 是由 [ForkJoinPool](https://docs.oracle.com/javase/tutorial/essential/concurrency/forkjoin.html) 支持的 `ExecutionContext`。 +它应该满足大部分情况，但有几点需要注意。 +`ForkJoinPool` 管理有限数量的线程（线程的最大数量由 *parallelism level* 指定）。 +仅当每个阻塞调用都包装在 `blocking` 调用中时（更多内容见下文），并发阻塞计算的数量才能超过并行度级别。 +否则，全局执行上下文中的线程池会有饥饿死锁风险，致使任何计算无法继续进行。 +缺省情况下，`ExecutionContext.global` 将其底层ForkJoin连接池的并行级别设置为可用处理器的数量([Runtime.availableProcessors](https://docs.oracle.com/javase/7/docs/api/java/lang/Runtime.html#availableProcessors%28%29))。 +通过设置以下一个（或多个） VM 属性，来重载这个设置： + + * scala.concurrent.context.minThreads - 缺省为 `Runtime.availableProcessors` + * scala.concurrent.context.numThreads - 可以是一个数字，或者是 “xN” 这样形式中的乘数（N）；缺省为 `Runtime.availableProcessors` + * scala.concurrent.context.maxThreads - 缺省为 `Runtime.availableProcessors` + +只要并行度的数值在 `[minThreads; maxThreads]` 范围内，它就可以给 `numThreads` 赋值。 + +如上所述，在存在阻塞计算的情况下，`ForkJoinPool` 可以将线程数增加到超过 `parallelismLevel`。 +如 `ForkJoinPool` API 中所述，这只有在明确通知 `ForkJoinPool` 时才有可能： + +{% tabs futures-02 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-02 %} + +```scala +import scala.concurrent.{ Future, ExecutionContext } +import scala.concurrent.forkjoin._ + +// the following is equivalent to `implicit val ec = ExecutionContext.global` +import ExecutionContext.Implicits.global + +Future { + ForkJoinPool.managedBlock( + new ManagedBlocker { + var done = false + + def block(): Boolean = { + try { + myLock.lock() + // ... + } finally { + done = true + } + true + } + + def isReleasable: Boolean = done + } + ) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-02 %} + +```scala +import scala.concurrent.{ Future, ExecutionContext } +import scala.concurrent.forkjoin.* + +// the following is equivalent to `given ExecutionContext = ExecutionContext.global` +import ExecutionContext.Implicits.global + +Future { + ForkJoinPool.managedBlock( + new ManagedBlocker { + var done = false + + def block(): Boolean = + try + myLock.lock() + // ... + finally + done = true + true + + def isReleasable: Boolean = done + } + ) +} +``` +{% endtab %} +{% endtabs %} + +幸运的是，并发包为这提供了便捷的方法： + +{% tabs blocking %} +{% tab 'Scala 2 and 3' for=blocking %} + +```scala +import scala.concurrent.Future +import scala.concurrent.blocking + +Future { + blocking { + myLock.lock() + // ... + } +} +``` + +{% endtab %} +{% endtabs %} + +注意 `blocking` 是一个通用结构，它将会在[下面](#future-内的阻塞)作深入探讨。 + +最后你必须记住 `ForkJoinPool` 不是设计用来长连接阻塞操作。 +即使收到 `blocking` 通知，池也可能无法像预期的那样生成新工作，而创建新工作线程时，它们的数量也可能多达 32767。 +为了给您有个概念，以下代码将使用 32000 个线程： + +{% tabs futures-03 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-03 %} + +```scala +implicit val ec = ExecutionContext.global + +for (i <- 1 to 32000) { + Future { + blocking { + Thread.sleep(999999) + } + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-03 %} + +```scala +given ExecutionContext = ExecutionContext.global + +for i <- 1 to 32000 do + Future { + blocking { + Thread.sleep(999999) + } + } +``` + +{% endtab %} +{% endtabs %} + +如果您需要包装持久的阻塞操作，我们建议使用专用的 `ExecutionContext`，例如通过包装Java 的 `Executor`。 + +### 适配 Java Executor + +使用 `ExecutionContext.fromExecutor` 方法，你可以把 `Executor` 包装进 `ExecutionContext`。 +例如： + +{% tabs executor class=tabs-scala-version %} +{% tab 'Scala 2' for=executor %} + +```scala +ExecutionContext.fromExecutor(new ThreadPoolExecutor( /* your configuration */ )) +``` -默认情况下，future和promise并不采用一般的阻塞操作，而是依赖回调进行非阻塞操作。为了在语法和概念层面更加简明扼要地使用这些回调，Scala还提供了flatMap、foreach和filter等算子，使得我们能够以非阻塞的方式对future进行组合。当然，future仍然支持阻塞操作——必要时，可以阻塞等待future（不过并不鼓励这样做）。 +{% endtab %} +{% tab 'Scala 3' for=executor %} + +```scala +ExecutionContext.fromExecutor(ThreadPoolExecutor( /* your configuration */ )) +``` + +{% endtab %} +{% endtabs %} + +### 同步执行上下文 + +也许试图得到一个在当前线程中运行计算的 `ExecutionContext`： + +{% tabs bad-example %} +{% tab 'Scala 2 and 3' for=bad-example %} + +```scala +val currentThreadExecutionContext = ExecutionContext.fromExecutor( + new Executor { + // Do not do this! + def execute(runnable: Runnable) = runnable.run() + }) +``` + +{% endtab %} +{% endtabs %} + +应该避免这种情况，因为它会在执行 future 时引入不确定性。 + +{% tabs bad-example-2 %} +{% tab 'Scala 2 and 3' for=bad-example-2 %} + +```scala +Future { + doSomething +}(ExecutionContext.global).map { + doSomethingElse +}(currentThreadExecutionContext) +``` + +{% endtab %} +{% endtabs %} + +`doSomethingElse` 调用，可能在 `doSomething` 的线程中执行或者在主线程中执行，这样可以是同步的或者是异步的。 +正如[这里](https://blog.ometer.com/2011/07/24/callbacks-synchronous-and-asynchronous/)解释的，一个调用不能两者都是。 ## Future 所谓Future，是一种用于指代某个尚未就绪的值的对象。而这个值，往往是某个计算过程的结果： -- 若该计算过程尚未完成，我们就说该Future未就位； -- 若该计算过程正常结束，或中途抛出异常，我们就说该Future已就位。 +1. 若该计算过程尚未完成，我们就说该Future **未就位**； +2. 若该计算过程正常结束，或中途抛出异常，我们就说该Future **已就位**。 Future的就位分为两种情况： -- 当Future带着某个值就位时，我们就说该Future携带计算结果成功就位。 -- 当Future因对应计算过程抛出异常而就绪，我们就说这个Future因该异常而失败。 +1. 当 `Future` 带着某个值就位时，我们就说该 future 携带计算结果**成功就位**。 +2. 当 `Future` 因对应计算过程抛出异常而就绪，我们就说这个 future因该异常而**失败**。 -Future的一个重要属性在于它只能被赋值一次。一旦给定了某个值或某个异常，future对象就变成了不可变对象——无法再被改写。 +`Future` 的一个重要属性在于它只能被赋值一次。一旦给定了某个值或某个异常，`Future` 对象就变成了不可变对象——无法再被改写。 -创建future对象最简单的方法是调用future方法，该future方法启用异步(asynchronous)计算并返回保存有计算结果的futrue，一旦该future对象计算完成，其结果就变的可用。 +创建future对象最简单的方法是调用 `Future.apply` 方法，该future方法启用异步(asynchronous)计算并返回保存有计算结果的futrue，一旦该future对象计算完成，其结果就变的可用。 -注意_Future[T]_ 是表示future对象的类型，而future是方法，该方法创建和调度一个异步计算，并返回随着计算结果而完成的future对象。 +注意 _Future[T]_ 是表示future对象的类型，而 `Future.apply` 是方法，该方法创建和调度一个异步计算，并返回随着计算结果而完成的future对象。 这最好通过一个例子予以说明。 假设我们使用某些流行的社交网络的假定API获取某个用户的朋友列表，我们将打开一个新对话(session)，然后发送一个请求来获取某个特定用户的好友列表。 - import scala.concurrent._ - import ExecutionContext.Implicits.global +{% tabs futures-04 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-04 %} - val session = socialNetwork.createSessionFor("user", credentials) - val f: Future[List[Friend]] = Future { - session.getFriends() - } +```scala +import scala.concurrent._ +import ExecutionContext.Implicits.global -以上，首先导入scala.concurrent 包使得Future类型和future构造函数可见。我们将马上解释第二个导入。 +val session = socialNetwork.createSessionFor("user", credentials) +val f: Future[List[Friend]] = Future { + session.getFriends() +} +``` -然后我们初始化一个session变量来用作向服务器发送请求，用一个假想的 createSessionFor 方法来返回一个List[Friend]。为了获得朋友列表，我们必须通过网络发送一个请求，这个请求可能耗时很长。这能从调用getFriends方法得到解释。为了更好的利用CPU，响应到达前不应该阻塞(block)程序的其他部分执行，于是在计算中使用异步。future方法就是这样做的，它并行地执行指定的计算块，在这个例子中是向服务器发送请求和等待响应。 +{% endtab %} +{% tab 'Scala 3' for=futures-04 %} -一旦服务器响应，future f 中的好友列表将变得可用。 +```scala +import scala.concurrent.* +import ExecutionContext.Implicits.global -未成功的尝试可能会导致一个异常(exception)。在下面的例子中，session的值未被正确的初始化，于是在future的计算中将抛出NullPointerException，future f 不会圆满完成，而是以此异常失败。 +val session = socialNetwork.createSessionFor("user", credentials) +val f: Future[List[Friend]] = Future { + session.getFriends() +} +``` - val session = null - val f: Future[List[Friend]] = Future { - session.getFriends - } +{% endtab %} +{% endtabs %} -`import ExecutionContext.Implicits.global` 上面的线条导入默认的全局执行上下文(global execution context)，执行上下文执行执行提交给他们的任务，也可把执行上下文看作线程池，这对于future方法来说是必不可少的，因为这可以处理异步计算如何及何时被执行。我们可以定义自己的执行上下文，并在future上使用它，但是现在只需要知道你能够通过上面的语句导入默认执行上下文就足够了。 +以上，首先导入 `scala.concurrent` 包使得 `Future` 类型可见。 +我们将马上解释第二个导入。 -我们的例子是基于一个假定的社交网络API，此API的计算包含发送网络请求和等待响应。提供一个涉及到你能试着立即使用的异步计算的例子是公平的。假设你有一个文本文件，你想找出一个特定的关键字第一次出现的位置。当磁盘正在检索此文件内容时，这种计算可能会陷入阻塞，因此并行的执行该操作和程序的其他部分是合理的(make sense)。 +然后我们用一个假想的 `createSessionFor` 方法去初始化一个session变量，该变量用作向服务器发送请求。 +为了获得朋友列表，我们必须通过网络发送一个请求，这个请求可能耗时很长。 +这能从调用 `getFriends` 方法得到解释，该方法返回 `List[Friend]`。 +为了更好的利用CPU，响应到达前不应该阻塞(block)程序的其他部分执行，于是在计算中使用异步。`Future.apply` 方法就是这样做的，它并行地执行指定的计算块，在这个例子中是向服务器发送请求和等待响应。 - val firstOccurrence: Future[Int] = Future { - val source = scala.io.Source.fromFile("myText.txt") - source.toSeq.indexOfSlice("myKeyword") - } +一旦服务器响应，future `f` 中的好友列表将变得可用。 + +未成功的尝试可能会导致一个异常(exception)。在下面的例子中，`session` 的值未被正确的初始化，于是在 `Future` 阻塞中的计算将抛出 `NullPointerException`。 +该future `f` 不会圆满完成，而是以此异常失败： + +{% tabs futures-04b %} +{% tab 'Scala 2 and 3' for=futures-04b %} + +```scala +val session = null +val f: Future[List[Friend]] = Future { + session.getFriends +} +``` + +{% endtab %} +{% endtabs %} + +上面 `import ExecutionContext.Implicits.global` 这行，导入默认的全局执行上下文(global execution context)。 +执行上下文执行提交给他们的任务，也可把执行上下文看作线程池。 +这对于 `Future.apply` 方法来说是必不可少的，因为这可以处理异步计算如何及何时被执行。 +可以定义自己的执行上下文，并在 `Future` 上使用它，但是现在只需要知道你能够通过上面的语句导入默认执行上下文就足够了。 + +我们的例子是基于一个假定的社交网络 API，此 API 的计算包含发送网络请求和等待响应。 +提供一个涉及到你能试着立即使用的异步计算的例子是公平的。假设你有一个文本文件，你想找出一个特定的关键字第一次出现的位置。 +当磁盘正在检索此文件内容时，这种计算可能会陷入阻塞，因此并行的执行该操作和程序的其他部分是合理的(make sense)。 + +{% tabs futures-04c %} +{% tab 'Scala 2 and 3' for=futures-04c %} + +```scala +val firstOccurrence: Future[Int] = Future { + val source = scala.io.Source.fromFile("myText.txt") + source.toSeq.indexOfSlice("myKeyword") +} +``` + +{% endtab %} +{% endtabs %} ### Callbacks(回调函数) -现在我们知道如何开始一个异步计算来创建一个新的future值，但是我们没有展示一旦此结果变得可用后如何来使用，以便我们能够用它来做一些有用的事。我们经常对计算结果感兴趣而不仅仅是它的副作用。 +现在我们知道如何开始一个异步计算来创建一个新的future值，但是我们没有展示一旦此结果变得可用后如何来使用，以便我们能够用它来做一些有用的事。 +我们经常对计算结果感兴趣而不仅仅是它的副作用。 -在许多future的实现中，一旦future的client对future的结果感兴趣，它不得不阻塞它自己的计算直到future完成——然后才能使用future的值继续它自己的计算。虽然这在Scala的Future API（在后面会展示）中是允许的，但是从性能的角度来看更好的办法是一种完全非阻塞的方法，即在future中注册一个回调，future完成后这个回调称为异步回调。如果当注册回调时future已经完成，则回调可能是异步执行的，或在相同的线程中循序执行。 +在许多future的实现中，一旦future的client对future的结果感兴趣，它不得不阻塞它自己的计算直到future完成——然后才能使用future的值继续它自己的计算。 +虽然这在Scala的Future API（在后面会展示）中是允许的，但是从性能的角度来看更好的办法是一种完全非阻塞的方法，即在future中注册一个回调。 +future 完成后这个回调称为异步回调。如果当注册回调时 future 已经完成，则回调可能是异步执行的，或在相同的线程中循序执行。 -注册回调最通常的形式是使用OnComplete方法，即创建一个`Try[T] => U`类型的回调函数。如果future成功完成，回调则会应用到Success[T]类型的值中，否则应用到` Failure[T] `类型的值中。 +注册回调最通常的形式是使用 `OnComplete` 方法，即创建一个``Try[T] => U` 类型的回调函数。 +如果future成功完成，回调则会应用到 `Success[T]` 类型的值中，否则应用到 `Failure[T]` 类型的值中。 - `Try[T]` 和`Option[T]`或 `Either[T, S]`相似，因为它是一个可能持有某种类型值的单子。然而，它是特意设计来保持一个值或某个可抛出(throwable)对象。`Option[T]` 既可以是一个值（如：`Some[T]`）也可以是完全无值（如：`None`），如果`Try[T]`获得一个值则它为`Success[T]` ，否则为`Failure[T]`的异常。 `Failure[T]` 获得更多的关于为什么这儿没值的信息，而不仅仅是None。同时也可以把`Try[T]`看作一种特殊版本的`Either[Throwable, T]`，专门用于左值为可抛出类型(Throwable)的情形。 + `Try[T]` 和`Option[T]`或 `Either[T, S]`相似，因为它是一个可能持有某种类型值的单子。 + 然而，它是特意设计来保持一个值或某个可抛出(throwable)对象。 + `Option[T]` 既可以是一个值（如：`Some[T]`）也可以是完全无值（如：`None`），如果 `Try[T]` 获得一个值则它为 `Success[T]`，否则为 `Failure[T]` 的异常。`Failure[T]` 获得更多的关于为什么这儿没值的信息，而不仅仅是 `None`。 + 同时也可以把 `Try[T]` 看作一种特殊版本的 `Either[Throwable, T]`，专门用于左值为可抛出类型(Throwable)的情形。 -回到我们的社交网络的例子，假设我们想要获取我们最近的帖子并显示在屏幕上，我们通过调用getRecentPosts方法获得一个返回值List[String]——一个近期帖子的列表文本： +回到我们的社交网络的例子，假设我们想要获取我们最近的帖子并显示在屏幕上，我们通过调用 `getRecentPosts` 方法获得一个返回值 `List[String]` -- 一个近期帖子的列表文本： - val f: Future[List[String]] = Future { - session.getRecentPosts - } +{% tabs futures-05 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-05 %} - f onComplete { - case Success(posts) => for (post <- posts) println(post) - case Failure(t) => println("An error has occured: " + t.getMessage) - } +```scala +import scala.util.{Success, Failure} +val f: Future[List[String]] = Future { + session.getRecentPosts +} -onComplete方法一般在某种意义上它允许客户处理future计算出的成功或失败的结果。对于仅仅处理成功的结果，onSuccess 回调使用如下（该回调以一个偏函数(partial function)为参数）： +f.onComplete { + case Success(posts) => for (post <- posts) println(post) + case Failure(t) => println("An error has occured: " + t.getMessage) +} +``` - val f: Future[List[String]] = Future { - session.getRecentPosts - } +{% endtab %} +{% tab 'Scala 3' for=futures-05 %} - f onSuccess { - case posts => for (post <- posts) println(post) - } +```scala +import scala.util.{Success, Failure} -对于处理失败结果，onFailure回调使用如下： +val f: Future[List[String]] = Future { + session.getRecentPosts() +} - val f: Future[List[String]] = Future { - session.getRecentPosts - } +f.onComplete { + case Success(posts) => for post <- posts do println(post) + case Failure(t) => println("An error has occurred: " + t.getMessage) +} +``` - f onFailure { - case t => println("An error has occured: " + t.getMessage) - } +{% endtab %} +{% endtabs %} - f onSuccess { - case posts => for (post <- posts) println(post) - } +`onComplete` 方法一般在某种意义上它允许客户处理future计算出的成功或失败的结果。对于仅仅处理成功的结果，可以使用 `foreach` 回调： -如果future失败，即future抛出异常，则执行onFailure回调。 +{% tabs futures-06 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-06 %} -因为偏函数具有 isDefinedAt方法， onFailure方法只有在特定的Throwable类型对象中被定义才会触发。下面例子中的onFailure回调永远不会被触发： +```scala +val f: Future[List[String]] = Future { + session.getRecentPosts() +} - val f = Future { - 2 / 0 - } +for { + posts <- f + post <- posts +} println(post) +``` - f onFailure { - case npe: NullPointerException => - println("I'd be amazed if this printed out.") - } +{% endtab %} +{% tab 'Scala 3' for=futures-06 %} + +```scala +val f: Future[List[String]] = Future { + session.getRecentPosts() +} + +for + posts <- f + post <- posts +do println(post) +``` + +{% endtab %} +{% endtabs %} + +`Future` 提供了一个清晰的手段只用来处理失败的结果，这个手段是使用 `failed` 投影，这个投影把 `Failure[Throwable]` 转换成 `Success[Throwable]`。下面的[投影](#投影)章节提供了这样一个例子。 回到前面查找某个关键字第一次出现的例子，我们想要在屏幕上打印出此关键字的位置： - val firstOccurrence: Future[Int] = Future { - val source = scala.io.Source.fromFile("myText.txt") - source.toSeq.indexOfSlice("myKeyword") - } +{% tabs futures-oncomplete %} +{% tab 'Scala 2 and 3' for=futures-oncomplete %} - firstOccurrence onSuccess { - case idx => println("The keyword first appears at position: " + idx) - } +```scala +val firstOccurrence: Future[Int] = Future { + val source = scala.io.Source.fromFile("myText.txt") + source.toSeq.indexOfSlice("myKeyword") +} - firstOccurrence onFailure { - case t => println("Could not process file: " + t.getMessage) - } +firstOccurrence.onComplete { + case Success(idx) => println("The keyword first appears at position: " + idx) + case Failure(t) => println("Could not process file: " + t.getMessage) +} +``` - onComplete,、onSuccess 和 onFailure 方法都具有Unit的结果类型，这意味着不能链接使用这些方法的回调。注意这种设计是为了避免暗示而刻意为之的，因为链接回调也许暗示着按照一定的顺序执行注册回调（回调注册在同一个future中是无序的）。 +{% endtab %} +{% endtabs %} -也就是说，我们现在应讨论论何时调用callback。因为callback需要future的值是可用的，所有回调只能在future完成之后被调用。然而，不能保证callback在完成future的线程或创建callback的线程中被调用。反而， 回调(callback)会在future对象完成之后的一些线程和一段时间内执行。所以我们说回调(callback)最终会被执行。 +`onComplete` 和 `foreach` 方法都具有 `Unit` 的结果类型，这意味着不能链接使用这些方法的回调。注意这种设计是为了避免暗示而刻意为之的，因为链接回调也许暗示着按照一定的顺序执行注册回调（回调注册在同一个 future 中是无序的）。 -此外，回调(callback)执行的顺序不是预先定义的，甚至在相同的应用程序中callback的执行顺序也不尽相同。事实上，callback也许不是一个接一个连续的调用，但是可能会在同一时间同时执行。这意味着在下面的例子中，变量totalA也许不能在计算上下文中被设置为正确的大写或者小写字母。 +也就是说，我们现在应讨论**何时**正好在调用回调(callback)。因为回调需要 future 的值是可用的，所有回调只能在 future 完成之后被调用。 +然而，不能保证回调在完成 future 的线程或创建回调的线程中被调用。 +反而， 回调会在 future 对象完成之后的一些线程和一段时间内执行。所以我们说回调最终会被执行。 - @volatile var totalA = 0 +此外，回调(callback)执行的顺序不是预先定义的，甚至在相同的应用程序中回调的执行顺序也不尽相同。 +事实上，回调也许不是一个接一个连续的调用，但是可能会在同一时间同时执行。 +这意味着在下面的例子中，变量 `totalA` 也许不能在计算上下文中被设置为正确的大写或者小写字母 `a`。 - val text = Future { - "na" * 16 + "BATMAN!!!" - } +{% tabs volatile %} +{% tab 'Scala 2 and 3' for=volatile %} + +```scala +@volatile var totalA = 0 - text onSuccess { - case txt => totalA += txt.count(_ == 'a') - } +val text = Future { + "na" * 16 + "BATMAN!!!" +} - text onSuccess { - case txt => totalA += txt.count(_ == 'A') - } -以上，这两个回调(callbacks)可能是一个接一个地执行的，这样变量totalA得到的预期值为18。然而，它们也可能是并发执行的，于是totalA最终可能是16或2，因为+= 是一个不可分割的操作符（即它是由一个读和一个写的步骤组成，这样就可能使其与其他的读和写任意交错执行）。 +text.foreach { txt => + totalA += txt.count(_ == 'a') +} + +text.foreach { txt => + totalA += txt.count(_ == 'A') +} +``` + +{% endtab %} +{% endtabs %} + +以上，这两个回调(callbacks)可能是一个接一个地执行的，这样变量 `totalA` 得到的预期值为`18`。 +然而，它们也可能是并发执行的，于是 `totalA` 最终可能是`16`或`2`，因为 `+=` 不是一个原子性的操作符（即它是由一个读和一个写的步骤组成，这样就可能使其与其他的读和写任意交错执行）。 考虑到完整性，回调的使用情景列在这儿： -- 在future中注册onComplete回调的时候要确保最后future执行完成之后调用相应的终止回调。 +1. 在 future 中注册 `onComplete` 回调的时候要确保最后 future 执行完成之后调用相应的终止回调。 -- 注册onSuccess或者onFailure回调时也和注册onComplete一样，不同之处在于future执行成功或失败分别调用onSuccess或onSuccess的对应的闭包。 +2. 注册 `foreach` 回调时也和注册 `onComplete` 一样，不同之处在于 future 成功完成才会调用闭包。 -- 注册一个已经完成的future的回调最后将导致此回调一直处于执行状态（1所隐含的）。 +3. 在一个已经完成的 future 上注册回调将导致此该回调最终被执行（1所隐含的）。 -- 在future中注册多个回调的情况下，这些回调的执行顺序是不确定的。事实上，这些回调也许是同时执行的，然而，特定的ExecutionContext执行可能导致明确的顺序。 +4. 在 future 中注册多个回调的情况下，这些回调的执行顺序是不确定的。事实上，这些回调也许是同时执行的。然而，特定的 `ExecutionContext` 实现可能导致明确的顺序。 -- 在一些回调抛出异常的情况下，其他的回调的执行不受影响。 +5. 在一些回调抛出异常的情况下，其他的回调的执行不受影响。 -- 在一些情况下，回调函数永远不能结束（例如，这些回调处于无限循环中），其他回调可能完全不会执行。在这种情况下，对于那些潜在的阻塞回调要使用阻塞的构造（例子如下）。 +6. 在一些情况下，回调函数永远不能结束（例如，这些回调处于无限循环中），其他回调可能完全不会执行。在这种情况下，对于那些潜在的阻塞回调要使用 `blocking` 的构造（例子如下）。 -- 一旦执行完，回调将从future对象中移除，这样更适合JVM的垃圾回收机制(GC)。 +7. 一旦执行完，回调将从 future 对象中移除，这样更适合垃圾回收机制(GC)。 ### 函数组合(Functional Composition)和For解构(For-Comprehensions) -尽管前文所展示的回调机制已经足够把future的结果和后继计算结合起来的，但是有些时候回调机制并不易于使用，且容易造成冗余的代码。我们可以通过一个例子来说明。假设我们有一个用于进行货币交易服务的API，我们想要在有盈利的时候购进一些美元。让我们先来看看怎样用回调来解决这个问题： +尽管前文所展示的回调机制已经足够把future的结果和后继计算结合起来的。 +但是有些时候回调机制并不易于使用，且容易造成冗余的代码。 +我们可以通过一个例子来说明。假设我们有一个用于进行货币交易服务的 API，我们只想在有盈利的时候购进一些美元。让我们先来看看怎样用回调来解决这个问题： - val rateQuote = Future { - connection.getCurrentValue(USD) - } +{% tabs futures-07 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-07 %} + +```scala +val rateQuote = Future { + connection.getCurrentValue(USD) +} - rateQuote onSuccess { case quote => - val purchase = Future { - if (isProfitable(quote)) connection.buy(amount, quote) - else throw new Exception("not profitable") - } +for (quote <- rateQuote) { + val purchase = Future { + if (isProfitable(quote)) connection.buy(amount, quote) + else throw new Exception("not profitable") + } - purchase onSuccess { - case _ => println("Purchased " + amount + " USD") - } - } + for (amount <- purchase) + println("Purchased " + amount + " USD") +} +``` -首先，我们创建一个名为rateQuote的future对象并获得当前的汇率。在服务器返回了汇率且该future对象成功完成了之后，计算操作才会从onSuccess回调中执行，这时我们就可以开始判断买还是不买了。所以我们创建了另一个名为purchase的future对象，用来在可盈利的情况下做出购买决定，并在稍后发送一个请求。最后，一旦purchase运行结束，我们会在标准输出中打印一条通知消息。 +{% endtab %} +{% tab 'Scala 3' for=futures-07 %} -这确实是可行的，但是有两点原因使这种做法并不方便。其一，我们不得不使用onSuccess，且不得不在其中嵌套purchase future对象。试想一下，如果在purchase执行完成之后我们可能会想要卖掉一些其他的货币。这时我们将不得不在onSuccess的回调中重复这个模式，从而可能使代码过度嵌套，过于冗长，并且难以理解。 +```scala +val rateQuote = Future { + connection.getCurrentValue(USD) +} -其二，purchase只是定义在局部范围内--它只能被来自onSuccess内部的回调响应。这也就是说，这个应用的其他部分看不到purchase，而且不能为它注册其他的onSuccess回调，比如说卖掉些别的货币。 +for quote <- rateQuote do + val purchase = Future { + if isProfitable(quote) then connection.buy(amount, quote) + else throw Exception("not profitable") + } -为解决上述的两个问题，futures提供了组合器（combinators）来使之具有更多易用的组合形式。映射（map）是最基本的组合器之一。试想给定一个future对象和一个通过映射来获得该future值的函数，映射方法将创建一个新Future对象，一旦原来的Future成功完成了计算操作，新的Future会通过该返回值来完成自己的计算。你能够像理解容器(collections)的map一样来理解future的map。 + for amount <- purchase do + println("Purchased " + amount + " USD") +``` -让我们用map的方法来重构一下前面的例子： +{% endtab %} +{% endtabs %} - val rateQuote = Future { - connection.getCurrentValue(USD) - } +首先，我们创建一个名为 `rateQuote` 的 future 对象并获得当前的汇率。 +在服务器返回了汇率且该 future 对象成功完成了之后，计算操作才会从 `foreach` 回调中执行，这时我们就可以开始判断买还是不买了。 +所以我们创建了另一个名为 `purchase` 的 future 对象，用来只在可盈利的情况下做出购买决定，然后发送一个请求。 +最后，一旦purchase运行结束，我们会在标准输出中打印一条通知消息。 - val purchase = rateQuote map { quote => - if (isProfitable(quote)) connection.buy(amount, quote) - else throw new Exception("not profitable") - } +这确实是可行的，但是有两点原因使这种做法并不方便。其一，我们不得不使用 `foreach`，在其中嵌套第二个 `purchase` future 对象。试想一下，如果在 `purchase` 执行完成之后我们可能会想要卖掉一些其他的货币。这时我们将不得不在 `foreach` 回调中重复这个模式，从而可能使代码过度嵌套，过于冗长，并且难以理解。 - purchase onSuccess { - case _ => println("Purchased " + amount + " USD") - } +其二，`purchase` future 不在余下的代码范围内 -- 它只能被来自 `foreach` 内部的回调响应。这也就是说，这个应用的其他部分看不到 `purchase`，而且不能为它注册其他的 `foreach` 回调，比如说卖掉些别的货币。 -通过对rateQuote的映射我们减少了一次onSuccess的回调，更重要的是避免了嵌套。这时如果我们决定出售一些货币就可以再次使用purchase方法上的映射了。 +为解决上述的两个问题， futures提供了组合器（combinators）来使之具有更多易用的组合形式。映射（map）是最基本的组合器之一。试想给定一个 future 对象和一个通过映射来获得该 future 值的函数，映射方法将创建一个新 Future 对象，一旦原来的 Future 成功完成了计算操作，新的 Future 会通过该返回值来完成自己的计算。你能够像理解容器(collections)的map一样来理解 future 的map。 -可是如果isProfitable方法返回了false将会发生些什么？会引发异常？这种情况下，purchase的确会因为异常而失败。不仅仅如此，想象一下，链接的中断和getCurrentValue方法抛出异常会使rateQuote的操作失败。在这些情况下映射将不会返回任何值，而purchase也会会自动的以和rateQuote相同的异常而执行失败。 +让我们用 `map` 组合器来重构一下前面的例子： -总之，如果原Future的计算成功完成了，那么返回的Future将会使用原Future的映射值来完成计算。如果映射函数抛出了异常则Future也会带着该异常完成计算。如果原Future由于异常而计算失败，那么返回的Future也会包含相同的异常。这种异常的传导方式也同样适用于其他的组合器(combinators)。 +{% tabs futures-08 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-08 %} -使之能够在For-comprehensions原则下使用，是设计Future的目的之一。也正是因为这个原因，Future还拥有flatMap，filter和foreach等组合器。其中flatMap方法可以构造一个函数，它可以把值映射到一个姑且称为g的新future，然后返回一个随g的完成而完成的Future对象。 +```scala +val rateQuote = Future { + connection.getCurrentValue(USD) +} -让我们假设我们想把一些美元兑换成瑞士法郎。我们必须为这两种货币报价，然后再在这两个报价的基础上确定交易。下面是一个在for-comprehensions中使用flatMap和withFilter的例子： +val purchase = rateQuote map { quote => + if (isProfitable(quote)) connection.buy(amount, quote) + else throw new Exception("not profitable") +} - val usdQuote = Future { connection.getCurrentValue(USD) } - val chfQuote = Future { connection.getCurrentValue(CHF) } +purchase.foreach { amount => + println("Purchased " + amount + " USD") +} +``` - val purchase = for { - usd <- usdQuote - chf <- chfQuote - if isProfitable(usd, chf) - } yield connection.buy(amount, chf) +{% endtab %} +{% tab 'Scala 3' for=futures-08 %} - purchase onSuccess { - case _ => println("Purchased " + amount + " CHF") - } +```scala +val rateQuote = Future { + connection.getCurrentValue(USD) +} -purchase只有当usdQuote和chfQuote都完成计算以后才能完成-- 它以其他两个Future的计算值为前提所以它自己的计算不能更早的开始。 +val purchase = rateQuote.map { quote => + if isProfitable(quote) then connection.buy(amount, quote) + else throw Exception("not profitable") +} -上面的for-comprhension将被转换为： +purchase.foreach { amount => + println("Purchased " + amount + " USD") +} +``` - val purchase = usdQuote flatMap { - usd => - chfQuote - .withFilter(chf => isProfitable(usd, chf)) - .map(chf => connection.buy(amount, chf)) - } +{% endtab %} +{% endtabs %} + +通过在 `rateQuote` 上使用 `map`，我们减少了一次 `foreach` 的回调，更重要的是避免了嵌套。这时如果我们决定出售一些货币就可以再次在 `purchase` 上使用 `map` 了。 + +可是如果 `isProfitable` 方法返回了 `false` 将会发生些什么？会引发异常？ +这种情况下，`purchase` 的确会因为异常而失败。不仅仅如此，想象一下，链接的中断和 `getCurrentValue` 方法抛出异常会使 `rateQuote` 的操作失败。 +在这些情况下映射将不会返回任何值，而 `purchase` 也会自动的以和 `rateQuote` 相同的异常而失败。 + +总之，如果原 future 成功完成了，那么返回的 future 将会使用从原 future来的映射值完成。如果映射函数抛出了异常则返回的 future 也会带着一样的异常。如果原 future 由于异常而计算失败，那么返回的 future 也会包含相同的异常。这种异常的传导语义也存在于其余的组合器(combinators)。 + +使之能够在for-comprehensions 中使用，是设计 future 的目的之一。 +因为这个原因，future 还拥有 `flatMap` 和 `withFilter` 组合器。`flatMap` 方法获取一个函数，该函数把值映射到一个新 future `g`，然后返回一个随 `g` 的完成而完成的 future。 + +让我们假设我们想把一些美元兑换成瑞士法郎（CHF）。我们必须为这两种货币报价，然后再在这两个报价的基础上确定交易。 +下面是一个在 for-comprehensions 中使用 `flatMap` 和 `withFilter` 的例子： + +{% tabs futures-09 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-09 %} + +```scala +val usdQuote = Future { connection.getCurrentValue(USD) } +val chfQuote = Future { connection.getCurrentValue(CHF) } + +val purchase = for { + usd <- usdQuote + chf <- chfQuote + if isProfitable(usd, chf) +} yield connection.buy(amount, chf) -这的确是比for-comprehension稍微难以把握一些，但是我们这样分析有助于您更容易的理解flatMap的操作。FlatMap操作会把自身的值映射到其他future对象上，并随着该对象计算完成的返回值一起完成计算。在我们的例子里，flatMap用usdQuote的值把chfQuote的值映射到第三个futrue对象里，该对象用于发送一定量瑞士法郎的购入请求。只有当通过映射返回的第三个future对象完成了计算，purchase才能完成计算。 +purchase foreach { amount => + println("Purchased " + amount + " CHF") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-09 %} + +```scala +val usdQuote = Future { connection.getCurrentValue(USD) } +val chfQuote = Future { connection.getCurrentValue(CHF) } + +val purchase = for + usd <- usdQuote + chf <- chfQuote + if isProfitable(usd, chf) +yield connection.buy(amount, chf) + +purchase.foreach { amount => + println("Purchased " + amount + " CHF") +} +``` + +{% endtab %} +{% endtabs %} + +`purchase` 只有当 `usdQuote` 和 `chfQuote` 都完成计算以后才能完成-- 它以其他两个 future 的计算值为前提所以它自己的计算不能更早的开始。 + +上面的 for-comprhension 将被转换为： + +{% tabs for-translation %} +{% tab 'Scala 2 and 3' for=for-translation %} + +```scala +val purchase = usdQuote flatMap { + usd => + chfQuote + .withFilter(chf => isProfitable(usd, chf)) + .map(chf => connection.buy(amount, chf)) +} +``` + +{% endtab %} +{% endtabs %} + +这的确是比for-comprehension稍微难以把握一些，但是我们这样分析有助于您更容易的理解 `flatMap` 的操作。`flatMap` 操作会把自身的值映射到其他future对象上，并随着该对象计算完成的返回值一起完成计算。 +在我们的例子里，`flatMap` 用 `usdQuote` 的值把 `chfQuote` 的值映射到第三个 futrue 对象里，该对象用于发送一定量瑞士法郎的购入请求。 +只有当通过 `map` 返回的第三个 future 对象完成，结果 future `purchase` 才能完成。 这可能有些难以置信，但幸运的是faltMap操作在for-comprhensions模式以外很少使用，因为for-comprehensions本身更容易理解和使用。 -再说说filter，它可以用于创建一个新的future对象，该对象只有在满足某些特定条件的前提下才会得到原始future的计算值，否则就会抛出一个NoSuchElementException的异常而失败。调用了filter的future，其效果与直接调用withFilter完全一样。 +`filter` 组合器可以用于创建一个新的 future 对象，该对象只有在满足某些特定条件的前提下才会得到原始future的值。否则新 future 就会有 `NoSuchElementException` 的失败。调用了 `filter` 的future，其效果与直接调用 `withFilter` 完全一样。 -作为组合器的collect同filter之间的关系有些类似容器（collections）API里的那些方法之间的关系。 +作为组合器的 `collect` 同 `filter` 之间的关系有些类似容器（collections）API里的那些方法之间的关系。 -值得注意的是，调用foreach组合器并不会在计算值可用的时候阻塞当前的进程去获取计算值。恰恰相反，只有当future对象成功计算完成了，foreach所迭代的函数才能够被异步的执行。这意味着foreach与onSuccess回调意义完全相同。 +由于 `Future` trait(译注: trait有点类似java中的接口(interface)的概念)从概念上看可以包含两种类型的返回值（计算结果和异常），所以组合器会有一个处理异常的需求。 -由于Future trait(译注: trait有点类似java中的接口(interface)的概念)从概念上看包含两种类型的返回值（计算结果和异常），所以组合器会有一个处理异常的需求。 +比方说我们准备在 `rateQuote` 的基础上决定购入一定量的货币，那么 `connection.buy` 方法需要获取购入的 `amount` 和期望的 `quote`。它返回完成购买的数量。假如 `quote` 偏偏在这个节骨眼儿改变了，那buy方法将会抛出一个 `QuoteChangedExecption`，并且不会做任何交易。如果我们想让我们的 future 对象返回`0`而不是抛出那个异常，那我们需要使用 `recover` 组合器： -比方说我们准备在rateQuote的基础上决定购入一定量的货币，那么`connection.buy`方法需要知道购入的数量和期望的报价值，最终完成购买的数量将会被返回。假如报价值偏偏在这个节骨眼儿改变了，那buy方法将会抛出一个`QuoteChangedExecption`，并且不会做任何交易。如果我们想让我们的Future对象返回0而不是抛出那个该死的异常，那我们需要使用recover组合器： - val purchase: Future[Int] = rateQuote map { - quote => connection.buy(amount, quote) - } recover { - case QuoteChangedException() => 0 - } +{% tabs recover %} +{% tab 'Scala 2 and 3' for=recover %} -这里用到的recover能够创建一个新future对象，该对象当计算完成时持有和原future对象一样的值。如果执行不成功则偏函数的参数会被传递给使原Future失败的那个Throwable异常。如果它把Throwable映射到了某个值，那么新的Future就会成功完成并返回该值。如果偏函数没有定义在Throwable中，那么最终产生结果的future也会失败并返回同样的Throwable。 +```scala +val purchase: Future[Int] = rateQuote.map { + quote => connection.buy(amount, quote) +} recover { + case QuoteChangedException() => 0 +} +``` +{% endtab %} +{% endtabs %} -组合器recoverWith能够创建一个新future对象，当原future对象成功完成计算时，新future对象包含有和原future对象相同的计算结果。若原future失败或异常，偏函数将会返回造成原future失败的相同的Throwable异常。如果此时Throwable又被映射给了别的future，那么新Future就会完成并返回这个future的结果。recoverWith同recover的关系跟flatMap和map之间的关系很像。 +这里用到的 `recover` 能够创建一个新 future 对象，该对象当成功完成时持有和原 future 对象一样的值。如果执行不成功则偏函数的参数会被传递给使原 future 失败的那个 `Throwable` 异常。如果它把 `Throwable` 映射到了某个值，那么新的 future 就会成功完成并返回该值。 +如果偏函数没有定义在 `Throwable` 中，那么最终产生结果的 future 也会失败并返回同样的 `Throwable`。 -fallbackTo组合器生成的future对象可以在该原future成功完成计算时返回结果，如果原future失败或异常返回future参数对象的成功值。在原future和参数future都失败的情况下，新future对象会完成并返回原future对象抛出的异常。正如下面的例子中，本想打印美元的汇率，但是在获取美元汇率失败的情况下会打印出瑞士法郎的汇率： +组合器 `recoverWith` 能够创建一个新 future 对象，当原 future 对象成功完成计算时，新 future 包含有和原 future 相同的结果。若原 future 失败或异常，偏函数将会返回造成原 future 失败的相同的 `Throwable` 异常。如果此时 `Throwable` 又被映射给了别的 future ，那么新 future 就会完成并返回这个 future 的结果。 +`recoverWith` 同 `recover` 的关系跟 `flatMap` 和 `map` 之间的关系很像。 - val usdQuote = Future { - connection.getCurrentValue(USD) - } map { - usd => "Value: " + usd + "$" - } - val chfQuote = Future { - connection.getCurrentValue(CHF) - } map { - chf => "Value: " + chf + "CHF" - } +`fallbackTo` 组合器生成的 future 对象可以在该原 future 成功完成计算时返回结果，如果原 future 失败或异常返回 future 参数对象的成功值。在原 future 和参数 future 都失败的情况下，新 future 对象会完成并返回原 future 对象抛出的异常。正如下面的例子中，本想打印美元的汇率，但是在获取美元汇率失败的情况下会打印出瑞士法郎的汇率： - al anyQuote = usdQuote fallbackTo chfQuote +{% tabs fallback-to %} +{% tab 'Scala 2 and 3' for=fallback-to %} - anyQuote onSuccess { println(_) } +```scala +val usdQuote = Future { + connection.getCurrentValue(USD) +}.map { + usd => "Value: " + usd + "$" +} +val chfQuote = Future { + connection.getCurrentValue(CHF) +} map { + chf => "Value: " + chf + "CHF" +} -组合器andThen的用法是出于纯粹的side-effecting目的。经andThen返回的新Future无论原Future成功或失败都会返回与原Future一模一样的结果。一旦原Future完成并返回结果，andThen后跟的代码块就会被调用，且新Future将返回与原Future一样的结果，这确保了多个andThen调用的顺序执行。正如下例所示，这段代码可以从社交网站上把近期发出的帖子收集到一个可变集合里，然后把它们都打印在屏幕上： +val anyQuote = usdQuote.fallbackTo(chfQuote) - val allposts = mutable.Set[String]() +anyQuote.foreach { println(_) } +``` - Future { - session.getRecentPosts - } andThen { - case Success(posts) => allposts ++= posts - } andThen { - case _ => - clearAll() - for (post <- allposts) render(post) - } +{% endtab %} +{% endtabs %} -综上所述，Future的组合器功能是纯函数式的，每种组合器都会返回一个与原Future相关的新Future对象。 +组合器 `andThen` 的用法是出于纯粹的side-effecting目的。经 `andThen` 返回的新 future 无论原 future 成功或失败都会返回与原 future 一模一样的结果。 +一旦原 future 完成并返回结果，`andThen` 后跟的代码块就会被调用，且新 future 将返回与原 future 一样的结果，这确保了多个 `andThen` 调用的顺序执行。正如下例所示，这段代码可以从社交网站上把近期发出的帖子收集到一个可变集合里，然后把它们都打印在屏幕上： -### 投影(Projections) +{% tabs futures-10 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-10 %} -为了确保for解构(for-comprehensions)能够返回异常，futures也提供了投影(projections)。如果原future对象失败了，失败的投影(projection)会返回一个带有Throwable类型返回值的future对象。如果原Future成功了，失败的投影(projection)会抛出一个NoSuchElementException异常。下面就是一个在屏幕上打印出异常的例子： +```scala +val allposts = mutable.Set[String]() - val f = Future { - 2 / 0 - } - for (exc <- f.failed) println(exc) +Future { + session.getRecentPosts +} andThen { + case Success(posts) => allposts ++= posts +} andThen { + case _ => + clearAll() + for (post <- allposts) render(post) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-10 %} + +```scala +val allPosts = mutable.Set[String]() + +Future { + session.getRecentPosts() +}.andThen { + case Success(posts) => allPosts ++= posts +}.andThen { + case _ => + clearAll() + for post <- allPosts do render(post) +} +``` +{% endtab %} +{% endtabs %} + +综上所述，在 future 上的组合器功能是纯函数式的。 +每种组合器都会返回一个与原future相关的新 future 对象。 +### 投影 + +为了确保for解构(for-comprehensions)能够返回异常， future s也提供了投影(projections)。如果原 future 对象失败了，`failed` 的投影会返回一个带有 `Throwable` 类型返回值的 future 对象。如果原 future 成功了，`failed` 的投影失败并有一个 `NoSuchElementException`。下面就是一个在屏幕上打印出异常的例子： + +{% tabs futures-11 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-11 %} + +```scala +val f = Future { + 2 / 0 +} +for (exc <- f.failed) println(exc) +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-11 %} + +```scala +val f = Future { + 2 / 0 +} +for exc <- f.failed do println(exc) +``` + +{% endtab %} +{% endtabs %} + +本例中的 for-comprehension 翻译成： + +{% tabs for-comp-tran %} +{% tab 'Scala 2 and 3' for=for-comp-tran %} + +```scala +f.failed.foreach(exc => println(exc)) +``` + +{% endtab %} +{% endtabs %} + +因为 `f` 在这没有成功，该闭包被注册到新成功的 `Future[Throwable]` 上的 `foreach`。 下面的例子不会在屏幕上打印出任何东西： - val f = Future { +{% tabs futures-12 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-12 %} + +```scala +val f = Future { + 4 / 2 +} +for (exc <- f.failed) println(exc) +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-12 %} + +```scala +val g = Future { + 4 / 2 +} +for exc <- g.failed do println(exc) +``` + +{% endtab %} +{% endtabs %} + + + + + + ### Future的扩展 -用更多的实用方法来对Futures API进行扩展支持已经被提上了日程，这将为很多外部框架提供更多专业工具。 +用更多的实用方法来对 Futures API 进行扩展支持已经被提上了日程，这将为很多外部框架提供更多专业工具。 -## Blocking +## 阻塞（Blocking） -正如前面所说的，在future的blocking非常有效地缓解性能和预防死锁。虽然在futures中使用这些功能方面的首选方式是Callbacks和combinators，但在某些处理中也会需要用到blocking，并且它也是被Futures and Promises API所支持的。 +Future 通常是异步的，不会阻塞底层执行线程。 +但是，在某些情况下，有必要阻塞。 +我们区分了两种形式的阻塞执行线程： +调用任意代码，从 future 来内部阻塞线程， +以及从另一个 future 外部阻塞，等待该 future 完成。 -在之前的并发交易(concurrency trading)例子中，在应用的最后有一处用到block来确定是否所有的futures已经完成。这有个如何使用block来处理一个future结果的例子： +### Future 内的阻塞 - import scala.concurrent._ - import scala.concurrent.duration._ +正如在全局 `ExecutionContext` 中看到的那样，可以使用 `blocking` 结构通知某个阻塞调用的 `ExecutionContext`。 +但是，实现完全由 `ExecutionContext`。一些 `ExecutionContext`，如 `ExecutionContext.global`，用 `MangedBlocker` 的办法实现 `blocking`，而另外一样通过执行上下文，如固定线程池来实现 `blocking`： +通过“ManagedBlocker”实现“阻塞”，一些执行上下文，如固定线程池： - def main(args: Array[String]) { - val rateQuote = Future { - connection.getCurrentValue(USD) - } +{% tabs fixed-thread-pool %} +{% tab 'Scala 2 and 3' for=fixed-thread-pool %} - val purchase = rateQuote map { quote => - if (isProfitable(quote)) connection.buy(amount, quote) - else throw new Exception("not profitable") - } +```scala +ExecutionContext.fromExecutor(Executors.newFixedThreadPool(x)) +``` - Await.result(purchase, 0 nanos) - } +{% endtab %} +{% endtabs %} -在这种情况下这个future是不成功的，这个调用者转发出了该future对象不成功的异常。它包含了失败的投影(projection)-- 阻塞(blocking)该结果将会造成一个NoSuchElementException异常在原future对象被成功计算的情况下被抛出。 +将不作任何事，就像下面演示的那样： -相反的，调用`Await.ready`来等待这个future直到它已完成，但获不到它的结果。同样的方式，调用那个方法时如果这个future是失败的，它将不会抛出异常。 +{% tabs futures-13 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-13 %} -The Future trait实现了Awaitable trait还有其`ready()`和`result()`方法。这些方法不能被客户端直接调用，它们只能通过执行环境上下文来进行调用。 +```scala +implicit val ec = + ExecutionContext.fromExecutor(Executors.newFixedThreadPool(4)) -为了允许程序调用可能是阻塞式的第三方代码，而又不必实现Awaitable特质，原函数可以用如下的方式来调用： +Future { + blocking { blockingStuff() } +} +``` - blocking { - potentiallyBlockingCall() - } +{% endtab %} +{% tab 'Scala 3' for=futures-13 %} -这段blocking代码也可以抛出一个异常。在这种情况下，这个异常会转发给调用者。 +```scala +given ExecutionContext = + ExecutionContext.fromExecutor(Executors.newFixedThreadPool(4)) -## 异常(Exceptions) +Future { + blocking { blockingStuff() } +} +``` -当异步计算抛出未处理的异常时，与那些计算相关的futures就失败了。失败的futures存储了一个Throwable的实例，而不是返回值。Futures提供onFailure回调方法，它用一个PartialFunction去表示一个Throwable。下列特殊异常的处理方式不同： +{% endtab %} +{% endtabs %} -`scala.runtime.NonLocalReturnControl[_]` --此异常保存了一个与返回相关联的值。通常情况下，在方法体中的返回结构被调用去抛出这个异常。相关联的值将会存储到future或一个promise中，而不是一直保存在这个异常中。 +和以下代码有一样的副作用： -ExecutionException-当因为一个未处理的中断异常、错误或者`scala.util.control.ControlThrowable`导致计算失败时会被存储起来。这种情况下，ExecutionException会为此具有未处理的异常。这些异常会在执行失败的异步计算线程中重新抛出。这样做的目的，是为了防止正常情况下没有被客户端代码处理过的那些关键的、与控制流相关的异常继续传播下去，同时告知客户端其中的future对象是计算失败的。 +{% tabs alternative %} +{% tab 'Scala 2 and 3' for=alternative %} -更精确的语义描述请参见 [NonFatal]。 +```scala +Future { blockingStuff() } +``` -## Promises +{% endtab %} +{% endtabs %} -到目前为止，我们仅考虑了通过异步计算的方式创建future对象来使用future的方法。尽管如此，futures也可以使用promises来创建。 +阻塞代码也可能抛出异常。这种情况下，异常被转发给调用者。 -如果说futures是为了一个还没有存在的结果，而当成一种只读占位符的对象类型去创建，那么promise就被认为是一个可写的，可以实现一个future的单一赋值容器。这就是说，promise通过这种success方法可以成功去实现一个带有值的future。相反的，因为一个失败的promise通过failure方法就会实现一个带有异常的future。 +### Future 外部的阻塞 -一个promise p通过p.future方式返回future。 这个futrue对象被指定到promise p。根据这种实现方式，可能就会出现p.future与p相同的情况。 +正如前面所说的，为了性能和防止死锁，强烈建议不要在future上用阻塞。 +虽然在futures中使用这些功能方面的首选方式是回调和组合器，但在某些处理中也会需要用到阻塞，并且 Futures API 和 Promises API也支持它。 -考虑下面的生产者 - 消费者的例子，其中一个计算产生一个值，并把它转移到另一个使用该值的计算。这个传递中的值通过一个promise来完成。 +在之前的并发交易(concurrency trading)例子中，在应用的最后有一处用到阻塞来确定是否所有的 futures已经完成。这有个如何使用阻塞来处理一个 future 结果的例子： - import scala.concurrent.{ Future, Promise } - import scala.concurrent.ExecutionContext.Implicits.global +{% tabs futures-14 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-14 %} - val p = Promise[T]() - val f = p.future +```scala +import scala.concurrent._ +import scala.concurrent.duration._ - val producer = Future { - val r = produceSomething() - p success r - continueDoingSomethingUnrelated() +object awaitPurchase { + def main(args: Array[String]): Unit = { + val rateQuote = Future { + connection.getCurrentValue(USD) } - val consumer = Future { - startDoingSomething() - f onSuccess { - case r => doSomethingWithResult() - } + val purchase = rateQuote map { quote => + if (isProfitable(quote)) connection.buy(amount, quote) + else throw new Exception("not profitable") } -在这里，我们创建了一个promise并利用它的future方法获得由它实现的Future。然后，我们开始了两种异步计算。第一种做了某些计算，结果值存放在r中，通过执行promise p，这个值被用来完成future对象f。第二种做了某些计算，然后读取实现了future f的计算结果值r。需要注意的是，在生产者完成执行`continueDoingSomethingUnrelated()` 方法这个任务之前，消费者可以获得这个结果值。 + Await.result(purchase, 0.nanos) + } +} +``` -正如前面提到的，promises具有单赋值语义。因此，它们仅能被实现一次。在一个已经计算完成的promise或者failed的promise上调用success方法将会抛出一个IllegalStateException异常。 +{% endtab %} +{% tab 'Scala 3' for=futures-14 %} -下面的这个例子显示了如何fail a promise。 +```scala +import scala.concurrent.* +import scala.concurrent.duration.* - val p = promise[T] - val f = p.future +@main def awaitPurchase = + val rateQuote = Future { + connection.getCurrentValue(USD) + } - val producer = Future { - val r = someComputation - if (isInvalid(r)) - p failure (new IllegalStateException) - else { - val q = doSomeMoreComputation(r) - p success q - } - } + val purchase = rateQuote.map { quote => + if isProfitable(quote) then connection.buy(amount, quote) + else throw Exception("not profitable") + } -如上，生产者计算出一个中间结果值r，并判断它的有效性。如果它不是有效的，它会通过返回一个异常实现promise p的方式fails the promise，关联的future f是failed。否则，生产者会继续它的计算，最终使用一个有效的结果值实现future f，同时实现 promise p。 + Await.result(purchase, 0.nanos) +``` -Promises也能通过一个complete方法来实现，这个方法采用了一个`potential value Try[T]`，这个值要么是一个类型为`Failure[Throwable]`的失败的结果值，要么是一个类型为`Success[T]`的成功的结果值。 +{% endtab %} +{% endtabs %} -类似success方法，在一个已经完成(completed)的promise对象上调用failure方法和complete方法同样会抛出一个IllegalStateException异常。 +在这种情况下这个 future 是不成功的，这个调用者转发出了该 future 对象不成功的异常。它包含了 `failed` 的投影(projection)-- 阻塞(blocking)该结果将会造成一个 `NoSuchElementException` 异常在原 future 对象被成功计算的情况下被抛出。 -应用前面所述的promises和futures方法的一个优点是，这些方法是单一操作的并且是没有副作用(side-effects)的，因此程序是具有确定性的(deterministic)。确定性意味着，如果该程序没有抛出异常(future的计算值被获得)，无论并行的程序如何调度，那么程序的结果将会永远是一样的。 +相反的，调用`Await.ready`来等待这个future直到它已完成，但获不到它的结果。同样的方式，调用那个方法时如果这个future是失败的，它将不会抛出异常。 -在一些情况下，客户端也许希望能够只在promise没有完成的情况下完成该promise的计算(例如，如果有多个HTTP请求被多个不同的futures对象来执行，并且客户端只关心地一个HTTP应答(response)，该应答对应于地一个完成该promise的future)。因为这个原因，future提供了tryComplete，trySuccess和tryFailure方法。客户端需要意识到调用这些的结果是不确定的，调用的结果将以来从程序执行的调度。 +The `Future` trait实现了 `Awaitable` trait 还有其 `ready()` 和 `result()` 方法。这些方法不能被客户端直接调用，它们只能通过执行环境上下文来进行调用。 -completeWith方法将用另外一个future完成promise计算。当该future结束的时候，该promise对象得到那个future对象同样的值，如下的程序将打印1： +## 异常(Exceptions) - val f = Future { 1 } - val p = promise[Int] +当异步计算抛出未处理的异常时，与那些计算相关的 futures 就失败了。失败的 futures 存储了一个 `Throwable` 的实例，而不是返回值。`Futures` 提供 `failed` 投影方法，它允许这个 `Throwable` 被当作另一个 `Future` 的成功值来处理。下列特殊异常的处理方式不同： +1. `scala.runtime.NonLocalReturnControl[_]` -- 此异常保存了一个与返回相关联的值。通常情况下，方法体中的 `return` 结构被翻译成带有异常的 `throw` 。相关联的值将会存储到future或一个promise中，而不是一直保存在这个异常中。 - p completeWith f +2. `ExecutionException` -- 当因为一个未处理的 `InterruptedException`, `Error` 或者 `scala.util.control.ControlThrowable` 导致计算失败时会被存储起来。这种情况下， `ExecutionException` 会为此具有未处理的异常。这些异常会在执行失败的异步计算线程中重新抛出。这样做的目的，是为了防止正常情况下没有被客户端代码处理过的那些关键的、与控制流相关的异常继续传播下去，同时告知客户端其中的 future 对象是计算失败的。 - p.future onSuccess { - case x => println(x) - } +致命异常（由 `NonFatal` 确定）在执行失败的异步计算的线程中重新引发。这会通知管理问题执行线程的代码，并允许它在必要时快速失败。更精确的语义描述请参见[`NonFatal`](https://www.scala-lang.org/api/current/scala/util/control/NonFatal$.html)。 + +## Promise + +到目前为止，我们仅考虑了通过异步计算的方式创建 `Future` 对象来使用 `Future` 的方法。尽管如此，futures也可以使用 *promises* 来创建。 + +如果说futures是为了一个还没有存在的结果，而当成一种只读占位符的对象类型去创建，那么promise就被认为是一个可写的，可以实现一个future的单一赋值容器。这就是说，promise通过这种 `success` 方法可以成功去实现一个带有值(通过 “实现” 该 promise)的future。相反的，用 `failure` 方法。 +一个 promise 也能用来实现带有异常的 future，通过这个失败的promise。 + +一个promise `p` 通过 `p.future` 方式返回future。 这个futrue对象被指定到promise `p`。根据这种实现方式，可能就会出现 `p.future eq p` 的情况。 + +考虑下面的生产者-消费者的例子，其中一个计算产生一个值，并把它转移到另一个使用该值的计算。这个传递中的值通过一个 promise 来完成。 + +{% tabs promises %} +{% tab 'Scala 2 and 3' for=promises %} + +```scala +import scala.concurrent.{ Future, Promise } +import scala.concurrent.ExecutionContext.Implicits.global + +val p = Promise[T]() +val f = p.future + +val producer = Future { + val r = produceSomething() + p.success(r) + continueDoingSomethingUnrelated() +} + +val consumer = Future { + startDoingSomething() + f.foreach { r => + doSomethingWithResult() + } +} +``` + +{% endtab %} +{% endtabs %} + +在这里，我们创建了一个promise并利用它的 `future` 方法获得由它实现的 `Future`。然后，我们开始了两种异步计算。第一种做了某些计算，结果值存放在r中，通过执行promise `p`，这个值被用来完成future对象 `f`。第二种做了某些计算，然后读取实现了 future `f` 的计算结果值 `r`。需要注意的是，在 `producer` 完成执行 `continueDoingSomethingUnrelated()` 方法这个任务之前，消费者可以获得这个结果值。 + +正如前面提到的，promises 具有单赋值语义。因此，它们仅能被完成一次。在一个已经计算完成的 promise 或者 failed 的promise上调用 `success` 方法将会抛出一个 `IllegalStateException` 异常。 + +下面的这个例子显示了如何使 promise 失败。 + +{% tabs futures-15 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-15 %} + +```scala +val p = Promise[T]() +val f = p.future + +val producer = Future { + val r = someComputation + if (isInvalid(r)) + p.failure(new IllegalStateException) + else { + val q = doSomeMoreComputation(r) + p.success(q) + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-15 %} + +```scala +val p = Promise[T]() +val f = p.future + +val producer = Future { + val r = someComputation + if isInvalid(r) then + p.failure(new IllegalStateException) + else + val q = doSomeMoreComputation(r) + p.success(q) +} +``` + +{% endtab %} +{% endtabs %} + +如上， `producer` 计算出一个中间结果值 `r`，并判断它的有效性。如果它不是有效的，它会通过返回一个异常实现promise `p` 的方式fails the promise，关联的future `f` 是失败的。否则， `producer` 会继续它的计算，最终使用一个有效的结果值实现future f，同时实现 promise p。 + +Promises也能通过一个complete方法来实现，这个方法采用了一个 `potential value Try[T]`，这个值要么是一个类型为 `Failure[Throwable]` 的失败的结果值，要么是一个类型为 `Success[T]` 的成功的结果值。 + +类似 `success` 方法，在一个已经完成(completed)的promise对象上调用 `failure` 方法和 `complete` 方法同样会抛出一个 `IllegalStateException` 异常。 + +应用前面所述的 promises 和 futures 操作的一个优点是，这些方法是单一操作的并且是没有副作用(side-effects)的，因此程序是具有确定性的(deterministic)。确定性意味着，如果该程序没有抛出异常(future 的计算值被获得)，无论并行的程序如何调度，那么程序的结果将会永远是一样的。 + +在一些情况下，客户端也许希望能够只在 promise 没有完成的情况下完成该 promise 的计算(例如，如果有多个HTTP请求被多个不同的futures对象来执行，并且客户端只关心第一个HTTP应答(response)，该应答对应于第一个完成该 promise 的future)。因为这些原因，future提供了 `tryComplete`，`trySuccess` 和 `tryFailure` 方法。客户端需要意识到调用这些的结果是不确定的，调用的结果将以来从程序执行的调度。 + +`completeWith` 方法将用另外一个 future 完成 promise 计算。当该 future 结束的时候，该 promise 对象得到那个 future 对象同样的值，如下的程序将打印 `1`： -当让一个promise以异常失败的时候，三总子类型的Throwable异常被分别的处理。如果中断该promise的可抛出(Throwable)一场是`scala.runtime.NonLocalReturnControl`，那么该promise将以对应的值结束；如果是一个Error的实例，`InterruptedException`或者`scala.util.control.ControlThrowable`，那么该可抛出(Throwable)异常将会封装一个ExecutionException异常，该ExectionException将会让该promise以失败结束。 +{% tabs promises-2 %} +{% tab 'Scala 2 and 3' for=promises-2 %} -通过使用promises，futures的onComplete方法和future的构造方法，你能够实现前文描述的任何函数式组合组合器(compition combinators)。让我们来假设一下你想实现一个新的组合起，该组合器首先使用两个future对象f和，产生第三个future，该future能够用f或者g来完成，但是只在它能够成功完成的情况下。 +```scala +val f = Future { 1 } +val p = promise[Int]() + +p.completeWith(f) + +p.future.foreach { x => + println(x) +} +``` + +{% endtab %} +{% endtabs %} + +当让一个promise以异常失败的时候，三个子类型的 `Throwable` 异常被分别的处理。如果中断该promise的可抛出(Throwable)一场是`scala.runtime.NonLocalReturnControl`，那么该promise将以对应的值结束；如果是一个Error的实例，`InterruptedException` 或者 `scala.util.control.ControlThrowable`，那么该 `Throwable` 异常将会封装一个 `ExecutionException` 异常，该 `ExectionException` 将会让该 promise 以失败结束。 + +通过使用 promises，futures 的 `onComplete` 方法和 `future` 的构造方法，你能够实现前文描述的任何函数式组合组合器(compition combinators)。 +让我们来假设一下你想实现一个新的组合器 `first`，该组合器使用两个future `f` 和 `g`，然后生产出第三个 future，该future能够用 `f` 或者 `g` 来完成（看哪一个先到），但前提是它能够成功。 这里有个关于如何去做的实例： - def first[T](f: Future[T], g: Future[T]): Future[T] = { - val p = promise[T] +{% tabs futures-16 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-16 %} - f onSuccess { - case x => p.trySuccess(x) - } +```scala +def first[T](f: Future[T], g: Future[T]): Future[T] = { + val p = Promise[T] - g onSuccess { - case x => p.trySuccess(x) - } + f.foreach { x => + p.trySuccess(x) + } - p.future - } + g.foreach { x => + p.trySuccess(x) + } + + p.future +} +``` + +{% endtab %} +{% tab 'Scala 3' for=futures-16 %} + +```scala +def first[T](f: Future[T], g: Future[T]): Future[T] = + val p = Promise[T] + + f.foreach { x => + p.trySuccess(x) + } + + g.foreach { x => + p.trySuccess(x) + } + + p.future +``` -注意，在这种实现方式中，如果f与g都不是成功的，那么`first(f, g)`将不会实现（即返回一个值或者返回一个异常）。 +{% endtab %} +{% endtabs %} + +注意，在这种实现方式中，如果 `f` 和 `g` 都不成功，那么 `first(f, g)` 将不会完成（即返回一个值或者返回一个异常）。 + + ## 工具(Utilities) -为了简化在并发应用中处理时序(time)的问题，`scala.concurrent`引入了Duration抽象。Duration不是被作为另外一个通常的时间抽象存在的。他是为了用在并发(concurrency)库中使用的，Duration位于`scala.concurrent`包中。 +为了简化在并发应用中处理时序(time)的问题， `scala.concurrent` 引入了 `Duration` 抽象。`Duration` 不是被作为另外一个通常的时间抽象存在的。他是为了用在并发(concurrency)库中使用的，`Duration` 位于 `scala.concurrent` 包中。 + +`Duration` 是表示时间长短的基础类，其可以是有限的或者无限的。有限的duration用 `FiniteDuration` 类来表示，并通过 `Long` 长度和 `java.util.concurrent.TimeUnit` 来构造。无限的 durations，同样扩展自 `Duration`，只在两种情况下存在，`Duration.Inf` 和 `Duration.MinusInf`。库中同样提供了一些 `Duration` 的子类用来做隐式的转换，这些子类不应被直接使用。 + +抽象的 `Duration` 类包含了如下方法： + +1. 到不同时间单位的转换（`toNanos`，`toMicros`，`toMillis`，`toSeconds`，`toMinutes`，`toHours`，`toDays` 和 `toUnit(unit: TimeUnit)`）。 +2. durations的比较（`<`，`<=`，`>`和`>=`）。 +3. 算术运算符（`+`，`-`，`*`，`/`和 `unary_-`） +4. `this` duration 与提供的参数之间的最大和最小的方法（`min`，`max`）。 +5. 检查 duration是否有限（`isFinite`）。 + +`Duration` 能够用如下方法实例化（`instantiated`）： + +1. 通过 `Int` 和 `Long` 类型隐式转换，例如：`val d = 100 millis`。 +2. 通过传递一个 `Long` 长度和 `java.util.concurrent.TimeUnit`。例如：`val d = Duration(100, MILLISECONDS)`。 +3. 通过传递一个字符串来表示时间区间，例如： `val d = Duration("1.2 µs")`。 + +Duration 也提供了 `unapply` 方法，因此可以被用于模式匹配中，例如： + +{% tabs futures-17 class=tabs-scala-version %} +{% tab 'Scala 2' for=futures-17 %} + +```scala +import scala.concurrent.duration._ +import java.util.concurrent.TimeUnit._ -Duration是表示时间长短的基础类，其可以是有限的或者无限的。有限的duration用FiniteDuration类来表示，并通过时间长度`(length)`和`java.util.concurrent.TimeUnit`来构造。无限的durations，同样扩展了Duration，只在两种情况下存在，`Duration.Inf`和`Duration.MinusInf`。库中同样提供了一些Durations的子类用来做隐式的转换，这些子类不应被直接使用。 +// instantiation +val d1 = Duration(100, MILLISECONDS) // from Long and TimeUnit +val d2 = Duration(100, "millis") // from Long and String +val d3 = 100 millis // implicitly from Long, Int or Double +val d4 = Duration("1.2 µs") // from String -抽象的Duration类包含了如下方法： +// pattern matching +val Duration(length, unit) = 5 millis +``` -到不同时间单位的转换`(toNanos, toMicros, toMillis, toSeconds, toMinutes, toHours, toDays and toUnit(unit: TimeUnit))`。 -durations的比较`(<，<=，>和>=)`。 -算术运算符`（+, -, *, / 和单值运算_-）` -duration的最大最小方法`(min，max)`。 -测试duration是否是无限的方法`(isFinite)`。 -Duration能够用如下方法实例化`(instantiated)`： +{% endtab %} +{% tab 'Scala 3' for=futures-17 %} -隐式的通过Int和Long类型转换得来 `val d = 100 millis`。 -通过传递一个`Long length`和`java.util.concurrent.TimeUnit`。例如`val d = Duration(100, MILLISECONDS)`。 -通过传递一个字符串来表示时间区间，例如 `val d = Duration("1.2 µs")`。 -Duration也提供了unapply方法，因此可以i被用于模式匹配中，例如： +```scala +import scala.concurrent.duration.* +import java.util.concurrent.TimeUnit.* - import scala.concurrent.duration._ - import java.util.concurrent.TimeUnit._ +// instantiation +val d1 = Duration(100, MILLISECONDS) // from Long and TimeUnit +val d2 = Duration(100, "millis") // from Long and String +val d3 = 100.millis // implicitly from Long, Int or Double +val d4 = Duration("1.2 µs") // from String - // instantiation - val d1 = Duration(100, MILLISECONDS) // from Long and TimeUnit - val d2 = Duration(100, "millis") // from Long and String - val d3 = 100 millis // implicitly from Long, Int or Double - val d4 = Duration("1.2 µs") // from String +// pattern matching +val Duration(length, unit) = 5.millis +``` - // pattern matching - val Duration(length, unit) = 5 millis +{% endtab %} +{% endtabs %} diff --git a/_zh-cn/overviews/core/implicit-classes.md b/_zh-cn/overviews/core/implicit-classes.md index 12c6f5f555..e7ec62cad1 100644 --- a/_zh-cn/overviews/core/implicit-classes.md +++ b/_zh-cn/overviews/core/implicit-classes.md @@ -5,8 +5,6 @@ title: Implicit Classes partof: implicit-classes language: zh-cn - -discourse: false --- **Josh Suereth 著** @@ -15,7 +13,7 @@ discourse: false Scala 2.10引入了一种叫做隐式类的新特性。隐式类指的是用implicit关键字修饰的类。在对应的作用域内，带有这个关键字的类的主构造函数可用于隐式转换。 -隐式类型是在[SIP-13](http://docs.scala-lang.org/sips/pending/implicit-classes.html)中提出的。 +隐式类型是在[SIP-13](https://docs.scala-lang.org/sips/pending/implicit-classes.html)中提出的。 ## 用法 @@ -63,7 +61,7 @@ Scala 2.10引入了一种叫做隐式类的新特性。隐式类指的是用impl 2. 构造函数只能携带一个非隐式参数。 ```` - implicit class RichDate(date: java.util.Date) // 正确！ + implicit class RichDate(date: java.time.LocalDate) // 正确！ implicit class Indexer[T](collecton: Seq[T], index: Int) // 错误！ implicit class Indexer[T](collecton: Seq[T])(implicit index: Index) // 正确！ ```` diff --git a/_zh-cn/overviews/core/string-interpolation.md b/_zh-cn/overviews/core/string-interpolation.md deleted file mode 100644 index 91fed4b818..0000000000 --- a/_zh-cn/overviews/core/string-interpolation.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -layout: singlepage-overview -title: 字符串插值 - -partof: string-interpolation - -language: zh-cn - -discourse: false ---- - -**Josh Suereth 著** - -## 简介 - -自2.10.0版本开始，Scala提供了一种新的机制来根据数据生成字符串：字符串插值。字符串插值允许使用者将变量引用直接插入处理过的字面字符中。如下例： - - val name="James" - println(s"Hello,$name")//Hello,James - -在上例中， s"Hello,$name" 是待处理字符串字面，编译器会对它做额外的工作。待处理字符串字面通过“号前的字符来标示（例如：上例中是s）。字符串插值的实现细节在 [SIP-11](http://docs.scala-lang.org/sips/pending/string-interpolation.html) 中有全面介绍。 - -## 用法 - -Scala 提供了三种创新的字符串插值方法：s,f 和 raw. - -### s 字符串插值器 - -在任何字符串前加上s，就可以直接在串中使用变量了。你已经见过这个例子： - - val name="James" - println(s"Hello,$name")//Hello,James -此例中，$name嵌套在一个将被s字符串插值器处理的字符串中。插值器知道在这个字符串的这个地方应该插入这个name变量的值，以使输出字符串为Hello,James。使用s插值器，在这个字符串中可以使用任何在处理范围内的名字。 - -字符串插值器也可以处理任意的表达式。例如： - - println(s"1+1=${1+1}") -将会输出字符串1+1=2。任何表达式都可以嵌入到${}中。 - -### f 插值器 - -在任何字符串字面前加上 f，就可以生成简单的格式化串，功能相似于其他语言中的 printf 函数。当使用 f 插值器的时候，所有的变量引用都应当后跟一个printf-style格式的字符串，如%d。看下面这个例子： - - val height=1.9d - val name="James" - println(f"$name%s is $height%2.2f meters tall")//James is 1.90 meters tall -f 插值器是类型安全的。如果试图向只支持 int 的格式化串传入一个double 值，编译器则会报错。例如： - - val height:Double=1.9d - - scala>f"$height%4d" - :9: error: type mismatch; - found : Double - required: Int - f"$height%4d" - ^ -f 插值器利用了java中的字符串数据格式。这种以%开头的格式在 [Formatter javadoc] 中有相关概述。如果在具体变量后没有%，则格式化程序默认使用 %s（串型）格式。 - -### raw 插值器 - -除了对字面值中的字符不做编码外，raw 插值器与 s 插值器在功能上是相同的。如下是个被处理过的字符串： - - scala>s"a\nb" - res0:String= - a - b -这里，s 插值器用回车代替了\n。而raw插值器却不会如此处理。 - - scala>raw"a\nb" - res1:String=a\nb -当不想输入\n被转换为回车的时候，raw 插值器是非常实用的。 - -除了以上三种字符串插值器外，使用者可以自定义插值器。 - -### 高级用法 - -在Scala中，所有处理过的字符串字面值都进行了简单编码转换。任何时候编译器遇到一个如下形式的字符串字面值： - - id"string content" -它都会被转换成一个StringContext实例的call(id)方法。这个方法在隐式范围内仍可用。只需要简单得 -建立一个隐类，给StringContext实例增加一个新方法，便可以定义我们自己的字符串插值器。如下例： - - //注意：为了避免运行时实例化，我们从AnyVal中继承。 - //更多信息请见值类的说明 - implicit class JsonHelper(val sc:StringContext) extends AnyVal{ - def json(args:Any*):JSONObject=sys.error("TODO-IMPLEMENT") - } - - def giveMeSomeJson(x:JSONObject):Unit=... - - giveMeSomeJson(json"{name:$name,id:$id}") -在这个例子中，我们试图通过字符串插值生成一个JSON文本语法。隐类 JsonHelper 作用域内使用该语法，且这个JSON方法需要一个完整的实现。只不过，字符串字面值格式化的结果不是一个字符串，而是一个JSON对象。 - -当编译器遇到"{name:$name,id:$id"}"，它将会被重写成如下表达式： - - new StringContext("{name:",",id:","}").json(name,id) - -隐类则被重写成如下形式 - - new JsonHelper(new StringContext("{name:",",id:","}")).json(name,id) - -所以，JSON方法可以访问字符串的原生片段而每个表达式都是一个值。这个方法的一个简单但又令人迷惑的例子： - - implicit class JsonHelper(val sc:StringContext) extends AnyVal{ - def json(args:Any*):JSONObject={ - val strings=sc.parts.iterator - val expressions=args.iterator - var buf=new StringBuffer(strings.next) - while(strings.hasNext){ - buf append expressions.next - buf append strings.next - } - parseJson(buf) - } - } - -被处理过的字符串的每部分都是StringContext的成员。每个表达式的值都将传入到JSON方法的args参数。JSON方法接受这些值并合成一个大字符串，然后再解析成JSON格式。有一种更复杂的实现可以避免合成字符串的操作，它只是简单的直接通过原生字符串和表达式值构建JSON。 - -## 限制 - -字符串插值目前对模式匹配语句不适用。此特性将在2.11版本中生效。 diff --git a/_zh-cn/overviews/core/value-classes.md b/_zh-cn/overviews/core/value-classes.md index 85014abdb8..9b9446a94b 100644 --- a/_zh-cn/overviews/core/value-classes.md +++ b/_zh-cn/overviews/core/value-classes.md @@ -5,15 +5,13 @@ title: Value Classes and Universal Traits partof: value-classes language: zh-cn - -discourse: false --- **Mark Harrah 著** ## 引言 -Value classes是在[SIP-15](http://docs.scala-lang.org/sips/pending/value-classes.html)中提出的一种通过继承AnyVal类来避免运行时对象分配的新机制。以下是一个最简的value class。 +Value classes是在[SIP-15](https://docs.scala-lang.org/sips/pending/value-classes.html)中提出的一种通过继承AnyVal类来避免运行时对象分配的新机制。以下是一个最简的value class。 class Wrapper(val underlying: Int) extends AnyVal @@ -37,7 +35,7 @@ Value class只能继承universal traits，但其自身不能再被继承。所 ## 扩展方法 -关于value类的一个用例，是将它们和隐含类联合（[SIP-13](http://docs.scala-lang.org/sips/pending/implicit-classes.html)）以获得免分配扩展方法。使用隐含类可以提供便捷的语法来定义扩展方法，同时 value 类移除运行时开销。一个好的例子是在标准库里的RichInt类。RichInt 继承自Int类型并附带一些方法。由于它是一个 value类，使用RichInt 方法时不需要创建一个RichInt 的实例。 +关于value类的一个用例，是将它们和隐含类联合（[SIP-13](https://docs.scala-lang.org/sips/pending/implicit-classes.html)）以获得免分配扩展方法。使用隐含类可以提供便捷的语法来定义扩展方法，同时 value 类移除运行时开销。一个好的例子是在标准库里的RichInt类。RichInt 继承自Int类型并附带一些方法。由于它是一个 value类，使用RichInt 方法时不需要创建一个RichInt 的实例。 下面有关RichInt的代码片段示范了RichInt是如何继承Int来允许3.toHexString的表达式： @@ -45,7 +43,7 @@ Value class只能继承universal traits，但其自身不能再被继承。所 def toHexString: String = java.lang.Integer.toHexString(self) } -在运行时，表达式3.toHexString 被优化并等价于静态对象的方法调用 （RichInt$.MODULE$.extension$toHexString(3)），而不是创建一个新实例对象，再调用其方法。 +在运行时，表达式3.toHexString 被优化并等价于静态对象的方法调用 （RichInt$.MODULE$.toHexString$extension(3)），而不是创建一个新实例对象，再调用其方法。 ## 正确性 @@ -123,12 +121,12 @@ value类在以下情况下，需要真正实例化： 一个value类 ... -1. ... 必须只有一个public的构造函数。并有且只有一个public的，类型不为value类的val参数。 -2. ... 不能有特殊的类型参数. -3. ... 不能有嵌套或本地类、trait或对象。 +1. ... 必须只有一个主构造器。该构造器有且仅有一个public修饰的不可变（val）参数，且参数的类型不是用户自定义的value类。 +2. ... 不能有特殊的类型参数。 +3. ... 不能有嵌套或局部的类、特质或对象。 4. ... 不能定义equals或hashCode方法。 -5. ... 必须是一个顶级类，或静态访问对象的一个成员 -6. ... 仅能有def为成员。尤其是，成员不能有惰性val、val或者var 。 +5. ... 必须是一个顶级类，或静态访问对象的一个成员。 +6. ... 仅能有def为成员。尤其是，成员不能有惰性val、val或者var。 7. ... 不能被其它类继承。 ### 限制示例 @@ -226,7 +224,7 @@ value class不能将惰性val或val作为成员，也不能有嵌套类、trait value类不能继承non-universal trait，并且其本身不能被继承： trait NotUniversal - class Value(val x: Int) extends AnyVal with notUniversal + class Value(val x: Int) extends AnyVal with NotUniversal class Extend(x: Int) extends Value(x) Extend.scala:2: error: illegal inheritance; superclass AnyVal diff --git a/_zh-cn/overviews/index.md b/_zh-cn/overviews/index.md index 63c1b87fa9..a051fef550 100644 --- a/_zh-cn/overviews/index.md +++ b/_zh-cn/overviews/index.md @@ -1,53 +1,10 @@ --- -layout: inner-page-no-masthead +layout: overviews language: zh-cn +partof: overviews title: 目录 +redirect_from: + - /zh-cn/scala3/guides.html --- -
            -

            核心库

            -
            - * Scala的容器类 - * [简介](/zh-cn/overviews/collections/introduction.html) - * [Mutable和Immutable集合](/zh-cn/overviews/collections/overview.html) - * [Trait Traversable](/zh-cn/overviews/collections/trait-traversable.html) - * [Trait Iterable](/zh-cn/overviews/collections/trait-iterable.html) - * [序列trait：Seq、IndexedSeq 及 LinearSeq](/zh-cn/overviews/collections/seqs.html) - * [集合](/zh-cn/overviews/collections/sets.html) - * [映射](/zh-cn/overviews/collections/maps.html) - * [具体的不可变集实体类](/zh-cn/overviews/collections/concrete-immutable-collection-classes.html) - * [具体的可变容器类](/zh-cn/overviews/collections/concrete-mutable-collection-classes.html) - * [数组](/zh-cn/overviews/collections/arrays.html) - * [字符串](/zh-cn/overviews/collections/strings.html) - * [性能特点](/zh-cn/overviews/collections/performance-characteristics.html) - * [等价性](/zh-cn/overviews/collections/equality.html) - * [视图](/zh-cn/overviews/collections/views.html) - * [Iterators](/zh-cn/overviews/collections/iterators.html) - * [从头定义新容器](/zh-cn/overviews/collections/creating-collections-from-scratch.html) - * [Java和Scala容器的转换](/zh-cn/overviews/collections/conversions-between-java-and-scala-collections.html) - * [Scala 2.7迁移指南](/zh-cn/overviews/collections/migrating-from-scala-27.html) - * [Scala容器类体系结构](/zh-cn/overviews/core/architecture-of-scala-collections.html) - * [字符串插值](/zh-cn/overviews/core/string-interpolation.html) New in 2.10 - * [Implicit Classes](/zh-cn/overviews/core/implicit-classes.html) New in 2.10 - * [Value Classes and Universal Traits](/zh-cn/overviews/core/value-classes.html) New in 2.10 - -
            -

            Parallel and Concurrent Programming

            -
            - * [Future和Promise](/zh-cn/overviews/core/futures.html) New in 2.10 - * Scala的并行容器类 - * [概述](/zh-cn/overviews/parallel-collections/overview.html) - * [具体并行集合类](/zh-cn/overviews/parallel-collections/concrete-parallel-collections.html) - * [并行容器的转换](/zh-cn/overviews/parallel-collections/conversions.html) - * [并发字典树](/zh-cn/overviews/parallel-collections/ctries.html) - * [并行集合库的架构](/zh-cn/overviews/parallel-collections/architecture.html) - * [创建自定义并行容器](/zh-cn/overviews/parallel-collections/custom-parallel-collections.html) - * [配置并行集合](/zh-cn/overviews/parallel-collections/configuration.html) - * [测量性能](/zh-cn/overviews/parallel-collections/performance.html) - * [Scala Actors迁移指南](/zh-cn/overviews/core/actors-migration-guide.html) New in 2.10 - * [The Scala Actors API](/zh-cn/overviews/core/actors.html) Deprecated - -
            -

            Acknowledgements

            -
            -* [致谢名单](/zh-cn/overviews/thanks.html) + diff --git a/_zh-cn/overviews/parallel-collections/architecture.md b/_zh-cn/overviews/parallel-collections/architecture.md index b2aeb118b2..e0bfc8c7c7 100644 --- a/_zh-cn/overviews/parallel-collections/architecture.md +++ b/_zh-cn/overviews/parallel-collections/architecture.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 并行集合库的架构 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -56,8 +53,8 @@ Scala集合的层次和并行集合库 为了能够获得一个序列集合或并行集合的引用（这样可以通过par和seq在并行集合和序列集合之间切换)，两种集合类型存在一个共同的超型。这是上面所示的“通用”特征的起源，GenTraversable, GenIterable, GenSeq, GenMap and GenSet，不保证按次序或挨个的遍历。相应的序列或并行特征继承于这些。例如，一个ParSeq和Seq都是一个通用GenSeq的子类型，但是他们之间没有相互公认的继承关系。 -更详细的讨论序列集合和并行集合器之间的层次共享，请参见技术报告。[[1](http://infoscience.epfl.ch/record/165523/files/techrep.pdf)] +更详细的讨论序列集合和并行集合器之间的层次共享，请参见技术报告。[[1](https://infoscience.epfl.ch/record/165523/files/techrep.pdf)] 引用 -1. [On a Generic Parallel Collection Framework, Aleksandar Prokopec, Phil Bawgell, Tiark Rompf, Martin Odersky, June 2011](http://infoscience.epfl.ch/record/165523/files/techrep.pdf) +1. [On a Generic Parallel Collection Framework, Aleksandar Prokopec, Phil Bawgell, Tiark Rompf, Martin Odersky, June 2011](https://infoscience.epfl.ch/record/165523/files/techrep.pdf) diff --git a/_zh-cn/overviews/parallel-collections/concrete-parallel-collections.md b/_zh-cn/overviews/parallel-collections/concrete-parallel-collections.md index 9aac14f0d3..ea11bedf72 100644 --- a/_zh-cn/overviews/parallel-collections/concrete-parallel-collections.md +++ b/_zh-cn/overviews/parallel-collections/concrete-parallel-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 具体并行集合类 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -24,7 +21,7 @@ language: zh-cn scala> pa map (x => (x - 1) / 2) res1: scala.collection.parallel.mutable.ParArray[Int] = ParArray(0, 1, 2, 3, 4, 5, 6, 7,... -在内部，分离一个并行数组[分离器](http://docs.scala-lang.org/overviews/parallel-collections/architecture.html)相当于使用它们的下标迭代器更新来创建两个分离器。[组合](http://docs.scala-lang.org/overviews/parallel-collections/architecture.html)稍微负责一点。因为大多数的分离方法(如：flatmap, filter, takeWhile等)我们不能预先知道元素的个数（或者数组的大小），每一次组合本质上来说是一个数组缓冲区的一种变量根据分摊时间来进行加减的操作。不同的处理器进行元素相加操作，对每个独立并列数组进行组合，然后根据其内部连结在再进行组合。在并行数组中的基础数组只有在知道元素的总数之后才能被分配和填充。基于此，变换方法比存取方法要稍微复杂一些。另外，请注意，最终数组分配在JVM上的顺序进行，如果映射操作本身是很便宜，这可以被证明是一个序列瓶颈。 +在内部，分离一个并行数组[分离器](https://docs.scala-lang.org/overviews/parallel-collections/architecture.html)相当于使用它们的下标迭代器更新来创建两个分离器。[组合](https://docs.scala-lang.org/overviews/parallel-collections/architecture.html)稍微负责一点。因为大多数的分离方法(如：flatmap, filter, takeWhile等)我们不能预先知道元素的个数（或者数组的大小），每一次组合本质上来说是一个数组缓冲区的一种变量根据分摊时间来进行加减的操作。不同的处理器进行元素相加操作，对每个独立并列数组进行组合，然后根据其内部连结在再进行组合。在并行数组中的基础数组只有在知道元素的总数之后才能被分配和填充。基于此，变换方法比存取方法要稍微复杂一些。另外，请注意，最终数组分配在JVM上的顺序进行，如果映射操作本身是很便宜，这可以被证明是一个序列瓶颈。 通过调用seq方法，并行数组(parallel arrays)被转换为对应的顺序容器(sequential collections) ArraySeq。这种转换是非常高效的，因为新创建的ArraySeq 底层是通过并行数组(parallel arrays)获得的。 @@ -55,7 +52,7 @@ language: zh-cn ### 并行哈希表(Parallel Hash Tables) -并行哈希表存储在底层数组的元素，并将它们放置在由各自元素的哈希码的位置。并行不变的哈希集(set)（[mutable.ParHashSet](http://www.scala-lang.org/api/2.10.0/scala/collection/parallel/mutable/ParHashSet.html)）和并行不变的哈希映射([mutable.ParHashMap](http://www.scala-lang.org/api/2.10.0/scala/collection/parallel/mutable/ParHashMap.html)) 是基于哈希表的。 +并行哈希表存储在底层数组的元素，并将它们放置在由各自元素的哈希码的位置。并行不变的哈希集(set)（[mutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParHashSet.html)）和并行不变的哈希映射([mutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParHashMap.html)) 是基于哈希表的。 scala> val phs = scala.collection.parallel.mutable.ParHashSet(1 until 2000: _*) phs: scala.collection.parallel.mutable.ParHashSet[Int] = ParHashSet(18, 327, 736, 1045, 773, 1082,... @@ -69,7 +66,7 @@ language: zh-cn ### 并行散列Tries(Parallel Hash Tries) -并行hash tries是不可变(immutable)hash tries的并行版本，这种结果可以用来高效的维护不可变集合(immutable set)和不可变关联数组(immutable map)。他们都支持类[immutable.ParHashSet](http://www.scala-lang.org/api/2.10.0/scala/collection/parallel/immutable/ParHashSet.html)和[immutable.ParHashMap](http://www.scala-lang.org/api/2.10.0/scala/collection/parallel/immutable/ParHashMap.html)。 +并行hash tries是不可变(immutable)hash tries的并行版本，这种结果可以用来高效的维护不可变集合(immutable set)和不可变关联数组(immutable map)。他们都支持类[immutable.ParHashSet](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/immutable/ParHashSet.html)和[immutable.ParHashMap](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/immutable/ParHashMap.html)。 scala> val phs = scala.collection.parallel.immutable.ParHashSet(1 until 1000: _*) phs: scala.collection.parallel.immutable.ParHashSet[Int] = ParSet(645, 892, 69, 809, 629, 365, 138, 760, 101, 479,... @@ -83,7 +80,7 @@ language: zh-cn ### 并行并发tries(Parallel Concurrent Tries) -[ concurrent.triemap ](http://www.scala-lang.org/api/2.10.0/scala/collection/concurrent/TrieMap.html)是竞争对手的线程安全的地图，而[ mutable.partriemap ](http://www.scala-lang.org/api/2.10.0/scala/collection/parallel/mutable/ParTrieMap.html) 是他的并行副本。如果这个数据结构在遍历的过程中被修改了，大多数竞争对手的数据结构不能确保一致遍历，尝试确保在下一次迭代中更新是可见的。这意味着，你可以在尝试遍历的时候改变这些一致性，如下例子所示输出1到99的平方根。 +[ concurrent.triemap ](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/concurrent/TrieMap.html)是竞争对手的线程安全的地图，而[ mutable.partriemap ](https://www.scala-lang.org/api/{{ site.scala-212-version}}/scala/collection/parallel/mutable/ParTrieMap.html) 是他的并行副本。如果这个数据结构在遍历的过程中被修改了，大多数竞争对手的数据结构不能确保一致遍历，尝试确保在下一次迭代中更新是可见的。这意味着，你可以在尝试遍历的时候改变这些一致性，如下例子所示输出1到99的平方根。 scala> val numbers = scala.collection.parallel.mutable.ParTrieMap((1 until 100) zip (1 until 100): _*) map { case (k, v) => (k.toDouble, v.toDouble) } numbers: scala.collection.parallel.mutable.ParTrieMap[Double,Double] = ParTrieMap(0.0 -> 0.0, 42.0 -> 42.0, 70.0 -> 70.0, 2.0 -> 2.0,... diff --git a/_zh-cn/overviews/parallel-collections/configuration.md b/_zh-cn/overviews/parallel-collections/configuration.md index 362b06920e..7f3f808a4c 100644 --- a/_zh-cn/overviews/parallel-collections/configuration.md +++ b/_zh-cn/overviews/parallel-collections/configuration.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 配置并行集合 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -16,7 +13,7 @@ language: zh-cn 并行集合是以操作调度的方式建模的。每一个并行集合都有一个任务支持对象作为参数，该对象负责处理器任务的调度和负载均衡。 -任务支持对象内部有一个线程池实例的引用，并且决定着任务细分成更小任务的方式和时机。更多关于这方面的实现细节，请参考技术手册 [[1](http://infoscience.epfl.ch/record/165523/files/techrep.pdf)]。 +任务支持对象内部有一个线程池实例的引用，并且决定着任务细分成更小任务的方式和时机。更多关于这方面的实现细节，请参考技术手册 [[1](https://infoscience.epfl.ch/record/165523/files/techrep.pdf)]。 并行集合的任务支持现在已经有一些可用的实现。ForkJoinTaskSupport内部使用fork-join池，并被默认用与JVM1.6以及更高的版本。ThreadPoolTaskSupport 效率更低，是JVM1.5和不支持fork-join池的JVM的回退。ExecutionContextTaskSupport 使用在scala.concurrent中默认的执行上下文实现，并且它重用在scala.concurrent使用的线程池（根据JVM版本，可能是fork join 池或线程池执行器）。执行上下文的任务支持被默认地设置到每个并行集合中，所以并行集合重用相同的fork-join池。 @@ -56,4 +53,4 @@ execute方法异步调度任务并且返回等待计算结果的未来状态。e **引用** -1. [On a Generic Parallel Collection Framework, June 2011](http://infoscience.epfl.ch/record/165523/files/techrep.pdf) +1. [On a Generic Parallel Collection Framework, June 2011](https://infoscience.epfl.ch/record/165523/files/techrep.pdf) diff --git a/_zh-cn/overviews/parallel-collections/conversions.md b/_zh-cn/overviews/parallel-collections/conversions.md index 788ca55630..4fff12e7c5 100644 --- a/_zh-cn/overviews/parallel-collections/conversions.md +++ b/_zh-cn/overviews/parallel-collections/conversions.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 并行容器的转换 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -46,7 +43,7 @@ language: zh-cn |toStream | Stream | |toIterator | Iterator | |toBuffer | Buffer | -|toTraversable | GenTraverable | +|toTraversable | GenTraversable | |toIterable | ParIterable | |toSeq | ParSeq | |toSet | ParSet | diff --git a/_zh-cn/overviews/parallel-collections/ctries.md b/_zh-cn/overviews/parallel-collections/ctries.md index d3a2dc7d53..c8a0b5d044 100644 --- a/_zh-cn/overviews/parallel-collections/ctries.md +++ b/_zh-cn/overviews/parallel-collections/ctries.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 并发字典树 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -39,7 +36,7 @@ language: zh-cn } } -注意，在上面的计算平方根的巴比伦算法([3](http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method))中，某些数据会比别的数据收敛的更快。基于这个因素，我们希望能够尽快把他们从结果中剔除，只遍历那些真正需要耗时处理的元素。 +注意，在上面的计算平方根的巴比伦算法([3](https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method))中，某些数据会比别的数据收敛的更快。基于这个因素，我们希望能够尽快把他们从结果中剔除，只遍历那些真正需要耗时处理的元素。 另一个例子是广度优先搜索算法，该算法迭代地在末端节点遍历，直到找到通往目标的路径，或遍历完所有周围节点。一个二维地图上的节点定义为Int的元组。map定义为二维布尔值数组，用来表示各个位置是否已经到达。然后，定义2个并行字典树映射，open和closed。其中，映射open保存接着需要被遍历的末端节点。映射closed保存所有已经被遍历过的节点。映射open使用恰当节点来初始化，用以从地图的一角开始搜索，并找到通往地图中心的路径。随后，并行地对映射open中的所有节点迭代遍历，直到没有节点可以遍历。每次一个节点被遍历时，将它从映射open中移除，并放置在映射closed中。一旦执行完成，输出从目标节点到初始节点的路径。 （译者注：如扫雷，不断判断当前位置（末端节点）上下左右是否为地雷（二维布尔数组），从起始位置逐渐向外扩张。） @@ -98,7 +95,7 @@ language: zh-cn println() 例如，GitHub上个人生游戏的示例，就是使用Ctries去选择性地模拟人生游戏中当前活跃的机器人([4](https://github.com/axel22/ScalaDays2012-TrieMap))。它还基于Swing实现了模拟的人生游戏的视觉化，以便很直观地观察到调整参数是如何影响执行。 -并发字典树也支持线性化、无锁、及定时快照操作。这些操作会利用特定时间点上的所有元素来创建新并发 字典树。因此，实际上捕获了特定时间点上的字典树状态。快照操作仅仅为并发字典树生成一个新的根。子序列采用惰性更新的策略，只重建与更新相关的部分，其余部分保持原样。首先，这意味着，由于不需要拷贝元素，自动快照操作资源消耗较少。其次，写时拷贝优化策略只拷贝并发字典树的部分，后续的修改可以横向展开。readOnlySnapshot方法比Snapshot方法效率略高，但它返回的是无法修改的只读的映射。并发字典树也支持线性化，定时清除操作基于快照机制。了解更多关于并发字典树及快照的工作方式，请参阅 ([1](http://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf)) 和 ([2](http://lampwww.epfl.ch/~prokopec/ctries-snapshot.pdf)). +并发字典树也支持线性化、无锁、及定时快照操作。这些操作会利用特定时间点上的所有元素来创建新并发 字典树。因此，实际上捕获了特定时间点上的字典树状态。快照操作仅仅为并发字典树生成一个新的根。子序列采用惰性更新的策略，只重建与更新相关的部分，其余部分保持原样。首先，这意味着，由于不需要拷贝元素，自动快照操作资源消耗较少。其次，写时拷贝优化策略只拷贝并发字典树的部分，后续的修改可以横向展开。readOnlySnapshot方法比Snapshot方法效率略高，但它返回的是无法修改的只读的映射。并发字典树也支持线性化，定时清除操作基于快照机制。了解更多关于并发字典树及快照的工作方式，请参阅 ([1](https://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf)) 和 ([2](http://lampwww.epfl.ch/~prokopec/ctries-snapshot.pdf)). 并发字典树的迭代器基于快照实现。在迭代器对象被创建之前，会创建一个并发字典树的快照，所以迭代器只在字典树的快照创建时的元素中进行遍历。当然，迭代器使用只读快照。 @@ -106,7 +103,7 @@ size操作也基于快照。一种直接的实现方式是，size调用仅仅生 **引用** -[缓存感知无锁并发哈希字典树][1](http://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf) +[缓存感知无锁并发哈希字典树][1](https://infoscience.epfl.ch/record/166908/files/ctries-techreport.pdf) [具有高效非阻塞快照的并发字典树][2](http://lampwww.epfl.ch/~prokopec/ctries-snapshot.pdf) -[计算平方根的方法][3](http://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method) +[计算平方根的方法][3](https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method) [人生游戏模拟程序][4](https://github.com/axel22/ScalaDays2012-TrieMap)（译注：类似大富翁的棋盘游戏） diff --git a/_zh-cn/overviews/parallel-collections/custom-parallel-collections.md b/_zh-cn/overviews/parallel-collections/custom-parallel-collections.md index d6abd74588..50e1ac1e6a 100644 --- a/_zh-cn/overviews/parallel-collections/custom-parallel-collections.md +++ b/_zh-cn/overviews/parallel-collections/custom-parallel-collections.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 创建自定义并行容器 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections diff --git a/_zh-cn/overviews/parallel-collections/overview.md b/_zh-cn/overviews/parallel-collections/overview.md index 160432d0c3..b4aa6d24dd 100644 --- a/_zh-cn/overviews/parallel-collections/overview.md +++ b/_zh-cn/overviews/parallel-collections/overview.md @@ -1,9 +1,6 @@ --- layout: multipage-overview title: 概述 - -discourse: false - partof: parallel-collections overview-name: Parallel Collections @@ -96,7 +93,7 @@ Scala的并行容器库设计创意般的同Scala的（序列）容器库（从2 注意：那些天生就有序的容器（意思是元素必须一个接一个的访问），像lists，queues和streams，通过拷贝元素到类似的并行容器中被转换为它们的并行对应物。例如List--被转换为一个标准的不可变的并行序列中，就是ParVector。当然，其他容器类型不需要这些拷贝的开销，比如：Array，Vector，HashMap等等。 -关于并行容器的转换的更多信息请参见 [conversions](http://docs.scala-lang.org/overviews/parallel-collections/conversions.html) 和 [concrete parallel collections classes](http://docs.scala-lang.org/overviews/parallel-collections/concrete-parallel-collections.html)章节 +关于并行容器的转换的更多信息请参见 [conversions](https://docs.scala-lang.org/overviews/parallel-collections/conversions.html) 和 [concrete parallel collections classes](https://docs.scala-lang.org/overviews/parallel-collections/concrete-parallel-collections.html)章节 ## 语义(semantic) diff --git a/_zh-cn/overviews/parallel-collections/performance.md b/_zh-cn/overviews/parallel-collections/performance.md index e3170330d2..1e6cdc24fc 100644 --- a/_zh-cn/overviews/parallel-collections/performance.md +++ b/_zh-cn/overviews/parallel-collections/performance.md @@ -13,7 +13,7 @@ language: zh-cn 对JVM性能模型的评论常常令人费解，其结论也往往不易理解。由于种种原因，代码也可能不像预期的那样高性能、可扩展。在这里，我们提供了一些示例。 -其中一个原因是JVM应用程序的编译过程不同于静态编译语言（见[[2](http://www.ibm.com/developerworks/library/j-jtp12214/)]）。Java和Scala的编译器将源代码转换为JVM的字节码，做了非常少的优化。大多数现代JVM，运行时，会把字节码转化成相应机器架构的机器代码。这个过程被称为即时编译。由于追求运行速度，所以实时编译的代码优化程度较低。为了避免重新编译，所谓的HotSpot编译器只优化了部分经常被运行的代码。这对于基准程序作者来说，这意味着程序每次运行时的性能都可能不同。在同一个JVM实例中多次执行一段相同的代码（比如一个方法）可能会得到非常不同的性能结果，这取决于这段代码在运行过程中是否被优化。另外，在测量某些代码的执行时间时其中可能包含JIT编译器对代码进行优化的时间，因此可能得到不一致的结果。 +其中一个原因是JVM应用程序的编译过程不同于静态编译语言（见[[2](https://www.ibm.com/developerworks/library/j-jtp12214/)]）。Java和Scala的编译器将源代码转换为JVM的字节码，做了非常少的优化。大多数现代JVM，运行时，会把字节码转化成相应机器架构的机器代码。这个过程被称为即时编译。由于追求运行速度，所以实时编译的代码优化程度较低。为了避免重新编译，所谓的HotSpot编译器只优化了部分经常被运行的代码。这对于基准程序作者来说，这意味着程序每次运行时的性能都可能不同。在同一个JVM实例中多次执行一段相同的代码（比如一个方法）可能会得到非常不同的性能结果，这取决于这段代码在运行过程中是否被优化。另外，在测量某些代码的执行时间时其中可能包含JIT编译器对代码进行优化的时间，因此可能得到不一致的结果。 另一个在JVM上隐藏执行的是内存自动管理。每隔一段时间，程序的运行就被阻塞并且启动垃圾收集器。如果被进行基准测试的程序分配了任何堆内存（大部分JVM程序都会分配），垃圾收集器将会工作，因此可能会影响测量结果。为了缓冲垃圾收集的影响，被测量的程序应该运行多次以便触发多次垃圾回收。 @@ -176,6 +176,6 @@ collection的大小所对应的实际并发消耗取决于很多因素。部分 **引用** -1. [Anatomy of a flawed microbenchmark，Brian Goetz](http://www.ibm.com/developerworks/java/library/j-jtp02225/index.html) -2. [Dynamic compilation and performance measurement, Brian Goetz](http://www.ibm.com/developerworks/library/j-jtp12214/) +1. [Anatomy of a flawed microbenchmark，Brian Goetz](https://www.ibm.com/developerworks/java/library/j-jtp02225/index.html) +2. [Dynamic compilation and performance measurement, Brian Goetz](https://www.ibm.com/developerworks/library/j-jtp12214/) diff --git a/_zh-cn/overviews/reflection/.jekyll-metadata b/_zh-cn/overviews/reflection/.jekyll-metadata new file mode 100644 index 0000000000..72fc01387f Binary files /dev/null and b/_zh-cn/overviews/reflection/.jekyll-metadata differ diff --git a/_zh-cn/overviews/reflection/environment-universes-mirrors.md b/_zh-cn/overviews/reflection/environment-universes-mirrors.md new file mode 100644 index 0000000000..a42d247154 --- /dev/null +++ b/_zh-cn/overviews/reflection/environment-universes-mirrors.md @@ -0,0 +1,178 @@ +--- +layout: multipage-overview +title: Environment, Universes, and Mirrors +partof: reflection +overview-name: Reflection + +num: 2 +language: zh-cn +--- + +EXPERIMENTAL + +## Environment + +反射环境根据反射工作是在运行时还是在编译时完成而有所不同。在运行时和编译时使用的环境之间的区别被封装在一个所谓的 *宇宙（universe）* 中。 +反射环境的另一个重要方面是我们可以反射的访问一组实体。这组实体由所谓的 *镜像（mirror）* 决定。 + +例如，可通过运行时反射访问的实体由`ClassloaderMirror`提供。该镜像仅提供对由特定类加载器加载的实体（包，类型和成员）的访问。 + +镜像不仅可以确定反射访问的实体集。它们还提供对这些实体执行的反射操作。例如，在运行时反射中，可以使用*调用者镜像*（invoker mirror）来调用类的方法或构造函数。 + +## Universes + +宇宙有两种主要类型 - 由于同时具有运行时和编译时反射功能，一个人必须使用与即将完成的工作相对应的宇宙。二者之一： + +- `scala.reflect.runtime.universe` 用于 **运行时反射**，或者 +- `scala.reflect.macros.Universe` 用于 **编译时反射**。 + +一个宇宙提供了反射中使用的所有主要概念的接口，例如类型（`Types`），树（`Trees`）和注解（`Annotations`）。 + +## Mirrors + +反射提供的所有信息都可以通过*镜像*访问。根据要获得的信息类型或要采取的反射动作，必须使用不同类型的镜像。*类加载器镜像*可用于获取类型和成员的表示。 +从类加载器镜像中，可以获得更专门的*调用者*镜像（最常用的镜像），这些镜像实现了反射调用，例如方法或构造函数调用以及字段访问。 + +总结： + +- **"类加载器" 镜像**。这些镜像将名称转换为符号 (通过方法 `staticClass`/`staticModule`/`staticPackage`)。 + +- **"调用者" 镜像**。这些镜像实现反射调用（通过方法 `MethodMirror.apply`，`FieldMirror.get`，等等。）。这些"调用者"镜像是最常用的镜像类型。 + +### Runtime Mirrors + +在运行时使用的镜像的入口点是通过`ru.runtimeMirror()`，其中`ru`是`scala.reflect.runtime.universe`。 + +一个`scala.reflect.api.JavaMirrors＃runtimeMirror`的调用结果是一个类型为`scala.reflect.api.Mirrors＃ReflectiveMirror`的类加载器镜像，它可以按名称加载符号。 + +一个类加载器镜像可以创建多个调用者镜像（包括`scala.reflect.api.Mirrors#InstanceMirror`，`scala.reflect.api.Mirrors#MethodMirror`，`scala.reflect.api.Mirrors#FieldMirror`，`scala.reflect.api.Mirrors#ClassMirror`，和`scala.reflect.api.Mirrors#ModuleMirror`）。 + +下面提供了这两种类型的反射镜像如何相互作用的示例。 + +### Types of Mirrors, Their Use Cases & Examples + +`ReflectiveMirror`用于按名称加载符号，并用作调用者镜像的入口。入口点：`val m = ru.runtimeMirror()`。例如： + + scala> val ru = scala.reflect.runtime.universe + ru: scala.reflect.api.JavaUniverse = ... + + scala> val m = ru.runtimeMirror(getClass.getClassLoader) + m: scala.reflect.runtime.universe.Mirror = JavaMirror ... + +`InstanceMirror`用于为方法和字段以及内部类和内部对象（模块）创建调用者镜像。入口点：`val im = m.reflect()`。例如： + + scala> class C { def x = 2 } + defined class C + + scala> val im = m.reflect(new C) + im: scala.reflect.runtime.universe.InstanceMirror = instance mirror for C@3442299e + +`MethodMirror`用于调用实例方法（Scala仅具有实例方法-对象的方法是对象实例的实例方法，可通过`ModuleMirror.instance`获得）。入口点：`val mm = im.reflectMethod()`）。例如： + + scala> val methodX = ru.typeOf[C].decl(ru.TermName("x")).asMethod + methodX: scala.reflect.runtime.universe.MethodSymbol = method x + + scala> val mm = im.reflectMethod(methodX) + mm: scala.reflect.runtime.universe.MethodMirror = method mirror for C.x: scala.Int (bound to C@3442299e) + + scala> mm() + res0: Any = 2 + +`FieldMirror`用于获取/设置实例字段（与方法类似，Scala仅具有实例字段，请参见上文）。入口点：`val fm = im.reflectField()`。例如： + + scala> class C { val x = 2; var y = 3 } + defined class C + + scala> val m = ru.runtimeMirror(getClass.getClassLoader) + m: scala.reflect.runtime.universe.Mirror = JavaMirror ... + + scala> val im = m.reflect(new C) + im: scala.reflect.runtime.universe.InstanceMirror = instance mirror for C@5f0c8ac1 + + scala> val fieldX = ru.typeOf[C].decl(ru.TermName("x")).asTerm.accessed.asTerm + fieldX: scala.reflect.runtime.universe.TermSymbol = value x + + scala> val fmX = im.reflectField(fieldX) + fmX: scala.reflect.runtime.universe.FieldMirror = field mirror for C.x (bound to C@5f0c8ac1) + + scala> fmX.get + res0: Any = 2 + + scala> fmX.set(3) + + scala> val fieldY = ru.typeOf[C].decl(ru.TermName("y")).asTerm.accessed.asTerm + fieldY: scala.reflect.runtime.universe.TermSymbol = variable y + + scala> val fmY = im.reflectField(fieldY) + fmY: scala.reflect.runtime.universe.FieldMirror = field mirror for C.y (bound to C@5f0c8ac1) + + scala> fmY.get + res1: Any = 3 + + scala> fmY.set(4) + + scala> fmY.get + res2: Any = 4 + +`ClassMirror`用于为构造函数创建调用者镜像。入口点：对于静态类`val cm1 = m.reflectClass()`，对于内部类`val mm2 = im.reflectClass()`。例如： + + scala> case class C(x: Int) + defined class C + + scala> val m = ru.runtimeMirror(getClass.getClassLoader) + m: scala.reflect.runtime.universe.Mirror = JavaMirror ... + + scala> val classC = ru.typeOf[C].typeSymbol.asClass + classC: scala.reflect.runtime.universe.Symbol = class C + + scala> val cm = m.reflectClass(classC) + cm: scala.reflect.runtime.universe.ClassMirror = class mirror for C (bound to null) + + scala> val ctorC = ru.typeOf[C].decl(ru.termNames.CONSTRUCTOR).asMethod + ctorC: scala.reflect.runtime.universe.MethodSymbol = constructor C + + scala> val ctorm = cm.reflectConstructor(ctorC) + ctorm: scala.reflect.runtime.universe.MethodMirror = constructor mirror for C.(x: scala.Int): C (bound to null) + + scala> ctorm(2) + res0: Any = C(2) + +`ModuleMirror`用于访问单例对象的实例。入口点：对于静态对象`val mm1 = m.reflectModule()`，对于内部对象`val mm2 = im.reflectModule()`。例如： + + scala> object C { def x = 2 } + defined module C + + scala> val m = ru.runtimeMirror(getClass.getClassLoader) + m: scala.reflect.runtime.universe.Mirror = JavaMirror ... + + scala> val objectC = ru.typeOf[C.type].termSymbol.asModule + objectC: scala.reflect.runtime.universe.ModuleSymbol = object C + + scala> val mm = m.reflectModule(objectC) + mm: scala.reflect.runtime.universe.ModuleMirror = module mirror for C (bound to null) + + scala> val obj = mm.instance + obj: Any = C$@1005ec04 + +### Compile-Time Mirrors + +编译时镜像仅使用类加载器镜像来按名称加载符号。 + +类加载器镜像的入口点通过`scala.reflect.macros.Context＃mirror`。使用类加载器镜像的典型方法包括`scala.reflect.api.Mirror＃staticClass`，`scala.reflect.api.Mirror＃staticModule`和`scala.reflect.api.Mirror＃staticPackage`。例如： + + import scala.reflect.macros.Context + + case class Location(filename: String, line: Int, column: Int) + + object Macros { + def currentLocation: Location = macro impl + + def impl(c: Context): c.Expr[Location] = { + import c.universe._ + val pos = c.macroApplication.pos + val clsLocation = c.mirror.staticModule("Location") // get symbol of "Location" object + c.Expr(Apply(Ident(clsLocation), List(Literal(Constant(pos.source.path)), Literal(Constant(pos.line)), Literal(Constant(pos.column))))) + } + } + +注意：有几种高级替代方法，可以避免必须手动查找符号。例如，`typeOf[Location.type].termSymbol`（如果需要`ClassSymbol`，则为`typeOf[Location].typeSymbol`），因为我们不必使用字符串来查找符号，所以它们是类型安全的。 \ No newline at end of file diff --git a/_zh-cn/overviews/reflection/overview.md b/_zh-cn/overviews/reflection/overview.md new file mode 100644 index 0000000000..25f54810e9 --- /dev/null +++ b/_zh-cn/overviews/reflection/overview.md @@ -0,0 +1,296 @@ +--- +layout: multipage-overview +title: 概览 + +partof: reflection +overview-name: Reflection + +num: 1 +language: zh-cn + +permalink: /zh-cn/overviews/reflection/:title.html +--- + +EXPERIMENTAL + +**Heather Miller, Eugene Burmako, Philipp Haller** + +*反射(Reflection)*是指程序在运行过程中可以解析并甚至修改自身的一种能力。 +在横跨面向对象、函数式编程以及逻辑编程范式方面有着悠久的历史。 +虽然一些编程语言在设计之初就引入了反射作为指导原则，但是也有一些编程语言是随着时间演化逐渐引入了反射这一能力。 + +反射就是在程序运行中，将程序中隐式元素具体化(比如，使之显式化)的能力。 +这些隐式元素可以是静态编程中的元素，比如类、方法、或表达式。 +也可以是动态的元素，比如当前正在执行的[计算续体](https://zh.wikipedia.org/wiki/%E8%AE%A1%E7%AE%97%E7%BB%AD%E4%BD%93)或方法调用和访问字段这种正在执行的事件。 +一般根据在编译阶段执行反射还是在运行阶段执行反射来区分反射的类型。 +在程序编译期的反射是用于开发转换器和生成器时的好办法。 +在程序运行器的反射常用于调整语言语义或用于支持软件组件之间的后期绑定。 + +Scala 2.10版本以前一直没有反射功能。 +相应的替代品是借用了一部分Java的反射API实现了动态类型检查和对象成员的访问。 +然而很多Scala特有元素单用Java反射是无效的，反射操作只能暴露出Java元素以及类型。 +另外，使用Java反射也不能覆盖到运行时环境的类型信息，且对Scala中的泛型类型也存在限制。 + +在Scala 2.10版本中引入了一个全新的反射库，不仅弥补了原使用Java方式无法在Scala特定类型和泛型类型上进行反射操作的缺陷，而且还为Scala添加了一个功能更强大的通用反射工具箱。 +伴随着提供针对Scala类型和泛型全功能覆盖的运行时反射机制，Scala 2.10还提供了[宏](https://docs.scala-lang.org/overviews/macros/overview.html)形式的编译时反射功能，以及可以将Scala表达式修整改写后添入抽象语法树的能力。 + + +## 1. 运行时反射 + +什么是运行时反射呢？就是指在程序运行时，给定某个类型或某些对象的实例，反射可以做到： + +- 解析包括泛型在内的各种对象的类型 +- 能去实例化一个对象 +- 能去访问或调用对象中的成员 + +针对上面描述，下文中我们分别举例说明。 + +### 1.1 举例说明 + +#### 1.1.1 解析运行时的类型 (包括运行时的泛型) + +和其它的JVM系语言一样，Scala的类型在编译阶段会进行类型擦除（比如泛型信息擦除）。 +这意味着如果想解析某个实例运行时类型，那些Scala编译器在编译阶段所产生的全部类型信息则不一定能访问到了。 + +`类型标签(TypeTag)`可以理解为将编译时的类型信息全部带到运行时的一个对象。 +不过需要注意的是，一般`类型标签`都是由编译器生成。 +有隐式参数或`类型标签`与上下文绑定时被用到了，都会触发编译器生成类型标签。 +这意味着通常只能在用隐式参数或上下文绑定的地方获得`类型标签`。 + +举个上下文边界的例子： + +```scala +scala> import scala.reflect.runtime.{universe => ru} +import scala.reflect.runtime.{universe=>ru} + +scala> val l = List(1,2,3) +l: List[Int] = List(1, 2, 3) + +scala> def getTypeTag[T: ru.TypeTag](obj: T) = ru.typeTag[T] +getTypeTag: [T](obj: T)(implicit evidence$1: reflect.runtime.universe.TypeTag[T])reflect.runtime.universe.TypeTag[T] + +scala> val theType = getTypeTag(l).tpe +theType: ru.Type = List[Int] +``` + +在上面的例子中，我们首先引入了`scala.reflect.runtime.universe`（通常用这个包就是想用`类型标签`），接着我们创建了一个`List[Int]`叫`l`。然后我们定义了一个`getTypeTag`方法，其中包含类型参数`T`。这个`T`就是一个上下文绑定的参数。（如REPL中所示，这个`T`等同于同时定义了一个隐式声明的`evidence`，以此为据让编译器为`T`生成一个`类型标签`）。最终我们用`l`作为参数传入该方法，然后调用`tpe`返回了`类型标签`所包含的类型。 +最终我们获得了一个正确完整的类型（包含List的具体类型参数）—— `List[Int]`。 + +一旦我们获得了所需的`类型`实例，我们就可以将它解析出来，例如： + +```scala +scala> val decls = theType.decls.take(10) +decls: Iterable[ru.Symbol] = List(constructor List, method companion, method isEmpty, method head, method tail, method ::, method :::, method reverse_:::, method mapConserve, method ++) +``` + +#### 1.1.2 运行时实例化一个类型 + +通过反射获得的类型，可以通过使用适当的“调用器”镜像调用它们的构造函数来实例化（镜像`mirrors`的概念在[后续文档中说明](https://docs.scala-lang.org/overviews/reflection/overview.html#mirrors)）。 +让我们通过一个REPL的示例说明： + + +```scala +scala> case class Person(name: String) +defined class Person + +scala> val m = ru.runtimeMirror(getClass.getClassLoader) +m: scala.reflect.runtime.universe.Mirror = JavaMirror with ... +``` + +第一步我们获得一个镜像`m`，包括`Person`类在内的所有类和类型都被加载到当前的`classloader`。 + +```scala +scala> val classPerson = ru.typeOf[Person].typeSymbol.asClass +classPerson: scala.reflect.runtime.universe.ClassSymbol = class Person + +scala> val cm = m.reflectClass(classPerson) +cm: scala.reflect.runtime.universe.ClassMirror = class mirror for Person (bound to null) +``` + +第二步针对`Person`类使用`reflectClass`方法获得一个`ClassMirror`。 +`ClassMirror`提供了访问`class Person`构造器的能力。 + +```scala +scala> val ctor = ru.typeOf[Person].decl(ru.termNames.CONSTRUCTOR).asMethod +ctor: scala.reflect.runtime.universe.MethodSymbol = constructor Person +``` + +`Person`构造器方法的标识(`MethodSymbol`)只能在 `runtime universe`的`ru`中使用`Person`类型的声明获取. + +```scala +scala> val ctorm = cm.reflectConstructor(ctor) +ctorm: scala.reflect.runtime.universe.MethodMirror = constructor mirror for Person.(name: String): Person (bound to null) + +scala> val p = ctorm("Mike") +p: Any = Person(Mike) +``` + +#### 1.1.3 访问和调用运行时类型的成员 + +通常，想访问运行时类型的成员主要是用到”调用器“类似的`镜像`的方式。 +让我们通过一个REPL的示例说明： + +```scala +scala> case class Purchase(name: String, orderNumber: Int, var shipped: Boolean) +defined class Purchase + +scala> val p = Purchase("Jeff Lebowski", 23819, false) +p: Purchase = Purchase(Jeff Lebowski,23819,false) +``` + +本例中，我们将尝试反射的方式获取并设置`Purchase p`中的`shipped`字段。 + +```scala +scala> import scala.reflect.runtime.{universe => ru} +import scala.reflect.runtime.{universe=>ru} + +scala> val m = ru.runtimeMirror(p.getClass.getClassLoader) +m: scala.reflect.runtime.universe.Mirror = JavaMirror with ... +``` + +同上面示例一样，我们先获取一个镜像`m`，用于在`classloader`内加装好所有的类和类型，其中包含`p (Purchase)`类，我们用`m`去访问其成员`shipped`。 + +```scala +scala> val shippingTermSymb = ru.typeOf[Purchase].decl(ru.TermName("shipped")).asTerm +shippingTermSymb: scala.reflect.runtime.universe.TermSymbol = method shipped +``` + +通过`TermSymbol`(一种`Symbol`符号类型)去查询`shipped`字段声明。 +稍后，我们将需要使用此`Symbol`获取一个镜像，该镜像使我们可以访问所指向实例中字段的值。 + +```scala +scala> val im = m.reflect(p) +im: scala.reflect.runtime.universe.InstanceMirror = instance mirror for Purchase(Jeff Lebowski,23819,false) + +scala> val shippingFieldMirror = im.reflectField(shippingTermSymb) +shippingFieldMirror: scala.reflect.runtime.universe.FieldMirror = field mirror for Purchase.shipped (bound to Purchase(Jeff Lebowski,23819,false)) +``` + +上面这段代码中，`p`的实例镜像`im`是为了访问该实例中成员`shipped`的所要用到的反射镜像。 +通过实例镜像，我们可以将表示`p`类型字段声明的意思的`TermSymbol`对应到`FieldMirror`。 + +`FieldMirror`就是代表着当前我们指定的想反射操作的字段，我们可以使用`get`和`set`方法去获取/设置对应实例里的`shipped`成员。 +此处先将`shipped`的状态设置为`true`。 + +```scala +scala> shippingFieldMirror.get +res7: Any = false + +scala> shippingFieldMirror.set(true) + +scala> shippingFieldMirror.get +res9: Any = true +``` + +### 1.2 对比Java运行时类和Scala运行时类型 + +如果你已经熟悉Java中反射运行中的类实例，或许已经注意到我们在Scala中使用运行时类型做为相应的替代品。 + +下面REPL示例了一种非常简单的使用场景，使用Java去反射Scala类可能会返回奇怪的结果。 + +首先，我们定义了一个带着抽象类型`T`的`E`类。然后又有两个继承了E的子类`C`和`D`。 + +```scala +scala> class E { + | type T + | val x: Option[T] = None + | } +defined class E + +scala> class C extends E +defined class C + +scala> class D extends C +defined class D +``` + +然后，分别创建`C`和`D`的实例，同时指给成员`T`具体类型，均声明为`String`。 + +```scala +scala> val c = new C { type T = String } +c: C{type T = String} = $anon$1@7113bc51 + +scala> val d = new D { type T = String } +d: D{type T = String} = $anon$1@46364879 +``` + +现在我们用Java的反射方法`getClass`和`isAssignableFrom`去获取代表`c`和`d`运行时类的`java.lang.Class`实例， +然后去测试看看`d`的运行时类是不是一个`c`的运行时类的子类形式存在。 + +```scala +scala> c.getClass.isAssignableFrom(d.getClass) +res6: Boolean = false +``` + +我们明明看到`D`是继承于`C`的，但是执行结果有些意外。 +在尝试执行如此简单的运行时类型解析过程中，对于”d是否为c的子类“这一问题本来默认预期是得到`true`。 +然而如你所见，当`c`和`d`实例化后Scala编译器实际上分别为它们创建了各自的匿名子类。 + +事实上，Scala编译器需要将Scala特有的语言功能转译成同功能的Java字节码才能上JVM去执行。 +因此，Scala编译器经常会创建运行时使用的合成类（比如自动生产类）来代替用户自定义类。 +在使用Java反射功能与Scala一些功能结合时候经常会发生这种自动合成的情况，比如闭包、类型成员、类型优化，局部类等。 + +为了避开上述情况，我们改用Scala反射去获取Scala对象在运行时的精确的类型信息。 +这样的话就可以做到让Scala运行时类携带着编译阶段的所有类型，避免了编译时和运行时的类型不匹配问题。 + +接下来我们定义了一个使用Scala反射方式的方法去判断两个运行时类型的关系，检查他们之间是否是子类型的关系。 +如果第一个参数的类型是第二个参数的子类型，那就返回`true`： + +```scala +scala> import scala.reflect.runtime.{universe => ru} +import scala.reflect.runtime.{universe=>ru} + +scala> def m[T: ru.TypeTag, S: ru.TypeTag](x: T, y: S): Boolean = { + | val leftTag = ru.typeTag[T] + | val rightTag = ru.typeTag[S] + | leftTag.tpe <:< rightTag.tpe + | } +m: [T, S](x: T, y: S)(implicit evidence$1: scala.reflect.runtime.universe.TypeTag[T], implicit evidence$2: scala.reflect.runtime.universe.TypeTag[S])Boolean + +scala> m(d, c) +res9: Boolean = true +``` + +`d`的运行时类型确实是`c`的运行时类型的子类型，符合预期。 + +## 2. 编译阶段反射 + +Scala反射实现了允许在编译阶段就对程序进行修改的一种元编程形式。 +编译阶段反射通过宏的形式实现，宏提供了在编译时候对抽象语法数修改的能力。 + +一个比较有趣的地方是，宏和Scala运行时反射都是通过包`scala.reflect.api`用相同的API实现。 +这样就可以用同一套代码去实现宏和运行时反射。 + +需要注意的是[关于宏的指南](https://docs.scala-lang.org/overviews/macros/overview.html)中侧重于讲解其特性。本文档侧重于反射API方面。本文档中针对宏与反射相关概念有所直述，比如在抽象语法树部分有许多关于[Symbols, Trees, and Types](https://docs.scala-lang.org/overviews/reflection/symbols-trees-types.html)的概念有细讲。 + +## 3. 反射环境 + +所有的反射任务都需要设置一个相应的反射环境。 +这个反射环境根据是在运行时环境完成反射任务还是在编译时环境完成反射任务而有所区别。 +这个区别被封装于所谓的`universe`中。 +反射环境的另一个重要方面就是我们可以访问想反射的那组实体， +这组实体由所谓的镜像`mirrors`去确定。 + +镜像不仅决定反射化操作有哪些实体要被访问到，而且它还提供了反射操作去执行那些实体。 +比如在运行时反射过程中可以调用镜像去操作类中一个方法或构造器。 + +### 3.1 Universes + +`Universe`是Scala反射的切入点。 + +`universe`提供了使用反射所关联的很多核心概念，比如`Types`，`Trees`，以及`Annotations`。 +更多细节请参阅指南中[Universes](https://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html)部分，或者看`scala.reflect.api`包的[Universes API文档](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Universe.html)。 + +本指南中提供了大多数情况下Scala反射要用到的部分，一般在使用运行时反射的场景下，直接导入所有`universe`成员去用即可： + +```scala +import scala.reflect.runtime.universe._ +``` + +### 3.2 Mirrors + +`Mirrors`(镜像) 是Scala反射中的核心概念。 +反射所能提供的信息都是通过镜像去访问的。 +根据不同的类型信息或不同的反射操作，必须要使用不同类型的镜像。 + +更多细节请参阅指南中[Mirrors](https://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html)部分，或者看`scala.reflect.api`包的[Mirrors API文档](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Mirrors.html)。 diff --git a/_zh-cn/overviews/reflection/thread-safety.md b/_zh-cn/overviews/reflection/thread-safety.md new file mode 100644 index 0000000000..e601c8e7e8 --- /dev/null +++ b/_zh-cn/overviews/reflection/thread-safety.md @@ -0,0 +1,47 @@ +--- +layout: multipage-overview +title: 线程安全 +partof: reflection +overview-name: Reflection + +num: 6 +language: zh-cn +--- + +EXPERIMENTAL + +**Eugene Burmako** + +遗憾的是，在scala2.10.0发布的现行状态下，反射不是线程安全的。 +这里有个JIRA问题 [SI-6240](https://issues.scala-lang.org/browse/SI-6240)，它可以用来跟踪我们的进度和查找技术细节，下面是最新技术的简要总结。 + +

            NEWThread safety issues have been fixed in Scala 2.11.0-RC1, but we are going to keep this document available for now, since the problem still remains in the Scala 2.10.x series, and we currently don't have concrete plans on when the fix is going to be backported.

            + +目前，在反射相关方面存在两种竞争状态。 第一是反射的初始化（当调用代码首次访问`scala.reflect.runtime.universe`时）无法从多个线程安全地调用。第二是符号的初始化（当调用代码第一次访问符号的标记或类型签名时）也不安全。 +这是一个典型的表现： + + java.lang.NullPointerException: + at s.r.i.Types$TypeRef.computeHashCode(Types.scala:2332) + at s.r.i.Types$UniqueType.(Types.scala:1274) + at s.r.i.Types$TypeRef.(Types.scala:2315) + at s.r.i.Types$NoArgsTypeRef.(Types.scala:2107) + at s.r.i.Types$ModuleTypeRef.(Types.scala:2078) + at s.r.i.Types$PackageTypeRef.(Types.scala:2095) + at s.r.i.Types$TypeRef$.apply(Types.scala:2516) + at s.r.i.Types$class.typeRef(Types.scala:3577) + at s.r.i.SymbolTable.typeRef(SymbolTable.scala:13) + at s.r.i.Symbols$TypeSymbol.newTypeRef(Symbols.scala:2754) + +好消息是，编译时反射（通过`scala.reflect.macros.Context`暴露给宏的那一种）比运行时反射（通过`scala.reflect.runtime.universe`暴露出的那一种）更不容易受到线程问题的影响。 +第一个原因是，当宏有机会运行时，编译时反射`universe`已经初始化，这规避了我们的竞争条件1。第二个理由是至今为止没有编译程序本身就是线程安全，所以没有并行执行的工具。但是，如果您的宏产生了多个线程，则你仍应该小心。 + + +不过，对于运行时反射来说，情况要糟糕得多。首次初始化`scala.reflect.runtime.universe`时，称为反射初始化，而且这种初始化可以间接发生。 +此处最突出的示例是，调用带有`TypeTag`上下文边界的方法可能会带来问题，因为调用这种方法，Scala通常需要构造一个自动生成的类型标签，该标签需要创建一个类型，并需要初始化反射`universe`。 +这个结果是，如果不采取特殊措施，就无法在测试中可靠地调用基于`TypeTag`的方法，这是因为sbt等很多工具并行执行测试。 + +汇总： +* 如果您正在编写一个没有显式创建线程的宏那就没有问题。 +* 线程或参与者（actors）混在一起的运行时反射可能很危险。 +* 多个带有`TypeTag`上下文边界的线程调用方法可能导致不确定的结果。 +* 请查看 [SI-6240](https://issues.scala-lang.org/browse/SI-6240)，以了解我们在此问题上的进展。 diff --git a/_zh-cn/overviews/reflection/typetags-manifests.md b/_zh-cn/overviews/reflection/typetags-manifests.md new file mode 100644 index 0000000000..ab3f5d448c --- /dev/null +++ b/_zh-cn/overviews/reflection/typetags-manifests.md @@ -0,0 +1,132 @@ +--- +layout: multipage-overview +title: TypeTags 和 Manifests +partof: reflection +overview-name: Reflection + +num: 5 +language: zh-cn +--- + +与其他JVM语言一样，Scala的类型在运行时被擦除。这意味着，如果要检查某个实例的运行时类型，则可能无法访问Scala编译器在编译时可用的所有类型信息。 + +如`scala.reflect.Manifest`，`TypeTags`可以看作是将编译时可用的所有类型信息携带到运行时的对象。 +例如，`TypeTag[T]`封装了某个编译时类型`T`的运行时类型表示。但是请注意，`TypeTag`应该被认为是对2.10之前的`Manifest`概念的更丰富的替代品，后者还与Scala反射完全集成。 + +有三种不同类型的类型标记： + +1. `scala.reflect.api.TypeTags#TypeTag`。 +Scala类型的完整类型描述符。例如，`TypeTag[List[String]]`包含所有类型信息，在本例中是类型`scala.List[String]`。 + +2. `scala.reflect.ClassTag`。 +Scala类型的部分类型描述符。例如，`ClassTag[List[String]]`只包含已擦除、关于类的类型信息，在本例中为`scala.collection.immutable.List`。`ClassTag`只提供对类型的运行时类的访问。其类似于`scala.reflect.ClassManifest`。 + +3. `scala.reflect.api.TypeTags#WeakTypeTag`。 +抽象类型的类型描述符（参见下面相应的小节）。 + +## 获取`TypeTag` + +与`Manifest`类似，`TypeTag`总是由编译器生成，可以通过三种方式获得。 + +### 通过方法`typeTag`、`classTag`或`weakTypeTag` + +通过使用通过`Universe`提供的方法`typeTag`，就可以直接获得特定类型的`TypeTag`。 + +例如，要获取表示`Int`的`TypeTag`，我们可以执行以下操作： + + import scala.reflect.runtime.universe._ + val tt = typeTag[Int] + +或者类似地，要获得表示`String`的`ClassTag`，我们可以执行以下操作： + + import scala.reflect._ + val ct = classTag[String] + +这些方法中的每个方法都为给定的类型参数`T`构造一个`TypeTag[T]`或`ClassTag[T]`。 + +### 使用类型为`TypeTag[T]`、`ClassTag[T]`或`WeakTypeTag[T]`的隐式参数 + +与`Manifest`一样，实际上可以 _请求_ 编译器生成`TypeTag`。这只需指定一个类型为`TypeTag[T]`的隐式 _证据_ 参数即可完成。如果编译器在隐式搜索期间找不到匹配的隐式值，它将自动生成一个`TypeTag[T]`。 + +_注意_：这通常是通过在方法上使用隐式参数来实现的，并且只能在类上。 + +例如，我们可以编写一个方法，它可以接受任意对象，并且使用`TypeTag`打印有关该对象的类型参数的信息： + + import scala.reflect.runtime.universe._ + + def paramInfo[T](x: T)(implicit tag: TypeTag[T]): Unit = { + val targs = tag.tpe match { case TypeRef(_, _, args) => args } + println(s"type of $x has type arguments $targs") + } + +这里，我们在`T`上编写了一个参数化的泛型方法`paramInfo`，并提供了一个隐式参数`(implicit tag: TypeTag[T])`。 +那我们就可以使用`TypeTag`的方法`tpe`直接访问`tag`表示的类型（`type`类型）。 + +然后，我们可以使用方法`paramInfo`，如下所示： + + scala> paramInfo(42) + type of 42 has type arguments List() + + scala> paramInfo(List(1, 2)) + type of List(1, 2) has type arguments List(Int) + +### 使用类型参数的上下文绑定 + +要实现与上述完全相同的效果，一种不太冗长的方法是在类型参数上使用上下文绑定。不需要提供单独的隐式参数，只需在类型参数列表中包含`TypeTag`，如下所示： + + def myMethod[T: TypeTag] = ... + +给定上下文绑定的`[T: TypeTag]`，编译器只需生成类型为`TypeTag[T]`的隐式参数，这将重写方法以进行查找，就像上一节中使用隐式参数的示例一样。 + +上面重写为使用上下文边界的示例如下： + + + import scala.reflect.runtime.universe._ + + def paramInfo[T: TypeTag](x: T): Unit = { + val targs = typeOf[T] match { case TypeRef(_, _, args) => args } + println(s"type of $x has type arguments $targs") + } + + scala> paramInfo(42) + type of 42 has type arguments List() + + scala> paramInfo(List(1, 2)) + type of List(1, 2) has type arguments List(Int) + +## WeakTypeTags + +`WeakTypeTag[T]`泛化了`TypeTag`（意思是`TypeTag`是继承自`WeakTypeTag`的），`WeakTypeTag`与普通的`TypeTag`不同， + +其类型表示的组件可以是对类型参数或抽象类型的引用。但是，`WeakTypeTag[T]`试图尽可能的具体（意思是如果都存在则优先更加具体的类型(参数)），也就是说，如果类型标记可用于被引用的类型参数或抽象类型，则它们用于将具体类型嵌入到`WeakTypeTag[T]`中。 + +继续上面的例子： + + def weakParamInfo[T](x: T)(implicit tag: WeakTypeTag[T]): Unit = { + val targs = tag.tpe match { case TypeRef(_, _, args) => args } + println(s"type of $x has type arguments $targs") + } + + scala> def foo[T] = weakParamInfo(List[T]()) + foo: [T]=> Unit + + scala> foo[Int] + type of List() has type arguments List(T) + +## TypeTags and Manifests + +`TypeTag`可以大致对应2.10之前的`scala.reflect.Manifest`、 虽然`scala.reflect.ClassTag`对应于`scala.reflect.ClassManifest`而`scala.reflect.api.TypeTags#TypeTag`主要对应于`scala.reflect.Manifest`，但其他2.10版之前的`Manifest`类型与2.10版的`Tag`类型没有直接对应关系。 + +- **不支持scala.reflect.OptManifest。** +这是因为`Tag`可以具体化任意类型，所以它们总是可用的。 + +- **没有对应的scala.reflect.AnyValManifest。** +取而代之的是，可以将其`Tag`与基本`Tag`之一（在相应的伴随对象中定义）进行比较，以找出其是否代表原始值类。此外，可以简单地使用`.tpe.typeSymbol.isPrimitiveValueClass`。 + +- **无法替换Manifest伴随对象中定义的工厂方法。** +取而代之的是，可以使用Java（用于类）和Scala（用于类型）提供的反射API生成相应的类型。 + +- **不支持某些manifest操作（即`<:<`, `>:>`和`typeArguments`）。** +取而代之的是，可以使用Java（用于类）和Scala（用于类型）提供的反射API。 + +在Scala 2.10中，不建议使用`scala.reflect.ClassManifest`，而推荐使用`TypeTag`和`ClassTag`，并且计划在即将发布的版本中弃用`scala.reflect.Manifest`。因此，建议迁移任何基于`Manifest`的API以使用`Tag`。 diff --git a/_zh-cn/overviews/scala-book/introduction.md b/_zh-cn/overviews/scala-book/introduction.md new file mode 100644 index 0000000000..a456d618e2 --- /dev/null +++ b/_zh-cn/overviews/scala-book/introduction.md @@ -0,0 +1,24 @@ +--- +layout: multipage-overview +title: 摘要 +description: Scala之书摘要 +partof: scala_book +overview-name: Scala Book +num: 1 +outof: 54 +language: zh-cn +--- + +Scala之书的内容提供了对Scala编程语言的一个简要的介绍与概览。本书并未拘泥于正体文风，而是由50多个小课程构成。每一课都都有足够的篇幅让读者了解到课程涉及的语言特性，同时每一课也都足够精简干练，让读者可以在15分钟以内看完。 + +在开始本次旅程之前，需要注意： + +- 在编程风格上，大部分Scala用户以2个空格缩进他们的代码，但是本书使用4个空格，因为我们认为这样能够带来更好的阅读体验，尤其是在“书”这种形式中。 + +点击链接 “下一页（next）”或直接在目录中选择”序言：Scala之味“开始本书之旅。 + + + + + + diff --git a/_zh-cn/overviews/scala3-book/ca-context-bounds.md b/_zh-cn/overviews/scala3-book/ca-context-bounds.md new file mode 100644 index 0000000000..9e9c84238c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-context-bounds.md @@ -0,0 +1,114 @@ +--- +title: 上下文绑定 +type: section +description: This page demonstrates Context Bounds in Scala 3. +language: zh-cn +num: 62 +previous-page: ca-context-parameters +next-page: ca-given-imports + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在许多情况下，[上下文参数]({% link _overviews/scala3-book/ca-context-parameters.md %}#context-parameters) 的名称不必显式提及，因为它仅在编译器为其他上下文参数合成实参的时候用到。 +在这种情况下，您不必定义参数名称，只需提供参数类型即可。 + +## 背景 + +例如，假设一个 `maxElement` 方法返回一个集合里的最大值： + +{% tabs context-bounds-max-named-param class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def maxElement[A](as: List[A])(implicit ord: Ord[A]): A = + as.reduceLeft(max(_, _)(ord)) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def maxElement[A](as: List[A])(using ord: Ord[A]): A = + as.reduceLeft(max(_, _)(using ord)) +``` +{% endtab %} +{% endtabs %} + +上面这个 `maxElement` 方法只接受一个类型为 `Ord[A]` 的 _上下文参数_ 并将其作为实参传给 `max` 方法。 + +完整起见，以下是 `max` 和 `Ord` 的定义（注意，在实践中我们会使用 `List` 中已有的 `max` 方法 ， +但我们为了说明目的而编造了这个例子）： + +{% tabs context-bounds-max-ord class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +/** Defines how to compare values of type `A` */ +trait Ord[A] { + def greaterThan(a1: A, a2: A): Boolean +} + +/** Returns the maximum of two values */ +def max[A](a1: A, a2: A)(implicit ord: Ord[A]): A = + if (ord.greaterThan(a1, a2)) a1 else a2 +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +/** Defines how to compare values of type `A` */ +trait Ord[A]: + def greaterThan(a1: A, a2: A): Boolean + +/** Returns the maximum of two values */ +def max[A](a1: A, a2: A)(using ord: Ord[A]): A = + if ord.greaterThan(a1, a2) then a1 else a2 +``` +{% endtab %} +{% endtabs %} + +`max` 方法用了类型为 `Ord[A]` 的上下文参数, 就像 `maxElement` 方法一样。 + +## 省略上下文参数 + +因为 `ord` 是 `max` 方法的上下文参数，当我们调用方法 `max` 时， 编译器可以在 `maxElement` 的实现中为我们提供它： + +{% tabs context-bounds-context class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def maxElement[A](as: List[A])(implicit ord: Ord[A]): A = + as.reduceLeft(max(_, _)) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def maxElement[A](as: List[A])(using Ord[A]): A = + as.reduceLeft(max(_, _)) +``` + +注意，因为我们不用显示传递给 `max` 方法，我们可以在 `maxElement` 定义里不命名。 +这是 _匿名上下文参数_ 。 +{% endtab %} +{% endtabs %} + +## 上下文绑定 + +鉴于此背景，_上下文绑定_ 是一种简写语法，用于表达“依赖于类型参数的上下文参数”模式。 + +使用上下文绑定，`maxElement` 方法可以这样写： + +{% tabs context-bounds-max-rewritten %} +{% tab 'Scala 2 and 3' %} +```scala +def maxElement[A: Ord](as: List[A]): A = + as.reduceLeft(max(_, _)) +``` +{% endtab %} +{% endtabs %} + +方法或类的类型参数 `A`，有类似 `:Ord` 的绑定，它表示有 `Ord[A]` 的上下文参数。 +在后台，编译器将此语法转换为“背景”部分中显示的语法。 + +有关上下文绑定的更多信息，请参阅 Scala 常见问题解答的 [“什么是上下文绑定？”](https://docs.scala-lang.org/tutorials/FAQ/context-bounds.html) 部分。 diff --git a/_zh-cn/overviews/scala3-book/ca-context-parameters.md b/_zh-cn/overviews/scala3-book/ca-context-parameters.md new file mode 100644 index 0000000000..3742d36de1 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-context-parameters.md @@ -0,0 +1,152 @@ +--- +title: Given 实例和 Using 语句 +type: section +description: This page demonstrates how to use 'given' instances and 'using' clauses in Scala 3. +language: zh-cn +num: 61 +previous-page: ca-extension-methods +next-page: ca-context-bounds + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +
            使用上下文抽象仅限Scala 3
            + +Scala 3 提供了两个重要的上下文抽象特性： + +- **Using 语句** 允许你指定参数，这些参数程序员可以在调用时省略，这些参数由上下文自动提供。 +- **Given 实例** 让您定义 Scala 编译器可以用来填充缺失参数的术语。 + +## Using 语句 + +在设计系统时，通常需要向系统的不同组件提供上下文信息，如_配置_或设置。 +实现此目的的一种常见方法是将配置作为附加参数传递给您的方法。 + +在下面的示例中，我们定义了一个样例类 `Config` 来模拟一些网站配置并在不同的方法中传递它。 + +{% tabs nonusing %} +{% tab 'Scala 2 and 3' %} + +```scala +case class Config(port: Int, baseUrl: String) + +def renderWebsite(path: String, c: Config): String = + "" + renderWidget(List("cart"), c) + "" + +def renderWidget(items: List[String], c: Config): String = ??? + +val config = Config(8080, "docs.scala-lang.org") +renderWebsite("/home", config) +``` + +{% endtab %} +{% endtabs %} + +让我们假设配置在我们的大部分代码库中都没有改变。 +将 `c` 传递给每个方法调用（如 `renderWidget`）变得非常乏味并且使我们的程序更难阅读，因为我们需要忽略 `c` 参数。 + +#### 使用 `using` 将参数标记为上下文 + +在 Scala 3 中，我们可以将方法的一些参数标记为_上下文_。 + +{% tabs using1 %} +{% tab 'Scala 3 Only' %} + +```scala +def renderWebsite(path: String)(using c: Config): String = + "" + renderWidget(List("cart")) + "" + // ^^^ + // no argument c required anymore + +def renderWidget(items: List[String])(using c: Config): String = ??? +``` + +{% endtab %} +{% endtabs %} + +通过使用关键字 `using` 开始参数部分，我们告诉 Scala 编译器它应该在调用处自动找到具有正确类型的参数。 +因此，Scala 编译器执行**术语推断**。 + +在我们对 `renderWidget(List("cart"))` 的调用中，Scala 编译器将看到作用域（`c`）中有一个类型为 `Config` 的术语，并自动将其提供给 `renderWidget`。 +所以程序等同于上面的程序。 + +事实上，由于我们不再需要在 `renderWebsite` 的实现中引用 `c`，我们甚至可以在签名中省略它的名字： + +{% tabs using2 %} +{% tab 'Scala 3 Only' %} + +```scala +// no need to come up with a parameter name +// vvvvvvvvvvvvv +def renderWebsite(path: String)(using Config): String = + "" + renderWidget(List("cart")) + "" +``` + +{% endtab %} +{% endtabs %} + +#### 明确提供上下文参数 + +我们已经了解了如何_抽象_上下文参数，并且 Scala 编译器可以自动为我们提供参数。 +但是我们如何指定调用 `renderWebsite` 时使用的配置呢？ + +就像我们使用 `using` 指定参数部分一样，我们也可以使用 `using` 显式提供上下文参数： + +{% tabs using3 %} +{% tab 'Scala 3 Only' %} + +```scala +renderWebsite("/home")(using config) +``` + +{% endtab %} +{% endtabs %} + +如果我们在范围内有多个有意义的不同值，并且我们希望确保将正确的值传递给函数，则显式提供上下文参数可能很有用。 + +对于所有其他情况，正如我们将在下一节中看到的，还有另一种方法可以将上下文值引入范围。 + +## Give 实例 + +我们已经看到，我们可以通过使用 `using` 标记 _调用_的参数部分来显式地将参数作为上下文参数传递。 +但是，如果某个特定类型有一个_单一的规范值_，则还有另一种首选方法可以使其对 Scala 编译器可用：将其标记为 `given`。 + +{% tabs given1 %} +{% tab 'Scala 3 Only' %} + +```scala +val config = Config(8080, "docs.scala-lang.org") +// this is the type that we want to provide the +// canonical value for +// vvvvvv +given Config = config +// ^^^^^^ +// this is the value the Scala compiler will infer +// as argument to contextual parameters of type Config +``` + +{% endtab %} +{% endtabs %} + +在上面的示例中，我们指定每当在当前范围内省略 `Config` 类型的上下文参数时，编译器应该将 `config` 推断为参数。 + +为 `Config` 定义了 given，我们可以简单地调用 `renderWebsite`： + +{% tabs given2 %} +{% tab 'Scala 3 Only' %} + +```scala +renderWebsite("/home") +// ^^^^^ +// again no argument +``` + +{% endtab %} +{% endtabs %} + +[reference]: {{ site.scala3ref }}/overview.html +[blog-post]: /2020/11/06/explicit-term-inference-in-scala-3.html diff --git a/_zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md b/_zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md new file mode 100644 index 0000000000..4b6a82db3b --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md @@ -0,0 +1,88 @@ +--- +title: 上下文抽象 +type: chapter +description: This chapter provides an introduction to the Scala 3 concept of Contextual Abstractions. +language: zh-cn +num: 59 +previous-page: types-others +next-page: ca-extension-methods + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +## 背景 + +隐式是Scala 2中的一个主要的设计特色。隐式是进行上下文抽象的基本方式。它们代表了具有多种用例的统一范式，其中包括： + +- 实现类型类 +- 建立上下文 +- 依赖注入 +- 表达能力 +- 计算新类型，并证明它们之间的关系 + +此后，其他语言也纷纷效仿，例如 Rust 的 traits 或 Swift 的协议扩展。对于编译期的依赖解析方案，Kotlin 的设计方案也被提上日程，而对 C# 而言是 Shapes 和 Extensions 或对 F# 来说是 Traits。Implicits 也是 Coq 或 Agda 等定理证明器的共同特色。 + +尽管这些设计使用不同的术语，但它们都是*术语推理*核心思想的变体： +给定一个类型，编译器会合成一个具有该类型的“canonical”术语。 + +## 重新设计 + +Scala 3 重新设计了 Scala 中的上下文抽象。 +虽然这些概念是在 Scala 2 中逐渐“发现”的，但它们现在已广为人知和理解，并且重新设计利用了这些知识。 + +Scala 3 的设计侧重于 **意图** 而不是 **机制**。 +Scala 3 没有提供一个非常强大的隐式特性，而是提供了几个面向用例的特性： + +- **抽象上下文信息**。 + [使用子句][givens] 允许程序员对调用上下文中可用的信息进行抽象，并且应该隐式传递。 + 作为对 Scala 2 隐式的改进，可以按类型指定 using 子句，从而将函数签名从从未显式引用的术语变量名称中释放出来。 + +- **提供类型类实例**。 + [给定实例][type-classes]允许程序员定义某种类型的_规范值(canonical value)_。 + 这使得使用类型类的编程更加简单，而不会泄露实现细节。 + +- **追溯扩展类**。 + 在 Scala 2 中，扩展方法必须使用隐式转换或隐式类进行编码。 + 相比之下，在 Scala 3 [扩展方法][extension-methods] 现在直接内置到语言中，产生了更好的错误消息和改进的类型推断。 + +- **将一种类型视为另一种类型**。 + 隐式转换已从头开始[重新设计][implicit-conversions]，作为类型类 `Conversion` 的实例。 + +- **高阶上下文抽象**。 + [上下文函数][contextual-functions] 的_全新_特性使上下文抽象成为一等公民。 + 它们是库作者的重要工具，可以表达简洁的领域特定语言。 + +- **来自编译器的可操作反馈**。 + 如果编译器无法解析隐式参数，它现在会为您提供 [导入建议](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html) 来解决问题。 + +## 好处 + +Scala 3 中的这些更改实现了术语推理与语言其余部分的更好分离： + +- 仅有一种定义 given 的方法 +- 仅有一种方法可以引入隐式参数和自变量 +- [导入 givens][given-imports] 仅有一种单独的方法，不允许它们隐藏在正常导入的海洋中 +- 定义 [隐式转换][implicit-conversions] 的方法仅有一种，它被清楚地标记为这样，并且不需要特殊的语法 + +这些变化的好处包括： + +- 新设计避免了特性交织，从而使语言更加一致 +- 它使隐式更容易学习和更难滥用 +- 它极大地提高了 95% 使用隐式的 Scala 程序的清晰度 +- 它有可能以一种易于理解和友好的原则方式进行术语推理 + +本章将在以下各节中介绍其中的许多新功能。 + + +[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %} +[given-imports]: {% link _zh-cn/overviews/scala3-book/ca-given-imports.md %} +[implicit-conversions]: {% link _zh-cn/overviews/scala3-book/ca-implicit-conversions.md %} +[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +[context-bounds]: {% link _zh-cn/overviews/scala3-book/ca-context-bounds.md %} +[type-classes]: {% link _zh-cn/overviews/scala3-book/ca-type-classes.md %} +[equality]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} +[contextual-functions]: {% link _zh-cn/overviews/scala3-book/types-dependent-function.md %} diff --git a/_zh-cn/overviews/scala3-book/ca-extension-methods.md b/_zh-cn/overviews/scala3-book/ca-extension-methods.md new file mode 100644 index 0000000000..be1237733b --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-extension-methods.md @@ -0,0 +1,127 @@ +--- +title: 扩展方法 +type: section +description: This page demonstrates how Extension Methods work in Scala 3. +language: zh-cn +num: 60 +previous-page: ca-contextual-abstractions-intro +next-page: ca-context-parameters + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +在 Scala 2 中，用 [implicit classes]({% link _overviews/core/implicit-classes.md %}) 可以得到类似的结果。 + +--- + +扩展方法允许您在定义类型后向类型添加方法，即它们允许您向封闭类添加新方法。 +例如，假设其他人创建了一个 `Circle` 类： + +{% tabs ext1 %} +{% tab 'Scala 2 and 3' %} +```scala +case class Circle(x: Double, y: Double, radius: Double) +``` +{% endtab %} +{% endtabs %} + +现在想象一下，你需要一个 `circumference` 方法，但是你不能修改它们的源代码。 +在将术语推理的概念引入编程语言之前，您唯一能做的就是在单独的类或对象中编写一个方法，如下所示： + +{% tabs ext2 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object CircleHelpers { + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object CircleHelpers: + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +``` +{% endtab %} +{% endtabs %} + +你可以像这样用该方法： + +{% tabs ext3 %} +{% tab 'Scala 2 and 3' %} +```scala +val aCircle = Circle(2, 3, 5) + +// without extension methods +CircleHelpers.circumference(aCircle) +``` +{% endtab %} +{% endtabs %} + +但是使用扩展方法，您可以创建一个 `circumference` 方法来处理 `Circle` 实例： + +{% tabs ext4 %} +{% tab 'Scala 3 Only' %} +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 +``` +{% endtab %} +{% endtabs %} + +在这段代码中： + +- 扩展方法 `circumference` 将添加到 `Circle` 类型里 +- `c: Circle` 语法允许您在扩展方法中引用变量 `c` + +然后在您的代码中使用 `circumference`，就像它最初是在 `Circle` 类中定义的一样： + +{% tabs ext5 %} +{% tab 'Scala 3 Only' %} +```scala +aCircle.circumference +``` +{% endtab %} +{% endtabs %} + +### 导入扩展方法 + +想象一下，`circumference` 定义在`lib` 包中，你可以通过以下方式导入它 + +{% tabs ext6 %} +{% tab 'Scala 3 Only' %} +```scala +import lib.circumference + +aCircle.circumference +``` +{% endtab %} +{% endtabs %} + +如果缺少导入，编译器还会通过显示详细的编译错误消息来支持您，如下所示： + +```text +value circumference is not a member of Circle, but could be made available as an extension method. + +The following import might fix the problem: + + import lib.circumference +``` + +## 讨论 + +`extension` 关键字声明您将要在括号中的类型上定义一个或多个扩展方法。 +要在一个类型上定义多个扩展方法，请使用以下语法： + +{% tabs ext7 %} +{% tab 'Scala 3 Only' %} +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` +{% endtab %} +{% endtabs %} diff --git a/_zh-cn/overviews/scala3-book/ca-given-imports.md b/_zh-cn/overviews/scala3-book/ca-given-imports.md new file mode 100644 index 0000000000..ba56af52f0 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-given-imports.md @@ -0,0 +1,54 @@ +--- +title: Given 导入 +type: section +description: This page demonstrates how 'given' import statements work in Scala 3. +language: zh-cn +num: 63 +previous-page: ca-context-bounds +next-page: ca-type-classes + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +为了更清楚地说明当前作用域中的 given 来自何处，我们使用一种特殊形式的 `import` 语句来导入 `given` 实例。 +此示例中显示了基本形式： + +```scala +object A: + class TC + given tc: TC = ??? + def f(using TC) = ??? + +object B: + import A.* // import all non-given members + import A.given // import the given instance +``` + +在此代码中，对象 `B` 的 `import A.*` 子句导入 `A` 的所有成员*除了* `given` 实例 `tc`。 +相反，第二个导入 `import A.given` *仅*导入 `given` 实例。 +两个 `import` 子句也可以合并为一个： + +```scala +object B: + import A.{given, *} +``` + +## 讨论 + +通配符选择器 `*` 将除 given 或扩展之外的所有定义都导入作用域，而 `given` 选择器将所有 *given* 定义---包括由扩展而来的定义---导入作用域。 + +这些规则有两个主要优点： + +- 更清楚当前作用域内 given 的来源。 + 特别是，在一长串其他通配符导入中无法隐藏导入的 given 。 +- 它可以导入所有 given ，而无需导入任何其他内容。 + 这很重要，因为 given 是可以匿名的，因此通常使用命名导入是不切实际的。 + +“导入 given”语法的更多示例见 [package 和 import 章节][imports]。 + + +[imports]: {% link _zh-cn/overviews/scala3-book/packaging-imports.md %} diff --git a/_zh-cn/overviews/scala3-book/ca-implicit-conversions.md b/_zh-cn/overviews/scala3-book/ca-implicit-conversions.md new file mode 100644 index 0000000000..5ab40c8064 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-implicit-conversions.md @@ -0,0 +1,53 @@ +--- +title: 隐式转换 +type: section +description: This page demonstrates how to implement Implicit Conversions in Scala 3. +language: zh-cn +num: 66 +previous-page: ca-multiversal-equality +next-page: ca-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +隐式转换由 `scala.Conversion` 类的 `given` 实例定义。 +例如，不考虑可能的转换错误，这段代码定义了从 `String` 到 `Int` 的隐式转换： + +```scala +given Conversion[String, Int] with + def apply(s: String): Int = Integer.parseInt(s) +``` + +使用别名可以更简洁地表示为： + +```scala +given Conversion[String, Int] = Integer.parseInt(_) +``` + +使用这些转换中的任何一种，您现在可以在需要 `Int` 的地方使用 `String`： + +```scala +import scala.language.implicitConversions + +// a method that expects an Int +def plus1(i: Int) = i + 1 + +// pass it a String that converts to an Int +plus1("1") +``` + +> 注意开头的子句 `import scala.language.implicitConversions`， +> 在文件中启用隐式转换。 + +## 讨论 + +Predef 包包含“自动装箱”转换，将基本数字类型映射到 `java.lang.Number` 的子类。 +例如，从 `Int` 到 `java.lang.Integer` 的转换可以定义如下： + +```scala +given int2Integer: Conversion[Int, java.lang.Integer] = + java.lang.Integer.valueOf(_) +``` diff --git a/_zh-cn/overviews/scala3-book/ca-multiversal-equality.md b/_zh-cn/overviews/scala3-book/ca-multiversal-equality.md new file mode 100644 index 0000000000..9c6d2f422c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-multiversal-equality.md @@ -0,0 +1,204 @@ +--- +title: 多元相等性 +type: section +description: This page demonstrates how to implement Multiversal Equality in Scala 3. +language: zh-cn +num: 65 +previous-page: ca-type-classes +next-page: ca-implicit-conversions + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +以前，Scala 具有*通用相等性*：任何类型的两个值都可以使用 `==` 和 `!=` 相互比较。 +这是因为 `==` 和 `!=` 是根据 Java 的 `equals` 方法实现的，该方法还可以比较任何两种引用类型的值。 + +通用相等性很方便，但也很危险，因为它破坏了类型安全。 +例如，假设在一些重构之后，你会得到一个错误的程序，其中值 `y` 的类型为 `S` 而不是正确的类型 `T`： + +```scala +val x = ... // of type T +val y = ... // of type S, but should be T +x == y // typechecks, will always yield false + +``` + +如果 `y` 与其他类型为 `T` 的值进行比较，程序仍然会进行类型检查，因为所有类型的值都可以相互比较。 +但它可能会产生意想不到的结果并在运行时失败。 + +类型安全的编程语言可以做得更好，多元等价是使普遍平等更安全的一种选择方式。 +它使用二元类型类“CanEqual”来指示两个给定类型的值可以相互比较。 + +## 允许比较类实例 + +默认情况下，在 Scala 3 中，您仍然可以像这样创建相等比较： + +```scala +case class Cat(name: String) +case class Dog(name: String) +val d = Dog("Fido") +val c = Cat("Morris") + +d == c // false, but it compiles +``` + +但是使用 Scala 3，您可以禁用此类比较。 +通过 (a) 导入 `scala.language.strictEquality` 或 (b) 使用 `-language:strictEquality` 编译器标志，此比较不再编译： + +```scala +import scala.language.strictEquality + +val rover = Dog("Rover") +val fido = Dog("Fido") +println(rover == fido) // compiler error + +// compiler error message: +// Values of types Dog and Dog cannot be compared with == or != +``` + +## 启用比较 + +有两种方法可以使用 Scala 3 `CanEqual` 类型类来启用这种比较。 +对于像这样的简单情况，您的类可以*派生* `CanEqual` 类： + +```scala +// Option 1 +case class Dog(name: String) derives CanEqual +``` + +稍后您将看到，当您需要更多的灵活性时，您还可以使用以下语法： + +```scala +// Option 2 +case class Dog(name: String) +given CanEqual[Dog, Dog] = CanEqual.derived +``` + +现在，这两种方法中的任何一种都可以让 `Dog` 实例相互比较。 + +## 一个更真实的例子 + +在一个更真实的示例中，假设您有一家在线书店，并且想要允许或禁止比较实体书、打印的书和有声读物。 +在 Scala 3 中，您首先启用多元平等性，如前面的示例所示： + +```scala +// [1] add this import, or this command line flag: -language:strictEquality +import scala.language.strictEquality +``` + +然后像往常一样创建你的领域对象： + +```scala +// [2] create your class hierarchy +trait Book: + def author: String + def title: String + def year: Int + +case class PrintedBook( + author: String, + title: String, + year: Int, + pages: Int +) extends Book + +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book +``` + +最后，使用 `CanEqual` 定义您想要允许的比较： + +```scala +// [3] create type class instances to define the allowed comparisons. +// allow `PrintedBook == PrintedBook` +// allow `AudioBook == AudioBook` +given CanEqual[PrintedBook, PrintedBook] = CanEqual.derived +given CanEqual[AudioBook, AudioBook] = CanEqual.derived + +// [4a] comparing two printed books works as desired +val p1 = PrintedBook("1984", "George Orwell", 1961, 328) +val p2 = PrintedBook("1984", "George Orwell", 1961, 328) +println(p1 == p2) // true + +// [4b] you can’t compare a printed book and an audiobook +val pBook = PrintedBook("1984", "George Orwell", 1961, 328) +val aBook = AudioBook("1984", "George Orwell", 2006, 682) +println(pBook == aBook) // compiler error +``` + +最后一行代码导致此编译器错误消息： + +```` +Values of types PrintedBook and AudioBook cannot be compared with == or != +```` + +这就是多元相等性在编译时捕获非法类型比较的方式。 + +### 启用“PrintedBook == AudioBook” + +这可以按需要工作，但在某些情况下，您可能希望允许将实体书与有声读物进行比较。 +如果需要，请创建以下两个额外的相等比较： + +```scala +// allow `PrintedBook == AudioBook`, and `AudioBook == PrintedBook` +given CanEqual[PrintedBook, AudioBook] = CanEqual.derived +given CanEqual[AudioBook, PrintedBook] = CanEqual.derived +``` + +现在，您可以将实体书与有声书进行比较，而不会出现编译错误： + +```scala +println(pBook == aBook) // false +println(aBook == pBook) // false +``` + +#### 实现 “equals” 以使它们真正起作用 + +虽然现在允许进行这些比较，但它们将始终为 `false`，因为它们的 `equals` 方法不知道如何进行这些比较。 +因此，解决方案是覆盖每个类的 `equals` 方法。 +例如，当您覆盖 `AudioBook` 的 `equals` 方法时： + +```scala +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book: + // override to allow AudioBook to be compared to PrintedBook + override def equals(that: Any): Boolean = that match + case a: AudioBook => + if this.author == a.author + && this.title == a.title + && this.year == a.year + && this.lengthInMinutes == a.lengthInMinutes + then true else false + case p: PrintedBook => + if this.author == p.author && this.title == p.title + then true else false + case _ => + false +``` + +您现在可以将 `AudioBook` 与 `PrintedBook` 进行比较： + +```scala +println(aBook == pBook) // true (works because of `equals` in `AudioBook`) +println(pBook == aBook) // false +``` + +目前 `PrintedBook` 书没有 `equals` 方法，所以第二个比较返回 `false`。 +要启用该比较，只需覆盖 `PrintedBook` 中的 `equals` 方法。 + +您可以在参考文档中找到有关[多元相等性][ref-equal] 的更多信息。 + + +[ref-equal]: {{ site.scala3ref }}/contextual/multiversal-equality.html diff --git a/_zh-cn/overviews/scala3-book/ca-summary.md b/_zh-cn/overviews/scala3-book/ca-summary.md new file mode 100644 index 0000000000..60b1fd01a5 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-summary.md @@ -0,0 +1,37 @@ +--- +title: 总结 +type: section +description: This page provides a summary of the Contextual Abstractions lessons. +language: zh-cn +num: 67 +previous-page: ca-implicit-conversions +next-page: concurrency + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍了大多数上下文抽象主题，包括： + +- 给定实例和使用子句 +- 上下文绑定 +- 给定导入 +- 扩展方法 +- 实现类型类 +- 多元相等性 +- 隐式转换 + +这里没有涉及一些更高级的主题，包括： + +- 类型类派生 +- 上下文函数 +- 传名上下文参数 +- 与 Scala 2 隐式转换 的关系 + +这些主题在 [参考文档][ref] 中有详细讨论。 + + +[ref]: {{ site.scala3ref }}/contextual diff --git a/_zh-cn/overviews/scala3-book/ca-type-classes.md b/_zh-cn/overviews/scala3-book/ca-type-classes.md new file mode 100644 index 0000000000..7adffa0594 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-type-classes.md @@ -0,0 +1,193 @@ +--- +title: 实现类型类 +type: section +description: This page demonstrates how to create and use type classes in Scala 3. +language: zh-cn +num: 64 +previous-page: ca-given-imports +next-page: ca-multiversal-equality + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +_类型类_ 是一种抽象的参数化类型，它允许您在不使用子类型的情况下向任何封闭数据类型添加新行为。 +如果你从 Java 那边过来，你可以将类型类视为类似于 [`java.util.Comparator[T]`][comparator] 的东西。 + +> Oliveira 等人写的论文 [“Type Classes as Objects and Implicits”][typeclasses-paper] (2010) 讨论了在 Scala 中类型类背后的基本观点。 +> 虽然论文用了旧的 Scala 版本，但其中的观点至今依然有用。 + +这在多用例中很有用，例如： + +- 表达你不拥有的类型——来自标准库或第三方库——如何符合这种行为 +- 为多种类型表达这种行为，而不涉及这些类型之间的子类型关系 + +类型类只是具有一个或多个参数的 traits，其实现在 Scala 3 中，由 `given` 实例提供，在 Scala 2 中用 `implicit` 值。 + +## 例子 + +例如，`Show` 是 Haskell 中众所周知的类型类，下面的代码显示了在 Scala 中实现它的一种方法。 +如果您认为 Scala 类没有 `toString` 方法，您可以定义一个 `Show` 类型类，然后把此行为添加到任意的类，这个类是能够转换为自定义字符串。 + +### 类型类 + +创建类型类的第一步是声明具有一个或多个抽象方法的参数化 trait。 +因为 `Showable` 只有一个名为 `show` 的方法，所以写成这样： + +{% tabs 'definition' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +// a type class +trait Showable[A] { + def show(a: A): String +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +// a type class +trait Showable[A]: + extension(a: A) def show: String +``` +{% endtab %} +{% endtabs %} + +请注意，通常当你要定义 `Show` trait时，下面这样的办法接近普通的面向对象的办法： + +{% tabs 'trait' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +// a trait +trait Show { + def show: String +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +// a trait +trait Show: + def show: String +``` +{% endtab %} +{% endtabs %} + +有几件重要的事情需要指出： + +1. 像 `Showable` 这样的类型类有一个类型参数 `A` 来说明我们为哪种类型提供了 `show` 的实现；相反，像 `Show` 这样的传统的 trait 不会。 +2. 要将 show 功能添加到特定类型 `A`，传统的 trait 需要 `A extends Show`，而对于类型类，我们需要实现 `Showable[A]`。 +3. 在 Scala 3 中，为了在两个 `Showable` 中允许相同的方法调用语法来模仿 `Show`，我们将 `Showable.show` 定义为扩展方法。 + +### 实现具体实例 + +下一步是确定在应用程序中，`Showable` 适用于哪些类，然后为它们实现该行为。 +例如，为这个 `Person` 类实现 `Showable`： + +{% tabs 'person' %} +{% tab 'Scala 2 and 3' %} +```scala +case class Person(firstName: String, lastName: String) +``` +{% endtab %} +{% endtabs %} + +你将为 `Showable[Person]` 定义一个 _规范值_ ，例如下面的代码为 `Person` 类提供了一个 `Showable` 的实例： + +{% tabs 'instance' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +implicit val showablePerson: Showable[Person] = new Showable[Person] { + def show(p: Person): String = + s"${p.firstName} ${p.lastName}" +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +given Showable[Person] with + extension(p: Person) def show: String = + s"${p.firstName} ${p.lastName}" +``` +{% endtab %} +{% endtabs %} + +### 使用类型类 + +现在你可以像这样使用这个类型类： + +{% tabs 'usage' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val person = Person("John", "Doe") +println(showablePerson.show(person)) +``` + +注意，在实践中，类型类一般与类型未知的值一起使用，而不像下面章节展示的 `Person` 类。 +{% endtab %} +{% tab 'Scala 3' %} +```scala +val person = Person("John", "Doe") +println(person.show) +``` +{% endtab %} +{% endtabs %} + +同样，如果 Scala 没有可用于每个类的 `toString` 方法，您可以使用此技术将 `Showable` 行为添加到您希望能够转换为 `String` 的任何类。 + +### 编写使用类型类的方法 + +与继承一样，您可以定义使用 `Showable` 作为类型参数的方法： + +{% tabs 'method' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def showAll[A](as: List[A])(implicit showable: Showable[A]): Unit = + as.foreach(a => println(showable.show(a))) + +showAll(List(Person("Jane"), Person("Mary"))) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def showAll[A: Showable](as: List[A]): Unit = + as.foreach(x => println(a.show)) + +showAll(List(Person("Jane"), Person("Mary"))) +``` +{% endtab %} +{% endtabs %} + +### 具有多种方法的类型类 + +请注意，如果要创建具有多个方法的类型类，则初始语法如下所示： + +{% tabs 'multiple-methods' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +trait HasLegs[A] { + def walk(a: A): Unit + def run(a: A): Unit +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +trait HasLegs[A]: + extension (a: A) + def walk(): Unit + def run(): Unit +``` +{% endtab %} +{% endtabs %} + +### 一个真实的例子 + +有关如何在 Scala 3 中使用类型类的真实示例，请参阅[多元相等性部分][multiversal]中的 `CanEqual` 讨论。 + +[typeclasses-paper]: https://infoscience.epfl.ch/record/150280/files/TypeClasses.pdf +[typeclasses-chapter]: {% link _overviews/scala3-book/ca-type-classes.md %} +[comparator]: https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html +[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} diff --git a/_zh-cn/overviews/scala3-book/collections-classes.md b/_zh-cn/overviews/scala3-book/collections-classes.md new file mode 100644 index 0000000000..47ccd58bbe --- /dev/null +++ b/_zh-cn/overviews/scala3-book/collections-classes.md @@ -0,0 +1,861 @@ +--- +title: 集合类型 +type: section +description: This page introduces the common Scala 3 collections types and some of their methods. +language: zh-cn +num: 38 +previous-page: collections-intro +next-page: collections-methods + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +{% comment %} +TODO: mention Array, ArrayDeque, ListBuffer, Queue, Stack, StringBuilder? +LATER: note that methods like `+`, `++`, etc., are aliases for other methods +LATER: add links to the Scaladoc for the major types shown here +{% endcomment %} + +本页演示了常见的 Scala 3 集合及其附带的方法。 +Scala 提供了丰富的集合类型，但您可以从其中的几个开始，然后根据需要使用其他的。 +同样，每种集合类型都有数十种方法可以让您的生活更轻松，但您可以从其中的少数几个开始使用，就可以有很多收获。 + +因此，本节介绍并演示了在开始时，需要使用的最常见的类型和方法。 +当您需要更大的灵活性时，请参阅本节末尾的这些页面以获取更多细节。 + +## 三大类集合 + +从高层次看 Scala 集合，有三个主要类别可供选择： + +- **序列**是元素的顺序集合，可以是_有索引的_（如数组）或_线性的_（如链表） +- **映射** 包含键/值对的集合，例如 Java `Map`、Python 字典或 Ruby `Hash` +- **集合** 是无重复元素的无序集合 + +所有这些都是基本类型，并且具有用于特定目的的子类型，例如并发、缓存和流式传输。 +除了这三个主要类别之外，还有其他有用的集合类型，包括范围、堆栈和队列。 + +### 集合层次结构 + +作为简要概述，接下来的三个图显示了 Scala 集合中类和 trait 的层次结构。 + +第一张图显示了_scala.collection_包中的集合类型。 +这些都是高级抽象类或 traits，它们通常有_不可变_和_可变_的实现。 + +![一般集合层次结构][collections1] + +此图显示包 _scala.collection.immutable_ 中的所有集合： + +![不可变集合层次结构][collections2] + +此图显示包 _scala.collection.mutable_ 中的所有集合： + +![可变集合层次结构][collections3] + +在查看了所有集合类型的详细视图后，以下部分将介绍一些经常使用的常见类型。 + +{% comment %} +NOTE: those images come from this page: https://docs.scala-lang.org/overviews/collections-2.13/overview.html +{% endcomment %} + +## 常用集合 + +您经常使用的主要集合是： + +| 集合类型 | 不可变 | 可变 | 说明 | +| ------------- | --------- | -------- | ------------ | +| `List` | ✓ | | 线性（链表）、不可变序列 | +| `Vector` | ✓ | | 一个索引的、不可变的序列 | +| `LazyList` | ✓ | | 一个惰性不可变链表，它的元素仅在需要时才计算；适用于大型或无限序列。 | +| `ArrayBuffer` | | ✓ | 可变索引序列的首选类型 | +| `ListBuffer` | | ✓ | 当你想要一个可变的 `List` 时使用；通常转换为“列表” | +| `Map` | ✓ | ✓ | 由键和值对组成的可迭代集合。 | +| `Set` | ✓ | ✓ | 没有重复元素的可迭代集合 | + +如图所示，`Map` 和 `Set` 有不可变和可变版本。 + +以下部分演示了每种类型的基础知识。 + +> 在 Scala 中，_缓冲_——例如 `ArrayBuffer` 和 `ListBuffer`——是一个可以增长和缩小的序列。 + +### 关于不可变集合的说明 + +在接下来的部分中，无论何时使用_不可变_这个词，都可以安全地假设该类型旨在用于_函数式编程_(FP) 风格。 +使用这些类型，您无需修改​​集合；您将函数式方法应用于该集合以创建新的结果。 + +## 选择序列 + +选择_序列_ -- 一个顺序集合元素时 -- 您有两个主要决定： + +- 是否应该对序列进行索引（如数组），允许快速访问任何元素，还是应该将其实现为线性链表？ +- 你想要一个可变的还是不可变的集合？ + +此处显示了推荐的通用顺序集合，用于可变/不可变和索引/线性组合： + +| 类型/类别 | 不可变 | 可变 | +| --------------------- | --------- | ------------ | +|索引 | `Vector` |`ArrayBuffer` | +|线性（链表） | `List` |`ListBuffer` | + +例如，如果您需要一个不可变的索引集合，通常您应该使用 `Vector`。 +相反，如果您需要一个可变的索引集合，请使用 `ArrayBuffer`。 + +> `List` 和 `Vector` 在以函数式风格编写代码时经常使用。 +> `ArrayBuffer` 通常在以命令式风格编写代码时使用。 +> `ListBuffer` 用于混合样式时，例如构建列表。 + +接下来的几节简要介绍了 `List`、`Vector` 和 `ArrayBuffer` 类型。 + +## `List` + +[列表类型](https://www.scala-lang.org/api/current/scala/collection/immutable/List.html) 是一个线性的、不可变的序列。 +这只是意味着它是一个您无法修改的链表。 +任何时候你想添加或删除 `List` 元素，你都可以从现有的 `List` 中创建一个新的 `List`。 + +### 创建列表 + +这是创建初始“列表”的方式： + +{% tabs list-creation %} +{% tab 'Scala 2 and 3' %} +```scala +val ints = List(1, 2, 3) +val names = List("Joel", "Chris", "Ed") + +// another way to construct a List +val namesAgain = "Joel" :: "Chris" :: "Ed" :: Nil +``` +{% endtab %} +{% endtabs %} + +如果您愿意，也可以声明 `List` 的类型，但通常不是必需的： + +{% tabs list-type %} +{% tab 'Scala 2 and 3' %} +```scala +val ints: List[Int] = List(1, 2, 3) +val names: List[String] = List("Joel", "Chris", "Ed") +``` +{% endtab %} +{% endtabs %} + +一个例外是集合中有混合类型时。在这种情况下，您可能需要明确指定其类型： + +{% tabs list-mixed-types class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val things: List[Any] = List(1, "two", 3.0) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val things: List[String | Int | Double] = List(1, "two", 3.0) // with union types +val thingsAny: List[Any] = List(1, "two", 3.0) // with any +``` +{% endtab %} +{% endtabs %} + +### 将元素添加到列表 + +因为 `List` 是不可变的，所以你不能向它添加新元素。 +相反，您可以通过将元素添加到现有 `List` 来创建新列表。 +例如，给定这个 `List`： + +{% tabs adding-elements-init %} +{% tab 'Scala 2 and 3' %} +```scala +val a = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +使用 `List` 时，用 `::` 来_附加_一个元素，用 `:::` 把另一个 `List` 插在这个 `List` 之前，如下所示： + +{% tabs adding-elements-example %} +{% tab 'Scala 2 and 3' %} +```scala +val b = 0 :: a // List(0, 1, 2, 3) +val c = List(-1, 0) ::: a // List(-1, 0, 1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +你也可以在 `List` 中添加元素，但是因为 `List` 是一个单链表，你通常应该只在它前面添加元素； +在它的后面添加元素是一个相对较慢的操作，尤其是在处理大型序列时。 + +> 提示：如果您想将元素添加到不可变序列的前面或者后面时，请改用 `Vector`。 + +因为 `List` 是一个链表，你不应该尝试通过索引值来访问大列表的元素。 +例如，如果您有一个包含一百万个元素的 `List` ，则访问像 `myList(999_999)` 这样的元素将花费相对较长的时间，因为该请求必须遍历所有这些元素。 +如果您有一个大型集合并希望通过索引访问元素，请改用 `Vector` 或 `ArrayBuffer`。 + +### 如何记住方法名 + +现在 IDE 为我们提供了极大的帮助，但是记住这些方法名称的一种方法是，认为 `:` 字符代表序列所在的一侧，因此当您使用 `+:` 时，您知道列表需要在右边，像这样： + +{% tabs list-prepending %} +{% tab 'Scala 2 and 3' %} +```scala +0 +： a +``` +{% endtab %} +{% endtabs %} + +同样，当您使用 `:+` 时，您知道列表需要在左侧： + +{% tabs list-appending %} +{% tab 'Scala 2 and 3' %} +```scala +a ：+ 4 +``` +{% endtab %} +{% endtabs %} + +有更多的技术方法可以考虑这一点，但这可能是记住方法名称的有用方法。 + +{% comment %} +LATER: Add a discussion of `:` on method names, right-associativity, and infix operators. +{% endcomment %} + +此外，这些符号方法名称的一个好处是它们是一致的。 +相同的方法名称用于其他不可变序列，例如 `Seq` 和 `Vector`。 +如果您愿意，还可以使用非符号方法名称来附加元素和在头部插入元素。 + +### 如何遍历列表 + +给定一个名称 `List`： + +{% tabs list-loop-init %} +{% tab 'Scala 2 and 3' %} +```scala +val names = List("Joel", "Chris", "Ed") +``` +{% endtab %} +{% endtabs %} + +您可以像这样打印每个字符串： + +{% tabs list-loop-example class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +for (name <- names) println(name) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +for name <- names do println(name) +``` +{% endtab %} +{% endtabs %} + +这是它在 REPL 中的样子： + +{% tabs list-loop-repl class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +scala> for (name <- names) println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for name <-names do println(name) +Joel +Chris +Ed +``` +{% endtab %} +{% endtabs %} + +将 `for` 循环与集合一起使用的一个好处是 Scala 是一致的，并且相同的方法适用于所有序列，包括 `Array`、`ArrayBuffer`、`List`、`Seq`、`Vector`、`Map` ，`Set` 等。 + +### 一点历史 + +对于那些对历史感兴趣的人，Scala `List` 类似于 [Lisp 编程语言](https://en.wikipedia.org/wiki/Lisp_(programming_language)) 中的 `List`，它是最初于 1958 年确定的。 +实际上，除了像这样创建一个 `List` 之外： + +{% tabs list-history-init %} +{% tab 'Scala 2 and 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +您也可以通过这种方式创建完全相同的列表： + +{% tabs list-history-init2 %} +{% tab 'Scala 2 and 3' %} +```scala +val list = 1 :: 2 :: 3 :: Nil +``` +{% endtab %} +{% endtabs %} + +REPL 展示了它是如何工作的： + +{% tabs list-history-repl %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val list = 1 :: 2 :: 3 :: Nil +list: List[Int] = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +这是因为 `List` 是一个以 `Nil` 元素结尾的单链表，而 `::` 是一个 `List` 方法，其工作方式类似于 Lisp 的“cons”运算符。 + +### 旁白：LazyList + +Scala 集合还包括一个 [LazyList](https://www.scala-lang.org/api/current/scala/collection/immutable/LazyList.html)，它是一个 _惰性_不可变链表。 +它被称为“惰性”——或非严格——因为它仅在需要时计算其元素。 + +你可以看到 REPL 中的 `LazyList` 有多懒惰： + +{% tabs lazylist-example %} +{% tab 'Scala 2 and 3' %} +```scala +val x = LazyList.range(1, Int.MaxValue) +x.take(1) // LazyList() +x.take(5) // LazyList() +x.map(_ + 1) // LazyList() +``` +{% endtab %} +{% endtabs %} + +在所有这些例子中，什么都没有发生。 +事实上，除非你强迫它发生，否则什么都不会发生，例如通过调用它的 `foreach` 方法： + +{% tabs lazylist-evaluation-example %} +{% tab 'Scala 2 and 3' %} +```scala +scala> x.take(1).foreach(println) +1 +``` +{% endtab %} +{% endtabs %} + +有关严格和非严格的用途、好处和缺点的更多信息严格（惰性）集合，请参阅 [Scala 2.13集合的架构][strict] 页面上的“严格”和“非严格”讨论。 + + + +## 向量 + +[向量](https://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html) 是一个索引的、不可变的序列。 +描述的“索引”部分意味着它提供了在有效恒定时间内随机访问和更新向量，因此您可以通过索引值快速访问 `Vector` 元素，例如访问 `listOfPeople(123_456_789)` 。 + +一般来说，除了 (a) `Vector` 有索引而 `List` 没有索引，以及 (b) `List` 有 `::` 方法这两个不同外，这两种类型的工作方式相同，所以我们将快速过一下示例。 + +以下是创建“向量”的几种方法： + +{% tabs vector-creation %} +{% tab 'Scala 2 and 3' %} +```scala +val nums = Vector(1, 2, 3, 4, 5) + +val strings = Vector("one", "two") + +case class Person(name: String) +val people = Vector( + Person("Bert"), + Person("Ernie"), + Person("Grover") +) +``` +{% endtab %} +{% endtabs %} + +因为 `Vector` 是不可变的，所以你不能向它添加新元素。 +相反，您通过将元素附加或插入头部到现有的 `Vector`，从而创建新序列。 +这些示例展示了如何将元素_附加_到 `Vector`： + +{% tabs vector-appending %} +{% tab 'Scala 2 and 3' %} +```scala +val a = Vector(1,2,3) // Vector(1, 2, 3) +val b = a :+ 4 // Vector(1, 2, 3, 4) +val c = a ++ Vector(4, 5) // Vector(1, 2, 3, 4, 5) +``` +{% endtab %} +{% endtabs %} + +这就是你_插入头部_元素的方式： + +{% tabs vector-prepending %} +{% tab 'Scala 2 and 3' %} +```scala +val a = Vector(1,2,3) // Vector(1, 2, 3) +val b = 0 +: a // Vector(0, 1, 2, 3) +val c = Vector(-1, 0) ++: a // Vector(-1, 0, 1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +除了快速的随机访问和更新之外，`Vector` 还提供了快速的追加和前置时间，因此您可以根据需要使用这些功能。 + +> 请参阅 [集合性能特性](https://docs.scala-lang.org/overviews/collections-2.13/performance-characteristics.html) 了解有关 `Vector` 和其他集合的性能详细信息。 + +最后，您可以在 `for` 循环中使用 `Vector`，就像 `List`、`ArrayBuffer` 或任何其他序列一样： + +{% tabs vector-loop class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +scala> val names = Vector("Joel", "Chris", "Ed") +val names: Vector[String] = Vector(Joel, Chris, Ed) + +scala> for (name <- names) println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> val names = Vector("Joel", "Chris", "Ed") +val names: Vector[String] = Vector(Joel, Chris, Ed) + +scala> for name <- names do println(name) +Joel +Chris +Ed +``` +{% endtab %} +{% endtabs %} + +## 数组缓冲区 + +当您在 Scala 应用程序中需要一个通用的、可变的索引序列时，请使用 `ArrayBuffer`。 +它是可变的，所以你可以改变它的元素，也可以调整它的大小。 +因为它是索引的，所以元素的随机访问很快。 + +### 创建一个数组缓冲区 + +要使用 `ArrayBuffer`，首先导入它： + +{% tabs arraybuffer-import %} +{% tab 'Scala 2 and 3' %} +```scala +import scala.collection.mutable.ArrayBuffer +``` +{% endtab %} +{% endtabs %} + +如果您需要从一个空的 `ArrayBuffer` 开始，只需指定其类型： + +{% tabs arraybuffer-creation %} +{% tab 'Scala 2 and 3' %} +```scala +var strings = ArrayBuffer[String]() +var ints = ArrayBuffer[Int]() +var people = ArrayBuffer[Person]() +``` +{% endtab %} +{% endtabs %} + +如果您知道 `ArrayBuffer` 最终需要的大致大小，则可以使用初始大小创建它： + +{% tabs list-creation-with-size %} +{% tab 'Scala 2 and 3' %} +```scala +// ready to hold 100,000 ints +val buf = new ArrayBuffer[Int](100_000) +``` +{% endtab %} +{% endtabs %} + +要创建具有初始元素的新 `ArrayBuffer`，只需指定其初始元素，就像 `List` 或 `Vector` 一样： + +{% tabs arraybuffer-init %} +{% tab 'Scala 2 and 3' %} +```scala +val nums = ArrayBuffer(1, 2, 3) +val people = ArrayBuffer( + Person("Bert"), + Person("Ernie"), + Person("Grover") +) +``` +{% endtab %} +{% endtabs %} + +### 将元素添加到数组缓冲区 + +使用 `+=` 和 `++=` 方法将新元素附加到 `ArrayBuffer`。 +或者，如果您更喜欢具有文本名称的方法，您也可以使用 `append`、`appendAll`、`insert`、`insertAll`、`prepend` 和 `prependAll`。 + +以下是 `+=` 和 `++=` 的一些示例： + +{% tabs arraybuffer-add %} +{% tab 'Scala 2 and 3' %} +```scala +val nums = ArrayBuffer(1, 2, 3) // ArrayBuffer(1, 2, 3) +nums += 4 // ArrayBuffer(1, 2, 3, 4) +nums ++= List(5, 6) // ArrayBuffer(1, 2, 3, 4, 5, 6) +``` +{% endtab %} +{% endtabs %} + +### 从数组缓冲区中移除元素 + +`ArrayBuffer` 是可变的，所以它有 `-=`、`--=`、`clear`、`remove` 等方法。 +这些示例演示了 `-=` 和 `--=` 方法： + +{% tabs arraybuffer-remove %} +{% tab 'Scala 2 and 3' %} +```scala +val a = ArrayBuffer.range('a', 'h') // ArrayBuffer(a, b, c, d, e, f, g) +a -= 'a' // ArrayBuffer(b, c, d, e, f, g) +a --= Seq('b', 'c') // ArrayBuffer(d, e, f, g) +a --= Set('d', 'e') // ArrayBuffer(f, g) +``` +{% endtab %} +{% endtabs %} + +### 更新数组缓冲区元素 + +通过重新分配所需元素或使用 `update` 方法来更新 `ArrayBuffer` 中的元素： + +{% tabs arraybuffer-update %} +{% tab 'Scala 2 and 3' %} +```scala +val a = ArrayBuffer.range(1,5) // ArrayBuffer(1, 2, 3, 4) +a(2) = 50 // ArrayBuffer(1, 2, 50, 4) +a.update(0, 10) // ArrayBuffer(10, 2, 50, 4) +``` +{% endtab %} +{% endtabs %} + +## 映射 + +`Map` 是由键值对组成的可迭代集合。 +Scala 有可变和不可变的 `Map` 类型，本节演示如何使用_不可变_ `Map`。 + +### 创建不可变映射 + +像这样创建一个不可变的`Map`： + +{% tabs map-init %} +{% tab 'Scala 2 and 3' %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AZ" -> "Arizona" +) +``` +{% endtab %} +{% endtabs %} + +一旦你有了一个`Map`，你可以像这样在`for`循环中遍历它的元素： + +{% tabs map-loop class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +for ((k, v) <- states) println(s"key: $k, value: $v") +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +for (k, v) <- states do println(s"key: $k, value: $v") +``` +{% endtab %} +{% endtabs %} + +REPL 展示了它是如何工作的： + +{% tabs map-repl class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +scala> for ((k, v) <- states) println(s"key: $k, value: $v") +key: AK, value: Alaska +key: AL, value: Alabama +key: AZ, value: Arizona +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for (k, v) <- states do println(s"key: $k, value: $v") +key: AK, value: Alaska +key: AL, value: Alabama +key: AZ, value: Arizona +``` +{% endtab %} +{% endtabs %} + +### 访问映射元素 + +通过在括号中指定所需的键值来访问映射元素： + +{% tabs map-access-element %} +{% tab 'Scala 2 and 3' %} +```scala +val ak = states("AK") // ak: String = Alaska +val al = states("AL") // al: String = Alabama +``` +{% endtab %} +{% endtabs %} + +在实践中，您还将使用诸如 `keys`、`keySet`、`keysIterator`、`for` 循环之类的方法以及 `map` 之类的高阶函数来处理 `Map` 键和值。 + +### 向映射添加元素 + +使用 `+` 和 `++` 将元素添加到不可变映射中，记住将结果分配给新变量： + +{% tabs map-add-element %} +{% tab 'Scala 2 and 3' %} +```scala +val a = Map(1 -> "one") // a: Map(1 -> one) +val b = a + (2 -> "two") // b: Map(1 -> one, 2 -> two) +val c = b ++ Seq( + 3 -> "three", + 4 -> "four" +) +// c: Map(1 -> one, 2 -> two, 3 -> three, 4 -> four) +``` +{% endtab %} +{% endtabs %} + +### 从映射中删除元素 + +使用 `-` 或 `--` 和要删除的键值从不可变映射中删除元素，记住将结果分配给新变量： + +{% tabs map-remove-element %} +{% tab 'Scala 2 and 3' %} +```scala +val a = Map( + 1 -> "one", + 2 -> "two", + 3 -> "three", + 4 -> "four" +) + +val b = a - 4 // b: Map(1 -> one, 2 -> two, 3 -> three) +val c = a - 4 - 3 // c: Map(1 -> one, 2 -> two) +``` +{% endtab %} +{% endtabs %} + +### 更新映射元素 + +要更新不可变映射中的元素，请在将结果分配给新变量时使用 `updated` 方法（或 `+` 运算符）： + +{% tabs map-update-element %} +{% tab 'Scala 2 and 3' %} +```scala +val a = Map( + 1 -> "one", + 2 -> "two", + 3 -> "three" +) + +val b = a.updated(3, "THREE!") // b: Map(1 -> one, 2 -> two, 3 -> THREE!) +val c = a + (2 -> "TWO...") // c: Map(1 -> one, 2 -> TWO..., 3 -> three) +``` +{% endtab %} +{% endtabs %} + +### 遍历映射 + +如前所述，这是使用 `for` 循环手动遍历映射中元素的常用方法： + +{% tabs map-traverse class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AZ" -> "Arizona" +) + +for ((k, v) <- states) println(s"key: $k, value: $v") +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AZ" -> "Arizona" +) + +for (k, v) <- states do println(s"key: $k, value: $v") +``` +{% endtab %} +{% endtabs %} + +话虽如此，有_许多_方法可以使用映射中的键和值。 +常见的 `Map` 方法包括 `foreach`、`map`、`keys` 和 `values`。 + +Scala 有许多更专业的`Map` 类型，包括`CollisionProofHashMap`、`HashMap`、`LinkedHashMap`、`ListMap`、`SortedMap`、`TreeMap`、`WeakHashMap` 等等。 + +## 使用集合 + +Scala [集合]({{site.baseurl}}/overviews/collections-2.13/sets.html) 是一个没有重复元素的可迭代集合。 + +Scala 有可变和不可变的 `Set` 类型。 +本节演示_不可变_ `Set`。 + +### 创建一个集合 + +像这样创建新的空集： + +{% tabs set-creation %} +{% tab 'Scala 2 and 3' %} +```scala +val nums = Set[Int]() +val letters = Set[Char]() +``` +{% endtab %} +{% endtabs %} + +使用初始数据创建集合，如下： + +{% tabs set-init %} +{% tab 'Scala 2 and 3' %} +```scala +val nums = Set(1, 2, 3, 3, 3) // Set(1, 2, 3) +val letters = Set('a', 'b', 'c', 'c') // Set('a', 'b', 'c') +``` +{% endtab %} +{% endtabs %} + +### 向集合中添加元素 + +使用 `+` 和 `++` 将元素添加到不可变的 `Set`，记住将结果分配给一个新变量： + +{% tabs set-add-element %} +{% tab 'Scala 2 and 3' %} +```scala +val a = Set(1, 2) // Set(1, 2) +val b = a + 3 // Set(1, 2, 3) +val c = b ++ Seq(4, 1, 5, 5) // HashSet(5, 1, 2, 3, 4) +``` +{% endtab %} +{% endtabs %} + +请注意，当您尝试添加重复元素时，它们会被悄悄删除。 + +另请注意，元素的迭代顺序是任意的。 + +### 从集合中删除元素 + +使用 `-` 和 `--` 从不可变集合中删除元素，再次将结果分配给新变量： + +{% tabs set-remove-element %} +{% tab 'Scala 2 and 3' %} +```scala +val a = Set(1, 2, 3, 4, 5) // HashSet(5, 1, 2, 3, 4) +val b = a - 5 // HashSet(1, 2, 3, 4) +val c = b -- Seq(3, 4) // HashSet(1, 2) +``` +{% endtab %} +{% endtabs %} + +## 范围 + +Scala `Range` 通常用于填充数据结构和迭代 `for` 循环。 +这些 REPL 示例演示了如何创建范围： + +{% comment %} +LATER: the dotty repl currently shows results differently +{% endcomment %} + +{% tabs range-init %} +{% tab 'Scala 2 and 3' %} +```scala +1 to 5 // Range(1, 2, 3, 4, 5) +1 until 5 // Range(1, 2, 3, 4) +1 to 10 by 2 // Range(1, 3, 5, 7, 9) +'a' to 'c' // NumericRange(a, b, c) +``` +{% endtab %} +{% endtabs %} + +您可以使用范围来填充集合： + +{% tabs range-conversion %} +{% tab 'Scala 2 and 3' %} +```scala +val x = (1 to 5).toList // List(1, 2, 3, 4, 5) +val x = (1 to 5).toBuffer // ArrayBuffer(1, 2, 3, 4, 5) +``` +{% endtab %} +{% endtabs %} + +它们也用于 `for` 循环： + +{% tabs range-iteration class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +scala> for (i <- 1 to 3) println(i) +1 +2 +3 +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for i <- 1 to 3 do println(i) +1 +2 +3 +``` +{% endtab %} +{% endtabs %} + +还有 `range` 方法： + +{% tabs range-methods %} +{% tab 'Scala 2 and 3' %} +```scala +Vector.range(1, 5) // Vector(1, 2, 3, 4) +List.range(1, 10, 2) // List(1, 3, 5, 7, 9) +Set.range(1, 10) // HashSet(5, 1, 6, 9, 2, 7, 3, 8, 4) +``` +{% endtab %} +{% endtabs %} + +当您运行测试时，范围对于生成​​测试集合也很有用： + +{% tabs range-tests %} +{% tab 'Scala 2 and 3' %} +```scala +val evens = (0 to 10 by 2).toList // List(0, 2, 4, 6, 8, 10) +val odds = (1 to 10 by 2).toList // List(1, 3, 5, 7, 9) +val doubles = (1 to 5).map(_ * 2.0) // Vector(2.0, 4.0, 6.0, 8.0, 10.0) + +// create a Map +val map = (1 to 3).map(e => (e,s"$e")).toMap + // map: Map[Int, String] = Map(1 -> "1", 2 -> "2", 3 -> "3") +``` +{% endtab %} +{% endtabs %} + +## 更多细节 + +当您需要特定集合更多的信息，请参阅以下资源： + +- [具体的不可变集合类](https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html) +- [具体的可变集合类](https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html) +- [集合是如何构造的？ 我应该选择哪一个？](https://docs.scala-lang.org/tutorials/FAQ/collections.html) + + +[strict]: {% link _overviews/core/architecture-of-scala-213-collections.md %} +[collections1]: /resources/images/tour/collections-diagram-213.svg +[collections2]: /resources/images/tour/collections-immutable-diagram-213.svg +[collections3]: /resources/images/tour/collections-mutable-diagram-213.svg diff --git a/_zh-cn/overviews/scala3-book/collections-intro.md b/_zh-cn/overviews/scala3-book/collections-intro.md new file mode 100644 index 0000000000..0b2e1b77ff --- /dev/null +++ b/_zh-cn/overviews/scala3-book/collections-intro.md @@ -0,0 +1,30 @@ +--- +title: Scala 集合 +type: chapter +description: This page provides and introduction to the common collections classes and their methods in Scala 3. +language: zh-cn +num: 37 +previous-page: packaging-imports +next-page: collections-classes + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍了最常见的 Scala 3 集合及其附带的方法。 +Scala 提供了丰富的集合类型，但您可以从其中的几个开始，然后根据需要使用其他的。 +同样，每种类型都有数十种方法可以让您的生活更轻松，但您可以从少数几种方法开始使用，就可以有很多收获。 + +因此，本节介绍并演示您开始时，需要使用的最常见的集合类型和方法。 + +{% comment %} +LATER: Use more of the content from this page: + https://docs.scala-lang.org/overviews/index.html +{% endcomment %} + + + + diff --git a/_zh-cn/overviews/scala3-book/collections-methods.md b/_zh-cn/overviews/scala3-book/collections-methods.md new file mode 100644 index 0000000000..898619d144 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/collections-methods.md @@ -0,0 +1,558 @@ +--- +title: 集合方法 +type: section +description: This page demonstrates the common methods on the Scala 3 collections classes. +language: zh-cn +num: 39 +previous-page: collections-classes +next-page: collections-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 集合的一大优势在于它们提供了许多开箱即用的方法，并且这些方法在不可变和可变集合类型中始终可用。 +这样做的好处是，您不用在每次需要使用集合时编写自定义的 `for` 循环，并且当您从一个项目转到另一个项目时，您会发现更多地使用这些相同的方法，而不是使用自定义 `for` 循环。 + +有*几十*种方法可供您使用，因此此处并未全部显示。 +相反，只显示了一些最常用的方法，包括： + +- `map` +- `filter` +- `foreach` +- `head` +- `tail` +- `take`, `takeWhile` +- `drop`, `dropWhile` +- `reduce` + +以下方法适用于所有序列类型，包括 `List`、`Vector`、`ArrayBuffer` 等，但除非另有说明，否则这些示例使用 `List`。 + +> 作为一个非常重要的说明，`List` 上的任何方法都不会改变列表。 +> 它们都以函数式风格工作，这意味着它们返回带有修改结果的新集合。 + +## 常用方法示例 + +为了让您大致了解在后面章节中将看到的内容，这些示例展示了一些最常用的集合方法。 +首先，这里有一些不使用 lambda 的方法： + +{% tabs common-method-examples %} +{% tab 'Scala 2 and 3' %} +```scala +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) + +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.intersect(List(19,20,21)) // List(20) +a.last // 10 +a.lastOption // Some(10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +``` +{% endtab %} +{% endtabs %} + +### 高阶函数和 lambda + +接下来，我们将展示一些常用的接受 lambda（匿名函数）的高阶函数 (HOF)。 +首先，这里有几个 lambda 语法的变体，从最长的形式开始，逐步过渡最简洁的形式： + +{% tabs higher-order-functions-example %} +{% tab 'Scala 2 and 3' %} +```scala +// these functions are all equivalent and return +// the same data: List(10, 20, 10) + +a.filter((i: Int) => i < 25) // 1. most explicit form +a.filter((i) => i < 25) // 2. `Int` is not required +a.filter(i => i < 25) // 3. the parens are not required +a.filter(_ < 25) // 4. `i` is not required +``` +{% endtab %} +{% endtabs %} + +在那些编号的例子中： + +1. 第一个例子显示了最长的形式。 + _很少_需要这么多的冗长，并且只在最复杂的用法中需要。 +2. 编译器知道 `a` 包含 `Int`，所以这里没有必要重述。 +3. 只有一个参数时不需要括号，例如`i`。 +4. 当你有一个参数并且它在你的匿名函数中只出现一次时，你可以用 `_` 替换参数。 + +[匿名函数][lambdas] 提供了与缩短 lambda 表达式相关的规则的更多详细信息和示例。 + +现在您已经看到了简洁的形式，下面是使用短形式 lambda 语法的其他 HOF 的示例： + +{% tabs anonymous-functions-example %} +{% tab 'Scala 2 and 3' %} +```scala +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ > 100) // List() +a.filterNot(_ < 25) // List(30, 40) +a.find(_ > 20) // Some(30) +a.takeWhile(_ < 30) // List(10, 20) +``` +{% endtab %} +{% endtabs %} + +值得注意的是，HOF 也接受方法和函数作为参数——不仅仅是 lambda 表达式。 +下面是一些使用名为 `double` 的方法的`map` HOF 示例。 +再次显示了 lambda 语法的几种变体： + +{% tabs method-as-parameter-example %} +{% tab 'Scala 2 and 3' %} +```scala +def double(i: Int) = i * 2 + +// these all return `List(20, 40, 60, 80, 20)` +a.map(i => double(i)) +a.map(double(_)) +a.map(double) +``` +{% endtab %} +{% endtabs %} + +在最后一个示例中，当匿名函数由一个接受单个参数的函数调用组成时，您不必命名参数，因此甚至不需要 `_`。 + +最后，您可以根据需要组合 HOF 来解决问题： + +{% tabs higher-order-functions-combination-example %} +{% tab 'Scala 2 and 3' %} +```scala +// yields `List(100, 200)` +a.filter(_ < 40) + .takeWhile(_ < 30) + .map(_ * 10) +``` +{% endtab %} +{% endtabs %} + +## 例子数据 + +以下部分中的示例使用这些列表： + +{% tabs sample-data %} +{% tab 'Scala 2 and 3' %} +```scala +val oneToTen = (1 to 10).toList +val names = List("adam", "brandy", "chris", "david") +``` +{% endtab %} +{% endtabs %} + +## `map` + +`map` 方法遍历现有列表中的每个元素，将您提供的函数应用于每个元素，一次一个； +然后它返回一个包含所有修改元素的新列表。 + +这是一个将 `map` 方法应用于 `oneToTen` 列表的示例： + +{% tabs map-example %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val doubles = oneToTen.map(_ * 2) +doubles: List[Int] = List(2, 4, 6, 8, 10, 12, 14, 16, 18, 20) +``` +{% endtab %} +{% endtabs %} + +您还可以使用长格式编写匿名函数，如下所示： + +{% tabs map-example-anonymous %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val doubles = oneToTen.map(i => i * 2) +doubles: List[Int] = List(2, 4, 6, 8, 10, 12, 14, 16, 18, 20) +``` +{% endtab %} +{% endtabs %} + +但是，在本课中，我们将始终使用第一种较短的形式。 + +以下是更多应用于 `oneToTen` 和 `names` 列表的 `map` 方法的示例： + +{% tabs few-more-examples %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val capNames = names.map(_.capitalize) +capNames: List[String] = List(Adam, Brandy, Chris, David) + +scala> val nameLengthsMap = names.map(s => (s, s.length)).toMap +nameLengthsMap: Map[String, Int] = Map(adam -> 4, brandy -> 6, chris -> 5, david -> 5) + +scala> val isLessThanFive = oneToTen.map(_ < 5) +isLessThanFive: List[Boolean] = List(true, true, true, true, false, false, false, false, false, false) +``` +{% endtab %} +{% endtabs %} + +如最后两个示例所示，使用 `map` 返回与原始类型不同类型的集合是完全合法的（并且很常见）。 + +## `filter` + +`filter` 方法创建一个新列表，其中包含满足所提供谓词的元素。 +谓词或条件是返回 `Boolean`（`true` 或 `false`）的函数。 +这里有一些例子： + +{% tabs filter-example %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val lessThanFive = oneToTen.filter(_ < 5) +lessThanFive: List[Int] = List(1, 2, 3, 4) + +scala> val evens = oneToTen.filter(_ % 2 == 0) +evens: List[Int] = List(2, 4, 6, 8, 10) + +scala> val shortNames = names.filter(_.length <= 4) +shortNames: List[String] = List(adam) +``` +{% endtab %} +{% endtabs %} + +集合上的函数式方法的一个优点是您可以将它们链接在一起以解决问题。 +例如，这个例子展示了如何链接 `filter` 和 `map`： + +{% tabs filter-example-anonymous %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.filter(_ < 4).map(_ * 10) +``` +{% endtab %} +{% endtabs %} + +REPL 显示结果： + +{% tabs filter-example-anonymous-repl %} +{% tab 'Scala 2 and 3' %} +```scala +scala> oneToTen.filter(_ < 4).map(_ * 10) +val res1: List[Int] = List(10, 20, 30) +``` +{% endtab %} +{% endtabs %} + +## `foreach` + +`foreach` 方法用于遍历集合中的所有元素。 +请注意，`foreach` 用于副作用，例如打印信息。 +这是一个带有 `names` 列表的示例： + +{% tabs foreach-example %} +{% tab 'Scala 2 and 3' %} +```scala +scala> names.foreach(println) +adam +brandy +chris +david +``` +{% endtab %} +{% endtabs %} + +## `head` + +`head` 方法来自 Lisp 和其他早期的函数式编程语言。 +它用于访问列表的第一个元素（头元素）： + +{% tabs head-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.head // 1 +names.head // adam +``` +{% endtab %} +{% endtabs %} + +因为 `String` 可以看作是一个字符序列，所以你也可以把它当作一个列表。 +这就是 `head` 在这些字符串上的工作方式： + +{% tabs string-head-example %} +{% tab 'Scala 2 and 3' %} +```scala +"foo".head // 'f' +"bar".head // 'b' +``` +{% endtab %} +{% endtabs %} + +`head` 是一个很好的方法，但需要注意的是，在空集合上调用它时也会抛出异常： + +{% tabs head-error-example %} +{% tab 'Scala 2 and 3' %} +```scala +val emptyList = List[Int]() // emptyList: List[Int] = List() +emptyList.head // java.util.NoSuchElementException: head of empty list +``` +{% endtab %} +{% endtabs %} + +因此，您可能希望使用 `headOption` 而不是 `head`，尤其是在以函数式编程时： + +{% tabs head-option-example %} +{% tab 'Scala 2 and 3' %} +```scala +emptyList.headOption // None +``` +{% endtab %} +{% endtabs %} + +如图所示，它不会抛出异常，它只是返回值为 `None` 的类型 `Option`。 +您可以在 [函数式编程][fp-intro] 章节中了解有关这种编程风格的更多信息。 + +## `tail` + +`tail` 方法也来自 Lisp，它用于打印列表头元素之后的每个元素。 +几个例子展示了这一点： + +{% tabs tail-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.head // 1 +oneToTen.tail // List(2, 3, 4, 5, 6, 7, 8, 9, 10) + +names.head // adam +names.tail // List(brandy, chris, david) +``` +{% endtab %} +{% endtabs %} + +就像 `head` 一样，`tail` 也适用于字符串： + +{% tabs string-tail-example %} +{% tab 'Scala 2 and 3' %} +```scala +"foo".tail // "oo" +"bar".tail // "ar" +``` +{% endtab %} +{% endtabs %} + +如果列表为空，`tail` 会抛出 _java.lang.UnsupportedOperationException_，所以就像 `head` 和 `headOption` 一样，还有一个 `tailOption` 方法，这是函数式编程的首选方法。 + +也可以匹配一个列表，因此您可以编写如下表达式： + +{% tabs tail-match-example %} +{% tab 'Scala 2 and 3' %} +```scala +val x :: xs = names +``` +{% endtab %} +{% endtabs %} + +将该代码放在 REPL 中显示 `x` 分配给列表的头部，而 `xs` 分配给列表尾部： + +{% tabs tail-match-example-repl %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val x :: xs = names +val x: String = adam +val xs: List[String] = List(brandy, chris, david) +``` +{% endtab %} +{% endtabs %} + +像这样的模式匹配在许多情况下都很有用，例如使用递归编写一个 `sum` 方法： + +{% tabs tail-match-sum-example class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def sum(list: List[Int]): Int = list match { + case Nil => 0 + case x :: xs => x + sum(xs) +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def sum(list: List[Int]): Int = list match + case Nil => 0 + case x :: xs => x + sum(xs) +``` +{% endtab %} +{% endtabs %} + +## `take`、`takeRight`、`takeWhile` + +`take`、`takeRight` 和 `takeWhile` 方法为您提供了一种从列表中“获取”要用于创建新列表的元素的好方法。 +这是 `take` 和 `takeRight`： + +{% tabs take-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.take(1) // List(1) +oneToTen.take(2) // List(1, 2) + +oneToTen.takeRight(1) // List(10) +oneToTen.takeRight(2) // List(9, 10) +``` +{% endtab %} +{% endtabs %} + +注意这些方法是如何处理“临界”情况的，当我们要求比序列中更多的元素，或者要求零元素的时候： + +{% tabs take-edge-cases-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.take(Int.MaxValue) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.takeRight(Int.MaxValue) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.take(0) // List() +oneToTen.takeRight(0) // List() +``` +{% endtab %} +{% endtabs %} + +这是`takeWhile`，它与谓词函数一起使用： + +{% tabs take-while-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.takeWhile(_ < 5) // List(1, 2, 3, 4) +names.takeWhile(_.length < 5) // List(adam) +``` +{% endtab %} +{% endtabs %} + +## `drop`、`dropRight`、`dropWhile` + +`drop`、`dropRight` 和 `dropWhile` 本质上与它们对应的“取”相反，从列表中删除元素。 +这里有些例子： + +{% tabs drop-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.drop(1) // List(2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.drop(5) // List(6, 7, 8, 9, 10) + +oneToTen.dropRight(8) // List(1, 2) +oneToTen.dropRight(7) // List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +再次注意这些方法如何处理临界情况： + +{% tabs drop-edge-cases-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.drop(Int.MaxValue) // List() +oneToTen.dropRight(Int.MaxValue) // List() +oneToTen.drop(0) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +oneToTen.dropRight(0) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +``` +{% endtab %} +{% endtabs %} + +这是 `dropWhile`，它与谓词函数一起使用： + +{% tabs drop-while-example %} +{% tab 'Scala 2 and 3' %} +```scala +oneToTen.dropWhile(_ < 5) // List(5, 6, 7, 8, 9, 10) +names.dropWhile(_ != "chris") // List(chris, david) +``` +{% endtab %} +{% endtabs %} + +## `reduce` + +当您听到 “map reduce” 术语时，“reduce” 部分指的是诸如 `reduce` 之类的方法。 +它接受一个函数（或匿名函数）并将该函数应用于列表中的连续元素。 + +解释 `reduce` 的最好方法是创建一个可以传递给它的小辅助方法。 +例如，这是一个将两个整数相加的 `add` 方法，还为我们提供了一些不错的调试输出： + +{% tabs reduce-example class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def add(x: Int, y: Int): Int = { + val theSum = x + y + println(s"received $x and $y, their sum is $theSum") + theSum +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def add(x: Int, y: Int): Int = + val theSum = x + y + println(s"received $x and $y, their sum is $theSum") + theSum +``` +{% endtab %} +{% endtabs %} + +有上面的方法和下面的列表： + +{% tabs reduce-example-init %} +{% tab 'Scala 2 and 3' %} +```scala +val a = List(1,2,3,4) +``` +{% endtab %} +{% endtabs %} + +这就是将 `add` 方法传递给 `reduce` 时发生的情况： + +{% tabs reduce-example-evaluation %} +{% tab 'Scala 2 and 3' %} +```scala +scala> a.reduce(add) +received 1 and 2, their sum is 3 +received 3 and 3, their sum is 6 +received 6 and 4, their sum is 10 +res0: Int = 10 +``` +{% endtab %} +{% endtabs %} + +如该结果所示，`reduce` 使用`add` 将列表 `a` 归约为单个值，在这种情况下，是列表中整数的总和。 + +一旦你习惯了 `reduce`，你会写一个像这样的“求和”算法： + +{% tabs reduce-example-sum %} +{% tab 'Scala 2 and 3' %} +```scala +scala> a.reduce(_ + _) +res0: Int = 10 +``` +{% endtab %} +{% endtabs %} + +类似地，“连乘”算法如下所示： + +{% tabs reduce-example-multiply %} +{% tab 'Scala 2 and 3' %} +```scala +scala> a.reduce(_ * _) +res1: Int = 24 +``` +{% endtab %} +{% endtabs %} + +> 关于 `reduce` 的一个重要概念是——顾名思义——它用于将集合_归约_为单个值。 + +## 更多 + +在 Scala 集合类型上确实有几十个额外的方法，可以让你不再需要编写另一个 `for` 循环。有关 Scala 集合的更多详细信息，请参阅[可变和不可变集合][mut-immut-colls]和[Scala集合的架构][architecture]。 + +> 最后一点，如果您在 Scala 项目中使用 Java 代码，您可以将 Java 集合转换为 Scala 集合。 +> 通过这样做，您可以在 `for` 表达式中使用这些集合，还可以利用 Scala 的函数式集合方法。 +> 请参阅 [与 Java 交互][interacting] 部分了解更多详细信息。 + +[interacting]: {% link _zh-cn/overviews/scala3-book/interacting-with-java.md %} +[lambdas]: {% link _zh-cn/overviews/scala3-book/fun-anonymous-functions.md %} +[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %} +[mut-immut-colls]: {% link _overviews/collections-2.13/overview.md %} +[architecture]: {% link _overviews/core/architecture-of-scala-213-collections.md %} + diff --git a/_zh-cn/overviews/scala3-book/collections-summary.md b/_zh-cn/overviews/scala3-book/collections-summary.md new file mode 100644 index 0000000000..8a0c958712 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/collections-summary.md @@ -0,0 +1,37 @@ +--- +title: 总结 +type: section +description: This page provides a summary of the Collections chapter. +language: zh-cn +num: 40 +previous-page: collections-methods +next-page: fp-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章总结了常见的 Scala 3 集合及其附带的方法。 +如图所示，Scala 带有丰富的集合和方法。 + +当您需要查看本章中显示的集合类型的更多详细信息时，请参阅他们的 Scaladoc 页面： + +- [List](https://www.scala-lang.org/api/current/scala/collection/immutable/List.html) +- [Vector](https://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html) +- [ArrayBuffer](https://www.scala-lang.org/api/current/scala/collection/mutable/ArrayBuffer.html) +- [Range](https://www.scala-lang.org/api/current/scala/collection/immutable/Range.html) + +也提到了不可变的 `Map` 和 `Set`: + +- [Map](https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html) +- [Set](https://www.scala-lang.org/api/current/scala/collection/immutable/Set.html) + +和可变的 `Map` 和 `Set`: + +- [Map](https://www.scala-lang.org/api/current/scala/collection/mutable/Map.html) +- [Set](https://www.scala-lang.org/api/current/scala/collection/mutable/Set.html) + + diff --git a/_zh-cn/overviews/scala3-book/concurrency.md b/_zh-cn/overviews/scala3-book/concurrency.md new file mode 100644 index 0000000000..169e1f1684 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/concurrency.md @@ -0,0 +1,315 @@ +--- +title: 并发 +type: chapter +description: This page discusses how Scala concurrency works, with an emphasis on Scala Futures. +language: zh-cn +num: 68 +previous-page: ca-summary +next-page: scala-tools + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +当您想在 Scala 中编写并行和并发应用程序时，您_可以_使用原生 Java `Thread` --- 但 Scala [Future](https://www.scala-lang.org/api/current/scala/concurrent/Future$.html) 提供了一种更高级和惯用的方法，因此它是首选，本章将对此进行介绍。 + +## 介绍 + +以下是 Scaladoc 中对 Scala `Future` 的描述： + +> “ `Future` 代表一个值，它可能_当前_可用或不可用，但在某个时候可用，或者如果该值不能可用，则表示为异常。” + +为了演示这意味着什么，让我们首先看一下单线程编程。 +在单线程世界中，您将方法调用的结果绑定到如下变量： + +```scala +def aShortRunningTask(): Int = 42 +val x = aShortRunningTask() +``` + +在此代码中，值 `42` 立即绑定到 `x`。 + +当您使用 `Future` 时，分配过程看起来很相似： + +```scala +def aLongRunningTask(): Future[Int] = ??? +val x = aLongRunningTask() +``` + +但在这种情况下的主要区别在于，因为 `aLongRunningTask` 需要不确定的时间才能返回，所以 `x` 中的值可能_当前_可用也可能不可用，但它会在某个时候可用——在未来. + +另一种看待这个问题的方法是阻塞。 +在这个单线程示例中，在 `aShortRunningTask` 完成之前不会打印 `println` 语句： + +```scala +def aShortRunningTask(): Int = + Thread.sleep(500) + 42 +val x = aShortRunningTask() +println("Here") +``` + +相反，如果 `aShortRunningTask` 被创建为 `Future`，`println` 语句几乎立即被打印，因为 `aShortRunningTask` 是在其他线程上产生的——它不会阻塞。 + +在本章中，您将看到如何使用 futures，包括如何并行运行多个 future 并将它们的结果组合到一个 `for` 表达式中。 +您还将看到一些例子，在这些例子中，有些方法用于处理在返回的 future 中的值。 + +> 当你考虑 future 时，重要的是要知道它们是一次性的，“在其他线程上处理这个相对较慢的计算，完成后给把结果通知我”的结构。 +> 作为对比，[Akka](https://akka.io) Actor 旨在运行很长时间，并在其生命周期内响应许多请求。 +> 虽然 actor可能永远活着，但 future 最终会包含只运行一次的计算结果。 + +## REPL 中的一个例子 + +future 用于创建一个临时的并发包。 +例如，当您需要调用运行不确定时间的算法时---例如调用远程微服务---您使用 future---因此您希望在主线程之外运行它。 + +为了演示它是如何工作的，让我们从 REPL 中的 `Future` 示例开始。 +首先，粘贴这些必需的 `import` 语句： + +```scala +import scala.concurrent.Future +import scala.concurrent.ExecutionContext.Implicits.global +import scala.util.{Failure, Success} +``` + +现在您已准备好创造 future 。 +对于这个例子，首先定义一个长时间运行的单线程算法： + +```scala +def longRunningAlgorithm() = + Thread.sleep(10_000) + 42 +``` + +这种奇特的算法在十秒延迟后返回整数值`42`。 +现在通过将其包装到 `Future` 构造函数中来调用该算法，并将结果分配给一个变量： + +```scala +scala> val eventualInt = Future(longRunningAlgorithm()) +eventualInt: scala.concurrent.Future[Int] = Future() +``` + +马上，您的计算——对 `longRunningAlgorithm()` 的调用——开始运行。 +如果你立即检查变量 `eventualInt` 的值，你会看到 future 还没有完成： + +```scala +scala> eventualInt +val res1: scala.concurrent.Future[Int] = Future() +``` + +但是如果你在十秒后再次检查，你会看到它已经成功完成了： + +```scala +scala> eventualInt +val res2: scala.concurrent.Future[Int] = Future(Success(42)) +``` + +虽然这是一个相对简单的示例，但它显示了基本方法：只需使用您的长时间运行的算法构建一个新的 `Future`。 + +需要注意的一点是，您期望的 `42` 被包裹在 `Success` 中，而后者又被包裹在 `Future` 中。 +这是一个需要理解的关键概念：`Future` 中的值始终是`scala.util.Try` 类型之一的实例：`Success` 或 `Failure`。 +因此，当您处理 future 的结果时，您使用通常的 `Try` 处理技术。 + +### 将 `map` 与 future 一起使用 + +`Future` 有一个 `map` 方法，你可以像使用集合中的 `map` 方法一样使用它。 +这是在创建变量 `f` 后立即调用 `map` 时的结果： + +```scala +scala> val a = eventualInt.map(_ * 2) +a: scala.concurrent.Future[Int] = Future() +``` + +如图所示，对于使用 `longRunningAlgorithm` 创建的 future ，初始输出显示 `Future()`。 +但是当你在十秒后检查 `a` 的值时，你会看到它包含 `84` 的预期结果： + +```scala +scala> a +res1: scala.concurrent.Future[Int] = Future(Success(84)) +``` + +再一次，成功的结果被包裹在 `Success` 和 `Future` 中。 + +### 在 future 中使用回调方法 + +除了像`map`这样的高阶函数，你还可以使用回调方法和futures。 +一种常用的回调方法是 `onComplete`，它采用*偏函数*，您可以在其中处理 `Success` 和 `Failure` 情况： + +```scala +eventualInt.onComplete { + case Success(value) => println(s"Got the callback，value = $value") + case Failure(e) => e.printStackTrace +} +``` + +当您将该代码粘贴到 REPL 中时，您最终会看到结果： + +```scala +Got the callback, value = 42 +``` + +## 其他 future 方法 + +`Future` 类还有其他可以使用的方法。 +它具有您在 Scala 集合类中找到的一些方法，包括： + +- `filter` +- `flatMap` +- `map` + +它的回调方法有： + +- `onComplete` +- `andThen` +- `foreach` + +其他转换方法包括： + +- `fallbackTo` +- `recover` +- `recoverWith` + +请参阅 [Futures and Promises][futures] 页面，了解有关 future 可用的其他方法的讨论。 + +## 运行多个 future 并加入他们的结果 + +要并行运行多个计算并在所有 future 完成后加入它们的结果，请使用 “for” 表达式。 + +正确的做法是： + +1. 开始计算返回 `Future` 结果 +2. 将他们的结果合并到一个 `for` 表达式中 +3. 使用 `onComplete` 或类似技术提取合并结果 + +### 一个例子 + +以下示例显示了正确方法的三个步骤。 +一个关键是你首先开始计算返回 future ，然后将它们加入到 `for` 表达式中： + +```scala +import scala.concurrent.Future +import scala.concurrent.ExecutionContext.Implicits.global +import scala.util.{Failure, Success} + +val startTime = System.currentTimeMillis() +def delta() = System.currentTimeMillis() - startTime +def sleep(millis: Long) = Thread.sleep(millis) + +@main def multipleFutures1 = + + println(s"creating the futures: ${delta()}") + + // (1) start the computations that return futures + val f1 = Future { sleep(800); 1 } // eventually returns 1 + val f2 = Future { sleep(200); 2 } // eventually returns 2 + val f3 = Future { sleep(400); 3 } // eventually returns 3 + + // (2) join the futures in a `for` expression + val result = + for + r1 <- f1 + r2 <- f2 + r3 <- f3 + yield + println(s"in the 'yield': ${delta()}") + (r1 + r2 + r3) + + // (3) process the result + result.onComplete { + case Success(x) => + println(s"in the Success case: ${delta()}") + println(s"result = $x") + case Failure(e) => + e.printStackTrace + } + + println(s"before the 'sleep(3000)': ${delta()}") + + // important for a little parallel demo: keep the jvm alive + sleep(3000) +``` + +当您运行该应用程序时，您会看到如下所示的输出： + +```` +creating the futures: 1 +before the 'sleep(3000)': 2 +in the 'yield': 806 +in the Success case: 806 +result = 6 +```` + +如该输出所示， future 的创建速度非常快，仅在两毫秒内就到达了方法末尾的 `sleep(3000)` 语句之前的打印语句。 +所有这些代码都在 JVM 的主线程上运行。 +然后，在 806 毫秒，三个 future 完成并运行 `yield` 块中的代码。 +然后代码立即转到 `onComplete` 方法中的 `Success` 分支。 + +806 毫秒的输出是看到三个计算并行运行的关键。 +如果它们按顺序运行，总时间约为 1,400 毫秒——三个计算的睡眠时间之和。 +但是因为它们是并行运行的，所以总时间只比运行时间最长的计算：`f1`，即 800 毫秒，稍长。 + +> 请注意，如果计算是在 `for` 表达式中运行的，它们 +> 将按顺序执行，而不是并行执行： +> ~~~ +> // Sequential execution (no parallelism!) +> for +> r1 <- Future { sleep(800); 1 } +> r2 <- Future { sleep(200); 2 } +> r3 <- Future { sleep(400); 3 } +> yield +> r1 + r2 + r3 +> ~~~ +> 因此，如果您希望计算可能并行运行，请记住 +> 在 `for` 表达式之外运行它们。 + +### 一个返回 future 的方法 + +到目前为止，您已经了解了如何将单线程算法传递给 `Future` 构造函数。 +您可以使用相同的技术来创建一个返回 `Future` 的方法： + +```scala +// simulate a slow-running method +def slowlyDouble(x: Int, delay: Long): Future[Int] = Future { + sleep(delay) + x * 2 +} +``` + +与前面的示例一样，只需将方法调用的结果分配给一个新变量。 +然后当你立刻检查结果时，你会看到它没有完成，但是在延迟时间之后，future 会有一个结果： + +```` +scala> val f = slowlyDouble(2, 5_000L) +val f: concurrent.Future[Int] = Future() + +scala> f +val res0: concurrent.Future[Int] = Future() + +scala> f +val res1: concurrent.Future[Int] = Future(Success(4)) +```` + +## 关于 future 的要点 + +希望这些示例能让您了解 Scala future 是如何工作的。 +总而言之，关于 future 的几个关键点是： + +- 您构建 future 以在主线程之外运行任务 +- Futures 用于一次性的、可能长时间运行的并发任务，这些任务*最终*返回一个值；他们创造了一个临时的并发的容器 +- 一旦你构建了 future，它就会开始运行 +- future 相对于线程的一个好处是它们可以使用 `for` 表达式，并带有各种回调方法，可以简化使用并发线程的过程 +- 当您使用 future 时，您不必关心线程管理的低级细节 +- 您可以使用 `onComplete` 和 `andThen` 之类的回调方法或 `filter`、`map` 等转换方法来处理 future 的结果。 +- `Future` 中的值始终是 `Try` 类型之一的实例：`Success` 或 `Failure` +- 如果您使用多个 future 来产生一个结果，请将它们组合在一个 `for` 表达式中 + +此外，正如您在这些示例中看到的 `import` 语句，Scala `Future` 依赖于 `ExecutionContext`。 + +有关 future 的更多详细信息，请参阅[Future 和 Promises][future]，这是一篇讨论 future 、promises 和 ExecutionContext 的文章。 +它还讨论了如何将 `for` 表达式转换为 `flatMap` 操作。 + + +[futures]: {% link _overviews/core/futures.md %} diff --git a/_zh-cn/overviews/scala3-book/control-structures.md b/_zh-cn/overviews/scala3-book/control-structures.md new file mode 100644 index 0000000000..fa46f25a2c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/control-structures.md @@ -0,0 +1,1120 @@ +--- +title: 控制结构 +type: chapter +description: This page provides an introduction to Scala's control structures, including if/then/else, 'for' loops, 'for' expressions, 'match' expressions, try/catch/finally, and 'while' loops. +language: zh-cn +num: 19 +previous-page: string-interpolation +next-page: domain-modeling-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala具有您希望在编程语言中找到的控制结构，包括： + +- `if`/`then`/`else` +- `for` 循环 +- `while` 循环 +- `try`/`catch`/`finally` + +它还具有另外两个您可能以前从未见过的强大结构，具体取决于您的编程背景： + +- `for` 表达式（也被称作 _`for` comprehensions_） +- `match` 表达式 + +这些都将在以下各节中进行演示。 + +## if/then/else 结构 + +单行 Scala `if` 语句像这样： + +{% tabs control-structures-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-1 %} + +```scala +if (x == 1) println(x) +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-1 %} + +```scala +if x == 1 then println(x) +``` + +{% endtab %} +{% endtabs %} + +如果要在 `if` 比较后运行多行代码，用这个语法： + +{% tabs control-structures-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-2 %} + +```scala +if (x == 1) { + println("x is 1, as you can see:") + println(x) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-2 %} + +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +``` + +{% endtab %} +{% endtabs %} + +`if`/`else` 语法像这样： + +{% tabs control-structures-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-3 %} + +```scala +if (x == 1) { + println("x is 1, as you can see:") + println(x) +} else { + println("x was not 1") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-3 %} + +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +else + println("x was not 1") +``` + +{% endtab %} +{% endtabs %} + +这是 `if`/`else if`/`else` 语法： + +{% tabs control-structures-4 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-4 %} + +```scala +if (x < 0) + println("negative") +else if (x == 0) + println("zero") +else + println("positive") +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-4 %} + +```scala +if x < 0 then + println("negative") +else if x == 0 then + println("zero") +else + println("positive") +``` + +{% endtab %} +{% endtabs %} + +### `end if` 语句 + +
            +  这是 Scala 3 里的新东西，在 Scala 2 里不支持。 +
            + +如果您愿意，可以选择在每个表达式的末尾包含 `end if` 语句： + +{% tabs control-structures-5 %} +{% tab 'Scala 3 Only' %} + +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +end if +``` + +{% endtab %} +{% endtabs %} + +### `if`/`else` 表达式总是有返回值 + +请注意， `if` / `else` 比较形式为 _表达式_，这意味着它们返回一个可以分配给变量的值。 +因此，不需要特殊的三元运算符： + +{% tabs control-structures-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-6 %} + +```scala +val minValue = if (a < b) a else b +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-6 %} + +```scala +val minValue = if a < b then a else b +``` + +{% endtab %} +{% endtabs %} + +由于它们返回一个值，因此可以使用 `if`/`else` 表达式作为方法的主体： + +{% tabs control-structures-7 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-7 %} + +```scala +def compare(a: Int, b: Int): Int = + if (a < b) + -1 + else if (a == b) + 0 + else + 1 +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-7 %} + +```scala +def compare(a: Int, b: Int): Int = + if a < b then + -1 + else if a == b then + 0 + else + 1 +``` + +{% endtab %} +{% endtabs %} + +### 题外话：面向表达式的编程 + +作为一般编程的简要说明，当您编写的每个表达式都返回一个值时，该样式称为面向 _面向表达式的编程_ 或 EOP。 +例如，这是一个 _表达式_： + +{% tabs control-structures-8 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-8 %} + +```scala +val minValue = if (a < b) a else b +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-8 %} + +```scala +val minValue = if a < b then a else b +``` + +{% endtab %} +{% endtabs %} + +相反，不返回值的代码行称为 _语句_，用它们的 _副作用_。 +例如，这些代码行不返回值，因此用它们的副作用： + +{% tabs control-structures-9 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-9 %} + +```scala +if (a == b) action() +println("Hello") +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-9 %} + +```scala +if a == b then action() +println("Hello") +``` + +{% endtab %} +{% endtabs %} + +第一个示例在 `a` 等于 `b` 时将 `action` 方法作为副作用运行。 +第二个示例用于将字符串打印到 STDOUT 的副作用。 +随着你对Scala的了解越来越多，你会发现自己写的 _表达式_ 越来越多，_语句_ 也越来越少。 + +## `for` 循环 + +在最简单的用法中，Scala `for` 循环可用于迭代集合中的元素。 +例如，给定一个整数序列，您可以循环访问其元素并打印其值，如下所示： + +{% tabs control-structures-10 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-10 %} + +```scala +val ints = Seq(1, 2, 3) +for (i <- ints) println(i) +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-10 %} + +```scala +val ints = Seq(1, 2, 3) +for i <- ints do println(i) +``` + +{% endtab %} +{% endtabs %} + +代码 `i <- ints` 被称为 _生成器_。 + +这是在 Scala REPL 中的结果： + +{% tabs control-structures-11 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for (i <- ints) println(i) +1 +2 +3 +```` +{% endtab %} +{% tab 'Scala 3' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for i <- ints do println(i) +1 +2 +3 +```` + +{% endtab %} +{% endtabs %} + +如果需要在 `for` 生成器后面显示多行代码块，请使用以下语法：ddu + +{% tabs control-structures-12 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-12 %} + +```scala +for (i <- ints) { + val x = i * 2 + println(s"i = $i, x = $x") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-12 %} + +```scala +for + i <- ints +do + val x = i * 2 + println(s"i = $i, x = $x") +``` + +{% endtab %} +{% endtabs %} + +### 多生成器 + +`for` 循环可以有多个生成器，如以下示例所示： + +{% tabs control-structures-13 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-13 %} + +```scala +for { + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +} { + println(s"i = $i, j = $j, k = $k") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-13 %} + +```scala +for + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +do + println(s"i = $i, j = $j, k = $k") +``` + +{% endtab %} +{% endtabs %} + +那个表达式的输出： + +```` +i = 1, j = a, k = 1 +i = 1, j = a, k = 6 +i = 1, j = b, k = 1 +i = 1, j = b, k = 6 +i = 2, j = a, k = 1 +i = 2, j = a, k = 6 +i = 2, j = b, k = 1 +i = 2, j = b, k = 6 +```` + +### 守卫 + +`for` 循环也可以包含 `if` 语句，这些语句称为 _守卫_： + +{% tabs control-structures-14 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-14 %} + +```scala +for { + i <- 1 to 5 + if i % 2 == 0 +} { + println(i) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-14 %} + +```scala +for + i <- 1 to 5 + if i % 2 == 0 +do + println(i) +``` + +{% endtab %} +{% endtabs %} + +以上循环的输出是： + +```` +2 +4 +```` + +`for` 循环可以根据需要有任意数量的守卫。 +此示例显示了打印数字`4`的一种方法： + +{% tabs control-structures-15 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-15 %} + +```scala +for { + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +} { + println(i) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-15 %} + +```scala +for + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +do + println(i) +``` + +{% endtab %} +{% endtabs %} + +### 把 `for` 用在 `Map` 上 + +您还可以将 `for` 循环与 `Map` 一起使用。 +例如，给定州缩写及其全名的 `Map`： + +{% tabs map %} +{% tab 'Scala 2 and 3' for=map %} + +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AR" -> "Arizona" +) +``` + +{% endtab %} +{% endtabs %} + +您可以使用 `for` 打印键和值，如下所示： + +{% tabs control-structures-16 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-16 %} + +```scala +for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-16 %} + +```scala +for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +``` + +{% endtab %} +{% endtabs %} + +以下是 REPL 中的样子： + +{% tabs control-structures-17 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-17 %} + +```scala +scala> for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-17 %} + +```scala +scala> for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` + +{% endtab %} +{% endtabs %} + +当 `for` 循环遍历映射时，每个键/值对都绑定到变量 `abbrev` 和 `fullName` ，它们位于元组中： + +{% tabs tuple %} +{% tab 'Scala 2 and 3' for=tuple %} + +```scala +(abbrev, fullName) <- states +``` + +{% endtab %} +{% endtabs %} + +当循环运行时，变量 `abbrev` 被分配给映射中的当前 _键_，变量 `fullName` 被分配给当前map 的 _值_。 + +## `for` 表达式 + +在前面的 `for` 循环示例中，这些循环都用于 _副作用_，特别是使用 `println` 将这些值打印到STDOUT。 + +重要的是要知道，您还可以创建有返回值的 `for` _表达式_。 +您可以通过添加 `yield` 关键字和要返回的表达式来创建 `for` 表达式，如下所示： + +{% tabs control-structures-18 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-18 %} + +```scala +val list = + for (i <- 10 to 12) + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-18 %} + +```scala +val list = + for i <- 10 to 12 + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` + +{% endtab %} +{% endtabs %} + +在 `for` 表达式运行后，变量 `list` 是包含所示值的 `Vector` 。 +这是表达式的工作原理： + +1. `for` 表达式开始循环访问范围 `(10, 11, 12)` 中的值。 + 它首先处理值`10`，将其乘以`2`，然后 _产生_ 结果为`20`的值。 +2. 接下来，它处理`11`---该范围中的第二个值。 + 它乘以`2`，然后产生值`22`。 + 您可以将这些产生的值看作它们累积在某个临时位置。 +3. 最后，循环从范围中获取数字 `12`，将其乘以 `2`，得到数字 `24`。 + 循环此时完成并产生最终结果 `Vector(20, 22, 24)`。 + +{% comment %} +NOTE: This is a place where it would be great to have a TIP or NOTE block: +{% endcomment %} + +虽然本节的目的是演示 `for` 表达式，但它可以帮助知道显示的 `for` 表达式等效于以下 `map` 方法调用： + +{% tabs map-call %} +{% tab 'Scala 2 and 3' for=map-call %} + +```scala +val list = (10 to 12).map(i => i * 2) +``` + +{% endtab %} +{% endtabs %} + +只要您需要遍历集合中的所有元素，并将算法应用于这些元素以创建新列表，就可以使用 `for` 表达式。 + +下面是一个示例，演示如何在 `yield` 之后使用代码块： + +{% tabs control-structures-19 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-19 %} + +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for (name <- names) yield { + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName +} + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-19 %} + +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for name <- names yield + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` + +{% endtab %} +{% endtabs %} + +### 使用 `for` 表达式作为方法的主体 + +由于 `for` 表达式产生结果，因此可以将其用作返回有用值的方法的主体。 +此方法返回给定整数列表中介于`3`和`10`之间的所有值： + +{% tabs control-structures-20 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-20 %} + +```scala +def between3and10(xs: List[Int]): List[Int] = + for { + x <- xs + if x >= 3 + if x <= 10 + } yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-20 %} + +```scala +def between3and10(xs: List[Int]): List[Int] = + for + x <- xs + if x >= 3 + if x <= 10 + yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` + +{% endtab %} +{% endtabs %} + +## `while` 循环 + +Scala `while` 循环语法如下： + +{% tabs control-structures-21 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-21 %} + +```scala +var i = 0 + +while (i < 3) { + println(i) + i += 1 +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-21 %} + +```scala +var i = 0 + +while i < 3 do + println(i) + i += 1 +``` + +{% endtab %} +{% endtabs %} + +## `match` 表达式 + +模式匹配是函数式编程语言的一个主要特征，Scala包含一个具有许多功能的 `match` 表达式。 + +在最简单的情况下，您可以使用 `match` 表达式，象Java `switch` 语句，根据整数值匹配。 +请注意，这实际上是一个表达式，因为它计算出一个结果： + +{% tabs control-structures-22 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-22 %} + +```scala +// `i` is an integer +val day = i match { + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // the default, catch-all +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-22 %} + +```scala +import scala.annotation.switch + +// `i` is an integer +val day = i match + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // the default, catch-all +``` + +{% endtab %} +{% endtabs %} + +在此示例中，变量 `i` 根据所示情况进行测试。 +如果它介于`0`和`6`之间，则 `day` 绑定到一个字符串，该字符串表示一周中的某一天。 +否则，捕获所有情况，这些情况用 `_` 字符表示，这样 `day` 绑定到字符串 `"invalid day"`。 + +> 在编写像这样的简单 `match` 表达式时，建议在变量 `i` 上使用 `@switch` 注释。 +> 如果开关无法编译为 `tableswitch` 或 `lookupswitch`，则此注释会提供编译时警告，这个开关对性能更好。 + +### 使用缺省值 + +当您需要访问 `match` 表达式中匹配所有情况，也就是默认值时，只需在 `case` 语句的左侧提供一个变量名而不是 `_`，然后根据需要在语句的右侧使用该变量名称： + +{% tabs control-structures-23 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-23 %} + +```scala +i match { + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-23 %} + +```scala +i match + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what" ) +``` + +{% endtab %} +{% endtabs %} + +在模式中使用的名称必须以小写字母开头。 +以大写字母开头的名称并不引入变量，而是匹配该范围内的一个值： + +{% tabs control-structures-24 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-24 %} + +```scala +val N = 42 +i match { + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-24 %} + +```scala +val N = 42 +i match + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +``` + +{% endtab %} +{% endtabs %} + +如果 `i` 等于`42`，则 `case N` 将匹配，然后打印字符串`"42"`。它不会到达默认分支。 + +### 在一行上处理多个可能的匹配项 + +如前所述，`match` 表达式具有许多功能。 +此示例演示如何在每个 `case` 语句中使用多个可能的模式匹配： + +{% tabs control-structures-25 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-25 %} + +```scala +val evenOrOdd = i match { + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-25 %} + +```scala +val evenOrOdd = i match + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +``` + +{% endtab %} +{% endtabs %} + +### 在 `case` 子句中使用 `if` 守卫 + +您还可以在匹配表达式的 `case` 中使用守卫装置。 +在此示例中，第二个和第三个 `case` 都使用守卫来匹配多个整数值： + +{% tabs control-structures-26 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-26 %} + +```scala +i match { + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-26 %} + +```scala +i match + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +``` + +{% endtab %} +{% endtabs %} + +下面是另一个示例，它显示了如何将给定值与数字范围进行匹配： + +{% tabs control-structures-27 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-27 %} + +```scala +i match { + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-27 %} + +```scala +i match + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +``` + +{% endtab %} +{% endtabs %} + +#### 样例类和 match 表达式 + +您还可以从 `case` 类中提取字段 —— 以及正确编写了 `apply`/`unapply` 方法的类 —— 并在守卫条件下使用这些字段。 +下面是一个使用简单 `Person` 案例类的示例： + +{% tabs control-structures-28 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-28 %} + +```scala +case class Person(name: String) + +def speak(p: Person) = p match { + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") +} + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-28 %} + +```scala +case class Person(name: String) + +def speak(p: Person) = p match + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` + +{% endtab %} +{% endtabs %} + +### 使用 `match` 表达式作为方法的主体 + +由于 `match` 表达式返回一个值，因此它们可以用作方法的主体。 +此方法采用 `Matchable` 值作为输入参数，并根据 `match` 表达式的结果返回 `Boolean`： + +{% tabs control-structures-29 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-29 %} + +```scala +def isTruthy(a: Matchable) = a match { + case 0 | "" | false => false + case _ => true +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-29 %} + +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" | false => false + case _ => true +``` + +{% endtab %} +{% endtabs %} + +输入参数 `a` 被定义为 [`Matchable`类型][matchable]---这是可以对其执行模式匹配的所有Scala类型的根。 +该方法通过在输入上进行匹配来实现，提供两种情况： +第一个检查给定值是整数`0`，空字符串还是 `false`，在这种情况下返回 `false`。 +在默认情况下，我们为任何其他值返回 `true`。 +以下示例演示此方法的工作原理： + +{% tabs is-truthy-call %} +{% tab 'Scala 2 and 3' for=is-truthy-call %} + +```scala +isTruthy(0) // false +isTruthy(false) // false +isTruthy("") // false +isTruthy(1) // true +isTruthy(" ") // true +isTruthy(2F) // true +``` + +{% endtab %} +{% endtabs %} + +使用 `match` 表达式作为方法的主体是一种非常常见的用法。 + +#### 匹配表达式支持许多不同类型的模式 + +有许多不同形式的模式可用于编写 `match` 表达式。 +示例包括： + +- 常量模式（如 `case 3 => `） +- 序列模式（如 `case List(els : _*) =>`） +- 元组模式（如 `case (x, y) =>`） +- 构造函数模式（如 `case Person(first, last) =>`） +- 类型测试模式（如 `case p: Person =>`） + +所有这些类型的模式匹配都展示在以下 `pattern` 方法中，该方法采用类型为 `Matchable` 的输入参数并返回 `String` ： + +{% tabs control-structures-30 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-30 %} + +```scala +def pattern(x: Matchable): String = x match { + + // constant patterns + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // sequence patterns + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // tuple patterns + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // constructor patterns + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // type test patterns + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // the default wildcard pattern + case _ => "Unknown" +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-30 %} + +```scala +def pattern(x: Matchable): String = x match + + // constant patterns + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // sequence patterns + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // tuple patterns + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // constructor patterns + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // type test patterns + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // the default wildcard pattern + case _ => "Unknown" +``` + +{% endtab %} +{% endtabs %} + +{% comment %} +TODO: Add in the new Scala 3 syntax shown on this page: +http://dotty.epfl.ch/docs/reference/changed-features/match-syntax.html +{% endcomment %} + +## try/catch/finally + +与Java一样，Scala也有一个 `try`/`catch`/`finally` 结构，让你可以捕获和管理异常。 +为了保持一致性，Scala使用与 `match` 表达式相同的语法，并支持在可能发生的不同可能的异常上进行模式匹配。 + +在下面的示例中，`openAndReadAFile` 是一个执行其名称含义的方法：它打开一个文件并读取其中的文本，将结果分配给可变变量 `text` ： + +{% tabs control-structures-31 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-31 %} + +```scala +var text = "" +try { + text = openAndReadAFile(filename) +} catch { + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +} finally { + // close your resources here + println("Came to the 'finally' clause.") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-31 %} + +```scala +var text = "" +try + text = openAndReadAFile(filename) +catch + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +finally + // close your resources here + println("Came to the 'finally' clause.") +``` + +{% endtab %} +{% endtabs %} + +假设 `openAndReadAFile` 方法使用 Java `java.io.*` 类来读取文件并且不捕获其异常，则尝试打开和读取文件可能会导致 `FileNotFoundException` 和 `IOException` 异常，本例中，这两个异常在 `catch` 块中被捕获。 + +[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-fp.md b/_zh-cn/overviews/scala3-book/domain-modeling-fp.md new file mode 100644 index 0000000000..46797dfc7e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-fp.md @@ -0,0 +1,817 @@ +--- +title: 函数式领域建模 +type: section +description: This chapter provides an introduction to FP domain modeling with Scala 3. +language: zh-cn +num: 23 +previous-page: domain-modeling-oop +next-page: methods-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍了在 Scala 3 中使用函数式编程 (FP) 进行领域建模。 +当使用 FP 对我们周围的世界进行建模时，您通常会使用以下 Scala 构造： + +- 枚举 +- 样例类 +- Traits + +> 如果您不熟悉代数数据类型 (ADT) 及其泛型版本 (GADT)，您可能需要先阅读 [代数数据类型][adts] 部分，然后再阅读本节。 + +## 介绍 + +在 FP 中，*数据*和*对该数据的操作*是两个独立的东西；您不必像使用 OOP 那样将它们封装在一起。 + +这个概念类似于数值代数。 +当您考虑值大于或等于零的整数时，您有一*组*可能的值，如下所示： + +```` +0, 1, 2 ... Int.MaxValue +```` + +忽略整数的除法，对这些值可能的*操作*是： + +```` ++, -, * +```` + +FP设计以类似的方式实现： + +- 你描述你的值的集合（你的数据） +- 您描述了对这些值起作用的操作（您的函数） + +> 正如我们将看到的，这种风格的程序推理与面向对象的编程完全不同。 +> FP 中的数据只**是**： +> 将功能与数据分离，让您无需担心行为即可检查数据。 + +在本章中，我们将为披萨店中的“披萨”建模数据和操作。 +您将看到如何实现 Scala/FP 模型的“数据”部分，然后您将看到几种不同的方式来组织对该数据的操作。 + +## 数据建模 + +在 Scala 中，描述编程问题的数据模型很简单： + +- 如果您想使用不同的替代方案对数据进行建模，请使用 `enum` 结构，（或者在 Scala 2 中用 `case object`）。 +- 如果您只想对事物进行分组（或需要更细粒度的控制），请使用 样例类 + +### 描述替代方案 + +简单地由不同的选择组成的数据，如面饼大小、面饼类型和馅料，在 Scala 中使用枚举进行简洁的建模： + +{% tabs data_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_1 %} + +在 Scala 2 中，一个 `sealed class` 和若干个继承自该类的 `case object` 组合在一起来表示枚举： + +```scala +sealed abstract class CrustSize +object CrustSize { + case object Small extends CrustSize + case object Medium extends CrustSize + case object Large extends CrustSize +} + +sealed abstract class CrustType +object CrustType { + case object Thin extends CrustType + case object Thick extends CrustType + case object Regular extends CrustType +} + +sealed abstract class Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_1 %} + +在 Scala 3 中，用 `enum` 结构简洁地表示： + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +> 描述不同选择的数据类型（如 `CrustSize`）有时也称为_归纳类型_。 + +### 描述复合数据 + +可以将披萨饼视为上述不同属性的_组件_容器。 +我们可以使用 样例类来描述 `Pizza` 由 `crustSize`、`crustType` 和可能的多个 `Topping` 组成： + +{% tabs data_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_2 %} + +```scala +import CrustSize._ +import CrustType._ +import Topping._ + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% tab 'Scala 3' for=data_2 %} + +```scala +import CrustSize.* +import CrustType.* +import Topping.* + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% endtabs %} + +> 聚合多个组件的数据类型（如`Pizza`）有时也称为_乘积类型_。 + +就是这样。 +这就是 FP 式披萨系统的数据模型。 +该解决方案非常简洁，因为它不需要将披萨饼上的操作与数据模型相结合。 +数据模型易于阅读，就像声明关系数据库的设计一样。 +创建数据模型的值并检查它们也很容易： + +{% tabs data_3 %} +{% tab 'Scala 2 and 3' for=data_3 %} + +```scala +val myFavPizza = Pizza(Small, Regular, Seq(Cheese, Pepperoni)) +println(myFavPizza.crustType) // prints Regular +``` + +{% endtab %} +{% endtabs %} + +#### 更多数据模型 + +我们可能会以同样的方式对整个披萨订购系统进行建模。 +下面是一些用于对此类系统建模的其他 样例类： + +{% tabs data_4 %} +{% tab 'Scala 2 and 3' for=data_4 %} + +```scala +case class Address( + street1: String, + street2: Option[String], + city: String, + state: String, + zipCode: String +) + +case class Customer( + name: String, + phone: String, + address: Address +) + +case class Order( + pizzas: Seq[Pizza], + customer: Customer +) +``` + +{% endtab %} +{% endtabs %} + +#### “瘦领域对象（贫血模型）” + +Debasish Ghosh 在他的《*函数式和反应式领域建模*》一书中指出，OOP 从业者将他们的类描述为封装数据和行为的“富领域模型（充血模型）”，而 FP 数据模型可以被认为是“瘦领域对象”。 +这是因为——正如本课所示——数据模型被定义为具有属性但没有行为的样例类，从而产生了简短而简洁的数据结构。 + +## 操作建模 + +这就引出了一个有趣的问题：因为 FP 将数据与对该数据的操作分开，那么如何在 Scala 中实现这些操作？ + +答案实际上很简单：您只需编写对我们刚刚建模的数据值进行操作的函数（或方法）。 +例如，我们可以定义一个计算披萨价格的函数。 + +{% tabs data_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match { + case Pizza(crustSize, crustType, toppings) => { + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match + case Pizza(crustSize, crustType, toppings) => + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops +``` + +{% endtab %} +{% endtabs %} + +您注意到函数的实现如何简单地遵循数据的样式：由于 `Pizza` 是一个样例类，我们使用模式匹配来提取组件并调用辅助函数来计算各个部分单独的价格。 + +{% tabs data_6 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match { + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +``` + +{% endtab %} +{% endtabs %} + +同样，由于 `Topping` 是一个枚举，我们使用模式匹配来区分不同的变量。 +奶酪和洋葱的价格为 50ct，其余的价格为 75ct。 + +{% tabs data_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match { + // if the crust size is small or medium, + // the type is not important + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 + } +``` + +{% endtab %} +{% tab 'Scala 3' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match + // if the crust size is small or medium, + // the type is not important + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 +``` + +{% endtab %} +{% endtabs %} + +为了计算面饼的价格，我们同时对面饼的大小和类型进行模式匹配。 + +> 关于上面显示的所有函数的重要一点是它们是*纯函数*：它们不会改变任何数据或有其他副作用（如抛出异常或写入文件）。 +> 他们所做的只是简单地接收值并计算结果。 + +{% comment %} +I’ve added this comment per [this Github comment](https://github.com/scalacenter/docs.scala-lang/pull/3#discussion_r543372428). +To that point, I’ve added these definitions here from our Slack conversation, in case anyone wants to update the “pure function” definition. If not, please delete this comment. + +Sébastien: +---------- +A function `f` is pure if, given the same input `x`, it will always return the same output `f(x)`, and it never modifies any state outside of it (therefore potentially causing other functions to behave differently in the future). + +Jonathan: +--------- +We say a function is 'pure' if it does not depend on or modify the context it is called in. + +Wikipedia +--------- +The function always evaluates to the same result value given the same argument value(s). It cannot depend on any hidden state or value, and it cannot depend on any I/O. +Evaluation of the result does not cause any semantically observable side effect or output, such as mutation of mutable objects or output to I/O devices. + +Mine (Alvin, now modified, from fp-pure-functions.md): +------------------------------------------------------ +- A function `f` is pure if, given the same input `x`, it always returns the same output `f(x)` +- The function’s output depends *only* on its input variables and its internal algorithm +- It doesn’t modify its input parameters +- It doesn’t mutate any hidden state +- It doesn’t have any “back doors”: It doesn’t read data from the outside world (including the console, web services, databases, files, etc.), or write data to the outside world +{% endcomment %} + +## 如何组织功能 + +在实现上面的 `pizzaPrice` 函数时，我们没有说我们将在*哪里*定义它。 +在 Scala 3 中，在文件的顶层定义它是完全有效的。 +但是，该语言为我们提供了许多很棒的工具在不同命名空间和模块中组织我们的逻辑。 + +有几种不同的方式来实现和组织行为： + +- 在伴生对象中定义您的函数 +- 使用模块化编程风格 +- 使用“函数式对象”方法 +- 在扩展方法中定义功能 + +在本节的其余部分将展示这些不同的解决方案。 + +### 伴生对象 + +第一种方法是在伴生对象中定义行为——函数。 + +> 正如在领域建模 [工具部分][modeling-tools] 中所讨论的，_伴生对象_ 是一个与类同名的 `object` ，并在与类相同的文件中声明。 + +使用这种方法，除了枚举或样例类之外，您还定义了一个包含该行为的同名伴生对象。 + +{% tabs org_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// the companion object of case class Pizza +object Pizza { + // the implementation of `pizzaPrice` from above + def price(p: Pizza): Double = ... +} + +sealed abstract class Topping + +// the companion object of enumeration Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping + + // the implementation of `toppingPrice` above + def price(t: Topping): Double = ... +} +``` + +{% endtab %} +{% tab 'Scala 3' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// the companion object of case class Pizza +object Pizza: + // the implementation of `pizzaPrice` from above + def price(p: Pizza): Double = ... + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions + +// the companion object of enumeration Topping +object Topping: + // the implementation of `toppingPrice` above + def price(t: Topping): Double = t match + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +``` + +{% endtab %} +{% endtabs %} + +使用这种方法，您可以创建一个 `Pizza` 并计算其价格，如下所示： + +{% tabs org_2 %} +{% tab 'Scala 2 and 3' for=org_2 %} + +```scala +val pizza1 = Pizza(Small, Thin, Seq(Cheese, Onions)) +Pizza.price(pizza1) +``` + +{% endtab %} +{% endtabs %} + +以这种方式对功能进行分组有几个优点： + +- 它将功能与数据相关联，让程序员（和编译器）更容易找到它。 +- 它创建了一个命名空间，例如让我们使用 `price` 作为方法名称，而不必依赖重载。 +- `Topping.price` 的实现可以访问枚举值，例如 `Cheese` ，而无需导入它们。 + +但是，还应权衡： + +- 它将功能与您的数据模型紧密结合。 + 特别是，伴生对象需要在与您的样例类相同的文件中定义。 +- 可能不清楚在哪里定义像 `crustPrice` 这样同样可以放置在 `CrustSize` 或 `CrustType` 的伴生对象中的函数。 + +## 模块 + +组织行为的第二种方法是使用“模块化”方法。 +这本书，*Programming in Scala*，将 *模块* 定义为“具有良好定义的接口和隐藏实现的‘较小的程序片段’”。 +让我们看看这意味着什么。 + +### 创建一个 `PizzaService` 接口 + +首先要考虑的是 `Pizza` 的“行为”。 +执行此操作时，您可以像这样草拟一个 `PizzaServiceInterface` trait： + +{% tabs module_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_1 %} + +```scala +trait PizzaServiceInterface { + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +} +``` + +{% endtab %} +{% tab 'Scala 3' for=module_1 %} + +```scala +trait PizzaServiceInterface: + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +``` + +{% endtab %} +{% endtabs %} + +如图所示，每个方法都将 `Pizza` 作为输入参数——连同其他参数——然后返回一个 `Pizza` 实例作为结果 + +当你写一个像这样的纯接口时，你可以把它想象成一个约定，“所有扩展这个特性的非抽象类*必须*提供这些服务的实现。” + +此时您还可以做的是想象您是此 API 的使用者。 +当你这样做时，它有助于草拟一些示例“消费者”代码，以确保 API 看起来像你想要的： + +{% tabs module_2 %} +{% tab 'Scala 2 and 3' for=module_2 %} + +```scala +val p = Pizza(Small, Thin, Seq(Cheese)) + +// how you want to use the methods in PizzaServiceInterface +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) +``` + +{% endtab %} +{% endtabs %} + +如果该代码看起来没问题，您通常会开始草拟另一个 API ——例如用于订单的 API ——但由于我们现在只关注披萨饼，我们将停止考虑接口，然后创建这个接口的具体实现。 + +> 请注意，这通常是一个两步过程。 +> 在第一步中，您将 API 的合同草拟为*接口*。 +> 在第二步中，您创建该接口的具体*实现*。 +> 在某些情况下，您最终会创建基本接口的多个具体实现。 + +### 创建一个具体的实现 + +现在您知道了 `PizzaServiceInterface` 的样子，您可以通过为接口中定义的所有方法体来创建它的具体实现： + +{% tabs module_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface { + + def price(p: Pizza): Double = + ... // implementation from above + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface: + + def price(p: Pizza): Double = + ... // implementation from above + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) + +end PizzaService +``` + +{% endtab %} +{% endtabs %} + +虽然创建接口和实现的两步过程并不总是必要的，但明确考虑 API 及其使用是一种好方法。 + +一切就绪后，您可以使用 `Pizza` 类和 `PizzaService`： + +{% tabs module_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_4 %} + +```scala +import PizzaService._ + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// use the PizzaService methods +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // prints 8.75 +``` + +{% endtab %} +{% tab 'Scala 3' for=module_4 %} + +```scala +import PizzaService.* + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// use the PizzaService methods +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // prints 8.75 +``` + +{% endtab %} +{% endtabs %} + +### 函数对象 + +在 *Programming in Scala* 一书中，作者将术语“函数对象”定义为“不具有任何可变状态的对象”。 +`scala.collection.immutable` 中的类型也是如此。 +例如，`List` 上的方法不会改变内部状态，而是创建 `List` 的副本作为结果。 + +您可以将此方法视为“混合 FP/OOP 设计”，因为您： + +- 使用不可变的 样例类对数据进行建模。 +- 定义_同类型_数据中的行为（方法）。 +- 将行为实现为纯函数：它们不会改变任何内部状态；相反，他们返回一个副本。 + +> 这确实是一种混合方法：就像在 **OOP 设计**中一样，方法与数据一起封装在类中， +> 但作为典型的 **FP 设计**，方法被实现为纯函数，该函数不改变数据 + +#### 例子 + +使用这种方法，您可以在样例类中直接实现披萨上的功能： + +{% tabs module_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) { + + // the operations on the data model + def price: Double = + pizzaPrice(this) // implementation from above + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +): + + // the operations on the data model + def price: Double = + pizzaPrice(this) // implementation from above + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +``` + +{% endtab %} +{% endtabs %} + +请注意，与之前的方法不同，因为这些是 `Pizza` 类上的方法，它们不会将 `Pizza` 引用作为输入参数。 +相反，他们用 `this` 作为当前披萨实例的引用。 + +现在你可以像这样使用这个新设计： + +{% tabs module_6 %} +{% tab 'Scala 2 and 3' for=module_6 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +### 扩展方法 + +最后，我们展示了一种介于第一个（在伴生对象中定义函数）和最后一个（将函数定义为类型本身的方法）之间的方法。 + +扩展方法让我们创建一个类似于函数对象的 API，而不必将函数定义为类型本身的方法。 +这可以有多个优点： + +- 我们的数据模型再次_非常简洁_并且没有提及任何行为。 +- 我们可以_追溯性地_为类型配备额外的方法，而无需更改原始定义。 +- 除了伴生对象或类型上的直接方法外，扩展方法可以在_外部_另一个文件中定义。 + +让我们再次回顾一下我们的例子。 + +{% tabs module_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +implicit class PizzaOps(p: Pizza) { + def price: Double = + pizzaPrice(p) // implementation from above + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` +在上面的代码中，我们将披萨上的不同方法定义为_implicit class_。 +用 `implicit class PizzaOps(p: Pizza)`，不管什么时候导入 `PizzaOps`，它的方法在 `Pizza` 的实例上都是可用的。 +在本例中接收者是 `p`。 + +{% endtab %} +{% tab 'Scala 3' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +extension (p: Pizza) + def price: Double = + pizzaPrice(p) // implementation from above + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +``` +在上面的代码中，我们将披萨上的不同方法定义为_扩展方法_。 +对于 `extension (p: Pizza)`，我们想在 `Pizza` 的实例上让方法可用。在本例中接收者是 `p`。 + +{% endtab %} +{% endtabs %} + +使用扩展方法，我们可以获得和之前一样的 API： + +{% tabs module_8 %} +{% tab 'Scala 2 and 3' for=module_8 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +通常，如果您是数据模型的设计者，您将在伴生对象中定义您的扩展方法。 +这样，它们已经可供所有用户使用。 +否则，扩展方法需要显式导入才能使用。 + +## 这种方法的总结 + +在 Scala/FP 中定义数据模型往往很简单：只需使用枚举对数据的变体进行建模，并使用 样例类对复合数据进行建模。 +然后，为了对行为建模，定义对数据模型的值进行操作的函数。 +我们已经看到了组织函数的不同方法： + +- 你可以把你的方法放在伴生对象中 +- 您可以使用模块化编程风格，分离接口和实现 +- 您可以使用“函数对象”方法并将方法存储在定义的数据类型上 +- 您可以使用扩展方法把函数装配到数据模型上 + +[adts]: {% link _zh-cn/overviews/scala3-book/types-adts-gadts.md %} +[modeling-tools]: {% link _zh-cn/overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-intro.md b/_zh-cn/overviews/scala3-book/domain-modeling-intro.md new file mode 100644 index 0000000000..f2d91f71a3 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-intro.md @@ -0,0 +1,18 @@ +--- +title: 领域建模 +description: This chapter provides an introduction to domain modeling in Scala 3. +num: 20 +previous-page: control-structures +next-page: domain-modeling-tools + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +本章介绍如何使用 Scala 3 对周围的世界进行建模： + +- 工具部分介绍了可供您使用的工具，包括类、traits 、枚举等 +- OOP 建模部分着眼于面向对象编程 （OOP） 风格中的建模属性和行为 +- FP 建模部分以函数式编程 （FP） 风格来看领域建模 diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-oop.md b/_zh-cn/overviews/scala3-book/domain-modeling-oop.md new file mode 100644 index 0000000000..0c71a3f65c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-oop.md @@ -0,0 +1,588 @@ +--- +title: OOP 领域建模 +type: section +description: This chapter provides an introduction to OOP domain modeling with Scala 3. +language: zh-cn +num: 22 +previous-page: domain-modeling-tools +next-page: domain-modeling-fp + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍了在 Scala 3 中使用面向对象编程 (OOP) 进行领域建模。 + +## 介绍 + +Scala 为面向对象设计提供了所有必要的工具： + +- **Traits** 让您指定（抽象）接口以及具体实现。 +- **Mixin Composition** 为您提供了从较小的部分组成组件的工具。 +- **类**可以实现trait指定的接口。 +- 类的**实例**可以有自己的私有状态。 +- **Subtyping** 允许您在需要超类实例的地方使用一个类的实例。 +- **访问修饰符**允许您控制类的哪些成员可以被代码的哪个部分访问。 + +## Traits + +可能与支持 OOP 的其他语言（例如 Java）不同，Scala 中分解的主要工具不是类，而是trait。 +它们可以用来描述抽象接口，例如： + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String +``` + +{% endtab %} +{% endtabs %} + +并且还可以包含具体的实现： + +{% tabs traits_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String + def showHtml = "

            " + show + "

            " +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String + def showHtml = "

            " + show + "

            " +``` + +{% endtab %} +{% endtabs %} + +你可以看到我们用抽象方法 `show` 来定义方法 `showHtml`。 + +[Odersky and Zenger][scalable] 展示了 _面向服务的组件模型_ 和视图： + +- **抽象成员**作为_必须_服务：它们仍然需要由子类实现。 +- **具体成员**作为_提供_服务：它们被提供给子类。 + +我们已经可以在 `Showable` 的示例中看到这一点：定义一个扩展 `Showable` 的类 `Document`，我们仍然必须定义 `show`，但我们提供了 `showHtml`： + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Document(text: String) extends Showable { + def show = text +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Document(text: String) extends Showable: + def show = text +``` + +{% endtab %} +{% endtabs %} + +#### 抽象成员 + +抽象方法并不是trait中唯一可以抽象的东西。 +一个trait可以包含： + +- 抽象方法（`def m(): T`） +- 抽象值定义（`val x: T`） +- 抽象类型成员（`type T`），可能有界限（`type T <: S`） +- 抽象given（`given t: T`） +Scala 3 only + +上述每个特性都可用于指定对 trait 实现者的某种形式的要求。 + +## 混入组合 + +traits 不仅可以包含抽象和具体的定义，Scala 还提供了一种组合多个 trait 的强大方法：这个特性通常被称为 _混入组合_。 + +让我们假设以下两个（可能独立定义的）traits： + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait GreetingService { + def translate(text: String): String + def sayHello = translate("Hello") +} + +trait TranslationService { + def translate(text: String): String = "..." +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait GreetingService: + def translate(text: String): String + def sayHello = translate("Hello") + +trait TranslationService: + def translate(text: String): String = "..." +``` + +{% endtab %} +{% endtabs %} + +要组合这两个服务，我们可以简单地创建一个扩展它们的新trait： + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait ComposedService extends GreetingService with TranslationService +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait ComposedService extends GreetingService, TranslationService +``` + +{% endtab %} +{% endtabs %} + +一个 trait 中的抽象成员（例如 `GreetingService` 中的 `translate`）会自动与另一个 trait 中的具体成员匹配。 +这不仅适用于本例中的方法，而且适用于上述所有其他抽象成员（即类型、值定义等）。 + +## 类 + +Traits 非常适合模块化组件和描述接口（必需和提供）。 +但在某些时候，我们会想要创建它们的实例。 +在 Scala 中设计软件时，只考虑在继承模型的叶子中使用类通常很有帮助： + +{% comment %} +NOTE: I think “leaves” may technically be the correct word to use, but I prefer “leafs.” +{% endcomment %} + +{% tabs table-traits-cls-summary class=tabs-scala-version %} +{% tab 'Scala 2' %} +| Traits | `T1`, `T2`, `T3` +| 组合traits | `S1 extends T1 with T2`, `S2 extends T2 with T3` +| 类 | `C extends S1 with T3` +| 实例 | `new C()` +{% endtab %} +{% tab 'Scala 3' %} +| Traits | `T1`, `T2`, `T3` +| 组合 traits | `S extends T1, T2`, `S extends T2, T3` +| 类 | `C extends S, T3` +| 实例 | `C()` +{% endtab %} +{% endtabs %} + +在 Scala 3 中更是如此，trait 现在也可以接受参数，进一步消除了对类的需求。 + +#### 定义类 + +像trait一样，类可以扩展多个trait（但只有一个超类）： + +{% tabs class_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class MyService(name: String) extends ComposedService with Showable { + def show = s"$name says $sayHello" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class MyService(name: String) extends ComposedService, Showable: + def show = s"$name says $sayHello" +``` + +{% endtab %} +{% endtabs %} + +#### 子类型化 + +我们可以创建一个 `MyService` 的实例，如下所示： + +{% tabs class_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1: MyService = new MyService("Service 1") +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s1: MyService = MyService("Service 1") +``` + +{% endtab %} +{% endtabs %} + +通过子类型化的方式，我们的实例 `s1` 可以在任何扩展了trait的地方使用： + +{% tabs class_3 %} +{% tab 'Scala 2 and 3' %} + +```scala +val s2: GreetingService = s1 +val s3: TranslationService = s1 +val s4: Showable = s1 +// ... and so on ... +``` + +{% endtab %} +{% endtabs %} + +#### 扩展规划 + +如前所述，可以扩展另一个类： + +{% tabs class_4 %} +{% tab 'Scala 2 and 3' %} + +```scala +class Person(name: String) +class SoftwareDeveloper(name: String, favoriteLang: String) + extends Person(name) +``` + +{% endtab %} +{% endtabs %} + +然而，由于 _traits_ 被设计为主要的分解手段，在一个文件中定义的类_不能_在另一个文件中扩展。 +为了允许这样做，需要将基类标记为 `open`： + +{% tabs class_5 %} +{% tab 'Scala 3 Only' %} + +```scala +open class Person(name: String) +``` + +{% endtab %} +{% endtabs %} + +用 [`open`][open] 标记类是 Scala 3 的一个新特性。必须将类显式标记为开放可以避免面向对象设计中的许多常见缺陷。 +特别是，它要求库设计者明确计划扩展，例如用额外的扩展契约来记录那些被标记为开放的类。 + +{% comment %} +NOTE/FWIW: In his book, “Effective Java,” Joshua Bloch describes this as “Item 19: Design and document for inheritance or else prohibit it.” +Unfortunately I can’t find any good links to this on the internet. +I only mention this because I think that book and phrase is pretty well known in the Java world. +{% endcomment %} + +## 实例和私有可变状态 + +与其他支持 OOP 的语言一样，Scala 中的trait和类可以定义可变字段： + +{% tabs instance_6 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Counter { + // can only be observed by the method `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Counter: + // can only be observed by the method `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +``` + +{% endtab %} +{% endtabs %} + +`Counter` 类的每个实例都有自己的私有状态，只能通过方法 `count` 观察到，如下面的交互所示： + +{% tabs instance_7 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val c1 = new Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val c1 = Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% endtabs %} + +#### 访问修饰符 + +默认情况下，Scala 中的所有成员定义都是公开可见的。 +要隐藏实现细节，可以将成员（方法、字段、类型等）定义为 `private` 或 `protected`。 +通过这种方式，您可以控制访问或覆盖它们的方式。 +私有成员仅对类/trait本身及其伴生对象可见。 +受保护的成员对类的子类也是可见的。 + +## 高级示例：面向服务的设计 + +在下文中，我们展示了 Scala 的一些高级特性，并展示了如何使用它们来构建更大的软件组件。 +这些示例改编自 Martin Odersky 和 ​​Matthias Zenger 的论文 ["Scalable Component Abstractions"][scalable]。 +如果您不了解示例的所有细节，请不要担心；它的主要目的是演示如何使用多种类型特性来构造更大的组件。 + +我们的目标是定义一个_种类丰富_的软件组件，而对组件的细化，可以放到以后的实现中 +具体来说，以下代码将组件 `SubjectObserver` 定义为具有两个抽象类型成员的trait， `S` （用于主题）和 `O` （用于观察者）： + +{% tabs example_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait SubjectObserver { + + type S <: Subject + type O <: Observer + + trait Subject { self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = { + observers = obs :: observers + } + def publish() = { + for ( obs <- observers ) obs.notify(this) + } + } + + trait Observer { + def notify(sub: S): Unit + } +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait SubjectObserver: + + type S <: Subject + type O <: Observer + + trait Subject: + self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = + observers = obs :: observers + def publish() = + for obs <- observers do obs.notify(this) + + trait Observer: + def notify(sub: S): Unit +``` + +{% endtab %} +{% endtabs %} + +有几件事需要解释。 + +#### 抽象类型成员 + +声明 `type S <: Subject` 表示在 trait `SubjectObserver` 中我们可以引用一些我们称为 `S` 的_未知_（即抽象）类型。 +然而，该类型并不是完全未知的：我们至少知道它是trait `Subject` 的_某个子类型_。 +只要选择的类型是 `Subject` 的子类型，所有扩展自 `SubjectObserver` 的trait和类都可以自由地用于 `S`的类型。 +声明的 `<: Subject` 部分也称为 _`S` 的上界_。 + +#### 嵌套trait + +在 trait `SubjectObserver` _内_，我们定义了另外两个traits。 +让我们从 trait `Observer` 开始，它只定义了一个抽象方法 `notify`，它接受一个类型为 `S` 的参数。 +正如我们稍后将看到的，重要的是参数的类型为 `S` 而不是 `Subject` 类型。 + +第二个trait，`Subject`，定义了一个私有字段`observers`来存储所有订阅这个特定主题的观察者。 +订阅主题只是将对象存储到此列表中。 +同样，参数 `obs` 的类型是 `O`，而不是 `Observer`。 + +#### 自类型注解 + +最后，你可能想知道 trait `Subject` 上的 `self: S =>` 应该是什么意思。 +这称为 _自类型注解_。 +它要求 `Subject` 的子类型也是 `S` 的子类型。 +这对于能够使用 `this` 作为参数调用 `obs.notify` 是必要的，因为它需要 `S` 类型的值。 +如果 `S` 是一个_具体_类型，自类型注解可以被 `trait Subject extends S` 代替。 + +### 实现组件 + +我们现在可以实现上述组件并将抽象类型成员定义为具体类型： + +{% tabs example_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object SensorReader extends SubjectObserver { + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject { + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = { + currentValue = v + publish() + } + } + + class Display extends Observer { + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") + } +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object SensorReader extends SubjectObserver: + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject: + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = + currentValue = v + publish() + + class Display extends Observer: + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") +``` + +{% endtab %} +{% endtabs %} + +具体来说，我们定义了一个扩展 `SubjectObserver` 的_单例_对象 `SensorReader`。 +在 `SensorReader` 的实现中，我们说 `S` 类型现在被定义为 `Sensor` 类型，`O` 类型被定义为等于 `Display` 类型。 +`Sensor` 和 `Display` 都被定义为 `SensorReader` 中的嵌套类，相应地实现了 `Subject` 和 `Observer` 特性。 + +除了作为面向服务设计的示例之外，这段代码还突出了面向对象编程的许多方面： + +- `Sensor` 类引入了它自己的私有状态（`currentValue`），并在方法`changeValue` 后面封装了对状态的修改。 +- `changeValue` 的实现使用扩展trait中定义的方法 `publish`。 +- 类 `Display` 扩展了 `Observer` 特性，并实现了缺失的方法 `notify`。 + +{% comment %} +NOTE: You might say “the abstract method `notify`” in that last sentence, but I like “missing.” +{% endcomment %} + +有一点很重要，需要指出，`notify` 的实现只能安全地访问 `sub` 的标签和值，因为我们最初将参数声明为 `S` 类型。 + +### 使用组件 + +最后，下面的代码说明了如何使用我们的 `SensorReader` 组件： + +{% tabs example_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import SensorReader._ + +// setting up a network +val s1 = new Sensor("sensor1") +val s2 = new Sensor("sensor2") +val d1 = new Display() +val d2 = new Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// propagating updates through the network +s1.changeValue(2) +s2.changeValue(3) + +// prints: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 + +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import SensorReader.* + +// setting up a network +val s1 = Sensor("sensor1") +val s2 = Sensor("sensor2") +val d1 = Display() +val d2 = Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// propagating updates through the network +s1.changeValue(2) +s2.changeValue(3) + +// prints: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 +``` + +{% endtab %} +{% endtabs %} + +借助我们掌握的所有面向对象的编程工具，在下一节中，我们将演示如何以函数式风格设计程序。 + +{% comment %} +NOTE: One thing I occasionally do is flip things like this around, so I first show how to use a component, and then show how to implement that component. I don’t have a rule of thumb about when to do this, but sometimes it’s motivational to see the use first, and then see how to create the code to make that work. +{% endcomment %} + +[scalable]: https://doi.org/10.1145/1094811.1094815 +[open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-tools.md b/_zh-cn/overviews/scala3-book/domain-modeling-tools.md new file mode 100644 index 0000000000..08aa972f0a --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-tools.md @@ -0,0 +1,1345 @@ +--- +title: 工具 +type: section +description: This chapter provides an introduction to the available domain modeling tools in Scala 3, including classes, traits, enums, and more. +language: zh-cn +num: 21 +previous-page: domain-modeling-intro +next-page: domain-modeling-oop + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +Scala 3提供了许多不同的结构，因此我们可以对周围的世界进行建模： + +- 类 +- 对象 +- 伴生对象 +- Traits +- 抽象类 +- 枚举 +Scala 3 独有 +- 样例类 +- 样例对象 + +本节简要介绍其中的每种语言功能。 + +## 类 + +与其他语言一样，Scala中的_类_是用于创建对象实例的模板。 +下面是一些类的示例： + +{% tabs class_1 %} +{% tab 'Scala 2 and 3' %} + +```scala +class Person(var name: String, var vocation: String) +class Book(var title: String, var author: String, var year: Int) +class Movie(var name: String, var director: String, var year: Int) +``` + +{% endtab %} +{% endtabs %} + +这些例子表明，Scala有一种非常轻量级的方式来声明类。 + +我们的示例类的所有参数都定义为 `var` 字段，这意味着它们是可变的：您可以读取它们，也可以修改它们。 +如果您希望它们是不可变的---仅读取---请改为将它们创建为 `val` 字段，或者使用样例类。 + +在Scala 3之前，您使用 `new` 关键字来创建类的新实例： + +{% tabs class_2 %} +{% tab 'Scala 2 Only' %} + +```scala +val p = new Person("Robert Allen Zimmerman", "Harmonica Player") +// --- +``` + +{% endtab %} +{% endtabs %} + +然而，通过[通用 apply 方法][creator]，在 Scala 3 里面不要求使用 `new`： +Scala 3 独有 + +{% tabs class_3 %} +{% tab 'Scala 3 Only' %} + +```scala +val p = Person("Robert Allen Zimmerman", "Harmonica Player") +``` + +{% endtab %} +{% endtabs %} + +一旦你有了一个类的实例，比如 `p`，你就可以访问它的字段，在此示例中，这些字段都是构造函数的参数： + +{% tabs class_4 %} +{% tab 'Scala 2 and 3' %} + +```scala +p.name // "Robert Allen Zimmerman" +p.vocation // "Harmonica Player" +``` + +{% endtab %} +{% endtabs %} + +如前所述，所有这些参数都是作为 `var` 字段创建的，因此您也可以更改它们： + +{% tabs class_5 %} +{% tab 'Scala 2 and 3' %} + +```scala +p.name = "Bob Dylan" +p.vocation = "Musician" +``` + +{% endtab %} +{% endtabs %} + +### 字段和方法 + +类还可以具有不属于构造函数的方法和其他字段。 +它们在类的主体中定义。 +主体初始化为默认构造函数的一部分： + +{% tabs method class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person(var firstName: String, var lastName: String) { + + println("initialization begins") + val fullName = firstName + " " + lastName + + // a class method + def printFullName: Unit = + // access the `fullName` field, which is created above + println(fullName) + + printFullName + println("initialization ends") +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Person(var firstName: String, var lastName: String): + + println("initialization begins") + val fullName = firstName + " " + lastName + + // a class method + def printFullName: Unit = + // access the `fullName` field, which is created above + println(fullName) + + printFullName + println("initialization ends") +``` + +{% endtab %} +{% endtabs %} + +以下 REPL 会话演示如何使用这个类创建新的 `Person` 实例： + +{% tabs demo-person class=tabs-scala-version %} +{% tab 'Scala 2' %} +```` +scala> val john = new Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` +{% endtab %} +{% tab 'Scala 3' %} + +```` +scala> val john = Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` + +{% endtab %} +{% endtabs %} + +类还可以扩展 traits和抽象类，我们将在下面专门部分中介绍这些内容。 + +### 默认参数值 + +快速浏览一下其他功能，类构造函数参数也可以具有默认值： + +{% tabs default-values_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000) { + override def toString = s"timeout: $timeout, linger: $linger" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000): + override def toString = s"timeout: $timeout, linger: $linger" +``` + +{% endtab %} +{% endtabs %} + +此功能的一大优点是，它允许代码的使用者以各种不同的方式创建类，就好像该类有别的构造函数一样： + +{% tabs default-values_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s = new Socket() // timeout: 5000, linger: 5000 +val s = new Socket(2_500) // timeout: 2500, linger: 5000 +val s = new Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = new Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = new Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s = Socket() // timeout: 5000, linger: 5000 +val s = Socket(2_500) // timeout: 2500, linger: 5000 +val s = Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% endtabs %} + +创建类的新实例时，还可以使用命名参数。 +当许多参数具有相同的类型时，这特别有用，如以下比较所示： + +{% tabs default-values_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// option 1 +val s = new Socket(10_000, 10_000) + +// option 2 +val s = new Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// option 1 +val s = Socket(10_000, 10_000) + +// option 2 +val s = Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% endtabs %} + +### 辅助构造函数 + +可以为类定义多个构造函数，以便类的使用者用不同的方式来生成这个类。 +例如，假设您需要编写一些代码给大学招生系统中的学生进行建模。 +在分析需求时，您已经看到您需要能够以三种方式构建 `Student` 实例： + +- 当他们第一次开始招生过程时，带有姓名和政府 ID， +- 当他们提交申请时，带有姓名，政府 ID 和额外的申请日期 +- 在他们被录取后，带有姓名，政府 ID 和学生证 + +在 OOP 风格中处理这种情况的一种方法是使用以下代码： + +{% tabs structor_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import java.time._ + +// [1] the primary constructor +class Student( + var name: String, + var govtId: String +) { + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] a constructor for when the student has completed + // their application + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = { + this(name, govtId) + _applicationDate = Some(applicationDate) + } + + // [3] a constructor for when the student is approved + // and now has a student id + def this( + name: String, + govtId: String, + studentId: Int + ) = { + this(name, govtId) + _studentId = studentId + } +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import java.time.* + +// [1] the primary constructor +class Student( + var name: String, + var govtId: String +): + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] a constructor for when the student has completed + // their application + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = + this(name, govtId) + _applicationDate = Some(applicationDate) + + // [3] a constructor for when the student is approved + // and now has a student id + def this( + name: String, + govtId: String, + studentId: Int + ) = + this(name, govtId) + _studentId = studentId +``` + +{% endtab %} +{% endtabs %} + +{% comment %} +// for testing that code +override def toString = s""" +|Name: $name +|GovtId: $govtId +|StudentId: $_studentId +|Date Applied: $_applicationDate +""".trim.stripMargin +{% endcomment %} + +该类有三个构造函数，由代码中编号的注释给出： + +1. 主构造函数，由类定义中的 `name` 和 `govtId` 给出 +2. 具有参数 `name` 、 `govtId` 和 `applicationDate` 的辅助构造函数 +3. 另一个带有参数 `name` 、 `govtId` 和 `studentId` 的辅助构造函数 + +这些构造函数可以这样调用： + +{% tabs structor_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1 = new Student("Mary", "123") +val s2 = new Student("Mary", "123", LocalDate.now) +val s3 = new Student("Mary", "123", 456) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +val s1 = Student("Mary", "123") +val s2 = Student("Mary", "123", LocalDate.now) +val s3 = Student("Mary", "123", 456) +``` + +{% endtab %} +{% endtabs %} + +虽然可以使用此技术，但请记住，构造函数参数也可以具有默认值，这使得一个类看起来具有多个构造函数。 +这在前面的 `Socket` 示例中所示。 + +## 对象 + +对象是一个正好有一个实例的类。 +当其成员是引用类时，它会延迟初始化，类似于 `lazy val` 。 +Scala 中的对象允许在一个命名空间下对方法和字段进行分组，类似于我们在 Java，Javascript（ES6）中使用 `static` 方法或在 Python 中使用 `@staticmethod` 方法。 + +声明 `object` 类似于声明 `class` 。 +下面是一个“字符串实用程序”对象的示例，其中包含一组用于处理字符串的方法： + +{% tabs object_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object StringUtils { + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object StringUtils: + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +``` + +{% endtab %} +{% endtabs %} + +我们可以这样使用对象： + +{% tabs object_2 %} +{% tab 'Scala 2 and 3' %} + +```scala +StringUtils.truncate("Chuck Bartowski", 5) // "Chuck" +``` + +{% endtab %} +{% endtabs %} + +在 Scala 中导入非常灵活，并允许我们导入对象的_所有_ 成员： + +{% tabs object_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import StringUtils._ +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import StringUtils.* +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} +{% endtabs %} + +或者只是 _部分_ 成员： + +{% tabs object_4 %} +{% tab 'Scala 2 and 3' %} + +```scala +import StringUtils.{truncate, containsWhitespace} +truncate("Charles Carmichael", 7) // "Charles" +containsWhitespace("Captain Awesome") // true +isNullOrEmpty("Morgan Grimes") // Not found: isNullOrEmpty (error) +``` + +{% endtab %} +{% endtabs %} + +对象还可以包含字段，这些字段也可以像静态成员一样访问： + +{% tabs object_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object MathConstants { + val PI = 3.14159 + val E = 2.71828 +} + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object MathConstants: + val PI = 3.14159 + val E = 2.71828 + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} +{% endtabs %} + +## 伴生对象 + +与类同名且在与类在相同的文件中声明的 `object` 称为_“伴生对象”_。 +同样，相应的类称为对象的伴生类。 +伴生类或对象可以访问其伴生的私有成员。 + +伴生对象用于不特定于伴生类实例的方法和值。 +例如，在下面的示例中，类 `Circle` 具有一个名为 `area` 的成员，该成员特定于每个实例，其伴生对象具有一个名为 `calculateArea` 的方法，该方法(a)不特定于实例，并且(b)可用于每个实例： + +{% tabs companion class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.math._ + +class Circle(val radius: Double) { + def area: Double = Circle.calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = new Circle(5.0) +circle1.area +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import scala.math.* + +case class Circle(radius: Double): + def area: Double = Circle.calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) + +val circle1 = Circle(5.0) +circle1.area +``` + +{% endtab %} +{% endtabs %} + +在此示例中，每个实例可用的 `area` 方法使用伴生对象中定义的 `calculateArea` 方法。 +再一次， `calculateArea` 类似于Java中的静态方法。 +此外，由于 `calculateArea` 是私有的，因此其他代码无法访问它，但如图所示，它可以被 `Circle` 类的实例看到。 + +### 其他用途 + +伴生对象可用于多种用途： + +- 如图所示，它们可用于将“静态”方法分组到命名空间下 + - 这些方法可以是公共的，也可以是私有的 + - 如果 `calculateArea` 是公开的，它将被访问为 `Circle.calculateArea` +- 它们可以包含 `apply` 方法，这些方法---感谢一些语法糖---作为工厂方法来构建新实例 +- 它们可以包含 `unapply` 方法，用于解构对象，例如模式匹配 + +下面快速了解如何将 `apply` 方法当作工厂方法来创建新对象： + +{% tabs companion-use class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person { + var name = "" + var age = 0 + override def toString = s"$name is $age years old" +} + +object Person { + // a one-arg factory method + def apply(name: String): Person = { + var p = new Person + p.name = name + p + } + + // a two-arg factory method + def apply(name: String, age: Int): Person = { + var p = new Person + p.name = name + p.age = age + p + } +} + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +此处不涉及 `unapply` 方法，但在[语言规范](https://scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns)中对此进行了介绍。 + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Person: + var name = "" + var age = 0 + override def toString = s"$name is $age years old" + +object Person: + + // a one-arg factory method + def apply(name: String): Person = + var p = new Person + p.name = name + p + + // a two-arg factory method + def apply(name: String, age: Int): Person = + var p = new Person + p.name = name + p.age = age + p + +end Person + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +{% endtab %} +{% endtabs %} + +此处不涉及 `unapply` 方法，但在 [参考文档][unapply] 中对此进行了介绍。 + +## Traits + +如果你熟悉Java，Scala trait 类似于Java 8+中的接口。Traits 可以包含： + +- 抽象方法和成员 +- 具体方法和成员 + +在基本用法中，trait 可以用作接口，仅定义将由其他类实现的抽象成员： + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Employee { + def id: Int + def firstName: String + def lastName: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Employee: + def id: Int + def firstName: String + def lastName: String +``` + +{% endtab %} +{% endtabs %} + +但是，traits 也可以包含具体成员。 +例如，以下 traits定义了两个抽象成员---`numLegs` 和 `walk()`---并且还具有`stop()`方法的具体实现： + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Employee { + def id: Int + def firstName: String + def lastName: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait HasLegs: + def numLegs: Int + def walk(): Unit + def stop() = println("Stopped walking") +``` + +{% endtab %} +{% endtabs %} + +下面是另一个具有抽象成员和两个具体实现的 trait： + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasTail { + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait HasTail: + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +``` + +{% endtab %} +{% endtabs %} + +请注意，每个 trait 只处理非常特定的属性和行为：`HasLegs` 只处理腿，而 `HasTail` 只处理与尾部相关的功能。 +Traits可以让你构建这样的小模块。 + +在代码的后面部分，类可以混合多个 traits 来构建更大的组件： + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class IrishSetter(name: String) extends HasLegs with HasTail { + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class IrishSetter(name: String) extends HasLegs, HasTail: + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +``` + +{% endtab %} +{% endtabs %} + +请注意，`IrishSetter` 类实现了在 `HasLegs` 和 `HasTail` 中定义的抽象成员。 +现在，您可以创建新的 `IrishSetter` 实例： + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val d = new IrishSetter("Big Red") // "Big Red is a Dog" +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val d = IrishSetter（“Big Red”） // “Big Red is a Dog” +``` + +{% endtab %} +{% endtabs %} + +这只是你对 trait 可以完成的事情的一种体验。 +有关更多详细信息，请参阅这些建模课程的其余部分。 + +## 抽象类 + +{% comment %} +LATER: If anyone wants to update this section, our comments about abstract classes and traits are on Slack. The biggest points seem to be: +- The `super` of a trait is dynamic +- At the use site, people can mix in traits but not classes +- It remains easier to extend a class than a trait from Java, if the trait has at least a field +- Similarly, in Scala.js, a class can be imported from or exported to JavaScript. A trait cannot +- There are also some point that unrelated classes can’t be mixed together, and this can be a modeling advantage +{% endcomment %} + +当你想写一个类，但你知道它将有抽象成员时，你可以创建一个 trait 或一个抽象类。 +在大多数情况下，你会使用 trait，但从历史上看，有两种情况，使用抽象类比使用 trait 更好： + +- 您想要创建一个使用构造函数参数的基类 +- 代码将从 Java 代码调用 + +### 使用构造函数参数的基类 + +在 Scala 3 之前，当基类需要使用构造函数参数时，你可以将其声明为 `abstract class`： + +{% tabs abstract_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +abstract class Pet(name: String) { + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" +} + +class Dog(name: String, var age: Int) extends Pet(name) { + val greeting = "Woof" +} + +val d = new Dog("Fido", 1) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +abstract class Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +

            Trait 参数 Scala 3 独有

            + +但是，在 Scala 3 中，trait 现在可以具有[参数][trait-params]，因此您现在可以在相同情况下使用 trait： + +{% tabs abstract_2 %} +{% tab 'Scala 3 Only' %} + +```scala +trait Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, var age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +trait 的组成更加灵活---您可以混合多个 trait，但只能扩展一个类---并且大多数时候应该优先于类和抽象类。 +经验法则是，每当要创建特定类型的实例时，就使用类；如果要分解和重用行为时，应使用trait。 + +

            枚举Scala 3 独有

            + +枚举可用于定义由一组有限的命名值组成的类型（在[FP建模][fp-modeling]一节中，我们将看到枚举比这更灵活）。 +基本枚举用于定义常量集，如一年中的月份、一周中的天数、北/南/东/西方向等。 + +例如，这些枚举定义了与披萨饼相关的属性集： + +{% tabs enum_1 %} +{% tab 'Scala 3 Only' %} + + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +若要在其他代码中使用它们，请先导入它们，然后使用它们： + +{% tabs enum_2 %} +{% tab 'Scala 3 Only' %} + +```scala +import CrustSize.* +val currentCrustSize = Small +``` + +{% endtab %} +{% endtabs %} + +枚举值可以使用等于 （`==`） 进行比较，也可以用匹配的方式： + +{% tabs enum_3 %} +{% tab 'Scala 3 Only' %} + +```scala +// if/then +if (currentCrustSize == Large) + println("You get a prize!") + +// match +currentCrustSize match + case Small => println("small") + case Medium => println("medium") + case Large => println("large") +``` + +{% endtab %} +{% endtabs %} + +### 更多枚举特性 + +枚举也可以参数化： + +{% tabs enum_4 %} +{% tab 'Scala 3 Only' %} + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` + +{% endtab %} +{% endtabs %} + +它们还可以具有成员（如字段和方法）： + +{% tabs enum_5 %} +{% tab 'Scala 3 Only' %} + +```scala +enum Planet(mass: Double, radius: Double): + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = + otherMass * surfaceGravity + + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Earth extends Planet(5.976e+24, 6.37814e6) + // more planets here ... +``` + +{% endtab %} +{% endtabs %} + +### 与 Java 枚举的兼容性 + +如果要将 Scala 定义的枚举用作 Java 枚举，可以通过扩展类 `java.lang.Enum`（默认情况下导入）来实现，如下所示： + +{% tabs enum_6 %} +{% tab 'Scala 3 Only' %} + +```scala +enum Color extends Enum[Color] { case Red, Green, Blue } +``` + +{% endtab %} +{% endtabs %} + +类型参数来自 Java `enum` 定义，并且应与枚举的类型相同。 +在扩展时，无需向`java.lang.Enum`提供构造函数参数（如Java API文档中所定义的那样）---编译器会自动生成它们。 + +像这样定义 `Color` 之后，你可以像使用 Java 枚举一样使用它： + +```` +scala> Color.Red.compareTo（Color.Green） +val res0： Int = -1 +```` + +关于[代数数据类型][adts]和[参考文档][ref-enums]的部分更详细地介绍了枚举。 + +## 样例类 + +样例类用于对不可变数据结构进行建模。 +举个例子： + +{% tabs case-classes_1 %} +{% tab 'Scala 2 and 3' %} + +```scala +case class Person(name: String, relation: String) +``` + +{% endtab %} +{% endtabs %} + +由于我们将 `Person` 声明为样例类，因此默认情况下，字段 `name` 和 `relation` 是公共的和不可变的。 +我们可以创建 样例类的实例，如下所示： + +{% tabs case-classes_2 %} +{% tab 'Scala 2 and 3' %} + +```scala +val christina = Person("Christina", "niece") +``` + +{% endtab %} +{% endtabs %} + +请注意，这些字段不能发生更改： + +{% tabs case-classes_3 %} +{% tab 'Scala 2 and 3' %} + +```scala +christina.name = "Fred" // error: reassignment to val +``` + +{% endtab %} +{% endtabs %} + +由于 样例类的字段被假定为不可变的，因此 Scala 编译器可以为您生成许多有用的方法： + +* 生成一个 `unapply` 方法，该方法允许您对样例类执行模式匹配（即，`case Person（n， r） => ...`）。 +* 在类中生成一个 `copy` 方法，这对于创建实例的修改副本非常有用。 +* 生成使用结构相等的 `equals` 和 `hashCode` 方法，允许您在 `Map` 中使用样例类的实例。 +* 生成默认的 `toString` 方法，对调试很有帮助。 + +以下示例演示了这些附加功能： + +{% tabs case-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// Case classes can be used as patterns +christina match { + case Person(n, r) => println("name is " + n) +} + +// `equals` and `hashCode` methods generated for you +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// `toString` method +println(christina) // Person(Christina,niece) + +// built-in `copy` method +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// result: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) + +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// Case classes can be used as patterns +christina match + case Person(n, r) => println("name is " + n) + +// `equals` and `hashCode` methods generated for you +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// `toString` method +println(christina) // Person(Christina,niece) + +// built-in `copy` method +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// result: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) +``` + +{% endtab %} +{% endtabs %} + +### 支持函数式编程 + +如前所述，样例类支持函数式编程 （FP）： + +- 在FP中，您尽量避免改变数据结构。 + 因此，构造函数字段默认为 `val` 是有道理的。 + 由于无法更改样例类的实例，因此可以轻松共享它们，而不必担心突变或争用条件。 +- 您可以使用 `copy` 方法作为模板来创建新的（可能已更改的）实例，而不是改变实例。 + 此过程可称为“复制时更新”。 +- 自动为您生成 `unapply` 方法，还允许以模式匹配的高级方式使用样例类。 + +{% comment %} +NOTE: We can use this following text, if desired. If it’s used, it needs to be updated a little bit. + +### 一种 `unapply` 的方法 + +样例类的一大优点是，它可以为您的类自动生成一个 `unapply` 方法，因此您不必编写一个方法。 + +为了证明这一点，假设你有这个 trait： + +{% tabs case-classes_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Person { + def name: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Person: + def name: String +``` + +{% endtab %} +{% endtabs %} + +然后，创建以下样例类以扩展该 trait： + +{% tabs case-classes_6 %} +{% tab 'Scala 2 and 3' %} + +```scala +case class Student(name: String, year: Int) extends Person +case class Teacher(name: String, specialty: String) extends Person +``` + +{% endtab %} +{% endtabs %} + +由于它们被定义为样例类---并且它们具有内置的 `unapply` 方法---因此您可以编写如下匹配表达式： + +{% tabs case-classes_7 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def getPrintableString(p: Person): String = p match { + case Student(name, year) => + s"$name is a student in Year $year." + case Teacher(name, whatTheyTeach) => + s"$name teaches $whatTheyTeach." +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def getPrintableString(p: Person): String = p match + case Student(name, year) => + s"$name is a student in Year $year." + case Teacher(name, whatTheyTeach) => + s"$name teaches $whatTheyTeach." +``` + +{% endtab %} +{% endtabs %} + +请注意 `case` 语句中的以下两种模式： + +{% tabs case-classes_8 %} +{% tab 'Scala 2 and 3' %} + +```scala +case Student(name, year) => +case Teacher(name, whatTheyTeach) => +``` + +{% endtab %} +{% endtabs %} + +这些模式之所以有效，是因为 `Student` 和 `Teacher` 被定义为具有 `unapply` 方法的样例类，其类型签名符合特定标准。 +从技术上讲，这些示例中显示的特定类型的模式匹配称为_结构模式匹配_。 + +> Scala 标准是， `unapply` 方法在包装在 `Option` 中的元组中返回 样例类构造函数字段。 +> 解决方案的“元组”部分在上一课中进行了演示。 + +要显示该代码的工作原理，请创建一个 `Student` 和 `Teacher` 的实例： + +{% tabs case-classes_9 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s = new Student("Al", 1) +val t = new Teacher("Bob Donnan", "Mathematics") +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s = Student("Al", 1) +val t = Teacher("Bob Donnan", "Mathematics") +``` + +{% endtab %} +{% endtabs %} + +接下来，这是当您使用这两个实例来调用 `getPrintableString` 时，REPL 中的输出如下所示： + +{% tabs case-classes_10 %} +{% tab 'Scala 2 and 3' %} + +```scala +scala> getPrintableString(s) +res0: String = Al is a student in Year 1. + +scala> getPrintableString(t) +res1: String = Bob Donnan teaches Mathematics. +``` + +{% endtab %} +{% endtabs %} + +>所有这些关于 `unapply` 方法和提取器的内容对于这样的入门书来说都有些先进，但是因为样例类是一个重要的FP主题，所以似乎最好涵盖它们，而不是跳过它们。 + +#### 将模式匹配添加到任何具有 unapply 的类型 + +Scala 的一个很好的特性是，你可以通过编写自己的 `unapply` 方法来向任何类型添加模式匹配。 +例如，此类在其伴生对象中定义了一个 `unapply` 方法： + +{% tabs case-classes_11 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person(var name: String, var age: Int) +object Person { + def unapply(p: Person): Tuple2[String, Int] = (p.name, p.age) +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Person(var name: String, var age: Int) +object Person: + def unapply(p: Person): Tuple2[String, Int] = (p.name, p.age) +``` + +{% endtab %} +{% endtabs %} + +因为它定义了一个 `unapply` 方法，并且因为该方法返回一个元组，所以您现在可以将 `Person` 与 `match` 表达式一起使用： + +{% tabs case-classes_12 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val p = new Person("Astrid", 33) + +p match { + case Person(n,a) => println(s"name: $n, age: $a") + case null => println("No match") +} + +// that code prints: "name: Astrid, age: 33" +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val p = Person("Astrid", 33) + +p match + case Person(n,a) => println(s"name: $n, age: $a") + case null => println("No match") + +// that code prints: "name: Astrid, age: 33" +``` + +{% endtab %} +{% endtabs %} + +{% endcomment %} + +## 样例对象 + +样例对象之于对象，就像 样例类之于类：它们提供了许多自动生成的方法，以使其更加强大。 +每当您需要需要少量额外功能的单例对象时，它们特别有用，例如在 `match` 表达式中与模式匹配一起使用。 + +当您需要传递不可变消息时，样例对象非常有用。 +例如，如果您正在处理音乐播放器项目，您将创建一组命令或消息，如下所示： + +{% tabs case-objects_1 %} +{% tab 'Scala 2 and 3' %} + +```scala +sealed trait Message +case class PlaySong(name: String) extends Message +case class IncreaseVolume(amount: Int) extends Message +case class DecreaseVolume(amount: Int) extends Message +case object StopPlaying extends Message +``` + +{% endtab %} +{% endtabs %} + +然后在代码的其他部分，你可以编写这样的方法，这些方法使用模式匹配来处理传入的消息（假设方法 `playSong` ， `changeVolume` 和 `stopPlayingSong` 在其他地方定义）： + +{% tabs case-objects_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def handleMessages(message: Message): Unit = message match { + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def handleMessages(message: Message): Unit = message match + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +``` + +{% endtab %} +{% endtabs %} + +[ref-enums]: {{ site.scala3ref }}/enums/enums.html +[adts]: {% link _zh-cn/overviews/scala3-book/types-adts-gadts.md %} +[fp-modeling]: {% link _zh-cn/overviews/scala3-book/domain-modeling-fp.md %} +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[unapply]: {{ site.scala3ref }}/changed-features/pattern-matching.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_zh-cn/overviews/scala3-book/first-look-at-types.md b/_zh-cn/overviews/scala3-book/first-look-at-types.md new file mode 100644 index 0000000000..0c8fb09744 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/first-look-at-types.md @@ -0,0 +1,376 @@ +--- +title: 类型初探 +type: chapter +description: This page provides a brief introduction to Scala's built-in data types, including Int, Double, String, Long, Any, AnyRef, Nothing, and Null. +language: zh-cn +num: 17 +previous-page: taste-summary +next-page: string-interpolation + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +## 所有值都有一个类型 + +在 Scala 中，所有值都有一个类型，包括数值和函数。 +下图展示了类型层次结构的一个子集。 + +Scala 3 Type Hierarchy + +## Scala 类型层次结构 + +`Any` 是所有类型的超类型，也称为 **首类型**。 +它定义了某些通用方法，例如 `equals` ， `hashCode` 和 `toString` 。 + +首类型 `Any` 有一个子类型 [`Matchable`][matchable]，它用于标记可以执行模式匹配的所有类型。 +保证属性调用 _“参数化”_ 非常重要。 +我们不会在这里详细介绍，但总而言之，这意味着我们不能对类型为 `Any` 的值进行模式匹配，而只能对 `Matchable` 的子类型的值进行模式匹配。 +[参考文档][matchable]包含有关 `Matchable` 的更多信息。 + +`Matchable` 有两个重要的子类型： `AnyVal` 和 `AnyRef` 。 + +*`AnyVal`* 表示值类型。 +有几个预定义的值类型，它们是不可为空的： `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit`, 和 `Boolean`。 +`Unit` 是一种值类型，它不携带有意义的信息。 +`Unit` 只有一个实例，我们可以将其称为：`()`。 + +*`AnyRef`* 表示引用类型。 +所有非值类型都定义为引用类型。 +Scala中的每个用户定义类型都是 `AnyRef` 的子类型。 +如果在Java运行时环境的上下文中使用Scala，则 `AnyRef` 对应于 `java.lang.Object`。 + +在基于语句的编程语言中， `void` 用于没有返回值的方法。 +如果您在Scala中编写没有返回值的方法，例如以下方法，则 `Unit` 用于相同的目的： + +{% tabs unit %} +{% tab 'Scala 2 and 3' for=unit %} + +```scala +def printIt(a: Any): Unit = println(a) +``` + +{% endtab %} +{% endtabs %} + +下面是一个示例，它演示了字符串、整数、字符、布尔值和函数都是 `Any` 的实例，可以像对待其他所有对象一样处理： + +{% tabs any %} +{% tab 'Scala 2 and 3' for=any %} + +```scala +val list: List[Any] = List( + "a string", + 732, // an integer + 'c', // a character + true, // a boolean value + () => "an anonymous function returning a string" +) + +list.foreach(element => println(element)) +``` + +{% endtab %} +{% endtabs %} + +该代码定义了一个类型为 `List[Any]` 的值 `list` 。 +该列表使用各种类型的元素进行初始化，但每个元素都是 `scala.Any` 的实例，因此我们可以将它们添加到列表中。 + +下面是程序的输出： + +``` +a string +732 +c +true + +``` + +## Scala的“值类型” + +如上所示，Scala的值类型扩展了 `AnyVal`，它们都是成熟的对象。 +这些示例演示如何声明以下数值类型的变量： + +{% tabs anyval %} +{% tab 'Scala 2 and 3' for=anyval %} + +```scala +val b: Byte = 1 +val i: Int = 1 +val l: Long = 1 +val s: Short = 1 +val d: Double = 2.0 +val f: Float = 3.0 +``` + +{% endtab %} +{% endtabs %} + +在前四个示例中，如果未显式指定类型，则数字 `1` 将默认为 `Int` ，因此，如果需要其他数据类型之一 --- `Byte` 、`Long` 或 `Short` --- 则需要显式声明这些类型，如上面代码所示。 +带有小数的数字（如2.0）将默认为 `Double` ，因此，如果您想要 `Float` ，则需要声明 `Float` ，如上一个示例所示。 + +由于 `Int` 和 `Double` 是默认数值类型，因此通常在不显式声明数据类型的情况下创建它们： + +{% tabs anynum %} +{% tab 'Scala 2 and 3' for=anynum %} + +```scala +val i = 123 // defaults to Int +val x = 1.0 // defaults to Double +``` + +{% endtab %} +{% endtabs %} + +在代码中，您还可以将字符 `L` 、 `D` 和 `F` （及其小写等效项）加到数字末尾，以指定它们是 `Long`, `Double`, 或 `Float` 值： + +{% tabs type-post %} +{% tab 'Scala 2 and 3' for=type-post %} + +```scala +val x = 1_000L // val x: Long = 1000 +val y = 2.2D // val y: Double = 2.2 +val z = 3.3F // val z: Float = 3.3 +``` + +{% endtab %} +{% endtabs %} + +Scala还具有 `String` 和 `Char` 类型，通常可以使用隐式形式声明： + +{% tabs type-string %} +{% tab 'Scala 2 and 3' for=type-string %} + +```scala +val s = "Bill" +val c = 'a' +``` + +{% endtab %} +{% endtabs %} + +如下面表格所示，将字符串括在双引号中 --- 或多行字符串括在三引号中 --- 或字符括在单引号中。 + +这些数据类型及其范围包括： + +| 数据类型 | 可能的值 | +| ---------- | --------------- | +| Boolean | `true` 或 `false` | +| Byte | 8 位有符号二进制补码整数（-2^7 至 2^7-1,含）
            -128 至 127 | +| Short | 16 位有符号二进制补码整数（-2^15 至 2^15-1,含）
            -32,768 至 32,767 | +| Int | 32 位二进制补码整数（-2^31 至 2^31-1,含）
            -2,147,483,648 至 2,147,483,647 | +| Long | 64 位 2 的补码整数（-2^63 到 2^63-1,含）
            （-2^63 到 2^63-1,包括） | +| Float | 32 位 IEEE 754 单精度浮点数
            1.40129846432481707e-45 到 3.40282346638528860e+38 | +| Double | 64 位 IEEE 754 双精度浮点数
            4.94065645841246544e-324 到 1.79769313486231570e+308 | +| Char | 16 位无符号 Unicode 字符（0 到 2^16-1,含）
            0 到 65,535 | +| String | 一个 `Char` 序列 | + +## `BigInt` 和 `BigDecimal` + +当您需要非常大的数字时，请使用 `BigInt` 和 `BigDecimal` 类型： + +{% tabs type-bigint %} +{% tab 'Scala 2 and 3' for=type-bigint %} + +```scala +val a = BigInt(1_234_567_890_987_654_321L) +val b = BigDecimal(123_456.789) +``` + +{% endtab %} +{% endtabs %} + +其中 `Double` 和 `Float` 是近似的十进制数， `BigDecimal` 用于精确算术，例如在使用货币时。 + +`BigInt` 和 `BigDecimal` 的一个好处是，它们支持您习惯于用于数字类型的所有运算符： + +{% tabs type-bigint2 %} +{% tab 'Scala 2 and 3' for=type-bigint2 %} + +```scala +val b = BigInt(1234567890) // scala.math.BigInt = 1234567890 +val c = b + b // scala.math.BigInt = 2469135780 +val d = b * b // scala.math.BigInt = 1524157875019052100 +``` + +{% endtab %} +{% endtabs %} + +## 关于字符串的两个注释 + +Scala字符串类似于Java字符串，但它们有两个很棒的附加特性： + +- 它们支持字符串插值 +- 创建多行字符串很容易 + +### 字符串插值 + +字符串插值提供了一种非常可读的方式在字符串中使用变量。 +例如，给定以下三个变量： + +{% tabs string-inside1 %} +{% tab 'Scala 2 and 3' for=string-inside1 %} + +```scala +val firstName = "John" +val mi = 'C' +val lastName = "Doe" +``` + +{% endtab %} +{% endtabs %} + +你可以把那些变量组合成这样的字符串： + +{% tabs string-inside2 %} +{% tab 'Scala 2 and 3' for=string-inside2 %} + +```scala +println(s"Name: $firstName $mi $lastName") // "Name: John C Doe" +``` + +{% endtab %} +{% endtabs %} + +只需在字符串前面加上字母 `s` ，然后在字符串内的变量名称之前放置一个 `$` 符号。 + +如果要在字符串中使用可能较大的表达式时，请将它们放在大括号中： + +{% tabs string-inside3 %} +{% tab 'Scala 2 and 3' for=string-inside3 %} + +```scala +println(s"2 + 2 = ${2 + 2}") // prints "2 + 2 = 4" +val x = -1 +println(s"x.abs = ${x.abs}") // prints "x.abs = 1" +``` + +{% endtab %} +{% endtabs %} + +#### 其他插值器 + +放置在字符串前面的 `s` 只是一个可能的插值器。 +如果使用 `f` 而不是 `s` ，则可以在字符串中使用 `printf` 样式的格式语法。 +此外，字符串插值器只是一种特殊方法，可以定义自己的方法。 +例如，一些数据库库定义了非常强大的 `sql` 插值器。 + +### 多行字符串 + +多行字符串是通过将字符串包含在三个双引号内来创建的： + +{% tabs string-mlines1 %} +{% tab 'Scala 2 and 3' for=string-mlines1 %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` + +{% endtab %} +{% endtabs %} + +这种基本方法的一个缺点是，第一行之后的行是缩进的，如下所示： + +{% tabs string-mlines2 %} +{% tab 'Scala 2 and 3' for=string-mlines2 %} + +```scala +"The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +当间距很重要时，在第一行之后的所有行前面放一个 `|` 符号，并在字符串之后调用 `stripMargin` 方法： + +{% tabs string-mlines3 %} +{% tab 'Scala 2 and 3' for=string-mlines3 %} + +```scala +val quote = """The essence of Scala: + |Fusion of functional and object-oriented + |programming in a typed setting.""".stripMargin +``` + +{% endtab %} +{% endtabs %} + +现在字符串里所有行都是左对齐了： + +{% tabs string-mlines4 %} +{% tab 'Scala 2 and 3' for=string-mlines4 %} + +```scala +"The essence of Scala: +Fusion of functional and object-oriented +programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +## 类型转换 + +可以通过以下方式强制转换值类型： + +Scala Type Hierarchy + +例如： + +{% tabs cast1 %} +{% tab 'Scala 2 and 3' for=cast1 %} + +```scala +val b: Byte = 127 +val i: Int = b // 127 + +val face: Char = '☺' +val number: Int = face // 9786 +``` + +{% endtab %} +{% endtabs %} + +只有在没有丢失信息的情况下，才能强制转换为类型。否则，您需要明确说明强制转换： + +{% tabs cast2 %} +{% tab 'Scala 2 and 3' for=cast2 %} + +```scala +val x: Long = 987654321 +val y: Float = x.toFloat // 9.8765434E8 (注意 `.toFloat` 是必须的，因为强制类型转换后的精度会损) +val z: Long = y // Error +``` + +{% endtab %} +{% endtabs %} + +还可以将引用类型强制转换为子类型。 +这将在教程的后面部分介绍。 + +## `Nothing` 和 `null` + +`Nothing` 是所有类型的子类型，也称为**底部类型**。 +`Nothing` 类型是没有值的。 +一个常见的用途是发出非终止信号，例如抛出异常，程序退出或无限循环---即，它是不计算为值的那种表达式，或者不正常返回的方法。 + +`Null` 是所有引用类型的子类型（即 `AnyRef` 的任何子类型）。 +它具有由关键字面量 `null` 标识的单个值。 +目前，使用 `null` 被认为是不好的做法。它应该主要用于与其他JVM语言的互操作性。选择加入编译器选项会更改 `Null` 状态，以修复与其用法相关的警告。此选项可能会成为将来版本的 Scala 中的默认值。你可以在[这里][safe-null]了解更多关于它的信息。 + +与此同时， `null` 几乎不应该在Scala代码中使用。 +本书的[函数式编程章节][fp]和 [API文档][option-api]中讨论了 `null` 的替代方法。 + +[reference]: {{ site.scala3ref }}/overview.html +[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html +[interpolation]: {% link _overviews/scala3-book/string-interpolation.md %} +[fp]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %} +[option-api]: https://scala-lang.org/api/3.x/scala/Option.html +[safe-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html diff --git a/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md b/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md new file mode 100644 index 0000000000..b1cce269af --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md @@ -0,0 +1,489 @@ +--- +title: 函数式错误处理 +type: section +description: This section provides an introduction to functional error handling in Scala 3. +language: zh-cn +num: 46 +previous-page: fp-functions-are-values +next-page: fp-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +函数式编程就像写一系列代数方程，因为代数没有空值或抛出异常，所以你不用在 FP 中使用这些特性。 +这带来了一个有趣的问题：在 OOP 代码中通常可能使用空值或异常的情况下，您会怎么做？ + +Scala 的解决方案是使用类似 `Option`/`Some`/`None` 类的结构。 +本课介绍如何使用这些技术。 + +在我们开始之前有两个注意事项： + +- `Some` 和 `None` 类是 `Option` 的子类。 +- 下面的文字一般只指“`Option`”或“`Option`类”，而不是重复说“`Option`/`Some`/`None`”。 + +## 第一个例子 + +虽然第一个示例不处理空值，但它是引入 `Option` 类的好方法，所以我们将从它开始。 + +想象一下，您想编写一个方法，可以轻松地将字符串转换为整数值，并且您想要一种优雅的方法来处理异常，这个是异常是该方法获取类似“Hello”而不是“1”的字符串时引发的。 +对这种方法的初步猜测可能如下所示： + +{% tabs fp-java-try class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def makeInt(s: String): Int = + try { + Integer.parseInt(s.trim) + } catch { + case e: Exception => 0 + } +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def makeInt(s: String): Int = + try + Integer.parseInt(s.trim) + catch + case e: Exception => 0 +``` +{% endtab %} +{% endtabs %} + +如果转换成功，则此方法返回正确的 `Int` 值，但如果失败，则该方法返回 `0`。 +出于某些目的，这可能是可以的，但它并不准确。 +例如，该方法可能收到了`"0"`，但它也可能收到了 `"foo"`、`"bar"` 或无数其他将引发异常的字符串。 +这是一个真正的问题：您如何知道该方法何时真正收到 `"0"`，或者何时收到其他内容？ +答案是，用这种方法，没有办法知道。 + +## 使用 Option/Some/None + +Scala 中这个问题的一个常见解决方案是使用三个类，称为 `Option`、`Some` 和 `None` 。 +`Some` 和 `None` 类是 `Option` 的子类，因此解决方案的工作原理如下： + +- 你声明 `makeInt` 返回一个 `Option` 类型 +- 如果 `makeInt` 接收到一个字符串，它*可以* 转换为 `Int`，答案将包含在 `Some` 中 +- 如果 `makeInt` 接收到一个它*无法*转换的字符串，它返回一个 `None` + +这是 `makeInt` 的修订版： + +{% tabs fp--try-option class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def makeInt(s: String): Option[Int] = + try { + Some(Integer.parseInt(s.trim)) + } catch { + case e: Exception => None + } +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def makeInt(s: String): Option[Int] = + try + Some(Integer.parseInt(s.trim)) + catch + case e: Exception => None +``` +{% endtab %} +{% endtabs %} + +这段代码可以理解为，“当给定的字符串转换为整数时，返回包裹在 `Some` 中的 `Int`，例如 `Some(1)`。 +当字符串无法转换为整数时，会抛出并捕获异常，并且该方法返回一个 `None` 值。” + +这些示例展示了 `makeInt` 的工作原理： + +{% tabs fp-try-option-example %} +{% tab 'Scala 2 and 3' %} +```scala +val a = makeInt("1") // Some(1) +val b = makeInt("one") // None +``` +{% endtab %} +{% endtabs %} + +如图所示，字符串`"1"`产生一个 `Some(1)`，而字符串 `"one"` 产生一个 `None`。 +这是错误处理的 `Option` 方法的本质。 +如图所示，使用了这种技术，因此方法可以返回 *值* 而不是 *异常*。 +在其他情况下，`Option` 值也用于替换 `null` 值。 + +两个注意事项： + +- 你会发现这种方法在整个 Scala 库类和第三方 Scala 库中使用。 +- 这个例子的一个关键点是函数式方法不会抛出异常；相反，它们返回类似 `Option` 的值。 + +## 成为 makeInt 的消费者 + +现在假设您是 `makeInt` 方法的使用者。 +你知道它返回一个 `Option[Int]` 的子类，所以问题就变成了，你如何处理这些返回类型？ + +根据您的需要，有两个常见的答案： + +- 使用 `match` 表达式 +- 使用 `for` 表达式 + +## 使用 `match` 表达式 + +一种可能的解决方案是使用 `match` 表达式： + +{% tabs fp-option-match class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +makeInt(x) match { + case Some(i) => println(i) + case None => println("That didn’t work.") +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +makeInt(x) match + case Some(i) => println(i) + case None => println("That didn’t work.") +``` +{% endtab %} +{% endtabs %} + +在本例中，如果 `x` 可以转换为 `Int`，则计算第一个 `case` 子句右侧的表达式；如果 `x` 不能转换为 `Int`，则计算第二个 `case` 子句右侧的表达式。 + +## 使用 `for` 表达式 + +另一种常见的解决方案是使用 `for` 表达式，即本书前面显示的 `for`/`yield` 组合。 +例如，假设您要将三个字符串转换为整数值，然后将它们相加。 +这就是你使用 `for` 表达式和 `makeInt` 的方法： + +{% tabs fp-for-comprehension class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val y = for { + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +} yield { + a + b + c +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val y = for + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +yield + a + b + c +``` +{% endtab %} +{% endtabs %} + +在该表达式运行后，`y` 将是以下两种情况之一： + +- 如果*所有*三个字符串都转换为 `Int` 值，`y` 将是 `Some[Int]`，即包裹在 `Some` 中的整数 +- 如果三个字符串中*任意一个*字符串不能转换为 `Int`，则 `y` 将是 `None` + +你可以自己测试一下： + +{% tabs fp-for-comprehension-evaluation class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val stringA = "1" +val stringB = "2" +val stringC = "3" + +val y = for { + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +} yield { + a + b + c +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val stringA = "1" +val stringB = "2" +val stringC = "3" + +val y = for + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +yield + a + b + c +``` +{% endtab %} +{% endtabs %} + +使用该样本数据，变量 `y` 的值将是 `Some(6)` 。 + +要查看失败案例，请将这些字符串中的任何一个更改为不会转换为整数的字符串。 +当你这样做时，你会看到 `y` 是 `None`： + +{% tabs fp-for-comprehension-failure-result %} +{% tab 'Scala 2 and 3' %} +```scala +y: Option[Int] = None +``` +{% endtab %} +{% endtabs %} + +## 将 Option 视为容器 + +心智模型通常可以帮助我们理解新情况，因此，如果您不熟悉 `Option` 类，可以将它们视为*容器*： + +- `Some` 是一个容器，里面有一个项目 +- `None` 是一个容器，但里面什么都没有 + +如果您更愿意将 `Option` 类想象成一个盒子，`None` 就像一个空盒子。 +它可能有一些东西，但它没有。 + +{% comment %} +NOTE: I commented-out this subsection because it continues to explain Some and None, and I thought it was probably too much for this book. + +## Using `foreach` with `Option` + +Because `Some` and `None` can be thought of containers, they’re also like collections classes. +They have many of the methods you’d expect from a collection class, including `map`, `filter`, `foreach`, etc. + +This raises an interesting question: What will these two values print, if anything? + +{% tabs fp-option-methods-evaluation %} +{% tab 'Scala 2 and 3' %} +```scala +makeInt("1").foreach(println) +makeInt("x").foreach(println) +``` +{% endtab %} +{% endtabs %} + +Answer: The first example prints the number `1`, and the second example doesn’t print anything. +The first example prints `1` because: + +- `makeInt("1")` evaluates to `Some(1)` +- The expression becomes `Some(1).foreach(println)` +- The `foreach` method on the `Some` class knows how to reach inside the `Some` container and extract the value (`1`) that’s inside it, so it passes that value to `println` + +Similarly, the second example prints nothing because: + +- `makeInt("x")` evaluates to `None` +- The `foreach` method on the `None` class knows that `None` doesn’t contain anything, so it does nothing + +In this regard, `None` is similar to an empty `List`. + +### The happy and unhappy paths + +Somewhere in Scala’s history, someone noted that the first example (the `Some`) represents the “Happy Path” of the `Option` approach, and the second example (the `None`) represents the “Unhappy Path.” +*But* despite having two different possible outcomes, the great thing with `Option` is that there’s really just one path: The code you write to handle the `Some` and `None` possibilities is the same in both cases. +The `foreach` examples look like this: + +{% tabs fp-another-option-method-example %} +{% tab 'Scala 2 and 3' %} +```scala +makeInt(aString).foreach(println) +``` +{% endtab %} +{% endtabs %} + +And the `for` expression looks like this: + +{% tabs fp-another-for-comprehension-example class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val y = for { + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +} yield { + a + b + c +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val y = for + a <- makeInt(stringA) + b <- makeInt(stringB) + c <- makeInt(stringC) +yield + a + b + c +``` +{% endtab %} +{% endtabs %} + +With exceptions you have to worry about handling branching logic, but because `makeInt` returns a value, you only have to write one piece of code to handle both the Happy and Unhappy Paths, and that simplifies your code. + +Indeed, the only time you have to think about whether the `Option` is a `Some` or a `None` is when you handle the result value, such as in a `match` expression: + +{% tabs fp-option-match-handle class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +makeInt(x) match { + case Some(i) => println(i) + case None => println("That didn't work.") +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +makeInt(x) match + case Some(i) => println(i) + case None => println("That didn't work.") +``` +{% endtab %} +{% endtabs %} + +> There are several other ways to handle `Option` values. +> See the reference documentation for more details. +{% endcomment %} + +## 使用 `Option` 替换 `null` + +回到 `null` 值，`null` 值可以悄悄地潜入你的代码的地方是这样的类： + +{% tabs fp=case-class-nulls %} +{% tab 'Scala 2 and 3' %} +```scala +class Address( + var street1: String, + var street2: String, + var city: String, + var state: String, + var zip: String +) +``` +{% endtab %} +{% endtabs %} + +虽然地球上的每个地址都有一个 `street1` 值，但 `street2` 值是可选的。 +因此，`street2` 字段可以被分配一个 `null` 值： + +{% tabs fp-case-class-nulls-example class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val santa = new Address( + "1 Main Street", + null, // <-- D’oh! A null value! + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val santa = Address( + "1 Main Street", + null, // <-- D’oh! A null value! + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} +{% endtabs %} + +从历史上看，开发人员在这种情况下使用了空白字符串和空值，这两种方法都是使用技巧来解决基础性的问题，这个问题是：`street2` 是一个*可选*字段。 +在 Scala 和其他现代语言中，正确的解决方案是预先声明 `street2` 是可选的： + +{% tabs fp-case-class-with-options %} +{% tab 'Scala 2 and 3' %} +```scala +class Address( + var street1: String, + var street2: Option[String], // an optional value + var city: String, + var state: String, + var zip: String +) +``` +{% endtab %} +{% endtabs %} + +现在开发人员可以编写更准确的代码，如下所示： + +{% tabs fp-case-class-with-options-example-none class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val santa = new Address( + "1 Main Street", + None, // 'street2' has no value + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val santa = Address( + "1 Main Street", + None, // 'street2' has no value + "North Pole", + "Alaska", + "99705" +) +``` +{% endtab %} +{% endtabs %} + +或这个： + +{% tabs fp-case-class-with-options-example-some class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val santa = new Address( + "123 Main Street", + Some("Apt. 2B"), + "Talkeetna", + "Alaska", + "99676" +) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val santa = Address( + "123 Main Street", + Some("Apt. 2B"), + "Talkeetna", + "Alaska", + "99676" +) +``` +{% endtab %} +{% endtabs %} + +## `Option` 不是唯一的解决方案 + +虽然本节关注的是 `Option` 类，但 Scala 还有一些其他选择。 + +例如，称为 `Try`/`Success`/`Failure` 的三个类以相同的方式工作，但是 (a) 当您的代码可以抛出异常时，您主要使用这些类，并且 (b) 您想要使用`Failure` 类，因为它使您可以访问异常消息。 +例如，在编写与文件、数据库和 Internet 服务交互的方法时，通常会使用这些 `Try` 类，因为这些函数很容易引发异常。 + +## 快速回顾 + +这部分很长，让我们快速回顾一下： + +- 函数式程序员不使用 `null` 值 +- `null` 值的主要替代品是使用 `Option` 类 +- 函数式方法不会抛出异常； 相反，它们返回诸如 `Option` 、 `Try` 或 `Either` 之类的值 +- 使用 `Option` 值的常用方法是 `match` 和 `for` 表达式 +- Option 可以被认为是一个项目（`Some`）和没有项目（`None`）的容器 +- option 也可用于可选的构造函数或方法参数 + diff --git a/_zh-cn/overviews/scala3-book/fp-functions-are-values.md b/_zh-cn/overviews/scala3-book/fp-functions-are-values.md new file mode 100644 index 0000000000..ab802ed02a --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fp-functions-are-values.md @@ -0,0 +1,133 @@ +--- +title: 函数是值 +type: section +description: This section looks at the use of functions as values in functional programming. +language: zh-cn +num: 45 +previous-page: fp-pure-functions +next-page: fp-functional-error-handling + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +虽然曾经创建的每种编程语言都可能允许您编写纯函数，但 Scala FP 的第二个重要特性是*您可以将函数创建为值*，就像您创建 `String` 和 `Int` 值一样。 + +这个特性有很多好处，其中最常见的是（a）您可以定义方法来接受函数参数，以及（b）您可以将函数作为参数传递给方法。 +你已经在本书的多个地方看到了这一点，每当演示像 `map` 和 `filter` 这样的方法时： + +{% tabs fp-function-as-values-anonymous %} +{% tab 'Scala 2 and 3' %} +```scala +val nums = (1 to 10).toList + +val doubles = nums.map(_ * 2) // double each value +val lessThanFive = nums.filter(_ < 5) // List(1,2,3,4) +``` +{% endtab %} +{% endtabs %} + +在这些示例中，匿名函数被传递到 `map` 和 `filter` 中。 + +> 匿名函数也称为 *lambdas*。 + +除了将匿名函数传递给 `filter` 和 `map` 之外，您还可以为它们提供 *方法*： + +{% tabs fp-function-as-values-defined %} +{% tab 'Scala 2 and 3' %} +```scala +// two methods +def double(i: Int): Int = i * 2 +def underFive(i: Int): Boolean = i < 5 + +// pass those methods into filter and map +val doubles = nums.filter(underFive).map(double) +``` +{% endtab %} +{% endtabs %} + +这种将方法和函数视为值的能力是函数式编程语言提供的强大特性。 + +> 从技术上讲，将另一个函数作为输入参数的函数称为 *高阶函数*。 +> （如果你喜欢幽默，就像有人曾经写过的那样，这就像说一个将另一个类的实例作为构造函数参数的类是一个高阶类。） + +## 函数、匿名函数和方法 + +正如您在这些示例中看到的，这是一个匿名函数： + +{% tabs fp-anonymous-function-short %} +{% tab 'Scala 2 and 3' %} +```scala +_ * 2 +``` +{% endtab %} +{% endtabs %} + +如 [高阶函数][hofs] 讨论中所示，上面的写法是下面语法的简写版本： + +{% tabs fp-anonymous-function-full %} +{% tab 'Scala 2 and 3' %} +```scala +(i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +像这样的函数被称为“匿名”，因为它们没有名字。 +如果你想给一个名字，只需将它分配给一个变量： + +{% tabs fp-function-assignement %} +{% tab 'Scala 2 and 3' %} +```scala +val double = (i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +现在你有了一个命名函数，一个分配给变量的函数。 +您可以像使用方法一样使用此函数： + +{% tabs fp-function-used-like-method %} +{% tab 'Scala 2 and 3' %} +```scala +double(2) // 4 +``` +{% endtab %} +{% endtabs %} + +在大多数情况下，`double` 是函数还是方法并不重要。 Scala 允许您以同样的方式对待它们。 +在幕后，让您像对待函数一样对待方法的 Scala 技术被称为 [Eta 表达式][eta]。 + +这种将函数作为变量无缝传递的能力是 Scala 等函数式编程语言的一个显着特征。 +正如您在本书中的 `map` 和 `filter` 示例中所见，将函数传递给其他函数的能力有助于您创建简洁且仍然可读的代码---*富有表现力*。 + +如果您对将函数作为参数传递给其他函数的过程不适应，可以尝试以下几个示例： + +{% tabs fp-function-as-values-example %} +{% tab 'Scala 2 and 3' %} +```scala +List("bob", "joe").map(_.toUpperCase) // List(BOB, JOE) +List("bob", "joe").map(_.capitalize) // List(Bob, Joe) +List("plum", "banana").map(_.length) // List(4, 6) + +val fruits = List("apple", "pear") +fruits.map(_.toUpperCase) // List(APPLE, PEAR) +fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R) + +val nums = List(5, 1, 3, 11, 7) +nums.map(_ * 2) // List(10, 2, 6, 22, 14) +nums.filter(_ > 3) // List(5, 11, 7) +nums.takeWhile(_ < 6) // List(5, 1, 3) +nums.sortWith(_ < _) // List(1, 3, 5, 7, 11) +nums.sortWith(_ > _) // List(11, 7, 5, 3, 1) + +nums.takeWhile(_ < 6).sortWith(_ < _) // List(1, 3, 5) +``` +{% endtab %} +{% endtabs %} + +[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %} +[eta]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_zh-cn/overviews/scala3-book/fp-immutable-values.md b/_zh-cn/overviews/scala3-book/fp-immutable-values.md new file mode 100644 index 0000000000..1d6b474daf --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fp-immutable-values.md @@ -0,0 +1,95 @@ +--- +title: 不可变值 +type: section +description: This section looks at the use of immutable values in functional programming. +language: zh-cn +num: 43 +previous-page: fp-what-is-fp +next-page: fp-pure-functions + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在纯函数式编程中，只使用不可变的值。 +在 Scala 中，这意味着： + +- 所有变量都创建为 `val` 字段 +- 仅使用不可变的集合类，例如 `List`、`Vector` 和不可变的 `Map` 和 `Set` 类 + +只使用不可变变量会引发一个有趣的问题：如果一切都是不可变的，那么任何东西都如何改变？ + +当谈到使用集合时，一个答案是你不会改变现有的集合。相反，您将函数应用于现有集合以创建新集合。 +这就是像 `map` 和 `filter` 这样的高阶函数的用武之地。 + +例如，假设你有一个名字列表——一个 `List[String]`——都是小写的，你想找到所有以字母 `"j"` 开头的名字，并且把找出来的名字大写。 +在 FP 中，您编写以下代码： + +{% tabs fp-list %} +{% tab 'Scala 2 and 3' %} +```scala +val a = List("jane", "jon", "mary", "joe") +val b = a.filter(_.startsWith("j")) + .map(_.capitalize) +``` +{% endtab %} +{% endtabs %} + +如图所示，您不会改变原始列表 `a`。 +相反，您将过滤和转换函数应用于 `a` 以创建一个新集合，并将该结果分配给新的不可变变量 `b` 。 + +同样，在 FP 中，您不会创建具有可变 `var` 构造函数参数的类。 +也就是说，你不要这样写： + +{% tabs fp--class-variables %} +{% tab 'Scala 2 and 3' %} +```scala +// don’t do this in FP +class Person(var firstName: String, var lastName: String) + --- --- +``` +{% endtab %} +{% endtabs %} + +相反，您通常创建 `case` 类，其构造函数参数默认为 `val`： + +{% tabs fp-immutable-case-class %} +{% tab 'Scala 2 and 3' %} +```scala +case class Person(firstName: String, lastName: String) +``` +{% endtab %} +{% endtabs %} + +现在你创建一个 `Person` 实例作为 `val` 字段： + +{% tabs fp-case-class-creation %} +{% tab 'Scala 2 and 3' %} +```scala +val reginald = Person("Reginald", "Dwight") +``` +{% endtab %} +{% endtabs %} + +然后，当您需要对数据进行更改时，您可以使用 `case` 类附带的 `copy` 方法来“在制作副本时更新数据”，如下所示： + +{% tabs fp-case-class-copy %} +{% tab 'Scala 2 and 3' %} +```scala +val elton = reginald.copy( + firstName = "Elton", // update the first name + lastName = "John" // update the last name +) +``` +{% endtab %} +{% endtabs %} + +还有其他处理不可变集合和变量的技术，但希望这些示例能让您尝试一下这些技术。 + +> 根据您的需要，您可以创建枚举、traits 或类，而不是 `case` 类。 +> 有关详细信息，请参阅[数据建模][modeling]一章。 + +[modeling]: {% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %} diff --git a/_zh-cn/overviews/scala3-book/fp-intro.md b/_zh-cn/overviews/scala3-book/fp-intro.md new file mode 100644 index 0000000000..4805401aec --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fp-intro.md @@ -0,0 +1,30 @@ +--- +title: 函数式编程 +type: chapter +description: This chapter provides an introduction to functional programming in Scala 3. +language: zh-cn +num: 41 +previous-page: collections-summary +next-page: fp-what-is-fp + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 允许您以面向对象编程 (OOP) 风格、函数式编程 (FP) 风格以及混合风格编写代码——结合使用这两种方法。 +正如 Scala 的创建者 Martin Odersky 所说，Scala 的本质是在类型化设置中融合了函数式编程和面向对象编程： + +- 逻辑函数 +- 模块化的对象 + +本章假设您熟悉 OOP 而不太熟悉 FP，因此它简要介绍了几个主要的函数式编程概念： + +- 什么是函数式编程？ +- 不可变值 +- 纯函数 +- 函数是值 +- 函数式错误处理 + diff --git a/_zh-cn/overviews/scala3-book/fp-pure-functions.md b/_zh-cn/overviews/scala3-book/fp-pure-functions.md new file mode 100644 index 0000000000..25fa4398ff --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fp-pure-functions.md @@ -0,0 +1,129 @@ +--- +title: 纯函数 +type: section +description: This section looks at the use of pure functions in functional programming. +language: zh-cn +num: 44 +previous-page: fp-immutable-values +next-page: fp-functions-are-values + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 提供的另一个帮助您编写函数式代码的特性是编写纯函数的能力。 +一个_纯函数_可以这样定义： + +- 函数 `f` 是纯函数，如果给定相同的输入 `x`，它总是返回相同的输出 `f(x)` +- 函数的输出_只_取决于它的输入变量和它的实现 +- 它只计算输出而不修改周围的世界 + +这意味着： +- 它不修改其输入参数 +- 它不会改变任何隐藏状态 +- 没有任何“后门”：不从外界读取数据（包括控制台、Web服务、数据库、文件等），也不向外界写入数据 + +作为这个定义的结果，任何时候你调用一个具有相同输入值的纯函数，你总是会得到相同的结果。 +例如，您可以使用输入值 `2` 无限次调用 `double` 函数，并且始终得到结果 `4`。 + +## 纯函数示例 + +给定这个定义，你可以想象， *scala.math._* 包中的这些方法是纯函数： + +- `abs` +- `ceil` +- `max` + +这些 `String` 方法也是纯函数： + +- `isEmpty` +- `length` +- `substring` + +Scala 集合类上的大多数方法也可以作为纯函数工作，包括 `drop`、`filter`、`map` 等等。 + +> 在 Scala 中，_函数_和_方法_几乎可以完全互换，因此即使我们使用行业通用术语“纯函数”，这个术语也可以用来描述函数和方法。 +> 如果您对如何像函数一样使用方法感兴趣，请参阅 [Eta 表达式][eta] 的讨论。 + +## 不纯函数示例 + +相反，以下函数是_不纯的_，因为它们违反了纯函数的定义。 + +- `println` -- 与控制台、文件、数据库、Web 服务、传感器等交互的方法都是不纯的。 +- `currentTimeMillis ` -- 与日期和时间相关的方法都是不纯的，因为它们的输出取决于输入参数以外的其他东西 +- `sys.error` -- 异常抛出方法是不纯的，因为它们不简单地返回结果 + +不纯函数通常会执行以下一项或多项操作： + +- 从隐藏状态读取，即它们访问的变量和数据不是作为输入参数明确地传递给函数 +- 写入隐藏状态 +- 改变他们给定的参数，或改变隐藏变量，例如类中包涵的字段 +- 与外界执行某种 I/O + +> 通常，您应该注意返回类型为 `Unit` 的函数。 +> 因为这些函数不返回任何东西，逻辑上你调用它的唯一原因是实现一些副作用。 +> 因此，这些功能的使用通常是不纯的。 + +## 但是需要不纯的函数... + +当然，如果一个应用程序不能读取或写入外部世界，它就不是很有用，所以人们提出以下建议： + +> 使用纯函数编写应用程序的核心，然后围绕该核心编写一个不纯的“包装器”以与外部世界交互。 +> 正如有人曾经说过的，这就像在纯蛋糕上加了一层不纯的糖霜。 + +重要的是要注意，有一些方法可以让与外界的不纯粹互动感觉更纯粹。 +例如，你会听说使用 `IO` Monad 来处理输入和输出。 +这些主题超出了本文档的范围，所以为了简单起见，这样认识 FP 会有所帮助：FP 应用程序有一个纯函数核心，还有其他一些函数把这些纯函数包装起来与外部世界交互。 + +## 编写纯函数 + +**注意**：在本节中，常见的行业术语“纯函数”通常用于指代 Scala 方法。 + +要在 Scala 中编写纯函数，只需使用 Scala 的方法语法编写它们（尽管您也可以使用 Scala 的函数语法）。 +例如，这是一个将给定输入值加倍的纯函数： + +{% tabs fp-pure-function %} +{% tab 'Scala 2 and 3' %} +```scala +def double(i: Int): Int = i * 2 +``` +{% endtab %} +{% endtabs %} + +如果您对递归感到满意，这是一个计算整数列表之和的纯函数： + +{% tabs fp-pure-recursive-function class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def sum(xs: List[Int]): Int = xs match { + case Nil => 0 + case head :: tail => head + sum(tail) +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def sum(xs: List[Int]): Int = xs match + case Nil => 0 + case head :: tail => head + sum(tail) +``` +{% endtab %} +{% endtabs %} + +如果您理解该代码，您会发现它符合纯函数定义。 + +## 要点 + +本节的第一个要点是纯函数的定义： + +> _纯函数_是仅依赖于其声明的输入及其实现来产生其输出的函数。 +> 它只计算其输出，不依赖或修改外部世界。 + +第二个要点是每个现实世界的应用程序都与外部世界交互。 +因此，考虑函数式程序的一种简化方法是，它们由一个纯函数核心组成，其他一些函数把这些纯函数包装起来与外部世界交互。 + +[eta]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_zh-cn/overviews/scala3-book/fp-summary.md b/_zh-cn/overviews/scala3-book/fp-summary.md new file mode 100644 index 0000000000..459b2d6f82 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fp-summary.md @@ -0,0 +1,30 @@ +--- +title: 总结 +type: section +description: This section summarizes the previous functional programming sections. +language: zh-cn +num: 47 +previous-page: fp-functional-error-handling +next-page: types-introduction + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章在比较高的层次上，对 Scala 中的函数式编程进行了介绍。 +涵盖的主题是： + +- 什么是函数式编程？ +- 不可变值 +- 纯函数 +- 函数是值 +- 函数式错误处理 + +如前所述，函数式编程是一个很大的话题，所以我们在本书中所能做的就是触及这些介绍性概念。 +有关详细信息，请参阅 [参考文档][reference]。 + +[reference]: {{ site.scala3ref }}/overview.html + diff --git a/_zh-cn/overviews/scala3-book/fp-what-is-fp.md b/_zh-cn/overviews/scala3-book/fp-what-is-fp.md new file mode 100644 index 0000000000..79370d450b --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fp-what-is-fp.md @@ -0,0 +1,33 @@ +--- +title: 什么是函数式编程？ +type: section +description: This section provides an answer to the question, what is functional programming? +language: zh-cn +num: 42 +previous-page: fp-intro +next-page: fp-immutable-values + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +[维基百科定义_函数式编程_](https://en.wikipedia.org/wiki/Functional_programming)如下： + +
            +

            函数式编程是一种编程范式，通过应用和组合函数来构建程序。 +它是一种声明式编程范例，其中函数定义是表达式树，每个表达式都返回一个值，而不是改变程序状态的命令式语句序列。

            +

             

            +

            在函数式编程中，函数被视为一等公民，这意味着它们可以绑定到名称（包括本地标识符）、作为参数传递以及从其他函数返回，就像任何其他数据类型一样。 +这允许以声明式和可组合的方式编写程序，其中小函数以模块化方式组合。

            +
            + +知道这样的情况对你很有帮助：有经验的函数式程序员非常倾向于将他们的代码视为数学，将纯函数组合在一起就像组合一系列代数方程一样。 + +当你编写函数式代码时，你会感觉自己像个数学家，一旦你理解了范式，你就会想编写总是返回_值_---而不是异常或空值---的纯函数，这样你就可以将它们组合（结合）在一起以创建解决方案。 +编写类似数学的方程式（表达式）的感觉是驱使您_只_使用纯函数和不可变值的动力，因为这就是您在代数和其他形式的数学中使用的东西。 + +函数式编程是一个很大的主题，没有简单的方法可以将整个主题浓缩为一章，但希望以下部分能够概述主要主题，并展示 Scala 为编写函数式代码提供的一些工具。 + diff --git a/_zh-cn/overviews/scala3-book/fun-anonymous-functions.md b/_zh-cn/overviews/scala3-book/fun-anonymous-functions.md new file mode 100644 index 0000000000..ec08a19e02 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-anonymous-functions.md @@ -0,0 +1,202 @@ +--- +title: 匿名函数 +type: section +description: This page shows how to use anonymous functions in Scala, including examples with the List class 'map' and 'filter' functions. +language: zh-cn +num: 29 +previous-page: fun-intro +next-page: fun-function-variables + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +匿名函数（也称为 *lambda*）是作为参数传递给高阶函数的代码块。 +维基百科将 [匿名函数](https://en.wikipedia.org/wiki/Anonymous_function) 定义为“未绑定到标识符的函数定义”。 + +例如，给定这样的列表： + +{% tabs fun-anonymous-1 %} +{% tab 'Scala 2 and 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +您可以通过使用 `List` 类 `map` 方法和自定义匿名函数将 `ints` 中的每个元素加倍来创建一个新列表： + +{% tabs fun-anonymous-2 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map(_ * 2) // List(2, 4, 6) +``` +{% endtab %} +{% endtabs %} + +如注释所示，`doubledInts` 包含列表`List(2, 4, 6)`。 +在该示例中，这部分代码是一个匿名函数： + +{% tabs fun-anonymous-3 %} +{% tab 'Scala 2 and 3' %} +```scala +_ * 2 +``` +{% endtab %} +{% endtabs %} + +这是“将给定元素乘以 2”的简写方式。 + +## 更长的形式 + +一旦你熟悉了 Scala，你就会一直使用这种形式来编写匿名函数，这些函数在函数的一个位置使用一个变量。 +但如果你愿意，你也可以用更长的形式来写它们，所以除了写这段代码： + +{% tabs fun-anonymous-4 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +您也可以使用以下形式编写它： + +{% tabs fun-anonymous-5 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +val doubledInts = ints.map((i) => i * 2) +val doubledInts = ints.map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +所有这些行的含义完全相同：将 `ints` 中的每个元素加倍以创建一个新列表 `doubledInts`。 +（稍后会解释每种形式的语法。） + +如果您熟悉 Java，了解这些 `map` 示例与以下 Java 代码等价可能会有所帮助： + +{% tabs fun-anonymous-5-b %} +{% tab 'Java' %} +```java +List ints = List.of(1, 2, 3); +List doubledInts = ints.stream() + .map(i -> i * 2) + .collect(Collectors.toList()); +``` +{% endtab %} +{% endtabs %} + +## 缩短匿名函数 + +当你想要明确时，你可以使用这个长格式编写一个匿名函数： + +{% tabs fun-anonymous-6 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +``` +{% endtab %} +{% endtabs %} + +该表达式中的匿名函数是这样的： + +{% tabs fun-anonymous-7 %} +{% tab 'Scala 2 and 3' %} +```scala +(i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +如果您不熟悉这种语法，将 `=>` 符号视为转换器会有所帮助，因为表达式使用 `=>` 符号右侧的算法（在这种情况下，一个将 `Int` 加倍的表达式）把符号左侧的参数列表（名为 `i` 的 `Int` 变量) *转换*为新结果。 + +### 缩短该表达式 + +这种长形式可以缩短，如以下步骤所示。 +首先，这是最长和最明确的形式： + +{% tabs fun-anonymous-8 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +``` +{% endtab %} +{% endtabs %} + +因为 Scala 编译器可以从 `ints` 中的数据推断 `i` 是一个 `Int`，所以可以删除 `Int` 声明： + +{% tabs fun-anonymous-9 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map((i) => i * 2) +``` +{% endtab %} +{% endtabs %} + +因为只有一个参数，所以不需要在参数 `i` 周围的括号： + +{% tabs fun-anonymous-10 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +因为当参数在函数中只出现一次时，Scala 允许您使用 `_` 符号而不是变量名，所以代码可以进一步简化： + +{% tabs fun-anonymous-11 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +### 变得更短 + +在其他示例中，您可以进一步简化匿名函数。 +例如，从最显式的形式开始，您可以使用带有 `List` 类 `foreach` 方法的匿名函数打印 `ints` 中的每个元素： + +{% tabs fun-anonymous-12 %} +{% tab 'Scala 2 and 3' %} +```scala +ints.foreach((i: Int) => println(i)) +``` +{% endtab %} +{% endtabs %} + +和以前一样，不需要 `Int` 声明，因为只有一个参数，所以不需要 `i` 周围的括号： + +{% tabs fun-anonymous-13 %} +{% tab 'Scala 2 and 3' %} +```scala +ints.foreach(i => println(i)) +``` +{% endtab %} +{% endtabs %} + +因为 `i` 在函数体中只使用一次，表达式可以进一步简化为 `_` 符号： + +{% tabs fun-anonymous-14 %} +{% tab 'Scala 2 and 3' %} +```scala +ints.foreach(println(_)) +``` +{% endtab %} +{% endtabs %} + +最后，如果一个匿名函数由一个接受单个参数的方法调用组成，您不需要显式命名和指定参数，因此您最终可以只写方法的名称（此处为 `println`）： + +{% tabs fun-anonymous-15 %} +{% tab 'Scala 2 and 3' %} +```scala +ints.foreach(println) +``` +{% endtab %} +{% endtabs %} + diff --git a/_zh-cn/overviews/scala3-book/fun-eta-expansion.md b/_zh-cn/overviews/scala3-book/fun-eta-expansion.md new file mode 100644 index 0000000000..562ed0074e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-eta-expansion.md @@ -0,0 +1,114 @@ +--- +title: Eta 扩展 +type: section +description: This page discusses Eta Expansion, the Scala technology that automatically and transparently converts methods into functions. +language: zh-cn +num: 31 +previous-page: fun-function-variables +next-page: fun-hofs + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +当你查看 Scala 集合类的 `map` 方法的 Scaladoc 时，你会看到它被定义为接受一个_函数_： + +{% tabs fun_1 %} +{% tab 'Scala 2 and 3' for=fun_1 %} +```scala +def map[B](f: (A) => B): List[B] + ------------ +``` +{% endtab %} +{% endtabs %} + +事实上，Scaladoc 明确指出，“`f` 是应用于每个元素的_函数_。” +但尽管如此，你可以通过某种方式将_方法_传递给 `map`，它仍然有效： + +{% tabs fun_2 %} +{% tab 'Scala 2 and 3' for=fun_2 %} +```scala +def times10(i: Int) = i * 10 // a method +List(1, 2, 3).map(times10) // List(10,20,30) +``` +{% endtab %} +{% endtabs %} + +你有没有想过这是如何工作的——如何将_方法_传递给需要_函数_的`map`？ + +这背后的技术被称为_Eta Expansion_。 +它将 _方法类型_的表达式转换为 _函数类型_的等效表达式，并且它无缝而安静地完成了。 + +## 方法和函数的区别 + +{% comment %} +NOTE: I got the following “method” definition from this page (https://dotty.epfl.ch/docs/reference/changed-features/eta-expansion-spec.html), but I’m not sure it’s 100% accurate now that 方法 can exist outside of classes/traits/objects. +I’ve made a few changes to that description that I hope are more accurate and up to date. +{% endcomment %} + +从历史上看，_方法_一直是类定义的一部分，尽管在 Scala 3 中您现在可以拥有类之外的方法，例如 [Toplevel definitions][toplevel] 和 [extension 方法][extension]。 + +与方法不同，_函数_本身就是完整的对象，使它们成为第一等的实体。 + +它们的语法也不同。 +此示例说明如何定义执行相同任务的方法和函数，确定给定整数是否为偶数： + +{% tabs fun_3 %} +{% tab 'Scala 2 and 3' for=fun_3 %} +```scala +def isEvenMethod(i: Int) = i % 2 == 0 // a method +val isEvenFunction = (i: Int) => i % 2 == 0 // a function +``` +{% endtab %} +{% endtabs %} + +该函数确实是一个对象，因此您可以像使用任何其他变量一样使用它，例如将其放入列表中： + +{% tabs fun_4 %} +{% tab 'Scala 2 and 3' for=fun_4 %} +```scala +val functions = List(isEvenFunction) +``` +{% endtab %} +{% endtabs %} + + +{% tabs fun_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=fun_5 %} +```scala +// this example shows the Scala 2 error message +val methods = List(isEvenMethod) + ^ +error: missing argument list for method isEvenMethod +Unapplied methods are only converted to functions when a function type is expected. +You can make this conversion explicit by writing `isEvenMethod _` or `isEvenMethod(_)` instead of `isEvenMethod`. +``` + +相反，从技术上讲，方法不是对象，因此在 Scala 2 中，您不能将方法放入 `List` 中，至少不能直接放入，如下例所示： + +{% endtab %} +{% tab 'Scala 3' for=fun_5 %} + +```scala +val functions = List(isEvenFunction) // works +val methods = List(isEvenMethod) // works +``` + +Scala 3 的重要部分是改进了 Eta 扩展技术，所以现在当您尝试将方法当作变量用，它是可以工作的---您不必自己处理手动转换： + +{% endtab %} +{% endtabs %} + +就这本入门书而言，需要了解的重要事项是： + +- Eta Expansion 是 Scala 技术，让您可以像使用函数一样使用方法 +- 该技术在 Scala 3 中得到了改进，几乎完全无缝 + +有关其工作原理的更多详细信息，请参阅参考文档中的 [Eta 扩展页面][eta_expansion]。 + +[eta_expansion]: {{ site.scala3ref }}/changed-features/eta-expansion.html +[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +[toplevel]: {% link _zh-cn/overviews/scala3-book/taste-toplevel-definitions.md %} diff --git a/_zh-cn/overviews/scala3-book/fun-function-variables.md b/_zh-cn/overviews/scala3-book/fun-function-variables.md new file mode 100644 index 0000000000..e4591ef2ee --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-function-variables.md @@ -0,0 +1,166 @@ +--- +title: 函数变量 +type: section +description: This page shows how to use anonymous functions in Scala, including examples with the List class 'map' and 'filter' functions. +language: zh-cn +num: 30 +previous-page: fun-anonymous-functions +next-page: fun-eta-expansion + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +从上一节回到这个例子： + +{% tabs fun-function-variables-1 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +``` +{% endtab %} +{% endtabs %} + +我们注意到这部分表达式是一个匿名函数： + +{% tabs fun-function-variables-2 %} +{% tab 'Scala 2 and 3' %} +```scala +(i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +它被称为 *匿名* 的原因是它没有分配给变量，因此没有名称。 + +但是，可以将匿名函数（也称为*函数字面量*）分配给变量以创建*函数变量*： + +{% tabs fun-function-variables-3 %} +{% tab 'Scala 2 and 3' %} +```scala +val double = (i: Int) => i * 2 +``` +{% endtab %} +{% endtabs %} + +这将创建一个名为 `double` 的函数变量。 +在这个表达式中，原始函数字面量在 `=` 符号的右侧： + +{% tabs fun-function-variables-4 %} +{% tab 'Scala 2 and 3' %} +```scala +val double = (i: Int) => i * 2 + ----------------- +``` +{% endtab %} +{% endtabs %} + +新变量名在左侧： + +{% tabs fun-function-variables-5 %} +{% tab 'Scala 2 and 3' %} +```scala +val double = (i: Int) => i * 2 + ------ +``` +{% endtab %} +{% endtabs %} + +并且函数的参数列表在此处加下划线： + +{% tabs fun-function-variables-6 %} +{% tab 'Scala 2 and 3' %} +```scala +val double = (i: Int) => i * 2 + -------- +``` +{% endtab %} +{% endtabs %} + +就像方法的参数列表一样，这意味着 `double` 函数有一个参数，一个名为 `i` 的 `Int`。 +你可以在 REPL 中看到 `double` 的类型为 `Int => Int`，这意味着它接受一个 `Int` 参数并返回一个 `Int`： + +{% tabs fun-function-variables-7 %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val double = (i: Int) => i * 2 +val double: Int => Int = ... +``` +{% endtab %} +{% endtabs %} + +### 调用函数 + +现在你可以像这样调用`double`函数： + +{% tabs fun-function-variables-8 %} +{% tab 'Scala 2 and 3' %} +```scala +val x = double(2) // 4 +``` +{% endtab %} +{% endtabs %} + +您还可以将 `double` 传递给 `map` 调用： + +{% tabs fun-function-variables-9 %} +{% tab 'Scala 2 and 3' %} +```scala +List(1, 2, 3).map(double) // List(2, 4, 6) +``` +{% endtab %} +{% endtabs %} + +此外，当您有 `Int => Int` 类型的其他函数时： + +{% tabs fun-function-variables-10 %} +{% tab 'Scala 2 and 3' %} +```scala +val triple = (i: Int) => i * 3 +``` +{% endtab %} +{% endtabs %} + +您可以将它们存储在 `List` 或 `Map` 中： + +{% tabs fun-function-variables-11 %} +{% tab 'Scala 2 and 3' %} +```scala +val functionList = List(double, triple) + +val functionMap = Map( + "2x" -> double, + "3x" -> triple +) +``` +{% endtab %} +{% endtabs %} + +如果将这些表达式粘贴到 REPL 中，您会看到它们具有以下类型： + +{% tabs fun-function-variables-12 %} +{% tab 'Scala 2 and 3' %} +```` +// a List that contains functions of the type `Int => Int` +functionList: List[Int => Int] + +// a Map whose keys have the type `String`, and whose +// values have the type `Int => Int` +functionMap: Map[String, Int => Int] +```` +{% endtab %} +{% endtabs %} + +## 关键点 + +这里的重要部分是： + +- 要创建函数变量，只需将变量名分配给函数字面量 +- 一旦你有了一个函数，你可以像对待任何其他变量一样对待它，即像一个`String`或`Int`变量 + +并且由于 Scala 3 中改进的 [Eta Expansion][eta_expansion] 函数式，您可以以相同的方式处理 *方法*。 + +[eta_expansion]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_zh-cn/overviews/scala3-book/fun-hofs.md b/_zh-cn/overviews/scala3-book/fun-hofs.md new file mode 100644 index 0000000000..a0fda317b8 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-hofs.md @@ -0,0 +1,384 @@ +--- +title: 高阶函数 +type: section +description: This page demonstrates how to create and use higher-order functions in Scala. +language: zh-cn +num: 32 +previous-page: fun-eta-expansion +next-page: fun-write-map-function + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +高阶函数 (HOF) 通常定义为这类函数，它 (a) 将其他函数作为输入参数或 (b) 返回函数作为结果。 +在 Scala 中，HOF 是可能的，因为函数是一等值。 + +需要注意的是，虽然我们在本文档中使用了常见的行业术语“高阶函数”，但在 Scala 中，该短语同时适用于 *方法* 和 *函数*。 +得益于 Scala 的 [Eta 扩展技术][eta_expansion]，它们通常可以在相同的地方使用。 + +## 从消费者到创造者 + +在本书到目前为止的示例中，您已经了解了如何成为方法的*消费者*，该方法将其他函数作为输入参数，例如使用诸如 `map` 和 `filter` 之类的 HOF。 +在接下来的几节中，您将了解如何成为 HOF 的*创造者*，包括： + +- 如何编写将函数作为输入参数的方法 +- 如何从方法中返回函数 + +在这个过程中你会看到： + +- 用于定义函数输入参数的语法 +- 引用函数后如何调用它 + +作为本次讨论的一个有益的副作用，一旦您对这种语法感到满意，您将使用它来定义函数参数、匿名函数和函数变量，并且也更容易阅读有关高阶函数的 Scaladoc。 + +## 理解过滤器的 Scaladoc + +要了解高阶函数的工作原理，深入研究一个示例会有所帮助。 +例如，您可以通过查看 Scaladoc 来了解 `filter` 接受的函数类型。 +这是 `List[A]` 类中的 `filter` 定义： + +{% tabs filter-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def filter(p: (A) => Boolean): List[A] +``` +{% endtab %} +{% endtabs %} + +这表明 `filter` 是一个接受名为 `p` 的函数参数的方法。 +按照惯例，`p` 代表 *谓词（predicate）*，它只是一个返回 `Boolean` 值的函数。 +所以 `filter` 将谓词 `p` 作为输入参数，并返回一个 `List[A]`，其中 `A` 是列表中保存的类型；如果你在 `List[Int]` 上调用 `filter`，`A` 是 `Int` 类型。 + +在这一点上，如果你不知道 `filter` 方法的用途，你只知道它的算法以某种方式使用谓词 `p` 创建并返回 `List[A]`。 + +具体看函数参数 `p`，这部分 `filter` 的描述： + +{% tabs filter-definition_1 %} +{% tab 'Scala 2 and 3' %} +```scala +p: (A) => Boolean +``` +{% endtab %} +{% endtabs %} + +意味着您传入的任何函数都必须将类型 `A` 作为输入参数并返回一个 `Boolean` 。 +因此，如果您的列表是 `List[Int]`，则可以将通用类型 `A` 替换为 `Int`，并像这样读取该签名： + +{% tabs filter-definition_2 %} +{% tab 'Scala 2 and 3' %} +```scala +p: (Int) => Boolean +``` +{% endtab %} +{% endtabs %} + +因为 `isEven` 具有这种类型——它将输入 `Int` 转换为结果 `Boolean`——它可以与 `filter` 一起使用。 + +{% comment %} +NOTE: (A low-priority issue): The next several sections can be condensed. +{% endcomment %} + +## 编写接受函数参数的方法 + +鉴于此背景，让我们开始编写将函数作为输入参数的方法。 + +**注意：**为了使下面的讨论更清楚，我们将您编写的代码称为*方法*，将您作为输入参数接受的代码称为*函数*。 + +### 第一个例子 + +要创建一个接受函数参数的方法，您所要做的就是： + +1. 在方法的参数列表中，定义要接受的函数的签名 +2. 在你的方法中使用那个函数 + +为了证明这一点，这里有一个方法，它接受一个名为 `f` 的输入参数，其中 `f` 是一个函数： + +{% tabs sayHello-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def sayHello(f: () => Unit): Unit = f() +``` +{% endtab %} +{% endtabs %} + +这部分代码---*类型签名*---声明 `f` 是一个函数，并定义了 `sayHello` 方法将接受的函数类型： + +{% tabs sayHello-definition_1 %} +{% tab 'Scala 2 and 3' %} +```scala +f: () => Unit +``` +{% endtab %} +{% endtabs %} + +这是它的工作原理： + +- `f` 是函数输入参数的名称。 + 这就像将 `String` 参数命名为 `s` 或 `Int` 参数命名为 `i`。 +- `f` 的类型签名指定此方法将接受的函数的 *类型*。 +- `f` 签名的 `()` 部分（在 `=>` 符号的左侧）表明 `f` 不接受输入参数。 +- 签名的 `Unit` 部分（在 `=>` 符号的右侧）表示 `f` 不应返回有意义的结果。 +- 回顾 `sayHello` 方法的主体（在 `=` 符号的右侧），那里的 `f()` 语句调用传入的函数。 + +现在我们已经定义了 `sayHello`，让我们创建一个函数来匹配 `f` 的签名，以便我们可以测试它。 +以下函数不接受任何输入参数并且不返回任何内容，因此它匹配 `f` 的类型签名： + +{% tabs helloJoe-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def helloJoe(): Unit = println("Hello, Joe") +``` +{% endtab %} +{% endtabs %} + +因为类型签名匹配，你可以将 `helloJoe` 传递给 `sayHello`： + +{% tabs sayHello-usage %} +{% tab 'Scala 2 and 3' %} +```scala +sayHello(helloJoe) // prints "Hello, Joe" +``` +{% endtab %} +{% endtabs %} + +如果您以前从未这样做过，那么恭喜您： +您刚刚定义了一个名为 `sayHello` 的方法，它接受一个函数作为输入参数，然后在其方法体中调用该函数。 + +### sayHello 可以带很多函数 + +重要的是要知道这种方法的美妙之处并不是说​​ `sayHello` 可以将 *一个* 函数作为输入参数；而在于它可以采用与 `f` 签名匹配的 *任意一个* 函数。 +例如，因为下一个函数没有输入参数并且不返回任何内容，所以它也适用于 `sayHello`： + +{% tabs bonjourJulien-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def bonjourJulien(): Unit = println("Bonjour, Julien") +``` +{% endtab %} +{% endtabs %} + +它在 REPL 中： + +{% tabs bonjourJulien-usage %} +{% tab 'Scala 2 and 3' %} +```` +scala> sayHello(bonjourJulien) +Bonjour, Julien +```` +{% endtab %} +{% endtabs %} + +这是一个好的开始。 +现在唯一要做的就是查看更多示例，了解如何为函数参数定义不同的类型签名。 + +## 定义函数输入参数的通用语法 + +在这种方法中： + +{% tabs sayHello-definition-2 %} +{% tab 'Scala 2 and 3' %} +```scala +def sayHello(f: () => Unit): Unit +``` +{% endtab %} +{% endtabs %} + +我们注意到 `f` 的类型签名是： + +{% tabs sayHello-definition-2_1 %} +{% tab 'Scala 2 and 3' %} +```scala +() => Unit +``` +{% endtab %} +{% endtabs %} + +我们知道这意味着，“一个没有输入参数并且不返回任何有意义的东西的函数（由 `Unit` 给出）。” + +为了演示更多类型签名示例，这里有一个函数，它接受一个 `String` 参数并返回一个 `Int`： + +{% tabs sayHello-definition-2_2 %} +{% tab 'Scala 2 and 3' %} +```scala +f: (String) => Int +``` +{% endtab %} +{% endtabs %} + +什么样的函数接受一个字符串并返回一个整数？ +“字符串长度”和校验和等函数就是两个例子。 + +同样，此函数接受两个 `Int` 参数并返回一个 `Int`： + +{% tabs sayHello-definition-2_3 %} +{% tab 'Scala 2 and 3' %} +```scala +f: (Int, Int) => Int +``` +{% endtab %} +{% endtabs %} + +你能想象什么样的函数匹配那个签名？ + +答案是任何接受两个 `Int` 输入参数并返回 `Int` 的函数都与该签名匹配，因此所有这些“函数”（实际上是方法）都是匹配的： + +{% tabs add-sub-mul-definitions %} +{% tab 'Scala 2 and 3' %} +```scala +def add(a: Int, b: Int): Int = a + b +def subtract(a: Int, b: Int): Int = a - b +def multiply(a: Int, b: Int): Int = a * b +``` +{% endtab %} +{% endtabs %} + +正如您可以从这些示例中推断出的，定义函数参数类型签名的一般语法是： + +{% tabs add-sub-mul-definitions_1 %} +{% tab 'Scala 2 and 3' %} +```scala +variableName: (parameterTypes ...) => returnType +``` +{% endtab %} +{% endtabs %} + +> 因为函数式编程就像创建和组合一系列代数方程，所以在设计函数和应用程序时通常会考虑*很多*类型。 +> 你可能会说你“在类型中思考”。 + +## 将函数参数与其他参数一起使用 + +为了使 HOF 真正有用，它们还需要一些数据来处理。 +对于像 `List` 这样的类，它的 `map` 方法已经有数据可以处理：`List` 中的数据。 +但是对于没有自己数据的独立 HOF，它也应该接受数据作为其他输入参数。 + +例如，这是一个名为 `executeNTimes` 的方法，它有两个输入参数：一个函数和一个 `Int`： + +{% tabs executeNTimes-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def executeNTimes(f: () => Unit, n: Int): Unit = + for (i <- 1 to n) f() +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def executeNTimes(f: () => Unit, n: Int): Unit = + for i <- 1 to n do f() +``` +{% endtab %} +{% endtabs %} + +如代码所示，`executeNTimes` 执行了`f` 函数 `n` 次。 +因为像这样的简单 `for` 循环没有返回值，`executeNTimes` 返回 `Unit`。 + +要测试 `executeNTimes`，请定义一个匹配 `f` 签名的方法： + +{% tabs helloWorld-definition %} +{% tab 'Scala 2 and 3' %} +```scala +// a method of type `() => Unit` +def helloWorld(): Unit = println("Hello, world") +``` +{% endtab %} +{% endtabs %} + +然后将该方法与 `Int` 一起传递给`executeNTimes`： + +{% tabs helloWorld-usage %} +{% tab 'Scala 2 and 3' %} +```` +scala> executeNTimes(helloWorld, 3) +Hello, world +Hello, world +Hello, world +```` +{% endtab %} +{% endtabs %} + +优秀。 +`executeNTimes` 方法执行 `helloWorld` 函数 3 次。 + +### 需要多少参数 + +您的方法可以继续变得尽可能复杂。 +例如，此方法采用类型为 `(Int, Int) => Int` 的函数，以及两个输入参数： + +{% tabs executeAndPrint-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def executeAndPrint(f: (Int, Int) => Int, i: Int, j: Int): Unit = + println(f(i, j)) +``` +{% endtab %} +{% endtabs %} + +因为这些 `sum` 和 `multiply` 方法与该类型签名匹配，所以它们可以与两个 `Int` 值一起传递到 `executeAndPrint` 中： + +{% tabs executeAndPrint-usage %} +{% tab 'Scala 2 and 3' %} +```scala +def sum(x: Int, y: Int) = x + y +def multiply(x: Int, y: Int) = x * y + +executeAndPrint(sum, 3, 11) // prints 14 +executeAndPrint(multiply, 3, 9) // prints 27 +``` +{% endtab %} +{% endtabs %} + +## 函数类型签名一致性 + +学习 Scala 的函数类型签名的一个好处是，用于定义函数输入参数的语法与用于编写函数字面量的语法相同。 + +例如，如果你要编写一个计算两个整数之和的函数，你可以这样写： + +{% tabs f-val-definition %} +{% tab 'Scala 2 and 3' %} +```scala +val f: (Int, Int) => Int = (a, b) => a + b +``` +{% endtab %} +{% endtabs %} + +该代码由类型签名组成： + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ----------------- +```` + +输入参数： + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ------ +```` + +和函数体： + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ----- +```` + +这里展示了 Scala 的一致性，这里的函数类型： + +```` +val f: (Int, Int) => Int = (a, b) => a + b + ----------------- +```` + +与用于定义函数输入参数的类型签名相同： + +```` +def executeAndPrint(f: (Int, Int) => Int, ... + ----------------- +```` + +一旦你熟悉了这种语法，你就会用它来定义函数参数、匿名函数和函数变量，而且当你阅读 Scaladoc 中有关高阶函数的内容时，这些内容变得更容易了。 + +[eta_expansion]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %} diff --git a/_zh-cn/overviews/scala3-book/fun-intro.md b/_zh-cn/overviews/scala3-book/fun-intro.md new file mode 100644 index 0000000000..90d45c4387 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-intro.md @@ -0,0 +1,17 @@ +--- +title: 函数 +type: chapter +description: This chapter looks at all topics related to functions in Scala 3. +language: zh-cn +num: 28 +previous-page: methods-summary +next-page: fun-anonymous-functions + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +上一章介绍了 Scala *方法*，本章深入研究 *函数*。 +涵盖的主题包括匿名函数、函数变量和高阶函数 (HOF)，包括如何创建自己的 HOF。 diff --git a/_zh-cn/overviews/scala3-book/fun-summary.md b/_zh-cn/overviews/scala3-book/fun-summary.md new file mode 100644 index 0000000000..efc747c7ce --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-summary.md @@ -0,0 +1,40 @@ +--- +title: 总结 +type: section +description: This page shows how to use anonymous functions in Scala, including examples with the List class 'map' and 'filter' functions. +language: zh-cn +num: 35 +previous-page: fun-write-method-returns-function +next-page: packaging-imports + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +这是一个很长的章节，所以让我们回顾一下所涵盖的关键点。 + +我们通常这样定义高阶函数 (HOF)，它以其他函数作为输入参数或将函数作为其值。 +在 Scala 中这是可能的，因为函数是一等值。 + +浏览这些部分，首先您会看到： + +- 您可以将匿名函数编写为小代码片段 +- 您可以将它们传递给集合类上的几十个 HOF（方法），即像 `filter`、`map` 等方法。 +- 使用这些小代码片段和强大的 HOF，您只需少量代码即可创建大量的函数 + +在查看了匿名函数和 HOF 之后，您看到了： + +- 函数变量只是绑定到变量的匿名函数 + +在了解如何成为 HOF 的*消费者*之后，您将了解如何成为 HOF 的*创造者*。 +具体来说，您看到了： + +- 如何编写将函数作为输入参数的方法 +- 如何从方法中返回函数 + +本章的一个有益的副作用是您看到了许多关于如何为函数声明类型签名的示例。 +这样做的好处是，您可以使用相同的语法来定义函数参数、匿名函数和函数变量，而且对于 `map`、`filter` 等高阶函数，阅读 Scaladoc 也变得更容易。 + diff --git a/_zh-cn/overviews/scala3-book/fun-write-map-function.md b/_zh-cn/overviews/scala3-book/fun-write-map-function.md new file mode 100644 index 0000000000..3ba7e44c1b --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-write-map-function.md @@ -0,0 +1,140 @@ +--- +title: 自定义 map 函数 +type: section +description: This page demonstrates how to create and use higher-order functions in Scala. +language: zh-cn +num: 33 +previous-page: fun-hofs +next-page: fun-write-method-returns-function + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +现在您已经了解了如何编写自己的高阶函数，让我们快速浏览一个更真实的示例。 + +想象一下，`List` 类没有自己的 `map` 方法，而您想编写自己的方法。 +创建函数的第一步是准确地陈述问题。 +只关注 `List[Int]`，你说： + +> 我想编写一个 `map` 方法，该方法可用于将函数应用于给定的 `List[Int]` 中的每个元素，并将转换后的元素作为新列表返回。 + +鉴于该声明，您开始编写方法签名。 +首先，您知道您想接受一个函数作为参数，并且该函数应该将 `Int` 转换为某种通用类型 `A`，因此您编写： + +{% tabs map-accept-func-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def map(f: (Int) => A) +``` +{% endtab %} +{% endtabs %} + +使用泛型类型的语法要求在参数列表之前声明该类型符号，因此您添加： + +{% tabs map-type-symbol-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def map[A](f: (Int) => A) +``` +{% endtab %} +{% endtabs %} + +接下来，您知道 `map` 也应该接受 `List[Int]`： + +{% tabs map-list-int-param-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]) +``` +{% endtab %} +{% endtabs %} + +最后，您还知道 `map` 返回一个转换后的 `List`，其中包含泛型类型 `A` 的元素： + +{% tabs map-with-return-type-definition %} +{% tab 'Scala 2 and 3' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]): List[A] = ??? +``` +{% endtab %} +{% endtabs %} + +这负责方法签名。 +现在您所要做的就是编写方法体。 +`map` 方法将它赋予的函数应用于它赋予的列表中的每个元素，以生成一个新的、转换的列表。 +一种方法是使用 `for` 表达式： + +{% tabs for-definition class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +for (x <- xs) yield f(x) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +for x <- xs yield f(x) +``` +{% endtab %} +{% endtabs %} + +`for` 表达式通常使代码出奇地简单，对于我们的目的，它最终成为整个方法体。 + +把它和方法签名放在一起，你现在有了一个独立的 `map` 方法，它与 `List[Int]` 一起工作： + +{% tabs map-function class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]): List[A] = + for (x <- xs) yield f(x) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def map[A](f: (Int) => A, xs: List[Int]): List[A] = + for x <- xs yield f(x) +``` +{% endtab %} +{% endtabs %} + +### 使其泛型化 + +作为奖励，请注意 `for` 表达式不做任何取决于 `List` 中的类型为 `Int` 的事情。 +因此，您可以将类型签名中的 `Int` 替换为泛型类型参数 `B`： + +{% tabs map-function-full-generic class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def map[A, B](f: (B) => A, xs: List[B]): List[A] = + for (x <- xs) yield f(x) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def map[A, B](f: (B) => A, xs: List[B]): List[A] = + for x <- xs yield f(x) +``` +{% endtab %} +{% endtabs %} + +现在你有了一个适用于任何 `List` 的 `map` 方法。 + +这些示例表明 `map` 可以按需要工作： + +{% tabs map-use-example %} +{% tab 'Scala 2 and 3' %} +```scala +def double(i : Int) = i * 2 +map(double, List(1, 2, 3)) // List(2, 4, 6) + +def strlen(s: String) = s.length +map(strlen, List("a", "bb", "ccc")) // List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +现在您已经了解了如何编写接受函数作为输入参数的方法，让我们看看返回函数的方法。 + diff --git a/_zh-cn/overviews/scala3-book/fun-write-method-returns-function.md b/_zh-cn/overviews/scala3-book/fun-write-method-returns-function.md new file mode 100644 index 0000000000..84e3460b6f --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-write-method-returns-function.md @@ -0,0 +1,244 @@ +--- +title: 创建可以返回函数的方法 +type: section +description: This page demonstrates how to create and use higher-order functions in Scala. +language: zh-cn +num: 34 +previous-page: fun-write-map-function +next-page: fun-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +由于 Scala 的一致性，编写一个返回函数的方法与您在前几节中看到的所有内容相似。 +例如，假设您想编写一个返回函数的 `greet` 方法。 +我们再次从问题陈述开始： + +> 我想创建一个返回函数的 `greet` 方法。 +> 该函数将接受一个字符串参数并使用 `println` 打印它。 +> 为了简化第一个示例，`greet` 不会接受任何输入参数；它只会构建一个函数并返回它。 + +鉴于该声明，您可以开始构建 `greet`。 +你知道这将是一种方法： + +{% tabs fun-write-method-returns-function-1 %} +{% tab 'Scala 2 and 3' %} +```scala +def greet() +``` +{% endtab %} +{% endtabs %} + +您还知道此方法将返回一个函数，该函数 (a) 采用 `String` 参数，并且 (b) 使用 `println` 打印该字符串。 +因此，该函数的类型为 `String => Unit`： + +{% tabs fun-write-method-returns-function-2 %} +{% tab 'Scala 2 and 3' %} +```scala +def greet(): String => Unit = ??? + ---------------- +``` +{% endtab %} +{% endtabs %} + +现在你只需要一个方法体。 +您知道该方法需要返回一个函数，并且该函数接受一个“字符串”并打印它。 +此匿名函数与该描述匹配： + +{% tabs fun-write-method-returns-function-3 %} +{% tab 'Scala 2 and 3' %} +```scala +(name: String) => println(s"Hello, $name") +``` +{% endtab %} +{% endtabs %} + +现在您只需从方法中返回该函数： + +{% tabs fun-write-method-returns-function-4 %} +{% tab 'Scala 2 and 3' %} +```scala +// a method that returns a function +def greet(): String => Unit = + (name: String) => println(s"Hello, $name") +``` +{% endtab %} +{% endtabs %} + +因为这个方法返回一个函数，所以你可以通过调用`greet()`来得到这个函数。 +这是在 REPL 中做的一个很好的步骤，因为它验证了新函数的类型： + +{% tabs fun-write-method-returns-function-5 %} +{% tab 'Scala 2 and 3' %} +```` +scala> val greetFunction = greet() +val greetFunction: String => Unit = Lambda.... + ----------------------------------------- +```` +{% endtab %} +{% endtabs %} + +现在你可以调用`greetFunction`了： + +{% tabs fun-write-method-returns-function-6 %} +{% tab 'Scala 2 and 3' %} +```scala +greetFunction("Joe") // prints "Hello, Joe" +``` +{% endtab %} +{% endtabs %} + +恭喜，您刚刚创建了一个返回函数的方法，然后执行了该函数。 + +## 改进方法 + +如果您可以传递问候语，我们的方法会更有用，所以让我们这样做。 +您所要做的就是将问候语作为参数传递给 `greet` 方法，并在 `println` 中的字符串中使用它： + +{% tabs fun-write-method-returns-function-7 %} +{% tab 'Scala 2 and 3' %} +```scala +def greet(theGreeting: String): String => Unit = + (name: String) => println(s"$theGreeting, $name") +``` +{% endtab %} +{% endtabs %} + +现在，当您调用您的方法时，该过程更加灵活，因为您可以更改问候语。 +当您从此方法创建函数时，它是这样的： + +{% tabs fun-write-method-returns-function-8 %} +{% tab 'Scala 2 and 3' %} +```` +scala> val sayHello = greet("Hello") +val sayHello: String => Unit = Lambda..... + ---------------------- +```` +{% endtab %} +{% endtabs %} + +REPL 类型签名输出显示 `sayHello` 是一个接受 `String` 输入参数并返回 `Unit`（无）的函数。 +所以现在当你给 `sayHello` 一个 `String` 时，它会打印问候语： + +{% tabs fun-write-method-returns-function-9 %} +{% tab 'Scala 2 and 3' %} +```scala +sayHello("Joe") // prints "Hello, Joe" +``` +{% endtab %} +{% endtabs %} + +您还可以根据需要更改问候语以创建新函数： + +{% tabs fun-write-method-returns-function-10 %} +{% tab 'Scala 2 and 3' %} +```scala +val sayCiao = greet("Ciao") +val sayHola = greet("Hola") + +sayCiao("Isabella") // prints "Ciao, Isabella" +sayHola("Carlos") // prints "Hola, Carlos" +``` +{% endtab %} +{% endtabs %} + +## 一个更真实的例子 + +当您的方法返回许多可能的函数之一时，这种技术会更加有用，例如返回自定义构建函数的工厂。 + +例如，假设您想编写一个方法，该方法返回用不同语言问候人们的函数。 +我们将其限制为使用英语或法语问候的函数，具体取决于传递给方法的参数。 + +您知道的第一件事是，您想要创建一个方法，该方法 (a) 将“所需语言”作为输入，并且 (b) 返回一个函数作为其结果。 +此外，由于该函数会打印给定的字符串，因此您知道它的类型为 `String => Unit`。 +使用该信息编写方法签名： + +{% tabs fun-write-method-returns-function-11 %} +{% tab 'Scala 2 and 3' %} +```scala +def createGreetingFunction(desiredLanguage: String): String => Unit = ??? +``` +{% endtab %} +{% endtabs %} + +接下来，因为您知道可能返回的函数接受一个字符串并打印它，所以您可以为英语和法语编写两个匿名函数： + +{% tabs fun-write-method-returns-function-12 %} +{% tab 'Scala 2 and 3' %} +```scala +(name: String) => println(s"你好，$name") +(name: String) => println(s"Bonjour, $name") +``` +{% endtab %} +{% endtabs %} + +在方法内部，如果你给这些匿名函数起一些名字，它可能会更易读，所以让我们将它们分配给两个变量： + +{% tabs fun-write-method-returns-function-13 %} +{% tab 'Scala 2 and 3' %} +```scala +val englishGreeting = (name: String) => println(s"Hello, $name") +val frenchGreeting = (name: String) => println(s"Bonjour, $name") +``` +{% endtab %} +{% endtabs %} + +现在您需要做的就是 (a) 如果 `desiredLanguage` 是英语，则返回 `englishGreeting`，并且 (b) 如果 `desiredLanguage` 是法语，则返回 `frenchGreeting`。 +一种方法是使用 `match` 表达式： + +{% tabs fun-write-method-returns-function-14 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def createGreetingFunction(desiredLanguage: String): String => Unit = { + val englishGreeting = (name: String) => println(s"Hello, $name") + val frenchGreeting = (name: String) => println(s"Bonjour, $name") + desiredLanguage match { + case "english" => englishGreeting + case "french" => frenchGreeting + } +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def createGreetingFunction(desiredLanguage: String): String => Unit = + val englishGreeting = (name: String) => println(s"Hello, $name") + val frenchGreeting = (name: String) => println(s"Bonjour, $name") + desiredLanguage match + case "english" => englishGreeting + case "french" => frenchGreeting +``` +{% endtab %} +{% endtabs %} + +这是最后的方法。 +请注意，从方法返回函数值与返回字符串或整数没有什么不同呃值。 + +这就是 `createGreetingFunction` 构建法语问候函数的方式： + +{% tabs fun-write-method-returns-function-15 %} +{% tab 'Scala 2 and 3' %} +```scala +val greetInFrench = createGreetingFunction("french") +greetInFrench("Jonathan") // prints "Bonjour, Jonathan" +``` +{% endtab %} +{% endtabs %} + +这就是它构建英语问候功能的方式： + +{% tabs fun-write-method-returns-function-16 %} +{% tab 'Scala 2 and 3' %} +```scala +val greetInEnglish = createGreetingFunction("english") +greetInEnglish("Joe") // prints "Hello, Joe" +``` +{% endtab %} +{% endtabs %} + +如果你对这段代码感到满意——恭喜——你现在知道如何编写返回函数的方法了。 + diff --git a/_zh-cn/overviews/scala3-book/interacting-with-java.md b/_zh-cn/overviews/scala3-book/interacting-with-java.md new file mode 100644 index 0000000000..f2263d0bd2 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/interacting-with-java.md @@ -0,0 +1,343 @@ +--- +title: 与 Java 交互 +type: chapter +description: This page demonstrates how Scala code can interact with Java, and how Java code can interact with Scala code. +language: zh-cn +num: 72 +previous-page: tools-worksheets +next-page: scala-for-java-devs + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +## 介绍 + +本节介绍如何在 Scala 中使用 Java 代码，以及如何在 Java 中使用 Scala 代码。 + +一般来说，在 Scala 中使用 Java 代码是非常无缝的。 +只有几个地方需要使用 Scala 实用程序将 Java 概念转换为 Scala，包括： + +- Java 集合类 +- Java `Optional` 类 + +同样，如果您正在编写 Java 代码并想使用 Scala 概念，则需要转换 Scala 集合和 Scala `Option` 类。 + +以下部分演示了您需要的最常见的转换： + +- 如何在 Scala 中使用 Java 集合 +- 如何在 Scala 中使用 Java `Optional` +- 在 Scala 中扩展 Java 接口 +- 如何在 Java 中使用 Scala 集合 +- 如何在 Java 中使用 Scala `Option` +- 如何在 Java 中使用 Scala traits +- 如何在 Java 代码中处理 Scala 方法引发的异常 +- 如何在 Java 中使用 Scala 可变参数 +- 创建备用名称以在 Java 中使用 Scala 方法 + +请注意，本节中的 Java 示例假设您使用的是 Java 11 或更高版本。 + +## 如何在 Scala 中使用 Java 集合 + +当您编写 Scala 代码并需要使用 Java 集合类时，您_可以_按原样使用该类。 +但是，如果您想在 Scala `for` 循环中使用该类，或者想利用 Scala 集合类中的高阶函数，则需要将 Java 集合转换为 Scala 集合。 + +这是一个如何工作的例子。 +假定这个例子是 Java `ArrayList`： + +```java +// java +public class JavaClass { + public static List getStrings() { + return new ArrayList(List.of("a", "b", "c")); + } +} +``` + +您可以使用 Scala _scala.jdk.CollectionConverters_ 包中的转换实用程序将该 Java 列表转换为 Scala `Seq`： + +```scala +// scala +import scala.jdk.CollectionConverters.* + +def testList() = + println("Using a Java List in Scala") + val javaList: java.util.List[String] = JavaClass.getStrings() + val scalaSeq: Seq[String] = javaList.asScala.toSeq + scalaSeq.foreach(println) + for s <- scalaSeq do println(s) +``` + +当然，该代码可以缩短，但此处显示的各个步骤是为了准确演示转换过程是如何工作的。 + +## 如何在 Scala 中使用 Java `Optional` + +当您需要在 Scala 代码中使用 Java `Optional` 类时，导入 _scala.jdk.OptionConverters_ 对象，然后使用 `toScala` 方法将 `Optional` 值转换为 Scala `Option`。 + +为了证明这一点，这里有一个带有两个 `Optional` 值的 Java 类，一个包含字符串，另一个为空： + +```java +// java +import java.util.Optional; + +public class JavaClass { + static Optional oString = Optional.of("foo"); + static Optional oEmptyString = Optional.empty(); +} +``` + +现在在您的 Scala 代码中，您可以访问这些字段。 +如果您只是直接访问它们，它们都将是 `Optional` 值： + +```scala +// scala +import java.util.Optional + +val optionalString = JavaClass.oString // Optional[foo] +val eOptionalString = JavaClass.oEmptyString // Optional.empty +``` + +但是通过使用 _scala.jdk.OptionConverters_ 方法，您可以将它们转换为 Scala `Option` 值： + +```scala +import java.util.Optional +import scala.jdk.OptionConverters.* + +val optionalString = JavaClass.oString // Optional[foo] +val optionString = optionalString.toScala // Some(foo) + +val eOptionalString = JavaClass.oEmptyString // Optional.empty +val eOptionString = eOptionalString.toScala // None +``` + +## 在 Scala 中扩展 Java 接口 + +如果您需要在 Scala 代码中使用 Java 接口，请将它们扩展为 Scala trait。 +例如，给定这三个 Java 接口： + +```java +// java +interface Animal { + void speak(); +} + +interface Wagging { + void wag(); +} + +interface Running { + // an implemented method + default void run() { + System.out.println("I’m running"); + } +} +``` + +你可以在 Scala 中创建一个 `Dog` 类，就像使用 trait 一样。 +你所要做的就是实现 `speak` 和 `wag` 方法： + +```scala +// scala +class Dog extends Animal, Wagging, Running: + def speak = println("Woof") + def wag = println("Tail is wagging") + +@main def useJavaInterfaceInScala = + val d = new Dog + d.speak + d.wag +``` + +## 如何在 Java 中使用 Scala 集合 + +当您需要在 Java 代码中使用 Scala 集合类时，请在 Java 代码中使用 Scala 的 `scala.jdk.javaapi.CollectionConverters` 对象的方法来进行转换。 +例如，如果您在 Scala 类中有这样的 `List[String]`： + +```scala +// scala +class ScalaClass: + val strings = List("a", "b") +``` + +您可以像这样在 Java 代码中访问该 Scala `List`： + +```java +// java +import scala.jdk.javaapi.CollectionConverters; + +// create an instance of the Scala class +ScalaClass sc = new ScalaClass(); + +// access the `strings` field as `sc.strings()` +scala.collection.immutable.List xs = sc.strings(); + +// convert the Scala `List` a Java `List` +java.util.List listOfStrings = CollectionConverters.asJava(xs); +listOfStrings.forEach(System.out::println); +``` + +该代码可以缩短，但显示了完整的步骤以演示该过程的工作原理。 +以下是该代码中需要注意的一些事项： + +- 在你的 Java 代码中，你创建一个 `ScalaClass` 的实例，就像一个 Java 类的实例一样 +- `ScalaClass` 有一个名为 `strings` 的字段，但在 Java 中，您可以将该字段作为方法访问，即，作为 `sc.strings()` + +## 如何在 Java 中使用 Scala `Option` + +当您需要在 Java 代码中使用 Scala `Option` 时，可以使用 Scala `scala.jdk.javaapi.OptionConverters` 对象的 `toJava` 方法将 `Option` 转换为 Java `Optional` 值。 + +为了证明这一点，创建一个具有两个 `Option[String]` 值的 Scala 类，一个包含字符串，另一个为空： + +```scala +// scala +object ScalaObject: + val someString = Option("foo") + val noneString: Option[String] = None +``` + +然后在您的 Java 代码中，使用来自 `scala.jdk.javaapi.OptionConverters` 对象的 `toJava` 方法将这些 `Option[String]` 值转换为 `java.util.Optional[String]`： + +```java +// java +import java.util.Optional; +import static scala.jdk.javaapi.OptionConverters.toJava; + +public class JUseScalaOptionInJava { + public static void main(String[] args) { + Optional stringSome = toJava(ScalaObject.someString()); // Optional[foo] + Optional stringNone = toJava(ScalaObject.noneString()); // Optional.empty + System.out.printf("stringSome = %s\n", stringSome); + System.out.printf("stringNone = %s\n", stringNone); + } +} +``` + +两个 Scala `Option` 字段现在可用作 Java `Optional` 值。 + +## 如何在 Java 中使用 Scala trait + +在 Java 11 中，您可以像使用 Java 接口一样使用 Scala trait，即使 trait 已经实现了方法。 +例如，给定这两个 Scala trait，一个具有已实现的方法，一个只有一个接口： + +```scala +// scala +trait ScalaAddTrait: + def sum(x: Int, y: Int) = x + y // implemented + +trait ScalaMultiplyTrait: + def multiply(x: Int, y: Int): Int // abstract +``` + +Java 类可以实现这两个接口，并定义 `multiply` 方法： + +```java +// java +class JavaMath implements ScalaAddTrait, ScalaMultiplyTrait { + public int multiply(int a, int b) { + return a * b; + } +} + +JavaMath jm = new JavaMath(); +System.out.println(jm.sum(3,4)); // 7 +System.out.println(jm.multiply(3,4)); // 12 +``` + +## 如何处理在 Java 代码中抛出异常的 Scala 方法 + +当您使用 Scala 编程习惯编写 Scala 代码时，您永远不会编写引发异常的方法。 +但是如果由于某种原因你有一个抛出异常的 Scala 方法，并且你希望 Java 开发人员能够使用该方法，请在你的 Scala 方法中添加`@throws`注解，以便 Java 使用者知道它可以抛出的异常. + +例如，注解这个 Scala `exceptionThrower` 方法抛出一个 `Exception`： + +```scala +// scala +object SExceptionThrower: + @throws(classOf[Exception]) + def exceptionThrower = + throw new Exception("Idiomatic Scala methods don’t throw exceptions") +``` + +因此，您需要处理 Java 代码中的异常。 +例如，这段代码不会编译，因为我不处理异常： + +```java +// java: won’t compile because the exception isn’t handled +public class ScalaExceptionsInJava { + public static void main(String[] args) { + SExceptionThrower.exceptionThrower(); + } +} +``` + +编译器给出了这个错误： + +```` +[error] ScalaExceptionsInJava: unreported exception java.lang.Exception; + must be caught or declared to be thrown +[error] SExceptionThrower.exceptionThrower() +```` + +这很好——这就是你想要的：注解告诉 Java 编译器 `exceptionThrower` 可以抛出异常。 +现在，当您编写 Java 代码时，您必须使用 `try` 块处理异常或声明您的 Java 方法抛出异常。 + +相反，如果你 Scala `exceptionThrower` 方法的注释，Java 代码_将编译_。 +这可能不是您想要的，因为 Java 代码可能无法考虑引发异常的 Scala 方法。 + +## 如何在 Java 中使用 Scala 可变参数 + +当 Scala 方法具有可变参数并且您想在 Java 中使用该方法时，请使用 `@varargs` 注解来标记 Scala 方法。 +例如，这个 Scala 类中的 `printAll` 方法声明了一个 `String*` 可变参数字段： + +```scala +// scala +import scala.annotation.varargs + +object VarargsPrinter: + @varargs def printAll(args: String*): Unit = args.foreach(println) +``` + +因为 `printAll` 是用 `@varargs` 注释声明的，所以可以从具有可变数量参数的 Java 程序中调用它，如下例所示： + +```scala +// java +public class JVarargs { + public static void main(String[] args) { + VarargsPrinter.printAll("Hello", "world"); + } +} +``` + +运行此代码时，结果在以下输出中： + +```` +Hello +world +```` + +## 创建备用名称以在 Java 中使用 Scala 方法 + +在 Scala 中，您可能希望使用符号字符创建方法名称： + +```scala +def +(a: Int, b: Int) = a + b +``` + +该方法名称在 Java 中不能很好地工作，但您可以在 Scala 3 中为该方法提供一个“替代”名称——别名——这将在 Java 中工作： + +```scala +import scala.annotation.targetName + +class Adder: + @targetName("add") def +(a: Int, b: Int) = a + b +``` + +现在在您的 Java 代码中，您可以使用别名方法名称 `add`： + +```scala +var adder = new Adder(); +int x = adder.add(1,1); +System.out.printf("x = %d\n", x); +``` diff --git a/_zh-cn/overviews/scala3-book/introduction.md b/_zh-cn/overviews/scala3-book/introduction.md new file mode 100644 index 0000000000..2e82050a0e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/introduction.md @@ -0,0 +1,35 @@ +--- +title: 导言 +type: chapter +description: This page begins the overview documentation of the Scala 3 language. +language: zh-cn +num: 1 +previous-page: +next-page: scala-features + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +欢迎阅读《Scala 3》一书。 +本书的目标是提供对 Scala 语言的非正式介绍，并以相对轻松的方式涉及所有的 Scala 主题。 +若您在阅读本书时想了解有关特定功能的更多信息，可以随时参阅[_参考文档_][reference]，其中更详细地涵盖了 Scala 语言的许多新特性。 + +
            +  如果你有兴趣看本书的 Scala 2 版，你可以在这获得。 +我们目前在整合这两本书，你可以帮助我们。 +
            + +在本书中，我们希望证明 Scala 是一种优美的、富有表现力的编程语言。它具有简洁、现代的语法，支持函数式编程（FP）和面向对象编程（OOP），并提供安全的静态类型系统。 +Scala 的语法和特性都经过了重新思考与公开辩论，并在2020年更新，比以往任何时候都更清晰、更容易理解。 + +本书首先在[“品味 Scala”部分][taste]对 Scala 的许多特性进行了一次“旋风之旅”。随后的章节会提供有关这些语言特性的更多详细信息。 + +{% comment %} +We should have a link structure on the whole tour here +{% endcomment %} + +[reference]: {{ site.scala3ref }}/overview.html +[taste]: {% link _zh-cn/overviews/scala3-book/taste-intro.md %} diff --git a/_zh-cn/overviews/scala3-book/methods-intro.md b/_zh-cn/overviews/scala3-book/methods-intro.md new file mode 100644 index 0000000000..ec383b437e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/methods-intro.md @@ -0,0 +1,22 @@ +--- +title: 方法 +type: chapter +description: This section introduces methods in Scala 3. +language: zh-cn +num: 24 +previous-page: domain-modeling-fp +next-page: methods-most + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在 Scala 2 中，_方法_可以在类、traits、对象、样例类和样例对象中定义。 +但它变得更好了：在Scala 3中，可以在这些结构的_外部_定义方法；我们说它们是“顶级”定义，因为它们没有嵌套在另一个定义中。 +简而言之，现在可以在任何地方定义方法。 + +方法的许多功能将在下一节中演示。 +由于 `main` 方法需要更多的解释，因此后面有单独部分对其进行描述。 diff --git a/_zh-cn/overviews/scala3-book/methods-main-methods.md b/_zh-cn/overviews/scala3-book/methods-main-methods.md new file mode 100644 index 0000000000..1b185854b1 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/methods-main-methods.md @@ -0,0 +1,188 @@ +--- +title: main 方法 +type: section +description: This page describes how 'main' methods and the '@main' annotation work in Scala 3. +language: zh-cn +num: 26 +previous-page: methods-most +next-page: methods-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +
            编写仅Scala 3 适用的一行程序
            + +Scala 3 提供了一种定义可以从命令行调用的程序的新方法：在方法中添加 `@main` 注释会将其变成可执行程序的入口点： + +{% tabs method_1 %} +{% tab 'Scala 3 Only' for=method_1 %} + +```scala +@main def hello() = println("Hello, world") +``` + +{% endtab %} +{% endtabs %} + +只需将该行代码保存在一个名为 *Hello.scala* 的文件中——文件名不必与方法名匹配——并使用 `scala` 运行它： + +```bash +$ scala Hello.scala +Hello, world +``` + +`@main` 注释方法可以写在顶层（如图所示），也可以写在静态可访问的对象中。 +在任何一种情况下，程序的名称都是方法的名称，没有任何对象前缀。 + +学习更多 `@main` 注解，可以阅读以下章节，或者看这个视频： + +
            + +
            + +### 命令行参数 + +使用这种方法，您的`@main` 方法可以处理命令行参数，并且这些参数可以有不同的类型。 +例如，给定这个 `@main` 方法，它接受一个 `Int`、一个 `String` 和一个可变参数 `String*` 参数： + +{% tabs method_2 %} +{% tab 'Scala 3 Only' for=method_2 %} + +```scala +@main def happyBirthday(age: Int, name: String, others: String*) = + val suffix = (age % 100) match + case 11 | 12 | 13 => "th" + case _ => (age % 10) match + case 1 => "st" + case 2 => "nd" + case 3 => "rd" + case _ => "th" + + val sb = StringBuilder(s"Happy $age$suffix birthday, $name") + for other <- others do sb.append(" and ").append(other) + sb.toString +``` + +{% endtab %} +{% endtabs %} + +当你编译该代码时，它会创建一个名为 `happyBirthday` 的主程序，它的调用方式如下： + +``` +$ scala happyBirthday 23 Lisa Peter +Happy 23rd Birthday, Lisa and Peter! +``` + +如上所示，`@main` 方法可以有任意数量的参数。 +对于每个参数类型，必须是 `scala.util.CommandLineParser.FromString` 类型类的一个 [given实例]({% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %})，它将参数 `String` 转换为所需的参数类型。 +同样如图所示，主方法的参数列表可以以重复参数结尾，例如 `String*`，它接受命令行中给出的所有剩余参数。 + +从 `@main` 方法实现的程序检查命令行上是否有足够的参数来填充所有参数，以及参数字符串是否可以转换为所需的类型。 +如果检查失败，程序将终止并显示错误消息： + +``` +$ scala happyBirthday 22 +Illegal command line after first argument: more arguments expected + +$ scala happyBirthday sixty Fred +Illegal command line: java.lang.NumberFormatException: For input string: "sixty" +``` + +## 用户自定义的类型作为参数 + +正如上面指出的，编译器为参数类型寻找 `scala.util.CommandLineParser.FromString` 类型类 的given 实例。 +例如，我们自定义了一个 `Color`类型，并希望当以参数使用。你可以像以下代码这样使用： + +{% tabs method_3 %} +{% tab 'Scala 3 Only' for=method_3 %} + +```scala +enum Color: + case Red, Green, Blue + +given ComamndLineParser.FromString[Color] with + def fromString(value: String): Color = Color.valueOf(value) + +@main def run(color: Color): Unit = + println(s"The color is ${color.toString}") +``` + +{% endtab %} +{% endtabs %} + +这对于您程序中的自定义类型以及可能使用的其他库中的类型，都是一样的。 + +## 细节 + +Scala 编译器从 `@main` 方法 `f` 生成程序，如下所示： + +- 它在有 `@main` 方法的包中创建一个名为 `f` 的类。 +- 该类有一个静态方法 `main`，具有 Java `main` 方法的通常签名：它以 `Array[String]` 作为参数并返回 `Unit`。 +- 生成的 `main` 方法调用方法 `f` 并使用 `scala.util.CommandLineParser` 对象中的方法转换参数。 + +例如，上面的 `happyBirthday` 方法会生成与以下类等效的附加代码： + +{% tabs method_3 %} +{% tab 'Scala 3 Only' for=method_3 %} + +```scala +final class happyBirthday { + import scala.util.{CommandLineParser as CLP} + def main(args: Array[String]): Unit = + try + happyBirthday( + CLP.parseArgument[Int](args, 0), + CLP.parseArgument[String](args, 1), + CLP.parseRemainingArguments[String](args, 2)) + catch { + case error: CLP.ParseError => CLP.showError(error) + } +} +``` + +> **注意**：在这个生成的代码中，`` 修饰符表示 `main` 方法是作为 `happyBirthday` 类的静态方法生成的。 +> 此功能不适用于 Scala 中的用户程序。 +> 常规“静态”成员在 Scala 中使用对象生成。 + +{% endtab %} +{% endtabs %} + +## 与 Scala 2 的向后兼容性 + +`@main` 方法是在 Scala 3 中生成可以从命令行调用的程序的推荐方法。 +它们取代了 Scala 2 中以前的方法，即创建一个扩展 `App` 类的 `object` ： + +之前依赖于“神奇”的 `DelayedInit` trait 的 `App` 功能不再可用。 +`App` 目前仍以有限的形式存在，但它不支持命令行参数，将来会被弃用。 + +如果程序需要在 Scala 2 和 Scala 3 之间交叉构建，建议使用带有 `Array[String]` 参数的显式 `main` 方法： + +{% tabs method_4 %} +{% tab 'Scala 2 and 3' %} + +```scala +object happyBirthday { + private def happyBirthday(age: Int, name: String, others: String*) = { + ... // same as before + } + def main(args: Array[String]): Unit = + happyBirthday(args(0).toInt, args(1), args.drop(2).toIndexedSeq:_*) +} +``` + +> 注意我们用 `:_*` 来传递不定数量的参数。为了保持向后兼容性，Scala 3 保持了这种用法。 + +{% endtab %} +{% endtabs %} + +如果将该代码放在名为 *happyBirthday.scala* 的文件中，则可以使用 `scalac` 编译它并使用 `scala` 运行它，如前所示： + +```bash +$ scalac happyBirthday.scala + +$ scala happyBirthday 23 Lisa Peter +Happy 23rd Birthday, Lisa and Peter! +``` diff --git a/_zh-cn/overviews/scala3-book/methods-most.md b/_zh-cn/overviews/scala3-book/methods-most.md new file mode 100644 index 0000000000..86d78f7960 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/methods-most.md @@ -0,0 +1,700 @@ +--- +title: 方法特性 +type: section +description: This section introduces Scala 3 methods, including main methods, extension methods, and more. +language: zh-cn +num: 25 +previous-page: methods-intro +next-page: methods-main-methods + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本节介绍如何在 Scala 3 中定义和调用方法的各个方面。 + +## 定义方法 + +Scala 方法有很多特性，包括： + +- 泛型（类型）参数 +- 参数的默认值 +- 多个参数组（柯里化） +- 上下文提供的参数 +- 传名参数 +- ... + +本节演示了其中一些功能，但是当您定义一个不使用这些功能的“简单”方法时，语法如下所示： + +{% tabs method_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_1 %} + +```scala +def methodName(param1: Type1, param2: Type2): ReturnType = { + // the method body + // goes here +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_1 %} + +```scala +def methodName(param1: Type1, param2: Type2): ReturnType = + // the method body + // goes here +end methodName // this is optional +``` + +{% endtab %} +{% endtabs %} + +在该语法中： + +- 关键字 `def` 用于定义方法 +- Scala 标准是使用驼峰式命法来命名方法 +- 方法参数总是和它们的类型一起定义 +- 声明方法返回类型是可选的 +- 方法可以包含多行，也可以只包含一行 +- 在方法体之后提供 `end methodName` 部分也是可选的，仅推荐用于长方法 + +下面是一个名为 `add` 的单行方法的两个示例，它接受两个 `Int` 输入参数。 +第一个版本明确显示方法的 `Int` 返回类型，第二个版本没有： + +{% tabs method_2 %} +{% tab 'Scala 2 and 3' for=method_2 %} + +```scala +def add(a: Int, b: Int): Int = a + b +def add(a: Int, b: Int) = a + b +``` + +{% endtab %} +{% endtabs %} + +建议使用返回类型注释公开可见的方法。 +声明返回类型可以让您在几个月或几年后查看它或查看其他人的代码时更容易理解它。 + +## 调用方法 + +调用方法很简单： + +{% tabs method_3 %} +{% tab 'Scala 2 and 3' for=method_3 %} + +```scala +val x = add(1, 2) // 3 +``` + +{% endtab %} +{% endtabs %} + +Scala 集合类有几十个内置方法。 +这些示例显示了如何调用它们： + +{% tabs method_4 %} +{% tab 'Scala 2 and 3' for=method_4 %} + +```scala +val x = List(1, 2, 3) + +x.size // 3 +x.contains(1) // true +x.map(_ * 10) // List(10, 20, 30) +``` + +{% endtab %} +{% endtabs %} + +注意： + +- `size` 不带参数，并返回列表中元素的数量 +- `contains` 方法接受一个参数，即要搜索的值 +- `map` 接受一个函数参数；在上述情况下，传递给它的是一个匿名函数 + +## 多行方法 + +当方法超过一行时，从第二行开始方法体，向右缩进： + +{% tabs method_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_5 %} + +```scala +def addThenDouble(a: Int, b: Int): Int = { + // imagine that this body requires multiple lines + val sum = a + b + sum * 2 +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_5 %} + +```scala +def addThenDouble(a: Int, b: Int): Int = + // imagine that this body requires multiple lines + val sum = a + b + sum * 2 +``` + +{% endtab %} +{% endtabs %} + +在那个方法中： + +- `sum` 是一个不可变的局部变量；它不能在方法之外访问 +- 最后一行将 `sum` 的值加倍；这个值是从方法返回的 + +当您将该代码粘贴到 REPL 中时，您会看到它按预期工作： + +{% tabs method_6 %} +{% tab 'Scala 2 and 3' for=method_6 %} + +```scala +scala> addThenDouble(1, 1) +res0: Int = 4 +``` + +{% endtab %} +{% endtabs %} + +请注意，方法末尾不需要 `return` 语句。 +因为在 Scala 中几乎所有的东西都是一个_表达式_——意味着每一行代码都返回（或_执行_）一个值——不需要使用 `return`。 + +当您压缩该方法并将其写在一行上时，这一点变得更加清晰： + +{% tabs method_7 %} +{% tab 'Scala 2 and 3' for=method_7 %} + +```scala +def addThenDouble(a: Int, b: Int): Int = (a + b) * 2 +``` + +{% endtab %} +{% endtabs %} + +方法的主体可以使用语言的所有不同特性： + +- `if`/`else` 表达式 +- `match` 表达式 +- `while` 循环 +- `for` 循环和 `for` 表达式 +- 变量赋值 +- 调用其他方法 +- 其他方法的定义 + +作为一个真实世界的多行方法的例子，这个 `getStackTraceAsString` 方法将它的 `Throwable` 输入参数转换成一个格式良好的 `String`： + +{% tabs method_8 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_8 %} + +```scala +def getStackTraceAsString(t: Throwable): String = { + val sw = new StringWriter() + t.printStackTrace(new PrintWriter(sw)) + sw.toString +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_8 %} + +```scala +def getStackTraceAsString(t: Throwable): String = + val sw = StringWriter() + t.printStackTrace(PrintWriter(sw)) + sw.toString +``` + +{% endtab %} +{% endtabs %} + +在那个方法中： + +- 第一行将 `StringWriter` 的新实例分配给值绑定器 `sw` +- 第二行将堆栈跟踪内容存储到 `StringWriter` +- 第三行产生堆栈跟踪的 `String` 表示 + +## 默认参数值 + +方法参数可以有默认值。 +在此示例中，为 `timeout` 和 `protocol` 参数提供了默认值： + +{% tabs method_9 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_9 %} + +```scala +def makeConnection(timeout: Int = 5_000, protocol: String = "http") = { + println(f"timeout = ${timeout}%d, protocol = ${protocol}%s") + // more code here ... +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_9 %} + +```scala +def makeConnection(timeout: Int = 5_000, protocol: String = "http") = + println(f"timeout = ${timeout}%d, protocol = ${protocol}%s") + // more code here ... +``` + +{% endtab %} +{% endtabs %} + +由于参数具有默认值，因此可以通过以下方式调用该方法： + +{% tabs method_10 %} +{% tab 'Scala 2 and 3' for=method_10 %} + +```scala +makeConnection() // timeout = 5000, protocol = http +makeConnection(2_000) // timeout = 2000, protocol = http +makeConnection(3_000, "https") // timeout = 3000, protocol = https +``` + +{% endtab %} +{% endtabs %} + +以下是关于这些示例的一些要点： + +- 在第一个示例中，没有提供任何参数，因此该方法使用默认参数值 `5_000` 和 `http` +- 在第二个示例中，为 `timeout` 值提供了 `2_000`，因此它与 `protocol` 的默认值一起使用 +- 在第三个示例中，为两个参数提供了值，因此它们都被使用 + +请注意，通过使用默认参数值，消费者似乎可以使用三种不同的重载方法。 + +## 命名参数 + +如果您愿意，也可以在调用方法时使用方法参数的名称。 +例如，`makeConnection` 也可以通过以下方式调用： + +{% tabs method_11 %} +{% tab 'Scala 2 and 3' for=method_11 %} + +```scala +makeConnection(timeout=10_000) +makeConnection(protocol="https") +makeConnection(timeout=10_000, protocol="https") +makeConnection(protocol="https", timeout=10_000) +``` + +{% endtab %} +{% endtabs %} + +在某些框架中，命名参数被大量使用。 +当多个方法参数具有相同类型时，它们也非常有用： + +{% tabs method_12 %} +{% tab 'Scala 2 and 3' for=method_12 %} + +```scala +engage(true, true, true, false) +``` + +{% endtab %} +{% endtabs %} + +如果没有 IDE 的帮助，代码可能难以阅读，但这段代码更加清晰和明显： + +{% tabs method_13 %} +{% tab 'Scala 2 and 3' for=method_13 %} + +```scala +engage( + speedIsSet = true, + directionIsSet = true, + picardSaidMakeItSo = true, + turnedOffParkingBrake = false +) +``` + +{% endtab %} +{% endtabs %} + +## 关于不带参数的方法的建议 + +当一个方法不带参数时，它的 _arity_ 级别为 _arity-0_。 +类似地，当一个方法采用一个参数时，它是一个_arity-1_方法。 +当您创建 arity-0 方法时： + +- 如果方法执行副作用，例如调用`println`，用空括号声明方法 +- 如果该方法不执行副作用——例如获取集合的大小，这类似于访问集合上的字段——请去掉括号 + +例如，这个方法会产生副作用，所以它用空括号声明： + +{% tabs method_14 %} +{% tab 'Scala 2 and 3' for=method_14 %} + +```scala +def speak() = println("hi") +``` + +{% endtab %} +{% endtabs %} + +这样做需要方法的调用者在调用方法时使用括号： + +{% tabs method_15 %} +{% tab 'Scala 2 and 3' for=method_15 %} + +```scala +speak // error: "method speak must be called with () argument" +speak() // prints "hi" +``` + +{% endtab %} +{% endtabs %} + +虽然这只是一个约定，但遵循它可以显着提高代码的可读性：它可以让您更容易一目了然地理解 arity-0 方法执行副作用。 + +{% comment %} +Some of that wording comes from this page: https://docs.scala-lang.org/style/method-invocation.html +{% endcomment %} + +## 使用 `if` 作为方法体 + +因为 `if`/`else` 表达式返回一个值，所以它们可以用作方法的主体。 +这是一个名为 `isTruthy` 的方法，它实现了 Perl 对 `true` 和 `false` 的定义： + +{% tabs method_16 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_16 %} + +```scala +def isTruthy(a: Any) = { + if (a == 0 || a == "" || a == false) + false + else + true +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_16 %} + +```scala +def isTruthy(a: Any) = + if a == 0 || a == "" || a == false then + false + else + true +``` + +{% endtab %} +{% endtabs %} + +这些示例显示了该方法的工作原理： + +{% tabs method_17 %} +{% tab 'Scala 2 and 3' for=method_17 %} + +```scala +isTruthy(0) // false +isTruthy("") // false +isTruthy("hi") // true +isTruthy(1.0) // true +``` + +{% endtab %} +{% endtabs %} + +## 使用 `match` 作为方法体 + +`match` 表达式也可以用作整个方法体，而且经常如此。 +这是 `isTruthy` 的另一个版本，用 `match` 表达式编写： + +{% tabs method_18 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_18 %} + +```scala +def isTruthy(a: Any) = a match { + case 0 | "" | false => false + case _ => true +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_18 %} + +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" | false => false + case _ => true +``` + +> 此方法的工作方式与之前使用 `if`/`else` 表达式的方法一样。我们使用 `Matchable` 而不是 `Any` 作为参数的类型来接受任何支持模式匹配的值。 + +> 有关 `Matchable` trait 的更多详细信息，请参阅 [参考文档][reference_matchable]。 + +[reference_matchable]: {{ site.scala3ref }}/other-new-features/matchable.html +{% endtab %} +{% endtabs %} + +## 控制类中的可见性 + +在类、对象、trait和枚举中，Scala 方法默认是公共的，所以这里创建的 `Dog` 实例可以访问 `speak` 方法： + +{% tabs method_19 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_19 %} + +```scala +class Dog { + def speak() = println("Woof") +} + +val d = new Dog +d.speak() // prints "Woof" +``` + +{% endtab %} +{% tab 'Scala 3' for=method_19 %} + +```scala +class Dog: + def speak() = println("Woof") + +val d = new Dog +d.speak() // prints "Woof" +``` + +{% endtab %} +{% endtabs %} + +方法也可以标记为 `private`。 +这使得它们对当前类是私有的，因此它们不能在子类中被调用或重载： + +{% tabs method_20 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_20 %} + +```scala +class Animal { + private def breathe() = println("I’m breathing") +} + +class Cat extends Animal { + // this method won’t compile + override def breathe() = println("Yo, I’m totally breathing") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_20 %} + +```scala +class Animal: + private def breathe() = println("I’m breathing") + +class Cat extends Animal: + // this method won’t compile + override def breathe() = println("Yo, I’m totally breathing") +``` + +{% endtab %} +{% endtabs %} + +如果你想让一个方法对当前类私有，并且允许子类调用它或覆盖它，将该方法标记为 `protected`，如本例中的 `speak` 方法所示： + +{% tabs method_21 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_21 %} + +```scala +class Animal { + private def breathe() = println("I’m breathing") + def walk() = { + breathe() + println("I’m walking") + } + protected def speak() = println("Hello?") +} + +class Cat extends Animal { + override def speak() = println("Meow") +} + +val cat = new Cat +cat.walk() +cat.speak() +cat.breathe() // won’t compile because it’s private +``` + +{% endtab %} +{% tab 'Scala 3' for=method_21 %} + +```scala +class Animal: + private def breathe() = println("I’m breathing") + def walk() = + breathe() + println("I’m walking") + protected def speak() = println("Hello?") + +class Cat extends Animal: + override def speak() = println("Meow") + +val cat = new Cat +cat.walk() +cat.speak() +cat.breathe() // won’t compile because it’s private +``` + +{% endtab %} +{% endtabs %} + +`protected` 设置意味着： + +- 方法（或字段）可以被同一类的其他实例访问 +- 对当前包中的其他代码是不可见的 +- 它适用于子类 + +## 对象可以包含方法 + +之前你看到trait和类可以有方法。 +Scala `object` 关键字用于创建单例类，对象也可以包含方法。 +这是对一组“实用程序”方法进行分组的好方法。 +例如，此对象包含一组处理字符串的方法： + +{% tabs method_22 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_22 %} + +```scala +object StringUtils { + + /** + * Returns a string that is the same as the input string, but + * truncated to the specified length. + */ + def truncate(s: String, length: Int): String = s.take(length) + + /** + * Returns true if the string contains only letters and numbers. + */ + def lettersAndNumbersOnly_?(s: String): Boolean = + s.matches("[a-zA-Z0-9]+") + + /** + * Returns true if the given string contains any whitespace + * at all. Assumes that `s` is not null. + */ + def containsWhitespace(s: String): Boolean = + s.matches(".*\\s.*") + +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_22 %} + +```scala +object StringUtils: + + /** + * Returns a string that is the same as the input string, but + * truncated to the specified length. + */ + def truncate(s: String, length: Int): String = s.take(length) + + /** + * Returns true if the string contains only letters and numbers. + */ + def lettersAndNumbersOnly_?(s: String): Boolean = + s.matches("[a-zA-Z0-9]+") + + /** + * Returns true if the given string contains any whitespace + * at all. Assumes that `s` is not null. + */ + def containsWhitespace(s: String): Boolean = + s.matches(".*\\s.*") + +end StringUtils +``` + +{% endtab %} +{% endtabs %} + +## 扩展方法 + +扩展方法在上下文抽象一章的[扩展方法部分][extension]中讨论。 +有很多情况，你想向封闭类添加功能。 +如该部分所示，假设您有一个 `Circle` 类，但您无法更改其源代码。 +例如，它可以在第三方库中这样定义： + +{% tabs method_23 %} +{% tab 'Scala 2 and 3' for=method_23 %} + +```scala +case class Circle(x: Double, y: Double, radius: Double) +``` + +{% endtab %} +{% endtabs %} + +当你想给这个类添加方法时，你可以将它们定义为扩展方法，像这样： + +{% tabs method_24 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_24 %} + +```scala +implicit class CircleOps(c: Circle) { + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +} +``` +在 Scala 2 中使用 `implicit class`，在[这](/overviews/core/implicit-classes.html)找到更多细节。 + +{% endtab %} +{% tab 'Scala 3' for=method_24 %} + +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` +在 Scala 3 中使用新的 `extension` 结构。更多细节可以看[本书][extension]的章节，或者 [Scala 3 参考][reference-ext]。 + +[reference-ext]: {{ site.scala3ref }}/contextual/extension-methods.html +[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +{% endtab %} +{% endtabs %} + +现在，当您有一个名为 `aCircle` 的 `Circle` 实例时，您可以像这样调用这些方法： + +{% tabs method_25 %} +{% tab 'Scala 2 and 3' for=method_25 %} + +```scala +aCircle.circumference +aCircle.diameter +aCircle.area +``` + +{% endtab %} +{% endtabs %} + +## 更多 + +还有更多关于方法的知识，包括如何： + +- 调用超类的方法 +- 定义和使用传名参数 +- 编写一个带有函数参数的方法 +- 创建内嵌方法 +- 处理异常 +- 使用可变参数作为输入参数 +- 编写具有多个参数组的方法（部分应用的函数） +- 创建具有泛型类型参数的方法 + +{% comment %} +Jamie: there really needs better linking here - previously it was to the Scala 3 Reference, which doesnt cover any +of this +{% endcomment %} + +有关这些特性的更多详细信息，请看本书其它章节。 + +[reference_extension_methods]: {{ site.scala3ref }}/contextual/extension-methods.html +[reference_matchable]: {{ site.scala3ref }}/other-new-features/matchable.html diff --git a/_zh-cn/overviews/scala3-book/methods-summary.md b/_zh-cn/overviews/scala3-book/methods-summary.md new file mode 100644 index 0000000000..472c6230a1 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/methods-summary.md @@ -0,0 +1,28 @@ +--- +title: 总结 +type: section +description: This section summarizes the previous sections on Scala 3 methods. +language: zh-cn +num: 27 +previous-page: methods-main-methods +next-page: fun-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +还有更多关于方法的知识，包括如何： + +- 调用超类的方法 +- 定义和使用按名称参数 +- 编写一个带有函数参数的方法 +- 创建内嵌方法 +- 处理异常 +- 使用可变参数输入参数 +- 编写具有多个参数组的方法（部分应用的函数） +- 创建具有泛型类型参数的方法 + +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_zh-cn/overviews/scala3-book/packaging-imports.md b/_zh-cn/overviews/scala3-book/packaging-imports.md new file mode 100644 index 0000000000..bc928dbe67 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/packaging-imports.md @@ -0,0 +1,632 @@ +--- +title: 打包和导入 +type: chapter +description: A discussion of using packages and imports to organize your code, build related modules of code, control scope, and help prevent namespace collisions. +language: zh-cn +num: 36 +previous-page: fun-summary +next-page: collections-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 使用 *包* 创建命名空间，让您可以模块化程序并帮助防止命名空间冲突。 +Scala 支持 Java 使用的包命名样式，也支持 C++ 和 C# 等语言使用的“花括号”命名空间表示法。 + +Scala 导入成员的方法也类似于 Java，并且更灵活。 +使用 Scala，您可以： + +- 导入包、类、对象、traits 和方法 +- 将导入语句放在任何地方 +- 导入成员时隐藏和重命名成员 + +这些特性在以下示例中进行了演示。 + +## 创建一个包 + +通过在 Scala 文件的顶部声明一个或多个包名称来创建包。 +例如，当您的域名是 _acme.com_ 并且您正在使用名为 _myapp_ 的应用程序中的 _model_ 包中工作时，您的包声明如下所示： + +{% tabs packaging-imports-0 %} +{% tab 'Scala 2 and 3' %} +```scala +package com.acme.myapp.model + +class Person ... +``` +{% endtab %} +{% endtabs %} + +按照约定，包名应全部小写，正式命名约定为 *\.\.\.\*。 + +虽然不是必需的，但包名称通常遵循目录结构名称，因此如果您遵循此约定，则此项目中的 `Person` 类将在 *MyApp/src/main/scala/com/acme/myapp/model/Person.scala* 文件中找到。 + +### 在同一个文件中使用多个包 + +上面显示的语法适用于整个源文件：文件中的所有定义 +`Person.scala` 属于 `com.acme.myapp.model` 包，根据包子句 +在文件的开头。 + +或者，可以编写仅适用于定义的包子句 +他们包含： + +{% tabs packaging-imports-1 class=tabs-scala-version %} +{% tab 'Scala 2' %}```scala +package users { + + package administrators { // the full name of this package is users.administrators + class AdminUser // the full name of this class users.administrators.AdminUser + } + package normalusers { // the full name of this package is users.normalusers + class NormalUser // the full name of this class is users.normalusers.NormalUser + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-1 %} + +```scala +package users: + + package administrators: // the full name of this package is users.administrators + class AdminUser // the full name of this class is users.administrators.AdminUser + + package normalusers: // the full name of this package is users.normalusers + class NormalUser // the full name of this class is users.normalusers.NormalUser +``` +{% endtab %} +{% endtabs %} + +请注意，包名称后跟一个冒号，并且其中的定义 +一个包是缩进的。 + +这种方法的优点是它允许包嵌套，并提供更明显的范围和封装控制，尤其是在同一个文件中。 + +## 导入语句，第 1 部分 + +导入语句用于访问其他包中的实体。 +导入语句分为两大类： + +- 导入类、trait、对象、函数和方法 +- 导入 `given` 子句 + +如果您习惯于 Java 之类的语言，则第一类 import 语句与 Java 使用的类似，只是语法略有不同，因此具有更大的灵活性。 +这些示例展示了其中的一些灵活性： + +{% tabs packaging-imports-2 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import users._ // import everything from the `users` package +import users.User // import only the `User` class +import users.{User, UserPreferences} // import only two selected members +import users.{UserPreferences as UPrefs} // rename a member as you import it +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-2 %} + +```scala +import users.* // import everything from the `users` package +import users.User // import only the `User` class +import users.{User, UserPreferences} // import only two selected members +import users.{UserPreferences as UPrefs} // rename a member as you import it +``` + +{% endtab %} +{% endtabs %} + +这些示例旨在让您了解第一类 `import` 语句的工作原理。 +在接下来的小节中对它们进行了更多解释。 + +导入语句还用于将 `given` 实例导入本范围。 +这些将在本章末尾讨论。 + +继续之前的注意事项： + +> 访问同一包的成员不需要导入子句。 + +### 导入一个或多个成员 + +在 Scala 中，您可以从包中导入一个成员，如下所示： + +{% tabs packaging-imports-3 %} +{% tab 'Scala 2 and 3' %} +```scala +import scala.concurrent.Future +``` +{% endtab %} +{% endtabs %} + +和这样的多个成员： + +{% tabs packaging-imports-4 %} +{% tab 'Scala 2 and 3' %} +```scala +import scala.concurrent.Future +import scala.concurrent.Promise +import scala.concurrent.blocking +``` +{% endtab %} +{% endtabs %} + +导入多个成员时，您可以像这样更简洁地导入它们： + +{% tabs packaging-imports-5 %} +{% tab 'Scala 2 and 3' %} +```scala +import scala.concurrent.{Future, Promise, blocking} +``` +{% endtab %} +{% endtabs %} + +当您想从 *scala.concurrent* 包中导入所有内容时，请使用以下语法： + +{% tabs packaging-imports-6 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import scala.concurrent._ +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-6 %} + +```scala +import scala.concurrent.* +``` +{% endtab %} +{% endtabs %} + +### 在导入时重命名成员 + +有时，在导入实体时重命名实体会有所帮助，以避免名称冲突。 +例如，如果您想同时使用 Scala `List` 类和 *java.util.List* 类，可以在导入时重命名 *java.util.List* 类： + +{% tabs packaging-imports-7 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.util.{List => JavaList} +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-7 %} + +```scala +import java.util.{List as JavaList} +``` +{% endtab %} +{% endtabs %} + +现在您使用名称 `JavaList` 来引用该类，并使用 `List` 来引用 Scala 列表类。 + +您还可以使用以下语法一次重命名多个成员： + +{% tabs packaging-imports-8 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.util.{Date => JDate, HashMap => JHashMap, _} +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-8 %} + +```scala +import java.util.{Date as JDate, HashMap as JHashMap, *} +``` + +{% endtab %} +{% endtabs %} + +那行代码说，“重命名 `Date` 和 `HashMap` 类，如图所示，并导入 _java.util_ 包中的所有其他内容，而不重命名任何其他成员。” + +### 在导入时隐藏成员 + +您还可以在导入过程中*隐藏*成员。 +这个 `import` 语句隐藏了 *java.util.Random* 类，同时导入 *java.util 中的所有其他内容* 包裹： + +{% tabs packaging-imports-9 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.util.{Random => _, _} +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-9 %} + +```scala +import java.util.{Random as _, *} +``` +{% endtab %} +{% endtabs %} + +如果您尝试访问 `Random` 类，它将无法正常工作，但您可以访问该包中的所有其他成员： + +{% tabs packaging-imports-10 %} +{% tab 'Scala 2 and 3' %} +```scala +val r = new Random // won’t compile +new ArrayList // works +``` +{% endtab %} +{% endtabs %} + +#### 隐藏多个成员 + +要在导入过程中隐藏多个成员，请在使用最终通配符导入之前列出它们： + +{% tabs packaging-imports-11 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +scala> import java.util.{List => _, Map => _, Set => _, _} +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-11 %} + +```scala +scala> import java.util.{List as _, Map as _, Set as _, *} +``` +{% endtab %} +{% endtabs %} + +这些类再次被隐藏，但您可以使用 *java.util* 中的所有其他类： + +{% tabs packaging-imports-12 %} +{% tab 'Scala 2 and 3' %} +```scala +scala> new ArrayList[String] +val res0: java.util.ArrayList[String] = [] +``` +{% endtab %} +{% endtabs %} + +因为这些 Java 类是隐藏的，所以您也可以使用 Scala 的 `List`、`Set` 和 `Map` 类而不会发生命名冲突： + +{% tabs packaging-imports-13 %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val a = List(1, 2, 3) +val a: List[Int] = List(1, 2, 3) + +scala> val b = Set(1, 2, 3) +val b: Set[Int] = Set(1, 2, 3) + +scala> val c = Map(1 -> 1, 2 -> 2) +val c: Map[Int, Int] = Map(1 -> 1, 2 -> 2) +``` +{% endtab %} +{% endtabs %} + +### 在任何地方使用导入 + +在 Scala 中，`import` 语句可以在任何地方。 +它们可以在源代码文件的顶部使用： + +{% tabs packaging-imports-14 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +package foo + +import scala.util.Random + +class ClassA { + def printRandom(): Unit = { + val r = new Random // use the imported class + // more code here... + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-14 %} + +```scala +package foo + +import scala.util.Random + +class ClassA: + def printRandom: + val r = new Random // use the imported class + // more code here... +``` +{% endtab %} +{% endtabs %} + +如果您愿意，您还可以使用更接近需要它们的点的 `import` 语句： + +{% tabs packaging-imports-15 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +package foo + +class ClassA { + import scala.util.Random // inside ClassA + def printRandom(): Unit = { + val r = new Random + // more code here... + } +} + +class ClassB { + // the Random class is not visible here + val r = new Random // this code will not compile +} +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-15 %} + +```scala +package foo + +class ClassA: + import scala.util.Random // inside ClassA + def printRandom { + val r = new Random + // more code here... + +class ClassB: + // the Random class is not visible here + val r = new Random // this code will not compile +``` + +{% endtab %} +{% endtabs %} + +### “静态”导入 + +当您想以类似于 Java “静态导入”方法的方式导入成员时——因此您可以直接引用成员名称，而不必在它们前面加上类名——使用以下方法。 + +使用此语法导入 Java `Math` 类的所有静态成员： + +{% tabs packaging-imports-16 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.lang.Math._ +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-16 %} + +```scala +import java.lang.Math.* +``` +{% endtab %} +{% endtabs %} + +现在您可以访问静态的 `Math` 类方法，例如 `sin` 和 `cos`，而不必在它们前面加上类名： + +{% tabs packaging-imports-17 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +import java.lang.Math._ + +val a = sin(0) // 0.0 +val b = cos(PI) // -1.0 +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-17 %} + +```scala +import java.lang.Math.* + +val a = sin(0) // 0.0 +val b = cos(PI) // -1.0 +``` +{% endtab %} +{% endtabs %} + +### 默认导入的包 + +两个包被隐式导入到所有源代码文件的范围内： + +- java.lang.* +- scala.* + +Scala 对象 `Predef` 的成员也是默认导入的。 + +> 如果您想知道为什么可以使用 `List`、`Vector`、`Map` 等类，而无需导入它们，它们是可用的，因为 `Predef` 对象中的定义。 + +### 处理命名冲突 + +在极少数情况下会出现命名冲突，您需要从项目的根目录导入一些东西，在包名前加上 `_root_`： + +{% tabs packaging-imports-18 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +package accounts + +import _root_.accounts._ +``` + +{% endtab %} +{% tab 'Scala 3' for=packaging-imports-18 %} + +```scala +package accounts + +import _root_.accounts.* +``` +{% endtab %} +{% endtabs %} + +## 导入 `given` 实例 + +正如您将在 [上下文抽象][contextual] 一章中看到的，`import` 语句的一种特殊形式用于导入 `given` 实例。 +基本形式如本例所示： + +{% tabs packaging-imports-19 %} +{% tab 'Scala 3 only' %} +```scala +object A: + class TC + given tc: TC + def f(using TC) = ??? + +object B: + import A.* // import all non-given members + import A.given // import the given instance +``` +{% endtab %} +{% endtabs %} + +在此代码中，对象 `B` 的 `import A.*` 子句导入了 `A` 的所有成员 *除了* `given` 实例 `tc`。 +相反，第二个导入，`import A.given`，*仅*导入那个 `given` 实例。 +两个 `import` 子句也可以合并为一个： + +{% tabs packaging-imports-20 %} +{% tab 'Scala 3 only' %} +```scala +object B: + import A.{given, *} +``` +{% endtab %} +{% endtabs %} + +### 讨论 + +通配符选择器 `*` 将除给定或扩展之外的所有定义带入范围，而 `given` 选择器将所有*给定*——包括那些由扩展产生的定义——带入范围。 + +这些规则有两个主要好处： + +- 范围内的给定来自哪里更清楚。 + 特别是，不可能在一长串其他通配符导入中隐藏导入的给定。 +- 它可以在不导入任何其他内容的情况下导入所有给定。 + 这一点特别重要，因为给定可以是匿名的，所以通常使用命名导入是不切实际的。 + +### 按类型导入 + +由于给定可以是匿名的，因此按名称导入它们并不总是可行的，通常使用通配符导入。 +*按类型导入* 为通配符导入提供了更具体的替代方案，这使得导入的内容更加清晰： + +{% tabs packaging-imports-21 %} +{% tab 'Scala 3 only' %} +```scala +import A.{given TC} +``` +{% endtab %} +{% endtabs %} + +这会在 `A` 中导入任何具有符合 `TC` 的类型的 `given`。 +导入多种类型的给定 `T1,...,Tn` 由多个 `given` 选择器表示： + +{% tabs packaging-imports-22 %} +{% tab 'Scala 3 only' %} +```scala +import A.{given T1, ..., given Tn} +``` +{% endtab %} +{% endtabs %} + +导入参数化类型的所有 `given` 实例由通配符参数表示。 +例如，当你有这个 `object` 时： + +{% tabs packaging-imports-23 %} +{% tab 'Scala 3 only' %} +```scala +object Instances: + given intOrd: Ordering[Int] + given listOrd[T: Ordering]: Ordering[List[T]] + given ec: ExecutionContext = ... + given im: Monoid[Int] +``` +{% endtab %} +{% endtabs %} + +此导入语句导入 `intOrd`、`listOrd` 和 `ec` 实例，但省略了 `im` 实例，因为它不符合任何指定的边界： + +{% tabs packaging-imports-24 %} +{% tab 'Scala 3 only' %} +```scala +import Instances.{given Ordering[?], given ExecutionContext} +``` +{% endtab %} +{% endtabs %} + +按类型导入可以与按名称导入混合。 +如果两者都存在于导入子句中，则按类型导入排在最后。 +例如，这个 import 子句导入了 `im`、`intOrd` 和 `listOrd`，但省略了 `ec`： + +{% tabs packaging-imports-25 %} +{% tab 'Scala 3 only' %} +```scala +import Instances.{im, given Ordering[?]} +``` +{% endtab %} +{% endtabs %} + +### 一个例子 + +作为一个具体的例子，假设你有这个 `MonthConversions` 对象，它包含两个 `given` 定义： + +{% tabs packaging-imports-26 %} +{% tab 'Scala 3 only' %} + +```scala +object MonthConversions: + trait MonthConverter[A]: + def convert(a: A): String + + given intMonthConverter: MonthConverter[Int] with + def convert(i: Int): String = + i match + case 1 => "January" + case 2 => "February" + // more cases here ... + + given stringMonthConverter: MonthConverter[String] with + def convert(s: String): String = + s match + case "jan" => "January" + case "feb" => "February" + // more cases here ... +``` +{% endtab %} +{% endtabs %} + +要将这些给定导入当前范围，请使用以下两个 `import` 语句： + +{% tabs packaging-imports-27 %} +{% tab 'Scala 3 only' %} + +```scala +import MonthConversions.* +import MonthConversions.{given MonthConverter[?]} +``` +{% endtab %} +{% endtabs %} + +现在您可以创建一个使用这些 `given` 实例的方法： + +{% tabs packaging-imports-28 %} +{% tab 'Scala 3 only' %} + +```scala +def genericMonthConverter[A](a: A)(using monthConverter: MonthConverter[A]): String = + monthConverter.convert(a) +``` +{% endtab %} +{% endtabs %} + +然后您可以在您的应用程序中使用该方法： + +{% tabs packaging-imports-29 %} +{% tab 'Scala 3 only' %} + +```scala +@main def main = + println(genericMonthConverter(1)) // January + println(genericMonthConverter("jan")) // January +``` +{% endtab %} +{% endtabs %} + +如前所述， `import given` 语法的主要设计优势之一是明确范围内的给定来自何处，并且在这些 `import` 语句中，很清楚地表明给定是来自 `MonthConversions` 对象。 + +[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %} diff --git a/_zh-cn/overviews/scala3-book/scala-features.md b/_zh-cn/overviews/scala3-book/scala-features.md new file mode 100644 index 0000000000..9c8d02f085 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/scala-features.md @@ -0,0 +1,535 @@ +--- +title: Scala 3 特性 +type: chapter +description: This page discusses the main features of the Scala 3 programming language. +language: zh-cn +num: 2 +previous-page: introduction +next-page: why-scala-3 + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +_Scala_ 这个名字来源于 _scalable_ 一词。正如其名，Scala 语言被用于支撑高流量网站以及分析庞大的数据集。 +本节介绍了使 Scala 成为一门可扩展语言的特性。 +这些特性分为三个部分： + +- 高级语言特性 +- 底层语言特性 +- Scala 生态系统特性 + +{% comment %} +I think of this section as being like an “elevator pitch.” +{% endcomment %} + +## 高级特性 + +从宏观视角来看 Scala，您可以对它做出以下陈述： + +- 它是一种高级编程语言 +- 它具有简明易读的语法 +- 它是静态类型的（但使人感觉是动态的） +- 它有一个表达力强大的类型系统 +- 它是一种函数式编程（FP）语言 +- 它是一种面向对象的编程（OOP）语言 +- 它支持 FP 与 OOP 的融合 +- 上下文抽象提供了一种清晰的方式来实现 _表达式推断_ +- 它在 JVM（和浏览器）上运行 +- 它与 Java 代码无缝交互 +- 它可被用于服务器端应用（包括微服务）、大数据应用，也可以在浏览器中与 Scala.js 共同使用 + +以下部分将对这些特性进行简要介绍。 + +### 一门高级语言 + +Scala 至少在两个方面被认为是一门高级语言。 +首先，像 Java 和许多其他现代语言一样，您不需要与指针和内存管理等底层概念打交道。 + +其次，通过使用 lambda 与高阶函数，您可以在非常高的层次上编写代码。 +正如函数式编程的说法，在 Scala 中，您编写您想要 _“什么”_，而不是 _“如何”_ 去实现它。 +也就是说，我们不会像这样编写命令式代码： + +{% tabs scala-features-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=scala-features-1 %} +```scala +import scala.collection.mutable.ListBuffer + +def double(ints: List[Int]): List[Int] = { + val buffer = new ListBuffer[Int]() + for (i <- ints) { + buffer += i * 2 + } + buffer.toList +} + +val oldNumbers = List(1, 2, 3) +val newNumbers = double(oldNumbers) +``` +{% endtab %} +{% tab 'Scala 3' for=scala-features-1 %} +```scala +import scala.collection.mutable.ListBuffer + +def double(ints: List[Int]): List[Int] = + val buffer = new ListBuffer[Int]() + for i <- ints do + buffer += i * 2 + buffer.toList + +val oldNumbers = List(1, 2, 3) +val newNumbers = double(oldNumbers) +``` +{% endtab %} +{% endtabs %} + +这段代码指示编译器逐步执行特定操作。 +相反，我们使用像这样的高阶函数与 lambda 来编写高层次的函数式代码以计算出相同的结果： + +{% tabs scala-features-2 %} +{% tab 'Scala 2 and 3' for=scala-features-2 %} +```scala +val newNumbers = oldNumbers.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +如您所见，该代码更简洁、更容易阅读且更易于维护。 + +### 简明的语法 + +Scala 具有简明易读的语法。例如，变量的创建十分简洁，其类型也很明确。 + +{% tabs scala-features-3 %} +{% tab 'Scala 2 and 3' for=scala-features-3 %} +```scala +val nums = List(1,2,3) +val p = Person("Martin", "Odersky") +``` +{% endtab %} +{% endtabs %} + +高阶函数与 lambda 使代码简明易读： + +{% tabs scala-features-4 %} +{% tab 'Scala 2 and 3' for=scala-features-4 %} +```scala +nums.map(i => i * 2) // long form +nums.map(_ * 2) // short form + +nums.filter(i => i > 1) +nums.filter(_ > 1) +``` +{% endtab %} +{% endtabs %} + +特质（Traits）、类（Class）和方法（Method）都是用简洁、轻巧的语法定义的。 + +{% tabs scala-features-5 class=tabs-scala-version %} +{% tab 'Scala 2' for=scala-features-5 %} +```scala mdoc +trait Animal { + def speak(): Unit +} + +trait HasTail { + def wagTail(): Unit +} + +class Dog extends Animal with HasTail { + def speak(): Unit = println("Woof") + def wagTail(): Unit = println("⎞⎜⎛ ⎞⎜⎛") +} +``` +{% endtab %} +{% tab 'Scala 3' for=scala-features-5 %} +```scala +trait Animal: + def speak(): Unit + +trait HasTail: + def wagTail(): Unit + +class Dog extends Animal, HasTail: + def speak(): Unit = println("Woof") + def wagTail(): Unit = println("⎞⎜⎛ ⎞⎜⎛") +``` +{% endtab %} +{% endtabs %} + +研究表明，开发人员花在 _阅读_ 代码和 _编写_ 代码上的时间比例至少为 10:1。因此，编写简洁 _并_ 易读的代码非常重要。 + +### 动态感受 + +Scala 是一种静态类型的语言，但由于其类型推断能力，它使人感觉是动态的。所有这些表达式看起来都像 Python 或 Ruby 这样的动态类型语言代码，但其实它们都是 Scala 代码： + +{% tabs scala-features-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=scala-features-6 %} +```scala +val s = "Hello" +val p = Person("Al", "Pacino") +val sum = nums.reduceLeft(_ + _) +val y = for (i <- nums) yield i * 2 +val z = nums + .filter(_ > 100) + .filter(_ < 10_000) + .map(_ * 2) +``` +{% endtab %} +{% tab 'Scala 3' for=scala-features-6 %} +```scala +val s = "Hello" +val p = Person("Al", "Pacino") +val sum = nums.reduceLeft(_ + _) +val y = for i <- nums yield i * 2 +val z = nums + .filter(_ > 100) + .filter(_ < 10_000) + .map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +正如 Heather Miller 所说，Scala 被认为是一种[强静态类型语言](https://heather.miller.am/blog/types-in-scala.html)。您可以获得静态类型的全部益处： + +- 正确性：您可以在编译时捕获大多数错误 +- 强大的 IDE 支持 + - 可靠的代码补全 + - 在编译时捕获错误意味着在您打字时捕获错误 + - 简单而可靠的重构 +- 您可以自信地重构您的代码 +- 方法类型声明告诉读者该方法的作用，并作为文档提供帮助 +- 可扩展性与可维护性：类型有助于在任意大小的应用程序与开发团队中确保正确性 +- 强类型结合优秀的推断能力可实现[上下文抽象]({{ site.scala3ref }}/contextual)等机制，这允许您省略样板代码。通常，这些样板代码可由编译器根据类型定义及给定的上下文推断出来。 + +{% comment %} +In that list: +- 'Correctness' and 'Scalability' come from Heather Miller’s page +- the IDE-related quotes in this section come from the Scala.js website: + - catch most errors in the IDE + - Easy and reliable refactoring + - Reliable code completion +{% endcomment %} + +### 富有表现力的类型系统 + +{% comment %} +- this text comes from the current [ScalaTour](https://docs.scala-lang.org/tour/tour-of-scala.html). +- TODO: all of the URLs will have to be updated + +- i removed these items until we can replace them: +* [Compound types](/tour/compound-types.html) +* [conversions](/tour/implicit-conversions.html) +* [Explicitly typed self references](/tour/self-types.html) +{% endcomment %} + +Scala 的类型系统在编译时强制要求以安全与连贯的方式使用抽象概念。特别是，该类型系统支持： + +- [推断类型]({% link _zh-cn/overviews/scala3-book/types-inferred.md %}) +- [泛型类]({% link _zh-cn/overviews/scala3-book/types-generics.md %}) +- [型变]({% link _zh-cn/overviews/scala3-book/types-variance.md %}) +- [类型上界](/tour/upper-type-bounds.html) 与 [类型下界](/tour/lower-type-bounds.html) +- [多态方法](/tour/polymorphic-methods.html) +- [交叉类型]({% link _zh-cn/overviews/scala3-book/types-intersection.md %}) +- [联合类型]({% link _zh-cn/overviews/scala3-book/types-union.md %}) +- [类型 Lambda]({{ site.scala3ref }}/new-types/type-lambdas.html) +- [`given` 实例与 `using` 子句]({% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %}) +- [扩展方法]({% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}) +- [类型类]({% link _zh-cn/overviews/scala3-book/ca-type-classes.md %}) +- [多元相等]({% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %}) +- [不透明类型别名]({% link _zh-cn/overviews/scala3-book/types-opaque-types.md %}) +- [开放类]({{ site.scala3ref }}/other-new-features/open-classes.html) +- [匹配类型]({{ site.scala3ref }}/new-types/match-types.html) +- [依赖函数类型]({{ site.scala3ref }}/new-types/dependent-function-types.html) +- [多态函数类型]({{ site.scala3ref }}/new-types/polymorphic-function-types.html) +- [上下文边界]({{ site.scala3ref }}/contextual/context-bounds.html) +- [上下文函数]({{ site.scala3ref }}/contextual/context-functions.html) +- 作为对象成员的[内部类](/tour/inner-classes.html) 与 [抽象类型](/tour/abstract-type-members.html) + +通过结合使用，这些特性为编程抽象的安全重用及软件的类型安全扩展提供了强大的基础。 + +### 一门函数式编程语言 + +Scala 是一门函数式编程（FP）语言，也就是说： + +- 函数是值，可以像任何其他值一样被传递 +- 直接支持高阶函数 +- 原生地支持 Lambda +- Scala 中的一切都是会返回值的表达式 +- 从语法上来说，使用不可变变量很容易并且此行为被鼓励 +- 在标准库中有大量的不可变集合类 +- 这些集合类带有许多函数式方法：它们不改变集合本身，而是返回数据的更新副本 + +### 一门面向对象语言 + +Scala 是一门面向对象编程（OOP）语言。 +每个值都是一个类的实例，每个“运算符”都是一个方法。 + +在 Scala 中，所有类型都继承自顶层类 `Any`，其直接子类是 `AnyVal`（_值类型_，例如 `Int` 与 `Boolean`）和 `AnyRef`（_引用类型_，与 Java 中相同）。 +这意味着 Scala 中不存在 Java 中原始类型和包装类型的区别（例如 `int` 与 `Integer`）。 +装箱与拆箱对用户来说是完全透明的。 + +{% comment %} +- AnyRef above is wrong in case of strict null checking, no? On the other hand, maybe too much information to state this here +- probably not worth to mention (too advanced at this point) there is AnyKind +- Add the “types hierarchy” image here? +{% endcomment %} + +### 支持 FP 与 OOP 融合 + +{% comment %} +NOTE: This text in the first line comes from this slide: https://x.com/alexelcu/status/996408359514525696 +{% endcomment %} + +Scala 的本质是函数式编程和面向对象编程的融合： + +- 函数用于代表逻辑 +- 对象用于模块化 + +正如 [Martin Odersky 所说](https://jaxenter.com/current-state-scala-odersky-interview-129495.html)，“Scala 旨在表明函数式编程与面向对象编程的融合是切实可行的。” + +### 表达式推断，更加清晰 + +继 Haskell 之后，Scala 是第二种具有某种形式的 _隐式_ 的流行语言。 +在 Scala 3 中，这些概念经过了重新考虑并更清晰地实现。 + +其核心思想是 _表达式推断_：给定一个类型，编译器会合成一个具有该类型的“规范”表达式。 +在 Scala 中，一个上下文参数直接导致一个被推断出的参数项的出现。该参数项也可以被显式地写出来。 + +此概念的用例包括实现[类型类]({% link _overviews/scala3-book/ca-type-classes.md %})、建立上下文、依赖注入、表达能力、计算新类型以及证明它们之间的关系。 + +Scala 3 使此过程比以往任何时候都更加清晰。 +请在[参考文档]({{ site.scala3ref }}/contextual)中阅读关于上下文抽象的内容。 + +### 客户端与服务器 + +Scala 代码在 Java 虚拟机（JVM）上运行，因此您可以获得它的全部益处： + +- 安全性 +- 性能 +- 内存管理 +- 可移植性与平台独立性 +- 能够使用大量的现有 Java 和 JVM 库 + +除了在 JVM 上运行外，Scala 还可以通过 Scala.js （以及开源的第三方工具以集成流行的 JavaScript 库）在浏览器中运行，并且可以使用Scala Native 与 GraalVM 构建原生可执行文件。 + +### 与 Java 无缝交互 + +您可以在 Scala 应用程序中使用 Java 类和库，也可以在 Java 应用程序中使用 Scala 代码。 +对于第二点来说，诸如 [Akka](https://akka.io) 和 [Play Framework](https://www.playframework.com) 之类的大型库是用 Scala 编写的，并且它们可以在 Java 应用程序中使用。 + +对于第一点来说，Scala 应用程序中每天都会用到 Java 类和库。 +例如，在 Scala 中，您可以使用 Java 的 `BufferedReader` 和 `FileReader` 来读取文件： + +{% tabs scala-features-7 %} +{% tab 'Scala 2 and 3' for=scala-features-7 %} +```scala +import java.io.* +val br = BufferedReader(FileReader(filename)) +// read the file with `br` ... +``` +{% endtab %} +{% endtabs %} + +在 Scala 中使用 Java 代码通常是无缝衔接的。 + +Java 集合也可以在 Scala 中使用， 如果您想将 Scala 丰富的集合类方法与其一起使用，只需几行代码即可转换它们： + +{% tabs scala-features-8 %} +{% tab 'Scala 2 and 3' for=scala-features-8 %} +```scala +import scala.jdk.CollectionConverters.* +val scalaList: Seq[Integer] = JavaClass.getJavaList().asScala.toSeq +``` +{% endtab %} +{% endtabs %} + +### 丰富的库 + +正如您将在本页的第三部分中所看到的那样，已经有诸如此类的 Scala 库和框架被编写出来用于支撑高流量网站以及分析庞大的数据集： + +1. [Play Framework](https://www.playframework.com) 是一种用于创建高度可扩展应用程序的轻量级、无状态、对开发者及Web友好的架构 +2. [Apache Spark](https://spark.apache.org) 是一种面向大规模数据处理的统一分析引擎，内置流、SQL、机器学习和图形处理等模块 + +[Awesome Scala 列表](https://github.com/lauris/awesome-scala)展示了开发人员为构建 Scala 应用程序而创建的许多其他开源工具。 + +除了服务器端编程之外，[Scala.js](https://www.scala-js.org) 是一款用于编写 JavaScript 应用的强类型替代方案。其开源的第三方库包含支持与 Facebook 的 React、jQuery 及其他库等集成的工具。 + +{% comment %} +The Lower-Level Features section is like the second part of an elevator pitch. +Assuming you told someone about the previous high-level features and then they say, “Tell me more,” this is what you might tell them. +{% endcomment %} + +## 底层语言特性 + +上一节介绍了 Scala 3 的高级特性，有趣的是，您可以从高层次上对 Scala 2 和 Scala 3 作出相同的表述。 +十年前，Scala 就为各种理想特性打下了坚实基础，正如您在本节中即将看到的那样，这些效益在 Scala 3 中得到了提高。 + +以小见大，从程序员日常使用的语言特性来看，Scala 3 比 Scala 2 具有显著优势： + +- 可以用枚举更简洁地创建代数数据类型（ADT） +- 更简明易读的语法： + - “干净”的控制结构语法更容易阅读 + - 可选的大括号 + - 代码中包含更少的符号，因此会产生更少的视觉噪音，使其更容易阅读 + - 创建类实例时一般不再需要 `new` 关键字 + - 弃用了包对象，转而使用更简单的“顶层”定义 +- 更清晰的语法： + - 移除了 `implicit` 关键字的多种不同用法，这些用法被更显而易见的关键字所取代，如 `given`、 `using`、和 `extension`，以此将关注重点放在意图而不是机制上（详见 [Givens][givens] 部分） + - [扩展方法][extension]通过更加清晰简单的机制取代了隐式类 + - 为类添加了 `open` 修饰符，使开发者能够有意识地声明一个类是可以被修改的，从而限制对代码库的临时扩展 + - [多元相等][multiversal]排除了用 `==` 和 `!=` 进行无意义的比较（即试图将 `Person` 与 `Planet` 进行比较） + - 宏的实现变得更加容易 + - 联合与交叉提供了一种灵活的方式以建模类型 + - 特质参数取代并简化了早期初始化器 + - [不透明类型别名][opaque_types]取代了值类的大多数用途，并确保不进行装箱 + - 导出子句提供了一种简单而通用的方式来表现聚合，它可以取代之前继承自类的包对象的外观模式 + - 删除了过程语法并更改了可变参数语法，这增加了语言一致性 + - `@infix` 注解使得您想让一个方法被如何应用更加显而易见 + - [`@targetName`]({{ site.scala3ref }}/other-new-features/targetName.html) 方法注解为方法定义了一个候补名称。这提高了与 Java 的互操作性，并允许您为符号运算符提供别名 + +在这里演示所有这些特性会占用太多空间，请通过上述内容中的链接来查看这些特性的实际效果。 +所有这些特性都在[概述文档][reference]的*新特性*、*变更的特性*、与*删除的特性*等页面中进行了详细讨论。 + +{% comment %} +CHECKLIST OF ALL ADDED, UPDATED, AND REMOVED FEATURES +===================================================== + +New Features +------------ +- trait parameters +- super traits +- creator applications +- export clauses +- opaque type aliases +- open classes +- parameter untupling +- kind polymorphism +- tupled function +- threadUnsafe annotation +- new control syntax +- optional braces (experimental) +- explicit nulls +- safe initialization + +CHANGED FEATURES +---------------- +- numeric literals +- structural types +- operators +- wildcard types +- type checking +- type inference +- implicit resolution +- implicit conversions +- overload resolution +- match expressions +- vararg patterns +- pattern bindings +- pattern matching +- eta expansion +- compiler plugins +- lazy vals initialization +- main functions + +DROPPED FEATURES +---------------- +- DelayedInit +- macros +- existential types +- type projection +- do/while syntax +- procedure syntax +- package objects +- early initializers +- class shadowing +- limit 22 +- XML literals +- symbol literals +- auto-application +- weak conformance +- nonlocal returns +- [this] qualifier + - private[this] and protected[this] access modifiers are deprecated + and will be phased out +{% endcomment %} + +## Scala 生态系统 + +Scala 拥有一个充满活力的生态系统，有满足各种需求的库和框架。 +[Awesome Scala 列表](https://github.com/lauris/awesome-scala)提供了数百个可供 Scala 开发者使用的开源项目，[Scaladex](https://index.scala-lang.org) 则提供了 Scala 库的可搜索索引。 +以下列出了一些比较著名的库： + +### Web 开发 + +- [Play Framework](https://www.playframework.com) 遵循 Ruby on Rails 模型，是一种用于高度可扩展应用程序的轻量级、无状态、对开发者及Web友好的架构 +- [Scalatra](https://scalatra.org) 是一个小型的、高性能的、异步的网络框架，其灵感来自于 Sinatra +- [Finatra](https://twitter.github.io/finatra) 是基于 TwitterServer 和 Finagle 构建的 Scala 服务 +- [Scala.js](https://www.scala-js.org) 是 JavaScript 的强类型替代品，它提供了一种更安全的方式以构建稳健的前端 Web 应用程序 +- [ScalaJs-React](https://github.com/japgolly/scalajs-react) 将 Facebook 的 React 库整合至 Scala.js，并努力使其尽可能类型安全和 Scala 友好 + +HTTP(S) 库： + +- [Akka-http](https://akka.io) +- [Finch](https://github.com/finagle/finch) +- [Http4s](https://github.com/http4s/http4s) +- [Sttp](https://github.com/softwaremill/sttp) + +JSON 库： + +- [Argonaut](https://github.com/argonaut-io/argonaut) +- [Circe](https://github.com/circe/circe) +- [Json4s](https://github.com/json4s/json4s) +- [Play-JSON](https://github.com/playframework/play-json) + +序列化： + +- [ScalaPB](https://github.com/scalapb/ScalaPB) + +### 科学和数据分析 + +- [Algebird](https://github.com/twitter/algebird) +- [Spire](https://github.com/typelevel/spire) +- [Squants](https://github.com/typelevel/squants) + +### 大数据 + +- [Apache Spark](https://github.com/apache/spark) +- [Apache Flink](https://github.com/apache/flink) + +### 人工智能，机器学习 + +- [BigDL](https://github.com/intel-analytics/BigDL) （用于 Apache Spark 的分布式深度学习框架） +- [TensorFlow Scala](https://github.com/eaplatanios/tensorflow_scala) + +### 函数式编程 & 函数式响应式编程 + +函数式编程： + +- [Cats](https://github.com/typelevel/cats) +- [Zio](https://github.com/zio/zio) + +函数式响应式编程（FRP） + +- [fs2](https://github.com/typelevel/fs2) +- [monix](https://github.com/monix/monix) + +### 构建工具 + +- [sbt](https://www.scala-sbt.org) +- [Gradle](https://gradle.org) +- [Mill](https://github.com/lihaoyi/mill) + +## 总结 + +如此页所示，Scala 在高层、日常编程层面以及贯穿开发者生态系统都具有许多出色的编程语言特性。 + + +[reference]: {{ site.scala3ref }}/overview.html +[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} +[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %} +[opaque_types]: {% link _zh-cn/overviews/scala3-book/types-opaque-types.md %} diff --git a/_zh-cn/overviews/scala3-book/scala-for-java-devs.md b/_zh-cn/overviews/scala3-book/scala-for-java-devs.md new file mode 100644 index 0000000000..c8f449fd56 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/scala-for-java-devs.md @@ -0,0 +1,1279 @@ +--- +title: 向 Java 开发者介绍Scala +type: chapter +description: This page is for Java developers who are interested in learning about Scala 3. +language: zh-cn +num: 73 +previous-page: interacting-with-java +next-page: scala-for-javascript-devs + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +{% include_relative scala4x.css %} +
            + +此页面通过共享每种语言的并排示例，对 Java 和 Scala 编程语言进行了比较。 +它适用于了解 Java 并希望了解 Scala 的程序员，特别是通过 Scala 特性与 Java 特性的对比来了解。 + +## 概述 + +在进入示例之前，第一部分提供了以下部分的相对简短的介绍和总结。 +它从高层次上介绍了 Java 和 Scala 之间的异同，然后介绍了您在每天编写代码时会遇到的差异。 + +### 高层次的相似性 + +在高层次上，Scala 与 Java 有以下相似之处： + +- Scala代码编译成_.class_文件，打包成JAR文件，运行在JVM上 +- 这是一种[面向对象编程][modeling-oop] (OOP) 语言 +- 它是静态类型的 +- 两种语言都支持 lambdas 和 [高阶函数][hofs] +- 它们都可以与 IntelliJ IDEA 和 Microsoft VS Code 等 IDE 一起使用 +- 可以使用 Gradle、Ant 和 Maven 等构建工具构建项目 +- 它具有用于构建服务器端、网络密集型应用程序的出色库和框架，包括 Web 服务器应用程序、微服务、机器学习等（参见 [“Awesome Scala” 列表](https://github.com/lauris/awesome-scala)） +- Java 和 Scala 都可以使用 Scala 库： + - 他们可以使用 [Akka actor 库](https://akka.io) 来构建基于 actor 的并发系统，并使用 Apache Spark 来构建数据密集型应用程序 + - 他们可以使用 [Play Framework](https://www.playframework.com) 开发服务器端应用程序 +- 您可以使用 [GraalVM](https://www.graalvm.org) 将您的项目编译为本机可执行文件 +- Scala 可以无缝使用为 Java 开发的大量库 + +### 高层次的差异 + +同样在高层次上，Java 和 Scala 之间的区别是： + +- Scala 语法简洁易读；我们称之为_表现力_ +- 虽然它是静态类型的，但 Scala 经常感觉像是一门动态语言 +- Scala 是一种纯 OOP 语言，因此每个对象都是类的一个实例，而像运算符一样的符号 `+` 和 `+=` 是真正的方法；这意味着您可以创建自己的运算符 +- 除了是纯OOP语言，Scala还是纯FP语言；实际上，它鼓励 OOP 和 FP 的融合，具有用于逻辑的函数和用于模块化的对象 +- Scala 拥有一整套不可变集合，包括 `List`、`Vector` 和不可变的 `Map` 和 `Set` 实现 +- Scala 中的一切都是一个_表达式_：像 `if` 语句、`for` 循环、`match` 表达式，甚至 `try`/`catch` 表达式都有返回值 +- Scala 习惯上倾向缺省使用不可变性：鼓励您使用不可变（`final`）变量和不可变集合 +- 惯用的 Scala 代码不使用 `null`，因此不会遭受 `NullPointerException` +- Scala 生态系统在 sbt、Mill 等中还有其他 [构建工具][tools] +- 除了在 JVM 上运行之外，[Scala.js](https://www.scala-js.org) 项目允许您使用 Scala 作为 JavaScript 替代品 +- [Scala Native](http://www.scala-native.org) 项目添加了低级结构，让您可以编写“系统”级代码，也可以编译为本机可执行文件 + +{% comment %} +These are several notes that came up early in the writing process, and I (Alvin) can’t really address them: +TODO: Need a good, simple way to state that Scala has a sound type system +TODO: Points to make about Scala’s consistency? +TODO: Add a point about how the type system lets you express details as desired +{% endcomment %} + +### 编程层次差异 + +最后，这些是您在编写代码时每天都会看到的一些差异： + +- Scala 的语法极其一致 +- 变量和参数被定义为`val`（不可变，如Java中的`final`）或`var`（可变） +- _类型推导_ 让您的代码感觉是动态类型的，并有助于保持您的代码简洁 +- 除了简单的 `for` 循环之外，Scala 还具有强大的 `for` comprehensions，可以根据您的算法产生结果 +- 模式匹配和 `match` 表达式将改变你编写代码的方式 +- 默认情况下编写不可变代码会导致编写_表达式_而不是_语句_；随着时间的推移，您会发​​现编写表达式可以简化您的代码（和您的测试） +- [顶层定义][toplevel] 让您可以将方法、字段和其他定义放在任何地方，同时也带来简洁、富有表现力的代码 +- 您可以通过将多个 traits “混合”到类和对象中来创建_混搭_（特征类似于 Java 8 和更新版本中的接口） +- 默认情况下类是封闭的，支持 Joshua Bloch 在 _Effective Java_ 的习惯用法，“Design and document for inheritance or else forbid it” +- Scala 的 [上下文抽象][contextual] 和 _术语推导_ 提供了一系列特性： + - [扩展方法][extension-methods] 让您向封闭类添加新功能 + - [_给_实例][givens] 让您定义编译器可以在 _using_ 点合成的术语，从而使您的代码不那么冗长，实质上让编译器为您编写代码 + - [多元等式][multiversal] 允许您在编译时将相等比较限制为仅那些有意义的比较 +- Scala 拥有最先进的第三方开源函数式编程库 +- Scala 样例类就像 Java 14 中的记录；它们可以帮助您在编写 FP 代码时对数据进行建模，并内置对模式匹配和克隆等概念的支持 +- 由于名称参数、中缀符号、可选括号、扩展方法和 [高阶函数][hofs] 等功能，您可以创建自己的“控制结构”和 DSL +- Scala 文件不必根据它们包含的类或 trait 来命名 +- 许多其他好东西：伴生类和对象、宏、[联合][union-types] 和 [交集][intersection-types]、数字字面量、多参数列表、参数的默认值、命名参数等 + +### 用例子来进行特性对比 + +鉴于该介绍，以下部分提供了 Java 和 Scala 编程语言功能的并排比较。 + +## OOP 风格的类和方法 + +本节提供了与 OOP 风格的类和方法相关的特性的比较。 + +### 注释： + + + + + + + + + + +
            + // +
            /* ... */ +
            /** ... */             +
            + // +
            /* ... */ +
            /** ... */             +
            + +### OOP 风格类，主构造函数： + +Scala不遵循JavaBeans标准，因此我们在这里展示的Java代码 +与它后面的Scala代码等效，而不是显示以JavaBeans风格编写 +的Java代码。 + + + + + + + + + + +
            + class Person { +
              public String firstName; +
              public String lastName; +
              public int age; +
              public Person( +
                String firstName, +
                String lastName, +
                int age +
              ) { +
                this.firstName = firstName; +
                this.lastName = lastName; +
                this.age = age; +
              } +
              public String toString() { +
                return String.format("%s %s is %d years old.", firstName, lastName, age); +
              } +
            }             +
            + class Person ( +
              var firstName: String, +
              var lastName: String, +
              var age: Int +
            ):   +
              override def toString = s"$firstName $lastName is $age years old." +             +
            + +### 辅助构造函数： + + + + + + + + + + +
            + public class Person { +
              public String firstName; +
              public String lastName; +
              public int age; +
            +
              // primary constructor +
              public Person( +
                String firstName, +
                String lastName, +
                int age +
              ) { +
                this.firstName = firstName; +
                this.lastName = lastName; +
                this.age = age; +
              } +
            +
              // zero-arg constructor +
              public Person() { +
                this("", "", 0); +
              } +
            +
              // one-arg constructor +
              public Person(String firstName) { +
                this(firstName, "", 0); +
              } +
            +
              // two-arg constructor +
              public Person( +
                String firstName, +
                String lastName +
              ) { +
                this(firstName, lastName, 0); +
              } +
            +
            }             +
            + class Person ( +
              var firstName: String, +
              var lastName: String, +
              var age: Int +
            ): +
                // zero-arg auxiliary constructor +
                def this() = this("", "", 0) +
            +
                // one-arg auxiliary constructor +
                def this(firstName: String) = +
                  this(firstName, "", 0) +
            +
                // two-arg auxiliary constructor +
                def this( +
                  firstName: String, +
                  lastName: String +
                ) = +
                  this(firstName, lastName, 0) +
            +
            end Person             +
            + +### 类默认是封闭的： +“Plan for inheritance or else forbid it.” + + + + + + + + + + +
            + final class Person +
            + class Person +
            + +### 为扩展开放的类： + + + + + + + + + + +
            + class Person +
            + open class Person +
            + +### 单行方法： + + + + + + + + + + +
            + public int add(int a, int b) { +
              return a + b; +
            }             +
            + def add(a: Int, b: Int): Int = a + b +
            + +### 多行方法： + + + + + + + + + + +
            + public void walkThenRun() { +
              System.out.println("walk"); +
              System.out.println("run"); +
            }             +
            + def walkThenRun() = +
              println("walk") +
              println("run")             +
            + +### 不可变字段： + + + + + + + + + + +
            + final int i = 1; +
            + val i = 1 +
            + +### 可变字段： + + + + + + + + + + +
            + int i = 1; +
            var i = 1;             +
            + var i = 1 +
            + +## 接口、trait 和继承 + +本节将Java接口与Scala trait 进行比较，包括类如何扩展接口和 trait。 + +### 接口/trait： + + + + + + + + + + +
            + public interface Marker; +
            + trait Marker +
            + +### 简单接口： + + + + + + + + + + +
            + public interface Adder { +
              public int add(int a, int b); +
            }             +
            + trait Adder: +
              def add(a: Int, b: Int): Int             +
            + +### 有实体方法的接口： + + + + + + + + + + +
            + public interface Adder { +
              int add(int a, int b); +
              default int multiply( +
                int a, int b +
              ) { +
                return a * b; +
              } +
            }             +
            + trait Adder: +
              def add(a: Int, b: Int): Int +
              def multiply(a: Int, b: Int): Int = +
                a * b             +
            + +### 继承： + + + + + + + + + + +
            + class Dog extends Animal implements HasLegs, HasTail +
            + class Dog extends Animal, HasLegs, HasTail +
            + +### 扩展多个接口 + +这些接口和特征具有具体的、已实现的方法（默认方法）： + + + + + + + + + + +
            + interface Adder { +
              default int add(int a, int b) { +
                return a + b; +
              } +
            } +
            +
            interface Multiplier { +
              default int multiply ( +
                int a, +
                int b) +
              { +
                return a * b; +
              } +
            } +
            +
            public class JavaMath
            implements Adder, Multiplier {} +
            +
            JavaMath jm = new JavaMath(); +
            jm.add(1,1); +
            jm.multiply(2,2);             +
            + trait Adder: +
              def add(a: Int, b: Int) = a + b +
            +
            trait Multiplier: +
              def multiply(a: Int, b: Int) = a * b +
            +
            class ScalaMath extends Adder, Multiplier +
            +
            val sm = new ScalaMath +
            sm.add(1,1) +
            sm.multiply(2,2)             +
            + +### 混搭： + + + + + + + + + + +
            + N/A +
            + class DavidBanner +
            +
            trait Angry: +
              def beAngry() = +
                println("You won’t like me ...") +
            +
            trait Big: +
              println("I’m big") +
            +
            trait Green: +
              println("I’m green") +
            +
            // mix in the traits as DavidBanner +
            // is created +
            val hulk = new DavidBanner with Big with Angry with Green +             +
            + +## 控制结构 + +本节比较在 Java 和 Scala 中的[控制结构][control]。 + +### `if` 语句，单行： + + + + + + + + + + +
            + if (x == 1) { System.out.println(1); } +
            + if x == 1 then println(x) +
            + +### `if` 语句，多行： + + + + + + + + + + +
            + if (x == 1) { +
              System.out.println("x is 1, as you can see:") +
              System.out.println(x) +
            }             +
            + if x == 1 then +
              println("x is 1, as you can see:") +
              println(x)             +
            + +### if, else if, else: + + + + + + + + + + +
            + if (x < 0) { +
              System.out.println("negative") +
            } else if (x == 0) { +
              System.out.println("zero") +
            } else { +
              System.out.println("positive") +
            }             +
            + if x < 0 then +
              println("negative") +
            else if x == 0 +
              println("zero") +
            else +
              println("positive")             +
            + +### `if` 作为方法体： + + + + + + + + + + +
            + public int min(int a, int b) { +
              return (a < b) ? a : b; +
            }             +
            + def min(a: Int, b: Int): Int = +
              if a < b then a else b             +
            + +### 从 `if` 返回值： + +在 Java 中调用_三元运算符_： + + + + + + + + + + +
            + int minVal = (a < b) ? a : b; +
            + val minValue = if a < b then a else b +
            + +### `while` 循环： + + + + + + + + + + +
            + while (i < 3) { +
              System.out.println(i); +
              i++; +
            }             +
            + while i < 3 do +
              println(i) +
              i += 1             +
            + +### `for` 循环，单行： + + + + + + + + + + +
            + for (int i: ints) { +
              System.out.println(i); +
            }             +
            + //preferred +
            for i <- ints do println(i) +
            +
            // also available +
            for (i <- ints) println(i)             +
            + +### `for` 循环，多行： + + + + + + + + + + +
            + for (int i: ints) { +
              int x = i * 2; +
              System.out.println(x); +
            }             +
            + for +
              i <- ints +
            do +
              val x = i * 2 +
              println(s"i = $i, x = $x")             +
            + +### `for` 循环，多生成器： + + + + + + + + + + +
            + for (int i: ints1) { +
              for (int j: chars) { +
                for (int k: ints2) { +
                  System.out.printf("i = %d, j = %d, k = %d\n", i,j,k); +
                } +
              } +
            }             +
            + for +
              i <- 1 to 2 +
              j <- 'a' to 'b' +
              k <- 1 to 10 by 5 +
            do +
              println(s"i = $i, j = $j, k = $k")             +
            + +### 带守卫（`if`）表达式的生成器： + + + + + + + + + + +
            + List ints = +
              ArrayList(1,2,3,4,5,6,7,8,9,10); +
            +
            for (int i: ints) { +
              if (i % 2 == 0 && i < 5) { +
                System.out.println(x); +
              } +
            }             +
            + for +
              i <- 1 to 10 +
              if i % 2 == 0 +
              if i < 5 +
            do +
              println(i)             +
            + +### `for` comprehension: + + + + + + + + + + +
            + N/A +
            + val list = +
              for +
                i <- 1 to 3 +
              yield +
                i * 10 +
            // list: Vector(10, 20, 30)             +
            + +### switch/match: + + + + + + + + + + +
            + String monthAsString = ""; +
            switch(day) { +
              case 1: monthAsString = "January"; +
                      break; +
              case 2: monthAsString = "February"; +
                      break; +
              default: monthAsString = "Other"; +
                      break; +
            }             +
            + val monthAsString = day match +
              case 1 => "January" +
              case 2 => "February" +
              _ => "Other" +             +
            + +### switch/match, 每个情况下多个条件： + + + + + + + + + + +
            + String numAsString = ""; +
            switch (i) { +
              case 1: case 3: +
              case 5: case 7: case 9: +
                numAsString = "odd"; +
                break; +
              case 2: case 4: +
              case 6: case 8: case 10: +
                numAsString = "even"; +
                break; +
              default: +
                numAsString = "too big"; +
                break; +
            }             +
            + val numAsString = i match +
              case 1 | 3 | 5 | 7 | 9 => "odd" +
              case 2 | 4 | 6 | 8 | 10 => "even" +
              case _ => "too big" +             +
            + +### try/catch/finally: + + + + + + + + + + +
            + try { +
              writeTextToFile(text); +
            } catch (IOException ioe) { +
              println(ioe.getMessage()) +
            } catch (NumberFormatException nfe) { +
              println(nfe.getMessage()) +
            } finally { +
              println("Clean up resources here.") +
            }             +
            + try +
              writeTextToFile(text) +
            catch +
              case ioe: IOException => +
                println(ioe.getMessage) +
              case nfe: NumberFormatException => +
                println(nfe.getMessage) +
            finally +
              println("Clean up resources here.")             +
            + +## 集合类 + +本节比较 Java 和 Scala 里的[集合类][collections-classes]。 + +### 不可变集合类 + +如何创建不可变集合实例的例子。 + +### Sequences: + + + + + + + + + + +
            + List strings = List.of("a", "b", "c"); +
            + val strings = List("a", "b", "c") +
            val strings = Vector("a", "b", "c")             +
            + +### Sets: + + + + + + + + + + +
            + Set set = Set.of("a", "b", "c"); +
            + val set = Set("a", "b", "c") +
            + +### Maps: + + + + + + + + + + +
            + Map map = Map.of( +
              "a", 1, +
              "b", 2, +
              "c", 3 +
            );             +
            + val map = Map( +
              "a" -> 1, +
              "b" -> 2, +
              "c" -> 3 +
            )             +
            + +### 可变集合类 + +Scala 在其 _scala.collection.mutable_ 包中有可变集合类，例如 `ArrayBuffer`、`Map` 和 `Set`。 +在 [导入它们][imports] 到当前作用域之后，创建它们就像刚刚显示的不可变 `List`、`Vector`、`Map` 和 `Set` 示例一样。 + +Scala 还有一个 `Array` 类，您可以将其视为 Java `array` 原始类型的包装器。 +一个 Scala `Array[A]` 映射到一个 Java `A[]`，所以你可以认为这个是 Scala `Array[String]`： + +```scala +val a = Array("a", "b") +``` + +这个追溯到 Java 的 `String[]`: + +```java +String[] a = {"a", "b"}; +``` + +但是，Scala `Array` 还具有您期望在 Scala 集合中使用的所有函数方法，包括 `map` 和 `filter`： + +```scala +val nums = Array(1, 2, 3, 4, 5) +val doubledNums = nums.map(_ * 2) +val 过滤Nums = nums.filter(_ > 2) +``` + +因为 Scala `Array` 的表示方式与 Java `array` 相同，所以您可以轻松地在 Scala 代码中使用返回数组的 Java 方法。 + +> 尽管讨论了 `Array`，但请记住，在 Scala 中通常有可能更适合的 `Array` 替代品。 +> 数组对于与其他语言（Java、JavaScript）的互操作很有用，并且在编写需要从底层平台获得最大性能的低级代码时也很有用。但总的来说，当你需要使用序列时，Scala 的习惯用法是更喜欢像 `Vector` 和 `List` 这样的不可变序列，然后在你真的需要可变序列时使用 `ArrayBuffer`。 + +您还可以使用 Scala `CollectionConverters` 对象在 Java 和 Scala 集合类之间进行转换。 +在不同的包中有两个对象，一个用于从 Java 转换为 Scala，另一个用于从 Scala 转换为 Java。 +下表显示了可能的转换： + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            JavaScala
            java.util.Collectionscala.collection.Iterable
            java.util.Listscala.collection.mutable.Buffer
            java.util.Setscala.collection.mutable.Set
            java.util.Mapscala.collection.mutable.Map
            java.util.concurrent.ConcurrentMapscala.collection.mutable.ConcurrentMap
            java.util.Dictionaryscala.collection.mutable.Map
            + +## 集合类的方法 + +由于能够将 Java 集合视为流，Java 和 Scala 现在可以使用许多相同的通用函数方法： + +- `map` +- `filter` +- `forEach`/`foreach` +- `findFirst`/`find` +- `reduce` + +如果您习惯在 Java 中将这些方法与 lambda 表达式一起使用，您会发现在 Scala 的 [集合类][collections-classes] 上使用相同的方法很容易。 + +Scala 也有_数十个_其他 [集合方法][collections-methods]，包括 `head`、`tail`、`drop`、`take`、`distinct`、`flatten` 等等。 +起初你可能想知道为什么会有这么多方法，但是在使用 Scala 之后你会意识到_因为_有这些方法，你很少需要再编写自定义的 `for` 循环了。 + +（这也意味着你也很少需要_读_自定义的 `for` 循环。 +因为开发人员倾向于在_读_代码上花费的时间是_编写_代码的十倍，这很重要。） + +## 元组 + +Java 元组是这样创建的： + +```scala +Pair pair = + new Pair("Eleven", 11); + +Triplet triplet = + Triplet.with("Eleven", 11, 11.0); +Quartet triplet = + Quartet.with("Eleven", 11, 11.0, new Person("Eleven")); +``` + +其他 Java 元组名称是 Quintet、Sextet、Septet、Octet、Ennead、Decade。 + +Scala 中任何大小的元组都是通过将值放在括号内来创建的，如下所示： + +```scala +val a = ("eleven") +val b = ("eleven", 11) +val c = ("eleven", 11, 11.0) +val d = ("eleven", 11, 11.0, Person("Eleven")) +``` + +## 枚举 + +本节比较 Java 和 Scala 中的枚举。 + +### 基本枚举： + + + + + + + + + + +
            + enum Color { +
              RED, GREEN, BLUE +
            }             +
            + enum Color: +
              case Red, Green, Blue             +
            + +### 参数化的枚举： + + + + + + + + + + +
            + enum Color { +
              Red(0xFF0000), +
              Green(0x00FF00), +
              Blue(0x0000FF); +
            +
              private int rgb; +
            +
              Color(int rgb) { +
                this.rgb = rgb; +
              } +
            }             +
            + enum Color(val rgb: Int): +
              case Red   extends Color(0xFF0000) +
              case Green extends Color(0x00FF00) +
              case Blue  extends Color(0x0000FF)             +
            + +### 用户定义的枚举成员： + + + + + + + + + + +
            + enum Planet { +
              MERCURY (3.303e+23, 2.4397e6), +
              VENUS   (4.869e+24, 6.0518e6), +
              EARTH   (5.976e+24, 6.37814e6); +
              // more planets ... +
            +
              private final double mass; +
              private final double radius; +
            +
              Planet(double mass, double radius) { +
                this.mass = mass; +
                this.radius = radius; +
              } +
            +
              public static final double G = +
                6.67300E-11; +
            +
              private double mass() { +
                return mass; +
              } +
            +
              private double radius() { +
                return radius; +
              } +
            +
              double surfaceGravity() { +
                return G * mass / +
                  (radius * radius); +
              } +
            +
              double surfaceWeight( +
                double otherMass +
              ) { +
                return otherMass * +
                  surfaceGravity(); +
              } +
            +
            }             +
            + enum Planet( +
              mass: Double, +
              radius: Double +
            ): +
              case Mercury extends
                Planet(3.303e+23, 2.4397e6) +
              case Venus extends
                Planet(4.869e+24, 6.0518e6) +
              case Earth extends
                Planet(5.976e+24, 6.37814e6) +
                // more planets ... +
            +
              private final val G = 6.67300E-11 +
            +
              def surfaceGravity =
                G * mass / (radius * radius) +
            +
              def surfaceWeight(otherMass: Double) +
                = otherMass * surfaceGravity             +
            + +## 异常和错误处理 + +本节介绍 Java 和 Scala 中的异常处理之间的差异。 + +### Java 使用检查异常 + +Java 使用检查的异常，因此在 Java 代码中，您历来编写过 `try`/`catch`/`finally` 块，以及方法上的 `throws` 子句： + +```scala +public int makeInt(String s) +throws NumberFormatException { + // code here to convert a String to an int +} +``` + +### Scala 不使用检查异常 + +Scala 的习惯用法是_不_使用这样的检查异常。 +在处理可能抛出异常的代码时，您可以使用 `try`/`catch`/`finally` 块从抛出异常的代码中捕获异常，但是如何从那里开始的方式是不同的。 + +解释这一点的最好方法是说 Scala 代码是由具有返回值的_表达式_组成的。 +其结果是，最终你写代就像写一系列代数表达式： + +```scala +val a = f(x) +val b = g(a,z) +val c = h(b,y) +``` + +这很好，它只是代数。 +您创建方程来解决小问题，然后组合方程来解决更大的问题。 + +非常重要的是——正如你在代数课程中所记得的那样——代数表达式不会短路——它们不会抛出会破坏一系列方程的异常。 + +因此，在 Scala 中，我们的方法不会抛出异常。 +相反，它们返回像 `Option` 这样的类型。 +例如，这个 `makeInt` 方法捕获一个可能的异常并返回一个 `Option` 值： + +```scala +def makeInt(s: String): Option[Int] = + try + Some(s.toInt) + catch + case e: NumberFormatException => None +``` + +Scala `Option` 类似于 Java `Optional` 类。 +如图所示，如果 string 到 int 的转换成功，则在 `Some` 值中返回 `Int`，如果失败，则返回 `None` 值。 +`Some` 和 `None` 是 `Option` 的子类型，因此该方法被声明为返回 `Option[Int]` 类型。 + +当您有一个 `Option` 值时，例如 `makeInt` 返回的值，有很多方法可以使用它，具体取决于您的需要。 +此代码显示了一种可能的方法： + +```scala +makeInt(aString) match + case Some(i) => println(s"Int i = $i") + case None => println(s"Could not convert $aString to an Int.") +``` + +`Option` 在 Scala 中很常用，它内置在标准库的许多类中。 +其他类似的类的集合，例如 Try/Success/Failure 和 Either/Left/Right，提供了更大的灵活性。 + +有关在 Scala 中处理错误和异常的更多信息，请参阅 [函数式错误处理][error-handling] 部分。 + +## Scala 独有的概念 + +以上就是 Java 和 Scala 语言的比较。 + +Scala 中还有其他一些概念目前在 Java 11 中是没有的。 +这包括： + +- 与 Scala 的 [上下文抽象][contextual] 相关的一切 +- 几个 Scala 方法特性： + - 多参数列表 + - 默认参数值 + - 调用方法时使用命名参数 +- 样例类（如 Java 14 中的“记录”）、样例对象以及伴生类和对象（参见 [领域建模][modeling-intro]）一章 +- 创建自己的控制结构和 DSL 的能力 +- [顶级定义][toplevel] +- 模式匹配 +- `match` 表达式的高级特性 +- 类型 lambdas +- trait参数 +- [不透明类型别名][opaque] +- [多元相等性][equality] +- [类型类][type-classes] +- 中缀方法 +- 宏和元编程 + + +[collections-classes]: {% link _zh-cn/overviews/scala3-book/collections-classes.md %} +[collections-methods]: {% link _zh-cn/overviews/scala3-book/collections-methods.md %} +[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %} +[equality]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} +[error-handling]: {% link _zh-cn/overviews/scala3-book/fp-functional-error-handling.md %} +[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %} +[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %} +[imports]: {% link _zh-cn/overviews/scala3-book/packaging-imports.md %} +[modeling-intro]: {% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %} +[modeling-oop]: {% link _zh-cn/overviews/scala3-book/domain-modeling-oop.md %} +[opaque]: {% link _zh-cn/overviews/scala3-book/types-opaque-types.md %} +[tools]: {% link _zh-cn/overviews/scala3-book/scala-tools.md %} +[toplevel]: {% link _zh-cn/overviews/scala3-book/taste-toplevel-definitions.md %} +[type-classes]: {% link _zh-cn/overviews/scala3-book/ca-type-classes.md %} + +[concurrency]: {% link _zh-cn/overviews/scala3-book/concurrency.md %} +[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %} +[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %} +[intersection-types]: {% link _zh-cn/overviews/scala3-book/types-intersection.md %} +[modeling-fp]: {% link _zh-cn/overviews/scala3-book/domain-modeling-fp.md %} +[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} +[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %} + +
            diff --git a/_zh-cn/overviews/scala3-book/scala-for-javascript-devs.md b/_zh-cn/overviews/scala3-book/scala-for-javascript-devs.md new file mode 100644 index 0000000000..0ec0816eed --- /dev/null +++ b/_zh-cn/overviews/scala3-book/scala-for-javascript-devs.md @@ -0,0 +1,1336 @@ +--- +title: Scala for JavaScript Developers +type: chapter +description: This chapter provides an introduction to Scala 3 for JavaScript developers +language: zh-cn +num: 74 +previous-page: scala-for-java-devs +next-page: scala-for-python-devs + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +{% include_relative scala4x.css %} +
            + +此页面提供了 JavaScript 和 Scala 编程语言之间的比较。 +它适用于了解 JavaScript 并希望了解 Scala 的程序员，特别是通过查看 JavaScript 语言功能与 Scala 比较的示例。 + +## 概述 + +本节对以下各节进行了相对简短的介绍和总结。 +它从高层次上介绍了 JavaScript 和 Scala 之间的异同，然后介绍了您在每天编写代码时会遇到的差异。 + +### 高层次的相似性 + +在高层次上，Scala 与 JavaScript 有以下相似之处： + +- 两者都被认为是高级编程语言，您不必关心指针和手动内存管理等低级概念 +- 两者都有一个相对简单、简洁的语法 +- 两者都支持 C/C++/Java 风格的花括号语法，用于编写方法和其他代码块 +- 两者都包括面向对象编程 (OOP) 的特性（如类） +- 两者都包含用于 [函数式编程][fp-intro] (FP) 的（如 lambda） +- JavaScript 在浏览器和 Node.js 等其他环境中运行。 + Scala 的 [Scala.js](https://www.scala-js.org) 风格以 JavaScript 为目标，因此 Scala 程序可以在相同的环境中运行。 +- 开发人员使用 [Node.js](https://nodejs.org) 在 JavaScript 和 Scala 中编写服务器端应用程序； [Play Framework](https://www.playframework.com/) 之类的项目也可以让您在 Scala 中编写服务器端应用程序 +- 两种语言都有相似的 `if` 语句、`while` 循环和 `for` 循环 +- 从 [在这个 Scala.js 页面](https://www.scala-js.org/libraries/index.html) 开始，您会发现许多支持 React、Angular、jQuery 和许多其他 JavaScript 和Scala 库 +- JavaScript 对象是可变的；以命令式风格编写时，Scala 对象_可以_是可变的 +- JavaScript 和 Scala 都支持 _promises_ 作为处理异步计算结果的一种方式（[Scala concurrency][concurrency] 使用期货和承诺） + +### 高层次差异 + +同样在高层次上，JavaScript 和 Scala 之间的一些区别是： + +- JavaScript 是动态类型的，Scala 是静态类型的 + - 尽管 Scala 是静态类型的，但类型推断之类的特性让它感觉像是一种动态语言（正如您将在下面的示例中看到的那样） +- Scala 惯用语默认支持不变性：鼓励您使用不可变变量和不可变集合 +- Scala 语法简洁易读；我们称之为_表现力_ +- Scala 是一种纯 OOP 语言，因此每个对象都是类的一个实例，而像运算符一样的符号 `+` 和 `+=` 是真正的方法；这意味着您可以创建自己的方法作为运算符 +- 作为一种纯 OOP 语言和纯 FP 语言，Scala 鼓励 OOP 和 FP 的融合，具有用于逻辑的函数和用于模块化的不可变对象 +- Scala 拥有最先进的第三方开源函数式编程库 +- Scala 中的一切都是一个_表达式_：像 `if` 语句、`for` 循环、`match` 表达式，甚至 `try`/`catch` 表达式都有返回值 +- [Scala Native](https://scala-native.org/) 项目让您可以编写“系统”级代码，也可以编译为本机可执行文件 + +### 编程层次差异 + +在较低的层次上，这些是您在编写代码时每天都会看到的一些差异： + +- Scala 变量和参数使用 `val`（不可变，如 JavaScript `const`）或 `var`（可变，如 JavaScript `var` 或 `let`）定义 +- Scala 不在行尾使用分号 +- Scala 是静态类型的，尽管在许多情况下您不需要声明类型 +- Scala 使用 trait 作为接口并创建_混搭_ +- 除了简单的 `for` 循环之外，Scala 还具有强大的 `for` comprehensions，可以根据您的算法产生结果 +- 模式匹配和 `match` 表达式将改变你编写代码的方式 +- Scala 的 Scala 的 [上下文抽象][contextual] 和 _术语推导_ 提供了一系列特性： + - [扩展方法][extension-methods] 允许您在不破坏模块化的情况下向封闭类添加新功能，方法是仅在特定范围内可用（与猴子补丁相反，它会污染代码的其他区域） + - [给实例][givens] 让您定义编译器可以用来为您合成代码的术语 + - 类型安全和[多元等式][multiversal]让您将相等比较——在编译时——仅限于那些有意义的比较 +- 由于名称参数、中缀符号、可选括号、扩展方法和 [高阶函数][hofs] 等功能，您可以创建自己的“控制结构”和 DSL +- 您可以在本书中阅读到许多其他好东西：样例类、伴生类和对象、宏、[联合][union-type]和[交集][intersection-types]类型、多参数列表、命名参数等 + +## 变量和类型 + +### 注释 + + + + + + + + + + +
            + // +
            /* ... */ +
            /** ... */             +
            + // +
            /* ... */ +
            /** ... */             +
            + +### 可变变量 + + + + + + + + + + +
            + let   // now preferred for mutable +
            var   // old mutable style             +
            + var  // used for mutable variables +
            + +### 不可变变量 + + + + + + + + + + +
            + const +
            + val +
            + +Scala 的经验法则是使用 `val` 声明变量，除非有特定原因需要可变变量。 + +## 命名标准 + +JavaScript 和 Scala 通常使用相同的 _CamelCase_ 命名标准。 +变量命名为 `myVariableName`，方法命名为 `lastIndexOf`，类和对象命名为 `Animal` 和 `PrintedBook` 。 + +## 字符串 + +JavaScript 和 Scala 中字符串的许多用法相似，但 Scala 仅对简单字符串使用双引号，对多行字符串使用三引号。 + +### 字符串基础 + + + + + + + + + + +
            + // use single- or double-quotes +
            let msg = 'Hello, world'; +
            let msg = "Hello, world";             +
            + // use only double-quotes +
            val msg = "Hello, world"             +
            + +### 插入 + + + + + + + + + + +
            + let name = 'Joe'; +
            +
            // JavaScript uses backticks +
            let msg = `Hello, ${name}`;             +
            + val name = "Joe" +
            val age = 42 +
            val weight = 180.5 +
            +
            // use `s` before a string for simple interpolation +
            println(s"Hi, $name")   // "Hi, Joe" +
            println(s"${1 + 1}")    // "2" +
            +
            // `f` before a string allows printf-style formatting. +
            // this example prints: +
            // "Joe is 42 years old, and weighs" +
            // "180.5 pounds." +
            println(f"$name is $age years old, and weighs $weight%.1f pounds.")             +
            + +### 带插入的多行字符串 + + + + + + + + + + +
            + let name = "joe"; +
            let str = ` +
            Hello, ${name}. +
            This is a multiline string. +
            `; +             +
            + val name = "Martin Odersky" +
            +
            val quote = s""" +
            |$name says +
            |Scala is a fusion of +
            |OOP and FP. +
            """.stripMargin.replaceAll("\n", " ").trim +
            +
            // result: +
            // "Martin Odersky says Scala is a fusion of OOP and FP." +             +
            + +JavaScript 和 Scala 也有类似的处理字符串的方法，包括 `charAt`、`concat`、`indexOf` 等等。 +`\n`、`\f`、`\t` 等转义字符在两种语言中也是相同的。 + +## 数字和算术 + +JavaScript 和 Scala 之间的数字运算符很相似。 +最大的不同是 Scala 不提供 `++` 和 `--` 运算符。 + +### 数字运算符： + + + + + + + + + + +
            + let x = 1; +
            let y = 2.0; +
              +
            let a = 1 + 1; +
            let b = 2 - 1; +
            let c = 2 * 2; +
            let d = 4 / 2; +
            let e = 5 % 2; +             +
            + val x = 1 +
            val y = 2.0 +
              +
            val a = 1 + 1 +
            val b = 2 - 1 +
            val c = 2 * 2 +
            val d = 4 / 2 +
            val e = 5 % 2 +             +
            + +### 自增和自减： + + + + + + + + + + +
            + i++; +
            i += 1; +
            +
            i--; +
            i -= 1;             +
            + i += 1; +
            i -= 1;             +
            + +或许最大的区别在于像`+`和`-`这样的“操作符”在Scala中实际上是_方法_，而不是操作符。 +Scala 数字也有这些相关的方法： + +```scala +var a = 2 +a *= 2 // 4 +a /= 2 // 2 +``` + +Scala 的 `Double` 类型最接近于 JavaScript 的默认 `number` 类型， +`Int` 表示有符号的 32 位整数值，而 `BigInt` 对应于 JavaScript 的 `bigint`。 + +这些是 Scala `Int` 和 `Double` 值。 +请注意，类型不必显式声明： + +```scala +val i = 1 // Int +val d = 1.1 // Double +``` + +你可以按需要使用其它数字类型： + +```scala +val a: Byte = 0 // Byte = 0 +val a: Double = 0 // Double = 0.0 +val a: Float = 0 // Float = 0.0 +val a: Int = 0 // Int = 0 +val a: Long = 0 // Long = 0 +val a: Short = 0 // Short = 0 + +val x = BigInt(1_234_456_789) +val y = BigDecimal(1_234_456.890) +``` + +### 布尔值 + +两个语言都在布尔值中用 `true` 和 `false`。 + + + + + + + + + + +
            + let a = true; +
            let b = false;             +
            + val a = true +
            val b = false             +
            + +## 日期 + +日期是两种语言中另一种常用的类型。 + +### 获取当前日期： + + + + + + + + + + +
            + let d = new Date();
            +
            // result: +
            // Sun Nov 29 2020 18:47:57 GMT-0700 (Mountain Standard Time) +             +
            + // different ways to get the current date and time +
            import java.time.* +
            +
            val a = LocalDate.now +
                // 2020-11-29 +
            val b = LocalTime.now +
                // 18:46:38.563737 +
            val c = LocalDateTime.now +
                // 2020-11-29T18:46:38.563750 +
            val d = Instant.now +
                // 2020-11-30T01:46:38.563759Z             +
            + +### 指定不同的日期： + + + + + + + + + + +
            + let d = Date(2020, 1, 21, 1, 0, 0, 0); +
            let d = Date(2020, 1, 21, 1, 0, 0); +
            let d = Date(2020, 1, 21, 1, 0); +
            let d = Date(2020, 1, 21, 1); +
            let d = Date(2020, 1, 21);             +
            + val d = LocalDate.of(2020, 1, 21) +
            val d = LocalDate.of(2020, Month.JANUARY, 21) +
            val d = LocalDate.of(2020, 1, 1).plusDays(20) +             +
            + +在这种情况下，Scala 使用 Java 附带的日期和时间类。 +JavaScript 和 Scala 之间的许多日期/时间方法是相似的。 +有关详细信息，请参阅 [_java.time_ 包](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/package-summary.html)。 + +## 函数 + +在 JavaScript 和 Scala 中，函数都是对象，因此它们的功能相似，但它们的语法和术语略有不同。 + +### 命名函数，一行： + + + + + + + + + + +
            + function add(a, b) { +
              return a + b; +
            } +
            add(2, 2);   // 4             +
            + // technically this is a method, not a function +
            def add(a: Int, b: Int) = a + b +
            add(2, 2)   // 4             +
            + +### 命名函数，多行： + + + + + + + + + + +
            + function addAndDouble(a, b) { +
              // imagine this requires +
              // multiple lines +
              return (a + b) * 2 +
            }             +
            + def addAndDouble(a: Int, b: Int): Int = +
              // imagine this requires +
              // multiple lines +
              (a + b) * 2             +
            + +在 Scala 中，显示 `Int` 返回类型是可选的。 +它_不_显示在 `add` 示例中，而_是_显示在 `addAndDouble` 示例中，因此您可以看到这两种方法。 + +## 匿名函数 + +JavaScript 和 Scala 都允许您定义匿名函数，您可以将其传递给其他函数和方法。 + +### 箭头和匿名函数 + + + + + + + + + + +
            + // arrow function +
            let log = (s) => console.log(s) +
            +
            // anonymous function +
            let log = function(s) { +
              console.log(s); +
            } +
            +
            // use either of those functions here +
            function printA(a, log) { +
              log(a); +
            }             +
            + // a function (an anonymous function assigned to a variable) +
            val log = (s: String) => console.log(s) +
            +
            // a scala method. methods tend to be used much more often, +
            // probably because they’re easier to read. +
            def log(a: Any) = console.log(a) +
            +
            // a function or a method can be passed into another +
            // function or method +
            def printA(a: Any, f: log: Any => Unit) = log(a) +             +
            + +在 Scala 中，您很少使用所示的第一种语法来定义函数。 +相反，您经常在使用点定义匿名函数。 +许多集合方法是 [高阶函数][hofs]并接受函数参数，因此您编写如下代码： + +```scala +// map method, long form +List(1,2,3).map(i => i * 10) // List(10,20,30) + +// map, short form (which is more commonly used) +List(1,2,3).map(_ * 10) // List(10,20,30) + +// filter, short form +List(1,2,3).filter(_ < 3) // List(1,2) + +// filter and then map +List(1,2,3,4,5).filter(_ < 3).map(_ * 10) // List(10, 20) +``` + +## 类 + +Scala 既有类也有样例类。 +_类_ 与 JavaScript 类相似，通常用于 [OOP 风格应用程序][modeling-oop]（尽管它们也可以在 FP 代码中使用），并且 _样例类_有附加的特性，这让它在 [FP 风格应用][modeling-fp]中很有用。 + +下面的例子展示了如何创建几个类型作为枚举，然后定义一个 OOP 风格的 `Pizza` 类。 +最后，创建并使用了一个 `Pizza` 实例： + +```scala +// create some enumerations that the Pizza class will use +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions + +// import those enumerations and the ArrayBuffer, +// so the Pizza class can use them +import CrustSize.* +import CrustType.* +import Topping.* +import scala.collection.mutable.ArrayBuffer + +// define an OOP style Pizza class +class Pizza( + var crustSize: CrustSize, + var crustType: CrustType +): + + private val toppings = ArrayBuffer[Topping]() + + def addTopping(t: Topping): Unit = + toppings += t + + def removeTopping(t: Topping): Unit = + toppings -= t + + def removeAllToppings(): Unit = + toppings.clear() + + override def toString(): String = + s""" + |Pizza: + | Crust Size: ${crustSize} + | Crust Type: ${crustType} + | Toppings: ${toppings} + """.stripMargin + +end Pizza + +// create a Pizza instance +val p = Pizza(Small, Thin) + +// change the crust +p.crustSize = Large +p.crustType = Thick + +// add and remove toppings +p.addTopping(Cheese) +p.addTopping(Pepperoni) +p.addTopping(BlackOlives) +p.removeTopping(Pepperoni) + +// print the pizza, which uses its `toString` method +println(p) +``` + +## 接口、trait 和继承 + +Scala 使用 trait 作为接口，也可以创建混搭。 +trait 可以有抽象和具体的成员，包括方法和字段。 + +这个例子展示了如何定义两个 traits，创建一个扩展和实现这些 traits 的类，然后创建和使用该类的一个实例： + +```scala +trait HasLegs: + def numLegs: Int + def walk(): Unit + def stop() = println("Stopped walking") + +trait HasTail: + def wagTail(): Unit + def stopTail(): Unit + +class Dog(var name: String) extends HasLegs, HasTail: + val numLegs = 4 + def walk() = println("I’m walking") + def wagTail() = println("⎞⎜⎛ ⎞⎜⎛") + def stopTail() = println("Tail is stopped") + override def toString = s"$name is a Dog" + +// create a Dog instance +val d = Dog("Rover") + +// use the class’s attributes and behaviors +println(d.numLegs) // 4 +d.wagTail() // "⎞⎜⎛ ⎞⎜⎛" +d.walk() // "I’m walking" +``` + +## 控制结构 + +除了在 JavaScript 中使用 `===` 和 `!==` 之外，比较和逻辑运算符在 JavaScript 和 Scala 中几乎相同。 + +{% comment %} +TODO: Sébastien mentioned that `===` is closest to `eql` in Scala. Update this area. +{% endcomment %} + +### 比较运算符 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
            JavaScriptScala
            + == + ==
            + === + ==
            + != + !=
            + !== + !=
            + > + >
            + < + <
            + >= + >=
            + <= + <=
            + +### 逻辑运算符 + + + + + + + + + + + + +
            JavaScriptScala
            + && +
            || +
            !             +             		+ && +
            || +
            !             +
            + +## if/then/else 表达式 + +JavaScript和 Scala if/then/else 语句相似。 +在 Scala 2 中它们几乎相同，但在 Scala 3 中，花括号不再是必需的（尽管它们仍然可以使用）。 + +### `if` 语句，单行： + + + + + + + + + + +
            + if (x == 1) { console.log(1); } +
            + if x == 1 then println(x) +
            + +### `if` 语句，多行： + + + + + + + + + + +
            + if (x == 1) { +
              console.log("x is 1, as you can see:") +
              console.log(x) +
            }             +
            + if x == 1 then +
              println("x is 1, as you can see:") +
              println(x)             +
            + +### if, else if, else: + + + + + + + + + + +
            + if (x < 0) { +
              console.log("negative") +
            } else if (x == 0) { +
              console.log("zero") +
            } else { +
              console.log("positive") +
            }             +
            + if x < 0 then +
              println("negative") +
            else if x == 0 +
              println("zero") +
            else +
              println("positive")             +
            + +### 从 `if` 返回值： + +JavaScript 使用三元运算符，Scala 像往常一样使用它的 `if` 表达式： + + + + + + + + + + +
            + let minVal = a < b ? a : b; +
            + val minValue = if a < b then a else b +
            + +### `if` 作为方法体： + +Scala 方法往往很短，您可以轻松地使用 `if` 作为方法体： + + + + + + + + + + +
            + function min(a, b) { +
              return (a < b) ? a : b; +
            }             +
            + def min(a: Int, b: Int): Int = +
              if a < b then a else b             +
            + +在 Scala 3 中，如果您愿意，您仍然可以使用“花括号”样式。 +例如，您可以像这样编写 if/else-if/else 表达式： + +```scala +if (i == 0) { + println(0) +} else if (i == 1) { + println(1) +} else { + println("other") +} +``` + +## 循环 + +JavaScript 和 Scala 都有 `while` 循环和 `for` 循环。 +Scala 曾经有 do/while 循环，但它们已从语言中删除。 + +### `while` 循环： + + + + + + + + + + +
            + let i = 0; +
            while (i < 3) { +
              console.log(i); +
              i++; +
            }             +
            + var i = 0; +
            while i < 3 do +
              println(i) +
              i += 1             +
            + +如果你愿意，Scala 代码也可以写成这样： + +```scala +var i = 0 +while (i < 3) { + println(i) + i += 1 +} +``` + +以下示例展示了 JavaScript 和 Scala 中的“for”循环。 +他们假设您可以使用这些集合： + +```scala +// JavaScript +let nums = [1, 2, 3]; + +// Scala +val nums = List(1, 2, 3) +``` + +### `for` 循环，单行： + + + + + + + + + + +
            + // newer syntax +
            for (let i of nums) { +
              console.log(i); +
            } +
            +
            // older +
            for (i=0; i<nums.length; i++) { +
              console.log(nums[i]); +
            }             +
            + // preferred +
            for i <- ints do println(i) +
            +
            // also available +
            for (i <- ints) println(i)             +
            + +### `for` 循环，在循环体内多行 + + + + + + + + + + +
            + // preferred +
            for (let i of nums) { +
              let j = i * 2; +
              console.log(j); +
            } +
            +
            // also available +
            for (i=0; i<nums.length; i++) { +
              let j = nums[i] * 2; +
              console.log(j); +
            }             +
            + // preferred +
            for i <- ints do +
              val i = i * 2 +
              println(j) +
            +
            // also available +
            for (i <- nums) { +
              val j = i * 2 +
              println(j) +
            }             +
            + +### 在 `for` 循环中有多个生成器 + + + + + + + + + + +
            + let str = "ab"; +
            for (let i = 1; i < 3; i++) { +
              for (var j = 0; j < str.length; j++) { +
                for (let k = 1; k < 11; k++) { +
                  let c = str.charAt(j); +
                  console.log(`i: ${i} j: ${c} k: ${k}`); +
                } +
              } +
            }             +
            + for +
              i <- 1 to 2 +
              j <- 'a' to 'b' +
              k <- 1 to 10 by 5 +
            do +
              println(s"i: $i, j: $j, k: $k")             +
            + +### 带守卫的生成器 + +_守卫_是 `for` 表达式中的 `if` 表达式的名称。 + + + + + + + + + + +
            + for (let i = 0; i < 10; i++) { +
              if (i % 2 == 0 && i < 5) { +
                console.log(i); +
              } +
            }             +
            + for +
              i <- 1 to 10 +
              if i % 2 == 0 +
              if i < 5 +
            do +
              println(i)             +
            + +### `for` comprehension + +`for` comprehension 是一个 `for` 循环，它使用 `yield` 返回（产生）一个值。 它们经常在 Scala 中使用。 + + + + + + + + + + +
            + N/A +
            + val list = +
              for +
                i <- 1 to 3 +
              yield +
                i * 10 +
            // result: Vector(10, 20, 30)             +
            + +## switch & match + +JavaScript 有 `switch` 语句，Scala 有 `match` 表达式。 +就像 Scala 中的所有其他东西一样，这些确实是_表达式_，这意味着它们返回一个结果： + +```scala +val day = 1 + +// later in the code ... +val monthAsString = day match + case 1 => "January" + case 2 => "February" + case _ => "Other" +``` + +`match` 表达式可以在每个 `case` 语句中处理多个匹配项： + +```scala +val numAsString = i match + case 1 | 3 | 5 | 7 | 9 => "odd" + case 2 | 4 | 6 | 8 | 10 => "even" + case _ => "too big" +``` + +它们也可以用于方法体： + +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" => false + case _ => true + +def isPerson(x: Matchable): Boolean = x match + case p: Person => true + case _ => false +``` + +`match` 表达式有许多其他模式匹配选项。 + +## 集合类 + +Scala 有不同的 [集合类][collections-classes] 来满足不同的需求。 + +常见的_不可变_序列是： + +- `List` +- `Vector` + +常见的_可变_序列是： + +- `Array` +- `ArrayBuffer` + +Scala 还有可变和不可变的 Map 和 Set。 + +这是创建常见 Scala 集合类型的方式： + +```scala +val strings = List("a", "b", "c") +val strings = Vector("a", "b", "c") +val strings = ArrayBuffer("a", "b", "c") + +val set = Set("a", "b", "a") // result: Set("a", "b") +val map = Map( + "a" -> 1, + "b" -> 2, + "c" -> 3 +) +``` + +### 集合上的方法 + +以下示例展示了使用 Scala 集合的许多不同方法。 + +### 填充列表： + +```scala +// to, until +(1 to 5).toList // List(1, 2, 3, 4, 5) +(1 until 5).toList // List(1, 2, 3, 4) + +(1 to 10 by 2).toList // List(1, 3, 5, 7, 9) +(1 until 10 by 2).toList // List(1, 3, 5, 7, 9) +(1 to 10).by(2).toList // List(1, 3, 5, 7, 9) + +('d' to 'h').toList // List(d, e, f, g, h) +('d' until 'h').toList // List(d, e, f, g) +('a' to 'f').by(2).toList // List(a, c, e) + +// range method +List.range(1, 3) // List(1, 2) +List.range(1, 6, 2) // List(1, 3, 5) + +List.fill(3)("foo") // List(foo, foo, foo) +List.tabulate(3)(n => n * n) // List(0, 1, 4) +List.tabulate(4)(n => n * n) // List(0, 1, 4, 9) +``` + +### 序列上的函数式方法： + +```scala +// these examples use a List, but they’re the same with Vector +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) +a.contains(20) // true +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.filter(_ > 100) // List() +a.find(_ > 20) // Some(30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.last // 10 +a.lastOption // Some(10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +a.takeWhile(_ < 30) // List(10, 20) + +// map, flatMap +val fruits = List("apple", "pear") +fruits.map(_.toUpperCase) // List(APPLE, PEAR) +fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R) + +val nums = List(10, 5, 8, 1, 7) +nums.sorted // List(1, 5, 7, 8, 10) +nums.sortWith(_ < _) // List(1, 5, 7, 8, 10) +nums.sortWith(_ > _) // List(10, 8, 7, 5, 1) + +List(1,2,3).updated(0,10) // List(10, 2, 3) +List(2,4).union(List(1,3)) // List(2, 4, 1, 3) + +// zip +val women = List("Wilma", "Betty") // List(Wilma, Betty) +val men = List("Fred", "Barney") // List(Fred, Barney) +val couples = women.zip(men) // List((Wilma,Fred), (Betty,Barney)) +``` + +Scala 有_很多_更多可供您使用的方法。 +所有这些方法的好处是： + +- 您不必编写自定义的 `for` 循环来解决问题 +- 当你阅读别人的代码时，你不必阅读他们自定义的 `for` 循环； 你只会找到像这样的常用方法，因此更容易阅读来自不同项目的代码 + +### 元组 + +当您想将多个数据类型放在同一个列表中时，JavaScript 允许您这样做： + +```javascript +stuff = ["Joe", 42, 1.0]; +``` + +在 Scala 中你这样做： + +```scala +val a = ("eleven") +val b = ("eleven", 11) +val c = ("eleven", 11, 11.0) +val d = ("eleven", 11, 11.0, Person("Eleven")) +``` + +在 Scala 中，这些类型称为元组，如图所示，它们可以包含一个或多个元素，并且元素可以具有不同的类型。 +访问它们的元素就像访问 `List`、`Vector` 或 `Array` 的元素一样： + +```scala +d(0) // "eleven" +d(1) // 11 +``` + +### 枚举 + +JavaScript 没有枚举，但你可以这样做： + +```javascript +let Color = { + RED: 1, + GREEN: 2, + BLUE: 3 +}; +Object.freeze(Color); +``` + +在 Scala 3 中，您可以使用枚举做很多事情。 +您可以创建该代码的等效代码： + +```scala +enum Color: + case Red, Green, Blue +``` + +你可以创建带参数的枚举： + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` + +你也可以创建用户自定义的枚举成员： + +```scala +enum Planet(mass: Double, radius: Double): + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Venus extends Planet(4.869e+24,6.0518e6) + case Earth extends Planet(5.976e+24,6.37814e6) + // more planets here ... + + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity +``` + +## Scala.js DOM 代码 + +Scala.js 允许您编写 Scala 代码，这些代码编译为 JavaScript 代码，然后可以在浏览器中使用。 +该方法类似于 TypeScript、ReScript 和其他编译为 JavaScript 的语言。 + +包含必要的库并在项目中导入必要的包后，编写 Scala.js 代码看起来与编写 JavaScript 代码非常相似： + +```scala +// show an alert dialog on a button click +jQuery("#hello-button").click{() => + dom.window.alert("Hello, world") +} + +// define a button and what should happen when it’s clicked +val btn = button( + "Click me", + onclick := { () => + dom.window.alert("Hello, world") + }) + +// create two divs with css classes, an h2 element, and the button +val content = + div(cls := "foo", + div(cls := "bar", + h2("Hello"), + btn + ) + ) + +// add the content to the DOM +val root = dom.document.getElementById("root") +root.innerHTML = "" +root.appendChild(content.render) +``` + +请注意，尽管 Scala 是一种类型安全的语言，但在上面的代码中没有声明任何类型。 +Scala 强大的类型推断能力通常使 Scala 代码看起来像是动态类型的。 +但它是类型安全的，因此您可以在开发周期的早期捕获许多类错误。 + +## 其他 Scala.js 资源 + +Scala.js 网站为对使用 Scala.js 感兴趣的 JavaScript 开发人员提供了极好的教程集。 +以下是他们的一些初始教程： + +- [基础教程（创建第一个 Scala.js 项目）](https://www.scala-js.org/doc/tutorial/basic/) +- [适用于 JavaScript 开发人员的 Scala.js](https://www.scala-js.org/doc/sjs-for-js/) +- [从 ES6 到 Scala：基础](https://www.scala-js.org/doc/sjs-for-js/es6-to-scala-part1.html) +- [从 ES6 到 Scala：集合](https://www.scala-js.org/doc/sjs-for-js/es6-to-scala-part2.html) +- [从 ES6 到 Scala：高级](https://www.scala-js.org/doc/sjs-for-js/es6-to-scala-part3.html) + +## Scala 独有的概念 + +Scala 中还有其他一些概念目前在 JavaScript 中没有等效的概念： + +- 几乎所有与[上下文抽象][contextual]相关的东西 +- 方法特性： + - 多个参数列表 + - 调用方法时使用命名参数 +- 使用 trait 作为接口 +- 样例类 +- 伴生类和对象 +- 创建自己的[控制结构][control]和 DSL 的能力 +- `match` 表达式和模式匹配的高级功能 +- `for` comprehension +- 中缀方法 +- 宏和元编程 +- 更多的 ... + + +[collections-classes]: {% link _zh-cn/overviews/scala3-book/collections-classes.md %} +[concurrency]: {% link _zh-cn/overviews/scala3-book/concurrency.md %} +[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %} +[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %} +[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %} +[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %} +[intersection-types]: {% link _zh-cn/overviews/scala3-book/types-intersection.md %} +[modeling-fp]: {% link _zh-cn/overviews/scala3-book/domain-modeling-fp.md %} +[modeling-oop]: {% link _zh-cn/overviews/scala3-book/domain-modeling-oop.md %} +[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} +[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %} + +
            diff --git a/_zh-cn/overviews/scala3-book/scala-for-python-devs.md b/_zh-cn/overviews/scala3-book/scala-for-python-devs.md new file mode 100644 index 0000000000..618f8de44a --- /dev/null +++ b/_zh-cn/overviews/scala3-book/scala-for-python-devs.md @@ -0,0 +1,1361 @@ +--- +title: Scala for Python Developers +type: chapter +description: This page is for Python developers who are interested in learning about Scala 3. +language: zh-cn +num: 75 +previous-page: scala-for-javascript-devs +next-page: where-next + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +{% include_relative scala4x.css %} + +
            + +{% comment %} + +NOTE: Hopefully someone with more Python experience can give this a thorough review. + +NOTE: On this page (https://contributors.scala-lang.org/t/feedback-sought-optional-braces/4702/10), Li Haoyi comments: “Python’s success also speaks for itself; beginners certainly don’t pick Python because of performance, ease of installation, packaging, IDE support, or simplicity of the language’s runtime semantics!” I’m not a Python expert, so these points are good to know, though I don’t want to go negative in any comparisons. +It’s more like thinking, “Python developers will appreciate Scala’s performance, ease of installation, packaging, IDE support, etc.” +{% endcomment %} + +{% comment %} +TODO: We should probably go through this document and add links to our other detail pages, when time permits. +{% endcomment %} + +本节提供了 Python 和 Scala 编程语言之间的比较。 +它适用于懂得 Python 并希望了解 Scala 的程序员，特别是通过查看 Python 语言特性与 Scala 比较的示例。 + +## 介绍 + +在进入示例之前，第一部分提供了以下部分的相对简短的介绍和总结。 +这两种语言首先在高层次上进行比较，然后在日常编程层次上进行比较。 + +### 高层次相似性 + +在高层次上，Scala 与 Python 有这些*相似之处*： + +- 两者都是高级编程语言，您不必关心指针和手动内存管理等低级概念 +- 两者都有一个相对简单、简洁的语法 +- 两者都支持[函数式编程][fp-intro] +- 两者都是面向对象的编程 (OOP) 语言 +- 两者都有推导：Python 有列表推导，Scala 有 `for` 推导 +- 两种语言都支持 lambdas 和 [高阶函数][hofs] +- 两者都可以与 [Apache Spark](https://spark.apache.org) 一起用于大数据处理 +- 两者都有很多很棒的库 + +### 高层次差异 + +同样在高层次上，Python 和 Scala 之间的_差异_是： + +- Python 是动态类型的，Scala 是静态类型的 + - 虽然它是静态类型的，但 Scala 的类型推断等特性让它感觉像是一门动态语言 +- Python 被解释，Scala 代码被编译成 _.class_ 文件，并在 Java 虚拟机 (JVM) 上运行 +- 除了在 JVM 上运行之外，[Scala.js](https://www.scala-js.org) 项目允许您使用 Scala 作为 JavaScript 替代品 +- [Scala Native](https://scala-native.org/) 项目可让您编写“系统”级代码，并编译为本机可执行文件 +- Scala 中的一切都是一个_表达式_：像 `if` 语句、`for` 循环、`match` 表达式，甚至 `try`/`catch` 表达式都有返回值 +- Scala 习惯默认不变性：鼓励您使用不可变变量和不可变集合 +- Scala 对[并发和并行编程][concurrency]有很好的支持 + +### 编程层次相似性 + +本节介绍您在日常编写代码时会看到 Python 和 Scala 之间的相似之处： + +- Scala 的类型推断常常让人感觉像是一种动态类型语言 +- 两种语言都不使用分号来结束表达式 +- 两种语言都支持使用重要的缩进而不是大括号和圆括号 +- 定义方法的语法类似 +- 两者都有列表、字典（映射）、集合和元组 +- 两者都有映射和过滤的推导 +- 使用 Scala 3 的[顶级定义][toplevel]，您可以将方法、字段和其他定义放在任何地方 + - 一个区别是 Python 甚至可以在不声明单个方法的情况下运行，而 Scala 3 不能在顶层做_所有事_；例如，启动 Scala 应用程序需要一个 [main 方法][main-method] (`@main def`) + +### 编程层次差异 + +同样在编程级别，这些是您在编写代码时每天都会看到的一些差异： + +- 在 Scala 中编程感觉非常一致： + - `val` 和 `var` 字段用于定义字段和参数 + - 列表、映射、集合和元组都以类似方式创建和访问；例如，括号用于创建所有类型---`List(1,2,3)`, `Set(1,2,3)`, `Map(1->"one")`---就像创建任何其他 Scala 类 + - [集合类][collections-classes] 通常具有大部分相同的高阶函数 + - 模式匹配在整个语言中一致使用 + - 用于定义传递给方法的函数的语法与用于定义匿名函数的语法相同 +- Scala 变量和参数使用 `val`（不可变）或 `var`（可变）关键字定义 +- Scala 习惯用法更喜欢不可变的数据结构 +- Scala 通过 IntelliJ IDEA 和 Microsoft VS Code 提供了极好的 IDE 支持 +- 注释：Python 使用 `#` 表示注释； Scala 使用 C、C++ 和 Java 样式：`//`、`/*...*/` 和 `/**...*/` +- 命名约定：Python 标准是使用下划线，例如 `my_list`； Scala 使用 `myList` +- Scala 是静态类型的，因此您可以声明方法参数、方法返回值和其他地方的类型 +- 模式匹配和 `match` 表达式在 Scala 中被广泛使用（并且会改变你编写代码的方式） +- Scala 中大量使用 trait；接口和抽象类在 Python 中使用较少 +- Scala 的 [上下文抽象][contextual] 和 _术语推导_提供了一系列不同的特性： + - [扩展方法][extension-method]让您使用清晰的语法轻松地向类添加新功能 + - [多元等式][multiversal] 让您限制相等比较---在编译时——只有那些有意义的比较 +- Scala 拥有最先进的开源函数式编程库（参见 [“Awesome Scala” 列表](https://github.com/lauris/awesome-scala)） +- 借助对象、按名称参数、中缀表示法、可选括号、扩展方法、高阶函数等功能，您可以创建自己的“控制结构”和 DSL +- Scala 代码可以在 JVM 中运行，甚至可以编译为原生代码（使用 [Scala Native](https://github.com/scala-native/scala-native) 和 [GraalVM](https://www.graalvm) .org)) 实现高性能 +- 许多其他好东西：样例类、伴生类和对象、宏、[联合][union-types] 和 [交集][intersection-types] 类型、[顶级定义][toplevel]、数字字面量、多参数列表和更多的 + +### 特性比较示例 + +鉴于该介绍，以下部分提供了 Python 和 Scala 编程语言功能的并排比较。 + +{% comment %} +TODO: Update the Python examples to use four spaces. I started to do this, but then thought it would be better to do that in a separate PR. +{% endcomment %} + +## 注释 + +Python 使用 `#` 表示注释，而 Scala 的注释语法与 C、C++ 和 Java 等语言相同： + + + + + + + + + + +
            + # a comment +
            + // a comment +
            /* ... */ +
            /** ... */             +
            + +## 变量赋值 + +这些例子演示了如何在 Python 和 Scala 中创建变量。 + +### 创建整数和字符串变量： + + + + + + + + + + +
            + x = 1 +
            x = "Hi" +
            y = """foo +
                   bar +
                   baz"""             +
            + val x = 1 +
            val x = "Hi" +
            val y = """foo +
                       bar +
                       baz"""             +
            + +### 列表： + + + + + + + + + + +
            + x = [1,2,3] +
            + val x = List(1,2,3) +
            + +### 字典/映射： + + + + + + + + + + +
            + x = { +
              "Toy Story": 8.3, +
              "Forrest Gump": 8.8, +
              "Cloud Atlas": 7.4 +
            }             +
            + val x = Map( +
              "Toy Story" -> 8.3, +
              "Forrest Gump" -> 8.8, +
              "Cloud Atlas" -> 7.4 +
            )             +
            + +### 集合： + + + + + + + + + + +
            + x = {1,2,3} +
            + val x = Set(1,2,3) +
            + +### 元组： + + + + + + + + + + +
            + x = (11, "Eleven") +
            + val x = (11, "Eleven") +
            + +如果 Scala 字段是可变的，请使用 `var` 而不是 `val` 来定义变量： + +```scala +var x = 1 +x += 1 +``` + +然而，Scala 中的经验法则是始终使用 `val`，除非变量确实需要被改变。 + +## OOP 风格的类和方法 + +本节比较了与 OOP 风格的类和方法相关的特性。 + +### OOP 风格类，主构造函数： + + + + + + + + + + +
            + class Person(object): +
              def __init__(self, name): +
                self.name = name +
            +
              def speak(self): +
                print(f'Hello, my name is {self.name}')             +
            + class Person (var name: String): +
              def speak() = println(s"Hello, my name is $name")             +
            + +### 创建和使用实例： + + + + + + + + + + +
            + p = Person("John") +
            p.name   # John +
            p.name = 'Fred' +
            p.name   # Fred +
            p.speak()             +
            + val p = Person("John") +
            p.name   // John +
            p.name = "Fred" +
            p.name   // Fred +
            p.speak()             +
            + +### 单行方法： + + + + + + + + + + +
            + def add(a, b): return a + b +
            + def add(a: Int, b: Int): Int = a + b +
            + +### 多行方法： + + + + + + + + + + +
            + def walkThenRun(): +
              print('walk') +
              print('run')             +
            + def walkThenRun() = +
              println("walk") +
              println("run")             +
            + +## 接口，traits，和继承 + +如果您熟悉 Java 8 和更新版本，Scala trait 类似于那些 Java 接口。 +Traits 在 Scala 中一直使用，而 Python 接口和抽象类的使用频率要低得多。 +因此，与其试图比较两者，不如用这个例子来展示如何使用 Scala trait来构建一个模拟数学问题的小解决方案： + +```scala +trait Adder: + def add(a: Int, b: Int) = a + b + +trait Multiplier: + def multiply(a: Int, b: Int) = a * b + +// create a class from the traits +class SimpleMath extends Adder, Multiplier +val sm = new SimpleMath +sm.add(1,1) // 2 +sm.multiply(2,2) // 4 +``` + +还有[许多其他方法可以将 trait 与类和对象一起使用][modeling-intro]，但这让您了解如何使用它们将概念组织成行为的逻辑组，然后根据需要将它们合并以创建一个完整的解决方案。 + +## 控制结构 + +本节比较 Python 和 Scala 中的[控制结构][control-structures]。 +两种语言都有类似 `if`/`else`、`while`、`for` 循环和 `try` 的结构。 +Scala 也有 `match` 表达式。 + +### `if` 语句，单行： + + + + + + + + + + +
            + if x == 1: print(x) +
            + if x == 1 then println(x) +
            + +### `if` 语句，多行： + + + + + + + + + + +
            + if x == 1: +
              print("x is 1, as you can see:") +
              print(x)             +
            + if x == 1 then +
              println("x is 1, as you can see:") +
              println(x)             +
            + +### if, else if, else: + + + + + + + + + + +
            + if x < 0: +
              print("negative") +
            elif x == 0: +
              print("zero") +
            else: +
              print("positive")             +
            + if x < 0 then +
              println("negative") +
            else if x == 0 then +
              println("zero") +
            else +
              println("positive")             +
            + +### 从 `if` 返回值： + + + + + + + + + + +
            + min_val = a if a < b else b +
            + val minValue = if a < b then a else b +
            + +### `if` 作为方法体： + + + + + + + + + + +
            + def min(a, b): +
              return a if a < b else b             +
            + def min(a: Int, b: Int): Int = +
              if a < b then a else b             +
            + +### `while` 循环： + + + + + + + + + + +
            + i = 1 +
            while i < 3: +
              print(i) +
              i += 1             +
            + var i = 1 +
            while i < 3 do +
              println(i) +
              i += 1             +
            + +### 有范围的 `for` 循环： + + + + + + + + + + +
            + for i in range(0,3): +
              print(i)             +
            + // preferred +
            for i <- 0 until 3 do println(i) +
            +
            // also available +
            for (i <- 0 until 3) println(i) +
            +
            // multiline syntax +
            for +
              i <- 0 until 3 +
            do +
              println(i)             +
            + +### 列表的 `for` 循环： + + + + + + + + + + +
            + for i in ints: print(i) +
            +
            for i in ints: +
              print(i)             +
            + for i <- ints do println(i) +
            + +### `for` 循环，多行： + + + + + + + + + + +
            + for i in ints: +
              x = i * 2 +
              print(f"i = {i}, x = {x}")             +
            + for +
              i <- ints +
            do +
              val x = i * 2 +
              println(s"i = $i, x = $x")             +
            + +### 多“范围”生成器： + + + + + + + + + + +
            + for i in range(1,3): +
              for j in range(4,6): +
                for k in range(1,10,3): +
                  print(f"i = {i}, j = {j}, k = {k}")             +
            + for +
              i <- 1 to 2 +
              j <- 4 to 5 +
              k <- 1 until 10 by 3 +
            do +
              println(s"i = $i, j = $j, k = $k")             +
            + +### 带守卫（`if` 表达式）的生成器： + + + + + + + + + + +
            + for i in range(1,11): +
              if i % 2 == 0: +
                if i < 5: +
                  print(i)             +
            + for +
              i <- 1 to 10 +
              if i % 2 == 0 +
              if i < 5 +
            do +
              println(i)             +
            + +### 每行有多个 `if` 条件： + + + + + + + + + + +
            + for i in range(1,11): +
              if i % 2 == 0 and i < 5: +
                print(i)             +
            + for +
              i <- 1 to 10 +
              if i % 2 == 0 && i < 5 +
            do +
              println(i)             +
            + +### 推导： + + + + + + + + + + +
            + xs = [i * 10 for i in range(1, 4)] +
            # xs: [10,20,30]             +
            + val xs = for i <- 1 to 3 yield i * 10 +
            // xs: Vector(10, 20, 30)             +
            + +### `match` 表达式： + + + + + + + + + + +
            + # From 3.10, Python supports structural pattern matching +
            # You can also use dictionaries for basic “switch” functionality +
            match month: +
              case 1: +
                monthAsString = "January" +
              case 2: +
                monthAsString = "February" +
              case _: +
                monthAsString = "Other"             +
            + val monthAsString = month match +
              case 1 => "January" +
              case 2 => "February" +
              _ => "Other"             +
            + +### switch/match: + + + + + + + + + + +
            + # Only from Python 3.10 +
            match i: +
              case 1 | 3 | 5 | 7 | 9: +
                numAsString = "odd" +
              case 2 | 4 | 6 | 8 | 10: +
                numAsString = "even" +
              case _: +
                numAsString = "too big"             +
            + val numAsString = i match +
              case 1 | 3 | 5 | 7 | 9 => "odd" +
              case 2 | 4 | 6 | 8 | 10 => "even" +
              case _ => "too big"             +
            + +### try, catch, finally: + + + + + + + + + + +
            + try: +
              print(a) +
            except NameError: +
              print("NameError") +
            except: +
              print("Other") +
            finally: +
              print("Finally")             +
            + try +
              writeTextToFile(text) +
            catch +
              case ioe: IOException => +
                println(ioe.getMessage) +
              case fnf: FileNotFoundException => +
                println(fnf.getMessage) +
            finally +
              println("Finally")             +
            + +匹配表达式和模式匹配是 Scala 编程体验的重要组成部分，但这里只展示了几个 `match` 表达式功能。 有关更多示例，请参见 [控制结构][control-structures] 页面。 + +## 集合类 + +本节比较 Python 和 Scala 中可用的 [集合类][collections-classes]，包括列表、字典/映射、集合和元组。 + +### 列表 + +Python 有它的列表，Scala 有几个不同的专门的可变和不可变序列类，具体取决于您的需要。 +因为 Python 列表是可变的，所以它最直接地与 Scala 的 `ArrayBuffer` 进行比较。 + +### Python 列表 & Scala序列： +Match expressions and pattern matching are a big part of the Scala programming experience, but only a few `match` expression features are shown here. See the [Control Structures][control-structures] page for many more examples. + +## Collections classes + +This section compares the [collections classes][collections-classes] that are available in Python and Scala, including lists, dictionaries/maps, sets, and tuples. + +### Lists + +Where Python has its list, Scala has several different specialized mutable and immutable sequence classes, depending on your needs. +Because the Python list is mutable, it most directly compares to Scala’s `ArrayBuffer`. + +### Python list & Scala sequences: + + + + + + + + + + +
            + a = [1,2,3] +
            + // use different sequence classes +
            // as needed +
            val a = List(1,2,3) +
            val a = Vector(1,2,3) +
            val a = ArrayBuffer(1,2,3)             +
            + +### 获取列表元素： + + + + + + + + + +
            + a[0]
            a[1]             +
            + a(0)
            a(1)             // just like all other method calls +
            + +### 更新列表元素： + + + + + + + + + + +
            + a[0] = 10 +
            a[1] = 20             +
            + // ArrayBuffer is mutable +
            a(0) = 10 +
            a(1) = 20             +
            + +### 合并两个列表： + + + + + + + + + + +
            + c = a + b +
            + val c = a ++ b +
            + +### 遍历列表： + + + + + + + + + + +
            + for i in ints: print(i) +
            +
            for i in ints: +
              print(i)             +
            + // preferred +
            for i <- ints do println(i) +
            +
            // also available +
            for (i <- ints) println(i)             +
            + +Scala 的主要序列类是 `List`、`Vector` 和 `ArrayBuffer`。 +`List` 和 `Vector` 是当你想要一个不可变序列时使用的主要类，而 `ArrayBuffer` 是当你想要一个可变序列时使用的主要类。 +（Scala 中的“缓冲区”是一个可以增长和缩小的序列。） + +### 字典/映射 + +Python 字典就像_可变的_ Scala `Map` 类。 +但是，默认的 Scala 映射是_不可变的_，并且有许多转换方法可以让您轻松创建新映射。 + +#### 字典/映射 创建： + + + + + + + + + + +
            + my_dict = { +
              'a': 1, +
              'b': 2, +
              'c': 3 +
            }             +
            + val myMap = Map( +
              "a" -> 1, +
              "b" -> 2, +
              "c" -> 3 +
            )             +
            + +#### 获取字典/映射元素： + + + + + + + + + + +
            + my_dict['a']   # 1 +
            + myMap("a")   // 1 +
            + +#### 带 `for` 循环的字典/映射： + + + + + + + + + + +
            + for key, value in my_dict.items(): +
              print(key) +
              print(value)             +
            + for (key,value) <- myMap do +
              println(key) +
              println(value)             +
            + +Scala 有其他专门的 `Map` 类来满足不同的需求。 + +### 集合 + +Python 集合类似于_可变的_ Scala `Set` 类。 + +#### 集合创建： + + + + + + + + + + +
            + set = {"a", "b", "c"} +
            + val set = Set(1,2,3) +
            + +#### 重复元素： + + + + + + + + + + +
            + set = {1,2,1} +
            # set: {1,2}             +
            + val set = Set(1,2,1) +
            // set: Set(1,2)             +
            + +Scala 有其他专门的 `Set` 类来满足不同的需求。 + +### 元组 + +Python 和 Scala 元组也很相似。 + +#### 元组创建： + + + + + + + + + + +
            + t = (11, 11.0, "Eleven") +
            + val t = (11, 11.0, "Eleven") +
            + +#### 获取元组元素： + + + + + + + + + + +
            + t[0]   # 11 +
            t[1]   # 11.0             +
            + t(0)   // 11 +
            t(1)   // 11.0             +
            + +## 集合类上的方法 + +Python 和 Scala 有几个相同的常用函数方法可供它们使用： + +- `map` +- `filter` +- `reduce` + +如果您习惯于在 Python 中将这些方法与 lambda 表达式一起使用，您会发现 Scala 在其集合类中使用了类似的方法。 +为了演示此功能，这里有两个示例列表： + +```scala +numbers = (1,2,3) // python +val numbers = List(1,2,3) // scala +``` + +下表中使用了这些列表，显示了如何对其应用映射和过滤算法。 + +### 映射与推导： + + + + + + + + + + +
            + x = [i * 10 for i in numbers] +
            + val x = for i <- numbers yield i * 10 +
            + +### 有推导的过滤： + + + + + + + + + + +
            + evens = [i for i in numbers if i % 2 == 0] +
            + val evens = numbers.filter(_ % 2 == 0) +
            // or +
            val evens = for i <- numbers if i % 2 == 0 yield i             +
            + +### 映射 & 有推导的过滤： + + + + + + + + + + +
            + x = [i * 10 for i in numbers if i % 2 == 0] +
            + val x = numbers.filter(_ % 2 == 0).map(_ * 10) +
            // or +
            val x = for i <- numbers if i % 2 == 0 yield i * 10             +
            + +### 映射： + + + + + + + + + + +
            + x = map(lambda x: x * 10, numbers) +
            + val x = numbers.map(_ * 10) +
            + +### 过滤： + + + + + + + + + + +
            + f = lambda x: x > 1 +
            x = filter(f, numbers)             +
            + val x = numbers.filter(_ > 1) +
            + + +### Scala 集合方法： + +Scala 集合类有超过 100 种功能方法来简化您的代码。 +除了 `map`、`filter` 和 `reduce`，下面列出了其他常用的方法。 +在这些方法示例中： + +- `c` 指的是一个集合 +- `p` 是谓词 +- `f` 是一个函数、匿名函数或方法 +- `n` 指的是一个整数值 + +以下是一些可用的过滤方法： + +| 方法 | 说明 | +| -------------- | ------------- | +| `c1.diff(c2) ` | 返回 `c1` 和 `c2` 中元素的差异。 | +| `c.distinct` | 返回 `c` 中的唯一元素。 | +| `c.drop(n)` | 返回集合中除前 `n` 个元素之外的所有元素。 | +| `c.filter(p) ` | 返回集合中谓词为 `true` 的所有元素。 | +| `c.head` | 返回集合的第一个元素。 （如果集合为空，则抛出 `NoSuchElementException`。） | +| `c.tail` | 返回集合中除第一个元素之外的所有元素。 （如果集合为空，则抛出 `UnsupportedOperationException`。） | +| `c.take(n)` | 返回集合 `c` 的前 `n` 个元素。 | + +以下是一些转换方法： + +| 方法 | 说明 | +| --------------- | ------------- | +| `c.flatten` | 将集合的集合（例如列表列表）转换为单个集合（单个列表）。 | +| `c.flatMap(f)` | 通过将 `f` 应用于集合 `c` 的所有元素（如 `map`）返回一个新集合，然后将结果集合的元素展平。 | +| `c.map(f)` | 通过将 `f` 应用于集合 `c` 的所有元素来创建一个新集合。 | +| `c.reduce(f)` | 将 `reduction` 函数 `f` 应用于 `c` 中的连续元素以产生单个值。 | +| `c.sortWith(f)` | 返回由比较函数 `f` 排序的 `c` 版本。 | + +一些常见的分组方法： + +| 方法 | 说明 | +| ---------------- | ------------- | +| `c.groupBy(f)` | 根据 `f` 将集合划分为集合的 `Map`。 | +| `c.partition(p)` | 根据谓词 `p` 返回两个集合。 | +| `c.span(p)` | 返回两个集合的集合，第一个由 `c.takeWhile(p)` 创建，第二个由 `c.dropWhile(p)` 创建。 | +| `c.splitAt(n)` | 通过在元素 `n` 处拆分集合 `c` 来返回两个集合的集合。 | + +一些信息和数学方法： + +| 方法 | 说明 | +| -------------- | ------------- | +| `c1.containsSlice(c2)` | 如果 `c1` 包含序列 `c2`，则返回 `true`。 | +| `c.count(p)` | 计算 `c` 中元素的数量，其中 `p` 为 `true`。 | +| `c.distinct` | 返回 `c` 中的不重复的元素。 | +| `c.exists(p)` | 如果集合中任何元素的 `p` 为 `true` ，则返回 `true` 。 | +| `c.find(p)` | 返回匹配 `p` 的第一个元素。该元素以 `Option[A]` 的形式返回。 | +| `c.min` | 返回集合中的最小元素。 （可以抛出_java.lang.UnsupportedOperationException_。）| +| `c.max` | 返回集合中的最大元素。 （可以抛出_java.lang.UnsupportedOperationException_。）| +| `c slice(from, to)` | 返回从元素 `from` 开始到元素 `to` 结束的元素间隔。 | +| `c.sum` | 返回集合中所有元素的总和。 （需要为集合中的元素定义 `Ordering`。） | + +以下是一些示例，展示了这些方法如何在列表上工作： + +```scala +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.filter(_ > 100) // List() +a.find(_ > 20) // Some(30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.intersect(List(19,20,21)) // List(20) +a.last // 10 +a.lastOption // Some(10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +a.takeWhile(_ < 30) // List(10, 20) +``` + +这些方法展示了 Scala 中的一个常见模式：对象上可用的函数式方法。 +这些方法都不会改变初始列表“a”； 相反，它们都返回的数据在注释后显示。 + +还有更多可用的方法，但希望这些描述和示例能让您体验到预建集合方法的强大功能。 + +## 枚举 + +本节比较 Python 和 Scala 3 中的枚举。 + +### 创建枚举： + + + + + + + + + + +
            + from enum import Enum, auto +
            class Color(Enum): +
                RED = auto() +
                GREEN = auto() +
                BLUE = auto()             +
            + enum Color: +
              case Red, Green, Blue             +
            + +### 值和比较： + + + + + + + + + + +
            + Color.RED == Color.BLUE  # False +
            + Color.Red == Color.Blue  // false +
            + +### 参数化枚举： + + + + + + + + + + +
            + N/A +
            + enum Color(val rgb: Int): +
              case Red   extends Color(0xFF0000) +
              case Green extends Color(0x00FF00) +
              case Blue  extends Color(0x0000FF)             +
            + +### 用户定义枚举成员： + + + + + + + + + + +
            + N/A +
            + enum Planet( +
                mass: Double, +
                radius: Double +
              ): +
              case Mercury extends +
                Planet(3.303e+23, 2.4397e6) +
              case Venus extends +
                Planet(4.869e+24, 6.0518e6) +
              case Earth extends +
                Planet(5.976e+24, 6.37814e6) +
              // more planets ... +
            +
              // fields and methods +
              private final val G = 6.67300E-11 +
              def surfaceGravity = G * mass / +
                (radius * radius) +
              def surfaceWeight(otherMass: Double) +
                = otherMass * surfaceGravity             +
            + +## Scala 独有的概念 + +Scala 中的有些概念目前在 Python 中没有等效的功能。 +请点击以下链接了解更多详情： + + + +- 大多数与[上下文抽象][contextual]相关的概念，如[扩展方法][extension-methods]、类型类、隐式值 +- Scala 允许多参数列表，从而实现部分应用函数等特性，以及创建自己的 DSL 的能力 +- 样例类，对于函数式编程和模式匹配非常有用 +- 创建自己的控制结构和 DSL 的能力 +- 模式匹配和 `match` 表达式 +- [多重等式][multiversal]：在编译时控制哪些等式比较有意义的能力 +- 中缀方法 +- 宏和元编程 + +## Scala 和虚拟环境 + +在 Scala 中，无需显式设置 Python 虚拟环境的等价物。默认情况下，Scala 构建工具管理项目依赖项，因此用户不必考虑手动安装包。例如，使用 `sbt` 构建工具，我们在 `libraryDependencies` 设置下的 `build.sbt` 文件中指定依赖关系，然后执行 + +``` +cd myapp +sbt compile +``` + +自动解析该特定项目的所有依赖项。 下载依赖的位置很大程度上是构建工具的一个实现细节，用户不必直接与这些下载的依赖交互。 例如，如果我们删除整个 sbt 依赖项缓存，则在项目的下一次编译时，sbt 会自动重新解析并再次下载所有必需的依赖项。 + +这与 Python 不同，默认情况下，依赖项安装在系统范围或用户范围的目录中，因此要在每个项目的基础上获得隔离环境，必须创建相应的虚拟环境。 例如，使用 `venv` 模块，我们可以像这样为特定项目创建一个 + +``` +cd myapp +python3 -m venv myapp-env +source myapp-env/bin/activate +pip install -r requirements.txt +``` + +这会在项目的 `myapp/myapp-env` 目录下安装所有依赖项，并更改 shell 环境变量 `PATH` 以从 `myapp-env` 查找依赖项。 +在 Scala 中，这些手动过程都不是必需的。 + + +[collections-classes]: {% link _zh-cn/overviews/scala3-book/collections-classes.md %} +[concurrency]: {% link _zh-cn/overviews/scala3-book/concurrency.md %} +[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[control-structures]: {% link _zh-cn/overviews/scala3-book/control-structures.md %} +[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %} +[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %} +[intersection-types]: {% link _zh-cn/overviews/scala3-book/types-intersection.md %} +[main-method]: {% link _zh-cn/overviews/scala3-book/methods-main-methods.md %} +[modeling-intro]: {% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %} +[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} +[toplevel]: {% link _zh-cn/overviews/scala3-book/taste-toplevel-definitions.md %} +[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %} +
            diff --git a/_zh-cn/overviews/scala3-book/scala-tools.md b/_zh-cn/overviews/scala3-book/scala-tools.md new file mode 100644 index 0000000000..822c3d428a --- /dev/null +++ b/_zh-cn/overviews/scala3-book/scala-tools.md @@ -0,0 +1,20 @@ +--- +title: Scala 工具 +type: chapter +description: This chapter looks at two commonly-used Scala tools, sbt and ScalaTest. +language: zh-cn +num: 69 +previous-page: concurrency +next-page: tools-sbt + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍编写和运行 Scala 程序的两种方法： + +- 通过创建Scala项目，可能包含多个文件，并定义一个程序入口点， +- 通过与练习册交互，练习册是在单个文件中定义的程序，逐行执行。 diff --git a/_zh-cn/overviews/scala3-book/scala4x.css b/_zh-cn/overviews/scala3-book/scala4x.css new file mode 100644 index 0000000000..c7d34705bb --- /dev/null +++ b/_zh-cn/overviews/scala3-book/scala4x.css @@ -0,0 +1,59 @@ + + + diff --git a/_zh-cn/overviews/scala3-book/string-interpolation.md b/_zh-cn/overviews/scala3-book/string-interpolation.md new file mode 100644 index 0000000000..372eccc5e0 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/string-interpolation.md @@ -0,0 +1,356 @@ +--- +title: 字符串插值 +type: chapter +description: This page provides more information about creating strings and using 字符串插值. +language: zh-cn +num: 18 +previous-page: first-look-at-types +next-page: control-structures +redirect_from: + - /zh-cn/overviews/core/string-interpolation.html + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +## 介绍 + +字符串插值提供了一种在字符串中使用变量的方法。 +比如： + +{% tabs example-1 %} +{% tab 'Scala 2 and 3' for=example-1 %} +```scala +val name = "James" +val age = 30 +println(s"$name is $age years old") // "James is 30 years old" +``` +{% endtab %} +{% endtabs %} + +字符串插值由在字符串引号前面的 `s` 和任何有前缀 `$` 的变量组成。 + +### 其它插值 + +把 `s` 放在字符串前，只是 Scala 提供的插值的一种可能。 + +Scala 内置三种字符串插值方法： `s`, `f` 和 `raw`. +进一步，字符串插值器只是一种特殊的方法，所以你也可以定义自己的插值器。例如， +有些数据库的函数库定义了 `sql` 插值器，这个插值器可以返回数据库查询。 + +## `s` 插值器 (`s`-字符串) + +在任何字符串字面量加上 `s` 前缀，就可以让你在字符串中直接使用变量。你已经在这里见过这个例子： + +{% tabs example-2 %} +{% tab 'Scala 2 and 3' for=example-2 %} +```scala +val name = "James" +val age = 30 +println(s"$name is $age years old") // "James is 30 years old" +``` +{% endtab %} +{% endtabs %} + +这里字符串中的 `$name` 和 `$age` 占位符相应地被调用 `name.toString` 和 `age.toString` 的结果所替换。 +`s`-字符串可以获取当前作用域的所有变量。 + +虽然这看着很明显，但它很重要，需要在这指出来，字符串插值在普通字符串字面量中_不_起作用： + +{% tabs example-3 %} +{% tab 'Scala 2 and 3' for=example-3 %} +```scala +val name = "James" +val age = 30 +println("$name is $age years old") // "$name is $age years old" +``` +{% endtab %} +{% endtabs %} + +字符串插值器可以使用任何表达式。例如： + +{% tabs example-4 %} +{% tab 'Scala 2 and 3' for=example-4 %} +```scala +println(s"2 + 2 = ${2 + 2}") // "2 + 2 = 4" +val x = -1 +println(s"x.abs = ${x.abs}") // "x.abs = 1" +``` +{% endtab %} +{% endtabs %} + +任何表达式可以嵌入 `${}` 中. + +有些特殊字符在嵌入到字符串内时需要转义。 +当需要显示真实的美元符号时，你可以把美元符号双写 `$$`, 像这样： + +{% tabs example-5 %} +{% tab 'Scala 2 and 3' for=example-5 %} +```scala +println(s"New offers starting at $$14.99") // "New offers starting at $14.99" +``` +{% endtab %} +{% endtabs %} + +双引号一样需要转义。这个可以使用三引号来达到，如下： + +{% tabs example-6 %} +{% tab 'Scala 2 and 3' for=example-6 %} +```scala +println(s"""{"name":"James"}""") // `{"name":"James"}` +``` +{% endtab %} +{% endtabs %} + +最后，可以在所有多行字符串内插值 + +{% tabs example-7 %} +{% tab 'Scala 2 and 3' for=example-7 %} +```scala +println(s"""name: "$name", + |age: $age""".stripMargin) +``` + +This will print as follows: + +``` +name: "James" +age: 30 +``` +{% endtab %} +{% endtabs %} + +## `f` 插值器 (`f`-字符串) + +在任何字符串字面量加上 `f` 前缀，允许你创建简单的格式化字符串，像其它语言中的 `printf`。当使用 `f` 插值器时， +所有变量的引用应该遵循 `printf` 风格的格式化字符串，像 `%d`。让我们看以下例子： + +{% tabs example-8 %} +{% tab 'Scala 2 and 3' for=example-8 %} +```scala +val height = 1.9d +val name = "James" +println(f"$name%s is $height%2.2f meters tall") // "James is 1.90 meters tall" +``` +{% endtab %} +{% endtabs %} + +`f` 插值器是类型安全的。如果你尝试把一个双精度数传递给一个只能处理整数的格式化字符串，编译器会发出一个错误信息。 +例如： + +{% tabs f-interpolator-error class=tabs-scala-version %} + +{% tab 'Scala 2' for=f-interpolator-error %} +```scala +val height: Double = 1.9d + +scala> f"$height%4d" +:9: error: type mismatch; + found : Double + required: Int + f"$height%4d" + ^ +``` +{% endtab %} + +{% tab 'Scala 3' for=f-interpolator-error %} +```scala +val height: Double = 1.9d + +scala> f"$height%4d" +-- Error: ---------------------------------------------------------------------- +1 |f"$height%4d" + | ^^^^^^ + | Found: (height : Double), Required: Int, Long, Byte, Short, BigInt +1 error found + +``` +{% endtab %} +{% endtabs %} + +`f` 插值器使用来自 Java 的字符串格式化工具。格式化允许在 `%` 字符后，在[Formatter javadoc][java-format-docs] 中有说明。 +如果没有 `%` 字符在变量之后，那么 `%s` (`String`) 作为缺省的格式化工具。 + +最后，像在 Java 里，使用 `%%` 来让 `%` 字符出现在输出字符中： + +{% tabs literal-percent %} +{% tab 'Scala 2 and 3' for=literal-percent %} +```scala +println(f"3/19 is less than 20%%") // "3/19 is less than 20%" +``` +{% endtab %} +{% endtabs %} + +### `raw` 插值器 + +raw 插值器 和 `s` 插值器很像，除了它不动字符串内的转义符。这里有一个处理字符串的例子： + +{% tabs example-9 %} +{% tab 'Scala 2 and 3' for=example-9 %} +```scala +scala> s"a\nb" +res0: String = +a +b +``` +{% endtab %} +{% endtabs %} + +这里 `s` 字符串插值器把 `\n` 替换成回车字符。`raw` 插值器不会做那些。 + +{% tabs example-10 %} +{% tab 'Scala 2 and 3' for=example-10 %} +```scala +scala> raw"a\nb" +res1: String = a\nb +``` +{% endtab %} +{% endtabs %} + +当你希望避免像 `\n` 这样的表达式转义成回车符，raw 插值器会有用。 + +除了这三种自带的字符串插值器外，你还可以定义自己的插值器。 + +## 高级用法 + +字面量 `s"Hi $name"` 被 Scala 当成 _过程_ 字符串字面量来进行分析。 +这意味着编译器对这个字面量额外做了一些工作。具体的处理后的字符串 +和字符串插入器可以在 [SIP-11][sip-11] 中找到描述，但这里用一个快速的例子来展示它 +是如何工作的。 + +### 定制插值器 + +在 Scala 中，所有被处理过的字符串字面量都是简单的代码转换。任何时候当编译器遇到 +形式如下，处理过的字符串字面量时： + +{% tabs example-11 %} +{% tab 'Scala 2 and 3' for=example-11 %} +```scala +id"string content" +``` +{% endtab %} +{% endtabs %} + +编译器把这段代码转换成 在 [StringContext](https://www.scala-lang.org/api/current/scala/StringContext.html) 实例之上调用 (`id`) 方法. +该方法也在隐式作用域有效。 +为了定义我们自己的字符串插值器，我们需要创建一个 implicit class (Scala 2) 或者一个 `extension` 方法（Scala 3）方法，这样可以把新方法添加到 `StringContext` 中。 + +作为一个小例子，让我们假定 `Point` 类，并假定我们想创建一个定制化的插值器，它把 `p"a,b"` into a 转换成 `Point` 对象。 + +{% tabs custom-interpolator-1 %} +{% tab 'Scala 2 and 3' for=custom-interpolator-1 %} +```scala +case class Point(x: Double, y: Double) + +val pt = p"1,-2" // Point(1.0,-2.0) +``` +{% endtab %} +{% endtabs %} + +我们首先实现一个如下的 `StringContext` 扩展来创建一个定制的 `p`-插值器： + +{% tabs custom-interpolator-2 class=tabs-scala-version %} + +{% tab 'Scala 2' for=custom-interpolator-2 %} +```scala +implicit class PointHelper(val sc: StringContext) extends AnyVal { + def p(args: Any*): Point = ??? +} +``` + +**注意：** 在 Scala 2.x 中重要的一点是继承自 `AnyVal` ，从而防止运行时对每个插值器进行实例化。 +更多内容见 [值类][value-classes] 文档。 + +{% endtab %} + +{% tab 'Scala 3' for=custom-interpolator-2 %} +```scala +extension (sc: StringContext) + def p(args: Any*): Point = ??? +``` +{% endtab %} + +{% endtabs %} + +一旦这个扩展在作用域，当 Scala 编译器遇到 `p"some string"` 时，它将 +`some string` 中每一个嵌入到字符串中的变量转换为字符串和表达式参数。 + +例如 `p"1, $someVar"` 将转变成： + +{% tabs extension-desugaring class=tabs-scala-version %} + +{% tab 'Scala 2' for=extension-desugaring %} +```scala +new StringContext("1, ", "").p(someVar) +``` + +隐式类将用来重写成以下的样子： + +```scala +new PointHelper(new StringContext("1, ", "")).p(someVar) +``` +{% endtab %} + +{% tab 'Scala 3' for=extension-desugaring %} +```scala +StringContext("1, ","").p(someVar) +``` + +{% endtab %} + +{% endtabs %} + +作为结果，每一个处理过的字符串片段都暴露在 `StringContext.parts` 成员内，而在字符串中的任何 +表达式的值都传递给该方法的 `args` 参数。 + +### 实现的例子 + +我们这个天真的 Point 插值器方法的实现看着像以下的代码， +但是更复杂的方法可能会用更加精确的控制用于处理字符串 `parts` 和 表达式 `args`, +这样可以替代目前重用 `s`-插值器。 + +{% tabs naive-implementation class=tabs-scala-version %} + +{% tab 'Scala 2' for=naive-implementation %} +```scala +implicit class PointHelper(val sc: StringContext) extends AnyVal { + def p(args: Double*): Point = { + // reuse the `s`-interpolator and then split on ',' + val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } + Point(pts(0), pts(1)) + } +} + +val x=12.0 + +p"1, -2" // Point(1.0, -2.0) +p"${x/5}, $x" // Point(2.4, 12.0) +``` +{% endtab %} + +{% tab 'Scala 3' for=naive-implementation %} +```scala +extension (sc: StringContext) + def p(args: Double*): Point = { + // reuse the `s`-interpolator and then split on ',' + val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) } + Point(pts(0), pts(1)) + } + +val x=12.0 + +p"1, -2" // Point(1.0, -2.0) +p"${x/5}, $x" // Point(2.4, 12.0) +``` +{% endtab %} +{% endtabs %} + +虽然字符串插值器刚开始是用来创建某种字符串形式，但使用上面的定制插值器可以有强大的句法简写， +并且社区已经制造了一些语法便捷的用途，如 ANSI 终端颜色扩展，可执行 SQL 查询，神奇的 +`$"identifier"` 表达，还有更多其它的。 + +[java-format-docs]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html#detail +[value-classes]: {% link _overviews/core/value-classes.md %} +[sip-11]: {% link _sips/sips/string-interpolation.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-collections.md b/_zh-cn/overviews/scala3-book/taste-collections.md new file mode 100644 index 0000000000..966872f1a3 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-collections.md @@ -0,0 +1,156 @@ +--- +title: 集合 +type: section +description: This page provides a high-level overview of the main features of the Scala 3 programming language. +language: zh-cn +num: 13 +previous-page: taste-objects +next-page: taste-contextual-abstractions + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 库具有一组丰富的集合类，这些类具有一组丰富的方法。 +集合类有不可变和可变两种形式。 + +## 创建列表 + +为了让您了解这些类的工作原理，下面是一些使用 `List` 类的示例，该类是不可变的链接列表类。 +这些示例显示了创建填充的 `List` 的不同方法： + +{% tabs collection_1 %} +{% tab 'Scala 2 and 3' for=collection_1 %} + +```scala +val a = List(1, 2, 3) // a: List[Int] = List(1, 2, 3) + +// Range methods +val b = (1 to 5).toList // b: List[Int] = List(1, 2, 3, 4, 5) +val c = (1 to 10 by 2).toList // c: List[Int] = List(1, 3, 5, 7, 9) +val e = (1 until 5).toList // e: List[Int] = List(1, 2, 3, 4) +val f = List.range(1, 5) // f: List[Int] = List(1, 2, 3, 4) +val g = List.range(1, 10, 3) // g: List[Int] = List(1, 4, 7) +``` + +{% endtab %} +{% endtabs %} + +## `List`方法 + +拥有填充的列表后，以下示例将显示可以对其调用的一些方法。 +请注意，这些都是函数式方法，这意味着它们不会改变调用的集合，而是返回包含更新元素的新集合。 +每个表达式返回的结果显示在每行的注释中： + +{% tabs collection_2 %} +{% tab 'Scala 2 and 3' for=collection_2 %} + +```scala +// a sample list +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) + +a.drop(2) // List(30, 40, 10) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.slice(2,4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeWhile(_ < 30) // List(10, 20) + +// flatten +val a = List(List(1,2), List(3,4)) +a.flatten // List(1, 2, 3, 4) + +// map, flatMap +val nums = List("one", "two") +nums.map(_.toUpperCase) // List("ONE", "TWO") +nums.flatMap(_.toUpperCase) // List('O', 'N', 'E', 'T', 'W', 'O') +``` + +{% endtab %} +{% endtabs %} + +这些示例显示了如何使用 `foldLeft` 和 `reduceLeft` 方法来对整数序列中的值求和： + +{% tabs collection_3 %} +{% tab 'Scala 2 and 3' for=collection_3 %} + +```scala +val firstTen = (1 to 10).toList // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + +firstTen.reduceLeft(_ + _) // 55 +firstTen.foldLeft(100)(_ + _) // 155 (100 is a “seed” value) +``` + +{% endtab %} +{% endtabs %} + +Scala 集合类还有更多可用的方法，它们在[集合章节][collections]和 [API 文档][api]中进行了演示。 + +## 元组 + +Scala _元组_ 是一种类型，可让您轻松地将不同类型的集合放在同一个容器中。 +例如，给定以下 `Person` 样例类： + +{% tabs collection_4 %} +{% tab 'Scala 2 and 3' for=collection_4 %} + +```scala +case class Person(name: String) +``` + +{% endtab %} +{% endtabs %} + +这是演示你如创建一个元组，这个元组包含 `Int`, `String`, 和定制的 `Person` 值： + +{% tabs collection_5 %} +{% tab 'Scala 2 and 3' for=collection_5 %} + +```scala +val t = (11, "eleven", Person("Eleven")) +``` + +{% endtab %} +{% endtabs %} + +有元组后，可以通过将其值绑定到变量来访问，也可以通过数字访问它们： + +{% tabs collection_6 %} +{% tab 'Scala 2 and 3' for=collection_6 %} + +```scala +t(0) // 11 +t(1) // "eleven" +t(2) // Person("Eleven") +``` + +{% endtab %} +{% endtabs %} + +您还可以使用以下 _解构_ 的办法将元组字段分配变量名： + +{% tabs collection_7 %} +{% tab 'Scala 2 and 3' for=collection_7 %} + +```scala +val (num, str, person) = t + +// result: +// val num: Int = 11 +// val str: String = eleven +// val person: Person = Person(Eleven) +``` + +{% endtab %} +{% endtabs %} + +有些情况更适合使用元组， 那就是当你想要将异构类型的集合放在一个小的类似集合的结构中。 +有关更多元组详细信息，请参阅 [参考文档][reference]。 + +[collections]: {% link _zh-cn/overviews/scala3-book/collections-intro.md %} +[api]: https://scala-lang.org/api/3.x/ +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_zh-cn/overviews/scala3-book/taste-contextual-abstractions.md b/_zh-cn/overviews/scala3-book/taste-contextual-abstractions.md new file mode 100644 index 0000000000..cfa5db2f45 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-contextual-abstractions.md @@ -0,0 +1,77 @@ +--- +title: 上下文抽象 +type: section +description: This section provides an introduction to Contextual Abstractions in Scala 3. +language: zh-cn +num: 14 +previous-page: taste-collections +next-page: taste-toplevel-definitions + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +{% comment %} +TODO: Now that this is a separate section, it needs a little more content. +{% endcomment %} + +在某些情况下，可以省略在方法调用中你认为是重复的的某些参数。 + +这些参数之所以称为 _上下文参数_，是因为它们是由编译器从方法调用周围的上下文中推断出来的。 + +例如，考虑一个程序，该程序按两个条件对地址列表进行排序：城市名称，然后是街道名称。 + +{% tabs contextual_1 %} +{% tab 'Scala 2 and 3' for=contextual_1 %} + +```scala +val addresses: List[Address] = ... + +addresses.sortBy(address => (address.city, address.street)) +``` +{% endtab %} +{% endtabs %} + +`sortBy` 方法调用一个函数，该函数为每个地址返回值，这个值会用来与其他地址比较。 +在本例中，我们传递一个函数，该函数返回一对，该对包含城市名称和街道名称。 + +请注意，我们只指示 _怎么_ 比较的，而不是 _如何_ 来执行比较。 +排序算法如何知道如何比较 `String` 对的？ + +实际上，`sortBy` 方法采用第二个参数---一个上下文参数---该参数由编译器推断。 +它不会出现在上面的示例中，因为它是由编译器提供的。 + +第二个参数实现 _如何_ 进行比较。 +省略它很方便，因为我们知道 `String` 通常使用词典顺序进行比较。 + +但是，也可以显式传递它： + +{% tabs contextual_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=contextual_2 %} + +```scala +addresses.sortBy(address => (address.city, address.street))(Ordering.Tuple2(Ordering.String, Ordering.String)) +``` + +{% endtab %} +{% tab 'Scala 3' for=contextual_2 %} + +```scala +addresses.sortBy(address => (address.city, address.street))(using Ordering.Tuple2(Ordering.String, Ordering.String)) +``` +{% endtab %} +{% endtabs %} + +在本例中，`Ordering.Tuple2(Ordering.String, Ordering.String)` 实例正是编译器以其他方式推断的实例。 +换句话说，这两个示例生成相同的程序。 + +_上下文抽象_ 用于避免重复代码。 +它们帮助开发人员编写可扩展且同时简洁的代码段。 + +有关更多详细信息，请参阅本书的[上下文抽象章节][contextual]，以及[参考文档][reference]。 + +[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_zh-cn/overviews/scala3-book/taste-control-structures.md b/_zh-cn/overviews/scala3-book/taste-control-structures.md new file mode 100644 index 0000000000..a6d0196ee5 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-control-structures.md @@ -0,0 +1,546 @@ +--- +title: 控制结构 +type: section +description: This section demonstrates Scala 3 control structures. +language: zh-cn +num: 8 +previous-page: taste-vars-data-types +next-page: taste-modeling + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 具有您在其他编程语言中可以找到的控制结构，并且还具有强大的 `for` 表达式和 `match` 表达式： + +- `if`/`else` +- `for` 循环和表达式 +- `match` 表达式 +- `while` 循环 +- `try`/`catch` + +这些结构在以下示例中进行了说明。 + +## `if`/`else` + +Scala 的 `if`/`else` 控制结构看起来与其他语言相似： + +{% tabs if-else class=tabs-scala-version %} +{% tab 'Scala 2' for=if-else %} + +```scala +if (x < 0) { + println("negative") +} else if (x == 0) { + println("zero") +} else { + println("positive") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=if-else %} + +```scala +if x < 0 then + println("negative") +else if x == 0 then + println("zero") +else + println("positive") +``` + +{% endtab %} +{% endtabs %} + +请注意，这确实是一个 _表达式_ ---不是一个 _语句_。 +这意味着它返回一个值，因此您可以将结果赋值给一个变量： + +{% tabs if-else-expression class=tabs-scala-version %} +{% tab 'Scala 2' for=if-else-expression %} + +```scala +val x = if (a < b) { a } else { b } +``` + +{% endtab %} + +{% tab 'Scala 3' for=if-else-expression %} + +```scala +val x = if a < b then a else b +``` + +{% endtab %} +{% endtabs %} + +正如您将在本书中看到的那样，_所有_ Scala 控制结构都可以用作表达式。 + +> 表达式返回结果，而语句不返回。 +> 语句通常用于它们的副作用，例如使用 `println` 打印到控制台。 + +## `for` 循环和表达式 + +`for` 关键字用于创建 `for` 循环。 +这个例子展示了如何打印 `List` 中的每个元素： + +{% tabs for-loop class=tabs-scala-version %} +{% tab 'Scala 2' for=for-loop %} + +```scala +val ints = List(1, 2, 3, 4, 5) + +for (i <- ints) println(i) +``` + +> 代码 `i <- ints` 被称为_生成器_，在括号内的生成器后面是_循环体_。 + +{% endtab %} + +{% tab 'Scala 3' for=for-loop %} + + +```scala +val ints = List(1, 2, 3, 4, 5) + +for i <- ints do println(i) +``` + +> 代码 `i <- ints` 被称为 _生成器_，紧随 `do` 关键字的代码是 _循环体_。 + +{% endtab %} +{% endtabs %} + +### 守卫 + +您还可以在 `for` 循环中使用一个或多个 `if` 表达式。 +这些被称为 _守卫_。 +此示例打印 `ints` 中大于 `2` 的所有数字： + +{% tabs for-guards class=tabs-scala-version %} +{% tab 'Scala 2' for=for-guards %} + +```scala +for (i <- ints if i > 2) + println(i) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-guards %} + +```scala +for + i <- ints + if i > 2 +do + println(i) +``` + +{% endtab %} +{% endtabs %} + +您可以使用多个生成器和守卫。 +此循环遍历数字 `1` 到 `3`，并且对于每个数字，它还遍历字符 `a` 到 `c`。 +然而，它也有两个守卫，所以唯一一次调用 print 语句是当 `i` 的值为 `2` 并且 `j` 是字符 `b` 时： + +{% tabs for-guards-multi class=tabs-scala-version %} +{% tab 'Scala 2' for=for-guards-multi %} + +```scala +for { + i <- 1 to 3 + j <- 'a' to 'c' + if i == 2 + if j == 'b' +} { + println(s"i = $i, j = $j") // prints: "i = 2, j = b" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-guards-multi %} + +```scala +for + i <- 1 to 3 + j <- 'a' to 'c' + if i == 2 + if j == 'b' +do + println(s"i = $i, j = $j") // prints: "i = 2, j = b" +``` + +{% endtab %} +{% endtabs %} + +### `for` 表达式 + +`for` 关键字更强大：当您使用 `yield` 关键字代替 `do` 时，您会创建 `for` _表达式_用于计算和产生结果。 + +几个例子演示了这一点。 +使用与上一个示例相同的 `ints` 列表，此代码创建一个新列表，其中新列表中每个元素的值是原始列表中元素值的两倍： + +{% tabs for-expression_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expression_1 %} + +```` +scala> val doubles = for (i <- ints) yield i * 2 +val doubles: List[Int] = List(2, 4, 6, 8, 10) +```` + +{% endtab %} + +{% tab 'Scala 3' for=for-expression_1 %} + +```` +scala> val doubles = for i <- ints yield i * 2 +val doubles: List[Int] = List(2, 4, 6, 8, 10) +```` + +{% endtab %} +{% endtabs %} + +Scala 的控制结构语法很灵活，`for` 表达式可以用其他几种方式编写，具体取决于您的偏好： + +{% tabs for-expressioni_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_2 %} + +```scala +val doubles = for (i <- ints) yield i * 2 +val doubles = for (i <- ints) yield (i * 2) +val doubles = for { i <- ints } yield (i * 2) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_2 %} + +```scala +val doubles = for i <- ints yield i * 2 // 如上所示的风格 +val doubles = for (i <- ints) yield i * 2 +val doubles = for (i <- ints) yield (i * 2) +val doubles = for { i <- ints } yield (i * 2) +``` + +{% endtab %} +{% endtabs %} + +此示例显示如何将列表中每个字符串的第一个字符大写： + +{% tabs for-expressioni_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_3 %} + +```scala +val names = List("chris", "ed", "maurice") +val capNames = for (name <- names) yield name.capitalize +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_3 %} + +```scala +val names = List("chris", "ed", "maurice") +val capNames = for name <- names yield name.capitalize +``` + +{% endtab %} +{% endtabs %} + +最后，这个 `for` 表达式遍历一个字符串列表，并返回每个字符串的长度，但前提是该长度大于 `4`： + +{% tabs for-expressioni_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-expressioni_4 %} + +```scala +val fruits = List("apple", "banana", "lime", "orange") + +val fruitLengths = + for (f <- fruits if f.length > 4) yield f.length + +// fruitLengths: List[Int] = List(5, 6, 6) +``` + +{% endtab %} + +{% tab 'Scala 3' for=for-expressioni_4 %} + +```scala +val fruits = List("apple", "banana", "lime", "orange") + +val fruitLengths = for + f <- fruits + if f.length > 4 +yield + // 在这里你可以 + // 使用多行代码 + f.length + +//fruitLengths: List[Int] = List(5, 6, 6) +``` + +{% endtab %} +{% endtabs %} + +`for` 循环和表达式更多细节在本书的 [控制结构部分][control] 中，和 [参考文档]({{ site.scala3ref }}/other-new-features/control-syntax.html) 中。 + +## `match` 表达式 + +Scala 有一个 `match` 表达式，它最基本的用途类似于 Java `switch` 语句： + +{% tabs match class=tabs-scala-version %} +{% tab 'Scala 2' for=match %} + +```scala +val i = 1 + +// later in the code ... +i match { + case 1 => println("one") + case 2 => println("two") + case _ => println("other") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match %} + +```scala +val i = 1 + +// later in the code ... +i match + case 1 => println("one") + case 2 => println("two") + case _ => println("other") +``` + +{% endtab %} +{% endtabs %} + +但是，`match` 确实是一个表达式，这意味着它会根据模式匹配返回一个结果，您可以将其绑定到一个变量： + +{% tabs match-expression_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_1 %} + +```scala +val result = i match { + case 1 => "one" + case 2 => "two" + case _ => "other" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match-expression_1 %} + + +```scala +val result = i match + case 1 => "one" + case 2 => "two" + case _ => "other" +``` + +{% endtab %} +{% endtabs %} + +`match` 不仅限于使用整数值，它可以用于任何数据类型： + +{% tabs match-expression_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_2 %} + +```scala +val p = Person("Fred") + +// later in the code +p match { + case Person(name) if name == "Fred" => + println(s"$name says, Yubba dubba doo") + + case Person(name) if name == "Bam Bam" => + println(s"$name says, Bam bam!") + + case _ => println("Watch the Flintstones!") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=match-expression_2 %} + +```scala +val p = Person("Fred") + +// later in the code +p match + case Person(name) if name == "Fred" => + println(s"$name says, Yubba dubba doo") + + case Person(name) if name == "Bam Bam" => + println(s"$name says, Bam bam!") + + case _ => println("Watch the Flintstones!") +``` + +{% endtab %} +{% endtabs %} + +事实上，`match` 表达式可以用许多模式的不同类型来测试变量。 +此示例显示 (a) 如何使用 `match` 表达式作为方法的主体，以及 (b) 如何匹配显示的所有不同类型： + +{% tabs match-expression_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=match-expression_3 %} + +```scala +// getClassAsString is a method that takes a single argument of any type. +def getClassAsString(x: Any): String = x match { + case s: String => s"'$s' is a String" + case i: Int => "Int" + case d: Double => "Double" + case l: List[_] => "List" + case _ => "Unknown" +} + +// examples +getClassAsString(1) // Int +getClassAsString("hello") // 'hello' is a String +getClassAsString(List(1, 2, 3)) // List +``` + +因为 `getClassAsString` 方法获取 `Any` 类型的参数值，所以它可以解耦任意模式类型。 + +{% endtab %} + +{% tab 'Scala 3' for=match-expression_3 %} + +```scala +// getClassAsString 是一个接受任何类型的单个参数的方法。 +def getClassAsString(x: Matchable): String = x match + case s: String => s"'$s' is a String" + case i: Int => "Int" + case d: Double => "Double" + case l: List[_] => "List" + case _ => "Unknown" + +// examples +getClassAsString(1) // Int +getClassAsString("hello") // 'hello' is a String +getClassAsString(List(1, 2, 3)) // List +``` + +`getClassAsString` 方法将 [Matchable]({{ site.scala3ref }}/other-new-features/matchable.html) 类型的值作为参数，它可以是 +任何支持模式匹配的类型（某些类型不支持模式匹配，因为这可能打破封装）。 + +{% endtab %} +{% endtabs %} + +Scala 中的模式匹配还有 _更多_ 内容。 +模式可以嵌套，模式的结果可以绑定，模式匹配甚至可以是用户自定义的。 +有关详细信息，请参阅 [控制结构章节][control] 中的模式匹配示例。 + +## `try`/`catch`/`finally` + +Scala 的 `try`/`catch`/`finally` 控制结构让你捕获异常。 +它类似于 Java，但其语法与 `match` 表达式一致： + +{% tabs try class=tabs-scala-version %} +{% tab 'Scala 2' for=try %} + +```scala +try { + writeTextToFile(text) +} catch { + case ioe: IOException => println("Got an IOException.") + case nfe: NumberFormatException => println("Got a NumberFormatException.") +} finally { + println("Clean up your resources here.") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=try %} + +```scala +try + writeTextToFile(text) +catch + case ioe: IOException => println("Got an IOException.") + case nfe: NumberFormatException => println("Got a NumberFormatException.") +finally + println("Clean up your resources here.") +``` + +{% endtab %} +{% endtabs %} + +## `while` 循环 + +Scala 还有一个 `while` 循环结构。 +它的单行语法如下所示： + +{% tabs while_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=while_1 %} + +```scala +while (x >= 0) { x = f(x) } +``` + +{% endtab %} + +{% tab 'Scala 3' for=while_1 %} + +```scala +while x >= 0 do x = f(x) +``` +为了兼容性，Scala 3 仍然支持 Scala 2 语法。 + +{% endtab %} +{% endtabs %} + +`while` 循环多行语法如下所示： + +{% tabs while_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=while_2 %} + +```scala +var x = 1 + +while (x < 3) { + println(x) + x += 1 +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=while_2 %} + +```scala +var x = 1 + +while + x < 3 +do + println(x) + x += 1 +``` + +{% endtab %} +{% endtabs %} + +## 自定义控制结构 + +由于传名参数、中缀表示法、流畅接口、可选括号、扩展方法和高阶函数等功能，您还可以创建自己的代码，就像控制结构一样工作。 +您将在 [控制结构][control] 部分了解更多信息。 + +[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-functions.md b/_zh-cn/overviews/scala3-book/taste-functions.md new file mode 100644 index 0000000000..71cea44649 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-functions.md @@ -0,0 +1,87 @@ +--- +title: 头等函数 +type: section +description: This page provides an introduction to functions in Scala 3. +language: zh-cn +num: 11 +previous-page: taste-methods +next-page: taste-objects + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala具有函数式编程语言中您期望的大多数功能，包括： + +- Lambdas（匿名函数） +- 高阶函数 （HOFs） +- 标准库中的不可变集合 + +Lambdas（也称为 _匿名函数_）是保持代码简洁但可读性的重要组成部分。 + +`List` 类的 `map` 方法是高阶函数的典型示例---一个将函数作为参数的函数。 + +这两个示例是等效的，并演示如何通过将 lambda 传递到 `map` 方法中，将列表中的每个数字乘以 `2`： + + +{% tabs function_1 %} +{% tab 'Scala 2 and 3' for=function_1 %} + +```scala +val a = List(1, 2, 3).map(i => i * 2) // List(2,4,6) +val b = List(1, 2, 3).map(_ * 2) // List(2,4,6) +``` + +{% endtab %} +{% endtabs %} + +这些示例也等效于以下代码，该代码使用 `double` 方法而不是lambda： + +{% tabs function_2 %} +{% tab 'Scala 2 and 3' for=function_2 %} + +```scala +def double(i: Int): Int = i * 2 + +val a = List(1, 2, 3).map(i => double(i)) // List(2,4,6) +val b = List(1, 2, 3).map(double) // List(2,4,6) +``` + +{% endtab %} +{% endtabs %} + +> 如果您以前从未见过 `map` 方法，它会将给定的函数应用于列表中的每个元素，从而生成一个包含结果值的新列表。 + +将 lambda 传递给集合类上的高阶函数（如 `List`）是 Scala 体验的一部分，您每天都会这样做。 + +## 不可变集合 + +当您使用不可变集合（如 `List`，`Vector`）以及不可变的 `Map` 和 `Set` 类时，重要的是要知道这些函数不会改变它们被调用的集合；相反，它们返回包含更新数据的新集合。 +因此，以“流式”的风格将它们链接在一起以解决问题也很常见。 + +例如，此示例演示如何对一个集合进行两次筛选，然后将其余集合中的每个元素乘某个数： + +{% tabs function_3 %} +{% tab 'Scala 2 and 3' for=function_3 %} + +```scala +// a sample list +val nums = (1 to 10).toList // List(1,2,3,4,5,6,7,8,9,10) + +// methods can be chained together as needed +val x = nums.filter(_ > 3) + .filter(_ < 7) + .map(_ * 10) + +// result: x == List(40, 50, 60) +``` + +{% endtab %} +{% endtabs %} + +除了在整个标准库中使用的高阶函数外，您还可以[创建自己的][higher-order] 高阶函数。 + +[higher-order]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-hello-world.md b/_zh-cn/overviews/scala3-book/taste-hello-world.md new file mode 100644 index 0000000000..cebe30f7fa --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-hello-world.md @@ -0,0 +1,202 @@ +--- +title: Hello, World! +type: section +description: This section demonstrates a Scala 3 'Hello, World!' example. +language: zh-cn +num: 5 +previous-page: taste-intro +next-page: taste-repl + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +> **提示**：在以下示例中，尝试选择您喜欢的 Scala 版本。 +> + +## 你的第一个 Scala 程序 + +Scala “Hello, world!” 例子展示如下。 +首先，把以下代码写入 _Hello.scala_: + + +{% tabs hello-world-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-demo %} +```scala +object hello { + def main(args: Array[String]) = { + println("Hello, World!") + } +} +``` +> 代码中，在名为 `hello` 的 Scala `object` 中，我们定义了一个名称为 `main` 的方法。 +> 在 Scala 中 `object` 类似 `class`，但定义了一个可以传递的单例实例。 +> `main` 用名为 `args` 的输入参数，该参数必须是 `Array[String]` 类型（暂时忽略 `args`）。 + +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} +```scala +@main def hello() = println("Hello, World!") +``` +> 代码中， `hello` 是方法。 +> 它使用 `def` 定义，并用 `@main` 注释的手段把它声明为“main”方法。 +> 使用 `println` 方法，它在标准输出 （STDOUT）中打印了 `"Hello, world!"` 字符串。 + +{% endtab %} + +{% endtabs %} + + +下一步，用 `scalac` 编译代码： + +```bash +$ scalac Hello.scala +``` + +如果你是从 Java 转到 Scala，`scalac` 就像 `javac`，所以该命令会创建几个文件： + + +{% tabs hello-world-outputs class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-outputs %} +```bash +$ ls -1 +hello$.class +hello.class +hello.scala +``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-outputs %} +```bash +$ ls -1 +hello$package$.class +hello$package.class +hello$package.tasty +hello.scala +hello.class +hello.tasty +``` +{% endtab %} + +{% endtabs %} + + +与 Java 一样，_.class_ 文件是字节码文件，它们已准备好在 JVM 中运行。 + +现在您可以使用 `scala` 命令运行 `hello` 方法： + +```bash +$ scala hello +Hello, world! +``` + +假设它运行成功，那么恭喜，您刚刚编译并运行了您的第一个 Scala 应用程序。 + +> 在 [Scala 工具][scala_tools] 章节中可以找到 sbt 和其他使 Scala 开发更容易的工具相关的更多信息。 + +## 要求用户输入 + +在下一个示例中，让我们在问候用户之前询问用户名！ + +有几种方法可以从命令行读取输入，但一种简单的方法是使用 +_scala.io.StdIn_ 对象中的 `readline` 方法。要使用它，您需要先导入它，如下所示： + +{% tabs import-readline %} +{% tab 'Scala 2 and 3' for=import-readline %} +```scala +import scala.io.StdIn.readLine +``` +{% endtab %} +{% endtabs %} + +为了演示其工作原理，让我们创建一个小示例。将此源代码放在名为 _helloInteractive.scala_ 的文件里： + + +{% tabs hello-world-interactive class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-interactive %} +```scala +import scala.io.StdIn.readLine + +object helloInteractive { + + def main(args: Array[String]) = { + println("Please enter your name:") + val name = readLine() + + println("Hello, " + name + "!") + } + +} +``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-interactive %} +```scala +import scala.io.StdIn.readLine + +@main def helloInteractive() = + println("Please enter your name:") + val name = readLine() + + println("Hello, " + name + "!") +``` +{% endtab %} + +{% endtabs %} + + +在此代码中，我们将 `readLine` 的结果保存到一个名为 `name` 的变量中，然后 +使用字符串上的 `+` 运算符将 `“Hello， ”` 与 `name` 和 `"!"` 连接起来，生成单一字符串值。 + +> 您可以通过阅读[变量和数据类型]（/zh-cn/scala3/book/taste-vars-data-types.html）来了解有关使用 `val` 的更多信息。 + +然后使用 `scalac` 编译代码： + +```bash +$ scalac helloInteractive.scala +``` + +然后用 `scala helloInteractive` 运行它，这次程序将在询问您的名字后暂停并等待， +直到您键入一个名称，然后按键盘上的回车键，如下所示： + +```bash +$ scala helloInteractive +Please enter your name: +▌ +``` + +当您在提示符下输入您的姓名时，最终的交互应如下所示： + +```bash +$ scala helloInteractive +Please enter your name: +Alvin Alexander +Hello, Alvin Alexander! +``` + +### 关于导入的说明 + +正如您在此应用程序中看到的，有时某些方法或我们稍后将看到的其他类型的定义不可用， +除非您使用如下所示的 `导入` 子句： + +{% tabs import-readline-2 %} +{% tab 'Scala 2 and 3' for=import-readline-2 %} +```scala +import scala.io.StdIn.readLine +``` +{% endtab %} +{% endtabs %} + +导入可通过多种方式帮助您编写代码： + - 您可以将代码放在多个文件中，以帮助避免混乱，并帮助导航大型项目。 + - 您可以使用包含有用功能的代码库，该库可能是由其他人编写 + - 您可以知道某个定义的来源（特别是如果它没有写入当前文件）。 + +[scala_tools]: {% link _zh-cn/overviews/scala3-book/scala-tools.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-intro.md b/_zh-cn/overviews/scala3-book/taste-intro.md new file mode 100644 index 0000000000..0d2f0fdf50 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-intro.md @@ -0,0 +1,27 @@ +--- +title: Scala 的味道 +type: chapter +description: This chapter provides a high-level overview of the main features of the Scala 3 programming language. +language: zh-cn +num: 4 +previous-page: why-scala-3 +next-page: taste-hello-world + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章提供的快速导览涉及 Scala 3 编程语言的主要特性。 +在本导览之后，本书的其余部分提供了有关这些特性的更多详细信息，而[参考文档][reference]提供了_许多_ 细节。 + +## 设置 Scala + +在本章和本书的其余部分，我们鼓励您通过复制或手动键入来尝试这些示例。遵循示例所需的工具你可以按照我们的[入门指南][get-started]在自己的计算机上安装。 + +> 或者，您可以使用 [Scastie](https://scastie.scala-lang.org) 在 Web 浏览器中运行这些示例，这是一个完全在线的编辑器和 Scala 的代码运行器。 + +[reference]: {{ site.scala3ref }}/overview.html +[get-started]: {% link _overviews/getting-started/install-scala.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-methods.md b/_zh-cn/overviews/scala3-book/taste-methods.md new file mode 100644 index 0000000000..521c093a8e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-methods.md @@ -0,0 +1,217 @@ +--- +title: 方法 +type: section +description: This section provides an introduction to defining and using methods in Scala 3. +language: zh-cn +num: 10 +previous-page: taste-modeling +next-page: taste-functions + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +## Scala 方法 + +Scala 类、样例类、traits、枚举和对象都可以包含方法。 +简单方法的语法如下所示： + +{% tabs method_1 %} +{% tab 'Scala 2 and 3' for=method_1 %} + +```scala +def methodName(param1: Type1, param2: Type2): ReturnType = + // the method body + // goes here +``` + +{% endtab %} +{% endtabs %} + +这有一些例子： + +{% tabs method_2 %} +{% tab 'Scala 2 and 3' for=method_2 %} + +```scala +def sum(a: Int, b: Int): Int = a + b +def concatenate(s1: String, s2: String): String = s1 + s2 +``` + +{% endtab %} +{% endtabs %} + +您不必声明方法的返回类型，因此如果您愿意，可以像这样编写这些方法： + +{% tabs method_3 %} +{% tab 'Scala 2 and 3' for=method_3 %} + +```scala +def sum(a: Int, b: Int) = a + b +def concatenate(s1: String, s2: String) = s1 + s2 +``` + +{% endtab %} +{% endtabs %} + +这是你如何调用这些方法： + +{% tabs method_4 %} +{% tab 'Scala 2 and 3' for=method_4 %} + +```scala +val x = sum(1, 2) +val y = concatenate("foo", "bar") +``` + +{% endtab %} +{% endtabs %} + +这是一个多行的方法： + +{% tabs method_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=method_5 %} + +```scala +def getStackTraceAsString(t: Throwable): String = { + val sw = new StringWriter + t.printStackTrace(new PrintWriter(sw)) + sw.toString +} +``` + +{% endtab %} +{% tab 'Scala 3' for=method_5 %} + +```scala +def getStackTraceAsString(t: Throwable): String = + val sw = new StringWriter + t.printStackTrace(new PrintWriter(sw)) + sw.toString +``` + +{% endtab %} +{% endtabs %} + +方法参数也可以具有默认值。 +在此示例中，`timeout` 参数的默认值为 `5000`： + +{% tabs method_6 %} +{% tab 'Scala 2 and 3' for=method_6 %} + +```scala +def makeConnection(url: String, timeout: Int = 5000): Unit = + println(s"url=$url, timeout=$timeout") +``` + +{% endtab %} +{% endtabs %} + +由于方法声明中提供了默认的 `超时` 值，因此可以通过以下两种方式调用该方法： + +{% tabs method_7 %} +{% tab 'Scala 2 and 3' for=method_7 %} + +```scala +makeConnection("https://localhost") // url=http://localhost, timeout=5000 +makeConnection("https://localhost", 2500) // url=http://localhost, timeout=2500 +``` + +{% endtab %} +{% endtabs %} + +Scala 还支持在调用方法时使用 _命名参数_，因此如果您愿意，也可以像这样调用该方法： + +{% tabs method_8 %} +{% tab 'Scala 2 and 3' for=method_8 %} + +```scala +makeConnection( + url = "https://localhost", + timeout = 2500 +) +``` + +{% endtab %} +{% endtabs %} + +当多个方法参数具有相同的类型时，命名参数特别有用。 +乍一看，使用此方法，您可能想知道哪些参数设置为 `true` 或 `false`： + +{% tabs method_9 %} +{% tab 'Scala 2 and 3' for=method_9 %} + +```scala +engage(true, true, true, false) +``` + +{% endtab %} +{% endtabs %} + +如果没有IDE的帮助，那段代码可能很难阅读，但这个代码要明显得多： + +{% tabs method_10 %} +{% tab 'Scala 2 and 3' for=method_10 %} + +```scala +engage( + speedIsSet = true, + directionIsSet = true, + picardSaidMakeItSo = true, + turnedOffParkingBrake = false +) +``` +{% endtab %} +{% endtabs %} + +## 扩展方法 + +_扩展方法_ 允许您向封闭类添加新方法。 +例如，如果要将两个名为 `hello` 和 `aloha` 的方法添加到 `String` 类中，请将它们声明为扩展方法： + +{% tabs extension0 %} +{% tab 'Scala 3 Only' %} + +```scala +extension (s: String) + def hello: String = s"Hello, ${s.capitalize}!" + def aloha: String = s"Aloha, ${s.capitalize}!" + +"world".hello // "Hello, World!" +"friend".aloha // "Aloha, Friend!" +``` + +{% endtab %} +{% endtabs %} + +`extension` 关键字声明了括号内的参数将定义一个或多个扩展方法。 +如此示例所示，可以在扩展方法体中使用 `String` 类型的参数 `s`。 + +下一个示例演示如何将 `makeInt` 方法添加到 `String` 类。 +在这里，`makeInt` 采用一个名为 `radix` 的参数。 +该代码不考虑可能的字符串到整数转换错误，但跳过细节，示例显示了它的工作原理： + +{% tabs extension %} +{% tab 'Scala 3 Only' %} + +```scala +extension (s: String) + def makeInt(radix: Int): Int = Integer.parseInt(s, radix) + +"1".makeInt(2) // Int = 1 +"10".makeInt(2) // Int = 2 +"100".makeInt(2) // Int = 4 +``` + +{% endtab %} +{% endtabs %} + +## 参见 + +Scala方法可以更强大：它们可以采用类型参数和上下文参数。 +它们在[领域建模][data-1]一节中有详细介绍。 + +[data-1]: {% link _zh-cn/overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-modeling.md b/_zh-cn/overviews/scala3-book/taste-modeling.md new file mode 100644 index 0000000000..ca39aafe34 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-modeling.md @@ -0,0 +1,428 @@ +--- +title: 领域建模 +type: section +description: This section provides an introduction to data modeling in Scala 3. +language: zh-cn +num: 9 +previous-page: taste-control-structures +next-page: taste-methods + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +{% comment %} +NOTE: I kept the OOP section first, assuming that most readers will be coming from an OOP background. +{% endcomment %} + +Scala 同时支持函数式编程 (FP) 和面向对象编程 (OOP)，以及这两种范式的融合。 +本节简要概述了 OOP 和 FP 中的数据建模。 + +## OOP 领域建模 + +以 OOP 风格编写代码时，用于数据封装的两个主要工具是 _traits_ 和 _classes_。 + +{% comment %} +NOTE: Julien had a comment, “in OOP we don’t really model data. +It’s more about modeling operations, imho.” + +How to resolve? Is there a good DDD term to use here? +{% endcomment %} + +### Traits + +Scala trait 可以用作简单的接口，但它们也可以包含抽象和具体的方法和字段，并且它们可以有参数，就像类一样。 +它们为您提供了一种将行为组织成小型模块化单元的好方法。 +稍后，当您想要创建属性和行为的具体实现时，类和对象可以扩展特征，根据需要混合尽可能多的特征以实现所需的行为。 + +作为如何将 traits 用作接口的示例，以下是三个 traits，它们为狗和猫等动物定义了结构良好并且模块化的行为： + +{% tabs traits class=tabs-scala-version %} +{% tab 'Scala 2' for=traits %} + +```scala +trait Speaker { + def speak(): String // has no body, so it’s abstract +} + +trait TailWagger { + def startTail(): Unit = println("tail is wagging") + def stopTail(): Unit = println("tail is stopped") +} + +trait Runner { + def startRunning(): Unit = println("I’m running") + def stopRunning(): Unit = println("Stopped running") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits %} + + +```scala +trait Speaker: + def speak(): String // has no body, so it’s abstract + +trait TailWagger: + def startTail(): Unit = println("tail is wagging") + def stopTail(): Unit = println("tail is stopped") + +trait Runner: + def startRunning(): Unit = println("I’m running") + def stopRunning(): Unit = println("Stopped running") +``` + +{% endtab %} +{% endtabs %} + +鉴于这些特征，这里有一个 `Dog` 类，它扩展了所有这些特征，同时为抽象 `speak` 方法提供了一种行为： + +{% tabs traits-class class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-class %} + +```scala +class Dog(name: String) extends Speaker with TailWagger with Runner { + def speak(): String = "Woof!" +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-class %} + +```scala +class Dog(name: String) extends Speaker, TailWagger, Runner: + def speak(): String = "Woof!" +``` + +{% endtab %} +{% endtabs %} + +请注意该类如何使用 `extends` 关键字扩展 traits。 + +类似地，这里有一个 `Cat` 类，它实现了这些相同的 traits，同时还覆盖了它继承的两个具体方法： + +{% tabs traits-override class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-override %} + +```scala +class Cat(name: String) extends Speaker with TailWagger with Runner { + def speak(): String = "Meow" + override def startRunning(): Unit = println("Yeah ... I don’t run") + override def stopRunning(): Unit = println("No need to stop") +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-override %} + +```scala +class Cat(name: String) extends Speaker, TailWagger, Runner: + def speak(): String = "Meow" + override def startRunning(): Unit = println("Yeah ... I don’t run") + override def stopRunning(): Unit = println("No need to stop") +``` + +{% endtab %} +{% endtabs %} + +这些示例显示了如何使用这些类： + +{% tabs traits-use class=tabs-scala-version %} +{% tab 'Scala 2' for=traits-use %} + +```scala +val d = new Dog("Rover") +println(d.speak()) // prints "Woof!" + +val c = new Cat("Morris") +println(c.speak()) // "Meow" +c.startRunning() // "Yeah ... I don’t run" +c.stopRunning() // "No need to stop" +``` + +{% endtab %} + +{% tab 'Scala 3' for=traits-use %} + +```scala +val d = Dog("Rover") +println(d.speak()) // prints "Woof!" + +val c = Cat("Morris") +println(c.speak()) // "Meow" +c.startRunning() // "Yeah ... I don’t run" +c.stopRunning() // "No need to stop" +``` + +{% endtab %} +{% endtabs %} + +如果该代码有意义---太好了，您把 traits 作为接口感到舒服。 +如果没有，请不要担心，它们在 [Domain Modeling][data-1] 章节中有更详细的解释。 + +### 类 + +Scala _classes_ 用于 OOP 风格的编程。 +这是一个模拟“人”的类的示例。在 OOP 中，字段通常是可变的，所以 `firstName` 和 `lastName` 都被声明为 `var` 参数： + +{% tabs class_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=class_1 %} + +```scala +class Person(var firstName: String, var lastName: String) { + def printFullName() = println(s"$firstName $lastName") +} + +val p = new Person("John", "Stephens") +println(p.firstName) // "John" +p.lastName = "Legend" +p.printFullName() // "John Legend" +``` + +{% endtab %} + +{% tab 'Scala 3' for=class_1 %} + +```scala +class Person(var firstName: String, var lastName: String): + def printFullName() = println(s"$firstName $lastName") + +val p = Person("John", "Stephens") +println(p.firstName) // "John" +p.lastName = "Legend" +p.printFullName() // "John Legend" +``` + +{% endtab %} +{% endtabs %} + +请注意，类声明创建了一个构造函数： + +{% tabs class_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=class_2 %} + +```scala +// this code uses that constructor +val p = new Person("John", "Stephens") +``` + +{% endtab %} + +{% tab 'Scala 3' for=class_2 %} + +```scala +// 此代码使用该构造函数 +val p = Person("约翰", "斯蒂芬斯") +``` + +{% endtab %} +{% endtabs %} + +[Domain Modeling][data-1] 章节中介绍了构造函数和其他与类相关的主题。 + +## FP 领域建模 + +{% comment %} +NOTE: Julien had a note about expecting to see sealed traits here. +I didn’t include that because I didn’t know if enums are intended +to replace the Scala2 “sealed trait + case class” pattern. How to resolve? +{% endcomment %} + +以 FP 风格编写代码时，您将使用以下结构： + +- 代数数据类型（ADT）来定义数据 +- Traits 来定义数据上的功能 + +### 枚举和 Sum Types + +Sum types 是在 Scala 中给代数数据类型（ADT）建模的一种方法。 + +`enum` 构造是在 Scala 3 中对代数数据类型 (ADT) 进行建模的好方法。 + +例如，披萨具有三个主要属性： + +- 面饼大小 +- 面饼类型 +- 馅料 + +这些是用枚举简洁地建模的，它们是只包含单例值的 sum types： + +{% tabs enum_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_1 %} + +在 Scala 2 中，用 `sealed` 类和 `case object` 组合在一起来定义枚举: + +```scala +sealed abstract class CrustSize +object CrustSize { + case object Small extends CrustSize + case object Medium extends CrustSize + case object Large extends CrustSize +} + +sealed abstract class CrustType +object CrustType { + case object Thin extends CrustType + case object Thick extends CrustType + case object Regular extends CrustType +} + +sealed abstract class Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping +} +``` + +{% endtab %} +{% tab 'Scala 3' for=enum_1 %} + +Scala 3 提供了 `enum` 结构来定义枚举： + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +一旦你有了一个枚举，你就可以按照你通常使用特征、类或对象的所有方式来使用枚举： + +{% tabs enum_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_2 %} + +```scala +import CrustSize._ +val currentCrustSize = Small + +// enums in a `match` expression +currentCrustSize match { + case Small => println("Small crust size") + case Medium => println("Medium crust size") + case Large => println("Large crust size") +} + +// enums in an `if` statement +if (currentCrustSize == Small) println("Small crust size") +``` + +{% endtab %} +{% tab 'Scala 3' for=enum_2 %} + +```scala +import CrustSize.* +val currentCrustSize = Small + +// enums in a `match` expression +currentCrustSize match + case Small => println("Small crust size") + case Medium => println("Medium crust size") + case Large => println("Large crust size") + +// enums in an `if` statement +if currentCrustSize == Small then println("Small crust size") +``` + +{% endtab %} +{% endtabs %} + +下面是另一个如何在 Scala 中创建 sum type 的示例，它不能被叫作枚举，因为 `succ` 样例类有参数：的示例： + +{% tabs enum_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=enum_3 %} + +```scala +sealed abstract class Nat +object Nat { + case object Zero extends Nat + case class Succ(pred: Nat) extends Nat +} +``` + +Sum Types 在本书的[领域建模]({% link _overviews/scala3-book/domain-modeling-tools.md %})部分有详细的介绍。 + +{% endtab %} +{% tab 'Scala 3' for=enum_3 %} + +```scala +enum Nat: + case Zero + case Succ(pred: Nat) +``` + +枚举在本书的 [领域建模]({% link _overviews/scala3-book/domain-modeling-tools.md %})部分和 [参考文档]({{ site.scala3ref }}/enums/enums.html) 中有详细介绍。 + +{% endtab %} +{% endtabs %} + +### Product Types + +product type 是代数数据类型（ADT），它只含有一个形状，例如一个单例对象，在Scala 中用 `case` 对象来代表；或者是一个可以获取字段的不可变结构，用 `case` 类来代表。 + +`case` 类具有 `class` 的所有功能，还包含其他功能，使它们对函数式编程很有用。 +当编译器在 `class` 前面看到 `case` 关键字时，它具有以下效果和好处： + +- 样例类构造函数参数默认为 public `val` 字段，因此字段是不可变的，并且为每个参数生成访问器方法。 +- 生成一个 `unapply` 方法，它允许您在 `match` 表达式中以更多方式使用 样例类。 +- 在类中生成一个 `copy` 方法。 + 这提供了一种在不更改原始对象的情况下创建对象的更新副本的方法。 +- 生成 `equals` 和 `hashCode` 方法来实现结构相等等式。 +- 生成一个默认的 `toString` 方法，有助于调试。 + +{% comment %} +NOTE: Julien had a comment about how he decides when to use case classes vs classes. Add something here? +{% endcomment %} + +您_可以_自己手动将所有这些方法添加到一个类中，但是由于这些功能在函数式编程中非常常用，因此使用“case”类要方便得多。 + +这段代码演示了几个 `case` 类的特性： + +{% tabs case-class %} +{% tab 'Scala 2 and 3' for=case-class %} + +```scala +// define a case class +case class Person( + name: String, + vocation: String +) + +// create an instance of the case class +val p = Person("Reginald Kenneth Dwight", "Singer") + +// a good default toString method +p // : Person = Person(Reginald Kenneth Dwight,Singer) + +// can access its fields, which are immutable +p.name // "Reginald Kenneth Dwight" +p.name = "Joe" // error: can’t reassign a val field + +// when you need to make a change, use the `copy` method +// to “update as you copy” +val p2 = p.copy(name = "Elton John") +p2 // : Person = Person(Elton John,Singer) +``` + +{% endtab %} +{% endtabs %} + +有关 `case` 类的更多详细信息，请参阅 [领域建模][data-1] 部分。 + +[data-1]: {% link _zh-cn/overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-objects.md b/_zh-cn/overviews/scala3-book/taste-objects.md new file mode 100644 index 0000000000..3d3ec5457e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-objects.md @@ -0,0 +1,172 @@ +--- +title: 单例对象 +type: section +description: This section provides an introduction to the use of singleton objects in Scala 3. +language: zh-cn +num: 12 +previous-page: taste-functions +next-page: taste-collections + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在 Scala 中，`object` 关键字创建一个单例对象。 +换句话说，对象定义了一个只有一个实例的类。 + +对象有多种用途： + +- 它们用于创建实用程序方法的集合。 +- _伴生对象_ 与一个类同名二者在同一个文件里。 + 在此情况下，该类也称为 _伴生类_。 +- 它们用于实现 traits，再用 traits 来创建 _模块_。 + +## “实用工具”方法 + +因为 `object` 是单例，所以它的方法可以像 Java 类中的 `static` 方法一样被访问。 +例如，此 `StringUtils` 对象包含一个与字符串相关的方法的小型集合： + +{% tabs object_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_1 %} + +```scala +object StringUtils { + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty + def leftTrim(s: String): String = s.replaceAll("^\\s+", "") + def rightTrim(s: String): String = s.replaceAll("\\s+$", "") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=object_1 %} + +```scala +object StringUtils: + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty + def leftTrim(s: String): String = s.replaceAll("^\\s+", "") + def rightTrim(s: String): String = s.replaceAll("\\s+$", "") +``` + +{% endtab %} +{% endtabs %} + +由于 `StringUtils` 是一个单例，因此可以直接在对象上调用其方法： + +{% tabs object_2 %} +{% tab 'Scala 2 and 3' for=object_2 %} + +```scala +val x = StringUtils.isNullOrEmpty("") // true +val x = StringUtils.isNullOrEmpty("a") // false +``` + +{% endtab %} +{% endtabs %} + +## 伴生对象 + +伴生类或对象可以访问其伙伴的私有成员。 +对不特定于伴生类实例的方法和值使用伴生对象。 + +此示例演示了伴生类中的 `area` 方法如何访问其伴生对象中的私有 `calculateArea` 方法： + +{% tabs object_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_3 %} + +```scala +import scala.math._ + +class Circle(radius: Double) { + import Circle._ + def area: Double = calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = + Pi * pow(radius, 2.0) +} + +val circle1 = new Circle(5.0) +circle1.area // Double = 78.53981633974483 +``` + +{% endtab %} +{% tab 'Scala 3' for=object_3 %} + +```scala +import scala.math.* + +class Circle(radius: Double): + import Circle.* + def area: Double = calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = + Pi * pow(radius, 2.0) + +val circle1 = Circle(5.0) +circle1.area // Double = 78.53981633974483 +``` + +{% endtab %} +{% endtabs %} + +## 从 traits 创建模块 + +对象还可用于实现创建模块的 trait。 +这种技术需要两个traits，并将它们结合起来创建一个具体的 `object`： + +{% tabs object_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=object_4 %} + +```scala +trait AddService { + def add(a: Int, b: Int) = a + b +} + +trait MultiplyService { + def multiply(a: Int, b: Int) = a * b +} + +// implement those traits as a concrete object +object MathService extends AddService with MultiplyService + +// use the object +import MathService._ +println(add(1,1)) // 2 +println(multiply(2,2)) // 4 +``` + +{% endtab %} +{% tab 'Scala 3' for=object_4 %} + +```scala +trait AddService: + def add(a: Int, b: Int) = a + b + +trait MultiplyService: + def multiply(a: Int, b: Int) = a * b + +// implement those traits as a concrete object +object MathService extends AddService, MultiplyService + +// use the object +import MathService.* +println(add(1,1)) // 2 +println(multiply(2,2)) // 4 +``` + +{% endtab %} +{% endtabs %} + +{% comment %} +NOTE: I don’t know if this is worth keeping, but I’m leaving it here as a comment for now. + +> You may read that objects are used to _reify_ traits into modules. +> _Reify_ means, “to take an abstract concept and turn it into something concrete.” This is what happens in these examples, but “implement” is a more familiar word for most people than “reify.” +{% endcomment %} + + diff --git a/_zh-cn/overviews/scala3-book/taste-repl.md b/_zh-cn/overviews/scala3-book/taste-repl.md new file mode 100644 index 0000000000..2b043bef03 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-repl.md @@ -0,0 +1,92 @@ +--- +title: The REPL +type: section +description: This section provides an introduction to the Scala REPL. +language: zh-cn +num: 6 +previous-page: taste-hello-world +next-page: taste-vars-data-types + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala REPL（“Read-Evaluate-Print-Loop”）是一个命令行解释器，您可以将其用作“游乐场”区域来测试 Scala 代码。 +你可以通过运行 `scala` 或 `scala3` 命令来启动一个 REPL 会话，具体取决于您在操作系统命令行中的安装，您将看到如下所示的“欢迎”提示： + +{% tabs command-line class=tabs-scala-version %} + +{% tab 'Scala 2' for=command-line %} +```bash +$ scala +Welcome to Scala {{site.scala-version}} (OpenJDK 64-Bit Server VM, Java 1.8.0_342). +Type in expressions for evaluation. Or try :help. + +scala> _ +``` +{% endtab %} + +{% tab 'Scala 3' for=command-line %} +```bash +$ scala +Welcome to Scala {{site.scala-3-version}} (1.8.0_322, Java OpenJDK 64-Bit Server VM). +Type in expressions for evaluation. Or try :help. + +scala> _ +``` +{% endtab %} + +{% endtabs %} + +REPL 是一个命令行解释器，所以它就在那里等着你输入一些东西。 +现在您可以输入 Scala 表达式来查看它们是如何工作的： + +{% tabs expression-one %} +{% tab 'Scala 2 and 3' for=expression-one %} +```` +scala> 1 + 1 +val res0: Int = 2 + +scala> 2 + 2 +val res1: Int = 4 +```` +{% endtab %} +{% endtabs %} + +如输出所示，如果您不为表达式的结果分配变量，REPL 会为您创建名为 `res0`、`res1` 等的变量。 +您可以在后续表达式中使用这些变量名称： + +{% tabs expression-two %} +{% tab 'Scala 2 and 3' for=expression-two %} +```` +scala> val x = res0 * 10 +val x: Int = 20 +```` +{% endtab %} +{% endtabs %} + +请注意，REPL 输出还显示了表达式的结果。 + +您可以在 REPL 中运行各种实验。 +这个例子展示了如何创建然后调用一个 `sum` 方法： + +{% tabs expression-three %} +{% tab 'Scala 2 and 3' for=expression-three %} +```` +scala> def sum(a: Int, b: Int): Int = a + b +def sum(a: Int, b: Int): Int + +scala> sum(2, 2) +val res2: Int = 4 +```` +{% endtab %} +{% endtabs %} + +如果您更喜欢基于浏览器的游乐场环境，也可以使用 [scastie.scala-lang.org](https://scastie.scala-lang.org)。 + +如果您更喜欢在文本编辑器中而不是在控制台提示符中编写代码，您可以使用 [worksheet]。 + +[worksheet]: {% link _zh-cn/overviews/scala3-book/tools-worksheets.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-summary.md b/_zh-cn/overviews/scala3-book/taste-summary.md new file mode 100644 index 0000000000..1fee593727 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-summary.md @@ -0,0 +1,35 @@ +--- +title: 总结 +type: section +description: This page provides a summary of the previous 'Taste of Scala' sections. +language: zh-cn +num: 16 +previous-page: taste-toplevel-definitions +next-page: first-look-at-types + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在前面的部分中，您看到了： + +- 如何使用 Scala REPL +- 如何使用 `val` 和 `var` 创建变量 +- 一些常见的数据类型 +- 控制结构 +- 如何使用 OOP 和 FP 样式对现实世界进行建模 +- 如何创建和使用方法 +- 如何使用lambdas（匿名函数）和高阶函数 +- 如何将对象用于多种目的 +- [上下文抽象][contextual]的介绍 + +我们还提到，如果您更喜欢使用基于浏览器的游乐场环境而不是 Scala REPL，您还可以使用[Scastie](https://scastie.scala-lang.org)。 + +Scala还有更多功能在这次旋风之旅中没有涵盖。 +有关更多详细信息，请参阅本书的其余部分和[参考文档][reference]。 + +[reference]: {{ site.scala3ref }}/overview.html +[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %} diff --git a/_zh-cn/overviews/scala3-book/taste-toplevel-definitions.md b/_zh-cn/overviews/scala3-book/taste-toplevel-definitions.md new file mode 100644 index 0000000000..7deb81d9de --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-toplevel-definitions.md @@ -0,0 +1,80 @@ +--- +title: 顶层定义 +type: section +description: This page provides an introduction to top-level definitions in Scala 3 +language: zh-cn +num: 15 +previous-page: taste-contextual-abstractions +next-page: taste-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在 Scala 3 中，各种定义都可以在源代码文件的 “顶层” 编写。 +例如，您可以创建一个名为 _MyCoolApp.scala_ 的文件，并将以下内容放入其中： + +{% tabs toplevel_1 %} +{% tab 'Scala 3 only' for=toplevel_1 %} + +```scala +import scala.collection.mutable.ArrayBuffer + +enum Topping: + case Cheese, Pepperoni, Mushrooms + +import Topping.* +class Pizza: + val toppings = ArrayBuffer[Topping]() + +val p = Pizza() + +extension (s: String) + def capitalizeAllWords = s.split(" ").map(_.capitalize).mkString(" ") + +val hwUpper = "hello, world".capitalizeAllWords + +type Money = BigDecimal + +// more definitions here as desired ... + +@main def myApp = + p.toppings += Cheese + println("show me the code".capitalizeAllWords) +``` + +{% endtab %} +{% endtabs %} + +如代码中展示的，无需将这些定义放在 `package`, `class` 或其他构造中。 + +## 替换包对象 + +如果你熟悉Scala 2，这种方法可以取代 _包对象_。 +但是，虽然更易于使用，但它们的工作方式类似：当您将定义放在名为 _foo_ 的包中时，您可以在 _foo_ 包内的所有其他包内访问该定义，例如在此示例中的 _foo.bar_ 包中： + +{% tabs toplevel_2 %} +{% tab 'Scala 3 only' for=toplevel_2 %} + +```scala +package foo { + def double(i: Int) = i * 2 +} + +package foo { + package bar { + @main def fooBarMain = + println(s"${double(1)}") // this works + } +} +``` + +{% endtab %} +{% endtabs %} + +本示例中使用大括号来强调包嵌套。 + +这种方法的好处是，您可以将定义放在名为 _com.acme.myapp_ 的包下，然后可以在 _com.acme.myapp.model_、_com.acme.myapp.controller_ 等中引用这些定义。 diff --git a/_zh-cn/overviews/scala3-book/taste-vars-data-types.md b/_zh-cn/overviews/scala3-book/taste-vars-data-types.md new file mode 100644 index 0000000000..2c5a80e5a0 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/taste-vars-data-types.md @@ -0,0 +1,293 @@ +--- +title: 变量和数据类型 +type: section +description: This section demonstrates val and var variables, and some common Scala data types. +language: zh-cn +num: 7 +previous-page: taste-repl +next-page: taste-control-structures + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本节介绍 Scala 变量和数据类型。 + +## 两种类型的变量 + +当你在 Scala 中创建一个新变量时，你声明该变量是不可变的还是可变的： + + + + + + + + + + + + + + + + + + +
            变量类型说明
            val创建一个不可变变量——类似于 Java 中的 final。 您应该始终使用 val 创建一个变量，除非有理由使用可变变量。
            var创建一个可变变量，并且只应在变量的内容随时间变化时使用。
            + +这些示例展示了如何创建 `val` 和 `var` 变量： + +{% tabs var-express-1 %} +{% tab 'Scala 2 and 3' %} + +```scala +// immutable +val a = 0 + +// mutable +var b = 1 +``` + +{% endtab %} +{% endtabs %} + +在应用程序中，不能重新给一个 `val` 变量赋值。 +如果您尝试重新赋值一个 `val` 变量，将导致编译器错误： + +{% tabs var-express-2 %} +{% tab 'Scala 2 and 3' %} + +```scala +val msg = "Hello, world" +msg = "Aloha" // "reassignment to val" error; this won’t compile +``` + +{% endtab %} +{% endtabs %} + +相反，可以给 `var` 变量重新赋值： + +{% tabs var-express-3 %} +{% tab 'Scala 2 and 3' %} + +```scala +var msg = "Hello, world" +msg = "Aloha" // 因为可以重新分配 var，所以可以编译 +``` + +{% endtab %} +{% endtabs %} + +## 声明变量类型 + +创建变量时，您可以显式声明其类型，或让编译器推断类型： + +{% tabs var-express-4 %} +{% tab 'Scala 2 and 3' %} + +```scala +val x: Int = 1 // 显式 +val x = 1 // 隐式的；编译器推断类型 +``` + +{% endtab %} +{% endtabs %} + +第二种形式称为 _类型推断_，它是帮助保持此类代码简洁的好方法。 +Scala 编译器通常可以为您推断数据类型，如以下 REPL 示例的输出所示： + +{% tabs var-express-5 %} +{% tab 'Scala 2 and 3' %} + +```scala +scala> val x = 1 +val x: Int = 1 + +scala> val s = "a string" +val s: String = a string + +scala> val nums = List(1, 2, 3) +val nums: List[Int] = List(1, 2, 3) +``` + +{% endtab %} +{% endtabs %} + +如果您愿意，您始终可以显式声明变量的类型，但在像这样的简单赋值中，不须要这样： + +{% tabs var-express-6 %} +{% tab 'Scala 2 and 3' %} + +```scala +val x: Int = 1 +val s: String = "a string" +val p: Person = Person("Richard") +``` + +{% endtab %} +{% endtabs %} + +请注意，使用这种方法会感觉代码太啰嗦。 + +{% comment %} +TODO: Jonathan had an early comment on the text below: “While it might feel like this, I would be afraid that people automatically assume from this statement that everything is always boxed.” Suggestion on how to change this? +{% endcomment %} + +## 内置数据类型 + +Scala 带有你所期望的标准数值数据类型，它们都是类的成熟（full-blown）实例。 +在 Scala 中，一切都是对象。 + +这些示例展示了如何声明数值类型的变量： + +{% tabs var-express-7 %} +{% tab 'Scala 2 and 3' %} + +```scala +val b: Byte = 1 +val i: Int = 1 +val l: Long = 1 +val s: Short = 1 +val d: Double = 2.0 +val f: Float = 3.0 +``` + +{% endtab %} +{% endtabs %} + +因为 `Int` 和 `Double` 是默认的数字类型，所以您通常创建它们而不显式声明数据类型： + +{% tabs var-express-8 %} +{% tab 'Scala 2 and 3' %} + +```scala +val i = 123 // 默认为 Int +val j = 1.0 // 默认为 Double +``` + +{% endtab %} +{% endtabs %} + +在您的代码中，您还可以将字符 `L`、`D` 和 `F`（或者它们对应的小写字母）加到数字后面以指定它们是 `Long`、`Double` 或 `Float` 值： + +{% tabs var-express-9 %} +{% tab 'Scala 2 and 3' %} + +```scala +val x = 1_000L // val x: Long = 1000 +val y = 2.2D // val y: Double = 2.2 +val z = 3.3F // val z: Float = 3.3 +``` + +{% endtab %} +{% endtabs %} + +当您需要非常大的数字时，请使用 `BigInt` 和 `BigDecimal` 类型： + +{% tabs var-express-10 %} +{% tab 'Scala 2 and 3' %} + +```scala +var a = BigInt(1_234_567_890_987_654_321L) +var b = BigDecimal(123_456.789) +``` + +{% endtab %} +{% endtabs %} + +其中 `Double` 和 `Float` 是近似十进制数，`BigDecimal` 用于精确算术。 + +Scala 还有 `String` 和 `Char` 数据类型： + +{% tabs var-express-11 %} +{% tab 'Scala 2 and 3' %} + +```scala +val name = "Bill" // String +val c = 'a' // Char +``` + +{% endtab %} +{% endtabs %} + +### 字符串 + +Scala 字符串类似于 Java 字符串，但它们有两个很棒的附加特性： + +- 他们支持字符串插值 +- 创建多行字符串很容易 + +#### 字符串插值 + +字符串插值提供了一种非常易读的方式在字符串中使用变量。 +例如，给定这三个变量： + +{% tabs var-express-12 %} +{% tab 'Scala 2 and 3' %} + +```scala +val firstName = "John" +val mi = 'C' +val lastName = "Doe" +``` + +{% endtab %} +{% endtabs %} + +您可以将这些变量组合在一个字符串中，如下所示： + +{% tabs var-express-13 %} +{% tab 'Scala 2 and 3' %} + +```scala +println(s"Name: $firstName $mi $lastName") // "Name: John C Doe" +``` + +{% endtab %} +{% endtabs %} + +只需在字符串前面加上字母 `s`，然后在字符串中的变量名之前放置一个 `$` 符号。 + +要将任意表达式嵌入字符串中，请将它们括在花括号中： + +{% tabs var-express-14 %} +{% tab 'Scala 2 and 3' %} + +``` scala +println(s"2 + 2 = ${2 + 2}") // 打印 "2 + 2 = 4" + +val x = -1 +println(s"x.abs = ${x.abs}") // 打印 "x.abs = 1" +``` + +{% endtab %} +{% endtabs %} + +放在字符串前面的 `s` 只是一种可能的插值器。 +如果使用 `f` 而不是 `s`，则可以在字符串中使用 `printf` 样式的格式化语法。 +此外，字符串插值器只是一种特殊方法，可以定义自己的方法。 +例如，有一些数据库方向的类库定义了非常强大的 `sql` 插值器。 + +#### 多行字符串 + +多行字符串是通过将字符串包含在三个双引号内来创建的： + +{% tabs var-express-15 %} +{% tab 'Scala 2 and 3' %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` + +{% endtab %} +{% endtabs %} + +> 有关字符串插值器和多行字符串的更多详细信息，请参阅[“类型初探”章节][first-look]。 + +[first-look]: {% link _zh-cn/overviews/scala3-book/first-look-at-types.md %} diff --git a/_zh-cn/overviews/scala3-book/tools-sbt.md b/_zh-cn/overviews/scala3-book/tools-sbt.md new file mode 100644 index 0000000000..2b1720c2c9 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/tools-sbt.md @@ -0,0 +1,496 @@ +--- +title: 使用 sbt 构建和测试 Scala 项目 +type: section +description: This section looks at a commonly-used build tool, sbt, and a testing library, ScalaTest. +language: zh-cn +num: 70 +previous-page: scala-tools +next-page: tools-worksheets + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在本节中，您将看到 Scala 项目中常用的两个工具： + +- [sbt](https://www.scala-sbt.org) 构建工具 +- [ScalaTest](https://www.scalatest.org)，一个源代码测试框架 + +我们将首先展示如何使用 sbt 构建您的 Scala 项目，然后我们将展示如何一起使用 sbt 和 ScalaTest 来测试您的 Scala 项目。 + +> 如果您想了解帮助您将 Scala 2 代码迁移到 Scala 3 的工具，请参阅我们的 [Scala 3 迁移指南](/scala3/guides/migration/compatibility-intro.html)。 + +## 使用 sbt 构建 Scala 项目 + +您可以使用多种不同的工具来构建您的 Scala 项目，包括 Ant、Maven、Gradle、Mill 等。 +但是名为 _sbt_ 的工具是第一个专门为 Scala 创建的构建工具。 + +> 要安装 sbt，请参阅 [其下载页面](https://www.scala-sbt.org/download.html) 或我们的 [Getting Started][getting_started] 页面。 + +### 创建一个 “Hello, world” 项目 + +只需几个步骤，您就可以创建一个 sbt “Hello, world” 项目。 +首先，创建一个工作目录，然后进入该目录： + +```bash +$ mkdir hello +$ cd hello +``` + +在 `hello` 目录下，创建一个子目录 `project`： + +```bash +$ mkdir project +``` + +在 `project` 目录中创建一个名为 _build.properties_ 的文件，其中 +以下内容： + +```text +sbt.version=1.10.11 +``` + +然后在包含此行的项目根目录中创建一个名为 _build.sbt_ 的文件： + +```scala +scalaVersion := "{{ site.scala-3-version }}" +``` + +现在创建一个名为 _Hello.scala_ 的文件——名称的第一部分无关紧要——使用这一行： + +```scala +@main def helloWorld = println("Hello, world") +``` + +这就是你所要做的。 + +您应该具有如下的项目结构： + +~~~ bash +$ tree +. +├── build.sbt +├── Hello.scala +└── project + └── build.properties +~~~ + +现在使用 `sbt` 命令运行项目： + +```bash +$ sbt run +``` + +您应该会看到如下所示的输出，包括程序中的 `"Hello, world"`： + +```bash +$ sbt run +[info] welcome to sbt 1.5.4 (AdoptOpenJDK Java 11.x) +[info] loading project definition from project ... +[info] loading settings for project from build.sbt ... +[info] compiling 1 Scala source to target/scala-3.0.0/classes ... +[info] running helloWorld +Hello, world +[success] Total time: 2 s +``` + +sbt 启动器——`sbt` 命令行工具——加载文件 _project/build.properties_ 中设置的 sbt 版本，它加载文件 _build.sbt_ 中设置的 Scala 编译器版本，编译 _Hello.scala_ 文件中的代码，并运行生成的字节码。 + +当你查看你的目录时，你会看到 sbt 有一个名为 _target_ 的目录。 +这些是 sbt 使用的工作目录。 + +如您所见，使用 sbt 创建和运行一个小的 Scala 项目只需要几个简单的步骤。 + +### 在大型项目中使用 sbt + +对于一个小项目，这就是 sbt 运行所需的全部内容。 +对于需要许多源代码文件、依赖项或 sbt 插件的大型项目，您需要创建一个有组织的目录结构。 +本节的其余部分演示了 sbt 使用的结构。 + +### sbt 目录结构 + +与 Maven 一样，sbt 使用标准的项目目录结构。 +这样做的一个很好的好处是，一旦你对它的结构感到满意，它就可以很容易地处理其他 Scala/sbt 项目。 + +首先要知道的是，在项目的根目录下，sbt 需要一个如下所示的目录结构： + +```text +. +├── build.sbt +├── project/ +│ └── build.properties +├── src/ +│ ├── main/ +│ │ ├── java/ +│ │ ├── resources/ +│ │ └── scala/ +│ └── test/ +│ ├── java/ +│ ├── resources/ +│ └── scala/ +└── target/ +``` + +如果您想将非托管依赖项---JAR 文件---添加到您的项目中，您还可以在根目录下添加一个 _lib_ 目录。 + +如果您要创建一个包含 Scala 源代码文件和测试的项目，但不会使用任何 Java 源代码文件，并且不需要任何“资源”——例如嵌入式图像、配置文件、等等---这就是你在_src_目录下真正需要的： + +```text +. +└── src/ + ├── main/ + │ └── scala/ + └── test/ + └── scala/ +``` + +### 带有 sbt 目录结构的 “Hello, world” + +{% comment %} +LATER: using something like `sbt new scala/scala3.g8` may eventually + be preferable, but that seems to have a few bugs atm (creates + a 'target' directory above the root; renames the root dir; + uses 'dottyVersion'; 'name' doesn’t match the supplied name; + config syntax is a little hard for beginners.) +{% endcomment %} + +创建这个目录结构很简单。 +有一些工具可以为你做到这一点，但假设你使用的是 Unix/Linux 系统，你可以使用这些命令来创建你的第一个 sbt 项目目录结构： + +```bash +$ mkdir HelloWorld +$ cd HelloWorld +$ mkdir -p src/{main,test}/scala +$ mkdir project target +``` + +在运行这些命令后运行 `find .` 命令时，您应该会看到以下结果： + +```bash +$ find . +. +./project +./src +./src/main +./src/main/scala +./src/test +./src/test/scala +./target +``` + +如果你看到上面那样，那么没有问题，可以进行下一步了。 + +> 还有其他方法可以为 sbt 项目创建文件和目录。 +> 一种方法是使用 `sbt new` 命令，[在 scala-sbt.org 上有文档](https://www.scala-sbt.org/1.x/docs/Hello.html)。 +> 该方法未在此处显示，因为它创建的某些文件比像这样的介绍所必需的要复杂。 + +### 创建第一个 build.sbt 文件 + +此时，您只需要另外两件事来运行 “Hello, world” 项目： + +- 一个 _build.sbt_ 文件 +- 一个 _Hello.scala_ 文件 + +对于像这样的小项目，_build.sbt_ 文件只需要一个 `scalaVersion` 条目，但我们将添加您通常看到的三行： + +```scala +name := "HelloWorld" +version := "0.1" +scalaVersion := "{{ site.scala-3-version }}" +``` + +因为 sbt 项目使用标准的目录结构，所以 sbt 可以找到它需要的所有其他内容。 + +现在你只需要添加一个小小的“Hello, world”程序。 + +### “Hello, world” 程序 + +在大型项目中，您所有的 Scala 源代码文件都将放在 _src/main/scala_ 和 _src/test/scala_ 目录下，但是对于像这样的小示例项目，您可以将源代码文件放在您项目的根目录下。 +因此，在根目录中创建一个名为 _HelloWorld.scala_ 的文件，其中包含以下内容： + +```scala +@main def helloWorld = println("Hello, world") +``` + +该代码定义了一个 Scala 3 “main” 方法，该方法在运行时打印 `"Hello, world"`。 + +现在，使用 `sbt run` 命令编译并运行您的项目： + +```bash +$ sbt run + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition +[info] loading settings for project root from build.sbt ... +[info] Compiling 1 Scala source ... +[info] running helloWorld +Hello, world +[success] Total time: 4 s +``` + +第一次运行 `sbt` 时，它会下载所需的所有内容，这可能需要一些时间才能运行，但之后它会变得更快。 + +此外，一旦你完成了这第一步，你会发现以交互方式运行 sbt 会快得多。 +为此，首先单独运行 `sbt` 命令： + +```bash +$ sbt + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition ... +[info] loading settings for project root from build.sbt ... +[info] sbt server started at + local:///${HOME}/.sbt/1.0/server/7d26bae822c36a31071c/sock +sbt:hello-world> _ +``` + +然后在这个 sbt shell 中，执行它的 `run` 命令： + +```` +sbt:hello-world> run + +[info] running helloWorld +Hello, world +[success] Total time: 0 s +```` + +这要快得多。 + +如果您在 sbt 命令提示符下键入 `help`，您将看到可以运行的其他命令的列表。 +但现在，只需键入 `exit`（或按 `CTRL-D`）离开 sbt shell。 + +### 使用项目模板 + +手动创建项目结构可能很乏味。谢天谢地，sbt 可以基于模板为你创建项目。 + +要从模板创建 Scala 3 项目，请在 shell 中运行以下命令： + +~~~ +$ sbt new scala/scala3.g8 +~~~ + +Sbt 将加载模板，提出一些问题，并在子目录中创建项目文件： + +~~~ +$ tree scala-3-project-template +scala-3-project-template +├── build.sbt +├── project +│ └── build.properties +├── README.md +└── src + ├── main + │ └── scala + │ └── Main.scala + └── test + └── scala + └── Test1.scala +~~~ + +> 如果要创建与 Scala 2 交叉编译的 Scala 3 项目，请使用模板 `scala/scala3-cross.g8`： +> +> ~~~ +> $ sbt new scala/scala3-cross.g8 +> ~~~ + +在 [sbt 文档](https://www.scala-sbt.org/1.x/docs/sbt-new-and-Templates.html#sbt+new+) 中了解有关 `sbt new` 和项目模板的更多信息。 + +### Scala 的其他构建工具 + +虽然 sbt 被广泛使用，但您还可以使用其他工具来构建 Scala 项目： + +- [ant](https://ant.apache.org/) +- [Gradle](https://gradle.org/) +- [Maven](https://maven.apache.org/) +- [mill](https://com-lihaoyi.github.io/mill/) + +#### Coursier + +在相关说明中，[Coursier](https://get-coursier.io/docs/overview) 是一个“依赖解析器”，在功能上类似于 Maven 和 Ivy。 +它是用 Scala 从头开始编写的，“包含函数式编程原则”，并且可以并行下载工件以实现快速下载。 +sbt 使用它来处理大多数依赖关系解析，并且作为一个命令行工具，它可以用于在您的系统上轻松安装 sbt、Java 和 Scala 等工具，如我们的 [Getting Started][getting_started] 页面所示。 + +来自 `launch` 网页的这个示例显示了 `cs launch` 命令可用于从依赖项启动应用程序： + +```scala +$ cs launch org.scalameta::scalafmt-cli:2.4.2 -- --help +scalafmt 2.4.2 +Usage: scalafmt [options] [...] + + -h, --help prints this usage text + -v, --version print version + more ... +``` + +有关详细信息，请参阅 Coursier 的 [启动页面](https://get-coursier.io/docs/cli-launch)。 + +## 使用 sbt 和 ScalaTest + +[ScalaTest](https://www.scalatest.org) 是 Scala 项目的主要测试库之一。 +在本节中，您将看到创建使用 ScalaTest 的 Scala/sbt 项目所需的步骤。 + +### 1) 创建项目目录结构 + +与上一课一样，使用以下命令为名为 _HelloScalaTest_ 的项目创建一个 sbt 项目目录结构： + +```bash +$ mkdir HelloScalaTest +$ cd HelloScalaTest +$ mkdir -p src/{main,test}/scala +$ mkdir project +``` + +### 2) 创建 build.properties 和 build.sbt 文件 + +接下来，把下面这行代码用于在项目的 _project/_ 子目录中创建一个 _build.properties_ 文件： + +```text +sbt.version=1.10.11 +``` + +接下来，在项目的根目录中创建一个 _build.sbt_ 文件，其中包含以下内容： + +```scala +name := "HelloScalaTest" +version := "0.1" +scalaVersion := "{{site.scala-3-version}}" + +libraryDependencies ++= Seq( + "org.scalatest" %% "scalatest" % "3.2.19" % Test +) +``` + +该文件的前三行与第一个示例基本相同。 +`libraryDependencies` 行告诉 sbt 包含包含 ScalaTest 所需的依赖项（JAR 文件）。 + +> ScalaTest 文档一直很优秀，您始终可以在 [安装 ScalaTest](https://www.scalatest.org/install) 页面上找到有关这些行应该是什么样子的最新信息。 + +### 3) 创建一个 Scala 源代码文件 + +接下来，创建一个可用于演示 ScalaTest 的 Scala 程序。 +首先，在 _src/main/scala_ 下创建一个名为 _math_ 的目录： + +```bash +$ mkdir src/main/scala/math + ---- +``` + +然后，在该目录中，使用以下内容创建一个名为 _MathUtils.scala_ 的文件： + +```scala +package math + +object MathUtils: + def double(i: Int) = i * 2 +``` + +该方法提供了一种演示 ScalaTest 的简单方法。 + +{% comment %} +Because this project doesn’t have a `main` method, we don’t try to run it with `sbt run`; we just compile it with `sbt compile`: + +```` +$ sbt compile + +[info] welcome to sbt +[info] loading settings for project ... +[info] loading project definition ... +[info] loading settings for project ... +[info] Executing in batch mode. For better performance use sbt's shell +[success] Total time: 1 s +```` + +With that compiled, let’s create a ScalaTest file to test the `double` method. +{% endcomment %} + +### 4) 创建你的第一个 ScalaTest 测试 + +ScalaTest 非常灵活，并提供了几种不同的方式来编写测试。 +一个简单的入门方法是使用 ScalaTest `AnyFunSuite` 编写测试。 +首先，在 _src/test/scala_ 目录下创建一个名为 _math_ 的目录： + +```bash +$ mkdir src/test/scala/math + ---- +``` + +接下来，在该目录中创建一个名为 _MathUtilsTests.scala_ 的文件，其内容如下： + +```scala +package math + +import org.scalatest.funsuite.AnyFunSuite + +class MathUtilsTests extends AnyFunSuite: + + // test 1 + test("'double' should handle 0") { + val result = MathUtils.double(0) + assert(result == 0) + } + + // test 2 + test("'double' should handle 1") { + val result = MathUtils.double(1) + assert(result == 2) + } + + test("test with Int.MaxValue") (pending) + +end MathUtilsTests +``` + +此代码演示了 ScalaTest `AnyFunSuite` 方法。 +几个重要的点： + +- 你的测试类应该继承 `AnyFunSuite` +- 如图所示，您可以通过为每个 `test` 指定一个唯一的名称来创建测试 +- 在每个测试结束时，您应该调用 `assert` 来测试条件是否已满足 +- 当你知道你想写一个测试，但你现在不想写它时，将测试创建为“待定”，语法如上例所示 + +像这样使用 ScalaTest 类似于 JUnit，所以如果你是从 Java 转到 Scala 的，希望这看起来相似。 + +现在您可以使用 `sbt test` 命令运行这些测试。 +跳过前几行输出，结果如下所示： + +```` +sbt:HelloScalaTest> test + +[info] Compiling 1 Scala source ... +[info] MathUtilsTests: +[info] - 'double' should handle 0 +[info] - 'double' should handle 1 +[info] - test with Int.MaxValue (pending) +[info] Total number of tests run: 2 +[info] Suites: completed 1, aborted 0 +[info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 1 +[info] All tests passed. +[success] Total time: 1 s +```` + +如果一切正常，您将看到类似的输出。 +欢迎来到使用 sbt 和 ScalaTest 测试 Scala 应用程序的世界。 + +### 支持多种类型的测试 + +此示例演示了一种类似于 xUnit _测试驱动开发_(TDD) 样式测试的测试样式，并具有_行为驱动开发_(BDD) 样式的一些优点。 + +如前所述，ScalaTest 很灵活，您还可以用其它风格来编写测试，例如类似于 Ruby 的 RSpec 的风格。 +您还可以使用伪对象、基于属性的测试，并使用 ScalaTest 来测试 Scala.js 代码。 + +有关可用的不同测试风格的更多详细信息，请参阅 [ScalaTest 网站](https://www.scalatest.org) 上的用户指南。 + +## 从这往哪儿走 + +有关 sbt 和 ScalaTest 的更多信息，请参阅以下资源： + +- [sbt 文档](https://www.scala-sbt.org/1.x/docs/) +- [ScalaTest 网站](https://www.scalatest.org/) + + +[getting_started]: {{ site.baseurl }}/scala3/getting-started.html diff --git a/_zh-cn/overviews/scala3-book/tools-worksheets.md b/_zh-cn/overviews/scala3-book/tools-worksheets.md new file mode 100644 index 0000000000..214b744d8b --- /dev/null +++ b/_zh-cn/overviews/scala3-book/tools-worksheets.md @@ -0,0 +1,65 @@ +--- +title: worksheet +type: section +description: This section looks at worksheets, an alternative to Scala projects. +language: zh-cn +num: 71 +previous-page: tools-sbt +next-page: interacting-with-java + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +工作表是在保存时评估的 Scala 文件，并把每个表达式的结果 +显示在程序右侧的列中。工作表就像是加了激素的[REPL 会话][REPL session]，并且 +享受一流的编辑器支持：自动补全、超链接、交互式错误输入等。 +工作表使用扩展名 `.worksheet.sc` 。 + +下面，我们将展示如何在 IntelliJ 和 VS Code（带有 Metals 扩展）中使用工作表。 + +1. 打开一个 Scala 项目，或者创建一个。 + - 要在 IntelliJ 中创建项目，选择“File”->“New”->“Project...”， 在左侧栏中选择“Scala”， + 单击“下一步”设置项目名称和位置。 + - 要在 VS Code 中创建项目，请运行命令“Metals: New Scala project”，选择 + 种子 `scala/scala3.g8`，设置项目位置，在新的 VS Code 窗口中打开它，然后 + 导入其构建。 +1. 在 `src/main/scala/` 目录下创建一个名为 `hello.worksheet.sc` 的文件。 + - 在 IntelliJ 中，右键单击目录 `src/main/scala/`，然后选择“New”，然后 + 是“文件”。 + - 在 VS Code 中，右键单击目录`src/main/scala/`，然后选择“New File”。 +1. 在编辑器中粘贴以下内容： + ~~~ + println("Hello, world!") + + val x = 1 + x + x + ~~~ + +1. 评估工作表。 + - 在 IntelliJ 中，单击编辑器顶部的绿色箭头以评估工作表。 + - 在 VS Code 中，保存文件。 + + 您应该在右侧面板 (IntelliJ) 上看到每一行的评估结果，或者 + 作为注释（VS Code）。 + +![]({{ site.baseurl }}/resources/images/scala3-book/intellij-worksheet.png) + +在 IntelliJ 中评估的工作表。 + +![]({{ site.baseurl }}/resources/images/scala3-book/metals-worksheet.png) + +在 VS Code 中评估的工作表（带有 Metals 扩展）。 + +请注意，工作表将使用项目定义的 Scala 版本（通常在文件`build.sbt`中， +设置 `scalaVersion` 键）。 + +另请注意，工作表没有 [程序入口点][program entry point]。作为替代，顶级语句和表达式 +从上到下进行评估。 + + +[REPL session]: {% link _zh-cn/overviews/scala3-book/taste-repl.md %} +[program entry point]: {% link _zh-cn/overviews/scala3-book/methods-main-methods.md %} diff --git a/_zh-cn/overviews/scala3-book/types-adts-gadts.md b/_zh-cn/overviews/scala3-book/types-adts-gadts.md new file mode 100644 index 0000000000..4d1604e187 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-adts-gadts.md @@ -0,0 +1,213 @@ +--- +title: 代数数据类型 +type: section +description: This section introduces and demonstrates algebraic data types (ADTs) in Scala 3. +language: zh-cn +num: 53 +previous-page: types-union +next-page: types-variance + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +代数数据类型 (ADT) 可以使用 `enum` 构造创建，因此我们将在查看 ADT 之前简要回顾一下枚举。 + +## 枚举 + +_enumeration_ 用于定义由一组命名值组成的类型： + +```scala +enum Color: + case Red, Green, Blue +``` + +这可以看作是以下的简写： + +```scala +enum Color: + case Red extends Color + case Green extends Color + case Blue extends Color +``` + +#### 参数 + +枚举可以参数化： + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` + +这样，每个不同的变体都有一个值成员 `rgb`，它被分配了相应的值： + +```scala +println(Color.Green.rgb) // prints 65280 +``` + +#### 自定义 + +枚举也可以有自定义： + +```scala +enum Planet(mass: Double, radius: Double): + + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity + + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Venus extends Planet(4.869e+24, 6.0518e6) + case Earth extends Planet(5.976e+24, 6.37814e6) + // 5 or 6 more planets ... +``` + +像类和 `case` 类一样，你也可以为枚举定义一个伴生对象： + +```scala +object Planet: + def main(args: Array[String]) = + val earthWeight = args(0).toDouble + val mass = earthWeight / Earth.surfaceGravity + for (p <- values) + println(s"Your weight on $p is ${p.surfaceWeight(mass)}") +``` + +## 代数数据类型 (ADTs) + +`enum` 概念足够通用，既支持_代数数据类型_（ADT）和它的通用版本（GADT）。 +本示例展示了如何将 `Option` 类型表示为 ADT： + +```scala +enum Option[+T]: + case Some(x: T) + case None +``` + +这个例子创建了一个带有协变类型参数 `T` 的 `Option` 枚举，它由两种情况组成， `Some` 和 `None`。 +`Some` 是_参数化_的，它带有值参数 `x`；它是从 `Option` 继承的 `case` 类的简写。 +由于 `None` 没有参数化，它被视为普通的 `enum` 值。 + +前面示例中省略的 `extends` 子句也可以显式给出： + +```scala +enum Option[+T]: + case Some(x: T) extends Option[T] + case None extends Option[Nothing] +``` + +与普通的 `enum` 值一样，`enum` 的情况是在 `enum` 的伴生对象中定义的，因此它们被引用为 `Option.Some` 和 `Option.None`（除非定义是在导入时单独列出）： + +```scala +scala> Option.Some("hello") +val res1: t2.Option[String] = Some(hello) + +scala> Option.None +val res2: t2.Option[Nothing] = None +``` + +与其他枚举用途一样，ADT 可以定义更多的方法。 +例如，这里又是一个 `Option`，它的伴生对象中有一个 `isDefined` 方法和一个 `Option(...)` 构造函数： + +```scala +enum Option[+T]: + case Some(x: T) + case None + + def isDefined: Boolean = this match + case None => false + case Some(_) => true + +object Option: + def apply[T >: Null](x: T): Option[T] = + if (x == null) None else Some(x) +``` + +枚举和 ADT 共享相同的句法结构，因此它们可以 +被简单地视为光谱的两端，把二者混搭是完全可能的。 +例如，下面的代码给出了一个 +`Color` 的实现，可以使用三个枚举值或使用 +RGB 值的参数化情况： + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) + case Mix(mix: Int) extends Color(mix) +``` + +#### 递归枚举 + +到目前为止，我们定义的所有枚举都由值或样例类的不同变体组成。 +枚举也可以是递归的，如下面的自然数编码示例所示： + +```scala +enum Nat: + case Zero + case Succ(n: Nat) +``` + +例如，值 `Succ(Succ(Zero))` 表示一元编码中的数字 `2`。 +列表可以以非常相似的方式定义： + +```scala +enum List[+A]: + case Nil + case Cons(head: A, tail: List[A]) +``` + +## 广义代数数据类型 (GADT) + +上面的枚举表示法非常简洁，可以作为建模数据类型的完美起点。 +由于我们总是可以更明确，因此也可以表达更强大的类型：广义代数数据类型 (GADT)。 + +这是一个 GADT 示例，其中类型参数 (`T`) 指定存储在框中的内容： + +```scala +enum Box[T](contents: T): + case IntBox(n: Int) extends Box[Int](n) + case BoolBox(b: Boolean) extends Box[Boolean](b) +``` + +特定构造函数（`IntBox` 或 `BoolBox`）上的模式匹配可恢复类型信息： + +```scala +def extract[T](b: Box[T]): T = b match + case IntBox(n) => n + 1 + case BoolBox(b) => !b +``` + +只有在第一种情况下返回一个 `Int` 才是安全的，因为我们从 pattern 匹配输入是一个“IntBox”。 + +## 去除语法糖的枚举 + +_从概念上讲_，枚举可以被认为是定义一个密封类及其伴生对象。 +让我们看看上面的 `Color` 枚举的无语法糖版本： + +```scala +sealed abstract class Color(val rgb: Int) extends scala.reflect.Enum +object Color: + case object Red extends Color(0xFF0000) { def ordinal = 0 } + case object Green extends Color(0x00FF00) { def ordinal = 1 } + case object Blue extends Color(0x0000FF) { def ordinal = 2 } + case class Mix(mix: Int) extends Color(mix) { def ordinal = 3 } + + def fromOrdinal(ordinal: Int): Color = ordinal match + case 0 => Red + case 1 => Green + case 2 => Blue + case _ => throw new NoSuchElementException(ordinal.toString) +``` + +请注意，上面的去除语法糖被简化了，我们故意省略了[一些细节][desugar-enums]。 + +虽然枚举可以使用其他构造手动编码，但使用枚举更简洁，并且还附带了一些额外的实用程序（例如 `fromOrdinal` 方法）。 + +[desugar-enums]: {{ site.scala3ref }}/enums/desugarEnums.html diff --git a/_zh-cn/overviews/scala3-book/types-dependent-function.md b/_zh-cn/overviews/scala3-book/types-dependent-function.md new file mode 100644 index 0000000000..37084f1647 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-dependent-function.md @@ -0,0 +1,175 @@ +--- +title: 依赖函数类型 +type: section +description: This section introduces and demonstrates dependent function types in Scala 3. +language: zh-cn +num: 57 +previous-page: types-structural +next-page: types-others + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +*依赖函数类型*描述函数类型，其中结果类型可能取决于函数的参数值。 +依赖类型和依赖函数类型的概念更高级，您通常只会在设计自己的库或使用高级库时遇到它。 + +## 依赖方法类型 + +让我们考虑以下可以存储不同类型值的异构数据库示例。 +键包含有关相应值的类型的信息： + +```scala +trait Key { type Value } + +trait DB { + def get(k: Key): Option[k.Value] // a dependent method +} +``` + +给定一个键，`get` 方法允许我们访问地图并可能返回类型为 `k.Value` 的存储值。 +我们可以将这个_路径依赖类型_解读为：“根据参数 `k` 的具体类型，我们返回一个匹配值”。 + +例如，我们可以有以下键： + +```scala +object Name extends Key { type Value = String } +object Age extends Key { type Value = Int } +``` + +以下对方法 `get` 的调用现在将键入检查： + +```scala +val db: DB = ... +val res1: Option[String] = db.get(Name) +val res2: Option[Int] = db.get(Age) +``` + +调用方法 `db.get(Name)` 返回一个 `Option[String]` 类型的值，而调用 `db.get(Age)` 返回一个 `Option[Int]` 类型的值。 +返回类型_依赖_于传递给 `get` 的参数的具体类型---因此名称为_依赖类型_。 + +## 依赖函数类型 + +如上所示，Scala 2 已经支持依赖方法类型。 +但是，创建 `DB` 类型的值非常麻烦： + +```scala +// a user of a DB +def user(db: DB): Unit = + db.get(Name) ... db.get(Age) + +// creating an instance of the DB and passing it to `user` +user(new DB { + def get(k: Key): Option[k.Value] = ... // implementation of DB +}) +``` + +我们需要手动创建一个匿名的 `DB` 内部类，实现 `get` 方法。 +对于依赖于创建许多不同的 `DB` 实例的代码，这是非常乏味的。 + + `DB` 只有一个抽象方法 `get` 。 +如果我们可以使用 lambda 语法，那不是很好吗？ + +```scala +user { k => + ... // implementation of DB +``` + +事实上，现在这在 Scala 3 中是可能的！我们可以将 `DB` 定义为_依赖函数类型_： + +```scala +type DB = (k: Key) => Option[k.Value] +// ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +// A dependent function type +``` + +鉴于 `DB` 的这个定义，上面对 `user` 类型的调用按原样检查。 + +您可以在 [参考文档][ref] 中阅读有关依赖函数类型内部结构的更多信息。 + +## 案例研究：数值表达式 + +假设我们要定义一个抽象数字内部表示的模块。 +例如，这对于实现用于自动派生的库很有用。 + +我们首先为数字定义我们的模块： + +```scala +trait Nums: + // the type of numbers is left abstract + type Num + + // some operations on numbers + def lit(d: Double): Num + def add(l: Num, r: Num): Num + def mul(l: Num, r: Num): Num +``` + +> 我们省略了 `Nums` 的具体实现，但作为练习，您可以通过分配 `type Num = Double` 来实现 `Nums` 并相应地实现方法。 + +使用我们的数字抽象的程序现在具有以下类型： + +```scala +type Prog = (n: Nums) => n.Num => n.Num + +val ex: Prog = nums => x => nums.add(nums.lit(0.8), x) +``` + +计算诸如 `ex` 之类的程序的导数的函数的类型是： + +```scala +def derivative(input: Prog): Double +``` + +鉴于依赖函数类型的便利，用不同的程序调用这个函数非常方便： + +```scala +derivative { nums => x => x } +derivative { nums => x => nums.add(nums.lit(0.8), x) } +// ... +``` + +回想一下，上面编码中的相同程序将是： + +```scala +derivative(new Prog { + def apply(nums: Nums)(x: nums.Num): nums.Num = x +}) +derivative(new Prog { + def apply(nums: Nums)(x: nums.Num): nums.Num = nums.add(nums.lit(0.8), x) +}) +// ... +``` + +#### 上下文组合函数 + +扩展方法、[上下文函数][ctx-fun]和依赖函数的组合为库设计者提供了强大的工具。 +例如，我们可以从上面优化我们的库，如下所示： + +```scala +trait NumsDSL extends Nums: + extension (x: Num) + def +(y: Num) = add(x, y) + def *(y: Num) = mul(x, y) + +def const(d: Double)(using n: Nums): n.Num = n.lit(d) + +type Prog = (n: NumsDSL) ?=> n.Num => n.Num +// ^^^ +// prog is now a context function that implicitly +// assumes a NumsDSL in the calling context + +def derivative(input: Prog): Double = ... + +// notice how we do not need to mention Nums in the examples below? +derivative { x => const(1.0) + x } +derivative { x => x * x + const(2.0) } +// ... +``` + + +[ref]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[ctx-fun]: {{ site.scala3ref }}/contextual/context-functions.html diff --git a/_zh-cn/overviews/scala3-book/types-generics.md b/_zh-cn/overviews/scala3-book/types-generics.md new file mode 100644 index 0000000000..cdea2a2c4c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-generics.md @@ -0,0 +1,91 @@ +--- +title: 泛型 +type: section +description: This section introduces and demonstrates generics in Scala 3. +language: zh-cn +num: 50 +previous-page: types-inferred +next-page: types-intersection + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +泛型类（或 traits）把在方括号 `[...]` 中的类型作为_参数_进行调用。 +Scala 约定是使用单个字母（如 `A`）来命名这些类型参数。 +然后当需要时，该类型可以在类中用于方法实例参数，或返回类型： + +{% tabs stack class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +// here we declare the type parameter A +// v +class Stack[A] { + private var elements: List[A] = Nil + // ^ + // Here we refer to the type parameter + // v + def push(x: A): Unit = + elements = elements.prepended(x) + def peek: A = elements.head + def pop(): A = { + val currentTop = peek + elements = elements.tail + currentTop + } +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +// here we declare the type parameter A +// v +class Stack[A]: + private var elements: List[A] = Nil + // ^ + // Here we refer to the type parameter + // v + def push(x: A): Unit = { elements = elements.prepended(x) } + def peek: A = elements.head + def pop(): A = + val currentTop = peek + elements = elements.tail + currentTop +``` +{% endtab %} +{% endtabs %} + +`Stack` 类的这个实现采用任何类型作为参数。 +泛型的美妙之处在于您现在可以创建一个 `Stack[Int]`、`Stack[String]` 等，允许您将 `Stack` 的实现重复用于任意元素类型。 + +这是创建和使用 `Stack[Int]` 的方式： + +{% tabs stack-usage class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val stack = new Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val stack = Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 +``` +{% endtab %} +{% endtabs %} + +> 有关如何用泛型类型表达可变的详细信息，请参阅[型变（Variance）部分][variance]。 + +[variance]: {% link _zh-cn/overviews/scala3-book/types-variance.md %} diff --git a/_zh-cn/overviews/scala3-book/types-inferred.md b/_zh-cn/overviews/scala3-book/types-inferred.md new file mode 100644 index 0000000000..aa6d3faf18 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-inferred.md @@ -0,0 +1,58 @@ +--- +title: 类型推断 +type: section +description: This section introduces and demonstrates inferred types in Scala 3 +language: zh-cn +num: 49 +previous-page: types-introduction +next-page: types-generics + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +与其他静态类型编程语言一样，在 Scala 中，您可以在创建新变量时_声明_类型： + +{% tabs xy %} +{% tab 'Scala 2 and 3' %} +```scala +val x: Int = 1 +val y: Double = 1 +``` +{% endtab %} +{% endtabs %} + +在这些示例中，类型分别_明确地_声明为 `Int` 和 `Double` 。 +但是，在 Scala 中，您通常不必在定义值绑定器时声明类型： + +{% tabs abm %} +{% tab 'Scala 2 and 3' %} +```scala +val a = 1 +val b = List(1, 2, 3) +val m = Map(1 -> "one", 2 -> "two") +``` +{% endtab %} +{% endtabs %} + +当你这样做时，Scala _推断_类型，如下面的 REPL 交互所示： + +{% tabs abm2 %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val a = 1 +val a: Int = 1 + +scala> val b = List(1, 2, 3) +val b: List[Int] = List(1, 2, 3) + +scala> val m = Map(1 -> "one", 2 -> "two") +val m: Map[Int, String] = Map(1 -> one, 2 -> two) +``` +{% endtab %} +{% endtabs %} + +事实上，大多数变量都是这样定义的，而 Scala 自动推断类型的能力是使它_感觉_像一种动态类型语言的一个特性。 diff --git a/_zh-cn/overviews/scala3-book/types-intersection.md b/_zh-cn/overviews/scala3-book/types-intersection.md new file mode 100644 index 0000000000..db1d250a4c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-intersection.md @@ -0,0 +1,64 @@ +--- +title: 相交类型 +type: section +description: This section introduces and demonstrates intersection types in Scala 3. +language: zh-cn +num: 51 +previous-page: types-generics +next-page: types-union + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- +Scala 3 only + +用于类型，`&` 运算符创建一个所谓的_相交类型_。 +`A & B` 类型表示同时是 `A` 类型和 `B` 类型**两者**的值。 +例如，以下示例使用相交类型 `Resettable & Growable[String]`： + +{% tabs intersection-reset-grow %} +{% tab 'Scala 3 Only' %} +```scala +trait Resettable: + def reset(): Unit + +trait Growable[A]: + def add(a: A): Unit + +def f(x: Resettable & Growable[String]): Unit = + x.reset() + x.add("first") +``` +{% endtab %} +{% endtabs %} + +在本例中的方法 `f` 中，参数 `x` 必须*同时*既是 `Resettable` 也是 `Growable[String]`。 + +相交类型 `A & B` 的_成员_既有 `A` 的所有成员，也有 `B` 的所有成员。 +因此，如图所示，`Resettable & Growable[String]` 具有成员方法 `reset` 和 `add`。 + +相交类型可用于_结构性_地描述需求。 +也就是说，在我们的示例 `f` 中，我们直接表示只要 `x` 是 `Resettable` 和 `Growable` 的子类型的任意值， 我们就感到满意。 +我们**不**需要创建一个_通用_的辅助 trait，如下所示： + +{% tabs normal-trait class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +trait Both[A] extends Resettable with Growable[A] +def f(x: Both[String]): Unit +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +trait Both[A] extends Resettable, Growable[A] +def f(x: Both[String]): Unit +``` +{% endtab %} +{% endtabs %} + +定义 `f` 的两种选择之间有一个重要区别：虽然两者都允许使用 `Both` 的实例调用 `f`，但只有前者允许传递属于 `Resettable` 和 `Growable[String]` 子类型的实例，后者 `Both[String]` _不允许_。 + +> 请注意，`&` 是_可交换的_：`A & B` 与 `B & A` 的类型相同。 diff --git a/_zh-cn/overviews/scala3-book/types-introduction.md b/_zh-cn/overviews/scala3-book/types-introduction.md new file mode 100644 index 0000000000..dfe1b6b790 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-introduction.md @@ -0,0 +1,61 @@ +--- +title: 类型和类型系统 +type: chapter +description: This chapter provides an introduction to Scala 3 types and the type system. +language: zh-cn +num: 48 +previous-page: fp-summary +next-page: types-inferred + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 是一种独特的语言，因为它是静态类型的，但通常_感觉_它灵活和动态。 +例如，由于类型推断，您可以编写这样的代码而无需显式指定变量类型： + +{% tabs hi %} +{% tab 'Scala 2 and 3' %} +```scala +val a = 1 +val b = 2.0 +val c = "Hi!" +``` +{% endtab %} +{% endtabs %} + +这使代码感觉是动态类型的。 +并且由于新特性，例如 Scala 3 中的 [联合类型][union-types]，您还可以编写如下代码，非常简洁地表达出期望哪些值作为参数，哪些值作为返回的类型： + +{% tabs union-example %} +{% tab 'Scala 3 Only' %} +```scala +def isTruthy(a: Boolean | Int | String): Boolean = ??? +def dogCatOrWhatever(): Dog | Plant | Car | Sun = ??? +``` +{% endtab %} +{% endtabs %} + +正如例子所暗示的，当使用联合类型时，这些类型不必共享一个公共层次结构，您仍然可以接受它们作为参数或从方法中返回它们。 + +如果您是应用程序开发人员，您将每天使用类型推断和每周使用泛型等功能。 +当您阅读 Scaladoc 中的类和方法时，您还需要对_可变的(variance)_有所了解。 +希望您会发现使用类型可以相当简单，而且使用类型可以为库开发人员提供了很多表达能力、灵活性和控制力。 + +## 类型的好处 + +静态类型的编程语言提供了许多好处，包括： + +- 帮助提供强大的 IDE 支持 +- 在编译时消除许多类的潜在错误 +- 协助重构 +- 提供强大的文档，因为它经过类型检查，所以不会过时 + +## Scala 类型系统的特性介绍 + +鉴于此简要介绍，以下部分将概述 Scala 类型系统的特性。 + +[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %} diff --git a/_zh-cn/overviews/scala3-book/types-opaque-types.md b/_zh-cn/overviews/scala3-book/types-opaque-types.md new file mode 100644 index 0000000000..c8ba8405f5 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-opaque-types.md @@ -0,0 +1,160 @@ +--- +title: 不透明类型 +type: section +description: This section introduces and demonstrates opaque types in Scala 3. +language: zh-cn +num: 55 +previous-page: types-variance +next-page: types-structural + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala 3 _不透明类型别名_提供没有任何**开销**的类型抽象。 + +## 抽象开销 + +假设我们要定义一个提供数字算术运算的模块，这些数字由它们的对数表示。 +当涉及的数值非常大或接近于零时，使用对数有利于提高精度。 + +把“常规”双精度值与存储为对数的值区分开来很重要，我们引入了一个类 `Logarithm`： + +```scala +class Logarithm(protected val underlying: Double): + def toDouble: Double = math.exp(underlying) + def + (that: Logarithm): Logarithm = + // here we use the apply method on the companion + Logarithm(this.toDouble + that.toDouble) + def * (that: Logarithm): Logarithm = + new Logarithm(this.underlying + that.underlying) + +object Logarithm: + def apply(d: Double): Logarithm = new Logarithm(math.log(d)) +``` + +伴生对象上的 apply 方法让我们可以创建 `Logarithm` 类型的值，我们可用如下方式使用： + +```scala +val l2 = Logarithm(2.0) +val l3 = Logarithm(3.0) +println((l2 * l3).toDouble) // prints 6.0 +println((l2 + l3).toDouble) // prints 4.999... +``` + +虽然 `Logarithm` 类为以这种特殊对数形式存储的 `Double` 值提供了一个很好的抽象，但它带来了严重的性能开销：对于每一个数学运算，我们需要提取基础值，然后将其再次包装在一个 `Logarithm` 的新实例中。 + +## 模块抽象 + +让我们考虑另一种实现相同库的方法。 +这次我们没有将 `Logarithm` 定义为一个类，而是使用_类型别名_来定义它。 +首先，我们定义模块的抽象接口： + +```scala +trait Logarithms: + + type Logarithm + + // operations on Logarithm + def add(x: Logarithm, y: Logarithm): Logarithm + def mul(x: Logarithm, y: Logarithm): Logarithm + + // functions to convert between Double and Logarithm + def make(d: Double): Logarithm + def extract(x: Logarithm): Double + + // extension methods to use `add` and `mul` as "methods" on Logarithm + extension (x: Logarithm) + def toDouble: Double = extract(x) + def + (y: Logarithm): Logarithm = add(x, y) + def * (y: Logarithm): Logarithm = mul(x, y) +``` + +现在，让我们通过说类型 `Logarithm` 等于 `Double` 来实现这个抽象接口： + +```scala +object LogarithmsImpl extends Logarithms: + + type Logarithm = Double + + // operations on Logarithm + def add(x: Logarithm, y: Logarithm): Logarithm = make(x.toDouble + y.toDouble) + def mul(x: Logarithm, y: Logarithm): Logarithm = x + y + + // functions to convert between Double and Logarithm + def make(d: Double): Logarithm = math.log(d) + def extract(x: Logarithm): Double = math.exp(x) +``` + +在 `LogarithmsImpl` 的实现中，等式 `Logarithm = Double` 允许我们实现各种方法。 + +#### 暴露抽象 + +但是，这种抽象有点暴露。 +我们必须确保_只_针对抽象接口 `Logarithms` 进行编程，并且永远不要直接使用 `LogarithmsImpl`。 +直接使用 `LogarithmsImpl` 会使等式 `Logarithm = Double` 对用户可见，用户可能会意外使用 `Double`，而实际上是需要 对数双精度。 +例如： + +```scala +import LogarithmsImpl.* +val l: Logarithm = make(1.0) +val d: Double = l // type checks AND leaks the equality! +``` + +必须将模块分离为抽象接口和实现可能很有用，但只为了隐藏 `Logarithm` 的实现细节，就需要付出很多努力。 +针对抽象模块 `Logarithm` 进行编程可能非常乏味，并且通常需要使用像路径依赖类型这样的高级特性，如下例所示： + +```scala +def someComputation(L: Logarithms)(init: L.Logarithm): L.Logarithm = ... +``` + +#### 装箱的开销 + +类型抽象，例如 `type Logarithm` [抹去](https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure) 到它们的界限（在我们的例子中是 `Any`）。 +也就是说，虽然我们不需要手动包装和解包 `Double` 值，但仍然会有一些与装箱原始类型 `Double` 相关的装箱开销。 + +## 不透明类型 + +我们可以简单地使用 Scala 3 中的不透明类型来实现类似的效果，而不是手动将我们的 `Logarithms` 组件拆分为抽象部分和具体实现： + +```scala +object Logarithms: +//vvvvvv this is the important difference! + opaque type Logarithm = Double + + object Logarithm: + def apply(d: Double): Logarithm = math.log(d) + + extension (x: Logarithm) + def toDouble: Double = math.exp(x) + def + (y: Logarithm): Logarithm = Logarithm(math.exp(x) + math.exp(y)) + def * (y: Logarithm): Logarithm = x + y +``` + +`Logarithm` 与 `Double` 相同的事实仅在定义 `Logarithm` 的范围内已知，在上面的示例中对应于对象 `Logarithms`。 +类型相等 `Logarithm = Double` 可用于实现方法（如 `*` 和 `toDouble`）。 + +然而，在模块之外， `Logarithm` 类型是完全封装的，或者说是“不透明的”。 对于 `Logarithm` 的用户来说，不可能发现 `Logarithm` 实际上是作为 `Double` 实现的： + +```scala +import Logarithms.* +val l2 = Logarithm(2.0) +val l3 = Logarithm(3.0) +println((l2 * l3).toDouble) // prints 6.0 +println((l2 + l3).toDouble) // prints 4.999... + +val d: Double = l2 // ERROR: Found Logarithm required Double +``` + +尽管我们抽象了 `Logarithm`，但抽象是免费的： +由于只有一种实现，在运行时对于像 `Double` 这样的原始类型将_没有装箱开销_。 + +### 不透明类型总结 + +不透明类型提供了对实现细节的合理抽象，而不会增加性能开销。 +如上图所示，不透明类型使用起来很方便，并且与 [扩展方法][extension] 功能很好地集成在一起。 + +[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} diff --git a/_zh-cn/overviews/scala3-book/types-others.md b/_zh-cn/overviews/scala3-book/types-others.md new file mode 100644 index 0000000000..eec6faada8 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-others.md @@ -0,0 +1,32 @@ +--- +title: 其他类型 +type: section +description: This section mentions other advanced types in Scala 3. +language: zh-cn +num: 58 +previous-page: types-dependent-function +next-page: ca-contextual-abstractions-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +Scala还有其他几种高级类型，本书中没有介绍，包括： + +- 类型 lambdas +- 匹配类型 +- 存在类型 +- 高等类型 +- 单例类型 +- 细化类型 +- 种类多态性 + +有关这些类型的更多详细信息，请参阅[参考文档][reference]。 +有关单例类型参见 Scala 3 规格中的[字面量类型](https://scala-lang.org/files/archive/spec/3.4/03-types.html#literal-types) 一节， +细化类型参见[细化类型](https://scala-lang.org/files/archive/spec/3.4/03-types.html) 一节。 + + +[reference]: {{ site.scala3ref }}/overview.html diff --git a/_zh-cn/overviews/scala3-book/types-structural.md b/_zh-cn/overviews/scala3-book/types-structural.md new file mode 100644 index 0000000000..4c12a87901 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-structural.md @@ -0,0 +1,110 @@ +--- +title: 结构化类型 +type: section +description: This section introduces and demonstrates structural types in Scala 3. +language: zh-cn +num: 56 +previous-page: types-opaque-types +next-page: types-dependent-function + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +{% comment %} +NOTE: It would be nice to simplify this more. +{% endcomment %} + + +一些用例，例如建模数据库访问，在静态类型语言中比在动态类型语言中更尴尬。 +使用动态类型语言，很自然地将行建模为记录或对象，并使用简单的点表示法选择条目，例如 `row.columnName`。 + +要在静态类型语言中获得相同的体验，需要为数据库操作产生的每个可能的行定义一个类——包括连接和投影产生的行——并设置一个方案以在行和代表它的类之间进行映射。 + +这需要大量样板文件，这导致开发人员将静态类型的优势换成更简单的方案，其中列名表示为字符串并传递给其他运算符，例如 `row.select("columnName")`。 +这种方法即便放弃了静态类型的优点，也仍然不如动态类型的版本自然。 + +在您希望在动态上下文中支持简单的点表示法而又不失静态类型优势的情况下，结构化类型会有所帮助。 +它们允许开发人员使用点表示法并配置应如何解析字段和方法。 + +## 例子 + +这是一个结构化类型 `Person` 的示例： + +```scala +class Record(elems: (String, Any)*) extends Selectable: + private val fields = elems.toMap + def selectDynamic(name: String): Any = fields(name) + +type Person = Record { + val name: String + val age: Int +} +``` + +`Person` 类型在其父类型 `Record` 中添加了一个_精细的改进_，它定义了 `name` 和 `age` 字段。 +我们精细的改进是_构造的_，因为 `name` 和 `age` 没有在父类型中定义。 +但是它们仍然作为 `Person` 类的成员存在。 +例如，以下程序将打印 `"Emma is 42 years old."`： + +```scala +val person = Record( + "name" -> "Emma", + "age" -> 42 +).asInstanceOf[Person] + +println(s"${person.name} is ${person.age} years old.") +``` + +本例中的父类型 `Record` 是一个通用类，可以在其 `elems` 参数中表示任意记录。 +该参数是一个序列，该序列的元素是 `String` 类型的标签和 `Any` 类型的值组成的对。 +当您将 `Person` 创建为 `Record` 时，您必须使用类型转换断言该记录定义了正确类型的正确字段。 +`Record` 本身的类型太弱了，所以编译器在没有用户帮助的情况下无法知道这一点。 +实际上，结构化类型与其底层通用表示之间的连接很可能由数据库层完成，因此最终用户没必要关注。 + +`Record` 扩展了标记 trait `scala.Selectable` 并定义了一个方法 `selectDynamic`，它将字段名称映射到其值。 +通过调用此方法来选择结构化类型成员。 +Scala 编译器把选择 `person.name` 和 `person.age` 翻译成： + +```scala +person.selectDynamic("name").asInstanceOf[String] +person.selectDynamic("age").asInstanceOf[Int] +``` + +## 第二个例子 + +为了强化您刚刚看到的内容，这里有另一个名为 `Book` 的结构化类型，它表示您可能从数据库中读取的一本书： + +```scala +type Book = Record { + val title: String + val author: String + val year: Int + val rating: Double +} +``` + +与 `Person` 一样，这是创建 `Book` 实例的方式： + +```scala +val book = Record( + "title" -> "The Catcher in the Rye", + "author" -> "J. D. Salinger", + "year" -> 1951, + "rating" -> 4.5 +).asInstanceOf[Book] +``` + +## 可选类 + +除了 `selectDynamic` 之外，`Selectable`类有时还会定义 `applyDynamic` 方法。 +然后可以使用它来翻译是函数调用的结构成员。 +因此，如果 `a` 是 `Selectable` 的一个实例，则像 `a.f(b, c)` 这样的结构调用将转换为： + +```scala +a.applyDynamic("f")(b, c) +``` + diff --git a/_zh-cn/overviews/scala3-book/types-union.md b/_zh-cn/overviews/scala3-book/types-union.md new file mode 100644 index 0000000000..4e1ca79242 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-union.md @@ -0,0 +1,111 @@ +--- +title: 联合类型 +type: section +description: This section introduces and demonstrates union types in Scala 3. +language: zh-cn +num: 52 +previous-page: types-intersection +next-page: types-adts-gadts + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +scala3: true +versionSpecific: true +--- + + +用于类型，`|` 操作符创建一个所谓的_联合类型_。 +类型 `A | B` 表示**要么是** `A` 类型的值，**要么是** `B` 类型的值。 + +在下面的例子中，`help` 方法接受一个名为 `id` 的联合类型 `Username | Password`，可以是 `Useername` 或 `Password`： + +```scala +case class Username(name: String) +case class Password(hash: Hash) + +def help(id: Username | Password) = + val user = id match + case Username(name) => lookupName(name) + case Password(hash) => lookupPassword(hash) + // more code here ... +``` + +我们通过使用模式匹配区分二者，从而实现 `help` 方法。 + +此代码是一种灵活且类型安全的解决方案。 +如果您尝试传入`Useername` 或 `Password` 以外的类型，编译器会将其标记为错误： + +```scala +help("hi") // error: Found: ("hi" : String) + // Required: Username | Password +``` + +如果您尝试将 `case` 添加到与 `Username` 或 `Password` 类型不匹配的 `match` 表达式中，也会出现错误： + +```scala +case 1.0 => ??? // ERROR: this line won’t compile +``` + +### 联合类型的替代方案 + +如图所示，联合类型可用于替代几种不同的类型，而不要求这些类型是定制类层次结构的一部分，也不需要显式包装。 + +#### 预先规划类层次结构 + +其他语言需要预先规划类层次结构，如下例所示： + +{% tabs pre-planning %} +{% tab 'Scala 2 and 3' %} +```scala +trait UsernameOrPassword +case class Username(name: String) extends UsernameOrPassword +case class Password(hash: Hash) extends UsernameOrPassword +def help(id: UsernameOrPassword) = ... +``` +{% endtab %} +{% endtabs %} + +预先计划不能很好地扩展，例如，API 用户的需求可能无法预见。 +此外，使用诸如 `UsernameOrPassword` 之类的标记 trait 使类型层次结构混乱也会使代码更难阅读。 + +#### 标记联合 + +另一种选择是定义一个单独的枚举类型，如： + +```scala +enum UsernameOrPassword: + case IsUsername(u: Username) + case IsPassword(p: Password) +``` + +枚举 `UsernameOrPassword` 表示 `Username` 和 `Password` 的 _标记_联合。 +但是，这种联合建模方式需要_显式包装和展开_，例如，`Username` **不是** `UsernameOrPassword` 的子类型。 + +### 联合类型推断 + +_仅当_明确给出这种类型时，编译器才会将联合类型分配给表达式。 +例如，给定这些值： + +```scala +val name = Username("Eve") // name: Username = Username(Eve) +val password = Password(123) // password: Password = Password(123) +``` + +这个 REPL 示例展示了在将变量绑定到 `if`/`else` 表达式的结果时如何使用联合类型： + +```` +scala> val a = if (true) name else password +val a: Object = Username(Eve) + +scala> val b: Password | Username = if (true) name else password +val b: Password | Username = Username(Eve) +```` + +`a` 的类型是 `Object`，它是 `Username` 和 `Password` 的超类型，但不是二者*最小*的超类型 `Password | Username`。 +如果你想要最小的超类型，你必须明确地给出它，就像对 `b` 所做的那样。 + +> 联合类型是交集类型的对偶。 +> 和具有交集类型的 `&` 一样，`|` 也是可交换的：`A | B` 与 `B | A` 是同一类型。 + diff --git a/_zh-cn/overviews/scala3-book/types-variance.md b/_zh-cn/overviews/scala3-book/types-variance.md new file mode 100644 index 0000000000..3c774c1d52 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/types-variance.md @@ -0,0 +1,250 @@ +--- +title: 型变 +type: section +description: This section introduces and demonstrates variance in Scala 3. +language: zh-cn +num: 54 +previous-page: types-adts-gadts +next-page: types-opaque-types + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +类型参数_型变_控制参数化类型（如类或 traits）的子类型。 + +为了解释型变，让我们假设以下类型定义： + +{% tabs types-variance-1 %} +{% tab 'Scala 2 and 3' %} +```scala +trait Item { def productNumber: String } +trait Buyable extends Item { def price: Int } +trait Book extends Buyable { def isbn: String } +``` +{% endtab %} +{% endtabs %} + +我们还假设以下参数化类型： + +{% tabs types-variance-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-2 %} +```scala +// an example of an invariant type +trait Pipeline[T] { + def process(t: T): T +} + +// an example of a covariant type +trait Producer[+T] { + def make: T +} + +// an example of a contravariant type +trait Consumer[-T] { + def take(t: T): Unit +} +``` +{% endtab %} + +{% tab 'Scala 3' for=types-variance-2 %} +```scala +// an example of an invariant type +trait Pipeline[T]: + def process(t: T): T + +// an example of a covariant type +trait Producer[+T]: + def make: T + +// an example of a contravariant type +trait Consumer[-T]: + def take(t: T): Unit +``` +{% endtab %} +{% endtabs %} + +一般来说，型变有三种模式： + +- **不变的**---默认值，写成 `Pipeline[T]` +- **协变**---用`+`注释，例如 `Producer[+T]` +- **逆变**---用`-`注释，如 `Consumer[-T]` + +我们现在将详细介绍此注释的含义以及我们使用它的原因。 + +### 不变类型 + +默认情况下，像 `Pipeline` 这样的类型在它们的类型参数中是不变的（本例中是 `T`）。 +这意味着像 `Pipeline[Item]`、`Pipeline[Buyable]` 和 `Pipeline[Book]` 这样的类型彼此之间_没有子类型关系_。 + +理所当然地！假设以下方法使用两个类型为`Pipeline[Buyable]` 的值，并根据价格将其参数 `b` 传递给其中一个： + +{% tabs types-variance-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-3 %} +```scala +def oneOf( + p1: Pipeline[Buyable], + p2: Pipeline[Buyable], + b: Buyable +): Buyable = { + val b1 = p1.process(b) + val b2 = p2.process(b) + if (b1.price < b2.price) + b1 + else + b2 + } +``` +{% endtab %} + +{% tab 'Scala 3' for=types-variance-3 %} +```scala +def oneOf( + p1: Pipeline[Buyable], + p2: Pipeline[Buyable], + b: Buyable +): Buyable = + val b1 = p1.process(b) + val b2 = p2.process(b) + if b1.price < b2.price then b1 else b2 +``` +{% endtab %} +{% endtabs %} + +现在，回想一下，我们的类型之间存在以下_子类型关系_： + +{% tabs types-variance-4 %} +{% tab 'Scala 2 and 3' %} +```scala +Book <: Buyable <: Item +``` +{% endtab %} +{% endtabs %} + +我们不能将 `Pipeline[Book]` 传递给 `oneOf` 方法，因为在其实现中，我们调用的 `p1` 和 `p2` 是 `Buyable` 类型的值。 +`Pipeline[Book]` 需要的是 `Book`，这可能会导致运行时错误。 + +我们不能传递一个 `Pipeline[Item]` 因为在它上面调用 `process` 只会保证返回一个 `Item`；但是，我们应该返回一个 `Buyable` 。 + +#### 为什么是不变的？ + +事实上，`Pipeline` 类型需要是不变的，因为它使用它的类型参数 `T` _既_作为参数类型，_又_作为返回类型。 +出于同样的原因，Scala 集合库中的某些类型——例如 `Array` 或 `Set` —— 也是_不变的_。 + +### 协变类型 + +与不变的 `Pipeline` 相比，`Producer` 类型通过在类型参数前面加上 `+` 前缀被标记为 **协变**。 +这是有效的，因为类型参数仅用于_返回的位置_。 + +将其标记为协变意味着当需要 `Producer[Buyable]` 时，我们可以传递（或返回）一个 `Producer[Book]`。 +事实上，这是合理的。 `Producer[Buyable].make` 的类型只承诺_返回_ `Buyable`。 +作为 `make` 的调用者，我们乐意接受作为 `Buyable` 的子类型的 `Book` 类型，---也就是说，它_至少_是一个 `Buyable`。 + +以下示例说明了这一点，其中函数 `makeTwo` 需要一个 `Producer[Buyable]`： + +{% tabs types-variance-5 %} +{% tab 'Scala 2 and 3' %} +```scala +def makeTwo(p: Producer[Buyable]): Int = + p.make.price + p.make.price +``` +{% endtab %} +{% endtabs %} + +通过书籍制作人是完全可以的： + +{% tabs types-variance-6 %} +{% tab 'Scala 2 and 3' %} +```scala +val bookProducer: Producer[Book] = ??? +makeTwo(bookProducer) +``` +{% endtab %} +{% endtabs %} + +在 `makeTwo` 中调用 `price` 对书籍仍然有效。 + +#### 不可变容器的协变类型 + +在处理不可变容器时，您会经常遇到协变类型，例如可以在标准库中找到的那些（例如 `List`、`Seq`、`Vector` 等）。 + +例如，`List` 和 `Vector` 大致定义为： + +{% tabs types-variance-7 %} +{% tab 'Scala 2 and 3' %} +```scala +class List[+A] ... +class Vector[+A] ... +``` +{% endtab %} +{% endtabs %} + +这样，您可以在需要 `List[Buyable]` 的地方使用 `List[Book]`。 +这在直觉上也是有道理的：如果您期望收藏可以购买的东西，那么给您收藏书籍应该没问题。 +在我们的示例中，它们有一个额外的 ISBN 方法，但您可以随意忽略这些额外的功能。 + +### 逆变类型 + +与标记为协变的类型 `Producer` 相比，类型 `Consumer` 通过在类型参数前加上 `-` 来标记为**逆变**。 +这是有效的，因为类型参数仅用于_参数位置_。 + +将其标记为逆变意味着如果我们想要 `Consumer[Buyable]` 时，可以传递（或返回） `Consumer[Item]`。 +也就是说，我们有子类型关系`Consumer[Item] <: Consumer[Buyable]`。 +请记住，对于类型 `Producer`，情况正好相反，我们有 `Producer[Buyable] <: Producer[Item]`。 + +事实上，这是合理的。 `Consumer[Item].take` 方法接受一个 `Item`。 +作为 `take` 的调用者，我们还可以提供 `Buyable`，它会被 `Consumer[Item]` 愉快地接受，因为 `Buyable` 是 `Item` 的一个子类型——也就是说，它_至少_是 `Item` 。 + +#### 消费者的逆变类型 + +逆变类型比协变类型少得多。 +在我们的示例中，您可以将它们视为“消费者”。你可能来的最重要的类型标记为逆变的 cross 是函数之一： + +{% tabs types-variance-8 class=tabs-scala-version %} +{% tab 'Scala 2' for=types-variance-8 %} +```scala +trait Function[-A, +B] { + def apply(a: A): B +} +``` +{% endtab %} + +{% tab 'Scala 3' for=types-variance-8 %} +```scala +trait Function[-A, +B]: + def apply(a: A): B +``` +{% endtab %} +{% endtabs %} + +它的参数类型 `A` 被标记为逆变的 `A` ——它消费 `A` 类型的值。 +相反，它的结果类型 `B` 被标记为协变——它产生 `B` 类型的值。 + +以下是一些示例，这些示例说明了由函数上可变注释引起的子类型关系： + +{% tabs types-variance-9 %} +{% tab 'Scala 2 and 3' %} +```scala +val f: Function[Buyable, Buyable] = b => b + +// OK to return a Buyable where a Item is expected +val g: Function[Buyable, Item] = f + +// OK to provide a Book where a Buyable is expected +val h: Function[Book, Buyable] = f +``` +{% endtab %} +{% endtabs %} + +## 概括 + +在本节中，我们遇到了三种不同的方差： + +- **生产者**通常是协变的，并用 `+` 标记它们的类型参数。 + 这也适用于不可变集合。 +- **消费者**通常是逆变的，并用 `-` 标记他们的类型参数。 +- **既是**生产者**又**是消费者的类型必须是不变的，并且不需要在其类型参数上进行任何标记。 + 像 `Array` 这样的可变集合就属于这一类。 diff --git a/_zh-cn/overviews/scala3-book/where-next.md b/_zh-cn/overviews/scala3-book/where-next.md new file mode 100644 index 0000000000..66c3afe639 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/where-next.md @@ -0,0 +1,20 @@ +--- +title: 下一步去哪 +type: chapter +description: Where to go next after reading the Scala Book +language: zh-cn +num: 76 +previous-page: scala-for-python-devs +next-page: + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +我们希望你能喜欢 Scala 编程语言的介绍，我们也希望你能分享一些这门语言的美丽之处。 + +如果你继续用 Scala 工作，你可以在我们[引导和概览部分][overviews]发现更多细节。 + +[overviews]: {% link _overviews/index.md %} diff --git a/_zh-cn/overviews/scala3-book/why-scala-3.md b/_zh-cn/overviews/scala3-book/why-scala-3.md new file mode 100644 index 0000000000..b07b567fe7 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/why-scala-3.md @@ -0,0 +1,504 @@ +--- +title: 为什么是 Scala 3 ？ +type: chapter +description: This page describes the benefits of the Scala 3 programming language. +language: zh-cn +num: 3 +previous-page: scala-features +next-page: taste-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +{% comment %} +TODO: Is “Scala 3 Benefits” a better title? +NOTE: Could mention “grammar” as a way of showing that Scala isn’t a large language; see this slide: https://www.slideshare.net/Odersky/preparing-for-scala-3#13 +{% endcomment %} + +使用 Scala 有很多好处，特别是 Scala 3。 +很难列出 Scala 的每一个好处，但“前十名”列表可能看起来像这样： + +1. Scala 融合了函数式编程（FP）和面向对象编程（OOP） +2. Scala 是静态类型的语言，但通常感觉像一种动态类型语言。 +3. Scala 的语法简洁，但仍然可读;它通常被称为 _易于表达_ +4. Scala 2 中的 _Implicits_ 是一个定义特性，它们在 Scala 3 中得到了改进和简化。 +5. Scala 与 Java 无缝集成，因此您可以创建混合了 Scala 和 Java 代码的项目，Scala 代码可以轻松使用成千上万个现有的 Java 库 +6. Scala 可以在服务器上使用，通过 [Scala.js](https://www.scala-js.org)， Scala 也可以在浏览器中使用 +7. Scala 标准库具有数十种预构建的函数式方法，可节省您的时间，并大大减少编写自定义 `for` 循环和算法的需要 +8. Scala 内置了“最佳实践”，它支持不可变性，匿名函数，高阶函数，模式匹配，默认情况下无法扩展的类等 +9. Scala 生态系统提供世界上最现代化的 FP 库 +10. 强类型式系统 + +## 1) FP/OOP 融合 + +Scala 比任何其他语言都更支持 FP 和 OOP 范式的融合。 +正如 Martin Odersky 所说，Scala 的本质是在类型化环境中融合了函数式和面向对象编程，具有： + +- 函数用于编写逻辑 （局部） +- 对象用于构建模块化 （整体） + +模块化的一些最佳示例可能是标准库中的类。 +例如，`List` 被定义为一个类---从技术上讲，它是一个抽象类---并且像这样创建了一个新实例： + +{% tabs list %} +{% tab 'Scala 2 and 3' %} +```scala +val x = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +但是，在程序员看来是一个简单的 `List` 实际上是由几种特殊类型的组合构建的，包括名为`Iterable`, `Seq`, 和 `LinearSeq` 的 traits。 +这些类型同样由其他小型的模块化代码单元组成。 + +除了从一系列模块化 traits 构建/cases像 `List` 这样的类型之外，`List` API还包含数十种其他方法，其中许多是高阶函数： + +{% tabs list-methods %} +{% tab 'Scala 2 and 3' %} +```scala +val xs = List(1, 2, 3, 4, 5) + +xs.map(_ + 1) // List(2, 3, 4, 5, 6) +xs.filter(_ < 3) // List(1, 2) +xs.find(_ > 3) // Some(4) +xs.takeWhile(_ < 3) // List(1, 2) +``` +{% endtab %} +{% endtabs %} + +在这些示例中，无法修改列表中的值。 +`List` 类是不可变的，因此所有这些方法都返回新值，如每个注释中的数据所示。 + +## 2) 动态的感觉 + +Scala的 _类型推断_ 经常使语言感觉是动态类型的，即使它是静态类型的。 +对于变量声明，情况确实如此： + +{% tabs dynamic %} +{% tab 'Scala 2 and 3' %} +```scala +val a = 1 +val b = "Hello, world" +val c = List(1,2,3,4,5) +val stuff = ("fish", 42, 1_234.5) +``` +{% endtab %} +{% endtabs %} + +当把匿名函数传递给高阶函数时，情况也是如此： + +{% tabs dynamic-hof %} +{% tab 'Scala 2 and 3' %} +```scala +list.filter(_ < 4) +list.map(_ * 2) +list.filter(_ < 4) + .map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +还有定义方法的时候： + +{% tabs list-method %} +{% tab 'Scala 2 and 3' %} +```scala +def add(a: Int, b: Int) = a + b +``` +{% endtab %} +{% endtabs %} + +这在Scala 3中比以往任何时候都更加真实，例如在使用[union types][union-types] 时： + +{% tabs union %} +{% tab 'Scala 3 Only' %} +```scala +// union type parameter +def help(id: Username | Password) = + val user = id match + case Username(name) => lookupName(name) + case Password(hash) => lookupPassword(hash) + // more code here ... + +// union type value +val b: Password | Username = if (true) name else password +``` +{% endtab %} +{% endtabs %} + +## 3) 简洁的语法 + +Scala是一种 low ceremony，“简洁但仍然可读”的语言。例如，变量声明是简洁的： + +{% tabs concise %} +{% tab 'Scala 2 and 3' %} +```scala +val a = 1 +val b = "Hello, world" +val c = List(1,2,3) +``` +{% endtab %} +{% endtabs %} + +创建类型如traits, 类和枚举都很简洁： + +{% tabs enum %} +{% tab 'Scala 3 Only' %} +```scala +trait Tail: + def wagTail(): Unit + def stopTail(): Unit + +enum Topping: + case Cheese, Pepperoni, Sausage, Mushrooms, Onions + +class Dog extends Animal, Tail, Legs, RubberyNose + +case class Person( + firstName: String, + lastName: String, + age: Int +) +``` +{% endtab %} +{% endtabs %} + +简洁的高阶函数： + +{% tabs list-hof %} +{% tab 'Scala 2 and 3' %} +```scala +list.filter(_ < 4) +list.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +所有这些表达方式以及更多表达方式都很简洁，并且仍然非常易读：我们称之为 _富有表现力_。 + +## 4) 隐式，简化 + +Scala 2 中的隐式是一个主要明显的设计特征。 +它们代表了抽象上下文的基本方式，具有服务于各种用例的统一范式，其中包括： + +- 实现 [type classes]({% link _zh-cn/overviews/scala3-book/ca-type-classes.md %}) +- 建立背景 +- 依赖注入 +- 表达能力 + +从那以后，其他语言也采用了类似的概念，所有这些都是 _术语推断_ 核心思想的变体：给定一个类型，编译器合成一个具有该类型的“规范”术语。 + +虽然隐式是 Scala 2 中的一个定义特性，但它们的设计在 Scala 3 中得到了极大的改进： + +- 定义“given”值的方法只有一种 +- 只有一种方法可以引入隐式参数和参数 +- 有一种单独的方式来导入 givens，不允许它们隐藏在正常导入的海洋中 +- 只有一种定义隐式转换的方法，它被清楚地标记为这样，并且不需要特殊的语法 + +这些变化的好处包括： + +- 新设计避免了特性交叉，使语言更加一致 +- 它使隐式更容易学习和不容易滥用 +- 它极大地提高了 95% 使用隐式的 Scala 程序的清晰度 +- 它有可能以一种易于理解和友好的原则方式进行术语推断 + +这些功能在其他部分有详细描述，因此请参阅 [上下文抽象介绍][context] 和 [`given` 和 `using` 子句][given] 部分了解更多详细信息。 + +## 5) 与 Java 无缝集成 + +Scala/Java 交互在许多方面都是无缝的。 +例如： + +- 您可以使用 Scala 项目中可用的所有数千个 Java 库 +- Scala `String` 本质上是 Java `String`，添加了附加功能 +- Scala 无缝使用 Java 中 *java.time._* 包中的日期/时间类 + +您还可以在 Scala 中使用 Java 集合类，并为它们提供更多功能，Scala 包含方法，因此您可以将它们转换为 Scala 集合。 + +虽然几乎所有交互都是无缝的，但[“与 Java 交互”一章][java] 演示了如何更好地结合使用某些功能，包括如何使用： + +- Scala 中的 Java 集合 +- Scala 中的 Java `Optional` +- Scala 中的 Java 接口 +- Java 中的 Scala 集合 +- Java 中的 Scala `Option` +- Java 中的 Scala traits +- 在 Java 代码中引发异常的 Scala 方法 +- Java 中的 Scala 可变参数 + +有关这些功能的更多详细信息，请参见该章。 + +## 6) 客户 &服务器 + +Scala 可以通过非常棒的框架在服务器端使用： + +- [Play Framework](https://www.playframework.com) 可让您构建高度可扩展的服务器端应用程序和微服务 +- [Akka Actors](https://akka.io) 让你使用actor模型大大简化分布式和并发软件应用程序 + +Scala 也可以通过 [Scala.js 项目](https://www.scala-js.org) 在浏览器中使用，它是 JavaScript 的类型安全替代品。 +Scala.js 生态系统 [有几十个库](https://www.scala-js.org/libraries) 让您可以在浏览器中使用 React、Angular、jQuery 和许多其他 JavaScript 和 Scala 库。 + +除了这些工具之外，[Scala Native](https://github.com/scala-native/scala-native) 项目“是一个优化的提前编译器和专为 Scala 设计的轻量级托管运行时”。它允许您使用纯 Scala 代码构建“系统”风格的二进制可执行应用程序，还允许您使用较低级别的原语。 + +## 7) 标准库方法 + +您将很少需要再次编写自定义的 `for` 循环，因为 Scala 标准库中的数十种预构建函数方法既可以节省您的时间，又有助于使代码在不同应用程序之间更加一致。 + +下面的例子展示了一些内置的集合方法，除此之外还有很多。 +虽然这些都使用 `List` 类，但相同的方法适用于其他集合类，例如 `Seq`、`Vector`、`LazyList`、`Set`、`Map`、`Array` 和 `ArrayBuffer`。 + +这里有些例子： + +{% tabs list-more %} +{% tab 'Scala 2 and 3' %} +```scala +List.range(1, 3) // List(1, 2) +List.range(start = 1, end = 6, step = 2) // List(1, 3, 5) +List.fill(3)("foo") // List(foo, foo, foo) +List.tabulate(3)(n => n * n) // List(0, 1, 4) +List.tabulate(4)(n => n * n) // List(0, 1, 4, 9) + +val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10) +a.distinct // List(10, 20, 30, 40) +a.drop(2) // List(30, 40, 10) +a.dropRight(2) // List(10, 20, 30) +a.dropWhile(_ < 25) // List(30, 40, 10) +a.filter(_ < 25) // List(10, 20, 10) +a.filter(_ > 100) // List() +a.find(_ > 20) // Some(30) +a.head // 10 +a.headOption // Some(10) +a.init // List(10, 20, 30, 40) +a.intersect(List(19,20,21)) // List(20) +a.last // 10 +a.lastOption // Some(10) +a.map(_ * 2) // List(20, 40, 60, 80, 20) +a.slice(2, 4) // List(30, 40) +a.tail // List(20, 30, 40, 10) +a.take(3) // List(10, 20, 30) +a.takeRight(2) // List(40, 10) +a.takeWhile(_ < 30) // List(10, 20) +a.filter(_ < 30).map(_ * 10) // List(100, 200, 100) + +val fruits = List("apple", "pear") +fruits.map(_.toUpperCase) // List(APPLE, PEAR) +fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R) + +val nums = List(10, 5, 8, 1, 7) +nums.sorted // List(1, 5, 7, 8, 10) +nums.sortWith(_ < _) // List(1, 5, 7, 8, 10) +nums.sortWith(_ > _) // List(10, 8, 7, 5, 1) +``` +{% endtab %} +{% endtabs %} + +## 8) 内置最佳实践 + +Scala 习语以多种方式鼓励最佳实践。 +对于不可变性，我们鼓励您创建不可变的 `val` 声明： + +{% tabs val %} +{% tab 'Scala 2 and 3' %} +```scala +val a = 1 // 不可变变量 +``` +{% endtab %} +{% endtabs %} + +还鼓励您使用不可变集合类，例如 `List` 和 `Map`： + +{% tabs list-map %} +{% tab 'Scala 2 and 3' %} +```scala +val b = List(1,2,3) // List 是不可变的 +val c = Map(1 -> "one") // Map 是不可变的 +``` +{% endtab %} +{% endtabs %} + +样例类主要用于 [领域建模]({% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %})，它们的参数是不可变的： + +{% tabs case-class %} +{% tab 'Scala 2 and 3' %} +```scala +case class Person(name: String) +val p = Person("Michael Scott") +p.name // Michael Scott +p.name = "Joe" // 编译器错误（重新分配给 val 名称） +``` +{% endtab %} +{% endtabs %} + +如上一节所示，Scala 集合类支持高阶函数，您可以将方法（未显示）和匿名函数传递给它们： + +{% tabs higher-order %} +{% tab 'Scala 2 and 3' %} +```scala +a.dropWhile(_ < 25) +a.filter(_ < 25) +a.takeWhile(_ < 30) +a.filter(_ < 30).map(_ * 10) +nums.sortWith(_ < _) +nums.sortWith(_ > _) +``` +{% endtab %} +{% endtabs %} + +`match` 表达式让您可以使用模式匹配，它们确实是返回值的 _表达式_： + +{% tabs match class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val numAsString = i match { + case 1 | 3 | 5 | 7 | 9 => "odd" + case 2 | 4 | 6 | 8 | 10 => "even" + case _ => "too big" +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val numAsString = i match + case 1 | 3 | 5 | 7 | 9 => "odd" + case 2 | 4 | 6 | 8 | 10 => "even" + case _ => "too big" +``` +{% endtab %} +{% endtabs %} + +因为它们可以返回值，所以它们经常被用作方法的主体： + +{% tabs match-body class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def isTruthy(a: Matchable) = a match { + case 0 | "" => false + case _ => true +} +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" => false + case _ => true +``` +{% endtab %} +{% endtabs %} + +## 9) 生态系统库 + +用于函数式编程的 Scala 库，如 [Cats](https://typelevel.org/cats) 和 [Zio](https://zio.dev) 是 FP 社区中的前沿库。 +所有流行语，如高性能、类型安全、并发、异步、资源安全、可测试、函数式、模块化、二进制兼容、高效、副作用/有副作用等，都可以用于这些库。 + +我们可以在这里列出数百个库，但幸运的是它们都列在另一个位置：有关这些详细信息，请参阅 [“Awesome Scala” 列表](https://github.com/lauris/awesome-scala)。 + +## 10) 强类型系统 + +Scala 有一个强大的类型系统，它在 Scala 3 中得到了更多的改进。 +Scala 3 的目标很早就定义了，与类型系统相关的目标包括： + +- 简化 +- 消除不一致 +- 安全 +- 人体工程学 +- 性能 + +_简化_ 来自数十个更改和删除的特性。 +例如，从 Scala 2 中重载的 `implicit` 关键字到 Scala 3 中的术语 `given` 和 `using` 的变化使语言更加清晰，尤其是对于初学者来说。 + +_消除不一致_ 与Scala 3中的几十个[删除的特性][dropped]、[改变的特性][changed]和[增加的特性][add]有关。 +此类别中一些最重要的功能是： + +- 交集类型 +- 并集类型 +- 隐式函数类型 +- 依赖函数类型 +- trait 参数 +- 通用元组 + +{% comment %} +A list of types from the Dotty documentation: + +- Inferred types +- Generics +- Intersection types +- Union types +- Structural types +- Dependent function types +- Type classes +- Opaque types +- Variance +- Algebraic Data Types +- Wildcard arguments in types: ? replacing _ +- Type lambdas +- Match types +- Existential types +- Higher-kinded types +- Singleton types +- Refinement types +- Kind polymorphism +- Abstract type members and path-dependent types +- Dependent function types +- Bounds +{% endcomment %} + +_安全_ 与几个新的和改变的特性有关： + +- Multiversal equality +- Restricting implicit conversions +- Null safety +- Safe initialization + +_人体工程学_ 的好例子是枚举和扩展方法，它们以非常易读的方式添加到 Scala 3 中： + +{% tabs extension %} +{% tab 'Scala 3 Only' %} +```scala +// 枚举 +enum Color: + case Red, Green, Blue + +// 扩展方法 +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` +{% endtab %} +{% endtabs %} + +_性能_ 涉及几个方面。 +其中之一是 [不透明类型][opaque-types]。 +在 Scala 2 中，有几次尝试创建解决方案以与域驱动设计 (DDD) 实践相一致，即赋予值更有意义的类型。 +这些尝试包括： + +- 类型别名 +- 值类 +- 样例类 + +不幸的是，所有这些方法都有弱点，如 [_Opaque Types_ SIP](https://docs.scala-lang.org/sips/opaque-types.html) 中所述。 +相反，如 SIP 中所述，不透明类型的目标是“对这些包装器类型的操作不得在运行时产生任何额外开销，同时在编译时仍提供类型安全使用。” + +有关更多类型系统的详细信息，请参阅 [参考文档][reference]。 + +## 其他很棒的功能 + +Scala 有许多很棒的特性，选择十大列表可能是主观的。 +多项调查表明，不同的开发人员群体喜欢不同的特性。 + +[java]: {% link _zh-cn/overviews/scala3-book/interacting-with-java.md %} +[given]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %} +[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %} +[reference]: {{ site.scala3ref }} +[dropped]: {{ site.scala3ref }}/dropped-features +[changed]: {{ site.scala3ref }}/changed-features +[added]:{{ site.scala3ref }}/other-new-features + +[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %} +[opaque-types]: {% link _zh-cn/overviews/scala3-book/types-opaque-types.md %} diff --git a/_zh-cn/overviews/thanks.md b/_zh-cn/overviews/thanks.md index 16c526c2ad..e2fac4be7a 100644 --- a/_zh-cn/overviews/thanks.md +++ b/_zh-cn/overviews/thanks.md @@ -1,7 +1,8 @@ --- -layout: inner-page-no-masthead +layout: singlepage-overview language: zh-cn title: 致谢名单 +orphanTranslation: true --- 2013年10月份起，CSDN CODE开始组织志愿者翻译Scala官方文档。计划翻译的文档主要为Scala官网上overview部分的内容，包含以下部分： @@ -16,32 +17,32 @@ title: 致谢名单 - The Scala Actors API - Scala’s Collections Library -经过公开征集、筛选，我们最终组织了二十多位志愿者来进行此项翻译工作。我们并邀请到了国内Scala知名社区“Scala研学社”的两位老师**连城**、**尹绪森**来担任顾问和翻译校对的工作。在此向Scala研学社表示衷心的感谢！ +经过公开征集、筛选，我们最终组织了二十多位志愿者来进行此项翻译工作。我们并邀请到了国内Scala知名社区“Scala研学社”的两位老师**连城**、**尹绪森**来担任顾问和翻译校对的工作。在此向Scala研学社表示衷心的感谢！ -更要特别感谢的是在此次翻译工作中付出辛勤劳动的、广大的翻译志愿者朋友们，他们是： -（以下按姓氏拼音排序） -姓名 CSDN ID -陈骏 [jacty0219](https://code.csdn.net/jacty0219) -陈幸 Meteor2520 -董泉 dqsweet -何乃梧 [yuyi20112011](https://code.csdn.net/yuyi20112011) -黄越勇 aptweasel -赖正兴 laizx -李奕飞 fancylee -林君 a455642158 -刘国锋 [iceongrass](https://code.csdn.net/iceongrass) -吕浩志 lvhaozhi -聂雪珲 blueforgetmenot -潘栋华 -潘义文 Caidaoqq -王金岩 i9901028 -王雨施 -熊杰 [xiaoxiong345064855](https://code.csdn.net/xiaoxiong345064855) -杨志斌 qwewegfd -张冰 usen521 -张明明 [a775901421](https://code.csdn.net/a775901421) -张欣 kevenking@gmail.com +更要特别感谢的是在此次翻译工作中付出辛勤劳动的、广大的翻译志愿者朋友们，他们是： +（以下按姓氏拼音排序） +姓名 CSDN ID +陈骏 jacty0219 +陈幸 Meteor2520 +董泉 dqsweet +何乃梧 yuyi20112011 +黄越勇 aptweasel +赖正兴 laizx +李奕飞 fancylee +林君 a455642158 +刘国锋 iceongrass +吕浩志 lvhaozhi +聂雪珲 blueforgetmenot +潘栋华 +潘义文 Caidaoqq +王金岩 i9901028 +王雨施 +熊杰 xiaoxiong345064855 +杨志斌 qwewegfd +张冰 usen521 +张明明 a775901421 +张欣 kevenking@gmail.com 周逸灵 pastgift -感谢大家的辛勤劳动！ +感谢大家的辛勤劳动！ 我们已将经过最终校审的Scala文档中文版上传在此文档项目中，欢迎各位阅读、指正。如果您发现翻译稿件中有什么错误或问题，可以在此项目中给我们留言，或者直接派生、修改后提交合并请求给我们。谢谢！ diff --git a/_zh-cn/scala3/guides/tasty-overview.md b/_zh-cn/scala3/guides/tasty-overview.md new file mode 100644 index 0000000000..9ab7cc3124 --- /dev/null +++ b/_zh-cn/scala3/guides/tasty-overview.md @@ -0,0 +1,146 @@ +--- +layout: singlepage-overview +title: TASTy 概览 +--- +假定你创建了一个 Scala 3 源代码文件叫 _Hello.scala_: + +```scala +@main def hello = println("Hello, world") +``` + +然后用 `scalac` 编译了该文件： + +```bash +$ scalac Hello.scala +``` + +你会发现在 `scalac` 生成的其它文件结果中，有些文件是以 _.tasty_ 为扩展名： + +```bash +$ ls -1 +Hello$package$.class +Hello$package.class +Hello$package.tasty +Hello.scala +hello.class +hello.tasty +``` + +这自然地会引出一个问题，“什么是 tasty？” + +## 什么是 TASTy? + +TASTy 是从 _Typed Abstract Syntax Trees_ 这个术语的首字母缩写来的。它是 Scala 3 的高级交换格式，在本文档中，我们将它称为 _Tasty_ 。 + +首先要知道的是，Tasty 文件是由 `scalac` 编译器生成的，并且包含 _所有_ 有关源代码的信息，这些信息包括程序的语法结构，以及有关类型，位置甚至文档的 _所有_ 信息。Tasty 文件包含的信息比 _.class_ 文件多得多，后者是为在 JVM 上运行而生成的。（后面有详细介绍）。 + +在 Scala 3 中，编译流程像这样： + +```text + +-------------+ +-------------+ +-------------+ +$ scalac | Hello.scala | -> | Hello.tasty | -> | Hello.class | + +-------------+ +-------------+ +-------------+ + ^ ^ ^ + | | | + 你的代码 TASTy 文件 Class 文件 + 用于 scalac 用于 JVM + （包括完整信息） （不完整信息） +``` + +您可以通过使用 `-print-tasty` 标志在 _.tasty_ 文件上运行编译器，以人类可读的形式查看 _.tasty_ 文件的内容。 +您还可以使用 `-decompile` 标志以类似于 Scala 源代码的形式查看反编译的内容。 + +```bash +$ scalac -print-tasty hello.tasty +$ scalac -decompile hello.tasty +``` + +### The issue with _.class_ files + +由于象 [类型擦除][erasure] 等问题，_.class_ 文件实际上是代码的不完整表示形式。 +演示这一点的一种简单方法是使用 `List` 示例。 + +_类型擦除_ 意味着当你编写这样的Scala代码，并假定它是在JVM上运行时： + +```scala +val xs: List[Int] = List(1, 2, 3) +``` + +该代码被编译为需要与 JVM 兼容的 _.class_ 文件。由于该兼容性要求，该类文件中的代码 --- 您可以使用 `javap` 命令看到它，--- 最终看起来像这样： + +```java +public scala.collection.immutable.List xs(); +``` + +该 `javap` 命令输出显示了类文件中包含的内容，该内容是 Java 的表示形式。请注意，在此输出中，`xs` _不是_ 定义为 `List[Int]` ；它真正表示的是 `List[java.lang.Object]` 。为了使您的 Scala 代码与 JVM 配合使用，`Int` 类型已被擦除。 + +稍后，当您在 Scala 代码中访问 `List[Int]` 的元素时，像这样： + +```scala +val x = xs(0) +``` + +生成的类文件对此行代码进行强制转换操作，您可以将其想象成： + +``` +int x = (Int) xs.get(0) // Java-ish +val x = xs.get(0).asInstanceOf[Int] // more Scala-like +``` + +同样，这样做是为了兼容性，因此您的 Scala 代码可以在 JVM 上运行。但是，我们已经有的整数列表的信息在类文件中丢失了。 +当尝试使用已编译的库来编译 Scala 程序时，会带来问题。为此，我们需要的信息比类文件中通常可用的信息更多。 + +此讨论仅涵盖类型擦除的主题。对于 JVM 没有意识到的所有其他 Scala 结构，也存在类似的问题，包括 unions, intersections, 带有参数的 traits 以及更多 Scala 3 特性。 + +### TASTy to the Rescue + +因此，TASTy 格式不是像 _.class_ 文件那样没有原始类型的信息，或者只有公共 API（如Scala 2.13 “Pickle” 格式），而是在类型检查后存储完整的抽象语法树（AST）。存储整个 AST 有很多优点：它支持单独编译，针对不同的 JVM 版本重新编译，程序的静态分析等等。 + +### 重点 + +因此，这是本节的第一个要点：您在 Scala 代码中指定的类型在 _.class_ 文件中没有完全准确地表示。 + +第二个关键点是要了解 _编译时_ 和 _运行时_ 提供的信息之间存在差异： + +- 在**编译时**，当 `scalac` 读取和分析你的代码时，它知道 `xs` 是一个 `List[Int]` +- 当编译器将你的代码写入类文件时，它会写 `xs` 是 `List[Object]` ，并在访问 `xs` 的任何地方添加转换信息 +- 然后在**运行时** --- 你的代码在 JVM 中运行，--- JVM 不知道你的列表是一个 `List[Int]` + +对于 Scala 3 和 Tasty，这里有一个关于编译时的重要说明： + +- 当您编写使用其他 Scala 3 库的 Scala 3 代码时，`scalac` 不必再读取其 _.class_ 文件;它可以读取其 _.tasty_ 文件，如前所述，这些文件是代码的 _准确_ 表示形式。这对于在 Scala 2.13 和 Scala 3 之间实现单独编译和兼容性非常重要。 + +## Tasty 的好处 + +可以想象，拥有代码的完整表示形式具有[许多好处][benefits]： + +- 编译器使用它来支持单独的编译。 +- Scala 基于 _Language Server Protocol_ 的语言服务器使用它来支持超链接、命令补全、文档以及全局操作，如查找引用和重命名。 +- Tasty 为新一代[基于反射的宏][macros]奠定了良好的基础。 +- 优化器和分析器可以使用它进行深度代码分析和高级代码生成。 + +在相关的说明中，Scala 2.13.6 有一个 TASTy 读取器，Scala 3 编译器也可以读取2.13“Pickle”格式。Scala 3 迁移指南中的 [类路径兼容性页面][compatibility-ref] 解释了此交叉编译功能的好处。 + +## 更多信息 + +总之，Tasty 是 Scala 3 的高级交换格式，_.tasty_ 文件包含源代码的完整表示形式，从而带来了上一节中概述的好处。 + +有关更多详细信息，请参阅以下资源： + +- 在 [此视频](https://www.youtube.com/watch?v=YQmVrUdx8TU) 中，Scala 中心的Jamie Thompson 对 Tasty 的工作原理及其优势进行了详尽的讨论 +- [库作者的二进制兼容性][binary] 讨论二进制兼容性、源代码兼容性和 JVM 执行模型 +- [Scala 3 Transition 的前向兼容性](https://www.scala-lang.org/blog/2020/11/19/scala-3-forward-compat.html) 演示了在同一项目中使用 Scala 2.13 和 Scala 3 的技术 + +这些文章提供了有关 Scala 3 宏的更多信息： + +- [Scala 宏库](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html) +- [宏：Scala 3 的计划](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html) +- [Quotes Reflect 的参考文档][quotes-reflect] +- [宏的参考文档][macros] + +[benefits]: https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html +[erasure]: https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure +[binary]: {% link _overviews/tutorials/binary-compatibility-for-library-authors.md %} +[compatibility-ref]: {% link _overviews/scala3-migration/compatibility-classpath.md %} +[quotes-reflect]: {{ site.scala3ref }}/metaprogramming/reflection.html +[macros]: {{ site.scala3ref }}/metaprogramming/macros.html diff --git a/_zh-cn/scala3/new-in-scala3.md b/_zh-cn/scala3/new-in-scala3.md new file mode 100644 index 0000000000..5f82276635 --- /dev/null +++ b/_zh-cn/scala3/new-in-scala3.md @@ -0,0 +1,122 @@ +--- +layout: singlepage-overview +title: Scala 3 里的新东西 +scala3: true +--- +令人振奋的新版 Scala 3 带来了许多改进和新功能。在这里，我们为你提供最重要的变更的快速概述。如果你想深入挖掘，还有一些参考资料供你使用： + +- [Scala 3 Book]({% link _overviews/scala3-book/introduction.md %}) 面向刚接触 Scala 语言的开发人员。 +- [Syntax Summary][syntax-summary] 为您提供了新语法的正式描述。 +- [Language Reference][reference] 对 Scala 2 到 Scala 3 的变化做了详细说明。 +- [Migration Guide][migration] 为你提供了从 Scala 2 迁移到 Scala 3 的所有必要信息。 +- [Scala 3 Contributing Guide][contribution] Scala 3 贡献指南，更深入地探讨了编译器，包括修复问题的指南。 + +## Scala 3 里有什么新东西 +Scala 3 是对 Scala 语言的一次彻底改造。在其核心部分，类型系统的许多方面都被改变了，变得更有原则性。虽然这也带来了令人兴奋的新功能（比如联合类型），但首先意味着类型系统变得（甚至）不那么碍事了，例如[类型推断][type-inference]和 overload resolution 都得到了很大的改善。 + +### 新的和闪亮的：语法 +除了许多（小的）清理工作，Scala 3 的语法还提供了以下改进： + +- 用于控制结构的新“quiet”语法，如 `if`、`while` 和 `for` 。 ([new control syntax][syntax-control]) +- `new` 关键字是可选的 (_aka_ [creator applications][creator]) +- [Optional braces][syntax-indentation]：可选的大括号，支持不受干扰、缩进敏感的编程风格 +- [类型级通配符][syntax-wildcard] 从 `_` 更改为 `?`。 +- implicit（和它们的语法）已被[大量修订][implicits]。 + +### Opinionated: 上下文抽象 +Scala的一个基本核心概念是（在某种程度上仍然是）为用户提供一小部分强大的功能，这些功能可以被组合成巨大的（有时甚至是不可预见的）表达能力。例如，_implicit_ 的特性被用来模拟上下文抽象、表达类型级计算、模拟类型类、执行隐式强制、编码扩展方法等等。从这些用例中学习，Scala 3 采取了一种略微不同的方法，专注于 **意图** 而非 **机制**。Scala 3 没有提供一个非常强大的功能，而是提供了多个定制的语言功能，让程序员直接表达他们的意图。 + +- **Abtracting over contextual information**. [Using clauses][contextual-using] 允许程序员对调用上下文中的信息进行抽象，这些信息应该以隐式方式传递。作为对 Scala 2 implicits 的改进，可以按类型指定 using 子句，从而将函数签名从从未显式引用的术语变量名中解放出来。 + +- **Providing Type-class instances**. [Given instances][contextual-givens] 允许程序员定义某个类型的 _规范值_ 。这使得使用类型类的编程更加简单，而不会泄露实现细节。 + +- **Retroactively extending classes**. 在 Scala 2 中，扩展方法必须使用隐式转换或隐式类进行编码。相比之下，在 Scala 3 中，[extension methods][contextual-extension]现在直接内置于语言中，从而产生更好的错误消息和改进的类型推断。 + +- **Viewing one type as another**. [隐式转换][contextual-conversions]已经被重新设计为类型类`Conversion`的实例。 + +- **Higher-order contextual abstractions**. [context functions][contextual-functions]的 _全新_ 功能使上下文抽象成为第一等公民。它们是库开发人员的一个重要工具，允许表达简洁的特定领域语言。 + +- **Actionable feedback from the compiler**. 如果一个隐式参数不能被编译器解决，它现在提供了可能解决这个问题的[import suggestions](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html)。 + +### 表达真正的意思: 类型系统改进 +除了极大地改进了类型推断，Scala 3 类型系统还提供了许多新的功能，还为你提供了强大的工具来静态地表达类型中的不变量： + +- **Enumerations**. [枚举][enums]已经被重新设计，以便与样例类很好地融合，并形成表达[代数数据类型][enums-adts]的新标准。 + +- **Opaque Types**. 将实现细节隐藏在[opaque type aliases][types-opaque]的别名后面，而不需要在性能上付出代价! Opaque types 取代了值类，并允许你建立一个抽象的屏障，而不会造成额外的装箱开销。 + +- **Intersection and union types**. 将类型系统建立在新的基础上，引入了新的类型系统特性：[intersection types][types-intersection]的实例，如`A & B`，既是`A`的实例，也是`B`的实例；[union types][types-union]的实例，如`A | B`，是`A`或`B`的实例。这两种结构都允许程序员在继承层次结构之外灵活地表达类型约束。 + +- **Dependent function types**. Scala 2 已经允许返回类型依赖于（值）参数。在 Scala 3 中，现在可以对这种模式进行抽象，表达[dependent function types][types-dependent]。在类型`F = (e: Entry) => e.Key`中，结果类型取决于参数。 + +- **Polymorphic function types**. 与 dependent function types 一样，Scala 2 支持拥有类型参数的方法，但不允许程序员对这些方法进行抽象。在 Scala 3 中，像`[A] => List[A] => List[A]`这样的[polymorphic function types][types-polymorphic]可以抽象出除值参数外还接受 _类型参数_ 的函数。 + +- **Type lambdas**. 在 Scala 2 中需要用[编译器插件](https://github.com/typelevel/kind-projector)来表达的东西，现在在 Scala 3 中是原生支持的功能：类型lambdas是类型级别的函数，可以作为（高等类型的）类型参数传递，而不需要辅助类型定义。 + +- **Match types**. Scala 3 提供了对[matching on types][types-match]的直接支持，而不是使用隐式解析对类型级别的计算进行编码。将类型级计算整合到类型检查器中，可以改进错误信息，并消除对复杂编码的需求。 + +### Re-envisioned：面向对象的编程 +Scala 一直处于函数式编程和面向对象编程的前沿 -- 而 Scala 3 在这两个方向上都推动了边界的发展! 上述类型系统的变化和上下文抽象的重新设计使得 _函数式编程_ 比以前更容易。同时，以下的新特性使结构良好的 _面向对象设计_ 成为可能，并支持最佳实践。 + +- **Pass it on**. Trait 更接近于 class，现在也可以接受[参数][oo-trait-parameters]，使其作为模块化软件分解的工具更加强大。 + +- **Plan for extension**. 在面向对象的设计中，扩展那些不打算扩展的类是一个长期存在的问题。为了解决这个问题，[open classes][oo-open]要求库设计者 _明确地_ 将类标记为 open（开放的）。 + +- **Hide implementation details**. 实现功能的工具性的traits有时不应该是推断类型的一部分。在 Scala 3 中，这些traits可以被标记为[transparent][oo-transparent]，（在推断类型中）向用户隐藏继承信息。 + +- **Composition over inheritance**. 这句话经常被引用，但实现起来却很繁琐。Scala 3 的[export clauses][oo-export]则不然：与imports对应，export clauses 允许用户为对象的选定成员定义别名。 + +- **No more NPEs**. Scala 3 比以往任何时候都更安全：[explicit null][oo-explicit-null]将`null`移出了类型层次结构，帮助你静态地捕捉错误；[safe initialization][oo-safe-init]的额外检查可以检测对未初始化对象的访问。 + +### Batteries Included: 元编程 +Scala 2 中的宏只是一个实验性的功能，而 Scala 3 则为元编程提供了强大的工具库。[宏教程]({% link _overviews/scala3-macros/tutorial/index.md %})中包含了关于不同设施的详细信息。特别是，Scala 3 为元编程提供了以下功能： + +- **Inline**. [inline feature][meta-inline]允许在编译时化简值和方法。这个简单的功能已经涵盖了许多使用情况，同时也为更高级的功能提供了入口。 +- **Compile-time operations**. 包[`scala.compiletime`][meta-compiletime]中包含了额外的功能，可以用来实现内联方法。 +- **Quoted code blocks**. Scala 3为代码增加了[quasi-quotation][meta-quotes]的新功能，这为构建和分析代码提供了方便的高级接口。构建加一加一的代码就像`'{ 1 + 1 }`一样简单。 +- **Reflection API**. 对于更高级的用例，[quotes.reflect][meta-reflection]提供了更详细的控制来检查和生成程序树。 + +如果你想进一步了解 Scala 3 中的元编程，我们邀请你参阅我们的[教程][meta-tutorial]。 + +[enums]: {{ site.scala3ref }}/enums/enums.html +[enums-adts]: {{ site.scala3ref }}/enums/adts.html + +[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html +[types-union]: {{ site.scala3ref }}/new-types/union-types.html +[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html +[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html +[types-match]: {{ site.scala3ref }}/new-types/match-types.html +[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html + +[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html +[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html +[reference]: {{ site.scala3ref }}/overview.html +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %} +[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %} + +[implicits]: {{ site.scala3ref }}/contextual +[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html +[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html +[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html +[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html +[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html + +[syntax-summary]: {{ site.scala3ref }}/syntax.html +[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html +[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html +[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html + +[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %} +[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %} + +[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html +[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html +[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html +[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html +[oo-export]: {{ site.scala3ref }}/other-new-features/export.html diff --git a/_zh-cn/scala3/reference/README.md b/_zh-cn/scala3/reference/README.md new file mode 100644 index 0000000000..960554be5f --- /dev/null +++ b/_zh-cn/scala3/reference/README.md @@ -0,0 +1,5 @@ +https://docs.scala-lang.org/scala3/reference 的页面内容是从 [Scala 3 编译器库](https://github.com/scala/scala3) 生成的。 + +请到这里为 Scala 3 参考文档做贡献： + +https://github.com/scala/scala3/tree/main/docs/_docs diff --git a/_zh-cn/thanks.md b/_zh-cn/thanks.md index 16c526c2ad..e2fac4be7a 100644 --- a/_zh-cn/thanks.md +++ b/_zh-cn/thanks.md @@ -1,7 +1,8 @@ --- -layout: inner-page-no-masthead +layout: singlepage-overview language: zh-cn title: 致谢名单 +orphanTranslation: true --- 2013年10月份起，CSDN CODE开始组织志愿者翻译Scala官方文档。计划翻译的文档主要为Scala官网上overview部分的内容，包含以下部分： @@ -16,32 +17,32 @@ title: 致谢名单 - The Scala Actors API - Scala’s Collections Library -经过公开征集、筛选，我们最终组织了二十多位志愿者来进行此项翻译工作。我们并邀请到了国内Scala知名社区“Scala研学社”的两位老师**连城**、**尹绪森**来担任顾问和翻译校对的工作。在此向Scala研学社表示衷心的感谢！ +经过公开征集、筛选，我们最终组织了二十多位志愿者来进行此项翻译工作。我们并邀请到了国内Scala知名社区“Scala研学社”的两位老师**连城**、**尹绪森**来担任顾问和翻译校对的工作。在此向Scala研学社表示衷心的感谢！ -更要特别感谢的是在此次翻译工作中付出辛勤劳动的、广大的翻译志愿者朋友们，他们是： -（以下按姓氏拼音排序） -姓名 CSDN ID -陈骏 [jacty0219](https://code.csdn.net/jacty0219) -陈幸 Meteor2520 -董泉 dqsweet -何乃梧 [yuyi20112011](https://code.csdn.net/yuyi20112011) -黄越勇 aptweasel -赖正兴 laizx -李奕飞 fancylee -林君 a455642158 -刘国锋 [iceongrass](https://code.csdn.net/iceongrass) -吕浩志 lvhaozhi -聂雪珲 blueforgetmenot -潘栋华 -潘义文 Caidaoqq -王金岩 i9901028 -王雨施 -熊杰 [xiaoxiong345064855](https://code.csdn.net/xiaoxiong345064855) -杨志斌 qwewegfd -张冰 usen521 -张明明 [a775901421](https://code.csdn.net/a775901421) -张欣 kevenking@gmail.com +更要特别感谢的是在此次翻译工作中付出辛勤劳动的、广大的翻译志愿者朋友们，他们是： +（以下按姓氏拼音排序） +姓名 CSDN ID +陈骏 jacty0219 +陈幸 Meteor2520 +董泉 dqsweet +何乃梧 yuyi20112011 +黄越勇 aptweasel +赖正兴 laizx +李奕飞 fancylee +林君 a455642158 +刘国锋 iceongrass +吕浩志 lvhaozhi +聂雪珲 blueforgetmenot +潘栋华 +潘义文 Caidaoqq +王金岩 i9901028 +王雨施 +熊杰 xiaoxiong345064855 +杨志斌 qwewegfd +张冰 usen521 +张明明 a775901421 +张欣 kevenking@gmail.com 周逸灵 pastgift -感谢大家的辛勤劳动！ +感谢大家的辛勤劳动！ 我们已将经过最终校审的Scala文档中文版上传在此文档项目中，欢迎各位阅读、指正。如果您发现翻译稿件中有什么错误或问题，可以在此项目中给我们留言，或者直接派生、修改后提交合并请求给我们。谢谢！ diff --git a/_zh-cn/tour/abstract-type-members.md b/_zh-cn/tour/abstract-type-members.md new file mode 100644 index 0000000000..3fbbb8a487 --- /dev/null +++ b/_zh-cn/tour/abstract-type-members.md @@ -0,0 +1,72 @@ +--- +layout: tour +title: 抽象类型 +partof: scala-tour + +num: 21 + +language: zh-cn + +next-page: compound-types +previous-page: inner-classes +--- + +特质和抽象类可以包含一个抽象类型成员，意味着实际类型可由具体实现来确定。例如： + +```scala mdoc +trait Buffer { + type T + val element: T +} +``` +这里定义的抽象类型`T`是用来描述成员`element`的类型的。通过抽象类来扩展这个特质后，就可以添加一个类型上边界来让抽象类型`T`变得更加具体。 + +```scala mdoc +abstract class SeqBuffer extends Buffer { + type U + type T <: Seq[U] + def length = element.length +} +``` +注意这里是如何借助另外一个抽象类型`U`来限定类型上边界的。通过声明类型`T`只可以是`Seq[U]`的子类（其中U是一个新的抽象类型），这个`SeqBuffer`类就限定了缓冲区中存储的元素类型只能是序列。 + +含有抽象类型成员的特质或类（[classes](classes.html)）经常和匿名类的初始化一起使用。为了能够阐明问题，下面看一段程序，它处理一个涉及整型列表的序列缓冲区。 + +```scala mdoc +abstract class IntSeqBuffer extends SeqBuffer { + type U = Int +} + + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer { + type T = List[U] + val element = List(elem1, elem2) + } +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +这里的工厂方法`newIntSeqBuf`使用了`IntSeqBuf`的匿名类实现方式，其类型`T`被设置成了`List[Int]`。 + +把抽象类型成员转成类的类型参数或者反过来，也是可行的。如下面这个版本只用了类的类型参数来转换上面的代码： + +```scala mdoc:nest +abstract class Buffer[+T] { + val element: T +} +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T] { + def length = element.length +} + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]] { + val element = List(e1, e2) + } + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` + +需要注意的是为了隐藏从方法`newIntSeqBuf`返回的对象的具体序列实现的类型，这里的[型变标号](variances.html)（`+T <: Seq[U]`）是必不可少的。此外要说明的是，有些情况下用类型参数替换抽象类型是行不通的。 diff --git a/_zh-cn/tour/abstract-types.md b/_zh-cn/tour/abstract-types.md deleted file mode 100644 index 6fe6dcdf04..0000000000 --- a/_zh-cn/tour/abstract-types.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: tour -title: Abstract Types - -discourse: false - -partof: scala-tour - -num: 21 - -language: zh-cn - -next-page: compound-types -previous-page: inner-classes ---- diff --git a/_zh-cn/tour/annotations.md b/_zh-cn/tour/annotations.md index 3daf046e8d..56992045d6 100644 --- a/_zh-cn/tour/annotations.md +++ b/_zh-cn/tour/annotations.md @@ -1,15 +1,123 @@ --- layout: tour -title: Annotations - -discourse: false - +title: 注解 partof: scala-tour num: 30 language: zh-cn -next-page: default-parameter-values +next-page: packages-and-imports previous-page: by-name-parameters --- + +注解将元信息与定义相关联。 例如，方法之前的注解 `@deprecated` 会导致编译器在该方法被使用时打印警告信息。 +``` +object DeprecationDemo extends App { + @deprecated("deprecation message", "release # which deprecates method") + def hello = "hola" + + hello +} +``` +这个程序可以编译，但编译器将打印一个警告信息: "there was one deprecation warning"。 + +注解作用于其后的第一个定义或声明。 在定义和声明之前可以有多个注解。 这些注解的顺序并不重要。 + +## 确保编码正确性的注解 +如果不满足条件，某些注解实际上会导致编译失败。 例如，注解 `@tailrec` 确保方法是 [尾递归](https://en.wikipedia.org/wiki/Tail_call)。 尾递归可以保持内存需求不变。 以下是它在计算阶乘的方法中的用法： +```scala mdoc +import scala.annotation.tailrec + +def factorial(x: Int): Int = { + + @tailrec + def factorialHelper(x: Int, accumulator: Int): Int = { + if (x == 1) accumulator else factorialHelper(x - 1, accumulator * x) + } + factorialHelper(x, 1) +} +``` +方法 `factorialHelper` 使用注解 `@tailrec` 确保方法确实是尾递归的。 如果我们将方法 `factorialHelper` 的实现改为以下内容，它将编译失败： +``` +import scala.annotation.tailrec + +def factorial(x: Int): Int = { + @tailrec + def factorialHelper(x: Int): Int = { + if (x == 1) 1 else x * factorialHelper(x - 1) + } + factorialHelper(x) +} +``` +我们将得到一个错误信息 "Recursive call not in tail position". + + +## 影响代码生成的注解 +像 `@inline` 这样的注解会影响生成的代码(即你的 jar 文件可能与你没有使用注解时有不同的字节)。 内联表示在调用点插入被调用方法体中的代码。 生成的字节码更长，但有希望能运行得更快。 使用注解 `@inline` 并不能确保方法内联，当且仅当满足某些生成代码大小的启发式算法时，它才会触发编译器执行此操作。 + +### Java 注解 ### +在编写与 Java 互操作的 Scala 代码时，注解语法中存在一些差异需要注意。 +**注意：** 确保你在开启 `-target:jvm-1.8` 选项时使用 Java 注解。 + +Java 注解有用户自定义元数据的形式 ，参考 [annotations](https://docs.oracle.com/javase/tutorial/java/annotations/) 。 注解的一个关键特性是它们依赖于指定 name-value 对来初始化它们的元素。 例如，如果我们需要一个注解来跟踪某个类的来源，我们可以将其定义为 +``` +@interface Source { + public String URL(); + public String mail(); +} +``` + +并且按如下方式使用它 + +``` +@Source(URL = "https://coders.com/", + mail = "support@coders.com") +public class MyClass extends HisClass ... +``` + +Scala 中的注解应用看起来像构造函数调用，要实例化 Java 注解，必须使用命名参数： + +``` +@Source(URL = "https://coders.com/", + mail = "support@coders.com") +class MyScalaClass ... +``` + +如果注解只包含一个元素(没有默认值)，则此语法非常繁琐，因此，按照惯例，如果将元素名称指定为 `value`，则可以使用类似构造函数的语法在 Java 中应用它： +``` +@interface SourceURL { + public String value(); + public String mail() default ""; +} +``` + +然后按如下方式使用 + +``` +@SourceURL("https://coders.com/") +public class MyClass extends HisClass ... +``` + +在这种情况下， Scala 提供了相同的可能性 + +``` +@SourceURL("https://coders.com/") +class MyScalaClass ... +``` + +`mail` 元素在定义时设有默认值，因此我们不需要显式地为它提供值。 但是，如果我们需要显示地提供值，我们则不能在 Java 中混合使用这两种方式： + +``` +@SourceURL(value = "https://coders.com/", + mail = "support@coders.com") +public class MyClass extends HisClass ... +``` + +Scala 在这方面提供了更大的灵活性 + +``` +@SourceURL("https://coders.com/", + mail = "support@coders.com") + class MyScalaClass ... +``` diff --git a/_zh-cn/tour/automatic-closures.md b/_zh-cn/tour/automatic-closures.md deleted file mode 100644 index e7ac224a51..0000000000 --- a/_zh-cn/tour/automatic-closures.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -layout: tour -title: Automatic Closures - -discourse: false - -partof: scala-tour - -language: zh-cn ---- diff --git a/_zh-cn/tour/basics.md b/_zh-cn/tour/basics.md index dc6a06b0be..a7f9c3bf0a 100644 --- a/_zh-cn/tour/basics.md +++ b/_zh-cn/tour/basics.md @@ -1,9 +1,6 @@ --- layout: tour title: 基础 - -discourse: false - partof: scala-tour num: 2 @@ -11,46 +8,40 @@ language: zh-cn next-page: unified-types previous-page: tour-of-scala - -redirect_from: "/tutorials/tour/basics.html" --- 这篇文章涵盖了Scala的基础知识。 ## 在浏览器上尝试Scala -你可以在浏览器上使用ScalaFiddle运行Scala。 +你可以在浏览器上使用Scastie运行Scala。 -1. 打开[https://scalafiddle.io](https://scalafiddle.io)； +1. 打开[Scastie](https://scastie.scala-lang.org/)； 2. 在左侧窗格中粘贴`println("Hello, world!")`； 3. 点击"Run"按钮，输出将展现在右侧窗格中。 这是一种简单的、零设置的方法来实践Scala的代码片段。 -这篇文档中的大部分代码示例集成了ScalaFiddle，直接点击“Run"按钮即可运行。 - ## 表达式 表达式是可计算的语句。 -``` +```scala mdoc 1 + 1 ``` 你可以使用`println`来输出表达式的结果。 -{% scalafiddle %} -```tut +```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! println("Hello," + " world!") // Hello, world! ``` -{% endscalafiddle %} ### 常量（`Values`） 你可以使用`val`关键字来给表达式的结果命名。 -```tut +```scala mdoc val x = 1 + 1 println(x) // 2 ``` @@ -59,13 +50,13 @@ println(x) // 2 常量（`values`）不能重新被赋值。 -```tut:fail +```scala mdoc:fail x = 3 // This does not compile. ``` -常量（`values`）的类型可以被推断，或者你也可以显示地声明类型，例如： +常量（`values`）的类型可以被推断，或者你也可以显式地声明类型，例如： -```tut +```scala mdoc:nest val x: Int = 1 + 1 ``` @@ -75,15 +66,15 @@ val x: Int = 1 + 1 除了可以重新赋值，变量和常量类似。你可以使用`var`关键字来定义一个变量。 -```tut +```scala mdoc:nest var x = 1 + 1 x = 3 // This compiles because "x" is declared with the "var" keyword. println(x * x) // 9 ``` -和常量一样，你可以显示地声明类型： +和常量一样，你可以显式地声明类型： -```tut +```scala mdoc:nest var x: Int = 1 + 1 ``` @@ -94,7 +85,7 @@ var x: Int = 1 + 1 代码块中最后一个表达式的结果，也正是整个块的结果。 -```tut +```scala mdoc println({ val x = 1 + 1 x + 1 @@ -107,7 +98,7 @@ println({ 你可以定义一个匿名函数（即没有名字），来返回一个给定整数加一的结果。 -```tut +```scala mdoc (x: Int) => x + 1 ``` @@ -115,25 +106,21 @@ println({ 你也可以给函数命名。 -{% scalafiddle %} -```tut +```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -{% endscalafiddle %} 函数可带有多个参数。 -{% scalafiddle %} -```tut +```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} 或者不带参数。 -```tut +```scala mdoc val getTheAnswer = () => 42 println(getTheAnswer()) // 42 ``` @@ -144,27 +131,23 @@ println(getTheAnswer()) // 42 方法由`def`关键字定义。`def`后面跟着一个名字、参数列表、返回类型和方法体。 -{% scalafiddle %} -```tut +```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} 注意返回类型是怎么在函数列表和一个冒号`: Int`之后声明的。 方法可以接受多个参数列表。 -{% scalafiddle %} -```tut +```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -{% endscalafiddle %} 或者没有参数列表。 -```tut +```scala mdoc def name: String = System.getProperty("user.name") println("Hello, " + name + "!") ``` @@ -172,19 +155,22 @@ println("Hello, " + name + "!") 还有一些其他的区别，但是现在你可以认为方法就是类似于函数的东西。 方法也可以有多行的表达式。 -```tut + +```scala mdoc def getSquareString(input: Double): String = { val square = input * input square.toString } +println(getSquareString(2.5)) // 6.25 ``` + 方法体的最后一个表达式就是方法的返回值。（Scala中也有一个`return`关键字，但是很少使用） ## 类 你可以使用`class`关键字定义一个类，后面跟着它的名字和构造参数。 -```tut +```scala mdoc class Greeter(prefix: String, suffix: String) { def greet(name: String): Unit = println(prefix + name + suffix) @@ -194,7 +180,7 @@ class Greeter(prefix: String, suffix: String) { 你可以使用`new`关键字创建一个类的实例。 -```tut +```scala mdoc val greeter = new Greeter("Hello, ", "!") greeter.greet("Scala developer") // Hello, Scala developer! ``` @@ -205,13 +191,13 @@ greeter.greet("Scala developer") // Hello, Scala developer! Scala有一种特殊的类叫做样例类（case class）。默认情况下，样例类一般用于不可变对象，并且可作值比较。你可以使用`case class`关键字来定义样例类。 -```tut +```scala mdoc case class Point(x: Int, y: Int) ``` 你可以不用`new`关键字来实例化样例类。 -```tut +```scala mdoc val point = Point(1, 2) val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) @@ -219,17 +205,17 @@ val yetAnotherPoint = Point(2, 2) 并且它们的值可以进行比较。 -```tut +```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) and Point(1,2) are the same. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) and Point(2,2) are different. ``` @@ -241,7 +227,7 @@ if (point == yetAnotherPoint) { 你可以使用`object`关键字定义对象。 -```tut +```scala mdoc object IdFactory { private var counter = 0 def create(): Int = { @@ -253,7 +239,7 @@ object IdFactory { 你可以通过引用它的名字来访问一个对象。 -```tut +```scala mdoc val newId: Int = IdFactory.create() println(newId) // 1 val newerId: Int = IdFactory.create() @@ -268,7 +254,7 @@ println(newerId) // 2 你可以使用`trait`关键字定义特质。 -```tut +```scala mdoc:nest trait Greeter { def greet(name: String): Unit } @@ -276,8 +262,7 @@ trait Greeter { 特质也可以有默认的实现。 -{% scalafiddle %} -```tut +```scala mdoc:reset trait Greeter { def greet(name: String): Unit = println("Hello, " + name + "!") @@ -286,7 +271,7 @@ trait Greeter { 你可以使用`extends`关键字来继承特质，使用`override`关键字来覆盖默认的实现。 -```tut +```scala mdoc class DefaultGreeter extends Greeter class CustomizableGreeter(prefix: String, postfix: String) extends Greeter { @@ -301,7 +286,6 @@ greeter.greet("Scala developer") // Hello, Scala developer! val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` -{% endscalafiddle %} 这里，`DefaultGreeter`仅仅继承了一个特质，它还可以继承多个特质。 @@ -313,7 +297,7 @@ customGreeter.greet("Scala developer") // How are you, Scala developer? 通过使用对象，你可以如下所示来定义一个主方法。 -```tut +```scala mdoc object Main { def main(args: Array[String]): Unit = println("Hello, Scala developer!") diff --git a/_zh-cn/tour/by-name-parameters.md b/_zh-cn/tour/by-name-parameters.md index 5d55959e0c..ce3ad1f726 100644 --- a/_zh-cn/tour/by-name-parameters.md +++ b/_zh-cn/tour/by-name-parameters.md @@ -1,9 +1,6 @@ --- layout: tour -title: By-name Parameters - -discourse: false - +title: 传名参数 partof: scala-tour num: 29 @@ -13,3 +10,30 @@ language: zh-cn next-page: annotations previous-page: operators --- + +_传名参数_ 仅在被使用时触发实际参数的求值运算。 它们与 _传值参数_ 正好相反。 要将一个参数变为传名参数，只需在它的类型前加上 `=>`。 +```scala mdoc +def calculate(input: => Int) = input * 37 +``` +传名参数的优点是，如果它们在函数体中未被使用，则不会对它们进行求值。 另一方面，传值参数的优点是它们仅被计算一次。 +以下是我们如何实现一个 while 循环的例子： + +```scala mdoc +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if (condition) { + body + whileLoop(condition)(body) + } + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // prints 2 1 +``` +方法 `whileLoop` 使用多个参数列表来分别获取循环条件和循环体。 如果 `condition` 为 true，则执行 `body`，然后对 whileLoop 进行递归调用。 如果 `condition` 为 false，则永远不会计算 body，因为我们在 `body` 的类型前加上了 `=>`。 + +现在当我们传递 `i > 0` 作为我们的 `condition` 并且 `println(i); i-= 1` 作为 `body` 时，它表现得像许多语言中的标准 while 循环。 + +如果参数是计算密集型或长时间运行的代码块，如获取 URL，这种延迟计算参数直到它被使用时才计算的能力可以帮助提高性能。 diff --git a/_zh-cn/tour/case-classes.md b/_zh-cn/tour/case-classes.md index 949113281e..15a2dbf4cb 100644 --- a/_zh-cn/tour/case-classes.md +++ b/_zh-cn/tour/case-classes.md @@ -1,9 +1,6 @@ --- layout: tour -title: Case Classes - -discourse: false - +title: 样例类（Case Classes） partof: scala-tour num: 10 @@ -13,3 +10,48 @@ language: zh-cn next-page: pattern-matching previous-page: multiple-parameter-lists --- + +样例类（Case classes）和普通类差不多，只有几点关键差别，接下来的介绍将会涵盖这些差别。样例类非常适合用于不可变的数据。下一节将会介绍他们在[模式匹配](pattern-matching.html)中的应用。 + +## 定义一个样例类 +一个最简单的样例类定义由关键字`case class`，类名，参数列表（可为空）组成： +```scala mdoc +case class Book(isbn: String) + +val frankenstein = Book("978-0486282114") +``` +注意在实例化样例类`Book`时，并没有使用关键字`new`，这是因为样例类有一个默认的`apply`方法来负责对象的创建。 + +当你创建包含参数的样例类时，这些参数是公开（public）的`val` +``` +case class Message(sender: String, recipient: String, body: String) +val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") + +println(message1.sender) // prints guillaume@quebec.ca +message1.sender = "travis@washington.us" // this line does not compile +``` +你不能给`message1.sender`重新赋值，因为它是一个`val`（不可变）。在样例类中使用`var`也是可以的，但并不推荐这样。 + +## 比较 +样例类在比较的时候是按值比较而非按引用比较： +``` +case class Message(sender: String, recipient: String, body: String) + +val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") +val messagesAreTheSame = message2 == message3 // true +``` +尽管`message2`和`message3`引用不同的对象，但是他们的值是相等的，所以`message2 == message3`为`true`。 + +## 拷贝 +你可以通过`copy`方法创建一个样例类实例的浅拷贝，同时可以指定构造参数来做一些改变。 +``` +case class Message(sender: String, recipient: String, body: String) +val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") +val message5 = message4.copy(sender = message4.recipient, recipient = "claire@bourgogne.fr") +message5.sender // travis@washington.us +message5.recipient // claire@bourgogne.fr +message5.body // "Me zo o komz gant ma amezeg" +``` +上述代码指定`message4`的`recipient`作为`message5`的`sender`，指定`message5`的`recipient`为"claire@bourgogne.fr"，而`message4`的`body`则是直接拷贝作为`message5`的`body`了。 + diff --git a/_zh-cn/tour/classes.md b/_zh-cn/tour/classes.md index 1fa22ae904..e01dece08f 100644 --- a/_zh-cn/tour/classes.md +++ b/_zh-cn/tour/classes.md @@ -1,9 +1,6 @@ --- layout: tour title: 类 - -discourse: true - partof: scala-tour num: 4 @@ -14,22 +11,20 @@ next-page: traits previous-page: unified-types topics: classes prerequisite-knowledge: no-return-keyword, type-declaration-syntax, string-interpolation, procedures - -redirect_from: "/tutorials/tour/classes.html" --- Scala中的类是用于创建对象的蓝图，其中包含了方法、常量、变量、类型、对象、特质、类，这些统称为成员。类型、对象和特质将在后面的文章中介绍。 ## 类定义 -一个最简的类的定义就是关键字`class`+标识符，类名必须是大写。 -```tut +一个最简的类的定义就是关键字`class`+标识符，类名首字母应大写。 +```scala mdoc class User val user1 = new User ``` 关键字`new`被用于创建类的实例。`User`由于没有定义任何构造器，因而只有一个不带任何参数的默认构造器。然而，你通常需要一个构造器和类体。下面是类定义的一个例子： -```tut +```scala mdoc class Point(var x: Int, var y: Int) { def move(dx: Int, dy: Int): Unit = { @@ -52,7 +47,7 @@ println(point1) // prints (2, 3) 构造器可以通过提供一个默认值来拥有可选参数： -```tut +```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val origin = new Point // x and y are both set to 0 @@ -62,7 +57,7 @@ println(point1.x) // prints 1 ``` 在这个版本的`Point`类中，`x`和`y`拥有默认值`0`所以没有必传参数。然而，因为构造器是从左往右读取参数，所以如果仅仅要传个`y`的值，你需要带名传参。 -``` +```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val point2 = new Point(y=2) println(point2.y) // prints 2 @@ -71,8 +66,8 @@ println(point2.y) // prints 2 这样的做法在实践中有利于使得表达明确无误。 ## 私有成员和Getter/Setter语法 -成员默认是公有（`public`）的。使用`private`访问修饰符可以在函数外部隐藏它们。 -```tut +成员默认是公有（`public`）的。使用`private`访问修饰符可以在类外部隐藏它们。 +```scala mdoc:nest class Point { private var _x = 0 private var _y = 0 @@ -97,15 +92,15 @@ point1.y = 101 // prints the warning ``` 在这个版本的`Point`类中，数据存在私有变量`_x`和`_y`中。`def x`和`def y`方法用于访问私有数据。`def x_=`和`def y_=`是为了验证和给`_x`和`_y`赋值。注意下对于setter方法的特殊语法：这个方法在getter方法的后面加上`_=`，后面跟着参数。 -主构造方法中带有`val`和`var`的参数时公有的。然而由于`val`是不可变的，所以不能像下面这样去使用。 -``` +主构造方法中带有`val`和`var`的参数是公有的。然而由于`val`是不可变的，所以不能像下面这样去使用。 +```scala mdoc:fail class Point(val x: Int, val y: Int) val point = new Point(1, 2) point.x = 3 // <-- does not compile ``` 不带`val`或`var`的参数是私有的，仅在类中可见。 -``` +```scala mdoc:fail class Point(x: Int, y: Int) val point = new Point(1, 2) point.x // <-- does not compile diff --git a/_zh-cn/tour/compound-types.md b/_zh-cn/tour/compound-types.md index d21731a865..9c36707c67 100644 --- a/_zh-cn/tour/compound-types.md +++ b/_zh-cn/tour/compound-types.md @@ -1,9 +1,6 @@ --- layout: tour -title: Compound Types - -discourse: false - +title: 复合类型 partof: scala-tour num: 22 @@ -11,5 +8,45 @@ num: 22 language: zh-cn next-page: self-types -previous-page: abstract-types +previous-page: abstract-type-members --- + +有时需要表明一个对象的类型是其他几种类型的子类型。 在 Scala 中，这可以表示成 *复合类型*，即多个类型的交集。 + +假设我们有两个特质 `Cloneable` 和 `Resetable`： + +```scala mdoc +trait Cloneable extends java.lang.Cloneable { + override def clone(): Cloneable = { + super.clone().asInstanceOf[Cloneable] + } +} +trait Resetable { + def reset: Unit +} +``` + +现在假设我们要编写一个方法 `cloneAndReset`，此方法接受一个对象，克隆它并重置原始对象： + +``` +def cloneAndReset(obj: ?): Cloneable = { + val cloned = obj.clone() + obj.reset + cloned +} +``` + +这里出现一个问题，参数 `obj` 的类型是什么。 如果类型是 `Cloneable` 那么参数对象可以被克隆 `clone`，但不能重置 `reset`; 如果类型是 `Resetable` 我们可以重置 `reset` 它，但却没有克隆 `clone` 操作。 为了避免在这种情况下进行类型转换，我们可以将 `obj` 的类型同时指定为 `Cloneable` 和 `Resetable`。 这种复合类型在 Scala 中写成：`Cloneable with Resetable`。 + +以下是更新后的方法： + +``` +def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { + //... +} +``` + +复合类型可以由多个对象类型构成，这些对象类型可以有单个细化，用于缩短已有对象成员的签名。 +格式为：`A with B with C ... { refinement }` + +关于使用细化的例子参考 [通过混入（mixin）来组合类](mixin-class-composition.html)。 diff --git a/_zh-cn/tour/default-parameter-values.md b/_zh-cn/tour/default-parameter-values.md index e9102c8b93..67db867770 100644 --- a/_zh-cn/tour/default-parameter-values.md +++ b/_zh-cn/tour/default-parameter-values.md @@ -1,9 +1,6 @@ --- layout: tour -title: Default Parameter Values - -discourse: false - +title: 默认参数值 partof: scala-tour num: 31 @@ -13,3 +10,37 @@ language: zh-cn next-page: named-arguments previous-page: annotations --- + +Scala具备给参数提供默认值的能力，这样调用者就可以忽略这些具有默认值的参数。 + +```scala mdoc +def log(message: String, level: String = "INFO") = println(s"$level: $message") + +log("System starting") // prints INFO: System starting +log("User not found", "WARNING") // prints WARNING: User not found +``` + +上面的参数level有默认值，所以是可选的。最后一行中传入的参数`"WARNING"`重写了默认值`"INFO"`。在Java中，我们可以通过带有可选参数的重载方法达到同样的效果。不过，只要调用方忽略了一个参数，其他参数就必须要带名传入。 + +```scala mdoc +class Point(val x: Double = 0, val y: Double = 0) + +val point1 = new Point(y = 1) +``` +这里必须带名传入`y = 1`。 + +注意从Java代码中调用时，Scala中的默认参数则是必填的（非可选），如： + +```scala mdoc:nest +// Point.scala +class Point(val x: Double = 0, val y: Double = 0) +``` + +```java +// Main.java +public class Main { + public static void main(String[] args) { + Point point = new Point(1); // does not compile + } +} +``` diff --git a/_zh-cn/tour/extractor-objects.md b/_zh-cn/tour/extractor-objects.md index 39ce4bc90f..c74d946482 100644 --- a/_zh-cn/tour/extractor-objects.md +++ b/_zh-cn/tour/extractor-objects.md @@ -1,9 +1,6 @@ --- layout: tour -title: Extractor Objects - -discourse: false - +title: 提取器对象 partof: scala-tour num: 14 @@ -13,3 +10,55 @@ language: zh-cn next-page: generic-classes previous-page: regular-expression-patterns --- + +提取器对象是一个包含有 `unapply` 方法的单例对象。`apply` 方法就像一个构造器，接受参数然后创建一个实例对象，反之 `unapply` 方法接受一个实例对象然后返回最初创建它所用的参数。提取器常用在模式匹配和偏函数中。 + +```scala mdoc +import scala.util.Random + +object CustomerID { + + def apply(name: String) = s"$name--${Random.nextLong()}" + + def unapply(customerID: String): Option[String] = { + val stringArray: Array[String] = customerID.split("--") + if (stringArray.tail.nonEmpty) Some(stringArray.head) else None + } +} + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match { + case CustomerID(name) => println(name) // prints Sukyoung + case _ => println("Could not extract a CustomerID") +} +``` + +这里 `apply` 方法用 `name` 创建一个 `CustomerID` 字符串。而 `unapply` 方法正好相反，它返回 `name` 。当我们调用 `CustomerID("Sukyoung")` ，其实是调用了 `CustomerID.apply("Sukyoung")` 的简化语法。当我们调用 `case CustomerID(name) => println(name)`，就是在调用提取器方法。 + +因为变量定义可以使用模式引入变量，提取器可以用来初始化这个变量，使用 unapply 方法来生成值。 + +```scala mdoc +val customer2ID = CustomerID("Nico") +val CustomerID(name) = customer2ID +println(name) // prints Nico +``` + +上面的代码等价于 `val name = CustomerID.unapply(customer2ID).get`。 + +```scala mdoc +val CustomerID(name2) = "--asdfasdfasdf" +``` + +如果没有匹配的值，会抛出 `scala.MatchError`： + +```scala +val CustomerID(name3) = "-asdfasdfasdf" +``` + +`unapply` 方法的返回值应当符合下面的某一条： + +* 如果只是用来判断真假，可以返回一个 `Boolean` 类型的值。例如 `case even()`。 +* 如果只是用来提取单个 T 类型的值，可以返回 `Option[T]`。 +* 如果你想要提取多个值，类型分别为 `T1,...,Tn`，可以把它们放在一个可选的元组中 `Option[(T1,...,Tn)]`。 + +有时，要提取的值的数量不是固定的，因此我们想根据输入来返回随机数量的值。这种情况下，你可以用 `unapplySeq` 方法来定义提取器，此方法返回 `Option[Seq[T]]`。常见的例子有，用 `case List(x, y, z) =>` 来解构一个列表 `List`，以及用一个正则表达式 `Regex` 来分解一个字符串 `String`，例如 `case r(name, remainingFields @ _*) =>`。 diff --git a/_zh-cn/tour/for-comprehensions.md b/_zh-cn/tour/for-comprehensions.md index 6799214e4e..1c3f823fa8 100644 --- a/_zh-cn/tour/for-comprehensions.md +++ b/_zh-cn/tour/for-comprehensions.md @@ -1,9 +1,6 @@ --- layout: tour -title: For Comprehensions - -discourse: false - +title: For 表达式 partof: scala-tour num: 15 @@ -13,3 +10,54 @@ language: zh-cn next-page: generic-classes previous-page: extractor-objects --- + +Scala 提供一个轻量级的标记方式用来表示 *序列推导*。推导使用形式为 `for (enumerators) yield e` 的 for 表达式，此处 `enumerators` 指一组以分号分隔的枚举器。一个 *enumerator* 要么是一个产生新变量的生成器，要么是一个过滤器。for 表达式在枚举器产生的每一次绑定中都会计算 `e` 值，并在循环结束后返回这些值组成的序列。 + +看下例： + +```scala mdoc +case class User(name: String, age: Int) + +val userBase = List(User("Travis", 28), + User("Kelly", 33), + User("Jennifer", 44), + User("Dennis", 23)) + +val twentySomethings = for (user <- userBase if (user.age >=20 && user.age < 30)) + yield user.name // i.e. add this to a list + +twentySomethings.foreach(name => println(name)) // prints Travis Dennis +``` +这里 `for` 循环后面使用的 `yield` 语句实际上会创建一个 `List`。因为当我们说 `yield user.name` 的时候，它实际上是一个 `List[String]`。 `user <- userBase` 是生成器，`if (user.age >=20 && user.age < 30)` 是过滤器用来过滤掉那些年龄不是20多岁的人。 + +下面这个例子复杂一些，使用了两个生成器。它计算了 `0` 到 `n-1` 的所有两两求和为 `v` 的数字的组合： + +```scala mdoc +def foo(n: Int, v: Int) = + for (i <- 0 until n; + j <- i until n if i + j == v) + yield (i, j) + +foo(10, 10) foreach { + case (i, j) => + println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) +} + +``` +这里 `n == 10` 和 `v == 10`。在第一次迭代时，`i == 0` 并且 `j == 0` 所以 `i + j != v` 因此没有返回值被生成。在 `i` 的值递增到 `1` 之前，`j` 的值又递增了 9 次。如果没有 `if` 语句过滤，上面的例子只会打印出如下的结果： +```scala +(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... +``` + +注意 for 表达式并不局限于使用列表。任何数据类型只要支持 `withFilter`，`map`，和 `flatMap` 操作（不同数据类型可能支持不同的操作）都可以用来做序列推导。 + +你可以在使用 for 表达式时省略 `yield` 语句。此时会返回 `Unit`。当你想要执行一些副作用的时候这很有用。下面的例子输出和上面相同的结果，但是没有使用 `yield`： + +```scala mdoc:nest +def foo(n: Int, v: Int) = + for (i <- 0 until n; + j <- i until n if i + j == v) + println(s"($i, $j)") + +foo(10, 10) +``` diff --git a/_zh-cn/tour/generic-classes.md b/_zh-cn/tour/generic-classes.md index e38f3a315e..fed6f8d629 100644 --- a/_zh-cn/tour/generic-classes.md +++ b/_zh-cn/tour/generic-classes.md @@ -1,9 +1,6 @@ --- layout: tour -title: Generic Classes - -discourse: false - +title: 泛型类 partof: scala-tour num: 16 @@ -13,3 +10,48 @@ language: zh-cn next-page: variances previous-page: extractor-objects --- +泛型类指可以接受类型参数的类。泛型类在集合类中被广泛使用。 + +## 定义一个泛型类 +泛型类使用方括号 `[]` 来接受类型参数。一个惯例是使用字母 `A` 作为参数标识符，当然你可以使用任何参数名称。 +```scala mdoc +class Stack[A] { + private var elements: List[A] = Nil + def push(x: A): Unit = + elements = x :: elements + def peek: A = elements.head + def pop(): A = { + val currentTop = peek + elements = elements.tail + currentTop + } +} +``` +上面的 `Stack` 类的实现中接受类型参数 `A`。 这表示其内部的列表，`var elements: List[A] = Nil`，只能够存储类型 `A` 的元素。方法 `def push` 只接受类型 `A` 的实例对象作为参数(注意：`elements = x :: elements` 将 `elements` 放到了一个将元素 `x` 添加到 `elements` 的头部而生成的新列表中)。 + +## 使用 + +要使用一个泛型类，将一个具体类型放到方括号中来代替 `A`。 +``` +val stack = new Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop) // prints 2 +println(stack.pop) // prints 1 +``` +实例对象 `stack` 只能接受整型值。然而，如果类型参数有子类型，子类型可以被传入： +``` +class Fruit +class Apple extends Fruit +class Banana extends Fruit + +val stack = new Stack[Fruit] +val apple = new Apple +val banana = new Banana + +stack.push(apple) +stack.push(banana) +``` +类 `Apple` 和类 `Banana` 都继承自类 `Fruit`，所以我们可以把实例对象 `apple` 和 `banana` 压入栈 `Fruit` 中。 + +_注意：泛型类型的子类型是*不可传导*的。这表示如果我们有一个字母类型的栈 `Stack[Char]`，那它不能被用作一个整型的栈 `Stack[Int]`。否则就是不安全的，因为它将使我们能够在字母型的栈中插入真正的整型值。结论就是，只有当类型 `B = A` 时， `Stack[A]` 是 `Stack[B]` 的子类型才成立。因为此处可能会有很大的限制，Scala 提供了一种 [类型参数注释机制](variances.html) 用以控制泛型类型的子类型的行为。_ diff --git a/_zh-cn/tour/higher-order-functions.md b/_zh-cn/tour/higher-order-functions.md index 27bba41ce2..c5112c1805 100644 --- a/_zh-cn/tour/higher-order-functions.md +++ b/_zh-cn/tour/higher-order-functions.md @@ -1,9 +1,6 @@ --- layout: tour -title: Higher-order Functions - -discourse: false - +title: 高阶函数 partof: scala-tour num: 7 @@ -13,3 +10,93 @@ language: zh-cn next-page: nested-functions previous-page: mixin-class-composition --- + +高阶函数是指使用其他函数作为参数、或者返回一个函数作为结果的函数。在Scala中函数是“一等公民”，所以允许定义高阶函数。这里的术语可能有点让人困惑，我们约定，使用函数值作为参数，或者返回值为函数值的“函数”和“方法”，均称之为“高阶函数”。 + +最常见的一个例子是Scala集合类（collections）的高阶函数`map` +``` +val salaries = Seq(20000, 70000, 40000) +val doubleSalary = (x: Int) => x * 2 +val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) +``` +函数`doubleSalary`有一个整型参数`x`，返回`x * 2`。一般来说，在`=>`左边的元组是函数的参数列表，而右边表达式的值则为函数的返回值。在第3行，函数`doubleSalary`被应用在列表`salaries`中的每一个元素。 + +为了简化压缩代码，我们可以使用匿名函数，直接作为参数传递给`map`: +``` +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) +``` +注意在上述示例中`x`没有被显式声明为Int类型，这是因为编译器能够根据map函数期望的类型推断出`x`的类型。对于上述代码，一种更惯用的写法为： +```scala mdoc +val salaries = Seq(20000, 70000, 40000) +val newSalaries = salaries.map(_ * 2) +``` +既然Scala编译器已经知道了参数的类型（一个单独的Int），你可以只给出函数的右半部分，不过需要使用`_`代替参数名（在上一个例子中是`x`） + +## 强制转换方法为函数 +你同样可以传入一个对象方法作为高阶函数的参数，这是因为Scala编译器会将方法强制转换为一个函数。 +``` +case class WeeklyWeatherForecast(temperatures: Seq[Double]) { + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF +} +``` +在这个例子中，方法`convertCtoF`被传入`forecastInFahrenheit`。这是可以的，因为编译器强制将方法`convertCtoF`转成了函数`x => convertCtoF(x)` （注: `x`是编译器生成的变量名，保证在其作用域是唯一的）。 + +## 接收函数作为参数的函数 +使用高阶函数的一个原因是减少冗余的代码。比方说需要写几个方法以通过不同方式来提升员工工资，若不使用高阶函数，代码可能像这样： +```scala mdoc +object SalaryRaiser { + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +} +``` + +注意这三个方法的差异仅仅是提升的比例不同，为了简化代码，其实可以把重复的代码提到一个高阶函数中： + +```scala mdoc:nest +object SalaryRaiser { + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def bigPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +} +``` + +新的方法`promotion`有两个参数，薪资列表和一个类型为`Double => Double`的函数（参数和返回值类型均为Double），返回薪资提升的结果。 + +## 返回函数的函数 + +有一些情况你希望生成一个函数， 比如： + +```scala mdoc +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { + val schema = if (ssl) "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" +} + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` + +注意urlBuilder的返回类型是`(String, String) => String`，这意味着返回的匿名函数有两个String参数，返回一个String。在这个例子中，返回的匿名函数是`(endpoint: String, query: String) => s"https://www.example.com/$endpoint?$query"`。 diff --git a/_zh-cn/tour/implicit-conversions.md b/_zh-cn/tour/implicit-conversions.md index 9458fba5d3..4c2d94cc0b 100644 --- a/_zh-cn/tour/implicit-conversions.md +++ b/_zh-cn/tour/implicit-conversions.md @@ -1,9 +1,6 @@ --- layout: tour -title: Implicit Conversions - -discourse: false - +title: 隐式转换 partof: scala-tour num: 25 @@ -13,3 +10,52 @@ language: zh-cn next-page: polymorphic-methods previous-page: implicit-parameters --- + +一个从类型 `S` 到类型 `T` 的隐式转换由一个函数类型 `S => T` 的隐式值来定义，或者由一个可转换成所需值的隐式方法来定义。 + +隐式转换在两种情况下会用到： + +* 如果一个表达式 `e` 的类型为 `S`， 并且类型 `S` 不符合表达式的期望类型 `T`。 +* 在一个类型为 `S` 的实例对象 `e` 中调用 `e.m`， 如果被调用的 `m` 并没有在类型 `S` 中声明。 + +在第一种情况下，搜索转换 `c`，它适用于 `e`，并且结果类型为 `T`。 +在第二种情况下，搜索转换 `c`，它适用于 `e`，其结果包含名为 `m` 的成员。 + +如果一个隐式方法 `List[A] => Ordered[List[A]]`，以及一个隐式方法 `Int => Ordered[Int]` 在上下文范围内，那么对下面两个类型为 `List[Int]` 的列表的操作是合法的： + +``` +List(1, 2, 3) <= List(4, 5) +``` + +在 `scala.Predef.intWrapper` 已经自动提供了一个隐式方法 `Int => Ordered[Int]`。下面提供了一个隐式方法 `List[A] => Ordered[List[A]]` 的例子。 + +```scala mdoc +import scala.language.implicitConversions + +implicit def list2ordered[A](x: List[A]) + (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] = + new Ordered[List[A]] { + //replace with a more useful implementation + def compare(that: List[A]): Int = 1 + } +``` + +自动导入的对象 `scala.Predef` 声明了几个预定义类型 (例如 `Pair`) 和方法 (例如 `assert`)，同时也声明了一些隐式转换。 + +例如，当调用一个接受 `java.lang.Integer` 作为参数的 Java 方法时，你完全可以传入一个 `scala.Int`。那是因为 Predef 包含了以下的隐式转换： + +```scala mdoc +import scala.language.implicitConversions + +implicit def int2Integer(x: Int): Integer = + Integer.valueOf(x) +``` + +因为如果不加选择地使用隐式转换可能会导致陷阱，编译器会在编译隐式转换定义时发出警告。 + +要关闭警告，执行以下任一操作： + +* 将 `scala.language.implicitConversions` 导入到隐式转换定义的上下文范围内 +* 启用编译器选项 `-language:implicitConversions` + +在编译器应用隐式转换时不会发出警告。 diff --git a/_zh-cn/tour/implicit-parameters.md b/_zh-cn/tour/implicit-parameters.md index 46bb8d5e9d..e8e89451e6 100644 --- a/_zh-cn/tour/implicit-parameters.md +++ b/_zh-cn/tour/implicit-parameters.md @@ -1,9 +1,6 @@ --- layout: tour -title: Implicit Parameters - -discourse: false - +title: 隐式参数 partof: scala-tour num: 24 @@ -13,3 +10,62 @@ language: zh-cn next-page: implicit-conversions previous-page: self-types --- + +方法可以具有 _隐式_ 参数列表，由参数列表开头的 _implicit_ 关键字标记。 如果参数列表中的参数没有像往常一样传递， Scala 将查看它是否可以获得正确类型的隐式值，如果可以，则自动传递。 + +Scala 将查找这些参数的位置分为两类： + +* Scala 在调用包含有隐式参数块的方法时，将首先查找可以直接访问的隐式定义和隐式参数 (无前缀)。 +* 然后，它在所有伴生对象中查找与隐式候选类型相关的有隐式标记的成员。 + +更加详细的关于 Scala 到哪里查找隐式参数的指南请参考 [常见问题](/tutorials/FAQ/finding-implicits.html) + +在下面的例子中，我们定义了一个方法 `sum`，它使用 Monoid 类的 `add` 和 `unit` 方法计算一个列表中元素的总和。 请注意，隐式值不能是顶级值。 + +```scala mdoc +abstract class Monoid[A] { + def add(x: A, y: A): A + def unit: A +} + +object ImplicitTest { + implicit val stringMonoid: Monoid[String] = new Monoid[String] { + def add(x: String, y: String): String = x concat y + def unit: String = "" + } + + implicit val intMonoid: Monoid[Int] = new Monoid[Int] { + def add(x: Int, y: Int): Int = x + y + def unit: Int = 0 + } + + def sum[A](xs: List[A])(implicit m: Monoid[A]): A = + if (xs.isEmpty) m.unit + else m.add(xs.head, sum(xs.tail)) + + def main(args: Array[String]): Unit = { + println(sum(List(1, 2, 3))) // uses IntMonoid implicitly + println(sum(List("a", "b", "c"))) // uses StringMonoid implicitly + } +} +``` + +类 `Monoid` 定义了一个名为 `add` 的操作，它将一对 `A` 类型的值相加并返回一个 `A`，以及一个名为 `unit` 的操作，用来创建一个（特定的）`A` 类型的值。 + +为了说明隐式参数如何工作，我们首先分别为字符串和整数定义 Monoid 实例， `StringMonoid` 和 `IntMonoid`。 `implicit` 关键字表示可以隐式使用相应的对象。 + +方法 `sum` 接受一个 `List[A]`，并返回一个 `A` 的值，它从 `unit` 中取初始的 `A` 值，并使用 `add` 方法依次将列表中的下一个 `A` 值相加。在这里将参数 `m` 定义为隐式意味着，如果 Scala 可以找到隐式 `Monoid[A]` 用于隐式参数 `m`，我们在调用 `sum` 方法时只需要传入 `xs` 参数。 + +在 `main` 方法中我们调用了 `sum` 方法两次，并且只传入参数 `xs`。 Scala 会在上例的上下文范围内寻找隐式值。 第一次调用 `sum` 方法的时候传入了一个 `List[Int]` 作为 `xs` 的值，这意味着此处类型 `A` 是 `Int`。 隐式参数列表 `m` 被省略了，因此 Scala 将查找类型为 `Monoid[Int]` 的隐式值。 第一查找规则如下 + +> Scala 在调用包含有隐式参数块的方法时，将首先查找可以直接访问的隐式定义和隐式参数 (无前缀)。 + +`intMonoid` 是一个隐式定义，可以在`main`中直接访问。 并且它的类型也正确，因此它会被自动传递给 `sum` 方法。 + +第二次调用 `sum` 方法的时候传入一个 `List[String]`，这意味着此处类型 `A` 是 `String`。 与查找 `Int` 型的隐式参数时类似，但这次会找到 `stringMonoid`，并自动将其作为 `m` 传入。 + +该程序将输出 +``` +6 +abc +``` diff --git a/_zh-cn/tour/inner-classes.md b/_zh-cn/tour/inner-classes.md index 471c41c610..a390c0b340 100644 --- a/_zh-cn/tour/inner-classes.md +++ b/_zh-cn/tour/inner-classes.md @@ -1,15 +1,79 @@ --- layout: tour -title: Inner Classes - -discourse: false - +title: 内部类 partof: scala-tour num: 20 language: zh-cn -next-page: abstract-types +next-page: abstract-type-members previous-page: lower-type-bounds --- + +在Scala中，一个类可以作为另一个类的成员。 在一些类似 Java 的语言中，内部类是外部类的成员，而 Scala 正好相反，内部类是绑定到外部对象的。 假设我们希望编译器在编译时阻止我们混淆节点 nodes 与图形 graph 的关系，路径依赖类型提供了一种解决方案。 + +为了说明差异，我们简单描述了一个图形数据类型的实现： + +```scala mdoc +class Graph { + class Node { + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes + } + } + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` +该程序将图形表示为节点列表 (`List[Node]`)。 每个节点都有一个用来存储与其相连的其他节点的列表 (`connectedNodes`)。 类 `Node` 是一个 _路径依赖类型_，因为它嵌套在类 `Graph` 中。 因此，`connectedNodes` 中存储的所有节点必须使用同一个 `Graph` 的实例对象的 `newNode` 方法来创建。 + +```scala mdoc +val graph1: Graph = new Graph +val node1: graph1.Node = graph1.newNode +val node2: graph1.Node = graph1.newNode +val node3: graph1.Node = graph1.newNode +node1.connectTo(node2) +node3.connectTo(node1) +``` +为清楚起见，我们已经明确地将 `node1`，`node2`，和 `node3` 的类型声明为`graph1.Node`，但编译器其实可以自动推断出它。 这是因为当我们通过调用 `graph1.newNode` 来调用 `new Node` 时，该方法产生特定于实例 `graph1` 的 `Node` 类型的实例对象。 + +如果我们现在有两个图形，Scala 的类型系统不允许我们将一个图形中定义的节点与另一个图形的节点混合，因为另一个图形的节点具有不同的类型。 +下例是一个非法的程序： + +```scala mdoc:fail +val graph1: Graph = new Graph +val node1: graph1.Node = graph1.newNode +val node2: graph1.Node = graph1.newNode +node1.connectTo(node2) // legal +val graph2: Graph = new Graph +val node3: graph2.Node = graph2.newNode +node1.connectTo(node3) // illegal! +``` +类型 `graph1.Node` 与类型 `graph2.Node` 完全不同。 在 Java 中，上一个示例程序中的最后一行是正确的。 对于两个图形的节点，Java 将分配相同的类型 `Graph.Node`; 即 `Node` 以类 `Graph` 为前缀。 在Scala中也可以表示出这种类型，它写成了 `Graph#Node`。 如果我们希望能够连接不同图形的节点，我们必须通过以下方式更改图形类的初始实现的定义： + +```scala mdoc:nest +class Graph { + class Node { + var connectedNodes: List[Graph#Node] = Nil + def connectTo(node: Graph#Node): Unit = { + if (!connectedNodes.exists(node.equals)) { + connectedNodes = node :: connectedNodes + } + } + } + var nodes: List[Node] = Nil + def newNode: Node = { + val res = new Node + nodes = res :: nodes + res + } +} +``` diff --git a/_zh-cn/tour/lower-type-bounds.md b/_zh-cn/tour/lower-type-bounds.md index cb924cc78c..b511f52cf7 100644 --- a/_zh-cn/tour/lower-type-bounds.md +++ b/_zh-cn/tour/lower-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour -title: Lower Type Bounds - -discourse: false - +title: 类型下界 partof: scala-tour num: 19 @@ -13,3 +10,58 @@ language: zh-cn next-page: inner-classes previous-page: upper-type-bounds --- + +[类型上界](upper-type-bounds.html) 将类型限制为另一种类型的子类型，而 *类型下界* 将类型声明为另一种类型的超类型。 术语 `B >: A` 表示类型参数 `B` 或抽象类型 `B` 是类型 `A` 的超类型。 在大多数情况下，`A` 将是类的类型参数，而 `B` 将是方法的类型参数。 + +下面看一个适合用类型下界的例子： + +```scala mdoc:fail +trait Node[+B] { + def prepend(elem: B): Node[B] +} + +case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { + def prepend(elem: B): ListNode[B] = ListNode(elem, this) + def head: B = h + def tail: Node[B] = t +} + +case class Nil[+B]() extends Node[B] { + def prepend(elem: B): ListNode[B] = ListNode(elem, this) +} +``` + +该程序实现了一个单链表。 `Nil` 表示空元素（即空列表）。 `class ListNode` 是一个节点，它包含一个类型为 `B` (`head`) 的元素和一个对列表其余部分的引用 (`tail`)。 `class Node` 及其子类型是协变的，因为我们定义了 `+B`。 + +但是，这个程序 _不能_ 编译，因为方法 `prepend` 中的参数 `elem` 是*协*变的 `B` 类型。 这会出错，因为函数的参数类型是*逆*变的，而返回类型是*协*变的。 + +要解决这个问题，我们需要将方法 `prepend` 的参数 `elem` 的型变翻转。 我们通过引入一个新的类型参数 `U` 来实现这一点，该参数具有 `B` 作为类型下界。 + +```scala mdoc +trait Node[+B] { + def prepend[U >: B](elem: U): Node[U] +} + +case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { + def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) + def head: B = h + def tail: Node[B] = t +} + +case class Nil[+B]() extends Node[B] { + def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) +} +``` + +现在我们像下面这么做： +```scala mdoc +trait Bird +case class AfricanSwallow() extends Bird +case class EuropeanSwallow() extends Bird + + +val africanSwallowList= ListNode[AfricanSwallow](AfricanSwallow(), Nil()) +val birdList: Node[Bird] = africanSwallowList +birdList.prepend(EuropeanSwallow()) +``` +可以为 `Node[Bird]` 赋值 `africanSwallowList`，然后再加入一个 `EuropeanSwallow`。 diff --git a/_zh-cn/tour/mixin-class-composition.md b/_zh-cn/tour/mixin-class-composition.md index 99e4119c92..1b4c6bab36 100644 --- a/_zh-cn/tour/mixin-class-composition.md +++ b/_zh-cn/tour/mixin-class-composition.md @@ -1,9 +1,6 @@ --- layout: tour -title: Class Composition with Mixins - -discourse: false - +title: 通过混入（mixin）来组合类 partof: scala-tour num: 6 @@ -11,5 +8,77 @@ num: 6 language: zh-cn next-page: higher-order-functions -previous-page: traits +previous-page: tuples --- + +当某个特质被用于组合类时，被称为混入。 + +```scala mdoc +abstract class A { + val message: String +} +class B extends A { + val message = "I'm an instance of class B" +} +trait C extends A { + def loudMessage = message.toUpperCase() +} +class D extends B with C + +val d = new D +println(d.message) // I'm an instance of class B +println(d.loudMessage) // I'M AN INSTANCE OF CLASS B +``` + +类`D`有一个父类`B`和一个混入`C`。一个类只能有一个父类但是可以有多个混入（分别使用关键字`extends`和`with`）。混入和某个父类可能有相同的父类。 + +现在，让我们看一个更有趣的例子，其中使用了抽象类： + +```scala mdoc +abstract class AbsIterator { + type T + def hasNext: Boolean + def next(): T +} +``` + +该类中有一个抽象的类型`T`和标准的迭代器方法。 + +接下来，我们将实现一个具体的类（所有的抽象成员`T`、`hasNext`和`next`都会被实现）： + +```scala mdoc +class StringIterator(s: String) extends AbsIterator { + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = { + val ch = s charAt i + i += 1 + ch + } +} +``` + +`StringIterator`带有一个`String`类型参数的构造器，可用于对字符串进行迭代。（例如查看一个字符串是否包含某个字符）： + +现在我们创建一个特质，也继承于`AbsIterator`。 + +```scala mdoc +trait RichIterator extends AbsIterator { + def foreach(f: T => Unit): Unit = while (hasNext) f(next()) +} +``` + +该特质实现了`foreach`方法——只要还有元素可以迭代（`while (hasNext)`），就会一直对下个元素(`next()`) 调用传入的函数`f: T => Unit`。因为`RichIterator`是个特质，可以不必实现`AbsIterator`中的抽象成员。 + +下面我们要把`StringIterator`和`RichIterator` 中的功能组合成一个类。 + +```scala mdoc +object StringIteratorTest extends App { + class RichStringIter extends StringIterator("Scala") with RichIterator + val richStringIter = new RichStringIter + richStringIter foreach println +} +``` + +新的类`RichStringIter`有一个父类`StringIterator`和一个混入`RichIterator`。如果是单一继承，我们将不会达到这样的灵活性。 diff --git a/_zh-cn/tour/multiple-parameter-lists.md b/_zh-cn/tour/multiple-parameter-lists.md index 54a101b206..d0c16aebb1 100644 --- a/_zh-cn/tour/multiple-parameter-lists.md +++ b/_zh-cn/tour/multiple-parameter-lists.md @@ -1,9 +1,6 @@ --- layout: tour -title: Multiple Parameter Lists (Currying) - -discourse: false - +title: 多参数列表（柯里化） partof: scala-tour num: 9 @@ -13,3 +10,68 @@ language: zh-cn next-page: case-classes previous-page: nested-functions --- + +方法可以定义多个参数列表，当使用较少的参数列表调用多参数列表的方法时，会产生一个新的函数，该函数接收剩余的参数列表作为其参数。这被称为[柯里化](https://zh.wikipedia.org/wiki/%E6%9F%AF%E9%87%8C%E5%8C%96)。 + +下面是一个例子，在Scala集合 `trait TraversableOnce` 定义了 `foldLeft` + +```scala mdoc:fail +def foldLeft[B](z: B)(op: (B, A) => B): B +``` + +`foldLeft`从左到右，以此将一个二元运算`op`应用到初始值`z`和该迭代器（traversable)的所有元素上。以下是该函数的一个用例： + +从初值0开始, 这里 `foldLeft` 将函数 `(m, n) => m + n` 依次应用到列表中的每一个元素和之前累积的值上。 + +```scala mdoc +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val res = numbers.foldLeft(0)((m, n) => m + n) +print(res) // 55 +``` + +多参数列表有更复杂的调用语法，因此应该谨慎使用，建议的使用场景包括： + +#### 单一的函数参数 + 在某些情况下存在单一的函数参数时，例如上述例子`foldLeft`中的`op`，多参数列表可以使得传递匿名函数作为参数的语法更为简洁。如果不使用多参数列表，代码可能像这样： + +```scala +numbers.foldLeft(0, {(m: Int, n: Int) => m + n}) +``` + + 注意使用多参数列表时，我们还可以利用Scala的类型推断来让代码更加简洁（如下所示），而如果没有多参数列表，这是不可能的。 + +```scala mdoc +numbers.foldLeft(0)(_ + _) +``` + 像上述语句这样，我们可以给定多参数列表的一部分参数列表（如上述的`z`）来形成一个新的函数（partially applied function），达到复用的目的，如下所示： + +```scala mdoc:nest +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]())_ + +val squares = numberFunc((xs, x) => xs:+ x*x) +print(squares.toString()) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) + +val cubes = numberFunc((xs, x) => xs:+ x*x*x) +print(cubes.toString()) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` + + 最后，`foldLeft` 和 `foldRight` 可以按以下任意一种形式使用， +```scala mdoc:nest +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) + +numbers.foldLeft(0)((sum, item) => sum + item) // Generic Form +numbers.foldRight(0)((sum, item) => sum + item) // Generic Form + +numbers.foldLeft(0)(_+_) // Curried Form +numbers.foldRight(0)(_+_) // Curried Form +``` + + +#### 隐式（implicit）参数 + 如果要指定参数列表中的某些参数为隐式（implicit），应该使用多参数列表。例如： + +```scala +def execute(arg: Int)(implicit ec: ExecutionContext) = ??? +``` + diff --git a/_zh-cn/tour/named-arguments.md b/_zh-cn/tour/named-arguments.md index 544605034b..2a25884bec 100644 --- a/_zh-cn/tour/named-arguments.md +++ b/_zh-cn/tour/named-arguments.md @@ -1,9 +1,6 @@ --- layout: tour -title: Named Arguments - -discourse: false - +title: 命名参数 partof: scala-tour num: 32 @@ -13,3 +10,22 @@ language: zh-cn next-page: packages-and-imports previous-page: default-parameter-values --- + +当调用方法时，实际参数可以通过其对应的形式参数的名称来标记： + +```scala mdoc +def printName(first: String, last: String): Unit = { + println(first + " " + last) +} + +printName("John", "Smith") // Prints "John Smith" +printName(first = "John", last = "Smith") // Prints "John Smith" +printName(last = "Smith", first = "John") // Prints "John Smith" +``` +注意使用命名参数时，顺序是可以重新排列的。 但是，如果某些参数被命名了，而其他参数没有，则未命名的参数要按照其方法签名中的参数顺序放在前面。 + +```scala mdoc:fail +printName(last = "Smith", "john") // error: positional after named argument +``` + +注意调用 Java 方法时不能使用命名参数。 diff --git a/_zh-cn/tour/nested-functions.md b/_zh-cn/tour/nested-functions.md index d296bc28ba..388c04503f 100644 --- a/_zh-cn/tour/nested-functions.md +++ b/_zh-cn/tour/nested-functions.md @@ -1,9 +1,6 @@ --- layout: tour -title: Nested Methods - -discourse: false - +title: 嵌套方法 partof: scala-tour num: 8 @@ -13,3 +10,25 @@ language: zh-cn next-page: multiple-parameter-lists previous-page: higher-order-functions --- + +在Scala中可以嵌套定义方法。例如以下对象提供了一个`factorial`方法来计算给定数值的阶乘： + +```scala mdoc + def factorial(x: Int): Int = { + def fact(x: Int, accumulator: Int): Int = { + if (x <= 1) accumulator + else fact(x - 1, x * accumulator) + } + fact(x, 1) + } + + println("Factorial of 2: " + factorial(2)) + println("Factorial of 3: " + factorial(3)) +``` + +程序的输出为: + +``` +Factorial of 2: 2 +Factorial of 3: 6 +``` diff --git a/_zh-cn/tour/operators.md b/_zh-cn/tour/operators.md index 10721d65a0..9bca79a928 100644 --- a/_zh-cn/tour/operators.md +++ b/_zh-cn/tour/operators.md @@ -1,9 +1,6 @@ --- layout: tour -title: Operators - -discourse: false - +title: 运算符 partof: scala-tour num: 28 @@ -13,3 +10,69 @@ language: zh-cn next-page: by-name-parameters previous-page: type-inference --- +在Scala中，运算符即是方法。 任何具有单个参数的方法都可以用作 _中缀运算符_。 例如，可以使用点号调用 `+`： +``` +10.+(1) +``` + +而中缀运算符则更易读: +``` +10 + 1 +``` + +## 定义和使用运算符 +你可以使用任何合法标识符作为运算符。 包括像 `add` 这样的名字或像 `+` 这样的符号。 +```scala mdoc +case class Vec(x: Double, y: Double) { + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) +} + +val vector1 = Vec(1.0, 1.0) +val vector2 = Vec(2.0, 2.0) + +val vector3 = vector1 + vector2 +vector3.x // 3.0 +vector3.y // 3.0 +``` +类 Vec 有一个方法 `+`，我们用它来使 `vector1` 和 `vector2` 相加。 使用圆括号，你可以使用易读的语法来构建复杂表达式。 这是 `MyBool` 类的定义，其中有方法 `and` 和 `or`： + +```scala mdoc +case class MyBool(x: Boolean) { + def and(that: MyBool): MyBool = if (x) that else this + def or(that: MyBool): MyBool = if (x) this else that + def negate: MyBool = MyBool(!x) +} +``` + +现在可以使用 `and` 和 `or` 作为中缀运算符： + +```scala mdoc +def not(x: MyBool) = x.negate +def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) +``` + +这有助于让方法 `xor` 的定义更具可读性。 + +## 优先级 +当一个表达式使用多个运算符时，将根据运算符的第一个字符来评估优先级： +``` +(characters not shown below) +* / % ++ - +: += ! +< > +& +^ +| +(all letters, $, _) +``` +这也适用于你自定义的方法。 例如，以下表达式： +``` +a + b ^? c ?^ d less a ==> b | c +``` +等价于 +``` +((a + b) ^? (c ?^ d)) less ((a ==> b) | c) +``` +`?^` 具有最高优先级，因为它以字符 `?` 开头。 `+` 具有第二高的优先级，然后依次是 `==>`， `^?`， `|`， 和 `less`。 diff --git a/_zh-cn/tour/package-objects.md b/_zh-cn/tour/package-objects.md new file mode 100644 index 0000000000..254b5933c1 --- /dev/null +++ b/_zh-cn/tour/package-objects.md @@ -0,0 +1,67 @@ +--- +layout: tour +title: 包对象 +language: zh-cn +partof: scala-tour + +num: 36 +previous-page: packages-and-imports +--- + +# 包对象 + +Scala 提供包对象作为在整个包中方便的共享使用的容器。 + +包对象中可以定义任何内容，而不仅仅是变量和方法。 例如，包对象经常用于保存包级作用域的类型别名和隐式转换。 包对象甚至可以继承 Scala 的类和特质。 + +按照惯例，包对象的代码通常放在名为 `package.scala` 的源文件中。 + +每个包都允许有一个包对象。 在包对象中的任何定义都被认为是包自身的成员。 + +看下例。 假设有一个类 `Fruit` 和三个 `Fruit` 对象在包 `gardening.fruits` 中； + +``` +// in file gardening/fruits/Fruit.scala +package gardening.fruits + +case class Fruit(name: String, color: String) +object Apple extends Fruit("Apple", "green") +object Plum extends Fruit("Plum", "blue") +object Banana extends Fruit("Banana", "yellow") +``` + +现在假设你要将变量 `planted` 和方法 `showFruit` 直接放入包 `gardening` 中。 +下面是具体做法： + +``` +// in file gardening/fruits/package.scala +package gardening +package object fruits { + val planted = List(Apple, Plum, Banana) + def showFruit(fruit: Fruit): Unit = { + println(s"${fruit.name}s are ${fruit.color}") + } +} +``` + +作为一个使用范例，下例中的对象 `PrintPlanted` 用导入类 `Fruit` 相同的方式来导入 `planted` 和 `showFruit`，在导入包 `gardening.fruits` 时使用通配符： + +``` +// in file PrintPlanted.scala +import gardening.fruits._ +object PrintPlanted { + def main(args: Array[String]): Unit = { + for (fruit <- planted) { + showFruit(fruit) + } + } +} +``` + +包对象与其他对象类似，这意味着你可以使用继承来构建它们。 例如，一个包对象可能会混入多个特质： + +``` +package object fruits extends FruitAliases with FruitHelpers { + // helpers and variables follows here +} +``` diff --git a/_zh-cn/tour/packages-and-imports.md b/_zh-cn/tour/packages-and-imports.md index 48ac98fc3d..883c961345 100644 --- a/_zh-cn/tour/packages-and-imports.md +++ b/_zh-cn/tour/packages-and-imports.md @@ -1,9 +1,6 @@ --- layout: tour -title: Packages and Imports - -discourse: true - +title: 包和导入 partof: scala-tour num: 33 @@ -11,4 +8,78 @@ num: 33 language: zh-cn previous-page: named-arguments +next-page: package-objects --- + +# 包和导入 +Scala 使用包来创建命名空间，从而允许你创建模块化程序。 + +## 创建包 +通过在 Scala 文件的头部声明一个或多个包名称来创建包。 + +``` +package users + +class User +``` +一个惯例是将包命名为与包含 Scala 文件的目录名相同。 但是，Scala 并未对文件布局作任何限制。 在一个 sbt 工程中，`package users` 的目录结构可能如下所示： +``` +- ExampleProject + - build.sbt + - project + - src + - main + - scala + - users + User.scala + UserProfile.scala + UserPreferences.scala + - test +``` +注意 `users` 目录是包含在 `scala` 目录中的，该包中包含有多个 Scala 文件。 包中的每个 Scala 文件都可以具有相同的包声明。 声明包的另一种方式是使用大括号： +``` +package users { + package administrators { + class NormalUser + } + package normalusers { + class NormalUser + } +} +``` +如你所见，这允许包嵌套并提供了对范围和封装的更好控制。 + +包名称应全部为小写，如果代码是在拥有独立网站的组织内开发的，则应采用以下的约定格式：`..`。 例如，如果 Google 有一个名为 `SelfDrivingCar` 的项目，则包名称将如下所示： +``` +package com.google.selfdrivingcar.camera + +class Lens +``` +这可以对应于以下目录结构：`SelfDrivingCar/src/main/scala/com/google/selfdrivingcar/camera/Lens.scala` + +## 导入 +`import` 语句用于导入其他包中的成员（类，特质，函数等）。 使用相同包的成员不需要 `import` 语句。 导入语句可以有选择性： +``` +import users._ // 导入包 users 中的所有成员 +import users.User // 导入类 User +import users.{User, UserPreferences} // 仅导入选择的成员 +import users.{UserPreferences => UPrefs} // 导入类并且设置别名 +``` + +Scala 不同于 Java 的一点是 Scala 可以在任何地方使用导入： + +```scala mdoc +def sqrtplus1(x: Int) = { + import scala.math.sqrt + sqrt(x) + 1.0 +} +``` +如果存在命名冲突并且你需要从项目的根目录导入，请在包名称前加上 `_root_`： +``` +package accounts + +import _root_.users._ +``` + + +注意：包 `scala` 和 `java.lang` 以及 `object Predef` 是默认导入的。 diff --git a/_zh-cn/tour/pattern-matching.md b/_zh-cn/tour/pattern-matching.md index 96d9d849b2..36ad508a7c 100644 --- a/_zh-cn/tour/pattern-matching.md +++ b/_zh-cn/tour/pattern-matching.md @@ -1,9 +1,6 @@ --- layout: tour -title: Pattern Matching - -discourse: false - +title: 模式匹配 partof: scala-tour num: 11 @@ -13,3 +10,142 @@ language: zh-cn next-page: singleton-objects previous-page: case-classes --- + +模式匹配是检查某个值（value）是否匹配某一个模式的机制，一个成功的匹配同时会将匹配值解构为其组成部分。它是Java中的`switch`语句的升级版，同样可以用于替代一系列的 if/else 语句。 + +## 语法 +一个模式匹配语句包括一个待匹配的值，`match`关键字，以及至少一个`case`语句。 + +```scala mdoc +import scala.util.Random + +val x: Int = Random.nextInt(10) + +x match { + case 0 => "zero" + case 1 => "one" + case 2 => "two" + case _ => "other" +} +``` +上述代码中的`val x`是一个0到10之间的随机整数，将它放在`match`运算符的左侧对其进行模式匹配，`match`的右侧是包含4条`case`的表达式，其中最后一个`case _`表示匹配其余所有情况，在这里就是其他可能的整型值。 + +`match`表达式具有一个结果值 +```scala mdoc +def matchTest(x: Int): String = x match { + case 1 => "one" + case 2 => "two" + case _ => "other" +} +matchTest(3) // other +matchTest(1) // one +``` +这个`match`表达式是String类型的，因为所有的情况（case）均返回String，所以`matchTest`函数的返回值是String类型。 + +## 样例类（case classes）的匹配 + +样例类非常适合用于模式匹配。 + +```scala mdoc +abstract class Notification + +case class Email(sender: String, title: String, body: String) extends Notification + +case class SMS(caller: String, message: String) extends Notification + +case class VoiceRecording(contactName: String, link: String) extends Notification + + +``` + +`Notification` 是一个虚基类，它有三个具体的子类`Email`, `SMS`和`VoiceRecording`，我们可以在这些样例类(Case Class)上像这样使用模式匹配： + +``` +def showNotification(notification: Notification): String = { + notification match { + case Email(sender, title, _) => + s"You got an email from $sender with title: $title" + case SMS(number, message) => + s"You got an SMS from $number! Message: $message" + case VoiceRecording(name, link) => + s"you received a Voice Recording from $name! Click the link to hear it: $link" + } +} +val someSms = SMS("12345", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") + +println(showNotification(someSms)) // prints You got an SMS from 12345! Message: Are you there? + +println(showNotification(someVoiceRecording)) // you received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123 +``` +`showNotification`函数接受一个抽象类`Notification`对象作为输入参数，然后匹配其具体类型。（也就是判断它是一个`Email`，`SMS`，还是`VoiceRecording`）。在`case Email(sender, title, _)`中，对象的`sender`和`title`属性在返回值中被使用，而`body`属性则被忽略，故使用`_`代替。 + +## 模式守卫（Pattern guards） +为了让匹配更加具体，可以使用模式守卫，也就是在模式后面加上`if `。 +``` + +def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String = { + notification match { + case Email(sender, _, _) if importantPeopleInfo.contains(sender) => + "You got an email from special someone!" + case SMS(number, _) if importantPeopleInfo.contains(number) => + "You got an SMS from special someone!" + case other => + showNotification(other) // nothing special, delegate to our original showNotification function + } +} + +val importantPeopleInfo = Seq("867-5309", "jenny@gmail.com") + +val someSms = SMS("867-5309", "Are you there?") +val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123") +val importantEmail = Email("jenny@gmail.com", "Drinks tonight?", "I'm free after 5!") +val importantSms = SMS("867-5309", "I'm here! Where are you?") + +println(showImportantNotification(someSms, importantPeopleInfo)) +println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) +println(showImportantNotification(importantEmail, importantPeopleInfo)) +println(showImportantNotification(importantSms, importantPeopleInfo)) +``` + +在`case Email(sender, _, _) if importantPeopleInfo.contains(sender)`中，除了要求`notification`是`Email`类型外，还需要`sender`在重要人物列表`importantPeopleInfo`中，才会匹配到该模式。 + + +## 仅匹配类型 +也可以仅匹配类型，如下所示： +```scala mdoc +abstract class Device +case class Phone(model: String) extends Device { + def screenOff = "Turning screen off" +} +case class Computer(model: String) extends Device { + def screenSaverOn = "Turning screen saver on..." +} + +def goIdle(device: Device) = device match { + case p: Phone => p.screenOff + case c: Computer => c.screenSaverOn +} +``` +当不同类型对象需要调用不同方法时，仅匹配类型的模式非常有用，如上代码中`goIdle`函数对不同类型的`Device`有着不同的表现。一般使用类型的首字母作为`case`的标识符，例如上述代码中的`p`和`c`，这是一种惯例。 + +## 密封类 + +特质（trait）和类（class）可以用`sealed`标记为密封的，这意味着其所有子类都必须与之定义在相同文件中，从而保证所有子类型都是已知的。 + +```scala mdoc +sealed abstract class Furniture +case class Couch() extends Furniture +case class Chair() extends Furniture + +def findPlaceToSit(piece: Furniture): String = piece match { + case a: Couch => "Lie on the couch" + case b: Chair => "Sit on the chair" +} +``` +这对于模式匹配很有用，因为我们不再需要一个匹配其他任意情况的`case`。 + +## 备注 + +Scala的模式匹配语句对于使用[样例类（case classes）](case-classes.html)表示的类型非常有用，同时也可以利用[提取器对象（extractor objects）](extractor-objects.html)中的`unapply`方法来定义非样例类对象的匹配。 + diff --git a/_zh-cn/tour/polymorphic-methods.md b/_zh-cn/tour/polymorphic-methods.md index 6c5e459c6e..8b195febc5 100644 --- a/_zh-cn/tour/polymorphic-methods.md +++ b/_zh-cn/tour/polymorphic-methods.md @@ -1,9 +1,6 @@ --- layout: tour -title: Polymorphic Methods - -discourse: false - +title: 多态方法 partof: scala-tour num: 26 @@ -13,3 +10,24 @@ language: zh-cn next-page: type-inference previous-page: implicit-conversions --- + +Scala 中的方法可以按类型和值进行参数化。 语法和泛型类类似。 类型参数括在方括号中，而值参数括在圆括号中。 + +看下面的例子： + +```scala mdoc +def listOfDuplicates[A](x: A, length: Int): List[A] = { + if (length < 1) + Nil + else + x :: listOfDuplicates(x, length - 1) +} +println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3) +println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La) +``` + +方法 `listOfDuplicates` 具有类型参数 `A` 和值参数 `x` 和 `length`。 值 `x` 是 `A` 类型。 如果 `length < 1`，我们返回一个空列表。 否则我们将 `x` 添加到递归调用返回的重复列表中。 （注意，`::` 表示将左侧的元素添加到右侧的列表中。） + +上例中第一次调用方法时，我们显式地提供了类型参数 `[Int]`。 因此第一个参数必须是 `Int` 类型，并且返回类型为 `List[Int]`。 + +上例中第二次调用方法，表明并不总是需要显式提供类型参数。 编译器通常可以根据上下文或值参数的类型来推断。 在这个例子中，`"La"` 是一个 `String`，因此编译器知道 `A` 必须是 `String`。 diff --git a/_zh-cn/tour/regular-expression-patterns.md b/_zh-cn/tour/regular-expression-patterns.md index bf416b902b..9709c0ade8 100644 --- a/_zh-cn/tour/regular-expression-patterns.md +++ b/_zh-cn/tour/regular-expression-patterns.md @@ -1,9 +1,6 @@ --- layout: tour -title: Regular Expression Patterns - -discourse: false - +title: 正则表达式模式 partof: scala-tour num: 13 @@ -13,3 +10,52 @@ language: zh-cn next-page: extractor-objects previous-page: singleton-objects --- + +正则表达式是用来找出数据中的指定模式（或缺少该模式）的字符串。`.r`方法可使任意字符串变成一个正则表达式。 + + +```scala mdoc +import scala.util.matching.Regex + +val numberPattern: Regex = "[0-9]".r + +numberPattern.findFirstMatchIn("awesomepassword") match { + case Some(_) => println("Password OK") + case None => println("Password must contain a number") +} +``` + +上例中，`numberPattern`的类型是正则表达式类`Regex`，其作用是确保密码中包含一个数字。 + +你还可以使用括号来同时匹配多组正则表达式。 + +```scala mdoc +import scala.util.matching.Regex + +val keyValPattern: Regex = "([0-9a-zA-Z-#() ]+): ([0-9a-zA-Z-#() ]+)".r + +val input: String = + """background-color: #A03300; + |background-image: url(img/header100.png); + |background-position: top center; + |background-repeat: repeat-x; + |background-size: 2160px 108px; + |margin: 0; + |height: 108px; + |width: 100%;""".stripMargin + +for (patternMatch <- keyValPattern.findAllMatchIn(input)) + println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}") +``` +上例解析出了一个字符串中的多个键和值，其中的每个匹配又有一组子匹配，结果如下： + +``` +key: background-color value: #A03300 +key: background-image value: url(img +key: background-position value: top center +key: background-repeat value: repeat-x +key: background-size value: 2160px 108px +key: margin value: 0 +key: height value: 108px +key: width value: 100 +``` diff --git a/_zh-cn/tour/self-types.md b/_zh-cn/tour/self-types.md index 1cd47419c6..c30e900480 100644 --- a/_zh-cn/tour/self-types.md +++ b/_zh-cn/tour/self-types.md @@ -1,9 +1,6 @@ --- layout: tour -title: Self-types - -discourse: false - +title: 自类型 partof: scala-tour num: 23 @@ -13,3 +10,27 @@ language: zh-cn next-page: implicit-parameters previous-page: compound-types --- +自类型用于声明一个特质必须混入其他特质，尽管该特质没有直接扩展其他特质。 这使得所依赖的成员可以在没有导入的情况下使用。 + +自类型是一种细化 `this` 或 `this` 别名之类型的方法。 语法看起来像普通函数语法，但是意义完全不一样。 + +要在特质中使用自类型，写一个标识符，跟上要混入的另一个特质，以及 `=>`（例如 `someIdentifier: SomeOtherTrait =>`）。 +```scala mdoc +trait User { + def username: String +} + +trait Tweeter { + this: User => // 重新赋予 this 的类型 + def tweet(tweetText: String) = println(s"$username: $tweetText") +} + +class VerifiedTweeter(val username_ : String) extends Tweeter with User { // 我们混入特质 User 因为 Tweeter 需要 + def username = s"real $username_" +} + +val realBeyoncé = new VerifiedTweeter("Beyoncé") +realBeyoncé.tweet("Just spilled my glass of lemonade") // 打印出 "real Beyoncé: Just spilled my glass of lemonade" +``` + +因为我们在特质 `trait Tweeter` 中定义了 `this: User =>`，现在变量 `username` 可以在 `tweet` 方法内使用。 这也意味着，由于 `VerifiedTweeter` 继承了 `Tweeter`，它还必须混入 `User`（使用 `with User`）。 diff --git a/_zh-cn/tour/singleton-objects.md b/_zh-cn/tour/singleton-objects.md index 70c32748d3..1177e92d49 100644 --- a/_zh-cn/tour/singleton-objects.md +++ b/_zh-cn/tour/singleton-objects.md @@ -1,9 +1,6 @@ --- layout: tour -title: Singleton Objects - -discourse: false - +title: 单例对象 partof: scala-tour num: 12 @@ -13,3 +10,100 @@ language: zh-cn next-page: regular-expression-patterns previous-page: pattern-matching --- + +单例对象是一种特殊的类，有且只有一个实例。和惰性变量一样，单例对象是延迟创建的，当它第一次被使用时创建。 + +当对象定义于顶层时(即没有包含在其他类中)，单例对象只有一个实例。 + +当对象定义在一个类或方法中时，单例对象表现得和惰性变量一样。 + +# 定义一个单例对象 +一个单例对象是就是一个值。单例对象的定义方式很像类，但是使用关键字 `object`： +```scala mdoc +object Box +``` + +下面例子中的单例对象包含一个方法： +``` +package logging + +object Logger { + def info(message: String): Unit = println(s"INFO: $message") +} +``` +方法 `info` 可以在程序中的任何地方被引用。像这样创建功能性方法是单例对象的一种常见用法。 + +下面让我们来看看如何在另外一个包中使用 `info` 方法： + +``` +import logging.Logger.info + +class Project(name: String, daysToComplete: Int) + +class Test { + val project1 = new Project("TPS Reports", 1) + val project2 = new Project("Website redesign", 5) + info("Created projects") // Prints "INFO: Created projects" +} +``` + +因为 import 语句 `import logging.Logger.info`，方法 `info` 在此处是可见的。 + +import语句要求被导入的标识具有一个“稳定路径”，一个单例对象由于全局唯一，所以具有稳定路径。 + +注意：如果一个 `object` 没定义在顶层而是定义在另一个类或者单例对象中，那么这个单例对象和其他类普通成员一样是“路径相关的”。这意味着有两种行为，`class Milk` 和 `class OrangeJuice`，一个类成员 `object NutritionInfo` “依赖”于包装它的实例，要么是牛奶要么是橙汁。 `milk.NutritionInfo` 则完全不同于`oj.NutritionInfo`。 + +## 伴生对象 + +当一个单例对象和某个类共享一个名称时，这个单例对象称为 _伴生对象_。 同理，这个类被称为是这个单例对象的伴生类。类和它的伴生对象可以互相访问其私有成员。使用伴生对象来定义那些在伴生类中不依赖于实例化对象而存在的成员变量或者方法。 +``` +import scala.math._ + +case class Circle(radius: Double) { + import Circle._ + def area: Double = calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = Circle(5.0) + +circle1.area +``` + +这里的 `class Circle` 有一个成员 `area` 是和具体的实例化对象相关的，单例对象 `object Circle` 包含一个方法 `calculateArea` ，它在每一个实例化对象中都是可见的。 + +伴生对象也可以包含工厂方法： +```scala mdoc +class Email(val username: String, val domainName: String) + +object Email { + def fromString(emailString: String): Option[Email] = { + emailString.split('@') match { + case Array(a, b) => Some(new Email(a, b)) + case _ => None + } + } +} + +val scalaCenterEmail = Email.fromString("scala.center@epfl.ch") +scalaCenterEmail match { + case Some(email) => println( + s"""Registered an email + |Username: ${email.username} + |Domain name: ${email.domainName} + """) + case None => println("Error: could not parse email") +} +``` +伴生对象 `object Email` 包含有一个工厂方法 `fromString` 用来根据一个 String 创建 `Email` 实例。在这里我们返回的是 `Option[Email]` 以防有语法分析错误。 + +注意：类和它的伴生对象必须定义在同一个源文件里。如果需要在 REPL 里定义类和其伴生对象，需要将它们定义在同一行或者进入 `:paste` 模式。 + +## Java 程序员的注意事项 ## + +在 Java 中 `static` 成员对应于 Scala 中的伴生对象的普通成员。 + +在 Java 代码中调用伴生对象时，伴生对象的成员会被定义成伴生类中的 `static` 成员。这称为 _静态转发_。这种行为发生在当你自己没有定义一个伴生类时。 diff --git a/_zh-cn/tour/tour-of-scala.md b/_zh-cn/tour/tour-of-scala.md index aa7ee75345..78b70dd115 100644 --- a/_zh-cn/tour/tour-of-scala.md +++ b/_zh-cn/tour/tour-of-scala.md @@ -1,9 +1,6 @@ --- layout: tour title: 导言 - -discourse: false - partof: scala-tour num: 1 @@ -14,9 +11,9 @@ next-page: basics --- ## 欢迎来到Scala之旅 -本次之旅包含了对于大多数Scala特性的简单介绍，主要针对的是这门语言的初学者。 +本次 Scala 之旅教程包含了对于大多数 Scala 特性的简单介绍。主要针对 Scala 这门语言的初学者。 -这是个简化的教程，如果希望得到完整的话，可以考虑购买[书籍](/books.html)或者参考[其他资源](/learn.html)。 +这是个简化的教程，如果希望得到完整的话，可以考虑购买[书籍](/books.html)或者参考[其他资源](/online-courses.html)。 ## Scala是什么？ Scala是一门现代的多范式语言，志在以简洁、优雅及类型安全的方式来表达常用的编程模型。它平滑地集成了面向对象和函数式语言的特性。 @@ -36,7 +33,7 @@ Scala配备了一个拥有强大表达能力的类型系统，它可以静态地 * [泛型类](generic-classes.html) * [型变注解](variances.html) * [上](upper-type-bounds.html)、[下](lower-type-bounds.html) 类型边界 -* 作为对象成员的[内部类](inner-classes.html)和[抽象类型](abstract-types.html) +* 作为对象成员的[内部类](inner-classes.html)和[抽象类型](abstract-type-members.html) * [复合类型](compound-types.html) * [显式类型的自我引用](self-types.html) * [隐式参数](implicit-parameters.html)和[隐式转化](implicit-conversions.html) @@ -50,7 +47,7 @@ Scala配备了一个拥有强大表达能力的类型系统，它可以静态地 很多场景下，这些扩展可以不通过类似宏（macros）的元编程工具完成。例如： -* [隐式类](http://docs.scala-lang.org/overviews/core/implicit-classes.html)允许给已有的类型添加扩展方法。 +* [隐式类](https://docs.scala-lang.org/overviews/core/implicit-classes.html)允许给已有的类型添加扩展方法。 * [字符串插值](/overviews/core/string-interpolation.html)可以让用户使用自定义的插值器进行扩展。 ## Scala的互操作性 @@ -61,4 +58,4 @@ Scala设计的目标是与流行的Java运行环境（JRE）进行良好的互 ## 尽享学习之乐 -请点击菜单上的[下一页](basics.html)继续阅读。 \ No newline at end of file +请点击菜单上的[下一页](basics.html)继续阅读。 diff --git a/_zh-cn/tour/traits.md b/_zh-cn/tour/traits.md index 7c646b44f5..83b7a39633 100644 --- a/_zh-cn/tour/traits.md +++ b/_zh-cn/tour/traits.md @@ -1,21 +1,16 @@ --- layout: tour title: 特质 - -discourse: false - partof: scala-tour num: 5 language: zh-cn -next-page: mixin-class-composition +next-page: tuples previous-page: classes topics: traits prerequisite-knowledge: expressions, classes, generics, objects, companion-objects - -redirect_from: "/tutorials/tour/traits.html" --- 特质 (Traits) 用于在类 (Class)之间共享程序接口 (Interface)和字段 (Fields)。 它们类似于Java 8的接口。 类和对象 (Objects)可以扩展特质，但是特质不能被实例化，因此特质没有参数。 @@ -25,12 +20,12 @@ redirect_from: "/tutorials/tour/traits.html" ## 定义一个特质 最简化的特质就是关键字trait+标识符： -```tut +```scala mdoc trait HairColor ``` 特征作为泛型类型和抽象方法非常有用。 -```tut +```scala mdoc trait Iterator[A] { def hasNext: Boolean def next(): A @@ -42,7 +37,7 @@ trait Iterator[A] { ## 使用特质 使用 `extends` 关键字来扩展特征。然后使用 `override` 关键字来实现trait里面的任何抽象成员： -```tut +```scala mdoc:nest trait Iterator[A] { def hasNext: Boolean def next(): A @@ -69,7 +64,7 @@ iterator.next() // returns 1 ## 子类型 凡是需要特质的地方，都可以由该特质的子类型来替换。 -```tut +```scala mdoc import scala.collection.mutable.ArrayBuffer trait Pet { diff --git a/_zh-cn/tour/tuples.md b/_zh-cn/tour/tuples.md new file mode 100644 index 0000000000..871c70c3b5 --- /dev/null +++ b/_zh-cn/tour/tuples.md @@ -0,0 +1,93 @@ +--- +layout: tour +title: 元组 +partof: scala-tour + +num: + +language: zh-cn + +next-page: mixin-class-composition +previous-page: traits +topics: tuples +--- + +在 Scala 中，元组是一个可以容纳不同类型元素的类。 +元组是不可变的。 + +当我们需要从函数返回多个值时，元组会派上用场。 + +元组可以创建如下： + +```scala mdoc +val ingredient = ("Sugar" , 25):Tuple2[String, Int] +``` +这将创建一个包含一个 String 元素和一个 Int 元素的元组。 + +Scala 中的元组包含一系列类：Tuple2，Tuple3等，直到 Tuple22。 +因此，当我们创建一个包含 n 个元素（n 位于 2 和 22 之间）的元组时，Scala 基本上就是从上述的一组类中实例化 +一个相对应的类，使用组成元素的类型进行参数化。 +上例中，`ingredient` 的类型为 `Tuple2[String, Int]`。 + +## 访问元素 + +使用下划线语法来访问元组中的元素。 +'tuple._n' 取出了第 n 个元素（假设有足够多元素）。 + +```scala mdoc +println(ingredient._1) // Sugar + +println(ingredient._2) // 25 +``` + +## 解构元组数据 + +Scala 元组也支持解构。 + +```scala mdoc +val (name, quantity) = ingredient + +println(name) // Sugar + +println(quantity) // 25 +``` + +元组解构也可用于模式匹配。 + +```scala mdoc +val planetDistanceFromSun = List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6 ), ("Mars", 227.9), ("Jupiter", 778.3)) + +planetDistanceFromSun.foreach{ tuple => { + + tuple match { + + case ("Mercury", distance) => println(s"Mercury is $distance millions km far from Sun") + + case p if(p._1 == "Venus") => println(s"Venus is ${p._2} millions km far from Sun") + + case p if(p._1 == "Earth") => println(s"Blue planet is ${p._2} millions km far from Sun") + + case _ => println("Too far....") + + } + + } + +} +``` + +或者，在 'for' 表达式中。 + +```scala mdoc +val numPairs = List((2, 5), (3, -7), (20, 56)) + +for ((a, b) <- numPairs) { + + println(a * b) + +} +``` + +类型 `Unit` 的值 `()` 在概念上与类型 `Tuple0` 的值 `()` 相同。 `Tuple0` 只能有一个值，因为它没有元素。 + +用户有时可能在元组和 case 类之间难以选择。 通常，如果元素具有更多含义，则首选 case 类。 diff --git a/_zh-cn/tour/type-inference.md b/_zh-cn/tour/type-inference.md index f2f4581966..3b50faf3a4 100644 --- a/_zh-cn/tour/type-inference.md +++ b/_zh-cn/tour/type-inference.md @@ -1,9 +1,6 @@ --- layout: tour -title: Type Inference - -discourse: false - +title: 类型推断 partof: scala-tour num: 27 @@ -13,3 +10,65 @@ language: zh-cn next-page: operators previous-page: polymorphic-methods --- + +Scala 编译器通常可以推断出表达式的类型，因此你不必显式地声明它。 + +## 省略类型 + +```scala mdoc +val businessName = "Montreux Jazz Café" +``` +编译器可以发现 `businessName` 是 String 类型。 它的工作原理和方法类似： + +```scala mdoc +def squareOf(x: Int) = x * x +``` +编译器可以推断出方法的返回类型为 `Int`，因此不需要明确地声明返回类型。 + +对于递归方法，编译器无法推断出结果类型。 下面这个程序就是由于这个原因而编译失败： + +```scala mdoc:fail +def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1) +``` + +当调用 [多态方法](polymorphic-methods.html) 或实例化 [泛型类](generic-classes.html) 时，也不必明确指定类型参数。 Scala 编译器将从上下文和实际方法的类型/构造函数参数的类型推断出缺失的类型参数。 + +看下面两个例子： + +```scala mdoc +case class MyPair[A, B](x: A, y: B) +val p = MyPair(1, "scala") // type: MyPair[Int, String] + +def id[T](x: T) = x +val q = id(1) // type: Int +``` + +编译器使用传给 `MyPair` 参数的类型来推断出 `A` 和 `B` 的类型。对于 `x` 的类型同样如此。 + +## 参数 + +编译器从不推断方法形式参数的类型。 但是，在某些情况下，当函数作为参数传递时，编译器可以推断出匿名函数形式参数的类型。 + +```scala mdoc +Seq(1, 3, 4).map(x => x * 2) // List(2, 6, 8) +``` + +方法 map 的形式参数是 `f: A => B`。 因为我们把整数放在 `Seq` 中，编译器知道 `A` 是 `Int` 类型 (即 `x` 是一个整数)。 因此，编译器可以从 `x * 2` 推断出 `B` 是 `Int` 类型。 + +## 何时 _不要_ 依赖类型推断 + +通常认为，公开可访问的 API 成员应该具有显示类型声明以增加可读性。 因此，我们建议你将代码中向用户公开的任何 API 明确指定类型。 + +此外，类型推断有时会推断出太具体的类型。 假设我们这么写： + +```scala +var obj = null +``` + +我们就不能进行重新赋值： + +```scala mdoc:fail +obj = new AnyRef +``` + +它不能编译，因为 `obj` 推断出的类型是 `Null`。 由于该类型的唯一值是 `null`，因此无法分配其他的值。 diff --git a/_zh-cn/tour/unified-types.md b/_zh-cn/tour/unified-types.md index 69a01b09d7..904684e4dc 100644 --- a/_zh-cn/tour/unified-types.md +++ b/_zh-cn/tour/unified-types.md @@ -1,9 +1,6 @@ --- layout: tour title: 统一类型 - -discourse: true - partof: scala-tour num: 3 @@ -13,8 +10,6 @@ language: zh-cn next-page: classes previous-page: basics prerequisite-knowledge: classes, basics - -redirect_from: "/tutorials/tour/unified-types.html" --- 在Scala中，所有的值都有类型，包括数值和函数。下图阐述了类型层次结构的一个子集。 @@ -23,7 +18,7 @@ redirect_from: "/tutorials/tour/unified-types.html" ## Scala类型层次结构 ## -[`Any`](http://www.scala-lang.org/api/2.12.1/scala/Any.html)是所有类型的超类型，也称为顶级类 +[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html)是所有类型的超类型，也称为顶级类 型。它定义了一些通用的方法如`equals`、`hashCode`和`toString`。`Any`有两个直接子类：`AnyVal`和`AnyRef`。 `AnyVal`代表值类型。有9个预定义的非空的值类型分别是：`Double`、`Float`、`Long`、`Int`、`Short`、`Byte`、`Char`、`Unit`和`Boolean`。`Unit`是不带任何意义的值类型，它仅有一个实例可以像这样声明：`()`。所有的函数必须有返回，所以说有时候`Unit`也是有用的返回类型。 @@ -32,7 +27,7 @@ redirect_from: "/tutorials/tour/unified-types.html" 这里有一个例子，说明了字符串、整型、布尔值和函数都是对象，这一点和其他对象一样： -```tut +```scala mdoc val list: List[Any] = List( "a string", 732, // an integer @@ -44,7 +39,7 @@ val list: List[Any] = List( list.foreach(element => println(element)) ``` -这里定义了一个类型`List`的变量`list`。这个列表里由多种类型进行初始化，但是它们都是`scala.Any`的实例，所以可以把它们加入到列表中。 +这里定义了一个类型`List`的变量`list`。这个列表里由多种类型进行初始化，但是它们都是`scala.Any`的实例，所以可以把它们加入到列表中。 下面是程序的输出： @@ -62,9 +57,9 @@ true 例如： -```tut +```scala mdoc val x: Long = 987654321 -val y: Float = x // 9.8765434E8 (note that some precision is lost in this case) +val y: Float = x.toFloat // 9.8765434E8 (note that some precision is lost in this case) val face: Char = '☺' val number: Int = face // 9786 @@ -74,7 +69,7 @@ val number: Int = face // 9786 ``` val x: Long = 987654321 -val y: Float = x // 9.8765434E8 +val y: Float = x.toFloat // 9.8765434E8 val z: Long = y // Does not conform ``` diff --git a/_zh-cn/tour/upper-type-bounds.md b/_zh-cn/tour/upper-type-bounds.md index fe321e4a0c..917bc3e2e4 100644 --- a/_zh-cn/tour/upper-type-bounds.md +++ b/_zh-cn/tour/upper-type-bounds.md @@ -1,9 +1,6 @@ --- layout: tour -title: Upper Type Bounds - -discourse: false - +title: 类型上界 partof: scala-tour num: 18 @@ -13,3 +10,42 @@ language: zh-cn next-page: lower-type-bounds previous-page: variances --- + +在Scala中，[类型参数](generic-classes.html)和[抽象类型](abstract-type-members.html)都可以有一个类型边界约束。这种类型边界在限制类型变量实际取值的同时还能展露类型成员的更多信息。比如像`T <: A`这样声明的类型上界表示类型变量`T`应该是类型`A`的子类。下面的例子展示了类`PetContainer`的一个类型参数的类型上界。 + +```scala mdoc +abstract class Animal { + def name: String +} + +abstract class Pet extends Animal {} + +class Cat extends Pet { + override def name: String = "Cat" +} + +class Dog extends Pet { + override def name: String = "Dog" +} + +class Lion extends Animal { + override def name: String = "Lion" +} + +class PetContainer[P <: Pet](p: P) { + def pet: P = p +} + +val dogContainer = new PetContainer[Dog](new Dog) +val catContainer = new PetContainer[Cat](new Cat) +``` + +```scala mdoc:fail +// this would not compile +val lionContainer = new PetContainer[Lion](new Lion) +``` +类`PetContainer`接受一个必须是`Pet`子类的类型参数`P`。因为`Dog`和`Cat`都是`Pet`的子类，所以可以构造`PetContainer[Dog]`和`PetContainer[Cat]`。但在尝试构造`PetContainer[Lion]`的时候会得到下面的错误信息： + +`type arguments [Lion] do not conform to class PetContainer's type parameter bounds [P <: Pet]` + +这是因为`Lion`并不是`Pet`的子类。 diff --git a/_zh-cn/tour/variances.md b/_zh-cn/tour/variances.md index 49e9e0c066..ecd5249a35 100644 --- a/_zh-cn/tour/variances.md +++ b/_zh-cn/tour/variances.md @@ -1,9 +1,6 @@ --- layout: tour -title: Variance - -discourse: false - +title: 型变 partof: scala-tour num: 17 @@ -13,3 +10,143 @@ language: zh-cn next-page: upper-type-bounds previous-page: generic-classes --- + +型变是复杂类型的子类型关系与其组件类型的子类型关系的相关性。 Scala支持 [泛型类](generic-classes.html) 的类型参数的型变注释，允许它们是协变的，逆变的，或在没有使用注释的情况下是不变的。 在类型系统中使用型变允许我们在复杂类型之间建立直观的连接，而缺乏型变则会限制类抽象的重用性。 + +```scala mdoc +class Foo[+A] // A covariant class +class Bar[-A] // A contravariant class +class Baz[A] // An invariant class +``` + +### 协变 + +使用注释 `+A`，可以使一个泛型类的类型参数 `A` 成为协变。 对于某些类 `class List[+A]`，使 `A` 成为协变意味着对于两种类型 `A` 和 `B`，如果 `A` 是 `B` 的子类型，那么 `List[A]` 就是 `List[B]` 的子类型。 这允许我们使用泛型来创建非常有用和直观的子类型关系。 + +考虑以下简单的类结构： + +```scala mdoc +abstract class Animal { + def name: String +} +case class Cat(name: String) extends Animal +case class Dog(name: String) extends Animal +``` + +类型 `Cat` 和 `Dog` 都是 `Animal` 的子类型。 Scala 标准库有一个通用的不可变的类 `sealed abstract class List[+A]`，其中类型参数 `A` 是协变的。 这意味着 `List[Cat]` 是 `List[Animal]`，`List[Dog]` 也是 `List[Animal]`。 直观地说，猫的列表和狗的列表都是动物的列表是合理的，你应该能够用它们中的任何一个替换 `List[Animal]`。 + +在下例中，方法 `printAnimalNames` 将接受动物列表作为参数，并且逐行打印出它们的名称。 如果 `List[A]` 不是协变的，最后两个方法调用将不能编译，这将严重限制 `printAnimalNames` 方法的适用性。 + +```scala mdoc +object CovarianceTest extends App { + def printAnimalNames(animals: List[Animal]): Unit = { + animals.foreach { animal => + println(animal.name) + } + } + + val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom")) + val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex")) + + printAnimalNames(cats) + // Whiskers + // Tom + + printAnimalNames(dogs) + // Fido + // Rex +} +``` + +### 逆变 + +通过使用注释 `-A`，可以使一个泛型类的类型参数 `A` 成为逆变。 与协变类似，这会在类及其类型参数之间创建一个子类型关系，但其作用与协变完全相反。 也就是说，对于某个类 `class Writer[-A]` ，使 `A` 逆变意味着对于两种类型 `A` 和 `B`，如果 `A` 是 `B` 的子类型，那么 `Writer[B]` 是 `Writer[A]` 的子类型。 + +考虑在下例中使用上面定义的类 `Cat`，`Dog` 和 `Animal` ： + +```scala mdoc +abstract class Printer[-A] { + def print(value: A): Unit +} +``` + +这里 `Printer[A]` 是一个简单的类，用来打印出某种类型的 `A`。 让我们定义一些特定的子类： + +```scala mdoc +class AnimalPrinter extends Printer[Animal] { + def print(animal: Animal): Unit = + println("The animal's name is: " + animal.name) +} + +class CatPrinter extends Printer[Cat] { + def print(cat: Cat): Unit = + println("The cat's name is: " + cat.name) +} +``` + +如果 `Printer[Cat]` 知道如何在控制台打印出任意 `Cat`，并且 `Printer[Animal]` 知道如何在控制台打印出任意 `Animal`，那么 `Printer[Animal]` 也应该知道如何打印出 `Cat` 就是合理的。 反向关系不适用，因为 `Printer[Cat]` 并不知道如何在控制台打印出任意 `Animal`。 因此，如果我们愿意，我们应该能够用 `Printer[Animal]` 替换 `Printer[Cat]`，而使 `Printer[A]` 逆变允许我们做到这一点。 + +```scala mdoc +object ContravarianceTest extends App { + val myCat: Cat = Cat("Boots") + + def printMyCat(printer: Printer[Cat]): Unit = { + printer.print(myCat) + } + + val catPrinter: Printer[Cat] = new CatPrinter + val animalPrinter: Printer[Animal] = new AnimalPrinter + + printMyCat(catPrinter) + printMyCat(animalPrinter) +} +``` + +这个程序的输出如下： + +``` +The cat's name is: Boots +The animal's name is: Boots +``` + +### 不变 + +默认情况下，Scala中的泛型类是不变的。 这意味着它们既不是协变的也不是逆变的。 在下例中，类 `Container` 是不变的。 `Container[Cat]` _不是_ `Container[Animal]`，反之亦然。 + +```scala mdoc +class Container[A](value: A) { + private var _value: A = value + def getValue: A = _value + def setValue(value: A): Unit = { + _value = value + } +} +``` + +可能看起来一个 `Container[Cat]` 自然也应该是一个 `Container[Animal]`，但允许一个可变的泛型类成为协变并不安全。 在这个例子中，`Container` 是不变的非常重要。 假设 `Container` 实际上是协变的，下面的情况可能会发生： + +``` +val catContainer: Container[Cat] = new Container(Cat("Felix")) +val animalContainer: Container[Animal] = catContainer +animalContainer.setValue(Dog("Spot")) +val cat: Cat = catContainer.getValue // 糟糕，我们最终会将一只狗作为值分配给一只猫 +``` + +幸运的是，编译器在此之前就会阻止我们。 + +### 其他例子 + +另一个可以帮助理解型变的例子是 Scala 标准库中的 `trait Function1[-T, +R]`。 `Function1` 表示具有一个参数的函数，其中第一个类型参数 `T` 表示参数类型，第二个类型参数 `R` 表示返回类型。 `Function1` 在其参数类型上是逆变的，并且在其返回类型上是协变的。 对于这个例子，我们将使用文字符号 `A => B` 来表示 `Function1[A, B]`。 + +假设前面使用过的类似 `Cat`，`Dog`，`Animal` 的继承关系，加上以下内容： + +```scala mdoc +abstract class SmallAnimal extends Animal +case class Mouse(name: String) extends SmallAnimal +``` + +假设我们正在处理接受动物类型的函数，并返回他们的食物类型。 如果我们想要一个 `Cat => SmallAnimal`（因为猫吃小动物），但是给它一个 `Animal => Mouse`，我们的程序仍然可以工作。 直观地看，一个 `Animal => Mouse` 的函数仍然会接受一个 `Cat` 作为参数，因为 `Cat` 即是一个 `Animal`，并且这个函数返回一个 `Mouse`，也是一个 `SmallAnimal`。 既然我们可以安全地，隐式地用后者代替前者，我们可以说 `Animal => Mouse` 是 `Cat => SmallAnimal` 的子类型。 + +### 与其他语言的比较 + +某些与 Scala 类似的语言以不同的方式支持型变。 例如，Scala 中的型变注释与 C# 中的非常相似，在定义类抽象时添加型变注释（声明点型变）。 但是在Java中，当类抽象被使用时（使用点型变），才会给出型变注释。 diff --git a/_zh-cn/tutorials/scala-for-java-programmers.md b/_zh-cn/tutorials/scala-for-java-programmers.md index fd792844b3..a3327a1963 100644 --- a/_zh-cn/tutorials/scala-for-java-programmers.md +++ b/_zh-cn/tutorials/scala-for-java-programmers.md @@ -1,10 +1,8 @@ --- -layout: overview +layout: singlepage-overview title: 给 Java 工程师的 Scala 入门教学 -overview: scala-for-java-programmers -discourse: false -multilingual-overview: true +partof: scala-for-java-programmers language: zh-cn --- @@ -20,7 +18,7 @@ Lightsing 译 这里用标准的 *Hello world* 程序作为第一个例子。虽然它很无趣，但让我们可以用少量语言特质来演示 Scala 工具。程序如下： object HelloWorld { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { println("Hello, world!") } } @@ -62,7 +60,7 @@ Java 的标准函数库定义了一些有用的工具类，如 `Date` 跟 `DateF import java.text.DateFormat._ object FrenchDate { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val now = new Date val df = getDateInstance(LONG, Locale.FRANCE) println(df format now) @@ -87,7 +85,7 @@ Scala 的导入表达式跟 Java 非常像，但更为强大。如第一行， ## 一切都是对象 -Scala 是一个纯粹的面向对象语言，这句话的意思是说，*所有东西*都是对象，包括数字、函数。因为 Java 将基本类型 (如 `boolean` 与 `int` ) 跟参照类型分开，而且没有办法像操作变量一样操作函数，从这角度来看 Scala 跟 Java 是不同的。 +Scala 是一个纯粹的面向对象语言，意即包括数字、函数在内的*一切*都是对象。这跟 Java 不同，因为 Java 的基本类型 (如 `boolean` 与 `int` ) 和引用类型是有区别的。 ### 数字是对象 @@ -97,23 +95,13 @@ Scala 是一个纯粹的面向对象语言，这句话的意思是说，*所有 只有使用函数调用，因为像前一节一样，该式等价于 - (1).+(((2).*(3))./(x)) + 1.+(2.*(3)./(x)) 这也表示着 `+`、`*` 之类的在 Scala 里是合法的标识符。 -因为Scala的词法分析器对于符号采用最长匹配，在第二版的表达式当中，那些括号是必要的。也就是说分析器会把这个表达式： - - 1.+(2) - -拆成 `1.`、`+`、`2` 这三个标记。会这样拆分是因为 `1.` 既是合法匹配的同时又比 `1` 长。 `1.` 会被解释成字面常数 `1.0`，使得它被视为 `Double` 而不是 `Int`。把表达式写成： - - (1).+(2) - -可以避免 `1` 被解释成 `Double`。 - ### 函数是对象 -可能令 Java 程序员更为惊讶的会是，Scala 中函数也是对象。因此，将函数当做对象传递、把它们存入变量、从其他函数返回函数都是可能的。能够像操作变量一样的操作函数这点是*函数式编程*这一非常有趣的程序设计思想的基石之一。 +Scala 中的函数也是对象，所以将函数当做对象传递、把它们存入变量、从其他函数返回函数都是可能的。能够像操作变量一样的操作函数这点是*函数式编程*这一非常有趣的程序设计思想的基石之一。 为何把函数当做变量一样的操作会很有用呢，让我们考虑一个定时函数，功能是每秒执行一些动作。我们要怎么将这动作传给它？最直接的便是将这动作视为函数传入。应该有不少程序员对这种简单传递函数的行为很熟悉：通常在用户界面相关的程序上，用来注册一些当事件发生时被调用的回调函数。 @@ -126,7 +114,7 @@ Scala 是一个纯粹的面向对象语言，这句话的意思是说，*所有 def timeFlies() { println("time flies like an arrow...") } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(timeFlies) } } @@ -141,7 +129,7 @@ Scala 是一个纯粹的面向对象语言，这句话的意思是说，*所有 def oncePerSecond(callback: () => Unit) { while (true) { callback(); Thread sleep 1000 } } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(() => println("time flies like an arrow...")) } @@ -169,7 +157,7 @@ Scala 是一个纯粹的面向对象语言，这句话的意思是说，*所有 函数 `re`、`im` 有个小问题，为了调用函数，我们必须在函数名称后面加上一对空括号，如这个例子： object ComplexNumbers { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val c = new Complex(1.2, 3.4) println("imaginary part: " + c.im()) } @@ -273,7 +261,7 @@ Java 中我们会将这个树用一个抽象父类表示，然后每种节点跟 我们还没有探讨完模式匹配的全部功能，不过为了让这份文件保持简短，先就此打住。我们还是希望能看到这两个函数在真正的示例如何作用。因此让我们写一个简单的 `main` 函数，对表达式 `(x+x)+(7+y)` 做一些操作：先在环境 `{ x -> 5, y -> 7 }` 下计算结果，然后在对 `x` 接着对 `y` 取导数。 - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) val env: Environment = { case "x" => 5 case "y" => 7 } println("Expression: " + exp) @@ -320,7 +308,7 @@ Java 中我们会将这个树用一个抽象父类表示，然后每种节点跟 def year = y def month = m def day = d - override def toString(): String = year + "-" + month + "-" + day + override def toString(): String = s"$year-$month-$day" 这边要注意的是声明在类名称跟参数之后的 `extends Ord`。这个语法声明了 `Date` 继承 `Ord` 特质。 @@ -373,7 +361,7 @@ Scala 借由可定义泛型类 (跟函数) 来解决这问题。让我们借由 为了使用 `Reference` 类型，我们必须指定 `T`，也就是这容器所包容的元素类型。举例来说，创造并使用该容器来容纳整数，我们可以这样写： object IntegerReference { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val cell = new Reference[Int] cell.set(13) println("Reference contains the half of " + (cell.get * 2)) diff --git a/_zh-tw/tutorials/scala-for-java-programmers.md b/_zh-tw/tutorials/scala-for-java-programmers.md index 15d95b0b27..333744ecea 100755 --- a/_zh-tw/tutorials/scala-for-java-programmers.md +++ b/_zh-tw/tutorials/scala-for-java-programmers.md @@ -3,8 +3,6 @@ layout: singlepage-overview title: 給 Java 程式設計師的 Scala 入門教學 partof: scala-for-java-programmers - -discourse: false language: zh-tw --- @@ -20,7 +18,7 @@ Chikei Lee 譯 這邊用標準的 *Hello world* 程式作為第一個例子。雖然它很無趣，可是這讓我們在僅用少量語言特性下演示 Scala 工具。程式如下： object HelloWorld { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { println("Hello, world!") } } @@ -62,7 +60,7 @@ Java 的標準函式庫定義了一些有用的工具類別，如 `Date` 跟 `Da import java.text.DateFormat._ object FrenchDate { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val now = new Date val df = getDateInstance(LONG, Locale.FRANCE) println(df format now) @@ -97,20 +95,10 @@ Scala 是一個純粹的物件導向語言，這句話的意思是說，*所有 只有使用函式呼叫，因為像前一節一樣，該式等價於 - (1).+(((2).*(3))./(x)) + 1.+(2.*(3)./(x)) 這也表示著 `+`、`*` 之類的在 Scala 裡是合法的識別符號。 -因為Scala的詞法分析器對於符號採用最長匹配，在第二版的表示式當中，那些括號是必要的。也就是說分析器會把這個表示式： - - 1.+(2) - -拆成 `1.`、`+`、`2` 這三個符號。會這樣拆分是因為 `1.` 既是合法匹配同時又比 `1` 長。 `1.` 會被解釋成字面常數 `1.0`，使得它被視為 `Double` 而不是 `Int`。把表示式寫成： - - (1).+(2) - -可以避免 `1` 被解釋成 `Double`。 - ### 函式是物件 可能令 Java 程式員更為驚訝的會是，Scala 中函式也是物件。因此，將函式當做引數傳遞、把它們存入變數、從其他函式返回函式都是可能的。能夠像操作變數一樣的操作函式這點是*函數編程*這一非常有趣的程設典範的基石之一。 @@ -126,7 +114,7 @@ Scala 是一個純粹的物件導向語言，這句話的意思是說，*所有 def timeFlies() { println("time flies like an arrow...") } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(timeFlies) } } @@ -141,7 +129,7 @@ Scala 是一個純粹的物件導向語言，這句話的意思是說，*所有 def oncePerSecond(callback: () => Unit) { while (true) { callback(); Thread sleep 1000 } } - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { oncePerSecond(() => println("time flies like an arrow...")) } @@ -169,7 +157,7 @@ Scala 是一個純粹的物件導向語言，這句話的意思是說，*所有 函式 `re`、`im` 有個小問題，為了呼叫函式，我們必須在函式名稱後面加上一對空括號，如這個例子： object ComplexNumbers { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val c = new Complex(1.2, 3.4) println("imaginary part: " + c.im()) } @@ -273,7 +261,7 @@ Java 中我們會將這個樹用一個抽象母類別表示，然後每種節點 我們還沒有探討完模式匹配的全部功能，不過為了讓這份文件保持簡短，先就此打住。我們還是希望能看到這兩個函式在真正的範例如何作用。因此讓我們寫一個簡單的 `main` 函數，對表示式 `(x+x)+(7+y)` 做一些操作：先在環境 `{ x -> 5, y -> 7 }` 下計算結果，然後在對 `x` 接著對 `y` 取導數。 - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y"))) val env: Environment = { case "x" => 5 case "y" => 7 } println("Expression: " + exp) @@ -320,7 +308,7 @@ Java 中我們會將這個樹用一個抽象母類別表示，然後每種節點 def year = y def month = m def day = d - override def toString(): String = year + "-" + month + "-" + day + override def toString(): String = s"$year-$month-$day" 這邊要注意的是宣告在類別名稱跟參數之後的 `extends Ord`。這個語法宣告了 `Date` 繼承 `Ord` 特質。 @@ -373,7 +361,7 @@ Scala 藉由可定義泛型類別 (跟函式) 來解決這問題。讓我們藉 為了使用 `Reference` 類型，我們必須指定 `T`，也就是這容器所包容的元素型別。舉例來說，創造並使用該容器來容納整數，我們可以這樣寫： object IntegerReference { - def main(args: Array[String]) { + def main(args: Array[String]): Unit = { val cell = new Reference[Int] cell.set(13) println("Reference contains the half of " + (cell.get * 2)) diff --git a/api/all.md b/api/all.md index 1c0819c843..6f049664b7 100644 --- a/api/all.md +++ b/api/all.md @@ -2,17 +2,28 @@ layout: singlepage-overview title: Scala API Docs includeTOC: true +redirect_from: + - /reference.html --- ## Latest releases -* Scala 2.12.6 - * [Library API](https://www.scala-lang.org/api/2.12.6/) - * [Compiler API](https://www.scala-lang.org/api/2.12.6/scala-compiler/scala/) - * [Reflection API](https://www.scala-lang.org/api/2.12.6/scala-reflect/scala/reflect/) + +* Scala {{site.scala-3-version}} + * [Library API](https://www.scala-lang.org/api/{{site.scala-3-version}}/) +* Scala 3.3.6 LTS + * [Library API](https://www.scala-lang.org/api/3.3.6/) +* Scala 2.13.16 + * [Library API](https://www.scala-lang.org/api/2.13.16/) + * [Compiler API](https://www.scala-lang.org/api/2.13.16/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.16/scala-reflect/scala/reflect/) +* Scala 2.12.20 + * [Library API](https://www.scala-lang.org/api/2.12.20/) + * [Compiler API](https://www.scala-lang.org/api/2.12.20/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.20/scala-reflect/scala/reflect/) * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.12.6/scala-xml/scala/xml/) - * [Parser Combinators API](https://www.scala-lang.org/api/2.12.6/scala-parser-combinators/scala/util/parsing/) - * [Swing API](https://www.scala-lang.org/api/2.12.6/scala-swing/scala/swing/) + * [XML API](https://www.scala-lang.org/api/2.12.20/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.20/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.20/scala-swing/scala/swing/) * Scala 2.11.12 * [Library API](https://www.scala-lang.org/api/2.11.12/) * [Compiler API](https://www.scala-lang.org/api/2.11.12/scala-compiler/) @@ -25,20 +36,250 @@ includeTOC: true * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.12/scala-continuations-library/#scala.util.continuations.package) * [Scala 2.10.7](https://www.scala-lang.org/api/2.10.7/) + + ## Nightly builds +API documentation for nightly builds is not currently available in browsable form. + +Jars of nightly builds, including scaladoc jars, are available from +https://scala-ci.typesafe.com/artifactory/scala-integration/org/scala-lang/ + + ## Previous releases +* Scala 3.7.0 + * [Library API](https://www.scala-lang.org/api/3.7.0/) +* Scala 3.6.4 + * [Library API](https://www.scala-lang.org/api/3.6.4/) +* Scala 3.6.3 + * [Library API](https://www.scala-lang.org/api/3.6.3/) +* Scala 3.6.2 + * [Library API](https://www.scala-lang.org/api/3.6.2/) +* Scala 3.5.2 + * [Library API](https://www.scala-lang.org/api/3.5.2/) +* Scala 3.5.1 + * [Library API](https://www.scala-lang.org/api/3.5.1/) +* Scala 3.5.0 + * [Library API](https://www.scala-lang.org/api/3.5.0/) +* Scala 3.4.3 + * [Library API](https://www.scala-lang.org/api/3.4.3/) +* Scala 3.4.2 + * [Library API](https://www.scala-lang.org/api/3.4.2/) +* Scala 3.4.1 + * [Library API](https://www.scala-lang.org/api/3.4.1/) +* Scala 3.4.0 + * [Library API](https://www.scala-lang.org/api/3.4.0/) +* Scala 3.3.5 LTS + * [Library API](https://www.scala-lang.org/api/3.3.5/) +* Scala 3.3.4 LTS + * [Library API](https://www.scala-lang.org/api/3.3.4/) +* Scala 3.3.3 LTS + * [Library API](https://www.scala-lang.org/api/3.3.3/) +* Scala 3.3.1 LTS + * [Library API](https://www.scala-lang.org/api/3.3.1/) +* Scala 3.3.0 LTS + * [Library API](https://www.scala-lang.org/api/3.3.0/) +* Scala 3.2.2 + * [Library API](https://www.scala-lang.org/api/3.2.2/) +* Scala 3.2.1 + * [Library API](https://www.scala-lang.org/api/3.2.1/) +* Scala 3.2.0 + * [Library API](https://www.scala-lang.org/api/3.2.0/) +* Scala 3.1.3 + * [Library API](https://www.scala-lang.org/api/3.1.3/) +* Scala 3.1.2 + * [Library API](https://www.scala-lang.org/api/3.1.2/) +* Scala 3.1.1 + * [Library API](https://www.scala-lang.org/api/3.1.1/) +* Scala 3.1.0 + * [Library API](https://www.scala-lang.org/api/3.1.0/) +* Scala 3.0.2 + * [Library API](https://www.scala-lang.org/api/3.0.2/) +* Scala 3.0.1 + * [Library API](https://www.scala-lang.org/api/3.0.1/) +* Scala 3.0.0 + * [Library API](https://www.scala-lang.org/api/3.0.0/) +* Scala 2.13.15 + * [Library API](https://www.scala-lang.org/api/2.13.15/) + * [Compiler API](https://www.scala-lang.org/api/2.13.15/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.15/scala-reflect/scala/reflect/) +* Scala 2.13.14 + * [Library API](https://www.scala-lang.org/api/2.13.14/) + * [Compiler API](https://www.scala-lang.org/api/2.13.14/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.14/scala-reflect/scala/reflect/) +* Scala 2.13.13 + * [Library API](https://www.scala-lang.org/api/2.13.13/) + * [Compiler API](https://www.scala-lang.org/api/2.13.13/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.13/scala-reflect/scala/reflect/) +* Scala 2.13.12 + * [Library API](https://www.scala-lang.org/api/2.13.12/) + * [Compiler API](https://www.scala-lang.org/api/2.13.12/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.12/scala-reflect/scala/reflect/) +* Scala 2.13.11 + * [Library API](https://www.scala-lang.org/api/2.13.11/) + * [Compiler API](https://www.scala-lang.org/api/2.13.11/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.11/scala-reflect/scala/reflect/) +* Scala 2.13.10 + * [Library API](https://www.scala-lang.org/api/2.13.10/) + * [Compiler API](https://www.scala-lang.org/api/2.13.10/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.10/scala-reflect/scala/reflect/) +* Scala 2.13.9 + * [Library API](https://www.scala-lang.org/api/2.13.9/) + * [Compiler API](https://www.scala-lang.org/api/2.13.9/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.9/scala-reflect/scala/reflect/) +* Scala 2.13.8 + * [Library API](https://www.scala-lang.org/api/2.13.8/) + * [Compiler API](https://www.scala-lang.org/api/2.13.8/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.8/scala-reflect/scala/reflect/) +* Scala 2.13.7 + * [Library API](https://www.scala-lang.org/api/2.13.7/) + * [Compiler API](https://www.scala-lang.org/api/2.13.7/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.7/scala-reflect/scala/reflect/) +* Scala 2.13.6 + * [Library API](https://www.scala-lang.org/api/2.13.6/) + * [Compiler API](https://www.scala-lang.org/api/2.13.6/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.6/scala-reflect/scala/reflect/) +* Scala 2.13.5 + * [Library API](https://www.scala-lang.org/api/2.13.5/) + * [Compiler API](https://www.scala-lang.org/api/2.13.5/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.5/scala-reflect/scala/reflect/) +* Scala 2.13.4 + * [Library API](https://www.scala-lang.org/api/2.13.4/) + * [Compiler API](https://www.scala-lang.org/api/2.13.4/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.4/scala-reflect/scala/reflect/) +* Scala 2.13.3 + * [Library API](https://www.scala-lang.org/api/2.13.3/) + * [Compiler API](https://www.scala-lang.org/api/2.13.3/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.3/scala-reflect/scala/reflect/) +* Scala 2.13.2 + * [Library API](https://www.scala-lang.org/api/2.13.2/) + * [Compiler API](https://www.scala-lang.org/api/2.13.2/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.2/scala-reflect/scala/reflect/) +* Scala 2.13.1 + * [Library API](https://www.scala-lang.org/api/2.13.1/) + * [Compiler API](https://www.scala-lang.org/api/2.13.1/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.1/scala-reflect/scala/reflect/) +* Scala 2.13.0 + * [Library API](https://www.scala-lang.org/api/2.13.0/) + * [Compiler API](https://www.scala-lang.org/api/2.13.0/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.13.0/scala-reflect/scala/reflect/) +* Scala 2.12.19 + * [Library API](https://www.scala-lang.org/api/2.12.19/) + * [Compiler API](https://www.scala-lang.org/api/2.12.19/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.19/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.19/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.19/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.19/scala-swing/scala/swing/) +* Scala 2.12.18 + * [Library API](https://www.scala-lang.org/api/2.12.18/) + * [Compiler API](https://www.scala-lang.org/api/2.12.18/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.18/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.18/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.18/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.18/scala-swing/scala/swing/) +* Scala 2.12.17 + * [Library API](https://www.scala-lang.org/api/2.12.17/) + * [Compiler API](https://www.scala-lang.org/api/2.12.17/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.17/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.17/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.17/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.17/scala-swing/scala/swing/) +* Scala 2.12.16 + * [Library API](https://www.scala-lang.org/api/2.12.16/) + * [Compiler API](https://www.scala-lang.org/api/2.12.16/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.16/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.16/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.16/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.16/scala-swing/scala/swing/) +* Scala 2.12.15 + * [Library API](https://www.scala-lang.org/api/2.12.15/) + * [Compiler API](https://www.scala-lang.org/api/2.12.15/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.15/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.15/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.15/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.15/scala-swing/scala/swing/) +* Scala 2.12.14 + * [Library API](https://www.scala-lang.org/api/2.12.14/) + * [Compiler API](https://www.scala-lang.org/api/2.12.14/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.14/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.14/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.14/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.14/scala-swing/scala/swing/) +* Scala 2.12.13 + * [Library API](https://www.scala-lang.org/api/2.12.13/) + * [Compiler API](https://www.scala-lang.org/api/2.12.13/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.13/scala-reflect/scala/reflect/) +* Scala 2.12.12 + * [Library API](https://www.scala-lang.org/api/2.12.12/) + * [Compiler API](https://www.scala-lang.org/api/2.12.12/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.12/scala-reflect/scala/reflect/) +* Scala 2.12.11 + * [Library API](https://www.scala-lang.org/api/2.12.11/) + * [Compiler API](https://www.scala-lang.org/api/2.12.11/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.11/scala-reflect/scala/reflect/) +* Scala 2.12.10 + * [Library API](https://www.scala-lang.org/api/2.12.10/) + * [Compiler API](https://www.scala-lang.org/api/2.12.10/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.10/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.10/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.10/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.10/scala-swing/scala/swing/) +* Scala 2.12.9 + * [Library API](https://www.scala-lang.org/api/2.12.9/) + * [Compiler API](https://www.scala-lang.org/api/2.12.9/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.9/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.9/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.9/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.9/scala-swing/scala/swing/) +* Scala 2.12.8 + * [Library API](https://www.scala-lang.org/api/2.12.8/) + * [Compiler API](https://www.scala-lang.org/api/2.12.8/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.8/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.8/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.8/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.8/scala-swing/scala/swing/) +* Scala 2.12.7 + * [Library API](https://www.scala-lang.org/api/2.12.7/) + * [Compiler API](https://www.scala-lang.org/api/2.12.7/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.7/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.7/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.7/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.7/scala-swing/scala/swing/) +* Scala 2.12.6 + * [Library API](https://www.scala-lang.org/api/2.12.6/) + * [Compiler API](https://www.scala-lang.org/api/2.12.6/scala-compiler/scala/) + * [Reflection API](https://www.scala-lang.org/api/2.12.6/scala-reflect/scala/reflect/) + * Scala Modules + * [XML API](https://www.scala-lang.org/api/2.12.6/scala-xml/scala/xml/) + * [Parser Combinators API](https://www.scala-lang.org/api/2.12.6/scala-parser-combinators/scala/util/parsing/) + * [Swing API](https://www.scala-lang.org/api/2.12.6/scala-swing/scala/swing/) * Scala 2.12.5 * [Library API](https://www.scala-lang.org/api/2.12.5/) * [Compiler API](https://www.scala-lang.org/api/2.12.5/scala-compiler/scala/) @@ -79,140 +320,3 @@ includeTOC: true * [XML API](https://www.scala-lang.org/api/2.12.1/scala-xml/#scala.xml.package) * [Parser Combinators API](https://www.scala-lang.org/api/2.12.1/scala-parser-combinators/) * [Swing API](https://www.scala-lang.org/api/2.12.1/scala-swing/#scala.swing.package) -* Scala 2.11.11 - * [Library API](https://www.scala-lang.org/api/2.11.11/) - * [Compiler API](https://www.scala-lang.org/api/2.11.11/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.11/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.11/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.11/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.11/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.11/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.11/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.10 - * [Library API](https://www.scala-lang.org/api/2.11.10/) - * [Compiler API](https://www.scala-lang.org/api/2.11.10/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.10/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.10/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.10/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.10/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.10/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.10/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.9 - * [Library API](https://www.scala-lang.org/api/2.11.9/) - * [Compiler API](https://www.scala-lang.org/api/2.11.9/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.9/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.9/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.9/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.9/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.9/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.9/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.8 - * [Library API](https://www.scala-lang.org/api/2.11.8/) - * [Compiler API](https://www.scala-lang.org/api/2.11.8/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.8/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.8/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.8/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.8/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.8/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.8/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.7 - * [Library API](https://www.scala-lang.org/api/2.11.7/) - * [Compiler API](https://www.scala-lang.org/api/2.11.7/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.7/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.7/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.7/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.7/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.7/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.7/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.6 - * [Library API](https://www.scala-lang.org/api/2.11.6/) - * [Compiler API](https://www.scala-lang.org/api/2.11.6/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.6/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.6/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.6/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.6/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.6/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.6/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.5 - * [Library API](https://www.scala-lang.org/api/2.11.5/) - * [Compiler API](https://www.scala-lang.org/api/2.11.5/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.5/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.5/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.5/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.5/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.5/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.5/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.4 - * [Library API](https://www.scala-lang.org/api/2.11.4/) - * [Compiler API](https://www.scala-lang.org/api/2.11.4/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.4/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.4/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.4/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.4/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.4/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.4/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.2 - * [Library API](https://www.scala-lang.org/api/2.11.2/) - * [Compiler API](https://www.scala-lang.org/api/2.11.2/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.2/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.2/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.2/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.2/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.2/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.2/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.1 - * [Library API](https://www.scala-lang.org/api/2.11.1/) - * [Compiler API](https://www.scala-lang.org/api/2.11.1/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.1/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.1/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.1/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.1/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.1/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.1/scala-continuations-library/#scala.util.continuations.package) -* Scala 2.11.0 - * [Library API](https://www.scala-lang.org/api/2.11.0/) - * [Compiler API](https://www.scala-lang.org/api/2.11.0/scala-compiler/) - * [Reflection API](https://www.scala-lang.org/api/2.11.0/scala-reflect/#scala.reflect.package) - * Scala Modules - * [XML API](https://www.scala-lang.org/api/2.11.0/scala-xml/#scala.xml.package) - * [Parser Combinators API](https://www.scala-lang.org/api/2.11.0/scala-parser-combinators/) - * [Actors API](https://www.scala-lang.org/api/2.11.0/scala-actors/#scala.actors.package) (deprecated) - * [Swing API](https://www.scala-lang.org/api/2.11.0/scala-swing/#scala.swing.package) - * [Continuations API](https://www.scala-lang.org/files/archive/api/2.11.0/scala-continuations-library/#scala.util.continuations.package) -* [Scala 2.10.6](https://www.scala-lang.org/api/2.10.6/) -* [Scala 2.10.5](https://www.scala-lang.org/api/2.10.5/) -* [Scala 2.10.4](https://www.scala-lang.org/api/2.10.4/) -* [Scala 2.10.3](https://www.scala-lang.org/api/2.10.3/) -* [Scala 2.10.2](https://www.scala-lang.org/api/2.10.2/) -* [Scala 2.10.1](https://www.scala-lang.org/api/2.10.1/) -* [Scala 2.9.3](https://www.scala-lang.org/api/2.9.3/) -* [Scala 2.9.2](https://www.scala-lang.org/api/2.9.2/) -* [Scala 2.9.1-1](https://www.scala-lang.org/api/2.9.1-1/) -* [Scala 2.9.1.final](https://www.scala-lang.org/api/2.9.1/) -* [Scala 2.9.0.1](https://www.scala-lang.org/api/2.9.0.1/) -* [Scala 2.9.0.final](https://www.scala-lang.org/api/2.9.0/) -* [Scala 2.8.2.final](https://www.scala-lang.org/api/2.8.2/) -* [Scala 2.8.1.final](https://www.scala-lang.org/api/2.8.1/) -* [Scala 2.8.0.final](https://www.scala-lang.org/api/2.8.0/) -* [Scala 2.7.7.final](https://www.scala-lang.org/api/2.7.7/) -* [Scala 2.7.6.final](https://www.scala-lang.org/api/2.7.6/) -* [Scala 2.7.5.final](https://www.scala-lang.org/api/2.7.5/) -* [Scala 2.7.4.final](https://www.scala-lang.org/api/2.7.4/) -* [Scala 2.7.3.final](https://www.scala-lang.org/api/2.7.3/) -* [Scala 2.7.2.final](https://www.scala-lang.org/api/2.7.2/) -* [Scala 2.7.1.final](https://www.scala-lang.org/api/2.7.1/) -* [Scala 2.7.0.final](https://www.scala-lang.org/api/2.7.0/) -* [Scala 2.6.1.final](https://www.scala-lang.org/api/2.6.1/) -* [Scala 2.6.0.final](https://www.scala-lang.org/api/2.6.0/) -* [Scala 2.5.1.final](https://www.scala-lang.org/api/2.5.1/) -* [Scala 2.5.0.final](https://www.scala-lang.org/api/2.5.0/) diff --git a/books.md b/books.md index 0bdfff3358..3e33b863d5 100644 --- a/books.md +++ b/books.md @@ -1,12 +1,12 @@ --- title: Books -layout: inner-page +layout: basic-index redirect_from: - /documentation/books.html --- -More and more books being published about Scala every year. Here, you can find -just a small selection of the many available titles. +More books about Scala are published every year. This is +only a selection of the available titles.
            diff --git a/contribute.md b/contribute.md index 9f4692f679..3ac938c17b 100644 --- a/contribute.md +++ b/contribute.md @@ -1,13 +1,13 @@ --- -layout: contribute -title: Contribute +layout: singlepage-overview +title: Why Contribute to docs.scala-lang.org? --- -###### Heather Miller +###### A note from Heather Miller ## A Place to Build Documentation Together -[docs.scala-lang.org](http://docs.scala-lang.org) was intended to make it easier for the Scala team and the community at large to easily collect, organize, and "make public" many different types of documentation while making it easy for users to find, interact, and help us improve that documentation. +[docs.scala-lang.org](https://docs.scala-lang.org) was intended to make it easier for the Scala team and the community at large to easily collect, organize, and "make public" many different types of documentation while making it easy for users to find, interact, and help us improve that documentation. This website is an open-source repository of official Scala documentation, hosted on [github](https://github.com/scala/docs.scala-lang), that is always ready for contributions. @@ -15,136 +15,12 @@ This website is an open-source repository of official Scala documentation, hoste The availability, depth, and quality of documentation is considered by many to be a huge issue. -As Scala continues to mature, it continues to attract more and more interested newcomers and potential adopters who are well accustomed to easy-to-find, abundant, quality documentation (found in other languages, like Java). For many, the learning curve becomes unnecessarily steep, and [people sometimes get frustrated](http://groups.google.com/group/scala-user/browse_thread/thread/29996782cb8428cd/5ade8462ba30b177). +As Scala continues to mature, it continues to attract more and more interested newcomers and potential adopters who are well accustomed to easy-to-find, abundant, quality documentation (found in other languages, like Java). For many, the learning curve becomes unnecessarily steep, and [people sometimes get frustrated](https://groups.google.com/group/scala-user/browse_thread/thread/29996782cb8428cd/5ade8462ba30b177). If we want Scala to be accessible to more programmers, clear, easy-to-find documentation is essential. If you're interested in contributing to the Scala project in general, I argue that one of the most meaningful ways that you can, is to help us improve this transfer of information- let's make it easier and faster for people to _get_ core concepts, and to answer their own questions so they can progress to _Scala-proficient_ quickly. Each line that you contribute has the potential to affect the entire Scala community as a whole-- current, and future. -## About docs.scala-lang.org +## How Can I Contribute? -### Content - -Currently, the _types_ of documentation supported in this repository are: - -- **Guides/Overviews**: Definitive guides/overviews of specific language features. Often long, detailed documents, often produced by members of the Scala team. An example is the excellent [Collections]({{ site.baseurl }}/overviews/collections/introduction.html) overview. -- **Tutorials**: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly. -- **Cheatsheets**: Quick reference of Scala syntax and behaviors. - -### Implementation - -This documentation repository is open-source, it lives in [github repository](https://github.com/scala/docs.scala-lang), and is always contribution-ready. - -It's statically generated from [Markdown](http://en.wikipedia.org/wiki/Markdown) source using [Jekyll](https://github.com/mojombo/jekyll), and hosted on [GitHub Pages](http://pages.github.com/). This workflow was chosen so as to make it as easy as possible for core committers and the community alike to produce HTML documentation, and as easy as possible to publish it in a central location. - -The markdown syntax being used supports [Maruku](https://github.com/bhollis/maruku) extensions, and has automatic syntax highlighting, without the need for any tags. - -Additionally [tut](https://github.com/tpolecat/tut) is used during pull requests to validate Scala code blocks. To use this feature you must use the backtick notation as documented by tut. Note that only validation is done. The output files from tut are not used in the building of the tutorial. Either use `tut` or `tut:fail` for your code blocks. - -## Submitting Docs - -For one to contribute a document, one must simply -[fork](https://help.github.com/articles/fork-a-repo/) the -[repo](https://github.com/scala/docs.scala-lang), write their article in -[Markdown](http://daringfireball.net/projects/markdown/syntax) (example below), and submit a pull request. That's it. Likely after some edits and discussion, your document will be made live on [docs.scala-lang.org](http://docs.scala-lang.org). - - --- - layout: overview - title: My Awesome Title - --- - - ## An h2 Header in Markdown - - And a paragraph, with a [link](http://www.scala-lang.org). - - One can contribute code by indenting it 4 spaces, or in-line by putting backticks around it like so, `def foo` - -Everything else is automatically generated for you; tables of contents, and most index pages. And of course, the styling is already taken care of for you. - -### Criteria for Docs to be Accepted - -The goal of this documentation repository is to be tighter and more organized than other community-driven documentation platforms, like wikis. As such, any document pulled in for inclusion on [http://docs.scala-lang.org](http://docs.scala-lang.org) must: - -- **"fit in"** to the repository ( _i.e.,_ it should not be a complete duplicate of another article), -- **be polished** it must be thorough, complete, correct, organized, and "article-like" (personal programming notes don't quite fit.) -- **be maintained** if the document might require revisions from time to time, it should come with an owner - -If you have something you're thinking about contributing, or that you're thinking about writing in order to contribute-- we'd love to consider it! Please don't hesitate to use GitHub issues and pull requests and the [scala/contributors room](https://gitter.im/scala/contributors) on Gitter for any questions, concerns, clarifications, etc. - -## Document Templates - -
            -

            Note: These templates will soon change slightly as a result of necessary refactoring.

            -
            - -### Guides/Overviews - -A guide or an overview that can be logically placed on **one** page must be placed in the directory `overviews/RELEVANT-CATEGORY/_posts` with the file name in the format `YYYY-MM-dd-title-separarted-by-dashes.md`, and header: - - --- - layout: overview - title: YOUR TITLE - --- - -The rest of the document should, of course, be written in [Markdown](http://en.wikipedia.org/wiki/Markdown). - -At the moment, `RELEVANT-CATEGORY` corresponds to only a single category, "core," because we are currently focusing on building up documentation of core libraries. However, expect more categories here in the future. - -If your document consists of **multiple** pages, like the [Collections]({{ site.baseurl }}/overviews/collections/introduction.html) overview, an ordering must be specified, by numbering documents in their logical order with `num`, and a name must be assigned to the collection of pages using `partof`. For example, the following header might be used for a document in the collections overview: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 10 - --- - -A **single** document in the collection must contain a tag in the header, `outof`, that indicates the total number of documents in the large overview. Putting it on the last page in the overview is often best: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 15 - outof: 15 - --- - -Any overview document may also include comments. To include comments, just add the tag `discourse: true` to your header. - -Index pages, such as [http://docs.scala-lang.org/overviews/index.html](http://docs.scala-lang.org/overviews/index.html) are automatically generated, assuming documents are properly placed under the correct `RELEVANT-CATEGORY`. So, simply drop your document into the correct folder, and you're done. - -### Tutorials - -At the moment, a tutorial that can be logically placed on **one** page must be placed in the directory `tutorials/` with the file name in the format `title-separated-by-dashes.md`. For the moment, single-page tutorials use the same layout as single-page overviews: - - --- - layout: overview - title: YOUR TITLE - --- - -If you have a **multiple-page** tutorial, like in the case of multiple-page overviews, you must both specify an ordering for your document, and a name must be assigned to the collection of tutorial pages. For example, the following header is used for the [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html) series of tutorial articles: - - --- - layout: inner-page-no-masthead - title: YOUR TITLE - - tutorial: scala-tour - num: 4 - --- - -Any tutorial document may also include comments. To include comments, just add the tag `discourse: true` to your header. - -At the moment, only indexes for multiple-page tutorials are automatically generated. - -### Cheatsheets - -For now, cheatsheets are assumed to be in the form of tables. To contribute a cheatsheet, one must simply produce their cheatsheet as a Markdown table, with the following header: - - --- - layout: cheatsheet - title: YOUR TITLE - by: YOUR NAME - about: SOME TEXT ABOUT THE CHEAT SHEET. - --- +Please read: [Add New Guides/Tutorials](https://docs.scala-lang.org/contribute/add-guides.html) diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000000..75b1876399 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,9 @@ +services: + jekyll: + user: "${UID}:${GID}" + build: . + command: sh -c "chown $UID / && bundle exec jekyll serve --incremental --host=0.0.0.0 " + ports: + - '4000:4000' + volumes: + - .:/srv/jekyll diff --git a/docker-compose_build-only.yml b/docker-compose_build-only.yml new file mode 100644 index 0000000000..615d0425a7 --- /dev/null +++ b/docker-compose_build-only.yml @@ -0,0 +1,9 @@ +version: '2' + +services: + jekyll: + user: "${UID}:${GID}" + build: . + command: sh -c "chown $UID / && bundle exec jekyll build" + volumes: + - .:/srv/jekyll diff --git a/getting-started.md b/getting-started.md deleted file mode 100644 index 59b7d96958..0000000000 --- a/getting-started.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -layout: singlepage-overview -title: Getting Started -includeTOC: true ---- - -
            There are two main ways people prefer to work in Scala.
            - -
              -
            1. Using an IDE.
              2. -
            2. Using the command line.
              3. -
            - - -The following tutorials will walk you through the set up process for either way -you prefer. - -However, if you just want to jump directly into Scala without installing anything, skip the guides on this page and check out: - - - -## Setting up and getting started with Scala - -### If prefer working in an IDE... - -IntelliJ is the most commonly-used IDE by Scala developers. In this tutorial, -we'll walk you through downloading and setting up IntelliJ with the Scala -plugin, and we'll get you started with your first Scala project, complete with -unit tests! - -* [Getting Started with Scala in IntelliJ](getting-started-intellij-track/getting-started-with-scala-in-intellij.html) -* [Building a Scala Project with IntelliJ and sbt](getting-started-intellij-track/building-a-scala-project-with-intellij-and-sbt.html) -* [Testing Scala in IntelliJ with ScalaTest](getting-started-intellij-track/testing-scala-in-intellij-with-scalatest.html) - - -### If you prefer working on the command line... - -If you prefer using a text editor like emacs, Vim, Atom, or Sublime Text, then -the best way to compile, test, and run Scala code is using _sbt_, Scala's build -tool. - -* [Getting Started with Scala and sbt on the Command Line](getting-started-sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html) -* [Testing Scala with sbt and ScalaTest on the Command Line](getting-started-sbt-track/testing-scala-with-sbt-on-the-command-line.html) - - - -## Next Steps -Once you've finished these tutorials, check out - -* [The Tour of Scala](tour/tour-of-scala.html) for bite-sized introductions to Scala's features. -* [Learning Resources](learn.html), which includes online interactive tutorials and courses. -* [Our list of some popular Scala books](books.html). - -## Getting Help -There are a multitude of mailing lists and real-time chat channels in case you want to quickly connect with other Scala users. Check out our [community](https://scala-lang.org/community/) page a list of these resources and where to reach out for help. diff --git a/guides.md b/guides.md deleted file mode 100644 index eef2743e4f..0000000000 --- a/guides.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-no-masthead -title: Guides and Overviews -languages: [ja, zh-cn, es] - ---- diff --git a/index.md b/index.md index 23ed9edcd5..22cbc790cc 100644 --- a/index.md +++ b/index.md @@ -1,40 +1,55 @@ --- -layout: inner-page-documentation -title: Documentation -#redirect_from: -# - /what-is-scala/ -#includeTOC: true +layout: landing-page +languages: [ja, zh-cn, ru, uk] -# Content masthead links -sections: +title: Learn Scala +namespace: root +discourse: true +partof: documentation +more-resources-label: More Resources +redirect_from: + - /scala3/ + - /scala3/index.html +sections: - title: "First Steps..." links: - title: "Getting Started" description: "Install Scala on your computer and start writing some Scala code!" icon: "fa fa-rocket" - link: /getting-started.html + link: /getting-started/install-scala.html - title: "Tour of Scala" description: "Bite-sized introductions to core language features." icon: "fa fa-flag" link: /tour/tour-of-scala.html - - title: "Scala for Java Programmers" - description: "A quick introduction to Scala for those with a Java background." - icon: "fa fa-coffee" - link: /tutorials/scala-for-java-programmers.html - more-resources: - - title: Online Courses, Exercises, & Blogs - url: /learn.html + - title: "Scala 3 Book" + description: "Learn Scala by reading a series of short lessons." + icon: "fa fa-book-open" + link: /scala3/book/introduction.html + - title: "Scala Toolkit" + description: "Sending HTTP requests, writing files, running processes, parsing JSON..." + icon: "fa fa-toolbox" + link: /toolkit/introduction.html + - title: Online Courses + description: "MOOCs to learn Scala, for beginners and experienced programmers." + icon: "fa fa-cloud" + link: /online-courses.html - title: Books - url: /books.html + description: "Printed and digital books about Scala." + icon: "fa fa-book" + link: /books.html + - title: Tutorials + description: "Take you by the hand through a series of steps to create Scala applications." + icon: "fa fa-tasks" + link: /tutorials.html - - title: "Returning Users" + - title: "Returning Users" links: - title: "API" description: "API documentation for every version of Scala." - icon: "fa fa-file-text" + icon: "fa fa-file-alt" link: /api/all.html - - title: "Overviews" + - title: "Guides & Overviews" description: "In-depth documentation covering many of Scala's features." icon: "fa fa-database" link: /overviews/index.html @@ -45,25 +60,51 @@ sections: - title: "Cheatsheet" description: "A handy cheatsheet covering the basics of Scala's syntax." icon: "fa fa-list" - link: /cheatsheets/index.html - - title: "Scala FAQs" - description: "A list of frequently-asked questions about Scala language features and their answers." + link: /cheatsheets/index.html + - title: "Scala FAQ" + description: "Answers to frequently-asked questions about Scala." icon: "fa fa-question-circle" link: /tutorials/FAQ/index.html - - title: "Language Spec" - description: "Scala's formal language specification." + - title: "Language Spec v2.x" + description: "Scala 2's formal language specification." + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/2.13/ + - title: "Language Spec v3.x" + description: "Scala 3's formal language specification." icon: "fa fa-book" - link: http://scala-lang.org/files/archive/spec/2.12/ + link: https://scala-lang.org/files/archive/spec/3.4/ + - title: "Scala 3 Language Reference" + description: "The Scala 3 language reference." + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference - - title: "Scala Evolution" + - title: "Explore Scala 3" links: - - title: "SIPs" - description: "The Scala Improvement Process. Language & compiler evolution." - icon: "fa fa-cogs" - link: sips/index.html - - title: "SPP" - description: "The Scala Platform Process. Community-driven library evolution." - icon: "fa fa-users" - link: https://platform.scala-lang.org + - title: "Migration Guide" + description: "A guide to help you move from Scala 2 to Scala 3." + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "New in Scala 3" + description: "An overview of the exciting new features in Scala 3." + icon: "fa fa-star" + link: /scala3/new-in-scala3.html + - title: "All new Scaladoc for Scala 3" + description: "Highlights of new features for Scaladoc" + icon: "fa fa-star" + link: /scala3/scaladoc.html + - title: "Talks" + description: "Talks about Scala 3 that can be watched online" + icon: "fa fa-play-circle" + link: /scala3/talks.html + - title: "Scala Evolution" + links: + - title: "Scala Improvement Process" + description: "Description of the process for evolving the language, and list of all the Scala Improvement Proposals (SIPs)." + icon: "fa fa-cogs" + link: /sips/index.html + - title: "Become a Scala OSS Contributor" + description: "From start to finish: discover how you can help Scala's open-source ecosystem" + icon: "fa fa-code-branch" + link: /contribute/ --- diff --git a/learn.md b/learn.md deleted file mode 100644 index 3ec8a4909a..0000000000 --- a/learn.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Online Resources -layout: inner-page-no-masthead -redirect_from: - - /documentation/books.html ---- - -## Quick Online Exercises -[Scala Exercises](https://www.scala-exercises.org/) is a series of lessons and exercises created by [47 Degrees](https://www.47deg.com/). It's a great way to get a brief introduction to Scala while testing your knowledge along the way. - -## Online Courses from EPFL - -The following courses are available for free. They teach you the main features of the Scala language and introduce you -to functional programming. They are published on both [Coursera](https://www.coursera.org) and an EPFL-hosted Open edX -instance at [courseware.epfl.ch](https://courseware.epfl.ch/). - - * Functional Programming in Scala Specialization (on [Coursera](https://www.coursera.org/specializations/scala)). - The Specialization provides a hands-on introduction to functional programming using Scala. You can access the courses - material and exercises by either signing up for the specialization or auditing the courses individually. The - specialization has the following courses. - * Functional Programming Principles in Scala ([Coursera](https://www.coursera.org/learn/progfun1) and - [Open edX](https://courseware.epfl.ch/courses/course-v1:EPFL+progfun1+2018_T1/about)), - * Functional Program Design in Scala ([Coursera](https://www.coursera.org/learn/progfun2) and - [Open edX](https://courseware.epfl.ch/courses/course-v1:EPFL+progfun2+2018_T1/about)), - * Parallel programming ([Coursera](https://www.coursera.org/learn/parprog1) and - [Open edX](https://courseware.epfl.ch/courses/course-v1:EPFL+parprog1+2018_T1/about)), - * Big Data Analysis with Scala and Spark ([Coursera](https://www.coursera.org/learn/scala-spark-big-data) and - [Open edX](https://courseware.epfl.ch/courses/course-v1:EPFL+scala-spark-big-data+2018-T1/about)), - * Functional Programming in Scala Capstone ([Coursera](https://www.coursera.org/learn/scala-capstone) only). - -Note : On Coursera there is a paid version available. The only difference between the free and the paid version is that -you get a certificate of completion from Coursera on the paid version. You can learn more about coursera certificates in -[this help document](https://learner.coursera.help/hc/en-us/articles/209819053-Get-a-Course-Certificate). - -## Dr.Mark C Lewis's Lectures from Trinity University - - * [Dr.Mark C Lewis](http://www.cs.trinity.edu/~mlewis/) from Trinity University, San Antonio, TX, teaches programming courses using the Scala language. Course videos are available in YouTube for free. Some of the courses below. - * [Introduction to Programming and Problem Solving Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt9MIJ9DV4ps-_trOzWtphYO) - * [Object-Orientation, Abstraction, and Data Structures Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt8JLumqKj-3BlHmEXPIfR42) - - You can visit his [YouTube channel](https://www.youtube.com/user/DrMarkCLewis/featured) for more videos. - - -## Try Scala In Your Browser! -There are a handful of websites where you can interactively run Scala code in your browser! Have a look at [ScalaFiddle](https://scalafiddle.io/) and [Scastie](http://scastie.org/). - -## allaboutscala -[allaboutscala](http://allaboutscala.com/) provides detailed tutorials for beginners. - -## ScalaCourses -[Independent Courseware](http://getscala.com), online self-study or instructor-led Scala and Play courses for a fee. diff --git a/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md b/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md index 7735015903..c4722a5bb3 100644 --- a/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md +++ b/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md @@ -1,15 +1,14 @@ --- -layout: inner-page-no-masthead +layout: singlepage-overview title: "Functional Programming Principles in Scala: Impressions and Statistics" -discourse: true --- ###### By Heather Miller and Martin Odersky
            - In this post, we discuss our experience giving the popular MOOC Functional Programming Principles in Scala, and provide some insight into who our course participants were, how, overall, students performed in the course, and how students felt about the course. We visualize a lot of these statistics in a number of interactive plots, and we go on to publicly release the data and the code to generate these plots within a fun Scala-based project aimed at allowing you to manipulate these statistics with functional programming in Scala, to generate HTML/Javascript for easily visualizing and sharing them. We encourage you to share what you find with us— we'll share a number of your plots in a follow-up post! + In this post, we discuss our experience giving the popular MOOC Functional Programming Principles in Scala, and provide some insight into who our course participants were, how, overall, students performed in the course, and how students felt about the course. We visualize a lot of these statistics in a number of interactive plots, and we go on to publicly release the data and the code to generate these plots within a fun Scala-based project aimed at allowing you to manipulate these statistics with functional programming in Scala, to generate HTML/JavaScript for easily visualizing and sharing them. We encourage you to share what you find with us— we'll share a number of your plots in a follow-up post!
            -[_Functional Programming Principles in Scala_](https://www.coursera.org/course/progfun) is a [MOOC](http://en.wikipedia.org/wiki/Massive_open_online_course) given by [our research group](http://lamp.epfl.ch) at [EPFL](http://www.epfl.ch), whose first edition was recently completed on [Coursera](http://www.coursera.org). The certificates of completion for those who passed the course have been released, and in looking back as the dust settles— it was a great experience to have done a class like that which greatly exceeded our expectations in more than one dimension. +[_Functional Programming Principles in Scala_](https://www.coursera.org/course/progfun) is a [MOOC](https://en.wikipedia.org/wiki/Massive_open_online_course) given by [our research group](https://lamp.epfl.ch) at [EPFL](https://www.epfl.ch), whose first edition was recently completed on [Coursera](https://www.coursera.org). The certificates of completion for those who passed the course have been released, and in looking back as the dust settles— it was a great experience to have done a class like that which greatly exceeded our expectations in more than one dimension. We had more than 50,000 registered students— an unfathomably large number in the context of traditional teaching. While large, that number doesn't tell the whole story; as is typical for a MOOC, a statistical majority of those students participate no further beyond watching a couple of videos to find out what the course is about. Of the 50,000, about 21,000 students participated in the interactive in-video quizzes that are part of the lectures, and a remarkable 18,000 unique students attempted at least one programming assignment. A whopping 9,593 students successfully completed the course and earned a certificate of completion— that's an incredible 20% of students, which blows the average 10% rate of completion for MOOCs out of the water. @@ -34,7 +33,7 @@ Those of you reading this who were enrolled in the course might recall that, sev For example, as mentioned above, a success rate of 20% is quite high for an online course. One might suspect that it was because the course was very easy, but in our previous experience that's not the case. In fact, the online course is a direct adaptation of a 2nd year course that was given at EPFL for a number of years and that has a reputation of being rather tough. If anything, the material in the online course was a bit more compressed than in the previous on-campus class. -In particular, 57% of all respondents to the survey rated the overall course as being 3, "Just Right", on a scale from 1 to 5, with 1 being "Too Easy" and 5 being "Too Difficult. With regard to programming assignments specifically, 40% rated the assignments as being 3, "Just Right", while 46% rated assignments as being 4 "Challenging". +In particular, 57% of all respondents to the survey rated the overall course as being 3, "Just Right", on a scale from 1 to 5, with 1 being "Too Easy" and 5 being "Too Difficult". With regard to programming assignments specifically, 40% rated the assignments as being 3, "Just Right", while 46% rated assignments as being 4 "Challenging". Another point which might be particularly interesting is the fact that the difficulty rating appears to be independent of whether people have a background in Computer Science/Software Engineering or not. One might guess that this could mean that learning Scala is not much more difficult without a formal educational background in Computer Science. @@ -44,7 +43,7 @@ While a majority of the students in the course have degrees in Computer Science/
            Participants' Fields of Study
             
            -However, we were still interested to see how the formal education of participants influenced their assessment of the perceived difficulty. It turns out that, of those who have or have pursued university degrees— Bachelors or Masters degrees, there was almost no difference in perceived difficulty. The only marked differences appeared to the far left and the far right of the spectrum. +However, we were still interested to see how the formal education of participants influenced their assessment of the perceived difficulty. It turns out that, of those who have or have pursued university degrees— Bachelors or Master's degrees, there was almost no difference in perceived difficulty. The only marked differences appeared to the far left and the far right of the spectrum.
            Perceived Difficulty Relative to Level of Education
             
            Scale: 1 - Too Easy, 2 - Easy, 3 - Just Right, 4 - Challenging, 5 - Too Difficult

             

            @@ -80,7 +79,7 @@ We also collected numbers about the used programming tools. First, we were inter
            Which editor do you normally use, and which editor did you use for the course?
             
            -The collected numbers are markedly different. In no small part this is due to the fact that the [Scala IDE for Eclipse](http://scala-ide.org) introduced a new [worksheet](https://github.com/scala-ide/scala-worksheet/wiki/Getting-Started) component used throughout the lectures. +The collected numbers are markedly different. In no small part this is due to the fact that the Scala IDE for Eclipse introduced a new [worksheet](https://github.com/scala-ide/scala-worksheet/wiki/Getting-Started) component used throughout the lectures. We'd like to close with some fun, and partially surprising, information on the demographics of those who took the course and completed our survey. Here is a world map showing the number of participants per country— darker colors indicate a larger number of students per-country: @@ -94,7 +93,7 @@ Here's that graph again, relating that population of students who enrolled in th ## Get the data and explore it with Scala! -For those of you who want to have a little bit of fun with the numbers, we've made all of the data publicly available, and we've made a small Scala project out of it. In particular, we put the code that we used to produce the above plots on [github (progfun-stats)](http://www.github.com/heathermiller/progfun-stats). +For those of you who want to have a little bit of fun with the numbers, we've made all the data publicly available, and we've made a small Scala project out of it. In particular, we put the code that we used to produce the above plots on [github (progfun-stats)](https://www.github.com/heathermiller/progfun-stats). For those of you who have taken the course and are itching for some fun additional exercises in functional programming, one of our suggestions is to tinker with and extend this project! You'll find the code examples for generating most of these plots available in this post, in the above repository. diff --git a/online-courses.md b/online-courses.md new file mode 100644 index 0000000000..6b65a5115f --- /dev/null +++ b/online-courses.md @@ -0,0 +1,43 @@ +--- +title: Online Courses +layout: online-courses +redirect_from: + - /documentation/books.html + - /learn +--- + +## Other Online Resources + +### Tour of Scala + +[Tour of Scala](https://tourofscala.com) is an interactive website that introduces the basics of Scala programming through a series of hands-on lessons. +Each lesson provides code examples and exercises that compiles and runs directly in the browser, making it a quick and accessible way to get started with Scala. + +In the [Scala Learning Discord](http://sca.la/learning-community), you can connect with fellow Scala learners and engage with the Tour of Scala community. + +### Scala Exercises + +[Scala Exercises](https://www.scala-exercises.org/) is a series of lessons and exercises created by [47 Degrees](https://www.47deg.com/). +It's a great way to get a brief introduction to Scala while testing your knowledge along the way. +It also covers some libraries of the ecosystem such as cats, doobie, scalacheck etc. + +### DevInsideYou + +[DevInsideYou](https://youtube.com/devinsideyou) is a YouTube channel with hundreds of hours of free Scala content. + +### Visual Scala Reference + +[Visual Scala Reference](https://superruzafa.github.io/visual-scala-reference/) is a visual guide to the most common methods of the Scala collections. + +### allaboutscala + +[allaboutscala](https://allaboutscala.com/) provides detailed tutorials for beginners. + +### Dr. Mark C Lewis's lectures from Trinity University + +[Dr. Mark C Lewis](https://www.cs.trinity.edu/~mlewis/) from Trinity University, San Antonio, TX, teaches programming courses using the Scala language. Course videos are available in YouTube for free. Some courses below. + +- [Introduction to Programming and Problem Solving Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt9MIJ9DV4ps-_trOzWtphYO) +- [Object-Orientation, Abstraction, and Data Structures Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt8JLumqKj-3BlHmEXPIfR42) + +You can visit his [YouTube channel](https://www.youtube.com/user/DrMarkCLewis/featured) for more videos. diff --git a/reference.md b/reference.md deleted file mode 100644 index e7a837825e..0000000000 --- a/reference.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-no-masthead -sitemap: false -permalink: /reference.html -redirect_to: /api/all.html ---- diff --git a/resources/css/style.scss b/resources/css/style.scss index 7d297f71ea..5f30379a90 100755 --- a/resources/css/style.scss +++ b/resources/css/style.scss @@ -55,13 +55,16 @@ @import 'layout/training-events'; @import 'layout/blog'; @import 'layout/download'; +@import 'layout/online-courses'; @import 'layout/content-contributors'; // COMPONENTS +@import 'layout/details-summary'; //------------------------------------------------ //------------------------------------------------ @import 'components/buttons'; @import 'components/call-to-action'; @import 'components/slider'; @import 'components/heading-line'; +@import 'components/alt-details'; @import 'components/card'; @import 'components/calendar'; @import 'components/tooltip'; @@ -71,3 +74,5 @@ @import 'components/tag'; @import 'components/search'; @import 'components/dropdown'; +@import 'components/wip-notice'; +@import 'components/heading-anchor.scss'; diff --git a/resources/images/documentation-preview.png b/resources/images/documentation-preview.png new file mode 100644 index 0000000000..49f174f05c Binary files /dev/null and b/resources/images/documentation-preview.png differ diff --git a/resources/images/documentation-snippet.png b/resources/images/documentation-snippet.png new file mode 100644 index 0000000000..76b3ac48dc Binary files /dev/null and b/resources/images/documentation-snippet.png differ diff --git a/resources/images/getting-started/IntelliJScala.png b/resources/images/getting-started/IntelliJScala.png new file mode 100644 index 0000000000..c567da38df Binary files /dev/null and b/resources/images/getting-started/IntelliJScala.png differ diff --git a/resources/images/getting-started/VSCodeMetals.png b/resources/images/getting-started/VSCodeMetals.png new file mode 100644 index 0000000000..bdc5090726 Binary files /dev/null and b/resources/images/getting-started/VSCodeMetals.png differ diff --git a/resources/images/learning-path.png b/resources/images/learning-path.png new file mode 100644 index 0000000000..43e9d09631 Binary files /dev/null and b/resources/images/learning-path.png differ diff --git a/resources/images/library-author-guide/fowards_backwards_compatibility.png b/resources/images/library-author-guide/forward_backward_compatibility.png similarity index 100% rename from resources/images/library-author-guide/fowards_backwards_compatibility.png rename to resources/images/library-author-guide/forward_backward_compatibility.png diff --git a/resources/images/online-courses/coursera.png b/resources/images/online-courses/coursera.png new file mode 100644 index 0000000000..a329139aa0 Binary files /dev/null and b/resources/images/online-courses/coursera.png differ diff --git a/resources/images/online-courses/extension-school.png b/resources/images/online-courses/extension-school.png new file mode 100644 index 0000000000..94da532d8c Binary files /dev/null and b/resources/images/online-courses/extension-school.png differ diff --git a/resources/images/online-courses/rock-the-jvm.png b/resources/images/online-courses/rock-the-jvm.png new file mode 100644 index 0000000000..86b6512c0b Binary files /dev/null and b/resources/images/online-courses/rock-the-jvm.png differ diff --git a/resources/images/scala3-book/hierarchy.dot b/resources/images/scala3-book/hierarchy.dot new file mode 100644 index 0000000000..24e6c2a896 --- /dev/null +++ b/resources/images/scala3-book/hierarchy.dot @@ -0,0 +1,37 @@ +digraph unix { + rankdir = BT; + size="6,6"; + node [color=lightblue2, style=filled, fontname="Consolas"]; + + + {rank=same; "AnyVal"; "AnyRef / Object"} + + {rank=same; + "Unit"; "Boolean"; "Int"; "... (value types)"; + "String"; "List[Int]"; "... (reference types)" + } + + "Matchable" -> "Any"; + "AnyVal" -> "Matchable"; + "AnyRef / Object" -> "Matchable"; + + "Unit" -> "AnyVal"; + "Boolean" -> "AnyVal"; + "Int" -> "AnyVal"; + "... (value types)" -> "AnyVal"; + + "String" -> "AnyRef / Object"; + "List[Int]" -> "AnyRef / Object"; + "... (reference types)" -> "AnyRef / Object"; + + "Null" -> "String"; + "Null" -> "List[Int]"; + "Null" -> "... (reference types)"; + + "Nothing" -> "Null"; + "Nothing" -> "Unit"; + "Nothing" -> "Boolean"; + "Nothing" -> "Int"; + "Nothing" -> "... (value types)"; + +} diff --git a/resources/images/scala3-book/hierarchy.svg b/resources/images/scala3-book/hierarchy.svg new file mode 100644 index 0000000000..013848749e --- /dev/null +++ b/resources/images/scala3-book/hierarchy.svg @@ -0,0 +1,199 @@ + + + + + + +unix + + + +AnyVal + +AnyVal + + + +Matchable + +Matchable + + + +AnyVal->Matchable + + + + + +AnyRef / Object + +AnyRef / Object + + + +AnyRef / Object->Matchable + + + + + +Unit + +Unit + + + +Unit->AnyVal + + + + + +Boolean + +Boolean + + + +Boolean->AnyVal + + + + + +Int + +Int + + + +Int->AnyVal + + + + + +... (value types) + +... (value types) + + + +... (value types)->AnyVal + + + + + +String + +String + + + +String->AnyRef / Object + + + + + +List[Int] + +List[Int] + + + +List[Int]->AnyRef / Object + + + + + +... (reference types) + +... (reference types) + + + +... (reference types)->AnyRef / Object + + + + + +Any + +Any + + + +Matchable->Any + + + + + +Null + +Null + + + +Null->String + + + + + +Null->List[Int] + + + + + +Null->... (reference types) + + + + + +Nothing + +Nothing + + + +Nothing->Unit + + + + + +Nothing->Boolean + + + + + +Nothing->Int + + + + + +Nothing->... (value types) + + + + + +Nothing->Null + + + + + diff --git a/resources/images/scala3-book/intellij-worksheet.png b/resources/images/scala3-book/intellij-worksheet.png new file mode 100644 index 0000000000..e33fd3566e Binary files /dev/null and b/resources/images/scala3-book/intellij-worksheet.png differ diff --git a/resources/images/scala3-book/metals-worksheet.png b/resources/images/scala3-book/metals-worksheet.png new file mode 100644 index 0000000000..da950e19d6 Binary files /dev/null and b/resources/images/scala3-book/metals-worksheet.png differ diff --git a/resources/images/scala3-migration/compatibility-213-to-3.svg b/resources/images/scala3-migration/compatibility-213-to-3.svg new file mode 100644 index 0000000000..32d5687bce --- /dev/null +++ b/resources/images/scala3-migration/compatibility-213-to-3.svg @@ -0,0 +1,3 @@ + + +
            bar_3
            bar_3
            foo_2.13
            foo_2.13            Viewer does not support full SVG 1.1             \ No newline at end of file diff --git a/resources/images/scala3-migration/compatibility-3-to-213.svg b/resources/images/scala3-migration/compatibility-3-to-213.svg new file mode 100644 index 0000000000..88fdc8606e --- /dev/null +++ b/resources/images/scala3-migration/compatibility-3-to-213.svg @@ -0,0 +1,3 @@ + + +
            bar_2.13
            bar_2.13
            foo_3
            foo_3            Viewer does not support full SVG 1.1             \ No newline at end of file diff --git a/resources/images/scala3-migration/compatibility-sandwich.svg b/resources/images/scala3-migration/compatibility-sandwich.svg new file mode 100644 index 0000000000..32942b7d03 --- /dev/null +++ b/resources/images/scala3-migration/compatibility-sandwich.svg @@ -0,0 +1,3 @@ + + +
            lib_2.13
            lib_2.13
            core_3
            core_3
            app_2.13
            app_2.13            Viewer does not support full SVG 1.1             \ No newline at end of file diff --git a/resources/images/scala3-migration/tutorial-macro-cross-building.svg b/resources/images/scala3-migration/tutorial-macro-cross-building.svg new file mode 100644 index 0000000000..03b75bd497 --- /dev/null +++ b/resources/images/scala3-migration/tutorial-macro-cross-building.svg @@ -0,0 +1,3 @@ + + +
            example_2.13
            example_2.13
            app_2.13
            app_2.13
            example_3
            example_3
            app_3
            app_3            Viewer does not support full SVG 1.1             \ No newline at end of file diff --git a/resources/images/scala3-migration/tutorial-macro-mixing.svg b/resources/images/scala3-migration/tutorial-macro-mixing.svg new file mode 100644 index 0000000000..18023dffb9 --- /dev/null +++ b/resources/images/scala3-migration/tutorial-macro-mixing.svg @@ -0,0 +1,3 @@ + + +
            example-compat_2.13
            example-compat_2.13
            example_3
            example_3
            app_2.13
            app_2.13
            app_3
            app_3            Viewer does not support full SVG 1.1             \ No newline at end of file diff --git a/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png b/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png new file mode 100644 index 0000000000..65179260c2 Binary files /dev/null and b/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png differ diff --git a/resources/images/scala3/scaladoc/assert-compilation-errors.gif b/resources/images/scala3/scaladoc/assert-compilation-errors.gif new file mode 100644 index 0000000000..c13cf0ef49 Binary files /dev/null and b/resources/images/scala3/scaladoc/assert-compilation-errors.gif differ diff --git a/resources/images/scala3/scaladoc/blog-post.png b/resources/images/scala3/scaladoc/blog-post.png new file mode 100644 index 0000000000..f8db0483d2 Binary files /dev/null and b/resources/images/scala3/scaladoc/blog-post.png differ diff --git a/resources/images/scala3/scaladoc/documentation-snippet.png b/resources/images/scala3/scaladoc/documentation-snippet.png new file mode 100644 index 0000000000..31ce6087fc Binary files /dev/null and b/resources/images/scala3/scaladoc/documentation-snippet.png differ diff --git a/resources/images/scala3/scaladoc/documentation-snippet2.png b/resources/images/scala3/scaladoc/documentation-snippet2.png new file mode 100644 index 0000000000..d60acb4634 Binary files /dev/null and b/resources/images/scala3/scaladoc/documentation-snippet2.png differ diff --git a/resources/images/scala3/scaladoc/hiding-code.gif b/resources/images/scala3/scaladoc/hiding-code.gif new file mode 100644 index 0000000000..f3e52712be Binary files /dev/null and b/resources/images/scala3/scaladoc/hiding-code.gif differ diff --git a/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif b/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif new file mode 100644 index 0000000000..1cc25b5683 Binary files /dev/null and b/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif differ diff --git a/resources/images/scala3/scaladoc/logo.svg b/resources/images/scala3/scaladoc/logo.svg new file mode 100644 index 0000000000..1774519639 --- /dev/null +++ b/resources/images/scala3/scaladoc/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/resources/images/scala3/scaladoc/nightly.gif b/resources/images/scala3/scaladoc/nightly.gif new file mode 100644 index 0000000000..d6e764a032 Binary files /dev/null and b/resources/images/scala3/scaladoc/nightly.gif differ diff --git a/resources/images/scala3/scaladoc/snippet-compiler1.gif b/resources/images/scala3/scaladoc/snippet-compiler1.gif new file mode 100644 index 0000000000..d3573e395f Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler1.gif differ diff --git a/resources/images/scala3/scaladoc/snippet-compiler2.gif b/resources/images/scala3/scaladoc/snippet-compiler2.gif new file mode 100644 index 0000000000..2074c74ebb Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler2.gif differ diff --git a/resources/images/scala3/scaladoc/snippet-compiler3.png b/resources/images/scala3/scaladoc/snippet-compiler3.png new file mode 100644 index 0000000000..3982bc782f Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler3.png differ diff --git a/resources/images/scala3/scaladoc/snippet-compiler4.png b/resources/images/scala3/scaladoc/snippet-compiler4.png new file mode 100644 index 0000000000..5bb2afaa15 Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler4.png differ diff --git a/resources/images/scala3/scaladoc/snippet-includes.png b/resources/images/scala3/scaladoc/snippet-includes.png new file mode 100644 index 0000000000..cd9db043d6 Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-includes.png differ diff --git a/resources/images/scala3/scaladoc/social-links.png b/resources/images/scala3/scaladoc/social-links.png new file mode 100644 index 0000000000..4c20568c7c Binary files /dev/null and b/resources/images/scala3/scaladoc/social-links.png differ diff --git a/resources/images/scala3/scaladoc/static-site.png b/resources/images/scala3/scaladoc/static-site.png new file mode 100644 index 0000000000..9f27f058b2 Binary files /dev/null and b/resources/images/scala3/scaladoc/static-site.png differ diff --git a/resources/images/scalacenter-courses/testimonial000.jpg b/resources/images/scalacenter-courses/testimonial000.jpg new file mode 100644 index 0000000000..50c03ecf3a Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial000.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial001.jpg b/resources/images/scalacenter-courses/testimonial001.jpg new file mode 100644 index 0000000000..b3e1cc7584 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial001.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial002.jpg b/resources/images/scalacenter-courses/testimonial002.jpg new file mode 100644 index 0000000000..62174d4319 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial002.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial003.jpg b/resources/images/scalacenter-courses/testimonial003.jpg new file mode 100644 index 0000000000..3a594aabdd Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial003.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial004.jpg b/resources/images/scalacenter-courses/testimonial004.jpg new file mode 100644 index 0000000000..2750557f9c Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial004.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial005.jpg b/resources/images/scalacenter-courses/testimonial005.jpg new file mode 100644 index 0000000000..d6104cd9dd Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial005.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial006.jpg b/resources/images/scalacenter-courses/testimonial006.jpg new file mode 100644 index 0000000000..acdcdc7b34 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial006.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial007.jpg b/resources/images/scalacenter-courses/testimonial007.jpg new file mode 100644 index 0000000000..46a1e90193 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial007.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial008.jpg b/resources/images/scalacenter-courses/testimonial008.jpg new file mode 100644 index 0000000000..bde859d696 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial008.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial009.jpg b/resources/images/scalacenter-courses/testimonial009.jpg new file mode 100644 index 0000000000..e036db8133 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial009.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial010.jpg b/resources/images/scalacenter-courses/testimonial010.jpg new file mode 100644 index 0000000000..b329771b8f Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial010.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial011.jpg b/resources/images/scalacenter-courses/testimonial011.jpg new file mode 100644 index 0000000000..ec49e73333 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial011.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial012.jpg b/resources/images/scalacenter-courses/testimonial012.jpg new file mode 100644 index 0000000000..639c5a0617 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial012.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial013.jpg b/resources/images/scalacenter-courses/testimonial013.jpg new file mode 100644 index 0000000000..4dd0e747f7 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial013.jpg differ diff --git a/resources/images/scalacenter-courses/testimonial014.jpg b/resources/images/scalacenter-courses/testimonial014.jpg new file mode 100644 index 0000000000..4fe1763fe4 Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial014.jpg differ diff --git a/resources/images/sip/process-chart.png b/resources/images/sip/process-chart.png new file mode 100644 index 0000000000..c647901efd Binary files /dev/null and b/resources/images/sip/process-chart.png differ diff --git a/resources/images/sip/sip-stages.png b/resources/images/sip/sip-stages.png new file mode 100644 index 0000000000..981f8b8937 Binary files /dev/null and b/resources/images/sip/sip-stages.png differ diff --git a/resources/images/tour/Makefile b/resources/images/tour/Makefile index 7e563a4bc8..6782bb92d9 100644 --- a/resources/images/tour/Makefile +++ b/resources/images/tour/Makefile @@ -1,4 +1,21 @@ +all: unified-types\ + type-casting\ + collections\ + collections-immutable\ + collections-mutable\ + collections-legend unified-types: - dot -Tsvg unified-types-diagram.dot -o unified-types-diagram.svg + dot -Tsvg $@-diagram.dot -o $@-diagram.svg type-casting: - dot -Tsvg type-casting-diagram.dot -o type-casting-diagram.svg + dot -Tsvg $@-diagram.dot -o $@-diagram.svg +collections: + dot -Tsvg $@-diagram.dot -o $@-diagram.svg + dot -Tsvg $@-diagram-213.dot -o $@-diagram-213.svg +collections-immutable: + dot -Tsvg $@-diagram.dot -o $@-diagram.svg + dot -Tsvg $@-diagram-213.dot -o $@-diagram-213.svg +collections-mutable: + dot -Tsvg $@-diagram.dot -o $@-diagram.svg + dot -Tsvg $@-diagram-213.dot -o $@-diagram-213.svg +collections-legend: + dot -Tsvg $@-diagram.dot -o $@-diagram.svg diff --git a/resources/images/tour/collections-diagram-213.dot b/resources/images/tour/collections-diagram-213.dot new file mode 100644 index 0000000000..e26137b51f --- /dev/null +++ b/resources/images/tour/collections-diagram-213.dot @@ -0,0 +1,21 @@ +digraph Collections { + edge [ + color="#7F7F7F" + ]; + node [ + shape="box", + style="rounded, filled", + fontcolor="#FFFFFF", + color="#6DC6E6" + ]; + rankdir="TB"; + + Iterable -> Seq; + Iterable -> Set; + Iterable -> Map; + Seq -> IndexedSeq; + Seq -> LinearSeq; + Set -> SortedSet; + SortedSet -> BitSet; + Map -> SortedMap; +} diff --git a/resources/images/tour/collections-diagram-213.svg b/resources/images/tour/collections-diagram-213.svg new file mode 100644 index 0000000000..b12b436482 --- /dev/null +++ b/resources/images/tour/collections-diagram-213.svg @@ -0,0 +1,98 @@ + + + + + + +Collections + + +Iterable + +Iterable + + +Seq + +Seq + + +Iterable->Seq + + + + +Set + +Set + + +Iterable->Set + + + + +Map + +Map + + +Iterable->Map + + + + +IndexedSeq + +IndexedSeq + + +Seq->IndexedSeq + + + + +LinearSeq + +LinearSeq + + +Seq->LinearSeq + + + + +SortedSet + +SortedSet + + +Set->SortedSet + + + + +SortedMap + +SortedMap + + +Map->SortedMap + + + + +BitSet + +BitSet + + +SortedSet->BitSet + + + + + diff --git a/resources/images/tour/collections-diagram.dot b/resources/images/tour/collections-diagram.dot new file mode 100644 index 0000000000..ed837d3f77 --- /dev/null +++ b/resources/images/tour/collections-diagram.dot @@ -0,0 +1,22 @@ +digraph Collections { + edge [ + color="#7F7F7F" + ]; + node [ + shape="box", + style="rounded, filled", + fontcolor="#FFFFFF", + color="#6DC6E6" + ]; + rankdir="TB"; + + Traversable -> Iterable; + Iterable -> Seq; + Iterable -> Set; + Iterable -> Map; + Seq -> IndexedSeq; + Seq -> LinearSeq; + Set -> SortedSet; + SortedSet -> BitSet; + Map -> SortedMap; +} diff --git a/resources/images/tour/collections-diagram.svg b/resources/images/tour/collections-diagram.svg new file mode 100644 index 0000000000..4ecb4da875 --- /dev/null +++ b/resources/images/tour/collections-diagram.svg @@ -0,0 +1,108 @@ + + + + + + +Collections + + +Traversable + +Traversable + + +Iterable + +Iterable + + +Traversable->Iterable + + + + +Seq + +Seq + + +Iterable->Seq + + + + +Set + +Set + + +Iterable->Set + + + + +Map + +Map + + +Iterable->Map + + + + +IndexedSeq + +IndexedSeq + + +Seq->IndexedSeq + + + + +LinearSeq + +LinearSeq + + +Seq->LinearSeq + + + + +SortedSet + +SortedSet + + +Set->SortedSet + + + + +SortedMap + +SortedMap + + +Map->SortedMap + + + + +BitSet + +BitSet + + +SortedSet->BitSet + + + + + diff --git a/resources/images/tour/collections-immutable-diagram-213.dot b/resources/images/tour/collections-immutable-diagram-213.dot new file mode 100644 index 0000000000..59258f2a9b --- /dev/null +++ b/resources/images/tour/collections-immutable-diagram-213.dot @@ -0,0 +1,55 @@ +digraph ImmutableCollections { + edge [ + color="#7F7F7F" + ]; + node [ + shape="box", + style="rounded, filled", + fontcolor="#FFFFFF", + color="#6DC6E6" + ]; + rankdir="TB"; + + HashSet [color="#4A5659"]; + TreeSet [color="#4A5659"]; + ListSet [color="#4A5659"]; + HashMap [color="#4A5659"]; + TreeMap [color="#4A5659"]; + ListMap [color="#4A5659"]; + VectorMap [color="#4A5659"]; + Vector [color="#4A5659"]; + ArraySeq [color="#4A5659"]; + NumericRange [color="#4A5659"]; + String [color="#4A5659"]; + Range [color="#4A5659"]; + List [color="#4A5659"]; + LazyList [color="#4A5659"]; + Queue [color="#4A5659"]; + + Iterable -> Set; + Iterable -> Seq [penwidth="4"]; + Iterable -> Map; + Set -> SortedSet; + Set -> HashSet [penwidth="4"]; + Set -> ListSet; + SortedSet -> BitSet; + SortedSet -> TreeSet; + Seq -> IndexedSeq; + Seq -> LinearSeq [penwidth="4"]; + IndexedSeq -> Vector [penwidth="4"]; + IndexedSeq -> ArraySeq; + IndexedSeq -> NumericRange; + IndexedSeq -> Range; + IndexedSeq -> String [style="dashed"]; + LinearSeq -> List [penwidth="4"]; + LinearSeq -> LazyList; + LinearSeq -> Queue; + Map -> HashMap [penwidth="4"]; + Map -> SortedMap; + Map -> SeqMap; + SortedMap -> TreeMap; + SeqMap -> ListMap; + SeqMap -> VectorMap; + + {rank=same; Seq; TreeMap} +} diff --git a/resources/images/tour/collections-immutable-diagram-213.svg b/resources/images/tour/collections-immutable-diagram-213.svg new file mode 100644 index 0000000000..4902e1a656 --- /dev/null +++ b/resources/images/tour/collections-immutable-diagram-213.svg @@ -0,0 +1,258 @@ + + + + + + +ImmutableCollections + + +HashSet + +HashSet + + +TreeSet + +TreeSet + + +ListSet + +ListSet + + +HashMap + +HashMap + + +TreeMap + +TreeMap + + +ListMap + +ListMap + + +VectorMap + +VectorMap + + +Vector + +Vector + + +ArraySeq + +ArraySeq + + +NumericRange + +NumericRange + + +String + +String + + +Range + +Range + + +List + +List + + +LazyList + +LazyList + + +Queue + +Queue + + +Iterable + +Iterable + + +Set + +Set + + +Iterable->Set + + + + +Seq + +Seq + + +Iterable->Seq + + + + +Map + +Map + + +Iterable->Map + + + + +Set->HashSet + + + + +Set->ListSet + + + + +SortedSet + +SortedSet + + +Set->SortedSet + + + + +IndexedSeq + +IndexedSeq + + +Seq->IndexedSeq + + + + +LinearSeq + +LinearSeq + + +Seq->LinearSeq + + + + +Map->HashMap + + + + +SortedMap + +SortedMap + + +Map->SortedMap + + + + +SeqMap + +SeqMap + + +Map->SeqMap + + + + +SortedSet->TreeSet + + + + +BitSet + +BitSet + + +SortedSet->BitSet + + + + +IndexedSeq->Vector + + + + +IndexedSeq->ArraySeq + + + + +IndexedSeq->NumericRange + + + + +IndexedSeq->String + + + + +IndexedSeq->Range + + + + +LinearSeq->List + + + + +LinearSeq->LazyList + + + + +LinearSeq->Queue + + + + +SortedMap->TreeMap + + + + +SeqMap->ListMap + + + + +SeqMap->VectorMap + + + + + diff --git a/resources/images/tour/collections-immutable-diagram.dot b/resources/images/tour/collections-immutable-diagram.dot new file mode 100644 index 0000000000..460913e7a6 --- /dev/null +++ b/resources/images/tour/collections-immutable-diagram.dot @@ -0,0 +1,53 @@ +digraph ImmutableCollections { + edge [ + color="#7F7F7F" + ]; + node [ + shape="box", + style="rounded, filled", + fontcolor="#FFFFFF", + color="#6DC6E6" + ]; + rankdir="TB"; + + HashSet [color="#4A5659"]; + TreeSet [color="#4A5659"]; + ListSet [color="#4A5659"]; + HashMap [color="#4A5659"]; + TreeMap [color="#4A5659"]; + ListMap [color="#4A5659"]; + Vector [color="#4A5659"]; + NumericRange [color="#4A5659"]; + String [color="#4A5659"]; + Range [color="#4A5659"]; + List [color="#4A5659"]; + Stack [color="#4A5659"]; + Stream [color="#4A5659"]; + Queue [color="#4A5659"]; + + Traversable -> Iterable [penwidth="4"]; + Iterable -> Set; + Iterable -> Seq [penwidth="4"]; + Iterable -> Map; + Set -> SortedSet; + Set -> HashSet [penwidth="4"]; + Set -> ListSet; + SortedSet -> BitSet; + SortedSet -> TreeSet; + Seq -> IndexedSeq; + Seq -> LinearSeq [penwidth="4"]; + IndexedSeq -> Vector [penwidth="4"]; + IndexedSeq -> NumericRange; + IndexedSeq -> Range; + IndexedSeq -> String [style="dashed"]; + LinearSeq -> List [penwidth="4"]; + LinearSeq -> Stack; + LinearSeq -> Stream; + LinearSeq -> Queue; + Map -> HashMap [penwidth="4"]; + Map -> ListMap; + Map -> SortedMap; + SortedMap -> TreeMap; + + {rank=same; Seq; TreeMap} +} diff --git a/resources/images/tour/collections-immutable-diagram.svg b/resources/images/tour/collections-immutable-diagram.svg new file mode 100644 index 0000000000..bb14323280 --- /dev/null +++ b/resources/images/tour/collections-immutable-diagram.svg @@ -0,0 +1,248 @@ + + + + + + +ImmutableCollections + + +HashSet + +HashSet + + +TreeSet + +TreeSet + + +ListSet + +ListSet + + +HashMap + +HashMap + + +TreeMap + +TreeMap + + +ListMap + +ListMap + + +Vector + +Vector + + +NumericRange + +NumericRange + + +String + +String + + +Range + +Range + + +List + +List + + +Stack + +Stack + + +Stream + +Stream + + +Queue + +Queue + + +Traversable + +Traversable + + +Iterable + +Iterable + + +Traversable->Iterable + + + + +Set + +Set + + +Iterable->Set + + + + +Seq + +Seq + + +Iterable->Seq + + + + +Map + +Map + + +Iterable->Map + + + + +Set->HashSet + + + + +Set->ListSet + + + + +SortedSet + +SortedSet + + +Set->SortedSet + + + + +IndexedSeq + +IndexedSeq + + +Seq->IndexedSeq + + + + +LinearSeq + +LinearSeq + + +Seq->LinearSeq + + + + +Map->HashMap + + + + +Map->ListMap + + + + +SortedMap + +SortedMap + + +Map->SortedMap + + + + +SortedSet->TreeSet + + + + +BitSet + +BitSet + + +SortedSet->BitSet + + + + +IndexedSeq->Vector + + + + +IndexedSeq->NumericRange + + + + +IndexedSeq->String + + + + +IndexedSeq->Range + + + + +LinearSeq->List + + + + +LinearSeq->Stack + + + + +LinearSeq->Stream + + + + +LinearSeq->Queue + + + + +SortedMap->TreeMap + + + + + diff --git a/resources/images/tour/collections-legend-diagram.dot b/resources/images/tour/collections-legend-diagram.dot new file mode 100644 index 0000000000..8eda960d45 --- /dev/null +++ b/resources/images/tour/collections-legend-diagram.dot @@ -0,0 +1,21 @@ +digraph Legend { + edge [ + color="#7F7F7F" + ]; + node [ + label="Trait" + shape="box", + style="rounded, filled", + fontcolor="#FFFFFF", + color="#6DC6E6" + ]; + rankdir="LR"; + + Class1 [label="Class", color="#4A5659"]; + Class2 [label="Class", color="#4A5659"]; + Class3 [label="Class", color="#4A5659"]; + + Trait1 -> Class1 [label="Implemented by"]; + Trait2 -> Class2 [label="Default Implementation", penwidth="4"]; + Trait3 -> Class3 [label="via Implicit Conversion", style="dashed"]; +} diff --git a/resources/images/tour/collections-legend-diagram.svg b/resources/images/tour/collections-legend-diagram.svg new file mode 100644 index 0000000000..0c30d40176 --- /dev/null +++ b/resources/images/tour/collections-legend-diagram.svg @@ -0,0 +1,61 @@ + + + + + + +Legend + + +Class1 + +Class + + +Class2 + +Class + + +Class3 + +Class + + +Trait1 + +Trait + + +Trait1->Class1 + + +Implemented by + + +Trait2 + +Trait + + +Trait2->Class2 + + +Default Implementation + + +Trait3 + +Trait + + +Trait3->Class3 + + +via Implicit Conversion + + + diff --git a/resources/images/tour/collections-mutable-diagram-213.dot b/resources/images/tour/collections-mutable-diagram-213.dot new file mode 100644 index 0000000000..e47d4ab1bf --- /dev/null +++ b/resources/images/tour/collections-mutable-diagram-213.dot @@ -0,0 +1,84 @@ +digraph MutableCollections { + edge [ + color="#7F7F7F" + ]; + node [ + shape="box", + style="rounded, filled", + fontcolor="#FFFFFF", + color="#6DC6E6" + ]; + rankdir="TB"; + + HashSet [color="#4A5659"]; + LinkedHashSet [color="#4A5659"]; + HashMap [color="#4A5659"]; + WeakHashMap [color="#4A5659"]; + LinkedHashMap [color="#4A5659"]; + ListMap [color="#4A5659"]; + TreeMap [color="#4A5659"]; + ArraySeq [color="#4A5659"]; + ArrayBuffer [color="#4A5659"]; + ArrayDeque [color="#4A5659"]; + StringBuilder [color="#4A5659"]; + ListBuffer [color="#4A5659"]; + Stack [color="#4A5659"]; + Queue [color="#4A5659"]; + PriorityQueue [color="#4A5659"]; + + Iterable -> Map; + Iterable -> Seq [penwidth="4"]; + Iterable -> Set; + Iterable -> PriorityQueue; + Map -> HashMap [penwidth="4"]; + Map -> WeakHashMap; + Map -> TreeMap; + Map -> ListMap; + Map -> MultiMap; + Map -> SeqMap; + SeqMap -> LinkedHashMap; + Set -> HashSet [penwidth="4"]; + Set -> LinkedHashSet; + Set -> SortedSet; + SortedSet -> BitSet; + Seq -> IndexedSeq [penwidth="4"]; + Seq -> Buffer; + ArrayDeque -> Stack; + IndexedSeq -> ArraySeq; + IndexedSeq -> StringBuilder; + IndexedSeq -> ArrayBuffer [penwidth="4"]; + IndexedSeq -> ArrayDeque; + Buffer -> ArrayBuffer [penwidth="4"]; + Buffer -> ArrayDeque; + Buffer -> ListBuffer; + ArrayDeque -> Queue; + + {rank=same; + Iterable; + PriorityQueue} + {rank=same; + Map; + Set} + {rank=same; + WeakHashMap; + LinkedHashMap; + ListMap; + BitSet; + LinkedHashSet; + Seq} + {rank=same; + HashMap; + MultiMap; + HashSet} + {rank=same; + IndexedSeq; + Buffer} + {rank=same; + ArraySeq; + ArrayBuffer} + {rank=same; + StringBuilder; + ListBuffer; + Queue; + Stack} +} diff --git a/resources/images/tour/collections-mutable-diagram-213.svg b/resources/images/tour/collections-mutable-diagram-213.svg new file mode 100644 index 0000000000..760646161e --- /dev/null +++ b/resources/images/tour/collections-mutable-diagram-213.svg @@ -0,0 +1,268 @@ + + + + + + +MutableCollections + + +HashSet + +HashSet + + +LinkedHashSet + +LinkedHashSet + + +HashMap + +HashMap + + +WeakHashMap + +WeakHashMap + + +LinkedHashMap + +LinkedHashMap + + +ListMap + +ListMap + + +TreeMap + +TreeMap + + +ArraySeq + +ArraySeq + + +ArrayBuffer + +ArrayBuffer + + +ArrayDeque + +ArrayDeque + + +Stack + +Stack + + +ArrayDeque->Stack + + + + +Queue + +Queue + + +ArrayDeque->Queue + + + + +StringBuilder + +StringBuilder + + +ListBuffer + +ListBuffer + + +PriorityQueue + +PriorityQueue + + +Iterable + +Iterable + + +Iterable->PriorityQueue + + + + +Map + +Map + + +Iterable->Map + + + + +Seq + +Seq + + +Iterable->Seq + + + + +Set + +Set + + +Iterable->Set + + + + +Map->HashMap + + + + +Map->WeakHashMap + + + + +Map->ListMap + + + + +Map->TreeMap + + + + +MultiMap + +MultiMap + + +Map->MultiMap + + + + +SeqMap + +SeqMap + + +Map->SeqMap + + + + +IndexedSeq + +IndexedSeq + + +Seq->IndexedSeq + + + + +Buffer + +Buffer + + +Seq->Buffer + + + + +Set->HashSet + + + + +Set->LinkedHashSet + + + + +SortedSet + +SortedSet + + +Set->SortedSet + + + + +SeqMap->LinkedHashMap + + + + +BitSet + +BitSet + + +SortedSet->BitSet + + + + +IndexedSeq->ArraySeq + + + + +IndexedSeq->ArrayBuffer + + + + +IndexedSeq->ArrayDeque + + + + +IndexedSeq->StringBuilder + + + + +Buffer->ArrayBuffer + + + + +Buffer->ArrayDeque + + + + +Buffer->ListBuffer + + + + + diff --git a/resources/images/tour/collections-mutable-diagram.dot b/resources/images/tour/collections-mutable-diagram.dot new file mode 100644 index 0000000000..03d032eadf --- /dev/null +++ b/resources/images/tour/collections-mutable-diagram.dot @@ -0,0 +1,123 @@ +digraph MutableCollections { + edge [ + color="#7F7F7F" + ]; + node [ + shape="box", + style="rounded, filled", + fontcolor="#FFFFFF", + color="#6DC6E6" + ]; + rankdir="TB"; + + HashSet [color="#4A5659"]; + ImmutableSetAdaptor [color="#4A5659"]; + LinkedHashSet [color="#4A5659"]; + HashMap [color="#4A5659"]; + OpenHashMap [color="#4A5659"]; + WeakHashMap [color="#4A5659"]; + LinkedHashMap [color="#4A5659"]; + ListMap [color="#4A5659"]; + TreeMap [color="#4A5659"]; + ImmutableMapAdaptor [color="#4A5659"]; + ArraySeq [color="#4A5659"]; + ArrayBuffer [color="#4A5659"]; + StringBuilder [color="#4A5659"]; + ListBuffer [color="#4A5659"]; + Stack [color="#4A5659"]; + ArrayStack [color="#4A5659"]; + SynchronizedStack [color="#4A5659"]; + PriorityQueue [color="#4A5659"]; + SynchronizedPriorityQueue [color="#4A5659"]; + SynchronizedQueue [color="#4A5659"]; + MutableList [color="#4A5659"]; + LinkedList [color="#4A5659"]; + DoubleLinkedList [color="#4A5659"]; + + Traversable -> Iterable [penwidth="4"]; + Iterable -> Map; + Iterable -> Seq [penwidth="4"]; + Iterable -> Set; + Iterable -> PriorityQueue; + Map -> HashMap [penwidth="4"]; + Map -> WeakHashMap; + Map -> OpenHashMap; + Map -> LinkedHashMap; + Map -> ObservableMap; + Map -> SynchronizedMap; + Map -> ImmutableMapAdaptor; + Map -> TreeMap; + Map -> ListMap; + Map -> MultiMap; + Set -> HashSet [penwidth="4"]; + Set -> ObservableSet; + Set -> ImmutableSetAdaptor; + Set -> LinkedHashSet; + Set -> SynchronizedSet; + Set -> SortedSet; + SortedSet -> BitSet; + Seq -> LinearSeq; + Seq -> IndexedSeq [penwidth="4"]; + Seq -> Buffer; + Seq -> Stack; + Seq -> ArrayStack; + LinearSeq -> MutableList [penwidth="4"]; + LinearSeq -> LinkedList; + LinearSeq -> DoubleLinkedList; + IndexedSeq -> ArraySeq; + IndexedSeq -> StringBuilder; + IndexedSeq -> ArrayBuffer [penwidth="4"]; + Buffer -> ArrayBuffer [penwidth="4"]; + Buffer -> ObservableBuffer; + Buffer -> SynchronizedBuffer; + Buffer -> ListBuffer; + Stack -> SynchronizedStack; + PriorityQueue -> SynchronizedPriorityQueue; + MutableList -> Queue; + Queue -> SynchronizedQueue; + + {rank=same; + Iterable; + PriorityQueue; + SynchronizedPriorityQueue} + {rank=same; + Map; + Set} + {rank=same; + WeakHashMap; + LinkedHashMap; + ListMap; + ObservableMap; + ImmutableMapAdaptor; + BitSet; + LinkedHashSet; + ObservableSet; + Seq} + {rank=same; + HashMap; + OpenHashMap; + SynchronizedMap; + MultiMap; + HashSet; + ImmutableSetAdaptor; + SynchronizedSet} + {rank=same; + IndexedSeq; + Buffer; + LinearSeq; + Stack; + ArrayStack} + {rank=same; + ArraySeq; + ArrayBuffer; + SynchronizedBuffer; + SynchronizedStack; + MutableList; + LinkedList} + {rank=same; + ObservableBuffer; + StringBuilder; + ListBuffer; + Queue; + DoubleLinkedList} +} diff --git a/resources/images/tour/collections-mutable-diagram.svg b/resources/images/tour/collections-mutable-diagram.svg new file mode 100644 index 0000000000..dee3618e45 --- /dev/null +++ b/resources/images/tour/collections-mutable-diagram.svg @@ -0,0 +1,423 @@ + + + + + + +MutableCollections + + +HashSet + +HashSet + + +ImmutableSetAdaptor + +ImmutableSetAdaptor + + +LinkedHashSet + +LinkedHashSet + + +HashMap + +HashMap + + +OpenHashMap + +OpenHashMap + + +WeakHashMap + +WeakHashMap + + +LinkedHashMap + +LinkedHashMap + + +ListMap + +ListMap + + +TreeMap + +TreeMap + + +ImmutableMapAdaptor + +ImmutableMapAdaptor + + +ArraySeq + +ArraySeq + + +ArrayBuffer + +ArrayBuffer + + +StringBuilder + +StringBuilder + + +ListBuffer + +ListBuffer + + +Stack + +Stack + + +SynchronizedStack + +SynchronizedStack + + +Stack->SynchronizedStack + + + + +ArrayStack + +ArrayStack + + +PriorityQueue + +PriorityQueue + + +SynchronizedPriorityQueue + +SynchronizedPriorityQueue + + +PriorityQueue->SynchronizedPriorityQueue + + + + +SynchronizedQueue + +SynchronizedQueue + + +MutableList + +MutableList + + +Queue + +Queue + + +MutableList->Queue + + + + +LinkedList + +LinkedList + + +DoubleLinkedList + +DoubleLinkedList + + +Traversable + +Traversable + + +Iterable + +Iterable + + +Traversable->Iterable + + + + +Iterable->PriorityQueue + + + + +Map + +Map + + +Iterable->Map + + + + +Seq + +Seq + + +Iterable->Seq + + + + +Set + +Set + + +Iterable->Set + + + + +Map->HashMap + + + + +Map->OpenHashMap + + + + +Map->WeakHashMap + + + + +Map->LinkedHashMap + + + + +Map->ListMap + + + + +Map->TreeMap + + + + +Map->ImmutableMapAdaptor + + + + +ObservableMap + +ObservableMap + + +Map->ObservableMap + + + + +SynchronizedMap + +SynchronizedMap + + +Map->SynchronizedMap + + + + +MultiMap + +MultiMap + + +Map->MultiMap + + + + +Seq->Stack + + + + +Seq->ArrayStack + + + + +LinearSeq + +LinearSeq + + +Seq->LinearSeq + + + + +IndexedSeq + +IndexedSeq + + +Seq->IndexedSeq + + + + +Buffer + +Buffer + + +Seq->Buffer + + + + +Set->HashSet + + + + +Set->ImmutableSetAdaptor + + + + +Set->LinkedHashSet + + + + +ObservableSet + +ObservableSet + + +Set->ObservableSet + + + + +SynchronizedSet + +SynchronizedSet + + +Set->SynchronizedSet + + + + +SortedSet + +SortedSet + + +Set->SortedSet + + + + +BitSet + +BitSet + + +SortedSet->BitSet + + + + +LinearSeq->MutableList + + + + +LinearSeq->LinkedList + + + + +LinearSeq->DoubleLinkedList + + + + +IndexedSeq->ArraySeq + + + + +IndexedSeq->ArrayBuffer + + + + +IndexedSeq->StringBuilder + + + + +Buffer->ArrayBuffer + + + + +Buffer->ListBuffer + + + + +ObservableBuffer + +ObservableBuffer + + +Buffer->ObservableBuffer + + + + +SynchronizedBuffer + +SynchronizedBuffer + + +Buffer->SynchronizedBuffer + + + + +Queue->SynchronizedQueue + + + + + diff --git a/resources/images/travis-publishing-key.png b/resources/images/travis-publishing-key.png new file mode 100644 index 0000000000..f748d7c097 Binary files /dev/null and b/resources/images/travis-publishing-key.png differ diff --git a/resources/img/books/CreativeScala.png b/resources/img/books/CreativeScala.png new file mode 100644 index 0000000000..b965d9983a Binary files /dev/null and b/resources/img/books/CreativeScala.png differ diff --git a/resources/img/books/FPiS_93x116.jpg b/resources/img/books/FPiS_93x116.jpg new file mode 100644 index 0000000000..dac8f9d915 Binary files /dev/null and b/resources/img/books/FPiS_93x116.jpg differ diff --git a/resources/img/books/FPiS_93x116.png b/resources/img/books/FPiS_93x116.png deleted file mode 100644 index c942bd6bab..0000000000 Binary files a/resources/img/books/FPiS_93x116.png and /dev/null differ diff --git a/resources/img/books/HandsOnScala.jpg b/resources/img/books/HandsOnScala.jpg new file mode 100644 index 0000000000..f279aa5995 Binary files /dev/null and b/resources/img/books/HandsOnScala.jpg differ diff --git a/resources/img/books/ProgrammingInScala.gif b/resources/img/books/ProgrammingInScala.gif deleted file mode 100644 index 06452435db..0000000000 Binary files a/resources/img/books/ProgrammingInScala.gif and /dev/null differ diff --git a/resources/img/books/ProgrammingInScala.png b/resources/img/books/ProgrammingInScala.png new file mode 100644 index 0000000000..bfc20e4d56 Binary files /dev/null and b/resources/img/books/ProgrammingInScala.png differ diff --git a/resources/img/books/ProgrammingScala-final-border.gif b/resources/img/books/ProgrammingScala-final-border.gif index 69f7cb8cad..a8646acbdd 100644 Binary files a/resources/img/books/ProgrammingScala-final-border.gif and b/resources/img/books/ProgrammingScala-final-border.gif differ diff --git a/resources/img/books/ProgrammingScala.jpg b/resources/img/books/ProgrammingScala.jpg index 07db7ec46a..232d0abff8 100644 Binary files a/resources/img/books/ProgrammingScala.jpg and b/resources/img/books/ProgrammingScala.jpg differ diff --git a/resources/img/books/get-programming-book.png b/resources/img/books/get-programming-book.png new file mode 100644 index 0000000000..93dd8c60e5 Binary files /dev/null and b/resources/img/books/get-programming-book.png differ diff --git a/resources/img/books/scala_for_the_impatient.jpg b/resources/img/books/scala_for_the_impatient.jpg new file mode 100644 index 0000000000..c1dab91058 Binary files /dev/null and b/resources/img/books/scala_for_the_impatient.jpg differ diff --git a/resources/img/books/scala_for_the_impatient.png b/resources/img/books/scala_for_the_impatient.png deleted file mode 100644 index 012367038d..0000000000 Binary files a/resources/img/books/scala_for_the_impatient.png and /dev/null differ diff --git a/resources/img/foundreq.jpg b/resources/img/foundreq.jpg new file mode 100644 index 0000000000..47c56099da Binary files /dev/null and b/resources/img/foundreq.jpg differ diff --git a/resources/img/foundreq_record.jpg b/resources/img/foundreq_record.jpg new file mode 100644 index 0000000000..c54f105ecc Binary files /dev/null and b/resources/img/foundreq_record.jpg differ diff --git a/resources/img/frontpage/discord-logo.png b/resources/img/frontpage/discord-logo.png new file mode 100644 index 0000000000..c055c19c6c Binary files /dev/null and b/resources/img/frontpage/discord-logo.png differ diff --git a/resources/img/frontpage/gitter-logo.png b/resources/img/frontpage/gitter-logo.png deleted file mode 100644 index ff91a264d4..0000000000 Binary files a/resources/img/frontpage/gitter-logo.png and /dev/null differ diff --git a/resources/img/implicits-circe.jpg b/resources/img/implicits-circe.jpg new file mode 100644 index 0000000000..840898eb81 Binary files /dev/null and b/resources/img/implicits-circe.jpg differ diff --git a/resources/img/implicits-compact.jpg b/resources/img/implicits-compact.jpg new file mode 100644 index 0000000000..900820c8ca Binary files /dev/null and b/resources/img/implicits-compact.jpg differ diff --git a/resources/js/functions.js b/resources/js/functions.js index ed94b16a9f..686a38f47b 100644 --- a/resources/js/functions.js +++ b/resources/js/functions.js @@ -65,14 +65,11 @@ $(document).ready(function() { // Highlight $(document).ready(function() { hljs.configure({ - languages: ["scala", "bash"] + languages: ["scala", "bash"], + noHighlightRe: /^hljs-skip$/i }) - hljs.initHighlighting(); -}); - -// Show Blog -$(".hide").click(function() { - $(".new-on-the-blog").hide(); + hljs.registerLanguage("scala", highlightDotty); + hljs.highlightAll(); }); // Documentation menu dropdown toggle @@ -133,30 +130,6 @@ $(document).ready(function() { return false; }; - - $('.white-card').each(function(index) { - if (!$(this).hasOverflow()) { - $(this).find(".expand-btn").hide(); - $(this).find(".go-btn").show(); - } - }); - - $(".card-footer").click(function() { - // if we clicked on the expand button, expand the box - if ($(this).find(".expand-btn").is(':visible')) { - - // height mangling becasue flexbox align-self: self-end; doesn't work :( - $(this).parent().css('max-height', 'none'); - var cardWrapHeight = $(this).parent().find(".card-wrap").outerHeight(); - var cardFooterHeight = $(this).outerHeight() - $(this).parent().outerHeight(cardWrapHeight + cardFooterHeight); - - $(this).find(".expand-btn").hide(); - $(this).find(".go-btn").show(); - } else { - window.location.href = $(this).find(".go-btn").attr("href"); - } - }); }); @@ -171,7 +144,7 @@ $(document).ready(function() { old.empty(); // if there are no translations, hide language dropdown box - if (items.length <= 1) { + if (items.length === 0) { $("#dd").hide(); } }); @@ -299,32 +272,19 @@ $(document).ready(function() { $(document).ready(function() { if ($("#sidebar-toc").length) { $('#toc').toc({ - exclude: 'h1, h5, h6', - context: '.inner-box', + exclude: 'h1, h4, h5, h6', + context: '.toc-context', autoId: true, numerate: false }); - toggleStickyToc(); + const target = $('#sidebar-toc .active'); + if (target.length) { + const marginTop = $('#sidebar-toc .type-chapter').length ? 15 : 10; + $('#sidebar-toc').animate({scrollTop: target.position().top - marginTop}, 200); + }; } -}) - -$(window).resize(function() { - toggleStickyToc(); }); -var toggleStickyToc = function() { - if ($("#sidebar-toc").length) { - if ($(window).width() <= 992) { - $(".sidebar-toc-wrapper").unstick(); - } else { - $(".sidebar-toc-wrapper").sticky({ - topSpacing: 0, - bottomSpacing: 500 - }); - } - } -} - // Language dropdown function DropDown(el) { this.dd = el; @@ -424,25 +384,151 @@ $(document).ready(function() { } }); +// Browser Storage Support (https://stackoverflow.com/a/41462752/2538602) +function storageAvailable(type) { + try { + var storage = window[type], + x = '__storage_test__'; + storage.setItem(x, x); + storage.removeItem(x); + return true; + } + catch (e) { + return false; + } +} + +// Store preference for Scala 2 vs 3 +$(document).ready(function() { + + const Storage = (namespace) => { + return ({ + getPreference(key, defaultValue) { + const res = localStorage.getItem(`${namespace}.${key}`); + return res === null ? defaultValue : res; + }, + setPreference(key, value, onChange) { + const old = this.getPreference(key, null); + if (old !== value) { // activate effect only if value changed. + localStorage.setItem(`${namespace}.${key}`, value); + onChange(old); + } + } + }); + }; + + function activateTab(tabs, value) { + // check the code tab corresponding to the preferred value + tabs.find('input[data-target=' + value + ']').prop("checked", true); + } + + /** Links all tabs created in Liquid templates with class ".tabs-$namespace" + * on the page together, such that + * changing a tab to some value will activate all other tab sections to + * also change to that value. + * Also records a preference for the tab in localStorage, so + * that when the page is refreshed, the same tab will be selected. + * On page load, selects the tab corresponding to stored value. + */ + function setupTabs(tabs, namespace, defaultValue, storage) { + const preferredValue = storage.getPreference(namespace, defaultValue); + + activateTab(tabs, preferredValue) + + // setup listeners to record new preferred Scala version. + tabs.find('input').on('change', function() { + // if checked then set the preferred version, and activate the other tabs on page. + if ($(this).is(':checked')) { + const parent = $(this).parent(); + const newValue = $(this).data('target'); + + storage.setPreference(namespace, newValue, _ => { + // when we set a new scalaVersion, find scalaVersionTabs except current one + // and activate those tabs. + activateTab(tabs.not(parent), newValue); + }); + + } + + }); + } + + function setupAlertCancel(alert, storage) { + const messageId = alert.data('message_id'); + let onHide = () => {}; + if (messageId) { + const key = `alert.${messageId}`; + const isHidden = storage.getPreference(key, 'show') === 'hidden'; + if (isHidden) { + alert.hide(); + } + onHide = () => storage.setPreference(key, 'hidden', _ => {}); + } + + + alert.find('.hide').click(function() { + alert.hide(), onHide(); + }); + } + + function setupAllTabs(storage) { + var scalaVersionTabs = $(".tabsection.tabs-scala-version"); + if (scalaVersionTabs.length) { + setupTabs(scalaVersionTabs, "scalaVersion", "scala-3", storage); + } + var buildToolTabs = $(".tabsection.tabs-build-tool"); + if (buildToolTabs.length) { + setupTabs(buildToolTabs, "buildTool", "scala-cli", storage); + } + } + + function setupAllAlertCancels(storage) { + var alertBanners = $(".new-on-the-blog.alert-warning"); + if (alertBanners.length) { + setupAlertCancel(alertBanners, storage); + } + } + + if (storageAvailable('localStorage')) { + const PreferenceStorage = Storage('org.scala-lang.docs.preferences'); + setupAllTabs(PreferenceStorage); + setupAllAlertCancels(PreferenceStorage); + } + +}); + // OS detection function getOS() { var osname = "linux"; if (navigator.appVersion.indexOf("Win") != -1) osname = "windows"; - if (navigator.appVersion.indexOf("Mac") != -1) osname = "osx"; + if (navigator.appVersion.indexOf("Mac") != -1) osname = "macos"; if (navigator.appVersion.indexOf("Linux") != -1) osname = "linux"; if (navigator.appVersion.indexOf("X11") != -1) osname = "unix"; return osname; } -$(document).ready(function() { - if ($(".main-download").length) { +$(document).ready(function () { + // for each code snippet area, find the copy button, + // and add a click listener that will copy text from + // the code area to the clipboard + $(".code-snippet-area").each(function () { + var area = this; + $(area).children(".code-snippet-buttons").children("button.copy-button").click(function () { + var code = $(area).children(".code-snippet-display").children("code").text(); + window.navigator.clipboard.writeText(code); + }); + }); +}); + +$(document).ready(function () { + // click the get-started tab corresponding to the users OS. + var platformOSOptions = $(".tabsection.platform-os-options"); + if (platformOSOptions.length) { var os = getOS(); - var intelliJlink = $("#intellij-" + os).text(); - var sbtLink = $("#sbt-" + os).text(); - var stepOneContent = $("#stepOne-" + os).html() - $("#download-intellij-link").attr("href", intelliJlink); - $("#download-sbt-link").attr("href", sbtLink); - $("#download-step-one").html(stepOneContent); + if (os === 'unix') { + os = 'linux'; + } + platformOSOptions.find('input[data-target=' + os + ']').prop("checked", true); } }); @@ -476,17 +562,17 @@ function updatePointer() { // Glossary search $(document).ready(function() { -$('#filter').focus(); +$('#filter-glossary-terms').focus(); - $("#filter").keyup(function(){ + $("#filter-glossary-terms").keyup(function(){ // Retrieve the input field text and reset the count to zero var filter = $(this).val(), count = 0; // Loop through the comment list - $(".glossary > .inner-box > ul li").each(function(){ + $(".glossary .toc-context > ul li").each(function(){ // If the name of the glossary term does not contain the text phrase fade it out - if (jQuery(this).find("h4").text().search(new RegExp(filter, "i")) < 0) { + if (jQuery(this).find("h3").text().search(new RegExp(filter, "i")) < 0) { $(this).fadeOut(); // Show the list item if the phrase matches and increase the count by 1 @@ -509,18 +595,18 @@ $('#filter').focus(); //Footer scroll to top button -$(document).ready(function(){ - $(window).scroll(function(){ - if ($(this).scrollTop() > 100) { - $('#scroll-to-top-btn').fadeIn(); - } else { - $('#scroll-to-top-btn').fadeOut(); - } - }); - $('#scroll-to-top-btn').click(function(){ - $("html, body").animate({ scrollTop: 0 }, 600); - return false; - }); +$(document).ready(function(){ + $(window).scroll(function(){ + if ($(this).scrollTop() > 100) { + $('#scroll-to-top-btn').fadeIn(); + } else { + $('#scroll-to-top-btn').fadeOut(); + } + }); + $('#scroll-to-top-btn').click(function(){ + $("html, body").animate({ scrollTop: 0 }, 600); + return false; + }); }); //Contributors widget @@ -532,7 +618,7 @@ $(document).ready(function () { * - some files aren't prefixed with underscore, see rootFiles * - some files are placed in _overviews but rendered to its folder, see overviewsFolders */ - + let rootFiles = ['getting-started', 'learn', 'glossary']; let overviewsFolders = ['FAQ', 'cheatsheets', 'collections', 'compiler-options', 'core', 'jdk-compatibility', 'macros', 'parallel-collections', @@ -547,12 +633,16 @@ $(document).ready(function () { let isInOverviewsFolder = overviewsFolders.some(of => thisPageUrl.startsWith(of)); if(isRootFile) { thisPageUrl = thisPageUrl + '.md'; + } else if(thisPageUrl.indexOf("tutorials/FAQ/") == 0) { + thisPageUrl = '_overviews/' + thisPageUrl.substring("tutorials/".length) + '.md'; } else if(isInOverviewsFolder) { thisPageUrl = '_overviews/'+ thisPageUrl + '.md'; + } else if (thisPageUrl.startsWith('scala3/book')) { + thisPageUrl = '_overviews/scala3-book/' + thisPageUrl.substring("scala3/book/".length) + '.md'; } else { thisPageUrl = '_' + thisPageUrl + '.md'; } - + let url = githubApiUrl + '?path=' + thisPageUrl; $.get(url, function (data, status) { if(!data || data.length < 1) { @@ -603,3 +693,15 @@ $(document).ready(function () { $('#contributors').html(contributorsHtml); }); }); + +$(document).ready(function() { + const icon = '' + const anchor = '' + + $('.content-primary.documentation').find('h1, h2, h3, h4, h5, h6').each(function() { + const id = $(this).attr('id'); + if (id) { + $(this).append($(anchor).attr('href', '#' + id).html(icon)); + } + }); +}); diff --git a/resources/js/hljs-scala3.js b/resources/js/hljs-scala3.js new file mode 100644 index 0000000000..e0be3758b8 --- /dev/null +++ b/resources/js/hljs-scala3.js @@ -0,0 +1,504 @@ +function highlightDotty(hljs) { + + // identifiers + const capitalizedId = /\b[A-Z][$\w]*\b/ + const alphaId = /[a-zA-Z$_][$\w]*/ + const op1 = /[^\s\w\d,;"'()[\]{}=:]/ + const op2 = /[^\s\w\d,;"'()[\]{}]/ + const compound = `[a-zA-Z$][a-zA-Z0-9$]*_${op2.source}` // e.g. value_= + const id = new RegExp(`(${compound}|${alphaId.source}|${op2.source}{2,}|${op1.source}+|\`.+?\`)`) + + // numbers + const hexDigit = '[a-fA-F0-9]' + const hexNumber = `0[xX](${hexDigit})+(_(${hexDigit})+)*[lL]?` + const wholePart = `(\\d+)(_\\d+)*` + const decPoint = `\\.\\d+` + const floatingSuffix = `([eE][-+]?\\d+)?[fFdD]?` + const intOrFloat = `${decPoint}${floatingSuffix}|\\b${wholePart}([lLfFdD]|(${decPoint})?${floatingSuffix})` + const number = new RegExp(`(-?)((\\b(${hexNumber})|${intOrFloat}))`) + + // Regular Keywords + // The "soft" keywords (e.g. 'using') are added later where necessary + const alwaysKeywords = { + $pattern: /(\w+|\?=>|\?{1,3}|=>>|=>|<:|>:|_|#|<-|\.nn)/, + keyword: + 'abstract case catch class def do else enum export extends final finally for given ' + + 'if implicit import lazy match new object package private protected override return ' + + 'sealed then throw trait true try type val var while with yield =>> => ?=> <: >: _ ? <- #', + literal: 'true false null this super', + built_in: '??? asInstanceOf isInstanceOf assert implicitly locally summon valueOf .nn' + } + const modifiers = 'abstract|final|implicit|override|private|protected|sealed' + + // End of class, enum, etc. header + const templateDeclEnd = /(\/[/*]|{|:(?= *\n)|\n(?! *(extends|with|derives)))/ + + // all the keywords + soft keywords, separated by spaces + function withSoftKeywords(kwd) { + return { + $pattern: alwaysKeywords.$pattern, + keyword: kwd + ' ' + alwaysKeywords.keyword, + literal: alwaysKeywords.literal, + built_in: alwaysKeywords.built_in + } + } + + // title inside of a complex token made of several parts, but colored as a type (e.g. class) + const TP_TITLE = { + className: 'type', + begin: id, + returnEnd: true, + keywords: alwaysKeywords.keyword, + literal: alwaysKeywords.literal, + built_in: alwaysKeywords.built_in + } + + // title inside of a complex token made of several parts (e.g. class) + const TITLE = { + className: 'title', + begin: id, + returnEnd: true, + keywords: alwaysKeywords.keyword, + literal: alwaysKeywords.literal, + built_in: alwaysKeywords.built_in + } + + // title that goes to the end of a simple token (e.g. val) + const TITLE2 = { + className: 'title', + begin: id, + excludeEnd: true, + endsWithParent: true + } + + const TYPED = { + begin: /: (?=[a-zA-Z()?])/, + end: /\/\/|\/\*|\n/, + endsWithParent: true, + returnEnd: true, + contains: [ + { + // works better than the usual way of defining keyword, + // in this specific situation + className: 'keyword', + begin: /\?\=>|=>>|[=:][><]|\?/, + }, + { + className: 'type', + begin: alphaId + } + ] + } + + const PROBABLY_TYPE = { + className: 'type', + begin: capitalizedId, + relevance: 0 + } + + const NUMBER = { + className: 'number', + begin: number, + relevance: 0, + } + + const CHAR = { + className: 'string', + begin: /\'([^'\\]|\\[\s\S])\'/, + relevance: 0, + } + + // type parameters within [square brackets] + const TPARAMS = { + begin: /\[/, end: /\]/, + keywords: { + $pattern: /<:|>:|[+-?_:]/, + keyword: '<: >: : + - ? _' + }, + contains: [ + hljs.C_BLOCK_COMMENT_MODE, + { + className: 'type', + begin: alphaId + }, + ], + relevance: 3 + } + + // Class or method parameters declaration + const PARAMS = { + className: 'params', + begin: /\(/, end: /\)/, + excludeBegin: true, + excludeEnd: true, + keywords: withSoftKeywords('inline using'), + contains: [ + hljs.C_BLOCK_COMMENT_MODE, + hljs.QUOTE_STRING_MODE, + PROBABLY_TYPE + ] + } + + // (using T1, T2, T3) + const CTX_PARAMS = { + className: 'params', + begin: /\(using (?!\w+:)/, end: /\)/, + excludeBegin: false, + excludeEnd: true, + relevance: 5, + keywords: withSoftKeywords('using'), + contains: [ + PROBABLY_TYPE + ] + } + + // String interpolation + const SUBST = { + className: 'subst', + variants: [ + { begin: /\$[a-zA-Z_]\w*/ }, + { + begin: /\${/, end: /}/, + contains: [ + NUMBER, + hljs.QUOTE_STRING_MODE + ] + } + ] + } + + // "string" or """string""", with or without interpolation + const STRING = { + className: 'string', + variants: [ + hljs.QUOTE_STRING_MODE, + { + begin: '"""', end: '"""', + contains: [hljs.BACKSLASH_ESCAPE], + relevance: 10 + }, + { + begin: alphaId.source + '"', end: '"', + contains: [hljs.BACKSLASH_ESCAPE, SUBST], + illegal: /\n/, + relevance: 5 + }, + { + begin: alphaId.source + '"""', end: '"""', + contains: [hljs.BACKSLASH_ESCAPE, SUBST], + relevance: 10 + } + ] + } + + // Class or method apply + const APPLY = { + begin: /\(/, end: /\)/, + excludeBegin: true, excludeEnd: true, + keywords: { + $pattern: alwaysKeywords.$pattern, + keyword: 'using ' + alwaysKeywords.keyword, + literal: alwaysKeywords.literal, + built_in: alwaysKeywords.built_in + }, + contains: [ + STRING, + NUMBER, + CHAR, + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + PROBABLY_TYPE, + ] + } + + // @annot(...) or @my.package.annot(...) + const ANNOTATION = { + className: 'meta', + begin: `@${id.source}(\\.${id.source})*`, + contains: [ + APPLY, + hljs.C_BLOCK_COMMENT_MODE + ] + } + + // glob all non-whitespace characters as a "string" + const DIRECTIVE_VALUE = { + className: 'string', + begin: /\S+/, + } + + // glob all non-whitespace characters as a "type", so that we can highlight differently to values + const DIRECTIVE_KEY = { + className: 'type', + begin: /\S+/, + } + + // directives + const USING_DIRECTIVE = hljs.COMMENT('//>', '\n', { + contains: [ + { + begin: /using /, + end: /\s/, + keywords: 'using', + contains: [ + DIRECTIVE_KEY + ] + }, + DIRECTIVE_VALUE, + ] + }) + + // Documentation + const SCALADOC = hljs.COMMENT('/\\*\\*', '\\*/', { + contains: [ + { + className: 'doctag', + begin: /@[a-zA-Z]+/ + }, + // markdown syntax elements: + { + className: 'code', + variants: [ + { begin: /```.*\n/, end: /```/ }, + { begin: /`/, end: /`/ } + ], + }, + { + className: 'bold', + variants: [ + { begin: /\*\*/, end: /\*\*/ }, + { begin: /__/, end: /__/ } + ], + }, + { + className: 'emphasis', + variants: [ + { begin: /\*(?!([\*\s/])|([^\*]*\*[\*/]))/, end: /\*/ }, + { begin: /_/, end: /_/ } + ], + }, + { + className: 'bullet', // list item + begin: /- (?=\S)/, end: /\s/, + }, + { + begin: /\[.*?\]\(/, end: /\)/, + contains: [ + { + // mark as "link" only the URL + className: 'link', + begin: /.*?/, + endsWithParent: true + } + ] + } + ] + }) + + // Methods + const METHOD = { + className: 'function', + begin: `((${modifiers}|transparent|inline|infix) +)*def `, end: / =\s|\n/, + excludeEnd: true, + relevance: 5, + keywords: withSoftKeywords('inline infix transparent'), + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + TPARAMS, + CTX_PARAMS, + PARAMS, + TYPED, // prevents the ":" (declared type) to become a title + PROBABLY_TYPE, + TITLE + ] + } + + // Variables & Constants + const VAL = { + beginKeywords: 'val var', end: /[=:;\n/]/, + excludeEnd: true, + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + TITLE2 + ] + } + + // Type declarations + const TYPEDEF = { + className: 'typedef', + begin: `((${modifiers}|opaque) +)*type `, end: /[=;\n]| ?[<>]:/, + excludeEnd: true, + keywords: withSoftKeywords('opaque'), + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + PROBABLY_TYPE, + TITLE, + ] + } + + // Given instances + const GIVEN = { + begin: `((${modifiers}|transparent|inline) +)*given `, end: / =|[=;\n]/, + excludeEnd: true, + keywords: withSoftKeywords('inline transparent given using with'), + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + PARAMS, + CTX_PARAMS, + PROBABLY_TYPE, + TITLE + ] + } + + // Extension methods + const EXTENSION = { + begin: /extension/, end: /(\n|def)/, + returnEnd: true, + keywords: 'extension implicit using', + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + CTX_PARAMS, + PARAMS, + PROBABLY_TYPE + ] + } + + // 'end' soft keyword + const END = { + begin: `end(?= (if|while|for|match|try|given|extension|this|val|${id.source})\\n)`, end: /\s/, + keywords: 'end' + } + + // Classes, traits, enums, etc. + const EXTENDS_PARENT = { + begin: ' extends ', end: /( with | derives |\/[/*])/, + endsWithParent: true, + returnEnd: true, + keywords: 'extends', + contains: [APPLY, PROBABLY_TYPE] + } + const WITH_MIXIN = { + begin: ' with ', end: / derives |\/[/*]/, + endsWithParent: true, + returnEnd: true, + keywords: 'with', + contains: [APPLY, PROBABLY_TYPE], + relevance: 10 + } + const DERIVES_TYPECLASS = { + begin: ' derives ', end: /\n|\/[/*]/, + endsWithParent: true, + returnEnd: true, + keywords: 'derives', + contains: [PROBABLY_TYPE], + relevance: 10 + } + + const CLASS = { + className: 'class', + begin: `((${modifiers}|open|case|transparent) +)*(class|trait|enum|object|package object)`, end: templateDeclEnd, + keywords: withSoftKeywords('open transparent'), + excludeEnd: true, + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + TPARAMS, + CTX_PARAMS, + PARAMS, + EXTENDS_PARENT, + WITH_MIXIN, + DERIVES_TYPECLASS, + TITLE, + PROBABLY_TYPE + ] + } + + // package declaration with a content + const PACKAGE = { + className: 'package', + begin: /package (?=\w+ *[:{\n])/, end: /[:{\n]/, + excludeEnd: true, + keywords: alwaysKeywords, + contains: [ + TITLE + ] + } + + // Case in enum + const ENUM_CASE = { + begin: /case (?!.*=>)/, end: /\n/, + keywords: 'case', + excludeEnd: true, + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + PARAMS, + EXTENDS_PARENT, + WITH_MIXIN, + DERIVES_TYPECLASS, + TP_TITLE, + PROBABLY_TYPE + ] + } + + // Case in pattern matching + const MATCH_CASE = { + begin: /case/, end: /=>|\n/, + keywords: 'case', + excludeEnd: true, + contains: [ + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + { + begin: /[@_]/, + keywords: { + $pattern: /[@_]/, + keyword: '@ _' + } + }, + NUMBER, + STRING, + PROBABLY_TYPE + ] + } + + // inline someVar[andMaybeTypeParams] match + const INLINE_MATCH = { + begin: /inline [^\n:]+ match/, + keywords: 'inline match' + } + + return { + name: 'Scala3', + aliases: ['scala', 'dotty'], + keywords: alwaysKeywords, + contains: [ + NUMBER, + CHAR, + STRING, + USING_DIRECTIVE, + SCALADOC, + hljs.C_LINE_COMMENT_MODE, + hljs.C_BLOCK_COMMENT_MODE, + METHOD, + VAL, + TYPEDEF, + PACKAGE, + CLASS, + GIVEN, + EXTENSION, + ANNOTATION, + ENUM_CASE, + MATCH_CASE, + INLINE_MATCH, + END, + APPLY, + PROBABLY_TYPE + ] + } +} diff --git a/resources/js/tweetMachine-update.js b/resources/js/tweetMachine-update.js index a7604d2ba7..0addd1b951 100755 --- a/resources/js/tweetMachine-update.js +++ b/resources/js/tweetMachine-update.js @@ -133,11 +133,11 @@ }); // Usernames text = text.replace(/@[A-Za-z0-9_]+/g, function (u) { - return '' + u + ''; + return '' + u + ''; }); // Hashtags text = text.replace(/#[A-Za-z0-9_\-]+/g, function (u) { - return '' + u + ''; + return '' + u + ''; }); return text; }, @@ -160,7 +160,7 @@ // Set the user screen name var usernameLink = "" + "@" @@ -170,7 +170,7 @@ // Set the username: var userLink = "" + actualTweet.user.name @@ -178,7 +178,7 @@ tweetObj.find('.user').html("" + userLink); // Set the timestamp - var dateLink = "" + tweetMachine.relativeTime(actualTweet.created_at) @@ -411,4 +411,4 @@ } }); }; -})(jQuery); \ No newline at end of file +})(jQuery); diff --git a/resources/js/vendor/jquery.sticky.js b/resources/js/vendor/jquery.sticky.js deleted file mode 100644 index f50486f357..0000000000 --- a/resources/js/vendor/jquery.sticky.js +++ /dev/null @@ -1,287 +0,0 @@ -// Sticky Plugin v1.0.4 for jQuery -// ============= -// Author: Anthony Garand -// Improvements by German M. Bravo (Kronuz) and Ruud Kamphuis (ruudk) -// Improvements by Leonardo C. Daronco (daronco) -// Created: 02/14/2011 -// Date: 07/20/2015 -// Website: http://stickyjs.com/ -// Description: Makes an element on the page stick on the screen as you scroll -// It will only set the 'top' and 'position' of your element, you -// might need to adjust the width in some cases. - -(function (factory) { - if (typeof define === 'function' && define.amd) { - // AMD. Register as an anonymous module. - define(['jquery'], factory); - } else if (typeof module === 'object' && module.exports) { - // Node/CommonJS - module.exports = factory(require('jquery')); - } else { - // Browser globals - factory(jQuery); - } -}(function ($) { - var slice = Array.prototype.slice; // save ref to original slice() - var splice = Array.prototype.splice; // save ref to original slice() - - var defaults = { - topSpacing: 0, - bottomSpacing: 0, - className: 'is-sticky', - wrapperClassName: 'sticky-wrapper', - center: false, - getWidthFrom: '', - widthFromWrapper: true, // works only when .getWidthFrom is empty - responsiveWidth: false, - zIndex: 'auto' - }, - $window = $(window), - $document = $(document), - sticked = [], - windowHeight = $window.height(), - scroller = function() { - var scrollTop = $window.scrollTop(), - documentHeight = $document.height(), - dwh = documentHeight - windowHeight, - extra = (scrollTop > dwh) ? dwh - scrollTop : 0; - - for (var i = 0, l = sticked.length; i < l; i++) { - var s = sticked[i], - elementTop = s.stickyWrapper.offset().top, - etse = elementTop - s.topSpacing - extra; - - //update height in case of dynamic content - s.stickyWrapper.css('height', s.stickyElement.outerHeight()); - - if (scrollTop <= etse) { - if (s.currentTop !== null) { - s.stickyElement - .css({ - 'width': '', - 'position': '', - 'top': '', - 'z-index': '' - }); - s.stickyElement.parent().removeClass(s.className); - s.stickyElement.trigger('sticky-end', [s]); - s.currentTop = null; - } - } - else { - var newTop = documentHeight - s.stickyElement.outerHeight() - - s.topSpacing - s.bottomSpacing - scrollTop - extra; - if (newTop < 0) { - newTop = newTop + s.topSpacing; - } else { - newTop = s.topSpacing; - } - if (s.currentTop !== newTop) { - var newWidth; - if (s.getWidthFrom) { - newWidth = $(s.getWidthFrom).width() || null; - } else if (s.widthFromWrapper) { - newWidth = s.stickyWrapper.width(); - } - if (newWidth == null) { - newWidth = s.stickyElement.width(); - } - s.stickyElement - .css('width', newWidth) - .css('position', 'fixed') - .css('top', newTop) - .css('z-index', s.zIndex); - - s.stickyElement.parent().addClass(s.className); - - if (s.currentTop === null) { - s.stickyElement.trigger('sticky-start', [s]); - } else { - // sticky is started but it have to be repositioned - s.stickyElement.trigger('sticky-update', [s]); - } - - if (s.currentTop === s.topSpacing && s.currentTop > newTop || s.currentTop === null && newTop < s.topSpacing) { - // just reached bottom || just started to stick but bottom is already reached - s.stickyElement.trigger('sticky-bottom-reached', [s]); - } else if(s.currentTop !== null && newTop === s.topSpacing && s.currentTop < newTop) { - // sticky is started && sticked at topSpacing && overflowing from top just finished - s.stickyElement.trigger('sticky-bottom-unreached', [s]); - } - - s.currentTop = newTop; - } - - // Check if sticky has reached end of container and stop sticking - var stickyWrapperContainer = s.stickyWrapper.parent(); - var unstick = (s.stickyElement.offset().top + s.stickyElement.outerHeight() >= stickyWrapperContainer.offset().top + stickyWrapperContainer.outerHeight()) && (s.stickyElement.offset().top <= s.topSpacing); - - if( unstick ) { - s.stickyElement - .css('position', 'absolute') - .css('top', '') - .css('bottom', 0) - .css('z-index', ''); - } else { - s.stickyElement - .css('position', 'fixed') - .css('top', newTop) - .css('bottom', '') - .css('z-index', s.zIndex); - } - } - } - }, - resizer = function() { - windowHeight = $window.height(); - - for (var i = 0, l = sticked.length; i < l; i++) { - var s = sticked[i]; - var newWidth = null; - if (s.getWidthFrom) { - if (s.responsiveWidth) { - newWidth = $(s.getWidthFrom).width(); - } - } else if(s.widthFromWrapper) { - newWidth = s.stickyWrapper.width(); - } - if (newWidth != null) { - s.stickyElement.css('width', newWidth); - } - } - }, - methods = { - init: function(options) { - return this.each(function() { - var o = $.extend({}, defaults, options); - var stickyElement = $(this); - - var stickyId = stickyElement.attr('id'); - var wrapperId = stickyId ? stickyId + '-' + defaults.wrapperClassName : defaults.wrapperClassName; - var wrapper = $('
            ') - .attr('id', wrapperId) - .addClass(o.wrapperClassName); - - stickyElement.wrapAll(function() { - if ($(this).parent("#" + wrapperId).length == 0) { - return wrapper; - } -}); - - var stickyWrapper = stickyElement.parent(); - - if (o.center) { - stickyWrapper.css({width:stickyElement.outerWidth(),marginLeft:"auto",marginRight:"auto"}); - } - - if (stickyElement.css("float") === "right") { - stickyElement.css({"float":"none"}).parent().css({"float":"right"}); - } - - o.stickyElement = stickyElement; - o.stickyWrapper = stickyWrapper; - o.currentTop = null; - - sticked.push(o); - - methods.setWrapperHeight(this); - methods.setupChangeListeners(this); - }); - }, - - setWrapperHeight: function(stickyElement) { - var element = $(stickyElement); - var stickyWrapper = element.parent(); - if (stickyWrapper) { - stickyWrapper.css('height', element.outerHeight()); - } - }, - - setupChangeListeners: function(stickyElement) { - if (window.MutationObserver) { - var mutationObserver = new window.MutationObserver(function(mutations) { - if (mutations[0].addedNodes.length || mutations[0].removedNodes.length) { - methods.setWrapperHeight(stickyElement); - } - }); - mutationObserver.observe(stickyElement, {subtree: true, childList: true}); - } else { - if (window.addEventListener) { - stickyElement.addEventListener('DOMNodeInserted', function() { - methods.setWrapperHeight(stickyElement); - }, false); - stickyElement.addEventListener('DOMNodeRemoved', function() { - methods.setWrapperHeight(stickyElement); - }, false); - } else if (window.attachEvent) { - stickyElement.attachEvent('onDOMNodeInserted', function() { - methods.setWrapperHeight(stickyElement); - }); - stickyElement.attachEvent('onDOMNodeRemoved', function() { - methods.setWrapperHeight(stickyElement); - }); - } - } - }, - update: scroller, - unstick: function(options) { - return this.each(function() { - var that = this; - var unstickyElement = $(that); - - var removeIdx = -1; - var i = sticked.length; - while (i-- > 0) { - if (sticked[i].stickyElement.get(0) === that) { - splice.call(sticked,i,1); - removeIdx = i; - } - } - if(removeIdx !== -1) { - unstickyElement.unwrap(); - unstickyElement - .css({ - 'width': '', - 'position': '', - 'top': '', - 'float': '', - 'z-index': '' - }) - ; - } - }); - } - }; - - // should be more efficient than using $window.scroll(scroller) and $window.resize(resizer): - if (window.addEventListener) { - window.addEventListener('scroll', scroller, false); - window.addEventListener('resize', resizer, false); - } else if (window.attachEvent) { - window.attachEvent('onscroll', scroller); - window.attachEvent('onresize', resizer); - } - - $.fn.sticky = function(method) { - if (methods[method]) { - return methods[method].apply(this, slice.call(arguments, 1)); - } else if (typeof method === 'object' || !method ) { - return methods.init.apply( this, arguments ); - } else { - $.error('Method ' + method + ' does not exist on jQuery.sticky'); - } - }; - - $.fn.unstick = function(method) { - if (methods[method]) { - return methods[method].apply(this, slice.call(arguments, 1)); - } else if (typeof method === 'object' || !method ) { - return methods.unstick.apply( this, arguments ); - } else { - $.error('Method ' + method + ' does not exist on jQuery.sticky'); - } - }; - $(function() { - setTimeout(scroller, 0); - }); -})); diff --git a/scala3/contribute-to-docs.md b/scala3/contribute-to-docs.md new file mode 100644 index 0000000000..3196600581 --- /dev/null +++ b/scala3/contribute-to-docs.md @@ -0,0 +1,63 @@ +--- +layout: singlepage-overview +overview-name: "Scala 3 Documentation" +title: Contributing to the Docs +languages: ["ja", "ru"] +--- +## Overview +There are several ongoing efforts to produce high quality documentation for +Scala 3. In particular there are the following documents: + +- Scala 3 book +- Macros tutorial +- Migration guide +- Scala 3 language reference + +We welcome contributions from the community to every aspect of the documentation. + + +### How can I contribute? +In general, there are many ways you can help us: + +- **Confused about something in any of the docs?** Open an issue. +- **Found something not up-to-date?** Open an issue or create a PR. +- **Typos and other small text enhancements?** Create a PR. +- **Want to add something new or make larger changes?** Great! Please open an issue and let us discuss this. + +Typically, each of the different documentation projects contain links (and so does this document, in the table-of-contents pane - so far only visible in the desktop view) to edit and improve them. Additionally, below we provide you with the necessary information to get started. + +## Scala 3 Book +The [Scala 3 Book][scala3-book] is being written by Alvin Alexander and provides an overview over all the important features of Scala 3. It targets readers, which are new to Scala. + +- [Sources](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-book) +- [Issues](https://github.com/scala/docs.scala-lang/issues) + +## Macros Tutorial +The [Macros Tutorial](/scala3/guides/macros) is being written by Nicolas Stucki and contains detailed information about macros in Scala 3 and best-practices. + +- [Sources](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-macros) +- [Issues](https://github.com/scala/docs.scala-lang/issues) + +## Migration Guide +The [Scala 3 Migration Guide](/scala3/guides/migration/compatibility-intro.html) +contains a comprehensive overview over compatibility between Scala 2 and Scala 3, +a tour presenting the migration tools, and detailed migration guides. + +- [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration) +- [Issues](https://github.com/scala/docs.scala-lang/issues) + +## Scala 3 Contributing Guide +The [Scala 3 Contributing Guide](/scala3/guides/contribution/contribution-intro.html) +contains a comprehensive overview over contribution to and internals of the Scala 3 compiler and libraries + +- [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution) +- [Issues](https://github.com/scala/docs.scala-lang/issues) + +## Scala 3 Language Reference +The [Scala 3 reference]({{ site.scala3ref }}) contains a formal presentation and detailed technical information about the various features of the language. + +- [Sources](https://github.com/scala/scala3/tree/main/docs/_docs) +- [Issues](https://github.com/scala/scala3/issues) + + +[scala3-book]: {% link _overviews/scala3-book/introduction.md %} diff --git a/scala3/guides/tasty-overview.md b/scala3/guides/tasty-overview.md new file mode 100644 index 0000000000..245c822ee5 --- /dev/null +++ b/scala3/guides/tasty-overview.md @@ -0,0 +1,162 @@ +--- +layout: singlepage-overview +title: An Overview of TASTy +partof: tasty-overview +languages: ["uk"] +scala3: true +versionSpecific: true +--- +If you create a Scala 3 source code file named _Hello.scala_: + +```scala +@main def hello = println("Hello, world") +``` + +and then compile that file with `scalac`: + +```bash +$ scalac Hello.scala +``` + +you’ll notice that amongst other resulting files, `scalac` creates files with the _.tasty_ extension: + +```bash +$ ls -1 +Hello$package$.class +Hello$package.class +Hello$package.tasty +Hello.scala +hello.class +hello.tasty +``` + +This leads to the natural question, “What is tasty?” + + + +## What is TASTy? + +TASTy is an acronym that comes from the term, _Typed Abstract Syntax Trees_. +It’s a high-level interchange format for Scala 3, and in this document we’ll refer to it as _Tasty_. + +A first important thing to know is that Tasty files are generated by the `scalac` compiler, and contain _all_ the information about your source code, including the syntactic structure of your program, and _complete_ information about types, positions, and even documentation. Tasty files contain much more information than _.class_ files, which are generated to run on the JVM. (More on this shortly.) + +In Scala 3, the compilation process looks like this: + +```text + +-------------+ +-------------+ +-------------+ +$ scalac | Hello.scala | -> | Hello.tasty | -> | Hello.class | + +-------------+ +-------------+ +-------------+ + ^ ^ ^ + | | | + Your source TASTy file Class file + code for scalac for the JVM + (contains (incomplete + complete information) + information) +``` + +You can view the contents of a _.tasty_ file in a human-readable form by running the compiler on it with the `-print-tasty` flag. +You can also view the contents decompiled in a form similar to Scala source code using the `-decompile` flag. +```bash +$ scalac -print-tasty hello.tasty +$ scalac -decompile hello.tasty +``` + +### The issue with _.class_ files + +Because of issues such as [type erasure][erasure], _.class_ files are actually an incomplete representation of your code. +A simple way to demonstrate this is with a `List` example. + +_Type erasure_ means that when you write Scala code like this that’s supposed to run on the JVM: + +```scala +val xs: List[Int] = List(1, 2, 3) +``` + +that code is compiled to a _.class_ file that needs to be compatible with the JVM. As a result of that compatibility requirement, the code inside that class file --- which you can see with a `javap` command --- ends up looking like this: + +```java +public scala.collection.immutable.List xs(); +``` + +That `javap` command output shows a Java representation of what’s contained in the class file. Notice in this output that `xs` _is not_ defined as a `List[Int]` anymore; it’s essentially represented as a `List[java.lang.Object]`. For your Scala code to work with the JVM, the `Int` type has been erased. + +Later, when you access an element of your `List[Int]` in your Scala code, like this: + +```scala +val x = xs(0) +``` + +the resulting class file will have a casting operation for this line of code, which you can think of being like this: + +``` +int x = (Int) xs.get(0) // Java-ish +val x = xs.get(0).asInstanceOf[Int] // more Scala-like +``` + +Again, this is done for compatibility, so your Scala code can run on the JVM. However, the information that we already had a list of integers is lost in the class files. +This poses problems when trying to compile a Scala program against an already compiled library. For this, we need more information than usually available in class files. + +And this discussion only covers the topic of type erasure. There are similar issues for every other Scala construct that the JVM isn’t aware of, including constructs like unions, intersections, traits with parameters, and many more Scala 3 features. + +### TASTy to the Rescue +So, instead of having no information about the original types in _.class_ files, or only the public API (as with the Scala 2.13 “Pickle” format), the TASTy format stores the complete abstract syntax tree (AST), after type checking. Storing the whole AST has a lot of advantages: it enables separate compilation, recompilation for a different JVM version, static analysis of programs, and many more. + +### Key points + +So that’s the first takeaway from this section: The types you specify in your Scala code aren’t represented completely accurately in _.class_ files. + +A second key point is to understand that there are differences between the information that’s available at _compile time_ and _run time_: + +- At **compile time**, as `scalac` reads and analyzes your code, it knows that `xs` is a `List[Int]` +- When the compiler writes your code to a class file, it writes that `xs` is a `List[Object]`, and it adds casting information everywhere else `xs` is accessed +- Then at **run time** --- with your code running inside the JVM --- the JVM doesn’t know that your list is a `List[Int]` + +With Scala 3 and Tasty, here’s another important note about compile time: + +- When you write Scala 3 code that uses other Scala 3 libraries, `scalac` doesn’t have to read their _.class_ files anymore; it can read their _.tasty_ files, which, as mentioned, are an _exact_ representation of your code. This is important to enable separate compilation and compatibility between Scala 2.13 and Scala 3. + + + +## Tasty benefits + +As you can imagine, having a complete representation of your code has [many benefits][benefits]: + +- The compiler uses it to support separate compilation. +- The Scala _Language Server Protocol_-based language server uses it to support hyperlinking, command completion, documentation, and also for global operations such as find-references and renaming. +- Tasty makes an excellent foundation for a new generation of [reflection-based macros][macros]. +- Optimizers and analyzers can use it for deep code analysis and advanced code generation. + +In a related note, Scala 2.13.6 has a TASTy reader, and the Scala 3 compiler can also read the 2.13 “Pickle” format. The [Classpath Compatibility Page][compatibility-ref] in the Scala 3 Migration Guide explains the benefits of this cross-compiling capability. + + + +## More information + +In summary, Tasty is a high-level interchange format for Scala 3, and _.tasty_ files contain a complete representation of your source code, leading to the benefits outlined in the previous section. + +For more details, see these resources: + +- In [this video](https://www.youtube.com/watch?v=YQmVrUdx8TU), Jamie Thompson of the Scala Center provides a thorough discussion of how Tasty works, and its benefits +- [Binary Compatibility for library authors][binary] discusses binary compatibility, source compatibility, and the JVM execution model +- [Forward Compatibility for the Scala 3 Transition](https://www.scala-lang.org/blog/2020/11/19/scala-3-forward-compat.html) demonstrates techniques for using Scala 2.13 and Scala 3 in the same project + +These articles provide more information about Scala 3 macros: + +- [Scala Macro Libraries](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html) +- [Macros: The Plan for Scala 3](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html) +- [The reference documentation on Quotes Reflect][quotes-reflect] +- [The reference documentation on macros](macros) + + +TASTyViz is a tool to inspect TASTy files visually. +At the time of writing, it is still in the early stages of developement, therefore you can expect missing functionality and less-than-ideal user experience, but it could still prove useful when debugging. +You can check it out [here](https://github.com/shardulc/tastyviz). + +[benefits]: https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html +[erasure]: https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure +[binary]: {% link _overviews/tutorials/binary-compatibility-for-library-authors.md %} +[compatibility-ref]: {% link _overviews/scala3-migration/compatibility-classpath.md %} +[quotes-reflect]: {{ site.scala3ref }}/metaprogramming/reflection.html +[macros]: {{ site.scala3ref }}/metaprogramming/macros.html diff --git a/scala3/new-in-scala3.md b/scala3/new-in-scala3.md new file mode 100644 index 0000000000..cc3c0add30 --- /dev/null +++ b/scala3/new-in-scala3.md @@ -0,0 +1,139 @@ +--- +layout: singlepage-overview +title: New in Scala 3 +languages: ["ja","zh-cn","uk","ru"] +--- +The exciting new version of Scala 3 brings many improvements and +new features. Here we provide you with a quick overview of the most important +changes. If you want to dig deeper, there are a few references at your disposal: + +- The [Scala 3 Book]({% link _overviews/scala3-book/introduction.md %}) targets developers new to the Scala language. +- The [Syntax Summary][syntax-summary] provides you with a formal description of the new syntax. +- The [Language Reference][reference] gives a detailed description of the changes from Scala 2 to Scala 3. +- The [Migration Guide][migration] provides you with all the information necessary to move from Scala 2 to Scala 3. +- The [Scala 3 Contributing Guide][contribution] dives deeper into the compiler, including a guide to fix issues. + +## What's new in Scala 3 +Scala 3 is a complete overhaul of the Scala language. At its core, many aspects +of the type-system have been changed to be more principled. While this also +brings exciting new features along (like union types), first and foremost, it +means that the type-system gets (even) less in your way and for instance +[type-inference][type-inference] and overload resolution are much improved. + +### New & Shiny: The Syntax +Besides many (minor) cleanups, the Scala 3 syntax offers the following improvements: + +- A new "quiet" syntax for control structures like `if`, `while`, and `for` ([new control syntax][syntax-control]) +- The `new` keyword is optional (_aka_ [creator applications][creator]) +- [Optional braces][syntax-indentation] that supports a distraction-free, indentation sensitive style of programming +- Change of [type-level wildcards][syntax-wildcard] from `_` to `?`. +- Implicits (and their syntax) have been [heavily revised][implicits]. + +### Opinionated: Contextual Abstractions +One underlying core concept of Scala was (and still is to some degree) to +provide users with a small set of powerful features that can be combined to +great (and sometimes even unforeseen) expressivity. For example, the feature of _implicits_ +has been used to model contextual abstraction, to express type-level +computation, model type-classes, perform implicit coercions, encode +extension methods, and many more. +Learning from these use cases, Scala 3 takes a slightly different approach +and focuses on **intent** rather than **mechanism**. +Instead of offering one very powerful feature, Scala 3 offers multiple +tailored language features, allowing programmers to directly express their intent: + +- **Abstracting over contextual information**. [Using clauses][contextual-using] allow programmers to abstract over information that is available in the calling context and should be passed implicitly. As an improvement over Scala 2 implicits, using clauses can be specified by type, freeing function signatures from term variable names that are never explicitly referred to. + +- **Providing Type-class instances**. [Given instances][contextual-givens] allow programmers to define the _canonical value_ of a certain type. This makes programming with type-classes more straightforward without leaking implementation details. + +- **Retroactively extending classes**. In Scala 2, extension methods had to be encoded using implicit conversions or implicit classes. In contrast, in Scala 3 [extension methods][contextual-extension] are now directly built into the language, leading to better error messages and improved type inference. + +- **Viewing one type as another**. Implicit conversions have been [redesigned][contextual-conversions] from the ground up as instances of a type-class `Conversion`. + +- **Higher-order contextual abstractions**. The _all-new_ feature of [context functions][contextual-functions] makes contextual abstractions a first-class citizen. They are an important tool for library authors and allow to express concise domain specific languages. + +- **Actionable feedback from the compiler**. In case an implicit parameter cannot be resolved by the compiler, it now provides [import suggestions](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html) that may fix the problem. + +### Say What You Mean: Type System Improvements +Besides greatly improved type inference, the Scala 3 type system also offers many new features, giving you powerful tools to statically express invariants in the types: + +- **Enumerations**. [Enums][enums] have been redesigned to blend well with case classes and form the new standard to express [algebraic data types][enums-adts]. + +- **Opaque Types**. Hide implementation details behind [opaque type aliases][types-opaque] without paying for it in performance! Opaque types supersede value classes and allow you to set up an abstraction barrier without causing additional boxing overhead. + +- **Intersection and union types**. Basing the type system on new foundations led to the introduction of new type system features: instances of [intersection types][types-intersection], like `A & B`, are instances of _both_ `A` and of `B`. Instances of [union types][types-union], like `A | B`, are instances of _either_ `A` or `B`. Both constructs allow programmers to flexibly express type constraints outside the inheritance hierarchy. + +- **Dependent function types**. Scala 2 already allowed return types to depend on (value) arguments. In Scala 3 it is now possible to abstract over this pattern and express [dependent function types][types-dependent]. In the type `type F = (e: Entry) => e.Key` the result type _depends_ on the argument! + +- **Polymorphic function types**. Like with dependent function types, Scala 2 supported methods that allow type parameters, but did not allow programmers to abstract over those methods. In Scala 3, [polymorphic function types][types-polymorphic] like `[A] => List[A] => List[A]` can abstract over functions that take _type arguments_ in addition to their value arguments. + +- **Type lambdas**. What needed to be expressed using a [compiler plugin](https://github.com/typelevel/kind-projector) in Scala 2 is now a first-class feature in Scala 3: Type lambdas are type level functions that can be passed as (higher-kinded) type arguments without requiring an auxiliary type definition. + +- **Match types**. Instead of encoding type-level computation using implicit resolution, Scala 3 offers direct support for [matching on types][types-match]. Integrating type-level computation into the type checker enables improved error messages and removes the need for complicated encodings. + + +### Re-envisioned: Object-Oriented Programming +Scala has always been at the frontier between functional programming and object-oriented programming -- +and Scala 3 pushes boundaries in both directions! The above-mentioned type system changes and the redesign of contextual abstractions make _functional programming_ easier than before. +At the same time, the following novel features enable well-structured _object-oriented designs_ and support best practices. + +- **Pass it on**. Traits move closer to classes and now can also take [parameters][oo-trait-parameters], making them even more powerful as a tool for modular software decomposition. +- **Plan for extension**. Extending classes that are not intended for extension is a long-standing problem in object-oriented design. To address this issue, [open classes][oo-open] require library designers to _explicitly_ mark classes as open. +- **Hide implementation details**. Utility traits that implement behavior sometimes should not be part of inferred types. In Scala 3, those traits can be marked as [transparent][oo-transparent] hiding the inheritance from the user (in inferred types). +- **Composition over inheritance**. This phrase is often cited, but tedious to implement. Not so with Scala 3's [export clauses][oo-export]: symmetric to imports, export clauses allow the user to define aliases for selected members of an object. +- **No more NPEs (experimental)**. Scala 3 is safer than ever: [explicit null][oo-explicit-null] moves `null` out of the type hierarchy, helping you to catch errors statically; additional checks for [safe initialization][oo-safe-init] detect access to uninitialized objects. + + +### Batteries Included: Metaprogramming +While macros in Scala 2 were an experimental feature only, Scala 3 comes with a powerful arsenal of tools for metaprogramming. +The [macro tutorial]({% link _overviews/scala3-macros/tutorial/index.md %}) contains detailed information on the different facilities. In particular, Scala 3 offers the following features for metaprogramming: + +- **Inline**. As the basic starting point, the [inline feature][meta-inline] allows values and methods to be reduced at compile time. This simple feature already covers many use-cases and at the same time provides the entry point for more advanced features. +- **Compile-time operations**. The package [`scala.compiletime`][meta-compiletime] contains additional functionality that can be used to implement inline methods. +- **Quoted code blocks**. Scala 3 adds the new feature of [quasi-quotation][meta-quotes] for code, providing a convenient high-level interface to construct and analyse code. Constructing code for adding one and one is as easy as `'{ 1 + 1 }`. +- **Reflection API**. For more advanced use cases [quotes.reflect][meta-reflection] provides more detailed control to inspect and generate program trees. + +If you want to learn more about metaprogramming in Scala 3, we invite you to take our [tutorial][meta-tutorial]. + + +[enums]: {{ site.scala3ref }}/enums/enums.html +[enums-adts]: {{ site.scala3ref }}/enums/adts.html + +[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html +[types-union]: {{ site.scala3ref }}/new-types/union-types.html +[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html +[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html +[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html +[types-match]: {{ site.scala3ref }}/new-types/match-types.html +[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html + +[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html +[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html +[reference]: {{ site.scala3ref }}/overview.html +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %} +[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %} + +[implicits]: {{ site.scala3ref }}/contextual +[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html +[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html +[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html +[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html +[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html + +[syntax-summary]: {{ site.scala3ref }}/syntax.html +[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html +[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html +[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html + +[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %} +[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %} +[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %} +[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %} +[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %} + +[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html +[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html +[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html +[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html +[oo-export]: {{ site.scala3ref }}/other-new-features/export.html diff --git a/scala3/reference/README.md b/scala3/reference/README.md new file mode 100644 index 0000000000..418bdbe3e1 --- /dev/null +++ b/scala3/reference/README.md @@ -0,0 +1,6 @@ +The content of the pages https://docs.scala-lang.org/scala3/reference is +generated from the [Scala 3 compiler repository](https://github.com/scala/scala3). + +Please go here to contribute to the Scala 3 reference documentation: + +https://github.com/scala/scala3/tree/main/docs/_docs diff --git a/scala3/scaladoc.md b/scala3/scaladoc.md new file mode 100644 index 0000000000..5a735173e3 --- /dev/null +++ b/scala3/scaladoc.md @@ -0,0 +1,87 @@ +--- +layout: singlepage-overview +title: New features for Scaladoc +partof: scala3-scaladoc +languages: ["uk","ru"] +--- + +The new Scala version 3 comes with a completely new implementation of the documentation generator _Scaladoc_, rewritten from scratch. +In this article you can find highlights of new features that are or will be introduced to Scaladoc. +For general reference, visit [Scaladoc manual]({% link _overviews/scala3-scaladoc/index.md %}). + +## New features + +### Markdown syntax + +The biggest change introduced in the new version of Scaladoc is the change of the default language for docstrings. So far Scaladoc only supported Wikidoc syntax. +The new Scaladoc can still parse legacy `Wikidoc` syntax, however Markdown has been chosen as a primary language for formatting comments. +To switch back to `Wikidoc` one can pass a global flag before running the `doc` task or one can define it for specific comments via the `@syntax wiki` directive. + +For more information on how to use the full power of docstings, check out [Scaladoc docstrings][scaladoc-docstrings] + + +### Static site + +Scaladoc also provides an easy way for creating **static sites** for both documentation and blog posts in the similar way as Jekyll does. +Thanks to this feature, you can store your documentation along-side with the generated Scaladoc API in a very convenient way. + +For more information on how to configure the generation of static sites check out [Static documentation][static-documentation] chapter + +![](../../resources/images/scala3/scaladoc/static-site.png) + +### Blog posts + +Blog posts are a specific type of static sites. In the Scaladoc manual you can find additional information about how to work with [blog posts][built-in-blog]. + +![](../../resources/images/scala3/scaladoc/blog-post.png) + +### Social links + +Furthermore, Scaladoc provides an easy way to configure your [social media links][social-links] e.g. Twitter or Discord. + +![](../../resources/images/scala3/scaladoc/social-links.png){: style="width: 180px"} + +## Experimental features + +The following features are currently (May 2021) not stable to be released with scaladoc, however we are happy to hear your feedback. Each feature has its own thread at scala-lang contributors site, where you can share your opinions. + +### Snippet compiling + +One of the experimental features of Scaladoc is a compiler for snippets. This tool will allow you to compile snippets that you attach to your docstring +to check that they actually behave as intended, e.g., to properly compile. This feature is very similar to the `tut` or `mdoc` tools, +but will be shipped with Scaladoc out of the box for easy setup and integration into your project. Making snippets interactive---e.g., letting users edit and compile them in the browser---is under consideration, though this feature is not in scope at this time. + +Showcase: +* Hiding code ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/hiding-code.gif) +* Assert compilation errors ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/assert-compilation-errors.gif) +* Snippet includes ![]({{ site.baseurl }}/resources/images/scala3/scaladoc/snippet-includes.png) + +For more information see [Guides](/scala3/guides/scaladoc/snippet-compiler.html), or follow this [Scala Contributors thread](https://contributors.scala-lang.org/t/snippet-validation-in-scaladoc-for-scala-3/4976) + +### Type-based search + +Searching for functions by their symbolic names can be time-consuming. +That is why the new scaladoc allows you to search for methods and fields by their types. + + +So, for a declaration: +``` +extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ... +``` +Instead of searching for `span` we can also search for `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`. + +To use this feature simply type the signature of the function you are looking for in the scaladoc searchbar. This is how it works: + +![](../../resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif) + +This feature is provided by the [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which works for Scala 3 and Kotlin. To be up-to-date with the development of this feature, follow the [Inkuire repository](https://github.com/VirtusLab/Inkuire). + +For more information see [Guides](/scala3/guides/scaladoc/search-engine.html) + +Note that this feature is still in development, so it can be subject to considerable change. +If you encounter a bug or have an idea for improvement, don't hesitate to create an issue on [Inkuire](https://github.com/VirtusLab/Inkuire/issues/new) or [scala3](https://github.com/scala/scala3/issues/new). + +[scaladoc-docstrings]: {% link _overviews/scala3-scaladoc/docstrings.md %} +[static-documentation]: {% link _overviews/scala3-scaladoc/static-site.md %} +[built-in-blog]: {% link _overviews/scala3-scaladoc/blog.md %} +[social-links]: {% link _overviews/scala3-scaladoc/settings.md %}#-social-links diff --git a/scala3/talks.md b/scala3/talks.md new file mode 100644 index 0000000000..0cdba8b2d0 --- /dev/null +++ b/scala3/talks.md @@ -0,0 +1,72 @@ +--- +layout: singlepage-overview +title: Talks +scala3: true +partof: scala3-talks +languages: ["uk","ru"] +versionSpecific: true +--- + +Let’s Talk About Scala 3 Series +------------------------------- + +[Let’s Talk About Scala 3](https://www.youtube.com/playlist?list=PLTx-VKTe8yLxYQfX_eGHCxaTuWvvG28Ml) is a series +of short (around 15 min) talks about Scala 3. It covers a variety of themes like how to get started, how to take +advantage of the new language features, or how to migrate from Scala 2. + +Talks on Scala 3 +---------------- +- (ScalaDays 2019, Lausanne) [A Tour of Scala 3](https://www.youtube.com/watch?v=_Rnrx2lo9cw) by [Martin Odersky](http://x.com/odersky) + +- (ScalaDays 2016, Berlin) [Scala's Road Ahead](https://www.youtube.com/watch?v=GHzWqJKFCk4) by [Martin Odersky](http://x.com/odersky) [\[slides\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016) + +- (JVMLS 2015) [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc) by [Martin Odersky](http://x.com/odersky) [\[slides\]](http://www.slideshare.net/Odersky/compilers-are-databases) + +- (Scala World 2015) [Dotty: Exploring the future of Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) by [Dmitry Petrashko](http://x.com/darkdimius) [\[slides\]](https://d-d.me/scalaworld2015/#/). + Dmitry covers many of the new features that Dotty brings on the table such as Intersection and Union types, improved lazy val initialization and more. + Dmitry also covers dotty internals and in particular the high-level of contextual abstractions of Dotty. You will get to + become familiar with many core concepts such as `Denotations`, their evolution through (compilation) time, their + transformations and more. + +Deep Dive with Scala 3 +---------------------- +- (ScalaDays 2019, Lausanne) [Metaprogramming in Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) by [Nicolas Stucki](https://github.com/nicolasstucki). + +- (ScalaDays 2019, Lausanne) [Future-proofing Scala: the TASTY intermediate representation](https://www.youtube.com/watch?v=zQFjC3zLYwo) by [Guillaume Martres](http://guillaume.martres.me/). + +- (Mar 21, 2017) [Dotty Internals 1: Trees & Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8) by [Dmitry Petrashko](http://x.com/darkdimius) [\[meeting notes\]](https://dotty.epfl.ch/docs/internals/dotty-internals-1-notes.html). + This is a recorded meeting between EPFL and Waterloo, where we introduce first notions inside Dotty: Trees and Symbols. + +- (Mar 21, 2017) [Dotty Internals 2: Types](https://www.youtube.com/watch?v=3gmLIYlGbKc) by [Martin Odersky](http://x.com/odersky) and [Dmitry Petrashko](http://x.com/darkdimius). + This is a recorded meeting between EPFL and Waterloo, where we introduce how types are represented inside Dotty. + +- (Jun 15, 2017) [Dotty Internals 3: Denotations](https://youtu.be/9iPA7zMRGKY) by [Martin Odersky](http://x.com/odersky) and [Dmitry Petrashko](http://x.com/darkdimius). + This is a recorded meeting between EPFL and Waterloo, where we introduce denotations in Dotty. + +- (JVM Language Summit) [How do we make the Dotty compiler fast](https://www.youtube.com/watch?v=9xYoSwnSPz0) by [Dmitry Petrashko](http://x.com/darkdimius). + [Dmitry Petrashko](http://x.com/darkdimius) gives a high-level introduction on what was done to make Dotty . + + +- (Typelevel Summit Oslo, May 2016) [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) by + Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/). + Guillaume focused on some practical improvements to the type system that Dotty makes, like the new type parameter + inference algorithm that is able to reason about the type safety of more situations than scalac. + +- (flatMap(Oslo) 2016) [AutoSpecialization in Dotty](https://vimeo.com/165928176) by [Dmitry Petrashko](http://x.com/darkdimius) [\[slides\]](https://d-d.me/talks/flatmap2016/#/). + The Dotty Linker analyses your program and its dependencies to + apply a new specialization scheme. It builds on our experience from Specialization, Miniboxing and the Valhalla Project, + and drastically reduces the size of the emitted bytecode. And, best of all, it's always enabled, happens behind the + scenes without annotations, and results in speedups in excess of 20x. Additionally, it "just works" on Scala collections. + +- (ScalaSphere 2016) [Hacking on Dotty: A live demo](https://www.youtube.com/watch?v=0OOYGeZLHs4) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-live-demo/). + Guillaume hacks on Dotty: a live demo during which he + creates a simple compiler phase to trace method calls at run-time. + +- (Scala By the Bay 2016) [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) by Guillaume + Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-tutorial/#/). Guillaume provides a high-level view of the + compilation-pipeline of Dotty. + +- (ScalaDays 2015, Amsterdam) [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) by Dmitry Petrashko [\[slides\]](https://d-d.me/scaladays2015/#/). + Dmitry introduces the call-graph analysis algorithm + that Dotty implements and the performance benefits we can get in terms of number of methods, bytecode size, JVM code size + and the number of objects allocated in the end. diff --git a/scalacenter-courses.md b/scalacenter-courses.md new file mode 100644 index 0000000000..b242e6f5fe --- /dev/null +++ b/scalacenter-courses.md @@ -0,0 +1,169 @@ +--- +title: Online Courses (MOOCs) from The Scala Center +layout: singlepage-overview +languages: [ru] +testimonials: + - /resources/images/scalacenter-courses/testimonial000.jpg + - /resources/images/scalacenter-courses/testimonial001.jpg + - /resources/images/scalacenter-courses/testimonial002.jpg + - /resources/images/scalacenter-courses/testimonial003.jpg + - /resources/images/scalacenter-courses/testimonial004.jpg + - /resources/images/scalacenter-courses/testimonial005.jpg + - /resources/images/scalacenter-courses/testimonial006.jpg + - /resources/images/scalacenter-courses/testimonial007.jpg + - /resources/images/scalacenter-courses/testimonial008.jpg + - /resources/images/scalacenter-courses/testimonial009.jpg + - /resources/images/scalacenter-courses/testimonial010.jpg + - /resources/images/scalacenter-courses/testimonial011.jpg + - /resources/images/scalacenter-courses/testimonial012.jpg + - /resources/images/scalacenter-courses/testimonial013.jpg + - /resources/images/scalacenter-courses/testimonial014.jpg +--- + +The [Scala Center] produces online courses (a.k.a. MOOCs) of various levels, from beginner +to advanced. + +**If you are a programmer and want to learn Scala**, there are two recommended +approaches. The fast path consists of taking the course [Effective Programming +in Scala](#effective-programming-in-scala). +Otherwise, you can take the full [Scala Specialization], which is made of +four courses (covering advanced topics such as big data analysis and +parallel programming) and a capstone project. + +You can learn more about the courses in the following video: + +
            + +
            + +## Scala Learning Path + +The diagram below summarizes the possible learning paths with our courses: + +![](/resources/images/learning-path.png) + +The “foundational” courses target programmers with no prior experience in Scala, whereas the “deepening” +courses aim at strengthening Scala programmers skills in a specific domain (such as parallel programming). + +We recommend starting with either Effective Programming in Scala, or Functional Programming Principles in +Scala followed by Functional Program Design. Then, you can complement your Scala skills by taking any +of the courses Programming Reactive Systems, Parallel Programming, or Big Data Analysis with Scala and Spark. +In case you take the Scala Specialization, you will end with the Scala Capstone Project. + +## Learning Platforms + +Currently, all our MOOCs are available on the platform [Coursera](https://coursera.org), +and some of them are available on [edX](https://edx.org) or the [Extension School](https://extensionschool.ch). +This section explains the differences between these learning platforms. + +On all the platforms the full material is always available online. It includes +video lectures, text articles, quizzes, and auto-graded homeworks. All the +platforms also provide discussion forums where you can exchange with the +other learners. + +The difference between the Extension School and the other platforms is that it +provides live meetings with instructors, and code reviews by Scala experts. + +On the other hand, on Coursera or edX it is possible to take +our courses for free (a.k.a. “audit” mode). Optionally, a subscription gives +you access to a certificate of completion that attests your accomplishments. + +Learn more about +[Coursera certificates](https://learners.coursera.help/hc/en-us/articles/209819053-Get-a-Course-Certificate), +[edX certificates](https://support.edx.org/hc/en-us/categories/115002269627-Certificates), +or [Extension School certificates](https://www.extensionschool.ch/faqs#certifying-coursework). +Note that your subscriptions also supports the work of the [Scala Center], +whose mission is to create high-quality educational material. + +If you prefer learning in autonomy, we recommend +you to choose the Coursera or edX platform, but if you are looking for more +support, we recommend you to choose the Extension School. Here is a table +below that compares the learning platforms: + +| | Coursera / edX (audit) | Coursera / edX (subscription) | Extension School | +|--------------------------------------------------|------------------------|-------------------------------|------------------| +| Video lectures, quizzes | Yes | Yes | Yes | +| Auto-graded homeworks | Yes | Yes | Yes | +| Discussion forums | Yes | Yes | Yes | +| Self-paced | Yes | Yes | Yes | +| Price | $0 | $50 to $100 per course | $420 per month | +| Certificate of completion | No | Yes | Yes | +| Supports the Scala Center | No | Yes | Yes | +| 30 min of live session with instructors per week | No | No | Yes | +| Code reviews by Scala experts | No | No | Yes | + +## Effective Programming in Scala + +This course is available on [Coursera](https://coursera.org/learn/effective-scala) +and the [Extension School](https://extensionschool.ch/learn/effective-programming-in-scala). +Please refer to [this section](#learning-platforms) to know the differences +between both learning platforms. + +[Effective Programming in Scala] teaches non-Scala programmers everything +they need to be ready to work in Scala. At the end of this hands-on course, +you will know how to achieve common programming tasks in Scala (e.g., +modeling business domains, implementing business logic, designing large +systems made of components, handling errors, manipulating data, running +concurrent tasks in parallel, testing your code). You can learn more about +this course in the following video: + +
            + +
            + +This course is also a good way to upgrade your Scala 2 knowledge to Scala 3. + +After taking this course, you might be interested in improving your +skills in specific areas by taking the courses [Parallel Programming], +[Big Data Analysis with Scala and Spark], or [Programming Reactive Systems]. + +## Scala Specialization + +The [Scala Specialization] provides a hands-on introduction to functional programming using Scala. You can access the courses +material and exercises by either signing up for the specialization or auditing the courses individually. The +specialization has the following courses. +* [Functional Programming Principles in Scala], +* [Functional Program Design in Scala], +* [Parallel programming], +* [Big Data Analysis with Scala and Spark], +* [Functional Programming in Scala Capstone]. + +These courses provide a deep understanding of the Scala language itself, +and they also dive into more specific topics such as parallel programming, +and Spark. + +## Programming Reactive Systems + +[Programming Reactive Systems] (also available on [edX](https://www.edx.org/course/scala-akka-reactive)) +teaches how to write responsive, scalable, and resilient systems with the +library Akka. + +## Scala 2 Courses + +The above courses all use Scala 3. If needed, you can find +the (legacy) Scala 2 version of our courses here: + +- [Functional Programming Principles in Scala (Scala 2 version)](https://www.coursera.org/learn/scala2-functional-programming) +- [Functional Program Design (Scala 2 version)](https://www.coursera.org/learn/scala2-functional-program-design) +- [Parallel Programming (Scala 2 version)](https://www.coursera.org/learn/scala2-parallel-programming) +- [Big Data Analysis with Scala and Spark (Scala 2 version)](https://www.coursera.org/learn/scala2-spark-big-data) +- [Programming Reactive Systems (Scala 2 version)](https://www.coursera.org/learn/scala2-akka-reactive) + +## Testimonials + +{% include carousel.html images=page.testimonials number=0 height="50" unit="%" duration="10" %} + +## Other Online Resources + +You can find other online resources contributed by the community on +[this page]({% link online-courses.md %}). + +[Scala Center]: https://scala.epfl.ch +[Scala Specialization]: https://www.coursera.org/specializations/scala +[Effective Programming in Scala]: https://www.coursera.org/learn/effective-scala +[Functional Programming Principles in Scala]: https://www.coursera.org/learn/scala-functional-programming +[Functional Program Design in Scala]: https://www.coursera.org/learn/scala-functional-program-design +[Parallel programming]: https://www.coursera.org/learn/scala-parallel-programming +[Big Data Analysis with Scala and Spark]: https://www.coursera.org/learn/scala-spark-big-data +[Functional Programming in Scala Capstone]: https://www.coursera.org/learn/scala-capstone +[Programming Reactive Systems]: https://www.coursera.org/learn/scala-akka-reactive diff --git a/scripts/ci.sh b/scripts/ci.sh deleted file mode 100755 index 6539e73af0..0000000000 --- a/scripts/ci.sh +++ /dev/null @@ -1,15 +0,0 @@ -#!/bin/bash - -. /usr/local/rvm/scripts/rvm - -set -eux - -bundle install -./scripts/run-tut.sh -rm -r tut-tmp -bundle exec jekyll build - -# Checking for docs.scala-lang/blob/master leads to a chicken and egg problem because of the edit links of new pages. -bundle exec htmlproofer ./_site/ --only-4xx --http-status-ignore "401,429" --empty-alt-ignore --allow-hash-href --url-ignore '/https://github.com/scala/docs.scala-lang/blob/master/.*/' - -exit 0 diff --git a/scripts/run-mdoc.sh b/scripts/run-mdoc.sh new file mode 100755 index 0000000000..fc478f83d5 --- /dev/null +++ b/scripts/run-mdoc.sh @@ -0,0 +1,17 @@ +#!/bin/bash +set -eux + +cs launch --scala-version 2.13.16 org.scalameta::mdoc:2.3.3 -- \ + --in . \ + --out /tmp/mdoc-out/ \ + --classpath \ + $(cs fetch --scala-version 2.13.16 -p \ + com.chuusai::shapeless:2.3.10 \ + org.scala-lang::toolkit:0.1.7 \ + org.scala-lang::toolkit-test:0.1.7 \ + ) \ + --scalac-options "-Xfatal-warnings -feature" \ + --no-link-hygiene \ + --include '**.md' + +exit 0 diff --git a/scripts/run-tut.sh b/scripts/run-tut.sh deleted file mode 100755 index 51a87057da..0000000000 --- a/scripts/run-tut.sh +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/bash - -set -eux - -coursier launch -r "https://dl.bintray.com/tpolecat/maven/" org.tpolecat:tut-core_2.12:0.6.7 -- . tut-tmp '.*\.md$' -classpath $(coursier fetch -p com.chuusai:shapeless_2.12:2.3.3) -Xfatal-warnings -feature - -exit 0 diff --git a/tutorials.md b/tutorials.md new file mode 100644 index 0000000000..17ade963ba --- /dev/null +++ b/tutorials.md @@ -0,0 +1,62 @@ +--- +layout: root-index-layout +title: Tutorials + +tutorials: +- title: "Getting Started with Scala in IntelliJ" + url: "/getting-started/intellij-track/getting-started-with-scala-in-intellij.html" + description: "Create a Scala project using IntelliJ IDE." + icon: rocket +- title: "Getting Started with Scala and sbt" + url: "/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html" + description: "Create a Scala project using sbt and the command-line." + icon: rocket +- title: "Scala for Java Programmers" + url: "/tutorials/scala-for-java-programmers.html" + description: "Quick introduction to the Scala language and compiler for people who already have some experience in Java." + icon: coffee +- title: "Scala on Android" + url: "/tutorials/scala-on-android.html" + description: "Create an Android app in Scala." + icon: robot +- title: "Scala with Maven" + url: "/tutorials/scala-with-maven.html" + description: "Create a Scala project with Maven." + icon: code +--- + +
            +
            +
            +
            +

            Tutorials

            +

            + Tutorials take you by the hand through a series of steps to create Scala applications. +

            +
            + {% for tutorial in page.tutorials %} +
            +
            +
            + {% if tutorial.icon %} +
            +
            +
            + {% endif %} +

            {{ tutorial.title }}

             +
            +
            + {% if tutorial.by %}
            By {{ tutorial.by }}
            {% endif %} + {% if tutorial.description %}

            {{ tutorial.description }}

            {% endif %} +
            +
            +
            + Read +
            +
            + {% endfor %} +
            +
            +
            +
            +