pax_global_header00006660000000000000000000000064146660175630014530gustar00rootroot0000000000000052 comment=e96ae992431019e4441113834b04285dd6a60dd1 yard-0.9.37/000077500000000000000000000000001466601756300125675ustar00rootroot00000000000000yard-0.9.37/.dockerignore000066400000000000000000000000141466601756300152360ustar00rootroot00000000000000doc .yardoc yard-0.9.37/.gitattributes000066400000000000000000000001221466601756300154550ustar00rootroot00000000000000# Auto detect text files and perform LF normalization * text eol=lf *.png binary yard-0.9.37/.github/000077500000000000000000000000001466601756300141275ustar00rootroot00000000000000yard-0.9.37/.github/FUNDING.yml000066400000000000000000000000761466601756300157470ustar00rootroot00000000000000# These are supported funding model platforms github: lsegal yard-0.9.37/.github/ISSUE_TEMPLATE.md000066400000000000000000000017421466601756300166400ustar00rootroot00000000000000[Describe your issue here. Try to be as specific as possible so we can find the root cause more quickly!] ## Steps to reproduce This is the minimal reproduction for the issue. I've done my best to remove all extraneous code and unique environment state on my machine before providing these steps: 1. Run the following command: `yard doc --no-private` 2. Open browser to (URL)... 3. Click on Method List link. ## Actual Output [Provide the full output (**please run yard with `--debug`**) or screenshots for visual issues.] ## Expected Output [Describe what you *expected* to happen.] ## Environment details: - OS: [Enter operating system / version here] - Ruby version (`ruby -v`): [Enter output of `ruby -v`] - YARD version (`yard -v`): [Enter output of `yard -v`] - Relevant software dependency/versions: - [Any 3rd party libs required to reproduce, omit if none] I have read the [Contributing Guide][contrib]. [contrib]: https://github.com/lsegal/yard/blob/main/CONTRIBUTING.md yard-0.9.37/.github/PULL_REQUEST_TEMPLATE.md000066400000000000000000000006521466601756300177330ustar00rootroot00000000000000# Description Describe your pull request and problem statement here. # Completed Tasks - [ ] I have read the [Contributing Guide][contrib]. - [ ] The pull request is complete (implemented / written). - [ ] Git commits have been cleaned up (squash WIP / revert commits). - [ ] I wrote tests and ran `bundle exec rake` locally (if code is attached to PR). [contrib]: https://github.com/lsegal/yard/blob/main/CONTRIBUTING.md yard-0.9.37/.github/dependabot.yml000066400000000000000000000006631466601756300167640ustar00rootroot00000000000000# To get started with Dependabot version updates, you'll need to specify which # package ecosystems to update and where the package manifests are located. # Please see the documentation for all configuration options: # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates version: 2 updates: - package-ecosystem: github-actions directory: / schedule: interval: weekly yard-0.9.37/.github/workflows/000077500000000000000000000000001466601756300161645ustar00rootroot00000000000000yard-0.9.37/.github/workflows/ci.yml000066400000000000000000000014461466601756300173070ustar00rootroot00000000000000name: Unit Tests on: [push, pull_request, workflow_dispatch] jobs: build: name: "Ruby: ${{ matrix.ruby }} OS: ${{ matrix.os }}" runs-on: ${{ matrix.os }} strategy: fail-fast: false matrix: os: [ubuntu-20.04, macos-latest, windows-2019] # 3.0 is interpreted as 3 ruby: [2.6, 2.7, "3.0", 3.1, 3.2, 3.3] exclude: - { os: windows-2019, ruby: 2.2 } - { os: windows-2019, ruby: 2.3 } steps: - name: Checkout uses: actions/checkout@v4 - name: Install Ruby & 'bundle install' uses: ruby/setup-ruby@v1 with: ruby-version: ${{ matrix.ruby }} bundler-cache: true - name: Run Test run: | ruby -v bundle exec rake env: CI: true yard-0.9.37/.github/workflows/gem.yml000066400000000000000000000006471466601756300174660ustar00rootroot00000000000000name: Release Version on: push: tags: - "v*" jobs: release_version: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: lsegal/github-release-from-changelog-action@latest env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Publish RubyGem uses: dawidd6/action-publish-gem@v1 with: api_key: ${{secrets.RUBYGEMS_API_KEY}} yard-0.9.37/.gitignore000066400000000000000000000001731466601756300145600ustar00rootroot00000000000000_Yardoc .DS_Store *.rbc *.pdf .yardoc *.gem Gemfile.lock /pkg /doc /doc_guide /coverage /.bundle /vendor spec/examples.txt yard-0.9.37/.rspec000066400000000000000000000000361466601756300137030ustar00rootroot00000000000000--color --require spec_helper yard-0.9.37/.rubocop.yml000066400000000000000000000053771466601756300150550ustar00rootroot00000000000000#inherit_from: # - .rubocop_todo.yml Metrics: Enabled: false Layout/LineLength: AutoCorrect: true Max: 100 Style/Semicolon: AllowAsExpressionSeparator: true Style/Documentation: Enabled: false Style/ClassVars: Enabled: false Style/HashSyntax: EnforcedStyle: hash_rockets Layout/SpaceInsideHashLiteralBraces: EnforcedStyle: no_space Layout/SpaceInsideBlockBraces: SpaceBeforeBlockParameters: false Style/NumericPredicate: # ruby 1.8/1.9 do not have positive?/negative? EnforcedStyle: comparison Layout/MultilineMethodCallIndentation: EnforcedStyle: indented Layout/DotPosition: EnforcedStyle: trailing Style/FormatString: EnforcedStyle: percent Layout/FirstArrayElementIndentation: EnforcedStyle: consistent Layout/FirstHashElementIndentation: EnforcedStyle: consistent # Disable these until we know what to do with them Style/SafeNavigation: Enabled: false # not supported in 1.8...2.1 Style/GuardClause: # does not provide much value Enabled: false Naming/VariableNumber: Enabled: false Naming/AccessorMethodName: # this creates breaking changes in the API Enabled: false Naming/PredicateName: # this creates breaking changes in the API Enabled: false Style/MethodMissingSuper: # this doesn't exist in 1.8/1.9 Enabled: false Style/MissingRespondToMissing: # this doesn't exist in 1.8/1.9 Enabled: false Style/Lambda: # not supported in 1.8 Enabled: false Style/EachWithObject: # not supported in 1.8 Enabled: false Layout/ParameterAlignment: # does not work correctly with subsequent block Enabled: false Layout/ArrayAlignment: # does not support indentation Enabled: false Layout/HashAlignment: # does not support indentation Enabled: false Style/MultilineTernaryOperator: Enabled: false Style/ClassAndModuleChildren: Enabled: false Layout/EmptyLineBetweenDefs: AllowAdjacentOneLineDefs: true Style/SingleLineMethods: Enabled: false Style/SingleLineBlockParams: Enabled: false Style/NestedTernaryOperator: Enabled: false Style/MutableConstant: Enabled: false Style/WhenThen: Enabled: false Style/StringLiterals: Enabled: false Style/StringLiteralsInInterpolation: Enabled: false Style/PerlBackrefs: Enabled: false Style/BlockComments: Exclude: - benchmarks/*.rb Style/CaseEquality: Enabled: false Style/WordArray: Enabled: false Style/GlobalVars: Exclude: - benchmarks/**/*.rb - spec/**/*.rb Lint/RedundantSplatExpansion: Enabled: false Security/Eval: Exclude: - benchmarks/**/*.rb - spec/**/*.rb Layout/SpaceAroundMethodCallOperator: Enabled: false Lint/RaiseException: Enabled: false Lint/StructNewOverride: Enabled: false Style/ExponentialNotation: Enabled: false Style/HashEachMethods: Enabled: false Style/HashTransformKeys: Enabled: false Style/HashTransformValues: Enabled: false yard-0.9.37/.yardopts000066400000000000000000000010501466601756300144310ustar00rootroot00000000000000--protected --no-private --embed-mixin ClassMethods --exclude /server/templates/ --exclude /yard/rubygems/ --asset docs/images:images --tag yard.signature:"YARD Tag Signature" --type-name-tag yard.tag:"YARD Tag" --type-name-tag yard.directive:"YARD Directive" --hide-tag yard.tag --hide-tag yard.directive --hide-tag yard.signature --load ./docs/templates/plugin.rb - CHANGELOG.md docs/WhatsNew.md docs/GettingStarted.md docs/Tags.md docs/Overview.md docs/CodeObjects.md docs/Parser.md docs/Handlers.md docs/TagsArch.md docs/Templates.md LICENSE LEGAL yard-0.9.37/.yardopts_guide000066400000000000000000000004571466601756300156200ustar00rootroot00000000000000-t guide --title YARD -o doc_guide --exclude /server/templates/ --exclude /yard/rubygems/ --asset docs/images:images - CHANGELOG.md docs/WhatsNew.md docs/GettingStarted.md docs/Tags.md docs/Overview.md docs/CodeObjects.md docs/Parser.md docs/Handlers.md docs/TagsArch.md docs/Templates.md LICENSE LEGAL yard-0.9.37/.yardopts_i18n000066400000000000000000000007771466601756300153070ustar00rootroot00000000000000--protected --no-private --exclude /server/templates/ --exclude /yard/rubygems/ --asset docs/images:images --tag yard.signature:"YARD Tag Signature" --type-name-tag yard.tag:"YARD Tag" --type-name-tag yard.directive:"YARD Directive" --hide-tag yard.tag --hide-tag yard.directive --hide-tag yard.signature --load ./docs/templates/plugin.rb - CHANGELOG.md docs/WhatsNew.md docs/GettingStarted.md docs/Tags.md docs/Overview.md docs/CodeObjects.md docs/Parser.md docs/Handlers.md docs/TagsArch.md docs/Templates.md yard-0.9.37/CHANGELOG.md000066400000000000000000001061001466601756300143760ustar00rootroot00000000000000# main # [0.9.37] - September 4th, 2024 [0.9.37]: https://github.com/lsegal/yard/compare/v0.9.36...v0.9.37 - Fix JavaScript errors in `--one-file` template (#1426) - Fix heredoc parsing and add support for squiggly heredocs (#1315, #1495) - Accessibility improvements to the default template (#1501) - Improved YARD documentation (#1410, #1512, #1516, #1544) - Fix error when parsing `@option` tags (#1515) - Fix issue parsing UTF-8 filenames (#1517) - Replace OpenStruct with optimized YARD::OpenStruct to avoid ostruct performance warnings (#1545) - Add support for `private attr_*` syntax (#1541) - Remove logger dependency (#1546) # [0.9.36] - February 29th, 2024 [0.9.36]: https://github.com/lsegal/yard/compare/v0.9.35...v0.9.36 - Further XSS fixes for generated frameset pages (#1538) - Improve tests for Ruby 3.3 compatibility (#1519, #1531) - Documentation improvements (#1524) # [0.9.35] - February 28th, 2024 [0.9.35]: https://github.com/lsegal/yard/compare/v0.9.34...v0.9.35 - Fix possible XSS on generated YARD frameset pages (thanks to @RedYetiDev for finding and patching) (2069e2b). - Fix errors when using `@option` on non-method objects (#1508) - Support Ruby 3.3 changes in Ripper parser (#1510) # [0.9.34] - April 12nd, 2023 [0.9.34]: https://github.com/lsegal/yard/compare/v0.9.33...v0.9.34 - Add changelog to yard.gemspec - Fix fork behavior in `yard server --fork` # [0.9.33] - April 11st, 2023 [0.9.33]: https://github.com/lsegal/yard/compare/v0.9.32...v0.9.33 - Ensure .yardopts is present in gem package (internal YARD documentation change) # 0.9.32 - April 9th, 2023 [0.9.32]: https://github.com/lsegal/yard/compare/v0.9.31...v0.9.32 - Fix issue with custom Rack::Request attributes in `yard server` # [0.9.31] - April 9th, 2023 [0.9.31]: https://github.com/lsegal/yard/compare/v0.9.30...v0.9.31 - Remove dependency on webrick in YARD::Server::Commands::StaticFileHelpers # [0.9.30] - April 9th, 2023 [0.9.30]: https://github.com/lsegal/yard/compare/v0.9.29...v0.9.30 - Hot release fix to correct issue with gem packaging missing templates (#1490) # [0.9.29] - April 8th, 2023 [0.9.29]: https://github.com/lsegal/yard/compare/v0.9.28...v0.9.29 - Enable table support for CommonMarker (#1443) - Parser performance improvements (#1452, #1453, #1454, #1455) - Fix autoload of RipperParser (#1460) - Remove dependency on webrick for better Ruby 3.1+ support - Improvements for mixin resolution (#1467, #1468) # [0.9.28] - June 1st, 2022 [0.9.28]: https://github.com/lsegal/yard/compare/v0.9.27...v0.9.28 - Safe load config YAML files (#1385) - Handle empty string constants (#1415) - Pre-emptively support removal of `Object#taint` in Ruby 3.2 (#1419) - Fix Ruby 3.1 forward args Ripper change (#1431) # [0.9.27] - November 29th, 2021 [0.9.27]: https://github.com/lsegal/yard/compare/v0.9.26...v0.9.27 - Add support for Ruby 3.0 endless method definitions. (#1376, #1381) - Add existence check for README file (#1367) - Support module_function decorator (#1365) - Add CommonMarker markup support (`-m commonmarker`) (#1157, #1388) - Fix nested array parsing (#1389) - Add WEBrick as a runtime dependency for Ruby 3.0 support (#1400) - Support `fail_on_warning` option in `yard stats` command (#1392) - Better integration with Sorbet (#1401) - Handle include mixins on complex paths (#1386) - Fix `@!scope` maintaining state in lone comment blocks (#1411) - Remove support for Travis CI # [0.9.26] - December 26th, 2020 [0.9.26]: https://github.com/lsegal/yard/compare/v0.9.25...v0.9.26 - Add support for Ruby 3.0 and fix tests - Fix support for `frozen_string_literal: false` magic comments (#1363) # [0.9.25] - May 3rd, 2020 [0.9.25]: https://github.com/lsegal/yard/compare/v0.9.24...v0.9.25 - Fix parsing issue with conditional blocks mixed with conditional modifiers. (#1308, #1324, #1326, #1327) - Add table of contents IDs to redcarpet generated markdown. (#1323) - Backport fixes for Ruby 1.9 (#1320) - Fix parsing of checksums in yard server (#1301) - Map Ruby C variable error names to Ruby classes (#1270, #1275) - Fix initialization of RDocMarkup across threads (#1318) - Remove warning for Kernel#open (#1312) - Omit spec files in gem package (#1307) - README updates (#1322) # [0.9.24] - January 8th, 2020 [0.9.24]: https://github.com/lsegal/yard/compare/v0.9.23...v0.9.24 - Add {YARD::CodeObjects::NamespaceMapper.on_invalidate} callback when separator cache is changed. - Fix issue where Registry fails to resolve first-time lookups on instance methods. # [0.9.23] - January 5th, 2020 [0.9.23]: https://github.com/lsegal/yard/compare/v0.9.22...v0.9.23 - Fix issues with double encoded code blocks when highlighted from an extra file. # [0.9.22] - December 31st, 2019 [0.9.22]: https://github.com/lsegal/yard/compare/v0.9.21...v0.9.22 - Revert jquery update in last release since it requires more changes. (#1298) # [0.9.21] - December 31st, 2019 [0.9.21]: https://github.com/lsegal/yard/compare/v0.9.20...v0.9.21 - Updates to add support for Ruby 2.7.0 (#1290, #1296) - Fix parsing of multiline method signatures (#1220) - Remove RubyGems post install message (#1269) - Improve object deletion from RegistryStore (#1284) - Improve memory usage performance (#1260) - Handle include and extend calls with explicit receivers (#1274) - Fix deep nesting of TOC items (#1288) - Fix highlighting for Asciidoc markup code blocks (#1276) - Fix HTML formatting of script tags (#1263) - Update jquery to 3.4.1 (#1294) - Test fixes (#1244) # [0.9.20] - June 27th, 2019 [0.9.20]: https://github.com/lsegal/yard/compare/v0.9.19...v0.9.20 - Fix parsing of stringified Symbols in Ruby source (#1256). - Fix path traversal vulnerability in `yard server`. This bug would allow unsanitized HTTP requests to access arbitrary files on the machine of a `yard server` host under certain conditions. Thanks to CuongMX from Viettel Cyber Security for discovering this vulnerability. # [0.9.19] - April 2nd, 2019 [0.9.19]: https://github.com/lsegal/yard/compare/v0.9.16...v0.9.19 - Fixed bug in browser back button (#1071, #1228) - Fixed handling of ArgumentError in ExtraFileObject (#1198) - Fixed double return tag displaying on boolean methods (#1226) - Removed unused `Module#namespace_name` function (#1229) - Fixed parsing order of README files. YARD will now prefer README over README.md over README.x.md or README-x.md (and the like). READMEs will now also be ordered by filename; the first README is still chosen unless `--readme` is provided. - Updated AsciiDoc markup support to use non-deprecated calls. # [0.9.16] - August 11th, 2018 [0.9.16]: https://github.com/lsegal/yard/compare/v0.9.15...v0.9.16 - Documentation fixes (#1175, #1178). - Fixed stack overflow issue when parsing extremely large lists (#1176). # [0.9.15] - July 17th, 2018 [0.9.15]: https://github.com/lsegal/yard/compare/v0.9.14...v0.9.15 - Fixed security issue in parsing of Ruby code that could allow for arbitrary execution. Credit to Nelson Elhage for discovering this issue. # [0.9.14] - June 2nd, 2018 [0.9.14]: https://github.com/lsegal/yard/compare/v0.9.13...v0.9.14 - Fixed a regression in symbol parsing (#1170). # [0.9.13] - May 28th, 2018 [0.9.13]: https://github.com/lsegal/yard/compare/v0.9.12...v0.9.13 - Added support for grouped constants via `@!group` directive (#1056). - Added support for quoted symbols (#1168). - Added support for i18n in tag text (#1169). - Fixed HTML rendering of inline code blocks (#1152). - Fixed rendering of anchor URLs in rendered HTML (#1154). # [0.9.12] - November 26th, 2017 [0.9.12]: https://github.com/lsegal/yard/compare/v0.9.11...v0.9.12 - Be more explicit about lack of support for absolute paths in extra files specified by `yard doc` command. # [0.9.11] - November 23rd, 2017 [0.9.11]: https://github.com/lsegal/yard/compare/v0.9.10...v0.9.11 - Fixed security issue in `--readme` that allowed for arbitrary file reads on disk. Credit to ztz for discovering this issue. - Improved styling for inline code blocks (#1142). # [0.9.10] - November 18th, 2017 [0.9.10]: https://github.com/lsegal/yard/compare/v0.9.9...v0.9.10 - Added `--fail-on-warning` option for `yard doc` which exits with a non-zero code if there are any warnings (#1093). - Added support for parsing inside `Struct.new` blocks (#1099). - Added support new ripper AST tokens (#1104, #1124). - Fixed an issue where `@see (obj)` reference tags would fail (#1111) - Fix sorting in `yard stats` (#1123). # [0.9.9] - April 23rd, 2017 [0.9.9]: https://github.com/lsegal/yard/compare/v0.9.8...v0.9.9 - Added `gem uninstall` hooks to remove YARD documentation files. (#1083) - Added support for C++ namespaces. (#809) - Fixed issue where loading a .html page via an anchor would not scroll to the anchor section. (#1082) - Hide some Ruby warnings. - Improve progress indicator icons in terminal. # [0.9.8] - January 13th, 2017 [0.9.8]: https://github.com/lsegal/yard/compare/v0.9.7...v0.9.8 - Fixed installed gems not being correctly found in `yard server` and by plugins. - Fixed tokenization of `%w(...)` array syntax. # [0.9.7] - January 9th, 2017 [0.9.7]: https://github.com/lsegal/yard/compare/v0.9.6...v0.9.7 - Fixed resolution of absolute object paths with ambiguous names. (#1029) # [0.9.6] - January 7th, 2017 [0.9.6]: https://github.com/lsegal/yard/compare/v0.9.5...v0.9.6 - Removed official support for Ruby 1.x (1.8/1.9). YARD can still be installed in these versions, but support is not guaranteed. Simple bug fixes may still be considered via pull request only. Issues without code will be automatically closed. - Added {YARD::Tags::Tag#explain_types} returning a plain English summary of the type specification of a given tag. Also adds {YARD::Tags::TypesExplainer} as an implementation class for the method. - Added support for automatic linking of constants and method calls of Ruby syntax highlighted source code in generated HTML. Also adds the {YARD::Parser::Ruby::TokenResolver} implementation class to iterate over tokenized code with extra resolved object information. - Added support for compound constant assignments (`A::B::C = true`). - Added `LibraryVersion#yardoc_file_for_SOURCE` callback method for sources with a pre-determined yardoc file location. Implement this method instead of manually setting `library.yardoc_file = ...` in your load method (you can still assign the attribute manually). - Use RubyGems 2.x+ API to query gems when available instead of using backport. - Various bug fixes # [0.9.5] - July 22nd, 2016 [0.9.5]: https://github.com/lsegal/yard/compare/v0.9.4...v0.9.5 - `yard doc` will now generate `.yardoc/processing` and `.yardoc/complete` files to allow other tools to properly detect when YARD is in the middle of parsing source files, and when it has completed writing the database. - Added support for on-demand generation of LibraryVersion objects using the `:disk` source type. LibraryVersion objects pointing to a .yardoc database directory will now auto-generate if there is a `source_path` attached. - Added warning for macros attached to non-method objects. - Fixed a few more parsing errors. # [0.9.4] - July 21st, 2016 [0.9.4]: https://github.com/lsegal/yard/compare/v0.9.3...v0.9.4 - Minor Ruby file parsing and CSS bug fixes. # [0.9.3] - July 20th, 2016 [0.9.3]: https://github.com/lsegal/yard/compare/v0.9.2...v0.9.3 - Added support for {YARD::Server::RackAdapter} to be mounted under prefix URIs. - Fixed regression in `yard server -g` that caused static file assets on index page to return 404 errors. - Fixed regression in `yard server -g` index page that disabled scrolling and caused other HTML rendering glitches. # [0.9.2] - July 19th, 2016 [0.9.2]: https://github.com/lsegal/yard/compare/v0.9.1...v0.9.2 - Added `yard config --gem-install-[yri|yard]` commands which auto-configure your `~/.gemrc` file to run yri/yard instead of ri/rdoc on a `gem install`. - Added support for gemspec metadata key `"yard.run"`, which can be either `"yard"` or `"yri"` to run the respective commands on a `gem install`. - Added `yard doc --no-progress` to hide the progress bar. - Fix resolution error for compound proxy namespaces. - YRI will now search across all gem versions (latest first) for the .yardoc database. # [0.9.1] - July 18th, 2016 [0.9.1]: https://github.com/lsegal/yard/compare/v0.9.0...v0.9.1 - Added "Attributes" section to `yard stats`. - Added support for RubyGems 2.x `--document=yri,yard` flags. You can now run YARD documentation generation against installed gems by running: `gem install mygem --document=yard,yri`. - Added `/static/*` routing for library-specific routing. This enables static template files to be served on a per-library basis instead of globally shared across the `yard server`. - Added support for inlining of `{include:*}` syntax. Using this syntax in the middle of a docstring paragraph will no longer create a separate paragraph for the included text. - Added support for resolving `{}` syntax in text templates, specifically for use in `{include:*}` syntax. - Improved object resolution logic in `{Foo::Bar}` syntax and {YARD::Registry.resolve}. New resolution logic should now more accurately support resolving compound paths across namespaces and through the inheritance tree (as Ruby does). - The `frozen_string_literal: true` comment line in Ruby source files will now be excluded from docstrings. - Added a workaround for https://bugs.ruby-lang.org/issues/11485 - Fixed an issue where type using a docstring reference on an `@!attribute` macro would be incorrectly parsed as a type specifier. This change updates the tag parser to disallow newlines between the tag name and opening bracket of the type specification. - Fixed an issue where `--embed-mixins` would improperly embed methods from inherited classes instead of modules. - Fixed various parsing errors and YARD exceptions. - Added a warning for modules or classes being redefined as constants. - Reverted stripping of HTML in {YARD::Docstring#summary}. - Added optimization to remove initial docstring parse on newly created code objects. - {YARD::CodeObjects::Base#format} now passes the :type parameter to templates. - Hide methods with filtered namespaces in Method Listing. # [0.9.0] - July 4th, 2016 [0.9.0]: https://github.com/lsegal/yard/compare/v0.8.7.6...v0.9.0 Special thanks to Alex Dowad, MSP-Greg, and Alex McLain for their extended contributions to this version. - (Breaking Change): Replaced default template with an updated "frameless" version. This change may affect backward compatibility if custom templates made modifications to `default/fulldoc/html`, specifically the index or navigation lists. - Added support for Ruby 2.1+ decorator style method declaration syntax. YARD now supports: private def foo(x, y) end - Metadata headers in extra files can now be escaped from rendering by enclosing them in HTML comment blocks (``). Ensure that the opening comment tag is alone on the first line of the file to use this functionality. - Improved parsing of various CRuby coding styles. - Fixed issue with binary image assets when using `yard server`. - Fixed deprecation warnings from Rake 10.x. - Tests updated for RSpec 3. # [0.8.7.6] - October 26, 2014 [0.8.7.6]: https://github.com/lsegal/yard/compare/v0.8.7.5...v0.8.7.6 - Support using `@option` tag on keyword arg splat parameter. (#729) - Add `.stats_options` for `YardocTask`. (#800, #801) # [0.8.7.5] - October 26, 2014 [0.8.7.5]: https://github.com/lsegal/yard/compare/v0.8.7.4...v0.8.7.5 - Fix linking of methods in top level namespace in method listing. (#776) - Support using C macros in function declarations. (#810) - YARD will no longer group comment blocks starting on the same column if they are preceded by code. (#798) - Handle anonymous lambda calls in toplevel scope. (#774) - Support I18n in `@overload` tags. (#794) - Support `yard stats` for objects with no file property. (#792) - Support for named arguments in Ruby >= 2.1. (#785) - Exclude README backup files from YARD generation. (#790) - Turned on the lax spacing option in Redcarpet to comply with the Markdown standard. - Escape HTML in YARD server search placeholder template. - Fix issue with `private_class_method` support. (#760, #767) - Enable tables support by default in Redcarpet Markdown provider. (#765) # 0.8.7.4 - March 22, 2014 [0.8.7.4]: https://github.com/lsegal/yard/compare/v0.8.7.3...v0.8.7.4 - Mark C methods as explicit but also remove explicit check in stats. (#727) - Report unresolved parent namespaces as undocumentable errors instead. (#753) - No longer ignore overridden methods from documentation check in stats (#719) - Fix JRuby throwing exception when remove_method called on non-existent method. (#732) - Add basic support for `private_class_method` (#747) - Ensure namespace is always set when parent module is not found. (#753) - Set overflow as auto on table of contents. - Report 100% documented if nothing is undocumented. (#754) - Added support for RubyGems 2.0.0+. (#742) - Allow users to enter their own YARD RakeTask name. (#705) - Fixed a typo that was causing Windows detection to always fail. (#715) - Add debug information when loading a plugin fails. (#711) # [0.8.7.3] - November 1, 2013 [0.8.7.3]: https://github.com/lsegal/yard/compare/v0.8.7.2...v0.8.7.3 - Handle Unicode method/class/file names in server URL encoding (lsegal/rubydoc.info#69). - Style keyword style hashes with same symbol color in code highlighting (#707). - Fix broken JS when visiting docs in file:// scheme (#706). - Add support for new AsciiDoc file extensions (#704). - Fix issues where non-Ruby code blocks would not display in Ruby 2 (#702). - Add support for extra Ruby 2 symbol types in Ripper (#701). - Ensure config directory exists before saving config file (#700). # [0.8.7.2] - September 18, 2013 [0.8.7.2]: https://github.com/lsegal/yard/compare/v0.8.7.1...v0.8.7.2 - Disallow absolute URLs when using frame anchor support. - Support casted functions in CRuby method declarations (#697) # [0.8.7.1] - September 11, 2013 [0.8.7.1]: https://github.com/lsegal/yard/compare/v0.8.7...v0.8.7.1 - Fix potential XSS issue with frame anchor support. - Add support for gettext 3.x gem. # [0.8.7] - July 26, 2013 [0.8.7]: https://github.com/lsegal/yard/compare/v0.8.6.2...v0.8.7 - Added `--hide-api API` option to hide objects with a given `@api` tag (#685). - Added "Returns ...." prefix to summary when a lone @return tag is used. - Fixed issue that caused ref tags to be added to a docstring twice (#678). - Fixed formatting issue in docstring summaries (#686) # [0.8.6.2] - June 27, 2013 [0.8.6.2]: https://github.com/lsegal/yard/compare/v0.8.6.1...v0.8.6.2 - Fixed issue where `yard graph` was not displaying methods # [0.8.6.1] - April 14, 2013 [0.8.6.1]: https://github.com/lsegal/yard/compare/v0.8.6...v0.8.6.1 - Fixed broken links in File menu on default HTML template - Added --layout switch to `yard display` to wrap output in layout template. - See {file:docs/WhatsNew.md} for more information on added features. # [0.8.6] - April 13, 2013 [0.8.6]: https://github.com/lsegal/yard/compare/v0.8.5.2...v0.8.6 - Various fixes and improved Ruby 2.x compatibility support - Added support for `asciidoc` markup type - Added `yard markups` command to list available markup types - Added `yard display` command to display and format an individual object - See {file:docs/WhatsNew.md} for more information on added features. # [0.8.5.2] - February 26, 2013 [0.8.5.2]: https://github.com/lsegal/yard/compare/v0.8.5.1...v0.8.5.2 - Support new keyword argument syntax in method signatures (Ruby 2.x) # [0.8.5.1] - February 25, 2013 [0.8.5.1]: https://github.com/lsegal/yard/compare/v0.8.5...v0.8.5.1 - Fix `yard diff` of gem files with RubyGems 2.x # [0.8.5] - February 24, 2013 [0.8.5]: https://github.com/lsegal/yard/compare/v0.8.4.1...v0.8.5 - Basic support for Ruby 2.0 (fix compat issues in RDoc 4.0, RubyGems 2.0) - Add CSS styling for tables in default HTML template # [0.8.4.1] - February 5, 2013 [0.8.4.1]: https://github.com/lsegal/yard/compare/v0.8.4...v0.8.4.1 - Fix regression that broke loading of existing yardoc dbs (#648) # [0.8.4] - February 4, 2013 [0.8.4]: https://github.com/lsegal/yard/compare/v0.8.3...v0.8.4 - Add `-B/--bind` switch to yard server (#593, #608) - Add CodeObjects::Base#title for plugins to customize how object links display (#646) - Disable linking objects filtered out by verifiers (#645) - Allow macro expansion on class methods (#632) - Expand newly attached macro on first DSL method call (#631) - Disable RubyGems plugin in Ruby 2.0 (#627) - Fix line range for class/module node bodies (#626) - Search extended modules for attached DSL macros (#553) # [0.8.3] - October 14, 2012 [0.8.3]: https://github.com/lsegal/yard/compare/v0.8.2.1...v0.8.3 - Add `--non-transitive-tag` to disable tag transitivity (#571) - Support --db inside .yardopts for graph/server commands (#583, #586) - Fix handling for =begin/=end docstrings (#577, #578) - Parser only sorts file lists when a glob is provided (#572) - Fix formatting in `{include:Object#method}` syntax (#569) - Fix @option tag inside of module functions (#563) - Fix to `--api` and `--no-api` support (#559) - Fix class nesting issues when path starts with "::" (#552) # [0.8.2.1] - June 9, 2012 [0.8.2.1]: https://github.com/lsegal/yard/compare/v0.8.2...v0.8.2.1 - Fix a set of regressions in yard server search and dynamic generation # [0.8.2] - June 7, 2012 [0.8.2]: https://github.com/lsegal/yard/compare/v0.8.1...v0.8.2 - Added progress style output in tty terminals - Embedded mixins should ignore methods defined on module (#539) - Fixed permalinks for embedded mixins in `yard server` (#540) - Improve parsing in CRuby code (#543) - Ensure Registry.resolve picks module when parsing mixins (#545) - Fixed regression that caused various commands to not show output (#548) - Respect current visibility when parsing class conditions (#551) # [0.8.1] - May 2, 2012 [0.8.1]: https://github.com/lsegal/yard/compare/v0.8.0...v0.8.1 - Added `--[no-]api` switch to generate docs for API sets (see {file:docs/WhatsNew.md} for details) (#532) - The `yard list` command now uses cache by default (#533) - Fix `yardoc` generating incorrectly named method list file (#528) - Fix HTML output occasionally showing trailing mdash on options list (#522) # [0.8.0] - April 30, 2012 [0.8.0]: https://github.com/lsegal/yard/compare/v0.7.5...v0.8.0 - See {file:docs/WhatsNew.md} for a list of added features - Over 20 bug fixes: - Properly filter hidden setter/getter attributes (#394) - Fix test failures in Linux environments (#397, #472, #473, #512, #513) - Fix attribute inheritance and @private (#432) - Fix attribute parsing (#435) - Allow aliases for attributes (#436) - Fix namespace fetching in `handle_alias()` (#437) - Fix overwritten attributes marked as inherited (#442) - Fix documenting constants defined from C code with `rb_define_const()` (#443) - Do not escape snippets twice (#445) - Ajax method/class search should not fire when a non-printable character is pressed (#446) - Fix yard server crashing when RDoc is not installed (#456) - Fix tags ignored when `(see #foo)` is used (#457) - Fix three "Returns" for two `@overload` tags (#458) - Do not auto-detect DSL methods as method objects if parameter name is not a valid method name (#464) - Fix attaching of macros to Object (#465) - Fix handling of `%w()` source in `[]/[]=` parsed context. (#461, pull in #468) - Don't add default `@return` if `@overload` has `@return`. (#458, pull in #469) - Don't discard tags by (see ...). (#457, pull in #470) - Fix constants listed as inherited when overwritten (#474) - Fix `yardoc --asset` behaving differently on first and subsequent calls. (#477) - `!!!lang` code blocks should set the lang in `
`'s class. (#478, #479)
  - Fix "File List" search tab error. (#502)
  - Fix search bar not redirecting to method page. (#509)
  - Fix server returning exception message bodies as String (#518)

# [0.7.5] - January 31, 2012

[0.7.5]: https://github.com/lsegal/yard/compare/v0.7.4...v0.7.5

- Various minor bug fixes

# [0.7.4] - December 2, 2011

[0.7.4]: https://github.com/lsegal/yard/compare/v0.7.3...v0.7.4

- Redcarpet is now the default Markdown formatting library. GFM now works out-of-box (#404)
- Fix server side searching for elements that are marked private (#420)
- Add 'textile_strict' and 'pre' markup types, reorganize text and none (#416)
- Improve encoding line detection (#415)
- Add support for `rb_define_alias` in CRuby code (#413)
- Fix rendering of some keywords in source view (#410)
- Add support for RDoc 3.10+ (#406, #407)
- Fix typewriter text being processed in code blocks (#403)
- Improve support for has_rdoc in RubyGems 1.8.x (#401)
- See the {file:docs/WhatsNew.md} document for details on added features

# [0.7.3] - October 15, 2011

[0.7.3]: https://github.com/lsegal/yard/compare/v0.7.2...v0.7.3

- Improve support for parsing under Ruby 1.9.2p290 and 1.9.3 (#365, #370)
- Add support for SWIG generated CRuby code (#369)
- Add support for `rb_define_attr` calls in CRuby code (#362)
- Handle file pointers in CRuby code (#358)

# [0.7.2] - June 14, 2011

[0.7.2]: https://github.com/lsegal/yard/compare/v0.7.1...v0.7.2

- Fix `yard --help` not showing proper output
- YARD now expands path to `.yardoc` file in daemon mode for server (#328)
- Fix `@overload` tag linking to wrong method (#330)
- Fix incorrect return type when using `@macro` (#334)
- YARD now requires 'thread' to support RubyGems 1.7+ (#338)
- Fix bug in constant documentation when using `%w()` (#348)
- Fix YARD style URL links when using autolinking markdown (#353)

# [0.7.1] - May 18, 2011

[0.7.1]: https://github.com/lsegal/yard/compare/v0.7.0...v0.7.1

- Fixes a bug in `yard server` not displaying class list properly.

# [0.7.0] - May 17, 2011

[0.7.0]: https://github.com/lsegal/yard/compare/v0.6.8...v0.7.0

- See the {file:docs/WhatsNew.md} document for details on added features
- Make sure that Docstring#line_range is filled when possible (#243)
- Set #verifier in YardocTask (#282)
- Parse BOM in UTF-8 files (#288)
- Fix instance attributes not showing up in method list (#302)
- Fix rendering of %w() literals in constants (#306)
- Ignore keyboard shortcuts when an input is active (#312)
- And more...

# [0.6.8] - April 14, 2011

[0.6.8]: https://github.com/lsegal/yard/compare/v0.6.7...v0.6.8

- Fix regression in RDoc 1.x markup loading
- Fix regression in loading of markup libraries for `yard server`

# [0.6.7] - April 6, 2011

[0.6.7]: https://github.com/lsegal/yard/compare/v0.6.6...v0.6.7

- Fix has_rdoc gem specification issue with new RubyGems plugin API (oops!)

# [0.6.6] - April 6, 2011

[0.6.6]: https://github.com/lsegal/yard/compare/v0.6.5...v0.6.6

- Fix error message when RDoc is not present (#270)
- Add markup type 'none' to perform basic HTML translation (fallback when RDoc is not present)
- Add support for RubyGems 1.7.x (#272)
- Fix rendering of `{url description}` syntax when description contains newline

# [0.6.5] - March 13, 2011

[0.6.5]: https://github.com/lsegal/yard/compare/v0.6.4...v0.6.5

- Support `ripper` gem in Ruby 1.8.7
- Upgrade jQuery to 1.5.1
- Fix handling of alias statements with quoted symbols (#262)
- Add CSS styles (#260)
- Unhandled exception in YARD::Handlers::Ruby::MixinHandler indexing documentation for eventmachine (#248)
- Splice any alias references on method re-definitions into separate methods (#247)
- Fix "yard graph" (#245)
- Don't process ++ typewriter text inside of HTML attributes (#244)
- Prioritize loading of Kramdown before Maruku (#241)
- Skip shebang encoding in docstrings (#238)
- Fix truncation of references in @deprecated (#232)
- Show @api private note when no other tags are present (#231)
- Detect docstrings starting with "##" as `Docstring#hash_flag` (#230)
- Remove trailing whitespace from freeform tags (#229)
- Fix line through for deprecated methods (#225)
- Mistake in Tags.md (#223)
- Improve database storage by being more efficient with filesystem usage (#222)
- Make Registry thread local (#221)
- Support `private_constant` class method for 1.9.3 (#219)
- Do not assume RDoc is installed (#214)

# [0.6.4] - December 21, 2010

[0.6.4]: https://github.com/lsegal/yard/compare/v0.6.3...v0.6.4

- Fix yri tool crashing with new Config class (gh-217)
- Fix support for ::TopLevelConstants (gh-216)
- YARD's test suite is now RSpec2 compatible (gh-215)
- Improved documentation for YARD::Server features (gh-207)
- Fix displaying of collaped method summary lists (gh-204)
- Fix automatic loading of markup providers (gh-206)
- Fix keyboard shortcuts for Chrome (gh-203)
- Disallow `extend self` inside of a class (gh-202)
- Constants now recognized in C extensions (gh-201)

# [0.6.3] - November 21, 2010

[0.6.3]: https://github.com/lsegal/yard/compare/v0.6.2...v0.6.3

- Fixed regression that caused `yardoc --markup` to silently exit

# [0.6.2] - November 15, 2010

[0.6.2]: https://github.com/lsegal/yard/compare/v0.6.1...v0.6.2

- **Plugins no longer automatically load, use `--plugin` to load a plugin**
- Added YARD::Config and ~/.yard/config YAML configuration file
- Added `yard config` command to view/edit YARD configuration file
- Fixes for YARD in 1.8.6 (gh-178)
- Various HTML template adjustments and fixes (gh-198,199,200)
- Improved `yard server -m` multi-project stability (gh-193)
- Fixed handling of `yardoc --no-private` with missing class definitions (gh-197)
- Added support for constants defined in C extensions (gh-177)
- Added support for Structs defined as "Klass = Struct.new(...)" (gh-187)
- Improved parsing support for third-party gems (gh-174,180)
- Improved support for JRuby 1.6.4+. YARD now passes all specs in JRuby (gh-185)
- Improved YARD documentation (gh-172,191,196)

# [0.6.1] - September 06, 2010

[0.6.1]: https://github.com/lsegal/yard/compare/v0.6.0...v0.6.1

- Fixed TOC showing on top of class/method list in no-frames view
- A message now displays when running `yard server` with Rack/Mongrel installed
- Improved performance of JS inline search for large class/method lists
- Improved link titles for relative object links
- Removed `String#camelcase` and `String#underscore` for better Rails compat.
- Fixed support for loading .yardoc files under Windows
- Fixed inheritance tree arrows not displaying in certain environments

# [0.6.0] - August 29, 2010

[0.6.0]: https://github.com/lsegal/yard/compare/v0.5.8...v0.6.0

- Added dynamic local documentation server
- Added @group/@endgroup declarations to organize methods into groups
- Added `yard` executable to serve as main CLI tool with pluggable commands
- Added `--asset` switch to `yardoc` to copy files/dirs to output dir
- Added ability to register/manipulate tags via CLI (`--tag`, etc.)
- Added `yard diff` command
- Added statistics to `yardoc` output (and `yard stats` command)
- Added Javascript generated Table of Contents to file pages
- Updated various APIs
- Removed `yard-graph` executable
- See more changes in the {file:docs/WhatsNew.md what's new document}

# [0.5.8] - June 22, 2010

[0.5.8]: https://github.com/lsegal/yard/compare/v0.5.7...v0.5.8

- Merge fix from 0.6 branch for --no-private visibility checking

# [0.5.7] - June 21, 2010

[0.5.7]: https://github.com/lsegal/yard/compare/v0.5.6...v0.5.7

- Fixed visibility flag parsing in `yardoc`
- Updated Parser Architecture documentation with new SourceParser API
- Improved Registry documentation for new load commands
- Fix loading of .yardoc file as cache (and preserving aliases)
- Fix "lib" directory missing when running YARD on installed gems

# [0.5.6] - June 12, 2010

[0.5.6]: https://github.com/lsegal/yard/compare/v0.5.5...v0.5.6

- Bug fixes for RubyGems plugin, `has_rdoc=false` should now work
- New API for registering custom parsers. See {file:docs/WhatsNew.md}

# [0.5.5] - May 22, 2010

[0.5.5]: https://github.com/lsegal/yard/compare/v0.5.4...v0.5.5

- Various bug fixes

# [0.5.4] - March 22, 2010

[0.5.4]: https://github.com/lsegal/yard/compare/v0.5.3...v0.5.4

- See {file:docs/WhatsNew.md what's new document} for changes

# [0.5.3] - January 11, 2010

[0.5.3]: https://github.com/lsegal/yard/compare/v0.5.2...v0.5.3

- See {file:docs/WhatsNew.md what's new document} for changes

# [0.5.2] - December 16, 2009

[0.5.2]: https://github.com/lsegal/yard/compare/v0.5.1...v0.5.2

- See {file:docs/WhatsNew.md what's new document} for changes

# [0.5.1] - December 15, 2009

[0.5.1]: https://github.com/lsegal/yard/compare/v0.5.0...v0.5.1

- See {file:docs/WhatsNew.md what's new document} for changes

# [0.5.0] - December 13, 2009

[0.5.0]: https://github.com/lsegal/yard/compare/v0.4.0...v0.5.0

- See {file:docs/WhatsNew.md what's new document} for changes

# [0.4.0] - November 15, 2009

[0.4.0]: https://github.com/lsegal/yard/compare/v0.2.3.5...v0.4.0

- Added new templating engine based on [tadpole](http://github.com/lsegal/tadpole)
- Added YARD queries (`--query` CLI argument to yardoc)
- Greatly expanded YARD documentation
- Added plugin support
- New `@abstract` and `@private` tags
- Changed default rake task to `rake yard`
- Read about changes in {file:docs/WhatsNew.md}

# [0.2.3.5] - August 13, 2009

[0.2.3.5]: https://github.com/lsegal/yard/compare/v0.2.3.4...v0.2.3.5

- Minor bug fixes.

# [0.2.3.4] - August 07, 2009

[0.2.3.4]: https://github.com/lsegal/yard/compare/v0.2.3.3...v0.2.3.4

- Minor bug fixes.

# [0.2.3.3] - July 26, 2009

[0.2.3.3]: https://github.com/lsegal/yard/compare/v0.2.3.2...v0.2.3.3

- Minor bug fixes.

# [0.2.3.2] - July 06, 2009

[0.2.3.2]: https://github.com/lsegal/yard/compare/v0.2.3.1...v0.2.3.2

- Fix Textile hard-break issues
- Add description for @see tag to use as link title in HTML docs.
- Add --title CLI option to specify a title for HTML doc files.
- Add custom.css file that can be overridden with various custom
  styelsheet declarations. To use this, simply add `default/fulldoc/html/custom.css`
  inside your code directory and use the `-t` template directory yardoc CLI
  option to point to that template directory (the dir holding 'default').
- Add support in `yardoc` CLI to specify extra files (formerly --files)
  by appending "- extra files here" after regular source files. Example:

        yardoc --private lib/**/*.rb - FAQ LICENSE

# [0.2.3.1] - June 13, 2009

[0.2.3.1]: https://github.com/lsegal/yard/compare/v0.2.3...v0.2.3.1

- Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead of
  RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in your
  .gemspec file.

# [0.2.3] - June 07, 2009

[0.2.3]: https://github.com/lsegal/yard/compare/v0.2.2...v0.2.3

- See the {file:docs/WhatsNew.md} file for a list of important new features.

# [0.2.2] - Jun 16, 2008

[0.2.2]: https://github.com/lsegal/yard/compare/v0.2.1...v0.2.2

- This is the largest changset since yard's conception and involves a complete
  overhaul of the parser and API to make it more robust and far easier to
  extend and use for the developer.

# [0.2.1] - February 20, 2008

[0.2.1]: https://github.com/lsegal/yard/compare/v0.1a...v0.2.1

- See the {file:docs/WhatsNew.md} file for a list of important new features.

# 0.1a - February 24, 2007

- Released 0.1a experimental version for testing. The goal here is
  to get people testing YARD on their code because there are too many possible
  code styles to fit into a sane amount of test cases. It also demonstrates the
  power of YARD and what to expect from the syntax (Yardoc style meta tags).
yard-0.9.37/CODE_OF_CONDUCT.md000066400000000000000000000012751466601756300153730ustar00rootroot00000000000000This document provides community guidelines for a safe, respectful, productive,
and collaborative place for any person who is willing to contribute to the YARD
project. It applies to all “collaborative space”, which is defined as community
communications channels (such as mailing lists, submitted patches, commit
comments, etc.).

* Participants will be tolerant of opposing views.

* Participants must ensure that their language and actions are free of personal
  attacks and disparaging personal remarks.

* When interpreting the words and actions of others, participants should always
  assume good intentions.

* Behaviour which can be reasonably considered harassment will not be tolerated.
yard-0.9.37/CONTRIBUTING.md000066400000000000000000000161661466601756300150320ustar00rootroot00000000000000# Contributing Guide

## Help YARD Help You!

**YARD thrives off of the contributions of its users**. This project will gladly
review pull requests and issues. This document outlines how to maximize
the chance of a reported issue being resolved or pull request being accepted.

## Code of Conduct

**All reported issues, pull requests, communication, and code related to YARD**
**must follow the [Code of Conduct][code] or they will be moderated immediately**.
Please take time to familiarize yourself with the Code of Conduct before
you get started. Fundamentally, **you are expected to behave with respect** to all
other users.

## Filing a Bug Report

**You can submit bug reports on our [GitHub issue tracker][issues]**.

If you believe you have found a bug, please include a few things in your report:

1. **A minimal reproduction of the issue**. Providing a huge blob of code is
   better than nothing, but providing the shortest possible set of instructions
   is even better. Take out any instructions or code that, when removed, have
   no effect on the problematic behavior. The easier your bug is to triage and
   diagnose, the higher up in the priority list it will go. We can do this stuff,
   but limited time means this may not happen immediately. Make your bug report
   extremely accessible and you will almost guarantee a quick fix.

2. **Your environment and relevant versions**. Please include your Ruby,
   YARD, and system versions (including OS) when reporting a bug. This
   makes it easier to diagnose problems. If the issue or stack trace
   includes another library, consider also listing any dependencies
   that may be affecting the issue. This is where a minimal reproduction
   case helps a lot.

3. **Your expected result**. Tell us what you think should happen. This
   helps us to understand the context of your problem. Many complex features
   can contain ambiguous usage, and your use case may differ from the
   intended one. If we know your expectations, we can more easily determine
   if the behavior is intentional or not.

Finally, please **DO NOT** submit a report that states a feature simply
_"does not work"_ without any additional information in the report. Consider
the issue from the maintainer's perspective: in order to fix your bug, we
need to drill down to the broken line of code, and in order to do this,
we must be able to reproduce the issue on our end to find that line of
code. The easier we can do this, the quicker your bug gets fixed. Help
us help you by providing as much information as you possibly can. We may
not have the tools or environment to properly diagnose your issue, so
your help may be required to debug the issue.

Also **consider opening a pull request** to fix the issue yourself if you can.
This will likely speed up the fix time significantly. See below for
information on how to do this.

## Asking a Question

**Questions are accepted on [GitHub issues][issues], but consider signing up**
**for the [YARD mailing list][ml]** and asking it there so that we can organize
issues appropriately. You can also hop onto IRC (irc.freenode.net / #yard)
for quick questions.

## Asking for a Feature

**YARD does not currently accept feature requests filed as GitHub issues**. If
you are looking to have a feature implemented into YARD, consider doing this
yourself and [submitting a pull request][pr] (PR) with your work. If the work
required is involved, consider starting a discussion on the [mailing list][ml]
or opening an issue to ask a question; we will be happy to have a conversation
and let you know if the feature would be considered. They usually are, but
it might be prudent to ask first!

Please do not fret if your feature request gets closed immediately. We do this
to keep our issue tracker clean. **Closing an issue does not mean it would not**
**be accepted as a pull request**. If the feature would not be accepted as a
PR, this will be communicated in the closed issue.

## Making a Change via Pull Request

**You can also submit pull requests on our [GitHub issue tracker][issues]**.

If you've been working on a patch or feature that you want in YARD, here are
some tips to ensure the quickest turnaround time on getting it merged in:

1. **Keep your changes small**. If your feature is large, consider splitting
   it up into smaller portions and submit pull requests for each component
   individually. Feel free to describe this in your first PR or on the
   mailing list, but note that it will be much easier to review changes
   if they affect smaller portions of code at a time.

2. **Keep commits brief and clean**: YARD uses Git and tries to maintain a
   clean repository. Please ensure that you use [commit conventions][commit]
   to make things nice and neat both in the description and commit history.
   Specifically, consider squashing commits if you have partial or complete
   reverts of code. Each commit should provide an atomic change that moves
   the project forwards, not back. Any changes that only fix other parts of
   your PR should be hidden from the commit history.

3. **Follow our coding conventions**. YARD uses typical Ruby source formatting,
   though it occasionally has minor differences with other projects you may
   have seen. Please look through a few files (at least the file you are
   editing) to ensure that you are consistent in the formatting your PR is
   using.

4. **Make sure you have tests**. Not all changes require tests, but if your
   changes involve code, you should consider adding at least one new test
   case for your change (and ideally a couple of tests). This will add
   confidence when reviewing and will make accepting the change much easier.

5. **Make sure ALL the tests pass**. YARD has a fairly large suite of tests.
   Please make sure you can run all of the tests (`bundle exec rake`) prior
   to submitting your PR. Please also remember that YARD supports a number
   of environments, including OS X, Linux, Windows, and a number of older
   Ruby versions (1.8+), so if you can test under these environments, that
   helps (but is not required). At the very least, be aware of this fact
   when submitting code.

If your change is large, consider starting a discussion on the [mailing list][ml]
or opening an issue to ask a question; we will be happy to have a conversation
and let you know if the feature would be considered. They usually are, but
it might be prudent to ask first!

## Maintainers

**Interested in helping to maintain YARD? Email [lsegal@soen.ca][mail]** for more
information. Offering to be a project maintainer is an important contribution
to open source software, and your work will be highly valued in the community.
If you have been a contributor, consider being a member of the core team to
help handle day-to-day operations, such as releases, bug fixes, and triage.
You can do some of this as a non-maintainer too, but if you like this project,
we can always use more hands on deck!

[code]: https://github.com/lsegal/yard/blob/main/CODE_OF_CONDUCT.md
[issues]: http://github.com/lsegal/yard/issues
[commit]: http://chris.beams.io/posts/git-commit/
[pr]: https://help.github.com/articles/using-pull-requests/
[ml]: https://groups.google.com/forum/#!forum/yardoc
[mail]: mailto:lsegal@soen.ca
yard-0.9.37/Dockerfile.samus000066400000000000000000000012171466601756300157110ustar00rootroot00000000000000FROM lsegal/samus:latest as samus

FROM ruby:2
ARG VERSION
ENV VERSION=${VERSION}
WORKDIR /github/lsegal/yard
ENTRYPOINT samus publish release-v${VERSION}.tar.gz

# Prepare credential config
RUN mkdir -p ~/.ssh
RUN echo "Host *" > ~/.ssh/config
RUN echo "    StrictHostKeyChecking no" >> ~/.ssh/config
RUN chmod 400 ~/.ssh/config
COPY ./.samusprep/.samus /root/.samus
COPY ./.samusprep/.gitconfig /root/.gitconfig

# Setup Samus
ENV PATH=$PATH:/samus/bin
COPY --from=samus /samus /samus

# Install gems
ENV BUNDLE_PATH=/var/gems
COPY Gemfile /github/lsegal/yard
RUN bundle

# Run build
COPY . /github/lsegal/yard
RUN samus build --skip-restore ${VERSION}
yard-0.9.37/Gemfile000066400000000000000000000010051466601756300140560ustar00rootroot00000000000000# frozen_string_literal: true
source 'https://rubygems.org'

group :development do
  gem 'rspec', '>= 3.11.0'
  gem 'rake'
  gem 'rdoc', '= 6.1.2.1'
  gem 'json'
  gem 'simplecov'
  gem 'samus', '~> 3.0.9', :require => false
  gem 'coveralls_reborn', :require => false
  gem 'webrick'
end

group :asciidoc do
  gem 'asciidoctor'
end

group :markdown do
  gem 'redcarpet'
  gem 'commonmarker'
end

group :textile do
  gem 'RedCloth'
end

group :server do
  gem 'rack', '~> 2.0'
end

group :i18n do
  gem 'gettext'
end
yard-0.9.37/LEGAL000066400000000000000000000106661466601756300133470ustar00rootroot00000000000000LEGAL NOTICE INFORMATION
------------------------

All the files in this distribution are covered under either the MIT
license (see the file LICENSE) except some files mentioned below.

lib/yard/parser/ruby/legacy/ruby_lex.rb:

  This file is under the Ruby license. YARD uses a modified version of it.

    Ruby is copyrighted free software by Yukihiro Matsumoto .
    You can redistribute it and/or modify it under either the terms of the GPL
    version 2 (see the file GPL), or the conditions below:

      1. You may make and give away verbatim copies of the source form of the
         software without restriction, provided that you duplicate all of the
         original copyright notices and associated disclaimers.

      2. You may modify your copy of the software in any way, provided that
         you do at least ONE of the following:

           a) place your modifications in the Public Domain or otherwise
              make them Freely Available, such as by posting said
          modifications to Usenet or an equivalent medium, or by allowing
          the author to include your modifications in the software.

           b) use the modified software only within your corporation or
              organization.

           c) give non-standard binaries non-standard names, with
              instructions on where to get the original software distribution.

           d) make other distribution arrangements with the author.

      3. You may distribute the software in object code or binary form,
         provided that you do at least ONE of the following:

           a) distribute the binaries and library files of the software,
          together with instructions (in the manual page or equivalent)
          on where to get the original distribution.

           b) accompany the distribution with the machine-readable source of
          the software.

           c) give non-standard binaries non-standard names, with
              instructions on where to get the original software distribution.

           d) make other distribution arrangements with the author.

      4. You may modify and include the part of the software into any other
         software (possibly commercial).  But some files in the distribution
         are not written by the author, so that they are not under these terms.

         For the list of those files and their copying conditions, see the
         file LEGAL.

      5. The scripts and library files supplied as input to or produced as
         output from the software do not automatically fall under the
         copyright of the software, but belong to whomever generated them,
         and may be sold commercially, and may be aggregated with this
         software.

      6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
         IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
         PURPOSE.

lib/yard/server/http_utils.rb:

   This file is vendored and slightly modified from WEBrick because it was
   removed from Ruby core in Ruby 3.x.

      Copyright (C) 1993-2013 Yukihiro Matsumoto. All rights reserved.

      Redistribution and use in source and binary forms, with or without
      modification, are permitted provided that the following conditions
      are met:
      1. Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
      2. Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.

      THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
      ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
      IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
      ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
      FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
      DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
      OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
      LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
      OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
      SUCH DAMAGE.
yard-0.9.37/LICENSE000066400000000000000000000020441466601756300135740ustar00rootroot00000000000000Copyright (c) 2007-2022 Loren Segal

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.
yard-0.9.37/README.md000066400000000000000000000325471466601756300140610ustar00rootroot00000000000000# YARD: Yay! A Ruby Documentation Tool

[![Homepage](https://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
[![GitHub](https://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
[![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)

[![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)
[![Unit Tests](https://github.com/lsegal/yard/actions/workflows/ci.yml/badge.svg)](https://github.com/lsegal/yard/actions/workflows/ci.yml)
[![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)
[![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)

## Synopsis

YARD is a documentation generation tool for the Ruby programming language. It
enables the user to generate consistent, usable documentation that can be
exported to a number of formats very easily, and also supports extending for
custom Ruby constructs such as custom class level definitions. Below is a
summary of some of YARD's notable features.

## Feature List

**1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible
with RDoc formatting. In fact, YARD does no processing on RDoc documentation
strings, and leaves this up to the output generation tool to decide how to
render the documentation.

**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other
languages**: YARD uses a '@tag' style definition syntax for meta tags alongside
regular code documentation. These tags should be able to happily sit side by
side RDoc formatted documentation, but provide a much more consistent and usable
way to describe important information about objects, such as what parameters
they take and what types they are expected to be, what type a method should
return, what exceptions it can raise, if it is deprecated, etc.. It also allows
information to be better (and more consistently) organized during the output
generation phase. You can find a list of tags in the {file:docs/Tags.md#taglist
Tags.md} file.

YARD also supports an optional "types" declarations for certain tags. This
allows the developer to document type signatures for ruby methods and parameters
in a non intrusive but helpful and consistent manner. Instead of describing this
data in the body of the description, a developer may formally declare the
parameter or return type(s) in a single line. Consider the following method
documented with YARD formatting:

```ruby
# Reverses the contents of a String or IO object.
#
# @param contents [String, #read] the contents to reverse
# @return [String] the contents reversed lexically
def reverse(contents)
  contents = contents.read if contents.respond_to? :read
  contents.reverse
end
```

With the above @param tag, we learn that the contents parameter can either be a
String or any object that responds to the 'read' method, which is more powerful
than the textual description, which says it should be an IO object. This also
informs the developer that they should expect to receive a String object
returned by the method, and although this may be obvious for a 'reverse' method,
it becomes very useful when the method name may not be as descriptive.

**3. Custom Constructs and Extensibility of YARD**: YARD is designed to be
extended and customized by plugins. Take for instance the scenario where you
need to document the following code:

```ruby
class List
 # Sets the publisher name for the list.
 cattr_accessor :publisher
end
```

This custom declaration provides dynamically generated code that is hard for a
documentation tool to properly document without help from the developer. To ease
the pains of manually documenting the procedure, YARD can be extended by the
developer to handle the `cattr_accessor` construct and automatically create an
attribute on the class with the associated documentation. This makes documenting
external API's, especially dynamic ones, a lot more consistent for consumption
by the users.

YARD is also designed for extensibility everywhere else, allowing you to add
support for new programming languages, new data structures and even where/how
data is stored.

**4. Raw Data Output**: YARD also outputs documented objects as raw data (the
dumped Namespace) which can be reloaded to do generation at a later date, or
even auditing on code. This means that any developer can use the raw data to
perform output generation for any custom format, such as YAML, for instance.
While YARD plans to support XHTML style documentation output as well as command
line (text based) and possibly XML, this may still be useful for those who would
like to reap the benefits of YARD's processing in other forms, such as throwing
all the documentation into a database. Another useful way of exploiting this raw
data format would be to write tools that can auto generate test cases, for
example, or show possible unhandled exceptions in code.

**5. Local Documentation Server**: YARD can serve documentation for projects or
installed gems (similar to `gem server`) with the added benefit of dynamic
searching, as well as live reloading. Using the live reload feature, you can
document your code and immediately preview the results by refreshing the page;
YARD will do all the work in re-generating the HTML. This makes writing
documentation a much faster process.

## Installing

To install YARD, use the following command:

```sh
$ gem install yard
```

(Add `sudo` if you're installing under a POSIX system as root)

Alternatively, if you've checked the source out directly, you can call
`rake install` from the root project directory.

**Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
install lacks RDoc, which is occasionally used by YARD to convert markup to
HTML. If running `which rdoc` turns up empty, install RDoc by issuing:

```sh
$ sudo apt-get install rdoc
```

### Markdown parser

When rendering markdown, yard will use one of several possible markdown providers,
[in order of priority](https://github.com/lsegal/yard/blob/e833aac7a01510245dd4ae1d1d18b046c8293c2d/lib/yard/templates/helpers/markup_helper.rb#L26-L33).
If you are experiencing rendering bugs (example [1](https://github.com/lsegal/yard/issues/1410) [2](https://github.com/lsegal/yard/issues/1543)), try adding one of the
gems further up in the list to your Gemfile.

## Usage

There are a couple of ways to use YARD. The first is via command-line, and the
second is the Rake task.

**1. yard Command-line Tool**

YARD comes packaged with a executable named `yard` which can control the many
functions of YARD, including generating documentation, graphs running the YARD
server, and so on. To view a list of available YARD commands, type:

```sh
$ yard --help
```

Plugins can also add commands to the `yard` executable to provide extra
functionality.

### Generating Documentation

The `yardoc` executable is a shortcut for `yard doc`.

The most common command you will probably use is `yard doc`, or `yardoc`. You
can type `yardoc --help` to see the options that YARD provides, but the easiest
way to generate docs for your code is to simply type `yardoc` in your project
root. This will assume your files are located in the `lib/` directory. If they
are located elsewhere, you can specify paths and globs from the commandline via:

```sh
$ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
```

The tool will generate a `.yardoc` file which will store the cached database of
your source code and documentation. If you want to re-generate your docs with
another template you can simply use the `--use-cache` (or -c) option to speed up
the generation process by skipping source parsing.

YARD will by default only document code in your public visibility. You can
document your protected and private code by adding `--protected` or `--private`
to the option switches. In addition, you can add `--no-private` to also ignore
any object that has the `@private` meta-tag. This is similar to RDoc's ":nodoc:"
behaviour, though the distinction is important. RDoc implies that the object
with :nodoc: would not be documented, whereas YARD still recommends documenting
private objects for the private API (for maintainer/developer consumption).

You can also add extra informative files (README, LICENSE) by separating the
globs and the filenames with '-'.

```sh
$ yardoc 'app/**/*.rb' - README LICENSE FAQ
```

If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is used:

```sh
$ yardoc - README LICENSE FAQ
```

Note that the README file can be specified with its own `--readme` switch.

You can also add a `.yardopts` file to your project directory which lists the
switches separated by whitespace (newlines or space) to pass to yardoc whenever
it is run. A full overview of the `.yardopts` file can be found in
[YARD::CLI::Yardoc](https://rubydoc.info/gems/yard/YARD/CLI/Yardoc#label-Options+File+-28.yardopts-29).

### Queries

The `yardoc` tool also supports a `--query` argument to only include objects
that match a certain data or meta-data query. The query syntax is Ruby, though a
few shortcuts are available. For instance, to document only objects that have an
"@api" tag with the value "public", all of the following syntaxes would give the
same result:

```sh
--query '@api.text == "public"'
--query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
--query 'has_tag?(:api) && tag(:api).text == "public"'
```

Note that the "@tag" syntax returns the first tag named "tag" on the object. To
return the array of all tags named "tag", use "@@tag".

Multiple `--query` arguments are allowed in the command line parameters. The
following two lines both check for the existence of a return and param tag:

```sh
--query '@return' --query '@param'
--query '@return && @param'
```

For more information about the query syntax, see the {YARD::Verifier} class.

**2. Rake Task**

The second most obvious is to generate docs via a Rake task. You can do this by
adding the following to your `Rakefile`:

```ruby
require 'yard'

YARD::Rake::YardocTask.new do |t|
 t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
 t.options = ['--any', '--extra', '--opts'] # optional
 t.stats_options = ['--list-undoc']         # optional
end
```

All the settings: `files`, `options` and `stats_options` are optional. `files`
will default to `lib/**/*.rb`, `options` will represents any options you might
want to add and `stats_options` will pass extra options to the stats command.
Again, a full list of options is available by typing `yardoc --help` in a shell.
You can also override the options at the Rake command-line with the OPTS
environment variable:

```sh
$ rake yard OPTS='--any --extra --opts'
```

**3. `yri` RI Implementation**

The yri binary will use the cached .yardoc database to give you quick ri-style
access to your documentation. It's way faster than ri but currently does not
work with the stdlib or core Ruby libraries, only the active project. Example:

```sh
$ yri YARD::Handlers::Base#register
$ yri File.relative_path
```

Note that class methods must not be referred to with the "::" namespace
separator. Only modules, classes and constants should use "::".

You can also do lookups on any installed gems. Just make sure to build the
.yardoc databases for installed gems with:

```sh
$ yard gems
```

If you don't have sudo access, it will write these files to your `~/.yard`
directory. `yri` will also cache lookups there.

**4. `yard server` Documentation Server**

The `yard server` command serves documentation for a local project or all
installed RubyGems. To serve documentation for a project you are working on,
simply run:

```sh
$ yard server
```

And the project inside the current directory will be parsed (if the source has
not yet been scanned by YARD) and served at
[http://localhost:8808](http://localhost:8808).

### Live Reloading

If you want to serve documentation on a project while you document it so that
you can preview the results, simply pass `--reload` (`-r`) to the above command
and YARD will reload any changed files on each request. This will allow you to
change any documentation in the source and refresh to see the new contents.

### Serving Gems

To serve documentation for all installed gems, call:

```sh
$ yard server --gems
```

This will also automatically build documentation for any gems that have not been
previously scanned. Note that in this case there will be a slight delay between
the first request of a newly parsed gem.

**5. `yard graph` Graphviz Generator**

You can use `yard graph` to generate dot graphs of your code. This, of course,
requires [Graphviz](http://www.graphviz.org) and the `dot` binary. By default
this will generate a graph of the classes and modules in the best UML2 notation
that Graphviz can support, but without any methods listed. With the `--full`
option, methods and attributes will be listed. There is also a `--dependencies`
option to show mixin inclusions. You can output to stdout or a file, or pipe
directly to `dot`. The same public, protected and private visibility rules apply
to `yard graph`. More options can be seen by typing `yard graph --help`, but
here is an example:

```sh
$ yard graph --protected --full --dependencies
```

## Changelog

See {file:CHANGELOG.md} for a list of changes.

## License

YARD © 2007-2020 by [Loren Segal](mailto:lsegal@soen.ca). YARD is licensed
under the MIT license except for some files which come from the RDoc/Ruby
distributions. Please see the {file:LICENSE} and {file:LEGAL} documents for more
information.
yard-0.9.37/Rakefile000066400000000000000000000015741466601756300142430ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/lib/yard'
require File.dirname(__FILE__) + '/lib/yard/rubygems/specification'
require 'rbconfig'

YARD::VERSION.replace(ENV['YARD_VERSION']) if ENV['YARD_VERSION']

Dir['tasks/**/*.rake'].each { |task_file| load task_file }

desc "Builds the gem"
task :gem do
  sh "gem build yard.gemspec"
end

desc "Installs the gem"
task :install => :gem do
  sh "gem install yard-#{YARD::VERSION}.gem --no-document"
end

begin
  require 'rspec/core/rake_task'
  RSpec::Core::RakeTask.new(:spec)
rescue LoadError
  nil # noop
end

desc "Generate documentation for Yard, and fail if there are any warnings"
task :test_doc do
  sh "ruby bin/yard --fail-on-warning #{"--no-progress" if ENV["CI"]}"
end

task :default => [:spec, :test_doc]

YARD::Rake::YardocTask.new do |t|
  t.options += ['--title', "YARD #{YARD::VERSION} Documentation"]
end
yard-0.9.37/SECURITY.md000066400000000000000000000017741466601756300143710ustar00rootroot00000000000000# Security Policy

## Supported Versions

The following versions are supported with security patches for
any reported vulnerabilities in YARD or dependent software.

| Version | Supported          |
| ------- | ------------------ |
| 0.9.x   | :white_check_mark: |
| < 0.9   | :x:                |

## Reporting a Vulnerability

If you've discovered a vulnerability in YARD source code, please email
lsegal@soen.ca with as much information as possible. You should typically
receive a response within 24-48 hours, though depending on scheduling
it may take up to a week to respond. If you do not get a response on
your initial email within a few days, please re-send your email or
reach out on other channels (such as yardoc@googlegroups.com) to
try to get a hold of a maintainer. Please do not include sensitive
material if you are reaching out through secondary channels unless
you first receive confirmation that it is okay.

Thank you for your help and cooperation in making YARD a stable and
safe piece of software.
yard-0.9.37/benchmarks/000077500000000000000000000000001466601756300147045ustar00rootroot00000000000000yard-0.9.37/benchmarks/builtins_vs_eval.rb000066400000000000000000000017301466601756300206020ustar00rootroot00000000000000# frozen_string_literal: true
require 'benchmark'
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')

TIMES = (ARGV[0] || 10_000).to_i

def bench_builtins(name)
  YARD::CodeObjects::BUILTIN_EXCEPTIONS_HASH.key? name
end

def bench_eval(name)
  eval(name).is_a?(Class)
rescue
  false
end

Benchmark.bmbm do |b|
  b.report("builtins PASS") { TIMES.times { YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_builtins(y) } } }
  b.report("eval PASS") { TIMES.times { YARD::CodeObjects::BUILTIN_EXCEPTIONS.each {|y| bench_eval(y) } } }
  b.report("builtins FAIL") { TIMES.times { YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_builtins(y) } } }
  b.report("eval FAIL") { TIMES.times { YARD::CodeObjects::BUILTIN_MODULES.each {|y| bench_eval(y) } } }
  b.report("builtins ANY") { TIMES.times { YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_builtins(y) } } }
  b.report("eval ANY") { TIMES.times { YARD::CodeObjects::BUILTIN_CLASSES.each {|y| bench_eval(y) } } }
end
yard-0.9.37/benchmarks/concat_vs_join.rb000066400000000000000000000005601466601756300202300ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"

STR1 = "Hello"
JOIN = "::"
STR2 = "World"

TESTS = 100_000
Benchmark.bmbm do |results|
  results.report("concat") { TESTS.times { "".concat(STR1).concat(JOIN).concat(STR2) } }
  results.report("add   ") { TESTS.times { STR1 + JOIN + STR2 } }
  results.report("join  ") { TESTS.times { [STR1, STR2].join(JOIN) } }
end
yard-0.9.37/benchmarks/erb_vs_erubis.rb000066400000000000000000000022121466601756300200570ustar00rootroot00000000000000# frozen_string_literal: true
require 'rubygems'
require 'erubis'
require 'erubis/tiny'
require 'erb'
require "benchmark"
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')

def rungen
  YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
  YARD::Registry.at("YARD::CodeObjects::Base").format(:format => :html)
end

Benchmark.bmbm do |x|
  x.report("erubis") do
    eval <<-eof
      module YARD; module Templates; module Template
        def erb_with(str, x) Erubis::Eruby.new(str) end
      end end end
    eof

    rungen
  end

  x.report("fast-erubis") do
    eval <<-eof
      module YARD; module Templates; module Template
        def erb_with(str, x) Erubis::FastEruby.new(str) end
      end end end
    eof

    rungen
  end

  x.report("tiny-erubis") do
    eval <<-eof
      module YARD; module Templates; module Template
        def erb_with(str, x) Erubis::TinyEruby.new(str) end
      end end end
    eof

    rungen
  end

  x.report("erb") do
    eval <<-eof
       module YARD; module Templates; module Template
        def erb_with(str, x) ERB.new(str) end
      end end end
    eof

    rungen
  end
end
yard-0.9.37/benchmarks/format_args.rb000066400000000000000000000023771466601756300175460ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"
require 'lib/yard'

def format_args_regex(object)
  if object.signature
    object.signature[/#{Regexp.quote object.name.to_s}\s*(.*)/, 1]
  else
    ""
  end
end

def format_args_parameters(object)
  if !object.parameters.empty?
    args = object.parameters.map {|n, v| v ? "#{n} = #{v}" : n.to_s }.join(", ")
    "(#{args})"
  else
    ""
  end
end

YARD::Registry.load
$object = YARD::Registry.at('YARD::Generators::Base#G')

log.puts "regex:  " + format_args_regex($object)
log.puts "params: " + format_args_parameters($object)
log.puts

TIMES = 100_000
Benchmark.bmbm do |x|
  x.report("regex")      { TIMES.times { format_args_regex($object) } }
  x.report("parameters") { TIMES.times { format_args_parameters($object) } }
end

=begin LAST RUN Jun 23 2008
regex:  (generator, opts = {})
params: (generator, opts = {})

Rehearsal ----------------------------------------------
regex        1.270000   0.020000   1.290000 (  1.294558)
parameters   0.690000   0.000000   0.690000 (  0.693324)
------------------------------------- total: 1.980000sec

                 user     system      total        real
regex        1.260000   0.010000   1.270000 (  1.268214)
parameters   0.670000   0.000000   0.670000 (  0.679114)
=end
yard-0.9.37/benchmarks/generation.rb000066400000000000000000000022171466601756300173660ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')

unless YARD::CodeObjects::Proxy.private_instance_methods.include?('to_obj')
  raise "This benchmark is dependent on YARD::CodeObjects::Proxy#to_obj"
end

def rungen
  YARD::Registry.clear
  YARD::CLI::Yardoc.run('--quiet', '--use-cache')
end

def redef(lock = false)
  eval <<-eof
    class YARD::CodeObjects::Proxy;
      def to_obj
        @obj #{lock ? '||' : ''}= YARD::Registry.resolve(@namespace, @name)
      end
    end
  eof
end

Benchmark.bmbm do |x|
  x.report("gen-w/o-locking")  { redef;       rungen }
  x.report("gen-with-locking") { redef(true); rungen }
end

=begin Results from 2008-06-07
Rehearsal ----------------------------------------------------
gen-w/o-locking    9.650000   0.450000  10.100000 ( 10.150556)
gen-with-locking   7.790000   0.400000   8.190000 (  8.373811)
------------------------------------------ total: 18.290000sec

                       user     system      total        real
gen-w/o-locking    9.820000   0.430000  10.250000 ( 10.293283)
gen-with-locking   7.820000   0.380000   8.200000 (  8.243326)
=end
yard-0.9.37/benchmarks/marshal_vs_dbm.rb000066400000000000000000000035571466601756300202240ustar00rootroot00000000000000# frozen_string_literal: true
require 'benchmark'
require 'dbm'

MARSHAL_FILE = "marshal_test.db"
DBM_FILE = "dbm_test"
WRITE_TIMES = 1
READ_TIMES = 100
NUM_INDICES = 10_000
INDICES = ['33', '857', '5022', '8555']

def generate_index
  '0' * (rand * 4096).floor
end

def write_dbm
  File.unlink(DBM_FILE + ".db") if File.exist?(DBM_FILE + ".db")
  handle = DBM.new(DBM_FILE)
  NUM_INDICES.times {|t| handle[t.to_s] = Marshal.dump(generate_index) }
  handle.close
end

def read_dbm
  db = DBM.open(DBM_FILE)
  INDICES.each {|index| Marshal.load(db[index]) }
  db.close
end

def write_marshal
  File.unlink(MARSHAL_FILE) if File.exist?(MARSHAL_FILE)
  handle = {}
  NUM_INDICES.times {|t| handle[t.to_s] = generate_index }
  File.open(MARSHAL_FILE, "wb") {|f| f.write(Marshal.dump(handle)) }
end

def read_marshal
  db = Marshal.load(File.read(MARSHAL_FILE))
  INDICES.each {|index| db[index] }
end

Benchmark.bmbm do |x|
  x.report("marshal-write") { WRITE_TIMES.times { write_marshal } }
  x.report("dbm-write") { WRITE_TIMES.times { write_dbm } }
  x.report("marshal-read ") { READ_TIMES.times { read_marshal } }
  x.report("dbm-read ") { READ_TIMES.times { read_dbm } }
end

File.unlink(MARSHAL_FILE)
File.unlink(DBM_FILE + ".db")

__END__

Rehearsal -------------------------------------------------
marshal-write   0.090000   0.070000   0.160000 (  0.465820)
dbm-write       0.560000   0.570000   1.130000 (  3.045556)
marshal-read    4.640000   3.180000   7.820000 (  7.821978)
dbm-read        0.020000   0.020000   0.040000 (  0.070920)
---------------------------------------- total: 9.150000sec

                    user     system      total        real
marshal-write   0.080000   0.050000   0.130000 (  0.436561)
dbm-write       0.560000   0.550000   1.110000 (  2.030530)
marshal-read    4.670000   3.180000   7.850000 (  7.842232)
dbm-read        0.010000   0.020000   0.030000 (  0.053928)
yard-0.9.37/benchmarks/parsing.rb000066400000000000000000000030411466601756300166720ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"
require 'yard'

PATH_ORDER = [
  'lib/yard/autoload.rb',
  'lib/yard/code_objects/base.rb',
  'lib/yard/code_objects/namespace_object.rb',
  'lib/yard/handlers/base.rb',
  'lib/yard/generators/helpers/*.rb',
  'lib/yard/generators/base.rb',
  'lib/yard/generators/method_listing_generator.rb',
  'lib/yard/serializers/base.rb',
  'lib/**/*.rb'
]

Benchmark.bmbm do |x|
  x.report("parse in order") { YARD::Registry.clear; YARD.parse PATH_ORDER, [], YARD::Logger::ERROR }
  x.report("parse") { YARD::Registry.clear; YARD.parse 'lib/**/*.rb', [], YARD::Logger::ERROR }
end

=begin
load_order branch (2008-06-07):

Rehearsal --------------------------------------------------
parse in order   6.510000   0.050000   6.560000 (  6.563223)
parse            6.300000   0.040000   6.340000 (  6.362272)
---------------------------------------- total: 12.900000sec

                     user     system      total        real
parse in order   6.310000   0.060000   6.370000 (  6.390945)
parse            6.300000   0.050000   6.350000 (  6.366709)


api_changes branch before merge (2008-06-07)

Rehearsal --------------------------------------------------
parse in order   6.330000   0.050000   6.380000 (  6.397552)
parse            6.380000   0.050000   6.430000 (  6.446954)
---------------------------------------- total: 12.810000sec

                     user     system      total        real
parse in order   6.320000   0.040000   6.360000 (  6.394460)
parse            6.040000   0.040000   6.080000 (  6.099738)
=end
yard-0.9.37/benchmarks/pathname_vs_string.rb000066400000000000000000000035751466601756300211360ustar00rootroot00000000000000# frozen_string_literal: true
require 'pathname'
require "benchmark"
require File.dirname(__FILE__) + '/../lib/yard'

pathobj = Pathname.new("a/b/c")
strobj  = "a/b/c"

TIMES = 1_000

log.puts "join:"
Benchmark.bmbm do |x|
  x.report("pathname") { TIMES.times { Pathname.new("a/b/c").join("d", "e", "f") } }
  x.report("string  ") { TIMES.times { File.join("a/b/c", "d", "e", "f") } }
  x.report("pathname-sameobject") { TIMES.times { pathobj.join("d", "e", "f") } }
  x.report("string-sameobject  ") { TIMES.times { File.join(strobj, "d", "e", "f") } }
end

log.puts
log.puts
log.puts "cleanpath:"
Benchmark.bmbm do |x|
  x.report("pathname") { TIMES.times { Pathname.new("a/b//.././c").cleanpath } }
  x.report("string  ") { TIMES.times { File.cleanpath("a/b//.././c") } }
end

__END__
join:
Rehearsal -------------------------------------------------------
pathname              0.330000   0.020000   0.350000 (  0.353481)
string                0.010000   0.000000   0.010000 (  0.001390)
pathname-sameobject   0.360000   0.020000   0.380000 (  0.384473)
string-sameobject     0.000000   0.000000   0.000000 (  0.001187)
---------------------------------------------- total: 0.740000sec

                          user     system      total        real
pathname              0.330000   0.020000   0.350000 (  0.350820)
string                0.000000   0.000000   0.000000 (  0.001055)
pathname-sameobject   0.330000   0.010000   0.340000 (  0.346949)
string-sameobject     0.000000   0.000000   0.000000 (  0.001141)


cleanpath:
Rehearsal --------------------------------------------
pathname   0.060000   0.000000   0.060000 (  0.059767)
string     0.010000   0.000000   0.010000 (  0.013775)
----------------------------------- total: 0.070000sec

               user     system      total        real
pathname   0.060000   0.000000   0.060000 (  0.059697)
string     0.020000   0.000000   0.020000 (  0.013624)yard-0.9.37/benchmarks/rdoc_vs_yardoc.rb000066400000000000000000000012001466601756300202220ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"

files = Dir.glob(File.dirname(__FILE__) + '/../lib/**/*.rb').join(" ")
Benchmark.bmbm do |x|
  x.report("rdoc") { `rm -rf rdoc && rdoc -q -o rdoc #{files} && rm -rf rdoc` }
  x.report("yardoc") { `rm -rf yard && ./bin/yardoc -q -o yard #{files} && rm -rf yard` }
  x.report("yardoc-cached") { `rm -rf yard && ./bin/yardoc -c -q -o yard #{files} && rm -rf yard` }
  x.report("yardoc-legacy") { `rm -rf yard && ./bin/yardoc --legacy -q -o yard #{files} && rm -rf yard` }
  x.report("yardoc-legacy-cached") { `rm -rf yard && ./bin/yardoc --legacy -c -q -o yard #{files} && rm -rf yard` }
end
yard-0.9.37/benchmarks/registry_store_types.rb000066400000000000000000000030141466601756300215370ustar00rootroot00000000000000# frozen_string_literal: true
require 'benchmark'
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')

def parse_and_select_objects
  YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
  YARD::Registry.load_all
  $paths = []
  4.times { $paths << YARD::Registry.paths[rand(YARD::Registry.paths.size)] }

  $regular_registry = {}
  $types_registry = {}
  YARD::Registry.all.each do |object|
    $regular_registry[object.path] = object
    ($types_registry[object.type] ||= {})[object.path] = object
  end
end

def run_lookup
  $paths.select {|path| $regular_registry[path] }
end

def run_lookup_with_types
  $paths.select {|path| $types_registry.values.find {|list| list[path] } }
end

TIMES = 100_000

parse_and_select_objects
p $paths
Benchmark.bmbm do |x|
  x.report("normal") { TIMES.times { run_lookup } }
  x.report("types")  { TIMES.times { run_lookup_with_types } }
end

__END__
# Run on March 22 2012
["YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar#initialize",
  "YARD::Parser::C::CParser#enumerator",
  "YARD::CodeObjects::ClassObject#inherited_meths",
  "YARD::Parser::C::Statement#source="]
Rehearsal ----------------------------------------------
normal       0.180000   0.000000   0.180000 (  0.182640)
types        1.150000   0.010000   1.160000 (  1.160219)
------------------------------------- total: 1.340000sec

                 user     system      total        real
normal       0.170000   0.000000   0.170000 (  0.165621)
types        1.140000   0.000000   1.140000 (  1.142269)
yard-0.9.37/benchmarks/ri_vs_yri.rb000066400000000000000000000011121466601756300172310ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"

TIMES = 10
Benchmark.bmbm do |x|
  x.report("ri") { TIMES.times { `ri -T YARD::Tags::Library` } }
  x.report("yri") { TIMES.times { `./bin/yri -T YARD::Tags::Library` } }
end

__END__

Rehearsal ---------------------------------------
ri    0.000000   0.020000   6.880000 (  6.929591)
yri   0.000000   0.000000   1.060000 (  1.074840)
------------------------------ total: 7.940000sec

          user     system      total        real
ri    0.000000   0.020000   6.850000 (  6.871660)
yri   0.000000   0.010000   1.060000 (  1.067585)
yard-0.9.37/benchmarks/ripper_parser.rb000066400000000000000000000010461466601756300201070ustar00rootroot00000000000000# encoding: utf-8
# frozen_string_literal: true
require 'benchmark'
require File.dirname(__FILE__) + '/../lib/yard'

$files = Dir[File.dirname(__FILE__) + '/../lib/**/*.rb'].map {|f| File.read(f) }
$files_rip = Dir[File.dirname(__FILE__) + '/../lib/**/*.rb'].map {|f| [File.read(f), f] }

TIMES = 2
Benchmark.bmbm do |x|
  x.report("rip-parser") { TIMES.times { $files_rip.each {|f| YARD::Parser::Ruby::RubyParser.parse(*f) } } }
  x.report("yard-parser  ") { TIMES.times { $files.each {|f| YARD::Parser::Ruby::Legacy::StatementList.new(f) } } }
end
yard-0.9.37/benchmarks/splat_vs_flatten.rb000066400000000000000000000006071466601756300206040ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"

# To prove that flattening a small list is not significantly slower than
# calling *list (used to get around create_tag list issue)
$a = "FOO BAR BAZ"
def foo(*args) args.last.inspect end

TESTS = 10_000
Benchmark.bmbm do |x|
  x.report("splat") { TESTS.times { foo(*$a) } }
  x.report("flatten") { TESTS.times { foo(*[$a].flatten) } }
end
yard-0.9.37/benchmarks/struct_vs_ostruct.rb000066400000000000000000000017521466601756300210550ustar00rootroot00000000000000require 'benchmark'
require 'ostruct'
require_relative '../lib/yard'

n = 100000
class MyStruct < Struct.new(:a, :b, :c); end
ostruct = OpenStruct.new
yostruct = YARD::OpenStruct.new
mystruct = MyStruct.new

Benchmark.bmbm do |x|
  x.report("Struct.new(args)") { n.times { MyStruct.new 1, 2, 3 } }
  x.report("Struct (assign)") { n.times { mystruct.a = 1 } }
  x.report("Struct (read)") { n.times { mystruct.a } }
  x.report("OpenStruct.new(args)") { n.times { OpenStruct.new a: 1, b: 2, c: 3 } }
  x.report("OpenStruct.new (blank)") { n.times { OpenStruct.new } }
  x.report("OpenStruct (assign)") { n.times { ostruct.a = 1 } }
  x.report("OpenStruct (read)") { n.times { ostruct.a } }
  x.report("YARD::OpenStruct.new(args)") { n.times { YARD::OpenStruct.new a: 1, b: 2, c: 3 } }
  x.report("YARD::OpenStruct.new (blank)") { n.times { YARD::OpenStruct.new } }
  x.report("YARD::OpenStruct (assign)") { n.times { yostruct.a = 1 } }
  x.report("YARD::OpenStruct (read)") { n.times { yostruct.a } }
end
yard-0.9.37/benchmarks/template_erb.rb000066400000000000000000000012531466601756300176750ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')

YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
obj = YARD::Registry.at("YARD::CodeObjects::Base")

TIMES = 3
Benchmark.bm do |x|
  x.report("trim-line") { TIMES.times { obj.format(:format => :html) } }
  module YARD
    module Templates
      module Template
        def erb(section, &block)
          erb = ERB.new(cache(section))
          erb.filename = cache_filename(section).to_s
          erb.result(binding, &block)
        end
      end
    end
  end
  x.report("no-trim  ") { TIMES.times { obj.format(:format => :html) } }
end
yard-0.9.37/benchmarks/template_format.rb000066400000000000000000000004601466601756300204140ustar00rootroot00000000000000# frozen_string_literal: true
require "benchmark"
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')

YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
obj = YARD::Registry.at("YARD::CodeObjects::Base")
log.puts Benchmark.measure { obj.format(:format => :html) }
yard-0.9.37/benchmarks/template_profile.rb000066400000000000000000000007711466601756300205710ustar00rootroot00000000000000# frozen_string_literal: true
require 'rubygems'
require 'ruby-prof'
# require 'benchmark'
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')

YARD::Registry.load_yardoc(File.join(File.dirname(__FILE__), '..', '.yardoc'))
obj = YARD::Registry.at("YARD::CodeObjects::Base")

# PerfTools::CpuProfiler.start("template_profile") do
# end

result = RubyProf.profile do
  obj.format(:format => :html, :no_highlight => true)
end

printer = RubyProf::CallTreePrinter.new(result)
printer.print(STDOUT)
yard-0.9.37/benchmarks/yri_cache.rb000066400000000000000000000006621466601756300171630ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/../lib/yard"
require "benchmark"
include YARD::CLI

class YARD::CLI::YRI
  def print_object(object) end
end

def remove_cache
  File.unlink(YRI::CACHE_FILE)
end

TIMES = 10
NAME = 'YARD'
remove_cache; YRI.run(NAME)
Benchmark.bmbm do |x|
  x.report("cache   ") { TIMES.times { YRI.run(NAME) } }
  x.report("no-cache") { TIMES.times { remove_cache; YRI.run(NAME) } }
end
yard-0.9.37/bin/000077500000000000000000000000001466601756300133375ustar00rootroot00000000000000yard-0.9.37/bin/yard000077500000000000000000000005421466601756300142250ustar00rootroot00000000000000#!/usr/bin/env ruby
# frozen_string_literal: true

# We do all this work just to find the proper load path
path = __FILE__
while File.symlink?(path)
  path = File.expand_path(File.readlink(path), File.dirname(path))
end
$LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))

require 'yard'

YARD::CLI::CommandParser.run(*ARGV)
yard-0.9.37/bin/yardoc000077500000000000000000000005331466601756300145470ustar00rootroot00000000000000#!/usr/bin/env ruby
# frozen_string_literal: true

# We do all this work just to find the proper load path
path = __FILE__
while File.symlink?(path)
  path = File.expand_path(File.readlink(path), File.dirname(path))
end
$LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))

require 'yard'

YARD::CLI::Yardoc.run(*ARGV)
yard-0.9.37/bin/yri000077500000000000000000000005301466601756300140660ustar00rootroot00000000000000#!/usr/bin/env ruby
# frozen_string_literal: true

# We do all this work just to find the proper load path
path = __FILE__
while File.symlink?(path)
  path = File.expand_path(File.readlink(path), File.dirname(path))
end
$LOAD_PATH.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))

require 'yard'

YARD::CLI::YRI.run(*ARGV)
yard-0.9.37/docs/000077500000000000000000000000001466601756300135175ustar00rootroot00000000000000yard-0.9.37/docs/CodeObjects.md000066400000000000000000000131001466601756300162200ustar00rootroot00000000000000# @title CodeObjects Architecture

# CodeObjects Architecture

Code objects are Ruby objects that describe the code being documented. For instance,
all classes, modules, methods, etc. are all extracted from the Ruby source as code
objects. All of these code objects extend from the {YARD::CodeObjects::Base} class, which
provides basic attributes like source location, source code, name and path.

## CodeObjects Organization

Code objects are divided into two basic types. {YARD::CodeObjects::NamespaceObject NamespaceObjects}
and non-namespace objects. A namespace object refers to any object in Ruby that can have
other objects defined inside of it. In the context of Ruby, this specifically means
modules and classes (both of which are subclasses of `NamespaceObject`). These objects
act like tree structures, maintaining a list of all of their direct children. All non
namespace objects are simply subclasses of the Base class. The {YARD::CodeObjects::RootObject RootObject}
is a special kind of `NamespaceObject` which refers to the top level namespace in Ruby.
Methods that accept a namespace object as a parameter should also accept the symbol
`:root` as a shortcut for the root object.

The following is an overview of the classes within the `CodeObjects` namespace:

![CodeObjects Class Diagram](images/code-objects-class-diagram.png)

## Unique Path Representation

All CodeObjects are uniquely defined by their implementation of {YARD::CodeObjects::Base#path}.
This path is used to locate or store a code object in the {YARD::Registry}. It is therefore
essential that any Base subclass return a unique String value for #path so that the
object may co-exist with other objects in the Registry.

In practice, a path is simply the conventional Ruby representation of a class,
module, constant, class variable or method. For example, the following objects
would have the following respective paths:

* Class `Klass` inside module `Mod`: `Mod::Klass`
* Instance method `bar` inside class `Foo`: `Foo#bar`
* Class method `bar` inside class `Foo`: `Foo.bar`
* Constant `VERSION` inside class `YARD`: `YARD::VERSION`
* Class variable `@@abc` inside class `A`: `A::@@abc`

## Registry

CodeObjects classes are coupled with the {YARD::Registry} class which keeps track of
all instantiated code objects. This is an explicit design choice to allow objects
to be fetched, cached, imported and exported from a centralized location. As mentioned
above, this coupling is a result of the fact that each object is uniquely identified by
its path, which is used to implement lookups. You can read more about the registry
in the {YARD::Registry} class.

## Identity Map

Code objects are instantiated using an identity-map like implementation that guarantees
only one unique Ruby object exists for an object described by a specific path. This
allows developers to create a code object without checking if it already exists in
the {YARD::Registry}. The following example will only create one object:

    id = ClassObject.new(:root, "MyClass").object_id #=> 13352
    ClassObject.new(:root, "MyClass").object_id #=> 13352

## Proxy Objects

In addition to providing access to existing objects, a {YARD::CodeObjects::Proxy}
class exists which can represent an object at a path that may or may not have been
created. This is necessary to represent a reference to an object in code that is
never defined in the same body of source code, or perhaps defined later. If any
attributes of a proxy are accessed, it will immediately be resolved to the object
at its declared path. In the case where such an object exists, it will act as
a delegate to the object. However, if the object does not exist, a warning will
be raised. Whenever arbitrary code objects are used, care should be taken in
order to make sure attributes are not accessed on unresolvable proxies. An
unresolvable proxy will return a class name of `Proxy` and #type of `:proxy`,
for example:

    P(:InvalidObject).type == :proxy  #=> true
    P(:InvalidObject).is_a?(Proxy)    #=> true

## Adding Data to Code Objects

Code objects act as hash-like structures that allow any arbitrary value to be set.
This allows easy extending of existing objects without creating custom subclasses.
For instance, to add a timestamp to a method object (when it was modified, maybe),
it is possible to simply do:

    object = MethodObject.new(:root, "my_method")
    object[:modified_at] = Time.now

This value can now be retrieved on this object both by the hash `[]` syntax as
well as like any other method:

    object.modified_at #=> 2009-06-03 20:08:46 -0400

## Creating a Custom CodeObject

It should first be mentioned that creating a custom code object should not be
necessary in most cases, except when functionality that cannot be represented
by classical Ruby objects is added. A good example *might* be a test class,
which although is technically a Ruby class, has a significantly different purpose
in documentation and needs a different set of metadata, as well as its own
representation in documentation.

The {YARD::CodeObjects::Base#path} implementation is the most important part of the
code object architecture. The first thing any custom code object must guarantee is
that its path value is unique among all other objects. The recommended way to do this
with custom objects is to add a descriptive prefix to the path. For example, the
following is an implementation of the path for a hypothetical `FooObject`:

    def path
      "__FooPrefix" + sep + super
    end

Note that if our FooObject is a `NamespaceObject`, meaning if it can have child
FooObjects defined inside of it, you may need to verify that the prefix is only
applied once.
yard-0.9.37/docs/GettingStarted.md000066400000000000000000000620111466601756300167710ustar00rootroot00000000000000# @title Getting Started Guide

# Getting Started with YARD

There are a few ways which YARD can be of use to you or your project. This
document will cover the most common ways to use YARD:

* [Documenting Code with YARD](#docing)
* [Using YARD to Generate Documentation](#using)
* [Configuring YARD](#config)
* [Extending YARD](#extending)
* [Templating YARD](#templating)
* [Plugin Support](#plugins)



## Documenting Code with YARD

By default, YARD is compatible with the same RDoc syntax most Ruby developers
are already familiar with. However, one of the biggest advantages of YARD is
the extended meta-data syntax, commonly known as "tags", that you can use
to express small bits of information in a structured and formal manner. While
RDoc syntax expects you to describe your method in a completely free-form
manner, YARD recommends declaring your parameters, return types, etc. with
the `@tag` syntax, which makes outputting the documentation more consistent
and easier to read. Consider the RDoc documentation for a method to_format:

    # Converts the object into textual markup given a specific `format`
    # (defaults to `:html`)
    #
    # == Parameters:
    # format::
    #   A Symbol declaring the format to convert the object to. This
    #   can be `:text` or `:html`.
    #
    # == Returns:
    # A string representing the object in a specified
    # format.
    #
    def to_format(format = :html)
      # format the object
    end

While this may seem easy enough to read and understand, it's hard for a machine
to properly pull this data back out of our documentation. Also we've tied our
markup to our content, and now our documentation becomes hard to maintain if
we decide later to change our markup style (maybe we don't want the ":" suffix
on our headers anymore).

In YARD, we would simply define our method as:

    # Converts the object into textual markup given a specific format.
    #
    # @param format [Symbol] the format type, `:text` or `:html`
    # @return [String] the object converted into the expected format.
    def to_format(format = :html)
      # format the object
    end

Using tags we can add semantic metadata to our code without worrying about
presentation. YARD will handle presentation for us when we decide to generate
documentation later.

## Which Markup Format?

YARD does not impose a specific markup. The above example uses standard RDoc
markup formatting, but YARD also supports textile and markdown via the
command-line switch or `.yardopts` file (see below). This means that you are
free to use whatever formatting you like. This guide is actually written
using markdown. YARD, however, does add a few important syntaxes that are
processed no matter which markup formatting you use, such as tag support
and inter-document linking. These syntaxes are discussed below.

## Adding Tags to Documentation

The tag syntax that YARD uses is the same @tag-style syntax you may have seen
if you've ever coded in Java, Python, PHP, Objective-C or a myriad of other
languages. The following tag adds an author tag to your class:

    # @author Loren Segal
    class MyClass
    end

To allow for large amounts of text, the @tag syntax will recognize any indented
lines following a tag as part of the tag data. For example:

    # @deprecated Use {#my_new_method} instead of this method because
    #   it uses a library that is no longer supported in Ruby 1.9.
    #   The new method accepts the same parameters.
    def mymethod
    end

### List of Tags

A list of tags can be found in {file:docs/Tags.md#taglist}

### Reference Tags

To reduce the amount of duplication in writing documentation for repetitive
code, YARD introduces "reference tags", which are not quite tags, but not
quite docstrings either. In a sense, they are tag (and docstring) modifiers.
Basically, any docstring (or tag) that begins with "(see OTHEROBJECT)" will
implicitly link the docstring or tag to the "OTHEROBJECT", copying any data
from that docstring/tag into your current object. Consider the example:

    class MyWebServer
      # Handles a request
      # @param request [Request] the request object
      # @return [String] the resulting webpage
      def get(request) "hello" end

      # (see #get)
      def post(request) "hello" end
    end

The above `#post` method takes the docstring and all tags (`param` and `return`)
of the `#get` method. When you generate HTML documentation, you will see this
duplication automatically, so you don't have to manually type it out. We can
also add our own custom docstring information below the "see" reference, and
whatever we write will be appended to the docstring:

    # (see #get)
    # @note This method may modify our application state!
    def post(request) self.state += 1; "hello" end

Here we added another tag, but we could have also added plain text. The
text must be appended *after* the `(see ...)` statement, preferably on
a separate line.

Note that we don't have to "refer" the whole docstring. We can also link
individual tags instead. Since "get" and "post" actually have different
descriptions, a more accurate example would be to only refer our parameter
and return tags:

    class MyWebServer
      # Handles a GET request
      # @param request [Request] the request object
      # @return [String] the resulting webpage
      def get(request) "hello" end

      # Handles a POST request
      # @note This method may modify our application state!
      # @param (see #get)
      # @return (see #get)
      def post(request) self.state += 1; "hello" end
    end

The above copies all of the param and return tags from `#get`. Note that you
cannot copy individual tags of a specific type with this syntax.

## Declaring Types

Some tags also have an optional "types" field which let us declare a list of
types associated with the tag. For instance, a return tag can be declared
with or without a types field.

    # @return [String, nil] the contents of our object or nil
    #   if the object has not been filled with data.
    def validate; end

    # We don't care about the "type" here:
    # @return the object
    def to_obj; end

The list of types is in the form `[type1, type2, ...]` and is mostly free-form,
so we can also specify duck-types or constant values. For example:

    # @param argname [#to_s] any object that responds to `#to_s`
    # @param argname [true, false] only true or false

Note the latter example can be replaced by the meta-type "Boolean".
Another meta-type is "void", which stands for "no meaningful value"
and is used for return values. These meta-types are by convention
only, but are recommended.

List types can be specified in the form `CollectionClass`.
For instance, consider the following Array that holds a set of Strings and
Symbols:

    # @param list [Array] the list of strings and symbols.

We mentioned that these type fields are "mostly" free-form. In truth, they
are defined "by convention". To view samples of common type specifications
and recommended conventions for writing type specifications, see
[http://yardoc.org/types.html](http://yardoc.org/types.html). Note that these
conventions may change every now and then, although we are working on a more
"formal" type specification proposal.

## Documenting Attributes

To document a Ruby attribute, add documentation text above the attribute
definition.

    # Controls the amplitude of the waveform.
    # @return [Numeric] the amplitude of the waveform
    attr_accessor :amplitude

As a short-hand syntax for declaring reader and writer attribute pairs,
YARD will automatically wire up the correct method types and information
by simply defining documentation in the `@return` tag. For example,
the following declaration will show the correct information for the
`waveform` attribute, both for the getter's return type and the
setter's value parameter type: 

    # @return [Numeric] the amplitude of the waveform
    attr_accessor :amplitude

In this case, the most important details for the attribute are the
object type declaration and its descriptive text.

### Documentation for a Separate Attribute Writer

Usually an attribute will get and set a value using the same syntax,
so there is no reason to have separate documentation for an attribute
writer. In the above `amplitude` case, the `Numeric` type is both used
for the getter and setter types.

Sometimes, however, you might want to have separate documentation
for the getter and setter. In this case, you would still add
the documentation text to the getter declaration (or `attr_accessor`)
and use `@overload` tags to declare the separate docstrings. For example:

    # @overload amplitude
    #   Gets the current waveform amplitude.
    #   @return [Numeric] the amplitude of the waveform
    # @overload amplitude=(value)
    #   Sets the new amplitude.
    #   @param value [Numeric] the new amplitude value
    #   @note The new amplitude will only take effect if {#restart}
    #     is called on the stream.

Note that by default, YARD exposes the reader portion of the attribute
in HTML output. If you have separate `attr_reader` and `attr_writer`
declarations, make sure to put your documentation (for both reader
and writer methods) on the reader declaration using `@overload`
tags as described above. For example:

    # @overload ...documentation here...
    attr_reader :amplitude

    # This documentation will be ignored by YARD.
    attr_writer :amplitude

## Documenting Custom DSL Methods

Application code in Ruby often makes use of DSL style metaprogrammed methods.
The most common is the `attr_accessor` method, which of course has built-in
support in YARD. However, frameworks and libraries often expose custom
methods that perform similar metaprogramming tasks, and it is often useful
to document their functionality in your application. Consider the `property`
method in a project like [DataMapper](http://datamapper.org), which creates
a typed attribute for a database model. The code might look like:

    class Post
      include DataMapper::Resource

      property :title, String
    end

As of version 0.7.0, YARD will automatically pick up on these basic methods if
you document them with a docstring. Therefore, simply adding some comments to
the code will cause it to generate documentation:

    class Post
      include DataMapper::Resource

      # @return [String] the title property of the post
      property :title, String
    end

Note that YARD uses the first argument in the method call to determine the
method name. In some cases, this would not be the method name, and you would
need to declare it manually. You can do so with the `@!method` directive:

    # @!method foo
    create_a_foo_method

The @!method directive can also accept a full method signature with parameters:

    # @!method foo(name, opts = {})
    create_a_foo_method

You can also set visibility and scope, or modify the method signature with
extra tags. The following adds documentation for a private class method:

    # @!method foo(opts = {})
    # The foo method!
    # @!scope class
    # @!visibility private
    create_a_private_foo_class_method

Finally, you can tag a method as an attribute by replacing the @!method
tag with @!attribute. The @!attribute directive allows for the flags [r], [w],
or [rw] to declare a readonly, writeonly, or readwrite attribute, respectively.

    # @!attribute [w]
    # The writeonly foo attribute!
    a_writeonly_attribute :foo

(Note that if the name can be automatically detected, you do not need to
specify it in the @!method or @!attribute directives)

However, you will notice a few drawbacks with this basic support:

1. There is a fair bit of duplication in such documentation. Specifically, we
   repeat the term String and title twice in the property example.
2. We must write a code comment for this property to show up in the documentation.
   If we do not write a comment, it is ignored.

### Macros

Fortunately YARD 0.7.0 also adds macros, a powerful way to add support for
these DSL methods on the fly without writing extra plugins. Macros allow
you to interpolate arguments from the method call inside the docstring,
reducing duplication. If we re-wrote the `property` example from above
using a macro, it might look like:

    class Post
      include DataMapper::Resource

      # @!macro dm.property
      # @return [$2] the $1 $0 of the post
      property :title, String
    end

(Note that $0 represents the method call, in this case `property`. The rest
are arguments in the method call.)

The above example is equivalent to the first version shown in the previous
section. There is also some extra benefit to using this macro, in that we
can re-apply it to any other property in our class by simply calling on
the macro. The following:

    # @!macro dm.property
    property :view_count, Integer

Would be equivalent to:

    # @return [Integer] the view_count property of the post
    property :view_count, Integer

Finally, macros can be "attached" to method calls, allowing them to be implicitly
activated every time the method call is seen in the source code of the class,
or an inheriting class. By simply adding the `[attach]` flag, the macro
becomes implicit on future calls. All of the properties below get documented
by using this snippet:

    class Post
      include DataMapper::Resource

      # @!macro [attach] dm.property
      # @return [$2] the $1 $0 of the post
      property :title, String
      property :view_count, Integer
      property :email, String
    end

You can read more about macros in the {file:docs/Tags.md Tags Overview} document.

## Customized YARD Markup

YARD supports a special syntax to link to other code objects, URLs, files,
or embed docstrings between documents. This syntax has the general form
of `{Name OptionalTitle}` (where `OptionalTitle` can have spaces, but `Name`
cannot).

### Linking Objects `{...}`

To link another "object" (class, method, module, etc.), use the format:

    {ObjectName#method OPTIONAL_TITLE}
    {Class::CONSTANT My constant's title}
    {#method_inside_current_namespace}

Without an explicit title, YARD will use the relative path to the object as
the link name. Note that you can also use relative paths inside the object
path to refer to an object inside the same namespace as your current docstring.

Note that the `@see` tag automatically links its data. You should not use
the link syntax in this tag:

    # @see #methodname   <- Correct.
    # @see {#methodname} <- Incorrect.

If you want to use a Hash, prefix the first { with "!":

   # !{ :some_key => 'value' }

### Linking URLs `{http://...}`

URLs are also linked using this `{...}` syntax:

    {http://example.com Optional Title}
    {mailto:email@example.com}

### Linking Files `{file:...}`

Files can also be linked using this same syntax but by adding the `file:`
prefix to the object name. Files refer to extra readme files you added
via the command-line. Consider the following examples:

    {file:docs/GettingStarted.md Getting Started}
    {file:mypage.html#anchor Name}

As shown, you can also add an optional `#anchor` if the page is an HTML link.

### Embedding Docstrings `{include:...}`

We saw the `(see ...)` syntax above, which allowed us to link an entire docstring
with another. Sometimes, however, we just want to copy docstring text without
tags. Using the same `{...}` syntax, but using the `include:` prefix, we can
embed a docstring (minus tags) at a specific point in the text.

    # This class is cool
    # @abstract
    class Foo; end

    # This is another class. {include:Foo} too!
    class Bar; end

The docstring for Bar becomes:

    "This is another class. This class is cool too!"

### Embedding Files `{include:file:...}`

You can embed the contents of files using `{include:file:path/to/file}`,
similar to the `{include:OBJECT}` tag above. If the file uses a specific markup
type, it will be applied and embedded as marked up text. The following
shows how the tag can be used inside of comments:

    # Here is an example of a highlighted Ruby file:
    #
    # {include:file:examples/test.rb}

### Rendering Objects `{render:...}`

Entire objects can also be rendered in place in documentation. This can be
used for guide-style documentation which does not document the entire source
tree, but instead selectively renders important classes or methods. Consider
the following documentation inside of a README file:

    !!!plain
    = igLatinPay!

    This library adds pig latin methods to the string class, allowing you
    to transform sentences into pig latin.

    {render:String#pig_latin}

    You can also un-pig-latin-ify a word or sentence:

    {render:String#de_pig_latin}

The above would render the methods in place inside the README document,
allowing you to summarize a small library in a single file.



## Using YARD to Generate Documentation

### `yard` Executable

YARD ships with a single executable aptly named `yard`. In addition to
generating standard documentation for your project, you would use this tool
if you wanted to:

* Document all installed gems
* Run a local documentation server
* Generate UML diagrams using [Graphviz][graphviz]
* View `ri`-style documentation
* Diff your documentation
* Analyze documentation statistics.

The following commands are available in YARD 0.6.x (see `yard help` for a
full list):

    Usage: yard  [options]

    Commands:
    config   Views or edits current global configuration
    diff     Returns the object diff of two gems or .yardoc files
    doc      Generates documentation
    gems     Builds YARD index for gems
    graph    Graphs class diagram using Graphviz
    help     Retrieves help for a command
    ri       A tool to view documentation in the console like `ri`
    server   Runs a local documentation server
    stats    Prints documentation statistics on a set of files

Note that `yardoc` is an alias for `yard doc`, and `yri` is an alias for
`yard ri`. These commands are maintained for backwards compatibility.

### `.yardopts` Options File

Unless your documentation is very small, you'll end up needing to run `yardoc`
with many options.  The `yardoc` tool will use the options found in this file.
It is recommended to check this in to your repository and distribute it with
your source. This file is placed at the root of your project (in the directory
you run `yardoc` from) and contains all of arguments you would otherwise pass
to the command-line tool. For instance, if you often type:

    yardoc --no-private --protected app/**/*.rb - README LEGAL COPYING

You can place the following into your `.yardopts`:

    --no-private --protected app/**/*.rb - README LEGAL COPYING

This way, you only need to type:

    yardoc

Any extra switches passed to the command-line now will be appended to your
`.yardopts` options.

Note that options for `yardoc` are discussed in the {file:README.md README},
and a full overview of the `.yardopts` file can be found in {YARD::CLI::Yardoc}.

### Documenting Extra Files

"Extra files" are extra guide style documents that help to give a brief overview
of how to use your library/framework, as well as any extra information that
might be vital for your users. The most common "extra file" is the README,
which is automatically detected by YARD if found in the root of your project
(any file starting with `README*`). You can specify extra files on the command
line (or in the `.yardopts` file) by listing them after the '-' separator:

    yardoc lib/**/*.rb ext/**/*.{c,rb} - LICENSE.txt

Note that the README will automatically be picked up, so you do not need to
specify it. If you don't want to modify the default file globs, you can ignore
the first set of arguments:

    yardoc - LICENSE.txt

Below you can read about how to customize the look of these extra files, both
with markup and pretty titles.

#### Adding Meta-Data to Extra Files

You can add YARD-style `@tag` metadata to the top of any extra file if prefixed
by a `#` hash comment. YARD allows for arbitrary meta-data, but pays special
attention to the tags `@markup`, `@encoding`, and `@title`. Note that there
cannot be any whitespace before the tags. Here is an example of some tag data
in a README:

    # @markup markdown
    # @title The Best Library in the World!
    # @author The Author Name

    This is the best library you will ever meet. Lipsum ...

The `@markup` tag allows you to specify a markup format to use for the file,
including "markdown", "textile", "rdoc", "ruby", "text", "html", or "none"
(no markup). This can be used when the markup cannot be auto-detected using
the extension of the filename, if the file has no extension, or if you want
to override the auto-detection.

By using `@encoding` you can specify a non-standard encoding. Note that
`yardoc --charset` sets the global encoding (for all comments / files),
so if you are using unicode across all your files, you can specify it there.
Using the `@encoding` tag might be used to override the default global
charset, say, if you had a localized `README.jp` file with SJIS data.
Also note that this only affects Ruby 1.9.x, as Ruby 1.8 is not properly
encoding aware.

The `@title` tag allows you to specify a full title name for the document.
By default, YARD uses the filename as the title of the document and lists
it in the file list in the index and file menu. In some cases, the file name
might not be descriptive enough, so YARD allows you to specify a full title:

    contents of TITLE.txt:
    # @title The Title of The Document

Currently all other meta-data is hidden from view, though accessible
programmatically using the {YARD::CodeObjects::ExtraFileObject} class.

You can wrap the meta data section in an HTML comment to prevent it
from being displayed in rendered markdown on GitHub:

    

    This is the best library you will ever meet. Lipsum ...



## Configuring YARD

YARD (0.6.2+) supports a global configuration file stored in `~/.yard/config`.
This file is stored as a YAML file and can contain arbitrary keys and values
that can be used by YARD at run-time. YARD defines specific keys that are used
to control various features, and they are listed in {YARD::Config::DEFAULT_CONFIG_OPTIONS}.
A sample configuration file might look like:

    :load_plugins: false
    :ignored_plugins:
      - my_plugin
      - my_other_plugin
    :autoload_plugins:
      - my_autoload_plugin
    :safe_mode: false

You can also view and edit these configuration options from the commandline
using the `yard config` command. To list your configuration, use `yard config --list`.
To view a key, use `yard config ITEM`, and to set it, use `yard config ITEM VALUE`.



## Extending YARD

There are many ways to extend YARD to support non-standard Ruby syntax (DSLs),
add new meta-data tags or programmatically access the intermediate metadata
and documentation from code. An overview of YARD's full architecture can be
found in the {file:docs/Overview.md} document.

For information on adding support for Ruby DSLs, see the {file:docs/Handlers.md}
and {file:docs/Parser.md} architecture documents.

For information on adding extra tags, see {file:docs/Tags.md}.

For information on accessing the data YARD stores about your documentation,
look at the {file:docs/CodeObjects.md} architecture document.



## Templating YARD

In many cases you may want to change the style of YARD's templates or add extra
information after extending it. The {file:docs/Templates.md} architecture
document covers the basics of how YARD's templating system works.



## Plugin Support

YARD will allow any RubyGem installed on your system (or in your Gemfile)
to be loaded as a plugin provided it has a name with the prefix of
`yard-` or `yard_`. In order to load a plugin, use the `--plugin`
switch with the short-name (name minus the `yard-` prefix) or full-name
of the gem:

    $ gem install yard-custom-plugin
    ...
    $ yard doc --plugin custom-plugin
    or
    $ yard doc --plugin yard-custom-plugin

Note: you can also put this switch in your `.yardopts` file. See the
      `.yardopts` section above for more information.

You can use this functionality to load a custom plugin that
[extend](#extending) YARD's functionality. A good example of this
is the [yard-rspec][yard-rspec] plugin, which adds [RSpec][rspec] specifications
to your documentation (`yardoc` and `yri`). You can try it out by installing
the gem or cloning the project and trying the example:

    $ gem install yard-rspec

 You can then load the plugin with:

    $ yard doc --plugin rspec

YARD also provides a way to temporarily disable plugins on a per-user basis.
To disable a plugin create the file `~/.yard/ignored_plugins` with a list
of plugin names separated by newlines. Note that the `.yard` directory might
not exist, so you may need to create it.

You may find some useful YARD plugins on [RubyGems][RubyGemsQuery] or with
a [Google advanced query][GoogleAdvancedQuery].

[graphviz]:http://www.graphviz.org
[yard-rspec]:http://github.com/lsegal/yard-spec-plugin
[rspec]:http://rspec.info
[GoogleAdvancedQuery]:https://www.google.com/search?q=site%3Arubygems.org+intitle%3A%22yard-%22+OR+intitle%3A%22yard_%22
[RubyGemsQuery]:https://rubygems.org/search?utf8=%E2%9C%93&query=name%3A+yard
yard-0.9.37/docs/Handlers.md000066400000000000000000000152101466601756300156000ustar00rootroot00000000000000# @title Handlers Architecture

# Handlers Architecture

Handlers allow the processing of parsed source code. Handling is done after
parsing to abstract away the implementation details of lexical and semantic
analysis on source and to only deal with the logic regarding recognizing
source statements as {file:docs/CodeObjects.md code objects}.

![Handlers Architecture Class Diagram](images/handlers-class-diagram.png)

## The Pipeline

After the {file:docs/Parser.md parser component} finishes analyzing the
source, it is handed off for post-processing to the {YARD::Handlers::Processor}
class, which is responsible for traversing the set of statements given by
the parser and delegating them to matching handlers. Handlers match when the
{YARD::Handlers::Base.handles?} method returns true for a given statement.
The handler can then perform any action after being invoked by the `process`
method.

## The Processor Class

The main purpose of the processor, as mentioned above, is to traverse through
the list of statements given to it by the parser. The processor also keeps
state about what is being processed. For instance, the processor is what keeps
track of the current namespace (the module or class an object is being defined
in), scope (class or instance), file and owner. The owner refers to the object
that is most directly responsible for the source statement being processed. This
is most often the same as the namespace, except when parsing the body of a method,
where the namespace would be the class/module the method is defined in and the
owner would be the method object itself.

## Implementing a Handler

This section covers the basics of implementing a *new-style* Ruby handler. For
details on implementing a legacy handler, see the "API Differences" section below.

a Ruby handler can be implemented simply by subclassing the {YARD::Handlers::Ruby::Base}
class and declaring what node types or source to process with the {YARD::Handlers::Base.handles handles}
class method. A very simple handler that handles a module definition would be:

    class MyModuleHandler < YARD::Handlers::Ruby::Base
      handles :module

      def process
        puts "Handling a module named #{statement[0].source}"
      end
    end

For details on what nodes are, and what node types are, see the
{file:docs/Parser.md parser architecture document}.

In this case the node type being handled is the `:module` type. More than one
node type or `handles` declarations may describe a single handler, for instance,
a handler that handles class definitions should handle the `:class` and `:sclass`
node types respectively (the latter refers to classes defined as `class << Something`).
The {YARD::Handlers::Base#statement statement} attribute refers to the current
node (or statement) that is being handled by the handler.

### Handling a Method Call

In some cases, a developer might need to handle a method call. The parser can
express a method call in many AST forms, so to simplify this process, a method
call can be handled by declaring the following in a `handles` statement:

    class MyHandler < YARD::Handlers::Ruby::Base
      handles method_call(:describe)

      def process
        # Process the method call
      end
    end

In this case we handle any of the method calls to method name `describe` with
the following syntaxes:

    describe(something)
    describe arg1, arg2, arg3
    describe(something) { perform_a_block }
    describe "Something" do
      a_block
    end

### Creating a new Code Object

Usually (but not always) handling is performed to create new code objects to add
to the registry (for information about code objects, see {file:docs/CodeObjects.md this document}).
Code objects should simply be created and added to the existing `namespace`. This
will be enough to add them to the registry. There is also a convenience
{YARD::Handlers::Base#register register} method which quickly sets standard attributed
on the newly created object, such as the file, line, source and docstring of the
object. This method will be seen in the next example.

### Handling an Inner Block

By default, the parser gives the processor class a list of all the top level
statements and the processor parses only those top level statements. If an inner
block of a module, class, method declaration or even a block passed to a method call
needs to be handled, the {YARD::Handlers::Base#parse_block parse_block} method must be called on the list of statements
to parse. This will send the list to the processor to continue processing on that
statement list. The source tree can be selectively parsed in this manner by parsing
only the inner blocks that are relevant to documentation.

For example, the module handler parses the inner body of a module by performing
the following commands:

    class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base
      handles :module

      def process
        modname = statement[0].source
        mod = register ModuleObject.new(namespace, modname)
        parse_block(statement[1], :namespace => mod)
      end
    end

In this case `statement[1]` refers to a list of extra statements, the block we
wish to parse. Note here that when parsing objects like modules and classes,
we set the namespace for the duration of the block parsing by setting options
on the `parse_block` method.

### API Differences for Legacy Handler

Because the legacy handler uses the legacy parser and therefore a different kind
of AST, there are subtle differences in the handler API. Most importantly, the
`handles` method usually deals with either lexical tokens or source code as a string
or RegExp object. The statement object, similarly, is made up of lexical tokens instead
of semantically parsed nodes (this is described in the {file:docs/Parser.md parser document}).

The module example above can be rewritten as a legacy handler as follows:

    class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base
      handles TkMODULE

      def process
        modname = statement.tokens.to_s[/^module\s+(#{NAMESPACEMATCH})/, 1]
        mod = register ModuleObject.new(namespace, modname)
        parse_block(:namespace => mod)
      end
    end

A few notes on the differences:

  * We inherit from `Legacy::Base` instead of the standard Ruby Base handler class.
  * We exchange node type `:module` for `TkMODULE`, which represents the
    first token in the statement.
  * We perform direct string manipulation to get the module name.
  * `parse_block` does not take a list of statements. In the old parser API,
    each statement has a `block` attribute which defines the list of
    statements within that statement, if any. Therefore, `parse_block` will
    always parse the `statement.block` if it exists.
yard-0.9.37/docs/Overview.md000066400000000000000000000050251466601756300156510ustar00rootroot00000000000000# @title Architecture Overview

# Architecture Overview

YARD is separated in three major components, each of which allows YARD to be
extended for a separate purpose. The split also emphasizes YARD's design choice
to explicitly separate data gathering from HTML document generation, something
that tools like RDoc do not do. These components are:

* [Code Parsing & Processing Component](#parsing)
* [Data Storage Component](#storage)
* [Post Processing & Templating System](#templates)

This separation is a major goal of the project, and means that YARD is not *just*
a tool to generate HTML output. The expectation is that any subset of YARD's
major components may be used, extended or modified independently. YARD may be
used just as a data gathering tool (to parse and audit code), just as a data
source (a webserver containing raw unformatted data about code), or just as a
conventional HTML documentation generation tool (like RDoc).

The important classes and dependencies of these components are shown in the
following class diagram:

![Overview Class Diagram](images/overview-class-diagram.png)



## Code Parsing & Processing Component

This component is made up of four sub-components, each of which have separate
tasks during the data gathering process (*note: the tag architecture is not*
*shown in the class diagram*). These sub-components are:

  * {file:docs/Parser.md}
  * {file:docs/Handlers.md}
  * {file:docs/CodeObjects.md}
  * {file:docs/Tags.md}

The parser component reads source files and converts it into a set of statements
which the handlers then process, creating code objects which in turn create tags
(meta-data) attached to the objects. These objects are all added to the {YARD::Registry},
the data store component.



## Data Storage Component

This component is currently implemented as a simple Ruby marshalled flat namespace
of object. The implementation is found in the single class {YARD::Registry}, which
is the centralized repository for all data being parsed, stored and accessed. There
are future plans to improve this storage mechanism to be backend agnostic and allow
for more robust storage.



## Post Processing & Templating System

This component handles processing of objects from the registry through a templating
engine that allows output to a variety of formats. Practically speaking, this is
where templates can be implemented to change the design, output or structure of
the data. See {file:docs/Templates.md Templates Architecture} for a complete overview.
yard-0.9.37/docs/Parser.md000066400000000000000000000212511466601756300152760ustar00rootroot00000000000000# @title Parser Architecture

# Parser Architecture

The parser component of YARD is the first component in the data processing pipeline
that runs before any handling is done on the source. The parser is meant to translate
the source into a set of statements that can be understood by the {file:docs/Handlers.md Handlers}
that run immediately afterwards.

The important classes are described in the class diagram of the entire parser
system below:

![Parser Class Diagram](images/parser-class-diagram.png)

(Note: the RubyToken classes are omitted from the diagram)

## SourceParser

The main class {YARD::Parser::SourceParser} acts as a factory class, instantiating
the correct parser class, an implementation of {YARD::Parser::Base}. The selected parser
is chosen based on either the file extension or by selecting it explicitly (as an argument
to parsing methods). YARD supports Ruby and C source files, but custom parsers can
be implemented and registered for various other languages by subclassing `Parser::Base`
and registering the parser with {YARD::Parser::SourceParser.register_parser_type}.

This factory class should always be used when parsing source files rather than
the individual parser classes since it initiates the pipeline that runs the
handlers on the parsed source. The parser used must also match the handlers,
and this is coordinated by the `SourceParser` class as well.

## Using the SourceParser Class

The `SourceParser` class API is optimized for parsing globs of files. As such,
the main method to use the class is the `parse` class method, which takes an
array of file globs or a single file glob.

    YARD::Parser::SourceParser.parse('spec_*.rb')
    YARD::Parser::SourceParser.parse(['spec_*.rb', '*_helper.rb'])

This is equivalent to the convenience method {YARD.parse}:

    YARD.parse('lib/**/*.rb')

In some cases (ie. for testing), it may be more helpful to parse a string of input
directly. In such a case, the method {YARD::Parser::SourceParser.parse_string} should be
used:

    YARD::Parser::SourceParser.parse_string("def method(a, b) end")

You can also provide the parser type explicitly as the second argument:

    # Parses a string of C
    YARD::Parser::SourceParser.parse_string("int main() { }", :c)

Note that these two methods are aliased as {YARD.parse} and {YARD.parse_string} for
convenience.

## Implementing and Registering a Custom Parser

To implement a custom parser, subclass {YARD::Parser::Base}. Documentation on which
abstract methods should be implemented are documented in that class. After the class
is implemented, it is registered with the {YARD::Parser::SourceParser} factory class
to be called when a file of the right extension needs to be parsed, or when a user
selects that parser type explicitly. To register your new parser class, call the
method {YARD::Parser::SourceParser.register_parser_type}:

    SourceParser.register_parser_type(:my_parser, MyParser, 'my_parser_ext')

The last argument can be a single extension, a list of extensions (Array), a single Regexp, or a
list of Regexps. Do not include the '.' in the extension.


## The Two Ruby Parser Types

When parsing Ruby, the SourceParser can either instantiate the new {YARD::Parser::Ruby::RubyParser}
class or the {YARD::Parser::Ruby::Legacy::StatementList} class. The first of the
two, although faster, more robust and more efficient, is only available for
Ruby 1.9. The legacy parser parser is available in both 1.8.x and 1.9, if
compatibility is required. The choice of parser will affect which handlers
ultimately get used, since new handlers can only use the new parser and the
same requirement applies to the legacy parser & handlers.

## Switching to Legacy Parser

By default, running YARD under Ruby 1.9 will automatically select the new parser
and new handlers by extension. Although YARD supports both handler styles, plugins
may choose to only implement one of the two (though this is not recommended). If
only the legacy handlers are implemented, the `SourceParser` class should force
the use of the legacy parser by setting the `parser_type` attribute as such:

    YARD::Parser::SourceParser.parser_type = :ruby18

The default value is `:ruby`. Note that this cannot be forced the other way around,
a parser type of `:ruby` cannot be set under Ruby 1.8.x as the new parser is not
supported under 1.8.

## RubyParser (the New Parser)

The new Ruby parser uses the Ripper library that is packaged as part of stdlib
in Ruby 1.9. Because of this, it can generate an AST from a string of Ruby input
that is similar to the style of other sexp libraries (such as ParseTree). Each
node generated in the tree is of the base type {YARD::Parser::Ruby::AstNode},
which has some subclasses for common node types.

### AstNode Basics

The `AstNode` class behaves like a standard Array class in which all of its data
make up the list of elements in the array. Unlike other sexp style libraries, however,
the node type is not the first element of the list. Instead, the node type is defined
by the `#type` method. The following examples show some of the basic uses of `AstNode`:

    # The sexp defines the statement `hello if 1`
    node = s(:if_mod, s(:int, "1"), s(:var_ref, s(:ident, "hello")))
    node.type  #=> :if_mod
    node[0]    #=> s(:int, "1")
    node[0][0] #=> "1"

(Note the `s()` syntax is shorthand for `AstNode.new(...)`. `s()` with no type
is shorthand for a node of type `:list`)

As shown, not all of the elements are AstNodes in themselves, some are String
objects containing values. A list of only the AstNodes within a node can be
accessed via the {YARD::Parser::Ruby::AstNode#children #children} method. Using
the sexp declared above, we can do:

    node.children #=> [s(:int, "1"), s(:var_ref, s(:ident, "hello"))]

### AstNode#source and #line

Every node defines the `#source` method which returns the source code that the
node represents. One of the most common things to do with a node is to grab its
source. The following example shows how this can be done:

    source = "if 1 == 1 then\n  raise Exception\n end"
    ast = YARD::Parser::Ruby::RubyParser.parse(source).root
    ast[0].condition.source  #=> "1 == 1"
    ast[0].then_block.source #=> "raise Exception"

Note that this only works on source parsed from the RubyParser, not sexps
declared using the `s()` syntax. This is because no source code is generated
or stored by nodes. Instead, only the character ranges are stored, which are
then looked up in the original full source string object. For example:

    # Following the code snippet above
    ast[0].then_block.source_range #=> 17..31

We can also get the line and line ranges in a similar fashion:

    ast[0].type       #=> :if
    ast[0].line       #=> 1
    ast[0].line_range #=> 1..3 (note the newlines in the source)

### AstNode#jump

Often the AST will be such that the node we care about might be buried arbitrarily
deep in a node's hierarchy. The {YARD::Parser::Ruby::AstNode#jump} method exists
to quickly get at a node of a specific type in such a situation:

    # Get the first identifier in the statement
    ast = s(s(:int, "1"), s(s(:var_ref, s(:ident, "hello"))))
    ast.jump(:ident)[0] #=> "hello"

Multiple types can be searched for at once. If none are found, the original root
node is returned so that it may be chained.

## The Legacy Parser

The goal of the legacy parser is much the same as the new parser, but it is far
more simplistic. Instead of a full-blown AST, the legacy parser simply groups
together lists of "statements" called a {YARD::Parser::Ruby::Legacy::StatementList}.
These statement lists are made up of {YARD::Parser::Ruby::Legacy::Statement} objects.
A statement is any method call condition, loop, or declaration. Each statement
may or may not have a block. In the case of a condition or loop, the block is
the inner list of statements; in the case of a method call, the block is a do
block (if provided). The statements themselves are made up of tokens, so instead
of being semantic in nature like the new parser, statements are tied directly
to the lexical tokens that make them up. To convert a statement into source, you
simply join all the tokens together (this is done through the use of `#to_s`).

Note that because there is little semantic parsing, the legacy parser is less
able to deal with certain Ruby syntaxes. Specifically, the `:if_mod` syntax
seen above ("hello if 1") would be considered two statements with the new parser,
but using the legacy parser it is only one statement:

    stmts = ARD::Parser::Ruby::Legacy::StatementList.new("hello if 1")
    stmts[0].block       #=> nil
    stmts[0].tokens.to_s #=> "hello if 1"

In addition, this means that most handling still needs to be done via string
manipulation and regular expression matching, making it considerably more
difficult to use in edge case scenarios.
yard-0.9.37/docs/Tags.md000066400000000000000000000323211466601756300147400ustar00rootroot00000000000000# @title Tags Overview

# Tags Overview

Tags represent meta-data as well as behavioural data that can be added to
documentation through the `@tag` style syntax. As mentioned, there are two
basic types of tags in YARD, "meta-data tags" and "behavioural tags", the
latter is more often known as "directives". These two tag types can be
visually identified by their prefix. Meta-data tags have a `@` prefix,
while directives have a prefix of `@!` to indicate that the directive
performs some potentially mutable action on or with the docstring. The
two tag types would be used in the following way, respectively:

    # @meta_data_tag some data
    # @!directive_tag some data
    class Foo; end

This document describes how tags can be specified, how they affect your
documentation, and how to use specific built-in tags in YARD, as well
as how to define custom tags.

## Meta-Data Tags

Meta-data tags are useful to add arbitrary meta-data about a documented
object. These tags simply add data to objects that can be looked up later,
either programmatically, or displayed in templates. The benefit to describing
objects using meta-data tags is that your documentation can be organized
semantically. Rather than having a huge listing of text with no distinction
of what each paragraph is discussing, tags allow you to focus in on specific
elements of your documentation.

For example, describing parameters of a method can often be important to your
documentation, but should not be mixed up with the documentation that describes
what the method itself does. In this case, separating the parameter documentation
into {tag:param} tags can yield much better organized documentation, both in
source and in your output, without having to manually format the data using
standard markup.

All of this meta-data can be easily parsed by tools and used both in your templates
as well as in code checker tools. An example of how you can leverage tags
programmatically is shown in the {tag:todo} tag, which lists a small snippet of
Ruby code that can list all of your TODO items, if they are properly tagged.

Custom meta-data tags can be added either programmatically or via the YARD
command-line. This is discussed in the "[Adding Custom Tags](#Adding_Custom_Tags)"
section.

A list of built-in meta-data tags are found below in the [Tag List](#Tag_List).

## Directives

Directives are similar to meta-data tags in the way they are specified, but they
do not add meta-data to the object directly. Instead, they affect the parsing
context and objects themselves, allowing a developer to create objects
(like methods) outright, rather than simply add text to an existing object.
Directives have a `@!` prefix to differentiate these tags from meta-data tags,
as well as to indicate that the tag may modify or create new objects when
it is called.

A list of built-in directives are found below in the [Directive List](#Directive_List).

## Tag Syntax

Tags begin with the `@` or `@!` prefix at the start of a comment line, followed
immediately by the tag name, and then optional tag data (if the tag requires it).
Unless otherwise specified by documentation for the tag, all "description" text
is considered free-form data and can include any arbitrary textual data.

### Multi-line Tags

Tags can span multiple lines if the subsequent lines are indented by more than
one space. The typical convention is to indent subsequent lines by 2 spaces.
In the following example, `@tagname` will have the text *"This is indented tag data"*:

    # @tagname This is
    #   indented tag data
    # but this is not

For most tags, newlines and indented data are not significant and do not impact
the result of the tag. In other words, you can decide to span a tag onto multiple
lines at any point by creating an indented block. However, some tags like
{tag:example}, {tag:overload}, {tag:!macro}, {tag:!method}, and {tag:!attribute}
rely on the first line for special information about the tag, and you cannot
split this first line up. For instance, the {tag:example} tag uses the first line
to indicate the example's title.

### Common Tag Syntaxes

Although custom tags can be parsed in any way, the built-in tags follow a few
common syntax structures by convention in order to simplify the syntax. The
following syntaxes are available:

1. **Freeform data** — In this case, any amount of textual data is allowed,
  including no data. In some cases, no data is necessary for the tag.
2. **Freeform data with a types specifier list** — Mostly freeform data
  beginning with an *optional* types specifier list surrounded in `[brackets]`.
  Note that for extensibility, other bracket types are allowed, such as `<>`,
  `()` and `{}`. The contents of the list are discussed in detail below.
3. **Freeform data with a name and types specifier list** — freeform
  data beginning with an *optional* types list, as well as a name key, placed
  either before or after the types list. The name key is *required*. Note that
  for extensibility, the name can be placed *before* the types list, like:
  `name [Types] description`. In this case, a separating space is not required
  between the name and types, and you can still use any of the other brackets
  that the type specifier list allows.
4. **Freeform data with title** — freeform data where the first line cannot
  be split into multiple lines. The first line must also always refer to the
  "title" portion, and therefore, if there is no title, the first line must
  be blank. The "title" might occasionally be listed by another name in tag
  documentation, however, you can identify this syntax by the existence of
  a multi-line signature with "Indented block" on the second line.

In the tag list below, the term "description" implies freeform data, `[Types]`
implies a types specifier list, "name" implies a name key, and "title" implies
the first line is a newline significant field that cannot be split into multiple
lines.

### Types Specifier List

In some cases, a tag will allow for a "types specifier list"; this will be evident
from the use of the `[Types]` syntax in the tag signature. A types specifier list
is a comma separated list of types, most often classes or modules, but occasionally
literals. For example, the following {tag:return} tag lists a set of types returned
by a method:

    # Finds an object or list of objects in the db using a query
    # @return [String, Array, nil] the object or objects to
    #   find in the database. Can be nil.
    def find(query) finder_code_here end

A list of conventions for type names is specified below. Typically, however,
any Ruby literal or class/module is allowed here. Duck-types (method names
prefixed with "#") are also allowed.

Note that the type specifier list is always an optional field and can be omitted
when present in a tag signature. This is the reason why it is surrounded by
brackets. It is also a freeform list, and can contain any list of values, though
a set of conventions for how to list types is described below.

### Type List Conventions



  A list of examples of common type listings and what they translate into is
  available at http://yardoc.org/types.



Typically, a type list contains a list of classes or modules that are associated
with the tag. In some cases, however, certain special values are allowed or required
to be listed. This section discusses the syntax for specifying Ruby types inside of
type specifier lists, as well as the other non-Ruby types that are accepted by
convention in these lists.

It's important to realize that the conventions listed here may not always adequately
describe every type signature, and is not meant to be a complete syntax. This is
why the types specifier list is freeform and can contain any set of values. The
conventions defined here are only conventions, and if they do not work for your
type specifications, you can define your own appropriate conventions.

Note that a types specifier list might also be used for non-Type values. In this
case, the tag documentation will describe what values are allowed within the
type specifier list.

#### Class or Module Types

Any Ruby type is allowed as a class or module type. Such a type is simply the name
of the class or module.

Note that one extra type that is accepted by convention is the `Boolean` type,
which represents both the `TrueClass` and `FalseClass` types. This type does not
exist in Ruby, however.

#### Parametrized Types

In addition to basic types (like String or Array), YARD conventions allow for
a "generics" like syntax to specify container objects or other parametrized types.
The syntax is `Type`. For instance, an Array might
contain only String objects, in which case the type specification would be
`Array`. Multiple parametrized types can be listed, separated by commas.

Note that parametrized types are typically not order-dependent, in other words,
a list of parametrized types can occur in any order inside of a type. An array
specified as `Array` can contain any amount of Strings or Fixnums,
in any order. When the order matters, use "order-dependent lists", described below.

#### Duck-Types

Duck-types are allowed in type specifier lists, and are identified by method
names beginning with the "#" prefix. Typically, duck-types are recommended
for {tag:param} tags only, though they can be used in other tags if needed.
The following example shows a method that takes a parameter of any type
that responds to the "read" method:

    # Reads from any I/O object.
    # @param io [#read] the input object to read from
    def read(io) io.read end

#### Hashes

Hashes can be specified either via the parametrized type discussed above,
in the form `Hash`, or using the hash specific syntax:
`Hash{KeyTypes=>ValueTypes}`. In the latter case, KeyTypes or ValueTypes can
also be a list of types separated by commas.

#### Order-Dependent Lists

An order dependent list is a set of types surrounded by "()" and separated by
commas. This list must contain exactly those types in exactly the order specified.
For instance, an Array containing a String, Fixnum and Hash in that order (and
having exactly those 3 elements) would be listed as: `Array(String, Fixnum, Hash)`.

#### Literals

Some literals are accepted by virtue of being Ruby literals, but also by YARD
conventions. Here is a non-exhaustive list of certain accepted literal values:

* `true`, `false`, `nil` — used when a method returns these explicit literal
  values. Note that if your method returns both `true` or `false`, you should use
  the `Boolean` conventional type instead.
* `self` — has the same meaning as Ruby's "self" keyword in the context of
  parameters or return types. Recommended mostly for {tag:return} tags that are
  chainable.
* `void` — indicates that the type for this tag is explicitly undefined.
  Mostly used to specify {tag:return} tags that do not care about their return
  value. Using a `void` return tag is recommended over no type, because it makes
  the documentation more explicit about what the user should expect. YARD will
  also add a note for the user if they have undefined return types, making things
  clear that they should not use the return value of such a method.



### Reference Tags



  Reference tag syntax applies only to meta-data tags, not directives.



If a tag's data begins with `(see OBJECT)` it is considered a "reference tag".
A reference tag literally copies the tag data by the given tag name from the
specified OBJECT. For instance, a method may copy all {tag:param} tags from
a given object using the reference tag syntax:

    # @param user [String] the username for the operation
    # @param host [String] the host that this user is associated with
    # @param time [Time] the time that this operation took place
    def clean(user, host, time = Time.now) end

    # @param (see #clean)
    def activate(user, host, time = Time.now) end

## Adding Custom Tags


If a tag is specific to a given project, consider namespacing
  it by naming it in the form projectname.tagname, ie.,
  yard.tag_signature.


Custom tags can be added to YARD either via the command-line or programmatically.
The programmatic method is not discussed in this document, but rather in the
{file:docs/TagsArch.md} document.

To add a custom tag via the command-line or .yardopts file, you can use the
`--*-tag` options. A few different options are available for the common tag
syntaxes described above. For example, to add a basic freeform tag, use:

    !!!sh
    $ yard doc --tag rest_url:"REST URL"

This will register the `@rest_url` tag for use in your documentation and display
this tag in HTML output wherever it is used with the heading "REST URL".
Note that the tag title should follow the tag name with a colon (`:`). Other
tag syntaxes exist, such as the type specifier list freeform tag
(`--type-tag`), or a named key tag with types (`--type-name-tag`).

If you want to create a tag but not display it in output (it is only for
programmatic use), add `--hide-tag tagname` after the definition:

    !!!sh
    $ yard doc --tag complexity:"McCabe Complexity" --hide-tag complexity

Note that you might not need a tag title if you are hiding it. The title
part can be omitted.

{yard:include_tags}

yard-0.9.37/docs/TagsArch.md000066400000000000000000000111441466601756300155360ustar00rootroot00000000000000# @title Tags Architecture

# Tags Architecture

## Programmatic API

### Accessing Tag Information

Tag metadata is added when a {YARD::Docstring} is added to a {file:docs/CodeObjects.md code object}
using the {YARD::CodeObjects::Base#docstring=} attribute. In addition to adding
conventional comments, tags are parsed and associated with the object. The easiest
way to access tags on an object is to use the {YARD::CodeObjects::Base#tag} and `#tags`
methods, for example:

    # Using the Foo class object from above
    obj.tags(:tagname).first.text #=> "some data"

Because multiple tags can be stored with the same name, they are stored as a list
of tags. The `#tag` method is an alias for the first item in the list of tags.
Also note that the `#tag`, `#tags` and `#has_tag?` methods are all convenience
methods that delegate to the {YARD::Docstring} object described above.

### Adding Custom Tags

The `@tagname` tag used in the above examples is clearly not part of the tags
that come with YARD. If such a tag would actually be part of documentation under
a default install, YARD would raise a warning that the tag does not exist. It is,
however, trivial to add this tag to be recognized by YARD.

All tags in YARD are added to the {YARD::Tags::Library tag library} which makes
use of a tag factory class to parse the data inside the tags. To simply add a
tag that stores simple text like our `@tagname` tag above, use:

    YARD::Tags::Library.define_tag("A Sample Tag", :tagname)

This will now allow YARD to add the metadata from `@tagname` to the docstring.

## Tag Factory Architecture

Recognizing a tag is one part of the process. Parsing the tag contents is the
second step. YARD has a tag architecture that allows developers to add or completely
change the way tags contents can be parsed.

The separation of registration and tag creation can be seen in the following
class diagram:

![Tags Architecture Class Diagram](images/tags-class-diagram.png)

### DefaultFactory

By default, YARD has a few standard syntaxes that can be parsed for tags. These
are all implemented by the {YARD::Tags::DefaultFactory} class. These syntaxes
are:

  * Standard text: no parsing is done, but text is stripped of newlines and
    multiple spaces.

  * Raw text: does no parsing at all, no stripping of newlines or spaces. This
    is best used for code snippets.

  * Raw text with title: does no parsing on the text but extracts the first line
    of the metadata as the "title", useful for tags such as `@example`:

        # @example Inspect an element
        #   myobj.inspect #=> #

  * Text with types: parses a list of types at the beginning of the text. Types
    are optional. The standard syntax is in the form `[type1, type2, ...]`,
    for example:

        # @return [String, Symbol] a description here
        # @return description here with no types

  * Text with types and a name: parses a list of types at the beginning of text
    followed by a name and extra descriptive text. For example:

        # @param [String] str the string to reverse
        def reverse(str) '...' end

As mentioned above, this syntax is implemented by the `DefaultFactory` which can
be swapped out for any factory. In some cases, a developer may want to change
the type declaration syntax to be in the form:

    # @tagname name  description

This can be done by simply implementing a new factory that parses the data in
this form.

### Implementing a Factory

Factories should implement the method `parse_tag` as well as any `parse_tag_SUFFIX`
method where SUFFIX refers to the suffix added when declaring the tag. For example,
a tag can also be declared as follows:

    YARD::Tags::Library.define_tag "Parameter", :param, :with_types

In such a case, the factory will be called with method `parse_tag_with_types`. In
all cases, the method should return a new {YARD::Tags::Tag} object. Generally,
the `parse_tag` methods take 2 or 3 parameters. A simple tag can be implemented
as:

    def parse_tag(tag_name, text)
      Tag.new(tag_name, text)
    end

The text parameter contains pre-parsed text with extra spaces and newlines removed.
If required, the method could also be declared with a third parameter containing
unmodified raw text:

    def parse_tag_with_raw_text(tag_name, text, raw_text)
      Tag.new(tag_name, raw_text)
    end

Note that this method would be invoked for a tag declared with the `:with_raw_text`
suffix.

### Changing the Factory

To change the factory, set the {YARD::Tags::Library.default_factory} attribute:

    YARD::Tags::Library.default_factory = MyFactory

This must be done before any parsing is done, or the factory will not be used.
yard-0.9.37/docs/Templates.md000066400000000000000000000453741466601756300160140ustar00rootroot00000000000000# @title Templates Architecture

# Templates Architecture

Templates are the main component in the output rendering process of YARD,
which is invoked when conventional HTML/text output needs to be rendered
for a set of code objects.

## Design Goals

The general design attempts to be as abstracted from actual content and templates
as possible. Unlike RDoc which uses one file to describe the entire template,
YARD splits up the rendering of code objects into small components, allowing
template modification for smaller subsets of a full template without having to
duplicate the entire template itself. This is necessary because of YARD's support
for plugins. YARD is designed for extensibility by external plugins, and because
of this, no one plugin can be responsible for the entire template because no
one plugin knows about the other plugins being used. For instance, if an RSpec
plugin was added to support and document specifications in class templates,
this information would need to be transparently added to the template to work
in conjunction with any other plugin that performed similar template modifications.
The design goals can be summarized as follows:

  1. Output should be able to be rendered for any arbitrary format with little
     modification to YARD's source code. The addition of extra templates should
     be sufficient.
  2. The output rendered for an object should independently rendered data
     from arbitrary sources. These independent components are called "sections".
  3. Sections should be able to be inserted into any object without affecting
     any existing sections in the document. This allows for easy modification
     of templates by plugins.

## Templates

Template modules are the objects used to orchestrate the design goals listed
above. Specifically, they organize the sections and render the template contents
depending on the format.

## Engine

The Engine class orchestrates the creation and rendering of Template modules and
handles serialization or specific rendering scenarios (like HTML). To create
a template, use the {YARD::Templates::Engine.template template} method. The two most
common methods used to initiate output are the {YARD::Templates::Engine.render render}
and {YARD::Templates::Engine.generate generate} methods which generate and
optionally serialize output to a file. The latter, `#generate`, is used
specially to generate HTML documentation and copy over assets that may be
needed. For instance, an object may be rendered with:

    YARD::Templates::Engine.render(:object => myobject)

A set of objects may be rendered into HTML documentation by using:

    # all_objects is an array of module and class objects
    # options includes a :serializer key to copy output to the file system
    YARD::Templates::Engine.generate(all_objects, options)

Note that these methods should not be called directly. The {YARD::CodeObjects::Base}
class has a {YARD::CodeObjects::Base#format #format} helper method to render an
object. For instance, the above render example is equivalent to the simple
call `myobject.format`. The `generate` method is a special kind of render
and is called from the {YARD::CLI::Yardoc} command line utility.

## Template Options

A template keeps state when it is rendering output. This state is kept in
an options hash which is initially passed to it during instantiation. Some
default options set the template style (`:template`), the output format (`:format`),
and the serializer to use (`:serializer`). This options hash is modifiable
from all methods seen above. For example, initializing a template to output as
HTML instead of text can be done as follows:

    myobject.format(:format => :html)

## Serializer

This class abstracts the logic involved in deciding how to serialize data to
the expected endpoint. For instance, there is both a {YARD::Serializers::StdoutSerializer StdoutSerializer}
and {YARD::Serializers::FileSystemSerializer FileSystemSerializer} class for
outputting to console or to a file respectively. When endpoints with locations
are used (like files or URLs), the serializer implements the {YARD::Serializers::Base#serialized_path #serialized_path}
method. This allows the translation from a code object to its path at the endpoint,
which enables inter-document linking.

Rendered objects are automatically serialized using the object if present,
otherwise the rendered object is returned as a string to its parent. Nested
Templates automatically set the serializer to nil so that they return
as a String to their parent.

## Creating a Template

Templates are represented by a directory inside the {YARD::Templates::Engine.template_paths}
on disk. A standard template directory looks like the following tree:

    (Assuming templates/ is a template path)
    templates
    `-- default
        |-- class
        |   |-- dot
        |   |   |-- setup.rb
        |   |   `-- superklass.erb
        |   |-- html
        |   |   |-- constructor_details.erb
        |   |   |-- setup.rb
        |   |   `-- subclasses.erb
        |   |-- setup.rb
        |   `-- text
        |       |-- setup.rb
        |       `-- subclasses.erb
        |-- docstring
        |   |-- html
        |   |   |-- abstract.erb
        |   |   |-- deprecated.erb
        |   |   |-- index.erb
        |   |   `-- text.erb
        |   |-- setup.rb
        |   `-- text
        |       |-- abstract.erb
        |       |-- deprecated.erb
        |       |-- index.erb
        |       `-- text.erb

The path `default` refers to the template style (:template key in options hash)
and the directories at the next level (such as `class`) refer to template
`:type` (options hash key) for a template. The next directory refers to the
output format being used defined by the `:format` template option.

As we saw in the above example, the format option can be set to `:html`, which
would use the `html/` directory instead of `text/`. Finally, the individual .erb
files are the sections that make up the template.

Note that the subdirectory `html/` is also its own "template" that inherits
from the parent directory. We will see more on this later.

## setup.rb

Every template should have at least one `setup.rb` file that defines the
{YARD::Templates::Template#init #init} method to set the
{YARD::Templates::Template#sections #sections} used by the template. If
a setup.rb is not defined in the template itself, there should be a template
that is inherited (via parent directory or explicitly) that sets the sections
on a newly created template.

A standard setup.rb file looks like:

    def init
      sections :section1, :section2, :section3
    end

## Sections

Sections are smaller components that correlate to template
fragments. Practically speaking, a section can either be a template fragment
(a conventional .erb file or other supported templating language), a method
(which returns a String) or another {YARD::Templates::Template} (which in turn has its own
list of sections).

## Nested Sections

Sections often require the ability to encapsulate a set of sub-sections in markup
(HTML, for instance). Rather than use heavier Template subclass objects, a more
lightweight solution is to nest a set of sub-sections as a list that follows
a section, for example:

    def init
      sections :header, [:section_a, :section_b]
    end

The above example nests `section_a` and `section_b` within the `header` section.
Practically speaking, these sections can be placed in the result by `yield`ing
to them. A sample header.erb template might contain:

    
Header

    

      <%= yieldall %>
    


This template code would place the output of `section_a` and `section_b` within
the above div element. Using `yieldall`, we can also change the object that is being
rendered. For example, we may want to yield the first method of the class.
We can do this like so:

    
First method

    <%= yieldall :object => object.meths.first %>

This would run the nested sections for the method object instead of the class.

Note that `yieldall` yields to all subsections, whereas `yield` will yield
to each individually (in order) until there are no more left to yield to.
In the vast majority of cases, you'd want to use `yieldall`, since `yield`
makes it hard for users to override your template.

## Inheriting Templates

Parent directory templates are automatically inherited (or mixed in, to be
more accurate) by the current template. This means that the 'default/class/html'
template automatically inherits from 'default/class'. This also means that anything
defined in 'default/class/setup.rb' can be overridden by 'default/class/html/setup.rb'.

Since the Template module is a module, and not a class, they can be mixed in
explicitly (via include/extend) from other templates, which allows templates
to share erb files or helper logic. The 'default/class' template explicitly
mixes in the 'default/module' template, since it uses much of the same sections.
This is done with the helper {YARD::Templates::Template::ClassMethods#T T} method, which
is simply a shorthand for {YARD::Templates::Engine.template Engine.template}.
It can then override (using standard inheritance) the sections from the module
template and insert sections pertaining to classes. This is one of the design
goals described above.

For instance, the first line in `default/class/html/setup.rb` is:

    include T('default/module/html')

This includes the 'default/module/html', which means it also includes 'default/module'
by extension. This allows class to make use of any of module's erb files.

## Inserting and Traversing Sections

The ability to insert sections was mentioned above. The class template, for
instance, will modify the #init method to insert class specific sections:

    def init
      super
      sections.place(:subclasses).before(:children)
      sections.delete(:children)
      sections.place([:constructor_details, [T('method_details')]]).before(:methodmissing)
    end

Observe how sections has been modified after the super method was called (the
super method would have been defined in `default/module/setup.rb`). The
`sections` object is of the {YARD::Templates::Section} class and allows sections to be inserted
before or after another section using {Array#place} by it's given name rather
than index. This allows the overriding of templates in a way that does not
depend on where the section is located (since it may have been overridden by
another module).

You can also use `sections[:name]` to find the first child section named `:name`.
For instance, with the following sections declaration:

    sections :a, [:b, :c, [:d]]

You can get to the :d section with:

    sections[:a][:c][:d]

You can use this to insert a section inside a nested set without using indexed
access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:

    sections[:a][:c].place(:e).after(:d)

There are also two methods, {Insertion#before_any} and {Insertion#after_any},
which allow you to insert sections before or after the first matching section name
recursively. The above example could simply be rewritten as:

    sections.place(:e).after_any(:d)

## Overriding Templates by Registering a Template Path

Inheriting templates explicitly is useful when creating a customized template
that wants to take advantage of code re-use. However, most users who want
to customize YARD templates will want to override existing behaviour without
creating a template from scratch.

YARD solves this problem by allowing other template paths to be registered.
Because template modules are represented by a relative path such as 'default/class',
they can be found within any of the registered template paths. A new template
path is registered as:

    YARD::Templates::Engine.register_template_path '/path/to/mytemplates'

At this point, any time the 'default/class' template is loaded, the template
will first be looked for inside the newly registered template path. If found,
it will be used as the template module, with the modules from the other
template paths implicitly mixed in.

Therefore, by using the same directory structure as a builtin YARD template,
a user can customize or override individual templates as if the old ones were
inherited. A real world example would further modify the 'default/class' template
seen above by creating such a path in our '/path/to/mytemplates' custom template
path:

    /path/to/mytemplates/:
    |-- class
    |   |-- html
    |   |   |-- customsection.erb
    |   |-- setup.rb

The `setup.rb` file would look like:

    def init
      super
      sections.push :customsection
    end

Now, when a class object is formatted as HTML, our customsection.erb will be
appended to the rendered data.


### Overriding Stylesheets and Javascripts

Template authors can override existing stylesheets and javascripts by creating
a file with the same name as existing files within the `fulldoc` template. The
documentation output will utilize the new replacement file.

YARD's `fulldoc` template defines three stylesheets:

    /yard/templates/default/:
    |-- fulldoc
    |   |-- html
    |   |   |-- css
    |   |   |   |-- common.css
    |   |   |   |-- full_list.css
    |   |   |   |-- style.css

The `style.css` is the primary stylesheet for the HTML output.

The `full_list.css` is an additional stylesheet loaded specifically for the
search field menus (i.e. class list, method list, and file list).

The `common.css` is an empty css file that an template author can easily override
to provide custom styles for their plugin. However, if a user installs multiple
plugins that utilize this same file to deliver styles, it is possible that they
will be overridden.

YARD's `fulldoc` template defines three javascript files:

    /yard/templates/default/:
    |-- fulldoc
    |   |-- html
    |   |   |-- js
    |   |   |   |-- app.js
    |   |   |   |-- full_list.js
    |   |   |   |-- jquery.js

The `app.js` is the primary javascript file for the HTML output.

The `full_list.js` defines additional javascript loaded specifically for the
search field menus (i.e. class list, method list, and file list).

The `jquery.js` is copy of the jquery javascript library.

### Adding a Custom Stylesheet or Javascript

To load additional stylesheets and javascripts with every page (except the search
field menus) generated from the base `layout` template:

  1. Define your own custom stylesheet and/or javascript file
     (default/ is the default template name inside of the /template root directory):

         /template/default/:
         |-- fulldoc
         |   |-- html
         |   |   |-- css
         |   |   |   |-- custom.css
         |   |   |-- js
         |   |   |   |-- custom.js

  2. Create a `setup.rb` in the `layout` template directory and override the methods
     `stylesheets` and `javascripts`. The path to the template would be:

         /template/default/:
         |-- layout
         |   |-- html
         |   |   |-- setup.rb

     And the code would look like:

         def stylesheets
           # Load the existing stylesheets while appending the custom one
           super + %w(css/custom.css)
         end

         def javascripts
           # Load the existing javascripts while appending the custom one
           super + %w(js/custom.js)
         end


To load additional stylesheets and javascripts for the search menus loaded from
the `fulldoc` template:

  1. Define your own custom stylesheet and/or javascript file.

        /path/to/mytemplates/:
        |-- fulldoc
        |   |-- html
        |   |   |-- css
        |   |   |   |-- custom_full_menu.css
        |   |   |-- js
        |   |   |   |-- custom_full_menu.js


  3. Override the methods `stylesheets_full_list` and `javascripts_full_list`
     in the `setup.rb` file inside fulldoc/html.

        def stylesheets_full_list
          # Load the existing stylesheets while appending the custom one
          super + %w(css/custom.css)
        end

        def javascripts_full_list
          # Load the existing javascripts while appending the custom one
          super + %w(js/custom.js)
        end

### Overriding Search Menus

By default YARD's `fulldoc` template generates three search fields:

  * Class List
  * Method List
  * File List

Their contents are rendered in methods within the `fulldoc` template:

  * `generate_class_list`
  * `generate_method_list`
  * `generate_file_list`

To override these lists you will need to:

  1. Create a `setup.rb` in the `fulldoc` template directory and override the
     particular method.

         /path/to/mytemplates/:
         |-- fulldoc
         |   |-- html
         |   |   |-- setup.rb

         def generate_method_list
           @items = prune_method_listing(Registry.all(:method), false)
           @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }

           # Here we changed the functionality to reverse the order of displayed methods
           @items = @items.sort_by {|m| m.name.to_s }.reverse
           @list_title = "Method List"
           @list_type = "methods"
           asset('method_list.html', erb(:full_list))
         end

### Adding Additional Search Menus

By default YARD's `fulldoc` template generates three search fields:

  * Class List
  * Method List
  * File List

These are defined in the `layout` template method `menu_lists` and pulled into
the `fulldoc` template through a similarly named method.

To load an additional menu item:


  1. Create a `setup.rb` in the `layout` template directory and override the methods
   `menu_lists`. The `type` informs the search field the name of the file.
    The `title` is the name that appears above the section when viewed in frames.
    The `search_title` is the name that appears in the search field tab on the page.


        /path/to/mytemplates/:
        |-- layout
        |   |-- html
        |   |   |-- setup.rb

        def menu_lists
          # Load the existing menus
          super + [ { :type => 'feature', :title => 'Features', :search_title => 'Feature List' } ]
        end

  2. Create a `setup.rb` in the `fulldoc` template directory and create a method
     to generate a menu for the specified `type`.
     The method `generate_assets` will look for a function with a signature prefixed
     with `generate`, the type value specified, and the suffix `list`. Within that
     method you can configure and load the specific objects you wish to display.

         /path/to/mytemplates/:
         |-- fulldoc
         |   |-- html
         |   |   |-- setup.rb

         def generate_feature_list

           # load all the features from the Registry
           @items = Registry.all(:feature)
           @list_title = "Feature List"
           @list_type = "feature"

           # optional: the specified stylesheet class
           # when not specified it will default to the value of @list_type
           @list_class = "class"

           # Generate the full list html file with named feature_list.html
           # @note this file must be match the name of the type
           asset('feature_list.html', erb(:full_list))
         end
yard-0.9.37/docs/WhatsNew.md000066400000000000000000001514461466601756300156140ustar00rootroot00000000000000# @title What's New?

# What's New in 0.8.x?

1. **Directives (new behavioural tag syntax)** (0.8.0)
2. **Added `--embed-mixin(s)` to embed mixins into class docs** (0.8.0)
3. **Internationalization (I18n) support for translating docs** (0.8.0)
4. **New C parser / handlers architecture** (0.8.0)
5. **YARD will now warn if `@param` name not in method params** (0.8.0)
6. **Added support for `module_function` calls in Ruby code** (0.8.0)
7. **Greatly improved tag documentation using custom template** (0.8.0)
8. **Tags can now contain '.' for namespacing** (0.8.0)
9. **Added "frames" links for non-framed pages for better nav** (0.8.0)
10. **Added Gemfile support to YARD server for local gem sets** (0.8.0)
11. **Server now displays README on index route like static docs** (0.8.0)
12. **Added line numbers to `yard stats --list-undoc --compact`** (0.8.0)
13. **Single object db now default (multi-object db unsupported)** (0.8.0)
14. **Added `--api` tag to generate documentation for API sets** (0.8.1)
15. **Added `--non-transitive-tag` to disable transitive tag** (0.8.3)
16. **Added `-B/--bind` to bind to a port in yard server** (0.8.4)
17. **Added `asciidoc` markup type support** (0.8.6)
18. **Added `yard markups` command to list available markup types** (0.8.6)
19. **Added `yard display` command to display formatted objects** (0.8.6)
20. **Added `--layout` to `yard display` command** (0.8.6.1)
21. **Added `stats_options` for the rake task** (0.8.7.6)

## Directives (new behavioural tag syntax) (0.8.0)



  The tags {tag:!macro}, {tag:!method}, {tag:!attribute}, {tag:!group},
  {tag:!endgroup}, {tag:!scope} and {tag:!visibility} have been changed
  from meta-data tags to directives. This means they should now be called
  with the "@!" prefix instead of "@". Note however that for 
  backward compatibility, the old "@macro", "@method", etc.,
  syntax for all of these tags will still work and is supported.





  Some backwards incompatible changes were made to {tag:!macro} syntax.
  Please read this section carefully if you are using this tag.



YARD 0.8.0 adds a new tag syntax called "directives" using the `@!`
prefix. These directive tags can be used to modify parser state while
processing objects, or even create new objects on the fly. A plugin
API is available similar to tags, and directives should be registered
in the {YARD::Tags::Library} class using {YARD::Tags::Library.define_directive}.

To use a directive, simply call it the same way as any tag. Tag syntax
is documented in {file:docs/Tags.md}.

### Notable features of directives

#### Directives do not need to be attached to object docstrings

Unlike meta-data tags which apply to created objects, directives
do not need to be attached to an object in order to be used. This
means you can have free-standing comments with directives, such as:

    # @macro mymacro
    #   A new macro, not attached to any docstring

    # ...other Ruby code here...

    # Using the macro:
    # @macro mymacro
    def mymethod; end

You can do the same to define methods and attributes, as discussed
below.

#### `@!method` and `@!attribute` directives improved

The method and attribute directives can now be used to create multiple
objects in a single docstring. Previously a `@method` or `@attribute`
tag would only create one method per docstring. In 0.8.0, you could
attach multiple methods to the same block of Ruby source, such as:

    # @!method foo(a, b, c)
    # @!method bar(x, y, z)
    # Docstring for code
    some_ruby_source

The above creates #foo and #bar and the source listing for both will
be `some_ruby_source` with "Docstring for code" as the docstring.

The attribute directive can take advantage of this functionality as well.
Note that these directives also do not need to be attached to a line of
code to be recognized; they can be in free-standing comments if the
methods are defined dynamically and not associated with any code.

#### New `@!parse` directive to parse Ruby code

A new {tag:!parse} directive was added that allows a developer to have
YARD parse code that might not necessarily be parsable in its original
form. This is useful when using `instance_eval` and other dynamic
meta-programming techniques to define methods or perform functionality.
For instance, a common case of the "self.included" callback in module
to extend a module on a class might be in the form:

    def self.included(mod)
      mod.extend(self)
    end

Unfortunately, this does not get picked up by YARD, but on the original
class, we can add:

    class MyClass
      # @!parse extend TheDynamicModule
      include TheDynamicModule
    end

YARD will then parse the code `extend TheDynamicModule` as if
it were in the source file.

You can also use this technique to register regular methods as
attributes, if you did not define them with `attr_*` methods:

    def foo; @foo end
    def foo=(v) @foo = v end

    # Register them as methods:
    # @!parse attr_accessor :foo

### Backward incompatible changes to `@!macro` directive

Unfortunately, in order to create the new directives architecture,
some previously supported syntax in `@macro` tags are no longer supported.
Specifically, macros can no longer expand text on an entire docstring.
Instead, macros only expand the data that is indented inside of the tag
text.

This syntax is **no longer supported**:

    # @macro mymacro
    # Expanding text $1 $2 $3
    property :a, :b, :c

In 0.7.0 to 0.7.5, the above would have created a method with the docstring
"Expanding text a b c". This will not work in 0.8.0. Instead, you must
indent all the macro expansion data so that it is part of the `@macro`
tag as follows:

    # @!macro mymacro
    #   Expanding text $1 $2 $3
    property :a, :b, :c

Note that we also use the recommended `@!macro` syntax, though `@macro`
is still supported.

## Added `--embed-mixin(s)` to embed mixins into class docs (0.8.0)

Methods from mixins can now be embedded directly into the documentation
output for a class by using `--embed-mixin ModuleName`, or `--embed-mixins`
for all mixins. This enables a documentation writer to refactor methods
into modules without worrying about them showing up in separate files
in generated documentation. When mixin methods are embedded, they
show up in both the original module page and the pages of the classes
they are mixed into. A note is added to the method signature telling the
user where the method comes from.

The `--embed-mixin` command-line option can also take wildcard values
in order to match specific namespaces. For instance, you can embed
only mixins inside of a "Foo::Bar" namespace by doing:

    !!!sh
    $ yard doc --embed-mixin "Foo::Bar::*"

## Internationalization (I18n) support for translating docs

YARD now ships with the beginnings of internationalization support
for translating documentation into multiple languages. The
`yard i18n` command now allows you to generate ".pot" and ultimately
".po" files for translation with [gettext](http://www.gnu.org/software/gettext).

Note that this tool is a small step in the larger transition for
proper I18n support in YARD. We still have to add proper gettext
support to our templates for proper generation in multiple languages,
but this tool allows you to get started in translating your
documents. Improved I18n support will come throughout the 0.8.x series.

## New C parser / handlers architecture (0.8.0)

The C parser was completely rewritten to take advantage of YARD's
parser and handler architecture. This means more YARD will be more robust
when parsing failures occur, tags and directives will now work consistently
across Ruby and CRuby files ({tag:!group} will now work, for instance),
and developers can now write custom handlers that target CRuby source files.

## YARD will now warn if `@param` name not in method params (0.8.0)

YARD will now give you a warning if you use a `@param` tag in your
source but give an invalid parameter name. This should catch a lot of
common documentation errors and help keep your documentation consistent.

## Added support for `module_function` calls in Ruby code (0.8.0)

The `module_function` command in Ruby is now supported in Ruby files.
It defines two separate methods, one class and one instance method,
both having the exact same docstring, and marks the instance method
as private.

## Greatly improved tag documentation using custom template (0.8.0)

We have completely revamped the {docs/Tags.md} to include documentation
for each meta-data tag and directive with at least one useful example
for each one. This was done using template customization and extension
available within YARD.

## Tags can now contain '.' for namespacing (0.8.0)

Prior to 0.8.0, tags could only contain alphanumeric characters and
underscore. YARD now allows the '.' character in tag names, and it
is now recommended for namespacing project-specific custom tags.
YARD has its own set of custom tags that are namespaced in this
way (using the "yard.tagname" namespace). The namespace recommendation
is to use "projectname.tagname", or "projectname.component.tagname".

## Added "frames" links for non-framed pages for better nav (0.8.0)

Frames navigation has always had a "(no frames)" link to get rid
of the frameset. YARD 0.8.0 introduces a "(frames)" link on non-framed
pages to reverse this, allowing you to navigate between framed and
frameless pages seamlessly.

## Added Gemfile support to YARD server for local gem sets (0.8.0)

The `yard server` command now supports `--gemfile` to serve gems
from a Gemfile.lock, instead of all system-wide gems.

## Server now displays README on index route like static docs (0.8.0)

The `yard server` command will now behave like static docs regarding
the index action for a project, listing the README file if present
before displaying the alphabetic index. Note that the route for
the alphabetic index page has now moved to the explicit '/index' action.

## Added line numbers to `yard stats --list-undoc --compact` (0.8.0)

Line numbers are now listed in the compact listing of undocumented objects
so that they can be more easily located in the files.

## Single object db now default (multi-object db unsupported) (0.8.0)

YARD previously would split the .yardoc db into multiple marshal files
for load-time performance reasons if it grew past a specific number of
objects. This check is now disabled, and YARD will never automatically
switch to a multi-object DB. YARD will now always use the single object
db unless explicitly set with `--no-single-db`. If YARD is taking a
long time to load your .yardoc database, you can try using this
option to split your database into multiple files, but note that this
can cause problems with certain codebases (specifically, if you
have class methods using the same name as a module/class).

## Added `--api` tag to generate documentation for API sets (0.8.1)

You can now use `yardoc --api APINAME` to generate documentation only
for objects with the `@api APINAME` tag (or any parent namespace objects,
since this tag is transitive). Multiple `--api` switches may be used to
generate documentation for multiple APIs together. The following generates
documentation for both the "public" and "developer" APIs, also including
any objects with undefined API (via `--no-api`):

    $ yard doc --api public --api developer --no-api

Note that if you use `--api`, you must ensure that you also add `@api`
tags to your namespace objects (modules and classes), not just your methods.
If you do not want to do this, you can also include all objects with *no*
`@api` tag by using `--no-api` as shown above.

Remember that applying an `@api` tag to a class or module will apply it
to all children that do not have this tag already defined, so you can
declare an entire class public by applying it to the class itself. Note
also that these tags can be overridden by child elements if the tag is
re-applied to the individual object.

This feature is a simplified version of the more powerful `--query`
switch. The query to display the same API documentation as the
above example would be:

    $ yard doc --query '!@api || @api.text =~ /^(public|private)$/'

But note that `--query` does not work when YARD is in "safe mode"
due to security concerns, whereas `--api` works in either mode.
This enables `--api` to function on remote documentation sites like
[rubydoc.info](http://rubydoc.info).

## Added `--non-transitive-tag` to disable transitive tag (0.8.3)

You can now use `--non-transitive-tag` to disable transitivity on
tags that are defined as transitive by default. For instance, in
some cases you might not want the @api tag to apply to all methods
when you define it on a class. Only the class itself has a specific
@api tag. To do this, you can mark @api as non-transitive with:

    $ yard doc --non-transitive-tag api --api some_api

Which will avoid classifying treating @api as a transitive tag
when parsing modules and classes.

## Added `-B/--bind` to bind to a port in yard server (0.8.4)

You can now bind the `yard server` command to a given local port
with `yard server -B PORT` or `yard server --bind PORT`.

## Added `asciidoc` markup type support (0.8.6)

Support for the AsciiDoc markup type is now introduced using the `asciidoc`
markup type (`yard doc -m asciidoc`). Requires the
[asciidoctor](http://rubygems.org/gems/asciidoctor) RubyGem library to be
installed before running YARD.

## Added `yard markups` command to list available markup types (0.8.6)

You can now list all available markup types and their respective providers by
typing `yard markups`. This list also includes the file extensions used to
auto-identify markup types for extra files and READMEs. To use a markup in
the list, call `yard doc` with `-m MARKUP_TYPE`. To select a specific markup
provider library, pass the `-M PROVIDER_NAME` option.

## Added `yard display` command to display formatted objects (0.8.6)


This feature requires the .yardoc registry to have already been
  generated. To generate the registry, run yard doc -n.



You can now display a single object (or a list of objects) in the YARD registry
using the `yard display OBJECT ...` command. For example, to display the
`YARD::CodeObjects` module as text (the way it is displayed in `yri`), type:

    $ yard display YARD::CodeObjects

You can also format individual objects as HTML. For example, you can format
the above object as HTML and pipe the contents into a file readable by a
web browser:

    $ yard display -f html YARD::CodeObjects > codeobjects.html

Custom templating options from `yard doc` can also be used, see
`yard display --help` for more options.

## Added `--layout` to `yard display` command (0.8.6.1)

The `yard display` command now accepts `--layout` to wrap content in a layout
template. Currently the `layout` and `onefile` layout templates are supported,
though any template can be used. If no parameter is specified, the layout will
default to the `layout` template. Example usage:

    $ yard display --layout onefile -f html YARD::CodeObjects > codeobjects.html

The above generates a `codeobjects.html` file that is self-contained with
CSS stylesheets and JavaScript code. This is similar to calling
`yard doc --one-file` with only the YARD::CodeObjects object in the registry.

Note that even though this uses the onefile template, the README file will not
be auto-included the way it is with the `yard doc` command. To include the
README text at the top of the onefile template, pass the --readme switch:

    $ yard display --layout onefile -f html --readme README.md OBJECT > out.html

# What's New in 0.7.x?

1. **Macro support and detection of DSL methods** (0.7.0)
2. **Inherited attributes now show in HTML output** (0.7.0)
3. **The 'app' directory is now parsed by default** (0.7.0)
4. **Added support for metadata (@title, @markup) in extra files/readmes** (0.7.0)
5. **Added `yard list` command (alias for `yardoc --list`)** (0.7.0)
6. **Added Git support in `yard diff`** (0.7.0)
7. **Added `{include:file:FILENAME}` syntax** (0.7.0)
8. **Added `{render:OBJECT}` syntax to embed object docs in extra files** (0.7.0)
9. **Added improved templates API for custom CSS/JS/menus** (0.7.0)
10. **Added Ruby markup type (`-m ruby`)** (0.7.0)
11. **Added state tracking variables to Parser/Handler architecture** (0.7.0)
12. **Added before/after callbacks to SourceParser** (0.7.0)
13. **Can now use `--yardopts FILE` to specify a custom yardopts file** (0.7.0)
14. **Added new `-t guide` template for guide based docs** (0.7.0)
15. **Github Flavoured Markdown now works out-of-box** (0.7.4)
16. **Added `-m textile_strict` and `-m pre` markup types** (0.7.4)
17. **Reorganized markup types 'text' and 'none'** (0.7.4)
18. **Add support for `rb_define_alias`** (0.7.4)

## Macro support and detection of DSL methods (0.7.0)

YARD will now automatically detect class level method calls, similar to the
way it knows what an `attr_accessor` is. By simply adding documentation to
your class level declarations, YARD can automatically detect them as methods
or attributes in your class. Consider DataMapper's "property" declaration:

    class Post
      # @attribute
      # @return [String] the title of the post
      property :title, String
    end

The above declaration would be created as the `Post#title`. The optional
`@attribute` tag tells YARD that the property is an "attribute", and not just
a regular method.

In addition to basic DSL method detection, YARD also supports macros to create
docstrings that can be copies to other objects; these macros can also be
"attached" to class level methods to create implicit documentation for macros.

Macros and DSL method detection are discussed in much more detail in the
{file:docs/GettingStarted.md}, so you should read about them there if you're
interested in this feature.

## Inherited attributes now show in HTML output (0.7.0)

Inherited attributes will now show up in HTML documentation using the default
template in the same manner that inherited methods do.

## The 'app' directory is now parsed by default (0.7.0)

YARD tries to follow the "It Just Works" attitude in writing developer tools,
and therefore has added `app/**/*.rb` to the default list of globs that it
searches for code in. You no longer need to create a `.yardopts` just to
list your app directory when documenting your code on rubydoc.info.
We should have done this a while ago! And don't worry, YARD still checks
lib and ext by default, too.

## Added support for metadata (@title, @markup) in extra files/readmes (0.7.0)

Extra files (READMEs, ChangeLogs, LICENSE files, and other guides) now support
metadata tags, just like docstrings in code comments. By adding @tag values
to the top of a file (no whitespace preceding it) inside of a `# comment` line,
YARD will detect and parse these tags and store it for later usage.

Tags can contain arbitrary data as well as arbitrary tag names, however the
tag names @title and @markup are reserved to specify the document title and
markup format respectively. The title will be used in the file list menu,
index page, as well as any linking of the file via the `{file:Filename}`
syntax. An example of a document with metadata would be:

    # @title The Best Project Ever!
    # @markup rdoc
    # @author Foo Bar (custom tag, does not display in templates)

    = This Project Rules

    == Contents

    ...

Note that previous versions of YARD recommended specifying the markup of an
extra file with the `#!markup` shebang, but the `@markup` metadata tag is now
the "best practice" for specifying the markup format of an extra file.

## Added `yard list` command (alias for `yardoc --list`) (0.7.0)

The `yardoc --list` command is used to list objects that are parsed from
a codebase. This can be used to grep methods/classes in a codebase from the
command line. `yard list` now calls `yardoc --list` as a convenience command.

Note that the `yardoc --list` command may eventually be replaced by a more
feature-filled `yard list` command, so `yard list` should be used instead of
`yardoc --list` when possible.

## Added Git support in `yard diff` (0.7.0)

The `yard diff` command can now perform object diffing on git repositories.
Provide the `--git` switch to `yard diff` with 2 commit/branches like so:

    $ yard diff --git HEAD~5 HEAD
    Added objects:

      YARD::Parser::SourceParser#contents
      YARD::Parser::SourceParser#globals
      ...

## Added `{include:file:FILENAME}` syntax (0.7.0)

You can now use the `{include:file:FILENAME}` syntax to embed the contents
of an extra file marked up in its markup format. This syntax supports embedding
Ruby source files and performing syntax highlighting on the code.

## Added `{render:OBJECT}` syntax to embed object docs in extra files (0.7.0)

You can now use the `{render:Object}` syntax to embed the documentation
rendering of an entire object (method, class, module) inside of an extra file.
This is useful when writing non-API based guides that might require listing
a few helper methods or classes. The {file:docs/GettingStarted.md} discussed
this syntax in more detail (with example usage).

## Added improved templates API for custom CSS/JS/menus (0.7.0)

Plugin & template developers can now more easily insert custom stylesheet
or JavaScript files in their customized templates, thanks to an abstraction
of the template API. This is documented in the {docs/Templates.md} document.
In addition to custom CSS/JS, developers can also create custom menu tabs
in both the framed and non framed version of the default theme.

## Added Ruby markup type (`-m ruby`) (0.7.0)

The Ruby markup type (`-m ruby`) will now use syntax highlighting for all
formatting. This is probably not useful as a global switch, but can be used
on individual extra files using the metadata markup specification discussed
above.

## Added state tracking variables to Parser/Handler architecture (0.7.0)

The parser and handler architecture now contain state variables
{YARD::Handlers::Base#extra_state} and {YARD::Handlers::Processor#globals}
to share data across handlers and the entire processing phase. `#extra_state`
provided a place to store per-file data, while `#globals` gives the developer
access to inter-file state when parsing multiple files at once.

## Added before/after callbacks to SourceParser (0.7.0)

The {YARD::Parser::SourceParser} class can now register callbacks to execute
code before and after parsing of file globs, as well as before and after
parsing of individual files. This allows plugin developers to perform
setup/teardown (and set global state or update the {YARD::Registry}).

See the documentation for the following methods:

* {YARD::Parser::SourceParser.before_parse_list}
* {YARD::Parser::SourceParser.after_parse_list}
* {YARD::Parser::SourceParser.before_parse_file}
* {YARD::Parser::SourceParser.after_parse_file}

## Can now use `--yardopts FILE` to specify a custom yardopts file (0.7.0)

The `yardoc` command now supports `--yardopts FILE` to specify custom .yardopts
options files. This is useful if you have multiple documentation sets, such
as a guide documentation set and an API documentation set.

## Added new `-t guide` template for guide based docs (0.7.0)

You can now write guide style documentation using a new 'guide' template that
only generates documentation for extra files. You would use it in the form:

    yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE

This creates the sections for the readme, a getting started, frequently asked
questions, trouble shooting and license page.

If you need to refer to class / method documentation, you can embed API documentation
using the `{render:Object}` tag discussed above.

## Github Flavoured Markdown now works out-of-box (0.7.4)

Due to the growing popularity of Github-Flavoured-Markdown (GFM), YARD now uses
the Redcarpet library as the default Markdown formatting library with GFM fenced
code blocks enabled. This means that you can use fenced code blocks inside of
Markdown files with redcarpet installed without any extra code. Previously, users
who wanted GFM in their Markdown would have to specify `-m markdown -M redcarpet`,
but this is now the default behaviour for YARD.

Note that you can still specify language types in code blocks without GFM in YARD
by using the "!!!lang" prefix syntax. For example (plain means no markup):

    !!!plain
    !!!plain
    Some code
    block here.

The GFM version would be:

    !!!plain
    ```plain
    Some code
    block here.
    ```

## Added `-m textile_strict` and `-m pre` markup types (0.7.4)

A new "textile_strict" markup type was added which behaves exactly like "textile"
except it enables hard breaks, so newlines behave as line breaks in the HTML
(using `
` tags). This option is added for users who want the classic textile
behaviour.

## Reorganized markup types 'text' and 'none' (0.7.4)

Due to the new pre markup type, the behaviour for text and none were slightly
reorganized to be more intuitive. The following behaviours now represent these
markup types:

 * pre: Used to wrap text inside `
` tags
 * text: No formatting except for hard breaks (`
`) on newlines
 * none: No formatting at all.

In all cases, HTML is escaped from input. If you want no HTML escaping, use the
html markup type.

## Add support for `rb_define_alias` (0.7.4)

CRuby code can now make use of the `rb_define_alias` function. Documentation
for aliases is not supported, however.

# What's New in 0.6.x?

1. **Local documentation server for RubyGems or projects (`yard server`)** (0.6.0)
2. **Groups support for method listing** (0.6.0)
3. **Single file template (`--one-file`) support** (0.6.0)
4. **`yard` CLI executable with pluggable commands** (0.6.0)
5. **`yard diff` command to object-diff two versions of a project** (0.6.0)
6. **Added `--asset` option to `yardoc`** (0.6.0)
7. **New template API** (0.6.0)
8. **HTML template now adds inline Table of Contents for extra files pages** (0.6.0)
9. **Removed `--incremental` in favour of `--use-cache`** (0.6.0)
10. **Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.)** (0.6.0)
11. **Added `--transitive-tags` to register transitive tags** (0.6.0)
12. **`yardoc` now displays RDoc-like statistics (`--no-stats` to hide)** (0.6.0)
13. **`yri` now works on constants** (0.6.0)
14. **Plugins are no longer auto-loaded (added `--plugin` switch)** (0.6.2)
15. **Added `YARD::Config` API and `~/.yard/config` configuration file** (0.6.2)
16. **Added `yard config` command to view/edit configuration** (0.6.2)
17. **Added `yard server -t` template path switch** (0.6.2)
18. **Added `YARD::Server.register_static_path` for static server assets** (0.6.2)
19. **YARD::Registry is now thread local** (0.6.5)
20. **Support for ripper gem in Ruby 1.8.7** (0.6.5)

## Local documentation server for RubyGems or projects (`yard server`) (0.6.0)

The new `yard server` command spawns a documentation server that can serve
either documentation for a local project or installed RubyGems. The server
will host (by default) on http://localhost:8808.

To serve documentation for the active project (in the current directory):

    $ yard server

The server can also run in "incremental" mode for local projects. In this
situation, any modified sources will immediately be updated at each request,
ensuring that the server always serve the code exactly as it is on disk.
Documenting your code in this fashion essentially gives you an efficient a
live preview without running a separate command everytime you make a change.
To serve documentation for the active project in incremental mode:

    $ yard server --reload

Note that in incremental mode, objects or method groupings
  cannot be removed. If you have removed objects or modified groupings, you
  will need to flush the cache by deleting `.yardoc` and (optionally)
  restarting the server.

The documentation server can also serve documentation for all installed gems
on your system, similar to `gem server`, but using YARD's functionality and
templates. To serve documentation for installed gems:

    $ yard server --gems

Documentation for the gem need not be previously generated
  at install-time. If documentation for the gem has not been generated, YARD
  will do this for you on-the-fly. It is therefore possible to speed up your
  gem installs by using `gem install GEMNAME --no-rdoc` without repercussion.
  You can also add this switch to your `~/.gemrc` file so that you don't need
   to re-type it each time. See [this link](http://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install)
   for exact instructions.

## Groups support for method listing (0.6.0)

You can now organize methods in a class/module into logical separated groups.
These groups apply lexically and are listed in the order they are defined.
For instance, to define a group:

    # @group Rendering an Object

    # Documentation here
    def foo; end

    # Extra documentation...
    def bar; end

    # @group Another Group

    def aaa; end

Note that these `@group` and `@endgroup` declarations are
  not "tags" and should always be separated with at least 1 line of whitespace
  from any other documentation or code.

In the above example, "Rendering an Object" will be listed with "foo" and
"bar" above "Another Group", even though "aaa" comes before the two other
methods, alphabetically. To end a group, use `@endgroup`. It is not necessary
to end a group to start a new one, only if there is an object following the
group that should not belong in any group.

    # @group Group 1

    def foo; end

    # @endgroup

    # This method should not be listed in any group
    def bar; end

## Single file template (`--one-file`) support (0.6.0)

`yardoc` now has the `--one-file` option to generate a single-file template
for small scripts and libraries. In this case, any comments at the top of
the script file will be recognized as a README.

## `yard` CLI executable with pluggable commands (0.6.0)

The `yardoc` and `yri` commands are not deprecated and can
  continue to be used. They are shortcuts for `yard doc` and `yard ri`
  respectively. However, `yard-graph` has been removed.

YARD now has a `yard` executable which combines all pre-existing and new
commands into a single pluggable command that is both easier to remember and
access. To get a list of commands, type `yard --help`.

If you are a plugin developer, you can create your own `yard` command by first
subclassing the {YARD::CLI::Command} class and then registering this class
with the {YARD::CLI::CommandParser.commands} list. For instance:

    YARD::CLI::CommandParser.commands[:my_command] = MyCommandClass

The above line will enable the user to execute `yard my_command [options]`.

## `yard diff` command to object-diff two versions of a project (0.6.0)

One of the built-in commands that comes with the new `yard` executable is the
ability to do object-oriented diffing across multiple versions of the same
project, either by 2 versions of a gem, or 2 working copies. Just like
regular diffing tells you which lines have been added/removed in a file,
object diffing allows you to see what classes/methods/modules have been
added/removed between versions of a codebase.

For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing](http://gnuu.org/2010/06/26/yard-object-oriented-diffing/).

## `yard stats` to display statistics and undocumented objects (0.6.0)

YARD now outputs the following statistics when `yard stats` is run:

    Files:         125
    Modules:        35 (    4 undocumented)
    Classes:       139 (   29 undocumented)
    Constants:      53 (   20 undocumented)
    Methods:       602 (   70 undocumented)
     85.16% documented

Note that these statistics are based on what you have set to show in your
documentation. If you use `@private` tags and/or do not display
private/protected methods in your documentation, these will not show up as
undocumented. Therefore this metric is contextual.

You can also specifically list all undocumented objects (and their file
locations) with the `--list-undoc` option.

## Added `--asset` option to `yardoc` (0.6.0)

The `yardoc` command can now take the `--asset` option to copy over
files/directories (recursively) to the output path after generating
documentation. The format of the argument is "from:to" where from is the
source path and to is the destination. For instance, YARD uses the following
syntax in the `.yardopts` file to copy over image assets from the
'docs/images' directory into the 'images' directory after generating HTML:

    --asset docs/images:images

## New template API (0.6.0)

The new template API allows for easier insertion of sections within an
inherited template. You should no longer need to insert by index, an
error-prone process that could break when a template is updated. Instead of:

    sections.last.place(:my_section).before(:another_section)

use:

    sections.place(:my_section).before_any(:another_section)

You can see more in the {file:docs/Templates.md#Inserting_and_Traversing_Sections}
document.

## HTML template now adds inline Table of Contents for extra files pages (0.6.0)

A table of contents is now generated dynamically using JavaScript for extra
file pages (such as README's, or this document). It is generated based off the
headers (h1,h2,... tags) used in the document, and can be floated to the
right or listed inline on the page.

## Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.) (0.6.0)

Simple meta-data tags can now be added at the command-line and registered to
display in templates in a number of pre-defined ways. For instance, to create
a freeform text tag, use the following:

    --tag my_tag_name:"My Tag Title"

You can also create a "typed" tag (similar to `@return`), a typed named tag
(similar to `@param`) as well as various combinations. The full list of
options are listed in `yardoc --help` under the "Tag Options" section.

If you wish to create a tag to store data but do not wish to show this data
in the templates, use the `--hide-tag` option to hide it from generated output:

    --hide-tag my_tag_name

## Added `--transitive-tags` to register transitive tags (0.6.0)

Transitive tags are tags that apply to all descendants of a namespace (class
or module) when documented on that namespace. For instance, the `@since` tag
is a transitive tag. Applying `@since` to a class will automatically apply
`@since` to all methods in the class. Creating a `@since` tag directly on a
method will override the inherited value.

You can specify transitive tags on the command-line by using this option. Note
that the tags must already exist (built-in or created with the `--tag` option)
to be specified as transitive. If you wish to do this programmatically, see
the {YARD::Tags::Library.transitive_tags} attribute.

## `yardoc` now displays RDoc-like statistics (`--no-stats` to hide) (0.6.0)

As seen in the `yard stats` feature overview, `yardoc` displays RDoc-like
statistics when it is run. The output is equivalent to typing `yard stats`.
To hide this output when yardoc is run, use `--no-stats`.

## `yri` now works on constants (0.6.0)

Templates have now been added for text view of constants, which displays any
documentation and the constant value.

## Plugins are no longer auto-loaded (added `--plugin` switch) (0.6.2)

This is a backwards-incompatible change that disables plugins from automatically
loading when YARD starts up. From now on, you should manually declare which
plugins your project is using by adding `--plugin PLUGINNAME` to a `.yardopts`
file in the root of your project. You can also re-enable autoloaded plugins
by setting `load_plugins` to true in your configuration file (`yard config load_plugins true`,
see next item). You can also set `autoload_plugins` to a list of plugins
to be automatically loaded on start.

If you are a YARD plugin author, please make sure to inform your users of these
changes.

Note that `--plugin` switches passed on the commandline (not via `.yardopts`)
are parsed before commands are loaded, and therefore can add in new CLI commands.

## Added `YARD::Config` API and `~/.yard/config` configuration file (0.6.2)

There is a new global configuration API that can be accessed programmatically
and set via the `~/.yard/config` file. The file is encoded as a YAML file,
and looks like:

    :load_plugins: false
    :ignored_plugins:
      - my_plugin
      - my_other_plugin
    :autoload_plugins:
      - my_autoload_plugin
    :safe_mode: false

You can also set configuration options via the command-line (see next item).

## Added `yard config` command to view/edit configuration (0.6.2)

A new `yard config` command was created to view or edit the configuration
file via the commandline.

* To view the current configuration use `yard config --list`.
* To view a specific item use `yard config ITEMNAME`
* To modify an item value use `yard config ITEMNAME VALUE`

## Added `yard server -t` template path switch (0.6.2)

The `yard server` command now accepts `-t` or `--template-path` to register
a new template path for template customization.

## Added `YARD::Server.register_static_path` for static server assets (0.6.2)

The server now supports a command to register static asset paths. If you are
extending the YARD::Server modules, make sure to register your asset paths
through this method.

## YARD::Registry is now thread local (0.6.5)

Creating a new thread will now implicitly load a new Registry that can be used
to parse and process new code objects independently of the other threads. Note
that this means you can no longer use the Registry across threads; you must
either access the threadlocal object directly, or synchronize threads to do
the processing in the initial registry's thread.

## Support for ripper gem in Ruby 1.8.7 (0.6.5)

YARD now supports the Ruby 1.8.7 port of the `ripper` gem to improve parsing
of source, both in terms of performance and functionality. When the `ripper`
gem is available, YARD will use the "new-style" handlers. You can take advantage
of this functionality by performing a `gem install ripper`.


What's New in 0.5.x?
====================

1. **Support for documenting native Ruby C code** (0.5.0)
2. **Incremental parsing and output generation with `yardoc -c`** (0.5.0, 0.5.3)
2. **Improved `yri` support to perform lookups on installed Gems** (0.5.0)
3. **Added `yardoc --default-return` and `yardoc --hide-void-return`** (0.5.0)
4. **Multiple syntax highlighting language support** (0.5.0)
5. **New .yardoc format** (0.5.0)
6. **Support for yard-doc-* gem packages as hosted .yardoc dbs** (0.5.1)
7. **Support for extra search paths in `yri`** (0.5.1)
8. **Generating HTML docs now adds frames view** (0.5.3)
9. **Tree view for class list** (0.5.3)
10. **Ability to specify markup format of extra files** (0.5.3)
11. **Keyboard shortcuts for default HTML template** (0.5.4)

Support for documenting native Ruby C code (0.5.0)
--------------------------------------------------

It is now possible to document native Ruby extensions with YARD with a new
C parser mostly borrowed from RDoc. This enables the ability to document
Ruby's core and stdlibs which will be hosted on http://yardoc.org/docs. In
addition, the .yardoc dump for the Ruby-core classes will become available
as an installable gem for yri support (see #3).

Incremental parsing and output generation with `yardoc -c` (0.5.0, 0.5.3)
-------------------------------------------------------------------------


Note: in 0.5.3 and above you must use --incremental
  to incrementally generate HTML, otherwise only parsing will be done
  incrementally but HTML will be generated with all objects. --incremental
  implies -c, so no need to specify them both.


YARD now compares file checksums before parsing when using `yardoc -c`
(aka `yardoc --use-cache`) to do incremental parsing of only the files that
have changed. HTML (or other output format) generation will also only be
done on the objects that were parsed from changed files (\*). This makes doing
a documentation development cycle much faster for quick HTML previews. Just
remember that when using incremental output generation, the index will not
be rebuilt and inter-file links might not hook up right, so it is best to
perform a full rebuild at the end of such previews.

(\*) Only for versions prior to 0.5.3. For 0.5.3+, use `--incremental` for
incremental HTML output.

Improved `yri` support to perform lookups on installed Gems (0.5.0)
-------------------------------------------------------------------

The `yri` executable can now perform lookups on gems that have been parsed
by yard. Therefore, to use this command you must first parse all gems with
YARD. To parse all gems, use the following command:

    $ sudo yardoc --build-gems

The above command builds a .yardoc file for all installed gems in the
respective gem directory. If you do not have write access to the gem path,
YARD will write the yardoc file to `~/.yard/gem_index/NAME-VERSION.yardoc`.

Note: you can also use `--re-build-gems` to force re-parsing of all gems.

You can now do lookups with yri:

    $ yri JSON

All lookups are cached to `~/.yard/yri_cache` for quicker lookups the second
time onward.

Added `yardoc --default-return` and `yardoc --hide-void-return` (0.5.0)
-----------------------------------------------------------------------

YARD defaults to displaying (Object) as the default return type of any
method that has not declared a @return tag. To customize the default
return type, you can specify:

    $ yardoc --default-return 'MyDefaultType'

You can also use the empty string to list no return type.

In addition, you can use --hide-void-return to ignore any method that
defines itself as a void type by: `@return [void]`

Multiple syntax highlighting language support (0.5.0)
-----------------------------------------------------

YARD now supports the ability to specify a language type for code blocks in
docstrings. Although no actual highlighting support is added for any language
but Ruby, you can add your own support by writing your own helper method:

    # Where LANGNAME is the language:
    def html_syntax_highlight_LANGNAME(source)
      # return highlighted HTML
    end

To use this language in code blocks, prefix the block with `!!!LANGNAME`:

    !!!plain
    !!!python
    def python_code(self):
      return self

By the same token. you can now use `!!!plain` to ignore highlighting for
a specific code block.

New .yardoc format (0.5.0)
--------------------------

To make the above yri support possible, the .yardoc format was redesigned
to be a directory instead of a file. YARD can still load old .yardoc files,
but they will be automatically upgraded if re-saved. The new .yardoc format
does have a larger memory footprint, but this will hopefully be optimized
downward.

Support for yard-doc-* gem packages as hosted .yardoc dbs (0.5.1)
-----------------------------------------------------------------

You can now install special YARD plugin gems titled yard-doc-NAME to get
packaged a .yardoc database. This will enable yri lookups or building docs
for the gem without the code.

One main use for this is the `yard-doc-core` package, which enabled yri
support for Ruby core classes (stdlib coming soon as `yard-doc-stdlib`).
To install it, simply:

    $ sudo gem install yard-doc-core
    # now you can use:
    $ yri String

This will by default install the 1.9.1 core library. To install a library
for a specific version of Ruby, use the `--version` switch on gem:

    $ sudo gem install --version '= 1.8.6' yard-doc-core

Support for extra search paths in `yri` (0.5.1)
-----------------------------------------------

You can now add custom paths to non-gem .yardoc files
by adding them as newline separated paths in `~/.yard/yri_search_paths`.

Generating HTML docs now adds frames view (0.5.3)
-------------------------------------------------

`yardoc` will now create a `frames.html` file when generating HTML documents
which allows the user to view documentation inside frames, for those users who
still find frames beneficial.

Tree view for class list (0.5.3)
--------------------------------

The class list now displays as an expandable tree view to better organized an
otherwise cluttered namespace. If you properly namespace your less important
classes (like Rails timezone classes), they will not take up space in the
class list unless the user looks for them.

Ability to specify markup format of extra files (0.5.3)
-------------------------------------------------------

You can now specify the markup format of an extra file (like README) at the
top of the file with a shebang-like line:

    #!textile
    contents here

The above file contents will be rendered with a textile markup engine
(eg. RedCloth).

Keyboard shortcuts for default HTML template (0.5.4)
----------------------------------------------------

You can now access the "Class List", "Method List" and "File List" with the
'c', 'm' and 'f' keyboard shortcuts in the default HTML template, allowing
for keyboard-only navigation around YARD documentation.

API for registering custom parsers (0.5.6)
------------------------------------------

You can now register parsers for custom source languages by calling the
following method:

    SourceParser.register_parser_type(:java, MyJavaParser, 'java')

The parser class MyJavaParser should be a subclass of {YARD::Parser::Base},
and the last argument is a set of extensions (string, array or regexp). You
can read more about registering parsers at the {YARD::Parser::SourceParser}
class documentation.


What's New in 0.4.x?
====================

1. **New templating engine and templates**
2. **yardoc `--query` argument**
3. **Greatly expanded API documentation**
4. **New plugin support**
5. **New tags (@abstract, @private)**
6. **Default rake task is now `rake yard`**

New templating engine and templates
-----------------------------------

The templates were redesigned, most notably removing the ugly frameset, adding
search to the class/method lists, simplifying the layout and making things
generally prettier. You should also notice that more tags are now visible in
the templates such as @todo, the new @abstract and @note tags and some others
that existed but were previously omitted from the generated documentation.

There is also a new templating engine (based on the tadpole templating library)
to allow for much more user customization. You can read about it in
{file:docs/Templates.md}.

yardoc `--query` argument
-------------------------

The yardoc command-line tool now supports queries to select which classes,
modules or methods to include in documentation based on their data or meta-data.
For instance, you can now generate documentation for your "public" API only by
adding "@api public" to each of your public API methods/classes and using
the following argument:

    --query '@api.text == "public"'

More information on queries is in the {file:README.md}.

Greatly expanded API documentation
----------------------------------

Last release focused on many how-to and architecture documents to explain
the design of YARD, but many of the actual API classes/methods were still
left undocumented. This release marks a focus on getting YARD's own documentation
up to par so that it can serve as an official reference on the recommended
conventions to use when documenting code.

New plugin support
------------------

YARD now supports loading of plugins via RubyGems. Any gem named `yard-*` or
`yard_*` will now be loaded when YARD starts up. Note that the '-' separator
is the recommended naming scheme.

To ignore plugins, add the gem names to `~/.yard/ignored_plugins` on separate
lines (or separated by whitespace).

New tags (@abstract, @private)
------------------------------

Two new tags were added to the list of builtin meta-tags in YARD. `@abstract`
marks a class/module/method as abstract while `@private` marks an object
as "private". The latter tag is used in situations where an object is public
due to Ruby's own visibility limitations (constants, classes and modules
can never be private) but not actually part of your public API. You should
use this tag sparingly, as it is not meant to be an equivalent to RDoc's
`:nodoc:` tag. Remember, YARD recommends documenting private objects too.
This tag exists so that you can create a query (`--query !@private`) to
ignore all of these private objects in your documentation. You can also
use the new `--no-private` switch, which is a shortcut to the aforementioned
query. You can read more about the new tags in the {file:docs/GettingStarted.md}
guide.

Default rake task is now `rake yard`
------------------------------------

Not a big change, but anyone using the default "rake yardoc" task should
update their scripts:

[http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0](http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0)


What's New in 0.2.3.x?
======================

1. **Full Ruby 1.9 support**
2. **New parser code and handler API for 1.9**
3. **A new `@overload` tag**
4. **Better documentation**
5. **Template changes and bug fixes**

Full Ruby 1.9 support
---------------------

YARD's development actually focuses primarily on 1.9 from the get-go, so it is
not an afterthought. All features are first implemented for compatibility with
1.9, but of course all functionality is also tested in 1.8.x. YARD 0.2.2 was
mostly compatible with 1.9, but the new release improves and extends in certain
areas where compatibility was lacking. The new release should be fully functional
in Ruby 1.9.

New parser code and handler API for 1.9
---------------------------------------

Using Ruby 1.9 also gives YARD the advantage of using the new `ripper` library
which was added to stdlib. The ripper parser is Ruby's official answer to
projects like ParseTree and ruby2ruby. Ripper allows access to the AST as it
is parsed by the Ruby compiler. This has some large benefits over alternative
projects:

  1. It is officially supported and maintained by the Ruby core team.
  2. The AST is generated directly from the exact same code that drives the
     compiler, meaning anything that compiles is guaranteed to generate the
     equivalent AST.
  3. It needs no hacks, gems or extra libs and works out of the box in 1.9.
  4. It's *fast*.

Having the AST means that developers looking to extend YARD have much better
access to the parsed code than in previous versions. The only caveat is that
this library is not back-compatible to 1.8.x. Because of this, there are
subtle changes to the handler extension API that developers use to extend YARD.
Namely, there is now a standard API for 1.9 and a "legacy" API that can run in
both 1.8.x and 1.9 if needed. A developer can still use the legacy API to write
handlers that are compatible for both 1.8.x and 1.9 in one shot, or decide to
implement the handler using both APIs. Realize that the benefit of using the new
API means 1.9 users will get a 2.5x parsing speed increase over running the legacy
handlers (this is *in addition to* the ~1.8x speed increase of using YARV over MRI).

A new `@overload` tag
---------------------

The new `@overload` tag enables users to document methods that take multiple
parameters depending on context. This is basically equivalent to RDoc's call-seq,
but with a name that is more akin to the OOP concept of method overloading
that is actually being employed. Here's an example:

      # @overload def to_html(html, autolink = true)
      #   This docstring describes the specific overload only.
      #   @param [String] html the HTML
      #   @param [Boolean] autolink whether or not to automatically link
      #     URL references
      # @overload def to_html(html, opts = {})
      #   @param [String] html the HTML
      #   @param [Hash] opts any attributes to add to the root HTML node
      def to_html(*args)
        # split args depending on context
      end

As you can see each overload takes its own nested tags (including a docstring)
as if it were its own method. This allows "virtual" overloading behaviour at
the API level to make Ruby look like overload-aware languages without caring
about the implementation details required to add the behaviour.

It is still recommended practice, however, to stay away from overloading when
possible and document the types of each method's real parameters. This allows
toolkits making use of YARD to get accurate type information for your methods,
for instance, allowing IDE autocompletion. There are, of course, situations
where overload just makes more sense.

Better documentation
--------------------

The first few iterations of YARD were very much a proof of concept. Few people
were paying attention and it was really just pieced together to see what was
feasible. Now that YARD is gaining interest, there are many developers that
want to take advantage of its extensibility support to do some really cool stuff.
Considerable time was spent for this release documenting, at a high level, what
YARD can do and how it can be done. Expect this documentation to be extended and
improved in future releases.

Template changes and bug fixes
------------------------------

Of course no new release would be complete without fixing the old broken code.
Some tags existed but were not present in generated documentation. The templates
were mostly fixed to add the major omitted tags. In addition to template adjustments,
many parsing bugs were ironed out to make YARD much more stable with existing projects
(Rails, HAML, Sinatra, Ramaze, etc.).
yard-0.9.37/docs/images/000077500000000000000000000000001466601756300147645ustar00rootroot00000000000000yard-0.9.37/docs/images/code-objects-class-diagram.png000066400000000000000000001731201466601756300225440ustar00rootroot00000000000000PNG


IHDRO{IDATxuXTKnnٵv v]kJIcwH"
* "0]t+1}}<3\f|sa@40(B!
^
R(B!O/?BQUWUiTH(xT=(Ӿjk(BK!wwwʤ Dx.;ul\VP vON	H
l[/;9"*?5'4r ~\	o=$-8..@DžjE~.KW!@}?iF7Hh:OY YqEƔ5k'@>PH*73-/L@،6gkt'<
N9&O2a"j]0
L,LV`	n_ɀp$u?-rnbj[9te͜ [wt;j&V|Ow+. k5!O[IUs-)+Oo\$bAl^x;KޖE6Dxt[%uS
z=^87ߕXl
ߑ~@bK5Bc5pV'K
t8ՎoVCPaɒxaFrR.<
lշbE_h&ٚ&3gcQˎL$uܸ1,JO@ A|\> OKf	y8&&Ȓ8q"Pv
Uk}ri7ކͺoh/^
%K^
R/Bx)K^
PDfwO1bXD_
6|"dxߟh0]:X
C_]AA>I7}>POܛ^Kx	/%^u2g=	/UPG [[*^n,^1@d(`o%?pP#^jh&`XH[	]w-[J	Ubf۬/%3`XpwK0]6Yx(B Ye0}VcvC6#֐
v%@^!֌l'ivGKd]s1lp,@V7"֌EУf
༬o7Ha	 矍"ϟ^[xڽb8
8n\4dKG@R4ME{`4	U~0Dx	oeO{yw^lخQA|ݫcsdȖU./Ō'?i%okdoM@]kZ@3Kgbo_O-&[!^Kx	U詄~(^W.xyOx8G"OlWEW^@,-$*sKxoV!ˮ;|0y'sz9Z/k-vf^p2x`%R6Vk<L ~pQ=k!=6	5HX	ۇ^[x6h*/2 K
i="&pW-y>SmEcnF+
+=g;d7/s"N3Hhی[GüZ\n~ER0\K-r9Jx
%Q6׼;8#u?-\x6bT
9J/^Nx	o)5'9U:vySE4ǹX3{V+z\Oҏ0{TKx,ZP.I$Lbp¢b"c!ώGGGEGGE&mnHtṗ0KxNߩ
0ކ 5MZ@!୑^Kx	gWM: v7zkL4OÖLH.Kx	oK8x<#tycZeKz1iފQe{~;?ʓlz/2o@J:%bTYE$mW9:v	^6qNDx	o}
ϊo$@qׁ'xV497Ax	o}M3V^l@dN*hI?]n++blt1%W(7[p&}[nn^>c}l/ϲ@;laLuFb`xN2ךp%>OؘQeRzO
k5MXm"׶y8H/x'yas:I򕖁S@轝G\M
{ƆޝSx9k@@֔!L]g$:([{:I&^xO
Eȷ#<$
Ds/t%$3T7v+žl0#cDsPg/;2<7)xYh40X,k`^ޏǛkHE[m}o
`K&.RBtJ#Cݵ%,	XPYF/oM^q/)eS
O~8l7'ړ,X ^Gɯ_6B.q:ړ&HU*\uHl~F^['lx#Cm[~]1x"z'7a;Z9dzW!xB^pY)WyWȎ|^[3xz;i&@W?-<3c_z-wc}{kuvv3M?菙JTK(pZ%!ݸN^%5rX9d+drҧJxoe%r2@e@(cYr2oKx	o-f22
;/HkkKxo%&Bx	/%=ާGVUO[Y[_+BkO/_;/Maycn#zwϝdn%!YC;Kxko\ee:JFxe=_*.v}R7SBn"notdx]ZO 8Ў=&Ys͞/fD{o:N(iS]"VT}+z!6oz/X!Y~qogčJxf]:Vco,%[*ٗ,8^`zq@'Sp"X)R >!'#fV=`A@gd밄*޼6o[(4YbӤn@=*3K*	
8t=JGL6Kxkl()ݥ7T6r*;us|9$Dr:''	jv@[#o7upz>o%bZLV3l(_hΈ4cr1ŀ`n_of2^$vl`O9	n\YD|a>`$pgdzvH8–YӶ%G@@8AZxs\
8#p%%c<~ W^|U/!W~\/%*dy-WD߶}.OnۤX{]oً	/)
N>o<+FX
M0Gh$`u;}(,2"K`D6I8gJ_,%5*;ߎ4A*'zf>Ln|'Q@!@7GM8̜_U[cM+{87vqkKxkokw]PuCs]9G:̞
L]+FsF uI+=̚m4]T+`oHHKxkl(_]}})At?4xfs`H}-I? G9H'_GF]*>FĎ59nAJx	o4lբ^ad#6
s7YW)Wz%E-Ax	;e0xmrs&ZI҄&@n^[xybʚǤ={"t_ Ƚ/]Z'Z]V2Am7jgڲaiW/ிnW)ї@x^[sx9YE_·m>[XKHAx
oΔ?NNsvmr>ѥm
^ɩOBx	o^Kx	gwWpQ>k~,\L`[K87<=82](2"^ws^[SxE׳+%9,iJOX{cJX+y{CxS)-߾[h	2!=c&.v[sx+.R\"LÓZ2Njh(
(9'"/2+Oɒ
*#blGԴy	oYmΖ붥!sцӫo[ys7d+iYcjk˝?Nlt'{9- e\%29:DELWo=h~א	⑦!
%)g(9Ʈd
!CHQe_97ͼߞ~m+`yj拀Vh	5H<8w|<	,@QTNPM/ѥ?:O\y>VV/Aظq1:uhw
~0]h'u~W}9^thp$`BeMKA?oW:%5[6z54;XEFWGz.vͣLG1uacOr:قce%Ͽa}
xJ'_%5V?{*:n3zͺFG؃KoY}Qaܚn]27UڮiXL{vہfg/a\H{ruӀGHu~\p|K&
uL[ F[S=Jn~(5&_^«pxZ{d YOXye>2Kx
%~xRKTgAwٻe
d|nAn¢b@$[Tr&^1\>Гi<߮?-0Z,a@k`\t-^[xcFloƆxoy8j|0$^$3_'V\0ԙ['mfz5'eK΁^r@kqVwQ\@&0f-at/ݦq7/iC"3^6~ڭnCna=skMV'H`/eξ8ck_-vdba%ρP8,=鈃Q<^V,R}).>/uD1_wZ'~r5yXOx3m1͂Ms }p5)[5KxkoF=]l;>Rwp8w**
%^Kx	/%u7H.%U\/ -P*DhZ*oCTv
s.&S ^«xxT=K['R;y|J/U|T[w-@lD{x{{{{/U<ʀ%AuI/œBʚ)x6Kx	/%^Kx	/%{.*7;|	/UdRNy;_=uxɸ#7SKxoE
QdpoT,	/Udyh1l@/	/U|BՀ̻%
o;G
Ž'"A帼xrųthiCx	o)eIzH6R*#6*kN5T6ކWt%(ྴ/^«x+*4'ͷQw^]/%e	/m8xٕ	x@`p`Ox	"iǖOT*4ފIv;.PH)o[1$2U7_	U]cccc4U@c/an^~~~~~MqJx
o
h.,fUƛ''WtU_
h;ǘܯɎ;vlGeUۏa3Fކr&!'bq_%xu/Z"er(^]/%snHZ1 {됨ҧ_rUl&^[xFJsMc&9[t'ⱄ+ފQe<_৾{4r# ~*lū]Byž%V\ajCWra7]`6emjVySqE3n%xOv?%T6u-7M
kJOR
px
	Gx	oMdP,9@ΡM"ҲڃR624޺++*JTu.*(6VrЍWeaQq>z)
T=ʚ;'hwL 2{Bv+=	{L"X;_@)9aSr/kNz;Nrnʶ\6xItXlQޝ\`ln?&'^ʢe$0~71@j`vzH:؈☐Ҹ$ =0c>	%~Cx	o
	6SF8>eҳBwǢA':|~uv#nC('!vzq6D֎bKx$:%~xw1Ku^w^[xeԃDfLK=UȍtT,k%uwq$w
	+=H6XlfOv`%L
)o2^k~vF"u\=PCgwf!q
<5H4Ҹ6䦋wbAx	o<̛q<qZ7Dc7
(gCp8xD
?GHbq-q_-ۙ*omͷgrMҼ	~e(]mM{}W@qIZE?ǣ&nWJFXa|[)[p5#$(4ZRg|wMT:w;3H$OTG2c@2%uV6ȋl*zHPZ6օ:>߾-c4Qx@R
0v=t'KxkoŴb=
@%8ÜPBdJh~k~|E*T>
#Ɖcrn{
#]բ#/#INg36ciJ)~mߎC>f?܇с>7#b_e^[xk!i'	/mxx,%
/INx	~/)yDHa#I揁.xM'lNݰPocdMMvӵi`uWݨ6MQh`\<ޏ(esviM>]x4*e1ٸ#:#@Kt,@R%uҨV=#n0MIg/YmΙ#]^=y/M;qH z-ڗFXi$ڶ͹E!Ƨ!\i֭+*cMͻp78=׋:.TSyCQDwϑv%x-2q@^[wx
*/ݢ
@^+,>॒1=CZYAzhk%x?mgLuʟ9^qJj]j2@.})װ
;?i8-5#MFx	o
e=0[ K9΍e$@k[O~tQ^[ǽ
ˮNx#
cnj^5s$3۞7ZvS_JX#fΚ͗5鄍-^Wy录x{zvtyVX< U2"Ǽy_*=ӧ^rH]
~
%^Kx	/%u+f9r@e	/mXxGaպ=F$E3!5Rr{	yXT:1IAx+ފa4uƅ\usљWϽ$_O
?o
9^-EP~ӮIlT$M3E77hZ?oJH;؄ig y%G?10ˇ|ЋD7m/X/0U&
X/*-b{
Y@bN^^?/ 9%-^7j)ޑc\޺Xyc#ŰY\#xaJjCŌ.૚D&Ӗ؝+Gf	#[:MoTYĥ=LiF 5pLsJĻgDF"^gy97f;sjEPM2Kx%+T=^ƋF*{| dVh.d_4t8À%z(l3ㆵu_>}\HΐTŬ\bQ\$"'ʁbN?RXW\>O(B>_$rŀW<@SKx?:VQqg)^n[ڠ!O[DVg	^\mOv	oEXwKIEj/ Mᘗτ\`d@4ߥee}Ӗ,πUkW0mSVL;Fve%壋ߏ7im#jn0ި%YZZ>+;ovKJQhj^1;ª5 k
i:
N+gD*˚<N0oBx?{֭*W}n^?pt6Q,:+& כ#7P;Yx6K`	vLŵ@~?RN+gD)'_Grg7]U߽UY\b{&NC8Ƈ/tOP.Lr]E	S-)8qc7󒲅	iq@d	BT/Z ^Zx+&6=zk˕&Y+5L_4u$c86~fxӻGU+љ  q@xW8# y?uWf~Vxg7u.cU7`%iNeJ>wb- @R
(c~Vx?x*B(ԟa~6jwg~?BhUW^³]
n}H|1f>ɅE@Cj`/lEx?1KQmD-^|q,gzǙ_J)kw-J
/?"8^,NoÓEs<"|)^Cx?mzVҬX&۫l^ZI.)3^	B)}bT^[-5̈_e\];5[hM=Er}ƛѫz5UΘ`hPF"0'np`l^5{@x?cv(އ;pf~1ǖSo0pT?^Dx?XXy(ԟNgM)_7ӽn
Wp~	iaS>?/[1ph,œyeȋ잛	'5x+*p'k"D9i,Xl,q:eW+-\s+rg~,DmT
';FO/.͞H$#U1JO-9=v{ix{	'h~-D|9/^4w!V.
C|8^5~J	km˂UtYӉ`JyM^I/"Nvv]YqM°bų	x+.R0T;Ǧ0簪'@`h7s/uJ!Fz~hQC"kpΞw\o'G}<تxųfI*ָ>BՊUǻ+ӈmDpꖇ4!SH|~
&oFz=wzrnwr2{V*{qœ\oÏ_u/+媺d,/
{UHoyW{-v\:\An)
 _0V-.NTic k0ϰ)db)m?Iy;%qPdO\|D*}ܾMrs_>Şu+/;!
;/Zcael^{LZsbYLT/5AxrrzGތY)ki=2oÍtZNj[
Br/}؟Oކ^sw0#LVx#!*YoMr#6++_hV~kg-{B]k	p|9my5mnZTgrYg3 wvU,4|YmELSmjoRY3xWpFduƷit7%m[
H./0ȌhpiQ;g1`6ֿg^5 
-55b6aδSij^y2Fq\֬wY`Z9_dӷ@r΋i:Ns8a
I^UؤGxXn{\-_Z:,*jF^+(ɎrD5v
,/mRWcĩ?qo:\7
k/w*9mPZo֝F+wOf
{~8(2w4|56~.ofOAGM1LxѸV"Eې"P^xQiw€1|/_
Y6@px`8(
7}&ˁ;jjExPB
cʇ,/KYtclQEߠ}oi$Gy}Ƨ:WdM;	D[{gf7]neSC˚!)|]y.	[w.-y-Nfz|k
Sh8xvI	ધc)iŵ;r6dځވzxf"0®ͯ_Gzŋ;-^6!"WNO/[xY}\棻
;'V;gt1X«O\ѝ}OEEVCCAU(>5["\&
j/ęUOLTmpMK«yѬbsӪJH'i{TIc@UdR[ߣZ;[~=Q˻«a7Û3L-
׈iwNH+«m-X0L-bflm{EUD=_[0kgz(e0aWA#rF2Ì#;asmύW4d5UlUv30jeafMm_HnoNx2͜kqK{|0?;0mש9n!
^NtgtMGleL-jRDx.r1Z$RJ쐛um^Eeuk&[_'ɷM«`h]MjsxMUƯ>B-67שn!=jlNZ;nwQecu{]uյv펵;i;PlD.P@BB{>/HUa{03̽w=wia^WNE
鴢35kx5&"ߨI
5JjHSU&P,ūa[5lP">rKk
{$*jw(uqExy\xNr	X׀T?^%)SOɤ]1nsy]O~;ɒ0$^,
3nVItHh]Lx\QiqSL.ňԍ~fz€$pH}r
L8V&(NrЇ2uiEF`6AV(97 h)˘ayK=@E5xZx_USLXs 3XetS[>cw
Ն5o=|'&ClmnNM#~om\͋1@h1b^:>У8v9y"%9vބ$#!-$5)<IDH"ddF	i:dƧFH"3"cҢ)@!	ʈP1<<$2šTUL\T&Vy3D7%.^W'^Q{+)EbGR
Y3̄c;׻ZKH
"oQ:6UoUM^wFFS{l*ݹWW/xڪoxu/5獊яx_m.xjmd59hxu%&ﻓٵovܫr-mm@kڏnPEqzx~tw$gJG
Ucjxk6E⍋$$WXTy%^|8%_GK)RwHрK/+f/wp%lh)Zy@7 0Au	Oxa(:\PsDn~ΙU?Uͳk|xaBYo^xuéi++^!d_zuS*F̹
/{}.΂c+<=[6%Ud]=D`/x7/Q>Gx_Ά9ћ
]NԟGHSUQ "͹Z"kUo\sqfR'|*{\"nY7ޒf[5NroxÃCL	Ιh%;+)]bInܯPn}kk{,
o9kM=>7g,:U!^ol.0Y4/j<^ɗׄ-"K<‹x|
tkp
"=R^7d=˼M8Hx׷B\ ~QCMxZ{	|헇xK(}=UNjDA[4r&݄(3^z	V4zi/bEZTTn)	[:ifऊEG n4^ѓBܦfy[{{;DEw=Oׁ2ZrEW1 5?TPyL$mۿoWe!fj}kʽ:/ykg]l/@Q]&zOoeE7Bq'`rd!G
^Ll?iq#|V%̾ձM$";@,/ejH
PqmEGd`7:)4v`5A	]Iؿ⚔|>Z=I&5G.-k5\2*ךhm>SmJ^Vs
uԟeVk&<-HM+Oɔp)Gt痧%%7ywk:yw PfSW IGIo7J~ddֽ95&%
AutD6
NQX^lo&RDīeÍP{.*,tQ{k fM$[t_xcVi^c%%9cmeֳ싰pX	){_kU^i3'j`ڇV
.=~kn/\x~u~~ct>^v+PoN3owIʒuEVxI
u3DW@i=WOe_fY?H@+7Y5Qf)@}L"1,KoOTסA`]^2\v/
f-KN3cBu\
-mj|gsf=dVA}uSJҖ>'cW?Ċ>J@cMCj}"nΙ+cWW&:ި75HˊSx0>7$X#-68Zfe[GAƷwc:>Ip:,˯̯ɘLV&;Etkkܾ:qޯ)a6LSrTTР.+[x/WCtt@̑u%?:S5%^Q|j6A;c ^U:S)jdD5DzH~wv=A!SVPx1KAERe)ޢ{jn:le۲!du6877N1'guÄli_=ƫL0C݃=ױd|sV[{3wgZxo4IԤ2U^	k0}5Q	쿏ׁG#a`Iw=z2^I4Dn|}7OKsY AS|*[Y8WBX݀gmBWM˚޴ڊx`w	"WR
oT5oblhSh^9}:\p̟ZO"Yuâ+[rtbj@CpTV3]t9	mO$|H[AɜRmw$?TCXnLb?QƂ.c
z\y:pFustRx}j^7B%ic
$ٕ2Ϥ@ߙ?iuz
\d5l6󋸵AywM*,qGP_=x0x-%ne'C%Y;L:E\mzC~(p{eZm^:Jޛ˲UYd vZs۵ֻ"^mCv_4,6>d5ng[=]x?+	uQ-ꈼNC{MxʝKv{sP}eLa'2fԸ*R|A_ޘYS'ǫ	fJ^5
_8(G	H'L˝o	_o;9;@IP(~&kWdZG|	xɌ_ᕵ0E%+W
zڣgTYoQe\z'>oP(\`lL2*:;5/+4L\im
W]rd}Po鍯Do΄:^QXDxK[^haIk#<)
|~ʘs̝O82GtjWg涚N
l
] 	|-g8Ȩnpv$u=UzV/!x`x艌Ve'jdYkUM0
oAP!MߕY6fD$bdNg5\WZNGL@Lqldݛ*6^\뢒﫮54s~ܝuK޼NWf#|)*x$Ts!<@0'w?%=v
{~>kI)>9=K9
p3uĘZ&6[F*LZyڪzEdYO*fg1ʾ	ͅoN%{`H(d/yxw־jP[3Oy[}x7yܫ_tM25H3x"|VIb2Z<7^_LȌ;NaMǥ7F&ڂi&s<yKcC}" }{3yݶ_b˾qO9xG2@R'af҂x/oؙz4H}x]LWޔ3vϬa0A7= +cUpSgQ6ۓTȀ粦^ǽG%%{i9%'I8~iTCWo*fvB)e_]}x14{^jü~{P1a&fսxUS::/E‹92d磰Nz.|y4>'	d-hE9qRaVµ^>4cv{IIRxZQ#:MQ6`w* F+ƍ/A3,޽-!'ةWGP^Մs4o,gr+bQW	3N}N"!'TNkAdryfi6N7v`Yε7GPO]n}mHDG2.upPsQOz`O+.oC19YķY`	?*$,[35Ūţ
@#0g%`?XHyus	G  LzFkztv2}RMUXxe=@08<d^>/%PW$xzDEDAg(eĹ&Ak2P`.j/4oD[(=3B[w}Yt.=)[Rv6-&bc7yIn,
BՃas5ozA39=k-[^'\jKރV*Rd=Ԍۦ)\
xbB+3
xkֲMߩtW	1d&py$2^XY!g~wD9{'7oUo7ڧg=jVMj+i+Ķ^6(뷎+W;kǭ׷V#Żc %'T޼Ea"DѷT	.w&Ⱦ_-יlG[eY?yOM%;27{CBVhx{t;KR(bMZ Ԝk+}ե
{GsjWW:}gִ~y5CPrxXw`SG|ɞF0z`Qe/\Tڠ_F>^c3]L"ɳI~qbTL<+E' .=I۔,GQo#N9gzWymQ%.:$3j茮c4si7ew*
ٝפE\L\ck\,PmF$:慖CL߿isZ)=r6؂9g'	I묿GY:%?Ͷ3BpU!lj?WG 
;;Uw/jC2]yW RXb4!
T7L>(Ga?`Q<|sī2?q/!	N
vF֧UFpw7e1QrT*%m.)"= 
I𜆢tqmh4zfџxh9LoᓲE>Y/&+H}}LJ6Z1nՙGrsKrz=`b-Uy* ~ja㝪K66CV	&򯕇]6LĺtnW#
p?LM6
>yZ'O6~zƺëđ[8[3؄MC;(J
;gq{;n?GɜN?19
p'S>orB6]=ln$IߛE ;9Br͒q԰W=
p
w-: tۺru}ׅ#:t8[lt[WŚWf4Te;q68Xxv
/x'y>+?Rv,-\}jx V(-_H۵p?!kIƴm&=^̶xq"ևz-:(l/qn6O;aeOW8n8PqĖD+
οeW'u='-U;eo>qkRjX3t85-n[˃M=\.
CtkߜYNPk$M|Y91zYFxYv"qW{i{s~rpn*7~|y9)zFz;睗SVD~NĜ<}WC=jXCxbo+s[J:^es욊
ok +. =P18}Bw]@MlH#szhßkB^_J,/V߿[h(W/ֆcįoE!cniNIeVxHB0GTS`jZP8lc
ϏT'6M(@!/hX
o3԰Fu}䲱d,lnW	M{Kwsf{KȨϲќT<;=?`vuj?XlMUDwmTZP=ֱ{"gęΘ_s&WxEWQ*78UfTbDx T42EH̀FyzwD(%QQJc3 M<&*39"QixY45It7ebkWk=^:Gq9~g(l~QIثw`b?
d5CW]`>BUT$WKwmhd
bȢy?TSB:볨SQU?jZy9?YP̰ c*%0_PHAw@֤DJ#=v3@8Hb?L;?m|U!q*YLz^-?[=x]^9!jO[kx})n
үk6A?NԺM^W'{ww	* #a}u#cvJKùJUxeJ/Ew/0+:Qz9Nn}ݵakTl_
Pӧ7BKOG>$wE`QIת
23OD94
ΎFVA_52>S^w,I(M&d'	g;:'v3Z̓Yg|^mQ|}-KvV|\o?0tB?ӭ'?@x4v
%{V<)Bzƒ
pk^^=õz8t_6U@ys,|ǺspIMwD1uAMpM9lwk63Z#z6
gdlN`im564=o$Nҿ
v8rә,	@~lΜ6ِd8a.W5q&}CNvmFhʋ7jVE뛍r"cA)mg9w3%Me!٭g.!>
oN576~Wdws6Ձ2RNﻥˣ¯O'C9E7rbOy2VKqCy	;lu%]|jV9LO0t,v٤V/ĔDT2@&TY>P)P(A.P*dJJRY5A.SR2$t`yeJR\J
Y6Ǡ
a+SP*T@(T
-ܝ9<(Zm%GwD=gśN6mg㍭vΒ𲑽 {#Цc!u32:hgdtocC@/3IiĮø%FPƶ?ϾK6拧2cn%^yFk-׌>=M,^8I W7P!&Y$V`ȊoW;(xk8^^J[.0&[=8әD6	'͝!Dm:5MҢ([wEY
<+k.hZ!6+dBӽ
판
nfG[C{͒_*,o2p,h+^>^qCD
kȢ)
x\ՆX!vص6<󠊀ۅ)țXvqܯɮƹ-29x68V{ͥFc?	ƏD	I!/Q@Lk#Me*Hnխ(v9țLXu޼6&wX9L݄/H9V-2n1uÅl؁C9	V
,
rjuSiU%U+5)Vh\
k/"ڕu6ysnʸluނ`ݹo>%7f͝"9zsCpo0HFM;T \?hsۨqiK7rث-z\BUpMznʼnCg\+:	Rj}3ghTLi9]1sZuOPAnD\*R.*H%d-
JT7V-E*LRڐi߼KL@56Nښ齠:5u/v./_zVrn40>oEoxK"RxK-dn<ʛKt[z?oIdO0ms6YvpO;@{L$۝
qϸ#sa-oHlmmΞ3(n&yTR7@LX%i7?ڝ/_%i׸r:m=S*A7I<_pRogCIx
\;c *K57zcʿDtPpƖN/%TpM|xoE:v,ZHvpTa|WUM>~_b#+!f:WLĿ-w{ʷt^o\U[ L0bS3v?$-R7/,hlut.scݓJE@WW-dme^@wN51Ec/V]fEvyid*#Xl6mo*k֨Έ.71$.pl۠S6#uU#FpZ8H2]@J26ӍL#~mqU;(S?-FH]+C$H)kt>O=hjzajl5. ?
pwB!}Tal\a.ϓuw}W^S|xOtx(g:IOwRx_sOMocOW	zoT=$ͬ:_y@s抬7m텰[,y)a]K)RMbaC'[B*-pǵ\:D4ҭbN=QZ:eO
yހ2!oFX}m;?^~-Lm$lbP&[^<
vHd6Gt'YIggp[,EM-ӳ>gS%aId]otxxtCsm
_ʻǍ{c!^/olWUm `?pgӔ=lE:z7yɝ{~
{Ug1ײvp*d2LQ][wkX~]xƕYXyd#JRqk"{}xKGM~W-M_6|&^K
ڷ[;UJodI9y,R^U׸(K Թ95^UYq߾Wbfۣ7I+-ߜ۴y\}uX6o|jL4a;M5+-MKL4.M~
	<>*HxV6ljN,[fTBLn4֨7lʒS}lVYnکJf9M>zL(o	:)ʸA4_8r	xlSLvNѕź9cR:;/By*lяP)Dy@ "n.T"e[PL
*O|(UOv!ůw$Ԩh=E8 *ʤs6ʼn
=gӜ:GHU%SpjDU>r[lR-x=^÷6ڨ\aXT?m|w f!#ec*8oi}tκ.3{fej\aj_=pW^wL)[yV}>Hd;q
t3%\ a_3H-G8yҾE]%p	=gf@p6LKxF/ㆰOz_sYRCx[}}(cėݟNzfb:mͪl"U""\x+N	}9=ٽm%gl&l52%r/֢6	E~LmvdFTsJEG*SDRӷw;(x!UsYe+SM`ƌ[1Q`c@uYo7L]ju27˹[Lbev{N;8{]fK탰ES_"7
o"as#Ƒ7~)
q&߾q	,7Cw<stgARyv(NPcd`o)/T*cbɖM;h73lVRi*wAS}ޣ9849iZW3.[l`lllpP?7EϞf'^Ot |t_6^p~<3ԼjE3|^;Pɇ~lZ}*[]բSG1fWx2oXȑ	_ܺ_B|jCV4gҷzoOEYʼ2ڀ"
AseeJ~x+駹1}]k<PvՏ'x*O> CD)sr=]4FKxQ٥/#
;9'=Xkl4+Ĉao8i&,
W޶v)^X.\oz	-ثET4;޵{Z
1JsJ-[NԴ++`*U#*;Gpڜ`C=y/^.YM|j[!qY>5{ڢ;w[hV4-{=srNawfpl+7{_4MhHo^mi2W9wCG@\H
'B_H[mhW~*;VٟtҴ/ϲAzo\9^N(L/.q>[Iz._ԢM6^8x|Q㮰SYg|mhxu^ލz{8!
WjټwT/x{z_;4֧ISg%lmڗs=+ļaPP].d/	h>۩A)'
;>?wC̲[ę{;Bӗ[ك47lruptu<Bm999;}L2~[[:@~B\PJ/y{r)⊣s*7{H5$~2x`
a7_xz{{{Fo5bEWP=&O~ۡT*<70e_xիCW!`ߌWα˳y\dﯿ&c:bky;ղR^/сQWۆox_U96Č1ʈ22=N4%ɋoPĚsMT1T8g3ks)ReCwxתʶ`1jC_G$@6sb[] OR	Ğ}5:t1b
3|3L+t}kMkSMc\{/Gœ?D`oؽnlߵoޒ};t/8T]sۼ+/:0ȁr*vtUT
Ub۾ m(4xz`,}Rv.1O/_t;%=R-Txabݎ&s04;2'HΊ㿞h8yw=[c >R`Yr=+7w*uıVs]$mKe
mN:Ox_*X'/\d?>{ocK
Y^W4…W4*՛ZxGg>ZV.[z@gj4<$)Q#^AjpF47q?hXo!C Zox[lRsUxF( ۜ9ʋyzha\T-xJ"Nﯶkq#Ow!ofi.)ϟ[/)[mxv&Ĝw}>!i-5bRF8;f2i/}gJ"XMmjgU
>=:?+wCm\Bl\o(.2<{R.oJ	o^IdI>]:ߨ;]`tneo\G$pݶ,&u2WpsOy޹8=qģ.7
8*ǥ{k¦~mC`ۭ6?3W%vͭwT,dmsH:ujsfyۃ2	
EsPzɃ^m/Whܿv1
cPmk~NlaG%qH4]JLX):.UVicK3'gs*ژ`m"6p)_!Arơ\:k%onE3phN/*+%el*ۜr5HnZeK%=jަPXgp)j4gm‡Wh7LuF>*kB!X[:O+{vƵi+S7Q{Xer;<n͆I:C'7{ qDkhb 4?vykmqUe!=~=Cis܋lK)c*J_t8V@ՃI_ކxh4
5-݂'6z:\EK^W
[kR[4{%A.ކ;L~
Gr½EJKEa[{
/lixu=/F$Yyo۽rJ"|΃D+dhtIn=J87LUYx:[H
sۼ2:Îp|;:Q}cRƠ!8_]9@ɩcwYt͈Bs!Iý}5p3:EW{t~Z:fgldK9Agt}8x\*
T;D<x+Ns<2idkop;FEaD=fj|sr/p`gM12Ijj.7~fl	/$aԀ%WfLgauV&Hiʵ!ބw3Sa\n|]>?xƜQ't8[XAI"Y
)a	 >RDӑ[HtEEh -&6%56&%(e*2.=6I#Nѐ&^)%k)(
av)=,XMB\xHI&D*FDGF'L-چ}R.?M:z!WGrѣ1tܦWIrڵ+ok׮]	z+
m72dṑh=Xkw8CO6SxxgLZP2vWaUVj`nx5r[^^ZqnZ<)9Wc,8%l}"Vϥ
}?6bW+^𶚒}gAE?Lu\;*ĭ6堡vYKG;8ud/6o7tԍMC:~_2N_)޼2MߓN"ȖԾ[/}IQPgo΍!F98bEiO⨺-1xunGfI$riVW}}y
]twemas-}cnR+R	iVQ~~O{VnC

WΗ	Wj_X¹i4eKU߬*2W.\hnt1:qs͞;SK<RNɗfCyh춰7񞮭ToE^ڙ'R šxO_B
yxvr%5ٕӥAR6e%^")˾qzeM{?URY߯Qk͑:DAiE?+koHaai}-IT6`NRh+Rj+E2
tA1q=~xE	njwL۟e7p(dCWx{x 폏H~52
7G	^EX+x[U͜XqZZƎ3xIK.Mߨ@wdMBepq}*▍q3e̝.6ۓ؍^;c/\_uFzqc9]\,fqiFƞ`{c
;xG{VAa!l	0(ސifff2‡W?=+
"޹ِ7g8T)Hx}^_=zuMn\*(r/Rh3šݻ*BT!C
)ZEZML%<]#|dyo1TմisCGmݙu~фW>`ߧxE>.vyb1lid_uX!tP0ki#?~w^?QۉW9P#TzΥX!Pǩ2Y6x	͋`CF3i%(Jyxq.-#iK;tiۏP}fCi9+ҶR(A[Ɖp@T[<)Қě\{RSZqh\AJk%͒{ioQ{$ue'9$m<po#IEc(޳rncv<:w;\|hݗW9q/l%INE]S$IEF(چm$I*gqx޺$Iqxo>"߷ݣr$KQoSy̳wU5TG=oq?=[IfM~բiYM*gQ#^ERB|>%|VcA>qx7?X{ڇȺāx^YIZvvEuu..IUk/Wz*N$k/tMıxڒ$Ifm7:(x^=Im?[*^$IoG\+GS}xV-˺w(J
eܝ}8=zxGQ#.}Im;D%x#z;Ts8o
7
7؝nc*=!gw>
'$~6GUxTI ;٣{8owfӈ*gP'DjKqx3^xPX7sԱőx/|jŰ 7rXw1k%_SwKޫ8o>ezx)~؛@?N]7h޳+Kf?W͏Lxje1O$Nodn13fn'w`
`!+t3o{[o*m-~xxE
)^BűW/Miflr(Mο^Avxe1?vke?Z3]BsuMrQ˓4#5?~zCǫkha>SRo(^yo^[0
`hlaoW -e>j bEiD{ićśyͳʿ|ioX-wT#{Mf!"~xwPF$n)[+97>*=r͒ĻXӬZkA.?kt-;3wI9D}(l&+c
,0;mmx^Wx|TMIeI/_!!AA"Mː[mݫ]xk2'†WCjcsAVos'w%F;|9Gy
ex;/[*ٝ-͇)e"@07=Q0*4@c"@3vCΙ9뫹&R{&j
u.Lί?i8ŰN9+dzeaG,g([0nhdUͷLjj4|ݹFbʔ)7HXu)88N42c7O]iX7<3$5pY-1h@⩓,U8L6ko_ETg5oT3ѕi|x7K;]L/m`Ӡw;ر]w{[ـ{j/,N7N_x'?³o,c9qoVƆSՙq,w7i.ONhf݆X"k`ۄ3	+Hiu!Zޏ]ө'ݚysW:
K~@ ˕#	8B-\x^*xٜV^f^~7ō41ô3=6lA^ʙ/7؜mh+d&2>T;@׋m϶>u hB]xsg@Mլ&
ǟ}Ɛ~hN)77W/fdݬscYRu1~q8rqT`{tY[Nioq!A
jqRkp7L3t0男5Wx88vc zg^~xs
ql4.BРzְP3ʒ6gj]W?Oސf\+ξAЮR*/Zy
3,T&oO}(|L7y_XOLֵVsRm0w*BWν+-ZOJ!T;@VC+xtwIW-iʌn'/lMk$L̅-r2J֭ތkP5f8Ϛ&(髝PF]%59XM྾o!Û6xM2}-N\膳471˓c;
^ű;*jֻ~Ȍ'dw\{c5Ds5T;6]kcjE5
s>]WM5pl)t5j'L۔ܠ@_l4ƱoVLmIȣLN?d@18$(ކ3;meJ-;}u綹˃Rڵuj$
pw-*Χojn첊;[lv@}tby5fca@"#ư[Pf:XcU+0)o•nwX/FK
騷{S^u{N>*iŠL@v-{֮w?3Ip|dyjy:11-SŦYefoy<8p+uv@'nK#nWuDW}W~9S!wZn𽋇R3MxjxZ4Qw=ӏK?"oTrj)v/wg҇/s%%k:wz}tq݃[Mb^]jdO˲m#=~8WVq=

g\jS3KIW(uD	wLGK3v5<$EK$^)S}jԙ724g`j
:0c(ؖUc@$C3L'L~$:J^b%;Ť
J-$!nI ifqM|Y'6vg*.$kp4x޷Qׯd?0E>SLJ{.&߼1:tWUemn0E
p\35U:[]FrEWB$/.%}?NN<]Cߠ>Ҋ]~j}!*Sxo#k69N
MmSU]#TG;^8]UA!z~\,I]5F=?5jEu*W}fC~tNXY/ZaޥJH~:J\ȤZHJץ`Y.je4FJH[Ai6	E)[bHngi{&di+fݝ8AtMԼ֨u.!e!uS~WfmtVq03KE]jeX폹f>V**ԛ1xMݠԬ_%SݓnʎI-FXt
h㤈MUJgfU޻并#uނ7*oZs̍;(K]ƽL=.w0bqJYpyd]fxn39l\``MɸY\4ܫ[sfL!USMf҉]b|Mɶ;cE5؄E1'޶7!Tq|3-px/IBt^㫓&


ϢbCH	"]@d`!'E.Y*@w?-x^s+u|VQYֈEoN͙G涺.#=WL"i^*)='nފ6k	d6Uݺ\
?$e'ez٣|/33jZV'~Rx~w)C[_u@St._qCu}HwxMS$}0WlvZڥg5&#gك`o7Ļd0>cffE+-ӖLPu<9]VV\|]/!Nb^V	J=Ƃy+Dp,>FNۯycf;Mzq׋`=mSjz-p."$<|ix^-xo?<Hz?݂]?
.nڸ/׵+D/{u͸[oˈz9w]^ĠyxS@q%Pv	箲תʦ6m6)0pڹ	3ڊ]OiN3ޣza>heL3ڧFgU99yoň96xֆbg',"sdӽ:_mϽo*C`0NwZ=OxP}h*:hVJRK+t<`;'[H囜3N_C%<,{Jï|k[NjTWMs޽;Ao=k}{nIZ_
~,/vFS
B}U~ٵiVQo-bv	
i
JM}SܿBo~P b76Ue?h窲{ې@+o|gmi"k
x4Q6|a?[U&00oeve5Lm7]-<#ɫ*ʢF^yJ49e3ar{4I%s wwΐv"S_UeymNGE҇lkFʗR˻IO}SVݻ1ZǘYr铐oZu,Z:!/yh{FL=E-9QfC,nx2ި's&א~{W8{|H1l/cͿ6b^DM9;pZ6[
_>4|ʝf>\EN3feqi.#\\i>J+duo<,~7KH}H!ī[(I_ML2:$*4xu:N7}x?.$Iբ R$I*CU,
Z	g_x፨!I$-|xeM7L=xl^,Nӂ58%\lɢ_bCװI_jљI[IYqbBD(4Ȏk!_z՜lrǡq
N8c:ePXǍR`tfWsz׶x?=5=h޴Es}Y#Z-M"wYJы4iLdR!KfFXQ:}U`d`8MwO{=MŒz2f[vId֩AVd&}~/@F<@*Zxp+ľrn@xG!Pem*f0+;m+~tƲe&1k{HZ.FMǥcz6\.
ﹷAͳa5[1ryQ>/L'j&VuN4v.]LYÝuƻ9*
^{M^N,q?OlRx~^Y3}m]}y!6^Ѩ]Wm3"@LqgҒq.Bڻ=[+m	
;M|WXaq[>maa1߯S
[C]?ܳwxK?Yc=&utXөL.G)	""+""++""+""+""+""++""+"""+"~\3 dEZRwY_e՚?US˺
v\(‰B]Wx^Wx?Z-[@M>U3>r\xfG
e1/1
	oAÛ`Frs(\N\`X{3.C9mWO]Jr>z.5挭Lx?>;~_~8ۏu]?9lN-rno$M:O­ڃҧ̍tf8tBx?Sk?(]abwN2]|Ptta1hxp'k?~x%ᨬOonnfSݢɉ2NG`y'o͗v6Q6dy]?ә5gEx}lolaM;n>
YGx?
}X-"@/RPW8h D) UtFQW6z5	86
GdKΎMwmj1|܄SFlW/qӍ&-q!QB\eLrML|VB$GE&IulrT&RU	q1%Sx?wɝC 
otW-x2)qYxm64?\r¬&lgAH^6
DEA-_\^W6+
㗑o}|!yvJx_5ɿXPWCmd\)Vxoy6Nxlqxkya2.rq'c1"ݡۭ&4
p|5#ƳN.ytq<+3Z<^$5Y=^~r;[BIx	UĤv%(̤m3ٰ%yA?9i]8z}உY$!M{	
~]Gkx3x|ū
nOJFYHѻ{^9Ná.b?y`K$EhQUCu!QХ#2ί6kgcH,x,(s,+?~=$ã"0w
&H(N[UEql%%[P74pĢͼ^;󮗟-
l;s[IExX$VV,azi"|{"
8nVj:^V&vcATU>oy'.
ܩ#(jܤPe%mNrZQv:B=y[)Z.cW+}_?mYfUz-%&NQkJTx:N?6llNEƘoy^U_]wྺ@쌦S7SƎ6g:zpxs:?u^I?.:^_xk
^Y?W|/8sZxk޿"[c)N?8+g!vXB|CȢQ
b)+W\Wx^Wx^Wx+
\Wୡxx՞F%OOOOOT_Qxmx^C`y#ɓ'OIsM^נ>oZ"	yAAùhMVx
ͭ%_-ٔ۽T}x^{kٮ.AkMOx8
p"?3hCW5nT/ҹ]?2/?????OCv>kHxV͟4^ό6LZˏCx_ڛ՛R}kx3+
+
+%1[S:ھRۉz^ߤ(8^՗Dfplj?G#_ΙyR^9o.Ȁ&.66666:+^,HsNRTT*Jk`xuYY-6de|h+Ph	lmmmmR^?W\dM+wVLi])x9~2A}1ǂ㳵__˟{J-;4}
HƓj&\'&=7g_l<]hJ
=TePW]krkOoL<NӃUYM-f=PE{5pa1)?<Еe}Ͼ/_6ejnm“ڡem_N~,l!jjєOiТi+ot?zߪƫ/,})%ܚciiiiij3KKKKӭ7lr(W͝B>ŅsBwJ
RW6ՁwU
dm__:B{5lAwE\oXL<:辀3+n>
c).3=7%A]b? ~*@KiYhR;R%q_LL+cjvOy.)bQ[k,jЁ'ފޜx ٍݽ"G}'JlƫXhmF_Ssn}J/
&ጛk\
RHQ\iX	/|5:]Zis):zm/J7n4Hw~+J5ҹ@V;
oS"޻m_!L߁[7@$(?^.l^tyh{fz߳>Pz]]]]]Oua1_o*5G~=|\Ɨ]{09T\;Sr{aI;QZS="UNwO3Dı|]Xؚk{.Jv/YysXt.-+K߇$.gkk-yWRv/u+FivKવ>+[7X-KלޜErò,;7=(B컏·c! ?J\jk,EP<HJ4x_&_Ӎ*T-*}`cus_]8><O:0ޱo2|m{n΁mC{s.~њ88:Z;$`A=~;yC}SCoFc9;رs=\wM#cPAZ'pU<#p=Z¬J$HZ
˓_6+Jʄ@uSdxJ|NBT}?T@Sx74DIx"'A#
Â!"XL
*ݓ| DIiAZH	U[A_UVh>2Ҁxrsp캻z;&^ja'Bū[$?3}%}5V@dIgm|RjMfb}MytZx ,&qb.[ۏ	
T)U_UVq{qIǩaH [+Cl<^S"j/]OWh=W:F9[sX*ظgӣHykxc[nX_*áeU=lSL	/4piJϩa>e\5x93UWk0\ZA+W5,ѩ:4%@i<>ouFx^9 
+V'H	Ȫh=o|p&o}НyGAaM^pyŊʻ9^Z~s-DAv-+hbEAg__!53whkt#mD;z	h.xުۺT^aB$gډ-t?Rk
g"6ҥ'=gXAɸ[ux>>[^,qW,_uf?4>aE]Ks?6[uxUGޝp`f71St7~Awg98Txk~1Z}nCҏvOZ059
>=	'@]h^}Li7F)Q	/O%x
ĹpX'YAE҆[
q `]JCqiew:ϗu]o%YJ7#]I,	`T7fM1}i~	ɰwx~.Ͼ5|N"η;WCef]9zAVg^0y`0Wx^נ>Od$
/cw<:F\4K|.9`IT;Ɂ҅QKOZvl_/**W%tPwxfxy6^ސ?i˰RsUd=JYc<.EPPS@fQwGQb2$%SMՒq\L	i9*P%=zaJPEG'Q[j7v[g'{KKD󗖬~fP0fo-jxt8n2~vdn6]1+)_;3u^z^yC|~K4#x™?6xa
t-xz0EcVh$Nr:8atv}ogK(oC+£Zоn4a8с}AAW(how@!p:kt7ƣm<},rϵ_	/ia#f+bVOn4{Xsx1n/V"5ɩRYAMY&&:NӪ;}6z-iDIxkTt̲ez00`|l*BApW.5m֩%S	0d
|HqݻD֒BWp/_'J@p=0Kxkާ%ڮ^%K~,yF޿ĀvA]c. M+%TfJSJ45[PT'>iRܾCRWkUw]ˊVjⰍQ2N/&NVr Q
,vNjfO\q$537˰5YRH}mwH1*[?]-q^ͿO_YNy,QF{3FT-_KTT5nm`&v6 ߚ@đ}-JUc
^)"ͦF̕U5i16cʺ%
SAjqB[UYU]3Gk~]Uv=<pw@B\<]PdŲ+4[;w?t~vr._Ъ7L=Ap㍂['S=#0;޿j@ЦVMi4c۞*{[	OǛQ7aa1jToŽvxWPYP֡ZF&N̅Sa^~dsB;j?'U0Z*iU }9hXH8LF>p^o#y5FR/Vv
_?[{^ån~>p=Uy>]+`G03vpE*5[G[6퀑j<;-Qː£C$:?z9sGv
nOtU5x6wT/O\OB=sBɩ{]MM;	}cRJu;^[inn?~5sĞ	t/|J
ιeAPۥ
Z5x/[g˅Io\]Cι>;p{h+0,222<@~+wt҅
̫i5k݆)5_AO4h-h冂wNĘذ_jrh$aISWM;viiZx=(>,~#4k~

Ƿ6=`cn˅ӎJ/&2ū/=sKHc_<| :W58`zH Hf2iLx
bFs<bv#ʪ\>	l1rgCmxř3&v$㟎,2k|_^p]:=V;/ַ.Û'I	\+x^逾˻Vm뵉2'ZY/_URWKI"
buLf;A	P:"
UWtqIJ''\[I.`gڪH=j;x*[zۻ`S,CVW)2jߣ18VJ_%v
zB|b=:4^
(\'ɨ}.[agک@t+V*acD;h%:^Y
dڢTq?ͱ.))*+yXx$R:UxmVqt0.nmơK%OG6.2dWWx^?GsKKE[JKKKU:W54)D^ڈ;9<*S^j;6j!84X?;gEԨO]d,
Y#W{7Nټf-[\B#xJr{ֽۚ-X>F!mR@jaXY?Yg/v֧v
-;s
!K׬'E{R|;7o3O3cV
mUQUY2Sj;G},dE9ƣ+ap{:[٦a|~;hW~~kdtɇrM_O㐴i˻e+5m; 7H4bx.~^8E@~+ܕs}}>&âډ ݝ1J*RO$	$qCjYgN+>nx+ۿ9pI}mhH%6=i9ܨ/O>oN;ܩñFJEWN1?|fs|idtUe!?u2y'uoqNz&FJ.@'J_;\) ơ1RyPLpOr==r RhŇWT/5~Z8н{Jx+$2>g>(w_}O7S-rRGg6"nC߽ȧ[Q痲7!'I(Px+o2͖MìiL30prlmAH^^'
W>V&G⣿wӍ$ֹ
\kfe쑖6{aokZSK)4YH1 VޙWPI!/2C?Yl=y9KG,s]h6Fnk΍uMoyqZN9ca5=-:7IDhçDZ8
xJ\2Y&8/w|&QtrrW4O~ʕ_A8q]Nxś_*HT	)19yQP4:qq*ȍOIBb<-b8- 
o{Jp&
hX...'c^DtWyxEAvGa+kn>W;ANLx
+'Z]Wm?u=@y^אe;Lک#Kk/ɜQ%KXkq0T.
}n+ow,fRj#VFAx
b}lL>|[9k~m+7ɠ:&>Y/
WW(}U&ldސ6v{x57^A#ek}^Ng:SSo!%彼+ޏvW}gH;n+p1kHx>=_XfJQX&|f>hCx
Kw$ҎCx+oOɰ[VA^Wx'OPoM;qsIpPNxw_?~W5dw7fg7c5o-\X;y7,M5	,*.....	omU1o"nbu\5$v\R̺xR6~c?8ީO2&6[xuY-gf1
lFe_ں'{+'Zmx
b,\plhGZD8FBh?݌3srrrr:)xj6W}[s  	h9'qT}5ӈuE)
ՎY;2@A맣pCrKCj׀~RZq@=>@eŀ/II7 c'k@x0dXfJ;WWmלuO+,ǽ5p{+8<^fP!DFxdH7Zx\Μt2	+""T^jD=8'װisOӆ~oIOXaxE^WDDxED^WDDxED^WDxED^Wo?q">UIENDB`yard-0.9.37/docs/images/handlers-class-diagram.png000066400000000000000000000255011466601756300220020ustar00rootroot00000000000000PNG


IHDR+6kPLTE9fff֋f99d99ff9dd99ffd9fd8f899f8888fff9ڋ8d9f9f8ff99ff8df9f99f99ڎe9898f9999ڶ9dfdfdd98df8Ԋd9ٶfڶd8Vfֳ8ey9fk8yyڎf8y999d8dfL190Odٲcfd88f889effffڎ99f9fڎ9999fff999ڎy)IDATx^j0@QCϯ%Ȫh(duxRT5/	_ VQbE"V
+V#SX=+SlŠ+b呡RbEXAOHs[RGߡXQTVM==͊X+bt:jE"VXaV.X:!V'ܲ)VHXKYR&+~Xaeg,j+]DFCϜAnjd(B"i/+·qn)c\#s|Zv)ZŠʡ_##3H
+۲ŠX+HĊXk"sEbeHV_X5kYa国3m¸`
(|%*j[a'NhP=rI(֢e~~ڏ<]|"gw9<a}Y9?xɫAV+b|ߙB:*''3$gC{X+U,7Fd~:ap疢6n+uWʜBhe#PxpX؀+-+ZYQ2$|RYXd`d탺X+ikm `~5ɪ:V$\<؟p ضBܙ-6nz{^+b?m{4~Oâ{VJV$+|
+
+bE"V@8Xi+DJK_x[Ż*^a#L/mIznNfy5DJK_bi
A]Yo?dx_b PaS,)RZ*`E9**,PWvX*-U"i
d%TZ`EqV@]aWJT*ɪUXQ^+nJe(-bEVZĊX0{[vq]+oOr{Ru_#O6t4+Vp[}ž۟6`W`eTZ+8ʮ~~"Vh(m0̯>xE#Wla`}'6+=­Vzh9mp+{K1#eE0snq9GF{_0~V>
{NgHelOjJ^tˑ	udoE"V`_bre|LtU4+b%iC}
rwabo"Vz*qtS(+TUZ+7=GѬX"?{w+CMufxVNVdy:s|xkdLqk0 pX")nzu-+v+:0NV8DGO|*EZ9+;AvN+U?(.bt,h3m[JaE
|_J>aZg$RXµB[K@rPo)+,\Θa!T	VxNX|%.,ŒR+W
%WP%l3zd	V䯀J h30#o+E3<~X+9~XWĊX+bE"VĊ=wY48ҞJ
Wq$=
Xmox9*}T~hܒ@S)+[lYAy~q$<s9d?!oe+n(+aŠT
sz8sP~a!EgR#+q?;0Xqe=B'ώن,>BN'(ڒR%+qO@m_xBvNg݂ϓuXंô,'((I+	ôDV2I@Ng0L$
s:Y4LŊt+b%m2@AbEfEZo;	Yl%U+oUV2Vʞj
[M?Pl%cK쩦ڰ9	$AT_
d~=T_Š*,%e?5ՆWsd~)
PSmx'g~j"'a5$j헕E	_SMNXŊ2+P
RdM"V7X&m,c]<}r	,²,c`V
ݢ.u%Yvʲt_|L,_SF
׺(QS2-aY qE+~8sn2YaI,00d+ԱBvT[XcpV+/Z	Xn 'v䄲,00du+1?q ^,!X )
泂xfz'eeH'53k+e!|VgV+ceP'53XINXIVXؤs&JJPy嶽ܜWf٘~aw9EV+^#θ&V
y<&EV+^n|sY
ݕ+di'ƙċZb%fɞypVKbK\_!Lrô +`ŋ/vhda=+bEX+bE"'b%bJ2J*ePD_A!Js䫨]af瀐bG򍃐9 ? 3pƐbA$gmfv+5+af`!E9IP TQ	̎A'L+bE9	bERtw!VbN{)v_0fK5)dj)ژ!0[fEA{#+
1(pBYQ9W+^Sij-!0[*aEO}`l)p'9|Z^t
&aR+bIƋ)sL-zB(CXQXQYQ׀XQ}P^YQ׀XQ(k@׀X 'A!VbE!VXQXQk`S:Y"V^pV|ˁ
bNKPXYo&U"%d-b+dZp	:rfAu+q
`}r	TJq,8#z٤Vb+g+e-9HJ
ast$,($V5@gF7D~X+l$VĊXQX-ĊX"V䯈̐ŕG,{q+W)
 V=A@H_AL+XW^AĊLYW"J
Z{mۈ<
ttEE+u/0UÌBIZ~D0$|N3S$_VD#yDg/y~
+9"#\"aERgD0VaEXVVaIӤʨ?++Š+2η"JtStj1;VSNUmlAX)Nb,fa%Ddź]hXa%Z-+9u,KVN)aeGc
+
+L/ÉNJ" XaVXaaEXyͰɴr8VXaEX5t
+++]_QSU;[/T|)٪^_|٥VBvIuJ)fa(]*Xaes^V9/c.rIYWֻhT֕._})+7%\"ÿhSx
VmCNg
VX<nw
VXQV#zV4ߑߊVXaV.+!s
+d
+ۓ{:J*- a}<CL竺b+IM)X}T+m BElb%~Nz+Iub]iw'ŠCه\{P'7	Y	+
+
+?JwVί?Cr~{PwVϬ]fSϬn
+
+ʘkCuL`x+VXaVXaVXaVXaV@UYsU0bxކi+?ok*V˔Vv9zQ<7	A+&֕*) MيAH>e~%֊
+io>ey{Ъ.;Tк6+۲JgVX)Xa[҃ϬDx1=X9<+^ft*)Y9G>gVNrI,궬J~YaV.^cޥm{+YaVSJYa%wPcVX驦
+]~V42ٛ:r[
+
+
+
+
+>rVXIVXaVXg)+
+
+2|.
+22}`Vg\v(l,*,ʮ uɷy8̓< }f&5m*9X4TrT|>N=_}<diN7(\5S
J0.lUm'>++ns=W,ݓԕ"sojo0JGq'ͦ&N)5$9ەuձ Z޶+ϸChޚ*WuGWCGF\J#W|vx Zoە:I5Vsތ1Rn0J`zG
~"cO)ypűE7]q6;YT3WAp@
\a3:WnX 0?T+m{ϩ+XdW]AW<(PW3îv$l+KhJ+wHs;J;+O?Hǫ*Rg+!B5EԵŭHEb?rA:J+^iMsR
,۴ L@ʙܺsǶRjx5RrgCQd/?Qr[ae}[MͿWC%X
VI
VO+_ڻ ѫux~[aa#"mq{>u|++Hf%V4`xRG8qq
)lخt$҉:%OSq9+)i?|?TVLH`%]+`PVh^Bg%7Z`%>X+`D+;Vk
Xi>s~؈Mw@WYT,JIĪpYA▻ocVt4+V6SW9+ٽJ^yVdGLχzVy+nVig=+0kf+qMawwP96J%#M?Yiv߷(YhӤWc<ofJD_a
=+l^:<+zW&wx-A+ l(X/Q23!XzAH8eEBj[zK#VbD11GL`8_k붨ʸش}njxRb> ̈́Cm[(חSV+>. l(Ạ=3J|tEIEさaQCGG9}jdʊTGq ՄK
-ۂyV
XAmVJ¿D$\QK++bz'0&@&*-EVTe$^$.Ԕm.?o{tFݘ3j43g&Ky<dus5B*X!X	0܍cEXA
HuWO"\fvcXt3+JUw^NldXarpzR	"plceR+s	_y]bX+%V2x-*zn_Ն`Pwl2wR(*٨64
ͳrR
SGbnf%Simo5NMs6>cwX_o:)tn"I2IhgmpY<
V`KўbiQ8
Q}VI2OͽdH6w$#MZVXHV p;k\#pV$=Hʪ0gX˟#	
NFDj5)K9 8\Qι6F8H+z99?djԿy8UVZ+BJgEsm+yV0/6{0Iy
@p")cEkcdX.?xt8.+lc^JY9+}ĵs̊Kn6ȳ5TXcg=K~dvε׳1Y1';I@""{Ha`TXyŜcX1V撱b+Ɗ2?|qfŻU]VOg+JۮM7_z^J&Vf0n$+0EQLQk$OhI%3V1ql_Ȥs,|ƍd:BSŗL"evf`eY9rH!
$iX!qAK&2;#Эs(|ͫkH%p>ҜYh5

,@SŗL"evf`YbVA)S[aXWT09rJZ܌|xK5+uJrAdt
H>VMTcWS
AFP
ADZbRJ&+W) #!dy-od]X*?zE,]01o	`qTŠk+]_ASOI4aHm l--(.cJK$פ0x\Ў[W2Vf{XiD5V:$ě$TKXijIƊUsKנI8Vq̝{Gwh
Vʁ5??&+rf7.==],1dZ~0[n,+ʧg{Bpg|MkЖGmJ!a?.a‚%({`%V
V`+X
V<	nrV`{ߧ`e;2_tV.]wW}۽_S>W-Y)y-@tI}Qaerep#a"ujզb+bUBfycZENʪG!i|pi3lR)sa|*tpV!ҧr*	^Ѽ
~f#^b*	YπYUIe5F<SƄ&+00̅d*].tr!aPP|xlBnpL(vVK	]a׷h<7*\s|wa3Whd
/H53`6	N3ݘp' l@.Ԣ
y*bˋNF%mjD8e`H95\8߆WT˅6*$S9m9a߫l=,Fqa	tLk 5,[!B=j_{Zz1
I[kM)q&]o{ŵt;5ow1^ě}O8օ%|z[zawǤjkqo0ch,bY
=
+)0)~P0)La
S0)La
S0)~@W[-~T|	~yvScӞ)La
S8!¶0s%w	LM}FEPXM4l.dZ5}$X_X¦RQxRf7y8ۮK	lKh鴅*^%(La
S`\>nGзB>7>?kc	S0)La
7;{*,;jM^WkcYO‰nPX+URn/B$ٲiIX?bړLXL
oHXF-FX0jwE&ӥO[V
y5
#	W覹W
tBD5]F"ՃGbї3p!$T+F끚M¦YFyH>,^A5~]͹3H6GAҽ$a@O(ݮLŅPX=u)[Oج$N3OXz[60 5cJVXù" WǮj
L$!mdR&H?Mp-!ᤷ%.<jګe,g1Jc8
aA_6Qºs	^S 
+6(a/Wq5FۮN6a1=]6iKlSX&
6!W~)aoO-M ފ)P6Sy9Ca^xa{?r
k7MǿVJt=cSֽ==}OMGO&:HRۏ2[{YPk{}\$Z$k
Vpڌk)(\ZH7Iޮp{:$<Մ)qnZ;_^}k·݌)yqq2g
}p>7SX
'Npם
bzoAapPQ_-΂O(le@!.lqcNp-$iŝ!.t#B)}lLEҔ]0k
1#[PqaE
.ܫv:
;/qa
(nC+pݑXyr=
S50PZbé%Al0\PGwVXbl[6`%
Aᙡ^OXz/nS6"La
SX$LatO
0Пg)8ʻI}&'^΀NxDZupoyضYJ4D^9l;]8A+%(lj-
?0^M0z~d$m\51Ùp%;aMP/2^Jpzt;EV8k:)Y&L$'Cw-YDX`*b0FX--vLETF}"ėӉLb Fŋ^Z&Մ`N*=aMaAjr8ayL'JuG6"xOW08Wzyv,
kƯ?\?
kƟc2yx7

=/#,fR6Z[a
KVœ_B}Ka
S1d«n+<ǥNX;pm_%|~L>Lp9(\_C*pȝd0txhPXUMM`brhaivw%dO#S󱀰Q{aS5x|G)pG=u>F{h/{Mu>N2] b"i7ǒtM~On)\
SP\mۆK3O_PS̶Dc{UqtK5Gq)S:/L~'vimQ7/q7o6OS_/m)|z&a90)Oؔ΄M?6)²^F
?F8uHVxNdy֊-ץV0zڬW_8Kک鮄_\_FrX-FZ_` RMMfZ]+LaBZa

k)l(tfk
)4
eٛN,u3a؞Juwjn|OWpEM Lay&Vk/<>NN![
kBOwzRv(@p>NNMB_35b_dNAG)?.Qj|@_
zR8_pޡ[NYǏj|k/]Xna1Gp>NF:kЭ&5")X7P+S3itrJy..M'j,]
w";7UX{Q8	e環&^kTYngd
{
-ޖ~«yVFyTVA0)ELaOUApa\t^;(Aa
cNS_)pM\pETS]z{:,%DGs>l$΅m/K	pHtV/pa
a
A/v;V	SXaR_ҡt;HA{py~(ly~Ef?(.𴪰d
.Zbb"Yw&inAAimOK8Gjk}^
¸,&k
˞Uv0[iLFa{X
>p8]a

?W=/h尙T`7܂0}ZzaL+?*f8Zs
\@Wޅ)La_P=(}59p`0)La
S5)La
S(K0MfR4IEP}Px1k:
S0))
xU}:}~^'p0)6(La
o5(̚0)

޿ #Sn/Aa
S0\nzy>[~PmSm(<'d0)La
)LՐS-653I;mIaĀNY7$0au5J	-,L
Q
St0Sh\ۆQmy~0)^Pk\/
;2˻J§ob-)~76p"rPXG~81!&&i:nSoM$8%A5icqILad
pt:ᚠ]D:W	=#qLYֱ0/La
S0ii,?F)jv&٭0)q:(,(l
'p&"0Vº0,bejUQ2~]Lua
SX\ĮQDXpUK[i La1Q5.2#
p8v&&3),.E.r8q(`,V3̅eAb0M¾ٍV`C-2݀5J6um	mK`
t=_6_2EX!.}a>0)'FøPxµGP0'
SXq]
E))q~TLx
/+
g.ľ
EF0Bh)La
G̈́Sk0wA嫞OIXuLXf*UO%.Q.*U',	&	KؾBFhI#a
g$0po"Fz·cZ&|&l6EQK	h	/p>&&O)TJht|,CZ'Xcpw<#B|AJtp>!SӚN&ńY6-SXp6DQQX4K	( b@x8ؖp{:mxOG|.Aa
SZ5\>NXVX
#Nm)V§S¶0)\g	a
py~*)\N…~)\gia
kRŹ~Z=)La>0)L0[kf*a
=bGa?+{R<ϢFsa
00!
)n6Rh'La
a
GV,4/_Q\Z="SX\x000Յ۴)i@L#S3xP¬(Lm)La
ZsyV20)La
:2}
\	3e¶0!&[yXaXlF;

Yi[TU¶0!"/R®֨`9la%L
@,%dOa
S0)La
S0[py:a
W pEP^'(La
S0)La43iOI\(:(xP08K}۬M|8ۊ70((La
S06#}q9ƃ0)La
o3(La
S0)La
⛫qT)IENDB`yard-0.9.37/docs/images/parser-class-diagram.png000066400000000000000000000260271466601756300215020ustar00rootroot00000000000000PNG


IHDR%n:PLTEe9ڶ9999ڶff8yy9ڎffڎ9ڎf9ڶfffڎf99999ff99ffff99ff99ff999f9f9fڶ99ff9f99ڎfڎ8eV99f99fff8yyff9ٶٶf99fڎ9e9ffڶff9lf*IDATx^݇zqn@tג>l{zo;G/Yg2o_Db=ɉB
VBJ+&vY/$F/
j9Vgy2}ILWIvyH+!W+4x3VkS/v5[z{v[NuoW3*}kM]m|[$MN-\˩&q2'>]6֭XndP,o5=za>ԷT^XwN@U|#rjmo__JКD$	KwjNJ8V]sޖaL'5¯Vcp/kT!h%h%h%Č!ԟg&VVBJJZ	A+A+!h%tyA+A+Z	ZthE+Z	ZJЊ'v'hE+ZZr{u!iYO-VٵVEX&=jNf!%]'ъVf+cv6V
7w]~kӁ8ɩ[ި}=ѵ{oZop~M6Yj
GZV@i!nwZѪ![{ٱZ#ת׺kS6O["\jW}wmdhw&4u,xۧ=5oucӃ{ښJξb׮ziENtK?
Z՟G8MnM(;K^k5hMn[
Z\|:|	4u&I11o˙[Zծ;,vwp{ŢV_ڜ췵Z)B+iF^we_9߼yxuwU]zPjS|oiPSjNNo'nwNj}rLkE+}ke'6o
N=BpA+ZъVhE+Z: uB+uhEhVhE+ZъVVEvg+{Q:VUPCΪV4>f[wWU(҉TcߊV[ժZwTF\	,nZ1CV[wTF1
ZwW5|
ZwWuo5jݑ02MIZtٵvZUOV.ܕhoe'yٗo@+uDbLaU}ugZ[~B1f;'Dӝ"3+)؆}#v1emnoC+Z?uw<߯>XwN0E!Z=}zw^ʵL]hoZ+~vB{UZSBZe[ǻnZ{JUh՝/jNѶK=UҪҪhE#"layp!;V{WZU￥UѺogi\ڿ;ת>OU!M^k_h^j;׭Fpup#Zd+7&&zD"LܮoU$yVЪ{fi\8|=v_4kq?GpƵ:h
#8NVGp"h
#8OV0kkEӸ[IJwGZGwл#h h=ZZ;2@Њu#h9{nƯ(5`Է;tӷG}kC7Z
Z
Z
Z:M>T쪭hEk]1	n741YgkE+"j/Sv'pE뙐*.~,;~'pEc\>[uf=GW8F٥[Cߚe1O[U֪-V}k~'pE9*i}jkL
~'p}vZA5}kw}^9ux}kLvHQ㨴UZ5Գ&1o/;ZvH	he0@ߪr}3"!t]RS:-=PhEvfof:[vq]^egH'x6#ZU}kWk^!ɾUT&9sߪ:Ec[h6h[zR'Էnqc6ٻ۔:~lUXGw}cj]cJ}Mb5HگqM68h5"K@+ZX+A+Zъ'#hxZ5WC6ZѺ/1jE+uUulB> E[9Pzګr= V/Ru/Szگr= UZUwX;*bzLЪ[{2]VrX \3v>ZA,Z	ZUXCi)I}X{gXs\fĢP'VVhE+Z	Zxkxɱ5h h)hU5Nk?2LT:XЊUVkУxcRڙ06œe:Vҷzx{3KG\ݷh
}kGf&hEҽnu`euPhEkp@UjؔMA+ZZ	ZhE+ZъVUu ZCЪ)Z.7{fe8hEO=Ir߬1hE+jU읕5"hJ`ϬkE+Z!kשּׁ1hE+W3kשּׁkE+Z!kChoЊV:hE+ZJЊV[c!ԷF>+ZCjqEkO[!Է~4h
5i\j>h5i\:xJ}k|ӸP'VhE+1#sJ^-hE+ZъVVVVVVVBzH:O/E+ЊV@+Z|VhE+ZъVhE+ZъhE9&h=ozhE+ZъV>àUj>h@WZc
Z_:rqz
_)Z#
}V.Dku9KZ̾_[EkuH"x3Ck|Ak7}k*LaК&EVg9Zceҏ	#	u	Z	hE+Zъ֧B|ɳՊVhE+Z%h:hE+ZъVhE+Zz.ZO'hE+ZCVh1E36eZъl%"_M,EV6_z~S?.rpfi8hEk*V7KJ5߬Ӑ}+ZZ`Y;tm
VEjl
/V7q)#gn^]	fj
C+ZyR}kmJR@ZъVqx~JlVNhEk3͢h=AЊV7~?k\F+ZZI:z_n{Gm*ǡzZJ6fV8"^֒DF+Zz.]6hVrZ/gnգGk_Y58OAYӯںJ~՗UiUZVUiUZUY볕Һ~J:9^=LywJwf~̒\T0!&{\R#2o&|}_tttXJq4nw3*U*i{D3fE!.
hLgݧ%JVJ3ؖ,[6ZFu	B'!(K'5@=C3=X`Zo͉|-,UR#S3K	N@{N+Mθ (Tk+qwlWJ,h'K+$52^Њ|TvbʼnHlWJgdi8зf`RRJfnGǥhWJQB&@`A+C֥hE+Z׊VъV?	hE+ZT;׊V=kE+Z͎hE+dàurJmE+ϭ`"hߊVЊVhE+ZъVsYˢR[hE+ZъVhE+ZъVhE+ZъVhE+ZъVhE+ZъVhE+ZъV\粦S)4szDnBާVeh,W^ݾ-vǔIzql+ZA+Zj\5hEMVA+ơh'@ON
Zb//Ƅ
S~VW5SChE+ZъVhE+ZъVhE+ZъVhE+ZъVh{ʅZm,	~%[ъVhEpZekE+ZъUmJӲ-vl-WϧʶڣAkTx^O8{FLAkúӺk}kUcr?P}GYjTADfklsДmo}hր[MCjr_/knQz͠5S)ug=cΰw8R.ƱK۵IX+ZŬlrRVvUxU6nFH_+ъjdGƺH׿
^7h-۝zuk^N{'󄻤d[(#wkfyRO#jGTVU_-wjZeg2nM3֙"jEklMZ_O;iM_9}h,qpZ[u8穖ehUIU+Zck2.7+S_^5\J+Z[u)/V7w/"zKiE+Zck2.}[=Vdl]ڛ'ϭQ[Ҋؚ.l>	'Z^MV5|G4<{:OZ*۶:[B8ڷ֪j
>̬h}|"p6!T4vw>ĠuU5Hk8oV~QчŴ@	A)@kXA+Z'e"]Z
ZѺecGTh0l
u?a㻰G	ZhEh^hE+ZѺW?ߚ׶bɬM.זϪj*wvmG*
$2d%&ؒ9"J*}w:ZU8l&nв$p_V#gy2ZZ
nDouw?ϢZ؃S;E+&`?=4L>S*s8Y-
Ъ"+Ѫ[EӰśȴг@>N-EGlLo*Vr+,_n-S=?eZ|.05
+~k
ЪݤjZ*Π5GڅCpZNiB
>uM0C_K7[,
BMuaЮ&˭
>hHZ)p8mp(n#U\،Vh@42ų˅BѪIm\[TfWhEV[WnV	0Y.܋V{]{}t!Z[-E+Zoe^U+`	$ ] t2'pهVZ!$^
B+ZV)C+VZű!YVvjbve]V)e&`l:ti-*Xf׆*^Gntt*_kJbS8gZTB+VZesMO`ve|ikG`S}]:~a,F+ZtzoZU,5u]?NZKG%AkhEZB6GZ;u|@(շVKu~v.*pzB2ǯKkYF:ɀ
MwޙɯZ~*zZ"J\=;ia+f5e#QW^zsKswEX[hYUxP)$Ÿ|댹ZcDs
	YB"aVh_(UͫЪ"+hhֹՇs[5ĎͫZ냎}
𷾐s[<|
̫3Һ"ZgOT^<ZO^W'ejjn+kU0GW֚LU0*ߚscUtK+Vњ:Њ5*k*6
hm0Z6
ekֶY,bZuZ#VhXԀJ#$BklƴbP#VrjihŐF8VF^;UsߔκrӖZ\i#ie~k3Z}wœ+5MHthKgmdZ!p$o^"cDYll6Տ\j.lVj̭㞀x7t0NQjN6&	\SҊg=T|![ײZ-+vD+Bkz=fZB+B+B+B+B+B+m
[ND+oUkoG`zoU}+:ݖ`ɭъr[;Њ5*-WedVhߪ2#w56U
{.SGN+֌|}˵[i:5XP_yrǡ
v$>j7n?xt90r
ZѲpl=ֺ!#adVhUٳvl=ֺaGMYe4ruYqh&;j^eٙhIEi\d펚:{ꐖ	h%hw;egZghE)KÍT]#BZiֶ#d#9u$oQe@'#Ym@knVhm?Zg	D=ݬ>5$vV֠RvZVh:"[Yӊ^n^\-M`-k:M?cn:.[: Bk:M-m
ůo
unZAS#iZ'ASC7Z
h=|_V*IZF`{ie~humKݤSzn$[5lQ]cњ
+]޵Uz…r*T
ӊUcZ`vkh=?[*Z
~h;:jlRWh=<вƟo{kCJnmw4\A@kȴ#6Z
Z㎆0WhmZw4enl0BkiX
ꀴ׾hm`pVhՠ.h'jLrMU iBs:AtC+jPU%r4!>&Dn!68=kIsyj	[**ZJ֎k[`iBzJn3-ZZZZZZZZZ!1KrA]Cuց)(
s[KϿ&ʖO5Zg
6Y	Ouߪy}Z>xWh1ZLOT:uo[,EVc6>@A
ZZ	hm
J@+B+B+B+i*UMzsYah`̫&1ςy}@ 	dLA"\ܹ=ý?i
ߊ5з֞5־gj+>Y
}$־gj+5зNU'}$ƶl	le+[Vle+[VֲY2oBOMv{17oꡚl~+oLZǸv{BZk]Z׌[a~k?_Bڟqo~+{kyZd[omG:le+[Vle+[V[
}듲Wuk7{uGZM]Nmuu;UKY~uV.ˈ^ǷL7%uYBZ8mYMbgt[o-OqVQZ`n+QvL8~bgt[o}U,6/kĎ:
le+ؚ٥c"@`@G;d
ܓhf+zV[OVlV[VlV[VlV[VlV[VlV[Vl[U.lV[ۊ`+؊`+؊`+؊`+؊`+,va~,!2l[e׎i@ pmZAp
@0Sas:6cIENDB`yard-0.9.37/docs/images/tags-class-diagram.png000066400000000000000000000217711466601756300211450ustar00rootroot00000000000000PNG


IHDRgSzAPLTEfff999f99fڎڎf999ff99ff9ff9fff99ڶfڎٶ8eVf9ee8yyHI8)ڍڍf99fڶfffڎ999fڎ9f9f9f9999O10eff9999f9fffffٶf>-"IDATx^n0Q=PΌY@Yhw
	Ǝ[<"	>33gDNSp3g8p})"Cnt"F޿E',B[·cuwmۿ18YYLU;pE$f(nn~_ԥߧ>?9,7]Mͳ.y-5Nr֑8o,)tu3(jƌ]+5<|Cm]hţʙw.gyјqJnƣ5^>X]Pڗ\YG
Ս] gE(Ud)+v	-d	C	#!Ψ
\Amg|nNQcmW!7{jM!O1>-?_ۭiy8!;3Q<<z~Z+ch[NK?.\x:C,g`ٗQuპ~bΝNCBǟ7ކ>oR&WrfqP0n1]BN''8˟nM/\n( 

7XPhUp
7֋Y-Jɟnv_Bs~
{ƥgPJtCM~Ҝ}ֱf5gk,T~".TH9SgI+?CwF4q63̓3؇!Y\,v
4վZΨֲCzi0kFjֲZߟ?HhRΨֲZ?oJZ"u-wFj-`-!vgX1Uܼ|TZVE)Bp	?@kvhrF笼r,n:aiF4r6Vk	kM_"_RΨi2q6%oD#geɯQZ&ęk*9S~&ęX=hLϦslWg
8nxG?T|򟉳B41ސ&=\t}'}?ìa\mbzaA?UoY8vag(ZF*rQ<{08A1src?cC
8#_)?XB5Q290Fcge!ǶTcaZƻڲ+Y&Y!ךAy@hFhI8
Aܟbg_[qF&`.=\k>g%3t42h=k-TC5O)#̪mۜ1q0#[	|7\k_#%ő})|[1l>S4JloFRj#gsQ0xFonBγ
2[QôNВ2:i_3kvծ65נF&5CdmLUSę8g*L3IScL36L>7zceE8)	5q™՞9!5g0`
DpfylleΡ?KfܬMJ,s
Ag/,,a&Y"W%*6sQ3Y#gn﹙sFYbr\3"N8s7GA/S3N
ܬMrEYJL(֘7FƏV:lE`\ckLE3q&Tt8;GRs"?Pg8RLe^3?o2"Mg~34bH~+`agsζf	DL5?ӝq3Dhagtg\8&ZY+3?ZY3?1d3Djag
ϪO~&?̷L̛3q&Tę8gL3}2&?|_L3?PKOq&5LE)?C	qęg~.`)?C	FμC<řg~0BuּC<řg~0M|ڟ:x3ck3&c35P;&@h3?-<>3s	t6 @ٹݴ8Υ*lj.*G. @-ҧa+;t:3:Cg3tβY(K3lil"KgiѾy_;@gcO:}+ͧ-vSgdq|r8n٧ep6VaOiK洪am\)ͧ1:3t:Cg3t@gt3:3t:Cg3t@gbvlbz^osf:6&3\x8<*B&̎u8(Ddz3ׯ6mΞMY8G{?gpiH}I}\+Mo6Zk9S7.gW}&bdę+ph}_eB1rpg5Ggxz鎆x38/+T7$gpgJlo>ݽ8ͼNh8*	S=:ų:gg;#Z]2ydk>ZY'ϟʦ޵38p(Rg(~k-,lj]x9JQ&#vyg9ӷLdgi{?,2EFJh-Zx[
J?:gV#|ٹZBҼTtgpꔩ?o^4-V4nmY
blT2Om_DB_vvZaa9)/IҞjp!4BSRH/t:e⾿M?u 1&+nJ,	$63S&[S1YFR
~
8@83pgpvĂ38ޑYݫu\z̳1,3TC5,?fjhpFc͜Ҁ!$Y;cͬҀ^l
fpg~
83838+838oha;8f,* e֙fig*g",_"3sz,/_i&Vic򵋄U?L3Yr<,?Ƕ6̮+=sY56;h8vBQwt	E^E܂Vc)ތU\kdz)z.jx{4fKBُѪތy56;ζ;PEg|g!8gE+"gn{3^qͶ옝rDYZx<˗.jߟu5gۛ׶#u똝rHoje>Gh;ɕ.tTfz3j8;f1g.R"x6D:Zt|Ӽ6oS3r_Ő\fk<`H=J{rg=[%:p6;ՐsYղW5/gUʜ_pn?e
Wfiun3ԣYx9W^69ଇ7S
:gTͷkepy)gzyE8C=9gM%3s}iRРҝ_pk 8383gpgp	Ya؄3grc}]1c=Z|K
l96٬f6Y7c-_mMAzY؄3g~`^l96Yk,l4pL*$Psl3;}_x=sl~eRl96g996@?PC
A3T{B`vo@CpACpP}BTY@!8C!g!gx"Jp!838383gpgp383838Cštk9
bҁ-a\[=<0gpE19\;'z*ͰyEٙV)gpVoH7ڜi>xVM𣏕Iͥ38B
lgt,tVqiq/ُ3G=t<+\jvEP;YQqg/QxyUX8ay1g"mp^,z|F6m8R'"I	I+gvLhT{8niH8#-
l")~Z838738>}?iˮ4^"h>
߭{qWm0m*|QAgp [>v9sq2!խpW(mj!>Qu
[f[^>QkF
!Jf*my++ї1qiwk7>ٜ^#T"2dqּtb5H?g>93MltP4??g^GװWԔ[#9ұ+poF_L'EmClFƵFi1͓?f{>$C62n#3	v;:K
-l>38nv|(͙'c3Yf܆דxCΙFmx+hHcU;M|(^7#ύm2Pcpg<gpgpgpgpgp,Հ^48K
,Lfq5`(Y4wDۙk۞38?-6V8qm5	쑭jgx;@F۟38?=g?gp{d-q_m.,V[⭵υ^mqf3yQQp30:s?ށ_
\8g!83g I}@QL3gy38CAr0ٓUjY]˟j\EkњEcΆtM8^ϒ96lOϱ	g{tg96?K?g ipgy!v!8CpgY)rY)r|(27gJL3L3"DH¯g8gC!83gVZ!IENDB`yard-0.9.37/docs/templates/000077500000000000000000000000001466601756300155155ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/000077500000000000000000000000001466601756300171415ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/fulldoc/000077500000000000000000000000001466601756300205715ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/fulldoc/html/000077500000000000000000000000001466601756300215355ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/fulldoc/html/full_list_tag.erb000066400000000000000000000004741466601756300250640ustar00rootroot00000000000000<% even_odd = 'odd'  %>
<% collect_tags.each do |tag| %>
  
  • 
    
    
      <%= tag_link(tag) %>
    
    
  
    • 
  <% even_odd = (even_odd == 'even' ? 'odd' : 'even') %>
<% end %>yard-0.9.37/docs/templates/default/fulldoc/html/setup.rb000066400000000000000000000002221466601756300232160ustar00rootroot00000000000000# frozen_string_literal: true
def generate_tag_list
  @list_title = "Tag List"
  @list_type = "tag"
  asset('tag_list.html', erb(:full_list))
end
yard-0.9.37/docs/templates/default/layout/000077500000000000000000000000001466601756300204565ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/layout/html/000077500000000000000000000000001466601756300214225ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/layout/html/setup.rb000066400000000000000000000003011466601756300231010ustar00rootroot00000000000000# frozen_string_literal: true
def init
  super
  sections.place(:tag_list).after_any(:files)
end

def menu_lists
  super + [{:type => 'tag', :title => 'Tags', :search_title => 'Tag List'}]
end
yard-0.9.37/docs/templates/default/layout/html/tag_list.erb000066400000000000000000000006071466601756300237250ustar00rootroot00000000000000
    Tag Listing
    

    The following are a brief list of tags that can be used in YARD formatted
  documentation. See <%= link_file "docs/Tags.md" %> for information on using tags.
    

      
<% n = 1 %>
<% collect_tags.each do |tag| %>
  
    • <%= tag_link(tag) %>
      • 
  <% n = n == 2 ? 1 : 2 %>
<% end %>

    

    
yard-0.9.37/docs/templates/default/yard_tags/000077500000000000000000000000001466601756300211165ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/yard_tags/html/000077500000000000000000000000001466601756300220625ustar00rootroot00000000000000yard-0.9.37/docs/templates/default/yard_tags/html/list.erb000066400000000000000000000010041466601756300235220ustar00rootroot00000000000000<% [["Tag", all_tags], ["Directive", all_directives]].each do |(name, list)| %>

    <%= name %> List
    

<% list.each_with_index do |tag, i| %>

    
  
    
    <%= tag_signature tag %>
  
    
  <% if name == "Directive" %>
    <%= yieldall :object => P("YARD::Tags::#{tag.text}") %>
  <% else %>
    <%= yieldall :object => tag.object %>
  <% end %>

    
<% end %>

<% end%>
yard-0.9.37/docs/templates/default/yard_tags/html/setup.rb000066400000000000000000000014171466601756300235520ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :list, [T('docstring')]
end

def tag_signature(tag)
  types = tag.types || []
  signature = "#{tag_link_name(tag)} "
  sig_tag = tag.object.tag('yard.signature')
  extra = sig_tag.text if sig_tag
  extra ||= case types.first
            when 'with_name'
              "name description"
            when 'with_types'
              "[Types] description"
            when 'with_types_and_name'
              "name [Types] description"
            when 'with_title_and_text'
              "title\ndescription"
            when 'with_types_and_title'
              "[Types] title\ndescription"
            else
              "description"
            end
  signature + h(extra).gsub(/\n/, "
       ")
end
yard-0.9.37/docs/templates/plugin.rb000066400000000000000000000033441466601756300173440ustar00rootroot00000000000000# frozen_string_literal: true
include YARD
include Templates

module TagTemplateHelper
  def all_tags
    Registry.all(:method).map {|m| m.tag('yard.tag') }.compact
  end

  def all_directives
    Registry.all(:method).map {|m| m.tag('yard.directive') }.compact
  end

  def collect_tags
    (all_tags + all_directives).sort_by(&:name)
  end

  def tag_link(tag)
    link_file("docs/Tags.md", tag_link_name(tag), tag.name)
  end

  def tag_link_name(tag)
    prefix = tag.tag_name == 'yard.directive' ? '@!' : '@'
    h(prefix + tag.name)
  end

  # Wrap url_for and url_for_file to rewrite object when generating docs for
  # yard.tag/directive objects.
  %w(url_for url_for_file).each do |meth|
    self.class.send(:define_method, meth) do
      if object.is_a?(CodeObjects::Base) &&
         (object.tag('yard.tag') || object.tag('yard.directive') ||
         (object.type == :class && object.superclass.name == :Directive))
        obj = object
        self.object = Registry.root
        url = super
        self.object = obj
        url
      else
        super
      end
    end
  end

  def linkify(*args)
    if args.first.is_a?(String)
      case args.first
      when "yard:include_tags"
        return T('yard_tags').run(options)
      when /^tag:(\S+)/
        tag_name = $1
        suffix = "tag"
        if tag_name =~ /^!/
          tag_name = tag_name[1..-1]
          suffix = "directive"
        end

        obj = Registry.at("YARD::Tags::Library##{tag_name}_#{suffix}")
        return tag_link(obj.tag("yard.#{suffix}")) if obj

        log.warn "Cannot find tag: #{args.first}"
        return args.first
      end
    end
    super
  end
end

Template.extra_includes << TagTemplateHelper
Engine.register_template_path(File.dirname(__FILE__))
yard-0.9.37/lib/000077500000000000000000000000001466601756300133355ustar00rootroot00000000000000yard-0.9.37/lib/rubygems_plugin.rb000066400000000000000000000006051466601756300170760ustar00rootroot00000000000000# frozen_string_literal: true
if defined?(Gem::VERSION) && Gem::VERSION >= "2.0."
  require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/hook')
else
  unless defined?(Gem::DocManager.load_yardoc)
    require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/specification')
    require File.expand_path(File.dirname(__FILE__) + '/yard/rubygems/doc_manager')
  end
end
yard-0.9.37/lib/yard.rb000066400000000000000000000045731466601756300146320ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  # The root path for YARD source libraries
  ROOT = File.expand_path(File.dirname(__FILE__))

  require File.join(YARD::ROOT, 'yard', 'version')
  require File.join(YARD::ROOT, 'yard', 'autoload')

  # The root path for YARD builtin templates
  TEMPLATE_ROOT = File.join(ROOT, '..', 'templates')

  # @deprecated Use {Config::CONFIG_DIR}
  CONFIG_DIR = Config::CONFIG_DIR

  # An alias to {Parser::SourceParser}'s parsing method
  #
  # @example Parse a glob of files
  #   YARD.parse('lib/**/*.rb')
  # @see Parser::SourceParser.parse
  def self.parse(*args) Parser::SourceParser.parse(*args) end

  # An alias to {Parser::SourceParser}'s parsing method
  #
  # @example Parse a string of input
  #   YARD.parse_string('class Foo; end')
  # @see Parser::SourceParser.parse_string
  def self.parse_string(*args) Parser::SourceParser.parse_string(*args) end

  # (see YARD::Config.load_plugins)
  # @deprecated Use {Config.load_plugins}
  def self.load_plugins; YARD::Config.load_plugins end

  # @return [Boolean] whether YARD is being run inside of Windows
  def self.windows?
    return @windows if defined? @windows
    require 'rbconfig'
    @windows =
      ::RbConfig::CONFIG['host_os'] =~ /mingw|win32|cygwin/ ? true : false
  ensure
    @windows ||= false
  end

  # @return [Boolean] whether YARD is being run in Ruby 1.8 mode
  def self.ruby18?; !ruby19? end

  # @return [Boolean] whether YARD is being run in Ruby 1.9 mode
  def self.ruby19?; @ruby19 ||= (RUBY_VERSION >= "1.9.1") end

  # @return [Boolean] whether YARD is being run in Ruby 2.0
  def self.ruby2?; @ruby2 ||= (RUBY_VERSION >= '2.0.0') end

  # @return [Boolean] whether YARD is being run in Ruby 3.0
  def self.ruby3?; @ruby3 ||= (RUBY_VERSION >= '3.0.0') end

  # @return [Boolean] whether YARD is being run in Ruby 3.1
  def self.ruby31?; @ruby31 ||= (RUBY_VERSION >= '3.1.0') end
end

# Keep track of Ruby version for compatibility code
# @deprecated Use {YARD.ruby18?} or {YARD.ruby19?} instead.
RUBY18 = YARD.ruby18?
RUBY19 = YARD.ruby19?

# Load Ruby core extension classes
Dir.glob(File.join(YARD::ROOT, 'yard', 'core_ext', '*.rb')).each do |file|
  require file
end

# Backport RubyGems SourceIndex and other classes
require File.join(YARD::ROOT, 'yard', 'rubygems', 'backports')

require File.join(YARD::ROOT, 'yard', 'globals')

# Load YARD configuration options (and plugins)
YARD::Config.load
yard-0.9.37/lib/yard/000077500000000000000000000000001466601756300142745ustar00rootroot00000000000000yard-0.9.37/lib/yard/autoload.rb000066400000000000000000000404101466601756300164300ustar00rootroot00000000000000# frozen_string_literal: true
# @private
def __p(path) File.join(YARD::ROOT, 'yard', *path.split('/')); end

module YARD
  module CLI # Namespace for command-line interface components
    autoload :Command,         __p('cli/command')
    autoload :CommandParser,   __p('cli/command_parser')
    autoload :Config,          __p('cli/config')
    autoload :Diff,            __p('cli/diff')
    autoload :Display,         __p('cli/display')
    autoload :Gems,            __p('cli/gems')
    autoload :Graph,           __p('cli/graph')
    autoload :Help,            __p('cli/help')
    autoload :List,            __p('cli/list')
    autoload :MarkupTypes,     __p('cli/markup_types')
    autoload :Server,          __p('cli/server')
    autoload :Stats,           __p('cli/stats')
    autoload :Yardoc,          __p('cli/yardoc')
    autoload :YardoptsCommand, __p('cli/yardopts_command')
    autoload :YRI,             __p('cli/yri')
    autoload :I18n,            __p('cli/i18n')
  end

  # A "code object" is defined as any entity in the Ruby language.
  # Classes, modules, methods, class variables and constants are the
  # major objects, but DSL languages can create their own by inheriting
  # from {CodeObjects::Base}.
  module CodeObjects
    autoload :Base,                 __p('code_objects/base')
    autoload :CodeObjectList,       __p('code_objects/base')
    autoload :ClassObject,          __p('code_objects/class_object')
    autoload :ClassVariableObject,  __p('code_objects/class_variable_object')
    autoload :ConstantObject,       __p('code_objects/constant_object')
    autoload :ExtendedMethodObject, __p('code_objects/extended_method_object')
    autoload :ExtraFileObject,      __p('code_objects/extra_file_object')
    autoload :MacroObject,          __p('code_objects/macro_object')
    autoload :MethodObject,         __p('code_objects/method_object')
    autoload :ModuleObject,         __p('code_objects/module_object')
    autoload :NamespaceMapper,      __p('code_objects/namespace_mapper')
    autoload :NamespaceObject,      __p('code_objects/namespace_object')
    autoload :Proxy,                __p('code_objects/proxy')
    autoload :ProxyMethodError,     __p('code_objects/proxy')
    autoload :RootObject,           __p('code_objects/root_object')

    autoload :BUILTIN_ALL,          __p('code_objects/base')
    autoload :BUILTIN_CLASSES,      __p('code_objects/base')
    autoload :BUILTIN_MODULES,      __p('code_objects/base')
    autoload :BUILTIN_EXCEPTIONS,   __p('code_objects/base')
    autoload :CONSTANTMATCH,        __p('code_objects/base')
    autoload :CONSTANTSTART,        __p('code_objects/base')
    autoload :METHODMATCH,          __p('code_objects/base')
    autoload :METHODNAMEMATCH,      __p('code_objects/base')
    autoload :NAMESPACEMATCH,       __p('code_objects/base')
    autoload :NSEP,                 __p('code_objects/base')
    autoload :NSEPQ,                __p('code_objects/base')
    autoload :ISEP,                 __p('code_objects/base')
    autoload :ISEPQ,                __p('code_objects/base')
    autoload :CSEP,                 __p('code_objects/base')
    autoload :CSEPQ,                __p('code_objects/base')
  end

  # Handlers are called during the data processing part of YARD's
  # parsing phase. This allows YARD as well as any custom extension to
  # analyze source and generate {CodeObjects} to be stored for later use.
  module Handlers
    # Shared logic between C and Ruby handlers.
    module Common
      autoload :MethodHandler,            __p('handlers/common/method_handler')
    end

    # CRuby Handlers
    # @since 0.8.0
    module C
      autoload :Base,                     __p('handlers/c/base')

      autoload :AliasHandler,             __p('handlers/c/alias_handler')
      autoload :AttributeHandler,         __p('handlers/c/attribute_handler')
      autoload :ClassHandler,             __p('handlers/c/class_handler')
      autoload :ConstantHandler,          __p('handlers/c/constant_handler')
      autoload :HandlerMethods,           __p('handlers/c/handler_methods')
      autoload :InitHandler,              __p('handlers/c/init_handler')
      autoload :MethodHandler,            __p('handlers/c/method_handler')
      autoload :MixinHandler,             __p('handlers/c/mixin_handler')
      autoload :ModuleHandler,            __p('handlers/c/module_handler')
      autoload :OverrideCommentHandler,   __p('handlers/c/override_comment_handler')
      autoload :PathHandler,              __p('handlers/c/path_handler')
      autoload :StructHandler,            __p('handlers/c/struct_handler')
      autoload :SymbolHandler,            __p('handlers/c/symbol_handler')
    end

    module Ruby # All Ruby handlers
      module Legacy # Handlers for old Ruby 1.8 parser
        autoload :Base,                   __p('handlers/ruby/legacy/base')

        autoload :AliasHandler,           __p('handlers/ruby/legacy/alias_handler')
        autoload :AttributeHandler,       __p('handlers/ruby/legacy/attribute_handler')
        autoload :ClassHandler,           __p('handlers/ruby/legacy/class_handler')
        autoload :ClassConditionHandler,  __p('handlers/ruby/legacy/class_condition_handler')
        autoload :ClassVariableHandler,   __p('handlers/ruby/legacy/class_variable_handler')
        autoload :CommentHandler,         __p('handlers/ruby/legacy/comment_handler')
        autoload :ConstantHandler,        __p('handlers/ruby/legacy/constant_handler')
        autoload :DSLHandler,             __p('handlers/ruby/legacy/dsl_handler')
        autoload :ExceptionHandler,       __p('handlers/ruby/legacy/exception_handler')
        autoload :ExtendHandler,          __p('handlers/ruby/legacy/extend_handler')
        autoload :MethodHandler,          __p('handlers/ruby/legacy/method_handler')
        autoload :MixinHandler,           __p('handlers/ruby/legacy/mixin_handler')
        autoload :ModuleHandler,          __p('handlers/ruby/legacy/module_handler')
        autoload :ModuleFunctionHandler,  __p('handlers/ruby/legacy/module_function_handler')
        autoload :PrivateClassMethodHandler, __p('handlers/ruby/legacy/private_class_method_handler')
        autoload :PrivateConstantHandler, __p('handlers/ruby/legacy/private_constant_handler')
        autoload :VisibilityHandler,      __p('handlers/ruby/legacy/visibility_handler')
        autoload :YieldHandler,           __p('handlers/ruby/legacy/yield_handler')
      end

      autoload :Base,                     __p('handlers/ruby/base')

      autoload :AliasHandler,             __p('handlers/ruby/alias_handler')
      autoload :AttributeHandler,         __p('handlers/ruby/attribute_handler')
      autoload :ClassHandler,             __p('handlers/ruby/class_handler')
      autoload :ClassConditionHandler,    __p('handlers/ruby/class_condition_handler')
      autoload :ClassVariableHandler,     __p('handlers/ruby/class_variable_handler')
      autoload :CommentHandler,           __p('handlers/ruby/comment_handler')
      autoload :ConstantHandler,          __p('handlers/ruby/constant_handler')
      autoload :DecoratorHandlerMethods,  __p('handlers/ruby/decorator_handler_methods')
      autoload :DSLHandler,               __p('handlers/ruby/dsl_handler')
      autoload :DSLHandlerMethods,        __p('handlers/ruby/dsl_handler_methods')
      autoload :ExceptionHandler,         __p('handlers/ruby/exception_handler')
      autoload :ExtendHandler,            __p('handlers/ruby/extend_handler')
      autoload :MethodHandler,            __p('handlers/ruby/method_handler')
      autoload :MethodConditionHandler,   __p('handlers/ruby/method_condition_handler')
      autoload :MixinHandler,             __p('handlers/ruby/mixin_handler')
      autoload :ModuleHandler,            __p('handlers/ruby/module_handler')
      autoload :ModuleFunctionHandler,    __p('handlers/ruby/module_function_handler')
      autoload :PrivateClassMethodHandler, __p('handlers/ruby/private_class_method_handler')
      autoload :PrivateConstantHandler,   __p('handlers/ruby/private_constant_handler')
      autoload :PublicClassMethodHandler, __p('handlers/ruby/public_class_method_handler')
      autoload :StructHandlerMethods,     __p('handlers/ruby/struct_handler_methods')
      autoload :VisibilityHandler,        __p('handlers/ruby/visibility_handler')
      autoload :YieldHandler,             __p('handlers/ruby/yield_handler')
    end

    autoload :Base,                       __p('handlers/base')
    autoload :HandlerAborted,             __p('handlers/base')
    autoload :NamespaceMissingError,      __p('handlers/base')
    autoload :Processor,                  __p('handlers/processor')
  end

  # Namespace for internationalization (i18n)
  # @since 0.8.0
  module I18n
    autoload :Locale,          __p('i18n/locale')
    autoload :Message,         __p('i18n/message')
    autoload :Messages,        __p('i18n/messages')
    autoload :PotGenerator,    __p('i18n/pot_generator')
    autoload :Text,            __p('i18n/text')
  end

  # The parser namespace holds all parsing engines used by YARD.
  # Currently only Ruby and C (Ruby) parsers are implemented.
  module Parser
    module C # CRuby Parsing components
      autoload :BodyStatement,     __p('parser/c/statement')
      autoload :Comment,           __p('parser/c/statement')
      autoload :CommentParser,     __p('parser/c/comment_parser')
      autoload :CParser,           __p('parser/c/c_parser')
      autoload :Statement,         __p('parser/c/statement')
      autoload :ToplevelStatement, __p('parser/c/statement')
    end

    module Ruby # Ruby parsing components.
      module Legacy # Handles Ruby parsing in Ruby 1.8.
        autoload :RubyParser,     __p('parser/ruby/legacy/ruby_parser')
        autoload :RubyToken,      __p('parser/ruby/legacy/ruby_lex')
        autoload :Statement,      __p('parser/ruby/legacy/statement')
        autoload :StatementList,  __p('parser/ruby/legacy/statement_list')
        autoload :TokenList,      __p('parser/ruby/legacy/token_list')
      end

      autoload :AstNode,           __p('parser/ruby/ast_node')
      autoload :RubyParser,        __p('parser/ruby/ruby_parser')
      autoload :RipperParser,      __p('parser/ruby/ruby_parser')
      autoload :TokenResolver,     __p('parser/ruby/token_resolver')
    end

    autoload :Base,                __p('parser/base')
    autoload :ParserSyntaxError,   __p('parser/source_parser')
    autoload :SourceParser,        __p('parser/source_parser')
    autoload :UndocumentableError, __p('parser/source_parser')
  end

  module Rake # Holds Rake tasks used by YARD
    autoload :YardocTask, __p('rake/yardoc_task')
  end

  module Serializers # Namespace for components that serialize to various endpoints
    autoload :Base,                 __p('serializers/base')
    autoload :FileSystemSerializer, __p('serializers/file_system_serializer')
    autoload :ProcessSerializer,    __p('serializers/process_serializer')
    autoload :StdoutSerializer,     __p('serializers/stdout_serializer')
    autoload :YardocSerializer,     __p('serializers/yardoc_serializer')
  end

  # Namespace for classes and modules that handle serving documentation over HTTP
  #
  # == Implementing a Custom Server
  # To customize the YARD server, see the {Adapter} and {Router} classes.
  #
  # == Rack Middleware
  # If you want to use the YARD server as a Rack middleware, see the documentation
  # in {RackMiddleware}.
  #
  # @since 0.6.0
  module Server
    require __p('server')

    # Commands implement specific kinds of server responses which are routed
    # to by the {Router} class. To implement a custom command, subclass {Commands::Base}.
    module Commands
      autoload :Base,                 __p('server/commands/base')
      autoload :DisplayFileCommand,   __p('server/commands/display_file_command')
      autoload :DisplayObjectCommand, __p('server/commands/display_object_command')
      autoload :FramesCommand,        __p('server/commands/frames_command')
      autoload :ListCommand,          __p('server/commands/list_command')
      autoload :LibraryCommand,       __p('server/commands/library_command')
      autoload :LibraryIndexCommand,  __p('server/commands/library_index_command')
      autoload :RootRequestCommand,   __p('server/commands/root_request_command')
      autoload :SearchCommand,        __p('server/commands/search_command')
      autoload :StaticFileCommand,    __p('server/commands/static_file_command')
      autoload :StaticFileHelpers,    __p('server/commands/static_file_helpers')
    end

    autoload :Adapter,                __p('server/adapter')
    autoload :DocServerSerializer,    __p('server/doc_server_serializer')
    autoload :DocServerHelper,        __p('server/doc_server_helper')
    autoload :FinishRequest,          __p('server/adapter')
    autoload :LibraryVersion,         __p('server/library_version')
    autoload :NotFoundError,          __p('server/adapter')
    autoload :HTTPUtils,              __p('server/http_utils')
    autoload :RackAdapter,            __p('server/rack_adapter')
    autoload :RackMiddleware,         __p('server/rack_adapter')
    autoload :Router,                 __p('server/router')
    autoload :StaticCaching,          __p('server/static_caching')
    autoload :WebrickAdapter,         __p('server/webrick_adapter')
    autoload :WebrickServlet,         __p('server/webrick_adapter')
  end

  module Tags # Namespace for Tag components
    autoload :AttributeDirective,  __p('tags/directives')
    autoload :DefaultFactory,      __p('tags/default_factory')
    autoload :DefaultTag,          __p('tags/default_tag')
    autoload :Directive,           __p('tags/directives')
    autoload :EndGroupDirective,   __p('tags/directives')
    autoload :GroupDirective,      __p('tags/directives')
    autoload :Library,             __p('tags/library')
    autoload :MacroDirective,      __p('tags/directives')
    autoload :MethodDirective,     __p('tags/directives')
    autoload :OptionTag,           __p('tags/option_tag')
    autoload :OverloadTag,         __p('tags/overload_tag')
    autoload :ParseDirective,      __p('tags/directives')
    autoload :RefTag,              __p('tags/ref_tag')
    autoload :RefTagList,          __p('tags/ref_tag_list')
    autoload :ScopeDirective,      __p('tags/directives')
    autoload :Tag,                 __p('tags/tag')
    autoload :TagFormatError,      __p('tags/tag_format_error')
    autoload :TypesExplainer,      __p('tags/types_explainer')
    autoload :VisibilityDirective, __p('tags/directives')
  end

  # Namespace for templating system
  module Templates
    module Helpers # Namespace for template helpers
      module Markup # Namespace for markup providers
        autoload :RDocMarkup,               __p('templates/helpers/markup/rdoc_markup')
        autoload :RDocMarkdown,             __p('templates/helpers/markup/rdoc_markdown')
      end

      autoload :BaseHelper,                 __p('templates/helpers/base_helper')
      autoload :FilterHelper,               __p('templates/helpers/filter_helper')
      autoload :HtmlHelper,                 __p('templates/helpers/html_helper')
      autoload :HtmlSyntaxHighlightHelper,  __p('templates/helpers/html_syntax_highlight_helper')
      autoload :MarkupHelper,               __p('templates/helpers/markup_helper')
      autoload :MethodHelper,               __p('templates/helpers/method_helper')
      autoload :ModuleHelper,               __p('templates/helpers/module_helper')
      autoload :TextHelper,                 __p('templates/helpers/text_helper')
      autoload :UMLHelper,                  __p('templates/helpers/uml_helper')
    end

    autoload :Engine,          __p('templates/engine')
    autoload :ErbCache,        __p('templates/erb_cache')
    autoload :Section,         __p('templates/section')
    autoload :Template,        __p('templates/template')
    autoload :TemplateOptions, __p('templates/template_options')
  end

  autoload :Config,           __p('config')
  autoload :Docstring,        __p('docstring')
  autoload :DocstringParser,  __p('docstring_parser')
  autoload :GemIndex,         __p('gem_index')
  autoload :Logger,           __p('logging')
  autoload :OpenStruct,       __p('open_struct')
  autoload :Options,          __p('options')
  autoload :Registry,         __p('registry')
  autoload :RegistryResolver, __p('registry_resolver')
  autoload :RegistryStore,    __p('registry_store')
  autoload :StubProxy,        __p('serializers/yardoc_serializer')
  autoload :Verifier,         __p('verifier')
end

undef __p
yard-0.9.37/lib/yard/cli/000077500000000000000000000000001466601756300150435ustar00rootroot00000000000000yard-0.9.37/lib/yard/cli/command.rb000066400000000000000000000060651466601756300170150ustar00rootroot00000000000000# frozen_string_literal: true
require 'optparse'

module YARD
  module CLI
    # Abstract base class for CLI utilities. Provides some helper methods for
    # the option parser
    #
    # @abstract
    # @since 0.6.0
    class Command
      # Helper method to run the utility on an instance.
      # @see #run
      def self.run(*args) new.run(*args) end

      def description; '' end

      protected

      # Adds a set of common options to the tail of the OptionParser
      #
      # @param [OptionParser] opts the option parser object
      # @return [void]
      def common_options(opts)
        opts.separator ""
        opts.separator "Other options:"
        opts.on('-e', '--load FILE', 'A Ruby script to load before running command.') do |file|
          load_script(file)
        end
        opts.on('--plugin PLUGIN', 'Load a YARD plugin (gem with `yard-\' prefix)') do |name|
          # Not actually necessary to load here, this is done at boot in YARD::Config.load_plugins
          # YARD::Config.load_plugin(name)
        end
        opts.on('--legacy', 'Use old style Ruby parser and handlers. ',
                            '  Always on in 1.8.x.') do
          YARD::Parser::SourceParser.parser_type = :ruby18
        end
        opts.on('--safe', 'Enable safe mode for this instance') do
          # Parsed in YARD::Config.load
        end
        opts.on_tail('-q', '--quiet', 'Show no warnings.') { log.level = Logger::ERROR }
        opts.on_tail('--verbose', 'Show more information.') { log.level = Logger::INFO }
        opts.on_tail('--debug', 'Show debugging information.') { log.level = Logger::DEBUG }
        opts.on_tail('--backtrace', 'Show stack traces') { log.show_backtraces = true }
        opts.on_tail('-v', '--version', 'Show version.') { log.puts "yard #{YARD::VERSION}"; exit }
        opts.on_tail('-h', '--help', 'Show this help.')  { log.puts opts; exit }
      end

      # Parses the option and gracefully handles invalid switches
      #
      # @param [OptionParser] opts the option parser object
      # @param [Array] args the arguments passed from input. This
      #   array will be modified.
      # @return [void]
      def parse_options(opts, args)
        opts.parse!(args)
      rescue OptionParser::ParseError => err
        unrecognized_option(err)
        args.shift if args.first && args.first[0, 1] != '-'
        retry
      end

      # Loads a Ruby script. If Config.options[:safe_mode] is enabled,
      # this method will do nothing.
      #
      # @param [String] file the path to the script to load
      # @since 0.6.2
      def load_script(file)
        return if YARD::Config.options[:safe_mode]
        load(file)
      rescue LoadError => load_exception
        log.error "The file `#{file}' could not be loaded:\n#{load_exception}"
        exit 1
      end

      # Callback when an unrecognize option is parsed
      #
      # @param [OptionParser::ParseError] err the exception raised by the
      #   option parser
      def unrecognized_option(err)
        log.warn "Unrecognized/#{err.message}"
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/command_parser.rb000066400000000000000000000052061466601756300203650ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # This class parses a command name out of the +yard+ CLI command and calls
    # that command in the form:
    #
    #   $ yard command_name [options]
    #
    # If no command or arguments are specified, or if the arguments immediately
    # begin with a +--opt+ (not +--help+), the {default_command} will be used
    # (which itself defaults to +:doc+).
    #
    # == Adding a Command
    #
    # To add a custom command via plugin, create a mapping in {commands} from
    # the Symbolic command name to the {Command} class that implements the
    # command. To implement a command, see the documentation for the {Command}
    # class.
    #
    # @see Command
    # @see commands
    # @see default_command
    class CommandParser
      class << self
        # @return [Hash{Symbol => Command}] the mapping of command names to
        #   command classes to parse the user command.
        attr_accessor :commands

        # @return [Symbol] the default command name to use when no options
        #   are specified or
        attr_accessor :default_command
      end

      self.commands = SymbolHash[
        :config  => Config,
        :diff    => Diff,
        :display => Display,
        :doc     => Yardoc,
        :gems    => Gems,
        :graph   => Graph,
        :help    => Help,
        :list    => List,
        :markups => MarkupTypes,
        :ri      => YRI,
        :server  => Server,
        :stats   => Stats,
        :i18n    => I18n
      ]

      self.default_command = :doc

      # Convenience method to create a new CommandParser and call {#run}
      # @return (see #run)
      def self.run(*args) new.run(*args) end

      def initialize
        log.show_backtraces = false
      end

      # Runs the {Command} object matching the command name of the first
      # argument.
      # @return [void]
      def run(*args)
        unless args == ['--help']
          if args.empty? || args.first =~ /^-/
            command_name = self.class.default_command
          else
            command_name = args.first.to_sym
            args.shift
          end
          if commands.key?(command_name)
            return commands[command_name].run(*args)
          end
        end
        list_commands
      end

      private

      def commands; self.class.commands end

      def list_commands
        log.puts "Usage: yard  [options]"
        log.puts
        log.puts "Commands:"
        commands.keys.sort_by(&:to_s).each do |command_name|
          command = commands[command_name].new
          log.puts "%-8s %s" % [command_name, command.description]
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/config.rb000066400000000000000000000143711466601756300166430ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # CLI command to view or edit configuration options
    # @since 0.6.2
    class Config < Command
      # @return [Symbol, nil] the key to view/edit, if any
      attr_accessor :key

      # @return [Array, nil] the list of values to set (or single value), if modifying
      attr_accessor :values

      # @return [Boolean] whether to reset the {#key}
      attr_accessor :reset

      # @return [Boolean] whether the value being set should be inside a list
      attr_accessor :as_list

      # @return [Boolean] whether to append values to existing key
      attr_accessor :append

      # @return [String, nil] command to use when configuring ~/.gemrc file.
      #   If the string is nil, configuration should not occur.
      attr_accessor :gem_install_cmd

      def initialize
        super
        self.key = nil
        self.values = []
        self.reset = false
        self.append = false
        self.as_list = false
        self.gem_install_cmd = nil
      end

      def description
        'Views or edits current global configuration'
      end

      def run(*args)
        optparse(*args)
        if gem_install_cmd
          configure_gemrc
        elsif key
          if reset || !values.empty?
            modify_item
          else
            view_item
          end
        else
          list_configuration
        end
      end

      private

      def configure_gemrc
        return unless gem_install_cmd

        require 'rubygems'

        ['install', :install, 'gem', :gem].find do |cmd|
          conf = Gem.configuration[cmd] || ""
          next if conf.empty? && cmd != :gem

          conf = conf.split(/\s+/)
          conf.delete_if {|c| c =~ /^--(no-)?document\b/ } # scrub doc args
          conf |= ["--document=#{gem_install_cmd}"]
          conf = conf.join(' ')

          Gem.configuration[cmd] = conf
          Gem.configuration.write
          log.puts "Updated #{Gem.configuration.path || '~/.gemrc'}: '#{cmd}: #{conf}'"
          true
        end
      end

      def modify_item
        if reset
          log.debug "Resetting #{key}"
          YARD::Config.options[key] = YARD::Config::DEFAULT_CONFIG_OPTIONS[key]
        else
          log.debug "Setting #{key} to #{values.inspect}"
          items = encode_values
          current_items = YARD::Config.options[key]
          items = [current_items].flatten + [items].flatten if append
          YARD::Config.options[key] = items
        end
        YARD::Config.save
      end

      def view_item
        log.debug "Viewing #{key}"
        log.puts YARD::Config.options[key].inspect
      end

      def list_configuration
        log.debug "Listing configuration"
        require 'yaml'
        log.puts YAML.dump(YARD::Config.options).sub(/\A--.*\n/, '').gsub(/\n\n/, "\n")
      end

      def encode_values
        if values.size == 1 && !as_list
          encode_value(values.first)
        else
          values.map {|v| encode_value(v) }
        end
      end

      def encode_value(value)
        case value
        when /^-?\d+/; value.to_i
        when "true"; true
        when "false"; false
        else value
        end
      end

      def optparse(*args)
        list = false
        self.as_list = false
        self.append = false
        opts = OptionParser.new
        opts.banner = "Usage: yard config [options] [item [value ...]]"
        opts.separator ""
        opts.separator "Example: yard config load_plugins true"
        opts.separator ""
        opts.separator "Views and sets configuration items. If an item is provided"
        opts.separator "With no value, the item is viewed. If a value is provided,"
        opts.separator "the item is modified. Specifying no item is equivalent to --list."
        opts.separator "If you specify multiple space delimited values, these are"
        opts.separator "parsed as an array of values."
        opts.separator ""
        opts.separator "Note that `true` and `false` are reserved words."
        opts.separator ""
        opts.separator "---------------------------------------------------------"
        opts.separator ""
        opts.separator "Configuring RubyGems support:"
        opts.separator ""
        opts.separator "YARD can automatically generate the YRI index or HTML"
        opts.separator "documentation in a `gem install` by adding the following"
        opts.separator "to your ~/.gemrc file:"
        opts.separator ""
        opts.separator "    gem: \"--document=yri\""
        opts.separator ""
        opts.separator "Note: you can add 'yard' to also generate HTML docs."
        opts.separator "  You can also add 'ri' to continue generating RDoc."
        opts.separator ""
        opts.separator "You can also run the following command to configure this"
        opts.separator "behavior automatically:"
        opts.separator ""
        opts.separator "    $ yard config --gem-install-yri"
        opts.separator ""
        opts.separator "Add --gem-install-yard to also generate HTML."
        opts.separator ""
        opts.separator "---------------------------------------------------------"
        opts.separator ""
        opts.separator "General options:"

        opts.on('-l', '--list', 'List current configuration') do
          list = true
        end
        opts.on('-r', '--reset', 'Resets the specific item to default') do
          self.reset = true
        end

        opts.separator ""
        opts.separator "Modifying keys:"

        opts.on('-a', '--append', 'Appends items to existing key values') do
          self.append = true
        end
        opts.on('--as-list', 'Forces the value(s) to be wrapped in an array') do
          self.as_list = true
        end

        opts.separator ""
        opts.separator "Add RubyGems install hook:"

        opts.on('--gem-install-yri', 'Configures ~/.gemrc to run yri on a gem install') do
          self.gem_install_cmd = 'yri' if gem_install_cmd != 'yard'
        end

        opts.on('--gem-install-yard', 'Configures ~/.gemrc to run yard on a gem install') do
          self.gem_install_cmd = 'yard'
        end

        common_options(opts)
        parse_options(opts, args)
        args = [] if list
        self.key = args.shift.to_sym if args.size >= 1
        self.values = args if args.size >= 1
        args
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/diff.rb000066400000000000000000000206621466601756300163060ustar00rootroot00000000000000# frozen_string_literal: true
require 'tmpdir'
require 'fileutils'
require 'open-uri'

module YARD
  module CLI
    # CLI command to return the objects that were added/removed from 2 versions
    # of a project (library, gem, working copy).
    # @since 0.6.0
    class Diff < Command
      def initialize
        super
        @list_all = false
        @use_git = false
        @compact = false
        @modified = true
        @verifier = Verifier.new
        @old_git_commit = nil
        @old_path = Dir.pwd
        log.show_backtraces = true
      end

      def description
        'Returns the object diff of two gems or .yardoc files'
      end

      def run(*args)
        registry = optparse(*args).map do |gemfile|
          if @use_git
            load_git_commit(gemfile)
            all_objects
          elsif load_gem_data(gemfile)
            log.info "Found #{gemfile}"
            all_objects
          else
            log.error "Cannot find gem #{gemfile}"
            nil
          end
        end.compact

        return if registry.size != 2

        first_object = nil
        [["Added objects", "A", added_objects(*registry)],
            ["Modified objects", "M", modified_objects(*registry)],
            ["Removed objects", "D", removed_objects(*registry)]].each do |name, short, objects|
          next if short == "M" && @modified == false
          next if objects.empty?
          last_object = nil
          all_objects_notice = false
          log.puts name + ":" unless @compact
          objects.sort_by(&:path).each do |object|
            if !@list_all && last_object && object.parent == last_object
              log.print " (...)" unless all_objects_notice
              all_objects_notice = true
              next
            elsif @compact
              log.puts if first_object
            else
              log.puts
            end
            all_objects_notice = false
            log.print "" + (@compact ? "#{short} " : "  ") +
                      object.path + " (#{object.file}:#{object.line})"
            last_object = object
            first_object = true
          end
          unless @compact
            log.puts; log.puts
          end
        end
        log.puts if @compact
      end

      private

      def all_objects
        return Registry.all if @verifier.expressions.empty?
        @verifier.run(Registry.all)
      end

      def added_objects(registry1, registry2)
        registry2.reject {|o| registry1.find {|o2| o2.path == o.path } }
      end

      def modified_objects(registry1, registry2)
        registry1.select do |obj|
          case obj
          when CodeObjects::MethodObject
            registry2.find {|o| obj == o && o.source != obj.source }
          when CodeObjects::ConstantObject
            registry2.find {|o| obj == o && o.value != obj.value }
          end
        end.compact
      end

      def removed_objects(registry1, registry2)
        registry1.reject {|o| registry2.find {|o2| o2.path == o.path } }
      end

      def load_git_commit(commit)
        Registry.clear
        commit_path = 'git_commit' + commit.gsub(/\W/, '_')
        tmpdir = File.join(Dir.tmpdir, commit_path)
        log.info "Expanding #{commit} to #{tmpdir}..."
        Dir.chdir(@old_path)
        FileUtils.mkdir_p(tmpdir)
        FileUtils.cp_r('.', tmpdir)
        Dir.chdir(tmpdir)
        log.info("git says: " + `git reset --hard #{commit}`.chomp)
        generate_yardoc(tmpdir)
      ensure
        Dir.chdir(@old_path)
        cleanup(commit_path)
      end

      def load_gem_data(gemfile)
        require_rubygems
        Registry.clear

        # First check for argument as .yardoc file
        [File.join(gemfile, '.yardoc'), gemfile].each do |yardoc|
          log.info "Searching for .yardoc db at #{yardoc}"
          next unless File.directory?(yardoc)
          Registry.load_yardoc(yardoc)
          Registry.load_all
          return true
        end

        # Next check installed RubyGems
        gemfile_without_ext = gemfile.sub(/\.gem$/, '')
        log.info "Searching for installed gem #{gemfile_without_ext}"
        YARD::GemIndex.each.find do |spec|
          next unless spec.full_name == gemfile_without_ext
          yardoc = Registry.yardoc_file_for_gem(spec.name, "= #{spec.version}")
          if yardoc
            Registry.load_yardoc(yardoc)
            Registry.load_all
          else
            log.enter_level(Logger::ERROR) do
              olddir = Dir.pwd
              Gems.run(spec.name, spec.version.to_s)
              Dir.chdir(olddir)
            end
          end
          return true
        end

        # Look for local .gem file
        gemfile += '.gem' unless gemfile =~ /\.gem$/
        log.info "Searching for local gem file #{gemfile}"
        if File.exist?(gemfile)
          File.open(gemfile, 'rb') do |io|
            expand_and_parse(gemfile, io)
          end
          return true
        end

        # Remote gemfile from rubygems.org
        url = "http://rubygems.org/downloads/#{gemfile}"
        log.info "Searching for remote gem file #{url}"
        begin
          # Note: In Ruby 2.4.x, URI.open is a private method. After
          # 2.5, URI.open behaves much like Kernel#open once you've
          # required 'open-uri'
          OpenURI.open_uri(url) {|io| expand_and_parse(gemfile, io) }
          return true
        rescue OpenURI::HTTPError
          nil # noop
        end
        false
      end

      def expand_and_parse(gemfile, io)
        dir = expand_gem(gemfile, io)
        generate_yardoc(dir)
        cleanup(gemfile)
      end

      def generate_yardoc(dir)
        Dir.chdir(dir) do
          log.enter_level(Logger::ERROR) { Yardoc.run('-n', '--no-save') }
        end
      end

      def expand_gem(gemfile, io)
        tmpdir = File.join(Dir.tmpdir, gemfile)
        FileUtils.mkdir_p(tmpdir)
        log.info "Expanding #{gemfile} to #{tmpdir}..."

        if Gem::VERSION >= '2.0.0'
          require 'rubygems/package/tar_reader'
          reader = Gem::Package::TarReader.new(io)
          reader.each do |pkg|
            next unless pkg.full_name == 'data.tar.gz'
            Zlib::GzipReader.wrap(pkg) do |gzio|
              tar = Gem::Package::TarReader.new(gzio)
              tar.each do |entry|
                file = File.join(tmpdir, entry.full_name)
                FileUtils.mkdir_p(File.dirname(file))
                File.open(file, 'wb') do |out|
                  out.write(entry.read)
                  begin
                    out.fsync
                  rescue NotImplementedError
                    nil # noop
                  end
                end
              end
            end
            break
          end
        else
          Gem::Package.open(io) do |pkg|
            pkg.each do |entry|
              pkg.extract_entry(tmpdir, entry)
            end
          end
        end

        tmpdir
      end

      def require_rubygems
        require 'rubygems'
        require 'rubygems/package'
      rescue LoadError => e
        log.error "Missing RubyGems, cannot run this command."
        raise(e)
      end

      def cleanup(gemfile)
        dir = File.join(Dir.tmpdir, gemfile)
        log.info "Cleaning up #{dir}..."
        FileUtils.rm_rf(dir)
      end

      def optparse(*args)
        opts = OptionParser.new
        opts.banner = "Usage: yard diff [options] oldgem newgem"
        opts.separator ""
        opts.separator "Example: yard diff yard-0.5.6 yard-0.5.8"
        opts.separator ""
        opts.separator "If the files don't exist locally, they will be grabbed using the `gem fetch`"
        opts.separator "command. If the gem is a .yardoc directory, it will be used. Finally, if the"
        opts.separator "gem name matches an installed gem (full name-version syntax), that gem will be used."

        opts.on('-a', '--all', 'List all objects, even if they are inside added/removed module/class') do
          @list_all = true
        end
        opts.on('--compact', 'Show compact results') { @compact = true }
        opts.on('--git', 'Compare versions from two git commit/branches') do
          @use_git = true
        end
        opts.on('--query QUERY', 'Only diff filtered objects') do |query|
          @verifier.add_expressions(query)
        end
        opts.on('--no-modified', 'Ignore modified objects') do
          @modified = false
        end
        common_options(opts)
        parse_options(opts, args)
        unless args.size == 2
          log.puts opts.banner
          exit(0)
        end

        args
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/display.rb000066400000000000000000000036371466601756300170460ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # Display one object
    # @since 0.8.6
    class Display < Yardoc
      def description; 'Displays a formatted object' end

      def initialize(*args)
        super
        options.format = :text # default for this command
        @layout = nil
        @objects = []
      end

      # Runs the commandline utility, parsing arguments and displaying an object
      # from the {Registry}.
      #
      # @param [Array] args the list of arguments.
      # @return [void]
      def run(*args)
        return unless parse_arguments(*args)
        log.puts wrap_layout(format_objects)
      end

      # @return [String] the output data for all formatted objects
      def format_objects
        @objects.inject([]) do |arr, obj|
          arr.push obj.format(options)
        end.join("\n")
      end

      def wrap_layout(contents)
        return contents unless @layout
        opts = options.merge(
          :contents => contents,
          :object => @objects.first,
          :objects => @objects
        )
        args = [options.template, @layout, options.format]
        Templates::Engine.template(*args).run(opts)
      end

      # Parses commandline options.
      # @param [Array] args each tokenized argument
      def parse_arguments(*args)
        opts = OptionParser.new
        opts.banner = "Usage: yard display [options] OBJECT [OTHER OBJECTS]"
        general_options(opts)
        output_options(opts)
        parse_options(opts, args)

        Registry.load
        @objects = args.map {|o| Registry.at(o) }

        # validation
        return false if @objects.any?(&:nil?)
        verify_markup_options
      end

      def output_options(opts)
        super(opts)
        opts.on('-l', '--layout [LAYOUT]', 'Wraps output in layout template (good for HTML)') do |layout|
          @layout = layout || 'layout'
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/gems.rb000066400000000000000000000046201466601756300163250ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # @since 0.6.0
    class Gems < Command
      def initialize
        @rebuild = false
        @gems = []
      end

      def description; "Builds YARD index for gems" end

      # Runs the commandline utility, parsing arguments and generating
      # YARD indexes for gems.
      #
      # @param [Array] args the list of arguments
      # @return [void]
      def run(*args)
        require 'rubygems'
        optparse(*args)
        build_gems
      end

      private

      # Builds .yardoc files for all non-existing gems
      def build_gems
        require 'rubygems'
        @gems.each do |spec|
          ver = "= #{spec.version}"
          dir = Registry.yardoc_file_for_gem(spec.name, ver)
          if dir && File.directory?(dir) && !@rebuild
            log.debug "#{spec.name} index already exists at '#{dir}'"
          else
            yfile = Registry.yardoc_file_for_gem(spec.name, ver, true)
            next unless yfile
            next unless File.directory?(spec.full_gem_path)
            Registry.clear
            Dir.chdir(spec.full_gem_path) do
              log.info "Building yardoc index for gem: #{spec.full_name}"
              Yardoc.run('--no-stats', '-n', '-b', yfile)
            end
          end
        end
      end

      def add_gems(gems)
        0.step(gems.size - 1, 2) do |index|
          gem = gems[index]
          ver_require = gems[index + 1] || ">= 0"
          specs = YARD::GemIndex.find_all_by_name(gem, ver_require)
          if specs.empty?
            log.warn "#{gem} #{ver_require} could not be found in RubyGems index"
          else
            @gems += specs
          end
        end
      end

      # Parses options
      def optparse(*args)
        opts = OptionParser.new
        opts.banner = 'Usage: yard gems [options] [gem_name [version]]'
        opts.separator ""
        opts.separator "#{description}. If no gem_name is given,"
        opts.separator "all gems are built."
        opts.separator ""
        opts.on('--rebuild', 'Rebuilds index') do
          @rebuild = true
        end

        common_options(opts)
        parse_options(opts, args)
        add_gems(args)

        if !args.empty? && @gems.empty?
          log.error "No specified gems could be found for command"
        elsif @gems.empty?
          @gems += YARD::GemIndex.all if @gems.empty?
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/graph.rb000066400000000000000000000074641466601756300165040ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # Options to pass to the {Graph} CLI.
    class GraphOptions < Templates::TemplateOptions
      # @return [:dot] the default output format
      default_attr :format, :dot

      # @return [Boolean] whether to list the full class diagram
      attr_accessor :full

      # @return [Boolean] whether to show the object dependencies
      attr_accessor :dependencies

      # @return [String] any contents to pass to the digraph
      attr_accessor :contents
    end

    # A command-line utility to generate Graphviz graphs from
    # a set of objects
    #
    # @see Graph#run
    # @since 0.6.0
    class Graph < YardoptsCommand
      # The options parsed out of the commandline.
      # Default options are:
      #   :format => :dot
      attr_reader :options

      # The set of objects to include in the graph.
      attr_reader :objects

      # Creates a new instance of the command-line utility
      def initialize
        super
        @use_document_file = false
        @options = GraphOptions.new
        options.reset_defaults
        options.serializer = YARD::Serializers::StdoutSerializer.new
      end

      def description
        "Graphs class diagram using Graphviz"
      end

      # Runs the command-line utility.
      #
      # @example
      #   grapher = Graph.new
      #   grapher.run('--private')
      # @param [Array] args each tokenized argument
      def run(*args)
        parse_arguments(*args)

        contents = objects.map do |o|
          o.format(options.merge(:serialize => false))
        end.join("\n")
        opts = {:type => :layout, :contents => contents}
        options.update(opts)
        Templates::Engine.render(options)
      end

      private

      def unrecognized_option(err) end

      # Parses commandline options.
      # @param [Array] args each tokenized argument
      def optparse(*args)
        visibilities = [:public]
        opts = OptionParser.new

        opts.separator ""
        opts.separator "General Options:"

        opts.on('-b', '--db FILE', 'Use a specified .yardoc db to load from or save to. (defaults to .yardoc)') do |yfile|
          YARD::Registry.yardoc_file = yfile
        end

        opts.on('--full', 'Full class diagrams (show methods and attributes).') do
          options[:full] = true
        end

        opts.on('-d', '--dependencies', 'Show mixins in dependency graph.') do
          options[:dependencies] = true
        end

        opts.on('--no-public', "Don't show public methods. (default shows public)") do
          visibilities.delete(:public)
        end

        opts.on('--protected', "Show or don't show protected methods. (default hides protected)") do
          visibilities.push(:protected)
        end

        opts.on('--private', "Show or don't show private methods. (default hides private)") do
          visibilities.push(:private)
        end

        opts.separator ""
        opts.separator "Output options:"

        opts.on('--dot [OPTIONS]', 'Send the results directly to `dot` with optional arguments.') do |dotopts|
          options.serializer = Serializers::ProcessSerializer.new('dot ' + dotopts.to_s)
        end

        opts.on('-f', '--file [FILE]', 'Writes output to a file instead of stdout.') do |file|
          options.serializer = Serializers::FileSystemSerializer.new(:basepath => '.', :extension => nil)
          options.serializer.instance_eval "def serialized_path(object) #{file.inspect} end"
        end

        common_options(opts)
        parse_options(opts, args)

        Registry.load

        expression = "#{visibilities.uniq.inspect}.include?(object.visibility)"
        options.verifier = Verifier.new(expression)
        @objects = args.first ?
          args.map {|o| Registry.at(o) }.compact :
          [Registry.root]
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/help.rb000066400000000000000000000007431466601756300163240ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # Handles help for commands
    # @since 0.6.0
    class Help < Command
      def description; "Retrieves help for a command" end

      def run(*args)
        cmd = args.first && CommandParser.commands[args.first.to_sym]
        if cmd
          cmd.run('--help')
        else
          log.puts "Command #{args.first} not found." if args.first
          CommandParser.run('--help')
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/i18n.rb000066400000000000000000000045461466601756300161600ustar00rootroot00000000000000# frozen_string_literal: true
require "pathname"

module YARD
  module CLI
    # CLI command to support internationalization (a.k.a. i18n).
    # I18n feature is based on gettext technology.
    # This command generates .pot file from docstring and extra
    # documentation.
    #
    # @since 0.8.0
    # @todo Support msgminit and msgmerge features?
    class I18n < Yardoc
      def initialize
        super
        @options.serializer.basepath = "po/yard.pot"
      end

      def description
        'Generates .pot file from source code and extra documentation'
      end

      def run(*args)
        if args.empty? || !args.first.nil?
          # fail early if arguments are not valid
          return unless parse_arguments(*args)
        end

        YARD.parse(files, excluded)

        serializer = options.serializer
        pot_file_path = Pathname.new(serializer.basepath).expand_path
        pot_file_dir_path, pot_file_basename = pot_file_path.split
        relative_base_path = Pathname.pwd.relative_path_from(pot_file_dir_path)
        serializer.basepath = pot_file_dir_path.to_s
        serializer.serialize(pot_file_basename.to_s,
                             generate_pot(relative_base_path.to_s))

        true
      end

      private

      def general_options(opts)
        opts.banner = "Usage: yard i18n [options] [source_files [- extra_files]]"
        opts.top.list.clear
        opts.separator "(if a list of source files is omitted, "
        opts.separator "  {lib,app}/**/*.rb ext/**/*.{c,rb} is used.)"
        opts.separator ""
        opts.separator "Example: yard i18n -o yard.pot - FAQ LICENSE"
        opts.separator "  The above example outputs .pot file for files in"
        opts.separator "  lib/**/*.rb to yard.pot including the extra files"
        opts.separator "  FAQ and LICENSE."
        opts.separator ""
        opts.separator "A base set of options can be specified by adding a .yardopts"
        opts.separator "file to your base path containing all extra options separated"
        opts.separator "by whitespace."
        super(opts)
      end

      def generate_pot(relative_base_path)
        generator = YARD::I18n::PotGenerator.new(relative_base_path)
        objects = run_verifier(all_objects)
        generator.parse_objects(objects)
        generator.parse_files(options.files || [])
        generator.generate
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/list.rb000066400000000000000000000013141466601756300163420ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # Lists all constant and method names in the codebase. Uses {Yardoc} --list.
    class List < Command
      def description; 'Lists all constant and methods. Uses `yard doc --list`' end

      # Runs the commandline utility, parsing arguments and displaying a
      # list of objects
      #
      # @param [Array] args the list of arguments.
      # @return [void]
      def run(*args)
        if args.include?('--help')
          log.puts "Usage: yard list [yardoc_options]"
          log.puts "Takes the same arguments as yardoc. See yardoc --help"
        else
          Yardoc.run('-c', '--list', *args)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/markup_types.rb000066400000000000000000000020761466601756300201200ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # Lists all markup types
    # @since 0.8.6
    class MarkupTypes < Command
      def description; 'Lists all available markup types and libraries' end

      # Runs the commandline utility, parsing arguments and displaying a
      # list of markup types
      #
      # @param [Array] args the list of arguments.
      # @return [void]
      def run(*args) # rubocop:disable Lint/UnusedMethodArgument
        log.puts "Available markup types for `doc' command:"
        log.puts
        types = Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS
        exts = Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS
        types.sort_by {|name, _| name.to_s }.each do |name, providers|
          log.puts "[#{name}]"
          libs = providers.map {|p| p[:lib] }.compact
          log.puts "  Providers: #{libs.join(" ")}" unless libs.empty?
          if exts[name]
            log.puts "  Extensions: #{exts[name].map {|e| ".#{e}" }.join(" ")}"
          end

          log.puts
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/server.rb000066400000000000000000000224621466601756300167040ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module CLI
    # A local documentation server
    # @since 0.6.0
    class Server < Command
      # @return [Hash] a list of options to pass to the doc server
      attr_accessor :options

      # @return [Hash] a list of options to pass to the web server
      attr_accessor :server_options

      # @return [Hash] a list of library names and yardoc files to serve
      attr_accessor :libraries

      # @return [YARD::Server::Adapter] the adapter to use for loading the web server
      attr_accessor :adapter

      # @return [Array] a list of scripts to load
      # @since 0.6.2
      attr_accessor :scripts

      # @return [Array] a list of template paths to register
      # @since 0.6.2
      attr_accessor :template_paths

      # Creates a new instance of the Server command line utility
      def initialize
        super
        self.scripts = []
        self.template_paths = []
        self.libraries = {}
        self.options = SymbolHash.new(false).update(
          :single_library => true,
          :caching => false
        )
        self.server_options = {:Port => 8808}
      end

      def description
        "Runs a local documentation server"
      end

      def run(*args)
        optparse(*args)

        select_adapter.setup
        load_scripts
        load_template_paths
        adapter.new(libraries, options, server_options).start
      end

      private

      def load_scripts
        scripts.each {|file| load_script(file) }
      end

      def load_template_paths
        return if YARD::Config.options[:safe_mode]

        Templates::Engine.template_paths |= template_paths
      end

      def select_adapter
        return adapter if adapter

        require 'rubygems'
        require 'rack'
        self.adapter = YARD::Server::RackAdapter
      rescue LoadError
        self.adapter = YARD::Server::WebrickAdapter
      end

      def add_libraries(args)
        (0...args.size).step(2) do |index|
          library = args[index]
          dir = args[index + 1]

          libver = nil
          if dir
            if File.exist?(dir)
              # Provided dir contains a .yardopts file
              libver = create_library_version_if_yardopts_exist(library, dir)
              libver ||= YARD::Server::LibraryVersion.new(library, nil, dir)
            end
          else
            # Check if this dir contains a .yardopts file
            pwd = Dir.pwd
            libver = create_library_version_if_yardopts_exist(library, pwd)

            # Check default location
            yfile = File.join(pwd, Registry::DEFAULT_YARDOC_FILE)
            libver ||= YARD::Server::LibraryVersion.new(library, nil, yfile)
          end

          # Register library
          if libver
            libver.yardoc_file = File.expand_path(libver.yardoc_file) if libver.yardoc_file
            libver.source_path = File.expand_path(libver.source_path) if libver.source_path
            libraries[library] ||= []
            libraries[library] |= [libver]
          else
            log.warn "Cannot find yardoc db for #{library}: #{dir.inspect}"
          end
        end
      end

      # @param [String] library The library name.
      # @param [String, nil] dir The argument provided on the CLI after the
      #   library name. Is supposed to point to either a project directory
      #   with a Yard options file, or a yardoc db.
      # @return [LibraryVersion, nil]
      def create_library_version_if_yardopts_exist(library, dir)
        if dir
          options_file = File.join(dir, Yardoc::DEFAULT_YARDOPTS_FILE)
          if File.exist?(options_file)
            # Found yardopts, extract db path
            yfile = extract_db_from_options_file(options_file)
            db = File.expand_path(yfile, dir)

            # Create libver
            libver = YARD::Server::LibraryVersion.new(library, nil, db)
            libver.source_path = dir
            libver
          end
        end
      end

      def add_gems
        require 'rubygems'
        YARD::GemIndex.each do |spec|
          libraries[spec.name] ||= []
          libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name, spec.version.to_s,
                                                                    nil, :gem)]
        end
      end

      def add_gems_from_gemfile(gemfile = nil)
        require 'bundler'
        gemfile ||= "Gemfile"
        if File.exist?("#{gemfile}.lock")
          Bundler::LockfileParser.new(File.read("#{gemfile}.lock")).specs.each do |spec|
            libraries[spec.name] ||= []
            libraries[spec.name] |= [YARD::Server::LibraryVersion.new(spec.name,
                                                                      spec.version.to_s, nil, :gem)]
          end
        else
          log.warn "Cannot find #{gemfile}.lock, ignoring --gemfile option"
        end
      rescue LoadError
        log.error "Bundler not available, ignoring --gemfile option"
      end

      def optparse(*args)
        opts = OptionParser.new
        opts.banner = 'Usage: yard server [options] [[library yardoc_file] ...]'
        opts.separator ''
        opts.separator 'Example: yard server -m yard .yardoc ruby-core ../ruby/.yardoc'
        opts.separator 'The above example serves documentation for YARD and Ruby-core'
        opts.separator ''
        opts.separator 'If no library/yardoc_file is specified, the server uses'
        opts.separator 'the name of the current directory and `.yardoc` respectively'
        opts.separator ''
        opts.separator "General Options:"
        opts.on('-m', '--multi-library', 'Serves documentation for multiple libraries') do
          options[:single_library] = false
        end
        opts.on('-c', '--cache', 'Caches all documentation to document root (see --docroot)') do
          options[:caching] = true
        end
        opts.on('-r', '--reload', 'Reparses the library code on each request') do
          options[:incremental] = true
        end
        opts.on('-g', '--gems', 'Serves documentation for installed gems') do
          add_gems
        end
        opts.on('-G', '--gemfile [GEMFILE]',
                'Serves documentation for gems from Gemfile') do |gemfile|
          add_gems_from_gemfile(gemfile)
        end
        opts.on('-t', '--template-path PATH',
                'The template path to look for templates in. (used with -t).') do |path|
          template_paths << path
        end
        opts.separator ''
        opts.separator "Web Server Options:"
        opts.on('-d', '--daemon', 'Daemonizes the server process') do
          server_options[:daemonize] = true
        end
        opts.on('-B HOST', '--bind', 'The host address to bind to') do |host|
          server_options[:Host] = host.to_s
        end
        opts.on('-p PORT', '--port', 'Serves documentation on PORT') do |port|
          server_options[:Port] = port.to_i
        end
        opts.on('--docroot DOCROOT', 'Uses DOCROOT as document root') do |docroot|
          server_options[:DocumentRoot] = File.expand_path(docroot)
        end
        opts.on('-a', '--adapter ADAPTER',
                'Use the ADAPTER (full Ruby class) for web server') do |adapter|
          self.adapter = if adapter.casecmp('webrick') == 0
                           YARD::Server::WebrickAdapter
                         elsif adapter.casecmp('rack') == 0
                           YARD::Server::RackAdapter
                         else
                           eval(adapter) # rubocop:disable Security/Eval
                         end
        end
        opts.on('-s', '--server TYPE',
                'Use a specific server type eg. thin,mongrel,cgi (Rack specific)') do |type|
          server_options[:server] = type
        end
        opts.on('--fork', 'Use process forking when serving requests') do
          options[:use_fork] = true
        end
        common_options(opts)
        opts.on('-e', '--load FILE',
                'A Ruby script to load before the source tree is parsed.') do |file|
          scripts << file
        end
        parse_options(opts, args)

        if args.empty? && libraries.empty?
          # No args - try to use current dir
          add_libraries([File.basename(Dir.pwd), nil])

          # Generate doc for first time
          # This is not necessary but makes for a better first-run experience
          libver = libraries.empty? ? nil : libraries.values.first.first
          generate_doc_for_first_time(libver) if libver && !libver.ready?
        else
          add_libraries(args)
          options[:single_library] = false if libraries.size > 1
        end
      end

      def generate_doc_for_first_time(libver)
        log.enter_level(Logger::INFO) do
          yardoc_file = libver.yardoc_file.sub(%r{^#{Regexp.quote Dir.pwd}[\\/]+}, '')
          log.info "No yardoc db found in #{yardoc_file}, parsing source before starting server..."
        end
        Dir.chdir(libver.source_path) do
          Yardoc.run('-n')
        end
      end

      def extract_db_from_options_file(options_file)
        args = File.read_binary(options_file).shell_split
        db = YARD::Registry.yardoc_file
        opts = OptionParser.new
        opts.on('-b', '--db FILE') {|file| db = file }

        begin
          opts.parse!(args)
        rescue OptionParser::ParseError
          args.shift if args.first && args.first[0, 1] != '-'
          retry
        end

        db
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/stats.rb000066400000000000000000000162411466601756300165320ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CLI
    # @since 0.6.0
    class Stats < Yardoc
      include Templates::Helpers::BaseHelper

      # Maintains the order in which +stats_for_+ statistics methods should be
      # printed.
      #
      # @see #print_statistics
      STATS_ORDER = [:files, :modules, :classes, :constants, :attributes, :methods]

      # @return [Boolean] whether to parse and load registry
      attr_accessor :parse

      # @param [Boolean] parse whether to parse and load registry (see {#parse})
      def initialize(parse = true)
        super()
        @parse = parse
        @undoc_list = nil
        @compact = false
      end

      def description
        "Prints documentation statistics on a set of files"
      end

      # Runs the commandline utility, parsing arguments and generating
      # output if set.
      #
      # @param [Array] args the list of arguments
      # @return [void]
      def run(*args)
        parse_arguments(*args)

        if use_cache
          Registry.load!
        elsif parse
          YARD.parse(files, excluded)
          Registry.save(use_cache) if save_yardoc
        end

        print_statistics
        print_undocumented_objects

        abort if fail_on_warning && log.warned
      end

      # Prints statistics for different object types
      #
      # To add statistics for a specific type, add a method +#stats_for_TYPE+
      # to this class that calls {#output}.
      def print_statistics
        @total = 0
        @undocumented = 0
        meths = methods.map(&:to_s).grep(/^stats_for_/)
        STATS_ORDER.each do |meth|
          mname = "stats_for_#{meth}"
          if meths.include?(mname)
            send(mname)
            meths.delete(mname)
          end
        end
        meths.each {|m| send(m) }

        total =
          if @undocumented == 0
            100
          elsif @total == 0
            0
          else
            (@total - @undocumented).to_f / @total.to_f * 100
          end
        log.puts("% 3.2f%% documented" % total)
      end

      # Prints list of undocumented objects
      def print_undocumented_objects
        return if !@undoc_list || @undoc_list.empty?
        log.puts
        log.puts "Undocumented Objects:"

        # array needed for sort due to unstable sort
        objects = @undoc_list.sort_by {|o| [o.file.to_s, o.path] }
        max = objects.max {|a, b| a.path.length <=> b.path.length }.path.length
        if @compact
          objects.each do |object|
            log.puts("%-#{max}s     (%s)" % [object.path,
              [object.file || "-unknown-", object.line].compact.join(":")])
          end
        else
          last_file = nil
          objects.each do |object|
            if object.file != last_file
              log.puts
              log.puts "(in file: #{object.file || "-unknown-"})"
            end
            log.puts object.path
            last_file = object.file
          end
        end
      end

      # @return [Array] all the parsed objects in the registry,
      #   removing any objects that are not visible (private, protected) depending
      #   on the arguments passed to the command.
      def all_objects
        @all_objects ||= run_verifier Registry.all
      end

      # Statistics for files
      def stats_for_files
        files = []
        all_objects.each {|o| files |= [o.file] }
        output "Files", files.size
      end

      # Statistics for modules
      def stats_for_modules
        output "Modules", *type_statistics(:module)
      end

      # Statistics for classes
      def stats_for_classes
        output "Classes", *type_statistics(:class)
      end

      # Statistics for constants
      def stats_for_constants
        output "Constants", *type_statistics(:constant)
      end

      # Statistics for attributes
      def stats_for_attributes
        objs = all_objects.select {|m| m.type == :method && m.is_attribute? }
        objs.uniq! {|m| m.name.to_s.gsub(/=$/, '') }
        undoc = objs.select {|m| m.docstring.blank? }
        @undoc_list |= undoc if @undoc_list
        output "Attributes", objs.size, undoc.size
      end

      # Statistics for methods
      def stats_for_methods
        objs = all_objects.select {|m| m.type == :method }
        objs.reject!(&:is_alias?)
        objs.reject!(&:is_attribute?)
        undoc = objs.select {|m| m.docstring.blank? }
        @undoc_list |= undoc if @undoc_list
        output "Methods", objs.size, undoc.size
      end

      # Prints a statistic to standard out. This method is optimized for
      # getting Integer values, though it allows any data to be printed.
      #
      # @param [String] name the statistic name
      # @param [Integer, String] data the numeric (or any) data representing
      #   the statistic. If +data+ is an Integer, it should represent the
      #   total objects of a type.
      # @param [Integer, nil] undoc number of undocumented objects for the type
      # @return [void]
      def output(name, data, undoc = nil)
        @total += data if data.is_a?(Integer) && undoc
        @undocumented += undoc if undoc.is_a?(Integer)
        data =
          if undoc
            ("%5s (% 5d undocumented)" % [data, undoc])
          else
            "%5s" % data
          end
        log.puts("%-12s %s" % [name + ":", data])
      end

      private

      def type_statistics(type)
        objs = all_objects.select {|m| m.type == type }
        undoc = objs.find_all {|m| m.docstring.blank? }
        @undoc_list |= undoc if @undoc_list
        [objs.size, undoc.size]
      end

      # Parses commandline options.
      # @param [Array] args each tokenized argument
      def optparse(*args)
        opts = OptionParser.new
        opts.banner = "Usage: yard stats [options] [source_files]"

        opts.separator "(if a list of source files is omitted, lib/**/*.rb ext/**/*.{c,rb} is used.)"

        general_options(opts)
        output_options(opts)
        tag_options(opts)
        common_options(opts)
        parse_options(opts, args)
        parse_files(*args) unless args.empty?
      end

      def general_options(opts)
        super(opts)

        opts.on('--list-undoc', 'List all undocumented objects') do
          @undoc_list = []
        end

        opts.on('--compact', 'Compact undocumented objects listing') do
          @compact = true
        end

        opts.on('--no-public', "Don't include public methods in statistics.") do
          visibilities.delete(:public)
        end

        opts.on('--protected', "Include protected methods in statistics.") do
          visibilities.push(:protected)
        end

        opts.on('--private', "Include private methods in statistics.") do
          visibilities.push(:private)
        end

        opts.on('--no-private', "Don't include objects with @private tag in statistics.") do
          options[:verifier].add_expressions '!object.tag(:private) &&
            (object.namespace.type == :proxy || !object.namespace.tag(:private))'
        end

        opts.on('--query QUERY', "Only includes objects that match a specific query") do |query|
          query.taint if query.respond_to?(:taint)
          options[:verifier].add_expressions(query)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/yardoc.rb000066400000000000000000000666331466601756300166670ustar00rootroot00000000000000# frozen_string_literal: true
require 'digest/sha1'
require 'fileutils'

module YARD
  module CLI
    # Default options used in +yard doc+ command.
    class YardocOptions < Templates::TemplateOptions
      # @return [Array]
      #   the list of extra files rendered along with objects
      default_attr :files, lambda { [] }

      # @return [String] the default title appended to each generated page
      default_attr :title, "Documentation by YARD #{YARD::VERSION}"

      # @return [Verifier] the default verifier object to filter queries
      default_attr :verifier, lambda { Verifier.new }

      # @return [Serializers::Base] the default serializer for generating output
      #   to disk.
      default_attr :serializer, lambda { Serializers::FileSystemSerializer.new }

      # @return [Symbol] the default output format (:html).
      default_attr :format, :html

      # @return [Boolean] whether the data should be rendered in a single page,
      #   if the template supports it.
      default_attr :onefile, false

      # @return [CodeObjects::ExtraFileObject] the README file object rendered
      #   along with objects
      attr_accessor :readme

      # @return [Array] the list of code objects to render
      #   the templates with.
      attr_accessor :objects

      # @return [Numeric] An index value for rendering sequentially related templates
      attr_accessor :index

      # @return [CodeObjects::Base] an extra item to send to a template that is not
      #   the main rendered object
      attr_accessor :item

      # @return [CodeObjects::ExtraFileObject] the file object being rendered.
      #   The +object+ key is not used so that a file may be rendered in the context
      #   of an object's namespace (for generating links).
      attr_accessor :file

      # @return [String] the current locale
      attr_accessor :locale
    end

    # Yardoc is the default YARD CLI command (+yard doc+ and historic +yardoc+
    # executable) used to generate and output (mainly) HTML documentation given
    # a set of source files.
    #
    # == Usage
    #
    # Main usage for this command is:
    #
    #   $ yardoc [options] [source_files [- extra_files]]
    #
    # See +yardoc --help+ for details on valid options.
    #
    # == Options File (+.yardopts+)
    #
    # If a +.yardopts+ file is found in the source directory being processed,
    # YARD will use the contents of the file as arguments to the command,
    # treating newlines as spaces. You can use shell-style quotations to
    # group space delimited arguments, just like on the command line.
    #
    # A valid +.yardopts+ file might look like:
    #
    #   --no-private
    #   --title "My Title"
    #   --exclude foo --exclude bar
    #   lib/**/*.erb
    #   lib/**/*.rb -
    #   HACKING.rdoc LEGAL COPYRIGHT
    #
    # Note that Yardoc also supports the legacy RDoc style +.document+ file,
    # though this file can only specify source globs to parse, not options.
    #
    # == Queries (+--query+)
    #
    # Yardoc supports queries to select specific code objects for which to
    # generate documentation. For example, you might want to generate
    # documentation only for your public API. If you've documented your public
    # methods with +@api public+, you can use the following query to select
    # all of these objects:
    #
    #   --query '@api.text == "public"'
    #
    # Note that the syntax for queries is mostly Ruby with a few syntactic
    # simplifications for meta-data tags. See the {Verifier} class for an
    # overview of this syntax.
    #
    # == Adding Custom Ad-Hoc Meta-data Tags (+--tag+)
    #
    # YARD allows specification of {file:docs/Tags.md meta-data tags}
    # programmatically via the {YARD::Tags::Library} class, but often this is not
    # practical for users writing documentation. To make adding custom tags
    # easier, Yardoc has a few command-line switches for creating basic tags
    # and displaying them in generated HTML output.
    #
    # To specify a custom tag to be displayed in output, use any of the
    # following:
    #
    # * +--tag+ TAG:TITLE
    # * +--name-tag+ TAG:TITLE
    # * +--type-tag+ TAG:TITLE
    # * +--type-name-tag+ TAG:TITLE
    # * +--title-tag+ TAG:TITLE
    #
    # "TAG:TITLE" is of the form: name:"Display Title", for example:
    #
    #   --tag overload:"Overloaded Method"
    #
    # See +yard help doc+ for a description of the various options.
    #
    # Tags added in this way are automatically displayed in output. To add
    # a meta-data tag that does not show up in output, use +--hide-tag TAG+.
    # Note that you can also use this option on existing tags to hide
    # builtin tags, for instance.
    #
    # == Processed Data Storage (+.yardoc+ directory)
    #
    # When Yardoc parses a source directory, it creates a +.yardoc+ directory
    # (by default, override with +-b+) at the root of the project. This directory
    # contains marshal dumps for all raw object data in the source, so that
    # you can access it later for various commands (+stats+, +graph+, etc.).
    # This directory is also used as a cache for any future calls to +yardoc+
    # so as to process only the files which have changed since the last call.
    #
    # When Yardoc uses the cache in subsequent calls to +yardoc+, methods
    # or classes that have been deleted from source since the last parsing
    # will not be erased from the cache (YARD never deletes objects). In such
    # a case, you should wipe the cache and do a clean parsing of the source tree.
    # You can do this by deleting the +.yardoc+ directory manually, or running
    # Yardoc without +--use-cache+ (+-c+).
    #
    # @since 0.2.1
    # @see Verifier
    class Yardoc < YardoptsCommand
      # @return [Hash] the hash of options passed to the template.
      # @see Templates::Engine#render
      attr_reader :options

      # @return [Array] list of Ruby source files to process
      attr_accessor :files

      # @return [Array] list of excluded paths (regexp matches)
      # @since 0.5.3
      attr_accessor :excluded

      # @return [Boolean] whether to use the existing yardoc db if the
      #   .yardoc already exists. Also makes use of file checksums to
      #   parse only changed files.
      attr_accessor :use_cache

      # @return [Boolean] whether objects should be serialized to .yardoc db
      attr_accessor :save_yardoc

      # @return [Boolean] whether to generate output
      attr_accessor :generate

      # @return [Boolean] whether to print a list of objects
      # @since 0.5.5
      attr_accessor :list

      # Keep track of which visibilities are to be shown
      # @return [Array] a list of visibilities
      # @since 0.5.6
      attr_accessor :visibilities

      # Keep track of which APIs are to be shown
      # @return [Array] a list of APIs
      # @since 0.8.1
      attr_accessor :apis

      # Keep track of which APIs are to be hidden
      # @return [Array] a list of APIs to be hidden
      # @since 0.8.7
      attr_accessor :hidden_apis

      # @return [Array] a list of tags to hide from templates
      # @since 0.6.0
      attr_accessor :hidden_tags

      # @return [Boolean] whether to print statistics after parsing
      # @since 0.6.0
      attr_accessor :statistics

      # @return [Array] a list of assets to copy after generation
      # @since 0.6.0
      attr_accessor :assets

      # @return [Boolean] whether markup option was specified
      # @since 0.7.0
      attr_accessor :has_markup

      # @return [Boolean] whether yard exits with error status code if a warning occurs
      attr_accessor :fail_on_warning

      # Creates a new instance of the commandline utility
      def initialize
        super
        @options = YardocOptions.new
        @options.reset_defaults
        @visibilities = [:public]
        @apis = []
        @hidden_apis = []
        @assets = {}
        @excluded = []
        @files = []
        @hidden_tags = []
        @use_cache = false
        @generate = true
        @statistics = true
        @list = false
        @save_yardoc = true
        @has_markup = false
        @fail_on_warning = false

        if defined?(::Encoding) && ::Encoding.respond_to?(:default_external=)
          utf8 = ::Encoding.find('utf-8')

          ::Encoding.default_external = utf8 unless ::Encoding.default_external == utf8
          ::Encoding.default_internal = utf8 unless ::Encoding.default_internal == utf8
        end
      end

      def description
        "Generates documentation"
      end

      # Runs the commandline utility, parsing arguments and generating
      # output if set.
      #
      # @param [Array] args the list of arguments. If the list only
      #   contains a single nil value, skip calling of {#parse_arguments}
      # @return [void]
      def run(*args)
        log.show_progress = true
        if args.empty? || !args.first.nil?
          # fail early if arguments are not valid
          return unless parse_arguments(*args)
        end

        checksums = nil
        if use_cache
          Registry.load
          checksums = Registry.checksums.dup
        end

        if save_yardoc
          Registry.lock_for_writing do
            YARD.parse(files, excluded)
            Registry.save(use_cache)
          end
        else
          YARD.parse(files, excluded)
        end

        if generate
          run_generate(checksums)
          copy_assets
        elsif list
          print_list
        end

        if !list && statistics && log.level < Logger::ERROR
          Registry.load_all
          log.enter_level(Logger::ERROR) do
            Stats.new(false).run(*args)
          end
        end

        abort if fail_on_warning && log.warned

        true
      ensure
        log.show_progress = false
      end

      # Parses commandline arguments
      # @param [Array] args the list of arguments
      # @return [Boolean] whether or not arguments are valid
      # @since 0.5.6
      def parse_arguments(*args)
        super(*args)

        # Last minute modifications
        self.files = Parser::SourceParser::DEFAULT_PATH_GLOB if files.empty?
        files.delete_if {|x| x =~ /\A\s*\Z/ } # remove empty ones
        readme = Dir.glob('README{,*[^~]}').
          select {|f| extra_file_valid?(f)}.
          sort_by {|r| [r.count('.'), r.index('.'), r] }.first
        readme ||= Dir.glob(files.first).first if options.onefile && !files.empty?
        options.readme ||= CodeObjects::ExtraFileObject.new(readme) if readme && extra_file_valid?(readme)
        options.files.unshift(options.readme).uniq! if options.readme

        Tags::Library.visible_tags -= hidden_tags
        add_visibility_verifier
        add_api_verifier

        apply_locale

        # US-ASCII is invalid encoding for onefile
        if defined?(::Encoding) && options.onefile
          if ::Encoding.default_internal == ::Encoding::US_ASCII
            log.warn "--one-file is not compatible with US-ASCII encoding, using ASCII-8BIT"
            ::Encoding.default_external, ::Encoding.default_internal = ['ascii-8bit'] * 2
          end
        end

        if generate && !verify_markup_options
          false
        else
          true
        end
      end

      # The list of all objects to process. Override this method to change
      # which objects YARD should generate documentation for.
      #
      # @deprecated To hide methods use the +@private+ tag instead.
      # @return [Array] a list of code objects to process
      def all_objects
        Registry.all(:root, :module, :class)
      end

      private

      # Generates output for objects
      # @param [Hash, nil] checksums if supplied, a list of checksums for files.
      # @return [void]
      # @since 0.5.1
      def run_generate(checksums)
        if checksums
          changed_files = []
          Registry.checksums.each do |file, hash|
            changed_files << file if checksums[file] != hash
          end
        end
        Registry.load_all if use_cache
        objects = run_verifier(all_objects).reject do |object|
          serialized = !options.serializer || options.serializer.exists?(object)
          if checksums && serialized && !object.files.any? {|f, _line| changed_files.include?(f) }
            true
          else
            log.debug "Re-generating object #{object.path}..."
            false
          end
        end
        Templates::Engine.generate(objects, options)
      end

      # Verifies that the markup options are valid before parsing any code.
      # Failing early is better than failing late.
      #
      # @return (see YARD::Templates::Helpers::MarkupHelper#load_markup_provider)
      def verify_markup_options
        result = false
        lvl = has_markup ? log.level : Logger::FATAL
        obj = Struct.new(:options).new(options)
        obj.extend(Templates::Helpers::MarkupHelper)
        options.files.each do |file|
          markup = file.attributes[:markup] || obj.markup_for_file('', file.filename)
          result = obj.load_markup_provider(markup)
          return false if !result && markup != :rdoc
        end
        options.markup = :rdoc unless has_markup
        log.enter_level(lvl) { result = obj.load_markup_provider }
        if !result && !has_markup
          log.warn "Could not load default RDoc formatter, " \
                   "ignoring any markup (install RDoc to get default formatting)."
          options.markup = :none
          true
        else
          result
        end
      end

      # Copies any assets to the output directory
      # @return [void]
      # @since 0.6.0
      def copy_assets
        return unless options.serializer
        outpath = options.serializer.basepath
        assets.each do |from, to|
          to = File.join(outpath, to)
          log.debug "Copying asset '#{from}' to '#{to}'"
          from += '/.' if File.directory?(from)
          FileUtils.cp_r(from, to)
        end
      end

      # Prints a list of all objects
      # @return [void]
      # @since 0.5.5
      def print_list
        Registry.load_all
        run_verifier(Registry.all).
          sort_by {|item| [item.file || '', item.line || 0] }.each do |item|
          log.puts "#{item.file}:#{item.line}: #{item.path}"
        end
      end

      # Adds a set of extra documentation files to be processed
      # @param [Array] files the set of documentation files
      def add_extra_files(*files)
        files.map! {|f| f.include?("*") ? Dir.glob(f) : f }.flatten!
        files.each do |file|
          if extra_file_valid?(file)
            options.files << CodeObjects::ExtraFileObject.new(file)
          end
        end
      end

      # @param file [String] the filename to validate
      # @param check_exists [Boolean] whether the file should exist on disk
      # @return [Boolean] whether the file is allowed to be used
      def extra_file_valid?(file, check_exists = true)
        if file =~ %r{^(?:\.\./|/)}
          log.warn "Invalid file: #{file}"
          false
        elsif check_exists && !File.file?(file)
          log.warn "Could not find file: #{file}"
          false
        else
          true
        end
      end

      # Parses the file arguments into Ruby files and extra files, which are
      # separated by a '-' element.
      #
      # @example Parses a set of Ruby source files
      #   parse_files %w(file1 file2 file3)
      # @example Parses a set of Ruby files with a separator and extra files
      #   parse_files %w(file1 file2 - extrafile1 extrafile2)
      # @param [Array] files the list of files to parse
      # @return [void]
      def parse_files(*files)
        seen_extra_files_marker = false

        files.each do |file|
          if file == "-"
            seen_extra_files_marker = true
            next
          end

          if seen_extra_files_marker
            add_extra_files(file)
          else
            self.files << file
          end
        end
      end

      # Adds verifier rule for visibilities
      # @return [void]
      # @since 0.5.6
      def add_visibility_verifier
        vis_expr = "#{visibilities.uniq.inspect}.include?(object.visibility)"
        options.verifier.add_expressions(vis_expr)
      end

      # Adds verifier rule for APIs
      # @return [void]
      # @since 0.8.1
      def add_api_verifier
        no_api = true if apis.delete('')
        exprs = []

        exprs << "#{apis.uniq.inspect}.include?(@api.text)" unless apis.empty?

        unless hidden_apis.empty?
          exprs << "!#{hidden_apis.uniq.inspect}.include?(@api.text)"
        end

        exprs = !exprs.empty? ? [exprs.join(' && ')] : []
        exprs << "!@api" if no_api

        expr = exprs.join(' || ')
        options.verifier.add_expressions(expr) unless expr.empty?
      end

      # Applies the specified locale to collected objects
      # @return [void]
      # @since 0.8.3
      def apply_locale
        YARD::I18n::Locale.default = options.locale
        options.files.each do |file|
          file.locale = options.locale
        end
      end

      # (see Templates::Helpers::BaseHelper#run_verifier)
      def run_verifier(list)
        options.verifier ? options.verifier.run(list) : list
      end

      # @since 0.6.0
      def add_tag(tag_data, factory_method = nil)
        tag, title = *tag_data.split(':')
        title ||= tag.capitalize
        Tags::Library.define_tag(title, tag.to_sym, factory_method)
        Tags::Library.visible_tags |= [tag.to_sym]
      end

      # Parses commandline options.
      # @param [Array] args each tokenized argument
      def optparse(*args)
        opts = OptionParser.new
        opts.banner = "Usage: yard doc [options] [source_files [- extra_files]]"

        opts.separator "(if a list of source files is omitted, "
        opts.separator "  {lib,app}/**/*.rb ext/**/*.{c,rb} is used.)"
        opts.separator ""
        opts.separator "Example: yardoc -o documentation/ - FAQ LICENSE"
        opts.separator "  The above example outputs documentation for files in"
        opts.separator "  lib/**/*.rb to documentation/ including the extra files"
        opts.separator "  FAQ and LICENSE."
        opts.separator ""
        opts.separator "A base set of options can be specified by adding a .yardopts"
        opts.separator "file to your base path containing all extra options separated"
        opts.separator "by whitespace."

        general_options(opts)
        output_options(opts)
        tag_options(opts)
        common_options(opts)
        parse_options(opts, args)
        parse_files(*args) unless args.empty?
      end

      # Adds general options
      def general_options(opts)
        opts.separator ""
        opts.separator "General Options:"

        opts.on('-b', '--db FILE', 'Use a specified .yardoc db to load from or save to',
                      '  (defaults to .yardoc)') do |yfile|
          YARD::Registry.yardoc_file = yfile
        end

        opts.on('--[no-]single-db', 'Whether code objects should be stored to single',
                                    '  database file (advanced)') do |use_single_db|
          Registry.single_object_db = use_single_db
        end

        opts.on('-n', '--no-output', 'Only generate .yardoc database, no documentation.') do
          self.generate = false
        end

        opts.on('-c', '--use-cache [FILE]',
                "Use the cached .yardoc db to generate documentation.",
                "  (defaults to no cache)") do |file|
          YARD::Registry.yardoc_file = file if file
          self.use_cache = true
        end

        opts.on('--no-cache', "Clear .yardoc db before parsing source.") do
          self.use_cache = false
        end

        yardopts_options(opts)

        opts.on('--no-save', 'Do not save the parsed data to the yardoc db') do
          self.save_yardoc = false
        end

        opts.on('--exclude REGEXP', 'Ignores a file if it matches path match (regexp)') do |path|
          excluded << path
        end

        opts.on('--fail-on-warning', 'Exit with error status code if a warning occurs') do
          self.fail_on_warning = true
        end
      end

      # Adds output options
      def output_options(opts)
        opts.separator ""
        opts.separator "Output options:"

        opts.on('--one-file', 'Generates output as a single file') do
          options.onefile = true
        end

        opts.on('--list', 'List objects to standard out (implies -n)') do |_format|
          self.generate = false
          self.list = true
        end

        opts.on('--no-public', "Don't show public methods. (default shows public)") do
          visibilities.delete(:public)
        end

        opts.on('--protected', "Show protected methods. (default hides protected)") do
          visibilities.push(:protected)
        end

        opts.on('--private', "Show private methods. (default hides private)") do
          visibilities.push(:private)
        end

        opts.on('--no-private', "Hide objects with @private tag") do
          options.verifier.add_expressions '!object.tag(:private) &&
            (object.namespace.is_a?(CodeObjects::Proxy) || !object.namespace.tag(:private))'
        end

        opts.on('--[no-]api API', 'Generates documentation for a given API',
                                  '(objects which define the correct @api tag).',
                                  'If --no-api is given, displays objects with',
                                  'no @api tag.') do |api|
          api = '' if api == false
          apis.push(api)
        end

        opts.on('--hide-api API', 'Hides given @api tag from documentation') do |api|
          hidden_apis.push(api)
        end

        opts.on('--embed-mixins', "Embeds mixin methods into class documentation") do
          options.embed_mixins << '*'
        end

        opts.on('--embed-mixin [MODULE]', "Embeds mixin methods from a particular",
                                          " module into class documentation") do |mod|
          options.embed_mixins << mod
        end

        opts.on('--no-highlight', "Don't highlight code blocks in output.") do
          options.highlight = false
        end

        opts.on('--default-return TYPE', "Shown if method has no return type. ",
                                         "  (defaults to 'Object')") do |type|
          options.default_return = type
        end

        opts.on('--hide-void-return', "Hides return types specified as 'void'. ",
                                      "  (default is shown)") do
          options.hide_void_return = true
        end

        opts.on('--query QUERY', "Only show objects that match a specific query") do |query|
          next if YARD::Config.options[:safe_mode]
          query.taint if query.respond_to?(:taint)
          options.verifier.add_expressions(query)
        end

        opts.on('--title TITLE', 'Add a specific title to HTML documents') do |title|
          options.title = title
        end

        opts.on('-r', '--readme FILE', '--main FILE', 'The readme file used as the title page',
                                                      '  of documentation.') do |readme|
          if extra_file_valid?(readme)
            options.readme = CodeObjects::ExtraFileObject.new(readme)
          end
        end

        opts.on('--files FILE1,FILE2,...', 'Any extra comma separated static files to be ',
                                           '  included (eg. FAQ)') do |files|
          add_extra_files(*files.split(","))
        end

        opts.on('--asset FROM[:TO]', 'A file or directory to copy over to output ',
                                     '  directory after generating') do |asset|
          from, to = *asset.split(':').map {|f| File.cleanpath(f, true) }
          to ||= from
          if extra_file_valid?(from, false) && extra_file_valid?(to, false)
            assets[from] = to
          end
        end

        opts.on('-o', '--output-dir PATH',
                'The output directory. (defaults to ./doc)') do |dir|
          options.serializer.basepath = dir
        end

        opts.on('-m', '--markup MARKUP',
                'Markup style used in documentation, like textile, ',
                '  markdown or rdoc. (defaults to rdoc)') do |markup|
          self.has_markup = true
          options.markup = markup.to_sym
        end

        opts.on('-M', '--markup-provider MARKUP_PROVIDER',
                'Overrides the library used to process markup ',
                '  formatting (specify the gem name)') do |markup_provider|
          options.markup_provider = markup_provider.to_sym
        end

        opts.on('--charset ENC', 'Character set to use when parsing files ',
                                 '  (default is system locale)') do |encoding|
          begin
            if defined?(Encoding) && Encoding.respond_to?(:default_external=)
              Encoding.default_external = encoding
              Encoding.default_internal = encoding
            end
          rescue ArgumentError => e
            raise OptionParser::InvalidOption, e
          end
        end

        opts.on('-t', '--template TEMPLATE',
                'The template to use. (defaults to "default")') do |template|
          options.template = template.to_sym
        end

        opts.on('-p', '--template-path PATH',
                'The template path to look for templates in.',
                '  (used with -t).') do |path|
          next if YARD::Config.options[:safe_mode]
          YARD::Templates::Engine.register_template_path(File.expand_path(path))
        end

        opts.on('-f', '--format FORMAT',
                'The output format for the template.',
                '  (defaults to html)') do |format|
          options.format = format.to_sym
        end

        opts.on('--no-stats', 'Don\'t print statistics') do
          self.statistics = false
        end

        opts.on('--no-progress', 'Don\'t show progress bar') do
          log.show_progress = false
        end

        opts.on('--locale LOCALE',
                'The locale for generated documentation.',
                '  (defaults to en)') do |locale|
          options.locale = locale
        end

        opts.on('--po-dir DIR',
                'The directory that has .po files.',
                "  (defaults to #{YARD::Registry.po_dir})") do |dir|
          YARD::Registry.po_dir = dir
        end
      end

      # Adds tag options
      # @since 0.6.0
      def tag_options(opts)
        opts.separator ""
        opts.separator "Tag options: (TAG:TITLE looks like: 'overload:Overloaded Method')"

        opts.on('--tag TAG:TITLE', 'Registers a new free-form metadata @tag') do |tag|
          add_tag(tag)
        end

        opts.on('--type-tag TAG:TITLE', 'Tag with an optional types field') do |tag|
          add_tag(tag, :with_types)
        end

        opts.on('--type-name-tag TAG:TITLE', 'Tag with optional types and a name field') do |tag|
          add_tag(tag, :with_types_and_name)
        end

        opts.on('--name-tag TAG:TITLE', 'Tag with a name field') do |tag|
          add_tag(tag, :with_name)
        end

        opts.on('--title-tag TAG:TITLE', 'Tag with first line as title field') do |tag|
          add_tag(tag, :with_title_and_text)
        end

        opts.on('--hide-tag TAG', 'Hides a previously defined tag from templates') do |tag|
          self.hidden_tags |= [tag.to_sym]
        end

        opts.on('--transitive-tag TAG', 'Marks a tag as transitive') do |tag|
          Tags::Library.transitive_tags |= [tag.to_sym]
        end

        opts.on('--non-transitive-tag TAG', 'Marks a tag as not transitive') do |tag|
          Tags::Library.transitive_tags -= [tag.to_sym]
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/yardopts_command.rb000066400000000000000000000066531466601756300207450ustar00rootroot00000000000000# frozen_string_literal: true
require 'optparse'

module YARD
  module CLI
    # Abstract base class for command that reads .yardopts file
    #
    # @abstract
    # @since 0.8.3
    class YardoptsCommand < Command
      # The configuration filename to load extra options from
      DEFAULT_YARDOPTS_FILE = ".yardopts"

      # @return [Boolean] whether to parse options from .yardopts
      attr_accessor :use_yardopts_file

      # @return [Boolean] whether to parse options from .document
      attr_accessor :use_document_file

      # The options file name (defaults to {DEFAULT_YARDOPTS_FILE})
      # @return [String] the filename to load extra options from
      attr_accessor :options_file

      # Creates a new command that reads .yardopts
      def initialize
        super
        @options_file = DEFAULT_YARDOPTS_FILE
        @use_yardopts_file = true
        @use_document_file = true
      end

      # Parses commandline arguments
      # @param [Array] args the list of arguments
      # @return [Boolean] whether or not arguments are valid
      # @since 0.5.6
      def parse_arguments(*args)
        parse_yardopts_options(*args)

        # Parse files and then command line arguments
        parse_rdoc_document_file
        parse_yardopts
        optparse(*args)
      end

      protected

      # Adds --[no-]yardopts / --[no-]document
      def yardopts_options(opts)
        opts.on('--[no-]yardopts [FILE]',
                "If arguments should be read from FILE",
                "  (defaults to yes, FILE defaults to .yardopts)") do |use_yardopts|
          if use_yardopts.is_a?(String)
            self.options_file = use_yardopts
            self.use_yardopts_file = true
          else
            self.use_yardopts_file = (use_yardopts != false)
          end
        end

        opts.on('--[no-]document', "If arguments should be read from .document file. ",
                                   "  (defaults to yes)") do |use_document|
          self.use_document_file = use_document
        end
      end

      private

      # Parses the .yardopts file for default yard options
      # @return [Array] an array of options parsed from .yardopts
      def yardopts(file = options_file)
        return [] unless use_yardopts_file
        File.read_binary(file).shell_split
      rescue Errno::ENOENT
        []
      end

      # Parses out the yardopts/document options
      def parse_yardopts_options(*args)
        opts = OptionParser.new
        opts.base.long.clear # HACK: why are --help and --version defined?
        yardopts_options(opts)
        begin
          opts.parse(args)
        rescue OptionParser::ParseError => err
          idx = args.index(err.args.first)
          args = args[(idx + 1)..-1]
          args.shift while args.first && args.first[0, 1] != '-'
          retry
        end
      end

      def parse_rdoc_document_file(file = '.document')
        optparse(*support_rdoc_document_file!(file)) if use_document_file
      end

      def parse_yardopts(file = options_file)
        optparse(*yardopts(file)) if use_yardopts_file
      end

      # Reads a .document file in the directory to get source file globs
      # @return [Array] an array of files parsed from .document
      def support_rdoc_document_file!(file = '.document')
        return [] unless use_document_file
        File.read(file).gsub(/^[ \t]*#.+/m, '').split(/\s+/)
      rescue Errno::ENOENT
        []
      end
    end
  end
end
yard-0.9.37/lib/yard/cli/yri.rb000066400000000000000000000146501466601756300162010ustar00rootroot00000000000000# frozen_string_literal: true
require 'rbconfig'

module YARD
  module CLI
    # A tool to view documentation in the console like `ri`
    class YRI < Command
      # The location in {YARD::CONFIG_DIR} where the YRI cache file is loaded
      # from.
      CACHE_FILE = File.expand_path(File.join(YARD::Config::CONFIG_DIR, 'yri_cache'))

      # A file containing all paths, delimited by newlines, to search for
      # yardoc databases.
      # @since 0.5.1
      SEARCH_PATHS_FILE = File.expand_path(File.join(YARD::Config::CONFIG_DIR, 'yri_search_paths'))

      # Default search paths that should be loaded dynamically into YRI. These paths
      # take precedence over all other paths ({SEARCH_PATHS_FILE} and RubyGems
      # paths). To add a path, call:
      #
      #   DEFAULT_SEARCH_PATHS.push("/path/to/.yardoc")
      #
      # @return [Array] a list of extra search paths
      # @since 0.6.0
      DEFAULT_SEARCH_PATHS = []

      # Helper method to run the utility on an instance.
      # @see #run
      def self.run(*args) new.run(*args) end

      def initialize
        super
        @cache = {}
        @search_paths = []
        add_default_paths
        add_gem_paths
        load_cache
        @search_paths.uniq!
      end

      def description
        "A tool to view documentation in the console like `ri`"
      end

      # Runs the command-line utility.
      #
      # @example
      #   YRI.new.run('String#reverse')
      # @param [Array] args each tokenized argument
      def run(*args)
        optparse(*args)

        if ::RbConfig::CONFIG['host_os'] =~ /mingw|win32/
          @serializer ||= YARD::Serializers::StdoutSerializer.new
        else
          @serializer ||= YARD::Serializers::ProcessSerializer.new('less')
        end

        if @name.nil? || @name.strip.empty?
          print_usage
          return exit(1)
        end

        object = find_object(@name)
        if object
          print_object(object)
        else
          STDERR.puts "No documentation for `#{@name}'"
          return exit(1)
        end
      end

      protected

      # Prints the command usage
      # @return [void]
      # @since 0.5.6
      def print_usage
        log.puts "Usage: yri [options] "
        log.puts "See yri --help for more options."
      end

      # Caches the .yardoc file where an object can be found in the {CACHE_FILE}
      # @return [void]
      def cache_object(name, path)
        return if path == Registry.yardoc_file
        @cache[name] = path

        File.open!(CACHE_FILE, 'w') do |file|
          @cache.each do |key, value|
            file.puts("#{key} #{value}")
          end
        end
      end

      # @param [CodeObjects::Base] object the object to print.
      # @return [String] the formatted output for an object.
      def print_object(object)
        if object.type == :method && object.is_alias?
          tmp = P(object.namespace, (object.scope == :instance ? "#" : "") +
            object.namespace.aliases[object].to_s)
          object = tmp unless YARD::CodeObjects::Proxy === tmp
        end
        object.format(:serializer => @serializer)
      end

      # Locates an object by name starting in the cached paths and then
      # searching through any search paths.
      #
      # @param [String] name the full name of the object
      # @return [CodeObjects::Base] an object if found
      # @return [nil] if no object is found
      def find_object(name)
        @search_paths.unshift(@cache[name]) if @cache[name]
        @search_paths.unshift(Registry.yardoc_file)

        # Try to load it from in memory cache
        log.debug "Searching for #{name} in memory"
        obj = try_load_object(name, nil)
        return obj if obj

        log.debug "Searching for #{name} in search paths"
        @search_paths.each do |path|
          next unless File.exist?(path)
          log.debug "Searching for #{name} in #{path}..."
          Registry.load(path)
          obj = try_load_object(name, path)
          return obj if obj
        end
        nil
      end

      private

      # Tries to load the object with name. If successful, caches the object
      # with the cache_path
      #
      # @param [String] name the object path
      # @param [String] cache_path the location of the yardoc
      #   db containing the object to cache for future lookups.
      #   No caching is done if this is nil.
      # @return [void]
      def try_load_object(name, cache_path)
        obj = Registry.at(name)
        cache_object(name, cache_path) if obj && cache_path
        obj
      end

      # Loads {CACHE_FILE}
      # @return [void]
      def load_cache
        return unless File.file?(CACHE_FILE)
        File.readlines(CACHE_FILE).each do |line|
          line = line.strip.split(/\s+/)
          @cache[line[0]] = line[1]
        end
      end

      # Adds all RubyGems yardoc files to search paths
      # @return [void]
      def add_gem_paths
        require 'rubygems'
        gem_paths = []
        YARD::GemIndex.each do |spec|
          yfile = Registry.yardoc_file_for_gem(spec.name)
          next if yfile.nil?

          if spec.name =~ /^yard-doc-/
            gem_paths.unshift(yfile)
          else
            gem_paths.push(yfile)
          end
        end
        @search_paths += gem_paths
      rescue LoadError
        nil # noop
      end

      # Adds paths in {SEARCH_PATHS_FILE}
      # @since 0.5.1
      def add_default_paths
        @search_paths.concat(DEFAULT_SEARCH_PATHS)
        return unless File.file?(SEARCH_PATHS_FILE)
        paths = File.readlines(SEARCH_PATHS_FILE).map(&:strip)
        @search_paths.concat(paths)
      end

      # Parses commandline options.
      # @param [Array] args each tokenized argument
      def optparse(*args)
        opts = OptionParser.new
        opts.banner = "Usage: yri [options] "
        opts.separator "Example: yri String#gsub"
        opts.separator ""
        opts.separator "General Options:"

        opts.on('-b', '--db FILE', 'Use a specified .yardoc db to search in') do |yfile|
          @search_paths.unshift(yfile)
        end

        opts.on('-T', '--no-pager', 'No pager') do
          @serializer = YARD::Serializers::StdoutSerializer.new
        end

        opts.on('-p PAGER', '--pager') do |pager|
          @serializer = YARD::Serializers::ProcessSerializer.new(pager)
        end

        common_options(opts)
        parse_options(opts, args)
        @name = args.first
      end
    end
  end
end
yard-0.9.37/lib/yard/code_objects/000077500000000000000000000000001466601756300167175ustar00rootroot00000000000000yard-0.9.37/lib/yard/code_objects/base.rb000066400000000000000000000556751466601756300202000ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CodeObjects
    # A list of code objects. This array acts like a set (no unique items)
    # but also disallows any {Proxy} objects from being added.
    class CodeObjectList < Array
      # Creates a new object list associated with a namespace
      #
      # @param [NamespaceObject] owner the namespace the list should be associated with
      # @return [CodeObjectList]
      def initialize(owner = Registry.root)
        @owner = owner
      end

      # Adds a new value to the list
      #
      # @param [Base] value a code object to add
      # @return [CodeObjectList] self
      def push(value)
        value = Proxy.new(@owner, value) if value.is_a?(String) || value.is_a?(Symbol)
        if value.is_a?(CodeObjects::Base) || value.is_a?(Proxy)
          super(value) unless include?(value)
        else
          raise ArgumentError, "#{value.class} is not a valid CodeObject"
        end
        self
      end
      alias << push
    end

    extend NamespaceMapper

    # Namespace separator
    NSEP = '::'

    # Regex-quoted namespace separator
    NSEPQ = NSEP

    # Instance method separator
    ISEP = '#'

    # Regex-quoted instance method separator
    ISEPQ = ISEP

    # Class method separator
    CSEP = '.'

    # Regex-quoted class method separator
    CSEPQ = Regexp.quote CSEP

    # Regular expression to match constant name
    CONSTANTMATCH = /[A-Z]\w*/

    # Regular expression to match the beginning of a constant
    CONSTANTSTART = /^[A-Z]/

    # Regular expression to match namespaces (const A or complex path A::B)
    NAMESPACEMATCH = /(?:(?:#{NSEPQ}\s*)?#{CONSTANTMATCH})+/

    # Regular expression to match a method name
    METHODNAMEMATCH = %r{[a-zA-Z_]\w*[!?=]?|[-+~]\@|<<|>>|=~|===?|![=~]?|<=>|[<>]=?|\*\*|[-/+%^&*~`|]|\[\]=?}

    # Regular expression to match a fully qualified method def (self.foo, Class.foo).
    METHODMATCH = /(?:(?:#{NAMESPACEMATCH}|[a-z]\w*)\s*(?:#{CSEPQ}|#{NSEPQ})\s*)?#{METHODNAMEMATCH}/

    # All builtin Ruby exception classes for inheritance tree.
    BUILTIN_EXCEPTIONS = ["ArgumentError", "ClosedQueueError", "EncodingError",
      "EOFError", "Exception", "FiberError", "FloatDomainError", "IndexError",
      "Interrupt", "IOError", "KeyError", "LoadError", "LocalJumpError",
      "NameError", "NoMemoryError", "NoMethodError", "NotImplementedError",
      "RangeError", "RegexpError", "RuntimeError", "ScriptError", "SecurityError",
      "SignalException", "StandardError", "StopIteration", "SyntaxError",
      "SystemCallError", "SystemExit", "SystemStackError", "ThreadError",
      "TypeError", "UncaughtThrowError", "ZeroDivisionError"]

    # All builtin Ruby classes for inheritance tree.
    # @note MatchingData is a 1.8.x legacy class
    BUILTIN_CLASSES = ["Array", "Bignum", "Binding", "Class", "Complex",
      "ConditionVariable", "Data", "Dir", "Encoding", "Enumerator", "FalseClass",
      "Fiber", "File", "Fixnum", "Float", "Hash", "IO", "Integer", "MatchData",
      "Method", "Module", "NilClass", "Numeric", "Object", "Proc", "Queue",
      "Random", "Range", "Rational", "Regexp", "RubyVM", "SizedQueue", "String",
      "Struct", "Symbol", "Thread", "ThreadGroup", "Time", "TracePoint",
      "TrueClass", "UnboundMethod"] + BUILTIN_EXCEPTIONS

    # All builtin Ruby modules for mixin handling.
    BUILTIN_MODULES = ["Comparable", "Enumerable", "Errno", "FileTest", "GC",
      "Kernel", "Marshal", "Math", "ObjectSpace", "Precision", "Process", "Signal"]

    # All builtin Ruby classes and modules.
    BUILTIN_ALL = BUILTIN_CLASSES + BUILTIN_MODULES

    # Hash of {BUILTIN_EXCEPTIONS} as keys and true as value (for O(1) lookups)
    BUILTIN_EXCEPTIONS_HASH = BUILTIN_EXCEPTIONS.inject({}) {|h, n| h.update(n => true) }

    # +Base+ is the superclass of all code objects recognized by YARD. A code
    # object is any entity in the Ruby language (class, method, module). A
    # DSL might subclass +Base+ to create a new custom object representing
    # a new entity type.
    #
    # == Registry Integration
    # Any created object associated with a namespace is immediately registered
    # with the registry. This allows the Registry to act as an identity map
    # to ensure that no object is represented by more than one Ruby object
    # in memory. A unique {#path} is essential for this identity map to work
    # correctly.
    #
    # == Custom Attributes
    # Code objects allow arbitrary custom attributes to be set using the
    # {#[]=} assignment method.
    #
    # == Namespaces
    # There is a special type of object called a "namespace". These are subclasses
    # of the {NamespaceObject} and represent Ruby entities that can have
    # objects defined within them. Classically these are modules and classes,
    # though a DSL might create a custom {NamespaceObject} to describe a
    # specific set of objects.
    #
    # == Separators
    # Custom classes with different separator tokens should define their own
    # separators using the {NamespaceMapper.register_separator} method. The
    # standard Ruby separators have already been defined ('::', '#', '.', etc).
    #
    # @abstract This class should not be used directly. Instead, create a
    #   subclass that implements {#path}, {#sep} or {#type}. You might also
    #   need to register custom separators if {#sep} uses alternate separator
    #   tokens.
    # @see Registry
    # @see #path
    # @see #[]=
    # @see NamespaceObject
    # @see NamespaceMapper.register_separator
    class Base
      # The files the object was defined in. To add a file, use {#add_file}.
      # @return [Array] a list of files
      # @see #add_file
      attr_reader :files

      # The namespace the object is defined in. If the object is in the
      # top level namespace, this is {Registry.root}
      # @return [NamespaceObject] the namespace object
      attr_reader :namespace

      # The source code associated with the object
      # @return [String, nil] source, if present, or nil
      attr_reader :source

      # Language of the source code associated with the object. Defaults to
      # +:ruby+.
      #
      # @return [Symbol] the language type
      attr_accessor :source_type

      # The one line signature representing an object. For a method, this will
      # be of the form "def meth(arguments...)". This is usually the first
      # source line.
      #
      # @return [String] a line of source
      attr_accessor :signature

      # The non-localized documentation string associated with the object
      # @return [Docstring] the documentation string
      # @since 0.8.4
      attr_reader :base_docstring
      undef base_docstring
      def base_docstring; @docstring end

      # Marks whether or not the method is conditionally defined at runtime
      # @return [Boolean] true if the method is conditionally defined at runtime
      attr_accessor :dynamic

      # @return [String] the group this object is associated with
      # @since 0.6.0
      attr_accessor :group

      # Is the object defined conditionally at runtime?
      # @see #dynamic
      def dynamic?; @dynamic end

      # @return [Symbol] the visibility of an object (:public, :private, :protected)
      attr_accessor :visibility
      undef visibility=
      def visibility=(v) @visibility = v.to_sym end

      class << self
        # Allocates a new code object
        # @return [Base]
        # @see #initialize
        def new(namespace, name, *args, &block)
          raise ArgumentError, "invalid empty object name" if name.to_s.empty?
          if namespace.is_a?(ConstantObject)
            unless namespace.value =~ /\A#{NAMESPACEMATCH}\Z/
              raise Parser::UndocumentableError, "constant mapping"
            end

            namespace = Proxy.new(namespace.namespace, namespace.value)
          end

          if name.to_s[0, 2] == NSEP
            name = name.to_s[2..-1]
            namespace = Registry.root
          end

          if name =~ /(?:#{NSEPQ})([^:]+)$/
            return new(Proxy.new(namespace, $`), $1, *args, &block)
          end

          obj = super(namespace, name, *args)
          existing_obj = Registry.at(obj.path)
          obj = existing_obj if existing_obj && existing_obj.class == self
          yield(obj) if block_given?
          obj
        end

        # Compares the class with subclasses
        #
        # @param [Object] other the other object to compare classes with
        # @return [Boolean] true if other is a subclass of self
        def ===(other)
          other.is_a?(self)
        end
      end

      # Creates a new code object
      #
      # @example Create a method in the root namespace
      #   CodeObjects::Base.new(:root, '#method') # => #
      # @example Create class Z inside namespace X::Y
      #   CodeObjects::Base.new(P("X::Y"), :Z) # or
      #   CodeObjects::Base.new(Registry.root, "X::Y")
      # @param [NamespaceObject] namespace the namespace the object belongs in,
      #   {Registry.root} or :root should be provided if it is associated with
      #   the top level namespace.
      # @param [Symbol, String] name the name (or complex path) of the object.
      # @yield [self] a block to perform any extra initialization on the object
      # @yieldparam [Base] self the newly initialized code object
      # @return [Base] the newly created object
      def initialize(namespace, name, *)
        if namespace && namespace != :root &&
           !namespace.is_a?(NamespaceObject) && !namespace.is_a?(Proxy)
          raise ArgumentError, "Invalid namespace object: #{namespace}"
        end

        @files = []
        @current_file_has_comments = false
        @name = name.to_sym
        @source_type = :ruby
        @visibility = :public
        @tags = []
        @docstrings = {}
        @docstring = Docstring.new!('', [], self)
        @namespace = nil
        self.namespace = namespace
        yield(self) if block_given?
      end

      # Copies all data in this object to another code object, except for
      # uniquely identifying information (path, namespace, name, scope).
      #
      # @param [Base] other the object to copy data to
      # @return [Base] the other object
      # @since 0.8.0
      def copy_to(other)
        copyable_attributes.each do |ivar|
          ivar = "@#{ivar}"
          other.instance_variable_set(ivar, instance_variable_get(ivar))
        end
        other.docstring = @docstring.to_raw
        other
      end

      # The name of the object
      # @param [Boolean] prefix whether to show a prefix. Implement
      #   this in a subclass to define how the prefix is showed.
      # @return [Symbol] if prefix is false, the symbolized name
      # @return [String] if prefix is true, prefix + the name as a String.
      #   This must be implemented by the subclass.
      def name(prefix = false)
        prefix ? @name.to_s : (defined?(@name) && @name)
      end

      # Associates a file with a code object, optionally adding the line where it was defined.
      # By convention, '' should be used to associate code that comes form standard input.
      #
      # @param [String] file the filename ('' for standard input)
      # @param [Fixnum, nil] line the line number where the object lies in the file
      # @param [Boolean] has_comments whether or not the definition has comments associated. This
      #   will allow {#file} to return the definition where the comments were made instead
      #   of any empty definitions that might have been parsed before (module namespaces for instance).
      def add_file(file, line = nil, has_comments = false)
        raise(ArgumentError, "file cannot be nil or empty") if file.nil? || file == ''
        obj = [file.to_s, line]
        return if files.include?(obj)
        if has_comments && !@current_file_has_comments
          @current_file_has_comments = true
          @files.unshift(obj)
        else
          @files << obj # back of the line
        end
      end

      # Returns the filename the object was first parsed at, taking
      # definitions with docstrings first.
      #
      # @return [String] a filename
      # @return [nil] if there is no file associated with the object
      def file
        @files.first ? @files.first[0] : nil
      end

      # Returns the line the object was first parsed at (or nil)
      #
      # @return [Fixnum] the line where the object was first defined.
      # @return [nil] if there is no line associated with the object
      def line
        @files.first ? @files.first[1] : nil
      end

      # Tests if another object is equal to this, including a proxy
      # @param [Base, Proxy] other if other is a {Proxy}, tests if
      #   the paths are equal
      # @return [Boolean] whether or not the objects are considered the same
      def equal?(other)
        if other.is_a?(Base) || other.is_a?(Proxy)
          path == other.path
        else
          super
        end
      end
      alias == equal?
      alias eql? equal?

      # @return [Integer] the object's hash value (for equality checking)
      def hash; path.hash end

      # @return [nil] this object does not turn into an array
      def to_ary; nil end

      # Accesses a custom attribute on the object
      # @param [#to_s] key the name of the custom attribute
      # @return [Object, nil] the custom attribute or nil if not found.
      # @see #[]=
      def [](key)
        if respond_to?(key)
          send(key)
        elsif instance_variable_defined?("@#{key}")
          instance_variable_get("@#{key}")
        end
      end

      # Sets a custom attribute on the object
      # @param [#to_s] key the name of the custom attribute
      # @param [Object] value the value to associate
      # @return [void]
      # @see #[]
      def []=(key, value)
        if respond_to?("#{key}=")
          send("#{key}=", value)
        else
          instance_variable_set("@#{key}", value)
        end
      end

      # @overload dynamic_attr_name
      #   @return the value of attribute named by the method attribute name
      #   @raise [NoMethodError] if no method or custom attribute exists by
      #     the attribute name
      #   @see #[]
      # @overload dynamic_attr_name=(value)
      #   @param value a value to set
      #   @return +value+
      #   @see #[]=
      def method_missing(meth, *args, &block)
        if meth.to_s =~ /=$/
          self[meth.to_s[0..-2]] = args.first
        elsif instance_variable_get("@#{meth}")
          self[meth]
        else
          super
        end
      end

      # Attaches source code to a code object with an optional file location
      #
      # @param [#source, String] statement
      #   the +Parser::Statement+ holding the source code or the raw source
      #   as a +String+ for the definition of the code object only (not the block)
      def source=(statement)
        if statement.respond_to?(:source)
          @source = format_source(statement.source.strip)
        else
          @source = format_source(statement.to_s)
        end

        if statement.respond_to?(:signature)
          self.signature = statement.signature
        end
      end

      # The documentation string associated with the object
      #
      # @param [String, I18n::Locale] locale (I18n::Locale.default)
      #   the locale of the documentation string.
      # @return [Docstring] the documentation string
      def docstring(locale = I18n::Locale.default)
        if locale.nil?
          @docstring.resolve_reference
          return @docstring
        end

        if locale.is_a?(String)
          locale_name = locale
          locale = nil
        else
          locale_name = locale.name
        end
        @docstrings[locale_name] ||=
          translate_docstring(locale || Registry.locale(locale_name))
      end

      # Attaches a docstring to a code object by parsing the comments attached to the statement
      # and filling the {#tags} and {#docstring} methods with the parsed information.
      #
      # @param [String, Array, Docstring] comments
      #   the comments attached to the code object to be parsed
      #   into a docstring and meta tags.
      def docstring=(comments)
        @docstrings.clear
        @docstring = Docstring === comments ?
          comments : Docstring.new(comments, self)
      end

      # Default type is the lowercase class name without the "Object" suffix.
      # Override this method to provide a custom object type
      #
      # @return [Symbol] the type of code object this represents
      def type
        obj_name = self.class.name.split('::').last
        obj_name.gsub!(/Object$/, '')
        obj_name.downcase!
        obj_name.to_sym
      end

      # Represents the unique path of the object. The default implementation
      # joins the path of {#namespace} with {#name} via the value of {#sep}.
      # Custom code objects should ensure that the path is unique to the code
      # object by either overriding {#sep} or this method.
      #
      # @example The path of an instance method
      #   MethodObject.new(P("A::B"), :c).path # => "A::B#c"
      # @return [String] the unique path of the object
      # @see #sep
      def path
        @path ||= if parent && !parent.root?
                    [parent.path, name.to_s].join(sep)
                  else
                    name.to_s
                  end
      end
      alias to_s path

      # @note
      #   Override this method if your object has a special title that does
      #   not match the {#path} attribute value. This title will be used
      #   when linking or displaying the object.
      # @return [String] the display title for an object
      # @see 0.8.4
      def title
        path
      end

      # @param [Base, String] other another code object (or object path)
      # @return [String] the shortest relative path from this object to +other+
      # @since 0.5.3
      def relative_path(other)
        other = Registry.at(other) if String === other && Registry.at(other)
        same_parent = false
        if other.respond_to?(:path)
          same_parent = other.parent == parent
          other = other.path
        end
        return other unless namespace
        common = [path, other].join(" ").match(/^(\S*)\S*(?: \1\S*)*$/)[1]
        common = path unless common =~ /(\.|::|#)$/
        common = common.sub(/(\.|::|#)[^:#\.]*?$/, '') if same_parent
        suffix = %w(. :).include?(common[-1, 1]) || other[common.size, 1] == '#' ?
          '' : '(::|\.)'
        result = other.sub(/^#{Regexp.quote common}#{suffix}/, '')
        result.empty? ? other : result
      end

      # Renders the object using the {Templates::Engine templating system}.
      #
      # @example Formats a class in plaintext
      #   puts P('MyClass').format
      # @example Formats a method in html with rdoc markup
      #   puts P('MyClass#meth').format(:format => :html, :markup => :rdoc)
      # @param [Hash] options a set of options to pass to the template
      # @option options [Symbol] :format (:text) :html, :text or another output format
      # @option options [Symbol] :template (:default) a specific template to use
      # @option options [Symbol] :markup (nil) the markup type (:rdoc, :markdown, :textile)
      # @option options [Serializers::Base] :serializer (nil) see Serializers
      # @return [String] the rendered template
      # @see Templates::Engine#render
      def format(options = {})
        options = options.merge(:object => self)
        options = options.merge(:type => type) unless options[:type]
        Templates::Engine.render(options)
      end

      # Inspects the object, returning the type and path
      # @return [String] a string describing the object
      def inspect
        "#"
      end

      # Sets the namespace the object is defined in.
      #
      # @param [NamespaceObject, :root, nil] obj the new namespace (:root
      #   for {Registry.root}). If obj is nil, the object is unregistered
      #   from the Registry.
      def namespace=(obj)
        if @namespace
          @namespace.children.delete(self)
          Registry.delete(self)
        end

        @namespace = (obj == :root ? Registry.root : obj)

        if @namespace
          reg_obj = Registry.at(path)
          return if reg_obj && reg_obj.class == self.class

          unless @namespace.is_a?(Proxy)
            # remove prior objects from obj's children that match this one
            @namespace.children.delete_if {|o| o.path == path }
            @namespace.children << self
          end
          Registry.register(self)
        end
      end

      alias parent namespace
      alias parent= namespace=

      # Gets a tag from the {#docstring}
      # @see Docstring#tag
      def tag(name); docstring.tag(name) end

      # Gets a list of tags from the {#docstring}
      # @see Docstring#tags
      def tags(name = nil); docstring.tags(name) end

      # Tests if the {#docstring} has a tag
      # @see Docstring#has_tag?
      def has_tag?(name); docstring.has_tag?(name) end

      # Add tags to the {#docstring}
      # @see Docstring#add_tag
      # @since 0.8.4
      def add_tag(*tags)
        @docstrings.clear
        @docstring.add_tag(*tags)
      end

      # @return whether or not this object is a RootObject
      def root?; false end

      # Override this method with a custom component separator. For instance,
      # {MethodObject} implements sep as '#' or '.' (depending on if the
      # method is instance or class respectively). {#path} depends on this
      # value to generate the full path in the form: namespace.path + sep + name
      #
      # @return [String] the component that separates the namespace path
      #   and the name (default is {NSEP})
      def sep; NSEP end

      protected

      # Override this method if your code object subclass does not allow
      # copying of certain attributes.
      #
      # @return [Array] the list of instance variable names (without
      #   "@" prefix) that should be copied when {#copy_to} is called
      # @see #copy_to
      # @since 0.8.0
      def copyable_attributes
        vars = instance_variables.map {|ivar| ivar.to_s[1..-1] }
        vars -= %w(docstring docstrings namespace name path)
        vars
      end

      private

      # Formats source code by removing leading indentation
      #
      # @param [String] source the source code to format
      # @return [String] formatted source
      def format_source(source)
        source = source.chomp
        last = source.split(/\r?\n/).last
        indent = last ? last[/^([ \t]*)/, 1].length : 0
        source.gsub(/^[ \t]{#{indent}}/, '')
      end

      def translate_docstring(locale)
        @docstring.resolve_reference
        return @docstring if locale.nil?

        text = I18n::Text.new(@docstring)
        localized_text = text.translate(locale)
        docstring = Docstring.new(localized_text, self)
        @docstring.tags.each do |tag|
          if tag.is_a?(Tags::Tag)
            localized_tag = tag.clone
            localized_tag.text = I18n::Text.new(tag.text).translate(locale)
            docstring.add_tag(localized_tag)
          else
            docstring.add_tag(tag)
          end
        end
        docstring
      end
    end
  end
end
yard-0.9.37/lib/yard/code_objects/class_object.rb000066400000000000000000000120231466601756300216750ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  register_separator NSEP, :class

  # A ClassObject represents a Ruby class in source code. It is a {ModuleObject}
  # with extra inheritance semantics through the superclass.
  class ClassObject < NamespaceObject
    # The {ClassObject} that this class object inherits from in Ruby source.
    # @return [ClassObject] a class object that is the superclass of this one
    attr_reader :superclass

    # Creates a new class object in +namespace+ with +name+
    #
    # @see Base.new
    def initialize(namespace, name, *args, &block)
      super

      if is_exception?
        self.superclass ||= "::Exception" unless P(namespace, name) == P(:Exception)
      else
        case P(namespace, name).path
        when "BasicObject"
          nil
        when "Object"
          self.superclass ||= "::BasicObject"
        else
          self.superclass ||= "::Object"
        end
      end
    end

    # Whether or not the class is a Ruby Exception
    #
    # @return [Boolean] whether the object represents a Ruby exception
    def is_exception?
      inheritance_tree.reverse.any? {|o| BUILTIN_EXCEPTIONS_HASH.key? o.path }
    end

    # Returns the inheritance tree of the object including self.
    #
    # @param [Boolean] include_mods whether or not to include mixins in the
    #   inheritance tree.
    # @return [Array] the list of code objects that make up
    #   the inheritance tree.
    def inheritance_tree(include_mods = false)
      list = (include_mods ? mixins(:instance, :class) : [])
      if superclass.is_a?(Proxy) || superclass.respond_to?(:inheritance_tree)
        list += [superclass] unless superclass == P(:Object) || superclass == P(:BasicObject)
      end
      [self] + list.map do |m|
        next m if m == self
        next m unless m.respond_to?(:inheritance_tree)
        m.inheritance_tree(include_mods)
      end.flatten.uniq
    end

    # Returns the list of methods matching the options hash. Returns
    # all methods if hash is empty.
    #
    # @param [Hash] opts the options hash to match
    # @option opts [Boolean] :inherited (true) whether inherited methods should be
    #   included in the list
    # @option opts [Boolean] :included (true) whether mixed in methods should be
    #   included in the list
    # @return [Array] the list of methods that matched
    def meths(opts = {})
      opts = SymbolHash[:inherited => true].update(opts)
      list = super(opts)
      list += inherited_meths(opts).reject do |o|
        next(false) if opts[:all]
        list.find {|o2| o2.name == o.name && o2.scope == o.scope }
      end if opts[:inherited]
      list
    end

    # Returns only the methods that were inherited.
    #
    # @return [Array] the list of inherited method objects
    def inherited_meths(opts = {})
      inheritance_tree[1..-1].inject([]) do |list, superclass|
        if superclass.is_a?(Proxy)
          list
        else
          list += superclass.meths(opts).reject do |o|
            next(false) if opts[:all]
            child(:name => o.name, :scope => o.scope) ||
              list.find {|o2| o2.name == o.name && o2.scope == o.scope }
          end
        end
      end
    end

    # Returns the list of constants matching the options hash.
    #
    # @param [Hash] opts the options hash to match
    # @option opts [Boolean] :inherited (true) whether inherited constant should be
    #   included in the list
    # @option opts [Boolean] :included (true) whether mixed in constant should be
    #   included in the list
    # @return [Array] the list of constant that matched
    def constants(opts = {})
      opts = SymbolHash[:inherited => true].update(opts)
      super(opts) + (opts[:inherited] ? inherited_constants : [])
    end

    # Returns only the constants that were inherited.
    #
    # @return [Array] the list of inherited constant objects
    def inherited_constants
      inheritance_tree[1..-1].inject([]) do |list, superclass|
        if superclass.is_a?(Proxy)
          list
        else
          list += superclass.constants.reject do |o|
            child(:name => o.name) || list.find {|o2| o2.name == o.name }
          end
        end
      end
    end

    # Sets the superclass of the object
    #
    # @param [Base, Proxy, String, Symbol, nil] object the superclass value
    # @return [void]
    def superclass=(object)
      case object
      when Base, Proxy, NilClass
        @superclass = object
      when String, Symbol
        @superclass = Proxy.new(namespace, object)
      else
        raise ArgumentError, "superclass must be CodeObject, Proxy, String or Symbol"
      end

      if name == @superclass.name && namespace != YARD::Registry.root && !object.is_a?(Base)
        @superclass = Proxy.new(namespace.namespace, object)
      end

      if @superclass == self
        msg = "superclass #{@superclass.inspect} cannot be the same as the declared class #{inspect}"
        @superclass = P("::Object")
        raise ArgumentError, msg
      end
    end
  end
end
yard-0.9.37/lib/yard/code_objects/class_variable_object.rb000066400000000000000000000005151466601756300235450ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  register_separator NSEP, :class_variable

  # Represents a class variable inside a namespace. The path is expressed
  # in the form "A::B::@@classvariable"
  class ClassVariableObject < Base
    # @return [String] the class variable's value
    attr_accessor :value
  end
end
yard-0.9.37/lib/yard/code_objects/constant_object.rb000066400000000000000000000007321466601756300224250ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  register_separator NSEP, :constant

  # A +ConstantObject+ represents a Ruby constant (not a module or class).
  # To access the constant's (source code) value, use {#value}.
  class ConstantObject < Base
    # The source code representing the constant's value
    # @return [String] the value the constant is set to
    attr_reader :value

    def value=(value)
      @value = format_source(value)
    end
  end
end
yard-0.9.37/lib/yard/code_objects/extended_method_object.rb000066400000000000000000000014411466601756300237320ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  # Represents an instance method of a module that was mixed into the class
  # scope of another namespace.
  #
  # @see MethodObject
  class ExtendedMethodObject
    instance_methods.each {|m| undef_method(m) unless m =~ /^__/ || m.to_sym == :object_id }

    # @return [Symbol] always +:class+
    def scope; :class end

    # Sets up a delegate for {MethodObject} obj.
    #
    # @param [MethodObject] obj the instance method to treat as a mixed in
    #   class method on another namespace.
    def initialize(obj) @del = obj end

    # Sends all methods to the {MethodObject} assigned in {#initialize}
    # @see #initialize
    # @see MethodObject
    def method_missing(sym, *args, &block) @del.__send__(sym, *args, &block) end
  end
end
yard-0.9.37/lib/yard/code_objects/extra_file_object.rb000066400000000000000000000067311466601756300227230ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  # An ExtraFileObject represents an extra documentation file (README or other
  # file). It is not strictly a CodeObject (does not inherit from `Base`) although
  # it implements `path`, `name` and `type`, and therefore should be structurally
  # compatible with most CodeObject interfaces.
  class ExtraFileObject
    attr_accessor :filename
    attr_writer :attributes
    attr_accessor :name
    # @since 0.8.3
    attr_reader :locale

    # Creates a new extra file object.
    # @param [String] filename the location on disk of the file
    # @param [String] contents the file contents. If not set, the contents
    #   will be read from disk using the +filename+.
    def initialize(filename, contents = nil)
      self.filename = filename
      self.name = File.basename(filename).gsub(/\.[^.]+$/, '')
      self.attributes = SymbolHash.new(false)
      @original_contents = contents
      @parsed = false
      @locale = nil
      ensure_parsed
    end

    alias path name

    def attributes
      ensure_parsed
      @attributes
    end

    def title
      attributes[:title] || name
    end

    def contents
      ensure_parsed
      @contents
    end

    def contents=(contents)
      @original_contents = contents
      @parsed = false
    end

    # @param [String] locale the locale name to be translated.
    # @return [void]
    # @since 0.8.3
    def locale=(locale)
      @locale = locale
      @parsed = false
    end

    def inspect
      "#"
    end
    alias to_s inspect

    def type; :extra_file end

    def ==(other)
      return false unless self.class === other
      other.filename == filename
    end
    alias eql? ==
    alias equal? ==
    def hash; filename.hash end

    private

    def ensure_parsed
      return if @parsed
      @parsed = true
      @contents = parse_contents(@original_contents || File.read(@filename))
    end

    # @param [String] data the file contents
    def parse_contents(data)
      retried = false
      cut_index = 0
      data = translate(data)
      data = data.split("\n")
      data.each_with_index do |line, index|
        case line
        when /^#!(\S+)\s*$/
          if index == 0
            attributes[:markup] = $1
          else
            cut_index = index
            break
          end
        when /^\s*#\s*@(\S+)\s*(.+?)\s*$/
          attributes[$1] = $2
        when /^\s*\s*$/
          # Ignore HTML comments
        else
          cut_index = index
          break
        end
      end
      data = data[cut_index..-1] if cut_index > 0
      contents = data.join("\n")

      if contents.respond_to?(:force_encoding) && attributes[:encoding]
        begin
          contents.force_encoding(attributes[:encoding])
        rescue ArgumentError
          log.warn "Invalid encoding `#{attributes[:encoding]}' in #{filename}"
        end
      end
      contents
    rescue ArgumentError => e
      raise unless e.message =~ /invalid byte sequence/

      if retried
        # This should never happen.
        log.warn "Could not read #{filename}, #{e.message}. You probably want to set `--charset`."
        return ''
      else
        data.force_encoding('binary') if data.respond_to?(:force_encoding)
        retried = true
        retry
      end
    end

    def translate(data)
      text = YARD::I18n::Text.new(data, :have_header => true)
      text.translate(YARD::Registry.locale(locale))
    end
  end
end
yard-0.9.37/lib/yard/code_objects/macro_object.rb000066400000000000000000000165021466601756300216770ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module CodeObjects
    # A MacroObject represents a docstring defined through +@!macro NAME+ and can be
    # reused by specifying the tag +@!macro NAME+. You can also provide the
    # +attached+ type flag to the macro definition to have it attached to the
    # specific DSL method so it will be implicitly reused.
    #
    # Macros are fully described in the {file:docs/Tags.md#macro Tags Overview}
    # document.
    #
    # @example Creating a basic named macro
    #   # @!macro prop
    #   #   @!method $1(${3-})
    #   #   @return [$2] the value of the $0
    #   property :foo, String, :a, :b
    #
    #   # @!macro prop
    #   property :bar, Numeric, :value
    #
    # @example Creating a macro that is attached to the method call
    #   # @!macro [attach] prop2
    #   #   @!method $1(value)
    #   property :foo
    #
    #   # Extra data added to docstring
    #   property :bar
    class MacroObject < Base
      MACRO_MATCH = /(\\)?\$(?:\{(-?\d+|\*)(-)?(-?\d+)?\}|(-?\d+|\*))/

      class << self
        # Creates a new macro and fills in the relevant properties.
        # @param [String] macro_name the name of the macro, must be unique.
        # @param [String] data the data the macro should expand when re-used
        # @param [CodeObjects::Base] method_object an object to attach this
        #   macro to. If supplied, {#attached?} will be true
        # @return [MacroObject] the newly created object
        def create(macro_name, data, method_object = nil)
          obj = new(:root, macro_name)
          obj.macro_data = data
          obj.method_object = method_object
          obj
        end

        # Finds a macro using +macro_name+
        # @param [#to_s] macro_name the name of the macro
        # @return [MacroObject] if a macro is found
        # @return [nil] if there is no registered macro by that name
        def find(macro_name)
          Registry.at('.macro.' + macro_name.to_s)
        end

        # Parses a given docstring and determines if the macro is "new" or
        # not. If the macro has $variable names or if it has a @!macro tag
        # with the [new] or [attached] flag, it is considered new.
        #
        # If a new macro is found, the macro is created and registered. Otherwise
        # the macro name is searched and returned. If a macro is not found,
        # nil is returned.
        #
        # @param [#to_s] macro_name the name of the macro
        # @param [CodeObjects::Base] method_object an optional method to attach
        #   the macro to. Only used if the macro is being created, otherwise
        #   this argument is ignored.
        # @return [MacroObject] the newly created or existing macro, depending
        #   on whether the @!macro tag was a new tag or not.
        # @return [nil] if the +data+ has no macro tag or if the macro is
        #   not new and no macro by the macro name is found.
        def find_or_create(macro_name, data, method_object = nil)
          find(name) || create(macro_name, data, method_object)
        end
        alias create_docstring find_or_create

        # Expands +macro_data+ using the interpolation parameters.
        #
        # Interpolation rules:
        # * $0, $1, $2, ... = the Nth parameter in +call_params+
        # * $* = the full statement source (excluding block)
        # * Also supports $!{N-M} ranges, as well as negative indexes on N or M
        # * Use \$ to escape the variable name in a macro.
        #
        # @!macro [new] macro.expand
        #   @param [Array] call_params the method name and parameters
        #     to the method call. These arguments will fill \$0-N
        #   @param [String] full_source the full source line (excluding block)
        #     interpolated as \$*
        #   @param [String] block_source Currently unused. Will support
        #     interpolating the block data as a variable.
        #   @return [String] the expanded macro data
        # @param [String] macro_data the macro data to expand (taken from {#macro_data})
        def expand(macro_data, call_params = [], full_source = '', block_source = '') # rubocop:disable Lint/UnusedMethodArgument
          macro_data = macro_data.all if macro_data.is_a?(Docstring)
          macro_data.gsub(MACRO_MATCH) do
            escape = $1
            first = $2 || $5
            last = $4
            rng = $3 ? true : false
            next $&[1..-1] if escape
            if first == '*'
              last ? $& : full_source
            else
              first_i = first.to_i
              last_i = (last ? last.to_i : call_params.size)
              last_i = first_i unless rng
              params = call_params[first_i..last_i]
              params ? params.join(", ") : ''
            end
          end
        end

        # Applies a macro on a docstring by creating any macro data inside of
        # the docstring first. Equivalent to calling {find_or_create} and {apply_macro}
        # on the new macro object.
        #
        # @param [Docstring] docstring the docstring to create a macro out of
        # @!macro macro.expand
        # @see find_or_create
        def apply(docstring, call_params = [], full_source = '', block_source = '', _method_object = nil) # rubocop:disable Lint/UnusedMethodArgument
          docstring = docstring.all if Docstring === docstring
          parser = Docstring.parser
          handler = OpenStruct.new
          handler.call_params = call_params[1..-1]
          handler.caller_method = call_params.first
          handler.statement = OpenStruct.new(:source => full_source)
          parser.parse(docstring, nil, handler).to_docstring.to_raw
        end

        # Applies a macro to a docstring, interpolating the macro's data on the
        # docstring and appending any extra local docstring data that was in
        # the original +docstring+ object.
        #
        # @param [MacroObject] macro the macro object
        # @!macro macro.expand
        def apply_macro(macro, docstring, call_params = [], full_source = '', block_source = '') # rubocop:disable Lint/UnusedMethodArgument
          apply(docstring, call_params, full_source, block_source)
        end
      end

      # @return [String] the macro data stored on the object
      attr_accessor :macro_data

      # @return [CodeObjects::Base] the method object that this macro is
      #   attached to.
      attr_accessor :method_object

      # @return [Boolean] whether this macro is attached to a method
      def attached?; method_object ? true : false end

      # Overrides {Base#path} so the macro path is ".macro.MACRONAME"
      def path; '.macro.' + name.to_s end

      # Overrides the separator to be '.'
      def sep; '.' end

      # Expands the macro using
      # @param [Array] call_params a list of tokens that are passed
      #   to the method call
      # @param [String] full_source the full method call (not including the block)
      # @param [String] block_source the source passed in the block of the method
      #   call, if there is a block.
      # @example Expanding a Macro
      #   macro.expand(%w(property foo bar), 'property :foo, :bar', '') #=>
      #     "...macro data interpolating this line of code..."
      # @see expand
      def expand(call_params = [], full_source = '', block_source = '')
        self.class.expand(macro_data, call_params, full_source, block_source)
      end
    end
  end
end
yard-0.9.37/lib/yard/code_objects/method_object.rb000066400000000000000000000137711466601756300220630ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  register_separator CSEP, :method
  register_separator ISEP, :method

  # Represents a Ruby method in source
  class MethodObject < Base
    # The scope of the method (+:class+ or +:instance+)
    #
    # @return [Symbol] the scope
    attr_reader :scope

    # Whether the object is explicitly defined in source or whether it was
    # inferred by a handler. For instance, attribute methods are generally
    # inferred and therefore not explicitly defined in source.
    #
    # @return [Boolean] whether the object is explicitly defined in source.
    attr_accessor :explicit

    # Returns the list of parameters parsed out of the method signature
    # with their default values.
    #
    # @return [Array] a list of parameter names followed
    #   by their default values (or nil)
    attr_accessor :parameters

    # Creates a new method object in +namespace+ with +name+ and an instance
    # or class +scope+
    #
    # If scope is +:module+, this object is instantiated as a public
    # method in +:class+ scope, but also creates a new (empty) method
    # as a private +:instance+ method on the same class or module.
    #
    # @param [NamespaceObject] namespace the namespace
    # @param [String, Symbol] name the method name
    # @param [Symbol] scope +:instance+, +:class+, or +:module+
    def initialize(namespace, name, scope = :instance, &block)
      @module_function = false
      @scope = nil

      # handle module function
      if scope == :module
        other = self.class.new(namespace, name, &block)
        other.visibility = :private
        scope = :class
        @module_function = true
      end

      @visibility = :public
      self.scope = scope
      self.parameters = []

      super
    end

    # Changes the scope of an object from :instance or :class
    # @param [Symbol] v the new scope
    def scope=(v)
      reregister = @scope ? true : false

      # handle module function
      if v == :module
        other = self.class.new(namespace, name)
        other.visibility = :private
        @visibility = :public
        @module_function = true
        @path = nil
      end

      YARD::Registry.delete(self)
      @path = nil
      @scope = v.to_sym
      @scope = :class if @scope == :module
      YARD::Registry.register(self) if reregister
    end

    # @return whether or not the method is the #initialize constructor method
    def constructor?
      name == :initialize && scope == :instance && namespace.is_a?(ClassObject)
    end

    # @return [Boolean] whether or not this method was created as a module
    #   function
    # @since 0.8.0
    def module_function?
      @module_function
    end

    # Returns the read/writer info for the attribute if it is one
    # @return [SymbolHash] if there is information about the attribute
    # @return [nil] if the method is not an attribute
    # @since 0.5.3
    def attr_info
      return nil unless namespace.is_a?(NamespaceObject)
      namespace.attributes[scope][name.to_s.gsub(/=$/, '')]
    end

    # @return [Boolean] whether the method is a writer attribute
    # @since 0.5.3
    def writer?
      info = attr_info
      info && info[:write] == self ? true : false
    end

    # @return [Boolean] whether the method is a reader attribute
    # @since 0.5.3
    def reader?
      info = attr_info
      info && info[:read] == self ? true : false
    end

    # Tests if the object is defined as an attribute in the namespace
    # @return [Boolean] whether the object is an attribute
    def is_attribute?
      info = attr_info
      if info
        read_or_write = name.to_s =~ /=$/ ? :write : :read
        info[read_or_write] ? true : false
      else
        false
      end
    end

    # Tests if the object is defined as an alias of another method
    # @return [Boolean] whether the object is an alias
    def is_alias?
      return false unless namespace.is_a?(NamespaceObject)
      namespace.aliases.key? self
    end

    # Tests boolean {#explicit} value.
    #
    # @return [Boolean] whether the method is explicitly defined in source
    def is_explicit?
      explicit ? true : false
    end

    # @return [MethodObject] the object that this method overrides
    # @return [nil] if it does not override a method
    # @since 0.6.0
    def overridden_method
      return nil if namespace.is_a?(Proxy)
      meths = namespace.meths(:all => true)
      meths.find {|m| m.path != path && m.name == name && m.scope == scope }
    end

    # Returns all alias names of the object
    # @return [Array] the alias names
    def aliases
      list = []
      return list unless namespace.is_a?(NamespaceObject)
      namespace.aliases.each do |o, aname|
        list << o if aname == name && o.scope == scope
      end
      list
    end

    # Override path handling for instance methods in the root namespace
    # (they should still have a separator as a prefix).
    # @return [String] the path of a method
    def path
      @path ||= !namespace || namespace.path == "" ? sep + super : super
    end

    # Returns the name of the object.
    #
    # @example The name of an instance method (with prefix)
    #   an_instance_method.name(true) # => "#mymethod"
    # @example The name of a class method (with prefix)
    #   a_class_method.name(true) # => "mymethod"
    # @param [Boolean] prefix whether or not to show the prefix
    # @return [String] returns {#sep} + +name+ for an instance method if
    #   prefix is true
    # @return [Symbol] the name without {#sep} if prefix is set to false
    def name(prefix = false)
      prefix ? (sep == ISEP ? "#{sep}#{super}" : super.to_s) : super
    end

    # Override separator to differentiate between class and instance
    # methods.
    # @return [String] "#" for an instance method, "." for class
    def sep
      if scope == :class
        namespace && namespace != YARD::Registry.root ? CSEP : NSEP
      else
        ISEP
      end
    end

    protected

    def copyable_attributes
      super - %w(scope module_function)
    end
  end
end
yard-0.9.37/lib/yard/code_objects/module_object.rb000066400000000000000000000012721466601756300220610ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  register_separator NSEP, :module

  # Represents a Ruby module.
  class ModuleObject < NamespaceObject
    # Returns the inheritance tree of mixins.
    #
    # @param [Boolean] include_mods if true, will include mixed in
    #   modules (which is likely what is wanted).
    # @return [Array] a list of namespace objects
    def inheritance_tree(include_mods = false)
      return [self] unless include_mods
      [self] + mixins(:instance, :class).map do |m|
        next if m == self
        next m unless m.respond_to?(:inheritance_tree)
        m.inheritance_tree(true)
      end.compact.flatten.uniq
    end
  end
end
yard-0.9.37/lib/yard/code_objects/namespace_mapper.rb000066400000000000000000000104631466601756300225500ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CodeObjects
    # This module controls registration and accessing of namespace separators
    # for {Registry} lookup.
    #
    # @since 0.9.1
    module NamespaceMapper
      # @!group Registering a Separator for a Namespace

      # Registers a separator with an optional set of valid types that
      # must follow the separator lexically.
      #
      # Calls all callbacks defined by {NamespaceMapper.on_invalidate} after
      # the separator is registered.
      #
      # @param sep [String] the separator string for the namespace
      # @param valid_types [Array] a list of object types that
      #   must follow the separator. If the list is empty, any type can
      #   follow the separator.
      # @example Registering separators for a method object
      #   # Anything after a "#" denotes a method object
      #   register_separator "#", :method
      #   # Anything after a "." denotes a method object
      #   register_separator ".", :method
      # @see .on_invalidate
      def register_separator(sep, *valid_types)
        NamespaceMapper.invalidate

        valid_types.each do |t|
          NamespaceMapper.rev_map[t] ||= []
          NamespaceMapper.rev_map[t] << sep
        end

        NamespaceMapper.map[sep] ||= []
        NamespaceMapper.map[sep] += valid_types
      end

      # Unregisters a separator by a type.
      #
      # @param type [Symbol] the type to unregister
      # @see #register_separator
      def unregister_separator_by_type(type)
        seps = NamespaceMapper.rev_map[type]
        return unless seps
        
        seps.each {|s| NamespaceMapper.map.delete(s) }
        NamespaceMapper.rev_map.delete(type)
        NamespaceMapper.invalidate
      end

      # Clears the map of separators.
      #
      # @return [void]
      def clear_separators
        NamespaceMapper.invalidate
        NamespaceMapper.map = {}
        NamespaceMapper.rev_map = {}
      end

      # Gets or sets the default separator value to use when no
      # separator for the namespace can be determined.
      #
      # @param value [String, nil] the default separator, or nil to return the
      #   value
      # @example
      #   default_separator "::"
      def default_separator(value = nil)
        if value
          NamespaceMapper.invalidate
          NamespaceMapper.default_separator = Regexp.quote value
        else
          NamespaceMapper.default_separator
        end
      end

      # @!group Separator and Type Lookup Helpers

      # @return [Array] all of the registered separators
      def separators
        NamespaceMapper.map.keys
      end

      # @return [Regexp] the regexp match of all separators
      def separators_match
        NamespaceMapper.map_match
      end

      # @param sep [String] the separator to return types for
      # @return [Array] a list of types registered to a separator
      def types_for_separator(sep)
        NamespaceMapper.map[sep] || []
      end

      # @param type [String] the type to return separators for
      # @return [Array] a list of separators registered to a type
      def separators_for_type(type)
        NamespaceMapper.rev_map[type] || []
      end

      # Internal methods to act as a singleton registry
      class << self
        # @!group Invalidation callbacks

        # Adds a callback that triggers when a new separator is registered or
        # the cache is cleared by invalidation.
        def on_invalidate(&block)
          (@invalidation_callbacks ||= []).push(block)
        end

        # @!visibility private

        # @return [Hash] a mapping of types to separators
        def map
          @map ||= {}
        end

        # @return [Hash] a reverse mapping of separators to types
        def rev_map
          @rev_map ||= {}
        end

        # Invalidates all separators
        # @return [void]
        def invalidate
          @map_match = nil
          (@invalidation_callbacks || []).each(&:call)
        end

        # @return [Regexp] the full list of separators as a regexp match
        def map_match
          @map_match ||= map.keys.map {|k| Regexp.quote k }.join('|')
        end

        # @return [String] the default separator when no separator can begin
        #   determined.
        attr_accessor :default_separator
      end
    end
  end
end
yard-0.9.37/lib/yard/code_objects/namespace_object.rb000066400000000000000000000163551466601756300225400ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::CodeObjects
  register_separator NSEP, :namespace
  default_separator NSEP

  # A "namespace" is any object that can store other objects within itself.
  # The two main Ruby objects that can act as namespaces are modules
  # ({ModuleObject}) and classes ({ClassObject}).
  class NamespaceObject < Base
    # @return [Array] a list of ordered group names inside the namespace
    # @since 0.6.0
    attr_accessor :groups

    # The list of objects defined in this namespace
    # @return [Array] a list of objects
    attr_reader :children

    # A hash containing two keys, class and instance, each containing
    # the attribute name with a { :read, :write } hash for the read and
    # write objects respectively.
    #
    # @example The attributes of an object
    #   >> Registry.at('YARD::Docstring').attributes
    #   => {
    #         :class => { },
    #         :instance => {
    #           :ref_tags => {
    #             :read => #,
    #             :write => nil
    #           },
    #           :object => {
    #             :read => #,
    #             :write => #
    #            },
    #            ...
    #         }
    #       }
    # @return [Hash] a list of methods
    attr_reader :attributes

    # A hash containing two keys, :class and :instance, each containing
    # a hash of objects and their alias names.
    # @return [Hash] a list of methods
    attr_reader :aliases

    # Class mixins
    # @return [Array] a list of mixins
    attr_reader :class_mixins

    # Instance mixins
    # @return [Array] a list of mixins
    attr_reader :instance_mixins

    # Creates a new namespace object inside +namespace+ with +name+.
    # @see Base#initialize
    def initialize(namespace, name, *args, &block)
      @children = CodeObjectList.new(self)
      @class_mixins = CodeObjectList.new(self)
      @instance_mixins = CodeObjectList.new(self)
      @attributes = SymbolHash[:class => SymbolHash.new, :instance => SymbolHash.new]
      @aliases = {}
      @groups = []
      super
    end

    # Only the class attributes
    # @return [Hash] a list of method names and their read/write objects
    # @see #attributes
    def class_attributes
      attributes[:class]
    end

    # Only the instance attributes
    # @return [Hash] a list of method names and their read/write objects
    # @see #attributes
    def instance_attributes
      attributes[:instance]
    end

    # Looks for a child that matches the attributes specified by +opts+.
    #
    # @example Finds a child by name and scope
    #   namespace.child(:name => :to_s, :scope => :instance)
    #   # => #
    # @return [Base, nil] the first matched child object, or nil
    def child(opts = {})
      if !opts.is_a?(Hash)
        children.find {|o| o.name == opts.to_sym }
      else
        opts = SymbolHash[opts]
        children.find do |obj|
          opts.each do |meth, value|
            break false unless value.is_a?(Array) ? value.include?(obj[meth]) : obj[meth] == value
          end
        end
      end
    end

    # Returns all methods that match the attributes specified by +opts+. If
    # no options are provided, returns all methods.
    #
    # @example Finds all private and protected class methods
    #   namespace.meths(:visibility => [:private, :protected], :scope => :class)
    #   # => [#, #]
    # @option opts [Array, Symbol] :visibility ([:public, :private,
    #   :protected]) the visibility of the methods to list. Can be an array or
    #   single value.
    # @option opts [Array, Symbol] :scope ([:class, :instance]) the
    #   scope of the methods to list. Can be an array or single value.
    # @option opts [Boolean] :included (true) whether to include mixed in
    #   methods in the list.
    # @return [Array] a list of method objects
    def meths(opts = {})
      opts = SymbolHash[
        :visibility => [:public, :private, :protected],
        :scope => [:class, :instance],
        :included => true
      ].update(opts)

      opts[:visibility] = [opts[:visibility]].flatten
      opts[:scope] = [opts[:scope]].flatten

      ourmeths = children.select do |o|
        o.is_a?(MethodObject) &&
          opts[:visibility].include?(o.visibility) &&
          opts[:scope].include?(o.scope)
      end

      ourmeths + (opts[:included] ? included_meths(opts) : [])
    end

    # Returns methods included from any mixins that match the attributes
    # specified by +opts+. If no options are specified, returns all included
    # methods.
    #
    # @option opts [Array, Symbol] :visibility ([:public, :private,
    #   :protected]) the visibility of the methods to list. Can be an array or
    #   single value.
    # @option opts [Array, Symbol] :scope ([:class, :instance]) the
    #   scope of the methods to list. Can be an array or single value.
    # @option opts [Boolean] :included (true) whether to include mixed in
    #   methods in the list.
    # @see #meths
    def included_meths(opts = {})
      opts = SymbolHash[:scope => [:instance, :class]].update(opts)
      [opts[:scope]].flatten.map do |scope|
        mixins(scope).inject([]) do |list, mixin|
          next list if mixin.is_a?(Proxy)
          arr = mixin.meths(opts.merge(:scope => :instance)).reject do |o|
            next false if opts[:all]
            child(:name => o.name, :scope => scope) || list.find {|o2| o2.name == o.name }
          end
          arr.map! {|o| ExtendedMethodObject.new(o) } if scope == :class
          list + arr
        end
      end.flatten
    end

    # Returns all constants in the namespace
    #
    # @option opts [Boolean] :included (true) whether or not to include
    #   mixed in constants in list
    # @return [Array] a list of constant objects
    def constants(opts = {})
      opts = SymbolHash[:included => true].update(opts)
      consts = children.select {|o| o.is_a? ConstantObject }
      consts + (opts[:included] ? included_constants : [])
    end

    # Returns constants included from any mixins
    # @return [Array] a list of constant objects
    def included_constants
      instance_mixins.inject([]) do |list, mixin|
        if mixin.respond_to? :constants
          list += mixin.constants.reject do |o|
            child(:name => o.name) || list.find {|o2| o2.name == o.name }
          end
        else
          list
        end
      end
    end

    # Returns class variables defined in this namespace.
    # @return [Array] a list of class variable objects
    def cvars
      children.select {|o| o.is_a? ClassVariableObject }
    end

    # Returns for specific scopes. If no scopes are provided, returns all mixins.
    # @param [Array] scopes a list of scopes (:class, :instance) to
    #   return mixins for. If this is empty, all scopes will be returned.
    # @return [Array] a list of mixins
    def mixins(*scopes)
      return class_mixins if scopes == [:class]
      return instance_mixins if scopes == [:instance]
      class_mixins | instance_mixins
    end
  end
end
yard-0.9.37/lib/yard/code_objects/proxy.rb000066400000000000000000000172621466601756300204350ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CodeObjects
    # A special type of +NoMethodError+ when raised from a {Proxy}
    class ProxyMethodError < NoMethodError; end

    # @private
    PROXY_MATCH = /(?:#{NSEPQ}|#{ISEPQ}|#{CSEPQ})([^#{Regexp.quote(
      (NSEP + ISEP + CSEP).split('').uniq.join
    )}]+)$/

    # The Proxy class is a way to lazily resolve code objects in
    # cases where the object may not yet exist. A proxy simply stores
    # an unresolved path until a method is called on the object, at which
    # point it does a lookup using {Registry.resolve}. If the object is
    # not found, a warning is raised and {ProxyMethodError} might be raised.
    #
    # @example Creates a Proxy to the String class from a module
    #   # When the String class is parsed this method will
    #   # begin to act like the String ClassObject.
    #   Proxy.new(mymoduleobj, "String")
    # @see Registry.resolve
    # @see ProxyMethodError
    class Proxy
      def self.===(other) other.is_a?(self) end

      attr_reader :namespace
      alias parent namespace

      # Creates a new Proxy
      #
      # @raise [ArgumentError] if namespace is not a NamespaceObject
      # @return [Proxy] self
      def initialize(namespace, name, type = nil)
        namespace = Registry.root if !namespace || namespace == :root

        if name =~ /^#{NSEPQ}/
          namespace = Registry.root
          name = name[2..-1]
        end

        if name =~ PROXY_MATCH
          @orignamespace = namespace
          @origname = name
          @imethod = true if name.include? ISEP
          namespace = Proxy.new(namespace, $`) unless $`.empty?
          name = $1
        else
          @orignamespace = nil
          @origname = nil
          @imethod = nil
        end

        @name = name.to_sym
        @namespace = namespace
        @obj = nil
        @imethod ||= nil
        self.type = type

        if @namespace.is_a?(ConstantObject)
          unless @namespace.value =~ /\A#{NAMESPACEMATCH}\Z/
            raise Parser::UndocumentableError, "constant mapping for " +
              "#{@origname} (type=#{type.inspect})"
          end

          @origname = nil # forget these for a constant
          @orignamespace = nil
          @namespace = Proxy.new(@namespace.namespace, @namespace.value)
        end

        unless @namespace.is_a?(NamespaceObject) || @namespace.is_a?(Proxy)
          raise ArgumentError, "Invalid namespace object: #{namespace}"
        end

        # If the name begins with "::" (like "::String")
        # this is definitely a root level object, so
        # remove the namespace and attach it to the root
        if @name =~ /^#{NSEPQ}/
          @name.gsub!(/^#{NSEPQ}/, '')
          @namespace = Registry.root
        end
      end

      # (see Base#name)
      def name(prefix = false)
        prefix ? "#{@imethod && ISEP}#{@name}" : @name
      end

      # Returns a text representation of the Proxy
      # @return [String] the object's #inspect method or P(OBJECTPATH)
      def inspect
        to_obj ? to_obj.inspect : "P(#{path})"
      end

      # If the proxy resolves to an object, returns its path, otherwise
      # guesses at the correct path using the original namespace and name.
      #
      # @return [String] the assumed path of the proxy (or the real path
      #   of the resolved object)
      def path
        to_obj ? to_obj.path : proxy_path
      end
      alias to_s path
      alias to_str path
      alias title path

      # @return [Boolean]
      def is_a?(klass)
        to_obj ? to_obj.is_a?(klass) : self.class <= klass
      end

      # @return [Boolean]
      def ===(other)
        to_obj ? to_obj === other : self.class <= other.class
      end

      # @return [Boolean]
      def <=>(other)
        if other.respond_to? :path
          path <=> other.path
        else
          false
        end
      end

      # @return [Boolean]
      def equal?(other)
        if other.respond_to? :path
          path == other.path
        else
          false
        end
      end
      alias == equal?

      # @return [Integer] the object's hash value (for equality checking)
      def hash; path.hash end

      # Returns the class name of the object the proxy is mimicking, if
      # resolved. Otherwise returns +Proxy+.
      # @return [Class] the resolved object's class or +Proxy+
      def class
        to_obj ? to_obj.class : Proxy
      end

      # Returns the type of the proxy. If it cannot be resolved at the
      # time of the call, it will either return the inferred proxy type
      # (see {#type=}) or +:proxy+
      # @return [Symbol] the Proxy's type
      # @see #type=
      def type
        to_obj ? to_obj.type : @type || :proxy
      end

      # Allows a parser to infer the type of the proxy by its path.
      # @param [#to_sym] type the proxy's inferred type
      # @return [void]
      def type=(type) @type = type ? type.to_sym : nil end

      # @return [Boolean]
      def instance_of?(klass)
        self.class == klass
      end

      # @return [Boolean]
      def kind_of?(klass)
        self.class <= klass
      end

      # @return [Boolean]
      def respond_to?(meth, include_private = false)
        to_obj ? to_obj.respond_to?(meth, include_private) : super
      end

      # Dispatches the method to the resolved object.
      #
      # @raise [ProxyMethodError] if the proxy cannot find the real object
      def method_missing(meth, *args, &block)
        if to_obj
          to_obj.__send__(meth, *args, &block)
        else
          log.warn "Load Order / Name Resolution Problem on #{path}:\n" \
                   "-\n" \
                   "Something is trying to call #{meth} on object #{path} before it has been recognized.\n" \
                   "This error usually means that you need to modify the order in which you parse files\n" \
                   "so that #{path} is parsed before methods or other objects attempt to access it.\n" \
                   "-\n" \
                   "YARD will recover from this error and continue to parse but you *may* have problems\n" \
                   "with your generated documentation. You should probably fix this.\n" \
                   "-\n"
          begin
            super
          rescue NoMethodError
            raise ProxyMethodError, "Proxy cannot call method ##{meth} on object '#{path}'"
          end
        end
      end

      # This class is never a root object
      def root?; false end

      private

      # @note this method fixes a bug in 1.9.2: http://gist.github.com/437136
      def to_ary; nil end

      # Attempts to find the object that this unresolved object
      # references by checking if any objects by this name are
      # registered all the way up the namespace tree.
      #
      # @return [Base, nil] the registered code object or nil
      def to_obj
        return @obj if @obj
        @obj = Registry.resolve(@namespace, (@imethod ? ISEP : '') + @name.to_s, false, false, @type)
        if @obj
          if @origname && @origname.include?("::") && !@obj.path.include?(@origname)
            # the object's path should include the original proxy namespace,
            # otherwise it's (probably) not the right object.
            @obj = nil
          else
            @namespace = @obj.namespace
            @name = @obj.name
          end
        end
        @obj
      end

      def proxy_path
        if @namespace.root?
          (@imethod ? ISEP : "") + name.to_s
        elsif @origname
          if @origname =~ CONSTANTSTART
            @origname
          else
            [namespace.path, @origname].join
          end
        elsif name.to_s =~ CONSTANTSTART
          name.to_s
        else # class meth?
          [namespace.path, name.to_s].join(CSEP)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/code_objects/root_object.rb000066400000000000000000000010101466601756300215450ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module CodeObjects
    # Represents the root namespace object (the invisible Ruby module that
    # holds all top level modules, class and other objects).
    class RootObject < ModuleObject
      def path; @path ||= "" end
      def inspect; @inspect ||= "#" end
      def root?; true end
      def title; 'Top Level Namespace' end

      def equal?(other)
        other == :root ? true : super(other)
      end

      def hash; :root.hash end
    end
  end
end
yard-0.9.37/lib/yard/config.rb000066400000000000000000000226521466601756300160750ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  # This class maintains all system-wide configuration for YARD and handles
  # the loading of plugins. To access options call {options}, and to load
  # a plugin use {load_plugin}. All other public methods are used by YARD
  # during load time.
  #
  # == User Configuration Files
  #
  # Persistent user configuration files can be stored in the file
  # +~/.yard/config+, which is read when YARD first loads. The file should
  # be formatted as YAML, and should contain a map of keys and values.
  #
  # Although you can specify any key-value mapping in the configuration file,
  # YARD defines special keys specified in {DEFAULT_CONFIG_OPTIONS}.
  #
  # An example of a configuration file is listed below:
  #
  #     !!!yaml
  #     load_plugins: true # Auto-load plugins when YARD starts
  #     ignored_plugins:
  #       - yard-broken
  #       - broken2 # yard- prefix not necessary
  #     autoload_plugins:
  #       - yard-rspec
  #
  # == Automatic Loading of Plugins
  #
  # YARD 0.6.2 will no longer automatically load all plugins by default. This
  # option can be reset by setting 'load_plugins' to true in the configuration
  # file. In addition, you can specify a set of specific plugins to load on
  # load through the 'autoload_plugins' list setting. This setting is
  # independent of the 'load_plugins' value and will always be processed.
  #
  # == Ignored Plugins File
  #
  # YARD 0.5 and below used a +~/.yard/ignored_plugins+ file to specify
  # plugins to be ignored at load time. Ignored plugins in 0.6.2 and above
  # should now be specified in the main configuration file, though YARD
  # will support the +ignored_plugins+ file until 0.7.x.
  #
  # == Safe Mode
  #
  # YARD supports running in safe-mode. By doing this, it will avoid executing
  # any user code such as require files or queries. Plugins will still be
  # loaded with safe mode on, because plugins are properly namespaced with
  # a 'yard-' prefix, must be installed as a gem, and therefore cannot be
  # touched by the user. To specify safe mode, use the +safe_mode+ key.
  #
  # == Plugin Specific Configuration
  #
  # Additional settings can be defined within the configuration file
  # specifically to provide configuration for a plugin. A plugin that utilizes
  # the YARD configuration is strongly encouraged to utilize namespacing of
  # their configuration content.
  #
  #     !!!yaml
  #     load_plugins: true # Auto-load plugins when YARD starts
  #     ignored_plugins:
  #       - yard-broken
  #       - broken2 # yard- prefix not necessary
  #     autoload_plugins:
  #       - yard-rspec
  #     # Plugin Specific Configuration
  #     yard-sample-plugin:
  #       show-results-inline: true
  #
  # As the configuration is available system wide, it can be
  # accessed within the plugin code.
  #
  #
  #     if YARD::Config.options['yard-sample-plugin'] and
  #       YARD::Config.options['yard-sample-plugin']['show-results-inline']
  #       # ... perform the action that places the results inline ...
  #     else
  #       # ... do the default behavior of not showing the results inline ...
  #     end
  #
  # When accessing the configuration, be aware that this file is user managed
  # so configuration keys and values may not be present. Make no assumptions and
  # instead ensure that you check for the existence of keys before proceeding to
  # retrieve values.
  #
  # @since 0.6.2
  # @see options
  class Config
    class << self
      # The system-wide configuration options for YARD
      # @return [SymbolHash] a map a key-value pair settings.
      # @see DEFAULT_CONFIG_OPTIONS
      attr_accessor :options
    end

    # The location where YARD stores user-specific settings
    CONFIG_DIR = File.expand_path('~/.yard')

    # The main configuration YAML file.
    CONFIG_FILE = File.join(CONFIG_DIR, 'config')

    # File listing all ignored plugins
    # @deprecated Set `ignored_plugins` in the {CONFIG_FILE} instead.
    IGNORED_PLUGINS = File.join(CONFIG_DIR, 'ignored_plugins')

    # Default configuration options
    DEFAULT_CONFIG_OPTIONS = {
      :load_plugins => false,   # Whether to load plugins automatically with YARD
      :ignored_plugins => [],   # A list of ignored plugins by name
      :autoload_plugins => [],  # A list of plugins to be automatically loaded
      :safe_mode => false       # Does not execute or eval any user-level code
    }

    # The prefix used for YARD plugins. Name your gem with this prefix
    # to allow it to be used as a plugin.
    YARD_PLUGIN_PREFIX = /^yard[-_]/

    # Loads settings from {CONFIG_FILE}. This method is called by YARD at
    # load time and should not be called by the user.
    # @return [void]
    def self.load
      self.options = SymbolHash.new(false)
      options.update(DEFAULT_CONFIG_OPTIONS)
      options.update(read_config_file)
      load_commandline_safemode
      add_ignored_plugins_file
      translate_plugin_names
      load_plugins
    rescue => e
      log.error "Invalid configuration file, using default options."
      log.backtrace(e)
      options.update(DEFAULT_CONFIG_OPTIONS)
    end

    # Saves settings to {CONFIG_FILE}.
    # @return [void]
    def self.save
      require 'yaml'
      Dir.mkdir(CONFIG_DIR) unless File.directory?(CONFIG_DIR)
      File.open(CONFIG_FILE, 'w') {|f| f.write(YAML.dump(options)) }
    end

    # Loads gems that match the name 'yard-*' (recommended) or 'yard_*' except
    # those listed in +~/.yard/ignored_plugins+. This is called immediately
    # after YARD is loaded to allow plugin support.
    #
    # @return [Boolean] true if all plugins loaded successfully, false otherwise.
    def self.load_plugins
      load_gem_plugins &&
        load_autoload_plugins &&
        load_commandline_plugins ? true : false
    end

    # Loads an individual plugin by name. It is not necessary to include the
    # +yard-+ plugin prefix here.
    #
    # @param [String] name the name of the plugin (with or without +yard-+ prefix)
    # @return [Boolean] whether the plugin was successfully loaded
    def self.load_plugin(name)
      name = translate_plugin_name(name)
      return false if options[:ignored_plugins].include?(name)
      return false if name =~ /^yard-doc-/
      log.debug "Loading plugin '#{name}'..."
      require name
      true
    rescue LoadError => e
      load_plugin_failed(name, e)
    end

    # Load gem plugins if :load_plugins is true
    def self.load_gem_plugins
      return true unless options[:load_plugins]
      require 'rubygems'
      result = true
      YARD::GemIndex.each do |gem|
        begin
          next true unless gem.name =~ YARD_PLUGIN_PREFIX
          load_plugin(gem.name)
        rescue Gem::LoadError => e
          tmp = load_plugin_failed(gem.name, e)
          result = tmp unless tmp
        end
      end
      result
    rescue LoadError
      log.debug "RubyGems is not present, skipping plugin loading"
      false
    end

    # Load plugins set in :autoload_plugins
    def self.load_autoload_plugins
      options[:autoload_plugins].each {|name| load_plugin(name) }
    end

    # Load plugins from {arguments}
    def self.load_commandline_plugins
      with_yardopts do
        arguments.each_with_index do |arg, i|
          next unless arg == '--plugin'
          load_plugin(arguments[i + 1])
        end
      end
    end

    # Check for command-line safe_mode switch in {arguments}
    def self.load_commandline_safemode
      with_yardopts do
        arguments.each_with_index do |arg, _i|
          options[:safe_mode] = true if arg == '--safe'
        end
      end
    end

    # Print a warning if the plugin failed to load
    # @return [false]
    def self.load_plugin_failed(name, exception)
      log.error "Error loading plugin '#{name}'"
      log.backtrace(exception) if $DEBUG
      false
    end

    # Legacy support for {IGNORED_PLUGINS}
    def self.add_ignored_plugins_file
      if File.file?(IGNORED_PLUGINS)
        options[:ignored_plugins] += File.read(IGNORED_PLUGINS).split(/\s+/)
      end
    end

    # Translates plugin names to add yard- prefix.
    def self.translate_plugin_names
      options[:ignored_plugins].map! {|name| translate_plugin_name(name) }
      options[:autoload_plugins].map! {|name| translate_plugin_name(name) }
    end

    # Loads the YAML configuration file into memory
    # @return [Hash] the contents of the YAML file from disk
    # @see CONFIG_FILE
    def self.read_config_file
      if File.file?(CONFIG_FILE)
        require 'yaml'
        if YAML.respond_to?(:safe_load_file)
          YAML.safe_load_file(CONFIG_FILE, permitted_classes: [SymbolHash, Symbol])
        else
          YAML.load_file(CONFIG_FILE)
        end
      else
        {}
      end
    end

    # Sanitizes and normalizes a plugin name to include the 'yard-' prefix.
    # @param [String] name the plugin name
    # @return [String] the sanitized and normalized plugin name.
    def self.translate_plugin_name(name)
      name = name.delete('/') # Security sanitization
      name = "yard-" + name unless name =~ YARD_PLUGIN_PREFIX
      name
    end

    # Temporarily loads .yardopts file into @yardopts
    def self.with_yardopts
      yfile = CLI::Yardoc::DEFAULT_YARDOPTS_FILE
      @yardopts = File.file?(yfile) ? File.read_binary(yfile).shell_split : []
      result = yield
      @yardopts = nil
      result
    end

    # @return [Array] arguments from commandline and yardopts file
    def self.arguments
      ARGV + @yardopts
    end
  end

  Config.options = Config::DEFAULT_CONFIG_OPTIONS
end
yard-0.9.37/lib/yard/core_ext/000077500000000000000000000000001466601756300161045ustar00rootroot00000000000000yard-0.9.37/lib/yard/core_ext/array.rb000066400000000000000000000011361466601756300175500ustar00rootroot00000000000000# frozen_string_literal: true
class Array
  # Places values before or after another object (by value) in
  # an array. This is used in tandem with the before and after
  # methods of the {Insertion} class.
  #
  # @example Places an item before another
  #   [1, 2, 3].place(4).before(3) # => [1, 2, 4, 3]
  # @example Places an item after another
  #   [:a, :b, :c].place(:x).after(:a) # => [:a, :x, :b, :c]
  # @param [Array] values value to insert
  # @return [Insertion] an insertion object to
  # @see Insertion#before
  # @see Insertion#after
  def place(*values) Insertion.new(self, values) end
end
yard-0.9.37/lib/yard/core_ext/file.rb000066400000000000000000000041031466601756300173460ustar00rootroot00000000000000# frozen_string_literal: true
require 'fileutils'

class File
  RELATIVE_PARENTDIR = '..'
  RELATIVE_SAMEDIR = '.'

  # @group Manipulating Paths

  # Turns a path +to+ into a relative path from starting
  # point +from+. The argument +from+ is assumed to be
  # a filename. To treat it as a directory, make sure it
  # ends in +File::SEPARATOR+ ('/' on UNIX filesystems).
  #
  # @param [String] from the starting filename
  #   (or directory with +from_isdir+ set to +true+).
  # @param [String] to the final path that should be made relative.
  # @return [String] the relative path from +from+ to +to+.
  def self.relative_path(from, to)
    from = expand_path(from).split(SEPARATOR)
    to = expand_path(to).split(SEPARATOR)
    from.length.times do
      break if from[0] != to[0]
      from.shift; to.shift
    end
    from.pop
    join(*(from.map { RELATIVE_PARENTDIR } + to))
  end

  # Cleans a path by removing extraneous '..', '.' and '/' characters
  #
  # @example Clean a path
  #   File.cleanpath('a/b//./c/../e') # => "a/b/e"
  # @param [String] path the path to clean
  # @param [Boolean] rel_root allows relative path above root value
  # @return [String] the sanitized path
  def self.cleanpath(path, rel_root = false)
    path = path.split(SEPARATOR)
    path = path.inject([]) do |acc, comp|
      next acc if comp == RELATIVE_SAMEDIR
      if comp == RELATIVE_PARENTDIR && !acc.empty? && acc.last != RELATIVE_PARENTDIR
        acc.pop
        next acc
      elsif !rel_root && comp == RELATIVE_PARENTDIR && acc.empty?
        next acc
      end
      acc << comp
    end
    File.join(*path)
  end

  # @group Reading Files

  # Forces opening a file (for writing) by first creating the file's directory
  # @param [String] file the filename to open
  # @since 0.5.2
  def self.open!(file, *args, &block)
    dir = dirname(file)
    FileUtils.mkdir_p(dir) unless directory?(dir)
    open(file, *args, &block)
  end

  # Reads a file with binary encoding
  # @return [String] the ascii-8bit encoded data
  # @since 0.5.3
  def self.read_binary(file)
    File.open(file, 'rb', &:read)
  end
end
yard-0.9.37/lib/yard/core_ext/hash.rb000066400000000000000000000005241466601756300173550ustar00rootroot00000000000000# frozen_string_literal: true
class Hash
  class << self
    def create(*args)
      if args.first.is_a?(Array) && args.size == 1
        obj = new
        args.first.each {|k, v| obj[k] = v }
        obj
      else
        create_186(*args)
      end
    end
    alias create_186 []
    alias [] create
  end
end if RUBY_VERSION < "1.8.7"
yard-0.9.37/lib/yard/core_ext/insertion.rb000066400000000000000000000037571466601756300204570ustar00rootroot00000000000000# frozen_string_literal: true
# The Insertion class inserts a value before or after another
# value in a list.
#
# @example
#   Insertion.new([1, 2, 3], 4).before(3) # => [1, 2, 4, 3]
class Insertion
  # Creates an insertion object on a list with a value to be
  # inserted. To finalize the insertion, call {#before} or
  # {#after} on the object.
  #
  # @param [Array] list the list to perform the insertion on
  # @param [Object] value the value to insert
  def initialize(list, value)
    @list = list
    @values = (Array === value ? value : [value])
  end

  # Inserts the value before +val+
  # @param [Object] val the object the value will be inserted before
  # @param [Boolean] recursive look inside sublists
  def before(val, recursive = false) insertion(val, 0, recursive) end

  # Inserts the value after +val+.
  #
  # @example If subsections are ignored
  #   Insertion.new([1, [2], 3], :X).after(1) # => [1, [2], :X, 3]
  # @param [Object] val the object the value will be inserted after
  # @param [Boolean] recursive look inside sublists
  def after(val, recursive = false) insertion(val, 1, recursive) end

  # Alias for {#before} with +recursive+ set to true
  # @since 0.6.0
  def before_any(val) insertion(val, 0, true) end

  # Alias for {#after} with +recursive+ set to true
  # @since 0.6.0
  def after_any(val) insertion(val, 1, true) end

  private

  # This method performs the actual insertion
  #
  # @param [Object] val the value to insert
  # @param [Fixnum] rel the relative index (0 or 1) of where the object
  #   should be placed
  # @param [Boolean] recursive look inside sublists
  # @param [Array] list the list to place objects into
  def insertion(val, rel, recursive = false, list = @list)
    if recursive
      list.each do |item|
        next unless item.is_a?(Array)
        tmp = item.dup
        insertion(val, rel, recursive, item)
        return(list) unless item == tmp
      end
    end

    index = list.index(val)
    list[index + rel, 0] = @values if index
    list
  end
end
yard-0.9.37/lib/yard/core_ext/module.rb000066400000000000000000000004161466601756300177170ustar00rootroot00000000000000# frozen_string_literal: true
class Module
  # Returns the class name of a full module namespace path
  #
  # @example
  #   module A::B::C; class_name end # => "C"
  # @return [String] the last part of a module path
  def class_name
    name.split("::").last
  end
end
yard-0.9.37/lib/yard/core_ext/string.rb000066400000000000000000000031361466601756300177420ustar00rootroot00000000000000# frozen_string_literal: true
class String
  # Splits text into tokens the way a shell would, handling quoted
  # text as a single token. Use '\"' and "\'" to escape quotes and
  # '\\' to escape a backslash.
  #
  # @return [Array] an array representing the tokens
  def shell_split
    out = [String.new("")]
    state = :none
    escape_next = false
    quote = String.new("")
    strip.split(//).each do |char|
      case state
      when :none, :space
        case char
        when /\s/
          out << String.new("") unless state == :space
          state = :space
          escape_next = false
        when "\\"
          if escape_next
            out.last << char
            escape_next = false
          else
            escape_next = true
          end
        when '"', "'"
          if escape_next
            out.last << char
            escape_next = false
          else
            state = char
            quote = String.new("")
          end
        else
          state = :none
          out.last << char
          escape_next = false
        end
      when '"', "'"
        case char
        when '"', "'"
          if escape_next
            quote << char
            escape_next = false
          elsif char == state
            out.last << quote
            state = :none
          else
            quote << char
          end
        when '\\'
          if escape_next
            quote << char
            escape_next = false
          else
            escape_next = true
          end
        else
          quote << char
          escape_next = false
        end
      end
    end
    out
  end
end
yard-0.9.37/lib/yard/core_ext/symbol_hash.rb000066400000000000000000000047741466601756300207550ustar00rootroot00000000000000# frozen_string_literal: true
# A subclass of Hash where all keys are converted into Symbols, and
# optionally, all String values are converted into Symbols.
class SymbolHash < Hash
  # Creates a new SymbolHash object
  #
  # @param [Boolean] symbolize_value converts any String values into Symbols
  #   if this is set to +true+.
  def initialize(symbolize_value = true)
    @symbolize_value = symbolize_value
  end

  # @overload [](hash)
  #   Creates a SymbolHash object from an existing Hash
  #
  #   @example
  #     SymbolHash['x' => 1, :y => 2] # => #
  #   @param [Hash] hash the hash object
  #   @return [SymbolHash] a new SymbolHash from a hash object
  #
  # @overload [](*list)
  #   Creates a SymbolHash from an even list of keys and values
  #
  #   @example
  #     SymbolHash[key1, value1, key2, value2, ...]
  #   @param [Array] list an even list of key followed by value
  #   @return [SymbolHash] a new SymbolHash object
  def self.[](*hsh)
    obj = new
    if hsh.size == 1 && hsh.first.is_a?(Hash)
      hsh.first.each {|k, v| obj[k] = v }
    else
      0.step(hsh.size, 2) {|n| obj[hsh[n]] = hsh[n + 1] }
    end
    obj
  end

  # Assigns a value to a symbolized key
  # @param [#to_sym] key the key
  # @param [Object] value the value to be assigned. If this is a String and
  #   values are set to be symbolized, it will be converted into a Symbol.
  def []=(key, value)
    super(key.to_sym, value.instance_of?(String) && @symbolize_value ? value.to_sym : value)
  end

  # Accessed a symbolized key
  # @param [#to_sym] key the key to access
  # @return [Object] the value associated with the key
  def [](key) super(key.to_sym) end

  # Deleted a key and value associated with it
  # @param [#to_sym] key the key to delete
  # @return [void]
  def delete(key) super(key.to_sym) end

  # Tests if a symbolized key exists
  # @param [#to_sym] key the key to test
  # @return [Boolean] whether the key exists
  def key?(key) super(key.to_sym) end
  alias has_key? key?

  # Updates the object with the contents of another Hash object.
  # This method modifies the original SymbolHash object
  #
  # @param [Hash] hash the hash object to copy the values from
  # @return [SymbolHash] self
  def update(hash) hash.each {|k, v| self[k] = v }; self end
  alias merge! update

  # Merges the contents of another hash into a new SymbolHash object
  #
  # @param [Hash] hash the hash of objects to copy
  # @return [SymbolHash] a new SymbolHash containing the merged data
  def merge(hash) dup.merge!(hash) end
end
yard-0.9.37/lib/yard/docstring.rb000066400000000000000000000327101466601756300166200ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  # A documentation string, or "docstring" for short, encapsulates the
  # comments and metadata, or "tags", of an object. Meta-data is expressed
  # in the form +@tag VALUE+, where VALUE can span over multiple lines as
  # long as they are indented. The following +@example+ tag shows how tags
  # can be indented:
  #
  #   # @example My example
  #   #   a = "hello world"
  #   #   a.reverse
  #   # @version 1.0
  #
  # Tags can be nested in a documentation string, though the {Tags::Tag}
  # itself is responsible for parsing the inner tags.
  class Docstring < String
    class << self
      # @note Plugin developers should make sure to reset this value
      #   after parsing finishes. This can be done via the
      #   {Parser::SourceParser.after_parse_list} callback. This will
      #   ensure that YARD can properly parse multiple projects in
      #   the same process.
      # @return [Class] the parser class used to parse
      #   text and optional meta-data from docstrings. Defaults to
      #   {DocstringParser}.
      # @see DocstringParser
      # @see Parser::SourceParser.after_parse_list
      attr_accessor :default_parser

      # Creates a parser object using the current {default_parser}.
      # Equivalent to:
      #   Docstring.default_parser.new(*args)
      # @param args arguments are passed to the {DocstringParser}
      #   class. See {DocstringParser#initialize} for details on
      #   arguments.
      # @return [DocstringParser] the parser object used to parse a
      #   docstring.
      def parser(*args) default_parser.new(*args) end
    end

    self.default_parser = DocstringParser

    # @return [Array] the list of reference tags
    attr_reader :ref_tags

    # @return [CodeObjects::Base] the object that owns the docstring.
    attr_accessor :object

    # @return [Range] line range in the {#object}'s file where the docstring was parsed from
    attr_accessor :line_range

    # @return [String] the raw documentation (including raw tag text)
    attr_reader :all

    # @return [Boolean] whether the docstring was started with "##"
    attr_reader :hash_flag
    def hash_flag=(v) @hash_flag = v.nil? ? false : v end

    # Matches a tag at the start of a comment line
    # @deprecated Use {DocstringParser::META_MATCH}
    META_MATCH = DocstringParser::META_MATCH

    # @group Creating a Docstring Object

    # Creates a new docstring without performing any parsing through
    # a {DocstringParser}. This method is called by +DocstringParser+
    # when creating the new docstring object.
    #
    # @param [String] text the textual portion of the docstring
    # @param [Array] tags the list of tag objects in the docstring
    # @param [CodeObjects::Base, nil] object the object associated with the
    #   docstring. May be nil.
    # @param [String] raw_data the complete docstring, including all
    #   original formatting and any unparsed tags/directives.
    # @param [CodeObjects::Base, nil] ref_object a reference object used for
    #   the base set of documentation / tag information.
    def self.new!(text, tags = [], object = nil, raw_data = nil, ref_object = nil)
      docstring = allocate
      docstring.replace(text, false)
      docstring.object = object
      docstring.add_tag(*tags)
      docstring.instance_variable_set("@unresolved_reference", ref_object)
      docstring.instance_variable_set("@all", raw_data) if raw_data
      docstring
    end

    # Creates a new docstring with the raw contents attached to an optional
    # object. Parsing will be done by the {DocstringParser} class.
    #
    # @note To properly parse directives with proper parser context within
    #   handlers, you should not use this method to create a Docstring.
    #   Instead, use the {parser}, which takes a handler object that
    #   can pass parser state onto directives. If a Docstring is created
    #   with this method, directives do not have access to any parser
    #   state, and may not function as expected.
    # @example
    #   Docstring.new("hello world\n@return Object return", someobj)
    #
    # @param [String] content the raw comments to be parsed into a docstring
    #   and associated meta-data.
    # @param [CodeObjects::Base] object an object to associate the docstring
    #   with.
    def initialize(content = '', object = nil)
      @object = object
      @summary = nil
      @hash_flag = false

      self.all = content
    end

    # Adds another {Docstring}, copying over tags.
    #
    # @param [Docstring, String] other the other docstring (or string) to
    #   add.
    # @return [Docstring] a new docstring with both docstrings combines
    def +(other)
      case other
      when Docstring
        Docstring.new([all, other.all].join("\n"), object)
      else
        super
      end
    end

    def to_s
      resolve_reference
      super
    end

    # Replaces the docstring with new raw content. Called by {#all=}.
    # @param [String] content the raw comments to be parsed
    def replace(content, parse = true)
      content = content.join("\n") if content.is_a?(Array)
      @tags = []
      @ref_tags = []
      if parse
        super(parse_comments(content))
      else
        @all = content
        @unresolved_reference = nil
        super(content)
      end
    end
    alias all= replace

    # Deep-copies a docstring
    #
    # @note This method creates a new docstring with new tag lists, but does
    #   not create new individual tags. Modifying the tag objects will still
    #   affect the original tags.
    # @return [Docstring] a new copied docstring
    # @since 0.7.0
    def dup
      resolve_reference
      obj = super
      %w(all summary tags ref_tags).each do |name|
        val = instance_variable_defined?("@#{name}") && instance_variable_get("@#{name}")
        obj.instance_variable_set("@#{name}", val ? val.dup : nil)
      end
      obj
    end

    # @endgroup

    # @return [Fixnum] the first line of the {#line_range}
    # @return [nil] if there is no associated {#line_range}
    def line
      line_range ? line_range.first : nil
    end

    # Gets the first line of a docstring to the period or the first paragraph.
    # @return [String] The first line or paragraph of the docstring; always ends with a period.
    def summary
      resolve_reference
      return @summary if defined?(@summary) && @summary
      stripped = gsub(/[\r\n](?![\r\n])/, ' ').strip
      num_parens = 0
      idx = length.times do |index|
        case stripped[index, 1]
        when "."
          next_char = stripped[index + 1, 1].to_s
          break index - 1 if num_parens <= 0 && next_char =~ /^\s*$/
        when "\r", "\n"
          next_char = stripped[index + 1, 1].to_s
          if next_char =~ /^\s*$/
            break stripped[index - 1, 1] == '.' ? index - 2 : index - 1
          end
        when "{", "(", "["
          num_parens += 1
        when "}", ")", "]"
          num_parens -= 1
        end
      end
      @summary = stripped[0..idx]
      if !@summary.empty? && @summary !~ /\A\s*\{include:.+\}\s*\Z/
        @summary += '.'
      end
      @summary
    end

    # Reformats and returns a raw representation of the tag data using the
    # current tag and docstring data, not the original text.
    #
    # @return [String] the updated raw formatted docstring data
    # @since 0.7.0
    # @todo Add Tags::Tag#to_raw and refactor
    def to_raw
      tag_data = tags.map do |tag|
        case tag
        when Tags::OverloadTag
          tag_text = "@#{tag.tag_name} #{tag.signature}\n"
          unless tag.docstring.blank?
            tag_text += "\n  " + tag.docstring.all.gsub(/\r?\n/, "\n  ")
          end
        when Tags::OptionTag
          tag_text = "@#{tag.tag_name} #{tag.name}"
          tag_text += ' [' + tag.pair.types.join(', ') + ']' if tag.pair.types
          tag_text += ' ' + tag.pair.name.to_s if tag.pair.name
          tag_text += "\n " if tag.name && tag.text
          tag_text += ' (' + tag.pair.defaults.join(', ') + ')' if tag.pair.defaults
          tag_text += " " + tag.pair.text.strip.gsub(/\n/, "\n  ") if tag.pair.text
        else
          tag_text = '@' + tag.tag_name
          tag_text += ' [' + tag.types.join(', ') + ']' if tag.types
          tag_text += ' ' + tag.name.to_s if tag.name
          tag_text += "\n " if tag.name && tag.text
          tag_text += ' ' + tag.text.strip.gsub(/\n/, "\n  ") if tag.text
        end
        tag_text
      end
      [strip, tag_data.join("\n")].reject(&:empty?).compact.join("\n")
    end

    # @group Creating and Accessing Meta-data

    # Adds a tag or reftag object to the tag list. If you want to parse
    # tag data based on the {Tags::DefaultFactory} tag factory, use
    # {DocstringParser} instead.
    #
    # @param [Tags::Tag, Tags::RefTag] tags list of tag objects to add
    # @return [void]
    def add_tag(*tags)
      tags.each_with_index do |tag, i|
        case tag
        when Tags::Tag
          tag.object = object
          @tags << tag
        when Tags::RefTag, Tags::RefTagList
          @ref_tags << tag
        else
          raise ArgumentError, "expected Tag or RefTag, got #{tag.class} (at index #{i})"
        end
      end
    end

    # Convenience method to return the first tag
    # object in the list of tag objects of that name
    #
    # @example
    #   doc = Docstring.new("@return zero when nil")
    #   doc.tag(:return).text  # => "zero when nil"
    #
    # @param [#to_s] name the tag name to return data for
    # @return [Tags::Tag] the first tag in the list of {#tags}
    def tag(name)
      tags.find {|tag| tag.tag_name.to_s == name.to_s }
    end

    # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
    #
    # @param [#to_s] name the tag name to return data for, or nil for all tags
    # @return [Array] the list of tags by the specified tag name
    def tags(name = nil)
      list = stable_sort_by(@tags + convert_ref_tags, &:tag_name)
      return list unless name
      list.select {|tag| tag.tag_name.to_s == name.to_s }
    end

    # Returns true if at least one tag by the name +name+ was declared
    #
    # @param [String] name the tag name to search for
    # @return [Boolean] whether or not the tag +name+ was declared
    def has_tag?(name)
      tags.any? {|tag| tag.tag_name.to_s == name.to_s }
    end

    # Delete all tags with +name+
    # @param [String] name the tag name
    # @return [void]
    # @since 0.7.0
    def delete_tags(name)
      delete_tag_if {|tag| tag.tag_name.to_s == name.to_s }
    end

    # Deletes all tags where the block returns true
    # @yieldparam [Tags::Tag] tag the tag that is being tested
    # @yieldreturn [Boolean] true if the tag should be deleted
    # @return [void]
    # @since 0.7.0
    def delete_tag_if(&block)
      @tags.delete_if(&block)
      @ref_tags.delete_if(&block)
    end

    # Returns true if the docstring has no content that is visible to a template.
    #
    # @param [Boolean] only_visible_tags whether only {Tags::Library.visible_tags}
    #   should be checked, or if all tags should be considered.
    # @return [Boolean] whether or not the docstring has content
    def blank?(only_visible_tags = true)
      if only_visible_tags
        empty? && !tags.any? {|tag| Tags::Library.visible_tags.include?(tag.tag_name.to_sym) }
      else
        empty? && @tags.empty? && @ref_tags.empty?
      end
    end

    # @endgroup

    # Resolves unresolved other docstring reference if there is
    # unresolved reference. Does nothing if there is no unresolved
    # reference.
    #
    # Normally, you don't need to call this method
    # explicitly. Resolving unresolved reference is done implicitly.
    #
    # @return [void]
    def resolve_reference
      loop do
        return if defined?(@unresolved_reference).nil? || @unresolved_reference.nil?
        return if CodeObjects::Proxy === @unresolved_reference

        reference = @unresolved_reference
        @unresolved_reference = nil
        self.all = [reference.docstring.all, @all].join("\n")
      end
    end

    private

    # Maps valid reference tags
    #
    # @return [Array] the list of valid reference tags
    def convert_ref_tags
      list = @ref_tags.reject {|t| CodeObjects::Proxy === t.owner }

      @ref_tag_recurse_count ||= 0
      @ref_tag_recurse_count += 1
      if @ref_tag_recurse_count > 2
        log.error "#{@object.file}:#{@object.line}: Detected circular reference tag in " \
                  "`#{@object}', ignoring all reference tags for this object " \
                  "(#{@ref_tags.map {|t| "@#{t.tag_name}" }.join(", ")})."
        @ref_tags = []
        return @ref_tags
      end
      list = list.map(&:tags).flatten
      @ref_tag_recurse_count -= 1
      list
    end

    # Parses out comments split by newlines into a new code object
    #
    # @param [String] comments
    #   the newline delimited array of comments. If the comments
    #   are passed as a String, they will be split by newlines.
    #
    # @return [String] the non-metadata portion of the comments to
    #   be used as a docstring
    def parse_comments(comments)
      parser = self.class.parser
      parser.parse(comments, object)
      @all = parser.raw_text
      @unresolved_reference = parser.reference
      add_tag(*parser.tags)
      parser.text
    end

    # A stable sort_by method.
    #
    # @param list [Enumerable] the list to sort.
    # @return [Array] a stable sorted list.
    def stable_sort_by(list)
      list.each_with_index.sort_by {|tag, i| [yield(tag), i] }.map(&:first)
    end
  end
end
yard-0.9.37/lib/yard/docstring_parser.rb000066400000000000000000000264671466601756300202100ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  # Parses text and creates a {Docstring} object to represent documentation
  # for a {CodeObjects::Base}. To create a new docstring, you should initialize
  # the parser and call {#parse} followed by {#to_docstring}.
  #
  # == Subclassing Notes
  #
  # The DocstringParser can be subclassed and substituted during parsing by
  # setting the {Docstring.default_parser} attribute with the name of the
  # subclass. This allows developers to change the way docstrings are
  # parsed, allowing for completely different docstring syntaxes.
  #
  # @example Creating a Docstring with a DocstringParser
  #   DocstringParser.new.parse("text here").to_docstring
  # @example Creating a Custom DocstringParser
  #   # Parses docstrings backwards!
  #   class ReverseDocstringParser
  #     def parse_content(content)
  #       super(content.reverse)
  #     end
  #   end
  #
  #   # Set the parser as default when parsing
  #   YARD::Docstring.default_parser = ReverseDocstringParser
  # @see #parse_content
  # @since 0.8.0
  class DocstringParser
    # @return [String] the parsed text portion of the docstring,
    #   with tags removed.
    attr_accessor :text

    # @return [String] the complete input string to the parser.
    attr_accessor :raw_text

    # @return [Array] the list of meta-data tags identified
    #   by the parser
    attr_accessor :tags

    # @return [Array] a list of directives identified
    #   by the parser. This list will not be passed on to the
    #   Docstring object.
    attr_accessor :directives

    # @return [OpenStruct] any arbitrary state to be passed between
    #   tags during parsing. Mainly used by directives to coordinate
    #   behaviour (so that directives can be aware of other directives
    #   used in a docstring).
    attr_accessor :state

    # @return [CodeObjects::Base, nil] the object associated with
    #   the docstring being parsed. May be nil if the docstring is
    #   not attached to any object.
    attr_accessor :object

    # @return [CodeObjects::Base, nil] the object referenced by
    #   the docstring being parsed. May be nil if the docstring doesn't
    #   refer to any object.
    attr_accessor :reference

    # @return [Handlers::Base, nil] the handler parsing this
    #   docstring. May be nil if this docstring parser is not
    #   initialized through
    attr_accessor :handler

    # @return [Tags::Library] the tag library being used to
    #   identify registered tags in the docstring.
    attr_accessor :library

    # The regular expression to match the tag syntax
    META_MATCH = /^@(!)?((?:\w\.?)+)(?:\s+(.*))?$/i

    # @!group Creation and Conversion Methods

    # Creates a new parser to parse docstring data
    #
    # @param [Tags::Library] library a tag library for recognizing
    #   tags.
    def initialize(library = Tags::Library.instance)
      @text = ""
      @raw_text = ""
      @tags = []
      @directives = []
      @library = library
      @object = nil
      @reference = nil
      @handler = nil
      @state = OpenStruct.new
    end

    # @return [Docstring] translates parsed text into
    #   a Docstring object.
    def to_docstring
      Docstring.new!(text, tags, object, raw_text, reference)
    end

    # @!group Parsing Methods

    # Parses all content and returns itself.
    #
    # @param [String] content the docstring text to parse
    # @param [CodeObjects::Base] object the object that the docstring
    #   is attached to. Will be passed to directives to act on
    #   this object.
    # @param [Handlers::Base, nil] handler the handler object that is
    #   parsing this object. May be nil if this parser is not being
    #   called from a {Parser::SourceParser} context.
    # @return [self] the parser object. To get the docstring,
    #   call {#to_docstring}.
    # @see #to_docstring
    def parse(content, object = nil, handler = nil)
      @object = object
      @handler = handler
      @reference, @raw_text = detect_reference(content)
      text = parse_content(@raw_text)
      @text = text.strip
      call_directives_after_parse
      post_process
      self
    end

    # Parses a given block of text.
    #
    # @param [String] content the content to parse
    # @note Subclasses can override this method to perform custom
    #   parsing of content data.
    def parse_content(content)
      content = content.split(/\r?\n/) if content.is_a?(String)
      return '' if !content || content.empty?
      docstring = String.new("")

      indent = content.first[/^\s*/].length
      last_indent = 0
      orig_indent = 0
      directive = false
      last_line = ""
      tag_name = nil
      tag_buf = []

      (content + ['']).each_with_index do |line, index|
        indent = line[/^\s*/].length
        empty = (line =~ /^\s*$/ ? true : false)
        done = content.size == index

        if tag_name && (((indent < orig_indent && !empty) || done ||
            (indent == 0 && !empty)) || (indent <= last_indent && line =~ META_MATCH))
          buf = tag_buf.join("\n")
          if directive || tag_is_directive?(tag_name)
            directive = create_directive(tag_name, buf)
            if directive
              docstring << parse_content(directive.expanded_text).chomp
            end
          else
            create_tag(tag_name, buf)
          end
          tag_name = nil
          tag_buf = []
          directive = false
          orig_indent = 0
        end

        # Found a meta tag
        if line =~ META_MATCH
          directive = $1
          tag_name = $2
          tag_buf = [($3 || '')]
        elsif tag_name && indent >= orig_indent && !empty
          orig_indent = indent if orig_indent == 0
          # Extra data added to the tag on the next line
          last_empty = last_line =~ /^[ \t]*$/ ? true : false

          tag_buf << '' if last_empty
          tag_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
        elsif !tag_name
          # Regular docstring text
          docstring << line
          docstring << "\n"
        end

        last_indent = indent
        last_line = line
      end

      docstring
    end

    # @!group Parser Callback Methods

    # Call post processing callbacks on parser.
    # This is called implicitly by parser. Use this when
    # manually configuring a {Docstring} object.
    #
    # @return [void]
    def post_process
      call_after_parse_callbacks
    end

    # @!group Tag Manipulation Methods

    # Creates a tag from the {Tags::DefaultFactory tag factory}.
    #
    # To add an already created tag object, append it to {#tags}.
    #
    # @param [String] tag_name the tag name
    # @param [String] tag_buf the text attached to the tag with newlines removed.
    # @return [Tags::Tag, Tags::RefTag] a tag
    def create_tag(tag_name, tag_buf = '')
      if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
        return create_ref_tag(tag_name, $1, $2)
      end

      if library.has_tag?(tag_name)
        @tags += [library.tag_create(tag_name, tag_buf)].flatten
      else
        log.warn "Unknown tag @#{tag_name}" +
                 (object ? " in file `#{object.file}` near line #{object.line}" : "")
      end
    rescue Tags::TagFormatError
      log.warn "Invalid tag format for @#{tag_name}" +
               (object ? " in file `#{object.file}` near line #{object.line}" : "")
    end

    # Creates a {Tags::RefTag}
    def create_ref_tag(tag_name, name, object_name)
      @tags << Tags::RefTagList.new(tag_name, P(object, object_name), name)
    end

    # Creates a new directive using the registered {#library}
    # @return [Tags::Directive] the directive object that is created
    def create_directive(tag_name, tag_buf)
      if library.has_directive?(tag_name)
        dir = library.directive_create(tag_name, tag_buf, self)
        if dir.is_a?(Tags::Directive)
          @directives << dir
          dir
        end
      else
        log.warn "Unknown directive @!#{tag_name}" +
                 (object ? " in file `#{object.file}` near line #{object.line}" : "")
        nil
      end
    rescue Tags::TagFormatError
      log.warn "Invalid directive format for @!#{tag_name}" +
               (object ? " in file `#{object.file}` near line #{object.line}" : "")
      nil
    end

    # Backward compatibility to detect old tags that should be specified
    # as directives in 0.8 and onward.
    def tag_is_directive?(tag_name)
      list = %w(attribute endgroup group macro method scope visibility)
      list.include?(tag_name)
    end

    # Creates a callback that is called after a docstring is successfully
    # parsed. Use this method to perform sanity checks on a docstring's
    # tag data, or add any extra tags automatically to a docstring.
    #
    # @yield [parser] a block to be called after a docstring is parsed
    # @yieldparam [DocstringParser] parser the docstring parser object
    #   with all directives and tags created.
    # @yieldreturn [void]
    # @return [void]
    def self.after_parse(&block)
      after_parse_callbacks << block
    end

    # @return [Array] the {after_parse} callback proc objects
    def self.after_parse_callbacks
      @after_parse_callbacks ||= []
    end

    # Define a callback to check that @param tags are properly named
    after_parse do |parser|
      next unless parser.object
      next unless parser.object.is_a?(CodeObjects::MethodObject)
      next if parser.object.is_alias?
      names = parser.object.parameters.map {|l| l.first.gsub(/\W/, '') }
      seen_names = []
      infile_info = "\n    in file `#{parser.object.file}' " \
                    "near line #{parser.object.line}"
      parser.tags.each do |tag|
        next if tag.is_a?(Tags::RefTagList) # we don't handle this yet
        next unless tag.tag_name == "param"
        if seen_names.include?(tag.name)
          log.warn "@param tag has duplicate parameter name: " \
                   "#{tag.name} #{infile_info}"
        elsif names.include?(tag.name)
          seen_names << tag.name
        else
          log.warn "@param tag has unknown parameter name: " \
                   "#{tag.name} #{infile_info}"
        end
      end
    end

    private

    def namespace
      object && object.namespace
    end

    def detect_reference(content)
      if content =~ /\A\s*\(see (\S+)\s*\)(?:\s|$)/
        path = $1
        extra = $'
        [CodeObjects::Proxy.new(namespace, path), extra]
      else
        [nil, content]
      end
    end

    # @!group Parser Callback Methods

    # Calls the {Tags::Directive#after_parse} callback on all the
    # created directives.
    def call_directives_after_parse
      directives.each(&:after_parse)
    end

    # Calls all {after_parse} callbacks
    def call_after_parse_callbacks
      self.class.after_parse_callbacks.each do |cb|
        cb.call(self)
      end
    end

    # Define a callback to check that @see tags do not use {}.
    after_parse do |parser|
      next unless parser.object

      parser.tags.each_with_index do |tag, i|
        next if tag.is_a?(Tags::RefTagList) # we don't handle this yet
        next unless tag.tag_name == "see"
        next unless "#{tag.name}#{tag.text}" =~ /\A\{.*\}\Z/
        infile_info = "\n    in file `#{parser.object.file}' " \
                      "near line #{parser.object.line}"
        log.warn "@see tag (##{i + 1}) should not be wrapped in {} " \
                 "(causes rendering issues): #{infile_info}"
      end
    end
  end
end
yard-0.9.37/lib/yard/gem_index.rb000066400000000000000000000012421466601756300165570ustar00rootroot00000000000000# frozen_string_literal: true

# Backward compatibility for gem specification lookup
# @see Gem::SourceIndex
module YARD
  module GemIndex
    module_function

    def find_all_by_name(*args)
      if defined?(Gem::Specification) && Gem::Specification.respond_to?(:find_all_by_name)
        Gem::Specification.find_all_by_name(*args)
      else
        Gem.source_index.find_name(*args)
      end
    end

    def each(&block)
      if defined?(Gem::Specification) && Gem::Specification.respond_to?(:each)
        Gem::Specification.each(&block)
      else
        Gem.source_index.find_name('').each(&block)
      end
    end

    def all
      each.to_a
    end
  end
end
yard-0.9.37/lib/yard/globals.rb000066400000000000000000000010511466601756300162410ustar00rootroot00000000000000# frozen_string_literal: true
# @group Global Convenience Methods

# Shortcut for creating a YARD::CodeObjects::Proxy via a path
#
# @see YARD::CodeObjects::Proxy
# @see YARD::Registry.resolve
def P(namespace, name = nil, type = nil) # rubocop:disable Naming/MethodName
  if name.nil?
    name = namespace
    namespace = nil
  end
  YARD::Registry.resolve(namespace, name, false, true, type)
end

# The global {YARD::Logger} instance
#
# @return [YARD::Logger] the global {YARD::Logger} instance
# @see YARD::Logger
def log
  YARD::Logger.instance
end
yard-0.9.37/lib/yard/handlers/000077500000000000000000000000001466601756300160745ustar00rootroot00000000000000yard-0.9.37/lib/yard/handlers/base.rb000066400000000000000000000546571466601756300173540ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    # Raise this error when a handler should exit before completing.
    # The exception will be silenced, allowing the next handler(s) in the
    # queue to be executed.
    # @since 0.8.4
    class HandlerAborted < ::RuntimeError; end

    # Raised during processing phase when a handler needs to perform
    # an operation on an object's namespace but the namespace could
    # not be resolved.
    class NamespaceMissingError < Parser::UndocumentableError
      # The object the error occurred on
      # @return [CodeObjects::Base] a code object
      attr_accessor :object

      def initialize(object) @object = object end
    end

    # Handlers are pluggable semantic parsers for YARD's code generation
    # phase. They allow developers to control what information gets
    # generated by YARD, giving them the ability to, for instance, document
    # any Ruby DSLs that a customized framework may use. A good example
    # of this would be the ability to document and generate meta data for
    # the 'describe' declaration of the RSpec testing framework by simply
    # adding a handler for such a keyword. Similarly, any Ruby API that
    # takes advantage of class level declarations could add these to the
    # documentation in a very explicit format by treating them as first-
    # class objects in any outputted documentation.
    #
    # == Overview of a Typical Handler Scenario
    #
    # Generally, a handler class will declare a set of statements which
    # it will handle using the {handles} class declaration. It will then
    # implement the {#process} method to do the work. The processing would
    # usually involve the manipulation of the {#namespace}, {#owner}
    # {CodeObjects::Base code objects} or the creation of new ones, in
    # which case they should be registered by {#register}, a method that
    # sets some basic attributes for the new objects.
    #
    # Handlers are usually simple and take up to a page of code to process
    # and register a new object or add new attributes to the current +namespace+.
    #
    # == Setting up a Handler for Use
    #
    # A Handler is automatically registered when it is subclassed from the
    # base class. The only other thing that needs to be done is to specify
    # which statement the handler will process. This is done with the +handles+
    # declaration, taking either a {Parser::Ruby::Legacy::RubyToken}, {String} or `Regexp`.
    # Here is a simple example which processes module statements.
    #
    #   class MyModuleHandler < YARD::Handlers::Base
    #     handles TkMODULE
    #
    #     def process
    #       # do something
    #     end
    #   end
    #
    # == Processing Handler Data
    #
    # The goal of a specific handler is really up to the developer, and as
    # such there is no real guideline on how to process the data. However,
    # it is important to know where the data is coming from to be able to use
    # it.
    #
    # === +statement+ Attribute
    #
    # The +statement+ attribute pertains to the {Parser::Ruby::Legacy::Statement} object
    # containing a set of tokens parsed in by the parser. This is the main set
    # of data to be analyzed and processed. The comments attached to the statement
    # can be accessed by the {Parser::Ruby::Legacy::Statement#comments} method, but generally
    # the data to be processed will live in the +tokens+ attribute. This list
    # can be converted to a +String+ using +#to_s+ to parse the data with
    # regular expressions (or other text processing mechanisms), if needed.
    #
    # === +namespace+ Attribute
    #
    # The +namespace+ attribute is a {CodeObjects::NamespaceObject namespace object}
    # which represents the current namespace that the parser is in. For instance:
    #
    #   module SomeModule
    #     class MyClass
    #       def mymethod; end
    #     end
    #   end
    #
    # If a handler was to parse the 'class MyClass' statement, it would
    # be necessary to know that it belonged inside the SomeModule module.
    # This is the value that +namespace+ would return when processing such
    # a statement. If the class was then entered and another handler was
    # called on the method, the +namespace+ would be set to the 'MyClass'
    # code object.
    #
    # === +owner+ Attribute
    #
    # The +owner+ attribute is similar to the +namespace+ attribute in that
    # it also follows the scope of the code during parsing. However, a namespace
    # object is loosely defined as a module or class and YARD has the ability
    # to parse beyond module and class blocks (inside methods, for instance),
    # so the +owner+ attribute would not be limited to modules and classes.
    #
    # To put this into context, the example from above will be used. If a method
    # handler was added to the mix and decided to parse inside the method body,
    # the +owner+ would be set to the method object but the namespace would remain
    # set to the class. This would allow the developer to process any method
    # definitions set inside a method (def x; def y; 2 end end) by adding them
    # to the correct namespace (the class, not the method).
    #
    # In summary, the distinction between +namespace+ and +owner+ can be thought
    # of as the difference between first-class Ruby objects (namespaces) and
    # second-class Ruby objects (methods).
    #
    # === +visibility+ and +scope+ Attributes
    #
    # Mainly needed for parsing methods, the +visibility+ and +scope+ attributes
    # refer to the public/protected/private and class/instance values (respectively)
    # of the current parsing position.
    #
    # == Parsing Blocks in Statements
    #
    # In addition to parsing a statement and creating new objects, some
    # handlers may wish to continue parsing the code inside the statement's
    # block (if there is one). In this context, a block means the inside
    # of any statement, be it class definition, module definition, if
    # statement or classic 'Ruby block'.
    #
    # For example, a class statement would be "class MyClass" and the block
    # would be a list of statements including the method definitions inside
    # the class. For a class handler, the programmer would execute the
    # {#parse_block} method to continue parsing code inside the block, with
    # the +namespace+ now pointing to the class object the handler created.
    #
    # YARD has the ability to continue into any block: class, module, method,
    # even if statements. For this reason, the block parsing method must be
    # invoked explicitly out of efficiency sake.
    #
    # @abstract Subclass this class to provide a handler for YARD to use
    #   during the processing phase.
    #
    # @see CodeObjects::Base
    # @see CodeObjects::NamespaceObject
    # @see handles
    # @see #namespace
    # @see #owner
    # @see #register
    # @see #parse_block
    class Base
      # For accessing convenience, eg. "MethodObject"
      # instead of the full qualified namespace
      include YARD::CodeObjects

      include Parser

      class << self
        # Clear all registered subclasses. Testing purposes only
        # @return [void]
        def clear_subclasses
          @@subclasses = []
        end

        # Returns all registered handler subclasses.
        # @return [Array] a list of handlers
        def subclasses
          @@subclasses ||= []
        end

        def inherited(subclass)
          @@subclasses ||= []
          @@subclasses << subclass
        end

        # Declares the statement type which will be processed
        # by this handler.
        #
        # A match need not be unique to a handler. Multiple
        # handlers can process the same statement. However,
        # in this case, care should be taken to make sure that
        # {#parse_block} would only be executed by one of
        # the handlers, otherwise the same code will be parsed
        # multiple times and slow YARD down.
        #
        # @param [Parser::Ruby::Legacy::RubyToken, Symbol, String, Regexp] matches
        #   statements that match the declaration will be
        #   processed by this handler. A {String} match is
        #   equivalent to a +/\Astring/+ regular expression
        #   (match from the beginning of the line), and all
        #   token matches match only the first token of the
        #   statement.
        #
        def handles(*matches)
          (@handlers ||= []).concat(matches)
        end

        # This class is implemented by {Ruby::Base} and {Ruby::Legacy::Base}.
        # To implement a base handler class for another language, implement
        # this method to return true if the handler should process the given
        # statement object. Use {handlers} to enumerate the matchers declared
        # for the handler class.
        #
        # @param statement a statement object or node (depends on language type)
        # @return [Boolean] whether or not this handler object should process
        #   the given statement
        def handles?(statement) # rubocop:disable Lint/UnusedMethodArgument
          raise NotImplementedError, "override #handles? in a subclass"
        end

        # @return [Array] a list of matchers for the handler object.
        # @see handles?
        def handlers
          @handlers ||= []
        end

        # Declares that the handler should only be called when inside a
        # {CodeObjects::NamespaceObject}, not a method body.
        #
        # @return [void]
        def namespace_only
          @namespace_only = true
        end

        # @return [Boolean] whether the handler should only be processed inside
        #   a namespace.
        def namespace_only?
          @namespace_only ||= false
        end

        # Declares that a handler should only be called when inside a filename
        # by its basename or a regex match for the full path.
        #
        # @param [String, Regexp] filename a matching filename or regex
        # @return [void]
        # @since 0.6.2
        def in_file(filename)
          (@in_files ||= []) << filename
        end

        # @return [Boolean] whether the filename matches the declared file
        #   match for a handler. If no file match is specified, returns true.
        # @since 0.6.2
        def matches_file?(filename)
          @in_files ||= nil # avoid ruby warnings
          return true unless @in_files
          @in_files.any? do |in_file|
            case in_file
            when String
              File.basename(filename) == in_file
            when Regexp
              filename =~ in_file
            else
              true
            end
          end
        end

        # Generates a +process+ method, equivalent to +def process; ... end+.
        # Blocks defined with this syntax will be wrapped inside an anonymous
        # module so that the handler class can be extended with mixins that
        # override the +process+ method without alias chaining.
        #
        # @!macro yard.handlers.process
        #   @!method process
        #   Main processing callback
        #   @return [void]
        # @see #process
        # @return [void]
        # @since 0.5.4
        def process(&block)
          mod = Module.new
          mod.send(:define_method, :process, &block)
          include mod
        end
      end

      def initialize(source_parser, stmt)
        @parser = source_parser
        @statement = stmt
      end

      # The main handler method called by the parser on a statement
      # that matches the {handles} declaration.
      #
      # Subclasses should override this method to provide the handling
      # functionality for the class.
      #
      # @return [Array, CodeObjects::Base, Object]
      #   If this method returns a code object (or a list of them),
      #   they are passed to the +#register+ method which adds basic
      #   attributes. It is not necessary to return any objects and in
      #   some cases you may want to explicitly avoid the returning of
      #   any objects for post-processing by the register method.
      #
      # @see handles
      # @see #register
      #
      def process
        raise NotImplementedError, "#{self} did not implement a #process method for handling."
      end

      # Parses the semantic "block" contained in the statement node.
      #
      # @abstract Subclasses should call {Processor#process parser.process}
      def parse_block(*)
        raise NotImplementedError, "#{self} did not implement a #parse_block method for handling"
      end

      # @return [Processor] the processor object that manages all global state
      #   during handling.
      attr_reader :parser

      # @return [Object] the statement object currently being processed. Usually
      #   refers to one semantic language statement, though the strict definition
      #   depends on the parser used.
      attr_reader :statement

      # (see Processor#owner)
      attr_accessor :owner

      # (see Processor#namespace)
      attr_accessor :namespace

      # (see Processor#visibility)
      attr_accessor :visibility

      # (see Processor#scope)
      attr_accessor :scope

      # (see Processor#globals)
      attr_reader :globals

      # (see Processor#extra_state)
      attr_reader :extra_state

      undef owner, owner=, namespace, namespace=
      undef visibility, visibility=, scope, scope=
      undef globals, extra_state

      def owner; parser.owner end
      def owner=(v) parser.owner = v end
      def namespace; parser.namespace end
      def namespace=(v); parser.namespace = v end
      def visibility; parser.visibility end
      def visibility=(v); parser.visibility = v end
      def scope; parser.scope end
      def scope=(v); parser.scope = v end
      def globals; parser.globals end
      def extra_state; parser.extra_state end

      # Aborts a handler by raising {Handlers::HandlerAborted}.
      # An exception will only be logged in debugging mode for
      # this kind of handler exit.
      #
      # @since 0.8.4
      def abort!
        raise Handlers::HandlerAborted
      end

      # Executes a given block with specific state values for {#owner},
      # {#namespace} and {#scope}.
      #
      # @option opts [CodeObjects::NamespaceObject] :namespace (value of #namespace)
      #   the namespace object that {#namespace} will be equal to for the
      #   duration of the block.
      # @option opts [Symbol] :scope (:instance)
      #   the scope for the duration of the block.
      # @option opts [CodeObjects::Base] :owner (value of #owner)
      #   the owner object (method) for the duration of the block
      # @yield a block to execute with the given state values.
      def push_state(opts = {})
        opts = {
          :namespace => namespace,
          :scope => :instance,
          :owner => owner || namespace,
          :visibility => nil
        }.update(opts)

        ns = namespace
        vis = visibility
        sc = scope
        oo = owner
        self.namespace = opts[:namespace]
        self.visibility = opts[:visibility] || :public
        self.scope = opts[:scope]
        self.owner = opts[:owner]

        yield

        self.namespace = ns
        self.visibility = vis
        self.scope = sc
        self.owner = oo
      end

      # Do some post processing on a list of code objects.
      # Adds basic attributes to the list of objects like
      # the filename, line number, {CodeObjects::Base#dynamic},
      # source code and {CodeObjects::Base#docstring},
      # but only if they don't exist.
      #
      # @param [Array] objects
      #   the list of objects to post-process.
      #
      # @return [CodeObjects::Base, Array]
      #   returns whatever is passed in, for chainability.
      #
      def register(*objects)
        objects.flatten.each do |object|
          next unless object.is_a?(CodeObjects::Base)
          register_ensure_loaded(object)
          yield(object) if block_given?
          register_file_info(object)
          register_source(object)
          register_visibility(object)
          register_docstring(object)
          register_group(object)
          register_dynamic(object)
          register_module_function(object)
        end
        objects.size == 1 ? objects.first : objects
      end

      # Ensures that the object's namespace is loaded before attaching it
      # to the namespace.
      #
      # @param [CodeObjects::Base] object the object to register
      # @return [void]
      # @since 0.8.0
      def register_ensure_loaded(object)
        ensure_loaded!(object.namespace)
        object.namespace.children << object
      rescue NamespaceMissingError
        nil # noop
      end

      # Registers the file/line of the declaration with the object
      #
      # @param [CodeObjects::Base] object the object to register
      # @return [void]
      # @since 0.8.0
      def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
        object.add_file(file, line, comments)
      end

      # Registers any docstring found for the object and expands macros
      #
      # @param [CodeObjects::Base] object the object to register
      # @return [void]
      # @since 0.8.0
      def register_docstring(object, docstring = statement.comments, stmt = statement)
        docstring = docstring.join("\n") if Array === docstring
        parser = Docstring.parser
        parser.parse(docstring || "", object, self)

        if object && docstring
          object.docstring = parser.to_docstring

          # Add hash_flag/line_range
          if stmt
            object.docstring.hash_flag = stmt.comments_hash_flag
            object.docstring.line_range = stmt.comments_range
          end
        end

        register_transitive_tags(object)
      end

      # Registers the object as being inside a specific group
      #
      # @param [CodeObjects::Base] object the object to register
      # @return [void]
      # @since 0.8.0
      def register_group(object, group = extra_state.group)
        if group
          unless object.namespace.is_a?(Proxy)
            object.namespace.groups |= [group]
          end
          object.group = group
        end
      end

      # Registers any transitive tags from the namespace on the object
      #
      # @param [CodeObjects::Base, nil] object the object to register
      # @return [void]
      # @since 0.8.0
      def register_transitive_tags(object)
        return unless object && !object.namespace.is_a?(Proxy)
        Tags::Library.transitive_tags.each do |tag|
          next unless object.namespace.has_tag?(tag)
          next if object.has_tag?(tag)
          object.add_tag(*object.namespace.tags(tag))
        end
      end

      # @param [CodeObjects::Base] object the object to register
      # @return [void]
      # @since 0.8.0
      def register_source(object, source = statement, type = parser.parser_type)
        return unless object.is_a?(MethodObject)
        object.source ||= source
        object.source_type = type
      end

      # Registers visibility on a method object. If the object does not
      # respond to setting visibility, nothing is done.
      #
      # @param [#visibility=] object the object to register
      # @param [Symbol] visibility the visibility to set on the object
      # @since 0.8.0
      def register_visibility(object, visibility = self.visibility)
        return unless object.respond_to?(:visibility=)
        return if object.is_a?(NamespaceObject)
        object.visibility = visibility
      end

      # Registers the same method information on the module function, if
      # the object was defined as a module function.
      #
      # @param [CodeObjects::Base] object the possible module function object
      #   to copy data for
      # @since 0.8.0
      def register_module_function(object)
        return unless object.is_a?(MethodObject)
        return unless object.module_function?
        modobj = MethodObject.new(object.namespace, object.name)
        object.copy_to(modobj)
        modobj.visibility = :private # rubocop:disable Lint/UselessSetterCall
      end

      # Registers the object as dynamic if the object is defined inside
      # a method or block (owner != namespace)
      #
      # @param [CodeObjects::Base] object the object to register
      # @return [void]
      # @since 0.8.0
      def register_dynamic(object)
        object.dynamic = true if owner != namespace
      end

      # Ensures that a specific +object+ has been parsed and loaded into the
      # registry. This is necessary when adding data to a namespace, for instance,
      # since the namespace may not have been processed yet (it can be located
      # in a file that has not been handled).
      #
      # Calling this method defers the handler until all other files have been
      # processed. If the object gets resolved, the rest of the handler continues,
      # otherwise an exception is raised.
      #
      # @example Adding a mixin to the String class programmatically
      #   ensure_loaded! P('String')
      #   # "String" is now guaranteed to be loaded
      #   P('String').mixins << P('MyMixin')
      #
      # @param [Proxy, CodeObjects::Base] object the object to resolve.
      # @param [Integer] max_retries the number of times to defer the handler
      #   before raising a +NamespaceMissingError+.
      # @raise [NamespaceMissingError] if the object is not resolved within
      #   +max_retries+ attempts, this exception is raised and the handler
      #   finishes processing.
      def ensure_loaded!(object, max_retries = 1)
        return if object.root?
        return object unless object.is_a?(Proxy)

        retries = 0
        while object.is_a?(Proxy)
          raise NamespaceMissingError, object if retries > max_retries
          log.debug "Missing object #{object} in file `#{parser.file}', moving it to the back of the line."
          parser.parse_remaining_files
          retries += 1
        end
        object
      end

      # @group Macro Support

      # @abstract Implement this method to return the parameters in a method call
      #   statement. It should return an empty list if the statement is not a
      #   method call.
      # @return [Array] a list of argument names
      def call_params
        raise NotImplementedError
      end

      # @abstract Implement this method to return the method being called in
      #   a method call. It should return nil if the statement is not a method
      #   call.
      # @return [String] the method name being called
      # @return [nil] if the statement is not a method call
      def caller_method
        raise NotImplementedError
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/000077500000000000000000000000001466601756300163165ustar00rootroot00000000000000yard-0.9.37/lib/yard/handlers/c/alias_handler.rb000066400000000000000000000007241466601756300214340ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::AliasHandler < YARD::Handlers::C::Base
  MATCH = /rb_define_alias
             \s*\(\s*([\w\.]+),
             \s*"([^"]+)",
             \s*"([^"]+)"\s*\)/xm
  handles MATCH
  statement_class BodyStatement

  process do
    statement.source.scan(MATCH) do |var_name, new_name, old_name|
      var_name = "rb_cObject" if var_name == "rb_mKernel"
      handle_alias(var_name, new_name, old_name)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/attribute_handler.rb000066400000000000000000000007101466601756300223410ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::AttributeHandler < YARD::Handlers::C::Base
  MATCH = /rb_define_attr\s*\(\s*([\w\.]+),\s*"([^"]+)",\s*(0|1)\s*,\s*(0|1)\s*\)/
  handles MATCH

  process do
    return if ToplevelStatement == statement
    return if Comment === statement && statement.type != :multi
    statement.source.scan(MATCH) do |var_name, name, read, write|
      handle_attribute(var_name, name, read, write)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/base.rb000066400000000000000000000120451466601756300175570ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module C
      class Base < Handlers::Base
        include YARD::Parser::C
        include HandlerMethods

        # @return [Boolean] whether the handler handles this statement
        def self.handles?(statement, processor)
          processor.globals.cruby_processed_files ||= {}
          processor.globals.cruby_processed_files[processor.file] = true

          src = statement.respond_to?(:declaration) ?
            statement.declaration : statement.source

          handlers.any? do |a_handler|
            statement_class >= statement.class &&
              case a_handler
              when String
                src == a_handler
              when Regexp
                src =~ a_handler
              end
          end
        end

        def self.statement_class(type = nil)
          if type
            @statement_class = type
          else
            (defined?(@statement_class) && @statement_class) || Statement
          end
        end

        # @group Registering objects

        def register_docstring(object, docstring = nil, stmt = nil)
          super(object, docstring, stmt) if docstring
        end

        def register_file_info(object, file = nil, line = nil, comments = nil)
          super(object, file, line, comments) if file
        end

        def register_source(object, source = nil, type = nil)
          super(object, source, type) if source
        end

        def register_visibility(object, visibility = nil)
          super(object, visibility) if visibility
        end

        # @group Looking up Symbol and Var Values

        def symbols
          globals.cruby_symbols ||= {}
        end

        def override_comments
          globals.cruby_override_comments ||= []
        end

        def namespace_for_variable(var)
          return namespaces[var] if namespaces[var]

          # The global variables for Ruby's core error classes does not
          # represent their Ruby name. So we need to look up these names.
          name = ERROR_CLASS_NAMES[var]
          return P(name) if name

          # Otherwise the name is inferred from the C variable name.
          var = remove_var_prefix(var)
          var.empty? ? nil : P(var)
        end

        def ensure_variable_defined!(var, max_retries = 1)
          retries = 0
          object = nil

          loop do
            object = namespace_for_variable(var)
            break unless object.is_a?(Proxy)

            raise NamespaceMissingError, object if retries > max_retries
            log.debug "Missing namespace variable #{var} in file `#{parser.file}', moving it to the back of the line."
            parser.parse_remaining_files
            retries += 1
          end

          object
        end

        def namespaces
          globals.cruby_namespaces ||= {}
        end

        def processed_files
          globals.cruby_processed_files ||= {}
        end

        # @group Parsing an Inner Block

        def parse_block(opts = {})
          return if !statement.block || statement.block.empty?
          push_state(opts) do
            parser.process(statement.block)
          end
        end

        # @group Processing other files

        def process_file(file, object)
          file = File.cleanpath(file)
          return if processed_files[file]
          processed_files[file] = file
          begin
            log.debug "Processing embedded call to C source #{file}..."
            globals.ordered_parser.files.delete(file) if globals.ordered_parser
            parser.process(Parser::C::CParser.new(File.read(file), file).parse)
          rescue Errno::ENOENT
            log.warn "Missing source file `#{file}' when parsing #{object}"
          end
        end

        # @endgroup

        private

        # Generated by update_error_map.rb (Copy+past results)
        ERROR_CLASS_NAMES = {
          'rb_eArgError' => 'ArgumentError',
          'rb_eEncodingError' => 'EncodingError',
          'rb_eException' => 'Exception',
          'rb_eFatal' => 'fatal',
          'rb_eFrozenError' => 'FrozenError',
          'rb_eIndexError' => 'IndexError',
          'rb_eInterrupt' => 'Interrupt',
          'rb_eKeyError' => 'KeyError',
          'rb_eLoadError' => 'LoadError',
          'rb_eNameError' => 'NameError',
          'rb_eNoMatchingPatternError' => 'NoMatchingPatternError',
          'rb_eNoMemError' => 'NoMemoryError',
          'rb_eNoMethodError' => 'NoMethodError',
          'rb_eNotImpError' => 'NotImplementedError',
          'rb_eRangeError' => 'RangeError',
          'rb_eRuntimeError' => 'RuntimeError',
          'rb_eScriptError' => 'ScriptError',
          'rb_eSecurityError' => 'SecurityError',
          'rb_eSignal' => 'SignalException',
          'rb_eStandardError' => 'StandardError',
          'rb_eSyntaxError' => 'SyntaxError',
          'rb_eSystemCallError' => 'SystemCallError',
          'rb_eSystemExit' => 'SystemExit',
          'rb_eTypeError' => 'TypeError',
        }

        def remove_var_prefix(var)
          var.gsub(/^rb_[mc]|^[a-z_]+/, '')
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/class_handler.rb000066400000000000000000000014701466601756300214470ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::ClassHandler < YARD::Handlers::C::Base
  MATCH1 = /([\w\.]+)\s* = \s*(?:rb_define_class|boot_defclass)\s*
            \(
               \s*"([\w:]+)",
               \s*(\w+|0)\s*
            \)/mx

  MATCH2 = /([\w\.]+)\s* = \s*rb_define_class_under\s*
            \(
               \s*(\w+),
               \s*"(\w+)"(?:,
               \s*([\w\*\s\(\)\.\->]+)\s*)?  # for SWIG
            \s*\)/mx
  handles MATCH1
  handles MATCH2
  statement_class BodyStatement

  process do
    statement.source.scan(MATCH1) do |var_name, class_name, parent|
      handle_class(var_name, class_name, parent)
    end
    statement.source.scan(MATCH2) do |var_name, in_module, class_name, parent|
      handle_class(var_name, class_name, parent.strip, in_module)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/constant_handler.rb000066400000000000000000000006701466601756300221740ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::ConstantHandler < YARD::Handlers::C::Base
  MATCH = /\brb_define_((?:readonly_)?variable|(?:global_)?const)
                \s*\((?:\s*(\w+),)?\s*"(\w+)",\s*(.*?)\s*\)\s*;/xm
  handles MATCH
  statement_class BodyStatement

  process do
    statement.source.scan(MATCH) do |type, var_name, const_name, value|
      handle_constants(type, var_name, const_name, value)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/handler_methods.rb000066400000000000000000000204761466601756300220140ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module C
      module HandlerMethods
        include Parser::C
        include CodeObjects
        include Common::MethodHandler

        def handle_class(var_name, class_name, parent, in_module = nil)
          parent = nil if parent == "0"
          namespace = in_module ? ensure_variable_defined!(in_module) : Registry.root
          if namespace.nil?
            raise Parser::UndocumentableError,
              "class #{class_name}. Cannot find definition for parent namespace."
          end

          register ClassObject.new(namespace, class_name) do |obj|
            if parent
              parent_class = namespace_for_variable(parent)
              if parent_class.is_a?(Proxy)
                obj.superclass = "::#{parent_class.path}"
                obj.superclass.type = :class
              else
                obj.superclass = parent_class
              end
            end
            namespaces[var_name] = obj
            register_file_info(obj, statement.file, statement.line)
          end
        end

        def handle_module(var_name, module_name, in_module = nil)
          namespace = in_module ? ensure_variable_defined!(in_module) : Registry.root
          if namespace.nil?
            raise Parser::UndocumentableError,
              "module #{module_name}. Cannot find definition for parent namespace."
          end

          register ModuleObject.new(namespace, module_name) do |obj|
            namespaces[var_name] = obj
            register_file_info(obj, statement.file, statement.line)
          end
        end

        def handle_method(scope, var_name, name, func_name, _source_file = nil)
          visibility = :public
          case scope
          when "singleton_method"; scope = :class
          when "module_function"; scope = :module
          when "private_method"; scope = :instance; visibility = :private
          else; scope = :instance
          end

          namespace = namespace_for_variable(var_name)

          # Is this method being defined on a core Ruby class or module?
          if namespace.is_a?(Proxy)
            if var_name =~ /^rb_c(\w+)/ && YARD::CodeObjects::BUILTIN_CLASSES.include?($1)
              namespace = namespaces[var_name] = YARD::CodeObjects::ClassObject.new(:root, $1)
            elsif var_name =~ /^rb_m(\w+)/ && YARD::CodeObjects::BUILTIN_MODULES.include?($1)
              namespace = namespaces[var_name] = YARD::CodeObjects::ModuleObject.new(:root, $1)
            end
          end

          return if namespace.nil? # XXX: raise UndocumentableError might be too noisy.
          register MethodObject.new(namespace, name, scope) do |obj|
            register_visibility(obj, visibility)
            find_method_body(obj, func_name)
            obj.explicit = true
            add_predicate_return_tag(obj) if name =~ /\?$/
          end
        end

        def handle_attribute(var_name, name, read, write)
          values = {:read => read.to_i, :write => write.to_i}
          {:read => name, :write => "#{name}="}.each do |type, meth_name|
            next unless values[type] > 0
            obj = handle_method(:instance, var_name, meth_name, nil)
            register_file_info(obj, statement.file, statement.line)
            obj.namespace.attributes[:instance][name] ||= SymbolHash[:read => nil, :write => nil]
            obj.namespace.attributes[:instance][name][type] = obj
          end
        end

        def handle_alias(var_name, new_name, old_name)
          namespace = namespace_for_variable(var_name)
          return if namespace.nil?
          new_meth = new_name.to_sym
          old_meth = old_name.to_sym
          old_obj = namespace.child(:name => old_meth, :scope => :instance)
          new_obj = register MethodObject.new(namespace, new_meth, :instance) do |o|
            register_visibility(o, visibility)
            register_file_info(o, statement.file, statement.line)
          end

          if old_obj
            new_obj.signature = old_obj.signature
            new_obj.source = old_obj.source
            new_obj.docstring = old_obj.docstring
            new_obj.docstring.object = new_obj
          else
            new_obj.signature = "def #{new_meth}" # this is all we know.
          end

          namespace.aliases[new_obj] = old_meth
        end

        def handle_constants(type, var_name, const_name, value)
          return unless type =~ /^const$|^global_const$/
          namespace = type == 'global_const' ?
            :root : namespace_for_variable(var_name)
          register ConstantObject.new(namespace, const_name) do |obj|
            obj.source_type = :c
            obj.value = value
            register_file_info(obj, statement.file, statement.line)
            find_constant_docstring(obj)
          end
        end

        private

        def find_constant_docstring(object)
          comment = nil

          # look inside overrides for declaration value
          override_comments.each do |name, override_comment|
            next unless override_comment.file == statement.file
            just_const_name = name.gsub(/\A.+::/, '')
            if object.path == name || object.name.to_s == just_const_name
              comment = override_comment.source
              break
            end
          end

          # use any comments on this statement as a last resort
          if comment.nil? && statement.comments && statement.comments.source =~ /\S/
            comment = statement.comments.source
            stmt = statement.comments
          end

          # In the case of rb_define_const, the definition and comment are in
          # "/* definition: comment */" form.  The literal ':' and '\' characters
          # can be escaped with a backslash.
          if comment
            comment.scan(/\A\s*(.*?[^\s\\]):\s*(.+)/m) do |new_value, new_comment|
              object.value = new_value.gsub(/\\:/, ':')
              comment = new_comment
            end
            register_docstring(object, comment, stmt)
          end
        end

        def find_method_body(object, symbol)
          file = statement.file
          in_file = false
          if statement.comments && statement.comments.source =~ /\A\s*in (\S+)\Z/
            file = $1
            in_file = true
            process_file(file, object)
          end

          src_stmt = symbols[symbol]
          if src_stmt
            register_file_info(object, src_stmt.file, src_stmt.line, true)
            register_source(object, src_stmt)
            record_parameters(object, symbol, src_stmt)
            unless src_stmt.comments.nil? || src_stmt.comments.source.empty?
              register_docstring(object, src_stmt.comments.source, src_stmt)
              return # found docstring
            end
          end

          # found source (possibly) but no docstring
          # so look in overrides
          return if override_comments.any? do |name, override_comment|
            next unless override_comment.file == file
            name = name.gsub(/::([^:\.#]+?)\Z/, '.\1')

            # explicit namespace in override comment
            path = (name =~ /\.|#/ ? object.path : object.name.to_s)
            if path == name || path == name.sub(/new$/, 'initialize') || path == name.sub('.', '#')
              register_docstring(object, override_comment.source, override_comment)
              true
            else
              false
            end
          end

          # use any comments on this statement as a last resort
          if !in_file && statement.comments && statement.comments.source =~ /\S/
            register_docstring(object, statement.comments.source, statement)
          end
        end

        def record_parameters(object, symbol, src)
          # use regex to extract comma-delimited list of parameters from cfunc definition
          if src.source =~ /VALUE\s+#{symbol}\(([^)]*)\)\s*\{/m
            params = $~[1].split(/\s*,\s*/) # rubocop:disable Style/SpecialGlobalVars
            # cfunc for a "varargs" method has params "int argc, VALUE *argv"
            if params[0] =~ /int\s+argc/ && params[1] =~ /VALUE\s*\*\s*argv/
              object.parameters = [['*args', nil]]
            else
              # the first cfunc argument is the 'self' argument, we don't need that
              object.parameters = params.drop(1).map {|s| [s[/VALUE\s+(\S+)/, 1], nil] }
            end
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/init_handler.rb000066400000000000000000000011051466601756300213000ustar00rootroot00000000000000# frozen_string_literal: true
# Handles the Init_Libname() method
class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
  MATCH = /\A\s*(?:\S+\s+)*void\s+(?:[Ii]nit_)?(\w+)\s*/
  handles MATCH
  statement_class ToplevelStatement

  process do
    parse_block
    decl = statement.declaration[MATCH, 1]
    if decl
      ns = namespace_for_variable(decl)
      if ns.is_a?(YARD::CodeObjects::NamespaceObject) && ns.docstring.blank?
        if statement.comments
          register_docstring(ns, statement.comments.source, statement)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/method_handler.rb000066400000000000000000000030411466601756300216160ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
  MATCH1 = /rb_define_
                 (
                    singleton_method |
                    method           |
                    module_function  |
                    private_method
                 )
                 \s*\(\s*([\w\.]+)\s*,
                   \s*"([^"]+)"\s*,
                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?\s*,
                   \s*(-?\w+)\s*\)/xm
  MATCH2 = /rb_define_global_function\s*\(
                \s*"([^"]+)",
                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
                \s*(-?\w+)\s*\)/xm
  MATCH3 = /define_filetest_function\s*\(
                \s*"([^"]+)",
                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
                \s*(-?\w+)\s*\)/xm
  handles MATCH1
  handles MATCH2
  handles MATCH3
  statement_class BodyStatement

  process do
    statement.source.scan(MATCH1) do |type, var_name, name, func_name, _param_count|
      break if var_name == "ruby_top_self"
      break if var_name == "nstr"
      break if var_name == "envtbl"

      var_name = "rb_cObject" if var_name == "rb_mKernel"
      handle_method(type, var_name, name, func_name)
    end

    statement.source.scan(MATCH2) do |name, func_name, _param_count|
      handle_method("method", "rb_mKernel", name, func_name)
    end

    statement.source.scan(MATCH3) do |name, func_name, _param_count|
      handle_method("singleton_method", "rb_cFile", name, func_name)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/mixin_handler.rb000066400000000000000000000011461466601756300214660ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::MixinHandler < YARD::Handlers::C::Base
  MATCH = /rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/
  handles MATCH
  statement_class BodyStatement

  process do
    statement.source.scan(MATCH) do |klass_var, mixin_var|
      namespace = namespace_for_variable(klass_var)
      ensure_loaded!(namespace)

      var = namespace_for_variable(mixin_var)
      if var
        namespace.mixins(:instance) << var
      else
        raise YARD::Parser::UndocumentableError,
          "CRuby mixin for unrecognized variable '#{mixin_var}'"
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/module_handler.rb000066400000000000000000000011151466601756300216230ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::ModuleHandler < YARD::Handlers::C::Base
  MATCH1 = /([\w\.]+)\s* = \s*rb_define_module\s*\(\s*"([\w:]+)"\s*\)/mx
  MATCH2 = /([\w\.]+)\s* = \s*rb_define_module_under\s*\(\s*(\w+),\s*"(\w+)"\s*\)/mx
  handles MATCH1
  handles MATCH2
  statement_class BodyStatement

  process do
    statement.source.scan(MATCH1) do |var_name, module_name|
      handle_module(var_name, module_name)
    end
    statement.source.scan(MATCH2) do |var_name, in_module, module_name|
      handle_module(var_name, module_name, in_module)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/override_comment_handler.rb000066400000000000000000000015571466601756300237110ustar00rootroot00000000000000# frozen_string_literal: true
# Parses comments
class YARD::Handlers::C::OverrideCommentHandler < YARD::Handlers::C::Base
  handles(/./)
  statement_class Comment

  process do
    return if statement.overrides.empty?
    statement.overrides.each do |type, name|
      override_comments << [name, statement]
      obj = nil
      case type
      when :class
        name, superclass = *name.split(/\s*<\s*/)
        obj = YARD::CodeObjects::ClassObject.new(:root, name)
        obj.superclass = "::#{superclass}" if superclass
      when :module
        obj = YARD::CodeObjects::ModuleObject.new(:root, name)
      end
      register(obj)
    end
  end

  def register_docstring(object, docstring = statement.source, stmt = statement)
    super
  end

  def register_file_info(object, file = parser.file, line = statement.line, comments = statement.comments)
    super
  end
end
yard-0.9.37/lib/yard/handlers/c/path_handler.rb000066400000000000000000000004511466601756300212740ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::PathHandler < YARD::Handlers::C::Base
  MATCH = /([\w\.]+)\s* = \s*rb_path2class\s*\(\s*"([\w:]+)"\)/mx
  handles MATCH

  process do
    statement.source.scan(MATCH) do |var_name, path|
      namespaces[var_name] = P(path)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/struct_handler.rb000066400000000000000000000006241466601756300216660ustar00rootroot00000000000000# frozen_string_literal: true
class YARD::Handlers::C::StructHandler < YARD::Handlers::C::Base
  MATCH = /([\w\.]+)\s*=\s*(?:rb_struct_define_without_accessor)\s*
           \(\s*"([\w:]+)"\s*,\s*(\w+)\s*/mx
  handles MATCH
  statement_class BodyStatement

  process do
    statement.source.scan(MATCH) do |var_name, class_name, parent|
      handle_class(var_name, class_name, parent)
    end
  end
end
yard-0.9.37/lib/yard/handlers/c/symbol_handler.rb000066400000000000000000000005511466601756300216460ustar00rootroot00000000000000# frozen_string_literal: true
# Keeps track of function bodies for symbol lookup during Ruby method declarations
class YARD::Handlers::C::SymbolHandler < YARD::Handlers::C::Base
  MATCH = /\A\s*(?:(?:\w+)\s+)?(?:intern\s+)?VALUE\s+(\w+)\s*\(/
  handles MATCH
  statement_class ToplevelStatement
  process { symbols[statement.source[MATCH, 1]] = statement }
end
yard-0.9.37/lib/yard/handlers/common/000077500000000000000000000000001466601756300173645ustar00rootroot00000000000000yard-0.9.37/lib/yard/handlers/common/method_handler.rb000066400000000000000000000011101466601756300226570ustar00rootroot00000000000000# frozen_string_literal: true

module YARD::Handlers
  module Common
    # Shared functionality between Ruby and C method handlers.
    module MethodHandler
      # @param [MethodObject] obj
      def add_predicate_return_tag(obj)
        if obj.tag(:return) && (obj.tag(:return).types || []).empty?
          obj.tag(:return).types = ['Boolean']
        elsif obj.tag(:return).nil?
          unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
            obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/processor.rb000066400000000000000000000172531466601756300204500ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module Handlers
    # Iterates over all statements in a file and delegates them to the
    # {Handlers::Base} objects that are registered to handle the statement.
    #
    # This class is passed to each handler and keeps overall processing state.
    # For example, if the {#visibility} is set in a handler, all following
    # statements will have access to this state. This allows "public",
    # "protected" and "private" statements to be handled in classes and modules.
    # In addition, the {#namespace} can be set during parsing to control
    # where objects are being created from. You can also access extra stateful
    # properties that any handler can set during the duration of the post
    # processing of a file from {#extra_state}. If you need to access state
    # across different files, look at {#globals}.
    #
    # @see Handlers::Base
    class Processor
      class << self
        # Registers a new namespace for handlers of the given type.
        # @since 0.6.0
        def register_handler_namespace(type, ns)
          namespace_for_handler[type] = ns
        end

        # @return [Hash] a list of registered parser type extensions
        # @private
        # @since 0.6.0
        attr_reader :namespace_for_handler
        undef namespace_for_handler
        def namespace_for_handler; @@parser_type_extensions ||= {} end
      end

      register_handler_namespace :ruby, Ruby
      register_handler_namespace :ruby18, Ruby::Legacy
      register_handler_namespace :c, C

      # @return [String] the filename
      attr_accessor :file

      # @return [CodeObjects::NamespaceObject] the current namespace
      attr_accessor :namespace

      # @return [Symbol] the current visibility (public, private, protected)
      attr_accessor :visibility

      # @return [Symbol] the current scope (class, instance)
      attr_accessor :scope

      # @return [CodeObjects::Base, nil] unlike the namespace, the owner
      #   is a non-namespace object that should be stored between statements.
      #   For instance, when parsing a method body, the {CodeObjects::MethodObject}
      #   is set as the owner, in case any extra method information is processed.
      attr_accessor :owner

      # @return [Symbol] the parser type (:ruby, :ruby18, :c)
      attr_accessor :parser_type

      # Handlers can share state for the entire post processing stage through
      # this attribute. Note that post processing stage spans multiple files.
      # To share state only within a single file, use {#extra_state}
      #
      # @example Sharing state among two handlers
      #   class Handler1 < YARD::Handlers::Ruby::Base
      #     handles :class
      #     process { globals.foo = :bar }
      #   end
      #
      #   class Handler2 < YARD::Handlers::Ruby::Base
      #     handles :method
      #     process { puts globals.foo }
      #   end
      # @return [OpenStruct] global shared state for post-processing stage
      # @see #extra_state
      attr_accessor :globals

      # Share state across different handlers inside of a file.
      # This attribute is similar to {#visibility}, {#scope}, {#namespace}
      # and {#owner}, in that they all maintain state across all handlers
      # for the entire source file. Use this attribute to store any data
      # your handler might need to save during the parsing of a file. If
      # you need to save state across files, see {#globals}.
      #
      # @return [OpenStruct] an open structure that can store arbitrary data
      # @see #globals
      attr_accessor :extra_state

      # Creates a new Processor for a +file+.
      # @param [Parser::SourceParser] parser the parser used to initialize the processor
      def initialize(parser)
        @file = parser.file || "(stdin)"
        @namespace = YARD::Registry.root
        @visibility = :public
        @scope = :instance
        @owner = @namespace
        @parser_type = parser.parser_type
        @handlers_loaded = {}
        @globals = parser.globals || OpenStruct.new
        @extra_state = OpenStruct.new
        load_handlers
      end

      # Processes a list of statements by finding handlers to process each
      # one.
      #
      # @param [Array] statements a list of statements
      # @return [void]
      def process(statements)
        statements.each_with_index do |stmt, _index|
          find_handlers(stmt).each do |handler|
            begin
              handler.new(self, stmt).process
            rescue HandlerAborted
              log.debug "#{handler} cancelled from #{caller.last}"
              log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
            rescue NamespaceMissingError => missingerr
              log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized.\n" \
                       "If this class/method is part of your source tree, this will affect your documentation results.\n" \
                       "You can correct this issue by loading the source file for this object before `#{file}'\n"
            rescue Parser::UndocumentableError => undocerr
              log.warn "in #{handler}: Undocumentable #{undocerr.message}\n" \
                       "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
            rescue => e
              log.error "Unhandled exception in #{handler}:\n" \
                        "  in `#{file}`:#{stmt.line}:\n\n#{stmt.show}\n"
              log.backtrace(e)
            end
          end
        end
      end

      # Continue parsing the remainder of the files in the +globals.ordered_parser+
      # object. After the remainder of files are parsed, processing will continue
      # on the current file.
      #
      # @return [void]
      # @see Parser::OrderedParser
      def parse_remaining_files
        if globals.ordered_parser
          globals.ordered_parser.parse
          log.debug("Re-processing #{@file}...")
        end
      end

      # Searches for all handlers in {Base.subclasses} that match the +statement+
      #
      # @param statement the statement object to match.
      # @return [Array] a list of handlers to process the statement with.
      def find_handlers(statement)
        Base.subclasses.find_all do |handler|
          handler_base_class > handler &&
            (handler.namespace_only? ? owner.is_a?(CodeObjects::NamespaceObject) : true) &&
            handles?(handler, statement)
        end
      end

      private

      def handles?(handler, statement)
        return false unless handler.matches_file?(file)
        if handler.method(:handles?).arity == 1
          handler.handles?(statement)
        elsif [-1, 2].include?(handler.method(:handles?).arity)
          handler.handles?(statement, self)
        end
      end

      # Returns the handler base class
      # @return [Base] the base class
      def handler_base_class
        handler_base_namespace.const_get(:Base)
      end

      # The module holding the handlers to be loaded
      #
      # @return [Module] the module containing the handlers depending on
      #   {#parser_type}.
      def handler_base_namespace
        self.class.namespace_for_handler[parser_type]
      end

      # Loads handlers from {#handler_base_namespace}. This ensures that
      # Ruby1.9 handlers are never loaded into 1.8; also lowers the amount
      # of modules that are loaded
      # @return [void]
      def load_handlers
        return if @handlers_loaded[parser_type]
        handler_base_namespace.constants.each do |c|
          const = handler_base_namespace.const_get(c)
          unless Handlers::Base.subclasses.include?(const)
            Handlers::Base.subclasses << const
          end
        end
        @handlers_loaded[parser_type] = true
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/000077500000000000000000000000001466601756300170555ustar00rootroot00000000000000yard-0.9.37/lib/yard/handlers/ruby/alias_handler.rb000066400000000000000000000031651466601756300221750ustar00rootroot00000000000000# frozen_string_literal: true
# Handles alias and alias_method calls
class YARD::Handlers::Ruby::AliasHandler < YARD::Handlers::Ruby::Base
  handles :alias, method_call(:alias_method)
  namespace_only

  process do
    names = []
    if statement.type == :alias
      nodes = [:ident, :op, :kw, :const, :tstring_content, :string_content]
      names = statement.map {|o| o.jump(*nodes).source }
    elsif statement.call?
      statement.parameters(false).each do |obj|
        case obj.type
        when :symbol_literal
          names << obj.jump(:ident, :op, :kw, :const).source
        when :string_literal, :dyna_symbol
          names << obj.jump(:string_content, :tstring_content).source
        end
      end
    end
    raise YARD::Parser::UndocumentableError, "alias/alias_method" if names.size != 2

    new_meth = names[0].to_sym
    old_meth = names[1].to_sym
    old_obj = namespace.child(:name => old_meth, :scope => scope)
    new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
      o.add_file(parser.file, statement.line)
    end
    namespace.aliases[new_obj] = old_meth

    if old_obj
      new_obj.signature = old_obj.signature
      new_obj.source = old_obj.source
      comments = [old_obj.docstring.to_raw, statement.comments].join("\n")
      doc = YARD::Docstring.parser.parse(comments, new_obj, self)
      new_obj.docstring = doc.to_docstring
      new_obj.docstring.line_range = statement.comments_range
      new_obj.docstring.hash_flag = statement.comments_hash_flag
      new_obj.docstring.object = new_obj
    else
      new_obj.signature = "def #{new_meth}" # this is all we know.
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/attribute_handler.rb000066400000000000000000000054701466601756300231100ustar00rootroot00000000000000# frozen_string_literal: true
# Handles +attr_*+ statements in modules/classes
class YARD::Handlers::Ruby::AttributeHandler < YARD::Handlers::Ruby::Base
  handles method_call(:attr)
  handles method_call(:attr_reader)
  handles method_call(:attr_writer)
  handles method_call(:attr_accessor)
  namespace_only

  process do
    return if statement.type == :var_ref || statement.type == :vcall
    read = true
    write = false
    params = statement.parameters(false).dup

    # Change read/write based on attr_reader/writer/accessor
    case statement.method_name(true)
    when :attr
      # In the case of 'attr', the second parameter (if given) isn't a symbol.
      if params.size == 2
        write = true if params.pop == s(:var_ref, s(:kw, "true"))
      end
    when :attr_accessor
      write = true
    when :attr_reader
      # change nothing
    when :attr_writer
      read = false
      write = true
    end

    # Add all attributes
    validated_attribute_names(params).each do |name|
      namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]

      # Show their methods as well
      {:read => name, :write => "#{name}="}.each do |type, meth|
        if type == :read ? read : write
          o = MethodObject.new(namespace, meth, scope)
          if type == :write
            o.parameters = [['value', nil]]
            src = "def #{meth}(value)"
            full_src = "#{src}\n  @#{name} = value\nend"
            doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
          else
            src = "def #{meth}"
            full_src = "#{src}\n  @#{name}\nend"
            doc = "Returns the value of attribute #{name}."
          end
          o.source ||= full_src
          o.signature ||= src
          register(o)
          o.docstring = doc if o.docstring.blank?(false)

          # Register the object explicitly
          namespace.attributes[scope][name][type] = o
        else
          obj = namespace.children.find {|other| other.name == meth.to_sym && other.scope == scope }

          # register an existing method as attribute
          namespace.attributes[scope][name][type] = obj if obj
        end
      end
    end
  end

  protected

  # Strips out any non-essential arguments from the attr statement.
  #
  # @param [Array] params a list of the parameters
  #   in the attr call.
  # @return [Array] the validated attribute names
  # @raise [Parser::UndocumentableError] if the arguments are not valid.
  def validated_attribute_names(params)
    params.map do |obj|
      case obj.type
      when :symbol_literal
        obj.jump(:ident, :op, :kw, :const).source
      when :string_literal
        obj.jump(:string_content).source
      else
        raise YARD::Parser::UndocumentableError, obj.source
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/base.rb000066400000000000000000000133601466601756300203170ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module Ruby
      # To implement a custom handler matcher, subclass this class and implement
      # {#matches?} to return whether a node matches the handler.
      #
      # @example A Custom Handler Matcher Extension
      #   # Implements a handler that checks for a specific string
      #   # in the node's source.
      #   class MyExtension < HandlesExtension
      #     def matches?(node) node.source.include?(name) end
      #   end
      #
      #   # This handler will handle any node where the source includes 'foo'
      #   class MyHandler < Handlers::Ruby::Base
      #     handles MyExtension.new('foo')
      #   end
      class HandlesExtension
        # Creates a new extension with a specific matcher value +name+
        # @param [Object] name the matcher value to check against {#matches?}
        def initialize(name) @name = name end

        # Tests if the node matches the handler
        # @param [Parser::Ruby::AstNode] node a Ruby node
        # @return [Boolean] whether the +node+ matches the handler
        def matches?(node) # rubocop:disable Lint/UnusedMethodArgument
          raise NotImplementedError
        end

        protected

        # @return [String] the extension matcher value
        attr_reader :name
      end

      class MethodCallWrapper < HandlesExtension
        def matches?(node)
          case node.type
          when :var_ref
            if !node.parent || node.parent.type == :list
              return true if node[0].type == :ident && (name.nil? || node[0][0] == name)
            end
          when :fcall, :command, :vcall
            return true if name.nil? || node[0][0] == name
          when :call, :command_call
            return true if name.nil? || node[2][0] == name
          end
          false
        end
      end

      class TestNodeWrapper < HandlesExtension
        def matches?(node) !node.send(name).is_a?(FalseClass) end
      end

      # This is the base handler class for the new-style (1.9) Ruby parser.
      # All handlers that subclass this base class will be used when the
      # new-style parser is used. For implementing legacy handlers, see
      # {Legacy::Base}.
      #
      # @abstract See {Handlers::Base} for subclassing information.
      # @see Handlers::Base
      # @see Legacy::Base
      class Base < Handlers::Base
        class << self
          include Parser::Ruby

          # @group Statement Matcher Extensions

          # Matcher for handling any type of method call. Method calls can
          # be expressed by many {AstNode} types depending on the syntax
          # with which it is called, so YARD allows you to use this matcher
          # to simplify matching a method call.
          #
          # @example Match the "describe" method call
          #   handles method_call(:describe)
          #
          #   # The following will be matched:
          #   # describe(...)
          #   # object.describe(...)
          #   # describe "argument" do ... end
          #
          # @param [#to_s] name matches the method call of this name
          # @return [void]
          def method_call(name = nil)
            MethodCallWrapper.new(name ? name.to_s : nil)
          end

          # Matcher for handling a node with a specific meta-type. An {AstNode}
          # has a {AstNode#type} to define its type but can also be associated
          # with a set of types. For instance, +:if+ and +:unless+ are both
          # of the meta-type +:condition+.
          #
          # A meta-type is any method on the {AstNode} class ending in "?",
          # though you should not include the "?" suffix in your declaration.
          # Some examples are: "condition", "call", "literal", "kw", "token",
          # "ref".
          #
          # @example Handling any conditional statement (if, unless)
          #   handles meta_type(:condition)
          # @param [Symbol] type the meta-type to match. A meta-type can be
          #   any method name + "?" that {AstNode} responds to.
          # @return [void]
          def meta_type(type)
            TestNodeWrapper.new(type.to_s + "?")
          end

          # @group Testing for a Handler

          # @return [Boolean] whether or not an {AstNode} object should be
          #   handled by this handler
          def handles?(node)
            handlers.any? do |a_handler|
              case a_handler
              when Symbol
                a_handler == node.type
              when String
                node.source == a_handler
              when Regexp
                node.source =~ a_handler
              when Parser::Ruby::AstNode
                a_handler == node
              when HandlesExtension
                a_handler.matches?(node)
              end
            end
          end
        end

        include Parser::Ruby

        # @group Parsing an Inner Block

        def parse_block(inner_node, opts = {})
          push_state(opts) do
            nodes = inner_node.type == :list ? inner_node.children : [inner_node]
            parser.process(nodes)
          end
        end

        # @group Macro Handling

        def call_params
          return [] unless statement.respond_to?(:parameters)
          statement.parameters(false).compact.map do |param|
            if param.type == :list
              param.map {|n| n.jump(:ident, :kw, :tstring_content).source }
            else
              param.jump(:ident, :kw, :tstring_content).source
            end
          end.flatten
        end

        def caller_method
          if statement.call? || statement.def?
            statement.method_name(true).to_s
          elsif statement.type == :var_ref || statement.type == :vcall
            statement[0].jump(:ident, :kw).source
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/class_condition_handler.rb000066400000000000000000000047511466601756300242610ustar00rootroot00000000000000# frozen_string_literal: true
# Matches if/unless conditions inside classes and attempts to process only
# one branch (by evaluating the condition if possible).
#
# @example A simple class conditional
#   class Foo
#     if 0
#       # This method is ignored
#       def xyz; end
#     end
#   end
class YARD::Handlers::Ruby::ClassConditionHandler < YARD::Handlers::Ruby::Base
  handles meta_type(:condition)
  namespace_only

  process do
    condition = parse_condition
    if condition.nil?
      # Parse both blocks if we're unsure of the condition
      parse_then_block
      parse_else_block
    elsif condition
      parse_then_block
    else
      parse_else_block
    end
  end

  protected

  # Parses the condition part of the if/unless statement
  #
  # @return [true, false, nil] true if the condition can be definitely
  #   parsed to true, false if not, and nil if the condition cannot be
  #   parsed with certainty (it's dynamic)
  def parse_condition
    condition = nil

    # Right now we can handle very simple unary conditions like:
    #   if true
    #   if false
    #   if 0
    #   if 100 (not 0)
    #   if defined? SOME_CONSTANT
    #
    # The last case will do a lookup in the registry and then one
    # in the Ruby world (using eval).
    case statement.condition.type
    when :int
      condition = statement.condition[0] != "0"
    when :defined
      # defined? keyword used, let's see if we can look up the name
      # in the registry, then we'll try using Ruby's powers. eval() is not
      # *too* dangerous here since code is not actually executed.
      arg = statement.condition.first

      if arg.type == :var_ref
        name = arg.source
        obj = YARD::Registry.resolve(namespace, name, true)

        begin
          condition = true if obj || (name && Object.instance_eval("defined? #{name}"))
        rescue SyntaxError, NameError
          condition = false
        end
      end
    when :var_ref
      var = statement.condition[0]
      if var == s(:kw, "true")
        condition = true
      elsif var == s(:kw, "false")
        condition = false
      end
    end

    # Invert an unless condition
    if statement.type == :unless || statement.type == :unless_mod
      condition = !condition unless condition.nil?
    end
    condition
  end

  def parse_then_block
    parse_block(statement.then_block, :visibility => visibility)
  end

  def parse_else_block
    if statement.else_block
      parse_block(statement.else_block, :visibility => visibility)
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/class_handler.rb000066400000000000000000000101721466601756300222050ustar00rootroot00000000000000# frozen_string_literal: true
# Handles class declarations
class YARD::Handlers::Ruby::ClassHandler < YARD::Handlers::Ruby::Base
  include YARD::Handlers::Ruby::StructHandlerMethods
  handles :class, :sclass
  namespace_only

  process do
    classname = statement[0].source.gsub(/\s/, '')
    if statement.type == :class
      superclass = parse_superclass(statement[1])
      if superclass == "Struct"
        is_a_struct = true
        superclass = struct_superclass_name(statement[1]) # refine the superclass if possible
        create_struct_superclass(superclass, statement[1])
      end
      undocsuper = statement[1] && superclass.nil?
      klass = register ClassObject.new(namespace, classname) do |o|
        o.superclass = superclass if superclass
        o.superclass.type = :class if o.superclass.is_a?(Proxy)
      end
      if is_a_struct
        parse_struct_superclass(klass, statement[1])
      elsif klass
        create_attributes(klass, members_from_tags(klass))
      end
      parse_block(statement[2], :namespace => klass)

      if undocsuper
        raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
      end
    elsif statement.type == :sclass
      if statement[0] == s(:var_ref, s(:kw, "self"))
        parse_block(statement[1], :namespace => namespace, :scope => :class)
      else
        proxy = Proxy.new(namespace, classname)

        # Allow constants to reference class names
        if ConstantObject === proxy
          if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
            proxy = Proxy.new(namespace, proxy.value)
          else
            raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
          end
        end

        if classname[0, 1] =~ /[A-Z]/
          register ClassObject.new(namespace, classname) if Proxy === proxy
          parse_block(statement[1], :namespace => proxy, :scope => :class)
        else
          raise YARD::Parser::UndocumentableError, "class '#{classname}'"
        end
      end
    else
      sig_end = (statement[1] ? statement[1].source_end : statement[0].source_end) - statement.source_start
      raise YARD::Parser::UndocumentableError, "class: #{statement.source[0..sig_end]}"
    end
  end

  private

  # Extract the parameters from the Struct.new AST node, returning them as a list
  # of strings
  #
  # @param [MethodCallNode] superclass the AST node for the Struct.new call
  # @return [Array] the member names to generate methods for
  def extract_parameters(superclass)
    members = superclass.parameters.select {|x| x && x.type == :symbol_literal }
    members.map! {|x| x.source.strip[1..-1] }
    members
  end

  def create_struct_superclass(superclass, superclass_def)
    return if superclass == "Struct"
    the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
      o.superclass = "Struct"
    end
    parse_struct_superclass(the_super, superclass_def)
    the_super
  end

  def struct_superclass_name(superclass)
    if superclass.call?
      first = superclass.parameters.first
      if first.type == :string_literal && first[0].type == :string_content && first[0].size == 1
        return "Struct::#{first[0][0][0]}"
      end
    end
    "Struct"
  end

  def parse_struct_superclass(klass, superclass)
    return unless superclass.call? && superclass.parameters
    members = extract_parameters(superclass)
    create_attributes(klass, members)
  end

  def parse_superclass(superclass)
    return nil unless superclass

    case superclass.type
    when :var_ref
      return namespace.path if superclass.first == s(:kw, "self")
      return superclass.source if superclass.first.type == :const
    when :const, :const_ref, :const_path_ref, :top_const_ref
      return superclass.source
    when :fcall, :command
      methname = superclass.method_name.source
      return superclass.parameters.first.source if methname == "DelegateClass"
      return methname if superclass.method_name.type == :const
    when :call, :command_call
      cname = superclass.namespace.source
      if cname =~ /^O?Struct$/ && superclass.method_name(true) == :new
        return cname
      end
    end
    nil
  end
end
yard-0.9.37/lib/yard/handlers/ruby/class_variable_handler.rb000066400000000000000000000007371466601756300240600ustar00rootroot00000000000000# frozen_string_literal: true
# Handles a class variable (@@variable)
class YARD::Handlers::Ruby::ClassVariableHandler < YARD::Handlers::Ruby::Base
  handles :assign
  namespace_only

  process do
    if statement[0].type == :var_field && statement[0][0].type == :cvar
      name = statement[0][0][0]
      value = statement[1].source
      register ClassVariableObject.new(namespace, name) do |o|
        o.source = statement
        o.value = value
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/comment_handler.rb000066400000000000000000000003761466601756300225470ustar00rootroot00000000000000# frozen_string_literal: true
# Handles any lone comment statement in a Ruby file
class YARD::Handlers::Ruby::CommentHandler < YARD::Handlers::Ruby::Base
  handles :comment, :void_stmt
  namespace_only

  process do
    register_docstring(nil)
  end
end
yard-0.9.37/lib/yard/handlers/ruby/constant_handler.rb000066400000000000000000000036201466601756300227310ustar00rootroot00000000000000# frozen_string_literal: true
# Handles any constant assignment
class YARD::Handlers::Ruby::ConstantHandler < YARD::Handlers::Ruby::Base
  include YARD::Handlers::Ruby::StructHandlerMethods
  handles :assign
  namespace_only

  process do
    if statement[1].call? && statement[1][0][0] == s(:const, "Struct") &&
       statement[1][2] == s(:ident, "new")
      process_structclass(statement)
    elsif statement[0].type == :var_field && statement[0][0].type == :const
      process_constant(statement)
    elsif statement[0].type == :const_path_field
      process_constant(statement)
    end
  end

  private

  def process_constant(statement)
    name = statement[0].source
    value = statement[1].source
    obj = P(namespace, name)
    if obj.is_a?(NamespaceObject) && obj.namespace == namespace
      raise YARD::Parser::UndocumentableError, "constant for existing #{obj.type} #{obj}"
    else
      ensure_loaded! obj.parent
      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
    end
  end

  def process_structclass(statement)
    lhs = statement[0][0]
    if lhs.type == :const
      klass = create_class(lhs[0], P(:Struct))
      create_attributes(klass, extract_parameters(statement[1]))
      parse_block(statement[1].block[1], :namespace => klass) unless statement[1].block.nil?
    else
      raise YARD::Parser::UndocumentableError, "Struct assignment to #{statement[0].source}"
    end
  end

  # Extract the parameters from the Struct.new AST node, returning them as a list
  # of strings
  #
  # @param [MethodCallNode] superclass the AST node for the Struct.new call
  # @return [Array] the member names to generate methods for
  def extract_parameters(superclass)
    return [] unless superclass.parameters
    members = superclass.parameters.select {|x| x && x.type == :symbol_literal }
    members.map! {|x| x.source.strip[1..-1] }
    members
  end
end
yard-0.9.37/lib/yard/handlers/ruby/decorator_handler_methods.rb000066400000000000000000000077401466601756300246140ustar00rootroot00000000000000# frozen_string_literal: true
# Helper methods to assist with processing decorators.
module YARD::Handlers::Ruby::DecoratorHandlerMethods
  # @overload process_decorator(*nodes, opts = {}, &block)
  #   Takes care of parsing method definitions passed to decorators
  #   as parameters, as well as parsing chained decorators.
  #
  #   Use this in a handler's process block.
  #
  #   @yieldparam method [YARD::CodeObjects::MethodObject] Method being decorated.
  #   @yieldparam node [YARD::Parser::Ruby::AstNode] AST node of the decorated method.
  #   @yieldparam name [Symbol] Name of the decorated method.
  #   @return [Array] Array of hashes containing :method, :node, :name.
  #     See yield params.
  #
  #   @param nodes [YARD::Parser::Ruby::AstNode] AST nodes that refer to decorated
  #     methods, like indexes of statement.parameter. Defaults to all parameters.
  #     Pass nil to specify zero parameters.
  #
  #   @option opts [:instance, :class] :scope (:instance) Scope to use for each
  #     MethodObject.
  #
  #   @option opts [true, false] :transfer_docstring Set false to disable
  #     transferring the decorator docstring to method definitions passed to the
  #     decorator as parameters.
  #
  #   @option opts [true, false] :transfer_source Set false to disable
  #     transferring the decorator source code string to method definitions
  #     passed to the decorator as parameters.
  #
  #   @example Basic Usage
  #     # Simply pass the method docs through to the method definition.
  #     process do
  #       process_decorator
  #     end
  #
  #   @example Setting a method's visibility to private.
  #     process do
  #       process_decorator :scope => :class do |method|
  #         method.visibility = :private if method.respond_to? :visibility
  #       end
  #     end
  def process_decorator(*nodes, &block)
    opts = nodes.last.is_a?(Hash) ? nodes.pop : {}

    all_nodes = statement.parameters.select do |p|
      p.is_a? YARD::Parser::Ruby::AstNode
    end

    # Parse decorator parameters (decorator chain).
    all_nodes.each do |param|
      parse_block param if param.call? || param.def?
    end

    selected_nodes =
      if nodes.empty?
        all_nodes
      elsif nodes.count == 1 && nodes.first.nil?
        []
      else
        nodes
      end

    decorated_methods = selected_nodes.map do |param|
      process_decorator_parameter param, opts, &block
    end.flatten

    # Store method nodes in decorator node.
    statement.define_singleton_method :decorators do
      decorated_methods.map {|h| h[:node] }
    end

    decorated_methods
  end

  private

  def process_decorator_parameter(node, opts = {}, &block)
    scope              = opts.fetch :scope, :instance
    transfer_docstring = opts.fetch :transfer_docstring, true
    transfer_source    = opts.fetch :transfer_source, true

    name = nil

    if node.call?
      if node.respond_to? :decorators
        return node.decorators.map do |n|
          process_decorator_parameter n, opts, &block
        end
      end
    elsif node.def?
      name = node.jump(:def).method_name.source
    else
      name = node.jump(:ident, :string_content, :const).source
    end

    if name.nil?
      raise YARD::Parser::UndocumentableError, 'statement, cannot determine method name'
    end

    method = YARD::CodeObjects::Proxy.new(
      namespace,
      (scope == :instance ? '#' : '.') + name.to_s,
      :method
    )

    # Transfer source to methods passed to the helper as parameters.
    method.source = statement.source if transfer_source && node.def?

    # Transfer decorator docstring to methods passed to the helper as parameters.
    if transfer_docstring && node.def? &&
       statement.docstring && method.docstring.empty?
      tags = method.tags if method.respond_to? :tags
      tags ||= []
      method.docstring = statement.docstring
      tags.each {|t| method.add_tag t }
    end

    yield method, node, name.to_sym if block_given?

    [{:method => method, :node => node, :name => name.to_sym}]
  end
end
yard-0.9.37/lib/yard/handlers/ruby/dsl_handler.rb000066400000000000000000000005241466601756300216620ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module Ruby
      # Handles automatic detection of dsl-style methods
      class DSLHandler < Base
        include CodeObjects
        include DSLHandlerMethods
        handles method_call
        namespace_only
        process { handle_comments }
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/dsl_handler_methods.rb000066400000000000000000000056611466601756300234140ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module Ruby
      module DSLHandlerMethods
        include CodeObjects
        include Parser

        IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor
          attr_reader attr_writer extend include module_function public private
          protected private_constant private_class_method public_class_method).
          map {|n| [n, true] }.flatten]

        def handle_comments
          return if IGNORE_METHODS[caller_method]

          @docstring = statement.comments || ""
          @docstring = @docstring.join("\n") if @docstring.is_a?(Array)

          attaching = false
          if @docstring =~ /^@!?macro\s+\[[^\]]*attach/
            register_docstring(nil)
            @docstring = ""
            attaching = true
          end

          macro = find_attached_macro
          if macro
            txt = macro.expand([caller_method, *call_params], statement.source)
            @docstring += "\n" + txt

            # macro may have a directive
            return register_docstring(nil) if !attaching && txt.match(/^\s*@!/)
          elsif !statement.comments_hash_flag && !implicit_docstring?
            return register_docstring(nil)
          end

          # ignore DSL definitions if @method/@attribute directive is used
          if @docstring =~ /^@!?(method|attribute)\b/
            return register_docstring(nil)
          end

          register MethodObject.new(namespace, method_name, scope) do |o|
            o.signature = method_signature
          end
        end

        def register_docstring(object, docstring = @docstring, stmt = statement)
          super
        end

        private

        def implicit_docstring?
          tags = %w(method attribute overload visibility scope return)
          tags.any? {|tag| @docstring =~ /^@!?#{tag}\b/ }
        end

        def method_name
          name = call_params.first || ""
          if name =~ /^#{CodeObjects::METHODNAMEMATCH}$/
            name
          else
            raise UndocumentableError, "method, missing name"
          end
        end

        def method_signature
          "def #{method_name}"
        end

        def find_attached_macro
          Registry.all(:macro).each do |macro|
            next unless macro.method_object
            next unless macro_name_matches(macro)
            (namespace.inheritance_tree(true) + [P('Object')]).each do |obj|
              return macro if obj == macro.method_object.namespace
            end
          end
          nil
        end

        # @return [Boolean] whether caller method matches a macro or
        #   its alias names.
        def macro_name_matches(macro)
          objs = [macro.method_object]
          if objs.first.type != :proxy && objs.first.respond_to?(:aliases)
            objs.concat(objs.first.aliases)
          end

          objs.any? {|obj| obj.name.to_s == caller_method.to_s }
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/exception_handler.rb000066400000000000000000000015311466601756300230750ustar00rootroot00000000000000# frozen_string_literal: true
# Handles 'raise' calls inside methods
class YARD::Handlers::Ruby::ExceptionHandler < YARD::Handlers::Ruby::Base
  handles method_call(:raise)

  process do
    return unless owner.is_a?(MethodObject) # Only methods yield
    return if [:command_call, :call].include? statement.type
    return if owner.has_tag?(:raise)

    klass = nil
    if statement.call?
      params = statement.parameters(false)
      if params.size == 1
        if params.first.ref? && params.first.first.type != :ident
          klass = params.first.source
        elsif params.first.call? && params.first.method_name(true) == :new
          klass = params.first.namespace.source
        end
      elsif params.size > 1
        klass = params.first.source
      end
    end

    owner.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
  end
end
yard-0.9.37/lib/yard/handlers/ruby/extend_handler.rb000066400000000000000000000010571466601756300223710ustar00rootroot00000000000000# frozen_string_literal: true
# Handles 'extend' call to include modules into the class scope of another
# @see MixinHandler
class YARD::Handlers::Ruby::ExtendHandler < YARD::Handlers::Ruby::MixinHandler
  handles method_call(:extend)
  namespace_only

  def scope; :class end

  private

  def process_mixin(mixin)
    if mixin == s(:var_ref, s(:kw, "self"))
      if namespace.is_a?(ClassObject)
        raise UndocumentableError, "extend(self) statement on class"
      end
      namespace.mixins(scope) << namespace
    else
      super
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/000077500000000000000000000000001466601756300203215ustar00rootroot00000000000000yard-0.9.37/lib/yard/handlers/ruby/legacy/alias_handler.rb000066400000000000000000000026141466601756300234370ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::AliasHandler)
class YARD::Handlers::Ruby::Legacy::AliasHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\Aalias(_method)?(\s|\()/)
  namespace_only

  process do
    if TkALIAS === statement.tokens.first
      tokens = statement.tokens[2..-1].to_s.split(/\s+/)
      names = [tokens[0], tokens[1]].map {|t| t.gsub(/^:(['"])?(.+?)\1?$|^(:)(.+)/, '\2') }
    else
      names = tokval_list(statement.tokens[2..-1], :attr)
    end
    raise YARD::Parser::UndocumentableError, statement.tokens.first.text if names.size != 2

    names = names.map {|n| Symbol === n ? n.to_s.delete('"') : n }
    new_meth = names[0].to_sym
    old_meth = names[1].to_sym
    old_obj = namespace.child(:name => old_meth, :scope => scope)
    new_obj = register MethodObject.new(namespace, new_meth, scope) do |o|
      o.add_file(parser.file, statement.tokens.first.line_no, statement.comments)
    end

    if old_obj
      new_obj.signature = old_obj.signature
      new_obj.source = old_obj.source
      new_obj.docstring = old_obj.docstring + YARD::Docstring.new(statement.comments)
      new_obj.docstring.line_range = statement.comments_range
      new_obj.docstring.hash_flag = statement.comments_hash_flag
      new_obj.docstring.object = new_obj
    else
      new_obj.signature = "def #{new_meth}" # this is all we know.
    end

    namespace.aliases[new_obj] = old_meth
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/attribute_handler.rb000066400000000000000000000041761466601756300243560ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::AttributeHandler)
class YARD::Handlers::Ruby::Legacy::AttributeHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\Aattr(?:_(?:reader|writer|accessor))?(?:\s|\()/)
  namespace_only

  process do
    begin
      attr_type   = statement.tokens.first.text.to_sym
      symbols     = tokval_list statement.tokens[2..-1], :attr, TkTRUE, TkFALSE
      read = true
      write = false
    rescue SyntaxError
      raise YARD::Parser::UndocumentableError, attr_type
    end

    # Change read/write based on attr_reader/writer/accessor
    case attr_type
    when :attr
      # In the case of 'attr', the second parameter (if given) isn't a symbol.
      write = symbols.pop if symbols.size == 2
    when :attr_accessor
      write = true
    when :attr_reader
      # change nothing
    when :attr_writer
      read = false
      write = true
    end

    # Add all attributes
    symbols.each do |name|
      namespace.attributes[scope][name] = SymbolHash[:read => nil, :write => nil]

      # Show their methods as well
      {:read => name, :write => "#{name}="}.each do |type, meth|
        if type == :read ? read : write
          o = MethodObject.new(namespace, meth, scope)
          if type == :write
            o.parameters = [['value', nil]]
            src = "def #{meth}(value)"
            full_src = "#{src}\n  @#{name} = value\nend"
            doc = "Sets the attribute #{name}\n@param value the value to set the attribute #{name} to."
          else
            src = "def #{meth}"
            full_src = "#{src}\n  @#{name}\nend"
            doc = "Returns the value of attribute #{name}"
          end
          o.source ||= full_src
          o.signature ||= src
          register(o)
          o.docstring = doc if o.docstring.blank?(false)

          # Register the object explicitly
          namespace.attributes[scope][name][type] = o
        else
          obj = namespace.children.find {|other| other.name == meth.to_sym && other.scope == scope }

          # register an existing method as attribute
          namespace.attributes[scope][name][type] = obj if obj
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/base.rb000066400000000000000000000223051466601756300215620ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module Ruby::Legacy
      # This is the base handler for the legacy parser. To implement a legacy
      # handler, subclass this class.
      #
      # @abstract (see Ruby::Base)
      class Base < Handlers::Base
        # For tokens like TkDEF, TkCLASS, etc.
        include YARD::Parser::Ruby::Legacy::RubyToken

        # @return [Boolean] whether or not a {Parser::Ruby::Legacy::Statement} object should be handled
        #   by this handler.
        def self.handles?(stmt)
          handlers.any? do |a_handler|
            case a_handler
            when String
              stmt.tokens.first.text == a_handler
            when Regexp
              stmt.tokens.to_s =~ a_handler
            else
              a_handler == stmt.tokens.first.class
            end
          end
        end

        # Parses a statement's block with a set of state values. If the
        # statement has no block, nothing happens. A description of state
        # values can be found at {Handlers::Base#push_state}
        #
        # @param [Hash] opts State options
        # @option opts (see Handlers::Base#push_state)
        # @see Handlers::Base#push_state #push_state
        def parse_block(opts = {})
          push_state(opts) do
            if statement.block
              blk = Parser::Ruby::Legacy::StatementList.new(statement.block)
              parser.process(blk)
            end
          end
        end

        def call_params
          if statement.tokens.first.is_a?(TkDEF)
            extract_method_details.last.map(&:first)
          else
            tokens = statement.tokens[1..-1]
            tokval_list(tokens, :attr, :identifier, TkId).map(&:to_s)
          end
        end

        def caller_method
          if statement.tokens.first.is_a?(TkIDENTIFIER)
            statement.tokens.first.text
          elsif statement.tokens.first.is_a?(TkDEF)
            extract_method_details.first
          end
        end

        private

        # Extracts method information for macro expansion only
        #
        # @todo This is a duplicate implementation of {MethodHandler}. Refactor.
        # @return [Array>>] the method name followed by method
        #   arguments (name and optional value)
        def extract_method_details
          if statement.tokens.to_s =~ /^def\s+(#{METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
            meth = $1
            args = $2
            meth.gsub!(/\s+/, '')
            args = tokval_list(Parser::Ruby::Legacy::TokenList.new(args), :all)
            args.map! {|a| k, v = *a.split('=', 2); [k.strip, (v ? v.strip : nil)] } if args
            meth = $` if meth =~ /(?:#{NSEPQ}|#{CSEPQ})([^#{NSEP}#{CSEPQ}]+)$/
            [meth, args]
          end
        end

        # The string value of a token. For example, the return value for the symbol :sym
        # would be :sym. The return value for a string +"foo #{ bar}"+ would be the literal
        # +"foo #{ bar}"+ without any interpolation. The return value of the identifier
        # 'test' would be the same value: 'test'. Here is a list of common types and
        # their return values:
        #
        # @example
        #   tokval(TokenList.new('"foo"').first) => "foo"
        #   tokval(TokenList.new(':foo').first) => :foo
        #   tokval(TokenList.new('CONSTANT').first, RubyToken::TkId) => "CONSTANT"
        #   tokval(TokenList.new('identifier').first, RubyToken::TkId) => "identifier"
        #   tokval(TokenList.new('3.25').first) => 3.25
        #   tokval(TokenList.new('/xyz/i').first) => /xyz/i
        #
        # @param [Token] token The token of the class
        #
        # @param [Array>, Symbol] accepted_types
        #   The allowed token types that this token can be. Defaults to [{TkVal}].
        #   A list of types would be, for example, [+TkSTRING+, +TkSYMBOL+], to return
        #   the token's value if it is either of those types. If +TkVal+ is accepted,
        #   +TkNode+ is also accepted.
        #
        #   Certain symbol keys are allowed to specify multiple types in one fell swoop.
        #   These symbols are:
        #     :string       => +TkSTRING+, +TkDSTRING+, +TkDXSTRING+ and +TkXSTRING+
        #     :attr         => +TkSYMBOL+ and +TkSTRING+
        #     :identifier   => +TkIDENTIFIER, +TkFID+ and +TkGVAR+.
        #     :number       => +TkFLOAT+, +TkINTEGER+
        #
        # @return [Object] if the token is one of the accepted types, in its real value form.
        #   It should be noted that identifiers and constants are kept in String form.
        # @return [nil] if the token is not any of the specified accepted types
        def tokval(token, *accepted_types)
          accepted_types = [TkVal] if accepted_types.empty?
          accepted_types.push(TkNode) if accepted_types.include? TkVal

          if accepted_types.include?(:attr)
            accepted_types.push(TkSTRING, TkSYMBOL)
          end

          if accepted_types.include?(:string)
            accepted_types.push(TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING)
          end

          if accepted_types.include?(:identifier)
            accepted_types.push(TkIDENTIFIER, TkFID, TkGVAR)
          end

          if accepted_types.include?(:number)
            accepted_types.push(TkFLOAT, TkINTEGER)
          end

          return unless accepted_types.any? {|t| t === token }

          case token
          when TkSTRING, TkDSTRING, TkXSTRING, TkDXSTRING
            token.text[1..-2]
          when TkSYMBOL
            token.text[1..-1].to_sym
          when TkFLOAT
            token.text.to_f
          when TkINTEGER
            token.text.to_i
          when TkREGEXP
            token.text =~ %r{\A/(.+)/([^/])\Z}
            Regexp.new($1, $2)
          when TkTRUE
            true
          when TkFALSE
            false
          when TkNIL
            nil
          else
            token.text
          end
        end

        # Returns a list of symbols or string values from a statement.
        # The list must be a valid comma delimited list, and values
        # will only be returned to the end of the list only.
        #
        # Example:
        #   attr_accessor :a, 'b', :c, :d => ['a', 'b', 'c', 'd']
        #   attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c']
        #
        # The tokval list of a {Parser::Ruby::Legacy::TokenList} of the above
        # code would be the {#tokval} value of :a, 'b',
        # :c and :d.
        #
        # It should also be noted that this function stops immediately at
        # any ruby keyword encountered:
        #   "attr_accessor :a, :b, :c if x == 5"  => ['a', 'b', 'c']
        #
        # @param [TokenList] tokenlist The list of tokens to process.
        # @param [Array>] accepted_types passed to {#tokval}
        # @return [Array] the list of tokvalues in the list.
        # @return [Array] if there are no symbols or Strings in the list
        # @see #tokval
        def tokval_list(tokenlist, *accepted_types)
          return [] unless tokenlist
          out = [[]]
          parencount = 0
          beforeparen = 0
          needcomma = false
          seen_comma = true
          tokenlist.each do |token|
            tokval = accepted_types == [:all] ? token.text : tokval(token, *accepted_types)
            parencond = !out.last.empty? && !tokval.nil?
            # puts "#{seen_comma.inspect} #{parencount} #{token.class.class_name} #{out.inspect}"
            case token
            when TkCOMMA
              if parencount == 0
                out << [] unless out.last.empty?
                needcomma = false
                seen_comma = true
              elsif parencond
                out.last << token.text
              end
            when TkLPAREN
              if seen_comma
                beforeparen += 1
              else
                parencount += 1
                out.last << token.text if parencond
              end
            when TkRPAREN
              if beforeparen > 0
                beforeparen -= 1
              else
                out.last << token.text if parencount > 0 && !tokval.nil?
                parencount -= 1
              end
            when TkLBRACE, TkLBRACK, TkDO
              parencount += 1
              out.last << token.text unless tokval.nil?
            when TkRBRACE, TkRBRACK, TkEND
              out.last << token.text unless tokval.nil?
              parencount -= 1
            else
              break if TkKW === token && ![TkTRUE, TkFALSE, TkSUPER, TkSELF, TkNIL].include?(token.class)

              seen_comma = false unless TkWhitespace === token
              if parencount == 0
                next if needcomma
                next if TkWhitespace === token
                if !tokval.nil?
                  out.last << tokval
                else
                  out.last.clear
                  needcomma = true
                end
              elsif parencond
                needcomma = true
                out.last << token.text
              end
            end

            break if beforeparen == 0 && parencount < 0
          end
          # Flatten any single element lists
          out.map {|e| e.empty? ? nil : (e.size == 1 ? e.pop : e.flatten.join) }.compact
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/class_condition_handler.rb000066400000000000000000000044311466601756300255200ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ClassConditionHandler)
# @since 0.5.4
class YARD::Handlers::Ruby::Legacy::ClassConditionHandler < YARD::Handlers::Ruby::Legacy::Base
  namespace_only
  handles TkIF, TkELSIF, TkUNLESS

  process do
    condition = parse_condition
    if condition.nil?
      # Parse both blocks if we're unsure of the condition
      parse_then_block
      parse_else_block
    elsif condition
      parse_then_block
    else
      parse_else_block
    end
  end

  protected

  # Parses the condition part of the if/unless statement
  #
  # @return [true, false, nil] true if the condition can be definitely
  #   parsed to true, false if not, and nil if the condition cannot be
  #   parsed with certainty (it's dynamic)
  # @since 0.5.5
  def parse_condition
    condition = nil

    # Right now we can handle very simple unary conditions like:
    #   if true
    #   if false
    #   if 0
    #   if 100 (not 0)
    #   if defined? SOME_CONSTANT
    #
    # The last case will do a lookup in the registry and then one
    # in the Ruby world (using eval).
    case statement.tokens[1..-1].to_s.strip
    when /^(\d+)$/
      condition = $1 != "0"
    when /^defined\?\s*\(?\s*([A-Za-z0-9:_]+?)\s*\)?$/
      # defined? keyword used, let's see if we can look up the name
      # in the registry, then we'll try using Ruby's powers. eval() is not
      # *too* dangerous here since code is not actually executed.
      name = $1
      obj = YARD::Registry.resolve(namespace, name, true)
      begin
        condition = true if obj || Object.instance_eval("defined? #{name}")
      rescue SyntaxError, NameError
        condition = false
      end
    when "true"
      condition = true
    when "false"
      condition = false
    end

    if TkUNLESS === statement.tokens.first
      condition = !condition unless condition.nil?
    end
    condition
  end

  # @since 0.5.5
  def parse_then_block
    parse_block(:visibility => visibility)
  end

  # @since 0.5.5
  def parse_else_block
    return unless statement.block
    stmtlist = YARD::Parser::Ruby::Legacy::StatementList
    stmtlist.new(statement.block).each do |stmt|
      next unless TkELSE === stmt.tokens.first
      push_state(:visibility => visibility) do
        parser.process(stmtlist.new(stmt.block))
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/class_handler.rb000066400000000000000000000074131466601756300234550ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ClassHandler)
class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy::Base
  include YARD::Handlers::Ruby::StructHandlerMethods
  handles TkCLASS
  namespace_only

  process do
    if statement.tokens.to_s =~ /^class\s+(#{NAMESPACEMATCH})\s*(?:<\s*(.+)|\Z)/m
      classname = $1
      superclass_def = $2
      superclass = parse_superclass($2)
      classname = classname.gsub(/\s/, '')
      if superclass == "Struct"
        is_a_struct = true
        superclass = struct_superclass_name(superclass_def)
        create_struct_superclass(superclass, superclass_def)
      end
      undocsuper = superclass_def && superclass.nil?

      klass = register ClassObject.new(namespace, classname) do |o|
        o.superclass = superclass if superclass
        o.superclass.type = :class if o.superclass.is_a?(Proxy)
      end
      if is_a_struct
        parse_struct_subclass(klass, superclass_def)
      elsif klass
        create_attributes(klass, members_from_tags(klass))
      end
      parse_block(:namespace => klass)

      if undocsuper
        raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
      end
    elsif statement.tokens.to_s =~ /^class\s*<<\s*([\w\:\s]+)/
      classname = $1.gsub(/\s/, '')
      proxy = Proxy.new(namespace, classname)

      # Allow constants to reference class names
      if ConstantObject === proxy
        if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
          proxy = Proxy.new(namespace, proxy.value)
        else
          raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
        end
      end

      if classname == "self"
        parse_block(:namespace => namespace, :scope => :class)
      elsif classname[0, 1] =~ /[A-Z]/
        register ClassObject.new(namespace, classname) if Proxy === proxy
        parse_block(:namespace => proxy, :scope => :class)
      else
        raise YARD::Parser::UndocumentableError, "class '#{classname}'"
      end
    else
      raise YARD::Parser::UndocumentableError, "class: #{statement.tokens}"
    end
  end

  private

  # Extracts the parameter list from the Struct.new declaration and returns it
  # formatted as a list of member names. Expects the user will have used symbols
  # to define the struct member names
  #
  # @param [String] superstring the string declaring the superclass
  # @return [Array] a list of member names
  def extract_parameters(superstring)
    paramstring = superstring.match(/\A(O?Struct)\.new\((.*?)\)/)[2]
    paramstring.split(",").select {|x| x.strip[0, 1] == ":" }.map {|x| x.strip[1..-1] } # the 1..-1 chops the leading :
  end

  def create_struct_superclass(superclass, superclass_def)
    return if superclass == "Struct"
    the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
      o.superclass = "Struct"
    end
    parse_struct_subclass(the_super, superclass_def)
    the_super
  end

  def struct_superclass_name(superclass)
    match = superclass.match(/\A(Struct)\.new\((.*?)\)/)
    if match
      paramstring = match[2].split(",")
      first = paramstring.first.strip
      if first[0, 1] =~ /['"]/ && first[-1, 1] =~ /['"]/ && first !~ /\#\{/
        return "Struct::#{first[1..-2]}"
      end
    end
    "Struct"
  end

  def parse_struct_subclass(klass, superclass_def)
    # Bounce if there's no parens
    return unless superclass_def =~ /O?Struct\.new\((.*?)\)/
    members = extract_parameters(superclass_def)
    create_attributes(klass, members)
  end

  def parse_superclass(superclass)
    case superclass
    when /\A(#{NAMESPACEMATCH})(?:\s|\Z)/,
         /\A(Struct|OStruct)\.new/,
         /\ADelegateClass\((.+?)\)\s*\Z/,
         /\A(#{NAMESPACEMATCH})\(/
      $1
    when "self"
      namespace.path
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/class_variable_handler.rb000066400000000000000000000006751466601756300253250ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ClassVariableHandler)
class YARD::Handlers::Ruby::Legacy::ClassVariableHandler < YARD::Handlers::Ruby::Legacy::Base
  HANDLER_MATCH = /\A@@\w+\s*=\s*/m
  handles HANDLER_MATCH
  namespace_only

  process do
    name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
    register ClassVariableObject.new(namespace, name) do |o|
      o.source = statement
      o.value = value.strip
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/comment_handler.rb000066400000000000000000000003541466601756300240070ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::CommentHandler)
class YARD::Handlers::Ruby::Legacy::CommentHandler < YARD::Handlers::Ruby::Legacy::Base
  handles TkCOMMENT
  namespace_only

  process do
    register_docstring(nil)
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/constant_handler.rb000066400000000000000000000016141466601756300241760ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ConstantHandler)
class YARD::Handlers::Ruby::Legacy::ConstantHandler < YARD::Handlers::Ruby::Legacy::Base
  include YARD::Handlers::Ruby::StructHandlerMethods
  HANDLER_MATCH = /\A[A-Z]\w*\s*=[^=]\s*/m
  handles HANDLER_MATCH
  namespace_only

  process do
    name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
    if value =~ /\A\s*Struct.new(?:\s*\(?|\b)/
      process_structclass(name, $')
    else
      register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
    end
  end

  private

  def process_structclass(classname, parameters)
    klass = create_class(classname, P(:Struct))
    create_attributes(klass, extract_parameters(parameters))
  end

  def extract_parameters(parameters)
    members = tokval_list(YARD::Parser::Ruby::Legacy::TokenList.new(parameters), TkSYMBOL)
    members.map(&:to_s)
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/dsl_handler.rb000066400000000000000000000005511466601756300231260ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module Ruby
      module Legacy
        # (see Ruby::DSLHandler)
        class DSLHandler < Base
          include CodeObjects
          include DSLHandlerMethods
          handles TkIDENTIFIER
          namespace_only
          process { handle_comments }
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/exception_handler.rb000066400000000000000000000007741466601756300243510ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ExceptionHandler)
class YARD::Handlers::Ruby::Legacy::ExceptionHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\Araise(\s|\(|\Z)/)

  process do
    return unless owner.is_a?(MethodObject) # Only methods yield
    return if owner.has_tag?(:raise)

    klass = statement.tokens.to_s[/^raise[\(\s]*(#{NAMESPACEMATCH})\s*(?:\)|,|\s(?:if|unless|until)|;|(?:(?:\.|\:\:)\s*)?new|$)/, 1]
    owner.add_tag YARD::Tags::Tag.new(:raise, '', klass) if klass
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/extend_handler.rb000066400000000000000000000007451466601756300236400ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ExtendHandler)
class YARD::Handlers::Ruby::Legacy::ExtendHandler < YARD::Handlers::Ruby::Legacy::MixinHandler
  handles(/\Aextend(\s|\()/)
  namespace_only

  def scope; :class end

  private

  def process_mixin(mixin)
    if mixin == "self"
      if namespace.is_a?(ClassObject)
        raise UndocumentableError, "extend(self) statement on class"
      end
      namespace.mixins(scope) << namespace
    else
      super
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/method_handler.rb000066400000000000000000000055311466601756300236270ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::MethodHandler)
class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy::Base
  handles TkDEF

  process do
    nobj = namespace
    mscope = scope

    if statement.tokens.to_s =~ /^def\s+(#{METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
      meth = $1
      args = $2
      meth.gsub!(/\s+/, '')
      args = tokval_list(YARD::Parser::Ruby::Legacy::TokenList.new(args), :all)
      args.map! do |a|
        k, v, r = *a.split(/(:)|=/, 2)
        if r
          k += v
          v = r
        end
        [k.strip, (v ? v.strip : nil)]
      end if args
    else
      raise YARD::Parser::UndocumentableError, "method: invalid name"
    end

    # Class method if prefixed by self(::|.) or Module(::|.)
    if meth =~ /(?:#{NSEPQ}|#{CSEPQ})([^#{NSEP}#{CSEPQ}]+)$/
      mscope = :class
      meth = $1
      prefix = $`
      if prefix =~ /^[a-z]/ && prefix != "self"
        raise YARD::Parser::UndocumentableError, 'method defined on object instance'
      end
      nobj = P(namespace, prefix) unless prefix == "self"
    end

    nobj = P(namespace, nobj.value) while nobj.type == :constant
    obj = register MethodObject.new(nobj, meth, mscope) do |o|
      o.explicit = true
      o.parameters = args
    end

    # delete any aliases referencing old method
    nobj.aliases.each do |aobj, name|
      next unless name == obj.name
      nobj.aliases.delete(aobj)
    end if nobj.is_a?(NamespaceObject)

    if mscope == :instance && meth == "initialize"
      unless obj.has_tag?(:return)
        obj.add_tag(YARD::Tags::Tag.new(:return,
          "a new instance of #{namespace.name}", namespace.name.to_s))
      end
    elsif mscope == :class && obj.docstring.blank? && %w(inherited included
        extended method_added method_removed method_undefined).include?(meth)
      obj.add_tag(YARD::Tags::Tag.new(:private, nil))
    elsif meth.to_s =~ /\?$/
      if obj.tag(:return) && (obj.tag(:return).types || []).empty?
        obj.tag(:return).types = ['Boolean']
      elsif obj.tag(:return).nil?
        unless obj.tags(:overload).any? {|overload| overload.tag(:return) }
          obj.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
        end
      end
    end

    if obj.has_tag?(:option)
      # create the options parameter if its missing
      obj.tags(:option).each do |option|
        expected_param = option.name
        unless obj.tags(:param).find {|x| x.name == expected_param }
          new_tag = YARD::Tags::Tag.new(:param, "a customizable set of options", "Hash", expected_param)
          obj.add_tag(new_tag)
        end
      end
    end

    info = obj.attr_info
    if info
      if meth.to_s =~ /=$/ # writer
        info[:write] = obj if info[:read]
      elsif info[:write]
        info[:read] = obj
      end
    end

    parse_block(:owner => obj) # mainly for yield/exceptions
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/mixin_handler.rb000066400000000000000000000022201466601756300234630ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::MixinHandler)
class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\Ainclude(\s|\()/)
  namespace_only

  process do
    errors = []
    statement.tokens[1..-1].to_s.split(/\s*,\s*/).reverse.each do |mixin|
      mixin = mixin.strip
      begin
        process_mixin(mixin)
      rescue YARD::Parser::UndocumentableError => err
        errors << err.message
      end
    end

    unless errors.empty?
      msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
      raise YARD::Parser::UndocumentableError, "mixin#{msg} for class #{namespace.path}"
    end
  end

  private

  def process_mixin(mixin)
    mixmatch = mixin[/\A(#{NAMESPACEMATCH})/, 1]
    raise YARD::Parser::UndocumentableError unless mixmatch

    case obj = Proxy.new(namespace, mixmatch)
    when ConstantObject # If a constant is included, use its value as the real object
      obj = Proxy.new(namespace, obj.value, :module)
    else
      obj = Proxy.new(namespace, mixmatch, :module)
    end

    namespace.mixins(scope).unshift(obj) unless namespace.mixins(scope).include?(obj)
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/module_function_handler.rb000066400000000000000000000011431466601756300255340ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ModuleFunctionHandler)
class YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\A(module_function)(\s|\(|$)/)
  namespace_only

  process do
    if statement.tokens.size == 1
      self.scope = :module
    else
      tokval_list(statement.tokens[2..-1], :attr).each do |name|
        instance_method = MethodObject.new(namespace, name)
        class_method = MethodObject.new(namespace, name, :module)
        instance_method.copy_to(class_method)
        class_method.visibility = :public
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/module_handler.rb000066400000000000000000000005601466601756300236310ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::ModuleHandler)
class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base
  handles TkMODULE
  namespace_only

  process do
    modname = statement.tokens.to_s[/^module\s+(#{NAMESPACEMATCH})/, 1]
    mod = register ModuleObject.new(namespace, modname)
    parse_block(:namespace => mod)
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/private_class_method_handler.rb000066400000000000000000000012101466601756300265340ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::PrivateClassMethodHandler)
class YARD::Handlers::Ruby::Legacy::PrivateClassMethodHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\Aprivate_class_method(\s|\(|$)/)
  namespace_only

  process do
    tokval_list(statement.tokens[2..-1], :attr).each do |name|
      privatize_class_method name
    end
  end

  private

  def privatize_class_method(name)
    method = Proxy.new(namespace, name)
    ensure_loaded!(method)
    method.visibility = :private
  rescue YARD::Handlers::NamespaceMissingError
    raise UndocumentableError, "private visibility set on unrecognized method: #{name}"
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/private_constant_handler.rb000066400000000000000000000011611466601756300257250ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::PrivateConstantHandler)
class YARD::Handlers::Ruby::Legacy::PrivateConstantHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\Aprivate_constant(\s|\(|$)/)
  namespace_only

  process do
    tokval_list(statement.tokens[2..-1], :attr, TkCONSTANT).each do |name|
      privatize_constant name
    end
  end

  private

  def privatize_constant(name)
    const = Proxy.new(namespace, name)
    ensure_loaded!(const)
    const.visibility = :private
  rescue NamespaceMissingError
    raise UndocumentableError, "private visibility set on unrecognized constant: #{name}"
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/visibility_handler.rb000066400000000000000000000010001466601756300245210ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::VisibilityHandler)
class YARD::Handlers::Ruby::Legacy::VisibilityHandler < YARD::Handlers::Ruby::Legacy::Base
  handles(/\A(protected|private|public)(\s|\(|$)/)
  namespace_only

  process do
    vis = statement.tokens.first.text
    if statement.tokens.size == 1
      self.visibility = vis
    else
      tokval_list(statement.tokens[2..-1], :attr).each do |name|
        MethodObject.new(namespace, name, scope) {|o| o.visibility = vis }
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/legacy/yield_handler.rb000066400000000000000000000020361466601756300234520ustar00rootroot00000000000000# frozen_string_literal: true
# (see Ruby::YieldHandler)
class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy::Base
  handles TkYIELD

  process do
    return unless owner.is_a?(MethodObject) # Only methods yield
    return if owner.has_tag? :yield         # Don't override yield tags
    return if owner.has_tag? :yieldparam    # Same thing.

    yieldtag = YARD::Tags::Tag.new(:yield, "", [])
    tokval_list(statement.tokens[2..-1], Token).each do |item|
      item = item.inspect unless item.is_a?(String)
      if item == "self"
        yieldtag.types << '_self'
        owner.add_tag YARD::Tags::Tag.new(:yieldparam,
          "the object that the method was called on", owner.namespace.path, '_self')
      elsif item == "super"
        yieldtag.types << '_super'
        owner.add_tag YARD::Tags::Tag.new(:yieldparam,
          "the result of the method from the superclass", nil, '_super')
      else
        yieldtag.types << item
      end
    end

    owner.add_tag(yieldtag) unless yieldtag.types.empty?
  end
end
yard-0.9.37/lib/yard/handlers/ruby/method_condition_handler.rb000066400000000000000000000004041466601756300244230ustar00rootroot00000000000000# frozen_string_literal: true
# Handles a conditional inside a method
class YARD::Handlers::Ruby::MethodConditionHandler < YARD::Handlers::Ruby::Base
  handles :if_mod, :unless_mod

  process do
    parse_block(statement.then_block, :owner => owner)
  end
end
yard-0.9.37/lib/yard/handlers/ruby/method_handler.rb000066400000000000000000000057031466601756300223640ustar00rootroot00000000000000# frozen_string_literal: true
# Handles a method definition
class YARD::Handlers::Ruby::MethodHandler < YARD::Handlers::Ruby::Base
  include YARD::Handlers::Common::MethodHandler

  handles :def, :defs

  process do
    meth = statement.method_name(true).to_s
    args = format_args
    blk = statement.block
    nobj = namespace
    mscope = scope
    if statement.type == :defs
      if statement[0][0].type == :ident
        raise YARD::Parser::UndocumentableError, 'method defined on object instance'
      end
      nobj = P(namespace, statement[0].source) if statement[0][0].type == :const
      mscope = :class
    end

    nobj = P(namespace, nobj.value) while nobj.type == :constant
    obj = register MethodObject.new(nobj, meth, mscope) do |o|
      o.explicit = true
      o.parameters = args
    end

    # delete any aliases referencing old method
    nobj.aliases.each do |aobj, name|
      next unless name == obj.name
      nobj.aliases.delete(aobj)
    end if nobj.is_a?(NamespaceObject)

    if obj.constructor?
      unless obj.has_tag?(:return)
        obj.add_tag(YARD::Tags::Tag.new(:return,
          "a new instance of #{namespace.name}", namespace.name.to_s))
      end
    elsif mscope == :class && obj.docstring.blank? && %w(inherited included
        extended method_added method_removed method_undefined).include?(meth)
      obj.add_tag(YARD::Tags::Tag.new(:private, nil))
    elsif meth.to_s =~ /\?$/
      add_predicate_return_tag(obj)
    end

    if obj.has_tag?(:option)
      # create the options parameter if its missing
      obj.tags(:option).each do |option|
        expected_param = option.name
        unless obj.tags(:param).find {|x| x.name == expected_param }
          new_tag = YARD::Tags::Tag.new(:param, "a customizable set of options", "Hash", expected_param)
          obj.add_tag(new_tag)
        end
      end
    end

    info = obj.attr_info
    if info
      if meth.to_s =~ /=$/ # writer
        info[:write] = obj if info[:read]
      elsif info[:write]
        info[:read] = obj
      end
    end

    parse_block(blk, :owner => obj) # mainly for yield/exceptions
  end

  def format_args
    return [] unless args = statement.parameters

    params = []

    if args.unnamed_required_params
      params += args.unnamed_required_params.map {|a| [a.source, nil] }
    end

    if args.unnamed_optional_params
      params += args.unnamed_optional_params.map do |a|
        [a[0].source, a[1].source]
      end
    end

    params << ['*' + args.splat_param.source, nil] if args.splat_param

    if args.unnamed_end_params
      params += args.unnamed_end_params.map {|a| [a.source, nil] }
    end

    if args.named_params
      params += args.named_params.map do |a|
        [a[0].source, a[1] ? a[1].source : nil]
      end
    end

    if args.double_splat_param
      params << ['**' + args.double_splat_param.source, nil]
    end

    params << ['&' + args.block_param.source, nil] if args.block_param && !args.args_forward

    params
  end
end
yard-0.9.37/lib/yard/handlers/ruby/mixin_handler.rb000066400000000000000000000035071466601756300222300ustar00rootroot00000000000000# frozen_string_literal: true
# Handles the 'include' statement to mixin a module in the instance scope
class YARD::Handlers::Ruby::MixinHandler < YARD::Handlers::Ruby::Base
  handles method_call(:include)
  handles method_call(:prepend)
  namespace_only

  process do
    errors = []
    statement.parameters(false).reverse.each do |mixin|
      begin
        process_mixin(mixin)
      rescue YARD::Parser::UndocumentableError => err
        errors << err.message
      end
    end
    unless errors.empty?
      msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
      raise YARD::Parser::UndocumentableError, "mixin#{msg} for class #{namespace.path}"
    end
  end

  protected

  def process_mixin(mixin)
    raise YARD::Parser::UndocumentableError unless mixin.ref?
    raise YARD::Parser::UndocumentableError if mixin.first.type == :ident

    if mixin.type == :var_ref && mixin[0] == s(:kw, "self")
      obj = namespace
    else
      case obj = Proxy.new(namespace, mixin.source)
      when ConstantObject # If a constant is included, use its value as the real object
        obj = Proxy.new(namespace, obj.value, :module)
      else
        obj = Proxy.new(namespace, mixin.source, :module)
      end
    end

    rec = recipient(mixin)
    return if rec.nil?

    ensure_loaded!(rec)
    return if rec.mixins(scope).include?(obj)

    shift = statement.method_name(true) == :include ? :unshift : :push
    rec.mixins(scope).send(shift, obj)
  end

  def recipient(mixin)
    if statement[0].type == :const_path_ref || statement[0].type == :top_const_ref
      Proxy.new(namespace, statement[0].source)
    elsif statement[0].type == :var_ref && statement[0][0] != s(:kw, "self")
      statement[0][0].type == :const ?
        Proxy.new(namespace, statement.namespace.source) :
        nil
    else
      namespace
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/module_function_handler.rb000066400000000000000000000023161466601756300242730ustar00rootroot00000000000000# frozen_string_literal: true
# Handles module_function calls to turn methods into public class methods.
# Also creates a private instance copy of the method.
class YARD::Handlers::Ruby::ModuleFunctionHandler < YARD::Handlers::Ruby::Base
  include YARD::Handlers::Ruby::DecoratorHandlerMethods

  handles method_call(:module_function)
  namespace_only

  process do
    return if statement.jump(:ident) == statement
    case statement.type
    when :var_ref, :vcall
      self.scope = :module
    when :fcall, :command
      statement[1].traverse do |node|
        case node.type
        when :def
          process_decorator do |instance_method|
            make_module_function(instance_method, namespace)
          end
          break
        when :symbol; name = node.first.source
        when :string_content; name = node.source
        else next
        end

        instance_method = MethodObject.new(namespace, name)
        make_module_function(instance_method, namespace)
      end
    end
  end

  def make_module_function(instance_method, namespace)
    class_method = MethodObject.new(namespace, instance_method.name, :module)
    instance_method.copy_to(class_method)
    class_method.visibility = :public
  end
end
yard-0.9.37/lib/yard/handlers/ruby/module_handler.rb000066400000000000000000000005211466601756300223620ustar00rootroot00000000000000# frozen_string_literal: true
# Handles the declaration of a module
class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base
  handles :module
  namespace_only

  process do
    modname = statement[0].source
    mod = register ModuleObject.new(namespace, modname)
    parse_block(statement[1], :namespace => mod)
  end
end
yard-0.9.37/lib/yard/handlers/ruby/private_class_method_handler.rb000066400000000000000000000006611466601756300253010ustar00rootroot00000000000000# frozen_string_literal: true
# Sets visibility of a class method to private.
class YARD::Handlers::Ruby::PrivateClassMethodHandler < YARD::Handlers::Ruby::Base
  include YARD::Handlers::Ruby::DecoratorHandlerMethods

  handles method_call(:private_class_method)
  namespace_only

  process do
    process_decorator :scope => :class do |method|
      method.visibility = :private if method.respond_to? :visibility=
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/private_constant_handler.rb000066400000000000000000000026021466601756300244620ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Handlers
    module Ruby
      # Sets visibility of a constant (class, module, const)
      class PrivateConstantHandler < YARD::Handlers::Ruby::Base
        handles method_call(:private_constant)
        namespace_only

        process do
          errors = []
          statement.parameters.each do |param|
            next unless AstNode === param
            begin
              privatize_constant(param)
            rescue UndocumentableError => err
              errors << err.message
            end
          end
          unless errors.empty?
            msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
            raise UndocumentableError, "private constant#{msg} for #{namespace.path}"
          end
        end

        private

        def privatize_constant(node)
          if node.literal? || (node.type == :var_ref && node[0].type == :const)
            node = node.jump(:tstring_content, :const)
            const = Proxy.new(namespace, node[0])
            ensure_loaded!(const)
            const.visibility = :private
          else
            raise UndocumentableError, "invalid argument to private_constant: #{node.source}"
          end
        rescue NamespaceMissingError
          raise UndocumentableError, "private visibility set on unrecognized constant: #{node[0]}"
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/public_class_method_handler.rb000066400000000000000000000006541466601756300251070ustar00rootroot00000000000000# frozen_string_literal: true
# Sets visibility of a class method to public.
class YARD::Handlers::Ruby::PublicClassMethodHandler < YARD::Handlers::Ruby::Base
  include YARD::Handlers::Ruby::DecoratorHandlerMethods

  handles method_call(:public_class_method)
  namespace_only

  process do
    process_decorator :scope => :class do |method|
      method.visibility = :public if method.respond_to? :visibility
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/struct_handler_methods.rb000066400000000000000000000153441466601756300241550ustar00rootroot00000000000000# frozen_string_literal: true
# Helper methods to parse @attr_* tags on a class.
#
# @deprecated The use of +@attr+ tags are deprecated since 0.8.0 in favour of
#   the +@!attribute+ directive. This module should not be relied on.
# @since 0.5.6
module YARD::Handlers::Ruby::StructHandlerMethods
  include YARD::CodeObjects

  # Extracts the user's defined @member tag for a given class and its member. Returns
  # nil if the user did not define a @member tag for this struct entry.
  #
  # @param [ClassObject] klass the class whose tags we're searching
  # @param [String] member the name of the struct member we need
  # @param [Symbol] type reader method, or writer method?
  # @return [Tags::Tag, nil] the tag matching the request, or nil if not found
  def member_tag_for_member(klass, member, type = :read)
    specific_tag = type == :read ? :attr_reader : :attr_writer
    (klass.tags(specific_tag) + klass.tags(:attr)).find {|tag| tag.name == member }
  end

  # Retrieves all members defined in @attr* tags
  #
  # @param [ClassObject] klass the class with the attributes
  # @return [Array] the list of members defined as attributes on the class
  def members_from_tags(klass)
    tags = klass.tags(:attr) + klass.tags(:attr_reader) + klass.tags(:attr_writer)
    tags.map(&:name).uniq
  end

  # Determines whether to create an attribute method based on the class's
  # tags.
  #
  # @param [ClassObject] klass the class whose tags we're searching
  # @param [String] member the name of the struct member we need
  # @param [Symbol] type (:read) reader method, or writer method?
  # @return [Boolean] should the attribute be created?
  def create_member_method?(klass, member, type = :read)
    return true if (klass.tags(:attr) + klass.tags(:attr_reader) + klass.tags(:attr_writer)).empty?
    return true if member_tag_for_member(klass, member, type)
    return !member_tag_for_member(klass, member, :write) if type == :read
    !member_tag_for_member(klass, member, :read)
  end

  # Gets the return type for the member in a nicely formatted string. Used
  # to be injected into auto-generated docstrings.
  #
  # @param [Tags::Tag] member_tag the tag object to check for types
  # @return [String] the user-declared type of the struct member, or [Object] if
  #   the user did not define a type for this member.
  def return_type_from_tag(member_tag)
    member_tag && member_tag.types ? member_tag.types : "Object"
  end

  # Creates the auto-generated docstring for the getter method of a struct's
  # member. This is used so the generated documentation will look just like that
  # of an attribute defined using attr_accessor.
  #
  # @param [ClassObject] klass the class whose members we're working with
  # @param [String] member the name of the member we're generating documentation for
  # @return [String] a docstring to be attached to the getter method for this member
  def add_reader_tags(klass, new_method, member)
    member_tag = member_tag_for_member(klass, member, :read)
    return_type = return_type_from_tag(member_tag)
    getter_doc_text = member_tag ? member_tag.text : "Returns the value of attribute #{member}"
    new_method.docstring.replace(getter_doc_text)
    new_method.add_tag YARD::Tags::Tag.new(:return, "the current value of #{member}", return_type)
  end

  # Creates the auto-generated docstring for the setter method of a struct's
  # member. This is used so the generated documentation will look just like that
  # of an attribute defined using attr_accessor.
  #
  # @param [ClassObject] klass the class whose members we're working with
  # @param [String] member the name of the member we're generating documentation for
  # @return [String] a docstring to be attached to the setter method for this member
  def add_writer_tags(klass, new_method, member)
    member_tag = member_tag_for_member(klass, member, :write)
    return_type = return_type_from_tag(member_tag)
    setter_doc_text = member_tag ? member_tag.text : "Sets the attribute #{member}"
    new_method.docstring.replace(setter_doc_text)
    new_method.add_tag YARD::Tags::Tag.new(:param, "the value to set the attribute #{member} to.", return_type, "value")
    new_method.add_tag YARD::Tags::Tag.new(:return, "the newly set value", return_type)
  end

  # Creates and registers a class object with the given name and superclass name.
  # Returns it for further use.
  #
  # @param [String] classname the name of the class
  # @param [String] superclass the name of the superclass
  # @return [ClassObject] the class object for further processing/method attaching
  def create_class(classname, superclass)
    register ClassObject.new(namespace, classname) do |o|
      o.superclass = superclass if superclass
      o.superclass.type = :class if o.superclass.is_a?(Proxy)
    end
  end

  # Creates the setter (writer) method and attaches it to the class as an attribute.
  # Also sets up the docstring to prettify the documentation output.
  #
  # @param [ClassObject] klass the class to attach the method to
  # @param [String] member the name of the member we're generating a method for
  def create_writer(klass, member)
    # We want to convert these members into attributes just like
    # as if they were declared using attr_accessor.
    new_meth = register MethodObject.new(klass, "#{member}=", :instance) do |o|
      o.parameters = [['value', nil]]
      o.signature ||= "def #{member}=(value)"
      o.source ||= "#{o.signature}\n  @#{member} = value\nend"
    end
    add_writer_tags(klass, new_meth, member)
    klass.attributes[:instance][member][:write] = new_meth
  end

  # Creates the getter (reader) method and attaches it to the class as an attribute.
  # Also sets up the docstring to prettify the documentation output.
  #
  # @param [ClassObject] klass the class to attach the method to
  # @param [String] member the name of the member we're generating a method for
  def create_reader(klass, member)
    new_meth = register MethodObject.new(klass, member, :instance) do |o|
      o.signature ||= "def #{member}"
      o.source ||= "#{o.signature}\n  @#{member}\nend"
    end
    add_reader_tags(klass, new_meth, member)
    klass.attributes[:instance][member][:read] = new_meth
  end

  # Creates the given member methods and attaches them to the given ClassObject.
  #
  # @param [ClassObject] klass the class to generate attributes for
  # @param [Array] members a list of member names
  def create_attributes(klass, members)
    # For each parameter, add reader and writers
    members.each do |member|
      next if klass.attributes[:instance][member]
      klass.attributes[:instance][member] = SymbolHash[:read => nil, :write => nil]
      create_writer klass, member if create_member_method?(klass, member, :write)
      create_reader klass, member if create_member_method?(klass, member, :read)
    end
  end
end
yard-0.9.37/lib/yard/handlers/ruby/visibility_handler.rb000066400000000000000000000021311466601756300232630ustar00rootroot00000000000000# frozen_string_literal: true
# Handles 'private', 'protected', and 'public' calls.
class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
  include YARD::Handlers::Ruby::DecoratorHandlerMethods

  handles method_call(:private)
  handles method_call(:protected)
  handles method_call(:public)
  namespace_only

  process do
    return if (ident = statement.jump(:ident)) == statement
    case statement.type
    when :var_ref, :vcall
      self.visibility = ident.first.to_sym
    when :command
      if RUBY_VERSION >= '3.' && is_attribute_method?(statement.parameters.first)
        parse_block(statement.parameters.first, visibility: ident.first.to_sym)
        return
      end
      process_decorator do |method|
        method.visibility = ident.first if method.respond_to? :visibility=
      end
    when :fcall
      process_decorator do |method|
        method.visibility = ident.first if method.respond_to? :visibility=
      end
    end
  end

  def is_attribute_method?(node)
    node.type == :command && node.jump(:ident).first.to_s =~ /^attr_(accessor|writer|reader)$/
  end
end
yard-0.9.37/lib/yard/handlers/ruby/yield_handler.rb000066400000000000000000000020641466601756300222070ustar00rootroot00000000000000# frozen_string_literal: true
# Handles 'yield' calls
class YARD::Handlers::Ruby::YieldHandler < YARD::Handlers::Ruby::Base
  handles :yield, :yield0

  process do
    return unless owner.is_a?(MethodObject) # Only methods yield
    return if owner.has_tag? :yield         # Don't override yield tags
    return if owner.has_tag? :yieldparam    # Same thing.

    yieldtag = YARD::Tags::Tag.new(:yield, "", [])

    if statement.type == :yield
      statement.jump(:list).children.each do |item|
        if item == s(:var_ref, s(:kw, "self"))
          yieldtag.types << '_self'
          owner.add_tag YARD::Tags::Tag.new(:yieldparam,
            "the object that the method was called on", owner.namespace.path, '_self')
        elsif item == s(:zsuper)
          yieldtag.types << '_super'
          owner.add_tag YARD::Tags::Tag.new(:yieldparam,
            "the result of the method from the superclass", nil, '_super')
        else
          yieldtag.types << item.source
        end
      end
    end

    owner.add_tag(yieldtag) unless yieldtag.types.empty?
  end
end
yard-0.9.37/lib/yard/i18n/000077500000000000000000000000001466601756300150535ustar00rootroot00000000000000yard-0.9.37/lib/yard/i18n/locale.rb000066400000000000000000000034601466601756300166420ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module I18n
    # +Locale+ is a unit of translation. It has {#name} and a set of
    # messages.
    #
    # @since 0.8.2
    class Locale
      class << self
        # @return [String, nil] the default locale name.
        # @since 0.8.4
        attr_accessor :default

        undef default
        def default
          @@default ||= nil
        end

        undef default=
        def default=(locale)
          @@default = locale
        end
      end

      # @return [String] the name of the locale. It used IETF language
      #   tag format +[language[_territory][.codeset][@modifier]]+.
      # @see http://tools.ietf.org/rfc/bcp/bcp47.txt
      #   BCP 47 - Tags for Identifying Languages
      attr_reader :name

      # Creates a locale for +name+ locale.
      #
      # @param [String] name the locale name.
      def initialize(name)
        @name = name
        @messages = {}
      end

      # Loads translation messages from +locale_directory+/{#name}.po.
      #
      # @param [String] locale_directory the directory path that has
      #   {#name}.po.
      # @return [Boolean] +true+ if PO file exists, +false+ otherwise.
      def load(locale_directory)
        return false if @name.nil?

        po_file = File.join(locale_directory, "#{@name}.po")
        return false unless File.exist?(po_file)

        require "yard/i18n/po_parser"
        return false unless POParser.available?

        po_parser = POParser.new
        @messages.merge!(po_parser.parse(po_file))

        true
      end

      # @param [String] message the translation target message.
      # @return [String] translated message. If translation isn't
      #   registered, the +message+ is returned.
      def translate(message)
        @messages[message] || message
      end
    end
  end
end
yard-0.9.37/lib/yard/i18n/message.rb000066400000000000000000000032611466601756300170260ustar00rootroot00000000000000# frozen_string_literal: true
require "set"

module YARD
  module I18n
    # +Message+ is a translation target message. It has message ID as
    # {#id} and some properties {#locations} and {#comments}.
    #
    # @since 0.8.1
    class Message
      # @return [String] the message ID of the translation target message.
      attr_reader :id

      # @return [Set] the set of locations. Location is an array of
      # path and line number where the message is appeared.
      attr_reader :locations

      # @return [Set] the set of comments for the messages.
      attr_reader :comments

      # Creates a translate target message for message ID +id+.
      #
      # @param [String] id the message ID of the translate target message.
      def initialize(id)
        @id = id
        @locations = Set.new
        @comments = Set.new
      end

      # Adds location information for the message.
      #
      # @param [String] path the path where the message appears.
      # @param [Integer] line the line number where the message appears.
      # @return [void]
      def add_location(path, line)
        @locations << [path, line]
      end

      # Adds a comment for the message.
      #
      # @param [String] comment the comment for the message to be added.
      # @return [void]
      def add_comment(comment)
        @comments << comment unless comment.nil?
      end

      # @param [Message] other the +Message+ to be compared.
      # @return [Boolean] checks whether this message is equal to another.
      def ==(other)
        other.is_a?(self.class) &&
          @id == other.id &&
          @locations == other.locations &&
          @comments == other.comments
      end
    end
  end
end
yard-0.9.37/lib/yard/i18n/messages.rb000066400000000000000000000030501466601756300172050ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module I18n
    # Acts as a container for {Message} objects.
    #
    # @since 0.8.1
    class Messages
      include Enumerable

      # Creates a new container.
      def initialize
        @messages = {}
      end

      # Enumerates each {Message} in the container.
      #
      # @yieldparam [Message] message the next message object in
      #   the enumeration.
      # @return [void]
      def each(&block)
        @messages.each_value(&block)
      end

      # @param [String] id the message ID to perform a lookup on.
      # @return [Message, nil] a registered message for the given +id+,
      #   or nil if no message for the ID is found.
      def [](id)
        @messages[id]
      end

      # Registers a {Message}, the message ID of which is +id+. If
      # corresponding +Message+ is already registered, the previously
      # registered object is returned.
      #
      # @param [String] id the ID of the message to be registered.
      # @return [Message] the registered +Message+.
      def register(id)
        @messages[id] ||= Message.new(id)
      end

      # Checks if this messages list is equal to another messages list.
      #
      # @param [Messages] other the container to compare.
      # @return [Boolean] whether +self+ and +other+ is equivalence or not.
      def ==(other)
        other.is_a?(self.class) &&
          @messages == other.messages
      end

      protected

      # @return [Hash{String=>Message}] the set of message objects
      attr_reader :messages
    end
  end
end
yard-0.9.37/lib/yard/i18n/po_parser.rb000066400000000000000000000032121466601756300173700ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module I18n
    # +Locale+ is a wrapper for gettext's PO parsing feature. It hides
    # gettext API difference from YARD.
    #
    # @since 0.8.8
    class POParser
      if RUBY_VERSION < "1.9"
        begin
          require "gettext/tools/poparser"
          require "gettext/runtime/mofile"
          @@gettext_version = 2
        rescue LoadError
          log.warn "Need gettext gem 2.x for i18n feature:\n" \
                   "\tgem install gettext -v 2.3.9"
        end
      else
        begin
          require "gettext/po_parser"
          require "gettext/mo"
          @@gettext_version = 3
        rescue LoadError
          begin
            require "gettext/tools/poparser"
            require "gettext/runtime/mofile"
            @@gettext_version = 2
          rescue LoadError
            log.warn "Need gettext gem for i18n feature:\n" \
                     "\tgem install gettext"
          end
        end
      end

      class << self
        # @return [Boolean] true if gettext is available, false otherwise.
        def available?
          !@@gettext_version.nil?
        end
      end

      # Parses PO file.
      #
      # @param [String] file path of PO file to be parsed.
      # @return [Hash] parsed messages.
      def parse(file)
        case @@gettext_version
        when 2
          parser = GetText::PoParser.new
          data = GetText::MoFile.new
        when 3
          parser = GetText::POParser.new
          data = GetText::MO.new
        end
        parser.report_warning = false
        parser.parse_file(file, data)
        data
      end
    end
  end
end
yard-0.9.37/lib/yard/i18n/pot_generator.rb000066400000000000000000000230571466601756300202570ustar00rootroot00000000000000# frozen_string_literal: true
require "stringio"

module YARD
  module I18n
    # The +PotGenerator+ generates POT format string from
    # {CodeObjects::Base} and {CodeObjects::ExtraFileObject}.
    #
    # == POT and PO
    #
    # POT is an acronym for "Portable Object Template". POT is a
    # template file to create PO file. The extension for POT is
    # ".pot". PO file is an acronym for "Portable Object". PO file has
    # many parts of message ID (msgid) that is translation target
    # message and message string (msgstr) that is translated message
    # of message ID. If you want to translate "Hello" in English into
    # "Bonjour" in French, "Hello" is the msgid ID and "Bonjour" is
    # msgstr. The extension for PO is ".po".
    #
    # == How to extract msgids
    #
    # The +PotGenerator+ has two parse methods:
    #
    # * {#parse_objects} for {CodeObjects::Base}
    # * {#parse_files} for {CodeObjects::ExtraFileObject}
    #
    # {#parse_objects} extracts msgids from docstring and tags of
    # {CodeObjects::Base} objects. The docstring of
    # {CodeObjects::Base} object is parsed and a paragraph is
    # extracted as a msgid. Tag name and tag text are extracted as
    # msgids from a tag.
    #
    # {#parse_files} extracts msgids from
    # {CodeObjects::ExtraFileObject} objects. The file content of
    # {CodeObjects::ExtraFileObject} object is parsed and a paragraph
    # is extracted as a msgid.
    #
    # == Usage
    #
    # To create a .pot file by +PotGenerator+, instantiate a
    # +PotGenerator+ with a relative working directory path from a
    # directory path that has created .pot file, parse
    # {CodeObjects::Base} objects and {CodeObjects::ExtraFileObject}
    # objects, generate a POT and write the generated POT to a .pot
    # file. The relative working directory path is ".." when the
    # working directory path is "."  and the POT is wrote into
    # "po/yard.pot".
    #
    # @example Generate a .pot file
    #   po_file_path = "po/yard.pot"
    #   po_file_directory_pathname = Pathname.new(po_file_path).directory)
    #   working_directory_pathname = Pathname.new(".")
    #   relative_base_path = working_directory_pathname.relative_path_from(po_file_directory_pathname).to_s
    #   # relative_base_path -> ".."
    #   generator = YARD::I18n::PotGenerator.new(relative_base_path)
    #   generator.parse_objects(objects)
    #   generator.parse_files(files)
    #   pot = generator.generate
    #   po_file_directory_pathname.mkpath
    #   File.open(po_file_path, "w") do |pot_file|
    #     pot_file.print(pot)
    #   end
    # @see http://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
    #   GNU gettext manual about details of PO file
    class PotGenerator
      # Extracted messages.
      #
      # @return [Messages]
      # @since 0.8.1
      attr_reader :messages

      # Creates a POT generator that uses +relative_base_path+ to
      # generate locations for a msgid. +relative_base_path+ is
      # prepended to all locations.
      #
      # @param [String] relative_base_path a relative working
      #   directory path from a directory path that has created .pot
      #   file.
      def initialize(relative_base_path)
        @relative_base_path = relative_base_path
        @extracted_objects = {}
        @messages = Messages.new
      end

      # Parses {CodeObjects::Base} objects and stores extracted msgids
      # into {#messages}
      #
      # @param [Array] objects a list of
      #   {CodeObjects::Base} to be parsed.
      # @return [void]
      def parse_objects(objects)
        objects.each do |object|
          extract_documents(object)
        end
      end

      # Parses {CodeObjects::ExtraFileObject} objects and stores
      # extracted msgids into {#messages}.
      #
      # @param [Array] files a list
      #   of {CodeObjects::ExtraFileObject} objects to be parsed.
      # @return [void]
      def parse_files(files)
        files.each do |file|
          extract_paragraphs(file)
        end
      end

      # Generates POT from +@messages+.
      #
      # One PO file entry is generated from a +Message+ in
      # +@messages+.
      #
      # Locations of the +Message+ are used to generate the reference
      # line that is started with "#: ". +relative_base_path+ passed
      # when the generator is created is prepended to each path in location.
      #
      # Comments of the +Message+ are used to generate the
      # translator-comment line that is started with "# ".
      #
      # @return [String] POT format string
      def generate
        pot = String.new(header)
        sorted_messages = @messages.sort_by do |message|
          sorted_locations = message.locations.sort
          sorted_locations.first || []
        end
        sorted_messages.each do |message|
          generate_message(pot, message)
        end
        pot
      end

      private

      def header
        <<-EOH
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR , YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\\n"
"Report-Msgid-Bugs-To: \\n"
"POT-Creation-Date: #{generate_pot_creation_date_value}\\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\\n"
"Last-Translator: FULL NAME \\n"
"Language-Team: LANGUAGE \\n"
"Language: \\n"
"MIME-Version: 1.0\\n"
"Content-Type: text/plain; charset=UTF-8\\n"
"Content-Transfer-Encoding: 8bit\\n"

EOH
      end

      def current_time
        @current_time ||= Time.now
      end

      def generate_pot_creation_date_value
        current_time.strftime("%Y-%m-%d %H:%M%z")
      end

      def generate_message(pot, message)
        message.comments.sort.each do |comment|
          pot << "# #{comment}\n" unless comment.empty?
        end
        message.locations.sort.each do |path, line|
          pot << "#: #{@relative_base_path}/#{path}:#{line}\n"
        end
        escaped_message_id = escape_message_id(message.id)
        escaped_message_id = escaped_message_id.gsub(/\n/, "\\\\n\"\n\"")
        pot << "msgid \"#{escaped_message_id}\"\n"
        pot << "msgstr \"\"\n"
        pot << "\n"
        pot
      end

      def escape_message_id(message_id)
        message_id.gsub(/(\\|")/) do
          special_character = $1
          "\\#{special_character}"
        end
      end

      def register_message(id)
        @messages.register(id)
      end

      def extract_documents(object)
        return if @extracted_objects.key?(object)

        @extracted_objects[object] = true
        case object
        when CodeObjects::NamespaceObject
          object.children.each do |child|
            extract_documents(child)
          end
        end

        if object.group
          message = register_message(object.group)
          object.files.each do |path, line|
            message.add_location(path, line)
          end
          message.add_comment(object.path) unless object.path.empty?
        end

        docstring = object.docstring
        unless docstring.empty?
          text = Text.new(StringIO.new(docstring))
          text.extract_messages do |type, *args|
            case type
            when :paragraph
              paragraph, line_no = *args
              message = register_message(paragraph.rstrip)
              object.files.each do |path, line|
                message.add_location(path, (docstring.line || line) + line_no)
              end
              message.add_comment(object.path) unless object.path.empty?
            else
              raise "should not reach here: unexpected type: #{type}"
            end
          end
        end
        docstring.tags.each do |tag|
          extract_tag_documents(tag)
        end
      end

      def extract_tag_documents(tag)
        extract_tag_name(tag)
        extract_tag_text(tag)

        extract_documents(tag) if Tags::OverloadTag === tag
      end

      def extract_tag_name(tag)
        return if tag.name.nil?
        return if tag.name.is_a?(String) && tag.name.empty?
        key = "tag|#{tag.tag_name}|#{tag.name}"
        message = register_message(key)
        tag.object.files.each do |path, line|
          message.add_location(path, line)
        end
        tag_label = String.new("@#{tag.tag_name}")
        tag_label << " [#{tag.types.join(', ')}]" if tag.types
        message.add_comment(tag_label)
      end

      def extract_tag_text(tag)
        return if tag.text.nil?
        return if tag.text.empty?
        message = register_message(tag.text)
        tag.object.files.each do |path, line|
          message.add_location(path, line)
        end
        tag_label = String.new("@#{tag.tag_name}")
        tag_label << " [#{tag.types.join(', ')}]" if tag.types
        tag_label << " #{tag.name}" if tag.name
        message.add_comment(tag_label)
      end

      def extract_paragraphs(file)
        File.open(file.filename) do |input|
          text = Text.new(input, :have_header => true)
          text.extract_messages do |type, *args|
            case type
            when :attribute
              name, value, line_no = *args
              message = register_message(value)
              message.add_location(file.filename, line_no)
              message.add_comment(name)
            when :paragraph
              paragraph, line_no = *args
              message = register_message(paragraph.rstrip)
              message.add_location(file.filename, line_no)
            else
              raise "should not reach here: unexpected type: #{type}"
            end
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/i18n/text.rb000066400000000000000000000124641466601756300163730ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module I18n
    # Provides some convenient features for translating a text.
    class Text
      # Creates a text object that has translation related features for
      # the input text.
      #
      # @param [#each_line] input a text to be translated.
      # @option options [Boolean] :have_header (false) whether the
      #   input text has header or not.
      def initialize(input, options = {})
        @input = input
        @options = options
      end

      # Extracts translation target messages from +@input+.
      #
      # @yield [:attribute, name, value, line_no] the block that
      #   receives extracted an attribute in header. It may called many
      #   times.
      # @yieldparam [String] name the name of extracted attribute.
      # @yieldparam [String] value the value of extracted attribute.
      # @yieldparam [Integer] line_no the defined line number of extracted
      #   attribute.
      # @yield [:paragraph, text, start_line_no] the block that
      #   receives extracted a paragraph in body. Paragraph is a text
      #   block separated by one or more empty lines. Empty line is a
      #   line that contains only zero or more whitespaces. It may
      #   called many times.
      # @yieldparam [String] text the text of extracted paragraph.
      # @yieldparam [Integer] start_line_no the start line number of
      #   extracted paragraph.
      # @return [void]
      def extract_messages
        parse do |part|
          case part[:type]
          when :markup, :empty_line
            # ignore
          when :attribute
            yield(:attribute, part[:name], part[:value], part[:line_no])
          when :paragraph
            yield(:paragraph, part[:paragraph], part[:line_no])
          end
        end
      end

      # Translates into +locale+.
      #
      # @param [Locale] locale the translation target locale.
      # @return [String] translated text.
      def translate(locale)
        translated_text = String.new("")
        parse do |part|
          case part[:type]
          when :markup
            translated_text << part[:line]
          when :attribute
            prefix = "#{part[:prefix]}#{part[:name]}#{part[:infix]}"
            value = locale.translate(part[:value])
            suffix = part[:suffix]
            translated_text << "#{prefix}#{value}#{suffix}"
          when :paragraph
            translated_text << locale.translate(part[:paragraph])
          when :empty_line
            translated_text << part[:line]
          else
            raise "should not reach here: unexpected type: #{type}"
          end
        end
        translated_text
      end

      private

      def parse(&block)
        paragraph = String.new("")
        paragraph_start_line = 0
        line_no = 0
        in_header = @options[:have_header]

        @input.each_line do |line|
          line_no += 1
          if in_header
            case line
            when /^#!\S+\s*$/
              if line_no == 1
                emit_markup_event(line, line_no, &block)
              else
                in_header = false
              end
            when /^(\s*#\s*@)(\S+)(\s*)(.+?)(\s*)$/
              emit_attribute_event(Regexp.last_match, line_no, &block)
            else
              in_header = false
              if line.strip.empty?
                emit_empty_line_event(line, line_no, &block)
                next
              end
            end
            next if in_header
          end

          case line
          when /^\s*$/
            if paragraph.empty?
              emit_empty_line_event(line, line_no, &block)
            else
              paragraph << line
              emit_paragraph_event(paragraph, paragraph_start_line, line_no,
                                   &block)
              paragraph = String.new("")
            end
          else
            paragraph_start_line = line_no if paragraph.empty?
            paragraph << line
          end
        end

        unless paragraph.empty?
          emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
        end
      end

      def emit_markup_event(line, line_no)
        part = {
          :type => :markup,
          :line => line,
          :line_no => line_no
        }
        yield(part)
      end

      def emit_attribute_event(match_data, line_no)
        part = {
          :type => :attribute,
          :prefix => match_data[1],
          :name => match_data[2],
          :infix => match_data[3],
          :value => match_data[4],
          :suffix => match_data[5],
          :line_no => line_no
        }
        yield(part)
      end

      def emit_empty_line_event(line, line_no)
        part = {
          :type => :empty_line,
          :line => line,
          :line_no => line_no
        }
        yield(part)
      end

      def emit_paragraph_event(paragraph, paragraph_start_line, line_no, &block)
        paragraph_part = {
          :type => :paragraph,
          :line_no => paragraph_start_line
        }
        match_data = /(\s*)\z/.match(paragraph)
        if match_data
          paragraph_part[:paragraph] = match_data.pre_match
          yield(paragraph_part)
          emit_empty_line_event(match_data[1], line_no, &block)
        else
          paragraph_part[:paragraph] = paragraph
          yield(paragraph_part)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/logging.rb000066400000000000000000000164731466601756300162620ustar00rootroot00000000000000# encoding: utf-8
# frozen_string_literal: true
require 'thread'

module YARD
  # Handles console logging for info, warnings and errors.
  # Uses the stdlib Logger class in Ruby for all the backend logic.
  class Logger
    # Log severity levels
    module Severity
      # Debugging log level
      DEBUG = 0

      # Information log level
      INFO = 1

      # Warning log level
      WARN = 2

      # Error log level
      ERROR = 3

      # Fatal log level
      FATAL = 4

      # Unknown log level
      UNKNOWN = 5

      # @private
      SEVERITIES = {
        DEBUG => :debug,
        INFO => :info,
        WARN => :warn,
        ERROR => :error,
        FATAL => :fatal,
        UNKNOWN => :unknown
      }
    end

    include Severity

    # The list of characters displayed beside the progress bar to indicate
    # "movement".
    # @since 0.8.2
    PROGRESS_INDICATORS = %w(⣷ ⣯ ⣟ ⡿ ⢿ ⣻ ⣽ ⣾)

    # @return [IO] the IO object being logged to
    # @since 0.8.2
    attr_accessor :io

    # @return [Boolean] whether backtraces should be shown (by default
    #   this is on).
    def show_backtraces; @show_backtraces || level == DEBUG end
    attr_writer :show_backtraces

    # @return [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the logging level
    attr_accessor :level

    # @return [Boolean] whether a warn message has been emitted. Used for status tracking.
    attr_accessor :warned

    # @return [Boolean] whether progress indicators should be shown when
    #   logging CLIs (by default this is off).
    def show_progress
      return false if YARD.ruby18? # threading is too ineffective for progress support
      return false unless io.tty? # no TTY support on IO
      return false unless level > INFO # no progress in verbose/debug modes
      @show_progress
    end
    attr_writer :show_progress

    # @!group Constructor Methods

    # The logger instance
    # @return [Logger] the logger instance
    def self.instance(pipe = STDOUT)
      @logger ||= new(pipe)
    end

    # Creates a new logger
    # @private
    def initialize(pipe, *args)
      self.io = pipe
      self.show_backtraces = true
      self.show_progress = false
      self.level = WARN
      self.warned = false
      @progress_indicator = 0
      @mutex = Mutex.new
      @progress_msg = nil
      @progress_last_update = Time.now
    end

    # @!macro [attach] logger.create_log_method
    #   @method $1(message)
    #   Logs a message with the $1 severity level.
    #   @param message [String] the message to log
    #   @see #log
    #   @return [void]
    # @private
    def self.create_log_method(name)
      severity = Severity.const_get(name.to_s.upcase)
      define_method(name) { |message| log(severity, message) }
    end

    # @!group Logging Methods

    create_log_method :info
    create_log_method :error
    create_log_method :fatal
    create_log_method :unknown

    # Changes the debug level to DEBUG if $DEBUG is set and writes a debugging message.
    create_log_method :debug

    # Remembers when a warning occurs and writes a warning message.
    create_log_method :warn

    # Logs a message with a given severity
    # @param severity [DEBUG, INFO, WARN, ERROR, FATAL, UNKNOWN] the severity level
    # @param message [String] the message to log
    def log(severity, message)
      self.level = DEBUG if $DEBUG
      return unless severity >= level

      self.warned = true if severity == WARN
      clear_line
      puts "[#{SEVERITIES[severity].to_s.downcase}]: #{message}"
    end

    # @!group Level Control Methods

    # Sets the logger level for the duration of the block
    #
    # @example
    #   log.enter_level(Logger::ERROR) do
    #     YARD.parse_string "def x; end"
    #   end
    # @param [Fixnum] new_level the logger level for the duration of the block.
    #   values can be found in Ruby's Logger class.
    # @yield the block with the logger temporarily set to +new_level+
    def enter_level(new_level = level)
      old_level = level
      self.level = new_level
      yield
    ensure
      self.level = old_level
    end

    # @!group Utility Printing Methods

    # Displays a progress indicator for a given message. This progress report
    # is only displayed on TTY displays, otherwise the message is passed to
    # the +nontty_log+ level.
    #
    # @param [String] msg the message to log
    # @param [Symbol, nil] nontty_log the level to log as if the output
    #   stream is not a TTY. Use +nil+ for no alternate logging.
    # @return [void]
    # @since 0.8.2
    def progress(msg, nontty_log = :debug)
      send(nontty_log, msg) if nontty_log
      return unless show_progress
      icon = ""
      if defined?(::Encoding)
        icon = PROGRESS_INDICATORS[@progress_indicator] + " "
      end
      @mutex.synchronize do
        print("\e[2K\e[?25l\e[1m#{icon}#{msg}\e[0m\r")
        @progress_msg = msg
        if Time.now - @progress_last_update > 0.2
          @progress_indicator += 1
          @progress_indicator %= PROGRESS_INDICATORS.size
          @progress_last_update = Time.now
        end
      end
      Thread.new do
        sleep(0.05)
        progress(msg + ".", nil) if @progress_msg == msg
      end
    end

    # Clears the progress indicator in the TTY display.
    # @return [void]
    # @since 0.8.2
    def clear_progress
      return unless show_progress
      io.write("\e[?25h\e[2K")
      @progress_msg = nil
    end

    # Displays an unformatted line to the logger output stream, adding
    # a newline.
    # @param [String] msg the message to display
    # @return [void]
    # @since 0.8.2
    def puts(msg = '')
      print("#{msg}\n")
    end

    # Displays an unformatted line to the logger output stream.
    # @param [String] msg the message to display
    # @return [void]
    # @since 0.8.2
    def print(msg = '')
      clear_line
      io.write(msg)
    end
    alias << print

    # Prints the backtrace +exc+ to the logger as error data.
    #
    # @param [Array] exc the backtrace list
    # @param [Symbol] level_meth the level to log backtrace at
    # @return [void]
    def backtrace(exc, level_meth = :error)
      return unless show_backtraces
      send(level_meth, "#{exc.class.class_name}: #{exc.message}")
      send(level_meth, "Stack trace:" +
        exc.backtrace[0..5].map {|x| "\n\t#{x}" }.join + "\n")
    end

    # @!group Benchmarking Methods

    # Captures the duration of a block of code for benchmark analysis. Also
    # calls {#progress} on the message to display it to the user.
    #
    # @todo Implement capture storage for reporting of benchmarks
    # @param [String] msg the message to display
    # @param [Symbol, nil] nontty_log the level to log as if the output
    #   stream is not a TTY. Use +nil+ for no alternate logging.
    # @yield a block of arbitrary code to benchmark
    # @return [void]
    def capture(msg, nontty_log = :debug)
      progress(msg, nontty_log)
      yield
    ensure
      clear_progress
    end

    # @!endgroup

    # Warns that the Ruby environment does not support continuations. Applies
    # to JRuby, Rubinius and MacRuby. This warning will only display once
    # per Ruby process.
    #
    # @deprecated Continuations are no longer needed by YARD 0.8.0+.
    # @return [void]
    # @private
    def warn_no_continuations
    end

    private

    def clear_line
      return unless @progress_msg
      io.write("\e[2K\r")
    end
  end
end
yard-0.9.37/lib/yard/open_struct.rb000066400000000000000000000024621466601756300171720ustar00rootroot00000000000000module YARD
  # An OpenStruct compatible struct class that allows for basic access of attributes
  # via +struct.attr_name+ and +struct.attr_name = value+.
  class OpenStruct
    def initialize(hash = {})
      @table = hash.each_pair { |k, v| [k.to_sym, v] }
    end

    # @private
    def method_missing(name, *args)
      if name.to_s.end_with?('=')
        varname = name.to_s[0..-2].to_sym
        __cache_lookup__(varname)
        send(name, args.first)
      else
        __cache_lookup__(name)
        send(name)
      end
    end

    def to_h
      @table.dup
    end

    def ==(other)
      other.is_a?(self.class) && to_h == other.to_h
    end

    def hash
      @table.hash
    end

    def dig(*keys)
      @table.dig(*keys)
    end

    def []=(key, value)
      @table[key.to_sym] = value
    end

    def [](key)
      @table[key.to_sym]
    end

    def each_pair(&block)
      @table.each_pair(&block)
    end

    def marshal_dump
      @table
    end

    def marshal_load(data)
      @table = data
    end

    private

    def __cache_lookup__(name)
      key = name.to_sym.inspect
      instance_eval <<-RUBY, __FILE__, __LINE__ + 1
        def #{name}; @table[#{key}]; end
        def #{name.to_s.sub('?','_')}=(v); @table[#{key}] = v; end unless #{key}.to_s.include?('?')
      RUBY
    end
  end
end
yard-0.9.37/lib/yard/options.rb000066400000000000000000000176271466601756300163310ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  # Generalized options class for passing around large amounts of options between objects.
  #
  # The options class exists for better visibility and documentability of options being
  # passed through to other objects. Because YARD has parser and template architectures
  # that are heavily reliant on options, it is necessary to make these option keys easily
  # visible and understood by developers. Since the options class is more than just a
  # basic Hash, the subclass can provide aliasing and convenience methods to simplify
  # option property access, and, if needed, support backward-compatibility for deprecated
  # key names.
  #
  # == Hash and OpenStruct-like Access
  #
  # Although the options class allows for Hash-like access (opts[:key]), the recommended
  # mechanism for accessing an option key will be via standard method calls on attributes
  #
  # The options class can also act as an open ended key value storage structure (like a
  # Hash or OpenStruct), and allows for setting and getting of unregistered option keys.
  # This methodology is not recommended, however, and is only supported for backward
  # compatibility inside YARD. Whenever possible, developers should define all keys used
  # by an options class.
  #
  # == Declaring Default Values
  #
  # Note that the options class can contain default value definitions for certain options,
  # but to initialize these defaults, {#reset_defaults} must be called manually after
  # initialization; the options object is always created empty until defaults are applied.
  #
  # @abstract Subclasses should define (and document) custom attributes that are expected
  #   to be made available as option keys.
  # @example Defining an Options class with custom option keys
  #   class TemplateOptions < YARD::Options
  #     # @return [Symbol] the output format to generate templates in
  #     attr_accessor :format
  #
  #     # @return [Symbol] the template to use when generating output
  #     attr_accessor :template
  #   end
  # @example Initializing default option values
  #   class TemplateOptions < YARD::Options
  #     def reset_defaults
  #       super
  #       self.format = :html
  #       self.template = :default
  #       self.highlight = true
  #       # ...
  #     end
  #   end
  # @example Using +default_attr+ to create default attributes
  #   class TemplateOptions < YARD::Options
  #     default_attr :format, :html
  #     default_attr :template, :default
  #     default_attr :highlight, true
  #   end
  # @example Deprecating an option while still supporting it
  #   class TemplateOptions < YARD::Options
  #     # @return [Boolean] if syntax highlighting should be performed on code blocks.
  #     #   Defaults to true.
  #     attr_accessor :highlight
  #
  #     # @deprecated Use {#highlight} instead.
  #     # @return [Boolean] if no syntax highlighting should be performs on code blocks.
  #     #   Defaults to false.
  #     attr_accessor :no_highlight
  #     def no_highlight=(value) @highlight = !value end
  #     def no_highlight; !highlight end
  #   end
  class Options
    # @!macro [attach] yard.default_attr
    #   @!attribute $1
    # Defines an attribute named +key+ and sets a default value for it
    #
    # @example Defining a default option key
    #   default_attr :name, 'Default Name'
    #   default_attr :time, lambda { Time.now }
    # @param [Symbol] key the option key name
    # @param [Object, Proc] default the default object value. If the default
    #   value is a proc, it is executed upon initialization.
    def self.default_attr(key, default)
      (@defaults ||= {})[key] = default
      attr_accessor(key)
    end

    # Delegates calls with Hash syntax to actual method with key name
    #
    # @example Calling on an option key with Hash syntax
    #   options[:format] # equivalent to: options.format
    # @param [Symbol, String] key the option name to access
    # @return the value of the option named +key+
    def [](key) send(key) end

    # Delegates setter calls with Hash syntax to the attribute setter with the key name
    #
    # @example Setting an option with Hash syntax
    #   options[:format] = :html # equivalent to: options.format = :html
    # @param [Symbol, String] key the option to set
    # @param [Object] value the value to set for the option
    # @return [Object] the value being set
    def []=(key, value) send("#{key}=", value) end

    # Updates values from an options hash or options object on this object.
    # All keys passed should be key names defined by attributes on the class.
    #
    # @example Updating a set of options on an Options object
    #   opts.update(:template => :guide, :type => :fulldoc)
    # @param [Hash, Options] opts
    # @return [self]
    def update(opts)
      opts = opts.to_hash if Options === opts
      opts.each do |key, value|
        self[key] = value
      end
      self
    end

    # Creates a new options object and sets options hash or object value
    # onto that object.
    #
    # @param [Options, Hash] opts
    # @return [Options] the newly created options object
    # @see #update
    def merge(opts)
      dup.update(opts)
    end

    # @return [Hash] Converts options object to an options hash. All keys
    #   will be symbolized.
    def to_hash
      opts = {}
      instance_variables.each do |ivar|
        name = ivar.to_s.sub(/^@/, '')
        opts[name.to_sym] = send(name)
      end
      opts
    end

    # Yields over every option key and value
    # @yield [key, value] every option key and value
    # @yieldparam [Symbol] key the option key
    # @yieldparam [Object] value the option value
    # @return [void]
    def each
      instance_variables.each do |ivar|
        name = ivar.to_s.sub(/^@/, '')
        yield(name.to_sym, send(name))
      end
    end

    # Inspects the object
    def inspect
      "<#{self.class}: #{to_hash.inspect}>"
    end

    # @return [Boolean] whether another Options object equals the
    #   keys and values of this options object
    def ==(other)
      case other
      when Options; to_hash == other.to_hash
      when Hash; to_hash == other
      else false
      end
    end

    # Handles setting and accessing of unregistered keys similar
    # to an OpenStruct object.
    #
    # @note It is not recommended to set and access unregistered keys on
    #   an Options object. Instead, register the attribute before using it.
    def method_missing(meth, *args, &block)
      if meth.to_s =~ /^(.+)=$/
        log.debug "Attempting to set unregistered key #{$1} on #{self.class}"
        instance_variable_set("@#{$1}", args.first)
      elsif args.empty?
        log.debug "Attempting to access unregistered key #{meth} on #{self.class}"
        instance_variable_defined?("@#{meth}") ? instance_variable_get("@#{meth}") : nil
      else
        super
      end
    end

    # Resets all values to their defaults.
    #
    # @abstract Subclasses should override this method to perform custom
    #   value initialization if not using {default_attr}. Be sure to call
    #   +super+ so that default initialization can take place.
    # @return [void]
    def reset_defaults
      names_set = {}
      self.class.ancestors.each do |klass| # look at all ancestors
        defaults =
          klass.instance_variable_defined?("@defaults") &&
          klass.instance_variable_get("@defaults")
        next unless defaults
        defaults.each do |key, value|
          next if names_set[key]
          names_set[key] = true
          self[key] = Proc === value ? value.call : value
        end
      end
    end

    # Deletes an option value for +key+
    #
    # @param [Symbol, String] key the key to delete a value for
    # @return [Object] the value that was deleted
    def delete(key)
      val = self[key]
      if instance_variable_defined?("@#{key}")
        remove_instance_variable("@#{key}")
      end
      val
    end

    def tap; yield(self); self end unless defined?(tap) # only for 1.8.6
  end
end
yard-0.9.37/lib/yard/parser/000077500000000000000000000000001466601756300155705ustar00rootroot00000000000000yard-0.9.37/lib/yard/parser/base.rb000066400000000000000000000037031466601756300170320ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser
    # Represents the abstract base parser class that parses source code in
    # a specific way. A parser should implement {#parse}, {#tokenize} and
    # {#enumerator}.
    #
    # == Registering a Custom Parser
    # To register a parser, see {SourceParser.register_parser_type}
    #
    # @abstract
    # @see #parse
    # @see #tokenize
    # @see #enumerator
    # @since 0.5.6
    class Base
      # Convenience method to create a new parser and {#parse}
      def self.parse(source, filename = nil)
        new(source, filename).parse
      end

      # This default constructor does nothing. The subclass is responsible for
      # storing the source contents and filename if they are required.
      # @param [String] source the source contents
      # @param [String] filename the name of the file if from disk
      def initialize(source, filename) # rubocop:disable Lint/UnusedMethodArgument
        raise NotImplementedError, "invalid parser implementation"
      end

      # This method should be implemented to parse the source and return itself.
      # @abstract
      # @return [Base] this method should return itself
      def parse
        raise NotImplementedError, "#{self.class} must implement #parse"
      end

      # This method should be implemented to tokenize given source
      # @abstract
      # @return [Array] a list/tree of lexical tokens
      def tokenize
        raise NotImplementedError, "#{self.class} does not support tokenization"
      end

      # This method should be implemented to return a list of semantic tokens
      # representing the source code to be post-processed. Otherwise the method
      # should return nil.
      #
      # @abstract
      # @return [Array] a list of semantic tokens representing the source code
      #   to be post-processed
      # @return [nil] if no post-processing should be done
      def enumerator
        nil
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/c/000077500000000000000000000000001466601756300160125ustar00rootroot00000000000000yard-0.9.37/lib/yard/parser/c/c_parser.rb000066400000000000000000000152521466601756300201420ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser
    module C
      class CParser < Base
        def initialize(source, file = '(stdin)')
          @file = file
          @namespaces = {}
          @content = source
          @index = 0
          @line = 1
          @state = nil
          @newline = true
          @statements = []
          @last_comment = nil
          @last_statement = nil
        end

        def parse
          parse_toplevel
          enumerator
        end

        def enumerator
          @statements
        end

        def tokenize
          raise NotImplementedError, "no tokenization support for C/C++ files"
        end

        private

        def parse_toplevel
          advance_loop do
            case char
            when /['"]/; consume_quote(char)
            when '#'; consume_directive
            when '/'; consume_comment
            when /\s/; consume_whitespace
            when '}'; advance # Skip possible C++ namespace closing brackets.
            else consume_toplevel_statement
            end
          end
        end

        def consume_quote(type = '"')
          advance
          advance_loop do
            case char
            when "\n"; advance; nextline
            when '\\'; advance(2)
            when type; advance; return
            else advance
            end
          end
        end

        def consume_directive
          return(advance) unless @newline
          @last_comment = nil
          @last_statement = nil
          advance_loop do
            if char == '\\' && nextchar =~ /[\r\n]/
              advance_loop { advance; break(nextline) if char == "\n" }
            elsif char == "\n"
              return
            end
            advance
          end
        end

        def consume_toplevel_statement
          @newline = false
          start = @index
          line = @line
          decl = consume_until(/[{;]/)
          return nil if decl =~ /\A\s*\Z/
          # Skip C++ namespace - treat content as top level statement.
          return nil if decl =~ /\A(namespace)/
          statement = ToplevelStatement.new(nil, @file, line)
          @statements << statement
          attach_comment(statement)
          stmts = nil
          if prevchar == '{'
            stmts = consume_body_statements
            if decl =~ /\A(typedef|enum|class|#{struct}|union)/
              consume_until(';')
            end
          end
          statement.source = @content[start..@index]
          statement.block = stmts
          statement.declaration = decl # rubocop:disable Lint/UselessSetterCall
        end

        def consume_body_statements
          stmts = []
          brace_level = 1
          loop do
            strip_non_statement_data
            start = @index
            line = @line
            consume_until(/[{};]/)
            brace_level += 1 if prevchar == '{'
            brace_level -= 1 if prevchar == '}'

            break if prevchar.empty? || (brace_level <= 0 && prevchar == '}')
            src = @content[start...@index]
            next unless src && src !~ /\A\s*\Z|\A\}\Z/

            stmt = BodyStatement.new(src, @file, line)
            attach_comment(stmt)
            stmts << stmt
          end
          stmts
        end

        def strip_non_statement_data
          start = @index
          loop do
            start = @index
            case char
            when /\s/; consume_whitespace
            when '#';  consume_directive
            when '/';  consume_comment
            end

            break if start == @index
          end
        end

        def consume_whitespace
          advance_loop { nextline if char == "\n"; break if char =~ /\S/; advance }
        end

        def consume_comment(add_comment = true)
          return(advance) unless nextchar == '*' || nextchar == '/'
          line = @line
          type = nextchar == '*' ? :multi : :line
          advance(2)
          comment = String.new("")
          advance_loop do
            comment << char
            if type == :multi
              nextline if char == "\n"
              if char(2) == '*/'
                if add_comment
                  comment << '/'
                  stmt = Comment.new(comment, @file, line)
                  stmt.type = type
                  attach_comment(stmt)
                  @statements << stmt
                end
                return advance(2)
              end
            elsif char == "\n"
              if add_comment
                stmt = Comment.new(comment[0...-1], @file, line)
                stmt.type = type
                attach_comment(stmt)
                @statements << stmt
              end
              return
            end
            advance
          end
        end

        def consume_until(end_char, bracket_level = 0, brace_level = 0, add_comment = true)
          end_char = /#{end_char}/ if end_char.is_a?(String)
          start = @index
          advance_loop do
            chr = char
            case chr
            when /\s/; consume_whitespace
            when /['"]/; consume_quote(char)
            when '#'; consume_directive
            when '/'; consume_comment(add_comment)
            when '{'; advance; brace_level += 1
            when '}'; advance; brace_level -= 1
            when '('; advance; bracket_level += 1
            when ')'; advance; bracket_level -= 1
            else advance
            end
            @newline = false if chr !~ /\s/

            if chr =~ end_char
              break if chr == '{' || chr == '('
              break if bracket_level <= 0 && brace_level <= 0
            end
          end
          @content[start...@index]
        end

        def attach_comment(statement)
          if Comment === statement
            if @last_statement && @last_statement.line == statement.line
              @last_statement.comments = statement
              statement.statement = @last_statement
            end
            @last_comment = statement
            @last_statement = nil
          else
            if @last_comment
              statement.comments = @last_comment
              @last_comment.statement = statement
            end
            @last_statement = statement
            @last_comment = nil
          end
        end

        def advance(num = 1) @index += num end
        def back(num = 1) @index -= num end

        def advance_loop
          yield while @index <= @content.size
        end

        def nextline
          @line += 1
          @newline = true
        end

        def char(num = 1) @content[@index, num] end
        def prevchar(num = 1) @content[@index - 1, num] end
        def nextchar(num = 1) @content[@index + 1, num] end

        def struct
          /struct\s[a-zA-Z0-9]+\s\{/
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/c/comment_parser.rb000066400000000000000000000111711466601756300213560ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser
    module C
      module CommentParser
        protected

        def parse_comments(comments)
          @overrides = []
          spaces = nil
          comments = remove_private_comments(comments)
          comments = comments.split(/\r?\n/).map do |line|
            line.gsub!(%r{^\s*/?\*/?}, '')
            line.gsub!(%r{\*/\s*$}, '')
            if line =~ /^\s*$/
              next if spaces.nil?
              next ""
            end
            spaces = (line[/^(\s+)/, 1] || "").size if spaces.nil?
            line.gsub(/^\s{0,#{spaces}}/, '').rstrip
          end.compact

          comments = parse_overrides(comments)
          comments = parse_callseq(comments)
          comments.join("\n")
        end

        private

        def parse_overrides(comments)
          comments.map do |line|
            type, name = *line.scan(/^\s*Document-(class|module|method|attr|const):\s*(\S.*)\s*$/).first
            if type
              @overrides << [type.to_sym, name]
              nil
            else
              line
            end
          end.compact
        end

        def parse_callseq(comments)
          return comments unless comments[0] =~ /\Acall-seq:\s*(\S.+)?/
          if $1
            comments[0] = " #{$1}"
          else
            comments.shift
          end
          overloads = []
          seen_data = false
          while comments.first =~ /^\s+(\S.+)/ || comments.first =~ /^\s*$/
            line = comments.shift.strip
            break if line.empty? && seen_data
            next if line.empty?
            seen_data = true
            line.sub!(/^\w+[\.#]/, '')
            signature, types = *line.split(/ [-=]> /)
            types = parse_types(types)
            if signature.sub!(/\[?\s*(\{(?:\s*\|(.+?)\|)?.*\})\s*\]?\s*$/, '') && $1
              blk = $1
              blkparams = $2
            else
              blk = nil
              blkparams = nil
            end
            case signature
            when /^(\w+)\s*=\s+(\w+)/
              signature = "#{$1}=(#{$2})"
            when /^\w+\s+\S/
              signature = signature.split(/\s+/)
              signature = "#{signature[1]}#{signature[2] ? '(' + signature[2..-1].join(' ') + ')' : ''}"
            when /^\w+\[(.+?)\]\s*(=)?/
              signature = "[]#{$2}(#{$1})"
            when /^\w+\s+(#{CodeObjects::METHODMATCH})\s+(\w+)/
              signature = "#{$1}(#{$2})"
            end
            break unless signature =~ /^#{CodeObjects::METHODNAMEMATCH}/
            signature = signature.rstrip
            overloads << "@overload #{signature}"
            overloads << "  @yield [#{blkparams}]" if blk
            overloads << "  @return [#{types.join(', ')}]" unless types.empty?
          end

          comments + [""] + overloads
        end

        def parse_types(types)
          if types =~ /true or false/
            ["Boolean"]
          else
            (types || "").split(/,| or /).map do |t|
              case t.strip.gsub(/^an?_/, '')
              when "class"; "Class"
              when "obj", "object", "anObject"; "Object"
              when "arr", "array", "anArray", "ary", "new_ary", /^\[/; "Array"
              when /^char\s*\*/, "char", "str", "string", "new_str"; "String"
              when "enum", "anEnumerator"; "Enumerator"
              when "exc", "exception"; "Exception"
              when "proc", "proc_obj", "prc"; "Proc"
              when "binding"; "Binding"
              when "hsh", "hash", "aHash"; "Hash"
              when "ios", "io"; "IO"
              when "file"; "File"
              when "float"; "Float"
              when "time", "new_time"; "Time"
              when "dir", "aDir"; "Dir"
              when "regexp", "new_regexp"; "Regexp"
              when "matchdata"; "MatchData"
              when "encoding"; "Encoding"
              when "fixnum", "fix"; "Fixnum"
              when /^(?:un)?signed$/, /^(?:(?:un)?signed\s*)?(?:short|int|long|long\s+long)$/, "integer", "Integer"; "Integer"
              when "num", "numeric", "Numeric", "number"; "Numeric"
              when "aBignum"; "Bignum"
              when "nil"; "nil"
              when "true"; "true"
              when "false"; "false"
              when "bool", "boolean", "Boolean"; "Boolean"
              when "self"; "self"
              when /^[-+]?\d/; t
              when /[A-Z][_a-z0-9]+/; t
              end
            end.compact
          end
        end

        def remove_private_comments(comment)
          comment = comment.gsub(%r{/?\*--\n(.*?)/?\*\+\+}m, '')
          comment = comment.sub(%r{/?\*--\n.*}m, '')
          comment
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/c/statement.rb000066400000000000000000000025571466601756300203540ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser
    module C
      class Statement
        attr_accessor :source
        attr_accessor :line
        attr_accessor :file

        # @deprecated Groups are now defined by directives
        # @see Tags::GroupDirective
        attr_accessor :group

        attr_accessor :comments_hash_flag

        def initialize(source, file = nil, line = nil)
          @source = source
          @file = file
          @line = line
        end

        def line_range
          line...(line + source.count("\n"))
        end

        def comments_range
          comments.line_range
        end

        def first_line
          source.split(/\n/).first
        end

        alias signature first_line

        def show
          "\t#{line}: #{first_line}"
        end
      end

      class BodyStatement < Statement
        attr_accessor :comments
      end

      class ToplevelStatement < Statement
        attr_accessor :block
        attr_accessor :declaration
        attr_accessor :comments
      end

      class Comment < Statement
        include CommentParser

        attr_accessor :type
        attr_accessor :overrides
        attr_accessor :statement

        def initialize(source, file = nil, line = nil)
          super(parse_comments(source), file, line)
        end

        def comments; self end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/000077500000000000000000000000001466601756300165515ustar00rootroot00000000000000yard-0.9.37/lib/yard/parser/ruby/ast_node.rb000066400000000000000000000415361466601756300207030ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser
    module Ruby
      # Builds and s-expression by creating {AstNode} objects with
      # the type provided by the first argument.
      #
      # @example An implicit list of keywords
      #   ast = s(s(:kw, "if"), s(:kw, "else"))
      #   ast.type # => :list
      # @example A method call
      #   s(:command, s(:var_ref, "mymethod"))
      #
      # @overload s(*nodes, opts = {})
      #   @param [Array] nodes a list of nodes.
      #   @param [Hash] opts any extra options (docstring, file, source) to
      #     set on the object
      #   @return [AstNode] an implicit node where node.type == +:list+
      # @overload s(type, *children, opts = {})
      #   @param [Symbol] type the node type
      #   @param [Array] children any child nodes inside this one
      #   @param [Hash] opts any extra options to set on the object
      #   @return [AstNode] a node of type +type+.
      # @see AstNode#initialize
      def s(*args)
        type = Symbol === args.first ? args.shift : :list
        opts = Hash === args.last ? args.pop : {}
        AstNode.node_class_for(type).new(type, args, opts)
      end

      # An AST node is characterized by a type and a list of children. It
      # is most easily represented by the s-expression {#s} such as:
      #   # AST for "if true; 5 end":
      #   s(s(:if, s(:var_ref, s(:kw, "true")), s(s(:int, "5")), nil))
      #
      # The node type is not considered part of the list, only its children.
      # So +ast[0]+ does not refer to the type, but rather the first child
      # (or object). Items that are not +AstNode+ objects can be part of the
      # list, like Strings or Symbols representing names. To return only
      # the AstNode children of the node, use {#children}.
      class AstNode < Array
        attr_accessor :docstring_hash_flag
        attr_accessor :docstring, :docstring_range, :source

        # @deprecated Groups are now defined by directives
        # @see Tags::GroupDirective
        attr_accessor :group

        attr_writer :source_range, :line_range, :file, :full_source
        alias comments docstring
        alias comments_range docstring_range
        alias comments_hash_flag docstring_hash_flag
        alias to_s source

        # @return [Symbol] the node's unique symbolic type
        attr_accessor :type

        # @return [AstNode, nil] the node's parent or nil if it is a root node.
        attr_accessor :parent

        # @return [Range] the character range in {#full_source} represented
        #   by the node
        def source_range
          reset_line_info unless @source_range
          @source_range
        end

        # @return [Range] the line range in {#full_source} represented
        #   by the node
        def line_range
          reset_line_info unless @line_range
          @line_range
        end

        # @return [String] the filename the node was parsed from
        def file
          return parent.file if parent
          @file
        end

        # @return [String] the full source that the node was parsed from
        def full_source
          return parent.full_source if parent
          return @full_source if @full_source
          return IO.read(@file) if file && File.exist?(file)
        end

        # @return [String] the parse of {#full_source} that the node represents
        def source
          return parent.full_source[source_range] if parent
          full_source
        end

        # List of all known keywords
        # @return [Hash]
        KEYWORDS = {:class => true, :alias => true, :lambda => true, :do_block => true,
          :def => true, :defs => true, :begin => true, :rescue => true, :rescue_mod => true,
          :if => true, :if_mod => true, :else => true, :elsif => true, :case => true,
          :when => true, :next => true, :break => true, :retry => true, :redo => true,
          :return => true, :throw => true, :catch => true, :until => true, :until_mod => true,
          :while => true, :while_mod => true, :yield => true, :yield0 => true, :zsuper => true,
          :unless => true, :unless_mod => true, :for => true, :super => true, :return0 => true}

        # @group Creating an AstNode

        # Finds the node subclass that should be instantiated for a specific
        # node type
        #
        # @param [Symbol] type the node type to find a subclass for
        # @return [Class] a subclass of AstNode to instantiate the node with.
        def self.node_class_for(type)
          case type
          when :params
            ParameterNode
          when :call, :fcall, :vcall, :command, :command_call
            MethodCallNode
          when :if, :elsif, :if_mod, :unless, :unless_mod
            ConditionalNode
          when :for, :while, :while_mod, :until, :until_mod
            LoopNode
          when :def, :defs
            MethodDefinitionNode
          when :class, :sclass
            ClassNode
          when :module
            ModuleNode
          else
            if type.to_s =~ /_ref\Z/
              ReferenceNode
            elsif type.to_s =~ /_literal\Z/
              LiteralNode
            elsif KEYWORDS.key?(type)
              KeywordNode
            else
              AstNode
            end
          end
        end

        # Creates a new AST node
        #
        # @param [Symbol] type the type of node being created
        # @param [Array] arr the child nodes
        # @param [Hash] opts any extra line options
        # @option opts [Fixnum] :line (nil) the line the node starts on in source
        # @option opts [String] :char (nil) the character number the node starts on
        #   in source
        # @option opts [Fixnum] :listline (nil) a special key like :line but for
        #   list nodes
        # @option opts [Fixnum] :listchar (nil) a special key like :char but for
        #   list nodes
        # @option opts [Boolean] :token (nil) whether the node represents a token
        def initialize(type, arr, opts = {})
          super(arr)
          self.type = type
          self.line_range = opts[:line]
          self.source_range = opts[:char]
          @fallback_line = opts[:listline]
          @fallback_source = opts[:listchar]
          @token = true if opts[:token]
          @docstring = nil
        end

        # @return [Boolean] whether the node is equal to another by checking
        #   the list and type
        # @private
        def ==(other)
          super && type == other.type
        end

        # @group Traversing a Node

        # Searches through the node and all descendants and returns the
        # first node with a type matching any of +node_types+, otherwise
        # returns the original node (self).
        #
        # @example Returns the first method definition in a block of code
        #   ast = YARD.parse_string("if true; def x; end end").ast
        #   ast.jump(:def)
        #   # => s(:def, s(:ident, "x"), s(:params, nil, nil, nil, nil,
        #   #      nil), s(s(:void_stmt, )))
        # @example Returns first 'def' or 'class' statement
        #   ast = YARD.parse_string("class X; def y; end end")
        #   ast.jump(:def, :class).first
        #   # =>
        # @example If the node types are not present in the AST
        #   ast = YARD.parse("def x; end")
        #   ast.jump(:def)
        #
        # @param [Array] node_types a set of node types to match
        # @return [AstNode] the matching node, if one was found
        # @return [self] if no node was found
        def jump(*node_types)
          traverse {|child| return(child) if node_types.include?(child.type) }
          self
        end

        # @return [Array] the {AstNode} children inside the node
        def children
          @children ||= select {|e| AstNode === e }
        end

        # Traverses the object and yields each node (including descendants) in order.
        #
        # @yield each descendant node in order
        # @yieldparam [AstNode] self, or a child/descendant node
        # @return [void]
        def traverse
          nodes = [self]
          until nodes.empty?
            node = nodes.pop
            yield node
            nodes += node.children.reverse unless node.children.empty?
          end
        end

        # @group Node Meta Types

        # @return [Boolean] whether the node is a token
        def token?
          @token
        end

        # @return [Boolean] whether the node is a reference (variable,
        #   constant name)
        def ref?
          false
        end

        # @return [Boolean] whether the node is a literal value
        def literal?
          false
        end

        # @return [Boolean] whether the node is a keyword
        def kw?
          false
        end

        # @return [Boolean] whether the node is a method call
        def call?
          false
        end

        # @return [Boolean] whether the node is a method definition
        def def?
          false
        end

        # @return [Boolean] whether the node is a if/elsif/else condition
        def condition?
          false
        end

        # @return [Boolean] whether the node is a loop
        def loop?
          false
        end

        # @return [Boolean] whether the node has a block
        def block?
          respond_to?(:block) || condition?
        end

        # @group Getting Line Information

        # @return [Boolean] whether the node has a {#line_range} set
        def has_line?
          @line_range ? true : false
        end

        # @return [Fixnum] the starting line number of the node
        def line
          line_range && line_range.first
        end

        # @return [String] the first line of source represented by the node.
        def first_line
          full_source.split(/\r?\n/)[line - 1].strip
        end

        # @group Printing a Node

        # @return [String] the first line of source the node represents
        def show
          "\t#{line}: #{first_line}"
        end

        # @return [nil] pretty prints the node
        def pretty_print(q)
          objs = dup + [:__last__]
          objs.unshift(type) if type && type != :list

          options = []
          options << ['docstring', docstring] if @docstring
          if @source_range || @line_range
            options << ['line', line_range]
            options << ['source', source_range]
          end
          objs.pop if options.empty?

          q.group(3, 's(', ')') do
            q.seplist(objs, nil, :each) do |v|
              if v == :__last__
                q.seplist(options, nil, :each) do |arr|
                  k, v2 = *arr
                  q.group(3) do
                    q.text k
                    q.group(3) do
                      q.text ': '
                      q.pp v2
                    end
                  end
                end
              else
                q.pp v
              end
            end
          end
        end

        # @return [String] inspects the object
        def inspect
          typeinfo = type && type != :list ? ':' + type.to_s + ', ' : ''
          's(' + typeinfo + map(&:inspect).join(", ") + ')'
        end

        # @group Managing node state

        # Resets node state in tree
        def unfreeze
          @children = nil
        end

        # @endgroup

        private

        # Resets line information
        # @return [void]
        def reset_line_info
          if size == 0
            self.line_range = @fallback_line
            self.source_range = @fallback_source
          elsif !children.empty?
            f = children.first
            l = children.last
            self.line_range = Range.new(f.line_range.first, l.line_range.last)
            self.source_range = Range.new(f.source_range.first, l.source_range.last)
          elsif @fallback_line || @fallback_source
            self.line_range = @fallback_line
            self.source_range = @fallback_source
          else
            self.line_range = 0...0
            self.source_range = 0...0
          end
        end
      end

      class ReferenceNode < AstNode
        def ref?; true end

        def path
          Array.new flatten
        end

        def namespace
          Array.new flatten[0...-1]
        end
      end

      class LiteralNode < AstNode
        def literal?; true end
      end

      class KeywordNode < AstNode
        def kw?; true end
      end

      class ParameterNode < AstNode
        def unnamed_required_params
          self[0]
        end

        def unnamed_optional_params
          return @unnamed_optional_params if defined?(@unnamed_optional_params)

          params = self[1] || []
          if self[-3] && self[-3][0] && self[-3][0].type == :unnamed_optional_arg
            params += self[-3]
          end

          @unnamed_optional_params = params.empty? ? nil : params
        end

        def named_params
          return @named_params if defined?(@named_params)

          if YARD.ruby2? && self[-3] && self[-3][0] && self[-3][0].type == :named_arg
            @named_params = self[-3]
          else
            @named_params = nil
          end
        end

        def splat_param
          self[2] ? self[2][0] : nil
        end

        def unnamed_end_params
          self[3]
        end

        def double_splat_param
          return nil unless YARD.ruby2?
          if (node = self[-2]).is_a?(AstNode)
            if node.type == :ident
              node
            elsif node.type == :kwrest_param
              # See https://bugs.ruby-lang.org/issues/12387
              node.last
            end
          end
        end

        def block_param
          self[-1] ? self[-1][0] : nil
        end

        def args_forward
          # shape is (required, optional, rest, more, keyword, keyword_rest, block)
          # Ruby 3.1 moves :args_forward from rest to keyword_rest
          args_index = YARD.ruby31? ? -2 : 2
          self[args_index].type == :args_forward if self[args_index]
        end
      end

      class MethodCallNode < AstNode
        def call?; true end
        def namespace; first if index_adjust > 0 end

        def method_name(name_only = false)
          name = self[index_adjust]
          if name == :call
            nil
          elsif name_only && Array === name
            name.jump(:ident).first.to_sym
          else
            name
          end
        end

        def parameters(include_block_param = true)
          return [] if type == :vcall
          params = self[1 + index_adjust]
          return [] unless params
          params = call_has_paren? ? params.first : params
          return [] unless params
          include_block_param ? params : params[0...-1]
        end

        def block_param; parameters.last end

        def block
          last.type == :do_block || last.type == :brace_block ? last : nil
        end

        private

        def index_adjust
          [:call, :command_call].include?(type) ? 2 : 0
        end

        def call_has_paren?
          [:fcall, :call].include?(type)
        end
      end

      class MethodDefinitionNode < AstNode
        def kw?; true end
        def def?; true end
        def namespace; first if index_adjust > 0 end

        def method_name(name_only = false)
          name = self[index_adjust]
          name_only ? name.jump(:ident).first.to_sym : name
        end

        def parameters(include_block_param = true)
          return unless params = self[1 + index_adjust]
          params = params[0] if params.type == :paren
          include_block_param ? params : params[0...-1]
        end

        def signature
          params_src = ''
          params = self[1 + index_adjust]
          if params and params.first
            params_src = params.type == :paren ? '' : ' '
            params_src += params.source.gsub(/\s+(\s|\))/m, '\1')
          end

          "def #{method_name(true)}#{params_src}"
        end

        alias block last

        private

        def index_adjust
          type == :defs ? 2 : 0
        end
      end

      class ConditionalNode < KeywordNode
        def condition?; true end
        def condition; first end
        def then_block; self[1] end

        def else_block
          return unless self[2] && !cmod?
          self[2].type == :elsif ? self[2] : self[2][0]
        end

        private

        def cmod?; type =~ /_mod$/ end
      end

      class ClassNode < KeywordNode
        def class_name; first end
        def superclass; type == :sclass ? nil : self[1] end
        def block; last end
      end

      class ModuleNode < KeywordNode
        def module_name; first end
        def block; last end
      end

      class LoopNode < KeywordNode
        def loop?; true end
        def condition; type == :for ? s(self[0], self[1]) : first end
        def block; last end
      end

      # Represents a lone comment block in source
      class CommentNode < AstNode
        def docstring; first end
        def docstring=(value) end
        alias comments docstring

        def source; "" end
        def first_line; "" end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/legacy/000077500000000000000000000000001466601756300200155ustar00rootroot00000000000000yard-0.9.37/lib/yard/parser/ruby/legacy/irb/000077500000000000000000000000001466601756300205715ustar00rootroot00000000000000yard-0.9.37/lib/yard/parser/ruby/legacy/irb/slex.rb000066400000000000000000000152271466601756300221000ustar00rootroot00000000000000# frozen_string_literal: false
#
#   irb/slex.rb - simple lex analyzer
#   	$Release Version: 0.9.6$
#   	$Revision$
#   	by Keiju ISHITSUKA(keiju@ruby-lang.org)
#
# --
#
#
#

require "irb/notifier"

# @private
module IRB
  class SLex
    DOUT = Notifier::def_notifier("SLex::")
    D_WARN = DOUT::def_notifier(1, "Warn: ")
    D_DEBUG = DOUT::def_notifier(2, "Debug: ")
    D_DETAIL = DOUT::def_notifier(4, "Detail: ")

    DOUT.level = Notifier::D_NOMSG

    def initialize
      @head = Node.new("")
    end

    def def_rule(token, preproc = nil, postproc = nil, &block)
      D_DETAIL.pp token

      postproc = block if block_given?
      create(token, preproc, postproc)
    end

    def def_rules(*tokens, &block)
      if block_given?
        p = block
      end
      for token in tokens
        def_rule(token, nil, p)
      end
    end

    def preproc(token, proc)
      node = search(token)
      node.preproc=proc
    end

    # need a check?
    def postproc(token)
      node = search(token, proc)
      node.postproc=proc
    end

    def search(token)
      @head.search(token.split(//))
    end

    def create(token, preproc = nil, postproc = nil)
      @head.create_subnode(token.split(//), preproc, postproc)
    end

    def match(token)
      case token
      when Array
      when String
        return match(token.split(//))
      else
        return @head.match_io(token)
      end
      ret = @head.match(token)
      D_DETAIL.exec_if{D_DETAIL.printf "match end: %s:%s\n", ret, token.inspect}
      ret
    end

    def inspect
      format("", @head.inspect)
    end

    #----------------------------------------------------------------------
    #
    #   class Node -
    #
    #----------------------------------------------------------------------
    class Node
      # if postproc is nil, this node is an abstract node.
      # if postproc is non-nil, this node is a real node.
      def initialize(preproc = nil, postproc = nil)
        @Tree = {}
        @preproc = preproc
        @postproc = postproc
      end

      attr_accessor :preproc
      attr_accessor :postproc

      def search(chrs, opt = nil)
        return self if chrs.empty?
        ch = chrs.shift
        if node = @Tree[ch]
          node.search(chrs, opt)
        else
          if opt
            chrs.unshift ch
            self.create_subnode(chrs)
          else
            raise "node nothing"
          end
        end
      end

      def create_subnode(chrs, preproc = nil, postproc = nil)
        if chrs.empty?
          if @postproc
            D_DETAIL.pp node
            raise "node already exists"
          else
            D_DEBUG.puts "change abstract node to real node."
            @preproc = preproc
            @postproc = postproc
          end
          return self
        end

        ch = chrs.shift
        if node = @Tree[ch]
          if chrs.empty?
            if node.postproc
              DebugLogger.pp node
              DebugLogger.pp self
              DebugLogger.pp ch
              DebugLogger.pp chrs
              raise "node already exists"
            else
              D_WARN.puts "change abstract node to real node"
              node.preproc = preproc
              node.postproc = postproc
            end
          else
            node.create_subnode(chrs, preproc, postproc)
          end
        else
          if chrs.empty?
            node = Node.new(preproc, postproc)
          else
            node = Node.new
            node.create_subnode(chrs, preproc, postproc)
          end
          @Tree[ch] = node
        end
        node
      end

      #
      # chrs: String
      #       character array
      #       io must have getc()/ungetc(); and ungetc() must be
      #       able to be called arbitrary number of times.
      #
      def match(chrs, op = "")
        D_DETAIL.print "match>: ", chrs, "op:", op, "\n"
        if chrs.empty?
          if @preproc.nil? || @preproc.call(op, chrs)
            DOUT.printf(D_DETAIL, "op1: %s\n", op)
            @postproc.call(op, chrs)
          else
            nil
          end
        else
          ch = chrs.shift
          if node = @Tree[ch]
            if ret = node.match(chrs, op+ch)
              return ret
            else
              chrs.unshift ch
              if @postproc and @preproc.nil? || @preproc.call(op, chrs)
                DOUT.printf(D_DETAIL, "op2: %s\n", op.inspect)
                ret = @postproc.call(op, chrs)
                return ret
              else
                return nil
              end
            end
          else
            chrs.unshift ch
            if @postproc and @preproc.nil? || @preproc.call(op, chrs)
              DOUT.printf(D_DETAIL, "op3: %s\n", op)
              @postproc.call(op, chrs)
              return ""
            else
              return nil
            end
          end
        end
      end

      def match_io(io, op = "")
        if op == ""
          ch = io.getc
          if ch == nil
            return nil
          end
        else
          ch = io.getc_of_rests
        end
        if ch.nil?
          if @preproc.nil? || @preproc.call(op, io)
            D_DETAIL.printf("op1: %s\n", op)
            @postproc.call(op, io)
          else
            nil
          end
        else
          if node = @Tree[ch]
            if ret = node.match_io(io, op+ch)
              ret
            else
              io.ungetc ch
              if @postproc and @preproc.nil? || @preproc.call(op, io)
                DOUT.exec_if{D_DETAIL.printf "op2: %s\n", op.inspect}
                @postproc.call(op, io)
              else
                nil
              end
            end
          else
            io.ungetc ch
            if @postproc and @preproc.nil? || @preproc.call(op, io)
              D_DETAIL.printf("op3: %s\n", op)
              @postproc.call(op, io)
            else
              nil
            end
          end
        end
      end
    end
  end
end
# :startdoc:

if $0 == __FILE__
  case $1
  when "1"
    tr = SLex.new
    print "0: ", tr.inspect, "\n"
    tr.def_rule("=") {print "=\n"}
    print "1: ", tr.inspect, "\n"
    tr.def_rule("==") {print "==\n"}
    print "2: ", tr.inspect, "\n"

    print "case 1:\n"
    print tr.match("="), "\n"
    print "case 2:\n"
    print tr.match("=="), "\n"
    print "case 3:\n"
    print tr.match("=>"), "\n"

  when "2"
    tr = SLex.new
    print "0: ", tr.inspect, "\n"
    tr.def_rule("=") {print "=\n"}
    print "1: ", tr.inspect, "\n"
    tr.def_rule("==", proc{false}) {print "==\n"}
    print "2: ", tr.inspect, "\n"

    print "case 1:\n"
    print tr.match("="), "\n"
    print "case 2:\n"
    print tr.match("=="), "\n"
    print "case 3:\n"
    print tr.match("=>"), "\n"
  end
  exit
end
yard-0.9.37/lib/yard/parser/ruby/legacy/ruby_lex.rb000066400000000000000000001063101466601756300221740ustar00rootroot00000000000000require_relative 'irb/slex'

module YARD
  module Parser::Ruby::Legacy
    # Legacy lexical tokenizer module.
    module RubyToken
      EXPR_BEG   = :EXPR_BEG
      EXPR_MID   = :EXPR_MID
      EXPR_END   = :EXPR_END
      EXPR_ARG   = :EXPR_ARG
      EXPR_FNAME = :EXPR_FNAME
      EXPR_DOT   = :EXPR_DOT
      EXPR_CLASS = :EXPR_CLASS

      # Represents a token in the Ruby lexer
      class Token
        # @return [Integer] the line number in the file/stream the token is
        #   located.
        attr_reader :line_no

        # @return [Integer] the character number in the file/stream the token
        #   is located.
        attr_reader :char_no

        # @return [String] the token text value
        attr_reader :text

        # @return [Symbol] the lexical state at the token
        attr_accessor :lex_state

        # @private
        NO_TEXT = "??".freeze

        # Creates a new Token object
        # @param [Integer] line_no the line number to initialize the token to
        # @param [Integer] char_no the char number to initialize the token to
        def initialize(line_no, char_no)
          @line_no = line_no
          @char_no = char_no
          @text    = NO_TEXT
        end

        # Chainable way to sets the text attribute
        #
        # @param [String] text the new text
        # @return [Token] this token object
        def set_text(text)
          @text = text
          self
        end
      end

      # Represents a block
      class TkBlockContents < Token
        def text; '...' end
      end

      # Represents an end statement
      class TkStatementEnd < Token
        def text; '' end
      end

      class TkNode < Token
        attr :node
      end

      # Represents whitespace
      class TkWhitespace < Token
      end

      # Represents a Ruby identifier
      class TkId < Token
        def initialize(line_no, char_no, name)
          super(line_no, char_no)
          @name = name
        end
        attr :name
      end

      # Represents a Ruby keyword
      class TkKW < TkId
      end

      # Represents a Ruby value
      class TkVal < Token
        def initialize(line_no, char_no, value = nil)
          super(line_no, char_no)
          set_text(value)
        end
      end

      class TkOp < Token
        def name
          self.class.op_name
        end
      end

      class TkOPASGN < TkOp
        def initialize(line_no, char_no, op)
          super(line_no, char_no)
          op = TkReading2Token[op] unless op.is_a?(Symbol)
          @op = op
        end
        attr :op
      end

      class TkUnknownChar < Token
        def initialize(line_no, char_no, _id)
          super(line_no, char_no)
          @name = char_no > 255 ? '?' : char_no.chr
        end
        attr :name
      end

      class TkError < Token
      end

      # @private
      def set_token_position(line, char)
        @prev_line_no = line
        @prev_char_no = char
      end

      # @private
      def Token(token, value = nil) # rubocop:disable Style/MethodName
        tk = nil
        case token
        when String, Symbol
          source = token.is_a?(String) ? TkReading2Token : TkSymbol2Token
          if (tk = source[token]).nil?
            raise "no key #{token}"
          end
          tk = Token(tk[0], value)
        else
          if token
            tk = if (token.ancestors & [TkId, TkVal, TkOPASGN, TkUnknownChar]).empty?
                   token.new(@prev_line_no, @prev_char_no)
                 else
                   token.new(@prev_line_no, @prev_char_no, value)
                 end
          end
        end
        tk
      end

      # @private
      TokenDefinitions = [
        [:TkCLASS,      TkKW,  "class",  EXPR_CLASS],
        [:TkMODULE,     TkKW,  "module", EXPR_BEG],
        [:TkDEF,        TkKW,  "def",    EXPR_FNAME],
        [:TkUNDEF,      TkKW,  "undef",  EXPR_FNAME],
        [:TkBEGIN,      TkKW,  "begin",  EXPR_BEG],
        [:TkRESCUE,     TkKW,  "rescue", EXPR_MID],
        [:TkENSURE,     TkKW,  "ensure", EXPR_BEG],
        [:TkEND,        TkKW,  "end",    EXPR_END],
        [:TkIF,         TkKW,  "if",     EXPR_BEG, :TkIF_MOD],
        [:TkUNLESS,     TkKW,  "unless", EXPR_BEG, :TkUNLESS_MOD],
        [:TkTHEN,       TkKW,  "then",   EXPR_BEG],
        [:TkELSIF,      TkKW,  "elsif",  EXPR_BEG],
        [:TkELSE,       TkKW,  "else",   EXPR_BEG],
        [:TkCASE,       TkKW,  "case",   EXPR_BEG],
        [:TkWHEN,       TkKW,  "when",   EXPR_BEG],
        [:TkWHILE,      TkKW,  "while",  EXPR_BEG, :TkWHILE_MOD],
        [:TkUNTIL,      TkKW,  "until",  EXPR_BEG, :TkUNTIL_MOD],
        [:TkFOR,        TkKW,  "for",    EXPR_BEG],
        [:TkBREAK,      TkKW,  "break",  EXPR_END],
        [:TkNEXT,       TkKW,  "next",   EXPR_END],
        [:TkREDO,       TkKW,  "redo",   EXPR_END],
        [:TkRETRY,      TkKW,  "retry",  EXPR_END],
        [:TkIN,         TkKW,  "in",     EXPR_BEG],
        [:TkDO,         TkKW,  "do",     EXPR_BEG],
        [:TkRETURN,     TkKW,  "return", EXPR_MID],
        [:TkYIELD,      TkKW,  "yield",  EXPR_END],
        [:TkSUPER,      TkKW,  "super",  EXPR_END],
        [:TkSELF,       TkKW,  "self",   EXPR_END],
        [:TkNIL,        TkKW,  "nil",    EXPR_END],
        [:TkTRUE,       TkKW,  "true",   EXPR_END],
        [:TkFALSE,      TkKW,  "false",  EXPR_END],
        [:TkAND,        TkKW,  "and",    EXPR_BEG],
        [:TkOR,         TkKW,  "or",     EXPR_BEG],
        [:TkNOT,        TkKW,  "not",    EXPR_BEG],
        [:TkIF_MOD,     TkKW],
        [:TkUNLESS_MOD, TkKW],
        [:TkWHILE_MOD,  TkKW],
        [:TkUNTIL_MOD,  TkKW],
        [:TkALIAS,      TkKW,  "alias",    EXPR_FNAME],
        [:TkDEFINED,    TkKW,  "defined?", EXPR_END],
        [:TklBEGIN,     TkKW,  "BEGIN",    EXPR_END],
        [:TklEND,       TkKW,  "END",      EXPR_END],
        [:Tk__LINE__,   TkKW,  "__LINE__", EXPR_END],
        [:Tk__FILE__,   TkKW,  "__FILE__", EXPR_END],
        [:TkIDENTIFIER, TkId],
        [:TkFID,        TkId],
        [:TkGVAR,       TkId],
        [:TkIVAR,       TkId],
        [:TkCONSTANT,   TkId],
        [:TkINTEGER,    TkVal],
        [:TkFLOAT,      TkVal],
        [:TkSYMBOL,     TkVal],
        [:TkLABEL,      TkVal],
        [:TkSTRING,     TkVal],
        [:TkXSTRING,    TkVal],
        [:TkREGEXP,     TkVal],
        [:TkCOMMENT,    TkVal],
        [:TkDSTRING,    TkNode],
        [:TkDXSTRING,   TkNode],
        [:TkDREGEXP,    TkNode],
        [:TkNTH_REF,    TkId],
        [:TkBACK_REF,   TkId],
        [:TkUPLUS,      TkOp,   "+@"],
        [:TkUMINUS,     TkOp,   "-@"],
        [:TkPOW,        TkOp,   "**"],
        [:TkCMP,        TkOp,   "<=>"],
        [:TkEQ,         TkOp,   "=="],
        [:TkEQQ,        TkOp,   "==="],
        [:TkNEQ,        TkOp,   "!="],
        [:TkGEQ,        TkOp,   ">="],
        [:TkLEQ,        TkOp,   "<="],
        [:TkANDOP,      TkOp,   "&&"],
        [:TkOROP,       TkOp,   "||"],
        [:TkMATCH,      TkOp,   "=~"],
        [:TkNMATCH,     TkOp,   "!~"],
        [:TkDOT2,       TkOp,   ".."],
        [:TkDOT3,       TkOp,   "..."],
        [:TkAREF,       TkOp,   "[]"],
        [:TkASET,       TkOp,   "[]="],
        [:TkLSHFT,      TkOp,   "<<"],
        [:TkRSHFT,      TkOp,   ">>"],
        [:TkCOLON2,     TkOp],
        [:TkCOLON3,     TkOp],
        [:OPASGN,       TkOp], # +=, -=  etc. #
        [:TkASSOC,      TkOp,   "=>"],
        [:TkQUESTION,   TkOp,   "?"], #?
        [:TkCOLON,      TkOp,   ":"], #:
        [:TkSTAR],            # *arg
        [:TkAMPER],           # &arg #
        [:TkSYMBEG,     TkId],
        [:TkGT,         TkOp,   ">"],
        [:TkLT,         TkOp,   "<"],
        [:TkPLUS,       TkOp,   "+"],
        [:TkMINUS,      TkOp,   "-"],
        [:TkMULT,       TkOp,   "*"],
        [:TkDIV,        TkOp,   "/"],
        [:TkMOD,        TkOp,   "%"],
        [:TkBITOR,      TkOp,   "|"],
        [:TkBITXOR,     TkOp,   "^"],
        [:TkBITAND,     TkOp,   "&"],
        [:TkBITNOT,     TkOp,   "~"],
        [:TkNOTOP,      TkOp,   "!"],
        [:TkBACKQUOTE,  TkOp,   "`"],
        [:TkASSIGN,     Token,  "="],
        [:TkDOT,        Token,  "."],
        [:TkLPAREN,     Token,  "("],  # (exp)
        [:TkLBRACK,     Token,  "["],  # [arry]
        [:TkLBRACE,     Token,  "{"],  # {hash}
        [:TkRPAREN,     Token,  ")"],
        [:TkRBRACK,     Token,  "]"],
        [:TkRBRACE,     Token,  "}"],
        [:TkCOMMA,      Token,  ","],
        [:TkSEMICOLON,  Token,  ";"],
        [:TkSPACE,          TkWhitespace],
        [:TkNL,             TkWhitespace],
        [:TkEND_OF_SCRIPT,  TkWhitespace],
        [:TkBACKSLASH,  TkUnknownChar,  "\\"],
        [:TkAT,         TkUnknownChar,  "@"],
        [:TkDOLLAR,     TkUnknownChar,  "\$"]
      ]

      # { reading => token_class }
      # { reading => [token_class, *opt] }
      TkReading2Token = {}
      TkSymbol2Token = {}

      # @private
      def self.def_token(token_n, super_token = Token, reading = nil, *opts)
        token_n = token_n.id2name unless token_n.is_a?(String)
        if RubyToken.const_defined?(token_n)
          # IRB.fail AlreadyDefinedToken, token_n
        end

        token_c = Class.new super_token
        RubyToken.const_set token_n, token_c
        # token_c.inspect

        if reading
          if TkReading2Token[reading]
            raise "duplicate #{token_n} #{reading}"
          end
          if opts.empty?
            TkReading2Token[reading] = [token_c]
          else
            TkReading2Token[reading] = [token_c].concat(opts)
          end
        end
        TkSymbol2Token[token_n.intern] = token_c

        if token_c <= TkOp
          token_c.class_eval %{
            def self.op_name; "#{reading}"; end
          }
        end
      end

      for defs in TokenDefinitions
        def_token(*defs)
      end

      NEWLINE_TOKEN = TkNL.new(0, 0)
      NEWLINE_TOKEN.set_text("\n")
    end

    # Lexical analyzer for Ruby source
    # @private
    class RubyLex
      # Read an input stream character by character. We allow for unlimited
      # ungetting of characters just read.
      #
      # We simplify the implementation greatly by reading the entire input
      # into a buffer initially, and then simply traversing it using
      # pointers.
      #
      # We also have to allow for the here document diversion. This
      # little gem comes about when the lexer encounters a here
      # document. At this point we effectively need to split the input
      # stream into two parts: one to read the body of the here document,
      # the other to read the rest of the input line where the here
      # document was initially encountered. For example, we might have
      #
      #   do_something(<<-A, <<-B)
      #     stuff
      #     for
      #   A
      #     stuff
      #     for
      #   B
      #
      # When the lexer encounters the <= @size
          ch = @content[@offset, 1]

          @offset += 1
          @hwm = @offset if @hwm < @offset

          if @newline_pending
            @line_num += 1
            @last_newline = @offset - 1
            @newline_pending = false
          end

          if ch == "\n"
            @newline_pending = true
          end
          ch
        end

        def getc_already_read
          getc
        end

        def ungetc(_ch)
          raise "unget past beginning of file" if @offset <= 0
          @offset -= 1
          if @content[@offset] == ?\n
            @newline_pending = false
          end
        end

        def get_read
          res = @content[@read_back_offset...@offset]
          @read_back_offset = @offset
          res
        end

        def peek(at)
          pos = @offset + at
          if pos >= @size
            nil
          else
            @content[pos, 1]
          end
        end

        def peek_equal(str)
          @content[@offset, str.length] == str
        end

        def divert_read_from(reserve)
          @content[@offset, 0] = reserve
          @size = @content.size
        end
      end

      # end of nested class BufferedReader

      include RubyToken
      include IRB

      attr_reader :continue
      attr_reader :lex_state

      def self.debug?
        false
      end

      def initialize(content)
        lex_init

        @reader = BufferedReader.new(content)

        @exp_line_no = @line_no = 1
        @base_char_no = 0
        @indent = 0

        @ltype = nil
        @quoted = nil
        @lex_state = EXPR_BEG
        @space_seen = false

        @continue = false
        @line = ""

        @skip_space = false
        @read_auto_clean_up = false
        @exception_on_syntax_error = true

        @colonblock_seen = false
      end

      attr_accessor :skip_space
      attr_accessor :read_auto_clean_up
      attr_accessor :exception_on_syntax_error

      attr :indent

      # io functions
      def line_no
        @reader.line_num
      end

      def char_no
        @reader.column
      end

      def get_read
        @reader.get_read
      end

      def getc
        @reader.getc
      end

      def getc_of_rests
        @reader.getc_already_read
      end

      def gets
        (c = getc) || return
        l = ""
        begin
          l.concat c unless c == "\r"
          break if c == "\n"
        end while c = getc # rubocop:disable Lint/Loop
        l
      end

      def ungetc(c = nil)
        @reader.ungetc(c)
      end

      def peek_equal?(str)
        @reader.peek_equal(str)
      end

      def peek(i = 0)
        @reader.peek(i)
      end

      def lex
        catch(:eof) do
          until ((tk = token).is_a?(TkNL) || tk.is_a?(TkEND_OF_SCRIPT)) &&
                !@continue ||
                tk.nil?
          end
          line = get_read

          if line == "" && tk.is_a?(TkEND_OF_SCRIPT) || tk.nil?
            nil
          else
            line
          end
        end
      end

      def token
        set_token_position(line_no, char_no)
        catch(:eof) do
          begin
            begin
              tk = @OP.match(self)
              @space_seen = tk.is_a?(TkSPACE)
            rescue SyntaxError
              abort if @exception_on_syntax_error
              tk = TkError.new(line_no, char_no)
            end
          end while @skip_space && tk.is_a?(TkSPACE)
          if @read_auto_clean_up
            get_read
          end
          # throw :eof unless tk
          p tk if $DEBUG
          tk.lex_state = lex_state if tk
          tk
        end
      end

      ENINDENT_CLAUSE = [
        "case", "class", "def", "do", "for", "if",
        "module", "unless", "until", "while", "begin"
      ] #, "when"
      ACCEPTS_COLON = ["if", "for", "unless", "until", "while"]
      DEINDENT_CLAUSE = ["end"] #, "when"

      PERCENT_LTYPE = {
        "q" => "\'",
        "Q" => "\"",
        "x" => "\`",
        "r" => "/",
        "w" => "]",
        "W" => "]"
      }

      PERCENT_PAREN = {
        "{" => "}",
        "[" => "]",
        "<" => ">",
        "(" => ")"
      }

      Ltype2Token = {
        "\'" => TkSTRING,
        "\"" => TkSTRING,
        "\`" => TkXSTRING,
        "/" => TkREGEXP,
        "]" => TkDSTRING
      }
      Ltype2Token.default = TkSTRING

      DLtype2Token = {
        "\"" => TkDSTRING,
        "\`" => TkDXSTRING,
        "/" => TkDREGEXP
      }

      def lex_init()
        @OP = SLex.new
        @OP.def_rules("\0", "\004", "\032") do |chars, _io|
          Token(TkEND_OF_SCRIPT).set_text(chars)
        end

        @OP.def_rules(" ", "\t", "\f", "\r", "\13") do |chars, _io|
          @space_seen = true
          while (ch = getc) =~ /[ \t\f\r\13]/
            chars << ch
          end
          ungetc
          Token(TkSPACE).set_text(chars)
        end

        @OP.def_rule("#") do |_op, _io|
          identify_comment
        end

        @OP.def_rule("=begin", proc { @prev_char_no == 0 && peek(0) =~ /\s/ }) do |op, _io|
          str = String.new(op)
          @ltype = "="

          begin
            line = String.new
            begin
              ch = getc
              line << ch
            end until ch == "\n"
            str << line
          end until line =~ /^=end/

          ungetc

          @ltype = nil

          if str =~ /\A=begin\s+rdoc/i
            str.sub!(/\A=begin.*\n/, '')
            str.sub!(/^=end.*/m, '')
            Token(TkCOMMENT).set_text(str)
          else
            Token(TkCOMMENT).set_text(str)
          end
        end

        @OP.def_rule("\n") do
          print "\\n\n" if RubyLex.debug?
          @colonblock_seen = false
          case @lex_state
          when EXPR_BEG, EXPR_FNAME, EXPR_DOT
            @continue = true
          else
            @continue = false
            @lex_state = EXPR_BEG
          end
          Token(TkNL).set_text("\n")
        end

        @OP.def_rules("*", "**",
          "!", "!=", "!~",
          "=", "==", "===",
          "=~", "<=>",
          "<", "<=",
          ">", ">=", ">>") do |op, _io|
          @lex_state = EXPR_BEG
          Token(op).set_text(op)
        end

        @OP.def_rules("<<") do |op, _io|
          tk = nil
          if @lex_state != EXPR_END && @lex_state != EXPR_CLASS &&
             (@lex_state != EXPR_ARG || @space_seen)
            c = peek(0)
            tk = identify_here_document if /[-~\w\"\'\`]/ =~ c
          end
          if !tk
            @lex_state = EXPR_BEG
            tk = Token(op).set_text(op)
          end
          tk
        end

        @OP.def_rules("'", '"') do |op, _io|
          identify_string(op)
        end

        @OP.def_rules("`") do |op, _io|
          if @lex_state == EXPR_FNAME
            Token(op).set_text(op)
          else
            identify_string(op)
          end
        end

        @OP.def_rules('?') do |op, _io|
          if @lex_state == EXPR_END
            @lex_state = EXPR_BEG
            Token(TkQUESTION).set_text(op)
          else
            ch = getc
            if @lex_state == EXPR_ARG && ch !~ /\s/
              ungetc
              @lex_state = EXPR_BEG
              Token(TkQUESTION).set_text(op)
            else
              str = String.new(op)
              str << ch
              if ch == '\\' #'
                str << read_escape
              end
              @lex_state = EXPR_END
              Token(TkINTEGER).set_text(str)
            end
          end
        end

        @OP.def_rules("&", "&&", "|", "||") do |op, _io|
          @lex_state = EXPR_BEG
          Token(op).set_text(op)
        end

        @OP.def_rules("+=", "-=", "*=", "**=",
          "&=", "|=", "^=", "<<=", ">>=", "||=", "&&=") do |op, _io|
          @lex_state = EXPR_BEG
          op =~ /^(.*)=$/
          Token(TkOPASGN, $1).set_text(op)
        end

        @OP.def_rule("+@", proc { @lex_state == EXPR_FNAME }) do |op, _io|
          Token(TkUPLUS).set_text(op)
        end

        @OP.def_rule("-@", proc { @lex_state == EXPR_FNAME }) do |op, _io|
          Token(TkUMINUS).set_text(op)
        end

        @OP.def_rules("+", "-") do |op, _io|
          catch(:RET) do
            if @lex_state == EXPR_ARG
              if @space_seen && peek(0) =~ /[0-9]/
                throw :RET, identify_number(op)
              else
                @lex_state = EXPR_BEG
              end
            elsif @lex_state != EXPR_END && peek(0) =~ /[0-9]/
              throw :RET, identify_number(op)
            else
              @lex_state = EXPR_BEG
            end
            Token(op).set_text(op)
          end
        end

        @OP.def_rule(".") do
          @lex_state = EXPR_BEG
          if peek(0) =~ /[0-9]/
            ungetc
            identify_number("")
          else
            # for obj.if
            @lex_state = EXPR_DOT
            Token(TkDOT).set_text(".")
          end
        end

        @OP.def_rules("..", "...") do |op, _io|
          @lex_state = EXPR_BEG
          Token(op).set_text(op)
        end

        lex_int2
      end

      def lex_int2
        @OP.def_rules("]", "}", ")") do |op, _io|
          @lex_state = EXPR_END
          @indent -= 1
          Token(op).set_text(op)
        end

        @OP.def_rule(":") do
          if (@colonblock_seen && @lex_state != EXPR_BEG) || peek(0) =~ /\s/
            @lex_state = EXPR_BEG
            tk = Token(TkCOLON)
          else
            @lex_state = EXPR_FNAME
            tk = Token(TkSYMBEG)
          end
          tk.set_text(":")
        end

        @OP.def_rule("::") do
          # p @lex_state.id2name, @space_seen
          if @lex_state == EXPR_BEG || @lex_state == EXPR_ARG && @space_seen
            @lex_state = EXPR_BEG
            tk = Token(TkCOLON3)
          else
            @lex_state = EXPR_DOT
            tk = Token(TkCOLON2)
          end
          tk.set_text("::")
        end

        @OP.def_rule("/") do |op, _io|
          if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
            identify_string(op)
          elsif peek(0) == '='
            getc
            @lex_state = EXPR_BEG
            Token(TkOPASGN, :/).set_text("/=") #")
          elsif @lex_state == EXPR_ARG && @space_seen && peek(0) !~ /\s/
            identify_string(op)
          else
            @lex_state = EXPR_BEG
            Token("/").set_text(op)
          end
        end

        @OP.def_rules("^") do
          @lex_state = EXPR_BEG
          Token("^").set_text("^")
        end

        # @OP.def_rules("^=") do
        #   @lex_state = EXPR_BEG
        #   Token(TkOPASGN, :^)
        # end

        @OP.def_rules(",", ";") do |op, _io|
          @colonblock_seen = false
          @lex_state = EXPR_BEG
          Token(op).set_text(op)
        end

        @OP.def_rule("~") do
          @lex_state = EXPR_BEG
          Token("~").set_text("~")
        end

        @OP.def_rule("~@", proc { @lex_state = EXPR_FNAME }) do
          @lex_state = EXPR_BEG
          Token("~").set_text("~@")
        end

        @OP.def_rule("(") do
          @indent += 1
            # if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
            #  @lex_state = EXPR_BEG
            #  tk = Token(TkfLPAREN)
            # else
            @lex_state = EXPR_BEG
            tk = Token(TkLPAREN)
          # end
          tk.set_text("(")
        end

        @OP.def_rule("[]", proc { @lex_state == EXPR_FNAME }) do
          Token("[]").set_text("[]")
        end

        @OP.def_rule("[]=", proc { @lex_state == EXPR_FNAME }) do
          Token("[]=").set_text("[]=")
        end

        @OP.def_rule("[") do
          @indent += 1
          # if @lex_state == EXPR_FNAME
          #   t = Token(TkfLBRACK)
          # else
          #   if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
          #     t = Token(TkLBRACK)
          #   elsif @lex_state == EXPR_ARG && @space_seen
          #   else
          #     t = Token(TkfLBRACK)
          #   end
          # end
          t = Token(TkLBRACK)
          @lex_state = EXPR_BEG
          t.set_text("[")
        end

        @OP.def_rule("{") do
          @indent += 1
          # if @lex_state != EXPR_END && @lex_state != EXPR_ARG
          #   t = Token(TkLBRACE)
          # else
          #   t = Token(TkfLBRACE)
          # end
          t = Token(TkLBRACE)
          @lex_state = EXPR_BEG
          t.set_text("{")
        end

        @OP.def_rule('\\') do #'
          if getc == "\n"
            @space_seen = true
            @continue = true
            Token(TkSPACE).set_text("\\\n")
          else
            ungetc
            Token("\\").set_text("\\") #"
          end
        end

        @OP.def_rule('%') do |_op, _io|
          if @lex_state == EXPR_BEG || @lex_state == EXPR_MID
            identify_quotation('%')
          elsif peek(0) == '='
            getc
            Token(TkOPASGN, "%").set_text("%=")
          elsif @lex_state == EXPR_ARG && @space_seen && peek(0) !~ /\s/
            identify_quotation('%')
          else
            @lex_state = EXPR_BEG
            Token("%").set_text("%")
          end
        end

        @OP.def_rule('$') do #'
          identify_gvar
        end

        @OP.def_rule('@') do
          if peek(0) =~ /[@\w]/
            ungetc
            identify_identifier
          else
            Token("@").set_text("@")
          end
        end

        # @OP.def_rule("def", proc{|op, io| /\s/ =~ io.peek(0)}) do
        #   |op, io|
        #   @indent += 1
        #   @lex_state = EXPR_FNAME
        # # @lex_state = EXPR_END
        # # until @rests[0] == "\n" or @rests[0] == ";"
        # #   rests.shift
        # # end
        # end

        @OP.def_rule("__END__", proc { @prev_char_no == 0 && peek(0) =~ /[\r\n]/ }) do
          throw :eof
        end

        @OP.def_rule("") do |op, io|
          printf "MATCH: start %s: %s\n", op, io.inspect if RubyLex.debug?
          if peek(0) =~ /[0-9]/
            t = identify_number("")
          elsif peek(0) =~ /[\w]/
            t = identify_identifier
          end
          printf "MATCH: end %s: %s\n", op, io.inspect if RubyLex.debug?
          t
        end

        p @OP if RubyLex.debug?
      end

      def identify_gvar
        @lex_state = EXPR_END
        str = String.new("$")

        tk = case ch = getc
             when %r{[~_*$?!@/\\;,=:<>".]}
               str << ch
               Token(TkGVAR, str)

             when "-"
               str << "-" << getc
               Token(TkGVAR, str)

             when "&", "`", "'", "+"
               str << ch
               Token(TkBACK_REF, str)

             when /[1-9]/
               str << ch
               while (ch = getc) =~ /[0-9]/
                 str << ch
               end
               ungetc
               Token(TkNTH_REF)
             when /\w/
               ungetc
               ungetc
               return identify_identifier
             else
               ungetc
               Token("$")
             end
        tk.set_text(str)
      end

      def identify_identifier
        token = ""
        token.concat getc if peek(0) =~ /[$@]/
        token.concat getc if peek(0) == "@"

        while (ch = getc) =~ /\w|_/
          print ":", ch, ":" if RubyLex.debug?
          token.concat ch
        end
        ungetc

        if ch == "!" || ch == "?"
          token.concat getc
        end
        # fix token

        # $stderr.puts "identifier - #{token}, state = #@lex_state"

        case token
        when /^\$/
          return Token(TkGVAR, token).set_text(token)
        when /^\@/
          @lex_state = EXPR_END
          return Token(TkIVAR, token).set_text(token)
        end

        if @lex_state != EXPR_DOT
          print token, "\n" if RubyLex.debug?

          token_c, *trans = TkReading2Token[token]
          if token_c
            # reserved word?

            if @lex_state != EXPR_BEG &&
               @lex_state != EXPR_FNAME &&
               trans[1]
              # modifiers
              token_c = TkSymbol2Token[trans[1]]
              @lex_state = trans[0]
            else
              if @lex_state != EXPR_FNAME
                if ENINDENT_CLAUSE.include?(token)
                  @indent += 1

                  if ACCEPTS_COLON.include?(token)
                    @colonblock_seen = true
                  else
                    @colonblock_seen = false
                  end
                elsif DEINDENT_CLAUSE.include?(token)
                  @indent -= 1
                  @colonblock_seen = false
                end
                @lex_state = trans[0]
              else
                @lex_state = EXPR_END
              end
            end
            return Token(token_c, token).set_text(token)
          end
        end

        if @lex_state == EXPR_FNAME
          @lex_state = EXPR_END
          if peek(0) == '='
            token.concat getc
          end
        elsif @lex_state == EXPR_BEG || @lex_state == EXPR_DOT
          @lex_state = EXPR_ARG
        else
          @lex_state = EXPR_END
        end

        if token[0, 1] =~ /[A-Z]/
          return Token(TkCONSTANT, token).set_text(token)
        elsif token[token.size - 1, 1] =~ /[!?]/
          return Token(TkFID, token).set_text(token)
        else
          return Token(TkIDENTIFIER, token).set_text(token)
        end
      end

      def identify_here_document
        ch = getc
        if ch == "-"
          ch = getc
        elsif ch == "~"
          ch = getc
          indent = true
        end
        if /['"`]/ =~ ch # '
          lt = ch
          quoted = ""
          while (c = getc) && c != lt
            quoted.concat c
          end
        else
          lt = '"'
          quoted = ch.dup
          while (c = getc) && c =~ /\w/
            quoted.concat c
          end
          ungetc
        end

        ltback, @ltype = @ltype, lt
        reserve = String.new

        while ch = getc
          reserve << ch
          if ch == "\\" #"
            ch = getc
            reserve << ch
          elsif ch == "\n"
            break
          end
        end

        str = String.new
        while (l = gets)
          l.chomp!
          if l == quoted
            str = dedent(str) if indent
            break
          else
            str << l.chomp << "\n"
          end
        end

        @reader.divert_read_from(reserve)

        @ltype = ltback
        @lex_state = EXPR_END
        Token(Ltype2Token[lt], str).set_text(str.dump)
      end

      def dedent(str)
        lines = str.split("\n", -1)
        dedent_amt = lines.map do |line|
          line =~ /\S/ ? line.match(/^ */).offset(0)[1] : nil
        end.compact.min || 0
        return str if dedent_amt.zero?

        lines.map { |line| line =~ /\S/ ? line.gsub(/^ {#{dedent_amt}}/, "") : line }.join("\n")
      end

      def identify_quotation(initial_char)
        ch = getc
        if lt = PERCENT_LTYPE[ch]
          initial_char += ch
          ch = getc
        elsif ch =~ /\W/
          lt = "\""
        else
          # RubyLex.fail SyntaxError, "unknown type of %string ('#{ch}')"
        end
        # if ch !~ /\W/
        #   ungetc
        #   next
        # end
        # @ltype = lt
        @quoted = ch unless @quoted = PERCENT_PAREN[ch]
        identify_string(lt, @quoted, ch, initial_char) if lt
      end

      def identify_number(start)
        str = start.dup

        if start == "+" || start == "-" || start == ""
          start = getc
          str << start
        end

        @lex_state = EXPR_END

        if start == "0"
          if peek(0) == "x"
            ch = getc
            str << ch
            match = /[0-9a-f_]/
          else
            match = /[0-7_]/
          end
          while ch = getc
            if ch !~ match
              ungetc
              break
            else
              str << ch
            end
          end
          return Token(TkINTEGER).set_text(str)
        end

        type = TkINTEGER
        allow_point = true
        allow_e = true
        while ch = getc
          case ch
          when /[0-9_]/
            str << ch

          when allow_point && "."
            type = TkFLOAT
            if peek(0) !~ /[0-9]/
              ungetc
              break
            end
            str << ch
            allow_point = false

          when allow_e && "e", allow_e && "E"
            str << ch
            type = TkFLOAT
            if peek(0) =~ /[+-]/
              str << getc
            end
            allow_e = false
            allow_point = false
          else
            ungetc
            break
          end
        end
        Token(type).set_text(str)
      end

      def identify_string(ltype, quoted = ltype, opener = nil, initial_char = nil)
        @ltype = ltype
        @quoted = quoted
        subtype = nil

        str = String.new
        str << initial_char if initial_char
        str << (opener || quoted)

        nest = 0
        begin
          while ch = getc
            str << ch
            if @quoted == ch
              if nest == 0
                break
              else
                nest -= 1
              end
            elsif opener == ch
              nest += 1
            elsif @ltype != "'" && @ltype != "]" && ch == "#"
              ch = getc
              if ch == "{"
                subtype = true
                str << ch << skip_inner_expression
              else
                ungetc(ch)
              end
            elsif ch == '\\' #'
              str << read_escape
            end
          end
          if @ltype == "/"
            if peek(0) =~ /i|o|n|e|s/
              str << getc
            end
          end
          if subtype
            Token(DLtype2Token[ltype], str)
          else
            Token(Ltype2Token[ltype], str)
          end.set_text(str)
        ensure
          @ltype = nil
          @quoted = nil
          @lex_state = EXPR_END
        end
      end

      def skip_inner_expression
        res = String.new
        nest = 0
        while (ch = getc)
          res << ch
          if ch == '}'
            break if nest == 0
            nest -= 1
          elsif ch == '{'
            nest += 1
          end
        end
        res
      end

      def identify_comment
        @ltype = "#"
        comment = String.new("#")
        while ch = getc
          if ch == "\\"
            ch = getc
            if ch == "\n"
              ch = " "
            else
              comment << "\\"
            end
          else
            if ch == "\n"
              @ltype = nil
              ungetc
              break
            end
          end
          comment << ch
        end
        Token(TkCOMMENT).set_text(comment)
      end

      def read_escape
        res = String.new
        case ch = getc
        when /[0-7]/
          ungetc ch
          3.times do
          case ch = getc
          when /[0-7]/
          when nil
            break
          else
            ungetc
            break
          end
          res << ch
          end

        when "x"
          res << ch
          2.times do
          case ch = getc
          when /[0-9a-fA-F]/
          when nil
            break
          else
            ungetc
            break
          end
            res << ch
          end

        when "M"
          res << ch
          if (ch = getc) != '-'
            ungetc
          else
            res << ch
            if (ch = getc) == "\\" #"
              res << ch
              res << read_escape
            else
              res << ch
            end
          end

        when "C", "c" #, "^"
          res << ch
          if ch == "C" && (ch = getc) != "-"
            ungetc
          else
            res << ch
            if (ch = getc) == "\\" #"
              res << ch
              res << read_escape
            else
              res << ch
            end
          end
        else
          res << ch
        end
        res
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/legacy/ruby_parser.rb000066400000000000000000000012341466601756300226770ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser
    module Ruby
      module Legacy
        # Legacy Ruby parser
        # @since 0.5.6
        class RubyParser < Parser::Base
          def initialize(source, _filename)
            @source = source
          end

          def parse
            @parse ||= StatementList.new(@source)
            self
          end

          def tokenize
            @tokenize ||= TokenList.new(@source)
          end

          def enumerator
            @parse
          end

          def encoding_line; @parse.encoding_line end
          def shebang_line; @parse.shebang_line end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/legacy/statement.rb000066400000000000000000000031061466601756300223460ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser::Ruby::Legacy
    class Statement
      attr_reader :tokens, :comments, :block
      attr_accessor :comments_range

      # @deprecated Groups are now defined by directives
      # @see Tags::GroupDirective
      attr_accessor :group

      attr_accessor :comments_hash_flag

      def initialize(tokens, block = nil, comments = nil)
        @tokens = tokens
        @block  = block
        @comments = comments
        @comments_hash_flag = false
      end

      def first_line
        to_s.split(/\n/)[0]
      end

      alias signature first_line

      def to_s(include_block = true)
        tokens.map do |token|
          RubyToken::TkBlockContents === token ? (include_block ? block.to_s : '') : token.text
        end.join
      end
      alias source to_s

      def inspect
        l = line - 1
        to_s(false).split(/\n/).map do |text|
          "\t#{l += 1}:  #{text}"
        end.join("\n")
      end

      def show
        "\t#{line}: #{first_line}"
      end

      # @return [Fixnum] the first line of Ruby source
      def line
        tokens.first.line_no
      end

      # @return [Range] the first to last lines of Ruby source
      # @since 0.5.4
      def line_range
        tokens.first.line_no..tokens.last.line_no
      end

      private

      def clean_tokens(tokens)
        last_tk = nil
        tokens.reject do |tk|
          tk.is_a?(RubyToken::TkNL) ||
            (last_tk.is_a?(RubyToken::TkSPACE) &&
            last_tk.class == tk.class) && last_tk = tk
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/legacy/statement_list.rb000066400000000000000000000317361466601756300234130ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser::Ruby::Legacy
    class StatementList < Array
      include RubyToken

      attr_accessor :shebang_line, :encoding_line

      # The following list of tokens will require a block to be opened
      # if used at the beginning of a statement.
      OPEN_BLOCK_TOKENS = [TkCLASS, TkDEF, TkMODULE, TkUNTIL,
                           TkIF, TkELSIF, TkUNLESS, TkWHILE, TkFOR, TkCASE]

      # Creates a new statement list
      #
      # @param [TokenList, String] content the tokens to create the list from
      def initialize(content)
        @shebang_line = nil
        @encoding_line = nil
        @comments_last_line = nil
        if content.is_a? TokenList
          @tokens = content.dup
        elsif content.is_a? String
          @tokens = TokenList.new(content.delete("\r"))
        else
          raise ArgumentError, "Invalid content for StatementList: #{content.inspect}:#{content.class}"
        end

        parse_statements
      end

      private

      def parse_statements
        loop do
          stmt = next_statement
          break if stmt.nil?
          self << stmt
        end
      end

      # Returns the next statement in the token stream
      #
      # @return [Statement] the next statement
      def next_statement
        @state = :first_statement
        @statement_stack = []
        @level = 0
        @block_num = 0
        @done = false
        @current_block = nil
        @comments_line = nil
        @comments_hash_flag = nil
        @statement = TokenList.new
        @block = nil
        @comments = nil
        @last_tk = nil
        @last_ns_tk = nil
        @before_last_tk = nil
        @before_last_ns_tk = nil
        @first_line = nil

        until @done
          tk = @tokens.shift
          break if tk.nil?
          process_token(tk)

          @before_last_tk = @last_tk
          @last_tk = tk # Save last token
          unless [TkSPACE, TkNL, TkEND_OF_SCRIPT].include? tk.class
            @before_last_ns_tk = @last_ns_tk
            @last_ns_tk = tk
          end
        end

        # Return the code block with starting token and initial comments
        # If there is no code in the block, return nil
        @comments = @comments.compact if @comments
        if @block || !@statement.empty?
          sanitize_statement_end
          sanitize_block
          @statement.pop if [TkNL, TkSPACE, TkSEMICOLON].include?(@statement.last.class)
          stmt = Statement.new(@statement, @block, @comments)
          if @comments && @comments_line
            stmt.comments_range = (@comments_line..(@comments_line + @comments.size - 1))
            stmt.comments_hash_flag = @comments_hash_flag
          end
          stmt
        elsif @comments
          @statement << TkCOMMENT.new(@comments_line, 0)
          @statement.first.set_text("# " + @comments.join("\n# "))
          Statement.new(@statement, nil, @comments)
        end
      end

      def sanitize_statement_end
        extra = []
        (@statement.size - 1).downto(0) do |index|
          token = @statement[index]
          next unless TkStatementEnd === token

          while [TkNL, TkSPACE, TkSEMICOLON].include?(@statement[index - 1].class)
            extra.unshift(@statement.delete_at(index - 1))
            index -= 1
          end
          @statement.insert(index + 1, *extra)
          break
        end
      end

      def sanitize_block
        return unless @block
        extra = []
        while [TkSPACE, TkNL, TkSEMICOLON].include?(@block.last.class)
          next(@block.pop) if TkSEMICOLON === @block.last
          extra.unshift(@block.pop)
        end

        @statement.each_with_index do |token, index|
          if TkBlockContents === token
            @statement[index, 1] = [token, *extra]
            break
          end
        end
      end

      # Processes a single token
      #
      # @param [RubyToken::Token] tk the token to process
      def process_token(tk)
        # p tk.class, tk.text, @state, @level, @current_block, "
    "
        case @state
        when :first_statement
          return if process_initial_comment(tk)
          return if @statement.empty? && [TkSPACE, TkNL, TkCOMMENT].include?(tk.class)
          @comments_last_line = nil
          if @statement.empty? && tk.class == TkALIAS
            @state = :alias_statement
            @alias_values = []
            push_token(tk)
            return
          end
          return if process_simple_block_opener(tk)
          push_token(tk)
          return if process_complex_block_opener(tk)

          if balances?(tk)
            process_statement_end(tk)
          else
            @state = :balance
          end
        when :alias_statement
          push_token(tk)
          @alias_values << tk unless [TkSPACE, TkNL, TkCOMMENT].include?(tk.class)
          if @alias_values.size == 2
            @state = :first_statement
            if [NilClass, TkNL, TkEND_OF_SCRIPT, TkSEMICOLON].include?(peek_no_space.class)
              @done = true
            end
          end
        when :balance
          @statement << tk
          return unless balances?(tk)
          @state = :first_statement
          process_statement_end(tk)
        when :block_statement
          push_token(tk)
          return unless balances?(tk)
          process_statement_end(tk)
        when :pre_block
          @current_block = nil
          process_block_token(tk) unless tk.class == TkSEMICOLON
          @state = :block
        when :block
          process_block_token(tk)
        when :post_block
          if tk.class == TkSPACE
            @statement << tk
            return
          end

          process_statement_end(tk)
          @state = :block
        end

        if @first_line == tk.line_no && !@statement.empty? && TkCOMMENT === tk
          process_initial_comment(tk)
        end
      end

      # Processes a token in a block
      #
      # @param [RubyToken::Token] tk the token to process
      def process_block_token(tk)
        if balances?(tk)
          @statement << tk
          @state = :first_statement
          process_statement_end(tk)
        elsif @block_num > 1 || (@block.empty? && [TkSPACE, TkNL].include?(tk.class))
          @statement << tk
        else
          if @block.empty?
            @statement << TkBlockContents.new(tk.line_no, tk.char_no)
          end
          @block << tk
        end
      end

      # Processes a comment token that comes before a statement
      #
      # @param [RubyToken::Token] tk the token to process
      # @return [Boolean] whether or not +tk+ was processed as an initial comment
      def process_initial_comment(tk)
        if @statement.empty? && (@comments_last_line || 0) < tk.line_no - 2
          @comments = nil
        end

        return unless tk.class == TkCOMMENT

        case tk.text
        when Parser::SourceParser::SHEBANG_LINE
          if !@last_ns_tk && !@encoding_line
            @shebang_line = tk.text
            return
          end
        when Parser::SourceParser::ENCODING_LINE
          if (@last_ns_tk.class == TkCOMMENT && @last_ns_tk.text == @shebang_line) ||
             !@last_ns_tk
            @encoding_line = tk.text
            return
          end
        end

        return if !@statement.empty? && @comments
        return if @first_line && tk.line_no > @first_line

        if @comments_last_line && @comments_last_line < tk.line_no - 1
          if @comments && @statement.empty?
            @tokens.unshift(tk)
            return @done = true
          end
          @comments = nil
        end
        @comments_line = tk.line_no unless @comments

        # Remove the "#" and up to 1 space before the text
        # Since, of course, the convention is to have "# text"
        # and not "#text", which I deem ugly (you heard it here first)
        @comments ||= []
        if tk.text.start_with?('=begin')
          lines = tk.text.count("\n")
          @comments += tk.text.gsub(/\A=begin.*\r?\n|\r?\n=end.*\r?\n?\Z/, '').split(/\r?\n/)
          @comments_last_line = tk.line_no + lines
        else
          @comments << tk.text.gsub(/^(#+)\s{0,1}/, '')
          @comments_hash_flag = $1 == '##' if @comments_hash_flag.nil?
          @comments_last_line = tk.line_no
        end
        @comments.pop if @comments.size == 1 && @comments.first =~ /^\s*$/
        true
      end

      # Processes a simple block-opening token;
      # that is, a block opener such as +begin+ or +do+
      # that isn't followed by an expression
      #
      # @param [RubyToken::Token] tk the token to process
      def process_simple_block_opener(tk)
        return unless [TkLBRACE, TkDO, TkBEGIN, TkELSE].include?(tk.class) &&
                      # Make sure hashes are parsed as hashes, not as blocks
                      (@last_ns_tk.nil? || @last_ns_tk.lex_state != EXPR_BEG)

        @level += 1
        @state = :block
        @block_num += 1
        if @block.nil?
          @block = TokenList.new
          tokens = [tk, TkStatementEnd.new(tk.line_no, tk.char_no)]
          tokens = tokens.reverse if TkBEGIN === tk.class
          @statement.concat(tokens)
        else
          @statement << tk
        end

        true
      end

      # Processes a complex block-opening token;
      # that is, a block opener such as +while+ or +for+
      # that is followed by an expression
      #
      # @param [RubyToken::Token] tk the token to process
      def process_complex_block_opener(tk)
        return unless OPEN_BLOCK_TOKENS.include?(tk.class)

        @current_block = tk.class
        @state = :block_statement

        true
      end

      # Processes a token that closes a statement
      #
      # @param [RubyToken::Token] tk the token to process
      def process_statement_end(tk)
        # Whitespace means that we keep the same value of @new_statement as last token
        return if tk.class == TkSPACE

        return unless
          # We might be coming after a statement-ending token...
          (@last_tk && [TkSEMICOLON, TkNL, TkEND_OF_SCRIPT].include?(tk.class)) ||
          # Or we might be at the beginning of an argument list
          (@current_block == TkDEF && tk.class == TkRPAREN)

        # Continue line ending on . or ::
        return if @last_tk && [EXPR_DOT].include?(@last_tk.lex_state)

        # Continue a possible existing new statement unless we just finished an expression...
        return unless (@last_tk && [EXPR_END, EXPR_ARG].include?(@last_tk.lex_state)) ||
                      # Or we've opened a block and are ready to move into the body
                      (@current_block && [TkNL, TkSEMICOLON].include?(tk.class) &&
                       # Handle the case where the block statement's expression is on the next line
                       #
                       # while
                       #     foo
                       # end
                       @last_ns_tk.class != @current_block &&
                       # And the case where part of the expression is on the next line
                       #
                       # while foo ||
                       #     bar
                       # end
                       @last_tk.lex_state != EXPR_BEG)

        # Continue with the statement if we've hit a comma in a def
        return if @current_block == TkDEF && peek_no_space.class == TkCOMMA

        if [TkEND_OF_SCRIPT, TkNL, TkSEMICOLON].include?(tk.class) && @state == :block_statement &&
           [TkRBRACE, TkEND].include?(@last_ns_tk.class) && @level == 0
          @current_block = nil
        end

        unless @current_block
          @done = true
          return
        end

        @state = :pre_block
        @level += 1
        @block_num += 1
        unless @block
          @block = TokenList.new
          @statement << TkStatementEnd.new(tk.line_no, tk.char_no)
        end
      end

      # Handles the balancing of parentheses and blocks
      #
      # @param [RubyToken::Token] tk the token to process
      # @return [Boolean] whether or not the current statement's parentheses and blocks
      #   are balanced after +tk+
      def balances?(tk)
        unless [TkALIAS, TkDEF].include?(@last_ns_tk.class) || @before_last_ns_tk.class == TkALIAS
          if [TkLPAREN, TkLBRACK, TkLBRACE, TkDO, TkBEGIN].include?(tk.class)
            @level += 1
          elsif OPEN_BLOCK_TOKENS.include?(tk.class)
            @level += 1 unless tk.class == TkELSIF
          elsif [TkRPAREN, TkRBRACK, TkRBRACE, TkEND].include?(tk.class) && @level > 0
            @level -= 1
          end
        end

        @level == 0
      end

      # Adds a token to the current statement,
      # unless it's a newline, semicolon, or comment
      #
      # @param [RubyToken::Token] tk the token to process
      def push_token(tk)
        @first_line = tk.line_no if @statement.empty?
        @statement << tk unless @level == 0 && [TkCOMMENT].include?(tk.class)
      end

      # Returns the next token in the stream that's not a space
      #
      # @return [RubyToken::Token] the next non-space token
      def peek_no_space
        return @tokens.first unless @tokens.first.class == TkSPACE
        @tokens[1]
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/legacy/token_list.rb000066400000000000000000000037721466601756300225260ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser::Ruby::Legacy
    class TokenList < Array
      include RubyToken

      def initialize(content = nil)
        self << content if content
      end

      def to_s(full_statement = false, show_block = true)
        inject([]) do |acc, token|
          break acc if !full_statement && TkStatementEnd === token
          acc << (!show_block && TkBlockContents === token ? "" : token.text)
        end.join
      end

      # @param [TokenList, Token, String] tokens
      #   A list of tokens. If the token is a string, it
      #   is parsed with {RubyLex}.
      def push(*tokens)
        tokens.each do |tok|
          if tok.is_a?(TokenList) || tok.is_a?(Array)
            concat tok
          elsif tok.is_a?(Token)
            super tok
          elsif tok.is_a?(String)
            parse_content(tok)
          else
            raise ArgumentError, "Expecting token, list of tokens or string of code to be tokenized. Got #{tok.class}"
          end
        end
        self
      end
      alias << push

      def squeeze(type = TkSPACE)
        last = nil
        TokenList.new(map {|t| x = t.is_a?(type) && last.is_a?(type) ? nil : t; last = t; x })
      end

      private

      def parse_content(content)
        lex = RubyLex.new(content)
        loop do
          tk = lex.token
          break if tk.nil?
          self << convert_token(lex, tk)
        end
      end

      def convert_token(lex, tk)
        if TkIDENTIFIER === tk && lex.peek == ':'
          next_tk = lex.token
          sym = TkLABEL.new(tk.line_no, tk.char_no, nil)
          sym.lex_state = lex.lex_state
          sym.set_text(tk.text + next_tk.text)
        elsif TkSYMBEG === tk
          next_tk = lex.token
          if next_tk
            sym = TkSYMBOL.new(tk.line_no, tk.char_no, nil)
            sym.lex_state = lex.lex_state
            sym.set_text(tk.text + next_tk.text)
          else
            tk
          end
        else
          tk
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/ruby_parser.rb000066400000000000000000000567721466601756300214540ustar00rootroot00000000000000# frozen_string_literal: true
begin require 'ripper'; rescue LoadError; nil end

module YARD
  module Parser
    module Ruby
      # Ruby 1.9 parser
      # @!attribute [r] encoding_line
      # @!attribute [r] frozen_string_line
      # @!attribute [r] shebang_line
      # @!attribute [r] enumerator
      class RubyParser < Parser::Base
        def initialize(source, filename)
          @parser = RipperParser.new(source, filename)
        end

        def parse; @parser.parse end
        def tokenize; @parser.tokens end
        def enumerator; @parser.enumerator end
        def shebang_line; @parser.shebang_line end
        def encoding_line; @parser.encoding_line end
        def frozen_string_line; @parser.frozen_string_line end
      end

      # Internal parser class
      # @since 0.5.6
      class RipperParser < Ripper
        attr_reader :ast, :charno, :comments, :file, :tokens
        attr_reader :shebang_line, :encoding_line, :frozen_string_line
        alias root ast

        def initialize(source, filename, *args)
          super
          @last_ns_token = nil
          @file = filename
          @source = source
          @tokens = []
          @comments = {}
          @comments_range = {}
          @comments_flags = {}
          @heredoc_tokens = nil
          @heredoc_state = nil
          @map = {}
          @ns_charno = 0
          @list = []
          @charno = 0
          @shebang_line = nil
          @encoding_line = nil
          @frozen_string_line = nil
          @file_encoding = nil
          @newline = true
          @percent_ary = nil
        end

        def parse
          @ast = super
          @ast.full_source = @source
          @ast.file = @file
          freeze_tree
          insert_comments
          self
        end

        def enumerator
          ast.children
        end

        def file_encoding
          return nil unless defined?(::Encoding)
          return @file_encoding if @file_encoding
          return Encoding.default_internal unless @encoding_line
          match = @encoding_line.match(SourceParser::ENCODING_LINE)
          @file_encoding = match.captures.last if match
        end

        private

        MAPPINGS = {
          :BEGIN => "BEGIN",
          :END => "END",
          :alias => "alias",
          :array => :lbracket,
          :arg_paren => :lparen,
          :begin => "begin",
          :blockarg => "&",
          :brace_block => :lbrace,
          :break => "break",
          :case => "case",
          :class => "class",
          :def => "def",
          :defined => "defined?",
          :defs => "def",
          :do_block => "do",
          :else => "else",
          :elsif => "elsif",
          :ensure => "ensure",
          :for => "for",
          :hash => :lbrace,
          :if => "if",
          :lambda => [:tlambda, "lambda"],
          :module => "module",
          :next => "next",
          :paren => :lparen,
          :qwords_literal => :qwords_beg,
          :words_literal => :words_beg,
          :qsymbols_literal => :qsymbols_beg,
          :symbols_literal => :symbols_beg,
          :redo => "redo",
          :regexp_literal => :regexp_beg,
          :rescue => "rescue",
          :rest_param => "*",
          :retry => "retry",
          :return => "return",
          :return0 => "return",
          :sclass => "class",
          :string_embexpr => :embexpr_beg,
          :string_literal => [:tstring_beg, :heredoc_beg],
          :super => "super",
          :symbol => :symbeg,
          :top_const_ref => "::",
          :undef => "undef",
          :unless => "unless",
          :until => "until",
          :when => "when",
          :while => "while",
          :xstring_literal => :backtick,
          :yield => "yield",
          :yield0 => "yield",
          :zsuper => "super"
        }
        REV_MAPPINGS = {}

        AST_TOKENS = [:CHAR, :backref, :const, :cvar, :gvar, :heredoc_end, :ident,
          :int, :float, :ivar, :label, :period, :regexp_end, :tstring_content, :backtick]

        COMMENT_SKIP_NODE_TYPES = [
          :comment,
          :void_stmt,
          :list
        ].freeze

        MAPPINGS.each do |k, v|
          if Array === v
            v.each {|vv| (REV_MAPPINGS[vv] ||= []) << k }
          else
            (REV_MAPPINGS[v] ||= []) << k
          end
        end

        PARSER_EVENT_TABLE.each do |event, arity|
          node_class = AstNode.node_class_for(event)

          if arity == 0 && /_new\z/ =~ event.to_s
            module_eval(<<-eof, __FILE__, __LINE__ + 1)
              def on_#{event}(*args)
                #{node_class}.new(:list, args, :listchar => charno...charno, :listline => lineno..lineno)
              end
            eof
          elsif /_add(_.+)?\z/ =~ event.to_s
            module_eval(<<-eof, __FILE__, __LINE__ + 1)
              begin; undef on_#{event}; rescue NameError; end
              def on_#{event}(list, item)
                list.push(item)
                list
              end
            eof
          elsif MAPPINGS.key?(event)
            module_eval(<<-eof, __FILE__, __LINE__ + 1)
              begin; undef on_#{event}; rescue NameError; end
              def on_#{event}(*args)
                visit_event #{node_class}.new(:#{event}, args)
              end
            eof
          else
            module_eval(<<-eof, __FILE__, __LINE__ + 1)
              begin; undef on_#{event}; rescue NameError; end
              def on_#{event}(*args)
                #{node_class}.new(:#{event}, args, :listline => lineno..lineno, :listchar => charno...charno)
              end
            eof
          end
        end

        SCANNER_EVENTS.each do |event|
          ast_token = AST_TOKENS.include?(event)
          module_eval(<<-eof, __FILE__, __LINE__ + 1)
            begin; undef on_#{event}; rescue NameError; end
            def on_#{event}(tok)
              visit_ns_token(:#{event}, tok, #{ast_token.inspect})
            end
          eof
        end

        REV_MAPPINGS.select {|k, _v| k.is_a?(Symbol) }.each do |pair|
          event = pair.first
          ast_token = AST_TOKENS.include?(event)
          module_eval(<<-eof, __FILE__, __LINE__ + 1)
            begin; undef on_#{event}; rescue NameError; end
            def on_#{event}(tok)
              (@map[:#{event}] ||= []) << [lineno, charno]
              visit_ns_token(:#{event}, tok, #{ast_token.inspect})
            end
          eof
        end

        [:kw, :op].each do |event|
          module_eval(<<-eof, __FILE__, __LINE__ + 1)
            begin; undef on_#{event}; rescue NameError; end
            def on_#{event}(tok)
              unless @last_ns_token == [:kw, "def"] ||
                  (@tokens.last && @tokens.last[0] == :symbeg)
                (@map[tok] ||= []) << [lineno, charno]
              end
              visit_ns_token(:#{event}, tok, true)
            end
          eof
        end

        [:nl, :ignored_nl].each do |event|
          module_eval(<<-eof, __FILE__, __LINE__ + 1)
            begin; undef on_#{event}; rescue NameError; end
            def on_#{event}(tok)
              add_token(:#{event}, tok)
              @newline = true
              @charno += tok ? tok.length : 0
            end
          eof
        end

        undef on_sp

        def on_sp(tok)
          add_token(:sp, tok)
          @charno += tok.length
        end

        def visit_event(node)
          map = @map[MAPPINGS[node.type]]
          lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
          node.source_range = Range.new(sstart, @ns_charno - 1)
          node.line_range = Range.new(lstart, lineno)
          if node.respond_to?(:block)
            sr = node.block.source_range
            lr = node.block.line_range
            node.block.source_range = Range.new(sr.first, @tokens.last[2][1] - 1)
            node.block.line_range = Range.new(lr.first, @tokens.last[2][0])
          end
          node
        end

        def visit_event_arr(node)
          mapping = MAPPINGS[node.type].find {|k| @map[k] && !@map[k].empty? }
          lstart, sstart = *@map[mapping].pop
          node.source_range = Range.new(sstart, @ns_charno - 1)
          node.line_range = Range.new(lstart, lineno)
          node
        end

        def visit_ns_token(token, data, ast_token = false)
          add_token(token, data)
          ch = charno
          @last_ns_token = [token, data]
          @charno += data.length
          @ns_charno = charno
          @newline = [:semicolon, :comment, :kw, :op, :lparen, :lbrace].include?(token)
          if ast_token
            AstNode.new(token, [data], :line => lineno..lineno, :char => ch..charno - 1, :token => true)
          end
        end

        def add_token(token, data)
          if @percent_ary
            if token == :words_sep && data !~ /\s\z/
              rng = @percent_ary.source_range
              rng = Range.new(rng.first, rng.last + data.length)
              @percent_ary.source_range = rng
              @tokens << [token, data, [lineno, charno]]
              @percent_ary = nil
              return
            elsif token == :tstring_end && data =~ /\A\s/
              rng = @percent_ary.source_range
              rng = Range.new(rng.first, rng.last + data.length)
              @percent_ary.source_range = rng
              @tokens << [token, data, [lineno, charno]]
              @percent_ary = nil
              return
            end
          end

          if @tokens.last && (@tokens.last[0] == :symbeg ||
              (@tokens.last[0] == :symbol && token.to_s =~ /^tstring/))
            @tokens[-1] = [:symbol, @tokens.last[1] + data, @tokens.last[2]]
          elsif @heredoc_state == :started
            @heredoc_tokens << [token, data, [lineno, charno]]

            # fix ripper encoding of heredoc bug
            # (see http://bugs.ruby-lang.org/issues/6200)
            data.force_encoding(file_encoding) if file_encoding

            @heredoc_state = :ended if token == :heredoc_end
          elsif (token == :nl || token == :comment) && @heredoc_state == :ended
            @heredoc_tokens.unshift([token, data, [lineno, charno]])
            @tokens += @heredoc_tokens
            @heredoc_tokens = nil
            @heredoc_state = nil
          else
            @tokens << [token, data, [lineno, charno]]
            if token == :heredoc_beg
              @heredoc_state = :started
              @heredoc_tokens = []
            end
          end
        end

        undef on_program
        undef on_assoc_new
        undef on_array
        undef on_hash
        undef on_bare_assoc_hash
        undef on_assoclist_from_args
        undef on_aref
        undef on_aref_field
        undef on_lbracket
        undef on_rbracket
        undef on_string_literal
        undef on_lambda
        undef on_unary
        undef on_string_content
        undef on_rescue
        undef on_void_stmt
        undef on_params
        undef on_label
        undef on_comment
        undef on_embdoc_beg
        undef on_embdoc
        undef on_embdoc_end
        undef on_parse_error
        undef on_bodystmt
        undef on_top_const_ref
        undef on_const_path_ref
        undef on_dyna_symbol

        def on_program(*args)
          args.first
        end

        def on_body_stmt(*args)
          args.compact.size == 1 ? args.first : AstNode.new(:list, args)
        end
        alias on_bodystmt on_body_stmt

        def on_assoc_new(*args)
          AstNode.new(:assoc, args)
        end

        def on_hash(*args)
          visit_event AstNode.new(:hash, args.first || [])
        end

        def on_bare_assoc_hash(*args)
          AstNode.new(:list, args.first)
        end

        def on_assoclist_from_args(*args)
          args.first
        end

        def on_unary(op, val)
          map = @map[op.to_s[0, 1]]
          lstart, sstart = *(map ? map.pop : [lineno, @ns_charno - 1])
          node = AstNode.node_class_for(:unary).new(:unary, [op, val])
          node.source_range = Range.new(sstart, @ns_charno - 1)
          node.line_range = Range.new(lstart, lineno)
          node
        end

        def on_aref(*args)
          @map[:lbracket].pop
          ll, lc = *@map[:aref].shift
          sr = args.first.source_range.first..lc
          lr = args.first.line_range.first..ll
          AstNode.new(:aref, args, :char => sr, :line => lr)
        end

        def on_aref_field(*args)
          @map[:lbracket].pop
          AstNode.new(:aref_field, args,
                      :listline => lineno..lineno, :listchar => charno...charno)
        end

        def on_array(other)
          node = AstNode.node_class_for(:array).new(:array, [other])
          map = @map[MAPPINGS[node.type]]
          if map && !map.empty?
            lstart, sstart = *map.pop
            node.source_range = Range.new(sstart, @ns_charno - 1)
            node.line_range = Range.new(lstart, lineno)
          else
            sstart = other.source_range.begin
            lstart = other.line_range.begin
            node.source_range = Range.new(sstart, @ns_charno - 1)
            node.line_range = Range.new(lstart, lineno)
            node.source_range = other.source_range
            node.line_range = other.line_range
          end
          node
        end

        def on_lbracket(tok)
          (@map[:lbracket] ||= []) << [lineno, charno]
          visit_ns_token(:lbracket, tok, false)
        end

        def on_rbracket(tok)
          (@map[:aref] ||= []) << [lineno, charno]
          visit_ns_token(:rbracket, tok, false)
        end

        def on_dyna_symbol(sym)
          rng = if sym.source_range.to_a.size == 0 # rubocop:disable Style/ZeroLengthPredicate
                  (sym.source_range.begin - 3)...sym.source_range.end
                else
                  (sym.source_range.begin - 2)..(sym.source_range.end + 1)
                end
          AstNode.new(:dyna_symbol, [sym], :line => lineno..lineno,
            :listline => lineno..lineno, :listchar => rng, :char => rng)
        end

        def on_top_const_ref(*args)
          type = :top_const_ref
          node = AstNode.node_class_for(type).new(type, args)
          mapping = @map[MAPPINGS[type]]
          extra_op = mapping.last[1] + 2 == charno ? mapping.pop : nil
          lstart, sstart = *mapping.pop
          node.source_range = Range.new(sstart, args.last.source_range.last)
          node.line_range = Range.new(lstart, args.last.line_range.last)
          mapping.push(extra_op) if extra_op
          node
        end

        def on_const_path_ref(*args)
          ReferenceNode.new(:const_path_ref, args, :listline => lineno..lineno, :listchar => charno..charno)
        end

        [:if_mod, :unless_mod, :while_mod, :until_mod].each do |kw|
          node_class = AstNode.node_class_for(kw)
          module_eval(<<-eof, __FILE__, __LINE__ + 1)
            begin; undef on_#{kw}; rescue NameError; end
            def on_#{kw}(*args)
              mapping = @map[#{kw.to_s.sub(/_mod$/, '').inspect}]
              mapping.pop if mapping
              sr = args.last.source_range.first..args.first.source_range.last
              lr = args.last.line_range.first..args.first.line_range.last
              #{node_class}.new(:#{kw}, args, :line => lr, :char => sr)
            end
          eof
        end

        %w(symbols qsymbols words qwords).each do |kw|
          module_eval(<<-eof, __FILE__, __LINE__ + 1)
            begin; undef on_#{kw}_new; rescue NameError; end
            def on_#{kw}_new(*args)
              node = LiteralNode.new(:#{kw}_literal, args)
              @percent_ary = node
              if @map[:#{kw}_beg]
                lstart, sstart = *@map[:#{kw}_beg].pop
                node.source_range = Range.new(sstart, @ns_charno-1)
                node.line_range = Range.new(lstart, lineno)
              end
              node
            end

            begin; undef on_#{kw}_add; rescue NameError; end
            def on_#{kw}_add(list, item)
              last = @source[@ns_charno,1] == "\n" ? @ns_charno - 1 : @ns_charno
              list.source_range = (list.source_range.first..last)
              list.line_range = (list.line_range.first..lineno)
              list.push(item)
              list
            end
          eof
        end

        def on_string_literal(*args)
          node = visit_event_arr(LiteralNode.new(:string_literal, args))
          if args.size == 1
            r = args[0].source_range
            if node.source_range != Range.new(r.first - 1, r.last + 1)
              klass = AstNode.node_class_for(node[0].type)
              r = Range.new(node.source_range.first + 1, node.source_range.last - 1)
              node[0] = klass.new(node[0].type, [@source[r]], :line => node.line_range, :char => r)
            end
          end
          node
        end

        def on_lambda(*args)
          visit_event_arr AstNode.new(:lambda, args)
        end

        def on_string_content(*args)
          chr_rng = args.empty? ? charno...charno : charno..charno
          AstNode.new(:string_content, args, :listline => lineno..lineno, :listchar => chr_rng)
        end

        def on_rescue(exc, *args)
          exc = AstNode.new(:list, exc) if exc
          visit_event AstNode.new(:rescue, [exc, *args])
        end

        def on_void_stmt
          AstNode.new(:void_stmt, [], :line => lineno..lineno, :char => charno...charno)
        end

        def on_params(*args)
          args.map! do |arg|
            next arg unless arg.class == Array

            if arg.first.class == Array
              arg.map! do |sub_arg|
                next sub_arg unless sub_arg.class == Array
                type = sub_arg[0].type == :label ?
                  :named_arg : :unnamed_optional_arg
                AstNode.new(type, sub_arg, :listline => lineno..lineno, :listchar => charno..charno)
              end
            end

            AstNode.new(:list, arg, :listline => lineno..lineno, :listchar => charno..charno)
          end

          ParameterNode.new(:params, args, :listline => lineno..lineno, :listchar => charno..charno)
        end

        def on_label(data)
          add_token(:label, data)
          ch = charno
          @charno += data.length
          @ns_charno = charno
          AstNode.new(:label, [data[0...-1]], :line => lineno..lineno, :char => ch..charno - 1, :token => true)
        end

        def on_comment(comment)
          not_comment = false
          if @last_ns_token.nil? || @last_ns_token.empty?
            if comment =~ SourceParser::SHEBANG_LINE && !@encoding_line
              @shebang_line = comment
              not_comment = true
            elsif comment =~ SourceParser::ENCODING_LINE
              @encoding_line = comment
              not_comment = true
            elsif comment =~ SourceParser::FROZEN_STRING_LINE
              @frozen_string_line = comment
              not_comment = true
            end
          end

          ch = charno
          visit_ns_token(:comment, comment)
          if not_comment
            @last_ns_token = nil
            return
          end

          source_range = ch..(charno - 1)
          comment = comment.gsub(/^(\#+)\s{0,1}/, '').chomp
          append_comment = @comments[lineno - 1]

          hash_flag = $1 == '##' ? true : false

          if append_comment && @comments_last_column &&
             @comments_last_column == column && comment_starts_line?(ch)
            @comments.delete(lineno - 1)
            @comments_flags[lineno] = @comments_flags[lineno - 1]
            @comments_flags.delete(lineno - 1)
            range = @comments_range.delete(lineno - 1)
            source_range = range.first..source_range.last
            comment = append_comment + "\n" + comment
          end

          @comments[lineno] = comment
          @comments_range[lineno] = source_range
          @comments_flags[lineno] = hash_flag unless append_comment
          @comments_last_column = column
        end

        def on_embdoc_beg(text)
          visit_ns_token(:embdoc_beg, text)
          @embdoc_start = charno - text.length
          @embdoc = String.new("")
        end

        def on_embdoc(text)
          visit_ns_token(:embdoc, text)
          @embdoc << text
        end

        def on_embdoc_end(text)
          visit_ns_token(:embdoc_end, text)
          @comments_last_column = nil
          @comments[lineno] = @embdoc
          @comments_range[lineno] = @embdoc_start...charno
          @embdoc_start = nil
          @embdoc = nil
        end

        def on_parse_error(msg)
          raise ParserSyntaxError, "syntax error in `#{file}`:(#{lineno},#{column}): #{msg}"
        end
        alias compile_error on_parse_error

        def comment_starts_line?(charno)
          (charno - 1).downto(0) do |i|
            ch = @source[i]
            break if ch == "\n"
            return false if ch != " " && ch != "\t"
          end
          true
        end

        def insert_comments
          root.traverse do |node|
            next if COMMENT_SKIP_NODE_TYPES.include?(node.type) || node.parent.type != :list

            # never attach comments to if/unless mod nodes
            if node.type == :if_mod || node.type == :unless_mod
              node = node.then_block
            end

            # check upwards from line before node; check node's line at the end
            ((node.line - 1).downto(node.line - 2).to_a + [node.line]).each do |line|
              comment = @comments[line]
              if comment && !comment.empty?
                add_comment(line, node)
                break
              end
            end

            @comments.keys.each do |line|
              add_comment(line, nil, node) if node.line > line
            end
          end

          # insert any lone unadded comments before node
          root.traverse do |node|
            next if node.type == :list || node.parent.type != :list
            @comments.keys.each do |line|
              next unless node.line_range.include?(line)
              pick = nil
              node.traverse do |subnode|
                next unless subnode.type == :list
                pick ||= subnode
                next unless subnode.line_range.include?(line)
                pick = subnode
              end
              add_comment(line, nil, pick, true) if pick
            end
          end unless @comments.empty?

          # insert all remaining comments
          @comments.each do |line, _comment|
            add_comment(line, nil, root, true)
          end

          @comments = {}
        end

        def add_comment(line, node = nil, before_node = nil, into = false)
          comment = @comments[line]
          source_range = @comments_range[line]
          line_range = ((line - comment.count("\n"))..line)
          if node.nil?
            node = CommentNode.new(:comment, [comment], :line => line_range, :char => source_range)
            if into
              before_node.push(node)
              before_node.unfreeze
              node.parent = before_node
            elsif before_node
              parent_node = before_node.parent
              idx = parent_node.index(before_node)
              parent_node.insert(idx, node)
              parent_node.unfreeze
              node.parent = parent_node
            end
          end
          node.docstring = comment
          node.docstring_hash_flag = @comments_flags[line]
          node.docstring_range = line_range
          @comments.delete(line)
          @comments_range.delete(line)
          @comments_flags.delete(line)
        end

        def freeze_tree(node = nil)
          @tokens = @tokens.sort_by {|t| t.last }
          nodes = [node || root]
          until nodes.empty?
            p_node = nodes.shift
            p_node.children.each do |child|
              child.parent = p_node
              nodes << child
            end
          end
        end
      end if defined?(::Ripper)
    end
  end
end
yard-0.9.37/lib/yard/parser/ruby/token_resolver.rb000066400000000000000000000117071466601756300221450ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Parser
    module Ruby
      # Supports {#each} enumeration over a source's tokens, yielding
      # the token and a possible {CodeObjects::Base} associated with the
      # constant or identifier token.
      class TokenResolver
        include Enumerable
        include CodeObjects::NamespaceMapper

        # Creates a token resolver for given source.
        #
        # @param source [String] the source code to tokenize
        # @param namespace [CodeObjects::Base] the object/namespace to resolve from
        def initialize(source, namespace = Registry.root)
          @tokens = RubyParser.parse(source, '(tokenize)').tokens
          raise ParserSyntaxError if @tokens.empty? && !source.empty?
          @default_namespace = namespace
        end

        # Iterates over each token, yielding the token and a possible code
        # object that is associated with the token.
        #
        # @yieldparam token [Array(Symbol,String,Array(Integer,Integer))] the
        #   current token object being iterated
        # @yieldparam object [CodeObjects::Base, nil] the fully qualified code
        #   object associated with the current token, or nil if there is no object
        #   for the yielded token.
        # @example Yielding code objects
        #   r = TokenResolver.new("A::B::C")
        #   r.each do |tok, obj|
        #     if obj
        #       puts "#{tok[0]} -> #{obj.path.inspect}"
        #     else
        #       puts "No object: #{tok.inspect}"
        #     end
        #   end
        #
        #   # Prints:
        #   # :const -> "A"
        #   # No object: [:op, "::"]
        #   # :const -> "A::B"
        #   # No object: [:op, "::"]
        #   # :const -> "A::B::C"
        def each
          @states = []
          push_state
          @tokens.each do |token|
            yield_obj = false

            if skip_group && [:const, :ident, :op, :period].include?(token[0])
              yield token, nil
              next
            else
              self.skip_group = false
            end

            case token[0]
            when :const
              lookup(token[0], token[1])
              yield_obj = true
              self.last_sep = nil
            when :ident
              lookup(token[0], token[1])
              yield_obj = true
              self.last_sep = nil
            when :op, :period
              self.last_sep = token[1]
              unless CodeObjects.types_for_separator(token[1])
                self.object = nil
                self.last_sep = nil
              end
            when :lparen
              push_state
            when :rparen
              pop_state
            else
              self.object = nil
            end

            yield token, (yield_obj ? object : nil)

            if next_object
              self.object = next_object
              self.next_object = nil
            end
            self.skip_group = true if yield_obj && object.nil?
          end
        end

        def self.state_attr(*attrs)
          attrs.each do |attr|
            define_method(attr) { @states.last[attr.to_sym] }
            define_method("#{attr}=") {|v| @states.last[attr.to_sym] = v }
            protected attr, :"#{attr}="
          end
        end

        private

        def push_state
          @states.push :object => nil, :skip_group => false, :last_sep => nil
        end

        def pop_state
          @states.pop
        end

        state_attr :object, :next_object, :skip_group, :last_sep

        def lookup(toktype, name)
          types = object_resolved_types
          return self.object = nil if types.empty?

          if toktype == :const
            types.any? do |type|
              prefix = type ? type.path : ""
              prefix += last_sep.to_s if separators.include?(last_sep.to_s)
              self.object = Registry.resolve(@default_namespace, "#{prefix}#{name}", true)
            end
          else # ident
            types.any? do |type|
              obj = Registry.resolve(type, name, true)
              if obj.nil? && name == "new"
                obj = Registry.resolve(object, "#initialize", true)
                self.next_object = object if obj.nil?
              end
              self.object = obj
            end
          end
        end

        def object_resolved_types(obj = object)
          return [obj] unless obj.is_a?(CodeObjects::MethodObject)

          resolved_types = []
          tags = obj.tags(:return)
          tags += obj.tags(:overload).map {|o| o.tags(:return) }.flatten
          tags.each do |tag|
            next if tag.types.nil?
            tag.types.each do |type|
              type = type.sub(/<.+>/, '')
              if type == "self"
                resolved_types << obj.parent
              else
                type_obj = Registry.resolve(obj, type, true)
                resolved_types << type_obj if type_obj
              end
            end
          end

          resolved_types
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/parser/source_parser.rb000066400000000000000000000470041466601756300207760ustar00rootroot00000000000000# frozen_string_literal: true
require 'stringio'

module YARD
  module Parser
    # Raised when an object is recognized but cannot be documented. This
    # generally occurs when the Ruby syntax used to declare an object is
    # too dynamic in nature.
    class UndocumentableError < RuntimeError; end

    # Raised when the parser sees a Ruby syntax error
    class ParserSyntaxError < UndocumentableError; end

    # Responsible for parsing a list of files in order. The
    # {#parse} method of this class can be called from the
    # {SourceParser#globals} globals state list to re-enter
    # parsing for the remainder of files in the list recursively.
    #
    # @see Processor#parse_remaining_files
    class OrderedParser
      # @return [Array] the list of remaining files to parse
      attr_accessor :files

      # Creates a new OrderedParser with the global state and a list
      # of files to parse.
      #
      # @note OrderedParser sets itself as the +ordered_parser+ key on
      #   global_state for later use in {Handlers::Processor}.
      # @param [OpenStruct] global_state a structure containing all global
      #   state during parsing
      # @param [Array] files the list of files to parse
      def initialize(global_state, files)
        @global_state = global_state
        @files = files.dup
        @global_state.ordered_parser = self
      end

      # Parses the remainder of the {#files} list.
      #
      # @see Processor#parse_remaining_files
      def parse
        until files.empty?
          file = files.shift
          log.capture("Parsing #{file}") do
            SourceParser.new(SourceParser.parser_type, @global_state).parse(file)
          end
        end
      end
    end

    # Responsible for parsing a source file into the namespace. Parsing
    # also invokes handlers to process the parsed statements and generate
    # any code objects that may be recognized.
    #
    # == Custom Parsers
    # SourceParser allows custom parsers to be registered and called when
    # a certain filetype is recognized. To register a parser and hook it
    # up to a set of file extensions, call {register_parser_type}
    #
    # @see register_parser_type
    # @see Handlers::Base
    # @see CodeObjects::Base
    class SourceParser
      SHEBANG_LINE  = /\A\s*#!\S+/
      ENCODING_LINE = %r{\A(?:\s*#*!.*\r?\n)?\s*(?:#+|/\*+|//+).*coding\s*[:=]{1,2}\s*([a-z\d_\-]+)}i
      FROZEN_STRING_LINE = /frozen(-|_)string(-|_)literal:\s+(true|false)/i

      # The default glob of files to be parsed.
      # @since 0.9.0
      DEFAULT_PATH_GLOB = ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp,rb}"]

      # Byte order marks for various encodings
      # @since 0.7.0
      ENCODING_BYTE_ORDER_MARKS = {
        'utf-8' => String.new("\xEF\xBB\xBF"),
        # Not yet supported
        # 'utf-16be' => "\xFE\xFF",
        # 'utf-16le' => "\xFF\xFE",
        # 'utf-32be' => "\x00\x00\xFF\xFE",
        # 'utf-32le' => "\xFF\xFE",
      }

      class << self
        # @return [Symbol] the default parser type (defaults to :ruby)
        attr_reader :parser_type

        def parser_type=(value)
          @parser_type = validated_parser_type(value)
        end

        # Parses a path or set of paths
        #
        # @param [String, Array] paths a path, glob, or list of paths to
        #   parse
        # @param [Array] excluded a list of excluded path matchers
        # @param [Fixnum] level the logger level to use during parsing. See
        #   {YARD::Logger}
        # @return [void]
        def parse(paths = DEFAULT_PATH_GLOB, excluded = [], level = log.level)
          log.debug("Parsing #{paths.inspect} with `#{parser_type}` parser")
          excluded = excluded.map do |path|
            case path
            when Regexp; path
            else Regexp.new(path.to_s, Regexp::IGNORECASE)
            end
          end
          files = [paths].flatten.
            map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c,cc,cxx,cpp}" : p }.
            map {|p| p.include?("*") ? Dir[p].sort_by {|d| [d.length, d] } : p }.flatten.
            reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }.
            map {|p| p.encoding == Encoding.default_external ? p : p.dup.force_encoding(Encoding.default_external) }

          log.enter_level(level) do
            parse_in_order(*files.uniq)
          end
        end

        # Parses a string +content+
        #
        # @param [String] content the block of code to parse
        # @param [Symbol] ptype the parser type to use. See {parser_type}.
        # @return the parser object that was used to parse +content+
        def parse_string(content, ptype = parser_type)
          new(ptype).parse(StringIO.new(content))
        end

        # Tokenizes but does not parse the block of code
        #
        # @param [String] content the block of code to tokenize
        # @param [Symbol] ptype the parser type to use. See {parser_type}.
        # @return [Array] a list of tokens
        def tokenize(content, ptype = parser_type)
          new(ptype).tokenize(content)
        end

        # Registers a new parser type.
        #
        # @example Registering a parser for "java" files
        #   SourceParser.register_parser_type :java, JavaParser, 'java'
        # @param [Symbol] type a symbolic name for the parser type
        # @param [Base] parser_klass a class that implements parsing and tokenization
        # @param [Array, String, Regexp] extensions a list of extensions or a
        #   regex to match against the file extension
        # @return [void]
        # @see Parser::Base
        def register_parser_type(type, parser_klass, extensions = nil)
          unless Base > parser_klass
            raise ArgumentError, "expecting parser_klass to be a subclass of YARD::Parser::Base"
          end
          parser_type_extensions[type.to_sym] = extensions if extensions
          parser_types[type.to_sym] = parser_klass
        end

        # @return [Hash{Symbol=>Object}] a list of registered parser types
        # @private
        # @since 0.5.6
        def parser_types; @@parser_types ||= {} end
        def parser_types=(value) @@parser_types = value end

        # @return [Hash] a list of registered parser type extensions
        # @private
        # @since 0.5.6
        def parser_type_extensions; @@parser_type_extensions ||= {} end
        def parser_type_extensions=(value) @@parser_type_extensions = value end

        # Finds a parser type that is registered for the extension. If no
        # type is found, the default Ruby type is returned.
        #
        # @return [Symbol] the parser type to be used for the extension
        # @since 0.5.6
        def parser_type_for_extension(extension)
          type = parser_type_extensions.find do |_t, exts|
            [exts].flatten.any? {|ext| ext === extension }
          end
          validated_parser_type(type ? type.first : :ruby)
        end

        # Returns the validated parser type. Basically, enforces that :ruby
        # type is never set if the Ripper library is not available
        #
        # @param [Symbol] type the parser type to set
        # @return [Symbol] the validated parser type
        # @private
        def validated_parser_type(type)
          !defined?(::Ripper) && type == :ruby ? :ruby18 : type
        end

        # @group Parser Callbacks

        # Registers a callback to be called before a list of files is parsed
        # via {parse}. The block passed to this method will be called on
        # subsequent parse calls.
        #
        # @example Installing a simple callback
        #   SourceParser.before_parse_list do |files, globals|
        #     puts "Starting to parse..."
        #   end
        #   YARD.parse('lib/**/*.rb')
        #   # prints "Starting to parse..."
        #
        # @example Setting global state
        #   SourceParser.before_parse_list do |files, globals|
        #     globals.method_count = 0
        #   end
        #   SourceParser.after_parse_list do |files, globals|
        #     puts "Found #{globals.method_count} methods"
        #   end
        #   class MyCountHandler < Handlers::Ruby::Base
        #     handles :def, :defs
        #     process { globals.method_count += 1 }
        #   end
        #   YARD.parse
        #   # Prints: "Found 37 methods"
        #
        # @example Using a global callback to cancel parsing
        #   SourceParser.before_parse_list do |files, globals|
        #     return false if files.include?('foo.rb')
        #   end
        #
        #   YARD.parse(['foo.rb', 'bar.rb']) # callback cancels this method
        #   YARD.parse('bar.rb') # parses normally
        #
        # @yield [files, globals] the yielded block is called once before
        #   parsing all files
        # @yieldparam [Array] files the list of files that will be parsed.
        # @yieldparam [OpenStruct] globals a global structure to store arbitrary
        #   state for post processing (see {Handlers::Processor#globals})
        # @yieldreturn [Boolean] if the block returns +false+, parsing is
        #   cancelled.
        # @return [Proc] the yielded block
        # @see after_parse_list
        # @see before_parse_file
        # @since 0.7.0
        def before_parse_list(&block)
          before_parse_list_callbacks << block
        end

        # Registers a callback to be called after a list of files is parsed
        # via {parse}. The block passed to this method will be called on
        # subsequent parse calls.
        #
        # @example Printing results after parsing occurs
        #   SourceParser.after_parse_list do
        #     puts "Finished parsing!"
        #   end
        #   YARD.parse
        #   # Prints "Finished parsing!" after parsing files
        # @yield [files, globals] the yielded block is called once before
        #   parsing all files
        # @yieldparam [Array] files the list of files that will be parsed.
        # @yieldparam [OpenStruct] globals a global structure to store arbitrary
        #   state for post processing (see {Handlers::Processor#globals})
        # @yieldreturn [void] the return value for the block is ignored.
        # @return [Proc] the yielded block
        # @see before_parse_list
        # @see before_parse_file
        # @since 0.7.0
        def after_parse_list(&block)
          after_parse_list_callbacks << block
        end

        # Registers a callback to be called before an individual file is parsed.
        # The block passed to this method will be called on subsequent parse
        # calls.
        #
        # To register a callback that is called before the entire list of files
        # is processed, see {before_parse_list}.
        #
        # @example Installing a simple callback
        #   SourceParser.before_parse_file do |parser|
        #     puts "I'm parsing #{parser.file}"
        #   end
        #   YARD.parse('lib/**/*.rb')
        #   # prints:
        #   "I'm parsing lib/foo.rb"
        #   "I'm parsing lib/foo_bar.rb"
        #   "I'm parsing lib/last_file.rb"
        #
        # @example Cancel parsing of any test_*.rb files
        #   SourceParser.before_parse_file do |parser|
        #     return false if parser.file =~ /^test_.+\.rb$/
        #   end
        #
        # @yield [parser] the yielded block is called once before each
        #   file that is parsed. This might happen many times for a single
        #   codebase.
        # @yieldparam [SourceParser] parser the parser object that will {#parse}
        #   the file.
        # @yieldreturn [Boolean] if the block returns +false+, parsing for
        #   the file is cancelled.
        # @return [Proc] the yielded block
        # @see after_parse_file
        # @see before_parse_list
        # @since 0.7.0
        def before_parse_file(&block)
          before_parse_file_callbacks << block
        end

        # Registers a callback to be called after an individual file is parsed.
        # The block passed to this method will be called on subsequent parse
        # calls.
        #
        # To register a callback that is called after the entire list of files
        # is processed, see {after_parse_list}.
        #
        # @example Printing the length of each file after it is parsed
        #   SourceParser.after_parse_file do |parser|
        #     puts "#{parser.file} is #{parser.contents.size} characters"
        #   end
        #   YARD.parse('lib/**/*.rb')
        #   # prints:
        #   "lib/foo.rb is 1240 characters"
        #   "lib/foo_bar.rb is 248 characters"
        #
        # @yield [parser] the yielded block is called once after each file
        #   that is parsed. This might happen many times for a single codebase.
        # @yieldparam [SourceParser] parser the parser object that parsed
        #   the file.
        # @yieldreturn [void] the return value for the block is ignored.
        # @return [Proc] the yielded block
        # @see before_parse_file
        # @see after_parse_list
        # @since 0.7.0
        def after_parse_file(&block)
          after_parse_file_callbacks << block
        end

        # @return [Array] the list of callbacks to be called before
        #   parsing a list of files. Should only be used for testing.
        # @since 0.7.0
        def before_parse_list_callbacks
          @before_parse_list_callbacks ||= []
        end

        # @return [Array] the list of callbacks to be called after
        #   parsing a list of files. Should only be used for testing.
        # @since 0.7.0
        def after_parse_list_callbacks
          @after_parse_list_callbacks ||= []
        end

        # @return [Array] the list of callbacks to be called before
        #   parsing a file. Should only be used for testing.
        # @since 0.7.0
        def before_parse_file_callbacks
          @before_parse_file_callbacks ||= []
        end

        # @return [Array] the list of callbacks to be called after
        #   parsing a file. Should only be used for testing.
        # @since 0.7.0
        def after_parse_file_callbacks
          @after_parse_file_callbacks ||= []
        end

        # @endgroup

        private

        # Parses a list of files in a queue.
        #
        # @param [Array] files a list of files to queue for parsing
        # @return [void]
        def parse_in_order(*files)
          global_state = OpenStruct.new

          return if before_parse_list_callbacks.any? do |cb|
            cb.call(files, global_state) == false
          end

          OrderedParser.new(global_state, files).parse

          after_parse_list_callbacks.each do |cb|
            cb.call(files, global_state)
          end
        end
      end

      register_parser_type :ruby,   Ruby::RubyParser
      register_parser_type :ruby18, Ruby::Legacy::RubyParser
      register_parser_type :c,      C::CParser, ['c', 'cc', 'cxx', 'cpp']

      self.parser_type = :ruby

      # @return [String] the filename being parsed by the parser.
      attr_accessor :file

      # @return [Symbol] the parser type associated with the parser instance.
      #   This should be set by the {#initialize constructor}.
      attr_reader :parser_type

      # @return [OpenStruct] an open struct containing arbitrary global state
      #   shared between files and handlers.
      # @since 0.7.0
      attr_reader :globals

      # @return [String] the contents of the file to be parsed
      # @since 0.7.0
      attr_reader :contents

      # @overload initialize(parser_type = SourceParser.parser_type, globals = nil)
      #   Creates a new parser object for code parsing with a specific parser type.
      #
      #   @param [Symbol] parser_type the parser type to use
      #   @param [OpenStruct] globals global state to be re-used across separate source files
      def initialize(parser_type = SourceParser.parser_type, globals1 = nil, globals2 = nil)
        globals = [true, false].include?(globals1) ? globals2 : globals1
        @file = '(stdin)'
        @globals = globals || OpenStruct.new
        self.parser_type = parser_type
      end

      # The main parser method. This should not be called directly. Instead,
      # use the class methods {parse} and {parse_string}.
      #
      # @param [String, #read, Object] content the source file to parse
      # @return [Object, nil] the parser object used to parse the source
      def parse(content = __FILE__)
        case content
        when String
          @file = File.cleanpath(content)
          content = convert_encoding(String.new(File.read_binary(file)))
          checksum = Registry.checksum_for(content)
          return if Registry.checksums[file] == checksum

          if Registry.checksums.key?(file)
            log.info "File '#{file}' was modified, re-processing..."
          end
          Registry.checksums[@file] = checksum
          self.parser_type = parser_type_for_filename(file)
        else
          content = content.read if content.respond_to? :read
        end

        @contents = content
        @parser = parser_class.new(content, file)

        self.class.before_parse_file_callbacks.each do |cb|
          return @parser if cb.call(self) == false
        end

        @parser.parse
        post_process

        self.class.after_parse_file_callbacks.each do |cb|
          cb.call(self)
        end

        @parser
      rescue ArgumentError, NotImplementedError => e
        log.warn("Cannot parse `#{file}': #{e.message}")
        log.backtrace(e, :warn)
      rescue ParserSyntaxError => e
        log.warn(e.message.capitalize)
        log.backtrace(e, :warn)
      end

      # Tokenizes but does not parse the block of code using the current {#parser_type}
      #
      # @param [String] content the block of code to tokenize
      # @return [Array] a list of tokens
      def tokenize(content)
        @parser = parser_class.new(content, file)
        @parser.tokenize
      end

      private

      # Searches for encoding line and forces encoding
      # @since 0.5.3
      def convert_encoding(content)
        return content unless content.respond_to?(:force_encoding)
        if content =~ ENCODING_LINE
          content.force_encoding($1)
        else
          content.force_encoding('binary')
          ENCODING_BYTE_ORDER_MARKS.each do |encoding, bom|
            bom.force_encoding('binary')
            if content.start_with?(bom)
              return content.sub(bom, '').force_encoding(encoding)
            end
          end
          content.force_encoding('utf-8') # UTF-8 is default encoding
          content
        end
      end

      # Runs a {Handlers::Processor} object to post process the parsed statements.
      # @return [void]
      def post_process
        return unless @parser.respond_to?(:enumerator)

        enumerator = @parser.enumerator
        if enumerator
          post = Handlers::Processor.new(self)
          post.process(enumerator)
        end
      end

      def parser_type=(value)
        @parser_type = self.class.validated_parser_type(value)
      end

      # Guesses the parser type to use depending on the file extension.
      #
      # @param [String] filename the filename to use to guess the parser type
      # @return [Symbol] a parser type that matches the filename
      def parser_type_for_filename(filename)
        ext = (File.extname(filename)[1..-1] || "").downcase
        type = self.class.parser_type_for_extension(ext)
        parser_type == :ruby18 && type == :ruby ? :ruby18 : type
      end

      # @since 0.5.6
      def parser_class
        klass = self.class.parser_types[parser_type]
        unless klass
          raise ArgumentError, "invalid parser type '#{parser_type}' or unrecognized file", caller[1..-1]
        end

        klass
      end
    end
  end
end
yard-0.9.37/lib/yard/rake/000077500000000000000000000000001466601756300152165ustar00rootroot00000000000000yard-0.9.37/lib/yard/rake/yardoc_task.rb000066400000000000000000000052721466601756300200540ustar00rootroot00000000000000# frozen_string_literal: true
require 'rake'
require 'rake/tasklib'

module YARD
  module Rake
    # The rake task to run {CLI::Yardoc} and generate documentation.
    class YardocTask < ::Rake::TaskLib
      # The name of the task
      # @return [String] the task name
      attr_accessor :name

      # Options to pass to {CLI::Yardoc}
      # @return [Array] the options passed to the commandline utility
      attr_accessor :options

      # Options to pass to {CLI::Stats}
      # @return [Array] the options passed to the stats utility
      attr_accessor :stats_options

      # The Ruby source files (and any extra documentation files separated by '-')
      # to process.
      # @example Task files assignment
      #   YARD::Rake::YardocTask.new do |t|
      #     t.files   = ['app/**/*.rb', 'lib/**/*.rb', '-', 'doc/FAQ.md', 'doc/Changes.md']
      #   end
      # @return [Array] a list of files
      attr_accessor :files

      # Runs a +Proc+ before the task
      # @return [Proc] a proc to call before running the task
      attr_accessor :before

      # Runs a +Proc+ after the task
      # @return [Proc] a proc to call after running the task
      attr_accessor :after

      # @return [Verifier, Proc] an optional {Verifier} to run against all objects
      #   being generated. Any object that the verifier returns false for will be
      #   excluded from documentation. This attribute can also be a lambda.
      # @see Verifier
      attr_accessor :verifier

      # Creates a new task with name +name+.
      #
      # @param [String, Symbol] name the name of the rake task
      # @yield a block to allow any options to be modified on the task
      # @yieldparam [YardocTask] _self the task object to allow any parameters
      #   to be changed.
      def initialize(name = :yard)
        @name = name
        @options = []
        @stats_options = []
        @files = []

        yield self if block_given?
        self.options += ENV['OPTS'].split(/[ ,]/) if ENV['OPTS']
        self.files   += ENV['FILES'].split(/[ ,]/) if ENV['FILES']
        self.options << '--no-stats' unless stats_options.empty?

        define
      end

      protected

      # Defines the rake task
      # @return [void]
      def define
        desc "Generate YARD Documentation" unless ::Rake.application.last_description
        task(name) do
          before.call if before.is_a?(Proc)
          yardoc = YARD::CLI::Yardoc.new
          yardoc.options[:verifier] = verifier if verifier
          yardoc.run(*(options + files))
          YARD::CLI::Stats.run(*(stats_options + ['--use-cache'])) unless stats_options.empty?
          after.call if after.is_a?(Proc)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/registry.rb000066400000000000000000000402141466601756300164720ustar00rootroot00000000000000# frozen_string_literal: true
require 'fileutils'
require 'digest/sha1'

module YARD
  # The +Registry+ is the centralized data store for all {CodeObjects} created
  # during parsing. The storage is a key value store with the object's path
  # (see {CodeObjects::Base#path}) as the key and the object itself as the value.
  # Object paths must be unique to be stored in the Registry. All lookups for
  # objects are done on the singleton Registry instance using the {Registry.at}
  # or {Registry.resolve} methods.
  #
  # == Saving / Loading a Registry
  # The registry is saved to a "yardoc file" (actually a directory), which can
  # be loaded back to perform any lookups. See {Registry.load!} and
  # {Registry.save} for information on saving and loading of a yardoc file.
  #
  # == Threading Notes
  # The registry class is a singleton class that is accessed directly in many
  # places across YARD. To mitigate threading issues, YARD (0.6.5+) makes
  # the Registry thread local. This means all access to a registry for a specific
  # object set must occur in the originating thread.
  #
  # @example Loading the Registry
  #   Registry.load!('/path/to/yardocfile') # loads all objects into memory
  #   Registry.at('YARD::CodeObjects::Base').docstring
  #   # => "+Base+ is the superclass of all code objects ..."
  # @example Getting an object by a specific path
  #   Registry.at('YARD::CodeObjects::Base#docstring')
  # @example Performing a lookup on a method anywhere in the inheritance tree
  #   Registry.resolve(P('YARD::CodeObjects::Base'), '#docstring', true)
  module Registry
    DEFAULT_YARDOC_FILE = ".yardoc"
    LOCAL_YARDOC_INDEX = File.expand_path(File.join(Config::CONFIG_DIR, 'gem_index'))
    DEFAULT_PO_DIR = "po"

    extend Enumerable

    class << self
      # @group Getting .yardoc File Locations

      # Returns the .yardoc file associated with a gem.
      #
      # @param [String] gem the name of the gem to search for
      # @param [String] ver_require an optional Gem version requirement
      # @param [Boolean] for_writing whether or not the method should search
      #   for writable locations
      # @return [String] if +for_writing+ is set to +true+, returns the best
      #   location suitable to write the .yardoc file. Otherwise, the first
      #   existing location associated with the gem's .yardoc file.
      # @return [nil] if +for_writing+ is set to false and no yardoc file
      #   is found, returns nil.
      def yardoc_file_for_gem(gem, ver_require = ">= 0", for_writing = false)
        specs = YARD::GemIndex.find_all_by_name(gem, ver_require)
        return if specs.empty?

        result = nil
        specs.reverse.each do |spec|
          if gem =~ /^yard-doc-/
            path = File.join(spec.full_gem_path, DEFAULT_YARDOC_FILE)
            result = File.exist?(path) && !for_writing ? path : nil
            result ? break : next
          end

          if for_writing
            result = global_yardoc_file(spec, for_writing) ||
                     old_global_yardoc_file(spec, for_writing) ||
                     local_yardoc_file(spec, for_writing)
          else
            result = local_yardoc_file(spec, for_writing) ||
                     global_yardoc_file(spec, for_writing) ||
                     old_global_yardoc_file(spec, for_writing)
          end

          break if result
        end

        result
      end

      # Gets/sets the yardoc filename
      # @return [String] the yardoc filename
      # @see DEFAULT_YARDOC_FILE
      attr_accessor :yardoc_file
      undef yardoc_file, yardoc_file=
      def yardoc_file=(v) Thread.current[:__yard_yardoc_file__] = v end

      def yardoc_file
        Thread.current[:__yard_yardoc_file__] ||= DEFAULT_YARDOC_FILE
      end

      # @group Loading Data from Disk

      # Loads the registry and/or parses a list of files
      #
      # @example Loads the yardoc file or parses files 'a', 'b' and 'c' (but not both)
      #   Registry.load(['a', 'b', 'c'])
      # @example Reparses files 'a' and 'b' regardless of whether yardoc file exists
      #   Registry.load(['a', 'b'], true)
      # @param [String, Array] files if +files+ is an Array, it should represent
      #   a list of files that YARD should parse into the registry. If reload is
      #   set to false and the yardoc file already exists, these files are skipped.
      #   If files is a String, it should represent the yardoc file to load
      #   into the registry.
      # @param [Boolean] reparse if reparse is false and a yardoc file already
      #   exists, any files passed in will be ignored.
      # @return [Registry] the registry object (for chaining)
      # @raise [ArgumentError] if files is not a String or Array
      def load(files = [], reparse = false)
        if files.is_a?(Array)
          if File.exist?(yardoc_file) && !reparse
            load_yardoc
          else
            size = thread_local_store.keys.size
            YARD.parse(files)
            save if thread_local_store.keys.size > size
          end
        elsif files.is_a?(String)
          load_yardoc(files)
        else
          raise ArgumentError, "Must take a list of files to parse or the .yardoc file to load."
        end
        self
      end

      # Loads a yardoc file directly
      #
      # @param [String] file the yardoc file to load.
      # @return [Registry] the registry object (for chaining)
      def load_yardoc(file = yardoc_file)
        clear
        thread_local_store.load(file)
        self
      end

      # Loads a yardoc file and forces all objects cached on disk into
      # memory. Equivalent to calling {load_yardoc} followed by {load_all}
      #
      # @param [String] file the yardoc file to load
      # @return [Registry] the registry object (for chaining)
      # @see #load_yardoc
      # @see #load_all
      # @since 0.5.1
      def load!(file = yardoc_file)
        clear
        thread_local_store.load!(file)
        self
      end

      # Forces all objects cached on disk into memory
      #
      # @example Loads all objects from disk
      #   Registry.load
      #   Registry.all.count #=> 0
      #   Registry.load_all
      #   Registry.all.count #=> 17
      # @return [Registry] the registry object (for chaining)
      # @since 0.5.1
      def load_all
        thread_local_store.load_all
        self
      end

      # @group Saving and Deleting Data from Disk

      # Saves the registry to +file+
      #
      # @param [String] file the yardoc file to save to
      # @return [Boolean] true if the file was saved
      def save(merge = false, file = yardoc_file)
        thread_local_store.save(merge, file)
      end

      # Deletes the yardoc file from disk
      # @return [void]
      def delete_from_disk
        thread_local_store.destroy
      end

      # @group Adding and Deleting Objects from the Registry

      # Registers a new object with the registry
      #
      # @param [CodeObjects::Base] object the object to register
      # @return [CodeObjects::Base] the registered object
      def register(object)
        return if object.is_a?(CodeObjects::Proxy)
        thread_local_store[object.path] = object
      end

      # Deletes an object from the registry
      # @param [CodeObjects::Base] object the object to remove
      # @return [void]
      def delete(object)
        thread_local_store.delete(object.path)
      end

      # Clears the registry
      # @return [void]
      def clear
        self.thread_local_store = RegistryStore.new
      end

      # Creates a pessmistic transactional lock on the database for writing.
      # Use with {YARD.parse} to ensure the database is not written multiple
      # times.
      #
      # @see locked_for_writing?
      def lock_for_writing(file = yardoc_file, &block)
        thread_local_store.lock_for_writing(file, &block)
      end

      # (see Serializers::YardocSerializer#locked_for_writing?)
      def locked_for_writing?(file = yardoc_file)
        thread_local_store.locked_for_writing?(file)
      end

      # @group Accessing Objects in the Registry

      # Iterates over {all} with no arguments
      def each(&block)
        all.each(&block)
      end

      # Returns all objects in the registry that match one of the types provided
      # in the +types+ list (if +types+ is provided).
      #
      # @example Returns all objects
      #   Registry.all
      # @example Returns all classes and modules
      #   Registry.all(:class, :module)
      # @param [Array] types an optional list of types to narrow the
      #   objects down by. Equivalent to performing a select:
      #     +Registry.all.select {|o| types.include(o.type) }+
      # @return [Array] the list of objects found
      # @see CodeObjects::Base#type
      def all(*types)
        if types.empty?
          thread_local_store.values.select {|obj| obj != root }
        else
          list = []
          types.each do |type|
            list += thread_local_store.values_for_type(type)
          end
          list
        end
      end

      # Returns the paths of all of the objects in the registry.
      # @param [Boolean] reload whether to load entire database
      # @return [Array] all of the paths in the registry.
      def paths(reload = false)
        thread_local_store.keys(reload).map(&:to_s)
      end

      # Returns the object at a specific path.
      # @param [String, :root] path the pathname to look for. If +path+ is +root+,
      #   returns the {root} object.
      # @return [CodeObjects::Base] the object at path
      # @return [nil] if no object is found
      def at(path) path ? thread_local_store[path] : nil end
      alias [] at

      # The root namespace object.
      # @return [CodeObjects::RootObject] the root object in the namespace
      def root; thread_local_store[:root] end

      # @param [String] name the locale name.
      # @return [I18n::Locale] the locale object for +name+.
      # @since 0.8.3
      def locale(name)
        thread_local_store.locale(name)
      end

      # Attempts to find an object by name starting at +namespace+, performing
      # a lookup similar to Ruby's method of resolving a constant in a namespace.
      #
      # @example Looks for instance method #reverse starting from A::B::C
      #   Registry.resolve(P("A::B::C"), "#reverse")
      # @example Looks for a constant in the root namespace
      #   Registry.resolve(nil, 'CONSTANT')
      # @example Looks for a class method respecting the inheritance tree
      #   Registry.resolve(myclass, 'mymethod', true)
      # @example Looks for a constant but returns a proxy if not found
      #   Registry.resolve(P('A::B::C'), 'D', false, true) # => #
      # @example Looks for a complex path from a namespace
      #   Registry.resolve(P('A::B'), 'B::D') # => #
      # @param [CodeObjects::NamespaceObject, nil] namespace the starting namespace
      #   (module or class). If +nil+ or +:root+, starts from the {root} object.
      # @param [String, Symbol] name the name (or complex path) to look for from
      #   +namespace+.
      # @param [Boolean] inheritance Follows inheritance chain (mixins, superclass)
      #   when performing name resolution if set to +true+.
      # @param [Boolean] proxy_fallback If +true+, returns a proxy representing
      #   the unresolved path (namespace + name) if no object is found.
      # @param [Symbol, nil] type the {CodeObjects::Base#type} that the resolved
      #   object must be equal to. No type checking if nil.
      # @return [CodeObjects::Base] the object if it is found
      # @return [CodeObjects::Proxy] a Proxy representing the object if
      #   +proxy_fallback+ is +true+.
      # @return [nil] if +proxy_fallback+ is +false+ and no object was found.
      # @see P
      def resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil)
        thread_local_resolver.lookup_by_path name,
          :namespace => namespace, :inheritance => inheritance,
          :proxy_fallback => proxy_fallback, :type => type
      end

      # @group Managing Source File Checksums

      # @return [Hash{String => String}] a set of checksums for files
      def checksums
        thread_local_store.checksums
      end

      # @param [String] data data to checksum
      # @return [String] the SHA1 checksum for data
      def checksum_for(data)
        Digest::SHA1.hexdigest(data)
      end

      # @group Managing Internal State (Advanced / Testing Only)

      # Whether or not the Registry storage should load everything into a
      # single object database (for disk efficiency), or spread them out
      # (for load time efficiency).
      #
      # @note Setting this attribute to nil will offload the decision to
      #   the {RegistryStore storage adapter}.
      # @return [Boolean, nil] if this value is set to nil, the storage
      #   adapter will decide how to store the data.
      attr_accessor :single_object_db
      undef single_object_db, single_object_db=
      def single_object_db=(v) Thread.current[:__yard_single_db__] = v end
      def single_object_db; Thread.current[:__yard_single_db__] end

      # The assumed types of a list of paths. This method is used by CodeObjects::Base
      # @return [{String => Symbol}] a set of unresolved paths and their assumed type
      # @private
      # @deprecated The registry no longer globally tracks proxy types.
      def proxy_types
        thread_local_store.proxy_types
      end

      # @group I18n features

      # Gets/sets the directory that has LANG.po files
      # @return [String] the directory that has .po files
      attr_accessor :po_dir
      undef po_dir, po_dir=
      def po_dir=(dir) Thread.current[:__yard_po_dir__] = dir end

      def po_dir
        Thread.current[:__yard_po_dir__] ||= DEFAULT_PO_DIR
      end

      # @group Legacy Methods

      # The registry singleton instance.
      #
      # @deprecated use Registry.methodname directly.
      # @return [Registry] returns the registry instance
      def instance; self end

      private

      # @group Accessing Objects in the Registry

      # Attempts to resolve a name in a namespace
      #
      # @param [CodeObjects::NamespaceObject] namespace the starting namespace
      # @param [String] name the name to look for
      # @param [Symbol, nil] type the {CodeObjects::Base#type} that the resolved
      #   object must be equal to
      def partial_resolve(namespace, name, type = nil)
        obj = at(name) || at('#' + name) if namespace.root?
        return obj if obj && (type.nil? || obj.type == type)
        [CodeObjects::NSEP, CodeObjects::CSEP, ''].each do |s|
          next if s.empty? && name =~ /^\w/
          path = name
          path = [namespace.path, name].join(s) if namespace != root
          found = at(path)
          return found if found && (type.nil? || found.type == type)
        end
        nil
      end

      # @group Retrieving yardoc File Locations

      def global_yardoc_file(spec, for_writing = false)
        path = spec.doc_dir
        yfile = spec.doc_dir(DEFAULT_YARDOC_FILE)
        if for_writing
          if File.writable?(path) ||
             (!File.directory?(path) && File.writable?(File.dirname(path)))
            return yfile
          end
        elsif !for_writing && File.exist?(yfile)
          return yfile
        end
      end

      def old_global_yardoc_file(spec, for_writing = false)
        path = spec.full_gem_path
        yfile = File.join(path, DEFAULT_YARDOC_FILE)
        return yfile if for_writing && File.writable?(path)
        return yfile if !for_writing && File.exist?(yfile)
      end

      def local_yardoc_file(spec, for_writing = false)
        path = Registry::LOCAL_YARDOC_INDEX
        FileUtils.mkdir_p(path) if for_writing
        path = File.join(path, "#{spec.full_name}.yardoc")
        if for_writing
          path
        else
          File.exist?(path) ? path : nil
        end
      end

      # @group Threading support

      # @since 0.6.5
      def thread_local_store
        Thread.current[:__yard_registry__] ||= clear
      end

      # @since 0.6.5
      def thread_local_store=(value)
        Thread.current[:__yard_registry__] = value
      end

      # @since 0.9.1
      def thread_local_resolver
        Thread.current[:__yard_resolver__] ||= RegistryResolver.new
      end
    end
  end
end
yard-0.9.37/lib/yard/registry_resolver.rb000066400000000000000000000162261466601756300204210ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  # Handles all logic for complex lexical and inherited object resolution.
  # Used by {Registry.resolve}, so there is no need to use this class
  # directly.
  #
  # @see Registry.resolve
  # @since 0.9.1
  class RegistryResolver
    include CodeObjects::NamespaceMapper

    # Creates a new resolver object for a registry.
    #
    # @param registry [Registry] only set this if customizing the registry
    #   object
    def initialize(registry = Registry)
      @registry = registry
      @default_sep = nil

      # Preload all code objects for separator declarations
      YARD::CodeObjects.constants.map {|t| YARD::CodeObjects.const_get(t) }
    end

    # Performs a lookup on a given path in the registry. Resolution will occur
    # in a similar way to standard Ruby identifier resolution, doing lexical
    # lookup, as well as (optionally) through the inheritance chain. A proxy
    # object can be returned if the lookup fails for future resolution. The
    # proxy will be type hinted with the +type+ used in the original lookup.
    #
    # @option opts namespace [CodeObjects::Base, :root, nil] (nil) the namespace
    #   object to start searching from. If root or nil is provided, {Registry.root}
    #   is assumed.
    # @option opts inheritance [Boolean] (false) whether to perform lookups through
    #   the inheritance chain (includes mixins)
    # @option opts proxy_fallback [Boolean] (false) when true, a proxy is returned
    #   if no match is found
    # @option opts type [Symbol] (nil) an optional type hint for the resolver
    #   to consider when performing a lookup. If a type is provided and the
    #   resolved object's type does not match the hint, the object is discarded.
    # @return [CodeObjects::Base, CodeObjects::Proxy, nil] the first object
    #   that matches the path lookup. If proxy_fallback is provided, a proxy
    #   object will be returned in the event of no match, otherwise nil will
    #   be returned.
    # @example A lookup from root
    #   resolver.lookup_by_path("A::B::C")
    # @example A lookup from the A::B namespace
    #   resolver.lookup_by_path("C", namespace: P("A::B"))
    # @example A lookup on a method through the inheritance tree
    #   resolver.lookup_by_math("A::B#foo", inheritance: true)
    def lookup_by_path(path, opts = {})
      path = path.to_s
      namespace = opts[:namespace]
      inheritance = opts[:inheritance] || false
      proxy_fallback = opts[:proxy_fallback] || false
      type = opts[:type]

      if namespace.is_a?(CodeObjects::Proxy)
        return proxy_fallback ? CodeObjects::Proxy.new(namespace, path, type) : nil
      end

      if namespace == :root || !namespace
        namespace = @registry.root
      else
        namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
      end
      orignamespace = namespace

      if path =~ starts_with_default_separator_match
        path = $'
        namespace = @registry.root
        orignamespace = @registry.root
      end

      resolved = nil
      lexical_lookup = 0
      while namespace && !resolved
        resolved = lookup_path_direct(namespace, path, type)
        resolved ||= lookup_path_inherited(namespace, path, type) if inheritance
        break if resolved
        namespace = namespace.parent
        lexical_lookup += 1
      end

      # method objects cannot be resolved through lexical lookup by more than 1 ns
      if lexical_lookup > 1 && resolved.is_a?(CodeObjects::MethodObject)
        resolved = nil
      end

      if proxy_fallback
        resolved ||= CodeObjects::Proxy.new(orignamespace, path, type)
      end

      resolved
    end

    private

    # return [Boolean] if the obj's type matches the provided type.
    def validate(obj, type)
      !type || (obj && obj.type == type) ? obj : nil
    end

    # Performs a lexical lookup from a namespace for a path and a type hint.
    def lookup_path_direct(namespace, path, type)
      result = namespace.root? && validate(@registry.at(path), type)
      return result if result

      if path =~ starts_with_separator_match
        return validate(@registry.at(namespace.path + path), type)
      end

      separators.each do |sep|
        result = validate(@registry.at("#{namespace.path}#{sep}#{path}"), type)
        return result if result
      end

      nil
    end

    # Performs a lookup through the inheritance chain on a path with a type hint.
    def lookup_path_inherited(namespace, path, type)
      resolved = nil
      last_obj = namespace
      scopes = []
      last_sep = nil
      pos = 0

      if path =~ starts_with_separator_match
        last_sep = $1
        path = $'
      end

      path.scan(split_on_separators_match).each do |part, sep|
        cur_obj = nil
        pos += part.length
        pos += sep.length
        parsed_end = pos == path.length

        if !last_obj || (!parsed_end && !last_obj.is_a?(CodeObjects::NamespaceObject))
          break # can't continue
        end

        collect_namespaces(last_obj).each do |ns|
          next if ns.is_a?(CodeObjects::Proxy)

          found = nil
          search_seps = []
          scopes.each do |scope|
            search_seps += separators_for_type(scope)
          end

          if search_seps.empty?
            search_seps =
              if ns.type == :root
                [""]
              elsif last_sep.nil?
                separators
              else
                [@default_sep]
              end
          end

          ([last_sep] | search_seps).compact.each do |search_sep|
            found = @registry.at(ns.path + search_sep.to_s + part)
            break if found
          end

          break cur_obj = found if found
        end

        last_sep = sep
        scopes = types_for_separator(sep) || []
        last_obj = cur_obj
        resolved = cur_obj if parsed_end && cur_obj && (type.nil? || type == cur_obj.type)
      end

      resolved
    end

    # Collects and returns all inherited namespaces for a given object
    def collect_namespaces(object)
      return [] unless object.respond_to?(:inheritance_tree)

      nss = object.inheritance_tree(true)
      if object.respond_to?(:superclass)
        nss |= [P('Object')] if object.superclass != P('BasicObject')
        nss |= [P('BasicObject')]
      end

      nss
    end

    # @return [Regexp] the regexp match of the default separator
    def starts_with_default_separator_match
      @@starts_with_default_separator_match ||= /\A#{default_separator}/
    end

    # @return [Regexp] the regexp that matches strings starting with
    #   a separator
    def starts_with_separator_match
      @@starts_with_separator_match ||= /\A(#{separators_match})/
    end

    # @return [Regexp] the regexp that can be used to split a string on all
    #   occurrences of separator tokens
    def split_on_separators_match
      @@split_on_separators_match ||= /(.+?)(#{separators_match}|$)/
    end

    # Additional invalidations to done when NamespaceMapper API methods are
    # called on this class
    YARD::CodeObjects::NamespaceMapper.on_invalidate do
      @@starts_with_default_separator_match = nil
      @@starts_with_separator_match = nil
      @@split_on_separators_match = nil
    end
  end
end
yard-0.9.37/lib/yard/registry_store.rb000066400000000000000000000231301466601756300177040ustar00rootroot00000000000000# frozen_string_literal: true
require 'fileutils'

module YARD
  # The data store for the {Registry}.
  #
  # @see Registry
  # @see Serializers::YardocSerializer
  class RegistryStore
    # @deprecated The registry no longer tracks proxy types
    attr_reader :proxy_types
    attr_reader :file, :checksums

    def initialize
      @file = nil
      @checksums = {}
      @store = {}
      @proxy_types = {}
      @object_types = {:root => [:root]}
      @notfound = {}
      @loaded_objects = 0
      @available_objects = 0
      @locales = {}
      @store[:root] = CodeObjects::RootObject.allocate
      @store[:root].send(:initialize, nil, :root)
    end

    # Gets a {CodeObjects::Base} from the store
    #
    # @param [String, Symbol] key the path name of the object to look for.
    #   If it is empty or :root, returns the {#root} object.
    # @return [CodeObjects::Base, nil] a code object or nil if none is found
    def get(key)
      key = :root if key == ''
      key = key.to_sym
      return @store[key] if @store[key]
      return if @loaded_objects >= @available_objects

      # check disk
      return if @notfound[key]
      obj = @serializer.deserialize(key)
      if obj
        @loaded_objects += 1
        put(key, obj)
      else
        @notfound[key] = true
        nil
      end
    end

    # Associates an object with a path
    # @param [String, Symbol] key the path name (:root or '' for root object)
    # @param [CodeObjects::Base] value the object to store
    # @return [CodeObjects::Base] returns +value+
    def put(key, value)
      if key == ''
        @object_types[:root] = [:root]
        @store[:root] = value
      else
        @notfound.delete(key.to_sym)
        (@object_types[value.type] ||= []) << key.to_s
        if @store[key.to_sym]
          @object_types[@store[key.to_sym].type].delete(key.to_s)
        end
        @store[key.to_sym] = value
      end
    end

    alias [] get
    alias []= put

    # Deletes an object at a given path
    # @param [#to_sym] key the key to delete
    # @return [void]
    def delete(key)
      if @store[key.to_sym]
        @object_types[@store[key.to_sym].type].delete(key.to_s)
        @store.delete(key.to_sym)
      end
    end

    # Gets all path names from the store. Loads the entire database
    # if +reload+ is +true+
    #
    # @param [Boolean] reload if false, does not load the entire database
    #   before a lookup.
    # @return [Array] the path names of all the code objects
    def keys(reload = false) load_all if reload; @store.keys end

    # Gets all code objects from the store. Loads the entire database
    # if +reload+ is +true+
    #
    # @param [Boolean] reload if false, does not load the entire database
    #   before a lookup.
    # @return [Array] all the code objects
    def values(reload = false) load_all if reload; @store.values end

    # @param [Symbol] type the type to look for
    # @return [Array] a list of object paths with a given
    #   {CodeObjects::Base#type}
    # @since 0.8.0
    def paths_for_type(type, reload = false)
      load_all if reload
      @object_types[type] || []
    end

    # @param [Symbol] type the type to look for
    # @return [Array] a list of objects with a given
    #   {CodeObjects::Base#type}
    # @since 0.8.0
    def values_for_type(type, reload = false)
      load_all if reload
      paths_for_type(type).map {|t| @store[t.to_sym] }
    end

    # @return [CodeObjects::RootObject] the root object
    def root; @store[:root] end

    # @param [String] name the locale name.
    # @return [I18n::Locale] the locale object for +name+.
    # @since 0.8.3
    def locale(name)
      @locales[name] ||= load_locale(name)
    end

    # @param [String, nil] file the name of the yardoc db to load
    # @return [Boolean] whether the database was loaded
    def load(file = nil)
      initialize
      @file = file
      @serializer = Serializers::YardocSerializer.new(@file)
      load_yardoc
    end

    # Loads the .yardoc file and loads all cached objects into memory
    # automatically.
    #
    # @param [String, nil] file the name of the yardoc db to load
    # @return [Boolean] whether the database was loaded
    # @see #load_all
    # @since 0.5.1
    def load!(file = nil)
      if load(file)
        load_all
        true
      else
        false
      end
    end

    # Loads all cached objects into memory
    # @return [void]
    def load_all
      return unless @file
      return if @loaded_objects >= @available_objects
      log.debug "Loading entire database: #{@file} ..."
      objects = []

      all_disk_objects.sort_by(&:size).each do |path|
        obj = @serializer.deserialize(path, true)
        objects << obj if obj
      end

      objects.each do |obj|
        put(obj.path, obj)
      end

      @loaded_objects += objects.size
      log.debug "Loaded database (file='#{@file}' count=#{objects.size} total=#{@available_objects})"
    end

    # Saves the database to disk
    # @param [Boolean] merge if true, merges the data in memory with the
    #   data on disk, otherwise the data on disk is deleted.
    # @param [String, nil] file if supplied, the name of the file to save to
    # @return [Boolean] whether the database was saved
    def save(merge = true, file = nil)
      if file && file != @file
        @file = file
        @serializer = Serializers::YardocSerializer.new(@file)
      end
      destroy unless merge

      sdb = Registry.single_object_db
      if sdb == true || sdb.nil?
        @serializer.serialize(@store)
      else
        values(false).each do |object|
          @serializer.serialize(object)
        end
      end
      write_proxy_types
      write_object_types
      write_checksums
      write_complete_lock
      true
    end

    # (see Serializers::YardocSerializer#lock_for_writing)
    # @param file [String] if supplied, the path to the database
    def lock_for_writing(file = nil, &block)
      Serializers::YardocSerializer.new(file || @file).lock_for_writing(&block)
    end

    # (see Serializers::YardocSerializer#locked_for_writing?)
    # @param file [String] if supplied, the path to the database
    def locked_for_writing?(file = nil)
      Serializers::YardocSerializer.new(file || @file).locked_for_writing?
    end

    # Deletes the .yardoc database on disk
    #
    # @param [Boolean] force if force is not set to true, the file/directory
    #   will only be removed if it ends with .yardoc. This helps with
    #   cases where the directory might have been named incorrectly.
    # @return [Boolean] true if the .yardoc database was deleted, false
    #   otherwise.
    def destroy(force = false)
      if (!force && file =~ /\.yardoc$/) || force
        if File.file?(@file)
          # Handle silent upgrade of old .yardoc format
          File.unlink(@file)
        elsif File.directory?(@file)
          FileUtils.rm_rf(@file)
        end
        true
      else
        false
      end
    end

    protected

    def objects_path
      @serializer.objects_path
    end

    # @deprecated The registry no longer tracks proxy types
    def proxy_types_path
      @serializer.proxy_types_path
    end

    def checksums_path
      @serializer.checksums_path
    end

    def object_types_path
      @serializer.object_types_path
    end

    def load_yardoc
      return false unless @file
      if File.directory?(@file) # new format
        @loaded_objects = 0
        @available_objects = all_disk_objects.size
        load_proxy_types
        load_checksums
        load_root
        load_object_types
        true
      elsif File.file?(@file) # old format
        load_yardoc_old
        true
      else
        false
      end
    end

    private

    def load_yardoc_old
      @store, @proxy_types = *Marshal.load(File.read_binary(@file))
    end

    # @deprecated The registry no longer tracks proxy types
    def load_proxy_types
      return unless File.file?(proxy_types_path)
      @proxy_types = Marshal.load(File.read_binary(proxy_types_path))
    end

    def load_object_types
      if File.file?(object_types_path)
        @object_types = Marshal.load(File.read_binary(object_types_path))
      else # migrate db without object_types
        values.each do |object|
          (@object_types[object.type] ||= []) << object.path
        end
      end
    end

    def load_checksums
      return unless File.file?(checksums_path)
      lines = File.readlines(checksums_path).map do |line|
        line.strip.rpartition(' ').tap { |p| p.delete_at(1) }
      end
      @checksums = Hash[lines]
    end

    def load_root
      root = @serializer.deserialize('root')
      return if root.nil?

      @loaded_objects += 1
      if root.is_a?(Hash) # single object db
        log.debug "Loading single object DB from .yardoc"
        @loaded_objects += (root.keys.size - 1)
        @store = root
      else # just the root object
        @store[:root] = root
      end
    end

    def load_locale(name)
      locale = I18n::Locale.new(name)
      locale.load(Registry.po_dir)
      locale
    end

    def all_disk_objects
      Dir.glob(File.join(objects_path, '**/*')).select {|f| File.file?(f) }
    end

    # @deprecated The registry no longer tracks proxy types
    def write_proxy_types
      File.open!(proxy_types_path, 'wb') {|f| f.write(Marshal.dump(@proxy_types)) }
    end

    def write_object_types
      File.open!(object_types_path, 'wb') {|f| f.write(Marshal.dump(@object_types)) }
    end

    def write_checksums
      File.open!(checksums_path, 'w') do |f|
        @checksums.each {|k, v| f.puts("#{k} #{v}") }
      end
    end

    def write_complete_lock
      File.open!(@serializer.complete_lock_path, 'w') {}
    end
  end
end
yard-0.9.37/lib/yard/rubygems/000077500000000000000000000000001466601756300161315ustar00rootroot00000000000000yard-0.9.37/lib/yard/rubygems/backports.rb000066400000000000000000000004151466601756300204460ustar00rootroot00000000000000# frozen_string_literal: true
begin
  require 'rubygems'
  if defined?(Gem::VERSION) && Gem::VERSION >= '1.8.0'
    require File.dirname(__FILE__) + '/backports/gem'
    require File.dirname(__FILE__) + '/backports/source_index'
  end
rescue LoadError
  nil # noop
end
yard-0.9.37/lib/yard/rubygems/backports/000077500000000000000000000000001466601756300201215ustar00rootroot00000000000000yard-0.9.37/lib/yard/rubygems/backports/LICENSE.txt000066400000000000000000000046331466601756300217520ustar00rootroot00000000000000RubyGems is copyrighted free software by Chad Fowler, Rich Kilmer, Jim
Weirich and others.  You can redistribute it and/or modify it under
either the terms of the MIT license (see the file MIT.txt), or the
conditions below:

1. You may make and give away verbatim copies of the source form of the
   software without restriction, provided that you duplicate all of the
   original copyright notices and associated disclaimers.

2. You may modify your copy of the software in any way, provided that
   you do at least ONE of the following:

   a. place your modifications in the Public Domain or otherwise
      make them Freely Available, such as by posting said
      modifications to Usenet or an equivalent medium, or by allowing
      the author to include your modifications in the software.

   b. use the modified software only within your corporation or
      organization.

   c. give non-standard executables non-standard names, with
      instructions on where to get the original software distribution.

   d. make other distribution arrangements with the author.

3. You may distribute the software in object code or executable
   form, provided that you do at least ONE of the following:

   a. distribute the executables and library files of the software,
      together with instructions (in the manual page or equivalent)
      on where to get the original distribution.

   b. accompany the distribution with the machine-readable source of
      the software.

   c. give non-standard executables non-standard names, with
      instructions on where to get the original software distribution.

   d. make other distribution arrangements with the author.

4. You may modify and include the part of the software into any other
   software (possibly commercial).  But some files in the distribution
   are not written by the author, so that they are not under these terms.

   For the list of those files and their copying conditions, see the
   file LEGAL.

5. The scripts and library files supplied as input to or produced as
   output from the software do not automatically fall under the
   copyright of the software, but belong to whomever generated them,
   and may be sold commercially, and may be aggregated with this
   software.

6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
   PURPOSE.
yard-0.9.37/lib/yard/rubygems/backports/MIT.txt000066400000000000000000000021001466601756300213040ustar00rootroot00000000000000Copyright (c) Chad Fowler, Rich Kilmer, Jim Weirich and others.

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.
yard-0.9.37/lib/yard/rubygems/backports/gem.rb000066400000000000000000000004401466601756300212140ustar00rootroot00000000000000# frozen_string_literal: true
module Gem
  class << self
    undef source_index if method_defined?(:source_index)
    # Returns the Gem::SourceIndex of specifications that are in the Gem.path
    def source_index
      @@source_index ||= SourceIndex.from_installed_gems
    end
  end
end
yard-0.9.37/lib/yard/rubygems/backports/source_index.rb000066400000000000000000000223661466601756300231460ustar00rootroot00000000000000# frozen_string_literal: true
#--
# Copyright 2006 by Chad Fowler, Rich Kilmer, Jim Weirich and others.
# All rights reserved.
# See LICENSE.txt for permissions.
#++

require 'rubygems/specification'

##
# The SourceIndex object indexes all the gems available from a
# particular source (e.g. a list of gem directories, or a remote
# source).  A SourceIndex maps a gem full name to a gem
# specification.
#
# NOTE:: The class used to be named Cache, but that became
#        confusing when cached source fetchers where introduced. The
#        constant Gem::Cache is an alias for this class to allow old
#        YAMLized source index objects to load properly.

class Gem::SourceIndex
  # Undef old methods
  alias old_initialize initialize
  undef old_initialize
  %w(all_gems prerelease_gems load_gems_in latest_specs prerelease_specs
      released_specs add_spec add_specs remove_spec each specification
      index_signature gem_signature size length find_name search released_gems
      refresh! outdated == dump gems spec_dirs spec_dirs=).each do |meth|
    undef_method(meth) if method_defined?(meth)
  end

  include Enumerable

  attr_reader :gems # :nodoc:

  ##
  # Directories to use to refresh this SourceIndex when calling refresh!

  attr_accessor :spec_dirs

  class << self
    # Undef old methods
    %w(from_installed_gems installed_spec_directories
        from_gems_in load_specification).each do |meth|
      undef_method(meth) if instance_methods(true).find {|m| m.to_s == meth }
    end

    ##
    # Factory method to construct a source index instance for a given
    # path.
    #
    # deprecated::
    #   If supplied, from_installed_gems will act just like
    #   +from_gems_in+.  This argument is deprecated and is provided
    #   just for backwards compatibility, and should not generally
    #   be used.
    #
    # return::
    #   SourceIndex instance

    def from_installed_gems(*deprecated)
      if deprecated.empty?
        from_gems_in(*installed_spec_directories)
      else
        from_gems_in(*deprecated) # HACK: warn
      end
    end

    ##
    # Returns a list of directories from Gem.path that contain specifications.

    def installed_spec_directories
      Gem.path.collect {|dir| File.join(dir, "specifications") }
    end

    ##
    # Creates a new SourceIndex from the ruby format gem specifications in
    # +spec_dirs+.

    def from_gems_in(*spec_dirs)
      source_index = new
      source_index.spec_dirs = spec_dirs
      source_index.refresh!
    end

    ##
    # Loads a ruby-format specification from +file_name+ and returns the
    # loaded spec.

    def load_specification(file_name)
      Gem::Specification.load file_name
    end
  end

  ##
  # Constructs a source index instance from the provided specifications, which
  # is a Hash of gem full names and Gem::Specifications.
  #--
  # TODO merge @gems and @prerelease_gems and provide a separate method
  # #prerelease_gems

  def initialize(specifications = {})
    @gems = {}
    specifications.each {|_full_name, spec| add_spec spec }
    @spec_dirs = nil
  end

  # TODO: remove method
  def all_gems
    @gems
  end

  def prerelease_gems
    @gems.reject {|_name, gem| !gem.version.prerelease? }
  end

  def released_gems
    @gems.reject {|_name, gem| gem.version.prerelease? }
  end

  ##
  # Reconstruct the source index from the specifications in +spec_dirs+.

  def load_gems_in(*spec_dirs)
    @gems.clear

    spec_dirs.reverse_each do |spec_dir|
      spec_files = Dir.glob File.join(spec_dir, '*.gemspec')

      spec_files.each do |spec_file|
        gemspec = Gem::Specification.load spec_file
        add_spec gemspec if gemspec
      end
    end

    self
  end

  ##
  # Returns an Array specifications for the latest released versions
  # of each gem in this index.

  def latest_specs(include_prerelease = false)
    result = Hash.new {|h, k| h[k] = [] }
    latest = {}

    sort.each do |_, spec|
      name = spec.name
      curr_ver = spec.version
      prev_ver = latest.key?(name) ? latest[name].version : nil

      next if !include_prerelease && curr_ver.prerelease?
      next unless prev_ver.nil? || curr_ver >= prev_ver ||
                  latest[name].platform != Gem::Platform::RUBY

      if prev_ver.nil? ||
         (curr_ver > prev_ver && spec.platform == Gem::Platform::RUBY)
        result[name].clear
        latest[name] = spec
      end

      if spec.platform != Gem::Platform::RUBY
        result[name].delete_if do |result_spec|
          result_spec.platform == spec.platform
        end
      end

      result[name] << spec
    end

    # TODO: why is this a hash while @gems is an array? Seems like
    # structural similarity would be good.
    result.values.flatten
  end

  ##
  # An array including only the prerelease gemspecs

  def prerelease_specs
    prerelease_gems.values
  end

  ##
  # An array including only the released gemspecs

  def released_specs
    released_gems.values
  end

  ##
  # Add a gem specification to the source index.

  def add_spec(gem_spec, name = gem_spec.full_name)
    # No idea why, but the Indexer wants to insert them using original_name
    # instead of full_name. So we make it an optional arg.
    @gems[name] = gem_spec
  end

  ##
  # Add gem specifications to the source index.

  def add_specs(*gem_specs)
    gem_specs.each do |spec|
      add_spec spec
    end
  end

  ##
  # Remove a gem specification named +full_name+.

  def remove_spec(full_name)
    @gems.delete full_name
  end

  ##
  # Iterate over the specifications in the source index.

  def each(&block) # :yields: gem.full_name, gem
    @gems.each(&block)
  end

  ##
  # The gem specification given a full gem spec name.

  def specification(full_name)
    @gems[full_name]
  end

  ##
  # The signature for the source index.  Changes in the signature indicate a
  # change in the index.

  def index_signature
    require 'digest'

    Digest::SHA256.new.hexdigest(@gems.keys.sort.join(',')).to_s
  end

  ##
  # The signature for the given gem specification.

  def gem_signature(gem_full_name)
    require 'digest'

    Digest::SHA256.new.hexdigest(@gems[gem_full_name].to_yaml).to_s
  end

  def size
    @gems.size
  end
  alias length size

  ##
  # Find a gem by an exact match on the short name.

  def find_name(gem_name, requirement = Gem::Requirement.default)
    dep = Gem::Dependency.new gem_name, requirement
    search dep
  end

  ##
  # Search for a gem by Gem::Dependency +gem_pattern+.  If +only_platform+
  # is true, only gems matching Gem::Platform.local will be returned.  An
  # Array of matching Gem::Specification objects is returned.
  #
  # For backwards compatibility, a String or Regexp pattern may be passed as
  # +gem_pattern+, and a Gem::Requirement for +platform_only+.  This
  # behavior is deprecated and will be removed.

  def search(gem_pattern, platform_only = false)
    requirement = nil
    only_platform = false

    # TODO: Remove support and warning for legacy arguments after 2008/11
    unless Gem::Dependency === gem_pattern
      warn "#{Gem.location_of_caller.join ':'}:Warning: Gem::SourceIndex#search support for #{gem_pattern.class} patterns is deprecated, use #find_name"
    end

    case gem_pattern
    when Regexp then
      requirement = platform_only || Gem::Requirement.default
    when Gem::Dependency then
      only_platform = platform_only
      requirement = gem_pattern.requirement

      gem_pattern = if Regexp === gem_pattern.name
                      gem_pattern.name
                    elsif gem_pattern.name.empty?
                      //
                    else
                      /^#{Regexp.escape gem_pattern.name}$/
                    end
    else
      requirement = platform_only || Gem::Requirement.default
      gem_pattern = /#{gem_pattern}/i
    end

    unless Gem::Requirement === requirement
      requirement = Gem::Requirement.create requirement
    end

    specs = all_gems.values.select do |spec|
      spec.name =~ gem_pattern &&
        requirement.satisfied_by?(spec.version)
    end

    if only_platform
      specs = specs.select do |spec|
        Gem::Platform.match spec.platform
      end
    end

    specs.sort_by(&:sort_obj)
  end

  ##
  # Replaces the gems in the source index from specifications in the
  # directories this source index was created from.  Raises an exception if
  # this source index wasn't created from a directory (via from_gems_in or
  # from_installed_gems, or having spec_dirs set).

  def refresh!
    raise 'source index not created from disk' if @spec_dirs.nil?
    load_gems_in(*@spec_dirs)
  end

  ##
  # Returns an Array of Gem::Specifications that are not up to date.

  def outdated
    outdateds = []

    latest_specs.each do |local|
      dependency = Gem::Dependency.new local.name, ">= #{local.version}"

      fetcher = Gem::SpecFetcher.fetcher
      remotes = fetcher.find_matching dependency
      remotes = remotes.map {|(_, version, _), _| version }

      latest = remotes.sort.last

      outdateds << local.name if latest && local.version < latest
    end

    outdateds
  end

  def ==(other) # :nodoc:
    self.class === other && @gems == other.gems
  end

  def dump
    Marshal.dump(self)
  end
end

# :stopdoc:
module Gem
  ##
  # Cache is an alias for SourceIndex to allow older YAMLized source index
  # objects to load properly.

  Cache = SourceIndex unless defined?(Cache)
end
# :startdoc:
yard-0.9.37/lib/yard/rubygems/doc_manager.rb000066400000000000000000000045461466601756300207260ustar00rootroot00000000000000# frozen_string_literal: true
begin
  require 'rubygems/user_interaction'
  require 'rubygems/doc_manager'
rescue LoadError
  nil # noop
end

class Gem::DocManager
  def self.load_yardoc
    require File.expand_path(File.join(File.dirname(__FILE__), *%w(.. .. yard)))
  end

  def run_yardoc(*args)
    args << '--quiet'
    args << '--backtrace' if Gem.configuration.backtrace
    unless File.file?(File.join(@spec.full_gem_path, '.yardopts'))
      args << @spec.require_paths
      unless @spec.extra_rdoc_files.empty?
        args << '-'
        args += @spec.extra_rdoc_files
      end
    end
    args = args.flatten.map(&:to_s)

    old_pwd = Dir.pwd
    Dir.chdir(@spec.full_gem_path)
    YARD::CLI::Yardoc.run(*args)
  rescue Errno::EACCES => e
    dirname = File.dirname e.message.split("-")[1].strip
    raise Gem::FilePermissionError, dirname
  rescue => ex
    alert_error "While generating documentation for #{@spec.full_name}"
    ui.errs.puts "... MESSAGE:   #{ex}"
    ui.errs.puts "... YARDOC args: #{args.join(' ')}"
    ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
    ui.errs.puts "(continuing with the rest of the installation)"
  ensure
    Dir.chdir(old_pwd)
  end

  begin undef setup_rdoc; rescue NameError; nil end
  def setup_rdoc
    if File.exist?(@doc_dir) && !File.writable?(@doc_dir)
      raise Gem::FilePermissionError, @doc_dir
    end

    FileUtils.mkdir_p @doc_dir unless File.exist?(@doc_dir)

    self.class.load_rdoc if @spec.has_rdoc?
    self.class.load_yardoc if @spec.has_yardoc?
  end

  def install_yardoc
    rdoc_dir = File.join(@doc_dir, 'rdoc')

    FileUtils.rm_rf rdoc_dir

    say "Installing YARD documentation for #{@spec.full_name}..."
    run_yardoc '-o', rdoc_dir
  end

  def install_ri_yard
    install_ri_yard_orig if @spec.has_rdoc?
    return if @spec.has_rdoc? == false
    return if @spec.has_yardoc?

    self.class.load_yardoc
    say "Building YARD (yri) index for #{@spec.full_name}..."
    run_yardoc '-c', '-n'
  end

  begin
    alias install_ri_yard_orig install_ri
    alias install_ri install_ri_yard
  rescue NameError; nil end

  def install_rdoc_yard
    if @spec.has_rdoc?
      install_rdoc_yard_orig
    elsif @spec.has_yardoc?
      install_yardoc
    end
  end

  begin
    alias install_rdoc_yard_orig install_rdoc
    alias install_rdoc install_rdoc_yard
  rescue NameError; nil end
end
yard-0.9.37/lib/yard/rubygems/hook.rb000066400000000000000000000116231466601756300174210ustar00rootroot00000000000000# frozen_string_literal: true
require 'rubygems'
require 'rubygems/user_interaction'
require 'fileutils'

##
# Gem::YARDoc provides methods to generate YARDoc and yri data for installed gems
# upon gem installation.
#
# This file is automatically required by RubyGems 1.9 and newer.

module YARD
  class RubygemsHook
    include Gem::UserInteraction
    extend Gem::UserInteraction

    @yard_version = nil

    ##
    # Force installation of documentation?

    attr_accessor :force

    ##
    # Generate yard?

    attr_accessor :generate_yard

    ##
    # Generate yri data?

    attr_accessor :generate_yri

    class << self
      ##
      # Loaded version of YARD. Set by ::load_yard

      attr_reader :yard_version
    end

    ##
    # Post installs hook that generates documentation for each specification in
    # +specs+

    def self.generation_hook(installer, specs)
      start = Time.now
      types = installer.document

      generate_yard = types.include?('yardoc') || types.include?('yard')
      generate_yri = types.include? 'yri'

      specs.each do |spec|
        gen_yard = generate_yard
        gen_yri = generate_yri
        gen_yri = false if gen_yard # never generate both, no need
        unless types.empty? # --no-document is not in effect
          # look at spec.metadata['yard.run'] for override
          run_yard = spec.metadata['yard.run']
          gen_yard = true if run_yard && run_yard != 'yri'
          gen_yri = true if run_yard == 'yri'
        end

        new(spec, gen_yard, gen_yri).generate
      end

      return unless generate_yard || generate_yri

      duration = (Time.now - start).to_i
      names = specs.map(&:name).join ', '

      say "Done installing documentation for #{names} after #{duration} seconds"
    end

    ##
    # Pre uninstalls hook that removes documentation
    #

    def self.removal_hook(uninstaller)
      new(uninstaller.spec).remove
    end

    ##
    # Loads the YARD generator

    def self.load_yard
      return if @yard_version

      require 'yard'

      @yard_version = Gem::Version.new ::YARD::VERSION
    end

    def initialize(spec, generate_yard = false, generate_yri = true)
      @doc_dir = spec.doc_dir
      @force = false
      @spec = spec

      @generate_yard = generate_yard
      @generate_yri = generate_yri

      @yard_dir = spec.doc_dir('yard')
      @yri_dir = spec.doc_dir('.yardoc')
    end

    def run_yardoc(*args)
      args << '--quiet' unless Gem.configuration.really_verbose
      args << '--backtrace' if Gem.configuration.backtrace
      unless File.file?(File.join(@spec.full_gem_path, '.yardopts'))
        args << @spec.require_paths
        unless @spec.extra_rdoc_files.empty?
          args << '-'
          args += @spec.extra_rdoc_files
        end
      end
      args = args.flatten.map(&:to_s)

      Dir.chdir(@spec.full_gem_path) do
        YARD::CLI::Yardoc.run(*args)
      end
    rescue Errno::EACCES => e
      dirname = File.dirname e.message.split("-")[1].strip
      raise Gem::FilePermissionError, dirname
    rescue => ex
      alert_error "While generating documentation for #{@spec.full_name}"
      ui.errs.puts "... MESSAGE:   #{ex}"
      ui.errs.puts "... YARDOC args: #{args.join(' ')}"
      ui.errs.puts "\t#{ex.backtrace.join("\n\t")}" if Gem.configuration.backtrace
      ui.errs.puts "(continuing with the rest of the installation)"
    end

    def install_yard
      FileUtils.rm_rf @yard_dir

      say "Installing YARD documentation for #{@spec.full_name}..."
      run_yardoc '--no-progress', '--db', @yri_dir, '-o', @yard_dir
    end

    def install_yri
      FileUtils.rm_rf @yri_dir

      say "Building YARD (yri) index for #{@spec.full_name}..."
      run_yardoc '--no-progress', '-c', '-n', '--db', @yri_dir
    end

    ##
    # Generates YARD and yri data

    def generate
      return if @spec.default_gem?
      return unless @generate_yri || @generate_yard

      setup

      install_yri if @generate_yri && (@force || !File.exist?(@yri_dir))

      install_yard if @generate_yard && (@force || !File.exist?(@yard_dir))
    end

    ##
    # Prepares the spec for documentation generation

    def setup
      self.class.load_yard

      if File.exist?(@doc_dir)
        raise Gem::FilePermissionError, @doc_dir unless File.writable?(@doc_dir)
      else
        FileUtils.mkdir_p @doc_dir
      end
    end

    def uninstall_yard
      if File.exist?(@yard_dir)
        raise Gem::FilePermissionError, @yard_dir unless File.writable?(@yard_dir)
        FileUtils.rm_rf @yard_dir
      end
    end

    def uninstall_yri
      if File.exist?(@yri_dir)
        raise Gem::FilePermissionError, @yri_dir unless File.writable?(@yri_dir)
        FileUtils.rm_rf @yri_dir
      end
    end

    ##
    # Removes YARD and yri data

    def remove
      uninstall_yri
      uninstall_yard
    end
  end
end

Gem.done_installing(&YARD::RubygemsHook.method(:generation_hook))
Gem.pre_uninstall(&YARD::RubygemsHook.method(:removal_hook))
yard-0.9.37/lib/yard/rubygems/specification.rb000066400000000000000000000023311466601756300212750ustar00rootroot00000000000000# frozen_string_literal: true
require 'rubygems/specification'

class Gem::Specification
  # @since 0.5.3
  def has_yardoc=(value)
    @has_rdoc = value ? 'yard' : false
  end

  def has_yardoc
    @has_rdoc == 'yard'
  end

  undef has_rdoc?
  def has_rdoc?
    (@has_rdoc ||= true) && @has_rdoc != 'yard'
  end

  alias has_yardoc? has_yardoc

  # has_rdoc should not be ignored!
  if respond_to?(:overwrite_accessor)
    overwrite_accessor(:has_rdoc) { @has_rdoc ||= true }
    overwrite_accessor(:has_rdoc=) {|v| @has_rdoc = v }
  else
    attr_accessor :has_rdoc
  end

  if defined?(Gem::VERSION) && Gem::VERSION >= '1.7.'
    def _dump_with_rdoc(limit)
      dmp = _dump_without_rdoc(limit)
      dmp[15] = @has_rdoc if dmp[15] == true
      dmp
    end
    alias _dump_without_rdoc _dump
    alias _dump _dump_with_rdoc

    if class_variable_defined?(:@@default_value)
      if @@default_value.frozen?
        t = @@default_value.dup
        t[:has_rdoc] = true
        @@default_value = t.freeze
      else
        @@default_value[:has_rdoc] = true
      end
    end
    @@attributes << 'has_rdoc' if class_variable_defined?(:@@attributes)
    @@nil_attributes << 'has_rdoc' if class_variable_defined?(:@@nil_attributes)
  end
end
yard-0.9.37/lib/yard/serializers/000077500000000000000000000000001466601756300166305ustar00rootroot00000000000000yard-0.9.37/lib/yard/serializers/base.rb000066400000000000000000000061521466601756300200730ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Serializers
    # The abstract base serializer. Serializers allow templates to be
    # rendered to various endpoints. For instance, a {FileSystemSerializer}
    # would allow template contents to be written to the filesystem
    #
    # To implement a custom serializer, override the following methods:
    # * {#serialize}
    # * {#serialized_path}
    #
    # Optionally, a serializer can implement before and after filters:
    # * {#before_serialize}
    # * {#after_serialize}
    #
    # @abstract Override this class to implement a custom serializer.
    class Base
      # All serializer options are saved so they can be passed to other serializers.
      #
      # @return [SymbolHash] the serializer options
      attr_reader :options

      # @group Creating a New Serializer

      # Creates a new serializer with options
      #
      # @param [Hash] opts the options to assign to {#options}
      def initialize(opts = {})
        @options = SymbolHash.new(false).update(opts)
      end

      # @group Serializing an Object

      # Serializes an object.
      #
      # @abstract This method should implement the logic that serializes
      #   +data+ to the respective endpoint. This method should also call
      #   the before and after callbacks {#before_serialize} and {#after_serialize}
      # @param [CodeObjects::Base, String] object the object to serialize the
      #   data for. The object can also be a string (for non-object serialization)
      # @param [String] data the contents that should be serialized
      def serialize(object, data) end

      # The serialized path of an object
      #
      # @abstract This method should return the path of the object on the
      #   endpoint. For instance, for a file serializer, this should return
      #   the filename that represents the object on disk.
      # @param [CodeObjects::Base] object the object to return a path for
      # @return [String] the serialized path of an object
      def serialized_path(object) end

      # Returns whether an object has been serialized
      #
      # @abstract This method should return whether the endpoint already exists.
      #   For instance, a file system serializer would check if the file exists
      #   on disk. You will most likely use +#basepath+ and {#serialized_path} to
      #   get the endpoint's location.
      # @param [CodeObjects::Base] object the object to check existence of
      # @return [Boolean] whether the endpoint exists.
      # @since 0.6.0
      def exists?(object) # rubocop:disable Lint/UnusedMethodArgument
        false
      end

      # @group Callbacks

      # Called before serialization.
      #
      # @abstract Should run code before serialization. Should return false
      #   if serialization should not occur.
      # @return [Boolean] whether or not serialization should occur
      def before_serialize; end

      # Called after serialization.
      #
      # @abstract Should run code after serialization.
      # @param [String] data the data that was serialized.
      # @return [void]
      def after_serialize(data); end
    end
  end
end
yard-0.9.37/lib/yard/serializers/file_system_serializer.rb000066400000000000000000000107761466601756300237440ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Serializers
    # Implements a serializer that reads from and writes to the filesystem.
    class FileSystemSerializer < Base
      # The base path to write data to.
      # @return [String] a base path
      attr_reader :basepath

      def basepath=(value)
        @basepath = options[:basepath] = value
      end

      # The extension of the filename (defaults to +html+)
      #
      # @return [String] the extension of the file. Empty string for no extension.
      attr_reader :extension

      def extension=(value)
        @extension = options[:extension] = value
      end

      # Creates a new FileSystemSerializer with options
      #
      # @option opts [String] :basepath ('doc') the base path to write data to
      # @option opts [String] :extension ('html') the extension of the serialized
      #   path filename. If this is set to the empty string, no extension is used.
      def initialize(opts = {})
        super
        @name_map = nil
        @basepath = (options[:basepath] || 'doc').to_s
        @extension = (options.key?(:extension) ? options[:extension] : 'html').to_s
      end

      # Serializes object with data to its serialized path (prefixed by the +#basepath+).
      #
      # @return [String] the written data (for chaining)
      def serialize(object, data)
        path = File.join(basepath, serialized_path(object))
        log.debug "Serializing to #{path}"
        File.open!(path, "wb") {|f| f.write data }
      end

      # Implements the serialized path of a code object.
      #
      # @param [CodeObjects::Base, CodeObjects::ExtraFileObject, String] object
      #   the object to get a path for. The path of a string is the string itself.
      # @return [String] if object is a String, returns
      #   object, otherwise the path on disk (without the basepath).
      def serialized_path(object)
        return object if object.is_a?(String)

        if object.is_a?(CodeObjects::ExtraFileObject)
          fspath = ['file.' + object.name + (extension.empty? ? '' : ".#{extension}")]
        else
          objname = object != YARD::Registry.root ? mapped_name(object) : "top-level-namespace"
          objname += '_' + object.scope.to_s[0, 1] if object.is_a?(CodeObjects::MethodObject)
          fspath = [objname + (extension.empty? ? '' : ".#{extension}")]
          if object.namespace && object.namespace.path != ""
            fspath.unshift(*object.namespace.path.split(CodeObjects::NSEP))
          end
        end

        File.join(encode_path_components(*fspath))
      end

      # Checks the disk for an object and returns whether it was serialized.
      #
      # @param [CodeObjects::Base] object the object to check
      # @return [Boolean] whether an object has been serialized to disk
      def exists?(object)
        File.exist?(File.join(basepath, serialized_path(object)))
      end

      private

      # Builds a filename mapping from object paths to filesystem path names.
      # Needed to handle case sensitive YARD objects mapped into a case
      # insensitive filesystem. Uses with {#mapped_name} to determine the
      # mapping name for a given object.
      #
      # @note In order to use filesystem name mapping, you must initialize
      #   the serializer object after preparing the {YARD::Registry}.
      def build_filename_map
        @name_map = {}
        YARD::Registry.all.each do |object|
          lpath = nil
          if object.parent && object.parent.type != :root
            lpath = object.parent.path + "::" + object.name.to_s.downcase
          else
            lpath = object.path.downcase
          end

          @name_map[lpath] ||= {}
          size = @name_map[lpath].size
          name = "#{object.name}#{size > 0 ? "_" * size : ""}"
          @name_map[lpath][object.name] = name
        end
      end

      # @return [String] the filesystem mapped name of a given object.
      def mapped_name(object)
        build_filename_map unless @name_map
        map = @name_map[object.path.downcase]
        map && map[object.name] ? map[object.name] : object.name.to_s
      end

      # Remove special chars from filenames.
      # Windows disallows \ / : * ? " < > | but we will just remove any
      # non alphanumeric (plus period, underscore and dash).
      def encode_path_components(*components)
        components.map! do |p|
          p.gsub(/[^\w\.-]/) do |x|
            encoded = String.new('_')

            x.each_byte {|b| encoded << ("%X" % b) }
            encoded
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/serializers/process_serializer.rb000066400000000000000000000013211466601756300230610ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Serializers
    # Serializes an object to a process (like less)
    #
    # @example Serializing to a pager (less)
    #   serializer = ProcessSerializer.new('less')
    #   serializer.serialize(object, "data!")
    class ProcessSerializer < Base
      # Creates a new ProcessSerializer for the shell command +cmd+
      #
      # @param [String] cmd the command that will accept data on stdin
      def initialize(cmd)
        @cmd = cmd
      end

      # Overrides serialize behaviour and writes data to standard input
      # of the associated command
      def serialize(_object, data)
        IO.popen(@cmd, 'w') {|io| io.write(data) }
      end
    end
  end
end
yard-0.9.37/lib/yard/serializers/stdout_serializer.rb000066400000000000000000000020271466601756300227310ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Serializers
    # A serializer that writes data to standard output.
    class StdoutSerializer < Base
      # Creates a serializer to print text to stdout
      #
      # @param [Fixnum, nil] wrap if wrap is a number, wraps text to +wrap+
      #   columns, otherwise no wrapping is done.
      def initialize(wrap = nil)
        @wrap = wrap
      end

      # Overrides serialize behaviour to write data to standard output
      def serialize(_object, data)
        print(@wrap ? word_wrap(data, @wrap) : data)
      end

      private

      # Wraps text to a specific column length
      #
      # @param [String] text the text to wrap
      # @param [Fixnum] _length the column length to wrap to
      # @return [String] the wrapped text
      def word_wrap(text, _length = 80)
        # See ruby-talk/10655 / Ernest Ellingson
        text.gsub(/\t/, "     ").gsub(/.{1,50}(?:\s|\Z)/) do
          ($& + 5.chr).gsub(/\n\005/, "\n").gsub(/\005/, "\n")
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/serializers/yardoc_serializer.rb000066400000000000000000000104771466601756300227000ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  # Stubs marshal dumps and acts a delegate class for an object by path
  #
  # @private
  class StubProxy
    instance_methods.each {|m| undef_method(m) unless m.to_s =~ /^__|^object_id$/ }

    def _dump(_depth) @path end
    def self._load(str) new(str) end
    def hash; @path.hash end

    def initialize(path, transient = false)
      @path = path
      @transient = transient
    end

    def method_missing(meth, *args, &block)
      return true if meth == :respond_to? && args.first == :_dump
      @object = nil if @transient
      @object ||= Registry.at(@path)
      @object.send(meth, *args, &block)
    rescue NoMethodError => e
      e.backtrace.delete_if {|l| l[0, FILELEN] == __FILE__ }
      raise
    end

    FILELEN = __FILE__.size
  end

  module Serializers
    class YardocSerializer < FileSystemSerializer
      def initialize(yfile)
        super(:basepath => yfile, :extension => 'dat')
      end

      def objects_path; File.join(basepath, 'objects') end
      # @deprecated The registry no longer tracks proxy types
      def proxy_types_path; File.join(basepath, 'proxy_types') end
      def checksums_path; File.join(basepath, 'checksums') end
      def object_types_path; File.join(basepath, 'object_types') end
      def complete_lock_path; File.join(basepath, 'complete') end
      def processing_path; File.join(basepath, 'processing') end

      def complete?
        File.exist?(complete_lock_path) && !locked_for_writing?
      end

      # Creates a pessmistic transactional lock on the database for writing.
      # Use with {YARD.parse} to ensure the database is not written multiple
      # times.
      #
      # @see #locked_for_writing?
      def lock_for_writing
        File.open!(processing_path, 'w') {}
        yield
      ensure
        File.unlink(processing_path) if File.exist?(processing_path)
      end

      # @return [Boolean] whether the database is currently locked for writing
      def locked_for_writing?
        File.exist?(processing_path)
      end

      def serialized_path(object)
        path =
          case object
          when String, Symbol
            object = object.to_s
            if object =~ /#/
              object += '_i'
            elsif object =~ /\./
              object += '_c'
            end
            object.split(/::|\.|#/).map do |p|
              p.gsub(/[^\w\.-]/) do |x|
                encoded = '_'

                x.each_byte {|b| encoded += ("%X" % b) }
                encoded
              end
            end.join('/') + '.' + extension
          when YARD::CodeObjects::RootObject
            'root.dat'
          else
            super(object)
          end

        File.join('objects', path)
      end

      def serialize(object)
        if Hash === object
          super(object[:root], dump(object)) if object[:root]
        else
          super(object, dump(object))
        end
      end

      def deserialize(path, is_path = false)
        path = File.join(basepath, serialized_path(path)) unless is_path
        if File.file?(path)
          log.debug "Deserializing #{path}..."
          Marshal.load(File.read_binary(path))
        else
          log.debug "Could not find #{path}"
          nil
        end
      end

      private

      def dump(object)
        object = internal_dump(object, true) unless object.is_a?(Hash)
        Marshal.dump(object)
      end

      def internal_dump(object, first_object = false)
        if !first_object && object.is_a?(CodeObjects::Base) &&
           !(Tags::OverloadTag === object)
          return StubProxy.new(object.path)
        end

        if object.is_a?(Hash) || object.is_a?(Array) ||
           object.is_a?(CodeObjects::Base) ||
           !object.instance_variables.empty?
          object = object.dup
        end

        object.instance_variables.each do |ivar|
          ivar_obj = object.instance_variable_get(ivar)
          ivar_obj_dump = internal_dump(ivar_obj)
          object.instance_variable_set(ivar, ivar_obj_dump)
        end

        case object
        when Hash
          list = object.map do |k, v|
            [k, v].map {|item| internal_dump(item) }
          end
          object.replace(Hash[list])
        when Array
          list = object.map {|item| internal_dump(item) }
          object.replace(list)
        end

        object
      end
    end
  end
end
yard-0.9.37/lib/yard/server.rb000066400000000000000000000006211466601756300161260ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    # Registers a static path to be used in static asset lookup.
    # @param [String] path the pathname to register
    # @return [void]
    # @since 0.6.2
    def self.register_static_path(path)
      static_paths = Commands::StaticFileCommand::STATIC_PATHS
      static_paths.push(path) unless static_paths.include?(path)
    end
  end
end
yard-0.9.37/lib/yard/server/000077500000000000000000000000001466601756300156025ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/adapter.rb000066400000000000000000000103341466601756300175500ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    # Short circuits a request by raising an error. This exception is caught
    # by {Commands::Base#call} to immediately end a request and return a response.
    class FinishRequest < RuntimeError; end

    # Raises an error if a resource is not found. This exception is caught by
    # {Commands::Base#call} to immediately end a request and return a 404 response
    # code. If a message is provided, the body is set to the exception message.
    class NotFoundError < RuntimeError; end

    # This class implements the bridge between the {Router} and the server
    # backend for a specific server type. YARD implements concrete adapters
    # for WEBrick and Rack respectively, though other adapters can be made
    # for other server architectures.
    #
    # == Subclassing Notes
    # To create a concrete adapter class, implement the {#start} method to
    # initiate the server backend.
    #
    # @abstract
    class Adapter
      # @return [String] the location where static files are located, if any.
      #   To set this field on initialization, pass +:DocumentRoot+ to the
      #   +server_opts+ argument in {#initialize}
      attr_accessor :document_root

      # @return [Hash{String=>Array}] a map of libraries.
      # @see LibraryVersion LibraryVersion for information on building a list of libraries
      # @see #add_library
      attr_accessor :libraries

      # @return [Hash] options passed and processed by adapters. The actual
      #   options mostly depend on the adapters themselves.
      attr_accessor :options

      # @return [Hash] a set of options to pass to the server backend. Note
      #   that +:DocumentRoot+ also sets the {#document_root}.
      attr_accessor :server_options

      # @return [Router] the router object used to route URLs to commands
      attr_accessor :router

      # Performs any global initialization for the adapter.
      # @note If you subclass this method, make sure to call +super+.
      # @return [void]
      def self.setup
        Templates::Template.extra_includes |= [YARD::Server::DocServerHelper]
        Templates::Engine.template_paths |= [File.dirname(__FILE__) + '/templates']
      end

      # Performs any global shutdown procedures for the adapter.
      # @note If you subclass this method, make sure to call +super+.
      # @return [void]
      def self.shutdown
        Templates::Template.extra_includes -= [YARD::Server::DocServerHelper]
        Templates::Engine.template_paths -= [File.dirname(__FILE__) + '/templates']
      end

      # Creates a new adapter object
      #
      # @param [Hash{String=>Array}] libs a list of libraries,
      #   see {#libraries} for formulating this list.
      # @param [Hash] opts extra options to pass to the adapter
      # @option opts [Class] :router (Router) the router class to initialize as the
      #   adapter's router.
      # @option opts [Boolean] :caching (false) whether or not caching is enabled
      # @option opts [Boolean] :single_library (false) whether to server documentation
      #   for a single or multiple libraries (changes URL structure)
      def initialize(libs, opts = {}, server_opts = {})
        self.class.setup
        self.libraries = libs
        self.options = opts
        self.server_options = server_opts
        self.document_root = server_options[:DocumentRoot]
        self.router = (options[:router] || Router).new(self)
        options[:adapter] = self
        log.debug "Serving libraries using #{self.class}: #{libraries.keys.join(', ')}"
        log.debug "Caching on" if options[:caching]
        log.debug "Document root: #{document_root}" if document_root
      end

      # Adds a library to the {#libraries} mapping for a given library object.
      # @example Adding a new library to an adapter
      #   adapter.add_library LibraryVersion.new('mylib', '1.0', '/path/to/.yardoc')
      # @param [LibraryVersion] library a library to add
      def add_library(library)
        libraries[library.name] ||= []
        libraries[library.name] |= [library]
      end

      # Implement this method to connect your adapter to your server.
      # @abstract
      def start
        raise NotImplementedError
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/000077500000000000000000000000001466601756300174035ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/commands/base.rb000066400000000000000000000162221466601756300206450ustar00rootroot00000000000000# frozen_string_literal: true
require 'fileutils'

module YARD
  module Server
    module Commands
      # This is the base command class used to implement custom commands for
      # a server. A command will be routed to by the {Router} class and return
      # a Rack-style response.
      #
      # == Attribute Initializers
      # All attributes can be initialized via options passed into the {#initialize}
      # method. When creating a custom command, the {Adapter#options} will
      # automatically be mapped to attributes by the same name on your class.
      #
      #   class MyCommand < Base
      #     attr_accessor :myattr
      #   end
      #
      #   Adapter.new(libs, {:myattr => 'foo'}).start
      #
      #   # when a request comes in, cmd.myattr == 'foo'
      #
      # == Subclassing Notes
      # To implement a custom command, override the {#run} method, not {#call}.
      # In your implementation, you should set the body and status for requests.
      # See details in the +#run+ method documentation.
      #
      # Note that if your command deals directly with libraries, you should
      # consider subclassing the more specific {LibraryCommand} class instead.
      #
      # @abstract
      # @see #run
      class Base
        # @group Basic Command and Adapter Options

        # @return [Hash] the options passed to the command's constructor
        attr_accessor :command_options

        # @return [Adapter] the server adapter
        attr_accessor :adapter

        # @return [Boolean] whether to cache
        attr_accessor :caching

        # @group Attributes Set Per Request

        # @return [Rack::Request] request object
        attr_accessor :request

        # @return [String] the path after the command base URI
        attr_accessor :path

        # @return [Hash{String => String}] response headers
        attr_accessor :headers

        # @return [Numeric] status code. Defaults to 200 per request
        attr_accessor :status

        # @return [String] the response body. Defaults to empty string.
        attr_accessor :body

        # @group Instance Method Summary

        # Creates a new command object, setting attributes named by keys
        # in the options hash. After initialization, the options hash
        # is saved in {#command_options} for further inspection.
        #
        # @example Creating a Command
        #   cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)
        #   cmd.library # => mylib
        #   cmd.command_options # => {:caching => true, :library => mylib}
        # @param [Hash] opts the options hash, saved to {#command_options}
        #   after initialization.
        def initialize(opts = {})
          opts.each do |key, value|
            send("#{key}=", value) if respond_to?("#{key}=")
          end
          self.command_options = opts
        end

        # The main method called by a router with a request object.
        #
        # @note This command should not be overridden by subclasses. Implement
        #   the callback method {#run} instead.
        # @param [Adapter Dependent] request the request object
        # @return [Array(Numeric,Hash,Array)] a Rack-style response
        #   of status, headers, and body wrapped in an array.
        def call(request)
          self.request = request
          self.path ||= request.path_info[1..-1]
          self.headers = {'Content-Type' => 'text/html'}
          self.body = ''
          self.status = 200
          add_cache_control
          begin
            run
          rescue FinishRequest
            nil # noop
          rescue NotFoundError => e
            self.body = e.message if e.message != e.class.to_s
            not_found
          end

          # keep this to support commands setting status manually.
          not_found if status == 404

          [status, headers, body.is_a?(Array) ? body : [body]]
        end

        # @group Abstract Methods

        # Subclass this method to implement a custom command. This method
        # should set the {#status} and {#body}, and optionally modify the
        # {#headers}. Note that +#status+ defaults to 200.
        #
        # @example A custom command
        #   class ErrorCommand < Base
        #     def run
        #       self.body = 'ERROR! The System is down!'
        #       self.status = 500
        #       self.headers['Content-Type'] = 'text/plain'
        #     end
        #   end
        #
        # @abstract
        # @return [void]
        def run
          raise NotImplementedError
        end

        protected

        # @group Helper Methods

        # Renders a specific object if provided, or a regular template rendering
        # if object is not provided.
        #
        # @todo This method is dependent on +#options+, it should be in {LibraryCommand}.
        # @param [CodeObjects::Base, nil] object calls {CodeObjects::Base#format} if
        #   an object is provided, or {Templates::Engine.render} if object is nil. Both
        #   receive +#options+ as an argument.
        # @return [String] the resulting output to display
        def render(object = nil)
          case object
          when CodeObjects::Base
            cache object.format(options)
          when nil
            cache Templates::Engine.render(options)
          else
            cache object
          end
        end

        # Override this method to implement custom caching mechanisms for
        #
        # @example Caching to memory
        #   $memory_cache = {}
        #   def cache(data)
        #     $memory_cache[path] = data
        #   end
        # @param [String] data the data to cache
        # @return [String] the same cached data (for chaining)
        # @see StaticCaching
        def cache(data)
          if caching && adapter.document_root
            path = File.join(adapter.document_root, request.path_info.sub(/\.html$/, '') + '.html')
            path = path.sub(%r{/\.html$}, '.html')
            FileUtils.mkdir_p(File.dirname(path))
            log.debug "Caching data to #{path}"
            File.open(path, 'wb') {|f| f.write(data) }
          end
          self.body = data
        end

        # Sets the body and headers for a 404 response. Does not modify the
        # body if already set.
        #
        # @return [void]
        def not_found
          self.status = 404
          return unless body.empty?
          self.body = "Not found: #{request.path}"
          headers['Content-Type'] = 'text/plain'
          headers['X-Cascade'] = 'pass'
          headers['Cache-Control'] = 'nocache'
        end

        # Sets the headers and status code for a redirection to a given URL
        # @param [String] url the URL to redirect to
        # @raise [FinishRequest] causes the request to terminate.
        def redirect(url)
          headers['Location'] = url
          self.status = 302
          raise FinishRequest
        end

        private

        # Add a conservative cache control policy to reduce load on
        # requests served with "?1234567890" style timestamp query strings.
        def add_cache_control
          return if request.query_string.to_i == 0
          headers['Cache-Control'] ||= 'public, max-age=300'
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/display_file_command.rb000066400000000000000000000017261466601756300241000ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      # Displays a README or extra file.
      #
      # @todo Implement better support for detecting binary (image) filetypes
      class DisplayFileCommand < LibraryCommand
        attr_accessor :index

        def run
          filename = File.cleanpath(File.join(library.source_path, path))
          raise NotFoundError unless File.file?(filename)
          if filename =~ /\.(jpe?g|gif|png|bmp|svg)$/i
            headers['Content-Type'] = StaticFileCommand::DefaultMimeTypes[$1.downcase] || 'text/html'
            render File.read_binary(filename)
          else
            file = CodeObjects::ExtraFileObject.new(filename)
            options.update :object => Registry.root,
                           :type => :layout,
                           :file => file,
                           :index => index ? true : false
            render
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/display_object_command.rb000066400000000000000000000032521466601756300244230ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      # Displays documentation for a specific object identified by the path
      class DisplayObjectCommand < LibraryCommand
        include DocServerHelper

        def run
          if path.empty?
            if options.readme
              filename = options.readme.filename
              opts = adapter.options.merge(
                :index => true, :library => library,
                :path => filename.sub(%r{^#{library.source_path.to_s}/}, '')
              )
              self.status, self.headers, self.body =
                *DisplayFileCommand.new(opts).call(request)
              cache(body)
              return
            else
              self.path = 'index'
            end
          end
          return index if path == 'index'

          object = Registry.at(object_path)
          if object
            options.update(:type => :layout)
            render(object)
          else
            not_found
          end
        end

        def index
          Registry.load_all

          options.update(
            :object => '_index.html',
            :objects => Registry.all(:module, :class),
            :type => :layout
          )
          render
        end

        def not_found
          super
          self.body = "Could not find object: #{object_path}"
        end

        private

        def object_path
          return @object_path if @object_path
          if path == "toplevel"
            @object_path = :root
          else
            @object_path = path.sub(':', '#').gsub('/', '::').sub(/^toplevel\b/, '').sub(/\.html$/, '')
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/frames_command.rb000066400000000000000000000006001466601756300226770ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      # Displays an object wrapped in frames
      class FramesCommand < DisplayObjectCommand
        def run
          options.update(:frames => true, :type => :fulldoc)
          tpl = fulldoc_template
          tpl.generate_frameset
          cache(tpl.contents)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/library_command.rb000066400000000000000000000134321466601756300230750ustar00rootroot00000000000000# frozen_string_literal: true
require 'thread'

module YARD
  module Server
    module Commands
      class LibraryOptions < CLI::YardocOptions
        def adapter; @command.adapter end
        def library; @command.library end
        def single_library; @command.single_library end
        def serializer; @command.serializer end
        def serialize; false end

        attr_accessor :command
        attr_accessor :frames

        def each(&block)
          super(&block)
          yield(:adapter, adapter)
          yield(:library, library)
          yield(:single_library, single_library)
          yield(:serializer, serializer)
        end
      end

      # This is the base command for all commands that deal directly with libraries.
      # Some commands do not, but most (like {DisplayObjectCommand}) do. If your
      # command deals with libraries directly, subclass this class instead.
      # See {Base} for notes on how to subclass a command.
      #
      # @abstract
      class LibraryCommand < Base
        begin
          Process.fork { }
          CAN_FORK = true
        rescue Exception # rubocop:disable Lint/RescueException
          CAN_FORK = false
        end

        # @return [LibraryVersion] the object containing library information
        attr_accessor :library

        # @return [LibraryOptions] default options for the library
        attr_accessor :options

        # @return [Serializers::Base] the serializer used to perform file linking
        attr_accessor :serializer

        # @return [Boolean] whether router should route for multiple libraries
        attr_accessor :single_library

        # @return [Boolean] whether to reparse data
        attr_accessor :incremental

        # @return [Boolean] whether or not this adapter calls +fork+ when serving
        #   library requests. Defaults to false.
        attr_accessor :use_fork

        # Needed to synchronize threads in {#setup_yardopts}
        # @private
        @@library_chdir_lock = Mutex.new

        def initialize(opts = {})
          super
          self.serializer = DocServerSerializer.new
        end

        def call(request)
          if can_fork?
            call_with_fork(request) { super }
          else
            begin
              save_default_template_info
              call_without_fork(request) { super }
            ensure
              restore_template_info
            end
          end
        end

        private

        def call_without_fork(request)
          self.request = request
          self.options = LibraryOptions.new
          options.reset_defaults
          options.command = self
          setup_library
          options.title = "Documentation for #{library.name} " +
                          (library.version ? '(' + library.version + ')' : '')
          yield
        rescue LibraryNotPreparedError
          not_prepared
        end

        def call_with_fork(request, &block)
          IO.pipe(:binmode => true) do |reader, writer|
            fork do
              log.debug "[pid=#{Process.pid}] fork serving: #{request.path}"
              reader.close
              writer.print(Marshal.dump(call_without_fork(request, &block)))
            end

            writer.close
            Marshal.load(reader.read)
          end
        end

        def can_fork?
          CAN_FORK && use_fork
        end

        def save_default_template_info
          @old_template_paths = Templates::Engine.template_paths.dup
          @old_extra_includes = Templates::Template.extra_includes.dup
        end

        def restore_template_info
          Templates::Engine.template_paths = @old_template_paths
          Templates::Template.extra_includes = @old_extra_includes
        end

        def setup_library
          library.prepare! if request.xhr? && request.query['process']
          load_yardoc
          setup_yardopts
          true
        end

        def setup_yardopts
          @@library_chdir_lock.synchronize do
            Dir.chdir(library.source_path) do
              yardoc = CLI::Yardoc.new
              if incremental
                yardoc.run('-c', '-n', '--no-stats')
              else
                yardoc.parse_arguments
              end
              yardoc.send(:verify_markup_options)
              yardoc.options.delete(:serializer)
              yardoc.options.delete(:serialize)
              options.update(yardoc.options.to_hash)
            end
          end
        end

        def load_yardoc
          raise LibraryNotPreparedError unless library.ready?
          if Thread.current[:__yard_last_yardoc__] == library.yardoc_file
            log.debug "Reusing yardoc file: #{library.yardoc_file}"
            return
          end
          Registry.clear
          Templates::ErbCache.clear!
          Registry.load_yardoc(library.yardoc_file)
          Thread.current[:__yard_last_yardoc__] = library.yardoc_file
        end

        def not_prepared
          options.update(:template => :doc_server, :type => :processing)
          self.caching = false
          self.status = 202
          self.body = render
          self.headers = {'Content-Type' => 'text/html'}
          [status, headers, [body]]
        end

        # Hack to load a custom fulldoc template object that does
        # not do any rendering/generation. We need this to access the
        # generate_*_list methods.
        def fulldoc_template
          tplopts = [options.template, :fulldoc, options.format]
          tplclass = Templates::Engine.template(*tplopts)
          obj = Object.new.extend(tplclass)
          class << obj; define_method(:init) {} end
          obj.class = tplclass
          obj.send(:initialize, options)
          class << obj
            attr_reader :contents
            define_method(:asset) {|_, contents| @contents = contents }
          end
          obj
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/library_index_command.rb000066400000000000000000000013161466601756300242620ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      class LibraryIndexOptions < CLI::YardocOptions
        attr_accessor :adapter, :libraries
        default_attr :template, :doc_server
        default_attr :type, :library_list
        default_attr :serialize, false
      end

      # Returns the index of libraries served by the server.
      class LibraryIndexCommand < Base
        attr_accessor :options

        def run
          return unless path.empty?

          self.options = LibraryIndexOptions.new
          options.adapter = adapter
          options.libraries = adapter.libraries
          options.reset_defaults
          render
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/list_command.rb000066400000000000000000000012251466601756300224010ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      # Returns a list of objects of a specific type
      class ListCommand < LibraryCommand
        include Templates::Helpers::BaseHelper

        def run
          Registry.load_all
          options.update(:objects => run_verifier(Registry.all(:class, :module)))
          list_type = request.path.split('/').last
          meth = "generate_#{list_type}_list"
          tpl = fulldoc_template
          if tpl.respond_to?(meth)
            tpl.send(meth)
            cache(tpl.contents)
          else
            not_found
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/root_request_command.rb000066400000000000000000000004741466601756300241660ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      # Serves requests from the root of the server
      class RootRequestCommand < Base
        include StaticFileHelpers

        def run
          static_template_file? || favicon? || not_found
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/search_command.rb000066400000000000000000000045741466601756300227050ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      # Performs a search over the objects inside of a library and returns
      # the results as HTML or plaintext
      class SearchCommand < LibraryCommand
        include Templates::Helpers::BaseHelper
        include Templates::Helpers::ModuleHelper
        include DocServerHelper

        attr_accessor :results, :query

        def run
          Registry.load_all
          self.query = request.query['q']
          redirect(abs_url(adapter.router.docs_prefix, single_library ? library : '')) if query.nil? || query =~ /\A\s*\Z/

          found = Registry.at(query)
          redirect(url_for(found)) if found

          search_for_object
          request.xhr? ? serve_xhr : serve_normal
        end

        def visible_results
          results[0, 10]
        end

        private

        def url_for(object)
          abs_url(base_path(router.docs_prefix),
            serializer.serialized_path(object))
        end

        def serve_xhr
          headers['Content-Type'] = 'text/plain'
          self.body = visible_results.map {|o|
            [(o.type == :method ? o.name(true) : o.name).to_s,
             o.path,
             o.namespace.root? ? '' : o.namespace.path,
             url_for(o)].join(",")
          }.join("\n")
        end

        def serve_normal
          options.update(
            :visible_results => visible_results,
            :query => query,
            :results => results,
            :template => :doc_server,
            :type => :search
          )
          self.body = Templates::Engine.render(options)
        end

        def search_for_object
          # rubocop:disable Style/MultilineBlockChain
          self.results = run_verifier(Registry.all).select do |o|
            o.path.downcase.include?(query.downcase)
          end.reject do |o|
            name = (o.type == :method ? o.name(true) : o.name).to_s.downcase
            !name.include?(query.downcase) ||
              case o.type
              when :method
                !(query =~ /[#.]/) && query.include?("::")
              when :class, :module, :constant, :class_variable
                query =~ /[#.]/
              end
          end.sort_by do |o|
            name = (o.type == :method ? o.name(true) : o.name).to_s
            name.length.to_f / query.length.to_f
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/static_file_command.rb000066400000000000000000000012741466601756300237200ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    module Commands
      # Serves static content when no other router matches a request
      class StaticFileCommand < LibraryCommand
        include StaticFileHelpers

        DefaultMimeTypes['js'] = 'text/javascript'

        # Defines the paths used to search for static assets. To define an
        # extra path, use {YARD::Server.register_static_path} rather than
        # modifying this constant directly. Also note that files in the
        # document root will always take precedence over these paths.
        STATIC_PATHS = []

        def run
          static_template_file? || not_found
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/commands/static_file_helpers.rb000066400000000000000000000036071466601756300237460ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module Server
    module Commands
      # Include this module to get access to {#static_template_file?}
      # and {favicon?} helpers.
      module StaticFileHelpers
        include Server::HTTPUtils

        # Serves an empty favicon.
        # @raise [FinishRequest] finalizes an empty body if the path matches
        #   /favicon.ico so browsers don't complain.
        def favicon?
          return unless request.path == '/favicon.ico'
          headers['Content-Type'] = 'image/png'
          self.status = 200
          self.body = ''
          raise FinishRequest
        end

        # Attempts to route a path to a static template file.
        #
        # @raise [FinishRequest] if a file was found and served
        # @return [void]
        def static_template_file?
          # this const was defined in StaticFileCommand originally
          default_mime_types = StaticFileCommand::DefaultMimeTypes

          file = find_file(adapter, path)

          if file
            ext = "." + (path[/\.(\w+)$/, 1] || "html")
            headers['Content-Type'] = mime_type(ext, default_mime_types)
            self.body = File.read(file)
            raise FinishRequest
          end
        end

        module_function

        def find_file(adapter, url)
          # this const was defined in StaticFileCommand originally
          static_paths = StaticFileCommand::STATIC_PATHS

          file = nil
          ([adapter.document_root] + static_paths.reverse).compact.each do |path_prefix|
            file = File.join(path_prefix, url)
            break if File.exist?(file)
            file = nil
          end

          # Search in default/fulldoc/html template if nothing in static asset paths
          assets_template = Templates::Engine.template(:default, :fulldoc, :html)
          file || assets_template.find_file(url)
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/server/doc_server_helper.rb000066400000000000000000000071141466601756300216240ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    # A module that is mixed into {Templates::Template} in order to customize
    # certain template methods.
    module DocServerHelper
      # Modifies {Templates::Helpers::HtmlHelper#url_for} to return a URL instead
      # of a disk location.
      # @param (see Templates::Helpers::HtmlHelper#url_for)
      # @return (see Templates::Helpers::HtmlHelper#url_for)
      def url_for(obj, anchor = nil, relative = false) # rubocop:disable Lint/UnusedMethodArgument
        return '' if obj.nil?
        return url_for_index if obj == '_index.html'
        return abs_url(base_path(router.static_prefix), obj) if String === obj
        url = super(obj, anchor, false)
        return unless url
        abs_url(base_path(router.docs_prefix), url)
      end

      # Modifies {Templates::Helpers::HtmlHelper#url_for_file} to return a URL instead
      # of a disk location.
      # @param (see Templates::Helpers::HtmlHelper#url_for_file)
      # @return (see Templates::Helpers::HtmlHelper#url_for_file)
      def url_for_file(filename, anchor = nil)
        if filename.is_a?(CodeObjects::ExtraFileObject)
          filename = filename.filename
        end
        fname = filename.sub(%r{^#{@library.source_path.to_s}/}, '')
        fname += "##{anchor}" if anchor && !anchor.empty?
        abs_url(base_path(router.docs_prefix), 'file', fname)
      end

      # Modifies {Templates::Helpers::HtmlHelper#url_for_list} to return a URL
      # based on the list prefix instead of a HTML filename.
      # @param (see Templates::Helpers::HtmlHelper#url_for_list)
      # @return (see Templates::Helpers::HtmlHelper#url_for_list)
      def url_for_list(type)
        abs_url(base_path(router.list_prefix), type.to_s)
      end

      # Returns the frames URL for the page
      # @return (see Templates::Helpers::HtmlHelper#url_for_frameset)
      def url_for_frameset
        options.file ? url_for_file(options.file) : url_for(object)
      end

      # Returns the main URL, first checking a readme and then linking to the index
      # @return (see Templates::Helpers::HtmlHelper#url_for_main)
      def url_for_main
        options.readme ? url_for_file(options.readme) : url_for_index
      end

      # Returns the URL for the alphabetic index page
      # @return (see Templates::Helpers::HtmlHelper#url_for_index)
      def url_for_index
        abs_url(base_path(router.docs_prefix), 'index')
      end

      # @param path_components [Array] components of a URL
      # @return [String] the absolute path from any mounted base URI.
      def abs_url(*path_components)
        File.join(router.request.script_name, *path_components)
      end

      # @example The base path for a library 'foo'
      #   base_path('docs') # => 'docs/foo'
      # @param [String] path the path prefix for a base path URI
      # @return [String] the base URI for a library with an extra +path+ prefix
      def base_path(path)
        libname = router.request.version_supplied ? @library.to_s : @library.name
        path + (@single_library ? '' : "/#{libname}")
      end

      # @return [Router] convenience method for accessing the router
      def router; @adapter.router end

      # @return [String] a timestamp for a given file
      def mtime(file)
        file = YARD::Server::Commands::StaticFileHelpers.find_file(@adapter, file)
        file ? File.mtime(file).to_i : nil
      end

      # @return [String] a URL for a file with a timestamp
      def mtime_url(file)
        url = url_for(file)
        time = mtime(file)
        url + (time ? "?#{time}" : "")
      end
    end
  end
end
yard-0.9.37/lib/yard/server/doc_server_serializer.rb000066400000000000000000000024171466601756300225170ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    # A custom {Serializers::Base serializer} which returns resource URLs instead of
    # static relative paths to files on disk.
    class DocServerSerializer < Serializers::FileSystemSerializer
      def initialize(_command = nil)
        super(:basepath => '', :extension => '')
      end

      def serialized_path(object)
        case object
        when CodeObjects::RootObject
          "toplevel"
        when CodeObjects::ExtendedMethodObject
          serialized_path(object.namespace) + ':' + urlencode(object.name.to_s)
        when CodeObjects::MethodObject
          serialized_path(object.namespace) +
            (object.scope == :instance ? ":" : ".") + urlencode(object.name.to_s)
        when CodeObjects::ConstantObject, CodeObjects::ClassVariableObject
          serialized_path(object.namespace) + "##{object.name}-#{object.type}"
        when CodeObjects::ExtraFileObject
          super(object).gsub(/^file\./, 'file/')
        else
          super(object)
        end
      end

      private

      def urlencode(name)
        if name.respond_to?(:force_encoding)
          name = name.dup.force_encoding('binary')
        end
        Templates::Helpers::HtmlHelper.urlencode(name)
      end
    end
  end
end
yard-0.9.37/lib/yard/server/http_utils.rb000066400000000000000000000316701466601756300203350ustar00rootroot00000000000000# frozen_string_literal: false
#
# httputils.rb -- HTTPUtils Module
#
# Author: IPR -- Internet Programming with Ruby -- writers
# Copyright (c) 2000, 2001 TAKAHASHI Masayoshi, GOTOU Yuuzou
# Copyright (c) 2002 Internet Programming with Ruby writers. All rights
# reserved.
#
# $IPR: httputils.rb,v 1.34 2003/06/05 21:34:08 gotoyuzo Exp $

require 'socket'
require 'tempfile'

module YARD::Server
  CR   = "\x0d"     # :nodoc:
  LF   = "\x0a"     # :nodoc:
  CRLF = "\x0d\x0a" # :nodoc:

  ##
  # HTTPUtils provides utility methods for working with the HTTP protocol.
  #
  # This module is generally used internally by WEBrick

  module HTTPUtils

    ##
    # Normalizes a request path.  Raises an exception if the path cannot be
    # normalized.

    def normalize_path(path)
      raise "abnormal path `#{path}'" if path[0] != ?/
      ret = path.dup

      ret.gsub!(%r{/+}o, '/')                    # //      => /
      while ret.sub!(%r'/\.(?:/|\Z)', '/'); end  # /.      => /
      while ret.sub!(%r'/(?!\.\./)[^/]+/\.\.(?:/|\Z)', '/'); end # /foo/.. => /foo

      raise "abnormal path `#{path}'" if %r{/\.\.(/|\Z)} =~ ret
      ret
    end
    module_function :normalize_path

    ##
    # Default mime types

    DefaultMimeTypes = {
      "ai"    => "application/postscript",
      "asc"   => "text/plain",
      "avi"   => "video/x-msvideo",
      "bin"   => "application/octet-stream",
      "bmp"   => "image/bmp",
      "class" => "application/octet-stream",
      "cer"   => "application/pkix-cert",
      "crl"   => "application/pkix-crl",
      "crt"   => "application/x-x509-ca-cert",
     #"crl"   => "application/x-pkcs7-crl",
      "css"   => "text/css",
      "dms"   => "application/octet-stream",
      "doc"   => "application/msword",
      "dvi"   => "application/x-dvi",
      "eps"   => "application/postscript",
      "etx"   => "text/x-setext",
      "exe"   => "application/octet-stream",
      "gif"   => "image/gif",
      "htm"   => "text/html",
      "html"  => "text/html",
      "jpe"   => "image/jpeg",
      "jpeg"  => "image/jpeg",
      "jpg"   => "image/jpeg",
      "js"    => "application/javascript",
      "json"  => "application/json",
      "lha"   => "application/octet-stream",
      "lzh"   => "application/octet-stream",
      "mjs"   => "application/javascript",
      "mov"   => "video/quicktime",
      "mpe"   => "video/mpeg",
      "mpeg"  => "video/mpeg",
      "mpg"   => "video/mpeg",
      "pbm"   => "image/x-portable-bitmap",
      "pdf"   => "application/pdf",
      "pgm"   => "image/x-portable-graymap",
      "png"   => "image/png",
      "pnm"   => "image/x-portable-anymap",
      "ppm"   => "image/x-portable-pixmap",
      "ppt"   => "application/vnd.ms-powerpoint",
      "ps"    => "application/postscript",
      "qt"    => "video/quicktime",
      "ras"   => "image/x-cmu-raster",
      "rb"    => "text/plain",
      "rd"    => "text/plain",
      "rtf"   => "application/rtf",
      "sgm"   => "text/sgml",
      "sgml"  => "text/sgml",
      "svg"   => "image/svg+xml",
      "tif"   => "image/tiff",
      "tiff"  => "image/tiff",
      "txt"   => "text/plain",
      "wasm"  => "application/wasm",
      "xbm"   => "image/x-xbitmap",
      "xhtml" => "text/html",
      "xls"   => "application/vnd.ms-excel",
      "xml"   => "text/xml",
      "xpm"   => "image/x-xpixmap",
      "xwd"   => "image/x-xwindowdump",
      "zip"   => "application/zip",
    }

    ##
    # Loads Apache-compatible mime.types in +file+.

    def load_mime_types(file)
      # note: +file+ may be a "| command" for now; some people may
      # rely on this, but currently we do not use this method by default.
      open(file){ |io|
        hash = Hash.new
        io.each{ |line|
          next if /^#/ =~ line
          line.chomp!
          mimetype, ext0 = line.split(/\s+/, 2)
          next unless ext0
          next if ext0.empty?
          ext0.split(/\s+/).each{ |ext| hash[ext] = mimetype }
        }
        hash
      }
    end
    module_function :load_mime_types

    ##
    # Returns the mime type of +filename+ from the list in +mime_tab+.  If no
    # mime type was found application/octet-stream is returned.

    def mime_type(filename, mime_tab)
      suffix1 = (/\.(\w+)$/ =~ filename && $1.downcase)
      suffix2 = (/\.(\w+)\.[\w\-]+$/ =~ filename && $1.downcase)
      mime_tab[suffix1] || mime_tab[suffix2] || "application/octet-stream"
    end
    module_function :mime_type

    ##
    # Parses an HTTP header +raw+ into a hash of header fields with an Array
    # of values.

    def parse_header(raw)
      header = Hash.new([].freeze)
      field = nil
      raw.each_line{|line|
        case line
        when /^([A-Za-z0-9!\#$%&'*+\-.^_`|~]+):\s*(.*?)\s*\z/om
          field, value = $1, $2
          field.downcase!
          header[field] = [] unless header.has_key?(field)
          header[field] << value
        when /^\s+(.*?)\s*\z/om
          value = $1
          unless field
            raise HTTPStatus::BadRequest, "bad header '#{line}'."
          end
          header[field][-1] << " " << value
        else
          raise HTTPStatus::BadRequest, "bad header '#{line}'."
        end
      }
      header.each{|key, values|
        values.each(&:strip!)
      }
      header
    end
    module_function :parse_header

    ##
    # Splits a header value +str+ according to HTTP specification.

    def split_header_value(str)
      str.scan(%r'\G((?:"(?:\\.|[^"])+?"|[^",]+)+)
                    (?:,\s*|\Z)'xn).flatten
    end
    module_function :split_header_value

    ##
    # Parses a Range header value +ranges_specifier+

    def parse_range_header(ranges_specifier)
      if /^bytes=(.*)/ =~ ranges_specifier
        byte_range_set = split_header_value($1)
        byte_range_set.collect{|range_spec|
          case range_spec
          when /^(\d+)-(\d+)/ then $1.to_i .. $2.to_i
          when /^(\d+)-/      then $1.to_i .. -1
          when /^-(\d+)/      then -($1.to_i) .. -1
          else return nil
          end
        }
      end
    end
    module_function :parse_range_header

    ##
    # Parses q values in +value+ as used in Accept headers.

    def parse_qvalues(value)
      tmp = []
      if value
        parts = value.split(/,\s*/)
        parts.each {|part|
          if m = %r{^([^\s,]+?)(?:;\s*q=(\d+(?:\.\d+)?))?$}.match(part)
            val = m[1]
            q = (m[2] or 1).to_f
            tmp.push([val, q])
          end
        }
        tmp = tmp.sort_by{|val, q| -q}
        tmp.collect!{|val, q| val}
      end
      return tmp
    end
    module_function :parse_qvalues

    ##
    # Removes quotes and escapes from +str+

    def dequote(str)
      ret = (/\A"(.*)"\Z/ =~ str) ? $1 : str.dup
      ret.gsub!(/\\(.)/, "\\1")
      ret
    end
    module_function :dequote

    ##
    # Quotes and escapes quotes in +str+

    def quote(str)
      '"' << str.gsub(/[\\\"]/o, "\\\1") << '"'
    end
    module_function :quote

    ##
    # Stores multipart form data.  FormData objects are created when
    # WEBrick::HTTPUtils.parse_form_data is called.

    class FormData < String
      EmptyRawHeader = [].freeze # :nodoc:
      EmptyHeader = {}.freeze # :nodoc:

      ##
      # The name of the form data part

      attr_accessor :name

      ##
      # The filename of the form data part

      attr_accessor :filename

      attr_accessor :next_data # :nodoc:
      protected :next_data

      ##
      # Creates a new FormData object.
      #
      # +args+ is an Array of form data entries.  One FormData will be created
      # for each entry.
      #
      # This is called by WEBrick::HTTPUtils.parse_form_data for you

      def initialize(*args)
        @name = @filename = @next_data = nil
        if args.empty?
          @raw_header = []
          @header = nil
          super("")
        else
          @raw_header = EmptyRawHeader
          @header = EmptyHeader
          super(args.shift)
          unless args.empty?
            @next_data = self.class.new(*args)
          end
        end
      end

      ##
      # Retrieves the header at the first entry in +key+

      def [](*key)
        begin
          @header[key[0].downcase].join(", ")
        rescue StandardError, NameError
          super
        end
      end

      ##
      # Adds +str+ to this FormData which may be the body, a header or a
      # header entry.
      #
      # This is called by WEBrick::HTTPUtils.parse_form_data for you

      def <<(str)
        if @header
          super
        elsif str == CRLF
          @header = HTTPUtils::parse_header(@raw_header.join)
          if cd = self['content-disposition']
            if /\s+name="(.*?)"/ =~ cd then @name = $1 end
            if /\s+filename="(.*?)"/ =~ cd then @filename = $1 end
          end
        else
          @raw_header << str
        end
        self
      end

      ##
      # Adds +data+ at the end of the chain of entries
      #
      # This is called by WEBrick::HTTPUtils.parse_form_data for you.

      def append_data(data)
        tmp = self
        while tmp
          unless tmp.next_data
            tmp.next_data = data
            break
          end
          tmp = tmp.next_data
        end
        self
      end

      ##
      # Yields each entry in this FormData

      def each_data
        tmp = self
        while tmp
          next_data = tmp.next_data
          yield(tmp)
          tmp = next_data
        end
      end

      ##
      # Returns all the FormData as an Array

      def list
        ret = []
        each_data{|data|
          ret << data.to_s
        }
        ret
      end

      ##
      # A FormData will behave like an Array

      alias :to_ary :list

      ##
      # This FormData's body

      def to_s
        String.new(self)
      end
    end

    ##
    # Parses the query component of a URI in +str+

    def parse_query(str)
      query = Hash.new
      if str
        str.split(/[&;]/).each{|x|
          next if x.empty?
          key, val = x.split(/=/,2)
          key = unescape_form(key)
          val = unescape_form(val.to_s)
          val = FormData.new(val)
          val.name = key
          if query.has_key?(key)
            query[key].append_data(val)
            next
          end
          query[key] = val
        }
      end
      query
    end
    module_function :parse_query

    ##
    # Parses form data in +io+ with the given +boundary+

    def parse_form_data(io, boundary)
      boundary_regexp = /\A--#{Regexp.quote(boundary)}(--)?#{CRLF}\z/
      form_data = Hash.new
      return form_data unless io
      data = nil
      io.each_line{|line|
        if boundary_regexp =~ line
          if data
            data.chop!
            key = data.name
            if form_data.has_key?(key)
              form_data[key].append_data(data)
            else
              form_data[key] = data
            end
          end
          data = FormData.new
          next
        else
          if data
            data << line
          end
        end
      }
      return form_data
    end
    module_function :parse_form_data

    #####

    reserved = ';/?:@&=+$,'
    num      = '0123456789'
    lowalpha = 'abcdefghijklmnopqrstuvwxyz'
    upalpha  = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
    mark     = '-_.!~*\'()'
    unreserved = num + lowalpha + upalpha + mark
    control  = (0x0..0x1f).collect{|c| c.chr }.join + "\x7f"
    space    = " "
    delims   = '<>#%"'
    unwise   = '{}|\\^[]`'
    nonascii = (0x80..0xff).collect{|c| c.chr }.join

    module_function

    # :stopdoc:

    def _make_regex(str) /([#{Regexp.escape(str)}])/n end
    def _make_regex!(str) /([^#{Regexp.escape(str)}])/n end
    def _escape(str, regex)
      str = str.b
      str.gsub!(regex) {"%%%02X" % $1.ord}
      # %-escaped string should contain US-ASCII only
      str.force_encoding(Encoding::US_ASCII)
    end
    def _unescape(str, regex)
      str = str.b
      str.gsub!(regex) {$1.hex.chr}
      # encoding of %-unescaped string is unknown
      str
    end

    UNESCAPED = _make_regex(control+space+delims+unwise+nonascii)
    UNESCAPED_FORM = _make_regex(reserved+control+delims+unwise+nonascii)
    NONASCII  = _make_regex(nonascii)
    ESCAPED   = /%([0-9a-fA-F]{2})/
    UNESCAPED_PCHAR = _make_regex!(unreserved+":@&=+$,")

    # :startdoc:

    ##
    # Escapes HTTP reserved and unwise characters in +str+

    def escape(str)
      _escape(str, UNESCAPED)
    end

    ##
    # Unescapes HTTP reserved and unwise characters in +str+

    def unescape(str)
      _unescape(str, ESCAPED)
    end

    ##
    # Escapes form reserved characters in +str+

    def escape_form(str)
      ret = _escape(str, UNESCAPED_FORM)
      ret.gsub!(/ /, "+")
      ret
    end

    ##
    # Unescapes form reserved characters in +str+

    def unescape_form(str)
      _unescape(str.gsub(/\+/, " "), ESCAPED)
    end

    ##
    # Escapes path +str+

    def escape_path(str)
      result = ""
      str.scan(%r{/([^/]*)}).each{|i|
        result << "/" << _escape(i[0], UNESCAPED_PCHAR)
      }
      return result
    end

    ##
    # Escapes 8 bit characters in +str+

    def escape8bit(str)
      _escape(str, NONASCII)
    end
  end
end
yard-0.9.37/lib/yard/server/library_version.rb000066400000000000000000000262671466601756300213550ustar00rootroot00000000000000# frozen_string_literal: true
require 'fileutils'
require 'thread'

module YARD
  module Server
    # This exception is raised when {LibraryVersion#prepare!} fails, or discovers
    # that the library is not "prepared" to be served by
    class LibraryNotPreparedError < RuntimeError; end

    # A library version encapsulates a library's documentation at a specific version.
    # Although the version is optional, this allows for creating multiple documentation
    # points for a specific library, each representing a unique version. The term
    # "library" used in other parts of the YARD::Server documentation refers to
    # objects of this class unless otherwise noted.
    #
    # A library points to a location where a {#yardoc_file} is located so that
    # its documentation may be loaded and served. Optionally, a {#source_path} is
    # given to point to a location where any extra files (and {YARD::CLI::Yardoc .yardopts})
    # should be loaded from. Both of these methods may not be known immediately,
    # since the yardoc file may not be built until later. Resolving the yardoc
    # file and source path are dependent on the specific library "source type" used.
    # Source types (known as "library source") are discussed in detail below.
    #
    # == Using with Adapters
    # A list of libraries need to be passed into adapters upon creation. In
    # most cases, you will never do this manually, but if you use a {RackMiddleware},
    # you will need to pass in this list yourself. To build this list of libraries,
    # you should create a hash of library names mapped to an *Array* of LibraryVersion
    # objects. For example:
    #
    #   {'mylib' => [LibraryVersion.new('mylib', '1.0', ...),
    #                LibraryVersion.new('mylib', '2.0', ...)]}
    #
    # Note that you can also use {Adapter#add_library} for convenience.
    #
    # The "array" part is required, even for just one library version.
    #
    # == Library Sources
    # The {#source} method represents the library source type, ie. where the
    # library "comes from". It might come from "disk", or it might come from a
    # "gem" (technically the disk, but a separate type nonetheless). In these
    # two cases, the yardoc file sits somewhere on your filesystem, though
    # it may also be built dynamically if it does not yet exist. This behaviour
    # is controlled through the {#prepare!} method, which prepares the yardoc file
    # given a specific library source. We will see how this works in detail in
    # the following section.
    #
    # == Implementing a Custom Library Source
    # YARD can be extended to support custom library sources in order to
    # build or retrieve a yardoc file at runtime from many different locations.
    #
    # To implement this behaviour, 3 methods can be added to the +LibraryVersion+
    # class, +#load_yardoc_from_SOURCE+, +#yardoc_file_for_SOURCE+, and
    # +#source_path_for_SOURCE+. In all cases, "SOURCE" represents the source
    # type used in {#source} when creating the library object. The
    # +#yardoc_file_for_SOURCE+ and +#source_path_for_SOURCE+ methods are called upon
    # creation and should return the location where the source code for the library
    # lives. The load method is called from {#prepare!} if there is no yardoc file
    # and should set {#yardoc_file}. Below is a full example for
    # implementing a custom library source, +:http+, which reads packaged .yardoc
    # databases from zipped archives off of an HTTP server.
    #
    # Note that only +#load_yardoc_from_SOURCE+ is required. The other two
    # methods are optional and can be set manually (via {#source_path=} and
    # {#yardoc_file=}) on the object at any time.
    #
    # @example Implementing a Custom Library Source
    #   # Adds the source type "http" for .yardoc files zipped on HTTP servers
    #   class LibraryVersion
    #     def load_yardoc_from_http
    #       Thread.new do
    #         # zip/unzip method implementations are not shown
    #         download_zip_file("http://mysite.com/yardocs/#{self}.zip")
    #         unzip_file_to("/path/to/yardocs/#{self}")
    #       end
    #
    #       # tell the server it's not ready yet (but it might be next time)
    #       raise LibraryNotPreparedError
    #     end
    #
    #     def yardoc_file_for_http
    #       "/path/to/yardocs/#{self}/.yardoc"
    #     end
    #
    #     def source_path_for_http
    #       File.dirname(yardoc_file)
    #     end
    #   end
    #
    #   # Creating a library of this source type:
    #   LibraryVersion.new('name', '1.0', nil, :http)
    #
    class LibraryVersion
      # @return [String] the name of the library
      attr_accessor :name

      # @return [String] the version of the specific library
      attr_accessor :version

      # @return [String] the location of the yardoc file used to load the object
      #   information from.
      # @return [nil] if no yardoc file exists yet. In this case, {#prepare!} will
      #   be called on this library to build the yardoc file.
      # @note To implement a custom yardoc file getter, implement
      def yardoc_file
        @yardoc_file ||= load_yardoc_file
      end
      attr_writer :yardoc_file

      # @return [Symbol] the source type representing where the yardoc should be
      #   loaded from. Defaults are +:disk+ and +:gem+, though custom sources
      #   may be implemented. This value is used to inform {#prepare!} about how
      #   to load the necessary data in order to display documentation for an object.
      # @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
      attr_accessor :source

      # @return [String] the location of the source code for a library. This
      #   value is filled by calling +#source_path_for_SOURCE+ on this class.
      # @return [nil] if there is no source code
      # @see LibraryVersion LibraryVersion documentation for "Implementing a Custom Library Source"
      def source_path
        @source_path ||= load_source_path
      end
      attr_writer :source_path

      # @param [String] name the name of the library
      # @param [String] version the specific (usually, but not always, numeric) library
      #   version
      # @param [String] yardoc the location of the yardoc file, or nil if it is
      #   generated later
      # @param [Symbol] source the location of the files used to build the yardoc.
      #   Builtin source types are +:disk+ or +:gem+.
      def initialize(name, version = nil, yardoc = nil, source = :disk)
        self.name = name
        self.yardoc_file = yardoc
        self.version = version
        self.source = source
      end

      # @param [Boolean] url_format if true, returns the string in a URI-compatible
      #   format (for appending to a URL). Otherwise, it is given in a more human
      #   readable format.
      # @return [String] the string representation of the library.
      def to_s(url_format = true)
        version ? "#{name}#{url_format ? '/' : '-'}#{version}" : name.to_s
      end

      # @return [Fixnum] used for Hash mapping.
      def hash; to_s.hash end

      # @return [Boolean] whether another LibraryVersion is equal to this one
      def eql?(other)
        other.is_a?(LibraryVersion) && other.name == name &&
          other.version == version && other.yardoc_file == yardoc_file
      end
      alias == eql?
      alias equal? eql?

      # @return [Boolean] whether the library has been completely processed
      #   and is ready to be served
      def ready?
        return false if yardoc_file.nil?
        serializer.complete?
      end

      # @note You should not directly override this method. Instead, implement
      #   +load_yardoc_from_SOURCENAME+ when implementing loading for a specific
      #   source type. See the {LibraryVersion} documentation for "Implementing
      #   a Custom Library Source"
      #
      # Prepares a library to be displayed by the server. This callback is
      # performed before each request on a library to ensure that it is loaded
      # and ready to be viewed. If any steps need to be performed prior to loading,
      # they are performed through this method (though they should be implemented
      # through the +load_yardoc_from_SOURCE+ method).
      #
      # @raise [LibraryNotPreparedError] if the library is not ready to be
      #   displayed. Usually when raising this error, you would simultaneously
      #   begin preparing the library for subsequent requests, although this
      #   is not necessary.
      def prepare!
        return if ready?
        meth = "load_yardoc_from_#{source}"
        send(meth) if respond_to?(meth, true)
      end

      # @return [Gem::Specification] a gemspec object for a given library. Used
      #   for :gem source types.
      # @return [nil] if there is no installed gem for the library
      def gemspec
        ver = version ? "= #{version}" : ">= 0"
        YARD::GemIndex.find_all_by_name(name, ver).last
      end

      protected

      @@chdir_mutex = Mutex.new

      # Called when a library of source type "disk" is to be prepared. In this
      # case, the {#yardoc_file} should already be set, but the library may not
      # be prepared. Run preparation if not done.
      #
      # @raise [LibraryNotPreparedError] if the yardoc file has not been
      #   prepared.
      def load_yardoc_from_disk
        return if ready?

        @@chdir_mutex.synchronize do
          Dir.chdir(source_path_for_disk) do
            Thread.new do
              CLI::Yardoc.run('--no-stats', '-n', '-b', yardoc_file)
            end
          end
        end

        raise LibraryNotPreparedError
      end

      # Called when a library of source type "gem" is to be prepared. In this
      # case, the {#yardoc_file} needs to point to the correct location for
      # the installed gem. The yardoc file is built if it has not been done.
      #
      # @raise [LibraryNotPreparedError] if the gem does not have an existing
      #   yardoc file.
      def load_yardoc_from_gem
        return if ready?
        ver = version ? "= #{version}" : ">= 0"

        @@chdir_mutex.synchronize do
          Thread.new do
            # Build gem docs on demand
            log.debug "Building gem docs for #{to_s(false)}"
            CLI::Gems.run(name, ver)
            log.debug "Done building gem docs for #{to_s(false)}"
          end
        end

        raise LibraryNotPreparedError
      end

      # @return [String] the source path for a disk source
      def source_path_for_disk
        File.dirname(yardoc_file) if yardoc_file
      end

      # @return [String] the source path for a gem source
      def source_path_for_gem
        gemspec.full_gem_path if gemspec
      end

      # @return [String] the yardoc file for a gem source
      def yardoc_file_for_gem
        require 'rubygems'
        ver = version ? "= #{version}" : ">= 0"
        Registry.yardoc_file_for_gem(name, ver)
      end

      private

      def load_source_path
        meth = "source_path_for_#{source}"
        send(meth) if respond_to?(meth, true)
      end

      def load_yardoc_file
        meth = "yardoc_file_for_#{source}"
        send(meth) if respond_to?(meth, true)
      end

      def serializer
        return if yardoc_file.nil?
        Serializers::YardocSerializer.new(yardoc_file)
      end
    end
  end
end
yard-0.9.37/lib/yard/server/rack_adapter.rb000066400000000000000000000066151466601756300205570ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module Server
    begin
      require 'rackup'
      # @private
      RackServer = Rackup::Server
    rescue LoadError
      require 'rack'
      # @private
      RackServer = Rack::Server
    end

    # This class wraps the {RackAdapter} into a Rack-compatible middleware.
    # See {#initialize} for a list of options to pass via Rack's +#use+ method.
    #
    # @note You must pass a +:libraries+ option to the RackMiddleware via +#use+. To
    #   read about how to return a list of libraries, see {LibraryVersion} or look
    #   at the example below.
    # @example Using the RackMiddleware in a Rack application
    #   libraries = {:mylib => [YARD::Server::LibraryVersion.new('mylib', nil, '/path/to/.yardoc')]}
    #   use YARD::Server::RackMiddleware, :libraries => libraries
    #
    class RackMiddleware
      # Creates a new Rack-based middleware for serving YARD documentation.
      #
      # @param app the next Rack middleware in the stack
      # @option opts [Hash{String=>Array}] :libraries ({})
      #   the map of libraries to serve through the adapter. This option is *required*.
      # @option opts [Hash] :options ({}) a list of options to pass to the adapter.
      #   See {Adapter#options} for a list.
      # @option opts [Hash] :server_options ({}) a list of options to pass to the server.
      #   See {Adapter#server_options} for a list.
      def initialize(app, opts = {})
        args = [opts[:libraries] || {}, opts[:options] || {}, opts[:server_options] || {}]
        @app = app
        @adapter = RackAdapter.new(*args)
      end

      def call(env)
        status, headers, body = *@adapter.call(env)
        if status == 404
          @app.call(env)
        else
          [status, headers, body]
        end
      end
    end

    # A server adapter to respond to requests using the Rack server infrastructure.
    class RackAdapter < Adapter
      include YARD::Server::HTTPUtils

      # Responds to Rack requests and builds a response with the {Router}.
      # @return [Array(Numeric,Hash,Array)] the Rack-style response
      def call(env)
        request = Rack::Request.new(env)
        request.path_info = unescape(request.path_info) # unescape things like %3F
        router.call(request)
      rescue StandardError => ex
        log.backtrace(ex)
        [500, {'Content-Type' => 'text/plain'},
          [ex.message + "\n" + ex.backtrace.join("\n")]]
      end

      # Starts the Rack server. This method will pass control to the server and
      # block.
      # @return [void]
      def start
        server = RackServer.new(server_options)
        server.instance_variable_set("@app", self)
        print_start_message(server)
        server.start
      end

      private

      def print_start_message(server)
        opts = server.default_options.merge(server.options)
        log.puts ">> YARD #{YARD::VERSION} documentation server at http://#{opts[:Host]}:#{opts[:Port]}"

        # Only happens for Mongrel
        return unless server.server.to_s == "Rack::Handler::Mongrel"
        log.puts ">> #{server.server.class_name} web server (running on Rack)"
        log.puts ">> Listening on #{opts[:Host]}:#{opts[:Port]}, CTRL+C to stop"
      end
    end
  end
end

# @private
class Rack::Request
  attr_accessor :version_supplied
  alias query params
  def xhr?; (env['HTTP_X_REQUESTED_WITH'] || "").casecmp("xmlhttprequest") == 0 end
end
yard-0.9.37/lib/yard/server/router.rb000066400000000000000000000153631466601756300174570ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    # A router class implements the logic used to recognize a request for a specific
    # URL and run specific {Commands::Base commands}.
    #
    # == Subclassing Notes
    # To create a custom router, subclass this class and pass it into the adapter
    # options through {Adapter#initialize} or by directly modifying {Adapter#router}.
    #
    # The most general customization is to change the URL prefixes recognized by
    # routing, which can be done by overriding {#docs_prefix}, {#list_prefix},
    # {#static_prefix}, and {#search_prefix}.
    #
    # == Implementing Custom Caching
    # By default, the Router class performs static disk-based caching on all
    # requests through the +#check_static_cache+. To override this behaviour,
    # or create your own caching mechanism, mixin your own custom module with
    # this method implemented as per {StaticCaching#check_static_cache}.
    #
    # @example Creating a subclassed router
    #   # Adds 'my' to all routing prefixes
    #   class MyRouter < YARD::Server::Router
    #     def docs_prefix; 'mydocs' end
    #     def list_prefix; 'mylist' end
    #     def static_prefix; 'mystatic' end
    #     def search_prefix; 'mysearch' end
    #   end
    #
    #   # Using it:
    #   WebrickAdapter.new(libraries, :router => MyRouter).start
    class Router
      include StaticCaching
      include Commands

      # @return [Adapter Dependent] the request data coming in with the routing
      attr_accessor :request

      # @return [Adapter] the adapter used by the router
      attr_accessor :adapter

      # Creates a new router for a specific adapter
      #
      # @param [Adapter] adapter the adapter to route requests to
      def initialize(adapter)
        self.adapter = adapter
      end

      # Perform routing on a specific request, serving the request as a static
      # file through {Commands::RootRequestCommand} if no route is found.
      #
      # @param [Adapter Dependent] request the request object
      # @return [Array(Numeric,Hash,Array)] the Rack-style server response data
      def call(request)
        self.request = request
        result = check_static_cache || route
        result ? result : RootRequestCommand.new(adapter.options).call(request)
      end

      # @group Route Prefixes

      # @return [String] the URI prefix for all object documentation requests
      def docs_prefix; 'docs' end

      # @return [String] the URI prefix for all class/method/file list requests
      def list_prefix; 'list' end

      # @return [String] the URI prefix for all search requests
      def search_prefix; 'search' end

      # @return [String] the URI prefix for all static assets (templates)
      def static_prefix; 'static' end

      # @group Routing Methods

      # @return [Array(LibraryVersion, Array)] the library followed
      #   by the rest of the path components in the request path. LibraryVersion
      #   will be nil if no matching library was found.
      def parse_library_from_path(paths)
        return [adapter.libraries.values.first.first, paths] if adapter.options[:single_library]
        library = nil
        paths = paths.dup
        libs = adapter.libraries[paths.first]
        if libs
          paths.shift
          library = libs.find {|l| l.version == paths.first }
          if library
            request.version_supplied = true if request
            paths.shift
          else # use the last lib in the list
            request.version_supplied = false if request
            library = libs.last
          end
        end
        [library, paths]
      end

      protected

      # Performs routing algorithm to find which prefix is called, first
      # parsing out library name/version information.
      #
      # @return [Array(Numeric,Hash,Array)] the Rack-style response
      # @return [nil] if no route is matched
      def route(path = request.path_info)
        path = path.gsub(%r{//+}, '/').gsub(%r{^/|/$}, '')
        return route_index if path.empty? || path == docs_prefix
        case path
        when %r{^(#{docs_prefix}|#{list_prefix}|#{search_prefix}|#{static_prefix})(/.*|$)}
          prefix = $1
          paths = $2.gsub(%r{^/|/$}, '').split('/')
          library, paths = *parse_library_from_path(paths)
          return unless library
          return case prefix
                 when docs_prefix;   route_docs(library, paths)
                 when list_prefix;   route_list(library, paths)
                 when search_prefix; route_search(library, paths)
                 when static_prefix; route_static(library, paths)
                 end
        end
        nil
      end

      # Routes requests from {#docs_prefix} and calls the appropriate command
      # @param [LibraryVersion] library the library to route for
      # @param [Array] paths path components (split by '/')
      # @return (see #route)
      def route_docs(library, paths)
        return route_index if library.nil?
        case paths.first
        when "frames"
          paths.shift
          cmd = DisplayObjectCommand
        when "file"
          paths.shift
          cmd = DisplayFileCommand
        else
          cmd = DisplayObjectCommand
        end
        cmd = cmd.new(final_options(library, paths))
        cmd.call(request)
      end

      # Routes for the index of a library / multiple libraries
      # @return (see #route)
      def route_index
        if adapter.options[:single_library]
          route_docs(adapter.libraries.values.first.first, [])
        else
          LibraryIndexCommand.new(adapter.options.merge(:path => '')).call(request)
        end
      end

      # Routes requests from {#list_prefix} and calls the appropriate command
      # @param (see #route_docs)
      # @return (see #route_docs)
      def route_list(library, paths)
        return if paths.empty?
        ListCommand.new(final_options(library, paths)).call(request)
      end

      # Routes requests from {#search_prefix} and calls the appropriate command
      # @param (see #route_docs)
      # @return (see #route_docs)
      def route_search(library, paths)
        return unless paths.empty?
        SearchCommand.new(final_options(library, paths)).call(request)
      end

      def route_static(library, paths)
        StaticFileCommand.new(final_options(library, paths)).call(request)
      end

      # @group Utility Methods

      # Adds extra :library/:path option keys to the adapter options.
      # Use this method when passing options to a command.
      #
      # @param (see #route_docs)
      # @return [Hash] finalized options
      def final_options(library, paths)
        path = File.cleanpath(paths.join('/')).gsub(%r{^(\.\./)+}, '')
        adapter.options.merge(:library => library, :path => path)
      end
    end
  end
end
yard-0.9.37/lib/yard/server/static_caching.rb000066400000000000000000000033761466601756300211030ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Server
    # Implements static caching for requests.
    #
    # @see Router Router documentation for "Caching"
    module StaticCaching
      # Called by a router to return the cached object. By default, this
      # method performs disk-based caching. To perform other forms of caching,
      # implement your own +#check_static_cache+ method and mix the module into
      # the Router class.
      #
      # Note that caching does not occur here. This method simply checks for
      # the existence of cached data. To actually cache a response, see
      # {Commands::Base#cache}.
      #
      # @example Implementing In-Memory Cache Checking
      #   module MemoryCaching
      #     def check_static_cache
      #       # $memory_cache is filled by {Commands::Base#cache}
      #       cached_data = $memory_cache[request.path]
      #       if cached_data
      #         [200, {'Content-Type' => 'text/html'}, [cached_data]]
      #       else
      #         nil
      #       end
      #     end
      #   end
      #
      #   class YARD::Server::Router; include MemoryCaching; end
      # @return [Array(Numeric,Hash,Array)] the Rack-style response
      # @return [nil] if no cache is available and routing should continue
      # @see Commands::Base#cache
      def check_static_cache
        return nil unless adapter.document_root
        cache_path = File.join(adapter.document_root, request.path.sub(/\.html$/, '') + '.html')
        cache_path = cache_path.sub(%r{/\.html$}, '.html')
        if File.file?(cache_path)
          log.debug "Loading cache from disk: #{cache_path}"
          return [200, {'Content-Type' => 'text/html'}, [File.read_binary(cache_path)]]
        end
        nil
      end
    end
  end
end
yard-0.9.37/lib/yard/server/templates/000077500000000000000000000000001466601756300176005ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/000077500000000000000000000000001466601756300212245ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/fulldoc/000077500000000000000000000000001466601756300226545ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/fulldoc/html/000077500000000000000000000000001466601756300236205ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/fulldoc/html/css/000077500000000000000000000000001466601756300244105ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/fulldoc/html/css/custom.css000066400000000000000000000057501466601756300264430ustar00rootroot00000000000000#search_results h1 { margin-bottom: 0; }
#search_results p { margin-top: 0; margin-bottom: 25px; }
#search_results ul { list-style-position: inside; padding-left: 0; list-style: none; }
#search_results ul li { padding: 7px 15px; font-size: 1.1em; }

form.search {
  z-index: 8000;
  position: absolute;
  color: #fff;
  border: 1px solid #99f; width: 210px; background: #05a;
  border-radius: 4px; border-top-left-radius: 0; border-top-right-radius: 0;
}
form.search input {
  height: 25px;
  padding: 0;
  padding-left: 4px;
  margin: 4px;
  margin-right: 0;
  width: 202px;
  border: 1px solid #99f;
  border-radius: 3px;
  font-size: 1.1em;
  box-sizing: border-box;
  -webkit-appearance: none;
}

@media (max-width: 920px) {
  form.search {
    position: absolute;
    color: #fff;
    width: 100%;
    margin-top: 0;
    background: #05a;
    border-radius: 0;
    border: 0;
    margin-bottom: 10px;
    left: 0;
    top: 0;
  }
  form.search input {
    margin-top: 9px;
    margin-bottom: 11px;
    margin-left: 12px;
    padding-left: 6px;
    border: 1px solid #eaf0ff;
  }
  #menu { margin-top: 41px; }
  #search a {
    border-top-left-radius: 3px; border-top-right-radius: 3px;
    background: none;
    border: 0;
    box-shadow: none;
    margin-top: 4px;
    padding-bottom: 5px;
    color: #eaf0ff; fill: #eaf0ff;
  }
  #search a.active {
    background: #048; border: 0;
  }
}

@media (min-width: 920px) {
  form.search { right: 12px; top: 0; }
}

#menu { padding-top: 5px; }
#content h1 { margin-top: 15px; border-top: 0; }

#content.error { font-size: 1.2em; }
#content.error p tt { font-size: 1.2em; }
#content.error .note { padding: 12px; }

.signature .permalink { float: right; font-size: 0.9em; }

/* autocomplete */
.ac_results {
	padding: 0px;
	border: 1px solid black;
	width: 500px;
	overflow: hidden;
	z-index: 99999;
}

.ac_results ul {
	width: 100%;
	list-style-position: outside;
	list-style: none;
	padding: 0;
	margin: 0;
}

.ac_results li {
  cursor: pointer;
	margin: 0px;
	padding: 3px;
	display: block;
	font-family: sans-serif;
	font-size: 12px;
	line-height: 16px;
	overflow: hidden;

}

.ac_loading {
	background: white url('/images/processing.gif') right center no-repeat;
}

.ac_even {
  background: #fafafa; border: 1px dotted #fafafa; border-left-width: 0; border-right-width: 0;
}

.ac_odd {
	background: #f0f0f0; border: 1px dotted #f0f0f0; border-left-width: 0; border-right-width: 0;
}

.ac_over {
  background: #ddd; cursor: pointer; border: 1px dotted #fff; border-left-width: 0; border-right-width: 0;
}

#fade { display: none; position: absolute; top: 0px; left: 0; background: #eee; z-index: -1; width: 100%; height: 100%; border-top: 1px solid #e0e0e0; }
#processing {
  position: absolute; width: 400px; height: 200px; margin: auto; background: #fff; padding: 10px 30px; z-index: 20;
  -webkit-box-shadow: 0px 0px 20px #444; -moz-box-shadow: 0px 0px 20px #444;
  -webkit-border-radius: 4px;
  display: none;
}
#processing img { display: block; position: absolute; bottom: 30px; left: 44%; }
yard-0.9.37/lib/yard/server/templates/default/fulldoc/html/images/000077500000000000000000000000001466601756300250655ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/fulldoc/html/images/processing.gif000066400000000000000000000023431466601756300277320ustar00rootroot00000000000000GIF89aҼܸت666&&&PPPpppVVVhhhFFFHHH222!NETSCAPE2.0!
,@pHdR Ĩth8 W	e4Sib-kK'\n1|!!B
C|GvsA!
!,W@p(| @	ˡÉD
"Qzv$^QSPH$`d(qx
CKxgy
WWCA!
 ,	M "JdHb+Q\g!HTY#hp8r;>KeӉ`,I$H񌠈lÑxlv}1b6"h8`@(!
!,	YpCr\Kc
nNǁBlFzR1
"`ǸBB
!B !BvG	ur
GA!
!,V@pHt .	qhl(PRҹD˅%~]!GQf0p^9
PS} SS
t}	A;yard-0.9.37/lib/yard/server/templates/default/fulldoc/html/js/000077500000000000000000000000001466601756300242345ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/fulldoc/html/js/autocomplete.js000066400000000000000000000175031466601756300273010ustar00rootroot00000000000000/*
 * jQuery Autocomplete plugin 1.1
 *
 * Copyright (c) 2009 Jörn Zaefferer
 *
 * Dual licensed under the MIT and GPL licenses:
 *   http://www.opensource.org/licenses/mit-license.php
 *   http://www.gnu.org/licenses/gpl.html
 *
 * Revision: $Id: jquery.autocomplete.js 15 2009-08-22 10:30:27Z joern.zaefferer $
 */
eval(function(p,a,c,k,e,r){e=function(c){return(c35?String.fromCharCode(c+29):c.toString(36))};if(!''.replace(/^/,String)){while(c--)r[e(c)]=k[c]||e(c);k=[function(e){return r[e]}];e=function(){return'\\w+'};c=1};while(c--)if(k[c])p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c]);return p}(';(3($){$.2e.1u({19:3(b,d){5 c=W b=="1B";d=$.1u({},$.M.1T,{Y:c?b:P,y:c?P:b,1J:c?$.M.1T.1J:10,X:d&&!d.1D?10:48},d);d.1y=d.1y||3(a){6 a};d.1v=d.1v||d.1R;6 A.I(3(){1M $.M(A,d)})},L:3(a){6 A.11("L",a)},1k:3(a){6 A.14("1k",[a])},2b:3(){6 A.14("2b")},28:3(a){6 A.14("28",[a])},24:3(){6 A.14("24")}});$.M=3(o,r){5 t={2Y:38,2S:40,2N:46,2I:9,2E:13,2B:27,2x:3I,2v:33,2p:34,2n:8};5 u=$(o).3r("19","3o").Q(r.2Q);5 p;5 m="";5 n=$.M.3c(r);5 s=0;5 k;5 h={1F:C};5 l=$.M.32(r,o,1Z,h);5 j;$.1Y.2X&&$(o.2U).11("45.19",3(){4(j){j=C;6 C}});u.11(($.1Y.2X?"43":"42")+".19",3(a){s=1;k=a.2M;3V(a.2M){O t.2Y:a.1d();4(l.N()){l.30()}w{12(0,D)}R;O t.2S:a.1d();4(l.N()){l.2D()}w{12(0,D)}R;O t.2v:a.1d();4(l.N()){l.2C()}w{12(0,D)}R;O t.2p:a.1d();4(l.N()){l.2A()}w{12(0,D)}R;O r.17&&$.1c(r.S)==","&&t.2x:O t.2I:O t.2E:4(1Z()){a.1d();j=D;6 C}R;O t.2B:l.Z();R;3J:1P(p);p=1O(12,r.1J);R}}).2t(3(){s++}).3E(3(){s=0;4(!h.1F){2r()}}).2q(3(){4(s++>1&&!l.N()){12(0,D)}}).11("1k",3(){5 c=(1r.7>1)?1r[1]:P;3 1N(q,a){5 b;4(a&&a.7){16(5 i=0;i1){5 f=r.S.7;5 c=$(o).18().1I;5 d,1H=0;$.I(b,3(i,a){1H+=a.7;4(c<=1H){d=i;6 C}1H+=f});b[d]=v;v=b.3f(r.S)}v+=r.S}u.K(v);1l();u.14("L",[e.y,e.F]);6 D}3 12(b,c){4(k==t.2N){l.Z();6}5 a=u.K();4(!c&&a==m)6;m=a;a=1m(a);4(a.7>=r.29){u.Q(r.26);4(!r.1s)a=a.J();21(a,3a,1l)}w{1q();l.Z()}};3 15(b){4(!b)6[""];4(!r.17)6[$.1c(b)];6 $.4h(b.23(r.S),3(a){6 $.1c(b).7?$.1c(a):P})}3 1m(a){4(!r.17)6 a;5 c=15(a);4(c.7==1)6 c[0];5 b=$(o).18().1I;4(b==a.7){c=15(a)}w{c=15(a.22(a.37(b),""))}6 c[c.7-1]}3 1G(q,a){4(r.1G&&(1m(u.K()).J()==q.J())&&k!=t.2n){u.K(u.K()+a.37(1m(m).7));$(o).18(m.7,m.7+a.7)}};3 2r(){1P(p);p=1O(1l,4g)};3 1l(){5 c=l.N();l.Z();1P(p);1q();4(r.36){u.1k(3(a){4(!a){4(r.17){5 b=15(u.K()).1n(0,-1);u.K(b.3f(r.S)+(b.7?r.S:""))}w{u.K("");u.14("L",P)}}})}};3 3a(q,a){4(a&&a.7&&s){1q();l.35(a,q);1G(q,a[0].F);l.20()}w{1l()}};3 21(f,d,g){4(!r.1s)f=f.J();5 e=n.31(f);4(e&&e.7){d(f,e)}w 4((W r.Y=="1B")&&(r.Y.7>0)){5 c={4f:+1M 4e()};$.I(r.2Z,3(a,b){c[a]=W b=="3"?b():b});$.4d({4c:"4b",4a:"19"+o.49,2V:r.2V,Y:r.Y,y:$.1u({q:1m(f),47:r.X},c),44:3(a){5 b=r.1A&&r.1A(a)||1A(a);n.1i(f,b);d(f,b)}})}w{l.2T();g(f)}};3 1A(c){5 d=[];5 b=c.23("\\n");16(5 i=0;i]*)("+a.22(/([\\^\\$\\(\\)\\[\\]\\{\\}\\*\\.\\+\\?\\|\\\\])/2K,"\\\\$1")+")(?![^<>]*>)(?![^&;]+;)","2K"),"<2J>$1")},1D:D,1E:3S};$.M.3c=3(g){5 h={};5 j=0;3 1f(s,a){4(!g.1s)s=s.J();5 i=s.2H(a);4(g.1w=="3R"){i=s.J().1k("\\\\b"+a.J())}4(i==-1)6 C;6 i==0||g.1w};3 1i(q,a){4(j>g.1g){1o()}4(!h[q]){j++}h[q]=a}3 1e(){4(!g.y)6 C;5 f={},2G=0;4(!g.Y)g.1g=1;f[""]=[];16(5 i=0,2F=g.y.7;i<2F;i++){5 c=g.y[i];c=(W c=="1B")?[c]:c;5 d=g.1v(c,i+1,g.y.7);4(d===C)1V;5 e=d.3Q(0).J();4(!f[e])f[e]=[];5 b={F:d,y:c,L:g.1z&&g.1z(c)||d};f[e].1U(b);4(2G++0){5 c=h[k];$.I(c,3(i,x){4(1f(x.F,q)){a.1U(x)}})}}6 a}w 4(h[q]){6 h[q]}w 4(g.1f){16(5 i=q.7-1;i>=g.29;i--){5 c=h[q.3O(0,i)];4(c){5 a=[];$.I(c,3(i,x){4(1f(x.F,q)){a[a.7]=x}});6 a}}}6 P}}};$.M.32=3(e,g,f,k){5 h={H:"3N"};5 j,z=-1,y,1t="",1S=D,G,B;3 2y(){4(!1S)6;G=$("<3M/>").Z().Q(e.2P).T("3L","3K").1Q(1K.2w);B=$("<3H/>").1Q(G).3G(3(a){4(U(a).2u&&U(a).2u.3F()==\'2s\'){z=$("1L",B).1h(h.H).3D(U(a));$(U(a)).Q(h.H)}}).2q(3(a){$(U(a)).Q(h.H);f();g.2t();6 C}).3C(3(){k.1F=D}).3B(3(){k.1F=C});4(e.E>0)G.T("E",e.E);1S=C}3 U(a){5 b=a.U;3A(b&&b.3z!="2s")b=b.3y;4(!b)6[];6 b}3 V(b){j.1n(z,z+1).1h(h.H);2o(b);5 a=j.1n(z,z+1).Q(h.H);4(e.1D){5 c=0;j.1n(0,z).I(3(){c+=A.1a});4((c+a[0].1a-B.1b())>B[0].3x){B.1b(c+a[0].1a-B.3w())}w 4(c=j.1j()){z=0}}3 2m(a){6 e.X&&e.X").3v(e.1y(a,1t)).Q(i%2==0?"3u":"3P").1Q(B)[0];$.y(c,"2k",y[i])}j=B.3t("1L");4(e.1X){j.1n(0,1).Q(h.H);z=0}4($.2e.2W)B.2W()}6{35:3(d,q){2y();y=d;1t=q;2l()},2D:3(){V(1)},30:3(){V(-1)},2C:3(){4(z!=0&&z-8<0){V(-z)}w{V(-8)}},2A:3(){4(z!=j.1j()-1&&z+8>j.1j()){V(j.1j()-1-z)}w{V(8)}},Z:3(){G&&G.Z();j&&j.1h(h.H);z=-1},N:3(){6 G&&G.3s(":N")},3q:3(){6 A.N()&&(j.2j("."+h.H)[0]||e.1X&&j[0])},20:3(){5 a=$(g).3p();G.T({E:W e.E=="1B"||e.E>0?e.E:$(g).E(),2i:a.2i+g.1a,1W:a.1W}).20();4(e.1D){B.1b(0);B.T({2L:e.1E,3n:\'3X\'});4($.1Y.3m&&W 1K.2w.3l.2L==="1x"){5 c=0;j.I(3(){c+=A.1a});5 b=c>e.1E;B.T(\'3k\',b?e.1E:c);4(!b){j.E(B.E()-2R(j.T("2O-1W"))-2R(j.T("2O-3j")))}}}},2g:3(){5 a=j&&j.2j("."+h.H).1h(h.H);6 a&&a.7&&$.y(a[0],"2k")},2T:3(){B&&B.2z()},1p:3(){G&&G.3i()}}};$.2e.18=3(b,f){4(b!==1x){6 A.I(3(){4(A.2d){5 a=A.2d();4(f===1x||b==f){a.4n("2c",b);a.3h()}w{a.4m(D);a.4l("2c",b);a.4k("2c",f);a.3h()}}w 4(A.3g){A.3g(b,f)}w 4(A.1C){A.1C=b;A.3e=f}})}5 c=A[0];4(c.2d){5 e=1K.18.4j(),3d=c.F,2a="<->",2f=e.3b.7;e.3b=2a;5 d=c.F.2H(2a);c.F=3d;A.18(d,d+2f);6{1I:d,39:d+2f}}w 4(c.1C!==1x){6{1I:c.1C,39:c.3e}}}})(4i);',62,272,'|||function|if|var|return|length|||||||||||||||||||||||||else||data|active|this|list|false|true|width|value|element|ACTIVE|each|toLowerCase|val|result|Autocompleter|visible|case|null|addClass|break|multipleSeparator|css|target|moveSelect|typeof|max|url|hide||bind|onChange||trigger|trimWords|for|multiple|selection|autocomplete|offsetHeight|scrollTop|trim|preventDefault|populate|matchSubset|cacheLength|removeClass|add|size|search|hideResultsNow|lastWord|slice|flush|unbind|stopLoading|arguments|matchCase|term|extend|formatMatch|matchContains|undefined|highlight|formatResult|parse|string|selectionStart|scroll|scrollHeight|mouseDownOnSelect|autoFill|progress|start|delay|document|li|new|findValueCallback|setTimeout|clearTimeout|appendTo|formatItem|needsInit|defaults|push|continue|left|selectFirst|browser|selectCurrent|show|request|replace|split|unautocomplete||loadingClass||setOptions|minChars|teststring|flushCache|character|createTextRange|fn|textLength|selected|in|top|filter|ac_data|fillList|limitNumberOfItems|BACKSPACE|movePosition|PAGEDOWN|click|hideResults|LI|focus|nodeName|PAGEUP|body|COMMA|init|empty|pageDown|ESC|pageUp|next|RETURN|ol|nullData|indexOf|TAB|strong|gi|maxHeight|keyCode|DEL|padding|resultsClass|inputClass|parseInt|DOWN|emptyList|form|dataType|bgiframe|opera|UP|extraParams|prev|load|Select|||display|mustMatch|substring||end|receiveData|text|Cache|orig|selectionEnd|join|setSelectionRange|select|remove|right|height|style|msie|overflow|off|offset|current|attr|is|find|ac_even|html|innerHeight|clientHeight|parentNode|tagName|while|mouseup|mousedown|index|blur|toUpperCase|mouseover|ul|188|default|absolute|position|div|ac_over|substr|ac_odd|charAt|word|180|RegExp|100|switch|400|auto|ac_loading|ac_results||ac_input|keydown|keypress|success|submit||limit|150|name|port|abort|mode|ajax|Date|timestamp|200|map|jQuery|createRange|moveEnd|moveStart|collapse|move'.split('|'),0,{}))yard-0.9.37/lib/yard/server/templates/default/layout/000077500000000000000000000000001466601756300225415ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/layout/html/000077500000000000000000000000001466601756300235055ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/layout/html/breadcrumb.erb000066400000000000000000000034131466601756300263060ustar00rootroot00000000000000
    
  

    



yard-0.9.37/lib/yard/server/templates/default/layout/html/script_setup.erb000066400000000000000000000004751466601756300267310ustar00rootroot00000000000000
yard-0.9.37/lib/yard/server/templates/default/layout/html/setup.rb000066400000000000000000000002051466601756300251670ustar00rootroot00000000000000# frozen_string_literal: true
def javascripts
  super + %w(js/autocomplete.js)
end

def stylesheets
  super + %w(css/custom.css)
end
yard-0.9.37/lib/yard/server/templates/default/method_details/000077500000000000000000000000001466601756300242115ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/method_details/html/000077500000000000000000000000001466601756300251555ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/default/method_details/html/permalink.erb000066400000000000000000000003451466601756300276330ustar00rootroot00000000000000
yard-0.9.37/lib/yard/server/templates/default/method_details/html/setup.rb000066400000000000000000000001551466601756300266430ustar00rootroot00000000000000# frozen_string_literal: true
def init
  super
  sections.place(:permalink).after_any(:method_signature)
end
yard-0.9.37/lib/yard/server/templates/doc_server/000077500000000000000000000000001466601756300217335ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/doc_server/library_list/000077500000000000000000000000001466601756300244325ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/doc_server/library_list/html/000077500000000000000000000000001466601756300253765ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/doc_server/library_list/html/headers.erb000066400000000000000000000011401466601756300274770ustar00rootroot00000000000000
YARD Documentation Server <%= YARD::VERSION %> - Library Listing



yard-0.9.37/lib/yard/server/templates/doc_server/library_list/html/library_list.erb000066400000000000000000000005441466601756300305720ustar00rootroot00000000000000

  
    <%= erb(:headers) %>
  
  
    
    
      
    
        <%= yieldall %>
      
    
    
    
  

yard-0.9.37/lib/yard/server/templates/doc_server/library_list/html/listing.erb000066400000000000000000000011741466601756300275440ustar00rootroot00000000000000
      
  <% @libraries.sort_by {|name, y| name.downcase }.each do |name, library_versions| %>
  
    • 
    <% library_versions = library_versions.dup %>
    <% first_lib = library_versions.pop %>
    <%= name %>
    <% if first_lib.version %>
      (<%= first_lib.version %><% if library_versions.size > 0 %>,
        <%= library_versions.reverse.map {|lib| "#{lib.version}" }.join(', ') %><% end %>)
    <% end %>
  
      • 
  <% end %>

    
yard-0.9.37/lib/yard/server/templates/doc_server/library_list/html/setup.rb000066400000000000000000000002031466601756300270560ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/layout/html')

def init
  sections :library_list, [:title, :listing, :footer]
end
yard-0.9.37/lib/yard/server/templates/doc_server/library_list/html/title.erb000066400000000000000000000001211466601756300272030ustar00rootroot00000000000000
    YARD Documentation Server <%= YARD::VERSION %>
    

    Library Listing
    
yard-0.9.37/lib/yard/server/templates/doc_server/processing/000077500000000000000000000000001466601756300241075ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/doc_server/processing/html/000077500000000000000000000000001466601756300250535ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/doc_server/processing/html/processing.erb000066400000000000000000000047111466601756300277240ustar00rootroot00000000000000

  
    
    
    
    
    
    
    Processing <%= @library.to_s(false) %>
  
  
    
    
    
    
    
      
    Processing <%= @library.name %>
    
      
    
        <%= @library.name %> <% if @library.version %>(<%= @library.version %>)<% end %> is being processed.
        You'll be redirected when the pages are built, it shouldn't take much longer.
      
    
      
    
    
  

yard-0.9.37/lib/yard/server/templates/doc_server/processing/html/setup.rb000066400000000000000000000001021466601756300265310ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :processing
end
yard-0.9.37/lib/yard/server/templates/doc_server/search/000077500000000000000000000000001466601756300232005ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/doc_server/search/html/000077500000000000000000000000001466601756300241445ustar00rootroot00000000000000yard-0.9.37/lib/yard/server/templates/doc_server/search/html/search.erb000066400000000000000000000013031466601756300261000ustar00rootroot00000000000000
    
  
    Search Results (for '<%= h @query %>')
    
  
    Showing <%= @visible_results.size %> of <%= @results.size %> results
    
  
      
    <% n = 1 %>
    <% @visible_results.each do |result| %>
      <% name = result.type == :method ? result.name(true).to_s : result.name.to_s %>
      <% path = name.gsub(/(#{Regexp.quote @query})/i, '\1') %>
      
    • 
        <%= path %>
          <% if !result.namespace.root? %>
          (<%= result.namespace.path %>)
          <% end %>
      
      • 
      <% n = n == 2 ? 1 : 2 %>
    <% end %>
  
    

    
yard-0.9.37/lib/yard/server/templates/doc_server/search/html/setup.rb000066400000000000000000000003061466601756300256300ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :search, [T('../default/layout')]
end

def search
  options.breadcrumb_title = h("Search for '#{@query}'")
  yieldall :contents => erb(:search)
end
yard-0.9.37/lib/yard/server/webrick_adapter.rb000066400000000000000000000025331466601756300212600ustar00rootroot00000000000000# frozen_string_literal: true
require 'webrick'

module YARD
  module Server
    # The main adapter to initialize a WEBrick server.
    class WebrickAdapter < Adapter
      # Initializes a WEBrick server. If {Adapter#server_options} contains a
      # +:daemonize+ key set to true, the server will be daemonized.
      def start
        server_options[:ServerType] = WEBrick::Daemon if server_options[:daemonize]
        server = WEBrick::HTTPServer.new(server_options)
        server.mount('/', WebrickServlet, self)
        trap("INT") { server.shutdown }
        server.start
      end
    end

    # The main WEBrick servlet implementation, accepting only GET requests.
    class WebrickServlet < WEBrick::HTTPServlet::AbstractServlet
      attr_accessor :adapter

      def initialize(server, adapter)
        super
        self.adapter = adapter
      end

      # @private
      def do_GET(request, response) # rubocop:disable Style/MethodName
        status, headers, body = *adapter.router.call(request)
        response.status = status
        response.body = body.is_a?(Array) ? body[0] : body
        headers.each do |key, value|
          response[key] = value
        end
      end
    end
  end
end

# @private
class WEBrick::HTTPRequest
  attr_accessor :version_supplied
  def xhr?; (self['X-Requested-With'] || "").casecmp('xmlhttprequest') == 0 end
end
yard-0.9.37/lib/yard/tags/000077500000000000000000000000001466601756300152325ustar00rootroot00000000000000yard-0.9.37/lib/yard/tags/default_factory.rb000066400000000000000000000162101466601756300207320ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    class DefaultFactory
      TYPELIST_OPENING_CHARS = '[({<'
      TYPELIST_CLOSING_CHARS = '>})]'

      # Parses tag text and creates a new tag with descriptive text
      #
      # @param tag_name        the name of the tag to parse
      # @param [String] text   the raw tag text
      # @return [Tag]          a tag object with the tag_name and text values filled
      def parse_tag(tag_name, text)
        Tag.new(tag_name, text.strip)
      end

      # Parses tag text and creates a new tag with a key name and descriptive text
      #
      # @param tag_name        the name of the tag to parse
      # @param [String] text   the raw tag text
      # @return [Tag]          a tag object with the tag_name, name and text values filled
      def parse_tag_with_name(tag_name, text)
        name, text = *extract_name_from_text(text)
        Tag.new(tag_name, text, nil, name)
      end

      # Parses tag text and creates a new tag with formally declared types and
      # descriptive text
      #
      # @param tag_name        the name of the tag to parse
      # @param [String] text   the raw tag text
      # @return [Tag]          a tag object with the tag_name, types and text values filled
      def parse_tag_with_types(tag_name, text)
        name, types, text = *extract_types_and_name_from_text(text)
        raise TagFormatError, "cannot specify a name before type list for '@#{tag_name}'" if name
        Tag.new(tag_name, text, types)
      end

      # Parses tag text and creates a new tag with formally declared types, a key
      # name and descriptive text
      #
      # @param tag_name        the name of the tag to parse
      # @param [String] text   the raw tag text
      # @return [Tag]          a tag object with the tag_name, name, types and text values filled
      def parse_tag_with_types_and_name(tag_name, text)
        name, types, text = *extract_types_and_name_from_text(text)
        name, text = *extract_name_from_text(text) unless name
        Tag.new(tag_name, text, types, name)
      end

      # Parses tag text and creates a new tag with formally declared types, a title
      # on the first line and descriptive text
      #
      # @param tag_name        the name of the tag to parse
      # @param [String] text   the raw tag text
      # @return [Tag]          a tag object with the tag_name, name, types and text values filled
      def parse_tag_with_types_and_title(tag_name, text)
        name, types, text = *extract_types_and_name_from_text_unstripped(text)
        if name
          title = name
          desc = text
        else
          title, desc = *extract_title_and_desc_from_text(text)
        end
        Tag.new(tag_name, desc, types, title)
      rescue TagFormatError
        Tag.new(tag_name, '', types, nil)
      end

      def parse_tag_with_title_and_text(tag_name, text)
        title, desc = *extract_title_and_desc_from_text(text)
        Tag.new(tag_name, desc, nil, title)
      end

      def parse_tag_with_types_name_and_default(tag_name, text)
        # Can't allow () in a default tag, otherwise the grammar is too ambiguous when types is omitted.
        open = TYPELIST_OPENING_CHARS.delete('(')
        close = TYPELIST_CLOSING_CHARS.delete(')')
        name, types, text = *extract_types_and_name_from_text(text, open, close)
        name, text = *extract_name_from_text(text) unless name
        if text && text.start_with?('(')
          _, default, text = *extract_types_and_name_from_text(text, '(', ')')
          DefaultTag.new(tag_name, text, types, name, default)
        else
          DefaultTag.new(tag_name, text, types, name, nil)
        end
      end

      def parse_tag_with_options(tag_name, text)
        name, text = *extract_name_from_text(text)
        OptionTag.new(tag_name, name, parse_tag_with_types_name_and_default(tag_name, text))
      end

      private

      # Extracts the name from raw tag text returning the name and remaining value
      #
      # @param [String] text the raw tag text
      # @return [Array] an array holding the name as the first element and the
      #                 value as the second element
      def extract_name_from_text(text)
        text.strip.split(/\s+/, 2)
      end

      def extract_title_and_desc_from_text(text)
        raise TagFormatError if text.nil? || text.empty?
        title = nil
        desc = nil
        if text =~ /\A[ \t]\n/
          desc = text
        else
          text = text.split(/\r?\n/)
          title = text.shift.squeeze(' ').strip
          desc = text.join("\n")
        end
        [title, desc]
      end

      # Parses a [], <>, {} or () block at the beginning of a line of text
      # into a list of comma delimited values.
      #
      # @example
      #   obj.parse_types('[String, Array, nil]') # => [nil, ['String', 'Array', 'nil'], ""]
      #   obj.parse_types('b A string') # => ['b', ['String'], 'A string']
      #
      # @return [Array(String, Array, String)] the text before the type
      #   list (or nil), followed by the type list parsed into an array of
      #   strings, followed by the text following the type list.
      def extract_types_and_name_from_text(text, opening_types = TYPELIST_OPENING_CHARS, closing_types = TYPELIST_CLOSING_CHARS)
        before, list, text = *extract_types_and_name_from_text_unstripped(text, opening_types, closing_types)
        if list.nil?
          [nil, nil, text.strip]
        else
          [before ? before.strip : nil, list.map(&:strip), text.strip]
        end
      end

      def extract_types_and_name_from_text_unstripped(text, opening_types = TYPELIST_OPENING_CHARS, closing_types = TYPELIST_CLOSING_CHARS)
        e = 0
        before = String.new("")
        list = [String.new("")]
        level = 0
        seen_space = false
        i = 0
        last_seen = ''
        text ||= ''
        while i < text.length
          c = text[i, 1]

          if (c == '"' || c == "'") && text[i..-1] =~ /#{c}.+?#{c}/
            list.last << $&
            i += $&.length
            next
          end

          if level > 0 && c == '#' && text[i + 1..-1] =~ CodeObjects::METHODNAMEMATCH
            list.last << c + $&
            i += $&.length + 1
            next
          elsif opening_types.include?(c)
            list.last << c if level > 0
            level += 1
          elsif closing_types.include?(c)
            level -= 1 unless last_seen == '=' && c == '>'
            break e = i if level == 0
            list.last << c
          elsif c == ',' && level == 1
            list.push String.new("")
          elsif c =~ /\S/ && level == 0
            break e = i if seen_space && list == ['']
            before << c
          elsif c =~ /[ \t]/ && level == 0 && !before.empty?
            seen_space = true
          elsif level >= 1
            list.last << c
          elsif level == 0 && c == "\n"
            break e = i
          end
          last_seen = c
          i += 1
        end

        before = before.empty? ? nil : before
        if list.size == 1 && list.first == ''
          [nil, nil, text]
        else
          [before, list, text[(e + 1)..-1]]
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/tags/default_tag.rb000066400000000000000000000004421466601756300200360ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    class DefaultTag < Tag
      attr_reader :defaults

      def initialize(tag_name, text, types = nil, name = nil, defaults = nil)
        super(tag_name, text, types, name)
        @defaults = defaults
      end
    end
  end
end
yard-0.9.37/lib/yard/tags/directives.rb000066400000000000000000000544131466601756300177270ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module Tags
    # The base directive class. Subclass this class to create a custom
    # directive, registering it with {Library.define_directive}. Directive
    # classes are executed via the {#call} method, which perform all directive
    # processing on the object.
    #
    # If processing occurs within a handler, the {#handler} attribute is
    # available to access more information about parsing context and state.
    # Handlers are only available when parsing from {Parser::SourceParser},
    # not when parsing directly from {DocstringParser}. If the docstring is
    # attached to an object declaration, {#object} will be set and available
    # to modify the generated code object directly. Note that both of these
    # attributes may be nil, and directives should test their existence
    # before attempting to use them.
    #
    # @abstract Subclasses should implement {#call}.
    # @see Library.define_directive
    # @since 0.8.0
    class Directive
      # @return [Tag] the meta-data tag containing data input to the directive
      attr_accessor :tag

      # Set this field to replace the directive definition inside of a docstring
      # with arbitrary text. For instance, the {MacroDirective} uses this field
      # to expand its macro data in place of the call to a +@!macro+.
      #
      # @return [String] the text to expand in the original docstring in place
      #   of this directive definition.
      # @return [nil] if no expansion should take place for this directive
      attr_accessor :expanded_text

      # @return [DocstringParser] the parser that is parsing all tag
      #   information out of the docstring
      attr_accessor :parser

      # @!attribute [r] object
      # @return [CodeObjects::Base, nil] the object the parent docstring is
      #   attached to. May be nil.
      def object; parser.object end

      # @!attribute [r] handler
      # @return [Handlers::Base, nil] the handler object the docstring parser
      #   might be attached to. May be nil. Only available when parsing
      #   through {Parser::SourceParser}.
      def handler; parser.handler end

      # @!endgroup

      # @param [Tag] tag the meta-data tag containing all input to the docstring
      # @param [DocstringParser] parser the docstring parser object
      def initialize(tag, parser)
        self.tag = tag
        self.parser = parser
        self.expanded_text = nil
      end

      # @!group Parser callbacks

      # Called when processing the directive. Subclasses should implement
      # this method to perform all functionality of the directive.
      #
      # @abstract implement this method to perform all data processing for
      #   the directive.
      # @return [void]
      def call; raise NotImplementedError end

      # Called after parsing all directives and tags in the docstring. Used
      # to perform any cleanup after all directives perform their main task.
      # @return [void]
      def after_parse; end

      protected :parser

      protected

      def inside_directive?
        return true if parser.state.inside_directive
        parser.directives.any? { |d| d.is_a?(MethodDirective) && d.tag.text.empty? }
      end
    end

    # Ends a group listing definition. Group definition automatically end
    # when class or module blocks are closed, and defining a new group overrides
    # the last group definition, but occasionally you need to end the current
    # group to return to the default listing. Use {tag:!group} to begin a
    # group listing.
    #
    # @example
    #   class Controller
    #     # @!group Callbacks
    #
    #     def before_filter; end
    #     def after_filter; end
    #
    #     # @!endgroup
    #
    #     def index; end
    #   end
    # @see tag:!group
    # @since 0.6.0
    class EndGroupDirective < Directive
      def call
        return unless handler
        handler.extra_state.group = nil
      end
    end

    # Defines a group listing. All methods (and attributes) seen after this
    # directive are placed into a group with the given description as the
    # group name. The group listing is used by templates to organize methods
    # and attributes into respective logical groups. To end a group listing
    # use {tag:!endgroup}.
    #
    # @note A group definition only applies to the scope it is defined in.
    #   If a new class or module is opened after the directive, this directive
    #   will not apply to methods in that class or module.
    # @example
    #   # @!group Callbacks
    #
    #   def before_filter; end
    #   def after_filter; end
    # @see tag:!endgroup
    # @since 0.6.0
    class GroupDirective < Directive
      def call
        return unless handler
        handler.extra_state.group = tag.text
      end
    end

    # Defines a block of text to be expanded whenever the macro is called by name
    # in subsequent docstrings. The macro data can be any arbitrary text data, be
    # it regular documentation, meta-data tags or directives.
    #
    # == Defining a Macro
    #
    # A macro must first be defined in order to be used. Note that a macro is also
    # expanded upon definition if it defined on an object (the docstring of a
    # method, class, module or constant object as opposed to a free standing
    # comment). To define a macro, use the "new" or "attach" identifier in the
    # types specifier list. A macro will also automatically be created if an
    # indented macro data block is given, so the keywords are not strictly needed.
    #
    # === Anonymous Macros
    #
    # In addition to standard named macros, macros can be defined anonymously if
    # no name is given. In this case, they can not be re-used in future docstrings,
    # but they will expand in the first definition. This is useful when needing
    # to take advantage of the macro expansion variables (described below).
    #
    # == Using a Macro
    #
    # To re-use a macro in another docstring after it is defined, simply use
    # @!macro the_name with no indented block of macro data. The resulting
    # data will be expanded in place.
    #
    # == Attaching a Macro to a DSL Method
    #
    # Macros can be defined to auto-expand on DSL-style class method calls. To
    # define a macro to be auto expanded in this way, use the "attach" keyword
    # in the type specifier list ("new" is implied).
    #
    # Attached macros can also be attached directly on the class method declaration
    # that provides the DSL method to its subclasses. The syntax in either case
    # is the same.
    #
    # == Macro Expansion Variables
    #
    # In the case of using macros on DSL-style method calls, a number of expansion
    # variables can be used for interpolation inside of the macro data. The variables,
    # similar in syntax to Ruby's global variables, are as follows:
    #
    # * $0 - the method name being called
    # * $1, $2, $3, ... - the Nth argument in the method call
    # * $& - the full source line
    #
    # The following example shows what the expansion variables might hold for a given
    # DSL method call:
    #
    #   property :foo, :a, :b, :c, String
    #   # $0 => "property"
    #   # $1 => "foo"
    #   # $2 => "a"
    #   # $& => "property :foo, :a, :b, :c, String"
    #
    # === Ranges
    #
    # Ranges are also acceptable with the syntax ${N-M}. Negative values
    # on either N or M are valid, and refer to indexes from the end of the list.
    # Consider a DSL method that creates a method using the first argument with
    # argument names following, ending with the return type of the method. This
    # could be documented as:
    #
    #     # @!macro dsl_method
    #     #   @!method $1(${2--2})
    #     #   @return [${-1}] the return value of $0
    #     create_method_with_args :foo, :a, :b, :c, String
    #
    # As described, the method is using the signature foo(a, b, c) and the return
    # type from the last argument, +String+. When using ranges, tokens are joined
    # with commas. Note that this includes using $0:
    #
    #     !!!plain
    #     $0-1 # => Interpolates to "create_method_with_args, foo"
    #
    # If you want to separate them with spaces, use $1 $2 $3 $4 .... Note that
    # if the token cannot be expanded, it will return the empty string (not an error),
    # so it would be safe to list $1 $2 ... $10, for example.
    #
    # === Escaping Interpolation
    #
    # Interpolation can be escaped by prefixing the +$+ with +\\\+, like so:
    #
    #     # @!macro foo
    #     #   I have \$2.00 USD.
    #
    # @example Defining a simple macro
    #   # @!macro [new] returnself
    #   #   @return [self] returns itself
    # @example Using a simple macro in multiple docstrings
    #   # Documentation for map
    #   # ...
    #   # @macro returnself
    #   def map; end
    #
    #   # Documentation for filter
    #   # ...
    #   # @macro returnself
    #   def filter; end
    # @example Attaching a macro to a class method (for DSL usage)
    #     class Resource
    #       # Defines a new property
    #       # @param [String] name the property name
    #       # @param [Class] type the property's type
    #       # @!macro [attach] property
    #       #   @return [$2] the $1 property
    #       def self.property(name, type) end
    #     end
    #
    #     class Post < Resource
    #       property :title, String
    #       property :view_count, Integer
    #     end
    # @example Attaching a macro directly to a DSL method
    #     class Post < Resource
    #       # @!macro [attach] property
    #       #   @return [$2] the $1 property
    #       property :title, String
    #
    #       # Macro will expand on this definition too
    #       property :view_count, Integer
    #     end
    # @since 0.7.0
    class MacroDirective < Directive
      def call
        raise TagFormatError if tag.name.nil? && tag.text.to_s.empty?
        macro_data = find_or_create
        unless macro_data
          warn
          return
        end

        self.expanded_text = expand(macro_data)
      end

      private

      def new?
        (tag.types && tag.types.include?('new')) ||
          (tag.text && !tag.text.strip.empty?)
      end

      def attach?
        new? && # must have data or there is nothing to attach
          class_method? || # always attach to class methods
          (tag.types && tag.types.include?('attach'))
      end

      def class_method?
        object && object.is_a?(CodeObjects::MethodObject) &&
          object.scope == :class
      end

      def anonymous?
        tag.name.nil? || tag.name.empty?
      end

      def expand(macro_data)
        return if attach? && class_method?
        return if !anonymous? && new? &&
                  (!handler || handler.statement.source.empty?)
        call_params = []
        caller_method = nil
        full_source = ''
        if handler
          call_params = handler.call_params
          caller_method = handler.caller_method
          full_source = handler.statement.source
        end
        all_params = ([caller_method] + call_params).compact
        CodeObjects::MacroObject.expand(macro_data, all_params, full_source)
      end

      def find_or_create
        if new? || attach?
          if handler && attach?
            if object && object.is_a?(CodeObjects::NamespaceObject)
              log.warn "Attaching macros to non-methods is unsupported, ignoring: " \
                       "#{object.path} (#{handler.parser.file}:#{handler.statement.line})"
              obj = nil
            else
              obj = object ? object :
                P("#{handler.namespace}.#{handler.caller_method}")
            end
          else
            obj = nil
          end

          return tag.text || "" if anonymous? # anonymous macro
          macro = CodeObjects::MacroObject.create(tag.name, tag.text, obj)
        else
          macro = CodeObjects::MacroObject.find(tag.name)
        end

        macro ? macro.macro_data : nil
      end

      def warn
        if object && handler
          log.warn "Invalid/missing macro name for " \
                   "#{object.path} (#{handler.parser.file}:#{handler.statement.line})"
        end
      end
    end

    # Defines a method object with a given method signature, using indented
    # block data as the method's docstring. The signature is similar to the
    # {tag:overload} tag. The comment containing this directive does not need
    # to be attached to any source, but if it is, that source code will be
    # used as the method's source.
    #
    # To define an attribute method, see {tag:!attribute}
    #
    # @note This directive should only be used if there is no explicit
    #   declaration for the method in any source files (i.e., the method
    #   is declared dynamically via meta-programming). In all other cases, add
    #   documentation to the method definition itself.
    # @note For backwards compatibility support, you do not need to indent
    #   the method's docstring text. If a +@!method+ directive is seen with
    #   no indented block, the entire docstring is used as the new method's
    #   docstring text.
    # @example Defining a simple method
    #   # @!method quit(username, message = "Quit")
    #   #   Sends a quit message to the server for a +username+.
    #   #   @param [String] username the username to quit
    #   #   @param [String] message the quit message
    #   quit_message_method
    # @example Attaching multiple methods to the same source
    #   # @!method method1
    #   # @!method method2
    #   create_methods :method1, :method2
    # @see tag:!attribute
    # @since 0.7.0
    class MethodDirective < Directive
      SCOPE_MATCH = /\A\s*self\s*\.\s*/

      def call; end

      def after_parse
        return unless handler
        use_indented_text
        create_object
      end

      protected

      def method_name
        sig = sanitized_tag_signature
        if sig && sig =~ /^#{CodeObjects::METHODNAMEMATCH}(\s|\(|$)/
          sig[/\A\s*([^\(; \t]+)/, 1]
        else
          handler.call_params.first
        end
      end

      def method_signature
        "def #{sanitized_tag_signature || method_name}"
      end

      def sanitized_tag_signature
        if tag.name && tag.name =~ SCOPE_MATCH
          parser.state.scope = :class
          $'
        else
          tag.name
        end
      end

      def use_indented_text
        return if tag.text.empty?
        handler = parser.handler
        object = parser.object
        self.parser = parser.class.new(parser.library)
        parser.state.inside_directive = true
        parser.parse(tag.text, object, handler)
        parser.state.inside_directive = false
      end

      def create_object
        name = method_name
        scope = parser.state.scope || handler.scope
        visibility = parser.state.visibility || handler.visibility
        ns = CodeObjects::NamespaceObject === object ? object : handler.namespace
        obj = CodeObjects::MethodObject.new(ns, name, scope)
        handler.register_file_info(obj)
        handler.register_source(obj)
        handler.register_visibility(obj, visibility)
        handler.register_group(obj)
        obj.signature = method_signature
        obj.parameters = OverloadTag.new(:overload, method_signature).parameters
        obj.docstring = Docstring.new!(parser.text, parser.tags, obj,
          parser.raw_text, parser.reference)
        handler.register_module_function(obj)
        old_obj = parser.object
        parser.object = obj
        parser.post_process
        parser.object = old_obj
        obj
      end
    end

    # Defines an attribute with a given name, using indented block data as the
    # attribute's docstring. If the type specifier is supplied with "r", "w", or
    # "rw", the attribute is made readonly, writeonly or readwrite respectively.
    # A readwrite attribute is the default, if no type is specified. The comment
    # containing this directive does not need to be attached to any source, but
    # if it is, that source code will be used as the method's source.
    #
    # To define a regular method, see {tag:!method}
    #
    # @note This directive should only be used if there is no explicit +attr_*+
    #   declaration for the attribute in any source files (i.e., the attribute
    #   is declared dynamically via meta-programming). In all other cases, add
    #   documentation to the attribute declaration itself.
    # @note For backwards compatibility support, you do not need to indent
    #   the attribute's docstring text. If an +@!attribute+ directive is seen with
    #   no indented block, the entire docstring is used as the new attribute's
    #   docstring text.
    # @example Defining a simple readonly attribute
    #   # @!attribute [r] count
    #   #   @return [Fixnum] the size of the list
    # @example Defining a simple readwrite attribute
    #   # @!attribute name
    #   #   @return [String] the name of the user
    # @see tag:!method
    # @since 0.7.0
    class AttributeDirective < MethodDirective
      def after_parse
        return unless handler
        use_indented_text
        create_attribute_data(create_object)
      end

      protected

      def method_name
        name = sanitized_tag_signature || handler.call_params.first
        name += '=' unless readable?
        name
      end

      def method_signature
        if readable?
          "def #{method_name}"
        else
          "def #{method_name}(value)"
        end
      end

      private

      def create_attribute_data(object)
        return unless object
        clean_name = object.name.to_s.sub(/=$/, '')
        attrs = object.namespace.attributes[object.scope]
        attrs[clean_name] ||= SymbolHash[:read => nil, :write => nil]
        attrs[clean_name][:read] = object if readable?
        if writable?
          if object.name.to_s[-1, 1] == '='
            writer = object
            writer.parameters = [['value', nil]]
          else
            writer = CodeObjects::MethodObject.new(object.namespace,
              object.name.to_s + '=', object.scope)
            writer.signature = "def #{object.name}=(value)"
            writer.visibility = object.visibility
            writer.dynamic = object.dynamic
            writer.source = object.source
            writer.group = object.group
            writer.parameters = [['value', nil]]
            writer.docstring = object.base_docstring
            handler.register_file_info(writer)
          end
          attrs[clean_name][:write] = writer
        end
      end

      def writable?
        !tag.types || tag.types.join.include?('w')
      end

      def readable?
        !tag.types || tag.types.join =~ /(?!w)r/
      end
    end

    # Parses a block of code as if it were present in the source file at that
    # location. This directive is useful if a class has dynamic meta-programmed
    # behaviour that cannot be recognized by YARD.
    #
    # You can specify the language of the code block using the types
    # specification list. By default, the code language is "ruby".
    #
    # @example Documenting dynamic module inclusion
    #   class User
    #     # includes "UserMixin" and extends "UserMixin::ClassMethods"
    #     # using the UserMixin.included callback.
    #     # @!parse include UserMixin
    #     # @!parse extend UserMixin::ClassMethods
    #   end
    # @example Declaring a method as an attribute
    #   # This should really be an attribute
    #   # @!parse attr_reader :foo
    #   def object; @parent.object end
    # @example Parsing C code
    #   # @!parse [c]
    #   #   void Init_Foo() {
    #   #     rb_define_method(rb_cFoo, "method", method, 0);
    #   #   }
    # @since 0.8.0
    class ParseDirective < Directive
      def call
        lang = tag.types ? tag.types.first.to_sym :
          (handler ? handler.parser.parser_type : :ruby)
        if handler && lang == handler.parser.parser_type
          pclass = Parser::SourceParser.parser_types[handler.parser.parser_type]
          pobj = pclass.new(tag.text, handler.parser.file)
          pobj.parse
          handler.parser.process(pobj.enumerator)
        else # initialize a new parse chain
          src_parser = Parser::SourceParser.new(lang, handler ? handler.globals : nil)
          src_parser.file = handler.parser.file if handler
          src_parser.parse(StringIO.new(tag.text))
        end
      end
    end

    # Modifies the current parsing scope (class or instance). If this
    # directive is defined on a docstring attached to an object definition,
    # it is applied only to that object. Otherwise, it applies the scope
    # to all future objects in the namespace.
    #
    # @example Modifying the scope of a DSL method
    #   # @!scope class
    #   cattr_accessor :subclasses
    # @example Modifying the scope of a set of methods
    #   # @!scope class
    #
    #   # Documentation for method1
    #   def method1; end
    #
    #   # Documentation for method2
    #   def method2; end
    # @since 0.7.0
    class ScopeDirective < Directive
      def call
        if %w(class instance module).include?(tag.text)
          if object.is_a?(CodeObjects::MethodObject)
            object.scope = tag.text.to_sym
          elsif handler && !inside_directive?
            handler.scope = tag.text.to_sym
          else
            parser.state.scope = tag.text.to_sym
          end
        end
      end
    end

    # Modifies the current parsing visibility (public, protected, or private).
    # If this directive is defined on a docstring attached to an object
    # definition, it is applied only to that object. Otherwise, it applies
    # the visibility to all future objects in the namespace.
    #
    # @example Modifying the visibility of a DSL method
    #   # @!visibility private
    #   cattr_accessor :subclasses
    # @example Modifying the visibility of a set of methods
    #   # Note that Ruby's "protected" is recommended over this directive
    #   # @!visibility protected
    #
    #   # Documentation for method1
    #   def method1; end
    #
    #   # Documentation for method2
    #   def method2; end
    # @since 0.7.0
    class VisibilityDirective < Directive
      def call
        if %w(public protected private).include?(tag.text)
          if object.is_a?(CodeObjects::Base)
            object.visibility = tag.text.to_sym
          elsif handler && !inside_directive?
            handler.visibility = tag.text.to_sym
          else
            parser.state.visibility = tag.text.to_sym
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/tags/library.rb000066400000000000000000000620561466601756300172340ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    # Keeps track of all the registered meta-data tags and directives.
    # Also allows for defining of custom tags and customizing the tag parsing
    # syntax.
    #
    # == Defining Custom Meta-Data Tags
    #
    # To define a custom tag, use {define_tag}. You should pass the tag
    # name and the factory method to use when creating the tag. If you do not
    # provide a factory method to use, it will default to {DefaultFactory#parse_tag}
    #
    # You can also define tag objects manually by simply implementing a "tagname_tag"
    # method that returns a {Tag} object, but they will not take advantage of tag factory
    # parsing:
    #
    #   def mytag_tag(text)
    #     Tag.new(:mytag, text)
    #   end
    #
    # == Defining Custom Directives
    #
    # Directives can be defined by calling the {define_directive} method, taking
    # the directive name, an optional tag factory parser method (to parse the
    # data in the directive into a temporary {Tag} object) and a {Directive} subclass
    # that performs the directive processing. For more information on creating a
    # Directive subclass, see the {Directive} class documentation.
    #
    # Similar to tags, Directives can also be defined manually, in this case using
    # the method name "mydirective_directive" and returning a new {Directive} object:
    #
    #   def mydirective_directive(tag, parser)
    #     MyDirective.new(tag, parser)
    #   end
    #
    # == Namespaced Tags
    #
    # In YARD 0.8.0+, tags can be namespaced using the '.' character. It is recommended
    # to namespace project specific tags, like +@yard.tag_name+, so that tags do not
    # collide with other plugins or new built-in tags.
    #
    # == Adding/Changing the Tag Syntax
    #
    # If you have specialized tag parsing needs you can substitute the {#factory}
    # object with your own by setting {Library.default_factory= Library.default_factory}
    # to a new class with its own parsing methods before running YARD. This is useful
    # if you want to change the syntax of existing tags (@see, @since, etc.)
    #
    # @example Defining a custom tag
    #   define_tag "Parameter", :param, :with_types_and_name
    #   define_tag "Author", :author
    # @example Defining a custom directive
    #   define_directive :method, :with_title_and_text, MethodDirective
    # @see DefaultFactory
    # @see define_tag
    # @see define_directive
    # @see Directive
    class Library
      class << self
        # @return [SymbolHash{Symbol=>String}] the map of tag names and their
        #   respective display labels.
        attr_reader :labels

        # @!attribute instance
        # @return [Library] the main Library instance object.
        def instance
          @instance ||= new
        end

        # @!attribute default_factory
        # Replace the factory object responsible for parsing tags by setting
        # this to an object (or class) that responds to +parse_TAGNAME+ methods
        # where +TAGNAME+ is the name of the tag.
        #
        # You should set this value before performing any source parsing with
        # YARD, otherwise your factory class will not be used.
        #
        # @example
        #   YARD::Tags::Library.default_factory = MyFactory
        #
        # @see DefaultFactory
        def default_factory
          @default_factory ||= DefaultFactory.new
        end

        def default_factory=(factory)
          @default_factory = factory.is_a?(Class) ? factory.new : factory
        end

        # Returns the factory method used to parse the tag text for a specific tag
        #
        # @param [Symbol] tag the tag name
        # @return [Symbol] the factory method name for the tag
        # @return [Class,Symbol] the Tag class to use to parse the tag
        #   or the method to call on the factory class
        # @return [nil] if the tag is freeform text
        # @since 0.6.0
        def factory_method_for(tag)
          @factory_methods[tag]
        end

        # Returns the factory method used to parse the tag text for a specific
        # directive
        #
        # @param [Symbol] directive the directive name
        # @return [Symbol] the factory method name for the tag
        # @return [Class,Symbol] the Tag class to use to parse the tag or
        #   the methods to call on the factory class
        # @return [nil] if the tag is freeform text
        # @since 0.8.0
        def factory_method_for_directive(directive)
          @directive_factory_classes[directive]
        end

        # Sets the list of tags to display when rendering templates. The order of
        # tags in the list is also significant, as it represents the order that
        # tags are displayed in templates.
        #
        # You can use the {Array#place} to insert new tags to be displayed in
        # the templates at specific positions:
        #
        #   Library.visible_tags.place(:mytag).before(:return)
        #
        # @return [Array] a list of ordered tags
        # @since 0.6.0
        attr_accessor :visible_tags

        # Sets the list of tags that should apply to any children inside the
        # namespace they are defined in. For instance, a "@since" tag should
        # apply to all methods inside a module it is defined in. Transitive
        # tags can be overridden by directly defining a tag on the child object.
        #
        # @return [Array] a list of transitive tags
        # @since 0.6.0
        attr_accessor :transitive_tags

        # Sorts the labels lexically by their label name, often used when displaying
        # the tags.
        #
        # @return [Array, String] the sorted labels as an array of the tag name and label
        def sorted_labels
          labels.sort_by {|a| a.last.downcase }
        end

        # Convenience method to define a new tag using one of {Tag}'s factory methods, or the
        # regular {DefaultFactory#parse_tag} factory method if none is supplied.
        #
        # @!macro [attach] yard.tag
        #   @!method $2_tag
        #   @!visibility private
        #   @yard.tag $2 [$3] $1
        # @param [#to_s] label the label used when displaying the tag in templates
        # @param [#to_s] tag the tag name to create
        # @param [#to_s, Class] meth the {Tag} factory method to call when
        #   creating the tag or the name of the class to directly create a tag for
        def define_tag(label, tag, meth = nil)
          tag_meth = tag_method_name(tag)
          if meth.is_a?(Class) && Tag > meth
            class_eval(<<-eof, __FILE__, __LINE__ + 1)
              def #{tag_meth}(text)
                #{meth}.new(#{tag.inspect}, text)
              end
            eof
          else
            class_eval(<<-eof, __FILE__, __LINE__ + 1)
              begin; undef #{tag_meth}; rescue NameError; end
              def #{tag_meth}(text)
                send_to_factory(#{tag.inspect}, #{meth.inspect}, text)
              end
            eof
          end

          @labels ||= SymbolHash.new(false)
          @labels.update(tag => label)
          @factory_methods ||= SymbolHash.new(false)
          @factory_methods.update(tag => meth)
          tag
        end

        # @macro [attach] yard.directive
        #   @!method $1_directive
        #   @!visibility private
        #   @yard.directive $1 [$2] $-1
        # @overload define_directive(tag, tag_meth = nil, directive_class)
        #   Convenience method to define a new directive using a {Tag} factory
        #   method and {Directive} subclass that implements the directive
        #   callbacks.
        #
        #   @param [#to_s] tag the tag name of the directive
        #   @param [#to_s] tag_meth the tag factory method to use when
        #     parsing tag information
        #   @param [Class] the directive class that implements the
        #     directive behaviour
        #   @see define_tag
        def define_directive(tag, tag_meth = nil, directive_class = nil)
          directive_meth = directive_method_name(tag)
          if directive_class.nil?
            directive_class = tag_meth
            tag_meth = nil
          end
          class_eval <<-eof, __FILE__, __LINE__
            def #{directive_meth}(tag, parser)
              directive_call(tag, parser)
            end
          eof

          @factory_methods ||= SymbolHash.new(false)
          @factory_methods.update(tag => tag_meth)
          @directive_factory_classes ||= SymbolHash.new(false)
          @directive_factory_classes.update(tag => directive_class)

          tag
        end

        def tag_method_name(tag_name)
          tag_or_directive_method_name(tag_name)
        end

        def directive_method_name(tag_name)
          tag_or_directive_method_name(tag_name, 'directive')
        end

        private

        def tag_or_directive_method_name(tag_name, type = 'tag')
          "#{tag_name.to_s.tr('.', '_')}_#{type}"
        end
      end

      private

      def send_to_factory(tag_name, meth, text)
        meth = meth.to_s
        send_name = "parse_tag" + (meth.empty? ? "" : "_" + meth)
        if @factory.respond_to?(send_name)
          @factory.send(send_name, tag_name, text)
        else
          raise NoMethodError, "Factory #{@factory.class_name} does not implement factory method :#{meth}."
        end
      end

      # @return [Directive]
      def directive_call(tag, parser)
        meth = self.class.factory_method_for_directive(tag.tag_name)
        if meth <= Directive
          meth = meth.new(tag, parser)
          meth.call
          meth
        else
          meth.call(tag, parser)
        end
      end

      public

      # A factory class to handle parsing of tags, defaults to {default_factory}
      attr_accessor :factory

      def initialize(factory = Library.default_factory)
        self.factory = factory
      end

      # @param [#to_s] tag_name the name of the tag to look for
      # @return [Boolean] whether a tag by the given name is registered in
      #   the library.
      def has_tag?(tag_name)
        tag_name && respond_to?(self.class.tag_method_name(tag_name))
      end

      # Creates a new {Tag} object with a given tag name and data
      # @return [Tag] the newly created tag object
      def tag_create(tag_name, tag_buf)
        send(self.class.tag_method_name(tag_name), tag_buf)
      end

      # @param [#to_s] tag_name the name of the tag to look for
      # @return [Boolean] whether a directive by the given name is registered in
      #   the library.
      def has_directive?(tag_name)
        tag_name && respond_to?(self.class.directive_method_name(tag_name))
      end

      # Creates a new directive with tag information and a docstring parser
      # object.
      # @param [String] tag_name the name of the tag
      # @param [String] tag_buf the tag data
      # @param [DocstringParser] parser the parser object parsing the docstring
      # @return [Directive] the newly created directive
      def directive_create(tag_name, tag_buf, parser)
        meth = self.class.factory_method_for(tag_name)
        tag = send_to_factory(tag_name, meth, tag_buf)
        meth = self.class.directive_method_name(tag_name)
        send(meth, tag, parser)
      end

      # @!macro yard.tag.transitive
      #   @note This tag is *transitive*. If it is applied on a
      #     namespace (module or class), it will immediately be
      #     applied to all children objects of that namespace unless
      #     it is redefined on the child object.

      # Marks a class/module/method as abstract with optional
      # implementor information.
      #
      # @example
      #   # @abstract Subclass and override {#run} to implement
      #   #   a custom Threadable class.
      #   class Runnable
      #     def run; raise NotImplementedError end
      #   end
      define_tag "Abstract",           :abstract

      # Declares the API that the object belongs to. Does not display in
      # output, but useful for performing queries (+yardoc --query+). Any text is
      # allowable in this tag, and there are no predefined values.
      #
      # @!macro yard.tag.transitive
      # @note The special name +@api private+ does display a notice in
      #   documentation if it is listed, letting users know that the
      #   method is not to be used by external components.
      # @example
      #   class Post
      #     # @api private
      #     def reset_table!; table.flush end
      #   end
      define_tag "API Visibility",     :api

      # Declares a readwrite attribute on a Struct or class.
      #
      # @note This attribute is only applicable on class docstrings
      # @deprecated Use the more powerful {tag:!attribute} directive instead.
      # @example
      #   # @attr [String] name the name of the structure
      #   # @attr [Fixnum] size the size of the structure
      #   class MyStruct < Struct; end
      define_tag "Attribute",          :attr,        :with_types_and_name

      # Declares a readonly attribute on a Struct or class.
      #
      # @note This attribute is only applicable on class docstrings
      # @deprecated Use the more powerful {tag:!attribute} directive instead.
      # @example
      #   # @attr_reader [String] name the name of the structure
      #   # @attr_reader [Fixnum] size the size of the structure
      #   class MyStruct < Struct; end
      define_tag "Attribute Getter",   :attr_reader, :with_types_and_name

      # Declares a writeonly attribute on a Struct or class.
      #
      # @note This attribute is only applicable on class docstrings
      # @deprecated Use the more powerful {tag:!attribute} directive instead.
      # @example
      #   # @attr_reader [String] name the name of the structure
      #   # @attr_reader [Fixnum] size the size of the structure
      #   class MyStruct < Struct; end
      define_tag "Attribute Setter",   :attr_writer, :with_types_and_name

      # List the author or authors of a class, module, or method.
      #
      # @example
      #   # @author Foo Bar 
      #   class MyClass; end
      define_tag "Author",             :author

      # Marks a method/class as deprecated with an optional description.
      # The description should be used to inform users of the recommended
      # migration path, and/or any useful information about why the object
      # was marked as deprecated.
      #
      # @example Deprecate a method with a replacement API
      #   # @deprecated Use {#bar} instead.
      #   def foo; end
      # @example Deprecate a method with no replacement
      #   class Thread
      #     # @deprecated Exiting a thread in this way is not reliable and
      #     #   can cause a program crash.
      #     def kill; end
      #   end
      define_tag "Deprecated",         :deprecated

      # Show an example snippet of code for an object. The first line
      # is an optional title.
      #
      # @example
      #   # @example Reverse a String
      #   #   "mystring".reverse #=> "gnirtsym"
      #   def reverse; end
      # @yard.signature Optional title
      #   Code block
      define_tag "Example",            :example, :with_title_and_text

      # Adds an emphasized note at the top of the docstring for the object
      #
      # @example
      #   # @note This method should only be used in outer space.
      #   def eject; end
      # @see tag:todo
      define_tag "Note",               :note

      # Describe an options hash in a method. The tag takes the
      # name of the options parameter first, followed by optional types,
      # the option key name, a default value for the key and a
      # description of the option. The default value should be placed within
      # parentheses and is optional (can be omitted).
      #
      # Note that a +@param+ tag need not be defined for the options
      # hash itself, though it is useful to do so for completeness.
      #
      # @note For keyword parameters, use +@param+, not +@option+.
      #
      # @example
      #   # @param [Hash] opts the options to create a message with.
      #   # @option opts [String] :subject The subject
      #   # @option opts [String] :from ('nobody') From address
      #   # @option opts [String] :to Recipient email
      #   # @option opts [String] :body ('') The email's body
      #   def send_email(opts = {}) end
      # @yard.signature name [Types] option_key (default_value) description
      define_tag "Options Hash",       :option,      :with_options

      # Describe that your method can be used in various
      # contexts with various parameters or return types. The first
      # line should declare the new method signature, and the following
      # indented tag data will be a new documentation string with its
      # own tags adding metadata for such an overload.
      #
      # @example
      #   # @overload set(key, value)
      #   #   Sets a value on key
      #   #   @param key [Symbol] describe key param
      #   #   @param value [Object] describe value param
      #   # @overload set(value)
      #   #   Sets a value on the default key +:foo+
      #   #   @param value [Object] describe value param
      #   def set(*args) end
      # @yard.signature method_signature(parameters)
      #   Indented docstring for overload method
      define_tag "Overloads",          :overload,    OverloadTag

      # Documents a single method parameter (either regular or keyword) with a given name, type
      # and optional description.
      #
      # @example
      #   # @param url [String] the URL of the page to download
      #   # @param directory [String] the name of the directory to save to
      #   def load_page(url, directory: 'pages') end
      define_tag "Parameters",         :param,       :with_types_and_name

      # Declares that the _logical_ visibility of an object is private.
      # In other words, it specifies that this method should be marked
      # private but cannot due to Ruby's visibility restrictions. This
      # exists for classes, modules and constants that do not obey Ruby's
      # visibility rules. For instance, an inner class might be considered
      # "private", though Ruby would make no such distinction.
      #
      # This tag is meant to be used in conjunction with the +--no-private+
      # command-line option, and is required to actually remove these objects
      # from documentation output. See {file:README.md} for more information on
      # switches.
      #
      # If you simply want to set the API visibility of a method, you should
      # look at the {tag:api} tag instead.
      #
      # @note This method is not recommended for hiding undocumented or
      #   "unimportant" methods. This tag should only be used to mark objects
      #   private when Ruby visibility rules cannot do so. In Ruby 1.9.3, you
      #   can use +private_constant+ to declare constants (like classes or
      #   modules) as private, and should be used instead of +@private+.
      # @macro yard.tag.transitive
      # @example
      #   # @private
      #   class InteralImplementation; end
      # @see tag:api
      # @yard.signature
      define_tag "Private",            :private

      # Describes that a method may raise a given exception, with
      # an optional description of what it may mean.
      #
      # @example
      #   # @raise [AccountBalanceError] if the account does not have
      #   #   sufficient funds to perform the transaction
      #   def withdraw(amount) end
      define_tag "Raises",             :raise,       :with_types

      # Describes the return value (and type or types) of a method.
      # You can list multiple return tags for a method in the case
      # where a method has distinct return cases. In this case, each
      # case should begin with "if ...".
      #
      # @example A regular return value
      #   # @return [Fixnum] the size of the file
      #   def size; @file.size end
      # @example A method returns an Array or a single object
      #   # @return [String] if a single object was returned
      #   #   from the database.
      #   # @return [Array] if multiple objects were
      #   #   returned.
      #   def find(query) end
      define_tag "Returns",            :return,      :with_types

      # "See Also" references for an object. Accepts URLs or
      # other code objects with an optional description at the end.
      # Note that the URL or object will be automatically linked by
      # YARD and does not need to be formatted with markup.
      #
      # @example
      #   # Synchronizes system time using NTP.
      #   # @see http://ntp.org/documentation.html NTP Documentation
      #   # @see NTPHelperMethods
      #   class NTPUpdater; end
      define_tag "See Also",           :see,         :with_name

      # Lists the version that the object was first added.
      #
      # @!macro yard.tag.transitive
      # @example
      #   # @since 1.2.4
      #   def clear_routes; end
      define_tag "Since",              :since

      # Marks a TODO note in the object being documented.
      # For reference, objects with TODO items can be enumerated
      # from the command line with a simple command:
      #
      #   !!!sh
      #   mocker$ yard list --query '@todo'
      #   lib/mocker/mocker.rb:15: Mocker
      #   lib/mocker/report/html.rb:5: Mocker::Report::Html
      #
      # YARD can also be used to enumerate the TODO items from
      # a short script:
      #
      #   !!!ruby
      #   require 'yard'
      #   YARD::Registry.load!.all.each do |o|
      #     puts o.tag(:todo).text if o.tag(:todo)
      #   end
      #
      # @example
      #   # @todo Add support for Jabberwocky service.
      #   #   There is an open source Jabberwocky library available
      #   #   at http://jbrwcky.org that can be easily integrated.
      #   class Wonderlander; end
      # @see tag:note
      define_tag "Todo Item",          :todo

      # Lists the version of a class, module or method. This is
      # similar to a library version, but at finer granularity.
      # In some cases, version of specific modules, classes, methods
      # or generalized components might change independently between
      # releases. A version tag is used to infer the API compatibility
      # of a specific object.
      #
      # @example
      #   # The public REST API for http://jbrwcky.org
      #   # @version 2.0
      #   class JabberwockyAPI; end
      define_tag "Version",            :version

      # Describes what a method might yield to a given block.
      # The types specifier list should not list types, but names
      # of the parameters yielded to the block. If you define
      # parameters with +@yieldparam+, you do not need to define
      # the parameters in the type specification of +@yield+ as
      # well.
      #
      # @example
      #   # For a block {|a,b,c| ... }
      #   # @yield [a, b, c] Gives 3 random numbers to the block
      #   def provide3values(&block) yield(42, 42, 42) end
      # @see tag:yieldparam
      # @see tag:yieldreturn
      # @yard.signature [parameters] description
      define_tag "Yields",             :yield,       :with_types

      # Defines a parameter yielded by a block. If you define the
      # parameters with +@yieldparam+, you do not need to define
      # them via +@yield+ as well.
      #
      # @example
      #   # @yieldparam [String] name the name that is yielded
      #   def with_name(name) yield(name) end
      define_tag "Yield Parameters",   :yieldparam,  :with_types_and_name

      # Documents the value and type that the block is expected
      # to return to the method.
      #
      # @example
      #   # @yieldreturn [Fixnum] the number to add 5 to.
      #   def add5_block(&block) 5 + yield end
      # @see tag:return
      define_tag "Yield Returns",      :yieldreturn, :with_types

      # @yard.signature [r | w | rw] attribute_name
      #   Indented attribute docstring
      define_directive :attribute, :with_types_and_title, AttributeDirective

      # @yard.signature
      define_directive :endgroup,                         EndGroupDirective

      define_directive :group,                            GroupDirective

      # @yard.signature [attach | new] optional_name
      #   Optional macro expansion data
      define_directive :macro, :with_types_and_title,     MacroDirective

      # @yard.signature method_signature(parameters)
      #   Indented method docstring
      define_directive :method, :with_title_and_text,     MethodDirective

      # @yard.signature [language] code
      define_directive :parse, :with_types,               ParseDirective

      # Sets the scope of a DSL method. Only applicable to DSL method
      # calls. Acceptable values are 'class' or 'instance'
      # @yard.signature class | instance
      define_directive :scope,                            ScopeDirective

      # Sets the visibility of a DSL method. Only applicable to
      # DSL method calls. Acceptable values are public, protected, or private.
      # @yard.signature public | protected | private
      define_directive :visibility,                       VisibilityDirective

      self.visible_tags = [:abstract, :deprecated, :note, :todo, :example, :overload,
        :param, :option, :yield, :yieldparam, :yieldreturn, :return, :raise,
        :see, :author, :since, :version]

      self.transitive_tags = [:since, :api]
    end
  end
end
yard-0.9.37/lib/yard/tags/option_tag.rb000066400000000000000000000003611466601756300177220ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    class OptionTag < Tag
      attr_accessor :pair

      def initialize(tag_name, name, pair)
        super(tag_name, nil, nil, name)
        @pair = pair
      end
    end
  end
end
yard-0.9.37/lib/yard/tags/overload_tag.rb000066400000000000000000000037751466601756300202410ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    class OverloadTag < Tag
      attr_reader :signature, :parameters, :docstring

      def initialize(tag_name, text)
        super(tag_name, nil)
        parse_tag(text)
        parse_signature
      end

      def tag(name) docstring.tag(name) end
      def tags(name = nil) docstring.tags(name) end
      def has_tag?(name) docstring.has_tag?(name) end

      def object=(value)
        super(value)
        docstring.object = value
        docstring.tags.each {|tag| tag.object = value }
      end

      def name(prefix = false)
        return @name unless prefix
        object.scope == :class ? @name.to_s : "#{object.send(:sep)}#{@name}"
      end

      def method_missing(*args, &block)
        object.send(*args, &block)
      end

      def type
        object.type
      end

      def is_a?(other)
        object.is_a?(other) || self.class >= other.class || false
      end
      alias kind_of? is_a?

      private

      def parse_tag(text)
        @signature, text = *text.split(/\r?\n/, 2)
        @signature.strip!
        text ||= String.new("")
        numspaces = text[/\A(\s*)/, 1].length
        text.gsub!(/^[ \t]{#{numspaces}}/, '')
        text.strip!
        @docstring = Docstring.new(text, nil)
      end

      def parse_signature
        if signature =~ /^(?:def\s)?\s*(#{CodeObjects::METHODMATCH})(?:(?:\s+|\s*\()(.*)(?:\)\s*$)?)?/m
          meth = $1
          args = $2
          meth.gsub!(/\s+/, '')
          # FIXME: refactor this code to not make use of the Handlers::Base class (tokval_list should be moved)
          toks = YARD::Parser::Ruby::Legacy::TokenList.new(args)
          args = YARD::Handlers::Ruby::Legacy::Base.new(nil, nil).send(:tokval_list, toks, :all)
          args = args.map do |a|
            k, v = *a.split(/:|=/, 2)
            [k.strip.to_s + (a[k.size, 1] == ':' ? ':' : ''), (v ? v.strip : nil)]
          end if args
          @name = meth.to_sym
          @parameters = args
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/tags/ref_tag.rb000066400000000000000000000001671466601756300171720ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    module RefTag
      attr_accessor :owner
    end
  end
end
yard-0.9.37/lib/yard/tags/ref_tag_list.rb000066400000000000000000000011701466601756300202200ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    class RefTagList
      attr_accessor :owner, :tag_name, :name

      def initialize(tag_name, owner, name = nil)
        @owner = CodeObjects::Proxy === owner ? owner : P(owner)
        @tag_name = tag_name.to_s
        @name = name
      end

      def tags
        if owner.is_a?(CodeObjects::Base)
          o = owner.tags(tag_name)
          o = o.select {|t| t.name.to_s == name.to_s } if name
          o.each do |t|
            t.extend(RefTag)
            t.owner = owner
          end
          o
        else
          []
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/tags/tag.rb000066400000000000000000000051671466601756300163430ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    # Represents a metadata tag value (+@tag+). Tags can have any combination of
    # {#types}, {#name} and {#text}, or none of the above.
    #
    # @example Programmatic tag creation
    #   # The following docstring syntax:
    #   #   @param [String, nil] arg an argument
    #   #
    #   # is equivalent to:
    #   Tag.new(:param, 'an argument', ['String', 'nil'], 'arg')
    class Tag
      # @return [String] the name of the tag
      attr_accessor :tag_name

      # @return [String] the tag text associated with the tag
      # @return [nil] if no tag text is supplied
      attr_accessor :text

      # @return [Array] a list of types associated with the tag
      # @return [nil] if no types are associated with the tag
      attr_accessor :types

      # @return [String] a name associated with the tag
      # @return [nil] if no tag name is supplied
      attr_accessor :name

      # @return [CodeObjects::Base] the associated object
      attr_accessor :object

      # Creates a new tag object with a tag name and text. Optionally, formally declared types
      # and a key name can be specified.
      #
      # Types are mainly for meta tags that rely on type information, such as +param+, +return+, etc.
      #
      # Key names are for tags that declare meta data for a specific key or name, such as +param+,
      # +raise+, etc.
      #
      # @param [#to_s] tag_name        the tag name to create the tag for
      # @param [String] text           the descriptive text for this tag
      # @param [Array] types   optional type list of formally declared types
      #                                for the tag
      # @param [String] name           optional key name which the tag refers to
      def initialize(tag_name, text, types = nil, name = nil)
        @tag_name = tag_name.to_s
        @text = text
        @name = name
        @types = (types ? [types].flatten.compact : nil)
      end

      # Convenience method to access the first type specified. This should mainly
      # be used for tags that only specify one type.
      #
      # @return [String] the first of the list of specified types
      # @see #types
      def type
        types.first
      end

      # Provides a plain English summary of the type specification, or nil
      # if no types are provided or parsable.
      #
      # @return [String] a plain English description of the associated types
      # @return [nil] if no types are provided or not parsable
      def explain_types
        return nil if !types || types.empty?
        TypesExplainer.explain(*types)
      end
    end
  end
end
yard-0.9.37/lib/yard/tags/tag_format_error.rb000066400000000000000000000001621466601756300211120ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Tags
    class TagFormatError < RuntimeError
    end
  end
end
yard-0.9.37/lib/yard/tags/types_explainer.rb000066400000000000000000000114411466601756300207730ustar00rootroot00000000000000# frozen_string_literal: true
require 'strscan'

module YARD
  module Tags
    class TypesExplainer
      # (see Tag#explain_types)
      # @param types [Array] a list of types to parse and summarize
      def self.explain(*types)
        explain!(*types)
      rescue SyntaxError
        nil
      end

      # (see explain)
      # @raise [SyntaxError] if the types are not parsable
      def self.explain!(*types)
        Parser.parse(types.join(", ")).join("; ")
      end

      class << self
        private :new
      end

      # @private
      class Type
        attr_accessor :name

        def initialize(name)
          @name = name
        end

        def to_s(singular = true)
          if name[0, 1] == "#"
            singular ? "an object that responds to #{name}" : "objects that respond to #{name}"
          elsif name[0, 1] =~ /[A-Z]/
            singular ? "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} " + name : "#{name}#{name[-1, 1] =~ /[A-Z]/ ? "'" : ''}s"
          else
            name
          end
        end

        private

        def list_join(list)
          index = 0
          list.inject(String.new) do |acc, el|
            acc << el.to_s
            acc << ", " if index < list.size - 2
            acc << " or " if index == list.size - 2
            index += 1
            acc
          end
        end
      end

      # @private
      class CollectionType < Type
        attr_accessor :types

        def initialize(name, types)
          @name = name
          @types = types
        end

        def to_s(_singular = true)
          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} of (" + list_join(types.map {|t| t.to_s(false) }) + ")"
        end
      end

      # @private
      class FixedCollectionType < CollectionType
        def to_s(_singular = true)
          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} containing (" + types.map(&:to_s).join(" followed by ") + ")"
        end
      end

      # @private
      class HashCollectionType < Type
        attr_accessor :key_types, :value_types

        def initialize(name, key_types, value_types)
          @name = name
          @key_types = key_types
          @value_types = value_types
        end

        def to_s(_singular = true)
          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} with keys made of (" +
            list_join(key_types.map {|t| t.to_s(false) }) +
            ") and values of (" + list_join(value_types.map {|t| t.to_s(false) }) + ")"
        end
      end

      # @private
      class Parser
        include CodeObjects

        TOKENS = {
          :collection_start => / />/,
          :fixed_collection_start => /\(/,
          :fixed_collection_end => /\)/,
          :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|\w+/,
          :type_next => /[,;]/,
          :whitespace => /\s+/,
          :hash_collection_start => /\{/,
          :hash_collection_next => /=>/,
          :hash_collection_end => /\}/,
          :parse_end => nil
        }

        def self.parse(string)
          new(string).parse
        end

        def initialize(string)
          @scanner = StringScanner.new(string)
        end

        def parse
          types = []
          type = nil
          name = nil
          loop do
            found = false
            TOKENS.each do |token_type, match|
              # TODO: cleanup this code.
              # rubocop:disable Lint/AssignmentInCondition
              next unless (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
              found = true
              case token_type
              when :type_name
                raise SyntaxError, "expecting END, got name '#{token}'" if name
                name = token
              when :type_next
                raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
                type = Type.new(name) unless type
                types << type
                type = nil
                name = nil
              when :fixed_collection_start, :collection_start
                name ||= "Array"
                klass = token_type == :collection_start ? CollectionType : FixedCollectionType
                type = klass.new(name, parse)
              when :hash_collection_start
                name ||= "Hash"
                type = HashCollectionType.new(name, parse, parse)
              when :hash_collection_next, :hash_collection_end, :fixed_collection_end, :collection_end, :parse_end
                raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
                type = Type.new(name) unless type
                types << type
                return types
              end
            end
            raise SyntaxError, "invalid character at #{@scanner.peek(1)}" unless found
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/000077500000000000000000000000001466601756300162725ustar00rootroot00000000000000yard-0.9.37/lib/yard/templates/engine.rb000066400000000000000000000165301466601756300200710ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module Templates
    # This module manages all creation, handling and rendering of {Template}
    # objects.
    #
    # * To create a template object at a path, use {template}.
    # * To render a template, call {render}.
    # * To register a template path in the lookup paths, call {register_template_path}.
    module Engine
      class << self
        # @return [Array] the list of registered template paths
        attr_accessor :template_paths

        # Registers a new template path in {template_paths}
        #
        # @param [String] path a new template path
        # @return [void]
        def register_template_path(path)
          template_paths.push(path) unless template_paths.include?(path)
        end

        # Creates a template module representing the path. Searches on disk
        # for the first directory named +path+ (joined by '/') within the
        # template paths and builds a template module for. All other matching
        # directories in other template paths will be included in the
        # generated module as mixins (for overriding).
        #
        # @param [Array] path a list of path components
        # @raise [ArgumentError] if the path does not exist within one of the
        #   {template_paths} on disk.
        # @return [Template] the module representing the template
        def template(*path)
          from_template = nil
          from_template = path.shift if path.first.is_a?(Template)
          path = path.join('/')
          full_paths = find_template_paths(from_template, path)

          path = File.cleanpath(path).gsub('../', '')
          raise ArgumentError, "No such template for #{path}" if full_paths.empty?
          mod = template!(path, full_paths)

          mod
        end

        # Forces creation of a template at +path+ within a +full_path+.
        #
        # @param [String] path the path name of the template
        # @param [Array] full_paths the full path on disk of the template
        # @return [Template] the template module representing the +path+
        def template!(path, full_paths = nil)
          full_paths ||= [path]
          full_paths = [full_paths] unless full_paths.is_a?(Array)
          name = template_module_name(full_paths.first)
          begin; return const_get(name); rescue NameError; nil end

          mod = const_set(name, Module.new)
          mod.send(:include, Template)
          mod.send(:initialize, path, full_paths)
          mod
        end

        # Renders a template on a {CodeObjects::Base code object} using
        # a set of default (overridable) options. Either the +:object+
        # or +:type+ keys must be provided.
        #
        # If a +:serializer+ key is provided and +:serialize+ is not set to
        # false, the rendered contents will be serialized through the {Serializers::Base}
        # object. See {with_serializer}.
        #
        # @example Renders an object with html formatting
        #   Engine.render(:format => :html, :object => obj)
        # @example Renders without an object
        #   Engine.render(:type => :fulldoc, :otheropts => somevalue)
        # @param [Hash] options the options hash
        # @option options [Symbol] :format (:text) the default format
        # @option options [Symbol] :type (nil) the :object's type.
        # @option options [Symbol] :template (:default) the default template
        # @return [String] the rendered template
        def render(options = {})
          options = set_default_options(options)
          mod = template(options.template, options.type, options.format)

          if options.serializer && options.serialize != false
            with_serializer(options.object, options.serializer) { mod.run(options) }
          else
            mod.run(options)
          end
        end

        # Passes a set of objects to the +:fulldoc+ template for full documentation generation.
        # This is called by {CLI::Yardoc} to most commonly perform HTML
        # documentation generation.
        #
        # @param [Array] objects a list of {CodeObjects::Base}
        #   objects to pass to the template
        # @param [Hash] options (see {render})
        # @return [void]
        def generate(objects, options = {})
          options = set_default_options(options)
          options.objects = objects
          options.object = Registry.root
          template(options.template, :fulldoc, options.format).run(options)
        end

        # Serializes the results of a block with a +serializer+ object.
        #
        # @param [CodeObjects::Base] object the code object to serialize
        # @param [Serializers::Base] serializer the serializer object
        # @yield a block whose result will be serialize
        # @yieldreturn [String] the contents to serialize
        # @see Serializers::Base
        def with_serializer(object, serializer)
          output = nil
          filename = serializer.serialized_path(object)
          if serializer.respond_to?(:basepath)
            filename = File.join(serializer.basepath, filename)
          end
          log.capture("Generating #{filename}", nil) do
            serializer.before_serialize if serializer
            output = yield
            if serializer
              serializer.serialize(object, output)
              serializer.after_serialize(output)
            end
          end
          output
        end

        private

        # Sets default options on the options hash
        #
        # @param [Hash] options the options hash
        # @option options [Symbol] :format (:text) the default format
        # @option options [Symbol] :type (nil) the :object's type, if provided
        # @option options [Symbol] :template (:default) the default template
        # @return [void]
        def set_default_options(options = {})
          if options.is_a?(Hash)
            options = TemplateOptions.new.tap do |o|
              o.reset_defaults
              o.update(options)
            end
          end
          options.type ||= options.object.type if options.object
          options
        end

        # Searches through the registered {template_paths} and returns
        # all full directories that have the +path+ within them on disk.
        #
        # @param [Template] from_template if provided, allows a relative
        #   path to be specified from this template's full path.
        # @param [String] path the path component to search for in the
        #   {template_paths}
        # @return [Array] a list of full paths that are existing
        #   candidates for a template module
        def find_template_paths(from_template, path)
          paths = template_paths.dup
          paths = from_template.full_paths + paths if from_template

          paths.inject([]) do |acc, tp|
            full_path = File.cleanpath(File.join(tp, path))
            acc.unshift(full_path) if File.directory?(full_path)
            acc
          end.uniq
        end

        # The name of the module that represents a +path+
        #
        # @param [String] path the path to generate a module name for
        # @return [String] the module name
        def template_module_name(path)
          'Template_' + path.to_s.gsub(/[^a-z0-9]/i, '_')
        end
      end

      self.template_paths = []
    end

    Engine.register_template_path(File.join(YARD::ROOT, '..', 'templates'))
  end
end
yard-0.9.37/lib/yard/templates/erb_cache.rb000066400000000000000000000011071466601756300205110ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates
    # @since 0.5.4
    module ErbCache
      def self.method_for(filename)
        @methods ||= {}
        return @methods[filename] if @methods[filename]
        @methods[filename] = name = "_erb_cache_#{@methods.size}"
        erb = yield.src
        encoding = erb[/\A(#coding[:=].*\r?\n)/, 1] || ''
        module_eval "#{encoding}def #{name}; #{erb}; end", filename

        name
      end

      def self.clear!
        return unless defined?(@methods) && @methods
        @methods.clear
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/000077500000000000000000000000001466601756300177345ustar00rootroot00000000000000yard-0.9.37/lib/yard/templates/helpers/base_helper.rb000066400000000000000000000157711466601756300225450ustar00rootroot00000000000000# frozen_string_literal: true
module YARD::Templates::Helpers
  # The base helper module included in all templates.
  module BaseHelper
    attr_accessor :object, :serializer

    # @return [CodeObjects::Base] the object representing the current generated
    #   page. Might not be the current {#object} when inside sub-templates.
    attr_reader :owner
    undef owner
    def owner; (defined?(@owner) && @owner) || object.namespace end

    # @group Managing Global Template State

    # An object that keeps track of global state throughout the entire template
    # rendering process (including any sub-templates).
    #
    # @return [OpenStruct] a struct object that stores state
    # @since 0.6.0
    def globals; options.globals end

    # @group Running the Verifier

    # Runs a list of objects against the {Verifier} object passed into the
    # template and returns the subset of verified objects.
    #
    # @param [Array] list a list of code objects
    # @return [Array] a list of code objects that match
    #   the verifier. If no verifier is supplied, all objects are returned.
    def run_verifier(list)
      options.verifier ? options.verifier.run(list) : list
    end

    # @group Escaping Text

    # Escapes text. This is used a lot by the HtmlHelper and there should
    # be some helper to "clean up" text for whatever, this is it.
    def h(text)
      text
    end

    # @group Linking Objects and URLs

    # Links objects or URLs. This method will delegate to the correct +link_+
    # method depending on the arguments passed in.
    #
    # @example Linking a URL
    #   linkify('http://example.com')
    # @example Including docstring contents of an object
    #   linkify('include:YARD::Docstring')
    # @example Linking to an extra file
    #   linkify('file:README')
    # @example Linking an object by path
    #   linkify('YARD::Docstring')
    def linkify(*args)
      if args.first.is_a?(String)
        case args.first
        when %r{://}, /^mailto:/
          link_url(args[0], args[1], {:target => '_parent'}.merge(args[2] || {}))
        when /^include:file:(\S+)/
          file = $1
          relpath = File.relative_path(Dir.pwd, File.expand_path(file))
          if relpath =~ /^\.\./
            log.warn "Cannot include file from path `#{file}'"
            ""
          elsif File.file?(file)
            link_include_file(file)
          else
            log.warn "Cannot find file at `#{file}' for inclusion"
            ""
          end
        when /^include:(\S+)/
          path = $1
          obj = YARD::Registry.resolve(object.namespace, path)
          if obj
            link_include_object(obj)
          else
            log.warn "Cannot find object at `#{path}' for inclusion"
            ""
          end
        when /^render:(\S+)/
          path = $1
          obj = YARD::Registry.resolve(object, path)
          if obj
            opts = options.dup
            opts.delete(:serializer)
            obj.format(opts)
          else
            ''
          end
        when /^file:(\S+?)(?:#(\S+))?$/
          link_file($1, args[1] ? args[1] : nil, $2)
        else
          link_object(*args)
        end
      else
        link_object(*args)
      end
    end

    # Includes an object's docstring into output.
    # @since 0.6.0
    # @param [CodeObjects::Base] obj the object to include
    # @return [String] the object's docstring (no tags)
    def link_include_object(obj)
      obj.docstring
    end

    # Include a file as a docstring in output
    # @since 0.7.0
    # @param [String] file the filename to include
    # @return [String] the file's contents
    def link_include_file(file)
      File.read(file)
    end

    # Links to an object with an optional title
    #
    # @param [CodeObjects::Base] obj the object to link to
    # @param [String] title the title to use for the link
    # @return [String] the linked object
    def link_object(obj, title = nil)
      return title if title

      case obj
      when YARD::CodeObjects::Base, YARD::CodeObjects::Proxy
        obj.title
      when String, Symbol
        P(obj).title
      else
        obj
      end
    end

    # Links to a URL
    #
    # @param [String] url the URL to link to
    # @param [String] title the optional title to display the link as
    # @param [Hash] params optional parameters for the link
    # @return [String] the linked URL
    def link_url(url, title = nil, params = nil) # rubocop:disable Lint/UnusedMethodArgument
      url
    end

    # Links to an extra file
    #
    # @param [String] filename the filename to link to
    # @param [String] title the title of the link
    # @param [String] anchor optional anchor
    # @return [String] the link to the file
    # @since 0.5.5
    def link_file(filename, title = nil, anchor = nil) # rubocop:disable Lint/UnusedMethodArgument
      return filename.filename if CodeObjects::ExtraFileObject === filename
      filename
    end

    # @group Formatting Object Attributes

    # Formats a list of return types for output and links each type.
    #
    # @example Formatting types
    #   format_types(['String', 'Array']) #=> "(String, Array)"
    # @example Formatting types without surrounding brackets
    #   format_types(['String', 'Array'], false) #=> "String, Array"
    # @param [Array] list a list of types
    # @param [Boolean] brackets whether to surround the types in brackets
    # @return [String] the formatted list of Ruby types
    def format_types(list, brackets = true)
      list.nil? || list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
    end

    # @example Formatted type of an exception class
    #   o = ClassObject.new(:root, :MyError)
    #   o.superclass = P('RuntimeError')
    #   format_object_type(o) # => "Exception"
    # @example Formatted type of a method
    #   o = MethodObject.new(:root, :to_s)
    #   format_object_type(o) # => "Method"
    # @param [CodeObjects::Base] object the object to retrieve the type for
    # @return [String] the human-readable formatted {CodeObjects::Base#type #type}
    #   for the object
    def format_object_type(object)
      case object
      when YARD::CodeObjects::ClassObject
        object.is_exception? ? "Exception" : "Class"
      else
        object.type.to_s.capitalize
      end
    end

    # @example
    #   s = format_object_title ModuleObject.new(:root, :MyModuleName)
    #   s # => "Module: MyModuleName"
    # @param [CodeObjects::Base] object the object to retrieve a title for
    # @return [String] the page title name for a given object
    def format_object_title(object)
      case object
      when YARD::CodeObjects::RootObject
        "Top Level Namespace"
      else
        format_object_type(object) + ": " + object.title
      end
    end

    # Indents and formats source code
    #
    # @param [String] value the input source code
    # @return [String] formatted source code
    def format_source(value)
      sp = value.split("\n").last[/^(\s+)/, 1]
      num = sp ? sp.size : 0
      value.gsub(/^\s{#{num}}/, '')
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/filter_helper.rb000066400000000000000000000013131466601756300231030ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates::Helpers
    # Helpers for various object types
    module FilterHelper
      # @return [Boolean] whether an object is a method
      def is_method?(object)
        object.type == :method
      end

      # @return [Boolean] whether an object is a namespace
      def is_namespace?(object)
        object.is_a?(CodeObjects::NamespaceObject)
      end

      # @return [Boolean] whether an object is a class
      def is_class?(object)
        object.is_a?(CodeObjects::ClassObject)
      end

      # @return [Boolean] whether an object is a module
      def is_module?(object)
        object.is_a?(CodeObjects::ModuleObject)
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/html_helper.rb000066400000000000000000000567321466601756300226010ustar00rootroot00000000000000# frozen_string_literal: true
require 'cgi'

module YARD
  module Templates::Helpers
    # The helper module for HTML templates.
    module HtmlHelper
      include MarkupHelper
      include HtmlSyntaxHighlightHelper

      # @private
      URLMATCH = /[^\w\s~!\*'\(\):;@&=\$,\[\]<>-]/

      # @private
      ASCIIDOC_ATTRIBUTES = {"env" => "yard", "env-yard" => ""}.freeze

      # @group Escaping Template Data

      # Escapes HTML entities
      #
      # @param [String] text the text to escape
      # @return [String] the HTML with escaped entities
      def h(text)
        CGI.escapeHTML(text.to_s)
      end

      # Escapes a URL
      #
      # @param [String] text the URL
      # @return [String] the escaped URL
      def urlencode(text)
        text = text.dup
        enc = nil
        if text.respond_to?(:force_encoding)
          enc = text.encoding
          text = text.force_encoding('binary')
        end

        text = text.gsub(/%[a-z0-9]{2}|#{URLMATCH}/i) do
          $&.size > 1 ? $& : "%" + $&.ord.to_s(16).upcase
        end.tr(' ', '+')

        text = text.force_encoding(enc) if enc
        text
      end

      module_function :urlencode

      # @group Converting Markup to HTML

      # Turns text into HTML using +markup+ style formatting.
      #
      # @param [String] text the text to format
      # @param [Symbol] markup examples are +:markdown+, +:textile+, +:rdoc+.
      #   To add a custom markup type, see {MarkupHelper}
      # @return [String] the HTML
      def htmlify(text, markup = options.markup)
        markup_meth = "html_markup_#{markup}"
        return text unless respond_to?(markup_meth)
        return "" unless text
        return text unless markup
        html = send(markup_meth, text).dup
        if html.respond_to?(:encode)
          html = html.force_encoding(text.encoding) # for libs that mess with encoding
          html = html.encode(:invalid => :replace, :replace => '?')
        end
        html = resolve_links(html)
        unless [:text, :none, :pre, :ruby].include?(markup)
          html = parse_codeblocks(html)
        end
        html
      end

      # Converts Markdown to HTML
      # @param [String] text input Markdown text
      # @return [String] output HTML
      # @since 0.6.0
      def html_markup_markdown(text)
        # TODO: other libraries might be more complex
        provider = markup_class(:markdown)
        case provider.to_s
        when  'RDiscount'
          provider.new(text, :autolink).to_html
        when 'RedcarpetCompat'
          provider.new(text, :autolink,
                             :fenced_code,
                             :gh_blockcode,
                             :lax_spacing,
                             :tables,
                             :with_toc_data,
                             :no_intraemphasis).to_html
        when 'CommonMarker'
          CommonMarker.render_html(text, %i[DEFAULT GITHUB_PRE_LANG], %i[autolink table])
        else
          provider.new(text).to_html
        end
      end

      # Converts org-mode to HTML
      # @param [String] text input org-mode text
      # @return [String] output HTML
      def html_markup_org(text)
        markup_class(:org).new(text).to_html
      end

      # Converts Asciidoc to HTML
      # @param [String] text input Asciidoc text
      # @return [String] output HTML
      def html_markup_asciidoc(text)
        options = {:attributes => ASCIIDOC_ATTRIBUTES}
        markup_class(:asciidoc).convert(text, options)
      end

      # Converts Textile to HTML
      # @param [String] text the input Textile text
      # @return [String] output HTML
      # @since 0.6.0
      def html_markup_textile(text)
        doc = markup_class(:textile).new(text)
        doc.hard_breaks = false if doc.respond_to?(:hard_breaks=)
        doc.to_html
      end

      # Converts plaintext to strict Textile (hard breaks)
      # @param [String] text the input textile data
      # @return [String] the output HTML
      # @since 0.6.0
      def html_markup_textile_strict(text)
        markup_class(:textile).new(text).to_html
      end

      # Converts RDoc formatting (SimpleMarkup) to HTML
      # @param [String] text the input RDoc formatted text
      # @return [String] output HTML
      # @since 0.6.0
      def html_markup_rdoc(text)
        doc = markup_class(:rdoc).new(text)
        doc.from_path = url_for(object) if doc.respond_to?(:from_path=)
        doc.to_html
      end

      # Converts plaintext to pre-formatted HTML
      # @param [String] text the input text
      # @return [String] the output HTML
      # @since 0.6.0
      def html_markup_pre(text)
        "
    " + h(text) + "
    "
      end

      # Converts plaintext to regular HTML
      # @param [String] text the input text
      # @return [String] the output HTML
      # @since 0.6.0
      def html_markup_text(text)
        h(text).gsub(/\r?\n/, '
    ')
      end

      # @return [String] the same text with no markup
      # @since 0.6.6
      def html_markup_none(text)
        h(text)
      end

      # Converts HTML to HTML
      # @param [String] text input html
      # @return [String] output HTML
      # @since 0.6.0
      def html_markup_html(text)
        text
      end

      # Highlights Ruby source. Similar to {#html_syntax_highlight}, but
      # this method is meant to be called from {#htmlify} when markup is
      # set to "ruby".
      #
      # @param [String] source the Ruby source
      # @return [String] the highlighted HTML
      # @since 0.7.0
      def html_markup_ruby(source)
        '
    ' + html_syntax_highlight(source, :ruby) + '
    '
      end

      # @return [String] HTMLified text as a single line (paragraphs removed)
      def htmlify_line(*args)
        "
    " + htmlify(*args) + "
    "
      end

      # @group Syntax Highlighting Source Code

      # Syntax highlights +source+ in language +type+.
      #
      # @note To support a specific language +type+, implement the method
      #   +html_syntax_highlight_TYPE+ in this class.
      #
      # @param [String] source the source code to highlight
      # @param [Symbol, String] type the language type (:ruby, :plain, etc). Use
      #   :plain for no syntax highlighting.
      # @return [String] the highlighted source
      def html_syntax_highlight(source, type = nil)
        return "" unless source
        return h(source) unless options.highlight

        new_type, source = parse_lang_for_codeblock(source)
        type ||= new_type || :ruby
        meth = "html_syntax_highlight_#{type}"
        respond_to?(meth) ? send(meth, source) : h(source)
      end

      # @return [String] unhighlighted source
      def html_syntax_highlight_plain(source)
        h(source)
      end

      # @group Linking Objects and URLs

      # Resolves any text in the form of +{Name}+ to the object specified by
      # Name. Also supports link titles in the form +{Name title}+.
      #
      # @example Linking to an instance method
      #   resolve_links("{MyClass#method}") # => "MyClass#method"
      # @example Linking to a class with a title
      #   resolve_links("{A::B::C the C class}") # => "the c class"
      # @param [String] text the text to resolve links in
      # @return [String] HTML with linkified references
      def resolve_links(text)
        code_tags = 0
        text.gsub(%r{<(/)?(pre|code|tt)|(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W<]|.+.*\s*(.*)\Z}
            name = $1
            title = $2
            title = nil if title.empty?
          end

          name = CGI.unescapeHTML(name)

          if object.is_a?(String)
            object
          else
            link = linkify(name, title)
            if (link == name || link == title) && (name + ' ' + link !~ /\A/)
              match = /(.+)?(\{#{Regexp.quote name}(?:\s.*?)?\})(.+)?/.match(text)
              file = (defined?(@file) && @file ? @file.filename : object.file) || '(unknown)'
              line = (defined?(@file) && @file ? 1 : (object.docstring.line_range ? object.docstring.line_range.first : 1)) + (match ? $`.count("\n") : 0)
              log.warn "In file `#{file}':#{line}: Cannot resolve link to #{name} from text" + (match ? ":" : ".") +
                       "\n\t" + (match[1] ? '...' : '') + match[2].delete("\n") + (match[3] ? '...' : '') if match
            end

            link
          end
        end
      end

      # (see BaseHelper#link_file)
      def link_file(filename, title = nil, anchor = nil)
        if CodeObjects::ExtraFileObject === filename
          file = filename
        else
          contents = File.file?(filename) ? nil : ''
          file = CodeObjects::ExtraFileObject.new(filename, contents)
        end
        return title || file.title unless serializer
        link_url(url_for_file(file, anchor), title || file.title)
      end

      # (see BaseHelper#link_include_file)
      def link_include_file(file)
        unless file.is_a?(CodeObjects::ExtraFileObject)
          file = CodeObjects::ExtraFileObject.new(file)
        end
        file.attributes[:markup] ||= markup_for_file('', file.filename)
        insert_include(file.contents, file.attributes[:markup] || options.markup)
      end

      # (see BaseHelper#link_include_object)
      def link_include_object(obj)
        insert_include(obj.docstring)
      end

      # Inserts an include link while respecting inlining
      def insert_include(text, markup = options.markup)
        htmlify(text, markup).gsub(%r{\A\s*
    |
    \s*\Z}, '')
      end

      # (see BaseHelper#link_object)
      def link_object(obj, title = nil, anchor = nil, relative = true)
        return title if obj.nil?
        obj = Registry.resolve(object, obj, true, true) if obj.is_a?(String)
        if title
          title = title.to_s
        elsif object.is_a?(CodeObjects::Base)
          # Check if we're linking to a class method in the current
          # object. If we are, create a title in the format of
          # "CurrentClass.method_name"
          if obj.is_a?(CodeObjects::MethodObject) && obj.scope == :class && obj.parent == object
            title = h([object.name, obj.sep, obj.name].join)
          elsif obj.title != obj.path
            title = h(obj.title)
          else
            title = h(object.relative_path(obj))
          end
        else
          title = h(obj.title)
        end
        return title unless serializer
        return title if obj.is_a?(CodeObjects::Proxy)

        link = url_for(obj, anchor, relative)
        link = link ? link_url(link, title, :title => h("#{obj.title} (#{obj.type})")) : title
        "" + link + ""
      rescue Parser::UndocumentableError
        log.warn "The namespace of link #{obj.inspect} is a constant or invalid."
        title || obj.to_s
      end

      # (see BaseHelper#link_url)
      def link_url(url, title = nil, params = {})
        title ||= url
        title = title.gsub(/[\r\n]/, ' ')
        params = SymbolHash.new(false).update(
          :href => url,
          :title => h(title)
        ).update(params)
        params[:target] ||= '_parent' if url =~ %r{^(\w+)://}
        "#{title}".gsub(/[\r\n]/, ' ')
      end

      # @group URL Helpers

      # @param [CodeObjects::Base] object the object to get an anchor for
      # @return [String] the anchor for a specific object
      def anchor_for(object)
        case object
        when CodeObjects::MethodObject
          "#{object.name}-#{object.scope}_#{object.type}"
        when CodeObjects::ClassVariableObject
          "#{object.name.to_s.gsub('@@', '')}-#{object.type}"
        when CodeObjects::Base
          "#{object.name}-#{object.type}"
        when CodeObjects::Proxy
          object.path
        else
          object.to_s
        end
      end

      # Returns the URL for an object.
      #
      # @param [String, CodeObjects::Base] obj the object (or object path) to link to
      # @param [String] anchor the anchor to link to
      # @param [Boolean] relative use a relative or absolute link
      # @return [String] the URL location of the object
      def url_for(obj, anchor = nil, relative = true)
        link = nil
        return link unless serializer
        return link if obj.is_a?(CodeObjects::Base) && run_verifier([obj]).empty?

        if obj.is_a?(CodeObjects::Base) && !obj.is_a?(CodeObjects::NamespaceObject)
          # If the obj is not a namespace obj make it the anchor.
          anchor = obj
          obj = obj.namespace
        end

        objpath = serializer.serialized_path(obj)
        return link unless objpath

        relative = false if object == Registry.root
        if relative
          fromobj = object
          if object.is_a?(CodeObjects::Base) &&
             !object.is_a?(CodeObjects::NamespaceObject)
            fromobj = owner
          end

          from = serializer.serialized_path(fromobj)
          link = File.relative_path(from, objpath)
        else
          link = objpath
        end

        link + (anchor ? '#' + urlencode(anchor_for(anchor)) : '')
      end

      alias mtime_url url_for
      def mtime(_file) nil end

      # Returns the URL for a specific file
      #
      # @param [String, CodeObjects::ExtraFileObject] filename the filename to link to
      # @param [String] anchor optional anchor
      # @return [String] the URL pointing to the file
      def url_for_file(filename, anchor = nil)
        return '' unless serializer
        fromobj = object
        if CodeObjects::Base === fromobj && !fromobj.is_a?(CodeObjects::NamespaceObject)
          fromobj = fromobj.namespace
        end
        from = serializer.serialized_path(fromobj)
        path = filename == options.readme ?
          'index.html' : serializer.serialized_path(filename)
        link = File.relative_path(from, path)
        link += (anchor ? '#' + urlencode(anchor) : '')
        link
      end

      # Returns the URL for a list type
      #
      # @param [String, Symbol] type the list type to generate a URL for
      # @return [String] the URL pointing to the list
      # @since 0.8.0
      def url_for_list(type)
        url_for_file("#{type}_list.html")
      end

      # Returns the URL for the frameset page
      #
      # @return [String] the URL pointing to the frames page
      # @since 0.8.0
      def url_for_frameset
        url_for_file("frames.html")
      end

      # Returns the URL for the main page (README or alphabetic index)
      #
      # @return [String] the URL pointing to the first main page the
      #   user should see.
      def url_for_main
        url_for_file("index.html")
      end

      # Returns the URL for the alphabetic index page
      #
      # @return [String] the URL pointing to the first main page the
      #   user should see.
      def url_for_index
        url_for_file("_index.html")
      end

      # @group Formatting Objects and Attributes

      # Formats a list of objects and links them
      # @return [String] a formatted list of objects
      def format_object_name_list(objects)
        objects.sort_by {|o| o.name.to_s.downcase }.map do |o|
          "" + linkify(o, o.name) + ""
        end.join(", ")
      end

      # Formats a list of types from a tag.
      #
      # @param [Array, FalseClass] typelist
      #   the list of types to be formatted.
      #
      # @param [Boolean] brackets omits the surrounding
      #   brackets if +brackets+ is set to +false+.
      #
      # @return [String] the list of types formatted
      #   as [Type1, Type2, ...] with the types linked
      #   to their respective descriptions.
      #
      def format_types(typelist, brackets = true)
        return unless typelist.is_a?(Array)
        list = typelist.map do |type|
          type = type.gsub(/([<>])/) { h($1) }
          type = type.gsub(/([\w:]+)/) { $1 == "lt" || $1 == "gt" ? $1 : linkify($1, $1) }
          "" + type + ""
        end
        list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
      end

      # Get the return types for a method signature.
      #
      # @param [CodeObjects::MethodObject] meth the method object
      # @param [Boolean] link whether to link the types
      # @return [String] the signature types
      # @since 0.5.3
      def signature_types(meth, link = true)
        meth = convert_method_to_overload(meth)
        if meth.respond_to?(:object) && !meth.has_tag?(:return)
          meth = meth.object
        end

        type = options.default_return || ""
        if meth.tag(:return) && meth.tag(:return).types
          types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
          first = link ? h(types.first) : format_types([types.first], false)
          if types.size == 2 && types.last == 'nil'
            type = first + '?'
          elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
            type = first + '+'
          elsif types.size > 2
            type = [first, '...'].join(', ')
          elsif types == ['void'] && options.hide_void_return
            type = ""
          else
            type = link ? h(types.join(", ")) : format_types(types, false)
          end
        elsif !type.empty?
          type = link ? h(type) : format_types([type], false)
        end
        type = "#{type} " unless type.empty?
        type
      end

      # Formats the signature of method +meth+.
      #
      # @param [CodeObjects::MethodObject] meth the method object to list
      #   the signature of
      # @param [Boolean] link whether to link the method signature to the details view
      # @param [Boolean] show_extras whether to show extra meta-data (visibility, attribute info)
      # @param [Boolean] full_attr_name whether to show the full attribute name
      #   ("name=" instead of "name")
      # @return [String] the formatted method signature
      def signature(meth, link = true, show_extras = true, full_attr_name = true)
        meth = convert_method_to_overload(meth)

        type = signature_types(meth, link)
        type = "⇒ #{type}" if type && !type.empty?
        scope = meth.scope == :class ? "." : "#"
        name = full_attr_name ? meth.name : meth.name.to_s.gsub(/^(\w+)=$/, '\1')
        blk = format_block(meth)
        args = !full_attr_name && meth.writer? ? "" : format_args(meth)
        extras = []
        extras_text = ''
        if show_extras
          rw = meth.attr_info
          if rw
            attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
            attname = attname.size == 1 ? attname.join('') + 'only' : nil
            extras << attname if attname
          end
          extras << meth.visibility if meth.visibility != :public
          extras_text = ' (' + extras.join(", ") + ')' unless extras.empty?
        end
        title = "%s%s%s %s %s" % [scope, h(name), args, blk, type]
        if link
          if meth.is_a?(YARD::CodeObjects::MethodObject)
            link_title = "#{h meth.name(true)} (#{meth.scope} #{meth.type})"
          else
            link_title = "#{h name} (#{meth.type})"
          end
          obj = meth.respond_to?(:object) ? meth.object : meth
          url = url_for(object, obj)
          link_url(url, title, :title => link_title) + extras_text
        else
          title + extras_text
        end
      end

      # @group Getting the Character Encoding

      # Returns the current character set. The default value can be overridden
      # by setting the +LANG+ environment variable or by overriding this
      # method. In Ruby 1.9 you can also modify this value by setting
      # +Encoding.default_external+.
      #
      # @return [String] the current character set
      # @since 0.5.4
      def charset
        has_encoding = defined?(::Encoding)
        if defined?(@file) && @file && has_encoding
          lang = @file.contents.encoding.to_s
        else
          return 'utf-8' unless has_encoding || ENV['LANG']
          lang =
            if has_encoding
              ::Encoding.default_external.name.downcase
            else
              ENV['LANG'].downcase.split('.').last
            end
        end

        case lang
        when "ascii-8bit", "us-ascii", "ascii-7bit"; 'iso-8859-1'
        when "utf8"; 'utf-8'
        else; lang
        end
      end

      # @endgroup

      private

      # Converts a set of hash options into HTML attributes for a tag
      #
      # @param [Hash{String => String}] opts the tag options
      # @return [String] the tag attributes of an HTML tag
      def tag_attrs(opts = {})
        opts.sort_by {|k, _v| k.to_s }.map {|k, v| "#{k}=#{v.to_s.inspect}" if v }.join(" ")
      end

      # Converts a {CodeObjects::MethodObject} into an overload object
      # @since 0.5.3
      def convert_method_to_overload(meth)
        # use first overload tag if it has a return type and method itself does not
        if !meth.tag(:return) && meth.tags(:overload).size == 1 && meth.tag(:overload).tag(:return)
          return meth.tag(:overload)
        end
        meth
      end

      # Parses !!!lang out of codeblock, returning the codeblock language
      # followed by the source code.
      #
      # @param [String] source the source code whose language to determine
      # @return [Array(String, String)] the language, if any, and the
      #   remaining source
      # @since 0.7.5
      def parse_lang_for_codeblock(source)
        type = nil
        if source =~ /\A(?:[ \t]*\r?\n)?[ \t]*!!!([\w.+-]+)[ \t]*\r?\n/
          type = $1
          source = $'
        end

        [type, source]
      end

      # Parses code blocks out of html and performs syntax highlighting
      # on code inside of the blocks.
      #
      # @param [String] html the html to search for code in
      # @return [String] highlighted html
      # @see #html_syntax_highlight
      def parse_codeblocks(html)
        html.gsub(%r{(?:\s*)?(.+?)(?:\s*)?
    }m) do
          string = $3

          # handle !!!LANG prefix to send to html_syntax_highlight_LANG
          language, = parse_lang_for_codeblock(string)
          language ||= detect_lang_in_codeblock_attributes($1, $2)
          language ||= object.source_type

          if options.highlight
            string = html_syntax_highlight(CGI.unescapeHTML(string), language)
          end
          classes = ['code', language].compact.join(' ')
          %(
    #{string}
    )
        end
      end

      # Parses code block's HTML attributes in order to detect the programming
      # language of what's enclosed in that code block.
      #
      # @param [String, nil] pre_html_attrs HTML attribute list of +pre+ element
      # @param [String, nil] code_html_attrs HTML attribute list of +code+
      #   element
      # @return [String, nil] detected programming language
      def detect_lang_in_codeblock_attributes(pre_html_attrs, code_html_attrs)
        detected = nil
        detected ||= (/\bdata-lang="(.+?)"/ =~ code_html_attrs && $1)
        detected ||= (/\blang="(.+?)"/ =~ pre_html_attrs && $1)
        detected ||= (/\bclass="(.+?)"/ =~ code_html_attrs && $1)
        detected
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/html_syntax_highlight_helper.rb000066400000000000000000000054141466601756300262250ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates
    module Helpers
      # Helper methods for syntax highlighting.
      module HtmlSyntaxHighlightHelper
        include ModuleHelper

        # Highlights Ruby source
        # @param [String] source the Ruby source code
        # @return [String] the highlighted Ruby source
        def html_syntax_highlight_ruby(source)
          if Parser::SourceParser.parser_type == :ruby
            html_syntax_highlight_ruby_ripper(source)
          else
            html_syntax_highlight_ruby_legacy(source)
          end
        end

        private

        def html_syntax_highlight_ruby_ripper(source)
          resolver = Parser::Ruby::TokenResolver.new(source, object)
          output = String.new("")
          resolver.each do |s, token_obj|
            token_obj = clean_token_object(token_obj)
            output << "" if [:tstring_beg, :regexp_beg].include?(s[0])
            case s.first
            when :nl, :ignored_nl, :sp
              output << h(s[1])
            when :ident, :const
              klass = s.first == :ident ? "id identifier rubyid_#{h(s[1])}" : s.first
              val = token_obj ? link_object(token_obj, s[1]) : h(s[1])
              output << "#{val}"
            else
              output << "#{h(s[1])}"
            end
            output << "" if [:tstring_end, :regexp_end].include?(s[0])
          end
          output
        rescue Parser::ParserSyntaxError
          source =~ /^#{prettyval}"
            else
              "#{h s.text}"
            end
          end.join
        end

        def clean_token_object(token_obj)
          return unless token_obj
          if token_obj == object
            token_obj = nil
          elsif token_obj.is_a?(CodeObjects::MethodObject)
            token_obj = prune_method_listing([token_obj], false).first
          else
            token_obj = run_verifier([token_obj]).first
          end

          token_obj
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/markup/000077500000000000000000000000001466601756300212335ustar00rootroot00000000000000yard-0.9.37/lib/yard/templates/helpers/markup/rdoc_markdown.rb000066400000000000000000000010411466601756300244050ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates
    module Helpers
      module Markup
        begin require 'rdoc'; rescue LoadError; nil end
        begin
          require 'rdoc/markdown'
        rescue LoadError
          raise NameError, "could not load RDoc Markdown support (rdoc is too old)"
        end

        class RDocMarkdown < RDocMarkup
          def initialize(text)
            super RDoc::Markdown.new.parse(text)
          end

          def fix_typewriter(html) html end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/markup/rdoc_markup.rb000066400000000000000000000063051466601756300240720ustar00rootroot00000000000000# frozen_string_literal: true
require 'thread'

module YARD
  module Templates
    module Helpers
      module Markup
        begin require 'rdoc'; rescue LoadError; nil end
        begin
          require 'rdoc/markup'
          require 'rdoc/markup/to_html'
          class RDocMarkup; MARKUP = RDoc::Markup end
          class RDocMarkupToHtml < RDoc::Markup::ToHtml
            if defined?(RDoc::VERSION) && RDoc::VERSION >= '4.0.0' &&
               defined?(RDoc::Options)
              def initialize
                options = RDoc::Options.new
                options.pipe = true
                super(options)
              end
            end
          end
        rescue LoadError
          begin
            require 'rdoc/markup/simple_markup'
            require 'rdoc/markup/simple_markup/to_html'
            class RDocMarkup; MARKUP = SM::SimpleMarkup end
            class RDocMarkupToHtml < SM::ToHtml; end
          rescue LoadError
            raise NameError, "could not load RDocMarkup (rdoc is not installed)"
          end
        end

        class RDocMarkup
          attr_accessor :from_path

          @@mutex = Mutex.new
          @@formatter = nil
          @@markup = nil

          def initialize(text)
            @text = text

            @@mutex.synchronize do
              @@formatter ||= RDocMarkupToHtml.new
              @@markup ||= MARKUP.new
            end
          end

          def to_html
            html = nil
            @@mutex.synchronize do
              @@formatter.from_path = from_path
              html = @@markup.convert(@text, @@formatter)
            end
            html = fix_dash_dash(html)
            html = fix_typewriter(html)
            html
          end

          private

          # Fixes RDoc behaviour with ++ only supporting alphanumeric text.
          #
          # @todo Refactor into own SimpleMarkup subclass
          def fix_typewriter(text)
            code_tags = 0
            text.gsub(%r{<(/)?(pre|code|tt)|(\s|^|>)\+(?! )([^\n\+]{1,900})(?! )\+}) do |str|
              closed = $1
              tag = $2
              first_text = $3
              type_text = $4

              if tag
                code_tags += (closed ? -1 : 1)
                next str
              end
              next str unless code_tags == 0
              first_text + '' + type_text + ''
            end
          end

          # Don't allow -- to turn into — element. The chances of this being
          # some --option is far more likely than the typographical meaning.
          #
          # @todo Refactor into own SimpleMarkup subclass
          def fix_dash_dash(text)
            text.gsub(/—(?=\S)/, '--')
          end
        end

        class RDocMarkupToHtml
          attr_accessor :from_path

          # Disable auto-link of URLs
          def handle_special_HYPERLINK(special) # rubocop:disable Style/MethodName
            @hyperlink ? special.text : super
          end

          def accept_paragraph(*args)
            par = args.last
            text = par.respond_to?(:txt) ? par.txt : par.text
            @hyperlink = text =~ /\{(https?:|mailto:|link:|www\.)/ ? true : false
            super
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/markup_helper.rb000066400000000000000000000147341466601756300231300ustar00rootroot00000000000000# frozen_string_literal: true
require 'rubygems'

module YARD
  module Templates::Helpers
    # Helper methods for loading and managing markup types.
    module MarkupHelper
      class << self
        # Clears the markup provider cache information. Mainly used for testing.
        # @return [void]
        def clear_markup_cache
          self.markup_cache = {}
        end

        # @return [Hash{Symbol=>{(:provider,:class)=>Object}}] the cached markup providers
        # @private
        # @since 0.6.4
        attr_accessor :markup_cache
      end

      MarkupHelper.clear_markup_cache

      # The default list of markup providers for each markup type
      MARKUP_PROVIDERS = {
        :markdown => [
          {:lib => :redcarpet, :const => 'RedcarpetCompat'},
          {:lib => :rdiscount, :const => 'RDiscount'},
          {:lib => :kramdown, :const => 'Kramdown::Document'},
          {:lib => :bluecloth, :const => 'BlueCloth'},
          {:lib => :maruku, :const => 'Maruku'},
          {:lib => :'rpeg-markdown', :const => 'PEGMarkdown'},
          {:lib => :rdoc, :const => 'YARD::Templates::Helpers::Markup::RDocMarkdown'},
          {:lib => :commonmarker, :const => 'CommonMarker'}
        ],
        :textile => [
          {:lib => :redcloth, :const => 'RedCloth'}
        ],
        :textile_strict => [
          {:lib => :redcloth, :const => 'RedCloth'}
        ],
        :rdoc => [
          {:lib => nil, :const => 'YARD::Templates::Helpers::Markup::RDocMarkup'}
        ],
        :org => [
          {:lib => :'org-ruby', :const => 'Orgmode::Parser'}
        ],
        :asciidoc => [
          {:lib => :asciidoctor, :const => 'Asciidoctor'}
        ],
        :ruby => [],
        :text => [],
        :pre  => [],
        :html => [],
        :none => []
      }

      # Returns a list of extensions for various markup types. To register
      # extensions for a type, add them to the array of extensions for the
      # type.
      # @since 0.6.0
      MARKUP_EXTENSIONS = {
        :html => ['htm', 'html', 'shtml'],
        :text => ['txt'],
        :textile => ['textile', 'txtile'],
        :asciidoc => ['asciidoc', 'ad', 'adoc', 'asc'],
        :markdown => ['markdown', 'md', 'mdown', 'mkd'],
        :rdoc => ['rdoc'],
        :org => ['org'],
        :ruby => ['rb', 'ru']
      }

      # Contains the Regexp object that matches the shebang line of extra
      # files to detect the markup type.
      MARKUP_FILE_SHEBANG = /\A#!(\S+)\s*$/

      # Attempts to load the first valid markup provider in {MARKUP_PROVIDERS}.
      # If a provider is specified, immediately try to load it.
      #
      # On success this sets `@markup_provider` and `@markup_class` to
      # the provider name and library constant class/module respectively for
      # the loaded provider.
      #
      # On failure this method will inform the user that no provider could be
      # found and exit the program.
      #
      # @return [Boolean] whether the markup provider was successfully loaded.
      def load_markup_provider(type = options.markup)
        return true if MarkupHelper.markup_cache[type]
        MarkupHelper.markup_cache[type] ||= {}

        providers = MARKUP_PROVIDERS[type.to_sym]
        return true if providers && providers.empty?
        if providers && options.markup_provider
          providers = providers.select {|p| p[:lib] == options.markup_provider }
        end

        if providers.nil? || providers.empty?
          log.error "Invalid markup type '#{type}' or markup provider " \
                    "(#{options.markup_provider}) is not registered."
          return false
        end

        # Search for provider, return the library class name as const if found
        providers.each do |provider|
          begin require provider[:lib].to_s; rescue LoadError; next end if provider[:lib]
          begin klass = eval("::" + provider[:const]); rescue NameError; next end # rubocop:disable Lint/Eval
          MarkupHelper.markup_cache[type][:provider] = provider[:lib] # Cache the provider
          MarkupHelper.markup_cache[type][:class] = klass
          return true
        end

        # Show error message telling user to install first potential provider
        lib = providers.first[:lib] || type
        log.error "Missing '#{lib}' gem for #{type.to_s.capitalize} formatting. Install it with `gem install #{lib}`"
        false
      end

      # Checks for a shebang or looks at the file extension to determine
      # the markup type for the file contents. File extensions are registered
      # for a markup type in {MARKUP_EXTENSIONS}.
      #
      # A shebang should be on the first line of a file and be in the form:
      #
      #   #!markup_type
      #
      # Standard markup types are text, html, rdoc, markdown, textile
      #
      # @param [String] contents Unused. Was necessary prior to 0.7.0.
      #   Newer versions of YARD use {CodeObjects::ExtraFileObject#contents}
      # @return [Symbol] the markup type recognized for the file
      # @see MARKUP_EXTENSIONS
      # @since 0.6.0
      def markup_for_file(contents, filename)
        return $1.to_sym if contents && contents =~ MARKUP_FILE_SHEBANG # Shebang support

        ext = (File.extname(filename)[1..-1] || '').downcase
        MARKUP_EXTENSIONS.each do |type, exts|
          return type if exts.include?(ext)
        end
        options.markup
      end

      # Strips any shebang lines on the file contents that pertain to
      # markup or preprocessing data.
      #
      # @deprecated Use {CodeObjects::ExtraFileObject#contents} instead
      # @return [String] the file contents minus any preprocessing tags
      # @since 0.6.0
      def markup_file_contents(contents)
        contents =~ MARKUP_FILE_SHEBANG ? $' : contents
      end

      # Gets the markup provider class/module constant for a markup type
      # Call {#load_markup_provider} before using this method.
      #
      # @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
      # @return [Class] the markup class
      def markup_class(type = options.markup)
        load_markup_provider(type)
        MarkupHelper.markup_cache[type][:class]
      end

      # Gets the markup provider name for a markup type
      # Call {#load_markup_provider} before using this method.
      #
      # @param [Symbol] type the markup type (:rdoc, :markdown, etc.)
      # @return [Symbol] the markup provider name (usually the gem name of the library)
      def markup_provider(type = options.markup)
        MarkupHelper.markup_cache[type][:provider]
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/method_helper.rb000066400000000000000000000050311466601756300230770ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates::Helpers
    # Helper methods for method objects.
    module MethodHelper
      # @return [String] formatted arguments for a method
      def format_args(object)
        return if object.parameters.nil?
        params = object.parameters
        if object.has_tag?(:yield) || object.has_tag?(:yieldparam)
          params.reject! do |param|
            param[0].to_s[0, 1] == "&" &&
              !object.tags(:param).any? {|t| t.name == param[0][1..-1] }
          end
        end

        if params.empty?
          ""
        else
          args = params.map do |n, v|
            v ? "#{n}#{n[-1, 1] == ':' ? '' : ' ='} #{v}" : n.to_s
          end.join(", ")
          h("(#{args})")
        end
      end

      # @return [String] formatted and linked return types for a method
      def format_return_types(object)
        return unless object.has_tag?(:return) && object.tag(:return).types
        return if object.tag(:return).types.empty?
        format_types [object.tag(:return).types.first], false
      end

      # @return [String] formatted block if one exists
      def format_block(object)
        if object.has_tag?(:yield) && object.tag(:yield).types
          params = object.tag(:yield).types
        elsif object.has_tag?(:yieldparam)
          params = object.tags(:yieldparam).map(&:name)
        elsif object.has_tag?(:yield)
          return "{ ... }"
        else
          params = nil
        end

        params ? h("{|" + params.join(", ") + "| ... }") : ""
      end

      # @return [String] formats line numbers for source code of an object
      def format_lines(object)
        return "" if object.source.nil? || object.line.nil?
        i = -1
        object.source.split(/\n/).map { object.line + (i += 1) }.join("\n")
      end

      # @return [String] formats source of an object
      def format_code(object, _show_lines = false)
        i = -1
        lines = object.source.split(/\n/)
        longestline = (object.line + lines.size).to_s.length
        lines.map do |line|
          lineno = object.line + (i += 1)
          (" " * (longestline - lineno.to_s.length)) + lineno.to_s + "    " + line
        end.join("\n")
      end

      # @return [String] formats source code of a constant value
      def format_constant(value)
        # last can return nil, so default to empty string
        sp = value.split("\n").last || ""
        sp = sp[/^(\s+)/, 1]
        num = sp ? sp.size : 0
        html_syntax_highlight value.gsub(/^\s{#{num}}/, '')
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/module_helper.rb000066400000000000000000000016101466601756300231030ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates
    module Helpers
      # Helper methods for managing module objects.
      module ModuleHelper
        # Prunes the method listing by running the verifier and removing attributes/aliases
        # @param [Array] list a list of methods
        # @param [Boolean] hide_attributes whether to prune attribute methods from the list
        # @return [Array] a pruned list of methods
        def prune_method_listing(list, hide_attributes = true)
          list = run_verifier(list)
          list = list.reject {|o| run_verifier([o.parent]).empty? }
          list = list.reject {|o| o.is_alias? unless CodeObjects::Proxy === o.namespace }
          list = list.reject {|o| o.is_attribute? unless CodeObjects::Proxy === o.namespace } if hide_attributes
          list
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/text_helper.rb000066400000000000000000000075341466601756300226150ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates
    module Helpers
      # Helper methods for text template formats.
      module TextHelper
        # @return [String] escapes text
        def h(text)
          out = String.new("")
          text = resolve_links(text)
          text = text.split(/\n/)
          text.each_with_index do |line, i|
            out <<
              case line
              when /^\s*$/; "\n\n"
              when /^\s+\S/, /^=/; line + "\n"
              else; line + (text[i + 1] =~ /^\s+\S/ ? "\n" : " ")
              end
          end
          out
        end

        # @return [String] wraps text at +col+ columns.
        def wrap(text, col = 72)
          text.gsub(/(.{1,#{col}})( +|$\n?)|(.{1,#{col}})/, "\\1\\3\n")
        end

        # @return [String] indents +text+ by +len+ characters.
        def indent(text, len = 4)
          text.gsub(/^/, ' ' * len)
        end

        # @return [String] aligns a title to the right
        def title_align_right(text, col = 72)
          align_right(text, '-', col)
        end

        # @return [String] aligns text to the right
        def align_right(text, spacer = ' ', col = 72)
          text = text[0, col - 4] + '...' if (col - 1 - text.length) < 0
          spacer * (col - 1 - text.length) + " " + text
        end

        # @return [String] returns a horizontal rule for output
        def hr(col = 72, sep = "-")
          sep * col
        end

        # @return [String] the formatted signature for a method
        def signature(meth)
          # use first overload tag if it has a return type and method itself does not
          if !meth.tag(:return) && meth.tag(:overload) && meth.tag(:overload).tag(:return)
            meth = meth.tag(:overload)
          end

          type = options.default_return || ""
          rmeth = meth
          if !rmeth.has_tag?(:return) && rmeth.respond_to?(:object)
            rmeth = meth.object
          end
          if rmeth.tag(:return) && rmeth.tag(:return).types
            types = rmeth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
            first = types.first
            if types.size == 2 && types.last == 'nil'
              type = first + '?'
            elsif types.size == 2 && types.last =~ /^(Array)?<#{Regexp.quote types.first}>$/
              type = first + '+'
            elsif types.size > 2
              type = [first, '...'].join(', ')
            elsif types == ['void'] && options.hide_void_return
              type = ""
            else
              type = types.join(", ")
            end
          end
          type = "(#{type})" if type.include?(',')
          type = " -> #{type} " unless type.empty?
          scope = meth.scope == :class ? "#{meth.namespace.name}." : "#{meth.namespace.name.to_s.downcase}."
          name = meth.name
          blk = format_block(meth)
          args = format_args(meth)
          extras = []
          extras_text = ''
          rw = meth.namespace.attributes[meth.scope][meth.name]
          if rw
            attname = [rw[:read] ? 'read' : nil, rw[:write] ? 'write' : nil].compact
            attname = attname.size == 1 ? attname.join('') + 'only' : nil
            extras << attname if attname
          end
          extras << meth.visibility if meth.visibility != :public
          extras_text = '(' + extras.join(", ") + ')' unless extras.empty?
          title = "%s%s%s %s%s%s" % [scope, name, args, blk, type, extras_text]
          title.gsub(/\s+/, ' ')
        end

        private

        def resolve_links(text)
          text.gsub(/(\\|!)?\{(?!\})(\S+?)(?:\s([^\}]*?\S))?\}(?=[\W]|$)/m) do |_str|
            escape = $1
            name = $2
            title = $3
            match = $&
            next(match[1..-1]) if escape
            next(match) if name[0, 1] == '|'
            linkify(name, title)
          end
        end
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/helpers/uml_helper.rb000066400000000000000000000026711466601756300224230ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates::Helpers
    # Helpers for UML template format
    module UMLHelper
      # Official UML visibility prefix syntax for an object given its visibility
      # @param [CodeObjects::Base] object the object to retrieve visibility for
      # @return [String] the UML visibility prefix
      def uml_visibility(object)
        case object.visibility
        when :public;    '+'
        when :protected; '#'
        when :private;   '-'
        end
      end

      # Formats the path of an object for Graphviz syntax
      # @param [CodeObjects::Base] object an object to format the path of
      # @return [String] the encoded path
      def format_path(object)
        object.path.gsub('::', '_')
      end

      # Encodes text in escaped Graphviz syntax
      # @param [String] text text to encode
      # @return [String] the encoded text
      def h(text)
        text.to_s.gsub(/(\W)/, '\\\\\1')
      end

      # Tidies data by formatting and indenting text
      # @param [String] data pre-formatted text
      # @return [String] tidied text.
      def tidy(data)
        indent = 0
        data.split(/\n/).map do |line|
          line.gsub!(/^\s*/, '')
          next if line.empty?
          indent -= 1 if line =~ /^\s*\}\s*$/
          line = (' ' * (indent * 2)) + line
          indent += 1 if line =~ /\{\s*$/
          line
        end.compact.join("\n") + "\n"
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/section.rb000066400000000000000000000044751466601756300202750ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  module Templates
    # Abstracts the structure for a section and its subsections into an ordered
    # list of sections and subsections.
    # @since 0.6.0
    class Section < Array
      attr_accessor :name

      def initialize(name, *args)
        self.name = name
        replace(parse_sections(args))
      end

      def dup
        obj = super
        obj.name = name
        obj
      end

      def [](*args)
        if args.first.is_a?(Range) || args.size > 1
          return self.class.new(name, *super(*args))
        elsif args.first.is_a?(Integer)
          return super(*args)
        end
        find {|o| o.name == args.first }
      end

      def eql?(other)
        super(other) && name == other.name
      end

      def ==(other)
        case other
        when Section
          eql?(other)
        when Array
          to_a == other
        else
          name == other
        end
      end

      def push(*args)
        super(*parse_sections(args))
      end
      alias << push

      def unshift(*args)
        super(*parse_sections(args))
      end

      def inspect
        n = name.respond_to?(:path) ? "T('#{name.path}')" : name.inspect
        subsects = empty? ? "" : ", subsections=#{super}"
        "Section(#{n}#{subsects})"
      end

      def place(*args)
        super(*parse_sections(args))
      end

      def to_a
        list = [name]
        unless empty?
          subsects = []
          each {|s| subsects += s.to_a }
          list << subsects
        end
        list
      end

      def any(item)
        find do |section|
          return section if section == item
          return section.any(item) unless section.empty?
        end
        nil
      end

      private

      def parse_sections(args)
        if args.size == 1 && args.first.is_a?(Array) && !args.first.is_a?(Section)
          args = args.first
        end
        sections = []
        args.each_with_index do |name, index|
          case name
          when Section; sections << name
          when Array;   next
          else
            subsections = args[index + 1].is_a?(Array) ? args[index + 1] : []
            subsections = [] if subsections.is_a?(Section)
            sections << Section.new(name, subsections)
          end
        end
        sections
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/template.rb000066400000000000000000000341321466601756300204350ustar00rootroot00000000000000# frozen_string_literal: true
require 'erb'

module YARD
  module Templates
    module Template
      attr_accessor :class, :section
      attr_reader :options

      class << self
        # Extra includes are mixins that are included after a template is created. These
        # mixins can be registered by plugins to operate on templates and override behaviour.
        #
        # Note that this array can be filled with modules or proc objects. If a proc object
        # is given, the proc will be called with the {Template#options} hash containing
        # relevant template information like the object, format, and more. The proc should
        # return a module or nil if there is none.
        #
        # @example Adding in extra mixins to include on a template
        #   Template.extra_includes << MyHelper
        # @example Conditionally including a mixin if the format is html
        #   Template.extra_includes << proc {|opts| MyHelper if opts.format == :html }
        # @return [Array] a list of modules to be automatically included
        #   into any new template module
        attr_accessor :extra_includes

        # @!parse extend ClassMethods
        # @private
        def included(klass)
          klass.extend(ClassMethods)
        end

        # Includes the {extra_includes} modules into the template object.
        #
        # @param [Template] template the template object to mixin the extra includes.
        # @param [SymbolHash] options the options hash containing all template information
        # @return [void]
        def include_extra(template, options)
          extra_includes.each do |mod|
            mod = mod.call(options) if mod.is_a?(Proc)
            next unless mod.is_a?(Module)
            template.extend(mod)
          end
        end
      end

      self.extra_includes = [
        proc do |options|
          {:html => Helpers::HtmlHelper,
            :text => Helpers::TextHelper,
            :dot  => Helpers::UMLHelper}[options.format]
        end
      ]

      include ErbCache
      include Helpers::BaseHelper
      include Helpers::MethodHelper

      module ClassMethods
        attr_accessor :path, :full_path

        # @return [Array] a list of full paths
        # @note This method caches path results. Paths should not be modified
        #   after this method is called; call {#reset_full_paths} to reset cache.
        def full_paths
          reset_full_paths unless defined? @cached_included_modules
          return @full_paths if included_modules == @cached_included_modules

          @cached_included_modules = included_modules
          @full_paths = included_modules.inject([full_path]) do |paths, mod|
            paths |= mod.full_paths if mod.respond_to?(:full_paths)
            paths
          end
        end

        # Resets cache for {#full_paths}
        def reset_full_paths
          @cached_included_modules = nil
        end

        def initialize(path, full_paths)
          full_path = full_paths.shift
          self.path = path
          self.full_path = full_path
          include_inherited(full_paths)
          include_parent
          load_setup_rb
        end

        # Searches for a file identified by +basename+ in the template's
        # path as well as any mixed in template paths. Equivalent to calling
        # {ClassMethods#find_nth_file} with index of 1.
        #
        # @param [String] basename the filename to search for
        # @return [String] the full path of a file on disk with filename
        #   +basename+ in one of the template's paths.
        # @see find_nth_file
        def find_file(basename)
          find_nth_file(basename)
        end

        # Searches for the nth file (where n = +index+) identified
        # by basename in the template's path and any mixed in template paths.
        #
        # @param [String] basename the filename to search for
        # @param [Fixnum] index the nth existing file to return
        # @return [String] the full path of the nth file on disk with
        #   filename +basename+ in one of the template paths
        def find_nth_file(basename, index = 1)
          n = 1
          full_paths.each do |path|
            file = File.join(path, basename)
            if File.file?(file)
              return file if index == n
              n += 1
            end
          end

          nil
        end

        def is_a?(klass)
          return true if klass == Template
          super(klass)
        end

        # Creates a new template object to be rendered with {Template#run}
        def new(*args)
          obj = Object.new.extend(self)
          obj.class = self
          obj.send(:initialize, *args)
          obj
        end

        def run(*args)
          new(*args).run
        end

        # rubocop:disable Style/MethodName

        # Alias for creating {Engine.template}.
        def T(*path)
          Engine.template(*path)
        end

        # Alias for creating a {Section} with arguments
        # @see Section#initialize
        # @since 0.6.0
        def S(*args)
          Section.new(*args)
        end

        # rubocop:enable Style/MethodName

        private

        def include_parent
          pc = path.to_s.split('/')
          if pc.size > 1
            pc.pop
            pc = pc.join('/')
            begin
              include Engine.template(pc)
            rescue ArgumentError
              include Engine.template!(pc, full_path.gsub(%r{/[^/]+$}, ''))
            end
          end
        end

        def include_inherited(full_paths)
          full_paths.reverse.each do |full_path|
            include Engine.template!(path, full_path)
          end
        end

        def load_setup_rb
          setup_file = File.join(full_path, 'setup.rb')
          if File.file? setup_file
            setup_code = File.read(setup_file)
            setup_code.taint if setup_code.respond_to?(:taint)
            module_eval(setup_code, setup_file, 1)
          end
        end
      end

      def initialize(opts = TemplateOptions.new)
        opts_class = opts.class
        opts_class = TemplateOptions if opts_class == Hash
        @cache = {}
        @cache_filename = {}
        @sections = []
        @options = opts_class.new
        add_options(opts)
        Template.include_extra(self, options)
        init
      end

      # Loads a template specified by path. If +:template+ or +:format+ is
      # specified in the {#options} hash, they are prepended and appended
      # to the path respectively.
      #
      # @param [Array] path the path of the template
      # @return [Template] the loaded template module
      def T(*path) # rubocop:disable Style/MethodName
        path.unshift(options.template) if options.template
        path.push(options.format) if options.format
        self.class.T(*path)
      end

      # Sets the sections (and subsections) to be rendered for the template
      #
      # @example Sets a set of erb sections
      #   sections :a, :b, :c # searches for a.erb, b.erb, c.erb
      # @example Sets a set of method and erb sections
      #   sections :a, :b, :c # a is a method, the rest are erb files
      # @example Sections with subsections
      #   sections :header, [:name, :children]
      #   # the above will call header.erb and only renders the subsections
      #   # if they are yielded by the template (see #yieldall)
      # @param [Array] args the sections
      #   to use to render the template. For symbols and strings, the
      #   section will be executed as a method (if one exists), or rendered
      #   from the file "name.erb" where name is the section name. For
      #   templates, they will have {Template::ClassMethods#run} called on them.
      #   Any subsections can be yielded to using yield or {#yieldall}
      def sections(*args)
        @sections = Section.new(nil, *args) unless args.empty?
        @sections
      end

      # Initialization called on the template. Override this in a 'setup.rb'
      # file in the template's path to implement a template
      #
      # @example A default set of sections
      #   def init
      #     sections :section1, :section2, [:subsection1, :etc]
      #   end
      # @see #sections
      def init
      end

      # Runs a template on +sects+ using extra options. This method should
      # not be called directly. Instead, call the class method {ClassMethods#run}
      #
      # @param [Hash, nil] opts any extra options to apply to sections
      # @param [Section, Array] sects a section list of sections to render
      # @param [Fixnum] start_at the index in the section list to start from
      # @param [Boolean] break_first if true, renders only the first section
      # @yield [opts] calls for the subsections to be rendered
      # @yieldparam [Hash] opts any extra options to yield
      # @return [String] the rendered sections joined together
      def run(opts = nil, sects = sections, start_at = 0, break_first = false, &block)
        out = String.new("")
        return out if sects.nil?
        sects = sects[start_at..-1] if start_at > 0
        sects = Section.new(nil, sects) unless sects.is_a?(Section)
        add_options(opts) do
          sects.each do |s|
            self.section = s
            subsection_index = 0
            value = render_section(section) do |*args|
              value = with_section do
                run(args.first, section, subsection_index, true, &block)
              end
              subsection_index += 1
              value
            end
            out << (value || "")
            break if break_first
          end
        end
        out
      end

      # Yields all subsections with any extra options
      #
      # @param [Hash] opts extra options to be applied to subsections
      def yieldall(opts = nil, &block)
        with_section { run(opts, section, &block) }
      end

      # @param [String, Symbol] section the section name
      # @yield calls subsections to be rendered
      # @return [String] the contents of the ERB rendered section
      def erb(section, &block)
        method_name = ErbCache.method_for(cache_filename(section)) do
          erb_with(cache(section), cache_filename(section))
        end
        send(method_name, &block)
      end

      # Returns the contents of a file. If +allow_inherited+ is set to +true+,
      # use +{{{__super__}}}+ inside the file contents to insert the contents
      # of the file from an inherited template. For instance, if +templates/b+
      # inherits from +templates/a+ and file "test.css" exists in both directories,
      # both file contents can be retrieved by having +templates/b/test.css+ look
      # like:
      #
      #   {{{__super__}}}
      #   ...
      #   body { css styles here }
      #   p.class { other styles }
      #
      # @param [String] basename the name of the file
      # @param [Boolean] allow_inherited whether inherited templates can
      #   be inserted with +{{{__super__}}}+
      # @return [String] the contents of a file identified by +basename+. All
      #   template paths (including any mixed in templates) are searched for
      #   the file
      # @see ClassMethods#find_file
      # @see ClassMethods#find_nth_file
      def file(basename, allow_inherited = false)
        file = self.class.find_file(basename)
        raise ArgumentError, "no file for '#{basename}' in #{self.class.path}" unless file

        data = IO.read(file)
        if allow_inherited
          superfile = self.class.find_nth_file(basename, 2)
          data.gsub!('{{{__super__}}}', superfile ? IO.read(superfile) : "")
        end

        data
      end

      # Calls the ERB file from the last inherited template with {#section}.erb
      #
      # @param [Symbol, String] sect if provided, uses a specific section name
      # @return [String] the rendered ERB file in any of the inherited template
      #   paths.
      def superb(sect = section, &block)
        filename = self.class.find_nth_file(erb_file_for(sect), 2)
        return "" unless filename
        method_name = ErbCache.method_for(filename) { erb_with(IO.read(filename), filename) }
        send(method_name, &block)
      end

      def options=(value)
        @options = value
        set_ivars
      end

      def inspect
        "Template(#{self.class.path}) [section=#{section.name}]"
      end

      protected

      def erb_file_for(section)
        "#{section}.erb"
      end

      def erb_with(content, filename = nil)
        erb = if ERB.instance_method(:initialize).parameters.assoc(:key) # Ruby 2.6+
                ERB.new(content, :trim_mode => options.format == :text ? '<>' : nil)
              else
                ERB.new(content, nil, options.format == :text ? '<>' : nil)
              end
        erb.filename = filename if filename
        erb
      end

      private

      def render_section(section, &block)
        section = section.name if section.is_a?(Section)
        case section
        when Section, String, Symbol
          if respond_to?(section)
            send(section, &block)
          else
            erb(section, &block)
          end
        when Module, Template
          section.run(options, &block) if section.is_a?(Template)
        end || ""
      end

      def cache(section)
        content = @cache[section.to_sym]
        return content if content

        file = cache_filename(section)
        @cache_filename[section.to_sym] = file
        raise ArgumentError, "no template for section '#{section}' in #{self.class.path}" unless file
        @cache[section.to_sym] = IO.read(file)
      end

      def cache_filename(section)
        @cache_filename[section.to_sym] ||=
          self.class.find_file(erb_file_for(section))
      end

      def set_ivars
        options.each do |k, v|
          instance_variable_set("@#{k}", v)
        end
      end

      def add_options(opts = nil)
        return(yield) if opts.nil? && block_given?
        cur_opts = options if block_given?

        self.options = options.merge(opts)

        if block_given?
          value = yield
          self.options = cur_opts
          value
        end
      end

      def with_section
        sect = section
        value = yield
        self.section = sect
        value
      end
    end
  end
end
yard-0.9.37/lib/yard/templates/template_options.rb000066400000000000000000000071301466601756300222060ustar00rootroot00000000000000# frozen_string_literal: true

module YARD
  module Templates
    # An Options class containing default options for base template rendering. For
    # options specific to generation of HTML output, see {CLI::YardocOptions}.
    #
    # @see CLI::YardocOptions
    class TemplateOptions < YARD::Options
      # @return [Symbol] the template output format
      default_attr :format, :text

      # @return [Symbol] the template name used to render output
      default_attr :template, :default

      # @return [Symbol] the markup format to use when parsing docstrings
      default_attr :markup, :rdoc # default is :rdoc but falls back on :none

      # @return [String] the default return type for a method with no return tags
      default_attr :default_return, "Object"

      # @return [Boolean] whether void methods should show "void" in their signature
      default_attr :hide_void_return, false

      # @return [Boolean] whether code blocks should be syntax highlighted
      default_attr :highlight, true

      # @return [Class] the markup provider class for the markup format
      attr_accessor :markup_provider

      # @return [OpenStruct] an open struct containing any global state across all
      #   generated objects in a template.
      default_attr :globals, lambda { OpenStruct.new }
      alias __globals globals

      # @return [CodeObjects::Base] the main object being generated in the template
      attr_accessor :object

      # @return [CodeObjects::Base] the owner of the generated object
      attr_accessor :owner

      # @return [Symbol] the template type used to generate output
      attr_accessor :type

      # @return [Boolean] whether serialization should be performed
      default_attr :serialize, true

      # @return [Serializers::Base] the serializer used to generate links and serialize
      #   output. Serialization output only occurs if {#serialize} is +true+.
      attr_accessor :serializer

      # @deprecated use {#highlight} instead.
      # @return [Boolean] whether highlighting should be ignored
      attr_reader :no_highlight
      undef no_highlight
      def no_highlight; !highlight end
      def no_highlight=(value) self.highlight = !value end

      # @return [String] the title of a given page
      attr_accessor :page_title

      # @return [Boolean] whether the page is the "index"
      attr_accessor :index

      # @example A list of mixin path names (including wildcards)
      #   opts.embed_mixins #=> ['ClassMethods', '*Helper', 'YARD::*']
      # @return [Array] an array of module name wildcards to embed into
      #   class documentation as if their methods were defined directly in the class.
      #   Useful for modules like ClassMethods. If the name contains '::', the module
      #   is matched against the full mixin path, otherwise only the module name is used.
      default_attr :embed_mixins, lambda { [] }

      # @param [CodeObjects::Base] mixin accepts any code object, but returns
      #   nil unless the object is a module.
      # @return [Boolean] whether a mixin matches the embed_mixins list
      # @return [nil] if the mixin is not a module object
      def embed_mixins_match?(mixin)
        return true if mixin == object # the method is not inherited
        return nil unless mixin.is_a?(CodeObjects::ModuleObject)
        embed_mixins.any? do |embed_mixin|
          re = /\A#{Regexp.quote(embed_mixin).gsub('\*', '.*')}\Z/
          matchstr = embed_mixin.include?("::") ? mixin.path : mixin.name
          re.match(matchstr.to_s)
        end
      end

      # @return [Verifier] the verifier object
      attr_accessor :verifier
    end
  end
end
yard-0.9.37/lib/yard/verifier.rb000066400000000000000000000115311466601756300164350ustar00rootroot00000000000000# frozen_string_literal: true
module YARD
  # Similar to a Proc, but runs a set of Ruby expressions using a small
  # DSL to make tag lookups easier.
  #
  # The syntax is as follows:
  # * All syntax is Ruby compatible
  # * +object+ (+o+ for short) exist to access the object being verified
  # * +@TAGNAME+ is translated into +object.tag('TAGNAME')+
  # * +@@TAGNAME+ is translated into +object.tags('TAGNAME')+
  # * +object+ can be omitted as target for method calls (it is implied)
  #
  # @example Create a verifier to check for objects that don't have @private tags
  #   verifier = Verifier.new('!@private')
  #   verifier.call(object) # => true (no @private tag)
  # @example Create a verifier to find any return tag with an empty description
  #   Verifier.new('@return.text.empty?')
  #   # Equivalent to:
  #   Verifier.new('object.tag(:return).text.empty?')
  # @example Check if there are any @param tags
  #   Verifier.new('@@param.empty?')
  #   # Equivalent to:
  #   Verifier.new('object.tags(:param).empty?')
  # @example Using +object+ or +o+ to look up object attributes directly
  #   Verifier.new('object.docstring == "hello world"')
  #   # Equivalent to:
  #   Verifier.new('o.docstring == "hello world"')
  # @example Without using +object+ or +o+
  #   Verifier.new('tag(:return).size == 1 || has_tag?(:author)')
  # @example Specifying multiple expressions
  #   Verifier.new('@return', '@param', '@yield')
  #   # Equivalent to:
  #   Verifier.new('@return && @param && @yield')
  class Verifier
    # @return [Array] a list of all expressions the verifier checks for
    # @since 0.5.6
    attr_reader :expressions

    def expressions=(value)
      @expressions = value
      create_method_from_expressions
    end

    # Creates a verifier from a set of expressions
    #
    # @param [Array] expressions a list of Ruby expressions to
    #   parse.
    def initialize(*expressions)
      @expressions = []
      add_expressions(*expressions)
    end

    # Adds a set of expressions and recompiles the verifier
    #
    # @param [Array] expressions a list of expressions
    # @return [void]
    # @since 0.5.6
    def add_expressions(*expressions)
      self.expressions += expressions.flatten
    end

    # Passes any method calls to the object from the {#call}
    def method_missing(sym, *args, &block)
      if object.respond_to?(sym)
        object.send(sym, *args, &block)
      else
        super
      end
    end

    # Tests the expressions on the object.
    #
    # @note If the object is a {CodeObjects::Proxy} the result will always be true.
    # @param [CodeObjects::Base] object the object to verify
    # @return [Boolean] the result of the expressions
    def call(object)
      return true if object.is_a?(CodeObjects::Proxy)
      modify_nilclass
      @object = object
      retval = __execute ? true : false
      unmodify_nilclass
      retval
    end

    # Runs a list of objects against the verifier and returns the subset
    # of verified objects.
    #
    # @param [Array] list a list of code objects
    # @return [Array] a list of code objects that match
    #   the verifier.
    def run(list)
      list.reject {|item| call(item).is_a?(FalseClass) }
    end

    protected

    # @return [CodeObjects::Base] the current object being tested
    attr_reader :object
    alias o object

    private

    # @private
    NILCLASS_METHODS = [:type, :method_missing]

    # Modifies nil to not throw NoMethodErrors. This allows
    # syntax like object.tag(:return).text to work if the #tag
    # call returns nil, which means users don't need to perform
    # stringent nil checking
    #
    # @return [void]
    def modify_nilclass
      NILCLASS_METHODS.each do |meth|
        NilClass.send(:define_method, meth) {|*args| }
      end
    end

    # Returns the state of NilClass back to normal
    # @return [void]
    def unmodify_nilclass
      NILCLASS_METHODS.each do |meth|
        next unless nil.respond_to?(meth)
        NilClass.send(:remove_method, meth)
      end
    end

    # Creates the +__execute+ method by evaluating the expressions
    # as Ruby code
    # @return [void]
    def create_method_from_expressions
      expr = expressions.map {|e| "(#{parse_expression(e)})" }.join(" && ")

      instance_eval(<<-eof, __FILE__, __LINE__ + 1)
        begin; undef __execute; rescue NameError; end
        def __execute; #{expr}; end
      eof
    end

    # Parses a single expression, handling some of the DSL syntax.
    #
    # The syntax "@tag" should be turned into object.tag(:tag),
    # and "@@tag" should be turned into object.tags(:tag)
    #
    # @return [String] the parsed expression
    def parse_expression(expr)
      expr = expr.gsub(/@@(?:(\w+)|\{([\w\.]+)\})/, 'object.tags("\1\2")')
      expr = expr.gsub(/@(?:(\w+)|\{([\w\.]+)\})/, 'object.tag("\1\2")')
      expr
    end
  end
end
yard-0.9.37/lib/yard/version.rb000066400000000000000000000001051466601756300163020ustar00rootroot00000000000000
# frozen_string_literal: true

module YARD
  VERSION = '0.9.37'
end
yard-0.9.37/po/000077500000000000000000000000001466601756300132055ustar00rootroot00000000000000yard-0.9.37/po/ja.po000066400000000000000000044053231466601756300141520ustar00rootroot00000000000000# Japanese translations for PACKAGE package.
# Copyright (C) 2011 THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
#  , 2011.
#
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2011-11-20 22:17+0900\n"
"PO-Revision-Date: 2012-06-20 16:56+0900\n"
"Last-Translator:  \n"
"Language-Team: Japanese\n"
"Language: ja\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Plural-Forms: nplurals=1; plural=0;\n"

#: ../README.md:1
msgid ""
"YARD: Yay! A Ruby Documentation Tool\n"
"===================================="
msgstr ""
"YARD: Yay! A Ruby Documentation Tool\n"
"===================================="

#: ../README.md:4
msgid ""
"**Homepage**:     [http://yardoc.org](http://yardoc.org)   \n"
"**IRC**:          [irc.freenode.net / #yard](irc://irc.freenode.net/"
"yard)    \n"
"**Git**:          [http://github.com/lsegal/yard](http://github.com/lsegal/"
"yard)   \n"
"**Author**:       Loren Segal  \n"
"**Contributors**: See Contributors section below    \n"
"**Copyright**:    2007-2012    \n"
"**License**:      MIT License    \n"
"**Latest Version**: 0.8.2.1 (codename \"Shave It\")    \n"
"**Release Date**: June 10th 2012"
msgstr ""
"**Homepage**:     [http://yardoc.org](http://yardoc.org)   \n"
"**IRC**:          [irc.freenode.net / #yard](irc://irc.freenode.net/yard)    \n"
"**Git**:          [http://github.com/lsegal/yard](http://github.com/lsegal/yard)   \n"
"**Author**:       Loren Segal  \n"
"**Contributors**: See Contributors section below    \n"
"**Copyright**:    2007-2012    \n"
"**License**:      MIT License    \n"
"**Latest Version**: 0.8.2.1 (codename \"Shave It\")    \n"
"**Release Date**: June 10th 2012"

#: ../README.md:14
msgid ""
"Synopsis\n"
"--------"
msgstr ""
"概要\n"
"--------"

#: ../README.md:17
msgid ""
"YARD is a documentation generation tool for the Ruby programming language.\n"
"It enables the user to generate consistent, usable documentation that can "
"be\n"
"exported to a number of formats very easily, and also supports extending "
"for\n"
"custom Ruby constructs such as custom class level definitions. Below is a\n"
"summary of some of YARD's notable features."
msgstr ""
"YARDはプログミング言語Rubyのドキュメント生成ツールである。\n"
"ユーザーが一貫性のあるドキュメント作成を可能にし、\n"
"いくつかの書式へ簡単にエキスポートできる。\n"
"又、カスタム定義によってRubyのカスタム構文用に\n"
"拡張することをサポートもする。\n"
"下はYARDの著名な機能の要約となる。"

#: ../README.md:24
msgid ""
"Feature List\n"
"------------"
msgstr ""
"機能リスト\n"
"------------"

#: ../README.md:27
msgid ""
"**1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be "
"compatible\n"
"with RDoc formatting. In fact, YARD does no processing on RDoc "
"documentation\n"
"strings, and leaves this up to the output generation tool to decide how to\n"
"render the documentation."
msgstr ""
"** 1. RDoc/SimpleMarkup書式との両立**: YARDはRDocの書式と両立する。\n"
"実際には、YARDはRDocドキュメント文字列の処理を行わない。\n"
"それは、後でドキュメント作成を表示する方法を選択する為、\n"
"その文字列を残している。"

#: ../README.md:32
msgid ""
"**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other "
"languages**:\n"
"YARD uses a '@tag' style definition syntax for meta tags alongside  regular "
"code\n"
"documentation. These tags should be able to happily sit side by side RDoc "
"formatted\n"
"documentation, but provide a much more consistent and usable way to "
"describe\n"
"important information about objects, such as what parameters they take and "
"what types\n"
"they are expected to be, what type a method should return, what exceptions "
"it can\n"
"raise, if it is deprecated, etc.. It also allows information to be better "
"(and more\n"
"consistently) organized during the output generation phase. You can find a "
"list\n"
"of tags in the {file:docs/Tags.md#taglist Tags.md} file."
msgstr ""
"** 2. Python, Java, Objective-Cや他の言語のようなYardocのメタタグフォーマット **:\n"
"YARDは通常のコードのドキュメントの側にメタタグ用の'@tag'スタイルの定義構文を使う\n"
"これらのタグは幸いなことにRDoc形式にフォーマットされたドキュメントと並んで配置する事ができる\n"
"しかしオブジェクトについて重要な情報を提供する為に更に一貫して便利な方法を提供する。\n"
"それらの何らかのパラメーターとそれらの何らかの期待される型を取得するには、\n"
"どの型のメソッドを返さなければならないか、\n"
"どの例外を上げることができるか、\n"
"もしそれが重複した場合は,, etc..\n"
"それは出力生成段階の間によりよく(そして一貫して)整理された情報を受け入れる\n"
"{file:docs/Tags.md#taglist Tags.md} ファイルでタグのリストについて紹介している。"

#: ../README.md:42
msgid ""
"YARD also supports an optional \"types\" declarations for certain tags.\n"
"This allows the developer to document type signatures for ruby methods and\n"
"parameters in a non intrusive but helpful and consistent manner. Instead of\n"
"describing this data in the body of the description, a developer may "
"formally\n"
"declare the parameter or return type(s) in a single line. Consider the\n"
"following method documented with YARD formatting:"
msgstr ""
"YARDは特定のタグを用い省略可能な\"型\"の宣言をサポートもする。\n"
"これにより開発者はRubyメソッド用や、\n"
"煩わしくなく、しかし役に立つパラメータや、\n"
"一貫性のある形式を型の用法として記述可能になる。\n"
"説明の中にこのデータを記述する代わりに、\n"
"開発者は、1つの行の中でパラメータやリターンタイプを形式的に宣言できる。\n"
"YARDの書式を使用した次のメソッドの記述を考えてみる。"

#: ../README.md:49
msgid ""
"     # Reverses the contents of a String or IO object.\n"
"     #\n"
"     # @param [String, #read] contents the contents to reverse\n"
"     # @return [String] the contents reversed lexically\n"
"     def reverse(contents)\n"
"       contents = contents.read if respond_to? :read\n"
"       contents.reverse\n"
"     end"
msgstr ""
"     # 文字列やIOオブジェクトの内容を逆にする\n"
"     #\n"
"     # @param [String, #read] 逆にするためのコンテンツを入れる\n"
"     # @return [String] 逆になった単語のコンテンツ\n"
"     def reverse(contents)\n"
"       contents = contents.read if respond_to? :read\n"
"       contents.reverse\n"
"     end"

#: ../README.md:58
msgid ""
"With the above @param tag, we learn that the contents parameter can either "
"be\n"
"a String or any object that responds to the 'read' method, which is more\n"
"powerful than the textual description, which says it should be an IO "
"object.\n"
"This also informs the developer that they should expect to receive a String\n"
"object returned by the method, and although this may be obvious for a\n"
"'reverse' method, it becomes very useful when the method name may not be as\n"
"descriptive."
msgstr ""
"上記の@paramタグによって、contentsのパラメータが\n"
"Stringまたは何らかのオブジェクトのいずれかを\n"
"'read'メソッドに返すことが分かる。\n"
"それは原文の説明よりももっと強力な\n"
"IOオブジェクトになると言える。\n"
"これは開発者達がメソッドによって返された、\n"
"Stringオブジェクトを受け取ることを期待することや、\n"
"この場合は\"reverse\"メソッドの目的が明らかとはいえ、\n"
"メソッド名が説明を含んでいない時にとても便利という事を\n"
"意味している。"

#: ../README.md:66
msgid ""
"**3. Custom Constructs and Extensibility of YARD**: YARD is designed to be\n"
"extended and customized by plugins. Take for instance the scenario where "
"you\n"
"need to document the following code:"
msgstr ""
"** 3. YARDのカスタムコンストラクタと拡張性 **: YARDは\n"
"プラグインによって拡張やカスタマイズする為に設計されている。\n"
"例えばあなたが次のコードのドキュメントの場所を必要とするシナリオを考える。"

#: ../README.md:70
msgid ""
"    class List\n"
"      # Sets the publisher name for the list.\n"
"      cattr_accessor :publisher\n"
"    end"
msgstr ""
"    class List\n"
"      # リスト用の発行者名を設定する\n"
"      cattr_accessor :publisher\n"
"    end"

#: ../README.md:75
msgid ""
"This custom declaration provides dynamically generated code that is hard for "
"a\n"
"documentation tool to properly document without help from the developer. To\n"
"ease the pains of manually documenting the procedure, YARD can be extended "
"by\n"
"the developer to handle the `cattr_accessor` construct and automatically "
"create\n"
"an attribute on the class with the associated documentation. This makes\n"
"documenting external API's, especially dynamic ones, a lot more consistent "
"for\n"
"consumption by the users."
msgstr ""
"このカスタム宣言は動的に生成されるコードを提供する。\n"
"それは開発者からの助けなしで正確なドキュメントを\n"
"ドキュメント作成ツールで作るのが困難な為である。\n"
"手書きでドキュメント作成する苦労が楽になるように、\n"
"YARDは `cattr_accessor` コンストラクタを操作する。\n"
"又、関連するドキュメントとクラスの属性を自動的に生成するように、\n"
"開発者によって拡張できる。\n"
"この拡張によって、ユーザーによって使用する多くの一貫性のある動的な\n"
"ドキュメント作成の外部のAPIを作れる。"

#: ../README.md:83
msgid ""
"YARD is also designed for extensibility everywhere else, allowing you to "
"add\n"
"support for new programming languages, new data structures and even where/"
"how\n"
"data is stored."
msgstr ""
"YARDはどこでも拡張できるように設計されている。\n"
"新しいプログラム言語や新しいデータ構造や\n"
"どこにどのようにデータを格納するかといったサポートを追加できる。"

#: ../README.md:87
msgid ""
"**4. Raw Data Output**: YARD also outputs documented objects as raw data "
"(the\n"
"dumped Namespace) which can be reloaded to do generation at a later date, "
"or\n"
"even auditing on code. This means that any developer can use the raw data "
"to\n"
"perform output generation for any custom format, such as YAML, for "
"instance.\n"
"While YARD plans to support XHTML style documentation output as well as\n"
"command line (text based) and possibly XML, this may still be useful for "
"those\n"
"who would like to reap the benefits of YARD's processing in other forms, "
"such\n"
"as throwing all the documentation into a database. Another useful way of\n"
"exploiting this raw data format would be to write tools that can auto "
"generate\n"
"test cases, for example, or show possible unhandled exceptions in code."
msgstr ""
"**4. 未加工データの出力**: YARDはオブジェクトのドキュメントを未加工のままデー"
"タ(ダンプした名前空間)出力する。後で生成する時や、コードを等しく調査する時は"
"再ロードされる。\n"
"つまり、開発者の誰もが何らかのカスタム書式のように出力生成を実行する為に、未"
"加工データを使う。例えば、YAMLのように。\n"
"YARDはXHTMLスタイルドキュメント出力もコマンドライン(テキストベース)も\n"
"(もしかしたらXMLも)サポートを計画しているので、\n"
"全てのドキュメントをデータベースへ投げておけば、\n"
"将来、他の型でもYARDの処理の恩恵を受けようと考えている人にとっては、\n"
"役立つかもしれない。\n"
"この未加工データの書式を利用する他の有用な方法として、\n"
"自動生成テストケースができるツールを書く為や、\n"
"コードの未処理例外を明らかにすること、などがある。"

#: ../README.md:98
msgid ""
"**5. Local Documentation Server**: YARD can serve documentation for "
"projects\n"
"or installed gems (similar to `gem server`) with the added benefit of "
"dynamic\n"
"searching, as well as live reloading. Using the live reload feature, you "
"can\n"
"document your code and immediately preview the results by refreshing the "
"page;\n"
"YARD will do all the work in re-generating the HTML. This makes writing\n"
"documentation a much faster process."
msgstr ""
"**5. ローカルドキュメントサーバー**:\n"
"YARDは動的な検索も再ロードの利点も用い\n"
"プロジェクトやインストール済みのgem( `gem server` と同様)用のドキュメント作成を提供する。\n"
"live reload機能によって,あなたのコードを記述したり\n"
"ページをリフレーシュする事によって結果をすぐにプレビューできる\n"
"YARDはHTML再生成の全ての仕事をする\n"
"これによりドキュメントの作成をより高速のプロセスで行える。"

#: ../README.md:106
msgid "## Installing"
msgstr "## インストール"

#: ../README.md:108
msgid "To install YARD, use the following command:"
msgstr "YARDをインストールする為に次のコマンドを使う。"

#: ../README.md:110
msgid "    $ gem install yard"
msgstr "    $ gem install yard"

#: ../README.md:112
msgid "(Add `sudo` if you're installing under a POSIX system as root)"
msgstr ""
"(もしPOSIXシステムのルート下でインストールしている場合、sudoを追加する)"

#: ../README.md:114
msgid ""
"Alternatively, if you've checked the source out directly, you can call\n"
"`rake install` from the root project directory."
msgstr ""
"上のコマンドの代わりに、もしソースを直接チェックアウトしたならば、\n"
"あなたはプロジェクトのルートディレクトリから `rake install` を行う事ができる"

#: ../README.md:117
msgid ""
"**Important Note for Debian/Ubuntu users:** there's a possible chance your "
"Ruby\n"
"install lacks RDoc, which is occasionally used by YARD to convert markup to "
"HTML.\n"
"If running `which rdoc` turns up empty, install RDoc by issuing:"
msgstr ""
"**Debian/Ubuntuユーザーへの重要な注意:**\n"
"RubyがRDocなしでinstallされる可能性がある。\n"
"RDocはYARDによってマークアップをHTMLに変換する為に時々使われるので、\n"
"もし `which rdoc` コマンドでパスが存在しない場合は、次のコマンドでRDocをインストールする。"

#: ../README.md:121
msgid "    $ sudo apt-get install rdoc"
msgstr "    $ sudo apt-get install rdoc"

# YARD::CLI::Yardoc
#: ../README.md:124
msgid "## Usage"
msgstr "## 使用法"

#: ../README.md:126
msgid ""
"There are a couple of ways to use YARD. The first is via command-line, and "
"the\n"
"second is the Rake task."
msgstr ""
"それらYARDを使うにはいくつかの方法がある。\n"
"最初はコマンドライン経由で、もうひとつはRake taskという方法がある。"

#: ../README.md:129
msgid "**1. yard Command-line Tool**"
msgstr "**1. yardのコマンドラインツール**"

#: ../README.md:131
msgid ""
"YARD comes packaged with a executable named `yard` which can control the "
"many\n"
"functions of YARD, including generating documentation, graphs running the\n"
"YARD server, and so on. To view a list of available YARD commands, type:"
msgstr ""
"YARDは実行可能な `yard` という名前と一緒にパッケージが入っている。\n"
"ドキュメントの生成や、グラフ、YARDサーバーを起動などを含み\n"
"たくさんの機能を制御できる。\n"
"利用可能なYARDのコマンドの一覧を表示するには、以下をタイプする。"

#: ../README.md:135
msgid "    $ yard --help"
msgstr "    $ yard --help"

#: ../README.md:137
msgid ""
"Plugins can also add commands to the `yard` executable to provide extra\n"
"functionality."
msgstr "プラグインは追加の機能を提供する為に実行可能な `yard` コマンドを追加できる。"

#: ../README.md:140
msgid "### Generating Documentation"
msgstr "### ドキュメントを生成する"

#: ../README.md:142
msgid ""
"The `yardoc` executable is a shortcut for `yard doc`."
msgstr "The `yardoc` executable is a shortcut for `yard doc`."

#: ../README.md:144
msgid ""
"The most common command you will probably use is `yard doc`, or `yardoc`. "
"You\n"
"can type `yardoc --help` to see the options that YARD provides, but the\n"
"easiest way to generate docs for your code is to simply type `yardoc` in "
"your\n"
"project root. This will assume your files are\n"
"located in the `lib/` directory. If they are located elsewhere, you can "
"specify\n"
"paths and globs from the commandline via:"
msgstr ""
"恐らく最も使用される一般的なコマンドは `yard doc` 、または `yardoc` となるだろう。\n"
"YARDが提供するオプションを見るには `yardoc --help` をタイプする事で表示できる。\n"
"でも、ドキュメントを生成するのに最も簡単な方法は、\n"
"あなたのプロジェクトのルートで `yardoc` をタイプする方法である。\n"
"これはあなたのファイルが `lib/` ディレクトリの中で示されるとみなす。\n"
"もし他の場所にあるなら、次のようにコマンドラインからパスとglobを指定する:"

#: ../README.md:151
msgid "    $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc..."
msgstr "    $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc..."

#: ../README.md:153
msgid ""
"The tool will generate a `.yardoc` file which will store the cached "
"database\n"
"of your source code and documentation. If you want to re-generate your docs\n"
"with another template you can simply use the `--use-cache` (or -c)\n"
"option to speed up the generation process by skipping source parsing."
msgstr ""
"このツールは `.yardoc` ファイルを生成する。それは\n"
"あなたのソースコードとドキュメントをキャッシュしたデータベースを格納する。\n"
"もしあなたが他のテンプレートと共にドキュメントを再生成したいなら、\n"
"単に `--use-cache` (or -c) オプションを使えばよい。\n"
"ソースの解析をスキップする事によって生成プロセスをスピードアップする。"

#: ../README.md:158
msgid ""
"YARD will by default only document code in your public visibility. You can\n"
"document your protected and private code by adding `--protected` or\n"
"`--private` to the option switches. In addition, you can add `--no-private`\n"
"to also ignore any object that has the `@private` meta-tag. This is similar\n"
"to RDoc's \":nodoc:\" behaviour, though the distinction is important. RDoc\n"
"implies that the object with :nodoc: would not be documented, whereas\n"
"YARD still recommends documenting private objects for the private API (for\n"
"maintainer/developer consumption)."
msgstr ""
"YARDはデフォルトでpublicな可視性の中のコードだけを記述する。\n"
"`--protected` や `--private` オプション引数の追加によって\n"
"protectedとprivateなコードを記録できる。\n"
"さらに、 `--no-private` の追加によって、\n"
"`@private` メタタグを持った何らかのオブジェクトの無視もできる。\n"
"区別は重要であるものの、これはRDocの\":nodoc:\"の挙動と似ている。\n"
"RDocはオブジェクトと共に:nodoc:は記録されないことを暗示する。\n"
"ところが、YARDは今もなおprivate APIの為に\n"
"privateなオブジェクトのドキュメント作成を\n"
"推奨する。(メンテナーや開発者が利用する為に)"

#: ../README.md:167
msgid ""
"You can also add extra informative files (README, LICENSE) by separating\n"
"the globs and the filenames with '-'."
msgstr ""
"globとファイル名と共に'-'で区切ることによって、\n"
"追加の情報ファイル(README, LICENSE)を追加もできる。"

#: ../README.md:170
msgid "    $ yardoc 'app/**/*.rb' - README LICENSE FAQ"
msgstr "    $ yardoc 'app/**/*.rb' - README LICENSE FAQ"

#: ../README.md:172
msgid ""
"If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is\n"
"used:"
msgstr "もしglob無しで、'-'引数が先行する場合、デフォルトのglobは( `lib/**/*.rb` )を使う。"

#: ../README.md:175
msgid "    $ yardoc - README LICENSE FAQ"
msgstr "    $ yardoc - README LICENSE FAQ"

#: ../README.md:177
msgid ""
"Note that the README file can be specified with its own `--readme` switch."
msgstr ""
"次の事に留意する。READMEファイルは自身の`--readme`引数と共に指定される。"

#: ../README.md:179
msgid ""
"You can also add a `.yardopts` file to your project directory which lists\n"
"the switches separated by whitespace (newlines or space) to pass to yardoc\n"
"whenever it is run. A full overview of the `.yardopts` file can be found in\n"
"{YARD::CLI::Yardoc}."
msgstr ""
"あなたはあなたのプロジェクトディレクトリに `.yardopts` を追加することもできる。\n"
"これは起動する時に毎回、スペースによって区切られた引数のリストをyardocに渡す。\n"
" `.yardopts` ファイルの全ての概要は、 {YARD::CLI::Yardoc} で見つけることができる。"

#: ../README.md:184
msgid "### Queries"
msgstr "### クエリー"

#: ../README.md:186
msgid ""
"The `yardoc` tool also supports a `--query` argument to only include "
"objects\n"
"that match a certain data or meta-data query. The query syntax is Ruby, "
"though\n"
"a few shortcuts are available. For instance, to document only objects that "
"have\n"
"an \"@api\" tag with the value \"public\", all of the following syntaxes "
"would give\n"
"the same result:"
msgstr ""
"`yardoc` ツールは、 `--query` 引数をサポートもする。\n"
"これはマッチするいくらかのデータやメタデータクエリーのオブジェクトだけ含んでいる。\n"
"クエリーの構文はRubyで、いくつかのショートカットが利用可能。\n"
"例えば、\"@api\"タグと\"public\"な値を持つオブジェクトだけを記述するには、\n"
"次のようになる。(全て同じ結果となる。)"

#: ../README.md:192
msgid ""
"    --query '@api.text == \"public\"'\n"
"    --query 'object.has_tag?(:api) && object.tag(:api).text == \"public\"'\n"
"    --query 'has_tag?(:api) && tag(:api).text == \"public\"'"
msgstr ""
"    --query '@api.text == \"public\"'\n"
"    --query 'object.has_tag?(:api) && object.tag(:api).text == \"public\"'\n"
"    --query 'has_tag?(:api) && tag(:api).text == \"public\"'"

#: ../README.md:196
msgid ""
"Note that the \"@tag\" syntax returns the first tag named \"tag\" on the "
"object.\n"
"To return the array of all tags named \"tag\", use \"@@tag\"."
msgstr ""
"次の事に留意する。\n"
"\"@tag\"構文は、オブジェクトの最初に\"tag\"と名付けられたタグを返す。\n"
"全ての\"tag\"と名付けたタグの配列を返すには、\"@@tag\"を使う。"

#: ../README.md:199
msgid ""
"Multiple `--query` arguments are allowed in the command line parameters. "
"The\n"
"following two lines both check for the existence of a return and param tag:"
msgstr ""
"複数の`--query`引数はコマンドライン引数の中で許可される。\n"
"次の2行は両方とも実際の返り値とparamタグをチェックする。"

#: ../README.md:202
msgid ""
"    --query '@return' --query '@param'\n"
"    --query '@return && @param'"
msgstr ""
"    --query '@return' --query '@param'\n"
"    --query '@return && @param'"

#: ../README.md:205
msgid ""
"For more information about the query syntax, see the {YARD::Verifier} class."
msgstr "さらなるquery構文の情報については、 {YARD::Verifier} クラスを参照する。"

#: ../README.md:207
msgid "**2. Rake Task**"
msgstr "**2. Rake Task**"

#: ../README.md:209
msgid ""
"The second most obvious is to generate docs via a Rake task. You can do this "
"by\n"
"adding the following to your `Rakefile`:"
msgstr ""
"もう一つの方法として、Rakeのタスクを介してドキュメントを生成する。\n"
"あなたの `Rakefile` に次の内容を追加することによって作成できる:"

#: ../README.md:212
msgid ""
"    YARD::Rake::YardocTask.new do |t|\n"
"      t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional\n"
"      t.options = ['--any', '--extra', '--opts'] # optional\n"
"    end"
msgstr ""
"    YARD::Rake::YardocTask.new do |t|\n"
"      t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional\n"
"      t.options = ['--any', '--extra', '--opts'] # optional\n"
"    end"

#: ../README.md:217
msgid ""
"both the `files` and `options` settings are optional. `files` will default "
"to\n"
"`lib/**/*.rb` and `options` will represents any options you might want\n"
"to add. Again, a full list of options is available by typing `yardoc --"
"help`\n"
"in a shell. You can also override the options at the Rake command-line with "
"the\n"
"OPTS environment variable:"
msgstr ""
"`files` も `options` の設定も、省略可能。\n"
"`files` は `lib/**/*.rb` にデフォルトで設定される、\n"
"そして `options` は追加したいオプションを表している。\n"
"さらに、オプションの全てのリストは、\n"
"シェルで `yardoc --help` を\n"
"タイプすることによって利用可能。又、\n"
"RakeコマンドラインとOPTS環境変数でoptionsを上書きできる。"

#: ../README.md:223
msgid "    $ rake yard OPTS='--any --extra --opts'"
msgstr "    $ rake yard OPTS='--any --extra --opts'"

#: ../README.md:225
msgid "**3. `yri` RI Implementation**"
msgstr "**3. `yri` RIの実装**"

#: ../README.md:227
msgid ""
"The yri binary will use the cached .yardoc database to give you quick ri-"
"style\n"
"access to your documentation. It's way faster than ri but currently does "
"not\n"
"work with the stdlib or core Ruby libraries, only the active project. "
"Example:"
msgstr ""
"yriコマンドはドキュメントをri-styleで速くアクセスする為に、\n"
"キャッシュした.yardocデータベースを使うだろう。\n"
"これはriよりも速い方法だが、しかし、今の所、\n"
"stdlibかコアRubyライブラリ、アクティブプロジェクトだけでしか\n"
"動かない。\n"
"使用例:"

#: ../README.md:231
msgid ""
"    $ yri YARD::Handlers::Base#register\n"
"    $ yri File.relative_path"
msgstr ""
"    $ yri YARD::Handlers::Base#register\n"
"    $ yri File.relative_path"

#: ../README.md:234
msgid ""
"Note that class methods must not be referred to with the \"::\" namespace\n"
"separator. Only modules, classes and constants should use \"::\"."
msgstr ""
"次の事に留意する。\n"
"クラスメソッドは、\"::\"ネームスペース区切りとともに参照されるべきではない。\n"
"モジュールだけクラスと定数は\"::\"を使うべきである。"

#: ../README.md:237
msgid ""
"You can also do lookups on any installed gems. Just make sure to build the\n"
".yardoc databases for installed gems with:"
msgstr ""
"あなたはインストール済みの任意のgemを検索できる。\n"
"以下はインストール済みのgemとともに.yardocデータベースをビルドする。"

#: ../README.md:240
msgid "    $ sudo yard gems"
msgstr "    $ sudo yard gems"

#: ../README.md:242
msgid ""
"If you don't have sudo access, it will write these files to your `~/.yard`\n"
"directory. `yri` will also cache lookups there."
msgstr ""
"sudo権限をもっていない場合は、あなたの `~/.yard` ディレクトリにこれらを記述する。\n"
" `yri` はそれらをcache検索する。"

#: ../README.md:245
msgid "**4. `yard server` Documentation Server**"
msgstr "**4. `yard server` ドキュメント作成サーバー**"

#: ../README.md:247
msgid ""
"The `yard server` command serves documentation for a local project or all "
"installed\n"
"RubyGems. To serve documentation for a project you are working on, simply "
"run:"
msgstr ""
"`yard server` コマンドは、\n"
"ローカルプロジェクトやインストール済みのRubyGems用の\n"
"ドキュメント作成を提供する。\n"
"ドキュメント作成を提供するには、\n"
"あなたが取り組んでいるプロジェクト上で次のコマンドを単に実行する。"

#: ../README.md:250 ../docs/WhatsNew.md:542
msgid "    $ yard server"
msgstr "    $ yard server"

#: ../README.md:252
msgid ""
"And the project inside the current directory will be parsed (if the source "
"has\n"
"not yet been scanned by YARD) and served at [http://localhost:8808](http://"
"localhost:8808)."
msgstr ""
"上のコマンドによってプロジェクトの現在のディレクトリ内部は解析される。\n"
"(YARDによってスキャンされたにもかかわらずソースがなかった場合)\n"
"そして [http://localhost:8808](http://localhost:8808) で提供される。"

#: ../README.md:255
msgid "### Live Reloading"
msgstr "### Live Reloading"

#: ../README.md:257
msgid ""
"If you want to serve documentation on a project while you document it so "
"that\n"
"you can preview the results, simply pass `--reload` (`-r`) to the above "
"command\n"
"and YARD will reload any changed files on each request. This will allow you "
"to\n"
"change any documentation in the source and refresh to see the new contents."
msgstr ""
"結果をプレビューできるようにドキュメント化しながら、\n"
"プロジェクトのドキュメント作成を提供したいなら、\n"
"上のコマンドに単純に `--reload` (`-r`)を渡す。\n"
"YARDはそれぞれのリクエストのどれかの変更があったファイルを再ロードする。\n"
"これはあなたがソースの中のドキュメントの変更や\n"
"新しいコンテンツを見るのにリフレッシュを可能にする。"

#: ../README.md:262
msgid "### Serving Gems"
msgstr "### Serving Gems"

#: ../README.md:264
msgid "To serve documentation for all installed gems, call:"
msgstr ""
"全てのインストール済みのgemのドキュメント作成を提供するには、\n"
"次のコマンドを入力する。"

#: ../README.md:266 ../docs/WhatsNew.md:562
msgid "    $ yard server --gems"
msgstr "    $ yard server --gems"

#: ../README.md:268
msgid ""
"This will also automatically build documentation for any gems that have not\n"
"been previously scanned. Note that in this case there will be a slight "
"delay\n"
"between the first request of a newly parsed gem."
msgstr ""
"これは自動的に以前にスキャンされていないあらゆるgemのドキュメントをビルドす"
"る。\n"
"次の事に留意する。\n"
"この場合、新たに解析されたgemの最初の要求の間にわずかな遅延が発生する。"

#: ../README.md:273
msgid "**5. `yard graph` Graphviz Generator**"
msgstr "**5. `yard graph` はGraphvizのジェネレーター**"

#: ../README.md:275
msgid ""
"You can use `yard graph` to generate dot graphs of your code. This, of "
"course,\n"
"requires [Graphviz](http://www.graphviz.org) and the `dot` binary. By "
"default\n"
"this will generate a graph of the classes and modules in the best UML2 "
"notation\n"
"that Graphviz can support, but without any methods listed. With the `--"
"full`\n"
"option, methods and attributes will be listed. There is also a `--"
"dependencies`\n"
"option to show mixin inclusions. You can output to stdout or a file, or pipe "
"directly\n"
"to `dot`. The same public, protected and private visibility rules apply to "
"`yard graph`.\n"
"More options can be seen by typing `yard graph --help`, but here is an "
"example:"
msgstr ""
"あなたのコードの図を生成する為に `yard graph` を利用できる。\n"
"これにはもちろん、[Graphviz](http://www.graphviz.org)と `dot` が必要となる。\n"
"デフォルトでこれは、Graphvizのサポートできる最高のURL2表記で\n"
"クラスやモジュールの図を生成する。しかし、記載されたメソッドは生成しない。\n"
"`-- full` オプションを用いメソッドと属性が記述される。\n"
"mixinで含んでいるものを一覧する為に `--dependencies` オプションもある。\n"
"標準出力やファイルに出力したり、また `dot` に直接パイプできる。\n"
"同じpublic,protectedとprivateの可視性規則は、 `yard-graph` に適用される。\n"
"詳細なオプションは、 `yard-graph --help` とタイプすることによって見ることができる。\n"
"次に例がある:"

#: ../README.md:284
msgid "    $ yard graph --protected --full --dependencies"
msgstr "    $ yard graph --protected --full --dependencies"

#: ../README.md:287
msgid "## Changelog"
msgstr "## Changelog"

#: ../README.md:289
msgid ""
"- **June.9.12**: 0.8.2.1 release\n"
"    - Fix a set of regressions in yard server search and dynamic generation"
msgstr ""
"- **June.9.12**: 0.8.2.1 release\n"
"    - Fix a set of regressions in yard server search and dynamic generation"

#: ../README.md:292
msgid ""
"- **June.7.12**: 0.8.2 release\n"
"    - Added progress style output in tty terminals\n"
"    - Embedded mixins should ignore methods defined on module (#539)\n"
"    - Fixed permalinks for embedded mixins in `yard server` (#540)\n"
"    - Improve parsing in CRuby code (#543)\n"
"    - Ensure Registry.resolve picks module when parsing mixins (#545)\n"
"    - Fixed regression that caused various commands to not show output "
"(#548)\n"
"    - Respect current visibility when parsing class conditions (#551)"
msgstr ""
"- **June.7.12**: 0.8.2 release\n"
"    - Added progress style output in tty terminals\n"
"    - Embedded mixins should ignore methods defined on module (#539)\n"
"    - Fixed permalinks for embedded mixins in `yard server` (#540)\n"
"    - Improve parsing in CRuby code (#543)\n"
"    - Ensure Registry.resolve picks module when parsing mixins (#545)\n"
"    - Fixed regression that caused various commands to not show output (#548)\n"
"    - Respect current visibility when parsing class conditions (#551)"

#: ../README.md:301
msgid ""
"- **May.2.12**: 0.8.1 release\n"
"    - Added `--[no-]api` switch to generate docs for API sets (see {file:"
"docs/WhatsNew.md} for details) (#532)\n"
"    - The `yard list` command now uses cache by default (#533)\n"
"    - Fix `yardoc` generating incorrectly named method list file (#528)\n"
"    - Fix HTML output occasionally showing trailing mdash on options list "
"(#522)"
msgstr ""
"- **May.2.12**: 0.8.1 release\n"
"    - Added `--[no-]api` switch to generate docs for API sets (see {file:docs/WhatsNew.md} for details) (#532)\n"
"    - The `yard list` command now uses cache by default (#533)\n"
"    - Fix `yardoc` generating incorrectly named method list file (#528)\n"
"    - Fix HTML output occasionally showing trailing mdash on options list (#522)"

#: ../README.md:307
msgid ""
"- **April.30.12**: 0.8.0 release\n"
"    - See {file:docs/WhatsNew.md} for a list of added features\n"
"    - Over 20 bug fixes:\n"
"      - Properly filter hidden setter/getter attributes (#394)\n"
"      - Fix test failures in Linux environments (#397, #472, #473, #512, "
"#513)\n"
"      - Fix attribute inheritance and @private (#432)\n"
"      - Fix attribute parsing (#435)\n"
"      - Allow aliases for attributes (#436)\n"
"      - Fix namespace fetching in `handle_alias()` (#437)\n"
"      - Fix overwritten attributes marked as inherited (#442)\n"
"      - Fix documenting constants defined from C code with `rb_define_const()"
"` (#443)\n"
"      - Do not escape snippets twice (#445)\n"
"      - Ajax method/class search should not fire when a non-printable "
"character is pressed (#446)\n"
"      - Fix yard server crashing when RDoc is not installed (#456)\n"
"      - Fix tags ignored when `(see #foo)` is used (#457)\n"
"      - Fix three \"Returns\" for two `@overload` tags (#458)\n"
"      - Do not auto-detect DSL methods as method objects if parameter name "
"is not a valid method name (#464)\n"
"      - Fix attaching of macros to Object (#465)\n"
"      - Fix handling of `%w()` source in `[]/[]=` parsed context. (#461, "
"pull in #468)\n"
"      - Don't add default `@return` if `@overload` has `@return`. (#458, "
"pull in #469)\n"
"      - Don't discard tags by (see ...). (#457, pull in #470)\n"
"      - Fix constants listed as inherited when overwritten (#474)\n"
"      - Fix `yardoc --asset` behaving differently on first and subsequent "
"calls. (#477)\n"
"      - `!!!lang` code blocks should set the lang in `
    `'s class. (#478, "
"#479)\n"
"      - Fix \"File List\" search tab error. (#502)\n"
"      - Fix search bar not redirecting to method page. (#509)\n"
"      - Fix server returning exception message bodies as String (#518)"
msgstr ""
"- **April.30.12**: 0.8.0 release\n"
"    - See {file:docs/WhatsNew.md} for a list of added features\n"
"    - Over 20 bug fixes:\n"
"      - Properly filter hidden setter/getter attributes (#394)\n"
"      - Fix test failures in Linux environments (#397, #472, #473, #512, #513)\n"
"      - Fix attribute inheritance and @private (#432)\n"
"      - Fix attribute parsing (#435)\n"
"      - Allow aliases for attributes (#436)\n"
"      - Fix namespace fetching in `handle_alias()` (#437)\n"
"      - Fix overwritten attributes marked as inherited (#442)\n"
"      - Fix documenting constants defined from C code with `rb_define_const()` (#443)\n"
"      - Do not escape snippets twice (#445)\n"
"      - Ajax method/class search should not fire when a non-printable character is pressed (#446)\n"
"      - Fix yard server crashing when RDoc is not installed (#456)\n"
"      - Fix tags ignored when `(see #foo)` is used (#457)\n"
"      - Fix three \"Returns\" for two `@overload` tags (#458)\n"
"      - Do not auto-detect DSL methods as method objects if parameter name is not a valid method name (#464)\n"
"      - Fix attaching of macros to Object (#465)\n"
"      - Fix handling of `%w()` source in `[]/[]=` parsed context. (#461, pull in #468)\n"
"      - Don't add default `@return` if `@overload` has `@return`. (#458, pull in #469)\n"
"      - Don't discard tags by (see ...). (#457, pull in #470)\n"
"      - Fix constants listed as inherited when overwritten (#474)\n"
"      - Fix `yardoc --asset` behaving differently on first and subsequent calls. (#477)\n"
"      - `!!!lang` code blocks should set the lang in `
    `'s class. (#478, #479)\n"
"      - Fix \"File List\" search tab error. (#502)\n"
"      - Fix search bar not redirecting to method page. (#509)\n"
"      - Fix server returning exception message bodies as String (#518)"

#: ../README.md:335
msgid ""
"- **January.31.12**: 0.7.5 release\n"
"    - Various minor bug fixes"
msgstr ""
"- **January.31.12**: 0.7.5 release\n"
"    - Various minor bug fixes"

#: ../README.md:338
msgid ""
"- **December.2.11**: 0.7.4 release\n"
"    - Redcarpet is now the default Markdown formatting library. GFM now "
"works out-of-box (#404)\n"
"    - Fix server side searching for elements that are marked private (#420)\n"
"    - Add 'textile_strict' and 'pre' markup types, reorganize text and none "
"(#416)\n"
"    - Improve encoding line detection (#415)\n"
"    - Add support for `rb_define_alias` in CRuby code (#413)\n"
"    - Fix rendering of some keywords in source view (#410)\n"
"    - Add support for RDoc 3.10+ (#406, #407)\n"
"    - Fix typewriter text being processed in code blocks (#403)\n"
"    - Improve support for has_rdoc in RubyGems 1.8.x (#401)\n"
"    - See the {file:docs/WhatsNew.md} document for details on added features"
msgstr ""
"- **December.2.11**: 0.7.4 release\n"
"    - Redcarpet is now the default Markdown formatting library. GFM now works out-of-box (#404)\n"
"    - Fix server side searching for elements that are marked private (#420)\n"
"    - Add 'textile_strict' and 'pre' markup types, reorganize text and none (#416)\n"
"    - Improve encoding line detection (#415)\n"
"    - Add support for `rb_define_alias` in CRuby code (#413)\n"
"    - Fix rendering of some keywords in source view (#410)\n"
"    - Add support for RDoc 3.10+ (#406, #407)\n"
"    - Fix typewriter text being processed in code blocks (#403)\n"
"    - Improve support for has_rdoc in RubyGems 1.8.x (#401)\n"
"    - See the {file:docs/WhatsNew.md} document for details on added features"

#: ../README.md:350
msgid ""
"- **October.15.11**: 0.7.3 release\n"
"    - Improve support for parsing under Ruby 1.9.2p290 and 1.9.3 (#365, "
"#370)\n"
"    - Add support for SWIG generated CRuby code (#369)\n"
"    - Add support for `rb_define_attr` calls in CRuby code (#362)\n"
"    - Handle file pointers in CRuby code (#358)"
msgstr ""
"- **October.15.11**: 0.7.3 release\n"
"    - Improve support for parsing under Ruby 1.9.2p290 and 1.9.3 (#365, #370)\n"
"    - Add support for SWIG generated CRuby code (#369)\n"
"    - Add support for `rb_define_attr` calls in CRuby code (#362)\n"
"    - Handle file pointers in CRuby code (#358)"

#: ../README.md:356
msgid ""
"- **June.14.11**: 0.7.2 release\n"
"    - Fix `yard --help` not showing proper output\n"
"    - YARD now expands path to `.yardoc` file in daemon mode for server "
"(#328)\n"
"    - Fix `@overload` tag linking to wrong method (#330)\n"
"    - Fix incorrect return type when using `@macro` (#334)\n"
"    - YARD now requires 'thread' to support RubyGems 1.7+ (#338)\n"
"    - Fix bug in constant documentation when using `%w()` (#348)\n"
"    - Fix YARD style URL links when using autolinking markdown (#353)"
msgstr ""
"- **June.14.11**: 0.7.2 release\n"
"    - Fix `yard --help` not showing proper output\n"
"    - YARD now expands path to `.yardoc` file in daemon mode for server (#328)\n"
"    - Fix `@overload` tag linking to wrong method (#330)\n"
"    - Fix incorrect return type when using `@macro` (#334)\n"
"    - YARD now requires 'thread' to support RubyGems 1.7+ (#338)\n"
"    - Fix bug in constant documentation when using `%w()` (#348)\n"
"    - Fix YARD style URL links when using autolinking markdown (#353)"

#: ../README.md:365
msgid ""
"- **May.18.11**: 0.7.1 release\n"
"    - Fixes a bug in `yard server` not displaying class list properly."
msgstr ""
"- **May.18.11**: 0.7.1 release\n"
"    - Fixes a bug in `yard server` not displaying class list properly."

#: ../README.md:368
msgid ""
"- **May.17.11**: 0.7.0 release\n"
"    - See the {file:docs/WhatsNew.md} document for details on added "
"features\n"
"    - Make sure that Docstring#line_range is filled when possible (#243)\n"
"    - Set #verifier in YardocTask (#282)\n"
"    - Parse BOM in UTF-8 files (#288)\n"
"    - Fix instance attributes not showing up in method list (#302)\n"
"    - Fix rendering of %w() literals in constants (#306)\n"
"    - Ignore keyboard shortcuts when an input is active (#312)\n"
"    - And more..."
msgstr ""
"- **May.17.11**: 0.7.0 release\n"
"    - See the {file:docs/WhatsNew.md} document for details on added features\n"
"    - Make sure that Docstring#line_range is filled when possible (#243)\n"
"    - Set #verifier in YardocTask (#282)\n"
"    - Parse BOM in UTF-8 files (#288)\n"
"    - Fix instance attributes not showing up in method list (#302)\n"
"    - Fix rendering of %w() literals in constants (#306)\n"
"    - Ignore keyboard shortcuts when an input is active (#312)\n"
"    - And more..."

#: ../README.md:378
msgid ""
"- **April.14.11**: 0.6.8 release\n"
"    - Fix regression in RDoc 1.x markup loading\n"
"    - Fix regression in loading of markup libraries for `yard server`"
msgstr ""
"- **April.14.11**: 0.6.8 release\n"
"    - Fix regression in RDoc 1.x markup loading\n"
"    - Fix regression in loading of markup libraries for `yard server`"

#: ../README.md:382
msgid ""
"- **April.6.11**: 0.6.7 release\n"
"    - Fix has_rdoc gem specification issue with new RubyGems plugin API "
"(oops!)"
msgstr ""
"- **April.6.11**: 0.6.7 release\n"
"    - Fix has_rdoc gem specification issue with new RubyGems plugin API (oops!)"

#: ../README.md:385
msgid ""
"- **April.6.11**: 0.6.6 release\n"
"    - Fix error message when RDoc is not present (#270)\n"
"    - Add markup type 'none' to perform basic HTML translation (fallback "
"when RDoc is not present)\n"
"    - Add support for RubyGems 1.7.x (#272)\n"
"    - Fix rendering of `{url description}` syntax when description contains "
"newline"
msgstr ""
"- **April.6.11**: 0.6.6 release\n"
"    - Fix error message when RDoc is not present (#270)\n"
"    - Add markup type 'none' to perform basic HTML translation (fallback when RDoc is not present)\n"
"    - Add support for RubyGems 1.7.x (#272)\n"
"    - Fix rendering of `{url description}` syntax when description contains newline"

#: ../README.md:391
msgid ""
"- **March.13.11**: 0.6.5 release\n"
"    - Support `ripper` gem in Ruby 1.8.7\n"
"    - Upgrade jQuery to 1.5.1\n"
"    - Fix handling of alias statements with quoted symbols (#262)\n"
"    - Add CSS styles (#260)\n"
"    - Unhandled exception in YARD::Handlers::Ruby::MixinHandler indexing "
"documentation for eventmachine (#248)\n"
"    - Splice any alias references on method re-definitions into separate "
"methods (#247)\n"
"    - Fix \"yard graph\" (#245)\n"
"    - Don't process ++ typewriter text inside of HTML attributes (#244)\n"
"    - Prioritize loading of Kramdown before Maruku (#241)\n"
"    - Skip shebang encoding in docstrings (#238)\n"
"    - Fix truncation of references in @deprecated (#232)\n"
"    - Show @api private note when no other tags are present (#231)\n"
"    - Detect docstrings starting with \"##\" as `Docstring#hash_flag` "
"(#230)\n"
"    - Remove trailing whitespace from freeform tags (#229)\n"
"    - Fix line through for deprecated methods (#225)\n"
"    - Mistake in Tags.md (#223)\n"
"    - Improve database storage by being more efficient with filesystem usage "
"(#222)\n"
"    - Make Registry thread local (#221)\n"
"    - Support `private_constant` class method for 1.9.3 (#219)\n"
"    - Do not assume RDoc is installed (#214)"
msgstr ""
"- **March.13.11**: 0.6.5 release\n"
"    - Support `ripper` gem in Ruby 1.8.7\n"
"    - Upgrade jQuery to 1.5.1\n"
"    - Fix handling of alias statements with quoted symbols (#262)\n"
"    - Add CSS styles (#260)\n"
"    - Unhandled exception in YARD::Handlers::Ruby::MixinHandler indexing documentation for eventmachine (#248)\n"
"    - Splice any alias references on method re-definitions into separate methods (#247)\n"
"    - Fix \"yard graph\" (#245)\n"
"    - Don't process ++ typewriter text inside of HTML attributes (#244)\n"
"    - Prioritize loading of Kramdown before Maruku (#241)\n"
"    - Skip shebang encoding in docstrings (#238)\n"
"    - Fix truncation of references in @deprecated (#232)\n"
"    - Show @api private note when no other tags are present (#231)\n"
"    - Detect docstrings starting with \"##\" as `Docstring#hash_flag` (#230)\n"
"    - Remove trailing whitespace from freeform tags (#229)\n"
"    - Fix line through for deprecated methods (#225)\n"
"    - Mistake in Tags.md (#223)\n"
"    - Improve database storage by being more efficient with filesystem usage (#222)\n"
"    - Make Registry thread local (#221)\n"
"    - Support `private_constant` class method for 1.9.3 (#219)\n"
"    - Do not assume RDoc is installed (#214)"

#: ../README.md:413
msgid ""
"- **December.21.10**: 0.6.4 release\n"
"    - Fix yri tool crashing with new Config class (gh-217)\n"
"    - Fix support for ::TopLevelConstants (gh-216)\n"
"    - YARD's test suite is now RSpec2 compatible (gh-215)\n"
"    - Improved documentation for YARD::Server features (gh-207)\n"
"    - Fix displaying of collaped method summary lists (gh-204)\n"
"    - Fix automatic loading of markup providers (gh-206)\n"
"    - Fix keyboard shortcuts for Chrome (gh-203)\n"
"    - Disallow `extend self` inside of a class (gh-202)\n"
"    - Constants now recognized in C extensions (gh-201)"
msgstr ""
"- **December.21.10**: 0.6.4 release\n"
"    - Fix yri tool crashing with new Config class (gh-217)\n"
"    - Fix support for ::TopLevelConstants (gh-216)\n"
"    - YARD's test suite is now RSpec2 compatible (gh-215)\n"
"    - Improved documentation for YARD::Server features (gh-207)\n"
"    - Fix displaying of collaped method summary lists (gh-204)\n"
"    - Fix automatic loading of markup providers (gh-206)\n"
"    - Fix keyboard shortcuts for Chrome (gh-203)\n"
"    - Disallow `extend self` inside of a class (gh-202)\n"
"    - Constants now recognized in C extensions (gh-201)"

#: ../README.md:424
msgid ""
"- **November.21.10**: 0.6.3 release\n"
"    - Fixed regression that caused `yardoc --markup` to silently exit"
msgstr ""
"- **November.21.10**: 0.6.3 release\n"
"    - Fixed regression that caused `yardoc --markup` to silently exit"

#: ../README.md:427
msgid ""
"- **November.15.10**: 0.6.2 release\n"
"    - **Plugins no longer automatically load, use `--plugin` to load a "
"plugin**\n"
"    - Added YARD::Config and ~/.yard/config YAML configuration file\n"
"    - Added `yard config` command to view/edit YARD configuration file\n"
"    - Fixes for YARD in 1.8.6 (gh-178)\n"
"    - Various HTML template adjustments and fixes (gh-198,199,200)\n"
"    - Improved `yard server -m` multi-project stability (gh-193)\n"
"    - Fixed handling of `yardoc --no-private` with missing class definitions "
"(gh-197)\n"
"    - Added support for constants defined in C extensions (gh-177)\n"
"    - Added support for Structs defined as \"Klass = Struct.new"
"(...)\" (gh-187)\n"
"    - Improved parsing support for third-party gems (gh-174,180)\n"
"    - Improved support for JRuby 1.6.4+. YARD now passes all specs in JRuby "
"(gh-185)\n"
"    - Improved YARD documentation (gh-172,191,196)"
msgstr ""
"- **November.15.10**: 0.6.2 release\n"
"    - **Plugins no longer automatically load, use `--plugin` to load a plugin**\n"
"    - Added YARD::Config and ~/.yard/config YAML configuration file\n"
"    - Added `yard config` command to view/edit YARD configuration file\n"
"    - Fixes for YARD in 1.8.6 (gh-178)\n"
"    - Various HTML template adjustments and fixes (gh-198,199,200)\n"
"    - Improved `yard server -m` multi-project stability (gh-193)\n"
"    - Fixed handling of `yardoc --no-private` with missing class definitions (gh-197)\n"
"    - Added support for constants defined in C extensions (gh-177)\n"
"    - Added support for Structs defined as \"Klass = Struct.new(...)\" (gh-187)\n"
"    - Improved parsing support for third-party gems (gh-174,180)\n"
"    - Improved support for JRuby 1.6.4+. YARD now passes all specs in JRuby (gh-185)\n"
"    - Improved YARD documentation (gh-172,191,196)"

#: ../README.md:441
msgid ""
"- **September.06.10**: 0.6.1 release\n"
"    - Fixed TOC showing on top of class/method list in no-frames view\n"
"    - A message now displays when running `yard server` with Rack/Mongrel "
"installed\n"
"    - Improved performance of JS inline search for large class/method lists\n"
"    - Improved link titles for relative object links\n"
"    - Removed `String#camelcase` and `String#underscore` for better Rails "
"compat.\n"
"    - Fixed support for loading .yardoc files under Windows\n"
"    - Fixed inheritance tree arrows not displaying in certain environments"
msgstr ""
"- **September.06.10**: 0.6.1 release\n"
"    - Fixed TOC showing on top of class/method list in no-frames view\n"
"    - A message now displays when running `yard server` with Rack/Mongrel installed\n"
"    - Improved performance of JS inline search for large class/method lists\n"
"    - Improved link titles for relative object links\n"
"    - Removed `String#camelcase` and `String#underscore` for better Rails compat.\n"
"    - Fixed support for loading .yardoc files under Windows\n"
"    - Fixed inheritance tree arrows not displaying in certain environments"

#: ../README.md:450
msgid ""
"- **August.29.10**: 0.6.0 release\n"
"    - Added dynamic local documentation server\n"
"    - Added @group/@endgroup declarations to organize methods into groups\n"
"    - Added `yard` executable to serve as main CLI tool with pluggable "
"commands\n"
"    - Added `--asset` switch to `yardoc` to copy files/dirs to output dir\n"
"    - Added ability to register/manipulate tags via CLI (`--tag`, etc.)\n"
"    - Added `yard diff` command\n"
"    - Added statistics to `yardoc` output (and `yard stats` command)\n"
"    - Added Javascript generated Table of Contents to file pages\n"
"    - Updated various APIs\n"
"    - Removed `yard-graph` executable\n"
"    - See more changes in the {file:docs/WhatsNew.md what's new document}"
msgstr ""
"- **August.29.10**: 0.6.0 release\n"
"    - Added dynamic local documentation server\n"
"    - Added @group/@endgroup declarations to organize methods into groups\n"
"    - Added `yard` executable to serve as main CLI tool with pluggable commands\n"
"    - Added `--asset` switch to `yardoc` to copy files/dirs to output dir\n"
"    - Added ability to register/manipulate tags via CLI (`--tag`, etc.)\n"
"    - Added `yard diff` command\n"
"    - Added statistics to `yardoc` output (and `yard stats` command)\n"
"    - Added Javascript generated Table of Contents to file pages\n"
"    - Updated various APIs\n"
"    - Removed `yard-graph` executable\n"
"    - See more changes in the {file:docs/WhatsNew.md what's new document}"

#: ../README.md:463
msgid ""
"- **June.22.10**: 0.5.8 release\n"
"    - Merge fix from 0.6 branch for --no-private visibility checking"
msgstr ""
"- **June.22.10**: 0.5.8 release\n"
"    - Merge fix from 0.6 branch for --no-private visibility checking"

#: ../README.md:466
msgid ""
"- **June.21.10**: 0.5.7 release\n"
"    - Fixed visibility flag parsing in `yardoc`\n"
"    - Updated Parser Architecture documentation with new SourceParser API\n"
"    - Improved Registry documentation for new load commands\n"
"    - Fix loading of .yardoc file as cache (and preserving aliases)\n"
"    - Fix \"lib\" directory missing when running YARD on installed gems"
msgstr ""
"- **June.21.10**: 0.5.7 release\n"
"    - Fixed visibility flag parsing in `yardoc`\n"
"    - Updated Parser Architecture documentation with new SourceParser API\n"
"    - Improved Registry documentation for new load commands\n"
"    - Fix loading of .yardoc file as cache (and preserving aliases)\n"
"    - Fix \"lib\" directory missing when running YARD on installed gems"

#: ../README.md:473
msgid ""
"- **June.12.10**: 0.5.6 release\n"
"    - Bug fixes for RubyGems plugin, `has_rdoc=false` should now work\n"
"    - New API for registering custom parsers. See {file:docs/WhatsNew.md}"
msgstr ""
"- **June.12.10**: 0.5.6 release\n"
"    - Bug fixes for RubyGems plugin, `has_rdoc=false` should now work\n"
"    - New API for registering custom parsers. See {file:docs/WhatsNew.md}"

#: ../README.md:477
msgid ""
"- **May.22.10**: 0.5.5 release\n"
"    - Various bug fixes"
msgstr ""
"- **May.22.10**: 0.5.5 release\n"
"    - Various bug fixes"

#: ../README.md:480
msgid ""
"- **March.22.10**: 0.5.4 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"
msgstr ""
"- **March.22.10**: 0.5.4 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"

#: ../README.md:483
msgid ""
"- **January.11.10**: 0.5.3 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"
msgstr ""
"- **January.11.10**: 0.5.3 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"

#: ../README.md:486
msgid ""
"- **December.16.09**: 0.5.2 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"
msgstr ""
"- **December.16.09**: 0.5.2 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"

#: ../README.md:489
msgid ""
"- **December.15.09**: 0.5.1 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"
msgstr ""
"- **December.15.09**: 0.5.1 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"

#: ../README.md:492
msgid ""
"- **December.13.09**: 0.5.0 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"
msgstr ""
"- **December.13.09**: 0.5.0 release\n"
"    - See {file:docs/WhatsNew.md what's new document} for changes"

#: ../README.md:495
msgid ""
"- **November.15.09**: 0.4.0 release\n"
"    - Added new templating engine based on [tadpole](http://github.com/"
"lsegal/tadpole)\n"
"    - Added YARD queries (`--query` CLI argument to yardoc)\n"
"    - Greatly expanded YARD documentation\n"
"    - Added plugin support\n"
"    - New `@abstract` and `@private` tags\n"
"    - Changed default rake task to `rake yard`\n"
"    - Read about changes in {file:docs/WhatsNew.md}"
msgstr ""
"- **November.15.09**: 0.4.0 release\n"
"    - Added new templating engine based on [tadpole](http://github.com/lsegal/tadpole)\n"
"    - Added YARD queries (`--query` CLI argument to yardoc)\n"
"    - Greatly expanded YARD documentation\n"
"    - Added plugin support\n"
"    - New `@abstract` and `@private` tags\n"
"    - Changed default rake task to `rake yard`\n"
"    - Read about changes in {file:docs/WhatsNew.md}"

#: ../README.md:504
msgid ""
"- **August.13.09**: 0.2.3.5 release\n"
"    - Minor bug fixes."
msgstr ""
"- **August.13.09**: 0.2.3.5 release\n"
"    - Minor bug fixes."

#: ../README.md:507
msgid ""
"- **August.07.09**: 0.2.3.4 release\n"
"    - Minor bug fixes."
msgstr ""
"- **August.07.09**: 0.2.3.4 release\n"
"    - Minor bug fixes."

#: ../README.md:510
msgid ""
"- **July.26.09**: 0.2.3.3 release\n"
"    - Minor bug fixes."
msgstr ""
"- **July.26.09**: 0.2.3.3 release\n"
"    - Minor bug fixes."

#: ../README.md:513
msgid ""
"- **July.06.09**: 0.2.3.2 release\n"
"    - Fix Textile hard-break issues\n"
"    - Add description for @see tag to use as link title in HTML docs.\n"
"    - Add --title CLI option to specify a title for HTML doc files.\n"
"    - Add custom.css file that can be overridden with various custom\n"
"      styelsheet declarations. To use this, simply add `default/fulldoc/html/"
"custom.css`\n"
"      inside your code directory and use the `-t` template directory yardoc "
"CLI\n"
"      option to point to that template directory (the dir holding "
"'default').\n"
"    - Add support in `yardoc` CLI to specify extra files (formerly --files)\n"
"      by appending \"- extra files here\" after regular source files. "
"Example:"
msgstr ""
"- **July.06.09**: 0.2.3.2 release\n"
"    - Fix Textile hard-break issues\n"
"    - Add description for @see tag to use as link title in HTML docs.\n"
"    - Add --title CLI option to specify a title for HTML doc files.\n"
"    - Add custom.css file that can be overridden with various custom\n"
"      styelsheet declarations. To use this, simply add `default/fulldoc/html/custom.css`\n"
"      inside your code directory and use the `-t` template directory yardoc CLI\n"
"      option to point to that template directory (the dir holding 'default').\n"
"    - Add support in `yardoc` CLI to specify extra files (formerly --files)\n"
"      by appending \"- extra files here\" after regular source files. Example:"

#: ../README.md:524
msgid "            yardoc --private lib/**/*.rb - FAQ LICENSE"
msgstr "            yardoc --private lib/**/*.rb - FAQ LICENSE"

#: ../README.md:526
msgid ""
"- **Jun.13.09**: 0.2.3.1 release.\n"
"    - Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead "
"of\n"
"      RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in "
"your\n"
"      .gemspec file."
msgstr ""
"- **Jun.13.09**: 0.2.3.1 release.\n"
"    - Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead of\n"
"      RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in your\n"
"      .gemspec file."

#: ../README.md:531
msgid ""
"- **Jun.07.09**: 0.2.3 release. See the {file:docs/WhatsNew.md} file for a\n"
"  list of important new features."
msgstr ""
"- **Jun.07.09**: 0.2.3 release. See the {file:docs/WhatsNew.md} file for a\n"
"  list of important new features."

#: ../README.md:534
msgid ""
"- **Jun.16.08**: 0.2.2 release. This is the largest changset since yard's\n"
"  conception and involves a complete overhaul of the parser and API to make "
"it\n"
"  more robust and far easier to extend and use for the developer."
msgstr ""
"- **Jun.16.08**: 0.2.2 release. This is the largest changset since yard's\n"
"  conception and involves a complete overhaul of the parser and API to make it\n"
"  more robust and far easier to extend and use for the developer."

#: ../README.md:538
msgid "- **Feb.20.08**: 0.2.1 release."
msgstr "- **Feb.20.08**: 0.2.1 release."

#: ../README.md:540
msgid ""
"- **Feb.24.07**: Released 0.1a experimental version for testing. The goal "
"here is\n"
"  to get people testing YARD on their code because there are too many "
"possible\n"
"  code styles to fit into a sane amount of test cases. It also demonstrates "
"the\n"
"  power of YARD and what to expect from the syntax (Yardoc style meta tags)."
msgstr ""
"- **Feb.24.07**: Released 0.1a experimental version for testing. The goal here is\n"
"  to get people testing YARD on their code because there are too many possible\n"
"  code styles to fit into a sane amount of test cases. It also demonstrates the\n"
"  power of YARD and what to expect from the syntax (Yardoc style meta tags)."

#: ../README.md:546
msgid "## Contributors"
msgstr "## 貢献者へ"

#: ../README.md:548
msgid ""
"Special thanks to all contributors for submitting patches. A full list of\n"
"contributors including their patches can be found at:"
msgstr ""
"パッチの申請をした全ての貢献者へ本当に感謝する。\n"
"これらのパッチを投げた全ての貢献者のリストは次で見れる:"

#: ../README.md:551
msgid "http://github.com/lsegal/yard/contributors"
msgstr "http://github.com/lsegal/yard/contributors"

#: ../README.md:553
msgid "## Copyright"
msgstr "## Copyright"

#: ../README.md:555
msgid ""
"YARD © 2007-2012 by [Loren Segal](mailto:lsegal@soen.ca). YARD is\n"
"licensed under the MIT license except for some files which come from the\n"
"RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}\n"
"documents for more information."
msgstr ""
"YARD © 2007-2012 by [Loren Segal](mailto:lsegal@soen.ca). YARD is\n"
"licensed under the MIT license except for some files which come from the\n"
"RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}\n"
"documents for more information."

# title
#: ../docs/CodeObjects.md:1
msgid "CodeObjects Architecture"
msgstr "コードオブジェクト構造"

#: ../docs/CodeObjects.md:3
msgid "# CodeObjects Architecture"
msgstr "# コードオブジェクト構造"

#: ../docs/CodeObjects.md:5
msgid ""
"Code objects are Ruby objects that describe the code being documented. For "
"instance,\n"
"all classes, modules, methods, etc. are all extracted from the Ruby source "
"as code\n"
"objects. All of these code objects extend from the {YARD::CodeObjects::Base} "
"class, which\n"
"provides basic attributes like source location, source code, name and path."
msgstr ""
"コードオブジェクトは記述されているコードの用途を説明するRubyオブジェクトとな"
"る。\n"
"例えば、全てのクラス,モジュール,メソッド等は、\n"
"コードオブジェクトのようにRubyのソースから全て抽出される。\n"
"これらコードオブジェクトの全ては、{YARD::CodeObjects::Base}クラスから拡張す"
"る。\n"
"そして、ソースの位置や,ソースコードや,名前や,パスのように基本属性を提供する。"

#: ../docs/CodeObjects.md:10
msgid "## CodeObjects Organization"
msgstr "## コードオブジェクト機構"

#: ../docs/CodeObjects.md:12
msgid ""
"Code objects are divided into two basic types. {YARD::CodeObjects::"
"NamespaceObject NamespaceObjects}\n"
"and non-namespace objects. A namespace object refers to any object in Ruby "
"that can have\n"
"other objects defined inside of it. In the context of Ruby, this "
"specifically means\n"
"modules and classes (both of which are subclasses of `NamespaceObject`). "
"These objects\n"
"act like tree structures, maintaining a list of all of their direct "
"children. All non\n"
"namespace objects are simply subclasses of the Base class. The {YARD::"
"CodeObjects::RootObject RootObject}\n"
"is a special kind of `NamespaceObject` which refers to the top level "
"namespace in Ruby.\n"
"Methods that accept a namespace object as a parameter should also accept the "
"symbol\n"
"`:root` as a shortcut for the root object."
msgstr ""
"コードオブジェクトは二つの基本的な方に分割される。\n"
"それは{YARD::CodeObjects::NamespaceObject NamespaceObjects}とnamespaceではないオブジェクトである。\n"
"namespace オブジェクトは\n"
"その内部で定義された他のオブジェクトを持つ事ができる任意のRubyのオブジェクトを参照する。\n"
"これは特にモジュールとクラスを意味する。\n"
"( `NamespaceObject` のサブクラスのどちらとも)\n"
"これらのオブジェクトはツリー構造のように振る舞い、これらの直接の子全てのリストを維持している。\n"
"namespaceではない全てのオブジェクトは単純にベースクラスのサブクラスである。\n"
"{YARD::CodeObjects::RootObject RootObject} は\n"
"特別な `NamespaceObject` ともいえ、Rubyの中のトップレベルnamespaceを参照する。\n"
"パラメータとして namespace オブジェクトを受け入れるメソッドは、\n"
"root オブジェクト用のショートカットとして `:root` シンボルも受け入れる。"

#: ../docs/CodeObjects.md:22
msgid ""
"The following is an overview of the classes within the `CodeObjects` "
"namespace:"
msgstr "以下は `CodeObjects` のnamespaceの中で用いられるクラスの概要となる。"

#: ../docs/CodeObjects.md:24
msgid "![CodeObjects Class Diagram](images/code-objects-class-diagram.png)"
msgstr "![CodeObjects Class Diagram](images/code-objects-class-diagram.png)"

#: ../docs/CodeObjects.md:26
msgid "## Unique Path Representation"
msgstr ""
"## ユニークパス表現\n"
"## Unique Path Representation"

#: ../docs/CodeObjects.md:28
msgid ""
"All CodeObjects are uniquely defined by their implementation of {YARD::"
"CodeObjects::Base#path}.\n"
"This path is used to locate or store a code object in the {YARD::Registry}. "
"It is therefore\n"
"essential that any Base subclass return a unique String value for #path so "
"that the\n"
"object may co-exist with other objects in the Registry."
msgstr ""
"全てのコードオブジェクトは\n"
"これらの{YARD::CodeObjects::Base#path}の実装によって個別に定義される。\n"
"このパスは場所を示すためや {YARD::Registry} の中でコードオブジェクトを登録するため利用される\n"
"それ故、任意の基本サブクラスが個別の#pathメソッド用の文字列値を返す必要がある。\n"
"オブジェクトはレジストリーの中で他のオブジェクトと一緒に共存する事になる。"

#: ../docs/CodeObjects.md:33
msgid ""
"In practice, a path is simply the conventional Ruby representation of a "
"class,\n"
"module, constant, class variable or method. For example, the following "
"objects\n"
"would have the following respective paths:"
msgstr ""
"実際のパスは、単純に慣習的なRubyの\n"
"クラス,モジュール,定数,クラス変数,メソッドの表現となる。\n"
"例えば、次のオブジェクトは、後に続く個別のパスを持っている。"

#: ../docs/CodeObjects.md:37
msgid ""
"* Class `Klass` inside module `Mod`: `Mod::Klass`\n"
"* Instance method `bar` inside class `Foo`: `Foo#bar`\n"
"* Class method `bar` inside class `Foo`: `Foo.bar`\n"
"* Constant `VERSION` inside class `YARD`: `YARD::VERSION`\n"
"* Class variable `@@abc` inside class `A`: `A::@@abc`"
msgstr ""
"* `Mod` モジュールの内部の `Klass` クラス: `Mod::Klass`\n"
"* `Foo` クラスの内部の `bar` インスタンスメソッド: `Foo#bar`\n"
"* `Foo` クラスの内部の `bar` クラスメソッド: `Foo.bar`\n"
"* `YARD` クラス内部の `VARSION` 定数: `YARD::VERSION`\n"
"* `A` クラス内部の `@@abc` クラス変数: `A::@@abc`"

#: ../docs/CodeObjects.md:43
msgid "## Registry"
msgstr "## レジストリー"

#: ../docs/CodeObjects.md:45
msgid ""
"CodeObjects classes are coupled with the {YARD::Registry} class which keeps "
"track of\n"
"all instantiated code objects. This is an explicit design choice to allow "
"objects\n"
"to be fetched, cached, imported and exported from a centralized location. As "
"mentioned\n"
"above, this coupling is a result of the fact that each object is uniquely "
"identified by\n"
"its path, which is used to implement lookups. You can read more about the "
"registry\n"
"in the {YARD::Registry} class."
msgstr ""
"コードオブジェクトクラスは {YARD::Registry} クラスを用い組み合わされ、\n"
"そしてインスタンス化されたコードオブジェクトのトラックを保持する。\n"
"これは集中化される場所から、\n"
"フェッチ,キャッシュ,インポート,エクスポートされるオブジェクトを許可するための\n"
"選択を明確に設計する。\n"
"上で言われた、\n"
"この組み合わせは個々のオブジェクトの要素の結果がそのパスによって独自に識別され,\n"
"検索を実装するために利用される。\n"
"レジストリーの詳細については、 {YARD::Registry} クラスの中で読むことができる。"

#: ../docs/CodeObjects.md:52
msgid "## Identity Map"
msgstr "## Identity Map"

#: ../docs/CodeObjects.md:54
msgid ""
"Code objects are instantiated using an identity-map like implementation that "
"guarantees\n"
"only one unique Ruby object exists for an object described by a specific "
"path. This\n"
"allows developers to create a code object without checking if it already "
"exists in\n"
"the {YARD::Registry}. The following example will only create one object:"
msgstr ""
"コードオブジェクトはidentity-mapによってインスタンス化される。\n"
"これは、特定のパスによって説明されるオブジェクトが\n"
"固有のRubyオブジェクトだと保証する実装のようなものである。\n"
"既に{YARD::Registry}の中に存在する場合\n"
"確認無しでコードオブジェクトを作成する為に開発者達を受け入れる\n"
"次の例は一つのオブジェクトだけ作成する。"

#: ../docs/CodeObjects.md:59
msgid ""
"    id = ClassObject.new(:root, \"MyClass\").object_id #=> 13352\n"
"    ClassObject.new(:root, \"MyClass\").object_id #=> 13352"
msgstr ""
"    id = ClassObject.new(:root, \"MyClass\").object_id #=> 13352\n"
"    ClassObject.new(:root, \"MyClass\").object_id #=> 13352"

#: ../docs/CodeObjects.md:62
msgid "## Proxy Objects"
msgstr "## プロキシ オブジェクト"

#: ../docs/CodeObjects.md:64
msgid ""
"In addition to providing access to existing objects, a {YARD::CodeObjects::"
"Proxy}\n"
"class exists which can represent an object at a path that may or may not "
"have been\n"
"created. This is necessary to represent a reference to an object in code "
"that is\n"
"never defined in the same body of source code, or perhaps defined later. If "
"any\n"
"attributes of a proxy are accessed, it will immediately be resolved to the "
"object\n"
"at its declared path. In the case where such an object exists, it will act "
"as\n"
"a delegate to the object. However, if the object does not exist, a warning "
"will\n"
"be raised. Whenever arbitrary code objects are used, care should be taken "
"in\n"
"order to make sure attributes are not accessed on unresolvable proxies. An\n"
"unresolvable proxy will return a class name of `Proxy` and #type of `:"
"proxy`,\n"
"for example:"
msgstr ""
"さらに現在のオブジェクトにアクセスを提供するには、\n"
"{YARD::CodeObjects::Proxy} クラスがある。\n"
"それは作成されるかどうかはわからないがパスでオブジェクトを表せる。\n"
"これは同じソースコード内で定義されないコードでオブジェクトへの参照を表す為や、\n"
"ことによると後で定義される時に必要となる。\n"
"任意プロキシの属性がアクセスされる場合、\n"
"すぐに宣言されたパスでオブジェクトの為に解決される。\n"
"オブジェクトが存在する場合、オブジェクトに委譲するように振る舞う。\n"
"しかしながら、オブジェクトが存在しなかった場合は、警告が出るだろう。\n"
"任意のコードオブジェクトが利用される時はいつでも、\n"
"属性が未解決のプロキシ上でアクセスしないか確認する為に\n"
"順番にされるので注意しなければならない。\n"
"未解決のプロキシは `Proxy` のクラス名と `:proxy` の#typeメソッドを返す。\n"
"例えば以下のように:"

#: ../docs/CodeObjects.md:76
msgid ""
"    P(:InvalidObject).type == :proxy  #=> true\n"
"    P(:InvalidObject).is_a?(Proxy)    #=> true"
msgstr ""
"    P(:InvalidObject).type == :proxy  #=> true\n"
"    P(:InvalidObject).is_a?(Proxy)    #=> true"

#: ../docs/CodeObjects.md:79
msgid "## Adding Data to Code Objects"
msgstr "## コードオブジェクトにデータを追加する。"

#: ../docs/CodeObjects.md:81
msgid ""
"Code objects act as hash-like structures that allow any arbitrary value to "
"be set.\n"
"This allows easy extending of existing objects without creating custom "
"subclasses.\n"
"For instance, to add a timestamp to a method object (when it was modified, "
"maybe),\n"
"it is possible to simply do:"
msgstr ""
"コードオブジェクトは設定される為の任意の値を受け入れるハッシュ構造のように振"
"る舞う。\n"
"これは、カスタムサブクラスを作成すること無しで、既存のオブジェクトの簡単な拡"
"張を受け入れる。\n"
"例えば、メソッドオブジェクトにtimestampを追加する為には、\n"
"以下の様に単純にする事が可能。"

#: ../docs/CodeObjects.md:86
msgid ""
"    object = MethodObject.new(:root, \"my_method\")\n"
"    object[:modified_at] = Time.now"
msgstr ""
"    object = MethodObject.new(:root, \"my_method\")\n"
"    object[:modified_at] = Time.now"

#: ../docs/CodeObjects.md:89
msgid ""
"This value can now be retrieved on this object both by the hash `[]` syntax "
"as\n"
"well as like any other method:"
msgstr ""
"この値はハッシュのような `[]` 構文でも以下のような\n"
"メソッド呼び出しでも取り出す事が出来る。"

#: ../docs/CodeObjects.md:92
msgid "    object.modified_at #=> 2009-06-03 20:08:46 -0400"
msgstr "    object.modified_at #=> 2009-06-03 20:08:46 -0400"

#: ../docs/CodeObjects.md:94
msgid "## Creating a Custom CodeObject"
msgstr "## カスタムコードオブジェクトを作成する"

#: ../docs/CodeObjects.md:96
msgid ""
"It should first be mentioned that creating a custom code object should not "
"be\n"
"necessary in most cases, except when functionality that cannot be "
"represented\n"
"by classical Ruby objects is added. A good example *might* be a test class,\n"
"which although is technically a Ruby class, has a significantly different "
"purpose\n"
"in documentation and needs a different set of metadata, as well as its own\n"
"representation in documentation."
msgstr ""
"カスタムコードオブジェクトを作成する前に、最初に言及すべきこととして、\n"
"大抵の場合、カスタムコードオブジェクトを作成する事は必須ではないはずであ"
"る。\n"
"この項は標準的なRubyオブジェクトの追加によって表現できない機能がある時の事を"
"予期する。\n"
"いい例は、testクラスかもしれない、\n"
"それは、形の上ではRubyのクラスだけれども、\n"
"中のドキュメントやメタデータの入った異なる設定を必要とし\n"
"かなり異なる目的をもっている。\n"
"それ自身もドキュメントの中を表している。"

#: ../docs/CodeObjects.md:103
msgid ""
"The {YARD::CodeObjects::Base#path} implementation is the most important part "
"of the\n"
"code object architecture. The first thing any custom code object must "
"guarantee is\n"
"that its path value is unique among all other objects. The recommended way "
"to do this\n"
"with custom objects is to add a descriptive prefix to the path. For example, "
"the\n"
"following is an implementation of the path for a hypothetical `FooObject`:"
msgstr ""
"{YARD::CodeObjects::Base#path}の実装がコードオブジェクト構造の最も重要な部分である。\n"
"どのカスタムコードオブジェクトでも最初に保証されなければならない事は、\n"
"パスの値が他の全てのオブジェクトとの間で固有でなければならない。\n"
"これを行うのに推奨される方法は、\n"
"カスタムオブジェクトがパスに説明のプレフィックス(接頭語)を\n"
"追加する方法である。\n"
"例えば、次は仮の `FooObject` 用のパスの実装となる。"

#: ../docs/CodeObjects.md:109
msgid ""
"    def path\n"
"      \"__FooPrefix\" + sep + super\n"
"    end"
msgstr ""
"    def path\n"
"      \"__FooPrefix\" + sep + super\n"
"    end"

#: ../docs/CodeObjects.md:113
msgid ""
"Note that if our FooObject is a `NamespaceObject`, meaning if it can have "
"child\n"
"FooObjects defined inside of it, you may need to verify that the prefix is "
"only\n"
"applied once."
msgstr ""
"次の事に留意する。\n"
"もし例のFooObjectが、 `NamespaceObject` の場合、\n"
"FooObjectがそれの内部で定義される子を持てるかどうか意味している。\n"
"一度だけ適用されるプレフィックスを確認する為に必要な場合がある。"

# title
#: ../docs/GettingStarted.md:1
msgid "Getting Started Guide"
msgstr "導入の案内"

#: ../docs/GettingStarted.md:3
msgid "# Getting Started with YARD"
msgstr "# YARDを使い始めるには"

#: ../docs/GettingStarted.md:5
msgid ""
"There are a few ways which YARD can be of use to you or your project. This\n"
"document will cover the most common ways to use YARD:"
msgstr ""
"YARDにはプロジェクトの助けとなるいくつかの使用方法があるが、\n"
"このドキュメントでは以下の目次で一般的なYARDの使い方について説明する。"

#: ../docs/GettingStarted.md:8
msgid ""
"* [Documenting Code with YARD](#docing)\n"
"* [Using YARD to Generate Documentation](#using)\n"
"* [Configuring YARD](#config)\n"
"* [Extending YARD](#extending)\n"
"* [Templating YARD](#templating)\n"
"* [Plugin Support](#plugins)"
msgstr ""
"* [YARDで文書を作る](#docing)\n"
"* [ドキュメントを生成するYARDの使い方](#using)\n"
"* [YARDの構成する](#config)\n"
"* [YARDの拡張する](#extending)\n"
"* [YARDのテンプレートを作成する](#templating)\n"
"* [プラグインサポート](#plugins)"

#: ../docs/GettingStarted.md:15
msgid ""
msgstr ""

#: ../docs/GettingStarted.md:17
msgid "## Documenting Code with YARD"
msgstr "## YARDで文書を作る"

#: ../docs/GettingStarted.md:19
msgid ""
"By default, YARD is compatible with the same RDoc syntax most Ruby "
"developers\n"
"are already familiar with. However, one of the biggest advantages of YARD "
"is\n"
"the extended meta-data syntax, commonly known as \"tags\", that you can use\n"
"to express small bits of information in a structured and formal manner. "
"While\n"
"RDoc syntax expects you to describe your method in a completely free-form\n"
"manner, YARD recommends declaring your parameters, return types, etc. with\n"
"the `@tag` syntax, which makes outputting the documentation more consistent\n"
"and easier to read. Consider the RDoc documentation for a method to_format:"
msgstr ""
"デフォルトで、YARDは多くのRuby開発者たちがすでによく知っている\n"
"RDoc構文と両立できる。\n"
"しかしながら、\n"
"YARDの最も大きな利点の一つは、拡張できるメタデータ構文となる。\n"
"それは、一般的に知られる\"タグ\"のように、\n"
"小さくて構造化された情報の中を明確にする為や\n"
"形式的な方法で記述する為に利用できる。\n"
"さらに、RDoc構文はメソッドを説明する為に全てフリーフォームマナーで要求するが、\n"
"YARDは宣言しているパラメータ、リターンタイプなどを `@tag` 構文を用いて、\n"
"一貫した表現で簡単に読む為のドキュメント作りを推奨する。\n"
"RDocのドキュメントのto_formatメソッドについて考えてみる。"

#: ../docs/GettingStarted.md:28
msgid ""
"    # Converts the object into textual markup given a specific `format`\n"
"    # (defaults to `:html`)\n"
"    #\n"
"    # == Parameters:\n"
"    # format::\n"
"    #   A Symbol declaring the format to convert the object to. This\n"
"    #   can be `:text` or `:html`.\n"
"    #\n"
"    # == Returns:\n"
"    # A string representing the object in a specified\n"
"    # format.\n"
"    #\n"
"    def to_format(format = :html)\n"
"      # format the object\n"
"    end"
msgstr ""
"    # 原文のマークアップの与えられた特定の `format` へオブジェクトを変換する\n"
"    # (defaults to `:html`)\n"
"    #\n"
"    # == Parameters:\n"
"    # format::\n"
"    #   A Symbol declaring the format to convert the object to. This\n"
"    #   can be `:text` or `:html`.\n"
"    #\n"
"    # == Returns:\n"
"    # A string representing the object in a specified\n"
"    # format.\n"
"    #\n"
"    def to_format(format = :html)\n"
"      # format the object\n"
"    end"

#: ../docs/GettingStarted.md:44
msgid ""
"While this may seem easy enough to read and understand, it's hard for a "
"machine\n"
"to properly pull this data back out of our documentation. Also we've tied "
"our\n"
"markup to our content, and now our documentation becomes hard to maintain "
"if\n"
"we decide later to change our markup style (maybe we don't want the \":\" "
"suffix\n"
"on our headers anymore)."
msgstr ""
"これは読んだり理解するには簡単と思われるかもしれないが、\n"
"機械にとっては例のドキュメントを取消しデータを適切に再配置\n"
"するのは大変である。(フリーフォームなので)\n"
"内容と紐付いたマークアップになっているので、\n"
"マークアップスタイルを変更するのが後で決まった場合、\n"
"例のドキュメントはすぐに維持するのが大変になる\n"
"(恐らく、私達は例の見出しのサフィックス\":\"を望んでいない。)"

#: ../docs/GettingStarted.md:50
msgid "In YARD, we would simply define our method as:"
msgstr "YARDの中で、私達は例のメソッドを単純に定義する。"

#: ../docs/GettingStarted.md:52
msgid ""
"    # Converts the object into textual markup given a specific format.\n"
"    #\n"
"    # @param [Symbol] format the format type, `:text` or `:html`\n"
"    # @return [String] the object converted into the expected format.\n"
"    def to_format(format = :html)\n"
"      # format the object\n"
"    end"
msgstr ""
"    # 原文のマークアップの与えられた特定のフォーマットへオブジェクトを変換する\n"
"    #\n"
"    # @param [Symbol] format the format type, `:text` or `:html`\n"
"    # @return [String] the object converted into the expected format.\n"
"    def to_format(format = :html)\n"
"      # format the object\n"
"    end"

#: ../docs/GettingStarted.md:60
msgid ""
"Using tags we can add semantic metadata to our code without worrying about\n"
"presentation. YARD will handle presentation for us when we decide to "
"generate\n"
"documentation later."
msgstr ""
"タグを用いることによって、\n"
"私達は(フリーフォームでの)見栄えを気にすることなく\n"
"意味のあるメタデータを追加することができる。\n"
"そしてYARDは後でドキュメントを生成すると決めた時、\n"
"見栄えを処理できる。"

#: ../docs/GettingStarted.md:64
msgid "## Which Markup Format?"
msgstr "## どのマークアップフォーマット?"

#: ../docs/GettingStarted.md:66
msgid ""
"YARD does not impose a specific markup. The above example uses standard "
"RDoc\n"
"markup formatting, but YARD also supports textile and markdown via the\n"
"command-line switch or `.yardopts` file (see below). This means that you "
"are\n"
"free to use whatever formatting you like. This guide is actually written\n"
"using markdown. YARD, however, does add a few important syntaxes that are\n"
"processed no matter which markup formatting you use, such as tag support\n"
"and inter-document linking. These syntaxes are discussed below."
msgstr ""
"YARDは特定のマークアップを強要しない。\n"
"上の例は標準のRDocマークアップ書式を例として使ったが、\n"
"それだけではなく、\n"
"コマンドラインや `.yardopts` ファイル経由でtexttileとmarkdownもサポートする(以下参照)\n"
"これが意味することは、\n"
"あなたが好きなどんな書式を使おうとも自由である。\n"
"このガイドは実際にmarkdownを使って書かれている。\n"
"ともあれYARDにはいくつかの重要な構文を追加された。\n"
"それは、\n"
" 1. あなた使うマークアップ書式で問題なく処理される\n"
" 2. タグの様なサポート\n"
" 3. ドキュメント内部のリンク\n"
"である。\n"
"これらの構文は以降で説明される。"

#: ../docs/GettingStarted.md:74
msgid "## Adding Tags to Documentation"
msgstr "## ドキュメントにつけられているタグ"

#: ../docs/GettingStarted.md:76
msgid ""
"The tag syntax that YARD uses is the same @tag-style syntax you may have "
"seen\n"
"if you've ever coded in Java, Python, PHP, Objective-C or a myriad of other\n"
"languages. The following tag adds an author tag to your class:"
msgstr ""
"YARDが使うタグ構文は,もしあなたが今まで\n"
"Java, Python, PHP, Objective-Cや無数の他の言語をプログラミングした事があれば\n"
"既にあなたが見たことがある@tagスタイルと同じ構文である\n"
"次のタグはauthorタグをあなたのクラスに追加する:"

#: ../docs/GettingStarted.md:80
msgid ""
"    # @author Loren Segal\n"
"    class MyClass\n"
"    end"
msgstr ""
"    # @author Loren Segal\n"
"    class MyClass\n"
"    end"

#: ../docs/GettingStarted.md:84
msgid ""
"To allow for large amounts of text, the @tag syntax will recognize any "
"indented\n"
"lines following a tag as part of the tag data. For example:"
msgstr ""
"大量のテキストを受け入れる為に、\n"
"タグ構文は続くインデントされた行をタグデータの一部として認識するだろう。\n"
"例えば以下の様になる。"

#: ../docs/GettingStarted.md:87
msgid ""
"    # @deprecated Use {#my_new_method} instead of this method because\n"
"    #   it uses a library that is no longer supported in Ruby 1.9.\n"
"    #   The new method accepts the same parameters.\n"
"    def mymethod\n"
"    end"
msgstr ""
"    # @deprecated Use {#my_new_method} instead of this method because\n"
"    #   it uses a library that is no longer supported in Ruby 1.9.\n"
"    #   The new method accepts the same parameters.\n"
"    def mymethod\n"
"    end"

#: ../docs/GettingStarted.md:93
msgid "### List of Tags"
msgstr "### タグのリスト"

#: ../docs/GettingStarted.md:95
msgid "A list of tags can be found in {file:docs/Tags.md#taglist}"
msgstr "タグのリストは {file:docs/Tags.md#taglist} で見つけられる。"

#: ../docs/GettingStarted.md:97 ../docs/Tags.md:230
msgid "### Reference Tags"
msgstr "### 参照タグ"

#: ../docs/GettingStarted.md:99
msgid ""
"To reduce the amount of duplication in writing documentation for repetitive\n"
"code, YARD introduces \"reference tags\", which are not quite tags, but not\n"
"quite docstrings either. In a sense, they are tag (and docstring) "
"modifiers.\n"
"Basically, any docstring (or tag) that begins with \"(see OTHEROBJECT)\" "
"will\n"
"implicitly link the docstring or tag to the \"OTHEROBJECT\", copying any "
"data\n"
"from that docstring/tag into your current object. Consider the example:"
msgstr ""
"繰り返しの多いドキュメント中の重複の総量を減少させるために、\n"
"YARDはタグでもdocstringsでもない\"参照タグ\"を導入する。\n"
"ある意味で、それらのタグ(とdocstring)の修飾となる。\n"
"基本的には、\"(see OTHEROBJECT)\"から始まるdocstring(又はタグ)は\n"
"\"OTHEROBJECT\"に暗黙的にリンクされる。これによって\n"
"何らかのデータをdocstringやタグからあなたの作業オブジェクトの中へコピーするこ"
"とができる。\n"
"例を考えてみる。"

#: ../docs/GettingStarted.md:106
msgid ""
"    class MyWebServer\n"
"      # Handles a request\n"
"      # @param [Request] request the request object\n"
"      # @return [String] the resulting webpage\n"
"      def get(request) \"hello\" end"
msgstr ""
"    class MyWebServer\n"
"      # リクエストを操作する\n"
"      # @param [Request] request the request object\n"
"      # @return [String] the resulting webpage\n"
"      def get(request) \"hello\" end"

#: ../docs/GettingStarted.md:112
msgid ""
"      # (see #get)\n"
"      def post(request) \"hello\" end\n"
"    end"
msgstr ""
"      # (see #get)\n"
"      def post(request) \"hello\" end\n"
"    end"

#: ../docs/GettingStarted.md:116
msgid ""
"The above `#post` method takes the docstring and all tags (`param` and "
"`return`)\n"
"of the `#get` method. When you generate HTML documentation, you will see "
"this\n"
"duplication automatically, so you don't have to manually type it out. We "
"can\n"
"also add our own custom docstring information below the \"see\" reference, "
"and\n"
"whatever we write will be appended to the docstring:"
msgstr ""
"上の `#post` メソッドは `#get` メソッドのdocstrigと\n"
"全てのタグ( `param` 及び `return` )を取得する。\n"
"HTMLドキュメントを生成する時には、\n"
"`#get` メソッドのタグの内容が自動的に複製されるので、\n"
"あなたが手でタイプする必要は無い。\n"
"また\"see\"の参照の下に、自分でカスタマイズしたdocstring情報を追加できる。\n"
"そして、以下の例の様に、\n"
"私達が書くものがどんなものでも、docstringに追加される。"

#: ../docs/GettingStarted.md:122
msgid ""
"    # (see #get)\n"
"    # @note This method may modify our application state!\n"
"    def post(request) self.state += 1; \"hello\" end"
msgstr ""
"    # (see #get)\n"
"    # @note このメソッドはアプリケーションの状態が変更されるかもしれない\n"
"    def post(request) self.state += 1; \"hello\" end"

#: ../docs/GettingStarted.md:126
msgid ""
"Here we added another tag, but we could have also added plain text. The\n"
"text must be appended *after* the `(see ...)` statement, preferably on\n"
"a separate line."
msgstr ""
"ここでは他のタグ(@note)を追加したが、他に簡単なテキストを持つこともできる。\n"
"その時はできればテキストを、`(see ...)`ステートメントの次の行に追加すべきである。"

#: ../docs/GettingStarted.md:130
msgid ""
"Note that we don't have to \"refer\" the whole docstring. We can also link\n"
"individual tags instead. Since \"get\" and \"post\" actually have different\n"
"descriptions, a more accurate example would be to only refer our parameter\n"
"and return tags:"
msgstr ""
"次の事に留意する。\n"
"必ずしもdocstring全体を\"参照\"する必要はなく、\n"
"代わりに個々のタグをリンクすることができる。\n"
"実際に異なる説明を持っている\"get\"と\"post\"から、\n"
"より正確な例はパラメータやリターンタグ参照だけになる。"

#: ../docs/GettingStarted.md:135
msgid ""
"    class MyWebServer\n"
"      # Handles a GET request\n"
"      # @param [Request] request the request object\n"
"      # @return [String] the resulting webpage\n"
"      def get(request) \"hello\" end"
msgstr ""
"    class MyWebServer\n"
"      # GETリクエストを操作する\n"
"      # @param [Request] request the request object\n"
"      # @return [String] the resulting webpage\n"
"      def get(request) \"hello\" end"

#: ../docs/GettingStarted.md:141
msgid ""
"      # Handles a POST request\n"
"      # @note This method may modify our application state!\n"
"      # @param (see #get)\n"
"      # @return (see #get)\n"
"      def post(request) self.state += 1; \"hello\" end\n"
"    end"
msgstr ""
"      # POSTリクエストを操作する\n"
"      # @note This method may modify our application state!\n"
"      # @param (see #get)\n"
"      # @return (see #get)\n"
"      def post(request) self.state += 1; \"hello\" end\n"
"    end"

#: ../docs/GettingStarted.md:148
msgid ""
"The above copies all of the param and return tags from `#get`. Note that "
"you\n"
"cannot copy individual tags of a specific type with this syntax."
msgstr ""
"上の構文は、 `#get` から@paramタグと@returnタグの全ての情報をコピーする。\n"
"次の事に留意する。\n"
"この構文を用いても特定の型の個々のタグをコピーできない。"

#: ../docs/GettingStarted.md:151
msgid "## Declaring Types"
msgstr "## 型を宣言する"

#: ../docs/GettingStarted.md:153
msgid ""
"Some tags also have an optional \"types\" field which let us declare a list "
"of\n"
"types associated with the tag. For instance, a return tag can be declared\n"
"with or without a types field."
msgstr ""
"いくつかのタグは省略可能な\"型\"フィールドも持つ。\n"
"それは関連する型のリストを宣言する場所となる。\n"
"例えば、@returnタグは、\n"
"型フィールドがあってもなくても宣言できる。"

#: ../docs/GettingStarted.md:157
msgid ""
"    # @return [String, nil] the contents of our object or nil\n"
"    #   if the object has not been filled with data.\n"
"    def validate; end"
msgstr ""
"    # @return [String, nil] オブジェクトやnilとなる。\n"
"    #   nilはデータと共に内容が入っていない場合になる。(ここまでreturnのコメ"
"ント)\n"
"    def validate; end"

#: ../docs/GettingStarted.md:161
msgid ""
"    # We don't care about the \"type\" here:\n"
"    # @return the object\n"
"    def to_obj; end"
msgstr ""
"    # 以下の様に\"型\"を気にする必要はない\n"
"    # @return the object\n"
"    def to_obj; end"

#: ../docs/GettingStarted.md:165
msgid ""
"The list of types is in the form `[type1, type2, ...]` and is mostly free-"
"form,\n"
"so we can also specify duck-types or constant values. For example:"
msgstr ""
"この型のリストは `[type1, type2, ...]` の形式である。\n"
"そして大部分はフリーフォームとなる。\n"
"したがってダックタイプ、又は、定数を指定する。\n"
"例えば、"

#: ../docs/GettingStarted.md:168
msgid ""
"    # @param [#to_s] argname any object that responds to `#to_s`\n"
"    # @param [true, false] argname only true or false"
msgstr ""
"    # @param [#to_s] argname any object that responds to `#to_s`\n"
"    # @param [true, false] argname only true or false"

#: ../docs/GettingStarted.md:171
msgid ""
"Note the latter example can be replaced by the meta-type \"Boolean\".\n"
"Another meta-type is \"void\", which stands for \"no meaningful value\"\n"
"and is used for return values. These meta-types are by convention\n"
"only, but are recommended."
msgstr ""
"次の事に留意する。\n"
"後の例は、メタタイプの\"Boolean\"によって置換される。\n"
"他のメタタイプは\"void\"で\"意味のない値\"用であり、戻り値用に利用される。\n"
"これらのメタタイプは慣習で利用されるだけだが推奨される。"

#: ../docs/GettingStarted.md:176
msgid ""
"List types can be specified in the form `CollectionClass`.\n"
"For instance, consider the following Array that holds a set of Strings and\n"
"Symbols:"
msgstr ""
"型のリストは、`CollectionClass`形式の中で指定されることができる。\n"
"例として、以下のArrayはStringそしてSymbolのセットをもっていると考える。"

#: ../docs/GettingStarted.md:180
msgid ""
"    # @param [Array] list the list of strings and symbols."
msgstr "    # @param [Array] list the list of strings and symbols."

#: ../docs/GettingStarted.md:182
msgid ""
"We mentioned that these type fields are \"mostly\" free-form. In truth, "
"they\n"
"are defined \"by convention\". To view samples of common type "
"specifications\n"
"and recommended conventions for writing type specifications, see\n"
"[http://yardoc.org/types.html](http://yardoc.org/types.html). Note that "
"these\n"
"conventions may change every now and then, although we are working on a "
"more\n"
"\"formal\" type specification proposal."
msgstr ""
"我々が述べてきたこれらのフィールドの型は殆どがフリーフォームである。\n"
"実のところ,それらは慣習によって定義される。\n"
"型の指定用に一般的な型指定の例や推奨される慣習を調べるには、\n"
"[http://yardoc.org/types.html](http://yardoc.org/types.html)を参照\n"
"これらの慣習はいつの日か変更されるかもしれない、\n"
"けれども我々はより正式な型指定の提案に取りかかっている。"

#: ../docs/GettingStarted.md:189
msgid "## Documenting DSL Methods"
msgstr "## DSLメソッドを記述する"

#: ../docs/GettingStarted.md:191
msgid ""
"Application code in Ruby often makes use of DSL style metaprogrammed "
"methods.\n"
"The most common is the `attr_accessor` method, which of course has built-in\n"
"support in YARD. However, frameworks and libraries often expose custom\n"
"methods that perform similar metaprogramming tasks, and it is often useful\n"
"to document their functionality in your application. Consider the "
"`property`\n"
"method in a project like [DataMapper](http://datamapper.org), which creates\n"
"a typed attribute for a database model. The code might look like:"
msgstr ""
"Rubyの中のアプリケーションコードは、\n"
"DSLスタイルのメタプログラミングしたメソッドをよく利用する。\n"
"最も一般的なのは、 `attr_accessor` メソッドで、\n"
"もちろんYARDの中でビルトインサポートされている。\n"
"とはいうものの、フレームワークやライブラリでは、\n"
"大抵似たようなメタプログラミング作業を実行するカスタムメソッドを目にする。\n"
"そして、それはアプリケーションの中にある機能を記述する為に便利である。\n"
"[DataMapper](http://datamapper.org)のようにプロジェクトの中の `property` メソッドを考え、\n"
"そして、データベースモデル用の属性の型を作成すると\n"
"コー​​ドは次のようになる。"

#: ../docs/GettingStarted.md:199 ../docs/GettingStarted.md:209
#: ../docs/GettingStarted.md:263 ../docs/GettingStarted.md:293
msgid ""
"    class Post\n"
"      include DataMapper::Resource"
msgstr ""
"    class Post\n"
"      include DataMapper::Resource"

#: ../docs/GettingStarted.md:202
msgid ""
"      property :title, String\n"
"    end"
msgstr ""
"      property :title, String\n"
"    end"

#: ../docs/GettingStarted.md:205
msgid ""
"As of version 0.7.0, YARD will automatically pick up on these basic methods "
"if\n"
"you document them with a docstring. Therefore, simply adding some comments "
"to\n"
"the code will cause it to generate documentation:"
msgstr ""
"0.7.0版の時点で、もしあなたが今まで紹介した例のdocstringを記述した場合、\n"
"YARDは組み込みの基本メソッドによって自動的に取得するだろう。\n"
"したがって、簡単にドキュメントを生成しいくつかのコメントを追加するには、\n"
"以下の様に記述できる。"

#: ../docs/GettingStarted.md:212
msgid ""
"      # @return [String] the title property of the post\n"
"      property :title, String\n"
"    end"
msgstr ""
"      # @return [String] the title property of the post\n"
"      property :title, String\n"
"    end"

#: ../docs/GettingStarted.md:216
msgid ""
"Note that YARD uses the first argument in the method call to determine the\n"
"method name. In some cases, this would not be the method name, and you "
"would\n"
"need to declare it manually. You can do so with the `@!method` directive:"
msgstr ""
"次の事に留意する。\n"
"YARDはメソッド名を決定するのに、メソッド呼び出しの最初に引数を使う。\n"
"もし、これがメソッド名でない場合、手動で宣言する必要がある。\n"
"下の`@method`タグで宣言を行うことができる。"

#: ../docs/GettingStarted.md:220
msgid ""
"    # @!method foo\n"
"    create_a_foo_method"
msgstr ""
"    # @!method foo\n"
"    create_a_foo_method"

#: ../docs/GettingStarted.md:223
msgid ""
"The @!method directive can also accept a full method signature with "
"parameters:"
msgstr ""
"@!method 命令は\n"
"完全なメソッドのシグネチャ受け入れる事もできる。"

#: ../docs/GettingStarted.md:225
msgid ""
"    # @!method foo(name, opts = {})\n"
"    create_a_foo_method"
msgstr ""
"    # @!method foo(name, opts = {})\n"
"    create_a_foo_method"

#: ../docs/GettingStarted.md:228
msgid ""
"You can also set visibility and scope, or modify the method signature with\n"
"extra tags. The following adds documentation for a private class method:"
msgstr ""
"あなたは可視性やスコープも設定できたり、\n"
"追加のタグを用いメソッド用法を変更できる。\n"
"以下は、privateクラスメソッドに対してドキュメントに追加する。"

#: ../docs/GettingStarted.md:231
msgid ""
"    # @!method foo(opts = {})\n"
"    # The foo method!\n"
"    # @!scope class\n"
"    # @!visibility private\n"
"    create_a_private_foo_class_method"
msgstr ""
"    # @!method foo(opts = {})\n"
"    # The foo method!\n"
"    # @!scope class\n"
"    # @!visibility private\n"
"    create_a_private_foo_class_method"

#: ../docs/GettingStarted.md:237
msgid ""
"Finally, you can tag a method as an attribute by replacing the @!method\n"
"tag with @!attribute. The @!attribute directive allows for the flags [r], "
"[w],\n"
"or [rw] to declare a readonly, writeonly, or readwrite attribute, "
"respectively."
msgstr ""
"最終的に、@!attributeタグを用い@!methodタグを\n"
"置換する事によって属性の様にメソッドのタグが出来る。\n"
"読み込み専用,書込み専用,読み書きOK,個々に指定を宣言する為に\n"
"@!attribute指令は[r], [w], [rw]フラグ用に受け入れる\n"

#: ../docs/GettingStarted.md:241
msgid ""
"    # @!attribute [w]\n"
"    # The writeonly foo attribute!\n"
"    a_writeonly_attribute :foo"
msgstr ""
"    # @!attribute [w]\n"
"    # The writeonly foo attribute!\n"
"    a_writeonly_attribute :foo"

#: ../docs/GettingStarted.md:245
msgid ""
"(Note that if the name can be automatically detected, you do not need to\n"
"specify it in the @!method or @!attribute directives)"
msgstr ""
"(次のことに留意する。\n"
"名前が自動で認められる場合、@!methodや@!attributeタグの記入を\n"
"必要としないことに注意する。)"

#: ../docs/GettingStarted.md:248
msgid "However, you will notice a few drawbacks with this basic support:"
msgstr ""
"とはいうものの、あなたはこの基本サポートの備えるいくつかの欠点に気づくだろ"
"う。"

#: ../docs/GettingStarted.md:250
msgid ""
"1. There is a fair bit of duplication in such documentation. Specifically, "
"we\n"
"   repeat the term String and title twice in the property example.\n"
"2. We must write a code comment for this property to show up in the "
"documentation.\n"
"   If we do not write a comment, it is ignored."
msgstr ""
"1. このようなドキュメントでは重複を少し整形する。\n"
"   具体的には、繰り返しのString用語やproperty例の中の2度目のタイトル\n"
"2. 私達はドキュメントに表示する為、propertyでコードのコメントを書かなければな"
"らない。\n"
"   コメントを書かない場合、それは無視される。"

#: ../docs/GettingStarted.md:255
msgid "### Macros"
msgstr "### マクロ"

#: ../docs/GettingStarted.md:257
msgid ""
"Fortunately YARD 0.7.0 also adds macros, a powerful way to add support for\n"
"these DSL methods on the fly without writing extra plugins. Macros allow\n"
"you to interpolate arguments from the method call inside the docstring,\n"
"reducing duplication. If we re-wrote the `property` example from above\n"
"using a macro, it might look like:"
msgstr ""
"幸運にも、YARD 0.7.0はマクロも追加する。\n"
"これらのDSLメソッドは余計なプラグインを記述することなく\n"
"オンザフライでサポートを追加する為の強力な方法となる。\n"
"マクロは重複を減らしたり、docstring内部のメソッド\n"
"呼び出しから引数を挿入することを可能にする。\n"
"もし私達が、例の`property`をマクロを用いて書き直した場合は、\n"
"次のようになる。"

#: ../docs/GettingStarted.md:266
msgid ""
"      # @!macro dm.property\n"
"      # @return [$2] the $1 $0 of the post\n"
"      property :title, String\n"
"    end"
msgstr ""
"      # @!macro dm.property\n"
"      # @return [$2] the $1 $0 of the post\n"
"      property :title, String\n"
"    end"

#: ../docs/GettingStarted.md:271
msgid ""
"(Note that $0 represents the method call, in this case `property`. The rest\n"
"are arguments in the method call.)"
msgstr ""
"(次の事に留意する。\n"
"$0はメソッド呼び出しを表す、この場合は`property`となる。\n"
"残りはメソッド呼び出しの引数となる。)"

#: ../docs/GettingStarted.md:274
msgid ""
"The above example is equivalent to the first version shown in the previous\n"
"section. There is also some extra benefit to using this macro, in that we\n"
"can re-apply it to any other property in our class by simply calling on\n"
"the macro. The following:"
msgstr ""
"上の例は、前項の中の最初の訳文と等しい。\n"
"このマクロを使うことによっていくつかの特別な恩恵もある。\n"
"それは、マクロを簡単に呼び出すことによって、\n"
"例のクラスの中の他のpropertyに最適用できる。\n"
"以下の例は、"

#: ../docs/GettingStarted.md:279
msgid ""
"    # @!macro dm.property\n"
"    property :view_count, Integer"
msgstr ""
"    # @!macro dm.property\n"
"    property :view_count, Integer"

#: ../docs/GettingStarted.md:282
msgid "Would be equivalent to:"
msgstr "下と同等になる。"

#: ../docs/GettingStarted.md:284
msgid ""
"    # @return [Integer] the view_count property of the post\n"
"    property :view_count, Integer"
msgstr ""
"    # @return [Integer] the view_count property of the post\n"
"    property :view_count, Integer"

#: ../docs/GettingStarted.md:287
msgid ""
"Finally, macros can be \"attached\" to method calls, allowing them to be "
"implicitly\n"
"activated every time the method call is seen in the source code of the "
"class,\n"
"or an inheriting class. By simply adding the `[attach]` flag, the macro\n"
"becomes implicit on future calls. All of the properties below get "
"documented\n"
"by using this snippet:"
msgstr ""
"最終的に、メソッド呼び出しの為に\"追加\"されるマクロは、\n"
"クラスや継承クラスのソースコードの中で見られるメソッド呼び出しを\n"
"いつでも起動できる様に実装される。\n"
"単に `[attach]` フラグを追加することで、\n"
"そのマクロは将来の呼び出しで暗黙的に呼び出される。\n"
"下記のすべてのpropertyは、このスニペットを使用してドキュメントになる。"

#: ../docs/GettingStarted.md:296
msgid ""
"      # @!macro [attach] dm.property\n"
"      # @return [$2] the $1 $0 of the post\n"
"      property :title, String\n"
"      property :view_count, Integer\n"
"      property :email, String\n"
"    end"
msgstr ""
"      # @!macro [attach] dm.property\n"
"      # @return [$2] the $1 $0 of the post\n"
"      property :title, String\n"
"      property :view_count, Integer\n"
"      property :email, String\n"
"    end"

#: ../docs/GettingStarted.md:303
msgid ""
"You can read more about macros in the {file:docs/Tags.md Tags Overview} "
"document."
msgstr ""
"もっとマクロについて知りたい場合は\n"
"{file:docs/Tags.md Tags Overview}ドキュメントの中で読むことができる。"

#: ../docs/GettingStarted.md:305
msgid "## Customized YARD Markup"
msgstr "## YARDマークアップのカスタマイズ"

#: ../docs/GettingStarted.md:307
msgid ""
"YARD supports a special syntax to link to other code objects, URLs, files,\n"
"or embed docstrings between documents. This syntax has the general form\n"
"of `{Name OptionalTitle}` (where `OptionalTitle` can have spaces, but "
"`Name`\n"
"cannot)."
msgstr ""
"YARDは他のコードオブジェクト、URL、ファイル、\n"
"ドキュメントの間で組み込むdocstringへのリンクの特別な構文をサポートする。\n"
"この構文は、`{Name OptionalTitle}`の一般的な型を持っている。\n"
"(`OptionalTitle`内でスペースを入れることはできるが、\n"
" `Name`は入れることができない)"

#: ../docs/GettingStarted.md:312
msgid "### Linking Objects `{...}`"
msgstr "### オブジェクトのリンク `{...}`"

#: ../docs/GettingStarted.md:314
msgid ""
"To link another \"object\" (class, method, module, etc.), use the format:"
msgstr ""
"他の\"オブジェクト\"(クラス、メソッド、モジュール、 etc.)へのリンクには、\n"
"以下の書式を使う:"

#: ../docs/GettingStarted.md:316
msgid ""
"    {ObjectName#method OPTIONAL_TITLE}\n"
"    {Class::CONSTANT My constant's title}\n"
"    {#method_inside_current_namespace}"
msgstr ""
"    {ObjectName#method OPTIONAL_TITLE}\n"
"    {Class::CONSTANT My constant's title}\n"
"    {#method_inside_current_namespace}"

#: ../docs/GettingStarted.md:320
msgid ""
"Without an explicit title, YARD will use the relative path to the object as\n"
"the link name. Note that you can also use relative paths inside the object\n"
"path to refer to an object inside the same namespace as your current "
"docstring."
msgstr ""
"明確なタイトルが無い時、YARDはオブジェクトのリンク名に相対パスを使う。\n"
"次の事に留意する。\n"
"現在のdocstringのように同じnamespace内にあるオブジェクトを参照する為に、\n"
"そのオブジェクトパス内で相対パスを使える。"

#: ../docs/GettingStarted.md:324
msgid ""
"Note that the `@see` tag automatically links its data. You should not use\n"
"the link syntax in this tag:"
msgstr ""
"次の事に留意する。`@see`タグは自動リンクとなるので、\n"
"このタグのなかでリンク構文を使うべきではない。"

#: ../docs/GettingStarted.md:327
msgid ""
"    # @see #methodname   <- Correct.\n"
"    # @see {#methodname} <- Incorrect."
msgstr ""
"    # @see #methodname   <- 正.\n"
"    # @see {#methodname} <- 誤."

#: ../docs/GettingStarted.md:330
msgid "If you want to use a Hash, prefix the first { with \"!\":"
msgstr ""
"もしあなたがハッシュを使う為にプレフィックスに、\n"
"最初の{がほしい場合\"!\"を一緒につける。"

#: ../docs/GettingStarted.md:332
msgid "   # !{ :some_key => 'value' }"
msgstr "   # !{ :some_key => 'value' }"

#: ../docs/GettingStarted.md:334
msgid "### Linking URLs `{http://...}`"
msgstr "### URLのリンク `{http://...}`"

#: ../docs/GettingStarted.md:336
msgid "URLs are also linked using this `{...}` syntax:"
msgstr "URLはこの`{...}`構文を用いリンクされる。"

#: ../docs/GettingStarted.md:338
msgid ""
"    {http://example.com Optional Title}\n"
"    {mailto:email@example.com}"
msgstr ""
"    {http://example.com Optional Title}\n"
"    {mailto:email@example.com}"

#: ../docs/GettingStarted.md:341
msgid "### Linking Files `{file:...}`"
msgstr "### ファイルのリンク `{file:...}`"

#: ../docs/GettingStarted.md:343
msgid ""
"Files can also be linked using this same syntax but by adding the `file:`\n"
"prefix to the object name. Files refer to extra readme files you added\n"
"via the command-line. Consider the following examples:"
msgstr ""
"ファイルも同じ構文を使ってリンクされる、\n"
"しかし、オブジェクト名のプレフィックスに`file:`が追加される。\n"
"ファイルはあなたがコマンドライン経由で追加した特別なreadmeファイルを参照す"
"る。\n"
"次の例を考えてみる。"

#: ../docs/GettingStarted.md:347
msgid ""
"    {file:docs/GettingStarted.md Getting Started}\n"
"    {file:mypage.html Name#anchor}"
msgstr ""
"    {file:docs/GettingStarted.md Getting Started}\n"
"    {file:mypage.html Name#anchor}"

#: ../docs/GettingStarted.md:350
msgid ""
"As shown, you can also add an optional `#anchor` if the page is an HTML link."
msgstr ""
"上のように、\n"
"そのページがHTMLリンク可能な場合は省略可能な`#anchor`を追加できる。"

#: ../docs/GettingStarted.md:352
msgid "### Embedding Docstrings `{include:...}`"
msgstr "### Docstringの組み込み `{include:...}`"

#: ../docs/GettingStarted.md:354
msgid ""
"We saw the `(see ...)` syntax above, which allowed us to link an entire "
"docstring\n"
"with another. Sometimes, however, we just want to copy docstring text "
"without\n"
"tags. Using the same `{...}` syntax, but using the `include:` prefix, we "
"can\n"
"embed a docstring (minus tags) at a specific point in the text."
msgstr ""
"私達は上の`{see ...}`構文を見たが、\n"
"それは他と一緒にdocstring丸ごとリンクすることを可能にした。\n"
"とはいうものの、タグなしでdocstringのテキストコピーのみ欲しい場合がある。\n"
"そこで、同じ`{...}`構文と`include:`プレフィックスを用いると、\n"
"テキストの特定の場所で、タグなしのdocstringを組み込むことができる。"

#: ../docs/GettingStarted.md:359
msgid ""
"    # This class is cool\n"
"    # @abstract\n"
"    class Foo; end"
msgstr ""
"    # This class is cool\n"
"    # @abstract\n"
"    class Foo; end"

#: ../docs/GettingStarted.md:363
msgid ""
"    # This is another class. {include:Foo} too!\n"
"    class Bar; end"
msgstr ""
"    # This is another class. {include:Foo} too!\n"
"    class Bar; end"

#: ../docs/GettingStarted.md:366
msgid "The docstring for Bar becomes:"
msgstr "docstringは次のようになる。"

#: ../docs/GettingStarted.md:368
msgid "    \"This is another class. This class is cool too!\""
msgstr "    \"This is another class. This class is cool too!\""

#: ../docs/GettingStarted.md:370
msgid "### Embedding Files `{include:file:...}`"
msgstr "### ファイルの埋め込み `{include:file:...}`"

#: ../docs/GettingStarted.md:372
msgid ""
"You can embed the contents of files using `{include:file:path/to/file}`,\n"
"similar to the `{include:OBJECT}` tag above. If the file uses a specific "
"markup\n"
"type, it will be applied and embedded as marked up text. The following\n"
"shows how the tag can be used inside of comments:"
msgstr ""
"`{include:file:path/to/file}`は上の`{include:OBJECT}`タグと同様に\n"
"使う事によってファイルの内容を埋め込む事ができる。\n"
"ファイルが特定のマークアップの型を使う場合は,\n"
"マークアップテキストとして埋め込まれ適用される。\n"
"次はコメントの内部で利用されるタグにどのようなものがあるか一覧する。"

#: ../docs/GettingStarted.md:377
msgid ""
"    # Here is an example of a highlighted Ruby file:\n"
"    #\n"
"    # {include:file:examples/test.rb}"
msgstr ""
"    # これはハイライトされたRubyのファイルの例である\n"
"    #\n"
"    # {include:file:examples/test.rb}"

#: ../docs/GettingStarted.md:381
msgid "### Rendering Objects `{render:...}`"
msgstr "### オブジェクトのレンダリング `{render:...}`"

#: ../docs/GettingStarted.md:383
msgid ""
"Entire objects can also be rendered in place in documentation. This can be\n"
"used for guide-style documentation which does not document the entire "
"source\n"
"tree, but instead selectively renders important classes or methods. "
"Consider\n"
"the following documentation inside of a README file:"
msgstr ""
"全てのオブジェクトはドキュメントの適当な位置に表示される。\n"
"{render:...}はガイドスタイルドキュメント用に使われるが\n"
"それは全てのソースツリーを記述しない。\n"
"しかし、代わりに重要なクラスやメソッドを選択的に表示する。\n"
"以下のREADMEファイルの内部のドキュメントを考えてみる。"

#: ../docs/GettingStarted.md:388
msgid ""
"    !!!plain\n"
"    = igLatinPay!"
msgstr ""
"    !!!plain\n"
"    = igLatinPay!"

#: ../docs/GettingStarted.md:391
msgid ""
"    This library adds pig latin methods to the string class, allowing you\n"
"    to transform sentences into pig latin."
msgstr ""
"    このライブラリはstring classの為にpig latinメソッドを追加する。\n"
"    pig latinへ文を変換する事を可能にする。"

#: ../docs/GettingStarted.md:394
msgid "    {render:String#pig_latin}"
msgstr "    {render:String#pig_latin}"

#: ../docs/GettingStarted.md:396
msgid "    You can also un-pig-latin-ify a word or sentence:"
msgstr "    あなたは単語や文を以下の様にpig-latinにしないこともできる。"

#: ../docs/GettingStarted.md:398
msgid "    {render:String#de_pig_latin}"
msgstr "    {render:String#de_pig_latin}"

#: ../docs/GettingStarted.md:400
msgid ""
"The above would render the methods in place inside the README document,\n"
"allowing you to summarize a small library in a single file."
msgstr ""
"上のように書くと、READMEドキュメント内部の{}の中のメソッドを表示する。\n"
"これによって、一つのファイルの中にライブラリの説明を要約できる。"

#: ../docs/GettingStarted.md:403
msgid ""
msgstr ""

#: ../docs/GettingStarted.md:405
msgid "## Using YARD to Generate Documentation"
msgstr "## ドキュメントを生成するYARDの使い方"

#: ../docs/GettingStarted.md:407
msgid "### `yard` Executable"
msgstr "### 実行可能な`yard`コマンド"

#: ../docs/GettingStarted.md:409
msgid ""
"YARD ships with a single executable aptly named `yard`. In addition to\n"
"generating standard documentation for your project, you would use this tool\n"
"if you wanted to:"
msgstr ""
"YARDは単一で適切に実行可能な'yard'コマンドとして送り出す。\n"
"あなたのプロジェクトの為の標準のドキュメントを生成することに加え、\n"
"次のツールも使える。"

#: ../docs/GettingStarted.md:413
msgid ""
"* Document all installed gems\n"
"* Run a local documentation server\n"
"* Generate UML diagrams using [Graphviz][graphviz]\n"
"* View `ri`-style documentation\n"
"* Diff your documentation\n"
"* Analyze documentation statistics."
msgstr ""
"* 全てのインストール済のジェムを記述する\n"
"* ローカルドキュメントサーバーを起動する\n"
"* [Graphviz][graphviz]によってUML図を生成する\n"
"* `ri`スタイルドキュメントを一覧する\n"
"* あなたのドキュメントの差分を見る\n"
"* ドキュメントの統計を解析する"

#: ../docs/GettingStarted.md:420
msgid ""
"The following commands are available in YARD 0.6.x (see `yard help` for a\n"
"full list):"
msgstr ""
"以下のコマンドは、YARD 0.6.xで利用できる。\n"
"(`yard help`コマンドで全てのリストが見れる)"

#: ../docs/GettingStarted.md:423
msgid "    Usage: yard  [options]"
msgstr ""
"    !!!plain\n"
"    Usage: yard <コマンド> [オプション...]"

#: ../docs/GettingStarted.md:425
msgid ""
"    Commands:\n"
"    config   Views or edits current global configuration\n"
"    diff     Returns the object diff of two gems or .yardoc files\n"
"    doc      Generates documentation\n"
"    gems     Builds YARD index for gems\n"
"    graph    Graphs class diagram using Graphviz\n"
"    help     Retrieves help for a command\n"
"    ri       A tool to view documentation in the console like `ri`\n"
"    server   Runs a local documentation server\n"
"    stats    Prints documentation statistics on a set of files"
msgstr ""
"    Commands:\n"
"    config   設定を見るか、現在の全体的な構成を編集する\n"
"    diff     2つのgemsまたは、'.yardoc'ファイルのオブジェクトの差分を返す\n"
"    doc      ドキュメントを生成する\n"
"    gems     gemsにYARDのインデックスを組み込む\n"
"    graph    Graphvizを用いてクラス図を図示する\n"
"    help     ヘルプコマンド\n"
"    ri       `ri`のようにコンソールの中でドキュメントを作成する\n"
"    server   ローカルなドキュメント作成サーバーを起動する\n"
"    stats    設定したファイルのドキュメントのステータスを出力する"

#: ../docs/GettingStarted.md:436
msgid ""
"Note that `yardoc` is an alias for `yard doc`, and `yri` is an alias for\n"
"`yard ri`. These commands are maintained for backwards compatibility."
msgstr ""
"次の事に留意する。\n"
"`yardoc`は、`yard doc`コマンドのエイリアスで,\n"
"`yri`は`yard ri`コマンドのエイリアスとなる。\n"
"これらのコマンドは、後方互換が維持されている。"

#: ../docs/GettingStarted.md:439
msgid "### `.yardopts` Options File"
msgstr "### `.yardopts` 設定ファイル"

#: ../docs/GettingStarted.md:441
msgid ""
"Unless your documentation is very small, you'll end up needing to run "
"`yardoc`\n"
"with many options.  The `yardoc` tool will use the options found in this "
"file.\n"
"It is recommended to check this in to your repository and distribute it "
"with\n"
"your source. This file is placed at the root of your project (in the "
"directory\n"
"you run `yardoc` from) and contains all of arguments you would otherwise "
"pass\n"
"to the command-line tool. For instance, if you often type:"
msgstr ""
"ドキュメントが小さくない限り、\n"
"結局`yardoc`コマンドと一緒にたくさんの設定を必要としているだろう。\n"
"`yardoc`コマンドは.yardoptsファイルの中で見つけた設定を使う。\n"
"その為、あなたのリポジトリに入れてソースと一緒に配布することを推奨する。\n"
"このファイルはあなたのプロジェクトのルートに位置する。\n"
"(あなたが`yardoc`を起動するディレクトリの中からの)\n"
"そして、全ての引数を含んでなければコマンドラインではパスしないだろう。\n"
"例えば、以下をよくタイプするならば、"

#: ../docs/GettingStarted.md:448
msgid "    yardoc --no-private --protected app/**/*.rb - README LEGAL COPYING"
msgstr "    yardoc --no-private --protected app/**/*.rb - README LEGAL COPYING"

#: ../docs/GettingStarted.md:450
msgid "You can place the following into your `.yardopts`:"
msgstr "下の内容を`.yardopts`の中へ書くことで設定できる。"

#: ../docs/GettingStarted.md:452
msgid "    --no-private --protected app/**/*.rb - README LEGAL COPYING"
msgstr "    --no-private --protected app/**/*.rb - README LEGAL COPYING"

#: ../docs/GettingStarted.md:454
msgid "This way, you only need to type:"
msgstr "この方法を用いると、以下をタイプするだけでよい。"

#: ../docs/GettingStarted.md:456
msgid "    yardoc"
msgstr "    yardoc"

#: ../docs/GettingStarted.md:458
msgid ""
"Any extra switches passed to the command-line now will be appended to your\n"
"`.yardopts` options."
msgstr "あなたの`.yardopts`設定にコマンドラインに渡された引数は追加される。"

#: ../docs/GettingStarted.md:461
msgid ""
"Note that options for `yardoc` are discussed in the {file:README.md "
"README},\n"
"and a full overview of the `.yardopts` file can be found in {YARD::CLI::"
"Yardoc}."
msgstr ""
"次の事に留意する。\n"
"`yardoc`用のオプションは {file:README.md README} の中で説明される。\n"
"全ての`.yardopts`ファイルの概要は {YARD::CLI::Yardoc} の中で見つけられる。"

#: ../docs/GettingStarted.md:464
msgid "### Documenting Extra Files"
msgstr "### 追加のファイルを記述する"

#: ../docs/GettingStarted.md:466
msgid ""
"\"Extra files\" are extra guide style documents that help to give a brief "
"overview\n"
"of how to use your library/framework, as well as any extra information that\n"
"might be vital for your users. The most common \"extra file\" is the "
"README,\n"
"which is automatically detected by YARD if found in the root of your "
"project\n"
"(any file starting with `README*`). You can specify extra files on the "
"command\n"
"line (or in the `.yardopts` file) by listing them after the '-' separator:"
msgstr ""
"\"Extra files\"はライブラリやフレームワークで使うのにも、\n"
"ユーザーにとっての何らかの特別な情報にも、\n"
"簡単な概要を提供することを助ける\n"
"追加のガイドスタイルドキュメントとなる。\n"
"最も一般的な\"extra file\"はREADMEで、\n"
"それは、もしあなたのプロジェクトのルートの中で見つけた場合、YARDによって自動"
"で検出する。\n"
"(`README*`で始まる何らかのファイル)\n"
"以下の用に、追加のファイルの前に'-'セパレータを記述することによって\n"
"コマンドライン上で(又は,`.yardopts`ファイル内で)指定できる。"

#: ../docs/GettingStarted.md:473
msgid "    yardoc lib/**/*.rb ext/**/*.c - LICENSE.txt"
msgstr "    yardoc lib/**/*.rb ext/**/*.c - LICENSE.txt"

#: ../docs/GettingStarted.md:475
msgid ""
"Note that the README will automatically be picked up, so you do not need to\n"
"specify it. If you don't want to modify the default file globs, you can "
"ignore\n"
"the first set of arguments:"
msgstr ""
"次の事に留意する。\n"
"READMEは、自動で選択される。\n"
"従って、それを指定する必要はない。\n"
"もしデフォルトのファイルglobを変更しないなら\n"
"最初に設定する引数は無視できる。"

#: ../docs/GettingStarted.md:479
msgid "    yardoc - LICENSE.txt"
msgstr "    yardoc - LICENSE.txt"

#: ../docs/GettingStarted.md:481
msgid ""
"Below you can read about how to customize the look of these extra files, "
"both\n"
"with markup and pretty titles."
msgstr ""
"以降は追加のファイルをカスタマイズする方法について読むことができる。\n"
"これによってマークアップやいいタイトル両方を使用できる。"

#: ../docs/GettingStarted.md:484
msgid "#### Adding Meta-Data to Extra Files"
msgstr "#### 追加のファイルにメタデータを追加する"

#: ../docs/GettingStarted.md:486
msgid ""
"You can add YARD-style `@tag` metadata to the top of any extra file if "
"prefixed\n"
"by a `#` hash comment. YARD allows for arbitrary meta-data, but pays "
"special\n"
"attention to the tags `@markup`, `@encoding`, and `@title`. Note that there\n"
"cannot be any whitespace before the tags. Here is an example of some tag "
"data\n"
"in a README:"
msgstr ""
"`#`のハッシュコメントによってプレフィックスした場合、\n"
"任意の追加のファイルのトップにYARDスタイルの`@tag`メタデータを追加できる。\n"
"YARDは任意のメタデータを受け入れる。\n"
"しかし`@markup`,`@encoding`,`@title`タグには特別な注意を払わなければならない。\n"
"次の事に留意する。\n"
"タグの前に空白があってはならない。\n"
"これはREADMEの中のいくつかのタグデータの例:"

#: ../docs/GettingStarted.md:492
msgid ""
"    # @markup markdown\n"
"    # @title The Best Library in the World!\n"
"    # @author The Author Name"
msgstr ""
"    # @markup markdown\n"
"    # @title The Best Library in the World!\n"
"    # @author The Author Name"

#: ../docs/GettingStarted.md:496
msgid "    This is the best library you will ever meet. Lipsum ..."
msgstr "    これはあなたが出会う最高のライブラリとなる。以下略..."

#: ../docs/GettingStarted.md:498
msgid ""
"The `@markup` tag allows you to specify a markup format to use for the "
"file,\n"
"including \"markdown\", \"textile\", \"rdoc\", \"ruby\", \"text\", \"html\", "
"or \"none\"\n"
"(no markup). This can be used when the markup cannot be auto-detected using\n"
"the extension of the filename, if the file has no extension, or if you want\n"
"to override the auto-detection."
msgstr ""
"`@markup`タグは、\"markdown\", \"textile\", \"rdoc\", \"ruby\", \n"
"\"text\", \"html\", \"none\"(no markup)を含んでいるファイルを扱えるよう、\n"
"マークアップ書式の指定を可能にする。\n"
"このマークアップはファイル名の拡張子を自動検出できなかった時や、\n"
"ファイル名の拡張子がない時や、\n"
"あなたが(拡張子の)自動検出を上書きしたい時に使われる。"

#: ../docs/GettingStarted.md:504
msgid ""
"By using `@encoding` you can specify a non-standard encoding. Note that\n"
"`yardoc --charset` sets the global encoding (for all comments / files),\n"
"so if you are using unicode across all your files, you can specify it "
"there.\n"
"Using the `@encoding` tag might be used to override the default global\n"
"charset, say, if you had a localized `README.jp` file with SJIS data.\n"
"Also note that this only affects Ruby 1.9.x, as Ruby 1.8 is not properly\n"
"encoding aware."
msgstr ""
"`@encoding`を使用することによって、\n"
"あなたは非標準のエンコーディングを指定できる。\n"
"次の事に留意する。\n"
"`yardoc --charset`は全体のエンコーディングを設定する(全てのコメント/ファイル)、\n"
"なので、もしあなたが全てのファイルでユニコードを使っているならこれを指定できる。\n"
"例えば、ローカライズした`README.jp`ファイルとSJISデータをもっていたら\n"
"`@encoding`タグを使うことによって、default global charsetを上書きする為に\n"
"使うことができる。\n"
"又、これはRuby1.9.xにだけ作用する、\n"
"Ruby1.8については適切なエンコーディングになっていない。"

#: ../docs/GettingStarted.md:512
msgid ""
"The `@title` tag allows you to specify a full title name for the document.\n"
"By default, YARD uses the filename as the title of the document and lists\n"
"it in the file list in the index and file menu. In some cases, the file "
"name\n"
"might not be descriptive enough, so YARD allows you to specify a full title:"
msgstr ""
"`@title`タグはそのドキュメントでフルタイトル名による指定を許可する。\n"
"デフォルトでは、YARDはドキュメントのタイトルにファイル名を使う。\n"
"そして、ファイルリストの中のインデックスやファイルメニューを列挙する。\n"
"一部の例では、ファイル名は十分に説明できないかもしれない、\n"
"その為、YARDはあなたがフルタイトルを指定することを認めている。"

#: ../docs/GettingStarted.md:517
msgid ""
"    contents of TITLE.txt:\n"
"    # @title The Title of The Document"
msgstr ""
"    contents of TITLE.txt:\n"
"    # @title The Title of The Document"

#: ../docs/GettingStarted.md:520
msgid ""
"Currently all other meta-data is hidden from view, though accessible\n"
"programmatically using the {YARD::CodeObjects::ExtraFileObject} class."
msgstr ""
"現在の全ての他のメタデータは一覧から隠される。そうはいうものの、\n"
"{YARD::CodeObjects::ExtraFileObject}クラスによってプログラムにアクセス可能である。"

#: ../docs/GettingStarted.md:523
msgid ""
msgstr ""

#: ../docs/GettingStarted.md:525
msgid "## Configuring YARD"
msgstr "## YARDを構成する"

#: ../docs/GettingStarted.md:527
msgid ""
"YARD (0.6.2+) supports a global configuration file stored in `~/.yard/"
"config`.\n"
"This file is stored as a YAML file and can contain arbitrary keys and "
"values\n"
"that can be used by YARD at run-time. YARD defines specific keys that are "
"used\n"
"to control various features, and they are listed in {YARD::Config::"
"DEFAULT_CONFIG_OPTIONS}.\n"
"A sample configuration file might look like:"
msgstr ""
"YARD (0.6.2)以降は`~/.yard/config`の中に格納した全体構成ファイルをサポートす"
"る。\n"
"このファイルはYAMLファイルのように格納され、\n"
"任意のキーと実行時にYARDによって利用できる値を含むことができる。\n"
"YARDは様々な機能を制御する為に使われるので特定のキーを定義する。\n"
"それは{YARD::Config::DEFAULT_CONFIG_OPTIONS}の中で列挙される。\n"
"サンプルの設定ファイルは次のようになる。"

#: ../docs/GettingStarted.md:533 ../docs/WhatsNew.md:759
msgid ""
"    :load_plugins: false\n"
"    :ignored_plugins:\n"
"      - my_plugin\n"
"      - my_other_plugin\n"
"    :autoload_plugins:\n"
"      - my_autoload_plugin\n"
"    :safe_mode: false"
msgstr ""
"    :load_plugins: false\n"
"    :ignored_plugins:\n"
"      - my_plugin\n"
"      - my_other_plugin\n"
"    :autoload_plugins:\n"
"      - my_autoload_plugin\n"
"    :safe_mode: false"

#: ../docs/GettingStarted.md:541
msgid ""
"You can also view and edit these configuration options from the commandline\n"
"using the `yard config` command. To list your configuration, use `yard "
"config --list`.\n"
"To view a key, use `yard config ITEM`, and to set it, use `yard config ITEM "
"VALUE`."
msgstr ""
"`yard config`コマンドを使って調べたり、構成設定を編集することもできる。\n"
"構成をリストするには、`yard config --list`を使う。\n"
"キーを調べるには、`yard config ITEM`, や、その値を設定する為に`yard config "
"ITEM VALUE`を使う。"

#: ../docs/GettingStarted.md:545
msgid ""
msgstr ""

#: ../docs/GettingStarted.md:547
msgid "## Extending YARD"
msgstr "## YARDを拡張する"

#: ../docs/GettingStarted.md:549
msgid ""
"There are many ways to extend YARD to support non-standard Ruby syntax "
"(DSLs),\n"
"add new meta-data tags or programmatically access the intermediate metadata\n"
"and documentation from code. An overview of YARD's full architecture can be\n"
"found in the {file:docs/Overview.md} document."
msgstr ""
"非標準のRuby構文(DSL)をサポートするのにYARDを拡張するための沢山の方法がある。\n"
"新しいメタデータタグの追加や\n"
"プログラム的に中間のメタデータにアクセスする方法、\n"
"コードから記述する方法など。\n"
"YARDの全体構造の概要は、\n"
"{file:docs/Overview.md}ドキュメントの中で見つけられる。"

#: ../docs/GettingStarted.md:554
msgid ""
"For information on adding support for Ruby DSLs, see the {file:docs/Handlers."
"md}\n"
"and {file:docs/Parser.md} architecture documents."
msgstr ""
"RubyDSLサポートを追加する方法については、\n"
"{file:docs/Handlers.md}や{file:docs/Parser.md}構造のドキュメントを参照。"

#: ../docs/GettingStarted.md:557
msgid "For information on adding extra tags, see {file:docs/Tags.md}."
msgstr "特別なタグを追加する方法は{file:docs/Tags.md}を参照。"

#: ../docs/GettingStarted.md:559
msgid ""
"For information on accessing the data YARD stores about your documentation,\n"
"look at the {file:docs/CodeObjects.md} architecture document."
msgstr ""
"あなたのドキュメントについて格納したYARDのデータがアクセスする方法は、\n"
"{file:docs/CodeObjects.md}構造ドキュメント参照。"

#: ../docs/GettingStarted.md:562
msgid ""
msgstr ""

#: ../docs/GettingStarted.md:564
msgid "## Templating YARD"
msgstr "## YARDのテンプレートを作る"

#: ../docs/GettingStarted.md:566
msgid ""
"In many cases you may want to change the style of YARD's templates or add "
"extra\n"
"information after extending it. The {file:docs/Templates.md} architecture\n"
"document covers the basics of how YARD's templating system works."
msgstr ""
"多くの場合、あなたがYARDテンプレートのスタイルを変える為や\n"
"特別な情報を後で拡張し追加する為に必要だろう。\n"
"{file:docs/Templates.md}構造ドキュメントは、\n"
"YARDテンプレートシステム作業の基本をカバーする。"

#: ../docs/GettingStarted.md:570
msgid ""
msgstr ""

#: ../docs/GettingStarted.md:572
msgid "## Plugin Support"
msgstr "## プラグインサポート"

#: ../docs/GettingStarted.md:574
msgid ""
"As of 0.4, YARD will automatically load any gem named with the prefix of\n"
"`yard-` or `yard_`. You can use this to load a custom plugin that\n"
"[extend](#extending) YARD's functionality. A good example of this\n"
"is the [yard-rspec][yard-rspec] plugin, which adds [RSpec][rspec] "
"specifications\n"
"to your documentation (`yardoc` and `yri`). You can try it out by "
"installing\n"
"the gem or cloning the project and trying the example:"
msgstr ""
"0.4以降、YARDは`yard-`や `yard_`から始まる名前のgemを\n"
"自動でロードするだろう。あなたはカスタムプラグインをロードする為に\n"
"YARDの機能の[extend](#extending)を使える。\n"
"これの良い例は[yard-rspec][yard-rspec] プラグインで、\n"
"ドキュメント(`yardoc` and `yri`)に[RSpec][rspec]の仕様を追加する。\n"
"gemをインストールすることによって、\n"
"またはプロジェクトをクローンすることで試すことができる。\n"
"例を以下に示す。"

#: ../docs/GettingStarted.md:581
msgid ""
"    $ gem install yard-rspec -s http://gemcutter.org\n"
"    or\n"
"    $ git clone git://github.com/lsegal/yard-spec-plugin"
msgstr ""
"    $ gem install yard-rspec -s http://gemcutter.org\n"
"    or\n"
"    $ git clone git://github.com/lsegal/yard-spec-plugin"

#: ../docs/GettingStarted.md:585
msgid ""
"YARD also provides a way to temporarily disable plugins on a per-user "
"basis.\n"
"To disable a plugin create the file `~/.yard/ignored_plugins` with a list\n"
"of plugin names separated by newlines. Note that the `.yard` directory "
"might\n"
"not exist, so you may need to create it."
msgstr ""
"YARDはユーザーごとの基本のプラグインを\n"
"一時的に無効にする方法も提供する。\n"
"プラグインを無効にする為には、\n"
"`~/.yard/ignored_plugins`ファイルを作り\n"
"改行によって区切られた、プラグイン名をリストする。\n"
"次の事に留意する。\n"
"`.yard`ディレクトリは存在しない場合、\n"
"作成する必要がある。"

#: ../docs/GettingStarted.md:590
msgid ""
"[graphviz]:http://www.graphviz.org\n"
"[yard-rspec]:http://github.com/lsegal/yard-spec-plugin\n"
"[rspec]:http://rspec.info"
msgstr ""
"[graphviz]:http://www.graphviz.org\n"
"[yard-rspec]:http://github.com/lsegal/yard-spec-plugin\n"
"[rspec]:http://rspec.info"

# title
#: ../docs/Handlers.md:1
msgid "Handlers Architecture"
msgstr "ハンドラー構造"

#: ../docs/Handlers.md:3
msgid "# Handlers Architecture"
msgstr "# ハンドラー構造"

#: ../docs/Handlers.md:5
msgid ""
"Handlers allow the processing of parsed source code. Handling is done after\n"
"parsing to abstract away the implementation details of lexical and semantic\n"
"analysis on source and to only deal with the logic regarding recognizing\n"
"source statements as {file:docs/CodeObjects.md code objects}."
msgstr ""
"ハンドラーは、ソースコードを解析した処理を受け入れる。\n"
"これの処理は、実行する単語の詳細の抽象化を解析の後で行う。\n"
"そして、意味のあるソースの分析や、\n"
"ロジックに関しては{file:docs/CodeObjects.md code objects}のような\n"
"ソースステートメントの受け入れだけで扱う。"

#: ../docs/Handlers.md:10
msgid ""
"![Handlers Architecture Class Diagram](images/handlers-class-diagram.png)"
msgstr "![Handlers Architecture Class Diagram](images/handlers-class-diagram.png)"

#: ../docs/Handlers.md:12
msgid "## The Pipeline"
msgstr "## パイプライン"

#: ../docs/Handlers.md:14
msgid ""
"After the {file:docs/Parser.md parser component} finishes analyzing the\n"
"source, it is handed off for post-processing to the {YARD::Handlers::"
"Processor}\n"
"class, which is responsible for traversing the set of statements given by\n"
"the parser and delegating them to matching handlers. Handlers match when "
"the\n"
"{YARD::Handlers::Base.handles?} method returns true for a given statement.\n"
"The handler can then perform any action after being invoked by the "
"`process`\n"
"method."
msgstr ""
"{file:docs/Parser.md parser component}がソースを解析すると、\n"
"後処理する為に{YARD::Handlers::Processor} クラスに渡す。\n"
"そしてパーサーによって与えるステートメントの設定を辿ったり、\n"
"ハンドラーがマッチしているステートメントを委譲する責任がある。\n"
"{YARD::Handlers::Base.handles?}メソッドがtrueを返す時、\n"
"ハンドラーがマッチしているステートメントを与える。\n"
"ハンドラーは`process`メソッドによって呼び出した後で任意の処理を実行できる。"

#: ../docs/Handlers.md:22
msgid "## The Processor Class"
msgstr "## プロセッサークラス"

#: ../docs/Handlers.md:24
msgid ""
"The main purpose of the processor, as mentioned above, is to traverse "
"through\n"
"the list of statements given to it by the parser. The processor also keeps\n"
"state about what is being processed. For instance, the processor is what "
"keeps\n"
"track of the current namespace (the module or class an object is being "
"defined\n"
"in), scope (class or instance), file and owner. The owner refers to the "
"object\n"
"that is most directly responsible for the source statement being processed. "
"This\n"
"is most often the same as the namespace, except when parsing the body of a "
"method,\n"
"where the namespace would be the class/module the method is defined in and "
"the\n"
"owner would be the method object itself."
msgstr ""
"主なプロセッサーの目的は、上で述べたように、\n"
"パーサーによって与えるステートメントのリストを通じて辿ることである。\n"
"プロセッサーは処理されている状態について管理する。\n"
"例えば、プロセッサーは現在の\n"
"ネームスペース(モジュールやオブジェクトのクラスが定義される)、\n"
"スコープ(クラスやインスタンス)、ファイルとオーナー\n"
"を追跡する。\n"
"オーナーは、オブジェクトを参照する。\n"
"そのオブジェクトは処理されるソースステートメントに最も直接的な責任を持つ。\n"
"これは(参照するオブジェクトの対象は)、多くの場合ネームスペースと同じで、\n"
"メソッドの本体を解析した時を除き、\n"
"そのネームスペースでは、クラスやモジュール,メソッドが定義される。\n"
"そしてオーナーはメソッドオブジェクト自体となる。"

#: ../docs/Handlers.md:34
msgid "## Implementing a Handler"
msgstr "## ハンドラーを実装する"

#: ../docs/Handlers.md:36
msgid ""
"This section covers the basics of implementing a *new-style* Ruby handler. "
"For\n"
"details on implementing a legacy handler, see the \"API Differences\" "
"section below."
msgstr ""
"このセクションは *新しいスタイル* Rubyハンドラー処理の基本をカバーする。\n"
"レガシーなハンドラーの詳細は、\"API Differences\" セクション以下を参照。"

#: ../docs/Handlers.md:39
msgid ""
"a Ruby handler can be implemented simply by subclassing the {YARD::Handlers::"
"Ruby::Base}\n"
"class and declaring what node types or source to process with the {YARD::"
"Handlers::Base.handles handles}\n"
"class method. A very simple handler that handles a module definition would "
"be:"
msgstr ""
"Rubyハンドラーは処理の為に、\n"
"{YARD::Handlers::Base.handles handles}クラスメソッドを用い、\n"
"{YARD::Handlers::Ruby::Base}サブクラスや、\n"
"ノードタイプやソースを宣言することによって実行される。\n"
"モジュール定義の処理は次のような非常に簡単なハンドラーである。"

#: ../docs/Handlers.md:43
msgid ""
"    class MyModuleHandler < YARD::Handlers::Ruby::Base\n"
"      handles :module"
msgstr ""
"    class MyModuleHandler < YARD::Handlers::Ruby::Base\n"
"      handles :module"

#: ../docs/Handlers.md:46
msgid ""
"      def process\n"
"        puts \"Handling a module named #{statement[0].source}\"\n"
"      end\n"
"    end"
msgstr ""
"      def process\n"
"        puts \"Handling a module named #{statement[0].source}\"\n"
"      end\n"
"    end"

#: ../docs/Handlers.md:51
msgid ""
"For details on what nodes are, and what node types are, see the\n"
"{file:docs/Parser.md parser architecture document}."
msgstr ""
"ノードやノードの型の詳細については、\n"
"{file:docs/Parser.md パーサー構造のドキュメント}を参照。"

#: ../docs/Handlers.md:54
msgid ""
"In this case the node type being handled is the `:module` type. More than "
"one\n"
"node type or `handles` declarations may describe a single handler, for "
"instance,\n"
"a handler that handles class definitions should handle the `:class` and `:"
"sclass`\n"
"node types respectively (the latter refers to classes defined as `class << "
"Something`).\n"
"The {YARD::Handlers::Base#statement statement} attribute refers to the "
"current\n"
"node (or statement) that is being handled by the handler."
msgstr ""
"このケースの場合、処理されるノードタイプは `:module` タイプである。\n"
"複数のノードタイプや `handles` 宣言は一つのハンドラーを記述する。\n"
"例えば、ハンドラーはhandlesクラス定義が `:class` や\n"
"`:sclass` ノードタイプそれぞれを処理する。\n"
"(後者の:sclassは `class << Something` のようにクラス定義を参照する。)\n"
"{YARD::Handlers::Base#statement statement}属性は、\n"
"ハンドラーによって処理される現在のノード(やステートメントを)参照する。"

#: ../docs/Handlers.md:61
msgid "### Handling a Method Call"
msgstr "### メソッド呼び出しの処理"

#: ../docs/Handlers.md:63
msgid ""
"In some cases, a developer might need to handle a method call. The parser "
"can\n"
"express a method call in many AST forms, so to simplify this process, a "
"method\n"
"call can be handled by declaring the following in a `handles` statement:"
msgstr ""
"場合によって開発者は、メソッド呼び出し操作を必要とするかもしれない。\n"
"パーサーは多くのAST型(Abstract Syntax Tree)の中で、\n"
"メソッド呼び出しを表現できる。そして、この処理を簡素化する為に、\n"
"メソッド呼び出しは、次のような`handles`ステートメントの中で宣言される事によって処理される。"

#: ../docs/Handlers.md:67
msgid ""
"    class MyHandler < YARD::Handlers::Ruby::Base\n"
"      handles method_call(:describe)"
msgstr ""
"    class MyHandler < YARD::Handlers::Ruby::Base\n"
"      handles method_call(:describe)"

#: ../docs/Handlers.md:70
msgid ""
"      def process\n"
"        # Process the method call\n"
"      end\n"
"    end"
msgstr ""
"      def process\n"
"        # メソッド呼び出しを処理する\n"
"      end\n"
"    end"

#: ../docs/Handlers.md:75
msgid ""
"In this case we handle any of the method calls to method name `describe` "
"with\n"
"the following syntaxes:"
msgstr ""
"このケースでは、私達はメソッド名`describe`メソッドの呼び出しを\n"
"次の構文のように処理できる。"

#: ../docs/Handlers.md:78
msgid ""
"    describe(something)\n"
"    describe arg1, arg2, arg3\n"
"    describe(something) { perform_a_block }\n"
"    describe \"Something\" do\n"
"      a_block\n"
"    end"
msgstr ""
"    describe(something)\n"
"    describe arg1, arg2, arg3\n"
"    describe(something) { perform_a_block }\n"
"    describe \"Something\" do\n"
"      a_block\n"
"    end"

#: ../docs/Handlers.md:85
msgid "### Creating a new Code Object"
msgstr "### 新しいコードオブジェクトを作成する"

#: ../docs/Handlers.md:87
msgid ""
"Usually (but not always) handling is performed to create new code objects to "
"add\n"
"to the registry (for information about code objects, see {file:docs/"
"CodeObjects.md this document}).\n"
"Code objects should simply be created and added to the existing `namespace`. "
"This\n"
"will be enough to add them to the registry. There is also a convenience\n"
"{YARD::Handlers::Base#register register} method which quickly sets standard "
"attributed\n"
"on the newly created object, such as the file, line, source and docstring of "
"the\n"
"object. This method will be seen in the next example."
msgstr ""
"通常(しかし、いつもではない)の処理は、\n"
"レジストリーを追加する新しいコードオブジェクトの作成する為に実行される。\n"
"(コードオブジェクトについては{file:docs/CodeObjects.md このドキュメント}を参照)\n"
"コードオブジェクトは単純に既存の `namespace` に作成され追加される。\n"
"これは、レジストリにそれらを追加するために十分である。\n"
"便利な{YARD::Handlers::Base#register register}メソッドがあり、\n"
"これは新たに作成されるオブジェクト、ファイル、行、\n"
"ソースやオブジェクトのdocstringのような標準属性を素早く設定する。\n"
"このメソッドは次の例の中で見られるだろう。"

#: ../docs/Handlers.md:95
msgid "### Handling an Inner Block"
msgstr "### 内部のブロックの操作"

#: ../docs/Handlers.md:97
msgid ""
"By default, the parser gives the processor class a list of all the top "
"level\n"
"statements and the processor parses only those top level statements. If an "
"inner\n"
"block of a module, class, method declaration or even a block passed to a "
"method call\n"
"needs to be handled, the {YARD::Handlers::Base#parse_block parse_block} "
"method must be called on the list of statements\n"
"to parse. This will send the list to the processor to continue processing on "
"that\n"
"statement list. The source tree can be selectively parsed in this manner by "
"parsing\n"
"only the inner blocks that are relevant to documentation."
msgstr ""
"デフォルトでパーサーは全てのトップレベルステートメントから、\n"
"プロセッサークラスのリストを与える。\n"
"そして、プロセッサーは、トップレベルステートメントだけ解析する。\n"
"モジュール、クラス、メソッド内でブロックが宣言される場合や、\n"
"ブロックが処理されるメソッド呼び出しを解析した場合でさえ、\n"
"{YARD::Handlers::Base#parse_block parse_block}メソッドは、\n"
"解析の為にステートメントのリストを呼び出さなければならない。\n"
"これはステートメントのリストの処理を継続するプロセッサーにリストを送信する。\n"
"ソースツリーは、ドキュメント作成に関連したブロック内だけ解析することによって、\n"
"この形式の中で選択され抜粋される。"

#: ../docs/Handlers.md:105
msgid ""
"For example, the module handler parses the inner body of a module by "
"performing\n"
"the following commands:"
msgstr ""
"例えばモジュールハンドラーは、\n"
"以下のコマンドを実行することによってモジュールから内部の本体を解析する。"

#: ../docs/Handlers.md:108
msgid ""
"    class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base\n"
"      handles :module"
msgstr ""
"    class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base\n"
"      handles :module"

#: ../docs/Handlers.md:111
msgid ""
"      def process\n"
"        modname = statement[0].source\n"
"        mod = register ModuleObject.new(namespace, modname)\n"
"        parse_block(statement[1], :namespace => mod)\n"
"      end\n"
"    end"
msgstr ""
"      def process\n"
"        modname = statement[0].source\n"
"        mod = register ModuleObject.new(namespace, modname)\n"
"        parse_block(statement[1], :namespace => mod)\n"
"      end\n"
"    end"

#: ../docs/Handlers.md:118
msgid ""
"In this case `statement[1]` refers to a list of extra statements, the block "
"we\n"
"wish to parse. Note here that when parsing objects like modules and "
"classes,\n"
"we set the namespace for the duration of the block parsing by setting "
"options\n"
"on the `parse_block` method."
msgstr ""
"この場合`statement[1]`は追加のステートメントで、\n"
"私達が解析するブロックのリストを参照する。\n"
"ここにあるように、\n"
"モジュールやクラスのようにオブジェクトを解析する時、\n"
"私達は`parse_block`メソッドのオプションが設定されることによって\n"
"解析しているブロックの範囲をネームスペースに設定する。"

#: ../docs/Handlers.md:123
msgid "### API Differences for Legacy Handler"
msgstr "### Legacy Handler用のAPIの相違点"

#: ../docs/Handlers.md:125
msgid ""
"Because the legacy handler uses the legacy parser and therefore a different "
"kind\n"
"of AST, there are subtle differences in the handler API. Most importantly, "
"the\n"
"`handles` method usually deals with either lexical tokens or source code as "
"a string\n"
"or RegExp object. The statement object, similarly, is made up of lexical "
"tokens instead\n"
"of semantically parsed nodes (this is described in the {file:docs/Parser.md "
"parser document})."
msgstr ""
"レガシーハンドラーはレガシーパーサーを使い,\n"
"それに伴い異る種類のASTがあるのでハンドラーAPIに微妙な違いがある。\n"
"最も重要なことだが、 `handles` メソッドは通常、\n"
"単語のトークンやソースコード、文字列やRegExpオブジェクトと共に処理する。\n"
"ステートメントのオブジェクトと同様、意味のある解析されるノードの代わりに、\n"
"単語のトークンから構成される。\n"
"(これは{file:docs/Parser.md パーサーのドキュメント}の中で記述される)"

#: ../docs/Handlers.md:131
msgid ""
"The module example above can be rewritten as a legacy handler as follows:"
msgstr ""
"上記のモジュール例は、次のようなレガシーハンドラーによって再書込みされる。"

#: ../docs/Handlers.md:133
msgid ""
"    class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::"
"Ruby::Legacy::Base\n"
"      handles TkMODULE"
msgstr ""
"    class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base\n"
"      handles TkMODULE"

#: ../docs/Handlers.md:136
msgid ""
"      def process\n"
"        modname = statement.tokens.to_s[/^module\\s+(#{NAMESPACEMATCH})/, "
"1]\n"
"        mod = register ModuleObject.new(namespace, modname)\n"
"        parse_block(:namespace => mod)\n"
"      end\n"
"    end"
msgstr ""
"      def process\n"
"        modname = statement.tokens.to_s[/^module\\s+(#{NAMESPACEMATCH})/, 1]\n"
"        mod = register ModuleObject.new(namespace, modname)\n"
"        parse_block(:namespace => mod)\n"
"      end\n"
"    end"

#: ../docs/Handlers.md:143
msgid "A few notes on the differences:"
msgstr "標準のハンドラーとの違いに関するいくつかの注意。"

#: ../docs/Handlers.md:145
msgid ""
"  * We inherit from `Legacy::Base` instead of the standard Ruby Base handler "
"class.\n"
"  * We exchange node type `:module` for `TkMODULE`, which represents the\n"
"    first token in the statement.\n"
"  * We perform direct string manipulation to get the module name.\n"
"  * `parse_block` does not take a list of statements. In the old parser "
"API,\n"
"    each statement has a `block` attribute which defines the list of\n"
"    statements within that statement, if any. Therefore, `parse_block` will\n"
"    always parse the `statement.block` if it exists."
msgstr ""
"  * 標準のRubyBaseハンドラークラスの代わりに `Legacy::Base` から継承する。\n"
"  * ノードタイプ `:module` を `TkMODULE` へ交換する、\n"
"    それは、ステートメントの中の最初のトークンを表す。\n"
"  * モジュール名を取得する為に直接文字列操作を実行する。\n"
"  * `parse_block`はステートメントのリストを取得しない。\n"
"    古いパーサーの中のAPIで、\n"
"    それぞれのステートメントは `block` 属性を持っていたら\n"
"    ステートメントの中にステートメントのリストを定義する、\n"
"    従って、 `parse_block` は、 `statement.block` が存在すれば解析する。"

# title
#: ../docs/Overview.md:1
msgid "Architecture Overview"
msgstr "基本設計概念の概要"

#: ../docs/Overview.md:3
msgid "# Architecture Overview"
msgstr "# 基本設計概念の概要"

#: ../docs/Overview.md:5
msgid ""
"YARD is separated in three major components, each of which allows YARD to "
"be\n"
"extended for a separate purpose. The split also emphasizes YARD's design "
"choice\n"
"to explicitly separate data gathering from HTML document generation, "
"something\n"
"that tools like RDoc do not do. These components are:"
msgstr ""
"YARDは主な構成として三つに分けられる。\n"
"いずれも、目的毎に拡張される為にYARDに受け入れられる。\n"
"これは、HTMLドキュメント生成から集めるデータを明確に分ける為に\n"
"YARD設計上の選択を重視する。"

#: ../docs/Overview.md:10
msgid ""
"* [Code Parsing & Processing Component](#parsing)\n"
"* [Data Storage Component](#storage)\n"
"* [Post Processing & Templating System](#templates)"
msgstr ""
"* [Code Parsing & Processing Component](#parsing)\n"
"* [Data Storage Component](#storage)\n"
"* [Post Processing & Templating System](#templates)"

#: ../docs/Overview.md:14
msgid ""
"This separation is a major goal of the project, and means that YARD is not "
"*just*\n"
"a tool to generate HTML output. The expectation is that any subset of "
"YARD's\n"
"major components may be used, extended or modified independently. YARD may "
"be\n"
"used just as a data gathering tool (to parse and audit code), just as a "
"data\n"
"source (a webserver containing raw unformatted data about code), or just as "
"a\n"
"conventional HTML documentation generation tool (like RDoc)."
msgstr ""
"この区分は、プロジェクトの主要な目的であり、\n"
"YARDがHTMLの出力を生成するただの道具では無い事を意味している。\n"
"期待することはYARDのメジャーな構成のサブセットが独自に利用,拡張,変更される事である。\n"
"YARDはデータ収集ツール(コードを解析,検査),\n"
"データの元(ウェブサーバーはコードについてフォーマットされて無い生のデータを含んでいる),\n"
"便利なHTMLドキュメント作成ツール(RDocのような)として利用される。"

#: ../docs/Overview.md:21
msgid ""
"The important classes and dependencies of these components are shown in the\n"
"following class diagram:"
msgstr "重要なクラスやこれらの構成の依存関係は、次のクラス図の中で表示される。"

#: ../docs/Overview.md:24
msgid "![Overview Class Diagram](images/overview-class-diagram.png)"
msgstr "![Overview Class Diagram](images/overview-class-diagram.png)"

#: ../docs/Overview.md:26
msgid ""
msgstr ""

#: ../docs/Overview.md:28
msgid "## Code Parsing & Processing Component"
msgstr "## コードの解析と処理の構成"

#: ../docs/Overview.md:30
msgid ""
"This component is made up of four sub-components, each of which have "
"separate\n"
"tasks during the data gathering process (*note: the tag architecture is "
"not*\n"
"*shown in the class diagram*). These sub-components are:"
msgstr ""
"この構成は、4つの下位構成を作り上げる、\n"
"いずれも、\n"
"データ収集処理の間,別々のタスクを持つ。\n"
"(*注意: タグ構造はクラス図)\n"
"下位構成は以下のようになる。"

#: ../docs/Overview.md:34
msgid ""
"  * {file:docs/Parser.md}\n"
"  * {file:docs/Handlers.md}\n"
"  * {file:docs/CodeObjects.md}\n"
"  * {file:docs/Tags.md}"
msgstr ""
"  * {file:docs/Parser.md}\n"
"  * {file:docs/Handlers.md}\n"
"  * {file:docs/CodeObjects.md}\n"
"  * {file:docs/Tags.md}"

#: ../docs/Overview.md:39
msgid ""
"The parser component reads source files and converts it into a set of "
"statements\n"
"which the handlers then process, creating code objects which in turn create "
"tags\n"
"(meta-data) attached to the objects. These objects are all added to the "
"{YARD::Registry},\n"
"the data store component."
msgstr ""
"パーサーの構成は、ソースファイルを読み込み、\n"
"ステートメントのグループの中へそれを変換する\n"
"コードオブジェクトを作成し,\n"
"順番にオブジェクトを追加されたタグ(メタデータ)を作成する。\n"
"これらのオブジェクトは {YARD::Registry} に全て追加される。\n"
"データは構成を記録する。"

#: ../docs/Overview.md:44
msgid ""
msgstr ""

#: ../docs/Overview.md:46
msgid "## Data Storage Component"
msgstr "## データの記録内容"

#: ../docs/Overview.md:48
msgid ""
"This component is currently implemented as a simple Ruby marshalled flat "
"namespace\n"
"of object. The implementation is found in the single class {YARD::Registry}, "
"which\n"
"is the centralized repository for all data being parsed, stored and "
"accessed. There\n"
"are future plans to improve this storage mechanism to be backend agnostic "
"and allow\n"
"for more robust storage."
msgstr ""
"この内容は現在の所、\n"
"単純にRubyの整理されたフラットなオブジェクトのnamespaceのように実装されている。\n"
"実装はシングルクラスの{YARD::Registry}の中で見つけられる。\n"
"始めに解析し,記憶,アクセスされる全てのデータ用に集中化されたリポジトリとなる。\n"
"寛容なバックエンドにこのストレージのメカニズムを修正し、\n"
"そして更なる堅牢なストレージを受け入れる為の将来の計画がある。"

#: ../docs/Overview.md:54
msgid ""
msgstr ""

#: ../docs/Overview.md:56
msgid "## Post Processing & Templating System"
msgstr "## 後処理とテンプレートシステム"

#: ../docs/Overview.md:58
msgid ""
"This component handles processing of objects from the registry through a "
"templating\n"
"engine that allows output to a variety of formats. Practically speaking, "
"this is\n"
"where templates can be implemented to change the design, output or structure "
"of\n"
"the data. See {file:docs/Templates.md Templates Architecture} for a complete "
"overview."
msgstr ""
"この構成は\n"
"レジストリーから多様な書式を出力可能なテンプレートエンジンまで\n"
"オブジェクトの処理を操作する。\n"
"実際の話をすると、これは、設計や出力やデータの構造を変更する為に\n"
"テンプレートが実装される場所となる。\n"
"テンプレートの詳細な説明は\n"
"{file:docs/Templates.md Templates Architecture}参照。"

# title
#: ../docs/Parser.md:1
msgid "Parser Architecture"
msgstr "パーサー構造"

#: ../docs/Parser.md:3
msgid "# Parser Architecture"
msgstr "# パーサー構造"

#: ../docs/Parser.md:5
msgid ""
"The parser component of YARD is the first component in the data processing "
"pipeline\n"
"that runs before any handling is done on the source. The parser is meant to "
"translate\n"
"the source into a set of statements that can be understood by the {file:docs/"
"Handlers.md Handlers}\n"
"that run immediately afterwards."
msgstr ""
"YARDのパーサーの構成要素は、\n"
"何らかの処理がソース上で行われる前に実行され\n"
"パイプラインのデータ処理の中の最初の構成要素となる。\n"
"パーサーはソースを、\n"
"後ですぐ実行する{file:docs/Handlers.md Handlers}によって理解され\n"
"ステートメントのグループの中へ変換するよう意図されている。"

#: ../docs/Parser.md:10
msgid ""
"The important classes are described in the class diagram of the entire "
"parser\n"
"system below:"
msgstr "重要なクラスは、以下のパーサーの全体のシステムのクラス図表の中で記述する。"

#: ../docs/Parser.md:13
msgid "![Parser Class Diagram](images/parser-class-diagram.png)"
msgstr "![Parser Class Diagram](images/parser-class-diagram.png)"

#: ../docs/Parser.md:15
msgid "(Note: the RubyToken classes are omitted from the diagram)"
msgstr "(注意: RubyTokenクラスは、図表から省略されます。)"

#: ../docs/Parser.md:17
msgid "## SourceParser"
msgstr "## ソースパーサー"

#: ../docs/Parser.md:19
msgid ""
"The main class {YARD::Parser::SourceParser} acts as a factory class, "
"instantiating\n"
"the correct parser class, an implementation of {YARD::Parser::Base}. The "
"selected parser\n"
"is chosen based on either the file extension or by selecting it explicitly "
"(as an argument\n"
"to parsing methods). YARD supports Ruby and C source files, but custom "
"parsers can\n"
"be implemented and registered for various other languages by subclassing "
"`Parser::Base`\n"
"and registering the parser with {YARD::Parser::SourceParser."
"register_parser_type}."
msgstr ""
"主なクラス{YARD::Parser::SourceParser}は、ファクトリークラスのように振る舞"
"う。\n"
"そして正確なパーサークラスをインスタンス化する。これは{YARD::Parser::Base}か"
"ら実装する。\n"
"選ばれるパーサーは、\n"
"ファイル拡張子かパーサータイプを明確に指定する事によってベースが選ばれる。\n"
"(メソッドの解析の為の引数のように)\n"
"YARDはRubyやCのソースファイルをサポートするが。\n"
"カスタムパーサーが\n"
"`Parser::Base`をサブクラス化し\n"
"{YARD::Parser::SourceParser.register_parser_type}を用い登録する事によって\n"
"様々な他の言語用に実装され、登録される。"

#: ../docs/Parser.md:26
msgid ""
"This factory class should always be used when parsing source files rather "
"than\n"
"the individual parser classes since it initiates the pipeline that runs the\n"
"handlers on the parsed source. The parser used must also match the "
"handlers,\n"
"and this is coordinated by the `SourceParser` class as well."
msgstr ""
"このファクトリークラスは、個々のパーサークラスを解析する時より\n"
"ソースファイルを解析する時に毎回利用される。\n"
"なので解析されたソース上でハンドラーを起動するパイプラインを開始する。\n"
"利用されるパーサーはハンドラーにマッチしなければならない、\n"
"これは `SourceParser` クラスによって同様にコーディネートされる。"

#: ../docs/Parser.md:31
msgid "## Using the SourceParser Class"
msgstr "## ソースパーサークラスを使うには"

#: ../docs/Parser.md:33
msgid ""
"The `SourceParser` class API is optimized for parsing globs of files. As "
"such,\n"
"the main method to use the class is the `parse` class method, which takes "
"an\n"
"array of file globs or a single file glob."
msgstr ""
"`SourceParser` クラスAPIは、ファイルのglobを解析する為に最適化される。\n"
"クラスを使う為の主なメソッドは、 `parse` クラスメソッドとなる。\n"
"そして、ファイルの配列や単一のファイルglobを取る。"

#: ../docs/Parser.md:37
msgid ""
"    YARD::Parser::SourceParser.parse('spec_*.rb')\n"
"    YARD::Parser::SourceParser.parse(['spec_*.rb', '*_helper.rb'])"
msgstr ""
"    YARD::Parser::SourceParser.parse('spec_*.rb')\n"
"    YARD::Parser::SourceParser.parse(['spec_*.rb', '*_helper.rb'])"

#: ../docs/Parser.md:40
msgid "This is equivalent to the convenience method {YARD.parse}:"
msgstr "これは以下の便宜的なメソッド{YARD.parse}と同等である。"

#: ../docs/Parser.md:42
msgid "    YARD.parse('lib/**/*.rb')"
msgstr "    YARD.parse('lib/**/*.rb')"

#: ../docs/Parser.md:44
msgid ""
"In some cases (ie. for testing), it may be more helpful to parse a string of "
"input\n"
"directly. In such a case, the method {YARD::Parser::SourceParser."
"parse_string} should be\n"
"used:"
msgstr ""
"場合によっては(つまりテストの為)、\n"
"それは直接入力の文字列を解析するのにとても役立つだろう。\n"
"このような場合には、\n"
"以下の{YARD::Parser::SourceParser.parse_string}メソッドが使われる。"

#: ../docs/Parser.md:48
msgid "    YARD::Parser::SourceParser.parse_string(\"def method(a, b) end\")"
msgstr "    YARD::Parser::SourceParser.parse_string(\"def method(a, b) end\")"

#: ../docs/Parser.md:50
msgid "You can also provide the parser type explicitly as the second argument:"
msgstr "あなたは、パーサーの型を第2引数のように提供できる。"

#: ../docs/Parser.md:52
msgid ""
"    # Parses a string of C\n"
"    YARD::Parser::SourceParser.parse_string(\"int main() { }\", :c)"
msgstr ""
"    # C言語の文字列を解析する\n"
"    YARD::Parser::SourceParser.parse_string(\"int main() { }\", :c)"

#: ../docs/Parser.md:55
msgid ""
"Note that these two methods are aliased as {YARD.parse} and {YARD."
"parse_string} for\n"
"convenience."
msgstr ""
"以下の事に留意する。\n"
"これらの二つのメソッドは、便利に使う為の\n"
"{YARD.parse}や{YARD.parse_string}のような別名となる。"

#: ../docs/Parser.md:58
msgid "## Implementing and Registering a Custom Parser"
msgstr "## カスタムパーサーを実装及び登録する"

#: ../docs/Parser.md:60
msgid ""
"To implement a custom parser, subclass {YARD::Parser::Base}. Documentation "
"on which\n"
"abstract methods should be implemented are documented in that class. After "
"the class\n"
"is implemented, it is registered with the {YARD::Parser::SourceParser} "
"factory class\n"
"to be called when a file of the right extension needs to be parsed, or when "
"a user\n"
"selects that parser type explicitly. To register your new parser class, call "
"the\n"
"method {YARD::Parser::SourceParser.register_parser_type}:"
msgstr ""
"カスタムパーサーを実装するには、{YARD::Parser::Base}をサブクラス化する。\n"
"抽象的なメソッドのドキュメントはクラスの中で記述され実装される。\n"
"クラスが実装されたあとで、\n"
"正しい拡張子のファイルが解析される為に必要となる時や\n"
"ユーザーが明示的にパーサーのタイプを選択する時に\n"
"呼び出される為に{YARD::Parser::SourceParser}ファクトリークラスを用い記録される。\n"
"あなたの新しいパーサークラスを登録するには、\n"
"以下の様に{YARD::Parser::SourceParser.register_parser_type}メソッドを呼び出す。"

#: ../docs/Parser.md:67
msgid ""
"    SourceParser.register_parser_type(:my_parser, MyParser, 'my_parser_ext')"
msgstr "    SourceParser.register_parser_type(:my_parser, MyParser, 'my_parser_ext')"

#: ../docs/Parser.md:69
msgid ""
"The last argument can be a single extension, a list of extensions (Array), a "
"single Regexp, or a\n"
"list of Regexps. Do not include the '.' in the extension."
msgstr ""
"最後の引数は、単一の拡張か、拡張のリストか、単独の正規表現か、正規表現のリス"
"トになる。\n"
"拡張する中に'.'を含めることはできない。"

#: ../docs/Parser.md:73
msgid "## The Two Ruby Parser Types"
msgstr "## 2つのRubyパーサーの型"

#: ../docs/Parser.md:75
msgid ""
"When parsing Ruby, the SourceParser can either instantiate the new {YARD::"
"Parser::Ruby::RubyParser}\n"
"class or the {YARD::Parser::Ruby::Legacy::StatementList} class. The first of "
"the\n"
"two, although faster, more robust and more efficient, is only available for\n"
"Ruby 1.9. The legacy parser parser is available in both 1.8.x and 1.9, if\n"
"compatibility is required. The choice of parser will affect which handlers\n"
"ultimately get used, since new handlers can only use the new parser and the\n"
"same requirement applies to the legacy parser & handlers."
msgstr ""
"Rubyを処理している時、\n"
"SourceParserは、{YARD::Parser::Ruby::RubyParser}クラスまたは、\n"
"{YARD::Parser::Ruby::Legacy::StatementList}クラスをインスタンス化する。\n"
"2つの内の最初の、{YARD::Parser::Ruby::RubyParser}は、\n"
"高速で、最も堅牢で最も効率的だが、Ruby 1.9のみ利用可能。\n"
"もし互換性が必要な場合、2番目のlegacy parserパーサーなら、\n"
"1.8.xと1.9の両方で利用可能。\n"
"パーサーの選択は、ハンドラーが最終的に取得する所で影響する。\n"
"だから、新しいハンドラーは新しいパーサーだけを使える。\n"
"その条件はレガシーパーサーとハンドラーも同様である。"

#: ../docs/Parser.md:83
msgid "## Switching to Legacy Parser"
msgstr "## レガシーパーサーに切替える"

#: ../docs/Parser.md:85
msgid ""
"By default, running YARD under Ruby 1.9 will automatically select the new "
"parser\n"
"and new handlers by extension. Although YARD supports both handler styles, "
"plugins\n"
"may choose to only implement one of the two (though this is not "
"recommended). If\n"
"only the legacy handlers are implemented, the `SourceParser` class should "
"force\n"
"the use of the legacy parser by setting the `parser_type` attribute as such:"
msgstr ""
"デフォルトで、稼動中のRuby1.9以下のバージョンで使われるYARDは、\n"
"拡張によって新しいパーサーと新しいハンドラーを自動で選択する。\n"
"YARDがどちらのハンドラースタイルもサポートするけれども、\n"
"プラグインは2つの内一つだけを実装する事を選択する事もできる。\n"
"(このような考えは推奨されない)\n"
"もし、レガシーハンドラーのみ実装する場合、\n"
"`SourceParser`クラスはレガシーパーサーの使用を\n"
"強制すべきである。\n"
"例として、以下の様に`parser_type`属性を設定する。"

#: ../docs/Parser.md:91
msgid "    YARD::Parser::SourceParser.parser_type = :ruby18"
msgstr "    YARD::Parser::SourceParser.parser_type = :ruby18"

#: ../docs/Parser.md:93
msgid ""
"The default value is `:ruby`. Note that this cannot be forced the other way "
"around,\n"
"a parser type of `:ruby` cannot be set under Ruby 1.8.x as the new parser is "
"not\n"
"supported under 1.8."
msgstr ""
"デフォルトの値は、`:ruby`となる。\n"
"次の事に留意する。`:ruby`にしても強制されるわけではない。\n"
"何故なら`:ruby`のパーサーの型はRipperライブラリが未定義の場合、\n"
"新しいパーサーが1.8.以下をサポートしない様にするので、\n"
"Ruby 1.8.x以下には設定されないからである。"

#: ../docs/Parser.md:97
msgid "## RubyParser (the New Parser)"
msgstr "## Rubyパーサー(新しいパーサー)"

#: ../docs/Parser.md:99
msgid ""
"The new Ruby parser uses the Ripper library that is packaged as part of "
"stdlib\n"
"in Ruby 1.9. Because of this, it can generate an AST from a string of Ruby "
"input\n"
"that is similar to the style of other sexp libraries (such as ParseTree). "
"Each\n"
"node generated in the tree is of the base type {YARD::Parser::Ruby::"
"AstNode},\n"
"which has some subclasses for common node types."
msgstr ""
"新しいRubyパーサーはRuby1.9の中のRipperライブラリを使用する。\n"
"これは標準ライブラリの一部としてパッケージされる。\n"
"そんな訳で、Rubyの入力文字列からのASTを生成することが出来る。\n"
"これは、他のS式ライブラリのスタイルと同様である。\n"
"ツリーの中のそれぞれの生成したノードは、\n"
"基準の型{YARD::Parser::Ruby::AstNode}となる。\n"
"そして、一般的なノードの型用のいくつかのサブクラスを\n"
"持っている。"

#: ../docs/Parser.md:105
msgid "### AstNode Basics"
msgstr "### AstNodeの基本"

#: ../docs/Parser.md:107
msgid ""
"The `AstNode` class behaves like a standard Array class in which all of its "
"data\n"
"make up the list of elements in the array. Unlike other sexp style "
"libraries, however,\n"
"the node type is not the first element of the list. Instead, the node type "
"is defined\n"
"by the `#type` method. The following examples show some of the basic uses of "
"`AstNode`:"
msgstr ""
"AstNodeクラスは、全てのデータが配列の中の要素のリストを\n"
"作り上げる所で標準の配列クラスのように振る舞う。\n"
"他のS式スタイルのライブラリとは異なっている。しかしながら、\n"
"ノードタイプは、リストの最初の要素では無い。\n"
"むしろ、ノードタイプは`#type`メソッドによって定義される。\n"
"以下の例は、いくつかの`AstNode`の基本的な使用法を表す。"

#: ../docs/Parser.md:112
msgid ""
"    # The sexp defines the statement `hello if 1`\n"
"    node = s(:if_mod, s(:int, \"1\"), s(:var_ref, s(:ident, \"hello\")))\n"
"    node.type  #=> :if_mod\n"
"    node[0]    #=> s(:int, \"1\")\n"
"    node[0][0] #=> \"1\""
msgstr ""
"    # S式は `hello if 1` ステートメントを定義する\n"
"    node = s(:if_mod, s(:int, \"1\"), s(:var_ref, s(:ident, \"hello\")))\n"
"    node.type  #=> :if_mod\n"
"    node[0]    #=> s(:int, \"1\")\n"
"    node[0][0] #=> \"1\""

#: ../docs/Parser.md:118
msgid ""
"(Note the `s()` syntax is shorthand for `AstNode.new(...)`. `s()` with no "
"type\n"
"is shorthand for a node of type `:list`)"
msgstr ""
"(注意 `s()`構文は`AstNode.new(...)`用の縮めた表記となる。\n"
"型がない`s()`は`:list`型のノード用の縮めた表記となる。)"

#: ../docs/Parser.md:121
msgid ""
"As shown, not all of the elements are AstNodes in themselves, some are "
"String\n"
"objects containing values. A list of only the AstNodes within a node can be\n"
"accessed via the {YARD::Parser::Ruby::AstNode#children #children} method. "
"Using\n"
"the sexp declared above, we can do:"
msgstr ""
"示されたように、要素の全てがそれら自身の中のAstNodeでは無く、\n"
"いくつかは、値を含んでいるStringオブジェクトとなる。\n"
"ノード内部AstNodeだけのリストは、\n"
"{YARD::Parser::Ruby::AstNode#children #children}メソッド経由でアクセスされる。\n"
"上で宣言されたS式によって以下のようにできる。"

#: ../docs/Parser.md:126
msgid ""
"    node.children #=> [s(:int, \"1\"), s(:var_ref, s(:ident, \"hello\"))]"
msgstr "    node.children #=> [s(:int, \"1\"), s(:var_ref, s(:ident, \"hello\"))]"

#: ../docs/Parser.md:128
msgid "### AstNode#source and #line"
msgstr "### AstNode#source and #line"

#: ../docs/Parser.md:130
msgid ""
"Every node defines the `#source` method which returns the source code that "
"the\n"
"node represents. One of the most common things to do with a node is to grab "
"its\n"
"source. The following example shows how this can be done:"
msgstr ""
"全てのノードは`#source`メソッドを定義する。\n"
"そして、ノードが意味するソースコードを返す。\n"
"ノードを用いた最も一般的な事は、ソースを取得する事となる。\n"
"以下の例は、これがどのように実行されるかを表す。"

#: ../docs/Parser.md:134
msgid ""
"    source = \"if 1 == 1 then\\n  raise Exception\\n end\"\n"
"    ast = YARD::Parser::Ruby::RubyParser.parse(source).root\n"
"    ast[0].condition.source  #=> \"1 == 1\"\n"
"    ast[0].then_block.source #=> \"raise Exception\""
msgstr ""
"    source = \"if 1 == 1 then\\n  raise Exception\\n end\"\n"
"    ast = YARD::Parser::Ruby::RubyParser.parse(source).root\n"
"    ast[0].condition.source  #=> \"1 == 1\"\n"
"    ast[0].then_block.source #=> \"raise Exception\""

#: ../docs/Parser.md:139
msgid ""
"Note that this only works on source parsed from the RubyParser, not sexps\n"
"declared using the `s()` syntax. This is because no source code is "
"generated\n"
"or stored by nodes. Instead, only the character ranges are stored, which "
"are\n"
"then looked up in the original full source string object. For example:"
msgstr ""
"次の事に留意する。\n"
"RubyParserから解析されるソース上だけで働き、\n"
"S式が`s()`構文によって宣言される時は働かない。\n"
"これは何故かというとノードによってソースコードは生成や格納されないからであ"
"る。\n"
"代わりに、文字列の範囲だけ格納され、\n"
"元の全てのソースのcharacterオブジェクトの中で検索される。\n"
"以下の様になる。"

#: ../docs/Parser.md:144
msgid ""
"    # Following the code snippet above\n"
"    ast[0].then_block.source_range #=> 17..31"
msgstr ""
"    # 上のコードは次のようになる。(raise Exception部分のレンジ)\n"
"    ast[0].then_block.source_range #=> 17..31"

#: ../docs/Parser.md:147
msgid "We can also get the line and line ranges in a similar fashion:"
msgstr "私達は以下の方法の様に、行や行の範囲を取得できる。\n"

#: ../docs/Parser.md:149
msgid ""
"    ast[0].type       #=> :if\n"
"    ast[0].line       #=> 1\n"
"    ast[0].line_range #=> 1..3 (note the newlines in the source)"
msgstr ""
"    ast[0].type       #=> :if\n"
"    ast[0].line       #=> 1\n"
"    ast[0].line_range #=> 1..3 (ソース中の改行に注意)"

#: ../docs/Parser.md:153
msgid "### AstNode#jump"
msgstr "### AstNode#jump"

#: ../docs/Parser.md:155
msgid ""
"Often the AST will be such that the node we care about might be buried "
"arbitrarily\n"
"deep in a node's hierarchy. The {YARD::Parser::Ruby::AstNode#jump} method "
"exists\n"
"to quickly get at a node of a specific type in such a situation:"
msgstr ""
"多くの場合AST処理の中でノードに対し私達が気を付ける事は、\n"
"任意でノードの階層の中深くに埋められるかもしれないという事である。\n"
"{YARD::Parser::Ruby::AstNode#jump}メソッドは、以下の状況において特定の型の\n"
"ノードに素早く到達する為に存在する。"

#: ../docs/Parser.md:159
msgid ""
"    # Get the first identifier in the statement\n"
"    ast = s(s(:int, \"1\"), s(s(:var_ref, s(:ident, \"hello\"))))\n"
"    ast.jump(:ident)[0] #=> \"hello\""
msgstr ""
"    # Get the first identifier in the statement\n"
"    ast = s(s(:int, \"1\"), s(s(:var_ref, s(:ident, \"hello\"))))\n"
"    ast.jump(:ident)[0] #=> \"hello\""

#: ../docs/Parser.md:163
msgid ""
"Multiple types can be searched for at once. If none are found, the original "
"root\n"
"node is returned so that it may be chained."
msgstr ""
"複数のタイプは、すぐに検索される。\n"
"もし、見つからなかった場合、オリジナルのルートノードは、連鎖されるように返さ"
"れる。"

#: ../docs/Parser.md:166
msgid "## The Legacy Parser"
msgstr "## レガシーパーサー"

#: ../docs/Parser.md:168
msgid ""
"The goal of the legacy parser is much the same as the new parser, but it is "
"far\n"
"more simplistic. Instead of a full-blown AST, the legacy parser simply "
"groups\n"
"together lists of \"statements\" called a {YARD::Parser::Ruby::Legacy::"
"StatementList}.\n"
"These statement lists are made up of {YARD::Parser::Ruby::Legacy::Statement} "
"objects.\n"
"A statement is any method call condition, loop, or declaration. Each "
"statement\n"
"may or may not have a block. In the case of a condition or loop, the block "
"is\n"
"the inner list of statements; in the case of a method call, the block is a "
"do\n"
"block (if provided). The statements themselves are made up of tokens, so "
"instead\n"
"of being semantic in nature like the new parser, statements are tied "
"directly\n"
"to the lexical tokens that make them up. To convert a statement into source, "
"you\n"
"simply join all the tokens together (this is done through the use of "
"`#to_s`)."
msgstr ""
"レガシーパーサーの目的は、新しいパーサーと殆んど同様であるが、\n"
"しかし、それははるかに単純である。\n"
"完璧なASTの代わりに、\n"
"レガシーパーサーは、単純に\n"
"{YARD::Parser::Ruby::Legacy::StatementList}で呼び出される\"ステートメント\"のリストの\n"
"グループを作る。\n"
"これらのステートメントのリストは、{YARD::Parser::Ruby::Legacy::Statement}\n"
"オブジェクトで構成されている。\n"
"ステートメントは任意のメソッドで条件,ループ,宣言を呼び出す。\n"
"それぞれのステートメントはブロックを持っているかわからない。\n"
"条件やループの場合、ブロックはステートメントの内部のリストになる。\n"
"メソッド呼び出しの場合、ブロックはブロックを実行する。(もし提供されるなら)\n"
"ステートメントそれ自体は、トークンで構成されている。\n"
"その為、新しいパーサーのように自然な意味になる代わりに、\n"
"ステートメントはそれらを作り上げる単語のトークンに直接紐付けられる。\n"
"ステートメントをソースに変換する為には、\n"
"全てのトークンと共に単純に加えればいい。\n"
"(これは`#to_s`メソッドを使用し行われる。)"

#: ../docs/Parser.md:180
msgid ""
"Note that because there is little semantic parsing, the legacy parser is "
"less\n"
"able to deal with certain Ruby syntaxes. Specifically, the `:if_mod` syntax\n"
"seen above (\"hello if 1\") would be considered two statements with the new "
"parser,\n"
"but using the legacy parser it is only one statement:"
msgstr ""
"次の事に留意する。\n"
"意味のある解析がほとんどないので、\n"
"レガシーパーサーは、特定のRuby構文と共に扱う事ができない。\n"
"具体的にいうと、\n"
"上の(\"hello if 1\")で見た`:if_mod`構文は、\n"
"新しいパーサーを用いた二つのステートメントと考えられる。\n"
"しかし、レガシーパーサーを使うと以下の一つのステートメントだけになる。"

#: ../docs/Parser.md:185
msgid ""
"    stmts = ARD::Parser::Ruby::Legacy::StatementList.new(\"hello if 1\")\n"
"    stmts[0].block       #=> nil\n"
"    stmts[0].tokens.to_s #=> \"hello if 1\""
msgstr ""
"    stmts = ARD::Parser::Ruby::Legacy::StatementList.new(\"hello if 1\")\n"
"    stmts[0].block       #=> nil\n"
"    stmts[0].tokens.to_s #=> \"hello if 1\""

#: ../docs/Parser.md:189
msgid ""
"In addition, this means that most handling still needs to be done via "
"string\n"
"manipulation and regular expression matching, making it considerably more\n"
"difficult to use in edge case scenarios."
msgstr ""
"さらに、ほとんどの処理は文字列操作や正規表現マッチ経由で行う\n"
"必要がある事を意味している。\n"
"それに合わせて作るには、極端なシナリオで利用する場合、大幅に難しくなる。"

# title
#: ../docs/Tags.md:1
msgid "Tags Overview"
msgstr "タグの概要"

#: ../docs/Tags.md:3
msgid "# Tags Overview"
msgstr "# タグの概要"

#: ../docs/Tags.md:5
msgid ""
"Tags represent meta-data as well as behavioural data that can be added to\n"
"documentation through the `@tag` style syntax. As mentioned, there are two\n"
"basic types of tags in YARD, \"meta-data tags\" and \"behavioural tags\", "
"the\n"
"latter is more often known as \"directives\". These two tag types can be\n"
"visually identified by their prefix. Meta-data tags have a `@` prefix,\n"
"while directives have a prefix of `@!` to indicate that the directive\n"
"performs some potentially mutable action on or with the docstring. The\n"
"two tag types would be used in the following way, respectively:"
msgstr ""
"タグは`@tag`スタイルの構文からドキュメントを\n"
"作成するために追加されるデータの行動(behavioural)としてメタデータを表す。\n"
"上で述べた、\n"
"YARDの中でタグには基本的な2つの方があり、\n"
"\"メタデータタグ\"と\"行動(behavioural)タグ\"がある。\n"
"後者は、\"ディレクティブ\"としてよく知られている。\n"
"これらの2つのタグの型は\n"
"これらのプレフィックス(接頭辞)によって視覚的に指定される。\n"
"ディレクティブがdocstringと一緒に\n"
"幾つかの潜在的に変更可能なアクションを実行する指示をする為に\n"
"`@!`のプレフィックスを持つ間、\n"
"メタデータタグは`@`プレフィックスを持つ。\n"
"2つのタグの型はそれぞれ次の方法で利用される:"

#: ../docs/Tags.md:14
msgid ""
"    # @meta_data_tag some data\n"
"    # @!directive_tag some data\n"
"    class Foo; end"
msgstr ""
"    # @meta_data_tag some data\n"
"    # @!directive_tag some data\n"
"    class Foo; end"

#: ../docs/Tags.md:18
msgid ""
"This document describes how tags can be specified, how they affect your\n"
"documentation, and how to use specific built-in tags in YARD, as well\n"
"as how to define custom tags."
msgstr ""
"このドキュメントはタグについて\n"
"どのように指定されるか、\n"
"あなたのドキュメントにどれほど影響するか、\n"
"YARDの指定の組み込みタグをどのように使うのか、\n"
"どのようにカスタムタグを定義するのかを説明する"

#: ../docs/Tags.md:22
msgid "## Meta-Data Tags"
msgstr "## メタデータタグ"

#: ../docs/Tags.md:24
msgid ""
"Meta-data tags are useful to add arbitrary meta-data about a documented\n"
"object. These tags simply add data to objects that can be looked up later,\n"
"either programmatically, or displayed in templates. The benefit to "
"describing\n"
"objects using meta-data tags is that your documentation can be organized\n"
"semantically. Rather than having a huge listing of text with no distinction\n"
"of what each paragraph is discussing, tags allow you to focus in on "
"specific\n"
"elements of your documentation."
msgstr ""
"メタデータタグは記述されたオブジェクトについて\n"
"任意のメタデータを追加するのに便利である。\n"
"これらのタグは\n"
"簡単に後で検索でき、全てプログラムでき、テンプレートで表示できるように\n"
"オブジェクトにデータを追加する。\n"
"メタデータタグを使う事によるオブジェクトの説明の利点は、\n"
"あなたのドキュメントが意味を持って整理されることである。\n"
"個々の段落がどこで議論されるか\n"
"区別しないで巨大なテキストでの記述するより、\n"
"タグはあなたがあなたのドキュメントの特定の属性に集中するのを\n"
"考慮している。"

#: ../docs/Tags.md:32
msgid ""
"For example, describing parameters of a method can often be important to "
"your\n"
"documentation, but should not be mixed up with the documentation that "
"describes\n"
"what the method itself does. In this case, separating the parameter "
"documentation\n"
"into {tag:param} tags can yield much better organized documentation, both "
"in\n"
"source and in your output, without having to manually format the data using\n"
"standard markup."
msgstr ""
"例えば、\n"
"メソッドのパラメータの説明は\n"
"あなたのドキュメントでしばしば必要になるが、\n"
"そのメソッド自体が何をするのか説明する\n"
"ドキュメントと一緒にごちゃ混ぜにすべきではない。\n"
"この場合は{tag:param}タグへドキュメントのパラメータを区切る事で\n"
"よりよく整理されたドキュメントにyieldでき、\n"
"ソースとあなたの出力両方で,\n"
"手動でなくても標準のマークアップでデータをフォーマットする。"

#: ../docs/Tags.md:39
msgid ""
"All of this meta-data can be easily parsed by tools and used both in your "
"templates\n"
"as well as in code checker tools. An example of how you can leverage tags\n"
"programmatically is shown in the {tag:todo} tag, which lists a small snippet "
"of\n"
"Ruby code that can list all of your TODO items, if they are properly tagged."
msgstr ""
"このメタデータの全ては\n"
"ツールによって簡単に解析され、\n"
"それはあなたのテンプレートとコードチェッカーツールの両方で利用される。\n"
"プログラムでどのタグを利用できるかの例は{tag:todo}タグで一覧でき、\n"
"これらが適切にタグ付けられれば、\n"
"あなたの全てのTODOの項目をリストされ小さいRubyのコードのスニペットを記述する。"

#: ../docs/Tags.md:44
msgid ""
"Custom meta-data tags can be added either programmatically or via the YARD\n"
"command-line. This is discussed in the \"[Adding Custom Tags]"
"(#Adding_Custom_Tags)\"\n"
"section."
msgstr ""
"カスタムメタデータタグはプログラムかYARDのコマンドラインで追加される。\n"
"これは\"[カスタムタグの追加](#Adding_Custom_Tags)\"の項の中で議論される。"

#: ../docs/Tags.md:48
msgid ""
"A list of built-in meta-data tags are found below in the [Tag List]"
"(#Tag_List)."
msgstr "組み込みのメタデータタグのリストは下の [タグリスト](#Tag_List) で見つけられる。"

#: ../docs/Tags.md:50
msgid "## Directives"
msgstr "## ディレクティブ"

#: ../docs/Tags.md:52
msgid ""
"Directives are similar to meta-data tags in the way they are specified, but "
"they\n"
"do not add meta-data to the object directly. Instead, they affect the "
"parsing\n"
"context and objects themselves, allowing a developer to create objects\n"
"(like methods) outright, rather than simply add text to an existing object.\n"
"Directives have a `@!` prefix to differentiate these tags from meta-data "
"tags,\n"
"as well as to indicate that the tag may modify or create new objects when\n"
"it is called."
msgstr ""
"ディレクティブはメタデータタグが指定される方法と似ているが、\n"
"これは直接オブジェクトにメタデータを追加しない。\n"
"代わりに、\n"
"これらは解析のコンテキストとそれ自身のオブジェクトに影響し、\n"
"既存のオブジェクトにテキストを単純に追加するより、\n"
"完全なオブジェクト(メソッドのような)を作成する開発者を受け入れる。\n"
"ディレクティブは、メタデータタグからこれらのタグを識別するためや\n"
"タグが変更される示すためや\n"
"呼び出される時に新しいオブジェクトを作成するに\n"
"`@!`プレフィックスを持つ。"

#: ../docs/Tags.md:60
msgid ""
"A list of built-in directives are found below in the [Directive List]"
"(#Directive_List)."
msgstr ""
"組み込みのディレクティブのリストは\n"
"以下の [ディレクティブリスト](#Directive_List) メソッドの中で定義される。"

#: ../docs/Tags.md:62
msgid "## Tag Syntax"
msgstr "## タグ構文"

#: ../docs/Tags.md:64
msgid ""
"Tags begin with the `@` or `@!` prefix at the start of a comment line, "
"followed\n"
"immediately by the tag name, and then optional tag data (if the tag requires "
"it).\n"
"Unless otherwise specified by documentation for the tag, all \"description\" "
"text\n"
"is considered free-form data and can include any arbitrary textual data."
msgstr ""
"タグはコメント行の始めで`@`や`@!`のプレフィックスと共に始まり、\n"
"すぐ次にタグ名、そして任意のタグデータ(もしタグにそれが必要なら)\n"
"別に必要ない場合は\n"
"タグ用のドキュメントを指定し、\n"
"全ての\"説明\"のテキストはフリーフォームのデータと見なされ、\n"
"任意の原文のデータを含む事ができる。"

#: ../docs/Tags.md:69
msgid "### Multi-line Tags"
msgstr "### 複数行のタグ"

#: ../docs/Tags.md:71
msgid ""
"Tags can span multiple lines if the subsequent lines are indented by more "
"than\n"
"one space. The typical convention is to indent subsequent lines by 2 "
"spaces.\n"
"In the following example, `@tagname` will have the text *\"This is indented "
"tag data\"*:"
msgstr ""
"タグは後続の行が一つ以上のスペースでインデントされる場合、複数の行に渡る事もできる。\n"
"一般的な慣習は2つのスペースによって続く行をする。\n"
"次の例の`@tagname`は *\"This is indented tag data\"* のテキストを持つ:"

#: ../docs/Tags.md:75
msgid ""
"    # @tagname This is\n"
"    #   indented tag data\n"
"    # but this is not"
msgstr ""
"    # @tagname This is\n"
"    #   indented tag data\n"
"    # but this is not"

#: ../docs/Tags.md:79
msgid ""
"For most tags, newlines and indented data are not significant and do not "
"impact\n"
"the result of the tag. In other words, you can decide to span a tag onto "
"multiple\n"
"lines at any point by creating an indented block. However, some tags like\n"
"{tag:example}, {tag:overload}, {tag:!macro}, {tag:!method}, and {tag:!"
"attribute}\n"
"rely on the first line for special information about the tag, and you "
"cannot\n"
"split this first line up. For instance, the {tag:example} tag uses the first "
"line\n"
"to indicate the example's title."
msgstr ""
"殆どのタグで、改行とインデントされたデータは\n"
"重要でないしタグの結果に影響しない。\n"
"つまり、あなたは\n"
"インデントされたブロックを作成する事によって全てのポイントで\n"
"複数行の上のタグに渡すのを決定できる。\n"
"しかしながら、\n"
"{tag:example}, {tag:overload}, {tag:!macro}, {tag:!method}, {tag:!attribute}のような、\n"
"いくつかのタグはタグについて特別な情報用に最初の行を頼り、\n"
"あなたはこの最初の行を分割できない。\n"
"例えば、{tag:example} タグは例のタイトルを指示するために最初の行を使う。"

#: ../docs/Tags.md:87
msgid "### Common Tag Syntaxes"
msgstr "### 一般的なタグ構文"

#: ../docs/Tags.md:89
msgid ""
"Although custom tags can be parsed in any way, the built-in tags follow a "
"few\n"
"common syntax structures by convention in order to simplify the syntax. The\n"
"following syntaxes are available:"
msgstr ""
"カスタムタグはどの方法でも解析され、\n"
"ビルトインタグは、構文を簡単にする為に定められた\n"
"いくつかの共通する構文構造に従う。\n"
"次の構文が用意されている。"

#: ../docs/Tags.md:93
msgid ""
"1. **Freeform data** — In this case, any amount of textual data is "
"allowed,\n"
"  including no data. In some cases, no data is necessary for the tag.\n"
"2. **Freeform data with a types specifier list** — Mostly freeform "
"data\n"
"  beginning with an *optional* types specifier list surrounded in `[brackets]"
"`.\n"
"  Note that for extensibility, other bracket types are allowed, such as "
"`<>`,\n"
"  `()` and `{}`. The contents of the list are discussed in detail below.\n"
"3. **Freeform data with a name and types specifier list** — freeform\n"
"  data beginning with an *optional* types list, as well as a name key. The\n"
"  name key is *required*. Note that for extensibility, the name can be "
"placed\n"
"  *before* the types list, like: `name [Types] description`. In this case,\n"
"  a separating space is not required between the name and types, and you\n"
"  can still use any of the other brackets that the type specifier list "
"allows.\n"
"4. **Freeform data with title** — freeform data where the first line "
"cannot\n"
"  be split into multiple lines. The first line must also always refer to "
"the\n"
"  \"title\" portion, and therefore, if there is no title, the first line "
"must\n"
"  be blank. The \"title\" might occasionally be listed by another name in "
"tag\n"
"  documentation, however, you can identify this syntax by the existence of\n"
"  a multi-line signature with \"Indented block\" on the second line."
msgstr ""
"1. **フリーフォームデータ** — この場合は全ての単語のデータの総量は許可され、\n"
"データを含まない。場合によってはデータ無しではタグを必要としない。\n"
"2. **型指定のリストを用いたフリーフォームデータ** — 大抵のフリーフォームデータは\n"
"*optional(任意の)* の`[brackets(括弧)]`で囲まれた型指定のリストを用いて始まっている。\n"
"拡張用に留意する事として、\n"
"`<>`、`()`、`{}`などとして他のブラケットの型は許可される。\n"
"リストの内容は下の詳細で議論される。    \n"
"3. **名前と型指定のリストを用いたフリーフォームデータ** — フリーフォームデータは\n"
"*optional(任意の)*型のリストもキーの名前も用い始まるデータ。\n"
"キーの名前は *必須* である。\n"
"拡張性について次のことに留意する。\n"
"名前は型のリストの前に置く事ができる:`name [Types] description`。\n"
"この場合は、区切りのスペースはnameとtypesの間に必要ではない。\n"
"そしてあなた型指定のリストの許可の他のbracket(括弧)の何かを使う事ができる。\n"
"4. **タイトルを用いたフリーフォームデータ** — 最初の行のところのフリーフォームデータは\n"
"複数の行へ分割できない。\n"
"最初の行は常に\"title\"の場所とそれ自身を参照しなければならない。\n"
"タイトル無しの場合は、\n"
"最初の行はブランクにしなければならない。\n"
"\"title\"は時々、タグのドキュメントの中で他の名前によって記述される。\n"
"しかしながら、あなたは2番目の行の\"インデントされたブロック\"を用い\n"
"複数行のシグネチャの存在によってこの構文を認証できる"

#: ../docs/Tags.md:112
msgid ""
"In the tag list below, the term \"description\" implies freeform data, `"
"[Types]`\n"
"implies a types specifier list, \"name\" implies a name key, and \"title\" "
"implies\n"
"the first line is a newline significant field that cannot be split into "
"multiple\n"
"lines."
msgstr ""
"下のタグのリストでは、\n"
"\"description\"の用語はフリーフォームデータを意味し、\n"
"`[Types]`は型指定のリストを意味する。\n"
"\"name\"はキーの名前を意味し、\n"
"最初の行を意味する\"title\"は改行で複数行へ分割できない特殊なフィールドである"

#: ../docs/Tags.md:117
msgid "### Types Specifier List"
msgstr "### 型指定のリスト"

#: ../docs/Tags.md:119
msgid ""
"In some cases, a tag will allow for a \"types specifier list\"; this will be "
"evident\n"
"from the use of the `[Types]` syntax in the tag signature. A types specifier "
"list\n"
"is a comma separated list of types, most often classes or modules, but "
"occasionally\n"
"literals. For example, the following {tag:return} tag lists a set of types "
"returned\n"
"by a method:"
msgstr ""
"幾つかの場合、タグは\"型指定のリスト\"用に許可する。\n"
"これはタグのシグネチャの中の`Types`の構文の利用から明らかである。\n"
"型指定のリストはコンマで区切られた型のリストである。\n"
"ほとんどはクラスやモジュールで、時々、リテラルである。\n"
"例えば、次の{tag:return}タグのリストはメソッドによって返された型のグループを記述する:"

#: ../docs/Tags.md:125
msgid ""
"    # Finds an object or list of objects in the db using a query\n"
"    # @return [String, Array, nil] the object or objects to\n"
"    #   find in the database. Can be nil.\n"
"    def find(query) finder_code_here end"
msgstr ""
"    # queryによってdbの中のオブジェクトやオブジェクトのリストを見つける\n"
"    # @return [String, Array, nil] the object or objects to\n"
"    #   find in the database. Can be nil.\n"
"    def find(query) finder_code_here end"

#: ../docs/Tags.md:130
msgid ""
"A list of conventions for type names is specified below. Typically, "
"however,\n"
"any Ruby literal or class/module is allowed here. Duck-types (method names\n"
"prefixed with \"#\") are also allowed."
msgstr ""
"型の名前用の慣習的なリストは下で指定される。\n"
"しかしながら一般的にRubyのリテラルやクラス/モジュールはここで許可される。\n"
"ダックタイピング(プレフィックスされたメソッド名を用いた\"#\")も許可される。"

#: ../docs/Tags.md:134
msgid ""
"Note that the type specifier list is always an optional field and can be "
"omitted\n"
"when present in a tag signature. This is the reason why it is surrounded by\n"
"brackets. It is also a freeform list, and can contain any list of values, "
"though\n"
"a set of conventions for how to list types is described below."
msgstr ""
"留意する事として次の事がある。\n"
"型指定のリストは常に任意のフィールドとなり\n"
"タグのシグネチャを示す時にタグ構文の中で残される。\n"
"これがbracket(括弧)によってとりかこまれる理由である。\n"
"フリーフォームのリストも、任意のリストの値を含む事ができる。\n"
"どんな型をリストにするかの慣習のグループは下で説明される。"

#: ../docs/Tags.md:139
msgid "### Type List Conventions"
msgstr "### 型のリストの慣習"

#: ../docs/Tags.md:141
msgid ""
"
    \n"
"  A list of examples of common type listings and what they translate into "
"is\n"
"  available at http://yardoc.org/types.\n"
"
    "
msgstr ""
"
    \n"
"  A list of examples of common type listings and what they translate into is\n"
"  available at http://yardoc.org/types.\n"
"
    "

#: ../docs/Tags.md:146
msgid ""
"Typically, a type list contains a list of classes or modules that are "
"associated\n"
"with the tag. In some cases, however, certain special values are allowed or "
"required\n"
"to be listed. This section discusses the syntax for specifying Ruby types "
"inside of\n"
"type specifier lists, as well as the other non-Ruby types that are accepted "
"by\n"
"convention in these lists."
msgstr ""
"一般的に、型のリストはタグに関連付けられるクラスやモジュールのリストを含んでいる。\n"
"しかしながら、幾つかの特別な値は記述される為に許可され,受入られる。\n"
"このセクションは型の指定のリストの内部のRubyの型の指定用の構文も、\n"
"これらのリストの中の慣例によって認められる他のRubyではない型も議論する。"

#: ../docs/Tags.md:152
msgid ""
"It's important to realize that the conventions listed here may not always "
"adequately\n"
"describe every type signature, and is not meant to be a complete syntax. "
"This is\n"
"why the types specifier list is freeform and can contain any set of values. "
"The\n"
"conventions defined here are only conventions, and if they do not work for "
"your\n"
"type specifications, you can define your own appropriate conventions."
msgstr ""
"ここで慣例で記述されたものは常に\n"
"全ての型のシグネチャを説明しないのと\n"
"完璧な構文であるというのは意味しないという事を\n"
"理解するのが重要である。\n"
"型の指定のリストがフリーフォームなのは任意の値のグループを含むことができるからである。\n"
"ここで定義された慣例はここだけの慣例で、これはあなたの型の指定用には動作しない。\n"
"あなたは自身の適切な慣例を定義できる。"

#: ../docs/Tags.md:158
msgid ""
"Note that a types specifier list might also be used for non-Type values. In "
"this\n"
"case, the tag documentation will describe what values are allowed within "
"the\n"
"type specifier list."
msgstr ""
"次の事に留意する。\n"
"型の指定のリストは型ではない値にも使われるかもしれない。\n"
"この場合は,タグのドキュメントは\n"
"どの値が型の指定のリストの中で許可されるのかを説明する。"

#: ../docs/Tags.md:162
msgid "#### Class or Module Types"
msgstr "#### クラスやモジュールの型"

#: ../docs/Tags.md:164
msgid ""
"Any Ruby type is allowed as a class or module type. Such a type is simply "
"the name\n"
"of the class or module."
msgstr ""
"Rubyの型はクラスやモジュールを受け入れる。\n"
"タイプなどは単純にクラスやモジュールの名前である。"

#: ../docs/Tags.md:167
msgid ""
"Note that one extra type that is accepted by convention is the `Boolean` "
"type,\n"
"which represents both the `TrueClass` and `FalseClass` types. This type does "
"not\n"
"exist in Ruby, however."
msgstr ""
"次の事に留意する。\n"
"`Boolean`の型は慣例によって受入れられる追加の型で\n"
"`TrueClass`と`FalseClass`の型の両方を表す。\n"
"この型はRubyの中に存在しない。"

#: ../docs/Tags.md:171
msgid "#### Parametrized Types"
msgstr "#### パラメータ化された型"

#: ../docs/Tags.md:173
msgid ""
"In addition to basic types (like String or Array), YARD conventions allow "
"for\n"
"a \"generics\" like syntax to specify container objects or other "
"parametrized types.\n"
"The syntax is `Type`. For instance, an Array "
"might\n"
"contain only String objects, in which case the type specification would be\n"
"`Array`. Multiple parametrized types can be listed, separated by "
"commas."
msgstr ""
"基本の型(StringやArrayのような)に更に、YARDの慣例は\n"
"コンテナオブジェクトや他のパラメータ化された型を指定するための構文のような\n"
"\"generics(総称的な)\"の為に許可する。\n"
"構文は`Type`となる\n"
"例えば、配列は文字列オブジェクトだけを含んでいるかもしれない。\n"
"その場合の型の指定は`Array`になる。\n"
"複数のパラメータ化された型はカンマによって区切られ記述される。"

#: ../docs/Tags.md:179
msgid ""
"Note that parametrized types are typically not order-dependent, in other "
"words,\n"
"a list of parametrized types can occur in any order inside of a type. An "
"array\n"
"specified as `Array` can contain any amount of Strings or "
"Fixnums,\n"
"in any order. When the order matters, use \"order-dependent lists\", "
"described below."
msgstr ""
"次のことに留意する。\n"
"パラメータ化された型は一般的に順番に依存せず、\n"
"いいかえれば、パラメータ化された型のリストは\n"
"型の内部で好きなの順番におく事ができる。\n"
"`Array` などとして指定された配列はStringやFixnumの総量を\n"
"任意の順番で含む事ができる。\n"
"順番が問題になる時は、\n"
"下で説明される\"order-dependent lists(順番依存のリスト)\"を使う:"

#: ../docs/Tags.md:184
msgid "#### Duck-Types"
msgstr "#### ダックタイピング"

#: ../docs/Tags.md:186
msgid ""
"Duck-types are allowed in type specifier lists, and are identified by "
"method\n"
"names beginning with the \"#\" prefix. Typically, duck-types are "
"recommended\n"
"for {tag:param} tags only, though they can be used in other tags if needed.\n"
"The following example shows a method that takes a parameter of any type\n"
"that responds to the \"read\" method:"
msgstr ""
"ダックタイピングは型指定のリストを受入れ、\n"
"\"#\"プレフィックス(接頭辞)を用いた最初のメソッド名によってインデントされる。\n"
"一般的にダックタイピングは {tag:param} タグだけに推奨されているが、\n"
"必要なら他のタグで利用する事もできる。\n"
"次の例は\"read\"メソッドに返事をする任意の型のパラメータを\n"
"取得するメソッドを一覧できる:"

#: ../docs/Tags.md:192
msgid ""
"    # Reads from any I/O object.\n"
"    # @param [#read] io the input object to read from\n"
"    def read(io) io.read end"
msgstr ""
"    # 任意のI/O オブジェクトから読み込む\n"
"    # @param [#read] io the input object to read from\n"
"    def read(io) io.read end"

#: ../docs/Tags.md:196
msgid "#### Hashes"
msgstr "#### ハッシュ"

#: ../docs/Tags.md:198
msgid ""
"Hashes can be specified either via the parametrized type discussed above,\n"
"in the form `Hash`, or using the hash specific syntax:\n"
"`Hash{KeyTypes=>ValueTypes}`. In the latter case, KeyTypes or ValueTypes "
"can\n"
"also be a list of types separated by commas."
msgstr ""
"ハッシュは上で議論されたパラメータ化された型、\n"
"`Hash` 形式経由か\n"
"もしくは次の指定のハッシュ構文を使う:\n"
"`Hash{KeyTypes=>ValueTypes}` \n"
"後者の場合、KeyTypesやValueTypesはカンマで区切られた型のリストにもできる。"

#: ../docs/Tags.md:203
msgid "#### Order-Dependent Lists"
msgstr "#### Order-Dependent Lists(順番依存のリスト)"

#: ../docs/Tags.md:205
msgid ""
"An order dependent list is a set of types surrounded by \"()\" and separated "
"by\n"
"commas. This list must contain exactly those types in exactly the order "
"specified.\n"
"For instance, an Array containing a String, Fixnum and Hash in that order "
"(and\n"
"having exactly those 3 elements) would be listed as: `Array<(String, Fixnum, "
"Hash)>`."
msgstr ""
"順番依存のリストは\"()\"によって囲われた型のグループであり、\n"
"カンマによって区切られる。\n"
"このリストは正確に順番の指定された中で正確にそれらの型を含まなければならない。\n"
"例えばString,Fixnum,Hashの順番の(それは3つの属性をもっている)配列は、\n"
"`Array<(String, Fixnum, Hash)>` として記述される。"

#: ../docs/Tags.md:210
msgid "#### Literals"
msgstr "#### リテラル"

#: ../docs/Tags.md:212
msgid ""
"Some literals are accepted by virtue of being Ruby literals, but also by "
"YARD\n"
"conventions. Here is a non-exhaustive list of certain accepted literal "
"values:"
msgstr ""
"幾つかのリテラルはRubyのリテラルにある利点を受け入れるが、\n"
"YARDによる慣例もある。\n"
"ここで紹介するのは明確に受入れられたリテラルの網羅的なリストではない。"

#: ../docs/Tags.md:215
msgid ""
"* `true`, `false`, `nil` — used when a method returns these explicit "
"literal\n"
"  values. Note that if your method returns both `true` or `false`, you "
"should use\n"
"  the `Boolean` conventional type instead.\n"
"* `self` — has the same meaning as Ruby's \"self\" keyword in the "
"context of\n"
"  parameters or return types. Recommended mostly for {tag:return} tags that "
"are\n"
"  chainable.\n"
"* `void` — indicates that the type for this tag is explicitly "
"undefined.\n"
"  Mostly used to specify {tag:return} tags that do not care about their "
"return\n"
"  value. Using a `void` return tag is recommended over no type, because it "
"makes\n"
"  the documentation more explicit about what the user should expect. YARD "
"will\n"
"  also add a note for the user if they have undefined return types, making "
"things\n"
"  clear that they should not use the return value of such a method."
msgstr ""
"* `true`, `false`, `nil` — メソッドがこれらの明確なリテラル値を返す時に\n"
"  利用される。次の事に留意する。\n"
"  あなたのメソッドが `true` や `false` 両方を返す場合、\n"
"  代わりにあなたは `Boolean` の慣例の型を使わなければならない。\n"
"* `self` — パラメータや戻りの型のコンテキストでRubyの\"self\"キーワードのように\n"
"  同じ意味を持つ。\n"
"  大体はチェーン可能な {tag:return} タグが推奨される。\n"
"* `void` — このタグが明確に未定義とされる型を指示する。\n"
"  一般的にそれらの戻り値について気にしない {tag:return} タグに利用される。\n"
"  `void` return タグを使う事によって、型がない事を知らせ、\n"
"  ユーザーが期待する事についての明確な情報のドキュメントを作れる。\n"
"  未定義の戻りの型を持つ場合、YARDはユーザーの為に注釈も追加し、\n"
"  それらのメソッドなどの戻り値を使わないものを明らかにする。"

#: ../docs/Tags.md:228
msgid ""
msgstr ""

#: ../docs/Tags.md:232
msgid ""
"
    \n"
"  Reference tag syntax applies only to meta-data tags, not directives.\n"
"
    "
msgstr ""
"
    \n"
"  Reference tag syntax applies only to meta-data tags, not directives.\n"
"
    "

#: ../docs/Tags.md:236
msgid ""
"If a tag's data begins with `(see OBJECT)` it is considered a \"reference tag"
"\".\n"
"A reference tag literally copies the tag data by the given tag name from "
"the\n"
"specified OBJECT. For instance, a method may copy all {tag:param} tags from\n"
"a given object using the reference tag syntax:"
msgstr ""
"`(see OBJECT)` を用い始まるタグデータの場合\"参照タグ\"と見なす。\n"
"参照タグは文字通り指定されたオブジェクトから与えられたタグ名によって\n"
"タグデータをコピーする。\n"
"例えばメソッドは次の参照タグ構文によって\n"
"与えられたオブジェクトから全ての {tag:param} タグをコピーする。"

#: ../docs/Tags.md:241
msgid ""
"    # @param [String] user the username for the operation\n"
"    # @param [String] host the host that this user is associated with\n"
"    # @param [Time] time the time that this operation took place\n"
"    def clean(user, host, time = Time.now) end"
msgstr ""
"    # @param [String] user the username for the operation\n"
"    # @param [String] host the host that this user is associated with\n"
"    # @param [Time] time the time that this operation took place\n"
"    def clean(user, host, time = Time.now) end"

#: ../docs/Tags.md:246
msgid ""
"    # @param (see #clean)\n"
"    def activate(user, host, time = Time.now) end"
msgstr ""
"    # @param (see #clean)\n"
"    def activate(user, host, time = Time.now) end"

#: ../docs/Tags.md:249
msgid "## Adding Custom Tags"
msgstr "## Adding Custom Tags"

#: ../docs/Tags.md:251
msgid ""
"
    If a tag is specific to a given project, consider "
"namespacing\n"
"  it by naming it in the form projectname.tagname, ie.,\n"
"  yard.tag_signature.
    "
msgstr ""
"
    If a tag is specific to a given project, consider namespacing\n"
"  it by naming it in the form projectname.tagname, ie.,\n"
"  yard.tag_signature.
    "

#: ../docs/Tags.md:255
msgid ""
"Custom tags can be added to YARD either via the command-line or "
"programmatically.\n"
"The programmatic method is not discussed in this document, but rather in "
"the\n"
"{file:docs/TagsArch.md} document."
msgstr ""
"カスタムタグはコマンドラインかプログラム経由でYARDに追加される。\n"
"プログラム的なメソッドはこのドキュメントの中で議論しないが、\n"
"{file:docs/TagsArch.md} のドキュメントで参照できる。"

#: ../docs/Tags.md:259
msgid ""
"To add a custom tag via the command-line or .yardopts file, you can use the\n"
"`--*-tag` options. A few different options are available for the common tag\n"
"syntaxes described above. For example, to add a basic freeform tag, use:"
msgstr ""
"コマンドラインや.yardoptsファイル経由でカスタムタグを追加するには、\n"
"`--*-tag` オプションを使う事ができる。\n"
"少数の異なるオプションは上で議論された一般的なタグ構文用に利用可能である。\n"
"例えば、基本のフリーフォームタグに追加するには次のようになる:"

#: ../docs/Tags.md:263
msgid ""
"    !!!sh\n"
"    $ yard doc --tag rest_url:\"REST URL\""
msgstr ""
"    !!!sh\n"
"    $ yard doc --tag rest_url:\"REST URL\""

#: ../docs/Tags.md:266
msgid ""
"This will register the `@rest_url` tag for use in your documentation and "
"display\n"
"this tag in HTML output wherever it is used with the heading \"REST URL\".\n"
"Note that the tag title should follow the tag name with a colon (`:`). "
"Other\n"
"tag syntaxes exist, such as the type specifier list freeform tag\n"
"(`--type-tag`), or a named key tag with types (`--type-name-tag`)."
msgstr ""
"これはあなたのドキュメントで利用するため `@rest_url` タグが追加され、\n"
"\"REST URL\"の表題と一緒にHTML出力でこのタグを表示する。\n"
"次の事に留意する。\n"
"タグタイトルは次のコロンを用いた(`:`)タグ名にしなければならない。\n"
"他のタグ構文は型指定のリストのフリーフォームタグの(`--type-tag`)や\n"
"(`--type-name-tag`)の型を用いるキー名のタグなどが存在する。"

#: ../docs/Tags.md:272
msgid ""
"If you want to create a tag but not display it in output (it is only for\n"
"programmatic use), add `--hide-tag tagname` after the definition:"
msgstr ""
"あなたがタグを作成する為にほしい場合\n"
"しかしその出力で表示しない場合(プログラム的にだけ利用する)\n"
"定義の後で `--hide-tag tagname` を追加する:"

#: ../docs/Tags.md:275
msgid ""
"    !!!sh\n"
"    $ yard doc --tag complexity:\"McCabe Complexity\" --hide-tag complexity"
msgstr ""
"    !!!sh\n"
"    $ yard doc --tag complexity:\"McCabe Complexity\" --hide-tag complexity"

#: ../docs/Tags.md:278
msgid ""
"Note that you might not need a tag title if you are hiding it. The title\n"
"part can be omitted."
msgstr ""
"次の事に留意する。\n"
"あなたはタグタイトル隠す場合は必要としないかもしれない。\n"
"タイトルの一部は除外できる。"

#: ../docs/Tags.md:281
msgid "{yard:include_tags}"
msgstr "{yard:include_tags}"

# title
#: ../docs/TagsArch.md:1
msgid "Tags Architecture"
msgstr "タグ構造"

#: ../docs/TagsArch.md:3
msgid "# Tags Architecture"
msgstr "# タグ構造"

#: ../docs/TagsArch.md:5
msgid "## Programmatic API"
msgstr "## プログラムのAPI"

#: ../docs/TagsArch.md:7
msgid "### Accessing Tag Information"
msgstr "### タグの情報を使う"

#: ../docs/TagsArch.md:9
msgid ""
"Tag metadata is added when a {YARD::Docstring} is added to a {file:docs/"
"CodeObjects.md code object}\n"
"using the {YARD::CodeObjects::Base#docstring=} attribute. In addition to "
"adding\n"
"conventional comments, tags are parsed and associated with the object. The "
"easiest\n"
"way to access tags on an object is to use the {YARD::CodeObjects::Base#tag} "
"and `#tags`\n"
"methods, for example:"
msgstr ""
"タグのメタデータは{YARD::Docstring}が\n"
"{YARD::CodeObjects::Base#docstring=} 属性を用い\n"
"{file:docs/CodeObjects.md コードオブジェクト} の為に追加される時、追加される。\n"
"通常型のコメントをつけることに加えて、タグは解析され、オブジェクトと関係付けられる。\n"
"オブジェクトのタグにアクセスするのに最も簡単な方法は、\n"
"{YARD::CodeObjects::Base#tag} や `#tags` メソッドを利用することである。\n"
"例えば:"

#: ../docs/TagsArch.md:15
msgid ""
"    # Using the Foo class object from above\n"
"    obj.tags(:tagname).first.text #=> \"some data\""
msgstr ""
"    # 上からFooクラスオブジェクトを使う\n"
"    obj.tags(:tagname).first.text #=> \"some data\""

#: ../docs/TagsArch.md:18
msgid ""
"Because multiple tags can be stored with the same name, they are stored as a "
"list\n"
"of tags. The `#tag` method is an alias for the first item in the list of "
"tags.\n"
"Also note that the `#tag`, `#tags` and `#has_tag?` methods are all "
"convenience\n"
"methods that delegate to the {YARD::Docstring} object described above."
msgstr ""
"同じ名前の複数のタグが格納されることもあるので、\n"
"それらはタグのリストとなっている。\n"
"`#tag` メソッドはタグのリストにおける最初のアイテムのエイリアスである。\n"
"また、the `#tag`についても述べておく。\n"
"`#tags` と `#has_tag?` のメソッドは上で記述された{YARD::Docstring}\n"
"オブジェクトを委譲する便利なメソッドである。"

#: ../docs/TagsArch.md:23
msgid "### Adding Custom Tags"
msgstr "### カスタムタグを付ける"

#: ../docs/TagsArch.md:25
msgid ""
"The `@tagname` tag used in the above examples is clearly not part of the "
"tags\n"
"that come with YARD. If such a tag would actually be part of documentation "
"under\n"
"a default install, YARD would raise a warning that the tag does not exist. "
"It is,\n"
"however, trivial to add this tag to be recognized by YARD."
msgstr ""
"前記の例などで使われている@tagnemeタグは明らかにYARDに存在するタグの一部では"
"ない。\n"
"もしそのようなタグがデフォルトでインストールされたドキュメントの一部であれ"
"ば、\n"
"YARDはそのようなタグは存在していないという警告を出すだろう。\n"
"つまり、YARDによって認識されるためのタグを付けることは、\n"
"重要ではない。"

#: ../docs/TagsArch.md:30
msgid ""
"All tags in YARD are added to the {YARD::Tags::Library tag library} which "
"makes\n"
"use of a tag factory class to parse the data inside the tags. To simply add "
"a\n"
"tag that stores simple text like our `@tagname` tag above, use:"
msgstr ""
"YARDのすべてのタグは{YARD::Tags::Library tag library}に追加される。\n"
"{YARD::Tags::Library tag library}はタグの中のデータを解析する為に、\n"
"タグファクトリークラスを利用している。\n"
"@tagnameタグのように単純なテキストを収納したタグを追加するなら、\n"
"次のようになる:"

#: ../docs/TagsArch.md:34
msgid "    YARD::Tags::Library.define_tag(\"A Sample Tag\", :tagname)"
msgstr "    YARD::Tags::Library.define_tag(\"A Sample Tag\", :tagname)"

#: ../docs/TagsArch.md:36
msgid ""
"This will now allow YARD to add the metadata from `@tagname` to the "
"docstring."
msgstr "docstringに`@tagname`からメタデータをつけることをYARDに許可する。"

#: ../docs/TagsArch.md:38
msgid "## Tag Factory Architecture"
msgstr "## タグファクトリー構造"

#: ../docs/TagsArch.md:40
msgid ""
"Recognizing a tag is one part of the process. Parsing the tag contents is "
"the\n"
"second step. YARD has a tag architecture that allows developers to add or "
"completely\n"
"change the way tags contents can be parsed."
msgstr ""
"タグを認識することはプロセスの一部である。\n"
"タグの中身を解析するのは第二段階となる。\n"
"YARDはタグの構造を持っている。\n"
"タグの構造によって、\n"
"開発者は中身が解析可能なタグを加えたり変更したりすることができる。\n"

#: ../docs/TagsArch.md:44
msgid ""
"The separation of registration and tag creation can be seen in the "
"following\n"
"class diagram:"
msgstr "登録の分離やタグ作成は次の表の通り。"

#: ../docs/TagsArch.md:47
msgid "![Tags Architecture Class Diagram](images/tags-class-diagram.png)"
msgstr "![Tags Architecture Class Diagram](images/tags-class-diagram.png)"

#: ../docs/TagsArch.md:49
msgid "### DefaultFactory"
msgstr "### デフォルトファクトリー"

#: ../docs/TagsArch.md:51
msgid ""
"By default, YARD has a few standard syntaxes that can be parsed for tags. "
"These\n"
"are all implemented by the {YARD::Tags::DefaultFactory} class. These "
"syntaxes\n"
"are:"
msgstr ""
"デフォルトで、YARDはタグを解析するいくつかの標準の構文を持っている。\n"
"それらはすべて {YARD::Tags::DefaultFactory}クラスで実装されている。\n"
"これらの構文は以下のとおり。\n"

#: ../docs/TagsArch.md:55
msgid ""
"  * Standard text: no parsing is done, but text is stripped of newlines and\n"
"    multiple spaces."
msgstr ""
"  * Standard text: 解析されていない。\n"
"    しかしテキストは新しい行や多重のスペースが取り除かれている。"

#: ../docs/TagsArch.md:58
msgid ""
"  * Raw text: does no parsing at all, no stripping of newlines or spaces. "
"This\n"
"    is best used for code snippets."
msgstr ""
"  * Raw text: まったく解析していない、新しい行やスペースは取り除かれていない。\n"
"    これはコードスニペットによく使われる。"

#: ../docs/TagsArch.md:61
msgid ""
"  * Raw text with title: does no parsing on the text but extracts the first "
"line\n"
"    of the metadata as the \"title\", useful for tags such as `@example`:"
msgstr ""
"  * Raw text with title: テキストの上では解析していないが、\n"
"    メタデータの最初の行を\"title\"として抽出する。以下の `@example` のようなタグで便利である:"

#: ../docs/TagsArch.md:64
msgid ""
"        # @example Inspect an element\n"
"        #   myobj.inspect #=> #"
msgstr ""
"        # @example Inspect an element\n"
"        #   myobj.inspect #=> #"

#: ../docs/TagsArch.md:67
msgid ""
"  * Text with types: parses a list of types at the beginning of the text. "
"Types\n"
"    are optional. The standard syntax is in the form `[type1, type2, ...]`,\n"
"    for example:"
msgstr ""
"  * Text with types: テキストの最初の部分で型のリストを解析する。型は任意で指定できる。\n"
"標準的な構文は`[type1, type2, ...]`という型をしている。例えば:"

#: ../docs/TagsArch.md:71
msgid ""
"        # @return [String, Symbol] a description here\n"
"        # @return description here with no types"
msgstr ""
"        # @return [String, Symbol] a description here\n"
"        # @return description here with no types"

#: ../docs/TagsArch.md:74
msgid ""
"  * Text with types and a name: parses a list of types at the beginning of "
"text\n"
"    followed by a name and extra descriptive text. For example:"
msgstr ""
"  * Text with types and a name: 名前や説明文が続くテキストの最初の部分で\n"
"型のリストを解析する。例えば:"

#: ../docs/TagsArch.md:77
msgid ""
"        # @param [String] str the string to reverse\n"
"        def reverse(str) '...' end"
msgstr ""
"        # @param [String] str the string to reverse\n"
"        def reverse(str) '...' end"

#: ../docs/TagsArch.md:80
msgid ""
"As mentioned above, this syntax is implemented by the `DefaultFactory` which "
"can\n"
"be swapped out for any factory. In some cases, a developer may want to "
"change\n"
"the type declaration syntax to be in the form:"
msgstr ""
"上述のように、この構文はDefaultFactoryで実装されている。\n"
"DefaultFactoryは任意のfactoryに交換されることができる。\n"
"時には、開発者はfactory構造の型宣言構文を変えることができる。"

#: ../docs/TagsArch.md:84
msgid "    # @tagname name  description"
msgstr "    # @tagname 名前 <型..., here> 説明"

#: ../docs/TagsArch.md:86
msgid ""
"This can be done by simply implementing a new factory that parses the data "
"in\n"
"this form."
msgstr ""
"このフォームの中でデータを解析する新しいファクトリーを実装するだけでよい。"

#: ../docs/TagsArch.md:89
msgid "### Implementing a Factory"
msgstr "### ファクトリー実装する"

#: ../docs/TagsArch.md:91
msgid ""
"Factories should implement the method `parse_tag` as well as any "
"`parse_tag_SUFFIX`\n"
"method where SUFFIX refers to the suffix added when declaring the tag. For "
"example,\n"
"a tag can also be declared as follows:"
msgstr ""
"ファクトリーはタグが宣言される時に、 `parse_tag_SUFFIX` メソッドのように\n"
"`parse_tag` メソッドが実装される。例えば、次のようにタグを定義できる。"

#: ../docs/TagsArch.md:95
msgid "    YARD::Tags::Library.define_tag \"Parameter\", :param, :with_types"
msgstr "    YARD::Tags::Library.define_tag \"Parameter\", :param, :with_types"

#: ../docs/TagsArch.md:97
msgid ""
"In such a case, the factory will be called with method "
"`parse_tag_with_types`. In\n"
"all cases, the method should return a new {YARD::Tags::Tag} object. "
"Generally,\n"
"the `parse_tag` methods take 2 or 3 parameters. A simple tag can be "
"implemented\n"
"as:"
msgstr ""
"上のようなケースでは、ファクトリーは `parse_tag_with_types` とともに呼び出される。\n"
"メソッドは新しい{YARD::Tags::Tag}オブジェクトを必ず返さなければならない。\n"
"一般に、 `parse_tag` メソッドは2つか3つの引数を取得する。\n"
"単純なタグは次のように実装することができる。"

#: ../docs/TagsArch.md:102
msgid ""
"    def parse_tag(tag_name, text)\n"
"      Tag.new(tag_name, text)\n"
"    end"
msgstr ""
"    def parse_tag(tag_name, text)\n"
"      Tag.new(tag_name, text)\n"
"    end"

#: ../docs/TagsArch.md:106
msgid ""
"The text parameter contains pre-parsed text with extra spaces and newlines "
"removed.\n"
"If required, the method could also be declared with a third parameter "
"containing\n"
"unmodified raw text:"
msgstr ""
"テキストパラメータは、\n"
"余分な空白と改行を削除するよう事前解析したテキストが含まれている。\n"
"もし必要なら以下のように、\n"
"3つ目の引数を用いて修正されていない生テキストを含めて宣言できる。"

#: ../docs/TagsArch.md:110
msgid ""
"    def parse_tag_with_raw_text(tag_name, text, raw_text)\n"
"      Tag.new(tag_name, raw_text)\n"
"    end"
msgstr ""
"    def parse_tag_with_raw_text(tag_name, text, raw_text)\n"
"      Tag.new(tag_name, raw_text)\n"
"    end"

#: ../docs/TagsArch.md:114
msgid ""
"Note that this method would be invoked for a tag declared with the `:"
"with_raw_text`\n"
"suffix."
msgstr ""
"次の事に留意する。\n"
"このメソッドはwith_raw_text suffixとともに宣言されたタグのために呼び出され"
"る。"

#: ../docs/TagsArch.md:117
msgid "### Changing the Factory"
msgstr "### ファクトリーを変更する"

#: ../docs/TagsArch.md:119
msgid ""
"To change the factory, set the {YARD::Tags::Library.default_factory} "
"attribute:"
msgstr ""
"ファクトリーを変更する為には、\n"
"以下の様に{YARD::Tags::Library.default_factory}属性を設定する。"

#: ../docs/TagsArch.md:121
msgid "    YARD::Tags::Library.default_factory = MyFactory"
msgstr "    YARD::Tags::Library.default_factory = MyFactory"

#: ../docs/TagsArch.md:123
msgid ""
"This must be done before any parsing is done, or the factory will not be "
"used."
msgstr ""
"これは解析が完了する前にしなければならない、でなければfactoryは使えない。"

# title
#: ../docs/Templates.md:1
msgid "Templates Architecture"
msgstr "テンプレート構造"

#: ../docs/Templates.md:3
msgid "# Templates Architecture"
msgstr "# テンプレート構造"

#: ../docs/Templates.md:5
msgid ""
"Templates are the main component in the output rendering process of YARD,\n"
"which is invoked when conventional HTML/text output needs to be rendered\n"
"for a set of code objects."
msgstr ""
"テンプレートは、YARDの処理を表示出力するのが主な内容となる。\n"
"そして、コードオブジェクトの集まりを表示する為に\n"
"従来のHTML/text出力が必要な時呼び出される。"

#: ../docs/Templates.md:9
msgid "## Design Goals"
msgstr "## 設計目標"

#: ../docs/Templates.md:11
msgid ""
"The general design attempts to be as abstracted from actual content and "
"templates\n"
"as possible. Unlike RDoc which uses one file to describe the entire "
"template,\n"
"YARD splits up the rendering of code objects into small components, "
"allowing\n"
"template modification for smaller subsets of a full template without having "
"to\n"
"duplicate the entire template itself. This is necessary because of YARD's "
"support\n"
"for plugins. YARD is designed for extensibility by external plugins, and "
"because\n"
"of this, no one plugin can be responsible for the entire template because "
"no\n"
"one plugin knows about the other plugins being used. For instance, if an "
"RSpec\n"
"plugin was added to support and document specifications in class templates,\n"
"this information would need to be transparently added to the template to "
"work\n"
"in conjunction with any other plugin that performed similar template "
"modifications.\n"
"The design goals can be summarized as follows:"
msgstr ""
"おおまかな設計目標は\n"
"テンプレートで、できるかぎり実際の内容から抽象化するのを試みる事である。\n"
"RDocとは違って、\n"
"YARDは、全てのテンプレートを説明する為に一つのファイルを利用し、\n"
"コードオブジェクトの表示を分割し小さい構成とする。\n"
"そして、テンプレートは\n"
"全てのテンプレートが重複無しに\n"
"最小のテンプレートの部分毎の修正を受け入れる\n"
"これは、プラグインのYARDのサポートの為に\n"
"必須となります。\n"
"YARDは、外部のプラグインによる拡張性を考え設計されている。\n"
"そんなわけで、プラグイン無しで全てのテンプレートを実行することが出来る。\n"
"何故なら、プラグインが無い場合は、\n"
"他のプラグインが利用される事について\n"
"識別するからである。\n"
"例えば、RSpecプラグインの場合、\n"
"サポートが追加されたり、\n"
"クラステンプレートの中の仕様が記述される。\n"
"同様のテンプレートの改良を施した\n"
"他のどんなプラグインを用いても、\n"
"連携するできるよう、テンプレートが\n"
"透過的に追加されることを必要とする。\n"
"設計目標は、以下の様に要約される。"

#: ../docs/Templates.md:24
msgid ""
"  1. Output should be able to be rendered for any arbitrary format with "
"little\n"
"     modification to YARD's source code. The addition of extra templates "
"should\n"
"     be sufficient.\n"
"  2. The output rendered for an object should independently rendered data\n"
"     from arbitrary sources. These independent components are called "
"\"sections\".\n"
"  3. Sections should be able to be inserted into any object without "
"affecting\n"
"     any existing sections in the document. This allows for easy "
"modification\n"
"     of templates by plugins."
msgstr ""
"  1. 出力はYARDのソースコードへの少ない変更で\n"
"     全て任意のフォーマット用に表示可能にすべきである。\n"
"     テンプレートの追加は充分なものにすべきである。\n"
"\n"
"  2. オブジェクト用に表示される出力は、任意のソースから独自にデータを\n"
"     表示するべきである。\n"
"     これらの独自構成は\"sections\"を呼び出す。\n"
"\n"
"  3. セクションはドキュメントの中の任意の存在するセクションへの影響無しで\n"
"     任意のオブジェクトに挿入される事を可能にするべきである。\n"
"     これはプラグインによるテンプレートの簡単な変更を受け入れる。"

#: ../docs/Templates.md:33
msgid "## Templates"
msgstr "## テンプレート"

#: ../docs/Templates.md:35
msgid ""
"Template modules are the objects used to orchestrate the design goals "
"listed\n"
"above. Specifically, they organize the sections and render the template "
"contents\n"
"depending on the format."
msgstr ""
"テンプレートモジュールは上で記述した設計目標を実現する為に利用されるオブジェクトとなる。\n"
"具体的にいうと、セクションを組織化したり、\n"
"フォーマットに依存するテンプレートの内容を表示する。"

#: ../docs/Templates.md:39
msgid "## Engine"
msgstr "## エンジン"

#: ../docs/Templates.md:41
msgid ""
"The Engine class orchestrates the creation and rendering of Template modules "
"and\n"
"handles serialization or specific rendering scenarios (like HTML). To "
"create\n"
"a template, use the {YARD::Templates::Engine.template template} method. The "
"two most\n"
"common methods used to initiate output are the {YARD::Templates::Engine."
"render render}\n"
"and {YARD::Templates::Engine.generate generate} methods which generate and\n"
"optionally serialize output to a file. The latter, `#generate`, is used\n"
"specially to generate HTML documentation and copy over assets that may be\n"
"needed. For instance, an object may be rendered with:"
msgstr ""
"エンジンクラスは、\n"
"作成とテンプレートモジュールの表示やシリアライズ処理や\n"
"特定の表示(HTMLのような)を統合する。\n"
"テンプレートを作成する為には、\n"
"{YARD::Templates::Engine.template template}メソッドを使用する。\n"
"出力を開始するために使われる二つの一般的なメソッドは\n"
"{YARD::Templates::Engine.render render} と\n"
"{YARD::Templates::Engine.generate generate} メソッドで\n"
"生成しファイルに任意で出力をシリアライズする。\n"
"その後で、 `#generate` メソッドは、\n"
"HTMLドキュメントを生成するための特別に使用され,\n"
"必要とされる資産をコピーする。\n"
"例えば,オブジェクトが次の例を用い表示される場合:"

#: ../docs/Templates.md:50
msgid "    YARD::Templates::Engine.render(:object => myobject)"
msgstr "    YARD::Templates::Engine.render(:object => myobject)"

#: ../docs/Templates.md:52
msgid "A set of objects may be rendered into HTML documentation by using:"
msgstr ""
"オブジェクトの設定は、以下の記法を用いる事によってHTMLドキュメントで表示され"
"る。"

#: ../docs/Templates.md:54
msgid ""
"    # all_objects is an array of module and class objects\n"
"    # options includes a :serializer key to copy output to the file system\n"
"    YARD::Templates::Engine.generate(all_objects, options)"
msgstr ""
"    # all_objects はモジュールの配列やクラスオブジェクトとなる\n"
"    # options はファイルシステムにコピー出力するの為に:serializerキーを含んで"
"いる。\n"
"    YARD::Templates::Engine.generate(all_objects, options)"

#: ../docs/Templates.md:58
msgid ""
"Note that these methods should not be called directly. The {YARD::"
"CodeObjects::Base}\n"
"class has a {YARD::CodeObjects::Base#format #format} helper method to render "
"an\n"
"object. For instance, the above render example is equivalent to the simple\n"
"call `myobject.format`. The `generate` method is a special kind of render\n"
"and is called from the {YARD::CLI::Yardoc} command line utility."
msgstr ""
"次の事に留意する。\n"
"これらのメソッドは、直接呼び出されるべきではない。\n"
"{YARD::CodeObjects::Base}クラスは\n"
"オブジェクトを表示する為の\n"
"{YARD::CodeObjects::Base#format #format} helper メソッドを\n"
"持っている。\n"
"例えば、上の表示の例は、\n"
"単純な`myobject.format`呼び出しと同等である。\n"
"`generate`メソッドは、特別な表示をし、\n"
"そしてそれは、{YARD::CLI::Yardoc}コマンドラインから呼び出せる。"

#: ../docs/Templates.md:64
msgid "## Template Options"
msgstr "## テンプレートオプション"

#: ../docs/Templates.md:66
msgid ""
"A template keeps state when it is rendering output. This state is kept in\n"
"an options hash which is initially passed to it during instantiation. Some\n"
"default options set the template style (`:template`), the output format (`:"
"format`),\n"
"and the serializer to use (`:serializer`). This options hash is modifiable\n"
"from all methods seen above. For example, initializing a template to output "
"as\n"
"HTML instead of text can be done as follows:"
msgstr ""
"テンプレートはそれが出力表示の時に状態を保持する。\n"
"この状態はハッシュのオプションの中で保持される。\n"
"そしは最初にインスタンス化される間に渡される。\n"
"幾つかのデフォルトのオプションはテンプレートスタイル(`:template`)\n"
"と出力フォーマット(`:format`)と(`:serializer`)を使うためのシリアライザーを設定する。\n"
"このハッシュのオプションは上で見られた全てのメソッドから変更可能\n"
"例えばテキストの代わりにHTMLとして出力するためにテンプレートを初期するには、次の様にできる。"

#: ../docs/Templates.md:73
msgid "    myobject.format(:format => :html)"
msgstr "    myobject.format(:format => :html)"

#: ../docs/Templates.md:75
msgid "## Serializer"
msgstr "## シリアライザー"

#: ../docs/Templates.md:77
msgid ""
"This class abstracts the logic involved in deciding how to serialize data "
"to\n"
"the expected endpoint. For instance, there is both a {YARD::Serializers::"
"StdoutSerializer StdoutSerializer}\n"
"and {YARD::Serializers::FileSystemSerializer FileSystemSerializer} class "
"for\n"
"outputting to console or to a file respectively. When endpoints with "
"locations\n"
"are used (like files or URLs), the serializer implements the {YARD::"
"Serializers::Base#serialized_path #serialized_path}\n"
"method. This allows the translation from a code object to its path at the "
"endpoint,\n"
"which enables inter-document linking."
msgstr ""
"このクラスは期待された出力先へ\n"
"データをシリアライズする為に、\n"
"決定方法,関連するロジックを抽象化する。\n"
"例えば、コンソールや個々のファイルの為の出力用の\n"
"{YARD::Serializers::StdoutSerializer StdoutSerializer}と、\n"
"{YARD::Serializers::FileSystemSerializer FileSystemSerializer} クラスがあ"
"る。\n"
"出力先が指定される時(ファイルやURLのような)、\n"
"シリアライザーは、{YARD::Serializers::Base#serialized_path #serialized_path}"
"メソッドを実装する。\n"
"これは、コードオブジェクトから出力先のパスまでの翻訳を受け入れ、\n"
"そして、内部のドキュメントのリンクを可能にする。"

#: ../docs/Templates.md:85
msgid ""
"Rendered objects are automatically serialized using the object if present,\n"
"otherwise the rendered object is returned as a string to its parent. Nested\n"
"Templates automatically set the serializer to nil so that they return\n"
"as a String to their parent."
msgstr ""
"表示されるオブジェクトが存在する場合は,\n"
"オブジェクトによって自動的にシリアライズされる。\n"
"それ以外の場合,表示されるオブジェクトはその親に文字列として返される。\n"
"ネストされたテンプレートはnilに自動的にシリアライザーを設定する。\n"
"なのでこれはそれらの親に文字列として返される。"

#: ../docs/Templates.md:90
msgid "## Creating a Template"
msgstr "## テンプレート作成"

#: ../docs/Templates.md:92
msgid ""
"Templates are represented by a directory inside the {YARD::Templates::Engine."
"template_paths}\n"
"on disk. A standard template directory looks like the following tree:"
msgstr ""
"テンプレートは\n"
"ディスク上の{YARD::Templates::Engine.template_paths}の中のディレクトリによって表される。\n"
"標準的なテンプレートは次の木構造のようになる。"

#: ../docs/Templates.md:95
msgid ""
"    (Assuming templates/ is a template path)\n"
"    templates\n"
"    `-- default\n"
"        |-- class\n"
"        |   |-- dot\n"
"        |   |   |-- setup.rb\n"
"        |   |   `-- superklass.erb\n"
"        |   |-- html\n"
"        |   |   |-- constructor_details.erb\n"
"        |   |   |-- setup.rb\n"
"        |   |   `-- subclasses.erb\n"
"        |   |-- setup.rb\n"
"        |   `-- text\n"
"        |       |-- setup.rb\n"
"        |       `-- subclasses.erb\n"
"        |-- docstring\n"
"        |   |-- html\n"
"        |   |   |-- abstract.erb\n"
"        |   |   |-- deprecated.erb\n"
"        |   |   |-- index.erb\n"
"        |   |   `-- text.erb\n"
"        |   |-- setup.rb\n"
"        |   `-- text\n"
"        |       |-- abstract.erb\n"
"        |       |-- deprecated.erb\n"
"        |       |-- index.erb\n"
"        |       `-- text.erb"
msgstr ""
"    (Assuming templates/ is a template path)\n"
"    templates\n"
"    `-- default\n"
"        |-- class\n"
"        |   |-- dot\n"
"        |   |   |-- setup.rb\n"
"        |   |   `-- superklass.erb\n"
"        |   |-- html\n"
"        |   |   |-- constructor_details.erb\n"
"        |   |   |-- setup.rb\n"
"        |   |   `-- subclasses.erb\n"
"        |   |-- setup.rb\n"
"        |   `-- text\n"
"        |       |-- setup.rb\n"
"        |       `-- subclasses.erb\n"
"        |-- docstring\n"
"        |   |-- html\n"
"        |   |   |-- abstract.erb\n"
"        |   |   |-- deprecated.erb\n"
"        |   |   |-- index.erb\n"
"        |   |   `-- text.erb\n"
"        |   |-- setup.rb\n"
"        |   `-- text\n"
"        |       |-- abstract.erb\n"
"        |       |-- deprecated.erb\n"
"        |       |-- index.erb\n"
"        |       `-- text.erb"

#: ../docs/Templates.md:123
msgid ""
"The path `default` refers to the template style (:template key in options "
"hash)\n"
"and the directories at the next level (such as `class`) refer to template\n"
"`:type` (options hash key) for a template. The next directory refers to the\n"
"output format being used defined by the `:format` template option."
msgstr ""
"パスの `default` はテンプレートスタイル(:template key in options hash)を参照し\n"
"次の階層でディレクトリは(例えば `class` など)\n"
"テンプレート用のテンプレートの `:type` (ハッシュのオプションキー)を参照する。\n"
"次のディレクトリは\n"
"`:format` テンプレートオプションによって定義され、\n"
"利用される出力フォーマットを参照する。"

#: ../docs/Templates.md:128
msgid ""
"As we saw in the above example, the format option can be set to `:html`, "
"which\n"
"would use the `html/` directory instead of `text/`. Finally, the individual ."
"erb\n"
"files are the sections that make up the template."
msgstr ""
"だれもが上の例で見た通り、\n"
"フォーマットオプションは `:html` に設定でき、\n"
"`text/` の代わりに `html/` ディレクトリを利用する。\n"
"最終的に個々の.erbファイルは、テンプレートを作り上げるセクションである。"

#: ../docs/Templates.md:132
msgid ""
"Note that the subdirectory `html/` is also its own \"template\" that "
"inherits\n"
"from the parent directory. We will see more on this later."
msgstr ""
"次の事に留意する。\n"
"`html/` サブディレクトリは\n"
"それ自身が親ディレクトリから継承する\"テンプレート\"でもある。\n"
"この後の項で詳細がされる。"

#: ../docs/Templates.md:135
msgid "## setup.rb"
msgstr "## setup.rb"

#: ../docs/Templates.md:137
msgid ""
"Every template should have at least one `setup.rb` file that defines the\n"
"{YARD::Templates::Template#init #init} method to set the\n"
"{YARD::Templates::Template#sections #sections} used by the template. If\n"
"a setup.rb is not defined in the template itself, there should be a "
"template\n"
"that is inherited (via parent directory or explcitly) that sets the "
"sections\n"
"on a newly created template."
msgstr ""
"常にテンプレートは少なくとも\n"
"テンプレートによって利用した{YARD::Templates::Template#sections #sections}を設定するために\n"
"{YARD::Templates::Template#init #init}メソッドを定義する\n"
"`setup.rb` ファイルを持つ。\n"
"setup.rbがテンプレートの中で未定義の場合は、\n"
"新規に作成されたテンプレート上のセクションを設定し、\n"
"継承される(親のディレクトリや明示的に)テンプレートになるべきである。"

#: ../docs/Templates.md:144
msgid "A standard setup.rb file looks like:"
msgstr "標準的なsetup.rbファイルは以下のように見える。"

#: ../docs/Templates.md:146
msgid ""
"    def init\n"
"      sections :section1, :section2, :section3\n"
"    end"
msgstr ""
"    def init\n"
"      sections :section1, :section2, :section3\n"
"    end"

#: ../docs/Templates.md:150
msgid "## Sections"
msgstr "## セクション"

#: ../docs/Templates.md:152
msgid ""
"Sections are smaller components that correlate to template\n"
"fragments. Practically speaking, a section can either be a template "
"fragment\n"
"(a conventional .erb file or other supported templating language), a method\n"
"(which returns a String) or another {YARD::Templates::Template} (which in "
"turn has its own\n"
"list of sections)."
msgstr ""
"セクションはテンプレートフラグに関連するより小さい構成要素である。\n"
"事実上、セクションはいづれかの\n"
"テンプレートの\n"
"フラグ(慣習で.erbファイルや他にサポートされたテンプレート言語),\n"
"メソッド(文字列を返す)やそれ以外{YARD::Templates::Template}にできる\n"
"(言い換えればセクションの自身のリストを持つ)"

#: ../docs/Templates.md:158
msgid "## Nested Sections"
msgstr "## ネストしたセクション"

#: ../docs/Templates.md:160
msgid ""
"Sections often require the ability to encapsulate a set of sub-sections in "
"markup\n"
"(HTML, for instance). Rather than use heavier Template subclass objects, a "
"more\n"
"lightweight solution is to nest a set of sub-sections as a list that "
"follows\n"
"a section, for example:"
msgstr ""
"セクションは時々マークアップで\n"
"サブセクションのグループを要約するのに能力を必要とする。(例えばHTML)\n"
"サブクラスオブジェクトのより重いテンプレートを使うより、\n"
"より軽い答えが\n"
"次のセクションのリストとしてサブセクションのグループをネストする事である。\n"
"例えば:"

#: ../docs/Templates.md:165
msgid ""
"    def init\n"
"      sections :header, [:section_a, :section_b]\n"
"    end"
msgstr ""
"    def init\n"
"      sections :header, [:section_a, :section_b]\n"
"    end"

#: ../docs/Templates.md:169
msgid ""
"The above example nests `section_a` and `section_b` within the `header` "
"section.\n"
"Practically speaking, these sections can be placed in the result by "
"`yield`ing\n"
"to them. A sample header.erb template might contain:"
msgstr ""
"上の例は、 `header` セクションの中に\n"
"`section_a` と `section_b` をネストする。\n"
"具体的には、これらのセクションは、\n"
"`yield` する事によってその結果の中に置かれる。\n"
"例のheader.erbテンプレートは以下を含んでいる"

#: ../docs/Templates.md:173
msgid ""
"    
    Header
    \n"
"    
    \n"
"      <%= yieldall %>\n"
"    
    "
msgstr ""
"    
    Header
    \n"
"    
    \n"
"      <%= yieldall %>\n"
"    
    "

#: ../docs/Templates.md:178
msgid ""
"This template code would place the output of `section_a` and `section_b` "
"within\n"
"the above div element. Using `yieldall`, we can also change the object that "
"is being\n"
"rendered. For example, we may want to yield the first method of the class.\n"
"We can do this like so:"
msgstr ""
"このテンプレートのコードは、\n"
"上のdiv属性の中で `section_a` と `section_b` の\n"
"出力ををセットする。\n"
"`yieldall` によって私達は、\n"
"表示されるオブジェクトを変更もできる。\n"
"例えばクラスの最初のメソッドをyieldの為にしたいとすると、\n"
"以下のようにできる。"

#: ../docs/Templates.md:183
msgid ""
"    
    First method
    \n"
"    <%= yieldall :object => object.meths.first %>"
msgstr ""
"    
    First method
    \n"
"    <%= yieldall :object => object.meths.first %>"

#: ../docs/Templates.md:186
msgid ""
"This would run the nested sections for the method object instead of the "
"class."
msgstr ""
"これは、クラスの代わりにメソッドオブジェクト用のネストされたセクションを起動"
"する。"

#: ../docs/Templates.md:188
msgid ""
"Note that `yieldall` yields to all subsections, whereas `yield` will yield\n"
"to each individually (in order) until there are no more left to yield to.\n"
"In the vast majority of cases, you'd want to use `yieldall`, since `yield`\n"
"makes it hard for users to override your template."
msgstr ""
"次の事に留意する。\n"
"`yieldall` は全ての下位セクションをyieldするのに対して、\n"
"`yield` は、要素が無くなるまで個々に(順番に)yieldする。\n"
"多くの場合あなたは `yieldall` を使いたいと思っただろう。\n"
"`yield` はユーザーがあなたのテンプレートを上書きする為に\n"
"確実に実行するからである。"

#: ../docs/Templates.md:193
msgid "## Inheriting Templates"
msgstr "## 継承するテンプレート"

#: ../docs/Templates.md:195
msgid ""
"Parent directory templates are automatically inherited (or mixed in, to be\n"
"more accurate) by the current template. This means that the 'default/class/"
"html'\n"
"template automatically inherits from 'default/class'. This also means that "
"anything\n"
"defined in 'default/class/setup.rb' can be overridden by 'default/class/html/"
"setup.rb'."
msgstr ""
"親のディレクトリのテンプレートは\n"
"現在のテンプレートによって自動的に継承される。\n"
"(または、正確にはmix-inされる)\n"
"つまり 'default/class/html' テンプレートは、\n"
"'default/class'から自動的に継承する。\n"
"そして 'default/class/setup.rb' の中に定義されるもの全ては、\n"
"'default/class/html/setup.rb' によって上書きされることも意味する。\n"
"(yard/lib以下の話ではなくyard/templates以下の話)"

#: ../docs/Templates.md:200
msgid ""
"Since the Template module is a module, and not a class, they can be mixed "
"in\n"
"explicitly (via include/extend) from other templates, which allows "
"templates\n"
"to share erb files or helper logic. The 'default/class' template explicitly\n"
"mixes in the 'default/module' template, since it uses much of the same "
"sections.\n"
"This is done with the helper {YARD::Templates::Template::ClassMethods#T T} "
"method, which\n"
"is simply a shorthand for {YARD::Templates::Engine.template Engine."
"template}.\n"
"It can then override (using standard inheritance) the sections from the "
"module\n"
"template and insert sections pertaining to classes. This is one of the "
"design\n"
"goals described above."
msgstr ""
"Templateモジュールはモジュールであり,クラスではない。\n"
"他のテンプレートから(include/extend経由)明示的に混ぜられ、\n"
"erbファイルやヘルパーロジックを共有するためにテンプレートを受け入れる。\n"
"'default/class'テンプレートは明示的に'default/module'テンプレートの中で混ぜられ、\n"
"同じセクションを使う。\n"
"これはヘルパーメソッドの {YARD::Templates::Template::ClassMethods#T T} を用い完了し、\n"
"それは単純に{YARD::Templates::Engine.template Engine.template}用の略記法で、\n"
"その時モジュールのテンプレートからセクションを上書き(標準の継承を使う事によって)できる\n"
"そしてクラスに付随するセクションを挿入する。\n"
"これは上で説明された設計目標の一つである。"

#: ../docs/Templates.md:210
msgid "For instance, the first line in `default/class/html/setup.rb` is:"
msgstr "例えば `default/class/html/setup.rb` の中の最初の行は以下のように:"

#: ../docs/Templates.md:212
msgid "    include T('default/module/html')"
msgstr "    include T('default/module/html')"

#: ../docs/Templates.md:214
msgid ""
"This includes the 'default/module/html', which means it also includes "
"'default/module'\n"
"by extension. This allows class to make use of any of module's erb files."
msgstr ""
"この'default/module/html'のincludeは、\n"
"拡張によって'default/module'を含める意味となる。\n"
"この拡張は任意でerbモジュールのファイルから利用するクラスを受け入れる。"

#: ../docs/Templates.md:217
msgid "## Inserting and Traversing Sections"
msgstr "## 挿入とトラバース(辿る)セクション"

#: ../docs/Templates.md:219
msgid ""
"The ability to insert sections was mentioned above. The class template, for\n"
"instance, will modify the #init method to insert class specific sections:"
msgstr ""
"挿入セクションの機能は上で述べた。\n"
"テンプレートクラス、例えば、\n"
"以下のクラスの特定のセクションを挿入する為に#initメソッドを変更する:"

#: ../docs/Templates.md:222
msgid ""
"    def init\n"
"      super\n"
"      sections.place(:subclasses).before(:children)\n"
"      sections.delete(:children)\n"
"      sections.place([:constructor_details, [T('method_details')]]).before(:"
"methodmissing)\n"
"    end"
msgstr ""
"    def init\n"
"      super\n"
"      sections.place(:subclasses).before(:children)\n"
"      sections.delete(:children)\n"
"      sections.place([:constructor_details, [T('method_details')]]).before(:methodmissing)\n"
"    end"

#: ../docs/Templates.md:229
msgid ""
"Observe how sections has been modified after the super method was called "
"(the\n"
"super method would have been defined in `default/module/setup.rb`). The\n"
"`sections` object is of the {YARD::Templates::Section} class and allows "
"sections to be inserted\n"
"before or after another section using {Array#place} by it's given name "
"rather\n"
"than index. This allows the overriding of templates in a way that does not\n"
"depend on where the section is located (since it may have been overridden by\n"
"another module)."
msgstr ""
"superメソッドが呼び出された後でセクションが変更されたか確認する。\n"
"(superメソッドは `default/module/setup.rb` で定義されている)\n"
"`sections`オブジェクトは{YARD::Templates::Section}クラスのであり、\n"
"インデックスより与えられた名前によって\n"
"{Array#place}を使う事によって\n"
"他のセクションの前後で挿入されるセクションを受け入れる\n"
"これはセクションが示されるところに依存しない方法で\n"
"テンプレートの上書きを受け入れる。\n"
"(なので他のモジュールによって上書きされるかもしれない)"

#: ../docs/Templates.md:237
msgid ""
"You can also use `sections[:name]` to find the first child section named `:"
"name`.\n"
"For instance, with the following sections declaration:"
msgstr ""
"あなたは、 `:name` と名付けられた最初の子のセクション名を探す為に\n"
"`sections[:name]` を利用できる。\n"
"例えば、次のようなセクション宣言を用いる。"

#: ../docs/Templates.md:240
msgid "    sections :a, [:b, :c, [:d]]"
msgstr "    sections :a, [:b, :c, [:d]]"

#: ../docs/Templates.md:242
msgid "You can get to the :d section with:"
msgstr "次のようにすると、:dセクションを取得できる。"

#: ../docs/Templates.md:244
msgid "    sections[:a][:c][:d]"
msgstr "    sections[:a][:c][:d]"

#: ../docs/Templates.md:246
msgid ""
"You can use this to insert a section inside a nested set without using "
"indexed\n"
"access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:"
msgstr ""
"アクセスを索引しないで、\n"
"ネストした集合の内部の\n"
"セクションを挿入する為に\n"
"これを利用できる。<\n"
"次のコマンドは `[:a, [:b, :c, [:d, :e]]]` の様な結果になる。"

#: ../docs/Templates.md:249
msgid "    sections[:a][:c].place(:e).after(:d)"
msgstr "    sections[:a][:c].place(:e).after(:d)"

#: ../docs/Templates.md:251
msgid ""
"There are also two methods, {Insertion#before_any} and "
"{Insertion#after_any},\n"
"which allow you to insert sections before or after the first matching "
"section name\n"
"recursively. The above example could simply be rewritten as:"
msgstr ""
"二つのメソッド、{Insertion#before_any}と{Insertion#after_any}がある。\n"
"これは、再帰的に最初にマッチするセクション名の前後のセクションへの挿入を可能"
"にする。\n"
"上の例は、単純に次のように書き換えできた。"

#: ../docs/Templates.md:255
msgid "    sections.place(:e).after_any(:d)"
msgstr "    sections.place(:e).after_any(:d)"

#: ../docs/Templates.md:257
msgid "## Overriding Templates by Registering a Template Path"
msgstr "## テンプレートパスを記録しテンプレートを上書き"

#: ../docs/Templates.md:259
msgid ""
"Inheriting templates explicitly is useful when creating a customized "
"template\n"
"that wants to take advantage of code re-use. However, most users who want\n"
"to customize YARD templates will want to override existing behaviour "
"without\n"
"creating a template from scratch."
msgstr ""
"明示的に継承するテンプレートは、\n"
"再利用したいコードのテンプレートを\n"
"カスタマイズし作成する時に便利である。\n"
"しかしながら、一般的なYARDテンプレートをカスタマイズしたいユーザーは、\n"
"下書きからテンプレートの作成無しで既存の挙動を上書きしたいだろう。"

#: ../docs/Templates.md:264
msgid ""
"YARD solves this problem by allowing other template paths to be registered.\n"
"Because template modules are represented by a relative path such as 'default/"
"class',\n"
"they can be found within any of the registered template paths. A new "
"template\n"
"path is registered as:"
msgstr ""
"YARDは記録される他のテンプレートパスを\n"
"受け入れる事によってこの問題を解決する。\n"
"何故なら、テンプレートモジュールは、\n"
"'default/class'のような、相対パスによって表される。\n"
"それは、テンプレートパスの記録される全ての中で見られる\n"
"新しいテンプレートは、次のように記録される。"

#: ../docs/Templates.md:269
msgid ""
"    YARD::Templates::Engine.register_template_path '/path/to/mytemplates'"
msgstr "    YARD::Templates::Engine.register_template_path '/path/to/mytemplates'"

#: ../docs/Templates.md:271
msgid ""
"At this point, any time the 'default/class' template is loaded, the "
"template\n"
"will first be looked for inside the newly registered template path. If "
"found,\n"
"it will be used as the template module, with the modules from the other\n"
"template paths implicitly mixed in."
msgstr ""
"この場所で、毎回、'default/class'テンプレートは、ロードされる。\n"
"テンプレートは\n"
"新しく記録したテンプレートパス内部に最初に固定される。\n"
"もし見つかった場合、\n"
"暗黙の内にmix-inされる他のテンプレートパスからモジュールと共に、\n"
"テンプレートモジュールのように利用される。"

#: ../docs/Templates.md:276
msgid ""
"Therefore, by using the same directory structure as a builtin YARD "
"template,\n"
"a user can customize or override individual templates as if the old ones "
"were\n"
"inherited. A real world example would further modify the 'default/class' "
"template\n"
"seen above by creating such a path in our '/path/to/mytemplates' custom "
"template\n"
"path:"
msgstr ""
"従って組み込みのYARDのテンプレートとして同じディレクトリ構造体を\n"
"使うことによってユーザーはカスタマイズできたり、\n"
"古いものが継承される場合など個々のテンプレートを上書きできる。\n"
"実際の例は、\n"
"更に例の'/path/to/mytemplates'のカスタムテンプレートパスの中のパスなど作成することによって\n"
"上で見た'default/class'テンプレートを変更する。"

#: ../docs/Templates.md:282
msgid ""
"    /path/to/mytemplates/:\n"
"    |-- class\n"
"    |   |-- html\n"
"    |   |   |-- customsection.erb\n"
"    |   |-- setup.rb"
msgstr ""
"    /path/to/mytemplates/:\n"
"    |-- class\n"
"    |   |-- html\n"
"    |   |   |-- customsection.erb\n"
"    |   |-- setup.rb"

#: ../docs/Templates.md:288
msgid "The `setup.rb` file would look like:"
msgstr "`setup.rb` ファイルは次の様になる。"

#: ../docs/Templates.md:290
msgid ""
"    def init\n"
"      super\n"
"      sections.push :customsection\n"
"    end"
msgstr ""
"    def init\n"
"      super\n"
"      sections.push :customsection\n"
"    end"

#: ../docs/Templates.md:295
msgid ""
"Now, when a class object is formatted as HTML, our customsection.erb will "
"be\n"
"appended to the rendered data."
msgstr ""
"クラスオブジェクトがHTMLとしてフォーマットされる時は、\n"
"例のcustomsection.erbは表示されるデータに適用される。"

#: ../docs/Templates.md:299
msgid "### Overriding Stylesheets and Javascripts"
msgstr "### スタイルシートとJavascriptsを上書きする。"

#: ../docs/Templates.md:301
msgid ""
"Template authors can override existing stylesheets and javascripts by "
"creating\n"
"a file with the same name as existing files within the `fulldoc` template. "
"The\n"
"documentation output will utilize the new replacement file."
msgstr ""
"テンプレートの著者は\n"
"`fulldoc` テンプレートの中で既存のファイルのような同じ名前を用い、\n"
"ファイルを作成する事によって\n"
"既存のスタイルシートとjavascriptを\n"
"上書きできる。\n"
"ドキュメント出力は新しく置換するファイルを利用する。"

#: ../docs/Templates.md:305
msgid "YARD's `fulldoc` template defines three stylesheets:"
msgstr "YARDの `fulldoc` テンプレートはツリーのスタイルシートを定義する。"

#: ../docs/Templates.md:307
msgid ""
"    /yard/templates/default/:\n"
"    |-- fulldoc\n"
"    |   |-- html\n"
"    |   |   |-- css\n"
"    |   |   |   |-- common.css\n"
"    |   |   |   |-- full_list.css\n"
"    |   |   |   |-- style.css"
msgstr ""
"    /yard/templates/default/:\n"
"    |-- fulldoc\n"
"    |   |-- html\n"
"    |   |   |-- css\n"
"    |   |   |   |-- common.css\n"
"    |   |   |   |-- full_list.css\n"
"    |   |   |   |-- style.css"

#: ../docs/Templates.md:315
msgid "The `style.css` is the primary stylesheet for the HTML output."
msgstr "`style.css` は、HTML出力用の主要なスタイルシートとなる。"

#: ../docs/Templates.md:317
msgid ""
"The `full_list.css` is an additional stylesheet loaded specifically for the\n"
"search field menus (i.e. class list, method list, and file list)."
msgstr ""
"追加のスタイルシートの `full_list.css` は、厳密にいえば検索フィールドメニューの為にロードされる。\n"
"(すなわち、クラスリスト、メソッドリスト、ファイルリスト)"

#: ../docs/Templates.md:320
msgid ""
"The `common.css` is an empty css file that an template author can easily "
"override\n"
"to provide custom styles for their plugin. However, if a user installs "
"multiple\n"
"plugins that utilize this same file to deliver styles, it is possible that "
"they\n"
"will be overridden."
msgstr ""
"`common.css` は、\n"
"テンプレートの著者がプラグイン用の\n"
"カスタムスタイルを提供する為に\n"
"簡単に上書きする空のcssファイルとなる。\n"
"しかしながらユーザーがスタイルを実行するのに、\n"
"同じファイルを利用する複数のプラグインをインストールした場合、\n"
"上書きされる事が問題になる。"

#: ../docs/Templates.md:325
msgid "YARD's `fulldoc` template defines three javascript files:"
msgstr "YARDの `fulldoc` テンプレートは次の様にツリー上のjavascriptファイルを定義する。"

#: ../docs/Templates.md:327
msgid ""
"    /yard/templates/default/:\n"
"    |-- fulldoc\n"
"    |   |-- html\n"
"    |   |   |-- js\n"
"    |   |   |   |-- app.js\n"
"    |   |   |   |-- full_list.js\n"
"    |   |   |   |-- jquery.js"
msgstr ""
"    /yard/templates/default/:\n"
"    |-- fulldoc\n"
"    |   |-- html\n"
"    |   |   |-- js\n"
"    |   |   |   |-- app.js\n"
"    |   |   |   |-- full_list.js\n"
"    |   |   |   |-- jquery.js"

#: ../docs/Templates.md:335
msgid "The `app.js` is the primary javascript file for the HTML output."
msgstr "`app.js` はHTML出力用の主要なjavascriptファイルとなる。"

#: ../docs/Templates.md:337
msgid ""
"The `full_list.js` defines additional javascript loaded specifically for "
"the\n"
"search field menus (i.e. class list, method list, and file list)."
msgstr ""
"追加のjavascriptを定義する `full_list.js` は、\n"
"厳密にいえば検索フィールドメニュー用にロードされる。\n"
"(すなわち、クラスリスト、メソッドリスト、ファイルリスト)"

#: ../docs/Templates.md:340
msgid "The `jquery.js` is copy of the jquery javascript library."
msgstr "`jquery.js` はjquery javascriptライブラリをコピーする。"

#: ../docs/Templates.md:342
msgid "### Adding a Custom Stylesheet or Javascript"
msgstr "### カスタムスタイルシートとJavascritpを追加する"

#: ../docs/Templates.md:344
msgid ""
"To load additional stylesheets and javascripts with every page (except the "
"search\n"
"field menus) generated from the base `layout` template:"
msgstr ""
"基本の `layout` テンプレートから生成した\n"
"全てのページと共に、\n"
"追加のスタイルシートとjavascriptをロードするには\n"
"(但し、検索フィールドメニューを除く):\n"

#: ../docs/Templates.md:347
msgid ""
"  1. Define your own custom stylesheet and/or javascript file\n"
"     (default/ is the default template name inside of the /template root "
"directory):"
msgstr ""
"  1. 自分のカスタムスタイルシートやjavascriptファイルを定義する。\n"
"     (デフォルトのディレクトリは/templateルートディレクトリの内部のデフォルトのテンプレート名である):"

#: ../docs/Templates.md:350
msgid ""
"        /template/default/:\n"
"        |-- fulldoc\n"
"        |   |-- html\n"
"        |   |   |-- css\n"
"        |   |   |   |-- custom.css\n"
"        |   |   |-- js\n"
"        |   |   |   |-- custom.js"
msgstr ""
"          /template/default/:\n"
"          |-- fulldoc\n"
"          |   |-- html\n"
"          |   |   |-- css\n"
"          |   |   |   |-- custom.css\n"
"          |   |   |-- js\n"
"          |   |   |   |-- custom.js"

#: ../docs/Templates.md:358
msgid ""
"  2. Create a `setup.rb` in the `layout` template directory and override the "
"methods\n"
"     `stylesheets` and `javascripts`. The path to the template would be:"
msgstr ""
"  2. `layout` テンプレートディレクトリの中の `setup.rb` を作成して\n"
"     `javascripts` と `stylesheets` メソッドを上書きする。\n"
"     テンプレートのパスは次の様になる:"

#: ../docs/Templates.md:361
msgid ""
"        /template/default/:\n"
"        |-- layout\n"
"        |   |-- html\n"
"        |   |   |-- setup.rb"
msgstr ""
"          /template/default/:\n"
"          |-- layout\n"
"          |   |-- html\n"
"          |   |   |-- setup.rb"

#: ../docs/Templates.md:366
msgid "      And the code would look like:"
msgstr "      そしてコードは次のようになる。"

#: ../docs/Templates.md:368
msgid ""
"        def stylesheets\n"
"          # Load the existing stylesheets while appending the custom one\n"
"          super + %w(css/custom.css)\n"
"        end"
msgstr ""
"          def stylesheets\n"
"            # カスタムのcssが追加される間、存在するスタイルシートをロードする\n"
"            super + %w(css/custom.css)\n"
"          end"

#: ../docs/Templates.md:373
msgid ""
"        def javascripts\n"
"          # Load the existing javascripts while appending the custom one\n"
"          super + %w(js/custom.js)\n"
"        end"
msgstr ""
"          def javascripts\n"
"            # カスタムのjavascriptが追加される間、存在するスタイルシートをロードする\n"
"            super + %w(js/custom.js)\n"
"          end"

#: ../docs/Templates.md:379
msgid ""
"To load additional stylesheets and javascripts for the search menus loaded "
"from\n"
"the `fulldoc` template:"
msgstr ""
"`fulldoc` テンプレートからロードされた検索メニュー用の\n"
"追加のスタイルシートとjavascriptをロードするには:"

#: ../docs/Templates.md:382
msgid "  1. Define your own custom stylesheet and/or javascript file."
msgstr "  1. 自分のカスタムスタイルシートとjavascriptファイルを定義する。"

#: ../docs/Templates.md:384
msgid ""
"        /path/to/mytemplates/:\n"
"        |-- fulldoc\n"
"        |   |-- html\n"
"        |   |   |-- css\n"
"        |   |   |   |-- custom_full_menu.css\n"
"        |   |   |-- js\n"
"        |   |   |   |-- custom_full_menu.js"
msgstr ""
"          /path/to/mytemplates/:\n"
"          |-- fulldoc\n"
"          |   |-- html\n"
"          |   |   |-- css\n"
"          |   |   |   |-- custom_full_menu.css\n"
"          |   |   |-- js\n"
"          |   |   |   |-- custom_full_menu.js"

#: ../docs/Templates.md:393
msgid ""
"  3. Override the methods `stylesheets_full_list` and "
"`javascripts_full_list`\n"
"     in the `setup.rb` file inside fulldoc/html."
msgstr ""
"  3. fulldoc/html内の `setup.rb` ファイルの中の\n"
"  `stylesheets_full_list` と `javascripts_full_list` メソッドを上書きする。"

#: ../docs/Templates.md:396
msgid ""
"        def stylesheets_full_list\n"
"          # Load the existing stylesheets while appending the custom one\n"
"          super + %w(css/custom.css)\n"
"        end"
msgstr ""
"        def stylesheets_full_list\n"
"          # カスタムのcssが追加される間、存在するスタイルシートをロードする\n"
"          super + %w(css/custom.css)\n"
"        end"

#: ../docs/Templates.md:401
msgid ""
"        def javascripts_full_list\n"
"          # Load the existing javascripts while appending the custom one\n"
"          super + %w(js/custom.js)\n"
"        end"
msgstr ""
"        def javascripts_full_list\n"
"          # カスタムのjavascriptが追加される間、存在するスタイルシートをロードする\n"
"          # Load the existing javascripts while appending the custom one\n"
"          super + %w(js/custom.js)\n"
"        end"

#: ../docs/Templates.md:406
msgid "### Overriding Search Menus"
msgstr "### 検索メニューを上書きする。"

#: ../docs/Templates.md:408 ../docs/Templates.md:443
msgid "By default YARD's `fulldoc` template generates three search fields:"
msgstr "デフォルトでYARDの `fulldoc` テンプレートは次のような検索フィールドのツリーを生成する。"

#: ../docs/Templates.md:410 ../docs/Templates.md:445
msgid ""
"  * Class List\n"
"  * Method List\n"
"  * File List"
msgstr ""
"  * Class List\n"
"  * Method List\n"
"  * File List"

#: ../docs/Templates.md:414
msgid "Their contents are rendered in methods within the `fulldoc` template:"
msgstr "その内容は、 `fulldoc` テンプレートの中でメソッドの中を表示する。"

#: ../docs/Templates.md:416
msgid ""
"  * `generate_class_list`\n"
"  * `generate_method_list`\n"
"  * `generate_file_list`"
msgstr ""
"  * `generate_class_list`\n"
"  * `generate_method_list`\n"
"  * `generate_file_list`"

#: ../docs/Templates.md:420
msgid "To override these lists you will need to:"
msgstr "これらのリスト上書きするには:"

#: ../docs/Templates.md:422
msgid ""
"  1. Create a `setup.rb` in the `fulldoc` template directory and override "
"the\n"
"     particular method."
msgstr ""
"  1. `fulldoc` テンプレートディレクトリの中の `setup.rb` を作成し、\n"
"  メソッドの詳細を上書きする。"

#: ../docs/Templates.md:425 ../docs/Templates.md:477
msgid ""
"         /path/to/mytemplates/:\n"
"         |-- fulldoc\n"
"         |   |-- html\n"
"         |   |   |-- setup.rb"
msgstr ""
"         /path/to/mytemplates/:\n"
"         |-- fulldoc\n"
"         |   |-- html\n"
"         |   |   |-- setup.rb"

#: ../docs/Templates.md:430
msgid ""
"         def generate_method_list\n"
"           @items = prune_method_listing(Registry.all(:method), false)\n"
"           @items = @items.reject {|m| m.name.to_s =~ /=$/ && m."
"is_attribute? }"
msgstr ""
"         def generate_method_list\n"
"           @items = prune_method_listing(Registry.all(:method), false)\n"
"           @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }"

#: ../docs/Templates.md:434
msgid ""
"           # Here we changed the functionality to reverse the order of "
"displayed methods\n"
"           @items = @items.sort_by {|m| m.name.to_s }.reverse\n"
"           @list_title = \"Method List\"\n"
"           @list_type = \"methods\"\n"
"           asset('method_list.html', erb(:full_list))\n"
"         end"
msgstr ""
"         # ここでメソッドを表示する順番を逆にする為の機能を変更する\n"
"           @items = @items.sort_by {|m| m.name.to_s }.reverse\n"
"           @list_title = \"Method List\"\n"
"           @list_type = \"methods\"\n"
"           asset('method_list.html', erb(:full_list))\n"
"         end"

#: ../docs/Templates.md:441
msgid "### Adding Additional Search Menus"
msgstr "### 追加の検索メニューを追加する。"

#: ../docs/Templates.md:449
msgid ""
"These are defined in the `layout` template method `menu_lists` and pulled "
"into\n"
"the `fulldoc` template through a similarly named method."
msgstr ""
"これらは `layout` テンプレートメソッドの中の `menu_lists` を定義される。\n"
"そして同様に名付けられたメソッドを通じて `fulldoc` テンプレートに置かれる。"

#: ../docs/Templates.md:452
msgid "To load an additional menu item:"
msgstr "追加のメニュー項目をロードするには次のようになる:"

#: ../docs/Templates.md:455
msgid ""
"  1. Create a `setup.rb` in the `layout` template directory and override the "
"methods\n"
"   `menu_lists`. The `type` informs the search field the name of the file.\n"
"    The `title` is the name that appears above the section when viewed in "
"frames.\n"
"    The `search_title` is the name that appears in the search field tab on "
"the page."
msgstr ""
"  1. `layout` テンプレートディレクトリの中で `setup.rb` を作成し `menu_lists` メソッドを上書きする。\n"
"   `type` はファイルの検索フィールド名通知する。\n"
"   `title` はフレームのなかで表示された時に上のセクションに登場する名前である。\n"
"   `search_title` はページの検索フィールドタブの中で登場する名前である。"

#: ../docs/Templates.md:461
msgid ""
"        /path/to/mytemplates/:\n"
"        |-- layout\n"
"        |   |-- html\n"
"        |   |   |-- setup.rb"
msgstr ""
"        /path/to/mytemplates/:\n"
"        |-- layout\n"
"        |   |-- html\n"
"        |   |   |-- setup.rb"

#: ../docs/Templates.md:466
msgid ""
"        def menu_lists\n"
"          # Load the existing menus\n"
"          super + [ { :type => 'feature', :title => 'Features', :"
"search_title => 'Feature List' } ]\n"
"        end"
msgstr ""
"        def menu_lists\n"
"          # 既存のメニューをロードする\n"
"          super + [ { :type => 'feature', :title => 'Features', :search_title => 'Feature List' } ]\n"
"        end"

#: ../docs/Templates.md:471
msgid ""
"  2. Create a `setup.rb` in the `fulldoc` template directory and create a "
"method\n"
"     to generate a menu for the specified `type`.\n"
"     The method `generate_assets` will look for a function with a signature "
"prefixed\n"
"     with `generate`, the type value specified, and the suffix `list`. "
"Within that\n"
"     method you can configure and load the specific objects you wish to "
"display."
msgstr ""
"  2. `fulldoc` のテンプレートディレクトリの中で `setup.rb` を作成し、\n"
"     指定された `type` 用にメニューを生成するためのメソッドを作成する\n"
"     `generate_assets` メソッドは、 `generate` で始まり,間に固有の値,末尾が `list` のシグネチャを探す。\n"
"     メソッドの中をあなたが構成でき、表示するためにあなたが望む特定のオブジェクトをロードする。"

#: ../docs/Templates.md:482
msgid "         def generate_feature_list"
msgstr "         def generate_feature_list"

#: ../docs/Templates.md:484
msgid ""
"           # load all the features from the Registry\n"
"           @items = Registry.all(:feature)\n"
"           @list_title = \"Feature List\"\n"
"           @list_type = \"feature\""
msgstr ""
"           # レジストリーから全ての機能をロードす\n"
"           @items = Registry.all(:feature)\n"
"           @list_title = \"Feature List\"\n"
"           @list_type = \"feature\""

#: ../docs/Templates.md:489
msgid ""
"           # optional: the specified stylesheet class\n"
"           # when not specified it will default to the value of @list_type\n"
"           @list_class = \"class\""
msgstr ""
"           # optional: the specified stylesheet class\n"
"           # when not specified it will default to the value of @list_type\n"
"           @list_class = \"class\""

#: ../docs/Templates.md:493
msgid ""
"           # Generate the full list html file with named feature_list.html\n"
"           # @note this file must be match the name of the type\n"
"           asset('feature_list.html', erb(:full_list))\n"
"         end"
msgstr ""
"           # feature_list.htmlの名前と共に完全なHTMLファイルのリストを作成する\n"
"           # @note this file must be match the name of the type\n"
"           asset('feature_list.html', erb(:full_list))\n"
"         end"

# title
#: ../docs/WhatsNew.md:1
msgid "What's New?"
msgstr "What's New?"

#: ../docs/WhatsNew.md:3
msgid "# What's New in 0.8.x?"
msgstr "# What's New in 0.8.x?"

#: ../docs/WhatsNew.md:5
msgid ""
"1. **Directives (new behavioural tag syntax)** (0.8.0)\n"
"2. **Added `--embed-mixin(s)` to embed mixins into class docs** (0.8.0)\n"
"3. **Internationalization (I18n) support for translating docs** (0.8.0)\n"
"4. **New C parser / handlers architecture** (0.8.0)\n"
"5. **YARD will now warn if `@param` name not in method params** (0.8.0)\n"
"6. **Added support for `module_function` calls in Ruby code** (0.8.0)\n"
"7. **Greatly improved tag documentation using custom template** (0.8.0)\n"
"8. **Tags can now contain '.' for namespacing** (0.8.0)\n"
"9. **Added \"frames\" links for non-framed pages for better nav** (0.8.0)\n"
"10. **Added Gemfile support to YARD server for local gem sets** (0.8.0)\n"
"11. **Server now displays README on index route like static docs** (0.8.0)\n"
"12. **Added line numbers to `yard stats --list-undoc --compact`** (0.8.0)\n"
"13. **Single object db now default (multi-object db unsupported)** (0.8.0)\n"
"14. **Added `--api` tag to generate documentation for API sets** (0.8.1)"
msgstr ""
"1. **ディレクティブ (タグ構文の新しい行動)** (0.8.0)\n"
"2. **クラスのドキュメントの中にmixinを埋め込むのに `--embed-mixin(s)` が追加された** (0.8.0)\n"
"3. **翻訳ドキュメント用の国際化 (I18n) サポート** (0.8.0)\n"
"4. **新しい C パーサー / ハンドラー アーキテクチャ** (0.8.0)\n"
"5. **YARDはメソッドのパラメータの中に`@param`名が無い場合、警告を出すようになった。\n"
"6. **`module_function` がRubyのコードを呼び出すサポートが追加された** (0.8.0)\n"
"7. **カスタムテンプレートによって大きくタグドキュメントが修正された** (0.8.0)\n"
"8. **タグがネームスペース用の '.' を含むようになった** (0.8.0)\n"
"9. **より良いナビをするのにフレームでないページ用に\"フレーム\"のリンクが追加された** (0.8.0)\n"
"10. **ローカルのgemのグループ用にYARDサーバーにGemfileのサポートが追加された** (0.8.0)\n"
"11. **サーバーは静的なドキュメントのようにルートのインデックス上のREADMEを表示するようになった** (0.8.0)\n"
"12. **`yard stats --list-undoc --compact`に行数が追加された** (0.8.0)\n"
"13. **単一のオブジェクトdbがデフォルトになった (マルチオブジェクトdbは未サポート)** (0.8.0)\n"
"14. **API用のグループのドキュメントを生成するのに `--api` タグが追加された** (0.8.1)"

#: ../docs/WhatsNew.md:20
msgid "## Directives (new behavioural tag syntax) (0.8.0)"
msgstr "## ディレクティブ (タグ構文の新しい行動) (0.8.0)"

#: ../docs/WhatsNew.md:22
msgid ""
"
    \n"
"  The tags {tag:!macro}, {tag:!method}, {tag:!attribute}, {tag:!group},\n"
"  {tag:!endgroup}, {tag:!scope} and {tag:!visibility} have been changed\n"
"  from meta-data tags to directives. This means they should now be called\n"
"  with the \"@!\" prefix instead of \"@\". Note however that for \n"
"  backward compatibility, the old \"@macro\", \"@method\", etc.,\n"
"  syntax for all of these tags will still work and is supported.\n"
"
    "
msgstr ""
"
    \n"
"  The tags {tag:!macro}, {tag:!method}, {tag:!attribute}, {tag:!group},\n"
"  {tag:!endgroup}, {tag:!scope} and {tag:!visibility} have been changed\n"
"  from meta-data tags to directives. This means they should now be called\n"
"  with the \"@!\" prefix instead of \"@\". Note however that for \n"
"  backward compatibility, the old \"@macro\", \"@method\", etc.,\n"
"  syntax for all of these tags will still work and is supported.\n"
"
    "

#: ../docs/WhatsNew.md:31
msgid ""
"
    \n"
"  Some backwards incompatible changes were made to {tag:!"
"macro} syntax.\n"
"  Please read this section carefully if you are using this tag.\n"
"
    "
msgstr ""
"
    \n"
"  Some backwards incompatible changes were made to {tag:!macro} syntax.\n"
"  Please read this section carefully if you are using this tag.\n"
"
    "

#: ../docs/WhatsNew.md:36
msgid ""
"YARD 0.8.0 adds a new tag syntax called \"directives\" using the `@!`\n"
"prefix. These directive tags can be used to modify parser state while\n"
"processing objects, or even create new objects on the fly. A plugin\n"
"API is available similar to tags, and directives should be registered\n"
"in the {YARD::Tags::Library} class using {YARD::Tags::Library."
"define_directive}."
msgstr ""
"YARD 0.8.0で追加された新しいタグ構文は\n"
"`@!` プレフィックス(接頭辞)によって\"directives(ディレクティブ)\"を呼び出す。\n"
"これらのディレクティブタグは、\n"
"オブジェクトを処理している間やオンザフライで新しくオブジェクトを作成する時でさえ、\n"
"パーサーの状態を変更するのに利用できる。\n"
"プラグインAPIはタグ同様に可能で、\n"
"ディレクティブは {YARD::Tags::Library.define_directive} によって\n"
"{YARD::Tags::Library} クラスのなかに登録される。"

#: ../docs/WhatsNew.md:42
msgid ""
"To use a directive, simply call it the same way as any tag. Tag syntax\n"
"is documented in {file:docs/Tags.md}."
msgstr ""
"ディレクティブを使うには、単純にタグなどと同じ方法で呼び出す。\n"
"タグ構文は {file:docs/Tags.md} で記述される。"

#: ../docs/WhatsNew.md:45
msgid "### Notable features of directives"
msgstr "### 著名なディレクティブの機能"

#: ../docs/WhatsNew.md:47
msgid "#### Directives do not need to be attached to object docstrings"
msgstr "#### ディレクティブはオブジェクトのdocstringに追加するのに必要ない"

#: ../docs/WhatsNew.md:49
msgid ""
"Unlike meta-data tags which apply to created objects, directives\n"
"do not need to be attached to an object in order to be used. This\n"
"means you can have free-standing comments with directives, such as:"
msgstr ""
"メタデータタグとは違って作成されたオブジェクトに追加され、\n"
"ディレクティブは利用される順番で追加される必要はない。\n"
"これは次のようなディレクティブを用い自由な位置にコメントできる事を意味する:"

#: ../docs/WhatsNew.md:53
msgid ""
"    # @macro mymacro\n"
"    #   A new macro, not attached to any docstring"
msgstr ""
"    # @macro mymacro\n"
"    #   A new macro, not attached to any docstring"

#: ../docs/WhatsNew.md:56
msgid "    # ...other Ruby code here..."
msgstr "    # ...other Ruby code here..."

#: ../docs/WhatsNew.md:58
msgid ""
"    # Using the macro:\n"
"    # @macro mymacro\n"
"    def mymethod; end"
msgstr ""
"    # 上のマクロを呼び出す:\n"
"    # @macro mymacro\n"
"    def mymethod; end"

#: ../docs/WhatsNew.md:62
msgid ""
"You can do the same to define methods and attributes, as discussed\n"
"below."
msgstr ""
"下の項で議論されるように\n"
"あなたはメソッドと属性を定義するのを同じようにできる。"

#: ../docs/WhatsNew.md:65
msgid "#### `@!method` and `@!attribute` directives improved"
msgstr "#### 改良された `@!method` と `@!attribute` ディレクティブ"

#: ../docs/WhatsNew.md:67
msgid ""
"The method and attribute directives can now be used to create multiple\n"
"objects in a single docstring. Previously a `@method` or `@attribute`\n"
"tag would only create one method per docstring. In 0.8.0, you could\n"
"attach multiple methods to the same block of Ruby source, such as:"
msgstr ""
"メソッドと属性(attribute)のディレクティブは\n"
"単一のdocstringで複数のオブジェクトを作成するのに利用できるようになった。\n"
"以前は `@method` や `@attribute` タグは\n"
"メソッド一つで個々のdocstringだけ作成していた。\n"
"0.8.0ではRubyのソースの同じブロックに複数のメソッドを追加できる。\n"
"次のようになる:"

#: ../docs/WhatsNew.md:72
msgid ""
"    # @!method foo(a, b, c)\n"
"    # @!method bar(x, y, z)\n"
"    # Docstring for code\n"
"    some_ruby_source"
msgstr ""
"    # @!method foo(a, b, c)\n"
"    # @!method bar(x, y, z)\n"
"    # コード用のdocstring\n"
"    some_ruby_source"

#: ../docs/WhatsNew.md:77
msgid ""
"The above creates #foo and #bar and the source listing for both will\n"
"be `some_ruby_source` with \"Docstring for code\" as the docstring."
msgstr ""
"上の例は\n"
"両方がdocstringとして\"コード用のdocstring\"と一緒に\n"
"`some_ruby_source` の説明になるように、\n"
"#fooメソッドと#barメソッドとソースのリストを作成する。"

#: ../docs/WhatsNew.md:80
msgid ""
"The attribute directive can take advantage of this functionality as well.\n"
"Note that these directives also do not need to be attached to a line of\n"
"code to be recognized; they can be in free-standing comments if the\n"
"methods are defined dynamically and not associated with any code."
msgstr ""
"属性のディレクティブはさらにこの機能の平均を取得できる。\n"
"次の事に留意する。\n"
"これらのディレクティブは認識されるのにコードの行に追加される必要もない。\n"
"つまり、これはメソッドが動的に定義される場合\n"
"自由な場所にコメントでき、任意のコードと一緒に関連づけられない。"

#: ../docs/WhatsNew.md:85
msgid "#### New `@!parse` directive to parse Ruby code"
msgstr "#### Rubyのコードを解析する為の新しい `@!parse` ディレクティブ"

#: ../docs/WhatsNew.md:87
msgid ""
"A new {tag:!parse} directive was added that allows a developer to have\n"
"YARD parse code that might not necessarily be parsable in its original\n"
"form. This is useful when using `instance_eval` and other dynamic\n"
"meta-programming techniques to define methods or perform functionality.\n"
"For instance, a common case of the \"self.included\" callback in module\n"
"to extend a module on a class might be in the form:"
msgstr ""
"新しい {tag:!parse} ディレクティブは\n"
"YARDが元の形式で解析する必要はないコードの解析を開発者に\n"
"許可するのに追加された。\n"
"これはメソッドを定義する時や機能を実行する時に\n"
" `instance_eval` と他の動的なメタプログラミングのテクニックを使う時に便利である。\n"
"例えば、次の形式でクラス上でモジュールを拡張するのに\n"
"モジュールの中の\"self.included\"コールバックの一般的なケース:"

#: ../docs/WhatsNew.md:94
msgid ""
"    def self.included(mod)\n"
"      mod.extend(self)\n"
"    end"
msgstr ""
"    def self.included(mod)\n"
"      mod.extend(self)\n"
"    end"

#: ../docs/WhatsNew.md:98
msgid ""
"Unfortunately, this does not get picked up by YARD, but on the original\n"
"class, we can add:"
msgstr ""
"あいにく、これはYARDによって取得できないが、\n"
"元のクラス上で次のように追加できる:"

#: ../docs/WhatsNew.md:101
msgid ""
"    class MyClass\n"
"      # @!parse extend TheDynamicModule\n"
"      include TheDynamicModule\n"
"    end"
msgstr ""
"    class MyClass\n"
"      # @!parse extend TheDynamicModule\n"
"      include TheDynamicModule\n"
"    end"

#: ../docs/WhatsNew.md:106
msgid ""
"YARD will then parse the code `extend TheDynamicModule` as if\n"
"it were in the source file."
msgstr ""
"それがソースファイルの中だった場合など\n"
"YARDが `extend TheDynamicModule` のコードを解析する時"

#: ../docs/WhatsNew.md:109
msgid ""
"You can also use this technique to register regular methods as\n"
"attributes, if you did not define them with `attr_*` methods:"
msgstr ""
"これらの `attr_*` メソッドを用いて定義しなかった場合、\n"
"あなたは属性として標準のメソッドを登録するのにこのテクニックを使う事ができる。"

#: ../docs/WhatsNew.md:112
msgid ""
"    def foo; @foo end\n"
"    def foo=(v) @foo = v end"
msgstr ""
"    def foo; @foo end\n"
"    def foo=(v) @foo = v end"

#: ../docs/WhatsNew.md:115
msgid ""
"    # Register them as methods:\n"
"    # @!parse attr_accessor :foo"
msgstr ""
"    # メソッドとしてそれらを登録する\n"
"    # @!parse attr_accessor :foo"

#: ../docs/WhatsNew.md:118
msgid "### Backward incompatible changes to `@!macro` directive"
msgstr "### 後方互換性のない `@!macro` ディレクティブに変更する"

#: ../docs/WhatsNew.md:120
msgid ""
"Unfortunately, in order to create the new directives architecture,\n"
"some previously supported syntax in `@macro` tags are no longer supported.\n"
"Specifically, macros can no longer expand text on an entire docstring.\n"
"Instead, macros only expand the data that is indented inside of the tag\n"
"text."
msgstr ""
"あいにく、新しいディレクティブアーキテクチャを作成する為の順番、\n"
"`@macro` タグの中でいくつか前にサポートされた構文は、もうサポートされない。\n"
"すなわち、マクロは全てのdocstring上のテキストを展開することはできない。\n"
"代わりに、マクロはタグのテキストの内部のインデントされたデータだけ展開する。"

#: ../docs/WhatsNew.md:126
msgid "This syntax is **no longer supported**:"
msgstr "This syntax is **no longer supported**:"

#: ../docs/WhatsNew.md:128
msgid ""
"    # @macro mymacro\n"
"    # Expanding text $1 $2 $3\n"
"    property :a, :b, :c"
msgstr ""
"    # @macro mymacro\n"
"    # Expanding text $1 $2 $3\n"
"    property :a, :b, :c"

#: ../docs/WhatsNew.md:132
msgid ""
"In 0.7.0 to 0.7.5, the above would have created a method with the docstring\n"
"\"Expanding text a b c\". This will not work in 0.8.0. Instead, you must\n"
"indent all the macro expansion data so that it is part of the `@macro`\n"
"tag as follows:"
msgstr ""
"0.7.0 ~ 0.7.5で、\n"
"上はの例はdocstring \"Expanding text a b c\"と一緒に作成されたメソッドを持つ。\n"
"これは、0.8.0では動かない。\n"
"代わりに、あなたは全てのマクロ展開のデータをインデントしなければならない。\n"
"つまり `@macro` タグの一部を次のようにする:"

#: ../docs/WhatsNew.md:137
msgid ""
"    # @!macro mymacro\n"
"    #   Expanding text $1 $2 $3\n"
"    property :a, :b, :c"
msgstr ""
"    # @!macro mymacro\n"
"    #   Expanding text $1 $2 $3\n"
"    property :a, :b, :c"

#: ../docs/WhatsNew.md:141
msgid ""
"Note that we also use the recommended `@!macro` syntax, though `@macro`\n"
"is still supported."
msgstr ""
"次の事に留意する。\n"
"我々は推奨された `@!macro` 構文を使うけれども、\n"
"`@macro` はまだサポートされている。"

#: ../docs/WhatsNew.md:144
msgid "## Added `--embed-mixin(s)` to embed mixins into class docs (0.8.0)"
msgstr "## クラスのドキュメントにmixinを埋め込むのに `--embed-mixin(s)` が追加された (0.8.0)"

#: ../docs/WhatsNew.md:146
msgid ""
"Methods from mixins can now be embedded directly into the documentation\n"
"output for a class by using `--embed-mixin ModuleName`, or `--embed-mixins`\n"
"for all mixins. This enables a documentation writer to refactor methods\n"
"into modules without worrying about them showing up in separate files\n"
"in generated documentation. When mixin methods are embedded, they\n"
"show up in both the original module page and the pages of the classes\n"
"they are mixed into. A note is added to the method signature telling the\n"
"user where the method comes from."
msgstr ""
"mixinからのメソッドは\n"
"全てのmixin用に `--embed-mixin ModuleName` や `--embed-mixins` 用の\n"
"ドキュメント出力の中へ直接埋め込まれるようになった。\n"
"これは生成されたドキュメントの中の分割されたファイルのなかの\n"
"その時の一覧について警告無しでモジュールの中の\n"
"メソッドをリファクタリングする為にドキュメントを書ける。\n"
"mixinメソッドが埋め込まれた時、\n"
"これは元のモジュールのページとこれらの混じったクラスのページの両方を一覧する。\n"
"noteはメソッドのシグネチャがメソッドがどこからくるかユーザーに知らせるのに追加された。"

#: ../docs/WhatsNew.md:155
msgid ""
"The `--embed-mixin` command-line option can also take wildcard values\n"
"in order to match specific namespaces. For instance, you can embed\n"
"only mixins inside of a \"Foo::Bar\" namespace by doing:"
msgstr ""
"`--embed-mixin` コマンドラインオプションは、\n"
"指定のネームスペースにマッチするのにワイルドカードの値も取得できる。\n"
"例えば、次の様にする事によって\n"
"\"Foo::Bar\"ネームスペースの内部にmixinだけ埋め込むことができる。"

#: ../docs/WhatsNew.md:159
msgid ""
"    !!!sh\n"
"    $ yard doc --embed-mixin \"Foo::Bar::*\""
msgstr ""
"    !!!sh\n"
"    $ yard doc --embed-mixin \"Foo::Bar::*\""

#: ../docs/WhatsNew.md:162
msgid "## Internationalization (I18n) support for translating docs"
msgstr "## 翻訳ドキュメント用の国際化(I18n)サポート"

#: ../docs/WhatsNew.md:164
msgid ""
"YARD now ships with the beginnings of internationalization support\n"
"for translating documentation into multiple languages. The\n"
"`yard i18n` command now allows you to generate \".pot\" and ultimately\n"
"\".po\" files for translation with [gettext](http://www.gnu.org/software/"
"gettext)."
msgstr ""
"YARDは複数の言語に翻訳したドキュメント用に国際化サポートを送りだすことになった。\n"
"`yard i18n` コマンドは\n"
"あなたが[gettext](http://www.gnu.org/software/gettext)を用いた翻訳用の\n"
"\".pot\"と最後に\".po\"ファイルを生成するのを許可するようになった。"

#: ../docs/WhatsNew.md:169
msgid ""
"Note that this tool is a small step in the larger transition for\n"
"proper I18n support in YARD. We still have to add proper gettext\n"
"support to our templates for proper generation in multiple languages,\n"
"but this tool allows you to get started in translating your\n"
"documents. Improved I18n support will come throughout the 0.8.x series."
msgstr ""
"次の事に留意する。\n"
"このツールはYARDの正当なI18nサポートの小さな一歩である。\n"
"我々はまだ複数の言語の適切な生成の為に、\n"
"例のテンプレートに適切なgettextサポートを追加する仕事が残っている。\n"
"だがこのツールはあなたが翻訳ドキュメントを始めるのを受け入れる。\n"
"改良されたI18nサポートは0.8.xシリーズに至る中で登場するだろう。"

#: ../docs/WhatsNew.md:175
msgid "## New C parser / handlers architecture (0.8.0)"
msgstr "## 新しい Cパーサー / ハンドラー構造 (0.8.0)"

#: ../docs/WhatsNew.md:177
msgid ""
"The C parser was completely rewritten to take advantage of YARD's\n"
"parser and handler architecture. This means more YARD will be more robust\n"
"when parsing failures occur, tags and directives will now work consistently\n"
"across Ruby and CRuby files ({tag:!group} will now work, for instance),\n"
"and developers can now write custom handlers that target CRuby source files."
msgstr ""
"YARDパーサーの平均とハンドラーアーキテクチャを取得するのに\n"
"C パーサーは完全に書き直された。\n"
"これはYARDが解析異常が起きた時にさらに堅牢になる事を意味し\n"
"タグとディレクティブはRubyとCRubyのファイル(例えば {tag:!group} が動くようになった)\n"
"全域で堅実に動く様になった。\n"
"そして、開発者はCRubyのソースファイルを目的にするカスタムハンドラーを書ける様になった。\n"

#: ../docs/WhatsNew.md:183
msgid "## YARD will now warn if `@param` name not in method params (0.8.0)"
msgstr "## YARDはメソッドパラメーターの中に`@param`名がない場合、警告を出すようになった(0.8.0)"

#: ../docs/WhatsNew.md:185
msgid ""
"YARD will now give you a warning if you use a `@param` tag in your\n"
"source but give an invalid parameter name. This should catch a lot of\n"
"common documentation errors and help keep your documentation consistent."
msgstr ""
"YARDはあなたのソースの中の `@param` タグを使う場合、あなたが警告を出せるようになった。\n"
"しかし有効なパラメータ名を与える。\n"
"これは沢山の一般的なドキュメントエラーをキャッチし、\n"
"あなたの一貫したドキュメントの保守を助ける。"

#: ../docs/WhatsNew.md:189
msgid "## Added support for `module_function` calls in Ruby code (0.8.0)"
msgstr "## `module_function` がRubyのコードの中で呼び出されるサポートが追加された (0.8.0)"

#: ../docs/WhatsNew.md:191
msgid ""
"The `module_function` command in Ruby is now supported in Ruby files.\n"
"It defines two separate methods, one class and one instance method,\n"
"both having the exact same docstring, and marks the instance method\n"
"as private."
msgstr ""
"Rubyの `module_function` コマンドは\n"
"Rubyのファイルでサポートされるようになった。\n"
"それは\"区切られたメソッド\"と\n"
"\"一つのクラスと一つのインスタンスメソッド\"二つを定義し、\n"
"正確な同じdocstring両方、\n"
"privateとしてインスタンスメソッドをマークする。"

#: ../docs/WhatsNew.md:196
msgid "## Greatly improved tag documentation using custom template (0.8.0)"
msgstr "## カスタムテンプレートによって大きく改良されたタグのドキュメント (0.8.0)"

#: ../docs/WhatsNew.md:198
msgid ""
"We have completely revamped the {docs/Tags.md} to include documentation\n"
"for each meta-data tag and directive with at least one useful example\n"
"for each one. This was done using template customization and extension\n"
"available within YARD."
msgstr ""
"我々は個々のメタデータタグとディレクティブ用の\n"
"ドキュメントを含めるのに {docs/Tags.md} を\n"
"少なくとも各々一つ便利な例を用い完全に刷新しました。\n"
"これはYARDの中でテンプレートのカスタマイズと拡張が可能になる事によって\n"
"行なわれた。"

#: ../docs/WhatsNew.md:203
msgid "## Tags can now contain '.' for namespacing (0.8.0)"
msgstr "## タグはネームスペース用の '.' を含める事できるようになった (0.8.0)"

#: ../docs/WhatsNew.md:205
msgid ""
"Prior to 0.8.0, tags could only contain alphanumeric characters and\n"
"underscore. YARD now allows the '.' character in tag names, and it\n"
"is now recommended for namespacing project-specific custom tags.\n"
"YARD has its own set of custom tags that are namespaced in this\n"
"way (using the \"yard.tagname\" namespace). The namespace recommendation\n"
"is to use \"projectname.tagname\", or \"projectname.component.tagname\"."
msgstr ""
"0.8.0以前のタグはアルファベット文字列とアンダースコアだけ含める事ができた。\n"
"YARDはタグ名で '.' の文字を受け入れるようになり、\n"
"プロジェクトの指定のカスタムタグのネームスペース用に推奨する。\n"
"YARDは自身のカスタム\n"
"この方法でネームスペース(名前付け)されるタグのグループを持つ。\n"
"おすすめのネームスペースは\n"
"\"projectname.tagname\" や \"projectname.component.tagname\"を使う"

#: ../docs/WhatsNew.md:212
msgid "## Added \"frames\" links for non-framed pages for better nav (0.8.0)"
msgstr "## ナビの改良の為フレームのないページ用にフレームのリンクが追加された (0.8.0)"

#: ../docs/WhatsNew.md:214
msgid ""
"Frames navigation has always had a \"(no frames)\" link to get rid\n"
"of the frameset. YARD 0.8.0 introduces a \"(frames)\" link on non-framed\n"
"pages to reverse this, allowing you to navigate between framed and\n"
"frameless pages seamlessly."
msgstr ""
"フレームのナビゲーションは\n"
"フレームセットを取り除くのを取得するのに常に\"(no frames)\"のリンクを持っていた。\n"
"YARD 0.8.0はこれを置き換えるのにフレームの無いページで\n"
"\"(frames)\"のリンクを導入する\n"
"フレームとフレーム無しのページ間を\n"
"シームレスにナビゲートするのに許可される。"

#: ../docs/WhatsNew.md:219
msgid "## Added Gemfile support to YARD server for local gem sets (0.8.0)"
msgstr "## ローカルgemのグループ用にYARDサーバーにGemfileのサポートが追加された (0.8.0)"

#: ../docs/WhatsNew.md:221
msgid ""
"The `yard server` command now supports `--gemfile` to serve gems\n"
"from a Gemfile.lock, instead of all system-wide gems."
msgstr ""
"全てのシステム側のgemの代わりにGemfile.lockからgemを提供するのに、\n"
"`yard server` コマンドは、`--gemfile` をサポートするようになった。"

#: ../docs/WhatsNew.md:224
msgid "## Server now displays README on index route like static docs (0.8.0)"
msgstr "## サーバーは静的なドキュメントのようなルートのインデックス上でREADMEを表示する(0.8.0)"

#: ../docs/WhatsNew.md:226
msgid ""
"The `yard server` command will now behave like static docs regarding\n"
"the index action for a project, listing the README file if present\n"
"before displaying the alphabetic index. Note that the route for\n"
"the alphabetic index page has now moved to the explicit '/index' action."
msgstr ""
"`yard server` コマンドは\n"
"プロジェクト用のインデックスの動作について\n"
"静的なドキュメントのような挙動になり、\n"
"アルファベットのインデックスを表示する前に与える場合、\n"
"READMEファイルを記述する。\n"
"次の事に留意する。\n"
"アルファベット順のインデックスページ用のルートは\n"
"明示的な '/index' の動作に移るようになった。"

#: ../docs/WhatsNew.md:231
msgid "## Added line numbers to `yard stats --list-undoc --compact` (0.8.0)"
msgstr "## `yard stats --list-undoc --compact` に行数が追加された (0.8.0)"

#: ../docs/WhatsNew.md:233
msgid ""
"Line numbers are now listed in the compact listing of undocumented objects\n"
"so that they can be more easily located in the files."
msgstr ""
"行数はコンパクトなアンドキュメントなオブジェクトのリストで記述されるようになった。\n"
"なのでこれらはさらに簡単にファイルの中を示す事ができる。"

#: ../docs/WhatsNew.md:236
msgid "## Single object db now default (multi-object db unsupported) (0.8.0)"
msgstr ""

#: ../docs/WhatsNew.md:238
msgid ""
"YARD previously would split the .yardoc db into multiple marshal files\n"
"for load-time performance reasons if it grew past a specific number of\n"
"objects. This check is now disabled, and YARD will never automatically\n"
"switch to a multi-object DB. YARD will now always use the single object\n"
"db unless explicitly set with `--no-single-db`. If YARD is taking a\n"
"long time to load your .yardoc database, you can try using this\n"
"option to split your database into multiple files, but note that this\n"
"can cause problems with certain codebases (specifically, if you\n"
"have class methods using the same name as a module/class)."
msgstr ""

#: ../docs/WhatsNew.md:248
msgid "## Added `--api` tag to generate documentation for API sets (0.8.1)"
msgstr ""

#: ../docs/WhatsNew.md:250
msgid ""
"You can now use `yardoc --api APINAME` to generate documentation only\n"
"for objects with the `@api APINAME` tag (or any parent namespace objects,\n"
"since this tag is transitive). Multiple `--api` switches may be used to\n"
"generate documentation for multiple APIs together. The following generates\n"
"documentation for both the \"public\" and \"developer\" APIs, also "
"including\n"
"any objects with undefined API (via `--no-api`):"
msgstr ""

#: ../docs/WhatsNew.md:257
msgid "    $ yard doc --api public --api developer --no-api"
msgstr "    $ yard doc --api public --api developer --no-api"

#: ../docs/WhatsNew.md:259
msgid ""
"Note that if you use `--api`, you must ensure that you also add `@api`\n"
"tags to your namespace objects (modules and classes), not just your "
"methods.\n"
"If you do not want to do this, you can also include all objects with *no*\n"
"`@api` tag by using `--no-api` as shown above."
msgstr ""

#: ../docs/WhatsNew.md:264
msgid ""
"Remember that applying an `@api` tag to a class or module will apply it\n"
"to all children that do not have this tag already defined, so you can\n"
"declare an entire class public by applying it to the class itself. Note\n"
"also that these tags can be overridden by child elements if the tag is\n"
"re-applied to the individual object."
msgstr ""

#: ../docs/WhatsNew.md:270
msgid ""
"This feature is a simplified version of the more powerful `--query`\n"
"switch. The query to display the same API documentation as the\n"
"above example would be:"
msgstr ""

#: ../docs/WhatsNew.md:274
msgid "    $ yard doc --query '!@api || @api.text =~ /^(public|private)$/'"
msgstr "    $ yard doc --query '!@api || @api.text =~ /^(public|private)$/'"

#: ../docs/WhatsNew.md:276
msgid ""
"But note that `--query` does not work when YARD is in \"safe mode\"\n"
"due to security concerns, whereas `--api` works in either mode.\n"
"This enables `--api` to function on remote documentation sites like\n"
"[rubydoc.info](http://rubydoc.info)."
msgstr ""

#: ../docs/WhatsNew.md:282
msgid "# What's New in 0.7.x?"
msgstr "# What's New in 0.7.x?"

#: ../docs/WhatsNew.md:284
msgid ""
"1. **Macro support and detection of DSL methods** (0.7.0)\n"
"2. **Inherited attributes now show in HTML output** (0.7.0)\n"
"3. **The 'app' directory is now parsed by default** (0.7.0)\n"
"4. **Added support for metadata (@title, @markup) in extra files/readmes** "
"(0.7.0)\n"
"5. **Added `yard list` command (alias for `yardoc --list`)** (0.7.0)\n"
"6. **Added Git support in `yard diff`** (0.7.0)\n"
"7. **Added `{include:file:FILENAME}` syntax** (0.7.0)\n"
"8. **Added `{render:OBJECT}` syntax to embed object docs in extra files** "
"(0.7.0)\n"
"9. **Added improved templates API for custom CSS/JS/menus** (0.7.0)\n"
"10. **Added Ruby markup type (`-m ruby`)** (0.7.0)\n"
"11. **Added state tracking variables to Parser/Handler architecture** "
"(0.7.0)\n"
"12. **Added before/after callbacks to SourceParser** (0.7.0)\n"
"13. **Can now use `--yardopts FILE` to specify a custom yardopts file** "
"(0.7.0)\n"
"14. **Added new `-t guide` template for guide based docs** (0.7.0)\n"
"15. **Github Flavoured Markdown now works out-of-box** (0.7.4)\n"
"16. **Added `-m textile_strict` and `-m pre` markup types** (0.7.4)\n"
"17. **Reorganized markup types 'text' and 'none'** (0.7.4)\n"
"18. **Add support for `rb_define_alias`** (0.7.4)"
msgstr ""
"1. **マクロのサポートとDSLメソッドの検知** (0.7.0)\n"
"2. **継承された属性はすぐHTML出力で一覧できる** (0.7.0)\n"
"3. **'app'ディレクトリは、すぐデフォルトで解析される** (0.7.0)\n"
"4. **追加のファイル/readmesでメタデータ用(@title,@markup)のサポートが追加され"
"た** (0.7.0)\n"
"5. **`yard list`コマンドが追加された(`yardoc --list`用のエイリアス)** "
"(0.7.0)\n"
"6. **`yard diff`でGitサポートが追加された** (0.7.0)\n"
"7. **`{include:file:FILENAME}`構文** (0.7.0)\n"
"8. **追加のファイルでオブジェクトのdocsを組み込む為の`{render:OBJECT}`構文が"
"追加された** (0.7.0)\n"
"9. **カスタムCSS/JS/メニュー用の改良されたテンプレートAPIが追加された** "
"(0.7.0)\n"
"10. **Rubyのマークアップの型(`-m ruby`)が追加された** (0.7.0)\n"
"11. **パーサー/ハンドラーのアーキテクチャにトラッキングの状態変数が追加された"
"** (0.7.0)\n"
"12. **SourceParserにbefore/afterのコールバックが追加された** (0.7.0)\n"
"13. **カスタムyardoptsファイルを指定するのに、`--yardopts FILE`ですぐに、使う"
"事が出来る** (0.7.0)\n"
"14. **基底となるdocstringをガイドするのに、`-t guide`テンプレートを新しく追加"
"する** (0.7.0)<\n"
"15. **Github風のMarkdownが常識破りの仕事をするようになった** (0.7.4)\n"
"16. **`-m textile_strict`と`-m pre`マークアップの型が追加された** (0.7.4)\n"
"17. **'text'と'none'のマークアップ型が再編成された** (0.7.4)\n"
"18. **`rb_define_alias`用のサポートが追加された** (0.7.4)"

#: ../docs/WhatsNew.md:303
msgid "## Macro support and detection of DSL methods (0.7.0)"
msgstr "## マクロのサポートとDSLメソッドの検知 (0.7.0)"

#: ../docs/WhatsNew.md:305
msgid ""
"YARD will now automatically detect class level method calls, similar to the\n"
"way it knows what an `attr_accessor` is. By simply adding documentation to\n"
"your class level declarations, YARD can automatically detect them as "
"methods\n"
"or attributes in your class. Consider DataMapper's \"property\" declaration:"
msgstr ""
"YARDは自動でクラスレベルメソッドの呼び出しを検知するようになった。\n"
"'attr_accessor'何なのか知るのと似ている。\n"
"簡単にあなたのクラスレベル宣言にドキュメントを追加する。\n"
"DataMapperの\"property\"宣言を考慮する。"

#: ../docs/WhatsNew.md:310
msgid ""
"    class Post\n"
"      # @attribute\n"
"      # @return [String] the title of the post\n"
"      property :title, String\n"
"    end"
msgstr ""
"    class Post\n"
"      # @attribute\n"
"      # @return [String] the title of the post\n"
"      property :title, String\n"
"    end"

#: ../docs/WhatsNew.md:316
msgid ""
"The above declaration would be created as the `Post#title`. The optional\n"
"`@attribute` tag tells YARD that the property is an \"attribute\", and not "
"just\n"
"a regular method."
msgstr ""
"上の宣言は、`Post#title`メソッドとして作成されるだろう。\n"
"任意の`@attribute`タグがYARDの\"property\"に伝えるのは、\"attribute\"であ"
"り、\n"
"それは正規のメソッドではない。"

#: ../docs/WhatsNew.md:320
msgid ""
"In addition to basic DSL method detection, YARD also supports macros to "
"create\n"
"docstrings that can be copies to other objects; these macros can also be\n"
"\"attached\" to class level methods to create implicit documentation for "
"macros."
msgstr ""
"更に基本のDSLメソッド検知に加えて、\n"
"YARDは他のオブジェクトにコピーできるdocstringを作成するマクロもサポートする。\n"
"これらのマクロはマクロ用に暗黙のドキュメントを作成するために\n"
"クラスレベルメソッドに\"追加\"(attached)もできる。"

#: ../docs/WhatsNew.md:324
msgid ""
"Macros and DSL method detection are discussed in much more detail in the\n"
"{file:docs/GettingStarted.md}, so you should read about them there if "
"you're\n"
"interested in this feature."
msgstr ""
"マクロとDSLメソッド宣言の詳細は{file:docs/GettingStarted.md}で説明されるので、\n"
"あなたがこの機能に興味がある場合、そこで読む事ができる。"

#: ../docs/WhatsNew.md:328
msgid "## Inherited attributes now show in HTML output (0.7.0)"
msgstr "## 継承された属性をHTML出力ですぐに調べられるようになった (0.7.0)"

#: ../docs/WhatsNew.md:330
msgid ""
"Inherited attributes will now show up in HTML documentation using the "
"default\n"
"template in the same manner that inherited methods do."
msgstr ""
"継承された属性は、\n"
"継承されたメソッドと同じ形式で\n"
"デフォルトのテンプレートによって\n"
"HTMLドキュメントですぐに現れるだろう。"

#: ../docs/WhatsNew.md:333
msgid "## The 'app' directory is now parsed by default (0.7.0)"
msgstr "## デフォルトで'app'ディレクトリはすぐに解析される (0.7.0)"

#: ../docs/WhatsNew.md:335
msgid ""
"YARD tries to follow the \"It Just Works\" attitude in writing developer "
"tools,\n"
"and therefore has added `app/**/*.rb` to the default list of globs that it\n"
"searches for code in. You no longer need to create a `.yardopts` just to\n"
"list your app directory when documenting your code on rubydoc.info.\n"
"We should have done this a while ago! And don't worry, YARD still checks\n"
"lib and ext by default, too."
msgstr ""
"YARDは開発者のツールで書かれている\\\"ちゃんと動く\\\"姿勢をフォローしようとする、\n"
"従って、それがコード用に検索するglobのデフォルトのリストに\n"
"追加された`app/**/*.rb`を持つ\n"
"あなたはもはやrubydoc.infoであなたのコードを記述する時に\n"
"あなたのアプリのディレクトリ記述するのに`.yardopts`を作成する必要はない。\n"
"ちょっと前にこれが完成したが、心配しないで、\n"
"YARDはまだデフォルトでlibとextもチェックする。"

#: ../docs/WhatsNew.md:342
msgid ""
"## Added support for metadata (@title, @markup) in extra files/readmes "
"(0.7.0)"
msgstr ""
"## 追加のファイルとREADMEの中でメタデータ(@title,@markup)用のサポートが追加さ"
"れた(0.7.0)"

#: ../docs/WhatsNew.md:344
msgid ""
"Extra files (READMEs, ChangeLogs, LICENSE files, and other guides) now "
"support\n"
"metadata tags, just like docstrings in code comments. By adding @tag values\n"
"to the top of a file (no whitespace preceding it) inside of a `# comment` "
"line,\n"
"YARD will detect and parse these tags and store it for later usage."
msgstr ""
"追加のファイル(README,ChangeLogs,LICENSEファイルや他のガイド)は、\n"
"すぐに、メタデータタグをサポートする(コードのコメント中のdocstringのよう"
"に)。\n"
"`# comment`行の中のファイルの最初に@tagの値を追加する事で、\n"
"YARDは、このタグを検知,解析し、最新の方法でそれを記録するだろう。"

#: ../docs/WhatsNew.md:349
msgid ""
"Tags can contain arbitrary data as well as arbitrary tag names, however the\n"
"tag names @title and @markup are reserved to specify the document title and\n"
"markup format respectively. The title will be used in the file list menu,\n"
"index page, as well as any linking of the file via the `{file:Filename}`\n"
"syntax. An example of a document with metadata would be:"
msgstr ""
"タグは任意のデータも任意のタグ名も含める事ができる、\n"
"しかしながら、タグ名の@titleと@markupは、\n"
"ドキュメントのタイトルとマークアップフォーマットを個別に指定する為に用意される。\n"
"タイトルはファイルリストメニューや\n"
"index pageも`{file:Filename}`構文経由の任意のファイルへのリンクでも利用される。\n"
"次はメタデータを用いたドキュメントの例:"

#: ../docs/WhatsNew.md:355
msgid ""
"    # @title The Best Project Ever!\n"
"    # @markup rdoc\n"
"    # @author Foo Bar (custom tag, does not display in templates)"
msgstr ""
"    # @title The Best Project Ever!\n"
"    # @markup rdoc\n"
"    # @author Foo Bar (custom tag, does not display in templates)"

#: ../docs/WhatsNew.md:359
msgid "    = This Project Rules"
msgstr "    = This Project Rules"

#: ../docs/WhatsNew.md:361
msgid "    == Contents"
msgstr "    == Contents"

#: ../docs/WhatsNew.md:363
msgid "    ..."
msgstr "    ..."

#: ../docs/WhatsNew.md:365
msgid ""
"Note that previous versions of YARD recommended specifying the markup of an\n"
"extra file with the `#!markup` shebang, but the `@markup` metadata tag is "
"now\n"
"the \"best practice\" for specifying the markup format of an extra file."
msgstr ""
"次の事に留意する。\n"
"YARDの前のバージョンは、\n"
"`#!markup`のshebangを用いた追加のファイルのマークアップの指定が\n"
"推奨された。\n"
"しかし、今は`@markup`メタデータタグが、\n"
"追加のファイルのマークアップフォーマットを指定するのに最善の方法である。"

#: ../docs/WhatsNew.md:369
msgid "## Added `yard list` command (alias for `yardoc --list`) (0.7.0)"
msgstr ""
"## `yard list`コマンドを追加する。(`yardoc --list`用のエイリアス) (0.7.0)"

#: ../docs/WhatsNew.md:371
msgid ""
"The `yardoc --list` command is used to list objects that are parsed from\n"
"a codebase. This can be used to grep methods/classes in a codebase from the\n"
"command line. `yard list` now calls `yardoc --list` as a convenience command."
msgstr ""
"`yardoc --list`コマンドはソースコードから解析されるリストオブジェクトの為に利"
"用される。\n"
"これは、ソースコードの中でメソッド/クラスをgrepする為に利用できる。\n"
"`yard list`は、便利なメソッドとして`yardoc --list`を呼び出すようになった。"

#: ../docs/WhatsNew.md:375
msgid ""
"Note that the `yardoc --list` command may eventually be replaced by a more\n"
"feature-filled `yard list` command, so `yard list` should be used instead "
"of\n"
"`yardoc --list` when possible."
msgstr ""
"次の事に留意する。`yardoc --list`コマンドは、\n"
"将来、より多くの機能で満たされた`yard list`コマンドに切り替わるだろう。\n"
"なので可能であれば`yardoc --list`の代わりに、`yard list`を利用する方がよい。"

#: ../docs/WhatsNew.md:379
msgid "## Added Git support in `yard diff` (0.7.0)"
msgstr "## `yard diff`でGitのサポートが追加された (0.7.0)"

#: ../docs/WhatsNew.md:381
msgid ""
"The `yard diff` command can now perform object diffing on git repositories.\n"
"Provide the `--git` switch to `yard diff` with 2 commit/branches like so:"
msgstr ""
"`yard diff`コマンドは、すぐに、gitリポジトリ上でオブジェクトのdiffを実行す"
"る。\n"
"`yard diff`に切り替える`--git`を提供する。\n"
"次のように、2つのcommitとbrancheを切り替える。"

#: ../docs/WhatsNew.md:384
msgid ""
"    $ yard diff --git HEAD~5 HEAD\n"
"    Added objects:"
msgstr ""
"    $ yard diff --git HEAD~5 HEAD\n"
"    Added objects:"

#: ../docs/WhatsNew.md:387
msgid ""
"      YARD::Parser::SourceParser#contents\n"
"      YARD::Parser::SourceParser#globals\n"
"      ..."
msgstr ""
"      YARD::Parser::SourceParser#contents\n"
"      YARD::Parser::SourceParser#globals\n"
"      ..."

#: ../docs/WhatsNew.md:391
msgid "## Added `{include:file:FILENAME}` syntax (0.7.0)"
msgstr "## `{include:file:FILENAME}`構文 (0.7.0)"

#: ../docs/WhatsNew.md:393
msgid ""
"You can now use the `{include:file:FILENAME}` syntax to embed the contents\n"
"of an extra file marked up in its markup format. This syntax supports "
"embedding\n"
"Ruby source files and performing syntax highlighting on the code."
msgstr ""
"あなたはすぐに、\n"
"マークアップされた追加のファイルの内容を埋め込む為の\n"
"`{include:file:FILENAME}`構文を利用できる。\n"
"この構文は、Rubyのソースファイルの埋め込みと構文のコードハイライトの実行をサ"
"ポートする。"

#: ../docs/WhatsNew.md:397
msgid ""
"## Added `{render:OBJECT}` syntax to embed object docs in extra files (0.7.0)"
msgstr ""
"## 追加のファイルでdocsオブジェクトを埋め込む為に`{render:OBJECT}`構文を追加"
"した (0.7.0)"

#: ../docs/WhatsNew.md:399
msgid ""
"You can now use the `{render:Object}` syntax to embed the documentation\n"
"rendering of an entire object (method, class, module) inside of an extra "
"file.\n"
"This is useful when writing non-API based guides that might require listing\n"
"a few helper methods or classes. The {file:docs/GettingStarted.md} "
"discussed\n"
"this syntax in more detail (with example usage)."
msgstr ""
"あなたは、追加のファイルの中の全てのオブジェクト(メソッド,クラス,モジュール)のドキュメント表示を\n"
"埋め込む為に`{render:Object}`構文を利用できる。\n"
"これはいくつかのヘルパーメソッドや\n"
"クラスを記述する必要があるAPIベースではないガイドを書く時に便利である。\n"
"この構文の更なる詳細(例や使用法)は、\n"
"{file:docs/GettingStarted.md}で説明される。"

#: ../docs/WhatsNew.md:405
msgid "## Added improved templates API for custom CSS/JS/menus (0.7.0)"
msgstr "## CSS/JS/メニュー用に改良されたテンプレートAPIが追加された (0.7.0)"

#: ../docs/WhatsNew.md:407
msgid ""
"Plugin & template developers can now more easily insert custom stylesheet\n"
"or JavaScript files in their customized templates, thanks to an abstraction\n"
"of the template API. This is documented in the {docs/Templates.md} "
"document.\n"
"In addition to custom CSS/JS, developers can also create custom menu tabs\n"
"in both the framed and non framed version of the default theme."
msgstr ""
"プラグインとテンプレートの開発者は、\n"
"template APIの抽象化のおかげで、\n"
"カスタマイズされたテンプレートで\n"
"スタイルシートやJavaScriptのファイルを挿入できるようになった。\n"
"これは、{docs/Templates.md}ドキュメントの中で記述される。\n"
"さらに、カスタムCSS/JSで、開発者は、\n"
"フレーム有とデフォルトテーマのフレーム無しの両方のカスタムメニュータブを\n"
"作成する事もできる。"

#: ../docs/WhatsNew.md:413
msgid "## Added Ruby markup type (`-m ruby`) (0.7.0)"
msgstr "## Rubyマークアップ型(`-m ruby`)が追加された (0.7.0)"

#: ../docs/WhatsNew.md:415
msgid ""
"The Ruby markup type (`-m ruby`) will now use syntax highlighting for all\n"
"formatting. This is probably not useful as a global switch, but can be used\n"
"on individual extra files using the metadata markup specification discussed\n"
"above."
msgstr ""
"Rubyマークアップ型の(`-m ruby`)は、すぐに、\n"
"全てのフォーマット用に構文のハイライトを利用する。\n"
"これは全体の切り替えとしては、恐らく便利ではないが、\n"
"上で説明されたメタデータマークアップの指定によって\n"
"個々の追加のファイル上で利用できる。"

#: ../docs/WhatsNew.md:420
msgid ""
"## Added state tracking variables to Parser/Handler architecture (0.7.0)"
msgstr ""
"## Parser/Handlerアーキテクチャにトラッキング変数の状態が追加された (0.7.0)"

#: ../docs/WhatsNew.md:422
msgid ""
"The parser and handler architecture now contain state variables\n"
"{YARD::Handlers::Base#extra_state} and {YARD::Handlers::Processor#globals}\n"
"to share data across handlers and the entire processing phase. "
"`#extra_state`\n"
"provided a place to store per-file data, while `#globals` gives the "
"developer\n"
"access to inter-file state when parsing multiple files at once."
msgstr ""
"パーサーとハンドラーのアーキテクチャは、\n"
"ハンドラーと全ての処理段階に渡って共有する為に\n"
"{YARD::Handlers::Base#extra_state} と {YARD::Handlers::Processor#globals}の\n"
"変数の状態を含むようになった。\n"
"`#extra_state`メソッドは、ファイル毎にデータを記録する為の場所を提供し、\n"
"`#globals`メソッドは、一気に複数のファイルを解析する時に内部のファイルの状態に\n"
"開発者がアクセスする事を許可する。"

#: ../docs/WhatsNew.md:428
msgid "## Added before/after callbacks to SourceParser (0.7.0)"
msgstr "## SourceParserにbeforeとafterのコールバックが追加された (0.7.0)"

#: ../docs/WhatsNew.md:430
msgid ""
"The {YARD::Parser::SourceParser} class can now register callbacks to "
"execute\n"
"code before and after parsing of file globs, as well as before and after\n"
"parsing of individual files. This allows plugin developers to perform\n"
"setup/teardown (and set global state or update the {YARD::Registry})."
msgstr ""
"{YARD::Parser::SourceParser}クラスは、\n"
"ファイルグロブの解析の前後のコードも個々のファイルの解析の前後も\n"
"実行する為にすぐにコールバックを記録できる。\n"
"これは、セットアップ/開発(全体の状態や{YARD::Registry}の更新)を実行する為、\n"
"開発者のプラグインを受入れる。"

#: ../docs/WhatsNew.md:435
msgid "See the documentation for the following methods:"
msgstr "次のメソッド用のドキュメントを参照:"

#: ../docs/WhatsNew.md:437
msgid ""
"* {YARD::Parser::SourceParser.before_parse_list}\n"
"* {YARD::Parser::SourceParser.after_parse_list}\n"
"* {YARD::Parser::SourceParser.before_parse_file}\n"
"* {YARD::Parser::SourceParser.after_parse_file}"
msgstr ""
"* {YARD::Parser::SourceParser.before_parse_list}\n"
"* {YARD::Parser::SourceParser.after_parse_list}\n"
"* {YARD::Parser::SourceParser.before_parse_file}\n"
"* {YARD::Parser::SourceParser.after_parse_file}"

#: ../docs/WhatsNew.md:442
msgid ""
"## Can now use `--yardopts FILE` to specify a custom yardopts file (0.7.0)"
msgstr ""
"## カスタムyardoptsファイルを指定するのに、`--yardopts FILE`を利用できるよう"
"になった (0.7.0)"

#: ../docs/WhatsNew.md:444
msgid ""
"The `yardoc` command now supports `--yardopts FILE` to specify custom ."
"yardopts\n"
"options files. This is useful if you have multiple documentation sets, such\n"
"as a guide documentation set and an API documentation set."
msgstr ""
"`yardoc`コマンドは、すぐに\n"
"カスタム.yardopts設定ファイルを指定するのに、\n"
"`--yardopts FILE`をサポートする。\n"
"これは、ガイドキュメントやAPIドキュメントのような\n"
"複数のドキュメントのグループを持っている場合、便利である。"

#: ../docs/WhatsNew.md:448
msgid "## Added new `-t guide` template for guide based docs (0.7.0)"
msgstr ""
"## docstringベースのガイド用に`-t guide`テンプレートが新しく追加された "
"(0.7.0)"

#: ../docs/WhatsNew.md:450
msgid ""
"You can now write guide style documentation using a new 'guide' template "
"that\n"
"only generates documentation for extra files. You would use it in the form:"
msgstr ""
"あなたは、追加のファイル用のドキュメントだけ生成する\n"
"新しく追加された'guide'テンプレートによって\n"
"すぐにガイドスタイルドキュメントを書く事ができる。\n"
"あなたは、次のような形式で利用できる。"

#: ../docs/WhatsNew.md:453
msgid "    yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE"
msgstr "    yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE"

#: ../docs/WhatsNew.md:455
msgid ""
"This creates the sections for the readme, a getting started, frequently "
"asked\n"
"questions, trouble shooting and license page."
msgstr ""
"これは、README,GettingStarted,FAQ,トラブルシューティング,ライセンスページ用の"
"セクションを生成する。"

#: ../docs/WhatsNew.md:458
msgid ""
"If you need to refer to class / method documentation, you can embed API "
"documentation\n"
"using the `{render:Object}` tag discussed above."
msgstr ""
"クラスとメソッドドキュメントに参照する必要がある場合、\n"
"APIドキュメントを上で説明された`{render:Object}`タグによって埋め込む事が出来"
"る。"

#: ../docs/WhatsNew.md:461
msgid "## Github Flavoured Markdown now works out-of-box (0.7.4)"
msgstr ""

#: ../docs/WhatsNew.md:463
msgid ""
"Due to the growing popularity of Github-Flavoured-Markdown (GFM), YARD now "
"uses\n"
"the Redcarpet library as the default Markdown formatting library with GFM "
"fenced\n"
"code blocks enabled. This means that you can use fenced code blocks inside "
"of\n"
"Markdown files with redcarpet installed without any extra code. Previously, "
"users\n"
"who wanted GFM in their Markdown would have to specify `-m markdown -M "
"redcarpet`,\n"
"but this is now the default behaviour for YARD."
msgstr ""

#: ../docs/WhatsNew.md:470
msgid ""
"Note that you can still specify language types in code blocks without GFM in "
"YARD\n"
"by using the \"!!!lang\" prefix syntax. For example (plain means no markup):"
msgstr ""

#: ../docs/WhatsNew.md:473
msgid ""
"    !!!plain\n"
"    !!!plain\n"
"    Some code\n"
"    block here."
msgstr ""
"    !!!plain\n"
"    !!!plain\n"
"    Some code\n"
"    block here."

#: ../docs/WhatsNew.md:478
msgid "The GFM version would be:"
msgstr ""

#: ../docs/WhatsNew.md:480
msgid ""
"    !!!plain\n"
"    ```plain\n"
"    Some code\n"
"    block here.\n"
"    ```"
msgstr ""
"    !!!plain\n"
"    ```plain\n"
"    Some code\n"
"    block here.\n"
"    ```"

#: ../docs/WhatsNew.md:486
msgid "## Added `-m textile_strict` and `-m pre` markup types (0.7.4)"
msgstr ""

#: ../docs/WhatsNew.md:488
msgid ""
"A new \"textile_strict\" markup type was added which behaves exactly like "
"\"textile\"\n"
"except it enables hard breaks, so newlines behave as line breaks in the "
"HTML\n"
"(using `
    ` tags). This option is added for users who want the classic "
"textile\n"
"behaviour."
msgstr ""

#: ../docs/WhatsNew.md:493
msgid "## Reorganized markup types 'text' and 'none' (0.7.4)"
msgstr ""

#: ../docs/WhatsNew.md:495
msgid ""
"Due to the new pre markup type, the behaviour for text and none were "
"slightly\n"
"reorganized to be more intuitive. The following behaviours now represent "
"these\n"
"markup types:"
msgstr ""

#: ../docs/WhatsNew.md:499
msgid ""
" * pre: Used to wrap text inside `
    ` tags\n"
" * text: No formatting except for hard breaks (`
    `) on newlines\n"
" * none: No formatting at all."
msgstr ""

#: ../docs/WhatsNew.md:503
msgid ""
"In all cases, HTML is escaped from input. If you want no HTML escaping, use "
"the\n"
"html markup type."
msgstr ""

#: ../docs/WhatsNew.md:506
msgid "## Add support for `rb_define_alias` (0.7.4)"
msgstr "## `rb_define_alias`用のサポートが追加された (0.7.4)"

#: ../docs/WhatsNew.md:508
msgid ""
"CRuby code can now make use of the `rb_define_alias` function. "
"Documentation\n"
"for aliases is not supported, however."
msgstr ""

#: ../docs/WhatsNew.md:511
msgid "# What's New in 0.6.x?"
msgstr ""

#: ../docs/WhatsNew.md:513
msgid ""
"1. **Local documentation server for RubyGems or projects (`yard server`)** "
"(0.6.0)\n"
"2. **Groups support for method listing** (0.6.0)\n"
"3. **Single file template (`--one-file`) support** (0.6.0)\n"
"4. **`yard` CLI executable with pluggable commands** (0.6.0)\n"
"5. **`yard diff` command to object-diff two versions of a project** (0.6.0)\n"
"6. **Added `--asset` option to `yardoc`** (0.6.0)\n"
"7. **New template API** (0.6.0)\n"
"8. **HTML template now adds inline Table of Contents for extra files pages** "
"(0.6.0)\n"
"9. **Removed `--incremental` in favour of `--use-cache`** (0.6.0)\n"
"10. **Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.)** (0.6.0)\n"
"11. **Added `--transitive-tags` to register transitive tags** (0.6.0)\n"
"12. **`yardoc` now displays RDoc-like statistics (`--no-stats` to hide)** "
"(0.6.0)\n"
"13. **`yri` now works on constants** (0.6.0)\n"
"14. **Plugins are no longer auto-loaded (added `--plugin` switch)** (0.6.2)\n"
"15. **Added `YARD::Config` API and `~/.yard/config` configuration file** "
"(0.6.2)\n"
"16. **Added `yard config` command to view/edit configuration** (0.6.2)\n"
"17. **Added `yard server -t` template path switch** (0.6.2)\n"
"18. **Added `YARD::Server.register_static_path` for static server assets** "
"(0.6.2)\n"
"19. **YARD::Registry is now thread local** (0.6.5)\n"
"20. **Support for ripper gem in Ruby 1.8.7** (0.6.5)"
msgstr ""
"1. **RubyGemsやプロジェクト用のローカルドキュメントサーバー(`yard server`)** "
"(0.6.0)\n"
"2. **メソッド記述用のサポートをグループ化する** (0.6.0)\n"
"3. **単一のファイルのテンプレートのサポート(`--one-file`)** (0.6.0)\n"
"4. **`yard` のコマンドは、プラグインコマンドを用い実行可能となる** (0.6.0)\n"
"5. **プロジェクトの二つのバージョンのオブジェクトのdiffを見る為の`yard diff`"
"コマンド** (0.6.0)\n"
"6. **`yardoc`に`--asset`オプションが追加された** (0.6.0)\n"
"7. **新しいテンプレートAPI** (0.6.0)\n"
"8. **HTMLテンプレートは追加のファイルのページの内容のインラインテーブルを追加"
"する** (0.6.0)\n"
"9. **`--use-cache`のおかげで`--incremental`は削除された** (0.6.0)\n"
"10. **`yardoc`CLI経由で臨時のタグの記録(`--tag`, etc.)** (0.6.0)\n"
"11. **過渡的なタグを記録する為に、`--transitive-tags`が追加された** (0.6.0)\n"
"12. **`yardoc`がRDocのように統計値を表示するようになった(隠すには、`--no-"
"stats`)**\n"
"13. **`yri`定数で働くようになった** (0.6.0)\n"
"14. **プラグインは、自動ロードされなくなった(`--plugin`引数が追加された)** "
"(0.6.2)\n"
"15. **`YARD::Config`APIと`~/.yard/config`設定ファイルが追加された** (0.6.2)\n"
"16. **設定の調査/編集の為の`yard config`コマンドが追加された** (0.6.2)\n"
"17. **`yard server -t`テンプレートのパスの引数が追加された** (0.6.2)\n"
"18. **静的なサーバー資源用に`YARD::Server.register_static_path`が追加された"
"** (0.6.2)\n"
"19. **YARD::Registryがスレッドローカルになった** (0.6.5)\n"
"20. **Ruby 1.8.7でgemのripper用のサポート** (0.6.5)"

#: ../docs/WhatsNew.md:534
msgid ""
"## Local documentation server for RubyGems or projects (`yard server`) "
"(0.6.0)"
msgstr ""
"## RubyGems又はプロジェクト用のローカルドキュメントサーバー(`yard server`) "
"(0.6.0)"

#: ../docs/WhatsNew.md:536
msgid ""
"The new `yard server` command spawns a documentation server that can serve\n"
"either documentation for a local project or installed RubyGems. The server\n"
"will host (by default) on http://localhost:8808."
msgstr ""
"新しい`yard server`コマンドは\n"
"ローカルプロジェクトや既存のRubyGems用の全てのドキュメントを提供できる\n"
"ドキュメントサーバーを生みだす。\n"
"サーバーはhttp://localhost:8808のホスト(デフォルトで)になる。"

#: ../docs/WhatsNew.md:540
msgid ""
"To serve documentation for the active project (in the current directory):"
msgstr ""
"アーカイブのプロジェクト用にドキュメントを提供するには、(現在のディレクトリの"
"中の)"

#: ../docs/WhatsNew.md:544
msgid ""
"The server can also run in \"incremental\" mode for local projects. In this\n"
"situation, any modified sources will immediately be updated at each "
"request,\n"
"ensuring that the server always serve the code exactly as it is on disk.\n"
"Documenting your code in this fashion essentially gives you an efficient a\n"
"live preview without running a separate command everytime you make a "
"change.\n"
"To serve documentation for the active project in incremental mode:"
msgstr ""
"サーバーはローカルプロジェクト用の \"incremental\" モードでも起動できる。\n"
"この場合、任意の変更されるソースは個々のリクエストですぐに更新され、\n"
"サーバーが常にディスク上で確実にコードを提供することを保証する。\n"
"基本的にこのやり方であなたののコードのドキュメントは\n"
"毎回あなたが変更するたびに\n"
"区切られたコマンド無しで効率的に動いたままプレビューできる。\n"
"インクリメンタルモードで\n"
"アクティブなプロジェクトのためにドキュメントを提供するには:"

#: ../docs/WhatsNew.md:551
msgid "    $ yard server --reload"
msgstr "    $ yard server --reload"

#: ../docs/WhatsNew.md:553
msgid ""
"Note that in incremental mode, objects or method "
"groupings\n"
"  cannot be removed. If you have removed objects or modified groupings, you\n"
"  will need to flush the cache by deleting `.yardoc` and (optionally)\n"
"  restarting the server."
msgstr ""
"Note that in incremental mode, objects or method groupings\n"
"  cannot be removed. If you have removed objects or modified groupings, you\n"
"  will need to flush the cache by deleting `.yardoc` and (optionally)\n"
"  restarting the server."

#: ../docs/WhatsNew.md:558
msgid ""
"The documentation server can also serve documentation for all installed "
"gems\n"
"on your system, similar to `gem server`, but using YARD's functionality and\n"
"templates. To serve documentation for installed gems:"
msgstr ""
"ドキュメントサーバーはあなたのシステムで\n"
"`gem server`と同様にYARDの機能とテンプレートを使う事によって\n"
"既存の全てのgem用のドキュメントも提供できる\n"
"既存のgem用にドキュメントを提供するには:"

#: ../docs/WhatsNew.md:564
msgid ""
"Documentation for the gem need not be previously "
"generated\n"
"  at install-time. If documentation for the gem has not been generated, "
"YARD\n"
"  will do this for you on-the-fly. It is therefore possible to speed up "
"your\n"
"  gem installs by using `gem install GEMNAME --no-rdoc` without "
"repercussion.\n"
"  You can also add this switch to your `~/.gemrc` file so that you don't "
"need\n"
"   to re-type it each time. See [this link](http://stackoverflow.com/"
"questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install)\n"
"   for exact instructions."
msgstr ""
"Documentation for the gem need not be previously generated\n"
"  at install-time. If documentation for the gem has not been generated, YARD\n"
"  will do this for you on-the-fly. It is therefore possible to speed up your\n"
"  gem installs by using `gem install GEMNAME --no-rdoc` without repercussion.\n"
"  You can also add this switch to your `~/.gemrc` file so that you don't need\n"
"   to re-type it each time. See [this link](http://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install)\n"
"   for exact instructions."

#: ../docs/WhatsNew.md:572
msgid "## Groups support for method listing (0.6.0)"
msgstr "## メソッドの記述用のサポートをグループ化する (0.6.0)"

#: ../docs/WhatsNew.md:574
msgid ""
"You can now organize methods in a class/module into logical separated "
"groups.\n"
"These groups apply lexically and are listed in the order they are defined.\n"
"For instance, to define a group:"
msgstr ""
"あなたは論理的に分けられたグループへ\n"
"class/moduleの中のメソッドをまとめられるようになった。\n"
"これらのグループは単語的に適用され、\n"
"これらの命令が定義される中で記述される。\n"
"例えばグループを定義するには:"

#: ../docs/WhatsNew.md:578
msgid "    # @group Rendering an Object"
msgstr "    # @group Rendering an Object"

#: ../docs/WhatsNew.md:580
msgid ""
"    # Documentation here\n"
"    def foo; end"
msgstr ""
"    # Documentation here\n"
"    def foo; end"

#: ../docs/WhatsNew.md:583
msgid ""
"    # Extra documentation...\n"
"    def bar; end"
msgstr ""
"    # Extra documentation...\n"
"    def bar; end"

#: ../docs/WhatsNew.md:586
msgid "    # @group Another Group"
msgstr "    # @group Another Group"

#: ../docs/WhatsNew.md:588
msgid "    def aaa; end"
msgstr "    def aaa; end"

#: ../docs/WhatsNew.md:590
msgid ""
"Note that these `@group` and `@endgroup` declarations "
"are\n"
"  not \"tags\" and should always be separated with at least 1 line of "
"whitespace\n"
"  from any other documentation or code."
msgstr ""
"Note that these `@group` and `@endgroup` declarations are\n"
"  not \"tags\" and should always be separated with at least 1 line of whitespace\n"
"  from any other documentation or code."

#: ../docs/WhatsNew.md:594
msgid ""
"In the above example, \"Rendering an Object\" will be listed with \"foo\" "
"and\n"
"\"bar\" above \"Another Group\", even though \"aaa\" comes before the two "
"other\n"
"methods, alphabetically. To end a group, use `@endgroup`. It is not "
"necessary\n"
"to end a group to start a new one, only if there is an object following the\n"
"group that should not belong in any group."
msgstr ""
"上の例で \"表示されるオブジェクトは\"\n"
"\"Another Group\" の上の \"foo\" と \"bar\"の\n"
"二つの他のメソッドが前にあるけれども\n"
"実際にはアルファベット順で\"aaa\"が来て記述される。\n"
"グループを終りには`@endgroup`を使う。\n"
"これは新しくグループを作るのにグループを終了する必要はない。\n"
"任意のグループの中に所属すべきではないグループに続くオブジェクトがある場合だけである。"

#: ../docs/WhatsNew.md:600
msgid "    # @group Group 1"
msgstr "    # @group Group 1"

#: ../docs/WhatsNew.md:602
msgid "    def foo; end"
msgstr "    def foo; end"

#: ../docs/WhatsNew.md:604
msgid "    # @endgroup"
msgstr "    # @endgroup"

#: ../docs/WhatsNew.md:606
msgid ""
"    # This method should not be listed in any group\n"
"    def bar; end"
msgstr ""
"    # This method should not be listed in any group\n"
"    def bar; end"

#: ../docs/WhatsNew.md:609
msgid "## Single file template (`--one-file`) support (0.6.0)"
msgstr "## 単一のファイルのテンプレート (`--one-file`)のサポート (0.6.0)"

#: ../docs/WhatsNew.md:611
msgid ""
"`yardoc` now has the `--one-file` option to generate a single-file template\n"
"for small scripts and libraries. In this case, any comments at the top of\n"
"the script file will be recognized as a README."
msgstr ""
"`yardoc`は、小さいスクリプトやライブラリ用の\n"
"単一のファイルのテンプレートを生成する`--one-file`オプションが追加された。\n"
"この場合、任意の内容の\n"
"スクリプトファイルのトップでの任意のコメントは、READMEとして認識される。"

#: ../docs/WhatsNew.md:615
msgid "## `yard` CLI executable with pluggable commands (0.6.0)"
msgstr "## `yard` CLI がプラグイン可能なコマンドとして実行可能になる (0.6.0)"

#: ../docs/WhatsNew.md:617
msgid ""
"The `yardoc` and `yri` commands are not deprecated and "
"can\n"
"  continue to be used. They are shortcuts for `yard doc` and `yard ri`\n"
"  respectively. However, `yard-graph` has been removed."
msgstr ""
"The `yardoc` and `yri` commands are not deprecated and can\n"
"  continue to be used. They are shortcuts for `yard doc` and `yard ri`\n"
"  respectively. However, `yard-graph` has been removed."

#: ../docs/WhatsNew.md:621
msgid ""
"YARD now has a `yard` executable which combines all pre-existing and new\n"
"commands into a single pluggable command that is both easier to remember "
"and\n"
"access. To get a list of commands, type `yard --help`."
msgstr ""
"YARDは既存のものと新たなコマンドを一体化し、\n"
"思い出しとアクセスすることを簡単に両立する単一の付け外し自由な\n"
"`yard`コマンドを持つようになった。\n"
"コマンドのリストを取得するには`yard --help`とタイプする。"

#: ../docs/WhatsNew.md:625
msgid ""
"If you are a plugin developer, you can create your own `yard` command by "
"first\n"
"subclassing the {YARD::CLI::Command} class and then registering this class\n"
"with the {YARD::CLI::CommandParser.commands} list. For instance:"
msgstr ""
"あなたがプラグイン開発者なら、\n"
"先に {YARD::CLI::Command} クラスをサブクラス化する事によって`yard`コマンドを\n"
"あなた自身の手によって作成できる。\n"
"その時 {YARD::CLI::CommandParser.commands} のリストを用いこのクラスを登録する。\n"
"例えば:"

#: ../docs/WhatsNew.md:629
msgid "    YARD::CLI::CommandParser.commands[:my_command] = MyCommandClass"
msgstr "    YARD::CLI::CommandParser.commands[:my_command] = MyCommandClass"

#: ../docs/WhatsNew.md:631
msgid ""
"The above line will enable the user to execute `yard my_command [options]`."
msgstr ""
"上の行で、ユーザーが`yard my_command [options]`を実行する事が可能となる。"

#: ../docs/WhatsNew.md:633
msgid "## `yard diff` command to object-diff two versions of a project (0.6.0)"
msgstr ""
"## プロジェクトの二つのバージョンをオブジェクトのdiffするコマンド、`yard "
"diff` (0.6.0)"

#: ../docs/WhatsNew.md:635
msgid ""
"One of the built-in commands that comes with the new `yard` executable is "
"the\n"
"ability to do object-oriented diffing across multiple versions of the same\n"
"project, either by 2 versions of a gem, or 2 working copies. Just like\n"
"regular diffing tells you which lines have been added/removed in a file,\n"
"object diffing allows you to see what classes/methods/modules have been\n"
"added/removed between versions of a codebase."
msgstr ""
"新しく実行可能な`yard`は、\n"
"gemの二つのバージョンや、2つの作業中のコピーのような、\n"
"同じプロジェクトの複数のバージョンに渡ってオブジェクト思考のdiffをする機能で、\n"
"組み込みコマンドの一つである。\n"
"普通のdiffのように、\n"
"ファイルで追加/削除された行が表示される。\n"
"diffのオブジェクトは、\n"
"コードのバージョン間で追加/削除されたクラス/メソッド/モジュールの参照を受け入れる。"

#: ../docs/WhatsNew.md:642
msgid ""
"For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing]"
"(http://gnuu.org/2010/06/26/yard-object-oriented-diffing/)."
msgstr "For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing](http://gnuu.org/2010/06/26/yard-object-oriented-diffing/)."

#: ../docs/WhatsNew.md:644
msgid "## `yard stats` to display statistics and undocumented objects (0.6.0)"
msgstr ""
"## 統計値を表示する`yard stats`とそれを表示しないオブジェクトが追加された "
"(0.6.0)"

#: ../docs/WhatsNew.md:646
msgid "YARD now outputs the following statistics when `yard stats` is run:"
msgstr "YARDは、`yard stats`が起動する時に続く統計値を出力する。(次のように)"

#: ../docs/WhatsNew.md:648
msgid ""
"    Files:         125\n"
"    Modules:        35 (    4 undocumented)\n"
"    Classes:       139 (   29 undocumented)\n"
"    Constants:      53 (   20 undocumented)\n"
"    Methods:       602 (   70 undocumented)\n"
"     85.16% documented"
msgstr ""
"    Files:         125\n"
"    Modules:        35 (    4 undocumented)\n"
"    Classes:       139 (   29 undocumented)\n"
"    Constants:      53 (   20 undocumented)\n"
"    Methods:       602 (   70 undocumented)\n"
"     85.16% documented"

#: ../docs/WhatsNew.md:655
msgid ""
"Note that these statistics are based on what you have set to show in your\n"
"documentation. If you use `@private` tags and/or do not display\n"
"private/protected methods in your documentation, these will not show up as\n"
"undocumented. Therefore this metric is contextual."
msgstr ""
"次の事に留意する。\n"
"これらの統計はあなたのドキュメントの中を調べられた設定が基準となる。\n"
"`@private`タグを使う場合やあなたのドキュメントのなかでprivate/protectedメソッドを\n"
"表示しない場合は、undocumentとしてこれらは表示しない。\n"
"従ってこの計測はコンテキスト次第である。"

#: ../docs/WhatsNew.md:660
msgid ""
"You can also specifically list all undocumented objects (and their file\n"
"locations) with the `--list-undoc` option."
msgstr ""
"あなたは`--list-undoc`オプションを用い\n"
"全ての未記載のオブジェクト(とそのファイルの場所)を明示的に記述できる。"

#: ../docs/WhatsNew.md:663
msgid "## Added `--asset` option to `yardoc` (0.6.0)"
msgstr "## `yardoc`に`--asset`オプションが追加された(0.6.0)"

#: ../docs/WhatsNew.md:665
msgid ""
"The `yardoc` command can now take the `--asset` option to copy over\n"
"files/directories (recursively) to the output path after generating\n"
"documentation. The format of the argument is \"from:to\" where from is the\n"
"source path and to is the destination. For instance, YARD uses the "
"following\n"
"syntax in the `.yardopts` file to copy over image assets from the\n"
"'docs/images' directory into the 'images' directory after generating HTML:"
msgstr ""
"`yardoc`コマンドは、\n"
"ドキュメント生成の後で出力するパスに\n"
"files/directories(再帰的に)全域をコピーするための\n"
"`--asset`オプションが追加された。\n"
"引数のフォーマットは\n"
"fromがソースパスでtoが目的になる場所、\n"
"形式は\"from:to\"となる。\n"
"例えば、HTML生成の後で、\n"
"'images'ディレクトリの中へ\n"
"'docs/images'ディレクトリからイメージの資産全部をコピーするために\n"
"`.yardopts`ファイルの中に次の構文を使う:"

#: ../docs/WhatsNew.md:672
msgid "    --asset docs/images:images"
msgstr "    --asset docs/images:images"

#: ../docs/WhatsNew.md:674
msgid "## New template API (0.6.0)"
msgstr "## 新しくなったテンプレートAPI (0.6.0)"

#: ../docs/WhatsNew.md:676
msgid ""
"The new template API allows for easier insertion of sections within an\n"
"inherited template. You should no longer need to insert by index, an\n"
"error-prone process that could break when a template is updated. Instead of:"
msgstr ""
"新たなテンプレートAPIは\n"
"継承されたテンプレートの中のセクションの簡単な挿入用に許可する。\n"
"あなたはもはやindexで挿入する必要はない、\n"
"エラー傾向は\n"
"テンプレートが更新される時に中断され処理する。\n"
"代わりに:"

#: ../docs/WhatsNew.md:680
msgid "    sections.last.place(:my_section).before(:another_section)"
msgstr "    sections.last.place(:my_section).before(:another_section)"

#: ../docs/WhatsNew.md:682
msgid "use:"
msgstr "use:"

#: ../docs/WhatsNew.md:684
msgid "    sections.place(:my_section).before_any(:another_section)"
msgstr "    sections.place(:my_section).before_any(:another_section)"

#: ../docs/WhatsNew.md:686
msgid ""
"You can see more in the {file:docs/Templates."
"md#Inserting_and_Traversing_Sections}\n"
"document."
msgstr ""
"あなたは{file:docs/Templates.md#Inserting_and_Traversing_Sections}ドキュメン"
"トで、\n"
"更に詳細を見る事が出来る。"

#: ../docs/WhatsNew.md:689
msgid ""
"## HTML template now adds inline Table of Contents for extra files pages "
"(0.6.0)"
msgstr ""
"## HTML テンプレートは追加のファイルのページ用に、\n"
"その内容のインラインテーブルが追加された(0.6.0)"

#: ../docs/WhatsNew.md:691
msgid ""
"A table of contents is now generated dynamically using JavaScript for extra\n"
"file pages (such as README's, or this document). It is generated based off "
"the\n"
"headers (h1,h2,... tags) used in the document, and can be floated to the\n"
"right or listed inline on the page."
msgstr ""
"コンテンツのテーブルは追加のファイルのページ用に、\n"
"JavaScriptによって動的に生成されるようになった(READMEやこのドキュメントのように)。\n"
"これは、ドキュメントで利用されたヘッダー(h1,h2,... tags)がのぞかれた\n"
"ベースを生成し右側に添えられるか、又は、ページ上でインラインが記述される。"

#: ../docs/WhatsNew.md:696
msgid "## Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.) (0.6.0)"
msgstr "## `yardoc`CLI(`--tag`, etc.)経由での臨時のタグの記録 (0.6.0)"

#: ../docs/WhatsNew.md:698
msgid ""
"Simple meta-data tags can now be added at the command-line and registered "
"to\n"
"display in templates in a number of pre-defined ways. For instance, to "
"create\n"
"a freeform text tag, use the following:"
msgstr ""
"単純なメタデータタグは\n"
"コマンドラインで追加され、事前に定義されたいくつか方法で\n"
"テンプレートの中で表示されるために登録されるようになった。\n"
"例えばフリーフォームテキストのタグを作成するには、次のようになる:"

#: ../docs/WhatsNew.md:702
msgid "    --tag my_tag_name:\"My Tag Title\""
msgstr "    --tag my_tag_name:\"My Tag Title\""

#: ../docs/WhatsNew.md:704
msgid ""
"You can also create a \"typed\" tag (similar to `@return`), a typed named "
"tag\n"
"(similar to `@param`) as well as various combinations. The full list of\n"
"options are listed in `yardoc --help` under the \"Tag Options\" section."
msgstr ""
"あなたは\"型\"のタグ(`@return`と同様に)も\n"
"型のタグ名(`@param`と同様に)も様々な組み合わせもを作成する事もできる。\n"
"オプションの完全なリストは\n"
"`yardoc --help`の \"Tag Options\" のセクションよりで記述される。"

#: ../docs/WhatsNew.md:708
msgid ""
"If you wish to create a tag to store data but do not wish to show this data\n"
"in the templates, use the `--hide-tag` option to hide it from generated "
"output:"
msgstr ""
"あなたがデータを登録するためにタグを作成することを望むが、\n"
"テンプレートの中のこのデータを一覧したくない場合、\n"
"生成された出力からそれを隠すには`--hide-tag`オプションを使う。\n"
"\n"

#: ../docs/WhatsNew.md:711
msgid "    --hide-tag my_tag_name"
msgstr "    --hide-tag my_tag_name"

#: ../docs/WhatsNew.md:713
msgid "## Added `--transitive-tags` to register transitive tags (0.6.0)"
msgstr "## 過渡的なタグを記録するのに、`--transitive-tags`を追加された (0.6.0)"

#: ../docs/WhatsNew.md:715
msgid ""
"Transitive tags are tags that apply to all descendants of a namespace "
"(class\n"
"or module) when documented on that namespace. For instance, the `@since` "
"tag\n"
"is a transitive tag. Applying `@since` to a class will automatically apply\n"
"`@since` to all methods in the class. Creating a `@since` tag directly on a\n"
"method will override the inherited value."
msgstr ""
"transitiveタグは、namespace上(クラス又はモジュール)で記述された時、\n"
"全てのnamespaceの子孫に適用するタグである。\n"
"例えば、`@since`タグはTransitiveタグである。\n"
"クラスに`@since`タグを適用すると、\n"
"クラスの中の全てのメソッドに自動的に`@since`が適用される\n"
"メソッドで直接`@since`タグを作成すると継承された値をオーバーライドする。"

#: ../docs/WhatsNew.md:721
msgid ""
"You can specify transitive tags on the command-line by using this option. "
"Note\n"
"that the tags must already exist (built-in or created with the `--tag` "
"option)\n"
"to be specified as transitive. If you wish to do this programmatically, see\n"
"the {YARD::Tags::Library.transitive_tags} attribute."
msgstr ""
"このオプションによって\n"
"コマンドラインのタグを過渡的に指定できる\n"
"transitiveとして指定される\n"
"タグは既に存在しなければならない。\n"
"(組み込みや`--tag`オプションによって作成された)\n"
"あなたがこのプログラムを実行したいなら、 {YARD::Tags::Library.transitive_tags} 属性を参照する。"

#: ../docs/WhatsNew.md:726
msgid ""
"## `yardoc` now displays RDoc-like statistics (`--no-stats` to hide) (0.6.0)"
msgstr ""
"## `yardoc`は、RDocのような統計値の表示するようになった。(`--no-stats`で隠"
"す) (0.6.0)"

#: ../docs/WhatsNew.md:728
msgid ""
"As seen in the `yard stats` feature overview, `yardoc` displays RDoc-like\n"
"statistics when it is run. The output is equivalent to typing `yard stats`.\n"
"To hide this output when yardoc is run, use `--no-stats`."
msgstr ""
"上記のように`yard stats`機能の概要は\n"
"`yardoc`が起動する時にRDocのように統計を表示する\n"
"出力は`yard stats`をタイプするのと同様である。\n"
"yardocが起動する時にこの出力を隠すには、\n"
"`--no-stats`を使う"

#: ../docs/WhatsNew.md:732
msgid "## `yri` now works on constants (0.6.0)"
msgstr "## `yri`定数の処理をできるようになった (0.6.0)"

#: ../docs/WhatsNew.md:734
msgid ""
"Templates have now been added for text view of constants, which displays "
"any\n"
"documentation and the constant value."
msgstr ""
"テンプレートは定数の一覧を作成するため追加されるようになった。\n"
"これは任意のドキュメントと定数を表示する。"

#: ../docs/WhatsNew.md:737
msgid "## Plugins are no longer auto-loaded (added `--plugin` switch) (0.6.2)"
msgstr ""
"## プラグインは自動でロードされなくなった。(`--plugin`引数で追加できる) "
"(0.6.2)"

#: ../docs/WhatsNew.md:739
msgid ""
"This is a backwards-incompatible change that disables plugins from "
"automatically\n"
"loading when YARD starts up. From now on, you should manually declare which\n"
"plugins your project is using by adding `--plugin PLUGINNAME` to a `."
"yardopts`\n"
"file in the root of your project. You can also re-enable autoloaded plugins\n"
"by setting `load_plugins` to true in your configuration file (`yard config "
"load_plugins true`,\n"
"see next item). You can also set `autoload_plugins` to a list of plugins\n"
"to be automatically loaded on start."
msgstr ""
"これはYARDのスタートアップする時の自動的なロードから\n"
"プラグインを無効化する非後方互換な変更である。\n"
"今後はあなたは手動で宣言しなければならない、\n"
"それはあなたのプロジェクトのプラグインが\n"
"あなたのプロジェクトのrootで`.yardopts`ファイルに\n"
"`--plugin PLUGINNAME`を追加することによって利用される。\n"
"あなたの設定ファイルの中で`load_plugins`をtrueに設定する事によって\n"
"自動でロードされるプラグインを再度有効にできる。\n"
"(`yard config load_plugins true`, 事項参照)\n"
"あなたは、起動時に自動的にロードする為にプラグインのリストに\n"
"`autoload_plugins`に設定する事も出来る。"

#: ../docs/WhatsNew.md:747
msgid ""
"If you are a YARD plugin author, please make sure to inform your users of "
"these\n"
"changes."
msgstr ""
"あなたがYARDプラグインの作者の場合、\n"
"これらの変更をあなたのユーザーに通知するか確認してください。"

#: ../docs/WhatsNew.md:750
msgid ""
"Note that `--plugin` switches passed on the commandline (not via `."
"yardopts`)\n"
"are parsed before commands are loaded, and therefore can add in new CLI "
"commands."
msgstr ""
"次のことに留意する。\n"
"コマンドライン(`.yardopts`経由ではない)で渡された--pulugin引数はコマンドがロードされる前に解析され、\n"
"その結果、新しいCLIコマンドの中で追加できる。"

#: ../docs/WhatsNew.md:753
msgid ""
"## Added `YARD::Config` API and `~/.yard/config` configuration file (0.6.2)"
msgstr ""
"## `YARD::Config` APIと`~/.yard/config`設定ファイルが追加された。 (0.6.2)"

#: ../docs/WhatsNew.md:755
msgid ""
"There is a new global configuration API that can be accessed "
"programmatically\n"
"and set via the `~/.yard/config` file. The file is encoded as a YAML file,\n"
"and looks like:"
msgstr ""
"これらは、プログラムにアクセスできる新しいグローバル設定APIとなり、\n"
"`~/.yard/config`ファイル経由で設定される。\n"
"ファイルはYAMLファイルとしてエンコードされる、次のようになる"

#: ../docs/WhatsNew.md:767
msgid ""
"You can also set configuration options via the command-line (see next item)."
msgstr "あなたは、コマンドライン経由で設定オプションを設定できる。(次項参照)"

#: ../docs/WhatsNew.md:769
msgid "## Added `yard config` command to view/edit configuration (0.6.2)"
msgstr "## 設定を一覧/編集する為に`yard config` コマンドが追加された (0.6.2)"

#: ../docs/WhatsNew.md:771
msgid ""
"A new `yard config` command was created to view or edit the configuration\n"
"file via the commandline."
msgstr ""
"新しい`yard config`コマンドが、\n"
"コマンドライン経由で設定ファイルを一覧・編集する為に作成された。"

#: ../docs/WhatsNew.md:774
msgid ""
"* To view the current configuration use `yard config --list`.\n"
"* To view a specific item use `yard config ITEMNAME`\n"
"* To modify an item value use `yard config ITEMNAME VALUE`"
msgstr ""
"* 現在の設定を一覧するには、`yard config --list`を使う\n"
"* 特定の項目(item)を一覧するには、`yard config ITEMNAME`を使う\n"
"* 項目の値を変更するには、`yard config ITEMNAME VALUE`を使う"

#: ../docs/WhatsNew.md:778
msgid "## Added `yard server -t` template path switch (0.6.2)"
msgstr "## `yard server -t`テンプレートパス引数が追加された (0.6.2)"

#: ../docs/WhatsNew.md:780
msgid ""
"The `yard server` command now accepts `-t` or `--template-path` to register\n"
"a new template path for template customization."
msgstr ""
"`yard server` コマンドは、\n"
"テンプレートをカスタマイズする為に新しいテンプレートパスを記録する為、\n"
"`-t`、又は、`--template-path`を受け入れる。"

#: ../docs/WhatsNew.md:783
msgid ""
"## Added `YARD::Server.register_static_path` for static server assets (0.6.2)"
msgstr ""
"## 静的なサーバー資源用に`YARD::Sever.register_static_path`が追加された。 "
"(0.6.2)"

#: ../docs/WhatsNew.md:785
msgid ""
"The server now supports a command to register static asset paths. If you "
"are\n"
"extending the YARD::Server modules, make sure to register your asset paths\n"
"through this method."
msgstr ""
"サーバーは静的な資源のパスを記録する為のコマンドをサポートするようになっ"
"た。\n"
"あなたが、YARD::Serverモジュールを拡張する場合は、\n"
"このメソッドを通してあなたの資源のパスを記録するか確認してください。"

#: ../docs/WhatsNew.md:789
msgid "## YARD::Registry is now thread local (0.6.5)"
msgstr "## YARD::Registryはスレッドローカルとなった (0.6.5)"

#: ../docs/WhatsNew.md:791
msgid ""
"Creating a new thread will now implicitly load a new Registry that can be "
"used\n"
"to parse and process new code objects independently of the other threads. "
"Note\n"
"that this means you can no longer use the Registry across threads; you must\n"
"either access the threadlocal object directly, or synchronize threads to do\n"
"the processing in the initial registry's thread."
msgstr ""
"新しいスレッドの作成は暗黙の内に、\n"
"解析する為に利用できる新しいレジストリーをロードするだろう。\n"
"そして、他のスレッドとは独自に新しいコードオブジェクトを処理する。\n"
"次の事に留意する。\n"
"これはあなたがもう、スレッドを渡ってレジストリーを利用する必要はないことを意味する。\n"
"あなたは、スレッドのローカルオブジェクトに直接アクセスするか、又は、\n"
"スレッドのレジストリーの初期化の処理をする為にスレッドを同期しなければならない。"

#: ../docs/WhatsNew.md:797
msgid "## Support for ripper gem in Ruby 1.8.7 (0.6.5)"
msgstr "## Ruby 1.8.7 でのripper gemのサポート (0.6.5)"

#: ../docs/WhatsNew.md:799
msgid ""
"YARD now supports the Ruby 1.8.7 port of the `ripper` gem to improve "
"parsing\n"
"of source, both in terms of performance and functionality. When the "
"`ripper`\n"
"gem is available, YARD will use the \"new-style\" handlers. You can take "
"advantage\n"
"of this functionality by performing a `gem install ripper`."
msgstr ""
"パフォーマンスと機能性の両面で、\n"
"YARDはソースの解析を向上する為に`ripper`gemのRuby1.8.7の一部をサポートするよ"
"うになった。\n"
"`ripper`gemが実行可能な時、YARDは\"new-style\"のハンドラーを利用する。\n"
"`gem install ripper`を実行する事で、この機能の恩恵を受ける事ができる。"

#: ../docs/WhatsNew.md:805
msgid ""
"What's New in 0.5.x?\n"
"===================="
msgstr ""
"What's New in 0.5.x?\n"
"===================="

#: ../docs/WhatsNew.md:808
msgid ""
"1. **Support for documenting native Ruby C code** (0.5.0)\n"
"2. **Incremental parsing and output generation with `yardoc -c`** (0.5.0, "
"0.5.3)\n"
"2. **Improved `yri` support to perform lookups on installed Gems** (0.5.0)\n"
"3. **Added `yardoc --default-return` and `yardoc --hide-void-return`** "
"(0.5.0)\n"
"4. **Multiple syntax highlighting language support** (0.5.0)\n"
"5. **New .yardoc format** (0.5.0)\n"
"6. **Support for yard-doc-* gem packages as hosted .yardoc dbs** (0.5.1)\n"
"7. **Support for extra search paths in `yri`** (0.5.1)\n"
"8. **Generating HTML docs now adds frames view** (0.5.3)\n"
"9. **Tree view for class list** (0.5.3)\n"
"10. **Ability to specify markup format of extra files** (0.5.3)\n"
"11. **Keyboard shortcuts for default HTML template** (0.5.4)"
msgstr ""
"1. **RubyとCのコードのドキュメント化をサポートする** (0.5.0)\n"
"2. **`yaradoc -c`を用いたインクリメンタルな解析と出力生成ができるようになった"
"** (0.5.0, 0.5.3)\n"
"3. **`yardoc --default-return`と`yardoc --hide-void-return`が追加された** "
"(0.5.0)\n"
"4. **複数の構文のハイライトする言語をサポート** (0.5.0)\n"
"5. **新しい.yardocフォーマット** (0.5.0)\n"
"6. **ホストされた.yardoc dbsとしてyard-doc-* gem パッケージをサポートする** "
"(0.5.1)\n"
"7. **`yri`で追加の検索パスをサポートする** (0.5.1)\n"
"8. **HTMLドキュメントの生成はフレーム一覧が追加されるようになった** (0.5.3)\n"
"9. **クラスリスト用のツリービュー** (0.5.3)\n"
"10. **追加のファイルのマークアップフォーマットを指定する機能** (0.5.3)\n"
"11. **デフォルトのHTMLテンプレート用のキーボードショートカット** (0.5.4)"

#: ../docs/WhatsNew.md:821
msgid ""
"Support for documenting native Ruby C code (0.5.0)\n"
"--------------------------------------------------"
msgstr ""
"RubyとCのコードのドキュメント生成のサポート (0.5.0)\n"
"--------------------------------------------------"

#: ../docs/WhatsNew.md:824
msgid ""
"It is now possible to document native Ruby extensions with YARD with a new\n"
"C parser mostly borrowed from RDoc. This enables the ability to document\n"
"Ruby's core and stdlibs which will be hosted on http://yardoc.org/docs. In\n"
"addition, the .yardoc dump for the Ruby-core classes will become available\n"
"as an installable gem for yri support (see #3)."
msgstr ""
"大部分をRDocから取り入れた新しいCパーサーと共にYARDを用い\n"
"Rubyの拡張ドキュメントを実行可能になった。\n"
"これは、Rubyのコアと標準ライブラリを記述する事を可能にする。\n"
"そして、http://yardoc.org/docs でホスト(アクセスできる)されるだろう。\n"
"さらに、Rubyコアクラス用の.yardocのダンプは、\n"
"yriのサポートに用いるインストール可能なgemとして利用可能になるだろう。(#3 参"
"照)"

#: ../docs/WhatsNew.md:830
msgid ""
"Incremental parsing and output generation with `yardoc -c` (0.5.0, 0.5.3)\n"
"-------------------------------------------------------------------------"
msgstr ""
"`yaradoc -c`を用いたインクリメンタルな解析と出力生成 (0.5.0, 0.5.3)\n"
"-------------------------------------------------------------------------"

#: ../docs/WhatsNew.md:833
msgid ""
"
    Note: in 0.5.3 and above you must use --incremental\n"
"  to incrementally generate HTML, otherwise only parsing will be done\n"
"  incrementally but HTML will be generated with all objects. --"
"incremental\n"
"  implies -c, so no need to specify them both.
    "
msgstr ""
"
    Note: in 0.5.3 and above you must use --incremental\n"
"  to incrementally generate HTML, otherwise only parsing will be done\n"
"  incrementally but HTML will be generated with all objects. --incremental\n"
"  implies -c, so no need to specify them both.
    "

#: ../docs/WhatsNew.md:838
msgid ""
"YARD now compares file checksums before parsing when using `yardoc -c`\n"
"(aka `yardoc --use-cache`) to do incremental parsing of only the files that\n"
"have changed. HTML (or other output format) generation will also only be\n"
"done on the objects that were parsed from changed files (\\*). This makes "
"doing\n"
"a documentation development cycle much faster for quick HTML previews. Just\n"
"remember that when using incremental output generation, the index will not\n"
"be rebuilt and inter-file links might not hook up right, so it is best to\n"
"perform a full rebuild at the end of such previews."
msgstr ""
"YARDはインクリメンタルに変更されたファイルだけ解析をする為に、\n"
"`yardoc -c`(別名 `yardoc --use-cache`)を使う時、解析前のファイルを比較す"
"る。\n"
"HTML(又は、他の出力フォーマット)生成は、\n"
"変更されたファイル(\\*)から解析されるオブジェクト上で実行されるだけである。\n"
"これにより迅速なHTMLプレビューの為に、より速い開発サイクルを作りあげる事がで"
"きる。\n"
"ただインクリメンタルな出力生成によって覚えておいてほしいことは、\n"
"インデックスが再構築されない事とファイル間のリンクが正しく接続されないかもし"
"れない、\n"
"なので、このようなプレビューの終了時に完全な再構築を実行することをお勧めしま"
"す。"

#: ../docs/WhatsNew.md:847
msgid ""
"(\\*) Only for versions prior to 0.5.3. For 0.5.3+, use `--incremental` for\n"
"incremental HTML output."
msgstr ""
"(\\*) 0.5.3より前のバージョンのみ、0.5.3以上の場合は、\n"
"インクリメンタルHTML出力用の`--incremental`を使う。"

#: ../docs/WhatsNew.md:850
msgid ""
"Improved `yri` support to perform lookups on installed Gems (0.5.0)\n"
"-------------------------------------------------------------------"
msgstr ""
"インストールされたgemを検索する為の`yri`のサポートが改良された。(0.5.0)\n"
"-------------------------------------------------------------------"

#: ../docs/WhatsNew.md:853
msgid ""
"The `yri` executable can now perform lookups on gems that have been parsed\n"
"by yard. Therefore, to use this command you must first parse all gems with\n"
"YARD. To parse all gems, use the following command:"
msgstr ""
"実行可能な`yri`コマンドは、YARDで解析されていたgemの検索を実行できるように"
"なった。\n"
"したがって、このコマンドを使う為には、\n"
"あなたは、最初に全てのgemをYARDで解析しなければならない。\n"
"全てのgemを解析する為には、次のコマンドを利用する:"

#: ../docs/WhatsNew.md:857
msgid "    $ sudo yardoc --build-gems"
msgstr "    $ sudo yardoc --build-gems"

#: ../docs/WhatsNew.md:859
msgid ""
"The above command builds a .yardoc file for all installed gems in the\n"
"respective gem directory. If you do not have write access to the gem path,\n"
"YARD will write the yardoc file to `~/.yard/gem_index/NAME-VERSION.yardoc`."
msgstr ""
"上のコマンドは、gemディレクトリに関係する全てのインストール済みのgem用に."
"yardocファイルをビルドする。\n"
"あなたが、gemのパスへのアクセスを書き込んでいない場合、\n"
"YARDは`~/.yard/gem_index/NAME-VERSION.yardoc`にyardocファイルを書き込むだろ"
"う。"

#: ../docs/WhatsNew.md:863
msgid ""
"Note: you can also use `--re-build-gems` to force re-parsing of all gems."
msgstr ""
"注意:あなたは、全てのgemめ強制的に再解析するのに、`--re-build-gems`を使うこと"
"もできる。"

#: ../docs/WhatsNew.md:865
msgid "You can now do lookups with yri:"
msgstr "あなたは、下のようにyriで検索できるようになった"

#: ../docs/WhatsNew.md:867
msgid "    $ yri JSON"
msgstr "    $ yri JSON"

#: ../docs/WhatsNew.md:869
msgid ""
"All lookups are cached to `~/.yard/yri_cache` for quicker lookups the "
"second\n"
"time onward."
msgstr ""
"全ての検索は、２度目の検索をより早くする為に、\n"
"`~/.yard/yri_cache`にキャッシュされる。"

#: ../docs/WhatsNew.md:872
msgid ""
"Added `yardoc --default-return` and `yardoc --hide-void-return` (0.5.0)\n"
"-----------------------------------------------------------------------"
msgstr ""
"`yardoc --default-return`と`yardoc --hide-void-return`が追加された (0.5.0)\n"
"-----------------------------------------------------------------------"

#: ../docs/WhatsNew.md:875
msgid ""
"YARD defaults to displaying (Object) as the default return type of any\n"
"method that has not declared a @return tag. To customize the default\n"
"return type, you can specify:"
msgstr ""
"YARDは@returnタグで宣言されなかった、\n"
"任意のデフォルトのメソッドの型を返し表示する事をデフォルトにする。\n"
"デフォルトの返す型をカスタマイズするには、以下のように指定する:"

#: ../docs/WhatsNew.md:879
msgid "    $ yardoc --default-return 'MyDefaultType'"
msgstr "    $ yardoc --default-return 'MyDefaultType'"

#: ../docs/WhatsNew.md:881
msgid "You can also use the empty string to list no return type."
msgstr "あなたは、返す型が無いのを記述するのに、空の文字列を利用できる。"

#: ../docs/WhatsNew.md:883
msgid ""
"In addition, you can use --hide-void-return to ignore any method that\n"
"defines itself as a void type by: `@return [void]`"
msgstr ""
"さらに、あなたは、`@return [void]`でそれ自身をvoidの型として定義する\n"
"任意のメソッドに--hide-void-returnを利用できる。"

#: ../docs/WhatsNew.md:886
msgid ""
"Multiple syntax highlighting language support (0.5.0)\n"
"-----------------------------------------------------"
msgstr ""
"複数の構文ハイライト用の言語サポート (0.5.0)\n"
"-----------------------------------------------------"

#: ../docs/WhatsNew.md:889
msgid ""
"YARD now supports the ability to specify a language type for code blocks in\n"
"docstrings. Although no actual highlighting support is added for any "
"language\n"
"but Ruby, you can add your own support by writing your own helper method:"
msgstr ""
"YARDはdocstringの中のコードブロック用に、\n"
"言語の型を指定する機能をサポートするようになった。\n"
"実際のハイライトサポートは、全ての言語に追加されているわけではないが\n"
"Rubyは、あなた自身がhelperメソッドを書くことによってサポートを追加する事ができる。"

#: ../docs/WhatsNew.md:893
msgid ""
"    # Where LANGNAME is the language:\n"
"    def html_syntax_highlight_LANGNAME(source)\n"
"      # return highlighted HTML\n"
"    end"
msgstr ""
"    # LANGNAMEがlanguageの場所:\n"
"    def html_syntax_highlight_LANGNAME(source)\n"
"      # ハイライトされたHTMLを返す\n"
"    end"

#: ../docs/WhatsNew.md:898
msgid ""
"To use this language in code blocks, prefix the block with `!!!LANGNAME`:"
msgstr ""
"コードブロックでこの言語を利用するには、次のように`!!!LANGNAME`を用い前に置"
"く。"

#: ../docs/WhatsNew.md:900
msgid ""
"    !!!plain\n"
"    !!!python\n"
"    def python_code(self):\n"
"      return self"
msgstr ""
"    !!!plain\n"
"    !!!python\n"
"    def python_code(self):\n"
"      return self"

#: ../docs/WhatsNew.md:905
msgid ""
"By the same token. you can now use `!!!plain` to ignore highlighting for\n"
"a specific code block."
msgstr ""
"同じトークンで、\n"
"あなたは特定のコードブロック用のハイライトを無視する為に`!!!plain`が利用でき"
"るようになった。"

#: ../docs/WhatsNew.md:908
msgid ""
"New .yardoc format (0.5.0)\n"
"--------------------------"
msgstr ""
"新しい.yardocフォーマット (0.5.0)\n"
"--------------------------"

#: ../docs/WhatsNew.md:911
msgid ""
"To make the above yri support possible, the .yardoc format was redesigned\n"
"to be a directory instead of a file. YARD can still load old .yardoc files,\n"
"but they will be automatically upgraded if re-saved. The new .yardoc format\n"
"does have a larger memory footprint, but this will hopefully be optimized\n"
"downward."
msgstr ""
"上のyriサポートを可能にする為に、\n"
".yardocフォーマットはファイルの代わりにディレクトリに記録される事になった。\n"
"YARDは尚、古い.yardocファイルをロードできるが、\n"
"しかし、それは、再セーブした場合、自動的に上書きされるだろう。\n"
"新しい.yaradocフォーマットは、より大きいメモリ足跡をもっているが\n"
"しかしこれは、恐らく下方修正されるだろう。"

#: ../docs/WhatsNew.md:917
msgid ""
"Support for yard-doc-* gem packages as hosted .yardoc dbs (0.5.1)\n"
"-----------------------------------------------------------------"
msgstr ""
".yardoc dbs でホストされたyard-doc-* gem パッケージ用のサポート\n"
"-----------------------------------------------------------------"

#: ../docs/WhatsNew.md:920
msgid ""
"You can now install special YARD plugin gems titled yard-doc-NAME to get\n"
"packaged a .yardoc database. This will enable yri lookups or building docs\n"
"for the gem without the code."
msgstr ""
"あなたは、パッケージされた.yardocデータベースを取得する為に\n"
"yard-doc-NAMEと名付けられた特殊なYARDプラグインのgemをインストールできるよう"
"になった。\n"
"これは、コード無しでgem用のdocstringをyriで検索、又は、ビルドを可能にするだろ"
"う。"

#: ../docs/WhatsNew.md:924
msgid ""
"One main use for this is the `yard-doc-core` package, which enabled yri\n"
"support for Ruby core classes (stdlib coming soon as `yard-doc-stdlib`).\n"
"To install it, simply:"
msgstr ""
"これの主なものとしては、`yard-doc-core`パッケージである。\n"
"これはRubyのコアクラス用のyriサポートを有効化する\n"
"(標準ライブラリは`yard-doc-stdlib`として近日登場予定)\n"
"簡単にインストールするには:"

#: ../docs/WhatsNew.md:928
msgid ""
"    $ sudo gem install yard-doc-core\n"
"    # now you can use:\n"
"    $ yri String"
msgstr ""
"    $ sudo gem install yard-doc-core\n"
"    # あなたは次のコマンドを使えるようになった:\n"
"    $ yri String"

#: ../docs/WhatsNew.md:932
msgid ""
"This will by default install the 1.9.1 core library. To install a library\n"
"for a specific version of Ruby, use the `--version` switch on gem:"
msgstr ""
"これは、1.9.1のコアライブラリをデフォルトでインストールする。\n"
"Rubyの固有のバージョンのライブラリをインストールするには、\n"
"次のように、gemで`--version`引数を利用する:"

#: ../docs/WhatsNew.md:935
msgid "    $ sudo gem install --version '= 1.8.6' yard-doc-core"
msgstr "    $ sudo gem install --version '= 1.8.6' yard-doc-core"

#: ../docs/WhatsNew.md:937
msgid ""
"Support for extra search paths in `yri` (0.5.1)\n"
"-----------------------------------------------"
msgstr ""
"`yri`で追加の検索パスをサポートされた (0.5.1)\n"
"-----------------------------------------------"

#: ../docs/WhatsNew.md:940
msgid ""
"You can now add custom paths to non-gem .yardoc files\n"
"by adding them as newline separated paths in `~/.yard/yri_search_paths`."
msgstr ""
"あなたは`~/.yard/yri_search_paths`の中に\n"
"改行に区切られたパスとして追加する事によって\n"
"gem無しの.yardocファイルに\n"
"カスタムパスを追加できるようになった。"

#: ../docs/WhatsNew.md:943
msgid ""
"Generating HTML docs now adds frames view (0.5.3)\n"
"-------------------------------------------------"
msgstr ""
"HTMLのdocstringを生成するとフレームの一覧が追加されるようになった (0.5.3)\n"
"-------------------------------------------------"

#: ../docs/WhatsNew.md:946
msgid ""
"`yardoc` will now create a `frames.html` file when generating HTML "
"documents\n"
"which allows the user to view documentation inside frames, for those users "
"who\n"
"still find frames beneficial."
msgstr ""
"`yardoc`はHTMLドキュメントを生成する時、\n"
"`frames.html`ファイルを作成できるようになった。\n"
"これは、フレームで探すのが便利だとするユーザーの為に、\n"
"フレーム内のドキュメントを一覧する為にユーザーを受け入れる。"

#: ../docs/WhatsNew.md:950
msgid ""
"Tree view for class list (0.5.3)\n"
"--------------------------------"
msgstr ""
"クラスリスト用のツリー 一覧 (0.5.3)\n"
"--------------------------------"

#: ../docs/WhatsNew.md:953
msgid ""
"The class list now displays as an expandable tree view to better organized "
"an\n"
"otherwise cluttered namespace. If you properly namespace your less "
"important\n"
"classes (like Rails timezone classes), they will not take up space in the\n"
"class list unless the user looks for them."
msgstr ""
"クラスリストは別の乱雑なnamespaceをより体型化する為に\n"
"拡張可能なツリー 一覧を表示できるようになった。\n"
"あなたが重要でないクラスをnamespaceにした場合、\n"
"(Railsのtimezome classのような)\n"
"それら(重要でないクラス)は、ユーザーが検索しなければ、\n"
"クラスリストのスペースを専有しない。"

#: ../docs/WhatsNew.md:958
msgid ""
"Ability to specify markup format of extra files (0.5.3)\n"
"-------------------------------------------------------"
msgstr ""
"追加のファイルのマークアップフォーマットを指定する為の機能 (0.5.3)\n"
"-------------------------------------------------------"

#: ../docs/WhatsNew.md:961
msgid ""
"You can now specify the markup format of an extra file (like README) at the\n"
"top of the file with a shebang-like line:"
msgstr ""
"あなたは、次のshebangのような行を用いファイルのトップで\n"
"追加のファイルの(READMEのような)固有のマークアップフォーマットを指定できるよ"
"うになった。"

#: ../docs/WhatsNew.md:964
msgid ""
"    #!textile\n"
"    contents here"
msgstr ""
"    #!textile\n"
"    contents here"

#: ../docs/WhatsNew.md:967
msgid ""
"The above file contents will be rendered with a textile markup engine\n"
"(eg. RedCloth)."
msgstr "上のファイルの内容は、textileマークアップエンジンで表示される(つまりRedCloth)。"

#: ../docs/WhatsNew.md:970
msgid ""
"Keyboard shortcuts for default HTML template (0.5.4)\n"
"----------------------------------------------------"
msgstr ""
"Keyboard shortcuts for default HTML template (0.5.4)\n"
"----------------------------------------------------"

#: ../docs/WhatsNew.md:973
msgid ""
"You can now access the \"Class List\", \"Method List\" and \"File List\" "
"with the\n"
"'c', 'm' and 'f' keyboard shortcuts in the default HTML template, allowing\n"
"for keyboard-only navigation around YARD documentation."
msgstr ""
"あなたは、\n"
"デフォルトのHTMLテンプレートで'c', 'm', 'f'のキーボードショートカットを用"
"い、\n"
"\"Class List\",\"Method List\",\"File List\"にアクセスできるようになった。\n"
"これは、YARDドキュメントの周りのキーボードだけのナビゲーションを受入れる。"

#: ../docs/WhatsNew.md:977
msgid ""
"API for registering custom parsers (0.5.6)\n"
"------------------------------------------"
msgstr ""
"カスタムパーサーの記録用API (0.5.6)\n"
"------------------------------------------"

#: ../docs/WhatsNew.md:980
msgid ""
"You can now register parsers for custom source languages by calling the\n"
"following method:"
msgstr ""
"あなたは、次のメソッドの様に呼び出される事で、\n"
"カスタムソース言語用のパーサーを記録できるようになった。"

#: ../docs/WhatsNew.md:983
msgid "    SourceParser.register_parser_type(:java, MyJavaParser, 'java')"
msgstr "    SourceParser.register_parser_type(:java, MyJavaParser, 'java')"

#: ../docs/WhatsNew.md:985
msgid ""
"The parser class MyJavaParser should be a subclass of {YARD::Parser::Base},\n"
"and the last argument is a set of extensions (string, array or regexp). You\n"
"can read more about registering parsers at the {YARD::Parser::SourceParser}\n"
"class documentation."
msgstr ""
"パーサークラスMyJavaParserは、{YARD::Parser::Base}のサブクラスになり、\n"
"最後の引数は、拡張のグループ(string, array or regexp)になる。\n"
"{YARD::Parser::SourceParser} クラスのドキュメントでパーサーを記録する方法につ"
"いて、\n"
"詳細を見る事が出来る。"

#: ../docs/WhatsNew.md:991
msgid ""
"What's New in 0.4.x?\n"
"===================="
msgstr ""
"What's New in 0.4.x?\n"
"===================="

#: ../docs/WhatsNew.md:994
msgid ""
"1. **New templating engine and templates**\n"
"2. **yardoc `--query` argument**\n"
"3. **Greatly expanded API documentation**\n"
"4. **New plugin support**\n"
"5. **New tags (@abstract, @private)**\n"
"6. **Default rake task is now `rake yard`**"
msgstr ""
"1. **新しいテンプレートエンジンとテンプレート**\n"
"2. **yardoc `--query` 引数**\n"
"3. **Greatly expanded API ドキュメント**\n"
"4. **新しいプラグインのサポート**\n"
"5. **新しいタグ(@abstract, @private)**\n"
"6. **デフォルトのrake taskは`rake yard`コマンドになった**"

#: ../docs/WhatsNew.md:1001
msgid ""
"New templating engine and templates\n"
"-----------------------------------"
msgstr ""
"新しいテンプレートエンジンとテンプレート\n"
"-----------------------------------"

#: ../docs/WhatsNew.md:1004
msgid ""
"The templates were redesigned, most notably removing the ugly frameset, "
"adding\n"
"search to the class/method lists, simplifying the layout and making things\n"
"generally prettier. You should also notice that more tags are now visible "
"in\n"
"the templates such as @todo, the new @abstract and @note tags and some "
"others\n"
"that existed but were previously omitted from the generated documentation."
msgstr ""
"テンプレートは再設計された特に汚いフレームセットを削除しなければならない、\n"
"クラス/メソッドのリストに検索を追加する。\n"
"レイアウトを簡単にしてほとんどの場合きれいに作成するようになった。\n"
"あなたがさらにタグで注意することは、\n"
"@todo,新しい@abstract,@noteタグそしていくつか存在する他のタグなどのように\n"
"テンプレートの中の可視性になった事である。\n"
"しかし既に生成されたドキュメントからは除外される。"

#: ../docs/WhatsNew.md:1010
msgid ""
"There is also a new templating engine (based on the tadpole templating "
"library)\n"
"to allow for much more user customization. You can read about it in\n"
"{file:docs/Templates.md}."
msgstr ""
"これは更なるユーザーのカスタマイズを受け入れる為の\n"
"新しいテンプレートエンジンでもある(tadpoleテンプレートライブラリベースの)\n"
"これらのについては{file:docs/Templates.md}の中で読む事ができる。"

#: ../docs/WhatsNew.md:1014
msgid ""
"yardoc `--query` argument\n"
"-------------------------"
msgstr ""
"yardoc `--query` 引数\n"
"-------------------------"

#: ../docs/WhatsNew.md:1017
msgid ""
"The yardoc command-line tool now supports queries to select which classes,\n"
"modules or methods to include in documentation based on their data or meta-"
"data.\n"
"For instance, you can now generate documentation for your \"public\" API "
"only by\n"
"adding \"@api public\" to each of your public API methods/classes and using\n"
"the following argument:"
msgstr ""
"yardocのコマンドラインツールは、\n"
"データやメタデータの基のドキュメントを組み込む為に、\n"
"そのクラス,モジュールやメソッドで選択するクエリーをサポートするようになっ"
"た。\n"
"例えば、あなたは、個々のpublic API メソッド/クラスに\n"
"\"@api public\"を追加するだけで、自分の\"public\"API用にドキュメントを生成で"
"きるようになった。\n"
"次の様に、引数を用いる:"

#: ../docs/WhatsNew.md:1023
msgid "    --query '@api.text == \"public\"'"
msgstr "    --query '@api.text == \"public\"'"

#: ../docs/WhatsNew.md:1025
msgid "More information on queries is in the {file:README.md}."
msgstr "クエリーの詳細な情報は{file:README.md}で"

#: ../docs/WhatsNew.md:1027
msgid ""
"Greatly expanded API documentation\n"
"----------------------------------"
msgstr ""
"非常に拡張されたAPIドキュメント\n"
"----------------------------------"

#: ../docs/WhatsNew.md:1030
msgid ""
"Last release focused on many how-to and architecture documents to explain\n"
"the design of YARD, but many of the actual API classes/methods were still\n"
"left undocumented. This release marks a focus on getting YARD's own "
"documentation\n"
"up to par so that it can serve as an official reference on the recommended\n"
"conventions to use when documenting code."
msgstr ""
"最後のリリースは沢山の操作手順とYARDのデザインを詳細に説明する為の\n"
"アーキテクチャドキュメントに焦点を合わせた。\n"
"しかし、実際のAPIクラス/メソッドの大部分は、いまだ記述されていない。\n"
"このリリースは、標準的なYARD独自のドキュメントの取得に焦点を当てている。\n"
"なのでこれは、コードを書く時に利用する推奨された公式のリファレンスとして提供"
"できる。"

#: ../docs/WhatsNew.md:1036
msgid ""
"New plugin support\n"
"------------------"
msgstr ""
"新しいプラグインサポート\n"
"------------------"

#: ../docs/WhatsNew.md:1039
msgid ""
"YARD now supports loading of plugins via RubyGems. Any gem named `yard-*` "
"or\n"
"`yard_*` will now be loaded when YARD starts up. Note that the '-' "
"separator\n"
"is the recommended naming scheme."
msgstr ""
"YARDは、RubyGems経由でプラグインのロードをサポートできるようになった。\n"
"`yard-*`や`yard_*`で名付けられた任意のgemは、YARDが起動する時にロードされるだ"
"ろう。\n"
"次の事に留意する。'-'区切りは、推奨された命名スキームである。"

#: ../docs/WhatsNew.md:1043
msgid ""
"To ignore plugins, add the gem names to `~/.yard/ignored_plugins` on "
"separate\n"
"lines (or separated by whitespace)."
msgstr ""
"プラグインを無視するには、\n"
"`~/.yard/ignored_plugins`ファイルで行区切り(又は、スペース区切りで)\n"
"でgem名を追加する。"

#: ../docs/WhatsNew.md:1046
msgid ""
"New tags (@abstract, @private)\n"
"------------------------------"
msgstr ""
"新しいタグ(@abstract, @private)\n"
"------------------------------"

#: ../docs/WhatsNew.md:1049
msgid ""
"Two new tags were added to the list of builtin meta-tags in YARD. "
"`@abstract`\n"
"marks a class/module/method as abstract while `@private` marks an object\n"
"as \"private\". The latter tag is used in situations where an object is "
"public\n"
"due to Ruby's own visibility limitations (constants, classes and modules\n"
"can never be private) but not actually part of your public API. You should\n"
"use this tag sparingly, as it is not meant to be an equivalent to RDoc's\n"
"`:nodoc:` tag. Remember, YARD recommends documenting private objects too.\n"
"This tag exists so that you can create a query (`--query !@private`) to\n"
"ignore all of these private objects in your documentation. You can also\n"
"use the new `--no-private` switch, which is a shortcut to the "
"aforementioned\n"
"query. You can read more about the new tags in the {file:docs/GettingStarted."
"md}\n"
"guide."
msgstr ""
"二つの新しいタグが、YARDの中の組み込みのメタタグのリストに追加された。\n"
"`@abstract`は、概要(abstract)として、class/module/methodをマークする。\n"
"さらに、`@private`は、\"private\"として、オブジェクトをマークする。\n"
"後者のタグは、\n"
"後のタグはオブジェクトがRuby自身の可視性の制約の為に\n"
"実際のあなたのpublic APIの一部ではないにしてもpublic相当の場所で利用される\n"
"(定数は、クラス、モジュールはプライベートにはできない)\n"
"あなたは、慎重にこのタグを利用すべきである。\n"
"RDocが`:nodoc:`タグと同様であるという意味ではない。\n"
"YARDはprivate オブジェクトの記述も推奨する事を覚えておいてほしい。\n"
"このタグは、あなたが、自分のドキュメントでこれらのprivateオブジェクトの全てを無視する為に\n"
"クエリー(`--query !@private`)を作成できるように存在する。\n"
"あなたは新しい`--no-private`引数を利用する事もできる。\n"
"これは前述のクエリーへのショートカットである。\n"
"さらに新しいタグについて知りたい場合は、 {file:docs/GettingStarted.md} のガイドで読むことができる。"

#: ../docs/WhatsNew.md:1062
msgid ""
"Default rake task is now `rake yard`\n"
"------------------------------------"
msgstr ""
"デフォルトのrake taskは、`rake yard`となった\n"
"------------------------------------"

#: ../docs/WhatsNew.md:1065
msgid ""
"Not a big change, but anyone using the default \"rake yardoc\" task should\n"
"update their scripts:"
msgstr ""
"大きな変更ではないが、誰もが使うデフォルトの\"rake yardoc\" taskは、\n"
"次のスクリプトに変更された。"

#: ../docs/WhatsNew.md:1068
msgid ""
"[http://github.com/lsegal/yard/commit/"
"ad38a68dd73898b06bd5d0a1912b7d815878fae0](http://github.com/lsegal/yard/"
"commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0)"
msgstr "[http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0](http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0)"

#: ../docs/WhatsNew.md:1071
msgid ""
"What's New in 0.2.3.x?\n"
"======================"
msgstr ""
"What's New in 0.2.3.x?\n"
"======================"

#: ../docs/WhatsNew.md:1074
msgid ""
"1. **Full Ruby 1.9 support**\n"
"2. **New parser code and handler API for 1.9**\n"
"3. **A new `@overload` tag**\n"
"4. **Better documentation**\n"
"5. **Template changes and bug fixes**"
msgstr ""
"1. **完全なRuby 1.9でのサポート**\n"
"2. **1.9用の新しいパーサーのコードとハンドラーAPI**\n"
"3. **新しい `@overload` タグ**\n"
"4. **より良いドキュメント**\n"
"5. **テンプレートの変更とバグの修正**"

#: ../docs/WhatsNew.md:1080
msgid ""
"Full Ruby 1.9 support\n"
"---------------------"
msgstr ""
"完全なRuby1.9のサポート\n"
"---------------------"

#: ../docs/WhatsNew.md:1083
msgid ""
"YARD's development actually focuses primarily on 1.9 from the get-go, so it "
"is\n"
"not an afterthought. All features are first implemented for compatibility "
"with\n"
"1.9, but of course all functionality is also tested in 1.8.x. YARD 0.2.2 "
"was\n"
"mostly compatible with 1.9, but the new release improves and extends in "
"certain\n"
"areas where compatibility was lacking. The new release should be fully "
"functional\n"
"in Ruby 1.9."
msgstr ""
"YARDの開発の実際の焦点は最初から1.9上が主で、結果として1.9になった訳ではな"
"い。\n"
"全ての機能は、始めに1.9互換で実装されるが、もちろん1.8.xでもテストされてい"
"る。\n"
"YARD 0.2.2は、大部分が1.9を用い互換性があるが、\n"
"新リリースは、互換性が欠けていた所を範囲を拡張する。\n"
"新しいリリースは、Ruby 1.9で完全に機能するはずである。"

#: ../docs/WhatsNew.md:1090
msgid ""
"New parser code and handler API for 1.9\n"
"---------------------------------------"
msgstr ""
"1.9用の新しいパーサーコードとハンドラーAPI\n"
"---------------------------------------"

#: ../docs/WhatsNew.md:1093
msgid ""
"Using Ruby 1.9 also gives YARD the advantage of using the new `ripper` "
"library\n"
"which was added to stdlib. The ripper parser is Ruby's official answer to\n"
"projects like ParseTree and ruby2ruby. Ripper allows access to the AST as "
"it\n"
"is parsed by the Ruby compiler. This has some large benefits over "
"alternative\n"
"projects:"
msgstr ""
"Ruby1.9の使用で、YARDの標準ライブラリに追加された\n"
"新しい`ripper`ライブラリの利点が与えられる。\n"
"ripperパーサーは、\n"
"ParseTreeとruby2rubyのように動かす為の\n"
"Rubyの公式な回答である。\n"
"Ripperは、Rubyコンパイラによって解析されるASTとしてアクセスを受入れる。\n"
"これは、別のプロジェクトにくらべていくつかの大きな恩恵がある。"

#: ../docs/WhatsNew.md:1099
msgid ""
"  1. It is officially supported and maintained by the Ruby core team.\n"
"  2. The AST is generated directly from the exact same code that drives the\n"
"     compiler, meaning anything that compiles is guaranteed to generate the\n"
"     equivalent AST.\n"
"  3. It needs no hacks, gems or extra libs and works out of the box in 1.9.\n"
"  4. It's *fast*."
msgstr ""
"  1. 公式にRubyのコアチームによってサポートとメンテナンスされている。\n"
"  2. ASTはコンパイラを起動する同じコードから直接生成され、  \n"
"     コンパイルがASTと同様に生成する為に保証されるどんなものでも意味があ"
"る。\n"
"  3. 道具を必要としない。gemや、追加のライブラリ、1.9の箱の外の仕事を\n"
"  4. 速い"

#: ../docs/WhatsNew.md:1106
msgid ""
"Having the AST means that developers looking to extend YARD have much "
"better\n"
"access to the parsed code than in previous versions. The only caveat is "
"that\n"
"this library is not back-compatible to 1.8.x. Because of this, there are\n"
"subtle changes to the handler extension API that developers use to extend "
"YARD.\n"
"Namely, there is now a standard API for 1.9 and a \"legacy\" API that can "
"run in\n"
"both 1.8.x and 1.9 if needed. A developer can still use the legacy API to "
"write\n"
"handlers that are compatible for both 1.8.x and 1.9 in one shot, or decide "
"to\n"
"implement the handler using both APIs. Realize that the benefit of using the "
"new\n"
"API means 1.9 users will get a 2.5x parsing speed increase over running the "
"legacy\n"
"handlers (this is *in addition to* the ~1.8x speed increase of using YARV "
"over MRI)."
msgstr ""
"ASTを持つ事は、開発者が拡張されたYARDがより多くの\n"
"(前のバージョンより解析されたコードから)アクセスを持つので探す事を意味す"
"る。\n"
"\n"
"誤解を生まないよう注意するが、\n"
"このライブラリは、1.8.xの後方互換ではない。\n"
"これは何故かというと、\n"
"開発者がYARDを拡張する為に利用する\n"
"ハンドラーの拡張APIに難解な変更があるからである。\n"
"即ち、必要なら、1.8.xと1.9両方で起動できる1.9用の標準APIと\"legacy\"APIになっ"
"た。\n"
"開発者は、1.8.xと1.9の両方のハンドラーを一回で書くのに、legacyAPIを利用でき"
"る。\n"
"又、両方のAPIによってハンドラーを実装する事を決めた。\n"
"1.9ユーザーの新しいAPIの手法を使う事によっての恩恵は、\n"
"レガシーハンドラーの起動より解析するスピードが2.5x倍増大すると理解する。\n"
"(これで、 *さらに*  ~1.8xのスピードがMRIでYARVを使う事によって増大する)"

#: ../docs/WhatsNew.md:1117
msgid ""
"A new `@overload` tag\n"
"---------------------"
msgstr ""
"新しい`@overload`タグ\n"
"---------------------"

#: ../docs/WhatsNew.md:1120
msgid ""
"The new `@overload` tag enables users to document methods that take "
"multiple\n"
"parameters depending on context. This is basically equivalent to RDoc's call-"
"seq,\n"
"but with a name that is more akin to the OOP concept of method overloading\n"
"that is actually being employed. Here's an example:"
msgstr ""
"新しい`@overload`タグは、ユーザーが\n"
"文脈の中で依存する複数のパラメータを取得するメソッドを記述する事を可能にす"
"る。\n"
"これは、基本的に、RDocのcall-seqと同様であるが、\n"
"オブジェクト指向の実際に用いられるオーバーロードのメソッドの概念により類似し"
"ている。\n"
"次のような例になる:"

#: ../docs/WhatsNew.md:1125
msgid ""
"      # @overload def to_html(html, autolink = true)\n"
"      #   This docstring describes the specific overload only.\n"
"      #   @param [String] html the HTML\n"
"      #   @param [Boolean] autolink whether or not to automatically link\n"
"      #     URL references\n"
"      # @overload def to_html(html, opts = {})\n"
"      #   @param [String] html the HTML\n"
"      #   @param [Hash] opts any attributes to add to the root HTML node\n"
"      def to_html(*args)\n"
"        # split args depending on context\n"
"      end"
msgstr ""
"      # @overload def to_html(html, autolink = true)\n"
"      #   This docstring describes the specific overload only.\n"
"      #   @param [String] html the HTML\n"
"      #   @param [Boolean] autolink whether or not to automatically link\n"
"      #     URL references\n"
"      # @overload def to_html(html, opts = {})\n"
"      #   @param [String] html the HTML\n"
"      #   @param [Hash] opts any attributes to add to the root HTML node\n"
"      def to_html(*args)\n"
"        # split args depending on context\n"
"      end"

#: ../docs/WhatsNew.md:1137
msgid ""
"As you can see each overload takes its own nested tags (including a "
"docstring)\n"
"as if it were its own method. This allows \"virtual\" overloading behaviour "
"at\n"
"the API level to make Ruby look like overload-aware languages without "
"caring\n"
"about the implementation details required to add the behaviour."
msgstr ""
"上のオーバーロードは、それが独自のメソッドのように\n"
"入れ子になった自身のタグを取得する(docstringを含んでいる)。\n"
"これは、振舞いを追加するのに必要とされる詳細の実装について気にすることな"
"く、\n"
"Rubyをオーバーロードに考慮した言語のように構成する為に、\n"
"APIレベルで\"仮の\"オーバーロードの挙動も受入れる。"

#: ../docs/WhatsNew.md:1142
msgid ""
"It is still recommended practice, however, to stay away from overloading "
"when\n"
"possible and document the types of each method's real parameters. This "
"allows\n"
"toolkits making use of YARD to get accurate type information for your "
"methods,\n"
"for instance, allowing IDE autocompletion. There are, of course, situations\n"
"where overload just makes more sense."
msgstr ""
"これはまだ推奨案だが、\n"
"可能な時はオーバーロードを使わないで、実際の引数の個々のメソッドの型を記述す"
"る。\n"
"これで、貴方のメソッド用に正確な型情報を取得する為にYARDのツールキットの使用"
"が受入れられる。\n"
"例えば、IDEの自動補完をがある。\n"
"これは勿論、オーバーロードでより多くの意味を成す場合もある。"

#: ../docs/WhatsNew.md:1148
msgid ""
"Better documentation\n"
"--------------------"
msgstr ""
"より良いドキュメント\n"
"--------------------"

#: ../docs/WhatsNew.md:1151
msgid ""
"The first few iterations of YARD were very much a proof of concept. Few "
"people\n"
"were paying attention and it was really just pieced together to see what "
"was\n"
"feasible. Now that YARD is gaining interest, there are many developers that\n"
"want to take advantage of its extensibility support to do some really cool "
"stuff.\n"
"Considerable time was spent for this release documenting, at a high level, "
"what\n"
"YARD can do and how it can be done. Expect this documentation to be extended "
"and\n"
"improved in future releases."
msgstr ""
"最初のいくつかのYARDのイテレータはよくできた概念の証明である。\n"
"いくらかの人は、注意を払ったり、それが本当に可能なのか見る為に一緒に試したり"
"しただろう。\n"
"現在のYARDは関心を集めているので、\n"
"いくつかの本当にイカした拡張サポートがほしい沢山の開発者がいる。\n"
"かなりの時間、このリリースで、\n"
"YARDで何ができるのかとどのような方法が出来るのかハイレベルで記述するのに費や"
"された。\n"
"このドキュメントが拡張され、機能のリリースで改良されるよう事を期待する。"

#: ../docs/WhatsNew.md:1159
msgid ""
"Template changes and bug fixes\n"
"------------------------------"
msgstr ""
"テンプレートの変更とバグ修正\n"
"------------------------------"

#: ../docs/WhatsNew.md:1162
msgid ""
"Of course no new release would be complete without fixing the old broken "
"code.\n"
"Some tags existed but were not present in generated documentation. The "
"templates\n"
"were mostly fixed to add the major omitted tags. In addition to template "
"adjustments,\n"
"many parsing bugs were ironed out to make YARD much more stable with "
"existing projects\n"
"(Rails, HAML, Sinatra, Ramaze, etc.)."
msgstr ""
"勿論、新しいリリースで、古い壊れたコードを修正無しで仕上げられるだろう。\n"
"いくつか存在したタグが、生成されるドキュメントで存在しなくなった。\n"
"テンプレートは、メジャーだが抜かされたタグを追加する為に大部分が修正され"
"た。\n"
"テンプレートの調整に加えて、\n"
"既存のプロジェクトを用い(Rails, HAML, Sinatra, Ramaze, etc.)より安定したYARD"
"を作る為に、\n"
"多くの解析のバグは無視された。"

# YARD::ROOT
#: ../lib/yard.rb:5
msgid "The root path for YARD source libraries"
msgstr "YARDソースライブラリ用のルートパス"

# YARD::TEMPLATE_ROOT
#: ../lib/yard.rb:8
msgid "The root path for YARD builtin templates"
msgstr "YARDビルトインテンプレート用のルートパス"

# @deprecated
#: ../lib/yard.rb:11
msgid "Use {Config::CONFIG_DIR}"
msgstr "Use {Config::CONFIG_DIR}"

# YARD.parse
# YARD.parse_string
#: ../lib/yard.rb:14 ../lib/yard.rb:21
msgid "An alias to {Parser::SourceParser}'s parsing method"
msgstr "解析用の{Parser::SourceParser}メソッドへのエイリアス"

# @example Parse a glob of files
#: ../lib/yard.rb:18
msgid "YARD.parse('lib/**/*.rb')"
msgstr "YARD.parse('lib/**/*.rb')"

# @example
#: ../lib/yard.rb:18
msgid "tag|example|Parse a glob of files"
msgstr "ファイルのglobを解析する。"

# @see
#: ../lib/yard.rb:18
msgid "tag|see|Parser::SourceParser.parse"
msgstr "tag|see|Parser::SourceParser.parse"

# @example Parse a string of input
#: ../lib/yard.rb:25
msgid "YARD.parse_string('class Foo; end')"
msgstr "YARD.parse_string('class Foo; end')"

# @example
#: ../lib/yard.rb:25
msgid "tag|example|Parse a string of input"
msgstr "tag|example|入力の文字列を解析する"

# @see
#: ../lib/yard.rb:25
msgid "tag|see|Parser::SourceParser.parse_string"
msgstr "tag|see|Parser::SourceParser.parse_string"

# YARD.load_plugins
# YARD::Config.load_plugins
#: ../lib/yard.rb:30 ../lib/yard/config.rb:139
msgid ""
"Loads gems that match the name 'yard-*' (recommended) or 'yard_*' except\n"
"those listed in +~/.yard/ignored_plugins+. This is called immediately\n"
"after YARD is loaded to allow plugin support."
msgstr ""
"'yard-*'(推奨される)や'yard_*'の名前にマッチするgemをロードする。\n"
"これを除外するには、 +~/.yard/ignored_plugins+ の中に対象の名前を記述する。\n"
"これは、YARDがプラグインサポートをロードした後すぐに呼び出される。"

# YARD::CLI
#: ../lib/yard/autoload.rb:6 ../lib/yard/cli/command.rb:6
#: ../lib/yard/cli/command_parser.rb:6 ../lib/yard/cli/config.rb:6
#: ../lib/yard/cli/diff.rb:6 ../lib/yard/cli/gems.rb:6
#: ../lib/yard/cli/graph.rb:6 ../lib/yard/cli/help.rb:6
#: ../lib/yard/cli/i18n.rb:6 ../lib/yard/cli/list.rb:6
#: ../lib/yard/cli/server.rb:6 ../lib/yard/cli/stats.rb:6
#: ../lib/yard/cli/yardoc.rb:6 ../lib/yard/cli/yri.rb:6
msgid "Namespace for command-line interface components"
msgstr "コマンドラインインタフェースコンポーネント用のNamespace"

# YARD::CodeObjects
#: ../lib/yard/autoload.rb:22 ../lib/yard/code_objects/base.rb:22
#: ../lib/yard/code_objects/class_object.rb:22
#: ../lib/yard/code_objects/class_variable_object.rb:22
#: ../lib/yard/code_objects/constant_object.rb:22
#: ../lib/yard/code_objects/extended_method_object.rb:22
#: ../lib/yard/code_objects/extra_file_object.rb:22
#: ../lib/yard/code_objects/macro_object.rb:22
#: ../lib/yard/code_objects/method_object.rb:22
#: ../lib/yard/code_objects/module_object.rb:22
#: ../lib/yard/code_objects/namespace_object.rb:22
#: ../lib/yard/code_objects/proxy.rb:22
#: ../lib/yard/code_objects/root_object.rb:22
msgid ""
"A \"code object\" is defined as any entity in the Ruby language.\n"
"Classes, modules, methods, class variables and constants are the\n"
"major objects, but DSL languages can create their own by inheriting\n"
"from {CodeObjects::Base}."
msgstr ""
"\"code object\"は、Ruby言語の中の任意の構成要素が定義される。\n"
"クラスや、モジュール、メソッド、クラス変数、定数は重要なオブジェクトとな"
"る。\\n\n"
"そして、DSL言語は、{CodeObjects::Base}からの継承によって\n"
"DSL言語自身を作成できる。"

# YARD::Handlers
#: ../lib/yard/autoload.rb:58 ../lib/yard/handlers/base.rb:58
#: ../lib/yard/handlers/c/base.rb:58
#: ../lib/yard/handlers/c/handler_methods.rb:58
#: ../lib/yard/handlers/processor.rb:58 ../lib/yard/handlers/ruby/base.rb:58
#: ../lib/yard/handlers/ruby/dsl_handler.rb:58
#: ../lib/yard/handlers/ruby/dsl_handler_methods.rb:58
#: ../lib/yard/handlers/ruby/legacy/base.rb:58
#: ../lib/yard/handlers/ruby/legacy/dsl_handler.rb:58
msgid ""
"Handlers are called during the data processing part of YARD's\n"
"parsing phase. This allows YARD as well as any custom extension to\n"
"analyze source and generate {CodeObjects} to be stored for later use."
msgstr ""
"ハンドラーは、YARDの解析段階でデータの処理の間に呼び出される。\n"
"これは、ソースの解析や後で使う為に記録される{CodeObjects}を生成する為に\n"
"YARD本体も任意のカスタム拡張も受け入れる。"

# YARD::Handlers::Ruby
#: ../lib/yard/autoload.rb:62 ../lib/yard/handlers/c/base.rb:62
#: ../lib/yard/handlers/c/handler_methods.rb:62
msgid "CRuby Handlers"
msgstr "CRuby ハンドラー"

# YARD::Handlers::Ruby
#: ../lib/yard/autoload.rb:82 ../lib/yard/handlers/ruby/base.rb:82
#: ../lib/yard/handlers/ruby/dsl_handler.rb:82
#: ../lib/yard/handlers/ruby/dsl_handler_methods.rb:82
#: ../lib/yard/handlers/ruby/legacy/dsl_handler.rb:82
msgid "All Ruby handlers"
msgstr "全てのRubyハンドラー"

# YARD::Handlers::Ruby::Legacy
#: ../lib/yard/autoload.rb:83 ../lib/yard/handlers/ruby/legacy/base.rb:83
#: ../lib/yard/handlers/ruby/legacy/dsl_handler.rb:83
msgid "Handlers for old Ruby 1.8 parser"
msgstr "古いRuby1.8パーサー用のハンドラー"

# YARD::Templates
#: ../lib/yard/autoload.rb:134 ../lib/yard/i18n/locale.rb:134
#: ../lib/yard/i18n/message.rb:134 ../lib/yard/i18n/messages.rb:134
#: ../lib/yard/i18n/pot_generator.rb:134 ../lib/yard/i18n/text.rb:134
msgid "Namespace for internationalization (i18n)"
msgstr "国際化用のNamespace (i18n)"

# YARD::Parser
#: ../lib/yard/autoload.rb:144 ../lib/yard/parser/base.rb:144
#: ../lib/yard/parser/c/c_parser.rb:144
#: ../lib/yard/parser/c/comment_parser.rb:144
#: ../lib/yard/parser/c/statement.rb:144
#: ../lib/yard/parser/ruby/ast_node.rb:144
#: ../lib/yard/parser/ruby/legacy/ruby_parser.rb:144
#: ../lib/yard/parser/ruby/ruby_parser.rb:144
#: ../lib/yard/parser/source_parser.rb:144
msgid ""
"The parser namespace holds all parsing engines used by YARD.\n"
"Currently only Ruby and C (Ruby) parsers are implemented."
msgstr ""
"ParserのnamespaceはYARDによって利用される全てのパーサーエンジンをサポートす"
"る。\n"
"今の所、RubyとC(Ruby)パーサーだけ実装されている。"

# YARD::Parser::Ruby
#: ../lib/yard/autoload.rb:147 ../lib/yard/parser/c/c_parser.rb:147
#: ../lib/yard/parser/c/comment_parser.rb:147
#: ../lib/yard/parser/c/statement.rb:147
msgid "CRuby Parsing components"
msgstr "CRubyのパーサーの構成"

# YARD::Parser::Ruby
#: ../lib/yard/autoload.rb:156 ../lib/yard/parser/ruby/ast_node.rb:156
#: ../lib/yard/parser/ruby/legacy/ruby_parser.rb:156
#: ../lib/yard/parser/ruby/ruby_parser.rb:156
msgid "Ruby parsing components."
msgstr "Rubyのパーサーの構成"

# YARD::Parser::Ruby::Legacy
#: ../lib/yard/autoload.rb:157 ../lib/yard/parser/ruby/legacy/ruby_lex.rb:157
#: ../lib/yard/parser/ruby/legacy/ruby_parser.rb:157
#: ../lib/yard/parser/ruby/legacy/statement.rb:157
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:157
#: ../lib/yard/parser/ruby/legacy/token_list.rb:157
msgid "Handles Ruby parsing in Ruby 1.8."
msgstr "Ruby1.8で利用されるパーサー処理"

# YARD::Rake
#: ../lib/yard/autoload.rb:176 ../lib/yard/rake/yardoc_task.rb:176
msgid "Holds Rake tasks used by YARD"
msgstr "YARDによって利用されるRake taskを持つ"

# YARD::Serializers
#: ../lib/yard/autoload.rb:180 ../lib/yard/serializers/base.rb:180
#: ../lib/yard/serializers/file_system_serializer.rb:180
#: ../lib/yard/serializers/process_serializer.rb:180
#: ../lib/yard/serializers/stdout_serializer.rb:180
#: ../lib/yard/serializers/yardoc_serializer.rb:180
msgid "Namespace for components that serialize to various endpoints"
msgstr "様々な出力でシリアライズする構成用のNamespace"

# YARD::Server
#: ../lib/yard/autoload.rb:188 ../lib/yard/server.rb:188
#: ../lib/yard/server/adapter.rb:188 ../lib/yard/server/commands/base.rb:188
#: ../lib/yard/server/commands/display_file_command.rb:188
#: ../lib/yard/server/commands/display_object_command.rb:188
#: ../lib/yard/server/commands/frames_command.rb:188
#: ../lib/yard/server/commands/library_command.rb:188
#: ../lib/yard/server/commands/library_index_command.rb:188
#: ../lib/yard/server/commands/list_command.rb:188
#: ../lib/yard/server/commands/search_command.rb:188
#: ../lib/yard/server/commands/static_file_command.rb:188
#: ../lib/yard/server/doc_server_helper.rb:188
#: ../lib/yard/server/doc_server_serializer.rb:188
#: ../lib/yard/server/library_version.rb:188
#: ../lib/yard/server/rack_adapter.rb:188 ../lib/yard/server/router.rb:188
#: ../lib/yard/server/static_caching.rb:188
#: ../lib/yard/server/webrick_adapter.rb:188
msgid ""
"Namespace for classes and modules that handle serving documentation over HTTP"
msgstr "HTTP経由でドキュメント作成の提供するクラスやモジュールの為のNamespace"

# YARD::Server
#: ../lib/yard/autoload.rb:190 ../lib/yard/server.rb:190
#: ../lib/yard/server/adapter.rb:190 ../lib/yard/server/commands/base.rb:190
#: ../lib/yard/server/commands/display_file_command.rb:190
#: ../lib/yard/server/commands/display_object_command.rb:190
#: ../lib/yard/server/commands/frames_command.rb:190
#: ../lib/yard/server/commands/library_command.rb:190
#: ../lib/yard/server/commands/library_index_command.rb:190
#: ../lib/yard/server/commands/list_command.rb:190
#: ../lib/yard/server/commands/search_command.rb:190
#: ../lib/yard/server/commands/static_file_command.rb:190
#: ../lib/yard/server/doc_server_helper.rb:190
#: ../lib/yard/server/doc_server_serializer.rb:190
#: ../lib/yard/server/library_version.rb:190
#: ../lib/yard/server/rack_adapter.rb:190 ../lib/yard/server/router.rb:190
#: ../lib/yard/server/static_caching.rb:190
#: ../lib/yard/server/webrick_adapter.rb:190
msgid ""
"== Implementing a Custom Server\n"
"To customize the YARD server, see the {Adapter} and {Router} classes."
msgstr ""
"== カスタムサーバーの実装\n"
"YARDサーバーをカスタマイズするには、{Adapter}や{Router}クラス参照。"

# YARD::Server
#: ../lib/yard/autoload.rb:193 ../lib/yard/server.rb:193
#: ../lib/yard/server/adapter.rb:193 ../lib/yard/server/commands/base.rb:193
#: ../lib/yard/server/commands/display_file_command.rb:193
#: ../lib/yard/server/commands/display_object_command.rb:193
#: ../lib/yard/server/commands/frames_command.rb:193
#: ../lib/yard/server/commands/library_command.rb:193
#: ../lib/yard/server/commands/library_index_command.rb:193
#: ../lib/yard/server/commands/list_command.rb:193
#: ../lib/yard/server/commands/search_command.rb:193
#: ../lib/yard/server/commands/static_file_command.rb:193
#: ../lib/yard/server/doc_server_helper.rb:193
#: ../lib/yard/server/doc_server_serializer.rb:193
#: ../lib/yard/server/library_version.rb:193
#: ../lib/yard/server/rack_adapter.rb:193 ../lib/yard/server/router.rb:193
#: ../lib/yard/server/static_caching.rb:193
#: ../lib/yard/server/webrick_adapter.rb:193
msgid ""
"== Rack Middleware\n"
"If you want to use the YARD server as a Rack middleware, see the "
"documentation\n"
"in {RackMiddleware}."
msgstr ""
"== Rack Middleware\n"
"あなたがRack MiddlewareのようにYARDサーバーを使いたい場合、\n"
"{RackMiddleware}ドキュメントを参照。"

# YARD::Server::Commands
#: ../lib/yard/autoload.rb:201 ../lib/yard/server/commands/base.rb:201
#: ../lib/yard/server/commands/display_file_command.rb:201
#: ../lib/yard/server/commands/display_object_command.rb:201
#: ../lib/yard/server/commands/frames_command.rb:201
#: ../lib/yard/server/commands/library_command.rb:201
#: ../lib/yard/server/commands/library_index_command.rb:201
#: ../lib/yard/server/commands/list_command.rb:201
#: ../lib/yard/server/commands/search_command.rb:201
#: ../lib/yard/server/commands/static_file_command.rb:201
msgid ""
"Commands implement specific kinds of server responses which are routed\n"
"to by the {Router} class. To implement a custom command, subclass {Commands::"
"Base}."
msgstr ""
"コマンドは特定のサーバーの応答のような実装。\n"
"そして、{Router}クラスによって送られる。\n"
"カスタムコマンドを実装する為には、{Commands::Base}サブクラス参照。"

# YARD::Tags
#: ../lib/yard/autoload.rb:229 ../lib/yard/tags/default_factory.rb:229
#: ../lib/yard/tags/default_tag.rb:229 ../lib/yard/tags/directives.rb:229
#: ../lib/yard/tags/library.rb:229 ../lib/yard/tags/option_tag.rb:229
#: ../lib/yard/tags/overload_tag.rb:229 ../lib/yard/tags/ref_tag.rb:229
#: ../lib/yard/tags/ref_tag_list.rb:229 ../lib/yard/tags/tag.rb:229
#: ../lib/yard/tags/tag_format_error.rb:229
msgid "Namespace for Tag components"
msgstr "タグの構成の為のNamespace"

# YARD::Templates
#: ../lib/yard/autoload.rb:249 ../lib/yard/templates/engine.rb:249
#: ../lib/yard/templates/erb_cache.rb:249
#: ../lib/yard/templates/helpers/html_syntax_highlight_helper.rb:249
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:249
#: ../lib/yard/templates/helpers/module_helper.rb:249
#: ../lib/yard/templates/helpers/text_helper.rb:249
#: ../lib/yard/templates/section.rb:249 ../lib/yard/templates/template.rb:249
#: ../lib/yard/templates/template_options.rb:249
msgid "Namespace for templating system"
msgstr "テンプレートシステム用のNamespace"

# YARD::Templates::Helpers
#: ../lib/yard/autoload.rb:251
#: ../lib/yard/templates/helpers/base_helper.rb:251
#: ../lib/yard/templates/helpers/filter_helper.rb:251
#: ../lib/yard/templates/helpers/html_helper.rb:251
#: ../lib/yard/templates/helpers/html_syntax_highlight_helper.rb:251
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:251
#: ../lib/yard/templates/helpers/markup_helper.rb:251
#: ../lib/yard/templates/helpers/method_helper.rb:251
#: ../lib/yard/templates/helpers/module_helper.rb:251
#: ../lib/yard/templates/helpers/text_helper.rb:251
#: ../lib/yard/templates/helpers/uml_helper.rb:251
msgid "Namespace for template helpers"
msgstr "テンプレートへルパー用のNamespace"

# YARD::Templates::Helpers::Markup
#: ../lib/yard/autoload.rb:252
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:252
msgid "Namespace for markup providers"
msgstr "マークアップを提供する為のNamespace"

# YARD::CLI::Command
#: ../lib/yard/cli/command.rb:6
msgid ""
"Abstract base class for CLI utilities. Provides some helper methods for\n"
"the option parser"
msgstr ""
"CLIユーティリティ用の抽象的なベースクラス。\n"
"オプションパーサー用のいくつかのヘルパーメソッドを提供する。"

# YARD::CLI::YRI.run
# YARD::CLI::Command.run
#: ../lib/yard/cli/command.rb:12 ../lib/yard/cli/yri.rb:27
msgid "Helper method to run the utility on an instance."
msgstr "インスタンス上のユーティリティを起動する為のヘルパーメソッド。"

# @see
#: ../lib/yard/cli/command.rb:13 ../lib/yard/cli/yri.rb:28
#: ../lib/yard/server/commands/base.rb:33
msgid "tag|see|#run"
msgstr "tag|see|#run"

# YARD::CLI::Command#common_options
#: ../lib/yard/cli/command.rb:20
msgid "Adds a set of common options to the tail of the OptionParser"
msgstr "OptionParserの末尾に一般的なオプションのグループを追加する。"

# @param [Hash]
# @param [OptionParser]
# @param [Hash{String => String}]
# @param [Hash, nil]
#: ../lib/yard/cli/command.rb:23 ../lib/yard/cli/command.rb:54
#: ../lib/yard/code_objects/class_object.rb:63
#: ../lib/yard/code_objects/class_object.rb:98
#: ../lib/yard/code_objects/namespace_object.rb:113
#: ../lib/yard/code_objects/namespace_object.rb:144
#: ../lib/yard/code_objects/namespace_object.rb:164
#: ../lib/yard/handlers/base.rb:355
#: ../lib/yard/handlers/ruby/legacy/base.rb:34 ../lib/yard/options.rb:108
#: ../lib/yard/options.rb:122 ../lib/yard/parser/ruby/ast_node.rb:152
#: ../lib/yard/serializers/base.rb:27
#: ../lib/yard/serializers/file_system_serializer.rb:27
#: ../lib/yard/server/adapter.rb:71 ../lib/yard/server/commands/base.rb:74
#: ../lib/yard/server/rack_adapter.rb:26
#: ../lib/yard/templates/helpers/html_helper.rb:536
#: ../lib/yard/templates/template.rb:230 ../lib/yard/templates/template.rb:256
msgid "tag|param|opts"
msgstr "tag|param|opts"

# @param [OptionParser] opts
#: ../lib/yard/cli/command.rb:23 ../lib/yard/cli/command.rb:54
msgid "the option parser object"
msgstr "パーサーオブジェクトのオプション"

# YARD::CLI::Command#parse_options
#: ../lib/yard/cli/command.rb:49
msgid "Parses the option and gracefully handles invalid switches"
msgstr "オプションを解析し、無効な引数を処理する。"

# @since
#: ../lib/yard/cli/command.rb:54 ../lib/yard/cli/diff.rb:201
#: ../lib/yard/cli/gems.rb:59 ../lib/yard/cli/graph.rb:66
#: ../lib/yard/cli/help.rb:8 ../lib/yard/cli/server.rb:109
#: ../lib/yard/cli/stats.rb:179 ../lib/yard/cli/yardoc.rb:193
#: ../lib/yard/cli/yardoc.rb:197 ../lib/yard/cli/yardoc.rb:201
#: ../lib/yard/cli/yardoc.rb:388 ../lib/yard/cli/yardoc.rb:498
#: ../lib/yard/cli/yardoc.rb:742 ../lib/yard/cli/yri.rb:24
#: ../lib/yard/code_objects/base.rb:149
#: ../lib/yard/code_objects/method_object.rb:132
#: ../lib/yard/code_objects/namespace_object.rb:12
#: ../lib/yard/core_ext/insertion.rb:30 ../lib/yard/core_ext/insertion.rb:34
#: ../lib/yard/handlers/processor.rb:24 ../lib/yard/handlers/processor.rb:31
#: ../lib/yard/handlers/processor.rb:33 ../lib/yard/serializers/base.rb:61
#: ../lib/yard/server/commands/display_object_command.rb:47
#: ../lib/yard/tags/directives.rb:98 ../lib/yard/tags/directives.rb:121
#: ../lib/yard/tags/library.rb:100 ../lib/yard/tags/library.rb:128
#: ../lib/yard/tags/library.rb:137
#: ../lib/yard/templates/helpers/base_helper.rb:19
#: ../lib/yard/templates/helpers/base_helper.rb:102
#: ../lib/yard/templates/helpers/html_helper.rb:57
#: ../lib/yard/templates/helpers/html_helper.rb:73
#: ../lib/yard/templates/helpers/html_helper.rb:83
#: ../lib/yard/templates/helpers/html_helper.rb:91
#: ../lib/yard/templates/helpers/html_helper.rb:101
#: ../lib/yard/templates/helpers/html_helper.rb:109
#: ../lib/yard/templates/helpers/html_helper.rb:123
#: ../lib/yard/templates/helpers/markup_helper.rb:52
#: ../lib/yard/templates/helpers/markup_helper.rb:122
#: ../lib/yard/templates/helpers/markup_helper.rb:140
#: ../lib/yard/templates/section.rb:85 ../lib/yard/templates/template.rb:133
msgid "0.6.0"
msgstr "0.6.0"

# @param [Array]
# @param [Array]
#: ../lib/yard/cli/command.rb:54 ../lib/yard/cli/gems.rb:17
#: ../lib/yard/cli/graph.rb:50 ../lib/yard/cli/graph.rb:66
#: ../lib/yard/cli/list.rb:12 ../lib/yard/cli/stats.rb:33
#: ../lib/yard/cli/stats.rb:165 ../lib/yard/cli/yardoc.rb:243
#: ../lib/yard/cli/yardoc.rb:281 ../lib/yard/cli/yardoc.rb:507
#: ../lib/yard/cli/yri.rb:49 ../lib/yard/cli/yri.rb:189
#: ../lib/yard/docstring.rb:37 ../lib/yard/templates/template.rb:204
msgid "tag|param|args"
msgstr "tag|param|args"

# @param [Array] args
#: ../lib/yard/cli/command.rb:54
msgid ""
"the arguments passed from input. This\n"
"array will be modified."
msgstr ""
"引数は入力から解析される。\n"
"この配列は、変更されるだろう。"

# YARD::CLI::Command#load_script
#: ../lib/yard/cli/command.rb:63
msgid ""
"Loads a Ruby script. If Config.options[:safe_mode] is enabled,\n"
"this method will do nothing."
msgstr ""
"Rubyスクリプトをロードする。 Config.options[:safe_mode] が有効の場合、\n"
"このメソッドは、何もしないだろう。"

# @since
#: ../lib/yard/cli/command.rb:67 ../lib/yard/cli/config.rb:90
#: ../lib/yard/cli/server.rb:20 ../lib/yard/cli/server.rb:24
#: ../lib/yard/config.rb:263 ../lib/yard/handlers/base.rb:228
#: ../lib/yard/handlers/base.rb:235 ../lib/yard/server.rb:7
msgid "0.6.2"
msgstr "0.6.2"

# @param [String]
# @param [String, nil]
#: ../lib/yard/cli/command.rb:67 ../lib/yard/code_objects/base.rb:260
#: ../lib/yard/core_ext/file.rb:53 ../lib/yard/registry.rb:118
#: ../lib/yard/registry.rb:132 ../lib/yard/registry.rb:158
#: ../lib/yard/registry_store.rb:113 ../lib/yard/registry_store.rb:130
#: ../lib/yard/registry_store.rb:164
#: ../lib/yard/templates/helpers/base_helper.rb:110
msgid "tag|param|file"
msgstr "tag|param|file"

# @param [String] file
#: ../lib/yard/cli/command.rb:67
msgid "the path to the script to load"
msgstr "ロードするスクリプトの為のパス"

# YARD::CLI::CommandParser
#: ../lib/yard/cli/command_parser.rb:4
msgid ""
"This class parses a command name out of the +yard+ CLI command and calls\n"
"that command in the form:"
msgstr ""
"このクラスは、 +yard+ CLIコマンド出力のコマンド名を解析する。\n"
"以下の形式のコマンド呼び出しとなる。"

# YARD::CLI::CommandParser
#: ../lib/yard/cli/command_parser.rb:7
msgid "  $ yard command_name [options]"
msgstr "  $ yard command_name [options]"

# YARD::CLI::CommandParser
#: ../lib/yard/cli/command_parser.rb:9
msgid ""
"If no command or arguments are specified, or if the arguments immediately\n"
"begin with a +--opt+ (not +--help+), the {default_command} will be used\n"
"(which itself defaults to +:doc+)."
msgstr ""
"コマンドが無い場合や、引数が指定される場合、\n"
"又は、引数が直後に +--opt+ ( +--help+ ではない)で始まる場合、\n"
"{default_command}が利用される。(そして自身の +:doc+ をデフォルトにする)"

# YARD::CLI::CommandParser
#: ../lib/yard/cli/command_parser.rb:13
msgid "== Adding a Command"
msgstr "== コマンドを追加する"

# YARD::CLI::CommandParser
#: ../lib/yard/cli/command_parser.rb:15
msgid ""
"To add a custom command via plugin, create a mapping in {commands} from\n"
"the Symbolic command name to the {Command} class that implements the\n"
"command. To implement a command, see the documentation for the {Command}\n"
"class."
msgstr ""
"プラグイン経由でカスタムコマンドを追加するには、\n"
"そのコマンド名の象徴から\n"
"コマンドを実装する{Command}クラスに\n"
"{commands}のマッピングを作成する。\n"
"コマンドを実装するには、{Command}クラス用のドキュメントを参照。"

# @see
#: ../lib/yard/cli/command_parser.rb:22
msgid "tag|see|Command"
msgstr "tag|see|Command"

# @see
#: ../lib/yard/cli/command_parser.rb:22
msgid "tag|see|commands"
msgstr "tag|see|commands"

# @see
#: ../lib/yard/cli/command_parser.rb:22
msgid "tag|see|default_command"
msgstr "tag|see|default_command"

# @return [Hash{Symbol => Command}]
#: ../lib/yard/cli/command_parser.rb:26
msgid ""
"the mapping of command names to\n"
"command classes to parse the user command."
msgstr "ユーザーコマンドを解析するコマンドクラスの為のコマンド名のマッピング"

# @return [Symbol]
#: ../lib/yard/cli/command_parser.rb:30
msgid ""
"the default command name to use when no options\n"
"are specified or"
msgstr "オプションが指定されない時に利用するデフォルトのコマンド名"

# YARD::CLI::CommandParser.run
#: ../lib/yard/cli/command_parser.rb:50
msgid "Convenience method to create a new CommandParser and call {#run}"
msgstr ""
"新しいCommandParserを作成し、{#run}メソッドを呼び出す為の便利メソッド。"

# @return [CommandParser]
#: ../lib/yard/cli/command_parser.rb:53
msgid "a new instance of CommandParser"
msgstr "CommandParserの新しいインスタンス"

# YARD::CLI::CommandParser#run
#: ../lib/yard/cli/command_parser.rb:58
msgid ""
"Runs the {Command} object matching the command name of the first\n"
"argument."
msgstr "最初の引数のコマンド名にマッチする{Command}オブジェクトを起動する。"

# YARD::CLI::Config
#: ../lib/yard/cli/config.rb:4
msgid "CLI command to view or edit configuration options"
msgstr ""
"CLIコマンドを調べる。\n"
"又は、設定オプションを編集する。"

# @return [Symbol, nil]
#: ../lib/yard/cli/config.rb:7
msgid "the key to view/edit, if any"
msgstr "調べたり、編集する為のkey"

# @return [Array, nil]
#: ../lib/yard/cli/config.rb:10
msgid "the list of values to set (or single value), if modifying"
msgstr "変更する場合、セットする値のリストを返す(又は、単一の値)"

# @return [Boolean]
#: ../lib/yard/cli/config.rb:13
msgid "whether to reset the {#key}"
msgstr "{#key}をリセットするかどうか"

# @return [Boolean]
#: ../lib/yard/cli/config.rb:16
msgid "whether the value being set should be inside a list"
msgstr "設定される値がリストの内部になるかどうか"

# @return [Boolean]
#: ../lib/yard/cli/config.rb:19
msgid "whether to append values to existing key"
msgstr "既存のkeyに値を追加するかどうか"

# @return [Config]
#: ../lib/yard/cli/config.rb:21
msgid "a new instance of Config"
msgstr "Configの新しいインスタンス"

# YARD::CLI::Diff
#: ../lib/yard/cli/diff.rb:8
msgid ""
"CLI command to return the objects that were added/removed from 2 versions\n"
"of a project (library, gem, working copy)."
msgstr ""
"プロジェクトの2つのバージョンから追加や削除された所のオブジェクトを返す為の"
"CLIコマンド。\n"
"(library, gem, working copy)"

# @return [Diff]
#: ../lib/yard/cli/diff.rb:11
msgid "a new instance of Diff"
msgstr "Diffの新しいインスタンス"

# @return [Gems]
#: ../lib/yard/cli/gems.rb:5
msgid "a new instance of Gems"
msgstr "Gemsの新しいインスタンス"

# YARD::CLI::Gems#run
#: ../lib/yard/cli/gems.rb:13
msgid ""
"Runs the commandline utility, parsing arguments and generating\n"
"YARD indexes for gems."
msgstr ""
"コマンドラインユーティリティを起動し、引数を解析し、gem用のYARDインデックスを"
"生成する。"

# @param [Array] args
#: ../lib/yard/cli/gems.rb:17 ../lib/yard/cli/stats.rb:33
#: ../lib/yard/cli/yardoc.rb:281
msgid "the list of arguments"
msgstr "引数のリスト"

# YARD::CLI::Gems#build_gems
#: ../lib/yard/cli/gems.rb:26
msgid "Builds .yardoc files for all non-existing gems"
msgstr "存在しないgem用に.yardocファイルをビルドする。"

# @param [Array]
#: ../lib/yard/cli/gems.rb:27
msgid "tag|param|gems"
msgstr "tag|param|gems"

# YARD::CLI::Gems#optparse
#: ../lib/yard/cli/gems.rb:59
msgid "Parses options"
msgstr "オプションを解析する。"

# YARD::Rake::YardocTask#options
# YARD::Rake::YardocTask#options=
#: ../lib/yard/cli/graph.rb:4
msgid "Options to pass to the {Graph} CLI."
msgstr "{Graph} CLIに渡す為のオプション"

# @param [String] text
#: ../lib/yard/cli/graph.rb:6
msgid "the default output format"
msgstr "デフォルトの出力フォーマット"

# @param [Boolean] link
#: ../lib/yard/cli/graph.rb:9
msgid "whether to list the full class diagram"
msgstr "全てのクラス図をリストするかどうか"

# @return [Boolean]
#: ../lib/yard/cli/graph.rb:12
msgid "whether to show the object dependencies"
msgstr "オブジェクトの依存関係を調べるかどうか"

# @param [Hash] opts
#: ../lib/yard/cli/graph.rb:15
msgid "any contents to pass to the digraph"
msgstr "図に渡す内容"

# YARD::CLI::Graph
#: ../lib/yard/cli/graph.rb:19
msgid ""
"A command-line utility to generate Graphviz graphs from\n"
"a set of objects"
msgstr ""
"オブジェクトのグループからGraphvizのグラフを生成する為のコマンドラインユー"
"ティリティ"

# @see
#: ../lib/yard/cli/graph.rb:23
msgid "tag|see|Graph#run"
msgstr "tag|see|Graph#run"

# YARD::CLI::Graph#options
#: ../lib/yard/cli/graph.rb:25
msgid ""
"The options parsed out of the commandline.\n"
"Default options are:\n"
"  :format => :dot"
msgstr ""
"optionsはコマンドラインの出力を解析する。\n"
"optionsのデフォルトは:\n"
"  :format => dot"

# YARD::CLI::Graph#objects
#: ../lib/yard/cli/graph.rb:30
msgid "The set of objects to include in the graph."
msgstr "graphでインクルードする為のオブジェクトのグループ"

# YARD::CLI::Graph#initialize
#: ../lib/yard/cli/graph.rb:33
msgid "Creates a new instance of the command-line utility"
msgstr "コマンドラインユーティリティの新しいインスタンスを作成する。"

# @return [Graph]
#: ../lib/yard/cli/graph.rb:33
msgid "a new instance of Graph"
msgstr "Graphの新しいインスタンス"

# YARD::CLI::YRI#run
# YARD::CLI::Graph#run
#: ../lib/yard/cli/graph.rb:45 ../lib/yard/cli/yri.rb:45
msgid "Runs the command-line utility."
msgstr "コマンドラインユーティリティを起動する。"

# @param [Array] args
#: ../lib/yard/cli/graph.rb:50 ../lib/yard/cli/graph.rb:66
#: ../lib/yard/cli/stats.rb:165 ../lib/yard/cli/yardoc.rb:507
#: ../lib/yard/cli/yri.rb:49 ../lib/yard/cli/yri.rb:189
msgid "each tokenized argument"
msgstr "個々にトークナイズされた引数"

# @example 
#: ../lib/yard/cli/graph.rb:50
msgid ""
"grapher = Graph.new\n"
"grapher.run('--private')"
msgstr ""
"grapher = Graph.new\n"
"grapher.run('--private')"

# YARD::CLI::YRI#optparse
# YARD::CLI::Graph#optparse
# YARD::CLI::Stats#optparse
# YARD::CLI::Yardoc#optparse
#: ../lib/yard/cli/graph.rb:65 ../lib/yard/cli/stats.rb:164
#: ../lib/yard/cli/yardoc.rb:506 ../lib/yard/cli/yri.rb:188
msgid "Parses commandline options."
msgstr "コマンドラインオプションを解析する。"

# YARD::CLI::Help
#: ../lib/yard/cli/help.rb:4
msgid "Handles help for commands"
msgstr "コマンド用のヘルプを操作する。"

# YARD::CLI::I18n
#: ../lib/yard/cli/i18n.rb:6
msgid ""
"CLI command to support internationalization (a.k.a. i18n).\n"
"I18n feature is based on gettext technology.\n"
"This command generates .pot file from docstring and extra\n"
"documentation."
msgstr ""

# @todo
#: ../lib/yard/cli/i18n.rb:12
msgid "Support msgminit and msgmerge features?"
msgstr ""

# @return [YRI]
#: ../lib/yard/cli/i18n.rb:13
msgid "a new instance of I18n"
msgstr "I18nの新しいインスタンス"

# @since
#: ../lib/yard/cli/i18n.rb:60 ../lib/yard/code_objects/base.rb:233
#: ../lib/yard/code_objects/base.rb:531
#: ../lib/yard/code_objects/method_object.rb:83
#: ../lib/yard/docstring_parser.rb:268 ../lib/yard/handlers/base.rb:411
#: ../lib/yard/handlers/base.rb:424 ../lib/yard/handlers/base.rb:433
#: ../lib/yard/handlers/base.rb:456 ../lib/yard/handlers/base.rb:470
#: ../lib/yard/handlers/base.rb:483 ../lib/yard/handlers/base.rb:495
#: ../lib/yard/handlers/base.rb:506 ../lib/yard/handlers/base.rb:520
#: ../lib/yard/handlers/c/override_comment_handler.rb:27
#: ../lib/yard/i18n/pot_generator.rb:258 ../lib/yard/registry_store.rb:94
#: ../lib/yard/registry_store.rb:103 ../lib/yard/tags/directives.rb:73
#: ../lib/yard/tags/directives.rb:519 ../lib/yard/tags/library.rb:113
#: ../lib/yard/templates/helpers/html_helper.rb:364
#: ../lib/yard/templates/helpers/html_helper.rb:372
msgid "0.8.0"
msgstr ""

# YARD::CLI::List
#: ../lib/yard/cli/list.rb:4
msgid ""
"Lists all constant and method names in the codebase. Uses {Yardoc} --list."
msgstr ""
"全ての定数とコードベースの中のメソッド名を記述する。{yardoc} --list で利用す"
"る。"

# YARD::CLI::List#run
#: ../lib/yard/cli/list.rb:8
msgid ""
"Runs the commandline utility, parsing arguments and displaying a\n"
"list of objects"
msgstr ""
"コマンドラインユーティリティを起動し、引数を解析する。\n"
"そして、オブジェクトのリストを表示する。"

# @param [Array] args
#: ../lib/yard/cli/list.rb:12
msgid "the list of arguments."
msgstr "引数のリスト"

# YARD::CLI::Server
#: ../lib/yard/cli/server.rb:4
msgid "A local documentation server"
msgstr "ローカルドキュメントサーバー"

# @return [Hash]
#: ../lib/yard/cli/server.rb:7
msgid "a list of options to pass to the doc server"
msgstr "ドキュメントサーバーに渡す為のオプションのリスト"

# @return [Hash]
#: ../lib/yard/cli/server.rb:10
msgid "a list of options to pass to the web server"
msgstr "webサーバーに渡す為のオプションのリスト"

# @return [Hash]
#: ../lib/yard/cli/server.rb:13
msgid "a list of library names and yardoc files to serve"
msgstr "ライブラリ名のリストと提供する為のyardocファイル"

# @return [Adapter]
#: ../lib/yard/cli/server.rb:16
msgid "the adapter to use for loading the web server"
msgstr "ロードするwebサーバー用に利用されるアダプタ"

# @return [Array]
#: ../lib/yard/cli/server.rb:20
msgid "a list of scripts to load"
msgstr "ロードする為のスクリプトのリスト"

# @return [Array]
#: ../lib/yard/cli/server.rb:24
msgid "a list of template paths to register"
msgstr "登録するテンプレートのパスのリスト"

# YARD::CLI::Yardoc#initialize
#: ../lib/yard/cli/server.rb:27
msgid "Creates a new instance of the Server command line utility"
msgstr "サーバーコマンドラインユーティリティの新しいインスタンスを作成する。"

# @return [Verifier]
#: ../lib/yard/cli/server.rb:27
msgid "a new instance of Server"
msgstr "サーバーの新しいインスタンス"

# YARD::CLI::Stats::STATS_ORDER
#: ../lib/yard/cli/stats.rb:8
msgid ""
"Maintains the order in which +stats_for_+ statistics methods should be\n"
"printed."
msgstr ""
"オーダーを継続する。そして統計用の +stats_for_+ メソッドは、プリントされるべ"
"きである。"

# @see
#: ../lib/yard/cli/stats.rb:11
msgid "tag|see|#print_statistics"
msgstr ""

# @return [Boolean]
#: ../lib/yard/cli/stats.rb:14
msgid "whether to parse and load registry"
msgstr "解析するかレジストリーをロードするかどうか"

# @return [Stats]
#: ../lib/yard/cli/stats.rb:17
msgid "a new instance of Stats"
msgstr "Statsの新しいインスタンス"

# @param [Boolean]
#: ../lib/yard/cli/stats.rb:17
msgid "tag|param|parse"
msgstr ""

# @param [Boolean] parse
#: ../lib/yard/cli/stats.rb:17
msgid "whether to parse and load registry (see {#parse})"
msgstr "解析するかレジストリーがロードされるかどうか(see {#parse})"

# YARD::CLI::Stats#run
# YARD::CLI::Yardoc#run
#: ../lib/yard/cli/stats.rb:29 ../lib/yard/cli/yardoc.rb:238
msgid ""
"Runs the commandline utility, parsing arguments and generating\n"
"output if set."
msgstr ""
"コマンドラインユーティリティを起動し、引数を解析する。\n"
"そしてグループの場合、出力を生成する。"

# YARD::CLI::Stats#print_statistics
#: ../lib/yard/cli/stats.rb:48
msgid "Prints statistics for different object types"
msgstr "色々なオブジェクト型用に統計値をプリントする。"

# YARD::CLI::Stats#print_statistics
#: ../lib/yard/cli/stats.rb:50
msgid ""
"To add statistics for a specific type, add a method +#stats_for_TYPE+\n"
"to this class that calls {#output}."
msgstr ""
"特定の型用に統計値を追加するには、\n"
"{#output}メソッドに呼び出されるこのクラスに +#stats_for_TYPE+ メソッドを追加"
"する。"

# YARD::CLI::Stats#print_undocumented_objects
#: ../lib/yard/cli/stats.rb:71
msgid "Prints list of undocumented objects"
msgstr "記述されなかったオブジェクトのリストをプリントする。"

# @return [Array]
#: ../lib/yard/cli/stats.rb:99
msgid ""
"all the parsed objects in the registry,\n"
"removing any objects that are not visible (private, protected) depending\n"
"on the arguments passed to the command."
msgstr ""
"レジストリーの中の全ての解析されたオブジェクト,\n"
"コマンドに渡された引数に応じて不可視(private,protected)のオブジェクトを削除している。"

# YARD::CLI::Stats#stats_for_files
#: ../lib/yard/cli/stats.rb:104
msgid "Statistics for files"
msgstr "ファイル用の統計値"

# YARD::CLI::Stats#stats_for_modules
#: ../lib/yard/cli/stats.rb:111
msgid "Statistics for modules"
msgstr "モジュール用の統計値"

# YARD::CLI::Stats#stats_for_classes
#: ../lib/yard/cli/stats.rb:116
msgid "Statistics for classes"
msgstr "クラス用の統計値"

# YARD::CLI::Stats#stats_for_constants
#: ../lib/yard/cli/stats.rb:121
msgid "Statistics for constants"
msgstr "定数用の統計値"

# YARD::CLI::Stats#stats_for_methods
#: ../lib/yard/cli/stats.rb:126
msgid "Statistics for methods"
msgstr "メソッド用の統計値"

# YARD::CLI::Stats#output
#: ../lib/yard/cli/stats.rb:135
msgid ""
"Prints a statistic to standard out. This method is optimized for\n"
"getting Integer values, though it allows any data to be printed."
msgstr ""
"標準出力に統計値をプリントする。このメソッドは、\n"
"Integerの値の取得用に最適化され、プリントされる為に任意のデータを受入れる。"

# @param [Integer, nil] undoc
#: ../lib/yard/cli/stats.rb:143
msgid "number of undocumented objects for the type"
msgstr "型によって記述されなかったオブジェクトの数"

# @param [String]
# @param [Integer, String]
#: ../lib/yard/cli/stats.rb:143
#: ../lib/yard/code_objects/extra_file_object.rb:47
#: ../lib/yard/code_objects/macro_object.rb:39 ../lib/yard/registry.rb:323
#: ../lib/yard/serializers/base.rb:41 ../lib/yard/serializers/base.rb:77
#: ../lib/yard/server/commands/base.rb:159
#: ../lib/yard/templates/helpers/uml_helper.rb:33
msgid "tag|param|data"
msgstr ""

# @param [String]
# @param [Symbol, String]
# @param [String, Symbol]
# @param [Object]
# @param [#to_s]
#: ../lib/yard/cli/stats.rb:143 ../lib/yard/cli/yri.rb:109
#: ../lib/yard/cli/yri.rb:141 ../lib/yard/code_objects/base.rb:207
#: ../lib/yard/code_objects/method_object.rb:33 ../lib/yard/config.rb:154
#: ../lib/yard/config.rb:247 ../lib/yard/docstring.rb:237
#: ../lib/yard/docstring.rb:245 ../lib/yard/docstring.rb:255
#: ../lib/yard/docstring.rb:263 ../lib/yard/handlers/ruby/base.rb:21
#: ../lib/yard/handlers/ruby/base.rb:83 ../lib/yard/i18n/locale.rb:20
#: ../lib/yard/rake/yardoc_task.rb:46 ../lib/yard/registry.rb:270
#: ../lib/yard/registry.rb:368 ../lib/yard/server/library_version.rb:120
#: ../lib/yard/tags/tag.rb:43
msgid "tag|param|name"
msgstr ""

# @param [Integer, nil]
#: ../lib/yard/cli/stats.rb:143
msgid "tag|param|undoc"
msgstr ""

# @param [Integer, String] data
#: ../lib/yard/cli/stats.rb:143
msgid ""
"the numeric (or any) data representing\n"
"the statistic. If +data+ is an Integer, it should represent the\n"
"total objects of a type."
msgstr ""
"数(又は何か)のデータを表す統計値。\n"
"+data+ がIntegerの場合、型の全体のオブジェクトを表すはずである。"

# @param [String] name
#: ../lib/yard/cli/stats.rb:143
msgid "the statistic name"
msgstr "統計値の名前"

# YARD::CLI::YardocOptions
#: ../lib/yard/cli/yardoc.rb:7
msgid "Default options used in +yard doc+ command."
msgstr ""

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:10
msgid "the list of extra files rendered along with objects"
msgstr "オブジェクトと一緒に表示される追加のファイルのリスト"

# @return [String]
#: ../lib/yard/cli/yardoc.rb:13
msgid "the default title appended to each generated page"
msgstr ""

# @return [Verifier]
#: ../lib/yard/cli/yardoc.rb:16
msgid "the default verifier object to filter queries"
msgstr ""

# @return [Serializers::Base]
#: ../lib/yard/cli/yardoc.rb:20
msgid ""
"the default serializer for generating output\n"
"to disk."
msgstr ""

# @return [String]
#: ../lib/yard/cli/yardoc.rb:23
msgid "the default output format (:html)."
msgstr "デフォルト出力フォーマット (:html)"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:27
msgid ""
"whether the data should be rendered in a single page,\n"
"if the template supports it."
msgstr ""

# @return [CodeObjects::ExtraFileObject]
#: ../lib/yard/cli/yardoc.rb:31
msgid ""
"the README file object rendered\n"
"along with objects"
msgstr ""

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:35
msgid ""
"the list of code objects to render\n"
"the templates with."
msgstr "リストと共にテンプレートを表示する為のコードオブジェクトのリスト"

# @return [Numeric]
#: ../lib/yard/cli/yardoc.rb:38
msgid "An index value for rendering sequentially related templates"
msgstr ""

# @return [CodeObjects::Base]
#: ../lib/yard/cli/yardoc.rb:42
msgid ""
"an extra item to send to a template that is not\n"
"the main rendered object"
msgstr ""

# @return [CodeObjects::ExtraFileObject]
#: ../lib/yard/cli/yardoc.rb:47
msgid ""
"the file object being rendered.\n"
"The +object+ key is not used so that a file may be rendered in the context\n"
"of an object's namespace (for generating links)."
msgstr ""

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:51
msgid ""
"Yardoc is the default YARD CLI command (+yard doc+ and historic +yardoc+\n"
"executable) used to generate and output (mainly) HTML documentation given\n"
"a set of source files."
msgstr ""
"Yardocは、デフォルトのYARD CLIコマンドとなり( +yard doc+ と省略表記の +yardoc"
"+ が実行可能)、\n"
"生成し、与えられたソースファイルのグループのHTMLドキュメントの出力(主な機能)"
"の為に利用される。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:55 ../lib/yard/i18n/pot_generator.rb:38
msgid "== Usage"
msgstr "== 使用法"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:57
msgid "Main usage for this command is:"
msgstr "このコマンドの主な使用法は次のようになる:"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:59
msgid "  $ yardoc [options] [source_files [- extra_files]]"
msgstr ""

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:61
msgid "See +yardoc --help+ for details on valid options."
msgstr "有効なオプションの詳細は +yardoc --help+ で参照できる。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:63
msgid "== Options File (+.yardopts+)"
msgstr "== オプションファイル (+.yardopts+)"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:65
msgid ""
"If a +.yardopts+ file is found in the source directory being processed,\n"
"YARD will use the contents of the file as arguments to the command,\n"
"treating newlines as spaces. You can use shell-style quotations to\n"
"group space delimited arguments, just like on the command line."
msgstr ""
"+.yardopts+ ファイルが、処理されるソースディレクトリで見つかった場合、\n"
"YARDは、コマンドに引数としてファイルの内容を利用し、改行をスペースとして処理"
"する。\n"
"あなたはスペースで区切られた引数のグループに、\n"
"コマンドラインのようなシェルスタイルの引用を利用できる。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:70
msgid "A valid +.yardopts+ file might look like:"
msgstr "有効な +.yardopts+ ファイルは、次のようになる。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:72
msgid ""
"  --no-private\n"
"  --title \"My Title\"\n"
"  --exclude foo --exclude bar\n"
"  lib/**/*.erb\n"
"  lib/**/*.rb -\n"
"  HACKING.rdoc LEGAL COPYRIGHT"
msgstr ""

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:79
msgid ""
"Note that Yardoc also supports the legacy RDoc style +.document+ file,\n"
"though this file can only specify source globs to parse, not options."
msgstr ""
"次の事に留意する。Yardocは、レガシーなRDocスタイルの +.document+ ファイルもサ"
"ポートするけれども、\n"
"このファイルは、オプションはなしで、解析の為にソースのglobだけ指定できる。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:82
msgid "== Queries (+--query+)"
msgstr "== クエリー (+--query+)"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:84
msgid ""
"Yardoc supports queries to select specific code objects for which to\n"
"generate documentation. For example, you might want to generate\n"
"documentation only for your public API. If you've documented your public\n"
"methods with +@api public+, you can use the following query to select\n"
"all of these objects:"
msgstr ""
"Yardocは、ドキュメントを生成する時に、\n"
"特定のコードオブジェクトを選択する為にクエリーをサポートする。\n"
"例えば、あなたが、\n"
"自分のpublic APIの為だけにドキュメント生成したいかもしれない。\n"
"あなたが、 +@api public+ を用いて記述されたpublicメソッドを持っていた場合、\n"
"これらのオブジェクトの全てを選択する為に、次の様なクエリーを利用できる:"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:90
msgid "  --query '@api.text == \"public\"'"
msgstr ""

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:92
msgid ""
"Note that the syntax for queries is mostly Ruby with a few syntactic\n"
"simplifications for meta-data tags. See the {Verifier} class for an\n"
"overview of this syntax."
msgstr ""
"次の事に留意する。クエリー用の構文は、\n"
"主にRuby構文で、メタデータタグ用のいくつかの構文の簡単にしたものも用いてい"
"る。\n"
"この構文の概要は、{Verifier}クラス参照。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:96
msgid "== Adding Custom Ad-Hoc Meta-data Tags (+--tag+)"
msgstr "== カスタムした特別なメタデータタグ(+--tag+)を追加する"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:98
msgid ""
"YARD allows specification of {file:docs/Tags.md meta-data tags}\n"
"programmatically via the {YARD::Tags::Library} class, but often this is not\n"
"practical for users writing documentation. To make adding custom tags\n"
"easier, Yardoc has a few command-line switches for creating basic tags\n"
"and displaying them in generated HTML output."
msgstr ""
"YARDは、{YARD::Tags::Library}クラス経由でプラグラムされた{file:docs/Tags.md "
"meta-data tags}の仕様を受入れるが、時々これは、ユーザーが書いているドキュメン"
"トとはそぐわない場合がある。\n"
"簡単なカスタムタグを作成するには、\n"
"Yardocが基本的なタグ作成用にいくつかのコマンドライン引数を持っており、\n"
"それをHTML出力し表示できる。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:104
msgid ""
"To specify a custom tag to be displayed in output, use any of the\n"
"following:"
msgstr "出力に表示されるカスタムタグを指定するには、次のように利用できる。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:107
msgid ""
"* +--tag+ TAG:TITLE\n"
"* +--name-tag+ TAG:TITLE\n"
"* +--type-tag+ TAG:TITLE\n"
"* +--type-name-tag+ TAG:TITLE\n"
"* +--title-tag+ TAG:TITLE"
msgstr ""

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:113
msgid "\"TAG:TITLE\" is of the form: name:\"Display Title\", for example:"
msgstr ""
"以下のように\"TAG:TITLE\" は、 形式: 名前:\"表示されるタイトル\" とする。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:115
msgid "  --tag overload:\"Overloaded Method\""
msgstr ""

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:117
msgid "See +yardoc --help+ for a description of the various options."
msgstr "様々なオプションの説明は +yardoc --help+ 参照。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:119
msgid ""
"Tags added in this way are automatically displayed in output. To add\n"
"a meta-data tag that does not show up in output, use +--hide-tag TAG+.\n"
"Note that you can also use this option on existing tags to hide\n"
"builtin tags, for instance."
msgstr ""
"この方法で追加したタグは、自動的に出力で表示される。\n"
"出力に表示しないでメタデータタグを追加するには、 +--hide-tag TAG+ を使う。\n"
"次の事に留意する。あなたは、\n"
"組み込みタグを隠す為に既存のタグ上でこのオプションも利用できる。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:124
msgid "== Processed Data Storage (+.yardoc+ directory)"
msgstr "== 処理されたデータストレージ (+.yardoc+ ディレクトリ)"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:126
msgid ""
"When Yardoc parses a source directory, it creates a +.yardoc+ directory\n"
"(by default, override with +-b+) at the root of the project. This directory\n"
"contains marshal dumps for all raw object data in the source, so that\n"
"you can access it later for various commands (+stats+, +graph+, etc.).\n"
"This directory is also used as a cache for any future calls to +yardoc+\n"
"so as to process only the files which have changed since the last call."
msgstr ""
"Yardocがソースディレクトリを解析する時、プロジェクトのルートで +.yardoc+ ディ"
"レクトリを作成する。\n"
"(デフォルトで、 +-b+ と共に上書きする)\n"
"このディレクトリは、\n"
"全てのソースの生のオブジェクトデータ用に整理されたダンプを含んでいるので、\n"
"後で様々なコマンド用(+stats+, +graph+ 等)にアクセスできる。\n"
"このディレクトリは、いつか +yardoc+ を呼び出す為にもキャッシュとして利用す"
"る。\n"
"最後の呼び出しから変更した所のファイルだけ処理する為に。"

# YARD::CLI::Yardoc
#: ../lib/yard/cli/yardoc.rb:133
msgid ""
"When Yardoc uses the cache in subsequent calls to +yardoc+, methods\n"
"or classes that have been deleted from source since the last parsing\n"
"will not be erased from the cache (YARD never deletes objects). In such\n"
"a case, you should wipe the cache and do a clean parsing of the source "
"tree.\n"
"You can do this by deleting the +.yardoc+ directory manually, or running\n"
"Yardoc without +--use-cache+ (+-c+)."
msgstr ""
"Yardocが +yardoc+ 呼び出しに続くキャッシュを使う時、\n"
"最後に解析しているのでソースから削除されているメソッドやクラスは、\n"
"キャッシュから削除されない。(YARDはオブジェクトを決して削除しない)\n"
"このような場合、あなたは、キャッシュを一掃し、クリーンなソースツリーの解析に"
"するべきである。\n"
"+.yardoc+ ディレクトリを手動で削除する事に上記の事ができる。\n"
"又は、yardoc の +--use-cache+ (+-c+)無しで起動する。"

# @see
#: ../lib/yard/cli/yardoc.rb:141 ../lib/yard/rake/yardoc_task.rb:38
msgid "tag|see|Verifier"
msgstr ""

# YARD::CLI::Yardoc::DEFAULT_YARDOPTS_FILE
#: ../lib/yard/cli/yardoc.rb:143
msgid "The configuration filename to load extra options from"
msgstr "追加のオプションをロードする設定ファイル名"

# @see
#: ../lib/yard/cli/yardoc.rb:147 ../lib/yard/code_objects/base.rb:463
msgid "tag|see|Templates::Engine#render"
msgstr ""

# @return [Hash]
#: ../lib/yard/cli/yardoc.rb:147
msgid "the hash of options passed to the template."
msgstr "テンプレートに解析された、optionsのハッシュ"

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:150
msgid "list of Ruby source files to process"
msgstr "処理する為のRubyソースファイルのリスト"

# @since
#: ../lib/yard/cli/yardoc.rb:154 ../lib/yard/code_objects/base.rb:430
#: ../lib/yard/code_objects/method_object.rb:91
#: ../lib/yard/code_objects/method_object.rb:98
#: ../lib/yard/code_objects/method_object.rb:104
#: ../lib/yard/core_ext/file.rb:62 ../lib/yard/parser/source_parser.rb:469
#: ../lib/yard/templates/helpers/html_helper.rb:430
#: ../lib/yard/templates/helpers/html_helper.rb:542
msgid "0.5.3"
msgstr ""

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:154
msgid "list of excluded paths (regexp matches)"
msgstr "除外されたパス(正規表現にマッチする)のリスト"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:159
msgid ""
"whether to use the existing yardoc db if the\n"
".yardoc already exists. Also makes use of file checksums to\n"
"parse only changed files."
msgstr ""
".yardocが既に存在する場合、既存のyardoc dbを利用するかどうか。\n"
"従って、変更されたファイルだけ解析する為にファイルチェックサムを活用する。"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:162
msgid "whether to parse options from .yardopts"
msgstr ".yardoptsから、オプションを解析するかどうか"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:165
msgid "whether to parse options from .document"
msgstr ".documentからオプションを解析するかどうか"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:168
msgid "whether objects should be serialized to .yardoc db"
msgstr "オブジェクトが.yardoc dbにシリアライズされるかどうか"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:171
msgid "whether to generate output"
msgstr "出力を生成するかどうか"

# @since
#: ../lib/yard/cli/yardoc.rb:175 ../lib/yard/cli/yardoc.rb:402
#: ../lib/yard/handlers/ruby/legacy/class_condition_handler.rb:28
#: ../lib/yard/handlers/ruby/legacy/class_condition_handler.rb:67
#: ../lib/yard/handlers/ruby/legacy/class_condition_handler.rb:72
#: ../lib/yard/templates/helpers/base_helper.rb:149
msgid "0.5.5"
msgstr ""

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:175
msgid "whether to print a list of objects"
msgstr "オブジェクトのリストをプリントするかどうか"

# YARD::CLI::Yardoc#options_file
# YARD::CLI::Yardoc#options_file=
#: ../lib/yard/cli/yardoc.rb:178
msgid "The options file name (defaults to {DEFAULT_YARDOPTS_FILE})"
msgstr "ファイル名のオプション(デフォルトでは{DEFAULT_YARDOPTS_FILE}になる)"

# @return [String]
#: ../lib/yard/cli/yardoc.rb:179
msgid "the filename to load extra options from"
msgstr "追加のオプションをロードする為のファイル名"

# YARD::CLI::Yardoc#visibilities
# YARD::CLI::Yardoc#visibilities=
#: ../lib/yard/cli/yardoc.rb:182
msgid "Keep track of which visibilities are to be shown"
msgstr "visibilitiesで示されるその中で手順を維持する。"

# @since
#: ../lib/yard/cli/yardoc.rb:184 ../lib/yard/cli/yardoc.rb:281
#: ../lib/yard/cli/yardoc.rb:476 ../lib/yard/cli/yri.rb:74
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:133
#: ../lib/yard/parser/base.rb:51
#: ../lib/yard/parser/ruby/legacy/ruby_parser.rb:26
#: ../lib/yard/parser/source_parser.rb:150
#: ../lib/yard/parser/source_parser.rb:152
#: ../lib/yard/parser/source_parser.rb:158
#: ../lib/yard/parser/source_parser.rb:160
#: ../lib/yard/parser/source_parser.rb:168
#: ../lib/yard/parser/source_parser.rb:512 ../lib/yard/verifier.rb:36
#: ../lib/yard/verifier.rb:57
msgid "0.5.6"
msgstr ""

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:184
msgid "a list of visibilities"
msgstr "visibilitiesのリスト"

# YARD::CLI::Yardoc#visibilities
# YARD::CLI::Yardoc#visibilities=
#: ../lib/yard/cli/yardoc.rb:187
msgid "Keep track of which APIs are to be shown"
msgstr "そのAPIが表示される経過を追う"

# @since
#: ../lib/yard/cli/yardoc.rb:189 ../lib/yard/cli/yardoc.rb:484
#: ../lib/yard/i18n/message.rb:48 ../lib/yard/i18n/messages.rb:52
#: ../lib/yard/i18n/pot_generator.rb:69
msgid "0.8.1"
msgstr ""

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:189
msgid "a list of APIs"
msgstr "APIのリスト"

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:193
msgid "a list of tags to hide from templates"
msgstr "テンプレートから隠すタグのリスト"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:197
msgid "whether to print statistics after parsing"
msgstr "解析の後で統計値をプリントするかどうか"

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:201
msgid "a list of assets to copy after generation"
msgstr "生成の後でコピーする資産のリスト"

# @since
#: ../lib/yard/cli/yardoc.rb:205 ../lib/yard/docstring.rb:138
#: ../lib/yard/docstring.rb:186 ../lib/yard/docstring.rb:263
#: ../lib/yard/docstring.rb:272 ../lib/yard/parser/source_parser.rb:68
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
#: ../lib/yard/parser/source_parser.rb:292
#: ../lib/yard/parser/source_parser.rb:321
#: ../lib/yard/parser/source_parser.rb:328
#: ../lib/yard/parser/source_parser.rb:335
#: ../lib/yard/parser/source_parser.rb:342
#: ../lib/yard/parser/source_parser.rb:349
#: ../lib/yard/parser/source_parser.rb:393
#: ../lib/yard/parser/source_parser.rb:397 ../lib/yard/tags/directives.rb:318
#: ../lib/yard/tags/directives.rb:393 ../lib/yard/tags/directives.rb:489
#: ../lib/yard/tags/directives.rb:553 ../lib/yard/tags/directives.rb:583
#: ../lib/yard/templates/helpers/base_helper.rb:110
#: ../lib/yard/templates/helpers/html_helper.rb:134
msgid "0.7.0"
msgstr ""

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:205
msgid "whether markup option was specified"
msgstr "マークアップオプションが指定されたかどうか"

# YARD::CLI::Yardoc#initialize
#: ../lib/yard/cli/yardoc.rb:208
msgid "Creates a new instance of the commandline utility"
msgstr "コマンドラインユーティリティの新しいインスタンスを作成する。"

# @return [Yardoc]
#: ../lib/yard/cli/yardoc.rb:208
msgid "a new instance of Yardoc"
msgstr "Yardocの新しいインスタンス"

# @param [Array] args
#: ../lib/yard/cli/yardoc.rb:243
msgid ""
"the list of arguments. If the list only\n"
"contains a single nil value, skip calling of {#parse_arguments}"
msgstr ""
"引数のリスト。リストがnilだけの場合、\n"
"{#parse_arguments}メソッドを呼び出しスキップする。"

# YARD::CLI::Yardoc#parse_arguments
#: ../lib/yard/cli/yardoc.rb:278
msgid "Parses commandline arguments"
msgstr "コマンドライン引数を解析する"

# @return [Boolean]
#: ../lib/yard/cli/yardoc.rb:281
msgid "whether or not arguments are valid"
msgstr "引数が有効かどうか"

# YARD::CLI::Yardoc#all_objects
#: ../lib/yard/cli/yardoc.rb:317
msgid ""
"The list of all objects to process. Override this method to change\n"
"which objects YARD should generate documentation for."
msgstr ""
"処理する上での全てのオブジェクトのリスト。\n"
"変更するたびに、このメソッドは上書きするので、\n"
"YARDのオブジェクトは、ドキュメントを生成するべきである。"

# @deprecated
#: ../lib/yard/cli/yardoc.rb:321
msgid "To hide methods use the +@private+ tag instead."
msgstr "メソッドを隠すには、代わりに、 +@private+ タグを使う"

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:321
msgid "a list of code objects to process"
msgstr "処理する為のコードオブジェクトのリスト"

# YARD::CLI::Yardoc#yardopts
#: ../lib/yard/cli/yardoc.rb:326
msgid "Parses the .yardopts file for default yard options"
msgstr "デフォルトのyardオプション用に.yardoptsファイルを解析する。"

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:327
msgid "an array of options parsed from .yardopts"
msgstr ".yardoptsから解析されたオプションの配列"

# YARD::CLI::Yardoc#run_generate
#: ../lib/yard/cli/yardoc.rb:337
msgid "Generates output for objects"
msgstr "オブジェクト用の出力を生成する"

# @since
#: ../lib/yard/cli/yardoc.rb:340 ../lib/yard/cli/yri.rb:14
#: ../lib/yard/cli/yri.rb:180 ../lib/yard/registry.rb:132
#: ../lib/yard/registry.rb:147 ../lib/yard/registry_store.rb:130
msgid "0.5.1"
msgstr ""

# @param [Hash, nil] checksums
#: ../lib/yard/cli/yardoc.rb:340
msgid "if supplied, a list of checksums for files."
msgstr "提供する場合は、ファイルの為のチェックサムのリスト"

# @param [Hash, nil]
#: ../lib/yard/cli/yardoc.rb:340
msgid "tag|param|checksums"
msgstr ""

# YARD::CLI::Yardoc#verify_markup_options
#: ../lib/yard/cli/yardoc.rb:361
msgid ""
"Verifies that the markup options are valid before parsing any code.\n"
"Failing early is better than failing late."
msgstr ""
"任意のコードを解析する前に、有効なマークアップオプションを認証する。\n"
"(早期に失敗が分かるほうが、後で失敗するよりいいので)"

# YARD::CLI::Yardoc#copy_assets
#: ../lib/yard/cli/yardoc.rb:386
msgid "Copies any assets to the output directory"
msgstr "出力ディレクトリに任意の資産をコピーする。"

# YARD::CLI::Yardoc#print_list
#: ../lib/yard/cli/yardoc.rb:400
msgid "Prints a list of all objects"
msgstr "全てのオブジェクトのリストをプリントする"

# YARD::CLI::Yardoc#parse_yardopts_options
#: ../lib/yard/cli/yardoc.rb:411
msgid "Parses out the yardopts/document options"
msgstr "yardopts/documentオプションの出力を解析する"

# YARD::CLI::Yardoc#support_rdoc_document_file!
#: ../lib/yard/cli/yardoc.rb:426
msgid "Reads a .document file in the directory to get source file globs"
msgstr ""
"ソースファイルのglobを取得する為にディレクトリの中の.documentファイルをロード"
"する"

# @return [Array]
#: ../lib/yard/cli/yardoc.rb:427
msgid "an array of files parsed from .document"
msgstr ".documentから解析されたファイルの配列"

# YARD::CLI::Yardoc#add_extra_files
#: ../lib/yard/cli/yardoc.rb:435
msgid "Adds a set of extra documentation files to be processed"
msgstr "処理される追加のドキュメントファイルのグループを追加する"

# @param [Array]
# @param [String, Array]
#: ../lib/yard/cli/yardoc.rb:436 ../lib/yard/cli/yardoc.rb:456
#: ../lib/yard/i18n/pot_generator.rb:102
#: ../lib/yard/parser/source_parser.rb:32
#: ../lib/yard/parser/source_parser.rb:361 ../lib/yard/registry.rb:97
msgid "tag|param|files"
msgstr ""

# @param [Array] files
#: ../lib/yard/cli/yardoc.rb:436
msgid "the set of documentation files"
msgstr "ドキュメントファイルのグループ"

# YARD::CLI::Yardoc#parse_files
#: ../lib/yard/cli/yardoc.rb:448
msgid ""
"Parses the file arguments into Ruby files and extra files, which are\n"
"separated by a '-' element."
msgstr ""
"Rubyのファイルと追加のファイルをfilesの引数として解析する。\n"
"それは、'-'要素によって区切られる。"

# @example Parses a set of Ruby files with a separator and extra files
#: ../lib/yard/cli/yardoc.rb:456
msgid "parse_files %w(file1 file2 - extrafile1 extrafile2)"
msgstr ""

# @example Parses a set of Ruby source files
#: ../lib/yard/cli/yardoc.rb:456
msgid "parse_files %w(file1 file2 file3)"
msgstr ""

# @example
#: ../lib/yard/cli/yardoc.rb:456
msgid "tag|example|Parses a set of Ruby files with a separator and extra files"
msgstr "Rubyのファイルと区切りを用いた追加のファイルのグループを解析する"

# @example
#: ../lib/yard/cli/yardoc.rb:456
msgid "tag|example|Parses a set of Ruby source files"
msgstr "Rubyソースファイルのグループを解析する"

# @param [Array] files
#: ../lib/yard/cli/yardoc.rb:456 ../lib/yard/parser/source_parser.rb:32
msgid "the list of files to parse"
msgstr "解析するファイルのリスト"

# YARD::CLI::Yardoc#add_visibility_verifier
#: ../lib/yard/cli/yardoc.rb:474
msgid "Adds verifier rule for visibilities"
msgstr "visibilities用に認証ルールを追加する"

# YARD::CLI::Yardoc#add_visibility_verifier
#: ../lib/yard/cli/yardoc.rb:482
msgid "Adds verifier rule for APIs"
msgstr "API用に認証ルールを追加する"

# YARD::CLI::Yardoc#run_verifier
# YARD::Templates::Helpers::BaseHelper#run_verifier
#: ../lib/yard/cli/yardoc.rb:494
#: ../lib/yard/templates/helpers/base_helper.rb:24
msgid ""
"Runs a list of objects against the {Verifier} object passed into the\n"
"template and returns the subset of verified objects."
msgstr ""
"テンプレートへ渡された{Verifier}オブジェクトに対してオブジェクトのリストを起"
"動する。\n"
"そして、認証されたオブジェクトのサブセットを返す。"

# YARD::CLI::Yardoc#general_options
#: ../lib/yard/cli/yardoc.rb:532
msgid "Adds general options"
msgstr "全体的なオプションを追加する。"

# YARD::CLI::Yardoc#yardopts_options
#: ../lib/yard/cli/yardoc.rb:573
msgid "Adds --[no-]yardopts / --[no-]document"
msgstr ""

# @since
#: ../lib/yard/cli/yardoc.rb:592
msgid "0.2.1"
msgstr ""

# YARD::CLI::Yardoc#output_options
#: ../lib/yard/cli/yardoc.rb:592
msgid "Adds output options"
msgstr "オプションの出力を追加する。"

# YARD::CLI::Yardoc#tag_options
#: ../lib/yard/cli/yardoc.rb:741
msgid "Adds tag options"
msgstr "タグのオプションを追加する。"

# YARD::CLI::YRI
#: ../lib/yard/cli/yri.rb:6
msgid "A tool to view documentation in the console like `ri`"
msgstr "`ri`のようなコンソールでドキュメントを調べる為のツール"

# YARD::CLI::YRI::CACHE_FILE
#: ../lib/yard/cli/yri.rb:8
msgid ""
"The location in {YARD::CONFIG_DIR} where the YRI cache file is loaded\n"
"from."
msgstr "YRIキャッシュファイルがロードされる、{YARD::CONFIG_DIR}の中の場所"

# YARD::CLI::YRI::SEARCH_PATHS_FILE
#: ../lib/yard/cli/yri.rb:12
msgid ""
"A file containing all paths, delimited by newlines, to search for\n"
"yardoc databases."
msgstr ""
"ファイルは、改行によって区切られたyardocデータベース用の検索する為の\n"
"全てのパスを含んでいる。"

# YARD::CLI::YRI::DEFAULT_SEARCH_PATHS
#: ../lib/yard/cli/yri.rb:17
msgid ""
"Default search paths that should be loaded dynamically into YRI. These "
"paths\n"
"take precedence over all other paths ({SEARCH_PATHS_FILE} and RubyGems\n"
"paths). To add a path, call:"
msgstr ""
"デフォルトでは、YRIへ動的にロードされるべきパスを検索する。\n"
"これらのパスは、他のパス全てより優先して取得する({SEARCH_PATHS_FILE}と"
"RubyGemsパス)。\n"
"パスを追加するには、次のように呼び出す。"

# YARD::CLI::YRI::DEFAULT_SEARCH_PATHS
#: ../lib/yard/cli/yri.rb:21
msgid "  DEFAULT_SEARCH_PATHS.push(\"/path/to/.yardoc\")"
msgstr ""

# @return [Array]
#: ../lib/yard/cli/yri.rb:24
msgid "a list of extra search paths"
msgstr "追加の検索パスのリスト"

# @return [YRI]
#: ../lib/yard/cli/yri.rb:30
msgid "a new instance of YRI"
msgstr "YRIの新しいインスタンス"

# @example 
#: ../lib/yard/cli/yri.rb:49
msgid "YRI.new.run('String#reverse')"
msgstr ""

# YARD::CLI::YRI#print_usage
#: ../lib/yard/cli/yri.rb:72
msgid "Prints the command usage"
msgstr "コマンドの使用法をプリントする。"

# YARD::CLI::YRI#cache_object
#: ../lib/yard/cli/yri.rb:80
msgid ""
"Caches the .yardoc file where an object can be found in the {CACHE_FILE}"
msgstr ""
"オブジェクトが{CACHE_FILE}の中を見つけられる場合、\n"
".yardocファイルをキャッシュする。"

# @param [CodeObjects::Base, nil]
# @param [CodeObjects::Base]
# @param [Base, Proxy, String, Symbol, nil]
# @param [Proxy, CodeObjects::Base]
# @param [CodeObjects::Base, String]
# @param [CodeObjects::Base, CodeObjects::ExtraFileObject, String]
#: ../lib/yard/cli/yri.rb:94 ../lib/yard/code_objects/class_object.rb:122
#: ../lib/yard/docstring.rb:74 ../lib/yard/docstring.rb:99
#: ../lib/yard/docstring_parser.rb:106 ../lib/yard/handlers/base.rb:411
#: ../lib/yard/handlers/base.rb:424 ../lib/yard/handlers/base.rb:433
#: ../lib/yard/handlers/base.rb:456 ../lib/yard/handlers/base.rb:470
#: ../lib/yard/handlers/base.rb:483 ../lib/yard/handlers/base.rb:495
#: ../lib/yard/handlers/base.rb:506 ../lib/yard/handlers/base.rb:520
#: ../lib/yard/handlers/base.rb:544 ../lib/yard/registry.rb:174
#: ../lib/yard/registry.rb:182 ../lib/yard/serializers/base.rb:41
#: ../lib/yard/serializers/base.rb:50 ../lib/yard/serializers/base.rb:61
#: ../lib/yard/serializers/file_system_serializer.rb:48
#: ../lib/yard/serializers/file_system_serializer.rb:69
#: ../lib/yard/server/commands/base.rb:138 ../lib/yard/templates/engine.rb:114
#: ../lib/yard/templates/helpers/base_helper.rb:102
#: ../lib/yard/templates/helpers/base_helper.rb:119
#: ../lib/yard/templates/helpers/base_helper.rb:179
#: ../lib/yard/templates/helpers/base_helper.rb:193
#: ../lib/yard/templates/helpers/html_helper.rb:288
#: ../lib/yard/templates/helpers/uml_helper.rb:8
#: ../lib/yard/templates/helpers/uml_helper.rb:19 ../lib/yard/verifier.rb:75
msgid "tag|param|object"
msgstr ""

# @return [String]
#: ../lib/yard/cli/yri.rb:94
msgid "the formatted output for an object."
msgstr "オブジェクト用にフォーマットされた出力"

# @param [CodeObjects::Base] object
#: ../lib/yard/cli/yri.rb:94
msgid "the object to print."
msgstr "プリントする為のオブジェクト"

# YARD::CLI::YRI#find_object
#: ../lib/yard/cli/yri.rb:104
msgid ""
"Locates an object by name starting in the cached paths and then\n"
"searching through any search paths."
msgstr ""
"キャッシュされたパスで始まる名前のオブジェクトを示し、\n"
"その時、任意の検索パスを通して検索する。"

# @return [CodeObjects::Base]
#: ../lib/yard/cli/yri.rb:109
msgid "an object if found"
msgstr "見つかった場合は、オブジェクト"

# @return [nil]
#: ../lib/yard/cli/yri.rb:109 ../lib/yard/registry.rb:235
msgid "if no object is found"
msgstr "オブジェクトが見つからない場合"

# @param [String] name
#: ../lib/yard/cli/yri.rb:109
msgid "the full name of the object"
msgstr "オブジェクトのフルネーム"

# YARD::CLI::YRI#try_load_object
#: ../lib/yard/cli/yri.rb:134
msgid ""
"Tries to load the object with name. If successful, caches the object\n"
"with the cache_path"
msgstr ""

# @param [String]
# @param [Array]
# @param [String, :root]
#: ../lib/yard/cli/yri.rb:141
msgid "tag|param|cache_path"
msgstr ""

# @param [String] cache_path
#: ../lib/yard/cli/yri.rb:141
msgid ""
"the location of the yardoc\n"
"db containing the object to cache for future lookups.\n"
"No caching is done if this is nil."
msgstr ""

# @return [CodeObjects::Base]
#: ../lib/yard/cli/yri.rb:141
msgid "the object path"
msgstr "オブジェクトパス"

# YARD::CLI::YRI#load_cache
#: ../lib/yard/cli/yri.rb:151
msgid "Loads {CACHE_FILE}"
msgstr "{CACHE_FILE}をロードする"

# YARD::CLI::YRI#add_gem_paths
#: ../lib/yard/cli/yri.rb:161
msgid "Adds all RubyGems yardoc files to search paths"
msgstr "パスを検索する為に全てのRubyGemsyardocファイルを追加する\n"

# YARD::CLI::YRI#add_default_paths
#: ../lib/yard/cli/yri.rb:179
msgid "Adds paths in {SEARCH_PATHS_FILE}"
msgstr "{SEARCH_PATHS_FILE}の中のパスを追加する。"

# YARD::CodeObjects::CodeObjectList
#: ../lib/yard/code_objects/base.rb:4
msgid ""
"A list of code objects. This array acts like a set (no unique items)\n"
"but also disallows any {Proxy} objects from being added."
msgstr ""
"コードオブジェクトのリスト、この配列はグループ(固有の物ではない)のように振る"
"舞う。\n"
"しかしながら、追加される任意の{Proxy}オブジェクトを拒否する。"

# YARD::CodeObjects::CodeObjectList#initialize
#: ../lib/yard/code_objects/base.rb:7
msgid "Creates a new object list associated with a namespace"
msgstr "namespaceに関連付けられた新しいオブジェクトのリストを作成する。"

# @param [NamespaceObject]
#: ../lib/yard/code_objects/base.rb:10
msgid "tag|param|owner"
msgstr ""

# @param [NamespaceObject] owner
#: ../lib/yard/code_objects/base.rb:10
msgid "the namespace the list should be associated with"
msgstr "リストで関連付けられるべき、namespace"

# YARD::CodeObjects::CodeObjectList#push
# YARD::CodeObjects::CodeObjectList#<<
#: ../lib/yard/code_objects/base.rb:15 ../lib/yard/code_objects/base.rb:28
msgid "Adds a new value to the list"
msgstr "リストに新しく値を追加する"

# @param [Base] value
#: ../lib/yard/code_objects/base.rb:18
msgid "a code object to add"
msgstr "追加するコードオブジェクト"

# @return [CodeObjectList]
# @return [Proxy]
# @return [SymbolHash]
#: ../lib/yard/code_objects/base.rb:18 ../lib/yard/code_objects/proxy.rb:28
#: ../lib/yard/core_ext/symbol_hash.rb:65
msgid "self"
msgstr ""

# @param
# @param [Base]
# @param [Object]
# @param [String]
# @param [CodeObjects::Base]
#: ../lib/yard/code_objects/base.rb:18 ../lib/yard/code_objects/base.rb:325
#: ../lib/yard/code_objects/extra_file_object.rb:7
#: ../lib/yard/code_objects/extra_file_object.rb:8
#: ../lib/yard/code_objects/extra_file_object.rb:9
#: ../lib/yard/code_objects/extra_file_object.rb:10
#: ../lib/yard/code_objects/namespace_object.rb:6
#: ../lib/yard/code_objects/namespace_object.rb:7
#: ../lib/yard/code_objects/namespace_object.rb:8
#: ../lib/yard/core_ext/insertion.rb:13 ../lib/yard/core_ext/symbol_hash.rb:41
#: ../lib/yard/handlers/base.rb:311 ../lib/yard/handlers/base.rb:314
#: ../lib/yard/handlers/base.rb:317 ../lib/yard/handlers/base.rb:320
#: ../lib/yard/handlers/base.rb:333 ../lib/yard/handlers/base.rb:335
#: ../lib/yard/handlers/base.rb:337 ../lib/yard/handlers/base.rb:339
#: ../lib/yard/logging.rb:20 ../lib/yard/logging.rb:30
#: ../lib/yard/options.rb:99 ../lib/yard/parser/c/statement.rb:5
#: ../lib/yard/parser/c/statement.rb:6 ../lib/yard/parser/c/statement.rb:7
#: ../lib/yard/parser/c/statement.rb:13 ../lib/yard/parser/c/statement.rb:39
#: ../lib/yard/parser/c/statement.rb:43 ../lib/yard/parser/c/statement.rb:44
#: ../lib/yard/parser/c/statement.rb:45 ../lib/yard/parser/c/statement.rb:51
#: ../lib/yard/parser/c/statement.rb:52 ../lib/yard/parser/c/statement.rb:53
#: ../lib/yard/parser/ruby/ast_node.rb:41
#: ../lib/yard/parser/ruby/ast_node.rb:42
#: ../lib/yard/parser/ruby/ast_node.rb:48
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:485
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:486
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:487
#: ../lib/yard/parser/ruby/legacy/statement.rb:5
#: ../lib/yard/parser/ruby/legacy/statement.rb:11
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:6
#: ../lib/yard/registry_store.rb:52 ../lib/yard/tags/option_tag.rb:4
#: ../lib/yard/tags/ref_tag.rb:4 ../lib/yard/tags/ref_tag_list.rb:4
#: ../lib/yard/templates/helpers/base_helper.rb:4
#: ../lib/yard/templates/helpers/base_helper.rb:206
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:23
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:68
#: ../lib/yard/templates/template.rb:6 ../lib/yard/templates/template.rb:59
msgid "tag|param|value"
msgstr ""

# YARD::CodeObjects::NSEP
#: ../lib/yard/code_objects/base.rb:32
msgid "Namespace separator"
msgstr "Namespace separator(ネームスペース区切り)"

# YARD::CodeObjects::NSEPQ
#: ../lib/yard/code_objects/base.rb:35
msgid "Regex-quoted namespace separator"
msgstr ""
"Regex-quoted namespace separator(クオートされた正規表現ネームスペース区切り)"

# YARD::CodeObjects::ISEP
#: ../lib/yard/code_objects/base.rb:38
msgid "Instance method separator"
msgstr "Instance method separator(インスタンスメソッドの区切り)"

# YARD::CodeObjects::ISEPQ
#: ../lib/yard/code_objects/base.rb:41
msgid "Regex-quoted instance method separator"
msgstr ""
"Regex-quoted instance method separator(正規表現でクオートされたインスタンスメ"
"ソッド区切り)"

# YARD::CodeObjects::CSEP
#: ../lib/yard/code_objects/base.rb:44
msgid "Class method separator"
msgstr "Class method separator(クラスメソッド区切り)"

# YARD::CodeObjects::CSEPQ
#: ../lib/yard/code_objects/base.rb:47
msgid "Regex-quoted class method separator"
msgstr ""
"Regex-quoted class method separator(正規表現でクオートされたクラスメソッド区"
"切り)"

# YARD::CodeObjects::CONSTANTMATCH
#: ../lib/yard/code_objects/base.rb:50
msgid "Regular expression to match constant name"
msgstr "Regular expression to match constant name(定数名にマッチする正規表現)"

# YARD::CodeObjects::NAMESPACEMATCH
#: ../lib/yard/code_objects/base.rb:53
msgid "Regular expression to match namespaces (const A or complex path A::B)"
msgstr "namespaceにマッチする正規表現(const A or complex path A::B)"

# YARD::CodeObjects::METHODNAMEMATCH
#: ../lib/yard/code_objects/base.rb:56
msgid "Regular expression to match a method name"
msgstr "メソッド名にマッチする正規表現"

# YARD::CodeObjects::METHODMATCH
#: ../lib/yard/code_objects/base.rb:59
msgid ""
"Regular expression to match a fully qualified method def (self.foo, Class."
"foo)."
msgstr "全てに有効なメソッド定義(self.foo Class.fooなど)にマッチする正規表現"

# YARD::CodeObjects::BUILTIN_EXCEPTIONS
#: ../lib/yard/code_objects/base.rb:62
msgid "All builtin Ruby exception classes for inheritance tree."
msgstr "継承ツリー用の全ての組み込みRuby例外クラス"

# YARD::CodeObjects::BUILTIN_CLASSES
#: ../lib/yard/code_objects/base.rb:68
msgid "All builtin Ruby classes for inheritance tree."
msgstr "継承ツリー用の全てのRubyクラス"

# @note
#: ../lib/yard/code_objects/base.rb:69
msgid "MatchingData is a 1.8.x legacy class"
msgstr "マッチデータが1.8以降のレガシーケースの場合\n"

# YARD::CodeObjects::BUILTIN_MODULES
#: ../lib/yard/code_objects/base.rb:74
msgid "All builtin Ruby modules for mixin handling."
msgstr "mixin操作用の全てのRuby組み込みモジュール"

# YARD::CodeObjects::BUILTIN_ALL
#: ../lib/yard/code_objects/base.rb:77
msgid "All builtin Ruby classes and modules."
msgstr "全ての組み込みRubyクラスやモジュール"

# YARD::CodeObjects::BUILTIN_EXCEPTIONS_HASH
#: ../lib/yard/code_objects/base.rb:80
msgid ""
"Hash of {BUILTIN_EXCEPTIONS} as keys and true as value (for O(1) lookups)"
msgstr "{BUILTIN_EXCEPTIONS}のキーと,値がtrueのハッシュ,(for O(1) lookups)"

# YARD::CodeObjects::Base
#: ../lib/yard/code_objects/base.rb:83
msgid ""
"+Base+ is the superclass of all code objects recognized by YARD. A code\n"
"object is any entity in the Ruby language (class, method, module). A\n"
"DSL might subclass +Base+ to create a new custom object representing\n"
"a new entity type."
msgstr ""
"+Base+ は、YARDによって表される全てのコードオブジェクトのスーパークラスとな"
"る。\n"
"コードオブジェクトは、Ruby言語の中の何らかの(class,method,module)構成要素とな"
"る。\n"
"DSLは新しい構成要素の型で表されるカスタムオブジェクトを作成する為に、\n"
"+Base+ をサブクラスとするかもしれない。\n"

# YARD::CodeObjects::Base
#: ../lib/yard/code_objects/base.rb:88
msgid ""
"== Registry Integration\n"
"Any created object associated with a namespace is immediately registered\n"
"with the registry. This allows the Registry to act as an identity map\n"
"to ensure that no object is represented by more than one Ruby object\n"
"in memory. A unique {#path} is essential for this identity map to work\n"
"correctly."
msgstr ""
"== レジストリーの統合\n"
"namespaceと共に関連付けられ作成される任意のオブジェクトは、レジストリーと共に直ぐに記録される。\n"
"これは、メモリの中で一つ以上のRubyオブジェクトによって表される事を保証し、\n"
"レジストリーが独自のマップの様に振る舞う事を受け入れる。\n"
"固有の{#path}メソッドは、この独自のマップを正常に機能させる為に必須のものである。"

# YARD::CodeObjects::Base
#: ../lib/yard/code_objects/base.rb:95
msgid ""
"== Custom Attributes\n"
"Code objects allow arbitrary custom attributes to be set using the\n"
"{#[]=} assignment method."
msgstr ""

# YARD::CodeObjects::Base
#: ../lib/yard/code_objects/base.rb:99
msgid ""
"== Namespaces\n"
"There is a special type of object called a \"namespace\". These are "
"subclasses\n"
"of the {NamespaceObject} and represent Ruby entities that can have\n"
"objects defined within them. Classically these are modules and classes,\n"
"though a DSL might create a custom {NamespaceObject} to describe a\n"
"specific set of objects."
msgstr ""
"== Namespaces\n"
"\"namespace\"に呼び出されるオブジェクトの特別な型がある。\n"
"これらは{NamespaceObject}をサブクラス化し、\n"
"それらの中で定義されるオブジェクトが持つ事が出来るRubyの構成要素を表す。\n"
"オーソドックスなこれらのモジュールやクラスは、\n"
"DSLが特定のオブジェクトのグループを説明する為に、\n"
"カスタム{NamespaceObject}を作成するかもしれない。\n"

# @abstract
#: ../lib/yard/code_objects/base.rb:111
msgid ""
"This class should not be used directly. Instead, create a\n"
"subclass that implements {#path}, {#sep} or {#type}."
msgstr ""
"このクラスは、直接利用するべきではない。\n"
"代わりに、{#path}, {#sep} , {#type}メソッドを実装するサブクラスを作成する。"

# @see
#: ../lib/yard/code_objects/base.rb:111 ../lib/yard/code_objects/base.rb:312
msgid "tag|see|#[]="
msgstr ""

# @see
#: ../lib/yard/code_objects/base.rb:111
msgid "tag|see|#path"
msgstr ""

# @see
#: ../lib/yard/code_objects/base.rb:111
msgid "tag|see|NamespaceObject"
msgstr ""

# @see
#: ../lib/yard/code_objects/base.rb:111 ../lib/yard/registry_store.rb:8
msgid "tag|see|Registry"
msgstr ""

# YARD::CodeObjects::Base#files
#: ../lib/yard/code_objects/base.rb:113
msgid "The files the object was defined in. To add a file, use {#add_file}."
msgstr ""
"中で定義されたオブジェクトから成るファイル、\n"
"ファイルを追加するには、{#add_file}メソッドを使う。"

# @return [Array]
#: ../lib/yard/code_objects/base.rb:115 ../lib/yard/rake/yardoc_task.rb:24
msgid "a list of files"
msgstr "ファイルのリスト"

# @see
#: ../lib/yard/code_objects/base.rb:115
msgid "tag|see|#add_file"
msgstr ""

# YARD::CodeObjects::Base#namespace
# YARD::CodeObjects::Base#parent
#: ../lib/yard/code_objects/base.rb:118 ../lib/yard/code_objects/base.rb:496
msgid ""
"The namespace the object is defined in. If the object is in the\n"
"top level namespace, this is {Registry.root}"
msgstr ""
"中で定義されるオブジェクトから成るnamespace,オブジェクトがtop level namespace"
"の場合、\n"
"これは、{Registry.root}になる。"

# @return [NamespaceObject]
#: ../lib/yard/code_objects/base.rb:120
msgid "the namespace object"
msgstr "namespaceオブジェクト"

# YARD::CodeObjects::Base#source
#: ../lib/yard/code_objects/base.rb:123
msgid "The source code associated with the object"
msgstr "オブジェクトに関連付けられたソースコード"

# @return [String, nil]
#: ../lib/yard/code_objects/base.rb:124
msgid "source, if present, or nil"
msgstr "存在する場合はソース,そうでなけば、nil"

# YARD::CodeObjects::Base#source_type
# YARD::CodeObjects::Base#source_type=
#: ../lib/yard/code_objects/base.rb:127
msgid ""
"Language of the source code associated with the object. Defaults to\n"
"+:ruby+."
msgstr ""
"オブジェクトと共に関連付けられたソースコードの言語。\n"
"デフォルトは +:ruby+ 。"

# @return [Symbol]
#: ../lib/yard/code_objects/base.rb:130
msgid "the language type"
msgstr "言語の型"

# YARD::CodeObjects::Base#signature
# YARD::CodeObjects::Base#signature=
#: ../lib/yard/code_objects/base.rb:133
msgid ""
"The one line signature representing an object. For a method, this will\n"
"be of the form \"def meth(arguments...)\". This is usually the first\n"
"source line."
msgstr ""
"オブジェクトを一行の用法で表している。メソッド用、\n"
"これは、\"def meth(arguments...)\"のような形式になるだろう。\n"
"普通は、最初のソースの最初の行となる。"

# @return [String]
#: ../lib/yard/code_objects/base.rb:137
msgid "a line of source"
msgstr "ソースの行"

# YARD::CodeObjects::Base#docstring
#: ../lib/yard/code_objects/base.rb:140
msgid "The documentation string associated with the object"
msgstr "オブジェクトに関連付けられたドキュメント文字列"

# @return [Docstring]
#: ../lib/yard/code_objects/base.rb:141 ../lib/yard/code_objects/base.rb:367
msgid "the documentation string"
msgstr "ドキュメント文字列(docstring)"

# YARD::CodeObjects::Base#dynamic
# YARD::CodeObjects::Base#dynamic=
#: ../lib/yard/code_objects/base.rb:144
msgid "Marks whether or not the method is conditionally defined at runtime"
msgstr "メソッドが実行時に定義された条件となるか、マークする。"

# @return [Boolean]
#: ../lib/yard/code_objects/base.rb:145
msgid "true if the method is conditionally defined at runtime"
msgstr "メソッドが実行時に定義された条件となる場合、true"

# @return [String]
#: ../lib/yard/code_objects/base.rb:149
msgid "the group this object is associated with"
msgstr "このオブジェクトに関連付けられたグループ"

# YARD::CodeObjects::Base#dynamic?
#: ../lib/yard/code_objects/base.rb:152
msgid "Is the object defined conditionally at runtime?"
msgstr "オブジェクトが実行時に条件が定義されたか?"

# @see
#: ../lib/yard/code_objects/base.rb:153
msgid "tag|see|#dynamic"
msgstr ""

# @return [Symbol]
#: ../lib/yard/code_objects/base.rb:156 ../lib/yard/code_objects/base.rb:158
msgid "the visibility of an object (:public, :private, :protected)"
msgstr "オブジェクトの可視性(:public, :private, :protected)"

# YARD::CodeObjects::Base.new
#: ../lib/yard/code_objects/base.rb:162
msgid "Allocates a new code object"
msgstr "新しいコードオブジェクトを割り当てる。"

# @see
#: ../lib/yard/code_objects/base.rb:164
#: ../lib/yard/code_objects/extended_method_object.rb:21
msgid "tag|see|#initialize"
msgstr ""

# YARD::CodeObjects::Base.===
#: ../lib/yard/code_objects/base.rb:185
msgid "Compares the class with subclasses"
msgstr "サブクラスとクラスを比較する"

# @param [Object]
# @param [Base, Proxy]
# @param [Base, String]
# @param [Docstring, String]
#: ../lib/yard/code_objects/base.rb:188 ../lib/yard/code_objects/base.rb:233
#: ../lib/yard/code_objects/base.rb:292 ../lib/yard/code_objects/base.rb:430
#: ../lib/yard/docstring.rb:112 ../lib/yard/i18n/message.rb:48
#: ../lib/yard/i18n/messages.rb:44
msgid "tag|param|other"
msgstr ""

# @param [Object] other
#: ../lib/yard/code_objects/base.rb:188
msgid "the other object to compare classes with"
msgstr "クラスと比較する他のオブジェクト"

# @return [Boolean]
#: ../lib/yard/code_objects/base.rb:188
msgid "true if other is a subclass of self"
msgstr "otherが自身のサブクラスの場合、true"

# YARD::CodeObjects::Base#initialize
#: ../lib/yard/code_objects/base.rb:194
msgid "Creates a new code object"
msgstr "新しいコードオブジェクトを作成する。"

# @example Create a method in the root namespace
#: ../lib/yard/code_objects/base.rb:207
msgid "CodeObjects::Base.new(:root, '#method') # => #"
msgstr ""

# @example Create class Z inside namespace X::Y
#: ../lib/yard/code_objects/base.rb:207
msgid ""
"CodeObjects::Base.new(P(\"X::Y\"), :Z) # or\n"
"CodeObjects::Base.new(Registry.root, \"X::Y\")"
msgstr ""

# @yield [self]
#: ../lib/yard/code_objects/base.rb:207
msgid "a block to perform any extra initialization on the object"
msgstr "オブジェクト上で任意の追加のイニシャライズを実行するblock"

# @example
#: ../lib/yard/code_objects/base.rb:207
msgid "tag|example|Create a method in the root namespace"
msgstr "root namespaceの中にメソッドを作成する"

# @example
#: ../lib/yard/code_objects/base.rb:207
msgid "tag|example|Create class Z inside namespace X::Y"
msgstr "namespace X::Yの中にZクラスを作成する。"

# @param [NamespaceObject]
# @param [CodeObjects::NamespaceObject, nil]
# @param [CodeObjects::NamespaceObject]
#: ../lib/yard/code_objects/base.rb:207
#: ../lib/yard/code_objects/method_object.rb:33 ../lib/yard/registry.rb:270
#: ../lib/yard/registry.rb:368
msgid "tag|param|namespace"
msgstr "namespace"

# @yieldparam [Base]
#: ../lib/yard/code_objects/base.rb:207
msgid "tag|yieldparam|self"
msgstr "self"

# @param [Symbol, String] name
#: ../lib/yard/code_objects/base.rb:207
msgid "the name (or complex path) of the object."
msgstr "オブジェクトの名前(又は、complex path)"

# @param [NamespaceObject] namespace
#: ../lib/yard/code_objects/base.rb:207
msgid ""
"the namespace the object belongs in,\n"
"{Registry.root} or :root should be provided if it is associated with\n"
"the top level namespace."
msgstr ""
"その中でオブジェクトの属するnamespace,\n"
"top level namespaceと共に、\n"
"{Registry.root} と :rootは、提供されるべきである。"

# @return [Base]
# @return [MacroObject]
#: ../lib/yard/code_objects/base.rb:207
#: ../lib/yard/code_objects/macro_object.rb:39
msgid "the newly created object"
msgstr "新たに作成されたオブジェクト"

# @yieldparam [Base] self
#: ../lib/yard/code_objects/base.rb:207
msgid "the newly initialized code object"
msgstr "新たにinitializeされるコードオジェクト"

# YARD::CodeObjects::Base#copy_to
#: ../lib/yard/code_objects/base.rb:228
msgid ""
"Copies all data in this object to another code object, except for\n"
"uniquely identifying information (path, namespace, name, scope)."
msgstr ""

# @return [CodeObjects::Base]
#: ../lib/yard/code_objects/base.rb:233
msgid "the object to copy data to"
msgstr "オブジェクトにデータをコピーする為のオブジェクト"

# @return [CodeObjects::RootObject]
#: ../lib/yard/code_objects/base.rb:233
msgid "the other object"
msgstr "他のオブジェクト"

# YARD::CodeObjects::Base#name
# YARD::CodeObjects::Proxy#name
#: ../lib/yard/code_objects/base.rb:243 ../lib/yard/code_objects/proxy.rb:71
msgid "The name of the object"
msgstr "オブジェクトの名前"

# @return [Symbol]
#: ../lib/yard/code_objects/base.rb:248
msgid "if prefix is false, the symbolized name"
msgstr "prefixがfalseの場合、シンボル化される名前"

# @return [String]
#: ../lib/yard/code_objects/base.rb:248
msgid ""
"if prefix is true, prefix + the name as a String.\n"
"This must be implemented by the subclass."
msgstr ""
"prefixがtrueの場合、prefix + 名前の文字列となる。\n"
"これは、サブクラスによって実装されなければならない。"

# @param [Boolean]
#: ../lib/yard/code_objects/base.rb:248
#: ../lib/yard/code_objects/method_object.rb:170
msgid "tag|param|prefix"
msgstr "prefix"

# @param [Boolean] prefix
#: ../lib/yard/code_objects/base.rb:248
msgid ""
"whether to show a prefix. Implement\n"
"this in a subclass to define how the prefix is showed."
msgstr ""
"prefixを見せるかどうか。\n"
"prefixがどのようにみせられるか定義する為に、\n"
"このサブクラスの中で実装する。"

# YARD::CodeObjects::Base#add_file
#: ../lib/yard/code_objects/base.rb:253
msgid ""
"Associates a file with a code object, optionally adding the line where it "
"was defined.\n"
"By convention, '' should be used to associate code that comes form "
"standard input."
msgstr ""
"コードオブジェクトと共に、ファイルを関連付け、\n"
"定義された場所で任意で行を追加する。\n"
"慣習で、''は、標準入力形式で入って来るコードに関連付けて利用されるべき"
"である。"

# @param [Boolean]
#: ../lib/yard/code_objects/base.rb:260
msgid "tag|param|has_comments"
msgstr "has_comments"

# @param [Fixnum, nil]
#: ../lib/yard/code_objects/base.rb:260 ../lib/yard/i18n/message.rb:34
msgid "tag|param|line"
msgstr "param|line"

# @param [String] file
#: ../lib/yard/code_objects/base.rb:260
msgid "the filename ('' for standard input)"
msgstr "ファイル名('' は標準入力用)"

# @param [Fixnum, nil] line
#: ../lib/yard/code_objects/base.rb:260
msgid "the line number where the object lies in the file"
msgstr "ファイルの中でオブジェクトが位置する,行数"

# @param [Boolean] has_comments
#: ../lib/yard/code_objects/base.rb:260
msgid ""
"whether or not the definition has comments associated. This\n"
"will allow {#file} to return the definition where the comments were made "
"instead\n"
"of any empty definitions that might have been parsed before (module "
"namespaces for instance)."
msgstr ""
"定義が関連付けられたコメントを持っているかどうか。\n"
"これは、解析される前に(例えば、module namespace)、空の定義の代わりに任意の作"
"られたコメントで、\n"
"定義を返す為に、{#file}メソッドを受け入れる。"

# YARD::CodeObjects::Base#file
#: ../lib/yard/code_objects/base.rb:273
msgid ""
"Returns the filename the object was first parsed at, taking\n"
"definitions with docstrings first."
msgstr ""
"オブジェクトが、最初に解析された所で、\n"
"最初のdocstringと共に、定義を取ってくるファイル名を返す"

# @return [String]
#: ../lib/yard/code_objects/base.rb:276
msgid "a filename"
msgstr "ファイル名"

# YARD::CodeObjects::Base#line
#: ../lib/yard/code_objects/base.rb:281
msgid "Returns the line the object was first parsed at (or nil)"
msgstr "オブジェクトが、最初に解析された所(又は、nil)の行を返す"

# @return [nil]
#: ../lib/yard/code_objects/base.rb:284
msgid "if there is no line associated with the object"
msgstr "オブジェクトと共に関連付けられた行がない場合"

# @return [Fixnum]
#: ../lib/yard/code_objects/base.rb:284
msgid "the line where the object was first defined."
msgstr "オブジェクトが最初に定義された所の行"

# YARD::CodeObjects::Base#equal?
# YARD::CodeObjects::Base#==
# YARD::CodeObjects::Base#eql?
#: ../lib/yard/code_objects/base.rb:289 ../lib/yard/code_objects/base.rb:300
#: ../lib/yard/code_objects/base.rb:301
msgid "Tests if another object is equal to this, including a proxy"
msgstr "他のオブジェクトがBaseとイコールかProxyを含んでいるかテストする。"

# @param [Base, Proxy] other
#: ../lib/yard/code_objects/base.rb:292
msgid ""
"if other is a {Proxy}, tests if\n"
"the paths are equal"
msgstr ""
"pathがイコールの場合、\n"
"otherが{Proxy}か、テストする。\n"

# @return [Boolean]
#: ../lib/yard/code_objects/base.rb:292
msgid "whether or not the objects are considered the same"
msgstr "オブジェクトが同じものかどうか判断する"

# @return [Integer]
#: ../lib/yard/code_objects/base.rb:303 ../lib/yard/code_objects/proxy.rb:138
msgid "the object's hash value (for equality checking)"
msgstr "オブジェクトのハッシュ値(イコールかチェック用)"

# @return [nil]
#: ../lib/yard/code_objects/base.rb:306
msgid "this object does not turn into an array"
msgstr "このオブジェクトは配列にはできない"

# YARD::CodeObjects::Base#[]
#: ../lib/yard/code_objects/base.rb:309
msgid "Accesses a custom attribute on the object"
msgstr "オブジェクト上のカスタム属性にアクセスする"

# @param [#to_s]
# @param [String, Symbol]
# @param [#to_sym]
#: ../lib/yard/code_objects/base.rb:312 ../lib/yard/code_objects/base.rb:325
#: ../lib/yard/core_ext/symbol_hash.rb:41
#: ../lib/yard/core_ext/symbol_hash.rb:48
#: ../lib/yard/core_ext/symbol_hash.rb:53
#: ../lib/yard/core_ext/symbol_hash.rb:58 ../lib/yard/options.rb:79
#: ../lib/yard/options.rb:90 ../lib/yard/options.rb:99
#: ../lib/yard/options.rb:204 ../lib/yard/registry_store.rb:31
#: ../lib/yard/registry_store.rb:52 ../lib/yard/registry_store.rb:72
msgid "tag|param|key"
msgstr "key"

# @return [Object, nil]
#: ../lib/yard/code_objects/base.rb:312
msgid "the custom attribute or nil if not found."
msgstr "カスタム属性や見つからなかった場合はnilを返す"

# @param [#to_s] key
#: ../lib/yard/code_objects/base.rb:312 ../lib/yard/code_objects/base.rb:325
msgid "the name of the custom attribute"
msgstr "カスタム属性の名前"

# YARD::CodeObjects::Base#[]=
#: ../lib/yard/code_objects/base.rb:321
msgid "Sets a custom attribute on the object"
msgstr "オブジェクトにカスタム属性を設定する"

# @see
#: ../lib/yard/code_objects/base.rb:325
msgid "tag|see|#[]"
msgstr ""

# @param [Object] value
#: ../lib/yard/code_objects/base.rb:325
msgid "the value to associate"
msgstr "関連する値"

# @overload
#: ../lib/yard/code_objects/base.rb:342
msgid "tag|overload|dynamic_attr_name"
msgstr "dynamic_attr_name"

# @overload
#: ../lib/yard/code_objects/base.rb:342
msgid "tag|overload|dynamic_attr_name="
msgstr "dynamic_attr_name="

# YARD::CodeObjects::Base#source=
#: ../lib/yard/code_objects/base.rb:353
msgid "Attaches source code to a code object with an optional file location"
msgstr ""
"任意のファイルの場所と共にコードオブジェクトの為にソースコードを追加する。"

# @param [#source, String]
# @param
#: ../lib/yard/code_objects/base.rb:357 ../lib/yard/handlers/base.rb:198
#: ../lib/yard/handlers/processor.rb:149
msgid "tag|param|statement"
msgstr "statement"

# @param [#source, String] statement
#: ../lib/yard/code_objects/base.rb:357
msgid ""
"the +Parser::Statement+ holding the source code or the raw source\n"
"as a +String+ for the definition of the code object only (not the block)"
msgstr ""
"+Parser::Statement+ はソースコードや\n"
"コードオブジェクトだけの定義用に(blockではない)\n"
" +String+ のような未加工のソースを保持する。"

# YARD::CodeObjects::Base#docstring=
#: ../lib/yard/code_objects/base.rb:382
msgid ""
"Attaches a docstring to a code object by parsing the comments attached to "
"the statement\n"
"and filling the {#tags} and {#docstring} methods with the parsed information."
msgstr ""
"ステートメントに添付されたコメントを解析する事によって、\n"
"コードオブジェクトにdocstringを追加する。\n"
"そして、解析された情報と共に、{#tags}や{#docstring}メソッドを埋め込む。"

# @param [String, Array, Docstring]
# @param [String]
#: ../lib/yard/code_objects/base.rb:387 ../lib/yard/docstring.rb:310
msgid "tag|param|comments"
msgstr "comments"

# @param [String, Array, Docstring] comments
#: ../lib/yard/code_objects/base.rb:387
msgid ""
"the comments attached to the code object to be parsed\n"
"into a docstring and meta tags."
msgstr ""
"docstringとメタタグの中を解析する為に、コードオブジェクトに追加される,コメン"
"ト"

# YARD::CodeObjects::Base#type
#: ../lib/yard/code_objects/base.rb:402
msgid ""
"Default type is the lowercase class name without the \"Object\" suffix.\n"
"Override this method to provide a custom object type"
msgstr ""
"デフォルトの型は\"Object\"サフィックスなしの小文字のクラス名となる。\n"
"このメソッドを上書きする為にカスタムオブジェクト型を提供する。"

# @return [Symbol]
#: ../lib/yard/code_objects/base.rb:405
msgid "the type of code object this represents"
msgstr "これを表すコードオブジェクトの型"

# YARD::CodeObjects::Base#path
# YARD::CodeObjects::Base#to_s
#: ../lib/yard/code_objects/base.rb:410 ../lib/yard/code_objects/base.rb:426
msgid ""
"Represents the unique path of the object. The default implementation\n"
"joins the path of {#namespace} with {#name} via the value of {#sep}.\n"
"Custom code objects should ensure that the path is unique to the code\n"
"object by either overriding {#sep} or this method."
msgstr ""
"オブジェクトの固有のパスを表す。\n"
"デフォルトの実装は、{#sep}の値を挟んで{#namespace} と {#name}のパスを加え"
"た、\n"
"実装となる。\n"
"カスタムコードオブジェクトは、{#sep}メソッドやこのメソッドによって\n"
"固有のパスが確保されるべきである。"

# @example The path of an instance method
#: ../lib/yard/code_objects/base.rb:418
msgid "MethodObject.new(P(\"A::B\"), :c).path # => \"A::B#c\""
msgstr ""

# @example
#: ../lib/yard/code_objects/base.rb:418
msgid "tag|example|The path of an instance method"
msgstr "インスタンスメソッドのパス"

# @see
#: ../lib/yard/code_objects/base.rb:418
msgid "tag|see|#sep"
msgstr ""

# @return [String]
#: ../lib/yard/code_objects/base.rb:418
msgid "the unique path of the object"
msgstr "オブジェクトの固有のパス"

# @param [Base, String] other
#: ../lib/yard/code_objects/base.rb:430
msgid "another code object (or object path)"
msgstr "他のコードオブジェクト(又は、オブジェクトのパス)"

# @return [String]
#: ../lib/yard/code_objects/base.rb:430
msgid "the shortest relative path from this object to +other+"
msgstr "このオブジェクトから +other+ への最短の相対パス"

# YARD::CodeObjects::Base#format
#: ../lib/yard/code_objects/base.rb:451
msgid "Renders the object using the {Templates::Engine templating system}."
msgstr "{Templates::Engine templating system}によってオブジェクトを表示する。"

# @param [Hash] options
#: ../lib/yard/code_objects/base.rb:463
msgid "a set of options to pass to the template"
msgstr "テンプレートに渡すoptionのグループ"

# @example Formats a method in html with rdoc markup
#: ../lib/yard/code_objects/base.rb:463
msgid "puts P('MyClass#meth').format(:format => :html, :markup => :rdoc)"
msgstr ""

# @example Formats a class in plaintext
#: ../lib/yard/code_objects/base.rb:463
msgid "puts P('MyClass').format"
msgstr ""

# @example
#: ../lib/yard/code_objects/base.rb:463
msgid "tag|example|Formats a class in plaintext"
msgstr "プレーンテキストでクラスを書式化する"

# @example
#: ../lib/yard/code_objects/base.rb:463
msgid "tag|example|Formats a method in html with rdoc markup"
msgstr "rdocマークアップと共に、htmlで、メソッドを書式化する"

# @option
#: ../lib/yard/code_objects/base.rb:463 ../lib/yard/i18n/text.rb:11
#: ../lib/yard/templates/engine.rb:81 ../lib/yard/templates/engine.rb:140
msgid "tag|option|options"
msgstr ""

# @param [Hash]
#: ../lib/yard/code_objects/base.rb:463 ../lib/yard/i18n/text.rb:11
#: ../lib/yard/templates/engine.rb:81 ../lib/yard/templates/engine.rb:100
#: ../lib/yard/templates/engine.rb:140 ../lib/yard/templates/template.rb:37
msgid "tag|param|options"
msgstr ""

# @return [String]
#: ../lib/yard/code_objects/base.rb:463 ../lib/yard/templates/engine.rb:81
msgid "the rendered template"
msgstr "テンプレートを表示する。"

# YARD::CodeObjects::Base#inspect
#: ../lib/yard/code_objects/base.rb:469
msgid "Inspects the object, returning the type and path"
msgstr "オブジェクトを検査し、型とパスを返す。"

# @return [String]
#: ../lib/yard/code_objects/base.rb:470
msgid "a string describing the object"
msgstr "オブジェクトを説明する文字列"

# YARD::CodeObjects::Base#namespace=
# YARD::CodeObjects::Base#parent=
#: ../lib/yard/code_objects/base.rb:475 ../lib/yard/code_objects/base.rb:497
msgid "Sets the namespace the object is defined in."
msgstr "中で定義されるオブジェクトのnamespaceを設定する。"

# @param [String, CodeObjects::Base]
# @param [NamespaceObject, :root, nil]
# @param [MethodObject]
#: ../lib/yard/code_objects/base.rb:479
#: ../lib/yard/code_objects/extended_method_object.rb:16
#: ../lib/yard/templates/helpers/html_helper.rb:309
msgid "tag|param|obj"
msgstr "obj"

# @param [NamespaceObject, :root, nil] obj
#: ../lib/yard/code_objects/base.rb:479
msgid ""
"the new namespace (:root\n"
"for {Registry.root}). If obj is nil, the object is unregistered\n"
"from the Registry."
msgstr ""
"新しいnamespace({Registry.root}用の:root)\n"
"objがnilの場合、記録されたオブジェクトはレジストリから戻される。"

# YARD::CodeObjects::Base#tag
#: ../lib/yard/code_objects/base.rb:499
msgid "Gets a tag from the {#docstring}"
msgstr "{#docstring}メソッドから、取得する。"

# @see
#: ../lib/yard/code_objects/base.rb:500
msgid "tag|see|Docstring#tag"
msgstr ""

# YARD::CodeObjects::Base#tags
#: ../lib/yard/code_objects/base.rb:503
msgid "Gets a list of tags from the {#docstring}"
msgstr "{#docstring}メソッドから、タグのリストを取得する。"

# @see
#: ../lib/yard/code_objects/base.rb:504
msgid "tag|see|Docstring#tags"
msgstr ""

# YARD::CodeObjects::Base#has_tag?
#: ../lib/yard/code_objects/base.rb:507
msgid "Tests if the {#docstring} has a tag"
msgstr "{#docstring}メソッドがタグを持つ場合、テストする。"

# @see
#: ../lib/yard/code_objects/base.rb:508
msgid "tag|see|Docstring#has_tag?"
msgstr ""

# @return [Boolean]
#: ../lib/yard/code_objects/base.rb:511
msgid "whether or not this object is a RootObject"
msgstr "このオブジェクトがRootObjectかどうか"

# YARD::CodeObjects::Base#sep
#: ../lib/yard/code_objects/base.rb:514
msgid ""
"Override this method with a custom component separator. For instance,\n"
"{MethodObject} implements sep as '#' or '.' (depending on if the\n"
"method is instance or class respectively). {#path} depends on this\n"
"value to generate the full path in the form: namespace.path + sep + name"
msgstr ""
"このメソッドは、区切りのカスタム構成を上書きする。\n"
"例えば、{MethodObject}は'#'や'.'のような区切りを実装する。\n"
"(メソッドのインスタンスやクラスの関係に依存している)\n"
"{#path}メソッドは namespace.path + sep + name の形式で、\n"
"フルパスを生成する為、この値に依存している。"

# @return [String]
#: ../lib/yard/code_objects/base.rb:520
msgid ""
"the component that separates the namespace path\n"
"and the name (default is {NSEP})"
msgstr "namespace path と name で区切る構成となる。(デフォルトは{NSEP})"

# YARD::CodeObjects::Base#copyable_attributes
#: ../lib/yard/code_objects/base.rb:525
msgid ""
"Override this method if your code object subclass does not allow\n"
"copying of certain attributes."
msgstr ""

# @see
#: ../lib/yard/code_objects/base.rb:531
msgid "tag|see|#copy_to"
msgstr ""

# @return [Array]
#: ../lib/yard/code_objects/base.rb:531
msgid ""
"the list of instance variable names (without\n"
"\"@\" prefix) that should be copied when {#copy_to} is called"
msgstr ""

# YARD::CodeObjects::Base#format_source
#: ../lib/yard/code_objects/base.rb:540
msgid "Formats source code by removing leading indentation"
msgstr "インデントを読み込み削除する事によってソースコードを書式化する"

# @return [String]
#: ../lib/yard/code_objects/base.rb:543
msgid "formatted source"
msgstr "書式化されたソース"

# @param [Symbol]
# @param [String]
#: ../lib/yard/code_objects/base.rb:543 ../lib/yard/parser/base.rb:25
#: ../lib/yard/server/library_version.rb:120
#: ../lib/yard/templates/helpers/html_helper.rb:134
#: ../lib/yard/templates/helpers/html_helper.rb:154
#: ../lib/yard/templates/helpers/html_helper.rb:557
#: ../lib/yard/templates/helpers/html_syntax_highlight_helper.rb:9
msgid "tag|param|source"
msgstr "source"

# @param [String] source
#: ../lib/yard/code_objects/base.rb:543
msgid "the source code to format"
msgstr "書式化するソースコード"

# YARD::CodeObjects::ClassObject
#: ../lib/yard/code_objects/class_object.rb:3
msgid ""
"A ClassObject represents a Ruby class in source code. It is a "
"{ModuleObject}\n"
"with extra inheritance semantics through the superclass."
msgstr ""
"クラスオブジェクトはソースコードの中のRubyクラスを意味する。\n"
"それは、スーパークラスを介した特別な継承の意味を持つ {ModuleObject} となる。"

# YARD::CodeObjects::ClassObject#superclass
#: ../lib/yard/code_objects/class_object.rb:6
msgid "The {ClassObject} that this class object inherits from in Ruby source."
msgstr "このクラスオブジェクトがRubyのソースから継承する{ClassObject}"

# @return [ClassObject]
#: ../lib/yard/code_objects/class_object.rb:7
msgid "a class object that is the superclass of this one"
msgstr "このクラスオブジェクトのスーパークラスとなるクラスオブジェクトを返す"

# YARD::CodeObjects::ClassObject#initialize
#: ../lib/yard/code_objects/class_object.rb:10
msgid "Creates a new class object in +namespace+ with +name+"
msgstr "+name+ と共に +namespace+ の中で新しいクラスオブジェクトを作成する。"

# @return [ClassObject]
#: ../lib/yard/code_objects/class_object.rb:12
msgid "a new instance of ClassObject"
msgstr "クラスオブジェクトの新しいインスタンス"

# @see
#: ../lib/yard/code_objects/class_object.rb:12
msgid "tag|see|Base.new"
msgstr ""

# YARD::CodeObjects::ClassObject#is_exception?
#: ../lib/yard/code_objects/class_object.rb:30
msgid "Whether or not the class is a Ruby Exception"
msgstr "Ruby Exceptionクラスかどうか"

# @return [Boolean]
#: ../lib/yard/code_objects/class_object.rb:32
msgid "whether the object represents a Ruby exception"
msgstr "Ruby exceptionクラスを表すオブジェクトかどうか"

# YARD::CodeObjects::ClassObject#inheritance_tree
#: ../lib/yard/code_objects/class_object.rb:37
msgid "Returns the inheritance tree of the object including self."
msgstr "自身を含んでいるオブジェクトの継承ツリーを返す"

# @param [Boolean]
#: ../lib/yard/code_objects/class_object.rb:42
#: ../lib/yard/code_objects/module_object.rb:9
msgid "tag|param|include_mods"
msgstr "include_mods"

# @return [Array]
#: ../lib/yard/code_objects/class_object.rb:42
msgid ""
"the list of code objects that make up\n"
"the inheritance tree."
msgstr "継承ツリーを作り上げるコードオブジェクトのリスト"

# @param [Boolean] include_mods
#: ../lib/yard/code_objects/class_object.rb:42
msgid ""
"whether or not to include mixins in the\n"
"inheritance tree."
msgstr "継承ツリーの中でmixinを含んでいるかどうか"

# YARD::CodeObjects::ClassObject#meths
#: ../lib/yard/code_objects/class_object.rb:55
msgid ""
"Returns the list of methods matching the options hash. Returns\n"
"all methods if hash is empty."
msgstr ""
"ハッシュのオプションにマッチするメソッドのリストを返す。\n"
"(ハッシュが空の場合は、全てのメソッド)"

# @option
#: ../lib/yard/code_objects/class_object.rb:63
#: ../lib/yard/code_objects/class_object.rb:98
#: ../lib/yard/code_objects/namespace_object.rb:113
#: ../lib/yard/code_objects/namespace_object.rb:144
#: ../lib/yard/code_objects/namespace_object.rb:164
#: ../lib/yard/handlers/base.rb:355 ../lib/yard/parser/ruby/ast_node.rb:152
#: ../lib/yard/serializers/file_system_serializer.rb:27
#: ../lib/yard/server/adapter.rb:71 ../lib/yard/server/rack_adapter.rb:26
msgid "tag|option|opts"
msgstr "opts"

# @return [Array]
#: ../lib/yard/code_objects/class_object.rb:63
msgid "the list of methods that matched"
msgstr "マッチしたメソッドのリスト"

# @param [Hash] opts
#: ../lib/yard/code_objects/class_object.rb:63
#: ../lib/yard/code_objects/class_object.rb:98
msgid "the options hash to match"
msgstr "マッチするハッシュのオプション"

# YARD::CodeObjects::ClassObject#inherited_meths
#: ../lib/yard/code_objects/class_object.rb:74
msgid "Returns only the methods that were inherited."
msgstr "継承したメソッドだけを返す"

# @return [Array]
#: ../lib/yard/code_objects/class_object.rb:76
msgid "the list of inherited method objects"
msgstr "メソッドオブジェクトを継承したリスト"

# YARD::CodeObjects::ClassObject#constants
#: ../lib/yard/code_objects/class_object.rb:91
msgid "Returns the list of constants matching the options hash."
msgstr "ハッシュのオプションにマッチする定数のリストを返す"

# @return [Array]
#: ../lib/yard/code_objects/class_object.rb:98
msgid "the list of constant that matched"
msgstr "マッチした定数のリスト"

# YARD::CodeObjects::ClassObject#inherited_constants
#: ../lib/yard/code_objects/class_object.rb:104
msgid "Returns only the constants that were inherited."
msgstr "継承された定数だけ返す"

# @return [Array]
#: ../lib/yard/code_objects/class_object.rb:106
msgid "the list of inherited constant objects"
msgstr "定数オブジェクトを継承したリスト"

# YARD::CodeObjects::ClassObject#superclass=
#: ../lib/yard/code_objects/class_object.rb:119
msgid "Sets the superclass of the object"
msgstr "オブジェクトのスーパークラスをグループ化する。"

# @param [Base, Proxy, String, Symbol, nil] object
#: ../lib/yard/code_objects/class_object.rb:122
msgid "the superclass value"
msgstr "スーパークラスの値"

# YARD::CodeObjects::ClassVariableObject
#: ../lib/yard/code_objects/class_variable_object.rb:3
msgid ""
"Represents a class variable inside a namespace. The path is expressed\n"
"in the form \"A::B::@@classvariable\""
msgstr ""
"namespaceの内部でクラス変数を表す。\n"
"パスは、\"A::B::@@クラス変数\"形式で表される。"

# @return [String]
#: ../lib/yard/code_objects/class_variable_object.rb:6
msgid "the class variable's value"
msgstr "クラス変数の値"

# YARD::CodeObjects::ConstantObject
#: ../lib/yard/code_objects/constant_object.rb:3
msgid ""
"A +ConstantObject+ represents a Ruby constant (not a module or class).\n"
"To access the constant's (source code) value, use {#value}."
msgstr ""
"+ConstantObject+ は、Ruby定数を表す。(モジュールやクラスではない)\n"
"定数(ソースコード)の値にアクセスする為には、{#value}メソッドを利用する。"

# YARD::CodeObjects::ConstantObject#value
#: ../lib/yard/code_objects/constant_object.rb:6
msgid "The source code representing the constant's value"
msgstr "定数の値を表しているソースコード"

# @return [String]
#: ../lib/yard/code_objects/constant_object.rb:7
msgid "the value the constant is set to"
msgstr "定数を設定される値"

# YARD::CodeObjects::ExtendedMethodObject
#: ../lib/yard/code_objects/extended_method_object.rb:3
msgid ""
"Represents an instance method of a module that was mixed into the class\n"
"scope of another namespace."
msgstr ""
"他のnamespaceのクラススコープの中へ混ぜられたモジュールのインスタンスメソッド"
"を表す。"

# @see
#: ../lib/yard/code_objects/extended_method_object.rb:6
#: ../lib/yard/code_objects/extended_method_object.rb:21
msgid "tag|see|MethodObject"
msgstr ""

# @return [Symbol]
#: ../lib/yard/code_objects/extended_method_object.rb:10
msgid "always +:class+"
msgstr "常に +:class+"

# YARD::CodeObjects::ExtendedMethodObject#initialize
#: ../lib/yard/code_objects/extended_method_object.rb:13
msgid "Sets up a delegate for {MethodObject} obj."
msgstr "{MethodObject}オブジェクト用に委譲をセットアップする"

# @return [ExtendedMethodObject]
#: ../lib/yard/code_objects/extended_method_object.rb:16
msgid "a new instance of ExtendedMethodObject"
msgstr "ExtendedMethodObjectの新しいインスタンス"

# @param [MethodObject] obj
#: ../lib/yard/code_objects/extended_method_object.rb:16
msgid ""
"the instance method to treat as a mixed in\n"
"class method on another namespace."
msgstr ""
"別のnamespace上でクラスメソッドを混ぜたような処理をする,インスタンスメソッド"

# YARD::CodeObjects::ExtendedMethodObject#method_missing
#: ../lib/yard/code_objects/extended_method_object.rb:19
msgid "Sends all methods to the {MethodObject} assigned in {#initialize}"
msgstr ""
"{MethodObject}が{#initialize}メソッドを割り当てる事によって、\n"
"全てのメソッドを__send__する。"

# YARD::CodeObjects::ExtraFileObject
#: ../lib/yard/code_objects/extra_file_object.rb:3
msgid ""
"An ExtraFileObject represents an extra documentation file (README or other\n"
"file). It is not strictly a CodeObject (does not inherit from `Base`) "
"although\n"
"it implements `path`, `name` and `type`, and therefore should be "
"structurally\n"
"compatible with most CodeObject interfaces."
msgstr ""
"ExtraFileObjectは、追加のドキュメントファイル(README や 他のファイル)を表すけ"
"れど、\n"
"コードオブジェクトに限らず(`Base`から継承はできない)`path`, `name` , `type`を"
"実装できる。\n"
"従って、殆どのCodeObjectインターフェースと互換性があり、構造上両立されるべき"
"である。"

# @param value
#: ../lib/yard/code_objects/extra_file_object.rb:7
msgid "the value to set the attribute filename to."
msgstr "filename属性を設定する値"

# YARD::CodeObjects::ExtraFileObject#filename
#: ../lib/yard/code_objects/extra_file_object.rb:8
msgid "Returns the value of attribute filename"
msgstr "filename属性の値を返す"

# YARD::CodeObjects::ExtraFileObject#filename=
#: ../lib/yard/code_objects/extra_file_object.rb:8
msgid "Sets the attribute filename"
msgstr "filename属性を設定する"

# @param value
#: ../lib/yard/code_objects/extra_file_object.rb:8
msgid "the value to set the attribute attributes to."
msgstr "attributesの属性を設定する値"

# YARD::CodeObjects::ExtraFileObject#attributes
#: ../lib/yard/code_objects/extra_file_object.rb:9
msgid "Returns the value of attribute attributes"
msgstr "attributes属性の値を返す"

# YARD::CodeObjects::ExtraFileObject#attributes=
#: ../lib/yard/code_objects/extra_file_object.rb:9
msgid "Sets the attribute attributes"
msgstr "attributes属性を設定する"

# @param value
#: ../lib/yard/code_objects/extra_file_object.rb:9
#: ../lib/yard/tags/ref_tag_list.rb:4
msgid "the value to set the attribute name to."
msgstr "name属性を設定する値"

# YARD::CodeObjects::ExtraFileObject#name
# YARD::CodeObjects::ExtraFileObject#path
# YARD::Parser::Ruby::Legacy::RubyToken::TkId#name
# YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar#name
# YARD::Tags::RefTagList#name
# YARD::Templates::Section#name
#: ../lib/yard/code_objects/extra_file_object.rb:10
#: ../lib/yard/code_objects/extra_file_object.rb:24
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:79
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:114
#: ../lib/yard/tags/ref_tag_list.rb:5
msgid "Returns the value of attribute name"
msgstr "name属性の値を返す"

# YARD::CodeObjects::ExtraFileObject#name=
# YARD::Tags::RefTagList#name=
# YARD::Templates::Section#name=
#: ../lib/yard/code_objects/extra_file_object.rb:10
#: ../lib/yard/tags/ref_tag_list.rb:5
msgid "Sets the attribute name"
msgstr "name属性を設定する"

# @param value
#: ../lib/yard/code_objects/extra_file_object.rb:10
msgid "the value to set the attribute contents to."
msgstr "値に属性の内容を設定するための値"

# YARD::Parser::Ruby::Legacy::Statement#comments
# YARD::Parser::Ruby::RipperParser#comments
#: ../lib/yard/code_objects/extra_file_object.rb:11
msgid "Returns the value of attribute contents"
msgstr "属性の内容の値を返す"

# YARD::CodeObjects::NamespaceObject#constants=
#: ../lib/yard/code_objects/extra_file_object.rb:11
msgid "Sets the attribute contents"
msgstr "属性の内容を設定する"

# YARD::CodeObjects::ExtraFileObject#initialize
#: ../lib/yard/code_objects/extra_file_object.rb:13
msgid "Creates a new extra file object."
msgstr "新しく追加のファイルオブジェクトを作成する"

# @return [ExtraFileObject]
#: ../lib/yard/code_objects/extra_file_object.rb:16
msgid "a new instance of ExtraFileObject"
msgstr "ExtraFileObjectの新しいインスタンス"

# @param [String]
#: ../lib/yard/code_objects/extra_file_object.rb:16
#: ../lib/yard/templates/helpers/markup_helper.rb:122
msgid "tag|param|contents"
msgstr "contents"

# @param [String, CodeObjects::ExtraFileObject]
# @param [String]
# @param [String, Regexp]
#: ../lib/yard/code_objects/extra_file_object.rb:16
#: ../lib/yard/handlers/base.rb:228 ../lib/yard/parser/base.rb:25
#: ../lib/yard/parser/source_parser.rb:505
#: ../lib/yard/templates/helpers/base_helper.rb:149
#: ../lib/yard/templates/helpers/html_helper.rb:342
msgid "tag|param|filename"
msgstr "filename"

# @param [String] contents
#: ../lib/yard/code_objects/extra_file_object.rb:16
msgid ""
"the file contents. If not set, the contents\n"
"will be read from disk using the +filename+."
msgstr ""
"ファイルの内容となる。設定しない場合、\n"
"contentsは、 +filename+ によってディスクから読み込まれるだろう。"

# @param [String] filename
#: ../lib/yard/code_objects/extra_file_object.rb:16
msgid "the location on disk of the file"
msgstr "ファイルのディスク上の場所"

# @param [String] data
#: ../lib/yard/code_objects/extra_file_object.rb:47
msgid "the file contents"
msgstr "ファイルの内容"

# YARD::CodeObjects::MacroObject
#: ../lib/yard/code_objects/macro_object.rb:6
msgid ""
"A MacroObject represents a docstring defined through +@!macro NAME+ and can "
"be\n"
"reused by specifying the tag +@!macro NAME+. You can also provide the\n"
"+attached+ type flag to the macro definition to have it attached to the\n"
"specific DSL method so it will be implicitly reused."
msgstr ""
"マクロオブジェクトは、+@!macro NAME+ を通じて定義した docstring を表し、\n"
"+@!macro NAME+ タグを指定する事によって、再利用できる。\n"
"あなたは、固有のDSLメソッドに加えるマクロ定義の為に\n"
"+attached+ 型フラグを提供もできる。\n"
"なので、暗黙の内に再利用される。"

# YARD::CodeObjects::MacroObject
#: ../lib/yard/code_objects/macro_object.rb:11
msgid ""
"Macros are fully described in the {file:docs/Tags.md#macro Tags Overview}\n"
"document."
msgstr ""
"マクロは、{file:docs/Tags.md#macros Tags Overview}ドキュメントで詳細に説明さ"
"れている。"

# @example Creating a macro that is attached to the method call
#: ../lib/yard/code_objects/macro_object.rb:29
msgid ""
"# @!macro [attach] prop2\n"
"#   @!method $1(value)\n"
"property :foo\n"
"\n"
"# Extra data added to docstring\n"
"property :bar"
msgstr ""

# @example Creating a basic named macro
#: ../lib/yard/code_objects/macro_object.rb:29
msgid ""
"# @!macro prop\n"
"#   @!method $1(${3-})\n"
"#   @return [$2] the value of the $0\n"
"property :foo, String, :a, :b\n"
"\n"
"# @!macro prop\n"
"property :bar, Numeric, :value"
msgstr ""

# @example
#: ../lib/yard/code_objects/macro_object.rb:29
msgid "tag|example|Creating a basic named macro"
msgstr "一般的なマクロを作成"

# @example
#: ../lib/yard/code_objects/macro_object.rb:29
msgid "tag|example|Creating a macro that is attached to the method call"
msgstr "メソッド呼び出しの為に加えられるマクロを作成する。"

# YARD::CodeObjects::MacroObject.create
#: ../lib/yard/code_objects/macro_object.rb:34
msgid "Creates a new macro and fills in the relevant properties."
msgstr "関連したプロパティのファイルと新しいマクロを作成する。"

# @param [CodeObjects::Base] method_object
#: ../lib/yard/code_objects/macro_object.rb:39
msgid ""
"an object to attach this\n"
"macro to. If supplied, {#attached?} will be true"
msgstr ""
"このマクロに加えるオブジェクト。もし提供された場合、\n"
"{#attached?}はtrueになる。"

# @param [String]
#: ../lib/yard/code_objects/macro_object.rb:39
#: ../lib/yard/code_objects/macro_object.rb:50
#: ../lib/yard/code_objects/macro_object.rb:70
msgid "tag|param|macro_name"
msgstr "macro_name"

# @param [CodeObjects::Base]
#: ../lib/yard/code_objects/macro_object.rb:39
#: ../lib/yard/code_objects/macro_object.rb:70
msgid "tag|param|method_object"
msgstr "method_object"

# @param [String] data
#: ../lib/yard/code_objects/macro_object.rb:39
msgid "the data the macro should expand when re-used"
msgstr "再利用された時、マクロが展開するであろうデータ"

# @param [String] macro_name
#: ../lib/yard/code_objects/macro_object.rb:39
msgid "the name of the macro, must be unique."
msgstr "マクロの名前、固有のものにしなければならない"

# YARD::CodeObjects::MacroObject.find
#: ../lib/yard/code_objects/macro_object.rb:47
msgid "Finds a macro using +macro_name+"
msgstr "+macro_name+ のマクロを見つける"

# @return [MacroObject]
#: ../lib/yard/code_objects/macro_object.rb:50
msgid "if a macro is found"
msgstr "マクロが見つかった場合"

# @return [nil]
#: ../lib/yard/code_objects/macro_object.rb:50
msgid "if there is no registered macro by that name"
msgstr "マクロの名前が記録されない場合"

# @return [String]
#: ../lib/yard/code_objects/macro_object.rb:50
#: ../lib/yard/code_objects/macro_object.rb:70
msgid "the name of the macro"
msgstr "マクロの名前"

# YARD::CodeObjects::MacroObject.find_or_create
# YARD::CodeObjects::MacroObject.create_docstring
#: ../lib/yard/code_objects/macro_object.rb:55
#: ../lib/yard/code_objects/macro_object.rb:78
msgid ""
"Parses a given docstring and determines if the macro is \"new\" or\n"
"not. If the macro has $variable names or if it has a @!macro tag\n"
"with the [new] or [attached] flag, it is considered new."
msgstr ""
"与えらたdocstringを解析しマクロが新しく作成されるものかどうか決める。\n"
"もしマクロが$variable名を持っていた場合や\n"
"[new]や[attached]フラグと一緒に@!macroタグを持っていた場合、\n"
"新規に作成されるものとみなされる。"

# YARD::CodeObjects::MacroObject.find_or_create
# YARD::CodeObjects::MacroObject.create_docstring
#: ../lib/yard/code_objects/macro_object.rb:59
#: ../lib/yard/code_objects/macro_object.rb:82
msgid ""
"If a new macro is found, the macro is created and registered. Otherwise\n"
"the macro name is searched and returned. If a macro is not found,\n"
"nil is returned."
msgstr ""
"新しいマクロが見つかった場合、作成され記録される。\n"
"その他の場合、マクロ名が検索され返される。\n"
"マクロが見つからなかった場合は、nilが返される。"

# @param [CodeObjects::Base] method_object
#: ../lib/yard/code_objects/macro_object.rb:70
msgid ""
"an optional method to attach\n"
"the macro to. Only used if the macro is being created, otherwise\n"
"this argument is ignored."
msgstr ""
"マクロを加える為の任意のメソッド\n"
"マクロが作成される場合、利用されるだけである。\n"
"さもなければ、この引数は無視される。"

# @return [nil]
#: ../lib/yard/code_objects/macro_object.rb:70
msgid ""
"if the +data+ has no macro tag or if the macro is\n"
"not new and no macro by the macro name is found."
msgstr ""
"+data+ がマクロタグを持っていないか、\n"
"マクロが、\"new\"でなかったり、\n"
"macro name is foundによって、マクロ自体が無い場合、nilを返す。"

# @return [MacroObject]
#: ../lib/yard/code_objects/macro_object.rb:70
msgid ""
"the newly created or existing macro, depending\n"
"on whether the @!macro tag was a new tag or not."
msgstr ""
"新たに作成された、又は、既存のマクロを返す。\n"
"@!macroタグはnewタグかそうでないかに依存する。"

# YARD::CodeObjects::MacroObject.expand
#: ../lib/yard/code_objects/macro_object.rb:80
msgid "Expands +macro_data+ using the interpolation parameters."
msgstr "補完の引数によって、 +macro_data+ を展開する。"

# YARD::CodeObjects::MacroObject.expand
#: ../lib/yard/code_objects/macro_object.rb:82
msgid ""
"Interpolation rules:\n"
"* $0, $1, $2, ... = the Nth parameter in +call_params+\n"
"* $* = the full statement source (excluding block)\n"
"* Also supports $!{N-M} ranges, as well as negative indexes on N or M\n"
"* Use \\$ to escape the variable name in a macro."
msgstr ""
"補完のルール:\n"
"* $0, $1, $2, ... = +call_params+ の中のN番目の引数\n"
"* $* = 完全なステートメントのソース(blockを除外する)\n"
"* $!{N-M}の範囲もサポートし,マイナスのインデックスも利用できる\n"
"* マクロの中の変数名のエスケープには\\$を使う"

# @param [String]
#: ../lib/yard/code_objects/macro_object.rb:96
msgid "tag|param|macro_data"
msgstr "マクロデータ"

# @param [String] macro_data
#: ../lib/yard/code_objects/macro_object.rb:96
msgid "the macro data to expand (taken from {#macro_data})"
msgstr "拡張する為のマクロデータ({#macro_data}メソッドから取得する)"

# YARD::CodeObjects::MacroObject.apply
#: ../lib/yard/code_objects/macro_object.rb:114
msgid ""
"Applies a macro on a docstring by creating any macro data inside of\n"
"the docstring first. Equivalent to calling {find_or_create} and "
"{apply_macro}\n"
"on the new macro object."
msgstr ""
"最初にdocstringの内部の何らかのマクロデータを作成する事によって\n"
"docstring上のマクロを適用する。\n"
"{find_or_create}と、\n"
"新しいマクロオブジェクト上で{apply_macro}を呼び出すのは同様である。"

# @param [Docstring]
#: ../lib/yard/code_objects/macro_object.rb:120
msgid "tag|param|docstring"
msgstr "docstring"

# @see
#: ../lib/yard/code_objects/macro_object.rb:120
msgid "tag|see|find_or_create"
msgstr ""

# @param [Docstring] docstring
#: ../lib/yard/code_objects/macro_object.rb:120
msgid "the docstring to create a macro out of"
msgstr "マクロの出力を作成する為のdocstrng"

# YARD::CodeObjects::MacroObject.apply_macro
#: ../lib/yard/code_objects/macro_object.rb:131
msgid ""
"Applies a macro to a docstring, interpolating the macro's data on the\n"
"docstring and appending any extra local docstring data that was in\n"
"the original +docstring+ object."
msgstr ""
"docstringにmacroが適用され、\n"
"docstring上のマクロデータを補完する。\n"
"そして、元の +docstring+ オブジェクトの中の\n"
"任意で加えられるローカルなdocstringのデータを適用する。\n"

# @param [MacroObject]
# @param [CodeObjects::MacroObject]
#: ../lib/yard/code_objects/macro_object.rb:136
msgid "tag|param|macro"
msgstr "macro"

# @param [MacroObject] macro
#: ../lib/yard/code_objects/macro_object.rb:136
msgid "the macro object"
msgstr "マクロオブジェクト"

# @return [String]
#: ../lib/yard/code_objects/macro_object.rb:142
msgid "the macro data stored on the object"
msgstr "マクロ上で記録されるデータ"

# @return [CodeObjects::Base]
#: ../lib/yard/code_objects/macro_object.rb:146
msgid ""
"the method object that this macro is\n"
"attached to."
msgstr "このマクロが追加されるメソッドオブジェクト\n"

# @return [Boolean]
#: ../lib/yard/code_objects/macro_object.rb:149
msgid "whether this macro is attached to a method"
msgstr "このマクロがメソッドに加えられるかどうか"

# YARD::CodeObjects::MacroObject#path
#: ../lib/yard/code_objects/macro_object.rb:152
msgid "Overrides {Base#path} so the macro path is \".macro.MACRONAME\""
msgstr ""

# YARD::CodeObjects::MacroObject#sep
#: ../lib/yard/code_objects/macro_object.rb:155
msgid "Overrides the separator to be '.'"
msgstr ""

# YARD::CodeObjects::MacroObject#expand
#: ../lib/yard/code_objects/macro_object.rb:158
msgid "Expands the macro using"
msgstr "マクロによって展開される"

# @param [Array] call_params
#: ../lib/yard/code_objects/macro_object.rb:167
msgid ""
"a list of tokens that are passed\n"
"to the method call"
msgstr "メソッド呼び出しに渡されるトークンのリスト"

# @example Expanding a Macro
#: ../lib/yard/code_objects/macro_object.rb:167
msgid ""
"macro.expand(%w(property foo bar), 'property :foo, :bar', '') #=>\n"
"  \"...macro data interpolating this line of code...\""
msgstr ""

# @example
#: ../lib/yard/code_objects/macro_object.rb:167
msgid "tag|example|Expanding a Macro"
msgstr "マクロを展開する"

# @param [String]
#: ../lib/yard/code_objects/macro_object.rb:167
msgid "tag|param|block_source"
msgstr "block_source"

# @param [Array]
#: ../lib/yard/code_objects/macro_object.rb:167
msgid "tag|param|call_params"
msgstr "call_params"

# @param [String]
#: ../lib/yard/code_objects/macro_object.rb:167
msgid "tag|param|full_source"
msgstr "full_source"

# @see
#: ../lib/yard/code_objects/macro_object.rb:167
msgid "tag|see|expand"
msgstr ""

# @param [String] full_source
#: ../lib/yard/code_objects/macro_object.rb:167
msgid "the full method call (not including the block)"
msgstr "全てのメソッド呼び出し(blockを含んでいない)"

# @param [String] block_source
#: ../lib/yard/code_objects/macro_object.rb:167
msgid ""
"the source passed in the block of the method\n"
"call, if there is a block."
msgstr "ブロックがある場合、メソッド呼び出しのブロックの中で解析されたソース。"

# YARD::CodeObjects::MethodObject
#: ../lib/yard/code_objects/method_object.rb:3
msgid "Represents a Ruby method in source"
msgstr "ソースの中のRubyメソッドを表す。"

# YARD::CodeObjects::MethodObject#scope
#: ../lib/yard/code_objects/method_object.rb:5
msgid "The scope of the method (+:class+ or +:instance+)"
msgstr "メソッドのスコープ( +:class+ や +:instance+ )"

# @return [Symbol]
#: ../lib/yard/code_objects/method_object.rb:7
msgid "the scope"
msgstr "スコープ"

# YARD::CodeObjects::MethodObject#explicit
# YARD::CodeObjects::MethodObject#explicit=
#: ../lib/yard/code_objects/method_object.rb:10
msgid ""
"Whether the object is explicitly defined in source or whether it was\n"
"inferred by a handler. For instance, attribute methods are generally\n"
"inferred and therefore not explicitly defined in source."
msgstr ""
"オブジェクトがソースの中で明確に定義されるかどうかや、\n"
"それがハンドラーによって推察されたかどうか。\n"
"例えば、大抵メソッドの属性は推察されるが、\n"
"ソースの中で明確に定義されない場合、マーカーはどこも示せない。"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:14
msgid "whether the object is explicitly defined in source."
msgstr "オブジェクトがソースの中で明確に定義されたかどうか"

# YARD::CodeObjects::MethodObject#parameters
# YARD::CodeObjects::MethodObject#parameters=
#: ../lib/yard/code_objects/method_object.rb:17
msgid ""
"Returns the list of parameters parsed out of the method signature\n"
"with their default values."
msgstr ""
"メソッドの用法のデフォルトの値と共に、その出力の解析された引数のリストを返"
"す。"

# @return [Array]
#: ../lib/yard/code_objects/method_object.rb:21
msgid ""
"a list of parameter names followed\n"
"by their default values (or nil)"
msgstr "引数名のデフォルトの値をフォローする(又は、nil)"

# YARD::CodeObjects::MethodObject#initialize
#: ../lib/yard/code_objects/method_object.rb:24
msgid ""
"Creates a new method object in +namespace+ with +name+ and an instance\n"
"or class +scope+"
msgstr ""
"+name+ とインスタンスや +scope+ クラスと共に、\n"
"+namespace+の中で新しいメソッドオブジェクトを作成する。"

# YARD::CodeObjects::MethodObject#initialize
#: ../lib/yard/code_objects/method_object.rb:27
msgid ""
"If scope is +:module+, this object is instantiated as a public\n"
"method in +:class+ scope, but also creates a new (empty) method\n"
"as a private +:instance+ method on the same class or module."
msgstr ""

# @param [Symbol] scope
#: ../lib/yard/code_objects/method_object.rb:33
msgid "+:instance+, +:class+, or +:module+"
msgstr "+:instance+ や +:class+ や +:module+"

# @return [MethodObject]
#: ../lib/yard/code_objects/method_object.rb:33
msgid "a new instance of MethodObject"
msgstr "メソッドオブジェクトの新しいインスタンス"

# @param [Symbol]
#: ../lib/yard/code_objects/method_object.rb:33
msgid "tag|param|scope"
msgstr ""

# @param [String, Symbol] name
#: ../lib/yard/code_objects/method_object.rb:33
msgid "the method name"
msgstr "メソッド名"

# @param [NamespaceObject] namespace
#: ../lib/yard/code_objects/method_object.rb:33
msgid "the namespace"
msgstr "namespace"

# YARD::CodeObjects::MethodObject#scope=
#: ../lib/yard/code_objects/method_object.rb:53
msgid "Changes the scope of an object from :instance or :class"
msgstr ":instanceや:classからオブジェクトのスコープを変更する。"

# @param [Symbol]
#: ../lib/yard/code_objects/method_object.rb:54
msgid "tag|param|v"
msgstr "v"

# @param [Symbol] v
#: ../lib/yard/code_objects/method_object.rb:54
msgid "the new scope"
msgstr "新しいスコープ"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:76
msgid "whether or not the method is the #initialize constructor method"
msgstr "メソッドが#initialize,コンストラクタメソッドかどうか"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:83
msgid ""
"whether or not this method was created as a module\n"
"function"
msgstr "このメソッドがモジュール関数として作成されたかどうか"

# YARD::CodeObjects::MethodObject#attr_info
#: ../lib/yard/code_objects/method_object.rb:88
msgid "Returns the read/writer info for the attribute if it is one"
msgstr "属性がひとつだけの場合、読み/書きする為の情報を返す。"

# @return [nil]
#: ../lib/yard/code_objects/method_object.rb:91
msgid "if the method is not an attribute"
msgstr "メソッドが属性で無い場合"

# @return [SymbolHash]
#: ../lib/yard/code_objects/method_object.rb:91
msgid "if there is information about the attribute"
msgstr "属性についての情報がある場合"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:98
msgid "whether the method is a writer attribute"
msgstr "メソッドがwriter属性かどうか"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:104
msgid "whether the method is a reader attribute"
msgstr "メソッドがreader属性かどうか"

# YARD::CodeObjects::MethodObject#is_attribute?
#: ../lib/yard/code_objects/method_object.rb:109
msgid "Tests if the object is defined as an attribute in the namespace"
msgstr "オブジェクトがnamespaceの中でその属性を定義される場合、テストする。"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:110
msgid "whether the object is an attribute"
msgstr "オブジェクトが属性かどうか"

# YARD::CodeObjects::MethodObject#is_alias?
#: ../lib/yard/code_objects/method_object.rb:116
msgid "Tests if the object is defined as an alias of another method"
msgstr ""
"オブジェクトが別のメソッドがそのエイリアスに定義される場合、テストする。"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:117
msgid "whether the object is an alias"
msgstr "オブジェクトがエイリアスかどうか"

# YARD::CodeObjects::MethodObject#is_explicit?
#: ../lib/yard/code_objects/method_object.rb:123
msgid "Tests boolean {#explicit} value."
msgstr "ブールの{#explicit}メソッドの値をテストする。"

# @return [Boolean]
#: ../lib/yard/code_objects/method_object.rb:125
msgid "whether the method is explicitly defined in source"
msgstr "メソッドがソースの中で明確に定義されるかどうか"

# @return [nil]
#: ../lib/yard/code_objects/method_object.rb:132
msgid "if it does not override a method"
msgstr "メソッドが上書きされない場合"

# @return [MethodObject]
#: ../lib/yard/code_objects/method_object.rb:132
msgid "the object that this method overrides"
msgstr "このメソッドが上書きするオブジェクト"

# YARD::CodeObjects::MethodObject#aliases
#: ../lib/yard/code_objects/method_object.rb:139
msgid "Returns all alias names of the object"
msgstr "オブジェクトの全てのエイリアスの名前を返す"

# @return [Array]
#: ../lib/yard/code_objects/method_object.rb:140
msgid "the alias names"
msgstr "エイリアスの名前"

# YARD::CodeObjects::MethodObject#path
#: ../lib/yard/code_objects/method_object.rb:150
msgid ""
"Override path handling for instance methods in the root namespace\n"
"(they should still have a separator as a prefix)."
msgstr ""
"root namespaseの中のインスタンスメソッド用に操作するパスを上書きする。\n"
"(root namespaseはプレフィックスとして区切りが必要である)"

# @return [String]
#: ../lib/yard/code_objects/method_object.rb:152
msgid "the path of a method"
msgstr "メソッドのパス"

# YARD::CodeObjects::MethodObject#name
#: ../lib/yard/code_objects/method_object.rb:161
msgid "Returns the name of the object."
msgstr "オブジェクトの名前を返す"

# @example The name of a class method (with prefix)
#: ../lib/yard/code_objects/method_object.rb:170
msgid "a_class_method.name(true) # => \"mymethod\""
msgstr ""

# @example The name of an instance method (with prefix)
#: ../lib/yard/code_objects/method_object.rb:170
msgid "an_instance_method.name(true) # => \"#mymethod\""
msgstr ""

# @return [String]
#: ../lib/yard/code_objects/method_object.rb:170
msgid ""
"returns {#sep} + +name+ for an instance method if\n"
"prefix is true"
msgstr ""
"プレフィックスがtrueの場合、インスタンスメソッド用に{#sep} + +name+ を返す"

# @example
#: ../lib/yard/code_objects/method_object.rb:170
msgid "tag|example|The name of a class method (with prefix)"
msgstr "クラスメソッドの名前(プレフィックスを用いる)"

# @example
#: ../lib/yard/code_objects/method_object.rb:170
msgid "tag|example|The name of an instance method (with prefix)"
msgstr "インスタンスメソッドの名前(プレフィックスを用いる)"

# @return [Symbol]
#: ../lib/yard/code_objects/method_object.rb:170
msgid "the name without {#sep} if prefix is set to false"
msgstr "プレフィックスにfalseを設定する場合、{#sep}メソッド無しの名前となる。"

# @param [Boolean] prefix
#: ../lib/yard/code_objects/method_object.rb:170
msgid "whether or not to show the prefix"
msgstr "プレフィックスを見せるかどうか"

# YARD::CodeObjects::MethodObject#sep
#: ../lib/yard/code_objects/method_object.rb:175
msgid ""
"Override separator to differentiate between class and instance\n"
"methods."
msgstr "インスタンスメソッドとクラスの間で区別する為に区切りを上書きする。"

# @return [String]
#: ../lib/yard/code_objects/method_object.rb:177
msgid "\"#\" for an instance method, \".\" for class"
msgstr "インスタンスメソッド用の\"#\"、クラス用の\".\"。"

# YARD::CodeObjects::ModuleObject
#: ../lib/yard/code_objects/module_object.rb:3
msgid "Represents a Ruby module."
msgstr "Rubyモジュールを表す。"

# YARD::CodeObjects::ModuleObject#inheritance_tree
#: ../lib/yard/code_objects/module_object.rb:5
msgid "Returns the inheritance tree of mixins."
msgstr "mixinの継承ツリーを返す"

# @return [Array]
#: ../lib/yard/code_objects/module_object.rb:9
msgid "a list of namespace objects"
msgstr "オブジェクトのnamespaceのリスト"

# @param [Boolean] include_mods
#: ../lib/yard/code_objects/module_object.rb:9
msgid ""
"if true, will include mixed in\n"
"modules (which is likely what is wanted)."
msgstr ""
"trueの場合、mixinされるモジュールを含んでいる(それが何ができそうであるか)"

# YARD::CodeObjects::NamespaceObject
#: ../lib/yard/code_objects/namespace_object.rb:3
msgid ""
"A \"namespace\" is any object that can store other objects within itself.\n"
"The two main Ruby objects that can act as namespaces are modules\n"
"({ModuleObject}) and classes ({ClassObject})."
msgstr ""
"namespaceはそれ自身の中で他のオブジェクトを記録できる任意のオブジェクトとな"
"る。\n"
"namespaceがモジュール({ModuleObject})とクラス({ClassObject})のように振る舞え"
"るオブジェクトとなる。"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:6
msgid "the value to set the attribute child to."
msgstr "child属性を設定する値"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:6
msgid "the value to set the attribute constants to."
msgstr "属性の定数を設定する値"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:6
msgid "the value to set the attribute cvars to."
msgstr "cvars(クラス変数)の属性を設定する値"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:6
msgid "the value to set the attribute meths to."
msgstr "meths(メソッド)属性を設定する値"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:6
msgid "the value to set the attribute mixins to."
msgstr "mixinの属性を設定する値"

# YARD::CodeObjects::NamespaceObject#child=
#: ../lib/yard/code_objects/namespace_object.rb:7
msgid "Sets the attribute child"
msgstr "child属性を設定する"

# YARD::CodeObjects::NamespaceObject#constants=
#: ../lib/yard/code_objects/namespace_object.rb:7
msgid "Sets the attribute constants"
msgstr "定数の属性を設定する"

# YARD::CodeObjects::NamespaceObject#cvars=
#: ../lib/yard/code_objects/namespace_object.rb:7
msgid "Sets the attribute cvars"
msgstr "cvarsの属性を設定する"

# YARD::CodeObjects::NamespaceObject#meths=
#: ../lib/yard/code_objects/namespace_object.rb:7
msgid "Sets the attribute meths"
msgstr "meths属性を設定する"

# YARD::CodeObjects::NamespaceObject#mixins=
#: ../lib/yard/code_objects/namespace_object.rb:7
msgid "Sets the attribute mixins"
msgstr "mixinの属性を設定する"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:7
msgid "the value to set the attribute class_attributes to."
msgstr "class_attributes属性を設定する値"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:7
msgid "the value to set the attribute instance_attributes to."
msgstr "instance_attributes属性を設定する値"

# YARD::CodeObjects::NamespaceObject#class_attributes=
#: ../lib/yard/code_objects/namespace_object.rb:8
msgid "Sets the attribute class_attributes"
msgstr "class_attributes属性を設定する"

# YARD::CodeObjects::NamespaceObject#instance_attributes=
#: ../lib/yard/code_objects/namespace_object.rb:8
msgid "Sets the attribute instance_attributes"
msgstr "instance_attributes属性を設定する"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:8
msgid "the value to set the attribute included_constants to."
msgstr "included_constants属性を設定する値"

# @param value
#: ../lib/yard/code_objects/namespace_object.rb:8
msgid "the value to set the attribute included_meths to."
msgstr "included_meths属性を設定する値"

# YARD::CodeObjects::NamespaceObject#included_constants=
#: ../lib/yard/code_objects/namespace_object.rb:9
msgid "Sets the attribute included_constants"
msgstr "included_constants属性を設定する"

# YARD::CodeObjects::NamespaceObject#included_meths=
#: ../lib/yard/code_objects/namespace_object.rb:9
msgid "Sets the attribute included_meths"
msgstr "included_meths属性を設定する"

# @return [Array]
#: ../lib/yard/code_objects/namespace_object.rb:12
msgid "a list of ordered group names inside the namespace"
msgstr "namespace内部の名前のグループへの命令の入ったリスト"

# YARD::CodeObjects::NamespaceObject#children
#: ../lib/yard/code_objects/namespace_object.rb:15
msgid "The list of objects defined in this namespace"
msgstr "このnamespaceの中で定義されたオブジェクトのリスト"

# @return [Array]
#: ../lib/yard/code_objects/namespace_object.rb:16
msgid "a list of objects"
msgstr "オブジェクトのリスト"

# YARD::CodeObjects::NamespaceObject#attributes
#: ../lib/yard/code_objects/namespace_object.rb:19
msgid ""
"A hash containing two keys, class and instance, each containing\n"
"the attribute name with a { :read, :write } hash for the read and\n"
"write objects respectively."
msgstr ""
"ハッシュはクラスとインスタンスの二つのキーを含んでいる,\n"
"読み書きオブジェクトそれぞれ{:read, :write}ハッシュと共に\n"
"属性の名前をそれぞれ含んでいる。"

# @example The attributes of an object
#: ../lib/yard/code_objects/namespace_object.rb:39
msgid ""
">> Registry.at('YARD::Docstring').attributes\n"
"=> {\n"
"      :class => { },\n"
"      :instance => {\n"
"        :ref_tags => {\n"
"          :read => #,\n"
"          :write => nil\n"
"        },\n"
"        :object => {\n"
"          :read => #,\n"
"          :write => #\n"
"         },\n"
"         ...\n"
"      }\n"
"    }"
msgstr ""

# @return [Hash]
# @param [Array] list
#: ../lib/yard/code_objects/namespace_object.rb:39
#: ../lib/yard/code_objects/namespace_object.rb:44
#: ../lib/yard/templates/helpers/module_helper.rb:10
msgid "a list of methods"
msgstr "メソッドのリスト"

# @example
#: ../lib/yard/code_objects/namespace_object.rb:39
msgid "tag|example|The attributes of an object"
msgstr "オブジェクトの属性"

# YARD::CodeObjects::NamespaceObject#aliases
#: ../lib/yard/code_objects/namespace_object.rb:42
msgid ""
"A hash containing two keys, :class and :instance, each containing\n"
"a hash of objects and their alias names."
msgstr ""
"二つのキーを含んでいるハッシュで,クラスとインスタンスはそれぞれ、\n"
"オブジェクトのハッシュと、そのエイリアスの名前を含んでいる。"

# YARD::CodeObjects::NamespaceObject#class_mixins
#: ../lib/yard/code_objects/namespace_object.rb:47
msgid "Class mixins"
msgstr "mixinのクラス"

# @return [Array]
#: ../lib/yard/code_objects/namespace_object.rb:48
#: ../lib/yard/code_objects/namespace_object.rb:52
#: ../lib/yard/code_objects/namespace_object.rb:194
msgid "a list of mixins"
msgstr "mixinのリスト"

# YARD::CodeObjects::NamespaceObject#instance_mixins
#: ../lib/yard/code_objects/namespace_object.rb:51
msgid "Instance mixins"
msgstr "mixinのインスタンス"

# YARD::CodeObjects::NamespaceObject#initialize
#: ../lib/yard/code_objects/namespace_object.rb:55
msgid "Creates a new namespace object inside +namespace+ with +name+."
msgstr ""
"+name+ と共に、 +namespace+ の内部で新しいnamespaceオブジェクトを作成する。"

# @return [NamespaceObject]
#: ../lib/yard/code_objects/namespace_object.rb:56
msgid "a new instance of NamespaceObject"
msgstr "NamespaceObjectの新しいインスタンス"

# @see
#: ../lib/yard/code_objects/namespace_object.rb:56
msgid "tag|see|Base#initialize"
msgstr ""

# YARD::CodeObjects::NamespaceObject#class_attributes
#: ../lib/yard/code_objects/namespace_object.rb:67
msgid "Only the class attributes"
msgstr "クラス属性だけ"

# @return [Hash]
#: ../lib/yard/code_objects/namespace_object.rb:69
#: ../lib/yard/code_objects/namespace_object.rb:76
msgid "a list of method names and their read/write objects"
msgstr "メソッド名のリストとそれを読み/書きするオブジェクト"

# @see
#: ../lib/yard/code_objects/namespace_object.rb:69
#: ../lib/yard/code_objects/namespace_object.rb:76
msgid "tag|see|#attributes"
msgstr ""

# YARD::CodeObjects::NamespaceObject#instance_attributes
#: ../lib/yard/code_objects/namespace_object.rb:74
msgid "Only the instance attributes"
msgstr "インスタンス属性だけ"

# YARD::CodeObjects::NamespaceObject#child
#: ../lib/yard/code_objects/namespace_object.rb:81
msgid "Looks for a child that matches the attributes specified by +opts+."
msgstr "+opts+に指定された属性にマッチする子を検索する"

# @example Finds a child by name and scope
#: ../lib/yard/code_objects/namespace_object.rb:86
msgid ""
"namespace.child(:name => :to_s, :scope => :instance)\n"
"# => #"
msgstr ""

# @example
#: ../lib/yard/code_objects/namespace_object.rb:86
msgid "tag|example|Finds a child by name and scope"
msgstr "名前とスコープの子を検索する"

# @return [Base, nil]
#: ../lib/yard/code_objects/namespace_object.rb:86
msgid "the first matched child object, or nil"
msgstr "最初にマッチした子のオブジェクト、又はnil"

# YARD::CodeObjects::NamespaceObject#meths
#: ../lib/yard/code_objects/namespace_object.rb:100
msgid ""
"Returns all methods that match the attributes specified by +opts+. If\n"
"no options are provided, returns all methods."
msgstr ""
"+opts+に指定された属性にマッチする全てのメソッドを返す。\n"
"optionが提供されない場合は、全てのメソッドを返す。"

# @param [Hash] opts
#: ../lib/yard/code_objects/namespace_object.rb:113
#: ../lib/yard/code_objects/namespace_object.rb:144
#: ../lib/yard/code_objects/namespace_object.rb:164
#: ../lib/yard/handlers/base.rb:355 ../lib/yard/i18n/text.rb:11
#: ../lib/yard/serializers/file_system_serializer.rb:27
#: ../lib/yard/server/rack_adapter.rb:26
msgid "a customizable set of options"
msgstr "カスタマイズ可能なオプションのグループ"

# @return [Array]
#: ../lib/yard/code_objects/namespace_object.rb:113
msgid "a list of method objects"
msgstr "オブジェクトのメソッドのリスト"

# @example Finds all private and protected class methods
#: ../lib/yard/code_objects/namespace_object.rb:113
msgid ""
"namespace.meths(:visibility => [:private, :protected], :scope => :class)\n"
"# => [#, #]"
msgstr ""

# @example
#: ../lib/yard/code_objects/namespace_object.rb:113
msgid "tag|example|Finds all private and protected class methods"
msgstr "全てのprivateとクラスメソッドのprotectedを検索する"

# YARD::CodeObjects::NamespaceObject#included_meths
#: ../lib/yard/code_objects/namespace_object.rb:133
msgid ""
"Returns methods included from any mixins that match the attributes\n"
"specified by +opts+. If no options are specified, returns all included\n"
"methods."
msgstr ""
"+opts+で指定された属性にマッチする任意のmixinから含んでいるメソッドを返す\n"
"オプションが指定されない場合、全ての含んでいるメソッドを返すmethods."

# @see
#: ../lib/yard/code_objects/namespace_object.rb:144
msgid "tag|see|#meths"
msgstr ""

# YARD::CodeObjects::NamespaceObject#constants
#: ../lib/yard/code_objects/namespace_object.rb:160
msgid "Returns all constants in the namespace"
msgstr "namespaceの中の全ての定数を返す"

# @return [Array]
#: ../lib/yard/code_objects/namespace_object.rb:164
#: ../lib/yard/code_objects/namespace_object.rb:172
msgid "a list of constant objects"
msgstr "定数オブジェクトのリスト"

# YARD::CodeObjects::NamespaceObject#included_constants
#: ../lib/yard/code_objects/namespace_object.rb:171
msgid "Returns constants included from any mixins"
msgstr "任意のmixinから、含んでいる定数を返す"

# YARD::CodeObjects::NamespaceObject#cvars
#: ../lib/yard/code_objects/namespace_object.rb:185
msgid "Returns class variables defined in this namespace."
msgstr "このnamespaseの中で定義されたクラス変数を返す"

# @return [Array]
#: ../lib/yard/code_objects/namespace_object.rb:186
msgid "a list of class variable objects"
msgstr "オブジェクトのクラス変数のリスト"

# YARD::CodeObjects::NamespaceObject#mixins
#: ../lib/yard/code_objects/namespace_object.rb:191
msgid ""
"Returns for specific scopes. If no scopes are provided, returns all mixins."
msgstr "固有のスコープを返す。スコープが提供されない場合、全てのmixinを返す"

# @param [Array] scopes
#: ../lib/yard/code_objects/namespace_object.rb:194
msgid ""
"a list of scopes (:class, :instance) to\n"
"return mixins for. If this is empty, all scopes will be returned."
msgstr ""
"mixinを返す為のスコープのリスト(:class, :instance).\n"
"これが空の場合、全てのスコープが、返されるだろう。"

# @param [Array]
#: ../lib/yard/code_objects/namespace_object.rb:194
msgid "tag|param|scopes"
msgstr "scopes"

# YARD::CodeObjects::ProxyMethodError
#: ../lib/yard/code_objects/proxy.rb:4
msgid "A special type of +NoMethodError+ when raised from a {Proxy}"
msgstr "{Proxy}から、例外が上げられる時の、+NoMethodError+の特別な型"

# YARD::CodeObjects::Proxy
#: ../lib/yard/code_objects/proxy.rb:7
msgid ""
"The Proxy class is a way to lazily resolve code objects in\n"
"cases where the object may not yet exist. A proxy simply stores\n"
"an unresolved path until a method is called on the object, at which\n"
"point it does a lookup using {Registry.resolve}. If the object is\n"
"not found, a warning is raised and {ProxyMethodError} might be raised."
msgstr ""
"Proxyクラスは、オブジェクトがまだ存在しないかもしれないケースで、\n"
"コードオブジェクトを簡単に解決する為の方法である。\n"
"単純にproxyは、メソッドが解決されなかったパスを記録し、\n"
"オブジェクト上で呼び出され{Registry.resolve}によって検索する。\n"
"オブジェクトが見つからない場合、警告がでたり、{ProxyMethodError}が出るかもし"
"れない。"

# @example Creates a Proxy to the String class from a module
#: ../lib/yard/code_objects/proxy.rb:18
msgid ""
"# When the String class is parsed this method will\n"
"# begin to act like the String ClassObject.\n"
"Proxy.new(mymoduleobj, \"String\")"
msgstr ""

# @example
#: ../lib/yard/code_objects/proxy.rb:18
msgid "tag|example|Creates a Proxy to the String class from a module"
msgstr "モジュールからStringクラスの為のProxyを作成する"

# @see
#: ../lib/yard/code_objects/proxy.rb:18
msgid "tag|see|ProxyMethodError"
msgstr ""

# @see
#: ../lib/yard/code_objects/proxy.rb:18
msgid "tag|see|Registry.resolve"
msgstr ""

# YARD::CodeObjects::Proxy#namespace
# YARD::CodeObjects::Proxy#parent
#: ../lib/yard/code_objects/proxy.rb:22 ../lib/yard/code_objects/proxy.rb:23
#: ../lib/yard/handlers/base.rb:315 ../lib/yard/handlers/base.rb:335
msgid "Returns the value of attribute namespace"
msgstr "namespaxe属性の値を返す"

# YARD::CodeObjects::Proxy#initialize
#: ../lib/yard/code_objects/proxy.rb:25
msgid "Creates a new Proxy"
msgstr "新しいProxyを返す"

# @raise [ArgumentError]
#: ../lib/yard/code_objects/proxy.rb:28
msgid "if namespace is not a NamespaceObject"
msgstr "namespaceがNamespaceObjectでない場合"

# YARD::CodeObjects::Proxy#inspect
#: ../lib/yard/code_objects/proxy.rb:76
msgid "Returns a text representation of the Proxy"
msgstr "Proxyのテキスト表現を返す"

# @return [String]
#: ../lib/yard/code_objects/proxy.rb:77
msgid "the object's #inspect method or P(OBJECTPATH)"
msgstr "#inspectメソッドやP(OBJECTPATH)のオブジェクト"

# YARD::CodeObjects::Proxy#path
# YARD::CodeObjects::Proxy#to_s
# YARD::CodeObjects::Proxy#to_str
#: ../lib/yard/code_objects/proxy.rb:86 ../lib/yard/code_objects/proxy.rb:98
#: ../lib/yard/code_objects/proxy.rb:99
msgid ""
"If the proxy resolves to an object, returns its path, otherwise\n"
"guesses at the correct path using the original namespace and name."
msgstr ""
"proxyがオブジェクトを解決する場合、パスを返す。\n"
"他の場合、\n"
"元のnamespaceとnameによって正しいパスを推測する"

# @return [String]
#: ../lib/yard/code_objects/proxy.rb:90
msgid ""
"the assumed path of the proxy (or the real path\n"
"of the resolved object)"
msgstr "proxyのパスを装う(又は、解決したオブジェクトの実際のパス)"

# YARD::CodeObjects::Proxy#class
#: ../lib/yard/code_objects/proxy.rb:141
msgid ""
"Returns the class name of the object the proxy is mimicking, if\n"
"resolved. Otherwise returns +Proxy+."
msgstr ""
"解決した場合、proxyが模倣するオブジェクトのクラス名を返す。\n"
"他の場合、+Proxy+を返す。"

# @return [Class]
#: ../lib/yard/code_objects/proxy.rb:143
msgid "the resolved object's class or +Proxy+"
msgstr "解決したオブジェクトのクラスや +Proxy+"

# YARD::CodeObjects::Proxy#type
#: ../lib/yard/code_objects/proxy.rb:152
msgid ""
"Returns the type of the proxy. If it cannot be resolved at the\n"
"time of the call, it will either return the inferred proxy type\n"
"(see {#type=}) or +:proxy+"
msgstr ""
"proxyの型を返す。呼び出される時間で解決できない場合、\n"
"予想されるproxyの型(see {#type=})や +:proxy+ を返す。"

# @see
#: ../lib/yard/code_objects/proxy.rb:156
msgid "tag|see|#type="
msgstr ""

# @return [Symbol]
#: ../lib/yard/code_objects/proxy.rb:156
msgid "the Proxy's type"
msgstr "Proxyの型"

# YARD::CodeObjects::Proxy#type=
#: ../lib/yard/code_objects/proxy.rb:165
msgid "Allows a parser to infer the type of the proxy by its path."
msgstr "パスによってproxyの型を推測する為に、パーサーを受け入れる。"

# @param [#to_sym]
# @param [Symbol]
#: ../lib/yard/code_objects/proxy.rb:167 ../lib/yard/handlers/ruby/base.rb:102
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:16
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:37
#: ../lib/yard/parser/ruby/ast_node.rb:110
#: ../lib/yard/parser/ruby/ast_node.rb:152
#: ../lib/yard/parser/source_parser.rb:139
#: ../lib/yard/parser/source_parser.rb:181 ../lib/yard/registry.rb:270
#: ../lib/yard/registry.rb:368 ../lib/yard/registry_store.rb:94
#: ../lib/yard/registry_store.rb:103
#: ../lib/yard/templates/helpers/html_helper.rb:154
#: ../lib/yard/templates/helpers/html_helper.rb:364
#: ../lib/yard/templates/helpers/markup_helper.rb:149
#: ../lib/yard/templates/helpers/markup_helper.rb:159
msgid "tag|param|type"
msgstr "type"

# @param [#to_sym] type
#: ../lib/yard/code_objects/proxy.rb:167
msgid "the proxy's inferred type"
msgstr "推察されたproxyの型"

# YARD::CodeObjects::Proxy#method_missing
#: ../lib/yard/code_objects/proxy.rb:189
msgid "Dispatches the method to the resolved object."
msgstr "解決したオブジェクトにメソッドを送る"

# @raise [ProxyMethodError]
#: ../lib/yard/code_objects/proxy.rb:191
msgid "if the proxy cannot find the real object"
msgstr "proxyが実際のオブジェクトを見つけられない場合"

# YARD::CodeObjects::Proxy#root?
#: ../lib/yard/code_objects/proxy.rb:213
msgid "This class is never a root object"
msgstr "このクラスrootオブジェクトにはならない"

# @note
#: ../lib/yard/code_objects/proxy.rb:218
msgid "this method fixes a bug in 1.9.2: http://gist.github.com/437136"
msgstr ""
"このメソッドはバグを修正する。\n"
"(in 1.9.2: http://gist.github.com/4371369)"

# YARD::CodeObjects::Proxy#to_obj
#: ../lib/yard/code_objects/proxy.rb:221
msgid ""
"Attempts to find the object that this unresolved object\n"
"references by checking if any objects by this name are\n"
"registered all the way up the namespace tree."
msgstr ""
"この名前によって任意のオブジェクトが\n"
"namespaceツリーの変更を記録する場合、\n"
"これがチェックするオブジェクトの参照が\n"
"未解決だったオブジェクトを見つける為に試みる。"

# @return [Base, nil]
#: ../lib/yard/code_objects/proxy.rb:225
msgid "the registered code object or nil"
msgstr "記録されるコードオブジェクト、又は、nil"

# YARD::CodeObjects::RootObject
#: ../lib/yard/code_objects/root_object.rb:4
msgid ""
"Represents the root namespace object (the invisible Ruby module that\n"
"holds all top level modules, class and other objects)."
msgstr ""
"root namespaceオブジェクトを表す(全てのtop levelのモジュール,クラス,他のオブ"
"ジェクトを把握する隠れたRubyモジュール)"

# YARD::Config
#: ../lib/yard/config.rb:3
msgid ""
"This class maintains all system-wide configuration for YARD and handles\n"
"the loading of plugins. To access options call {options}, and to load\n"
"a plugin use {load_plugin}. All other public methods are used by YARD\n"
"during load time."
msgstr ""
"このクラスは\n"
"YARDとプラグインのロードを操作するシステム全体の設定を維持する。\n"
"設定を呼び出す{options}にアクセスする為や、\n"
"プラグインを使う{load_plugin}をロードする事を目的に、\n"
"全ての他のpublicなメソッドが、\n"
"ロード中にYARDによって利用される。"

# YARD::Config
#: ../lib/yard/config.rb:8
msgid "== User Configuration Files"
msgstr "== ユーザー設定ファイル"

# YARD::Config
#: ../lib/yard/config.rb:10
msgid ""
"Persistent user configuration files can be stored in the file\n"
"+~/.yard/config+, which is read when YARD first loads. The file should\n"
"be formatted as YAML, and should contain a map of keys and values."
msgstr ""
"persistent(長く使った)ユーザーの設定ファイルは、+~/.yard/config+ ファイルの中"
"に記録される。\n"
"そして、YARDが最初にロードする時に、読み出される。\n"
"このファイルはYAMLのように書式化される、\n"
"そして、キーや値のマップを含んでいるはずである。"

# YARD::Config
#: ../lib/yard/config.rb:14
msgid ""
"Although you can specify any key-value mapping in the configuration file,\n"
"YARD defines special keys specified in {DEFAULT_CONFIG_OPTIONS}."
msgstr ""
"あなたは、設定ファイルの中に任意のキーや値のマッピングを指定できるけれど"
"も、\n"
"YARDは{DEFAULT_CONFIG_OPTIONS}の中の規定の特別なキーを定義する。"

# YARD::Config
#: ../lib/yard/config.rb:17
msgid "An example of a configuration file is listed below:"
msgstr "設定ファイルの例は次のよう記述される。"

# YARD::Config
#: ../lib/yard/config.rb:19
msgid ""
"    !!!yaml\n"
"    load_plugins: true # Auto-load plugins when YARD starts\n"
"    ignored_plugins:\n"
"      - yard-broken\n"
"      - broken2 # yard- prefix not necessary\n"
"    autoload_plugins:\n"
"      - yard-rspec"
msgstr ""

# YARD::Config
#: ../lib/yard/config.rb:27
msgid "== Automatic Loading of Plugins"
msgstr "== プラグインの自動ロード"

# YARD::Config
#: ../lib/yard/config.rb:29
msgid ""
"YARD 0.6.2 will no longer automatically load all plugins by default. This\n"
"option can be reset by setting 'load_plugins' to true in the configuration\n"
"file. In addition, you can specify a set of specific plugins to load on\n"
"load through the 'autoload_plugins' list setting. This setting is\n"
"independent of the 'load_plugins' value and will always be processed."
msgstr ""
"YARD 0.6.2からは、デフォルトで全てのプラグインを自動ロードしない。\n"
"この設定は、設定ファイルの中の'load_plugins'をtrueに設定する事によってリセッ"
"トできる。\n"
"さらに、あなたは、\n"
"'autoload_plugins'リストのセッティングを通して、\n"
"ロード毎に特定のプラグインの設定を指定できる。\n"
"特定のプラグインのグループを指定できる。\n"
"この設定は、'load_plugins'の独自の値となり、そして常に処理されるだろう。"

# YARD::Config
#: ../lib/yard/config.rb:35
msgid "== Ignored Plugins File"
msgstr "== プラグインファイルを無視する"

# YARD::Config
#: ../lib/yard/config.rb:37
msgid ""
"YARD 0.5 and below used a +~/.yard/ignored_plugins+ file to specify\n"
"plugins to be ignored at load time. Ignored plugins in 0.6.2 and above\n"
"should now be specified in the main configuration file, though YARD\n"
"will support the +ignored_plugins+ file until 0.7.x."
msgstr ""
"YARD 0.5やそれ以下では、\n"
"ロード時間で無視されるプラグインを指定する為に\n"
"+~/.yard/ignored_plugins+ ファイルを利用した。\n"
"0.6.2以上で無視されるプラグインは、\n"
"現在、主に設定ファイルの中で規定されるはずである。\n"
"とはいえ,YARDは +ignored_pluginis+ ファイルを0.7.xまで、サポートする。"

# YARD::Config
#: ../lib/yard/config.rb:42
msgid "== Safe Mode"
msgstr "== セーフモード"

# YARD::Config
#: ../lib/yard/config.rb:44
msgid ""
"YARD supports running in safe-mode. By doing this, it will avoid executing\n"
"any user code such as require files or queries. Plugins will still be\n"
"loaded with safe mode on, because plugins are properly namespaced with\n"
"a 'yard-' prefix, must be installed as a gem, and therefore cannot be\n"
"touched by the user. To specify safe mode, use the +safe_mode+ key."
msgstr ""
"YARDはセーフモードでの起動をサポートする。\n"
"これを行うことにより、requireファイルやクエリーのような\n"
"任意のユーザーコードの実行を無効にする。\n"
"しかし、プラグインはセーフモードの実行と共にロードされる。\n"
"何故なら、プラグインは、'yard-'プレフィックスと共に、\n"
"適切にnamespaceが設定され,\n"
"gemのようにインストールされるはずである,\n"
"そして、これ自身の設定はユーザーによって変更できない。\n"
"セーフモードを指定するには、 +safe_mode+ キーを利用する。"

# YARD::Config
#: ../lib/yard/config.rb:50
msgid "== Plugin Specific Configuration"
msgstr "== プラグインの詳細な設定"

# YARD::Config
#: ../lib/yard/config.rb:52
msgid ""
"Additional settings can be defined within the configuration file\n"
"specifically to provide configuration for a plugin. A plugin that utilizes\n"
"the YARD configuration is strongly encouraged to utilize namespacing of\n"
"their configuration content."
msgstr ""
"追加の設定は\n"
"プラグイン用の設定を提供する為に、\n"
"明確に設定ファイルの中で\n"
"定義される。\n"
"YARDの設定を利用するプラグインは、\n"
"その設定内容のnamespaceを利用する為に\n"
"強力に後押しされる。"

# YARD::Config
#: ../lib/yard/config.rb:57
msgid ""
"    !!!yaml\n"
"    load_plugins: true # Auto-load plugins when YARD starts\n"
"    ignored_plugins:\n"
"      - yard-broken\n"
"      - broken2 # yard- prefix not necessary\n"
"    autoload_plugins:\n"
"      - yard-rspec\n"
"    # Plugin Specific Configuration\n"
"    yard-sample-plugin:\n"
"      show-results-inline: true"
msgstr ""

# YARD::Config
#: ../lib/yard/config.rb:68
msgid ""
"As the configuration is available system wide, it can be\n"
"accessed within the plugin code."
msgstr ""
"この設定はシステム全体に及び、\n"
"プラグインのコードの中で、アクセスできる。"

# YARD::Config
#: ../lib/yard/config.rb:72
msgid ""
"    if YARD::Config.options['yard-sample-plugin'] and\n"
"      YARD::Config.options['yard-sample-plugin']['show-results-inline']\n"
"      # ... perform the action that places the results inline ...\n"
"    else\n"
"      # ... do the default behavior of not showing the results inline ...\n"
"    end"
msgstr ""

# YARD::Config
#: ../lib/yard/config.rb:79
msgid ""
"When accessing the configuration, be aware that this file is user managed\n"
"so configuration keys and values may not be present. Make no assumptions "
"and\n"
"instead ensure that you check for the existence of keys before proceeding "
"to\n"
"retrieve values."
msgstr ""
"設定にアクセスする時、\n"
"このファイルはユーザーが扱う事に注意する。\n"
"なので、キーや値の設定は見つからないかもしれない。\n"
"勝手に作成しない代わりに、\n"
"あなたが値を取り出す手続きをする前にキーの存在の管理する事を保証する。"

# @see
#: ../lib/yard/config.rb:85
msgid "tag|see|options"
msgstr ""

# YARD::Config.options
# YARD::Config.options=
#: ../lib/yard/config.rb:88
msgid "The system-wide configuration options for YARD"
msgstr "YARD用のシステム全体の設定オプション"

# @return [SymbolHash]
#: ../lib/yard/config.rb:90
msgid "a map a key-value pair settings."
msgstr "キー,値のペア設定のマップ"

# @see
#: ../lib/yard/config.rb:90
msgid "tag|see|DEFAULT_CONFIG_OPTIONS"
msgstr ""

# YARD::Config::CONFIG_DIR
#: ../lib/yard/config.rb:94
msgid "The location where YARD stores user-specific settings"
msgstr "YARDがユーザー固有の設定を記録する場所"

# YARD::Config::CONFIG_FILE
#: ../lib/yard/config.rb:97
msgid "The main configuration YAML file."
msgstr "YAMLファイルの主な設定"

# YARD::Config::IGNORED_PLUGINS
#: ../lib/yard/config.rb:100
msgid "File listing all ignored plugins"
msgstr "ファイルに記述する、無視されるプラグイン"

# @deprecated
#: ../lib/yard/config.rb:101
msgid "Set `ignored_plugins` in the {CONFIG_FILE} instead."
msgstr "{CONFIG_FILE}の代わりに、`ignored_plugins`を設定する。"

# YARD::Config::DEFAULT_CONFIG_OPTIONS
#: ../lib/yard/config.rb:104
msgid "Default configuration options"
msgstr "デフォルトの設定オプション"

# YARD::Config::YARD_PLUGIN_PREFIX
#: ../lib/yard/config.rb:112
msgid ""
"The prefix used for YARD plugins. Name your gem with this prefix\n"
"to allow it to be used as a plugin."
msgstr ""
"プレフィックスは、YARDプラグイン用に利用される。\n"
"あなたのgemがプラグインの様に利用される為に、\n"
"このプレフィックスと共に名付ける。"

# YARD::Config.load
#: ../lib/yard/config.rb:116
msgid ""
"Loads settings from {CONFIG_FILE}. This method is called by YARD at\n"
"load time and should not be called by the user."
msgstr ""
"{CONFIG_FILE}からの設定をロードする。\n"
"これメソッドは、ロード時間でYARDによって呼び出される。\n"
"そして、ユーザーによって呼び出されないはずである。"

# YARD::Config.save
#: ../lib/yard/config.rb:132
msgid "Saves settings to {CONFIG_FILE}."
msgstr "{CONFIG_FILE}の為の設定を保存する。"

# @deprecated
#: ../lib/yard/config.rb:143
msgid "Use {Config.load_plugins}"
msgstr ""

# @return [Boolean]
#: ../lib/yard/config.rb:143
msgid "true if all plugins loaded successfully, false otherwise."
msgstr "全てのプラグインが正しくロードした場合、true、そうでなければ、false"

# YARD::Config.load_plugin
#: ../lib/yard/config.rb:150
msgid ""
"Loads an individual plugin by name. It is not necessary to include the\n"
"+yard-+ plugin prefix here."
msgstr ""
"名前によって、個々のプラグインをロードする。\n"
"ここで +yard-+ プラグインのプレフィックスを含む必要は無い。"

# @param [String] name
#: ../lib/yard/config.rb:154
msgid "the name of the plugin (with or without +yard-+ prefix)"
msgstr "プラグインの名前( +yard-+ プレフィックスの有無にかかわらず)"

# @return [Boolean]
#: ../lib/yard/config.rb:154
msgid "whether the plugin was successfully loaded"
msgstr "プラグインがロードに成功したかどうか"

# YARD::Config.load_gem_plugins
#: ../lib/yard/config.rb:168
msgid "Load gem plugins if :load_plugins is true"
msgstr ":load_pluginsがtrueの場合、gemプラグインをロードする"

# YARD::Config.load_autoload_plugins
#: ../lib/yard/config.rb:188
msgid "Load plugins set in :autoload_plugins"
msgstr ":autoload_pluginsの中のグループのプラグインをロードする。"

# YARD::Config.load_commandline_plugins
#: ../lib/yard/config.rb:193
msgid "Load plugins from {#arguments}"
msgstr "(#arguments)メソッドからプラグインをロードする。"

# YARD::Config.load_commandline_safemode
#: ../lib/yard/config.rb:203
msgid "Check for command-line safe_mode switch in {#arguments}"
msgstr ""

# YARD::Config.load_plugin_failed
#: ../lib/yard/config.rb:212
msgid "Print a warning if the plugin failed to load"
msgstr "ロードに失敗したプラグインの場合、警告をプリントする。"

# YARD::Config.add_ignored_plugins_file
#: ../lib/yard/config.rb:220
msgid "Legacy support for {IGNORED_PLUGINS}"
msgstr "{IGNORED_PLUGINS}用のレガシーサポート"

# YARD::Config.translate_plugin_names
#: ../lib/yard/config.rb:227
msgid "Translates plugin names to add yard- prefix."
msgstr "yard-プレフィックスを追加する為にプラグイン名を翻訳する。"

# YARD::Config.read_config_file
#: ../lib/yard/config.rb:233
msgid "Loads the YAML configuration file into memory"
msgstr "メモリの中にYAML設定ファイルをロードする。"

# @see
#: ../lib/yard/config.rb:235
msgid "tag|see|CONFIG_FILE"
msgstr ""

# @return [Hash]
#: ../lib/yard/config.rb:235
msgid "the contents of the YAML file from disk"
msgstr "ディスクからのYAMLファイルの内容"

# YARD::Config.translate_plugin_name
#: ../lib/yard/config.rb:245
msgid "Sanitizes and normalizes a plugin name to include the 'yard-' prefix."
msgstr "'yard-'プレフィックスを含んでいるプラグイン名を正規化する。"

# @param [String] name
#: ../lib/yard/config.rb:247
msgid "the plugin name"
msgstr "プラグイン名"

# @return [String]
#: ../lib/yard/config.rb:247
msgid "the sanitized and normalized plugin name."
msgstr "正規化されるプラグイン名"

# YARD::Config.with_yardopts
#: ../lib/yard/config.rb:254
msgid "Temporarily loads .yardopts file into @yardopts"
msgstr "@yardoptsの中に、.yardoptsファイルを一時的にロードする。"

# @return [Array]
#: ../lib/yard/config.rb:263
msgid "arguments from commandline and yardopts file"
msgstr "コマンドラインやyardoptsファイルからの引数"

# Array#place
#: ../lib/yard/core_ext/array.rb:3
msgid ""
"Places values before or after another object (by value) in\n"
"an array. This is used in tandem with the before and after\n"
"methods of the {Insertion} class."
msgstr ""
"配列の前後に他のオブジェクト(値として)の値を置く\n"
"これは、前後に{Insertion}クラスのメソッドを用いている。"

# @example Places an item before another
#: ../lib/yard/core_ext/array.rb:14
msgid "[1, 2, 3].place(4).before(3) # => [1, 2, 4, 3]"
msgstr ""

# @example Places an item after another
#: ../lib/yard/core_ext/array.rb:14
msgid "[:a, :b, :c].place(:x).after(:a) # => [:a, :x, :b, :c]"
msgstr ""

# @return [Insertion]
#: ../lib/yard/core_ext/array.rb:14
msgid "an insertion object to"
msgstr "挿入されたオブジェクト"

# @example
#: ../lib/yard/core_ext/array.rb:14
msgid "tag|example|Places an item after another"
msgstr "後ろに別の要素を置く"

# @example
#: ../lib/yard/core_ext/array.rb:14
msgid "tag|example|Places an item before another"
msgstr "前に別の要素を置く"

# @param [Array]
#: ../lib/yard/core_ext/array.rb:14
msgid "tag|param|values"
msgstr "values"

# @see
#: ../lib/yard/core_ext/array.rb:14
msgid "tag|see|Insertion#after"
msgstr ""

# @see
#: ../lib/yard/core_ext/array.rb:14
msgid "tag|see|Insertion#before"
msgstr ""

# @param [Array] values
#: ../lib/yard/core_ext/array.rb:14
msgid "value to insert"
msgstr "挿入する値"

# File.relative_path
#: ../lib/yard/core_ext/file.rb:10
msgid ""
"Turns a path +to+ into a relative path from starting\n"
"point +from+. The argument +from+ is assumed to be\n"
"a filename. To treat it as a directory, make sure it\n"
"ends in +File::SEPARATOR+ ('/' on UNIX filesystems)."
msgstr ""
"+from+ で始まる場所から、相対パスの情報へパスを変える。\n"
"+from+ の引数は、ファイル名になるように処理される。\n"
"ディレクトリとして取得するには、 +File::SEPARATOR+ で終わる必要がある。\n"
"(UNIX上のファイルシステムなら、'/')"

# File.relative_path
# File.cleanpath
#: ../lib/yard/core_ext/file.rb:18 ../lib/yard/core_ext/file.rb:35
msgid "Manipulating Paths"
msgstr "パスを操作する"

# @param [String]
#: ../lib/yard/core_ext/file.rb:18
msgid "tag|param|from"
msgstr "from"

# @param [String]
#: ../lib/yard/core_ext/file.rb:18
msgid "tag|param|to"
msgstr "to"

# @param [String] to
#: ../lib/yard/core_ext/file.rb:18
msgid "the final path that should be made relative."
msgstr "対応して作られる最後のパス"

# @return [String]
#: ../lib/yard/core_ext/file.rb:18
msgid "the relative path from +from+ to +to+."
msgstr "+from+ から +to+ への相対パス"

# @param [String] from
#: ../lib/yard/core_ext/file.rb:18
msgid ""
"the starting filename\n"
"(or directory with +from_isdir+ set to +true+)."
msgstr ""
"ファイル名(又は +from_isdir+ を +true+ を設定した場合はディレクトリ)の文字列"

# File.cleanpath
#: ../lib/yard/core_ext/file.rb:30
msgid "Cleans a path by removing extraneous '..', '.' and '/' characters"
msgstr "無関係の '..', '.', '/' 文字を削除し、パスをきれいにする。"

# @example Clean a path
#: ../lib/yard/core_ext/file.rb:35
msgid "File.cleanpath('a/b//./c/../e') # => \"a/b/e\""
msgstr ""

# @example
#: ../lib/yard/core_ext/file.rb:35
msgid "tag|example|Clean a path"
msgstr "pathをきれいにする"

# @param [String]
# @param [Array]
# @param [String, :root]
#: ../lib/yard/core_ext/file.rb:35 ../lib/yard/i18n/message.rb:34
#: ../lib/yard/registry.rb:235 ../lib/yard/server.rb:7
#: ../lib/yard/server/doc_server_helper.rb:65
#: ../lib/yard/templates/engine.rb:20 ../lib/yard/templates/engine.rb:34
#: ../lib/yard/templates/engine.rb:52 ../lib/yard/templates/engine.rb:160
#: ../lib/yard/templates/engine.rb:175 ../lib/yard/templates/template.rb:182
msgid "tag|param|path"
msgstr "path"

# @param [String] path
#: ../lib/yard/core_ext/file.rb:35
msgid "the path to clean"
msgstr "きれいにするパス"

# @return [String]
#: ../lib/yard/core_ext/file.rb:35
msgid "the sanitized path"
msgstr "きれいにされたパス"

# File.open!
#: ../lib/yard/core_ext/file.rb:51
msgid ""
"Forces opening a file (for writing) by first creating the file's directory"
msgstr ""
"最初にファイルのディレクトリを作成する事によって、開くファイル(書込み用)を強"
"制する。"

# @since
#: ../lib/yard/core_ext/file.rb:53
msgid "0.5.2"
msgstr ""

# File.open!
# File.read_binary
#: ../lib/yard/core_ext/file.rb:53 ../lib/yard/core_ext/file.rb:62
msgid "Reading Files"
msgstr "ファイルを読み込む"

# @param [String] file
#: ../lib/yard/core_ext/file.rb:53
msgid "the filename to open"
msgstr "展開するファイル名"

# File.read_binary
#: ../lib/yard/core_ext/file.rb:60
msgid "Reads a file with binary encoding"
msgstr "バイナリコードにしてファイルを読み込む"

# @return [String]
#: ../lib/yard/core_ext/file.rb:62
msgid "the ascii-8bit encoded data"
msgstr "ascii-8bitにエンコードされたデータ"

# Insertion
#: ../lib/yard/core_ext/insertion.rb:2
msgid ""
"The Insertion class inserts a value before or after another\n"
"value in a list."
msgstr "Insertionクラスはリストの中の前後に他の値を挿入する。"

# @example 
#: ../lib/yard/core_ext/insertion.rb:6
msgid "Insertion.new([1, 2, 3], 4).before(3) # => [1, 2, 4, 3]"
msgstr ""

# Insertion#initialize
#: ../lib/yard/core_ext/insertion.rb:8
msgid ""
"Creates an insertion object on a list with a value to be\n"
"inserted. To finalize the insertion, call {#before} or\n"
"{#after} on the object."
msgstr ""
"挿入される値と共にリスト上のinsertionオブジェクトを作成する。\n"
"最終的にinsertionは、オブジェクト上の{#before}や{#after}メソッドを呼び出す。"

# @return [Insertion]
#: ../lib/yard/core_ext/insertion.rb:13
msgid "a new instance of Insertion"
msgstr "Insertionの新しいインスタンス"

# @param [Array]
# @param [Array]
# @param [Array]
#: ../lib/yard/core_ext/insertion.rb:13 ../lib/yard/core_ext/insertion.rb:45
#: ../lib/yard/templates/helpers/base_helper.rb:29
#: ../lib/yard/templates/helpers/base_helper.rb:165
#: ../lib/yard/templates/helpers/module_helper.rb:10
#: ../lib/yard/verifier.rb:90
msgid "tag|param|list"
msgstr "list"

# @param [Array] list
#: ../lib/yard/core_ext/insertion.rb:13
msgid "the list to perform the insertion on"
msgstr "insertionで実行するリスト"

# @param [Object] value
# @param [Object] val
#: ../lib/yard/core_ext/insertion.rb:13 ../lib/yard/core_ext/insertion.rb:45
msgid "the value to insert"
msgstr "挿入する値"

# Insertion#before
#: ../lib/yard/core_ext/insertion.rb:16
msgid "Inserts the value before +val+"
msgstr "+val+ の前に値を挿入する"

# @param [Boolean] recursive
#: ../lib/yard/core_ext/insertion.rb:18 ../lib/yard/core_ext/insertion.rb:26
#: ../lib/yard/core_ext/insertion.rb:45
msgid "look inside sublists"
msgstr "ネストした配列の内部をみるかどうか"

# @param [Boolean]
#: ../lib/yard/core_ext/insertion.rb:18 ../lib/yard/core_ext/insertion.rb:26
#: ../lib/yard/core_ext/insertion.rb:45
msgid "tag|param|recursive"
msgstr "recursive"

# @param [Object]
#: ../lib/yard/core_ext/insertion.rb:18 ../lib/yard/core_ext/insertion.rb:26
#: ../lib/yard/core_ext/insertion.rb:45
msgid "tag|param|val"
msgstr "val"

# @param [Object] val
#: ../lib/yard/core_ext/insertion.rb:18
msgid "the object the value will be inserted before"
msgstr "値が前に挿入される,オブジェクト"

# Insertion#after
#: ../lib/yard/core_ext/insertion.rb:21
msgid "Inserts the value after +val+."
msgstr "+val+ の前に値を挿入する"

# @example If subsections are ignored
#: ../lib/yard/core_ext/insertion.rb:26
msgid "Insertion.new([1, [2], 3], :X).after(1) # => [1, [2], :X, 3]"
msgstr ""

# @example
#: ../lib/yard/core_ext/insertion.rb:26
msgid "tag|example|If subsections are ignored"
msgstr "ネストした配列が無視される場合"

# @param [Object] val
#: ../lib/yard/core_ext/insertion.rb:26
msgid "the object the value will be inserted after"
msgstr "値が前に挿入される,オブジェクト"

# Insertion#before_any
#: ../lib/yard/core_ext/insertion.rb:29
msgid "Alias for {#before} with +recursive+ set to true"
msgstr "+recursive+ にtrueを設定する{#before}メソッド用のエイリアス"

# Insertion#after_any
#: ../lib/yard/core_ext/insertion.rb:33
msgid "Alias for {#after} with +recursive+ set to true"
msgstr "+recursive+ にtrueを設定する{#after}メソッド用のエイリアス"

# Insertion#insertion
#: ../lib/yard/core_ext/insertion.rb:39
msgid "This method performs the actual insertion"
msgstr "このメソッドが、実際にinsertionを実行する。"

# @param [Fixnum]
#: ../lib/yard/core_ext/insertion.rb:45
msgid "tag|param|rel"
msgstr "rel"

# @param [Array] list
#: ../lib/yard/core_ext/insertion.rb:45
msgid "the list to place objects into"
msgstr "オブジェクトの情報を置く為のリスト"

# @param [Fixnum] rel
#: ../lib/yard/core_ext/insertion.rb:45
msgid ""
"the relative index (0 or 1) of where the object\n"
"should be placed"
msgstr "オブジェクトが置かれる所の相対インデックス(0又は1)"

# Module#class_name
#: ../lib/yard/core_ext/module.rb:3
msgid "Returns the class name of a full module namespace path"
msgstr "モジュールの完全なnamespaceパスのクラス名を返す"

# @example 
#: ../lib/yard/core_ext/module.rb:7
msgid "module A::B::C; class_name end # => \"C\""
msgstr ""

# @return [String]
#: ../lib/yard/core_ext/module.rb:7
msgid "the last part of a module path"
msgstr "モジュールパスの最後の部分"

# @return [String]
#: ../lib/yard/core_ext/module.rb:16
msgid "the namespace minus the class/module name"
msgstr "クラス/モジュール名を引いたnamespace"

# String#shell_split
#: ../lib/yard/core_ext/string.rb:3
msgid ""
"Splits text into tokens the way a shell would, handling quoted\n"
"text as a single token. Use '\\\"' and \"\\'\" to escape quotes and\n"
"'\\\\' to escape a backslash."
msgstr ""
"シェルの場合テキスト情報のトークンを分割し、\n"
"単一のトークンとしてクオートされたテキストを操作する。\n"
"エスケープをクオートするには、'\\\"'と\"\\'\"、\n"
"バックスラッシュをエスケープするには'\\\\'を使う。"

# @return [Array]
#: ../lib/yard/core_ext/string.rb:7
msgid "an array representing the tokens"
msgstr "トークンを表す配列"

# SymbolHash
#: ../lib/yard/core_ext/symbol_hash.rb:2
msgid ""
"A subclass of Hash where all keys are converted into Symbols, and\n"
"optionally, all String values are converted into Symbols."
msgstr ""
"全てのキーがSymbolsに変換される所のハッシュのサブクラス、\n"
"自由に全てのStringの値をSymblosに変換できる。"

# SymbolHash#initialize
#: ../lib/yard/core_ext/symbol_hash.rb:5
msgid "Creates a new SymbolHash object"
msgstr "新しいSymbolHashオブジェクトを作成する"

# @return [SymbolHash]
#: ../lib/yard/core_ext/symbol_hash.rb:8
msgid "a new instance of SymbolHash"
msgstr "SymbolHashの新しいインスタンス"

# @param [Boolean] symbolize_value
#: ../lib/yard/core_ext/symbol_hash.rb:8
msgid ""
"converts any String values into Symbols\n"
"if this is set to +true+."
msgstr ""
"この設定がtrueの場合、\n"
"全てのStringの値をSymbolへ変換する。"

# @param [Boolean]
#: ../lib/yard/core_ext/symbol_hash.rb:8
msgid "tag|param|symbolize_value"
msgstr "symbolize_value"

# @overload
#: ../lib/yard/core_ext/symbol_hash.rb:27
msgid "tag|overload|[]"
msgstr ""

# SymbolHash#[]=
#: ../lib/yard/core_ext/symbol_hash.rb:38
msgid "Assigns a value to a symbolized key"
msgstr "シンボル化されたキーに値を割り当てる"

# @param [#to_sym] key
#: ../lib/yard/core_ext/symbol_hash.rb:41
msgid "the key"
msgstr "キー"

# @param [Object] value
#: ../lib/yard/core_ext/symbol_hash.rb:41
msgid ""
"the value to be assigned. If this is a String and\n"
"values are set to be symbolized, it will be converted into a Symbol."
msgstr ""
"割り当てられる値。\n"
"これが、文字列の場合には、値がシンボル化される為に設定され、\n"
"シンボルへ変換されるだろう。"

# SymbolHash#[]
#: ../lib/yard/core_ext/symbol_hash.rb:46
msgid "Accessed a symbolized key"
msgstr "シンボル化されるキーにアクセスされる"

# @param [#to_sym] key
#: ../lib/yard/core_ext/symbol_hash.rb:48
msgid "the key to access"
msgstr "アクセスする為のキー"

# @return [Object]
#: ../lib/yard/core_ext/symbol_hash.rb:48
msgid "the value associated with the key"
msgstr "キーに関連付けられた値"

# SymbolHash#delete
#: ../lib/yard/core_ext/symbol_hash.rb:51
msgid "Deleted a key and value associated with it"
msgstr "関連付けられたキーと値が削除される"

# @param [#to_sym] key
#: ../lib/yard/core_ext/symbol_hash.rb:53 ../lib/yard/registry_store.rb:72
msgid "the key to delete"
msgstr "削除するキー"

# SymbolHash#has_key?
#: ../lib/yard/core_ext/symbol_hash.rb:56
msgid "Tests if a symbolized key exists"
msgstr "シンボル化されたキーがあるかテストする"

# @param [#to_sym] key
#: ../lib/yard/core_ext/symbol_hash.rb:58
msgid "the key to test"
msgstr "テストするキー"

# @return [Boolean]
#: ../lib/yard/core_ext/symbol_hash.rb:58
msgid "whether the key exists"
msgstr "キーが存在するかどうか"

# SymbolHash#update
# SymbolHash#merge!
#: ../lib/yard/core_ext/symbol_hash.rb:61
#: ../lib/yard/core_ext/symbol_hash.rb:67
msgid ""
"Updates the object with the contents of another Hash object.\n"
"This method modifies the original SymbolHash object"
msgstr ""
"他のハッシュオブジェクトの内容と共にオブジェクトを更新する。\n"
"このメソッドは元のSymbolHashオブジェクトを変更する。"

# @param [Hash]
#: ../lib/yard/core_ext/symbol_hash.rb:65
#: ../lib/yard/core_ext/symbol_hash.rb:72
msgid "tag|param|hash"
msgstr ""

# @param [Hash] hash
#: ../lib/yard/core_ext/symbol_hash.rb:65
msgid "the hash object to copy the values from"
msgstr "ハッシュオブジェクトから値をコピーする,ハッシュ"

# SymbolHash#merge
#: ../lib/yard/core_ext/symbol_hash.rb:69
msgid "Merges the contents of another hash into a new SymbolHash object"
msgstr "新しいSymbolHashオブジェクトへ他のハッシュの内容をマージする。"

# @return [SymbolHash]
#: ../lib/yard/core_ext/symbol_hash.rb:72
msgid "a new SymbolHash containing the merged data"
msgstr "マージされたデータを含んでいる新しいSymbolHash"

# @param [Hash] hash
#: ../lib/yard/core_ext/symbol_hash.rb:72
msgid "the hash of objects to copy"
msgstr "コピーするオブジェクトのハッシュ"

# YARD::Docstring
#: ../lib/yard/docstring.rb:3
msgid ""
"A documentation string, or \"docstring\" for short, encapsulates the\n"
"comments and metadata, or \"tags\", of an object. Meta-data is expressed\n"
"in the form +@tag VALUE+, where VALUE can span over multiple lines as\n"
"long as they are indented. The following +@example+ tag shows how tags\n"
"can be indented:"
msgstr ""
"documentation stringを略して\"docstring\"は、\n"
"コメントやメタデータ,オブジェクトのタグをカプセル化する。\n"
"メタデータは +@tag VALUE+ から\n"
"VALUEがインデントされる間の複数行に渡って表される。\n"
"次の +@example+ タグは\n"
"タグがどのようにインデントされるか表す。"

# YARD::Docstring
#: ../lib/yard/docstring.rb:9
msgid ""
"  # @example My example\n"
"  #   a = \"hello world\"\n"
"  #   a.reverse\n"
"  # @version 1.0"
msgstr ""

# YARD::Docstring
#: ../lib/yard/docstring.rb:14
msgid ""
"Tags can be nested in a documentation string, though the {Tags::Tag}\n"
"itself is responsible for parsing the inner tags."
msgstr ""
"タグはドキュメント文字列の中でネストされ、{Tags::Tag}自身は、\n"
"中のタグを解析する責任がある。"

# @note
#: ../lib/yard/docstring.rb:27
msgid ""
"Plugin developers should make sure to reset this value\n"
"after parsing finishes. This can be done via the\n"
"{Parser::SourceParser.after_parse_list} callback. This will\n"
"ensure that YARD can properly parse multiple projects in\n"
"the same process."
msgstr ""

# @param [Docstring]
#: ../lib/yard/docstring.rb:27
msgid "tag|see|DocstringParser"
msgstr ""

# @see
#: ../lib/yard/docstring.rb:27
msgid "tag|see|Parser::SourceParser.after_parse_list"
msgstr ""

# @return [Class]
#: ../lib/yard/docstring.rb:27
msgid ""
"the parser class used to parse\n"
"text and optional meta-data from docstrings. Defaults to\n"
"{DocstringParser}."
msgstr ""

# YARD::Docstring.parser
#: ../lib/yard/docstring.rb:30
msgid ""
"Creates a parser object using the current {default_parser}.\n"
"Equivalent to:\n"
"  Docstring.default_parser.new(*args)"
msgstr ""

# @param args
#: ../lib/yard/docstring.rb:37
msgid ""
"arguments are passed to the {DocstringParser}\n"
"class. See {DocstringParser#initialize} for details on\n"
"arguments."
msgstr ""

# @return [Object, nil]
#: ../lib/yard/docstring.rb:37
msgid ""
"the parser object used to parse a\n"
"docstring."
msgstr "docstringを解析する為に利用したパーサーオブジェクト。"

# @return [Array]
#: ../lib/yard/docstring.rb:43
msgid "the list of reference tags"
msgstr "参照タグのリスト"

# @return [CodeObjects::Base]
#: ../lib/yard/docstring.rb:46
msgid "the object that owns the docstring."
msgstr "docstring自身のオブジェクト"

# @return [Range]
#: ../lib/yard/docstring.rb:49
msgid "line range in the {#object}'s file where the docstring was parsed from"
msgstr "解析されるdocstringの{#object}ファイルの中のline range"

# @return [String]
#: ../lib/yard/docstring.rb:52
msgid "the raw documentation (including raw tag text)"
msgstr "未加工のドキュメント(未加工のタグテキストを含んでいる)"

# @return [Boolean]
#: ../lib/yard/docstring.rb:55
msgid "whether the docstring was started with \"##\""
msgstr "docstringが\"##\"と共に記録される"

# YARD::Docstring::META_MATCH
#: ../lib/yard/docstring.rb:59
msgid "Matches a tag at the start of a comment line"
msgstr "コメント行の始まりでタグにマッチする。"

# @deprecated
#: ../lib/yard/docstring.rb:60
msgid "Use {DocstringParser::META_MATCH}"
msgstr ""

# YARD::Docstring.new!
#: ../lib/yard/docstring.rb:65
msgid ""
"Creates a new docstring without performing any parsing through\n"
"a {DocstringParser}. This method is called by +DocstringParser+\n"
"when creating the new docstring object."
msgstr ""

# YARD::Docstring#initialize
# YARD::Docstring#+
# YARD::Docstring#replace
# YARD::Docstring#dup
#: ../lib/yard/docstring.rb:74 ../lib/yard/docstring.rb:99
#: ../lib/yard/docstring.rb:112 ../lib/yard/docstring.rb:123
#: ../lib/yard/docstring.rb:129 ../lib/yard/docstring.rb:138
msgid "Creating a Docstring Object"
msgstr "Docstringオブジェクトを作成する"

# @param [String]
#: ../lib/yard/docstring.rb:74
msgid "tag|param|raw_data"
msgstr ""

# @param [Tags::Tag, Tags::RefTag]
#: ../lib/yard/docstring.rb:74 ../lib/yard/docstring.rb:214
msgid "tag|param|tags"
msgstr ""

# @param [String]
#: ../lib/yard/docstring.rb:74 ../lib/yard/parser/ruby/legacy/ruby_lex.rb:48
#: ../lib/yard/serializers/stdout_serializer.rb:25
#: ../lib/yard/tags/default_factory.rb:12
#: ../lib/yard/tags/default_factory.rb:21
#: ../lib/yard/tags/default_factory.rb:32
#: ../lib/yard/tags/default_factory.rb:44
#: ../lib/yard/tags/default_factory.rb:56
#: ../lib/yard/tags/default_factory.rb:98 ../lib/yard/tags/tag.rb:43
#: ../lib/yard/templates/helpers/html_helper.rb:16
#: ../lib/yard/templates/helpers/html_helper.rb:24
#: ../lib/yard/templates/helpers/html_helper.rb:36
#: ../lib/yard/templates/helpers/html_helper.rb:57
#: ../lib/yard/templates/helpers/html_helper.rb:73
#: ../lib/yard/templates/helpers/html_helper.rb:83
#: ../lib/yard/templates/helpers/html_helper.rb:91
#: ../lib/yard/templates/helpers/html_helper.rb:101
#: ../lib/yard/templates/helpers/html_helper.rb:109
#: ../lib/yard/templates/helpers/html_helper.rb:123
#: ../lib/yard/templates/helpers/html_helper.rb:180
#: ../lib/yard/templates/helpers/uml_helper.rb:26
msgid "tag|param|text"
msgstr ""

# @param [String] raw_data
#: ../lib/yard/docstring.rb:74
msgid ""
"the complete docstring, including all\n"
"original formatting and any unparsed tags/directives."
msgstr ""

# YARD::CodeObjects::Base#tags
#: ../lib/yard/docstring.rb:74
msgid "the list of tag objects in the docstring"
msgstr "docstringの中のタグオブジェクトのリスト"

# @param [CodeObjects::Base] object
#: ../lib/yard/docstring.rb:74
msgid ""
"the object associated with the\n"
"docstring. May be nil."
msgstr "docstringと共に関連したオブジェクト, nilになるかもしれない。"

# @return [CodeObjects::Base]
#: ../lib/yard/docstring.rb:74
msgid "the textual portion of the docstring"
msgstr "docstringの原文の一部"

# YARD::Docstring#initialize
#: ../lib/yard/docstring.rb:84
msgid ""
"Creates a new docstring with the raw contents attached to an optional\n"
"object. Parsing will be done by the {DocstringParser} class."
msgstr ""
"任意のオブジェクトに追加された未加工のコンテンツを用い新しいdocstringを作成する。\n"
"解析は {DocstringParser} クラスによって完了する。"

# @example 
#: ../lib/yard/docstring.rb:99
msgid "Docstring.new(\"hello world\\n@return Object return\", someobj)"
msgstr ""

# @note
#: ../lib/yard/docstring.rb:99
msgid ""
"To properly parse directives with proper parser context within\n"
"handlers, you should not use this method to create a Docstring.\n"
"Instead, use the {parser}, which takes a handler object that\n"
"can pass parser state onto directives. If a Docstring is created\n"
"with this method, directives do not have access to any parser\n"
"state, and may not function as expected."
msgstr ""

# @return [Docstring]
#: ../lib/yard/docstring.rb:99
msgid "a new instance of Docstring"
msgstr "Docstringの新しいインスタンス"

# @param [CodeObjects::Base] object
#: ../lib/yard/docstring.rb:99
msgid ""
"an object to associate the docstring\n"
"with."
msgstr "docstringと関連するオブジェクト"

# @param [TokenList, String]
# @param [String]
# @param [String, #read, Object]
#: ../lib/yard/docstring.rb:99 ../lib/yard/docstring.rb:123
#: ../lib/yard/docstring_parser.rb:106 ../lib/yard/docstring_parser.rb:123
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:16
#: ../lib/yard/parser/source_parser.rb:116
#: ../lib/yard/parser/source_parser.rb:125
#: ../lib/yard/parser/source_parser.rb:416
#: ../lib/yard/parser/source_parser.rb:460
msgid "tag|param|content"
msgstr "内容"

# @param [String] content
#: ../lib/yard/docstring.rb:99
msgid ""
"the raw comments to be parsed into a docstring\n"
"and associated meta-data."
msgstr "docstring,関連するメタデータの中で解析される未加工の内容,"

# YARD::Docstring#+
#: ../lib/yard/docstring.rb:108
msgid "Adds another {Docstring}, copying over tags."
msgstr "別の{Docstring}を追加し、タグをコピーする。"

# @return [Docstring]
#: ../lib/yard/docstring.rb:112
msgid "a new docstring with both docstrings combines"
msgstr "docstring化し,一体化(別のdocstringと)した、新しいdocstring"

# @param [Docstring, String] other
#: ../lib/yard/docstring.rb:112
msgid ""
"the other docstring (or string) to\n"
"add."
msgstr "他の追加するdocstring(やstring)"

# YARD::Docstring#replace
# YARD::Docstring#all=
#: ../lib/yard/docstring.rb:122 ../lib/yard/docstring.rb:130
msgid "Replaces the docstring with new raw content. Called by {#all=}."
msgstr ""
"{#all=}メソッドが呼ばれる事によって、新しい整形前の内容にdocstringを置換す"
"る。"

# @param [String] content
#: ../lib/yard/docstring.rb:123
msgid "the raw comments to be parsed"
msgstr "解析される未加工のコメント"

# YARD::Docstring#dup
#: ../lib/yard/docstring.rb:132
msgid "Deep-copies a docstring"
msgstr "docstringを深い階層までコピーする。"

# @note
#: ../lib/yard/docstring.rb:138
msgid ""
"This method creates a new docstring with new tag lists, but does\n"
"not create new individual tags. Modifying the tag objects will still\n"
"affect the original tags."
msgstr ""
"このメソッドは新しいタグリストと共に新しいdocstringを作成する。\n"
"しかし、新しい個々のタグは作成できない。\n"
"タグオブジェクトを変更すると、元のタグに影響するだろう。"

# @return [Docstring]
#: ../lib/yard/docstring.rb:138
msgid "a new copied docstring"
msgstr "新しくコピーされたdocstring"

# @return [nil]
#: ../lib/yard/docstring.rb:151
msgid "if there is no associated {#line_range}"
msgstr "{#line_range}メソッドに関係ない場合"

# @return [Fixnum]
#: ../lib/yard/docstring.rb:151
msgid "the first line of the {#line_range}"
msgstr "{#line_range}メソッドの最初の行"

# YARD::Docstring#summary
#: ../lib/yard/docstring.rb:156
msgid ""
"Gets the first line of a docstring to the period or the first paragraph."
msgstr ""
"ピリオドや最初の段落の為に、\n"
"docstringの最初の行を取得する。"

# @return [String]
#: ../lib/yard/docstring.rb:157
msgid ""
"The first line or paragraph of the docstring; always ends with a period."
msgstr "docstringの最初の行や段落、そして常にperiodと共に終わる。"

# YARD::Docstring#to_raw
#: ../lib/yard/docstring.rb:181
msgid ""
"Reformats and returns a raw representation of the tag data using the\n"
"current tag and docstring data, not the original text."
msgstr ""
"再書式化し返す、\n"
"現在のタグやdocstringデータによって\n"
"未加工のタグデータで表される。\n"
"しかし元のテキストではない。"

# @todo
#: ../lib/yard/docstring.rb:186
msgid "Add Tags::Tag#to_raw and refactor"
msgstr "Tags::Tag#to_rawメソッドや再編集を追加する"

# @return [String]
#: ../lib/yard/docstring.rb:186
msgid "the updated raw formatted docstring data"
msgstr "更新され書式化される未加工のdocstringのデータ"

# YARD::Docstring#add_tag
#: ../lib/yard/docstring.rb:209
msgid ""
"Adds a tag or reftag object to the tag list. If you want to parse\n"
"tag data based on the {Tags::DefaultFactory} tag factory, use\n"
"{DocstringParser} instead."
msgstr ""
"タグのリストにタグや参照タグオブジェクトを追加する。\n"
"あなたが、 {Tags::DefaultFactory} タグファクトリーを元にしたタグデータを解析したい場合\n"
"代わりに {DocstringParser} を使う。"

# YARD::Docstring#create_tag
# YARD::Docstring#add_tag
# YARD::Docstring#tag
# YARD::Docstring#tags
# YARD::Docstring#has_tag?
# YARD::Docstring#delete_tags
# YARD::Docstring#delete_tag_if
# YARD::Docstring#blank?
#: ../lib/yard/docstring.rb:214 ../lib/yard/docstring.rb:237
#: ../lib/yard/docstring.rb:245 ../lib/yard/docstring.rb:255
#: ../lib/yard/docstring.rb:263 ../lib/yard/docstring.rb:272
#: ../lib/yard/docstring.rb:282 ../lib/yard/docstring.rb:297
#: ../lib/yard/docstring.rb:310
msgid "Creating and Accessing Meta-data"
msgstr "メタデータを作成しアクセスする。"

# @param [Tags::Tag, Tags::RefTag] tags
#: ../lib/yard/docstring.rb:214
msgid "list of tag objects to add"
msgstr "追加のタグオブジェクトのリスト"

# YARD::Docstring#tag
#: ../lib/yard/docstring.rb:229
msgid ""
"Convenience method to return the first tag\n"
"object in the list of tag objects of that name"
msgstr ""
"タグオブジェクトのリストのような名前の中の、\n"
"最初のタグオブジェクトを返す為の便利なメソッド。"

# @example 
#: ../lib/yard/docstring.rb:237
msgid ""
"doc = Docstring.new(\"@return zero when nil\")\n"
"doc.tag(:return).text  # => \"zero when nil\""
msgstr ""

# @return [Tags::Tag]
#: ../lib/yard/docstring.rb:237
msgid "the first tag in the list of {#tags}"
msgstr "{#tags}メソッドのリストの中の、最初のタグ"

# @param [#to_s] name
#: ../lib/yard/docstring.rb:237
msgid "the tag name to return data for"
msgstr "データを返す為のタグ名"

# YARD::Docstring#tags
#: ../lib/yard/docstring.rb:242
msgid ""
"Returns a list of tags specified by +name+ or all tags if +name+ is not "
"specified."
msgstr ""
"+name+ が指定されない場合、\n"
"+name+ やallタグによって指定されたタグのリストを返す"

# @return [Array]
#: ../lib/yard/docstring.rb:245
msgid "the list of tags by the specified tag name"
msgstr "指定されたタグ名によってタグのリストとなる。"

# @param [#to_s] name
#: ../lib/yard/docstring.rb:245
msgid "the tag name to return data for, or nil for all tags"
msgstr "データからタグ名を返す、又は、nilの場合、全てのタグ。"

# YARD::Docstring#has_tag?
#: ../lib/yard/docstring.rb:252
msgid "Returns true if at least one tag by the name +name+ was declared"
msgstr "宣言されるnameのタグ名が1つでもあれば、trueを返す。"

# @param [String] name
#: ../lib/yard/docstring.rb:255
msgid "the tag name to search for"
msgstr "検索の為のタグ名"

# @return [Boolean]
#: ../lib/yard/docstring.rb:255
msgid "whether or not the tag +name+ was declared"
msgstr "タグ +name+が宣言されるかどうか\n"

# YARD::Docstring#delete_tags
#: ../lib/yard/docstring.rb:260
msgid "Delete all tags with +name+"
msgstr "全てのタグ +name+ を用いた削除する。"

# @param [Symbol] tag
# @param [String] tag_name
# @param [String] name
#: ../lib/yard/docstring.rb:263 ../lib/yard/docstring_parser.rb:185
#: ../lib/yard/tags/library.rb:100
msgid "the tag name"
msgstr "タグ名"

# YARD::Docstring#delete_tag_if
#: ../lib/yard/docstring.rb:268
msgid "Deletes all tags where the block returns true"
msgstr "ブロックがtrueを返す所で全てのタグを削除する。"

# @yieldparam [Tags::Tag]
#: ../lib/yard/docstring.rb:272
msgid "tag|yieldparam|tag"
msgstr "tag"

# @yieldparam [Tags::Tag] tag
#: ../lib/yard/docstring.rb:272
msgid "the tag that is being tested"
msgstr "試されるタグ"

# @yieldreturn [Boolean]
#: ../lib/yard/docstring.rb:272
msgid "true if the tag should be deleted"
msgstr "タグが削除される場合、true"

# YARD::Docstring#blank?
#: ../lib/yard/docstring.rb:278
msgid ""
"Returns true if the docstring has no content that is visible to a template."
msgstr "docstringがテンプレートの為、明確な内容を持たない場合、trueを返す。"

# @param [Boolean]
#: ../lib/yard/docstring.rb:282
msgid "tag|param|only_visible_tags"
msgstr "only_visible_tags"

# @param [Boolean] only_visible_tags
#: ../lib/yard/docstring.rb:282
msgid ""
"whether only {Tags::Library.visible_tags}\n"
"should be checked, or if all tags should be considered."
msgstr ""
"{Tags::Library.visible_tags}が、チェックされるかどうか、\n"
"又は、全てのタグが考慮される場合"

# @return [Boolean]
#: ../lib/yard/docstring.rb:282
msgid "whether or not the docstring has content"
msgstr "docstringが内容を持っているかどうか"

# YARD::Docstring#convert_ref_tags
#: ../lib/yard/docstring.rb:295
msgid "Maps valid reference tags"
msgstr "有効な参照タグをマップする"

# @return [Array]
#: ../lib/yard/docstring.rb:297
msgid "the list of valid reference tags"
msgstr "有効な参照タグのリストを返す"

# YARD::Docstring#parse_comments
#: ../lib/yard/docstring.rb:303
msgid "Parses out comments split by newlines into a new code object"
msgstr "新しいコードオブジェクトの中の改行によって分割されるコメントを解析する"

# @param [String] comments
#: ../lib/yard/docstring.rb:310
msgid ""
"the newline delimited array of comments. If the comments\n"
"are passed as a String, they will be split by newlines."
msgstr ""
"コメントの配列を改行で区切る。\n"
"コメントが文字列の様に解析される場合、改行によって分割される。"

# @return [String]
#: ../lib/yard/docstring.rb:310
msgid ""
"the non-metadata portion of the comments to\n"
"be used as a docstring"
msgstr "docstringのように利用される為のコメントのメタデータではない部分"

# YARD::DocstringParser
#: ../lib/yard/docstring_parser.rb:5
msgid ""
"Parses text and creates a {Docstring} object to represent documentation\n"
"for a {CodeObjects::Base}. To create a new docstring, you should initialize\n"
"the parser and call {#parse} followed by {#to_docstring}."
msgstr ""

# YARD::DocstringParser
#: ../lib/yard/docstring_parser.rb:9
msgid "== Subclassing Notes"
msgstr ""

# YARD::DocstringParser
#: ../lib/yard/docstring_parser.rb:11
msgid ""
"The DocstringParser can be subclassed and substituted during parsing by\n"
"setting the {Docstring.default_parser} attribute with the name of the\n"
"subclass. This allows developers to change the way docstrings are\n"
"parsed, allowing for completely different docstring syntaxes."
msgstr ""

# @example Creating a Custom DocstringParser
#: ../lib/yard/docstring_parser.rb:29
msgid ""
"# Parses docstrings backwards!\n"
"class ReverseDocstringParser\n"
"  def parse_content(content)\n"
"    super(content.reverse)\n"
"  end\n"
"end\n"
"\n"
"# Set the parser as default when parsing\n"
"YARD::Docstring.default_parser = ReverseDocstringParser"
msgstr ""

# @example Creating a Docstring with a DocstringParser
#: ../lib/yard/docstring_parser.rb:29
msgid "DocstringParser.new.parse(\"text here\").to_docstring"
msgstr ""

# @example
#: ../lib/yard/docstring_parser.rb:29
msgid "tag|example|Creating a Custom DocstringParser"
msgstr "tag|example|カスタムDocstringParserを作成する"

# @example
#: ../lib/yard/docstring_parser.rb:29
msgid "tag|example|Creating a Docstring with a DocstringParser"
msgstr "tag|example|DocstringParserを用いDocstringを作成する"

# @param [TokenList, String]
# @param [String]
# @param [String, #read, Object]
#: ../lib/yard/docstring_parser.rb:29
msgid "tag|see|#parse_content"
msgstr ""

# @param [String] tag_buf
#: ../lib/yard/docstring_parser.rb:32
msgid ""
"the parsed text portion of the docstring,\n"
"with tags removed."
msgstr "解析されたdocstringのテキストの一部,  削除されたタグと一緒"

# @param [String] content
#: ../lib/yard/docstring_parser.rb:35
msgid "the complete input string to the parser."
msgstr "パーサーの為の完全な入力文字列"

# @return [Array]
#: ../lib/yard/docstring_parser.rb:39
msgid ""
"the list of meta-data tags identified\n"
"by the parser"
msgstr "パーサーに認証されたメタデータタグのリスト"

# @return [Array]
#: ../lib/yard/docstring_parser.rb:44
msgid ""
"a list of directives identified\n"
"by the parser. This list will not be passed on to the\n"
"Docstring object."
msgstr ""

# @return [OpenStruct]
#: ../lib/yard/docstring_parser.rb:50
msgid ""
"any arbitrary state to be passed between\n"
"tags during parsing. Mainly used by directives to coordinate\n"
"behaviour (so that directives can be aware of other directives\n"
"used in a docstring)."
msgstr ""

# @return [CodeObjects::Base, nil]
#: ../lib/yard/docstring_parser.rb:55
msgid ""
"the object associated with\n"
"the docstring being parsed. May be nil if the docstring is\n"
"not attached to any object."
msgstr ""

# @return [Handlers::Base, nil]
#: ../lib/yard/docstring_parser.rb:60
msgid ""
"the handler parsing this\n"
"docstring. May be nil if this docstring parser is not\n"
"initialized through"
msgstr ""

# @return [Tags::Library]
#: ../lib/yard/docstring_parser.rb:64
msgid ""
"the tag library being used to\n"
"identify registered tags in the docstring."
msgstr ""

# YARD::CodeObjects::CONSTANTMATCH
#: ../lib/yard/docstring_parser.rb:67
msgid "The regular expression to match the tag syntax"
msgstr "タグ構文にマッチする為の正規表現"

# YARD::Server::Router#initialize
#: ../lib/yard/docstring_parser.rb:72
msgid "Creates a new parser to parse docstring data"
msgstr "docstringのデータを解析する為の新しいパーサーを作成する"

# YARD::Docstring#create_tag
# YARD::Docstring#add_tag
# YARD::Docstring#tag
# YARD::Docstring#tags
# YARD::Docstring#has_tag?
# YARD::Docstring#delete_tags
# YARD::Docstring#delete_tag_if
# YARD::Docstring#blank?
#: ../lib/yard/docstring_parser.rb:75 ../lib/yard/docstring_parser.rb:88
msgid "Creation and Conversion Methods"
msgstr "作成、変換メソッド"

# @return [Docstring]
#: ../lib/yard/docstring_parser.rb:75
msgid "a new instance of DocstringParser"
msgstr "DocstringParserの新しいインスタンス"

# @param [Tags::Library] library
#: ../lib/yard/docstring_parser.rb:75
msgid ""
"a tag library for recognizing\n"
"tags."
msgstr ""

# @param [LibraryVersion]
#: ../lib/yard/docstring_parser.rb:75 ../lib/yard/server/adapter.rb:88
#: ../lib/yard/server/router.rb:122
msgid "tag|param|library"
msgstr ""

# YARD::Docstring#initialize
# YARD::Docstring#+
# YARD::Docstring#replace
# YARD::Docstring#dup
#: ../lib/yard/docstring_parser.rb:88
msgid ""
"translates parsed text into\n"
"a Docstring object."
msgstr "Docstringオブジェクトへ解析されたテキストを変換する"

# YARD::DocstringParser#parse
#: ../lib/yard/docstring_parser.rb:95
msgid "Parses all content and returns itself."
msgstr ""

# YARD::Server::Router#parse_library_from_path
# YARD::Server::Router#route
# YARD::Server::Router#route_docs
# YARD::Server::Router#route_index
# YARD::Server::Router#route_list
# YARD::Server::Router#route_search
#: ../lib/yard/docstring_parser.rb:106 ../lib/yard/docstring_parser.rb:123
msgid "Parsing Methods"
msgstr "解析メソッド"

# @param [Parser::Ruby::AstNode]
#: ../lib/yard/docstring_parser.rb:106
msgid "tag|param|handler"
msgstr ""

# @param [Docstring]
#: ../lib/yard/docstring_parser.rb:106
msgid "tag|see|#to_docstring"
msgstr ""

# @param [String, #read, Object] content
#: ../lib/yard/docstring_parser.rb:106
msgid "the docstring text to parse"
msgstr "解析の為のdocstringのテキスト"

# @param [Handlers::Base, nil] handler
#: ../lib/yard/docstring_parser.rb:106
msgid ""
"the handler object that is\n"
"parsing this object. May be nil if this parser is not being\n"
"called from a {Parser::SourceParser} context."
msgstr ""

# @param [CodeObjects::Base] object
#: ../lib/yard/docstring_parser.rb:106
msgid ""
"the object that the docstring\n"
"is attached to. Will be passed to directives to act on\n"
"this object."
msgstr ""

# @return [self]
#: ../lib/yard/docstring_parser.rb:106
msgid ""
"the parser object. To get the docstring,\n"
"call {#to_docstring}."
msgstr ""

# YARD::Parser::SourceParser.parse_string
#: ../lib/yard/docstring_parser.rb:119
msgid "Parses a given block of text."
msgstr "テキストの与えられたブロックを解析する"

# YARD::Handlers::Base#process
#: ../lib/yard/docstring_parser.rb:123
msgid ""
"Subclasses can override this method to perform custom\n"
"parsing of content data."
msgstr ""
"サブクラスは内容のデータのカスタム解析を実行する為に\n"
"このメソッドを上書きできる"

# @yieldreturn [String]
#: ../lib/yard/docstring_parser.rb:123
msgid "the content to parse"
msgstr "解析する為の内容"

# YARD::Docstring#create_tag
#: ../lib/yard/docstring_parser.rb:179
msgid "Creates a tag from the {Tags::DefaultFactory tag factory}."
msgstr "{Tags::DefaultFactory tag factory}から、タグを作成する。"

# YARD::Docstring#create_tag
#: ../lib/yard/docstring_parser.rb:181
msgid "To add an already created tag object, append it to {#tags}."
msgstr "既に作成されたタグオブジェクトを追加するには、{#tags}メソッドを追加する。"

# File.relative_path
# File.cleanpath
#: ../lib/yard/docstring_parser.rb:185 ../lib/yard/docstring_parser.rb:202
#: ../lib/yard/docstring_parser.rb:208 ../lib/yard/docstring_parser.rb:228
msgid "Tag Manipulation Methods"
msgstr "タグ操作メソッド"

# @return [Tags::Tag, Tags::RefTag]
#: ../lib/yard/docstring_parser.rb:185
msgid "a tag"
msgstr "タグ"

# @param [String]
#: ../lib/yard/docstring_parser.rb:185 ../lib/yard/tags/library.rb:290
msgid "tag|param|tag_buf"
msgstr "tag_buf"

# @param [#to_s]
# @param
# @param [String]
#: ../lib/yard/docstring_parser.rb:185 ../lib/yard/tags/default_factory.rb:12
#: ../lib/yard/tags/default_factory.rb:21
#: ../lib/yard/tags/default_factory.rb:32
#: ../lib/yard/tags/default_factory.rb:44
#: ../lib/yard/tags/default_factory.rb:56 ../lib/yard/tags/library.rb:267
#: ../lib/yard/tags/library.rb:280 ../lib/yard/tags/library.rb:290
#: ../lib/yard/tags/tag.rb:43
msgid "tag|param|tag_name"
msgstr "tag_name"

# @param [String] tag_buf
#: ../lib/yard/docstring_parser.rb:185
msgid "the text attached to the tag with newlines removed."
msgstr "空白文字が削除されたタグを追加したテキスト"

# YARD::Docstring#create_ref_tag
#: ../lib/yard/docstring_parser.rb:202
msgid "Creates a {Tags::RefTag}"
msgstr "{Tags::RefTag}を作成する"

# YARD::Registry.register
#: ../lib/yard/docstring_parser.rb:207
msgid "Creates a new directive using the registered {#library}"
msgstr "記録された{#library}メソッドを使って新しい命令を作成する"

# @return [OpenStruct]
#: ../lib/yard/docstring_parser.rb:208
msgid "the directive object that is created"
msgstr "作成される命令オブジェクト"

# YARD::DocstringParser#tag_is_directive?
#: ../lib/yard/docstring_parser.rb:227
msgid ""
"Backward compatibility to detect old tags that should be specified\n"
"as directives in 0.8 and onward."
msgstr ""

# YARD::DocstringParser#call_directives_after_parse
#: ../lib/yard/docstring_parser.rb:238
msgid ""
"Calls the {Directive#after_parse} callback on all the\n"
"created directives."
msgstr ""

# YARD::Parser::SourceParser.before_parse_list
# YARD::Parser::SourceParser.after_parse_list
# YARD::Parser::SourceParser.before_parse_file
# YARD::Parser::SourceParser.after_parse_file
# YARD::Parser::SourceParser.before_parse_list_callbacks
# YARD::Parser::SourceParser.after_parse_list_callbacks
# YARD::Parser::SourceParser.before_parse_file_callbacks
# YARD::Parser::SourceParser.after_parse_file_callbacks
#: ../lib/yard/docstring_parser.rb:239 ../lib/yard/docstring_parser.rb:246
#: ../lib/yard/docstring_parser.rb:263 ../lib/yard/docstring_parser.rb:268
msgid "Parser Callback Methods"
msgstr "パーサーコールバックメソッド"

# YARD::DocstringParser#call_after_parse_callbacks
#: ../lib/yard/docstring_parser.rb:246
msgid "Calls all {after_parse} callbacks"
msgstr ""

# YARD::DocstringParser.after_parse
#: ../lib/yard/docstring_parser.rb:255
msgid ""
"Creates a callback that is called after a docstring is successfully\n"
"parsed. Use this method to perform sanity checks on a docstring's\n"
"tag data, or add any extra tags automatically to a docstring."
msgstr ""

# @return [Proc]
#: ../lib/yard/docstring_parser.rb:263
msgid "a block to be called after a docstring is parsed"
msgstr "docstringが解析された後で呼び出されるためのブロック"

# @yieldparam [SourceParser]
#: ../lib/yard/docstring_parser.rb:263 ../lib/yard/parser/source_parser.rb:292
#: ../lib/yard/parser/source_parser.rb:321
msgid "tag|yieldparam|parser"
msgstr "parser"

# @yieldparam [DocstringParser] parser
#: ../lib/yard/docstring_parser.rb:263
msgid ""
"the docstring parser object\n"
"with all directives and tags created."
msgstr ""

# @return [Array]
#: ../lib/yard/docstring_parser.rb:268
msgid "the {after_parse} callback proc objects"
msgstr ""

# #P
#: ../lib/yard/globals.rb:4
msgid "Shortcut for creating a YARD::CodeObjects::Proxy via a path"
msgstr ""

# #P
# #log
#: ../lib/yard/globals.rb:7 ../lib/yard/globals.rb:16
msgid "Global Convenience Methods"
msgstr "グローバルな便利メソッド"

# @see
#: ../lib/yard/globals.rb:7
msgid "tag|see|YARD::CodeObjects::Proxy"
msgstr ""

# @see
#: ../lib/yard/globals.rb:7
msgid "tag|see|YARD::Registry.resolve"
msgstr ""

# #log
#: ../lib/yard/globals.rb:13
msgid "The global {YARD::Logger} instance"
msgstr ""

# @see
#: ../lib/yard/globals.rb:16
msgid "tag|see|YARD::Logger"
msgstr ""

# @return [YARD::Logger]
#: ../lib/yard/globals.rb:16
msgid "the global {YARD::Logger} instance"
msgstr ""

# YARD::Handlers::NamespaceMissingError
#: ../lib/yard/handlers/base.rb:4
msgid ""
"Raised during processing phase when a handler needs to perform\n"
"an operation on an object's namespace but the namespace could\n"
"not be resolved."
msgstr ""
"ハンドラーがnamespaceオブジェクトの演算を実行する必要がある時、\n"
"処理している間に例外を上げる。しかし、namespaceは解決されない。"

# YARD::Handlers::NamespaceMissingError#object
# YARD::Handlers::NamespaceMissingError#object=
#: ../lib/yard/handlers/base.rb:8
msgid "The object the error occurred on"
msgstr "エラーが生じたコードオブジェクトを返す。"

# @return [CodeObjects::Base]
#: ../lib/yard/handlers/base.rb:9
msgid "a code object"
msgstr "コードオブジェクト"

# @return [NamespaceMissingError]
#: ../lib/yard/handlers/base.rb:11
msgid "a new instance of NamespaceMissingError"
msgstr "NamespaceMissingErrorの新しいインスタンス"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:15
msgid ""
"Handlers are pluggable semantic parsers for YARD's code generation\n"
"phase. They allow developers to control what information gets\n"
"generated by YARD, giving them the ability to, for instance, document\n"
"any Ruby DSLs that a customized framework may use. A good example\n"
"of this would be the ability to document and generate meta data for\n"
"the 'describe' declaration of the RSpec testing framework by simply\n"
"adding a handler for such a keyword. Similarly, any Ruby API that\n"
"takes advantage of class level declarations could add these to the\n"
"documentation in a very explicit format by treating them as first-\n"
"class objects in any outputted documentation."
msgstr ""
"ハンドラーは、YARDがコード生成段階で、\n"
"プラグイン可能という意味のパーサーである。\n"
"ハンドラーは、YARDによって生成される情報や、\n"
"その情報に機能を与える為や、\n"
"例えば、利用するかもしれない\n"
"カスタマイズされたフレームワークの何らかのRuby DSLを記述すること等を\n"
"制御する為に開発者を受け入れる。\n"
"いい例は、キーワードのような単純なハンドラーの追加によって、\n"
"RSpec testing フレームワークの'describe'宣言のように、\n"
"ドキュメント作成やメタデータを生成する機能である。\n"
"同様に、クラスレベル宣言から利用する何らかのRubyAPIは、\n"
"出力されたドキュメントで、\n"
"最初のクラスオブジェクトとしてそれらを処理することによって、\n"
"明確な書式でドキュメントにこれらを追加できた。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:26
msgid "== Overview of a Typical Handler Scenario"
msgstr "== 標準的なハンドラーの処理概要"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:28
msgid ""
"Generally, a handler class will declare a set of statements which\n"
"it will handle using the {handles} class declaration. It will then\n"
"implement the {#process} method to do the work. The processing would\n"
"usually involve the manipulation of the {#namespace}, {#owner}\n"
"{CodeObjects::Base code objects} or the creation of new ones, in\n"
"which case they should be registered by {#register}, a method that\n"
"sets some basic attributes for the new objects."
msgstr ""
"一般的に、ハンドラークラスはステートメントのグループを宣言する。\n"
"そして、それは {handles} クラス宣言によって処理する。\n"
"それは、処理の為に {#process} メソッドを実装する。\n"
"処理中は、通常 {#namespace} , {#owner} , {CodeObjects::Base code objects} や\n"
"新規作成を含む場合に、それらは、 {#register} によって登録されるべき、\n"
"メソッドは新しいオブジェクト用にいくつかの基本的属性を設定する。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:36
msgid ""
"Handlers are usually simple and take up to a page of code to process\n"
"and register a new object or add new attributes to the current +namespace+."
msgstr ""
"ハンドラーは一般的にシンプルで、処理の為にコードのページを取り上げ、\n"
"新しいオブジェクトを登録し、現在の +namespace+ に新しい属性を追加する。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:39
msgid "== Setting up a Handler for Use"
msgstr "== ハンドラーを使う為の設定"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:41
msgid ""
"A Handler is automatically registered when it is subclassed from the\n"
"base class. The only other thing that needs to be done is to specify\n"
"which statement the handler will process. This is done with the +handles+\n"
"declaration, taking either a {Parser::Ruby::Legacy::RubyToken}, {String} or "
"`Regexp`.\n"
"Here is a simple example which processes module statements."
msgstr ""
"ハンドラーはベースクラスからサブクラス化される時に、\n"
"自動的に登録される。\n"
"必要なその他のこととしては、\n"
"ハンドラーがどのステートメントを処理するかを指定する。\n"
"これは、 +handles+ の宣言と共に、\n"
"{Parser::Ruby::Legacy::RubyToken} か {String} や `Regexp`が取得される。\n"
"これは、モジュールステートメントの処理の簡単な例です。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:47
msgid ""
"  class MyModuleHandler < YARD::Handlers::Base\n"
"    handles TkMODULE"
msgstr ""

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:50
msgid ""
"    def process\n"
"      # do something\n"
"    end\n"
"  end"
msgstr ""

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:55
msgid "== Processing Handler Data"
msgstr "== ハンドラーデータ処理"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:57
msgid ""
"The goal of a specific handler is really up to the developer, and as\n"
"such there is no real guideline on how to process the data. However,\n"
"it is important to know where the data is coming from to be able to use\n"
"it."
msgstr ""
"具体的なハンドラーの使い方は、開発者次第となる。\n"
"データ処理の方法のガイドラインは何もない。\n"
"しかしながら、データを扱う為には、\n"
"そのデータがどこから来るか知る事が重要となる。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:62
msgid "=== +statement+ Attribute"
msgstr "=== +statement+ 属性"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:64
msgid ""
"The +statement+ attribute pertains to the {Parser::Ruby::Legacy::Statement} "
"object\n"
"containing a set of tokens parsed in by the parser. This is the main set\n"
"of data to be analyzed and processed. The comments attached to the "
"statement\n"
"can be accessed by the {Parser::Ruby::Legacy::Statement#comments} method, "
"but generally\n"
"the data to be processed will live in the +tokens+ attribute. This list\n"
"can be converted to a +String+ using +#to_s+ to parse the data with\n"
"regular expressions (or other text processing mechanisms), if needed."
msgstr ""
"パーサーによって解析されたトークンの設定を\n"
"{Parser::Ruby::Legacy::Statement} オブジェクトが含んでいる為、\n"
"+statement+ 属性は関係がある。\n"
"これは解析や処理される為のデータの主な設定となる。\n"
"コメントはstatementが {Parser::Ruby::Legacy::Statement#comments} メソッドに"
"よってアクセスされる為に付加される、\n"
"しかし、処理される一般的なデータは +tokens+ 属性の中に存在する。\n"
"必要であれば、このリストは、正規表現(又は、他のテキストが処理しているメカニズ"
"ム)を用い、データを解析する為に+#to_s+メソッドによって +String+ に変換され"
"る。\n"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:72
msgid "=== +namespace+ Attribute"
msgstr "=== +namespace+ 属性"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:74
msgid ""
"The +namespace+ attribute is a {CodeObjects::NamespaceObject namespace "
"object}\n"
"which represents the current namespace that the parser is in. For instance:"
msgstr ""
"+namespace+ 属性は {CodeObjects::NamespaceObject namespace object} となる。\n"
"それは、そのパーサーの中では現在のnamespaceを表す。\n"
"例えば:"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:77
msgid ""
"  module SomeModule\n"
"    class MyClass\n"
"      def mymethod; end\n"
"    end\n"
"  end"
msgstr ""

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:83
msgid ""
"If a handler was to parse the 'class MyClass' statement, it would\n"
"be necessary to know that it belonged inside the SomeModule module.\n"
"This is the value that +namespace+ would return when processing such\n"
"a statement. If the class was then entered and another handler was\n"
"called on the method, the +namespace+ would be set to the 'MyClass'\n"
"code object."
msgstr ""
"ハンドラー処理が'class MyClass'ステートメントを解析する場合、\n"
"class My ClassがSomeModuleモジュールの内部に\n"
"属していることを知ることが必須になる。\n"
"ステートメントのような処理(class MyClassを解析)をしている時、\n"
"SomeModuleが +namespace+ 値となり返されるだろう。\n"
"もしMyClassがエントリーされたり、\n"
"他のハンドラーがメソッド上で呼び出された場合、\n"
"'MyClass'コードオブジェクトが +namespace+ に設定される。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:90
msgid "=== +owner+ Attribute"
msgstr "=== +owner+ 属性"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:92
msgid ""
"The +owner+ attribute is similar to the +namespace+ attribute in that\n"
"it also follows the scope of the code during parsing. However, a namespace\n"
"object is loosely defined as a module or class and YARD has the ability\n"
"to parse beyond module and class blocks (inside methods, for instance),\n"
"so the +owner+ attribute would not be limited to modules and classes."
msgstr ""
"+owner+ 属性は +namespace+ 属性と似ているが、\n"
"解析中のコードのスコープをフォローもする。\n"
"しかしながら、namespace オブジェクトは\n"
"モジュールやクラスのように曖昧に定義される。\n"
"その為、YARDはモジュールやクラスブロック(例えば、内部メソッド)を\n"
"越えて解析する為の機能を持つ。\n"
"なので、この +owner+ 属性は、モジュールやクラスに制限されない。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:98
msgid ""
"To put this into context, the example from above will be used. If a method\n"
"handler was added to the mix and decided to parse inside the method body,\n"
"the +owner+ would be set to the method object but the namespace would "
"remain\n"
"set to the class. This would allow the developer to process any method\n"
"definitions set inside a method (def x; def y; 2 end end) by adding them\n"
"to the correct namespace (the class, not the method)."
msgstr ""
"この文脈の中では、上の例が使われる。\n"
"ハンドラーのメソッドは、組み合わせる為に追加されたり、\n"
"メソッド本体の内部を解析する場合、\n"
"+owner+ はメソッドオブジェクトを設定する。\n"
"しかし、namespaceはクラスに設定されたままとなる。\n"
"これは開発者に以下のことを可能とする。全てのメソッド定義は、\n"
"正しいnamespaceを追加する事によって(クラスの,メソッドでは無い)、\n"
"メソッドの内部(def x; def y; 2 end end)のグループを処理する。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:105
msgid ""
"In summary, the distinction between +namespace+ and +owner+ can be thought\n"
"of as the difference between first-class Ruby objects (namespaces) and\n"
"second-class Ruby objects (methods)."
msgstr ""
"要約すると、+namespace+ と +owner+ の違いは、\n"
"ネストするクラスで考えると、:ownerは\n"
"最初のクラスのRubyオブジェクトでは(namespace)となるが、\n"
"次のネストしたクラスのRubyオブジェクトでは前のクラスのnamespaceとなる。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:109
msgid "=== +visibility+ and +scope+ Attributes"
msgstr "=== +visibility+ と +scope+ 属性"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:111
msgid ""
"Mainly needed for parsing methods, the +visibility+ and +scope+ attributes\n"
"refer to the public/protected/private and class/instance values "
"(respectively)\n"
"of the current parsing position."
msgstr ""
"大抵は解析されるメソッドの為に必要とされる、\n"
"+visibility+ と +scope+ 属性は現在の解析している場所の\n"
"public/protected/privateとclass/instanceの値(それぞれについて)を\n"
"参照する。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:115
msgid "== Parsing Blocks in Statements"
msgstr "== ステートメントの中のブロックを解析する"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:117
msgid ""
"In addition to parsing a statement and creating new objects, some\n"
"handlers may wish to continue parsing the code inside the statement's\n"
"block (if there is one). In this context, a block means the inside\n"
"of any statement, be it class definition, module definition, if\n"
"statement or classic 'Ruby block'."
msgstr ""
"ステートメントの解析や新しくオブジェクトを作成する事に加えて、\n"
"いくつかのハンドラーはステートメントのブロック(が一つでもある場合)の\n"
"内部コードの解析処理を継続するかもしれない。\n"
"このコンテキストでブロックとは、何らかのステートメントの内部を意味する。\n"
"それはステートメントやRubyで使われるblockの場合、クラス定義、モジュール定義になる。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:123
msgid ""
"For example, a class statement would be \"class MyClass\" and the block\n"
"would be a list of statements including the method definitions inside\n"
"the class. For a class handler, the programmer would execute the\n"
"{#parse_block} method to continue parsing code inside the block, with\n"
"the +namespace+ now pointing to the class object the handler created."
msgstr ""
"例えば、ステートメントのクラスが\"class MyClass\"になるかもしれない\n"
"そして、ブロックはクラスの内部でメソッドの定義を\n"
"含んでいるステートメントのリストになるかもしれない。\n"
"ハンドラーのクラス用に、\n"
"プログラマーは、{#parse_block} メソッドを実行する。\n"
"ブロックの内部のコード解析を継続する為に、\n"
"+namespace+ は、現在、ハンドラーが作成したクラスオブジェクトを指定する。"

# YARD::Handlers::Base
#: ../lib/yard/handlers/base.rb:129
msgid ""
"YARD has the ability to continue into any block: class, module, method,\n"
"even if statements. For this reason, the block parsing method must be\n"
"invoked explicitly out of efficiency sake."
msgstr ""
"YARDは何らかのブロックの中へ(クラス,モジュール,メソッド,ステートメントでさえ)\n"
"継続する特性がある。\n"
"従って、メソッドを解析するブロックは、\n"
"効率良く処理する為、明示的に呼び出されるべきである。"

# @abstract
#: ../lib/yard/handlers/base.rb:142
msgid ""
"Subclass this class to provide a handler for YARD to use\n"
"during the processing phase."
msgstr ""
"YARDが処理段階で使用するハンドラーを提供する為に、\n"
"このクラスをサブクラス化する。"

# @see
#: ../lib/yard/handlers/base.rb:142
msgid "tag|see|#namespace"
msgstr ""

# @see
#: ../lib/yard/handlers/base.rb:142
msgid "tag|see|#owner"
msgstr ""

# @see
#: ../lib/yard/handlers/base.rb:142
msgid "tag|see|#parse_block"
msgstr ""

# @see
#: ../lib/yard/handlers/base.rb:142 ../lib/yard/handlers/base.rb:290
msgid "tag|see|#register"
msgstr ""

# @see
#: ../lib/yard/handlers/base.rb:142 ../lib/yard/parser/source_parser.rb:62
msgid "tag|see|CodeObjects::Base"
msgstr ""

# @see
#: ../lib/yard/handlers/base.rb:142
msgid "tag|see|CodeObjects::NamespaceObject"
msgstr ""

# @see
#: ../lib/yard/handlers/base.rb:142 ../lib/yard/handlers/base.rb:290
msgid "tag|see|handles"
msgstr ""

# YARD::Handlers::Base.clear_subclasses
#: ../lib/yard/handlers/base.rb:151
msgid "Clear all registered subclasses. Testing purposes only"
msgstr "全ての登録されたサブクラスを消去する。テスト用"

# YARD::Handlers::Base.subclasses
#: ../lib/yard/handlers/base.rb:157
msgid "Returns all registered handler subclasses."
msgstr "全ての登録されたサブクラスのハンドラーを返す。"

# @return [Array]
#: ../lib/yard/handlers/base.rb:158
msgid "a list of handlers"
msgstr "ハンドラーのリスト"

# YARD::Handlers::Base.handles
#: ../lib/yard/handlers/base.rb:168
msgid ""
"Declares the statement type which will be processed\n"
"by this handler."
msgstr "このハンドラーによって処理されるステートメントの型を宣言する。"

# YARD::Handlers::Base.handles
#: ../lib/yard/handlers/base.rb:171
msgid ""
"A match need not be unique to a handler. Multiple\n"
"handlers can process the same statement. However,\n"
"in this case, care should be taken to make sure that\n"
"{#parse_block} would only be executed by one of\n"
"the handlers, otherwise the same code will be parsed\n"
"multiple times and slow YARD down."
msgstr ""
"ハンドラーでマッチするものは、一つでなくてもよい。\n"
"複数のハンドラーは同じステートメントを処理できる。\n"
"しかしながら、このケースの場合は、\n"
"{#parse_block}がハンドラーの一つによって実行されるだけで、\n"
"他の同じコードが複数回解析されYARDが遅くなる事に注意しなければならない。"

# @param [Parser::RubyToken, Symbol, String, Regexp] matches
#: ../lib/yard/handlers/base.rb:185
msgid ""
"statements that match the declaration will be\n"
"processed by this handler. A {String} match is\n"
"equivalent to a +/\\Astring/+ regular expression\n"
"(match from the beginning of the line), and all\n"
"token matches match only the first token of the\n"
"statement."
msgstr ""
"このハンドラーによって処理される宣言がマッチするステートメント。\n"
"A {String} のマッチは +/\\Astring/+ の正規表現と同様となる。\n"
"(行の最初からマッチ)、\n"
"そして全てのトークンのマッチは、ステートメントの最初のトークンにだけマッチする。"

# @param [Parser::RubyToken, Symbol, String, Regexp]
#: ../lib/yard/handlers/base.rb:185
msgid "tag|param|matches"
msgstr ""

# YARD::Handlers::Base.handles?
#: ../lib/yard/handlers/base.rb:190
msgid ""
"This class is implemented by {Ruby::Base} and {Ruby::Legacy::Base}.\n"
"To implement a base handler class for another language, implement\n"
"this method to return true if the handler should process the given\n"
"statement object. Use {handlers} to enumerate the matchers declared\n"
"for the handler class."
msgstr ""
"このクラスは、 {Ruby::Base} や {Ruby::Legacy::Base} によって実装される。\n"
"他の言語用のbase handlerクラスを実装する為には、\n"
"ハンドラーが与えられたステートメントオブジェクトを処理する場合、\n"
"trueを返す為にこのメソッドを実装する。\n"
"ハンドラークラス用のマッチする宣言を列挙するには、{handlers} を使用する。"

# @param statement
#: ../lib/yard/handlers/base.rb:198
msgid "a statement object or node (depends on language type)"
msgstr "オブジェクトやノードのステートメント(言語タイプに左右される)"

# @return [Boolean]
#: ../lib/yard/handlers/base.rb:198
msgid ""
"whether or not this handler object should process\n"
"the given statement"
msgstr "いずれにせよ、このハンドラーオブジェクトは指定されたステートメントを処理するべき"

# @return [Array]
#: ../lib/yard/handlers/base.rb:204
msgid "a list of matchers for the handler object."
msgstr "ハンドラーオブジェクト用の照合されるリスト"

# @see
#: ../lib/yard/handlers/base.rb:204
msgid "tag|see|handles?"
msgstr ""

# YARD::Handlers::Base.namespace_only
#: ../lib/yard/handlers/base.rb:209
msgid ""
"Declares that the handler should only be called when inside a\n"
"{CodeObjects::NamespaceObject}, not a method body."
msgstr ""
"ハンドラーが {CodeObjects::NamespaceObject} 内部の時だけ\n"
"呼び出される事を宣言する、このメソッドは本体ではない。"

# @return [Boolean]
#: ../lib/yard/handlers/base.rb:218
msgid ""
"whether the handler should only be processed inside\n"
"a namespace."
msgstr "このハンドラがnamespace内だけで処理されるかどうか"

# YARD::Handlers::Base.in_file
#: ../lib/yard/handlers/base.rb:223
msgid ""
"Declares that a handler should only be called when inside a filename\n"
"by its basename or a regex match for the full path."
msgstr ""
"ハンドラーがフルパス用のベースネームや正規表現マッチによって、\n"
"ファイルネーム内部の時だけ呼び出される事を宣言する。"

# @param [String, Regexp] filename
#: ../lib/yard/handlers/base.rb:228
msgid "a matching filename or regex"
msgstr "マッチするファイルネームや正規表現"

# @return [Boolean]
#: ../lib/yard/handlers/base.rb:235
msgid ""
"whether the filename matches the declared file\n"
"match for a handler. If no file match is specified, returns true."
msgstr ""
"ファイル名が宣言されたハンドラー用のファイルとマッチするかどうか、\n"
"ファイルがマッチしない場合は、trueを返す。"

# YARD::Handlers::Base.process
#: ../lib/yard/handlers/base.rb:251
msgid ""
"Generates a +process+ method, equivalent to +def process; ... end+.\n"
"Blocks defined with this syntax will be wrapped inside an anonymous\n"
"module so that the handler class can be extended with mixins that\n"
"override the +process+ method without alias chaining."
msgstr ""
"+process+ メソッドを生成する、 +def process; ...end+ と同等となる。\n"
"この構文を用いた定義されるブロックは、無名モジュールの内部でラップされる。\n"
"理由としては、ハンドラークラスが +procecc+ メソッドの上書きを\n"
"エイリアスチェーン無しでmixinを用い拡張できるようにする為である。"

# @since
#: ../lib/yard/handlers/base.rb:262
#: ../lib/yard/handlers/ruby/class_condition_handler.rb:11
#: ../lib/yard/parser/ruby/legacy/statement.rb:49
#: ../lib/yard/templates/erb_cache.rb:16
#: ../lib/yard/templates/helpers/html_helper.rb:510
msgid "0.5.4"
msgstr ""

# @see
#: ../lib/yard/handlers/base.rb:262
msgid "tag|see|#process"
msgstr ""

# @return [Base]
#: ../lib/yard/handlers/base.rb:269 ../lib/yard/parser/base.rb:25
#: ../lib/yard/serializers/base.rb:27 ../lib/yard/server/commands/base.rb:74
msgid "a new instance of Base"
msgstr "ベースの新しいインスタンス"

# YARD::Handlers::Base#process
#: ../lib/yard/handlers/base.rb:275
msgid ""
"The main handler method called by the parser on a statement\n"
"that matches the {handles} declaration."
msgstr ""
"主なハンドラーのメソッドは {handles} の宣言で\n"
"マッチするstatementのパーサーによって呼び出される。"

# YARD::Handlers::Base#process
#: ../lib/yard/handlers/base.rb:278
msgid ""
"Subclasses should override this method to provide the handling\n"
"functionality for the class."
msgstr ""
"サブクラスはクラス用の処理機能を提供する為に、\n"
"このメソッドを上書きする。"

# @return [Array, CodeObjects::Base, Object]
#: ../lib/yard/handlers/base.rb:290
msgid ""
"If this method returns a code object (or a list of them),\n"
"they are passed to the +#register+ method which adds basic\n"
"attributes. It is not necessary to return any objects and in\n"
"some cases you may want to explicitly avoid the returning of\n"
"any objects for post-processing by the register method."
msgstr ""
"このメソッドがコードオブジェクト(やそれらのリスト)を返す場合、\n"
"それらは、+#register+ メソッドに解析され、基本属性が追加される。\n"
"何らかのオブジェクトを返すのは必須ではなく、\n"
"場合によっては、\n"
"あなたはregisterメソッドによって後処理用の\n"
"何らかのオブジェクトを返すことを明確に無視できる。"

# YARD::Handlers::Base#parse_block
#: ../lib/yard/handlers/base.rb:295
msgid "Parses the semantic \"block\" contained in the statement node."
msgstr "ステートメントノードに含まれている意味のある\"block\"を解析する。"

# @abstract
#: ../lib/yard/handlers/base.rb:297
msgid "Subclasses should call {Processor#process parser.process}"
msgstr "{Processor#process parser.process} を呼び出しサブクラス化する。"

# @return [Processor]
#: ../lib/yard/handlers/base.rb:303
msgid ""
"the processor object that manages all global state\n"
"during handling."
msgstr "全てのグローバルな状態の処理の間に扱うプロセッサーオブジェクト"

# @return [Object]
#: ../lib/yard/handlers/base.rb:308
msgid ""
"the statement object currently being processed. Usually\n"
"refers to one semantic language statement, though the strict definition\n"
"depends on the parser used."
msgstr ""
"現在の処理されるステートメントオブジェクト。\n"
"厳格な定義は使われるパーサー次第とはいえ、\n"
"一般的には、一つの意味のある言語を参照する。"

# @param value
#: ../lib/yard/handlers/base.rb:311 ../lib/yard/handlers/base.rb:333
#: ../lib/yard/tags/ref_tag.rb:4 ../lib/yard/tags/ref_tag_list.rb:4
msgid "the value to set the attribute owner to."
msgstr "owner属性を設定する為の値"

# YARD::Tags::RefTag#owner
# YARD::Tags::RefTagList#owner
#: ../lib/yard/handlers/base.rb:312 ../lib/yard/handlers/base.rb:333
#: ../lib/yard/tags/ref_tag.rb:5 ../lib/yard/tags/ref_tag_list.rb:5
msgid "Returns the value of attribute owner"
msgstr "owner属性の値を返す"

# YARD::Tags::RefTag#owner=
# YARD::Tags::RefTagList#owner=
#: ../lib/yard/handlers/base.rb:312 ../lib/yard/handlers/base.rb:334
#: ../lib/yard/tags/ref_tag.rb:5 ../lib/yard/tags/ref_tag_list.rb:5
msgid "Sets the attribute owner"
msgstr "owner属性を設定する"

# @param value
#: ../lib/yard/handlers/base.rb:314 ../lib/yard/handlers/base.rb:335
msgid "the value to set the attribute namespace to."
msgstr "値にnamespace属性を設定するための値"

# YARD::CodeObjects::ExtraFileObject#name=
# YARD::Tags::RefTagList#name=
# YARD::Templates::Section#name=
#: ../lib/yard/handlers/base.rb:315 ../lib/yard/handlers/base.rb:336
msgid "Sets the attribute namespace"
msgstr "namespace属性を設定する"

# @param value
#: ../lib/yard/handlers/base.rb:317 ../lib/yard/handlers/base.rb:337
msgid "the value to set the attribute visibility to."
msgstr "値にvisibility属性を設定するための値"

# YARD::Parser::Ruby::RipperParser#ast
# YARD::Parser::Ruby::RipperParser#root
#: ../lib/yard/handlers/base.rb:318 ../lib/yard/handlers/base.rb:337
msgid "Returns the value of attribute visibility"
msgstr "visibility属性の値を返す"

# YARD::Parser::Ruby::AstNode#file=
#: ../lib/yard/handlers/base.rb:318 ../lib/yard/handlers/base.rb:338
msgid "Sets the attribute visibility"
msgstr "visibility属性を設定する。"

# @param value
#: ../lib/yard/handlers/base.rb:320 ../lib/yard/handlers/base.rb:339
msgid "the value to set the attribute scope to."
msgstr "値にスコープ属性を設定するための値"

# YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN#op
#: ../lib/yard/handlers/base.rb:321 ../lib/yard/handlers/base.rb:339
msgid "Returns the value of attribute scope"
msgstr "スコープ属性の値を返す"

# YARD::Parser::Ruby::AstNode#source=
#: ../lib/yard/handlers/base.rb:321 ../lib/yard/handlers/base.rb:340
msgid "Sets the attribute scope"
msgstr "スコープ属性を設定する"

# YARD::Tags::Library.labels
#: ../lib/yard/handlers/base.rb:324 ../lib/yard/handlers/base.rb:341
msgid "Returns the value of attribute globals"
msgstr "globals(全体)属性の値を返す"

# YARD::Parser::Ruby::Legacy::RubyLex#lex_state
#: ../lib/yard/handlers/base.rb:327 ../lib/yard/handlers/base.rb:342
msgid "Returns the value of attribute extra_state"
msgstr "extra_state属性の値を返す"

# YARD::Handlers::Base#push_state
#: ../lib/yard/handlers/base.rb:344
msgid ""
"Executes a given block with specific state values for {#owner},\n"
"{#namespace} and {#scope}."
msgstr ""
"{#owner}, {#namespace} , {#scope}メソッド用の特定の状態値と\n"
"一緒に与えられたブロックを実行する。"

# @yield
#: ../lib/yard/handlers/base.rb:355
msgid "a block to execute with the given state values."
msgstr "状態を指定すると共に実行するブロック。"

# @param [Proc]
#: ../lib/yard/handlers/base.rb:355
msgid "tag|param|block"
msgstr ""

# @param [Proc] block
#: ../lib/yard/handlers/base.rb:355
msgid "the block to execute with specific state"
msgstr "与えられた値の状態と共に実行するブロック。"

# YARD::Handlers::Base#register
#: ../lib/yard/handlers/base.rb:378
msgid ""
"Do some post processing on a list of code objects.\n"
"Adds basic attributes to the list of objects like\n"
"the filename, line number, {CodeObjects::Base#dynamic},\n"
"source code and {CodeObjects::Base#docstring},\n"
"but only if they don't exist."
msgstr ""
"コードオブジェクトのリストのいくつかの後処理をする。\n"
"ファイル名、行数、{CodeObjects::Base#dynamic} 、ソースコード、\n"
"{CodeObjects::Base#docstring}のようなオブジェクトのリストに、\n"
"基本属性を追加する。\n"
"しかし、それらが存在しない場合だけである。"

# @return [CodeObjects::Base, Array]
#: ../lib/yard/handlers/base.rb:389
msgid "returns whatever is passed in, for chainability."
msgstr "メソッドチェーンの為、解析されるものを返す"

# @param [Array]
#: ../lib/yard/handlers/base.rb:389 ../lib/yard/i18n/pot_generator.rb:90
#: ../lib/yard/templates/engine.rb:100
msgid "tag|param|objects"
msgstr ""

# @param [Array] objects
#: ../lib/yard/handlers/base.rb:389
msgid "the list of objects to post-process."
msgstr "後処理の為のオブジェクトのリスト"

# YARD::Handlers::Base#register_ensure_loaded
#: ../lib/yard/handlers/base.rb:406
msgid ""
"Ensures that the object's namespace is loaded before attaching it\n"
"to the namespace."
msgstr ""

# @param [CodeObjects::Base] object
#: ../lib/yard/handlers/base.rb:411 ../lib/yard/handlers/base.rb:424
#: ../lib/yard/handlers/base.rb:433 ../lib/yard/handlers/base.rb:456
#: ../lib/yard/handlers/base.rb:470 ../lib/yard/handlers/base.rb:483
#: ../lib/yard/handlers/base.rb:495 ../lib/yard/handlers/base.rb:520
#: ../lib/yard/registry.rb:174
msgid "the object to register"
msgstr "記録するオブジェクト"

# YARD::Logger#enter_level
#: ../lib/yard/handlers/base.rb:420
msgid "Registers the file/line of the declaration with the object"
msgstr "オブジェクトを用い宣言のファイル/行を登録する"

# YARD::Handlers::Base#expand_macro
#: ../lib/yard/handlers/base.rb:429
msgid "Registers any docstring found for the object and expands macros"
msgstr "オブジェクト用に見つかった任意のdocstringを登録し、マクロを拡張する"

# YARD::Registry.at
# YARD::Registry.[]
#: ../lib/yard/handlers/base.rb:452
msgid "Registers the object as being inside a specific group"
msgstr "特定のグループ内部のものとしてオブジェクトを登録する"

# YARD::CodeObjects::MethodObject#aliases
#: ../lib/yard/handlers/base.rb:466
msgid "Registers any transitive tags from the namespace on the object"
msgstr "オブジェクト上のnamespaceから全てのtransitiveタグを登録する"

# YARD::Handlers::Base#register_visibility
#: ../lib/yard/handlers/base.rb:490
msgid ""
"Registers visibility on a method object. If the object does not\n"
"respond to setting visibility, nothing is done."
msgstr ""

# @param [Array]
# @param [Array]
# @param [Array]
#: ../lib/yard/handlers/base.rb:495
msgid "tag|param|visibility"
msgstr ""

# @return [String]
#: ../lib/yard/handlers/base.rb:495
msgid "the visibility to set on the object"
msgstr "オブジェクトを設定するためのvisibility"

# YARD::Handlers::Base#register_module_function
#: ../lib/yard/handlers/base.rb:501
msgid ""
"Registers the same method information on the module function, if\n"
"the object was defined as a module function."
msgstr ""

# @param [CodeObjects::Base] object
#: ../lib/yard/handlers/base.rb:506
msgid ""
"the possible module function object\n"
"to copy data for"
msgstr ""

# YARD::Handlers::Base#register_dynamic
#: ../lib/yard/handlers/base.rb:515
msgid ""
"Registers the object as dynamic if the object is defined inside\n"
"a method or block (owner != namespace)"
msgstr ""

# YARD::Handlers::Base#ensure_loaded!
#: ../lib/yard/handlers/base.rb:525
msgid ""
"Ensures that a specific +object+ has been parsed and loaded into the\n"
"registry. This is necessary when adding data to a namespace, for instance,\n"
"since the namespace may not have been processed yet (it can be located\n"
"in a file that has not been handled)."
msgstr ""
"特定の +object+ は解析されて、レジストリの中へロードされる事を保証する。\n"
"例えば、namespaceは、まだ処理されないかもしれないので\n"
"(処理されないファイルの中にそれはある可能性がある。)\n"
"これはnamespaceにデータを追加する時に必要である。"

# YARD::Handlers::Base#ensure_loaded!
#: ../lib/yard/handlers/base.rb:530
msgid ""
"Calling this method defers the handler until all other files have been\n"
"processed. If the object gets resolved, the rest of the handler continues,\n"
"otherwise an exception is raised."
msgstr ""
"このメソッドの呼び出しは\n"
"他の全てのファイルが処理されるまでハンドラーを延期する。\n"
"もしオブジェクトが解決された場合、ハンドラーの残りが続き、\n"
"さもなければ、例外を上げる。"

# @example Adding a mixin to the String class programmatically
#: ../lib/yard/handlers/base.rb:544
msgid ""
"ensure_loaded! P('String')\n"
"# \"String\" is now guaranteed to be loaded\n"
"P('String').mixins << P('MyMixin')"
msgstr ""

# @raise [NamespaceMissingError]
#: ../lib/yard/handlers/base.rb:544
msgid ""
"if the object is not resolved within\n"
"+max_retries+ attempts, this exception is raised and the handler\n"
"finishes processing."
msgstr ""
"オブジェクトが +max_retries+ を試みても解決されない場合、\n"
"この例外を上げ、ハンドラーが処理を終了させる。"

# @example
#: ../lib/yard/handlers/base.rb:544
msgid "tag|example|Adding a mixin to the String class programmatically"
msgstr "Stringクラスのプログラムにmixinを追加する"

# @param [Integer]
#: ../lib/yard/handlers/base.rb:544
msgid "tag|param|max_retries"
msgstr ""

# @param [Integer] max_retries
#: ../lib/yard/handlers/base.rb:544
msgid ""
"the number of times to defer the handler\n"
"before raising a +NamespaceMissingError+."
msgstr "+NamespaceMissingError+ を上げる前にハンドラーがリトライする回数"

# @param [Proxy, CodeObjects::Base] object
#: ../lib/yard/handlers/base.rb:544
msgid "the object to resolve."
msgstr "解決したいオブジェクト"

# @abstract
#: ../lib/yard/handlers/base.rb:567
msgid ""
"Implement this method to return the parameters in a method call\n"
"statement. It should return an empty list if the statement is not a\n"
"method call."
msgstr ""
"メソッド呼び出しステートメントの中のパラメータを返す為にこのメソッドを実装する。\n"
"ステートメントがメソッド呼び出しでない場合は空のリストを返すべき。"

# YARD::Handlers::Base#call_params
# YARD::Handlers::Base#caller_method
# YARD::Handlers::Base#find_or_create_macro
# YARD::Handlers::Base#expand_macro
#: ../lib/yard/handlers/base.rb:567 ../lib/yard/handlers/base.rb:576
msgid "Macro Support"
msgstr "マクロのサポート"

# @return [Array]
#: ../lib/yard/handlers/base.rb:567
msgid "a list of argument names"
msgstr "引数の名前のリスト"

# @abstract
#: ../lib/yard/handlers/base.rb:576
msgid ""
"Implement this method to return the method being called in\n"
"a method call. It should return nil if the statement is not a method\n"
"call."
msgstr ""
"メソッド呼び出しの中で呼び出されるメソッドが返す為に\n"
"このメソッドが実装する。\n"
"ステートメントがメソッド呼び出しでない場合はnilを返すべき。"

# @return [nil]
#: ../lib/yard/handlers/base.rb:576
msgid "if the statement is not a method call"
msgstr "ステートメントがメソッド呼び出しでない場合"

# @return [String]
#: ../lib/yard/handlers/base.rb:576
msgid "the method name being called"
msgstr "呼び出されるメソッド名"

# YARD::Handlers::C::AliasHandler#process
# YARD::Handlers::C::AttributeHandler#process
# YARD::Handlers::C::ClassHandler#process
# YARD::Handlers::C::ConstantHandler#process
# YARD::Handlers::C::InitHandler#process
# YARD::Handlers::C::MethodHandler#process
# YARD::Handlers::C::MixinHandler#process
# YARD::Handlers::C::ModuleHandler#process
# YARD::Handlers::C::OverrideCommentHandler#process
# YARD::Handlers::C::PathHandler#process
# YARD::Handlers::C::StructHandler#process
# YARD::Handlers::C::SymbolHandler#process
# YARD::Handlers::Ruby::AliasHandler#process
# YARD::Handlers::Ruby::AttributeHandler#process
# YARD::Handlers::Ruby::ClassConditionHandler#process
# YARD::Handlers::Ruby::ClassHandler#process
# YARD::Handlers::Ruby::ClassVariableHandler#process
# YARD::Handlers::Ruby::CommentHandler#process
# YARD::Handlers::Ruby::ConstantHandler#process
# YARD::Handlers::Ruby::DSLHandler#process
# YARD::Handlers::Ruby::ExceptionHandler#process
# YARD::Handlers::Ruby::Legacy::AliasHandler#process
# YARD::Handlers::Ruby::Legacy::AttributeHandler#process
# YARD::Handlers::Ruby::Legacy::ClassConditionHandler#process
# YARD::Handlers::Ruby::Legacy::ClassHandler#process
# YARD::Handlers::Ruby::Legacy::ClassVariableHandler#process
# YARD::Handlers::Ruby::Legacy::CommentHandler#process
# YARD::Handlers::Ruby::Legacy::ConstantHandler#process
# YARD::Handlers::Ruby::Legacy::DSLHandler#process
# YARD::Handlers::Ruby::Legacy::ExceptionHandler#process
# YARD::Handlers::Ruby::Legacy::MethodHandler#process
# YARD::Handlers::Ruby::Legacy::MixinHandler#process
# YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler#process
# YARD::Handlers::Ruby::Legacy::ModuleHandler#process
# YARD::Handlers::Ruby::Legacy::PrivateConstantHandler#process
# YARD::Handlers::Ruby::Legacy::VisibilityHandler#process
# YARD::Handlers::Ruby::Legacy::YieldHandler#process
# YARD::Handlers::Ruby::MethodConditionHandler#process
# YARD::Handlers::Ruby::MethodHandler#process
# YARD::Handlers::Ruby::MixinHandler#process
# YARD::Handlers::Ruby::ModuleFunctionHandler#process
# YARD::Handlers::Ruby::ModuleHandler#process
# YARD::Handlers::Ruby::PrivateConstantHandler#process
# YARD::Handlers::Ruby::VisibilityHandler#process
# YARD::Handlers::Ruby::YieldHandler#process
#: ../lib/yard/handlers/c/alias_handler.rb:10
#: ../lib/yard/handlers/c/attribute_handler.rb:6
#: ../lib/yard/handlers/c/class_handler.rb:19
#: ../lib/yard/handlers/c/constant_handler.rb:8
#: ../lib/yard/handlers/c/init_handler.rb:8
#: ../lib/yard/handlers/c/method_handler.rb:22
#: ../lib/yard/handlers/c/mixin_handler.rb:7
#: ../lib/yard/handlers/c/module_handler.rb:9
#: ../lib/yard/handlers/c/override_comment_handler.rb:7
#: ../lib/yard/handlers/c/path_handler.rb:6
#: ../lib/yard/handlers/c/struct_handler.rb:8
#: ../lib/yard/handlers/c/symbol_handler.rb:7
#: ../lib/yard/handlers/ruby/alias_handler.rb:7
#: ../lib/yard/handlers/ruby/attribute_handler.rb:10
#: ../lib/yard/handlers/ruby/class_condition_handler.rb:16
#: ../lib/yard/handlers/ruby/class_handler.rb:8
#: ../lib/yard/handlers/ruby/class_variable_handler.rb:7
#: ../lib/yard/handlers/ruby/comment_handler.rb:7
#: ../lib/yard/handlers/ruby/constant_handler.rb:8
#: ../lib/yard/handlers/ruby/dsl_handler.rb:11
#: ../lib/yard/handlers/ruby/exception_handler.rb:6
#: ../lib/yard/handlers/ruby/legacy/alias_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/attribute_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/class_condition_handler.rb:8
#: ../lib/yard/handlers/ruby/legacy/class_handler.rb:8
#: ../lib/yard/handlers/ruby/legacy/class_variable_handler.rb:8
#: ../lib/yard/handlers/ruby/legacy/comment_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/constant_handler.rb:9
#: ../lib/yard/handlers/ruby/legacy/dsl_handler.rb:12
#: ../lib/yard/handlers/ruby/legacy/exception_handler.rb:6
#: ../lib/yard/handlers/ruby/legacy/method_handler.rb:6
#: ../lib/yard/handlers/ruby/legacy/mixin_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/module_function_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/module_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/private_constant_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/visibility_handler.rb:7
#: ../lib/yard/handlers/ruby/legacy/yield_handler.rb:6
#: ../lib/yard/handlers/ruby/method_condition_handler.rb:6
#: ../lib/yard/handlers/ruby/method_handler.rb:6
#: ../lib/yard/handlers/ruby/mixin_handler.rb:7
#: ../lib/yard/handlers/ruby/module_function_handler.rb:8
#: ../lib/yard/handlers/ruby/module_handler.rb:7
#: ../lib/yard/handlers/ruby/private_constant_handler.rb:7
#: ../lib/yard/handlers/ruby/visibility_handler.rb:9
#: ../lib/yard/handlers/ruby/yield_handler.rb:6
msgid "Main processing callback"
msgstr ""

# @return [Boolean]
#: ../lib/yard/handlers/c/base.rb:9
msgid "whether the handler handles this statement"
msgstr "ハンドラーがこのステートメントを操作するかどうか"

# @return [CodeObjects::Base]
#: ../lib/yard/handlers/c/base.rb:36 ../lib/yard/handlers/c/base.rb:40
#: ../lib/yard/handlers/c/base.rb:44 ../lib/yard/handlers/c/base.rb:48
msgid "Registering objects"
msgstr "オブジェクトを登録する"

# YARD::Handlers::C::Base#namespace_for_variable
# YARD::Handlers::C::Base#namespaces
# YARD::Handlers::C::Base#override_comments
# YARD::Handlers::C::Base#processed_files
# YARD::Handlers::C::Base#symbols
#: ../lib/yard/handlers/c/base.rb:54 ../lib/yard/handlers/c/base.rb:58
#: ../lib/yard/handlers/c/base.rb:62 ../lib/yard/handlers/c/base.rb:68
#: ../lib/yard/handlers/c/base.rb:72
msgid "Looking up Symbol and Var Values"
msgstr ""

# YARD::Handlers::Ruby::Base#parse_block
#: ../lib/yard/handlers/c/base.rb:78 ../lib/yard/handlers/ruby/base.rb:132
msgid "Parsing an Inner Block"
msgstr "内部のブロックを解析する"

# @return [String]
#: ../lib/yard/handlers/c/base.rb:87 ../lib/yard/handlers/c/base.rb:104
msgid "Processing other files"
msgstr "他のファイルを処理する"

# YARD::Handlers::Ruby::MethodConditionHandler
#: ../lib/yard/handlers/c/init_handler.rb:2
msgid "Handles the Init_Libname() method"
msgstr "Init_Libname()メソッドを操作する"

# YARD::CLI::Yardoc#parse_arguments
#: ../lib/yard/handlers/c/override_comment_handler.rb:2
msgid "Parses comments"
msgstr "コメントを解析する"

# YARD::Handlers::C::SymbolHandler
#: ../lib/yard/handlers/c/symbol_handler.rb:2
msgid ""
"Keeps track of function bodies for symbol lookup during Ruby method "
"declarations"
msgstr ""

# YARD::Handlers::Processor
#: ../lib/yard/handlers/processor.rb:6
msgid ""
"Iterates over all statements in a file and delegates them to the\n"
"{Handlers::Base} objects that are registered to handle the statement."
msgstr ""
"ファイルの中の全てのステートメントにまたがり繰り返し、\n"
"ステートメントを操作する為に記録される{Handlers::Base}オブジェクトに委譲す"
"る。"

# YARD::Handlers::Processor
#: ../lib/yard/handlers/processor.rb:9
msgid ""
"This class is passed to each handler and keeps overall processing state.\n"
"For example, if the {#visibility} is set in a handler, all following\n"
"statements will have access to this state. This allows \"public\",\n"
"\"protected\" and \"private\" statements to be handled in classes and "
"modules.\n"
"In addition, the {#namespace} can be set during parsing to control\n"
"where objects are being created from. You can also access extra stateful\n"
"properties that any handler can set during the duration of the post\n"
"processing of a file from {#extra_state}. If you need to access state\n"
"across different files, look at {#globals}."
msgstr ""
"このクラスはそれぞれのハンドラーが渡される。\n"
"そして、総合的な処理の状態を維持する。\n"
"例えば、{#visibility}はハンドラーの中で設定される。\n"
"全ての次のステートメントは、この状態にアクセス可能である。\n"
"これは、クラスやモジュールの中で操作される\n"
"\"public\",\"protected\",\"private\"ステートメントを受け入れる。\n"
"さらに、{#namespace}メソッドは、\n"
"オブジェクトが作成される場所で、制御の為に解析している間に設定される。\n"
"あなたは、追加の処理状態を把握する属性にアクセスも出来る。\n"
"任意のハンドラーが\n"
"{#extra_state}メソッドからファイルの後処理をしている間に\n"
"設定できる。\n"
"あなたが複数のファイルに渡って状態にアクセスする必要がある場合、\n"
"{#globals}メソッドで調べられる。"

# @see
#: ../lib/yard/handlers/processor.rb:19 ../lib/yard/handlers/ruby/base.rb:62
#: ../lib/yard/parser/source_parser.rb:62
msgid "tag|see|Handlers::Base"
msgstr ""

# YARD::Handlers::Processor.register_handler_namespace
#: ../lib/yard/handlers/processor.rb:23
msgid "Registers a new namespace for handlers of the given type."
msgstr "与える型の入ったハンドラー用の記録する。"

# @return [Hash]
#: ../lib/yard/handlers/processor.rb:31 ../lib/yard/handlers/processor.rb:33
#: ../lib/yard/parser/source_parser.rb:158
#: ../lib/yard/parser/source_parser.rb:160
msgid "a list of registered parser type extensions"
msgstr "parser type extensionsが,記録されるリスト"

# @return [String]
#: ../lib/yard/handlers/processor.rb:41
msgid "the filename"
msgstr "ファイル名"

# @return [CodeObjects::NamespaceObject]
#: ../lib/yard/handlers/processor.rb:44
msgid "the current namespace"
msgstr "現在のnamespace"

# @return [Symbol]
#: ../lib/yard/handlers/processor.rb:47
msgid "the current visibility (public, private, protected)"
msgstr "現在の可視性(public,private,protected)"

# @return [Symbol]
#: ../lib/yard/handlers/processor.rb:50
msgid "the current scope (class, instance)"
msgstr "現在のスコープ(クラス,インスタンス)"

# @return [CodeObjects::Base, nil]
#: ../lib/yard/handlers/processor.rb:56
msgid ""
"unlike the namespace, the owner\n"
"is a non-namespace object that should be stored between statements.\n"
"For instance, when parsing a method body, the {CodeObjects::MethodObject}\n"
"is set as the owner, in case any extra method information is processed."
msgstr ""
"namespaceとは異なり、ownerは、\n"
"ステートメントの間に記録されるnamespaceオブジェクトを持たない。\n"
"例えば、メソッド本体を解析する時、{CodeObjects::MethodObject}は、\n"
"このownerのように設定される。この場合、何らかの追加のメソッド情報が処理され"
"る。"

# @return [Symbol]
#: ../lib/yard/handlers/processor.rb:59
msgid "the parser type (:ruby, :ruby18, :c)"
msgstr "パーサー型(:ruby, :ruby18, :c)"

# YARD::Handlers::Base#globals
# YARD::Handlers::Processor#globals
# YARD::Handlers::Processor#globals=
#: ../lib/yard/handlers/processor.rb:62
msgid ""
"Handlers can share state for the entire post processing stage through\n"
"this attribute. Note that post processing stage spans multiple files.\n"
"To share state only within a single file, use {#extra_state}"
msgstr ""
"ハンドラーはこの属性を通して全体の後処理環境用の状態を共有できる。\n"
"以下の事に留意する。\n"
"後処理の状態は、複数ファイルに渡す。\n"
"単一のファイルの中でだけ状態を共有するには、 {#extra_state} を使用する。"

# @example Sharing state among two handlers
#: ../lib/yard/handlers/processor.rb:77
msgid ""
"class Handler1 < YARD::Handlers::Ruby::Base\n"
"  handles :class\n"
"  process { globals.foo = :bar }\n"
"end\n"
"\n"
"class Handler2 < YARD::Handlers::Ruby::Base\n"
"  handles :method\n"
"  process { puts globals.foo }\n"
"end"
msgstr ""

# @return [OpenStruct]
#: ../lib/yard/handlers/processor.rb:77
msgid "global shared state for post-processing stage"
msgstr "後処理環境用に状態を共有される,global"

# @example
#: ../lib/yard/handlers/processor.rb:77
msgid "tag|example|Sharing state among two handlers"
msgstr "2つのハンドラーの間で状態を共有する"

# @see
#: ../lib/yard/handlers/processor.rb:77
msgid "tag|see|#extra_state"
msgstr ""

# YARD::Handlers::Base#extra_state
# YARD::Handlers::Processor#extra_state
# YARD::Handlers::Processor#extra_state=
#: ../lib/yard/handlers/processor.rb:80
msgid ""
"Share state across different handlers inside of a file.\n"
"This attribute is similar to {#visibility}, {#scope}, {#namespace}\n"
"and {#owner}, in that they all maintain state across all handlers\n"
"for the entire source file. Use this attribute to store any data\n"
"your handler might need to save during the parsing of a file. If\n"
"you need to save state across files, see {#globals}."
msgstr ""
"ファイルの内部の別のハンドラーの行き来の状態を共有する。\n"
"それらは全体のソースファイルの為に全てのハンドラーの行き来の状態を\n"
"全て維持するという点で {#visibility}, {#scope}, {#namespace}, {#owner}属性と"
"似ている。\n"
"この属性を使って、あなたのハンドラーが必要とするかもしれないデータを格納し\n"
"ファイルの解析中に保存する。\n"
"ファイル全体の状態の保存が必要な場合、 {#globals} を参照。"

# @return [OpenStruct]
#: ../lib/yard/handlers/processor.rb:88
msgid "an open structure that can store arbitrary data"
msgstr "任意のデータを記録できる簡単な構造体"

# @see
#: ../lib/yard/handlers/processor.rb:88
msgid "tag|see|#globals"
msgstr ""

# YARD::Handlers::Processor#initialize
#: ../lib/yard/handlers/processor.rb:91
msgid "Creates a new Processor for a +file+."
msgstr "+file+用の新しいProcessorを作成する"

# @return [Processor]
#: ../lib/yard/handlers/processor.rb:92
msgid "a new instance of Processor"
msgstr "プロセッサーの新しいインスタンス"

# @param [Array]
# @param [Hash]
#: ../lib/yard/handlers/processor.rb:92 ../lib/yard/tags/directives.rb:54
#: ../lib/yard/tags/library.rb:290
msgid "tag|param|parser"
msgstr ""

# @param [Integer] char_no
#: ../lib/yard/handlers/processor.rb:92
msgid "the parser used to initialize the processor"
msgstr "プロセッサを初期化するために使ったパーサー"

# YARD::Handlers::Processor#process
#: ../lib/yard/handlers/processor.rb:106
msgid ""
"Processes a list of statements by finding handlers to process each\n"
"one."
msgstr ""
"処理の各自の処理ハンドラーが見つけることによって\n"
"処理ステートメントのリスト\n"

# @param [Array] statements
#: ../lib/yard/handlers/processor.rb:110
msgid "a list of statements"
msgstr "ステートメントのリスト"

# @param [Array]
#: ../lib/yard/handlers/processor.rb:110
msgid "tag|param|statements"
msgstr "statements"

# YARD::Handlers::Processor#parse_remaining_files
#: ../lib/yard/handlers/processor.rb:133
msgid ""
"Continue parsing the remainder of the files in the +globals.ordered_parser+\n"
"object. After the remainder of files are parsed, processing will continue\n"
"on the current file."
msgstr ""

# @see
#: ../lib/yard/handlers/processor.rb:138
msgid "tag|see|Parser::OrderedParser"
msgstr ""

# YARD::Handlers::Processor#find_handlers
#: ../lib/yard/handlers/processor.rb:146
msgid ""
"Searches for all handlers in {Base.subclasses} that match the +statement+"
msgstr ""
"+statement+ にマッチする{Base.sublasses}の中の全てのハンドラー用に検索する。"

# @return [Array]
#: ../lib/yard/handlers/processor.rb:149
msgid "a list of handlers to process the statement with."
msgstr "ステートメントと共に処理する為のハンドラーのリスト"

# @param statement
#: ../lib/yard/handlers/processor.rb:149
msgid "the statement object to match."
msgstr "オブジェクトにマッチするステートメント"

# YARD::Handlers::Processor#handler_base_class
#: ../lib/yard/handlers/processor.rb:169
msgid "Returns the handler base class"
msgstr "ハンドラーのbaseクラスを返す"

# @return [Base]
#: ../lib/yard/handlers/processor.rb:170
msgid "the base class"
msgstr ""

# YARD::Handlers::Processor#handler_base_namespace
#: ../lib/yard/handlers/processor.rb:175
msgid "The module holding the handlers to be loaded"
msgstr "ロードされるハンドラーを保持する,モジュール"

# @return [Module]
#: ../lib/yard/handlers/processor.rb:178
msgid ""
"the module containing the handlers depending on\n"
"{#parser_type}."
msgstr "{#parser_type}メソッドに依存しているハンドラーを含んでいる,モジュール"

# YARD::Handlers::Processor#load_handlers
#: ../lib/yard/handlers/processor.rb:183
msgid ""
"Loads handlers from {#handler_base_namespace}. This ensures that\n"
"Ruby1.9 handlers are never loaded into 1.8; also lowers the amount\n"
"of modules that are loaded"
msgstr ""
"{#handler_base_namespace}から、ハンドラーをロードする。\n"
"これはロードされるモジュールの量を減少させると共に\n"
"Ruby1.9ハンドラーが1.8でロードされない事を保証する。"

# YARD::Handlers::Ruby::Legacy::AliasHandler
# YARD::Handlers::Ruby::AliasHandler
#: ../lib/yard/handlers/ruby/alias_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/alias_handler.rb:2
msgid "Handles alias and alias_method calls"
msgstr "aliasを操作し、alias_methodを呼び出す。"

# YARD::Handlers::Ruby::Legacy::AttributeHandler
# YARD::Handlers::Ruby::AttributeHandler
#: ../lib/yard/handlers/ruby/attribute_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/attribute_handler.rb:2
msgid "Handles +attr_*+ statements in modules/classes"
msgstr "モジュール/クラスの中の +attr_+ ステートメントを操作する。"

# YARD::Handlers::Ruby::AttributeHandler#validated_attribute_names
#: ../lib/yard/handlers/ruby/attribute_handler.rb:65
msgid "Strips out any non-essential arguments from the attr statement."
msgstr "attrステートメントから、任意の重要ではない引数を取り除く"

# @param [Array] params
#: ../lib/yard/handlers/ruby/attribute_handler.rb:70
msgid ""
"a list of the parameters\n"
"in the attr call."
msgstr "attrの中で呼ばれる引数のリスト"

# @raise [Parser::UndocumentableError]
#: ../lib/yard/handlers/ruby/attribute_handler.rb:70
msgid "if the arguments are not valid."
msgstr "引数が有効でない場合"

# @param [Array]
# @param [Hash]
#: ../lib/yard/handlers/ruby/attribute_handler.rb:70
#: ../lib/yard/templates/helpers/base_helper.rb:138
msgid "tag|param|params"
msgstr "params"

# @return [Array]
#: ../lib/yard/handlers/ruby/attribute_handler.rb:70
msgid "the validated attribute names"
msgstr "有効化された属性名"

# YARD::Handlers::Ruby::HandlesExtension
#: ../lib/yard/handlers/ruby/base.rb:5
msgid ""
"To implement a custom handler matcher, subclass this class and implement\n"
"{#matches?} to return whether a node matches the handler."
msgstr ""
"カスタムハンドラーのマッチャーを実装するには、このクラスをサブクラス化す"
"る。\n"
"そして、ノードがハンドラーにマッチするかどうかを返す為に{#matches?}メソッドを"
"実装する。"

# @example A Custom Handler Matcher Extension
#: ../lib/yard/handlers/ruby/base.rb:18
msgid ""
"# Implements a handler that checks for a specific string\n"
"# in the node's source.\n"
"class MyExtension < HandlesExtension\n"
"  def matches?(node) node.source.include?(name) end\n"
"end\n"
"\n"
"# This handler will handle any node where the source includes 'foo'\n"
"class MyHandler < Handlers::Ruby::Base\n"
"  handles MyExtension.new('foo')\n"
"end"
msgstr ""
"# 特定の文字列をチェックするハンドラーを実装する\n"
"# ノードのソースの中で\n"
"class MyExtension < HandlesExtension\n"
"  def matches?(node) node.source.include?(name) end\n"
"end\n"
"\n"
"# このハンドラーは'foo'を含んでいるソースの所で任意のノードを操作する。\n"
"class MyHandler < Handlers::Ruby::Base\n"
"  handles MyExtension.new('foo')\n"
"end"

# @example
#: ../lib/yard/handlers/ruby/base.rb:18
msgid "tag|example|A Custom Handler Matcher Extension"
msgstr "カスタムハンドラーのマッチャーの拡張"

# YARD::Handlers::Ruby::HandlesExtension#initialize
#: ../lib/yard/handlers/ruby/base.rb:20
msgid "Creates a new extension with a specific matcher value +name+"
msgstr "特定のマッチャーの値の +name+ と共に、新たな拡張を作成する"

# @return [HandlesExtension]
#: ../lib/yard/handlers/ruby/base.rb:21
msgid "a new instance of HandlesExtension"
msgstr "HandlesExtensionの新しいインスタンス"

# @param [Object] name
#: ../lib/yard/handlers/ruby/base.rb:21
msgid "the matcher value to check against {#matches?}"
msgstr "{#matches?}メソッドに備えて確認する,マッチャーの値"

# YARD::Handlers::Ruby::HandlesExtension#matches?
#: ../lib/yard/handlers/ruby/base.rb:24
msgid "Tests if the node matches the handler"
msgstr "ノードがハンドラーにマッチする場合、テストする。"

# @param [Parser::Ruby::AstNode] node
#: ../lib/yard/handlers/ruby/base.rb:26
msgid "a Ruby node"
msgstr "Rubyのノード"

# @param [Parser::Ruby::AstNode]
#: ../lib/yard/handlers/ruby/base.rb:26
msgid "tag|param|node"
msgstr "node"

# @return [Boolean]
#: ../lib/yard/handlers/ruby/base.rb:26
msgid "whether the +node+ matches the handler"
msgstr "+node+ がハンドラーにマッチするかどうか"

# @return [String]
#: ../lib/yard/handlers/ruby/base.rb:31
msgid "the extension matcher value"
msgstr "拡張のマッチャーの値"

# YARD::Handlers::Ruby::Base
#: ../lib/yard/handlers/ruby/base.rb:55
msgid ""
"This is the base handler class for the new-style (1.9) Ruby parser.\n"
"All handlers that subclass this base class will be used when the\n"
"new-style parser is used. For implementing legacy handlers, see\n"
"{Legacy::Base}."
msgstr ""
"これは、新しい(1.9用)Rubyパーサー用の基本ハンドラークラスとなる。\n"
"この基本クラスからサブクラス化する全てのハンドラーは、\n"
"新しいスタイルのパーサーを使う時に利用される。\n"
"レガシーハンドラーの実装には、{Legacy::Base}を参照。"

# @abstract
#: ../lib/yard/handlers/ruby/base.rb:62
msgid "See {Handlers::Base} for subclassing information."
msgstr "サブクラス化用の情報には、{Handlers::Base}を参照"

# @see
#: ../lib/yard/handlers/ruby/base.rb:62
msgid "tag|see|Legacy::Base"
msgstr ""

# YARD::Handlers::Ruby::Base.method_call
#: ../lib/yard/handlers/ruby/base.rb:69
msgid ""
"Matcher for handling any type of method call. Method calls can\n"
"be expressed by many {AstNode} types depending on the syntax\n"
"with which it is called, so YARD allows you to use this matcher\n"
"to simplify matching a method call."
msgstr ""
"任意のメソッド呼び出しの型を操作する為のマッチャー\n"
"メソッド呼び出しは、\n"
"構文から多くの{AstNode}型となって表され\n"
"呼び出す事ができる。\n"
"なので、YARDは\n"
"あなたがメソッド呼び出しのマッチを簡単にする為に\n"
"このマッチャーを使う事を許可する。"

# YARD::Handlers::Ruby::Base.method_call
# YARD::Handlers::Ruby::Base.meta_type
#: ../lib/yard/handlers/ruby/base.rb:83 ../lib/yard/handlers/ruby/base.rb:102
msgid "Statement Matcher Extensions"
msgstr "ステートメントマッチャーの拡張"

# @example Match the "describe" method call
#: ../lib/yard/handlers/ruby/base.rb:83
msgid ""
"handles method_call(:describe)\n"
"\n"
"# The following will be matched:\n"
"# describe(...)\n"
"# object.describe(...)\n"
"# describe \"argument\" do ... end"
msgstr ""

# @param [#to_s] name
#: ../lib/yard/handlers/ruby/base.rb:83
msgid "matches the method call of this name"
msgstr "この名前のメソッド呼び出しのマッチャー"

# @example
#: ../lib/yard/handlers/ruby/base.rb:83
msgid "tag|example|Match the \"describe\" method call"
msgstr "\"describe\"メソッド呼び出しにマッチする"

# YARD::Handlers::Ruby::Base.meta_type
#: ../lib/yard/handlers/ruby/base.rb:88
msgid ""
"Matcher for handling a node with a specific meta-type. An {AstNode}\n"
"has a {AstNode#type} to define its type but can also be associated\n"
"with a set of types. For instance, +:if+ and +:unless+ are both\n"
"of the meta-type +:condition+."
msgstr ""
"特定のメタタイプと共にノードを処理する為のマッチャー。\n"
"{AstNode}はAstNodeの型を定義する為に\n"
"{AstNode#type}メソッドを持っている。\n"
"しかし、型のグループと共に関連付ける事もできる。\n"
"例えば、 +:if+ と +:unless+ は、両方とも +:condition+ のメタタイプとなる。"

# YARD::Handlers::Ruby::Base.meta_type
#: ../lib/yard/handlers/ruby/base.rb:93
msgid ""
"A meta-type is any method on the {AstNode} class ending in \"?\",\n"
"though you should not include the \"?\" suffix in your declaration.\n"
"Some examples are: \"condition\", \"call\", \"literal\", \"kw\", \"token\",\n"
"\"ref\"."
msgstr ""
"メタタイプは、\"?\"で終わる{AstNode}クラスの任意のメソッドである。\n"
"なので、あなたは、自身の宣言の中で\"?\"サフィックスを含むべきではない。\n"
"いくつかの例を上げると、\"condition\", \"call\", \"literal\", \"kw\", \"token"
"\",\"ref\" となる。"

# @example Handling any conditional statement (if, unless)
#: ../lib/yard/handlers/ruby/base.rb:102
msgid "handles meta_type(:condition)"
msgstr ""

# @example
#: ../lib/yard/handlers/ruby/base.rb:102
msgid "tag|example|Handling any conditional statement (if, unless)"
msgstr "任意の条件文(if, unless)を操作する"

# @param [Symbol] type
#: ../lib/yard/handlers/ruby/base.rb:102
msgid ""
"the meta-type to match. A meta-type can be\n"
"any method name + \"?\" that {AstNode} responds to."
msgstr ""
"マッチするメタタイプ。\n"
"メタタイプは、{AstNode}に対応する任意のメソッド名 + \"?\" でできる。"

# YARD::Handlers::Ruby::Base.handles?
#: ../lib/yard/handlers/ruby/base.rb:110
msgid "Testing for a Handler"
msgstr "ハンドラー用にテストする。"

# @return [Boolean]
#: ../lib/yard/handlers/ruby/base.rb:110
msgid ""
"whether or not an {AstNode} object should be\n"
"handled by this handler"
msgstr "{AstNode}オブジェクトはこのハンドラーによって処理されるかどうか"

# YARD::Handlers::Ruby::Base#call_params
# YARD::Handlers::Ruby::Base#caller_method
#: ../lib/yard/handlers/ruby/base.rb:141 ../lib/yard/handlers/ruby/base.rb:152
msgid "Macro Handling"
msgstr "マクロを処理する"

# YARD::Handlers::Ruby::Legacy::ClassConditionHandler
# YARD::Handlers::Ruby::ClassConditionHandler
#: ../lib/yard/handlers/ruby/class_condition_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/class_condition_handler.rb:2
msgid ""
"Matches if/unless conditions inside classes and attempts to process only\n"
"one branch (by evaluating the condition if possible)."
msgstr ""
"クラス内部のif/unless条件にマッチし、一つのブランチだけを処理する。(条件を評"
"価し可能ならば)"

# @example A simple class conditional
#: ../lib/yard/handlers/ruby/class_condition_handler.rb:11
msgid ""
"class Foo\n"
"  if 0\n"
"    # This method is ignored\n"
"    def xyz; end\n"
"  end\n"
"end"
msgstr ""
"class Foo\n"
"  if 0\n"
"    # このメソッドは無視される\n"
"    def xyz; end\n"
"  end\n"
"end"

# @example
#: ../lib/yard/handlers/ruby/class_condition_handler.rb:11
msgid "tag|example|A simple class conditional"
msgstr "シンプルな条件のクラス"

# YARD::Handlers::Ruby::Legacy::ClassConditionHandler#parse_condition
# YARD::Handlers::Ruby::ClassConditionHandler#parse_condition
#: ../lib/yard/handlers/ruby/class_condition_handler.rb:31
#: ../lib/yard/handlers/ruby/legacy/class_condition_handler.rb:23
msgid "Parses the condition part of the if/unless statement"
msgstr "if/unlessステートメントの部分の条件を解析する。"

# @return [true, false, nil]
#: ../lib/yard/handlers/ruby/class_condition_handler.rb:35
#: ../lib/yard/handlers/ruby/legacy/class_condition_handler.rb:28
msgid ""
"true if the condition can be definitely\n"
"parsed to true, false if not, and nil if the condition cannot be\n"
"parsed with certainty (it's dynamic)"
msgstr ""
"条件が間違いなく解析できる場合、true\n"
"そうでない場合、falseや、\n"
"条件が完璧に解析できない場合、nilとなる。\n"
"(it's dynamic)"

# YARD::Handlers::Ruby::Legacy::ClassHandler
# YARD::Handlers::Ruby::ClassHandler
#: ../lib/yard/handlers/ruby/class_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/class_handler.rb:2
msgid "Handles class declarations"
msgstr "クラスの宣言を操作する"

# YARD::Handlers::Ruby::ClassHandler#extract_parameters
# YARD::Handlers::Ruby::ConstantHandler#extract_parameters
#: ../lib/yard/handlers/ruby/class_handler.rb:63
#: ../lib/yard/handlers/ruby/constant_handler.rb:35
msgid ""
"Extract the parameters from the Struct.new AST node, returning them as a "
"list\n"
"of strings"
msgstr ""
"パラメータをStrct.new Astノードから抽出し、文字列のリストとしてAstノードを返"
"す。"

# @param [MethodCallNode]
# @param [String]
#: ../lib/yard/handlers/ruby/class_handler.rb:67
#: ../lib/yard/handlers/ruby/constant_handler.rb:39
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:91
msgid "tag|param|superclass"
msgstr "superclass"

# @param [MethodCallNode] superclass
#: ../lib/yard/handlers/ruby/class_handler.rb:67
#: ../lib/yard/handlers/ruby/constant_handler.rb:39
msgid "the AST node for the Struct.new call"
msgstr "Struct.new呼び出し用のASTノード"

# @return [Array]
#: ../lib/yard/handlers/ruby/class_handler.rb:67
#: ../lib/yard/handlers/ruby/constant_handler.rb:39
msgid "the member names to generate methods for"
msgstr "member名にメソッドを生成する,member名"

# YARD::Handlers::Ruby::Legacy::ClassVariableHandler
# YARD::Handlers::Ruby::ClassVariableHandler
#: ../lib/yard/handlers/ruby/class_variable_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/class_variable_handler.rb:2
msgid "Handles a class variable (@@variable)"
msgstr "クラス変数を操作する(@@変数)"

# YARD::Handlers::Ruby::Legacy::ConstantHandler
# YARD::Handlers::Ruby::ConstantHandler
#: ../lib/yard/handlers/ruby/comment_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/comment_handler.rb:2
msgid "Handles any lone comment statement in a Ruby file"
msgstr "Rubyのファイルの中の任意の単一のコメントステートメントを操作する"

# YARD::Handlers::Ruby::Legacy::ConstantHandler
# YARD::Handlers::Ruby::ConstantHandler
#: ../lib/yard/handlers/ruby/constant_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/constant_handler.rb:2
msgid "Handles any constant assignment"
msgstr "任意の定数割り当てを操作する"

# YARD::Handlers::Ruby::Legacy::MacroHandler
# YARD::Handlers::Ruby::MacroHandler
#: ../lib/yard/handlers/ruby/dsl_handler.rb:5
#: ../lib/yard/handlers/ruby/legacy/dsl_handler.rb:6
msgid "Handles automatic detection of dsl-style methods"
msgstr "DSLスタイルのメソッドの自動宣言を操作する"

# YARD::Handlers::Ruby::Legacy::ExceptionHandler
# YARD::Handlers::Ruby::ExceptionHandler
#: ../lib/yard/handlers/ruby/exception_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/exception_handler.rb:2
msgid "Handles 'raise' calls inside methods"
msgstr "メソッドの内部で呼び出す'raise'を操作する"

# YARD::Handlers::Ruby::Legacy::ExtendHandler
# YARD::Handlers::Ruby::ExtendHandler
#: ../lib/yard/handlers/ruby/extend_handler.rb:2
#: ../lib/yard/handlers/ruby/legacy/extend_handler.rb:2
msgid ""
"Handles 'extend' call to include modules into the class scope of another"
msgstr ""
"他のクラススコープの中へモジュールを含める為に、'extend'呼び出しを操作する。"

# @see
#: ../lib/yard/handlers/ruby/extend_handler.rb:3
msgid "tag|see|MixinHandler"
msgstr ""

# YARD::Handlers::Ruby::Legacy::Base
#: ../lib/yard/handlers/ruby/legacy/base.rb:5
msgid ""
"This is the base handler for the legacy parser. To implement a legacy\n"
"handler, subclass this class."
msgstr ""
"これは、legacy parser用のbase handlerとなる。\n"
"legacy handlerの実装には、このクラスをサブクラスにする。"

# @return [Boolean]
#: ../lib/yard/handlers/ruby/legacy/base.rb:14
msgid ""
"whether or not a {Parser::Ruby::Legacy::Statement} object should be handled\n"
"by this handler."
msgstr ""
"{Parser::Ruby::Legacy::Statement}オブジェクトが、\n"
"このハンドラーによって操作されるかどうか"

# YARD::Handlers::Ruby::Legacy::Base#parse_block
#: ../lib/yard/handlers/ruby/legacy/base.rb:28
msgid ""
"Parses a statement's block with a set of state values. If the\n"
"statement has no block, nothing happens. A description of state\n"
"values can be found at {Handlers::Base#push_state}"
msgstr ""
"値の状態のグループと共に、ブロックのステートメントを解析する。\n"
"ステートメントがブロックを持たない場合、何も起こらない。\n"
"値の状態の説明は、{Handlers::Base#push_state}で見つけられる。"

# @see Handlers::Base#push_state
#: ../lib/yard/handlers/ruby/legacy/base.rb:34
msgid "#push_state"
msgstr ""

# @param [Hash] opts
#: ../lib/yard/handlers/ruby/legacy/base.rb:34
msgid "State options"
msgstr "オプションの状態"

# @see
#: ../lib/yard/handlers/ruby/legacy/base.rb:34
msgid "tag|see|Handlers::Base#push_state"
msgstr ""

# YARD::Handlers::Ruby::Legacy::Base#extract_method_details
#: ../lib/yard/handlers/ruby/legacy/base.rb:67
msgid "Extracts method information for macro expansion only"
msgstr ""

# @todo
#: ../lib/yard/handlers/ruby/legacy/base.rb:71
msgid "This is a duplicate implementation of {MethodHandler}. Refactor."
msgstr ""

# @return [Array>>]
#: ../lib/yard/handlers/ruby/legacy/base.rb:71
msgid ""
"the method name followed by method\n"
"arguments (name and optional value)"
msgstr ""

# YARD::Handlers::Ruby::Legacy::Base#tokval
#: ../lib/yard/handlers/ruby/legacy/base.rb:85
msgid ""
"The string value of a token. For example, the return value for the symbol :"
"sym\n"
"would be :sym. The return value for a string +\"foo #{ bar}\"+ would be the "
"literal\n"
"+\"foo #{ bar}\"+ without any interpolation. The return value of the "
"identifier\n"
"'test' would be the same value: 'test'. Here is a list of common types and\n"
"their return values:"
msgstr ""
"トークンの文字列の値。例えば、シンボル:sym用に返す値は、:symになる。\n"
"文字列 +\"foo #{ bar}\"+ 用に返す値は、補完を含まない +\"foo #{ bar}\"+ リテ"
"ラルになる。\n"
"'test'識別子の返す値は、'test'と同じ値になるだろう。\n"
"ここでは、一般的な型のリストやそれらの値を返す。"

# @param [Array>, Symbol] accepted_types
#: ../lib/yard/handlers/ruby/legacy/base.rb:116
msgid ""
"The allowed token types that this token can be. Defaults to [{TkVal}].\n"
"A list of types would be, for example, [+TkSTRING+, +TkSYMBOL+], to return\n"
"the token's value if it is either of those types. If +TkVal+ is accepted,\n"
"+TkNode+ is also accepted.\n"
"\n"
"Certain symbol keys are allowed to specify multiple types in one fell "
"swoop.\n"
"These symbols are:\n"
"  :string       => +TkSTRING+, +TkDSTRING+, +TkDXSTRING+ and +TkXSTRING+\n"
"  :attr         => +TkSYMBOL+ and +TkSTRING+\n"
"  :identifier   => +TkIDENTIFIER, +TkFID+ and +TkGVAR+.\n"
"  :number       => +TkFLOAT+, +TkINTEGER+"
msgstr ""
"トークンにできる受け入れられるトークンの型となる。\n"
"デフォルトでは、[{TkVal}]になる。\n"
"型のリストになる、\n"
"\n"
"例えば、[+TkSTRING+, +TkSYMBOL+]は、\n"
"どちらかがこれらの型の場合、トークンの値を返す。\n"
"+TkVal+が受け入れられる場合、+TkNode+も受け入れられる。\n"
"\n"
"特定のシンボルキーは、一つで複数の型を一気に指定する為に受け入れられる。\n"
"このようなシンボルとなる:\n"
"  :string       => +TkSTRING+, +TkDSTRING+, +TkDXSTRING+ and +TkXSTRING+\n"
"  :attr         => +TkSYMBOL+ and +TkSTRING+\n"
"  :identifier   => +TkIDENTIFIER, +TkFID+ and +TkGVAR+.\n"
"  :number       => +TkFLOAT+, +TkINTEGER+"

# @param [Token] token
#: ../lib/yard/handlers/ruby/legacy/base.rb:116
msgid "The token of the class"
msgstr "クラスのトークン"

# @return [nil]
#: ../lib/yard/handlers/ruby/legacy/base.rb:116
msgid "if the token is not any of the specified accepted types"
msgstr "トークンが指定され受け入れられる型のどれでもない場合、"

# @return [Object]
#: ../lib/yard/handlers/ruby/legacy/base.rb:116
msgid ""
"if the token is one of the accepted types, in its real value form.\n"
"It should be noted that identifiers and constants are kept in String form."
msgstr ""
"トークンが受け入れられる型の一つの場合、その中は、実際の値の形式になる。\n"
"そして、識別子と定数がString形式で注釈される。"

# @param [Array>, Symbol]
# @param [Array>]
#: ../lib/yard/handlers/ruby/legacy/base.rb:116
#: ../lib/yard/handlers/ruby/legacy/base.rb:182
msgid "tag|param|accepted_types"
msgstr "accepted_types"

# @param [Token]
#: ../lib/yard/handlers/ruby/legacy/base.rb:116
msgid "tag|param|token"
msgstr "token"

# @example 
#: ../lib/yard/handlers/ruby/legacy/base.rb:116
msgid ""
"tokval(TokenList.new('\"foo\"').first) => \"foo\"\n"
"tokval(TokenList.new(':foo').first) => :foo\n"
"tokval(TokenList.new('CONSTANT').first, RubyToken::TkId) => \"CONSTANT\"\n"
"tokval(TokenList.new('identifier').first, RubyToken::TkId) => \"identifier"
"\"\n"
"tokval(TokenList.new('3.25').first) => 3.25\n"
"tokval(TokenList.new('/xyz/i').first) => /xyz/i"
msgstr ""

# YARD::Handlers::Ruby::Legacy::Base#tokval_list
#: ../lib/yard/handlers/ruby/legacy/base.rb:162
msgid ""
"Returns a list of symbols or string values from a statement.\n"
"The list must be a valid comma delimited list, and values\n"
"will only be returned to the end of the list only."
msgstr ""
"ステートメントから、シンボル,又は,文字列の値のリストを返す。\n"
"リストは、有効なカンマで区切られたリストでなければならない、\n"
"そして、値はリストで返されるだけにしなければならない。"

# YARD::Handlers::Ruby::Legacy::Base#tokval_list
#: ../lib/yard/handlers/ruby/legacy/base.rb:166
msgid ""
"Example:\n"
"  attr_accessor :a, 'b', :c, :d => ['a', 'b', 'c', 'd']\n"
"  attr_accessor 'a', UNACCEPTED_TYPE, 'c' => ['a', 'c']"
msgstr ""

# YARD::Handlers::Ruby::Legacy::Base#tokval_list
#: ../lib/yard/handlers/ruby/legacy/base.rb:170
msgid ""
"The tokval list of a {Parser::Ruby::Legacy::TokenList} of the above\n"
"code would be the {#tokval} value of :a, 'b',\n"
":c and :d."
msgstr ""
"上のコード{Parser::Ruby::Legacy::TokenList}のtokvalのリストは、\n"
":a, 'b', :c, :d の入った{#tokval}の値になる。"

# YARD::Handlers::Ruby::Legacy::Base#tokval_list
#: ../lib/yard/handlers/ruby/legacy/base.rb:174
msgid ""
"It should also be noted that this function stops immediately at\n"
"any ruby keyword encountered:\n"
"  \"attr_accessor :a, :b, :c if x == 5\"  => ['a', 'b', 'c']"
msgstr ""
"それは、この機能が任意のrubyキーワードが出会った所で、\n"
"直後に止めて注釈される。\n"
"  \"attr_accessor :a, :b, :c if x == 5\"  => ['a', 'b', 'c']"

# @param [TokenList] tokenlist
#: ../lib/yard/handlers/ruby/legacy/base.rb:182
msgid "The list of tokens to process."
msgstr "処理されるトークンのリスト"

# @return [Array]
#: ../lib/yard/handlers/ruby/legacy/base.rb:182
msgid "if there are no symbols or Strings in the list"
msgstr "シンボルやリストの文字列がない場合"

# @param [Array>] accepted_types
#: ../lib/yard/handlers/ruby/legacy/base.rb:182
msgid "passed to {#tokval}"
msgstr "{#tokval}に渡される"

# @param [TokenList]
#: ../lib/yard/handlers/ruby/legacy/base.rb:182
msgid "tag|param|tokenlist"
msgstr "tokenlist"

# @see
#: ../lib/yard/handlers/ruby/legacy/base.rb:182
msgid "tag|see|#tokval"
msgstr ""

# @return [Array]
#: ../lib/yard/handlers/ruby/legacy/base.rb:182
msgid "the list of tokvalues in the list."
msgstr "リストの中のtokvaluesのリスト"

# YARD::Handlers::Ruby::Legacy::ClassHandler#extract_parameters
#: ../lib/yard/handlers/ruby/legacy/class_handler.rb:62
msgid ""
"Extracts the parameter list from the Struct.new declaration and returns it\n"
"formatted as a list of member names. Expects the user will have used "
"symbols\n"
"to define the struct member names"
msgstr ""
"Struct.new宣言から、引数のリストを抽出し、\n"
"それをメンバー名のリストとして、書式化して返す\n"
"ユーザーは、structメンバー名を定義する為に、シンボルを\n"
"利用する事を要求するだろう。"

# @return [Array]
# @param [Array] members
#: ../lib/yard/handlers/ruby/legacy/class_handler.rb:67
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:133
msgid "a list of member names"
msgstr "メンバー名のリスト"

# @param [String]
#: ../lib/yard/handlers/ruby/legacy/class_handler.rb:67
msgid "tag|param|superstring"
msgstr "superstring"

# @param [String] superstring
#: ../lib/yard/handlers/ruby/legacy/class_handler.rb:67
msgid "the string declaring the superclass"
msgstr "文字列で宣言しているsuperclass"

# YARD::Handlers::Ruby::Legacy::MethodHandler
# YARD::Handlers::Ruby::MethodHandler
#: ../lib/yard/handlers/ruby/legacy/method_handler.rb:2
#: ../lib/yard/handlers/ruby/method_handler.rb:2
msgid "Handles a method definition"
msgstr "メソッドの定義を操作する"

# YARD::Handlers::Ruby::Legacy::MixinHandler
# YARD::Handlers::Ruby::MixinHandler
#: ../lib/yard/handlers/ruby/legacy/mixin_handler.rb:2
#: ../lib/yard/handlers/ruby/mixin_handler.rb:2
msgid "Handles the 'include' statement to mixin a module in the instance scope"
msgstr ""
"インスタンススコープのモジュールをmixinする為に、'include'ステートメントを操"
"作する。"

# YARD::Handlers::Ruby::Legacy::ModuleFunctionHandler
# YARD::Handlers::Ruby::ModuleFunctionHandler
#: ../lib/yard/handlers/ruby/legacy/module_function_handler.rb:2
#: ../lib/yard/handlers/ruby/module_function_handler.rb:2
msgid ""
"Handles module_function calls to turn methods into public class methods.\n"
"Also creates a private instance copy of the method."
msgstr ""

# YARD::Handlers::Ruby::Legacy::ModuleHandler
# YARD::Handlers::Ruby::ModuleHandler
#: ../lib/yard/handlers/ruby/legacy/module_handler.rb:2
#: ../lib/yard/handlers/ruby/module_handler.rb:2
msgid "Handles the declaration of a module"
msgstr "モジュールの宣言を操作する"

# YARD::Handlers::Ruby::Legacy::PrivateConstantHandler
# YARD::Handlers::Ruby::PrivateConstantHandler
#: ../lib/yard/handlers/ruby/legacy/private_constant_handler.rb:2
#: ../lib/yard/handlers/ruby/private_constant_handler.rb:2
msgid "Sets visibility of a constant (class, module, const)"
msgstr "定数の可視性を設定する(クラス,モジュール,定数)"

# YARD::Handlers::Ruby::Legacy::VisibilityHandler
# YARD::Handlers::Ruby::VisibilityHandler
#: ../lib/yard/handlers/ruby/legacy/visibility_handler.rb:2
#: ../lib/yard/handlers/ruby/visibility_handler.rb:2
msgid "Handles 'private', 'protected', and 'public' calls."
msgstr "'private', 'protected', 'public' 呼び出しを操作する。"

# YARD::Handlers::Ruby::Legacy::YieldHandler
# YARD::Handlers::Ruby::YieldHandler
#: ../lib/yard/handlers/ruby/legacy/yield_handler.rb:2
#: ../lib/yard/handlers/ruby/yield_handler.rb:2
msgid "Handles 'yield' calls"
msgstr "'yield'を呼び出し操作する"

# YARD::Handlers::Ruby::MethodConditionHandler
#: ../lib/yard/handlers/ruby/method_condition_handler.rb:2
msgid "Handles a conditional inside a method"
msgstr "メソッドの内部の条件を操作する"

# YARD::Handlers::Ruby::StructHandlerMethods
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:2
msgid "Helper methods to parse @attr_* tags on a class."
msgstr "クラスの@attr_* タグを解析する為のHelperメソッド"

# @deprecated
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:6
msgid ""
"The use of +@attr+ tags are deprecated since 0.8.0 in favour of\n"
"the +@!attribute+ directive. This module should not be relied on."
msgstr ""

# YARD::Handlers::Ruby::StructHandlerMethods#member_tag_for_member
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:10
msgid ""
"Extracts the user's defined @member tag for a given class and its member. "
"Returns\n"
"nil if the user did not define a @member tag for this struct entry."
msgstr ""
"与えられたクラスとそのメンバー用に\n"
"ユーザーの定義した@memberタグを抽出する。\n"
"この構造体の登録用の@memberタグが未定義だった場合、nilを返す。"

# @param [Symbol] type
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:16
msgid "reader method, or writer method?"
msgstr "readerメソッドかwriterメソッドか?"

# @param [ClassObject]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:16
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:25
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:37
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:61
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:76
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:103
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:120
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:133
msgid "tag|param|klass"
msgstr "klass"

# @param [String]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:16
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:37
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:61
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:76
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:103
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:120
msgid "tag|param|member"
msgstr "member"

# @param [ClassObject] klass
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:16
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:37
msgid "the class whose tags we're searching"
msgstr "検索しているタグのクラス"

# @param [String] member
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:16
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:37
msgid "the name of the struct member we need"
msgstr "必要とする構造体memberの名前"

# @return [Tags::Tag, nil]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:16
msgid "the tag matching the request, or nil if not found"
msgstr "マッチしているタグのリクエスト、見つからない場合は、nil"

# YARD::Handlers::Ruby::StructHandlerMethods#members_from_tags
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:22
msgid "Retrieves all members defined in @attr* tags"
msgstr "@attr* タグの中で定義した全てのメンバーを回収する"

# @param [ClassObject] klass
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:25
msgid "the class with the attributes"
msgstr "属性と一緒のクラス"

# @return [Array]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:25
msgid "the list of members defined as attributes on the class"
msgstr "クラス上の属性として、定義したメンバーのリスト"

# YARD::Handlers::Ruby::StructHandlerMethods#create_member_method?
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:31
msgid ""
"Determines whether to create an attribute method based on the class's\n"
"tags."
msgstr "クラス上で、基底のメソッド属性を作成するかどうか、確定する。"

# @param [Symbol] type
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:37
msgid "(:read) reader method, or writer method?"
msgstr "(:read) readerメソッドか、writerメソッドか?"

# @return [Boolean]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:37
msgid "should the attribute be created?"
msgstr "属性が作成されるかどうか?"

# YARD::Handlers::Ruby::StructHandlerMethods#return_type_from_tag
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:45
msgid ""
"Gets the return type for the member in a nicely formatted string. Used\n"
"to be injected into auto-generated docstrings."
msgstr ""
"より良く書式化された文字列でmember用に返す型を取得する。\n"
"自動生成されたdocstrigの中へ入れる為に利用される"

# @param [String]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:50
msgid "tag|param|member_tag"
msgstr ""

# @param [CodeObjects::Base] object
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:50
msgid "the tag object to check for types"
msgstr "型をチェックする為のタグオブジェクト"

# @return [String]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:50
msgid ""
"the user-declared type of the struct member, or [Object] if\n"
"the user did not define a type for this member."
msgstr ""
"構造体memberの宣言されたユーザーの型、\\n\n"
"又はこのmember用にuserが、型を定義しなかった場合 [Object] となる。"

# YARD::Handlers::Ruby::StructHandlerMethods#add_reader_tags
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:55
msgid ""
"Creates the auto-generated docstring for the getter method of a struct's\n"
"member. This is used so the generated documentation will look just like "
"that\n"
"of an attribute defined using attr_accessor."
msgstr ""
"構造体memberのgetterメソッド用に自動生成されるdocstringを作成する。\n"
"これを用いて生成されるドキュメントは、attr_accessorによって定義された属性のよ"
"うに見える。"

# @return [String]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:61
msgid "a docstring to be attached to the getter method for this member"
msgstr "このmember用にgetterメソッドに加えられるdocstring"

# @param [ClassObject] klass
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:61
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:76
msgid "the class whose members we're working with"
msgstr "操作するmemberクラスに用いるクラス"

# @param [String] member
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:61
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:76
msgid "the name of the member we're generating documentation for"
msgstr "生成されるドキュメントのmemberの名前"

# YARD::Handlers::Ruby::StructHandlerMethods#add_writer_tags
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:70
msgid ""
"Creates the auto-generated docstring for the setter method of a struct's\n"
"member. This is used so the generated documentation will look just like "
"that\n"
"of an attribute defined using attr_accessor."
msgstr ""
"構造体のメンバーのsetterメソッド用に、自動生成されたdocstringを作成する。\n"
"これは、生成されたドキュメントが、\n"
"attr_accessorによって定義された属性のように見えるように利用される。"

# @return [String]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:76
msgid "a docstring to be attached to the setter method for this member"
msgstr "このメンバー用にsetterメソッドに加えられるdocstring"

# YARD::Handlers::Ruby::StructHandlerMethods#create_class
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:86
msgid ""
"Creates and registers a class object with the given name and superclass "
"name.\n"
"Returns it for further use."
msgstr ""
"与えられたクラス名、スーパークラス名と共に、\n"
"クラスオブジェクトを作成,記録する。\n"
"更に利用する為に返す。"

# @param [String]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:91
msgid "tag|param|classname"
msgstr "classname"

# @return [ClassObject]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:91
msgid "the class object for further processing/method attaching"
msgstr "処理/メソッドを加える為のクラスオブジェクト"

# @param [String] classname
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:91
msgid "the name of the class"
msgstr "クラスの名前"

# @param [String] superclass
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:91
msgid "the name of the superclass"
msgstr "スーパークラスの名前"

# YARD::Handlers::Ruby::StructHandlerMethods#create_writer
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:99
msgid ""
"Creates the setter (writer) method and attaches it to the class as an "
"attribute.\n"
"Also sets up the docstring to prettify the documentation output."
msgstr ""
"setter(writer)メソッドを作成し、属性としてクラスに追加する。\n"
"それに加え、ドキュメント出力を装飾する為にdocstringをセットアップする。"

# @param [ClassObject] klass
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:103
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:120
msgid "the class to attach the method to"
msgstr "クラスにメソッドを追加するクラス"

# @param [String] member
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:103
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:120
msgid "the name of the member we're generating a method for"
msgstr "私達がメソッド用に生成するメンバーの名前"

# YARD::Handlers::Ruby::StructHandlerMethods#create_reader
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:116
msgid ""
"Creates the getter (reader) method and attaches it to the class as an "
"attribute.\n"
"Also sets up the docstring to prettify the documentation output."
msgstr ""
"getter(reader)メソッドを作成し、属性として、クラスに追加する。\n"
"さらに、ドキュメント出力を装飾する為に、docstringをセットアップする。"

# YARD::Handlers::Ruby::StructHandlerMethods#create_attributes
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:130
msgid ""
"Creates the given member methods and attaches them to the given ClassObject."
msgstr ""
"与えられたメンバーメソッドを作成し、与えられたClassObjectにそれらを加える。"

# @param [Array]
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:133
msgid "tag|param|members"
msgstr "members"

# @param [ClassObject] klass
#: ../lib/yard/handlers/ruby/struct_handler_methods.rb:133
msgid "the class to generate attributes for"
msgstr "属性を生成するクラス用のクラス"

# YARD::I18n::Locale
#: ../lib/yard/i18n/locale.rb:7
msgid ""
"+Locale+ is a unit of translation. It has {#name} and a set of\n"
"messages."
msgstr ""

# @see http://tools.ietf.org/rfc/bcp/bcp47.txt
#: ../lib/yard/i18n/locale.rb:15
msgid "BCP 47 - Tags for Identifying Languages"
msgstr ""

# @see
#: ../lib/yard/i18n/locale.rb:15
msgid "tag|see|http://tools.ietf.org/rfc/bcp/bcp47.txt"
msgstr ""

# @return [String]
#: ../lib/yard/i18n/locale.rb:15
msgid ""
"the name of the locale. It used IETF language\n"
"tag format +[language[_territory][.codeset][@modifier]]+."
msgstr ""

# YARD::Handlers::Processor#initialize
#: ../lib/yard/i18n/locale.rb:18
msgid "Creates a locale for +name+ locale."
msgstr "+name+ の言語別にlocaleを作成する"

# @return [Logger]
#: ../lib/yard/i18n/locale.rb:20
msgid "a new instance of Locale"
msgstr "Localeの新しいインスタンス"

# @return [String]
#: ../lib/yard/i18n/locale.rb:20
msgid "the locale name."
msgstr "言語名(地域名)"

# YARD::I18n::Locale#load
#: ../lib/yard/i18n/locale.rb:26
msgid "Loads translation messages from +locale_directory+/{#name}.po."
msgstr "+locale_directory+/{#name}.po.から翻訳メッセージをロードする"

# @return [Boolean]
#: ../lib/yard/i18n/locale.rb:30
msgid "+true+ if PO file exists, +false+ otherwise."
msgstr "POファイルが存在すればtrue、そうでなければ、false"

# @param [Boolean]
#: ../lib/yard/i18n/locale.rb:30
msgid "tag|param|locale_directory"
msgstr ""

# @param [String] locale_directory
#: ../lib/yard/i18n/locale.rb:30
msgid ""
"the directory path that has\n"
"{#name}.po."
msgstr ""

# @since
#: ../lib/yard/i18n/locale.rb:45 ../lib/yard/logging.rb:11
#: ../lib/yard/logging.rb:15 ../lib/yard/logging.rb:82
#: ../lib/yard/logging.rb:106 ../lib/yard/logging.rb:117
msgid "0.8.2"
msgstr ""

# @param [NamespaceObject]
# @param [CodeObjects::NamespaceObject, nil]
# @param [CodeObjects::NamespaceObject]
#: ../lib/yard/i18n/locale.rb:45
msgid "tag|param|message"
msgstr ""

# @param [CodeObjects::NamespaceObject] namespace
#: ../lib/yard/i18n/locale.rb:45
msgid "the translation target message."
msgstr "翻訳目標のメッセージ"

# @return [String]
#: ../lib/yard/i18n/locale.rb:45
msgid ""
"translated message. If translation isn't\n"
"registered, the +message+ is returned."
msgstr ""

# YARD::I18n::Message
#: ../lib/yard/i18n/message.rb:6
msgid ""
"+Message+ is a translation target message. It has message ID as\n"
"{#id} and some properties {#locations} and {#comments}."
msgstr ""

# @param tag_name
#: ../lib/yard/i18n/message.rb:11
msgid "the message ID of the translation target message."
msgstr "翻訳目標のメッセージのメッセージID"

# @param [Fixnum, nil] line
#: ../lib/yard/i18n/message.rb:14
msgid "path and line number where the message is appered."
msgstr "メッセージが現れるところのパスと行数"

# @return [Set]
#: ../lib/yard/i18n/message.rb:15
msgid "the set of locations. Location is an array of"
msgstr ""

# @return [Array]
#: ../lib/yard/i18n/message.rb:18
msgid "the set of comments for the messages."
msgstr "メッセージ用のコメントのグループ"

# YARD::Handlers::Processor#initialize
#: ../lib/yard/i18n/message.rb:21
msgid "Creates a translate target message for message ID +id+."
msgstr "メッセージID +id+ 用の翻訳目標のメッセージを作成する"

# @return [Tag]
#: ../lib/yard/i18n/message.rb:23
msgid "a new instance of Message"
msgstr "メッセージの新しいインスタンス"

# @param [Fixnum]
#: ../lib/yard/i18n/message.rb:23 ../lib/yard/i18n/messages.rb:26
#: ../lib/yard/i18n/messages.rb:36
msgid "tag|param|id"
msgstr ""

# @param [String] id
#: ../lib/yard/i18n/message.rb:23
msgid "the message ID of the translate target message."
msgstr "翻訳目標のメッセージのメッセージID"

# YARD::I18n::Message#add_location
#: ../lib/yard/i18n/message.rb:30
msgid "Adds location information for the message."
msgstr "メッセージ用の地域情報を追加する"

# @param [Fixnum, nil] line
#: ../lib/yard/i18n/message.rb:34
msgid "the line number where the message appears."
msgstr "メッセージが見えるところの行数"

# @return [String]
#: ../lib/yard/i18n/message.rb:34
msgid "the path where the message appears."
msgstr "メッセージが見えるところのパス"

# YARD::I18n::Message#add_comment
#: ../lib/yard/i18n/message.rb:39
msgid "Adds a comment for the message."
msgstr "メッセージ用のコメントを追加する"

# @param [String, Array, Docstring]
# @param [String]
#: ../lib/yard/i18n/message.rb:42
msgid "tag|param|comment"
msgstr ""

# @return [String]
#: ../lib/yard/i18n/message.rb:42
msgid "the comment for the message to be added."
msgstr "追加されるメッセージ用のコメント"

# @return [Boolean]
#: ../lib/yard/i18n/message.rb:48
msgid "checks whether this message is equal to another."
msgstr "このメッセージが他と同じかどうか"

# @param [String] content
#: ../lib/yard/i18n/message.rb:48
msgid "the +Message+ to be compared."
msgstr "比較される為の +message+"

# YARD::I18n::Messages
#: ../lib/yard/i18n/messages.rb:4
msgid "Acts as a container for {Message} objects."
msgstr ""

# YARD::Logger#initialize
#: ../lib/yard/i18n/messages.rb:10
msgid "Creates a new container."
msgstr "新しいコンテナを作成する"

# @return [Tag]
#: ../lib/yard/i18n/messages.rb:10
msgid "a new instance of Messages"
msgstr "メッセージの新しいインスタンス"

# YARD::I18n::Messages#each
#: ../lib/yard/i18n/messages.rb:15
msgid "Enumerates each {Message} in the container."
msgstr ""

# @yieldparam [Tags::Tag]
#: ../lib/yard/i18n/messages.rb:19
msgid "tag|yieldparam|message"
msgstr ""

# @return [CodeObjects::RootObject]
#: ../lib/yard/i18n/messages.rb:19
msgid ""
"the next message object in\n"
"the enumeration."
msgstr "配列の中の次のメッセージオブジェクト"

# @return [Message, nil]
#: ../lib/yard/i18n/messages.rb:26
msgid ""
"a registered message for the given +id+,\n"
"or nil if no message for the ID is found."
msgstr ""

# @param [String] id
#: ../lib/yard/i18n/messages.rb:26
msgid "the message ID to perform a lookup on."
msgstr ""

# YARD::I18n::Messages#register
#: ../lib/yard/i18n/messages.rb:31
msgid ""
"Registers a {Message}, the message ID of which is +id+. If\n"
"corresponding +Message+ is already registered, the previously\n"
"registered object is returned."
msgstr ""

# @param [String] path
#: ../lib/yard/i18n/messages.rb:36
msgid "the ID of the message to be registered."
msgstr "記録されるメッセージのID"

# @return [CodeObjects::Base]
#: ../lib/yard/i18n/messages.rb:36
msgid "the registered +Message+."
msgstr "記録された +Message+"

# YARD::I18n::Messages#==
#: ../lib/yard/i18n/messages.rb:41
msgid "Checks if this messages list is equal to another messages list."
msgstr ""

# @param [#to_s] tag
#: ../lib/yard/i18n/messages.rb:44
msgid "the container to compare."
msgstr "比較するためのコンテナ"

# @return [Boolean]
#: ../lib/yard/i18n/messages.rb:44
msgid "whether +self+ and +other+ is equivalence or not."
msgstr ""

# @return [Array]
#: ../lib/yard/i18n/messages.rb:52
msgid "the set of message objects"
msgstr "メッセージオブジェクトのグループ"

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:6
msgid ""
"The +PotGenerator+ generates POT format string from\n"
"{CodeObjects::Base} and {CodeObjects::ExtraFileObject}."
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:9
msgid "== POT and PO"
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:11
msgid ""
"POT is an acronym for \"Portable Object Template\". POT is a\n"
"template file to create PO file. The extension for POT is\n"
"\".pot\". PO file is an acronym for \"Portable Object\". PO file has\n"
"many parts of message ID (msgid) that is translation target\n"
"message and message string (msgstr) that is translated message\n"
"of message ID. If you want to translate \"Hello\" in English into\n"
"\"Bonjour\" in French, \"Hello\" is the msgid ID and \"Bonjour\" is\n"
"msgstr. The extension for PO is \".po\"."
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:20
msgid "== How to extract msgids"
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:22
msgid "The +PotGenerator+ has two parse methods:"
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:24
msgid ""
"* {#parse_objects} for {CodeObjects::Base}\n"
"* {#parse_files} for {CodeObjects::ExtraFileObject}"
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:27
msgid ""
"{#parse_objects} extracts msgids from docstring and tags of\n"
"{CodeObjects::Base} objects. The docstring of\n"
"{CodeObjects::Base} object is parsed and a paragraph is\n"
"extracted as a msgid. Tag name and tag text are extracted as\n"
"msgids from a tag."
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:33
msgid ""
"{#parse_files} extracts msgids from\n"
"{CodeObjects::ExtraFileObject} objects. The file content of\n"
"{CodeObjects::ExtraFileObject} object is parsed and a paragraph\n"
"is extracted as a msgid."
msgstr ""

# YARD::I18n::PotGenerator
#: ../lib/yard/i18n/pot_generator.rb:40
msgid ""
"To create a .pot file by +PotGenerator+, instantiate a\n"
"+PotGenerator+ with a relative working directory path from a\n"
"directory path that has created .pot file, parse\n"
"{CodeObjects::Base} objects and {CodeObjects::ExtraFileObject}\n"
"objects, generate a POT and write the generated POT to a .pot\n"
"file. The relative working directory path is \"..\" when the\n"
"working directory path is \".\"  and the POT is wrote into\n"
"\"po/yard.pot\"."
msgstr ""

# @see http://www.gnu.org/software/gettext/manual/html_node/PO-Files.html
#: ../lib/yard/i18n/pot_generator.rb:64
msgid "GNU gettext manual about details of PO file"
msgstr ""

# @example Generate a .pot file
#: ../lib/yard/i18n/pot_generator.rb:64
msgid ""
"po_file_path = \"po/yard.pot\"\n"
"po_file_directory_pathname = Pathname.new(po_file_path).directory)\n"
"working_directory_pathname = Pathname.new(\".\")\n"
"relative_base_path = working_directory_pathname.relative_path_from"
"(po_file_directory_pathname).to_s\n"
"# relative_base_path -> \"..\"\n"
"generator = YARD::I18n::PotGenerator.new(relative_base_path)\n"
"generator.parse_objects(objects)\n"
"generator.parse_files(files)\n"
"pot = generator.generate\n"
"po_file_directory_pathname.mkpath\n"
"File.open(po_file_path, \"w\") do |pot_file|\n"
"  pot_file.print(pot)\n"
"end"
msgstr ""

# @example
#: ../lib/yard/i18n/pot_generator.rb:64
msgid "tag|example|Generate a .pot file"
msgstr "tag|example|.popファイルを生成する"

# @see
#: ../lib/yard/i18n/pot_generator.rb:64
msgid ""
"tag|see|http://www.gnu.org/software/gettext/manual/html_node/PO-Files.html"
msgstr ""

# YARD::I18n::PotGenerator#messages
#: ../lib/yard/i18n/pot_generator.rb:66
msgid "Extracted messages."
msgstr ""

# YARD::I18n::PotGenerator#initialize
#: ../lib/yard/i18n/pot_generator.rb:72
msgid ""
"Creates a POT generator that uses +relative_base_path+ to\n"
"generate locations for a msgid. +relative_base_path+ is\n"
"prepended to all locations."
msgstr ""

# @return [Router]
#: ../lib/yard/i18n/pot_generator.rb:78
msgid "a new instance of PotGenerator"
msgstr "PotGeneratorの新しいインスタンス"

# @param [String] relative_base_path
#: ../lib/yard/i18n/pot_generator.rb:78
msgid ""
"a relative working\n"
"directory path from a directory path that has created .pot\n"
"file."
msgstr ""

# @param [Boolean]
#: ../lib/yard/i18n/pot_generator.rb:78
msgid "tag|param|relative_base_path"
msgstr ""

# @param [Array] objects
#: ../lib/yard/i18n/pot_generator.rb:85
msgid ""
"Parses {CodeObjects::Base} objects and stores extracted msgids\n"
"into {#messages}"
msgstr ""
"{CodeObjects::Base}オブジェクトを解析し、\n"
"{#messages}メソッドの中へ抽出されたmsgidを登録する"

# @param [Array] objects
#: ../lib/yard/i18n/pot_generator.rb:90
msgid ""
"a list of\n"
"{CodeObjects::Base} to be parsed."
msgstr "解析される {CodeObjects::Base} のリスト"

# @deprecated
#: ../lib/yard/i18n/pot_generator.rb:97
msgid ""
"Parses {CodeObjects::ExtraFileObject} objects and stores\n"
"extracted msgids into {#messages}."
msgstr ""
"{CodeObjects::ExtraFileObject} オブジェクトを解析し、\n"
"抽出されたmsgidを{#messages}の中へ登録する。"

# @deprecated
#: ../lib/yard/i18n/pot_generator.rb:102
msgid ""
"a list\n"
"of {CodeObjects::ExtraFileObject} objects to be parsed."
msgstr "解析される {CodeObjects::ExtraFileObject} オブジェクトのリスト"

# YARD::I18n::PotGenerator#generate
#: ../lib/yard/i18n/pot_generator.rb:109
msgid "Generates POT from +@messages+."
msgstr ""

# YARD::I18n::PotGenerator#generate
#: ../lib/yard/i18n/pot_generator.rb:111
msgid ""
"One PO file entry is generated from a +Message+ in\n"
"+@messages+."
msgstr ""

# YARD::I18n::PotGenerator#generate
#: ../lib/yard/i18n/pot_generator.rb:114
msgid ""
"Locations of the +Message+ are used to generate the reference\n"
"line that is started with \"#: \". +relative_base_path+ passed\n"
"when the generator is created is prepended to each path in location."
msgstr ""

# YARD::I18n::PotGenerator#generate
#: ../lib/yard/i18n/pot_generator.rb:118
msgid ""
"Comments of the +Message+ are used to generate the\n"
"translator-comment line that is started with \"# \"."
msgstr ""

# @return [String]
#: ../lib/yard/i18n/pot_generator.rb:121
msgid "POT format string"
msgstr ""

# YARD::I18n::Text
#: ../lib/yard/i18n/text.rb:4
msgid "Provides some convenient features for translating a text."
msgstr ""

# YARD::I18n::Text#initialize
#: ../lib/yard/i18n/text.rb:6
msgid ""
"Creates a text object that has translation related features for\n"
"the input text."
msgstr ""

# @return [Text]
#: ../lib/yard/i18n/text.rb:11
msgid "a new instance of Text"
msgstr "Textの新しいインスタンス"

# @param [String] text
#: ../lib/yard/i18n/text.rb:11
msgid "a text to be translated."
msgstr "翻訳されるテキスト"

# @param [Fixnum, nil]
#: ../lib/yard/i18n/text.rb:11
msgid "tag|param|input"
msgstr ""

# YARD::I18n::Text#extract_messages
#: ../lib/yard/i18n/text.rb:17
msgid "Extracts translation target messages from +@input+."
msgstr ""

# @yieldparam [Array]
#: ../lib/yard/i18n/text.rb:34
msgid "tag|yieldparam|line_no"
msgstr ""

# @yieldparam [Tags::Tag]
#: ../lib/yard/i18n/text.rb:34
msgid "tag|yieldparam|name"
msgstr ""

# @yieldparam [Tags::Tag]
#: ../lib/yard/i18n/text.rb:34
msgid "tag|yieldparam|start_line_no"
msgstr ""

# @yieldparam [Tags::Tag]
#: ../lib/yard/i18n/text.rb:34
msgid "tag|yieldparam|text"
msgstr ""

# @yieldparam [Array]
#: ../lib/yard/i18n/text.rb:34 ../lib/yard/options.rb:142
msgid "tag|yieldparam|value"
msgstr ""

# @yield [:paragraph, text, start_line_no]
#: ../lib/yard/i18n/text.rb:34
msgid ""
"the block that\n"
"receives extracted a paragraph in body. Paragraph is a text\n"
"block separated by one or more empty lines. Empty line is a\n"
"line that contains only zero or more whitespaces. It may\n"
"called many times."
msgstr ""

# @yield [:attribute, name, value, line_no]
#: ../lib/yard/i18n/text.rb:34
msgid ""
"the block that\n"
"receives extracted an attribute in header. It may called many\n"
"times."
msgstr ""

# @return [Fixnum]
#: ../lib/yard/i18n/text.rb:34
msgid ""
"the defined line number of extracted\n"
"attribute."
msgstr "抽出された属性の定義された行数"

# @param [#to_s] key
#: ../lib/yard/i18n/text.rb:34
msgid "the name of extracted attribute."
msgstr "抽出された属性の名前"

# @return [Fixnum]
#: ../lib/yard/i18n/text.rb:34
msgid ""
"the start line number of\n"
"extracted paragraph."
msgstr "抽出された段落の最初の行数"

# @param [String] text
#: ../lib/yard/i18n/text.rb:34
msgid "the text of extracted paragraph."
msgstr "抽出された段落のテキスト"

# @param value
#: ../lib/yard/i18n/text.rb:34
msgid "the value of extracted attribute."
msgstr "抽出された属性の値"

# YARD::I18n::Text#translate
#: ../lib/yard/i18n/text.rb:49
msgid "Translates into +locale+."
msgstr ""

# @param [Object]
#: ../lib/yard/i18n/text.rb:52
msgid "tag|param|locale"
msgstr ""

# @return [String]
#: ../lib/yard/i18n/text.rb:52
msgid "the translation target locale."
msgstr "翻訳目標の地域"

# @return [String]
#: ../lib/yard/i18n/text.rb:52
msgid "translated text."
msgstr "翻訳されたテキスト"

# YARD::Logger
#: ../lib/yard/logging.rb:6
msgid ""
"Handles console logging for info, warnings and errors.\n"
"Uses the stdlib Logger class in Ruby for all the backend logic."
msgstr ""
"コンソールがinfoや,警告や,エラー用にロギングし操作する。\n"
"全てのバックエンドの処理の為にRuby標準ライブラリのloggerクラスを使う。"

# YARD::Logger::PROGRESS_INDICATORS
#: ../lib/yard/logging.rb:9
msgid ""
"The list of characters displayed beside the progress bar to indicate\n"
"\"movement\"."
msgstr ""

# @return [CodeObjects::Base]
#: ../lib/yard/logging.rb:15
msgid "the IO object being logged to"
msgstr "IOオブジェクトに記録されるIOオブジェクト"

# @return [Boolean]
#: ../lib/yard/logging.rb:19
msgid ""
"whether backtraces should be shown (by default\n"
"this is on)."
msgstr ""

# @param value
#: ../lib/yard/logging.rb:20
msgid "the value to set the attribute show_backtraces to."
msgstr "show_backtraces属性を設定する値"

# YARD::Logger#show_backtraces=
#: ../lib/yard/logging.rb:21
msgid "Sets the attribute show_backtraces"
msgstr "show_backtraces属性を設定する"

# @return [Boolean]
#: ../lib/yard/logging.rb:24
msgid ""
"whether progress indicators should be shown when\n"
"logging CLIs (by default this is off)."
msgstr ""

# @param value
#: ../lib/yard/logging.rb:30
msgid "the value to set the attribute show_progress to."
msgstr "値にshow_progress属性を設定する為の値"

# YARD::Logger#show_backtraces=
#: ../lib/yard/logging.rb:31
msgid "Sets the attribute show_progress"
msgstr "show_progress属性を設定する"

# YARD::Logger.instance
#: ../lib/yard/logging.rb:33
msgid "The logger instance"
msgstr "loggerインスタンス"

# @return [Logger]
#: ../lib/yard/logging.rb:34
msgid "the logger instance"
msgstr "loggerインスタンス"

# YARD::Logger#initialize
#: ../lib/yard/logging.rb:39
msgid "Creates a new logger"
msgstr "新しいloggerを作成する"

# @return [Logger]
#: ../lib/yard/logging.rb:39
msgid "a new instance of Logger"
msgstr "Loggerの新しいインスタンス"

# YARD::Logger#debug
#: ../lib/yard/logging.rb:51
msgid ""
"Changes the debug level to DEBUG if $DEBUG is set\n"
"and writes a debugging message."
msgstr ""
"$DEBUGが設定された場合、debug levelをDEBUGに変更し、\n"
"デバッグメッセージを書き込む。"

# YARD::Logger#capture
#: ../lib/yard/logging.rb:58
msgid ""
"Captures the duration of a block of code for benchmark analysis. Also\n"
"calls {#progress} on the message to display it to the user."
msgstr ""

# @todo
#: ../lib/yard/logging.rb:66
msgid "Implement capture storage for reporting of benchmarks"
msgstr ""

# @param [String] content
#: ../lib/yard/logging.rb:66
msgid "a block of arbitrary code to benchmark"
msgstr "ベンチマークの為の任意のコードの入ったブロック"

# @param [Symbol]
# @param [#to_s]
#: ../lib/yard/logging.rb:66 ../lib/yard/logging.rb:82
#: ../lib/yard/logging.rb:117
msgid "tag|param|msg"
msgstr ""

# @param [TokenList, String]
# @param [String]
# @param [String, #read, Object]
#: ../lib/yard/logging.rb:66 ../lib/yard/logging.rb:82
msgid "tag|param|nontty_log"
msgstr ""

# @param [Symbol, nil] nontty_log
#: ../lib/yard/logging.rb:66 ../lib/yard/logging.rb:82
msgid ""
"the level to log as if the output\n"
"stream is not a TTY. Use +nil+ for no alternate logging."
msgstr ""

# @return [String]
#: ../lib/yard/logging.rb:66 ../lib/yard/logging.rb:117
msgid "the message to display"
msgstr "表示するメッセージ"

# YARD::Logger#progress
#: ../lib/yard/logging.rb:74
msgid ""
"Displays a progress indicator for a given message. This progress report\n"
"is only displayed on TTY displays, otherwise the message is passed to\n"
"the +nontty_log+ level."
msgstr ""

# @param [String, CodeObjects::ExtraFileObject] filename
# @param [String] filename
#: ../lib/yard/logging.rb:82
msgid "the message to log"
msgstr "記録するメッセージ"

# YARD::Logger#clear_progress
#: ../lib/yard/logging.rb:104
msgid "Clears the progress indicator in the TTY display."
msgstr ""

# YARD::Logger#puts
#: ../lib/yard/logging.rb:113
msgid ""
"Displays an unformatted line to the logger output stream. Similar to\n"
"the +#<<+ method, but adds a newline."
msgstr ""

# YARD::Logger#backtrace
#: ../lib/yard/logging.rb:122
msgid "Prints the backtrace +exc+ to the logger as error data."
msgstr "+exc+ のバックトレースをエラーデータとしてloggerにプリントする。"

# @param [Array]
#: ../lib/yard/logging.rb:126
msgid "tag|param|exc"
msgstr "exc"

# @param [Fixnum]
#: ../lib/yard/logging.rb:126
msgid "tag|param|level_meth"
msgstr ""

# @param [Array] exc
#: ../lib/yard/logging.rb:126
msgid "the backtrace list"
msgstr "バックトレースのリスト"

# @param [Array] exc
#: ../lib/yard/logging.rb:126
msgid "the level to log backtrace at"
msgstr "バックトレースを記録する階層"

# YARD::Logger#warn_no_continuations
#: ../lib/yard/logging.rb:134
msgid ""
"Warns that the Ruby environment does not support continuations. Applies\n"
"to JRuby, Rubinius and MacRuby. This warning will only display once\n"
"per Ruby process."
msgstr ""
"Rubyの環境がcontinuationをサポートしない警告を出す。\n"
"JRuby,Rubinius,MacRubyに適用される。\n"
"この警告は、Rubyの処理毎に一度だけ表示されるだろう"

# @deprecated
#: ../lib/yard/logging.rb:139
msgid "Continuations are no longer needed by YARD 0.8.0+."
msgstr ""

# YARD::Logger#enter_level
#: ../lib/yard/logging.rb:143
msgid "Sets the logger level for the duration of the block"
msgstr "ブロックの継続するlogger levelを設定する。"

# @example 
#: ../lib/yard/logging.rb:151
msgid ""
"log.enter_level(Logger::ERROR) do\n"
"  YARD.parse_string \"def x; end\"\n"
"end"
msgstr ""

# @param [Fixnum]
#: ../lib/yard/logging.rb:151
msgid "tag|param|new_level"
msgstr "new_level"

# @yield
#: ../lib/yard/logging.rb:151
msgid "the block with the logger temporarily set to +new_level+"
msgstr "loggerが一時的に+new_level+を設定するブロック"

# @param [Fixnum] new_level
#: ../lib/yard/logging.rb:151
msgid ""
"the logger level for the duration of the block.\n"
"values can be found in Ruby's Logger class."
msgstr ""
"ブロックの継続するlogger level.\n"
"値はRuby loggerクラスで見つける事が出来る。"

# YARD::Logger#format_log
#: ../lib/yard/logging.rb:160
msgid "Log format (from Logger implementation). Used by Logger internally"
msgstr "ログ書式(loggerの実装から)。Loggerによって内部で利用される。"

# YARD::Options
#: ../lib/yard/options.rb:3
msgid ""
"Generalized options class for passing around large amounts of options "
"between objects."
msgstr ""

# YARD::Options
#: ../lib/yard/options.rb:5
msgid ""
"The options class exists for better visibility and documentability of "
"options being\n"
"passed through to other objects. Because YARD has parser and template "
"architectures\n"
"that are heavily reliant on options, it is necessary to make these option "
"keys easily\n"
"visible and understood by developers. Since the options class is more than "
"just a\n"
"basic Hash, the subclass can provide aliasing and convenience methods to "
"simplify\n"
"option property access, and, if needed, support backward-compatibility for "
"deprecated\n"
"key names."
msgstr ""

# YARD::Options
#: ../lib/yard/options.rb:13
msgid "== Hash and OpenStruct-like Access"
msgstr ""

# YARD::Options
#: ../lib/yard/options.rb:15
msgid ""
"Although the options class allows for Hash-like access (opts[:key]), the recommended\n"
"mechanism for accessing an option key will be via standard method calls on "
"attributes"
msgstr ""

# YARD::Options
#: ../lib/yard/options.rb:18
msgid ""
"The options class can also act as an open ended key value storage structure "
"(like a\n"
"Hash or OpenStruct), and allows for setting and getting of unregistered "
"option keys.\n"
"This methodology is not recommended, however, and is only supported for "
"backward\n"
"compatibility inside YARD. Whenever possible, developers should define all "
"keys used\n"
"by an options class."
msgstr ""

# YARD::Options
#: ../lib/yard/options.rb:24
msgid "== Declaring Default Values"
msgstr ""

# YARD::Options
#: ../lib/yard/options.rb:26
msgid ""
"Note that the options class can contain default value definitions for "
"certain options,\n"
"but to initialize these defaults, {#reset_defaults} must be called manually "
"after\n"
"initialization; the options object is always created empty until defaults "
"are applied."
msgstr ""

# @abstract
#: ../lib/yard/options.rb:68
msgid ""
"Subclasses should define (and document) custom attributes that are expected\n"
"to be made available as option keys."
msgstr ""

# @example Deprecating an option while still supporting it
#: ../lib/yard/options.rb:68
msgid ""
"class TemplateOptions < YARD::Options\n"
"  # @return [Boolean] if syntax highlighting should be performed on code "
"blocks.\n"
"  #   Defaults to true.\n"
"  attr_accessor :highlight\n"
"\n"
"  # @deprecated Use {#highlight} instead.\n"
"  # @return [Boolean] if no syntax highlighting should be performs on code "
"blocks.\n"
"  #   Defaults to false.\n"
"  attr_accessor :no_highlight\n"
"  def no_highlight=(value) @highlight = !value end\n"
"  def no_highlight; !highlight end\n"
"end"
msgstr ""

# @example Defining an Options class with custom option keys
#: ../lib/yard/options.rb:68
msgid ""
"class TemplateOptions < YARD::Options\n"
"  # @return [Symbol] the output format to generate templates in\n"
"  attr_accessor :format\n"
"\n"
"  # @return [Symbol] the template to use when generating output\n"
"  attr_accessor :template\n"
"end"
msgstr ""

# @example Initializing default option values
#: ../lib/yard/options.rb:68
msgid ""
"class TemplateOptions < YARD::Options\n"
"  def reset_defaults\n"
"    super\n"
"    self.format = :html\n"
"    self.template = :default\n"
"    self.highlight = true\n"
"    # ...\n"
"  end\n"
"end"
msgstr ""

# @example Using +default_attr+ to create default attributes
#: ../lib/yard/options.rb:68
msgid ""
"class TemplateOptions < YARD::Options\n"
"  default_attr :format, :html\n"
"  default_attr :template, :default\n"
"  default_attr :highlight, true\n"
"end"
msgstr ""

# @example
#: ../lib/yard/options.rb:68
msgid "tag|example|Defining an Options class with custom option keys"
msgstr "カスタムオプションのkeyを用いたオプションクラス定義"

# @example
#: ../lib/yard/options.rb:68
msgid "tag|example|Deprecating an option while still supporting it"
msgstr "まだサポートしているけれど廃止するオプション"

# @example
#: ../lib/yard/options.rb:68
msgid "tag|example|Initializing default option values"
msgstr "tag|example|初期化されたデフォルトのオプション値"

# @example
#: ../lib/yard/options.rb:68
msgid "tag|example|Using +default_attr+ to create default attributes"
msgstr "tag|example|デフォルト属性を作成するための +default_attr+ を用いる"

# YARD::Options.default_attr
#: ../lib/yard/options.rb:70
msgid "Defines an attribute named +key+ and sets a default value for it"
msgstr ""

# @example Defining a default option key
#: ../lib/yard/options.rb:79
msgid ""
"default_attr :name, 'Default Name'\n"
"default_attr :time, lambda { Time.now }"
msgstr ""

# @example
#: ../lib/yard/options.rb:79
msgid "tag|example|Defining a default option key"
msgstr "tag|example|デフォルトのオプションキーの定義"

# @param [Object]
#: ../lib/yard/options.rb:79
msgid "tag|param|default"
msgstr ""

# @param [Object, Proc] default
#: ../lib/yard/options.rb:79
msgid ""
"the default object value. If the default\n"
"value is a proc, it is executed upon initialization."
msgstr ""

# @param [String, Symbol] section
#: ../lib/yard/options.rb:79
msgid "the option key name"
msgstr "オプションキー名"

# YARD::Options#[]
#: ../lib/yard/options.rb:85
msgid "Delegates calls with Hash syntax to actual method with key name"
msgstr ""

# @example Calling on an option key with Hash syntax
#: ../lib/yard/options.rb:90
msgid "options[:format] # equivalent to: options.format"
msgstr ""

# @example
#: ../lib/yard/options.rb:90
msgid "tag|example|Calling on an option key with Hash syntax"
msgstr "tag|example|ハッシュ構文を用いたオプションキーを呼び出す"

# @param [Hash] opts
#: ../lib/yard/options.rb:90
msgid "the option name to access"
msgstr "アクセスするためのオプション名"

# @param value
#: ../lib/yard/options.rb:90
msgid "the value of the option named +key+"
msgstr "+key+ と名付けられたオプションの値"

# YARD::Options#[]=
#: ../lib/yard/options.rb:93
msgid ""
"Delegates setter calls with Hash syntax to the attribute setter with the key "
"name"
msgstr ""

# @example Setting an option with Hash syntax
#: ../lib/yard/options.rb:99
msgid "options[:format] = :html # equivalent to: options.format = :html"
msgstr ""

# @example
#: ../lib/yard/options.rb:99
msgid "tag|example|Setting an option with Hash syntax"
msgstr "tag|example|ハッシュ構文を用いたオプションの設定"

# @param [Hash] options
#: ../lib/yard/options.rb:99
msgid "the option to set"
msgstr "設定するためのオプション"

# @param [Object] value
# @param [Object] val
#: ../lib/yard/options.rb:99
msgid "the value being set"
msgstr "設定される値"

# @param [String] title
#: ../lib/yard/options.rb:99
msgid "the value to set for the option"
msgstr "オプション用に設定するための値"

# YARD::Options#update
#: ../lib/yard/options.rb:102
msgid ""
"Updates values from an options hash or options object on this object.\n"
"All keys passed should be key names defined by attributes on the class."
msgstr ""

# @example Updating a set of options on an Options object
#: ../lib/yard/options.rb:108
msgid "opts.update(:template => :guide, :type => :fulldoc)"
msgstr ""

# @example
#: ../lib/yard/options.rb:108
msgid "tag|example|Updating a set of options on an Options object"
msgstr "tag|example|オプションオブジェクトでオプションのグループの更新"

# YARD::Options#merge
#: ../lib/yard/options.rb:117
msgid ""
"Creates a new options object and sets options hash or object value\n"
"onto that object."
msgstr ""

# @see
#: ../lib/yard/options.rb:122
msgid "tag|see|#update"
msgstr ""

# @return [Base]
# @return [MacroObject]
#: ../lib/yard/options.rb:122
msgid "the newly created options object"
msgstr "新たに作成されたオプションオブジェクト"

# @return [Hash]
#: ../lib/yard/options.rb:128
msgid ""
"Converts options object to an options hash. All keys\n"
"will be symbolized."
msgstr ""

# YARD::Options#each
#: ../lib/yard/options.rb:138
msgid "Yields over every option key and value"
msgstr ""

# @yield [key, value]
#: ../lib/yard/options.rb:142
msgid "every option key and value"
msgstr ""

# @yieldparam [Base]
#: ../lib/yard/options.rb:142
msgid "tag|yieldparam|key"
msgstr ""

# @param [Hash] options
#: ../lib/yard/options.rb:142
msgid "the option key"
msgstr "オプションのキー"

# @param [Hash] options
#: ../lib/yard/options.rb:142
msgid "the option value"
msgstr "オプションの値"

# @return [String]
#: ../lib/yard/options.rb:150
msgid "Inspects the object"
msgstr "オブジェクトを解析する"

# @return [Boolean]
#: ../lib/yard/options.rb:156
msgid ""
"whether another Options object equals the\n"
"keys and values of this options object"
msgstr ""

# YARD::Options#method_missing
#: ../lib/yard/options.rb:165
msgid ""
"Handles setting and accessing of unregistered keys similar\n"
"to an OpenStruct object."
msgstr ""

# @note
#: ../lib/yard/options.rb:169
msgid ""
"It is not recommended to set and access unregistered keys on\n"
"an Options object. Instead, register the attribute before using it."
msgstr ""

# YARD::Tags::DefaultTag#defaults
#: ../lib/yard/options.rb:182
msgid "Resets all values to their defaults."
msgstr "それらのデフォルトの全ての値をリセットする"

# @abstract
#: ../lib/yard/options.rb:187
msgid ""
"Subclasses should override this method to perform custom\n"
"value initialization if not using {default_attr}. Be sure to call\n"
"+super+ so that default initialization can take place."
msgstr ""

# YARD::Options#delete
#: ../lib/yard/options.rb:201
msgid "Deletes an option value for +key+"
msgstr ""

# @param [#to_sym] key
#: ../lib/yard/options.rb:204
msgid "the key to delete a value for"
msgstr "キー用に値を削除する為のキー"

# @param [String] data
#: ../lib/yard/options.rb:204
msgid "the value that was deleted"
msgstr "削除された値"

# YARD::Parser::Base
#: ../lib/yard/parser/base.rb:4
msgid ""
"Represents the abstract base parser class that parses source code in\n"
"a specific way. A parser should implement {#parse}, {#tokenize} and\n"
"{#enumerator}."
msgstr ""
"独自の方法でソースコードを解析する抽象的なベースパーサークラスを表す。\n"
"パーサーは{#parse}や,{#tokenize}や{#enumerator}メソッドを実装しなくてはならな"
"い。"

# YARD::Parser::Base
#: ../lib/yard/parser/base.rb:8
msgid ""
"== Registering a Custom Parser\n"
"To register a parser, see {SourceParser.register_parser_type}"
msgstr ""
"== カスタムパーサーを記録する\n"
"パーサーを記録する為には、{SourceParser.register_parser_type}を参照。"

# @see
#: ../lib/yard/parser/base.rb:15
msgid "tag|see|#enumerator"
msgstr ""

# @see
#: ../lib/yard/parser/base.rb:15
msgid "tag|see|#parse"
msgstr ""

# @see
#: ../lib/yard/parser/base.rb:15
msgid "tag|see|#tokenize"
msgstr ""

# YARD::Parser::Base.parse
#: ../lib/yard/parser/base.rb:17
msgid "Convenience method to create a new parser and {#parse}"
msgstr "新しいパーサーや(#parse)メソッドを作成する為の便利なメソッド"

# YARD::Parser::Base#initialize
#: ../lib/yard/parser/base.rb:22
msgid ""
"This default constructor does nothing. The subclass is responsible for\n"
"storing the source contents and filename if they are required."
msgstr ""
"このデフォルトのコンストラクターは何もしない。\n"
"サブクラスがソースの内容やファイル名が必要とされる場合、それらを記憶する責任"
"がある。"

# @param [String] filename
#: ../lib/yard/parser/base.rb:25
msgid "the name of the file if from disk"
msgstr "ディスクからの場合、ファイルの名前"

# @param [String] source
#: ../lib/yard/parser/base.rb:25
msgid "the source contents"
msgstr "ソースの内容"

# YARD::Parser::Base#parse
#: ../lib/yard/parser/base.rb:30
msgid ""
"This method should be implemented to parse the source and return itself."
msgstr ""
"このメソッドはソースの解析やそれ自身を返す為に\n"
"実装されなくてはならない。"

# @return [Base]
#: ../lib/yard/parser/base.rb:32
msgid "this method should return itself"
msgstr "このメソッドはそれ自身を返さなくてはならない。"

# YARD::Parser::Base#tokenize
#: ../lib/yard/parser/base.rb:37
msgid "This method should be implemented to tokenize given source"
msgstr ""
"このメソッドは与えられたソースを\n"
"トークナイズする為に実装されなければならない。"

# @return [Array]
#: ../lib/yard/parser/base.rb:39
msgid "a list/tree of lexical tokens"
msgstr "単語のトークンの入ったリストやツリー"

# YARD::Parser::Base#enumerator
#: ../lib/yard/parser/base.rb:44
msgid ""
"This method should be implemented to return a list of semantic tokens\n"
"representing the source code to be post-processed. Otherwise the method\n"
"should return nil."
msgstr ""
"後処理される為にソースコードを表している意味のあるトークンのリストを返す為"
"に\n"
"このメソッドは実装されなければならない。\n"
"そうでなければこのメソッドは、nilを返さなければならない。"

# @return [Array]
#: ../lib/yard/parser/base.rb:51
msgid ""
"a list of semantic tokens representing the source code\n"
"to be post-processed"
msgstr "後処理される為のソースコードを表す意味のあるトークンのリスト"

# @return [nil]
#: ../lib/yard/parser/base.rb:51
msgid "if no post-processing should be done"
msgstr "後処理がない場合、nilを返さなければならない。"

# @return [CParser]
#: ../lib/yard/parser/c/c_parser.rb:5
msgid "a new instance of CParser"
msgstr "Cパーサーの新しいインスタンス"

# @param value
#: ../lib/yard/parser/c/statement.rb:5 ../lib/yard/parser/ruby/ast_node.rb:42
msgid "the value to set the attribute source to."
msgstr "ソースの属性を設定する,値"

# YARD::Parser::Ruby::AstNode#to_s
#: ../lib/yard/parser/c/statement.rb:6 ../lib/yard/parser/ruby/ast_node.rb:53
msgid "Returns the value of attribute source"
msgstr "source属性の入った値を返す。"

# YARD::Parser::Ruby::AstNode#source=
#: ../lib/yard/parser/c/statement.rb:6 ../lib/yard/parser/ruby/ast_node.rb:43
msgid "Sets the attribute source"
msgstr "ソース属性を設定する。"

# @param value
#: ../lib/yard/parser/c/statement.rb:6
msgid "the value to set the attribute line to."
msgstr "値に行属性を設定するための値"

# YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader#line_num
#: ../lib/yard/parser/c/statement.rb:7
msgid "Returns the value of attribute line"
msgstr "行属性の値を返す"

# YARD::CodeObjects::ExtraFileObject#name=
# YARD::Tags::RefTagList#name=
# YARD::Templates::Section#name=
#: ../lib/yard/parser/c/statement.rb:7
msgid "Sets the attribute line"
msgstr "行属性を設定"

# @param value
#: ../lib/yard/parser/c/statement.rb:7 ../lib/yard/parser/ruby/ast_node.rb:48
msgid "the value to set the attribute file to."
msgstr "ファイル属性を設定する,値"

# YARD::Parser::Ruby::RipperParser#file
# YARD::RegistryStore#file
#: ../lib/yard/parser/c/statement.rb:8
#: ../lib/yard/parser/ruby/ruby_parser.rb:26 ../lib/yard/registry_store.rb:12
msgid "Returns the value of attribute file"
msgstr "file属性の値を返す。"

# YARD::Parser::Ruby::AstNode#file=
#: ../lib/yard/parser/c/statement.rb:8 ../lib/yard/parser/ruby/ast_node.rb:49
msgid "Sets the attribute file"
msgstr "ファイル属性を設定する。"

# @deprecated
#: ../lib/yard/parser/c/statement.rb:11 ../lib/yard/parser/ruby/ast_node.rb:46
#: ../lib/yard/parser/ruby/legacy/statement.rb:9
msgid "Groups are now defined by directives"
msgstr ""

# @see
#: ../lib/yard/parser/c/statement.rb:11 ../lib/yard/parser/ruby/ast_node.rb:46
#: ../lib/yard/parser/ruby/legacy/statement.rb:9
msgid "tag|see|Tags::GroupDirective"
msgstr ""

# @param value
#: ../lib/yard/parser/c/statement.rb:13
#: ../lib/yard/parser/ruby/legacy/statement.rb:11
msgid "the value to set the attribute comments_hash_flag to."
msgstr "comments_hash_flag属性を設定する。"

# YARD::Parser::Ruby::Legacy::Statement#comments_hash_flag
#: ../lib/yard/parser/c/statement.rb:14
#: ../lib/yard/parser/ruby/legacy/statement.rb:12
msgid "Returns the value of attribute comments_hash_flag"
msgstr "comments_hash_flag属性を返す。"

# YARD::Parser::Ruby::Legacy::Statement#comments_hash_flag=
#: ../lib/yard/parser/c/statement.rb:14
#: ../lib/yard/parser/ruby/legacy/statement.rb:12
msgid "Sets the attribute comments_hash_flag"
msgstr "comments_hash_flag属性を設定する。"

# @return [Statement]
#: ../lib/yard/parser/c/statement.rb:15
#: ../lib/yard/parser/ruby/legacy/statement.rb:13
msgid "a new instance of Statement"
msgstr "ステートメントの新しいインスタンス"

# @param value
#: ../lib/yard/parser/c/statement.rb:39 ../lib/yard/parser/c/statement.rb:45
msgid "the value to set the attribute comments to."
msgstr "値にコメント属性を設定するための値"

# YARD::Parser::Ruby::Legacy::Statement#comments
# YARD::Parser::Ruby::RipperParser#comments
#: ../lib/yard/parser/c/statement.rb:40 ../lib/yard/parser/c/statement.rb:46
#: ../lib/yard/parser/ruby/legacy/statement.rb:5
#: ../lib/yard/parser/ruby/ruby_parser.rb:26
msgid "Returns the value of attribute comments"
msgstr "コメント属性の値を返す。"

# YARD::CodeObjects::NamespaceObject#meths=
#: ../lib/yard/parser/c/statement.rb:40 ../lib/yard/parser/c/statement.rb:46
msgid "Sets the attribute comments"
msgstr "コメント属性を設定する"

# @param value
#: ../lib/yard/parser/c/statement.rb:43
msgid "the value to set the attribute block to."
msgstr "値にblock属性を設定するための値"

# YARD::Parser::Ruby::Legacy::Statement#block
#: ../lib/yard/parser/c/statement.rb:44
#: ../lib/yard/parser/ruby/legacy/statement.rb:5
msgid "Returns the value of attribute block"
msgstr "ブロック属性の値を返す。"

# YARD::Parser::Ruby::AstNode#source=
#: ../lib/yard/parser/c/statement.rb:44
msgid "Sets the attribute block"
msgstr "block属性を設定する。"

# @param value
#: ../lib/yard/parser/c/statement.rb:44
msgid "the value to set the attribute declaration to."
msgstr "値に宣言属性を設定するための値"

# YARD::Templates::Template#section
#: ../lib/yard/parser/c/statement.rb:45
msgid "Returns the value of attribute declaration"
msgstr "宣言属性の値を返す"

# YARD::Templates::Template#section=
#: ../lib/yard/parser/c/statement.rb:45
msgid "Sets the attribute declaration"
msgstr "宣言属性を設定する"

# @param value
#: ../lib/yard/parser/c/statement.rb:51
msgid "the value to set the attribute type to."
msgstr "値に型属性を設定するための値"

# YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN#op
#: ../lib/yard/parser/c/statement.rb:52
msgid "Returns the value of attribute type"
msgstr "型属性の値を返す"

# YARD::CodeObjects::ExtraFileObject#name=
# YARD::Tags::RefTagList#name=
# YARD::Templates::Section#name=
#: ../lib/yard/parser/c/statement.rb:52
msgid "Sets the attribute type"
msgstr "型属性を設定する"

# @param value
#: ../lib/yard/parser/c/statement.rb:52
msgid "the value to set the attribute overrides to."
msgstr "値にオーバーライド属性を設定するための値"

# YARD::Parser::Ruby::Legacy::RubyToken::TkNode#node
#: ../lib/yard/parser/c/statement.rb:53
msgid "Returns the value of attribute overrides"
msgstr "オーバーライド属性の値を返す"

# YARD::Tags::RefTag#owner=
# YARD::Tags::RefTagList#owner=
#: ../lib/yard/parser/c/statement.rb:53
msgid "Sets the attribute overrides"
msgstr "オーバーライド属性を設定する"

# @param value
#: ../lib/yard/parser/c/statement.rb:53
msgid "the value to set the attribute statement to."
msgstr "値にステートメント属性を設定するための値"

# YARD::CodeObjects::ExtraFileObject#name
# YARD::CodeObjects::ExtraFileObject#path
# YARD::Parser::Ruby::Legacy::RubyToken::TkId#name
# YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar#name
# YARD::Tags::RefTagList#name
# YARD::Templates::Section#name
#: ../lib/yard/parser/c/statement.rb:54
msgid "Returns the value of attribute statement"
msgstr "ステートメント属性の値を返す"

# YARD::CodeObjects::ExtraFileObject#name=
# YARD::Tags::RefTagList#name=
# YARD::Templates::Section#name=
#: ../lib/yard/parser/c/statement.rb:54
msgid "Sets the attribute statement"
msgstr "ステートメント属性を設定する"

# @return [Token]
#: ../lib/yard/parser/c/statement.rb:55
msgid "a new instance of Comment"
msgstr "コメントの新しいインスタンス"

# YARD::Parser::Ruby#s
#: ../lib/yard/parser/ruby/ast_node.rb:5
msgid ""
"Builds and s-expression by creating {AstNode} objects with\n"
"the type provided by the first argument."
msgstr ""
"最初の引数によって提供された型を用い{AstNode}オブジェクトを作成する事によって\n"
"ビルドされS式にされる。"

# @example An implicit list of keywords
#: ../lib/yard/parser/ruby/ast_node.rb:24
msgid ""
"ast = s(s(:kw, \"if\"), s(:kw, \"else\"))\n"
"ast.type # => :list"
msgstr ""

# @example A method call
#: ../lib/yard/parser/ruby/ast_node.rb:24
msgid "s(:command, s(:var_ref, \"mymethod\"))"
msgstr ""

# @example
#: ../lib/yard/parser/ruby/ast_node.rb:24
msgid "tag|example|A method call"
msgstr "メソッド呼び出し"

# @example
#: ../lib/yard/parser/ruby/ast_node.rb:24
msgid "tag|example|An implicit list of keywords"
msgstr "キーワードの暗黙のリスト"

# @overload
#: ../lib/yard/parser/ruby/ast_node.rb:24
msgid "tag|overload|s"
msgstr ""

# @see
#: ../lib/yard/parser/ruby/ast_node.rb:24
msgid "tag|see|AstNode#initialize"
msgstr ""

# YARD::Parser::Ruby::AstNode
#: ../lib/yard/parser/ruby/ast_node.rb:31
msgid ""
"An AST node is characterized by a type and a list of children. It\n"
"is most easily represented by the s-expression {#s} such as:\n"
"  # AST for \"if true; 5 end\":\n"
"  s(s(:if, s(:var_ref, s(:kw, \"true\")), s(s(:int, \"5\")), nil))"
msgstr ""
"ASTノードは型や子のリストによって特徴付けられる。\n"
"それは最も簡単にS式 {#s}メソッドによって表される。\n"
"以下の通り。\n"
"  # AST for \"if true; 5 end\":\n"
"  s(s(:if, s(:var_ref, s(:kw, \"true\")), s(s(:int, \"5\")), nil))"

# YARD::Parser::Ruby::AstNode
#: ../lib/yard/parser/ruby/ast_node.rb:36
msgid ""
"The node type is not considered part of the list, only its children.\n"
"So +ast[0]+ does not refer to the type, but rather the first child\n"
"(or object). Items that are not +AstNode+ objects can be part of the\n"
"list, like Strings or Symbols representing names. To return only\n"
"the AstNode children of the node, use {#children}."
msgstr ""
"ノードの型は、リストの一部とは考えられていない。\n"
"その為,そのリストは子だけとなる。\n"
"そして +ast[0]+ は型を参照しない、\n"
"しかし、最初の子(やオブジェクト)が選ばれる。\n"
"+AstNode+ オブジェクトではない事項は、リストの一部にでき、\n"
"文字列やシンボルのように、名前を表現している。\n"
"ノードからAstNodeの子だけ返すには、{#children}メソッドを使用する。"

# @param value
#: ../lib/yard/parser/ruby/ast_node.rb:41
msgid "the value to set the attribute docstring_hash_flag to."
msgstr "docstring_hash_flag属性を設定する,値"

# YARD::Parser::Ruby::AstNode#docstring_hash_flag
# YARD::Parser::Ruby::AstNode#comments_hash_flag
#: ../lib/yard/parser/ruby/ast_node.rb:42
#: ../lib/yard/parser/ruby/ast_node.rb:52
msgid "Returns the value of attribute docstring_hash_flag"
msgstr "docstring_hash_flag属性の値を返す。"

# YARD::Parser::Ruby::AstNode#docstring_hash_flag=
#: ../lib/yard/parser/ruby/ast_node.rb:42
msgid "Sets the attribute docstring_hash_flag"
msgstr "docstring_hash_flag属性を設定する。"

# @return [String]
#: ../lib/yard/parser/ruby/ast_node.rb:42
#: ../lib/yard/parser/ruby/ast_node.rb:88
msgid "the parse of {#full_source} that the node represents"
msgstr "ノードを表す{#full_source}の入った,parse"

# @param value
#: ../lib/yard/parser/ruby/ast_node.rb:42
msgid "the value to set the attribute docstring to."
msgstr "docstring属性を設定する,値"

# @param value
#: ../lib/yard/parser/ruby/ast_node.rb:42
msgid "the value to set the attribute docstring_range to."
msgstr "docstring_range属性を設定する,値"

# YARD::Parser::Ruby::AstNode#docstring
# YARD::Parser::Ruby::AstNode#comments
# YARD::Tags::OverloadTag#docstring
#: ../lib/yard/parser/ruby/ast_node.rb:43
#: ../lib/yard/parser/ruby/ast_node.rb:50 ../lib/yard/tags/overload_tag.rb:5
msgid "Returns the value of attribute docstring"
msgstr "docstring属性の入った値を返す。"

# YARD::Parser::Ruby::AstNode#docstring_range
# YARD::Parser::Ruby::AstNode#comments_range
#: ../lib/yard/parser/ruby/ast_node.rb:43
#: ../lib/yard/parser/ruby/ast_node.rb:51
msgid "Returns the value of attribute docstring_range"
msgstr "docstring_range属性の入った値を返す。"

# YARD::Parser::Ruby::AstNode#docstring=
#: ../lib/yard/parser/ruby/ast_node.rb:43
msgid "Sets the attribute docstring"
msgstr "docstring属性を設定する。"

# YARD::Parser::Ruby::AstNode#docstring_range=
#: ../lib/yard/parser/ruby/ast_node.rb:43
msgid "Sets the attribute docstring_range"
msgstr "docstring_range属性を設定する。"

# @param value
#: ../lib/yard/parser/ruby/ast_node.rb:48
msgid "the value to set the attribute full_source to."
msgstr "full_source属性を設定する,値"

# @param value
#: ../lib/yard/parser/ruby/ast_node.rb:48
msgid "the value to set the attribute line_range to."
msgstr "line_range属性を設定する,値"

# @param value
#: ../lib/yard/parser/ruby/ast_node.rb:48
msgid "the value to set the attribute source_range to."
msgstr "source_range属性を設定する,値"

# YARD::Parser::Ruby::AstNode#full_source=
#: ../lib/yard/parser/ruby/ast_node.rb:49
msgid "Sets the attribute full_source"
msgstr "full_source属性を設定する。"

# YARD::Parser::Ruby::AstNode#line_range=
#: ../lib/yard/parser/ruby/ast_node.rb:49
msgid "Sets the attribute line_range"
msgstr "line_range属性を設定する。"

# YARD::Parser::Ruby::AstNode#source_range=
#: ../lib/yard/parser/ruby/ast_node.rb:49
msgid "Sets the attribute source_range"
msgstr "source_range属性を設定する。"

# @return [Symbol]
#: ../lib/yard/parser/ruby/ast_node.rb:55
msgid "the node's unique symbolic type"
msgstr "独自のsymbolic型のノード群。"

# @return [AstNode, nil]
#: ../lib/yard/parser/ruby/ast_node.rb:58
msgid "the node's parent or nil if it is a root node."
msgstr "親ノード群(ルートノードの場合,nilとなる。)"

# @return [Range]
#: ../lib/yard/parser/ruby/ast_node.rb:62
msgid ""
"the character range in {#full_source} represented\n"
"by the node"
msgstr "ノードによって表される{#full_source}メソッドの中の固有の範囲。"

# @return [Range]
#: ../lib/yard/parser/ruby/ast_node.rb:69
msgid ""
"the line range in {#full_source} represented\n"
"by the node"
msgstr "ノードによって表される{#full_source}メソッドの中の行の範囲。"

# @return [String]
#: ../lib/yard/parser/ruby/ast_node.rb:75
msgid "the filename the node was parsed from"
msgstr "ノードを解析した,ファイル名"

# @return [String]
#: ../lib/yard/parser/ruby/ast_node.rb:81
msgid "the full source that the node was parsed from"
msgstr "ノードから解析されたソースの全て。"

# YARD::Parser::Ruby::AstNode::KEYWORDS
#: ../lib/yard/parser/ruby/ast_node.rb:94
msgid "List of all known keywords"
msgstr "著名なキーワードのリスト。"

# YARD::Parser::Ruby::AstNode.node_class_for
#: ../lib/yard/parser/ruby/ast_node.rb:106
msgid ""
"Finds the node subclass that should be instantiated for a specific\n"
"node type"
msgstr ""
"特定のノード型用の\n"
"インスタンス化されるべきサブクラスのノードを見つける。"

# YARD::Parser::Ruby::AstNode.node_class_for
# YARD::Parser::Ruby::AstNode#initialize
# YARD::Parser::Ruby::AstNode#==
#: ../lib/yard/parser/ruby/ast_node.rb:110
#: ../lib/yard/parser/ruby/ast_node.rb:152
#: ../lib/yard/parser/ruby/ast_node.rb:165
msgid "Creating an AstNode"
msgstr "AstNodeを作成する。"

# @return [Class]
#: ../lib/yard/parser/ruby/ast_node.rb:110
msgid "a subclass of AstNode to instantiate the node with."
msgstr "nodeをインスタンス化するAstNodeのサブクラス"

# @param [Symbol] type
#: ../lib/yard/parser/ruby/ast_node.rb:110
msgid "the node type to find a subclass for"
msgstr "ノードの型用のサブクラスを見つける,型"

# YARD::Parser::Ruby::AstNode#initialize
#: ../lib/yard/parser/ruby/ast_node.rb:140
msgid "Creates a new AST node"
msgstr "新しいASTノードを作成する。"

# @return [AstNode]
#: ../lib/yard/parser/ruby/ast_node.rb:152
msgid "a new instance of AstNode"
msgstr "AstNodeの新しいインスタンス"

# @param [Hash] opts
#: ../lib/yard/parser/ruby/ast_node.rb:152
msgid "any extra line options"
msgstr "行の為の追加の設定"

# @param [Array]
#: ../lib/yard/parser/ruby/ast_node.rb:152
msgid "tag|param|arr"
msgstr ""

# @param [Array] arr
#: ../lib/yard/parser/ruby/ast_node.rb:152
msgid "the child nodes"
msgstr "子のノード"

# @param [Symbol] type
#: ../lib/yard/parser/ruby/ast_node.rb:152
msgid "the type of node being created"
msgstr "作成されるノードのタイプ"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:165
msgid ""
"whether the node is equal to another by checking\n"
"the list and type"
msgstr "ノードがリストか型かチェックすることによって他と等しくなるかどうか"

# YARD::Parser::Ruby::AstNode#jump
#: ../lib/yard/parser/ruby/ast_node.rb:172
msgid ""
"Searches through the node and all descendants and returns the\n"
"first node with a type matching any of +node_types+, otherwise\n"
"returns the original node (self)."
msgstr ""
"ノードや,全ての子孫の中を検索する。\n"
"+node_types+ の入った型マッチと共に\n"
"最初のノードを返す。\n"
"さもなければ、(自身の)オリジナルノードを返す。"

# YARD::Parser::Ruby::AstNode#jump
# YARD::Parser::Ruby::AstNode#children
# YARD::Parser::Ruby::AstNode#traverse
#: ../lib/yard/parser/ruby/ast_node.rb:191
#: ../lib/yard/parser/ruby/ast_node.rb:197
#: ../lib/yard/parser/ruby/ast_node.rb:206
msgid "Traversing a Node"
msgstr "ノードを辿る。"

# @param [Array] node_types
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid "a set of node types to match"
msgstr "マッチするノードの型の設定。"

# @example If the node types are not present in the AST
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid ""
"ast = YARD.parse(\"def x; end\")\n"
"ast.jump(:def)"
msgstr ""

# @example Returns first 'def' or 'class' statement
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid ""
"ast = YARD.parse_string(\"class X; def y; end end\")\n"
"ast.jump(:def, :class).first\n"
"# =>"
msgstr ""

# @example Returns the first method definition in a block of code
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid ""
"ast = YARD.parse_string(\"if true; def x; end end\").ast\n"
"ast.jump(:def)\n"
"# => s(:def, s(:ident, \"x\"), s(:params, nil, nil, nil, nil,\n"
"#      nil), s(s(:void_stmt, )))"
msgstr ""

# @return [self]
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid "if no node was found"
msgstr "ノードが見つからなかった場合"

# @example
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid "tag|example|If the node types are not present in the AST"
msgstr "ノードの型がASTの中に渡さない場合"

# @example
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid "tag|example|Returns first 'def' or 'class' statement"
msgstr "最初の'def'や'class'ステートメントを返す。"

# @example
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid "tag|example|Returns the first method definition in a block of code"
msgstr "コードのブロックの中の最初のメソッド定義を返す。"

# @param [Array]
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid "tag|param|node_types"
msgstr ""

# @return [AstNode]
#: ../lib/yard/parser/ruby/ast_node.rb:191
msgid "the matching node, if one was found"
msgstr "マッチするノード(一つ見つかった場合)"

# @return [Array]
#: ../lib/yard/parser/ruby/ast_node.rb:197
msgid "the {AstNode} children inside the node"
msgstr "ノード内部の{AstNode}の子。"

# YARD::Parser::Ruby::AstNode#traverse
#: ../lib/yard/parser/ruby/ast_node.rb:202
msgid ""
"Traverses the object and yields each node (including descendants) in order."
msgstr ""
"オブジェクトを辿り、\n"
"順番にそれぞれのノード(子孫を含んでいる)を\n"
"yieldする。"

# @yield
#: ../lib/yard/parser/ruby/ast_node.rb:206
msgid "each descendant node in order"
msgstr "整理されたそれぞれの子孫のノード。"

# @yieldparam [AstNode] self,
#: ../lib/yard/parser/ruby/ast_node.rb:206
msgid "or a child/descendant node"
msgstr "自身や子や子孫のノード。"

# @yieldparam [AstNode]
#: ../lib/yard/parser/ruby/ast_node.rb:206
msgid "tag|yieldparam|self,"
msgstr ""

# YARD::Parser::Ruby::AstNode#token?
# YARD::Parser::Ruby::AstNode#ref?
# YARD::Parser::Ruby::AstNode#literal?
# YARD::Parser::Ruby::AstNode#kw?
# YARD::Parser::Ruby::AstNode#call?
# YARD::Parser::Ruby::AstNode#condition?
#: ../lib/yard/parser/ruby/ast_node.rb:217
#: ../lib/yard/parser/ruby/ast_node.rb:223
#: ../lib/yard/parser/ruby/ast_node.rb:228
#: ../lib/yard/parser/ruby/ast_node.rb:233
#: ../lib/yard/parser/ruby/ast_node.rb:238
#: ../lib/yard/parser/ruby/ast_node.rb:243
#: ../lib/yard/parser/ruby/ast_node.rb:248
#: ../lib/yard/parser/ruby/ast_node.rb:253
#: ../lib/yard/parser/ruby/ast_node.rb:258
msgid "Node Meta Types"
msgstr ""

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:217
msgid "whether the node is a token"
msgstr "ノードがトークンかどうか"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:223
msgid ""
"whether the node is a reference (variable,\n"
"constant name)"
msgstr "ノードが参照するかどうか(変数,定数名)"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:228
msgid "whether the node is a literal value"
msgstr "ノードがリテラル値かどうか"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:233
msgid "whether the node is a keyword"
msgstr "ノードがキーワードかどうか"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:238
msgid "whether the node is a method call"
msgstr "ノードがメソッド呼び出しかどうか"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:243
msgid "whether the node is a method definition"
msgstr "ノードがメソッド定義かどうか"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:248
msgid "whether the node is a if/elsif/else condition"
msgstr "ノードがifやelsifやelseの条件かどうか"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:253
msgid "whether the node is a loop"
msgstr "ノードがループかどうか"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:258
msgid "whether the node has a block"
msgstr "ノードがblockかどうか"

# YARD::Parser::Ruby::AstNode#has_line?
# YARD::Parser::Ruby::AstNode#line
# YARD::Parser::Ruby::AstNode#first_line
#: ../lib/yard/parser/ruby/ast_node.rb:265
#: ../lib/yard/parser/ruby/ast_node.rb:270
#: ../lib/yard/parser/ruby/ast_node.rb:275
msgid "Getting Line Information"
msgstr "行の情報を取得する。"

# @return [Boolean]
#: ../lib/yard/parser/ruby/ast_node.rb:265
msgid "whether the node has a {#line_range} set"
msgstr "ノードが{#line_range}設定を持っているかどうか"

# @return [Fixnum]
#: ../lib/yard/parser/ruby/ast_node.rb:270
msgid "the starting line number of the node"
msgstr "ノードの文字列の行数"

# @return [String]
#: ../lib/yard/parser/ruby/ast_node.rb:275
msgid "the first line of source represented by the node."
msgstr "ノードによって表されるソースの最初の行"

# YARD::Parser::Ruby::AstNode#show
# YARD::Parser::Ruby::AstNode#pretty_print
# YARD::Parser::Ruby::AstNode#inspect
#: ../lib/yard/parser/ruby/ast_node.rb:282
#: ../lib/yard/parser/ruby/ast_node.rb:287
#: ../lib/yard/parser/ruby/ast_node.rb:322
msgid "Printing a Node"
msgstr "ノードをプリントする。"

# @return [String]
#: ../lib/yard/parser/ruby/ast_node.rb:282
msgid "the first line of source the node represents"
msgstr "ノードを表すソースの最初の行"

# @return [nil]
#: ../lib/yard/parser/ruby/ast_node.rb:287
msgid "pretty prints the node"
msgstr "ノードの出力"

# @return [String]
#: ../lib/yard/parser/ruby/ast_node.rb:322
msgid "inspects the object"
msgstr "解析するオブジェクト"

# YARD::Templates::Helpers::BaseHelper#globals
#: ../lib/yard/parser/ruby/ast_node.rb:330
#: ../lib/yard/parser/ruby/ast_node.rb:340
#: ../lib/yard/parser/ruby/ast_node.rb:358
#: ../lib/yard/parser/ruby/ast_node.rb:359
#: ../lib/yard/parser/ruby/ast_node.rb:361
#: ../lib/yard/parser/ruby/ast_node.rb:365
#: ../lib/yard/parser/ruby/ast_node.rb:370
#: ../lib/yard/parser/ruby/ast_node.rb:371
#: ../lib/yard/parser/ruby/ast_node.rb:374
#: ../lib/yard/parser/ruby/ast_node.rb:375
#: ../lib/yard/parser/ruby/ast_node.rb:378
#: ../lib/yard/parser/ruby/ast_node.rb:379
#: ../lib/yard/parser/ruby/ast_node.rb:380
#: ../lib/yard/parser/ruby/ast_node.rb:381
#: ../lib/yard/parser/ruby/ast_node.rb:382
#: ../lib/yard/parser/ruby/ast_node.rb:383
#: ../lib/yard/parser/ruby/ast_node.rb:386
#: ../lib/yard/parser/ruby/ast_node.rb:387
#: ../lib/yard/parser/ruby/ast_node.rb:388
#: ../lib/yard/parser/ruby/ast_node.rb:390
#: ../lib/yard/parser/ruby/ast_node.rb:395
#: ../lib/yard/parser/ruby/ast_node.rb:404
#: ../lib/yard/parser/ruby/ast_node.rb:405
#: ../lib/yard/parser/ruby/ast_node.rb:411
#: ../lib/yard/parser/ruby/ast_node.rb:415
#: ../lib/yard/parser/ruby/ast_node.rb:420
#: ../lib/yard/parser/ruby/ast_node.rb:421
#: ../lib/yard/parser/ruby/ast_node.rb:422
#: ../lib/yard/parser/ruby/ast_node.rb:423
#: ../lib/yard/parser/ruby/ast_node.rb:425
#: ../lib/yard/parser/ruby/ast_node.rb:430
#: ../lib/yard/parser/ruby/ast_node.rb:436
#: ../lib/yard/parser/ruby/ast_node.rb:440
#: ../lib/yard/parser/ruby/ast_node.rb:445
#: ../lib/yard/parser/ruby/ast_node.rb:446
#: ../lib/yard/parser/ruby/ast_node.rb:447
#: ../lib/yard/parser/ruby/ast_node.rb:448
#: ../lib/yard/parser/ruby/ast_node.rb:450
#: ../lib/yard/parser/ruby/ast_node.rb:458
#: ../lib/yard/parser/ruby/ast_node.rb:461
#: ../lib/yard/parser/ruby/ast_node.rb:462
#: ../lib/yard/parser/ruby/ast_node.rb:463
#: ../lib/yard/parser/ruby/ast_node.rb:464
#: ../lib/yard/parser/ruby/ast_node.rb:467
#: ../lib/yard/parser/ruby/ast_node.rb:468
#: ../lib/yard/parser/ruby/ast_node.rb:469
#: ../lib/yard/parser/ruby/ast_node.rb:472
#: ../lib/yard/parser/ruby/ast_node.rb:473
#: ../lib/yard/parser/ruby/ast_node.rb:474
#: ../lib/yard/parser/ruby/ast_node.rb:475
#: ../lib/yard/parser/ruby/ast_node.rb:479
#: ../lib/yard/parser/ruby/ast_node.rb:480
#: ../lib/yard/parser/ruby/ast_node.rb:481
#: ../lib/yard/parser/ruby/ast_node.rb:482
#: ../lib/yard/parser/ruby/ast_node.rb:484
#: ../lib/yard/parser/ruby/ast_node.rb:485
msgid "Managing node state"
msgstr "ノードの状態の管理"

# YARD::Parser::Ruby::Legacy::RubyToken::TkStatementEnd
#: ../lib/yard/parser/ruby/ast_node.rb:330
msgid "Resets node state in tree"
msgstr "ツリーの中でノードの状態をリセットする"

# YARD::Parser::Ruby::AstNode#reset_line_info
#: ../lib/yard/parser/ruby/ast_node.rb:339
msgid "Resets line information"
msgstr "行情報をリセットする。"

# YARD::CodeObjects::MethodObject
#: ../lib/yard/parser/ruby/ast_node.rb:479
msgid "Represents a lone comment block in source"
msgstr "ソースの中の単一のコメントブロックを表す"

# YARD::Parser::Ruby::Legacy::RubyToken
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:7
msgid "Legacy lexical tokenizer module."
msgstr ""

# YARD::Parser::Ruby::Legacy::RubyToken::Token
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:17
msgid "Represents a token in the Ruby lexer"
msgstr "Ruby lexerの中のトークンを表す"

# @return [Integer]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:20
msgid ""
"the line number in the file/stream the token is\n"
"located."
msgstr "トークンが位置する,ファイルやストリームの中の行の数"

# @return [Integer]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:24
msgid ""
"the character number in the file/stream the token\n"
"is located."
msgstr "トークンが位置する,ファイルやストリームの中のcharacterの数"

# @return [String]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:27
msgid "the token text value"
msgstr "トークンのテキストの値"

# @return [Symbol]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:30
msgid "the lexical state at the token"
msgstr "トークンにおける単語の状態"

# YARD::Parser::Ruby::Legacy::RubyToken::Token#initialize
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:36
msgid "Creates a new Token object"
msgstr "新しいトークンオブジェクトを作成する"

# @return [Token]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:38
msgid "a new instance of Token"
msgstr "トークンの新しいインスタンス"

# @param [Integer]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:38
msgid "tag|param|char_no"
msgstr ""

# @param [Integer]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:38
msgid "tag|param|line_no"
msgstr ""

# @param [Integer] char_no
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:38
msgid "the char number to initialize the token to"
msgstr "char numberをトークンにイニシャライズする, char number"

# @param [Integer] line_no
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:38
msgid "the line number to initialize the token to"
msgstr "行数をトークンにイニシャライズする。行数"

# YARD::Parser::Ruby::Legacy::RubyToken::Token#set_text
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:45
msgid "Chainable way to sets the text attribute"
msgstr "テキスト属性を設定する為の方法を紐付ける。"

# @param [String] text
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:48
msgid "the new text"
msgstr "新しいテキスト"

# @return [Token]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:48
msgid "this token object"
msgstr "このトークンオブジェクト"

# YARD::Parser::Ruby::Legacy::RubyToken::TkBlockContents
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:55
msgid "Represents a block"
msgstr "ブロックを表す"

# YARD::Parser::Ruby::Legacy::RubyToken::TkStatementEnd
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:60
msgid "Represents an end statement"
msgstr "ステートメントの終りを表す。"

# YARD::Parser::Ruby::Legacy::RubyToken::TkNode#node
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:66
msgid "Returns the value of attribute node"
msgstr "node属性の値を返す。"

# YARD::Parser::Ruby::Legacy::RubyToken::TkWhitespace
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:69
msgid "Represents whitespace"
msgstr "空白を表す"

# YARD::Parser::Ruby::Legacy::RubyToken::TkId
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:73
msgid "Represents a Ruby identifier"
msgstr "RubyのIDを表す。"

# @return [TkId]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:74
msgid "a new instance of TkId"
msgstr "TkIdの新しいインスタンス"

# YARD::Parser::Ruby::Legacy::RubyToken::TkKW
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:82
msgid "Represents a Ruby keyword"
msgstr "Rubyキーワードを表す。"

# YARD::Parser::Ruby::Legacy::RubyToken::TkVal
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:86
msgid "Represents a Ruby value"
msgstr "Rubyの値を表す。"

# @return [TkVal]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:87
msgid "a new instance of TkVal"
msgstr "TkValの新しいインスタンス"

# @return [TkOPASGN]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:100
msgid "a new instance of TkOPASGN"
msgstr "TkOPASGNの新しいインスタンス"

# YARD::Parser::Ruby::Legacy::RubyToken::TkOPASGN#op
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:106
msgid "Returns the value of attribute op"
msgstr "op属性の値を返す。"

# @return [TkUnknownChar]
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:109
msgid "a new instance of TkUnknownChar"
msgstr "TkUnknownCharの新しいインスタンス"

# YARD::Parser::Ruby::Legacy::RubyToken::TkReading2Token
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:284
msgid ""
"{ reading => token_class }\n"
"{ reading => [token_class, *opt] }"
msgstr ""

# YARD::Parser::Ruby::Legacy::RubyLex
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:330
msgid "Lexical analyzer for Ruby source"
msgstr "Rubyソース用の単語解析"

# YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:333
msgid ""
"Read an input stream character by character. We allow for unlimited\n"
"ungetting of characters just read."
msgstr ""
"character毎にストリームの入力を読み込む。\n"
"そこで読まれたcharacterの書き戻しを無制限に許可する。"

# YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:336
msgid ""
"We simplify the implementation greatly by reading the entire input\n"
"into a buffer initially, and then simply traversing it using\n"
"pointers."
msgstr ""
"最初にバッファの中へ全ての入力を読み込む事によって\n"
"実装する事を非常に簡潔にする。\n"
"そして、それはポインターを利用する事によって簡単に辿ることができる。"

# YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:340
msgid ""
"We also have to allow for the here document diversion. This\n"
"little gem comes about when the lexer encounters a here\n"
"document. At this point we effectively need to split the input\n"
"stream into two parts: one to read the body of the here document,\n"
"the other to read the rest of the input line where the here\n"
"document was initially encountered. For example, we might have"
msgstr ""
"私達は 複数のヒアドキュメント も考慮しなければならない。\n"
"この複数のヒアドキュメントは、字句解析器がヒアドキュメントに出会う時に起こ"
"る。\n"
"この時点で私達は、事実上2つの部分に入力ストリームを分割する必要がある。\n"
"一つはヒアドキュメントの本体を読み込む部分、\n"
"もう一つは、それ以外の\n"
"ヒアドキュメントが最初に出会った所から、\n"
"入力行の残りを読み込む為の部分。\n"
"例えば、"

# YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:347
msgid ""
"  do_something(<<-A, <<-B)\n"
"    stuff\n"
"    for\n"
"  A\n"
"    stuff\n"
"    for\n"
"  B"
msgstr ""

# YARD::Parser::Ruby::Legacy::RubyLex::BufferedReader
#: ../lib/yard/parser/ruby/legacy/ruby_lex.rb:355
msgid ""
"When the lexer encounters the <]
#: ../lib/yard/parser/ruby/legacy/statement.rb:49
msgid "the first to last lines of Ruby source"
msgstr "Rubyのソースの入った,最初から最後までの行"

# @param value
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:6
msgid "the value to set the attribute encoding_line to."
msgstr "encoding_line属性を設定する,値"

# @param value
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:6
msgid "the value to set the attribute shebang_line to."
msgstr "shebang_line属性を設定する,値"

# YARD::Parser::Ruby::Legacy::StatementList#encoding_line
# YARD::Parser::Ruby::RipperParser#encoding_line
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:7
#: ../lib/yard/parser/ruby/ruby_parser.rb:27
msgid "Returns the value of attribute encoding_line"
msgstr "encoding_line属性を返す。"

# YARD::Parser::Ruby::Legacy::StatementList#shebang_line
# YARD::Parser::Ruby::RipperParser#shebang_line
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:7
#: ../lib/yard/parser/ruby/ruby_parser.rb:27
msgid "Returns the value of attribute shebang_line"
msgstr "shebang_line属性の値を返す。"

# YARD::Parser::Ruby::Legacy::StatementList#encoding_line=
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:7
msgid "Sets the attribute encoding_line"
msgstr "encoding_line属性を設定する。"

# YARD::Parser::Ruby::Legacy::StatementList#shebang_line=
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:7
msgid "Sets the attribute shebang_line"
msgstr "shebang_line属性を設定する。"

# YARD::Parser::Ruby::Legacy::StatementList::OPEN_BLOCK_TOKENS
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:9
msgid ""
"The following list of tokens will require a block to be opened\n"
"if used at the beginning of a statement."
msgstr ""
"続くトークンのリストは、\n"
"ステートメントの最初で使う場合、ブロックを必要とする。"

# YARD::Parser::Ruby::Legacy::StatementList#initialize
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:14
msgid "Creates a new statement list"
msgstr "新しいステートメントのリストを作成する。"

# @return [StatementList]
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:16
msgid "a new instance of StatementList"
msgstr "StatementListの新しいインスタンス"

# @param [TokenList, String] content
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:16
msgid "the tokens to create the list from"
msgstr "トークンのリストを作成する,トークン"

# YARD::Parser::Ruby::Legacy::StatementList#next_statement
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:37
msgid "Returns the next statement in the token stream"
msgstr "処理するトークンの中の次の文を返す。"

# @return [Statement]
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:39
msgid "the next statement"
msgstr "次のステートメント"

# YARD::Parser::Ruby::Legacy::StatementList#process_token
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:117
msgid "Processes a single token"
msgstr "単一のトークンを処理する。"

# @param [RubyToken::Token]
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:119
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:183
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:202
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:257
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:282
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:294
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:349
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:367
msgid "tag|param|tk"
msgstr ""

# @param [RubyToken::Token] tk
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:119
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:183
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:202
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:257
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:282
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:294
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:349
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:367
msgid "the token to process"
msgstr "処理の為のトークン"

# YARD::Parser::Ruby::Legacy::StatementList#process_block_token
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:181
msgid "Processes a token in a block"
msgstr "ブロックの中のトークンを処理する。"

# YARD::Parser::Ruby::Legacy::StatementList#process_initial_comment
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:199
msgid "Processes a comment token that comes before a statement"
msgstr "statement処理の前にトークンのコメントを処理する。"

# @return [Boolean]
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:202
msgid "whether or not +tk+ was processed as an initial comment"
msgstr ""
"+tk+ がこの#process_initial_commentメソッドが正常に処理されたかどうか。"

# YARD::Parser::Ruby::Legacy::StatementList#process_simple_block_opener
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:253
msgid ""
"Processes a simple block-opening token;\n"
"that is, a block opener such as +begin+ or +do+\n"
"that isn't followed by an expression"
msgstr ""
"後に式がない +begin+ や +do+ 等のような単純なトークンの\n"
"blockを開く処理をする。"

# YARD::Parser::Ruby::Legacy::StatementList#process_complex_block_opener
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:278
msgid ""
"Processes a complex block-opening token;\n"
"that is, a block opener such as +while+ or +for+\n"
"that is followed by an expression"
msgstr ""
"後に式が来る +while+ や +for+ 等のようなトークンの\n"
"複雑なblockを開く処理をする。"

# YARD::Parser::Ruby::Legacy::StatementList#process_statement_end
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:292
msgid "Processes a token that closes a statement"
msgstr "ステートメントを閉じるトークンを処理する。"

# YARD::Parser::Ruby::Legacy::StatementList#balances?
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:345
msgid "Handles the balancing of parentheses and blocks"
msgstr "丸括弧とブロックの両立の為の処理する。"

# @return [Boolean]
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:349
msgid ""
"whether or not the current statement's parentheses and blocks\n"
"are balanced after +tk+"
msgstr "現在のステートメントの丸括弧とブロックが +tk+ の後で両立するかどうか。"

# YARD::Parser::Ruby::Legacy::StatementList#push_token
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:364
msgid ""
"Adds a token to the current statement,\n"
"unless it's a newline, semicolon, or comment"
msgstr ""
"現在のステートメントの為にトークンを追加する。\n"
"ただし改行や、セミコロンや、コメントの場合を除く。"

# YARD::Parser::Ruby::Legacy::StatementList#peek_no_space
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:373
msgid "Returns the next token in the stream that's not a space"
msgstr "スペースの無いストリームの中の次のトークンを返す。"

# @return [RubyToken::Token]
#: ../lib/yard/parser/ruby/legacy/statement_list.rb:375
msgid "the next non-space token"
msgstr "スペースの無い次のトークン"

# @return [TokenList]
#: ../lib/yard/parser/ruby/legacy/token_list.rb:6
msgid "a new instance of TokenList"
msgstr "TokenListの新しいインスタンス"

# @param [TokenList, Token, String] tokens
#: ../lib/yard/parser/ruby/legacy/token_list.rb:25
msgid ""
"A list of tokens. If the token is a string, it\n"
"is parsed with {RubyLex}."
msgstr "トークンのリスト。トークンが文字列の場合、{RubyLex}と共に解析される。"

# @param [TokenList, Token, String]
#: ../lib/yard/parser/ruby/legacy/token_list.rb:25
msgid "tag|param|tokens"
msgstr ""

# YARD::Parser::Ruby::RubyParser
#: ../lib/yard/parser/ruby/ruby_parser.rb:7
#: ../lib/yard/parser/ruby/ruby_parser.rb:11
#: ../lib/yard/parser/ruby/ruby_parser.rb:18
#: ../lib/yard/parser/ruby/ruby_parser.rb:19
#: ../lib/yard/parser/ruby/ruby_parser.rb:20
msgid "Ruby 1.9 parser"
msgstr ""

# YARD::Parser::Ruby::RipperParser#ast
# YARD::Parser::Ruby::RipperParser#root
#: ../lib/yard/parser/ruby/ruby_parser.rb:26
#: ../lib/yard/parser/ruby/ruby_parser.rb:28
msgid "Returns the value of attribute ast"
msgstr "ast属性の値を返す。"

# YARD::Parser::Ruby::RipperParser#charno
#: ../lib/yard/parser/ruby/ruby_parser.rb:26
msgid "Returns the value of attribute charno"
msgstr "charno属性の値を返す。"

# @return [RipperParser]
#: ../lib/yard/parser/ruby/ruby_parser.rb:29
msgid "a new instance of RipperParser"
msgstr "RipperParserの新しいインスタンス"

# YARD::Parser::UndocumentableError
#: ../lib/yard/parser/source_parser.rb:7
msgid ""
"Raised when an object is recognized but cannot be documented. This\n"
"generally occurs when the Ruby syntax used to declare an object is\n"
"too dynamic in nature."
msgstr ""
"オブジェクトが認識される時に例外を上げる。\n"
"しかし、記述される事はない。\n"
"これは通常オブジェクトを宣言する為に\n"
"使われたRuby構文が動的すぎる時に起る。"

# YARD::Parser::ParserSyntaxError
#: ../lib/yard/parser/source_parser.rb:12
msgid "Raised when the parser sees a Ruby syntax error"
msgstr "パーサーがRubyの構文のエラーを発見した時、例外を上げる。"

# YARD::Parser::OrderedParser
#: ../lib/yard/parser/source_parser.rb:15
msgid ""
"Responsible for parsing a list of files in order. The\n"
"{#parse} method of this class can be called from the\n"
"{SourceParser#globals} globals state list to re-enter\n"
"parsing for the remainder of files in the list recursively."
msgstr ""

# @see
#: ../lib/yard/parser/source_parser.rb:20
#: ../lib/yard/parser/source_parser.rb:41
msgid "tag|see|Processor#parse_remaining_files"
msgstr ""

# @param [Array] files
#: ../lib/yard/parser/source_parser.rb:22
msgid "the list of remaining files to parse"
msgstr "解析のための残りのファイルのリスト"

# YARD::Parser::OrderedParser#initialize
#: ../lib/yard/parser/source_parser.rb:25
msgid ""
"Creates a new OrderedParser with the global state and a list\n"
"of files to parse."
msgstr ""

# @note
#: ../lib/yard/parser/source_parser.rb:32
msgid ""
"OrderedParser sets itself as the +ordered_parser+ key on\n"
"global_state for later use in {Handlers::Processor}."
msgstr ""

# @return [CParser]
#: ../lib/yard/parser/source_parser.rb:32
msgid "a new instance of OrderedParser"
msgstr "OrderedParserの新しいインスタンス"

# @return [Processor]
#: ../lib/yard/parser/source_parser.rb:32
msgid ""
"a structure containing all global\n"
"state during parsing"
msgstr "解析中の全ての全体の状態を含んでいる構造体"

# @yieldparam [OpenStruct]
#: ../lib/yard/parser/source_parser.rb:32
msgid "tag|param|global_state"
msgstr ""

# YARD::Handlers::Ruby::Legacy::ClassConditionHandler#parse_condition
# YARD::Handlers::Ruby::ClassConditionHandler#parse_condition
#: ../lib/yard/parser/source_parser.rb:39
msgid "Parses the remainder of the {#files} list."
msgstr "{#files} のリストの残りを解析する"

# YARD::Parser::SourceParser
#: ../lib/yard/parser/source_parser.rb:51
msgid ""
"Responsible for parsing a source file into the namespace. Parsing\n"
"also invokes handlers to process the parsed statements and generate\n"
"any code objects that may be recognized."
msgstr ""
"namespaceの中のソースファイルを解析する為の責任がある。\n"
"そして解析する事は、解析されるステートメントや\n"
"認識されるかもしれないコードオブジェクトを生成する\n"
"処理の為にハンドラーも起動する。"

# YARD::Parser::SourceParser
#: ../lib/yard/parser/source_parser.rb:55
msgid ""
"== Custom Parsers\n"
"SourceParser allows custom parsers to be registered and called when\n"
"a certain filetype is recognized. To register a parser and hook it\n"
"up to a set of file extensions, call {register_parser_type}"
msgstr ""
"== カスタムパーサー\n"
"ソースパーサーによってカスタムパーサーは\n"
"明確にファイルタイプが認識される時に\n"
"記録され呼び出される。\n"
"パーサーを記録しファイル拡張子の設定をつなぐには、\n"
"{register_parser_type}を呼び出す。"

# @see
#: ../lib/yard/parser/source_parser.rb:62
msgid "tag|see|register_parser_type"
msgstr ""

# YARD::Parser::SourceParser::ENCODING_BYTE_ORDER_MARKS
#: ../lib/yard/parser/source_parser.rb:67
msgid "Byte order marks for various encodings"
msgstr "様々なエンコーディング用のバイトオーダーマーク"

# @return [Symbol]
#: ../lib/yard/parser/source_parser.rb:79
msgid "the default parser type (defaults to :ruby)"
msgstr "デフォルトのパーサータイプ(デフォルト :ruby)"

# YARD::Parser::SourceParser.parse
#: ../lib/yard/parser/source_parser.rb:86
msgid "Parses a path or set of paths"
msgstr "パスやパスの設定を解析する。"

# @param [Array] excluded
#: ../lib/yard/parser/source_parser.rb:93
msgid "a list of excluded path matchers"
msgstr "パスの照合を除外されるリスト。"

# @param [String, Array] paths
#: ../lib/yard/parser/source_parser.rb:93
msgid ""
"a path, glob, or list of paths to\n"
"parse"
msgstr "パス,glob,解析の為のパスのリスト"

# @param [Array]
#: ../lib/yard/parser/source_parser.rb:93
msgid "tag|param|excluded"
msgstr "excluded"

# @param [Fixnum]
#: ../lib/yard/parser/source_parser.rb:93
msgid "tag|param|level"
msgstr "level"

# @param [Array]
# @param [String, Array]
#: ../lib/yard/parser/source_parser.rb:93 ../lib/yard/server/router.rb:122
msgid "tag|param|paths"
msgstr "paths"

# @param [Fixnum] level
#: ../lib/yard/parser/source_parser.rb:93
msgid ""
"the logger level to use during parsing. See\n"
"{YARD::Logger}"
msgstr ""
"解析される間、使用する為のloggerレベル。\n"
"{YARD::Logger}参照。"

# YARD::Parser::SourceParser.parse_string
#: ../lib/yard/parser/source_parser.rb:112
msgid "Parses a string +content+"
msgstr ""
"+content+ の文字列を解析する。\n"
"Parses a string +content+"

# @param [Symbol]
#: ../lib/yard/parser/source_parser.rb:116
#: ../lib/yard/parser/source_parser.rb:125
msgid "tag|param|ptype"
msgstr "ptype"

# @param [String] content
#: ../lib/yard/parser/source_parser.rb:116
msgid "the block of code to parse"
msgstr "解析する為のコードの入ったブロック。"

# @return
#: ../lib/yard/parser/source_parser.rb:116
msgid "the parser object that was used to parse +content+"
msgstr "+content+ を解析する為に利用されるパーサーオブジェクト。"

# @param [Symbol] ptype
#: ../lib/yard/parser/source_parser.rb:116
#: ../lib/yard/parser/source_parser.rb:125
msgid "the parser type to use. See {parser_type}."
msgstr "利用するパーサーの型。{parser_type}参照。"

# YARD::Parser::SourceParser.tokenize
#: ../lib/yard/parser/source_parser.rb:121
msgid "Tokenizes but does not parse the block of code"
msgstr "トークナイズする。しかしコードの入ったブロックは解析しない。"

# @return [Array]
#: ../lib/yard/parser/source_parser.rb:125
#: ../lib/yard/parser/source_parser.rb:460
msgid "a list of tokens"
msgstr "トークンの入ったリスト。"

# @param [String] content
#: ../lib/yard/parser/source_parser.rb:125
#: ../lib/yard/parser/source_parser.rb:460
msgid "the block of code to tokenize"
msgstr "トークナイズする為のコードの入ったブロック。"

# YARD::Parser::SourceParser.register_parser_type
#: ../lib/yard/parser/source_parser.rb:130
msgid "Registers a new parser type."
msgstr "新しいパーサーの型を記録する。"

# @example Registering a parser for "java" files
#: ../lib/yard/parser/source_parser.rb:139
msgid "SourceParser.register_parser_type :java, JavaParser, 'java'"
msgstr ""

# @param [Base] parser_klass
#: ../lib/yard/parser/source_parser.rb:139
msgid "a class that implements parsing and tokenization"
msgstr "解析やトークナイズを実装するクラス。"

# @param [Array, String, Regexp] extensions
#: ../lib/yard/parser/source_parser.rb:139
msgid ""
"a list of extensions or a\n"
"regex to match against the file extension"
msgstr "拡張子のリストやファイル拡張子に対しマッチする正規表現。"

# @param [Symbol] type
#: ../lib/yard/parser/source_parser.rb:139
msgid "a symbolic name for the parser type"
msgstr "パーサー型用のシンボリック名。"

# @example
#: ../lib/yard/parser/source_parser.rb:139
msgid "tag|example|Registering a parser for \"java\" files"
msgstr "\"java\"ファイル用にパーサーを記録する"

# @param [Array, String, Regexp]
#: ../lib/yard/parser/source_parser.rb:139
msgid "tag|param|extensions"
msgstr "extensions"

# @param [Base]
#: ../lib/yard/parser/source_parser.rb:139
msgid "tag|param|parser_klass"
msgstr "parser_klass"

# @see
#: ../lib/yard/parser/source_parser.rb:139
msgid "tag|see|Parser::Base"
msgstr ""

# @return [Hash{Symbol=>Object}]
#: ../lib/yard/parser/source_parser.rb:150
#: ../lib/yard/parser/source_parser.rb:152
msgid "a list of registered parser types"
msgstr "パーサーの型が記録されるリスト。"

# YARD::Parser::SourceParser.parser_type_for_extension
#: ../lib/yard/parser/source_parser.rb:164
msgid ""
"Finds a parser type that is registered for the extension. If no\n"
"type is found, the default Ruby type is returned."
msgstr ""
"拡張用の記録されるパーサーの型を見つける。\n"
"型が見つからない無い場合、デフォルトのRuby型が返される。"

# @return [Symbol]
#: ../lib/yard/parser/source_parser.rb:168
msgid "the parser type to be used for the extension"
msgstr "拡張用に利用されるパーサーの型。"

# YARD::Parser::SourceParser.validated_parser_type
#: ../lib/yard/parser/source_parser.rb:176
msgid ""
"Returns the validated parser type. Basically, enforces that :ruby\n"
"type is never set if the Ripper library is not available"
msgstr ""
"有効なパーサー型を返す。\n"
"基本的に、Ripperライブラリが利用不可の場合、\n"
":ruby型が設定されないよう実行される。"

# @param [Symbol] type
#: ../lib/yard/parser/source_parser.rb:181
msgid "the parser type to set"
msgstr "設定するパーサーの型。"

# @return [Symbol]
#: ../lib/yard/parser/source_parser.rb:181
msgid "the validated parser type"
msgstr "有効なパーサーの型。"

# YARD::Parser::SourceParser.before_parse_list
#: ../lib/yard/parser/source_parser.rb:188
msgid ""
"Registers a callback to be called before a list of files is parsed\n"
"via {parse}. The block passed to this method will be called on\n"
"subsequent parse calls."
msgstr ""
"{parse} 経由でファイルのリストが解析される前に呼び出されるコールバックを記録する\n"
"このメソッドに渡されるブロックはそれに続く、parse呼び出し上で呼び出される。"

# YARD::Parser::SourceParser.before_parse_list
# YARD::Parser::SourceParser.after_parse_list
# YARD::Parser::SourceParser.before_parse_file
# YARD::Parser::SourceParser.after_parse_file
# YARD::Parser::SourceParser.before_parse_list_callbacks
# YARD::Parser::SourceParser.after_parse_list_callbacks
# YARD::Parser::SourceParser.before_parse_file_callbacks
# YARD::Parser::SourceParser.after_parse_file_callbacks
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
#: ../lib/yard/parser/source_parser.rb:292
#: ../lib/yard/parser/source_parser.rb:321
#: ../lib/yard/parser/source_parser.rb:328
#: ../lib/yard/parser/source_parser.rb:335
#: ../lib/yard/parser/source_parser.rb:342
#: ../lib/yard/parser/source_parser.rb:349
#: ../lib/yard/parser/source_parser.rb:361
#: ../lib/yard/parser/source_parser.rb:384
#: ../lib/yard/parser/source_parser.rb:388
#: ../lib/yard/parser/source_parser.rb:393
#: ../lib/yard/parser/source_parser.rb:397
#: ../lib/yard/parser/source_parser.rb:404
#: ../lib/yard/parser/source_parser.rb:416
#: ../lib/yard/parser/source_parser.rb:460
#: ../lib/yard/parser/source_parser.rb:469
#: ../lib/yard/parser/source_parser.rb:490
#: ../lib/yard/parser/source_parser.rb:497
#: ../lib/yard/parser/source_parser.rb:505
#: ../lib/yard/parser/source_parser.rb:512
msgid "Parser Callbacks"
msgstr "パーサーのコールバック"

# @example Setting global state
#: ../lib/yard/parser/source_parser.rb:231
msgid ""
"SourceParser.before_parse_list do |files, globals|\n"
"  globals.method_count = 0\n"
"end\n"
"SourceParser.after_parse_list do |files, globals|\n"
"  puts \"Found #{globals.method_count} methods\"\n"
"end\n"
"class MyCountHandler < Handlers::Ruby::Base\n"
"  handles :def, :defs\n"
"  process { globals.method_count += 1 }\n"
"end\n"
"YARD.parse\n"
"# Prints: \"Found 37 methods\""
msgstr ""

# @example Installing a simple callback
#: ../lib/yard/parser/source_parser.rb:231
msgid ""
"SourceParser.before_parse_list do |files, globals|\n"
"  puts \"Starting to parse...\"\n"
"end\n"
"YARD.parse('lib/**/*.rb')\n"
"# prints \"Starting to parse...\""
msgstr ""

# @example Using a global callback to cancel parsing
#: ../lib/yard/parser/source_parser.rb:231
msgid ""
"SourceParser.before_parse_list do |files, globals|\n"
"  return false if files.include?('foo.rb')\n"
"end\n"
"\n"
"YARD.parse(['foo.rb', 'bar.rb']) # callback cancels this method\n"
"YARD.parse('bar.rb') # parses normally"
msgstr ""

# @yieldparam [OpenStruct] globals
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
msgid ""
"a global structure to store arbitrary\n"
"state for post processing (see {Handlers::Processor#globals})"
msgstr ""
"後処理用の任意の状態を格納する、globalなデータ(see {Handlers::"
"Processor#globals})"

# @yieldreturn [Boolean]
#: ../lib/yard/parser/source_parser.rb:231
msgid ""
"if the block returns +false+, parsing is\n"
"cancelled."
msgstr "ブロックが +false+ を返す場合、解析処理はキャンセルされる。"

# @example
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:292
msgid "tag|example|Installing a simple callback"
msgstr "簡単なコールバックを実装する"

# @example
#: ../lib/yard/parser/source_parser.rb:231
msgid "tag|example|Setting global state"
msgstr "globalの状態を設定する"

# @example
#: ../lib/yard/parser/source_parser.rb:231
msgid "tag|example|Using a global callback to cancel parsing"
msgstr "解析するのをキャンセルする為にコールバックにglobalを使う"

# @see
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:321
msgid "tag|see|after_parse_list"
msgstr ""

# @see
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
#: ../lib/yard/parser/source_parser.rb:321
msgid "tag|see|before_parse_file"
msgstr ""

# @yieldparam [Array]
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
msgid "tag|yieldparam|files"
msgstr "files"

# @yieldparam [OpenStruct]
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
msgid "tag|yieldparam|globals"
msgstr "globals"

# @yieldparam [Array] files
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
msgid "the list of files that will be parsed."
msgstr "解析されるファイルのリスト。"

# @return [Proc]
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
#: ../lib/yard/parser/source_parser.rb:292
#: ../lib/yard/parser/source_parser.rb:321
msgid "the yielded block"
msgstr "yieldされるブロック。"

# @yield [files, globals]
#: ../lib/yard/parser/source_parser.rb:231
#: ../lib/yard/parser/source_parser.rb:255
msgid ""
"the yielded block is called once before\n"
"parsing all files"
msgstr ""
"yieldされたブロックは\n"
"全てのファイルを解析する前に一度だけ呼び出される。"

# YARD::Parser::SourceParser.after_parse_list
#: ../lib/yard/parser/source_parser.rb:236
msgid ""
"Registers a callback to be called after a list of files is parsed\n"
"via {parse}. The block passed to this method will be called on\n"
"subsequent parse calls."
msgstr ""
"ファイルのリストが {parse} 経由で解析された後で呼び出される為にコールバックを記録する。\n"
"このメソッドの為に渡されるブロックはその後のparse呼び出し上で呼び出される。"

# @example Printing results after parsing occurs
#: ../lib/yard/parser/source_parser.rb:255
msgid ""
"SourceParser.after_parse_list do\n"
"  puts \"Finished parsing!\"\n"
"end\n"
"YARD.parse\n"
"# Prints \"Finished parsing!\" after parsing files"
msgstr ""

# @example
#: ../lib/yard/parser/source_parser.rb:255
msgid "tag|example|Printing results after parsing occurs"
msgstr "解析が終わった後で、結果をプリントする。"

# @see
#: ../lib/yard/parser/source_parser.rb:255
#: ../lib/yard/parser/source_parser.rb:292
msgid "tag|see|before_parse_list"
msgstr ""

# @yieldreturn [void]
#: ../lib/yard/parser/source_parser.rb:255
#: ../lib/yard/parser/source_parser.rb:321
msgid "the return value for the block is ignored."
msgstr "ブロックが無視される為の戻り値"

# YARD::Parser::SourceParser.before_parse_file
#: ../lib/yard/parser/source_parser.rb:260
msgid ""
"Registers a callback to be called before an individual file is parsed.\n"
"The block passed to this method will be called on subsequent parse\n"
"calls."
msgstr ""
"個々のファイルが解析される前に呼び出されるコールバックを記録する\n"
"blockはこのメソッドが続くparse呼び出しで呼び出されるために解析される。"

# YARD::Parser::SourceParser.before_parse_file
#: ../lib/yard/parser/source_parser.rb:264
msgid ""
"To register a callback that is called before the entire list of files\n"
"is processed, see {before_parse_list}."
msgstr ""
"全てのファイルのリストが処理される前に呼び出される\n"
"コールバックを記録する為には、{before_parse_list}参照。"

# @example Installing a simple callback
#: ../lib/yard/parser/source_parser.rb:292
msgid ""
"SourceParser.before_parse_file do |parser|\n"
"  puts \"I'm parsing #{parser.file}\"\n"
"end\n"
"YARD.parse('lib/**/*.rb')\n"
"# prints:\n"
"\"I'm parsing lib/foo.rb\"\n"
"\"I'm parsing lib/foo_bar.rb\"\n"
"\"I'm parsing lib/last_file.rb\""
msgstr ""

# @example Cancel parsing of any test_*.rb files
#: ../lib/yard/parser/source_parser.rb:292
msgid ""
"SourceParser.before_parse_file do |parser|\n"
"  return false if parser.file =~ /^test_.+\\.rb$/\n"
"end"
msgstr ""

# @yieldreturn [Boolean]
#: ../lib/yard/parser/source_parser.rb:292
msgid ""
"if the block returns +false+, parsing for\n"
"the file is cancelled."
msgstr ""
"ブロックが +false+ を返す場合、\n"
"ファイルがキャンセルされる為に解析する。"

# @example
#: ../lib/yard/parser/source_parser.rb:292
msgid "tag|example|Cancel parsing of any test_*.rb files"
msgstr "全てのtest_*.rbファイルの解析をキャンセルする"

# @see
#: ../lib/yard/parser/source_parser.rb:292
msgid "tag|see|after_parse_file"
msgstr ""

# @yieldparam [SourceParser] parser
#: ../lib/yard/parser/source_parser.rb:292
msgid ""
"the parser object that will {#parse}\n"
"the file."
msgstr "ファイルを{#parse}メソッドで解析するパーサーオブジェクト。"

# @yield [parser]
#: ../lib/yard/parser/source_parser.rb:292
msgid ""
"the yielded block is called once before each\n"
"file that is parsed. This might happen many times for a single\n"
"codebase."
msgstr ""
"yieldされるブロックは、それぞれのファイルが解析される前に一度呼び出される。\n"
"これは、単一のコードベースでは何回も起きる可能性がある。"

# YARD::Parser::SourceParser.after_parse_file
#: ../lib/yard/parser/source_parser.rb:297
msgid ""
"Registers a callback to be called after an individual file is parsed.\n"
"The block passed to this method will be called on subsequent parse\n"
"calls."
msgstr ""
"個々のファイルが解析された後で呼び出されるコールバックを登録する。\n"
"このメソッドに渡されたブロックは次のparseメソッドの呼び出しで呼び出される。"

# YARD::Parser::SourceParser.after_parse_file
#: ../lib/yard/parser/source_parser.rb:301
msgid ""
"To register a callback that is called after the entire list of files\n"
"is processed, see {after_parse_list}."
msgstr ""
"ファイルリストが全て処理された後で呼び出される。\n"
"コールバックを記録するには、{after_parse_list}参照。"

# @example Printing the length of each file after it is parsed
#: ../lib/yard/parser/source_parser.rb:321
msgid ""
"SourceParser.after_parse_file do |parser|\n"
"  puts \"#{parser.file} is #{parser.contents.size} characters\"\n"
"end\n"
"YARD.parse('lib/**/*.rb')\n"
"# prints:\n"
"\"lib/foo.rb is 1240 characters\"\n"
"\"lib/foo_bar.rb is 248 characters\""
msgstr ""

# @example
#: ../lib/yard/parser/source_parser.rb:321
msgid "tag|example|Printing the length of each file after it is parsed"
msgstr "tag|example|解析された後でそれぞれのファイルのサイズをプリントする"

# @yieldparam [SourceParser] parser
#: ../lib/yard/parser/source_parser.rb:321
msgid ""
"the parser object that parsed\n"
"the file."
msgstr "ファイルを解析した、パーサーオブジェクト。"

# @yield [parser]
#: ../lib/yard/parser/source_parser.rb:321
msgid ""
"the yielded block is called once after each file\n"
"that is parsed. This might happen many times for a single codebase."
msgstr ""
"yieldされたブロックは解析される個々のファイルの後で一度呼び出される。\n"
"これは単一のコードベースの為に何回も起る可能性がある。"

# @return [Array]
#: ../lib/yard/parser/source_parser.rb:328
msgid ""
"the list of callbacks to be called before\n"
"parsing a list of files. Should only be used for testing."
msgstr ""
"ファイルのリストを解析する前に呼び出されるコールバックのリスト。\n"
"検査用にだけ利用されるべきである。"

# @return [Array]
#: ../lib/yard/parser/source_parser.rb:335
msgid ""
"the list of callbacks to be called after\n"
"parsing a list of files. Should only be used for testing."
msgstr ""
"ファイルのリストを解析する前に呼び出される為のコールバックのリスト。\n"
"検査用にだけ利用されるべきである。"

# @return [Array]
#: ../lib/yard/parser/source_parser.rb:342
msgid ""
"the list of callbacks to be called before\n"
"parsing a file. Should only be used for testing."
msgstr ""
"ファイルが解析する前に呼び出される為のコールバックのリスト。\n"
"検査用にだけ利用されるべきである。"

# @return [Array]
#: ../lib/yard/parser/source_parser.rb:349
msgid ""
"the list of callbacks to be called after\n"
"parsing a file. Should only be used for testing."
msgstr ""
"ファイルが解析する前に呼び出される為のコールバックのリスト。\n"
"検査用にだけ利用されるべきである。"

# @param [Array] files
#: ../lib/yard/parser/source_parser.rb:358
msgid "Parses a list of files in a queue."
msgstr "キューのなかのファイルのリストを解析する"

# @param [Array] files
#: ../lib/yard/parser/source_parser.rb:361
msgid "a list of files to queue for parsing"
msgstr "解析用のキューの為のファイルのリスト。"

# @return [String]
#: ../lib/yard/parser/source_parser.rb:384
msgid "the filename being parsed by the parser."
msgstr "パーサーによって解析されているファイル名。"

# @return [Symbol]
#: ../lib/yard/parser/source_parser.rb:388
msgid ""
"the parser type associated with the parser instance.\n"
"This should be set by the {#initialize constructor}."
msgstr ""
"パーサーのインスタンスと共に関連付られるパーサーの型。\n"
"これは、{#initialize constructor}メソッドによって設定されるべきである。"

# @return [OpenStruct]
#: ../lib/yard/parser/source_parser.rb:393
msgid ""
"an open struct containing arbitrary global state\n"
"shared between files and handlers."
msgstr ""
"ファイルとハンドラーとの間で共有される\n"
"任意のグローバルな状態を含んでいるOpenStruct"

# @return [String]
#: ../lib/yard/parser/source_parser.rb:397
msgid "the contents of the file to be parsed"
msgstr "解析されるファイルの内容。"

# @return [SourceParser]
#: ../lib/yard/parser/source_parser.rb:404
msgid "a new instance of SourceParser"
msgstr "ソースパーサーの新しいインスタンス。"

# @overload
#: ../lib/yard/parser/source_parser.rb:404
msgid "tag|overload|initialize"
msgstr ""

# YARD::Parser::SourceParser#parse
#: ../lib/yard/parser/source_parser.rb:412
msgid ""
"The main parser method. This should not be called directly. Instead,\n"
"use the class methods {parse} and {parse_string}."
msgstr ""
"主なパーサーメソッド。これは直接呼ばれるべきではない。\n"
"代わりに、{parse}や{parse_string}クラスメソッドを利用する。"

# @return [Object, nil]
#: ../lib/yard/parser/source_parser.rb:416
msgid "the parser object used to parse the source"
msgstr "ソースを解析する為に利用されるパーサーオブジェクト。"

# @param [String, #read, Object] content
#: ../lib/yard/parser/source_parser.rb:416
msgid "the source file to parse"
msgstr "解析の為のソースファイル。"

# YARD::Parser::SourceParser#tokenize
#: ../lib/yard/parser/source_parser.rb:457
msgid ""
"Tokenizes but does not parse the block of code using the current "
"{#parser_type}"
msgstr ""
"トークナイズする。しかし、\n"
"現在の{#parser_type}メソッドを使用して、コードの入ったブロックは解析しない。"

# YARD::Parser::SourceParser#convert_encoding
#: ../lib/yard/parser/source_parser.rb:468
msgid "Searches for encoding line and forces encoding"
msgstr "エンコーディング行を検索し、エンコーディングを強制する。"

# YARD::Parser::SourceParser#post_process
#: ../lib/yard/parser/source_parser.rb:489
msgid ""
"Runs a {Handlers::Processor} object to post process the parsed statements."
msgstr "解析したステートメントの後処理の為に、{Handlers::Processor}オブジェクトを起動する。"

# YARD::Parser::SourceParser#parser_type_for_filename
#: ../lib/yard/parser/source_parser.rb:502
msgid "Guesses the parser type to use depending on the file extension."
msgstr "ファイル拡張子に応じて使用するパーサーの型を推測する。"

# @return [Symbol]
#: ../lib/yard/parser/source_parser.rb:505
msgid "a parser type that matches the filename"
msgstr "ファイル名の拡張子に応じたパーサータイプ。"

# @param [String] filename
#: ../lib/yard/parser/source_parser.rb:505
msgid "the filename to use to guess the parser type"
msgstr "パーサー型を推測する為に利用するファイル名。"

# YARD::Rake::YardocTask
#: ../lib/yard/rake/yardoc_task.rb:8
msgid "The rake task to run {CLI::Yardoc} and generate documentation."
msgstr "{CLI::Yardoc}を起動する為のrake taskとなり、ドキュメントを生成する。"

# YARD::Rake::YardocTask#name
# YARD::Rake::YardocTask#name=
#: ../lib/yard/rake/yardoc_task.rb:10
msgid "The name of the task"
msgstr "taskの名前"

# @return [String]
#: ../lib/yard/rake/yardoc_task.rb:11
msgid "the task name"
msgstr "task名"

# YARD::Rake::YardocTask#options
# YARD::Rake::YardocTask#options=
#: ../lib/yard/rake/yardoc_task.rb:14
msgid "Options to pass to {CLI::Yardoc}"
msgstr "{CLI::Yardoc}の為のパスの設定"

# @return [Hash]
#: ../lib/yard/rake/yardoc_task.rb:15
msgid "the options passed to the commandline utility"
msgstr "コマンドライン用途の為に渡される設定"

# YARD::Rake::YardocTask#files
# YARD::Rake::YardocTask#files=
#: ../lib/yard/rake/yardoc_task.rb:18
msgid ""
"The Ruby source files (and any extra documentation files separated by '-')\n"
"to process."
msgstr ""
"処理の為のRubyソースファイル(と'-'によって分割された、任意の特別なドキュメン"
"トファイル)"

# @example Task files assignment
#: ../lib/yard/rake/yardoc_task.rb:24
msgid ""
"YARD::Rake::YardocTask.new do |t|\n"
"  t.files   = ['app/**/*.rb', 'lib/**/*.rb', '-', 'doc/FAQ.md', 'doc/Changes."
"md']\n"
"end"
msgstr ""

# @example
#: ../lib/yard/rake/yardoc_task.rb:24
msgid "tag|example|Task files assignment"
msgstr "Taskのファイルを代入する"

# YARD::Rake::YardocTask#before
# YARD::Rake::YardocTask#before=
#: ../lib/yard/rake/yardoc_task.rb:27
msgid "Runs a +Proc+ before the task"
msgstr "taskの前に +Proc+ を起動する。"

# @return [Proc]
#: ../lib/yard/rake/yardoc_task.rb:28
msgid "a proc to call before running the task"
msgstr "task を起動する前に、呼び出される,proc"

# YARD::Rake::YardocTask#after
# YARD::Rake::YardocTask#after=
#: ../lib/yard/rake/yardoc_task.rb:31
msgid "Runs a +Proc+ after the task"
msgstr "taskの後で起動する +Proc+"

# @return [Proc]
#: ../lib/yard/rake/yardoc_task.rb:32
msgid "a proc to call after running the task"
msgstr "taskを起動した後で呼び出される,proc"

# @return [Verifier, Proc]
#: ../lib/yard/rake/yardoc_task.rb:38
msgid ""
"an optional {Verifier} to run against all objects\n"
"being generated. Any object that the verifier returns false for will be\n"
"excluded from documentation. This attribute can also be a lambda."
msgstr ""
"全てのオブジェクトに対して起動するための任意の {Verifier}(認証者)\n"
"verifierがドキュメントから除外される為のfalseを返す任意のオブジェクト\n"
"この属性はlmbdaにもできる。"

# YARD::Rake::YardocTask#initialize
#: ../lib/yard/rake/yardoc_task.rb:41
msgid "Creates a new task with name +name+."
msgstr "+name+ 名を用いる新しいタスクを作成する"

# @yield
#: ../lib/yard/rake/yardoc_task.rb:46
msgid "a block to allow any options to be modified on the task"
msgstr "task上で変更される為に任意のオプションを受け入れる,block"

# @return [YardocTask]
#: ../lib/yard/rake/yardoc_task.rb:46
msgid "a new instance of YardocTask"
msgstr "YardocTaskの新しいインスタンス"

# @yieldparam [YardocTask]
#: ../lib/yard/rake/yardoc_task.rb:46
msgid "tag|yieldparam|_self"
msgstr ""

# @param [String, Symbol] name
#: ../lib/yard/rake/yardoc_task.rb:46
msgid "the name of the rake task"
msgstr "rake taskの名前"

# @yieldparam [YardocTask] _self
#: ../lib/yard/rake/yardoc_task.rb:46
msgid ""
"the task object to allow any parameters\n"
"to be changed."
msgstr "変更される任意のパラメータを受け入れるtask オブジェクト"

# YARD::Rake::YardocTask#define
#: ../lib/yard/rake/yardoc_task.rb:61
msgid "Defines the rake task"
msgstr "rake taskを定義する。"

# YARD::Registry
#: ../lib/yard/registry.rb:6
msgid ""
"The +Registry+ is the centralized data store for all {CodeObjects} created\n"
"during parsing. The storage is a key value store with the object's path\n"
"(see {CodeObjects::Base#path}) as the key and the object itself as the "
"value.\n"
"Object paths must be unique to be stored in the Registry. All lookups for\n"
"objects are done on the singleton Registry instance using the {Registry.at}\n"
"or {Registry.resolve} methods."
msgstr ""
"+Registry+ は解析している間に、\n"
"全ての{CodeObjects}が作成される為の\n"
"集中データストアとなる。\n"
"ストレージは、\n"
"キーのようなオブジェクトパス(see {CodeObjects::Base#path})と\n"
"値のようなオブジェクトを用い、key valueストアとなる。\n"
"オブジェクトパスは、Registryの中で記録される為に固有でなければならない。\n"
"オブジェクト用の全ての検索は、\n"
"{Registry.at} や {Registry.resolve}メソッドによって\n"
"シングルトンレジストリインスタンスの上で行われる。\n"

# YARD::Registry
#: ../lib/yard/registry.rb:13
msgid ""
"== Saving / Loading a Registry\n"
"The registry is saved to a \"yardoc file\" (actually a directory), which "
"can\n"
"be loaded back to perform any lookups. See {Registry.load!} and\n"
"{Registry.save} for information on saving and loading of a yardoc file."
msgstr ""
"== レジストリーをセーブ/ロードする\n"
"レジストリーは\"yardoc file\"(実際はディレクトリ)にセーブされ、\n"
"任意の検索を実行する為に、ロードできる。\n"
"yardocファイルのセーブやロードの情報は、\n"
"{Registry.load!} , {Registry.save}を参照。"

# YARD::Registry
#: ../lib/yard/registry.rb:18
msgid ""
"== Threading Notes\n"
"The registry class is a singleton class that is accessed directly in many\n"
"places across YARD. To mitigate threading issues, YARD (0.6.5+) makes\n"
"the Registry thread local. This means all access to a registry for a "
"specific\n"
"object set must occur in the originating thread."
msgstr ""
"== スレッドの注意\n"
"レジストリークラスは、YARD全体で直接アクセスされるシングルトンクラスとなる。\n"
"スレッドの問題を緩和するには、YARD(0.6.5+)でthread localなレジストリーを作る。\n"
"これはスレッドの中で固有のオブジェクトのグループが生成される、\n"
"レジストリーにアクセスする全てのものを意味する。"

# @example Getting an object by a specific path
#: ../lib/yard/registry.rb:31
msgid "Registry.at('YARD::CodeObjects::Base#docstring')"
msgstr ""

# @example Loading a Registry
#: ../lib/yard/registry.rb:31
msgid ""
"Registry.load!('/path/to/yardocfile') # loads all objects into memory\n"
"Registry.at('YARD::CodeObjects::Base').docstring\n"
"# => \"+Base+ is the superclass of all code objects ...\""
msgstr ""

# @example Performing a lookup on a method anywhere in the inheritance tree
#: ../lib/yard/registry.rb:31
msgid "Registry.resolve(P('YARD::CodeObjects::Base'), '#docstring', true)"
msgstr ""

# @example
#: ../lib/yard/registry.rb:31
msgid "tag|example|Getting an object by a specific path"
msgstr "tag|example|パスによってオブジェクトを取得する"

# @example
#: ../lib/yard/registry.rb:31
msgid "tag|example|Loading the Registry"
msgstr "tag|example|レジストリーをロードする"

# @example
#: ../lib/yard/registry.rb:31
msgid ""
"tag|example|Performing a lookup on a method anywhere in the inheritance tree"
msgstr "tag|example|継承ツリーのどこでもメソッドで検索を実行する"

# YARD::Registry.yardoc_file_for_gem
#: ../lib/yard/registry.rb:41
msgid "Returns the .yardoc file associated with a gem."
msgstr "gemと共に関連した.yardocファイルを返す。"

# YARD::Registry.yardoc_file_for_gem
# YARD::Registry.yardoc_file
# YARD::Registry.yardoc_file=
#: ../lib/yard/registry.rb:51 ../lib/yard/registry.rb:73
#: ../lib/yard/registry.rb:75 ../lib/yard/registry.rb:76
msgid "Getting .yardoc File Locations"
msgstr ".yardocファイルの場所を取得する。"

# @param [String] ver_require
#: ../lib/yard/registry.rb:51
msgid "an optional Gem version requirement"
msgstr "任意のGemのバージョン要求"

# @return [String]
#: ../lib/yard/registry.rb:51
msgid ""
"if +for_writing+ is set to +true+, returns the best\n"
"location suitable to write the .yardoc file. Otherwise, the first\n"
"existing location associated with the gem's .yardoc file."
msgstr ""
"+for_writing+ にtrueをセットした場合、\n"
".yardocファイルを書き込む為に最適な場所を返す。\n"
"若しくは、.yardocファイルに関連づけられた\n"
"既存の場所になる。"

# @return [nil]
#: ../lib/yard/registry.rb:51
msgid ""
"if +for_writing+ is set to false and no yardoc file\n"
"is found, returns nil."
msgstr ""
"+for_writing+ がfalseを設定する場合と、\n"
"yardocファイルが見つからない場合は、nilを返す。"

# @param [Boolean]
#: ../lib/yard/registry.rb:51
msgid "tag|param|for_writing"
msgstr ""

# @param [String]
#: ../lib/yard/registry.rb:51
msgid "tag|param|gem"
msgstr ""

# @param [String]
#: ../lib/yard/registry.rb:51
msgid "tag|param|ver_require"
msgstr ""

# @param [String] gem
#: ../lib/yard/registry.rb:51
msgid "the name of the gem to search for"
msgstr "検索するgemの名前"

# @param [Boolean] for_writing
#: ../lib/yard/registry.rb:51
msgid ""
"whether or not the method should search\n"
"for writable locations"
msgstr "メソッドが書き込み可能な場所を検索するかどうか"

# YARD::Registry.yardoc_file
# YARD::Registry.yardoc_file=
#: ../lib/yard/registry.rb:71
msgid "Gets/sets the yardoc filename"
msgstr "yardocのファイル名を取得/設定する。"

# @see
#: ../lib/yard/registry.rb:73 ../lib/yard/registry.rb:75
#: ../lib/yard/registry.rb:76
msgid "tag|see|DEFAULT_YARDOC_FILE"
msgstr ""

# @return [String]
#: ../lib/yard/registry.rb:73 ../lib/yard/registry.rb:75
#: ../lib/yard/registry.rb:76
msgid "the yardoc filename"
msgstr "yardocのファイル名"

# YARD::Registry.load
#: ../lib/yard/registry.rb:83
msgid "Loads the registry and/or parses a list of files"
msgstr "レジストリのロードやファイルのリストを解析する"

# YARD::Registry.load
# YARD::Registry.load_yardoc
# YARD::Registry.load!
# YARD::Registry.load_all
#: ../lib/yard/registry.rb:97 ../lib/yard/registry.rb:118
#: ../lib/yard/registry.rb:132 ../lib/yard/registry.rb:147
msgid "Loading Data from Disk"
msgstr "ディスクから、データをロードする"

# @example Loads the yardoc file or parses files 'a', 'b' and 'c' (but not both)
#: ../lib/yard/registry.rb:97
msgid "Registry.load(['a', 'b', 'c'])"
msgstr ""

# @example Reparses files 'a' and 'b' regardless of whether yardoc file exists
#: ../lib/yard/registry.rb:97
msgid "Registry.load(['a', 'b'], true)"
msgstr ""

# @param [String, Array] files
#: ../lib/yard/registry.rb:97
msgid ""
"if +files+ is an Array, it should represent\n"
"a list of files that YARD should parse into the registry. If reload is\n"
"set to false and the yardoc file already exists, these files are skipped.\n"
"If files is a String, it should represent the yardoc file to load\n"
"into the registry."
msgstr ""
"+files+が配列の場合、YARDがレジストリーの中を解析するべきファイルのリストを表す。\n"
"reloadがfalseを設定された場合や、yardocファイルが既に存在する場合、\n"
"これらのファイルは、スキップされる。\n"
"ファイルがStringの場合、\n"
"レジストリーの中へロードするyardocファイルを表す。"

# @raise [ArgumentError]
#: ../lib/yard/registry.rb:97
msgid "if files is not a String or Array"
msgstr "ファイルがStringやArrayでない場合"

# @param [Boolean] reparse
#: ../lib/yard/registry.rb:97
msgid ""
"if reparse is false and a yardoc file already\n"
"exists, any files passed in will be ignored."
msgstr ""
"reparseがfalseの場合や、yardocファイルが既に存在する場合、\n"
"オプションの解析されるファイルは、無視される。"

# @example
#: ../lib/yard/registry.rb:97
msgid ""
"tag|example|Loads the yardoc file or parses files 'a', 'b' and 'c' (but not "
"both)"
msgstr ""
"yardocファイルをロードする。又は、'a','b','c'のファイルを解析する。(どちらか"
"だけ行う)"

# @example
#: ../lib/yard/registry.rb:97
msgid ""
"tag|example|Reparses files 'a' and 'b' regardless of whether yardoc file "
"exists"
msgstr ""
"yardocファイルが存在するかどうかにかかわらず、ファイル'a'と'b'を再解析する。"

# @param [Boolean]
#: ../lib/yard/registry.rb:97
msgid "tag|param|reparse"
msgstr ""

# @return [Registry]
#: ../lib/yard/registry.rb:97 ../lib/yard/registry.rb:118
#: ../lib/yard/registry.rb:132 ../lib/yard/registry.rb:147
msgid "the registry object (for chaining)"
msgstr "レジストリオブジェクト(チェーン用)"

# YARD::Registry.load_yardoc
#: ../lib/yard/registry.rb:115
msgid "Loads a yardoc file directly"
msgstr "直接yardocファイルをロードする"

# @param [String] file
#: ../lib/yard/registry.rb:118
msgid "the yardoc file to load."
msgstr "ロードするyardocファイル"

# YARD::Registry.load!
#: ../lib/yard/registry.rb:125
msgid ""
"Loads a yardoc file and forces all objects cached on disk into\n"
"memory. Equivalent to calling {load_yardoc} followed by {load_all}"
msgstr ""
"yardocファイルをロードし、\n"
"メモリの中へディスク上の全てのキャッシュされるオブジェクトを強制する。\n"
"{load_all}に続いて呼び出す{load_yardoc}と同等である。"

# @see
#: ../lib/yard/registry.rb:132 ../lib/yard/registry_store.rb:130
msgid "tag|see|#load_all"
msgstr ""

# @see
#: ../lib/yard/registry.rb:132
msgid "tag|see|#load_yardoc"
msgstr ""

# @param [String] file
#: ../lib/yard/registry.rb:132
msgid "the yardoc file to load"
msgstr "ロードするyardocファイル"

# YARD::Registry.load_all
#: ../lib/yard/registry.rb:139
msgid "Forces all objects cached on disk into memory"
msgstr "メモリの中へディスク上のキャッシュされる全てのオブジェクトを強制する"

# @example Loads all objects from disk
#: ../lib/yard/registry.rb:147
msgid ""
"Registry.load\n"
"Registry.all.count #=> 0\n"
"Registry.load_all\n"
"Registry.all.count #=> 17"
msgstr ""

# @example
#: ../lib/yard/registry.rb:147
msgid "tag|example|Loads all objects from disk"
msgstr "ディスクから全てのオブジェクトをロードする"

# YARD::Registry.save
#: ../lib/yard/registry.rb:155
msgid "Saves the registry to +file+"
msgstr "+file+ をレジストリーにセーブする"

# YARD::Registry.save
# YARD::Registry.delete_from_disk
#: ../lib/yard/registry.rb:158 ../lib/yard/registry.rb:164
msgid "Saving and Deleting Data from Disk"
msgstr "ディスクからデータをセーブ/削除する。"

# @param [String] file
#: ../lib/yard/registry.rb:158
msgid "the yardoc file to save to"
msgstr "セーブされるyardocファイル"

# @return [Boolean]
#: ../lib/yard/registry.rb:158
msgid "true if the file was saved"
msgstr "ファイルがセーブされた場合、trueを返す"

# YARD::Registry.delete_from_disk
#: ../lib/yard/registry.rb:163
msgid "Deletes the yardoc file from disk"
msgstr "ディスクからyardocファイルを削除する"

# YARD::Registry.register
#: ../lib/yard/registry.rb:171
msgid "Registers a new object with the registry"
msgstr "リジストリを用い新しいオブジェクトを記録する"

# YARD::Registry.register
# YARD::Registry.delete
# YARD::Registry.clear
#: ../lib/yard/registry.rb:174 ../lib/yard/registry.rb:182
#: ../lib/yard/registry.rb:188
msgid "Adding and Deleting Objects from the Registry"
msgstr "レジストリから、オブジェクトを追加,削除する。"

# @return [CodeObjects::Base]
#: ../lib/yard/registry.rb:174
msgid "the registered object"
msgstr "記録されたオブジェクト"

# YARD::Registry.delete
#: ../lib/yard/registry.rb:180
msgid "Deletes an object from the registry"
msgstr "レジストリーから、オブジェクトを削除する"

# @param [CodeObjects::Base] object
#: ../lib/yard/registry.rb:182
msgid "the object to remove"
msgstr "削除するオブジェクト"

# YARD::Registry.clear
#: ../lib/yard/registry.rb:187
msgid "Clears the registry"
msgstr "レジストリーを空にする"

# YARD::Registry.each
# YARD::Registry.all
# YARD::Registry.paths
# YARD::Registry.at
# YARD::Registry.[]
# YARD::Registry.root
# YARD::Registry.resolve
# YARD::Registry.partial_resolve
#: ../lib/yard/registry.rb:195 ../lib/yard/registry.rb:211
#: ../lib/yard/registry.rb:226 ../lib/yard/registry.rb:235
#: ../lib/yard/registry.rb:236 ../lib/yard/registry.rb:240
#: ../lib/yard/registry.rb:270 ../lib/yard/registry.rb:368
msgid "Accessing Objects in the Registry"
msgstr "レジストリーの中でオブジェクトにアクセスする"

# YARD::Registry.each
#: ../lib/yard/registry.rb:195
msgid "Iterates over {all} with no arguments"
msgstr "引数無しで{all}を繰り返す。"

# YARD::Registry.all
#: ../lib/yard/registry.rb:200
msgid ""
"Returns all objects in the registry that match one of the types provided\n"
"in the +types+ list (if +types+ is provided)."
msgstr ""
"+types+ リスト(タイプが供給される場合 )\n"
"供給される型の一つにマッチするレジストリーの中でオブジェクトの全てを返す"

# @example Returns all objects
#: ../lib/yard/registry.rb:211
msgid "Registry.all"
msgstr ""

# @example Returns all classes and modules
#: ../lib/yard/registry.rb:211
msgid "Registry.all(:class, :module)"
msgstr ""

# @param [Array] types
#: ../lib/yard/registry.rb:211
msgid ""
"an optional list of types to narrow the\n"
"objects down by. Equivalent to performing a select:\n"
"  +Registry.all.select {|o| types.include(o.type) }+"
msgstr ""
"任意の型のリストを絞り込む。次の選択と同様である。\n"
"  +Registry.all.select {|o| types.include(o.type) }+"

# @example
#: ../lib/yard/registry.rb:211
msgid "tag|example|Returns all classes and modules"
msgstr "全てのクラスとモジュールを返す"

# @example
#: ../lib/yard/registry.rb:211
msgid "tag|example|Returns all objects"
msgstr "全てのオブジェクトを返す"

# @param [Array]
# @param [Array]
#: ../lib/yard/registry.rb:211 ../lib/yard/tags/tag.rb:43
msgid "tag|param|types"
msgstr ""

# @see
#: ../lib/yard/registry.rb:211
msgid "tag|see|CodeObjects::Base#type"
msgstr ""

# @return [Array]
#: ../lib/yard/registry.rb:211
msgid "the list of objects found"
msgstr "オブジェクトのリストをみつける"

# YARD::Registry.paths
#: ../lib/yard/registry.rb:224
msgid "Returns the paths of all of the objects in the registry."
msgstr "レジストリーの中の全てのオブジェクトのパスを返す"

# @return [Array]
#: ../lib/yard/registry.rb:226
msgid "all of the paths in the registry."
msgstr "レジストリーの中のパスの全て"

# @param [Boolean]
#: ../lib/yard/registry.rb:226 ../lib/yard/registry_store.rb:80
#: ../lib/yard/registry_store.rb:88
msgid "tag|param|reload"
msgstr ""

# @param [Boolean] reload
#: ../lib/yard/registry.rb:226
msgid "whether to load entire database"
msgstr "データベース全体をロードするかどうか"

# YARD::Registry.at
# YARD::Registry.[]
#: ../lib/yard/registry.rb:231 ../lib/yard/registry.rb:237
msgid "Returns the object at a specific path."
msgstr "固有のパスでオブジェクトを返す"

# @return [CodeObjects::Base]
#: ../lib/yard/registry.rb:235
msgid "the object at path"
msgstr "パスのオブジェクト"

# @param [String, :root] path
#: ../lib/yard/registry.rb:235
msgid ""
"the pathname to look for. If +path+ is +root+,\n"
"returns the {root} object."
msgstr ""
"検索の為のパス名、 +path+ が +root+ の場合\n"
"{root}を返す。"

# YARD::Registry.root
#: ../lib/yard/registry.rb:239
msgid "The root namespace object."
msgstr "rootは名前空間オブジェクトとなる"

# @return [CodeObjects::RootObject]
#: ../lib/yard/registry.rb:240
msgid "the root object in the namespace"
msgstr "namespaceの中のrootオブジェクト"

# YARD::Registry.resolve
#: ../lib/yard/registry.rb:243
msgid ""
"Attempts to find an object by name starting at +namespace+, performing\n"
"a lookup similar to Ruby's method of resolving a constant in a namespace."
msgstr ""
"+namespace+ でnameで始まるオブジェクトが見つかるか試みる\n"
"namespaceの中で定数を解決するのに、Rubyメソッドと同様に検索を実行する。"

# @param [Boolean] inheritance
#: ../lib/yard/registry.rb:270
msgid ""
"Follows inheritance chain (mixins, superclass)\n"
"when performing name resolution if set to +true+."
msgstr ""
"+true+が設定された時、名前解決を実行する、継承のチェーン(mixin,superクラス)"

# @param [Boolean] proxy_fallback
#: ../lib/yard/registry.rb:270
msgid ""
"If +true+, returns a proxy representing\n"
"the unresolved path (namespace + name) if no object is found."
msgstr ""
"+true+の場合やオブジェクトが見つからなかった場合、\n"
"未解決のパス(namespace + name)を表すproxyを返す。"

# @example Looks for instance method #reverse starting from A::B::C
#: ../lib/yard/registry.rb:270
msgid "Registry.resolve(P(\"A::B::C\"), \"#reverse\")"
msgstr ""

# @example Looks for a complex path from a namespace
#: ../lib/yard/registry.rb:270
msgid "Registry.resolve(P('A::B'), 'B::D') # => #"
msgstr "Registry.resolve(P('A::B'), 'B::D') # => #"

# @example Looks for a constant but returns a proxy if not found
#: ../lib/yard/registry.rb:270
msgid ""
"Registry.resolve(P('A::B::C'), 'D', false, true) # => #"
msgstr ""

# @example Looks for a class method respecting the inheritance tree
#: ../lib/yard/registry.rb:270
msgid "Registry.resolve(myclass, 'mymethod', true)"
msgstr ""

# @example Looks for a constant in the root namespace
#: ../lib/yard/registry.rb:270
msgid "Registry.resolve(nil, 'CONSTANT')"
msgstr ""

# @return [CodeObjects::Proxy]
#: ../lib/yard/registry.rb:270
msgid ""
"a Proxy representing the object if\n"
"+proxy_fallback+ is +true+."
msgstr "+proxy_fallback+ が +true+の場合、オブジェクトを表すproxyとなる。"

# @return [nil]
#: ../lib/yard/registry.rb:270
msgid "if +proxy_fallback+ is +false+ and no object was found."
msgstr "+proxy_fallback+ が +false+ 又は、オブジェクトが見つからなかった場合"

# @example
#: ../lib/yard/registry.rb:270
msgid "tag|example|Looks for a class method respecting the inheritance tree"
msgstr "関連する継承ツリーのクラスメソッドを探す"

# @example
#: ../lib/yard/registry.rb:270
msgid "tag|example|Looks for a complex path from a namespace"
msgstr "namespaceから複雑なパスを検索する"

# @example
#: ../lib/yard/registry.rb:270
msgid "tag|example|Looks for a constant but returns a proxy if not found"
msgstr "定数を探すが、見つからない場合は、proxyを返す。"

# @example
#: ../lib/yard/registry.rb:270
msgid "tag|example|Looks for a constant in the root namespace"
msgstr "root namespaseの中の定数をを探す"

# @example
#: ../lib/yard/registry.rb:270
msgid "tag|example|Looks for instance method #reverse starting from A::B::C"
msgstr "A::B::Cで始まる、インスタンスメソッド#reverseを探す"

# @param [Boolean]
#: ../lib/yard/registry.rb:270
msgid "tag|param|inheritance"
msgstr "継承"

# @param [Boolean]
#: ../lib/yard/registry.rb:270
msgid "tag|param|proxy_fallback"
msgstr ""

# @see
#: ../lib/yard/registry.rb:270
msgid "tag|see|P"
msgstr ""

# @param [String, Symbol] name
#: ../lib/yard/registry.rb:270
msgid ""
"the name (or complex path) to look for from\n"
"+namespace+."
msgstr "+namespace+ から検索する名前(や複雑なパス)"

# @return [CodeObjects::Base]
#: ../lib/yard/registry.rb:270
msgid "the object if it is found"
msgstr "見つかったオブジェクト"

# @param [CodeObjects::NamespaceObject, nil] namespace
#: ../lib/yard/registry.rb:270
msgid ""
"the starting namespace\n"
"(module or class). If +nil+ or +:root+, starts from the {root} object."
msgstr ""
"始まりのnamespace(モジュールやクラス)。\n"
"+nil+ や +:root+ の場合、{root}オブジェクトから始まる。"

# @param [Symbol, nil] type
#: ../lib/yard/registry.rb:270
msgid ""
"the {CodeObjects::Base#type} that the resolved\n"
"object must be equal to. No type checking if nil."
msgstr ""

# YARD::Registry.checksums
# YARD::Registry.checksum_for
#: ../lib/yard/registry.rb:317 ../lib/yard/registry.rb:323
msgid "Managing Source File Checksums"
msgstr "ソースファイルチェックサムを管理する"

# @return [Hash{String => String}]
#: ../lib/yard/registry.rb:317
msgid "a set of checksums for files"
msgstr "ファイル用のチェックサムのグループ"

# @param [String] data
#: ../lib/yard/registry.rb:323
msgid "data to checksum"
msgstr "チェックサムするデータ"

# @return [String]
#: ../lib/yard/registry.rb:323
msgid "the SHA1 checksum for data"
msgstr "データのSHA1チェックサム"

# YARD::Registry.single_object_db
# YARD::Registry.single_object_db=
#: ../lib/yard/registry.rb:330
msgid ""
"Whether or not the Registry storage should load everything into a\n"
"single object database (for disk efficiency), or spread them out\n"
"(for load time efficiency)."
msgstr ""
"レジストリーストレージは単一のオブジェクトのデータベースの中へ\n"
"毎回ロードするか、(ディスク効率の為)\n"
"又は、データベースを展開する。(ロード時間効率の為)"

# YARD::Registry.single_object_db
# YARD::Registry.single_object_db=
# YARD::Registry.proxy_types
#: ../lib/yard/registry.rb:337 ../lib/yard/registry.rb:339
#: ../lib/yard/registry.rb:340 ../lib/yard/registry.rb:346
msgid "Managing Internal State (Advanced / Testing Only)"
msgstr "内部の状態を管理する(Advanced / Testing Only)"

# @note
#: ../lib/yard/registry.rb:337 ../lib/yard/registry.rb:339
#: ../lib/yard/registry.rb:340
msgid ""
"Setting this attribute to nil will offload the decision to\n"
"the {RegistryStore storage adapter}."
msgstr ""
"この属性にnilを設定すると、{RegistryStore storage adapter}の決定をunloadす"
"る。"

# @return [Boolean, nil]
#: ../lib/yard/registry.rb:337 ../lib/yard/registry.rb:339
#: ../lib/yard/registry.rb:340
msgid ""
"if this value is set to nil, the storage\n"
"adapter will decide how to store the data."
msgstr ""
"この値にnilを設定した場合、\n"
"ストレージアダプターがデータを記録する方法を決める。"

# YARD::Registry.proxy_types
#: ../lib/yard/registry.rb:343
msgid ""
"The assumed types of a list of paths. This method is used by CodeObjects::"
"Base"
msgstr ""
"パスのリストの想定される型。このメソッドはCodeObjects::Baseによって利用され"
"る。"

# @deprecated
#: ../lib/yard/registry.rb:346
msgid "The registry no longer globally tracks proxy types."
msgstr ""

# @return [{String => Symbol}]
#: ../lib/yard/registry.rb:346
msgid "a set of unresolved paths and their assumed type"
msgstr "未解決のパスのグループやその想定される型"

# YARD::Registry.instance
#: ../lib/yard/registry.rb:353
msgid "The registry singleton instance."
msgstr "レジストリーのシングルトンインスタンス"

# YARD::Registry.instance
#: ../lib/yard/registry.rb:356
msgid "Legacy Methods"
msgstr "Legacy Methods"

# @return [Registry]
#: ../lib/yard/registry.rb:356
msgid "returns the registry instance"
msgstr "レジストリーインスタンスを返す"

# @deprecated
#: ../lib/yard/registry.rb:356
msgid "use Registry.methodname directly."
msgstr "直接Registry.methodnameを使う"

# YARD::Registry.partial_resolve
#: ../lib/yard/registry.rb:363
msgid "Attempts to resolve a name in a namespace"
msgstr "namespaceの中で名前の解決を試みる"

# @param [String] name
#: ../lib/yard/registry.rb:368
msgid "the name to look for"
msgstr "検索するname"

# @param [CodeObjects::NamespaceObject] namespace
#: ../lib/yard/registry.rb:368
msgid "the starting namespace"
msgstr "始まりのnamespace"

# @param [Symbol, nil] type
#: ../lib/yard/registry.rb:368
msgid ""
"the {CodeObjects::Base#type} that the resolved\n"
"object must be equal to"
msgstr ""

# YARD::Registry.global_yardoc_file
# YARD::Registry.local_yardoc_file
#: ../lib/yard/registry.rb:385 ../lib/yard/registry.rb:395
msgid "Retrieving yardoc File Locations"
msgstr "yardocファイルの場所を取り出す"

# @since
#: ../lib/yard/registry.rb:409 ../lib/yard/registry.rb:414
msgid "0.6.5"
msgstr ""

# YARD::Registry.thread_local_store
# YARD::Registry.thread_local_store=
#: ../lib/yard/registry.rb:409 ../lib/yard/registry.rb:414
msgid "Threading support"
msgstr "スレッドをサポート"

# YARD::RegistryStore
#: ../lib/yard/registry_store.rb:5
msgid "The data store for the {Registry}."
msgstr "{Registry}用のデータストア"

# @see
#: ../lib/yard/registry_store.rb:8
msgid "tag|see|Serializers::YardocSerializer"
msgstr ""

# YARD::Registry.instance
#: ../lib/yard/registry_store.rb:10 ../lib/yard/registry_store.rb:213
#: ../lib/yard/registry_store.rb:250 ../lib/yard/registry_store.rb:291
#: ../lib/yard/serializers/yardoc_serializer.rb:36
msgid "The registry no longer tracks proxy types"
msgstr "レジストリはプロキシタイプの追跡をしない"

# YARD::RegistryStore#checksums
#: ../lib/yard/registry_store.rb:12
msgid "Returns the value of attribute checksums"
msgstr "checksums属性の値を返す"

# @return [RegistryStore]
#: ../lib/yard/registry_store.rb:13
msgid "a new instance of RegistryStore"
msgstr "RegistryStoreの新しいインスタンス"

# YARD::RegistryStore#get
# YARD::RegistryStore#[]
#: ../lib/yard/registry_store.rb:27 ../lib/yard/registry_store.rb:67
msgid "Gets a {CodeObjects::Base} from the store"
msgstr "記録から{CodeObjects::Base}を取得する"

# @return [CodeObjects::Base, nil]
#: ../lib/yard/registry_store.rb:31
msgid "a code object or nil if none is found"
msgstr "コードオブジェクトか見つからない場合はnilを返す"

# @param [String, Symbol] key
#: ../lib/yard/registry_store.rb:31
msgid ""
"the path name of the object to look for.\n"
"If it is empty or :root, returns the {#root} object."
msgstr ""
"検索の為のオブジェクトのパス名。\n"
"空か:rootの場合、{#root}オブジェクトを返す。"

# YARD::RegistryStore#put
# YARD::RegistryStore#[]=
#: ../lib/yard/registry_store.rb:49 ../lib/yard/registry_store.rb:68
msgid "Associates an object with a path"
msgstr "パスと一緒にオブジェクトを関連付ける。"

# @return [CodeObjects::Base]
#: ../lib/yard/registry_store.rb:52
msgid "returns +value+"
msgstr "+value+ を返す"

# @param [CodeObjects::Base] value
#: ../lib/yard/registry_store.rb:52
msgid "the object to store"
msgstr "記録するオブジェクト"

# @param [String, Symbol] key
#: ../lib/yard/registry_store.rb:52
msgid "the path name (:root or '' for root object)"
msgstr "パス名(:rootやrootオブジェクト用の'')"

# YARD::RegistryStore#put
# YARD::RegistryStore#[]=
#: ../lib/yard/registry_store.rb:70
msgid "Deletes an object at a given path"
msgstr "与えられたパスでオブジェクトを削除する"

# YARD::RegistryStore#keys
#: ../lib/yard/registry_store.rb:75
msgid ""
"Gets all path names from the store. Loads the entire database\n"
"if +reload+ is +true+"
msgstr ""
"記録から全てのパス名を取得する。\n"
"+reload+ が +true+ の場合、全体のデータベースをロードする。"

# @param [Boolean] reload
#: ../lib/yard/registry_store.rb:80 ../lib/yard/registry_store.rb:88
msgid ""
"if false, does not load the entire database\n"
"before a lookup."
msgstr "falseの場合、検索の前に全体のデータベースをロードしない"

# @return [Array]
#: ../lib/yard/registry_store.rb:80
msgid "the path names of all the code objects"
msgstr "全てのコードオブジェクトのパス名"

# YARD::RegistryStore#values
#: ../lib/yard/registry_store.rb:83
msgid ""
"Gets all code objects from the store. Loads the entire database\n"
"if +reload+ is +true+"
msgstr ""
"記録から全てのパス名を取得する。\n"
"+reload+ が +true+ の場合、全体のデータベースをロードする。"

# @return [Array]
#: ../lib/yard/registry_store.rb:88
msgid "all the code objects"
msgstr "全てのコードオブジェクト"

# @return [Array]
#: ../lib/yard/registry_store.rb:94
msgid ""
"a list of object paths with a given\n"
"{CodeObjects::Base#type}"
msgstr ""

# @param [String] name
#: ../lib/yard/registry_store.rb:94 ../lib/yard/registry_store.rb:103
msgid "the type to look for"
msgstr "型用に検索する型"

# @return [Array]
#: ../lib/yard/registry_store.rb:103
msgid ""
"a list of objects with a given\n"
"{CodeObjects::Base#type}"
msgstr ""

# @return [CodeObjects::RootObject]
#: ../lib/yard/registry_store.rb:109
msgid "the root object"
msgstr "rootオブジェクト"

# @param [String, nil] file
#: ../lib/yard/registry_store.rb:113 ../lib/yard/registry_store.rb:130
msgid "the name of the yardoc db to load"
msgstr "ロードするyardoc dbの名前"

# @return [Boolean]
#: ../lib/yard/registry_store.rb:113 ../lib/yard/registry_store.rb:130
msgid "whether the database was loaded"
msgstr "データベースがロードされたかどうか"

# YARD::RegistryStore#load!
#: ../lib/yard/registry_store.rb:124
msgid ""
"Loads the .yardoc file and loads all cached objects into memory\n"
"automatically."
msgstr ""
".yardocファイルをロードしたり、\n"
"全てのキャッシュされたオブジェクトを自動的にメモリの中へロードする。"

# YARD::RegistryStore#load_all
#: ../lib/yard/registry_store.rb:140
msgid "Loads all cached objects into memory"
msgstr "メモリの中へ全てのキャッシュされたオブジェクトをロードする"

# YARD::RegistryStore#save
#: ../lib/yard/registry_store.rb:160
msgid "Saves the database to disk"
msgstr "ディスクにデータベースをセーブする"

# @param [String, nil] file
#: ../lib/yard/registry_store.rb:164
msgid "if supplied, the name of the file to save to"
msgstr "指定された場合、セーブするファイルの名前となる"

# @param [Boolean] merge
#: ../lib/yard/registry_store.rb:164
msgid ""
"if true, merges the data in memory with the\n"
"data on disk, otherwise the data on disk is deleted."
msgstr ""
"trueの場合、ディスク上のデータと共にメモリの中のデータをマージする。\n"
"そうでなければ、ディスク上のデータは削除される。"

# @param [Boolean]
#: ../lib/yard/registry_store.rb:164
msgid "tag|param|merge"
msgstr ""

# @return [Boolean]
#: ../lib/yard/registry_store.rb:164
msgid "whether the database was saved"
msgstr "データベースがセーブされるかどうか"

# YARD::RegistryStore#destroy
#: ../lib/yard/registry_store.rb:186
msgid "Deletes the .yardoc database on disk"
msgstr "ディスク上のデータベースの.yardocの削除"

# @param [Boolean] force
#: ../lib/yard/registry_store.rb:192
msgid ""
"if force is not set to true, the file/directory\n"
"will only be removed if it ends with .yardoc. This helps with\n"
"cases where the directory might have been named incorrectly."
msgstr ""
"forceにtrueが設定されず、そのファイルの末尾に.yardocが付く場合、\n"
"ファイル/ディレクトリは削除される。\n"
"これは、ディレクトリが間違って名付けられた場合、役立つだろう。"

# @param [Boolean]
#: ../lib/yard/registry_store.rb:192
msgid "tag|param|force"
msgstr ""

# @return [Boolean]
#: ../lib/yard/registry_store.rb:192
msgid ""
"true if the .yardoc database was deleted, false\n"
"otherwise."
msgstr ""
".yardocデータベースが削除された場合、true。\n"
"それ以外はfalse。"

# YARD::Serializers::Base
#: ../lib/yard/serializers/base.rb:4
msgid ""
"The abstract base serializer. Serializers allow templates to be\n"
"rendered to various endpoints. For instance, a {FileSystemSerializer}\n"
"would allow template contents to be written to the filesystem"
msgstr ""
"これは抽象的なベースのシリアライザとなる。\n"
"シリアライザは、様々なエンドポイントで表示される\n"
"テンプレートを受け入れる。\n"
"例えば、{FileSystemSerializer}は、\n"
"ファイルシステムに書かれる内容のテンプレートを受け入れる。"

# YARD::Serializers::Base
#: ../lib/yard/serializers/base.rb:8
msgid ""
"To implement a custom serializer, override the following methods:\n"
"* {#serialize}\n"
"* {#serialized_path}"
msgstr ""
"カスタムシリアライザを実装するには、次のメソッドを上書きする。:\n"
"* {#serialize}\n"
"* {#serialized_path}"

# YARD::Serializers::Base
#: ../lib/yard/serializers/base.rb:12
msgid ""
"Optionally, a serializer can implement before and after filters:\n"
"* {#before_serialize}\n"
"* {#after_serialize}"
msgstr ""
"任意で、シリアライザはフィルターの前後に実装できる。:\n"
"* {#before_serialize}\n"
"* {#after_serialize}"

# @abstract
#: ../lib/yard/serializers/base.rb:16
msgid "Override this class to implement a custom serializer."
msgstr "カスタムシリアライザを実装する為に、このクラスを上書きする。"

# YARD::Serializers::Base#options
#: ../lib/yard/serializers/base.rb:18
msgid ""
"All serializer options are saved so they can be passed to other serializers."
msgstr ""
"全てのシリアライザのオプションはセーブされるので、他のシリアライザに渡す事が"
"出来る。"

# @return [SymbolHash]
#: ../lib/yard/serializers/base.rb:20
msgid "the serializer options"
msgstr "シリアライザのオプション"

# YARD::Serializers::Base#initialize
#: ../lib/yard/serializers/base.rb:25
msgid "Creates a new serializer with options"
msgstr "オプションと共に新しいシリアライザを作成する。"

# YARD::Serializers::Base#initialize
#: ../lib/yard/serializers/base.rb:27
msgid "Creating a New Serializer"
msgstr "新しいシリアライザを作成する。"

# @param [Hash] opts
#: ../lib/yard/serializers/base.rb:27
msgid "the options to assign to {#options}"
msgstr "{#options}メソッドに割り当てるオプション"

# YARD::Serializers::Base#serialize
#: ../lib/yard/serializers/base.rb:34
msgid "Serializes an object."
msgstr "シリアライズするオブジェクト"

# YARD::Serializers::Base#serialize
# YARD::Serializers::Base#serialized_path
# YARD::Serializers::Base#exists?
#: ../lib/yard/serializers/base.rb:41 ../lib/yard/serializers/base.rb:50
#: ../lib/yard/serializers/base.rb:61
msgid "Serializing an Object"
msgstr "シリアライズするオブジェクト"

# @abstract
#: ../lib/yard/serializers/base.rb:41
msgid ""
"This method should implement the logic that serializes\n"
"+data+ to the respective endpoint. This method should also call\n"
"the before and after callbacks {#before_serialize} and {#after_serialize}"
msgstr ""
"このメソッドはそれぞれのエンドポイントに +data+ をシリアライズするロジック"
"を\n"
"実装するべきである。\n"
"また、このメソッドは前後に{#before_serialize} と {#after_serialize}の\n"
"コールバックも呼び出すべきである。"

# @param [String] data
#: ../lib/yard/serializers/base.rb:41
msgid "the contents that should be serialized"
msgstr "シリアライズされるべき内容"

# @param [CodeObjects::Base, String] object
#: ../lib/yard/serializers/base.rb:41
msgid ""
"the object to serialize the\n"
"data for. The object can also be a string (for non-object serialization)"
msgstr ""
"オブジェクトのデータをシリアライズするオブジェクト、\n"
"このオブジェクトは文字列にもできる。(非オブジェクトをシリアライズする場合)"

# YARD::Serializers::Base#serialized_path
#: ../lib/yard/serializers/base.rb:44
msgid "The serialized path of an object"
msgstr "シリアライズされるオブジェクトのパス"

# @abstract
#: ../lib/yard/serializers/base.rb:50
msgid ""
"This method should return the path of the object on the\n"
"endpoint. For instance, for a file serializer, this should return\n"
"the filename that represents the object on disk."
msgstr ""
"このメソッドは、エンドポイント上のオブジェクトのパスを返す。\n"
"例えば、ファイルシリアライザは、ディスクの中のそのオブジェクトを表すファイル"
"名を返す。"

# @param [CodeObjects::Base] object
#: ../lib/yard/serializers/base.rb:50
msgid "the object to return a path for"
msgstr "パスを返す為のオブジェクト"

# @return [String]
#: ../lib/yard/serializers/base.rb:50
msgid "the serialized path of an object"
msgstr "シリアライズされたオブジェクトのパス"

# YARD::Serializers::Base#exists?
#: ../lib/yard/serializers/base.rb:53
msgid "Returns whether an object has been serialized"
msgstr "シリアライズされたオブジェクトかどうかを返す"

# @abstract
#: ../lib/yard/serializers/base.rb:61
msgid ""
"This method should return whether the endpoint already exists.\n"
"For instance, a file system serializer would check if the file exists\n"
"on disk. You will most likely use +#basepath+ and {#serialized_path} to\n"
"get the endpoint's location."
msgstr ""
"このメソッドは既にエンドポイントが存在するかどうかを返す。\n"
"例えば、ファイルがディスク上に存在する場合、\n"
"ファイルシステムシリアライザは、このチェックを行うだろう。\n"
"あなたは、恐らくエンドポイントの場所を取得する為に、\n"
"+#basepath+ や {#serialized_path} メソッドを使うだろう。"

# @param [CodeObjects::Base] object
#: ../lib/yard/serializers/base.rb:61
msgid "the object to check existence of"
msgstr "存在するかチェックするオブジェクト"

# @return [Boolean]
#: ../lib/yard/serializers/base.rb:61
msgid "whether the endpoint exists."
msgstr "エンドポイントが存在するかどうか"

# YARD::Serializers::Base#before_serialize
#: ../lib/yard/serializers/base.rb:66
msgid "Called before serialization."
msgstr "シリアライズする前に呼び出される"

# YARD::Serializers::Base#before_serialize
# YARD::Serializers::Base#after_serialize
#: ../lib/yard/serializers/base.rb:70 ../lib/yard/serializers/base.rb:77
msgid "Callbacks"
msgstr ""

# @abstract
#: ../lib/yard/serializers/base.rb:70
msgid ""
"Should run code before serialization. Should return false\n"
"if serialization should not occur."
msgstr ""
"シリアライズする前にコードを起動する。\n"
"シリアライズしても何も存在しない場合、falseを返す。"

# @return [Boolean]
#: ../lib/yard/serializers/base.rb:70
msgid "whether or not serialization should occur"
msgstr "シリアライズが存在するかどうか"

# YARD::Serializers::Base#after_serialize
#: ../lib/yard/serializers/base.rb:73
msgid "Called after serialization."
msgstr "後で呼び出されるシリアライズ"

# @abstract
#: ../lib/yard/serializers/base.rb:77
msgid "Should run code after serialization."
msgstr "後でシリアライズのコードを起動する"

# @param [String] data
#: ../lib/yard/serializers/base.rb:77
msgid "the data that was serialized."
msgstr "シリアライズされたデータ"

# YARD::Serializers::FileSystemSerializer
#: ../lib/yard/serializers/file_system_serializer.rb:4
msgid "Implements a serializer that reads from and writes to the filesystem."
msgstr "ファイルシステムに読み書き込みするシリアライザを実装する。"

# YARD::Serializers::FileSystemSerializer#basepath
#: ../lib/yard/serializers/file_system_serializer.rb:6
msgid "The base path to write data to."
msgstr "データに書き込む為のベースパス"

# @return [String]
#: ../lib/yard/serializers/file_system_serializer.rb:7
msgid "a base path"
msgstr "ベースパス"

# YARD::Serializers::FileSystemSerializer#extension
#: ../lib/yard/serializers/file_system_serializer.rb:14
msgid "The extension of the filename (defaults to +html+)"
msgstr "ファイル名の拡張子(デフォルトは +html+ )"

# @return [String]
#: ../lib/yard/serializers/file_system_serializer.rb:16
msgid "the extension of the file. Empty string for no extension."
msgstr "ファイルの拡張子。拡張子無しは空文字"

# YARD::Serializers::FileSystemSerializer#initialize
#: ../lib/yard/serializers/file_system_serializer.rb:23
msgid "Creates a new FileSystemSerializer with options"
msgstr "オプションと共に、新しいFileSystemSerializerを作成する。"

# @return [FileSystemSerializer]
#: ../lib/yard/serializers/file_system_serializer.rb:27
msgid "a new instance of FileSystemSerializer"
msgstr "FileSystemSerializerの新しいインスタンス"

# YARD::Serializers::FileSystemSerializer#serialize
#: ../lib/yard/serializers/file_system_serializer.rb:34
msgid ""
"Serializes object with data to its serialized path (prefixed by the "
"+#basepath+)."
msgstr ""
"パス(+#basepath+ がプレフィックスされる)をシリアライズする為、\n"
"データと共に、オブジェクトをシリアライズする。"

# @return [String]
#: ../lib/yard/serializers/file_system_serializer.rb:36
msgid "the written data (for chaining)"
msgstr "書き込まれるデータ(チェーン用)"

# YARD::Serializers::FileSystemSerializer#serialized_path
#: ../lib/yard/serializers/file_system_serializer.rb:43
msgid "Implements the serialized path of a code object."
msgstr "コードオブジェクトのシリアライズされるパスを実装する。"

# @return [String]
#: ../lib/yard/serializers/file_system_serializer.rb:48
msgid ""
"if object is a String, returns\n"
"object, otherwise the path on disk (without the basepath)."
msgstr ""
"オブジェクトがStringの場合、オブジェクトを返し、\n"
"それ以外は、ディスク上のパスを返す。(basepathを含まない)"

# @param [CodeObjects::Base, CodeObjects::ExtraFileObject, String] object
#: ../lib/yard/serializers/file_system_serializer.rb:48
msgid ""
"the object to get a path for. The path of a string is the string itself."
msgstr "パスを取得する為のオブジェクト。文字列のパスはその文字列自身を返す。"

# YARD::Serializers::FileSystemSerializer#exists?
#: ../lib/yard/serializers/file_system_serializer.rb:66
msgid "Checks the disk for an object and returns whether it was serialized."
msgstr ""
"オブジェクト用にディスクをチェックしたり、シリアライズされたかどうか返す。"

# @param [CodeObjects::Base] object
#: ../lib/yard/serializers/file_system_serializer.rb:69
msgid "the object to check"
msgstr "チェックするオブジェクト"

# @return [Boolean]
#: ../lib/yard/serializers/file_system_serializer.rb:69
msgid "whether an object has been serialized to disk"
msgstr "オブジェクトが既にディスクにシリアライズされているかどうか"

# YARD::Serializers::FileSystemSerializer#encode_path_components
#: ../lib/yard/serializers/file_system_serializer.rb:76
msgid ""
"Remove special chars from filenames.\n"
"Windows disallows \\ / : * ? \" < > | but we will just remove any\n"
"non alphanumeric (plus period, underscore and dash)."
msgstr ""

# YARD::Serializers::ProcessSerializer
#: ../lib/yard/serializers/process_serializer.rb:4
msgid "Serializes an object to a process (like less)"
msgstr "処理の為のオブジェクトをシリアライズする。(lessのような)"

# @example Serializing to a pager (less)
#: ../lib/yard/serializers/process_serializer.rb:8
msgid ""
"serializer = ProcessSerializer.new('less')\n"
"serializer.serialize(object, \"data!\")"
msgstr ""

# @example
#: ../lib/yard/serializers/process_serializer.rb:8
msgid "tag|example|Serializing to a pager (less)"
msgstr "ページャーをシリアライズする(less)"

# YARD::Serializers::ProcessSerializer#initialize
#: ../lib/yard/serializers/process_serializer.rb:10
msgid "Creates a new ProcessSerializer for the shell command +cmd+"
msgstr "シェルコマンド +cmd+ 用に新しいProcessSerializerを作成する。"

# @return [ProcessSerializer]
#: ../lib/yard/serializers/process_serializer.rb:12
msgid "a new instance of ProcessSerializer"
msgstr "ProcessSerializerの新しいインスタンス"

# @param [String]
#: ../lib/yard/serializers/process_serializer.rb:12
msgid "tag|param|cmd"
msgstr ""

# @param [String] cmd
#: ../lib/yard/serializers/process_serializer.rb:12
msgid "the command that will accept data on stdin"
msgstr "標準入力上でデータを受け入れるコマンド"

# YARD::Serializers::ProcessSerializer#serialize
#: ../lib/yard/serializers/process_serializer.rb:17
msgid ""
"Overrides serialize behaviour and writes data to standard input\n"
"of the associated command"
msgstr ""
"シリアライズの挙動を上書きし、\n"
"関連付けられたコマンドの標準入力にデータを書き込む。"

# YARD::Serializers::StdoutSerializer
#: ../lib/yard/serializers/stdout_serializer.rb:4
msgid "A serializer that writes data to standard output."
msgstr "標準出力にデータを書くシリアライザ"

# YARD::Serializers::StdoutSerializer#initialize
#: ../lib/yard/serializers/stdout_serializer.rb:6
msgid "Creates a serializer to print text to stdout"
msgstr "標準出力にテキストをプリントするシリアライザを作成する。"

# @return [StdoutSerializer]
#: ../lib/yard/serializers/stdout_serializer.rb:9
msgid "a new instance of StdoutSerializer"
msgstr "StdoutSerializerの新しいインスタンス"

# @param [Fixnum, nil] wrap
#: ../lib/yard/serializers/stdout_serializer.rb:9
msgid ""
"if wrap is a number, wraps text to +wrap+\n"
"columns, otherwise no wrapping is done."
msgstr ""
"wrapが数字の場合、+wrap+ カラムにテキストをラップする。\n"
"それ以外では、ラップは行わない。"

# @param [Fixnum, nil]
#: ../lib/yard/serializers/stdout_serializer.rb:9
msgid "tag|param|wrap"
msgstr ""

# YARD::Serializers::StdoutSerializer#serialize
#: ../lib/yard/serializers/stdout_serializer.rb:14
msgid "Overrides serialize behaviour to write data to standard output"
msgstr "標準出力にデータを書き込む為にシリアライズの挙動を上書きする。"

# YARD::Serializers::StdoutSerializer#word_wrap
#: ../lib/yard/serializers/stdout_serializer.rb:21
msgid "Wraps text to a specific column length"
msgstr "特定のカラムの長さにテキストをラップする。"

# @param [Fixnum]
#: ../lib/yard/serializers/stdout_serializer.rb:25
msgid "tag|param|length"
msgstr ""

# @param [Fixnum] length
#: ../lib/yard/serializers/stdout_serializer.rb:25
msgid "the column length to wrap to"
msgstr "ラップの為のカラムの長さ"

# @param [String] text
#: ../lib/yard/serializers/stdout_serializer.rb:25
msgid "the text to wrap"
msgstr "ラップされるテキスト"

# @return [String]
#: ../lib/yard/serializers/stdout_serializer.rb:25
msgid "the wrapped text"
msgstr "ラップされたテキスト"

# YARD::StubProxy
#: ../lib/yard/serializers/yardoc_serializer.rb:3
msgid "Stubs marshal dumps and acts a delegate class for an object by path"
msgstr ""
"引抜き、選別し、出力する。オブジェクトがパスによって委譲クラスのように振る舞"
"う"

# @return [StubProxy]
#: ../lib/yard/serializers/yardoc_serializer.rb:12
msgid "a new instance of StubProxy"
msgstr "StubProxyの新しいインスタンス"

# @return [YardocSerializer]
#: ../lib/yard/serializers/yardoc_serializer.rb:30
msgid "a new instance of YardocSerializer"
msgstr "YardocSerializerの新しいインスタンス"

# YARD::Server.register_static_path
#: ../lib/yard/server.rb:4
msgid "Registers a static path to be used in static asset lookup."
msgstr "静的な資源の検索の中で利用される静的パスを記録する。"

# @param [String] path
#: ../lib/yard/server.rb:7
msgid "the pathname to register"
msgstr "記録する為のパス名"

# YARD::Server::FinishRequest
#: ../lib/yard/server/adapter.rb:5
msgid ""
"Short circuits a request by raising an error. This exception is caught\n"
"by {Commands::Base#call} to immediately end a request and return a response."
msgstr ""
"エラーを上げることによってリクエストを省く。\n"
"この例外はすぐに、リクエストの終了とレスポンスを返す為に\n"
"{Commands::Base#call} によってキャッチされる。"

# YARD::Server::NotFoundError
#: ../lib/yard/server/adapter.rb:9
msgid ""
"Raises an error if a resource is not found. This exception is caught by\n"
"{Commands::Base#call} to immediately end a request and return a 404 "
"response\n"
"code. If a message is provided, the body is set to the exception message."
msgstr ""
"リソースが見つからない場合、エラーを上げる。\n"
"この例外は、すぐにリクエストの終りと404レスポンスコードを返す為に\n"
"{Commands::Base#call}によってキャッチされる。\n"
"メッセージが提供される場合、本体に、例外メッサージが設定される。"

# YARD::Server::Adapter
#: ../lib/yard/server/adapter.rb:14
msgid ""
"This class implements the bridge between the {Router} and the server\n"
"backend for a specific server type. YARD implements concrete adapters\n"
"for WEBrick and Rack respectively, though other adapters can be made\n"
"for other server architectures."
msgstr ""
"このクラスは {Router} と固有のサーバータイプ用にサーバーバックエンドの間の\n"
"ブリッジを実装する。\n"
"YARDはWEBrickとRackそれぞれに\n"
"具体的なアダプターを実装するけれども、\n"
"他のアダプターを、他のサーバーアーキテクチャ用に作る事も出来る。"

# YARD::Server::Adapter
#: ../lib/yard/server/adapter.rb:19
msgid ""
"== Subclassing Notes\n"
"To create a concrete adapter class, implement the {#start} method to\n"
"initiate the server backend."
msgstr ""
"== サブクラス化する注意\n"
"具体的なアダプタークラスを作成するには、\n"
"サーバーバックエンドを開始する為に{#start}メソッドを実装する。"

# @return [String]
#: ../lib/yard/server/adapter.rb:27
msgid ""
"the location where static files are located, if any.\n"
"To set this field on initialization, pass +:DocumentRoot+ to the\n"
"+server_opts+ argument in {#initialize}"
msgstr ""
"任意で、スタティックファイルが示される場所。\n"
"初期にこのフィールドを設定するには、\n"
"{#initialize}メソッドの中の +server_opts+ 引数に\n"
"+:DocumentRoot+ を渡す。"

# @see LibraryVersion
#: ../lib/yard/server/adapter.rb:32
msgid "LibraryVersion for information on building a list of libraries"
msgstr ""

# @return [Hash{String=>Array}]
#: ../lib/yard/server/adapter.rb:32
msgid "a map of libraries."
msgstr "ライブラリのマップ"

# @see
#: ../lib/yard/server/adapter.rb:32
msgid "tag|see|#add_library"
msgstr ""

# @see
#: ../lib/yard/server/adapter.rb:32 ../lib/yard/server/library_version.rb:105
#: ../lib/yard/server/library_version.rb:111
msgid "tag|see|LibraryVersion"
msgstr ""

# @return [Hash]
#: ../lib/yard/server/adapter.rb:36
msgid ""
"options passed and processed by adapters. The actual\n"
"options mostly depend on the adapters themselves."
msgstr ""
"アダプターによって渡され、処理されたoptions。\n"
"実際のoptionsの大抵は、アダプター自身に依存する。"

# @return [Hash]
#: ../lib/yard/server/adapter.rb:40
msgid ""
"a set of options to pass to the server backend. Note\n"
"that +:DocumentRoot+ also sets the {#document_root}."
msgstr ""
"サーバーのバックエンドに渡す為のoptionsのグループ\n"
"次の事に留意する。 +:DocumentRoot+ は {#document_root} にも設定する。"

# @return [Router]
#: ../lib/yard/server/adapter.rb:43
msgid "the router object used to route URLs to commands"
msgstr "コマンドにURLを送る為に利用された、routerオブジェクト"

# YARD::Server::Adapter.setup
#: ../lib/yard/server/adapter.rb:46
msgid "Performs any global initialization for the adapter."
msgstr "アダプター用に任意で全体の初期化を実行する。"

# @note
#: ../lib/yard/server/adapter.rb:48 ../lib/yard/server/adapter.rb:56
msgid "If you subclass this method, make sure to call +super+."
msgstr ""
"あなたがこのメソッドをサブクラス化する場合、\n"
"+super+ を呼び出すか確認する事。"

# YARD::Server::Adapter.shutdown
#: ../lib/yard/server/adapter.rb:54
msgid "Performs any global shutdown procedures for the adapter."
msgstr "任意で全体的なアダプター用の手続きのシャットダウンを実行する。"

# YARD::Server::Adapter#initialize
#: ../lib/yard/server/adapter.rb:62
msgid "Creates a new adapter object"
msgstr "新しいアダプターオブジェクトを作成する。"

# @param [Hash{String=>Array}] libs
#: ../lib/yard/server/adapter.rb:71
msgid ""
"a list of libraries,\n"
"see {#libraries} for formulating this list."
msgstr ""
"ライブラリのリスト、\n"
"このリストを公式化する為には、{#librathries}を参照。"

# @return [Adapter]
#: ../lib/yard/server/adapter.rb:71
msgid "a new instance of Adapter"
msgstr "アダプターの新しいインスタンス"

# @param [Hash] opts
#: ../lib/yard/server/adapter.rb:71
msgid "extra options to pass to the adapter"
msgstr "アダプターに渡す為の追加のoptions"

# @param [Hash{String=>Array}]
#: ../lib/yard/server/adapter.rb:71
msgid "tag|param|libs"
msgstr ""

# YARD::Server::Adapter#add_library
#: ../lib/yard/server/adapter.rb:85
msgid "Adds a library to the {#libraries} mapping for a given library object."
msgstr ""
"与えられたライブラリオブジェクト用の{#libraries}マッピングにライブラリを追加"
"する。"

# @param [LibraryVersion] library
#: ../lib/yard/server/adapter.rb:88
msgid "a library to add"
msgstr "追加する為のライブラリ"

# @example Adding a new library to an adapter
#: ../lib/yard/server/adapter.rb:88
msgid ""
"adapter.add_library LibraryVersion.new('mylib', '1.0', '/path/to/.yardoc')"
msgstr ""

# @example
#: ../lib/yard/server/adapter.rb:88
msgid "tag|example|Adding a new library to an adapter"
msgstr "アダプターに新しいライブラリを追加する。"

# YARD::Server::Adapter#start
#: ../lib/yard/server/adapter.rb:94
msgid "Implement this method to connect your adapter to your server."
msgstr ""
"あなたのサーバーにあなたのアダプターを接続する為に、このメソッドを実装する。"

# YARD::Server::Commands::Base
#: ../lib/yard/server/commands/base.rb:7
msgid ""
"This is the base command class used to implement custom commands for\n"
"a server. A command will be routed to by the {Router} class and return\n"
"a Rack-style response."
msgstr ""
"これは、サーバー用にカスタムコマンドを実装する為に、\n"
"利用されるベースコマンドクラスである。\n"
"コマンドは、{Router}クラスによって送られ、Rackスタイルのレスポンスを返す。"

# YARD::Server::Commands::Base
#: ../lib/yard/server/commands/base.rb:11
msgid ""
"== Attribute Initializers\n"
"All attributes can be initialized via options passed into the {#initialize}\n"
"method. When creating a custom command, the {Adapter#options} will\n"
"automatically be mapped to attributes by the same name on your class."
msgstr ""
"== 初期化子の属性\n"
"全ての属性は、{#initialize}メソッドへ渡されたoptions経由でイニシャライズされ"
"る。\n"
"カスタムメソッドが作成される時、{Adapter#options}メソッドは、\n"
"あなたのクラスの属性と同じ名前で自動的にマッピングされるだろう。"

# YARD::Server::Commands::Base
#: ../lib/yard/server/commands/base.rb:16
msgid ""
"  class MyCommand < Base\n"
"    attr_accessor :myattr\n"
"  end"
msgstr ""

# YARD::Server::Commands::Base
#: ../lib/yard/server/commands/base.rb:20
msgid "  Adapter.new(libs, {:myattr => 'foo'}).start"
msgstr ""

# YARD::Server::Commands::Base
#: ../lib/yard/server/commands/base.rb:22
msgid "  # when a request comes in, cmd.myattr == 'foo'"
msgstr ""

# YARD::Server::Commands::Base
#: ../lib/yard/server/commands/base.rb:24
msgid ""
"== Subclassing Notes\n"
"To implement a custom command, override the {#run} method, not {#call}.\n"
"In your implementation, you should set the body and status for requests.\n"
"See details in the +#run+ method documentation."
msgstr ""
"== サブクラス化する時の注意\n"
"カスタムコマンドを実装するには、{#run}メソッドを上書きする({#call}メソッドで"
"はない)。\n"
"あなたの実装で、あなたがボディと、リクエスト用のステータスを設定するべきであ"
"る。\n"
"詳細は +#run+ メソッドのドキュメントを参照。"

# YARD::Server::Commands::Base
#: ../lib/yard/server/commands/base.rb:29
msgid ""
"Note that if your command deals directly with libraries, you should\n"
"consider subclassing the more specific {LibraryCommand} class instead."
msgstr ""
"次の事に留意する。あなたのコマンドが\n"
"直接ライブラリを用い処理する場合、代わりに、\n"
"サブクラス化する{LibraryCommand}クラスの詳細を考慮するべきである。"

# YARD::Server::Commands::Base#command_options
# YARD::Server::Commands::Base#command_options=
# YARD::Server::Commands::Base#adapter
# YARD::Server::Commands::Base#adapter=
# YARD::Server::Commands::Base#caching
# YARD::Server::Commands::Base#caching=
#: ../lib/yard/server/commands/base.rb:37
#: ../lib/yard/server/commands/base.rb:40
#: ../lib/yard/server/commands/base.rb:43
msgid "Basic Command and Adapter Options"
msgstr "基本的なコマンドとアダプターオプション"

# @return [Hash]
#: ../lib/yard/server/commands/base.rb:37
msgid "the options passed to the command's constructor"
msgstr "コマンドのコンストラクタに渡されたoptions"

# @return [Adapter]
#: ../lib/yard/server/commands/base.rb:40
msgid "the server adapter"
msgstr "サーバーアダプター"

# @return [Boolean]
#: ../lib/yard/server/commands/base.rb:43
msgid "whether to cache"
msgstr "キャッシュするかどうか"

# YARD::Server::Commands::Base#request
# YARD::Server::Commands::Base#request=
# YARD::Server::Commands::Base#path
# YARD::Server::Commands::Base#path=
# YARD::Server::Commands::Base#headers
# YARD::Server::Commands::Base#headers=
# YARD::Server::Commands::Base#status
# YARD::Server::Commands::Base#status=
# YARD::Server::Commands::Base#body
# YARD::Server::Commands::Base#body=
#: ../lib/yard/server/commands/base.rb:48
#: ../lib/yard/server/commands/base.rb:51
#: ../lib/yard/server/commands/base.rb:54
#: ../lib/yard/server/commands/base.rb:57
#: ../lib/yard/server/commands/base.rb:60
msgid "Attributes Set Per Request"
msgstr "リクエスト毎のグループを属性化する。"

# @return [Request]
#: ../lib/yard/server/commands/base.rb:48
msgid "request object"
msgstr "オブジェクトのリクエスト"

# @return [String]
#: ../lib/yard/server/commands/base.rb:51
msgid "the path after the command base URI"
msgstr "コマンドのベースURIの後で返す、パス"

# @return [Hash{String => String}]
#: ../lib/yard/server/commands/base.rb:54
msgid "response headers"
msgstr "ヘッダーのレスポンス"

# @return [Numeric]
#: ../lib/yard/server/commands/base.rb:57
msgid "status code. Defaults to 200 per request"
msgstr "コードの状態。デフォルトで200リクエスト毎。"

# @return [String]
#: ../lib/yard/server/commands/base.rb:60
msgid "the response body. Defaults to empty string."
msgstr "ボディのレスポンス。デフォルトでは空の文字列になる。"

# YARD::Server::Commands::Base#initialize
#: ../lib/yard/server/commands/base.rb:65
msgid ""
"Creates a new command object, setting attributes named by keys\n"
"in the options hash. After initialization, the options hash\n"
"is saved in {#command_options} for further inspection."
msgstr ""
"新しいコマンドオブジェクトを作成し、\n"
"ハッシュオプションのキーによって、名付けられた属性をセッティングする。\n"
"イニシャライズの後でハッシュのオプションは、\n"
"調査を進める為に{#command_options}メソッドの中でセーブされる。"

# YARD::Server::Commands::Base#initialize
# YARD::Server::Commands::Base#call
#: ../lib/yard/server/commands/base.rb:74
#: ../lib/yard/server/commands/base.rb:88
msgid "Instance Method Summary"
msgstr "インスタンスメソッドの概要"

# @example Creating a Command
#: ../lib/yard/server/commands/base.rb:74
msgid ""
"cmd = DisplayObjectCommand.new(:caching => true, :library => mylib)\n"
"cmd.library # => mylib\n"
"cmd.command_options # => {:caching => true, :library => mylib}"
msgstr ""

# @example
#: ../lib/yard/server/commands/base.rb:74
msgid "tag|example|Creating a Command"
msgstr "コマンドを作成する"

# @param [Hash] opts
#: ../lib/yard/server/commands/base.rb:74
msgid ""
"the options hash, saved to {#command_options}\n"
"after initialization."
msgstr ""
"ハッシュのオプション、イニシャライズされた後で、\n"
"{#command_options}にセーブされる。"

# YARD::Server::Commands::Base#call
#: ../lib/yard/server/commands/base.rb:82
msgid "The main method called by a router with a request object."
msgstr ""
"主なメソッドは、requestオブジェクトを用い\n"
"routerによって呼び出される。"

# @note
#: ../lib/yard/server/commands/base.rb:88
msgid ""
"This command should not be overridden by subclasses. Implement\n"
"the callback method {#run} instead."
msgstr ""
"このコマンドは、サブクラスによって上書きされるべきではない、\n"
"代わりにコールバックの{#run}メソッドを実装する。"

# @return [Array(Number,Hash,Array)]
#: ../lib/yard/server/commands/base.rb:88
msgid ""
"a Rack-style response\n"
"of status, headers, and body wrapped in an array."
msgstr ""
"配列でラップされた\n"
"Rackスタイルのステータス、ヘッダー、ボディのレスポンス"

# @param [Adapter Dependent]
#: ../lib/yard/server/commands/base.rb:88 ../lib/yard/server/router.rb:52
msgid "tag|param|request"
msgstr ""

# @param [Adapter Dependent] request
#: ../lib/yard/server/commands/base.rb:88 ../lib/yard/server/router.rb:52
msgid "the request object"
msgstr "リクエストするオブジェクト"

# YARD::Server::Commands::Base#run
#: ../lib/yard/server/commands/base.rb:108
msgid ""
"Subclass this method to implement a custom command. This method\n"
"should set the {#status} and {#body}, and optionally modify the\n"
"{#headers}. Note that +#status+ defaults to 200."
msgstr ""
"カスタムコマンドを実装する為にこのメソッドをサブクラス化する。\n"
"このメソッドは、{#status}と{#body}を設定するべきで、\n"
"任意で、{#headers}を変更する。\n"
"留意する事として、 +#status+ はデフォルトで200になる。"

# YARD::Server::Commands::Base#run
#: ../lib/yard/server/commands/base.rb:122
msgid "Abstract Methods"
msgstr "抽象メソッド"

# @example A custom command
#: ../lib/yard/server/commands/base.rb:122
msgid ""
"class ErrorCommand < Base\n"
"  def run\n"
"    self.body = 'ERROR! The System is down!'\n"
"    self.status = 500\n"
"    self.headers['Content-Type'] = 'text/plain'\n"
"  end\n"
"end"
msgstr ""

# @example
#: ../lib/yard/server/commands/base.rb:122
msgid "tag|example|A custom command"
msgstr "カスタムコマンド"

# YARD::Server::Commands::Base#render
#: ../lib/yard/server/commands/base.rb:131
msgid ""
"Renders a specific object if provided, or a regular template rendering\n"
"if object is not provided."
msgstr ""
"提供された場合、特定のオブジェクトを表示するか、\n"
"オブジェクトが提供されない場合、規定のテンプレートが表示される。"

# YARD::Server::Commands::Base#render
# YARD::Server::Commands::Base#cache
# YARD::Server::Commands::Base#not_found
# YARD::Server::Commands::Base#redirect
#: ../lib/yard/server/commands/base.rb:138
#: ../lib/yard/server/commands/base.rb:159
#: ../lib/yard/server/commands/base.rb:174
#: ../lib/yard/server/commands/base.rb:184
msgid "Helper Methods"
msgstr "ヘルパーメソッド"

# @todo
#: ../lib/yard/server/commands/base.rb:138
msgid ""
"This method is dependent on +#options+, it should be in {LibraryCommand}."
msgstr ""
"このメソッドは、 +#options+ メソッドに依存している。\n"
"+#options+ メソッドは {LibraryCommand} にするべきである。"

# @param [CodeObjects::Base, nil] object
#: ../lib/yard/server/commands/base.rb:138
msgid ""
"calls {CodeObjects::Base#format} if\n"
"an object is provided, or {Templates::Engine.render} if object is nil. Both\n"
"receive +#options+ as an argument."
msgstr ""
"オブジェクトが提供される場合、\n"
"{CodeObjects::Base#format}を呼び出す、\n"
"又は、オブジェクトがnilの場合\n"
"{Templates::Engine.render}を呼び出す。\n"
"両者は、引数として +#options+ メソッドを受け取る。"

# @return [String]
#: ../lib/yard/server/commands/base.rb:138
msgid "the resulting output to display"
msgstr "表示する出力結果"

# YARD::Server::Commands::Base#cache
#: ../lib/yard/server/commands/base.rb:150
msgid "Override this method to implement custom caching mechanisms for"
msgstr "カスタムキャッシュメカニズムを実装する為にこのメソッドを上書きする。"

# @example Caching to memory
#: ../lib/yard/server/commands/base.rb:159
msgid ""
"$memory_cache = {}\n"
"def cache(data)\n"
"  $memory_cache[path] = data\n"
"end"
msgstr ""

# @example
#: ../lib/yard/server/commands/base.rb:159
msgid "tag|example|Caching to memory"
msgstr "メモリーにキャッシュする"

# @see
#: ../lib/yard/server/commands/base.rb:159
msgid "tag|see|StaticCaching"
msgstr ""

# @param [String] data
#: ../lib/yard/server/commands/base.rb:159
msgid "the data to cache"
msgstr "キャッシュするデータ"

# @return [String]
#: ../lib/yard/server/commands/base.rb:159
msgid "the same cached data (for chaining)"
msgstr "同じキャッシュされたデータ(メソッドチェーン用)"

# YARD::Server::Commands::Base#not_found
#: ../lib/yard/server/commands/base.rb:171
msgid ""
"Sets the body and headers (but not status) for a 404 response. Does\n"
"nothing if the body is already set."
msgstr ""
"404レスポンス用にボディとヘッダー(しかしステータスはない)を設定する。\n"
"ボディが既に設定されている場合は何もしない。"

# YARD::Server::Commands::Base#redirect
#: ../lib/yard/server/commands/base.rb:182
msgid "Sets the headers and status code for a redirection to a given URL"
msgstr ""
"与えられたURLへのリダイレクト用にヘッダーとステータスコードを設定する。"

# @raise [FinishRequest]
#: ../lib/yard/server/commands/base.rb:184
msgid "causes the request to terminate."
msgstr "打ち切る為にリクエストする。"

# @param [String]
#: ../lib/yard/server/commands/base.rb:184
#: ../lib/yard/templates/helpers/base_helper.rb:138
msgid "tag|param|url"
msgstr ""

# @param [String] url
#: ../lib/yard/server/commands/base.rb:184
msgid "the URL to redirect to"
msgstr "リダイレクトするURL"

# YARD::Server::Commands::DisplayFileCommand
#: ../lib/yard/server/commands/display_file_command.rb:5
msgid "Displays a README or extra file."
msgstr "README 又は、追加のファイルを表示する。"

# @todo
#: ../lib/yard/server/commands/display_file_command.rb:7
msgid "Implement better support for detecting binary (image) filetypes"
msgstr "バイナリ(画像)ファイルタイプを見つける為のより良いサポートを実装する。"

# YARD::Server::Commands::DisplayObjectCommand
#: ../lib/yard/server/commands/display_object_command.rb:5
msgid "Displays documentation for a specific object identified by the path"
msgstr "パスによって識別された固有のオブジェクト用にドキュメントを表示する。"

# YARD::Server::Commands::FramesCommand
#: ../lib/yard/server/commands/frames_command.rb:5
msgid "Displays an object wrapped in frames"
msgstr "フレームの中のラップされたオブジェクトを表示する。"

# YARD::Server::Commands::LibraryCommand
#: ../lib/yard/server/commands/library_command.rb:26
msgid ""
"This is the base command for all commands that deal directly with "
"libraries.\n"
"Some commands do not, but most (like {DisplayObjectCommand}) do. If your\n"
"command deals with libraries directly, subclass this class instead.\n"
"See {Base} for notes on how to subclass a command."
msgstr ""
"これは、ライブラリを用い直接処理する全てのコマンドの為のベースコマンド。\n"
"いくつかのコマンドには、用いないが({DisplayObjectCommand}のように)大抵の事は"
"行う。\n"
"あなたのコマンドが直接ライブラリを用い処理する場合、代わりにこのクラスをサブ"
"クラス化する。\n"
"コマンドをサブクラス化する為の方法については{Base}を参照。\n"

# @return [LibraryVersion]
#: ../lib/yard/server/commands/library_command.rb:33
msgid "the object containing library information"
msgstr "ライブラリの情報含んでいるオブジェクト"

# @return [Hash{Symbol => Object}]
#: ../lib/yard/server/commands/library_command.rb:36
msgid "default options for the library"
msgstr "ライブラリ用のデフォルトのoptions"

# @return [Serializers::Base]
#: ../lib/yard/server/commands/library_command.rb:39
msgid "the serializer used to perform file linking"
msgstr "ファイルリンクを実行する為に利用されるシリアライザ"

# @return [Boolean]
#: ../lib/yard/server/commands/library_command.rb:42
msgid "whether router should route for multiple libraries"
msgstr "routerが複数のライブラリ用に送るべきかどうか"

# @return [Boolean]
#: ../lib/yard/server/commands/library_command.rb:45
msgid "whether to reparse data"
msgstr "データを再解析するかどうか"

# YARD::Server::Commands::LibraryCommand::@@library_chdir_lock
#: ../lib/yard/server/commands/library_command.rb:48
msgid "Needed to synchronize threads in {#setup_yardopts}"
msgstr "{#setup_yardopts}メソッドの中で、スレッドを同期する為の必要とされる"

# @return [LibraryCommand]
#: ../lib/yard/server/commands/library_command.rb:51
msgid "a new instance of LibraryCommand"
msgstr "LibraryCommandの新しいインスタンス"

# YARD::Server::Commands::LibraryCommand#fulldoc_template
#: ../lib/yard/server/commands/library_command.rb:127
msgid ""
"Hack to load a custom fulldoc template object that does\n"
"not do any rendering/generation. We need this to access the\n"
"generate_*_list methods."
msgstr ""

# YARD::Server::Commands::LibraryIndexCommand
#: ../lib/yard/server/commands/library_index_command.rb:5
msgid "Returns the index of libraries served by the server."
msgstr "サーバーによって提供されたライブラリのインデックスを返す"

# YARD::Server::Commands::ListCommand
#: ../lib/yard/server/commands/list_command.rb:5
msgid "Returns a list of objects of a specific type"
msgstr "特定の型のオブジェクトのリストを返す"

# YARD::Server::Commands::SearchCommand
#: ../lib/yard/server/commands/search_command.rb:5
msgid ""
"Performs a search over the objects inside of a library and returns\n"
"the results as HTML or plaintext"
msgstr ""
"ライブラリの内部オブジェクトの検索を実行し、\n"
"HTMLやプレーンテキストとして結果を返す。"

# YARD::Server::Commands::StaticFileCommand
#: ../lib/yard/server/commands/static_file_command.rb:7
msgid "Serves static content when no other router matches a request"
msgstr "リクエストにマッチする他のrouterが無い時、静的な内容を提供する。"

# YARD::Server::Commands::StaticFileCommand::STATIC_PATHS
#: ../lib/yard/server/commands/static_file_command.rb:13
msgid ""
"Defines the paths used to search for static assets. To define an\n"
"extra path, use {YARD::Server.register_static_path} rather than\n"
"modifying this constant directly. Also note that files in the\n"
"document root will always take precedence over these paths."
msgstr ""
"静的な資産用に検索に利用されるパスを定義する。\n"
"追加のパスを定義するには、直接この定数を変更するよりも\n"
"{YARD::Server.register_static_path}を利用する。\n"
"尚、ドキュメントのrootのファイルは常時これらのパスより優先する。"

# YARD::Server::Commands::StaticFileCommand#favicon?
#: ../lib/yard/server/commands/static_file_command.rb:39
msgid ""
"Return an empty favicon.ico if it does not exist so that\n"
"browsers don't complain."
msgstr ""
"favicon.icoが存在しない場合、空のfavicon.icoを返す。\n"
"その為、ブラウザに問題は発生しない。"

# YARD::Server::DocServerHelper
#: ../lib/yard/server/doc_server_helper.rb:4
msgid ""
"A module that is mixed into {Templates::Template} in order to customize\n"
"certain template methods."
msgstr ""
"テンプレートメソッドをカスタマイズする為に、\n"
"{Templates::Template}へmixinされるモジュール。"

# YARD::Server::DocServerHelper#url_for
#: ../lib/yard/server/doc_server_helper.rb:7
msgid ""
"Modifies {Templates::Helpers::HtmlHelper#url_for} to return a URL instead\n"
"of a disk location."
msgstr ""
"ディスクの上の場所の代わりにURLを返す{Templates::Helpers::HtmlHelper#url_for}"
"を変更する。"

# YARD::Server::DocServerHelper#url_for_file
#: ../lib/yard/server/doc_server_helper.rb:18
msgid ""
"Modifies {Templates::Helpers::HtmlHelper#url_for_file} to return a URL "
"instead\n"
"of a disk location."
msgstr ""
"ディスク上の場所の代わりにURLを返す{Templates::Helpers::"
"HtmlHelper#url_for_file}を変更する。"

# YARD::Server::DocServerHelper#url_for_file
#: ../lib/yard/server/doc_server_helper.rb:30
msgid ""
"Modifies {Templates::Helpers::HtmlHelper#url_for_list} to return a URL\n"
"based on the list prefix instead of a HTML filename."
msgstr ""
"HTMLファイル名の代わりにリストのプレフィックス基準のURLを返すには、\n"
"{Templates::Helpers::HtmlHelper#url_for_list} を変更する"

# YARD::CodeObjects::MethodObject#name
#: ../lib/yard/server/doc_server_helper.rb:38
msgid "Returns the frames URL for the page"
msgstr "ページ用のフレームのURLを返す"

# YARD::Server::DocServerHelper#url_for_main
#: ../lib/yard/server/doc_server_helper.rb:46
msgid ""
"Returns the main URL, first checking a readme and then linking to the index"
msgstr "メインのURLを返し、最初にreadmeをチェックしその時インデックスにリンクする。"

# YARD::Templates::Helpers::HtmlHelper#url_for_file
#: ../lib/yard/server/doc_server_helper.rb:56
#: ../lib/yard/templates/helpers/html_helper.rb:385
msgid "Returns the URL for the alphabetic index page"
msgstr "アルファベット順のインデックスのページ用にURLを返す"

# @example The base path for a library 'foo'
#: ../lib/yard/server/doc_server_helper.rb:65
msgid "base_path('docs') # => 'docs/foo'"
msgstr ""

# @example
#: ../lib/yard/server/doc_server_helper.rb:65
msgid "tag|example|The base path for a library 'foo'"
msgstr "'foo'ライブラリ用のベースパス"

# @return [String]
#: ../lib/yard/server/doc_server_helper.rb:65
msgid "the base URI for a library with an extra +path+ prefix"
msgstr "追加の +path+ のプレフィックスを用いたライブラリ用のベースURI"

# @param [String] path
#: ../lib/yard/server/doc_server_helper.rb:65
msgid "the path prefix for a base path URI"
msgstr "URIベースパス用のパスのプレフィックス"

# @return [Router]
#: ../lib/yard/server/doc_server_helper.rb:71
msgid "convenience method for accessing the router"
msgstr "routerにアクセスする為の便利メソッド"

# YARD::Server::DocServerSerializer
#: ../lib/yard/server/doc_server_serializer.rb:6
msgid ""
"A custom {Serializers::Base serializer} which returns resource URLs instead "
"of\n"
"static relative paths to files on disk."
msgstr ""
"カスタム{Serializers::Base serializer}。\n"
"ディスク上のファイルの為に静的な相対パスの代わりに、URLリソースを返す。"

# @return [DocServerSerializer]
#: ../lib/yard/server/doc_server_serializer.rb:10
msgid "a new instance of DocServerSerializer"
msgstr "DocServerSerializerの新しいインスタンス"

# YARD::Server::LibraryNotPreparedError
#: ../lib/yard/server/library_version.rb:6
msgid ""
"This exception is raised when {LibraryVersion#prepare!} fails, or discovers\n"
"that the library is not \"prepared\" to be served by"
msgstr ""
"この例外は、{LibraryVersion#prepare!}が失敗した時や、\n"
"ライブラリが提供される為に\"prepared\"されない事をかぎつけた場合、上げられ"
"る。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:10
msgid ""
"A library version encapsulates a library's documentation at a specific "
"version.\n"
"Although the version is optional, this allows for creating multiple "
"documentation\n"
"points for a specific library, each representing a unique version. The term\n"
"\"library\" used in other parts of the YARD::Server documentation refers to\n"
"objects of this class unless otherwise noted."
msgstr ""
"ライブラリバージョンは、特定のバージョンでライブラリドキュメントをカプセル化"
"する。\n"
"バージョンは任意だけれども、\n"
"これは、複数のドキュメントの特定のライブラリ用にポイントを作成する為に受入"
"れ、\n"
"それぞれ固有のバージョンを表す。\n"
"\"library\"の表現は、YARD::Serverドキュメントの他の部分で利用され、\n"
"他の方法で注意されなかった場合、このクラスのオブジェクトを参照する。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:16
msgid ""
"A library points to a location where a {#yardoc_file} is located so that\n"
"its documentation may be loaded and served. Optionally, a {#source_path} is\n"
"given to point to a location where any extra files (and {YARD::CLI::Yardoc ."
"yardopts})\n"
"should be loaded from. Both of these methods may not be known immediately,\n"
"since the yardoc file may not be built until later. Resolving the yardoc\n"
"file and source path are dependent on the specific library \"source type\" "
"used.\n"
"Source types (known as \"library source\") are discussed in detail below."
msgstr ""
"ライブラリの{#yardoc_file}メソッドの指す場所は、\n"
"そのドキュメントがロードされセーブされる場所を示される。\n"
"任意で、{#source_path}メソッドは、\n"
"追加のファイル(と{YARD::CLI::Yardoc .yardopts})が、\n"
"ロードされるべき場所のポイントを与えられる。\n"
"これらのメソッドの両方は、直ぐに理解できないかもしれない、\n"
"なぜなら、yardocファイルが最新でない場合、ビルドされないかもしれないからであ"
"る。\n"
"yardocファイルとソースパスを解決するには、\"source type\"に利用される固有のラ"
"イブラリに依存する。\n"
"ソースの型(\"library source\"として知られる)は、下の詳細の中で検討される。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:24
msgid ""
"== Using with Adapters\n"
"A list of libraries need to be passed into adapters upon creation. In\n"
"most cases, you will never do this manually, but if you use a "
"{RackMiddleware},\n"
"you will need to pass in this list yourself. To build this list of "
"libraries,\n"
"you should create a hash of library names mapped to an *Array* of "
"LibraryVersion\n"
"objects. For example:"
msgstr ""
"== アダプタと一緒に使用する\n"
"ライブラリのリストは、\n"
"作成する上でアダプターへ渡される必要がある。\n"
"大抵の場合、これを手動で行う事はしないだろう、\n"
"だが、あなたが {RackMiddleware}を利用する場合、\n"
"あなた自身が配列でこの中へ渡す必要があるだろう。\n"
"このライブラリの配列をビルドするには、\n"
"次のように、オブジェクトのLibraryVersionの*配列*に、\n"
"マップされ名付けられたライブラリのハッシュを作成すべきである。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:31
msgid ""
"  {'mylib' => [LibraryVersion.new('mylib', '1.0', ...),\n"
"               LibraryVersion.new('mylib', '2.0', ...)]}"
msgstr ""

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:34
msgid "Note that you can also use {Adapter#add_library} for convenience."
msgstr ""
"次の事に留意する。あなたは、\n"
"便利な{Adapter#add_library}メソッドを\n"
"使う事もできる。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:36
msgid "The \"array\" part is required, even for just one library version."
msgstr "\"配列\"の部分は、たった一つのライブラリのバージョンでも必要とされる。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:38
msgid ""
"== Library Sources\n"
"The {#source} method represents the library source type, ie. where the\n"
"library \"comes from\". It might come from \"disk\", or it might come from "
"a\n"
"\"gem\" (technically the disk, but a separate type nonetheless). In these\n"
"two cases, the yardoc file sits somewhere on your filesystem, though\n"
"it may also be built dynamically if it does not yet exist. This behaviour\n"
"is controlled through the {#prepare!} method, which prepares the yardoc "
"file\n"
"given a specific library source. We will see how this works in detail in\n"
"the following section."
msgstr ""
"== ライブラリのソース\n"
"{#source}メソッドはライブラリのソースのタイプを表す、\n"
"つまり、ライブラリの場所である。\n"
"それは、\"disk\"からくるかもしれない、\n"
"又は、\"gem\"からくるかもしれない。\n"
"(実際にはどちらもディスク上だが、型は別れる)\n"
"この二つのケースの場合、\n"
"yardocのファイルは、あなたのファイルシステムの何処かに置いてあり、\n"
"まだ見つかっていない場合、動的にビルドされるかもしれない。\n"
"この挙動は、{#prepare!}メソッドを通じて制御され、\n"
"与えられた固有のライブラリのソースのyardocファイルを用意する。\n"
"私達は、続くセクションの中でこの仕組みを理解するだろう。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:48
msgid ""
"== Implementing a Custom Library Source\n"
"YARD can be extended to support custom library sources in order to\n"
"build or retrieve a yardoc file at runtime from many different locations."
msgstr ""
"==　カスタムライブラリのソースを実装する\n"
"YARDはカスタムライブラリのソースをビルドするのをサポートする為、拡張され、\n"
"多くのの異なる場所から実行時にyardocファイルを読み出す。"

# YARD::Server::LibraryVersion
#: ../lib/yard/server/library_version.rb:52
msgid ""
"To implement this behaviour, two methods must be added to the +LibraryVersion"
"+\n"
"class, +#load_yardoc_from_SOURCE+ and +#source_path_for_SOURCE+. In both\n"
"cases, \"SOURCE\" represents the source type used in {#source} when "
"creating\n"
"the library object. The +#source_path_for_SOURCE+ method is called upon\n"
"creation and should return the location where the source code for the "
"library\n"
"lives. The load method is called from {#prepare!} if there is no yardoc "
"file\n"
"and should set {#yardoc_file}. Below is a full example for\n"
"implementing a custom library source, +:http+, which reads packaged .yardoc\n"
"databases from zipped archives off of an HTTP server."
msgstr ""
"この挙動を実装するには、\n"
"+LibraryVersion+クラスの +#load_yardoc_from_SOURCE+ メソッドと "
"+#source_path_for_SOURCE+ メソッドの\n"
"2つのメソッドが大抵追加される。\n"
"どちらの場合も、ライブラリのオブジェクトが作成される時の、\n"
"\"SOURCE\"は{#source}メソッドで利用されたsource typeを表す。\n"
"+#source_path_for_SOURCE+ メソッドは、作成される所で呼び出され、\n"
"存在するライブラリのソースコードの場所を返すべきである。\n"
"loadメソッドは、yardocファイルが無い場合、{#prepare!}メソッドから呼び出され"
"る。\n"
"そして、{#yardoc_file}を設定すべきである。\n"
"下は、カスタムライブラリのソースと +:http+ を実装する為の、完全な例であり、\n"
"これは、HTTPサーバー経由でzipされたアーカイブからパーケージされた.yardocデー"
"タベースを読み出す。"

# @example Implementing a Custom Library Source
#: ../lib/yard/server/library_version.rb:87
msgid ""
"# Adds the source type \"http\" for .yardoc files zipped on HTTP servers\n"
"class LibraryVersion\n"
"  def load_yardoc_from_http\n"
"    return if yardoc_file # we have the library\n"
"\n"
"    # otherwise download it in a thread and return immediately\n"
"    Thread.new do\n"
"      # zip/unzip method implementations are not shown\n"
"      download_zip_file(\"http://mysite.com/yardocs/#{self}.zip\")\n"
"      unzip_file_to(\"/path/to/yardocs/#{self}\")\n"
"      self.yardoc_file = \"/path/to/yardocs/#{self}/.yardoc\"\n"
"      self.source_path = self.yardoc_file\n"
"    end\n"
"\n"
"    # tell the server it's not ready yet (but it might be next time)\n"
"    raise LibraryNotPreparedError\n"
"  end\n"
"\n"
"  # we set this later\n"
"  def source_path_for_http; nil end\n"
"end\n"
"\n"
"# Creating a library of this source type:\n"
"LibraryVersion.new('name', '1.0', nil, :http)"
msgstr ""
"# HTTPサーバー上でzipされた.yardocファイル用にソースの型\"http\"を追加す"
"る。\n"
"class LibraryVersion\n"
"  def load_yardoc_from_http\n"
"    return if yardoc_file #ライブラリを持っている場合\n"
"\n"
"    # その他の場合、そのスレッドの中でダウンロードし直ぐに返す\n"
"    Thread.new do\n"
"      # zip/unzip メソッドの実装は示さない\n"
"      download_zip_file(\"http://mysite.com/yardocs/#{self}.zip\")\n"
"      unzip_file_to(\"/path/to/yardocs/#{self}\")\n"
"      self.yardoc_file = \"/path/to/yardocs/#{self}/.yardoc\"\n"
"      self.source_path = self.yardoc_file\n"
"    end\n"
"\n"
"    # サーバーを呼び出す準備がまだできていない場合(でも次回になるかもしれな"
"い)\n"
"    raise LibraryNotPreparedError\n"
"  end\n"
"\n"
"  # 最新のものを設定する\n"
"  def source_path_for_http; nil end\n"
"end\n"
"\n"
"#次の様に、このソースの型を指定して、ライブラリを作成する。\n"
"LibraryVersion.new('name', '1.0', nil, :http)"

# @example
#: ../lib/yard/server/library_version.rb:87
msgid "tag|example|Implementing a Custom Library Source"
msgstr "カスタムライブラリのソースを実装する"

# @return [String]
# @param [String] name
#: ../lib/yard/server/library_version.rb:89
#: ../lib/yard/server/library_version.rb:120
msgid "the name of the library"
msgstr "ライブラリの名前"

# @return [String]
#: ../lib/yard/server/library_version.rb:92
msgid "the version of the specific library"
msgstr "固有のライブラリのバージョン"

# @return [nil]
#: ../lib/yard/server/library_version.rb:98
msgid ""
"if no yardoc file exists yet. In this case, {#prepare!} will\n"
"be called on this library to build the yardoc file."
msgstr ""
"yardocファイルがまだ存在しない場合、\n"
"yardocファイルをビルドする為に、\n"
"{#prepare!}がこのライブラリ上で呼び出されるだろう。"

# @return [String]
#: ../lib/yard/server/library_version.rb:98
msgid ""
"the location of the yardoc file used to load the object\n"
"information from."
msgstr "オブジェクトの情報をロードするのに利用されるyardocファイルの場所"

# @see LibraryVersion
#: ../lib/yard/server/library_version.rb:105
#: ../lib/yard/server/library_version.rb:111
msgid ""
"LibraryVersion documentation for \"Implementing a Custom Library Source\""
msgstr ""

# @return [Symbol]
#: ../lib/yard/server/library_version.rb:105
msgid ""
"the source type representing where the yardoc should be\n"
"loaded from. Defaults are +:disk+ and +:gem+, though custom sources\n"
"may be implemented. This value is used to inform {#prepare!} about how\n"
"to load the necessary data in order to display documentation for an object."
msgstr ""
"ソースは、yardocがロードされるべき場所を表す。\n"
"デフォルトは +:disk+ と +:gem+ となるが、カスタムソースの実装もできる。\n"
"この値は、オブジェクト用のドキュメントを表示する為に\n"
"必要なデータをロードする方法について、{#prepare!}メソッドに通知する為に利用さ"
"れる。"

# @return [nil]
#: ../lib/yard/server/library_version.rb:111
msgid "if there is no source code"
msgstr "これらがソースコードでない場合"

# @return [String]
#: ../lib/yard/server/library_version.rb:111
msgid ""
"the location of the source code for a library. This\n"
"value is filled by calling +#source_path_for_SOURCE+ on this class."
msgstr ""
"ライブラリの為のソースコードの場所。\n"
"この値は、このクラスで +#source_path_for_SOURCE+ を呼び出して埋められる。"

# @return [LibraryVersion]
#: ../lib/yard/server/library_version.rb:120
msgid "a new instance of LibraryVersion"
msgstr "LibraryVersionの新しいインスタンス"

# @param [String]
#: ../lib/yard/server/library_version.rb:120
msgid "tag|param|version"
msgstr ""

# @param [String]
#: ../lib/yard/server/library_version.rb:120
msgid "tag|param|yardoc"
msgstr ""

# @param [Symbol] source
#: ../lib/yard/server/library_version.rb:120
msgid ""
"the location of the files used to build the yardoc.\n"
"Builtin source types are +:disk+ or +:gem+."
msgstr ""
"yardocをビルドする為に利用されるファイルの場所。\n"
"組み込みのソースの型は +:disk+ 又は +:gem+ 。"

# @param [String] yardoc
#: ../lib/yard/server/library_version.rb:120
msgid ""
"the location of the yardoc file, or nil if it is\n"
"generated later"
msgstr "yardocの場所、又は、最新のものが生成される場合は、nil"

# @param [String] version
#: ../lib/yard/server/library_version.rb:120
msgid ""
"the specific (usually, but not always, numeric) library\n"
"version"
msgstr ""
"固有(普通は数字で表されるが、しかし常にではない)のライブラリのバージョン"

# @param [Boolean] url_format
#: ../lib/yard/server/library_version.rb:132
msgid ""
"if true, returns the string in a URI-compatible\n"
"format (for appending to a URL). Otherwise, it is given in a more human\n"
"readable format."
msgstr ""
"trueの場合、URI-compatibleフォーマット(URL追加用)で文字列を返し、\n"
"それ以外の場合、人間が読めるフォーマットが与えられる。"

# @param [Boolean]
#: ../lib/yard/server/library_version.rb:132
msgid "tag|param|url_format"
msgstr ""

# @return [String]
#: ../lib/yard/server/library_version.rb:132
msgid "the string representation of the library."
msgstr "ライブラリの文字列表現"

# @return [Fixnum]
#: ../lib/yard/server/library_version.rb:137
msgid "used for Hash mapping."
msgstr "ハッシュのマッピング用に利用される"

# @return [Boolean]
#: ../lib/yard/server/library_version.rb:140
msgid "whether another LibraryVersion is equal to this one"
msgstr "LibraryVersionが条件と一致するかどうか"

# YARD::Server::LibraryVersion#prepare!
#: ../lib/yard/server/library_version.rb:148
msgid ""
"Prepares a library to be displayed by the server. This callback is\n"
"performed before each request on a library to ensure that it is loaded\n"
"and ready to be viewed. If any steps need to be performed prior to loading,\n"
"they are performed through this method (though they should be implemented\n"
"through the +load_yardoc_from_SOURCE+ method)."
msgstr ""
"サーバーで表示されるライブラリを準備する。\n"
"このコールバックは、ロードされその一覧を準備する事を\n"
"保証する為にライブラリ上で、個々のリクエストの前に実行される。\n"
"任意のステップが、ロードの為に先に実行する必要がある場合、\n"
"このメソッドを通じて実行される。\n"
"(けれどもこれは +load_yardoc_from_SOURCE+ メソッドを通じて実装されるべきであ"
"る。)"

# @note
#: ../lib/yard/server/library_version.rb:162
msgid ""
"You should not directly override this method. Instead, implement\n"
"+load_yardoc_from_SOURCENAME+ when implementing loading for a specific\n"
"source type. See the {LibraryVersion} documentation for \"Implementing\n"
"a Custom Library Source\""
msgstr ""
"あなたは、このメソッドを直接上書きすべきではない。\n"
"固有のソースの型用にロードを実装する時は、\n"
"代わりに、 +load_yardoc_form_SOURCENAME+ を実装する。\n"
"\"カスタムライブラリのソースの実装\"には、{LibraryVersion}ドキュメントを参"
"照。"

# @raise [LibraryNotPreparedError]
#: ../lib/yard/server/library_version.rb:162
msgid ""
"if the library is not ready to be\n"
"displayed. Usually when raising this error, you would simultaneously\n"
"begin preparing the library for subsequent requests, although this\n"
"is not necessary."
msgstr ""
"ライブラリが表示する為の準備ができていない場合、\n"
"通常このエラーを上げる時は、\n"
"次のリクエストの為のライブラリの準備が一斉に始まる。\n"
"なので、これは、必須ではない。"

# @return [Gem::Specification]
#: ../lib/yard/server/library_version.rb:171
msgid ""
"a gemspec object for a given library. Used\n"
"for :gem source types."
msgstr ""
"与えられたライブラリ用のgemspecオブジェクト。\n"
":gemのソースの型用に利用される。"

# @return [nil]
#: ../lib/yard/server/library_version.rb:171
msgid "if there is no installed gem for the library"
msgstr "これらが、ライブラリ用のgemをインストールされない場合"

# YARD::Server::LibraryVersion#load_yardoc_from_disk
#: ../lib/yard/server/library_version.rb:179
msgid ""
"Called when a library of source type \"disk\" is to be prepared. In this\n"
"case, the {#yardoc_file} should already be set, so nothing needs to be\n"
"done."
msgstr ""
"ソースの型が\"disk\"のライブラリの時呼び出され、準備する。\n"
"この場合、{#yardoc_file}は、既に設定されるべきであり、\n"
"何も必要としない。"

# YARD::Server::LibraryVersion#load_yardoc_from_gem
#: ../lib/yard/server/library_version.rb:186
msgid ""
"Called when a library of source type \"gem\" is to be prepared. In this\n"
"case, the {#yardoc_file} needs to point to the correct location for\n"
"the installed gem. The yardoc file is built if it has not been done."
msgstr ""
"ソースの型が\"gem\"のライブラリの時呼び出され、準備する。\n"
"この場合、{#yardoc_file}は\n"
"インストールされたgemの正規の場所を必要とする。\n"
"yardocファイルを持っていない場合は、ビルドされる。"

# @raise [LibraryNotPreparedError]
#: ../lib/yard/server/library_version.rb:191
msgid ""
"if the gem does not have an existing\n"
"yardoc file."
msgstr "gemがyardocファイルに存在しない場合"

# @return [String]
#: ../lib/yard/server/library_version.rb:210
msgid "the source path for a disk source"
msgstr "ディスクのソース用のソースのパス"

# @return [String]
#: ../lib/yard/server/library_version.rb:215
msgid "the source path for a gem source"
msgstr "gemのソース用のソースのパス"

# YARD::Server::RackMiddleware
#: ../lib/yard/server/rack_adapter.rb:7
msgid ""
"This class wraps the {RackAdapter} into a Rack-compatible middleware.\n"
"See {#initialize} for a list of options to pass via Rack's +#use+ method."
msgstr ""
"このクラスは、Rackと互換性のあるミドルウェアの{RackAdapter}をラップする。\n"
"Rack の +#use+ メソッド経由で渡す為のoptionsのリストは、{#initialize}メソッド"
"を参照。\n"

# @note
#: ../lib/yard/server/rack_adapter.rb:16
msgid ""
"You must pass a +:libraries+ option to the RackMiddleware via +#use+. To\n"
"read about how to return a list of libraries, see {LibraryVersion} or look\n"
"at the example below."
msgstr ""
"あなたは +#use+ メソッド経由でRackWiddlewareに +:libraries+ のオプションを渡"
"さなければならない。\n"
"librariesのリストを返す為の方法について読むには、{LibraryVersion}又は、下の例"
"を参照。"

# @example Using the RackMiddleware in a Rack application
#: ../lib/yard/server/rack_adapter.rb:16
msgid ""
"libraries = {:mylib => [YARD::Server::LibraryVersion.new('mylib', nil, '/"
"path/to/.yardoc')]}\n"
"use YARD::Server::RackMiddleware, :libraries => libraries"
msgstr ""

# @example
#: ../lib/yard/server/rack_adapter.rb:16
msgid "tag|example|Using the RackMiddleware in a Rack application"
msgstr "RackアプリケーションでRackミドルウェアを使用する。"

# YARD::Server::RackMiddleware#initialize
#: ../lib/yard/server/rack_adapter.rb:18
msgid "Creates a new Rack-based middleware for serving YARD documentation."
msgstr ""
"YARDドキュメントに提供する為に、\n"
"新しくRackが基本となるミドルウェアを作成する。"

# @return [RackMiddleware]
#: ../lib/yard/server/rack_adapter.rb:26
msgid "a new instance of RackMiddleware"
msgstr "Rackミドルウェアの新しいインスタンス"

# @param
#: ../lib/yard/server/rack_adapter.rb:26
msgid "tag|param|app"
msgstr ""

# @param app
#: ../lib/yard/server/rack_adapter.rb:26
msgid "the next Rack middleware in the stack"
msgstr "スタックの中の次のRackミドルウェア"

# YARD::Server::RackAdapter
#: ../lib/yard/server/rack_adapter.rb:43
msgid ""
"A server adapter to respond to requests using the Rack server infrastructure."
msgstr ""
"Rackサーバーのインフラによって、リクエストに答える為のサーバーアダプター。"

# YARD::Server::RackAdapter#call
#: ../lib/yard/server/rack_adapter.rb:47
msgid "Responds to Rack requests and builds a response with the {Router}."
msgstr "Rackのリクエストにレスポンスし、{Router}を用いレスポンスをビルドする。"

# @return [Array(Numeric,Hash,Array)]
# @return [Array(Number,Hash,Array)]
#: ../lib/yard/server/rack_adapter.rb:48 ../lib/yard/server/router.rb:100
#: ../lib/yard/server/static_caching.rb:33
msgid "the Rack-style response"
msgstr "Rackスタイルのレスポンス"

# YARD::Server::RackAdapter#start
#: ../lib/yard/server/rack_adapter.rb:59
msgid ""
"Starts the +Rack::Server+. This method will pass control to the server and\n"
"block."
msgstr ""
"+Rack::Server+ をスタートする。\n"
"このメソッドは、サーバーとブロックに制御を渡すだろう。"

# YARD::Server::Router
#: ../lib/yard/server/router.rb:4
msgid ""
"A router class implements the logic used to recognize a request for a "
"specific\n"
"URL and run specific {Commands::Base commands}."
msgstr ""
"routerクラスは、特定のURL用のリクエストを認識する為に利用されたロジックを実装"
"し、\n"
"特定の{Commands::Base commands}を起動する。"

# YARD::Server::Router
#: ../lib/yard/server/router.rb:7
msgid ""
"== Subclassing Notes\n"
"To create a custom router, subclass this class and pass it into the adapter\n"
"options through {Adapter#initialize} or by directly modifying "
"{Adapter#router}."
msgstr ""
"== サブクラス化する時の注意\n"
"カスタムrouterを作成するには、\n"
"このクラスをサブクラス化し、\n"
"{Adapter#initialize}を通じてアダプタオプションへ渡すか、\n"
"直接{Adapter#router}を変更する。"

# YARD::Server::Router
#: ../lib/yard/server/router.rb:11
msgid ""
"The most general customization is to change the URL prefixes recognized by\n"
"routing, which can be done by overriding {#docs_prefix}, {#list_prefix}\n"
"and {#search_prefix}."
msgstr ""
"多くの場合、カスタマイズは、\n"
"routerで認識されるURLのプレフィックスを変更する為である。\n"
"{#docs_prefix}、{#list_prefix}、{#search_prefix}メソッドを上書きする事で、\n"
"実現できる。"

# YARD::Server::Router
#: ../lib/yard/server/router.rb:15
msgid ""
"== Implementing Custom Caching\n"
"By default, the Router class performs static disk-based caching on all\n"
"requests through the +#check_static_cache+. To override this behaviour,\n"
"or create your own caching mechanism, mixin your own custom module with\n"
"this method implemented as per {StaticCaching#check_static_cache}."
msgstr ""
"== カスタムキャッシュを実装する\n"
"デフォルトで、Routerクラスは、\n"
"+#check_static_cache+ を通じて\n"
"全てのリクエストで静的なディスクベースのキャッシュを実行する。\n"
"この挙動を上書きしたり、あなた自身でキャッシュのメカニズムを作成するには、\n"
"{StaticCaching#check_static_cache}メソッドとして実装されたこのメソッドを用い"
"て\n"
"あなた自身のカスタムモジュールをmixinする。"

# @example Creating a subclassed router
#: ../lib/yard/server/router.rb:30
msgid ""
"# Adds 'my' to all routing prefixes\n"
"class MyRouter < YARD::Server::Router\n"
"  def docs_prefix; 'mydocs' end\n"
"  def list_prefix; 'mylist' end\n"
"  def search_prefix; 'mysearch' end\n"
"end\n"
"\n"
"# Using it:\n"
"WebrickAdapter.new(libraries, :router => MyRouter).start"
msgstr ""

# @example
#: ../lib/yard/server/router.rb:30
msgid "tag|example|Creating a subclassed router"
msgstr "サブクラス化されたrouterを作成する"

# @return [Adapter Dependent]
#: ../lib/yard/server/router.rb:35
msgid "the request data coming in with the routing"
msgstr "routerを用いやってくるデータのリクエスト"

# @return [Adapter]
#: ../lib/yard/server/router.rb:38
msgid "the adapter used by the router"
msgstr "routerによって利用されたアダプタ"

# YARD::Server::Router#initialize
#: ../lib/yard/server/router.rb:41
msgid "Creates a new router for a specific adapter"
msgstr "特定のアダプタ用に新しいrouterを作成する"

# @return [Router]
#: ../lib/yard/server/router.rb:43
msgid "a new instance of Router"
msgstr "Routerの新しいインスタンス"

# @param [Adapter]
#: ../lib/yard/server/router.rb:43
msgid "tag|param|adapter"
msgstr ""

# @param [Adapter] adapter
#: ../lib/yard/server/router.rb:43
msgid "the adapter to route requests to"
msgstr "リクエストを送る為のアダプタ"

# YARD::Server::Router#call
#: ../lib/yard/server/router.rb:48
msgid ""
"Perform routing on a specific request, serving the request as a static\n"
"file through {Commands::StaticFileCommand} if no route is found."
msgstr ""
"特定のリクエストでrouterを実行し、\n"
"routeが見つからない場合、\n"
"{Commands::StaticFileCommand}を通じて、\n"
"静的なファイルとしてリクエストを提供する。"

# @return [Array(Number,Hash,Array)]
#: ../lib/yard/server/router.rb:52
msgid "the Rack-style server response data"
msgstr "Rackスタイルサーバーが返すデータ"

# YARD::Server::Router#docs_prefix
# YARD::Server::Router#list_prefix
# YARD::Server::Router#search_prefix
#: ../lib/yard/server/router.rb:64 ../lib/yard/server/router.rb:67
#: ../lib/yard/server/router.rb:70
msgid "Route Prefixes"
msgstr "プレフィックスを送る"

# @return [String]
#: ../lib/yard/server/router.rb:64
msgid "the URI prefix for all object documentation requests"
msgstr "全てのオブジェクトのドキュメントのリクエスト用のURIのプレフィックス"

# @return [String]
#: ../lib/yard/server/router.rb:67
msgid "the URI prefix for all class/method/file list requests"
msgstr ""
"全てのクラス/メソッド/ファイルのリストのリクエスト用のURIのプレフィックス"

# @return [String]
#: ../lib/yard/server/router.rb:70
msgid "the URI prefix for all search requests"
msgstr "全ての検索リクエスト用のURIプレフィックス"

# YARD::Server::Router#parse_library_from_path
# YARD::Server::Router#route
# YARD::Server::Router#route_docs
# YARD::Server::Router#route_index
# YARD::Server::Router#route_list
# YARD::Server::Router#route_search
#: ../lib/yard/server/router.rb:77 ../lib/yard/server/router.rb:100
#: ../lib/yard/server/router.rb:122 ../lib/yard/server/router.rb:140
#: ../lib/yard/server/router.rb:151 ../lib/yard/server/router.rb:159
msgid "Routing Methods"
msgstr "メソッドを送る"

# @return [Array(LibraryVersion, Array)]
#: ../lib/yard/server/router.rb:77
msgid ""
"the library followed\n"
"by the rest of the path components in the request path. LibraryVersion\n"
"will be nil if no matching library was found."
msgstr ""
"ライブラリは、リクエストのパスの中で\n"
"そのパスの構成の残りによってフォローされる。\n"
"見つかったライブラリが一致しなかった場合、\n"
"LibraryVersionは、nilになるだろう。"

# YARD::Server::Router#route
#: ../lib/yard/server/router.rb:96
msgid ""
"Performs routing algorithm to find which prefix is called, first\n"
"parsing out library name/version information."
msgstr ""
"プレフィックスを検索する為のrouterアルゴリズムを実行する。\n"
"ライブラリのname/version情報の出力を最初に解析する。"

# @return [nil]
#: ../lib/yard/server/router.rb:100
msgid "if no route is matched"
msgstr "route処理がマッチしない場合"

# YARD::Server::Router#route_docs
#: ../lib/yard/server/router.rb:119
msgid "Routes requests from {#docs_prefix} and calls the appropriate command"
msgstr "{#docs_prefix}からリクエストを送り、適当なコマンドを呼び出す。"

# @param [Array] paths
#: ../lib/yard/server/router.rb:122
msgid "path components (split by '/')"
msgstr "パスの構成('/'区切り)"

# @param [LibraryVersion] library
#: ../lib/yard/server/router.rb:122
msgid "the library to route for"
msgstr "routeする為のライブラリ"

# YARD::Server::Router#route_index
#: ../lib/yard/server/router.rb:139
msgid "Routes for the index of a library / multiple libraries"
msgstr "単一のライブラリ/複数のライブラリのインデックス用に送る"

# YARD::Server::Router#route_list
#: ../lib/yard/server/router.rb:149
msgid "Routes requests from {#list_prefix} and calls the appropriate command"
msgstr "{#list_prefix}メソッドからリクエストを送り、適切なコマンドを呼び出す"

# YARD::Server::Router#route_search
#: ../lib/yard/server/router.rb:157
msgid "Routes requests from {#search_prefix} and calls the appropriate command"
msgstr "{#search_prefix}メソッドからリクエストを送り、適切なコマンドを呼び出す"

# YARD::Server::Router#final_options
#: ../lib/yard/server/router.rb:167
msgid ""
"Adds extra :library/:path option keys to the adapter options.\n"
"Use this method when passing options to a command."
msgstr ""
"アダプタオプションに追加の:library/:pathオプションのキーを追加する。\n"
"このメソッドは、コマンドがオプションを解析する時に利用する。"

# YARD::Server::Router#final_options
#: ../lib/yard/server/router.rb:171
msgid "Utility Methods"
msgstr "ユーティリティメソッド"

# @return [Hash]
#: ../lib/yard/server/router.rb:171
msgid "finalized options"
msgstr "終わらせるオプション"

# YARD::Server::StaticCaching
#: ../lib/yard/server/static_caching.rb:4
msgid "Implements static caching for requests."
msgstr "リクエスト用の静的なキャッシュを実装する"

# @see Router
#: ../lib/yard/server/static_caching.rb:6
msgid "Router documentation for \"Caching\""
msgstr ""

# @see
#: ../lib/yard/server/static_caching.rb:6
msgid "tag|see|Router"
msgstr ""

# YARD::Server::StaticCaching#check_static_cache
#: ../lib/yard/server/static_caching.rb:8
msgid ""
"Called by a router to return the cached object. By default, this\n"
"method performs disk-based caching. To perform other forms of caching,\n"
"implement your own +#check_static_cache+ method and mix the module into\n"
"the Router class."
msgstr ""
"キャッシュされたオブジェクトを返す為にrouterによって呼び出される。\n"
"デフォルトで、このメソッドは、ディスクベースのキャッシュを実行する。\n"
"キャッシュの他の形式を実行するには、\n"
"あなた自身が +#check_static_cache+ メソッドを実装し、\n"
"Routerクラスへモジュールをmixinする。"

# YARD::Server::StaticCaching#check_static_cache
#: ../lib/yard/server/static_caching.rb:13
msgid ""
"Note that caching does not occur here. This method simply checks for\n"
"the existence of cached data. To actually cache a response, see\n"
"{Commands::Base#cache}."
msgstr ""
"次の事に留意する。キャッシュは、ここでは発生しない。\n"
"このメソッドは、単純にキャッシュデータの存在をチェックする。\n"
"実際にレスポンスをキャッシュするには、{Commands::Base#cache}を参照する。"

# @return [nil]
#: ../lib/yard/server/static_caching.rb:33
msgid "if no cache is available and routing should continue"
msgstr ""
"キャッシュが利用できない場合、nilを返す。\n"
"routerは継続すべきである。"

# @example Implementing In-Memory Cache Checking
#: ../lib/yard/server/static_caching.rb:33
msgid ""
"module MemoryCaching\n"
"  def check_static_cache\n"
"    # $memory_cache is filled by {Commands::Base#cache}\n"
"    cached_data = $memory_cache[request.path]\n"
"    if cached_data\n"
"      [200, {'Content-Type' => 'text/html'}, [cached_data]]\n"
"    else\n"
"      nil\n"
"    end\n"
"  end\n"
"end\n"
"\n"
"class YARD::Server::Router; include MemoryCaching; end"
msgstr ""

# @example
#: ../lib/yard/server/static_caching.rb:33
msgid "tag|example|Implementing In-Memory Cache Checking"
msgstr "メモリ内のキャッシュのチェックを実装する"

# @see
#: ../lib/yard/server/static_caching.rb:33
msgid "tag|see|Commands::Base#cache"
msgstr ""

# YARD::Server::WebrickAdapter
#: ../lib/yard/server/webrick_adapter.rb:6
msgid "The main adapter to initialize a WEBrick server."
msgstr "WEBrickサーバーをイニシャライズする為の主なアダプタ"

# YARD::Server::WebrickAdapter#start
#: ../lib/yard/server/webrick_adapter.rb:8
msgid ""
"Initializes a WEBrick server. If {Adapter#server_options} contains a\n"
"+:daemonize+ key set to true, the server will be daemonized."
msgstr ""
"WEBrickサーバーをイニシャライズする。\n"
"{Adapter#server_options}の内容の\n"
"+:daemonize+ キーにtrueが設定された場合、\n"
"サーバーは、デーモンで起動される。"

# YARD::Server::WebrickServlet
#: ../lib/yard/server/webrick_adapter.rb:19
msgid "The main WEBrick servlet implementation, accepting only GET requests."
msgstr ""
"主にWEBrickサーブレットの実装、取得するリクエストだけ受入れる。\n"
"(servlet:サーバー側で動くプログラムの事)"

# @return [WebrickServlet]
#: ../lib/yard/server/webrick_adapter.rb:22
msgid "a new instance of WebrickServlet"
msgstr "WebrickServletの新しいインスタンス"

# YARD::Tags::DefaultFactory#parse_tag
#: ../lib/yard/tags/default_factory.rb:8
msgid "Parses tag text and creates a new tag with descriptive text"
msgstr "タグテキストを解析し、説明文と共に新しいタグを作成する。"

# @return [Tag]
#: ../lib/yard/tags/default_factory.rb:12
msgid "a tag object with the tag_name and text values filled"
msgstr "タグ名やテキストの入ったタグオブジェクト"

# @param tag_name
#: ../lib/yard/tags/default_factory.rb:12
#: ../lib/yard/tags/default_factory.rb:21
#: ../lib/yard/tags/default_factory.rb:32
#: ../lib/yard/tags/default_factory.rb:44
#: ../lib/yard/tags/default_factory.rb:56
msgid "the name of the tag to parse"
msgstr "解析の為のタグの名前"

# @param [String] text
#: ../lib/yard/tags/default_factory.rb:12
#: ../lib/yard/tags/default_factory.rb:21
#: ../lib/yard/tags/default_factory.rb:32
#: ../lib/yard/tags/default_factory.rb:44
#: ../lib/yard/tags/default_factory.rb:56
#: ../lib/yard/tags/default_factory.rb:98
msgid "the raw tag text"
msgstr "元のタグテキスト"

# YARD::Tags::DefaultFactory#parse_tag_with_name
#: ../lib/yard/tags/default_factory.rb:17
msgid ""
"Parses tag text and creates a new tag with a key name and descriptive text"
msgstr "タグテキストを解析し、キー名と説明文と共に新しいタグを作成する。"

# @return [Tag]
#: ../lib/yard/tags/default_factory.rb:21
msgid "a tag object with the tag_name, name and text values filled"
msgstr "タグ名,キー名,テキストの入ったタグオブジェクト"

# YARD::Tags::DefaultFactory#parse_tag_with_types
#: ../lib/yard/tags/default_factory.rb:27
msgid ""
"Parses tag text and creates a new tag with formally declared types and\n"
"descriptive text"
msgstr ""
"タグテキストを解析し、形式的に宣言される型と説明文と共に新しいタグを作成す"
"る。"

# @return [Tag]
#: ../lib/yard/tags/default_factory.rb:32
msgid "a tag object with the tag_name, types and text values filled"
msgstr "タグ名,型,テキストを含んだタグオブジェクト"

# YARD::Tags::DefaultFactory#parse_tag_with_types_and_name
#: ../lib/yard/tags/default_factory.rb:39
msgid ""
"Parses tag text and creates a new tag with formally declared types, a key\n"
"name and descriptive text"
msgstr ""
"タグタキストを解析し,形式的に宣言された型と共に新しいタグを作成する,\n"
"キー名と説明文。"

# @return [Tag]
#: ../lib/yard/tags/default_factory.rb:44
#: ../lib/yard/tags/default_factory.rb:56
msgid "a tag object with the tag_name, name, types and text values filled"
msgstr "タグ名,キー名,型,テキストの入ったタグオブジェクト"

# YARD::Tags::DefaultFactory#parse_tag_with_types_and_name
#: ../lib/yard/tags/default_factory.rb:51
msgid ""
"Parses tag text and creates a new tag with formally declared types, a title\n"
"on the first line and descriptive text"
msgstr ""
"タグテキストを解析し、新しいタグを作成する。\n"
"形式的に宣言された型、最初の行のタイトル、説明文を用いる。"

# YARD::Tags::DefaultFactory#extract_name_from_text
#: ../lib/yard/tags/default_factory.rb:94
msgid ""
"Extracts the name from raw tag text returning the name and remaining value"
msgstr "元のタグテキストの返す名前から名前を抽出する。又、残りの値は残す。"

# @return [Array]
#: ../lib/yard/tags/default_factory.rb:98
msgid ""
"an array holding the name as the first element and the\n"
"value as the second element"
msgstr "最初の要素は名前を含み、次の要素は残りの値を含んだ配列"

# YARD::Tags::DefaultFactory#extract_types_and_name_from_text
#: ../lib/yard/tags/default_factory.rb:116
msgid ""
"Parses a [], <>, {} or () block at the beginning of a line of text\n"
"into a list of comma delimited values."
msgstr ""
"テキスト行の先頭で[],<>,{},()ブロックのカンマで区切られた値の配列の中を解析す"
"る\n"

# @example 
#: ../lib/yard/tags/default_factory.rb:125
msgid ""
"obj.parse_types('[String, Array, nil]') # => [nil, ['String', "
"'Array', 'nil'], \"\"]\n"
"obj.parse_types('b A string') # => ['b', ['String'], 'A string']"
msgstr ""

# @return [Array(String, Array, String)]
#: ../lib/yard/tags/default_factory.rb:125
msgid ""
"the text before the type\n"
"list (or nil), followed by the type list parsed into an array of\n"
"strings, followed by the text following the type list."
msgstr ""
"型の配列の前のテキスト(又はnil)、\n"
"続いて、文字列の配列の中を解析されることによって処理される,型のリスト,\n"
"続いて、型のリストをフォローする事によって処理される,テキストを含んだ配列"

# YARD::Tags::DefaultTag#defaults
#: ../lib/yard/tags/default_tag.rb:5
msgid "Returns the value of attribute defaults"
msgstr "デフォルトの属性の値を返す"

# @return [DefaultTag]
#: ../lib/yard/tags/default_tag.rb:6
msgid "a new instance of DefaultTag"
msgstr "DefaultTagクラスの新しいインスタンス"

# YARD::Tags::Directive
#: ../lib/yard/tags/directives.rb:6
msgid ""
"The base directive class. Subclass this class to create a custom\n"
"directive, registering it with {Library.define_directive}. Directive\n"
"classes are executed via the {#call} method, which perform all directive\n"
"processing on the object."
msgstr ""

# YARD::Tags::Directive
#: ../lib/yard/tags/directives.rb:11
msgid ""
"If processing occurs within a handler, the {#handler} attribute is\n"
"available to access more information about parsing context and state.\n"
"Handlers are only available when parsing from {Parser::SourceParser},\n"
"not when parsing directly from {DocstringParser}. If the docstring is\n"
"attached to an object declaration, {#object} will be set and available\n"
"to modify the generated code object directly. Note that both of these\n"
"attributes may be nil, and directives should test their existence\n"
"before attempting to use them."
msgstr ""

# @abstract
#: ../lib/yard/tags/directives.rb:22
msgid "Subclasses should implement {#call}."
msgstr ""

# @see
#: ../lib/yard/tags/directives.rb:22
msgid "tag|see|Library.define_directive"
msgstr ""

# @return [Tag]
#: ../lib/yard/tags/directives.rb:24
msgid "the meta-data tag containing data input to the directive"
msgstr ""

# YARD::Tags::Directive#expanded_text
# YARD::Tags::Directive#expanded_text=
#: ../lib/yard/tags/directives.rb:27
msgid ""
"Set this field to replace the directive definition inside of a docstring\n"
"with arbitrary text. For instance, the {MacroDirective} uses this field\n"
"to expand its macro data in place of the call to a +@!macro+."
msgstr ""

# @return [nil]
#: ../lib/yard/tags/directives.rb:33
msgid "if no expansion should take place for this directive"
msgstr ""

# @return [String]
#: ../lib/yard/tags/directives.rb:33
msgid ""
"the text to expand in the original docstring in place\n"
"of this directive definition."
msgstr ""

# @return [DocstringParser]
#: ../lib/yard/tags/directives.rb:37
msgid ""
"the parser that is parsing all tag\n"
"information out of the docstring"
msgstr ""

# @return [CodeObjects::Base]
#: ../lib/yard/tags/directives.rb:42
msgid ""
"the object the parent docstring is\n"
"attached to. May be nil."
msgstr ""
"オブジェクトを返す、親のdocstringがオブジェクトに追加される。\n"
"nilになるかもしれない。"

# @return [Handlers::Base, nil]
#: ../lib/yard/tags/directives.rb:48
msgid ""
"the handler object the docstring parser\n"
"might be attached to. May be nil. Only available when parsing\n"
"through {Parser::SourceParser}."
msgstr ""

# @return [Section]
#: ../lib/yard/tags/directives.rb:54
msgid "a new instance of Directive"
msgstr "ディレクティブの新しいインスタンス"

# @param [Symbol]
# @param [#to_s]
#: ../lib/yard/tags/directives.rb:54 ../lib/yard/tags/library.rb:100
#: ../lib/yard/tags/library.rb:158
msgid "tag|param|tag"
msgstr ""

# @param [OptionParser] opts
#: ../lib/yard/tags/directives.rb:54
msgid "the docstring parser object"
msgstr "docstringのパーサーオブジェクト"

# @return [Adapter Dependent]
#: ../lib/yard/tags/directives.rb:54
msgid "the meta-data tag containing all input to the docstring"
msgstr "メタデータタグ、docstringに全て入力するデータを含んでいる"

# YARD::Tags::Directive#call
#: ../lib/yard/tags/directives.rb:63
msgid ""
"Called when processing the directive. Subclasses should implement\n"
"this method to perform all functionality of the directive."
msgstr ""

# YARD::Parser::SourceParser.before_parse_list
# YARD::Parser::SourceParser.after_parse_list
# YARD::Parser::SourceParser.before_parse_file
# YARD::Parser::SourceParser.after_parse_file
# YARD::Parser::SourceParser.before_parse_list_callbacks
# YARD::Parser::SourceParser.after_parse_list_callbacks
# YARD::Parser::SourceParser.before_parse_file_callbacks
# YARD::Parser::SourceParser.after_parse_file_callbacks
#: ../lib/yard/tags/directives.rb:68 ../lib/yard/tags/directives.rb:73
#: ../lib/yard/tags/directives.rb:97 ../lib/yard/tags/directives.rb:98
#: ../lib/yard/tags/directives.rb:120 ../lib/yard/tags/directives.rb:121
#: ../lib/yard/tags/directives.rb:250 ../lib/yard/tags/directives.rb:251
#: ../lib/yard/tags/directives.rb:263 ../lib/yard/tags/directives.rb:268
#: ../lib/yard/tags/directives.rb:273 ../lib/yard/tags/directives.rb:278
#: ../lib/yard/tags/directives.rb:282 ../lib/yard/tags/directives.rb:298
#: ../lib/yard/tags/directives.rb:318 ../lib/yard/tags/directives.rb:350
#: ../lib/yard/tags/directives.rb:351 ../lib/yard/tags/directives.rb:353
#: ../lib/yard/tags/directives.rb:355 ../lib/yard/tags/directives.rb:363
#: ../lib/yard/tags/directives.rb:372 ../lib/yard/tags/directives.rb:376
#: ../lib/yard/tags/directives.rb:385 ../lib/yard/tags/directives.rb:393
#: ../lib/yard/tags/directives.rb:433 ../lib/yard/tags/directives.rb:434
#: ../lib/yard/tags/directives.rb:442 ../lib/yard/tags/directives.rb:448
#: ../lib/yard/tags/directives.rb:458 ../lib/yard/tags/directives.rb:485
#: ../lib/yard/tags/directives.rb:489 ../lib/yard/tags/directives.rb:518
#: ../lib/yard/tags/directives.rb:519 ../lib/yard/tags/directives.rb:552
#: ../lib/yard/tags/directives.rb:553 ../lib/yard/tags/directives.rb:582
#: ../lib/yard/tags/directives.rb:583
msgid "Parser callbacks"
msgstr "パーサーのコールバック"

# YARD::Server::Adapter#start
#: ../lib/yard/tags/directives.rb:68
msgid ""
"implement this method to perform all data processing for\n"
"the directive."
msgstr "ディレクディブ用に全てのデータ処理を実行する為にこのメソッドを実装する"

# YARD::Tags::Directive#after_parse
#: ../lib/yard/tags/directives.rb:71
msgid ""
"Called after parsing all directives and tags in the docstring. Used\n"
"to perform any cleanup after all directives perform their main task."
msgstr ""

# YARD::Tags::EndGroupDirective
#: ../lib/yard/tags/directives.rb:79
msgid ""
"Ends a group listing definition. Group definition automatically end\n"
"when class or module blocks are closed, and defining a new group overrides\n"
"the last group definition, but occasionally you need to end the current\n"
"group to return to the default listing. Use {tag:!group} to begin a\n"
"group listing."
msgstr ""

# @example 
#: ../lib/yard/tags/directives.rb:97
msgid ""
"class Controller\n"
"  # @!group Callbacks\n"
"\n"
"  def before_filter; end\n"
"  def after_filter; end\n"
"\n"
"  # @!endgroup\n"
"\n"
"  def index; end\n"
"end"
msgstr ""

# @see
#: ../lib/yard/tags/directives.rb:97
msgid "tag|see|tag:!group"
msgstr ""

# YARD::Tags::GroupDirective
#: ../lib/yard/tags/directives.rb:105
msgid ""
"Defines a group listing. All methods (and attributes) seen after this\n"
"directive are placed into a group with the given description as the\n"
"group name. The group listing is used by templates to organize methods\n"
"and attributes into respective logical groups. To end a group listing\n"
"use {tag:!endgroup}."
msgstr ""

# @example 
#: ../lib/yard/tags/directives.rb:120
msgid ""
"# @!group Callbacks\n"
"\n"
"def before_filter; end\n"
"def after_filter; end"
msgstr ""

# @note
#: ../lib/yard/tags/directives.rb:120
msgid ""
"A group definition only applies to the scope it is defined in.\n"
"If a new class or module is opened after the directive, this directive\n"
"will not apply to methods in that class or module."
msgstr ""

# @see
#: ../lib/yard/tags/directives.rb:120
msgid "tag|see|tag:!endgroup"
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:128
msgid ""
"Defines a block of text to be expanded whenever the macro is called by name\n"
"in subsequent docstrings. The macro data can be any arbitrary text data, be\n"
"it regular documentation, meta-data tags or directives."
msgstr ""

#: ../lib/yard/tags/directives.rb:132
msgid "== Defining a Macro"
msgstr "== マクロを定義する"

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:134
msgid ""
"A macro must first be defined in order to be used. Note that a macro is "
"also\n"
"expanded upon definition if it defined on an object (the docstring of a\n"
"method, class, module or constant object as opposed to a free standing\n"
"comment). To define a macro, use the \"new\" or \"attach\" identifier in "
"the\n"
"types specifier list. A macro will also automatically be created if an\n"
"indented macro data block is given, so the keywords are not strictly needed."
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:141
msgid "=== Anonymous Macros"
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:143
msgid ""
"In addition to standard named macros, macros can be defined anonymously if\n"
"no name is given. In this case, they can not be re-used in future "
"docstrings,\n"
"but they will expand in the first definition. This is useful when needing\n"
"to take advantage of the macro expansion variables (described below)."
msgstr ""

#: ../lib/yard/tags/directives.rb:148
msgid "== Using a Macro"
msgstr "== マクロを使う"

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:150
msgid ""
"To re-use a macro in another docstring after it is defined, simply use\n"
"@!macro the_name with no indented block of macro data. The "
"resulting\n"
"data will be expanded in place."
msgstr ""

#: ../lib/yard/tags/directives.rb:154
msgid "== Attaching a Macro to a DSL Method"
msgstr "== DSL（Class）メソッドにマクロを追加する"

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:156
msgid ""
"Macros can be defined to auto-expand on DSL-style class method calls. To\n"
"define a macro to be auto expanded in this way, use the \"attach\" keyword\n"
"in the type specifier list (\"new\" is implied)."
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:160
msgid ""
"Attached macros can also be attached directly on the class method "
"declaration\n"
"that provides the DSL method to its subclasses. The syntax in either case\n"
"is the same."
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:164
msgid "== Macro Expansion Variables"
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:166
msgid ""
"In the case of using macros on DSL-style method calls, a number of "
"expansion\n"
"variables can be used for interpolation inside of the macro data. The "
"variables,\n"
"similar in syntax to Ruby's global variables, are as follows:"
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:170
msgid ""
"* $0 - the method name being called\n"
"* $1, $2, $3, ... - the Nth argument in the method call\n"
"* $& - the full source line"
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:174
msgid ""
"The following example shows what the expansion variables might hold for a "
"given\n"
"DSL method call:"
msgstr ""

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:177
msgid ""
"  property :foo, :a, :b, :c, String\n"
"  # $0 => \"property\"\n"
"  # $1 => \"foo\"\n"
"  # $2 => \"a\"\n"
"  # $& => \"property :foo, :a, :b, :c, String\""
msgstr ""

#: ../lib/yard/tags/directives.rb:183
msgid "=== Ranges"
msgstr "=== 範囲"

#: ../lib/yard/tags/directives.rb:185
msgid ""
"Ranges are also acceptable with the syntax ${N-M}. Negative values\n"
"on either N or M are valid, and refer to indexes from the end of the list.\n"
"Consider a DSL method that creates a method using the first argument with\n"
"argument names following, ending with the return type of the method. This\n"
"could be documented as:"
msgstr ""
"範囲は ${N-M} の構文で指定できる。\n"
"NやMには負の値を指定可能で、\n"
"その場合リストの最後からのインデックスを参照する。\n"
"最初の引数でそれに続く引数名とともに使われて、\n"
"メソッドのリターンタイプとともに終了するメソッドを作るDSLメソッドを考えよう。\n"
"これは次のように記述できる。"

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:191
msgid ""
"    # @!macro dsl_method\n"
"    #   @!method $1(${2--2})\n"
"    #   @return [${-1}] the return value of $0\n"
"    create_method_with_args :foo, :a, :b, :c, String"
msgstr ""

#: ../lib/yard/tags/directives.rb:196
msgid ""
"As described, the method is using the signature foo(a, b, c) and "
"the return\n"
"type from the last argument, +String+. When using ranges, tokens are joined\n"
"with commas. Note that this includes using $0:"
msgstr ""
"上記の通り、メソッドは foo(a, b, c) の用法と最後の引数、\n"
"`String`からのリターンタイプを使っている。\n"
"範囲を使うときは、トークンはコンマでつながれている。\n"
"$0を使った場合を記述する。"

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:200
msgid ""
"    !!!plain\n"
"    $0-1 # => Interpolates to \"create_method_with_args, foo\""
msgstr ""

#: ../lib/yard/tags/directives.rb:203
msgid ""
"If you want to separate them with spaces, use $1 $2 $3 $4 .... Note "
"that\n"
"if the token cannot be expanded, it will return the empty string (not an "
"error),\n"
"so it would be safe to list $1 $2 ... $10, for example."
msgstr ""
"それらをスペースを用い区切りたい場合は、$1 $2 $3 $4 ... を使う\n"
"留意する事としてトークンが拡張できない場合は\n"
"空の文字列を返すだろう。(エラーではない)\n"
"なので例えば\n"
"$1 $2 ... $10 のように記述すると安全だろう。"

#: ../lib/yard/tags/directives.rb:207
msgid "=== Escaping Interpolation"
msgstr "=== 補間をエスケープする"

#: ../lib/yard/tags/directives.rb:209
msgid "Interpolation can be escaped by prefixing the +$+ with +\\+, like so:"
msgstr "補間文字をエスケープするには、下の様に +$+ の前に +\\+ 置く事でエスケープする。"

# YARD::Tags::MacroDirective
#: ../lib/yard/tags/directives.rb:211
msgid ""
"    # @!macro foo\n"
"    #   I have \\$2.00 USD."
msgstr ""

# @example Defining a simple macro
#: ../lib/yard/tags/directives.rb:250
msgid ""
"# @!macro [new] returnself\n"
"#   @return [self] returns itself"
msgstr ""

# @example Using a simple macro in multiple docstrings
#: ../lib/yard/tags/directives.rb:250
msgid ""
"# Documentation for map\n"
"# ...\n"
"# @macro returnself\n"
"def map; end\n"
"\n"
"# Documentation for filter\n"
"# ...\n"
"# @macro returnself\n"
"def filter; end"
msgstr ""

# @example Attaching a macro directly to a DSL method
#: ../lib/yard/tags/directives.rb:250
msgid ""
"class Post < Resource\n"
"  # @!macro [attach] property\n"
"  #   @return [$2] the $1 property\n"
"  property :title, String\n"
"\n"
"  # Macro will expand on this definition too\n"
"  property :view_count, Integer\n"
"end"
msgstr ""

# @example Attaching a macro to a class method (for DSL usage)
#: ../lib/yard/tags/directives.rb:250
msgid ""
"class Resource\n"
"  # Defines a new property\n"
"  # @param [String] name the property name\n"
"  # @param [Class] type the property's type\n"
"  # @!macro [attach] property\n"
"  #   @return [$2] the $1 property\n"
"  def self.property(name, type) end\n"
"end\n"
"\n"
"class Post < Resource\n"
"  property :title, String\n"
"  property :view_count, Integer\n"
"end"
msgstr ""

# @example
#: ../lib/yard/tags/directives.rb:250
msgid "tag|example|Attaching a macro directly to a DSL method"
msgstr "tag|example|DSLメソッドに直接マクロを追加する"

# @example
#: ../lib/yard/tags/directives.rb:250
msgid "tag|example|Attaching a macro to a class method (for DSL usage)"
msgstr "tag|example|クラスメソッドにマクロを追加する(DSL使用)"

# @example
#: ../lib/yard/tags/directives.rb:250
msgid "tag|example|Defining a simple macro"
msgstr "tag|example|簡単なマクロ定義"

# @example
#: ../lib/yard/tags/directives.rb:250
msgid "tag|example|Using a simple macro in multiple docstrings"
msgstr "tag|example|複数のdocstringの中の単純名マクロを使う"

# YARD::Tags::MethodDirective
#: ../lib/yard/tags/directives.rb:327
msgid ""
"Defines a method object with a given method signature, using indented\n"
"block data as the method's docstring. The signature is similar to the\n"
"{tag:overload} tag. The comment containing this directive does not need\n"
"to be attached to any source, but if it is, that source code will be\n"
"used as the method's source."
msgstr ""

# YARD::Tags::MethodDirective
#: ../lib/yard/tags/directives.rb:333
msgid "To define an attribute method, see {tag:!attribute}"
msgstr ""

# @example Attaching multiple methods to the same source
#: ../lib/yard/tags/directives.rb:350
msgid ""
"# @!method method1\n"
"# @!method method2\n"
"create_methods :method1, :method2"
msgstr ""

# @example Defining a simple method
#: ../lib/yard/tags/directives.rb:350
msgid ""
"# @!method quit(username, message = \"Quit\")\n"
"#   Sends a quit message to the server for a +username+.\n"
"#   @param [String] username the username to quit\n"
"#   @param [String] message the quit message\n"
"quit_message_method"
msgstr ""

# @note
#: ../lib/yard/tags/directives.rb:350
msgid ""
"For backwards compatibility support, you do not need to indent\n"
"the method's docstring text. If a +@!method+ directive is seen with\n"
"no indented block, the entire docstring is used as the new method's\n"
"docstring text."
msgstr ""

# @example
#: ../lib/yard/tags/directives.rb:350
msgid "tag|example|Attaching multiple methods to the same source"
msgstr "tag|example|同じソースに複数のメソッドを追加する"

# @example
#: ../lib/yard/tags/directives.rb:350
msgid "tag|example|Defining a simple method"
msgstr "tag|example|簡単なメソッドを定義する"

# @see
#: ../lib/yard/tags/directives.rb:350
msgid "tag|see|tag:!attribute"
msgstr ""

# YARD::Tags::AttributeDirective
#: ../lib/yard/tags/directives.rb:413
msgid ""
"Defines an attribute with a given name, using indented block data as the\n"
"attribute's docstring. If the type specifier is supplied with \"r\", \"w\", "
"or\n"
"\"rw\", the attribute is made readonly, writeonly or readwrite "
"respectively.\n"
"A readwrite attribute is the default, if no type is specified. The comment\n"
"containing this directive does not need to be attached to any source, but\n"
"if it is, that source code will be used as the method's source."
msgstr ""

# YARD::Tags::AttributeDirective
#: ../lib/yard/tags/directives.rb:420
msgid "To define an regular method, see {tag:!method}"
msgstr ""

# @example Defining a simple readonly attribute
#: ../lib/yard/tags/directives.rb:433
msgid ""
"# @!attribute [r] count\n"
"#   @return [Fixnum] the size of the list"
msgstr ""

# @example Defining a simple readwrite attribute
#: ../lib/yard/tags/directives.rb:433
msgid ""
"# @!attribute name\n"
"#   @return [String] the name of the user"
msgstr ""

# @note
#: ../lib/yard/tags/directives.rb:433
msgid ""
"For backwards compatibility support, you do not need to indent\n"
"the attribute's docstring text. If an +@!attribute+ directive is seen with\n"
"no indented block, the entire docstring is used as the new attribute's\n"
"docstring text."
msgstr ""

# @example
#: ../lib/yard/tags/directives.rb:433
msgid "tag|example|Defining a simple readonly attribute"
msgstr "tag|example|readonly属性を簡単に定義する"

# @example
#: ../lib/yard/tags/directives.rb:433
msgid "tag|example|Defining a simple readwrite attribute"
msgstr "tag|example|readwrite属性を簡単に定義する"

# @see
#: ../lib/yard/tags/directives.rb:433
msgid "tag|see|tag:!method"
msgstr ""

# YARD::Tags::ParseDirective
#: ../lib/yard/tags/directives.rb:495
msgid ""
"Parses a block of code as if it were present in the source file at that\n"
"location. This directive is useful if a class has dynamic meta-programmed\n"
"behaviour that cannot be recognized by YARD."
msgstr ""

# YARD::Tags::ParseDirective
#: ../lib/yard/tags/directives.rb:499
msgid ""
"You can specify the language of the code block using the types\n"
"specification list. By default, the code language is \"ruby\"."
msgstr ""

# @example Parsing C code
#: ../lib/yard/tags/directives.rb:518
msgid ""
"# @!parse [c]\n"
"#   void Init_Foo() {\n"
"#     rb_define_method(rb_cFoo, \"method\", method, 0);\n"
"#   }"
msgstr ""

# @example Declaring a method as an attribute
#: ../lib/yard/tags/directives.rb:518
msgid ""
"# This should really be an attribute\n"
"# @!parse attr_reader :foo\n"
"def object; @parent.object end"
msgstr ""

# @example Documenting dynamic module inclusion
#: ../lib/yard/tags/directives.rb:518
msgid ""
"class User\n"
"  # includes \"UserMixin\" and extends \"UserMixin::ClassMethods\"\n"
"  # using the UserMixin.included callback.\n"
"  # @!parse include UserMixin\n"
"  # @!parse extend UserMixin::ClassMethods\n"
"end"
msgstr ""

# @example
#: ../lib/yard/tags/directives.rb:518
msgid "tag|example|Declaring a method as an attribute"
msgstr "tag|example|属性としてメソッドを宣言する"

# @example
#: ../lib/yard/tags/directives.rb:518
msgid "tag|example|Documenting dynamic module inclusion"
msgstr "tag|example|動的にモジュール含有するドキュメントを作成する"

# @example
#: ../lib/yard/tags/directives.rb:518
msgid "tag|example|Parsing C code"
msgstr "tag|example|Cのコードを解析する"

# YARD::Tags::ScopeDirective
#: ../lib/yard/tags/directives.rb:536
msgid ""
"Modifies the current parsing scope (class or instance). If this\n"
"directive is defined on a docstring attached to an object definition,\n"
"it is applied only to that object. Otherwise, it applies the scope\n"
"to all future objects in the namespace."
msgstr ""

# @example Modifying the scope of a set of methods
#: ../lib/yard/tags/directives.rb:552
msgid ""
"# @!scope class\n"
"\n"
"# Documentation for method1\n"
"def method1; end\n"
"\n"
"# Documentation for method2\n"
"def method2; end"
msgstr ""

# @example Modifying the scope of a DSL method
#: ../lib/yard/tags/directives.rb:552
msgid ""
"# @!scope class\n"
"cattr_accessor :subclasses"
msgstr ""

# @example
#: ../lib/yard/tags/directives.rb:552
msgid "tag|example|Modifying the scope of a DSL method"
msgstr "tag|example|DSLメソッドのスコープを変更する"

# @example
#: ../lib/yard/tags/directives.rb:552
msgid "tag|example|Modifying the scope of a set of methods"
msgstr "tag|example|メソッドのグループのスコープを変更する"

# YARD::Tags::VisibilityDirective
#: ../lib/yard/tags/directives.rb:565
msgid ""
"Modifies the current parsing visibility (public, protected, or private).\n"
"If this directive is defined on a docstring attached to an object\n"
"definition, it is applied only to that object. Otherwise, it applies\n"
"the visibility to all future objects in the namespace."
msgstr ""

# @example Modifying the visibility of a DSL method
#: ../lib/yard/tags/directives.rb:582
msgid ""
"# @!visibility private\n"
"cattr_accessor :subclasses"
msgstr ""

# @example Modifying the visibility of a set of methods
#: ../lib/yard/tags/directives.rb:582
msgid ""
"# Note that Ruby's \"protected\" is recommended over this directive\n"
"# @!visibility protected\n"
"\n"
"# Documentation for method1\n"
"def method1; end\n"
"\n"
"# Documentation for method2\n"
"def method2; end"
msgstr ""

# @example
#: ../lib/yard/tags/directives.rb:582
msgid "tag|example|Modifying the visibility of a DSL method"
msgstr "tag|example|DSLメソッドの可視性を変更する"

# @example
#: ../lib/yard/tags/directives.rb:582
msgid "tag|example|Modifying the visibility of a set of methods"
msgstr "tag|example|メソッドのグループの可視性を変更する"

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:4
msgid ""
"Keeps track of all the registered meta-data tags and directives.\n"
"Also allows for defining of custom tags and customizing the tag parsing\n"
"syntax."
msgstr ""

# YARD::CLI::Yardoc
#: ../lib/yard/tags/library.rb:8
msgid "== Defining Custom Meta-Data Tags"
msgstr "== カスタムメタデータタグを定義する"

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:10
msgid ""
"To define a custom tag, use {define_tag}. You should pass the tag\n"
"name and the factory method to use when creating the tag. If you do not\n"
"provide a factory method to use, it will default to "
"{DefaultFactory#parse_tag}"
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:14
msgid ""
"You can also define tag objects manually by simply implementing a "
"\"tagname_tag\"\n"
"method that returns a {Tag} object, but they will not take advantage of tag "
"factory\n"
"parsing:"
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:18
msgid ""
"  def mytag_tag(text)\n"
"    Tag.new(:mytag, text)\n"
"  end"
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:22
msgid "== Defining Custom Directives"
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:24
msgid ""
"Directives can be defined by calling the {define_directive} method, taking\n"
"the directive name, an optional tag factory parser method (to parse the\n"
"data in the directive into a temporary {Tag} object) and a {Directive} "
"subclass\n"
"that performs the directive processing. For more information on creating a\n"
"Directive subclass, see the {Directive} class documentation."
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:30
msgid ""
"Similar to tags, Directives can also be defined manually, in this case "
"using\n"
"the method name \"mydirective_directive\" and returning a new {Directive} "
"object:"
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:33
msgid ""
"  def mydirective_directive(tag, parser)\n"
"    MyDirective.new(tag, parser)\n"
"  end"
msgstr ""

# YARD::Tags
#: ../lib/yard/tags/library.rb:37
msgid "== Namespaced Tags"
msgstr "== Namespaceタグ"

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:39
msgid ""
"In YARD 0.8.0+, tags can be namespaced using the '.' character. It is "
"recommended\n"
"to namespace project specific tags, like +@yard.tag_name+, so that tags do "
"not\n"
"collide with other plugins or new built-in tags."
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:43
msgid "== Adding/Changing the Tag Syntax"
msgstr ""

# YARD::Tags::Library
#: ../lib/yard/tags/library.rb:45
msgid ""
"If you have specialized tag parsing needs you can substitute the {#factory}\n"
"object with your own by setting {Library.default_factory= Library."
"default_factory}\n"
"to a new class with its own parsing methods before running YARD. This is "
"useful\n"
"if you want to change the syntax of existing tags (@see, @since, etc.)"
msgstr ""
"== 追加や変更のタグ構文\n"
"あなたが、専用のタグ解析が必要な場合、\n"
"自分で{Library.default_factory= Library.default_factory}を\n"
"YARDが起動する前に自身を解析するメソッドを用い\n"
"新しいクラスに設定する事によって\n"
"{#factory} オブジェクトを代替できる\n"
"これは、既に存在するタグ(@see,@since等)構文を変更したい場合、便利である。"

# @example Defining a custom directive
#: ../lib/yard/tags/library.rb:58
msgid "define_directive :method, :with_title_and_text, MethodDirective"
msgstr ""

# @example Defining a custom tag
#: ../lib/yard/tags/library.rb:58
msgid ""
"define_tag \"Parameter\", :param, :with_types_and_name\n"
"define_tag \"Author\", :author"
msgstr ""

# @example
#: ../lib/yard/tags/library.rb:58
msgid "tag|example|Defining a custom directive"
msgstr "tag|example|カスタムディレクティブを定義する"

# @example
#: ../lib/yard/tags/library.rb:58
msgid "tag|example|Defining a custom tag"
msgstr "tag|example|カスタムタグを定義する"

# @see
#: ../lib/yard/tags/library.rb:58 ../lib/yard/tags/library.rb:84
msgid "tag|see|DefaultFactory"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:58
msgid "tag|see|Directive"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:58
msgid "tag|see|define_directive"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:58
msgid "tag|see|define_tag"
msgstr ""

# @return [SymbolHash{Symbol=>String}]
#: ../lib/yard/tags/library.rb:62
msgid ""
"the map of tag names and their\n"
"respective display labels."
msgstr ""

# @return [NamespaceObject]
#: ../lib/yard/tags/library.rb:66
msgid "the main Library instance object."
msgstr "メインライブライリのインスタンスオブジェクト"

# YARD::Tags::Library.default_factory=
#: ../lib/yard/tags/library.rb:71
msgid ""
"Replace the factory object responsible for parsing tags by setting\n"
"this to an object (or class) that responds to +parse_TAGNAME+ methods\n"
"where +TAGNAME+ is the name of the tag."
msgstr ""
"+TAGNAME+ がタグの名前となる処理の所で、\n"
"+parse_TAGNAME+ メソッドに関連するオブジェクト(又は,クラス)の為に、\n"
"これを設定する事によってタグを解析するベースであるfactoryオブジェクトを変更す"
"る。"

# YARD::Tags::Library.default_factory=
#: ../lib/yard/tags/library.rb:75
msgid ""
"You should set this value before performing any source parsing with\n"
"YARD, otherwise your factory class will not be used."
msgstr ""
"あなたはYARDによって何らかのソースの解析を実行する前に、この値を設定しなけれ"
"ばならない。\n"
"設定しない場合、あなたのfactoryクラスは利用できない。"

# @example 
#: ../lib/yard/tags/library.rb:84
msgid "YARD::Tags::Library.default_factory = MyFactory"
msgstr ""

# @param [Class, Object]
#: ../lib/yard/tags/library.rb:84
msgid "tag|param|factory"
msgstr ""

# @param [Class, Object] factory
#: ../lib/yard/tags/library.rb:84
msgid "the factory that parses all tags"
msgstr "全てのタグを解析するファクトリー"

# YARD::Tags::Library.factory_method_for
#: ../lib/yard/tags/library.rb:93
msgid ""
"Returns the factory method used to parse the tag text for a specific tag"
msgstr ""
"特定のタグ用のタグテキストを解析するのに、利用されるファクトリーメソッドを返"
"す。"

# @return [nil]
#: ../lib/yard/tags/library.rb:100 ../lib/yard/tags/library.rb:113
msgid "if the tag is freeform text"
msgstr "タグがフリーフォームテキストの場合"

# @return [Class]
#: ../lib/yard/tags/library.rb:100
msgid ""
"the Tag class to use to parse the tag\n"
"or the method to call on the factory class"
msgstr "ファクトリークラスで呼び出すタグやメソッドを解析し利用する為のタグクラス"

# @return [Symbol]
#: ../lib/yard/tags/library.rb:100 ../lib/yard/tags/library.rb:113
msgid "the factory method name for the tag"
msgstr "タグの為のfactoryメソッド名"

# YARD::Tags::Library.factory_method_for
#: ../lib/yard/tags/library.rb:105
msgid ""
"Returns the factory method used to parse the tag text for a specific\n"
"directive"
msgstr ""
"特定のディレクティブ用に\n"
"タグテキストを解析する為に利用されたファクトリーメソッドを返す"

# @param [Boolean]
#: ../lib/yard/tags/library.rb:113
msgid "tag|param|directive"
msgstr ""

# @return [Class]
#: ../lib/yard/tags/library.rb:113
msgid ""
"the Tag class to use to parse the tag or\n"
"the methods to call on the factory class"
msgstr ""
"ファクトリークラスで呼び出す為に\n"
"タグやメソッドを解析し利用する為のタグクラス"

# @param [String, Symbol] section
#: ../lib/yard/tags/library.rb:113
msgid "the directive name"
msgstr "ディレクティブ名"

# YARD::Tags::Library.visible_tags
# YARD::Tags::Library.visible_tags=
#: ../lib/yard/tags/library.rb:118
msgid ""
"Sets the list of tags to display when rendering templates. The order of\n"
"tags in the list is also significant, as it represents the order that\n"
"tags are displayed in templates."
msgstr ""
"テンプレートをレンダリングする時、\n"
"表示する為にタグのリストをセットする。\n"
"リストの中のタグの順番は重要である。\n"
"これは、タグがテンプレートの中で表示される順番を表す。"

# YARD::Tags::Library.visible_tags
# YARD::Tags::Library.visible_tags=
#: ../lib/yard/tags/library.rb:122
msgid ""
"You can use the {Array#place} to insert new tags to be displayed in\n"
"the templates at specific positions:"
msgstr ""
"特定の場所でテンプレートの中で、\n"
"表示される新しいタグを挿入する為に{Array#place}メソッドを利用できる。"

# YARD::Tags::Library.visible_tags
# YARD::Tags::Library.visible_tags=
#: ../lib/yard/tags/library.rb:125
msgid "  Library.visible_tags.place(:mytag).before(:return)"
msgstr ""

# @return [Array]
#: ../lib/yard/tags/library.rb:128
msgid "a list of ordered tags"
msgstr "命令されるタグのリスト"

# YARD::Tags::Library.transitive_tags
# YARD::Tags::Library.transitive_tags=
#: ../lib/yard/tags/library.rb:131
msgid ""
"Sets the list of tags that should apply to any children inside the\n"
"namespace they are defined in. For instance, a \"@since\" tag should\n"
"apply to all methods inside a module it is defined in. Transitive\n"
"tags can be overridden by directly defining a tag on the child object."
msgstr ""
"定義されるnamespaceの内部で任意の子を適用しタグのリストをグループ化すべきであ"
"る。\n"
"例えば、\"@since\"タグは、モジュールの内部で定義される全てのメソッドが適用さ"
"れる。\n"
"過渡的なタグは、子のオブジェクトの上(親)のタグを直接定義する事によって上書き"
"できる。"

# @return [Array]
#: ../lib/yard/tags/library.rb:137
msgid "a list of transitive tags"
msgstr "過渡的なタグのリスト"

# YARD::Tags::Library.sorted_labels
#: ../lib/yard/tags/library.rb:140
msgid ""
"Sorts the labels lexically by their label name, often used when displaying\n"
"the tags."
msgstr ""
"ラベルをそのラベル名によってソートする。\n"
"タグを表示する時に、よく利用される。"

# @return [Array, String]
#: ../lib/yard/tags/library.rb:143
msgid "the sorted labels as an array of the tag name and label"
msgstr "ソートされるタグ名やラベルの配列"

# YARD::Tags::Library.define_tag
#: ../lib/yard/tags/library.rb:148
msgid ""
"Convenience method to define a new tag using one of {Tag}'s factory methods, "
"or the\n"
"regular {DefaultFactory#parse_tag} factory method if none is supplied."
msgstr ""
"{Tag}factoryメソッドの一つによって新しいタグを定義する便利なメソッド、\n"
"又、提供されない場合、正規の{DefaultFactory#parse_tag}メソッド"

# @param [Fixnum]
#: ../lib/yard/tags/library.rb:158
msgid "tag|param|label"
msgstr ""

# @param [#to_s, Class]
# @param [CodeObjects::MethodObject]
#: ../lib/yard/tags/library.rb:158
#: ../lib/yard/templates/helpers/html_helper.rb:430
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "tag|param|meth"
msgstr ""

# @param [#to_s] label
#: ../lib/yard/tags/library.rb:158
msgid "the label used when displaying the tag in templates"
msgstr ""

# @param [#to_s] tag
#: ../lib/yard/tags/library.rb:158
msgid "the tag name to create"
msgstr "作成するタグ名"

# @param [#to_s, Class] meth
#: ../lib/yard/tags/library.rb:158
msgid ""
"the {Tag} factory method to call when\n"
"creating the tag or the name of the class to directly create a tag for"
msgstr ""
"タグや直接タグを作成するクラスの名前を作成する時、呼び出すfactoryメソッドの"
"{Tag}"

# @overload
#: ../lib/yard/tags/library.rb:196
msgid "tag|overload|define_directive"
msgstr ""

# YARD::Tags::Library#factory
# YARD::Tags::Library#factory=
#: ../lib/yard/tags/library.rb:258
msgid ""
"A factory class to handle parsing of tags, defaults to {default_factory}"
msgstr ""
"タグの解析を操作するfactoryクラス、デフォルトは{default_factory}となる。"

# @return [Library]
#: ../lib/yard/tags/library.rb:260
msgid "a new instance of Library"
msgstr "ライブラリの新しいインスタンス"

# @param tag_name
#: ../lib/yard/tags/library.rb:267 ../lib/yard/tags/library.rb:280
msgid "the name of the tag to look for"
msgstr "検索する為のタグの名前"

# @return [Boolean]
#: ../lib/yard/tags/library.rb:267
msgid ""
"whether a tag by the given name is registered in\n"
"the library."
msgstr ""

# YARD::CodeObjects::CodeObjectList#initialize
#: ../lib/yard/tags/library.rb:272
msgid "Creates a new {Tag} object with a given tag name and data"
msgstr "与えられたタグ名とデータを用い新しい {Tag} オブジェクトを作成する。"

# @return [Base]
# @return [MacroObject]
#: ../lib/yard/tags/library.rb:273
msgid "the newly created tag object"
msgstr "新たに作成されたオブジェクト"

# @return [Boolean]
#: ../lib/yard/tags/library.rb:280
msgid ""
"whether a directive by the given name is registered in\n"
"the library."
msgstr ""

# YARD::Docstring#initialize
#: ../lib/yard/tags/library.rb:285
msgid ""
"Creates a new directive with tag information and a docstring parser\n"
"object."
msgstr "タグ情報とdocstringパーサーオブジェクトを用い新しいディレクティブを作成する"

# @return [String]
#: ../lib/yard/tags/library.rb:290 ../lib/yard/tags/tag.rb:14
msgid "the name of the tag"
msgstr "タグの名前"

# @return [Base]
# @return [MacroObject]
#: ../lib/yard/tags/library.rb:290
msgid "the newly created directive"
msgstr "新たに作成されたディレクティブ"

# @return [CodeObjects::Base]
#: ../lib/yard/tags/library.rb:290
msgid "the parser object parsing the docstring"
msgstr "パーサーオブジェクト、docstringを解析する"

# @param [Symbol] tag
# @param [String] tag_name
# @param [String] name
#: ../lib/yard/tags/library.rb:290
msgid "the tag data"
msgstr "タグデータ"

#: ../lib/yard/tags/library.rb:312
msgid ""
"# @abstract Subclass and override {#run} to implement\n"
"#   a custom Threadable class.\n"
"class Runnable\n"
"  def run; raise NotImplementedError end\n"
"end"
msgstr ""

# @yard.tag abstract
#: ../lib/yard/tags/library.rb:312
msgid "[] Abstract"
msgstr ""

# @param [Boolean]
#: ../lib/yard/tags/library.rb:312
msgid "tag|yard.tag|abstract"
msgstr ""

#: ../lib/yard/tags/library.rb:313
msgid ""
"Marks a class/module/method as abstract with optional\n"
"implementor information."
msgstr "任意の実装情報をと一緒に用い概要としてclass/module/methodをマークする"

#: ../lib/yard/tags/library.rb:327
msgid ""
"The special name +@api private+ does display a notice in\n"
"documentation if it is listed, letting users know that the\n"
"method is not to be used by external components."
msgstr ""
"特別な名前の +@api private+ は\n"
"それが記述された場合ドキュメントの中で通知を表示するようになり\n"
"ユーザーにメソッドが外部の構成要素によって使えないことを知らせる。"

# @note
#: ../lib/yard/tags/library.rb:327 ../lib/yard/tags/library.rb:473
#: ../lib/yard/tags/library.rb:518
msgid ""
"This tag is *transitive*. If it is applied on a\n"
"namespace (module or class), it will automatically be\n"
"applied to all children objects of that namespace unless\n"
"it is redefined on the child object."
msgstr ""

# @yard.tag api
#: ../lib/yard/tags/library.rb:327
msgid "[] API Visibility"
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:327
msgid ""
"class Post\n"
"  # @api private\n"
"  def reset_table!; table.flush end\n"
"end"
msgstr ""

# @param [Boolean]
#: ../lib/yard/tags/library.rb:327
msgid "tag|yard.tag|api"
msgstr ""

#: ../lib/yard/tags/library.rb:328
msgid ""
"Declares the API that the object belongs to. Does not display in\n"
"output, but useful for performing queries (+yardoc --query+). Any text is\n"
"allowable in this tag, and there are no predefined values."
msgstr ""
"オブジェクトが属するAPIを宣言する。\n"
"出力を表示できないが、クエリーの実行用に便利である(+yardoc --query+)。\n"
"任意のテキストは\n"
"このタグを受入可能であり、事前定義された値はない。"

# @example 
#: ../lib/yard/tags/library.rb:337
msgid ""
"# @attr [String] name the name of the structure\n"
"# @attr [Fixnum] size the size of the structure\n"
"class MyStruct < Struct; end"
msgstr ""

# YARD::Handlers::Base
#: ../lib/yard/tags/library.rb:337
msgid "Attribute"
msgstr "属性"

# @note
#: ../lib/yard/tags/library.rb:337 ../lib/yard/tags/library.rb:347
#: ../lib/yard/tags/library.rb:357
msgid "This attribute is only applicable on class docstrings"
msgstr ""

# @deprecated
#: ../lib/yard/tags/library.rb:337 ../lib/yard/tags/library.rb:347
#: ../lib/yard/tags/library.rb:357
msgid "Use the more powerful {tag:!attribute} directive instead."
msgstr ""

# @param [String]
# @param [Array]
# @param [String, :root]
#: ../lib/yard/tags/library.rb:337
msgid "tag|yard.tag|attr"
msgstr ""

# YARD::Tags::Library#attr_tag
#: ../lib/yard/tags/library.rb:338
msgid "Declares a readwrite attribute on a Struct or class."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:347 ../lib/yard/tags/library.rb:357
msgid ""
"# @attr_reader [String] name the name of the structure\n"
"# @attr_reader [Fixnum] size the size of the structure\n"
"class MyStruct < Struct; end"
msgstr ""

# YARD::Server::Commands::Base#request
# YARD::Server::Commands::Base#request=
# YARD::Server::Commands::Base#path
# YARD::Server::Commands::Base#path=
# YARD::Server::Commands::Base#headers
# YARD::Server::Commands::Base#headers=
# YARD::Server::Commands::Base#status
# YARD::Server::Commands::Base#status=
# YARD::Server::Commands::Base#body
# YARD::Server::Commands::Base#body=
#: ../lib/yard/tags/library.rb:347
msgid "Attribute Getter"
msgstr "Getter属性"

# @param [Boolean]
#: ../lib/yard/tags/library.rb:347
msgid "tag|yard.tag|attr_reader"
msgstr ""

# YARD::Tags::Library#attr_reader_tag
#: ../lib/yard/tags/library.rb:348
msgid "Declares a readonly attribute on a Struct or class."
msgstr ""

# YARD::Server::Commands::Base#request
# YARD::Server::Commands::Base#request=
# YARD::Server::Commands::Base#path
# YARD::Server::Commands::Base#path=
# YARD::Server::Commands::Base#headers
# YARD::Server::Commands::Base#headers=
# YARD::Server::Commands::Base#status
# YARD::Server::Commands::Base#status=
# YARD::Server::Commands::Base#body
# YARD::Server::Commands::Base#body=
#: ../lib/yard/tags/library.rb:357
msgid "Attribute Setter"
msgstr "Setter属性"

# @param [String]
#: ../lib/yard/tags/library.rb:357
msgid "tag|yard.tag|attr_writer"
msgstr ""

# YARD::Tags::Library#attr_writer_tag
#: ../lib/yard/tags/library.rb:358
msgid "Declares a writeonly attribute on a Struct or class."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:364
msgid ""
"# @author Foo Bar \n"
"class MyClass; end"
msgstr ""

# @yard.tag author
#: ../lib/yard/tags/library.rb:364
msgid "[] Author"
msgstr ""

# @param [String]
#: ../lib/yard/tags/library.rb:364
msgid "tag|yard.tag|author"
msgstr ""

#: ../lib/yard/tags/library.rb:365
msgid "List the author or authors of a class, module, or method."
msgstr "著者やクラス,モジュール,メソッドの著者を記述する"

# @example Deprecate a method with a replacement API
#: ../lib/yard/tags/library.rb:380
msgid ""
"# @deprecated Use {#bar} instead.\n"
"def foo; end"
msgstr ""

# @yard.tag deprecated
#: ../lib/yard/tags/library.rb:380
msgid "[] Deprecated"
msgstr ""

# @example Deprecate a method with no replacement
#: ../lib/yard/tags/library.rb:380
msgid ""
"class Thread\n"
"  # @deprecated Exiting a thread in this way is not reliable and\n"
"  #   can cause a program crash.\n"
"  def kill; end\n"
"end"
msgstr ""

# @example
#: ../lib/yard/tags/library.rb:380
msgid "tag|example|Deprecate a method with a replacement API"
msgstr "tag|example|置換APIを用いメソッドをメソッドを廃止する"

# @example
#: ../lib/yard/tags/library.rb:380
msgid "tag|example|Deprecate a method with no replacement"
msgstr "tag|example|置換APIを用いないでメソッドを廃止する"

# @param [Boolean]
#: ../lib/yard/tags/library.rb:380
msgid "tag|yard.tag|deprecated"
msgstr ""

# YARD::Tags::Library#deprecated_tag
#: ../lib/yard/tags/library.rb:381
msgid ""
"Marks a method/class as deprecated with an optional description.\n"
"The description should be used to inform users of the recommended\n"
"migration path, and/or any useful information about why the object\n"
"was marked as deprecated."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:391
msgid ""
"# @example Reverse a String\n"
"#   \"mystring\".reverse #=> \"gnirtsym\"\n"
"def reverse; end"
msgstr ""

# @yard.tag [with_title_and_text] example
#: ../lib/yard/tags/library.rb:391
msgid "Example"
msgstr ""

# @yard.signature
#: ../lib/yard/tags/library.rb:391
msgid ""
"Optional title\n"
"Code block"
msgstr ""

# @param [String, CodeObjects::ExtraFileObject]
# @param [String]
# @param [String, Regexp]
#: ../lib/yard/tags/library.rb:391
msgid "tag|yard.tag|example"
msgstr ""

#: ../lib/yard/tags/library.rb:392
msgid ""
"Show an example snippet of code for an object. The first line\n"
"is an optional title."
msgstr "オブジェクト用にコード片の例を表示する。最初の行は任意のタイトル。"

#: ../lib/yard/tags/library.rb:399
msgid ""
"# @note This method should only be used in outer space.\n"
"def eject; end"
msgstr ""

# @yard.tag note
#: ../lib/yard/tags/library.rb:399
msgid "[] Note"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:399
msgid "tag|see|tag:todo"
msgstr ""

# @param [Parser::Ruby::AstNode]
#: ../lib/yard/tags/library.rb:399
msgid "tag|yard.tag|note"
msgstr ""

# YARD::Tags::Library#note_tag
#: ../lib/yard/tags/library.rb:400
msgid "Adds an emphasized note at the top of the docstring for the object"
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:418
msgid ""
"# @param [Hash] opts the options to create a message with.\n"
"# @option opts [String] :subject The subject\n"
"# @option opts [String] :from ('nobody') From address\n"
"# @option opts [String] :to Recipient email\n"
"# @option opts [String] :body ('') The email's body\n"
"def send_email(opts = {}) end"
msgstr ""

# @param [Hash] options
#: ../lib/yard/tags/library.rb:418
msgid "Options Hash"
msgstr "ハッシュのオプション"

# @yard.signature
#: ../lib/yard/tags/library.rb:418
msgid "name [Types] option_key (default_value) description"
msgstr ""

# @param [String, Symbol]
# @param [Symbol, String]
#: ../lib/yard/tags/library.rb:418
msgid "tag|yard.tag|option"
msgstr ""

#: ../lib/yard/tags/library.rb:419
msgid ""
"Describe an options hash in a method. The tag takes the\n"
"name of the options parameter first, followed by optional types,\n"
"the option key name, a default value for the key and a\n"
"description of the option. The default value should be placed within\n"
"parentheses and is optional (can be omitted)."
msgstr ""
"メソッドの中のハッシュのオプションを説明する。\n"
"タグは最初にoptionsのパラメータの名前(name)を取得し、\n"
"続いて任意で型(types)、オプションのキー名、\n"
"キー用のデフォルトの値、オプションの説明となる。\n"
"デフォルト値は任意で(入れなくてもよい)\n"
"括弧の中に置なければならない。"

# YARD::Tags::Library#option_tag
#: ../lib/yard/tags/library.rb:425
msgid ""
"Note that a +@param+ tag need not be defined for the options\n"
"hash itself, though it is useful to do so for completeness."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:437
msgid ""
"# @overload set(key, value)\n"
"#   Sets a value on key\n"
"#   @param [Symbol] key describe key param\n"
"#   @param [Object] value describe value param\n"
"# @overload set(value)\n"
"#   Sets a value on the default key +:foo+\n"
"#   @param [Object] value describe value param\n"
"def set(*args) end"
msgstr ""

# @yard.tag [OverloadTag] overload
#: ../lib/yard/tags/library.rb:437
msgid "Overloads"
msgstr ""

# @yard.signature
#: ../lib/yard/tags/library.rb:437
msgid ""
"method_signature(parameters)\n"
"Indented docstring for overload method"
msgstr ""

# @param [Fixnum]
#: ../lib/yard/tags/library.rb:437
msgid "tag|yard.tag|overload"
msgstr ""

#: ../lib/yard/tags/library.rb:438
msgid ""
"Describe that your method can be used in various\n"
"contexts with various parameters or return types. The first\n"
"line should declare the new method signature, and the following\n"
"indented tag data will be a new documentation string with its\n"
"own tags adding metadata for such an overload."
msgstr ""
"あなたのメソッドが様々なパラメータや戻りの型と一緒に\n"
"様々なコンテキストで利用される説明をする。\n"
"最初に行は新しいメソッドのシグネチャで宣言しなければならない、\n"
"そして続くインデントされたタグデータは\n"
"オーバーロードの様に自身の追加するメタデータタグを用い\n"
"新しいドキュメント文字列になる。"

# @example 
#: ../lib/yard/tags/library.rb:445
msgid ""
"# @param [String] the URL of the page to download\n"
"def load_page(url) end"
msgstr ""

# @yard.tag [with_types_and_name] param
#: ../lib/yard/tags/library.rb:445
msgid "Parameters"
msgstr ""

# @param [Array]
# @param [Hash]
#: ../lib/yard/tags/library.rb:445
msgid "tag|yard.tag|param"
msgstr ""

# YARD::Tags::Library#param_tag
#: ../lib/yard/tags/library.rb:446
msgid ""
"Documents a single method parameter with a given name, type\n"
"and optional description."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:473
msgid ""
"# @private\n"
"class InteralImplementation; end"
msgstr ""

# @note
#: ../lib/yard/tags/library.rb:473
msgid ""
"This method is not recommended for hiding undocumented or\n"
"\"unimportant\" methods. This tag should only be used to mark objects\n"
"private when Ruby visibility rules cannot do so. In Ruby 1.9.3, you\n"
"can use +private_constant+ to declare constants (like classes or\n"
"modules) as private, and should be used instead of +@private+."
msgstr ""

# @yard.tag private
#: ../lib/yard/tags/library.rb:473
msgid "[] Private"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:473
msgid "tag|see|tag:api"
msgstr ""

# @param [String]
# @param [Array]
# @param [String, :root]
#: ../lib/yard/tags/library.rb:473
msgid "tag|yard.tag|private"
msgstr ""

# YARD::Tags::Library#private_tag
#: ../lib/yard/tags/library.rb:474
msgid ""
"Declares that the _logical_ visibility of an object is private.\n"
"In other words, it specifies that this method should be marked\n"
"private but cannot due to Ruby's visibility restrictions. This\n"
"exists for classes, modules and constants that do not obey Ruby's\n"
"visibility rules. For instance, an inner class might be considered\n"
"\"private\", though Ruby would make no such distinction."
msgstr ""

# YARD::Tags::Library#private_tag
#: ../lib/yard/tags/library.rb:481
msgid ""
"This tag is meant to be used in conjunction with the +--no-private+\n"
"command-line option, and is required to actually remove these objects\n"
"from documentation output. See {file:README.md} for more information on\n"
"switches."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:482
msgid ""
"# @raise [AccountBalanceError] if the account does not have\n"
"#   sufficient funds to perform the transaction\n"
"def withdraw(amount) end"
msgstr ""

# @yard.tag [with_types] raise
#: ../lib/yard/tags/library.rb:482
msgid "Raises"
msgstr ""

# @param [Boolean]
#: ../lib/yard/tags/library.rb:482
msgid "tag|yard.tag|raise"
msgstr ""

# YARD::Tags::Library#raise_tag
#: ../lib/yard/tags/library.rb:483
msgid ""
"Describes that a method may raise a given exception, with\n"
"an optional description of what it may mean."
msgstr ""

# YARD::Tags::Library#private_tag
#: ../lib/yard/tags/library.rb:486
msgid ""
"If you simply want to set the API visibility of a method, you should\n"
"look at the {tag:api} tag instead."
msgstr ""

# @example A regular return value
#: ../lib/yard/tags/library.rb:498
msgid ""
"# @return [Fixnum] the size of the file\n"
"def size; @file.size end"
msgstr ""

# @example A method returns an Array or a single object
#: ../lib/yard/tags/library.rb:498
msgid ""
"# @return [String] if a single object was returned\n"
"#   from the database.\n"
"# @return [Array] if multiple objects were\n"
"#   returned.\n"
"def find(query) end"
msgstr ""

# @yard.tag [with_types] return
#: ../lib/yard/tags/library.rb:498
msgid "Returns"
msgstr ""

# @example
#: ../lib/yard/tags/library.rb:498
msgid "tag|example|A method returns an Array or a single object"
msgstr "tag|example|メソッドは配列や単一のオブジェクトを返す"

# @example
#: ../lib/yard/tags/library.rb:498
msgid "tag|example|A regular return value"
msgstr "tag|example|慣習的な戻り値の例"

# @param [Boolean]
#: ../lib/yard/tags/library.rb:498
msgid "tag|yard.tag|return"
msgstr ""

# YARD::Tags::Library#return_tag
#: ../lib/yard/tags/library.rb:499
msgid ""
"Describes the return value (and type or types) of a method.\n"
"You can list multiple return tags for a method in the case\n"
"where a method has distinct return cases. In this case, each\n"
"case should begin with \"if ...\"."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:510
msgid ""
"# Synchronizes system time using NTP.\n"
"# @see http://ntp.org/documentation.html NTP Documentation\n"
"# @see NTPHelperMethods\n"
"class NTPUpdater; end"
msgstr ""

# @yard.tag [with_name] see
#: ../lib/yard/tags/library.rb:510
msgid "See Also"
msgstr ""

# @param [Tags::Tag, Tags::RefTag]
#: ../lib/yard/tags/library.rb:510
msgid "tag|yard.tag|see"
msgstr ""

#: ../lib/yard/tags/library.rb:511
msgid ""
"\"See Also\" references for an object. Accepts URLs or\n"
"other code objects with an optional description at the end.\n"
"Note that the URL or object will be automatically linked by\n"
"YARD and does not need to be formatted with markup."
msgstr ""
"\"See Also(参照)\"はオブジェクトに参照される。\n"
"URLや最後で任意の説明を用いた他のコードオブジェクトを受入れる。\n"
"留意する事としてURLやオブジェクトは\n"
"YARDによって自動的にリンクされ、\n"
"マークアップを用いフォーマットされる必要はない。"

# @example 
#: ../lib/yard/tags/library.rb:518
msgid ""
"# @since 1.2.4\n"
"def clear_routes; end"
msgstr ""

# @yard.tag since
#: ../lib/yard/tags/library.rb:518
msgid "[] Since"
msgstr ""

# @param [Fixnum, nil]
#: ../lib/yard/tags/library.rb:518
msgid "tag|yard.tag|since"
msgstr ""

#: ../lib/yard/tags/library.rb:519
msgid "Lists the version that the object was first added."
msgstr "オブジェクトが最初に追加されたバージョンを記述する"

#: ../lib/yard/tags/library.rb:544
msgid ""
"# @todo Add support for Jabberwocky service.\n"
"#   There is an open source Jabberwocky library available\n"
"#   at http://jbrwcky.org that can be easily integrated.\n"
"class Wonderlander; end"
msgstr ""

# @yard.tag todo
#: ../lib/yard/tags/library.rb:544
msgid "[] Todo Item"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:544
msgid "tag|see|tag:note"
msgstr ""

# @param [String]
#: ../lib/yard/tags/library.rb:544
msgid "tag|yard.tag|todo"
msgstr ""

# YARD::Tags::Library#todo_tag
#: ../lib/yard/tags/library.rb:545
msgid ""
"Marks a TODO note in the object being documented.\n"
"For reference, objects with TODO items can be enumerated\n"
"from the command line with a simple command:"
msgstr ""

# YARD::Tags::Library#todo_tag
#: ../lib/yard/tags/library.rb:549
msgid ""
"  !!!sh\n"
"  mocker$ yard list --query '@todo'\n"
"  lib/mocker/mocker.rb:15: Mocker\n"
"  lib/mocker/report/html.rb:5: Mocker::Report::Html"
msgstr ""

# YARD::Tags::Library#todo_tag
#: ../lib/yard/tags/library.rb:554
msgid ""
"YARD can also be used to enumerate the TODO items from\n"
"a short script:"
msgstr ""

# YARD::Tags::Library#todo_tag
#: ../lib/yard/tags/library.rb:557
msgid ""
"  !!!ruby\n"
"  require 'yard'\n"
"  YARD::Registry.load!.all.each do |o|\n"
"    puts o.tag(:todo).text if o.tag(:todo)\n"
"  end"
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:557
msgid ""
"# The public REST API for http://jbrwcky.org\n"
"# @version 2.0\n"
"class JabberwockyAPI; end"
msgstr ""

# @yard.tag version
#: ../lib/yard/tags/library.rb:557
msgid "[] Version"
msgstr ""

# @param [Array]
#: ../lib/yard/tags/library.rb:557
msgid "tag|yard.tag|version"
msgstr ""

# YARD::Tags::Library#version_tag
#: ../lib/yard/tags/library.rb:558
msgid ""
"Lists the version of a class, module or method. This is\n"
"similar to a library version, but at finer granularity.\n"
"In some cases, version of specific modules, classes, methods\n"
"or generalized components might change independently between\n"
"releases. A version tag is used to infer the API compatibility\n"
"of a specific object."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:573
msgid ""
"# For a block {|a,b,c| ... }\n"
"# @yield [a, b, c] Gives 3 random numbers to the block\n"
"def provide3values(&block) yield(42, 42, 42) end"
msgstr ""

# @yard.tag [with_types] yield
#: ../lib/yard/tags/library.rb:573
msgid "Yields"
msgstr ""

#: ../lib/yard/tags/library.rb:573
msgid "[parameters] description"
msgstr ""

# @yieldparam [Tags::Tag]
#: ../lib/yard/tags/library.rb:573
msgid "tag|see|tag:yieldparam"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:573
msgid "tag|see|tag:yieldreturn"
msgstr ""

# @param [Fixnum]
#: ../lib/yard/tags/library.rb:573
msgid "tag|yard.tag|yield"
msgstr ""

# YARD::Tags::Library#yield_tag
#: ../lib/yard/tags/library.rb:574
msgid ""
"Describes what a method might yield to a given block.\n"
"The types specifier list should not list types, but names\n"
"of the parameters yielded to the block. If you define\n"
"parameters with +@yieldparam+, you do not need to define\n"
"the parameters in the type specification of +@yield+ as\n"
"well."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:582
msgid ""
"# @yieldparam [String] name the name that is yielded\n"
"def with_name(name) yield(name) end"
msgstr ""

# @yard.tag [with_types_and_name] yieldparam
#: ../lib/yard/tags/library.rb:582
msgid "Yield Parameters"
msgstr ""

# @yieldparam [Tags::Tag]
#: ../lib/yard/tags/library.rb:582
msgid "tag|yard.tag|yieldparam"
msgstr ""

# YARD::Tags::Library#yieldparam_tag
#: ../lib/yard/tags/library.rb:583
msgid ""
"Defines a parameter yielded by a block. If you define the\n"
"parameters with +@yieldparam+, you do not need to define\n"
"them via +@yield+ as well."
msgstr ""

# @example 
#: ../lib/yard/tags/library.rb:591
msgid ""
"# @yieldreturn [Fixnum] the number to add 5 to.\n"
"def add5_block(&block) 5 + yield end"
msgstr ""

# @yard.tag [with_types] yieldreturn
#: ../lib/yard/tags/library.rb:591
msgid "Yield Returns"
msgstr ""

# @see
#: ../lib/yard/tags/library.rb:591
msgid "tag|see|tag:return"
msgstr ""

# @yard.tag [with_types]
#: ../lib/yard/tags/library.rb:591
msgid "tag|yard.tag|yieldreturn"
msgstr ""

# YARD::Tags::Library#yieldreturn_tag
#: ../lib/yard/tags/library.rb:592
msgid ""
"Documents the value and type that the block is expected\n"
"to return to the method."
msgstr ""

# @yard.directive [with_types_and_title] attribute
#: ../lib/yard/tags/library.rb:595
msgid "AttributeDirective"
msgstr ""

# @yard.signature
#: ../lib/yard/tags/library.rb:595
msgid ""
"[r | w | rw] attribute_name\n"
"Indented attribute docstring"
msgstr ""

# @param [Boolean]
#: ../lib/yard/tags/library.rb:595
msgid "tag|yard.directive|attribute"
msgstr ""

# @yard.directive [EndGroupDirective] endgroup
#: ../lib/yard/tags/library.rb:598
msgid "EndGroupDirective"
msgstr ""

# @yard.directive [EndGroupDirective]
#: ../lib/yard/tags/library.rb:598
msgid "tag|yard.directive|endgroup"
msgstr ""

# @yard.directive [GroupDirective] group
#: ../lib/yard/tags/library.rb:600
msgid "GroupDirective"
msgstr ""

# @yard.directive [GroupDirective]
#: ../lib/yard/tags/library.rb:600
msgid "tag|yard.directive|group"
msgstr ""

# @yard.directive [with_types_and_title] macro
#: ../lib/yard/tags/library.rb:604
msgid "MacroDirective"
msgstr ""

# @yard.signature
#: ../lib/yard/tags/library.rb:604
msgid ""
"[attach | new] optional_name\n"
"Optional macro expansion data"
msgstr ""

# @param [MacroObject]
# @param [CodeObjects::MacroObject]
#: ../lib/yard/tags/library.rb:604
msgid "tag|yard.directive|macro"
msgstr ""

# @yard.directive [with_title_and_text] method
#: ../lib/yard/tags/library.rb:608
msgid "MethodDirective"
msgstr ""

# @yard.signature
#: ../lib/yard/tags/library.rb:608
msgid ""
"method_signature(parameters)\n"
"Indented method docstring"
msgstr ""

# @yard.directive [with_title_and_text]
#: ../lib/yard/tags/library.rb:608
msgid "tag|yard.directive|method"
msgstr ""

# title
#: ../lib/yard/tags/library.rb:611
msgid "ParseDirective"
msgstr "パーサーディレクティブ"

# @return [Symbol]
#: ../lib/yard/tags/library.rb:611
msgid "[language] code"
msgstr ""

# @yard.directive [with_types]
#: ../lib/yard/tags/library.rb:611
msgid "tag|yard.directive|parse"
msgstr ""

# @yard.directive [ScopeDirective] scope
#: ../lib/yard/tags/library.rb:616
msgid "ScopeDirective"
msgstr ""

#: ../lib/yard/tags/library.rb:616
msgid "class | instance"
msgstr ""

# @param [Symbol]
#: ../lib/yard/tags/library.rb:616
msgid "tag|yard.directive|scope"
msgstr ""

#: ../lib/yard/tags/library.rb:617
msgid ""
"Sets the scope of a DSL method. Only applicable to DSL method\n"
"calls. Acceptable values are 'class' or 'instance'"
msgstr ""
"DSLメソッドのスコープに設定する。DSLメソッド呼び出しにだけ適用できる。\n"
"受け入れる値は'class'または'instance'である。"

# @yard.directive [VisibilityDirective] visibility
#: ../lib/yard/tags/library.rb:621
msgid "VisibilityDirective"
msgstr ""

# @yard.signature
#: ../lib/yard/tags/library.rb:621
msgid "public | protected | private"
msgstr ""

# @yard.directive [VisibilityDirective]
#: ../lib/yard/tags/library.rb:621
msgid "tag|yard.directive|visibility"
msgstr ""

#: ../lib/yard/tags/library.rb:622
msgid ""
"Sets the visibility of a DSL method. Only applicable to\n"
"DSL method calls. Acceptable values are public, protected, or private."
msgstr ""
"DSLメソッドの可視性を設定する。\n"
"DSLメソッド呼び出しに適用できる。\n"
"受け入れる値はpublic,protected,privateとなる"

# @param value
#: ../lib/yard/tags/option_tag.rb:4
msgid "the value to set the attribute pair to."
msgstr "pair属性に設定する値"

# YARD::Tags::OptionTag#pair
#: ../lib/yard/tags/option_tag.rb:5
msgid "Returns the value of attribute pair"
msgstr "pair属性の値を返す"

# YARD::Tags::OptionTag#pair=
#: ../lib/yard/tags/option_tag.rb:5
msgid "Sets the attribute pair"
msgstr "pair属性を設定する"

# @return [OptionTag]
#: ../lib/yard/tags/option_tag.rb:6
msgid "a new instance of OptionTag"
msgstr "オプションタグの新しいインスタンス"

# YARD::Tags::OverloadTag#parameters
#: ../lib/yard/tags/overload_tag.rb:5
msgid "Returns the value of attribute parameters"
msgstr "parameters属性の値を返す"

# YARD::Tags::OverloadTag#signature
#: ../lib/yard/tags/overload_tag.rb:5
msgid "Returns the value of attribute signature"
msgstr "signature属性の値を返す"

# @return [OverloadTag]
#: ../lib/yard/tags/overload_tag.rb:6
msgid "a new instance of OverloadTag"
msgstr "OverloadTagの新しいインスタンス"

# @param value
#: ../lib/yard/tags/ref_tag_list.rb:4
msgid "the value to set the attribute tag_name to."
msgstr "tag_name属性を設定する値"

# YARD::Tags::RefTagList#tag_name
#: ../lib/yard/tags/ref_tag_list.rb:5
msgid "Returns the value of attribute tag_name"
msgstr "tag_name属性の値を返す"

# YARD::Tags::RefTagList#tag_name=
#: ../lib/yard/tags/ref_tag_list.rb:5
msgid "Sets the attribute tag_name"
msgstr "tag_name属性を設定する"

# @return [RefTagList]
#: ../lib/yard/tags/ref_tag_list.rb:6
msgid "a new instance of RefTagList"
msgstr "RefTagListの新しいインスタンス"

# YARD::Tags::Tag
#: ../lib/yard/tags/tag.rb:4
msgid ""
"Represents a metadata tag value (+@tag+). Tags can have any combination of\n"
"{#types}, {#name} and {#text}, or none of the above."
msgstr ""
"タグはメタデータタグの値(+@tag+)を表し\n"
"任意の{#types},{#name},{#text},又は,\n"
"前述のどれでもないメソッドの組み合わせを持つ事が出来る。"

# @example Programmatic tag creation
#: ../lib/yard/tags/tag.rb:12
msgid ""
"# The following docstring syntax:\n"
"#   @param [String, nil] arg an argument\n"
"#\n"
"# is equivalent to:\n"
"Tag.new(:param, 'an argument', ['String', 'nil'], 'arg')"
msgstr ""
"# 次のdocstring構文は:\n"
"#   @param [String, nil] arg an argument\n"
"#\n"
"# 以下と同様になる。\n"
"Tag.new(:param, 'an argument', ['String', 'nil'], 'arg')"

# @example
#: ../lib/yard/tags/tag.rb:12
msgid "tag|example|Programmatic tag creation"
msgstr "タグを作成するプログラム例"

# @return [nil]
#: ../lib/yard/tags/tag.rb:18
msgid "if no tag text is supplied"
msgstr "タグテキストが指定されない場合"

# @return [String]
#: ../lib/yard/tags/tag.rb:18
msgid "the tag text associated with the tag"
msgstr "タグと一緒に関連付けられるタグテキスト"

# @return [Array]
#: ../lib/yard/tags/tag.rb:22
msgid "a list of types associated with the tag"
msgstr "タグと一緒に関連付けられる型のリスト"

# @return [nil]
#: ../lib/yard/tags/tag.rb:22
msgid "if no types are associated with the tag"
msgstr "型がタグと一緒に関連付けられない場合"

# @return [String]
#: ../lib/yard/tags/tag.rb:25
msgid "a name associated with the tag"
msgstr "タグと共に関連づけられる,名前"

# @return [CodeObjects::Base]
#: ../lib/yard/tags/tag.rb:28
msgid "the associated object"
msgstr "関連するオブジェクト"

# YARD::Tags::Tag#initialize
#: ../lib/yard/tags/tag.rb:31
msgid ""
"Creates a new tag object with a tag name and text. Optionally, formally "
"declared types\n"
"and a key name can be specified."
msgstr ""
"タグ名とテキストと共に新しいタグオブジェクトを作成する。\n"
"任意で、形式的に宣言される型やキー名を指定する事が出来る。"

# YARD::Tags::Tag#initialize
#: ../lib/yard/tags/tag.rb:34
msgid ""
"Types are mainly for meta tags that rely on type information, such as +param"
"+, +return+, etc."
msgstr "型は主に、+param+, +return+等の様な型情報を頼るメタタグ用である。"

# YARD::Tags::Tag#initialize
#: ../lib/yard/tags/tag.rb:36
msgid ""
"Key names are for tags that declare meta data for a specific key or name, "
"such as +param+,\n"
"+raise+, etc."
msgstr ""
"キー名(name)は +param+ , +raise+ 等のような\n"
"特定のキーや名前用のメタデータを宣言するタグの為にある。"

# @return [Tag]
#: ../lib/yard/tags/tag.rb:43
msgid "a new instance of Tag"
msgstr "タグの新しいインスタンス"

# @param [String] name
#: ../lib/yard/tags/tag.rb:43
msgid "optional key name which the tag refers to"
msgstr "タグが参照する,任意のキー名"

# @param [Array] types
#: ../lib/yard/tags/tag.rb:43
msgid ""
"optional type list of formally declared types\n"
"for the tag"
msgstr "タグ用に形式的に宣言された型の入った,任意の型配列"

# @param [String] text
#: ../lib/yard/tags/tag.rb:43
msgid "the descriptive text for this tag"
msgstr "このタグの為の説明文"

# @param [#to_s] tag_name
#: ../lib/yard/tags/tag.rb:43
msgid "the tag name to create the tag for"
msgstr "タグを作成する為のタグ名"

# YARD::Tags::Tag#type
#: ../lib/yard/tags/tag.rb:48
msgid ""
"Convenience method to access the first type specified. This should mainly\n"
"be used for tags that only specify one type."
msgstr ""
"最初の指定される型にアクセスする為の便利なメソッド,\n"
"これは、主に型が一つだけのタグを指定する時に利用されるべきである。"

# @see
#: ../lib/yard/tags/tag.rb:52
msgid "tag|see|#types"
msgstr ""

# @return [String]
#: ../lib/yard/tags/tag.rb:52
msgid "the first of the list of specified types"
msgstr "指定される型のリストの最初の部分"

# YARD::Templates::Engine
#: ../lib/yard/templates/engine.rb:6
msgid ""
"This module manages all creation, handling and rendering of {Template}\n"
"objects."
msgstr ""
"このモジュールは、全ての作成を管理し,操作する。そして、{Template}オブジェクト"
"から表示する。"

# YARD::Templates::Engine
#: ../lib/yard/templates/engine.rb:9
msgid ""
"* To create a template object at a path, use {template}.\n"
"* To render a template, call {render}.\n"
"* To register a template path in the lookup paths, call "
"{register_template_path}."
msgstr ""
"* パスでテンプレートオブジェクトを作成するには、{template}を使う\n"
"* テンプレートを表示するには、{render}を呼び出す\n"
"* 検索するパスでテンプレートパスを記録するには、{register_template_path}を呼"
"び出す。"

# @return [Array]
#: ../lib/yard/templates/engine.rb:14
msgid "the list of registered template paths"
msgstr "渡されたテンプレートパスのリスト"

# YARD::Templates::Engine.register_template_path
#: ../lib/yard/templates/engine.rb:17
msgid "Registers a new template path in {template_paths}"
msgstr "{template_paths}の中で、新しいテンプレートパスを記録する"

# @param [String] path
#: ../lib/yard/templates/engine.rb:20
msgid "a new template path"
msgstr "新しいテンプレートパス"

# YARD::Templates::Engine.template
#: ../lib/yard/templates/engine.rb:25
msgid ""
"Creates a template module representing the path. Searches on disk\n"
"for the first directory named +path+ (joined by '/') within the\n"
"template paths and builds a template module for. All other matching\n"
"directories in other template paths will be included in the\n"
"generated module as mixins (for overriding)."
msgstr ""
"パスを表すテンプレートモジュールを作成する。\n"
"テンプレートパスの内部で、\n"
"+path+ と名付けられた最初のディレクトリ('/'区切り)用に、\n"
"ディスク上をサーチする。\n"
"そして、テンプレートモジュール用にビルドする。\n"
"他にマッチするテンプレートパスの中のディレクトリ全ては、mixinとして(オーバー"
"ライド用に)、\n"
"生成されたモジュールが含まれる。"

# @param [Array] path
#: ../lib/yard/templates/engine.rb:34
msgid "a list of path components"
msgstr "構成要素のパスのリスト"

# @raise [ArgumentError]
#: ../lib/yard/templates/engine.rb:34
msgid ""
"if the path does not exist within one of the\n"
"{template_paths} on disk."
msgstr "ディスク上に{template_paths}が一つも存在しない場合、例外を上げる。"

# @return [Template]
#: ../lib/yard/templates/engine.rb:34
msgid "the module representing the template"
msgstr "モジュールの表しているテンプレート"

# YARD::Templates::Engine.template!
#: ../lib/yard/templates/engine.rb:48
msgid "Forces creation of a template at +path+ within a +full_path+."
msgstr ""
"+fullpath+ 内部の\n"
"+path+ で、テンプレートの作成を強制する。"

# @param [Array]
#: ../lib/yard/templates/engine.rb:52
msgid "tag|param|full_paths"
msgstr ""

# @param [Array] full_paths
#: ../lib/yard/templates/engine.rb:52
msgid "the full path on disk of the template"
msgstr "テンプレートのディスク上のフルパス"

# @param [String] path
#: ../lib/yard/templates/engine.rb:52
msgid "the path name of the template"
msgstr "テンプレートのパス名"

# @return [Template]
#: ../lib/yard/templates/engine.rb:52
msgid "the template module representing the +path+"
msgstr "テンプレートモジュールは、+path+ を表している。"

# YARD::Templates::Engine.render
#: ../lib/yard/templates/engine.rb:65
msgid ""
"Renders a template on a {CodeObjects::Base code object} using\n"
"a set of default (overridable) options. Either the +:object+\n"
"or +:type+ keys must be provided."
msgstr ""
"デフォルトのオプション(上書き可能)のグループによって、\n"
"{Codeobject::base code object}のテンプレートを表示する。\n"
"+:object+ か +:type+ キーが提供されければならない。"

# YARD::Templates::Engine.render
#: ../lib/yard/templates/engine.rb:69
msgid ""
"If a +:serializer+ key is provided and +:serialize+ is not set to\n"
"false, the rendered contents will be serialized through the {Serializers::"
"Base}\n"
"object. See {with_serializer}."
msgstr ""
"+:serializer+ キーが提供されるか、 +:serialize+ にfalseを設定しない場合、\n"
"表示される内容は、{Serializers::Base}オブジェクトを通して、シリアライズされる"
"だろう。\n"
"{with_serializer}参照。"

# @example Renders an object with html formatting
#: ../lib/yard/templates/engine.rb:81
msgid "Engine.render(:format => :html, :object => obj)"
msgstr ""

# @example Renders without an object
#: ../lib/yard/templates/engine.rb:81
msgid "Engine.render(:type => :fulldoc, :otheropts => somevalue)"
msgstr ""

# @example
#: ../lib/yard/templates/engine.rb:81
msgid "tag|example|Renders an object with html formatting"
msgstr "htmlフォーマットと共にオブジェクトを表示する"

# @example
#: ../lib/yard/templates/engine.rb:81
msgid "tag|example|Renders without an object"
msgstr "オブジェクト無しの表示"

# @param [Hash] options
#: ../lib/yard/templates/engine.rb:81 ../lib/yard/templates/engine.rb:140
msgid "the options hash"
msgstr "ハッシュのオプション"

# YARD::Templates::Engine.generate
#: ../lib/yard/templates/engine.rb:93
msgid ""
"Passes a set of objects to the +:fulldoc+ template for full documentation "
"generation.\n"
"This is called by {CLI::Yardoc} to most commonly perform HTML\n"
"documentation generation."
msgstr ""
"完璧なドキュメント生成用に、+:fulldoc+ テンプレートに\n"
"オブジェクトのグループが渡される。\n"
"これは、{CLI::Yardoc}によって呼び出される\n"
"一般的にhtmlドキュメント生成を実行しなければならない。"

# @param [Hash] options
#: ../lib/yard/templates/engine.rb:100
msgid "(see {render})"
msgstr ""

# @param [Array] objects
#: ../lib/yard/templates/engine.rb:100
msgid ""
"a list of {CodeObjects::Base}\n"
"objects to pass to the template"
msgstr ""
"テンプレートに渡す為の\n"
"{CodeObjects::Base} オブジェクトのリスト"

# YARD::Templates::Engine.with_serializer
#: ../lib/yard/templates/engine.rb:108
msgid "Serializes the results of a block with a +serializer+ object."
msgstr "+serializer+ オブジェクトを用いブロックの結果をシリアライズする。"

# @yield
#: ../lib/yard/templates/engine.rb:114
msgid "a block whose result will be serialize"
msgstr "結果がシリアライズされるブロック"

# @param [Serializers::Base]
#: ../lib/yard/templates/engine.rb:114
msgid "tag|param|serializer"
msgstr "serializer"

# @see
#: ../lib/yard/templates/engine.rb:114
msgid "tag|see|Serializers::Base"
msgstr ""

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/engine.rb:114
msgid "the code object to serialize"
msgstr "シリアライズする為のコードオブジェクト"

# @yieldreturn [String]
#: ../lib/yard/templates/engine.rb:114
msgid "the contents to serialize"
msgstr "シリアライズする為の内容"

# @param [Serializers::Base] serializer
#: ../lib/yard/templates/engine.rb:114
msgid "the serializer object"
msgstr "シリアライザーオブジェクト"

# YARD::Templates::Engine.set_default_options
#: ../lib/yard/templates/engine.rb:134
msgid "Sets default options on the options hash"
msgstr "ハッシュのオプションのデフォルトのオプションを設定する。"

# YARD::Templates::Engine.find_template_paths
#: ../lib/yard/templates/engine.rb:152
msgid ""
"Searches through the registered {template_paths} and returns\n"
"all full directories that have the +path+ within them on disk."
msgstr ""
"記録される{template_paths}を通して、検索され、\n"
"ディスク上に +path+ を持つ全てのディレクトリを返す。\n"

# @return [Array]
#: ../lib/yard/templates/engine.rb:160
msgid ""
"a list of full paths that are existing\n"
"candidates for a template module"
msgstr "テンプレートモジュール用の候補が存在するフルパスのリスト"

# @param [Template] from_template
#: ../lib/yard/templates/engine.rb:160
msgid ""
"if provided, allows a relative\n"
"path to be specified from this template's full path."
msgstr ""
"提供された場合、\n"
"このテンプレートのフルパスから指定される相対パスを受入れる。"

# @param [Template]
#: ../lib/yard/templates/engine.rb:160
msgid "tag|param|from_template"
msgstr "from_template"

# @param [String] path
#: ../lib/yard/templates/engine.rb:160
msgid ""
"the path component to search for in the\n"
"{template_paths}"
msgstr "{template_paths}用に検索する為のパスの構成"

# YARD::Templates::Engine.template_module_name
#: ../lib/yard/templates/engine.rb:172
msgid "The name of the module that represents a +path+"
msgstr "+path+ を表すモジュール名"

# @return [String]
#: ../lib/yard/templates/engine.rb:175
msgid "the module name"
msgstr "モジュール名"

# @param [String] the
#: ../lib/yard/templates/engine.rb:175
msgid "the path to generate a module name for"
msgstr "パス用のモジュール名を生成する為のパス"

# YARD::Templates::Helpers::BaseHelper
#: ../lib/yard/templates/helpers/base_helper.rb:3
msgid "The base helper module included in all templates."
msgstr "ベースへルパーモジュールは、全てのテンプレートを含んでいる。"

# @param value
#: ../lib/yard/templates/helpers/base_helper.rb:4
msgid "the value to set the attribute object to."
msgstr "オブジェクトの属性を設定する値"

# @param value
#: ../lib/yard/templates/helpers/base_helper.rb:4
msgid "the value to set the attribute serializer to."
msgstr "シリアライザーの属性を設定する値"

# YARD::Templates::Helpers::BaseHelper#object
#: ../lib/yard/templates/helpers/base_helper.rb:5
msgid "Returns the value of attribute object"
msgstr "オブジェクトの属性の値を返す"

# YARD::Templates::Helpers::BaseHelper#serializer
#: ../lib/yard/templates/helpers/base_helper.rb:5
msgid "Returns the value of attribute serializer"
msgstr "シリアライザーの属性の値を返す"

# YARD::Templates::Helpers::BaseHelper#object=
#: ../lib/yard/templates/helpers/base_helper.rb:5
msgid "Sets the attribute object"
msgstr "オブジェクトの属性を設定する。"

# YARD::Templates::Helpers::BaseHelper#serializer=
#: ../lib/yard/templates/helpers/base_helper.rb:5
msgid "Sets the attribute serializer"
msgstr "シリアライザーの属性を設定する。"

# @return [CodeObjects::Base]
#: ../lib/yard/templates/helpers/base_helper.rb:8
#: ../lib/yard/templates/helpers/base_helper.rb:10
msgid ""
"the object representing the current generated\n"
"page. Might not be the current {#object} when inside sub-templates."
msgstr ""

# YARD::Templates::Helpers::BaseHelper#globals
#: ../lib/yard/templates/helpers/base_helper.rb:15
msgid ""
"An object that keeps track of global state throughout the entire template\n"
"rendering process (including any sub-templates)."
msgstr ""
"全体のテンプレートの表示処理を通じて、globalの状態の軌跡を保持するオブジェク"
"ト。\n"
"(任意のサブテンプレートを含んでいる)"

# YARD::Templates::Helpers::BaseHelper#globals
#: ../lib/yard/templates/helpers/base_helper.rb:19
msgid "Managing Global Template State"
msgstr "グローバルなテンプレートの状態を管理する。"

# @return [OpenStruct]
#: ../lib/yard/templates/helpers/base_helper.rb:19
msgid "a struct object that stores state"
msgstr "状態を記憶する構造体オブジェクト"

# YARD::Templates::Helpers::BaseHelper#run_verifier
#: ../lib/yard/templates/helpers/base_helper.rb:29
msgid "Running the Verifier"
msgstr "Verifierを起動する。"

# @param [Array] list
#: ../lib/yard/templates/helpers/base_helper.rb:29 ../lib/yard/verifier.rb:90
msgid "a list of code objects"
msgstr "コードオブジェクトのリスト"

# @return [Array]
#: ../lib/yard/templates/helpers/base_helper.rb:29
msgid ""
"a list of code objects that match\n"
"the verifier. If no verifier is supplied, all objects are returned."
msgstr ""
"verifierにマッチするコードオブジェクトのリスト\n"
"verifierが提供されない場合、全てのオブジェクトが、返される。"

# YARD::Templates::Helpers::BaseHelper#h
#: ../lib/yard/templates/helpers/base_helper.rb:36
msgid ""
"Escapes text. This is used a lot by the HtmlHelper and there should\n"
"be some helper to \"clean up\" text for whatever, this is it."
msgstr ""
"テキストをエスケープする。これは、HtmlHelperに多く利用され、\n"
"どんなテキストでも仕上げる為にいくつかのhelperメソッドになる。"

# YARD::Templates::Helpers::BaseHelper#h
#: ../lib/yard/templates/helpers/base_helper.rb:37
msgid "Escaping Text"
msgstr "テキストをエスケープする。"

# YARD::Templates::Helpers::BaseHelper#linkify
#: ../lib/yard/templates/helpers/base_helper.rb:44
msgid ""
"Links objects or URLs. This method will delegate to the correct +link_+\n"
"method depending on the arguments passed in."
msgstr ""
"オブジェクトやURLをリンクする。このメソッドは、\n"
"渡された引数に応じて、妥当な +link_+ メソッドに委譲するだろう。"

# YARD::Templates::Helpers::BaseHelper#linkify
# YARD::Templates::Helpers::BaseHelper#link_include_object
# YARD::Templates::Helpers::BaseHelper#link_include_file
# YARD::Templates::Helpers::BaseHelper#link_object
# YARD::Templates::Helpers::BaseHelper#link_url
# YARD::Templates::Helpers::BaseHelper#link_file
# YARD::Templates::Helpers::HtmlHelper#resolve_links
# YARD::Templates::Helpers::HtmlHelper#link_file
# YARD::Templates::Helpers::HtmlHelper#link_include_file
# YARD::Templates::Helpers::HtmlHelper#link_include_object
# YARD::Templates::Helpers::HtmlHelper#link_object
# YARD::Templates::Helpers::HtmlHelper#link_url
#: ../lib/yard/templates/helpers/base_helper.rb:54
#: ../lib/yard/templates/helpers/base_helper.rb:102
#: ../lib/yard/templates/helpers/base_helper.rb:110
#: ../lib/yard/templates/helpers/base_helper.rb:119
#: ../lib/yard/templates/helpers/base_helper.rb:138
#: ../lib/yard/templates/helpers/base_helper.rb:149
#: ../lib/yard/templates/helpers/html_helper.rb:180
#: ../lib/yard/templates/helpers/html_helper.rb:219
#: ../lib/yard/templates/helpers/html_helper.rb:231
#: ../lib/yard/templates/helpers/html_helper.rb:240
#: ../lib/yard/templates/helpers/html_helper.rb:245
#: ../lib/yard/templates/helpers/html_helper.rb:273
msgid "Linking Objects and URLs"
msgstr "オブジェクトとURLにリンクする。"

# @example Linking an object by path
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "linkify('YARD::Docstring')"
msgstr ""

# @example Linking to an extra file
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "linkify('file:README')"
msgstr ""

# @example Linking a URL
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "linkify('http://example.com')"
msgstr ""

# @example Including docstring contents of an object
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "linkify('include:YARD::Docstring')"
msgstr ""

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "tag|example|Including docstring contents of an object"
msgstr "インクルードしているdocstringは、オブジェクトの内容となる。"

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "tag|example|Linking a URL"
msgstr "URLにリンクする。"

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "tag|example|Linking an object by path"
msgstr "パスによってオブジェクトにリンクする"

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:54
msgid "tag|example|Linking to an extra file"
msgstr "extraファイル(追加のファイル)にリンクする。"

# YARD::Templates::Helpers::BaseHelper#link_include_object
# YARD::Templates::Helpers::HtmlHelper#link_include_object
#: ../lib/yard/templates/helpers/base_helper.rb:99
#: ../lib/yard/templates/helpers/html_helper.rb:241
msgid "Includes an object's docstring into output."
msgstr "出力へ、オブジェクトのdocstringを含める"

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/helpers/base_helper.rb:102
msgid "the object to include"
msgstr "含めるオブジェクト"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:102
msgid "the object's docstring (no tags)"
msgstr "docstringオブジェクト(タグ無し)"

# YARD::Templates::Helpers::BaseHelper#link_include_file
# YARD::Templates::Helpers::HtmlHelper#link_include_file
#: ../lib/yard/templates/helpers/base_helper.rb:107
#: ../lib/yard/templates/helpers/html_helper.rb:232
msgid "Include a file as a docstring in output"
msgstr "出力でdocstringとして、ファイルを含める"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:110
msgid "the file's contents"
msgstr "ファイルの内容"

# @param [String] file
#: ../lib/yard/templates/helpers/base_helper.rb:110
msgid "the filename to include"
msgstr "含めるファイル名"

# YARD::Templates::Helpers::BaseHelper#link_object
# YARD::Templates::Helpers::HtmlHelper#link_object
#: ../lib/yard/templates/helpers/base_helper.rb:115
#: ../lib/yard/templates/helpers/html_helper.rb:246
msgid "Links to an object with an optional title"
msgstr "任意のタイトルと共にオブジェクトにリンクする"

# @param [String]
#: ../lib/yard/templates/helpers/base_helper.rb:119
#: ../lib/yard/templates/helpers/base_helper.rb:138
#: ../lib/yard/templates/helpers/base_helper.rb:149
msgid "tag|param|title"
msgstr "title"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:119
msgid "the linked object"
msgstr "リンクしたオブジェクト"

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/helpers/base_helper.rb:119
msgid "the object to link to"
msgstr "リンクするオブジェクト"

# @param [String] title
#: ../lib/yard/templates/helpers/base_helper.rb:119
msgid "the title to use for the link"
msgstr "リンク用に利用するタイトル"

# YARD::Templates::Helpers::BaseHelper#link_url
# YARD::Templates::Helpers::HtmlHelper#link_url
#: ../lib/yard/templates/helpers/base_helper.rb:133
#: ../lib/yard/templates/helpers/html_helper.rb:274
msgid "Links to a URL"
msgstr "URLにリンクする"

# @param [Hash] params
#: ../lib/yard/templates/helpers/base_helper.rb:138
msgid "optional parameters for the link"
msgstr "リンク用の任意のパラメーター"

# @param [String] url
#: ../lib/yard/templates/helpers/base_helper.rb:138
msgid "the URL to link to"
msgstr "リンクするURL"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:138
msgid "the linked URL"
msgstr "リンクしたURL"

# @param [String] title
#: ../lib/yard/templates/helpers/base_helper.rb:138
msgid "the optional title to display the link as"
msgstr "任意のタイトルとして、リンクに表示する"

# YARD::Templates::Helpers::BaseHelper#link_file
# YARD::Templates::Helpers::HtmlHelper#link_file
#: ../lib/yard/templates/helpers/base_helper.rb:143
#: ../lib/yard/templates/helpers/html_helper.rb:220
msgid "Links to an extra file"
msgstr "extraファイルにリンクする"

# @param [String] anchor
#: ../lib/yard/templates/helpers/base_helper.rb:149
#: ../lib/yard/templates/helpers/html_helper.rb:342
msgid "optional anchor"
msgstr "任意のアンカー"

# @param [String]
#: ../lib/yard/templates/helpers/base_helper.rb:149
#: ../lib/yard/templates/helpers/html_helper.rb:309
#: ../lib/yard/templates/helpers/html_helper.rb:342
msgid "tag|param|anchor"
msgstr "anchor"

# @param [String, CodeObjects::ExtraFileObject] filename
# @param [String] filename
#: ../lib/yard/templates/helpers/base_helper.rb:149
#: ../lib/yard/templates/helpers/html_helper.rb:342
msgid "the filename to link to"
msgstr "リンクするファイル名"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:149
msgid "the link to the file"
msgstr "ファイルへのリンク"

# @param [String] title
#: ../lib/yard/templates/helpers/base_helper.rb:149
msgid "the title of the link"
msgstr "リンクのタイトル"

# YARD::Templates::Helpers::BaseHelper#format_types
#: ../lib/yard/templates/helpers/base_helper.rb:157
msgid "Formats a list of return types for output and links each type."
msgstr "出力用に戻りの型のリストをフォーマットし、それぞれの型にリンクする。"

# YARD::Templates::Helpers::BaseHelper#format_types
# YARD::Templates::Helpers::BaseHelper#format_object_type
# YARD::Templates::Helpers::BaseHelper#format_object_title
# YARD::Templates::Helpers::BaseHelper#format_source
#: ../lib/yard/templates/helpers/base_helper.rb:165
#: ../lib/yard/templates/helpers/base_helper.rb:179
#: ../lib/yard/templates/helpers/base_helper.rb:193
#: ../lib/yard/templates/helpers/base_helper.rb:206
msgid "Formatting Object Attributes"
msgstr "オブジェクトの属性をフォーマットする"

# @param [Array] list
#: ../lib/yard/templates/helpers/base_helper.rb:165
msgid "a list of types"
msgstr "型のリスト"

# @example Formatting types
#: ../lib/yard/templates/helpers/base_helper.rb:165
msgid "format_types(['String', 'Array']) #=> \"(String, Array)\""
msgstr ""

# @example Formatting types without surrounding brackets
#: ../lib/yard/templates/helpers/base_helper.rb:165
msgid "format_types(['String', 'Array'], false) #=> \"String, Array\""
msgstr ""

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:165
msgid "tag|example|Formatting types"
msgstr "型をフォーマットする"

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:165
msgid "tag|example|Formatting types without surrounding brackets"
msgstr "周りをブラケット(括弧)無しの型へフォーマットする"

# @param [Boolean]
#: ../lib/yard/templates/helpers/base_helper.rb:165
#: ../lib/yard/templates/helpers/html_helper.rb:414
msgid "tag|param|brackets"
msgstr "brackets"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:165
msgid "the formatted list of Ruby types"
msgstr "フォーマットされたRubyの型のリスト"

# @param [Boolean] brackets
#: ../lib/yard/templates/helpers/base_helper.rb:165
msgid "whether to surround the types in brackets"
msgstr "ブラケット(括弧)の型で囲むかどうか"

# @example Formatted type of an exception class
#: ../lib/yard/templates/helpers/base_helper.rb:179
msgid ""
"o = ClassObject.new(:root, :MyError)\n"
"o.superclass = P('RuntimeError')\n"
"format_object_type(o) # => \"Exception\""
msgstr ""

# @example Formatted type of a method
#: ../lib/yard/templates/helpers/base_helper.rb:179
msgid ""
"o = MethodObject.new(:root, :to_s)\n"
"format_object_type(o) # => \"Method\""
msgstr ""

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:179
msgid "tag|example|Formatted type of a method"
msgstr "メソッドの入ったフォーマットされた型"

# @example
#: ../lib/yard/templates/helpers/base_helper.rb:179
msgid "tag|example|Formatted type of an exception class"
msgstr "exceptionクラスのフォーマットされた型"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:179
msgid ""
"the human-readable formatted {CodeObjects::Base#type #type}\n"
"for the object"
msgstr ""
"人が読みやすくフォーマットされたオブジェクト用の{CodeObjects::Base#type "
"#type}メソッド"

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/helpers/base_helper.rb:179
msgid "the object to retrieve the type for"
msgstr "型を回収するオブジェクト"

# @example 
#: ../lib/yard/templates/helpers/base_helper.rb:193
msgid ""
"s = format_object_title ModuleObject.new(:root, :MyModuleName)\n"
"s # => \"Module: MyModuleName\""
msgstr ""

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/helpers/base_helper.rb:193
msgid "the object to retrieve a title for"
msgstr "タイトルを回収するオブジェクト"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:193
msgid "the page title name for a given object"
msgstr "与えられたオブジェクト用のページのタイトル名"

# YARD::Templates::Helpers::BaseHelper#format_source
#: ../lib/yard/templates/helpers/base_helper.rb:203
msgid "Indents and formats source code"
msgstr "インデントし、ソースコードをフォーマットする"

# @return [String]
#: ../lib/yard/templates/helpers/base_helper.rb:206
msgid "formatted source code"
msgstr "フォーマットされたソースコード"

# @param [String] value
#: ../lib/yard/templates/helpers/base_helper.rb:206
msgid "the input source code"
msgstr "入力のソースコード"

# YARD::Templates::Helpers::FilterHelper
#: ../lib/yard/templates/helpers/filter_helper.rb:4
msgid "Helpers for various object types"
msgstr "様々なオブジェクト型用のHelperメソッド"

# @return [Boolean]
#: ../lib/yard/templates/helpers/filter_helper.rb:6
msgid "whether an object is a method"
msgstr "オブジェクトがメソッドかどうか"

# @return [Boolean]
#: ../lib/yard/templates/helpers/filter_helper.rb:11
msgid "whether an object is a namespace"
msgstr "オブジェクトがnamespaceかどうか"

# @return [Boolean]
#: ../lib/yard/templates/helpers/filter_helper.rb:16
msgid "whether an object is a class"
msgstr "オブジェクトがクラスかどうか"

# @return [Boolean]
#: ../lib/yard/templates/helpers/filter_helper.rb:21
msgid "whether an object is a module"
msgstr "オブジェクトがモジュールかどうか"

# YARD::Templates::Helpers::HtmlHelper
#: ../lib/yard/templates/helpers/html_helper.rb:6
msgid "The helper module for HTML templates."
msgstr "HTMLテンプレート用のhelperモジュール。"

# YARD::Templates::Helpers::HtmlHelper#h
#: ../lib/yard/templates/helpers/html_helper.rb:13
msgid "Escapes HTML entities"
msgstr "HTMLの構成要素をエスケープする。"

# YARD::Templates::Helpers::HtmlHelper#h
# YARD::Templates::Helpers::HtmlHelper#urlencode
#: ../lib/yard/templates/helpers/html_helper.rb:16
#: ../lib/yard/templates/helpers/html_helper.rb:24
msgid "Escaping Template Data"
msgstr "テンプレートのデータをエスケープする。"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:16
msgid "the HTML with escaped entities"
msgstr "エスケープされたものと一緒のHTML"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:16
msgid "the text to escape"
msgstr "エスケープするテキスト"

# YARD::Templates::Helpers::HtmlHelper#urlencode
#: ../lib/yard/templates/helpers/html_helper.rb:21
msgid "Escapes a URL"
msgstr "URLをエスケープする"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:24
msgid "the URL"
msgstr "URL"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:24
msgid "the escaped URL"
msgstr "エスケープされたURL"

# YARD::Templates::Helpers::HtmlHelper#htmlify
#: ../lib/yard/templates/helpers/html_helper.rb:31
msgid "Turns text into HTML using +markup+ style formatting."
msgstr ""
"+markup+ スタイルフォーマットにする事によって、HTMLへテキストを切り替える。"

# YARD::Templates::Helpers::HtmlHelper#htmlify
# YARD::Templates::Helpers::HtmlHelper#html_markup_markdown
# YARD::Templates::Helpers::HtmlHelper#html_markup_textile
# YARD::Templates::Helpers::HtmlHelper#html_markup_rdoc
# YARD::Templates::Helpers::HtmlHelper#html_markup_text
# YARD::Templates::Helpers::HtmlHelper#html_markup_none
# YARD::Templates::Helpers::HtmlHelper#html_markup_html
# YARD::Templates::Helpers::HtmlHelper#html_markup_ruby
# YARD::Templates::Helpers::HtmlHelper#htmlify_line
#: ../lib/yard/templates/helpers/html_helper.rb:36
#: ../lib/yard/templates/helpers/html_helper.rb:57
#: ../lib/yard/templates/helpers/html_helper.rb:73
#: ../lib/yard/templates/helpers/html_helper.rb:83
#: ../lib/yard/templates/helpers/html_helper.rb:91
#: ../lib/yard/templates/helpers/html_helper.rb:101
#: ../lib/yard/templates/helpers/html_helper.rb:109
#: ../lib/yard/templates/helpers/html_helper.rb:115
#: ../lib/yard/templates/helpers/html_helper.rb:123
#: ../lib/yard/templates/helpers/html_helper.rb:134
#: ../lib/yard/templates/helpers/html_helper.rb:139
msgid "Converting Markup to HTML"
msgstr "HTMLへMarkupを変換する。"

# @param [Symbol] markup
#: ../lib/yard/templates/helpers/html_helper.rb:36
msgid ""
"examples are +:markdown+, +:textile+, +:rdoc+.\n"
"To add a custom markup type, see {MarkupHelper}"
msgstr ""
"例えば、 +:markdown+ , +:textile+ , +:rdoc+ がある。\n"
"カスタムマークアップの型を追加するには、 {MarkupHelper}参照。"

# @param [Symbol]
#: ../lib/yard/templates/helpers/html_helper.rb:36
msgid "tag|param|markup"
msgstr "markup"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:36
msgid "the HTML"
msgstr "HTML"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:36
msgid "the text to format"
msgstr "フォーマットするテキスト"

# YARD::Templates::Helpers::HtmlHelper#html_markup_markdown
#: ../lib/yard/templates/helpers/html_helper.rb:54
msgid "Converts Markdown to HTML"
msgstr "HTMLへMarkdownを変換する。"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:57
msgid "input Markdown text"
msgstr "Markdownテキストを入力する"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:57
#: ../lib/yard/templates/helpers/html_helper.rb:73
#: ../lib/yard/templates/helpers/html_helper.rb:91
#: ../lib/yard/templates/helpers/html_helper.rb:123
msgid "output HTML"
msgstr "HTMLを出力する"

# YARD::Templates::Helpers::HtmlHelper#html_markup_textile
#: ../lib/yard/templates/helpers/html_helper.rb:70
msgid "Converts Textile to HTML"
msgstr "HTMLへTextileを変換する。"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:73
msgid "the input Textile text"
msgstr "入力するTextileテキスト"

# YARD::Templates::Helpers::HtmlHelper#html_markup_text
#: ../lib/yard/templates/helpers/html_helper.rb:80
msgid "Converts plaintext to strict Textile (hard breaks)"
msgstr "厳格なTextileにプレーンテキストを変換する。(hard breaks)"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:83
msgid "the input textile data"
msgstr "入力するTextileのデータ"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:83
#: ../lib/yard/templates/helpers/html_helper.rb:101
#: ../lib/yard/templates/helpers/html_helper.rb:109
msgid "the output HTML"
msgstr "出力HTML"

# YARD::Templates::Helpers::HtmlHelper#html_markup_rdoc
#: ../lib/yard/templates/helpers/html_helper.rb:88
msgid "Converts RDoc formatting (SimpleMarkup) to HTML"
msgstr "RDocフォーマット(SimpleMarkup)をHTMLへ変換する。"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:91
msgid "the input RDoc formatted text"
msgstr "RDocでフォーマットされたテキストの入力"

# YARD::Templates::Helpers::HtmlHelper#html_markup_text
#: ../lib/yard/templates/helpers/html_helper.rb:98
msgid "Converts plaintext to pre-formatted HTML"
msgstr "事前にフォーマットされたHTMLにプレーンテキストを変換する。"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:101
#: ../lib/yard/templates/helpers/html_helper.rb:109
msgid "the input text"
msgstr "入力テキスト"

# YARD::Templates::Helpers::HtmlHelper#html_markup_text
#: ../lib/yard/templates/helpers/html_helper.rb:106
msgid "Converts plaintext to regular HTML"
msgstr "通常のHTMLにプレーンテキストを変換する。"

# @since
#: ../lib/yard/templates/helpers/html_helper.rb:115
msgid "0.6.6"
msgstr ""

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:115
msgid "the same text with no markup"
msgstr "markupの無い、同じテキスト"

# YARD::Templates::Helpers::HtmlHelper#html_markup_html
#: ../lib/yard/templates/helpers/html_helper.rb:120
msgid "Converts HTML to HTML"
msgstr "HTMLからHTMLへ変換する"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:123
msgid "input html"
msgstr "htmlを入力する"

# YARD::Templates::Helpers::HtmlHelper#html_markup_ruby
#: ../lib/yard/templates/helpers/html_helper.rb:128
msgid ""
"Highlights Ruby source. Similar to {#html_syntax_highlight}, but\n"
"this method is meant to be called from {#htmlify} when markup is\n"
"set to \"ruby\"."
msgstr ""
"Rubyのソースをハイライトする。\n"
"{#html_syntax_highlight}メソッドと同様である。\n"
"しかし、このメソッドはmarkupが\"ruby\"を設定する時に、\n"
"{#htmlify}メソッドから呼び出される事を意味している。"

# @param [String] source
#: ../lib/yard/templates/helpers/html_helper.rb:134
msgid "the Ruby source"
msgstr "Rubyのソース"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:134
msgid "the highlighted HTML"
msgstr "ハイライトされたHTML"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:139
msgid "HTMLified text as a single line (paragraphs removed)"
msgstr "単一の行として、HTML化された(パラグラフが削除された)テキスト"

# YARD::Templates::Helpers::HtmlHelper#html_syntax_highlight
#: ../lib/yard/templates/helpers/html_helper.rb:146
msgid "Syntax highlights +source+ in language +type+."
msgstr "構文は、+type+ の言語で +source+ をハイライトする。"

# YARD::Templates::Helpers::HtmlHelper#html_syntax_highlight
# YARD::Templates::Helpers::HtmlHelper#html_syntax_highlight_plain
#: ../lib/yard/templates/helpers/html_helper.rb:154
#: ../lib/yard/templates/helpers/html_helper.rb:165
msgid "Syntax Highlighting Source Code"
msgstr "ソースコードをハイライトする構文"

# @note
#: ../lib/yard/templates/helpers/html_helper.rb:154
msgid ""
"To support a specific language +type+, implement the method\n"
"+html_syntax_highlight_TYPE+ in this class."
msgstr ""
"特定の +type+ の言語をサポートするには、\n"
"このクラスの中の、+html_syntax_highlight_TYPE+メソッドを実装する。"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:154
msgid "the highlighted source"
msgstr "ハイライトされたソース"

# @param [Symbol] type
#: ../lib/yard/templates/helpers/html_helper.rb:154
msgid ""
"the language type (:ruby, :plain, etc). Use\n"
":plain for no syntax highlighting."
msgstr ""
"言語の型(:ruby, :plain, etc.)。\n"
"ハイライト無しの構文には、 :plain を使う"

# @param [String] source
#: ../lib/yard/templates/helpers/html_helper.rb:154
msgid "the source code to highlight"
msgstr "ハイライトするソースコード"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:165
msgid "unhighlighted source"
msgstr "ハイライトを戻されたソース"

# YARD::Templates::Helpers::HtmlHelper#resolve_links
#: ../lib/yard/templates/helpers/html_helper.rb:172
msgid ""
"Resolves any text in the form of +{Name}+ to the object specified by\n"
"Name. Also supports link titles in the form +{Name title}+."
msgstr ""
"Nameによって指定されたオブジェクトに +{Name}+ の形式で\n"
"任意のテキストを解決する。\n"
"さらに、 +{Name title}+ 形式のタイトルのリンクもサポートする。"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:180
msgid "HTML with linkified references"
msgstr "リンクされた参照を用いたHTML"

# @example Linking to a class with a title
#: ../lib/yard/templates/helpers/html_helper.rb:180
msgid ""
"resolve_links(\"{A::B::C the C class}\") # => \"the c class"
"\""
msgstr ""

# @example Linking to an instance method
#: ../lib/yard/templates/helpers/html_helper.rb:180
msgid ""
"resolve_links(\"{MyClass#method}\") # => \"MyClass#method\""
msgstr ""

# @example
#: ../lib/yard/templates/helpers/html_helper.rb:180
msgid "tag|example|Linking to a class with a title"
msgstr "タイトルと共にクラスにリンクする"

# @example
#: ../lib/yard/templates/helpers/html_helper.rb:180
msgid "tag|example|Linking to an instance method"
msgstr "インスタンスメソッドにリンクする"

# @param [String] text
#: ../lib/yard/templates/helpers/html_helper.rb:180
msgid "the text to resolve links in"
msgstr "リンクを解決する為のテキスト"

# YARD::Templates::Helpers::HtmlHelper#anchor_for
# YARD::Templates::Helpers::HtmlHelper#url_for
# YARD::Templates::Helpers::HtmlHelper#url_for_file
#: ../lib/yard/templates/helpers/html_helper.rb:288
#: ../lib/yard/templates/helpers/html_helper.rb:309
#: ../lib/yard/templates/helpers/html_helper.rb:342
#: ../lib/yard/templates/helpers/html_helper.rb:364
#: ../lib/yard/templates/helpers/html_helper.rb:372
#: ../lib/yard/templates/helpers/html_helper.rb:380
#: ../lib/yard/templates/helpers/html_helper.rb:388
msgid "URL Helpers"
msgstr ""

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:288
msgid "the anchor for a specific object"
msgstr "固有のオブジェクト用のアンカー"

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/helpers/html_helper.rb:288
msgid "the object to get an anchor for"
msgstr "アンカーを取得するオブジェクト"

# YARD::Templates::Helpers::HtmlHelper#url_for
#: ../lib/yard/templates/helpers/html_helper.rb:304
msgid "Returns the URL for an object."
msgstr "オブジェクト用にURLを返す"

# @param [Boolean]
#: ../lib/yard/templates/helpers/html_helper.rb:309
msgid "tag|param|relative"
msgstr "relative"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:309
msgid "the URL location of the object"
msgstr "オブジェクトのURLの場所"

# @param [String] anchor
#: ../lib/yard/templates/helpers/html_helper.rb:309
msgid "the anchor to link to"
msgstr "リンクするアンカー"

# @param [String, CodeObjects::Base] obj
#: ../lib/yard/templates/helpers/html_helper.rb:309
msgid "the object (or object path) to link to"
msgstr "リンクするオブジェクト(又は、オブジェクトパス)"

# @param [Boolean] relative
#: ../lib/yard/templates/helpers/html_helper.rb:309
msgid "use a relative or absolute link"
msgstr "相対or絶対リンクを使うかどうか(trueで相対リンク)"

# YARD::Templates::Helpers::HtmlHelper#url_for_file
#: ../lib/yard/templates/helpers/html_helper.rb:338
msgid "Returns the URL for a specific file"
msgstr "固有のファイル用のURLを返す"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:342
msgid "the URL pointing to the file"
msgstr "ファイルの場所を指し示す、URL"

# YARD::Templates::Helpers::HtmlHelper#url_for_file
#: ../lib/yard/templates/helpers/html_helper.rb:360
msgid "Returns the URL for a list type"
msgstr "リストのタイプ用にURLを返す"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:364
msgid "the URL pointing to the list"
msgstr "リストの為の場所を示すURL"

# @param [ClassObject] klass
#: ../lib/yard/templates/helpers/html_helper.rb:364
msgid "the list type to generate a URL for"
msgstr "リストの型用のURLを生成するためのリストの型"

# YARD::Templates::Helpers::HtmlHelper#url_for_file
#: ../lib/yard/templates/helpers/html_helper.rb:369
msgid "Returns the URL for the frameset page"
msgstr "フレームセットページ用のURLを返す"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:372
msgid "the URL pointing to the frames page"
msgstr "フレームページのURLのポイント"

# YARD::Templates::Helpers::HtmlHelper#url_for_main
#: ../lib/yard/templates/helpers/html_helper.rb:377
msgid "Returns the URL for the main page (README or alphabetic index)"
msgstr ""

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:380
#: ../lib/yard/templates/helpers/html_helper.rb:388
msgid ""
"the URL pointing to the first main page the\n"
"user should see."
msgstr "ユーザーが調べる最初のメインページの為のURLのポイント"

# YARD::Templates::Helpers::HtmlHelper#format_object_name_list
#: ../lib/yard/templates/helpers/html_helper.rb:395
msgid "Formats a list of objects and links them"
msgstr "オブジェクトのリストをフォーマットし、それをリンクする。"

# YARD::Templates::Helpers::HtmlHelper#format_object_name_list
# YARD::Templates::Helpers::HtmlHelper#format_types
# YARD::Templates::Helpers::HtmlHelper#signature_types
# YARD::Templates::Helpers::HtmlHelper#signature
#: ../lib/yard/templates/helpers/html_helper.rb:396
#: ../lib/yard/templates/helpers/html_helper.rb:414
#: ../lib/yard/templates/helpers/html_helper.rb:430
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "Formatting Objects and Attributes"
msgstr "オブジェクトと属性をフォーマットする。"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:396
msgid "a formatted list of objects"
msgstr "フォーマットされたオブジェクトのリストを返す"

# YARD::Templates::Helpers::HtmlHelper#format_types
#: ../lib/yard/templates/helpers/html_helper.rb:403
msgid "Formats a list of types from a tag."
msgstr "タグから型のリストをフォーマットする。"

# @param [Boolean] brackets
#: ../lib/yard/templates/helpers/html_helper.rb:414
msgid ""
"omits the surrounding\n"
"brackets if +brackets+ is set to +false+."
msgstr ""
"+brackets+ に +false+ が設定された場合、\n"
"周りのブラケット(括弧)を除外する。"

# @param [Array, FalseClass]
#: ../lib/yard/templates/helpers/html_helper.rb:414
msgid "tag|param|typelist"
msgstr "typelist"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:414
msgid ""
"the list of types formatted\n"
"as [Type1, Type2, ...] with the types linked\n"
"to their respective descriptions."
msgstr ""
"それらの関連する説明にリンクした型と共に、\n"
"[Type1, Type2, ...]としてフォーマットされた型のリスト"

# @param [Array, FalseClass] typelist
#: ../lib/yard/templates/helpers/html_helper.rb:414
msgid "the list of types to be formatted."
msgstr "フォーマットされる型のリスト"

# YARD::Templates::Helpers::HtmlHelper#signature_types
#: ../lib/yard/templates/helpers/html_helper.rb:425
msgid "Get the return types for a method signature."
msgstr "メソッドのシグネチャ用に、返す型を取得する。"

# @param [Boolean]
#: ../lib/yard/templates/helpers/html_helper.rb:430
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "tag|param|link"
msgstr "link"

# @param [CodeObjects::MethodObject] meth
#: ../lib/yard/templates/helpers/html_helper.rb:430
msgid "the method object"
msgstr "メソッドのオブジェクト"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:430
msgid "the signature types"
msgstr "シグネチャの型"

# @param [Boolean] link
#: ../lib/yard/templates/helpers/html_helper.rb:430
msgid "whether to link the types"
msgstr "型をリンクするかどうか"

# YARD::Templates::Helpers::HtmlHelper#signature
#: ../lib/yard/templates/helpers/html_helper.rb:459
msgid "Formats the signature of method +meth+."
msgstr "+meth+ メソッドのシグネチャをフォーマットする"

# @param [Boolean]
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "tag|param|full_attr_name"
msgstr "full_attr_name"

# @param [Boolean]
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "tag|param|show_extras"
msgstr "show_extras"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "the formatted method signature"
msgstr "フォーマットされたメソッドのシグネチャ"

# @param [CodeObjects::MethodObject] meth
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid ""
"the method object to list\n"
"the signature of"
msgstr "シグネチャを記述するメソッドオブジェクト"

# @param [Boolean] link
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "whether to link the method signature to the details view"
msgstr "詳細の一覧にメソッドのシグネチャをリンクするかどうか"

# @param [Boolean] show_extras
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid "whether to show extra meta-data (visibility, attribute info)"
msgstr "追加のメタデータを見せるかどうか(可視性、infoの属性)"

# @param [Boolean] full_attr_name
#: ../lib/yard/templates/helpers/html_helper.rb:467
msgid ""
"whether to show the full attribute name\n"
"(\"name=\" instead of \"name\")"
msgstr "完全なnameの属性を見せるかどうか(\"name=\" instead of \"name\")"

# YARD::Templates::Helpers::HtmlHelper#charset
#: ../lib/yard/templates/helpers/html_helper.rb:504
msgid ""
"Returns the current character set. The default value can be overridden\n"
"by setting the +LANG+ environment variable or by overriding this\n"
"method. In Ruby 1.9 you can also modify this value by setting\n"
"+Encoding.default_external+."
msgstr ""
"現在の文字集合を返す。\n"
"デフォルトの値は、 +LANG+ 環境変数を設定したり、このメソッドを上書きする事に"
"よって\n"
"上書きできる。\n"
"又、Ruby1.9では +Encoding.default_external+ を設定する事によって、\n"
"この値を変更できる。"

# YARD::Templates::Helpers::HtmlHelper#charset
#: ../lib/yard/templates/helpers/html_helper.rb:510
#: ../lib/yard/templates/helpers/html_helper.rb:536
#: ../lib/yard/templates/helpers/html_helper.rb:542
#: ../lib/yard/templates/helpers/html_helper.rb:557
#: ../lib/yard/templates/helpers/html_helper.rb:572
msgid "Getting the Character Encoding"
msgstr "Character Encodingを取得する"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:510
msgid "the current character set"
msgstr "現在の文字集合"

# YARD::Templates::Helpers::HtmlHelper#tag_attrs
#: ../lib/yard/templates/helpers/html_helper.rb:533
msgid "Converts a set of hash options into HTML attributes for a tag"
msgstr "タグ用にHTML属性へハッシュのオプションのグループを変換する。"

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:536
msgid "the tag attributes of an HTML tag"
msgstr "HTMLタグのタグ属性"

# @param [Hash{String => String}] opts
#: ../lib/yard/templates/helpers/html_helper.rb:536
msgid "the tag options"
msgstr "そのタグのオプション"

# YARD::Templates::Helpers::HtmlHelper#convert_method_to_overload
#: ../lib/yard/templates/helpers/html_helper.rb:541
msgid "Converts a {CodeObjects::MethodObject} into an overload object"
msgstr "上書きするオブジェクトへ{CodeObjects::MethodObject}を変換する"

# YARD::Templates::Helpers::HtmlHelper#parse_lang_for_codeblock
#: ../lib/yard/templates/helpers/html_helper.rb:551
msgid ""
"Parses !!!lang out of codeblock, returning the codeblock language\n"
"followed by the source code."
msgstr ""

# @since
#: ../lib/yard/templates/helpers/html_helper.rb:557
msgid "0.7.5"
msgstr ""

# @return [Array(String, String)]
#: ../lib/yard/templates/helpers/html_helper.rb:557
msgid ""
"the language, if any, and the\n"
"remaining source"
msgstr ""

# @param [String] source
#: ../lib/yard/templates/helpers/html_helper.rb:557
msgid "the source code whose language to determine"
msgstr "どの言語か決める為のソースコード"

# YARD::Templates::Helpers::HtmlHelper#parse_codeblocks
#: ../lib/yard/templates/helpers/html_helper.rb:567
msgid ""
"Parses code blocks out of html and performs syntax highlighting\n"
"on code inside of the blocks."
msgstr ""

# @return [String]
#: ../lib/yard/templates/helpers/html_helper.rb:572
msgid "highlighted html"
msgstr "ハイライトされたHTML"

# @param [String]
#: ../lib/yard/templates/helpers/html_helper.rb:572
msgid "tag|param|html"
msgstr ""

# @see
#: ../lib/yard/templates/helpers/html_helper.rb:572
msgid "tag|see|#html_syntax_highlight"
msgstr ""

# @param [String] name
#: ../lib/yard/templates/helpers/html_helper.rb:572
msgid "the html to search for code in"
msgstr "HTMLの中のコード用に検索するためのHTML"

# YARD::Templates::Helpers::HtmlSyntaxHighlightHelper
#: ../lib/yard/templates/helpers/html_syntax_highlight_helper.rb:5
msgid "Helper methods for syntax highlighting."
msgstr "構文ハイライト用のHelperメソッド"

# YARD::Templates::Helpers::HtmlSyntaxHighlightHelper#html_syntax_highlight_ruby
#: ../lib/yard/templates/helpers/html_syntax_highlight_helper.rb:7
msgid "Highlights Ruby source"
msgstr "Rubyのソースをハイライトする"

# @param [String] source
#: ../lib/yard/templates/helpers/html_syntax_highlight_helper.rb:9
msgid "the Ruby source code"
msgstr "Rubyのソースコード"

# @return [String]
#: ../lib/yard/templates/helpers/html_syntax_highlight_helper.rb:9
msgid "the highlighted Ruby source"
msgstr "ハイライトされたRubyのソース"

# @param value
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:23
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:68
msgid "the value to set the attribute from_path to."
msgstr "from_path属性を設定する値"

# YARD::Templates::Helpers::Markup::RDocMarkup#from_path
# YARD::Templates::Helpers::Markup::RDocMarkupToHtml#from_path
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:24
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:69
msgid "Returns the value of attribute from_path"
msgstr "from_path属性の値を返す"

# YARD::Templates::Helpers::Markup::RDocMarkup#from_path=
# YARD::Templates::Helpers::Markup::RDocMarkupToHtml#from_path=
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:24
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:69
msgid "Sets the attribute from_path"
msgstr "from_path属性を設定する"

# @return [RDocMarkup]
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:25
msgid "a new instance of RDocMarkup"
msgstr "RDocMarkupの新しいインスタンス"

# YARD::Templates::Helpers::Markup::RDocMarkup#fix_typewriter
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:42
msgid "Fixes RDoc behaviour with ++ only supporting alphanumeric text."
msgstr ""
"RDocの振舞いを修正する(アルファベットと数字を組み合わせたテキストのサポートだ"
"け追加)"

# @todo
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:44
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:62
msgid "Refactor into own SimpleMarkup subclass"
msgstr "自身をSimpleMarkupサブクラスへリファクタリング予定"

# YARD::Templates::Helpers::Markup::RDocMarkup#fix_dash_dash
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:59
msgid ""
"Don't allow -- to turn into — element. The chances of this being\n"
"some --option is far more likely than the typographical meaning."
msgstr ""
"--を—へ変換する事は許可していない。\n"
"表示している意味よりも、いくつかの--optionになる可能性が高い。"

# YARD::Templates::Helpers::Markup::RDocMarkupToHtml#handle_special_HYPERLINK
#: ../lib/yard/templates/helpers/markup/rdoc_markup.rb:71
msgid "Disable auto-link of URLs"
msgstr "URLの自動リンクを無効にする"

# YARD::Templates::Helpers::MarkupHelper
#: ../lib/yard/templates/helpers/markup_helper.rb:6
msgid "Helper methods for loading and managing markup types."
msgstr "読み込みと,型のmarkupの管理用のHelperメソッド"

# YARD::Templates::Helpers::MarkupHelper.clear_markup_cache
#: ../lib/yard/templates/helpers/markup_helper.rb:9
msgid "Clears the markup provider cache information. Mainly used for testing."
msgstr ""
"マークアッププロバイダーのキャッシュ情報を初期化する。\n"
"主にtest用に利用される。"

# @since
#: ../lib/yard/templates/helpers/markup_helper.rb:17
msgid "0.6.4"
msgstr ""

# @return [Hash{Symbol=>{(:provider,:class)=>Object}}]
#: ../lib/yard/templates/helpers/markup_helper.rb:17
msgid "the cached markup providers"
msgstr "キャッシュされたマークアッププロバイダー"

# YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS
#: ../lib/yard/templates/helpers/markup_helper.rb:23
msgid "The default list of markup providers for each markup type"
msgstr ""
"それぞれのマークアップの型用の\n"
"マークアッププロバイダーのデフォルトのリスト。"

# YARD::Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS
#: ../lib/yard/templates/helpers/markup_helper.rb:49
msgid ""
"Returns a list of extensions for various markup types. To register\n"
"extensions for a type, add them to the array of extensions for the\n"
"type."
msgstr ""
"様々なmarkupの型の為に拡張のリストを返す。\n"
"型用に拡張を記録するには、型用の拡張の配列に拡張を追加する。"

# YARD::Templates::Helpers::MarkupHelper::MARKUP_FILE_SHEBANG
#: ../lib/yard/templates/helpers/markup_helper.rb:62
msgid ""
"Contains the Regexp object that matches the shebang line of extra\n"
"files to detect the markup type."
msgstr ""
"markup型を認識する為に、\n"
"追加のファイルのshebang行にマッチする\n"
"Regexpオブジェクトを含んでいる。"

# YARD::Templates::Helpers::MarkupHelper#load_markup_provider
#: ../lib/yard/templates/helpers/markup_helper.rb:66
msgid ""
"Attempts to load the first valid markup provider in {MARKUP_PROVIDERS}.\n"
"If a provider is specified, immediately try to load it."
msgstr ""
"{MARKUP_PROVIDERS}で最初の有効なマークアップロバイダーを読み込む。\n"
"プロバイダーが指定される場合、直ぐにロードするか試す。"

# YARD::Templates::Helpers::MarkupHelper#load_markup_provider
#: ../lib/yard/templates/helpers/markup_helper.rb:69
msgid ""
"On success this sets `@markup_provider` and `@markup_class` to\n"
"the provider name and library constant class/module respectively for\n"
"the loaded provider."
msgstr ""
"これは成功した場合、プロバイダー名に\n"
"`@markup_provider`と`@markup_class`を設定し、\n"
"ロードされたプロバイダーの為に、\n"
"それぞれライブラリ,定数,クラス/モジュールとなる。"

# YARD::Templates::Helpers::MarkupHelper#load_markup_provider
#: ../lib/yard/templates/helpers/markup_helper.rb:73
msgid ""
"On failure this method will inform the user that no provider could be\n"
"found and exit the program."
msgstr ""
"失敗した場合、このメソッドは、\n"
"プロバイダーが見つける事ができないユーザーを知らせて、プラグラムを脱出するだ"
"ろう。"

# @return [Boolean]
#: ../lib/yard/templates/helpers/markup_helper.rb:76
msgid "whether the markup provider was successfully loaded."
msgstr "マークアップのプロバイダーが正常に読み込まれたかどうか"

# YARD::Templates::Helpers::MarkupHelper#markup_for_file
#: ../lib/yard/templates/helpers/markup_helper.rb:108
msgid ""
"Checks for a shebang or looks at the file extension to determine\n"
"the markup type for the file contents. File extensions are registered\n"
"for a markup type in {MARKUP_EXTENSIONS}."
msgstr ""
"shebangをチェックし、\n"
"ファイルの内容の為にマークアップの型を決めるファイル拡張子を探す。\n"
"ファイル拡張子は、{MARKUP_EXTENSIONS}のマークアップの型が記録される。"

# YARD::Templates::Helpers::MarkupHelper#markup_for_file
#: ../lib/yard/templates/helpers/markup_helper.rb:112
msgid "A shebang should be on the first line of a file and be in the form:"
msgstr "shebangは、ファイルの最初の行になり、次のような形式となる。"

# YARD::Templates::Helpers::MarkupHelper#markup_for_file
#: ../lib/yard/templates/helpers/markup_helper.rb:114
msgid "  #!markup_type"
msgstr ""

# YARD::Templates::Helpers::MarkupHelper#markup_for_file
#: ../lib/yard/templates/helpers/markup_helper.rb:116
msgid "Standard markup types are text, html, rdoc, markdown, textile"
msgstr "標準のマークアップは、text,htmlcrdoc,markdown,textileとなる。"

# @param [String] contents
#: ../lib/yard/templates/helpers/markup_helper.rb:122
msgid ""
"Unused. Was necessary prior to 0.7.0.\n"
"Newer versions of YARD use {CodeObjects::ExtraFileObject#contents}"
msgstr ""
"利用されない。0.7.0.より前では、必須だった。\n"
"YARDの最新バージョンでは、{CodeObjects::ExtraFileObject#contents}を用いる。"

# @see
#: ../lib/yard/templates/helpers/markup_helper.rb:122
msgid "tag|see|MARKUP_EXTENSIONS"
msgstr ""

# @return [Symbol]
#: ../lib/yard/templates/helpers/markup_helper.rb:122
msgid "the markup type recognized for the file"
msgstr "ファイルに認識されたマークアップタイプ"

# YARD::Templates::Helpers::MarkupHelper#markup_file_contents
#: ../lib/yard/templates/helpers/markup_helper.rb:135
msgid ""
"Strips any shebang lines on the file contents that pertain to\n"
"markup or preprocessing data."
msgstr ""
"マークアップや処理するデータに関係があるファイルの内容の\n"
"任意のshebang行をStripする。"

# @deprecated
#: ../lib/yard/templates/helpers/markup_helper.rb:140
msgid "Use {CodeObjects::ExtraFileObject#contents} instead"
msgstr "替わりに{CodeObjects::ExtraFileObject#contents}を使う"

# @return [String]
#: ../lib/yard/templates/helpers/markup_helper.rb:140
msgid "the file contents minus any preprocessing tags"
msgstr ""
"ファイルの内容が任意のtagを表す\n"
"\n"

# YARD::Templates::Helpers::MarkupHelper#markup_class
#: ../lib/yard/templates/helpers/markup_helper.rb:145
msgid ""
"Gets the markup provider class/module constant for a markup type\n"
"Call {#load_markup_provider} before using this method."
msgstr ""
"マークアップ型がこのメソッドを使う前に{#load_markup_provider}を呼び出すマーク"
"アッププロバイダーのクラス/モジュールの定数を取得する。"

# @return [Class]
#: ../lib/yard/templates/helpers/markup_helper.rb:149
msgid "the markup class"
msgstr "マークアップのクラス"

# @param [Symbol] the
#: ../lib/yard/templates/helpers/markup_helper.rb:149
#: ../lib/yard/templates/helpers/markup_helper.rb:159
msgid "the markup type (:rdoc, :markdown, etc.)"
msgstr "マークアップの型(:rdoc, :markdown, etc.)"

# YARD::Templates::Helpers::MarkupHelper#markup_provider
#: ../lib/yard/templates/helpers/markup_helper.rb:155
msgid ""
"Gets the markup provider name for a markup type\n"
"Call {#load_markup_provider} before using this method."
msgstr ""
"マークアップ型がこのメソッド使う前に{#load_markup_provider}を呼び出すマーク"
"アッププロバイダー名を取得する。"

# @return [Symbol]
#: ../lib/yard/templates/helpers/markup_helper.rb:159
msgid "the markup provider name (usually the gem name of the library)"
msgstr "マークアッププロバイダー名(慣習では、ライブラリのgem名)"

# YARD::Templates::Helpers::MethodHelper
#: ../lib/yard/templates/helpers/method_helper.rb:4
msgid "Helper methods for method objects."
msgstr "メソッドオブジェクト用のHelperメソッド"

# @return [String]
#: ../lib/yard/templates/helpers/method_helper.rb:6
msgid "formatted arguments for a method"
msgstr "メソッド用にフォーマットされた引数"

# @return [String]
#: ../lib/yard/templates/helpers/method_helper.rb:25
msgid "formatted and linked return types for a method"
msgstr "メソッド用にフォーマットとリンクされた型を返す"

# @return [String]
#: ../lib/yard/templates/helpers/method_helper.rb:32
msgid "formatted block if one exists"
msgstr "何か渡された場合、フォーマットされたブロックを返す"

# @return [String]
#: ../lib/yard/templates/helpers/method_helper.rb:47
msgid "formats line numbers for source code of an object"
msgstr "オブジェクトのソースコード用に行数をフォーマットする"

# @return [String]
#: ../lib/yard/templates/helpers/method_helper.rb:54
msgid "formats source of an object"
msgstr "オブジェクトのソースをフォーマットする"

# @return [String]
#: ../lib/yard/templates/helpers/method_helper.rb:65
msgid "formats source code of a constant value"
msgstr "定数の値の入ったソースコードをフォーマットする"

# YARD::Templates::Helpers::ModuleHelper
#: ../lib/yard/templates/helpers/module_helper.rb:5
msgid "Helper methods for managing module objects."
msgstr "モジュールオブジェクトを管理用のHelperメソッド"

# YARD::Templates::Helpers::ModuleHelper#prune_method_listing
#: ../lib/yard/templates/helpers/module_helper.rb:7
msgid ""
"Prunes the method listing by running the verifier and removing attributes/"
"aliases"
msgstr ""
"verifierを起動する事によって、メソッドのリストを切り詰め、属性/エイリアスを削"
"除する。"

# @return [Array]
#: ../lib/yard/templates/helpers/module_helper.rb:10
msgid "a pruned list of methods"
msgstr "切り詰められたメソッドのリスト"

# @param [Boolean]
#: ../lib/yard/templates/helpers/module_helper.rb:10
msgid "tag|param|hide_attributes"
msgstr "hide_attributes"

# @param [Boolean] hide_attributes
#: ../lib/yard/templates/helpers/module_helper.rb:10
msgid "whether to prune attribute methods from the list"
msgstr "リストからメソッドの属性を切り詰めるかどうか"

# YARD::Templates::Helpers::TextHelper
#: ../lib/yard/templates/helpers/text_helper.rb:5
msgid "Helper methods for text template formats."
msgstr "テキストテンプレートフォーマット用のHelperメソッド"

# @return [String]
#: ../lib/yard/templates/helpers/text_helper.rb:7
msgid "escapes text"
msgstr "テキストをエスケープする"

# @return [String]
#: ../lib/yard/templates/helpers/text_helper.rb:22
msgid "wraps text at +col+ columns."
msgstr "+col+ 列でテキストをラップする。"

# @return [String]
#: ../lib/yard/templates/helpers/text_helper.rb:27
msgid "indents +text+ by +len+ characters."
msgstr "+len+ 文字で +text+ をインデントする"

# @return [String]
#: ../lib/yard/templates/helpers/text_helper.rb:32
msgid "aligns a title to the right"
msgstr "右にタイトルを並べる"

# @return [String]
#: ../lib/yard/templates/helpers/text_helper.rb:37
msgid "aligns text to the right"
msgstr "右にテキストを並べる"

# @return [String]
#: ../lib/yard/templates/helpers/text_helper.rb:43
msgid "returns a horizontal rule for output"
msgstr "出力用に横方向の罫線を返す"

# @return [String]
#: ../lib/yard/templates/helpers/text_helper.rb:48
msgid "the formatted signature for a method"
msgstr "メソッド用にフォーマットされたシグネチャ"

# YARD::Templates::Helpers::UMLHelper
#: ../lib/yard/templates/helpers/uml_helper.rb:4
msgid "Helpers for UML template format"
msgstr "UMLテンプレートフォーマット用のHelperメソッド"

# YARD::Templates::Helpers::UMLHelper#uml_visibility
#: ../lib/yard/templates/helpers/uml_helper.rb:6
msgid ""
"Official UML visibility prefix syntax for an object given its visibility"
msgstr "オブジェクト用に与えられた可視性の為の公式のUMLプレフィックス構文"

# @return [String]
#: ../lib/yard/templates/helpers/uml_helper.rb:8
msgid "the UML visibility prefix"
msgstr "UML可視性のプレフィックス"

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/helpers/uml_helper.rb:8
msgid "the object to retrieve visibility for"
msgstr "可視性を回収するオブジェクト"

# YARD::Templates::Helpers::UMLHelper#format_path
#: ../lib/yard/templates/helpers/uml_helper.rb:17
msgid "Formats the path of an object for Graphviz syntax"
msgstr "Graphviz構文用にオブジェクトのパスをフォーマットする。"

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/helpers/uml_helper.rb:19
msgid "an object to format the path of"
msgstr "パスをフォーマットするオブジェクト"

# @return [String]
#: ../lib/yard/templates/helpers/uml_helper.rb:19
msgid "the encoded path"
msgstr "エンコードされたパス"

# YARD::Templates::Helpers::UMLHelper#h
#: ../lib/yard/templates/helpers/uml_helper.rb:24
msgid "Encodes text in escaped Graphviz syntax"
msgstr "Graphviz構文用にエスケープされたテキストをエンコードする"

# @param [String] text
#: ../lib/yard/templates/helpers/uml_helper.rb:26
msgid "text to encode"
msgstr "エンコードするテキスト"

# @return [String]
#: ../lib/yard/templates/helpers/uml_helper.rb:26
msgid "the encoded text"
msgstr "エンコードされたテキスト"

# YARD::Templates::Helpers::UMLHelper#tidy
#: ../lib/yard/templates/helpers/uml_helper.rb:31
msgid "Tidies data by formatting and indenting text"
msgstr "フォーマットによってデータを整える、テキストをインデントする。"

# @param [String] data
#: ../lib/yard/templates/helpers/uml_helper.rb:33
msgid "pre-formatted text"
msgstr "フォーマットされる前のテキスト"

# @return [String]
#: ../lib/yard/templates/helpers/uml_helper.rb:33
msgid "tidied text."
msgstr "整えられたテキスト"

# YARD::Templates::Section
#: ../lib/yard/templates/section.rb:4
msgid ""
"Abstracts the structure for a section and its subsections into an ordered\n"
"list of sections and subsections."
msgstr ""
"セクションに構造体を抽象化し、セクションとサブセクションのオーダーされたリス"
"トをサブサクションにする。"

# @return [Section]
#: ../lib/yard/templates/section.rb:9
msgid "a new instance of Section"
msgstr "セクションの新しいインスタンス"

# @param value
#: ../lib/yard/templates/template.rb:6
msgid "the value to set the attribute class to."
msgstr "class属性を設定する値"

# @param value
#: ../lib/yard/templates/template.rb:6
msgid "the value to set the attribute section to."
msgstr "section属性を設定する値"

# YARD::Templates::Template#class
#: ../lib/yard/templates/template.rb:7
msgid "Returns the value of attribute class"
msgstr "class属性の値を返す"

# YARD::Templates::Template#section
#: ../lib/yard/templates/template.rb:7
msgid "Returns the value of attribute section"
msgstr "section属性の値を返す"

# YARD::Templates::Template#class=
#: ../lib/yard/templates/template.rb:7
msgid "Sets the attribute class"
msgstr "classの属性を設定する"

# YARD::Templates::Template#section=
#: ../lib/yard/templates/template.rb:7
msgid "Sets the attribute section"
msgstr "section属性を設定する"

# YARD::Server::Commands::LibraryIndexCommand#options
# YARD::Templates::Template#options
#: ../lib/yard/templates/template.rb:8
msgid "Returns the value of attribute options"
msgstr "options属性の値を返す"

# YARD::Templates::Template.extra_includes
# YARD::Templates::Template.extra_includes=
#: ../lib/yard/templates/template.rb:11
msgid ""
"Extra includes are mixins that are included after a template is created. "
"These\n"
"mixins can be registered by plugins to operate on templates and override "
"behaviour."
msgstr ""

# YARD::Templates::Template.extra_includes
# YARD::Templates::Template.extra_includes=
#: ../lib/yard/templates/template.rb:14
msgid ""
"Note that this array can be filled with modules or proc objects. If a proc "
"object\n"
"is given, the proc will be called with the {Template#options} hash "
"containing\n"
"relevant template information like the object, format, and more. The proc "
"should\n"
"return a module or nil if there is none."
msgstr ""

# @example Adding in extra mixins to include on a template
#: ../lib/yard/templates/template.rb:24
msgid "Template.extra_includes << MyHelper"
msgstr ""

# @example Conditionally including a mixin if the format is html
#: ../lib/yard/templates/template.rb:24
msgid ""
"Template.extra_includes << proc {|opts| MyHelper if opts.format == :html }"
msgstr ""

# @return [Array]
#: ../lib/yard/templates/template.rb:24
msgid ""
"a list of modules to be automatically included\n"
"into any new template module"
msgstr ""
"任意の新しいテンプレートモジュールへ自動でインクルードされるモジュールのリス"
"ト"

# @example
#: ../lib/yard/templates/template.rb:24
msgid "tag|example|Adding in extra mixins to include on a template"
msgstr "tag|example|テンプレート上でincludeするために追加のmixinを追加する"

# @example
#: ../lib/yard/templates/template.rb:24
msgid "tag|example|Conditionally including a mixin if the format is html"
msgstr ""

# YARD::Templates::Template.include_extra
#: ../lib/yard/templates/template.rb:33
msgid "Includes the {extra_includes} modules into the template object."
msgstr ""

# @param [Template]
#: ../lib/yard/templates/template.rb:37
msgid "tag|param|template"
msgstr "tag|param|template"

# @return [LibraryVersion]
#: ../lib/yard/templates/template.rb:37
msgid "the options hash containing all template information"
msgstr "ハッシュのオプションは全てのテンプレート情報を含んでいる"

# @param [CodeObjects::Base] object
#: ../lib/yard/templates/template.rb:37
msgid "the template object to mixin the extra includes."
msgstr "追加のincludeをmixinする為のテンプレートオブジェクト"

# @param value
#: ../lib/yard/templates/template.rb:59
msgid "the value to set the attribute full_path to."
msgstr "full_path属性を設定する値"

# @param value
#: ../lib/yard/templates/template.rb:59
msgid "the value to set the attribute path to."
msgstr "path属性を設定する値"

# YARD::Templates::Template::ClassMethods#full_path
#: ../lib/yard/templates/template.rb:60
msgid "Returns the value of attribute full_path"
msgstr "full_path属性の値を返す"

# YARD::Templates::Template::ClassMethods#path
#: ../lib/yard/templates/template.rb:60
msgid "Returns the value of attribute path"
msgstr "path属性の値を返す"

# YARD::Templates::Template::ClassMethods#full_path=
#: ../lib/yard/templates/template.rb:60
msgid "Sets the attribute full_path"
msgstr "full_path属性を設定する"

# YARD::Templates::Template::ClassMethods#path=
#: ../lib/yard/templates/template.rb:60
msgid "Sets the attribute path"
msgstr "path属性を設定する"

# @return [ClassMethods]
#: ../lib/yard/templates/template.rb:68
msgid "a new instance of ClassMethods"
msgstr "ClassMethodsの新しいインスタンス"

# YARD::Templates::Template::ClassMethods#find_file
#: ../lib/yard/templates/template.rb:78
msgid ""
"Searches for a file identified by +basename+ in the template's\n"
"path as well as any mixed in template paths. Equivalent to calling\n"
"{ClassMethods#find_nth_file} with index of 1."
msgstr ""
"テンプレートパスも\n"
"任意の混ぜられたテンプレートパスも +basename+ でファイルが一致する為に検索す"
"る。\n"
"{ClassMethods#find_nth_file}メソッドを index 1 で呼び出すのと同様である。"

# @param [String]
#: ../lib/yard/templates/template.rb:85 ../lib/yard/templates/template.rb:96
#: ../lib/yard/templates/template.rb:290
msgid "tag|param|basename"
msgstr "basename"

# @see
#: ../lib/yard/templates/template.rb:85
msgid "tag|see|find_nth_file"
msgstr "find_nth_file"

# @param [String] basename
#: ../lib/yard/templates/template.rb:85 ../lib/yard/templates/template.rb:96
msgid "the filename to search for"
msgstr "検索するファイル名"

# @return [String]
#: ../lib/yard/templates/template.rb:85
msgid ""
"the full path of a file on disk with filename\n"
"+basename+ in one of the template's paths."
msgstr ""
"テンプレートパスの一つである +basename+ の入ったディスク上のファイルのフルパ"
"スを返す"

# YARD::Templates::Template::ClassMethods#find_nth_file
#: ../lib/yard/templates/template.rb:90
msgid ""
"Searches for the nth file (where n = +index+) identified\n"
"by basename in the template's path and any mixed in template paths."
msgstr ""
"n番目のファイルがテンプレートパスか任意の混ぜられたテンプレートパスのbasename"
"によって\n"
"一致するかサーチする。"

# @param [Fixnum]
#: ../lib/yard/templates/template.rb:96
msgid "tag|param|index"
msgstr "index"

# @return [String]
#: ../lib/yard/templates/template.rb:96
msgid ""
"the full path of the nth file on disk with\n"
"filename +basename+ in one of the template paths"
msgstr ""
"テンプレートパスの一つの +basename+ を用いたディスク上のn番目のファイルフルパ"
"ス"

# @param [Fixnum] index
#: ../lib/yard/templates/template.rb:96
msgid "the nth existing file to return"
msgstr "n番目に存在するファイルを戻すindex"

# YARD::Templates::Template::ClassMethods#new
#: ../lib/yard/templates/template.rb:115
msgid "Creates a new template object to be rendered with {Template#run}"
msgstr "{Template#run}と共に表示される新しいテンプレートオブジェクトを作成する"

# YARD::Templates::Template::ClassMethods#S
#: ../lib/yard/templates/template.rb:131
msgid "Alias for creating a {Section} with arguments"
msgstr "引数と共に{Section}の作成用のエイリアス"

# @see
#: ../lib/yard/templates/template.rb:133
msgid "tag|see|Section#initialize"
msgstr "Section#initialize"

# @return [Template]
#: ../lib/yard/templates/template.rb:166
msgid "a new instance of Template"
msgstr "テンプレートの新しいインスタンス"

# YARD::Templates::Template#T
#: ../lib/yard/templates/template.rb:177
msgid ""
"Loads a template specified by path. If +:template+ or +:format+ is\n"
"specified in the {#options} hash, they are prepended and appended\n"
"to the path respectively."
msgstr ""
"pathによって指定されたテンプレートをロードする。\n"
"+:template+ や +:format+ が{#options}ハッシュメソッドで指定される場合、\n"
"#optionsメソッドに関係するパスが前後に加えられる。"

# @return [Template]
#: ../lib/yard/templates/template.rb:182
msgid "the loaded template module"
msgstr "ロードされたテンプレートモジュール"

# @param [Array] path
#: ../lib/yard/templates/template.rb:182
msgid "the path of the template"
msgstr "テンプレートのパス"

# YARD::Templates::Template#sections
#: ../lib/yard/templates/template.rb:189
msgid "Sets the sections (and subsections) to be rendered for the template"
msgstr "テンプレート用に表示されるセクション(とサブサクション)を設定する。"

# @example Sets a set of method and erb sections
#: ../lib/yard/templates/template.rb:204
msgid "sections :a, :b, :c # a is a method, the rest are erb files"
msgstr ""

# @example Sets a set of erb sections
#: ../lib/yard/templates/template.rb:204
msgid "sections :a, :b, :c # searches for a.erb, b.erb, c.erb"
msgstr ""

# @example Sections with subsections
#: ../lib/yard/templates/template.rb:204
msgid ""
"sections :header, [:name, :children]\n"
"# the above will call header.erb and only renders the subsections\n"
"# if they are yielded by the template (see #yieldall)"
msgstr ""
"sections :header, [:name, :children]\n"
"# 上は、header.erbが呼び出され、subsectionをが表示する。\n"
"# テンプレートでyieldしたい場合は (see #yieldall) 参照"

# @example
#: ../lib/yard/templates/template.rb:204
msgid "tag|example|Sections with subsections"
msgstr "subsectionsを用いたsection"

# @example
#: ../lib/yard/templates/template.rb:204
msgid "tag|example|Sets a set of erb sections"
msgstr "erb sectionのグループを設置する"

# @example
#: ../lib/yard/templates/template.rb:204
msgid "tag|example|Sets a set of method and erb sections"
msgstr "メソッドのグループとercセクションを設定する"

# @param [Array] args
#: ../lib/yard/templates/template.rb:204
msgid ""
"the sections\n"
"to use to render the template. For symbols and strings, the\n"
"section will be executed as a method (if one exists), or rendered\n"
"from the file \"name.erb\" where name is the section name. For\n"
"templates, they will have {Template::ClassMethods#run} called on them.\n"
"Any subsections can be yielded to using yield or {#yieldall}"
msgstr ""
"テンプレートを表示する為に利用するセクション。\n"
"symbolとstringでセクションは、メソッドとして実行される。(存在する場合)\n"
"又、nameがsection名の所で\"name.erb\"ファイルから表示される\n"
"テンプレート用に、呼び出された{Template::ClassMethods#run}を持つだろう。\n"
"任意のsubsectionは、yieldや{#yieldall}メソッドによってyieldされる。"

# YARD::Templates::Template#init
#: ../lib/yard/templates/template.rb:210
msgid ""
"Initialization called on the template. Override this in a 'setup.rb'\n"
"file in the template's path to implement a template"
msgstr ""
"テンプレート上で呼び出される初期化処理。\n"
"テンプレートを実装するテンプレートのパスで'setup.rb'ファイルを上書きする。"

# @example A default set of sections
#: ../lib/yard/templates/template.rb:217
msgid ""
"def init\n"
"  sections :section1, :section2, [:subsection1, :etc]\n"
"end"
msgstr ""

# @example
#: ../lib/yard/templates/template.rb:217
msgid "tag|example|A default set of sections"
msgstr "セクションのデフォルトのグループ"

# @see
#: ../lib/yard/templates/template.rb:217
msgid "tag|see|#sections"
msgstr ""

# YARD::Templates::Template#run
#: ../lib/yard/templates/template.rb:221
msgid ""
"Runs a template on +sects+ using extra options. This method should\n"
"not be called directly. Instead, call the class method {ClassMethods#run}"
msgstr ""
"追加のオプションによって、+sects+上でテンプレートを起動する。\n"
"このメソッドは、直接呼び出されないだろう。\n"
"代わりに、{ClassMethods#run}クラスメソッドを呼び出す。"

# @param [Section, Array] sects
#: ../lib/yard/templates/template.rb:230
msgid "a section list of sections to render"
msgstr "表示する為のsectionのリスト"

# @param [Hash, nil] opts
#: ../lib/yard/templates/template.rb:230
msgid "any extra options to apply to sections"
msgstr "sectionsに適用する任意の追加のオプション"

# @yieldparam [Hash] opts
#: ../lib/yard/templates/template.rb:230
msgid "any extra options to yield"
msgstr "yieldする任意の追加のオプション"

# @yield [opts]
#: ../lib/yard/templates/template.rb:230
msgid "calls for the subsections to be rendered"
msgstr "表示されるサブセクション用に呼び出される"

# @param [Boolean] break_first
#: ../lib/yard/templates/template.rb:230
msgid "if true, renders only the first section"
msgstr "trueなら、最初のセクションだけ表示される"

# @param [Boolean]
#: ../lib/yard/templates/template.rb:230
msgid "tag|param|break_first"
msgstr " break_first"

# @param [Section, Array]
#: ../lib/yard/templates/template.rb:230
msgid "tag|param|sects"
msgstr "sects"

# @param [Fixnum]
#: ../lib/yard/templates/template.rb:230
msgid "tag|param|start_at"
msgstr "start_at"

# @yieldparam [Hash]
#: ../lib/yard/templates/template.rb:230
msgid "tag|yieldparam|opts"
msgstr ""

# @param [Fixnum] start_at
#: ../lib/yard/templates/template.rb:230
msgid "the index in the section list to start from"
msgstr "セクションのリストの最初のindex"

# @return [String]
#: ../lib/yard/templates/template.rb:230
msgid "the rendered sections joined together"
msgstr "一緒に加えられた,表示されたsection"

# YARD::Templates::Template#yieldall
#: ../lib/yard/templates/template.rb:254
msgid "Yields all subsections with any extra options"
msgstr "任意の追加のオプションと共に全てのサブセクションをyieldする。"

# @param [Hash] opts
#: ../lib/yard/templates/template.rb:256
msgid "extra options to be applied to subsections"
msgstr "サブセクションに適用される追加のオプション"

# @yield
#: ../lib/yard/templates/template.rb:263
msgid "calls subsections to be rendered"
msgstr "表示されるサブセクションを呼び出す"

# @param [String, Symbol]
# @param [Symbol, String]
#: ../lib/yard/templates/template.rb:263 ../lib/yard/templates/template.rb:308
msgid "tag|param|section"
msgstr "section"

# @return [String]
#: ../lib/yard/templates/template.rb:263
msgid "the contents of the ERB rendered section"
msgstr "セクションに表示されるERBの内容"

# @param [String, Symbol] section
#: ../lib/yard/templates/template.rb:263
msgid "the section name"
msgstr "セクション名"

# YARD::Templates::Template#file
#: ../lib/yard/templates/template.rb:271
msgid ""
"Returns the contents of a file. If +allow_inherited+ is set to +true+,\n"
"use +{{{__super__}}}+ inside the file contents to insert the contents\n"
"of the file from an inherited template. For instance, if +templates/b+\n"
"inherits from +templates/a+ and file \"test.css\" exists in both "
"directories,\n"
"both file contents can be retrieved by having +templates/b/test.css+ look\n"
"like:"
msgstr ""
"ファイルの内容を返す。\n"
"+allow_inherited+ が +true+ に設定される場合、\n"
"継承されたテンプレートから\n"
"ファイルの入った内容を挿入する為、\n"
"ファイルの内容の内部で\n"
"+{{{__super__}}}+ を使う。\n"
"例えば、 +templates/b+ が +templates/a+ から継承され、 \"test.css\"ファイルが"
"存在する\n"
"ディレクトリの中で両方とも存在している場合、\n"
"両方ファイルの内容は、以下の用に\n"
"+templates/b/test.css+ を持つ事によって回収できる。"

# YARD::Templates::Template#file
#: ../lib/yard/templates/template.rb:278
msgid ""
"  {{{__super__}}}\n"
"  ...\n"
"  body { css styles here }\n"
"  p.class { other styles }"
msgstr ""

# @param [Boolean]
#: ../lib/yard/templates/template.rb:290
msgid "tag|param|allow_inherited"
msgstr "allow_inherited"

# @see
#: ../lib/yard/templates/template.rb:290
msgid "tag|see|ClassMethods#find_file"
msgstr ""

# @see
#: ../lib/yard/templates/template.rb:290
msgid "tag|see|ClassMethods#find_nth_file"
msgstr ""

# @return [String]
#: ../lib/yard/templates/template.rb:290
msgid ""
"the contents of a file identified by +basename+. All\n"
"template paths (including any mixed in templates) are searched for\n"
"the file"
msgstr ""
"+basename+ によって指定されたファイルの内容。\n"
"全てのテンプレートパスは(任意の混ぜられたテンプレートを含んでいる)、\n"
"ファイル用に検索される。"

# @param [String] basename
#: ../lib/yard/templates/template.rb:290
msgid "the name of the file"
msgstr "ファイルの名前"

# @param [Boolean] allow_inherited
#: ../lib/yard/templates/template.rb:290
msgid ""
"whether inherited templates can\n"
"be inserted with +{{{__super__}}}+"
msgstr "継承されたテンプレートが +{{{__super__}}}+ を用いて継承されるかどうか"

# YARD::Templates::Template#superb
#: ../lib/yard/templates/template.rb:304
msgid "Calls the ERB file from the last inherited template with {#section}.erb"
msgstr ""
"{#section}.erbと共に継承されたテンプレートの最後からERBファイルを呼び出す。"

# @param [Symbol, String] section
#: ../lib/yard/templates/template.rb:308
msgid "if provided, uses a specific section name"
msgstr "提供された場合、固有のセクション名を使う"

# @return [String]
#: ../lib/yard/templates/template.rb:308
msgid ""
"the rendered ERB file in any of the inherited template\n"
"paths."
msgstr "継承されたテンプレートパスの任意で表示されるERBファイル"

# YARD::Templates::TemplateOptions
#: ../lib/yard/templates/template_options.rb:6
msgid ""
"An Options class containing default options for base template rendering. "
"For\n"
"options specific to generation of HTML output, see {CLI::YardocOptions}."
msgstr ""

# @see
#: ../lib/yard/templates/template_options.rb:9
msgid "tag|see|CLI::YardocOptions"
msgstr ""

# @param [String] text
#: ../lib/yard/templates/template_options.rb:11
msgid "the template output format"
msgstr "テンプレート出力のフォーマット"

# @param [String] path
#: ../lib/yard/templates/template_options.rb:14
msgid "the template name used to render output"
msgstr "出力を表示するため利用されたテンプレート名"

# @param value
#: ../lib/yard/templates/template_options.rb:17
msgid "the markup format to use when parsing docstrings"
msgstr "docstringを解析する時に使うためのマークアップフォーマット"

# YARD::Templates::Helpers::HtmlHelper#signature_types
#: ../lib/yard/templates/template_options.rb:20
msgid "the default return type for a method with no return tags"
msgstr "returnタグを用いないメソッド用のデフォルトの戻りの型"

# @return [Boolean]
#: ../lib/yard/templates/template_options.rb:23
msgid "whether void methods should show \"void\" in their signature"
msgstr ""

# @param [String] source
#: ../lib/yard/templates/template_options.rb:26
msgid "whether code blocks should be syntax highlighted"
msgstr "コードブロックが構文ハイライトされるかどうか"

# YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS
#: ../lib/yard/templates/template_options.rb:29
msgid "the markup provider class for the markup format"
msgstr "マークアップフォーマット用のマークアッププロバイダークラス"

# @return [OpenStruct]
#: ../lib/yard/templates/template_options.rb:33
msgid ""
"an open struct containing any global state across all\n"
"generated objects in a template."
msgstr ""
"テンプレートの中で生成された全てのオブジェクトに渡って\n"
"全てのglobalの状態を含んでいるopen struct"

# @return [Template]
#: ../lib/yard/templates/template_options.rb:37
msgid "the main object being generated in the template"
msgstr "テンプレートの中で生成されるメインオブジェクト"

# YARD::CodeObjects::Base#name
# YARD::CodeObjects::Proxy#name
#: ../lib/yard/templates/template_options.rb:40
msgid "the owner of the generated object"
msgstr "生成されたオブジェクトのオーナー"

# @return [Boolean]
#: ../lib/yard/templates/template_options.rb:43
msgid "the template type used to generate output"
msgstr "出力を生成するために使ったテンプレートタイプ"

# @return [Boolean]
#: ../lib/yard/templates/template_options.rb:46
msgid "whether serialization should be performed"
msgstr "シリアライズが実行されるかどうか"

# @return [Serializers::Base]
#: ../lib/yard/templates/template_options.rb:50
msgid ""
"the serializer used to generate links and serialize\n"
"output. Serialization output only occurs if {#serialize} is +true+."
msgstr ""

# @deprecated
#: ../lib/yard/templates/template_options.rb:54
#: ../lib/yard/templates/template_options.rb:56
msgid "use {#highlight} instead."
msgstr ""

# @return [String]
#: ../lib/yard/templates/template_options.rb:54
#: ../lib/yard/templates/template_options.rb:56
msgid "whether highlighting should be ignored"
msgstr "ハイライトが無視されるかどうか"

# @param [String] title
#: ../lib/yard/templates/template_options.rb:60
msgid "the title of a given page"
msgstr "与えられたページのタイトル"

# @return [Array]
#: ../lib/yard/templates/template_options.rb:68
msgid ""
"an array of module name wildcards to embed into\n"
"class documentation as if their methods were defined directly in the class.\n"
"Useful for modules like ClassMethods. If the name contains '::', the module\n"
"is matched against the full mixin path, otherwise only the module name is "
"used."
msgstr ""

# @example A list of mixin path names (including wildcards)
#: ../lib/yard/templates/template_options.rb:68
msgid "opts.embed_mixins #=> ['ClassMethods', '*Helper', 'YARD::*']"
msgstr ""

# @example
#: ../lib/yard/templates/template_options.rb:68
msgid "tag|example|A list of mixin path names (including wildcards)"
msgstr ""

# @param [CodeObjects::Base] mixin
#: ../lib/yard/templates/template_options.rb:74
msgid ""
"accepts any code object, but returns\n"
"nil unless the object is a module."
msgstr ""

# @return [nil]
#: ../lib/yard/templates/template_options.rb:74
msgid "if the mixin is not a module object"
msgstr "mixinがモジュールオブジェクトでない場合"

# @param [Fixnum, nil]
#: ../lib/yard/templates/template_options.rb:74
msgid "tag|param|mixin"
msgstr "tag|param|mixin"

# @return [Boolean]
#: ../lib/yard/templates/template_options.rb:74
msgid "whether a mixin matches the embed_mixins list"
msgstr "mixinがembed_mixinsのリストにマッチするかどうか"

# @param [Serializers::Base] serializer
#: ../lib/yard/templates/template_options.rb:85
msgid "the verifier object"
msgstr "verifier(認証)オブジェクト"

# YARD::Verifier
#: ../lib/yard/verifier.rb:3
msgid ""
"Similar to a Proc, but runs a set of Ruby expressions using a small\n"
"DSL to make tag lookups easier."
msgstr ""
"Procと同様であるが、検索しやすいタグを作る為に、\n"
"ちょっとしたDSLによって、Rubyの式のグループを起動する。"

# YARD::Verifier
#: ../lib/yard/verifier.rb:6
msgid ""
"The syntax is as follows:\n"
"* All syntax is Ruby compatible\n"
"* +object+ (+o+ for short) exist to access the object being verified\n"
"* +@TAGNAME+ is translated into +object.tag('TAGNAME')+\n"
"* +@@TAGNAME+ is translated into +object.tags('TAGNAME')+\n"
"* +object+ can be omitted as target for method calls (it is implied)"
msgstr ""
"次の様な構文となる:\n"
"* 全ての構文は、Rubyと互換性がある。\n"
"* +object+ (略字は +o+)は検証されるオブジェクトにアクセスする為に存在する。\n"
"* +@TAGNAME+ は +object.tag('TAGNAME')+ の中で変換される\n"
"* +@@TAGNAME+ は +object.tags('TAGNAME')+ の中で変換される\n"
"* +object+ は、メソッド呼び出し用の対象として省略できる。(ほのめかす)"

# @example Check if there are any @param tags
#: ../lib/yard/verifier.rb:33
msgid ""
"Verifier.new('@@param.empty?')\n"
"# Equivalent to:\n"
"Verifier.new('object.tags(:param).empty?')"
msgstr ""
"Verifier.new('@@param.empty?')\n"
"# 下は上と同様\n"
"Verifier.new('object.tags(:param).empty?')"

# @example Specifying multiple expressions
#: ../lib/yard/verifier.rb:33
msgid ""
"Verifier.new('@return', '@param', '@yield')\n"
"# Equivalent to:\n"
"Verifier.new('@return && @param && @yield')"
msgstr ""
"Verifier.new('@return', '@param', '@yield')\n"
"# 以下は上と同様\n"
"Verifier.new('@return && @param && @yield')"

# @example Create a verifier to find any return tag with an empty description
#: ../lib/yard/verifier.rb:33
msgid ""
"Verifier.new('@return.text.empty?')\n"
"# Equivalent to:\n"
"Verifier.new('object.tag(:return).text.empty?')"
msgstr ""
"Verifier.new('@return.text.empty?')\n"
"# 下は上と同様\n"
"Verifier.new('object.tag(:return).text.empty?')"

# @example Using +object+ or +o+ to look up object attributes directly
#: ../lib/yard/verifier.rb:33
msgid ""
"Verifier.new('object.docstring == \"hello world\"')\n"
"# Equivalent to:\n"
"Verifier.new('o.docstring == \"hello world\"')"
msgstr ""
"Verifier.new('object.docstring == \"hello world\"')\n"
"# 下は上と同様\n"
"Verifier.new('o.docstring == \"hello world\"')"

# @example Without using +object+ or +o+
#: ../lib/yard/verifier.rb:33
msgid "Verifier.new('tag(:return).size == 1 || has_tag?(:author)')"
msgstr ""

# @example
#: ../lib/yard/verifier.rb:33
msgid "tag|example|Check if there are any @param tags"
msgstr "@paramタグがあるかチェックする"

# @example
#: ../lib/yard/verifier.rb:33
msgid ""
"tag|example|Create a verifier to check for objects that don't have @private "
"tags"
msgstr "@privateタグを持たないオブジェクト用にチェックする検証器を作成する。"

# @example
#: ../lib/yard/verifier.rb:33
msgid ""
"tag|example|Create a verifier to find any return tag with an empty "
"description"
msgstr "空の説明と共に、任意のreturnタグを見つける検証器を作成する。"

# @example
#: ../lib/yard/verifier.rb:33
msgid "tag|example|Specifying multiple expressions"
msgstr "複数の表現を指定する"

# @example
#: ../lib/yard/verifier.rb:33
msgid "tag|example|Using +object+ or +o+ to look up object attributes directly"
msgstr "直接オブジェクト属性を検索するには、+object+ や +o+を使う"

# @example
#: ../lib/yard/verifier.rb:33
msgid "tag|example|Without using +object+ or +o+"
msgstr "+object+ と +o+ を使わない例"

# @example Create a verifier to check for objects that don't have @private tags
#: ../lib/yard/verifier.rb:33
msgid ""
"verifier = Verifier.new('!@private')\n"
"verifier.call(object) # => true (no @private tag)"
msgstr ""

# @return [Array]
#: ../lib/yard/verifier.rb:36
msgid "a list of all expressions the verifier checks for"
msgstr "チェックする検証器用の全ての式のリスト"

# YARD::Verifier#initialize
#: ../lib/yard/verifier.rb:44
msgid "Creates a verifier from a set of expressions"
msgstr "式のグループから検証器を作成する。"

# @param [Array] expressions
#: ../lib/yard/verifier.rb:47
msgid ""
"a list of Ruby expressions to\n"
"parse."
msgstr "解析するRubyの式のリスト"

# @return [Verifier]
#: ../lib/yard/verifier.rb:47
msgid "a new instance of Verifier"
msgstr "検証器の新しいインスタンス"

# @param [Array]
#: ../lib/yard/verifier.rb:47 ../lib/yard/verifier.rb:57
msgid "tag|param|expressions"
msgstr "式"

# YARD::Verifier#add_expressions
#: ../lib/yard/verifier.rb:53
msgid "Adds a set of expressions and recompiles the verifier"
msgstr "式のグループを追加し、検証器を再編集する。"

# @param [Array] expressions
#: ../lib/yard/verifier.rb:57
msgid "a list of expressions"
msgstr "式のリスト"

# YARD::Verifier#method_missing
#: ../lib/yard/verifier.rb:62
msgid "Passes any method calls to the object from the {#call}"
msgstr "{#call}メソッドからオブジェクトに任意のメソッド呼び出しを解析する"

# YARD::Verifier#call
#: ../lib/yard/verifier.rb:71
msgid "Tests the expressions on the object."
msgstr "オブジェクト上の式をテストする"

# @note
#: ../lib/yard/verifier.rb:75
msgid "If the object is a {CodeObjects::Proxy} the result will always be true."
msgstr "オブジェクトが{CodeObjects::Proxy}なら、評価結果は,常にtrueになる。"

# @param [CodeObjects::Base] object
#: ../lib/yard/verifier.rb:75
msgid "the object to verify"
msgstr "検証するオブジェクト"

# @return [Boolean]
#: ../lib/yard/verifier.rb:75
msgid "the result of the expressions"
msgstr "式の結果"

# YARD::Verifier#run
#: ../lib/yard/verifier.rb:85
msgid ""
"Runs a list of objects against the verifier and returns the subset\n"
"of verified objects."
msgstr ""
"オブジェクトに対する検証器のリストを起動し、検証されるオブジェクトの下位集合"
"を返す"

# @return [Array]
#: ../lib/yard/verifier.rb:90
msgid ""
"a list of code objects that match\n"
"the verifier."
msgstr "検証器にマッチするコードオブジェクトのリスト"

# @return [CodeObjects::Base]
#: ../lib/yard/verifier.rb:97
msgid "the current object being tested"
msgstr "テストされる現在のオブジェクト"

# YARD::Verifier#modify_nilclass
#: ../lib/yard/verifier.rb:106
msgid ""
"Modifies nil to not throw NoMethodErrors. This allows\n"
"syntax like object.tag(:return).text to work if the #tag\n"
"call returns nil, which means users don't need to perform\n"
"stringent nil checking"
msgstr ""
"NoMethodErrorsにthrowせずnil classに変更する。\n"
"#tagメソッド呼び出しがnilを返す場合、\n"
"これはobject.tag(:return).textのような構文を受け入れる。\n"
"ユーザーが厳密なnilのチェックする為に必要としない事を意味する。"

# YARD::Verifier#unmodify_nilclass
#: ../lib/yard/verifier.rb:118
msgid "Returns the state of NilClass back to normal"
msgstr "NilClassの状態を元に戻す"

# YARD::Verifier#create_method_from_expressions
#: ../lib/yard/verifier.rb:126
msgid ""
"Creates the +__execute+ method by evaluating the expressions\n"
"as Ruby code"
msgstr ""
"Rubyのコードのような式を評価する事によって +__execute+ メソッドを作成する。"

# YARD::Verifier#parse_expression
#: ../lib/yard/verifier.rb:137
msgid "Parses a single expression, handling some of the DSL syntax."
msgstr "単独の式を解析し、いくつかのDSL構文を操作する。"

# YARD::Verifier#parse_expression
#: ../lib/yard/verifier.rb:139
msgid ""
"The syntax \"@tag\" should be turned into object.tag(:tag),\n"
"and \"@@tag\" should be turned into object.tags(:tag)"
msgstr ""
"\"@tag\"構文は、object.tag(:tag)へ渡され、\n"
"\"@tags\"構文は、object.tags(:tag)へ渡される。"

# @return [String]
#: ../lib/yard/verifier.rb:142
msgid "the parsed expression"
msgstr "解析された式"

# YARD::Tags::Library
#~ msgid ""
#~ "This will allow you to use @mytag TEXT to add meta data to classes "
#~ "through\n"
#~ "the docstring. You can use the {Library#factory} object to help parse "
#~ "standard\n"
#~ "tag syntax."
#~ msgstr ""
#~ "この例は、\n"
#~ "あなたが、docstringを通じてクラス化するメタデータを追加する為に\n"
#~ "@mytag TEXTを使う事を受け入れる。\n"
#~ "あなたは、標準のタグ構文を解析し補助する為に\n"
#~ "{Library#factory}オブジェクトを利用できる。"

# YARD::Tags::Library
#~ msgid ""
#~ "== Method #2\n"
#~ "Write your own +tagname_tag+ method that takes the raw text as a "
#~ "parameter.\n"
#~ "Example:\n"
#~ "  def mytag_tag(text)\n"
#~ "    # parse your tag contents here\n"
#~ "  end"
#~ msgstr ""
#~ "== 方法 #2\n"
#~ "自分で引数の様に生のテキストを取得し、 +tagname_tag+ メソッドを書く。\n"
#~ "\\nExample:\n"
#~ "  def mytag_tag(text)\n"
#~ "    # parse your tag contents here\n"
#~ "  end"

# YARD::Tags::Library
#~ msgid ""
#~ "Note that +tag_factory+ is the factory object used to parse tags. This "
#~ "value\n"
#~ "defaults to the {DefaultFactory} class and can be set by changing "
#~ "{Library.default_factory}."
#~ msgstr ""
#~ "次の事に留意する。\n"
#~ "+tag_factory+ は、タグを解析する為に利用されるfactoryオブジェクトとな"
#~ "る。\n"
#~ "この値は{DefaultFactory}クラスがデフォルトとなり、\n"
#~ "{Library.default_factory}を変更する事によって設定できる。"

# YARD::Tags::Library
#~ msgid ""
#~ "The second line will expand to:\n"
#~ "  def author_tag(text) tag_factory.parse_tag(text) end"
#~ msgstr ""
#~ "例の2番目の行は次の様になる:\n"
#~ "  def author_tag(text) tag_factory.parse_tag(text) end"

# YARD::Tags::Library
#~ msgid ""
#~ "The first line will expand to the code:\n"
#~ "  def param_tag(text) tag_factory.parse_tag_with_types_and_name(text) end"
#~ msgstr ""
#~ "例の最初の行は、次の様になる:\n"
#~ "  def param_tag(text) tag_factory.parse_tag_with_types_and_name(text) end"

# YARD::Tags::Library
#~ msgid ""
#~ "== Method #1\n"
#~ "Use {Library.define_tag} to define a new tag by passing the tag name\n"
#~ "and the factory method to use when creating the tag. These definitions "
#~ "will\n"
#~ "be auto expanded into ruby code similar to what is shown in method #2. If "
#~ "you\n"
#~ "do not provide a factory method to use, it will default to "
#~ "{DefaultFactory#parse_tag}\n"
#~ "Example:\n"
#~ "  define_tag \"Parameter\", :param, :with_types_and_name\n"
#~ "  define_tag \"Author\", :author"
#~ msgstr ""
#~ "== 方法 #1\n"
#~ "{Library.define_tag}を使い,タグ名を解析する事によって新しいタグを定義"
#~ "し、\n"
#~ "タグを作成する時にfactoryメソッドを使用する。\n"
#~ "これらの定義は 方法 #2の中の見られる事と同様に\n"
#~ "Rubyコードの中で自動拡張される。\n"
#~ "あなたがfactoryメソッドを利用しない場合、\n"
#~ "デフォルトは{DefaultFactory#parse_tag}になるだろう。\n"
#~ "\\nExample:\n"
#~ "  define_tag \"Parameter\", :param, :with_types_and_name\n"
#~ "  define_tag \"Author\", :author"

# YARD::Tags::Library
#~ msgid ""
#~ "Holds all the registered meta tags. If you want to extend YARD and add\n"
#~ "a new meta tag, you can do it in one of two ways."
#~ msgstr ""
#~ "全ての記録されるメタタグを把握する。あなたがYARDを拡張したい場合や\n"
#~ "新しいメタタグを追加したい場合は、2つの方法のうちどちらかを選択することが"
#~ "できる。"

# YARD::Server::WebrickServlet#adapter=
#~ msgid "Sets the attribute adapter"
#~ msgstr "アダプタの属性を設定する"

# YARD::Server::WebrickServlet#adapter
#~ msgid "Returns the value of attribute adapter"
#~ msgstr "アダプタの属性の値を返す"

# @param value
#~ msgid "the value to set the attribute adapter to."
#~ msgstr "アダプタの属性を設定する値"

# YARD::Server::Commands::SearchCommand#results=
#~ msgid "Sets the attribute results"
#~ msgstr "results属性を設定する"

# YARD::Server::Commands::SearchCommand#query=
#~ msgid "Sets the attribute query"
#~ msgstr "query属性を設定する"

# YARD::Server::Commands::SearchCommand#results
#~ msgid "Returns the value of attribute results"
#~ msgstr "results属性の値を返す"

# YARD::Server::Commands::SearchCommand#query
#~ msgid "Returns the value of attribute query"
#~ msgstr "query属性の値を返す"

# @param value
#~ msgid "the value to set the attribute results to."
#~ msgstr "results属性を設定する値"

# @param value
#~ msgid "the value to set the attribute query to."
#~ msgstr "query属性を設定する値"

# YARD::Server::Commands::ListFilesCommand
#~ msgid "Returns the list of README/extra files in a library"
#~ msgstr "ライブラリの中のREADMEと追加のファイルのリストを返す"

# YARD::Server::Commands::ListMethodsCommand
#~ msgid "Returns the list of methods in a library"
#~ msgstr "ライブラリの中のメソッドのリストを返す"

# YARD::Server::Commands::ListClassesCommand
#~ msgid "Returns the list of classes / modules in a library"
#~ msgstr "ライブラリの中のクラスとモジュールのリストを返す"

# YARD::Server::Commands::LibraryIndexCommand#options=
#~ msgid "Sets the attribute options"
#~ msgstr "options属性を設定する"

# @param value
#~ msgid "the value to set the attribute options to."
#~ msgstr "options属性を設定する為の値"

# YARD::RegistryStore#proxy_types
#~ msgid "Returns the value of attribute proxy_types"
#~ msgstr "proxy_types属性の値を返す"

# @example
#~ msgid "tag|example|Performing a Search on a Registry"
#~ msgstr "レジストリー上で検索を実行する"

# @param [Boolean] load_order_errors
#~ msgid "whether or not to raise the {LoadOrderError}"
#~ msgstr "{LoadOrderError}の例外を上げるかどうか"

# @param [Symbol] parser_type
#~ msgid "the parser type to use"
#~ msgstr "使用するパーサータイプ。"

# @param [Boolean]
#~ msgid "tag|param|load_order_errors"
#~ msgstr "load_order_errors"

# @param [OpenStruct] globals
#~ msgid "global state to be re-used across separate source files"
#~ msgstr "ソースファイルをまたいで再利用される、globals"

# YARD::Parser::SourceParser#initialize
#~ msgid ""
#~ "Creates a new parser object for code parsing with a specific parser type."
#~ msgstr ""
#~ "明確なパーサー型と共にコード解析用の\n"
#~ "新しいパーサーオブジェクトを作成する。"

# YARD::Parser::SourceParser.parse_in_order
#~ msgid ""
#~ "Parses a list of files in a queue. If a {LoadOrderError} is caught,\n"
#~ "the file is moved to the back of the queue with a Continuation object\n"
#~ "that can continue processing the file."
#~ msgstr ""
#~ "err節の説明が入ってない\n"
#~ "Errorの時は Continuation オブジェクトではなく、\n"
#~ "e.contextと共にファイルの後ろにpushされる。)\n"
#~ "\n"
#~ "キューの中のファイルのリストを解析する。\n"
#~ "{LoadOrderError}が見つかった場合、\n"
#~ "ファイルはキューの後ろに移動され、Continuationオブジェクトを用い、\n"
#~ "処理しているファイルを継続できる"

# @param [Continuation]
#~ msgid "tag|param|context"
#~ msgstr "context"

# @return [LoadOrderError]
#~ msgid "a new instance of LoadOrderError"
#~ msgstr "LoadOrderErrorの新しいインスタンス。"

# @return [Continuation]
#~ msgid ""
#~ "the context representing the\n"
#~ "point at which the load order error occurred."
#~ msgstr ""
#~ "コンテキストはload order errorが起こされる所の\n"
#~ "ポイントを指摘する。"

# YARD::Parser::LoadOrderError
#~ msgid ""
#~ "A LoadOrderError occurs when a handler needs to modify a\n"
#~ "{CodeObjects::NamespaceObject} (usually by adding a child to it)\n"
#~ "that has not yet been resolved."
#~ msgstr ""
#~ "LoadOrderErrorは、ハンドラーが解決されない{CodeObjects::NamespaceObject}"
#~ "を\n"
#~ "修正する必要がある時に起こる。(通常は、NamespaceObjectに子を追加する)"

# @return [Object]
#~ msgid "the current value of shebang_line"
#~ msgstr "shebang_lineの現在の値"

# @return [Object]
#~ msgid "the current value of enumerator"
#~ msgstr "enumeratorの現在の値"

# @return [Object]
#~ msgid "the current value of encoding_line"
#~ msgstr "encoding_lineの現在の値"

# YARD::Parser::Ruby::Legacy::Statement#group=
# YARD::Parser::Ruby::AstNode#group=
#~ msgid "Sets the attribute group"
#~ msgstr "グループ属性を設定する。"

# YARD::Parser::Ruby::Legacy::Statement#group
# YARD::Parser::Ruby::AstNode#group
#~ msgid "Returns the value of attribute group"
#~ msgstr "グループ属性の入った値を返す。"

# @param value
#~ msgid "the value to set the attribute group to."
#~ msgstr "グループ属性を設定する,値"

# @return [LocaleInfoCollector]
#~ msgid "a new instance of LocaleInfoCollector"
#~ msgstr "LocaleInfoCollectorの新しいインスタンス"

# @param [String] member
#~ msgid "the name of the struct member whose return type we need"
#~ msgstr "必要とする型を返す構造体memberの名前"

# @param [Boolean] load_order_error
#~ msgid ""
#~ "whether or not to raise {Parser::LoadOrderError}\n"
#~ "when a file has unresolved references that need to be parsed first.\n"
#~ "If these errors are raised, the processor will attempt to load all\n"
#~ "other files before continuing to parse the file."
#~ msgstr ""
#~ "ファイルが最初に解析される必要がある参照を未解決の時、\n"
#~ "{Parser::LoadOrderError}の例外を上げるかどうか\n"
#~ "もしこれらのエラーが上げられる場合、\n"
#~ "プロセッサーは、ファイルの解析を継続する前に\n"
#~ "全ての他のファイルをロードをする。"

# @param [Symbol] parser_type
#~ msgid ""
#~ "the parser type (:ruby, :ruby18, :c) from\n"
#~ "the parser. Used to select the handler (since handlers are specific\n"
#~ "to a parser type)."
#~ msgstr ""
#~ "パーサーが提供する,パーサータイプ(:ruby, :ruby18, :c)\n"
#~ "利用するハンドラーを選択するには、(ハンドラーがパーサータイプを指定す"
#~ "る。)\n"
#~ "the parser. Used to select the handler (since handlers are specific to a "
#~ "parser type)."

# @param [OpenStruct] globals
#~ msgid ""
#~ "the object holding all state during the\n"
#~ "post processing stage"
#~ msgstr "後処理段階の間に全ての状態を保持するオブジェクト"

# @param [String] file
#~ msgid ""
#~ "the name of the file that is being processed.\n"
#~ "uses '(stdin)' if file is nil."
#~ msgstr ""
#~ "処理されるファイルの名前、\n"
#~ "ファイルがnilの場合、'(stdin)'を使う。"

# @param [Symbol]
#~ msgid "tag|param|parser_type"
#~ msgstr "parser_type"

# @return [Boolean]
#~ msgid "whether or not {Parser::LoadOrderError} is raised"
#~ msgstr "{Parser::LoadOrderError}の例外を上げるかどうか"

# @param [CodeObjects::Base] object
#~ msgid "the object to expand the macro on"
#~ msgstr "拡張するオブジェクトのマクロ"

# @param [CodeObjects::MacroObject] macro
#~ msgid "the macro object to expand"
#~ msgstr "マクロによって拡張する為のオブジェクト"

# @return [CodeObjects::MacroObject]
#~ msgid "the newly created macro"
#~ msgstr "新たに作成されたマクロ"

# @param [Docstring, CodeObjects::Base] object_or_docstring
#~ msgid ""
#~ "the docstring\n"
#~ "or it's object with which to check for a macro"
#~ msgstr "マクロのチェックの為のdocstringやオブジェクト"

# @return [nil]
#~ msgid "if the docstring does not create or reference a macro"
#~ msgstr "docstringが作られていない場合やマクロの参照がない場合"

# YARD::Handlers::Base#find_or_create_macro
#~ msgid ""
#~ "Attempts to find or create a macro if a +@macro+ tag is found in the\n"
#~ "docstring (or the object's docstring)."
#~ msgstr ""
#~ "+@macro+ タグがdocstring(やオブジェクトのdocstring)の中で見つかった場"
#~ "合、\n"
#~ "マクロタグがあるか探し、マクロ作成を試みる。"

# @return [String]
#~ msgid "the localized docstring."
#~ msgstr "docstringを局所化する"

# YARD::Docstring#document
#~ msgid ""
#~ "Gets a localized docstring. Use String#to_s to get non\n"
#~ "localized docstring."
#~ msgstr ""
#~ "局所化されるdocstringを取得する。\n"
#~ "局所化されないdocstringを取得するには、\n"
#~ "String#to_sメソッドを使う。"

# @param [Array] call_params
#~ msgid ""
#~ "the method name and parameters\n"
#~ "to the method call. These arguments will fill $0-N"
#~ msgstr ""
#~ "メソッド名やメソッド呼び出しの為のパラメータ。\n"
#~ "これらの引数には、$0-Nを入れる。"

# @param [String] full_source
#~ msgid ""
#~ "the full source line (excluding block) \n"
#~ "interpolated as $*"
#~ msgstr "$*のように、補完される完全なソースの行(blockを除外する)"

# @return [String]
#~ msgid "the expanded macro data"
#~ msgstr "拡張されたマクロデータ"

# @param [String] block_source
#~ msgid ""
#~ "Currently unused. Will support \n"
#~ "interpolating the block data as a variable."
#~ msgstr ""
#~ "実際には、使われない。\n"
#~ "変数のように補完するブロックデータをサポートする。"

# @return [Boolean]
#~ msgid "whether to report missing translations."
#~ msgstr "見つからない変換をレポートするかどうか"

# @return [String]
#~ msgid "a language for output document."
#~ msgstr "ドキュメント出力用の言語"

# @return [Array]
#~ msgid "the default list of locale path."
#~ msgstr "デフォルトのロケールパスのリスト"

# @return [Array]
#~ msgid "a list of locale path."
#~ msgstr "ロケールパスのリスト"

#~ msgid ""
#~ "  3. Define custom javascript to load the search fields and the keyboard "
#~ "shortcuts."
#~ msgstr ""
#~ "  3. 検索フィールドとキーボードショートカットをロードするカスタム"
#~ "javascriptを定義する。"

#~ msgid ""
#~ "The interpolation syntax is similar to Ruby's regular expression variable "
#~ "syntax.\n"
#~ "It uses $1, $2, $3, ..., referring to the Nth argument in the method "
#~ "call. Using\n"
#~ "the above property example, $1 would be 'title', and $2 would be "
#~ "'String'.\n"
#~ "$0 is a special variable that refers to the method call itself, in this "
#~ "case\n"
#~ "'property'. Finally, there is a $& variable which refers to the full "
#~ "line,\n"
#~ "or 'property :title, String'."
#~ msgstr ""
#~ "補間の構文法は、Rubyの正規表現の変数の構文の表現に似ている。\n"
#~ "メソッドコールでのN番目の引数かを参照して、\n"
#~ "$1,$2,$3・・・を使う。\n"
#~ "上記の例で言うと、$1は'title'、$2は'String'となる。\n"
#~ "$0は、このケースのプロパティでは、\n"
#~ "メソッドコール自体を参照する特別な変数である。\n"
#~ "最後に、$&変数というのがある。\n"
#~ "これは全ての行あるいは'property :title, String'.を参照する。"

#~ msgid "### Macro Variable Interpolation Syntax"
#~ msgstr "### マクロの変数補間構文"

#~ msgid ""
#~ "If you cannot declare the macro on the actual method declaration, you "
#~ "can\n"
#~ "arbitrarily attach the macro to any method call. Suppose we only had the\n"
#~ "Post class in our codebase, we could add the macro to the first usage of\n"
#~ "the `property` call:"
#~ msgstr ""
#~ "もし、元々のクラスのメソッドでマクロを宣言してなくても、\n"
#~ "他のメソッド呼び出しでマクロを付けることができる。\n"
#~ "自身のコードベースの中でしかPostクラスを持っていないとすれば、\n"
#~ "`property`呼び出しで初めて使う時にマクロをつけることができる。"

#~ msgid ""
#~ "Macros can be created on class level methods (or class level method "
#~ "calls) in \n"
#~ "order to implicitly expand a macro whenever that method is subsequently "
#~ "called \n"
#~ "in a class, or any class that mixes in or inherits the method. These "
#~ "macros\n"
#~ "are called \"attached\" and are declared with the `[attach]` flag. For "
#~ "instance, \n"
#~ "a library that uses a class level method call `property` in its codebase "
#~ "can \n"
#~ "document these declarations in any future call like so:"
#~ msgstr ""
#~ "マクロはメソッドがクラスの中で呼び出された後で、\n"
#~ "何らかのマクロの拡張を実装する時にコードの中の\n"
#~ "クラスレベルメソッド上に作成される。(または、クラスレベルメソッド呼び出"
#~ "し)\n"
#~ "これらのマクロは`[attach]`フラグを用いる。\n"
#~ "これが宣言される事によってマクロが追加される。\n"
#~ "例えば、ライブラリーが`property`クラスレベルメソッド呼び出しを利用するに"
#~ "は、\n"
#~ "以下の様に、将来呼び出せるように宣言を記述できる。"

#~ msgid ""
#~ "In the above case, the macro 'macro_name' will always show both lines of "
#~ "text\n"
#~ "when expanded on other objects."
#~ msgstr ""
#~ "上記のケースだと、 'macro_name' というマクロは他のオブジェクトで\n"
#~ "展開すると、テキストの両方の行を表示する。"

#~ msgid ""
#~ "If there is no indented macro data, the entire docstring is saved as the\n"
#~ "macro data. For instance,"
#~ msgstr ""
#~ "インデントされたマクロのデータがないならば、\n"
#~ "docstring全体はマクロのデータとして保存される。\n"
#~ "例えば、"

#~ msgid ""
#~ "You can therefore keep portions of docstrings local to objects even when\n"
#~ "creating a macro, by indenting the portion of the data that should be "
#~ "re-\n"
#~ "expanded, and listing the local docstring data above or below."
#~ msgstr ""
#~ "マクロを作った時でも、docstringの一部をマクロとは別にしておくことができ"
#~ "る。\n"
#~ "それには、再度展開されるべきマクロデータの一部をインデントして、なおか"
#~ "つ、\n"
#~ "上か下にローカルのdocstringのデータを列挙する。"

#~ msgid ""
#~ "In the above case, \"The macro data is here.\" is the only portion that "
#~ "will be\n"
#~ "re-used if the macro is called again on another object. However, for the "
#~ "case\n"
#~ "of the above method, both the macro data and the local docstring will be\n"
#~ "applied to the method, creating the docstring:"
#~ msgstr ""
#~ "上記のケースで、\"The macro data is here.\"はマクロが、\n"
#~ "別のオブジェクトで呼ばれたら再利用されるものの一部である。\n"
#~ "だが、ここで使われないというわけではなく、\n"
#~ "上記のケースでは、マクロデータと他のdocstring(This data is~)はメソッドに適"
#~ "用され\n"
#~ "docstringを生成する。"

#~ msgid ""
#~ "If a macro tag has an indented body of macro data (shown below), it will "
#~ "be\n"
#~ "the only portion of the docstring saved for re-use."
#~ msgstr ""
#~ "マクロのタグが以下のようなインデントされたマクロデータの構造を有しているな"
#~ "らば、\n"
#~ "それは再利用のために保存されたdocstringの一部分にすぎない。\n"

#~ msgid "### Indenting the Macro Data"
#~ msgstr "### マクロのデータをインデントする。"

#~ msgid ""
#~ "Note that the name is never optional. Even if the macro is never re-"
#~ "used,\n"
#~ "it must be named."
#~ msgstr ""
#~ "次の事に留意する。\n"
#~ "名前は必ずつける。\n"
#~ "(マクロが再利用されていない時でも、必ず命名されなければならない。)"

#~ msgid ""
#~ "Any time 'foo' is called in the class scope of an inheriting class, the "
#~ "macro\n"
#~ "will automatically expand on that method call (potentially creating a "
#~ "new\n"
#~ "method object). Attaching macros is discussed below."
#~ msgstr ""
#~ "上のfooは常時、継承クラスのクラススコープの中に呼び出される。\n"
#~ "そしてマクロはメソッド呼び出しで自動的に展開する。\n"
#~ "(暗黙の内に新しいメソッドオブジェクトを生成する。)\n"
#~ "マクロを追加する方法は、以降で説明される。"

#~ msgid ""
#~ "You can also \"attach\" a macro to a method if it is in the class scope. "
#~ "In\n"
#~ "this case, you do not need to also provide the 'new' flag, using "
#~ "'attach'\n"
#~ "is sufficient:"
#~ msgstr ""
#~ "クラスのスコープの中にあれば、\n"
#~ "メソッドにマクロを\"attach\"できる。\n"
#~ "この場合、\"new\"フラグを提供する必要はなく、\n"
#~ "以下の様に\"attach\"で十分である。\n"

#~ msgid "Or:"
#~ msgstr "または:"

#~ msgid ""
#~ "For instance, creating a new macro might look like (see the section on\n"
#~ "interpolation below for a description of the `$2` syntax):"
#~ msgstr ""
#~ "例えば、新しいマクロを作ることは以下のようになる。\n"
#~ "(`$2`構文の説明は補間のセクション参照)"

#~ msgid ""
#~ "  1. there are interpolation variables (`$1`, `$2`, `${3-5}`, etc.) in "
#~ "the\n"
#~ "     docstring, or,\n"
#~ "  2. the macro is specified with the `[new]` or `[attached]` flag."
#~ msgstr ""
#~ "  1. docstringには補間変数(`$1`,`$2`,`$3-5`,etc.)がある。\n"
#~ "     （ここでいう補間変数とは、それを使用した場所と補間元とを置換するとい"
#~ "う意味）\n"
#~ "  2. あるいは、マクロは[new]か[attached]のフラグで指定されている。\n"

#~ msgid "If the macro does not already exist, it will be created if:"
#~ msgstr "マクロがまだ存在しない場合で、次の条件の時はマクロが生成される。"

#~ msgid ""
#~ "In the above example, both attributes `foo` and `bar` will get the "
#~ "docstring\n"
#~ "that includes a return tag \"the attribute as a String\". It would be "
#~ "equivalent\n"
#~ "to writing the following:"
#~ msgstr ""
#~ "上記の例では、fooとbarの２つの属性ともリターンタグの\n"
#~ "\"the attribute as a String\"を含んだdocstringを取得している。\n"
#~ "次のように書いた場合と同じである。"

#~ msgid ""
#~ "Macros enable the documenter to write repetitive documentation once and "
#~ "then\n"
#~ "re-apply it to other objects. Macros are defined on docstrings using the\n"
#~ "`@macro` tag. The same `@macro` tag is used to expand them. The "
#~ "following\n"
#~ "is an example of a simple macro declaration and expansion:"
#~ msgstr ""
#~ "マクロを使うと一度書いたドキュメントを、\n"
#~ "他のオブジェクトで再利用できる。\n"
#~ "マクロはdocstringsで@macroタグを使って定義される。\n"
#~ "同じ名前の@macroタグは展開するために使われる。\n"
#~ "以下は、単純なマクロの宣言と展開の例である。"

#~ msgid "## Macros"
#~ msgstr "## マクロ"

#~ msgid ""
#~ "Reference tags are represented by the {YARD::Tags::RefTag} class and are "
#~ "created\n"
#~ "directly during parsing by {YARD::Docstring}."
#~ msgstr ""
#~ "リファレンスタグは、{YARD::Tags::RefTag}クラスによって表わされ、\n"
#~ "{YARD::Docstring}を解析する間に作られる。\n"

#~ msgid ""
#~ "Because the UserHelper module methods delegate directly to `User.new`, "
#~ "copying\n"
#~ "the documentation details would be unmaintainable. In this case, the (see "
#~ "METHODNAME)\n"
#~ "syntax is used to reference the tags from the User constructor to the "
#~ "helper methods.\n"
#~ "For the first method, all `@param` tags are referenced in one shot, but "
#~ "the second\n"
#~ "method only references one of the tags by adding `username` before the "
#~ "reference."
#~ msgstr ""
#~ "何故なら、上のUserHelperモジュールのメソッドは直接`User.new`へ委譲するの"
#~ "で、\n"
#~ "ドキュメントの詳細をコピーすることはできない。\n"
#~ "このような場合、 (see METHODNAME) 構文はユーザーコンストラクターから\n"
#~ "ヘルパーメソッドまでのタグを参照するために利用される。\n"
#~ "最初のメソッドは、すべての@paramタグを一発で参照する。\n"
#~ "しかし、次のメソッドはリファレンスの前にユーザーネームが\n"
#~ "加えられたタグのみを参照する。"

#~ msgid ""
#~ "Although attempt is made in YARD to leave as many of the syntax details "
#~ "as\n"
#~ "possible to the factory provider, there is a special tag syntax for "
#~ "referencing\n"
#~ "tags created in other objects so that they can be reused again. This is "
#~ "common\n"
#~ "when an object describes a return type or parameters that are passed "
#~ "through to\n"
#~ "other methods. In such a case, it is more manageable to use the reference "
#~ "tag\n"
#~ "syntax. Consider the following example:"
#~ msgstr ""
#~ "ファクトリーの提供者によってYARDの中では沢山の構文の詳細を残すように試みら"
#~ "れたけれども、\n"
#~ "再利用できるように、他のオブジェクトの中に作成されたタグを参照する特別なタ"
#~ "グ構文がある。\n"
#~ "これは、オブジェクトが返す型や他のオブジェクトの為に解析されるパラメータ"
#~ "を\n"
#~ "説明する時に一般的に用いられる。\n"
#~ "このような場合には参照タグ構文を使うとより扱いやすい、\n"
#~ "以下の例を考えてみる。\n"

#~ msgid "## Reference Tags"
#~ msgstr "## 参照タグ"

#~ msgid "        @yieldreturn [optional, types, ...] description"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @yieldreturn [型(省略可能)...] 説明"

#~ msgid "  * `@yieldreturn`: Defines return type of a block"
#~ msgstr "  * `@yieldreturn`: ブロックのリターンタイプを定義する。"

#~ msgid "        @yieldparam [optional, types, ...] argname description"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @yieldparam [型(省略可能)...] 引数名 説明"

#~ msgid "  * `@yieldparam`: Defines parameters yielded by a block"
#~ msgstr "  * `@yieldparam`: ブロックでyieldされたパラメータを定義する。"

#~ msgid ""
#~ "        # for block {|a, b, c| ... }\n"
#~ "        @yield [a, b, c] Description of block"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        # for block {|a, b, c| ... }\n"
#~ "        @yield [a, b, c] ブロックの説明"

#~ msgid ""
#~ "  * `@yield`: Describes the block. Use types to list the parameter\n"
#~ "    names the block yields."
#~ msgstr "  * `@yield`: パラメータを列挙してブロックを説明する。"

#~ msgid "  * `@todo`: Marks a TODO note in the object being documented"
#~ msgstr ""
#~ "  * `@todo`: ドキュメントを作成しているオブジェクトの中に、\n"
#~ "    TODOをマークする。"

#~ msgid "        @return [optional, types, ...] description"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @return [型(省略可能)...] 説明"

#~ msgid "  * `@return`: Describes return value of method"
#~ msgstr "  * `@return`: メソッドの戻り値を説明する。"

#~ msgid "        @raise [ExceptionClass] description"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @raise [ExceptionClass] 説明"

#~ msgid "  * `@raise`: Describes an Exception that a method may throw"
#~ msgstr "  * `@raise`: メソッドが投げる例外を記述する。"

#~ msgid ""
#~ "  * `@private`: Defines an object as private. This exists for classes,\n"
#~ "    modules and constants that do not obey Ruby's visibility rules. For\n"
#~ "    instance, an inner class might be considered \"private\", though "
#~ "Ruby\n"
#~ "    would make no such distinction. By declaring the @private tag, the\n"
#~ "    class can be hidden from documentation by using the `--no-private`\n"
#~ "    command-line switch to yardoc (see {file:README.md})."
#~ msgstr ""
#~ "  * `@private`: privateとしてオブジェクトを定義する。\n"
#~ "これはRubyの可視性に従わないクラス、モジュール、定数のために存在する。\n"
#~ "たとえば、Rubyはそのような区分はしないだろうが,内部クラスは\"private\"だと"
#~ "考える場合、\n"
#~ "yardoc用のコマンド`--no-private`({file:README.md} 参照)を使うことによっ"
#~ "て\n"
#~ "@privateタグを宣言すると、クラスをドキュメンテーションから隠すことができ"
#~ "る。"

#~ msgid "        @param [optional, types, ...] argname description"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @param [型(省略可能)...] 引数名 説明"

#~ msgid "  * `@param`: Defines method parameters"
#~ msgstr "  * `@param`: メソッドのパラメータを定義する。"

#~ msgid ""
#~ "  * `@note`: Creates an emphasized note for the users to read about the\n"
#~ "    object."
#~ msgstr ""
#~ "  * `@note`: ユーザがオブジェクトのことを読んで知るために、\n"
#~ "     強調された注意書きを作る。\n"

#~ msgid ""
#~ "  * `@method`: Recognizes a DSL class method as a method with the given "
#~ "name\n"
#~ "    and optional signature. Only used with DSL methods."
#~ msgstr ""
#~ "  * `@method`: DSLクラスメソッドを名前と省略可能な用法がついたメソッドとし"
#~ "て認識する。DSLメソッドと一緒の時だけ使われる。"

#~ msgid ""
#~ "        @macro [new|attached] macro_name\n"
#~ "          The macro contents to expand"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @macro [new,又は,attached] マクロ名\n"
#~ "          展開する内容をここ以降に書く"

#~ msgid ""
#~ "  * `@macro`: Registers or expands a new macro. See the [Macros]"
#~ "(#macros)\n"
#~ "    section for more details. Note that the name parameter is never "
#~ "optional."
#~ msgstr ""
#~ "  * `@macro`: 新しいマクロを登録または拡張する。\n"
#~ "     詳細は [Macros](#macros) 参照。\n"
#~ "     NAMEというパラメータは省略できないことに注意する。"

#~ msgid ""
#~ "        @deprecated Describe the reason or provide alt. references here"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @deprecated 廃止される理由や代替の提供についての参照をここに書く。"

#~ msgid ""
#~ "  * `@deprecated`: Marks a method/class as deprecated with an optional\n"
#~ "    reason."
#~ msgstr ""
#~ "  * `@deprecated`: 廃止予定のメソッド,クラスをマークする。任意で理由を書く"

#~ msgid "        @author Full Name"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @author フルネーム"

#~ msgid "  * `@author`: List the author(s) of a class/method"
#~ msgstr "  * `@author`: クラス,メソッドの作者リスト"

#~ msgid "        @attribute [rw|r|w] NAME"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @attribute [rw|r|w] 名前"

#~ msgid ""
#~ "  * `@attribute`: Recognizes a DSL class method as an attribute with the "
#~ "given\n"
#~ "    name. Also accepts the r, w, or rw flag to signify that the attribute "
#~ "is \n"
#~ "    readonly, writeonly, or readwrite (default). Only used with DSL "
#~ "methods."
#~ msgstr ""
#~ "  * `@attribute`: DSLクラスメソッドを指定された名前を持つ属性として認識す"
#~ "る。\n"
#~ "     又,r,w,rwフラグは読み込み専用,書込み専用,読書き両用(デフォルト)とな"
#~ "る。\n"
#~ "     DSLのメソッドだけで使用される。\n"

#~ msgid "        @attr_writer [Types] name description of writeonly attribute"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @attr_writer [型...] 名前 書込み専用属性の説明"

#~ msgid ""
#~ "  * `@attr_writer`: Declares a writeonly attribute from the docstring of "
#~ "class.\n"
#~ "    Meant to be used on Struct classes only (classes that inherit "
#~ "Struct). See `@attr`."
#~ msgstr ""
#~ "  * `@attr_writer`: クラスのdocstringから書き込み専用属性と宣言する\n"
#~ "     Structクラスだけで使用できる。(Structクラスを継承するクラス)`@attr`参"
#~ "照。"

#~ msgid ""
#~ "        @attr_reader [Types] name description of a readonly attribute"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @attr_reader [型...] 名前 読取り専用属性の説明"

#~ msgid ""
#~ "  * `@attr_reader`: Declares a readonly attribute from the docstring of a "
#~ "class.\n"
#~ "    Meant to be used on Struct classes only (classes that inherit "
#~ "Struct). See `@attr`."
#~ msgstr ""
#~ "  * `@attr_reader`: クラスのdocstringから読み込み専用属性と宣言する。\n"
#~ "     Structクラスだけで使用できる。(Structクラスを継承するクラス)`@attr`参"
#~ "照。"

#~ msgid ""
#~ "        @attr [Types] attribute_name a full description of the attribute"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @attr [型...] 属性名 属性の全ての説明"

#~ msgid ""
#~ "  * `@attr`: Declares an attribute from the docstring of a class. Meant "
#~ "to be\n"
#~ "    used on Struct classes only (classes that inherit Struct)."
#~ msgstr ""
#~ "  * `@attr`: クラスのdocstringから属性を宣言する。\n"
#~ "     Structクラスだけで使用できる。(Structクラスを継承するクラス)"

#~ msgid "        @api freeform text"
#~ msgstr ""
#~ "        !!!plain\n"
#~ "        @api フリーフォームテキスト"

#~ msgid "YARD supplies the following built-in tags:"
#~ msgstr "YARDは、以下のビルトインタグを用意している。"

#~ msgid "## List of Available Tags"
#~ msgstr "## 利用可能なタグのリスト"

#~ msgid "As mentioned, types are optional, so the following is also valid:"
#~ msgstr "型は省略可能で, 以下は同様に有効である"

#~ msgid ""
#~ "Note that \"url\" in the above example is the key name. The syntax is of "
#~ "the form:"
#~ msgstr ""
#~ "次の事に留意する。\n"
#~ "上の例の中の\"url\"は、キー名である。\n"
#~ "この構文は次の形式になる。"

#~ msgid ""
#~ "A special case of the above data with optional type information is the "
#~ "case\n"
#~ "of tags like `@param`, where the data is further associated with a key. "
#~ "In\n"
#~ "the case of `@param` the key is an argument name in the method. The "
#~ "following\n"
#~ "shows how this can be used:"
#~ msgstr ""
#~ "省略可能な型情報を用いた上のデータの様な特殊なケースは、\n"
#~ "データがキーを用い更に関連付けられる場合、\n"
#~ "@paramのようなタグのケースとなる。\n"
#~ "`@param`キーのケースの場合は、メソッドの中の名前は引数となる。\n"
#~ "次のような用法で使われる。"

#~ msgid "### Data With Name and Optional Type Information"
#~ msgstr "### 名前と任意の型情報のついたデータ"

#~ msgid ""
#~ "This syntax optionally contains type information to be associated with "
#~ "the\n"
#~ "tag. Type information is specified as a freeform list of Ruby types, "
#~ "duck\n"
#~ "types or literal values. The following is a valid tag with type "
#~ "information:"
#~ msgstr ""
#~ "この構文は、省略できるタグに関連付けられる型情報が含まれる。\n"
#~ "型情報は、Rubyの型かダックタイプやリテラル値の\n"
#~ "フリーフォームのリストとして指定される。\n"
#~ "以下は、型情報を持つ有効なタグとなる。"

#~ msgid "### Data With Optional Type Information"
#~ msgstr "### 任意の型情報がついたデータ"

#~ msgid ""
#~ "Occasionally a freeform tag may reserve the first line for a title (or "
#~ "some\n"
#~ "other associative identifier) and treat only the subsequent indented "
#~ "lines as\n"
#~ "the tag data. Two examples are the `@example` and `@overload` tags. In "
#~ "the case\n"
#~ "of `@example` the first line is a title, and in the case of `@overload` "
#~ "the\n"
#~ "first line is the method signature for the overload. Here is an example "
#~ "of both:"
#~ msgstr ""
#~ "いくつかのフリーフォームタグは最初の行をタイトル(又は,他の関連する識別子)"
#~ "にする。\n"
#~ "そして、それに続くインデントされた行をタグデータとして処理する。\n"
#~ "２つの例は@exampleと@overloadタグのケースで、\n"
#~ "@exampleの場合は最初の行はタイトルとなる。\n"
#~ "@overloadの場合は最初の行はメソッドの用法となる。\n"
#~ "ここで両方の例を次に示す。"

#~ msgid "### Freeform Data With Title"
#~ msgstr "### タイトルを用いたフリーフォームデータ"

#~ msgid ""
#~ "This syntax has no special syntax, it is simply a tagname followed by "
#~ "any\n"
#~ "data."
#~ msgstr ""
#~ "この構文は特別な構文ではなく,\n"
#~ "何らかのデータに続いたタグ名があるだけとなる。"

#~ msgid "### Freeform Data"
#~ msgstr "### フリーフォームデータ"

#~ msgid ""
#~ "If a tag's data begins with `(see NAME)` it is considered a \"reference "
#~ "tag\".\n"
#~ "The syntax and semantics of a reference tag are discussed in the section "
#~ "below\n"
#~ "titled \"[Reference Tags](#reftags)\""
#~ msgstr ""
#~ "タグのデータが、`（see NAME）`で始まる場合、`それは、`参照タグ`とみなされ"
#~ "る。\n"
#~ "`参照タグ`の構文と文法は、\"[Reference Tags](#reftags)\"以下のセクションで"
#~ "説明されている。"

#~ msgid ""
#~ "In the above example, \"@tagname\" will have the text *\"This is tag data"
#~ "\"*."
#~ msgstr ""
#~ "上記の例で、\"@tagname\"内の情報は\"this is tag data\"となる。\n"
#~ "(but this is not は含まない)"

#~ msgid ""
#~ "Tags begin with \"@tagname\" at the start of a comment line. Tags can "
#~ "span multiple\n"
#~ "lines if the subsequent lines are indented by more than one space. The "
#~ "following\n"
#~ "syntax is valid:"
#~ msgstr ""
#~ "タグは、コメント行の冒頭にある\"@tagname\"から始まる。\n"
#~ "後続の行がスペースでインデントされている場合は、\n"
#~ "複数行にまたがることができる。\n"
#~ "次の構文は有効となる。"

#~ msgid ""
#~ "Tags are the best way to add arbitrary metadata when documenting an "
#~ "object in a\n"
#~ "way to access it later without having to parse the entire comment string. "
#~ "The\n"
#~ "rest of the document will describe the tag syntax, how to access the "
#~ "tag \n"
#~ "metadata and how to extend YARD to support custom tags or override "
#~ "existing tags."
#~ msgstr ""
#~ "タグはオブジェクトをドキュメント化する際、\n"
#~ "コメント文字列全てを解析せずにアクセスできるように、\n"
#~ "メタデータを追加する最善の方法となる。\n"
#~ "このドキュメントの残りの部分は、\n"
#~ "タグのメタデータにアクセスする方法\n"
#~ "カスタムタグをサポートしたり、既存のタグを上書きしたりするために\n"
#~ "YARDを拡張する方法といった、タグの構文の説明になる。"

#~ msgid ""
#~ "The above example adds metadata under the name `tagname` to the Foo class "
#~ "object."
#~ msgstr ""
#~ "上記の例では、\n"
#~ "Fooクラスオブジェクトの為に`@tagname`以降にメタデータを追加する。"

#~ msgid ""
#~ "Tags represent the metadata that can be added to documentation through "
#~ "the `@tag`\n"
#~ "style syntax:"
#~ msgstr ""
#~ "タグとは以下の様に@tag形式の構文を介して、\n"
#~ "ドキュメントに追加できるメタデータを表す。"

#~ msgid ""
#~ "* **Docstring (Documentation String)**: Comments associated with a code "
#~ "object\n"
#~ "  used for documentation purposes."
#~ msgstr ""
#~ "* **Docstring (Documentation String)**: コードオブジェクトに関連するコメン"
#~ "ト,\n"
#~ "用途を記述する為に利用される。"

#~ msgid ""
#~ "* **Domain Specific Language (DSL)**: In the context of Ruby, a DSL is a "
#~ "language\n"
#~ "  optimized for a specific domain (problem) but represented using Ruby "
#~ "syntax."
#~ msgstr ""
#~ "* **Domain Specific Language (DSL)**: Ruby関連の用語で、\n"
#~ "DSLとは、特定のドメイン(問題)用に最適化された言語である。\n"
#~ "しかし、内容自体はRuby構文によって表される。"

#~ msgid ""
#~ "* **Code Object**: Any explicitly defined Ruby source that describes a "
#~ "feature\n"
#~ "  of the code. By default, this refers to classes, modules, methods, "
#~ "constants\n"
#~ "  and class variables, though it can be extended to refer to custom "
#~ "functionality\n"
#~ "  defined by a DSL (like a spec, for instance)."
#~ msgstr ""
#~ "* **Code Object**: コードの機能を説明するRubyソースを明確に定義される。\n"
#~ "デフォルトでこれはクラス,モジュール,メソッド,定数,クラス変数を参照する。\n"
#~ "それは、DSLによって定義されるカスタム機能を参照する為に拡張できると考え"
#~ "る。\n"
#~ "(例えば、rspecのように)"

#~ msgid "# Glossary"
#~ msgstr "# 用語集"

#~ msgid ""
#~ "Usage\n"
#~ "-----"
#~ msgstr ""
#~ "使用法\n"
#~ "-----"

#~ msgid ""
#~ "Installing\n"
#~ "----------"
#~ msgstr ""
#~ "インストール\n"
#~ "----------"
yard-0.9.37/samus.json000066400000000000000000000014761466601756300146220ustar00rootroot00000000000000{
  "actions": [
    {
      "action": "fs-sedfiles",
      "files": [
        "lib/*/version.rb"
      ],
      "arguments": {
        "search": "VERSION = ['\"](.+?)['\"]",
        "replace": "VERSION = '$version'"
      }
    },
    {
      "action": "chmod-files",
      "files": [
        "**/*,644",
        "bin/*,755"
      ]
    },
    {
      "action": "changelog-rotate",
      "files": [
        "CHANGELOG.md"
      ],
      "arguments": {
        "title_format": "[$version] - %B %-d$day_nth, %Y"
      }
    },
    {
      "action": "git-commit",
      "files": [
        "CHANGELOG.md",
        "lib/*/version.rb"
      ]
    },
    {
      "action": "git-merge",
      "arguments": {
        "branch": "main"
      }
    },
    {
      "action": "ruby-bundle"
    },
    {
      "action": "rake-task"
    }
  ]
}
yard-0.9.37/spec/000077500000000000000000000000001466601756300135215ustar00rootroot00000000000000yard-0.9.37/spec/cli/000077500000000000000000000000001466601756300142705ustar00rootroot00000000000000yard-0.9.37/spec/cli/command_parser_spec.rb000066400000000000000000000023521466601756300206230ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::CommandParser do
  describe "#run" do
    before do
      @cmd = CLI::CommandParser.new
    end

    it "shows help if --help is provided" do
      command = double(:command)
      expect(command).to receive(:run).with('--help')
      CLI::CommandParser.commands[:foo] = command
      @cmd.class.default_command = :foo
      @cmd.run(*%w(foo --help))
    end

    it "uses default command if first argument is a switch" do
      command = double(:command)
      expect(command).to receive(:run).with('--a', 'b', 'c')
      CLI::CommandParser.commands[:foo] = command
      @cmd.class.default_command = :foo
      @cmd.run(*%w(--a b c))
    end

    it "uses default command if no arguments are provided" do
      command = double(:command)
      expect(command).to receive(:run)
      CLI::CommandParser.commands[:foo] = command
      @cmd.class.default_command = :foo
      @cmd.run
    end

    it "lists commands if command is not found" do
      expect(@cmd).to receive(:list_commands)
      @cmd.run(*%w(unknown_command --args))
    end

    it "lists commands if --help is provided as sole argument" do
      expect(@cmd).to receive(:list_commands)
      @cmd.run(*%w(--help))
    end
  end
end
yard-0.9.37/spec/cli/command_spec.rb000066400000000000000000000020751466601756300172510ustar00rootroot00000000000000# frozen_string_literal: true
require 'optparse'

RSpec.describe YARD::CLI::Command do
  describe "#parse_options" do
    before do
      @options = OptionParser.new
      @saw_foo = false
      @options.on('--foo') { @saw_foo = true }
    end

    def parse(*args)
      CLI::Command.new.send(:parse_options, @options, args)
      args
    end

    it "skips unrecognized options but continue to next option" do
      expect(log).to receive(:warn).with(/Unrecognized.*--list/)
      expect(log).to receive(:warn).with(/Unrecognized.*--list2/)
      parse('--list', '--list2', '--foo')
      expect(@saw_foo).to be true
    end

    it "skips unrecognized options and any extra non-option arg that follows" do
      expect(log).to receive(:warn).with(/Unrecognized.*--list/)
      parse('--list', 'foo', '--foo')
      expect(@saw_foo).to be true
    end

    it "stops retrying to parse at non-switch argument" do
      expect(log).to receive(:warn).with(/Unrecognized.*--list/)
      args = parse('--list', 'foo', 'foo', 'foo')
      expect(args).to eq %w(foo foo)
    end
  end
end
yard-0.9.37/spec/cli/config_spec.rb000066400000000000000000000106061466601756300170770ustar00rootroot00000000000000# frozen_string_literal: true
require 'yaml'

RSpec.describe YARD::CLI::Config do
  before do
    @config = YARD::CLI::Config.new
    YARD::Config.options = YARD::Config::DEFAULT_CONFIG_OPTIONS.dup
    allow(YARD::Config).to receive(:save)
  end

  def run(*args)
    @config.run(*args)
  end

  describe "Listing configuration" do
    it "accepts --list" do
      opts = YARD::Config.options
      expect(YAML).to receive(:dump).twice.and_return("--- foo\nbar\nbaz")
      expect(log).to receive(:puts).twice.with("bar\nbaz")
      run
      run('--list')
      expect(YARD::Config.options).to eq opts
    end
  end

  describe "Viewing an item" do
    it "views item if no value is given" do
      YARD::Config.options[:foo] = 'bar'
      expect(log).to receive(:puts).with('"bar"')
      run 'foo'
      expect(YARD::Config.options[:foo]).to eq 'bar'
    end
  end

  describe "Modifying an item" do
    it "accepts --reset to set value" do
      YARD::Config.options[:load_plugins] = 'foo'
      run('--reset', 'load_plugins')
      expect(YARD::Config.options[:load_plugins]).to be false
    end

    it "accepts --as-list to force single item as list" do
      run('--as-list', 'foo', 'bar')
      expect(YARD::Config.options[:foo]).to eq ['bar']
    end

    it "accepts --append to append values to existing key" do
      YARD::Config.options[:foo] = ['bar']
      run('--append', 'foo', 'baz', 'quux')
      expect(YARD::Config.options[:foo]).to eq ['bar', 'baz', 'quux']
      run('-a', 'foo', 'last')
      expect(YARD::Config.options[:foo]).to eq ['bar', 'baz', 'quux', 'last']
    end

    it "turns key into list if --append is used on single item" do
      YARD::Config.options[:foo] = 'bar'
      run('-a', 'foo', 'baz')
      expect(YARD::Config.options[:foo]).to eq ['bar', 'baz']
    end

    it "modifies item if value is given" do
      run('foo', 'xxx')
      expect(YARD::Config.options[:foo]).to eq 'xxx'
    end

    it "turns list of values into array of values" do
      run('foo', 'a', 'b', '1', 'true', 'false')
      expect(YARD::Config.options[:foo]).to eq ['a', 'b', 1, true, false]
    end

    it "turns number into numeric Ruby type" do
      run('foo', '1')
      expect(YARD::Config.options[:foo]).to eq 1
    end

    it "turns true into TrueClass" do
      run('foo', 'true')
      expect(YARD::Config.options[:foo]).to be true
    end

    it "turns false into FalseClass" do
      run('foo', 'false')
      expect(YARD::Config.options[:foo]).to be false
    end

    it "saves on modification" do
      expect(YARD::Config).to receive(:save)
      run('foo', 'true')
    end
  end

  describe "RubyGems hooks" do
    require 'rubygems'

    class FakeGemConfig < Hash
      attr_accessor :written
      def write; @written = true end
      def path; nil end
    end

    before do
      allow(Gem).to receive(:configuration).and_return(FakeGemConfig.new)
    end

    it "accepts --gem-install-yri" do
      @config.send(:optparse, '--gem-install-yri')
      expect(@config.gem_install_cmd).to eq 'yri'
    end

    it "accepts --gem-install-yard" do
      @config.send(:optparse, '--gem-install-yard')
      expect(@config.gem_install_cmd).to eq 'yard'
    end

    it "does not change back to yri if yard was specified" do
      @config.send(:optparse, '--gem-install-yard', '--gem-install-yri')
      expect(@config.gem_install_cmd).to eq 'yard'
    end

    it "ignores actual config options" do
      run('--gem-install-yri', 'foo', 'true')
      expect(YARD::Config).not_to receive(:save)
    end

    it "updates configuration as :gem if no configuration exists" do
      run('--gem-install-yri')
      expect(Gem.configuration[:gem]).to eq "--document=yri"
      expect(Gem.configuration.written).to eq true
    end

    [:install, "install", :gem, "gem"].each do |type|
      it "finds existing config in #{type.inspect} and updates that line without changing anything else" do
        Gem.configuration[type] = "--opts x"
        run('--gem-install-yri')
        expect(Gem.configuration[type]).to eq "--opts x --document=yri"
        ([:install, "install", :gem, "gem"] - [type]).each do |other|
          expect(Gem.configuration[other]).to eq nil
        end
      end
    end

    it "scrubs --document values from existing config" do
      Gem.configuration["gem"] = "--document=yri,ri --no-document --opts x"
      run('--gem-install-yri')
      expect(Gem.configuration["gem"]).to eq "--opts x --document=yri"
    end
  end
end
yard-0.9.37/spec/cli/diff_spec.rb000066400000000000000000000172341466601756300165460ustar00rootroot00000000000000# frozen_string_literal: true
require 'stringio'
require 'open-uri'

RSpec.describe YARD::CLI::Diff do
  before do
    allow(CLI::Yardoc).to receive(:run)
    allow(CLI::Gems).to receive(:run)
    @diff = CLI::Diff.new
  end

  describe "Argument handling" do
    it "exits if there is only one gem name" do
      expect(@diff).to receive(:exit)
      expect(log).to receive(:puts).with(/Usage/)
      @diff.run
    end
  end

  describe "Diffing" do
    before do
      @objects1 = nil
      @objects2 = nil
    end

    def run(*args)
      @all_call = -1
      @data = StringIO.new
      @objects1 ||= %w(C#fooey C#baz D.bar)
      @objects2 ||= %w(A A::B A::B::C A.foo A#foo B C.foo C.bar C#baz)
      @objects = [@objects1, @objects2]
      expect(@diff).to receive(:load_gem_data).ordered.with('gem1') do
        Registry.clear
        YARD.parse_string <<-eof
          class C
            def fooey; end
            def baz; FOO end
          end
          class D
            def self.bar; end
          end
        eof
      end
      expect(@diff).to receive(:load_gem_data).ordered.with('gem2') do
        Registry.clear
        YARD.parse_string <<-eof
          module A
            module B
              class C; end
            end
            def self.foo; end
            def foo; end
          end
          class C
            def self.foo; end
            def self.bar; end
            def baz; BAR end
          end
        eof
      end
      allow(log).to receive(:print) {|data| @data << data }
      allow(log).to receive(:puts) {|*pargs| @data << pargs.join("\n"); @data << "\n" }
      @diff.run(*(args + ['gem1', 'gem2']))
    end

    it "shows differences between objects" do
      run
      expect(@data.string).to eq <<-eof
Added objects:

  A ((stdin):1) (...)
  A::B::C ((stdin):3)
  C.bar ((stdin):10)
  C.foo ((stdin):9)

Modified objects:

  C#baz ((stdin):3)

Removed objects:

  C#fooey ((stdin):2)
  D ((stdin):5) (...)

eof
    end

    it "accepts --compact" do
      run('--compact')
      expect(@data.string).to eq <<-eof
A A ((stdin):1) (...)
A A::B::C ((stdin):3)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
M C#baz ((stdin):3)
D C#fooey ((stdin):2)
D D ((stdin):5) (...)
eof
    end

    it "accepts -a/--all" do
      ['-a', '--all'].each do |opt|
        run(opt)
        expect(@data.string).to eq <<-eof
Added objects:

  A ((stdin):1)
  A#foo ((stdin):6)
  A.foo ((stdin):5)
  A::B ((stdin):2)
  A::B::C ((stdin):3)
  C.bar ((stdin):10)
  C.foo ((stdin):9)

Modified objects:

  C#baz ((stdin):3)

Removed objects:

  C#fooey ((stdin):2)
  D ((stdin):5)
  D.bar ((stdin):6)

eof
      end
    end

    it "accepts --compact and --all" do
      run('--compact', '--all')
      expect(@data.string).to eq <<-eof
A A ((stdin):1)
A A#foo ((stdin):6)
A A.foo ((stdin):5)
A A::B ((stdin):2)
A A::B::C ((stdin):3)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
M C#baz ((stdin):3)
D C#fooey ((stdin):2)
D D ((stdin):5)
D D.bar ((stdin):6)
eof
    end

    it "accepts --no-modified" do
      run('--compact', '--no-modified')
      expect(@data.string).to eq <<-eof
A A ((stdin):1) (...)
A A::B::C ((stdin):3)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
D C#fooey ((stdin):2)
D D ((stdin):5) (...)
eof
    end

    it "accepts --query" do
      run('--compact', '--query', 'o.type == :method')
      expect(@data.string).to eq <<-eof
A A#foo ((stdin):6)
A A.foo ((stdin):5)
A C.bar ((stdin):10)
A C.foo ((stdin):9)
M C#baz ((stdin):3)
D C#fooey ((stdin):2)
D D.bar ((stdin):6)
eof
    end
  end

  describe "File searching" do
    before do
      allow(@diff).to receive(:generate_yardoc)
    end

    it "searches for gem/.yardoc" do
      expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(true)
      expect(File).to receive(:directory?).with('gem2/.yardoc').and_return(true)
      expect(Registry).to receive(:load_yardoc).with('gem1/.yardoc')
      expect(Registry).to receive(:load_yardoc).with('gem2/.yardoc')
      @diff.run('gem1', 'gem2')
    end

    it "searches for argument as yardoc" do
      expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem2/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem1').and_return(true)
      expect(File).to receive(:directory?).with('gem2').and_return(true)
      expect(Registry).to receive(:load_yardoc).with('gem1')
      expect(Registry).to receive(:load_yardoc).with('gem2')
      @diff.run('gem1', 'gem2')
    end

    it "searches for installed gem" do
      expect(File).to receive(:directory?).with('gem1-1.0.0.gem/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem2-1.0.0/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem1-1.0.0.gem').and_return(false)
      expect(File).to receive(:directory?).with('gem2-1.0.0').and_return(false)
      spec1   = double(:spec)
      spec2   = double(:spec)
      allow(YARD::GemIndex).to receive(:each) {|&b| [spec1, spec2].each(&b) }
      allow(spec1).to receive(:full_name).and_return('gem1-1.0.0')
      allow(spec1).to receive(:name).and_return('gem1')
      allow(spec1).to receive(:version).and_return('1.0.0')
      allow(spec2).to receive(:full_name).and_return('gem2-1.0.0')
      allow(spec2).to receive(:name).and_return('gem2')
      allow(spec2).to receive(:version).and_return('1.0.0')
      expect(Registry).to receive(:yardoc_file_for_gem).with('gem1', '= 1.0.0').and_return('/path/to/file')
      expect(Registry).to receive(:yardoc_file_for_gem).with('gem2', '= 1.0.0').and_return(nil)
      expect(Registry).to receive(:load_yardoc).with('/path/to/file')
      expect(CLI::Gems).to receive(:run).with('gem2', '1.0.0').and_return(nil)
      allow(Dir).to receive(:chdir)
      @diff.run('gem1-1.0.0.gem', 'gem2-1.0.0')
    end

    it "searches for .gem file" do
      expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem2.gem/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem1').and_return(false)
      expect(File).to receive(:directory?).with('gem2.gem').and_return(false)
      expect(File).to receive(:exist?).with('gem1.gem').and_return(true)
      expect(File).to receive(:exist?).with('gem2.gem').and_return(true)
      expect(File).to receive(:open).with('gem1.gem', 'rb')
      expect(File).to receive(:open).with('gem2.gem', 'rb')
      allow(FileUtils).to receive(:mkdir_p)
      allow(Gem::Package).to receive(:open)
      allow(FileUtils).to receive(:rm_rf)
      @diff.run('gem1', 'gem2.gem')
    end

    it "searches for .gem file on rubygems.org" do
      expect(File).to receive(:directory?).with('gem1/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem2.gem/.yardoc').and_return(false)
      expect(File).to receive(:directory?).with('gem1').and_return(false)
      expect(File).to receive(:directory?).with('gem2.gem').and_return(false)
      expect(File).to receive(:exist?).with('gem1.gem').and_return(false)
      expect(File).to receive(:exist?).with('gem2.gem').and_return(false)
      expect(OpenURI).to receive(:open_uri).with('http://rubygems.org/downloads/gem1.gem')
      expect(OpenURI).to receive(:open_uri).with('http://rubygems.org/downloads/gem2.gem')
      allow(FileUtils).to receive(:mkdir_p)
      allow(Gem::Package).to receive(:open)
      allow(FileUtils).to receive(:rm_rf)
      @diff.run('gem1', 'gem2.gem')
    end

    it "raises an error if gem is not found" do
      expect(log).to receive(:error).with("Cannot find gem gem1")
      expect(log).to receive(:error).with("Cannot find gem gem2.gem")
      allow(@diff).to receive(:load_gem_data).and_return(false)
      @diff.run('gem1', 'gem2.gem')
    end
  end
end
yard-0.9.37/spec/cli/display_spec.rb000066400000000000000000000017761466601756300173070ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::Display do
  before do
    allow(Registry).to receive(:load)
    @object = CodeObjects::ClassObject.new(:root, :Foo)
    @object.docstring = 'Foo bar'
  end

  it "displays an object" do
    YARD::CLI::Display.run('-f', 'text', 'Foo')
    expect(log.io.string.strip).to eq(@object.format.strip)
  end

  it "wraps output with -l (defaulting to layout)" do
    YARD::CLI::Display.run('-l', '-f', 'html', 'Foo')
    formatted_output = @object.format(:format => :html).strip
    actual_output = log.io.string.strip
    expect(actual_output).not_to eq(formatted_output)
    expect(actual_output).to include(formatted_output)
  end

  it "wraps output with --layout onefile" do
    YARD::CLI::Display.run('--layout', 'onefile', '-f', 'html', 'Foo')
    formatted_output = @object.format(:format => :html).strip
    actual_output = log.io.string.strip
    expect(actual_output).not_to eq(formatted_output)
    expect(actual_output).to include(formatted_output)
  end
end
yard-0.9.37/spec/cli/gems_spec.rb000066400000000000000000000063661466601756300165750ustar00rootroot00000000000000# frozen_string_literal: true
require 'rubygems'

RSpec.describe YARD::CLI::Gems do
  before do
    @rebuild = false
    @gem1 = build_mock('gem1')
    @gem2 = build_mock('gem2')
    @gem3 = build_mock('gem3')
  end

  def build_mock(name, version = '1.0')
    OpenStruct.new  :name => name,
                    :version => version,
                    :full_gem_path => "/path/to/gems/#{name}-#{version}",
                    :yardoc_file => "/path/to/yardoc/#{name}-#{version}"
  end

  def build_specs(*specs)
    specs.each do |themock|
      allow(Registry).to receive(:yardoc_file_for_gem).with(themock.name, "= #{themock.version}").and_return(themock.yardoc_file)
      allow(File).to receive(:directory?).with(themock.yardoc_file).and_return(@rebuild)
      allow(File).to receive(:directory?).with(themock.full_gem_path).and_return(true)
      allow(Registry).to receive(:yardoc_file_for_gem).with(themock.name, "= #{themock.version}", true).and_return(themock.yardoc_file)
      expect(Dir).to receive(:chdir).with(themock.full_gem_path).and_yield
    end
    expect(Registry).to receive(:clear).exactly(specs.size).times
    expect(CLI::Yardoc).to receive(:run).exactly(specs.size).times
  end

  describe "#run" do
    it "builds all gem indexes if no gem is specified" do
      build_specs(@gem1, @gem2)
      expect(YARD::GemIndex).to receive(:each) {|&b| [@gem1, @gem2].each(&b) }
      CLI::Gems.run
    end

    it "allows gem to be specified" do
      build_specs(@gem1)
      expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 0').and_return([@gem1])
      CLI::Gems.run(@gem1.name)
    end

    it "allows multiple gems to be specified for building" do
      build_specs(@gem1, @gem2)
      expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, @gem1.version).and_return([@gem1])
      expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem2.name, '>= 0').and_return([@gem2])
      CLI::Gems.run(@gem1.name, @gem1.version, @gem2.name)
    end

    it "allows version to be specified with gem" do
      build_specs(@gem1)
      expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 1.0').and_return([@gem1])
      CLI::Gems.run(@gem1.name, '>= 1.0')
    end

    it "warns if one of the gems is not found, but it should process others" do
      build_specs(@gem2)
      expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 2.0').and_return([])
      expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem2.name, '>= 0').and_return([@gem2])
      expect(log).to receive(:warn).with(/#{@gem1.name} >= 2.0 could not be found/)
      CLI::Gems.run(@gem1.name, '>= 2.0', @gem2.name)
    end

    it "fails if specified gem(s) is/are not found" do
      expect(CLI::Yardoc).not_to receive(:run)
      expect(YARD::GemIndex).to receive(:find_all_by_name).with(@gem1.name, '>= 2.0').and_return([])
      expect(log).to receive(:warn).with(/#{@gem1.name} >= 2.0 could not be found/)
      expect(log).to receive(:error).with(/No specified gems could be found/)
      CLI::Gems.run(@gem1.name, '>= 2.0')
    end

    it "accepts --rebuild" do
      @rebuild = true
      build_specs(@gem1)
      expect(YARD::GemIndex).to receive(:each) {|&b| [@gem1].each(&b) }
      CLI::Gems.run('--rebuild')
    end
  end
end
yard-0.9.37/spec/cli/graph_spec.rb000066400000000000000000000011271466601756300167310ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::Graph do
  it "serializes output" do
    allow(Registry).to receive(:load).at_least(1).times
    allow(subject).to receive(:yardopts) { [] }
    expect(subject.options.serializer).to receive(:serialize).once
    subject.run
  end

  it "reads yardoc file from .yardopts" do
    allow(Registry).to receive(:load).at_least(1).times
    allow(subject).to receive(:yardopts) { %w(--db /path/to/db) }
    expect(subject.options.serializer).to receive(:serialize).once
    subject.run
    expect(Registry.yardoc_file).to eq '/path/to/db'
  end
end
yard-0.9.37/spec/cli/help_spec.rb000066400000000000000000000011411466601756300165540ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::Help do
  describe "#run" do
    it "accepts help command" do
      expect(CLI::Yardoc).to receive(:run).with('--help')
      CLI::Help.run('doc')
    end

    it "accepts no arguments (and lists all commands)" do
      expect(CLI::CommandParser).to receive(:run).with('--help')
      CLI::Help.run
    end

    it "shows all commands if command isn't found" do
      expect(CLI::CommandParser).to receive(:run).with('--help')
      help = CLI::Help.new
      expect(log).to receive(:puts).with(/not found/)
      help.run('unknown')
    end
  end
end
yard-0.9.37/spec/cli/i18n_spec.rb000066400000000000000000000064451466601756300164170ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::I18n do
  before do
    @i18n = YARD::CLI::I18n.new
    @i18n.use_document_file = false
    @i18n.use_yardopts_file = false
    output_path = File.expand_path(@i18n.options.serializer.basepath)
    allow(File).to receive(:open!).with(output_path, "wb")
    allow(YARD).to receive(:parse)
  end

  describe "Defaults" do
    before do
      @i18n = YARD::CLI::I18n.new
      allow(@i18n).to receive(:yardopts).and_return([])
      allow(@i18n).to receive(:support_rdoc_document_file!).and_return([])
      @i18n.parse_arguments
    end

    it "reads .yardopts by default" do
      expect(@i18n.use_yardopts_file).to be true
    end

    it "only shows public visibility by default" do
      expect(@i18n.visibilities).to eq [:public]
    end
  end

  describe "General options" do
    def self.should_accept(*args, &block)
      @counter ||= 0
      @counter += 1
      counter = @counter
      args.each do |arg|
        define_method("test_options_#{@counter}", &block)
        it("accepts #{arg}") { send("test_options_#{counter}", arg) }
      end
    end

    should_accept('--yardopts') do |arg|
      @i18n = YARD::CLI::I18n.new
      @i18n.use_document_file = false
      expect(@i18n).to receive(:yardopts).at_least(1).times.and_return([])
      @i18n.parse_arguments(arg)
      expect(@i18n.use_yardopts_file).to be true
      @i18n.parse_arguments('--no-yardopts', arg)
      expect(@i18n.use_yardopts_file).to be true
    end

    should_accept('--yardopts with filename') do |_arg|
      @i18n = YARD::CLI::I18n.new
      expect(File).to receive(:read_binary).with('.yardopts_i18n').and_return('')
      @i18n.use_document_file = false
      @i18n.parse_arguments('--yardopts', '.yardopts_i18n')
      expect(@i18n.use_yardopts_file).to be true
      expect(@i18n.options_file).to eq '.yardopts_i18n'
    end

    should_accept('--no-yardopts') do |arg|
      @i18n = YARD::CLI::I18n.new
      @i18n.use_document_file = false
      expect(@i18n).not_to receive(:yardopts)
      @i18n.parse_arguments(arg)
      expect(@i18n.use_yardopts_file).to be false
      @i18n.parse_arguments('--yardopts', arg)
      expect(@i18n.use_yardopts_file).to be false
    end

    should_accept('--exclude') do |arg|
      expect(YARD).to receive(:parse).with(['a'], ['nota', 'b'])
      @i18n.run(arg, 'nota', arg, 'b', 'a')
    end
  end

  describe ".yardopts handling" do
    before do
      @i18n.use_yardopts_file = true
    end

    it "searches for and uses yardopts file specified by #options_file" do
      expect(File).to receive(:read_binary).with("test").and_return("-o \n\nMYPATH\nFILE1 FILE2")
      @i18n.use_document_file = false
      @i18n.options_file = "test"
      expect(File).to receive(:open!).with(File.expand_path("MYPATH"), "wb")
      @i18n.run
      expect(@i18n.files).to eq ["FILE1", "FILE2"]
    end
  end

  describe "#run" do
    it "calls parse_arguments if run() is called" do
      expect(@i18n).to receive(:parse_arguments)
      @i18n.run
    end

    it "calls parse_arguments if run(arg1, arg2, ...) is called" do
      expect(@i18n).to receive(:parse_arguments)
      @i18n.run('--private', '-p', 'foo')
    end

    it "doesn't call parse_arguments if run(nil) is called" do
      expect(@i18n).not_to receive(:parse_arguments)
      @i18n.run(nil)
    end
  end
end
yard-0.9.37/spec/cli/list_spec.rb000066400000000000000000000003541466601756300166040ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::List do
  it "passes command off to Yardoc with --list" do
    expect(YARD::CLI::Yardoc).to receive(:run).with('-c', '--list', '--foo')
    YARD::CLI::List.run('--foo')
  end
end
yard-0.9.37/spec/cli/markup_types_spec.rb000066400000000000000000000012111466601756300203450ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::MarkupTypes do
  it "lists all available markup types" do
    YARD::CLI::MarkupTypes.run
    data = log.io.string
    exts = YARD::Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS
    YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS.each do |name, providers|
      expect(data).to match(/\b#{name}\b/)

      # Match all extensions
      exts[name].each do |ext|
        expect(data).to include(".#{ext}")
      end if exts[name]

      # Match all provider libs
      providers.each do |provider|
        expect(data).to match(/\b#{provider[:lib]}\b/)
      end
    end
  end
end
yard-0.9.37/spec/cli/server_spec.rb000066400000000000000000000251561466601756300171460ustar00rootroot00000000000000# frozen_string_literal: true

class Server::WebrickAdapter; def start; end end

RSpec.describe YARD::CLI::Server do
  before do
    allow(CLI::Yardoc).to receive(:run)
    @no_verify_libraries = false
    @set_libraries = true
    @no_adapter_mock = false
    @libraries = {}
    @options = {:single_library => true, :caching => false}
    @server_options = {:Port => 8808}
    @adapter = double(:adapter, :setup => nil)
    new_cli
  end

  after(:all) do
    Server::Adapter.shutdown
  end

  def new_cli
    @cli = subject
  end

  def rack_required
    require 'rack'
  rescue LoadError
    pending "rack required for this test"
  end

  def bundler_required
    require 'bundler'
  rescue LoadError
    pending "bundler required for this test"
  end

  def unstub_adapter
    @no_adapter_mock = true
  end

  def run(*args)
    if @set_libraries && @libraries.empty?
      library = Server::LibraryVersion.new(
        File.basename(Dir.pwd), nil, File.expand_path('.yardoc')
      )
      @libraries = {library.name => [library]}
    end
    unless @no_verify_libraries
      @libraries.values.each do |libs|
        libs.each do |lib|
          yfile = File.expand_path(lib.yardoc_file)
          allow(File).to receive(:exist?).with(yfile).and_return(true)
        end
      end
    end
    unless @no_adapter_mock
      allow(@cli).to receive(:adapter).and_return(@adapter)
      expect(@adapter).to receive(:new).
        with(@libraries, @options, @server_options).and_return(@adapter)
      expect(@adapter).to receive(:start)
    end

    @cli.run(*args.flatten)
    assert_libraries @libraries, @cli.libraries
  end

  def assert_libraries(expected_libs, actual_libs)
    expect(actual_libs).to eq expected_libs
    expected_libs.each do |name, libs|
      libs.each_with_index do |expected, i|
        actual = actual_libs[name][i]
        [:source, :source_path, :yardoc_file].each do |m|
          expect(actual.send(m)).to eq expected.send(m)
        end
      end
    end
  end

  # Mocks the existence of a file.
  def mock_file(filename, content = nil)
    allow(File).to receive(:exist?).with(filename).and_return(true)
    allow(File).to receive(:read_binary).with(filename).and_return(content) if content
    filename_e = File.expand_path(filename)
    mock_file(filename_e) unless filename_e == filename
  end

  before :each do
    allow(File).to receive(:exist?).and_call_original
  end

  context 'when .yardopts file exists' do
    before :each do
      Registry.yardoc_file = Registry::DEFAULT_YARDOC_FILE
      allow(File).to receive(:exist?).with(%r{\.yardoc/complete$}).and_return(false)
      allow(Dir).to receive(:pwd).and_return('/path/to/bar')
      allow(Dir).to receive(:chdir).and_yield
      @name = 'bar'
    end

    it "uses .yardoc as the yardoc db if .yardopts doesn't specify an alternate path" do
      mock_file '/path/to/bar/.yardopts', '--protected'
      @libraries[@name] = [Server::LibraryVersion.new(@name, nil, File.expand_path('/path/to/bar/.yardoc'))]
      @libraries.values[0][0].source_path = File.expand_path('/path/to/bar')
      run
    end

    it "uses the yardoc db location specified by .yardopts" do
      allow(File).to receive(:exist?).with(%r{/foo/complete$}).and_return(false)
      mock_file '/path/to/bar/.yardopts', '--db foo'
      @libraries[@name] = [Server::LibraryVersion.new(@name, nil, File.expand_path('/path/to/bar/foo'))]
      @libraries.values[0][0].source_path = File.expand_path('/path/to/bar')
      run
    end

    it "parses .yardopts when the library list is odd" do
      mock_file '/path/to/bar/.yardopts', '--db foo'
      @libraries['a'] = [Server::LibraryVersion.new('a', nil, File.expand_path('/path/to/bar/foo'))]
      @libraries.values[0][0].source_path = File.expand_path('/path/to/bar')
      run 'a'
    end
  end

  context "when .yardopts file doesn't exist" do
    before :each do
      allow(File).to receive(:exist?).with(%r{\.yardoc/complete$}).and_return(false)
      allow(File).to receive(:exist?).with(%r{^(.*[\\/])?\.yardopts$}).and_return(false)
    end

    it "defaults to .yardoc if no library is specified" do
      allow(Dir).to receive(:chdir).and_yield
      expect(Dir).to receive(:pwd).at_least(:once).and_return(File.expand_path('/path/to/foo'))
      @libraries['foo'] = [Server::LibraryVersion.new('foo', nil, File.expand_path('/path/to/foo/.yardoc'))]
      run
    end

    it "uses .yardoc as yardoc file if library list is odd" do
      @libraries['a'] = [Server::LibraryVersion.new('a', nil, File.expand_path('.yardoc'))]
      run 'a'
    end

    it "forces multi library if more than one library is listed" do
      allow(File).to receive(:exist?).with('b').and_return(true)
      @options[:single_library] = false
      @libraries['a'] = [Server::LibraryVersion.new('a', nil, File.expand_path('b'))]
      @libraries['c'] = [Server::LibraryVersion.new('c', nil, File.expand_path('.yardoc'))]
      run %w(a b c)
    end

    it "fails if specified directory does not exist" do
      @set_libraries = false
      allow(File).to receive(:exist?).with('b').and_return(false)
      expect(log).to receive(:warn).with(/Cannot find yardoc db for a: "b"/)
      run %w(a b)
    end
  end

  describe "General options" do
    before do
      allow(File).to receive(:exist?).with(%r{\.yardoc/complete$}).and_return(false)
      allow(File).to receive(:exist?).with(/\.yardopts$/).and_return(false)
    end

    it "accepts -m, --multi-library" do
      @options[:single_library] = false
      run '-m'
      run '--multi-library'
    end

    it "accepts -c, --cache" do
      @options[:caching] = true
      run '-c'
      run '--cache'
    end

    it "accepts -r, --reload" do
      @options[:incremental] = true
      run '-r'
      run '--reload'
    end

    it "accepts -d, --daemon" do
      @server_options[:daemonize] = true
      run '-d'
      run '--daemon'
    end

    it "accepts -B, --bind" do
      @server_options[:Host] = 'example.com'
      run '-B', 'example.com'
      run '--bind', 'example.com'
    end

    it "binds address with WebRick adapter" do
      @server_options[:Host] = 'example.com'
      run '-B', 'example.com', '-a', 'webrick'
      run '--bind', 'example.com', '-a', 'webrick'
    end

    it "binds address with Rack adapter" do
      @server_options[:Host] = 'example.com'
      run '-B', 'example.com', '-a', 'rack'
      run '--bind', 'example.com', '-a', 'rack'
    end

    it "accepts -p, --port" do
      @server_options[:Port] = 10
      run '-p', '10'
      run '--port', '10'
    end

    it "accepts --docroot" do
      @server_options[:DocumentRoot] = Dir.pwd + '/__foo/bar'
      run '--docroot', '__foo/bar'
    end

    it "accepts -a webrick to create WEBrick adapter" do
      expect(@cli).to receive(:adapter=).with(YARD::Server::WebrickAdapter)
      run '-a', 'webrick'
    end

    it "accepts -a rack to create Rack adapter" do
      rack_required
      expect(@cli).to receive(:adapter=).with(YARD::Server::RackAdapter)
      run '-a', 'rack'
    end

    it "defaults to Rack adapter if exists on system" do
      rack_required
      expect(@cli).to receive(:require).with('rubygems').and_return(false)
      expect(@cli).to receive(:require).with('rack').and_return(true)
      expect(@cli).to receive(:adapter=).with(YARD::Server::RackAdapter)
      @cli.send(:select_adapter)
    end

    it "falls back to WEBrick adapter if Rack is not on system" do
      expect(@cli).to receive(:require).with('rubygems').and_return(false)
      expect(@cli).to receive(:require).with('rack').and_raise(LoadError)
      expect(@cli).to receive(:adapter=).with(YARD::Server::WebrickAdapter)
      @cli.send(:select_adapter)
    end

    it "accepts -s, --server" do
      @server_options[:server] = 'thin'
      run '-s', 'thin'
      run '--server', 'thin'
    end

    it "accepts -g, --gems" do
      @no_verify_libraries = true
      @options[:single_library] = false
      @libraries['gem1'] = [Server::LibraryVersion.new('gem1', '1.0.0', nil, :gem)]
      @libraries['gem2'] = [Server::LibraryVersion.new('gem2', '1.0.0', nil, :gem)]
      gem1 = double(:gem1, :name => 'gem1', :version => '1.0.0', :full_gem_path => '/path/to/foo')
      gem2 = double(:gem2, :name => 'gem2', :version => '1.0.0', :full_gem_path => '/path/to/bar')
      specs = {'gem1' => gem1, 'gem2' => gem2}
      allow(YARD::GemIndex).to receive(:find_all_by_name) do |k, _ver|
        specs.grep(k).map {|name| specs[name] }
      end
      allow(YARD::GemIndex).to receive(:each) {|&b| specs.values.each(&b) }
      run '-g'
      run '--gems'
    end

    it "accepts -G, --gemfile" do
      bundler_required
      @no_verify_libraries = true
      @options[:single_library] = false

      @libraries['gem1'] = [Server::LibraryVersion.new('gem1', '1.0.0', nil, :gem)]
      @libraries['gem2'] = [Server::LibraryVersion.new('gem2', '1.0.0', nil, :gem)]
      gem1 = double(:gem1, :name => 'gem1', :version => '1.0.0', :full_gem_path => '/path/to/foo')
      gem2 = double(:gem2, :name => 'gem2', :version => '1.0.0', :full_gem_path => '/path/to/bar')
      lockfile_parser = double(:new, :specs => [gem1, gem2])
      allow(Bundler::LockfileParser).to receive(:new).and_return(lockfile_parser)

      expect(File).to receive(:exist?).at_least(2).times.with("Gemfile.lock").and_return(true)
      allow(File).to receive(:read)

      run '-G'
      run '--gemfile'

      expect(File).to receive(:exist?).with("different_name.lock").and_return(true)
      run '--gemfile', 'different_name'
    end

    it "warns if lockfile is not found (with -G)" do
      bundler_required
      expect(File).to receive(:exist?).with(/\.yardopts$/).at_least(:once).and_return(false)
      expect(File).to receive(:exist?).with('somefile.lock').and_return(false)
      expect(log).to receive(:warn).with(/Cannot find somefile.lock/)
      run '-G', 'somefile'
    end

    it "displays an error if Bundler not available (with -G)" do
      expect(@cli).to receive(:require).with('bundler').and_raise(LoadError)
      expect(log).to receive(:error).with(/Bundler not available/)
      run '-G'
    end

    it "loads template paths after adapter template paths" do
      unstub_adapter
      @cli.adapter = Server::WebrickAdapter
      run '-t', 'foo'
      expect(Templates::Engine.template_paths.last).to eq 'foo'
    end

    it "loads ruby code (-e) after adapter" do
      unstub_adapter
      @cli.adapter = Server::WebrickAdapter
      path = File.dirname(__FILE__) + '/tmp.adapterscript.rb'
      begin
        File.open(path, 'w') do |f|
          f.puts "YARD::Templates::Engine.register_template_path 'foo'"
          f.flush
          run '-e', f.path
          expect(Templates::Engine.template_paths.last).to eq 'foo'
        end
      ensure
        File.unlink(path)
      end
    end
  end
end
yard-0.9.37/spec/cli/stats_spec.rb000066400000000000000000000053521466601756300167720ustar00rootroot00000000000000# frozen_string_literal: true
require 'stringio'

RSpec.describe YARD::CLI::Stats do
  before do
    Registry.clear
    YARD.parse_string <<-eof
      class A
        CONST = 1

        def foo; end

        attr_reader :fooattr

        # Documented
        def bar; end
      end
      module B; end
    eof

    @main_stats =
      "Files:           1\n" \
      "Modules:         1 (    1 undocumented)\n" \
      "Classes:         1 (    1 undocumented)\n" \
      "Constants:       1 (    1 undocumented)\n" \
      "Attributes:      1 (    0 undocumented)\n" \
      "Methods:         2 (    1 undocumented)\n" \
      " 33.33% documented\n"

    @output = StringIO.new
    @stats = CLI::Stats.new(false)
    allow(@stats).to receive(:support_rdoc_document_file!).and_return([])
    allow(@stats).to receive(:yardopts).and_return([])
    allow(log).to receive(:puts) {|*args| @output << args.join("\n") << "\n" }
  end

  it "lists undocumented objects with --list-undoc when there are undocumented objects" do
    @stats.run('--list-undoc')
    expect(@output.string).to eq <<-eof
#{@main_stats}
Undocumented Objects:

(in file: (stdin))
A
A#foo
A::CONST
B
eof
  end

  it "lists no undocumented objects with --list-undoc when there is nothing undocumented" do
    Registry.clear
    YARD.parse_string <<-eof
      # documentation
      def foo; end
    eof
    @stats.run('--list-undoc')
    expect(@output.string).to eq "Files:           1\n" \
                                 "Modules:         0 (    0 undocumented)\n" \
                                 "Classes:         0 (    0 undocumented)\n" \
                                 "Constants:       0 (    0 undocumented)\n" \
                                 "Attributes:      0 (    0 undocumented)\n" \
                                 "Methods:         1 (    0 undocumented)\n" \
                                 " 100.00% documented\n"
  end

  it "lists undocumented objects in compact mode with --list-undoc --compact" do
    @stats.run('--list-undoc', '--compact')
    expect(@output.string).to eq <<-eof
#{@main_stats}
Undocumented Objects:
A            ((stdin):1)
A#foo        ((stdin):4)
A::CONST     ((stdin):2)
B            ((stdin):11)
eof
  end

  it "still lists stats with --quiet" do
    @stats.run('--quiet')
    expect(@output.string).to eq @main_stats
  end

  it "ignores everything with --no-public" do
    @stats.run('--no-public')
    expect(@output.string).to eq(
      "Files:           0\n" \
      "Modules:         0 (    0 undocumented)\n" \
      "Classes:         0 (    0 undocumented)\n" \
      "Constants:       0 (    0 undocumented)\n" \
      "Attributes:      0 (    0 undocumented)\n" \
      "Methods:         0 (    0 undocumented)\n" \
      " 100.00% documented\n"
    )
  end
end
yard-0.9.37/spec/cli/yard_on_yard_spec.rb000066400000000000000000000021421466601756300203000ustar00rootroot00000000000000# frozen_string_literal: true

$TOPDIR = File.expand_path(File.join(File.dirname(__FILE__), '../..'))

require 'fileutils'

RSpec.describe YARD::CLI::Yardoc do
  include FileUtils

  context 'building the documentation of YARD itself' do
    before(:context) do
      rm_rf File.join($TOPDIR, 'doc')
      rm_rf File.join($TOPDIR, '.yardoc')

      # Note: as this is very time consuming, we do it only once
      Dir.chdir($TOPDIR) do
        @res = YARD::CLI::Yardoc.new.run('--title', 'YARD-On-YARD')
      end
    end

    it 'succeeds and creates doc/ and .yardoc/' do
      expect(@res).to be true
      expect(Dir.exist?('doc')).to be true
      expect(Dir.exist?('.yardoc')).to be true
    end

    it 'writes the given title in each documentation file' do
      Dir.glob(File.join($TOPDIR, 'doc/**/*.html')) do |htmlfile|
        next if %w(
          frames file_list class_list method_list tag_list _index
        ).include?(File.basename(htmlfile, '.html'))
        html = File.read(htmlfile)

        expect(html.index('— YARD-On-YARD')).to be >= 0
      end
    end
  end
end if ENV['CI'] || ENV['YY']
yard-0.9.37/spec/cli/yardoc_spec.rb000066400000000000000000001034301466601756300171110ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::CLI::Yardoc do
  before do
    @yardoc = YARD::CLI::Yardoc.new
    @yardoc.statistics = false
    @yardoc.use_document_file = false
    @yardoc.use_yardopts_file = false
    @yardoc.generate = false
    allow(Templates::Engine).to receive(:render)
    allow(Templates::Engine).to receive(:generate)
    allow(YARD).to receive(:parse)
    allow(Registry).to receive(:load)
    allow(Registry).to receive(:save)
    allow(File).to receive(:open!)
  end

  describe "Defaults" do
    before do
      @yardoc = CLI::Yardoc.new
      allow(@yardoc).to receive(:yardopts).and_return([])
      allow(@yardoc).to receive(:support_rdoc_document_file!).and_return([])
      @yardoc.parse_arguments
    end

    it "does not use cache by default" do
      expect(@yardoc.use_cache).to be false
    end

    it "prints statistics by default" do
      expect(@yardoc.statistics).to be true
    end

    it "generates output by default" do
      expect(@yardoc.generate).to be true
    end

    it "reads .yardopts by default" do
      expect(@yardoc.use_yardopts_file).to be true
    end

    it "reads .document by default" do
      expect(@yardoc.use_document_file).to be true
    end

    it "uses lib, app, and ext as default file glob paths" do
      expect(@yardoc.files).to eq Parser::SourceParser::DEFAULT_PATH_GLOB
    end

    it "uses rdoc as default markup type (but falls back on none)" do
      expect(@yardoc.options.markup).to eq :rdoc
    end

    it "uses default as default template" do
      expect(@yardoc.options.template).to eq :default
    end

    it "uses HTML as default format" do
      expect(@yardoc.options.format).to eq :html
    end

    it "uses 'Object' as default return type" do
      expect(@yardoc.options.default_return).to eq 'Object'
    end

    it "does not hide void return types by default" do
      expect(@yardoc.options.hide_void_return).to be false
    end

    it "only shows public visibility by default" do
      expect(@yardoc.visibilities).to eq [:public]
    end

    it "does not list objects by default" do
      expect(@yardoc.list).to be false
    end

    it "does not embed mixins by default" do
      expect(@yardoc.options.embed_mixins).to be_empty
    end

    it "does not set any locale by default" do
      expect(@yardoc.options.locale).to be nil
    end
  end

  describe "General options" do
    def self.should_accept(*args, &block)
      @counter ||= 0
      @counter += 1
      counter = @counter
      define_method("test_options_#{@counter}", &block)
      args.each do |arg|
        it("accepts #{arg}") { send("test_options_#{counter}", arg) }
      end
    end

    should_accept('--single-db') do |arg|
      @yardoc.parse_arguments(arg)
      expect(Registry.single_object_db).to be true
      Registry.single_object_db = nil
    end

    should_accept('--no-single-db') do |arg|
      @yardoc.parse_arguments(arg)
      expect(Registry.single_object_db).to be false
      Registry.single_object_db = nil
    end

    should_accept('-c', '--use-cache') do |arg|
      @yardoc.parse_arguments(arg)
      expect(@yardoc.use_cache).to be true
    end

    should_accept('--no-cache') do |arg|
      @yardoc.parse_arguments(arg)
      expect(@yardoc.use_cache).to be false
    end

    should_accept('--yardopts') do |arg|
      @yardoc = CLI::Yardoc.new
      @yardoc.use_document_file = false
      expect(@yardoc).to receive(:yardopts).at_least(1).times.and_return([])
      @yardoc.parse_arguments(arg)
      expect(@yardoc.use_yardopts_file).to be true
      @yardoc.parse_arguments('--no-yardopts', arg)
      expect(@yardoc.use_yardopts_file).to be true
    end

    should_accept('--yardopts with filename') do |_arg|
      @yardoc = CLI::Yardoc.new
      expect(File).to receive(:read_binary).with('.foobar').and_return('')
      @yardoc.use_document_file = false
      @yardoc.parse_arguments('--yardopts', '.foobar')
      expect(@yardoc.use_yardopts_file).to be true
      expect(@yardoc.options_file).to eq '.foobar'
    end

    should_accept('--no-yardopts') do |arg|
      @yardoc = CLI::Yardoc.new
      @yardoc.use_document_file = false
      expect(@yardoc).not_to receive(:yardopts)
      @yardoc.parse_arguments(arg)
      expect(@yardoc.use_yardopts_file).to be false
      @yardoc.parse_arguments('--yardopts', arg)
      expect(@yardoc.use_yardopts_file).to be false
    end

    should_accept('--document') do |arg|
      @yardoc = CLI::Yardoc.new
      @yardoc.use_yardopts_file = false
      expect(@yardoc).to receive(:support_rdoc_document_file!).and_return([])
      @yardoc.parse_arguments('--no-document', arg)
      expect(@yardoc.use_document_file).to be true
    end

    should_accept('--no-document') do |arg|
      @yardoc = CLI::Yardoc.new
      @yardoc.use_yardopts_file = false
      expect(@yardoc).not_to receive(:support_rdoc_document_file!)
      @yardoc.parse_arguments('--document', arg)
      expect(@yardoc.use_document_file).to be false
    end

    should_accept('-b', '--db') do |arg|
      @yardoc.parse_arguments(arg, 'test')
      expect(Registry.yardoc_file).to eq 'test'
      Registry.yardoc_file = '.yardoc'
    end

    should_accept('-n', '--no-output') do |arg|
      expect(Templates::Engine).not_to receive(:generate)
      @yardoc.run(arg)
    end

    should_accept('--exclude') do |arg|
      expect(YARD).to receive(:parse).with(['a'], ['nota', 'b'])
      @yardoc.run(arg, 'nota', arg, 'b', 'a')
    end

    should_accept('--no-save') do |arg|
      expect(YARD).to receive(:parse)
      expect(Registry).not_to receive(:save)
      @yardoc.run(arg)
    end

    # This example relies on processing Yard's own documentation, and with
    # --fail-on-warning option on, will raise a SystemExit error if building
    # that documentation produces any one warning.
    #
    # Unless handled, it will cause immediate and abnormal process exit,
    # without running remaining tests, and with non-successful exit status.
    #
    # While suppressing exceptions is generally a bad practice and against this
    # project's style guide, here it is well advocated,
    # hence Lint/HandleExceptions cop is disabled.
    should_accept('--fail-on-warning') do |arg|
      expect(YARD).to receive(:parse)
      begin
        @yardoc.run(arg)
      rescue SystemExit # rubocop:disable Lint/HandleExceptions
      end
    end
  end

  describe "Output options" do
    it "accepts --title" do
      @yardoc.parse_arguments('--title', 'hello world')
      expect(@yardoc.options.title).to eq 'hello world'
    end

    it "allows --title to have multiple spaces in .yardopts" do
      expect(File).to receive(:read_binary).with("test").and_return("--title \"Foo Bar\"")
      @yardoc.options_file = "test"
      @yardoc.use_yardopts_file = true
      @yardoc.run
      expect(@yardoc.options.title).to eq "Foo Bar"
    end

    it "aliases --main to the --readme flag" do
      Dir.chdir(File.join(File.dirname(__FILE__), '..', '..')) do
        @yardoc.parse_arguments('--main', 'README.md')
        expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.md', '')
      end
    end

    it "selects a markup provider when --markup-provider or -mp is set" do
      @yardoc.parse_arguments("-M", "test")
      expect(@yardoc.options.markup_provider).to eq :test
      @yardoc.parse_arguments("--markup-provider", "test2")
      expect(@yardoc.options.markup_provider).to eq :test2
    end

    it "selects a markup format when -m is set" do
      expect(@yardoc).to receive(:verify_markup_options).and_return(true)
      @yardoc.generate = true
      @yardoc.parse_arguments('-m', 'markdown')
      expect(@yardoc.options.markup).to eq :markdown
    end

    it "accepts --default-return" do
      @yardoc.parse_arguments(*%w(--default-return XYZ))
      expect(@yardoc.options.default_return).to eq "XYZ"
    end

    it "allows --hide-void-return to be set" do
      @yardoc.parse_arguments(*%w(--hide-void-return))
      expect(@yardoc.options.hide_void_return).to be true
    end

    it "accepts --embed-mixins" do
      @yardoc.parse_arguments(*%w(--embed-mixins))
      expect(@yardoc.options.embed_mixins).to eq ['*']
    end

    it "accepts --embed-mixin MODULE" do
      @yardoc.parse_arguments(*%w(--embed-mixin MyModule))
      expect(@yardoc.options.embed_mixins).to eq ['MyModule']
    end

    it "generates all objects with --use-cache" do
      expect(YARD).to receive(:parse)
      expect(Registry).to receive(:load)
      expect(Registry).to receive(:load_all)
      allow(@yardoc).to receive(:generate).and_return(true)
      @yardoc.run(*%w(--use-cache))
    end

    it "does not print statistics with --no-stats" do
      allow(@yardoc).to receive(:statistics).and_return(false)
      expect(CLI::Stats).not_to receive(:new)
      @yardoc.run(*%w(--no-stats))
    end

    it "disables progress bar with --no-progress" do
      old = log.show_progress
      log.show_progress = true
      @yardoc.run(*%w(--no-progress))
      expect(log.show_progress).to eq false
      log.show_progress = old
    end

    describe "--asset" do
      before do
        @yardoc.generate = true
        allow(@yardoc).to receive(:run_generate)
      end

      it "copies assets to output directory" do
        expect(FileUtils).to receive(:cp_r).with('a', 'doc/a')
        @yardoc.run(*%w(--asset a))
        expect(@yardoc.assets).to eq('a' => 'a')
      end

      it "allows multiple --asset options" do
        expect(FileUtils).to receive(:cp_r).with('a', 'doc/a')
        expect(FileUtils).to receive(:cp_r).with('b', 'doc/b')
        @yardoc.run(*%w(--asset a --asset b))
        expect(@yardoc.assets).to eq('a' => 'a', 'b' => 'b')
      end

      it "does not allow from or to to refer to a path above current path" do
        expect(log).to receive(:warn).exactly(4).times.with(/invalid/i)
        @yardoc.run(*%w(--asset ../../../etc/passwd))
        expect(@yardoc.assets).to be_empty
        @yardoc.run(*%w(--asset a/b/c/d/../../../../../../etc/passwd))
        expect(@yardoc.assets).to be_empty
        @yardoc.run(*%w(--asset /etc/passwd))
        expect(@yardoc.assets).to be_empty
        @yardoc.run(*%w(--asset normal:/etc/passwd))
        expect(@yardoc.assets).to be_empty
      end

      it "allows from:to syntax" do
        expect(FileUtils).to receive(:cp_r).with(%r{foo(\/\.)?}, 'doc/bar')
        @yardoc.run(*%w(--asset foo:bar))
        expect(@yardoc.assets).to eq('foo' => 'bar')
      end

      it "does not put from inside of to/ if from is a directory" do
        begin
          from = 'tmp_foo'
          to = 'tmp_bar'
          full_to = File.join(File.dirname(__FILE__), to)
          FileUtils.mkdir_p(from)
          @yardoc.options.serializer.basepath = File.dirname(__FILE__)
          @yardoc.run("--asset", "#{from}:#{to}")
          @yardoc.run("--asset", "#{from}:#{to}")
          expect(File.directory?(full_to)).to be true
          expect(File.directory?(File.join(full_to, 'tmp_foo'))).to be false
        ensure
          FileUtils.rm_rf(from)
          FileUtils.rm_rf(full_to)
        end
      end
    end

    describe "--locale" do
      it "applies specified locale to all extra file objects" do
        allow(File).to receive(:read).with('extra_file1').and_return('')
        allow(File).to receive(:read).with('extra_file2').and_return('')

        extra_file_object1 = CodeObjects::ExtraFileObject.new('extra_file1')
        extra_file_object2 = CodeObjects::ExtraFileObject.new('extra_file2')
        expect(extra_file_object1).to receive(:locale=).with('fr')
        expect(extra_file_object2).to receive(:locale=).with('fr')

        allow(CodeObjects::ExtraFileObject).to receive(:new).with('extra_file1').and_return(extra_file_object1)
        allow(CodeObjects::ExtraFileObject).to receive(:new).with('extra_file2').and_return(extra_file_object2)
        allow(Dir).to receive(:glob).with('README{,*[^~]}').and_return([])
        allow(File).to receive(:file?).with('extra_file1').and_return(true)
        allow(File).to receive(:file?).with('extra_file2').and_return(true)
        @yardoc.run('--locale=fr', '-', 'extra_file1', 'extra_file2')
      end
    end

    describe "--po-dir" do
      it "sets Registry.po_dir" do
        expect(Registry).to receive(:po_dir=).with("locale")
        @yardoc.run('--po-dir=locale')
      end
    end
  end

  describe "--[no-]api" do
    before { Registry.clear }

    it "allows --api name" do
      YARD.parse_string <<-eof
        # @api private
        class Foo; end
        # @api public
        class Bar; end
        class Baz; end
      eof
      @yardoc.run('--api', 'private')
      expect(@yardoc.options.verifier.run(Registry.all)).to eq [P('Foo')]
    end

    it "allows multiple --api's to all be shown" do
      YARD.parse_string <<-eof
        # @api private
        class Foo; end
        # @api public
        class Bar; end
        class Baz; end
      eof
      @yardoc.run('--api', 'private', '--api', 'public')
      expect(@yardoc.options.verifier.run(Registry.all).
        sort_by(&:path)).to eq [P('Bar'), P('Foo')]
    end

    it "allows --no-api to specify objects with no @api tag" do
      YARD.parse_string <<-eof
        # @api private
        class Foo; end
        # @api public
        class Bar; end
        class Baz; end
      eof
      @yardoc.run('--api', '')
      expect(@yardoc.options.verifier.run(Registry.all)).to eq [P('Baz')]
      @yardoc.options.verifier = Verifier.new
      @yardoc.run('--no-api')
      expect(@yardoc.options.verifier.run(Registry.all)).to eq [P('Baz')]
    end

    it "allows --no-api to work with other --api switches" do
      YARD.parse_string <<-eof
        # @api private
        class Foo; end
        # @api public
        class Bar; end
        class Baz; end
      eof
      @yardoc.run('--no-api', '--api', 'public')
      expect(@yardoc.options.verifier.run(Registry.all).
        sort_by(&:path)).to eq [P('Bar'), P('Baz')]
    end

    it "ensures Ruby code cannot be used" do
      [':symbol', '42', '"; exit'].each do |ruby|
        @yardoc.options.verifier.expressions = []
        @yardoc.run('--api', ruby)
        expect(@yardoc.options.verifier.expressions[1]).to include(ruby.inspect)
      end
    end
  end

  describe "--hide-api option" do
    it "allows --hide-api to hide objects with api tags" do
      YARD.parse_string <<-eof
        # @api private
        class Foo; end
        class Bar; end
        class Baz; end
      eof
      @yardoc.run('--hide-api', 'private')
      expect(@yardoc.options.verifier.run(Registry.all).
        sort_by(&:path)).to eq [P('Bar'), P('Baz')]
    end

    it "allows --hide-api to work with --api" do
      YARD.parse_string <<-eof
        # @api private
        class Foo; end
        # @api public
        class Bar; end
        class Baz; end
      eof
      @yardoc.run('--api', 'public', '--hide-api', 'private')
      expect(@yardoc.options.verifier.run(Registry.all).
        sort_by(&:path)).to eq [P('Bar')]
    end
  end

  describe "--no-private option" do
    it "accepts --no-private" do
      obj = double(:object)
      expect(obj).to receive(:tag).ordered.with(:private).and_return(true)
      @yardoc.parse_arguments(*%w(--no-private))
      expect(@yardoc.options.verifier.call(obj)).to be false
    end

    it "hides object if namespace is @private with --no-private" do
      ns = double(:namespace, :type => :module)
      expect(ns).to receive(:tag).with(:private).and_return(true)
      obj = double(:object, :namespace => ns)
      expect(obj).to receive(:tag).with(:private).and_return(false)
      @yardoc.parse_arguments(*%w(--no-private))
      expect(@yardoc.options.verifier.call(obj)).to be false
    end

    it "does not call #tag on namespace if namespace is proxy with --no-private" do
      ns = double(:namespace)
      expect(ns).to receive(:is_a?).with(CodeObjects::Proxy).and_return(true)
      expect(ns).not_to receive(:tag)
      obj = double(:object, :type => :class, :namespace => ns, :visibility => :public)
      expect(obj).to receive(:tag).ordered.with(:private).and_return(false)
      @yardoc.parse_arguments(*%w(--no-private))
      expect(@yardoc.options.verifier.call(obj)).to be true
    end

    # @bug gh-197
    it "does not call #tag on namespace if namespace is proxy with --no-private" do
      Registry.clear
      YARD.parse_string "module Qux; class Foo::Bar; end; end"
      foobar = Registry.at('Foo::Bar')
      foobar.namespace.type = :module
      @yardoc.parse_arguments(*%w(--no-private))
      expect(@yardoc.options.verifier.call(foobar)).to be true
    end

    it "does not call #tag on proxy object" do # @bug gh-197
      @yardoc.parse_arguments(*%w(--no-private))
      expect(@yardoc.options.verifier.call(P('ProxyClass'))).to be true
    end

    it "hides methods inside a 'private' class/module with --no-private" do
      Registry.clear
      YARD.parse_string <<-eof
        # @private
        class ABC
          def foo; end
        end
      eof
      @yardoc.parse_arguments(*%w(--no-private))
      expect(@yardoc.options.verifier.call(Registry.at('ABC'))).to be false
      expect(@yardoc.options.verifier.call(Registry.at('ABC#foo'))).to be false
    end
  end

  describe ".yardopts and .document handling" do
    before do
      @yardoc.use_yardopts_file = true
    end

    it "searches for and uses yardopts file specified by #options_file" do
      expect(File).to receive(:read_binary).with("test").and_return("-o \n\nMYPATH\nFILE1 FILE2")
      @yardoc.use_document_file = false
      @yardoc.options_file = "test"
      @yardoc.run
      expect(@yardoc.options.serializer.options[:basepath]).to eq "MYPATH"
      expect(@yardoc.files).to eq ["FILE1", "FILE2"]
    end

    it "uses String#shell_split to split .yardopts tokens" do
      optsdata = String.new("foo bar")
      expect(optsdata).to receive(:shell_split)
      expect(File).to receive(:read_binary).with("test").and_return(optsdata)
      @yardoc.options_file = "test"
      @yardoc.run
    end

    it "allows opts specified in command line to override yardopts file" do
      expect(File).to receive(:read_binary).with(".yardopts").and_return("-o NOTMYPATH")
      @yardoc.run("-o", "MYPATH", "FILE")
      expect(@yardoc.options.serializer.options[:basepath]).to eq "MYPATH"
      expect(@yardoc.files).to eq ["FILE"]
    end

    it "loads the RDoc .document file if found" do
      expect(File).to receive(:read_binary).with(".yardopts").and_return("-o NOTMYPATH")
      @yardoc.use_document_file = true
      allow(@yardoc).to receive(:support_rdoc_document_file!).and_return(["FILE2", "FILE3"])
      @yardoc.run("-o", "MYPATH", "FILE1")
      expect(@yardoc.options.serializer.options[:basepath]).to eq "MYPATH"
      expect(@yardoc.files).to eq ["FILE2", "FILE3", "FILE1"]
    end
  end

  describe "Query options" do
    after { Registry.clear }

    it "hides private constants in with default visibilities" do
      classobj = CodeObjects::ClassObject.new(:root, :Foo) {|o| o.visibility = :private }
      @yardoc.run
      expect(@yardoc.options.verifier.run([classobj])).to eq []
    end

    it "sets up visibility rules as verifier" do
      methobj = CodeObjects::MethodObject.new(:root, :test) {|o| o.visibility = :private }
      expect(File).to receive(:read_binary).with("test").and_return("--private")
      @yardoc.use_yardopts_file = true
      @yardoc.options_file = "test"
      @yardoc.run
      expect(@yardoc.options.verifier.call(methobj)).to be true
    end

    it "accepts a --query" do
      @yardoc.parse_arguments(*%w(--query @return))
      expect(@yardoc.options.verifier).to be_a(Verifier)
    end

    it "accepts multiple --query arguments" do
      obj = double(:object)
      expect(obj).to receive(:tag).ordered.with('return').and_return(true)
      expect(obj).to receive(:tag).ordered.with('tag').and_return(false)
      @yardoc.parse_arguments(*%w(--query @return --query @tag))
      expect(@yardoc.options.verifier).to be_a(Verifier)
      expect(@yardoc.options.verifier.call(obj)).to be false
    end
  end

  describe "Extra file arguments" do
    def expect_extra_files_valid(obj, validity_hash = {})
      validity_hash.each do |filename, valid|
        expect(obj).to receive(:extra_file_valid?).with(filename).and_return(valid)
      end
    end

    it "accepts extra files if specified after '-' with source files" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return([])
      expect(File).to receive(:file?).with('extra_file1').and_return(true)
      expect(File).to receive(:file?).with('extra_file2').and_return(true)
      expect(File).to receive(:read).with('extra_file1').and_return('')
      expect(File).to receive(:read).with('extra_file2').and_return('')
      @yardoc.parse_arguments(*%w(file1 file2 - extra_file1 extra_file2))
      expect(@yardoc.files).to eq %w(file1 file2)
      expect(@yardoc.options.files).to eq(
        [CodeObjects::ExtraFileObject.new('extra_file1', ''),
          CodeObjects::ExtraFileObject.new('extra_file2', '')]
      )
    end

    it "accepts files section only containing extra files" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return([])
      @yardoc.parse_arguments(*%w(- LICENSE))
      expect(@yardoc.files).to eq Parser::SourceParser::DEFAULT_PATH_GLOB
      expect(@yardoc.options.files).to eq [CodeObjects::ExtraFileObject.new('LICENSE', '')]
    end

    it "accepts globs as extra files" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return []
      expect(Dir).to receive(:glob).with('*.txt').and_return ['a.txt', 'b.txt']
      expect(File).to receive(:read).with('a.txt').and_return('')
      expect(File).to receive(:read).with('b.txt').and_return('')
      expect(File).to receive(:file?).with('a.txt').and_return(true)
      expect(File).to receive(:file?).with('b.txt').and_return(true)
      @yardoc.parse_arguments(*%w(file1 file2 - *.txt))
      expect(@yardoc.files).to eq %w(file1 file2)
      expect(@yardoc.options.files).to eq(
        [CodeObjects::ExtraFileObject.new('a.txt', ''),
          CodeObjects::ExtraFileObject.new('b.txt', '')]
      )
    end

    it "warns if extra file is not found" do
      expect(log).to receive(:warn).with(/Could not find file: UNKNOWN/)
      @yardoc.parse_arguments(*%w(- UNKNOWN))
    end

    it "warns if readme file is not found" do
      expect(log).to receive(:warn).with(/Could not find file: UNKNOWN/)
      @yardoc.parse_arguments(*%w(-r UNKNOWN))
    end

    it "warns on absolute paths in extra files" do
      expect(log).to receive(:warn).with(%r{Invalid file: /path/to/file})
      @yardoc.parse_arguments(*%w(- /path/to/file))
    end

    it "warns on absolute paths in readme" do
      expect(log).to receive(:warn).with(%r{Invalid file: /path/to/file})
      @yardoc.parse_arguments(*%w(-r /path/to/file))
    end

    it "uses first file as readme if no readme is specified when using --one-file" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return []
      expect(Dir).to receive(:glob).with('lib/*.rb').and_return(['lib/foo.rb'])
      expect_extra_files_valid(@yardoc, 'lib/foo.rb' => true)
      expect(File).to receive(:read).with('lib/foo.rb').and_return('')
      @yardoc.parse_arguments(*%w(--one-file lib/*.rb))
      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('lib/foo.rb', '')
    end

    it "uses no readme if files is empty and no readme is specified when using --one-file" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return []
      @yardoc.parse_arguments '--one-file', ''
      expect(@yardoc.options.readme).to be_nil
    end

    it "uses readme if it exists when using --one-file" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README']
      expect_extra_files_valid(@yardoc, 'README' => true)
      expect_extra_files_valid(@yardoc, 'README' => true)
      expect(File).to receive(:read).with('README').and_return('')
      @yardoc.parse_arguments(*%w(--one-file lib/*.rb))
      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README', '')
    end

    it "selects readme with no file extension over readme with file extension" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README.md', 'README-DEV', 'README']
      expect_extra_files_valid(@yardoc, 'README.md' => true, 'README-DEV' => true, 'README' => true)
      expect_extra_files_valid(@yardoc, 'README' => true)
      expect(File).to receive(:read).with('README').and_return('')
      @yardoc.parse_arguments
      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README', '')
    end

    it "selects readme with no suffix over readme with hyphenated suffix" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README-fr.md', 'README.long-extension', 'README-de.md']
      expect_extra_files_valid(@yardoc, 'README-fr.md' => true, 'README.long-extension'=> true, 'README-de.md' => true)
      expect_extra_files_valid(@yardoc, 'README.long-extension'=> true)
      expect(File).to receive(:read).with('README.long-extension').and_return('')
      @yardoc.parse_arguments
      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.long-extension', '')
    end

    it "selects readme with no suffix over readme with dotted suffix" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README.fr.md', 'README.md', 'README.de.md']
      expect(File).to receive(:read).with('README.md').and_return('')
      @yardoc.parse_arguments
      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.md', '')
    end

    it "selects first readme from lexically sorted list" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README-fr.md', 'README-de.md']
      expect_extra_files_valid(@yardoc, 'README-fr.md'=> true, 'README-de.md' => true)
      expect_extra_files_valid(@yardoc, 'README-de.md' => true)
      expect(File).to receive(:read).with('README-de.md').and_return('')
      @yardoc.parse_arguments
      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README-de.md', '')
    end

    it "selects readme that exists over a readme that does not" do
      expect(Dir).to receive(:glob).with('README{,*[^~]}').and_return ['README.fr.md', 'README.md', 'README.de.md']
      expect_extra_files_valid(@yardoc, 'README.fr.md'=> true, 'README.md' => false, 'README.de.md' => false)
      expect_extra_files_valid(@yardoc, 'README.fr.md'=> true)
      expect(File).to receive(:read).with('README.fr.md').and_return('')
      @yardoc.parse_arguments
      expect(@yardoc.options.readme).to eq CodeObjects::ExtraFileObject.new('README.fr.md', '')
    end

    it "does not allow US-ASCII charset when using --one-file" do
      ienc = Encoding.default_internal
      eenc = Encoding.default_external
      expect(log).to receive(:warn).with(/not compatible with US-ASCII.*using ASCII-8BIT/)
      @yardoc.parse_arguments(*%w(--one-file --charset us-ascii))
      expect(Encoding.default_internal.name).to eq 'ASCII-8BIT'
      expect(Encoding.default_external.name).to eq 'ASCII-8BIT'
      Encoding.default_internal = ienc
      Encoding.default_external = eenc
    end if defined?(::Encoding)
  end

  describe "Source file arguments" do
    it "accepts no params and parse {lib,app}/**/*.rb ext/**/*.c" do
      @yardoc.parse_arguments
      expect(@yardoc.files).to eq Parser::SourceParser::DEFAULT_PATH_GLOB
    end
  end

  describe "Tags options" do
    def tag_created(switch, factory_method)
      visible_tags = double(:visible_tags)
      expect(visible_tags).to receive(:|).ordered.with([:foo])
      expect(visible_tags).to receive(:-).ordered.with([]).and_return(visible_tags)
      expect(Tags::Library).to receive(:define_tag).with('Foo', :foo, factory_method)
      allow(Tags::Library).to receive(:visible_tags=)
      expect(Tags::Library).to receive(:visible_tags).at_least(1).times.and_return(visible_tags)
      @yardoc.parse_arguments("--#{switch}-tag", 'foo')
    end

    def tag_hidden(tag)
      visible_tags = double(:visible_tags)
      expect(visible_tags).to receive(:|).ordered.with([tag])
      expect(visible_tags).to receive(:-).ordered.with([tag]).and_return([])
      expect(Tags::Library).to receive(:define_tag).with(tag.to_s.capitalize, tag, nil)
      allow(Tags::Library).to receive(:visible_tags=)
      expect(Tags::Library).to receive(:visible_tags).at_least(1).times.and_return(visible_tags)
    end

    it "accepts --tag" do
      expect(Tags::Library).to receive(:define_tag).with('Title of Foo', :foo, nil)
      @yardoc.parse_arguments('--tag', 'foo:Title of Foo')
    end

    it "accepts --tag without title (and default to capitalized tag name)" do
      expect(Tags::Library).to receive(:define_tag).with('Foo', :foo, nil)
      @yardoc.parse_arguments('--tag', 'foo')
    end

    it "only lists tag once if declared twice" do
      visible_tags = []
      allow(Tags::Library).to receive(:define_tag)
      allow(Tags::Library).to receive(:visible_tags).and_return([:foo])
      allow(Tags::Library).to receive(:visible_tags=) {|value| visible_tags = value }
      @yardoc.parse_arguments('--tag', 'foo', '--tag', 'foo')
      expect(visible_tags).to eq [:foo]
    end

    it "accepts --type-tag" do
      tag_created 'type', :with_types
    end

    it "accepts --type-name-tag" do
      tag_created 'type-name', :with_types_and_name
    end

    it "accepts --name-tag" do
      tag_created 'name', :with_name
    end

    it "accepts --title-tag" do
      tag_created 'title', :with_title_and_text
    end

    it "accepts --hide-tag before tag is listed" do
      tag_hidden(:anewfoo)
      @yardoc.parse_arguments('--hide-tag', 'anewfoo', '--tag', 'anewfoo')
    end

    it "accepts --hide-tag after tag is listed" do
      tag_hidden(:anewfoo2)
      @yardoc.parse_arguments('--tag', 'anewfoo2', '--hide-tag', 'anewfoo2')
    end

    it "accepts --transitive-tag" do
      @yardoc.parse_arguments('--transitive-tag', 'foo')
      expect(Tags::Library.transitive_tags).to include(:foo)
    end

    it "accepts --non-transitive-tag" do
      Tags::Library.transitive_tags |= [:foo]
      @yardoc.parse_arguments('--non-transitive-tag', 'foo')
      expect(Tags::Library.transitive_tags).not_to include(:foo)
    end
  end

  describe "Safe mode" do
    before do
      allow(YARD::Config).to receive(:options).and_return(:safe_mode => true)
    end

    it "does not allow --load or -e in safe mode" do
      expect(@yardoc).not_to receive(:require)
      @yardoc.run('--load', 'foo')
      @yardoc.run('-e', 'foo')
    end

    it "does not allow --query in safe mode" do
      @yardoc.run('--query', 'foo')
      expect(@yardoc.options.verifier.expressions).not_to include("foo")
    end

    it "does not allow modifying the template paths" do
      expect(YARD::Templates::Engine).not_to receive(:register_template_path)
      @yardoc.run('-p', 'foo')
      @yardoc.run('--template-path', 'foo')
    end
  end

  describe "Markup Loading" do
    it "loads rdoc markup if no markup is provided" do
      @yardoc.generate = true
      @yardoc.run
      expect(@yardoc.options.markup).to eq :rdoc
    end

    it "loads rdoc markup even when no output is specified" do
      @yardoc.parse_arguments('--no-output')
      expect(@yardoc.options.markup).to eq :rdoc
    end

    it "warns if rdoc cannot be loaded and fallback to :none" do
      mod = YARD::Templates::Helpers::MarkupHelper
      mod.clear_markup_cache
      expect(mod.const_get(:MARKUP_PROVIDERS)).to receive(:[]).with(:rdoc).and_return([{:lib => 'INVALID'}])
      expect(log).to receive(:warn).with(/Could not load default RDoc formatter/)
      allow(@yardoc).to receive(:generate) { @yardoc.options.files = []; true }
      @yardoc.run
      expect(@yardoc.options.markup).to eq :none
      mod.clear_markup_cache
    end

    it "returns an error immediately if markup for any files are missing" do
      mod = YARD::Templates::Helpers::MarkupHelper
      mod.clear_markup_cache
      expect(mod.const_get(:MARKUP_PROVIDERS)).to receive(:[]).with(:markdown).and_return([{:lib => 'INVALID'}])
      expect(log).to receive(:error).with(/Missing 'INVALID' gem for Markdown formatting/)
      files = [CodeObjects::ExtraFileObject.new('test.md', '')]
      allow(@yardoc).to receive(:generate) { @yardoc.options.files = files; true }
      @yardoc.run
      mod.clear_markup_cache
    end

    it "returns an error immediately if markup for any files are missing (file markup specified in attributes)" do
      mod = YARD::Templates::Helpers::MarkupHelper
      mod.clear_markup_cache
      expect(mod.const_get(:MARKUP_PROVIDERS)).to receive(:[]).with(:markdown).and_return([{:lib => 'INVALID'}])
      expect(log).to receive(:error).with(/Missing 'INVALID' gem for Markdown formatting/)
      files = [CodeObjects::ExtraFileObject.new('test', '# @markup markdown')]
      allow(@yardoc).to receive(:generate) { @yardoc.options.files = files; true }
      @yardoc.run
      mod.clear_markup_cache
    end
  end

  describe "#run" do
    it "parses arguments if run() is called" do
      expect(@yardoc).to receive(:parse_arguments)
      @yardoc.run
    end

    it "parses arguments if run(arg1, arg2, ...) is called" do
      expect(@yardoc).to receive(:parse_arguments)
      @yardoc.run('--private', '-p', 'foo')
    end

    it "does not parse arguments if run(nil) is called" do
      expect(@yardoc).not_to receive(:parse_arguments)
      @yardoc.run(nil)
    end

    it "creates processing lock if saving" do
      expect(Registry).to receive(:lock_for_writing).and_yield
      @yardoc.run
    end

    it "does not create processing lock if not saving" do
      expect(Registry).not_to receive(:lock_for_writing)
      @yardoc.run('--no-save')
    end

    context "with --fail-on-warning" do
      it "exits with error status code if a warning occurs" do
        allow(log).to receive(:warned).and_return(true)
        expect { @yardoc.run("--fail-on-warning") }.to raise_error(SystemExit) do |error|
          expect(error).not_to be_success
        end
      end

      it "does not exit if a warning does not occur" do
        allow(log).to receive(:warned).and_return(false)
        expect { @yardoc.run("--fail-on-warning") }.not_to raise_error
      end
    end
  end
end
yard-0.9.37/spec/cli/yri_spec.rb000066400000000000000000000074341466601756300164420ustar00rootroot00000000000000# frozen_string_literal: true

class TestYRI < YARD::CLI::YRI
  public :optparse, :find_object, :cache_object
  def test_stub; end
  def print_object(*args) test_stub; super end
end

RSpec.describe YARD::CLI::YRI do
  before do
    @yri = TestYRI.new
    allow(Registry).to receive(:load)
  end

  describe "#find_object" do
    it "uses cache if available" do
      allow(@yri).to receive(:cache_object)
      expect(File).to receive(:exist?).with('.yardoc').and_return(false)
      expect(File).to receive(:exist?).with('bar.yardoc').and_return(true)
      expect(Registry).to receive(:load).with('bar.yardoc')
      expect(Registry).to receive(:at).ordered.with('Foo').and_return(nil)
      expect(Registry).to receive(:at).ordered.with('Foo').and_return('OBJ')
      @yri.instance_variable_set("@cache", 'Foo' => 'bar.yardoc')
      expect(@yri.find_object('Foo')).to eq 'OBJ'
    end

    it "never uses cache ahead of current directory's .yardoc" do
      allow(@yri).to receive(:cache_object)
      expect(File).to receive(:exist?).with('.yardoc').and_return(true)
      expect(Registry).to receive(:load).with('.yardoc')
      expect(Registry).to receive(:at).ordered.with('Foo').and_return(nil)
      expect(Registry).to receive(:at).ordered.with('Foo').and_return('OBJ')
      @yri.instance_variable_set("@cache", 'Foo' => 'bar.yardoc')
      expect(@yri.find_object('Foo')).to eq 'OBJ'
      expect(@yri.instance_variable_get("@search_paths")[0]).to eq '.yardoc'
    end
  end

  describe "#cache_object" do
    it "skips caching for Registry.yardoc_file" do
      expect(File).not_to receive(:open).with(CLI::YRI::CACHE_FILE, 'w')
      @yri.cache_object('Foo', Registry.yardoc_file)
    end
  end

  describe "#initialize" do
    it "loads search paths" do
      path = %r{/\.yard/yri_search_paths$}
      allow(File).to receive(:file?).and_call_original
      allow(File).to receive(:file?).with(%r{/\.yard/yri_cache$}).and_return(false)
      allow(File).to receive(:file?).with(path).and_return(true)
      allow(File).to receive(:readlines).with(path).and_return(%w(line1 line2))
      @yri = YARD::CLI::YRI.new
      spaths = @yri.instance_variable_get("@search_paths")
      expect(spaths).to include('line1')
      expect(spaths).to include('line2')
    end

    it "uses DEFAULT_SEARCH_PATHS prior to other paths" do
      YARD::CLI::YRI::DEFAULT_SEARCH_PATHS.push('foo', 'bar')
      path = %r{/\.yard/yri_search_paths$}
      allow(File).to receive(:file?).and_call_original
      allow(File).to receive(:file?).with(%r{/\.yard/yri_cache$}).and_return(false)
      allow(File).to receive(:file?).with(path).and_return(true)
      allow(File).to receive(:readlines).with(path).and_return(%w(line1 line2))
      @yri = YARD::CLI::YRI.new
      spaths = @yri.instance_variable_get("@search_paths")
      expect(spaths[0, 4]).to eq %w(foo bar line1 line2)
      YARD::CLI::YRI::DEFAULT_SEARCH_PATHS.replace([])
    end
  end

  describe "#run" do
    it "searches for objects and print their documentation" do
      obj = YARD::CodeObjects::ClassObject.new(:root, 'Foo')
      expect(@yri).to receive(:print_object).with(obj)
      @yri.run('Foo')
      Registry.clear
    end

    it "prints usage if no object is provided" do
      expect(@yri).to receive(:print_usage)
      expect(@yri).to receive(:exit).with(1)
      @yri.run('')
    end

    it "prints 'no documentation exists for object' if object is not found" do
      expect(STDERR).to receive(:puts).with("No documentation for `Foo'")
      expect(@yri).to receive(:exit).with(1)
      @yri.run('Foo')
    end

    it "ensures output is serialized" do
      YARD::CodeObjects::ClassObject.new(:root, 'Foo')
      allow(@yri).to receive(:test_stub) do
        expect(@yri.instance_variable_get(:@serializer)).to receive(:serialize).once
      end
      @yri.run('Foo')
    end
  end
end
yard-0.9.37/spec/code_objects/000077500000000000000000000000001466601756300161445ustar00rootroot00000000000000yard-0.9.37/spec/code_objects/base_spec.rb000066400000000000000000000407061466601756300204240ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::Base do
  before { Registry.clear }

  it "does not allow empty object name" do
    expect { Base.new(:root, '') }.to raise_error(ArgumentError)
  end

  it "returns a unique instance of any registered object" do
    obj = ClassObject.new(:root, :Me)
    obj2 = ClassObject.new(:root, :Me)
    expect(obj.object_id).to eq obj2.object_id

    obj3 = ModuleObject.new(obj, :Too)
    obj4 = CodeObjects::Base.new(obj3, :Hello)
    obj4.parent = obj

    obj5 = CodeObjects::Base.new(obj3, :hello)
    expect(obj4.object_id).not_to eq obj5.object_id
  end

  it "creates a new object if cached object is not of the same class" do
    expect(ConstantObject.new(:root, "MYMODULE")).to be_instance_of(ConstantObject)
    expect(ModuleObject.new(:root, "MYMODULE")).to be_instance_of(ModuleObject)
    expect(ClassObject.new(:root, "MYMODULE")).to be_instance_of(ClassObject)
    expect(YARD::Registry.at("MYMODULE")).to be_instance_of(ClassObject)
  end

  it "simplifies complex namespace paths" do
    obj = ClassObject.new(:root, "A::B::C::D")
    expect(obj.name).to eq :D
    expect(obj.path).to eq "A::B::C::D"
    expect(obj.namespace).to eq P("A::B::C")
  end

  # @bug gh-552
  it "simplifies complex namespace paths when path starts with ::" do
    obj = ClassObject.new(:root, "::A::B::C::D")
    expect(obj.name).to eq :D
    expect(obj.path).to eq "A::B::C::D"
    expect(obj.namespace).to eq P("A::B::C")
  end

  it "calls the block again if #new is called on an existing object" do
    o1 = ClassObject.new(:root, :Me) do |o|
      o.docstring = "DOCSTRING"
    end

    o2 = ClassObject.new(:root, :Me) do |o|
      o.docstring = "NOT_DOCSTRING"
    end

    expect(o1.object_id).to eq o2.object_id
    expect(o1.docstring).to eq "NOT_DOCSTRING"
    expect(o2.docstring).to eq "NOT_DOCSTRING"
  end

  it "allows complex name and converts it to namespace" do
    obj = CodeObjects::Base.new(nil, "A::B")
    expect(obj.namespace.path).to eq "A"
    expect(obj.name).to eq :B
  end

  it "allows namespace to be nil and not register in the Registry" do
    obj = CodeObjects::Base.new(nil, :Me)
    expect(obj.namespace).to eq nil
    expect(Registry.at(:Me)).to eq nil
  end

  it "allows namespace to be a NamespaceObject" do
    ns = ModuleObject.new(:root, :Name)
    obj = CodeObjects::Base.new(ns, :Me)
    expect(obj.namespace).to eq ns
  end

  it "allows :root to be the shorthand namespace of `Registry.root`" do
    obj = CodeObjects::Base.new(:root, :Me)
    expect(obj.namespace).to eq Registry.root
  end

  it "does not allow any other types as namespace" do
    expect { CodeObjects::Base.new("ROOT!", :Me) }.to raise_error(ArgumentError)
  end

  it "allows constants to be used as a namespace" do
    a = ConstantObject.new(:root, :A)
    a.value = "B::C"
    b = ClassObject.new(:root, :B)
    c = ClassObject.new(b, :C)
    klass = ClassObject.new(a, "MyClass")
    expect(klass.path).to eq "B::C::MyClass"
  end

  it "does not allow constants to be used as a namespace if they do not resolve to a valid namespace" do
    a = ConstantObject.new(:root, :A)
    a.value = "$$INVALID$$"
    expect { ClassObject.new(a, "MyClass") }.to raise_error(Parser::UndocumentableError)
  end

  it "registers itself in the registry if namespace is supplied" do
    obj = ModuleObject.new(:root, :Me)
    expect(Registry.at(:Me)).to eq obj

    obj2 = ModuleObject.new(obj, :Too)
    expect(Registry.at(:"Me::Too")).to eq obj2
  end

  describe "#[]=" do
    it "sets any attribute" do
      obj = ModuleObject.new(:root, :YARD)
      obj[:some_attr] = "hello"
      expect(obj[:some_attr]).to eq "hello"
    end

    it "uses the accessor method if available" do
      obj = CodeObjects::Base.new(:root, :YARD)
      obj[:source] = "hello"
      expect(obj.source).to eq "hello"
      obj.source = "unhello"
      expect(obj[:source]).to eq "unhello"
    end
  end

  it "sets attributes via attr= through method_missing" do
    obj = CodeObjects::Base.new(:root, :YARD)
    obj.something = 2
    expect(obj.something).to eq 2
    expect(obj[:something]).to eq 2
  end

  it "exists in the parent's #children after creation" do
    obj = ModuleObject.new(:root, :YARD)
    obj2 = MethodObject.new(obj, :testing)
    expect(obj.children).to include(obj2)
  end

  # @bug gh-1209
  it "removes prior defined objects at the same path from namespace's children" do
    Registry.clear
    obj = ModuleObject.new(:root, :YARD)
    ConstantObject.new(obj, :Testing)
    ClassObject.new(obj, :Testing)
    expect(obj.children.map {|o| o.type.to_sym }).to eq [:class]
    expect(Registry.at('YARD::Testing').type).to eq :class
  end

  it "properly re-indents source starting from 0 indentation" do
    obj = CodeObjects::Base.new(nil, :test)
    obj.source = <<-eof
      def mymethod
        if x == 2 &&
            5 == 5
          3
        else
          1
        end
      end
    eof
    expect(obj.source).to eq "def mymethod\n  if x == 2 &&\n      5 == 5\n    3\n  else\n    1\n  end\nend"

    Registry.clear
    Parser::SourceParser.parse_string <<-eof
      def key?(key)
        super(key)
      end
    eof
    expect(Registry.at('#key?').source).to eq "def key?(key)\n  super(key)\nend"

    Registry.clear
    Parser::SourceParser.parse_string <<-eof
        def key?(key)
          if x == 2
            puts key
          else
            exit
          end
        end
    eof
    expect(Registry.at('#key?').source).to eq "def key?(key)\n  if x == 2\n    puts key\n  else\n    exit\n  end\nend"
  end

  it "does not add newlines to source when parsing sub blocks" do
    Parser::SourceParser.parse_string <<-eof
      module XYZ
        module ZYX
          class ABC
            def msg
              hello_world
            end
          end
        end
      end
    eof
    expect(Registry.at('XYZ::ZYX::ABC#msg').source).to eq "def msg\n  hello_world\nend"
  end

  it "handles source for 'def x; end'" do
    Registry.clear
    Parser::SourceParser.parse_string "def x; 2 end"
    expect(Registry.at('#x').source).to eq "def x; 2 end"
  end

  it "sets file and line information" do
    Parser::SourceParser.parse_string <<-eof
      class X; end
    eof
    expect(Registry.at(:X).file).to eq '(stdin)'
    expect(Registry.at(:X).line).to eq 1
  end

  it "maintains all file associations when objects are defined multiple times in one file" do
    Parser::SourceParser.parse_string <<-eof
      class X; end
      class X; end
      class X; end
    eof

    expect(Registry.at(:X).file).to eq '(stdin)'
    expect(Registry.at(:X).line).to eq 1
    expect(Registry.at(:X).files).to eq [['(stdin)', 1], ['(stdin)', 2], ['(stdin)', 3]]
  end

  it "maintains all file associations when objects are defined multiple times in multiple files" do
    3.times do |i|
      allow(File).to receive(:read_binary).and_return("class X; end")
      Parser::SourceParser.new.parse("file#{i + 1}.rb")
    end

    expect(Registry.at(:X).file).to eq 'file1.rb'
    expect(Registry.at(:X).line).to eq 1
    expect(Registry.at(:X).files).to eq [['file1.rb', 1], ['file2.rb', 1], ['file3.rb', 1]]
  end

  it "prioritizes the definition with a docstring when returning #file" do
    Parser::SourceParser.parse_string <<-eof
      class X; end
      class X; end
      # docstring
      class X; end
    eof

    expect(Registry.at(:X).file).to eq '(stdin)'
    expect(Registry.at(:X).line).to eq 4
    expect(Registry.at(:X).files).to eq [['(stdin)', 4], ['(stdin)', 1], ['(stdin)', 2]]
  end

  describe "#format" do
    it "sends object to Templates.render" do
      object = MethodObject.new(:root, :method)
      expect(Templates::Engine).to receive(:render).with({:x => 1, :object => object, :type => object.type})
      object.format :x => 1
    end

    it "does not change options object class" do
      opts = YARD::Templates::TemplateOptions.new
      opts.type = "test"
      object = MethodObject.new(:root, :method)
      expect(Templates::Engine).to receive(:render).with kind_of(YARD::Templates::TemplateOptions)
      object.format(opts)
    end
  end

  describe "#source_type" do
    it "defaults to :ruby" do
      object = MethodObject.new(:root, :method)
      expect(object.source_type).to eq :ruby
    end
  end

  describe "#relative_path" do
    it "accepts a string" do
      YARD.parse_string "module A; class B; end; class C; end; end"
      expect(Registry.at('A::B').relative_path(Registry.at('A::C'))).to eq(
        Registry.at('A::B').relative_path('A::C')
      )
    end

    it "returns full class name when objects share a common class prefix" do
      YARD.parse_string "module User; end; module UserManager; end"
      expect(Registry.at('User').relative_path('UserManager')).to eq 'UserManager'
      expect(Registry.at('User').relative_path(Registry.at('UserManager'))).to eq 'UserManager'
    end

    it "returns the relative path when they share a common namespace" do
      YARD.parse_string "module A; class B; end; class C; end; end"
      expect(Registry.at('A::B').relative_path(Registry.at('A::C'))).to eq 'C'
      YARD.parse_string "module Foo; module A; end; module B; def foo; end end end"
      expect(Registry.at('Foo::A').relative_path(Registry.at('Foo::B#foo'))).to eq 'B#foo'
    end

    it "returns the full path if they don't have a common namespace" do
      YARD.parse_string "module A; class B; end; end; module D; class C; end; end"
      expect(Registry.at('A::B').relative_path('D::C')).to eq 'D::C'
      YARD.parse_string 'module C::B::C; module Apple; end; module Ant; end end'
      expect(Registry.at('C::B::C::Apple').relative_path('C::B::C::Ant')).to eq 'Ant'
      YARD.parse_string 'module OMG::ABC; end; class Object; end'
      expect(Registry.at('OMG::ABC').relative_path('Object')).to eq "Object"
      YARD.parse_string("class YARD::Config; MYCONST = 1; end")
      expect(Registry.at('YARD::Config').relative_path('YARD::Config::MYCONST')).to eq "MYCONST"
    end

    it "returns a relative path for class methods" do
      YARD.parse_string "module A; def self.b; end; def self.c; end; end"
      expect(Registry.at('A.b').relative_path('A.c')).to eq 'c'
      expect(Registry.at('A').relative_path('A.c')).to eq 'c'
    end

    it "returns a relative path for instance methods" do
      YARD.parse_string "module A; def b; end; def c; end; end"
      expect(Registry.at('A#b').relative_path('A#c')).to eq '#c'
      expect(Registry.at('A').relative_path('A#c')).to eq '#c'
    end

    it "returns full path if relative path is to parent namespace" do
      YARD.parse_string "module A; module B; end end"
      expect(Registry.at('A::B').relative_path('A')).to eq 'A'
    end

    it "only returns name for relative path to self" do
      YARD.parse_string("class A::B::C; def foo; end end")
      expect(Registry.at('A::B::C').relative_path('A::B::C')).to eq 'C'
      expect(Registry.at('A::B::C#foo').relative_path('A::B::C#foo')).to eq '#foo'
    end
  end

  describe "#docstring=" do
    it "converts string into Docstring when #docstring= is set" do
      o = ClassObject.new(:root, :Me)
      o.docstring = "DOCSTRING"
      expect(o.docstring).to be_instance_of(Docstring)
    end

    it "sets docstring to docstring of other object if docstring is '(see Path)'" do
      ClassObject.new(:root, :AnotherObject) {|x| x.docstring = "FOO" }
      o = ClassObject.new(:root, :Me)
      o.docstring = '(see AnotherObject)'
      expect(o.docstring).to eq "FOO"
    end

    it "does not copy docstring mid-docstring" do
      doc = "Hello.\n(see file.rb)\nmore documentation"
      o = ClassObject.new(:root, :Me)
      o.docstring = doc
      expect(o.docstring).to eq doc
    end

    it "allows extra docstring after (see Path)" do
      ClassObject.new(:root, :AnotherObject) {|x| x.docstring = "FOO" }
      o = ClassObject.new(:root, :Me)
      o.docstring = Docstring.new("(see AnotherObject)\n\nEXTRA\n@api private", o)
      expect(o.docstring).to eq "FOO\n\nEXTRA"
      expect(o.docstring).to have_tag(:api)
    end
  end

  describe "#docstring" do
    it "returns an empty string if docstring was '(see Path)' and Path is not resolved" do
      o = ClassObject.new(:root, :Me)
      o.docstring = '(see AnotherObject)'
      expect(o.docstring).to eq ""
    end

    it "returns docstring when object is resolved" do
      o = ClassObject.new(:root, :Me)
      o.docstring = '(see AnotherObject)'
      expect(o.docstring).to eq ""
      ClassObject.new(:root, :AnotherObject) {|x| x.docstring = "FOO" }
      expect(o.docstring).to eq "FOO"
    end

    describe "localization" do
      it "returns localized docstring" do
        fr_locale = YARD::I18n::Locale.new('fr')
        allow(fr_locale).to receive(:translate).with('Hello').and_return('Bonjour')

        o = ClassObject.new(:root, :Me)
        o.docstring = 'Hello'
        expect(o.docstring).to eq 'Hello'

        allow(Registry).to receive(:locale).with('fr').and_return(fr_locale)
        expect(o.docstring('fr')).to eq "Bonjour"
      end

      it "returns localized docstring tag" do
        o = CodeObjects::MethodObject.new(:root, 'Hello#message')
        o.docstring.add_tag(Tags::Tag.new('return', 'Hello'))

        fr_locale = YARD::I18n::Locale.new('fr')
        allow(fr_locale).to receive(:translate).with('Hello').and_return('Bonjour')
        allow(Registry).to receive(:locale).with('fr').and_return(fr_locale)

        expect(o.docstring('fr').tags.map(&:text)).to eq ['Bonjour']
      end

      it "returns updated localized docstring" do
        fr_locale = YARD::I18n::Locale.new('fr')
        allow(Registry).to receive(:locale).with('fr').and_return(fr_locale)

        o = ClassObject.new(:root, :Me)
        o.docstring = 'Hello'
        expect(o.docstring).to eq 'Hello'

        allow(fr_locale).to receive(:translate).with('Hello').and_return('Bonjour')
        expect(o.docstring('fr')).to eq "Bonjour"

        o.docstring = 'World'
        allow(fr_locale).to receive(:translate).with('World').and_return('Monde')
        expect(o.docstring('fr')).to eq "Monde"
        expect(o.docstring).to eq 'World'
      end
    end
  end

  describe "#add_file" do
    it "only adds a file/line combination once" do
      o = ClassObject.new(:root, :Me)
      o.add_file('filename', 12)
      expect(o.files).to eq [['filename', 12]]
      o.add_file('filename', 12)
      expect(o.files).to eq [['filename', 12]]
      o.add_file('filename', 40) # different line
      expect(o.files).to eq [['filename', 12], ['filename', 40]]
    end
  end

  describe "#copy_to" do
    it "copies all data to new object" do
      YARD.parse_string <<-eof
        private
        # A docstring
        # @return [String] a tag
        def foo(a, b, c)
          source_code_here
        end
      eof
      foo_c = MethodObject.new(:root, :foo, :class)
      Registry.at('#foo').copy_to(foo_c)
      expect(foo_c.scope).to eq :class
      expect(foo_c.visibility).to eq :private
      expect(foo_c.type).to eq :method
      expect(foo_c.class).to eq MethodObject
      expect(foo_c.path).to eq '::foo'
      expect(foo_c.docstring).to eq "A docstring"
      expect(foo_c.tag(:return).types).to eq ['String']
      expect(foo_c.file).to eq '(stdin)'
      expect(foo_c.line).to eq 4
      expect(foo_c.source).to match(/source_code_here/)
      expect(foo_c.signature).to eq 'def foo(a, b, c)'
      expect(foo_c.parameters).to eq [['a', nil], ['b', nil], ['c', nil]]
    end

    it "returns the copied object" do
      YARD.parse_string 'def foo; end'
      foo_c = MethodObject.new(:root, :foo, :class)
      expect(Registry.at('#foo').copy_to(foo_c)).to eq foo_c
    end

    it "copies docstring and rewrite tags to new object" do
      YARD.parse_string <<-eof
        # @return [String] a tag
        def foo; end
      eof
      foo_c = MethodObject.new(:root, :foo, :class)
      foo_i = Registry.at('#foo')
      foo_i.copy_to(foo_c)
      expect(foo_i.tags).not_to eq foo_c.tags
      expect(foo_c.tags.first.object).to eq foo_c
    end

    it "only copies #copyable_attributes" do
      foo = MethodObject.new(:root, :foo)
      expect(foo).to receive(:copyable_attributes).and_return %w(a b c)
      expect(foo).to receive(:instance_variable_get).with('@a').and_return(1)
      expect(foo).to receive(:instance_variable_get).with('@b').and_return(2)
      expect(foo).to receive(:instance_variable_get).with('@c').and_return(3)
      bar = MethodObject.new(:root, :bar)
      expect(bar).to receive(:instance_variable_set).with('@a', 1)
      expect(bar).to receive(:instance_variable_set).with('@b', 2)
      expect(bar).to receive(:instance_variable_set).with('@c', 3)
      foo.copy_to(bar)
    end
  end
end
yard-0.9.37/spec/code_objects/class_object_spec.rb000066400000000000000000000154321466601756300221430ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::ClassObject do
  describe "#inheritance_tree" do
    before(:all) do
      Registry.clear
      @mixin = ModuleObject.new(:root, :SomeMixin)
      @mixin2 = ModuleObject.new(:root, :SomeMixin2)
      @mixin2.instance_mixins << @mixin
      @mixin3 = ModuleObject.new(:root, :SomeMixin3)
      @mixin4 = ModuleObject.new(:root, :SomeMixin4)
      @mixin2.instance_mixins << @mixin3
      @superyard = ClassObject.new(:root, :SuperYard)
      @superyard.superclass = P("String")
      @superyard.instance_mixins << @mixin2
      @superyard.class_mixins << @mixin4
      @yard = ClassObject.new(:root, :YARD)
      @yard.superclass = @superyard
      @yard.instance_mixins << @mixin
    end

    it "shows the proper inheritance tree" do
      expect(@yard.inheritance_tree).to eq [@yard, @superyard, P(:String)]
    end

    it "shows proper inheritance tree when mixins are included" do
      expect(@yard.inheritance_tree(true)).to eq [@yard, @mixin, @superyard, @mixin4, @mixin2, @mixin3, P(:String)]
    end

    it "does not modify the object's mixin list when mixins are included" do
      @class1 = ClassObject.new(:root, :A)
      @class2 = ClassObject.new(:root, :B)
      @class2.superclass = @class1

      @class2.inheritance_tree(true)
      expect(@class2.mixins).to eq []
    end

    it "lists class mixins in inheritance tree" do
      mod = ModuleObject.new(:root, :ClassMethods)
      klass = ClassObject.new(:root, :ReceivingClass)
      klass.class_mixins << mod
      expect(klass.inheritance_tree(true)).to eq [klass, mod]
    end
  end

  describe "#meths / #inherited_meths" do
    before(:all) do
      Registry.clear

      YARD.parse_string <<-eof
        class SuperYard < String
          def foo; end
          def foo2; end
          def bar; end
          def middle; end
          protected :foo2
          private
          def self.bar; end
        end

        class MiddleYard < SuperYard
          def middle; end
        end

        class YARD < MiddleYard
          def mymethod; end
          def bar; end
        end

        module IncludedYard
          def foo; end
        end

        class FinalYard < SuperYard
          include IncludedYard
        end
      eof
    end

    it "shows inherited methods by default" do
      meths = P(:YARD).meths
      expect(meths).to include(P("YARD#mymethod"))
      expect(meths).to include(P("SuperYard#foo"))
      expect(meths).to include(P("SuperYard#foo2"))
      expect(meths).to include(P("SuperYard.bar"))
    end

    it "allows :inherited to be set to false" do
      meths = P(:YARD).meths(:inherited => false)
      expect(meths).to include(P("YARD#mymethod"))
      expect(meths).not_to include(P("SuperYard#foo"))
      expect(meths).not_to include(P("SuperYard#foo2"))
      expect(meths).not_to include(P("SuperYard.bar"))
    end

    it "does not show overridden methods" do
      meths = P(:YARD).meths
      expect(meths).to include(P("YARD#bar"))
      expect(meths).not_to include(P("SuperYard#bar"))

      meths = P(:YARD).inherited_meths
      expect(meths).not_to include(P("YARD#bar"))
      expect(meths).not_to include(P("YARD#mymethod"))
      expect(meths).to include(P("SuperYard#foo"))
      expect(meths).to include(P("SuperYard#foo2"))
      expect(meths).to include(P("SuperYard.bar"))
    end

    it "does not show inherited methods overridden by other subclasses" do
      meths = P(:YARD).inherited_meths
      expect(meths).to include(P('MiddleYard#middle'))
      expect(meths).not_to include(P('SuperYard#middle'))
    end

    it "shows mixed in methods before superclass method" do
      meths = P(:FinalYard).meths
      expect(meths).to include(P('IncludedYard#foo'))
      expect(meths).not_to include(P('SuperYard#foo'))
    end
  end

  describe "#constants / #inherited_constants" do
    before(:all) do
      Registry.clear

      Parser::SourceParser.parse_string <<-eof
        class YARD
          CONST1 = 1
          CONST2 = "hello"
          CONST4 = 0
        end

        class SUPERYARD < YARD
          CONST4 = 5
        end

        class SubYard < SUPERYARD
          CONST2 = "hi"
          CONST3 = "foo"
        end
      eof
    end

    it "lists inherited constants by default" do
      consts = P(:SubYard).constants
      expect(consts).to include(P("YARD::CONST1"))
      expect(consts).to include(P("SubYard::CONST3"))

      consts = P(:SubYard).inherited_constants
      expect(consts).to include(P("YARD::CONST1"))
      expect(consts).not_to include(P("YARD::CONST2"))
      expect(consts).not_to include(P("SubYard::CONST2"))
      expect(consts).not_to include(P("SubYard::CONST3"))
    end

    it "does not list inherited constants if turned off" do
      consts = P(:SubYard).constants(:inherited => false)
      expect(consts).not_to include(P("YARD::CONST1"))
      expect(consts).to include(P("SubYard::CONST3"))
    end

    it "does not include an inherited constant if it is overridden by the object" do
      consts = P(:SubYard).constants
      expect(consts).to include(P("SubYard::CONST2"))
      expect(consts).not_to include(P("YARD::CONST2"))
    end

    it "does not include an inherited constant if it is overridden by another subclass" do
      consts = P(:SubYard).inherited_constants
      expect(consts).to include(P("SUPERYARD::CONST4"))
      expect(consts).not_to include(P("YARD::CONST4"))
    end

    it "does not set a superclass on BasicObject class" do
      o = ClassObject.new(:root, :BasicObject)
      expect(o.superclass).to be nil
    end

    it "sets superclass of Object to BasicObject" do
      o = ClassObject.new(:root, :Object)
      expect(o.superclass).to eq P(:BasicObject)
    end

    it "raises ArgumentError if superclass == self" do
      expect do
        ClassObject.new(:root, :Object) do |o|
          o.superclass = :Object
        end
      end.to raise_error(ArgumentError)
    end

    it "tells the world if it is an exception class" do
      o = ClassObject.new(:root, :MyClass)
      o2 = ClassObject.new(:root, :OtherClass)
      o2.superclass = :SystemCallError
      o3 = ClassObject.new(:root, :StandardError)
      o3.superclass = :Object
      ClassObject.new(:root, :Object)

      o.superclass = :Object
      expect(o.is_exception?).to be false

      o.superclass = :Exception
      expect(o.is_exception?).to be true

      o.superclass = :NoMethodError
      expect(o.is_exception?).to be true

      o.superclass = o2
      expect(o.is_exception?).to be true

      o.superclass = o3
      expect(o.is_exception?).to be true
    end

    it "does not raise ArgumentError if superclass is proxy in different namespace" do
      expect do
        ClassObject.new(:root, :X) do |o|
          o.superclass = P('OTHER::X')
        end
      end.not_to raise_error
    end
  end
end
yard-0.9.37/spec/code_objects/code_object_list_spec.rb000066400000000000000000000016301466601756300227760ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::CodeObjectList do
  before { Registry.clear }

  describe "#push" do
    it "only allows CodeObjects::Base, String or Symbol" do
      list = CodeObjectList.new(nil)
      expect { list.push(:hash => 1) }.to raise_error(ArgumentError)
      list << "Test"
      list << :Test2
      list << ModuleObject.new(nil, :YARD)
      expect(list.size).to eq 3
    end
  end

  it "added value should be a proxy if parameter was String or Symbol" do
    list = CodeObjectList.new(nil)
    list << "Test"
    expect(list.first.class).to eq Proxy
  end

  it "contains a unique list of objects" do
    obj = ModuleObject.new(nil, :YARD)
    list = CodeObjectList.new(nil)

    list << P(:YARD)
    list << obj
    expect(list.size).to eq 1

    list << :Test
    list << "Test"
    expect(list.size).to eq 2
  end
end
yard-0.9.37/spec/code_objects/constants_spec.rb000066400000000000000000000067501466601756300215270ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects do
  def silence_warnings
    origverb = $VERBOSE
    $VERBOSE = nil
    yield
    $VERBOSE = origverb
  end

  describe :CONSTANTMATCH do
    it "matches a constant" do
      expect("Constant"[CodeObjects::CONSTANTMATCH]).to eq "Constant"
      expect("identifier"[CodeObjects::CONSTANTMATCH]).to be nil
      expect("File.new"[CodeObjects::CONSTANTMATCH]).to eq "File"
    end
  end

  describe :CONSTANTSTART do
    it "matches a constant" do
      expect("Constant"[CodeObjects::CONSTANTSTART]).to eq "C"
      expect("identifier"[CodeObjects::CONSTANTSTART]).to be nil
      expect("File.new"[CodeObjects::CONSTANTSTART]).to eq "F"
    end
  end

  describe :NAMESPACEMATCH do
    it "matches a namespace (multiple constants with ::)" do
      expect("Constant"[CodeObjects::NAMESPACEMATCH]).to eq "Constant"
      expect("A::B::C.new"[CodeObjects::NAMESPACEMATCH]).to eq "A::B::C"
    end
  end

  describe :METHODNAMEMATCH do
    it "matches a method name" do
      expect("method"[CodeObjects::METHODNAMEMATCH]).to eq "method"
      expect("[]()"[CodeObjects::METHODNAMEMATCH]).to eq "[]"
      expect("-@"[CodeObjects::METHODNAMEMATCH]).to eq "-@"
      expect("method?"[CodeObjects::METHODNAMEMATCH]).to eq "method?"
      expect("method!!"[CodeObjects::METHODNAMEMATCH]).to eq "method!"
    end
  end

  describe :METHODMATCH do
    it "matches a full class method path" do
      expect("method"[CodeObjects::METHODMATCH]).to eq "method"
      expect("A::B::C.method?"[CodeObjects::METHODMATCH]).to eq "A::B::C.method?"
      expect("A::B::C :: method"[CodeObjects::METHODMATCH]).to eq "A::B::C :: method"
      expect("SomeClass . method"[CodeObjects::METHODMATCH]).to eq "SomeClass . method"
    end

    it "matches self.method" do
      expect("self :: method!"[CodeObjects::METHODMATCH]).to eq "self :: method!"
      expect("self.is_a?"[CodeObjects::METHODMATCH]).to eq "self.is_a?"
    end
  end

  describe :BUILTIN_EXCEPTIONS do
    it "includes all base exceptions" do
      bad_names = []
      silence_warnings do
        YARD::CodeObjects::BUILTIN_EXCEPTIONS.each do |name|
          begin
            bad_names << name unless eval(name) <= Exception
          rescue NameError
            nil # noop
          end
        end
      end
      expect(bad_names).to be_empty
    end
  end

  describe :BUILTIN_CLASSES do
    it "includes all base classes" do
      bad_names = []
      silence_warnings do
        YARD::CodeObjects::BUILTIN_CLASSES.each do |name|
          begin
            bad_names << name unless eval(name).is_a?(Class)
          rescue NameError
            nil # noop
          end
        end
      end
      expect(bad_names).to be_empty
    end

    it "includes all exceptions" do
      YARD::CodeObjects::BUILTIN_EXCEPTIONS.each do |name|
        expect(YARD::CodeObjects::BUILTIN_CLASSES).to include(name)
      end
    end
  end

  describe :BUILTIN_ALL do
    it "includes classes, modules, and exceptions" do
      a = YARD::CodeObjects::BUILTIN_ALL
      b = YARD::CodeObjects::BUILTIN_CLASSES
      c = YARD::CodeObjects::BUILTIN_MODULES
      expect(a).to eq b + c
    end
  end

  describe :BUILTIN_MODULES do
    it "includes all base modules" do
      silence_warnings do
        YARD::CodeObjects::BUILTIN_MODULES.each do |name|
          next if YARD.ruby19? && ["Precision"].include?(name)
          expect(eval(name)).to be_instance_of(Module)
        end
      end
    end
  end
end
yard-0.9.37/spec/code_objects/extra_file_object_spec.rb000066400000000000000000000131741466601756300231610ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::ExtraFileObject do
  describe "#initialize" do
    it "attempts to read contents from filesystem if contents=nil" do
      expect(File).to receive(:read).with('file.txt').and_return('')
      ExtraFileObject.new('file.txt')
    end

    it "raises Errno::ENOENT if contents=nil and file does not exist" do
      expect { ExtraFileObject.new('file.txt') }.to raise_error(Errno::ENOENT)
    end

    it "does not attempt to read from disk if contents are provided" do
      # TODO: no assertions here!
      ExtraFileObject.new('file.txt', 'CONTENTS')
    end

    it "sets filename to filename" do
      file = ExtraFileObject.new('a/b/c/file.txt', 'CONTENTS')
      expect(file.filename).to eq "a/b/c/file.txt"
    end

    it "parses out attributes at top of the file" do
      file = ExtraFileObject.new('file.txt', "# @title X\n# @some_attribute Y\nFOO BAR")
      expect(file.attributes[:title]).to eq "X"
      expect(file.attributes[:some_attribute]).to eq "Y"
      expect(file.contents).to eq "FOO BAR"
    end

    it "allows whitespace prior to '#' marker when parsing attributes" do
      file = ExtraFileObject.new('file.txt', " \t # @title X\nFOO BAR")
      expect(file.attributes[:title]).to eq "X"
      expect(file.contents).to eq "FOO BAR"
    end

    it "allows the attributes section to be wrapped in an HTML comment" do
      file = ExtraFileObject.new('file.txt', "\nFOO BAR")
      expect(file.attributes[:title]).to eq "X"
      expect(file.contents).to eq "FOO BAR"
    end

    it "allows whitespace around ignored HTML comment" do
      file = ExtraFileObject.new('file.txt', " \t  \nFOO BAR")
      expect(file.attributes[:title]).to eq "X"
      expect(file.contents).to eq "FOO BAR"
    end

    it "parses out old-style #!markup shebang format" do
      file = ExtraFileObject.new('file.txt', "#!foobar\nHello")
      expect(file.attributes[:markup]).to eq "foobar"
    end

    it "does not parse old-style #!markup if any whitespace is found" do
      file = ExtraFileObject.new('file.txt', " #!foobar\nHello")
      expect(file.attributes[:markup]).to be nil
      expect(file.contents).to eq " #!foobar\nHello"
    end

    it "does not parse out attributes if there are newlines prior to attributes" do
      file = ExtraFileObject.new('file.txt', "\n# @title\nFOO BAR")
      expect(file.attributes).to be_empty
      expect(file.contents).to eq "\n# @title\nFOO BAR"
    end

    it "sets contents to data after attributes" do
      file = ExtraFileObject.new('file.txt', "# @title\nFOO BAR")
      expect(file.contents).to eq "FOO BAR"
    end

    it "preserves newlines" do
      file = ExtraFileObject.new('file.txt', "FOO\r\nBAR\nBAZ")
      expect(file.contents).to eq "FOO\r\nBAR\nBAZ"
    end

    it "does not include newlines in attribute data" do
      file = ExtraFileObject.new('file.txt', "# @title FooBar\r\nHello world")
      expect(file.attributes[:title]).to eq "FooBar"
    end

    it "forces encoding to @encoding attribute if present" do
      expect(log).not_to receive(:warn)
      data = String.new("# @encoding sjis\nFOO")
      data.force_encoding('binary')
      file = ExtraFileObject.new('file.txt', data)
      expect(['Shift_JIS', 'Windows-31J']).to include(file.contents.encoding.to_s)
    end if YARD.ruby19?

    it "warns if @encoding is invalid" do
      expect(log).to receive(:warn).with("Invalid encoding `INVALID' in file.txt")
      data = String.new("# @encoding INVALID\nFOO")
      encoding = data.encoding
      file = ExtraFileObject.new('file.txt', data)
      expect(file.contents.encoding).to eq encoding
    end if YARD.ruby19?

    it "ignores encoding in 1.8.x (or encoding-unaware platforms)" do
      expect(log).not_to receive(:warn)
      ExtraFileObject.new('file.txt', "# @encoding INVALID\nFOO")
    end if YARD.ruby18?

    it "attempts to re-parse data as 8-bit ascii if parsing fails" do
      expect(log).not_to receive(:warn)
      str, out = *([String.new("\xB0")] * 2)
      if str.respond_to?(:force_encoding!)
        str.force_encoding!('utf-8')
        out.force_encoding!('binary')
      end
      expect(str.valid_encoding?).to be(false)
      file = ExtraFileObject.new('file.txt', str)
      expect(file.contents).to eq out
    end
  end

  describe "#name" do
    it "returns basename (not extension) of filename" do
      file = ExtraFileObject.new('file.txt', '')
      expect(file.name).to eq 'file'
    end
  end

  describe "#title" do
    it "returns @title attribute if present" do
      file = ExtraFileObject.new('file.txt', '# @title FOO')
      expect(file.title).to eq 'FOO'
    end

    it "returns #name if no @title attribute exists" do
      file = ExtraFileObject.new('file.txt', '')
      expect(file.title).to eq 'file'
    end
  end

  describe "#locale=" do
    it "translates contents" do
      file = ExtraFileObject.new('file.txt', 'Hello')
      file.locale = 'fr'
      fr_locale = I18n::Locale.new('fr')
      fr_messages = fr_locale.instance_variable_get(:@messages)
      fr_messages["Hello"] = 'Bonjour'
      expect(Registry).to receive(:locale).with('fr').and_return(fr_locale)
      expect(file.contents).to eq 'Bonjour'
    end
  end

  describe "#==" do
    it "defines equality based on filename alone" do
      file1 = ExtraFileObject.new('file.txt', 'A')
      file2 = ExtraFileObject.new('file.txt', 'B')
      expect(file1).to eq file2
      expect(file1).to eql file2
      expect(file1).to equal file2

      # Another way to test the equality interface
      a = [file1]
      a |= [file2]
      expect(a.size).to eq 1
    end
  end
end
yard-0.9.37/spec/code_objects/macro_object_spec.rb000066400000000000000000000102521466601756300221320ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::MacroObject do
  before do
    Registry.clear
  end

  describe ".create" do
    def create(*args) MacroObject.create(*args) end

    it "creates an object" do
      create('foo', '')
      obj = Registry.at('.macro.foo')
      expect(obj).not_to be nil
    end

    it "uses identity map" do
      obj1 = create('foo', '')
      obj2 = create('foo', '')
      expect(obj1.object_id).to eq obj2.object_id
    end

    it "allows specifying of macro data" do
      obj = create('foo', 'MACRODATA')
      expect(obj.macro_data).to eq 'MACRODATA'
    end

    context "if a method object is provided" do
      it "attaches it" do
        obj = create('foo', 'MACRODATA', P('Foo.property'))
        expect(obj.method_object).to eq P('Foo.property')
        expect(obj).to be_attached
      end
    end
  end

  describe ".find" do
    before { MacroObject.create('foo', 'DATA') }

    it "searches for an object by name" do
      expect(MacroObject.find('foo').macro_data).to eq 'DATA'
    end

    it "accepts Symbol" do
      expect(MacroObject.find(:foo).macro_data).to eq 'DATA'
    end
  end

  describe ".find_or_create" do
    it "looks up name if @!macro is present and find object" do
      macro1 = MacroObject.create('foo', 'FOO')
      macro2 = MacroObject.find_or_create('foo', "a b c")
      expect(macro1).to eq macro2
    end

    it "creates new macro if macro by that name does not exist" do
      MacroObject.find_or_create('foo', "@!method $1")
      expect(MacroObject.find('foo').macro_data).to eq "@!method $1"
    end
  end

  describe ".apply" do
    let(:args) { %w(foo a b c) }

    def apply(comments)
      MacroObject.apply(comments, args)
    end

    it "only expands macros if @macro is present" do
      expect(apply("$1$2$3")).to eq "$1$2$3"
    end

    it "handles macro text inside block" do
      expect(apply("@!macro\n  foo$1$2$3\nfoobaz")).to eq "fooabc\nfoobaz"
    end

    it "appends docstring to existing macro" do
      MacroObject.create('name', '$3$2$1')
      result = MacroObject.apply("@!macro name\nfoobar", args)
      expect(result).to eq "cba\nfoobar"
    end

    it "uses only non-macro data if docstring is an existing macro" do
      data = "@!macro name\n  $3$2$1\nEXTRA"
      result = MacroObject.apply(data, args, 'SOURCE')
      expect(result).to eq "cba\nEXTRA"
      expect(MacroObject.apply("@!macro name\nFOO", args)).to eq "cba\nFOO"
    end

    it "creates macros if they don't exist" do
      result = MacroObject.apply("@!macro name\n  foo!$1", args, 'SOURCE')
      expect(result).to eq "foo!a"
      expect(MacroObject.find('name').macro_data).to eq 'foo!$1'
    end

    it "keeps other tags" do
      expect(apply("@!macro\n  foo$1$2$3\n@param name foo\nfoo")).to eq(
        "fooabc\nfoo\n@param name\n  foo"
      )
    end
  end

  describe ".expand" do
    def expand(comments)
      args = %w(foo a b c)
      full_line = 'foo :bar, :baz'
      MacroObject.expand(comments, args, full_line)
    end

    it "allows escaping of macro syntax" do
      expect(expand("$1\\$2$3")).to eq "a$2c"
    end

    it "replaces $* with the whole statement" do
      expect(expand("$* ${*}")).to eq "foo :bar, :baz foo :bar, :baz"
    end

    it "replaces $0 with method name" do
      expect(expand("$0 ${0}")).to eq "foo foo"
    end

    it "replaces all $N values with the Nth argument in the method call" do
      expect(expand("$1$2$3${3}\nfoobar")).to eq "abcc\nfoobar"
    end

    it "replaces ${N-M} ranges with N-M arguments (incl. commas)" do
      expect(expand("${1-2}x")).to eq "a, bx"
    end

    it "handles open ended ranges (${N-})" do
      expect(expand("${2-}")).to eq "b, c"
    end

    it "handles negative indexes ($-N)" do
      expect(expand("$-1 ${-2-} ${-2--2}")).to eq "c b, c b"
    end

    it "accepts Docstring objects" do
      expect(expand(Docstring.new("$1\n@param name foo"))).to eq "a\n@param name foo"
    end
  end

  describe "#expand" do
    it "expands a macro given its data" do
      macro = MacroObject.create_docstring('foo', '$1 $2 THREE!')
      expect(macro.expand(['NAME', 'ONE', 'TWO'])).to eq "ONE TWO THREE!"
    end
  end
end
yard-0.9.37/spec/code_objects/method_object_spec.rb000066400000000000000000000135721466601756300223210ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::MethodObject do
  before do
    Registry.clear
    @yard = ModuleObject.new(:root, :YARD)
  end

  context "for an instance method in the root" do
    it "has a path of testing" do
      meth = MethodObject.new(:root, :testing)
      expect(meth.path).to eq "#testing"
    end
  end

  context "for an instance method in YARD" do
    it "has a path of YARD#testing" do
      meth = MethodObject.new(@yard, :testing)
      expect(meth.path).to eq "YARD#testing"
    end
  end

  context "for a class method in YARD" do
    it "has a path of YARD.testing" do
      meth = MethodObject.new(@yard, :testing, :class)
      expect(meth.path).to eq "YARD.testing"
    end
  end

  context "for a class method added to root namespace" do
    it "has a path of ::testing (note the ::)" do
      meth = MethodObject.new(:root, :testing, :class)
      expect(meth.path).to eq "::testing"
    end
  end

  it "exists in the registry after successful creation" do
    MethodObject.new(@yard, :something, :class)
    expect(Registry.at("YARD.something")).not_to be nil
    expect(Registry.at("YARD#something")).to be nil
    expect(Registry.at("YARD::something")).to be nil
    MethodObject.new(@yard, :somethingelse)
    expect(Registry.at("YARD#somethingelse")).not_to be nil
  end

  it "allows #scope to be changed after creation" do
    obj = MethodObject.new(@yard, :something, :class)
    expect(Registry.at("YARD.something")).not_to be nil
    obj.scope = :instance
    expect(Registry.at("YARD.something")).to be nil
    expect(Registry.at("YARD#something")).not_to be nil
  end

  it "creates object in :class scope if scope is :module" do
    obj = MethodObject.new(@yard, :module_func, :module)
    expect(obj.scope).to eq :class
    expect(obj.visibility).to eq :public
    expect(Registry.at('YARD.module_func')).not_to be nil
  end

  it "creates second private instance method if scope is :module" do
    MethodObject.new(@yard, :module_func, :module)
    obj = Registry.at('YARD#module_func')
    expect(obj).not_to be nil
    expect(obj.visibility).to eq :private
    expect(obj.scope).to eq :instance
  end

  it "yields block to second method if scope is :module" do
    MethodObject.new(@yard, :module_func, :module) do |o|
      o.docstring = 'foo'
    end
    expect(Registry.at('YARD.module_func').docstring).to eq 'foo'
    expect(Registry.at('YARD#module_func').docstring).to eq 'foo'
  end

  describe "#name" do
    it "shows a prefix for an instance method when prefix=true" do
      obj = MethodObject.new(nil, :something)
      expect(obj.name(true)).to eq "#something"
    end

    it "never shows a prefix for a class method" do
      obj = MethodObject.new(nil, :something, :class)
      expect(obj.name).to eq :something
      expect(obj.name(true)).to eq "something"
    end
  end

  describe "#is_attribute?" do
    it "only returns true if attribute is set in namespace for read/write" do
      obj = MethodObject.new(@yard, :foo)
      @yard.attributes[:instance][:foo] = {:read => obj, :write => nil}
      expect(obj.is_attribute?).to be true
      expect(MethodObject.new(@yard, :foo=).is_attribute?).to be false
    end
  end

  describe "#attr_info" do
    it "returns attribute info if namespace is available" do
      obj = MethodObject.new(@yard, :foo)
      @yard.attributes[:instance][:foo] = {:read => obj, :write => nil}
      expect(obj.attr_info).to eq @yard.attributes[:instance][:foo]
    end

    it "returns nil if namespace is proxy" do
      MethodObject.new(P(:ProxyClass), :foo)
      expect(MethodObject.new(@yard, :foo).attr_info).to eq nil
    end

    it "returns nil if meth is not an attribute" do
      expect(MethodObject.new(@yard, :notanattribute).attr_info).to eq nil
    end
  end

  describe "#writer?" do
    it "returns true if method is a writer attribute" do
      obj = MethodObject.new(@yard, :foo=)
      @yard.attributes[:instance][:foo] = {:read => nil, :write => obj}
      expect(obj.writer?).to be true
      expect(MethodObject.new(@yard, :NOTfoo=).writer?).to be false
    end
  end

  describe "#reader?" do
    it "returns true if method is a reader attribute" do
      obj = MethodObject.new(@yard, :foo)
      @yard.attributes[:instance][:foo] = {:read => obj, :write => nil}
      expect(obj.reader?).to be true
      expect(MethodObject.new(@yard, :NOTfoo).reader?).to be false
    end
  end

  describe "#constructor?" do
    before { @class = ClassObject.new(:root, :MyClass) }

    it "marks the #initialize method as constructor" do
      MethodObject.new(@class, :initialize)
    end

    it "does not mark Klass.initialize as constructor" do
      expect(MethodObject.new(@class, :initialize, :class).constructor?).to be false
    end

    it "does not mark module method #initialize as constructor" do
      expect(MethodObject.new(@yard, :initialize).constructor?).to be false
    end
  end

  describe "#overridden_method" do
    before { Registry.clear }

    it "returns overridden method from mixin first" do
      YARD.parse_string(<<-eof)
        module C; def foo; end end
        class A; def foo; end end
        class B < A; include C; def foo; end end
      eof
      expect(Registry.at('B#foo').overridden_method).to eq Registry.at('C#foo')
    end

    it "returns overridden method from superclass" do
      YARD.parse_string(<<-eof)
        class A; def foo; end end
        class B < A; def foo; end end
      eof
      expect(Registry.at('B#foo').overridden_method).to eq Registry.at('A#foo')
    end

    it "returns nil if none is found" do
      YARD.parse_string(<<-eof)
        class A; end
        class B < A; def foo; end end
      eof
      expect(Registry.at('B#foo').overridden_method).to be nil
    end

    it "returns nil if namespace is a proxy" do
      YARD.parse_string "def ARGV.foo; end"
      expect(Registry.at('ARGV.foo').overridden_method).to be nil
    end
  end
end
yard-0.9.37/spec/code_objects/module_object_spec.rb000066400000000000000000000113471466601756300223240ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::ModuleObject do
  describe "#meths" do
    before do
      Registry.clear

      # setup the object space:
      #
      #   YARD:module
      #   YARD#foo:method
      #   YARD#foo2:method
      #   YARD#xyz:method
      #   YARD.bar:method
      #   SomeMod#mixmethod
      #   SomeMod#xyz:method
      #
      @yard = ModuleObject.new(:root, :YARD)
      MethodObject.new(@yard, :foo)
      MethodObject.new(@yard, :xyz)
      MethodObject.new(@yard, :foo2) do |o|
        o.visibility = :protected
      end
      MethodObject.new(@yard, :bar, :class) do |o|
        o.visibility = :private
      end
      @other = ModuleObject.new(:root, :SomeMod)
      MethodObject.new(@other, :mixmethod)
      MethodObject.new(@other, :xyz)
      MethodObject.new(@other, :baz, :class)
      @another = ModuleObject.new(:root, :AnotherMod)
      MethodObject.new(@another, :fizz)
      MethodObject.new(@another, :bar)
      MethodObject.new(@another, :fazz, :class)

      @yard.instance_mixins << @other
      @yard.class_mixins << @another
    end

    it "lists all methods (including mixin methods) via #meths" do
      meths = @yard.meths
      expect(meths).to include(P("YARD#foo"))
      expect(meths).to include(P("YARD#foo2"))
      expect(meths).to include(P("YARD.bar"))
      expect(meths).to include(P("SomeMod#mixmethod"))
      expect(meths).to include(P("AnotherMod#fizz"))
    end

    it "allows :visibility to be set" do
      meths = @yard.meths(:visibility => :public)
      expect(meths).not_to include(P("YARD.bar"))
      meths = @yard.meths(:visibility => [:public, :private])
      expect(meths).to include(P("YARD#foo"))
      expect(meths).to include(P("YARD.bar"))
      expect(meths).not_to include(P("YARD#foo2"))
    end

    it "only displays class methods for :scope => :class" do
      meths = @yard.meths(:scope => :class)
      expect(meths).not_to include(P("YARD#foo"))
      expect(meths).not_to include(P("YARD#foo2"))
      expect(meths).not_to include(P("SomeMod#mixmethod"))
      expect(meths).not_to include(P("SomeMod.baz"))
      expect(meths).not_to include(P("AnotherMod#fazz"))
      expect(meths).to include(P("YARD.bar"))
      expect(meths).to include(P("AnotherMod#fizz"))
    end

    it "only displays instance methods for :scope => :class" do
      meths = @yard.meths(:scope => :instance)
      expect(meths).to include(P("YARD#foo"))
      expect(meths).to include(P("YARD#foo2"))
      expect(meths).to include(P("SomeMod#mixmethod"))
      expect(meths).not_to include(P("YARD.bar"))
      expect(meths).not_to include(P("AnotherMod#fizz"))
    end

    it "allows :included to be set" do
      meths = @yard.meths(:included => false)
      expect(meths).not_to include(P("SomeMod#mixmethod"))
      expect(meths).not_to include(P("AnotherMod#fizz"))
      expect(meths).to include(P("YARD#foo"))
      expect(meths).to include(P("YARD#foo2"))
      expect(meths).to include(P("YARD.bar"))
    end

    it "chooses the method defined in the class over an included module" do
      meths = @yard.meths
      expect(meths).not_to include(P("SomeMod#xyz"))
      expect(meths).to include(P("YARD#xyz"))
      expect(meths).not_to include(P("AnotherMod#bar"))
      expect(meths).to include(P("YARD.bar"))

      meths = @other.meths
      expect(meths).to include(P("SomeMod#xyz"))

      meths = @another.meths
      expect(meths).to include(P("AnotherMod#bar"))
    end
  end

  describe "#inheritance_tree" do
    before do
      Registry.clear

      @mod1 = ModuleObject.new(:root, :Mod1)
      @mod2 = ModuleObject.new(:root, :Mod2)
      @mod3 = ModuleObject.new(:root, :Mod3)
      @mod4 = ModuleObject.new(:root, :Mod4)
      @mod5 = ModuleObject.new(:root, :Mod5)

      @mod1.instance_mixins << @mod2
      @mod2.instance_mixins << @mod3
      @mod3.instance_mixins << @mod4
      @mod1.instance_mixins << @mod4

      @proxy = P(:SomeProxyClass)
      @mod5.instance_mixins << @proxy
    end

    it "shows only itself for an inheritance tree without included modules" do
      expect(@mod1.inheritance_tree).to eq [@mod1]
    end

    it "shows proper inheritance tree when modules are included" do
      expect(@mod1.inheritance_tree(true)).to eq [@mod1, @mod2, @mod3, @mod4]
    end

    it "does not list inheritance tree of proxy objects in inheritance tree" do
      expect(@proxy).not_to receive(:inheritance_tree)
      expect(@mod5.instance_mixins).to eq [@proxy]
    end

    it "lists class mixins in inheritance tree" do
      mod = ModuleObject.new(:root, :ClassMethods)
      recvmod = ModuleObject.new(:root, :ReceivingModule)
      recvmod.class_mixins << mod
      expect(recvmod.inheritance_tree(true)).to eq [recvmod, mod]
    end
  end
end
yard-0.9.37/spec/code_objects/namespace_mapper_spec.rb000066400000000000000000000016271466601756300230110ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::NamespaceMapper do
  include YARD::CodeObjects::NamespaceMapper

  describe '#register_separator' do
    it 'should allow separators to be registered' do
      register_separator '!', :test_type

      expect(separators_for_type(:test_type)).to eq ['!']
      expect(types_for_separator('!')).to eq [:test_type]

      unregister_separator_by_type :test_type

      expect(separators_for_type(:test_type)).to be_empty
      expect(types_for_separator('!')).to be_empty
    end
  end

  describe '.on_invalidate' do
    it 'receives a callback when a new separator is added' do
      invalidated = false
      NamespaceMapper.on_invalidate { invalidated = true }

      register_separator '!', :test_type
      expect(invalidated).to be true

      unregister_separator_by_type :test_type
    end
  end
end
yard-0.9.37/spec/code_objects/namespace_object_spec.rb000066400000000000000000000127261466601756300227750ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::NamespaceObject do
  before { Registry.clear }

  describe "#child" do
    it "returns the object matching the name passed in if argument is a Symbol" do
      obj = NamespaceObject.new(nil, :YARD)
      other = NamespaceObject.new(obj, :Other)
      expect(obj.child(:Other)).to eq other
      expect(obj.child('Other')).to eq other
    end

    it "looks for attributes matching the object if the argument is a Hash" do
      obj = NamespaceObject.new(nil, :YARD)
      NamespaceObject.new(obj, :NotOther)
      other = NamespaceObject.new(obj, :Other)
      other.somevalue = 2
      expect(obj.child(:somevalue => 2)).to eq other
    end
  end

  describe "#meths" do
    it "returns #meths even if parent is a Proxy" do
      obj = NamespaceObject.new(P(:String), :YARD)
      expect(obj.meths).to be_empty
    end

    it "does not list included methods that are already defined in the namespace using #meths" do
      a = ModuleObject.new(nil, :Mod1)
      ameth = MethodObject.new(a, :testing)
      b = ModuleObject.new(nil, :Mod2)
      bmeth = MethodObject.new(b, :foo)
      c = NamespaceObject.new(nil, :YARD)
      cmeth = MethodObject.new(c, :testing)
      cmeth2 = MethodObject.new(c, :foo)
      c.instance_mixins << a
      c.class_mixins << b

      meths = c.meths
      expect(meths).to include(bmeth)
      expect(meths).to include(cmeth)
      expect(meths).to include(cmeth2)
      expect(meths).not_to include(ameth)

      meths = c.included_meths
      expect(meths).to include(bmeth)
      expect(meths).not_to include(ameth)
      expect(meths).not_to include(cmeth)
      expect(meths).not_to include(cmeth2)
    end
  end

  describe "#included_meths" do
    it "lists methods mixed into the class scope as class methods" do
      b = ModuleObject.new(nil, :Mod2)
      bmeth = MethodObject.new(b, :foo)
      bmeth2 = MethodObject.new(b, :foo2)
      c = NamespaceObject.new(nil, :YARD)
      c.class_mixins << b

      [bmeth, bmeth2].each {|o| expect(o.scope).to eq :instance }
      meths = c.included_meths(:scope => :class)
      meths.each {|o| expect(o.scope).to eq :class }
    end

    it "does not list methods overridden by another included module" do
      a = ModuleObject.new(nil, :Mod)
      ameth = MethodObject.new(a, :testing)
      b = ModuleObject.new(nil, :Mod2)
      bmeth = MethodObject.new(b, :testing)
      c = NamespaceObject.new(nil, :YARD)
      c.instance_mixins.unshift a
      c.instance_mixins.unshift b
      c.class_mixins.unshift b
      c.class_mixins.unshift a

      meths = c.included_meths(:scope => :instance)
      expect(meths).not_to include(ameth)
      expect(meths).to include(bmeth)

      meths = c.included_meths(:scope => :class)
      expect(meths).to include(ameth)
      expect(meths).not_to include(bmeth)
    end
  end

  describe "#class_attributes" do
    it "lists class attributes" do
      a = NamespaceObject.new(nil, :Mod)
      a.attributes[:instance][:a] = {:read => MethodObject.new(a, :a), :write => nil}
      a.attributes[:instance][:b] = {:read => MethodObject.new(a, :b), :write => nil}
      a.attributes[:class][:a] = {:read => MethodObject.new(a, :a, :class), :write => nil}
      expect(a.class_attributes.keys).to include(:a)
      expect(a.class_attributes.keys).not_to include(:b)
    end
  end

  describe "#instance_attributes" do
    it "lists instance attributes" do
      a = NamespaceObject.new(nil, :Mod)
      a.attributes[:instance][:a] = {:read => MethodObject.new(a, :a), :write => nil}
      a.attributes[:instance][:b] = {:read => MethodObject.new(a, :b), :write => nil}
      a.attributes[:class][:a] = {:read => MethodObject.new(a, :a, :class), :write => nil}
      expect(a.instance_attributes.keys).to include(:a)
      expect(a.instance_attributes.keys).to include(:b)
    end
  end

  describe "#constants/#included_constants" do
    before do
      Registry.clear

      YARD.parse_string <<-eof
        module A
          CONST1 = 1
          CONST2 = 2
        end

        module B
          CONST2 = -2
          CONST3 = -3
        end

        class C
          CONST3 = 3
          CONST4 = 4

          include A
          include B
        end
      eof
    end

    it "lists all included constants by default" do
      consts = P(:C).constants
      expect(consts).to include(P('A::CONST1'))
      expect(consts).to include(P('C::CONST4'))
    end

    it "allows :included to be set to false to ignore included constants" do
      consts = P(:C).constants(:included => false)
      expect(consts).not_to include(P('A::CONST1'))
      expect(consts).to include(P('C::CONST4'))
    end

    it "does not list an included constant if it is defined in the object" do
      consts = P(:C).constants
      expect(consts).to include(P('C::CONST3'))
      expect(consts).not_to include(P('B::CONST3'))
    end

    it "does not list an included constant if it is shadowed by another included constant" do
      consts = P(:C).included_constants
      expect(consts).to include(P('B::CONST2'))
      expect(consts).not_to include(P('A::CONST2'))
    end
  end

  describe "#included_meths" do
    it "returns all included methods with :all = true" do
      YARD.parse_string <<-eof
        module B; def foo; end end
        module C; def bar; end end
        class A; include B; include C; def foo; end; def bar; end end
      eof
      expect(Registry.at('A').included_meths(:all => true)).to eq [P('C#bar'), P('B#foo')]
    end
  end
end
yard-0.9.37/spec/code_objects/proxy_spec.rb000066400000000000000000000107441466601756300206720ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::CodeObjects::Proxy do
  before { Registry.clear }

  it "does not allow constants to be used as a namespace if they do not resolve to a valid namespace" do
    a = ConstantObject.new(:root, :A)
    a.value = "$$INVALID$$"
    expect { P("A::MyClass") }.to raise_error(Parser::UndocumentableError)
  end

  it "returns the object if it's in the Registry" do
    ModuleObject.new(:root, :YARD)
    proxyobj = P(:root, :YARD)
    expect(proxyobj.type).to eq :module
    expect(Proxy === proxyobj).to be false
  end

  it "handles complex string namespaces" do
    ModuleObject.new(:root, :A)
    ModuleObject.new(P(nil, :A), :B)
    expect(P(:root, "A::B")).to be_instance_of(ModuleObject)
  end

  it "does not return true to Proxy === obj if obj is a Proxy class holding a resolved object" do
    expect(Proxy === P(:root, 'a')).to be true
    expect(Proxy === P(:root)).to be false
    MethodObject.new(:root, 'a')
    expect(Proxy === P(:root, 'a')).to be false
    x = Proxy.new(:root, 'a')
    expect(Proxy === x).to be false
  end

  it "returns the object if it's an included Module" do
    yardobj = ModuleObject.new(:root, :YARD)
    pathobj = ClassObject.new(:root, :TestClass)
    pathobj.instance_mixins << yardobj
    expect(P(P(nil, :TestClass), :YARD)).to be_instance_of(ModuleObject)
  end

  it "responds to respond_to?" do
    ClassObject.new(:root, :Object)
    ModuleObject.new(:root, :YARD)
    expect(P(:YARD).respond_to?(:children)).to be true
    expect(P(:NOTYARD).respond_to?(:children)).to be false

    expect(P(:YARD).respond_to?(:initialize)).to be false
    expect(P(:YARD).respond_to?(:initialize, true)).to be true
    expect(P(:NOTYARD).respond_to?(:initialize)).to be false
    expect(P(:NOTYARD).respond_to?(:initialize, true)).to be true
  end

  it "makes itself obvious that it's a proxy" do
    pathobj = P(:root, :YARD)
    expect(pathobj.class).to eq Proxy
    expect(Proxy === pathobj).to be true
  end

  it "pretends it's the object's type if it can resolve" do
    ModuleObject.new(:root, :YARD)
    proxyobj = P(:root, :YARD)
    expect(proxyobj).to be_instance_of(ModuleObject)
  end

  it "handles instance method names" do
    obj = P(nil, '#test')
    expect(obj.name).to eq :test
    expect(obj.path).to eq "#test"
    expect(obj.namespace).to eq Registry.root
  end

  it "handles instance method names under a namespace" do
    pathobj = ModuleObject.new(:root, :YARD)
    obj = P(pathobj, "A::B#test")
    expect(obj.name).to eq :test
    expect(obj.path).to eq "A::B#test"
  end

  it "allows type to be changed" do
    obj = P("InvalidClass")
    expect(obj.type).to eq :proxy
    expect(Proxy === obj).to be true
    obj.type = :class
    expect(obj.type).to eq :class
  end

  it "does NOT retain a type change between Proxy objects" do
    P("InvalidClass").type = :class
    expect(P("InvalidClass").type).to eq :proxy
  end

  it "uses type to ensure resolved object is of intended type" do
    YARD.parse_string <<-eof
      module Foo
        class Bar; end
        def self.Bar; end
      end
    eof
    proxy = Proxy.new(P('Foo'), 'Bar')
    proxy.type = :method
    expect(proxy.path).to eq 'Foo.Bar'
  end

  it "allows type in initializer" do
    expect(Proxy.new(Registry.root, 'Foo', :method).type).to eq :method
    expect(P(Registry.root, 'Foo', :method).type).to eq :method
  end

  it "never equals Registry.root" do
    expect(P("MYPROXY")).not_to eq Registry.root
    expect(P("X::A")).not_to eq Registry.root
  end

  it "resets namespace and name when object is resolved" do
    obj1 = ModuleObject.new(:root, :YARD)
    obj2 = ModuleObject.new(:root, :NOTYARD)
    resolved = Proxy.new(obj2, :YARD)
    expect(resolved).to eq obj1
    expect(resolved.namespace).to eq Registry.root
    expect(resolved.name).to eq :YARD
  end

  it "ensures that the correct object was resolved" do
    foo = ModuleObject.new(:root, :Foo)
    foobar = ModuleObject.new(foo, :Bar)
    ClassObject.new(foo, :Baz)

    # Remember, we're looking for Qux::Bar, not just 'Bar'
    proxy = Proxy.new(foobar, 'Foo::Qux::Bar')
    expect(proxy.type).to eq :proxy

    qux = ModuleObject.new(foo, :Qux)
    ModuleObject.new(qux, :Bar)

    # Now it should resolve
    expect(proxy.type).to eq :module
  end

  it "handles constant names in namespaces" do
    YARD.parse_string <<-eof
      module A; end; B = A
      module B::C; def foo; end end
    eof
    expect(Proxy.new(:root, 'B::C')).to eq Registry.at('A::C')
  end
end
yard-0.9.37/spec/code_objects/spec_helper.rb000066400000000000000000000000631466601756300207610ustar00rootroot00000000000000# frozen_string_literal: true

include CodeObjects
yard-0.9.37/spec/config_spec.rb000066400000000000000000000201021466601756300163200ustar00rootroot00000000000000# frozen_string_literal: true
require 'yaml'

RSpec.describe YARD::Config do
  describe ".load" do
    before do
      expect(File).to receive(:file?).twice.with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).and_return(false)
    end

    it "uses default options if no ~/.yard/config is found" do
      expect(File).to receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(false)
      expect(File).to receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(false)
      YARD::Config.load
      expect(YARD::Config.options).to eq YARD::Config::DEFAULT_CONFIG_OPTIONS
    end

    it "overwrites options with data in ~/.yard/config" do
      expect(File).to receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(true)
      expect(File).to receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(false)
      if YAML.respond_to?(:safe_load_file)
        expect(YAML).to receive(:safe_load_file)
          .with(YARD::Config::CONFIG_FILE, permitted_classes: [SymbolHash, Symbol])
          .and_return('test' => true)
      else
        expect(YAML).to receive(:load_file).with(YARD::Config::CONFIG_FILE).and_return('test' => true)
      end
      YARD::Config.load
      expect(YARD::Config.options[:test]).to be true
    end

    it "ignores any plugins specified in '~/.yard/ignored_plugins'" do
      expect(File).to receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(false)
      expect(File).to receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(true)
      expect(File).to receive(:read).with(YARD::Config::IGNORED_PLUGINS).and_return('yard-plugin plugin2')
      YARD::Config.load
      expect(YARD::Config.options[:ignored_plugins]).to eq ['yard-plugin', 'yard-plugin2']
      expect(YARD::Config).not_to receive(:require).with('yard-plugin2')
      expect(YARD::Config.load_plugin('yard-plugin2')).to be false
    end

    it "loads safe_mode setting from --safe command line option" do
      expect(File).to receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(false)
      expect(File).to receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(false)
      ARGV.replace(['--safe'])
      YARD::Config.load
      expect(YARD::Config.options[:safe_mode]).to be true
      ARGV.replace([''])
    end
  end

  describe ".save" do
    it "saves options to config file" do
      allow(YARD::Config).to receive(:options).and_return(:a => 1, :b => %w(a b c))
      file = double(:file)
      expect(File).to receive(:open).with(YARD::Config::CONFIG_FILE, 'w').and_yield(file)
      expect(file).to receive(:write).with(YAML.dump(:a => 1, :b => %w(a b c)))
      YARD::Config.save
    end
  end

  describe ".load_plugin" do
    it "loads a plugin by 'name' as 'yard-name'" do
      expect(YARD::Config).to receive(:require).with('yard-foo')
      expect(log).to receive(:debug).with(/Loading plugin 'yard-foo'/).once
      expect(YARD::Config.load_plugin('foo')).to be true
    end

    it "does not load plugins like 'doc-*'" do
      expect(YARD::Config).not_to receive(:require).with('yard-doc-core')
      YARD::Config.load_plugin('doc-core')
      YARD::Config.load_plugin('yard-doc-core')
    end

    it "loads plugin by 'yard-name' as 'yard-name'" do
      expect(YARD::Config).to receive(:require).with('yard-foo')
      expect(log).to receive(:debug).with(/Loading plugin 'yard-foo'/).once
      expect(YARD::Config.load_plugin('yard-foo')).to be true
    end

    it "loads plugin by 'yard_name' as 'yard_name'" do
      expect(YARD::Config).to receive(:require).with('yard_foo')
      expect(log).to receive(:debug).with(/Loading plugin 'yard_foo'/).once
      log.show_backtraces = false
      expect(YARD::Config.load_plugin('yard_foo')).to be true
    end

    it "logs error if plugin is not found" do
      expect(YARD::Config).to receive(:require).with('yard-foo').and_raise(LoadError)
      expect(log).to receive(:error).with(/Error loading plugin 'yard-foo'/).once
      expect(YARD::Config.load_plugin('yard-foo')).to be false
    end

    it "sanitizes plugin name (remove /'s)" do
      expect(YARD::Config).to receive(:require).with('yard-foofoo')
      expect(YARD::Config.load_plugin('foo/foo')).to be true
    end

    it "ignores plugins in :ignore_plugins" do
      allow(YARD::Config).to receive(:options).and_return(:ignored_plugins => ['yard-foo', 'yard-bar'])
      expect(YARD::Config.load_plugin('foo')).to be false
      expect(YARD::Config.load_plugin('bar')).to be false
    end
  end

  describe ".load_plugins" do
    it "loads gem plugins if :load_plugins is true" do
      allow(YARD::Config).to receive(:options).and_return(:load_plugins => true, :ignored_plugins => [], :autoload_plugins => [])
      allow(YARD::Config).to receive(:load_plugin)
      expect(YARD::Config).to receive(:require).with('rubygems')
      YARD::Config.load_plugins
    end

    it "ignores gem loading if RubyGems cannot load" do
      allow(YARD::Config).to receive(:options).and_return(:load_plugins => true, :ignored_plugins => [], :autoload_plugins => [])
      expect(YARD::Config).to receive(:require).with('rubygems').and_raise(LoadError)
      expect(YARD::Config.load_plugins).to be false
    end

    it "loads certain plugins automatically when specified in :autoload_plugins" do
      expect(File).to receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).and_return(false)
      allow(YARD::Config).to receive(:options).and_return(:load_plugins => false, :ignored_plugins => [], :autoload_plugins => ['yard-plugin'])
      expect(YARD::Config).to receive(:require).with('yard-plugin').and_return(true)
      expect(YARD::Config.load_plugins).to be true
    end

    it "parses --plugin from command line arguments" do
      expect(YARD::Config).to receive(:arguments).at_least(1).times.and_return(%w(--plugin foo --plugin bar a b c))
      expect(YARD::Config).to receive(:load_plugin).with('foo').and_return(true)
      expect(YARD::Config).to receive(:load_plugin).with('bar').and_return(true)
      expect(YARD::Config.load_plugins).to be true
    end

    it "loads --plugin arguments from .yardopts" do
      expect(File).to receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).twice.and_return(true)
      expect(File).to receive(:file?).with(YARD::Config::CONFIG_FILE).and_return(false)
      expect(File).to receive(:file?).with(YARD::Config::IGNORED_PLUGINS).and_return(false)
      expect(File).to receive(:read_binary).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).twice.and_return('--plugin foo')
      expect(YARD::Config).to receive(:load_plugin).with('foo')
      YARD::Config.load
    end

    it "loads any gem plugins starting with 'yard_' or 'yard-'" do
      expect(File).to receive(:file?).with(CLI::Yardoc::DEFAULT_YARDOPTS_FILE).and_return(false)
      allow(YARD::Config).to receive(:options).and_return(:load_plugins => true, :ignored_plugins => ['yard_plugin'], :autoload_plugins => [])
      plugins = {
        'yard' => double('yard'),
        'yard_plugin' => double('yard_plugin'),
        'yard-plugin' => double('yard-plugin'),
        'my-yard-plugin' => double('yard-plugin'),
        'rspec' => double('rspec')
      }
      plugins.each do |k, v|
        expect(v).to receive(:name).at_least(1).times.and_return(k)
      end

      expect(YARD::GemIndex).to receive(:each) {|&b| plugins.values.each(&b) }
      expect(YARD::Config).to receive(:load_plugin).with('yard_plugin').and_return(false)
      expect(YARD::Config).to receive(:load_plugin).with('yard-plugin').and_return(true)
      expect(YARD::Config.load_plugins).to be true
    end

    it "logs an error if a gem raises an error" do
      allow(YARD::Config).to receive(:options).and_return(:load_plugins => true, :ignored_plugins => [], :autoload_plugins => [])
      plugins = {
        'yard-plugin' => double('yard-plugin')
      }
      plugins.each do |k, v|
        expect(v).to receive(:name).at_least(1).times.and_return(k)
      end

      expect(YARD::GemIndex).to receive(:each) {|&b| plugins.values.each(&b) }
      expect(YARD::Config).to receive(:load_plugin).with('yard-plugin').and_raise(Gem::LoadError)
      expect(log).to receive(:error).with(/Error loading plugin 'yard-plugin'/)
      expect(YARD::Config.load_plugins).to be false
    end
  end
end
yard-0.9.37/spec/core_ext/000077500000000000000000000000001466601756300153315ustar00rootroot00000000000000yard-0.9.37/spec/core_ext/array_spec.rb000066400000000000000000000005071466601756300200100ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe Array do
  describe "#place" do
    it "creates an Insertion object" do
      expect([].place('x')).to be_kind_of(Insertion)
    end

    it "allows multiple objects to be placed" do
      expect([1, 2].place('x', 'y', 'z').before(2)).to eq [1, 'x', 'y', 'z', 2]
    end
  end
end
yard-0.9.37/spec/core_ext/file_spec.rb000066400000000000000000000044031466601756300176100ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe File do
  describe ".relative_path" do
    it "returns the relative path between two files" do
      expect(File.relative_path('a/b/c/d.html', 'a/b/d/q.html')).to eq '../d/q.html'
    end

    it "returns the relative path between two directories" do
      expect(File.relative_path('a/b/c/d/', 'a/b/d/')).to eq '../d'
    end

    it "returns only the to file if from file is in the same directory as the to file" do
      expect(File.relative_path('a/b/c/d', 'a/b/c/e')).to eq 'e'
    end

    it "handles non-normalized paths" do
      expect(File.relative_path('Hello/./I/Am/Fred', 'Hello/Fred')).to eq '../../Fred'
      expect(File.relative_path('A//B/C', 'Q/X')).to eq '../../Q/X'
    end
  end

  describe ".cleanpath" do
    it "cleans double brackets" do
      expect(File.cleanpath('A//B/C')).to eq "A/B/C"
    end

    it "cleans a path with ." do
      expect(File.cleanpath('Hello/./I/.Am/Fred')).to eq "Hello/I/.Am/Fred"
    end

    it "cleans a path with .." do
      expect(File.cleanpath('Hello/../World')).to eq "World"
    end

    it "cleans a path with multiple .." do
      expect(File.cleanpath('A/B/C/../../D')).to eq "A/D"
    end

    it "cleans a path ending in .." do
      expect(File.cleanpath('A/B/C/D/..')).to eq "A/B/C"
    end

    it "allows '../' at the beginning if rel_root=true" do
      expect(File.cleanpath('A/../../B', true)).to eq '../B'
    end

    it "does not allow relative path above root" do
      expect(File.cleanpath('A/../../../../../D')).to eq "D"
    end

    it "does not remove multiple '../' at the beginning" do
      expect(File.cleanpath('../../A/B')).to eq 'A/B'
    end
  end

  describe ".open!" do
    it "creates the path before opening" do
      expect(File).to receive(:directory?).with('/path/to').and_return(false)
      expect(FileUtils).to receive(:mkdir_p).with('/path/to')
      expect(File).to receive(:open).with('/path/to/file', 'w')
      File.open!('/path/to/file', 'w')
    end

    it "just opens the file if the path exists" do
      expect(File).to receive(:directory?).with('/path/to').and_return(true)
      expect(FileUtils).not_to receive(:mkdir_p)
      expect(File).to receive(:open).with('/path/to/file', 'w')
      File.open!('/path/to/file', 'w')
    end
  end
end
yard-0.9.37/spec/core_ext/hash_spec.rb000066400000000000000000000005621466601756300176160ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe Hash do
  describe ".[]" do
    it "accepts an Array argument (Ruby 1.8.6 and older)" do
      list = [['foo', 'bar'], ['foo2', 'bar2']]
      expect(Hash[list]).to eq('foo' => 'bar', 'foo2' => 'bar2')
    end

    it "accepts an array as a key" do
      expect(Hash[['a', 'b'], 1]).to eq(['a', 'b'] => 1)
    end
  end
end
yard-0.9.37/spec/core_ext/insertion_spec.rb000066400000000000000000000021371466601756300207050ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe Insertion do
  describe "#before" do
    it "places an object before another" do
      expect([1, 2].place(3).before(2)).to eq [1, 3, 2]
      expect([1, 2].place(3).before(1)).to eq [3, 1, 2]
      expect([1, [4], 2].place(3).before(2)).to eq [1, [4], 3, 2]
    end
  end

  describe "#after" do
    it "places an object after another" do
      expect([1, 2].place(3).after(2)).to eq [1, 2, 3]
    end

    it "no longer places an object after another and its subsections (0.6)" do
      expect([1, [2]].place(3).after(1)).to eq [1, 3, [2]]
    end

    it "places an array after an object" do
      expect([1, 2, 3].place([4]).after(1)).to eq [1, [4], 2, 3]
    end
  end

  describe "#before_any" do
    it "places an object before another anywhere inside list (including sublists)" do
      expect([1, 2, [3]].place(4).before_any(3)).to eq [1, 2, [4, 3]]
    end
  end

  describe "#after_any" do
    it "places an object after another anywhere inside list (including sublists)" do
      expect([1, 2, [3]].place(4).after_any(3)).to eq [1, 2, [3, 4]]
    end
  end
end
yard-0.9.37/spec/core_ext/module_spec.rb000066400000000000000000000003321466601756300201530ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe Module do
  describe "#class_name" do
    it "returns just the name of the class/module" do
      expect(YARD::CodeObjects::Base.class_name).to eq "Base"
    end
  end
end
yard-0.9.37/spec/core_ext/string_spec.rb000066400000000000000000000023121466601756300201740ustar00rootroot00000000000000# frozen_string_literal: true

# described_in_docs String, '#camelcase'
# described_in_docs String, '#underscore'

RSpec.describe String do
  describe "#shell_split" do
    it "splits simple non-quoted text" do
      expect("a b c".shell_split).to eq %w(a b c)
    end

    it "splits double quoted text into single token" do
      expect('a "b c d" e'.shell_split).to eq ["a", "b c d", "e"]
    end

    it "splits single quoted text into single token" do
      expect("a 'b c d' e".shell_split).to eq ["a", "b c d", "e"]
    end

    it "handles escaped quotations in quotes" do
      expect("'a \\' b'".shell_split).to eq ["a ' b"]
    end

    it "handles escaped quotations outside quotes" do
      expect("\\'a 'b'".shell_split).to eq %w('a b)
    end

    it "handles escaped backslash" do
      expect("\\\\'a b c'".shell_split).to eq ['\a b c']
    end

    it "handles any whitespace as space" do
      text = "foo\tbar\nbaz\r\nfoo2 bar2"
      expect(text.shell_split).to eq %w(foo bar baz foo2 bar2)
    end

    it "handles complex input" do
      text = "hello \\\"world \"1 2\\\" 3\" a 'b \"\\\\\\'' c"
      expect(text.shell_split).to eq ["hello", "\"world", "1 2\" 3", "a", "b \"\\'", "c"]
    end
  end
end
yard-0.9.37/spec/core_ext/symbol_hash_spec.rb000066400000000000000000000043611466601756300212040ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe SymbolHash do
  it "allows access to keys as String or Symbol" do
    h = SymbolHash.new(false)
    h['test'] = true
    expect(h[:test]).to be true
    expect(h['test']).to be true
  end

  describe "#delete" do
    it "accepts either Strings or Symbols as deletion key" do
      h = SymbolHash.new
      expect(h.keys.length).to eq 0

      h['test'] = true
      expect(h.keys.length).to eq 1

      h.delete(:test)
      expect(h.keys.length).to eq 0

      h[:test] = true
      expect(h.keys.length).to eq 1

      h.delete('test')
      expect(h.keys.length).to eq 0
    end
  end

  describe "#key?" do
    it "returns same result for String or Symbol" do
      h = SymbolHash.new
      h[:test] = 1
      expect(h.key?(:test)).to be true
      expect(h.has_key?('test')).to be true # rubocop:disable Style/PreferredHashMethods
    end
  end

  it "symbolizes value if it is a String (and only a string)" do
    class Substring < String; end

    h = SymbolHash.new
    h['test1'] = "hello"
    h['test2'] = Substring.new("hello")
    expect(h['test1']).to eq :hello
    expect(h['test2']).to eq "hello"
  end

  it "does not symbolize value if SymbolHash.new(false) is created" do
    h = SymbolHash.new(false)
    h['test'] = "hello"
    expect(h[:test]).to eq "hello"
  end

  it "does not symbolize value if it is not a String" do
    h = SymbolHash.new
    h['test'] = [1, 2, 3]
    expect(h['test']).to eq [1, 2, 3]
  end

  it "supports symbolization using #update or #merge!" do
    h = SymbolHash.new
    h.update('test' => 'value')
    expect(h[:test]).to eq :value
    h.merge!('test' => 'value2') # rubocop:disable Performance/RedundantMerge
    expect(h[:test]).to eq :value2
  end

  it "supports symbolization non-destructively using #merge" do
    h = SymbolHash.new
    expect(h.merge('test' => 'value')[:test]).to eq :value
    expect(h).to eq SymbolHash.new
  end

  it "supports #initializing of a hash" do
    h = SymbolHash[:test => 1]
    expect(h[:test]).to eq 1
    expect(h[:somethingelse]).to be nil
  end

  it "supports reverse merge syntax" do
    opts = {}
    opts = SymbolHash[
      'default' => 1
    ].update(opts)
    expect(opts.keys).to eq [:default]
    expect(opts[:default]).to eq 1
  end
end
yard-0.9.37/spec/docstring_parser_spec.rb000066400000000000000000000172531466601756300204400ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::DocstringParser do
  after(:all) do
    YARD::Registry.clear
  end

  def parse(content, object = nil, handler = nil)
    @library ||= Tags::Library.instance
    @parser = DocstringParser.new(@library)
    @parser.parse(content, object, handler)
    @parser
  end

  def docstring(content, object = nil, handler = nil)
    parse(content, object, handler).to_docstring
  end

  describe "#parse" do
    it "parses comments into tags" do
      doc = docstring(<<-eof)
@param name Hello world
  how are you?
@param name2
  this is a new line
@param name3 and this
  is a new paragraph:

  right here.
      eof
      tags = doc.tags(:param)
      expect(tags[0].name).to eq "name"
      expect(tags[0].text).to eq "Hello world\nhow are you?"
      expect(tags[1].name).to eq "name2"
      expect(tags[1].text).to eq "this is a new line"
      expect(tags[2].name).to eq "name3"
      expect(tags[2].text).to eq "and this\nis a new paragraph:\n\nright here."
    end

    it "ends parsing a tag on de-dent" do
      doc = docstring(<<-eof)
@note test
  one two three
rest of docstring
      eof
      expect(doc.tag(:note).text).to eq "test\none two three"
      expect(doc).to eq "rest of docstring"
    end

    it "parses examples embedded in doc" do
      doc = docstring(<<-eof)
test string here
@example code

  def foo(x, y, z)
  end

  class A; end

more stuff
eof
      expect(doc).to eq "test string here\nmore stuff"
      expect(doc.tag(:example).text).to eq "\ndef foo(x, y, z)\nend\n\nclass A; end"
    end

    it "removes only original indentation from beginning of line in tags" do
      doc = docstring(<<-eof)
@param name
  some value
  foo bar
   baz
eof
      expect(doc.tag(:param).text).to eq "some value\nfoo bar\n baz"
    end

    it "allows numbers in tags" do
      Tags::Library.define_tag(nil, :foo1)
      Tags::Library.define_tag(nil, :foo2)
      Tags::Library.define_tag(nil, :foo3)
      doc = docstring(<<-eof)
@foo1 bar1
@foo2 bar2
@foo3 bar3
eof
      expect(doc.tag(:foo1).text).to eq "bar1"
      expect(doc.tag(:foo2).text).to eq "bar2"
    end

    it "ends tag on newline if next line is not indented" do
      doc = docstring(<<-eof)
@author bar1
@api bar2
Hello world
eof
      expect(doc.tag(:author).text).to eq "bar1"
      expect(doc.tag(:api).text).to eq "bar2"
    end

    it "warns about unknown tag" do
      expect(log).to receive(:warn).with(/Unknown tag @hello$/)
      docstring("@hello world")
    end

    it "does not add trailing whitespace to freeform tags" do
      doc = docstring("@api private   \t   ")
      expect(doc.tag(:api).text).to eq "private"
    end
  end

  describe "#parse with custom tag library" do
    class TestLibrary < Tags::Library; end

    before { @library = TestLibrary.new }

    it "accepts valid tags" do
      valid = %w(testing valid is_a is_A __)
      valid.each do |tag|
        TestLibrary.define_tag("Tag", tag)
        doc = docstring('@' + tag + ' foo bar')
        expect(doc.tag(tag).text).to eq 'foo bar'
      end
    end

    it "does not parse invalid tag names" do
      invalid = %w(@ @return@ @p,aram @x-y @.x.y.z)
      invalid.each do |tag|
        expect(docstring(tag + ' foo bar')).to eq tag + ' foo bar'
      end
    end

    it "allows namespaced tags in the form @x.y.z" do
      TestLibrary.define_tag("Tag", 'x.y.z')
      doc = docstring("@x.y.z foo bar")
      expect(doc.tag('x.y.z').text).to eq 'foo bar'
    end

    it "ignores new directives without @! prefix syntax" do
      TestLibrary.define_directive('dir1', Tags::ScopeDirective)
      expect(log).to receive(:warn).with(/@dir1/)
      docstring("@dir1")
    end

    %w(attribute endgroup group macro method scope visibility).each do |tag|
      it "handles non prefixed @#{tag} syntax as directive, not tag" do
        TestLibrary.define_directive(tag, Tags::ScopeDirective)
        parse("@#{tag}")
        expect(@parser.directives.first).to be_a(Tags::ScopeDirective)
      end
    end

    it "handles directives with @! prefix syntax" do
      TestLibrary.define_directive('dir2', Tags::ScopeDirective)
      docstring("@!dir2 class")
      expect(@parser.state.scope).to eq :class
    end
  end

  describe "#text" do
    it "only returns text data" do
      parse("Foo\n@param foo x y z\nBar")
      expect(@parser.text).to eq "Foo\nBar"
    end
  end

  describe "#raw_text" do
    it "returns the entire original data" do
      data = "Foo\n@param foo x y z\nBar"
      parse(data)
      expect(@parser.raw_text).to eq data
    end
  end

  describe "#tags" do
    it "returns the parsed tags" do
      data = "Foo\n@param foo x y z\nBar"
      parse(data)
      expect(@parser.tags.size).to eq 1
      expect(@parser.tags.first.tag_name).to eq 'param'
    end
  end

  describe "#directives" do
    it "groups all processed directives" do
      data = "Foo\n@!scope class\n@!visibility private\nBar"
      parse(data)
      dirs = @parser.directives
      expect(dirs[0]).to be_a(Tags::ScopeDirective)
      expect(dirs[0].tag.text).to eq 'class'
      expect(dirs[1]).to be_a(Tags::VisibilityDirective)
      expect(dirs[1].tag.text).to eq 'private'
    end
  end

  describe "#state" do
    it "handles modified state" do
      parse("@!scope class")
      expect(@parser.state.scope).to eq :class
    end
  end

  describe "after_parse (param)" do
    it "allows specifying of callbacks" do
      parser = DocstringParser.new
      the_yielded_obj = nil
      DocstringParser.after_parse {|obj| the_yielded_obj = obj }
      parser.parse("Some text")
      expect(the_yielded_obj).to eq parser
    end

    it "warns about invalid named parameters" do
      expect(log).to receive(:warn).with(/@param tag has unknown parameter name: notaparam/)
      YARD.parse_string <<-eof
        # @param notaparam foo
        def foo(a) end
      eof
    end

    it "warns about invalid named parameters on @!method directives" do
      expect(log).to receive(:warn).with(/@param tag has unknown parameter name: notaparam/)
      YARD.parse_string <<-eof
        # @!method foo(a)
        #   @param notaparam foo
        test
      eof
    end

    it "warns about duplicate named parameters" do
      expect(log).to receive(:warn).with(/@param tag has duplicate parameter name: a/)
      YARD.parse_string <<-eof
        # @param a foo
        # @param a foo
        def foo(a) end
      eof
    end

    it "does not warn on aliases" do
      expect(log).to_not receive(:warn)
      YARD.parse_string <<-eof
        # @param a foo
        def foo(a) end
        alias bar foo
      eof
    end

    it "does not warn on matching param with inline method modifier" do
      expect(log).to_not receive(:warn)
      YARD.parse_string <<-eof
        # @param [Numeric] a
        # @return [Numeric]
        private_class_method def self.foo(a); a + 1; end
      eof
    end

    it "warns on mismatching param with inline method modifier" do
      expect(log).to receive(:warn).with(/@param tag has unknown parameter name: notaparam/)
      YARD.parse_string <<-eof
        # @param [Numeric] notaparam
        # @return [Numeric]
        private_class_method def self.foo(a); a + 1; end
      eof
    end
  end

  describe "after_parse (see)" do
    it "does not warn on valid see tag" do
      expect(log).to_not receive(:warn)
      YARD.parse_string "# @see valid\nclass Foo;end"
    end

    it "warns if {} wraps single name" do
      expect(log).to receive(:warn).with(/@see tag \(#1\) should not be wrapped in \{\}/)
      YARD.parse_string "# @see {invalid}\nclass Foo;end"
    end

    it "warns if {} wraps across name and text" do
      expect(log).to receive(:warn).with(/@see tag \(#1\) should not be wrapped in \{\}/)
      YARD.parse_string "# @see {invalid tag}\nclass Foo;end"
    end
  end
end
yard-0.9.37/spec/docstring_spec.rb000066400000000000000000000304641466601756300170630ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Docstring do
  before { YARD::Registry.clear }

  describe "#initialize" do
    it "handles docstrings with empty newlines" do
      expect(Docstring.new("\n\n")).to eq ""
    end
  end

  describe "#+" do
    it "adds another Docstring" do
      d = Docstring.new("FOO") + Docstring.new("BAR")
      expect(d).to eq "FOO\nBAR"
    end

    it "copies over tags" do
      d1 = Docstring.new("FOO\n@api private\n")
      d2 = Docstring.new("BAR\n@param foo descr")
      d = (d1 + d2)
      expect(d).to have_tag(:api)
      expect(d).to have_tag(:param)
    end

    it "adds a String" do
      d = Docstring.new("FOO") + "BAR"
      expect(d).to eq "FOOBAR"
    end
  end

  describe "#line" do
    it "returns nil if #line_range is not set" do
      expect(Docstring.new('foo').line).to be nil
    end

    it "returns line_range.first if #line_range is set" do
      doc = Docstring.new('foo')
      doc.line_range = (1..10)
      expect(doc.line).to eq doc.line_range.first
    end
  end

  describe "#summary" do
    it "handles empty docstrings" do
      o1 = Docstring.new
      expect(o1.summary).to eq ""
    end

    it "handles multiple calls" do
      o1 = Docstring.new("Hello. world")
      5.times { expect(o1.summary).to eq "Hello." }
    end

    it "strips newlines in first paragraph before summarizing" do
      doc = Docstring.new("Foo\n== bar.")
      expect(doc.summary).to eq 'Foo == bar.'
    end

    it "returns the first sentence" do
      o = Docstring.new("DOCSTRING. Another sentence")
      expect(o.summary).to eq "DOCSTRING."
    end

    it "returns the first paragraph" do
      o = Docstring.new("DOCSTRING, and other stuff\n\nAnother sentence.")
      expect(o.summary).to eq "DOCSTRING, and other stuff."
    end

    it "returns proper summary when docstring is changed" do
      o = Docstring.new "DOCSTRING, and other stuff\n\nAnother sentence."
      expect(o.summary).to eq "DOCSTRING, and other stuff."
      o = Docstring.new "DOCSTRING."
      expect(o.summary).to eq "DOCSTRING."
    end

    it "does not double the ending period" do
      o = Docstring.new("Returns a list of tags specified by +name+ or all tags if +name+ is not specified.\n\nTest")
      expect(o.summary).to eq "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."

      doc = Docstring.new(<<-eof)

        Returns a list of tags specified by +name+ or all tags if +name+ is not specified.

        @param name the tag name to return data for, or nil for all tags
        @return [Array] the list of tags by the specified tag name
      eof
      expect(doc.summary).to eq "Returns a list of tags specified by +name+ or all tags if +name+ is not specified."
    end

    it "does not attach period if entire summary is include" do
      YARD.parse_string "# docstring\ndef foo; end"
      expect(Docstring.new("{include:#foo}").summary).to eq '{include:#foo}'
      Registry.clear
    end

    it "handles references embedded in summary" do
      expect(Docstring.new("Aliasing {Test.test}. Done.").summary).to eq "Aliasing {Test.test}."
    end

    it "only ends first sentence when outside parentheses" do
      expect(Docstring.new("Hello (the best.) world. Foo bar.").summary).to eq "Hello (the best.) world."
      expect(Docstring.new("A[b.]c.").summary).to eq "A[b.]c."
    end

    it "only sees '.' as period if whitespace (or eof) follows" do
      expect(Docstring.new("hello 1.5 times.").summary).to eq "hello 1.5 times."
      expect(Docstring.new("hello... me").summary).to eq "hello..."
      expect(Docstring.new("hello.").summary).to eq "hello."
    end

    it "returns summary if there is a newline and parentheses count doesn't match" do
      expect(Docstring.new("Happy method call :-)\n\nCall any time.").summary).to eq "Happy method call :-)."
      expect(Docstring.new("Sad method call :-(\n\nCall any time.").summary).to eq "Sad method call :-(."
      expect(Docstring.new("Hello (World. Forget to close.\n\nNew text").summary).to eq "Hello (World. Forget to close."
      expect(Docstring.new("Hello (World. Forget to close\n\nNew text").summary).to eq "Hello (World. Forget to close."
    end
  end

  describe "#ref_tags" do
    it "parses reference tag into ref_tags" do
      doc = Docstring.new("@return (see Foo#bar)")
      expect(doc.ref_tags.size).to eq 1
      expect(doc.ref_tags.first.owner).to eq P("Foo#bar")
      expect(doc.ref_tags.first.tag_name).to eq "return"
      expect(doc.ref_tags.first.name).to be nil
    end

    it "parses named reference tag into ref_tags" do
      doc = Docstring.new("@param blah \n   (see Foo#bar )")
      expect(doc.ref_tags.size).to eq 1
      expect(doc.ref_tags.first.owner).to eq P("Foo#bar")
      expect(doc.ref_tags.first.tag_name).to eq "param"
      expect(doc.ref_tags.first.name).to eq "blah"
    end

    it "fails to parse named reference tag into ref_tags" do
      doc = Docstring.new("@param blah THIS_BREAKS_REFTAG (see Foo#bar)")
      expect(doc.ref_tags.size).to eq 0
    end

    it "returns all valid reference tags along with #tags" do
      o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
      o.docstring.add_tag Tags::Tag.new('return', 'testing')
      doc = Docstring.new("@return (see Foo#bar)")
      tags = doc.tags
      expect(tags.size).to eq 1
      expect(tags.first.text).to eq 'testing'
      expect(tags.first).to be_kind_of(Tags::RefTag)
      expect(tags.first.owner).to eq o
    end

    it "returns all valid named reference tags along with #tags(name)" do
      o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
      o.docstring.add_tag Tags::Tag.new('param', 'testing', nil, '*args')
      o.docstring.add_tag Tags::Tag.new('param', 'NOTtesting', nil, 'notargs')
      doc = Docstring.new("@param *args (see Foo#bar)")
      tags = doc.tags('param')
      expect(tags.size).to eq 1
      expect(tags.first.text).to eq 'testing'
      expect(tags.first).to be_kind_of(Tags::RefTag)
      expect(tags.first.owner).to eq o
    end

    it "ignores invalid reference tags" do
      doc = Docstring.new("@param *args (see INVALID::TAG#tag)")
      tags = doc.tags('param')
      expect(tags.size).to eq 0
    end

    it "resolves references to methods in the same class with #methname" do
      klass = CodeObjects::ClassObject.new(:root, "Foo")
      o = CodeObjects::MethodObject.new(klass, "bar")
      ref = CodeObjects::MethodObject.new(klass, "baz")
      o.docstring.add_tag Tags::Tag.new('param', 'testing', nil, 'arg1')
      ref.docstring = "@param (see #bar)"

      tags = ref.docstring.tags("param")
      expect(tags.size).to eq 1
      expect(tags.first.text).to eq "testing"
      expect(tags.first).to be_kind_of(Tags::RefTag)
      expect(tags.first.owner).to eq o
    end

    it "returns an empty list (and warning) if circular reftags are found" do
      YARD.parse_string <<-eof
        class Foo
          # @param (see #b)
          def a; end
          # @param (see #a)
          def b; end
        end
      eof

      expect(log.io.string).to match(/error.*circular reference tag in `Foo#b'/)
      expect(Registry.at('Foo#a').tags).to be_empty
      expect(Registry.at('Foo#b').tags).to be_empty
    end

    it "returns an empty list (and warning) if self-circular reftags are found" do
      YARD.parse_string <<-eof
        class Foo
          # @param (see #bar)
          def bar; end
        end
      eof

      expect(log.io.string).to match(/error.*circular reference tag in `Foo#bar'/)
      expect(Registry.at('Foo#bar').tags).to be_empty
    end
  end

  describe "#empty?/#blank?" do
    before(:all) do
      Tags::Library.define_tag "Invisible", :invisible_tag
    end

    it "is blank and empty if it has no content and no tags" do
      expect(Docstring.new).to be_blank
      expect(Docstring.new).to be_empty
    end

    it "isn't empty or blank if it has content" do
      d = Docstring.new("foo bar")
      expect(d).not_to be_empty
      expect(d).not_to be_blank
    end

    it "is empty but not blank if it has tags" do
      d = Docstring.new("@param foo")
      expect(d).to be_empty
      expect(d).not_to be_blank
    end

    it "is empty but not blank if it has ref tags" do
      o = CodeObjects::MethodObject.new(:root, 'Foo#bar')
      o.docstring.add_tag Tags::Tag.new('return', 'testing')
      d = Docstring.new("@return (see Foo#bar)")
      expect(d).to be_empty
      expect(d).not_to be_blank
    end

    it "is blank if it has no visible tags" do
      d = Docstring.new("@invisible_tag value")
      expect(d).to be_blank
    end

    it "is not blank if it has invisible tags and only_visible_tags = false" do
      d = Docstring.new("@invisible_tag value")
      d.add_tag Tags::Tag.new('invisible_tag', nil, nil)
      expect(d.blank?(false)).to be false
    end
  end

  describe "#delete_tags" do
    it "deletes tags by a given tag name" do
      doc = Docstring.new("@param name x\n@param name2 y\n@return foo")
      doc.delete_tags(:param)
      expect(doc.tags.size).to eq 1
    end
  end

  describe "#delete_tag_if" do
    it "deletes tags for a given block" do
      doc = Docstring.new("@param name x\n@param name2 y\n@return foo")
      doc.delete_tag_if {|t| t.name == 'name2' }
      expect(doc.tags.size).to eq 2
    end
  end

  describe "#to_raw" do
    it "returns a clean representation of tags" do
      doc = Docstring.new("Hello world\n@return [String, X] foobar\n@param name the name\nBYE!")
      expect(doc.to_raw).to eq "Hello world\nBYE!\n@param [Array] name\n  the name\n@return [String, X] foobar"
    end

    it "handles tags with newlines and indentation" do
      doc = Docstring.new("@example TITLE\n  the \n  example\n  @foo\n@param [X] name\n  the name")
      expect(doc.to_raw).to eq "@example TITLE\n  the \n  example\n  @foo\n@param [X] name\n  the name"
    end

    it "handles deleted tags" do
      doc = Docstring.new("@example TITLE\n  the \n  example\n  @foo\n@param [X] name\n  the name")
      doc.delete_tags(:param)
      expect(doc.to_raw).to eq "@example TITLE\n  the \n  example\n  @foo"
    end

    it "handles added tags" do
      doc = Docstring.new("@example TITLE\n  the \n  example\n  @foo")
      doc.add_tag(Tags::Tag.new('foo', 'foo'))
      expect(doc.to_raw).to eq "@example TITLE\n  the \n  example\n  @foo\n@foo foo"
    end

    it "is equal to .all if not modified" do
      doc = Docstring.new("123\n@param")
      expect(doc.to_raw).to eq doc.all
    end

    it "is stable sorting tags" do
      expected = Docstring.new("123\n@param x\n@param y\n@version A")
      doc = Docstring.new("123")
      doc.add_tag(Tags::Tag.new('version', 'A'))
      doc.add_tag(Tags::Tag.new('param', 'x'))
      doc.add_tag(Tags::Tag.new('param', 'y'))
      expect(doc.to_raw).to eq expected.all
    end

    # @bug gh-563
    it "handles full @option tags" do
      doc = Docstring.new("@option foo [String] bar (nil) baz")
      expect(doc.to_raw).to eq "@option foo [String] bar (nil) baz"
    end

    # @bug gh-563
    it "handles simple @option tags" do
      doc = Docstring.new("@option foo :key bar")
      expect(doc.to_raw).to eq "@option foo :key bar"
    end
  end

  describe "#dup" do
    it "duplicates docstring text" do
      doc = Docstring.new("foo")
      expect(doc.dup).to eq doc
      expect(doc.dup.all).to eq doc
    end

    it "duplicates tags to new list" do
      doc = Docstring.new("@param x\n@return y")
      doc2 = doc.dup
      doc2.delete_tags(:param)
      expect(doc.tags.size).to eq 2
      expect(doc2.tags.size).to eq 1
    end

    it "preserves summary" do
      doc = Docstring.new("foo. bar")
      expect(doc.dup.summary).to eq doc.summary
    end

    it "preserves hash_flag" do
      doc = Docstring.new
      doc.hash_flag = 'foo'
      expect(doc.dup.hash_flag).to eq doc.hash_flag
    end

    it "preserves line_range" do
      doc = Docstring.new
      doc.line_range = (1..2)
      expect(doc.dup.line_range).to eq doc.line_range
    end
  end

  describe "reference docstrings" do
    it "allows for construction of docstring with ref object" do
      YARD.parse_string <<-eof
        class A
          # Docstring
          # @return [Boolean]
          def a; end
          # (see #a)
          def b; end
        end
      eof

      object = YARD::Registry.at('A#b')
      expect(object.docstring).to eq 'Docstring'
      expect(object.tags.map(&:tag_name)).to eq ['return']

      YARD::Registry.clear
    end
  end
end
yard-0.9.37/spec/handlers/000077500000000000000000000000001466601756300153215ustar00rootroot00000000000000yard-0.9.37/spec/handlers/alias_handler_spec.rb000066400000000000000000000054021466601756300214470ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}AliasHandler" do
  before(:all) { parse_file :alias_handler_001, __FILE__ }

  it "throws alias into namespace object list" do
    expect(P(:A).aliases[P("A#b")]).to eq :a
  end

  ['c', 'd?', '[]', '[]=', '-@', '%', '*', 'cstrkey', 'cstrmeth'].each do |a|
    it "handles the Ruby 'alias' keyword syntax for method ##{a}" do
      expect(P('A#' + a)).to be_instance_of(CodeObjects::MethodObject)
      expect(P('A#' + a).is_alias?).to be true
    end
  end

  it "handles keywords as the alias name" do
    expect(P('A#for')).to be_instance_of(CodeObjects::MethodObject)
  end

  it "allows ConstantNames to be specified as aliases" do
    expect(P('A#ConstantName')).to be_instance_of(CodeObjects::MethodObject)
  end

  it "creates a new method object for the alias" do
    expect(P("A#b")).to be_instance_of(CodeObjects::MethodObject)
  end

  it "pulls the method into the current class if it's from another one" do
    expect(P(:B).aliases[P("B#q")]).to eq :x
    expect(P(:B).aliases[P("B#r?")]).to eq :x
  end

  it "gracefully fails to pull a method in if the original method cannot be found" do
    expect(P(:B).aliases[P("B#s")]).to eq :to_s
  end

  it "allows complex Ruby expressions after the alias parameters" do
    expect(P(:B).aliases[P("B#t")]).to eq :inspect
  end

  it "shows up in #is_alias? for method" do
    expect(P("B#t").is_alias?).to be true
    expect(P('B#r?').is_alias?).to be true
  end

  it "allows operators and keywords to be specified as symbols" do
    expect(P('B#<<')).to be_instance_of(CodeObjects::MethodObject)
    expect(P('B#for')).to be_instance_of(CodeObjects::MethodObject)
  end

  it "handles keywords in alias names" do
    expect(P('B#do').is_alias?).to be true
    expect(P('B#x2').is_alias?).to be true
    expect(P(:B).aliases[P('B#do')]).to eq :x
    expect(P(:B).aliases[P('B#x2')]).to eq :do
  end

  it "handles quoted symbols" do
    foo = Registry.at('A#foo')
    expect(foo).not_to be nil
    expect(foo.is_alias?).to be true
    expect(Registry.at('A').aliases[foo]).to eq :a
  end

  it "prepends aliases object's docstring to comments" do
    expect(Registry.at('D#a').tag(:return).types).to eq ['Numeric']
    expect(Registry.at('D#b').tag(:return).types).to eq ['String']
    expect(Registry.at('D#b').docstring).to eq "Foo bar"
  end

  it "raises an UndocumentableError if only one parameter is passed" do
    undoc_error "alias_method :q"
  end

  it "raises an UndocumentableError if the parameter is not a Symbol or String" do
    undoc_error "alias_method CONST, Something"
    undoc_error "alias_method variable, ClassName"
    undoc_error "alias_method variable, other_variable"
  end
end
yard-0.9.37/spec/handlers/attribute_handler_spec.rb000066400000000000000000000056221466601756300223650ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}AttributeHandler" do
  before(:all) { parse_file :attribute_handler_001, __FILE__ }

  def read_write(namespace, name, read, write, scope = :instance)
    rname = namespace.to_s + "#" + name.to_s
    wname = namespace.to_s + "#" + name.to_s + "="
    if read
      expect(Registry.at(rname)).to be_instance_of(CodeObjects::MethodObject)
    else
      expect(Registry.at(rname)).to eq nil
    end

    if write
      expect(Registry.at(wname)).to be_kind_of(CodeObjects::MethodObject)
    else
      expect(Registry.at(wname)).to eq nil
    end

    attrs = Registry.at(namespace).attributes[scope][name]
    expect(attrs[:read]).to eq(read ? Registry.at(rname) : nil)
    expect(attrs[:write]).to eq(write ? Registry.at(wname) : nil)
  end

  it "parses attributes inside modules too" do
    expect(Registry.at("A#x=")).not_to eq nil
  end

  it "parses 'attr'" do
    read_write(:B, :a, true, true)
    read_write(:B, :a2, true, false)
    read_write(:B, "a3", true, false)
  end

  it "parses 'attr_reader'" do
    read_write(:B, :b, true, false)
  end

  it "parses 'attr_writer'" do
    read_write(:B, :e, false, true)
  end

  it "parses 'attr_accessor'" do
    read_write(:B, :f, true, true)
  end

  it "parses a list of attributes" do
    read_write(:B, :b, true, false)
    read_write(:B, :c, true, false)
    read_write(:B, :d, true, false)
  end

  it "has a default docstring if one is not supplied" do
    expect(Registry.at("B#f=").docstring).not_to be_empty
  end

  it "sets the correct docstring if one is supplied" do
    expect(Registry.at("B#b").docstring).to eq "Docstring"
    expect(Registry.at("B#c").docstring).to eq "Docstring"
    expect(Registry.at("B#d").docstring).to eq "Docstring"
  end

  it "is able to differentiate between class and instance attributes" do
    expect(P('B').class_attributes[:z][:read].scope).to eq :class
    expect(P('B').instance_attributes[:z][:read].scope).to eq :instance
  end

  it "responds true in method's #is_attribute?" do
    expect(P('B#a').is_attribute?).to be true
    expect(P('B#a=').is_attribute?).to be true
  end

  it "does not return true for #is_explicit? in created methods" do
    Registry.at(:B).meths.each do |meth|
      expect(meth.is_explicit?).to be false
    end
  end

  it "handles attr call with no arguments" do
    expect { StubbedSourceParser.parse_string "attr" }.not_to raise_error
  end

  it "adds existing reader method as part of attr_writer combo" do
    expect(Registry.at('C#foo=').attr_info[:read]).to eq Registry.at('C#foo')
  end

  it "adds existing writer method as part of attr_reader combo" do
    expect(Registry.at('C#foo').attr_info[:write]).to eq Registry.at('C#foo=')
  end

  it "maintains visibility for attr_reader" do
    expect(Registry.at('D#parser').visibility).to eq :protected
  end
end
yard-0.9.37/spec/handlers/base_spec.rb000066400000000000000000000153761466601756300176060ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

include Parser

RSpec.describe YARD::Handlers::Base do
  describe "#handles and inheritance" do
    before do
      allow(Handlers::Base).to receive(:inherited)
    end

    it "keeps track of subclasses" do
      expect(Handlers::Base).to receive(:inherited).once
      class TestHandler < Handlers::Base; end
    end

    it "raises NotImplementedError if process is called on a class with no #process" do
      class TestNotImplementedHandler < Handlers::Base
      end

      expect { TestNotImplementedHandler.new(0, 0).process }.to raise_error(NotImplementedError)
    end

    it "allows multiple handles arguments" do
      expect(Handlers::Base).to receive(:inherited).once
      class TestHandler1 < Handlers::Base
        handles :a, :b, :c
      end
      expect(TestHandler1.handlers).to eq [:a, :b, :c]
    end

    it "allows multiple handles calls" do
      expect(Handlers::Base).to receive(:inherited).once
      class TestHandler2 < Handlers::Base
        handles :a
        handles :b
        handles :c
      end
      expect(TestHandler2.handlers).to eq [:a, :b, :c]
    end
  end

  describe "#abort! (and HandlerAborted)" do
    it "allows HandlerAborted to be raised" do
      class AbortHandler1 < Handlers::Ruby::Base
        process { abort! }
      end
      expect { AbortHandler1.new(nil, nil).process }.to raise_error(HandlerAborted)
    end
  end

  describe "transitive tags" do
    it "adds transitive tags to children" do
      Registry.clear
      YARD.parse_string <<-eof
        # @since 1.0
        # @author Foo
        class A
          def foo; end
          # @since 1.1
          def bar; end
        end
      eof
      expect(Registry.at('A').tag(:since).text).to eq "1.0"
      expect(Registry.at('A#foo').tag(:since).text).to eq "1.0"
      expect(Registry.at('A#bar').tag(:since).text).to eq "1.1"
      expect(Registry.at('A#bar').tag(:author)).to be nil
    end
  end

  describe "sharing global state" do
    it "allows globals to share global state among handlers" do
      class GlobalStateHandler1 < Handlers::Ruby::Base
        class << self; attr_accessor :state end
        handles :class
        process { self.class.state = globals.foo; globals.foo = :bar }
      end

      class GlobalStateHandler2 < Handlers::Ruby::Base
        class << self; attr_accessor :state end
        handles :def
        process { self.class.state = globals.foo }
      end

      2.times do
        YARD.parse_string 'class Foo; end; def foo; end'
        expect(GlobalStateHandler1.state).to eq nil
        expect(GlobalStateHandler2.state).to eq :bar
      end
    end
  end if HAVE_RIPPER

  describe "#push_state" do
    def process(klass)
      state = OpenStruct.new(:namespace => "ROOT", :scope => :instance, :owner => "ROOT")
      klass.new(state, nil).process
    end

    it "pushes and return all old state info after block" do
      class PushStateHandler1 < Handlers::Base
        include RSpec::Matchers
        RSpec::Expectations::Syntax.enable_expect(self)

        def process
          push_state(:namespace => "FOO", :scope => :class, :owner => "BAR") do
            expect(namespace).to eq "FOO"
            expect(scope).to eq :class
            expect(owner).to eq "BAR"
          end
          expect(namespace).to eq "ROOT"
          expect(owner).to eq "ROOT"
          expect(scope).to eq :instance
        end
      end
      process PushStateHandler1
    end

    it "allows owner to be pushed individually" do
      class PushStateHandler2 < Handlers::Base
        include RSpec::Matchers
        RSpec::Expectations::Syntax.enable_expect(self)

        def process
          push_state(:owner => "BAR") do
            expect(namespace).to eq "ROOT"
            expect(scope).to eq :instance
            expect(owner).to eq "BAR"
          end
          expect(owner).to eq "ROOT"
        end
      end
      process PushStateHandler2
    end

    it "allows scope to be pushed individually" do
      class PushStateHandler3 < Handlers::Base
        include RSpec::Matchers
        RSpec::Expectations::Syntax.enable_expect(self)

        def process
          push_state(:scope => :foo) do
            expect(namespace).to eq "ROOT"
            expect(scope).to eq :foo
            expect(owner).to eq "ROOT"
          end
          expect(scope).to eq :instance
        end
      end
      process PushStateHandler3
    end
  end

  describe ".in_file" do
    def parse(filename, parser_type, src = "class A; end")
      parser = Parser::SourceParser.new(parser_type)
      parser.instance_variable_set("@file", filename)
      parser.parse(StringIO.new(src))
    end

    def create_handler(stmts, parser_type)
      $handler_counter ||= 0
      sklass = parser_type == :ruby ? "Base" : "Legacy::Base"
      instance_eval(<<-eof, __FILE__, __LINE__ + 1)
        class ::InFileHandler#{$handler_counter += 1} < Handlers::Ruby::#{sklass}
          handles(/^class/)
          #{stmts}
          def process; MethodObject.new(:root, :FOO) end
        end
      eof
    end

    def test_handler(file, stmts, creates = true, parser_type = :ruby)
      Registry.clear
      expect(Registry.at('#FOO')).to be nil
      create_handler(stmts, parser_type)
      parse(file, parser_type)
      expect(Registry.at('#FOO')).send(creates ? :not_to : :to, be_nil)
      Handlers::Base.subclasses.delete_if {|k, _v| k.to_s =~ /^InFileHandler/ }
    end

    [:ruby, :ruby18].each do |parser_type|
      next if parser_type == :ruby && LEGACY_PARSER
      describe "Parser type = #{parser_type.inspect}" do
        it "allows handler to be specific to a file" do
          test_handler 'file_a.rb', 'in_file "file_a.rb"', true, parser_type
        end

        it "ignores handler if filename does not match" do
          test_handler 'file_b.rb', 'in_file "file_a.rb"', false, parser_type
        end

        it "only tests filename part when given a String" do
          test_handler '/path/to/file_a.rb', 'in_file "/to/file_a.rb"', false, parser_type
        end

        it "tests exact match for entire String" do
          test_handler 'file_a.rb', 'in_file "file"', false, parser_type
        end

        it "allows a Regexp as argument and test against full path" do
          test_handler 'file_a.rbx', 'in_file(/\.rbx$/)', true, parser_type
          test_handler '/path/to/file_a.rbx', 'in_file(/\/to\/file_/)', true, parser_type
          test_handler '/path/to/file_a.rbx', 'in_file(/^\/path/)', true, parser_type
        end

        it "allows multiple in_file declarations" do
          stmts = 'in_file "x"; in_file(/y/); in_file "foo.rb"'
          test_handler 'foo.rb', stmts, true, parser_type
          test_handler 'xyzzy.rb', stmts, true, parser_type
          test_handler 'x', stmts, true, parser_type
        end
      end
    end
  end
end
yard-0.9.37/spec/handlers/c/000077500000000000000000000000001466601756300155435ustar00rootroot00000000000000yard-0.9.37/spec/handlers/c/alias_handler_spec.rb000066400000000000000000000017651466601756300217010ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::AliasHandler do
  it "allows defining of aliases (rb_define_alias)" do
    parse <<-eof
      /* FOO */
      VALUE foo(VALUE x) { int value = x; }
      void Init_Foo() {
        rb_cFoo = rb_define_class("Foo", rb_cObject);
        rb_define_method(rb_cFoo, "foo", foo, 1);
        rb_define_alias(rb_cFoo, "bar", "foo");
      }
    eof

    expect(Registry.at('Foo#bar')).to be_is_alias
    expect(Registry.at('Foo#bar').docstring).to eq 'FOO'
  end

  it "allows defining of aliases (rb_define_alias) of attributes" do
    parse <<-eof
      /* FOO */
      VALUE foo(VALUE x) { int value = x; }
      void Init_Foo() {
        rb_cFoo = rb_define_class("Foo", rb_cObject);
        rb_define_attr(rb_cFoo, "foo", 1, 0);
        rb_define_alias(rb_cFoo, "foo?", "foo");
      }
    eof

    expect(Registry.at('Foo#foo')).to be_reader
    expect(Registry.at('Foo#foo?')).to be_is_alias
  end
end
yard-0.9.37/spec/handlers/c/attribute_handler_spec.rb000066400000000000000000000022441466601756300226040ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::AttributeHandler do
  def run(read, write, commented = nil)
    parse <<-eof
      /* FOO */
      VALUE foo(VALUE x) { int value = x; }
      void Init_Foo() {
        rb_cFoo = rb_define_class("Foo", rb_cObject);
        #{commented ? '/*' : ''}
          rb_define_attr(rb_cFoo, "foo", #{read}, #{write});
        #{commented ? '*/' : ''}
      }
    eof
  end

  it "handles readonly attribute (rb_define_attr)" do
    run(1, 0)
    expect(Registry.at('Foo#foo')).to be_reader
    expect(Registry.at('Foo#foo=')).to be nil
  end

  it "handles writeonly attribute (rb_define_attr)" do
    run(0, 1)
    expect(Registry.at('Foo#foo')).to be nil
    expect(Registry.at('Foo#foo=')).to be_writer
  end

  it "handles readwrite attribute (rb_define_attr)" do
    run(1, 1)
    expect(Registry.at('Foo#foo')).to be_reader
    expect(Registry.at('Foo#foo=')).to be_writer
  end

  it "handles commented writeonly attribute (/* rb_define_attr */)" do
    run(1, 1, true)
    expect(Registry.at('Foo#foo')).to be_reader
    expect(Registry.at('Foo#foo=')).to be_writer
  end
end
yard-0.9.37/spec/handlers/c/class_handler_spec.rb000066400000000000000000000046141466601756300217110ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::ClassHandler do
  it "registers classes" do
    parse_init 'cFoo = rb_define_class("Foo", rb_cObject);'
    expect(Registry.at('Foo').type).to eq :class
  end

  it "registers classes under namespaces" do
    parse_init <<-EOF
      cBar = rb_define_class("Bar", rb_cObject);
      cFoo = rb_define_class_under( cBar, "Foo", rb_cBaz );
    EOF
    expect(Registry.at('Bar::Foo').type).to eq :class
    expect(Registry.at('Bar::Foo').superclass.path).to eq 'Baz'
  end

  it "remembers symbol defined with class" do
    parse_init(<<-eof)
      cXYZ = rb_define_class("Foo", rb_cObject);
      rb_define_method(cXYZ, "bar", bar, 0);
    eof
    expect(Registry.at('Foo').type).to eq :class
    expect(Registry.at('Foo#bar')).not_to be nil
  end

  it "looks up superclass symbol name" do
    parse_init(<<-eof)
      cXYZ = rb_define_class("Foo", rb_cObject);
      cBar = rb_define_class("Bar", cXYZ);
    eof
    expect(Registry.at('Bar').superclass).to eq Registry.at('Foo')
  end

  it "uses superclass symbol name as proxy if not found" do
    parse_init(<<-eof)
      // cXYZ = rb_define_class("Foo", rb_cObject);
      cBar = rb_define_class("Bar", cXYZ);
    eof
    expect(Registry.at('Bar').superclass).to eq P('XYZ')
  end

  it "does not associate declaration comments as class docstring" do
    parse_init(<<-eof)
      /* Docstring! */
      cFoo = rb_define_class("Foo", cObject);
    eof
    expect(Registry.at('Foo').docstring).to be_blank
  end

  it "associates a file with the declaration" do
    parse_init(<<-eof)
      cFoo = rb_define_class("Foo", cObject);
    eof
    expect(Registry.at('Foo').file).to eq '(stdin)'
    expect(Registry.at('Foo').line).to eq 2
  end

  it "properly handles Proxy superclasses" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      cBar = rb_define_class_under(mFoo, "Bar", rb_cBar);
    eof
    expect(Registry.at('Foo::Bar').type).to eq :class
    expect(Registry.at('Foo::Bar').superclass).to eq P('Bar')
    expect(Registry.at('Foo::Bar').superclass.type).to eq :class
  end

  it "resolves namespace variable names across multiple files" do
    parse_multi_file_init(
      'cBar = rb_define_class_under(cFoo, "Bar", rb_cObject);',
      'cFoo = rb_define_class("Foo", rb_cObject);'
    )

    expect(Registry.at('Foo::Bar').type).to eq :class
  end
end
yard-0.9.37/spec/handlers/c/constant_handler_spec.rb000066400000000000000000000042111466601756300224260ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::ConstantHandler do
  it "registers constants" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_const(mFoo, "FOO", ID2SYM(100));
      rb_define_global_const("BAR", ID2SYM(100));
    eof
    expect(Registry.at('Foo::FOO').type).to eq :constant
    expect(Registry.at('BAR').type).to eq :constant
  end

  it "looks for override comments" do
    parse <<-eof
      /* Document-const: FOO
       * Document-const: Foo::BAR
       * Foo bar!
       */

      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_const(mFoo, "FOO", ID2SYM(100));
        rb_define_const(mFoo, "BAR", ID2SYM(101));
      }
    eof
    foo = Registry.at('Foo::FOO')
    expect(foo.type).to eq :constant
    expect(foo.docstring).to eq 'Foo bar!'
    expect(foo.value).to eq 'ID2SYM(100)'
    expect(foo.file).to eq '(stdin)'
    expect(foo.line).to eq 8
    bar = Registry.at('Foo::BAR')
    expect(bar.type).to eq :constant
    expect(bar.docstring).to eq 'Foo bar!'
    expect(bar.file).to eq '(stdin)'
    expect(bar.line).to eq 9
    expect(bar.value).to eq 'ID2SYM(101)'
  end

  it "uses comment attached to declaration as fallback" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_const(mFoo, "FOO", ID2SYM(100)); // foobar!
    eof
    foo = Registry.at('Foo::FOO')
    expect(foo.value).to eq 'ID2SYM(100)'
    expect(foo.docstring).to eq 'foobar!'
  end

  it "allows the form VALUE: DOCSTRING to document value" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_const(mFoo, "FOO", ID2SYM(100)); // 100: foobar!
    eof
    foo = Registry.at('Foo::FOO')
    expect(foo.value).to eq '100'
    expect(foo.docstring).to eq 'foobar!'
  end

  it "allows escaping of backslashes in VALUE: DOCSTRING syntax" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_const(mFoo, "FOO", ID2SYM(100)); // 100\\:x\\:y: foobar:x!
    eof
    foo = Registry.at('Foo::FOO')
    expect(foo.value).to eq '100:x:y'
    expect(foo.docstring).to eq 'foobar:x!'
  end
end
yard-0.9.37/spec/handlers/c/init_handler_spec.rb000066400000000000000000000023151466601756300215430ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::InitHandler do
  it "adds documentation in Init_ClassName() to ClassName" do
    parse(<<-eof)
      // Bar!
      void Init_A() {
        rb_cA = rb_define_class("A", rb_cObject);
      }
    eof
    expect(Registry.at('A').docstring).to eq 'Bar!'
  end

  it "does not add documentation if ClassName is not created in Init" do
    parse(<<-eof)
      // Bar!
      void Init_A() {
      }
    eof
    expect(Registry.at('A')).to be nil
  end

  it "does not overwrite override comment" do
    parse(<<-eof)
      /* Document-class: A
       * Foo!
       */

      // Bar!
      static SWIGEXPORT void Init_A() {
        rb_cA = rb_define_class("A", rb_cObject);
      }
    eof
    expect(Registry.at('A').docstring).to eq 'Foo!'
  end

  it "checks non-Init methods for declarations too" do
    parse(<<-eof)
      void foo(int x, int y, char *name) {
        rb_cB = rb_define_class("B", rb_cObject);
        rb_define_method(rb_cB, "foo", foo_impl, 0);
      }
    eof
    expect(Registry.at('B')).to be_a(CodeObjects::ClassObject)
    expect(Registry.at('B#foo')).to be_a(CodeObjects::MethodObject)
  end
end
yard-0.9.37/spec/handlers/c/method_handler_spec.rb000066400000000000000000000261241466601756300220640ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::MethodHandler do
  it "registers methods" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_method(mFoo, "bar", bar, 0);
    eof
    expect(Registry.at('Foo#bar')).not_to be nil
    expect(Registry.at('Foo#bar').visibility).to eq :public
  end

  it "registers private methods" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_private_method(mFoo, "bar", bar, 0);
    eof
    expect(Registry.at('Foo#bar')).not_to be nil
    expect(Registry.at('Foo#bar').visibility).to eq :private
  end

  it "registers singleton methods" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_singleton_method(mFoo, "bar", bar, 0);
    eof
    expect(Registry.at('Foo.bar')).not_to be nil
    expect(Registry.at('Foo.bar').visibility).to eq :public
  end

  it "registers module functions" do
    parse <<-eof
      /* DOCSTRING
       * @return [String] foo!
      */
      static VALUE bar(VALUE self) { x(); y(); z(); }

      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_module_function(mFoo, "bar", bar, 0);
      }
    eof
    bar_c = Registry.at('Foo.bar')
    bar_i = Registry.at('Foo#bar')
    expect(bar_c).to be_module_function
    expect(bar_c.visibility).to eq :public
    expect(bar_c.docstring).to eq "DOCSTRING"
    expect(bar_c.tag(:return).object).to eq bar_c
    expect(bar_c.source).to eq "static VALUE bar(VALUE self) { x(); y(); z(); }"
    expect(bar_i).not_to be_module_function
    expect(bar_i.visibility).to eq :private
    expect(bar_i.docstring).to eq "DOCSTRING"
    expect(bar_i.tag(:return).object).to eq bar_i
    expect(bar_i.source).to eq bar_c.source
  end

  it "registers global functions into Kernel" do
    parse_init 'rb_define_global_function("bar", bar, 0);'
    expect(Registry.at('Kernel#bar')).not_to be nil
  end

  it "looks for symbol containing method source" do
    parse <<-eof
      static VALUE foo(VALUE self) { x(); y(); z(); }
      VALUE bar() { a(); b(); c(); }
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo", foo, 0);
        rb_define_method(mFoo, "bar", bar, 0);
      }
    eof
    foo = Registry.at('Foo#foo')
    bar = Registry.at('Foo#bar')
    expect(foo.source).to eq "static VALUE foo(VALUE self) { x(); y(); z(); }"
    expect(foo.file).to eq '(stdin)'
    expect(foo.line).to eq 1
    expect(bar.source).to eq "VALUE bar() { a(); b(); c(); }"
    expect(bar.file).to eq '(stdin)'
    expect(bar.line).to eq 2
  end

  it "finds docstrings attached to method symbols" do
    parse <<-eof
      /* DOCSTRING */
      static VALUE foo(VALUE self) { x(); y(); z(); }
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo", foo, 0);
      }
    eof
    foo = Registry.at('Foo#foo')
    expect(foo.docstring).to eq 'DOCSTRING'
  end

  it "uses declaration comments as docstring if there are no others" do
    parse <<-eof
      static VALUE foo(VALUE self) { x(); y(); z(); }
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        /* DOCSTRING */
        rb_define_method(mFoo, "foo", foo, 0);
        // DOCSTRING!
        rb_define_method(mFoo, "bar", bar, 0);
      }
    eof
    foo = Registry.at('Foo#foo')
    expect(foo.docstring).to eq 'DOCSTRING'
    bar = Registry.at('Foo#bar')
    expect(bar.docstring).to eq 'DOCSTRING!'
  end

  it "looks for symbols in other file" do
    other = <<-eof
      /* DOCSTRING! */
      static VALUE foo() { x(); }
    eof
    expect(File).to receive(:read).with('other.c').and_return(other)
    parse <<-eof
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo", foo, 0); // in other.c
      }
    eof
    foo = Registry.at('Foo#foo')
    expect(foo.docstring).to eq 'DOCSTRING!'
    expect(foo.file).to eq 'other.c'
    expect(foo.line).to eq 2
    expect(foo.source).to eq 'static VALUE foo() { x(); }'
  end

  it "allows extra file to include /'s and other filename characters" do
    expect(File).to receive(:read).at_least(1).times.with('ext/a-file.c').and_return(<<-eof)
      /* FOO */
      VALUE foo(VALUE x) { int value = x; }

      /* BAR */
      VALUE bar(VALUE x) { int value = x; }
    eof
    parse_init <<-eof
      rb_define_method(rb_cFoo, "foo", foo, 1); /* in ext/a-file.c */
      rb_define_global_function("bar", bar, 1); /* in ext/a-file.c */
    eof
    expect(Registry.at('Foo#foo').docstring).to eq 'FOO'
    expect(Registry.at('Kernel#bar').docstring).to eq 'BAR'
  end

  it "warns if other file can't be found" do
    expect(log).to receive(:warn).with(/Missing source file `other.c' when parsing Foo#foo/)
    parse <<-eof
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo", foo, 0); // in other.c
      }
    eof
  end

  it "looks at override comments for docstring" do
    parse <<-eof
      /* Document-method: Foo::foo
       * Document-method: new
       * Document-method: Foo::Bar#baz
       * Foo bar!
       */

      // init comments
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo", foo, 0);
        rb_define_method(mFoo, "initialize", foo, 0);
        mBar = rb_define_module_under(mFoo, "Bar");
        rb_define_method(mBar, "baz", foo, 0);
      }
    eof
    expect(Registry.at('Foo#foo').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo#initialize').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo::Bar#baz').docstring).to eq 'Foo bar!'
  end

  it "looks at overrides in other files" do
    other = <<-eof
      /* Document-method: Foo::foo
       * Document-method: new
       * Document-method: Foo::Bar#baz
       * Foo bar!
       */
    eof
    expect(File).to receive(:read).with('foo/bar/other.c').and_return(other)
    src = <<-eof
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo", foo, 0); // in foo/bar/other.c
        rb_define_method(mFoo, "initialize", foo, 0); // in foo/bar/other.c
        mBar = rb_define_module_under(mFoo, "Bar"); // in foo/bar/other.c
        rb_define_method(mBar, "baz", foo, 0); // in foo/bar/other.c
      }
    eof
    parse(src, 'foo/bar/baz/init.c')
    expect(Registry.at('Foo#foo').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo#initialize').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo::Bar#baz').docstring).to eq 'Foo bar!'
  end

  it "adds return tag on methods ending in '?'" do
    parse <<-eof
      /* DOCSTRING */
      static VALUE foo(VALUE self) { x(); y(); z(); }
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo?", foo, 0);
      }
    eof
    foo = Registry.at('Foo#foo?')
    expect(foo.docstring).to eq 'DOCSTRING'
    expect(foo.tag(:return).types).to eq ['Boolean']
    expect(foo.tags(:return).size).to eq 1
  end

  it "does not add return tag if return tags exist" do
    parse <<-eof
      // @return [String] foo
      static VALUE foo(VALUE self) { x(); y(); z(); }
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "foo?", foo, 0);
      }
    eof
    foo = Registry.at('Foo#foo?')
    expect(foo.tag(:return).types).to eq ['String']
    expect(foo.tags(:return).size).to eq 1
  end

  it "handles casted method names" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_define_method(mFoo, "bar", (METHOD)bar, 0);
      rb_define_global_function("baz", (METHOD)baz, 0);
    eof
    expect(Registry.at('Foo#bar')).not_to be nil
    expect(Registry.at('Kernel#baz')).not_to be nil
  end

  it "extracts at regular method parameters from C function signatures" do
    parse <<-eof
      static VALUE noargs_func(VALUE self) { return Qnil; }
      static VALUE twoargs_func(VALUE self, VALUE a, VALUE b) { return a; }
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "noargs", noargs_func, 0);
        rb_define_method(mFoo, "twoargs", twoargs_func, 2);
      }
    eof
    expect(Registry.at('Foo#noargs').parameters).to be_empty
    expect(Registry.at('Foo#twoargs').parameters).to eq [['a', nil], ['b', nil]]
  end

  it "extracts at varargs method parameters from C function signatures" do
    parse <<-eof
      static VALUE varargs_func(int argc, VALUE *argv, VALUE self) { return self; }
      /* let's see if parser is robust in the face of strange spacing */
      static VALUE varargs_func2(	int 	argc ,	VALUE
	* 	 argv  ,VALUE  self	)

      {return self;}
      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        rb_define_method(mFoo, "varargs", varargs_func, -1);
        rb_define_method(	mFoo	,"varargs2",varargs_func2		,-1);
      }
    eof
    expect(Registry.at('Foo#varargs').parameters).to eq [['*args', nil]]
    expect(Registry.at('Foo#varargs2').parameters).to eq [['*args', nil]]
  end

  it "is not too strict or too loose about matching override comments to methods" do
    parse <<-eof
      /* Document-method: Foo::foo
       * Document-method: new
       * Document-method: Foo::Bar#baz
       * Foo bar!
       */

      void Init_Foo() {
        mFoo = rb_define_module("Foo");
        mBar = rb_define_module_under(mFoo, "Bar");

        rb_define_method(mFoo, "foo", foo, 0);
        rb_define_singleton_method(mFoo, "foo", foo, 0);
        rb_define_method(mBar, "foo", foo, 0);
        rb_define_singleton_method(mBar, "foo", foo, 0);

        rb_define_method(mFoo, "initialize", foo, 0);
        rb_define_method(mBar, "initialize", foo, 0);

        rb_define_method(mFoo, "baz", foo, 0);
        rb_define_singleton_method(mFoo, "baz", foo, 0);
        rb_define_method(mBar, "baz", foo, 0);
        rb_define_singleton_method(mBar, "baz", foo, 0);
      }
    eof
    expect(Registry.at('Foo#foo').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo.foo').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo::Bar#foo').docstring).to be_empty
    expect(Registry.at('Foo::Bar.foo').docstring).to be_empty
    expect(Registry.at('Foo#initialize').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo::Bar#initialize').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo#baz').docstring).to be_empty
    expect(Registry.at('Foo.baz').docstring).to be_empty
    expect(Registry.at('Foo::Bar#baz').docstring).to eq 'Foo bar!'
    expect(Registry.at('Foo::Bar.baz').docstring).to be_empty
  end

  it "recognizes core Ruby classes and modules provided by ruby.h" do
    parse_init <<-eof
      rb_define_method(rb_cFixnum, "popcount", fix_popcount, 0);
      rb_define_private_method(rb_mKernel, "pp", obj_pp, 0);
      rb_define_method(rb_mEnumerable, "to_hash", enum_to_hash, 0);
    eof
    expect(Registry.at('Fixnum').type).to eq :class
    expect(Registry.at('Fixnum#popcount').type).to eq :method
    expect(Registry.at('Object').type).to eq :class
    # Methods defined on Kernel are treated as if they were defined on Object
    expect(Registry.at('Object#pp').type).to eq :method
    expect(Registry.at('Enumerable').type).to eq :module
    expect(Registry.at('Enumerable#to_hash').type).to eq :method
  end
end
yard-0.9.37/spec/handlers/c/mixin_handler_spec.rb000066400000000000000000000023171466601756300217260ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::MixinHandler do
  it "adds includes to modules or classes" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      cBar = rb_define_class("Bar", rb_cObject);
      mBaz = rb_define_module("Baz");
      rb_include_module(cBar, mFoo);
      rb_include_module(mBaz, mFoo);
    eof
    foo = Registry.at('Foo')
    bar = Registry.at('Bar')
    baz = Registry.at('Baz')
    expect(bar.mixins(:instance)).to eq [foo]
    expect(baz.mixins(:instance)).to eq [foo]
  end

  it "adds include as proxy if symbol lookup fails" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      rb_include_module(mFoo, mXYZ);
    eof
    foo = Registry.at('Foo')
    expect(foo.mixins(:instance)).to eq [P('XYZ')]
  end

  it "fails if mixin variable cannot be detected" do
    with_parser(:c) do
      undoc_error <<-eof
        void Init_Foo() {
          VALUE noprefix;

          mFoo = rb_define_module("Foo");
          // YARD doesn't understand this
          noprefix = rb_const_get(rb_cObject, rb_intern("Observable"));

          rb_include_module(mFoo, noprefix);
        }
      eof
    end
  end
end
yard-0.9.37/spec/handlers/c/module_handler_spec.rb000066400000000000000000000037531466601756300220740ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::ClassHandler do
  it "registers modules" do
    parse_init 'mFoo = rb_define_module("Foo");'
    expect(Registry.at('Foo').type).to eq :module
  end

  it "registers classes under namespaces" do
    parse_init <<-EOF
      mBar = rb_define_module("Bar");
      mFoo = rb_define_module_under(mBar, "Foo");
    EOF
    expect(Registry.at('Bar::Foo').type).to eq :module
  end

  it "remembers symbol defined with class" do
    parse_init(<<-eof)
      cXYZ = rb_define_module("Foo");
      rb_define_method(cXYZ, "bar", bar, 0);
    eof
    expect(Registry.at('Foo').type).to eq :module
    expect(Registry.at('Foo#bar')).not_to be nil
  end

  it "does not associate declaration comments as module docstring" do
    parse_init(<<-eof)
      /* Docstring! */
      mFoo = rb_define_module("Foo");
    eof
    expect(Registry.at('Foo').docstring).to be_blank
  end

  it "associates a file with the declaration" do
    parse_init(<<-eof)
      mFoo = rb_define_module("Foo");
    eof
    expect(Registry.at('Foo').file).to eq '(stdin)'
    expect(Registry.at('Foo').line).to eq 2
  end

  it "resolves namespace variable names across multiple files" do
    parse_multi_file_init(
      'mBar = rb_define_module_under(mFoo, "Bar");',
      'mFoo = rb_define_module("Foo");'
    )

    expect(Registry.at('Foo::Bar').type).to eq :module
  end

  it "raises undoc error if a class is defined under a namespace that cannot be resolved" do
    with_parser(:c) do
      undoc_error <<-eof
        void Init_Foo() {
          mFoo = rb_define_class_under(invalid, "Foo", rb_cObject);
        }
      eof
    end
  end unless ENV['LEGACY']

  it "raises undoc error if a module is defined under a namespace that cannot be resolved" do
    with_parser(:c) do
      undoc_error <<-eof
        void Init_Foo() {
          mFoo = rb_define_module_under(invalid, "Foo");
        }
      eof
    end
  end unless ENV['LEGACY']
end
yard-0.9.37/spec/handlers/c/override_comment_handler_spec.rb000066400000000000000000000024151466601756300241420ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::OverrideCommentHandler do
  [:class, :module].each do |type|
    it "handles Document-#{type}" do
      parse(<<-eof)
        void something;
        /* Document-#{type}: A
         * Foo bar baz
         */
        void
      eof
      expect(Registry.at('A').type).to eq type
      expect(Registry.at('A').docstring).to eq 'Foo bar baz'
      expect(Registry.at('A').file).to eq '(stdin)'
      expect(Registry.at('A').line).to eq 2
    end
  end

  it "handles multiple class/module combinations" do
    parse(<<-eof)
      /* Document-class: A
       * Document-class: B
       * Document-module: C
       * Foo bar baz
       */
    eof
    expect(Registry.at('A').docstring).to eq 'Foo bar baz'
    expect(Registry.at('B').docstring).to eq 'Foo bar baz'
    expect(Registry.at('C').docstring).to eq 'Foo bar baz'
    expect(Registry.at('C').type).to eq :module
  end

  it "handles Document-class with inheritance" do
    parse(<<-eof)
      /* Document-class: A < B
       * Foo bar baz
       */
      void
    eof
    obj = Registry.at('A')
    expect(obj.type).to eq :class
    expect(obj.docstring).to eq 'Foo bar baz'
    expect(obj.superclass).to eq P('B')
  end
end
yard-0.9.37/spec/handlers/c/path_handler_spec.rb000066400000000000000000000023511466601756300215340ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Handlers::C::PathHandler do
  it "tracks variable names defined under namespaces" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
      rb_define_method(cBar, "foo", foo, 1);
    eof
    expect(Registry.at('Foo::Bar')).not_to be nil
    expect(Registry.at('Foo::Bar#foo')).not_to be nil
  end

  it "tracks variable names defined under namespaces" do
    parse_init <<-eof
      mFoo = rb_define_module("Foo");
      cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
      mBaz = rb_define_module_under(cBar, "Baz");
      rb_define_method(mBaz, "foo", foo, 1);
    eof
    expect(Registry.at('Foo::Bar::Baz')).not_to be nil
    expect(Registry.at('Foo::Bar::Baz#foo')).not_to be nil
  end

  it "handles rb_path2class() calls" do
    parse_init <<-eof
      somePath = rb_path2class("Foo::Bar::Baz")
      mFoo = rb_define_module("Foo");
      cBar = rb_define_class_under(mFoo, "Bar", rb_cObject);
      mBaz = rb_define_module_under(cBar, "Baz");
      rb_define_method(somePath, "foo", foo, 1);
    eof
    expect(Registry.at('Foo::Bar::Baz#foo')).not_to be nil
  end
end
yard-0.9.37/spec/handlers/c/spec_helper.rb000066400000000000000000000012121466601756300203550ustar00rootroot00000000000000# frozen_string_literal: true

def parse(src, file = '(stdin)')
  YARD::Registry.clear
  parser = YARD::Parser::SourceParser.new(:c)
  parser.file = file
  parser.parse(StringIO.new(src))
end

def parse_init(src)
  YARD::Registry.clear
  YARD.parse_string("void Init_Foo() {\n#{src}\n}", :c)
end

def parse_multi_file_init(*srcs)
  YARD::Registry.clear
  srcs = srcs.map {|src| StringIO.new("void Init_Foo() {\n#{src}\n}") }
  orig_type = YARD::Parser::SourceParser.parser_type
  YARD::Parser::SourceParser.parser_type = :c
  YARD::Parser::OrderedParser.new(OpenStruct.new, srcs).parse
ensure
  YARD::Parser::SourceParser.parser_type = orig_type
end
yard-0.9.37/spec/handlers/c/struct_handler_spec.rb000066400000000000000000000007451466601756300221310ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Handlers::C::StructHandler do
  after { Registry.clear }

  it "handles Struct class definitions" do
    parse_init <<-eof
      rb_cRange = rb_struct_define_without_accessor(
          "Range", rb_cFoo, range_alloc,
          "begin", "end", "excl", NULL);
    eof
    expect(Registry.at('Range').type).to eq :class
    expect(Registry.at('Range').superclass).to eq P(:Foo)
  end
end
yard-0.9.37/spec/handlers/class_condition_handler_spec.rb000066400000000000000000000046251466601756300235370ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassConditionHandler" do
  before(:all) { parse_file :class_condition_handler_001, __FILE__ }

  def verify_method(*names)
    names.each {|name| expect(Registry.at("A##{name}")).not_to be nil }
    names.each {|name| expect(Registry.at("A##{name}not")).to be nil }
  end

  def no_undoc_error(code)
    expect { StubbedSourceParser.parse_string(code) }.not_to raise_error
  end

  it "parses all unless blocks for complex conditions" do
    verify_method :g
  end

  it "does not parse conditionals inside methods" do
    verify_method :h
  end

  it "only parses then block if condition is literal value `true`" do
    verify_method :p
  end

  it "only parses then block if condition is literal integer != 0" do
    verify_method :o
  end

  it "inverts block to parse for literal condition if it's an unless block" do
    verify_method :e
  end

  it "handles conditions such as 'defined? VALUE'" do
    verify_method :j, :k
  end

  it "parses all if/elsif blocks for complex conditions" do
    verify_method :a, :b, :c, :d
  end

  it "parses else block if condition is literal value `false`" do
    verify_method :q
  end

  it "only parses else block if condition is literal integer == 0" do
    verify_method :n
  end

  it "maintains visibility and scope state inside condition" do
    expect(Registry.at('A#m').visibility).to eq :private
    expect(Registry.at('A#mnot').visibility).to eq :private
  end

  it "does not fail on complex conditions" do
    expect(log).not_to receive(:warn)
    expect(log).not_to receive(:error)
    no_undoc_error "if defined?(A) && defined?(B); puts 'hi' end"
    no_undoc_error(<<-eof)
      (<<-TEST) unless defined?(ABCD_MODEL_TEST)
        'String'
      TEST
    eof
    no_undoc_error "if caller.none? { |l| l =~ %r{lib/rails/generators\\.rb:(\\d+):in `lookup!'$} }; end"
  end

  it "only parses identifiers or namespaces from defined? expressions" do
    module A
      @@value = nil
      def self.b(value) @@value = value end
      def self.value; @@value end
    end

    YARD.parse_string <<-eof
      if defined? A.b(42).to_i
        class Foo; end
      else
        class Bar; end
      end
    eof
    expect(A.value).to be_nil
    expect(YARD::Registry.at('Foo')).not_to be_nil
    expect(YARD::Registry.at('Bar')).not_to be_nil
  end
end
yard-0.9.37/spec/handlers/class_handler_spec.rb000066400000000000000000000213751466601756300214720ustar00rootroot00000000000000# frozen_string_literal: true
require File.expand_path(File.dirname(__FILE__) + '/spec_helper')

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassHandler" do
  before(:all) { parse_file :class_handler_001, __FILE__ }

  it "parses a class block with docstring" do
    expect(P("A").docstring).to eq "Docstring"
  end

  it "handles complex class names" do
    expect(P("A::B::C")).not_to eq nil
  end

  it "handles the subclassing syntax" do
    expect(P("A::B::C").superclass).to eq P(:String)
    expect(P("A::X").superclass).to eq Registry.at("A::B::C")
  end

  it "interprets class << self as a class level block" do
    expect(P("A.classmethod1")).not_to eq nil
  end

  it "interprets class << ClassName as a class level block in ClassName's namespace" do
    expect(P("A::B::C.Hello")).to be_instance_of(CodeObjects::MethodObject)
  end

  it "makes visibility public when parsing a block" do
    expect(P("A::B::C#method1").visibility).to eq :public
  end

  it "sets superclass type to :class if it is a Proxy" do
    expect(P("A::B::C").superclass.type).to eq :class
  end

  it "looks for a superclass before creating the class if it shares the same name" do
    expect(P('B::A').superclass).to eq P('A')
  end

  it "handles class definitions in the form ::ClassName" do
    expect(Registry.at("MyRootClass")).not_to be nil
  end

  it "handles superclass as a constant-style method (camping style < R /path/)" do
    expect(P('Test1').superclass).to eq P(:R)
    expect(P('Test2').superclass).to eq P(:R)
    expect(P('Test6').superclass).to eq P(:NotDelegateClass)
  end

  it "handles superclass with OStruct.new or Struct.new syntax (superclass should be OStruct/Struct)" do
    expect(P('Test3').superclass).to eq P(:Struct)
    expect(P('Test4').superclass).to eq P(:OStruct)
  end

  it "handles DelegateClass(CLASSNAME) superclass syntax" do
    expect(P('Test5').superclass).to eq P(:Array)
  end

  it "handles a superclass of the same name in the form ::ClassName" do
    expect(P('Q::Logger').superclass).to eq P(:Logger)
    expect(P('Q::Foo').superclass).not_to eq P('Q::Logger')
  end

  ["CallMethod('test')", "VSD^#}}", 'not.aclass', 'self'].each do |klass|
    it "raises an UndocumentableError for invalid class '#{klass}'" do
      with_parser(:ruby18) { undoc_error "class #{klass}; end" }
    end
  end

  ['@@INVALID', 'hi', '$MYCLASS', 'AnotherClass.new'].each do |klass|
    it "raises an UndocumentableError for invalid superclass '#{klass}' but it should create the class." do
      expect(YARD::CodeObjects::ClassObject).to receive(:new).with(Registry.root, 'A')
      with_parser(:ruby18) { undoc_error "class A < #{klass}; end" }
      expect(Registry.at('A').superclass).to eq P(:Object)
    end
  end

  ['not.aclass', 'self', 'AnotherClass.new'].each do |klass|
    it "raises an UndocumentableError if the constant class reference 'class << SomeConstant' does not point to a valid class name" do
      with_parser(:ruby18) do
        undoc_error <<-eof
          CONST = #{klass}
          class << CONST; end
        eof
      end
      expect(Registry.at(klass)).to be nil
    end
  end

  it "documents 'class << SomeConstant' by using SomeConstant's value as a reference to the real class name" do
    expect(Registry.at('String.classmethod')).not_to be nil
  end

  it "allows class << SomeRubyClass to create the class if it does not exist" do
    expect(Registry.at('Symbol.toString')).not_to be nil
  end

  it "documents 'class Exception' without running into superclass issues" do
    Parser::SourceParser.parse_string <<-eof
      class Exception
      end
    eof
    expect(Registry.at(:Exception)).not_to be nil
  end

  it "documents 'class RT < XX::RT' with proper superclass even if XX::RT is a proxy" do
    expect(Registry.at(:RT)).not_to be nil
    expect(Registry.at(:RT).superclass).to eq P('XX::RT')
  end

  it "does not overwrite docstring with an empty one" do
    expect(Registry.at(:Zebra).docstring).to eq "Docstring 2"
  end

  it "turns 'class Const < Struct.new(:sym)' into class Const with attr :sym" do
    obj = Registry.at("Point")
    expect(obj).to be_kind_of(CodeObjects::ClassObject)
    attrs = obj.attributes[:instance]
    [:x, :y, :z].each do |key|
      expect(attrs).to have_key(key)
      expect(attrs[key][:read]).not_to be nil
      expect(attrs[key][:write]).not_to be nil
    end
  end

  it "turns 'class Const < Struct.new('Name', :sym)' into class Const with attr :sym" do
    obj = Registry.at("AnotherPoint")
    expect(obj).to be_kind_of(CodeObjects::ClassObject)
    attrs = obj.attributes[:instance]
    [:a, :b, :c].each do |key|
      expect(attrs).to have_key(key)
      expect(attrs[key][:read]).not_to be nil
      expect(attrs[key][:write]).not_to be nil
    end

    expect(Registry.at("XPoint")).to be nil
  end

  it "creates a Struct::Name class when class Const < Struct.new('Name', :sym) is found" do
    obj = Registry.at("Struct::XPoint")
    expect(obj).not_to be nil
  end

  it "attaches attribtues to the generated Struct::Name class when Struct.new('Name') is used" do
    obj = Registry.at("Struct::XPoint")
    attrs = obj.attributes[:instance]
    [:a, :b, :c].each do |key|
      expect(attrs).to have_key(key)
      expect(attrs[key][:read]).not_to be nil
      expect(attrs[key][:write]).not_to be nil
    end
  end

  it "uses @attr to set attribute descriptions on Struct subclasses" do
    obj = Registry.at("DoccedStruct#input")
    expect(obj.docstring).to eq "the input stream"
  end

  it "uses @attr to set attribute types on Struct subclasses" do
    obj = Registry.at("DoccedStruct#someproc")
    expect(obj).not_to be nil
    expect(obj.tag(:return)).not_to be nil
    expect(obj.tag(:return).types).to eq ["Proc", "#call"]
  end

  it "defaults types unspecified by @attr to Object on Struct subclasses" do
    obj = Registry.at("DoccedStruct#mode")
    expect(obj).not_to be nil
    expect(obj.tag(:return)).not_to be nil
    expect(obj.tag(:return).types).to eq ["Object"]
  end

  it "creates parameters for writers of Struct subclass's attributes" do
    obj = Registry.at("DoccedStruct#input=")
    expect(obj.tags(:param).size).to eq 1
    expect(obj.tag(:param).types).to eq ["IO"]
  end

  ["SemiDoccedStruct", "NotAStruct"].each do |struct|
    describe("Attributes on a " + (struct == "NotAStruct" ? "class" : "struct")) do
      it "defines both readers and writers when @attr is used on Structs" do
        obj = Registry.at(struct)
        attrs = obj.attributes[:instance]
        expect(attrs[:first][:read]).not_to be nil
        expect(attrs[:first][:write]).not_to be nil
      end

      it "defines only a reader when only @attr_reader is used on Structs" do
        obj = Registry.at(struct)
        attrs = obj.attributes[:instance]
        expect(attrs[:second][:read]).not_to be nil
        expect(attrs[:second][:write]).to be nil
      end

      it "defines only a writer when only @attr_writer is used on Structs" do
        obj = Registry.at(struct)
        attrs = obj.attributes[:instance]
        expect(attrs[:third][:read]).to be nil
        expect(attrs[:third][:write]).not_to be nil
      end

      it "defines a reader with correct return types when @attr_reader is used on Structs" do
        obj = Registry.at("#{struct}#second")
        expect(obj.tag(:return).types).to eq ["Fixnum"]
      end

      it "defines a writer with correct parameter types when @attr_writer is used on Structs" do
        obj = Registry.at("#{struct}#third=")
        expect(obj.tag(:param).types).to eq ["Array"]
      end

      it "defines a reader and a writer when both @attr_reader and @attr_writer are used" do
        obj = Registry.at(struct)
        attrs = obj.attributes[:instance]
        expect(attrs[:fourth][:read]).not_to be nil
        expect(attrs[:fourth][:write]).not_to be nil
      end

      it "uses @attr_reader for the getter when both @attr_reader and @attr_writer are given" do
        obj = Registry.at("#{struct}#fourth")
        expect(obj.tag(:return).types).to eq ["#read"]
      end

      it "uses @attr_writer for the setter when both @attr_reader and @attr_writer are given" do
        obj = Registry.at("#{struct}#fourth=")
        expect(obj.tag(:param).types).to eq ["IO"]
      end

      it "extracts text from @attr_reader" do
        expect(Registry.at("#{struct}#fourth").docstring).to eq "returns a proc that reads"
      end

      it "extracts text from @attr_writer" do
        expect(Registry.at("#{struct}#fourth=").docstring).to eq "sets the proc that writes stuff"
      end
    end
  end

  it "inherits from a regular struct" do
    expect(Registry.at('RegularStruct').superclass).to eq P(:Struct)
    expect(Registry.at('RegularStruct2').superclass).to eq P(:Struct)
  end

  it "handles inheritance from 'self'" do
    expect(Registry.at('Outer1::Inner1').superclass).to eq Registry.at('Outer1')
  end
end
yard-0.9.37/spec/handlers/class_method_handler_shared_examples.rb000066400000000000000000000067641466601756300252510ustar00rootroot00000000000000# frozen_string_literal: true
RSpec.shared_examples "class method visibility decorator" do
  # Use let(:visibility) to specify the name of the x_class_method
  # visibility decorator to test.

  describe do
    before do
      StubbedSourceParser.parse_string <<-CODE
        class A
          def self.b; end
          def self.c; end
          def self.d; end
          def self.e; end

          #{visibility}_class_method(:c, :d)
          #{visibility}_class_method("e")
        end
      CODE
    end

    it "handles private_class_method statement" do
      expect(Registry.at('A.c').visibility).to eq visibility
      expect(Registry.at('A.d').visibility).to eq visibility
      expect(Registry.at('A.e').visibility).to eq visibility
    end

    # Issue #760
    # https://github.com/lsegal/yard/issues/760
    it "handles singleton classes" do
      # Note: It's important to def a method within the singleton class or
      #       the bug may not trigger.
      code = <<-CODE
        class SingletonClass
          private_class_method :new
          def self.foo
            "foo"
          end
        end
      CODE

      StubbedSourceParser.parse_string(code) # Should be successful.
    end unless LEGACY_PARSER
  end

  describe "handles reopened class" do
    before do
      StubbedSourceParser.parse_string <<-CODE
        class SingletonClass

          #{'private' unless visibility.to_sym == :private}

          # != visibility
          def self.foo
            'foo'
          end

          # == visibility
          def self.bar
          end

          # == visibility from reopening class.
          def self.baz
          end

          #{visibility}_class_method :new, :bar

        end
      CODE

      StubbedSourceParser.parse_string <<-CODE
        # Reopening singleton class.
        class SingletonClass
          #{visibility}_class_method :baz

          #{'private' unless visibility.to_sym == :private}
          # != visibility from reopened class. (Verifies class was reopened.)
          def self.bat
          end

        end
      CODE
    end

    specify do
      expect(Registry.at('SingletonClass.foo').visibility).not_to eq visibility
      expect(Registry.at('SingletonClass.bar').visibility).to     eq visibility
      expect(Registry.at('SingletonClass.baz').visibility).to     eq visibility
      expect(Registry.at('SingletonClass.bat').visibility).not_to eq visibility
    end
  end unless LEGACY_PARSER # reopened class

  describe "as method definition decorator" do
    subject { Registry.at('SingletonClass.foo') }

    # Valid as of Ruby 2.1.0:
    # private_class_method def self.foo; end

    let(:code) do
      <<-CODE
        class SingletonClass
          # Valid Ruby 2.1.0 syntax.
          #{method_def}
            'it works'
          end
        end
      CODE
    end

    let(:method_def) { "#{visibility}_class_method def self.foo param1, param2" }

    before { StubbedSourceParser.parse_string code }

    it "handles self.foo" do
      expect(subject.visibility).to eq visibility
    end

    it "handles parameters correctly" do
      expect(subject.parameters.map(&:first)).to eq ['param1', 'param2']
    end

    it "attaches documentation to method definition" do
      expect(subject.docstring).to eq "Valid Ruby 2.1.0 syntax."
    end

    describe "handles SingletonClass.foo" do
      let(:method_def) { "#{visibility}_class_method def SingletonClass.foo" }

      specify do
        expect(subject.visibility).to eq visibility
      end
    end
  end unless LEGACY_PARSER
end
yard-0.9.37/spec/handlers/class_variable_handler_spec.rb000066400000000000000000000006731466601756300233350ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ClassVariableHandler" do
  before(:all) { parse_file :class_variable_handler_001, __FILE__ }

  it "does not parse class variables inside methods" do
    obj = Registry.at("A::B::@@somevar")
    expect(obj.source).to eq "@@somevar = \"hello\""
    expect(obj.value).to eq '"hello"'
  end
end
yard-0.9.37/spec/handlers/constant_handler_spec.rb000066400000000000000000000072361466601756300222160ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}ConstantHandler" do
  before(:all) { parse_file :constant_handler_001, __FILE__ }

  it "does not parse constants inside methods" do
    expect(Registry.at("A::B::SOMECONSTANT").source).to eq "SOMECONSTANT= \"hello\""
  end

  it "only parses valid constants" do
    expect(Registry.at("A::B::notaconstant")).to be nil
  end

  it "maintains newlines" do
    expect(Registry.at("A::B::MYCONSTANT").value.delete("\r")).to eq "A +\nB +\nC +\nD"
  end

  it "turns Const = Struct.new(:sym) into class Const with attr :sym" do
    obj = Registry.at("MyClass")
    expect(obj).to be_kind_of(CodeObjects::ClassObject)
    attrs = obj.attributes[:instance]
    [:a, :b, :c].each do |key|
      expect(attrs).to have_key(key)
      expect(attrs[key][:read]).not_to be nil
      expect(attrs[key][:write]).not_to be nil
    end
  end

  it 'documents block for Struct.new if present' do
    obj = Registry.at("MyStructWithConstant")
    expect(obj).to be_kind_of(CodeObjects::ClassObject)
    expect(obj.constants[0].docstring).to eq 'A constant.'
    expect(obj.constants[0].name).to eq :CONSTANT
    expect(obj.constants[0].value).to eq "42"
    expect(obj.constants[1].docstring).to eq 'Special constant (empty symbol)'
    expect(obj.constants[1].name).to eq :EMPTY
    expect(obj.constants[1].value).to eq ":''"
  end

  it "turns Const = Struct.new('Name', :sym) into class Const with attr :sym" do
    obj = Registry.at("NotMyClass")
    expect(obj).to be_kind_of(CodeObjects::ClassObject)
    attrs = obj.attributes[:instance]
    [:b, :c].each do |key|
      expect(attrs).to have_key(key)
      expect(attrs[key][:read]).not_to be nil
      expect(attrs[key][:write]).not_to be nil
    end

    expect(Registry.at("NotMyClass2")).to be nil
  end

  it "turns Const = Struct.new into empty struct" do
    obj = Registry.at("MyEmptyStruct")
    expect(obj).not_to be nil
    expect(obj.attributes[:instance]).to be_empty
  end

  it "maintains docstrings on structs defined via constants" do
    obj = Registry.at("DocstringStruct")
    expect(obj).not_to be nil
    expect(obj.docstring).to eq "A crazy struct."
    expect(obj.attributes[:instance]).not_to be_empty
    a1 = Registry.at("DocstringStruct#bar")
    a2 = Registry.at("DocstringStruct#baz")
    expect(a1.docstring).to eq "An attr"
    expect(a1.tag(:return).types).to eq ["String"]
    expect(a2.docstring).to eq "Another attr"
    expect(a2.tag(:return).types).to eq ["Number"]
    a3 = Registry.at("DocstringStruct#new_syntax")
    expect(a3.docstring).to eq "Attribute defined with the new syntax"
    expect(a3.tag(:return).types).to eq ["Symbol"]
  end

  it "raises undocumentable error in 1.9 parser for Struct.new assignment to non-const" do
    undoc_error "nonconst = Struct.new"
  end unless LEGACY_PARSER

  %w(module class).each do |type|
    it "does not allow #{type} to be redefined as constant" do
      undoc_error <<-eof
        #{type} Foo; end
        Foo = "value"
      eof
    end
  end unless LEGACY_PARSER

  it "allows constant to have same name as constant in parent namespace" do
    YARD.parse_string <<-eof
      module A
        class C; end
        module B; C = 1 end
      end
    eof
    expect(log.io.string).to eq ""
    expect(Registry.at('A::B::C').type).to eq :constant
  end

  it "detects compound constant names" do
    YARD.parse_string <<-eof
      module A
        class AA; end
        AA::B = true
      end
      A::AA::C = true
    eof

    expect(Registry.at('A::AA::B').type).to eq :constant
    expect(Registry.at('A::AA::C').type).to eq :constant
  end if HAVE_RIPPER
end
yard-0.9.37/spec/handlers/decorator_handler_methods_spec.rb000066400000000000000000000266211466601756300240710ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::DecoratorHandlerMethods" do
  describe "#process_decorator" do
    # Create a YARD decorator handler.
    # @param name [Symbol] name of the mock decorator
    def create_test_handler(name)
      data[name] = {}

      local_mock_handler_opts = mock_handler_opts
      local_nodes = nodes
      local_data = data[name]

      Class.new YARD::Handlers::Ruby::Base do
        include YARD::Handlers::Ruby::DecoratorHandlerMethods

        handles method_call(:"#{name}_decorator")
        namespace_only

        process do
          # process_decorator params written like this due to Ruby 1.8.
          # A modern handler should splat local_nodes.
          local_data[:return] =
            process_decorator(*(local_nodes + [local_mock_handler_opts])) do |method, node, mname|
              local_data[:method] = method
              local_data[:node] = node
              local_data[:name] = mname
            end
        end
      end
    end

    # Generate method definition.
    # @param symbols [Symbol] method names
    # @return [String] method definition code
    def make_defs(*symbols)
      symbols.map do |s|
        s = "self.#{s}" if mock_handler_opts[:scope] == :class
        "def #{s}; end"
      end.join("\n")
    end

    # Generate an AST for the given source code string.
    def make_ast(code)
      YARD::Parser::Ruby::RubyParser.new(code, nil).parse.ast
    end

    subject { data[:mock] }

    let(:data) { Hash.new }
    let(:nodes) { [] }
    let(:mock_handler_opts) { {:scope => :instance} }
    let(:class_name)    { 'DecoratorTest' }
    let(:docstring)     { 'the foo method' }
    let(:param_string)  { 'def foo param1, param2; end' }
    let(:method_defs)   { [] }
    let(:method_string) { "#{class_name}#foo" }
    let(:code) do
      <<-eof
      class #{class_name}
        #{make_defs(*method_defs)}
        # #{docstring}
        mock_decorator #{param_string}
      end
      eof
    end

    before do
      Registry.clear
      YARD::Handlers::Base.clear_subclasses

      create_test_handler :mock
      create_test_handler :first
      create_test_handler :second
      create_test_handler :third

      StubbedSourceParser.parse_string code
    end

    it "returns an array of hashes containing the method proxy, node, and name" do
      expect(subject[:return]).to be_an Array
      expect(subject[:return].first[:name].to_s).to eq 'foo'
      expect(subject[:return].first[:method].to_s).to eq method_string
      expect(subject[:return].first[:node]).to be_a YARD::Parser::Ruby::AstNode
    end

    describe "method is a MethodObject if the method has been defined" do
      let(:code) { "class DecoratorTest; mock_decorator def foo; end; end" }

      specify do
        expect(subject[:return].first[:method]).
          to be_a YARD::CodeObjects::MethodObject
      end
    end

    describe "method is a Proxy if the method has not been defined" do
      let(:code) { "class DecoratorTest; mock_decorator :foo; end" }

      specify do
        expect(subject[:return].first[:method]).to be_a YARD::CodeObjects::Proxy
      end
    end

    specify "block yields method proxy, node, name" do
      expect(subject[:name]).to be_a Symbol
      expect(subject[:name]).to eq :foo

      expect(subject[:method]).to be_a YARD::CodeObjects::MethodObject
      expect(subject[:method].to_s).to eq method_string

      expect(subject[:node]).to be_a YARD::Parser::Ruby::AstNode
    end

    describe "capitalized method names" do
      let(:method_defs)   { [:Foo] }
      let(:param_string)  { 'def Foo param1, param2; end' }

      specify do
        expect(subject[:method].to_s).to eq "#{class_name}#Foo"
      end
    end

    describe "nodes argument" do
      subject { data[:mock][:return].map {|h| h[:method].to_s } }

      describe "assumes all params refer to methods by default" do
        let(:method_defs)  { [:foo, :bar] }
        let(:param_string) { method_defs.map(&:inspect).join(',') }
        let(:nodes) { [] }

        specify do
          expect(subject).to eq ["#{class_name}#foo", "#{class_name}#bar"]
        end
      end

      describe "can specify which params to capture as methods" do
        let(:method_defs) { [:foo, :bar, :baz, :bat] }
        let(:parameters) do
          [:option_1, :baz, :bat, :option_2, :foo, :bar].map do |s|
            make_ast s.inspect
          end
        end

        describe "as a single param" do
          let(:nodes) { parameters[4] }

          specify do
            expect(subject).to eq ["#{class_name}#foo"]
          end
        end

        describe "as a list of params" do
          let(:nodes) { [parameters[4], parameters[5]] }

          specify do
            expect(subject).to eq ["#{class_name}#foo", "#{class_name}#bar"]
          end
        end

        describe "as a range" do
          let(:nodes) { parameters[4..-1] }

          specify do
            expect(subject).to eq ["#{class_name}#foo", "#{class_name}#bar"]
          end
        end

        describe "as multiple ranges" do
          # Written like this due to Ruby 1.8. Can also splat the ranges as
          # separate params:
          #   *parameters[1..2], *parameters[4..-1]
          let(:nodes) { parameters[1..2] + parameters[4..-1] }

          specify do
            expect(subject).to eq [
              "#{class_name}#baz",
              "#{class_name}#bat",
              "#{class_name}#foo",
              "#{class_name}#bar"
            ]
          end
        end
      end

      describe "can select no nodes by passing nil" do
        let(:nodes) { [nil] }

        specify do
          expect(subject).to eq []
        end
      end
    end

    describe "scope option" do
      describe "defaults to :instance" do
        let(:mock_handler_opts) { {} }

        specify do
          expect(subject[:return].first[:method].to_s).to eq method_string
        end
      end

      describe "creates method proxies" do
        shared_examples "decorator helper scope" do
          let(:param_string) { decorator_params.map(&:inspect).join(',') }

          describe "for symbols" do
            let(:decorator_params) { [:foo, :bar] }

            specify do
              expect(subject.count).to eq decorator_params.count

              subject.each_with_index do |_, i|
                expect(subject[i]).to be_a YARD::CodeObjects::MethodObject
                expect(subject[i].to_s).to eq \
                  "#{class_name}#{mock_handler_opts[:scope] == :class ? '.' : '#'}#{decorator_params[i]}"
              end
            end
          end

          describe "for string literals" do
            let(:decorator_params) { ['foo', 'bar'] }

            specify do
              expect(subject.count).to eq decorator_params.count

              subject.each_with_index do |_, i|
                expect(subject[i]).to be_a YARD::CodeObjects::MethodObject
                expect(subject[i].to_s).to eq \
                  "#{class_name}#{mock_handler_opts[:scope] == :class ? '.' : '#'}#{decorator_params[i]}"
              end
            end
          end

          describe "for methods" do
            let(:param_string) { decorator_params.join(',') }
            let(:decorator_params) do
              ["def #{'self.' if mock_handler_opts[:scope] == :class}foo f1, f2; end",
              "def #{'self.' if mock_handler_opts[:scope] == :class}bar b1, b2; end"]
            end

            specify do
              expect(subject.count).to eq decorator_params.count

              subject.each_with_index do |_, i|
                expect(subject[i]).to be_a YARD::CodeObjects::MethodObject
                expect(subject[i].to_s).to eq \
                  class_name +
                  (mock_handler_opts[:scope] == :class ? '.' : '#') +
                  decorator_params[i].split(' ')[1][/\w+$/]
              end
            end
          end
        end # decorator helper scope shared examples

        subject { data[:mock][:return].map {|h| h[:method] } }

        let(:docstring) { 'the foo method' }
        let(:method_defs) { [:foo, :bar] }

        describe "for :instance" do
          let(:mock_handler_opts) { {:scope => :instance} }

          include_examples "decorator helper scope"
        end

        describe "for :class" do
          let(:mock_handler_opts) { {:scope => :class} }

          include_examples "decorator helper scope"
        end
      end
    end

    describe "docstring from decorator" do
      subject { Registry.at method_string }

      specify "attaches to method definitions as decorator parameters" do
        expect(subject.docstring).to eq docstring
      end

      describe "does not attach" do
        describe "to undefined methods" do
          let(:code) do
            <<-eof
            class #{class_name}
              # #{docstring}
              mock_decorator :foo
            end
            eof
          end

          specify do
            expect(subject).not_to respond_to :docstring
          end
        end

        describe "to methods with existing docstring" do
          let(:code) do
            <<-eof
            class #{class_name}

              # original docstring
              def foo; end

              # #{docstring}
              mock_decorator :foo
            end
            eof
          end

          specify do
            expect(subject.docstring).to eq 'original docstring'
          end
        end
      end
    end

    describe "chained decorators" do
      subject { Registry.at method_string }

      let(:param_string) { 'def foo param1, param2; end' }
      let(:code) do
        <<-eof
        class #{class_name}
          #{make_defs(*method_defs)}
          # #{docstring}
          first_decorator second_decorator third_decorator #{param_string}
        end
        eof
      end

      specify "register nested method defs" do
        expect(subject).to be_a YARD::CodeObjects::MethodObject
      end

      describe "transfer docstring to decorated method defs" do
        specify do
          expect(subject.docstring).to eq docstring
        end

        describe "unless opt-out param is set" do
          let(:mock_handler_opts) { {:transfer_docstring => false} }

          specify do
            expect(subject.docstring.empty?).to be true
          end
        end
      end

      describe "don't transfer docstring to referenced methods" do
        let(:method_defs)  { [:foo] }
        let(:param_string) { ':foo' }

        specify do
          expect(subject.docstring.empty?).to be true
        end
      end

      specify "don't transfer docstring to other decorators" do
        expect(Registry.at("#{class_name}#second_decorator")).
          not_to respond_to :docstring

        expect(Registry.at("#{class_name}#third_decorator")).
          not_to respond_to :docstring
      end

      describe "transfer source to decorated method defs" do
        specify do
          expect(subject.source).to eq code.lines.to_a[-2].strip
        end

        describe "unless opt-out param is set" do
          let(:mock_handler_opts) { {:transfer_source => false} }

          specify do
            expect(subject.source).to eq param_string
          end
        end
      end

      describe "don't transfer source to referenced methods" do
        let(:method_defs)  { [:foo] }
        let(:param_string) { ':foo' }

        specify do
          expect(subject.source).to eq make_defs(*method_defs)
        end
      end
    end
  end # process_decorator
end unless LEGACY_PARSER
yard-0.9.37/spec/handlers/dsl_handler_spec.rb000066400000000000000000000177131466601756300211500ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}DSLHandler" do
  before(:all) { parse_file :dsl_handler_001, __FILE__ }

  it "creates a readable attribute when @!attribute r is found" do
    obj = Registry.at('Foo#attr1')
    expect(obj).not_to be nil
    expect(obj).to be_reader
    expect(obj.tag(:return).types).to eq ['Numeric']
    expect(Registry.at('Foo#attr1=')).to be nil
  end

  it "creates a writable attribute when @!attribute w is found" do
    obj = Registry.at('Foo#attr2=')
    expect(obj).not_to be nil
    expect(obj).to be_writer
    expect(Registry.at('Foo#attr2')).to be nil
  end

  it "defaults to readwrite @!attribute" do
    obj = Registry.at('Foo#attr3')
    expect(obj).not_to be nil
    expect(obj).to be_reader
    obj = Registry.at('Foo#attr3=')
    expect(obj).not_to be nil
    expect(obj).to be_writer
  end

  it "allows @!attribute to define alternate method name" do
    expect(Registry.at('Foo#attr4')).to be nil
    expect(Registry.at('Foo#custom')).not_to be nil
  end

  it "defaults to creating an instance method for any DSL method with special tags" do
    obj = Registry.at('Foo#implicit0')
    expect(obj).not_to be nil
    expect(obj.docstring).to eq "IMPLICIT METHOD!"
    expect(obj.tag(:return).types).to eq ['String']
  end

  it "recognizes implicit docstring when it has scope tag" do
    obj = Registry.at("Foo.implicit1")
    expect(obj).not_to be nil
    expect(obj.scope).to eq :class
  end

  it "recognizes implicit docstring when it has visibility tag" do
    obj = Registry.at("Foo#implicit2")
    expect(obj).not_to be nil
    expect(obj.visibility).to eq :protected
  end

  it "does not recognize implicit docstring with any other normal tag" do
    obj = Registry.at('Foo#implicit_invalid3')
    expect(obj).to be nil
  end

  it "sets the method name when using @!method" do
    obj = Registry.at('Foo.xyz')
    expect(obj).not_to be nil
    expect(obj.signature).to eq 'def xyz(a, b, c)'
    expect(obj.parameters).to eq [['a', nil], ['b', nil], ['c', nil]]
    expect(obj.source).to eq 'foo_bar'
    expect(obj.docstring).to eq 'The foo method'
  end

  it "recognizes methods with no attached source" do
    obj = Registry.at('Foo#no_src')
    expect(obj).not_to be nil
    expect(obj.signature).to eq 'def no_src'
    expect(obj.source).to eq ''
  end

  it "allows setting of @!scope" do
    expect(Registry.at('Foo.xyz').scope).to eq :class
  end

  it "creates module function if @!scope is module" do
    mod_c = Registry.at('Foo.modfunc1')
    mod_i = Registry.at('Foo#modfunc1')
    expect(mod_c.scope).to eq :class
    expect(mod_i.visibility).to eq :private
  end

  it "allows setting of @!visibility" do
    expect(Registry.at('Foo.xyz').visibility).to eq :protected
  end

  it "ignores DSL methods without tags" do
    expect(Registry.at('Foo#implicit_invalid')).to be nil
  end

  it "accepts a DSL method without tags if it has hash_flag (##)" do
    expect(Registry.at('Foo#implicit_valid')).not_to be nil
    expect(Registry.at('Foo#implicit_invalid2')).to be nil
  end

  it "allows creation of macros" do
    macro = CodeObjects::MacroObject.find('property')
    expect(macro).not_to be nil
    expect(macro).not_to be_attached
    expect(macro.method_object).to be nil
  end

  it "handles macros with no parameters to expand" do
    expect(Registry.at('Foo#none')).not_to be nil
    expect(Registry.at('Baz#none').signature).to eq 'def none(foo, bar)'
  end

  it "expands $N on method definitions" do
    expect(Registry.at('Foo#regular_meth').docstring).to eq 'a b c'
  end

  it "applies new macro docstrings on new objects" do
    obj = Registry.at('Foo#name')
    expect(obj).not_to be nil
    expect(obj.source).to eq 'property :name, String, :a, :b, :c'
    expect(obj.signature).to eq 'def name(a, b, c)'
    expect(obj.docstring).to eq 'A property that is awesome.'
    expect(obj.tag(:param).name).to eq 'a'
    expect(obj.tag(:param).text).to eq 'first parameter'
    expect(obj.tag(:return).types).to eq ['String']
    expect(obj.tag(:return).text).to eq 'the property name'
  end

  it "allows reuse of named macros" do
    obj = Registry.at('Foo#age')
    expect(obj).not_to be nil
    expect(obj.source).to eq 'property :age, Fixnum, :value'
    expect(obj.signature).to eq 'def age(value)'
    expect(obj.docstring).to eq 'A property that is awesome.'
    expect(obj.tag(:param).name).to eq 'value'
    expect(obj.tag(:param).text).to eq 'first parameter'
    expect(obj.tag(:return).types).to eq ['Fixnum']
    expect(obj.tag(:return).text).to eq 'the property age'
  end

  it "knows about method information on DSL with macro expansion" do
    expect(Registry.at('Foo#right_name')).not_to be nil
    expect(Registry.at('Foo#right_name').source).to eq 'implicit_with_different_method_name :wrong, :right'
    expect(Registry.at('Foo#wrong_name')).to be nil
  end

  it "uses attached macros" do
    macro = CodeObjects::MacroObject.find('parser')
    expect(macro.macro_data).to eq "@!method $1(opts = {})\n@return NOTHING!"
    expect(macro).not_to be nil
    expect(macro).to be_attached
    expect(macro.method_object).to eq P('Foo.parser')
    obj = Registry.at('Foo#c_parser')
    expect(obj).not_to be nil
    expect(obj.docstring).to eq ""
    expect(obj.signature).to eq "def c_parser(opts = {})"
    expect(obj.docstring.tag(:return).text).to eq "NOTHING!"
  end

  it "appends docstring on DSL method to attached macro" do
    obj = Registry.at('Foo#d_parser')
    expect(obj).not_to be nil
    expect(obj.docstring).to eq "Another docstring"
    expect(obj.signature).to eq "def d_parser(opts = {})"
    expect(obj.docstring.tag(:return).text).to eq "NOTHING!"
  end

  it "only uses attached macros on methods defined in inherited hierarchy" do
    expect(Registry.at('Bar#x_parser')).to be nil
    expect(Registry.at('Baz#y_parser')).not_to be nil
  end

  it "looks through mixins for attached macros" do
    meth = Registry.at('Baz#mixin_method')
    expect(meth).not_to be nil
    expect(meth.docstring).to eq 'DSL method mixin_method'
  end

  it "handles top-level DSL methods" do
    obj = Registry.at('#my_other_method')
    expect(obj).not_to be nil
    expect(obj.docstring).to eq "Docstring for method"
  end

  it "handles Constant.foo syntax" do
    obj = Registry.at('#beep')
    expect(obj).not_to be nil
    expect(obj.signature).to eq 'def beep(a, b, c)'
  end

  it "expands attached macros in first DSL method" do
    expect(Registry.at('DSLMethods#foo').docstring).to eq "Returns String for foo"
    expect(Registry.at('DSLMethods#bar').docstring).to eq "Returns Integer for bar"
  end

  it "maintains state on unattached directives" do
    expect(Registry.at('StateParsing.method1')).to be_nil

    %w(method2 method3).each do |meth|
      expect(Registry.at("StateParsing.#{meth}").visibility).to eq(:private)
    end
  end

  it "does not detect implicit macros with invalid method names" do
    undoc_error <<-eof
      ##
      # IMPLICIT METHOD THAT SHOULD
      # NOT BE DETECTED
      dsl_method '/foo/bar'
    eof
  end

  it "warns on unparsable DSL statements" do
    undoc_error "private(*foo(bar))"
  end if HAVE_RIPPER

  # @note Currently unsupported behavior. Overriding a macro on an alias will
  #   not work until macro lookups can be done by caller_method directly.
  # @todo optimize MacroObject lookup to work by caller name, not macro name.
  it "cannot attach a macro on alias of attached macro" do
    expect(Registry.at('AliasTest#main_foo1')).not_to be nil
    expect(Registry.at('AliasTest#alt_foo1')).to be nil
  end if HAVE_RIPPER

  it "searches attached macro's aliases for caller method match" do
    expect(Registry.at('AliasTest#main_foo2')).not_to be nil
    expect(Registry.at('AliasTest#alt_foo2')).to be nil
  end if HAVE_RIPPER

  it "does not create method object if directive data detected in expanded macro" do
    expect(Registry.at('DirectiveMethods#Bar')).to be nil
    expect(Registry.at('DirectiveMethods').mixins).to include P(:Bar)
  end
end
yard-0.9.37/spec/handlers/examples/000077500000000000000000000000001466601756300171375ustar00rootroot00000000000000yard-0.9.37/spec/handlers/examples/alias_handler_001.rb.txt000066400000000000000000000012271466601756300234520ustar00rootroot00000000000000module A
  def a; end
  alias_method :b, :a
  alias_method :"cstrmeth", :"a"

  # Handle keyword syntax too
  alias :c :a
  alias :"cstrkey" :a
  alias d? a
  alias [] a
  alias []= a
  alias -@ a
  alias % a
  alias * a
  alias for a
  alias ConstantName a

  # Handle quoted symbols
  alias :'foo' :'a'
end

class C
  def x; end
end

class B < C
  alias_method(:q, :x)
  alias_method :r?, :x
  alias_method :s, :to_s
  alias_method :t, :inspect if 500 == 3 * CONSTANT
  alias_method :<<, :a
  alias_method :for, :a
  alias do x
  alias x2 do
end

class D
  # Foo bar
  def a; "FOO" end

  # @return [String]
  alias b a

  # @return [Numeric]
  def a; 0 end
endyard-0.9.37/spec/handlers/examples/attribute_handler_001.rb.txt000066400000000000000000000005501466601756300243620ustar00rootroot00000000000000module A
  attr_writer :x
end

class B
  class << self
    attr_accessor :z
  end

  attr :a, true
  attr :a2, false
  attr :a3
  # Docstring
  attr_reader :b, :c, :d
  attr_writer :e
  attr_accessor 'f'

  attr_accessor :z
end

class C
  def foo; end
  attr_writer :foo

  def bar=(value); end
  attr_reader :bar
end

class D
protected
attr_reader :parser
endyard-0.9.37/spec/handlers/examples/class_condition_handler_001.rb.txt000066400000000000000000000013131466601756300255300ustar00rootroot00000000000000class A
  if some_condition
    def a; end
  elsif 1 == 1
    def b; end
  else
    def c; end
  end

  def d; end if 50 * 2 == 101

  unless false
    def e; end
  else
    def enot; end
  end

  def g; end unless 5 * 2 == 101

  def h
    if 1
      def hnot; end
    end
  end

  if defined? A
    def j; end
  else
    def jnot; end
  end

  if defined? RUBY_VERSION
    def k; end
  else
    def knot; end
  end

  if 0
    def nnot; end
  else
    def n; end
  end

  if 256
    def o; end
  else
    def onot; end
  end

  if true
    def p; end
  else
    def pnot; end
  end

  if false
    def qnot; end
  else
    def q; end
  end

  private

  if a == 1
    def m; end
  else
    def mnot; end
  end
endyard-0.9.37/spec/handlers/examples/class_handler_001.rb.txt000066400000000000000000000037471466601756300234770ustar00rootroot00000000000000# Docstring
class A
  module B; end
  private
  class B::C < String;
    def method1; end
    def method2; end
  end
  class X :ruby))
  end

  it "starts with public visibility" do
    expect(@proc.visibility).to eq :public
  end

  it "starts in instance scope" do
    expect(@proc.scope).to eq :instance
  end

  it "starts in root namespace" do
    expect(@proc.namespace).to eq Registry.root
  end

  it "has a globals structure" do
    expect(@proc.globals).to be_a(YARD::OpenStruct)
  end

  it "ignores HandlerAborted exceptions (but print debug info)" do
    class AbortHandlerProcessor < YARD::Handlers::Ruby::Base
      process { abort! }
    end
    stmt = OpenStruct.new(:line => 1, :show => 'SOURCE')
    allow(@proc).to receive(:find_handlers).and_return([AbortHandlerProcessor])
    expect(log).to receive(:debug).with(/AbortHandlerProcessor cancelled from/)
    expect(log).to receive(:debug).with("\tin file '(stdin)':1:\n\nSOURCE\n")
    @proc.process([stmt])
  end
end
yard-0.9.37/spec/handlers/public_class_method_handler_spec.rb000066400000000000000000000005651466601756300243660ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'
require File.dirname(__FILE__) + '/class_method_handler_shared_examples'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}PublicClassMethodHandler" do
  before { Registry.clear }

  let(:visibility) { :public }

  include_examples "class method visibility decorator"
end
yard-0.9.37/spec/handlers/ruby/000077500000000000000000000000001466601756300163025ustar00rootroot00000000000000yard-0.9.37/spec/handlers/ruby/base_spec.rb000066400000000000000000000060701466601756300205560ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Handlers::Ruby::Base, '#valid_handler?' do
  include YARD::Parser::Ruby
  YARD::Parser::Ruby::AstNode # rubocop:disable Lint/Void

  before do
    allow(Handlers::Ruby::Base).to receive(:inherited)
    @processor = Handlers::Processor.new(OpenStruct.new(:parser_type => :ruby))
  end

  after(:all) do
    Handlers::Base.clear_subclasses
  end

  def valid(handler, stmt)
    expect(@processor.find_handlers(stmt)).to include(handler)
  end

  def invalid(handler, stmt)
    expect(@processor.find_handlers(stmt)).not_to include(handler)
  end

  it "only handles Handlers inherited from Ruby::Base class" do
    class IgnoredHandler < Handlers::Base
      handles :list
    end
    class NotIgnoredHandler < Handlers::Ruby::Base
      handles :list
    end
    allow(Handlers::Base).to receive(:subclasses).and_return [IgnoredHandler, NotIgnoredHandler]
    expect(@processor.find_handlers(s)).to eq [NotIgnoredHandler]
  end

  it "handles string input (matches AstNode#source)" do
    class StringHandler < Handlers::Ruby::Base
      handles "x"
    end
    allow(Handlers::Base).to receive(:subclasses).and_return [StringHandler]
    ast = Parser::Ruby::RubyParser.parse("if x == 2 then true end").ast
    valid StringHandler, ast[0][0][0]
    invalid StringHandler, ast[0][1]
  end

  it "handles symbol input (matches AstNode#type)" do
    class SymbolHandler < Handlers::Ruby::Base
      handles :myNodeType
    end
    allow(Handlers::Base).to receive(:subclasses).and_return [SymbolHandler]
    valid SymbolHandler, s(:myNodeType, s(1, 2, 3))
    invalid SymbolHandler, s(:NOTmyNodeType, s(1, 2, 3))
  end

  it "handles regex input (matches AstNode#source)" do
    class RegexHandler < Handlers::Ruby::Base
      handles(/^if x ==/)
    end
    allow(Handlers::Base).to receive(:subclasses).and_return [RegexHandler]
    ast = Parser::Ruby::RubyParser.parse("if x == 2 then true end").ast
    valid RegexHandler, ast
    invalid RegexHandler, ast[0][1]
  end

  it "handles AstNode input (matches AST literally)" do
    class ASTHandler < Handlers::Ruby::Base
      handles s(:vcall, s(:ident, "hello_world"))
    end
    allow(Handlers::Base).to receive(:subclasses).and_return [ASTHandler]
    valid ASTHandler, s(:vcall, s(:ident, "hello_world"))
    invalid ASTHandler, s(:vcall, s(:ident, "NOTHELLOWORLD"))
  end

  it "handles #method_call(:methname) on a valid AST" do
    class MethCallHandler < Handlers::Ruby::Base
      handles method_call(:meth)
    end
    allow(Handlers::Base).to receive(:subclasses).and_return [MethCallHandler]
    ast = Parser::Ruby::RubyParser.parse(<<-"eof").ast
      meth                   # 0
      meth()                 # 1
      meth(1,2,3)            # 2
      meth 1,2,3             # 3
      NotMeth.meth           # 4
      NotMeth.meth { }       # 5
      NotMeth.meth do end    # 6
      NotMeth.meth 1, 2, 3   # 7
      NotMeth.meth(1, 2, 3)  # 8
      NotMeth                # 9
    eof
    (0..8).each do |i|
      valid MethCallHandler, ast[i]
    end
    invalid MethCallHandler, ast[9]
  end
end if HAVE_RIPPER
yard-0.9.37/spec/handlers/ruby/legacy/000077500000000000000000000000001466601756300175465ustar00rootroot00000000000000yard-0.9.37/spec/handlers/ruby/legacy/base_spec.rb000066400000000000000000000052121466601756300220170ustar00rootroot00000000000000# frozen_string_literal: true

include Parser::Ruby::Legacy

RSpec.describe YARD::Handlers::Ruby::Legacy::Base, "#handles and inheritance" do
  before do
    allow(Handlers::Ruby::Legacy::Base).to receive(:inherited)
    if RUBY_VERSION > '1.8.7'
      allow(Handlers::Ruby::Legacy::MixinHandler).to receive(:inherited) # fixes a Ruby1.9 issue
    end
    @processor = Handlers::Processor.new(OpenStruct.new(:parser_type => :ruby18))
  end

  after(:all) do
    Handlers::Base.clear_subclasses
  end

  def stmt(string)
    Statement.new(TokenList.new(string))
  end

  it "only handles Handlers inherited from Ruby::Legacy::Base class" do
    class IgnoredHandler < Handlers::Base
      handles "hello"
    end
    class NotIgnoredHandlerLegacy < Handlers::Ruby::Legacy::Base
      handles "hello"
    end
    allow(Handlers::Base).to receive(:subclasses).and_return [IgnoredHandler, NotIgnoredHandlerLegacy]
    expect(@processor.find_handlers(stmt("hello world"))).to eq [NotIgnoredHandlerLegacy]
  end

  it "handles a string input" do
    class TestStringHandler < Handlers::Ruby::Legacy::Base
      handles "hello"
    end

    expect(TestStringHandler.handles?(stmt("hello world"))).to be true
    expect(TestStringHandler.handles?(stmt("nothello world"))).to be false
  end

  it "handles regex input" do
    class TestRegexHandler < Handlers::Ruby::Legacy::Base
      handles(/^nothello$/)
    end

    expect(TestRegexHandler.handles?(stmt("nothello"))).to be true
    expect(TestRegexHandler.handles?(stmt("not hello hello"))).to be false
  end

  it "handles token input" do
    class TestTokenHandler < Handlers::Ruby::Legacy::Base
      handles TkMODULE
    end

    expect(TestTokenHandler.handles?(stmt("module"))).to be true
    expect(TestTokenHandler.handles?(stmt("if"))).to be false
  end

  it "parses a do/end or { } block with #parse_block" do
    class MyBlockHandler < Handlers::Ruby::Legacy::Base
      handles(/\AmyMethod\b/)
      def process
        parse_block(:owner => "test")
      end
    end

    class MyBlockInnerHandler < Handlers::Ruby::Legacy::Base
      handles "inner"
      def self.reset; @@reached = false end
      def self.reached?; @@reached ||= false end
      def process; @@reached = true end
    end

    allow(Handlers::Base).to receive(:subclasses).and_return [MyBlockHandler, MyBlockInnerHandler]
    Parser::SourceParser.parser_type = :ruby18
    Parser::SourceParser.parse_string "myMethod do inner end"
    expect(MyBlockInnerHandler).to be_reached
    MyBlockInnerHandler.reset
    Parser::SourceParser.parse_string "myMethod { inner }"
    expect(MyBlockInnerHandler).to be_reached
    Parser::SourceParser.parser_type = :ruby
  end
end
yard-0.9.37/spec/handlers/spec_helper.rb000066400000000000000000000014131466601756300201360ustar00rootroot00000000000000# frozen_string_literal: true
require 'stringio'

include Handlers

def undoc_error(code)
  expect { StubbedSourceParser.parse_string(code) }.to raise_error(Parser::UndocumentableError)
end

def with_parser(parser_type)
  tmp = StubbedSourceParser.parser_type
  StubbedSourceParser.parser_type = parser_type
  yield
  StubbedSourceParser.parser_type = tmp
end

class StubbedProcessor < Processor
  def process(statements)
    statements.each_with_index do |stmt, _index|
      find_handlers(stmt).each do |handler|
        handler.new(self, stmt).process
      end
    end
  end
end

class StubbedSourceParser < Parser::SourceParser
  StubbedSourceParser.parser_type = :ruby
  def post_process
    post = StubbedProcessor.new(self)
    post.process(@parser.enumerator)
  end
end
yard-0.9.37/spec/handlers/visibility_handler_spec.rb000066400000000000000000000041531466601756300225470ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}VisibilityHandler" do
  before(:all) { parse_file :visibility_handler_001, __FILE__ }

  it "is able to set visibility to public" do
    expect(Registry.at("Testing#pub").visibility).to eq :public
    expect(Registry.at("Testing#pub2").visibility).to eq :public
  end

  it "is able to set visibility to private" do
    expect(Registry.at("Testing#priv").visibility).to eq :private
  end

  it "is able to set visibility to protected" do
    expect(Registry.at("Testing#prot").visibility).to eq :protected
  end

  it "supports parameters and only set visibility on those methods" do
    expect(Registry.at('Testing#notpriv').visibility).to eq :protected
    expect(Registry.at('Testing#notpriv2').visibility).to eq :protected
    expect(Registry.at('Testing#notpriv?').visibility).to eq :protected
  end

  it "only accepts strings and symbols" do
    expect(Registry.at('Testing#name')).to be nil
    expect(Registry.at('Testing#argument')).to be nil
    expect(Registry.at('Testing#method_call')).to be nil
  end

  it "handles constants passed in as symbols" do
    expect(Registry.at('Testing#Foo').visibility).to eq :private
  end

  it "does not register classes with visibility" do
    expect(Registry.at('Testing::Bar').visibility).to eq :public
    expect(Registry.at('Testing::Baz').visibility).to eq :public
  end

  it "can decorate a method definition" do
    expect(Registry.at('Testing#decpriv').visibility).to eq :private
  end unless LEGACY_PARSER

  describe 'ruby 3 specific features' do
    before(:all) { parse_file :visibility_handler_002, __FILE__ }

    it "handles attr_accessor when inlined" do
      expect(Registry.at('Testing#inline_private_attr').visibility).to eq :private
      expect(Registry.at('Testing#inline_private_attr=').visibility).to eq :private
      expect(Registry.at('Testing#inline_protected_writer=').visibility).to eq :protected
      expect(Registry.at('Testing#inline_public_reader').visibility).to eq :public
    end
  end if RUBY_VERSION >= "3."
end
yard-0.9.37/spec/handlers/yield_handler_spec.rb000066400000000000000000000042661466601756300214730ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe "YARD::Handlers::Ruby::#{LEGACY_PARSER ? "Legacy::" : ""}YieldHandler" do
  before(:all) { parse_file :yield_handler_001, __FILE__ }

  it "only parses yield blocks in methods" do
    expect(P(:Testing).tag(:yield)).to be nil
    expect(P(:Testing).tag(:yieldparam)).to be nil
  end

  it "handles an empty yield statement" do
    expect(P('Testing#mymethod').tag(:yield)).to be nil
    expect(P('Testing#mymethod').tag(:yieldparam)).to be nil
  end

  it "does not document a yield statement in a method with either @yield or @yieldparam" do
    expect(P('Testing#mymethod2').tag(:yield).types).to eq ['a', 'b']
    expect(P('Testing#mymethod2').tag(:yield).text).to eq "Blah"
    expect(P('Testing#mymethod2').tags(:yieldparam).size).to eq 2

    expect(P('Testing#mymethod3').tag(:yield).types).to eq ['a', 'b']
    expect(P('Testing#mymethod3').tags(:yieldparam).size).to eq 0

    expect(P('Testing#mymethod4').tag(:yieldparam).name).to eq '_self'
    expect(P('Testing#mymethod4').tag(:yieldparam).text).to eq 'BLAH'
  end

  it "handles any arbitrary yield statement" do
    expect(P('Testing#mymethod5').tag(:yield).types).to eq [':a', 'b', '_self', 'File.read(\'file\', \'w\')', 'CONSTANT']
  end

  it "handles parentheses" do
    expect(P('Testing#mymethod6').tag(:yield).types).to eq ['b', 'a']
  end

  it "only documents the first yield statement in a method (limitation of yield handler)" do
    expect(P('Testing#mymethod7').tag(:yield).types).to eq ['a']
  end

  it "handles `self` keyword and list object type as yieldparam for _self" do
    expect(P('Testing#mymethod8').tag(:yield).types).to eq ['_self']
    expect(P('Testing#mymethod8').tag(:yieldparam).types).to eq ['Testing']
    expect(P('Testing#mymethod8').tag(:yieldparam).text).to eq "the object that the method was called on"
  end

  it "handles `super` keyword and document it under _super" do
    expect(P('Testing#mymethod9').tag(:yield).types).to eq ['_super']
    expect(P('Testing#mymethod9').tag(:yieldparam).types).to be nil
    expect(P('Testing#mymethod9').tag(:yieldparam).text).to eq "the result of the method from the superclass"
  end
end
yard-0.9.37/spec/i18n/000077500000000000000000000000001466601756300143005ustar00rootroot00000000000000yard-0.9.37/spec/i18n/locale_spec.rb000066400000000000000000000037141466601756300171030ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::I18n::Locale do
  def locale(name)
    YARD::I18n::Locale.new(name)
  end

  before do
    @locale = locale("fr")
  end

  describe "#name" do
    it "returns name" do
      expect(locale("fr").name).to eq "fr"
    end
  end

  describe "#load" do
    it "returns false for nonexistent PO" do
      expect(File).to receive(:exist?).with('foo/fr.po').and_return(false)
      expect(@locale.load('foo')).to be false
    end

    have_gettext_gem = true
    if RUBY_VERSION < "1.9"
      begin
        require "gettext/tools/poparser"
      rescue LoadError
        have_gettext_gem = false
      end
    else
      begin
        require "gettext/po_parser"
      rescue LoadError
        begin
          require "gettext/tools/poparser"
        rescue LoadError
          have_gettext_gem = false
        end
      end
    end

    it "returns true for existent PO", :if => have_gettext_gem do
      data = <<-eop
msgid ""
msgstr ""
"Language: fr\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Hello"
msgstr "Bonjour"
eop
      parser = GetText::POParser.new
      expect(File).to receive(:exist?).with('foo/fr.po').and_return(true)
      expect(GetText::POParser).to receive(:new).and_return(parser)
      expect(parser).to receive(:parse_file) do |file, hash|
        expect(file).to eq 'foo/fr.po'
        parser.parse(String.new(data), hash)
      end
      expect(@locale.load('foo')).to be true
      expect(@locale.translate('Hello')).to eq "Bonjour"
    end
  end

  describe "#translate" do
    before do
      messages = @locale.instance_variable_get(:@messages)
      messages["Hello"] = "Bonjour"
    end

    it "returns translated string for existent string" do
      expect(@locale.translate("Hello")) == "Bonjour"
    end

    it "returns original string for nonexistent string" do
      expect(@locale.translate("nonexistent")) == "nonexistent"
    end
  end
end
yard-0.9.37/spec/i18n/message_spec.rb000066400000000000000000000024671466601756300172740ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::I18n::Message do
  def message(id)
    YARD::I18n::Message.new(id)
  end

  before do
    @message = message("Hello World!")
  end

  describe "#id" do
    it "returns ID" do
      expect(message("Hello World!").id).to eq "Hello World!"
    end
  end

  describe "#add_location" do
    it "adds some locations" do
      @message.add_location("hello.rb", 10)
      @message.add_location("message.rb", 5)
      expect(@message.locations).to eq Set.new([["hello.rb", 10], ["message.rb", 5]])
    end
  end

  describe "#add_comment" do
    it "adds some comments" do
      @message.add_comment("YARD.title")
      @message.add_comment("Hello#message")
      expect(@message.comments).to eq Set.new(["YARD.title", "Hello#message"])
    end
  end

  describe "#==" do
    it "returns true for same value messages" do
      locations = [["hello.rb", 10], ["message.rb", 5]]
      comments = ["YARD.title", "Hello#message"]

      other_message = message(@message.id)
      locations.each do |path, line|
        @message.add_location(path, line)
        other_message.add_location(path, line)
      end
      comments.each do |comment|
        @message.add_comment(comment)
        other_message.add_comment(comment)
      end

      expect(@message).to eq other_message
    end
  end
end
yard-0.9.37/spec/i18n/messages_spec.rb000066400000000000000000000033061466601756300174500ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::I18n::Messages do
  def message(id)
    YARD::I18n::Message.new(id)
  end

  def messages
    YARD::I18n::Messages.new
  end

  before do
    @messages = messages
  end

  describe "#each" do
    it "enumerates messages" do
      @messages.register("Hello World!")
      @messages.register("Title")
      enumerated_messages = []
      @messages.each do |message|
        enumerated_messages << message
      end
      enumerated_messages = enumerated_messages.sort_by(&:id)
      expect(enumerated_messages).to eq [message("Hello World!"), message("Title")]
    end

    it "does not yield any message if there are none" do
      enumerated_messages = []
      @messages.each do |message|
        enumerated_messages << message
      end
      expect(enumerated_messages).to eq []
    end
  end

  describe "#[]" do
    it "returns registered message" do
      @messages.register("Hello World!")
      expect(@messages["Hello World!"]).to eq message("Hello World!")
    end

    it "returns nil for nonexistent message ID" do
      expect(@messages["Hello World!"]).to eq nil
    end
  end

  describe "#register" do
    it "returns registered message" do
      expect(@messages.register("Hello World!")).to eq message("Hello World!")
    end

    it "returns existent message" do
      message = @messages.register("Hello World!")
      expect(@messages.register("Hello World!").object_id).to eq message.object_id
    end
  end

  describe "#==" do
    it "returns true for same value messages" do
      @messages.register("Hello World!")
      other_messages = messages
      other_messages.register("Hello World!")
      expect(@messages).to eq other_messages
    end
  end
end
yard-0.9.37/spec/i18n/pot_generator_spec.rb000066400000000000000000000204401466601756300205070ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::I18n::PotGenerator do
  def create_messages(messages)
    yard_messages = YARD::I18n::Messages.new
    add_messages(yard_messages, messages)
    yard_messages
  end

  def add_messages(yard_messages, messages)
    messages.each do |id, properties|
      yard_message = yard_messages.register(id)
      (properties[:locations] || []).each do |path, line|
        yard_message.add_location(path, line)
      end
      (properties[:comments] || []).each do |comment|
        yard_message.add_comment(comment)
      end
    end
  end

  before do
    @generator = YARD::I18n::PotGenerator.new("..")
  end

  describe "Generate" do
    it "generates the default header" do
      current_time = Time.parse("2011-11-20 22:17+0900")
      allow(@generator).to receive(:current_time).and_return(current_time)
      pot_creation_date = current_time.strftime("%Y-%m-%d %H:%M%z")
      expect(@generator.generate).to eq <<-eoh
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
# This file is distributed under the same license as the PACKAGE package.
# FIRST AUTHOR , YEAR.
#
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\\n"
"Report-Msgid-Bugs-To: \\n"
"POT-Creation-Date: #{pot_creation_date}\\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\\n"
"Last-Translator: FULL NAME \\n"
"Language-Team: LANGUAGE \\n"
"Language: \\n"
"MIME-Version: 1.0\\n"
"Content-Type: text/plain; charset=UTF-8\\n"
"Content-Transfer-Encoding: 8bit\\n"

eoh
    end

    it "generates messages in location order" do
      allow(@generator).to receive(:header).and_return("HEADER\n\n")
      messages = {
        "tag|see|Parser::SourceParser.parse" => {
          :locations => [["yard.rb", 14]],
          :comments => ["@see"]
        },
        "Parses a path or set of paths" => {
          :locations => [["yard.rb", 12], ["yard/parser/source_parser.rb", 83]],
          :comments => ["YARD.parse", "YARD::Parser::SourceParser.parse"]
        }
      }
      add_messages(@generator.messages, messages)
      expect(@generator.generate).to eq <<-'eoh'
HEADER

# YARD.parse
# YARD::Parser::SourceParser.parse
#: ../yard.rb:12
#: ../yard/parser/source_parser.rb:83
msgid "Parses a path or set of paths"
msgstr ""

# @see
#: ../yard.rb:14
msgid "tag|see|Parser::SourceParser.parse"
msgstr ""

eoh
    end
  end

  describe "Escape" do
    def generate_message_pot(message_id)
      pot = String.new("")
      message = YARD::I18n::Message.new(message_id)
      @generator.send(:generate_message, pot, message)
      pot
    end

    it "escapes <\\>" do
      expect(generate_message_pot("hello \\ world")).to eq <<-'eop'
msgid "hello \\ world"
msgstr ""

eop
    end

    it "escapes <\">" do
      expect(generate_message_pot("hello \" world")).to eq <<-'eop'
msgid "hello \" world"
msgstr ""

eop
    end

    it "escapes <\\n>" do
      expect(generate_message_pot("hello \n world")).to eq <<-'eop'
msgid "hello \n"
" world"
msgstr ""

eop
    end
  end

  describe "Object" do
    before do
      Registry.clear
      @yard = YARD::CodeObjects::ModuleObject.new(:root, :YARD)
    end

    it "extracts at docstring" do
      object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
        o.docstring = "An alias to {Parser::SourceParser}'s parsing method"
      end
      @generator.parse_objects([object])
      expect(@generator.messages).to eq create_messages(
        "An alias to {Parser::SourceParser}'s parsing method" => {
          :locations => [],
          :comments => ["YARD.parse"]
        }
      )
    end

    it "extracts at location" do
      object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
        o.docstring = "An alias to {Parser::SourceParser}'s parsing method"
        o.files = [["yard.rb", 12]]
      end
      @generator.parse_objects([object])
      expect(@generator.messages).to eq create_messages(
        "An alias to {Parser::SourceParser}'s parsing method" => {
          :locations => [["yard.rb", 13]],
          :comments => ["YARD.parse"]
        }
      )
    end

    it "extracts at tag name" do
      object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
        o.docstring = "@see Parser::SourceParser.parse"
        o.files = [["yard.rb", 12]]
      end
      @generator.parse_objects([object])
      expect(@generator.messages).to eq create_messages(
        "tag|see|Parser::SourceParser.parse" => {
          :locations => [["yard.rb", 12]],
          :comments => ["@see"]
        }
      )
    end

    it "extracts at tag text" do
      object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
        o.docstring = <<-eod
@example Parse a glob of files
  YARD.parse('lib/**/*.rb')
eod
        o.files = [["yard.rb", 12]]
      end
      @generator.parse_objects([object])
      expect(@generator.messages).to eq create_messages(
        "tag|example|Parse a glob of files" => {
          :locations => [["yard.rb", 12]],
          :comments => ["@example"]
        },
        "YARD.parse('lib/**/*.rb')" => {
          :locations => [["yard.rb", 12]],
          :comments => ["@example Parse a glob of files"]
        }
      )
    end

    it "extracts at tag types" do
      object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
        o.docstring = <<-eod
@param [String, Array] paths a path, glob, or list of paths to
  parse
eod
        o.files = [["yard.rb", 12]]
      end
      @generator.parse_objects([object])
      expect(@generator.messages).to eq create_messages(
        "tag|param|paths" => {
          :locations => [["yard.rb", 12]],
          :comments => ["@param [String, Array]"]
        },
        "a path, glob, or list of paths to\nparse" => {
          :locations => [["yard.rb", 12]],
          :comments => ["@param [String, Array] paths"]
        }
      )
    end

    it "extracts at overload tag recursively" do
      object = YARD::CodeObjects::MethodObject.new(@yard, :parse, :module) do |o|
        o.docstring = <<-eod
@overload foo(i)
  docstring foo(i)
  @param [Integer] i integer parameter
eod
      end

      @generator.parse_objects([object])
      expect(@generator.messages).to eq create_messages(
        "tag|overload|foo" => {
          :locations => [],
          :comments => ["@overload"]
        },
        "docstring foo(i)" => {
          :locations => [],
          :comments => ["YARD.parse"]
        },
        "tag|param|i" => {
          :locations => [],
          :comments => ["@param [Integer]"]
        },
        "integer parameter" => {
          :locations => [],
          :comments => ["@param [Integer] i"]
        }
      )
    end
  end

  describe "File" do
    it "extracts at attribute" do
      path = "GettingStarted.md"
      text = <<-eor
# @title Getting Started Guide

# Getting Started with YARD
eor
      allow(File).to receive(:open).with(path).and_yield(StringIO.new(text))
      allow(File).to receive(:read).with(path).and_return(text)
      file = YARD::CodeObjects::ExtraFileObject.new(path)
      @generator.parse_files([file])
      expect(@generator.messages).to eq create_messages(
        "Getting Started Guide" => {
          :locations => [[path, 1]],
          :comments => ["title"]
        },
        "# Getting Started with YARD" => {
          :locations => [[path, 3]],
          :comments => []
        }
      )
    end

    it "extracts at paragraphs" do
      path = "README.md"
      paragraph1 = <<-eop.strip
Note that class methods must not be referred to with the "::" namespace
separator. Only modules, classes and constants should use "::".
eop
      paragraph2 = <<-eop.strip
You can also do lookups on any installed gems. Just make sure to build the
.yardoc databases for installed gems with:
eop
      text = <<-eot
#{paragraph1}

#{paragraph2}
eot
      allow(File).to receive(:open).with(path).and_yield(StringIO.new(text))
      allow(File).to receive(:read).with(path).and_return(text)
      file = YARD::CodeObjects::ExtraFileObject.new(path)
      @generator.parse_files([file])
      expect(@generator.messages).to eq create_messages(
        paragraph1 => {
          :locations => [[path, 1]],
          :comments => []
        },
        paragraph2 => {
          :locations => [[path, 4]],
          :comments => []
        }
      )
    end
  end
end
yard-0.9.37/spec/i18n/text_spec.rb000066400000000000000000000075431466601756300166340ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::I18n::Text do
  describe "#extract_messages" do
    def extract_messages(input, options = {})
      text = YARD::I18n::Text.new(StringIO.new(input), options)
      messages = []
      text.extract_messages do |*message|
        messages << message
      end
      messages
    end

    describe "Header" do
      it "extracts at attribute" do
        text = <<-eot
# @title Getting Started Guide

# Getting Started with YARD
eot
        expect(extract_messages(text, :have_header => true)).to eq(
          [[:attribute, "title", "Getting Started Guide", 1],
           [:paragraph, "# Getting Started with YARD", 3]]
        )
      end

      it "ignores markup line" do
        text = <<-eot
#!markdown
# @title Getting Started Guide

# Getting Started with YARD
eot
        expect(extract_messages(text, :have_header => true)).to eq(
          [[:attribute, "title", "Getting Started Guide", 2],
           [:paragraph, "# Getting Started with YARD", 4]]
        )
      end

      it "terminates header block by markup line not at the first line" do
        text = <<-eot
# @title Getting Started Guide
#!markdown

# Getting Started with YARD
eot
        expect(extract_messages(text, :have_header => true)).to eq(
          [[:attribute, "title", "Getting Started Guide", 1],
           [:paragraph, "#!markdown", 2],
           [:paragraph, "# Getting Started with YARD", 4]]
        )
      end
    end

    describe "Body" do
      it "splits to paragraphs" do
        paragraph1 = <<-eop.strip
Note that class methods must not be referred to with the "::" namespace
separator. Only modules, classes and constants should use "::".
eop
        paragraph2 = <<-eop.strip
You can also do lookups on any installed gems. Just make sure to build the
.yardoc databases for installed gems with:
eop
        text = <<-eot
#{paragraph1}

#{paragraph2}
eot
        expect(extract_messages(text)).to eq(
          [[:paragraph, paragraph1, 1],
           [:paragraph, paragraph2, 4]]
        )
      end
    end
  end

  describe "#translate" do
    def locale
      locale = YARD::I18n::Locale.new("fr")
      messages = locale.instance_variable_get(:@messages)
      messages["markdown"] = "markdown (markdown in fr)"
      messages["Hello"] = "Bonjour (Hello in fr)"
      messages["Paragraph 1."] = "Paragraphe 1."
      messages["Paragraph 2."] = "Paragraphe 2."
      locale
    end

    def translate(input, options = {})
      text = YARD::I18n::Text.new(StringIO.new(input), options)
      text.translate(locale)
    end

    describe "Header" do
      it "extracts at attribute" do
        text = <<-eot
# @title Hello

# Getting Started with YARD

Paragraph.
eot
        expect(translate(text, :have_header => true)).to eq <<-eot
# @title Bonjour (Hello in fr)

# Getting Started with YARD

Paragraph.
eot
      end

      it "ignores markup line" do
        text = <<-eot
#!markdown
# @title Hello

# Getting Started with YARD

Paragraph.
eot
        expect(translate(text, :have_header => true)).to eq <<-eot
#!markdown
# @title Bonjour (Hello in fr)

# Getting Started with YARD

Paragraph.
eot
      end
    end

    describe "Body" do
      it "splits to paragraphs" do
        paragraph1 = <<-eop.strip
Paragraph 1.
eop
        paragraph2 = <<-eop.strip
Paragraph 2.
eop
        text = <<-eot
#{paragraph1}

#{paragraph2}
eot
        expect(translate(text)).to eq <<-eot
Paragraphe 1.

Paragraphe 2.
eot
      end

      it "does not modify non-translated message" do
        nonexistent_paragraph = <<-eop.strip
Nonexsitent paragraph.
eop
        text = <<-eot
#{nonexistent_paragraph}
eot
        expect(translate(text)).to eq <<-eot
#{nonexistent_paragraph}
eot
      end

      it "keeps empty lines" do
        text = <<-eot
Paragraph 1.




Paragraph 2.
eot
        expect(translate(text)).to eq <<-eot
Paragraphe 1.




Paragraphe 2.
eot
      end
    end
  end
end
yard-0.9.37/spec/logging_spec.rb000066400000000000000000000026021466601756300165060ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Logger do
  describe "#show_backtraces" do
    it "is true if debug level is on" do
      log.show_backtraces = true
      log.enter_level(Logger::DEBUG) do
        log.show_backtraces = false
        expect(log.show_backtraces).to be true
      end
      expect(log.show_backtraces).to be false
    end
  end

  describe "#backtrace" do
    before { log.show_backtraces = true }
    after  { log.show_backtraces = false }

    it "logs backtrace in error by default" do
      expect(log).to receive(:error).with("RuntimeError: foo")
      expect(log).to receive(:error).with("Stack trace:\n\tline1\n\tline2\n")
      exc = RuntimeError.new("foo")
      exc.set_backtrace(['line1', 'line2'])
      log.enter_level(Logger::INFO) { log.backtrace(exc) }
    end

    it "allows backtrace to be entered in other modes" do
      expect(log).to receive(:warn).with("RuntimeError: foo")
      expect(log).to receive(:warn).with("Stack trace:\n\tline1\n\tline2\n")
      exc = RuntimeError.new("foo")
      exc.set_backtrace(['line1', 'line2'])
      log.enter_level(Logger::INFO) { log.backtrace(exc, :warn) }
    end
  end

  describe '#warn' do
    before  { log.warned = false }
    after   { log.warned = false }

    it 'changes #warned from false to true' do
      expect { log.warn('message') }.to change(log, :warned).from(false).to(true)
    end
  end
end
yard-0.9.37/spec/options_spec.rb000066400000000000000000000111411466601756300165510ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Options do
  class FooOptions < YARD::Options
    attr_accessor :foo
    def initialize; self.foo = "abc" end
  end

  describe ".default_attr" do
    it "allows default attributes to be defined with symbols" do
      class DefaultOptions1 < YARD::Options
        default_attr :foo, 'HELLO'
      end
      o = DefaultOptions1.new
      o.reset_defaults
      expect(o.foo).to eq 'HELLO'
    end

    it "calls lambda if value is a Proc" do
      class DefaultOptions2 < YARD::Options
        default_attr :foo, lambda { 100 }
      end
      o = DefaultOptions2.new
      o.reset_defaults
      expect(o.foo).to eq 100
    end
  end

  describe "#reset_defaults" do
    it "does not define defaults until reset is called" do
      class ResetDefaultOptions1 < YARD::Options
        default_attr :foo, 'FOO'
      end
      expect(ResetDefaultOptions1.new.foo).to be nil
      o = ResetDefaultOptions1.new
      o.reset_defaults
      expect(o.foo).to eq 'FOO'
    end

    it "uses defaults from superclass as well" do
      class ResetDefaultOptions2 < YARD::Options
        default_attr :foo, 'FOO'
      end
      class ResetDefaultOptions3 < ResetDefaultOptions2
      end
      o = ResetDefaultOptions3.new
      o.reset_defaults
      expect(o.foo).to eq 'FOO'
    end
  end

  describe "#delete" do
    it "deletes an option" do
      o = FooOptions.new
      o.delete(:foo)
      expect(o.to_hash).to eq({})
    end

    it "does not error if an option is deleted that does not exist" do
      o = FooOptions.new
      o.delete(:foo)
      o.delete(:foo)
      expect(o.to_hash).to eq({})
    end
  end

  describe "#[]" do
    it "handles getting option values using hash syntax" do
      expect(FooOptions.new[:foo]).to eq "abc"
    end
  end

  describe "#[]=" do
    it "handles setting options using hash syntax" do
      o = FooOptions.new
      o[:foo] = "xyz"
      expect(o[:foo]).to eq "xyz"
    end

    it "allows setting of unregistered keys" do
      o = FooOptions.new
      o[:bar] = "foo"
      expect(o[:bar]).to eq "foo"
    end
  end

  describe "#method_missing" do
    it "allows setting of unregistered keys" do
      o = FooOptions.new
      o.bar = 'foo'
      expect(o.bar).to eq 'foo'
    end

    it "allows getting values of unregistered keys (return nil)" do
      expect(FooOptions.new.bar).to be nil
    end

    it "prints debugging messages about unregistered keys" do
      expect(log).to receive(:debug).with("Attempting to access unregistered key bar on FooOptions")
      FooOptions.new.bar
      expect(log).to receive(:debug).with("Attempting to set unregistered key bar on FooOptions")
      FooOptions.new.bar = 1
    end
  end

  describe "#update" do
    it "allows updating of options" do
      expect(FooOptions.new.update(:foo => "xyz").foo).to eq "xyz"
    end

    it "does not ignore keys with no setter (OpenStruct behaviour)" do
      o = FooOptions.new
      o.update(:bar => "xyz")
      expect(o.to_hash).to eq(:foo => "abc", :bar => "xyz")
    end
  end

  describe "#merge" do
    it "updates a new object" do
      o = FooOptions.new
      expect(o.merge(:foo => "xyz").object_id).not_to eq o.object_id
      expect(o.merge(:foo => "xyz").to_hash).to eq(:foo => "xyz")
    end

    it "adds in values from original object" do
      o = FooOptions.new
      o.update(:bar => "foo")
      expect(o.merge(:baz => 1).to_hash).to eq(:foo => "abc", :bar => "foo", :baz => 1)
    end
  end

  describe "#to_hash" do
    it "converts all instance variables and symbolized keys" do
      class ToHashOptions1 < YARD::Options
        attr_accessor :foo, :bar, :baz
        def initialize; @foo = 1; @bar = 2; @baz = "hello" end
      end
      o = ToHashOptions1.new
      hash = o.to_hash
      expect(hash.keys).to include(:foo, :bar, :baz)
      expect(hash[:foo]).to eq 1
      expect(hash[:bar]).to eq 2
      expect(hash[:baz]).to eq "hello"
    end

    it "uses accessor when converting values to hash" do
      class ToHashOptions2 < YARD::Options
        def initialize; @foo = 1 end
        def foo; "HELLO#{@foo}" end
      end
      o = ToHashOptions2.new
      expect(o.to_hash).to eq(:foo => "HELLO1")
    end

    it "ignores ivars with no accessor" do
      class ToHashOptions3 < YARD::Options
        attr_accessor :foo
        def initialize; @foo = 1; @bar = "NOIGNORE" end
      end
      o = ToHashOptions3.new
      expect(o.to_hash).to eq(:foo => 1, :bar => "NOIGNORE")
    end
  end

  describe "#tap" do
    it "supports #tap(&block) (even in 1.8.6)" do
      o = FooOptions.new.tap {|obj| obj.foo = :BAR }
      expect(o.to_hash).to eq(:foo => :BAR)
    end
  end
end
yard-0.9.37/spec/parser/000077500000000000000000000000001466601756300150155ustar00rootroot00000000000000yard-0.9.37/spec/parser/base_spec.rb000066400000000000000000000014071466601756300172700ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Parser::Base do
  describe "#initialize" do
    class MyParser < Parser::Base; def initialize(a, b) end end

    it "takes 2 arguments" do
      expect { YARD::Parser::Base.new }.to raise_error(ArgumentError,
        /wrong (number|#) of arguments|given 0, expected 2/)
    end

    it "raises NotImplementedError on #initialize" do
      expect { YARD::Parser::Base.new('a', 'b') }.to raise_error(NotImplementedError)
    end

    it "raises NotImplementedError on #parse" do
      expect { MyParser.new('a', 'b').parse }.to raise_error(NotImplementedError)
    end

    it "raises NotImplementedError on #tokenize" do
      expect { MyParser.new('a', 'b').tokenize }.to raise_error(NotImplementedError)
    end
  end
end
yard-0.9.37/spec/parser/c_parser_spec.rb000066400000000000000000000175311466601756300201610ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Parser::C::CParser do
  describe "#parse" do
    def parse(contents)
      Registry.clear
      YARD.parse_string(contents, :c)
    end

    describe "Array class" do
      before(:all) do
        file = File.join(File.dirname(__FILE__), 'examples', 'array.c.txt')
        parse(File.read(file))
      end

      it "parses Array class" do
        obj = YARD::Registry.at('Array')
        expect(obj).not_to be nil
        expect(obj.docstring).not_to be_blank
      end

      it "parses method" do
        obj = YARD::Registry.at('Array#initialize')
        expect(obj.docstring).not_to be_blank
        expect(obj.tags(:overload).size).to be > 1
      end

      it "parses new_ary return type" do
        obj = YARD::Registry.at('Array#map')
        expect(obj.tags(:overload).count do |overload|
          overload.tag(:return) && overload.tag(:return).types == ['Enumerator']
        end).to eq 2
        expect(obj.tags(:overload).count do |overload|
          overload.tag(:return) && overload.tag(:return).types == ['Array']
        end).to eq 2
      end
    end

    describe "C++ namespace" do
      before(:all) do
        file = File.join(File.dirname(__FILE__), 'examples', 'namespace.cpp.txt')
        parse(File.read(file))
      end

      it "parses Rect class" do
        obj = YARD::Registry.at('Rect')
        expect(obj).not_to be nil
        expect(obj.docstring).not_to be_blank
      end

      it "parses method inside of namespace" do
        obj = YARD::Registry.at('Rect#inspect')
        expect(obj.docstring).not_to be_blank
      end

      it "parses method after namespace" do
        obj = YARD::Registry.at('Rect#hello_world')
        expect(obj.docstring).not_to be_blank
      end
    end

    describe "Source located in extra files" do
      before(:all) do
        @multifile = File.join(File.dirname(__FILE__), 'examples', 'multifile.c.txt')
        @extrafile = File.join(File.dirname(__FILE__), 'examples', 'extrafile.c.txt')
        @contents = File.read(@multifile)
      end

      it "looks for methods in extra files (if 'in' comment is found)" do
        extra_contents = File.read(@extrafile)
        expect(File).to receive(:read).with('extra.c').and_return(extra_contents)
        parse(@contents)
        expect(Registry.at('Multifile#extra').docstring).to eq 'foo'
      end

      it "stops searching for extra source file gracefully if file is not found" do
        expect(File).to receive(:read).with('extra.c').and_raise(Errno::ENOENT)
        expect(log).to receive(:warn).with("Missing source file `extra.c' when parsing Multifile#extra")
        parse(@contents)
        expect(Registry.at('Multifile#extra').docstring).to eq ''
      end

      it "differentiates between a struct and a pointer to a struct retval" do
        parse(@contents)
        expect(Registry.at('Multifile#hello_mars').docstring).to eq 'Hello Mars'
      end
    end

    describe "Foo class" do
      it "does not include comments in docstring source" do
        parse <<-eof
          /*
           * Hello world
           */
          VALUE foo(VALUE x) {
            int value = x;
          }

          void Init_Foo() {
            rb_define_method(rb_cFoo, "foo", foo, 1);
          }
        eof
        expect(Registry.at('Foo#foo').source.gsub(/\s\s+/, ' ')).to eq(
          "VALUE foo(VALUE x) { int value = x;\n}"
        )
      end
    end

    describe "Class inherited from core error class" do
      it "resolves correct name" do
        parse <<-eof
          void
          Init_Mask(void)
          {
              rb_cFoo = rb_define_class("Foo", rb_cObject);
              rb_cMyError = rb_define_class("MyError", rb_eArgError);
          }
        eof
        klass = Registry.at('MyError')
        expect(klass.name).to eq :MyError
        expect(klass.title).to eq 'MyError'
        expect(klass.superclass.name).to eq :ArgumentError
        expect(klass.superclass.title).to eq 'ArgumentError'
      end
    end

    describe "Constant" do
      it "does not truncate docstring" do
        parse <<-eof
          #define MSK_DEADBEEF 0xdeadbeef
          void
          Init_Mask(void)
          {
              rb_cMask  = rb_define_class("Mask", rb_cObject);
              /* 0xdeadbeef: This constant is frequently used to indicate a
               * software crash or deadlock in embedded systems. */
              rb_define_const(rb_cMask, "DEADBEEF", INT2FIX(MSK_DEADBEEF));
          }
        eof
        constant = Registry.at('Mask::DEADBEEF')
        expect(constant.value).to eq '0xdeadbeef'
        expect(constant.docstring).to eq "This constant is frequently used to indicate a\nsoftware crash or deadlock in embedded systems."
      end
    end

    describe "Macros" do
      it "handles param## inside of macros" do
        thr = Thread.new do
          parse <<-eof
          void
          Init_gobject_gparamspecs(void)
          {
              VALUE cParamSpec = GTYPE2CLASS(G_TYPE_PARAM);
              VALUE c;

          #define DEF_NUMERIC_PSPEC_METHODS(c, typename) \
            G_STMT_START {\
              rbg_define_method(c, "initialize", typename##_initialize, 7); \
              rbg_define_method(c, "minimum", typename##_minimum, 0); \
              rbg_define_method(c, "maximum", typename##_maximum, 0); \
              rbg_define_method(c, "range", typename##_range, 0); \
            } G_STMT_END

          #if 0
              rbg_define_method(c, "default_value", typename##_default_value, 0); \
              rb_define_alias(c, "default", "default_value"); \

          #endif

              c = G_DEF_CLASS(G_TYPE_PARAM_CHAR, "Char", cParamSpec);
              DEF_NUMERIC_PSPEC_METHODS(c, char);
          eof
        end
        thr.join(5)
        if thr.alive?
          thr.kill
          raise "Did not parse in time"
        end
      end
    end

    describe "C macros in declaration" do
      it "handles C macros in method declaration" do
        Registry.clear
        parse <<-eof
        // docstring
        FOOBAR VALUE func() { }

        void
        Init_mod(void)
        {
          rb_define_method(rb_cFoo, "func", func, 0); \
        }
        eof

        expect(Registry.at('Foo#func').docstring).to eq "docstring"
      end
    end

    describe "File singleton methods" do
      before(:all) do
        file = File.join(File.dirname(__FILE__), 'examples', 'file.c.txt')
        parse(File.read(file))
      end

      it "parses methods from define_filetest_function" do
        obj = YARD::Registry.at('File.exist?')
        expect(obj).not_to be nil
        expect(obj.docstring).not_to be_blank
      end
    end
  end

  describe "Override comments" do
    before(:all) do
      Registry.clear
      override_file = File.join(File.dirname(__FILE__), 'examples', 'override.c.txt')
      @override_parser = YARD.parse_string(File.read(override_file), :c)
    end

    it "parses GMP::Z class" do
      z = YARD::Registry.at('GMP::Z')
      expect(z).not_to be nil
      expect(z.docstring).not_to be_blank
    end

    it "parses GMP::Z methods w/ bodies" do
      add = YARD::Registry.at('GMP::Z#+')
      expect(add.docstring).not_to be_blank
      expect(add.source).not_to be nil
      expect(add.source).not_to be_empty

      add_self = YARD::Registry.at('GMP::Z#+')
      expect(add_self.docstring).not_to be_blank
      expect(add_self.source).not_to be nil
      expect(add_self.source).not_to be_empty

      sqrtrem = YARD::Registry.at('GMP::Z#+')
      expect(sqrtrem.docstring).not_to be_blank
      expect(sqrtrem.source).not_to be nil
      expect(sqrtrem.source).not_to be_empty
    end

    it "parses GMP::Z methods w/o bodies" do
      neg = YARD::Registry.at('GMP::Z#neg')
      expect(neg.docstring).not_to be_blank
      expect(neg.source).to be nil

      neg_self = YARD::Registry.at('GMP::Z#neg')
      expect(neg_self.docstring).not_to be_blank
      expect(neg_self.source).to be nil
    end
  end
end
yard-0.9.37/spec/parser/examples/000077500000000000000000000000001466601756300166335ustar00rootroot00000000000000yard-0.9.37/spec/parser/examples/array.c.txt000066400000000000000000004733551466601756300207540ustar00rootroot00000000000000/**********************************************************************

  array.c -

  $Author$
  created at: Fri Aug  6 09:46:12 JST 1993

  Copyright (C) 1993-2007 Yukihiro Matsumoto
  Copyright (C) 2000  Network Applied Communication Laboratory, Inc.
  Copyright (C) 2000  Information-technology Promotion Agency, Japan

**********************************************************************/

#include "internal.h"
#include "ruby/util.h"
#include "ruby/st.h"
#include "probes.h"
#include "id.h"
#include "debug_counter.h"

#ifndef ARRAY_DEBUG
# define NDEBUG
#endif
#include "ruby_assert.h"

VALUE rb_cArray;

static ID id_div;

/* for OPTIMIZED_CMP: */
#define id_cmp idCmp

#define ARY_DEFAULT_SIZE 16
#define ARY_MAX_SIZE (LONG_MAX / (int)sizeof(VALUE))

# define ARY_SHARED_P(ary) \
    (assert(!FL_TEST((ary), ELTS_SHARED) || !FL_TEST((ary), RARRAY_EMBED_FLAG)), \
     FL_TEST((ary),ELTS_SHARED)!=0)
# define ARY_EMBED_P(ary) \
    (assert(!FL_TEST((ary), ELTS_SHARED) || !FL_TEST((ary), RARRAY_EMBED_FLAG)), \
     FL_TEST((ary), RARRAY_EMBED_FLAG)!=0)

#define ARY_HEAP_PTR(a) (assert(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.ptr)
#define ARY_HEAP_LEN(a) (assert(!ARY_EMBED_P(a)), RARRAY(a)->as.heap.len)
#define ARY_EMBED_PTR(a) (assert(ARY_EMBED_P(a)), RARRAY(a)->as.ary)
#define ARY_EMBED_LEN(a) \
    (assert(ARY_EMBED_P(a)), \
     (long)((RBASIC(a)->flags >> RARRAY_EMBED_LEN_SHIFT) & \
	 (RARRAY_EMBED_LEN_MASK >> RARRAY_EMBED_LEN_SHIFT)))
#define ARY_HEAP_SIZE(a) (assert(!ARY_EMBED_P(a)), assert(ARY_OWNS_HEAP_P(a)), RARRAY(a)->as.heap.aux.capa * sizeof(VALUE))

#define ARY_OWNS_HEAP_P(a) (!FL_TEST((a), ELTS_SHARED|RARRAY_EMBED_FLAG))
#define FL_SET_EMBED(a) do { \
    assert(!ARY_SHARED_P(a)); \
    FL_SET((a), RARRAY_EMBED_FLAG); \
} while (0)
#define FL_UNSET_EMBED(ary) FL_UNSET((ary), RARRAY_EMBED_FLAG|RARRAY_EMBED_LEN_MASK)
#define FL_SET_SHARED(ary) do { \
    assert(!ARY_EMBED_P(ary)); \
    FL_SET((ary), ELTS_SHARED); \
} while (0)
#define FL_UNSET_SHARED(ary) FL_UNSET((ary), ELTS_SHARED)

#define ARY_SET_PTR(ary, p) do { \
    assert(!ARY_EMBED_P(ary)); \
    assert(!OBJ_FROZEN(ary)); \
    RARRAY(ary)->as.heap.ptr = (p); \
} while (0)
#define ARY_SET_EMBED_LEN(ary, n) do { \
    long tmp_n = (n); \
    assert(ARY_EMBED_P(ary)); \
    assert(!OBJ_FROZEN(ary)); \
    RBASIC(ary)->flags &= ~RARRAY_EMBED_LEN_MASK; \
    RBASIC(ary)->flags |= (tmp_n) << RARRAY_EMBED_LEN_SHIFT; \
} while (0)
#define ARY_SET_HEAP_LEN(ary, n) do { \
    assert(!ARY_EMBED_P(ary)); \
    RARRAY(ary)->as.heap.len = (n); \
} while (0)
#define ARY_SET_LEN(ary, n) do { \
    if (ARY_EMBED_P(ary)) { \
        ARY_SET_EMBED_LEN((ary), (n)); \
    } \
    else { \
        ARY_SET_HEAP_LEN((ary), (n)); \
    } \
    assert(RARRAY_LEN(ary) == (n)); \
} while (0)
#define ARY_INCREASE_PTR(ary, n) do  { \
    assert(!ARY_EMBED_P(ary)); \
    assert(!OBJ_FROZEN(ary)); \
    RARRAY(ary)->as.heap.ptr += (n); \
} while (0)
#define ARY_INCREASE_LEN(ary, n) do  { \
    assert(!OBJ_FROZEN(ary)); \
    if (ARY_EMBED_P(ary)) { \
        ARY_SET_EMBED_LEN((ary), RARRAY_LEN(ary)+(n)); \
    } \
    else { \
        RARRAY(ary)->as.heap.len += (n); \
    } \
} while (0)

#define ARY_CAPA(ary) (ARY_EMBED_P(ary) ? RARRAY_EMBED_LEN_MAX : \
		       ARY_SHARED_ROOT_P(ary) ? RARRAY_LEN(ary) : RARRAY(ary)->as.heap.aux.capa)
#define ARY_SET_CAPA(ary, n) do { \
    assert(!ARY_EMBED_P(ary)); \
    assert(!ARY_SHARED_P(ary)); \
    assert(!OBJ_FROZEN(ary)); \
    RARRAY(ary)->as.heap.aux.capa = (n); \
} while (0)

#define ARY_SHARED(ary) (assert(ARY_SHARED_P(ary)), RARRAY(ary)->as.heap.aux.shared)
#define ARY_SET_SHARED(ary, value) do { \
    const VALUE _ary_ = (ary); \
    const VALUE _value_ = (value); \
    assert(!ARY_EMBED_P(_ary_)); \
    assert(ARY_SHARED_P(_ary_)); \
    assert(ARY_SHARED_ROOT_P(_value_)); \
    RB_OBJ_WRITE(_ary_, &RARRAY(_ary_)->as.heap.aux.shared, _value_); \
} while (0)
#define RARRAY_SHARED_ROOT_FLAG FL_USER5
#define ARY_SHARED_ROOT_P(ary) (FL_TEST((ary), RARRAY_SHARED_ROOT_FLAG))
#define ARY_SHARED_NUM(ary) \
    (assert(ARY_SHARED_ROOT_P(ary)), RARRAY(ary)->as.heap.aux.capa)
#define ARY_SHARED_OCCUPIED(ary) (ARY_SHARED_NUM(ary) == 1)
#define ARY_SET_SHARED_NUM(ary, value) do { \
    assert(ARY_SHARED_ROOT_P(ary)); \
    RARRAY(ary)->as.heap.aux.capa = (value); \
} while (0)
#define FL_SET_SHARED_ROOT(ary) do { \
    assert(!ARY_EMBED_P(ary)); \
    FL_SET((ary), RARRAY_SHARED_ROOT_FLAG); \
} while (0)

#define ARY_SET(a, i, v) RARRAY_ASET((assert(!ARY_SHARED_P(a)), (a)), (i), (v))

void
rb_mem_clear(register VALUE *mem, register long size)
{
    while (size--) {
	*mem++ = Qnil;
    }
}

static void
ary_mem_clear(VALUE ary, long beg, long size)
{
    RARRAY_PTR_USE(ary, ptr, {
	rb_mem_clear(ptr + beg, size);
    });
}

static inline void
memfill(register VALUE *mem, register long size, register VALUE val)
{
    while (size--) {
	*mem++ = val;
    }
}

static void
ary_memfill(VALUE ary, long beg, long size, VALUE val)
{
    RARRAY_PTR_USE(ary, ptr, {
	memfill(ptr + beg, size, val);
	RB_OBJ_WRITTEN(ary, Qundef, val);
    });
}

static void
ary_memcpy0(VALUE ary, long beg, long argc, const VALUE *argv, VALUE buff_owner_ary)
{
#if 1
    assert(!ARY_SHARED_P(buff_owner_ary));

    if (argc > (int)(128/sizeof(VALUE)) /* is magic number (cache line size) */) {
	rb_gc_writebarrier_remember(buff_owner_ary);
	RARRAY_PTR_USE(ary, ptr, {
	    MEMCPY(ptr+beg, argv, VALUE, argc);
	});
    }
    else {
	int i;
	RARRAY_PTR_USE(ary, ptr, {
	    for (i=0; i RARRAY_EMBED_LEN_MAX) {
        if (ARY_EMBED_P(ary)) {
            long len = ARY_EMBED_LEN(ary);
            VALUE *ptr = ALLOC_N(VALUE, (capacity));
            MEMCPY(ptr, ARY_EMBED_PTR(ary), VALUE, len);
            FL_UNSET_EMBED(ary);
            ARY_SET_PTR(ary, ptr);
            ARY_SET_HEAP_LEN(ary, len);
        }
        else {
	    SIZED_REALLOC_N(RARRAY(ary)->as.heap.ptr, VALUE, capacity, RARRAY(ary)->as.heap.aux.capa);
        }
        ARY_SET_CAPA(ary, (capacity));
    }
    else {
        if (!ARY_EMBED_P(ary)) {
            long len = RARRAY_LEN(ary);
	    const VALUE *ptr = RARRAY_CONST_PTR(ary);

	    if (len > capacity) len = capacity;
            MEMCPY((VALUE *)RARRAY(ary)->as.ary, ptr, VALUE, len);
            FL_SET_EMBED(ary);
            ARY_SET_LEN(ary, len);
	    ruby_xfree((VALUE *)ptr);
        }
    }
}

static inline void
ary_shrink_capa(VALUE ary)
{
    long capacity = ARY_HEAP_LEN(ary);
    long old_capa = RARRAY(ary)->as.heap.aux.capa;
    assert(!ARY_SHARED_P(ary));
    assert(old_capa >= capacity);
    if (old_capa > capacity)
	REALLOC_N(RARRAY(ary)->as.heap.ptr, VALUE, capacity);
}

static void
ary_double_capa(VALUE ary, long min)
{
    long new_capa = ARY_CAPA(ary) / 2;

    if (new_capa < ARY_DEFAULT_SIZE) {
	new_capa = ARY_DEFAULT_SIZE;
    }
    if (new_capa >= ARY_MAX_SIZE - min) {
	new_capa = (ARY_MAX_SIZE - min) / 2;
    }
    new_capa += min;
    ary_resize_capa(ary, new_capa);
}

static void
rb_ary_decrement_share(VALUE shared)
{
    if (shared) {
	long num = ARY_SHARED_NUM(shared) - 1;
	if (num == 0) {
	    rb_ary_free(shared);
	    rb_gc_force_recycle(shared);
	}
	else if (num > 0) {
	    ARY_SET_SHARED_NUM(shared, num);
	}
    }
}

static void
rb_ary_unshare(VALUE ary)
{
    VALUE shared = RARRAY(ary)->as.heap.aux.shared;
    rb_ary_decrement_share(shared);
    FL_UNSET_SHARED(ary);
}

static inline void
rb_ary_unshare_safe(VALUE ary)
{
    if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) {
	rb_ary_unshare(ary);
    }
}

static VALUE
rb_ary_increment_share(VALUE shared)
{
    long num = ARY_SHARED_NUM(shared);
    if (num >= 0) {
	ARY_SET_SHARED_NUM(shared, num + 1);
    }
    return shared;
}

static void
rb_ary_set_shared(VALUE ary, VALUE shared)
{
    rb_ary_increment_share(shared);
    FL_SET_SHARED(ary);
    ARY_SET_SHARED(ary, shared);
}

static inline void
rb_ary_modify_check(VALUE ary)
{
    rb_check_frozen(ary);
}

void
rb_ary_modify(VALUE ary)
{
    rb_ary_modify_check(ary);
    if (ARY_SHARED_P(ary)) {
	long shared_len, len = RARRAY_LEN(ary);
	VALUE shared = ARY_SHARED(ary);
        if (len <= RARRAY_EMBED_LEN_MAX) {
	    const VALUE *ptr = ARY_HEAP_PTR(ary);
            FL_UNSET_SHARED(ary);
            FL_SET_EMBED(ary);
	    MEMCPY((VALUE *)ARY_EMBED_PTR(ary), ptr, VALUE, len);
            rb_ary_decrement_share(shared);
            ARY_SET_EMBED_LEN(ary, len);
        }
	else if (ARY_SHARED_OCCUPIED(shared) && len > ((shared_len = RARRAY_LEN(shared))>>1)) {
	    long shift = RARRAY_CONST_PTR(ary) - RARRAY_CONST_PTR(shared);
	    FL_UNSET_SHARED(ary);
	    ARY_SET_PTR(ary, RARRAY_CONST_PTR(shared));
	    ARY_SET_CAPA(ary, shared_len);
	    RARRAY_PTR_USE(ary, ptr, {
		MEMMOVE(ptr, ptr+shift, VALUE, len);
	    });
	    FL_SET_EMBED(shared);
	    rb_ary_decrement_share(shared);
	}
        else {
            VALUE *ptr = ALLOC_N(VALUE, len);
            MEMCPY(ptr, RARRAY_CONST_PTR(ary), VALUE, len);
            rb_ary_unshare(ary);
            ARY_SET_CAPA(ary, len);
            ARY_SET_PTR(ary, ptr);
        }

	rb_gc_writebarrier_remember(ary);
    }
}

static VALUE
ary_ensure_room_for_push(VALUE ary, long add_len)
{
    long old_len = RARRAY_LEN(ary);
    long new_len = old_len + add_len;
    long capa;

    if (old_len > ARY_MAX_SIZE - add_len) {
	rb_raise(rb_eIndexError, "index %ld too big", new_len);
    }
    if (ARY_SHARED_P(ary)) {
	if (new_len > RARRAY_EMBED_LEN_MAX) {
	    VALUE shared = ARY_SHARED(ary);
	    if (ARY_SHARED_OCCUPIED(shared)) {
		if (RARRAY_CONST_PTR(ary) - RARRAY_CONST_PTR(shared) + new_len <= RARRAY_LEN(shared)) {
		    rb_ary_modify_check(ary);
		    return shared;
		}
		else {
		    /* if array is shared, then it is likely it participate in push/shift pattern */
		    rb_ary_modify(ary);
		    capa = ARY_CAPA(ary);
		    if (new_len > capa - (capa >> 6)) {
			ary_double_capa(ary, new_len);
		    }
		    return ary;
		}
	    }
	}
	rb_ary_modify(ary);
    }
    else {
	rb_ary_modify_check(ary);
    }
    capa = ARY_CAPA(ary);
    if (new_len > capa) {
	ary_double_capa(ary, new_len);
    }

    return ary;
}

/*
 *  call-seq:
 *      ary.freeze -> ary
 *
 *  Calls Object#freeze on +ary+ to prevent any further
 *  modification. A RuntimeError will be raised if a modification
 *  attempt is made.
 *
 */

VALUE
rb_ary_freeze(VALUE ary)
{
    return rb_obj_freeze(ary);
}

/*
 *  call-seq:
 *     ary.frozen?  -> true or false
 *
 *  Return +true+ if this array is frozen (or temporarily frozen
 *  while being sorted). See also Object#frozen?
 */

static VALUE
rb_ary_frozen_p(VALUE ary)
{
    if (OBJ_FROZEN(ary)) return Qtrue;
    return Qfalse;
}

/* This can be used to take a snapshot of an array (with
   e.g. rb_ary_replace) and check later whether the array has been
   modified from the snapshot.  The snapshot is cheap, though if
   something does modify the array it will pay the cost of copying
   it.  If Array#pop or Array#shift has been called, the array will
   be still shared with the snapshot, but the array length will
   differ. */
VALUE
rb_ary_shared_with_p(VALUE ary1, VALUE ary2)
{
    if (!ARY_EMBED_P(ary1) && ARY_SHARED_P(ary1) &&
	!ARY_EMBED_P(ary2) && ARY_SHARED_P(ary2) &&
	RARRAY(ary1)->as.heap.aux.shared == RARRAY(ary2)->as.heap.aux.shared &&
	RARRAY(ary1)->as.heap.len == RARRAY(ary2)->as.heap.len) {
	return Qtrue;
    }
    return Qfalse;
}

static VALUE
ary_alloc(VALUE klass)
{
    NEWOBJ_OF(ary, struct RArray, klass, T_ARRAY | RARRAY_EMBED_FLAG | (RGENGC_WB_PROTECTED_ARRAY ? FL_WB_PROTECTED : 0));
    /* Created array is:
     *   FL_SET_EMBED((VALUE)ary);
     *   ARY_SET_EMBED_LEN((VALUE)ary, 0);
     */
    return (VALUE)ary;
}

static VALUE
empty_ary_alloc(VALUE klass)
{
    RUBY_DTRACE_CREATE_HOOK(ARRAY, 0);
    return ary_alloc(klass);
}

static VALUE
ary_new(VALUE klass, long capa)
{
    VALUE ary,*ptr;

    if (capa < 0) {
	rb_raise(rb_eArgError, "negative array size (or size too big)");
    }
    if (capa > ARY_MAX_SIZE) {
	rb_raise(rb_eArgError, "array size too big");
    }

    RUBY_DTRACE_CREATE_HOOK(ARRAY, capa);

    ary = ary_alloc(klass);
    if (capa > RARRAY_EMBED_LEN_MAX) {
	ptr = ALLOC_N(VALUE, capa);
        FL_UNSET_EMBED(ary);
        ARY_SET_PTR(ary, ptr);
        ARY_SET_CAPA(ary, capa);
        ARY_SET_HEAP_LEN(ary, 0);
    }

    return ary;
}

VALUE
rb_ary_new_capa(long capa)
{
    return ary_new(rb_cArray, capa);
}

VALUE
rb_ary_new(void)
{
    return rb_ary_new2(RARRAY_EMBED_LEN_MAX);
}

VALUE
(rb_ary_new_from_args)(long n, ...)
{
    va_list ar;
    VALUE ary;
    long i;

    ary = rb_ary_new2(n);

    va_start(ar, n);
    for (i=0; i 0 && elts) {
	ary_memcpy(ary, 0, n, elts);
	ARY_SET_LEN(ary, n);
    }

    return ary;
}

VALUE
rb_ary_new_from_values(long n, const VALUE *elts)
{
    return rb_ary_tmp_new_from_values(rb_cArray, n, elts);
}

VALUE
rb_ary_tmp_new(long capa)
{
    return ary_new(0, capa);
}

VALUE
rb_ary_tmp_new_fill(long capa)
{
    VALUE ary = ary_new(0, capa);
    ary_memfill(ary, 0, capa, Qnil);
    ARY_SET_LEN(ary, capa);
    return ary;
}

void
rb_ary_free(VALUE ary)
{
    if (ARY_OWNS_HEAP_P(ary)) {
	RB_DEBUG_COUNTER_INC(obj_ary_ptr);
	ruby_sized_xfree((void *)ARY_HEAP_PTR(ary), ARY_HEAP_SIZE(ary));
    }
    else {
	RB_DEBUG_COUNTER_INC(obj_ary_embed);
    }
}

RUBY_FUNC_EXPORTED size_t
rb_ary_memsize(VALUE ary)
{
    if (ARY_OWNS_HEAP_P(ary)) {
	return ARY_CAPA(ary) * sizeof(VALUE);
    }
    else {
	return 0;
    }
}

static inline void
ary_discard(VALUE ary)
{
    rb_ary_free(ary);
    RBASIC(ary)->flags |= RARRAY_EMBED_FLAG;
    RBASIC(ary)->flags &= ~RARRAY_EMBED_LEN_MASK;
}

static VALUE
ary_make_shared(VALUE ary)
{
    assert(!ARY_EMBED_P(ary));
    if (ARY_SHARED_P(ary)) {
	return ARY_SHARED(ary);
    }
    else if (ARY_SHARED_ROOT_P(ary)) {
	return ary;
    }
    else if (OBJ_FROZEN(ary)) {
	ary_shrink_capa(ary);
	FL_SET_SHARED_ROOT(ary);
	ARY_SET_SHARED_NUM(ary, 1);
	return ary;
    }
    else {
	long capa = ARY_CAPA(ary), len = RARRAY_LEN(ary);
	NEWOBJ_OF(shared, struct RArray, 0, T_ARRAY | (RGENGC_WB_PROTECTED_ARRAY ? FL_WB_PROTECTED : 0));
        FL_UNSET_EMBED(shared);

	ARY_SET_LEN((VALUE)shared, capa);
	ARY_SET_PTR((VALUE)shared, RARRAY_CONST_PTR(ary));
	ary_mem_clear((VALUE)shared, len, capa - len);
	FL_SET_SHARED_ROOT(shared);
	ARY_SET_SHARED_NUM((VALUE)shared, 1);
	FL_SET_SHARED(ary);
	ARY_SET_SHARED(ary, (VALUE)shared);
	OBJ_FREEZE(shared);
	return (VALUE)shared;
    }
}

static VALUE
ary_make_substitution(VALUE ary)
{
    long len = RARRAY_LEN(ary);

    if (len <= RARRAY_EMBED_LEN_MAX) {
	VALUE subst = rb_ary_new2(len);
	ary_memcpy(subst, 0, len, RARRAY_CONST_PTR(ary));
        ARY_SET_EMBED_LEN(subst, len);
        return subst;
    }
    else {
        return rb_ary_increment_share(ary_make_shared(ary));
    }
}

VALUE
rb_assoc_new(VALUE car, VALUE cdr)
{
    return rb_ary_new3(2, car, cdr);
}

static VALUE
to_ary(VALUE ary)
{
    return rb_convert_type_with_id(ary, T_ARRAY, "Array", idTo_ary);
}

VALUE
rb_check_array_type(VALUE ary)
{
    return rb_check_convert_type_with_id(ary, T_ARRAY, "Array", idTo_ary);
}

/*
 *  call-seq:
 *     Array.try_convert(obj) -> array or nil
 *
 *  Tries to convert +obj+ into an array, using +to_ary+ method.  Returns the
 *  converted array or +nil+ if +obj+ cannot be converted for any reason.
 *  This method can be used to check if an argument is an array.
 *
 *     Array.try_convert([1])   #=> [1]
 *     Array.try_convert("1")   #=> nil
 *
 *     if tmp = Array.try_convert(arg)
 *       # the argument is an array
 *     elsif tmp = String.try_convert(arg)
 *       # the argument is a string
 *     end
 *
 */

static VALUE
rb_ary_s_try_convert(VALUE dummy, VALUE ary)
{
    return rb_check_array_type(ary);
}

/*
 *  call-seq:
 *     Array.new(size=0, default=nil)
 *     Array.new(array)
 *     Array.new(size) {|index| block }
 *
 *  Returns a new array.
 *
 *  In the first form, if no arguments are sent, the new array will be empty.
 *  When a +size+ and an optional +default+ are sent, an array is created with
 *  +size+ copies of +default+.  Take notice that all elements will reference the
 *  same object +default+.
 *
 *  The second form creates a copy of the array passed as a parameter (the
 *  array is generated by calling to_ary on the parameter).
 *
 *    first_array = ["Matz", "Guido"]
 *
 *    second_array = Array.new(first_array) #=> ["Matz", "Guido"]
 *
 *    first_array.equal? second_array       #=> false
 *
 *  In the last form, an array of the given size is created.  Each element in
 *  this array is created by passing the element's index to the given block
 *  and storing the return value.
 *
 *    Array.new(3){ |index| index ** 2 }
 *    # => [0, 1, 4]
 *
 *  == Common gotchas
 *
 *  When sending the second parameter, the same object will be used as the
 *  value for all the array elements:
 *
 *     a = Array.new(2, Hash.new)
 *     # => [{}, {}]
 *
 *     a[0]['cat'] = 'feline'
 *     a # => [{"cat"=>"feline"}, {"cat"=>"feline"}]
 *
 *     a[1]['cat'] = 'Felix'
 *     a # => [{"cat"=>"Felix"}, {"cat"=>"Felix"}]
 *
 *  Since all the Array elements store the same hash, changes to one of them
 *  will affect them all.
 *
 *  If multiple copies are what you want, you should use the block
 *  version which uses the result of that block each time an element
 *  of the array needs to be initialized:
 *
 *     a = Array.new(2) { Hash.new }
 *     a[0]['cat'] = 'feline'
 *     a # => [{"cat"=>"feline"}, {}]
 *
 */

static VALUE
rb_ary_initialize(int argc, VALUE *argv, VALUE ary)
{
    long len;
    VALUE size, val;

    rb_ary_modify(ary);
    if (argc == 0) {
	if (ARY_OWNS_HEAP_P(ary) && RARRAY_CONST_PTR(ary) != 0) {
	    ruby_sized_xfree((void *)RARRAY_CONST_PTR(ary), ARY_HEAP_SIZE(ary));
	}
        rb_ary_unshare_safe(ary);
        FL_SET_EMBED(ary);
	ARY_SET_EMBED_LEN(ary, 0);
	if (rb_block_given_p()) {
	    rb_warning("given block not used");
	}
	return ary;
    }
    rb_scan_args(argc, argv, "02", &size, &val);
    if (argc == 1 && !FIXNUM_P(size)) {
	val = rb_check_array_type(size);
	if (!NIL_P(val)) {
	    rb_ary_replace(ary, val);
	    return ary;
	}
    }

    len = NUM2LONG(size);
    /* NUM2LONG() may call size.to_int, ary can be frozen, modified, etc */
    if (len < 0) {
	rb_raise(rb_eArgError, "negative array size");
    }
    if (len > ARY_MAX_SIZE) {
	rb_raise(rb_eArgError, "array size too big");
    }
    /* recheck after argument conversion */
    rb_ary_modify(ary);
    ary_resize_capa(ary, len);
    if (rb_block_given_p()) {
	long i;

	if (argc == 2) {
	    rb_warn("block supersedes default value argument");
	}
	for (i=0; i [1, "a", /^A/]
 *   Array[ 1, 'a', /^A/ ]    # => [1, "a", /^A/]
 *   [ 1, 'a', /^A/ ]         # => [1, "a", /^A/]
 */

static VALUE
rb_ary_s_create(int argc, VALUE *argv, VALUE klass)
{
    VALUE ary = ary_new(klass, argc);
    if (argc > 0 && argv) {
        ary_memcpy(ary, 0, argc, argv);
        ARY_SET_LEN(ary, argc);
    }

    return ary;
}

void
rb_ary_store(VALUE ary, long idx, VALUE val)
{
    long len = RARRAY_LEN(ary);

    if (idx < 0) {
	idx += len;
	if (idx < 0) {
	    rb_raise(rb_eIndexError, "index %ld too small for array; minimum: %ld",
		     idx - len, -len);
	}
    }
    else if (idx >= ARY_MAX_SIZE) {
	rb_raise(rb_eIndexError, "index %ld too big", idx);
    }

    rb_ary_modify(ary);
    if (idx >= ARY_CAPA(ary)) {
	ary_double_capa(ary, idx);
    }
    if (idx > len) {
	ary_mem_clear(ary, len, idx - len + 1);
    }

    if (idx >= len) {
	ARY_SET_LEN(ary, idx + 1);
    }
    ARY_SET(ary, idx, val);
}

static VALUE
ary_make_partial(VALUE ary, VALUE klass, long offset, long len)
{
    assert(offset >= 0);
    assert(len >= 0);
    assert(offset+len <= RARRAY_LEN(ary));

    if (len <= RARRAY_EMBED_LEN_MAX) {
        VALUE result = ary_alloc(klass);
	ary_memcpy(result, 0, len, RARRAY_CONST_PTR(ary) + offset);
        ARY_SET_EMBED_LEN(result, len);
        return result;
    }
    else {
        VALUE shared, result = ary_alloc(klass);
        FL_UNSET_EMBED(result);

        shared = ary_make_shared(ary);
        ARY_SET_PTR(result, RARRAY_CONST_PTR(ary));
        ARY_SET_LEN(result, RARRAY_LEN(ary));
        rb_ary_set_shared(result, shared);

        ARY_INCREASE_PTR(result, offset);
        ARY_SET_LEN(result, len);
        return result;
    }
}

static VALUE
ary_make_shared_copy(VALUE ary)
{
    return ary_make_partial(ary, rb_obj_class(ary), 0, RARRAY_LEN(ary));
}

enum ary_take_pos_flags
{
    ARY_TAKE_FIRST = 0,
    ARY_TAKE_LAST = 1
};

static VALUE
ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos_flags last)
{
    VALUE nv;
    long n;
    long len;
    long offset = 0;

    rb_scan_args(argc, argv, "1", &nv);
    n = NUM2LONG(nv);
    len = RARRAY_LEN(ary);
    if (n > len) {
	n = len;
    }
    else if (n < 0) {
	rb_raise(rb_eArgError, "negative array size");
    }
    if (last) {
	offset = len - n;
    }
    return ary_make_partial(ary, rb_cArray, offset, n);
}

/*
 *  call-seq:
 *     ary << obj            -> ary
 *
 *  Append---Pushes the given object on to the end of this array. This
 *  expression returns the array itself, so several appends
 *  may be chained together.
 *
 *     a = [ 1, 2 ]
 *     a << "c" << "d" << [ 3, 4 ]
 *             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
 *     a
 *             #=>  [ 1, 2, "c", "d", [ 3, 4 ] ]
 *
 */

VALUE
rb_ary_push(VALUE ary, VALUE item)
{
    long idx = RARRAY_LEN(ary);
    VALUE target_ary = ary_ensure_room_for_push(ary, 1);
    RARRAY_PTR_USE(ary, ptr, {
	RB_OBJ_WRITE(target_ary, &ptr[idx], item);
    });
    ARY_SET_LEN(ary, idx + 1);
    return ary;
}

VALUE
rb_ary_cat(VALUE ary, const VALUE *argv, long len)
{
    long oldlen = RARRAY_LEN(ary);
    VALUE target_ary = ary_ensure_room_for_push(ary, len);
    ary_memcpy0(ary, oldlen, len, argv, target_ary);
    ARY_SET_LEN(ary, oldlen + len);
    return ary;
}

/*
 *  call-seq:
 *     ary.push(obj, ... )   -> ary
 *
 *  Append --- Pushes the given object(s) on to the end of this array. This
 *  expression returns the array itself, so several appends
 *  may be chained together. See also Array#pop for the opposite
 *  effect.
 *
 *     a = [ "a", "b", "c" ]
 *     a.push("d", "e", "f")
 *             #=> ["a", "b", "c", "d", "e", "f"]
 *     [1, 2, 3].push(4).push(5)
 *             #=> [1, 2, 3, 4, 5]
 */

static VALUE
rb_ary_push_m(int argc, VALUE *argv, VALUE ary)
{
    return rb_ary_cat(ary, argv, argc);
}

VALUE
rb_ary_pop(VALUE ary)
{
    long n;
    rb_ary_modify_check(ary);
    n = RARRAY_LEN(ary);
    if (n == 0) return Qnil;
    if (ARY_OWNS_HEAP_P(ary) &&
	n * 3 < ARY_CAPA(ary) &&
	ARY_CAPA(ary) > ARY_DEFAULT_SIZE)
    {
	ary_resize_capa(ary, n * 2);
    }
    --n;
    ARY_SET_LEN(ary, n);
    return RARRAY_AREF(ary, n);
}

/*
 *  call-seq:
 *     ary.pop    -> obj or nil
 *     ary.pop(n) -> new_ary
 *
 *  Removes the last element from +self+ and returns it, or
 *  +nil+ if the array is empty.
 *
 *  If a number +n+ is given, returns an array of the last +n+ elements
 *  (or less) just like array.slice!(-n, n) does. See also
 *  Array#push for the opposite effect.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.pop     #=> "d"
 *     a.pop(2)  #=> ["b", "c"]
 *     a         #=> ["a"]
 */

static VALUE
rb_ary_pop_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE result;

    if (argc == 0) {
	return rb_ary_pop(ary);
    }

    rb_ary_modify_check(ary);
    result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
    ARY_INCREASE_LEN(ary, -RARRAY_LEN(result));
    return result;
}

VALUE
rb_ary_shift(VALUE ary)
{
    VALUE top;
    long len = RARRAY_LEN(ary);

    rb_ary_modify_check(ary);
    if (len == 0) return Qnil;
    top = RARRAY_AREF(ary, 0);
    if (!ARY_SHARED_P(ary)) {
	if (len < ARY_DEFAULT_SIZE) {
	    RARRAY_PTR_USE(ary, ptr, {
		MEMMOVE(ptr, ptr+1, VALUE, len-1);
	    }); /* WB: no new reference */
            ARY_INCREASE_LEN(ary, -1);
	    return top;
	}
        assert(!ARY_EMBED_P(ary)); /* ARY_EMBED_LEN_MAX < ARY_DEFAULT_SIZE */

	ARY_SET(ary, 0, Qnil);
	ary_make_shared(ary);
    }
    else if (ARY_SHARED_OCCUPIED(ARY_SHARED(ary))) {
	RARRAY_PTR_USE(ary, ptr, ptr[0] = Qnil);
    }
    ARY_INCREASE_PTR(ary, 1);		/* shift ptr */
    ARY_INCREASE_LEN(ary, -1);

    return top;
}

/*
 *  call-seq:
 *     ary.shift    -> obj or nil
 *     ary.shift(n) -> new_ary
 *
 *  Removes the first element of +self+ and returns it (shifting all
 *  other elements down by one). Returns +nil+ if the array
 *  is empty.
 *
 *  If a number +n+ is given, returns an array of the first +n+ elements
 *  (or less) just like array.slice!(0, n) does. With +ary+
 *  containing only the remainder elements, not including what was shifted to
 *  +new_ary+. See also Array#unshift for the opposite effect.
 *
 *     args = [ "-m", "-q", "filename" ]
 *     args.shift     #=> "-m"
 *     args           #=> ["-q", "filename"]
 *
 *     args = [ "-m", "-q", "filename" ]
 *     args.shift(2)  #=> ["-m", "-q"]
 *     args           #=> ["filename"]
 */

static VALUE
rb_ary_shift_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE result;
    long n;

    if (argc == 0) {
	return rb_ary_shift(ary);
    }

    rb_ary_modify_check(ary);
    result = ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
    n = RARRAY_LEN(result);
    if (ARY_SHARED_P(ary)) {
	if (ARY_SHARED_OCCUPIED(ARY_SHARED(ary))) {
	  setup_occupied_shared:
	    ary_mem_clear(ary, 0, n);
	}
        ARY_INCREASE_PTR(ary, n);
    }
    else {
	if (RARRAY_LEN(ary) < ARY_DEFAULT_SIZE) {
	    RARRAY_PTR_USE(ary, ptr, {
		MEMMOVE(ptr, ptr+n, VALUE, RARRAY_LEN(ary)-n);
	    }); /* WB: no new reference */
	}
	else {
	    ary_make_shared(ary);
	    goto setup_occupied_shared;
	}
    }
    ARY_INCREASE_LEN(ary, -n);

    return result;
}

static VALUE
ary_ensure_room_for_unshift(VALUE ary, int argc)
{
    long len = RARRAY_LEN(ary);
    long new_len = len + argc;
    long capa;
    const VALUE *head, *sharedp;

    if (len > ARY_MAX_SIZE - argc) {
	rb_raise(rb_eIndexError, "index %ld too big", new_len);
    }

    if (ARY_SHARED_P(ary)) {
	VALUE shared = ARY_SHARED(ary);
	capa = RARRAY_LEN(shared);
	if (ARY_SHARED_OCCUPIED(shared) && capa > new_len) {
	    head = RARRAY_CONST_PTR(ary);
	    sharedp = RARRAY_CONST_PTR(shared);
	    goto makeroom_if_need;
	}
    }

    rb_ary_modify(ary);
    capa = ARY_CAPA(ary);
    if (capa - (capa >> 6) <= new_len) {
	ary_double_capa(ary, new_len);
    }

    /* use shared array for big "queues" */
    if (new_len > ARY_DEFAULT_SIZE * 4) {
	/* make a room for unshifted items */
	capa = ARY_CAPA(ary);
	ary_make_shared(ary);

	head = sharedp = RARRAY_CONST_PTR(ary);
	goto makeroom;
      makeroom_if_need:
	if (head - sharedp < argc) {
	    long room;
	  makeroom:
	    room = capa - new_len;
	    room -= room >> 4;
	    MEMMOVE((VALUE *)sharedp + argc + room, head, VALUE, len);
	    head = sharedp + argc + room;
	}
	ARY_SET_PTR(ary, head - argc);
	assert(ARY_SHARED_OCCUPIED(ARY_SHARED(ary)));
	return ARY_SHARED(ary);
    }
    else {
	/* sliding items */
	RARRAY_PTR_USE(ary, ptr, {
	    MEMMOVE(ptr + argc, ptr, VALUE, len);
	});

	return ary;
    }
}

/*
 *  call-seq:
 *     ary.unshift(obj, ...)  -> ary
 *
 *  Prepends objects to the front of +self+, moving other elements upwards.
 *  See also Array#shift for the opposite effect.
 *
 *     a = [ "b", "c", "d" ]
 *     a.unshift("a")   #=> ["a", "b", "c", "d"]
 *     a.unshift(1, 2)  #=> [ 1, 2, "a", "b", "c", "d"]
 */

static VALUE
rb_ary_unshift_m(int argc, VALUE *argv, VALUE ary)
{
    long len = RARRAY_LEN(ary);
    VALUE target_ary;

    if (argc == 0) {
	rb_ary_modify_check(ary);
	return ary;
    }

    target_ary = ary_ensure_room_for_unshift(ary, argc);
    ary_memcpy0(ary, 0, argc, argv, target_ary);
    ARY_SET_LEN(ary, len + argc);
    return ary;
}

VALUE
rb_ary_unshift(VALUE ary, VALUE item)
{
    return rb_ary_unshift_m(1,&item,ary);
}

/* faster version - use this if you don't need to treat negative offset */
static inline VALUE
rb_ary_elt(VALUE ary, long offset)
{
    long len = RARRAY_LEN(ary);
    if (len == 0) return Qnil;
    if (offset < 0 || len <= offset) {
	return Qnil;
    }
    return RARRAY_AREF(ary, offset);
}

VALUE
rb_ary_entry(VALUE ary, long offset)
{
    long len = RARRAY_LEN(ary);
    const VALUE *ptr = RARRAY_CONST_PTR(ary);
    if (len == 0) return Qnil;
    if (offset < 0) {
        offset += len;
        if (offset < 0) return Qnil;
    }
    else if (len <= offset) {
        return Qnil;
    }
    return ptr[offset];
}

VALUE
rb_ary_subseq(VALUE ary, long beg, long len)
{
    VALUE klass;
    long alen = RARRAY_LEN(ary);

    if (beg > alen) return Qnil;
    if (beg < 0 || len < 0) return Qnil;

    if (alen < len || alen < beg + len) {
	len = alen - beg;
    }
    klass = rb_obj_class(ary);
    if (len == 0) return ary_new(klass, 0);

    return ary_make_partial(ary, klass, beg, len);
}

/*
 *  call-seq:
 *     ary[index]                -> obj     or nil
 *     ary[start, length]        -> new_ary or nil
 *     ary[range]                -> new_ary or nil
 *     ary.slice(index)          -> obj     or nil
 *     ary.slice(start, length)  -> new_ary or nil
 *     ary.slice(range)          -> new_ary or nil
 *
 *  Element Reference --- Returns the element at +index+, or returns a
 *  subarray starting at the +start+ index and continuing for +length+
 *  elements, or returns a subarray specified by +range+ of indices.
 *
 *  Negative indices count backward from the end of the array (-1 is the last
 *  element).  For +start+ and +range+ cases the starting index is just before
 *  an element.  Additionally, an empty array is returned when the starting
 *  index for an element range is at the end of the array.
 *
 *  Returns +nil+ if the index (or starting index) are out of range.
 *
 *     a = [ "a", "b", "c", "d", "e" ]
 *     a[2] +  a[0] + a[1]    #=> "cab"
 *     a[6]                   #=> nil
 *     a[1, 2]                #=> [ "b", "c" ]
 *     a[1..3]                #=> [ "b", "c", "d" ]
 *     a[4..7]                #=> [ "e" ]
 *     a[6..10]               #=> nil
 *     a[-3, 3]               #=> [ "c", "d", "e" ]
 *     # special cases
 *     a[5]                   #=> nil
 *     a[6, 1]                #=> nil
 *     a[5, 1]                #=> []
 *     a[5..10]               #=> []
 *
 */

VALUE
rb_ary_aref(int argc, const VALUE *argv, VALUE ary)
{
    VALUE arg;
    long beg, len;

    if (argc == 2) {
	beg = NUM2LONG(argv[0]);
	len = NUM2LONG(argv[1]);
	if (beg < 0) {
	    beg += RARRAY_LEN(ary);
	}
	return rb_ary_subseq(ary, beg, len);
    }
    if (argc != 1) {
	rb_scan_args(argc, argv, "11", NULL, NULL);
    }
    arg = argv[0];
    /* special case - speeding up */
    if (FIXNUM_P(arg)) {
	return rb_ary_entry(ary, FIX2LONG(arg));
    }
    /* check if idx is Range */
    switch (rb_range_beg_len(arg, &beg, &len, RARRAY_LEN(ary), 0)) {
      case Qfalse:
	break;
      case Qnil:
	return Qnil;
      default:
	return rb_ary_subseq(ary, beg, len);
    }
    return rb_ary_entry(ary, NUM2LONG(arg));
}

/*
 *  call-seq:
 *     ary.at(index)   ->   obj  or nil
 *
 *  Returns the element at +index+. A negative index counts from the end of
 *  +self+. Returns +nil+ if the index is out of range. See also
 *  Array#[].
 *
 *     a = [ "a", "b", "c", "d", "e" ]
 *     a.at(0)     #=> "a"
 *     a.at(-1)    #=> "e"
 */

VALUE
rb_ary_at(VALUE ary, VALUE pos)
{
    return rb_ary_entry(ary, NUM2LONG(pos));
}

/*
 *  call-seq:
 *     ary.first     ->   obj or nil
 *     ary.first(n)  ->   new_ary
 *
 *  Returns the first element, or the first +n+ elements, of the array.
 *  If the array is empty, the first form returns +nil+, and the
 *  second form returns an empty array. See also Array#last for
 *  the opposite effect.
 *
 *     a = [ "q", "r", "s", "t" ]
 *     a.first     #=> "q"
 *     a.first(2)  #=> ["q", "r"]
 */

static VALUE
rb_ary_first(int argc, VALUE *argv, VALUE ary)
{
    if (argc == 0) {
	if (RARRAY_LEN(ary) == 0) return Qnil;
	return RARRAY_AREF(ary, 0);
    }
    else {
	return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_FIRST);
    }
}

/*
 *  call-seq:
 *     ary.last     ->  obj or nil
 *     ary.last(n)  ->  new_ary
 *
 *  Returns the last element(s) of +self+. If the array is empty,
 *  the first form returns +nil+.
 *
 *  See also Array#first for the opposite effect.
 *
 *     a = [ "w", "x", "y", "z" ]
 *     a.last     #=> "z"
 *     a.last(2)  #=> ["y", "z"]
 */

VALUE
rb_ary_last(int argc, const VALUE *argv, VALUE ary)
{
    if (argc == 0) {
	long len = RARRAY_LEN(ary);
	if (len == 0) return Qnil;
	return RARRAY_AREF(ary, len-1);
    }
    else {
	return ary_take_first_or_last(argc, argv, ary, ARY_TAKE_LAST);
    }
}

/*
 *  call-seq:
 *     ary.fetch(index)                    -> obj
 *     ary.fetch(index, default)           -> obj
 *     ary.fetch(index) { |index| block }  -> obj
 *
 *  Tries to return the element at position +index+, but throws an IndexError
 *  exception if the referenced +index+ lies outside of the array bounds.  This
 *  error can be prevented by supplying a second argument, which will act as a
 *  +default+ value.
 *
 *  Alternatively, if a block is given it will only be executed when an
 *  invalid +index+ is referenced.
 *
 *  Negative values of +index+ count from the end of the array.
 *
 *     a = [ 11, 22, 33, 44 ]
 *     a.fetch(1)               #=> 22
 *     a.fetch(-1)              #=> 44
 *     a.fetch(4, 'cat')        #=> "cat"
 *     a.fetch(100) { |i| puts "#{i} is out of bounds" }
 *                              #=> "100 is out of bounds"
 */

static VALUE
rb_ary_fetch(int argc, VALUE *argv, VALUE ary)
{
    VALUE pos, ifnone;
    long block_given;
    long idx;

    rb_scan_args(argc, argv, "11", &pos, &ifnone);
    block_given = rb_block_given_p();
    if (block_given && argc == 2) {
	rb_warn("block supersedes default value argument");
    }
    idx = NUM2LONG(pos);

    if (idx < 0) {
	idx +=  RARRAY_LEN(ary);
    }
    if (idx < 0 || RARRAY_LEN(ary) <= idx) {
	if (block_given) return rb_yield(pos);
	if (argc == 1) {
	    rb_raise(rb_eIndexError, "index %ld outside of array bounds: %ld...%ld",
			idx - (idx < 0 ? RARRAY_LEN(ary) : 0), -RARRAY_LEN(ary), RARRAY_LEN(ary));
	}
	return ifnone;
    }
    return RARRAY_AREF(ary, idx);
}

/*
 *  call-seq:
 *     ary.find_index(obj)             ->  int or nil
 *     ary.find_index { |item| block } ->  int or nil
 *     ary.find_index                  ->  Enumerator
 *     ary.index(obj)             ->  int or nil
 *     ary.index { |item| block } ->  int or nil
 *     ary.index                  ->  Enumerator
 *
 *  Returns the _index_ of the first object in +ary+ such that the object is
 *  == to +obj+.
 *
 *  If a block is given instead of an argument, returns the _index_ of the
 *  first object for which the block returns +true+.  Returns +nil+ if no
 *  match is found.
 *
 *  See also Array#rindex.
 *
 *  An Enumerator is returned if neither a block nor argument is given.
 *
 *     a = [ "a", "b", "c" ]
 *     a.index("b")              #=> 1
 *     a.index("z")              #=> nil
 *     a.index { |x| x == "b" }  #=> 1
 */

static VALUE
rb_ary_index(int argc, VALUE *argv, VALUE ary)
{
    VALUE val;
    long i;

    if (argc == 0) {
	RETURN_ENUMERATOR(ary, 0, 0);
	for (i=0; i  int or nil
 *     ary.rindex { |item| block } ->  int or nil
 *     ary.rindex                  ->  Enumerator
 *
 *  Returns the _index_ of the last object in +self+ == to +obj+.
 *
 *  If a block is given instead of an argument, returns the _index_ of the
 *  first object for which the block returns +true+, starting from the last
 *  object.
 *
 *  Returns +nil+ if no match is found.
 *
 *  See also Array#index.
 *
 *  If neither block nor argument is given, an Enumerator is returned instead.
 *
 *     a = [ "a", "b", "b", "b", "c" ]
 *     a.rindex("b")             #=> 3
 *     a.rindex("z")             #=> nil
 *     a.rindex { |x| x == "b" } #=> 3
 */

static VALUE
rb_ary_rindex(int argc, VALUE *argv, VALUE ary)
{
    VALUE val;
    long i = RARRAY_LEN(ary), len;

    if (argc == 0) {
	RETURN_ENUMERATOR(ary, 0, 0);
	while (i--) {
	    if (RTEST(rb_yield(RARRAY_AREF(ary, i))))
		return LONG2NUM(i);
	    if (i > (len = RARRAY_LEN(ary))) {
		i = len;
	    }
	}
	return Qnil;
    }
    rb_check_arity(argc, 0, 1);
    val = argv[0];
    if (rb_block_given_p())
	rb_warn("given block not used");
    while (i--) {
	VALUE e = RARRAY_AREF(ary, i);
	if (rb_equal(e, val)) {
	    return LONG2NUM(i);
	}
    }
    return Qnil;
}

VALUE
rb_ary_to_ary(VALUE obj)
{
    VALUE tmp = rb_check_array_type(obj);

    if (!NIL_P(tmp)) return tmp;
    return rb_ary_new3(1, obj);
}

static void
rb_ary_splice(VALUE ary, long beg, long len, const VALUE *rptr, long rlen)
{
    long olen;
    long rofs;

    if (len < 0) rb_raise(rb_eIndexError, "negative length (%ld)", len);
    olen = RARRAY_LEN(ary);
    if (beg < 0) {
	beg += olen;
	if (beg < 0) {
	    rb_raise(rb_eIndexError, "index %ld too small for array; minimum: %ld",
		     beg - olen, -olen);
	}
    }
    if (olen < len || olen < beg + len) {
	len = olen - beg;
    }

    {
	const VALUE *optr = RARRAY_CONST_PTR(ary);
	rofs = (rptr >= optr && rptr < optr + olen) ? rptr - optr : -1;
    }

    if (beg >= olen) {
	VALUE target_ary;
	if (beg > ARY_MAX_SIZE - rlen) {
	    rb_raise(rb_eIndexError, "index %ld too big", beg);
	}
	target_ary = ary_ensure_room_for_push(ary, rlen-len); /* len is 0 or negative */
	len = beg + rlen;
	ary_mem_clear(ary, olen, beg - olen);
	if (rlen > 0) {
	    if (rofs != -1) rptr = RARRAY_CONST_PTR(ary) + rofs;
	    ary_memcpy0(ary, beg, rlen, rptr, target_ary);
	}
	ARY_SET_LEN(ary, len);
    }
    else {
	long alen;

	if (olen - len > ARY_MAX_SIZE - rlen) {
	    rb_raise(rb_eIndexError, "index %ld too big", olen + rlen - len);
	}
	rb_ary_modify(ary);
	alen = olen + rlen - len;
	if (alen >= ARY_CAPA(ary)) {
	    ary_double_capa(ary, alen);
	}

	if (len != rlen) {
	    RARRAY_PTR_USE(ary, ptr,
			   MEMMOVE(ptr + beg + rlen, ptr + beg + len,
				   VALUE, olen - (beg + len)));
	    ARY_SET_LEN(ary, alen);
	}
	if (rlen > 0) {
	    if (rofs != -1) rptr = RARRAY_CONST_PTR(ary) + rofs;
	    MEMMOVE(RARRAY_PTR(ary) + beg, rptr, VALUE, rlen);
	}
    }
}

void
rb_ary_set_len(VALUE ary, long len)
{
    long capa;

    rb_ary_modify_check(ary);
    if (ARY_SHARED_P(ary)) {
	rb_raise(rb_eRuntimeError, "can't set length of shared ");
    }
    if (len > (capa = (long)ARY_CAPA(ary))) {
	rb_bug("probable buffer overflow: %ld for %ld", len, capa);
    }
    ARY_SET_LEN(ary, len);
}

/*!
 * expands or shrinks \a ary to \a len elements.
 * expanded region will be filled with Qnil.
 * \param ary  an array
 * \param len  new size
 * \return     \a ary
 * \post       the size of \a ary is \a len.
 */
VALUE
rb_ary_resize(VALUE ary, long len)
{
    long olen;

    rb_ary_modify(ary);
    olen = RARRAY_LEN(ary);
    if (len == olen) return ary;
    if (len > ARY_MAX_SIZE) {
	rb_raise(rb_eIndexError, "index %ld too big", len);
    }
    if (len > olen) {
	if (len >= ARY_CAPA(ary)) {
	    ary_double_capa(ary, len);
	}
	ary_mem_clear(ary, olen, len - olen);
	ARY_SET_LEN(ary, len);
    }
    else if (ARY_EMBED_P(ary)) {
        ARY_SET_EMBED_LEN(ary, len);
    }
    else if (len <= RARRAY_EMBED_LEN_MAX) {
	VALUE tmp[RARRAY_EMBED_LEN_MAX];
	MEMCPY(tmp, ARY_HEAP_PTR(ary), VALUE, len);
	ary_discard(ary);
	MEMCPY((VALUE *)ARY_EMBED_PTR(ary), tmp, VALUE, len); /* WB: no new reference */
        ARY_SET_EMBED_LEN(ary, len);
    }
    else {
	if (olen > len + ARY_DEFAULT_SIZE) {
	    SIZED_REALLOC_N(RARRAY(ary)->as.heap.ptr, VALUE, len, RARRAY(ary)->as.heap.aux.capa);
	    ARY_SET_CAPA(ary, len);
	}
	ARY_SET_HEAP_LEN(ary, len);
    }
    return ary;
}

/*
 *  call-seq:
 *     ary[index]         = obj                      ->  obj
 *     ary[start, length] = obj or other_ary or nil  ->  obj or other_ary or nil
 *     ary[range]         = obj or other_ary or nil  ->  obj or other_ary or nil
 *
 *  Element Assignment --- Sets the element at +index+, or replaces a subarray
 *  from the +start+ index for +length+ elements, or replaces a subarray
 *  specified by the +range+ of indices.
 *
 *  If indices are greater than the current capacity of the array, the array
 *  grows automatically.  Elements are inserted into the array at +start+ if
 *  +length+ is zero.
 *
 *  Negative indices will count backward from the end of the array.  For
 *  +start+ and +range+ cases the starting index is just before an element.
 *
 *  An IndexError is raised if a negative index points past the beginning of
 *  the array.
 *
 *  See also Array#push, and Array#unshift.
 *
 *     a = Array.new
 *     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
 *     a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
 *     a[1..2] = [ 1, 2 ]          #=> ["a", 1, 2, nil, "4"]
 *     a[0, 2] = "?"               #=> ["?", 2, nil, "4"]
 *     a[0..2] = "A"               #=> ["A", "4"]
 *     a[-1]   = "Z"               #=> ["A", "Z"]
 *     a[1..-1] = nil              #=> ["A", nil]
 *     a[1..-1] = []               #=> ["A"]
 *     a[0, 0] = [ 1, 2 ]          #=> [1, 2, "A"]
 *     a[3, 0] = "B"               #=> [1, 2, "A", "B"]
 */

static VALUE
rb_ary_aset(int argc, VALUE *argv, VALUE ary)
{
    long offset, beg, len;
    VALUE rpl;

    if (argc == 3) {
	rb_ary_modify_check(ary);
	beg = NUM2LONG(argv[0]);
	len = NUM2LONG(argv[1]);
	goto range;
    }
    rb_check_arity(argc, 2, 2);
    rb_ary_modify_check(ary);
    if (FIXNUM_P(argv[0])) {
	offset = FIX2LONG(argv[0]);
	goto fixnum;
    }
    if (rb_range_beg_len(argv[0], &beg, &len, RARRAY_LEN(ary), 1)) {
	/* check if idx is Range */
      range:
	rpl = rb_ary_to_ary(argv[argc-1]);
	rb_ary_splice(ary, beg, len, RARRAY_CONST_PTR(rpl), RARRAY_LEN(rpl));
	RB_GC_GUARD(rpl);
	return argv[argc-1];
    }

    offset = NUM2LONG(argv[0]);
fixnum:
    rb_ary_store(ary, offset, argv[1]);
    return argv[1];
}

/*
 *  call-seq:
 *     ary.insert(index, obj...)  -> ary
 *
 *  Inserts the given values before the element with the given +index+.
 *
 *  Negative indices count backwards from the end of the array, where +-1+ is
 *  the last element. If a negative index is used, the given values will be
 *  inserted after that element, so using an index of +-1+ will insert the
 *  values at the end of the array.
 *
 *     a = %w{ a b c d }
 *     a.insert(2, 99)         #=> ["a", "b", 99, "c", "d"]
 *     a.insert(-2, 1, 2, 3)   #=> ["a", "b", 99, "c", 1, 2, 3, "d"]
 */

static VALUE
rb_ary_insert(int argc, VALUE *argv, VALUE ary)
{
    long pos;

    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    rb_ary_modify_check(ary);
    pos = NUM2LONG(argv[0]);
    if (argc == 1) return ary;
    if (pos == -1) {
	pos = RARRAY_LEN(ary);
    }
    else if (pos < 0) {
	long minpos = -RARRAY_LEN(ary) - 1;
	if (pos < minpos) {
	    rb_raise(rb_eIndexError, "index %ld too small for array; minimum: %ld",
		     pos, minpos);
	}
	pos++;
    }
    rb_ary_splice(ary, pos, 0, argv + 1, argc - 1);
    return ary;
}

static VALUE
rb_ary_length(VALUE ary);

static VALUE
ary_enum_length(VALUE ary, VALUE args, VALUE eobj)
{
    return rb_ary_length(ary);
}

/*
 *  call-seq:
 *     ary.each { |item| block }  -> ary
 *     ary.each                   -> Enumerator
 *
 *  Calls the given block once for each element in +self+, passing that element
 *  as a parameter.  Returns the array itself.
 *
 *  If no block is given, an Enumerator is returned.
 *
 *     a = [ "a", "b", "c" ]
 *     a.each {|x| print x, " -- " }
 *
 *  produces:
 *
 *     a -- b -- c --
 */

VALUE
rb_ary_each(VALUE ary)
{
    long i;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    for (i=0; i ary
 *     ary.each_index                    -> Enumerator
 *
 *  Same as Array#each, but passes the +index+ of the element instead of the
 *  element itself.
 *
 *  An Enumerator is returned if no block is given.
 *
 *     a = [ "a", "b", "c" ]
 *     a.each_index {|x| print x, " -- " }
 *
 *  produces:
 *
 *     0 -- 1 -- 2 --
 */

static VALUE
rb_ary_each_index(VALUE ary)
{
    long i;
    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);

    for (i=0; i ary
 *     ary.reverse_each                   -> Enumerator
 *
 *  Same as Array#each, but traverses +self+ in reverse order.
 *
 *     a = [ "a", "b", "c" ]
 *     a.reverse_each {|x| print x, " " }
 *
 *  produces:
 *
 *     c b a
 */

static VALUE
rb_ary_reverse_each(VALUE ary)
{
    long len;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    len = RARRAY_LEN(ary);
    while (len--) {
	long nlen;
	rb_yield(RARRAY_AREF(ary, len));
	nlen = RARRAY_LEN(ary);
	if (nlen < len) {
	    len = nlen;
	}
    }
    return ary;
}

/*
 *  call-seq:
 *     ary.length -> int
 *
 *  Returns the number of elements in +self+. May be zero.
 *
 *     [ 1, 2, 3, 4, 5 ].length   #=> 5
 *     [].length                  #=> 0
 */

static VALUE
rb_ary_length(VALUE ary)
{
    long len = RARRAY_LEN(ary);
    return LONG2NUM(len);
}

/*
 *  call-seq:
 *     ary.empty?   -> true or false
 *
 *  Returns +true+ if +self+ contains no elements.
 *
 *     [].empty?   #=> true
 */

static VALUE
rb_ary_empty_p(VALUE ary)
{
    if (RARRAY_LEN(ary) == 0)
	return Qtrue;
    return Qfalse;
}

VALUE
rb_ary_dup(VALUE ary)
{
    long len = RARRAY_LEN(ary);
    VALUE dup = rb_ary_new2(len);
    ary_memcpy(dup, 0, len, RARRAY_CONST_PTR(ary));
    ARY_SET_LEN(dup, len);
    return dup;
}

VALUE
rb_ary_resurrect(VALUE ary)
{
    return rb_ary_new4(RARRAY_LEN(ary), RARRAY_CONST_PTR(ary));
}

extern VALUE rb_output_fs;

static void ary_join_1(VALUE obj, VALUE ary, VALUE sep, long i, VALUE result, int *first);

static VALUE
recursive_join(VALUE obj, VALUE argp, int recur)
{
    VALUE *arg = (VALUE *)argp;
    VALUE ary = arg[0];
    VALUE sep = arg[1];
    VALUE result = arg[2];
    int *first = (int *)arg[3];

    if (recur) {
	rb_raise(rb_eArgError, "recursive array join");
    }
    else {
	ary_join_1(obj, ary, sep, 0, result, first);
    }
    return Qnil;
}

static void
ary_join_0(VALUE ary, VALUE sep, long max, VALUE result)
{
    long i;
    VALUE val;

    if (max > 0) rb_enc_copy(result, RARRAY_AREF(ary, 0));
    for (i=0; i 0 && !NIL_P(sep))
	    rb_str_buf_append(result, sep);
	rb_str_buf_append(result, val);
	if (OBJ_TAINTED(val)) OBJ_TAINT(result);
    }
}

static void
ary_join_1(VALUE obj, VALUE ary, VALUE sep, long i, VALUE result, int *first)
{
    VALUE val, tmp;

    for (; i 0 && !NIL_P(sep))
	    rb_str_buf_append(result, sep);

	val = RARRAY_AREF(ary, i);
	if (RB_TYPE_P(val, T_STRING)) {
	  str_join:
	    rb_str_buf_append(result, val);
	    *first = FALSE;
	}
	else if (RB_TYPE_P(val, T_ARRAY)) {
	    obj = val;
	  ary_join:
	    if (val == ary) {
		rb_raise(rb_eArgError, "recursive array join");
	    }
	    else {
		VALUE args[4];

		args[0] = val;
		args[1] = sep;
		args[2] = result;
		args[3] = (VALUE)first;
		rb_exec_recursive(recursive_join, obj, (VALUE)args);
	    }
	}
	else {
	    tmp = rb_check_string_type(val);
	    if (!NIL_P(tmp)) {
		val = tmp;
		goto str_join;
	    }
	    tmp = rb_check_convert_type_with_id(val, T_ARRAY, "Array", idTo_ary);
	    if (!NIL_P(tmp)) {
		obj = val;
		val = tmp;
		goto ary_join;
	    }
	    val = rb_obj_as_string(val);
	    if (*first) {
		rb_enc_copy(result, val);
		*first = FALSE;
	    }
	    goto str_join;
	}
    }
}

VALUE
rb_ary_join(VALUE ary, VALUE sep)
{
    long len = 1, i;
    int taint = FALSE;
    VALUE val, tmp, result;

    if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new(0, 0);
    if (OBJ_TAINTED(ary)) taint = TRUE;

    if (!NIL_P(sep)) {
	StringValue(sep);
	len += RSTRING_LEN(sep) * (RARRAY_LEN(ary) - 1);
    }
    for (i=0; i str
 *
 *  Returns a string created by converting each element of the array to
 *  a string, separated by the given +separator+.
 *  If the +separator+ is +nil+, it uses current $,.
 *  If both the +separator+ and $, are +nil+,
 *  it uses an empty string.
 *
 *     [ "a", "b", "c" ].join        #=> "abc"
 *     [ "a", "b", "c" ].join("-")   #=> "a-b-c"
 *
 *  For nested arrays, join is applied recursively:
 *
 *     [ "a", [1, 2, [:x, :y]], "b" ].join("-")   #=> "a-1-2-x-y-b"
 */

static VALUE
rb_ary_join_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE sep;

    rb_scan_args(argc, argv, "01", &sep);
    if (NIL_P(sep)) sep = rb_output_fs;

    return rb_ary_join(ary, sep);
}

static VALUE
inspect_ary(VALUE ary, VALUE dummy, int recur)
{
    int tainted = OBJ_TAINTED(ary);
    long i;
    VALUE s, str;

    if (recur) return rb_usascii_str_new_cstr("[...]");
    str = rb_str_buf_new2("[");
    for (i=0; i 0) rb_str_buf_cat2(str, ", ");
	else rb_enc_copy(str, s);
	rb_str_buf_append(str, s);
    }
    rb_str_buf_cat2(str, "]");
    if (tainted) OBJ_TAINT(str);
    return str;
}

/*
 *  call-seq:
 *     ary.inspect  -> string
 *     ary.to_s     -> string
 *
 *  Creates a string representation of +self+.
 *
 *     [ "a", "b", "c" ].to_s     #=> "[\"a\", \"b\", \"c\"]"
 */

static VALUE
rb_ary_inspect(VALUE ary)
{
    if (RARRAY_LEN(ary) == 0) return rb_usascii_str_new2("[]");
    return rb_exec_recursive(inspect_ary, ary, 0);
}

VALUE
rb_ary_to_s(VALUE ary)
{
    return rb_ary_inspect(ary);
}

/*
 *  call-seq:
 *     ary.to_a     -> ary
 *
 *  Returns +self+.
 *
 *  If called on a subclass of Array, converts the receiver to an Array object.
 */

static VALUE
rb_ary_to_a(VALUE ary)
{
    if (rb_obj_class(ary) != rb_cArray) {
	VALUE dup = rb_ary_new2(RARRAY_LEN(ary));
	rb_ary_replace(dup, ary);
	return dup;
    }
    return ary;
}

/*
 *  call-seq:
 *     ary.to_h     -> hash
 *
 *  Returns the result of interpreting ary as an array of
 *  [key, value] pairs.
 *
 *     [[:foo, :bar], [1, 2]].to_h
 *       # => {:foo => :bar, 1 => 2}
 */

static VALUE
rb_ary_to_h(VALUE ary)
{
    long i;
    VALUE hash = rb_hash_new();
    for (i=0; i ary
 *
 *  Returns +self+.
 */

static VALUE
rb_ary_to_ary_m(VALUE ary)
{
    return ary;
}

static void
ary_reverse(VALUE *p1, VALUE *p2)
{
    while (p1 < p2) {
	VALUE tmp = *p1;
	*p1++ = *p2;
	*p2-- = tmp;
    }
}

VALUE
rb_ary_reverse(VALUE ary)
{
    VALUE *p2;
    long len = RARRAY_LEN(ary);

    rb_ary_modify(ary);
    if (len > 1) {
	RARRAY_PTR_USE(ary, p1, {
	    p2 = p1 + len - 1;	/* points last item */
	    ary_reverse(p1, p2);
	}); /* WB: no new reference */
    }
    return ary;
}

/*
 *  call-seq:
 *     ary.reverse!   -> ary
 *
 *  Reverses +self+ in place.
 *
 *     a = [ "a", "b", "c" ]
 *     a.reverse!       #=> ["c", "b", "a"]
 *     a                #=> ["c", "b", "a"]
 */

static VALUE
rb_ary_reverse_bang(VALUE ary)
{
    return rb_ary_reverse(ary);
}

/*
 *  call-seq:
 *     ary.reverse    -> new_ary
 *
 *  Returns a new array containing +self+'s elements in reverse order.
 *
 *     [ "a", "b", "c" ].reverse   #=> ["c", "b", "a"]
 *     [ 1 ].reverse               #=> [1]
 */

static VALUE
rb_ary_reverse_m(VALUE ary)
{
    long len = RARRAY_LEN(ary);
    VALUE dup = rb_ary_new2(len);

    if (len > 0) {
	const VALUE *p1 = RARRAY_CONST_PTR(ary);
	VALUE *p2 = (VALUE *)RARRAY_CONST_PTR(dup) + len - 1;
	do *p2-- = *p1++; while (--len > 0);
    }
    ARY_SET_LEN(dup, RARRAY_LEN(ary));
    return dup;
}

static inline long
rotate_count(long cnt, long len)
{
    return (cnt < 0) ? (len - (~cnt % len) - 1) : (cnt % len);
}

VALUE
rb_ary_rotate(VALUE ary, long cnt)
{
    rb_ary_modify(ary);

    if (cnt != 0) {
	VALUE *ptr = RARRAY_PTR(ary);
	long len = RARRAY_LEN(ary);

	if (len > 0 && (cnt = rotate_count(cnt, len)) > 0) {
	    --len;
	    if (cnt < len) ary_reverse(ptr + cnt, ptr + len);
	    if (--cnt > 0) ary_reverse(ptr, ptr + cnt);
	    if (len > 0) ary_reverse(ptr, ptr + len);
	    return ary;
	}
    }

    return Qnil;
}

/*
 *  call-seq:
 *     ary.rotate!(count=1)   -> ary
 *
 *  Rotates +self+ in place so that the element at +count+ comes first, and
 *  returns +self+.
 *
 *  If +count+ is negative then it rotates in the opposite direction, starting
 *  from the end of the array where +-1+ is the last element.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.rotate!        #=> ["b", "c", "d", "a"]
 *     a                #=> ["b", "c", "d", "a"]
 *     a.rotate!(2)     #=> ["d", "a", "b", "c"]
 *     a.rotate!(-3)    #=> ["a", "b", "c", "d"]
 */

static VALUE
rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary)
{
    long n = 1;

    switch (argc) {
      case 1: n = NUM2LONG(argv[0]);
      case 0: break;
      default: rb_scan_args(argc, argv, "01", NULL);
    }
    rb_ary_rotate(ary, n);
    return ary;
}

/*
 *  call-seq:
 *     ary.rotate(count=1)    -> new_ary
 *
 *  Returns a new array by rotating +self+ so that the element at +count+ is
 *  the first element of the new array.
 *
 *  If +count+ is negative then it rotates in the opposite direction, starting
 *  from the end of +self+ where +-1+ is the last element.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.rotate         #=> ["b", "c", "d", "a"]
 *     a                #=> ["a", "b", "c", "d"]
 *     a.rotate(2)      #=> ["c", "d", "a", "b"]
 *     a.rotate(-3)     #=> ["b", "c", "d", "a"]
 */

static VALUE
rb_ary_rotate_m(int argc, VALUE *argv, VALUE ary)
{
    VALUE rotated;
    const VALUE *ptr;
    long len, cnt = 1;

    switch (argc) {
      case 1: cnt = NUM2LONG(argv[0]);
      case 0: break;
      default: rb_scan_args(argc, argv, "01", NULL);
    }

    len = RARRAY_LEN(ary);
    rotated = rb_ary_new2(len);
    if (len > 0) {
	cnt = rotate_count(cnt, len);
	ptr = RARRAY_CONST_PTR(ary);
	len -= cnt;
	ary_memcpy(rotated, 0, len, ptr + cnt);
	ary_memcpy(rotated, len, cnt, ptr);
    }
    ARY_SET_LEN(rotated, RARRAY_LEN(ary));
    return rotated;
}

struct ary_sort_data {
    VALUE ary;
    struct cmp_opt_data cmp_opt;
};

static VALUE
sort_reentered(VALUE ary)
{
    if (RBASIC(ary)->klass) {
	rb_raise(rb_eRuntimeError, "sort reentered");
    }
    return Qnil;
}

static int
sort_1(const void *ap, const void *bp, void *dummy)
{
    struct ary_sort_data *data = dummy;
    VALUE retval = sort_reentered(data->ary);
    VALUE a = *(const VALUE *)ap, b = *(const VALUE *)bp;
    VALUE args[2];
    int n;

    args[0] = a;
    args[1] = b;
    retval = rb_yield_values2(2, args);
    n = rb_cmpint(retval, a, b);
    sort_reentered(data->ary);
    return n;
}

static int
sort_2(const void *ap, const void *bp, void *dummy)
{
    struct ary_sort_data *data = dummy;
    VALUE retval = sort_reentered(data->ary);
    VALUE a = *(const VALUE *)ap, b = *(const VALUE *)bp;
    int n;

    if (FIXNUM_P(a) && FIXNUM_P(b) && CMP_OPTIMIZABLE(data->cmp_opt, Fixnum)) {
	if ((long)a > (long)b) return 1;
	if ((long)a < (long)b) return -1;
	return 0;
    }
    if (STRING_P(a) && STRING_P(b) && CMP_OPTIMIZABLE(data->cmp_opt, String)) {
	return rb_str_cmp(a, b);
    }
    if (RB_FLOAT_TYPE_P(a) && CMP_OPTIMIZABLE(data->cmp_opt, Float)) {
	return rb_float_cmp(a, b);
    }

    retval = rb_funcallv(a, id_cmp, 1, &b);
    n = rb_cmpint(retval, a, b);
    sort_reentered(data->ary);

    return n;
}

/*
 *  call-seq:
 *     ary.sort!                   -> ary
 *     ary.sort! { |a, b| block }  -> ary
 *
 *  Sorts +self+ in place.
 *
 *  Comparisons for the sort will be done using the <=> operator
 *  or using an optional code block.
 *
 *  The block must implement a comparison between +a+ and +b+ and return
 *  an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+
 *  are equivalent, or an integer greater than 0 when +a+ follows +b+.
 *
 *  The result is not guaranteed to be stable.  When the comparison of two
 *  elements returns +0+, the order of the elements is unpredictable.
 *
 *     ary = [ "d", "a", "e", "c", "b" ]
 *     ary.sort!                     #=> ["a", "b", "c", "d", "e"]
 *     ary.sort! { |a, b| b <=> a }  #=> ["e", "d", "c", "b", "a"]
 *
 *  See also Enumerable#sort_by.
 */

VALUE
rb_ary_sort_bang(VALUE ary)
{
    rb_ary_modify(ary);
    assert(!ARY_SHARED_P(ary));
    if (RARRAY_LEN(ary) > 1) {
	VALUE tmp = ary_make_substitution(ary); /* only ary refers tmp */
	struct ary_sort_data data;
	long len = RARRAY_LEN(ary);

	RBASIC_CLEAR_CLASS(tmp);
	data.ary = tmp;
	data.cmp_opt.opt_methods = 0;
	data.cmp_opt.opt_inited = 0;
	RARRAY_PTR_USE(tmp, ptr, {
	    ruby_qsort(ptr, len, sizeof(VALUE),
		       rb_block_given_p()?sort_1:sort_2, &data);
	}); /* WB: no new reference */
	rb_ary_modify(ary);
        if (ARY_EMBED_P(tmp)) {
            if (ARY_SHARED_P(ary)) { /* ary might be destructively operated in the given block */
                rb_ary_unshare(ary);
		FL_SET_EMBED(ary);
            }
	    ary_memcpy(ary, 0, ARY_EMBED_LEN(tmp), ARY_EMBED_PTR(tmp));
            ARY_SET_LEN(ary, ARY_EMBED_LEN(tmp));
        }
        else {
            if (!ARY_EMBED_P(ary) && ARY_HEAP_PTR(ary) == ARY_HEAP_PTR(tmp)) {
                FL_UNSET_SHARED(ary);
                ARY_SET_CAPA(ary, RARRAY_LEN(tmp));
            }
            else {
                assert(!ARY_SHARED_P(tmp));
                if (ARY_EMBED_P(ary)) {
                    FL_UNSET_EMBED(ary);
                }
                else if (ARY_SHARED_P(ary)) {
                    /* ary might be destructively operated in the given block */
                    rb_ary_unshare(ary);
                }
                else {
		    ruby_sized_xfree((void *)ARY_HEAP_PTR(ary), ARY_HEAP_SIZE(ary));
                }
                ARY_SET_PTR(ary, RARRAY_CONST_PTR(tmp));
                ARY_SET_HEAP_LEN(ary, len);
                ARY_SET_CAPA(ary, RARRAY_LEN(tmp));
            }
            /* tmp was lost ownership for the ptr */
            FL_UNSET(tmp, FL_FREEZE);
            FL_SET_EMBED(tmp);
            ARY_SET_EMBED_LEN(tmp, 0);
            FL_SET(tmp, FL_FREEZE);
	}
        /* tmp will be GC'ed. */
        RBASIC_SET_CLASS_RAW(tmp, rb_cArray); /* rb_cArray must be marked */
    }
    return ary;
}

/*
 *  call-seq:
 *     ary.sort                   -> new_ary
 *     ary.sort { |a, b| block }  -> new_ary
 *
 *  Returns a new array created by sorting +self+.
 *
 *  Comparisons for the sort will be done using the <=> operator
 *  or using an optional code block.
 *
 *  The block must implement a comparison between +a+ and +b+ and return
 *  an integer less than 0 when +b+ follows +a+, +0+ when +a+ and +b+
 *  are equivalent, or an integer greater than 0 when +a+ follows +b+.
 *
 *  The result is not guaranteed to be stable.  When the comparison of two
 *  elements returns +0+, the order of the elements is unpredictable.
 *
 *     ary = [ "d", "a", "e", "c", "b" ]
 *     ary.sort                     #=> ["a", "b", "c", "d", "e"]
 *     ary.sort { |a, b| b <=> a }  #=> ["e", "d", "c", "b", "a"]
 *
 *  See also Enumerable#sort_by.
 */

VALUE
rb_ary_sort(VALUE ary)
{
    ary = rb_ary_dup(ary);
    rb_ary_sort_bang(ary);
    return ary;
}

static VALUE rb_ary_bsearch_index(VALUE ary);

/*
 *  call-seq:
 *     ary.bsearch {|x| block }  -> elem
 *
 *  By using binary search, finds a value from this array which meets
 *  the given condition in O(log n) where n is the size of the array.
 *
 *  You can use this method in two use cases: a find-minimum mode and
 *  a find-any mode.  In either case, the elements of the array must be
 *  monotone (or sorted) with respect to the block.
 *
 *  In find-minimum mode (this is a good choice for typical use case),
 *  the block must return true or false, and there must be an index i
 *  (0 <= i <= ary.size) so that:
 *
 *  - the block returns false for any element whose index is less than
 *    i, and
 *  - the block returns true for any element whose index is greater
 *    than or equal to i.
 *
 *  This method returns the i-th element.  If i is equal to ary.size,
 *  it returns nil.
 *
 *     ary = [0, 4, 7, 10, 12]
 *     ary.bsearch {|x| x >=   4 } #=> 4
 *     ary.bsearch {|x| x >=   6 } #=> 7
 *     ary.bsearch {|x| x >=  -1 } #=> 0
 *     ary.bsearch {|x| x >= 100 } #=> nil
 *
 *  In find-any mode (this behaves like libc's bsearch(3)), the block
 *  must return a number, and there must be two indices i and j
 *  (0 <= i <= j <= ary.size) so that:
 *
 *  - the block returns a positive number for ary[k] if 0 <= k < i,
 *  - the block returns zero for ary[k] if i <= k < j, and
 *  - the block returns a negative number for ary[k] if
 *    j <= k < ary.size.
 *
 *  Under this condition, this method returns any element whose index
 *  is within i...j.  If i is equal to j (i.e., there is no element
 *  that satisfies the block), this method returns nil.
 *
 *     ary = [0, 4, 7, 10, 12]
 *     # try to find v such that 4 <= v < 8
 *     ary.bsearch {|x| 1 - x / 4 } #=> 4 or 7
 *     # try to find v such that 8 <= v < 10
 *     ary.bsearch {|x| 4 - x / 2 } #=> nil
 *
 *  You must not mix the two modes at a time; the block must always
 *  return either true/false, or always return a number.  It is
 *  undefined which value is actually picked up at each iteration.
 */

static VALUE
rb_ary_bsearch(VALUE ary)
{
    VALUE index_result = rb_ary_bsearch_index(ary);

    if (FIXNUM_P(index_result)) {
	return rb_ary_entry(ary, FIX2LONG(index_result));
    }
    return index_result;
}

/*
 *  call-seq:
 *     ary.bsearch_index {|x| block }  -> int or nil
 *
 *  By using binary search, finds an index of a value from this array which
 *  meets the given condition in O(log n) where n is the size of the array.
 *
 *  It supports two modes, depending on the nature of the block and they are
 *  exactly the same as in the case of #bsearch method with the only difference
 *  being that this method returns the index of the element instead of the
 *  element itself. For more details consult the documentation for #bsearch.
 */

static VALUE
rb_ary_bsearch_index(VALUE ary)
{
    long low = 0, high = RARRAY_LEN(ary), mid;
    int smaller = 0, satisfied = 0;
    VALUE v, val;

    RETURN_ENUMERATOR(ary, 0, 0);
    while (low < high) {
	mid = low + ((high - low) / 2);
	val = rb_ary_entry(ary, mid);
	v = rb_yield(val);
	if (FIXNUM_P(v)) {
	    if (v == INT2FIX(0)) return INT2FIX(mid);
	    smaller = (SIGNED_VALUE)v < 0; /* Fixnum preserves its sign-bit */
	}
	else if (v == Qtrue) {
	    satisfied = 1;
	    smaller = 1;
	}
	else if (v == Qfalse || v == Qnil) {
	    smaller = 0;
	}
	else if (rb_obj_is_kind_of(v, rb_cNumeric)) {
	    const VALUE zero = INT2FIX(0);
	    switch (rb_cmpint(rb_funcallv(v, id_cmp, 1, &zero), v, zero)) {
	      case 0: return INT2FIX(mid);
	      case 1: smaller = 1; break;
	      case -1: smaller = 0;
	    }
	}
	else {
	    rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE
		     " (must be numeric, true, false or nil)",
		     rb_obj_class(v));
	}
	if (smaller) {
	    high = mid;
	}
	else {
	    low = mid + 1;
	}
    }
    if (!satisfied) return Qnil;
    return INT2FIX(low);
}


static VALUE
sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy))
{
    return rb_yield(i);
}

/*
 *  call-seq:
 *     ary.sort_by! { |obj| block }    -> ary
 *     ary.sort_by!                    -> Enumerator
 *
 *  Sorts +self+ in place using a set of keys generated by mapping the
 *  values in +self+ through the given block.
 *
 *  The result is not guaranteed to be stable.  When two keys are equal,
 *  the order of the corresponding elements is unpredictable.
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *  See also Enumerable#sort_by.
 */

static VALUE
rb_ary_sort_by_bang(VALUE ary)
{
    VALUE sorted;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    rb_ary_modify(ary);
    sorted = rb_block_call(ary, rb_intern("sort_by"), 0, 0, sort_by_i, 0);
    rb_ary_replace(ary, sorted);
    return ary;
}


/*
 *  call-seq:
 *     ary.collect { |item| block }  -> new_ary
 *     ary.map     { |item| block }  -> new_ary
 *     ary.collect                   -> Enumerator
 *     ary.map                       -> Enumerator
 *
 *  Invokes the given block once for each element of +self+.
 *
 *  Creates a new array containing the values returned by the block.
 *
 *  See also Enumerable#collect.
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.collect { |x| x + "!" }         #=> ["a!", "b!", "c!", "d!"]
 *     a.map.with_index { |x, i| x * i } #=> ["", "b", "cc", "ddd"]
 *     a                                 #=> ["a", "b", "c", "d"]
 */

static VALUE
rb_ary_collect(VALUE ary)
{
    long i;
    VALUE collect;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    collect = rb_ary_new2(RARRAY_LEN(ary));
    for (i = 0; i < RARRAY_LEN(ary); i++) {
	rb_ary_push(collect, rb_yield(RARRAY_AREF(ary, i)));
    }
    return collect;
}


/*
 *  call-seq:
 *     ary.collect! {|item| block }   -> ary
 *     ary.map!     {|item| block }   -> ary
 *     ary.collect!                   -> Enumerator
 *     ary.map!                       -> Enumerator
 *
 *  Invokes the given block once for each element of +self+, replacing the
 *  element with the value returned by the block.
 *
 *  See also Enumerable#collect.
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.map! {|x| x + "!" }
 *     a #=>  [ "a!", "b!", "c!", "d!" ]
 *     a.collect!.with_index {|x, i| x[0...i] }
 *     a #=>  ["", "b", "c!", "d!"]
 */

static VALUE
rb_ary_collect_bang(VALUE ary)
{
    long i;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    rb_ary_modify(ary);
    for (i = 0; i < RARRAY_LEN(ary); i++) {
	rb_ary_store(ary, i, rb_yield(RARRAY_AREF(ary, i)));
    }
    return ary;
}

VALUE
rb_get_values_at(VALUE obj, long olen, int argc, const VALUE *argv, VALUE (*func) (VALUE, long))
{
    VALUE result = rb_ary_new2(argc);
    long beg, len, i, j;

    for (i=0; i j)
		rb_ary_resize(result, RARRAY_LEN(result) + (beg + len) - j);
	    continue;
	}
	rb_ary_push(result, (*func)(obj, NUM2LONG(argv[i])));
    }
    return result;
}

/*
 *  call-seq:
 *     ary.values_at(selector, ...)  -> new_ary
 *
 *  Returns an array containing the elements in +self+ corresponding to the
 *  given +selector+(s).
 *
 *  The selectors may be either integer indices or ranges.
 *
 *  See also Array#select.
 *
 *     a = %w{ a b c d e f }
 *     a.values_at(1, 3, 5)          # => ["b", "d", "f"]
 *     a.values_at(1, 3, 5, 7)       # => ["b", "d", "f", nil]
 *     a.values_at(-1, -2, -2, -7)   # => ["f", "e", "e", nil]
 *     a.values_at(4..6, 3...6)      # => ["e", "f", nil, "d", "e", "f"]
 */

static VALUE
rb_ary_values_at(int argc, VALUE *argv, VALUE ary)
{
    return rb_get_values_at(ary, RARRAY_LEN(ary), argc, argv, rb_ary_entry);
}


/*
 *  call-seq:
 *     ary.select { |item| block } -> new_ary
 *     ary.select                  -> Enumerator
 *
 *  Returns a new array containing all elements of +ary+
 *  for which the given +block+ returns a true value.
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *     [1,2,3,4,5].select { |num|  num.even?  }   #=> [2, 4]
 *
 *     a = %w{ a b c d e f }
 *     a.select { |v| v =~ /[aeiou]/ }  #=> ["a", "e"]
 *
 *  See also Enumerable#select.
 */

static VALUE
rb_ary_select(VALUE ary)
{
    VALUE result;
    long i;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    result = rb_ary_new2(RARRAY_LEN(ary));
    for (i = 0; i < RARRAY_LEN(ary); i++) {
	if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) {
	    rb_ary_push(result, rb_ary_elt(ary, i));
	}
    }
    return result;
}

struct select_bang_arg {
    VALUE ary;
    long len[2];
};

static VALUE
select_bang_i(VALUE a)
{
    volatile struct select_bang_arg *arg = (void *)a;
    VALUE ary = arg->ary;
    long i1, i2;

    for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); arg->len[0] = ++i1) {
	VALUE v = RARRAY_AREF(ary, i1);
	if (!RTEST(rb_yield(v))) continue;
	if (i1 != i2) {
	    rb_ary_store(ary, i2, v);
	}
	arg->len[1] = ++i2;
    }
    return (i1 == i2) ? Qnil : ary;
}

static VALUE
select_bang_ensure(VALUE a)
{
    volatile struct select_bang_arg *arg = (void *)a;
    VALUE ary = arg->ary;
    long len = RARRAY_LEN(ary);
    long i1 = arg->len[0], i2 = arg->len[1];

    if (i2 < len && i2 < i1) {
	long tail = 0;
	if (i1 < len) {
	    tail = len - i1;
	    RARRAY_PTR_USE(ary, ptr, {
		    MEMMOVE(ptr + i2, ptr + i1, VALUE, tail);
		});
	}
	ARY_SET_LEN(ary, i2 + tail);
    }
    return ary;
}

/*
 *  call-seq:
 *     ary.select!  {|item| block } -> ary or nil
 *     ary.select!                  -> Enumerator
 *
 *  Invokes the given block passing in successive elements from +self+,
 *  deleting elements for which the block returns a +false+ value.
 *
 *  The array may not be changed instantly every time the block is called.
 *
 *  If changes were made, it will return +self+, otherwise it returns +nil+.
 *
 *  See also Array#keep_if
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 */

static VALUE
rb_ary_select_bang(VALUE ary)
{
    struct select_bang_arg args;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    rb_ary_modify(ary);

    args.ary = ary;
    args.len[0] = args.len[1] = 0;
    return rb_ensure(select_bang_i, (VALUE)&args, select_bang_ensure, (VALUE)&args);
}

/*
 *  call-seq:
 *     ary.keep_if { |item| block } -> ary
 *     ary.keep_if                  -> Enumerator
 *
 *  Deletes every element of +self+ for which the given block evaluates to
 *  +false+.
 *
 *  See also Array#select!
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *     a = %w{ a b c d e f }
 *     a.keep_if { |v| v =~ /[aeiou]/ }  #=> ["a", "e"]
 */

static VALUE
rb_ary_keep_if(VALUE ary)
{
    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    rb_ary_select_bang(ary);
    return ary;
}

static void
ary_resize_smaller(VALUE ary, long len)
{
    rb_ary_modify(ary);
    if (RARRAY_LEN(ary) > len) {
	ARY_SET_LEN(ary, len);
	if (len * 2 < ARY_CAPA(ary) &&
	    ARY_CAPA(ary) > ARY_DEFAULT_SIZE) {
	    ary_resize_capa(ary, len * 2);
	}
    }
}

/*
 *  call-seq:
 *     ary.delete(obj)            -> item or nil
 *     ary.delete(obj) { block }  -> item or result of block
 *
 *  Deletes all items from +self+ that are equal to +obj+.
 *
 *  Returns the last deleted item, or +nil+ if no matching item is found.
 *
 *  If the optional code block is given, the result of the block is returned if
 *  the item is not found.  (To remove +nil+ elements and get an informative
 *  return value, use Array#compact!)
 *
 *     a = [ "a", "b", "b", "b", "c" ]
 *     a.delete("b")                   #=> "b"
 *     a                               #=> ["a", "c"]
 *     a.delete("z")                   #=> nil
 *     a.delete("z") { "not found" }   #=> "not found"
 */

VALUE
rb_ary_delete(VALUE ary, VALUE item)
{
    VALUE v = item;
    long i1, i2;

    for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
	VALUE e = RARRAY_AREF(ary, i1);

	if (rb_equal(e, item)) {
	    v = e;
	    continue;
	}
	if (i1 != i2) {
	    rb_ary_store(ary, i2, e);
	}
	i2++;
    }
    if (RARRAY_LEN(ary) == i2) {
	if (rb_block_given_p()) {
	    return rb_yield(item);
	}
	return Qnil;
    }

    ary_resize_smaller(ary, i2);

    return v;
}

void
rb_ary_delete_same(VALUE ary, VALUE item)
{
    long i1, i2;

    for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); i1++) {
	VALUE e = RARRAY_AREF(ary, i1);

	if (e == item) {
	    continue;
	}
	if (i1 != i2) {
	    rb_ary_store(ary, i2, e);
	}
	i2++;
    }
    if (RARRAY_LEN(ary) == i2) {
	return;
    }

    ary_resize_smaller(ary, i2);
}

VALUE
rb_ary_delete_at(VALUE ary, long pos)
{
    long len = RARRAY_LEN(ary);
    VALUE del;

    if (pos >= len) return Qnil;
    if (pos < 0) {
	pos += len;
	if (pos < 0) return Qnil;
    }

    rb_ary_modify(ary);
    del = RARRAY_AREF(ary, pos);
    RARRAY_PTR_USE(ary, ptr, {
	MEMMOVE(ptr+pos, ptr+pos+1, VALUE, len-pos-1);
    });
    ARY_INCREASE_LEN(ary, -1);

    return del;
}

/*
 *  call-seq:
 *     ary.delete_at(index)  -> obj or nil
 *
 *  Deletes the element at the specified +index+, returning that element, or
 *  +nil+ if the +index+ is out of range.
 *
 *  See also Array#slice!
 *
 *     a = ["ant", "bat", "cat", "dog"]
 *     a.delete_at(2)    #=> "cat"
 *     a                 #=> ["ant", "bat", "dog"]
 *     a.delete_at(99)   #=> nil
 */

static VALUE
rb_ary_delete_at_m(VALUE ary, VALUE pos)
{
    return rb_ary_delete_at(ary, NUM2LONG(pos));
}

/*
 *  call-seq:
 *     ary.slice!(index)         -> obj or nil
 *     ary.slice!(start, length) -> new_ary or nil
 *     ary.slice!(range)         -> new_ary or nil
 *
 *  Deletes the element(s) given by an +index+ (optionally up to +length+
 *  elements) or by a +range+.
 *
 *  Returns the deleted object (or objects), or +nil+ if the +index+ is out of
 *  range.
 *
 *     a = [ "a", "b", "c" ]
 *     a.slice!(1)     #=> "b"
 *     a               #=> ["a", "c"]
 *     a.slice!(-1)    #=> "c"
 *     a               #=> ["a"]
 *     a.slice!(100)   #=> nil
 *     a               #=> ["a"]
 */

static VALUE
rb_ary_slice_bang(int argc, VALUE *argv, VALUE ary)
{
    VALUE arg1, arg2;
    long pos, len, orig_len;

    rb_ary_modify_check(ary);
    if (argc == 2) {
	pos = NUM2LONG(argv[0]);
	len = NUM2LONG(argv[1]);
      delete_pos_len:
	if (len < 0) return Qnil;
	orig_len = RARRAY_LEN(ary);
	if (pos < 0) {
	    pos += orig_len;
	    if (pos < 0) return Qnil;
	}
	else if (orig_len < pos) return Qnil;
	if (orig_len < pos + len) {
	    len = orig_len - pos;
	}
	if (len == 0) return rb_ary_new2(0);
	arg2 = rb_ary_new4(len, RARRAY_CONST_PTR(ary)+pos);
	RBASIC_SET_CLASS(arg2, rb_obj_class(ary));
	rb_ary_splice(ary, pos, len, 0, 0);
	return arg2;
    }

    if (argc != 1) {
	/* error report */
	rb_scan_args(argc, argv, "11", NULL, NULL);
    }
    arg1 = argv[0];

    if (!FIXNUM_P(arg1)) {
	switch (rb_range_beg_len(arg1, &pos, &len, RARRAY_LEN(ary), 0)) {
	  case Qtrue:
	    /* valid range */
	    goto delete_pos_len;
	  case Qnil:
	    /* invalid range */
	    return Qnil;
	  default:
	    /* not a range */
	    break;
	}
    }

    return rb_ary_delete_at(ary, NUM2LONG(arg1));
}

static VALUE
ary_reject(VALUE orig, VALUE result)
{
    long i;

    for (i = 0; i < RARRAY_LEN(orig); i++) {
	VALUE v = RARRAY_AREF(orig, i);
	if (!RTEST(rb_yield(v))) {
	    rb_ary_push(result, v);
	}
    }
    return result;
}

static VALUE
reject_bang_i(VALUE a)
{
    volatile struct select_bang_arg *arg = (void *)a;
    VALUE ary = arg->ary;
    long i1, i2;

    for (i1 = i2 = 0; i1 < RARRAY_LEN(ary); arg->len[0] = ++i1) {
	VALUE v = RARRAY_AREF(ary, i1);
	if (RTEST(rb_yield(v))) continue;
	if (i1 != i2) {
	    rb_ary_store(ary, i2, v);
	}
	arg->len[1] = ++i2;
    }
    return (i1 == i2) ? Qnil : ary;
}

static VALUE
ary_reject_bang(VALUE ary)
{
    struct select_bang_arg args;

    rb_ary_modify_check(ary);
    args.ary = ary;
    args.len[0] = args.len[1] = 0;
    return rb_ensure(reject_bang_i, (VALUE)&args, select_bang_ensure, (VALUE)&args);
}

/*
 *  call-seq:
 *     ary.reject! { |item| block }  -> ary or nil
 *     ary.reject!                   -> Enumerator
 *
 *  Deletes every element of +self+ for which the block evaluates to +true+,
 *  if no changes were made returns +nil+.
 *
 *  The array may not be changed instantly every time the block is called.
 *
 *  See also Enumerable#reject and Array#delete_if.
 *
 *  If no block is given, an Enumerator is returned instead.
 */

static VALUE
rb_ary_reject_bang(VALUE ary)
{
    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    return ary_reject_bang(ary);
}

/*
 *  call-seq:
 *     ary.reject  {|item| block }  -> new_ary
 *     ary.reject                   -> Enumerator
 *
 *  Returns a new array containing the items in +self+ for which the given
 *  block is not +true+. The ordering of non-rejected elements is maintained.
 *
 *  See also Array#delete_if
 *
 *  If no block is given, an Enumerator is returned instead.
 */

static VALUE
rb_ary_reject(VALUE ary)
{
    VALUE rejected_ary;

    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    rejected_ary = rb_ary_new();
    ary_reject(ary, rejected_ary);
    return rejected_ary;
}

/*
 *  call-seq:
 *     ary.delete_if { |item| block }  -> ary
 *     ary.delete_if                   -> Enumerator
 *
 *  Deletes every element of +self+ for which block evaluates to +true+.
 *
 *  The array is changed instantly every time the block is called, not after
 *  the iteration is over.
 *
 *  See also Array#reject!
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *     scores = [ 97, 42, 75 ]
 *     scores.delete_if {|score| score < 80 }   #=> [97]
 */

static VALUE
rb_ary_delete_if(VALUE ary)
{
    RETURN_SIZED_ENUMERATOR(ary, 0, 0, ary_enum_length);
    ary_reject_bang(ary);
    return ary;
}

static VALUE
take_i(RB_BLOCK_CALL_FUNC_ARGLIST(val, cbarg))
{
    VALUE *args = (VALUE *)cbarg;
    if (args[1]-- == 0) rb_iter_break();
    if (argc > 1) val = rb_ary_new4(argc, argv);
    rb_ary_push(args[0], val);
    return Qnil;
}

static VALUE
take_items(VALUE obj, long n)
{
    VALUE result = rb_check_array_type(obj);
    VALUE args[2];

    if (!NIL_P(result)) return rb_ary_subseq(result, 0, n);
    result = rb_ary_new2(n);
    args[0] = result; args[1] = (VALUE)n;
    if (rb_check_block_call(obj, idEach, 0, 0, take_i, (VALUE)args) == Qundef)
	rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE" (must respond to :each)",
		 rb_obj_class(obj));
    return result;
}


/*
 *  call-seq:
 *     ary.zip(arg, ...)                  -> new_ary
 *     ary.zip(arg, ...) { |arr| block }  -> nil
 *
 *  Converts any arguments to arrays, then merges elements of +self+ with
 *  corresponding elements from each argument.
 *
 *  This generates a sequence of ary.size _n_-element arrays,
 *  where _n_ is one more than the count of arguments.
 *
 *  If the size of any argument is less than the size of the initial array,
 *  +nil+ values are supplied.
 *
 *  If a block is given, it is invoked for each output +array+, otherwise an
 *  array of arrays is returned.
 *
 *     a = [ 4, 5, 6 ]
 *     b = [ 7, 8, 9 ]
 *     [1, 2, 3].zip(a, b)   #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
 *     [1, 2].zip(a, b)      #=> [[1, 4, 7], [2, 5, 8]]
 *     a.zip([1, 2], [8])    #=> [[4, 1, 8], [5, 2, nil], [6, nil, nil]]
 */

static VALUE
rb_ary_zip(int argc, VALUE *argv, VALUE ary)
{
    int i, j;
    long len = RARRAY_LEN(ary);
    VALUE result = Qnil;

    for (i=0; i 1) {
	    VALUE work, *tmp;

	    tmp = ALLOCV_N(VALUE, work, argc+1);

	    for (i=0; i new_ary
 *
 *  Assumes that +self+ is an array of arrays and transposes the rows and
 *  columns.
 *
 *     a = [[1,2], [3,4], [5,6]]
 *     a.transpose   #=> [[1, 3, 5], [2, 4, 6]]
 *
 *  If the length of the subarrays don't match, an IndexError is raised.
 */

static VALUE
rb_ary_transpose(VALUE ary)
{
    long elen = -1, alen, i, j;
    VALUE tmp, result = 0;

    alen = RARRAY_LEN(ary);
    if (alen == 0) return rb_ary_dup(ary);
    for (i=0; i ary
 *     ary.initialize_copy(other_ary)	-> ary
 *
 *  Replaces the contents of +self+ with the contents of +other_ary+,
 *  truncating or expanding if necessary.
 *
 *     a = [ "a", "b", "c", "d", "e" ]
 *     a.replace([ "x", "y", "z" ])   #=> ["x", "y", "z"]
 *     a                              #=> ["x", "y", "z"]
 */

VALUE
rb_ary_replace(VALUE copy, VALUE orig)
{
    rb_ary_modify_check(copy);
    orig = to_ary(orig);
    if (copy == orig) return copy;

    if (RARRAY_LEN(orig) <= RARRAY_EMBED_LEN_MAX) {
        VALUE shared = 0;

        if (ARY_OWNS_HEAP_P(copy)) {
	    RARRAY_PTR_USE(copy, ptr, ruby_sized_xfree(ptr, ARY_HEAP_SIZE(copy)));
	}
        else if (ARY_SHARED_P(copy)) {
            shared = ARY_SHARED(copy);
            FL_UNSET_SHARED(copy);
        }
        FL_SET_EMBED(copy);
	ary_memcpy(copy, 0, RARRAY_LEN(orig), RARRAY_CONST_PTR(orig));
        if (shared) {
            rb_ary_decrement_share(shared);
        }
        ARY_SET_LEN(copy, RARRAY_LEN(orig));
    }
    else {
        VALUE shared = ary_make_shared(orig);
        if (ARY_OWNS_HEAP_P(copy)) {
	    RARRAY_PTR_USE(copy, ptr, ruby_sized_xfree(ptr, ARY_HEAP_SIZE(copy)));
        }
        else {
            rb_ary_unshare_safe(copy);
        }
        FL_UNSET_EMBED(copy);
        ARY_SET_PTR(copy, RARRAY_CONST_PTR(orig));
        ARY_SET_LEN(copy, RARRAY_LEN(orig));
        rb_ary_set_shared(copy, shared);
    }
    return copy;
}

/*
 *  call-seq:
 *     ary.clear    -> ary
 *
 *  Removes all elements from +self+.
 *
 *     a = [ "a", "b", "c", "d", "e" ]
 *     a.clear    #=> [ ]
 */

VALUE
rb_ary_clear(VALUE ary)
{
    rb_ary_modify_check(ary);
    ARY_SET_LEN(ary, 0);
    if (ARY_SHARED_P(ary)) {
	if (!ARY_EMBED_P(ary)) {
	    rb_ary_unshare(ary);
	    FL_SET_EMBED(ary);
	}
    }
    else if (ARY_DEFAULT_SIZE * 2 < ARY_CAPA(ary)) {
	ary_resize_capa(ary, ARY_DEFAULT_SIZE * 2);
    }
    return ary;
}

/*
 *  call-seq:
 *     ary.fill(obj)                                 -> ary
 *     ary.fill(obj, start [, length])               -> ary
 *     ary.fill(obj, range )                         -> ary
 *     ary.fill { |index| block }                    -> ary
 *     ary.fill(start [, length] ) { |index| block } -> ary
 *     ary.fill(range) { |index| block }             -> ary
 *
 *  The first three forms set the selected elements of +self+ (which
 *  may be the entire array) to +obj+.
 *
 *  A +start+ of +nil+ is equivalent to zero.
 *
 *  A +length+ of +nil+ is equivalent to the length of the array.
 *
 *  The last three forms fill the array with the value of the given block,
 *  which is passed the absolute index of each element to be filled.
 *
 *  Negative values of +start+ count from the end of the array, where +-1+ is
 *  the last element.
 *
 *     a = [ "a", "b", "c", "d" ]
 *     a.fill("x")              #=> ["x", "x", "x", "x"]
 *     a.fill("z", 2, 2)        #=> ["x", "x", "z", "z"]
 *     a.fill("y", 0..1)        #=> ["y", "y", "z", "z"]
 *     a.fill { |i| i*i }       #=> [0, 1, 4, 9]
 *     a.fill(-2) { |i| i*i*i } #=> [0, 1, 8, 27]
 */

static VALUE
rb_ary_fill(int argc, VALUE *argv, VALUE ary)
{
    VALUE item = Qundef, arg1, arg2;
    long beg = 0, end = 0, len = 0;

    if (rb_block_given_p()) {
	rb_scan_args(argc, argv, "02", &arg1, &arg2);
	argc += 1;		/* hackish */
    }
    else {
	rb_scan_args(argc, argv, "12", &item, &arg1, &arg2);
    }
    switch (argc) {
      case 1:
	beg = 0;
	len = RARRAY_LEN(ary);
	break;
      case 2:
	if (rb_range_beg_len(arg1, &beg, &len, RARRAY_LEN(ary), 1)) {
	    break;
	}
	/* fall through */
      case 3:
	beg = NIL_P(arg1) ? 0 : NUM2LONG(arg1);
	if (beg < 0) {
	    beg = RARRAY_LEN(ary) + beg;
	    if (beg < 0) beg = 0;
	}
	len = NIL_P(arg2) ? RARRAY_LEN(ary) - beg : NUM2LONG(arg2);
	break;
    }
    rb_ary_modify(ary);
    if (len < 0) {
        return ary;
    }
    if (beg >= ARY_MAX_SIZE || len > ARY_MAX_SIZE - beg) {
	rb_raise(rb_eArgError, "argument too big");
    }
    end = beg + len;
    if (RARRAY_LEN(ary) < end) {
	if (end >= ARY_CAPA(ary)) {
	    ary_resize_capa(ary, end);
	}
	ary_mem_clear(ary, RARRAY_LEN(ary), end - RARRAY_LEN(ary));
	ARY_SET_LEN(ary, end);
    }

    if (item == Qundef) {
	VALUE v;
	long i;

	for (i=beg; i=RARRAY_LEN(ary)) break;
	    ARY_SET(ary, i, v);
	}
    }
    else {
	ary_memfill(ary, beg, len, item);
    }
    return ary;
}

/*
 *  call-seq:
 *     ary + other_ary   -> new_ary
 *
 *  Concatenation --- Returns a new array built by concatenating the
 *  two arrays together to produce a third array.
 *
 *     [ 1, 2, 3 ] + [ 4, 5 ]    #=> [ 1, 2, 3, 4, 5 ]
 *     a = [ "a", "b", "c" ]
 *     c = a + [ "d", "e", "f" ]
 *     c                         #=> [ "a", "b", "c", "d", "e", "f" ]
 *     a                         #=> [ "a", "b", "c" ]
 *
 *  Note that
 *     x += y
 *  is the same as
 *     x = x + y
 *  This means that it produces a new array. As a consequence,
 *  repeated use of += on arrays can be quite inefficient.
 *
 *  See also Array#concat.
 */

VALUE
rb_ary_plus(VALUE x, VALUE y)
{
    VALUE z;
    long len, xlen, ylen;

    y = to_ary(y);
    xlen = RARRAY_LEN(x);
    ylen = RARRAY_LEN(y);
    len = xlen + ylen;
    z = rb_ary_new2(len);

    ary_memcpy(z, 0, xlen, RARRAY_CONST_PTR(x));
    ary_memcpy(z, xlen, ylen, RARRAY_CONST_PTR(y));
    ARY_SET_LEN(z, len);
    return z;
}

static VALUE
ary_append(VALUE x, VALUE y)
{
    long n = RARRAY_LEN(y);
    if (n > 0) {
	rb_ary_splice(x, RARRAY_LEN(x), 0, RARRAY_CONST_PTR(y), n);
    }
    return x;
}

/*
 *  call-seq:
 *     ary.concat(other_ary1, other_ary2,...)   -> ary
 *
 *  Appends the elements of +other_ary+s to +self+.
 *
 *     [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ]
 *     [ "a" ].concat( ["b"], ["c", "d"] ) #=> [ "a", "b", "c", "d" ]
 *     [ "a" ].concat #=> [ "a" ]
 *
 *     a = [ 1, 2, 3 ]
 *     a.concat( [ 4, 5 ] )
 *     a                                 #=> [ 1, 2, 3, 4, 5 ]
 *
 *     a = [ 1, 2 ]
 *     a.concat(a, a)                    #=> [1, 2, 1, 2, 1, 2]
 *
 *  See also Array#+.
 */

static VALUE
rb_ary_concat_multi(int argc, VALUE *argv, VALUE ary)
{
    rb_ary_modify_check(ary);

    if (argc == 1) {
	rb_ary_concat(ary, argv[0]);
    }
    else if (argc > 1) {
	int i;
	VALUE args = rb_ary_tmp_new(argc);
	for (i = 0; i < argc; i++) {
	    rb_ary_concat(args, argv[i]);
	}
	ary_append(ary, args);
    }

    return ary;
}

VALUE
rb_ary_concat(VALUE x, VALUE y)
{
    return ary_append(x, to_ary(y));
}

/*
 *  call-seq:
 *     ary * int     -> new_ary
 *     ary * str     -> new_string
 *
 *  Repetition --- With a String argument, equivalent to
 *  ary.join(str).
 *
 *  Otherwise, returns a new array built by concatenating the +int+ copies of
 *  +self+.
 *
 *
 *     [ 1, 2, 3 ] * 3    #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
 *     [ 1, 2, 3 ] * ","  #=> "1,2,3"
 *
 */

static VALUE
rb_ary_times(VALUE ary, VALUE times)
{
    VALUE ary2, tmp;
    const VALUE *ptr;
    long t, len;

    tmp = rb_check_string_type(times);
    if (!NIL_P(tmp)) {
	return rb_ary_join(ary, tmp);
    }

    len = NUM2LONG(times);
    if (len == 0) {
	ary2 = ary_new(rb_obj_class(ary), 0);
	goto out;
    }
    if (len < 0) {
	rb_raise(rb_eArgError, "negative argument");
    }
    if (ARY_MAX_SIZE/len < RARRAY_LEN(ary)) {
	rb_raise(rb_eArgError, "argument too big");
    }
    len *= RARRAY_LEN(ary);

    ary2 = ary_new(rb_obj_class(ary), len);
    ARY_SET_LEN(ary2, len);

    ptr = RARRAY_CONST_PTR(ary);
    t = RARRAY_LEN(ary);
    if (0 < t) {
	ary_memcpy(ary2, 0, t, ptr);
	while (t <= len/2) {
	    ary_memcpy(ary2, t, t, RARRAY_CONST_PTR(ary2));
            t *= 2;
        }
        if (t < len) {
	    ary_memcpy(ary2, t, len-t, RARRAY_CONST_PTR(ary2));
        }
    }
  out:
    OBJ_INFECT(ary2, ary);

    return ary2;
}

/*
 *  call-seq:
 *     ary.assoc(obj)   -> element_ary  or  nil
 *
 *  Searches through an array whose elements are also arrays comparing +obj+
 *  with the first element of each contained array using obj.==.
 *
 *  Returns the first contained array that matches (that is, the first
 *  associated array), or +nil+ if no match is found.
 *
 *  See also Array#rassoc
 *
 *     s1 = [ "colors", "red", "blue", "green" ]
 *     s2 = [ "letters", "a", "b", "c" ]
 *     s3 = "foo"
 *     a  = [ s1, s2, s3 ]
 *     a.assoc("letters")  #=> [ "letters", "a", "b", "c" ]
 *     a.assoc("foo")      #=> nil
 */

VALUE
rb_ary_assoc(VALUE ary, VALUE key)
{
    long i;
    VALUE v;

    for (i = 0; i < RARRAY_LEN(ary); ++i) {
	v = rb_check_array_type(RARRAY_AREF(ary, i));
	if (!NIL_P(v) && RARRAY_LEN(v) > 0 &&
	    rb_equal(RARRAY_AREF(v, 0), key))
	    return v;
    }
    return Qnil;
}

/*
 *  call-seq:
 *     ary.rassoc(obj) -> element_ary or nil
 *
 *  Searches through the array whose elements are also arrays.
 *
 *  Compares +obj+ with the second element of each contained array using
 *  obj.==.
 *
 *  Returns the first contained array that matches +obj+.
 *
 *  See also Array#assoc.
 *
 *     a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ]
 *     a.rassoc("two")    #=> [2, "two"]
 *     a.rassoc("four")   #=> nil
 */

VALUE
rb_ary_rassoc(VALUE ary, VALUE value)
{
    long i;
    VALUE v;

    for (i = 0; i < RARRAY_LEN(ary); ++i) {
	v = RARRAY_AREF(ary, i);
	if (RB_TYPE_P(v, T_ARRAY) &&
	    RARRAY_LEN(v) > 1 &&
	    rb_equal(RARRAY_AREF(v, 1), value))
	    return v;
    }
    return Qnil;
}

static VALUE
recursive_equal(VALUE ary1, VALUE ary2, int recur)
{
    long i, len1;
    const VALUE *p1, *p2;

    if (recur) return Qtrue; /* Subtle! */

    p1 = RARRAY_CONST_PTR(ary1);
    p2 = RARRAY_CONST_PTR(ary2);
    len1 = RARRAY_LEN(ary1);

    for (i = 0; i < len1; i++) {
	if (*p1 != *p2) {
	    if (rb_equal(*p1, *p2)) {
		len1 = RARRAY_LEN(ary1);
		if (len1 != RARRAY_LEN(ary2))
		    return Qfalse;
		if (len1 < i)
		    return Qtrue;
		p1 = RARRAY_CONST_PTR(ary1) + i;
		p2 = RARRAY_CONST_PTR(ary2) + i;
	    }
	    else {
		return Qfalse;
	    }
	}
	p1++;
	p2++;
    }
    return Qtrue;
}

/*
 *  call-seq:
 *     ary == other_ary   ->   bool
 *
 *  Equality --- Two arrays are equal if they contain the same number of
 *  elements and if each element is equal to (according to Object#==) the
 *  corresponding element in +other_ary+.
 *
 *     [ "a", "c" ]    == [ "a", "c", 7 ]     #=> false
 *     [ "a", "c", 7 ] == [ "a", "c", 7 ]     #=> true
 *     [ "a", "c", 7 ] == [ "a", "d", "f" ]   #=> false
 *
 */

static VALUE
rb_ary_equal(VALUE ary1, VALUE ary2)
{
    if (ary1 == ary2) return Qtrue;
    if (!RB_TYPE_P(ary2, T_ARRAY)) {
	if (!rb_respond_to(ary2, idTo_ary)) {
	    return Qfalse;
	}
	return rb_equal(ary2, ary1);
    }
    if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
    if (RARRAY_CONST_PTR(ary1) == RARRAY_CONST_PTR(ary2)) return Qtrue;
    return rb_exec_recursive_paired(recursive_equal, ary1, ary2, ary2);
}

static VALUE
recursive_eql(VALUE ary1, VALUE ary2, int recur)
{
    long i;

    if (recur) return Qtrue; /* Subtle! */
    for (i=0; i true or false
 *
 *  Returns +true+ if +self+ and +other+ are the same object,
 *  or are both arrays with the same content (according to Object#eql?).
 */

static VALUE
rb_ary_eql(VALUE ary1, VALUE ary2)
{
    if (ary1 == ary2) return Qtrue;
    if (!RB_TYPE_P(ary2, T_ARRAY)) return Qfalse;
    if (RARRAY_LEN(ary1) != RARRAY_LEN(ary2)) return Qfalse;
    if (RARRAY_CONST_PTR(ary1) == RARRAY_CONST_PTR(ary2)) return Qtrue;
    return rb_exec_recursive_paired(recursive_eql, ary1, ary2, ary2);
}

/*
 *  call-seq:
 *     ary.hash   -> integer
 *
 *  Compute a hash-code for this array.
 *
 *  Two arrays with the same content will have the same hash code (and will
 *  compare using #eql?).
 *
 *  See also Object#hash.
 */

static VALUE
rb_ary_hash(VALUE ary)
{
    long i;
    st_index_t h;
    VALUE n;

    h = rb_hash_start(RARRAY_LEN(ary));
    h = rb_hash_uint(h, (st_index_t)rb_ary_hash);
    for (i=0; i true or false
 *
 *  Returns +true+ if the given +object+ is present in +self+ (that is, if any
 *  element == +object+), otherwise returns +false+.
 *
 *     a = [ "a", "b", "c" ]
 *     a.include?("b")   #=> true
 *     a.include?("z")   #=> false
 */

VALUE
rb_ary_includes(VALUE ary, VALUE item)
{
    long i;
    VALUE e;

    for (i=0; i RARRAY_LEN(ary2)) {
	len = RARRAY_LEN(ary2);
    }
    for (i=0; i other_ary   ->  -1, 0, +1 or nil
 *
 *  Comparison --- Returns an integer (+-1+, +0+, or +1) if this
 *  array is less than, equal to, or greater than +other_ary+.
 *
 *  Each object in each array is compared (using the <=> operator).
 *
 *  Arrays are compared in an "element-wise" manner; the first element of +ary+
 *  is compared with the first one of +other_ary+ using the <=> operator, then
 *  each of the second elements, etc...
 *  As soon as the result of any such comparison is non zero (i.e. the two
 *  corresponding elements are not equal), that result is returned for the
 *  whole array comparison.
 *
 *  If all the elements are equal, then the result is based on a comparison of
 *  the array lengths. Thus, two arrays are "equal" according to Array#<=> if,
 *  and only if, they have the same length and the value of each element is
 *  equal to the value of the corresponding element in the other array.
 *
 *  +nil+ is returned if the +other_ary+ is not an array or if the comparison
 *  of two elements returned +nil+.
 *
 *     [ "a", "a", "c" ]    <=> [ "a", "b", "c" ]   #=> -1
 *     [ 1, 2, 3, 4, 5, 6 ] <=> [ 1, 2 ]            #=> +1
 *     [ 1, 2 ]             <=> [ 1, :two ]         #=> nil
 *
 */

VALUE
rb_ary_cmp(VALUE ary1, VALUE ary2)
{
    long len;
    VALUE v;

    ary2 = rb_check_array_type(ary2);
    if (NIL_P(ary2)) return Qnil;
    if (ary1 == ary2) return INT2FIX(0);
    v = rb_exec_recursive_paired(recursive_cmp, ary1, ary2, ary2);
    if (v != Qundef) return v;
    len = RARRAY_LEN(ary1) - RARRAY_LEN(ary2);
    if (len == 0) return INT2FIX(0);
    if (len > 0) return INT2FIX(1);
    return INT2FIX(-1);
}

static VALUE
ary_add_hash(VALUE hash, VALUE ary)
{
    long i;

    for (i=0; intbl) {
	st_table *tbl = RHASH(hash)->ntbl;
	st_free_table(tbl);
    }
    rb_gc_force_recycle(hash);
}

/*
 *  call-seq:
 *     ary - other_ary    -> new_ary
 *
 *  Array Difference
 *
 *  Returns a new array that is a copy of the original array, removing any
 *  items that also appear in +other_ary+. The order is preserved from the
 *  original array.
 *
 *  It compares elements using their #hash and #eql? methods for efficiency.
 *
 *     [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ]  #=>  [ 3, 3, 5 ]
 *
 *  If you need set-like behavior, see the library class Set.
 */

static VALUE
rb_ary_diff(VALUE ary1, VALUE ary2)
{
    VALUE ary3;
    VALUE hash;
    long i;

    hash = ary_make_hash(to_ary(ary2));
    ary3 = rb_ary_new();

    for (i=0; i new_ary
 *
 *  Set Intersection --- Returns a new array containing unique elements common to the
 *  two arrays. The order is preserved from the original array.
 *
 *  It compares elements using their #hash and #eql? methods for efficiency.
 *
 *     [ 1, 1, 3, 5 ] & [ 3, 2, 1 ]                 #=> [ 1, 3 ]
 *     [ 'a', 'b', 'b', 'z' ] & [ 'a', 'b', 'c' ]   #=> [ 'a', 'b' ]
 *
 *  See also Array#uniq.
 */


static VALUE
rb_ary_and(VALUE ary1, VALUE ary2)
{
    VALUE hash, ary3, v;
    st_table *table;
    st_data_t vv;
    long i;

    ary2 = to_ary(ary2);
    ary3 = rb_ary_new();
    if (RARRAY_LEN(ary2) == 0) return ary3;
    hash = ary_make_hash(ary2);
    table = rb_hash_tbl_raw(hash);

    for (i=0; i new_ary
 *
 *  Set Union --- Returns a new array by joining +ary+ with +other_ary+,
 *  excluding any duplicates and preserving the order from the given arrays.
 *
 *  It compares elements using their #hash and #eql? methods for efficiency.
 *
 *     [ "a", "b", "c" ] | [ "c", "d", "a" ]    #=> [ "a", "b", "c", "d" ]
 *     [ "c", "d", "a" ] | [ "a", "b", "c" ]    #=> [ "c", "d", "a", "b" ]
 *
 *  See also Array#uniq.
 */

static VALUE
rb_ary_or(VALUE ary1, VALUE ary2)
{
    VALUE hash, ary3;
    long i;

    ary2 = to_ary(ary2);
    hash = ary_make_hash(ary1);

    for (i=0; i obj
 *     ary.max { |a, b| block }    -> obj
 *     ary.max(n)                  -> array
 *     ary.max(n) { |a, b| block } -> array
 *
 *  Returns the object in _ary_ with the maximum value. The
 *  first form assumes all objects implement Comparable;
 *  the second uses the block to return a <=> b.
 *
 *     a = %w(albatross dog horse)
 *     a.max                                   #=> "horse"
 *     a.max { |a, b| a.length <=> b.length }  #=> "albatross"
 *
 *  If the +n+ argument is given, maximum +n+ elements are returned
 *  as an array.
 *
 *     a = %w[albatross dog horse]
 *     a.max(2)                                  #=> ["horse", "dog"]
 *     a.max(2) {|a, b| a.length <=> b.length }  #=> ["albatross", "horse"]
 */
static VALUE
rb_ary_max(int argc, VALUE *argv, VALUE ary)
{
    struct cmp_opt_data cmp_opt = { 0, 0 };
    VALUE result = Qundef, v;
    VALUE num;
    long i;

    rb_scan_args(argc, argv, "01", &num);

    if (!NIL_P(num))
       return rb_nmin_run(ary, num, 0, 1, 1);

    if (rb_block_given_p()) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) > 0) {
	       result = v;
	   }
	}
    }
    else {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) > 0) {
	       result = v;
	   }
	}
    }
    if (result == Qundef) return Qnil;
    return result;
}

/*
 *  call-seq:
 *     ary.min                     -> obj
 *     ary.min {| a,b | block }    -> obj
 *     ary.min(n)                  -> array
 *     ary.min(n) {| a,b | block } -> array
 *
 *  Returns the object in _ary_ with the minimum value. The
 *  first form assumes all objects implement Comparable;
 *  the second uses the block to return a <=> b.
 *
 *     a = %w(albatross dog horse)
 *     a.min                                   #=> "albatross"
 *     a.min { |a, b| a.length <=> b.length }  #=> "dog"
 *
 *  If the +n+ argument is given, minimum +n+ elements are returned
 *  as an array.
 *
 *     a = %w[albatross dog horse]
 *     a.min(2)                                  #=> ["albatross", "dog"]
 *     a.min(2) {|a, b| a.length <=> b.length }  #=> ["dog", "horse"]
 */
static VALUE
rb_ary_min(int argc, VALUE *argv, VALUE ary)
{
    struct cmp_opt_data cmp_opt = { 0, 0 };
    VALUE result = Qundef, v;
    VALUE num;
    long i;

    rb_scan_args(argc, argv, "01", &num);

    if (!NIL_P(num))
       return rb_nmin_run(ary, num, 0, 0, 1);

    if (rb_block_given_p()) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || rb_cmpint(rb_yield_values(2, v, result), v, result) < 0) {
	       result = v;
	   }
	}
    }
    else {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	   v = RARRAY_AREF(ary, i);
	   if (result == Qundef || OPTIMIZED_CMP(v, result, cmp_opt) < 0) {
	       result = v;
	   }
	}
    }
    if (result == Qundef) return Qnil;
    return result;
}

static int
push_value(st_data_t key, st_data_t val, st_data_t ary)
{
    rb_ary_push((VALUE)ary, (VALUE)val);
    return ST_CONTINUE;
}

/*
 *  call-seq:
 *     ary.uniq!                -> ary or nil
 *     ary.uniq! { |item| ... } -> ary or nil
 *
 *  Removes duplicate elements from +self+.
 *
 *  If a block is given, it will use the return value of the block for
 *  comparison.
 *
 *  It compares values using their #hash and #eql? methods for efficiency.
 *
 *  +self+ is traversed in order, and the first occurrence is kept.
 *
 *  Returns +nil+ if no changes are made (that is, no duplicates are found).
 *
 *     a = [ "a", "a", "b", "b", "c" ]
 *     a.uniq!   # => ["a", "b", "c"]
 *
 *     b = [ "a", "b", "c" ]
 *     b.uniq!   # => nil
 *
 *     c = [["student","sam"], ["student","george"], ["teacher","matz"]]
 *     c.uniq! { |s| s.first } # => [["student", "sam"], ["teacher", "matz"]]
 *
 */

static VALUE
rb_ary_uniq_bang(VALUE ary)
{
    VALUE hash;
    long hash_size;

    rb_ary_modify_check(ary);
    if (RARRAY_LEN(ary) <= 1)
        return Qnil;
    if (rb_block_given_p())
	hash = ary_make_hash_by(ary);
    else
	hash = ary_make_hash(ary);

    hash_size = RHASH_SIZE(hash);
    if (RARRAY_LEN(ary) == hash_size) {
	return Qnil;
    }
    rb_ary_modify_check(ary);
    ARY_SET_LEN(ary, 0);
    if (ARY_SHARED_P(ary) && !ARY_EMBED_P(ary)) {
	rb_ary_unshare(ary);
	FL_SET_EMBED(ary);
    }
    ary_resize_capa(ary, hash_size);
    st_foreach(rb_hash_tbl_raw(hash), push_value, ary);
    ary_recycle_hash(hash);

    return ary;
}

/*
 *  call-seq:
 *     ary.uniq                -> new_ary
 *     ary.uniq { |item| ... } -> new_ary
 *
 *  Returns a new array by removing duplicate values in +self+.
 *
 *  If a block is given, it will use the return value of the block for comparison.
 *
 *  It compares values using their #hash and #eql? methods for efficiency.
 *
 *  +self+ is traversed in order, and the first occurrence is kept.
 *
 *     a = [ "a", "a", "b", "b", "c" ]
 *     a.uniq   # => ["a", "b", "c"]
 *
 *     b = [["student","sam"], ["student","george"], ["teacher","matz"]]
 *     b.uniq { |s| s.first } # => [["student", "sam"], ["teacher", "matz"]]
 *
 */

static VALUE
rb_ary_uniq(VALUE ary)
{
    VALUE hash, uniq;

    if (RARRAY_LEN(ary) <= 1)
        return rb_ary_dup(ary);
    if (rb_block_given_p()) {
	hash = ary_make_hash_by(ary);
	uniq = rb_hash_values(hash);
    }
    else {
	hash = ary_make_hash(ary);
	uniq = rb_hash_values(hash);
    }
    RBASIC_SET_CLASS(uniq, rb_obj_class(ary));
    ary_recycle_hash(hash);

    return uniq;
}

/*
 *  call-seq:
 *     ary.compact!    -> ary  or  nil
 *
 *  Removes +nil+ elements from the array.
 *
 *  Returns +nil+ if no changes were made, otherwise returns the array.
 *
 *     [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
 *     [ "a", "b", "c" ].compact!           #=> nil
 */

static VALUE
rb_ary_compact_bang(VALUE ary)
{
    VALUE *p, *t, *end;
    long n;

    rb_ary_modify(ary);
    p = t = (VALUE *)RARRAY_CONST_PTR(ary); /* WB: no new reference */
    end = p + RARRAY_LEN(ary);

    while (t < end) {
	if (NIL_P(*t)) t++;
	else *p++ = *t++;
    }
    n = p - RARRAY_CONST_PTR(ary);
    if (RARRAY_LEN(ary) == n) {
	return Qnil;
    }
    ary_resize_smaller(ary, n);

    return ary;
}

/*
 *  call-seq:
 *     ary.compact     -> new_ary
 *
 *  Returns a copy of +self+ with all +nil+ elements removed.
 *
 *     [ "a", nil, "b", nil, "c", nil ].compact
 *                       #=> [ "a", "b", "c" ]
 */

static VALUE
rb_ary_compact(VALUE ary)
{
    ary = rb_ary_dup(ary);
    rb_ary_compact_bang(ary);
    return ary;
}

/*
 *  call-seq:
 *     ary.count                   -> int
 *     ary.count(obj)              -> int
 *     ary.count { |item| block }  -> int
 *
 *  Returns the number of elements.
 *
 *  If an argument is given, counts the number of elements which equal +obj+
 *  using ==.
 *
 *  If a block is given, counts the number of elements for which the block
 *  returns a true value.
 *
 *     ary = [1, 2, 4, 2]
 *     ary.count                  #=> 4
 *     ary.count(2)               #=> 2
 *     ary.count { |x| x%2 == 0 } #=> 3
 *
 */

static VALUE
rb_ary_count(int argc, VALUE *argv, VALUE ary)
{
    long i, n = 0;

    if (argc == 0) {
	VALUE v;

	if (!rb_block_given_p())
	    return LONG2NUM(RARRAY_LEN(ary));

	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    v = RARRAY_AREF(ary, i);
	    if (RTEST(rb_yield(v))) n++;
	}
    }
    else {
	VALUE obj;

	rb_scan_args(argc, argv, "1", &obj);
	if (rb_block_given_p()) {
	    rb_warn("given block not used");
	}
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    if (rb_equal(RARRAY_AREF(ary, i), obj)) n++;
	}
    }

    return LONG2NUM(n);
}

static VALUE
flatten(VALUE ary, int level, int *modified)
{
    long i = 0;
    VALUE stack, result, tmp, elt;
    st_table *memo;
    st_data_t id;

    stack = ary_new(0, ARY_DEFAULT_SIZE);
    result = ary_new(0, RARRAY_LEN(ary));
    memo = st_init_numtable();
    st_insert(memo, (st_data_t)ary, (st_data_t)Qtrue);
    *modified = 0;

    while (1) {
	while (i < RARRAY_LEN(ary)) {
	    elt = RARRAY_AREF(ary, i++);
	    if (level >= 0 && RARRAY_LEN(stack) / 2 >= level) {
		rb_ary_push(result, elt);
		continue;
	    }
	    tmp = rb_check_array_type(elt);
	    if (RBASIC(result)->klass) {
		rb_raise(rb_eRuntimeError, "flatten reentered");
	    }
	    if (NIL_P(tmp)) {
		rb_ary_push(result, elt);
	    }
	    else {
		*modified = 1;
		id = (st_data_t)tmp;
		if (st_lookup(memo, id, 0)) {
		    st_free_table(memo);
		    rb_raise(rb_eArgError, "tried to flatten recursive array");
		}
		st_insert(memo, id, (st_data_t)Qtrue);
		rb_ary_push(stack, ary);
		rb_ary_push(stack, LONG2NUM(i));
		ary = tmp;
		i = 0;
	    }
	}
	if (RARRAY_LEN(stack) == 0) {
	    break;
	}
	id = (st_data_t)ary;
	st_delete(memo, &id, 0);
	tmp = rb_ary_pop(stack);
	i = NUM2LONG(tmp);
	ary = rb_ary_pop(stack);
    }

    st_free_table(memo);

    RBASIC_SET_CLASS(result, rb_obj_class(ary));
    return result;
}

/*
 *  call-seq:
 *     ary.flatten!        -> ary or nil
 *     ary.flatten!(level) -> ary or nil
 *
 *  Flattens +self+ in place.
 *
 *  Returns +nil+ if no modifications were made (i.e., the array contains no
 *  subarrays.)
 *
 *  The optional +level+ argument determines the level of recursion to flatten.
 *
 *     a = [ 1, 2, [3, [4, 5] ] ]
 *     a.flatten!   #=> [1, 2, 3, 4, 5]
 *     a.flatten!   #=> nil
 *     a            #=> [1, 2, 3, 4, 5]
 *     a = [ 1, 2, [3, [4, 5] ] ]
 *     a.flatten!(1) #=> [1, 2, 3, [4, 5]]
 */

static VALUE
rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary)
{
    int mod = 0, level = -1;
    VALUE result, lv;

    rb_scan_args(argc, argv, "01", &lv);
    rb_ary_modify_check(ary);
    if (!NIL_P(lv)) level = NUM2INT(lv);
    if (level == 0) return Qnil;

    result = flatten(ary, level, &mod);
    if (mod == 0) {
	ary_discard(result);
	return Qnil;
    }
    if (!(mod = ARY_EMBED_P(result))) rb_obj_freeze(result);
    rb_ary_replace(ary, result);
    if (mod) ARY_SET_EMBED_LEN(result, 0);

    return ary;
}

/*
 *  call-seq:
 *     ary.flatten -> new_ary
 *     ary.flatten(level) -> new_ary
 *
 *  Returns a new array that is a one-dimensional flattening of +self+
 *  (recursively).
 *
 *  That is, for every element that is an array, extract its elements into
 *  the new array.
 *
 *  The optional +level+ argument determines the level of recursion to
 *  flatten.
 *
 *     s = [ 1, 2, 3 ]           #=> [1, 2, 3]
 *     t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
 *     a = [ s, t, 9, 10 ]       #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
 *     a.flatten                 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 *     a = [ 1, 2, [3, [4, 5] ] ]
 *     a.flatten(1)              #=> [1, 2, 3, [4, 5]]
 */

static VALUE
rb_ary_flatten(int argc, VALUE *argv, VALUE ary)
{
    int mod = 0, level = -1;
    VALUE result, lv;

    rb_scan_args(argc, argv, "01", &lv);
    if (!NIL_P(lv)) level = NUM2INT(lv);
    if (level == 0) return ary_make_shared_copy(ary);

    result = flatten(ary, level, &mod);
    OBJ_INFECT(result, ary);

    return result;
}

#define OPTHASH_GIVEN_P(opts) \
    (argc > 0 && !NIL_P((opts) = rb_check_hash_type(argv[argc-1])) && (--argc, 1))
static ID id_random;

#define RAND_UPTO(max) (long)rb_random_ulong_limited((randgen), (max)-1)

/*
 *  call-seq:
 *     ary.shuffle!              -> ary
 *     ary.shuffle!(random: rng) -> ary
 *
 *  Shuffles elements in +self+ in place.
 *
 *     a = [ 1, 2, 3 ]           #=> [1, 2, 3]
 *     a.shuffle!                #=> [2, 3, 1]
 *     a                         #=> [2, 3, 1]
 *
 *  The optional +rng+ argument will be used as the random number generator.
 *
 *     a.shuffle!(random: Random.new(1))  #=> [1, 3, 2]
 */

static VALUE
rb_ary_shuffle_bang(int argc, VALUE *argv, VALUE ary)
{
    VALUE opts, randgen = rb_cRandom;
    long i, len;

    if (OPTHASH_GIVEN_P(opts)) {
	VALUE rnd;
	ID keyword_ids[1];

	keyword_ids[0] = id_random;
	rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd);
	if (rnd != Qundef) {
	    randgen = rnd;
	}
    }
    rb_check_arity(argc, 0, 0);
    rb_ary_modify(ary);
    i = len = RARRAY_LEN(ary);
    RARRAY_PTR_USE(ary, ptr, {
	while (i) {
	    long j = RAND_UPTO(i);
	    VALUE tmp;
	    if (len != RARRAY_LEN(ary) || ptr != RARRAY_CONST_PTR(ary)) {
		rb_raise(rb_eRuntimeError, "modified during shuffle");
	    }
	    tmp = ptr[--i];
	    ptr[i] = ptr[j];
	    ptr[j] = tmp;
	}
    }); /* WB: no new reference */
    return ary;
}


/*
 *  call-seq:
 *     ary.shuffle              -> new_ary
 *     ary.shuffle(random: rng) -> new_ary
 *
 *  Returns a new array with elements of +self+ shuffled.
 *
 *     a = [ 1, 2, 3 ]           #=> [1, 2, 3]
 *     a.shuffle                 #=> [2, 3, 1]
 *     a                         #=> [1, 2, 3]
 *
 *  The optional +rng+ argument will be used as the random number generator.
 *
 *     a.shuffle(random: Random.new(1))  #=> [1, 3, 2]
 */

static VALUE
rb_ary_shuffle(int argc, VALUE *argv, VALUE ary)
{
    ary = rb_ary_dup(ary);
    rb_ary_shuffle_bang(argc, argv, ary);
    return ary;
}


/*
 *  call-seq:
 *     ary.sample                  -> obj
 *     ary.sample(random: rng)     -> obj
 *     ary.sample(n)               -> new_ary
 *     ary.sample(n, random: rng)  -> new_ary
 *
 *  Choose a random element or +n+ random elements from the array.
 *
 *  The elements are chosen by using random and unique indices into the array
 *  in order to ensure that an element doesn't repeat itself unless the array
 *  already contained duplicate elements.
 *
 *  If the array is empty the first form returns +nil+ and the second form
 *  returns an empty array.
 *
 *  The optional +rng+ argument will be used as the random number generator.
 *
 *     a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
 *     a.sample         #=> 7
 *     a.sample(4)      #=> [6, 4, 2, 5]
 */


static VALUE
rb_ary_sample(int argc, VALUE *argv, VALUE ary)
{
    VALUE nv, result;
    VALUE opts, randgen = rb_cRandom;
    long n, len, i, j, k, idx[10];
    long rnds[numberof(idx)];
    long memo_threshold;

    if (OPTHASH_GIVEN_P(opts)) {
	VALUE rnd;
	ID keyword_ids[1];

	keyword_ids[0] = id_random;
	rb_get_kwargs(opts, keyword_ids, 0, 1, &rnd);
	if (rnd != Qundef) {
	    randgen = rnd;
	}
    }
    len = RARRAY_LEN(ary);
    if (argc == 0) {
	if (len < 2)
	    i = 0;
	else
	    i = RAND_UPTO(len);

	return rb_ary_elt(ary, i);
    }
    rb_scan_args(argc, argv, "1", &nv);
    n = NUM2LONG(nv);
    if (n < 0) rb_raise(rb_eArgError, "negative sample number");
    if (n > len) n = len;
    if (n <= numberof(idx)) {
	for (i = 0; i < n; ++i) {
	    rnds[i] = RAND_UPTO(len - i);
	}
    }
    k = len;
    len = RARRAY_LEN(ary);
    if (len < k && n <= numberof(idx)) {
	for (i = 0; i < n; ++i) {
	    if (rnds[i] >= len) return rb_ary_new_capa(0);
	}
    }
    if (n > len) n = len;
    switch (n) {
      case 0:
	return rb_ary_new_capa(0);
      case 1:
	i = rnds[0];
	return rb_ary_new_from_values(1, &RARRAY_AREF(ary, i));
      case 2:
	i = rnds[0];
	j = rnds[1];
	if (j >= i) j++;
	return rb_ary_new_from_args(2, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j));
      case 3:
	i = rnds[0];
	j = rnds[1];
	k = rnds[2];
	{
	    long l = j, g = i;
	    if (j >= i) l = i, g = ++j;
	    if (k >= l && (++k >= g)) ++k;
	}
	return rb_ary_new_from_args(3, RARRAY_AREF(ary, i), RARRAY_AREF(ary, j), RARRAY_AREF(ary, k));
    }
    memo_threshold =
	len < 2560 ? len / 128 :
	len < 5120 ? len / 64 :
	len < 10240 ? len / 32 :
	len / 16;
    if (n <= numberof(idx)) {
	long sorted[numberof(idx)];
	sorted[0] = idx[0] = rnds[0];
	for (i=1; i max_idx) max_idx = r;
	    }
	    len = RARRAY_LEN(ary);
	    if (len <= max_idx) n = 0;
	    else if (n > len) n = len;
	    RARRAY_PTR_USE(ary, ptr_ary, {
		for (i=0; i 0)) {
	n = RARRAY_AREF(args, 0);
    }
    if (RARRAY_LEN(self) == 0) return INT2FIX(0);
    if (n == Qnil) return DBL2NUM(INFINITY);
    mul = NUM2LONG(n);
    if (mul <= 0) return INT2FIX(0);
    n = LONG2FIX(mul);
    return rb_funcallv(rb_ary_length(self), '*', 1, &n);
}

/*
 *  call-seq:
 *     ary.cycle(n=nil) { |obj| block }  -> nil
 *     ary.cycle(n=nil)                  -> Enumerator
 *
 *  Calls the given block for each element +n+ times or forever if +nil+ is
 *  given.
 *
 *  Does nothing if a non-positive number is given or the array is empty.
 *
 *  Returns +nil+ if the loop has finished without getting interrupted.
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *     a = ["a", "b", "c"]
 *     a.cycle { |x| puts x }     # print, a, b, c, a, b, c,.. forever.
 *     a.cycle(2) { |x| puts x }  # print, a, b, c, a, b, c.
 *
 */

static VALUE
rb_ary_cycle(int argc, VALUE *argv, VALUE ary)
{
    long n, i;
    VALUE nv = Qnil;

    rb_scan_args(argc, argv, "01", &nv);

    RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_cycle_size);
    if (NIL_P(nv)) {
        n = -1;
    }
    else {
        n = NUM2LONG(nv);
        if (n <= 0) return Qnil;
    }

    while (RARRAY_LEN(ary) > 0 && (n < 0 || 0 < n--)) {
        for (i=0; iklass;
}

/*
 * Compute permutations of +r+ elements of the set [0..n-1].
 *
 * When we have a complete permutation of array indices, copy the values
 * at those indices into a new array and yield that array.
 *
 * n: the size of the set
 * r: the number of elements in each permutation
 * p: the array (of size r) that we're filling in
 * used: an array of booleans: whether a given index is already used
 * values: the Ruby array that holds the actual values to permute
 */
static void
permute0(const long n, const long r, long *const p, char *const used, const VALUE values)
{
    long i = 0, index = 0;

    for (;;) {
	const char *const unused = memchr(&used[i], 0, n-i);
	if (!unused) {
	    if (!index) break;
	    i = p[--index];                /* pop index */
	    used[i++] = 0;                 /* index unused */
	}
	else {
	    i = unused - used;
	    p[index] = i;
	    used[i] = 1;                   /* mark index used */
	    ++index;
	    if (index < r-1) {             /* if not done yet */
		p[index] = i = 0;
		continue;
	    }
	    for (i = 0; i < n; ++i) {
		if (used[i]) continue;
		p[index] = i;
		if (!yield_indexed_values(values, r, p)) {
		    rb_raise(rb_eRuntimeError, "permute reentered");
		}
	    }
	    i = p[--index];                /* pop index */
	    used[i] = 0;                   /* index unused */
	    p[index] = ++i;
	}
    }
}

/*
 * Returns the product of from, from-1, ..., from - how_many + 1.
 * http://en.wikipedia.org/wiki/Pochhammer_symbol
 */
static VALUE
descending_factorial(long from, long how_many)
{
    VALUE cnt = LONG2FIX(how_many >= 0);
    while (how_many-- > 0) {
	VALUE v = LONG2FIX(from--);
	cnt = rb_funcallv(cnt, '*', 1, &v);
    }
    return cnt;
}

static VALUE
binomial_coefficient(long comb, long size)
{
    VALUE r, v;
    if (comb > size-comb) {
	comb = size-comb;
    }
    if (comb < 0) {
	return LONG2FIX(0);
    }
    r = descending_factorial(size, comb);
    v = descending_factorial(comb, comb);
    return rb_funcallv(r, id_div, 1, &v);
}

static VALUE
rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj)
{
    long n = RARRAY_LEN(ary);
    long k = (args && (RARRAY_LEN(args) > 0)) ? NUM2LONG(RARRAY_AREF(args, 0)) : n;

    return descending_factorial(n, k);
}

/*
 *  call-seq:
 *     ary.permutation { |p| block }          -> ary
 *     ary.permutation                        -> Enumerator
 *     ary.permutation(n) { |p| block }       -> ary
 *     ary.permutation(n)                     -> Enumerator
 *
 * When invoked with a block, yield all permutations of length +n+ of the
 * elements of the array, then return the array itself.
 *
 * If +n+ is not specified, yield all permutations of all elements.
 *
 * The implementation makes no guarantees about the order in which the
 * permutations are yielded.
 *
 * If no block is given, an Enumerator is returned instead.
 *
 * Examples:
 *
 *   a = [1, 2, 3]
 *   a.permutation.to_a    #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
 *   a.permutation(1).to_a #=> [[1],[2],[3]]
 *   a.permutation(2).to_a #=> [[1,2],[1,3],[2,1],[2,3],[3,1],[3,2]]
 *   a.permutation(3).to_a #=> [[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]
 *   a.permutation(0).to_a #=> [[]] # one permutation of length 0
 *   a.permutation(4).to_a #=> []   # no permutations of length 4
 */

static VALUE
rb_ary_permutation(int argc, VALUE *argv, VALUE ary)
{
    VALUE num;
    long r, n, i;

    n = RARRAY_LEN(ary);                  /* Array length */
    RETURN_SIZED_ENUMERATOR(ary, argc, argv, rb_ary_permutation_size);   /* Return enumerator if no block */
    rb_scan_args(argc, argv, "01", &num);
    r = NIL_P(num) ? n : NUM2LONG(num);   /* Permutation size from argument */

    if (r < 0 || n < r) {
	/* no permutations: yield nothing */
    }
    else if (r == 0) { /* exactly one permutation: the zero-length array */
	rb_yield(rb_ary_new2(0));
    }
    else if (r == 1) { /* this is a special, easy case */
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else {             /* this is the general case */
	volatile VALUE t0;
	long *p = ALLOCV_N(long, t0, r+roomof(n, sizeof(long)));
	char *used = (char*)(p + r);
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	RBASIC_CLEAR_CLASS(ary0);

	MEMZERO(used, char, n); /* initialize array */

	permute0(n, r, p, used, ary0); /* compute and yield permutations */
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

static void
combinate0(const long len, const long n, long *const stack, const VALUE values)
{
    long lev = 0;

    MEMZERO(stack+1, long, n);
    stack[0] = -1;
    for (;;) {
	for (lev++; lev < n; lev++) {
	    stack[lev+1] = stack[lev]+1;
	}
	if (!yield_indexed_values(values, n, stack+1)) {
	    rb_raise(rb_eRuntimeError, "combination reentered");
	}
	do {
	    if (lev == 0) return;
	    stack[lev--]++;
	} while (stack[lev+1]+n == len+lev+1);
    }
}

static VALUE
rb_ary_combination_size(VALUE ary, VALUE args, VALUE eobj)
{
    long n = RARRAY_LEN(ary);
    long k = NUM2LONG(RARRAY_AREF(args, 0));

    return binomial_coefficient(k, n);
}

/*
 *  call-seq:
 *     ary.combination(n) { |c| block }    -> ary
 *     ary.combination(n)                  -> Enumerator
 *
 * When invoked with a block, yields all combinations of length +n+ of elements
 * from the array and then returns the array itself.
 *
 * The implementation makes no guarantees about the order in which the
 * combinations are yielded.
 *
 * If no block is given, an Enumerator is returned instead.
 *
 * Examples:
 *
 *     a = [1, 2, 3, 4]
 *     a.combination(1).to_a  #=> [[1],[2],[3],[4]]
 *     a.combination(2).to_a  #=> [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
 *     a.combination(3).to_a  #=> [[1,2,3],[1,2,4],[1,3,4],[2,3,4]]
 *     a.combination(4).to_a  #=> [[1,2,3,4]]
 *     a.combination(0).to_a  #=> [[]] # one combination of length 0
 *     a.combination(5).to_a  #=> []   # no combinations of length 5
 *
 */

static VALUE
rb_ary_combination(VALUE ary, VALUE num)
{
    long i, n, len;

    n = NUM2LONG(num);
    RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_combination_size);
    len = RARRAY_LEN(ary);
    if (n < 0 || len < n) {
	/* yield nothing */
    }
    else if (n == 0) {
	rb_yield(rb_ary_new2(0));
    }
    else if (n == 1) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else {
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	volatile VALUE t0;
	long *stack = ALLOCV_N(long, t0, n+1);

	RBASIC_CLEAR_CLASS(ary0);
	combinate0(len, n, stack, ary0);
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

/*
 * Compute repeated permutations of +r+ elements of the set
 * [0..n-1].
 *
 * When we have a complete repeated permutation of array indices, copy the
 * values at those indices into a new array and yield that array.
 *
 * n: the size of the set
 * r: the number of elements in each permutation
 * p: the array (of size r) that we're filling in
 * values: the Ruby array that holds the actual values to permute
 */
static void
rpermute0(const long n, const long r, long *const p, const VALUE values)
{
    long i = 0, index = 0;

    p[index] = i;
    for (;;) {
	if (++index < r-1) {
	    p[index] = i = 0;
	    continue;
	}
	for (i = 0; i < n; ++i) {
	    p[index] = i;
	    if (!yield_indexed_values(values, r, p)) {
		rb_raise(rb_eRuntimeError, "repeated permute reentered");
	    }
	}
	do {
	    if (index <= 0) return;
	} while ((i = ++p[--index]) >= n);
    }
}

static VALUE
rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj)
{
    long n = RARRAY_LEN(ary);
    long k = NUM2LONG(RARRAY_AREF(args, 0));
    VALUE v;

    if (k < 0) {
	return LONG2FIX(0);
    }

    v = LONG2NUM(k);
    return rb_funcallv(LONG2NUM(n), idPow, 1, &v);
}

/*
 *  call-seq:
 *     ary.repeated_permutation(n) { |p| block } -> ary
 *     ary.repeated_permutation(n)               -> Enumerator
 *
 * When invoked with a block, yield all repeated permutations of length +n+ of
 * the elements of the array, then return the array itself.
 *
 * The implementation makes no guarantees about the order in which the repeated
 * permutations are yielded.
 *
 * If no block is given, an Enumerator is returned instead.
 *
 * Examples:
 *
 *     a = [1, 2]
 *     a.repeated_permutation(1).to_a  #=> [[1], [2]]
 *     a.repeated_permutation(2).to_a  #=> [[1,1],[1,2],[2,1],[2,2]]
 *     a.repeated_permutation(3).to_a  #=> [[1,1,1],[1,1,2],[1,2,1],[1,2,2],
 *                                     #    [2,1,1],[2,1,2],[2,2,1],[2,2,2]]
 *     a.repeated_permutation(0).to_a  #=> [[]] # one permutation of length 0
 */

static VALUE
rb_ary_repeated_permutation(VALUE ary, VALUE num)
{
    long r, n, i;

    n = RARRAY_LEN(ary);                  /* Array length */
    RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_permutation_size);      /* Return Enumerator if no block */
    r = NUM2LONG(num);                    /* Permutation size from argument */

    if (r < 0) {
	/* no permutations: yield nothing */
    }
    else if (r == 0) { /* exactly one permutation: the zero-length array */
	rb_yield(rb_ary_new2(0));
    }
    else if (r == 1) { /* this is a special, easy case */
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else {             /* this is the general case */
	volatile VALUE t0;
	long *p = ALLOCV_N(long, t0, r);
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	RBASIC_CLEAR_CLASS(ary0);

	rpermute0(n, r, p, ary0); /* compute and yield repeated permutations */
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

static void
rcombinate0(const long n, const long r, long *const p, const long rest, const VALUE values)
{
    long i = 0, index = 0;

    p[index] = i;
    for (;;) {
	if (++index < r-1) {
	    p[index] = i;
	    continue;
	}
	for (; i < n; ++i) {
	    p[index] = i;
	    if (!yield_indexed_values(values, r, p)) {
		rb_raise(rb_eRuntimeError, "repeated combination reentered");
	    }
	}
	do {
	    if (index <= 0) return;
	} while ((i = ++p[--index]) >= n);
    }
}

static VALUE
rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj)
{
    long n = RARRAY_LEN(ary);
    long k = NUM2LONG(RARRAY_AREF(args, 0));
    if (k == 0) {
	return LONG2FIX(1);
    }
    return binomial_coefficient(k, n + k - 1);
}

/*
 *  call-seq:
 *     ary.repeated_combination(n) { |c| block } -> ary
 *     ary.repeated_combination(n)               -> Enumerator
 *
 * When invoked with a block, yields all repeated combinations of length +n+ of
 * elements from the array and then returns the array itself.
 *
 * The implementation makes no guarantees about the order in which the repeated
 * combinations are yielded.
 *
 * If no block is given, an Enumerator is returned instead.
 *
 * Examples:
 *
 *   a = [1, 2, 3]
 *   a.repeated_combination(1).to_a  #=> [[1], [2], [3]]
 *   a.repeated_combination(2).to_a  #=> [[1,1],[1,2],[1,3],[2,2],[2,3],[3,3]]
 *   a.repeated_combination(3).to_a  #=> [[1,1,1],[1,1,2],[1,1,3],[1,2,2],[1,2,3],
 *                                   #    [1,3,3],[2,2,2],[2,2,3],[2,3,3],[3,3,3]]
 *   a.repeated_combination(4).to_a  #=> [[1,1,1,1],[1,1,1,2],[1,1,1,3],[1,1,2,2],[1,1,2,3],
 *                                   #    [1,1,3,3],[1,2,2,2],[1,2,2,3],[1,2,3,3],[1,3,3,3],
 *                                   #    [2,2,2,2],[2,2,2,3],[2,2,3,3],[2,3,3,3],[3,3,3,3]]
 *   a.repeated_combination(0).to_a  #=> [[]] # one combination of length 0
 *
 */

static VALUE
rb_ary_repeated_combination(VALUE ary, VALUE num)
{
    long n, i, len;

    n = NUM2LONG(num);                 /* Combination size from argument */
    RETURN_SIZED_ENUMERATOR(ary, 1, &num, rb_ary_repeated_combination_size);   /* Return enumerator if no block */
    len = RARRAY_LEN(ary);
    if (n < 0) {
	/* yield nothing */
    }
    else if (n == 0) {
	rb_yield(rb_ary_new2(0));
    }
    else if (n == 1) {
	for (i = 0; i < RARRAY_LEN(ary); i++) {
	    rb_yield(rb_ary_new3(1, RARRAY_AREF(ary, i)));
	}
    }
    else if (len == 0) {
	/* yield nothing */
    }
    else {
	volatile VALUE t0;
	long *p = ALLOCV_N(long, t0, n);
	VALUE ary0 = ary_make_shared_copy(ary); /* private defensive copy of ary */
	RBASIC_CLEAR_CLASS(ary0);

	rcombinate0(len, n, p, n, ary0); /* compute and yield repeated combinations */
	ALLOCV_END(t0);
	RBASIC_SET_CLASS_RAW(ary0, rb_cArray);
    }
    return ary;
}

/*
 *  call-seq:
 *     ary.product(other_ary, ...)                -> new_ary
 *     ary.product(other_ary, ...) { |p| block }  -> ary
 *
 *  Returns an array of all combinations of elements from all arrays.
 *
 *  The length of the returned array is the product of the length of +self+ and
 *  the argument arrays.
 *
 *  If given a block, #product will yield all combinations and return +self+
 *  instead.
 *
 *     [1,2,3].product([4,5])     #=> [[1,4],[1,5],[2,4],[2,5],[3,4],[3,5]]
 *     [1,2].product([1,2])       #=> [[1,1],[1,2],[2,1],[2,2]]
 *     [1,2].product([3,4],[5,6]) #=> [[1,3,5],[1,3,6],[1,4,5],[1,4,6],
 *                                #     [2,3,5],[2,3,6],[2,4,5],[2,4,6]]
 *     [1,2].product()            #=> [[1],[2]]
 *     [1,2].product([])          #=> []
 */

static VALUE
rb_ary_product(int argc, VALUE *argv, VALUE ary)
{
    int n = argc+1;    /* How many arrays we're operating on */
    volatile VALUE t0 = tmpary(n);
    volatile VALUE t1 = tmpbuf(n, sizeof(int));
    VALUE *arrays = RARRAY_PTR(t0); /* The arrays we're computing the product of */
    int *counters = (int*)RSTRING_PTR(t1); /* The current position in each one */
    VALUE result = Qnil;      /* The array we'll be returning, when no block given */
    long i,j;
    long resultlen = 1;

    RBASIC_CLEAR_CLASS(t0);
    RBASIC_CLEAR_CLASS(t1);

    /* initialize the arrays of arrays */
    ARY_SET_LEN(t0, n);
    arrays[0] = ary;
    for (i = 1; i < n; i++) arrays[i] = Qnil;
    for (i = 1; i < n; i++) arrays[i] = to_ary(argv[i-1]);

    /* initialize the counters for the arrays */
    for (i = 0; i < n; i++) counters[i] = 0;

    /* Otherwise, allocate and fill in an array of results */
    if (rb_block_given_p()) {
	/* Make defensive copies of arrays; exit if any is empty */
	for (i = 0; i < n; i++) {
	    if (RARRAY_LEN(arrays[i]) == 0) goto done;
	    arrays[i] = ary_make_shared_copy(arrays[i]);
	}
    }
    else {
	/* Compute the length of the result array; return [] if any is empty */
	for (i = 0; i < n; i++) {
	    long k = RARRAY_LEN(arrays[i]);
	    if (k == 0) {
		result = rb_ary_new2(0);
		goto done;
	    }
            if (MUL_OVERFLOW_LONG_P(resultlen, k))
		rb_raise(rb_eRangeError, "too big to product");
	    resultlen *= k;
	}
	result = rb_ary_new2(resultlen);
    }
    for (;;) {
	int m;
	/* fill in one subarray */
	VALUE subarray = rb_ary_new2(n);
	for (j = 0; j < n; j++) {
	    rb_ary_push(subarray, rb_ary_entry(arrays[j], counters[j]));
	}

	/* put it on the result array */
	if (NIL_P(result)) {
	    FL_SET(t0, FL_USER5);
	    rb_yield(subarray);
	    if (! FL_TEST(t0, FL_USER5)) {
		rb_raise(rb_eRuntimeError, "product reentered");
	    }
	    else {
		FL_UNSET(t0, FL_USER5);
	    }
	}
	else {
	    rb_ary_push(result, subarray);
	}

	/*
	 * Increment the last counter.  If it overflows, reset to 0
	 * and increment the one before it.
	 */
	m = n-1;
	counters[m]++;
	while (counters[m] == RARRAY_LEN(arrays[m])) {
	    counters[m] = 0;
	    /* If the first counter overflows, we are done */
	    if (--m < 0) goto done;
	    counters[m]++;
	}
    }
done:
    tmpary_discard(t0);
    tmpbuf_discard(t1);

    return NIL_P(result) ? ary : result;
}

/*
 *  call-seq:
 *     ary.take(n)               -> new_ary
 *
 *  Returns first +n+ elements from the array.
 *
 *  If a negative number is given, raises an ArgumentError.
 *
 *  See also Array#drop
 *
 *     a = [1, 2, 3, 4, 5, 0]
 *     a.take(3)             #=> [1, 2, 3]
 *
 */

static VALUE
rb_ary_take(VALUE obj, VALUE n)
{
    long len = NUM2LONG(n);
    if (len < 0) {
	rb_raise(rb_eArgError, "attempt to take negative size");
    }
    return rb_ary_subseq(obj, 0, len);
}

/*
 *  call-seq:
 *     ary.take_while { |obj| block }  -> new_ary
 *     ary.take_while                  -> Enumerator
 *
 *  Passes elements to the block until the block returns +nil+ or +false+, then
 *  stops iterating and returns an array of all prior elements.
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *  See also Array#drop_while
 *
 *     a = [1, 2, 3, 4, 5, 0]
 *     a.take_while { |i| i < 3 }  #=> [1, 2]
 *
 */

static VALUE
rb_ary_take_while(VALUE ary)
{
    long i;

    RETURN_ENUMERATOR(ary, 0, 0);
    for (i = 0; i < RARRAY_LEN(ary); i++) {
	if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break;
    }
    return rb_ary_take(ary, LONG2FIX(i));
}

/*
 *  call-seq:
 *     ary.drop(n)               -> new_ary
 *
 *  Drops first +n+ elements from +ary+ and returns the rest of the elements in
 *  an array.
 *
 *  If a negative number is given, raises an ArgumentError.
 *
 *  See also Array#take
 *
 *     a = [1, 2, 3, 4, 5, 0]
 *     a.drop(3)             #=> [4, 5, 0]
 *
 */

static VALUE
rb_ary_drop(VALUE ary, VALUE n)
{
    VALUE result;
    long pos = NUM2LONG(n);
    if (pos < 0) {
	rb_raise(rb_eArgError, "attempt to drop negative size");
    }

    result = rb_ary_subseq(ary, pos, RARRAY_LEN(ary));
    if (result == Qnil) result = rb_ary_new();
    return result;
}

/*
 *  call-seq:
 *     ary.drop_while { |obj| block }   -> new_ary
 *     ary.drop_while                  -> Enumerator
 *
 *  Drops elements up to, but not including, the first element for which the
 *  block returns +nil+ or +false+ and returns an array containing the
 *  remaining elements.
 *
 *  If no block is given, an Enumerator is returned instead.
 *
 *  See also Array#take_while
 *
 *     a = [1, 2, 3, 4, 5, 0]
 *     a.drop_while {|i| i < 3 }   #=> [3, 4, 5, 0]
 *
 */

static VALUE
rb_ary_drop_while(VALUE ary)
{
    long i;

    RETURN_ENUMERATOR(ary, 0, 0);
    for (i = 0; i < RARRAY_LEN(ary); i++) {
	if (!RTEST(rb_yield(RARRAY_AREF(ary, i)))) break;
    }
    return rb_ary_drop(ary, LONG2FIX(i));
}

/*
 *  call-seq:
 *     ary.any? [{ |obj| block }]   -> true or false
 *
 *  See also Enumerable#any?
 */

static VALUE
rb_ary_any_p(VALUE ary)
{
    long i, len = RARRAY_LEN(ary);
    const VALUE *ptr = RARRAY_CONST_PTR(ary);

    if (!len) return Qfalse;
    if (!rb_block_given_p()) {
	for (i = 0; i < len; ++i) if (RTEST(ptr[i])) return Qtrue;
    }
    else {
	for (i = 0; i < RARRAY_LEN(ary); ++i) {
	    if (RTEST(rb_yield(RARRAY_AREF(ary, i)))) return Qtrue;
	}
    }
    return Qfalse;
}

/*
 * call-seq:
 *   ary.dig(idx, ...)                 -> object
 *
 * Extracts the nested value specified by the sequence of idx
 * objects by calling +dig+ at each step, returning +nil+ if any
 * intermediate step is +nil+.
 *
 *   a = [[1, [2, 3]]]
 *
 *   a.dig(0, 1, 1)                    #=> 3
 *   a.dig(1, 2, 3)                    #=> nil
 *   a.dig(0, 0, 0)                    #=> TypeError: Integer does not have #dig method
 *   [42, {foo: :bar}].dig(1, :foo)    #=> :bar
 */

VALUE
rb_ary_dig(int argc, VALUE *argv, VALUE self)
{
    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    self = rb_ary_at(self, *argv);
    if (!--argc) return self;
    ++argv;
    return rb_obj_dig(argc, argv, self, Qnil);
}

static inline VALUE
finish_exact_sum(long n, VALUE r, VALUE v, int z)
{
    if (n != 0)
        v = rb_fix_plus(LONG2FIX(n), v);
    if (r != Qundef) {
	/* r can be an Integer when mathn is loaded */
	if (FIXNUM_P(r))
	    v = rb_fix_plus(r, v);
	else if (RB_TYPE_P(r, T_BIGNUM))
	    v = rb_big_plus(r, v);
	else
	    v = rb_rational_plus(r, v);
    }
    else if (!n && z) {
        v = rb_fix_plus(LONG2FIX(0), v);
    }
    return v;
}

/*
 * call-seq:
 *   ary.sum(init=0)                    -> number
 *   ary.sum(init=0) {|e| expr }        -> number
 *
 * Returns the sum of elements.
 * For example, [e1, e2, e3].sum returns init + e1 + e2 + e3.
 *
 * If a block is given, the block is applied to each element
 * before addition.
 *
 * If ary is empty, it returns init.
 *
 *   [].sum                             #=> 0
 *   [].sum(0.0)                        #=> 0.0
 *   [1, 2, 3].sum                      #=> 6
 *   [3, 5.5].sum                       #=> 8.5
 *   [2.5, 3.0].sum(0.0) {|e| e * e }   #=> 15.25
 *   [Object.new].sum                   #=> TypeError
 *
 * The (arithmetic) mean value of an array can be obtained as follows.
 *
 *   mean = ary.sum(0.0) / ary.length
 *
 * This method can be used for non-numeric objects by
 * explicit init argument.
 *
 *   ["a", "b", "c"].sum("")            #=> "abc"
 *   [[1], [[2]], [3]].sum([])          #=> [1, [2], 3]
 *
 * However, Array#join and Array#flatten is faster than Array#sum for
 * array of strings and array of arrays.
 *
 *   ["a", "b", "c"].join               #=> "abc"
 *   [[1], [[2]], [3]].flatten(1)       #=> [1, [2], 3]
 *
 *
 * Array#sum method may not respect method redefinition of "+" methods
 * such as Integer#+.
 *
 */

static VALUE
rb_ary_sum(int argc, VALUE *argv, VALUE ary)
{
    VALUE e, v, r;
    long i, n;
    int block_given;

    if (rb_scan_args(argc, argv, "01", &v) == 0)
        v = LONG2FIX(0);

    block_given = rb_block_given_p();

    if (RARRAY_LEN(ary) == 0)
        return v;

    n = 0;
    r = Qundef;
    for (i = 0; i < RARRAY_LEN(ary); i++) {
        e = RARRAY_AREF(ary, i);
        if (block_given)
            e = rb_yield(e);
        if (FIXNUM_P(e)) {
            n += FIX2LONG(e); /* should not overflow long type */
            if (!FIXABLE(n)) {
                v = rb_big_plus(LONG2NUM(n), v);
                n = 0;
            }
        }
        else if (RB_TYPE_P(e, T_BIGNUM))
            v = rb_big_plus(e, v);
        else if (RB_TYPE_P(e, T_RATIONAL)) {
            if (r == Qundef)
                r = e;
            else
                r = rb_rational_plus(r, e);
        }
        else
            goto not_exact;
    }
    v = finish_exact_sum(n, r, v, argc!=0);
    return v;

  not_exact:
    v = finish_exact_sum(n, r, v, i!=0);

    if (RB_FLOAT_TYPE_P(e)) {
        /*
         * Kahan-Babuska balancing compensated summation algorithm
         * See http://link.springer.com/article/10.1007/s00607-005-0139-x
         */
        double f, c;

        f = NUM2DBL(v);
        c = 0.0;
        goto has_float_value;
        for (; i < RARRAY_LEN(ary); i++) {
            double x, t;
            e = RARRAY_AREF(ary, i);
            if (block_given)
                e = rb_yield(e);
            if (RB_FLOAT_TYPE_P(e))
              has_float_value:
                x = RFLOAT_VALUE(e);
            else if (FIXNUM_P(e))
                x = FIX2LONG(e);
            else if (RB_TYPE_P(e, T_BIGNUM))
                x = rb_big2dbl(e);
            else if (RB_TYPE_P(e, T_RATIONAL))
                x = rb_num2dbl(e);
            else
                goto not_float;

            t = f + x;
            if (fabs(f) >= fabs(x))
                c += ((f - t) + x);
            else
                c += ((x - t) + f);
            f = t;
        }
        f += c;
        return DBL2NUM(f);

      not_float:
        v = DBL2NUM(f);
    }

    goto has_some_value;
    for (; i < RARRAY_LEN(ary); i++) {
        e = RARRAY_AREF(ary, i);
        if (block_given)
            e = rb_yield(e);
      has_some_value:
        v = rb_funcall(v, idPLUS, 1, e);
    }
    return v;
}

/*
 *  Arrays are ordered, integer-indexed collections of any object.
 *
 *  Array indexing starts at 0, as in C or Java.  A negative index is assumed
 *  to be relative to the end of the array---that is, an index of -1 indicates
 *  the last element of the array, -2 is the next to last element in the
 *  array, and so on.
 *
 *  == Creating Arrays
 *
 *  A new array can be created by using the literal constructor
 *  [].  Arrays can contain different types of objects.  For
 *  example, the array below contains an Integer, a String and a Float:
 *
 *     ary = [1, "two", 3.0] #=> [1, "two", 3.0]
 *
 *  An array can also be created by explicitly calling Array.new with zero, one
 *  (the initial size of the Array) or two arguments (the initial size and a
 *  default object).
 *
 *     ary = Array.new    #=> []
 *     Array.new(3)       #=> [nil, nil, nil]
 *     Array.new(3, true) #=> [true, true, true]
 *
 *  Note that the second argument populates the array with references to the
 *  same object.  Therefore, it is only recommended in cases when you need to
 *  instantiate arrays with natively immutable objects such as Symbols,
 *  numbers, true or false.
 *
 *  To create an array with separate objects a block can be passed instead.
 *  This method is safe to use with mutable objects such as hashes, strings or
 *  other arrays:
 *
 *     Array.new(4) { Hash.new }  #=> [{}, {}, {}, {}]
 *     Array.new(4) {|i| i.to_s } #=> ["0", "1", "2", "3"]
 *
 *  This is also a quick way to build up multi-dimensional arrays:
 *
 *     empty_table = Array.new(3) { Array.new(3) }
 *     #=> [[nil, nil, nil], [nil, nil, nil], [nil, nil, nil]]
 *
 *  An array can also be created by using the Array() method, provided by
 *  Kernel, which tries to call #to_ary, then #to_a on its argument.
 *
 *	Array({:a => "a", :b => "b"}) #=> [[:a, "a"], [:b, "b"]]
 *
 *  == Example Usage
 *
 *  In addition to the methods it mixes in through the Enumerable module, the
 *  Array class has proprietary methods for accessing, searching and otherwise
 *  manipulating arrays.
 *
 *  Some of the more common ones are illustrated below.
 *
 *  == Accessing Elements
 *
 *  Elements in an array can be retrieved using the Array#[] method.  It can
 *  take a single integer argument (a numeric index), a pair of arguments
 *  (start and length) or a range. Negative indices start counting from the end,
 *  with -1 being the last element.
 *
 *     arr = [1, 2, 3, 4, 5, 6]
 *     arr[2]    #=> 3
 *     arr[100]  #=> nil
 *     arr[-3]   #=> 4
 *     arr[2, 3] #=> [3, 4, 5]
 *     arr[1..4] #=> [2, 3, 4, 5]
 *     arr[1..-3] #=> [2, 3, 4]
 *
 *  Another way to access a particular array element is by using the #at method
 *
 *     arr.at(0) #=> 1
 *
 *  The #slice method works in an identical manner to Array#[].
 *
 *  To raise an error for indices outside of the array bounds or else to
 *  provide a default value when that happens, you can use #fetch.
 *
 *     arr = ['a', 'b', 'c', 'd', 'e', 'f']
 *     arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
 *     arr.fetch(100, "oops") #=> "oops"
 *
 *  The special methods #first and #last will return the first and last
 *  elements of an array, respectively.
 *
 *     arr.first #=> 1
 *     arr.last  #=> 6
 *
 *  To return the first +n+ elements of an array, use #take
 *
 *     arr.take(3) #=> [1, 2, 3]
 *
 *  #drop does the opposite of #take, by returning the elements after +n+
 *  elements have been dropped:
 *
 *     arr.drop(3) #=> [4, 5, 6]
 *
 *  == Obtaining Information about an Array
 *
 *  Arrays keep track of their own length at all times.  To query an array
 *  about the number of elements it contains, use #length, #count or #size.
 *
 *    browsers = ['Chrome', 'Firefox', 'Safari', 'Opera', 'IE']
 *    browsers.length #=> 5
 *    browsers.count #=> 5
 *
 *  To check whether an array contains any elements at all
 *
 *    browsers.empty? #=> false
 *
 *  To check whether a particular item is included in the array
 *
 *    browsers.include?('Konqueror') #=> false
 *
 *  == Adding Items to Arrays
 *
 *  Items can be added to the end of an array by using either #push or #<<
 *
 *    arr = [1, 2, 3, 4]
 *    arr.push(5) #=> [1, 2, 3, 4, 5]
 *    arr << 6    #=> [1, 2, 3, 4, 5, 6]
 *
 *  #unshift will add a new item to the beginning of an array.
 *
 *     arr.unshift(0) #=> [0, 1, 2, 3, 4, 5, 6]
 *
 *  With #insert you can add a new element to an array at any position.
 *
 *     arr.insert(3, 'apple')  #=> [0, 1, 2, 'apple', 3, 4, 5, 6]
 *
 *  Using the #insert method, you can also insert multiple values at once:
 *
 *     arr.insert(3, 'orange', 'pear', 'grapefruit')
 *     #=> [0, 1, 2, "orange", "pear", "grapefruit", "apple", 3, 4, 5, 6]
 *
 *  == Removing Items from an Array
 *
 *  The method #pop removes the last element in an array and returns it:
 *
 *     arr =  [1, 2, 3, 4, 5, 6]
 *     arr.pop #=> 6
 *     arr #=> [1, 2, 3, 4, 5]
 *
 *  To retrieve and at the same time remove the first item, use #shift:
 *
 *     arr.shift #=> 1
 *     arr #=> [2, 3, 4, 5]
 *
 *  To delete an element at a particular index:
 *
 *     arr.delete_at(2) #=> 4
 *     arr #=> [2, 3, 5]
 *
 *  To delete a particular element anywhere in an array, use #delete:
 *
 *     arr = [1, 2, 2, 3]
 *     arr.delete(2) #=> 2
 *     arr #=> [1,3]
 *
 *  A useful method if you need to remove +nil+ values from an array is
 *  #compact:
 *
 *     arr = ['foo', 0, nil, 'bar', 7, 'baz', nil]
 *     arr.compact  #=> ['foo', 0, 'bar', 7, 'baz']
 *     arr          #=> ['foo', 0, nil, 'bar', 7, 'baz', nil]
 *     arr.compact! #=> ['foo', 0, 'bar', 7, 'baz']
 *     arr          #=> ['foo', 0, 'bar', 7, 'baz']
 *
 *  Another common need is to remove duplicate elements from an array.
 *
 *  It has the non-destructive #uniq, and destructive method #uniq!
 *
 *     arr = [2, 5, 6, 556, 6, 6, 8, 9, 0, 123, 556]
 *     arr.uniq #=> [2, 5, 6, 556, 8, 9, 0, 123]
 *
 *  == Iterating over Arrays
 *
 *  Like all classes that include the Enumerable module, Array has an each
 *  method, which defines what elements should be iterated over and how.  In
 *  case of Array's #each, all elements in the Array instance are yielded to
 *  the supplied block in sequence.
 *
 *  Note that this operation leaves the array unchanged.
 *
 *     arr = [1, 2, 3, 4, 5]
 *     arr.each { |a| print a -= 10, " " }
 *     # prints: -9 -8 -7 -6 -5
 *     #=> [1, 2, 3, 4, 5]
 *
 *  Another sometimes useful iterator is #reverse_each which will iterate over
 *  the elements in the array in reverse order.
 *
 *     words = %w[first second third fourth fifth sixth]
 *     str = ""
 *     words.reverse_each { |word| str += "#{word} " }
 *     p str #=> "sixth fifth fourth third second first "
 *
 *  The #map method can be used to create a new array based on the original
 *  array, but with the values modified by the supplied block:
 *
 *     arr.map { |a| 2*a }   #=> [2, 4, 6, 8, 10]
 *     arr                   #=> [1, 2, 3, 4, 5]
 *     arr.map! { |a| a**2 } #=> [1, 4, 9, 16, 25]
 *     arr                   #=> [1, 4, 9, 16, 25]
 *
 *  == Selecting Items from an Array
 *
 *  Elements can be selected from an array according to criteria defined in a
 *  block.  The selection can happen in a destructive or a non-destructive
 *  manner.  While the destructive operations will modify the array they were
 *  called on, the non-destructive methods usually return a new array with the
 *  selected elements, but leave the original array unchanged.
 *
 *  === Non-destructive Selection
 *
 *     arr = [1, 2, 3, 4, 5, 6]
 *     arr.select { |a| a > 3 }     #=> [4, 5, 6]
 *     arr.reject { |a| a < 3 }     #=> [3, 4, 5, 6]
 *     arr.drop_while { |a| a < 4 } #=> [4, 5, 6]
 *     arr                          #=> [1, 2, 3, 4, 5, 6]
 *
 *  === Destructive Selection
 *
 *  #select! and #reject! are the corresponding destructive methods to #select
 *  and #reject
 *
 *  Similar to #select vs. #reject, #delete_if and #keep_if have the exact
 *  opposite result when supplied with the same block:
 *
 *     arr.delete_if { |a| a < 4 } #=> [4, 5, 6]
 *     arr                         #=> [4, 5, 6]
 *
 *     arr = [1, 2, 3, 4, 5, 6]
 *     arr.keep_if { |a| a < 4 } #=> [1, 2, 3]
 *     arr                       #=> [1, 2, 3]
 *
 */

void
Init_Array(void)
{
#undef rb_intern
#define rb_intern(str) rb_intern_const(str)

    rb_cArray  = rb_define_class("Array", rb_cObject);
    rb_include_module(rb_cArray, rb_mEnumerable);

    rb_define_alloc_func(rb_cArray, empty_ary_alloc);
    rb_define_singleton_method(rb_cArray, "[]", rb_ary_s_create, -1);
    rb_define_singleton_method(rb_cArray, "try_convert", rb_ary_s_try_convert, 1);
    rb_define_method(rb_cArray, "initialize", rb_ary_initialize, -1);
    rb_define_method(rb_cArray, "initialize_copy", rb_ary_replace, 1);

    rb_define_method(rb_cArray, "inspect", rb_ary_inspect, 0);
    rb_define_alias(rb_cArray,  "to_s", "inspect");
    rb_define_method(rb_cArray, "to_a", rb_ary_to_a, 0);
    rb_define_method(rb_cArray, "to_h", rb_ary_to_h, 0);
    rb_define_method(rb_cArray, "to_ary", rb_ary_to_ary_m, 0);
    rb_define_method(rb_cArray, "frozen?",  rb_ary_frozen_p, 0);

    rb_define_method(rb_cArray, "==", rb_ary_equal, 1);
    rb_define_method(rb_cArray, "eql?", rb_ary_eql, 1);
    rb_define_method(rb_cArray, "hash", rb_ary_hash, 0);

    rb_define_method(rb_cArray, "[]", rb_ary_aref, -1);
    rb_define_method(rb_cArray, "[]=", rb_ary_aset, -1);
    rb_define_method(rb_cArray, "at", rb_ary_at, 1);
    rb_define_method(rb_cArray, "fetch", rb_ary_fetch, -1);
    rb_define_method(rb_cArray, "first", rb_ary_first, -1);
    rb_define_method(rb_cArray, "last", rb_ary_last, -1);
    rb_define_method(rb_cArray, "concat", rb_ary_concat_multi, -1);
    rb_define_method(rb_cArray, "<<", rb_ary_push, 1);
    rb_define_method(rb_cArray, "push", rb_ary_push_m, -1);
    rb_define_alias(rb_cArray,  "append", "push");
    rb_define_method(rb_cArray, "pop", rb_ary_pop_m, -1);
    rb_define_method(rb_cArray, "shift", rb_ary_shift_m, -1);
    rb_define_method(rb_cArray, "unshift", rb_ary_unshift_m, -1);
    rb_define_alias(rb_cArray,  "prepend", "unshift");
    rb_define_method(rb_cArray, "insert", rb_ary_insert, -1);
    rb_define_method(rb_cArray, "each", rb_ary_each, 0);
    rb_define_method(rb_cArray, "each_index", rb_ary_each_index, 0);
    rb_define_method(rb_cArray, "reverse_each", rb_ary_reverse_each, 0);
    rb_define_method(rb_cArray, "length", rb_ary_length, 0);
    rb_define_alias(rb_cArray,  "size", "length");
    rb_define_method(rb_cArray, "empty?", rb_ary_empty_p, 0);
    rb_define_method(rb_cArray, "find_index", rb_ary_index, -1);
    rb_define_method(rb_cArray, "index", rb_ary_index, -1);
    rb_define_method(rb_cArray, "rindex", rb_ary_rindex, -1);
    rb_define_method(rb_cArray, "join", rb_ary_join_m, -1);
    rb_define_method(rb_cArray, "reverse", rb_ary_reverse_m, 0);
    rb_define_method(rb_cArray, "reverse!", rb_ary_reverse_bang, 0);
    rb_define_method(rb_cArray, "rotate", rb_ary_rotate_m, -1);
    rb_define_method(rb_cArray, "rotate!", rb_ary_rotate_bang, -1);
    rb_define_method(rb_cArray, "sort", rb_ary_sort, 0);
    rb_define_method(rb_cArray, "sort!", rb_ary_sort_bang, 0);
    rb_define_method(rb_cArray, "sort_by!", rb_ary_sort_by_bang, 0);
    rb_define_method(rb_cArray, "collect", rb_ary_collect, 0);
    rb_define_method(rb_cArray, "collect!", rb_ary_collect_bang, 0);
    rb_define_method(rb_cArray, "map", rb_ary_collect, 0);
    rb_define_method(rb_cArray, "map!", rb_ary_collect_bang, 0);
    rb_define_method(rb_cArray, "select", rb_ary_select, 0);
    rb_define_method(rb_cArray, "select!", rb_ary_select_bang, 0);
    rb_define_method(rb_cArray, "keep_if", rb_ary_keep_if, 0);
    rb_define_method(rb_cArray, "values_at", rb_ary_values_at, -1);
    rb_define_method(rb_cArray, "delete", rb_ary_delete, 1);
    rb_define_method(rb_cArray, "delete_at", rb_ary_delete_at_m, 1);
    rb_define_method(rb_cArray, "delete_if", rb_ary_delete_if, 0);
    rb_define_method(rb_cArray, "reject", rb_ary_reject, 0);
    rb_define_method(rb_cArray, "reject!", rb_ary_reject_bang, 0);
    rb_define_method(rb_cArray, "zip", rb_ary_zip, -1);
    rb_define_method(rb_cArray, "transpose", rb_ary_transpose, 0);
    rb_define_method(rb_cArray, "replace", rb_ary_replace, 1);
    rb_define_method(rb_cArray, "clear", rb_ary_clear, 0);
    rb_define_method(rb_cArray, "fill", rb_ary_fill, -1);
    rb_define_method(rb_cArray, "include?", rb_ary_includes, 1);
    rb_define_method(rb_cArray, "<=>", rb_ary_cmp, 1);

    rb_define_method(rb_cArray, "slice", rb_ary_aref, -1);
    rb_define_method(rb_cArray, "slice!", rb_ary_slice_bang, -1);

    rb_define_method(rb_cArray, "assoc", rb_ary_assoc, 1);
    rb_define_method(rb_cArray, "rassoc", rb_ary_rassoc, 1);

    rb_define_method(rb_cArray, "+", rb_ary_plus, 1);
    rb_define_method(rb_cArray, "*", rb_ary_times, 1);

    rb_define_method(rb_cArray, "-", rb_ary_diff, 1);
    rb_define_method(rb_cArray, "&", rb_ary_and, 1);
    rb_define_method(rb_cArray, "|", rb_ary_or, 1);

    rb_define_method(rb_cArray, "max", rb_ary_max, -1);
    rb_define_method(rb_cArray, "min", rb_ary_min, -1);

    rb_define_method(rb_cArray, "uniq", rb_ary_uniq, 0);
    rb_define_method(rb_cArray, "uniq!", rb_ary_uniq_bang, 0);
    rb_define_method(rb_cArray, "compact", rb_ary_compact, 0);
    rb_define_method(rb_cArray, "compact!", rb_ary_compact_bang, 0);
    rb_define_method(rb_cArray, "flatten", rb_ary_flatten, -1);
    rb_define_method(rb_cArray, "flatten!", rb_ary_flatten_bang, -1);
    rb_define_method(rb_cArray, "count", rb_ary_count, -1);
    rb_define_method(rb_cArray, "shuffle!", rb_ary_shuffle_bang, -1);
    rb_define_method(rb_cArray, "shuffle", rb_ary_shuffle, -1);
    rb_define_method(rb_cArray, "sample", rb_ary_sample, -1);
    rb_define_method(rb_cArray, "cycle", rb_ary_cycle, -1);
    rb_define_method(rb_cArray, "permutation", rb_ary_permutation, -1);
    rb_define_method(rb_cArray, "combination", rb_ary_combination, 1);
    rb_define_method(rb_cArray, "repeated_permutation", rb_ary_repeated_permutation, 1);
    rb_define_method(rb_cArray, "repeated_combination", rb_ary_repeated_combination, 1);
    rb_define_method(rb_cArray, "product", rb_ary_product, -1);

    rb_define_method(rb_cArray, "take", rb_ary_take, 1);
    rb_define_method(rb_cArray, "take_while", rb_ary_take_while, 0);
    rb_define_method(rb_cArray, "drop", rb_ary_drop, 1);
    rb_define_method(rb_cArray, "drop_while", rb_ary_drop_while, 0);
    rb_define_method(rb_cArray, "bsearch", rb_ary_bsearch, 0);
    rb_define_method(rb_cArray, "bsearch_index", rb_ary_bsearch_index, 0);
    rb_define_method(rb_cArray, "any?", rb_ary_any_p, 0);
    rb_define_method(rb_cArray, "dig", rb_ary_dig, -1);
    rb_define_method(rb_cArray, "sum", rb_ary_sum, -1);

    id_random = rb_intern("random");
    id_div = rb_intern("div");
}
yard-0.9.37/spec/parser/examples/example1.rb.txt000066400000000000000000000001171466601756300215110ustar00rootroot00000000000000module Hello
  class Hi
	# Docstring
    def me
      "Value"
    end
  end
endyard-0.9.37/spec/parser/examples/extrafile.c.txt000066400000000000000000000001051466601756300215740ustar00rootroot00000000000000/*
 * foo
 */
VALUE
rb_extra(VALUE obj, VALUE n)
{
  return Qtrue;
}
yard-0.9.37/spec/parser/examples/file.c.txt000066400000000000000000000010271466601756300205340ustar00rootroot00000000000000VALUE rb_cFile;

/*
 * call-seq:
 *    File.exist?(file_name)    ->  true or false
 *
 * Return true if the named file exists.
 *
 * _file_name_ can be an IO object.
 *
 * "file exists" means that stat() or fstat() system call is successful.
 */

static VALUE
rb_file_exist_p(VALUE obj, VALUE fname)
{
    struct stat st;

    if (rb_stat(fname, &st) < 0) return Qfalse;
    return Qtrue;
}

void
Init_File(void)
{
	rb_cFile = rb_define_class("File", rb_cIO);
    define_filetest_function("exist?", rb_file_exist_p, 1);
}
yard-0.9.37/spec/parser/examples/multifile.c.txt000066400000000000000000000005701466601756300216110ustar00rootroot00000000000000struct hoge *
rb_fuga(VALUE obj)
{
  return Qtrue;
}

/*
 * Hello Mars
 */
VALUE
rb_hello_mars(VALUE obj, VALUE n)
{
    return Qtrue;
}

void
Init_Multifile(void)
{
    rb_cMultifile  = rb_define_class("Multifile", rb_cObject);
    rb_define_method(rb_cMultifile, "extra", rb_extra, 1); /* in extra.c */
    rb_define_method(rb_cMultifile, "hello_mars", rb_hello_mars, 1);
}
yard-0.9.37/spec/parser/examples/namespace.cpp.txt000066400000000000000000000027221466601756300221140ustar00rootroot00000000000000VALUE rb_cWXRect;

namespace RubyWX {
namespace Rect {

VALUE _alloc(VALUE self)
{
    return wrap(new wxRect());
}

/*
 * call-seq:
 *   inspect -> String
 *
 * Human-readable description.
 * ===Return value
 * String
*/
VALUE _inspect(VALUE self)
{
    return rb_sprintf( "%s(%d, %d, %d, %d)",
        rb_obj_classname( self ),
        FIX2INT(_getX(self)),
        FIX2INT(_getY(self)),
        FIX2INT(_getWidth(self)),
        FIX2INT(_getHeight(self)));
}

} // namespace Rect
} // namespace RubyWX


/*
 * call-seq:
 *   hello_world -> String
 *
 * Human-readable description.
 * ===Return value
 * String
*/
VALUE _hello_world(VALUE self)
{
    return rb_sprintf( "%s(%d, %d, %d, %d)",
        rb_obj_classname( self ),
        FIX2INT(_getX(self)),
        FIX2INT(_getY(self)),
        FIX2INT(_getWidth(self)),
        FIX2INT(_getHeight(self)));
}

/* Arrays are ordered, integer-indexed collections of any object.
 * Array indexing starts at 0, as in C or Java.  A negative index is
 * assumed to be relative to the end of the array---that is, an index of -1
 * indicates the last element of the array, -2 is the next to last
 * element in the array, and so on.
 */

void Init_Rect()
{
    using namespace RubyWX::Rect;
    rb_cWXRect = rb_define_class("Rect",rb_cObject);

    rb_define_alloc_func(rb_cWXRect,_alloc);

    rb_define_method(rb_cWXRect,"inspect",RUBY_METHOD_FUNC(_inspect),0);
    rb_define_method(rb_cWXRect,"hello_world",RUBY_METHOD_FUNC(_hello_world),0);

}
yard-0.9.37/spec/parser/examples/override.c.txt000066400000000000000000000251111466601756300214340ustar00rootroot00000000000000#include 
#include 
#include 

/*
 * Document-class: GMP::Z
 *
 * GMP Multiple Precision Integer.
 *
 * Instances of this class can store variables of the type mpz_t. This class
 * also contains many methods that act as the functions for mpz_t variables,
 * as well as a few methods that attempt to make this library more Ruby-ish.
 */

/**********************************************************************
 *    Macros                                                          *
 **********************************************************************/

/*
 * DEFUN_INT2INT defines two functions. The first takes a GMP::Z as
 * self, calls mpz_fname on the contained mpz_t, whose arguments are
 * exactly (0) the return argument and (1) self. The second is the same
 * destructive method.
 */
#define DEFUN_INT2INT(fname,mpz_fname)         \
static VALUE r_gmpz_##fname(VALUE self)        \
{                                              \
  MP_INT *self_val, *res_val;                  \
  VALUE res;                                   \
  mpz_get_struct(self, self_val);              \
  mpz_make_struct_init(res, res_val);          \
  mpz_fname(res_val, self_val);                \
  return res;                                  \
}                                              \
                                               \
static VALUE r_gmpz_##fname##_self(VALUE self) \
{                                              \
  MP_INT *self_val;                            \
  mpz_get_struct(self, self_val);              \
  mpz_fname(self_val, self_val);               \
  return self;                                 \
}


/**********************************************************************
 *    Integer Arithmetic                                              *
 **********************************************************************/

/*
 * call-seq:
 *   a + b
 *
 * Adds _a_ to _b_. _b_ must be an instance of one of:
 * * GMP::Z
 * * Fixnum
 * * GMP::Q
 * * GMP::F
 * * Bignum
 */
VALUE r_gmpz_add(VALUE self, VALUE arg)
{
  MP_INT *self_val, *arg_val, *res_val;
  VALUE res;

  mpz_get_struct(self,self_val);

  if (GMPZ_P(arg)) {
    mpz_get_struct(arg,arg_val);
    mpz_make_struct_init(res, res_val);
    mpz_add(res_val, self_val, arg_val);
  } else if (FIXNUM_P(arg)) {
    mpz_make_struct_init(res, res_val);
    if (FIX2NUM(arg) > 0)
      mpz_add_ui(res_val, self_val, FIX2NUM(arg));
    else
      mpz_sub_ui(res_val, self_val, -FIX2NUM(arg));
  } else if (GMPQ_P(arg)) {
    return r_gmpq_add(arg, self);
  } else if (GMPF_P(arg)) {
#ifndef MPFR
    return r_gmpf_add(arg, self);
#else
    return rb_funcall(arg, rb_intern("+"), 1, self);
#endif
  } else if (BIGNUM_P(arg)) {
    mpz_make_struct_init(res, res_val);
    mpz_init(res_val);
    mpz_set_bignum(res_val, arg);
    mpz_add(res_val, res_val, self_val);
  } else {
    typeerror(ZQFXB);
  }
  return res;
}

/*
 * call-seq:
 *   a.add!(_b_)
 *
 * Adds _a_ to _b_ in-place, setting _a_ to the sum. _b_ must be an instance of one of:
 * * GMP::Z
 * * Fixnum
 * * GMP::Q
 * * GMP::F
 * * Bignum
 */
VALUE r_gmpz_add_self(VALUE self, VALUE arg)
{
  MP_INT *self_val, *arg_val;

  mpz_get_struct(self,self_val);

  if (GMPZ_P(arg)) {
    mpz_get_struct(arg,arg_val);
    mpz_add(self_val, self_val, arg_val);
  } else if (FIXNUM_P(arg)) {
    if (FIX2NUM(arg) > 0)
      mpz_add_ui(self_val, self_val, FIX2NUM(arg));
    else
      mpz_sub_ui(self_val, self_val, -FIX2NUM(arg));
  } else if (BIGNUM_P(arg)) {
    mpz_temp_from_bignum(arg_val, arg);
    mpz_add(self_val, self_val, arg_val);
    mpz_temp_free(arg_val);
  } else {
    typeerror(ZXB);
  }
  return Qnil;
}

/*
 * call-seq:
 *   a - b
 *
 * Subtracts _b_ from _a_. _b_ must be an instance of one of:
 * * GMP::Z
 * * Fixnum
 * * GMP::Q
 * * GMP::F
 * * Bignum
 */
VALUE r_gmpz_sub(VALUE self, VALUE arg)
{
  MP_RAT *res_val_q, *arg_val_q;
  MP_INT *self_val, *arg_val, *res_val;
  MP_FLOAT *arg_val_f, *res_val_f;
  VALUE res;
  unsigned long prec;

  mpz_get_struct(self,self_val);

  if (GMPZ_P(arg)) {
    mpz_make_struct_init(res, res_val);
    mpz_get_struct(arg,arg_val);
    mpz_sub (res_val, self_val, arg_val);
  } else if (FIXNUM_P(arg)) {
    mpz_make_struct_init(res, res_val);
    if (FIX2NUM(arg) > 0)
      mpz_sub_ui (res_val, self_val, FIX2NUM(arg));
    else
      mpz_add_ui (res_val, self_val, -FIX2NUM(arg));
  } else if (GMPQ_P(arg)) {
    mpq_make_struct_init(res, res_val_q);
    mpq_get_struct(arg,arg_val_q);
    mpz_set (mpq_denref(res_val_q), mpq_denref(arg_val_q));
    mpz_mul (mpq_numref(res_val_q), mpq_denref(arg_val_q), self_val);
    mpz_sub (mpq_numref(res_val_q), mpq_numref(res_val_q), mpq_numref(arg_val_q));
  } else if (GMPF_P(arg)) {
    mpf_get_struct_prec (arg, arg_val_f, prec);
    mpf_make_struct_init(res, res_val_f, prec);
    mpf_set_z (res_val_f, self_val);
    mpf_sub (res_val_f, res_val_f, arg_val_f);
  } else if (BIGNUM_P(arg)) {
    mpz_make_struct_init(res, res_val);
    mpz_set_bignum (res_val, arg);
    mpz_sub (res_val, self_val, res_val);
  } else {
    typeerror (ZQFXB);
  }
  return res;
}

/*
 * call-seq:
 *   a.sub!(b)
 *
 * Subtracts _b_ from _a_ in-place, setting _a_ to the difference. _b_ must be an
 * instance of one of:
 * * GMP::Z
 * * Fixnum
 * * GMP::Q
 * * GMP::F
 * * Bignum
 */
VALUE r_gmpz_sub_self(VALUE self, VALUE arg)
{
  MP_INT *self_val, *arg_val;

  mpz_get_struct(self,self_val);

  if (GMPZ_P(arg)) {
    mpz_get_struct(arg, arg_val);
    mpz_sub (self_val, self_val, arg_val);
  } else if (FIXNUM_P(arg)) {
    if (FIX2NUM(arg) > 0)
      mpz_sub_ui (self_val, self_val, FIX2NUM(arg));
    else
      mpz_add_ui (self_val, self_val, -FIX2NUM(arg));
  } else if (BIGNUM_P(arg)) {
    mpz_temp_from_bignum(arg_val, arg);
    mpz_sub (self_val, self_val, arg_val);
    mpz_temp_free (arg_val);
  } else {
    typeerror (ZXB);
  }
  return Qnil;
}

/*
 * call-seq:
 *   a * b
 *
 * Multiplies _a_ with _b_. _a_ must be an instance of one of
 * * GMP::Z
 * * Fixnum
 * * GMP::Q
 * * GMP::F
 * * Bignum
 */
VALUE r_gmpz_mul(VALUE self, VALUE arg)
{
  MP_INT *self_val, *arg_val, *res_val;
  VALUE res;

  mpz_get_struct(self,self_val);

  if (GMPZ_P(arg)) {
    mpz_make_struct_init(res, res_val);
    mpz_get_struct(arg,arg_val);
    mpz_mul(res_val, self_val, arg_val);
  } else if (FIXNUM_P(arg)) {
    mpz_make_struct_init(res, res_val);
    mpz_mul_si(res_val, self_val, FIX2NUM(arg));
  } else if (GMPQ_P(arg)) {
    return r_gmpq_mul(arg, self);
  } else if (GMPF_P(arg)) {
#ifndef MPFR
    return r_gmpf_mul(arg, self);
#else
    return rb_funcall(arg, rb_intern("*"), 1, self);
#endif
  } else if (BIGNUM_P(arg)) {
    mpz_make_struct_init(res, res_val);
    mpz_set_bignum(res_val, arg);
    mpz_mul(res_val, res_val, self_val);
  } else {
    typeerror(ZQFXB);
  }
  return res;
}

/*
 * call-seq:
 *   a.addmul!(b, c)
 *
 * @since 0.4.17
 *
 * Sets _a_ to _a_ plus _b_ times _c_. _b_ and _c_ must each be an instance of one of
 * * GMP::Z
 * * Fixnum
 * * Bignum
 */
VALUE r_gmpz_addmul_self(VALUE self, VALUE b, VALUE c)
{
  MP_INT *self_val, *b_val, *c_val;
  int free_b_val = 0;

  if (GMPZ_P(b)) {
    mpz_get_struct(b, b_val);
  } else if (FIXNUM_P(b)) {
    mpz_temp_alloc(b_val);
    mpz_init_set_si(b_val, FIX2NUM(b));
    free_b_val = 1;
  } else if (BIGNUM_P(b)) {
    mpz_temp_from_bignum(b_val, b);
    free_b_val = 1;
  } else {
    typeerror_as(ZXB, "addend");
  }
  mpz_get_struct(self, self_val);

  if (GMPZ_P(c)) {
    mpz_get_struct(c, c_val);
    mpz_addmul(self_val, b_val, c_val);
  } else if (FIXNUM_P(c)) {
    if (FIX2NUM(c) < 0)
    {
      if (free_b_val) { mpz_temp_free(b_val); }
      rb_raise(rb_eRangeError, "multiplicand (Fixnum) must be nonnegative");
    }
    mpz_addmul_ui(self_val, b_val, FIX2NUM(c));
  } else if (BIGNUM_P(c)) {
    mpz_temp_from_bignum(c_val, c);
    mpz_addmul(self_val, b_val, c_val);
    mpz_temp_free(c_val);
  } else {
    if (free_b_val)
      mpz_temp_free(b_val);
    typeerror_as(ZXB, "multiplicand");
  }
  if (free_b_val)
    mpz_temp_free(b_val);
  return self;
}

/*
 * Document-method: neg
 *
 * call-seq:
 *   a.neg
 *   -a
 *
 * Returns -_a_.
 */
/*
 * Document-method: neg!
 *
 * call-seq:
 *   a.neg!
 *
 * Sets _a_ to -_a_.
 */
DEFUN_INT2INT(neg, mpz_neg)
/*
 * Document-method: abs
 *
 * call-seq:
 *   a.abs
 *
 * Returns the absolute value of _a_.
 */
/*
 * Document-method: abs!
 *
 * call-seq:
 *   a.abs!
 *
 * Sets _a_ to its absolute value.
 */
DEFUN_INT2INT(abs, mpz_abs)


/**********************************************************************
 *    Integer Roots                                                   *
 **********************************************************************/

/*
 * Document-method: sqrt
 *
 * call-seq:
 *   a.sqrt
 *
 * Returns the truncated integer part of the square root of _a_.
 */
/*
 * Document-method: sqrt!
 *
 * call-seq:
 *   a.sqrt!
 *
 * Sets _a_ to the truncated integer part of its square root.
 */
DEFUN_INT2INT(sqrt, mpz_sqrt)

/*
 * call-seq:
 *   a.sqrtrem #=> s, r
 *
 * Returns the truncated integer part of the square root of _a_ as _s_ and the remainder
 * a - s * s as _r_, which will be zero if _a_ is a perfect square.
 */
static VALUE r_gmpz_sqrtrem(VALUE self)
{
  MP_INT *self_val, *sqrt_val, *rem_val;
  VALUE sqrt, rem;

  mpz_get_struct(self, self_val);
  mpz_make_struct_init(sqrt, sqrt_val);
  mpz_make_struct_init(rem, rem_val);
  mpz_sqrtrem(sqrt_val, rem_val, self_val);
  return rb_assoc_new(sqrt, rem);
}


/**********************************************************************
 *    Init function                                                   *
 **********************************************************************/

void init_gmpz()
{
  mGMP = rb_define_module("GMP");
  rb_define_module_function(mGMP, "Z", r_gmpmod_z, -1);

  cGMP_Z = rb_define_class_under(mGMP, "Z", rb_cInteger);

  // Integer Arithmetic
  rb_define_method(cGMP_Z, "+",       r_gmpz_add, 1);
  rb_define_method(cGMP_Z, "add!",    r_gmpz_add_self, 1);
  rb_define_method(cGMP_Z, "-",       r_gmpz_sub, 1);
  rb_define_method(cGMP_Z, "sub!",    r_gmpz_sub_self, 1);
  rb_define_method(cGMP_Z, "*",       r_gmpz_mul, 1);
  rb_define_method(cGMP_Z, "addmul!", r_gmpz_addmul_self, 2);
  rb_define_method(cGMP_Z, "neg",     r_gmpz_neg, 0);
  rb_define_method(cGMP_Z, "neg!",    r_gmpz_neg_self, 0);
  rb_define_method(cGMP_Z, "-@",      r_gmpz_neg, 0);
  rb_define_method(cGMP_Z, "abs",     r_gmpz_abs, 0);
  rb_define_method(cGMP_Z, "abs!",    r_gmpz_abs_self, 0);

  // Integer Roots
  rb_define_method(cGMP_Z, "root",    r_gmpz_root, 1);
  rb_define_method(cGMP_Z, "sqrt",    r_gmpz_sqrt, 0);
  rb_define_method(cGMP_Z, "sqrt!",   r_gmpz_sqrt_self, 0);
  rb_define_method(cGMP_Z, "sqrtrem", r_gmpz_sqrtrem, 0);
}
yard-0.9.37/spec/parser/examples/parse_in_order_001.rb.txt000066400000000000000000000000341466601756300233460ustar00rootroot00000000000000class MyModule::MyClass
end
yard-0.9.37/spec/parser/examples/parse_in_order_002.rb.txt000066400000000000000000000000231466601756300233450ustar00rootroot00000000000000module MyModule
endyard-0.9.37/spec/parser/examples/tag_handler_001.rb.txt000066400000000000000000000000771466601756300226320ustar00rootroot00000000000000class Foo

  # @api public
  # @return nil
  def foo
  end

endyard-0.9.37/spec/parser/ruby/000077500000000000000000000000001466601756300157765ustar00rootroot00000000000000yard-0.9.37/spec/parser/ruby/ast_node_spec.rb000066400000000000000000000022561466601756300211360ustar00rootroot00000000000000# frozen_string_literal: true
require 'pp'
require 'stringio'

include YARD::Parser::Ruby

RSpec.describe YARD::Parser::Ruby::AstNode do
  describe "#jump" do
    it "jumps to the first specific inner node if found" do
      ast = s(:paren, s(:paren, s(:params, s(s(:ident, "hi"), s(:ident, "bye")))))
      expect(ast.jump(:params)[0][0].type).to equal(:ident)
    end

    it "returns the original ast if no inner node is found" do
      ast = s(:paren, s(:list, s(:list, s(s(:ident, "hi"), s(:ident, "bye")))))
      expect(ast.jump(:params).object_id).to eq ast.object_id
    end
  end

  describe "#pretty_print" do
    it "shows a list of nodes" do
      obj = YARD::Parser::Ruby::RubyParser.parse("# x\nbye", "x").ast
      out = StringIO.new
      PP.pp(obj, out)
      vcall = RUBY_VERSION >= '1.9.3' ? 'vcall' : 'var_ref'
      expect(out.string).to eq "s(s(:#{vcall},\n" \
                               "      s(:ident, \"bye\", line: 2..2, source: 4..6),\n" \
                               "      docstring: \"x\",\n" \
                               "      line: 2..2,\n" \
                               "      source: 4..6))\n"
    end
  end unless YARD.ruby31?
end if HAVE_RIPPER
yard-0.9.37/spec/parser/ruby/legacy/000077500000000000000000000000001466601756300172425ustar00rootroot00000000000000yard-0.9.37/spec/parser/ruby/legacy/statement_list_spec.rb000066400000000000000000000176641466601756300236560ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Parser::Ruby::Legacy::StatementList do
  def stmts(code) YARD::Parser::Ruby::Legacy::StatementList.new(code) end
  def stmt(code) stmts(code).first end

  it "parses dangling block expressions" do
    s = stmt <<-eof
      if
          foo
        puts 'hi'
      end
eof

    expect(s.tokens.to_s(true)).to eq "if\n          foo\n        ...\n      end"
    expect(s.tokens.to_s).to eq "if\n          foo"
    expect(s.block.to_s).to eq "puts 'hi'"

    s = stmt <<-eof
      if foo ||
          bar
        puts 'hi'
      end
eof

    expect(s.tokens.to_s(true)).to eq "if foo ||\n          bar\n        ...\n      end"
    expect(s.tokens.to_s).to eq "if foo ||\n          bar"
    expect(s.block.to_s).to eq "puts 'hi'"
  end

  it "allows semicolons within parentheses" do
    s = stmt "(foo; bar)"

    expect(s.tokens.to_s(true)).to eq "(foo; bar)"
    expect(s.block).to be nil
  end

  it "allows for non-block statements" do
    s = stmt "hello_world(1, 2, 3)"
    expect(s.tokens.to_s).to eq "hello_world(1, 2, 3)"
    expect(s.block).to be nil
  end

  it "allows block statements to be used as part of other block statements" do
    s = stmt "while (foo; bar); foo = 12; end; while"

    expect(s.tokens.to_s(true)).to eq "while (foo; bar); ... end"
    expect(s.tokens.to_s).to eq "while (foo; bar)"
    expect(s.block.to_s).to eq "foo = 12"
  end

  it "allows continued processing after a block" do
    s = stmt "if foo; end.stuff"
    expect(s.tokens.to_s(true)).to eq "if foo; end.stuff"
    expect(s.block.to_s).to eq ""

    s = stmt "if foo; end[stuff]"
    expect(s.tokens.to_s(true)).to eq "if foo; end[stuff]"
    expect(s.block.to_s).to eq ""

    s = stmt "if foo; hi end.map do; 123; end"
    expect(s.tokens.to_s(true)).to eq "if foo; ... end.map do; 123; end"
    expect(s.block.to_s).to eq "hi"
  end

  it "parses default arguments" do
    s = stmt "def foo(bar, baz = 1, bang = 2); bar; end"
    expect(s.tokens.to_s(true)).to eq "def foo(bar, baz = 1, bang = 2) ... end"
    expect(s.block.to_s).to eq "bar"

    s = stmt "def foo bar, baz = 1, bang = 2; bar; end"
    expect(s.tokens.to_s(true)).to eq "def foo bar, baz = 1, bang = 2; ... end"
    expect(s.block.to_s).to eq "bar"

    s = stmt "def foo bar , baz = 1 , bang = 2; bar; end"
    expect(s.tokens.to_s(true)).to eq "def foo bar , baz = 1 , bang = 2; ... end"
    expect(s.block.to_s).to eq "bar"
  end

  it "parses complex default arguments" do
    s = stmt "def foo(bar, baz = File.new(1, 2), bang = 3); bar; end"
    expect(s.tokens.to_s(true)).to eq "def foo(bar, baz = File.new(1, 2), bang = 3) ... end"
    expect(s.block.to_s).to eq "bar"

    s = stmt "def foo bar, baz = File.new(1, 2), bang = 3; bar; end"
    expect(s.tokens.to_s(true)).to eq "def foo bar, baz = File.new(1, 2), bang = 3; ... end"
    expect(s.block.to_s).to eq "bar"

    s = stmt "def foo bar , baz = File.new(1, 2) , bang = 3; bar; end"
    expect(s.tokens.to_s(true)).to eq "def foo bar , baz = File.new(1, 2) , bang = 3; ... end"
    expect(s.block.to_s).to eq "bar"
  end

  it "parses blocks with do/end" do
    s = stmt <<-eof
      foo do
        puts 'hi'
      end
    eof

    expect(s.tokens.to_s(true)).to eq "foo do\n        ...\n      end"
    expect(s.block.to_s).to eq "puts 'hi'"
  end

  it "parses blocks with {}" do
    s = stmt "x { y }"
    expect(s.tokens.to_s(true)).to eq "x { ... }"
    expect(s.block.to_s).to eq "y"

    s = stmt "x() { y }"
    expect(s.tokens.to_s(true)).to eq "x() { ... }"
    expect(s.block.to_s).to eq "y"
  end

  it "parses blocks with begin/end" do
    s = stmt "begin xyz end"
    expect(s.tokens.to_s(true)).to eq "begin ... end"
    expect(s.block.to_s).to eq "xyz"
  end

  it "parses nested blocks" do
    s = stmt "foo(:x) { baz(:y) { skippy } }"

    expect(s.tokens.to_s(true)).to eq "foo(:x) { ... }"
    expect(s.block.to_s).to eq "baz(:y) { skippy }"
  end

  it "does not parse hashes as blocks" do
    s = stmt "x({})"
    expect(s.tokens.to_s(true)).to eq "x({})"
    expect(s.block.to_s).to eq ""

    s = stmt "x = {}"
    expect(s.tokens.to_s(true)).to eq "x = {}"
    expect(s.block.to_s).to eq ""

    s = stmt "x(y, {})"
    expect(s.tokens.to_s(true)).to eq "x(y, {})"
    expect(s.block.to_s).to eq ""
  end

  it "parses hashes in blocks with {}" do
    s = stmt "x {x = {}}"

    expect(s.tokens.to_s(true)).to eq "x {...}"
    expect(s.block.to_s).to eq "x = {}"
  end

  it "parses blocks with {} in hashes" do
    s = stmt "[:foo, x {}]"

    expect(s.tokens.to_s(true)).to eq "[:foo, x {}]"
    expect(s.block.to_s).to eq ""
  end

  it "handles multiple methods" do
    s = stmt <<-eof
      def %; end
      def b; end
    eof
    expect(s.to_s).to eq "def %; end"
  end

  it "handles nested methods" do
    s = stmt <<-eof
      def *(o) def +@; end
        def ~@
        end end
    eof
    expect(s.tokens.to_s(true)).to eq "def *(o) ... end"
    expect(s.block.to_s).to eq "def +@; end\n        def ~@\n        end"

    s = stmts(<<-eof)
      def /(other) 'hi' end
      def method1
        def dynamic; end
      end
    eof
    expect(s[1].to_s).to eq "def method1\n        def dynamic; end\n      end"
  end

  it "gets comment line numbers" do
    s = stmt <<-eof
      # comment
      # comment
      # comment
      def method; end
    eof
    expect(s.comments).to eq ["comment", "comment", "comment"]
    expect(s.comments_range).to eq(1..3)

    s = stmt <<-eof

      # comment
      # comment
      def method; end
    eof
    expect(s.comments).to eq ["comment", "comment"]
    expect(s.comments_range).to eq(2..3)

    s = stmt <<-eof
      # comment
      # comment

      def method; end
    eof
    expect(s.comments).to eq ["comment", "comment"]
    expect(s.comments_range).to eq(1..2)

    s = stmt <<-eof
      # comment
      def method; end
    eof
    expect(s.comments).to eq ["comment"]
    expect(s.comments_range).to eq(1..1)

    s = stmt <<-eof
      def method; end # comment
    eof
    expect(s.comments).to eq ["comment"]
    expect(s.comments_range).to eq(1..1)
  end

  it "only looks up to two lines back for comments" do
    s = stmt <<-eof
      # comments

      # comments

      def method; end
    eof
    expect(s.comments).to eq ["comments"]

    s = stmt <<-eof
      # comments


      def method; end
    eof
    expect(s.comments).to eq nil

    ss = stmts <<-eof
      # comments


      def method; end

      # hello
      def method2; end
    eof
    expect(ss[0].comments).to eq nil
    expect(ss[1].comments).to eq ['hello']
  end

  it "handles CRLF (Windows) newlines" do
    s = stmts("require 'foo'\r\n\r\n# Test Test\r\n# \r\n# Example:\r\n#   example code\r\ndef test\r\nend\r\n")
    expect(s[1].comments).to eq ['Test Test', '', 'Example:', '  example code']
  end

  it "handles elsif blocks" do
    s = stmts(stmt("if 0\n  foo\nelsif 2\n  bar\nend\nbaz").block)
    expect(s.size).to eq 2
    expect(s[1].tokens.to_s).to eq "elsif 2"
    expect(s[1].block.to_s).to eq "bar"
  end

  it "handles else blocks" do
    s = stmts(stmt("if 0\n  foo\nelse\n  bar\nend\nbaz").block)
    expect(s.size).to eq 2
    expect(s[1].tokens.to_s).to eq "else"
    expect(s[1].block.to_s).to eq "bar"
  end

  it "allows aliasing keywords" do
    ['do x', 'x do', 'end begin', 'begin end'].each do |a|
      s = stmt("alias #{a}\ndef foo; end")
      expect(s.tokens.to_s).to eq "alias #{a}"
      expect(s.block).to be nil
    end

    s = stmt("alias do x if 2 ==\n 2")
    expect(s.tokens.to_s).to eq "alias do x if 2 ==\n 2"
  end

  it "does not open a block on an aliased keyword block opener" do
    s = stmts(<<-eof)
      class A; alias x do end
      class B; end
    eof
    expect(s[0].block.to_s).to eq 'alias x do'
    expect(s.size).to be > 1
  end

  it "converts heredoc to string" do
    src = "<<-XML\n  foo\n\nXML"
    s = stmt(src)
    expect(s.source).to eq '"  foo\n\n"'
  end

  it "converts squiggly heredoc to string" do
    src = "<<~XML\n  bar\n\nXML"
    s = stmt(src)
    expect(s.source).to eq '"bar\n\n"'
  end
end
yard-0.9.37/spec/parser/ruby/legacy/token_list_spec.rb000066400000000000000000000046551466601756300227660ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Parser::Ruby::Legacy::TokenList do
  Legacy = YARD::Parser::Ruby::Legacy
  TokenList = Legacy::TokenList
  LT = Legacy::RubyToken

  describe "#initialize / #push" do
    it "accepts a tokenlist (via constructor or push)" do
      expect { TokenList.new(TokenList.new) }.not_to raise_error
      expect(TokenList.new.push(TokenList.new("x = 2")).size).to eq 6
    end

    it "accept a token (via constructor or push)" do
      expect { TokenList.new(LT::Token.new(0, 0)) }.not_to raise_error
      expect(TokenList.new.push(LT::Token.new(0, 0),
                                LT::Token.new(1, 1)).size).to eq 2
    end

    it "accepts a string and parse it as code (via constructor or push)" do
      expect { TokenList.new("x = 2") }.not_to raise_error
      x = TokenList.new
      x.push("x", "=", "2")
      expect(x.size).to eq 6
      expect(x.to_s).to eq "x\n=\n2\n"
    end

    it "does not accept any other input" do
      expect { TokenList.new(:notcode) }.to raise_error(ArgumentError)
    end

    it "does not interpolate string data" do
      x = TokenList.new('x = "hello #{world}"')
      expect(x.size).to eq 6
      expect(x[4].class).to eq LT::TkDSTRING
      expect(x.to_s).to eq 'x = "hello #{world}"' + "\n"
    end

    it "handles label syntax" do
      x = TokenList.new('a:1,b:2')
      expect(x[0].class).to eq LT::TkLABEL
      expect(x[0].text).to eq 'a:'
      expect(x[3].class).to eq LT::TkLABEL
      expect(x[3].text).to eq 'b:'
    end
  end

  describe "#to_s" do
    before do
      @t = TokenList.new
      @t << LT::TkDEF.new(1, 1, "def")
      @t << LT::TkSPACE.new(1, 1)
      @t << LT::TkIDENTIFIER.new(1, 1, "x")
      @t << LT::TkStatementEnd.new(1, 1)
      @t << LT::TkSEMICOLON.new(1, 1) << LT::TkSPACE.new(1, 1)
      @t << LT::TkBlockContents.new(1, 1)
      @t << LT::TkSPACE.new(1, 1) << LT::TkEND.new(1, 1, "end")
      @t[0].set_text "def"
      @t[1].set_text " "
      @t[2].set_text "x"
      @t[4].set_text ";"
      @t[5].set_text " "
      @t[7].set_text " "
      @t[8].set_text "end"
    end

    it "only shows the statement portion of the tokens by default" do
      expect(@t.to_s).to eq "def x"
    end

    it "shows ... for the block token if all of the tokens are shown" do
      expect(@t.to_s(true)).to eq "def x; ... end"
    end

    it "ignores ... if show_block = false" do
      expect(@t.to_s(true, false)).to eq "def x;  end"
    end
  end
end
yard-0.9.37/spec/parser/ruby/ruby_parser_spec.rb000066400000000000000000000362431466601756300217020ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Parser::Ruby::RubyParser do
  def stmt(stmt)
    YARD::Parser::Ruby::RubyParser.new(stmt, nil).parse.root.first
  end

  def stmts(stmts)
    YARD::Parser::Ruby::RubyParser.new(stmts, nil).parse.root
  end

  def tokenize(stmt)
    YARD::Parser::Ruby::RubyParser.new(stmt, nil).parse.tokens
  end

  describe "#parse" do
    it "gets comment line numbers" do
      s = stmt <<-eof
        # comment
        # comment
        # comment
        def method; end
      eof
      expect(s.comments).to eq "comment\ncomment\ncomment"
      expect(s.comments_range).to eq(1..3)

      s = stmt <<-eof

        # comment
        # comment
        def method; end
      eof
      expect(s.comments).to eq "comment\ncomment"
      expect(s.comments_range).to eq(2..3)

      s = stmt <<-eof
        # comment
        # comment

        def method; end
      eof
      expect(s.comments).to eq "comment\ncomment"
      expect(s.comments_range).to eq(1..2)

      s = stmt <<-eof
        # comment
        def method; end
      eof
      expect(s.comments).to eq "comment"
      expect(s.comments_range).to eq(1..1)

      s = stmt <<-eof
        def method; end # comment
      eof
      expect(s.comments).to eq "comment"
      expect(s.comments_range).to eq(1..1)
    end

    it "only looks up to two lines back for comments" do
      s = stmts <<-eof
        # comments

        # comments

        def method; end
      eof
      expect(s[1].comments).to eq "comments"

      s = stmts <<-eof
        # comments


        def method; end
      eof
      expect(s[1].comments).to eq nil

      ss = stmts <<-eof
        # comments


        def method; end

        # hello
        def method2; end
      eof
      expect(ss[1].comments).to eq nil
      expect(ss[2].comments).to eq 'hello'
    end

    it "handles block comment followed by line comment" do
      ss = stmts <<-eof
# comments1

=begin
comments2
=end
# comments3
def hello; end
eof
      expect(ss.last.comments).to eq "comments3"
    end

    it "handles block comment followed by block comment" do
      ss = stmts <<-eof
=begin
comments1
=end
=begin
comments2
=end
def hello; end
eof
      expect(ss.last.comments.strip).to eq "comments2"
    end

    it "handles 1.9 lambda syntax with args" do
      src = "->(a,b,c=1,*args,&block) { hello_world }"
      expect(stmt(src).source).to eq src
    end

    it "handles 1.9 lambda syntax" do
      src = "-> { hello_world }"
      expect(stmt(src).source).to eq src
    end

    it "handles standard lambda syntax" do
      src = "lambda { hello_world }"
      expect(stmt(src).source).to eq src
    end

    it "throws a ParserSyntaxError on invalid code" do
      expect { stmt("Foo, bar.") }.to raise_error(YARD::Parser::ParserSyntaxError)
    end

    it "handles bare hashes as method parameters" do
      src = "command :a => 1, :b => 2, :c => 3"
      expect(stmt(src).jump(:command)[1].source).to eq ":a => 1, :b => 2, :c => 3"

      src = "command a: 1, b: 2, c: 3"
      expect(stmt(src).jump(:command)[1].source).to eq "a: 1, b: 2, c: 3"
    end

    it "handles source for hash syntax" do
      src = "{ :a => 1, :b => 2, :c => 3 }"
      expect(stmt(src).jump(:hash).source).to eq "{ :a => 1, :b => 2, :c => 3 }"
    end

    it "handles an empty hash" do
      expect(stmt("{}").jump(:hash).source).to eq "{}"
    end

    it "new hash label syntax should show label without colon" do
      ast = stmt("{ a: 1 }").jump(:label)
      expect(ast[0]).to eq "a"
      expect(ast.source).to eq "a:"
    end

    it "handles begin/rescue blocks" do
      ast = stmt("begin; X; rescue => e; Y end").jump(:rescue)
      expect(ast.source).to eq "rescue => e; Y end"

      ast = stmt("begin; X; rescue A => e; Y end").jump(:rescue)
      expect(ast.source).to eq "rescue A => e; Y end"

      ast = stmt("begin; X; rescue A, B => e; Y end").jump(:rescue)
      expect(ast.source).to eq "rescue A, B => e; Y end"
    end

    it "handles method rescue blocks" do
      ast = stmt("def x; A; rescue Y; B end")
      expect(ast.source).to eq "def x; A; rescue Y; B end"
      expect(ast.jump(:rescue).source).to eq "rescue Y; B end"
    end

    it "handles defs with keywords as method name" do
      ast = stmt("# docstring\nclass A;\ndef class; end\nend")
      expect(ast.jump(:class).docstring).to eq "docstring"
      expect(ast.jump(:class).line_range).to eq(2..4)
    end

    it "handles defs with unnamed argument with default values" do
      ast = stmt('def hello(one, two = 2, three = 3) end').jump(:params)
      expect(ast.source).to eq 'one, two = 2, three = 3'
    end

    it "handles defs with splats" do
      ast = stmt('def hello(one, *two) end').jump(:params)
      expect(ast.source).to eq 'one, *two'
    end

    if YARD.ruby2?
      it "handles defs with named arguments with default values" do
        ast = stmt('def hello(one, two: 2, three: 3) end').jump(:params)
        expect(ast.source).to eq 'one, two: 2, three: 3'
      end
    end

    if NAMED_OPTIONAL_ARGUMENTS
      it "handles defs with named arguments without default values" do
        ast = stmt('def hello(one, two:, three:) end').jump(:params)
        expect(ast.source).to eq 'one, two:, three:'
      end

      it "handles defs with double splats" do
        ast = stmt('def hello(one, **two) end').jump(:params)
        expect(ast.source).to eq 'one, **two'
      end
    end

    it "ends source properly on array reference" do
      ast = stmt("AS[0, 1 ]   ")
      expect(ast.source).to eq 'AS[0, 1 ]'

      ast = stmt('def x(a = S[1]) end').jump(:params)
      expect(ast.source).to eq 'a = S[1]'

      ast = stmt('a[b[c]]')
      expect(ast.source).to eq 'a[b[c]]'
    end

    it "ends source properly on if/unless mod" do
      %w(if unless while).each do |mod|
        expect(stmt("A=1 #{mod} true").source).to eq "A=1 #{mod} true"
      end
    end

    it "shows proper source for assignment" do
      expect(stmt("A=1").jump(:assign).source).to eq "A=1"
    end

    it "shows proper source for a top_const_ref" do
      s = stmt("::\nFoo::Bar")
      expect(s.jump(:top_const_ref).source).to eq "::\nFoo"
      expect(s).to be_ref
      expect(s.jump(:top_const_ref)).to be_ref
      expect(s.source).to eq "::\nFoo::Bar"
      expect(s.line_range.to_a).to eq [1, 2]
    end

    it "shows proper source for inline heredoc" do
      src = "def foo\n  foo(<<-XML, 1, 2)\n    bar\n\n  XML\nend"
      s = stmt(src)
      t = tokenize(src)
      expect(s.source).to eq src
      expect(t.map {|x| x[1] }.join).to eq src
    end

    it "shows proper source for regular heredoc" do
      src = "def foo\n  x = <<-XML\n  Hello \#{name}!\n  Bye!\n  XML\nend"
      s = stmt(src)
      t = tokenize(src)
      expect(s.source).to eq src
      expect(t.map {|x| x[1] }.join).to eq src
    end

    it "shows proper source for heredoc with comment" do
      src = "def foo\n  x = <<-XML # HI!\n  Hello \#{name}!\n  Bye!\n  XML\nend"
      s = stmt(src)
      t = tokenize(src)
      expect(s.source).to eq src
      expect(t.map {|x| x[1] }.join).to eq src
    end

    it "shows proper source for string" do
      ["'", '"'].each do |q|
        src = "#{q}hello\n\nworld#{q}"
        s = stmt(src)
        expect(s.jump(:string_content).source).to eq "hello\n\nworld"
        expect(s.source).to eq src
      end

      src = '("this is a string")'
      expect(stmt(src).jump(:string_literal).source).to eq '"this is a string"'
    end

    %w(w W i I).each do |tok|
      it "shows proper source for %#{tok}() array" do
        src = "%#{tok}(\na b c\n d e f\n)"
        expect(stmt(src).source).to eq src
      end

      it "shows proper source for %#{tok}{} array" do
        src = "%#{tok}{\na b c\n d e f\n}"
        expect(stmt(src).source).to eq src
      end
    end

    {'i' => :qsymbols_literal, 'I' => :symbols_literal,
     'w' => :qwords_literal, 'W' => :words_literal}.each do |id, sym|
      it "parses %#{id}(...) literals" do
        [
          "TEST = %#{id}(A B C)",
          "TEST = %#{id}(  A  B  C  )",
          "TEST = %#{id}( \nA \nB \nC \n)",
          "TEST = %#{id}(\n\nAD\n\nB\n\nC\n\n)",
          "TEST = %#{id}(\n A\n B\n C\n )"
        ].each do |str|
          node = stmt(str).jump(sym)
          expect(node.source).to eq(str[/(\%#{id}\(.+\))/m, 1])
        end
      end

      it "tokenizing %#{id}(...) returns correct tokens" do
        toks = tokenize("TEST = %#{id}(A B C)").flatten
        expect(toks.count(:tstring_content)).to eq(3)
      end
    end

    it "properly tokenizes symbols" do
      tokens = tokenize(<<-eof)
        class X
          Foo = :''
          Fuu = :bar
          Bar = :BAR
          Baz = :"B+z"
          Qux = :if
        end
      eof
      symbols = tokens.select {|t| t[0] == :symbol }.map {|t| t[1] }
      expect(symbols).to eq %w(:'' :bar :BAR :"B+z" :if)
    end

    # @bug gh-1313
    it "tokenizes comments in-order" do
      src = <<-eof
        def method
          # Method comment not docstring
        end
      eof
      
      tokens = tokenize(src.gsub(/^ +/, ''))
      expect(tokens).to eq(tokens.sort_by {|t| t.last })
      expect(tokens.map {|t| t.first }).to eq %i(kw sp ident nl comment kw nl)
    end

    it "parses %w() array in constant declaration" do
      s = stmt(<<-eof)
        class Foo
          FOO = %w( foo bar )
        end
      eof
      expect(s.jump(:qwords_literal).source).to eq '%w( foo bar )'
      if RUBY_VERSION >= '1.9.3' # ripper fix: array node encapsulates qwords
        expect(s.jump(:array).source).to eq '%w( foo bar )'
      end
    end

    it "parses %w() array source in object[] parsed context" do
      s = stmts(<<-eof)
        {}[:key]
        FOO = %w( foo bar )
      eof
      expect(s[1].jump(:array).source).to eq '%w( foo bar )'
    end

    it "parses %w() array source in object[]= parsed context" do
      s = stmts(<<-eof)
        {}[:key] = :value
        FOO = %w( foo bar )
      eof
      expect(s[1].jump(:array).source).to eq '%w( foo bar )'
    end

    it "parses [] as array" do
      s = stmt(<<-eof)
        class Foo
          FOO = ['foo', 'bar']
        end
      eof
      expect(s.jump(:array).source).to eq "['foo', 'bar']"
    end

    it "shows source for unary minus" do
      expect(stmt("X = - 1").jump(:unary).source).to eq '- 1'
    end

    it "shows source for unary exclamation" do
      expect(stmt("X = !1").jump(:unary).source).to eq '!1'
    end

    it "has the correct line range for class/modules" do
      s = stmt(<<-eof)
        class Foo
          def foo; end



          # Ending comment
        end
      eof
      expect(s.jump(:class).line_range).to eq(1..7)
    end

    it "has the correct line range for blocks" do
      Registry.clear
      ast = YARD.parse_string(<<-eof).enumerator
        module A
          some_method
        end
      eof
      expect(ast.first.block.source.strip).to eq "some_method"
    end

    it "finds lone comments" do
      Registry.clear
      ast = YARD.parse_string(<<-eof).enumerator
        class Foo
          ##
          # comment here


          def foo; end

          # end comment
        end
      eof
      comment = ast.first.last.jump(:comment)
      expect(comment.type).to eq :comment
      expect(comment.docstring_hash_flag).to be true
      expect(comment.docstring.strip).to eq "comment here"

      expect(ast.first.last.last.type).to eq :comment
      expect(ast.first.last.last.docstring).to eq "end comment"
    end

    it "does not group comments if they don't begin the line" do
      Registry.clear
      YARD.parse_string(<<-eof).enumerator
        class Foo
          CONST1 = 1 # Comment here
          CONST2 = 2 # Another comment here
        end
      eof
      expect(Registry.at("Foo::CONST1").docstring).to eq "Comment here"
      expect(Registry.at("Foo::CONST2").docstring).to eq "Another comment here"
    end

    it "handles comments in the middle of a multi-line statement" do
      Registry.clear
      YARD.parse_string <<-eof
        foo # BREAK
        .bar

        # Documentation
        class Baz; end
      eof
      expect(Registry.at('Baz')).not_to be_nil
      expect(Registry.at('Baz').docstring).to eq 'Documentation'
    end

    %w(if unless).each do |type|
      it "does not get confused by modifier '#{type}' statements" do
        Registry.clear
        YARD.parse_string(<<-eof).enumerator
          module Foo
            #{type} test?
              # Docstring
              class Bar
                # Docstring2
                def foo
                  x #{type} true
                end
              end
            end
          end
        eof

        expect(Registry.at("Foo::Bar").docstring).to eq "Docstring"
        expect(Registry.at("Foo::Bar#foo").docstring).to eq "Docstring2"
      end

      it "supports #{type} statements at start of source" do
        Registry.clear
        YARD.parse_string <<-eof
          #{type} condition?
            class Foo; def bar; #{type} true; end end end
          end
        eof

        expect(log.io.string).to eq ""
        expect(Registry.at('Foo#bar')).not_to eq nil
      end

      it "can handle complex non-modifier '#{type}' statements" do
        Registry.clear
        YARD.parse_string <<-eof
          class Foo
            def initialize(data, options = Hash.new)
              #{type} true; raise "error" end
              @x = ( #{type} 1; true end ) # This line should not blow up
            end
          end
        eof

        expect(log.io.string).to eq ""
        expect(Registry.at('Foo#initialize')).not_to eq nil
      end

      it "does not add comment blocks to #{type}_mod nodes" do
        Registry.clear
        YARD.parse_string(<<-eof).enumerator
          class Foo
            # Docstring
            def bar; end if true
          end
        eof

        expect(Registry.at("Foo#bar").docstring).to eq "Docstring"
      end
    end

    it "removes frozen string line from initial file comments" do
      YARD.parse_string "# frozen_string_literal: true\n# this is a comment\nclass Foo; end"
      YARD.parse_string "# Frozen-string-literal: false\n# this is a comment\nclass Bar; end"

      expect(Registry.at(:Foo).docstring).to eq "this is a comment"
      expect(Registry.at(:Bar).docstring).to eq "this is a comment"
    end

    it "handles compile errors" do
      expect { stmt(":~$ Do not clobber") }.to raise_error(Parser::ParserSyntaxError)
    end

    it "handles cls/mod comments without line spacing" do
      ast = stmt <<-eof
        module A
          # comment 1
          # comment 2
          class B
          end
        end
      eof
      expect(ast.jump(:class).docstring).to eq "comment 1\ncomment 2"
    end

    %w(if unless).each do |type|
      let(:condition_type) { type }
      let(:ast) { stmt '"#{' + type + ' condition?; 42; end}" ' + type + ' verbose?' }
      let(:subject) { ast.jump(:string_embexpr)[0][0].source }

      it "returns correct source for interpolated non-ternary '#{type}' conditionals" do
        is_expected.to eq "#{condition_type} condition?; 42; end"
      end
    end

    it "handles single-line method declaration syntax" do
      YARD.parse_string <<-eof
        class A
          # Adds two numbers
          def add(x) = x + 1
        end
      eof

      expect(Registry.at('A#add').docstring).to eq('Adds two numbers')
    end if RUBY_VERSION >= '3.'
  end
end if HAVE_RIPPER
yard-0.9.37/spec/parser/ruby/token_resolver_spec.rb000066400000000000000000000100631466601756300223760ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Parser::Ruby::TokenResolver do
  before(:all) do
    YARD.parse_string <<-eof
      module A
        def nomatch; end

        module B
          class C
            def initialize; end

            # @return [A::B::C]
            def self.foo; end

            # @return [self]
            def self.foo2; end

            def bar; end

            # @return [nil, D]
            def baz; end

            # @return [nil]
            # @return [D]
            def baz2; end

            # @overload qux(a)
            #   @return [nil]
            # @overload qux(b)
            #   @return [D]
            def qux; end
          end

          class SubC < C
          end
        end
      end

      module D
        def baz; end
      end

      class Q
        def method; end

        # @return [Q]
        def self.q; end
      end
    eof
  end

  def tokens_match
    expect(@resolved.map {|t| t.first.last }.join).to eq @src
  end

  def objs_match(*objects)
    other_objs = @resolved.reject {|_, o| !o }.map {|_, o| o.path }
    expect(other_objs).to eq objects.flatten
    tokens_match
  end

  def tokenize(src, object = nil)
    @src = src
    @resolver = YARD::Parser::Ruby::TokenResolver.new(src, object)
    @resolved = @resolver.map {|t, o| [t[0, 2], o] }
  end

  it "returns regular tokens" do
    str = "def foo; Z::X::Y end"
    tokenize(str)
    tokens_match
  end

  it "resolves objects in compound constant paths" do
    tokenize "A::B::C"
    objs_match "A", "A::B", "A::B::C"
  end

  it "ignores full constant path if it breaks at beginning" do
    tokenize "E::A::B::C"
    objs_match []
  end

  it "ignores rest of constant path if sub-objects don't match" do
    tokenize "D::A::B::C"
    objs_match "D"
  end

  it "resets parsing at non-op tokens" do
    tokenize "A::B::C < Q"
    objs_match "A", "A::B", "A::B::C", "Q"
  end

  it "does not restart constant path" do
    tokenize "A::B::D::A"
    objs_match "A", "A::B"
  end

  it "resolves objects from base namespace" do
    tokenize "A::B::C C", Registry.at("A::B")
    objs_match "A", "A::B", "A::B::C", "A::B::C"
  end

  it "resolves methods" do
    tokenize "A::B::C.foo"
    objs_match "A", "A::B", "A::B::C", "A::B::C.foo"
  end

  it "supports 'new' constructor method" do
    tokenize "A::B::C.new"
    objs_match "A", "A::B", "A::B::C", "A::B::C#initialize"
  end

  it "skips constructor method if not found but continues resolving" do
    tokenize "Q.new.method"
    objs_match "Q", "Q#method"
  end

  it "resolves methods in inheritance tree" do
    tokenize "A::B::SubC.new"
    objs_match "A", "A::B", "A::B::SubC", "A::B::C#initialize"
  end

  it "parses compound method call chains based on return type" do
    tokenize "A::B::C.foo.baz"
    objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#baz"
  end

  it "stops resolving if return types not found" do
    tokenize "A::B::C.foo.bar.baz.baz"
    objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#bar"
  end

  it "handles multiple return types (returns first valid type match)" do
    tokenize "A::B::C.foo.baz.baz"
    objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#baz", "D#baz"
  end

  it "doesn't perform lexical matching on methods" do
    tokenize "A::B::C.nomatch"
    objs_match "A", "A::B", "A::B::C"
  end

  it "handles multiple return tags (returns first valid type match)" do
    tokenize "A::B::C.foo.baz2.baz"
    objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#baz2", "D#baz"
  end

  it "handles self as return type" do
    tokenize "A::B::C.foo2.baz"
    objs_match "A", "A::B", "A::B::C", "A::B::C.foo2", "A::B::C#baz"
  end

  it "handles multiple return tags inside overload tags" do
    tokenize "A::B::C.foo.qux.baz"
    objs_match "A", "A::B", "A::B::C", "A::B::C.foo", "A::B::C#qux", "D#baz"
  end

  it "resolves method calls with arguments" do
    tokenize "Q.q(A::B, A::B::C.foo().bar).q.q"
    objs_match "Q", "Q.q", "A", "A::B", "A", "A::B", "A::B::C",
               "A::B::C.foo", "A::B::C#bar", "Q.q", "Q.q"
  end
end if HAVE_RIPPER
yard-0.9.37/spec/parser/source_parser_spec.rb000066400000000000000000000614571466601756300212450ustar00rootroot00000000000000# frozen_string_literal: true

class MyParser < Parser::Base; end

RSpec.shared_examples_for "parser type registration" do
  after do
    Parser::SourceParser.parser_types.delete(:my_parser)
    Parser::SourceParser.parser_type_extensions.delete(:my_parser)
  end
end

RSpec.describe YARD::Parser::SourceParser do
  before do
    Registry.clear
  end

  def parse_list(*list)
    files = list.map do |v|
      filename, source = *v
      allow(File).to receive(:read_binary).with(filename).and_return(source)
      filename
    end
    Parser::SourceParser.send(:parse_in_order, *files)
  end

  def before_list(&block)
    Parser::SourceParser.before_parse_list(&block)
  end

  def after_list(&block)
    Parser::SourceParser.after_parse_list(&block)
  end

  def before_file(&block)
    Parser::SourceParser.before_parse_file(&block)
  end

  def after_file(&block)
    Parser::SourceParser.after_parse_file(&block)
  end

  describe ".before_parse_list" do
    before do
      Parser::SourceParser.before_parse_list_callbacks.clear
      Parser::SourceParser.after_parse_list_callbacks.clear
    end

    it "handles basic callback support" do
      before_list do |files, globals|
        expect(files).to eq ['foo.rb', 'bar.rb']
        expect(globals).to eq YARD::OpenStruct.new
      end
      parse_list ['foo.rb', 'foo!'], ['bar.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
    end

    it "supports multiple callbacks" do
      checks = []
      before_list { checks << :one }
      before_list { checks << :two }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :two]
    end

    it "cancels parsing if it returns false" do
      checks = []
      before_list { checks << :one }
      before_list { false }
      before_list { checks << :three }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).to be nil
      expect(checks).to eq [:one]
    end

    it "does not cancel on nil" do
      checks = []
      before_list { checks << :one }
      before_list { nil }
      before_list { checks << :two }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :two]
    end

    it "passes in globals" do
      before_list {|_f, g| g.x = 1 }
      before_list {|_f, g| g.x += 1 }
      before_list {|_f, g| g.x += 1 }
      after_list {|_f, g| expect(g.x).to eq 3 }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
    end
  end

  describe ".after_parse_list" do
    before do
      Parser::SourceParser.before_parse_list_callbacks.clear
      Parser::SourceParser.after_parse_list_callbacks.clear
    end

    it "handles basic callback support and maintain files/globals" do
      before_list {|_f, g| g.foo = :bar }
      after_list do |files, globals|
        expect(files).to eq ['foo.rb', 'bar.rb']
        expect(globals.foo).to eq :bar
      end
      parse_list ['foo.rb', 'foo!'], ['bar.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
    end

    it "supports multiple callbacks" do
      checks = []
      after_list { checks << :one }
      after_list { checks << :two }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :two]
    end

    it "does not cancel parsing if it returns false" do
      checks = []
      after_list { checks << :one }
      after_list { false }
      after_list { checks << :three }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :three]
    end
  end

  describe ".before_parse_file" do
    before do
      Parser::SourceParser.before_parse_file_callbacks.clear
      Parser::SourceParser.after_parse_file_callbacks.clear
    end

    it "handles basic callback support" do
      before_file do |parser|
        expect(parser.contents).to eq 'class Foo; end'
        expect(parser.file).to match(/(foo|bar)\.rb/)
      end
      parse_list ['foo.rb', 'class Foo; end'], ['bar.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
    end

    it "supports multiple callbacks" do
      checks = []
      before_file { checks << :one }
      before_file { checks << :two }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :two, :one, :two, :one, :two]
    end

    it "cancels parsing if it returns false" do
      checks = []
      before_file { checks << :one }
      before_file { false }
      before_file { checks << :three }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).to be nil
      expect(checks).to eq [:one, :one, :one]
    end

    it "does not cancel on nil" do
      checks = []
      before_file { checks << :one }
      before_file { nil }
      before_file { checks << :two }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :two, :one, :two, :one, :two]
    end
  end

  describe ".after_parse_file" do
    before do
      Parser::SourceParser.before_parse_file_callbacks.clear
      Parser::SourceParser.after_parse_file_callbacks.clear
    end

    it "handles basic callback support" do
      after_file do |parser|
        expect(parser.contents).to eq 'class Foo; end'
        expect(parser.file).to match(/(foo|bar)\.rb/)
      end
      parse_list ['foo.rb', 'class Foo; end'], ['bar.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
    end

    it "supports multiple callbacks" do
      checks = []
      after_file { checks << :one }
      after_file { checks << :two }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :two, :one, :two, :one, :two]
    end

    it "does not cancel parsing if it returns false" do
      checks = []
      after_file { checks << :one }
      after_file { false }
      after_file { checks << :three }
      parse_list ['file.rb', ''], ['file2.rb', ''], ['file3.rb', 'class Foo; end']
      expect(Registry.at('Foo')).not_to be nil
      expect(checks).to eq [:one, :three, :one, :three, :one, :three]
    end
  end

  describe ".register_parser_type" do
    it_should_behave_like "parser type registration"

    it "registers a subclass of Parser::Base" do
      parser = double(:parser)
      expect(parser).to receive(:parse)
      expect(MyParser).to receive(:new).with('content', '(stdin)').and_return(parser)
      Parser::SourceParser.register_parser_type(:my_parser, MyParser, 'myparser')
      Parser::SourceParser.parse_string('content', :my_parser)
    end

    it "requires class to be a subclass of Parser::Base" do
      expect { Parser::SourceParser.register_parser_type(:my_parser, String) }.to raise_error(ArgumentError)
      expect { Parser::SourceParser.register_parser_type(:my_parser, Parser::Base) }.to raise_error(ArgumentError)
    end
  end

  describe ".parser_type_for_extension" do
    it_should_behave_like "parser type registration"

    it "finds an extension in a registered array of extensions" do
      Parser::SourceParser.register_parser_type(:my_parser, MyParser, ['a', 'b', 'd'])
      expect(Parser::SourceParser.parser_type_for_extension('a')).to eq :my_parser
      expect(Parser::SourceParser.parser_type_for_extension('b')).to eq :my_parser
      expect(Parser::SourceParser.parser_type_for_extension('d')).to eq :my_parser
      expect(Parser::SourceParser.parser_type_for_extension('c')).not_to eq :my_parser
    end

    it "finds an extension in a Regexp" do
      Parser::SourceParser.register_parser_type(:my_parser, MyParser, /abc$/)
      expect(Parser::SourceParser.parser_type_for_extension('dabc')).to eq :my_parser
      expect(Parser::SourceParser.parser_type_for_extension('dabcd')).not_to eq :my_parser
    end

    it "finds an extension in a list of Regexps" do
      Parser::SourceParser.register_parser_type(:my_parser, MyParser, [/ab$/, /abc$/])
      expect(Parser::SourceParser.parser_type_for_extension('dabc')).to eq :my_parser
      expect(Parser::SourceParser.parser_type_for_extension('dabcd')).not_to eq :my_parser
    end

    it "finds an extension in a String" do
      Parser::SourceParser.register_parser_type(:my_parser, MyParser, "abc")
      expect(Parser::SourceParser.parser_type_for_extension('abc')).to eq :my_parser
      expect(Parser::SourceParser.parser_type_for_extension('abcd')).not_to eq :my_parser
    end
  end

  describe "#parse_string" do
    it "parses basic Ruby code" do
      YARD.parse_string(<<-eof)
        module Hello
          class Hi
            # Docstring
            # Docstring2
            def me; "VALUE" end
          end
        end
      eof
      expect(Registry.at(:Hello)).not_to eq nil
      expect(Registry.at("Hello::Hi#me")).not_to eq nil
      expect(Registry.at("Hello::Hi#me").docstring).to eq "Docstring\nDocstring2"
      expect(Registry.at("Hello::Hi#me").docstring.line_range).to eq(3..4)
    end

    it "parses Ruby code with metaclasses" do
      YARD.parse_string(<<-eof)
        module Hello
          class Hi
            class < false, '##' => true}.each do |hash, expected|
        YARD.parse_string "#{hash}\n# Foo bar\nclass Foo; end"
        expect(Registry.at(:Foo).docstring.hash_flag).to eq expected
      end
    end

    it "removes shebang from initial file comments" do
      YARD.parse_string "#!/bin/ruby\n# this is a comment\nclass Foo; end"
      expect(Registry.at(:Foo).docstring).to eq "this is a comment"
    end

    it "removes encoding line from initial file comments" do
      YARD.parse_string "# encoding: utf-8\n# this is a comment\nclass Foo; end"
      expect(Registry.at(:Foo).docstring).to eq "this is a comment"
    end

    it "adds macros on any object" do
      YARD.parse_string <<-eof
        # @!macro [new] foo
        #   This is a macro
        #   @return [String] the string
        class Foo
          # @!macro foo
          def foo; end
        end
      eof

      macro = CodeObjects::MacroObject.find('foo')
      expect(macro.macro_data).to eq "This is a macro\n@return [String] the string"
      expect(Registry.at('Foo').docstring.to_raw).to eq  macro.macro_data
      expect(Registry.at('Foo#foo').docstring.to_raw).to eq macro.macro_data
    end

    it "allows directives parsed on lone comments" do
      YARD.parse_string(<<-eof)
        class Foo
          # @!method foo(a = "hello")
          # @!scope class
          # @!visibility private
          # @param [String] a the name of the foo
          # @return [Symbol] the symbolized foo

          # @!method bar(value)
        end
      eof
      foo = Registry.at('Foo.foo')
      bar = Registry.at('Foo#bar')
      expect(foo).not_to be nil
      expect(foo.visibility).to eq :private
      expect(foo.tag(:param).name).to eq 'a'
      expect(foo.tag(:return).types).to eq ['Symbol']
      expect(bar).not_to be nil
      expect(bar.signature).to eq 'def bar(value)'
    end

    it "parses lone comments at end of blocks" do
      YARD.parse_string(<<-eof)
        class Foo
          none

          # @!method foo(a = "hello")
        end
      eof
      foo = Registry.at('Foo#foo')
      expect(foo).not_to be nil
      expect(foo.signature).to eq 'def foo(a = "hello")'
    end

    it "handles lone comment with no code" do
      YARD.parse_string '# @!method foo(a = "hello")'
      foo = Registry.at('#foo')
      expect(foo).not_to be nil
      expect(foo.signature).to eq 'def foo(a = "hello")'
    end

    it "handles non-ASCII encoding in heredoc" do
      YARD.parse_string <<-eof
        # encoding: utf-8

        heredoc <<-ending
          foo\u{ffe2} bar.
        ending

        # Hello \u{ffe2} world
        class Foo < Bar
          attr_accessor :foo
        end
      eof
      expect(Registry.at('Foo').superclass).to eq P('Bar')
    end
  end

  describe "#parse" do
    it "parses a basic Ruby file" do
      parse_file :example1, __FILE__
      expect(Registry.at(:Hello)).not_to eq nil
      expect(Registry.at("Hello::Hi#me")).not_to eq nil
      expect(Registry.at("Hello::Hi#me").docstring).to eq "Docstring"
    end

    it "parses a set of file globs" do
      expect(Dir).to receive(:[]).with('lib/**/*.rb').and_return([])
      YARD.parse('lib/**/*.rb')
    end

    it "parses a set of absolute paths" do
      expect(Dir).not_to receive(:[])
      expect(File).to receive(:file?).with('/path/to/file').and_return(true)
      expect(File).to receive(:read_binary).with('/path/to/file').and_return("")
      YARD.parse('/path/to/file')
    end

    it "cleans paths before parsing" do
      expect(File).to receive(:open).and_return("")
      parser = Parser::SourceParser.new(:ruby, true)
      parser.parse('a//b//c')
      expect(parser.file).to eq 'a/b/c'
    end

    it "parses files with '*' in them as globs and others as absolute paths" do
      expect(Dir).to receive(:[]).with('*.rb').and_return(['a.rb', 'b.rb'])
      expect(File).to receive(:file?).with('/path/to/file').and_return(true)
      expect(File).to receive(:file?).with('a.rb').and_return(true)
      expect(File).to receive(:file?).with('b.rb').and_return(true)
      expect(File).to receive(:read_binary).with('/path/to/file').and_return("")
      expect(File).to receive(:read_binary).with('a.rb').and_return("")
      expect(File).to receive(:read_binary).with('b.rb').and_return("")
      YARD.parse ['/path/to/file', '*.rb']
    end

    it "converts directories into globs" do
      expect(Dir).to receive(:[]).with('foo/**/*.{rb,c,cc,cxx,cpp}').and_return(['foo/a.rb', 'foo/bar/b.rb'])
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/a.rb').and_return(true)
      expect(File).to receive(:file?).with('foo/bar/b.rb').and_return(true)
      expect(File).to receive(:read_binary).with('foo/a.rb').and_return("")
      expect(File).to receive(:read_binary).with('foo/bar/b.rb').and_return("")
      YARD.parse ['foo']
    end

    it "converts globs into UTF-8" do
      expect(Dir).to receive(:[]).with('lib/**/*.rb').and_return(['lib/é.rb'])
      expect(File).to receive(:file?).with('lib/é.rb').and_return(true)
      expect(File).to receive(:read_binary).with('lib/é.rb').and_return("class A; end")

      YARD.parse ['lib/**/*.rb']
      expect(Registry.at('A')).not_to be nil
    end

    it "uses Registry.checksums cache if file is cached" do
      data = 'DATA'
      hash = Registry.checksum_for(data)
      cmock = double(:cmock)
      expect(cmock).to receive(:[]).with('foo/bar').and_return(hash)
      expect(Registry).to receive(:checksums).and_return(cmock)
      expect(File).to receive(:file?).with('foo/bar').and_return(true)
      expect(File).to receive(:read_binary).with('foo/bar').and_return(data)
      YARD.parse('foo/bar')
    end

    it "supports excluded paths" do
      expect(File).to receive(:file?).with('foo/bar').and_return(true)
      expect(File).to receive(:file?).with('foo/baz').and_return(true)
      expect(File).not_to receive(:read_binary)
      YARD.parse(["foo/bar", "foo/baz"], ["foo", /baz$/])
    end

    it "converts file contents to proper encoding if coding line is present" do
      valid = []
      valid << "# encoding: sjis"
      valid << "# encoding: utf-8"
      valid << "# xxxxxencoding: sjis"
      valid << "# xxxxxencoding: sjis xxxxxx"
      valid << "# ENCODING: sjis"
      valid << "#coDiNG: sjis"
      valid << "# -*- coding: sjis -*-"
      valid << "# -*- coding: utf-8; indent-tabs-mode: nil"
      valid << "### coding: sjis"
      valid << "# encoding=sjis"
      valid << "# encoding:sjis"
      valid << "# encoding   =   sjis"
      valid << "# encoding   ==   sjis"
      valid << "# encoding :  sjis"
      valid << "# encoding ::  sjis"
      valid << "#!/bin/shebang\n# encoding: sjis"
      valid << "#!/bin/shebang\r\n# coding: sjis"
      invalid = []
      invalid << "#\n# encoding: sjis"
      invalid << "#!/bin/shebang\n#\n# encoding: sjis"
      invalid << "# !/bin/shebang\n# encoding: sjis"
      {:to => valid, :not_to => invalid}.each do |msg, list|
        list.each do |src|
          Registry.clear
          parser = Parser::SourceParser.new
          expect(File).to receive(:read_binary).with('tmpfile').and_return(src)
          result = parser.parse("tmpfile")
          if HAVE_RIPPER && YARD.ruby19?
            if msg == :not_to
              default_encoding = 'UTF-8'
              expect(result.enumerator[0].source.encoding.to_s).to eq(default_encoding)
            else
              expect(['Shift_JIS', 'Windows-31J', 'UTF-8']).send(msg,
                include(result.enumerator[0].source.encoding.to_s))
            end
          end
          expect(result.encoding_line).send(msg, eq(src.split("\n").last))
        end
      end
    end

    it "converts C file contents to proper encoding if coding line is present" do
      valid = []
      valid << "/* coding: utf-8 */"
      valid << "/* -*- coding: utf-8; c-file-style: \"ruby\" -*- */"
      valid << "// coding: utf-8"
      valid << "// -*- coding: utf-8; c-file-style: \"ruby\" -*-"
      invalid = []
      {:to => valid, :not_to => invalid}.each do |msg, list|
        list.each do |src|
          Registry.clear
          parser = Parser::SourceParser.new
          expect(File).to receive(:read_binary).with('tmpfile.c').and_return(src)
          result = parser.parse("tmpfile.c")
          content = result.instance_variable_get("@content")
          expect(['UTF-8']).send(msg, include(content.encoding.to_s))
        end
      end
    end if YARD.ruby19?

    Parser::SourceParser::ENCODING_BYTE_ORDER_MARKS.each do |encoding, bom|
      it "understands #{encoding.upcase} BOM" do
        parser = Parser::SourceParser.new
        src = bom + String.new("class FooBar; end").force_encoding('binary')
        src.force_encoding('binary')
        expect(File).to receive(:read_binary).with('tmpfile').and_return(src)
        result = parser.parse('tmpfile')
        expect(Registry.all(:class).first.path).to eq "FooBar"
        expect(result.enumerator[0].source.encoding.to_s.downcase).to eq encoding
      end
    end if HAVE_RIPPER && YARD.ruby19?
  end

  describe "#parse_in_order" do
    def in_order_parse(*files)
      paths = files.map {|f| File.join(File.dirname(__FILE__), 'examples', f.to_s + '.rb.txt') }
      YARD::Parser::SourceParser.parse(paths, [], Logger::DEBUG)
    end

    it "attempts to parse files in order" do
      log.enter_level(Logger::DEBUG) do
        msgs = []
        expect(log).to receive(:debug) {|m| msgs << m }.at_least(:once)
        allow(log).to receive(:<<)
        in_order_parse 'parse_in_order_001', 'parse_in_order_002'
        expect(msgs[1]).to match(/Parsing .+parse_in_order_001.+/)
        expect(msgs[2]).to match(/Missing object MyModule/)
        expect(msgs[3]).to match(/Parsing .+parse_in_order_002.+/)
        expect(msgs[4]).to match(/Re-processing .+parse_in_order_001.+/)
      end
    end

    it "attempts to order files by length for globs (process toplevel files first)" do
      files = %w(a a/b a/b/c)
      files.each do |file|
        expect(File).to receive(:file?).with(file).and_return(true)
        expect(File).to receive(:read_binary).with(file).ordered.and_return('')
      end
      expect(Dir).to receive(:[]).with('a/**/*').and_return(files.reverse)
      YARD.parse 'a/**/*'
    end

    it "allows overriding of length sorting when single file is presented" do
      files = %w(a/b/c a a/b)
      files.each do |file|
        expect(File).to receive(:file?).with(file).at_least(1).times.and_return(true)
        expect(File).to receive(:read_binary).with(file).ordered.and_return('')
      end
      expect(Dir).to receive(:[]).with('a/**/*').and_return(files.reverse)
      YARD.parse ['a/b/c', 'a/**/*']
    end
  end

  describe "#parse_statements" do
    before do
      Registry.clear
    end

    it "displays a warning for invalid parser type" do
      expect(log).to receive(:warn).with(/unrecognized file/)
      expect(log).to receive(:backtrace)
      YARD::Parser::SourceParser.parse_string("int main() { }", :d)
    end

    if HAVE_RIPPER
      it "displays a warning for a syntax error (with new parser)" do
        expect(log).to receive(:warn).with(/Syntax error in/)
        expect(log).to receive(:backtrace)
        YARD::Parser::SourceParser.parse_string("%!!!", :ruby)
      end
    end

    it "handles groups" do
      YARD.parse_string <<-eof
        class A
          # @group Group Name
          def foo; end
          def foo2; end

          # @endgroup

          def bar; end

          # @group Group 2
          def baz; end
        end
      eof

      expect(Registry.at('A').groups).to eq ['Group Name', 'Group 2']
      expect(Registry.at('A#bar').group).to be nil
      expect(Registry.at('A#foo').group).to eq "Group Name"
      expect(Registry.at('A#foo2').group).to eq "Group Name"
      expect(Registry.at('A#baz').group).to eq "Group 2"
    end

    it "handles multi-line class/module references" do
      YARD.parse_string <<-eof
        class A::
          B::C; end
      eof
      expect(Registry.all).to eq [P('A::B::C')]
    end

    it "handles sclass definitions of multi-line class/module references" do
      YARD.parse_string <<-eof
        class << A::
          B::C
          def foo; end
        end
      eof
      expect(Registry.all.size).to eq 2
      expect(Registry.at('A::B::C')).not_to be nil
      expect(Registry.at('A::B::C.foo')).not_to be nil
    end

    it "handles lone comment blocks at the end of a namespace" do
      YARD.parse_string <<-eof
        module A
          class B
            def c; end

            # @!method d
          end
        end
      eof
      expect(Registry.at('A#d')).to be nil
      expect(Registry.at('A::B#d')).not_to be nil
    end

    if YARD.ruby2?
      it "supports named arguments with default values" do
        YARD.parse_string 'def foo(a, b = 1, *c, d, e: 3, **f, &g) end'
        args = [['a', nil], ['b', '1'], ['*c', nil], ['d', nil], ['e:', '3'], ['**f', nil], ['&g', nil]]
        expect(Registry.at('#foo').parameters).to eq(args)
      end
    end

    if NAMED_OPTIONAL_ARGUMENTS && !LEGACY_PARSER
      it "supports named arguments without default values" do
        YARD.parse_string 'def foo(a, b = 1, *c, d, e: 3, f:, **g, &h) end'
        args = [['a', nil], ['b', '1'], ['*c', nil], ['d', nil], ['e:', '3'], ['f:', nil], ['**g', nil], ['&h', nil]]
        expect(Registry.at('#foo').parameters).to eq(args)
      end
    end
  end
end
yard-0.9.37/spec/parser/tag_parsing_spec.rb000066400000000000000000000007301466601756300206520ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Parser, "tag handling" do
  before { parse_file :tag_handler_001, __FILE__ }

  it "knows the list of all available tags" do
    expect(P("Foo#foo").tags).to include(P("Foo#foo").tag(:api))
  end

  it "knows the text of tags on a method" do
    expect(P("Foo#foo").tag(:api).text).to eq "public"
  end

  it "returns true when asked whether a tag exists" do
    expect(P("Foo#foo").has_tag?(:api)).to be true
  end
end
yard-0.9.37/spec/rake/000077500000000000000000000000001466601756300144435ustar00rootroot00000000000000yard-0.9.37/spec/rake/yardoc_task_spec.rb000066400000000000000000000061301466601756300203050ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Rake::YardocTask do
  before do
    @yardoc = YARD::CLI::Yardoc.new
    @yardoc.statistics = false
    @yardoc.use_document_file = false
    @yardoc.use_yardopts_file = false
    @yardoc.generate = false
    allow(Templates::Engine).to receive(:render)
    allow(Templates::Engine).to receive(:generate)
    allow(YARD).to receive(:parse)
    allow(Registry).to receive(:load)
    allow(Registry).to receive(:save)
    allow(YARD::CLI::Yardoc).to receive(:new).and_return(@yardoc)
    ::Rake.application.clear
  end

  def run
    ::Rake.application.tasks[0].invoke
  end

  describe "#initialize" do
    it "allows separate rake task name to be set" do
      YARD::Rake::YardocTask.new(:notyardoc)
      expect(::Rake.application.tasks[0].name).to eq "notyardoc"
    end
  end

  describe "#files" do
    it "allows files to be set" do
      YARD::Rake::YardocTask.new do |t|
        t.files = ['a', 'b', 'c']
      end
      run
      expect(@yardoc.files).to eq %w(a b c)
    end
  end

  describe "#options" do
    it "allows extra options to be set" do
      YARD::Rake::YardocTask.new do |t|
        t.options = ['--private', '--protected']
      end
      run
      expect(@yardoc.visibilities).to eq [:public, :private, :protected]
    end

    it "allows --api and --no-api" do
      YARD::Rake::YardocTask.new do |t|
        t.options = %w(--api public --no-api)
      end
      run
      expect(@yardoc.options.verifier.expressions).to include('["public"].include?(@api.text) || !@api')
    end
  end

  describe "#stats_options" do
    before do
      @yard_stats = Object.new
      allow(@yard_stats).to receive(:run)
      allow(YARD::CLI::Stats).to receive(:new).and_return(@yard_stats)
    end

    it "invokes stats" do
      expect(@yard_stats).to receive(:run).with('--list-undoc', '--use-cache')
      @yardoc.statistics = true
      YARD::Rake::YardocTask.new do |t|
        t.stats_options = %w(--list-undoc)
      end
      run
      expect(@yardoc.statistics).to be false
    end
  end

  describe "#before" do
    it "allows before callback" do
      proc = lambda {}
      expect(proc).to receive(:call)
      expect(@yardoc).to receive(:run)
      YARD::Rake::YardocTask.new {|t| t.before = proc }
      run
    end
  end

  describe "#after" do
    it "allows after callback" do
      proc = lambda {}
      expect(proc).to receive(:call)
      expect(@yardoc).to receive(:run)
      YARD::Rake::YardocTask.new {|t| t.after = proc }
      run
    end
  end

  describe "#verifier" do
    it "allows a verifier proc to be set" do
      verifier = Verifier.new
      expect(@yardoc).to receive(:run) do
        expect(@yardoc.options[:verifier]).to eq verifier
      end
      YARD::Rake::YardocTask.new {|t| t.verifier = verifier }
      run
    end

    it "overrides --query options" do
      verifier = Verifier.new
      expect(@yardoc).to receive(:run) do
        expect(@yardoc.options[:verifier]).to eq verifier
      end
      YARD::Rake::YardocTask.new do |t|
        t.options += ['--query', '@return']
        t.verifier = verifier
      end
      run
    end
  end
end
yard-0.9.37/spec/registry_resolver_spec.rb000066400000000000000000000007541466601756300206570ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::RegistryResolver do
  include YARD::CodeObjects::NamespaceMapper

  describe '#starts_with_separator_match' do
    subject { RegistryResolver.new }

    it 'should clear cache when a namespace separator is registered' do
      expect(subject.send(:starts_with_separator_match).to_s).not_to include('!')
      register_separator '!', :test_type
      expect(subject.send(:starts_with_separator_match).to_s).to include('!')
    end
  end
end
yard-0.9.37/spec/registry_spec.rb000066400000000000000000000421641466601756300167370ustar00rootroot00000000000000# frozen_string_literal: true
include CodeObjects

require "thread"

RSpec.describe YARD::Registry do
  before { Registry.clear }

  describe ".yardoc_file_for_gem" do
    before do
      @gem = double('gem')
      allow(@gem).to receive(:name).and_return('foo')
      allow(@gem).to receive(:full_name).and_return('foo-1.0')
      allow(@gem).to receive(:full_gem_path).and_return('/path/to/foo')
      allow(@gem).to receive(:doc_dir).and_return('/path/to/foo/doc')
      allow(@gem).to receive(:doc_dir).with('.yardoc').and_return('/path/to/foo/doc/.yardoc')
    end

    it "returns nil if gem isn't found" do
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([])
      expect(Registry.yardoc_file_for_gem('foo')).to eq nil
    end

    it "allows version to be specified" do
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '= 2').and_return([])
      expect(Registry.yardoc_file_for_gem('foo', '= 2')).to eq nil
    end

    it "returns existing .yardoc path for gem when for_writing=false" do
      allow(File).to receive(:exist?).twice.and_return(false)
      allow(File).to receive(:exist?).with('/path/to/foo/.yardoc').and_return(true)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo')).to eq '/path/to/foo/.yardoc'
    end

    it "returns new existing .yardoc path for gem when for_writing=false" do
      allow(File).to receive(:exist?).and_return(false)
      allow(File).to receive(:exist?).with('/path/to/foo/doc/.yardoc').and_return(true)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo')).to eq '/path/to/foo/doc/.yardoc'
    end

    it "returns nil if no .yardoc path exists in gem when for_writing=false" do
      allow(File).to receive(:exist?).twice.and_return(false)
      allow(File).to receive(:exist?).with('/path/to/foo/.yardoc').and_return(false)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo')).to eq nil
    end

    it "searches local gem path first if for_writing=false" do
      allow(File).to receive(:exist?).and_return(true)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo')).to match %r{/.yard/gem_index/foo-1.0.yardoc$}
    end

    it "returns global .yardoc path for gem if for_writing=true and dir is writable" do
      allow(File).to receive(:exist?).and_return(false)
      allow(File).to receive(:directory?).with(@gem.doc_dir).and_return(true)
      allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
      allow(File).to receive(:writable?).with(@gem.full_gem_path).and_return(true)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/.yardoc'
    end

    it "returns new global .yardoc path for gem if for_writing=true and dir is writable" do
      allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(true)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/doc/.yardoc'
    end

    it "returns new global .yardoc path for gem if for_writing=true and parent dir is writable (but dir does not exist)" do
      allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
      allow(File).to receive(:directory?).with(@gem.doc_dir).and_return(false)
      allow(File).to receive(:writable?).with(File.dirname(@gem.doc_dir)).and_return(true)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to eq '/path/to/foo/doc/.yardoc'
    end

    it "returns local .yardoc path for gem if for_writing=true and dir is not writable" do
      allow(File).to receive(:writable?).with(@gem.doc_dir).and_return(false)
      allow(File).to receive(:writable?).with(@gem.full_gem_path).and_return(false)
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('foo', '>= 0').and_return([@gem])
      expect(Registry.yardoc_file_for_gem('foo', '>= 0', true)).to match %r{/.yard/gem_index/foo-1.0.yardoc$}
    end

    it "returns gem path if gem starts with yard-doc- and for_writing=false" do
      allow(@gem).to receive(:name).and_return('yard-doc-core')
      allow(@gem).to receive(:full_name).and_return('yard-doc-core-1.0')
      allow(@gem).to receive(:full_gem_path).and_return('/path/to/yard-doc-core')
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('yard-doc-core', '>= 0').and_return([@gem])
      allow(File).to receive(:exist?).with('/path/to/yard-doc-core/.yardoc').and_return(true)
      expect(Registry.yardoc_file_for_gem('yard-doc-core')).to eq '/path/to/yard-doc-core/.yardoc'
    end

    it "returns nil if gem starts with yard-doc- and for_writing=true" do
      allow(@gem).to receive(:name).and_return('yard-doc-core')
      allow(@gem).to receive(:full_name).and_return('yard-doc-core-1.0')
      allow(@gem).to receive(:full_gem_path).and_return('/path/to/yard-doc-core')
      allow(YARD::GemIndex).to receive(:find_all_by_name).with('yard-doc-core', '>= 0').and_return([@gem])
      allow(File).to receive(:exist?).with('/path/to/yard-doc-core/.yardoc').and_return(true)
      expect(Registry.yardoc_file_for_gem('yard-doc-core', '>= 0', true)).to eq nil
    end
  end

  describe ".root" do
    it "has an empty path for root" do
      expect(Registry.root.path).to eq ""
    end
  end

  describe ".locale" do
    it "loads locale object" do
      fr_locale = I18n::Locale.new("fr")
      store = Registry.send(:thread_local_store)
      expect(store).to receive(:locale).with("fr").and_return(fr_locale)
      expect(Registry.locale("fr")).to eq fr_locale
    end
  end

  describe ".resolve" do
    it "resolves any existing namespace" do
      o1 = ModuleObject.new(:root, :A)
      o2 = ModuleObject.new(o1, :B)
      o3 = ModuleObject.new(o2, :C)
      expect(Registry.resolve(o1, "B::C")).to eq o3
      Registry.resolve(:root, "A::B::C")
    end

    it "resolves an object in the root namespace when prefixed with ::" do
      o1 = ModuleObject.new(:root, :A)
      o2 = ModuleObject.new(o1, :B)
      o3 = ModuleObject.new(o2, :C)
      expect(Registry.resolve(o3, "::A")).to eq o1

      expect(Registry.resolve(o3, "::String", false, true)).to eq P(:String)
    end

    it "resolves instance methods with # prefix" do
      o1 = ModuleObject.new(:root, :A)
      o2 = ModuleObject.new(o1, :B)
      o3 = ModuleObject.new(o2, :C)
      o4 = MethodObject.new(o3, :methname)
      expect(Registry.resolve(o1, "B::C#methname")).to eq o4
      expect(Registry.resolve(o2, "C#methname")).to eq o4
      expect(Registry.resolve(o3, "#methname")).to eq o4
    end

    it "resolves instance methods in the root without # prefix" do
      o = MethodObject.new(:root, :methname)
      expect(Registry.resolve(:root, 'methname')).to eq o
    end

    it "does lexical lookup on the initial namespace" do
      YARD.parse_string <<-eof
        module A
          module B; module C; end end
          module D; module E; end end
        end
      eof

      d = Registry.at('A::B::C')
      expect(Registry.resolve(d, 'D::E')).to eq Registry.at('A::D::E')
    end

    it "resolves superclass methods when inheritance = true" do
      superyard = ClassObject.new(:root, :SuperYard)
      yard = ClassObject.new(:root, :YARD)
      yard.superclass = superyard
      imeth = MethodObject.new(superyard, :hello)
      cmeth = MethodObject.new(superyard, :class_hello, :class)

      expect(Registry.resolve(yard, "#hello", false)).to be nil
      expect(Registry.resolve(yard, "#hello", true)).to eq imeth
      expect(Registry.resolve(yard, "class_hello", false)).to be nil
      expect(Registry.resolve(yard, "class_hello", true)).to eq cmeth
    end

    it "does not look at superclass proxies when inheritance = true" do
      YARD.parse_string "class A::B; end"
      expect(Registry.resolve(Registry.at('A::B'), "#bar", true)).to eq nil
    end

    it "resolves mixin methods when inheritance = true" do
      yard = ClassObject.new(:root, :YARD)
      mixin = ModuleObject.new(:root, :Mixin)
      yard.mixins(:instance) << mixin
      imeth = MethodObject.new(mixin, :hello)
      cmeth = MethodObject.new(mixin, :class_hello, :class)

      expect(Registry.resolve(yard, "#hello", false)).to be nil
      expect(Registry.resolve(yard, "#hello", true)).to eq imeth
      expect(Registry.resolve(yard, "class_hello", false)).to be nil
      expect(Registry.resolve(yard, "class_hello", true)).to eq cmeth
    end

    it "resolves methods in Object when inheritance = true" do
      YARD.parse_string <<-eof
        class Object; def foo; end end
        class A; end
        class MyObject < A; end
      eof

      expect(Registry.resolve(P('MyObject'), '#foo', true)).to eq P('Object#foo')
    end

    it "resolves methods in BasicObject when inheritance = true" do
      YARD.parse_string <<-eof
        class BasicObject; def foo; end end
        class A; end
        class MyObject < A; end
      eof

      expect(Registry.resolve(P('MyObject'), '#foo', true)).to eq P('BasicObject#foo')
    end

    it "does not perform lexical lookup to resolve a method object by more than one namespace" do
      YARD.parse_string <<-eof
        module A
          def foo; end
          def self.bar; end
          module B; module C; end end
        end
      eof

      expect(Registry.resolve(P('A::B::C'), '#foo', true)).to be nil
      expect(Registry.resolve(P('A::B::C'), '.bar', true)).to be nil
      expect(Registry.resolve(P('A::B'), '#foo', true)).not_to be nil
      expect(Registry.resolve(P('A::B'), '.bar', true)).not_to be nil
    end

    it "does not resolve methods in Object if inheriting BasicObject when inheritance = true" do
      YARD.parse_string <<-eof
        class Object; def foo; end end
        class MyObject < BasicObject; end
      eof

      expect(Registry.resolve(P('MyObject'), '#foo', true)).to be nil
    end

    it "performs lookups on each individual namespace when inheritance = true" do
      YARD.parse_string <<-eof
        module A
          module B; include A::D end
          module C; extend A::D end
          module D; def bar; end end
        end
      eof

      r = Registry.root
      expect(Registry.resolve(r, 'A::B#bar', true)).to eq Registry.at('A::D#bar')
      expect(Registry.resolve(r, 'A::C.bar', true)).to eq Registry.at('A::D#bar')
    end

    it "allows type=:typename to ensure resolved object is of a certain type" do
      YARD.parse_string "class Foo; end"
      expect(Registry.resolve(Registry.root, 'Foo')).to eq Registry.at('Foo')
      expect(Registry.resolve(Registry.root, 'Foo', false, false, :method)).to be nil
    end

    it "allows keep trying to find obj where type equals object type" do
      YARD.parse_string <<-eof
        module Foo
          class Bar; end
          def self.Bar; end
        end
      eof
      expect(Registry.resolve(P('Foo'), 'Bar', false, false, :class)).to eq Registry.at('Foo::Bar')
      expect(Registry.resolve(P('Foo'), 'Bar', false, false, :method)).to eq(
        Registry.at('Foo.Bar')
      )
    end

    it "returns proxy fallback with given type if supplied" do
      YARD.parse_string "module Foo; end"
      proxy = Registry.resolve(P('Foo'), 'Bar', false, true, :method)
      expect(proxy.type).to eq :method
      proxy = Registry.resolve(P('Qux'), 'Bar', false, true, :method)
      expect(proxy.type).to eq :method
    end

    it "does not return proxy on original namespace if path is anchored to root" do
      YARD.parse_string "module Foo; class Bar; def baz; end end end"
      proxy = Registry.resolve(P('Foo::Bar#baz'), '::Bar', true, true)
      expect(proxy.path).to eq('Bar')
      expect(proxy.namespace).to equal(Registry.root)
      expect(proxy.type).to eq(:proxy)
    end

    it "only checks 'Path' in lookup on root namespace" do
      expect(Registry).to receive(:at).once.with('Test').and_return(true)
      Registry.resolve(Registry.root, "Test")
    end

    it "does not perform lookup by joining namespace and name without separator" do
      yard = ClassObject.new(:root, :YARD)
      expect(Registry).not_to receive(:at).with('YARDB')
      Registry.resolve(yard, 'B')
    end
  end

  describe ".all" do
    it "returns objects of types specified by arguments" do
      ModuleObject.new(:root, :A)
      o1 = ClassObject.new(:root, :B)
      o2 = MethodObject.new(:root, :testing)
      r = Registry.all(:method, :class)
      expect(r).to include(o1, o2)
    end

    it "returns code objects" do
      o1 = ModuleObject.new(:root, :A)
      o2 = ClassObject.new(:root, :B)
      MethodObject.new(:root, :testing)
      r = Registry.all.select {|t| NamespaceObject === t }
      expect(r).to include(o1, o2)
    end

    it "allows .all to omit list" do
      o1 = ModuleObject.new(:root, :A)
      o2 = ClassObject.new(:root, :B)
      r = Registry.all
      expect(r).to include(o1, o2)
    end
  end

  describe ".paths" do
    it "returns all object paths" do
      ModuleObject.new(:root, :A)
      ClassObject.new(:root, :B)
      expect(Registry.paths).to include('A', 'B')
    end
  end

  describe ".load_yardoc" do
    it "delegates load to RegistryStore" do
      store = RegistryStore.new
      expect(store).to receive(:load).with('foo')
      expect(RegistryStore).to receive(:new).and_return(store)
      Registry.yardoc_file = 'foo'
      Registry.load_yardoc
    end

    it "returns itself" do
      expect(Registry.load_yardoc).to eq Registry
    end

    it "maintains hash key equality on loaded objects" do
      Registry.clear
      Registry.load!(File.dirname(__FILE__) + '/serializers/data/serialized_yardoc')
      baz = Registry.at('Foo#baz')
      expect(Registry.at('Foo').aliases.keys).to include(baz)
      expect(Registry.at('Foo').aliases.key?(baz)).to be true
    end
  end

  ['load', 'load_all', 'load!'].each do |meth|
    describe('.' + meth) do
      it "returns itself" do
        expect(Registry.send(meth)).to eq Registry
      end
    end
  end

  describe ".each" do
    before do
      YARD.parse_string "def a; end; def b; end; def c; end"
    end

    after { Registry.clear }

    it "iterates over .all" do
      items = []
      Registry.each {|x| items << x.path }
      expect(items.sort).to eq ['#a', '#b', '#c']
    end

    it "includes Enumerable and allow for find, select" do
      expect(Registry.find {|x| x.path == "#a" }).to be_a(CodeObjects::MethodObject)
    end
  end

  describe ".instance" do
    it "returns itself" do
      expect(Registry.instance).to eq Registry
    end
  end

  describe ".single_object_db" do
    it "defaults to nil" do
      expect(Registry.single_object_db).to eq nil
      Thread.new { expect(Registry.single_object_db).to eq nil }.join
    end
  end

  describe "Thread local" do
    it "maintains two Registries in separate threads" do
      barrier = 0
      mutex   = Mutex.new
      threads = []
      threads << Thread.new do
        Registry.clear
        YARD.parse_string "# docstring 1\nclass Foo; end"
        mutex.synchronize { barrier += 1 }
        "barrier < 2, spinning" while barrier < 2
        expect(Registry.at('Foo').docstring).to eq "docstring 1"
      end
      threads << Thread.new do
        Registry.clear
        YARD.parse_string "# docstring 2\nclass Foo; end"
        mutex.synchronize { barrier += 1 }
        "barrier < 2, spinning" while barrier < 2
        expect(Registry.at('Foo').docstring).to eq "docstring 2"
      end
      threads.each(&:join)
    end

    it "allows setting of yardoc_file in separate threads" do
      barrier = 0
      mutex   = Mutex.new
      threads = []
      threads << Thread.new do
        expect(Registry.yardoc_file).to eq '.yardoc'
        Registry.yardoc_file = 'foo'
        mutex.synchronize { barrier += 1 }
        "barrier = 1, spinning" while barrier == 1
        expect(Registry.yardoc_file).to eq 'foo'
      end
      threads << Thread.new do
        "barrier = 0, spinning" while barrier == 0
        expect(Registry.yardoc_file).to eq '.yardoc'
        mutex.synchronize { barrier += 1 }
        Registry.yardoc_file = 'foo2'
      end
      threads.each(&:join)
      Registry.yardoc_file = Registry::DEFAULT_YARDOC_FILE
    end

    it "automatically clears in new threads" do
      Thread.new { expect(Registry.all).to be_empty }.join
    end

    it "allows setting of po_dir in separate threads" do
      barrier = 0
      mutex   = Mutex.new
      threads = []
      threads << Thread.new do
        expect(Registry.po_dir).to eq 'po'
        Registry.po_dir = 'locale'
        mutex.synchronize { barrier += 1 }
        "barrier = 1, spinning" while barrier == 1
        expect(Registry.po_dir).to eq 'locale'
      end
      threads << Thread.new do
        "barrier = 0, spinning" while barrier == 0
        expect(Registry.po_dir).to eq 'po'
        mutex.synchronize { barrier += 1 }
        Registry.po_dir = '.'
      end
      threads.each(&:join)
      Registry.po_dir = Registry::DEFAULT_PO_DIR
    end
  end
end
yard-0.9.37/spec/registry_store_spec.rb000066400000000000000000000313001466601756300201410ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::RegistryStore do
  before do
    FileUtils.rm_rf("foo")
    @store = RegistryStore.new
    @serializer = Serializers::YardocSerializer.new('foo')
    @foo = CodeObjects::MethodObject.new(nil, :foo)
    @bar = CodeObjects::ClassObject.new(nil, :Bar)
    allow(Serializers::YardocSerializer).to receive(:new).and_return(@serializer)
  end

  describe "#load" do
    it "loads root.dat as full object list if it is a Hash" do
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/checksums').and_return(false)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(@serializer).to receive(:deserialize).with('root').and_return(:root => @foo, :A => @bar)
      expect(@store.load('foo')).to be true
      expect(@store.root).to eq @foo
      expect(@store.get('A')).to eq @bar
    end

    it "loads old yardoc format if .yardoc is a file" do
      expect(File).to receive(:directory?).with('foo').and_return(false)
      expect(File).to receive(:file?).with('foo').and_return(true)
      expect(File).to receive(:read_binary).with('foo').and_return('FOO')
      expect(Marshal).to receive(:load).with('FOO')

      @store.load('foo')
    end

    it "loads new yardoc format if .yardoc is a directory" do
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/checksums').and_return(false)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)

      expect(@store.load('foo')).to be true
    end

    it "returns true if .yardoc is loaded (file)" do
      expect(File).to receive(:directory?).with('myyardoc').and_return(false)
      expect(File).to receive(:file?).with('myyardoc').and_return(true)
      expect(File).to receive(:read_binary).with('myyardoc').and_return(Marshal.dump(''))
      expect(@store.load('myyardoc')).to be true
    end

    it "returns true if .yardoc is loaded (directory)" do
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/checksums').and_return(false)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
      expect(@store.load('foo')).to be true
    end

    it "returns false if .yardoc does not exist" do
      expect(@store.load('NONEXIST')).to be false
    end

    it "returns false if there is no file to load" do
      expect(@store.load(nil)).to be false
    end

    it "loads checksums if they exist" do
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/checksums').and_return(true)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
      expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(File).to receive(:readlines).with('foo/checksums').and_return([
        'file1 CHECKSUM1', '  file2 CHECKSUM2 '
      ])
      expect(@store.load('foo')).to be true
      expect(@store.checksums).to eq('file1' => 'CHECKSUM1', 'file2' => 'CHECKSUM2')
    end

    it "loads proxy_types if they exist" do
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/checksums').and_return(false)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(true)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
      expect(File).to receive(:read_binary).with('foo/proxy_types').and_return(Marshal.dump('a' => 'b'))
      expect(@store.load('foo')).to be true
      expect(@store.proxy_types).to eq('a' => 'b')
    end

    it "loads root object if it exists" do
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/checksums').and_return(false)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(true)
      expect(File).to receive(:read_binary).with('foo/objects/root.dat').and_return(Marshal.dump(@foo))
      expect(@store.load('foo')).to be true
      expect(@store.root).to eq @foo
    end
  end

  describe "#save" do
    before do
      allow(@store).to receive(:write_proxy_types)
      allow(@store).to receive(:write_checksums)
      allow(@store).to receive(:destroy)
    end

    after do
      Registry.single_object_db = nil
    end

    def saves_to_singledb
      expect(@serializer).to receive(:serialize).once.with(instance_of(Hash))
      @store.save(true, 'foo')
    end

    def add_items(n)
      n.times {|i| @store[i.to_s] = @foo }
    end

    def saves_to_multidb
      times = @store.keys.size
      expect(@serializer).to receive(:serialize).exactly(times).times
      @store.save(true, 'foo')
      @last = times
    end

    it "saves as single object db if single_object_db is nil and there are less than 3000 objects" do
      Registry.single_object_db = nil
      add_items(100)
      saves_to_singledb
      expect(@serializer.complete?).to eq true
    end

    it "saves as single object db if single_object_db is nil and there are more than 3000 objects" do
      Registry.single_object_db = nil
      add_items(5000)
      saves_to_singledb
    end

    it "saves as single object db if single_object_db is true (and any amount of objects)" do
      Registry.single_object_db = true
      add_items(100)
      saves_to_singledb
      add_items(5000)
      saves_to_singledb
    end

    it "never saves as single object db if single_object_db is false" do
      Registry.single_object_db = false
      add_items(100)
      saves_to_multidb
      add_items(5000)
      saves_to_multidb
    end
  end

  describe "#put" do
    it "assigns values" do
      @store.put(:YARD, @foo)
      expect(@store.get(:YARD)).to eq @foo
    end

    it "treats '' as root" do
      @store.put('', @foo)
      expect(@store.get(:root)).to eq @foo
    end
  end

  describe "#get" do
    it "hits cache if object exists" do
      @store.put(:YARD, @foo)
      expect(@store.get(:YARD)).to eq @foo
    end

    it "hits backstore on cache miss and cache is not fully loaded" do
      serializer = double(:serializer)
      expect(serializer).to receive(:deserialize).once.with(:YARD).and_return(@foo)
      @store.load('foo')
      @store.instance_variable_set("@loaded_objects", 0)
      @store.instance_variable_set("@available_objects", 100)
      @store.instance_variable_set("@serializer", serializer)
      expect(@store.get(:YARD)).to eq @foo
      expect(@store.get(:YARD)).to eq @foo
      expect(@store.instance_variable_get("@loaded_objects")).to eq 1
    end
  end

  [:keys, :values].each do |item|
    describe "##{item}" do
      it "loads entire database if reload=true" do
        expect(File).to receive(:directory?).with('foo').and_return(true)
        @store.load('foo')
        expect(@store).to receive(:load_all)
        @store.send(item, true)
      end

      it "does not load entire database if reload=false" do
        expect(File).to receive(:directory?).with('foo').and_return(true)
        @store.load('foo')
        expect(@store).not_to receive(:load_all)
        @store.send(item, false)
      end
    end
  end

  describe "#paths_for_type" do
    after { Registry.clear }

    it "sets all object types if not set by object_types" do
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/checksums').and_return(false)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(@serializer).to receive(:deserialize).with('root').and_return(:'A#foo' => @foo, :A => @bar)
      @store.load('foo')
      expect(@store.paths_for_type(:method)).to eq ['#foo']
      expect(@store.paths_for_type(:class)).to eq ['Bar']
    end

    it "keeps track of types when assigning values" do
      @store.put(:abc, @foo)
      expect(@store.paths_for_type(@foo.type)).to eq ['abc']
    end

    it "reassigns path if type changes" do
      foo = CodeObjects::ClassObject.new(:root, :Foo)
      @store.put('Foo', foo)
      expect(@store.get('Foo').type).to eq :class
      expect(@store.paths_for_type(:class)).to eq ["Foo"]
      foo = CodeObjects::ModuleObject.new(:root, :Foo)
      @store.put('Foo', foo)
      expect(@store.get('Foo').type).to eq :module
      expect(@store.paths_for_type(:class)).to eq []
      expect(@store.paths_for_type(:module)).to eq ["Foo"]
    end
  end

  describe "#values_for_type" do
    it "returns all objects with type" do
      @store.put(:abc, @foo)
      expect(@store.values_for_type(@foo.type)).to eq [@foo]
    end
  end

  describe "#load_all" do
    it "loads the entire database" do
      foomock = double(:Foo)
      barmock = double(:Bar)
      allow(foomock).to receive(:type).and_return(:class)
      allow(barmock).to receive(:type).and_return(:class)
      expect(foomock).to receive(:path).and_return('Foo')
      expect(barmock).to receive(:path).and_return('Bar')
      expect(File).to receive(:directory?).with('foo').and_return(true)
      expect(File).to receive(:file?).with('foo/proxy_types').and_return(false)
      expect(File).to receive(:file?).with('foo/object_types').and_return(false)
      expect(File).to receive(:file?).with('foo/checksums').and_return(false)
      expect(File).to receive(:file?).with('foo/objects/root.dat').and_return(false)
      expect(@store).to receive(:all_disk_objects).at_least(1).times.and_return(['foo/objects/foo', 'foo/objects/bar'])
      @store.load('foo')
      serializer = @store.instance_variable_get("@serializer")
      expect(serializer).to receive(:deserialize).with('foo/objects/foo', true).and_return(foomock)
      expect(serializer).to receive(:deserialize).with('foo/objects/bar', true).and_return(barmock)
      @store.send(:load_all)
      expect(@store.instance_variable_get("@available_objects")).to eq 2
      expect(@store.instance_variable_get("@loaded_objects")).to eq 2
      expect(@store[:Foo]).to eq foomock
      expect(@store[:Bar]).to eq barmock
    end
  end

  describe "#destroy" do
    it "destroys file ending in .yardoc when force=false" do
      expect(File).to receive(:file?).with('foo.yardoc').and_return(true)
      expect(File).to receive(:unlink).with('foo.yardoc')
      @store.instance_variable_set("@file", 'foo.yardoc')
      expect(@store.destroy).to be true
    end

    it "destroys dir ending in .yardoc when force=false" do
      expect(File).to receive(:directory?).with('foo.yardoc').and_return(true)
      expect(FileUtils).to receive(:rm_rf).with('foo.yardoc')
      @store.instance_variable_set("@file", 'foo.yardoc')
      expect(@store.destroy).to be true
    end

    it "does not destroy file/dir not ending in .yardoc when force=false" do
      expect(File).not_to receive(:file?).with('foo')
      expect(File).not_to receive(:directory?).with('foo')
      expect(File).not_to receive(:unlink).with('foo')
      expect(FileUtils).not_to receive(:rm_rf).with('foo')
      @store.instance_variable_set("@file", 'foo')
      expect(@store.destroy).to be false
    end

    it "destroys any file/dir when force=true" do
      expect(File).to receive(:file?).with('foo').and_return(true)
      expect(File).to receive(:unlink).with('foo')
      @store.instance_variable_set("@file", 'foo')
      expect(@store.destroy(true)).to be true
    end
  end

  describe "#delete" do
    it "deletes the given object from store" do
      @store.put(:YARD, @foo)
      expect(@store.get(:YARD)).to be @foo
      expect(@store.paths_for_type(:method)).to eq ["YARD"]
      @store.delete(:YARD)
      expect(@store.get(:YARD)).to be nil
      expect(@store.paths_for_type(:method)).to eq []
    end
  end

  describe "#locale" do
    it "loads ./po/LOCALE_NAME.po" do
      fr_locale = I18n::Locale.new("fr")
      expect(I18n::Locale).to receive(:new).with("fr").and_return(fr_locale)
      expect(Registry).to receive(:po_dir).and_return("po")
      expect(fr_locale).to receive(:load).with("po")
      expect(@store.locale("fr")).to eq fr_locale
    end
  end
end
yard-0.9.37/spec/rubygems/000077500000000000000000000000001466601756300153565ustar00rootroot00000000000000yard-0.9.37/spec/rubygems/doc_manager_spec.rb000066400000000000000000000073441466601756300211640ustar00rootroot00000000000000# frozen_string_literal: true
require File.join(YARD::ROOT, 'rubygems_plugin')
require 'fileutils'

RSpec.describe Gem::DocManager do
  before do
    # Ensure filesystem integrity
    allow(FileUtils).to receive(:mkdir_p)
    allow(FileUtils).to receive(:rm_rf)
    allow(Dir).to receive(:chdir)

    allow(YARD::CLI::Yardoc).to receive(:run)

    @spec_file = File.join(YARD::ROOT, '..', 'yard.gemspec')
    @spec = Gem::SourceIndex.load_specification(@spec_file)
    @spec.has_yardoc = false # no yardoc docs for now
    @yardopts = File.join(@spec.full_gem_path, '.yardopts')
    @doc = Gem::DocManager.new(@spec)
    allow(@doc).to receive(:install_ri_yard_orig)
    allow(@doc).to receive(:install_rdoc_yard_orig)
  end

  def runs; expect(YARD::CLI::Yardoc).to receive(:run) end

  describe ".load_yardoc" do
    it "properly loads YARD" do
      expect(Gem::DocManager).to receive(:require) do |path|
        expect(File.expand_path(path)).to eq YARD::ROOT + '/yard'
      end
      Gem::DocManager.load_yardoc
    end
  end

  describe "#install_ri_yard" do
    def install
      msg = "Building YARD (yri) index for #{@spec.full_name}..."
      expect(@doc).to receive(:say).with(msg)
      @doc.install_ri_yard
    end

    it "passes --quiet to all documentation" do
      runs.with('-c', '-n', '--quiet', 'lib')
      install
    end

    it "passes extra_rdoc_files to documentation" do
      @spec.extra_rdoc_files = %w(README LICENSE)
      runs.with('-c', '-n', '--quiet', 'lib', '-', 'README', 'LICENSE')
      install
    end

    it "adds --backtrace if Gem.configuration.backtrace" do
      Gem.configuration.backtrace = true
      runs.with('-c', '-n', '--quiet', '--backtrace', 'lib')
      install
      Gem.configuration.backtrace = false
    end

    it "adds require_paths if there is no .yardopts" do
      expect(File).to receive(:file?).with(@yardopts).and_return(true)
      runs.with('-c', '-n', '--quiet')
      install
    end

    it "adds extra_rdoc_files if there is no .yardopts" do
      @spec.extra_rdoc_files = %w(README LICENSE)
      expect(File).to receive(:file?).with(@yardopts).and_return(true)
      runs.with('-c', '-n', '--quiet')
      install
    end

    it "switches to directory before running command" do
      old = Dir.pwd
      expect(Dir).to receive(:chdir).with(@spec.full_gem_path)
      expect(Dir).to receive(:chdir).with(old)
      install
    end

    it "ensures that directory is switched back at end of command in failure" do
      old = Dir.pwd
      expect(Dir).to receive(:chdir).with(@spec.full_gem_path)
      expect(Dir).to receive(:chdir).with(old)
      expect(@doc.ui.errs).to receive(:puts).with(/ERROR:\s*While generating documentation/)
      expect(@doc.ui.errs).to receive(:puts).with(/MESSAGE:\s*foo/)
      expect(@doc.ui.errs).to receive(:puts).with(/YARDOC args:\s*-c -n --quiet lib/)
      expect(@doc.ui.errs).to receive(:puts).with("(continuing with the rest of the installation)")
      expect(YARD::CLI::Yardoc).to receive(:run).and_raise(RuntimeError.new("foo"))
      install
    end

    it "handles permission errors" do
      expect(YARD::CLI::Yardoc).to receive(:run).and_raise(Errno::EACCES.new("- dir"))
      expect { install }.to raise_error(Gem::FilePermissionError)
    end
  end

  describe "#install_rdoc_yard" do
    def install
      msg = "Installing YARD documentation for #{@spec.full_name}..."
      expect(@doc).to receive(:say).with(msg)
      @doc.install_rdoc_yard
    end

    it "adds -o outdir when generating docs" do
      expect(File).to receive(:file?).with(@yardopts).and_return(true)
      @spec.has_yardoc = true
      doc_dir = File.join(@doc.instance_variable_get("@doc_dir"), 'rdoc')
      runs.with('-o', doc_dir, '--quiet')
      install
    end
  end
end if Gem::VERSION < '2.0.0'
yard-0.9.37/spec/serializers/000077500000000000000000000000001466601756300160555ustar00rootroot00000000000000yard-0.9.37/spec/serializers/data/000077500000000000000000000000001466601756300167665ustar00rootroot00000000000000yard-0.9.37/spec/serializers/data/serialized_yardoc/000077500000000000000000000000001466601756300224625ustar00rootroot00000000000000yard-0.9.37/spec/serializers/data/serialized_yardoc/checksums000066400000000000000000000000611466601756300243670ustar00rootroot00000000000000test.rb 80e5834ff1e98223761615c0917ff9b77b7ae057
yard-0.9.37/spec/serializers/data/serialized_yardoc/objects/000077500000000000000000000000001466601756300241135ustar00rootroot00000000000000yard-0.9.37/spec/serializers/data/serialized_yardoc/objects/Foo.dat000066400000000000000000000012621466601756300253310ustar00rootroot00000000000000o:#YARD::CodeObjects::ClassObject:@childrenIC:&YARD::CodeObjects::CodeObjectList[Iu:YARD::StubProxyFoo#bar:EFIu;Foo#baz;	F:@ownerIu;Foo;	F:@class_mixinsIC;[;
Iu;Foo;	F:@instance_mixinsIC;[;
Iu;Foo;	F:@attributesIC:SymbolHash{:
classIC;{:@symbolize_valueT:
instanceIC;{;T;T:
@aliases{Iu;Foo#baz;	F:bar:@files[[I"test.rb;	Ti:@current_file_has_commentsF:
@name:Foo:@source_type:	ruby:
@tags[:@docstringIC:YARD::Docstring";	F:@objectIu;Foo;	F:
@summary0:@ref_tags[;[:	@allI";	F:@line_range0:@namespaceIu;;	F:@superclasso:YARD::CodeObjects::Proxy:
@imethod0:@origname0:@orignamespace0;:Object;"Iu;;	F:	@obj0yard-0.9.37/spec/serializers/data/serialized_yardoc/objects/Foo/000077500000000000000000000000001466601756300246365ustar00rootroot00000000000000yard-0.9.37/spec/serializers/data/serialized_yardoc/objects/Foo/bar_i.dat000066400000000000000000000006371466601756300264120ustar00rootroot00000000000000o:$YARD::CodeObjects::MethodObject:@scope:
instance:@visibility:public:@parameters[:@files[[I"test.rb:ETi:@current_file_has_commentsF:
@name:bar:@source_type:	ruby:
@tags[:@docstringIC:YARD::Docstring";F:@objectIu:YARD::StubProxyFoo#bar;F:
@summary0:@ref_tags[;[:	@allI";F:@line_range0:@namespaceIu;Foo;F:@sourceI"def bar; end;F:@signatureI"def bar( );F:@explicitTyard-0.9.37/spec/serializers/data/serialized_yardoc/objects/Foo/baz_i.dat000066400000000000000000000006231466601756300264150ustar00rootroot00000000000000o:$YARD::CodeObjects::MethodObject:@scope:
instance:@visibility:public:@parameters[:@files[[I"test.rb:ETi[@	i:@current_file_has_commentsF:
@name:baz:@source_type:	ruby:
@tags[:@docstringIC:YARD::Docstring";F:@objectIu:YARD::StubProxyFoo#baz;F:
@summary0:@ref_tags[;[:	@all0:@line_range0:@namespaceIu;Foo;F:@sourceI"def bar; end;F:@signatureI"def bar( );Fyard-0.9.37/spec/serializers/data/serialized_yardoc/objects/root.dat000066400000000000000000000007501466601756300255720ustar00rootroot00000000000000o:"YARD::CodeObjects::RootObject:@childrenIC:&YARD::CodeObjects::CodeObjectList[Iu:YARD::StubProxyFoo:EF:@ownerIu;;	F:@class_mixinsIC;[;
Iu;;	F:@instance_mixinsIC;[;
Iu;;	F:@attributesIC:SymbolHash{:
classIC;{:@symbolize_valueT:
instanceIC;{;T;T:
@aliases{:@files[:@current_file_has_commentsF:
@name:	root:@source_type:	ruby:
@tags[:@docstringIC:YARD::Docstring";	F:@objectIu;;	F:
@summary0:@ref_tags[;[:	@allI";	F:@namespace0yard-0.9.37/spec/serializers/data/serialized_yardoc/proxy_types000066400000000000000000000000311466601756300250040ustar00rootroot00000000000000{I"Object:EF:
classyard-0.9.37/spec/serializers/file_system_serializer_spec.rb000066400000000000000000000113741466601756300241760ustar00rootroot00000000000000# frozen_string_literal: true
require File.join(File.dirname(__FILE__), "spec_helper")

require 'stringio'

RSpec.describe YARD::Serializers::FileSystemSerializer do
  before do
    allow(FileUtils).to receive(:mkdir_p)
    allow(File).to receive(:open)
  end

  describe "#basepath" do
    it "defaults the base path to the 'doc/'" do
      obj = Serializers::FileSystemSerializer.new
      expect(obj.basepath).to eq 'doc'
    end
  end

  describe "#extension" do
    it "defaults the file extension to .html" do
      obj = Serializers::FileSystemSerializer.new
      expect(obj.extension).to eq "html"
    end
  end

  describe "#serialized_path" do
    it "allows no extension to be used" do
      obj = Serializers::FileSystemSerializer.new :extension => nil
      yard = CodeObjects::ClassObject.new(nil, :FooBar)
      expect(obj.serialized_path(yard)).to eq 'FooBar'
    end

    it "serializes to top-level-namespace for root" do
      obj = Serializers::FileSystemSerializer.new :extension => nil
      expect(obj.serialized_path(Registry.root)).to eq "top-level-namespace"
    end

    it "returns serialized_path for a String" do
      s = Serializers::FileSystemSerializer.new(:basepath => 'foo', :extension => 'txt')
      expect(s.serialized_path('test.txt')).to eq 'test.txt'
    end

    it "removes special chars from path" do
      m = CodeObjects::MethodObject.new(nil, 'a')
      s = Serializers::FileSystemSerializer.new

      {:gsub! => 'gsub_21_i.html',
        :ask? => 'ask_3F_i.html',
        :=== => '_3D_3D_3D_i.html',
        :+ => '_2B_i.html',
        :- => '-_i.html',
        :[]= => '_5B_5D_3D_i.html',
        :<< => '_3C_3C_i.html',
        :>= => '_3E_3D_i.html',
        :` => '_60_i.html',
        :& => '_26_i.html',
        :* => '_2A_i.html',
        :| => '_7C_i.html',
        :/ => '_2F_i.html',
        :=~ => '_3D_7E_i.html'}.each do |meth, value|
        allow(m).to receive(:name).and_return(meth)
        expect(s.serialized_path(m)).to eq value
      end
    end

    it "handles ExtraFileObject's" do
      s = Serializers::FileSystemSerializer.new
      e = CodeObjects::ExtraFileObject.new('filename.txt', '')
      expect(s.serialized_path(e)).to eq 'file.filename.html'
    end

    it "differentiates instance and class methods from serialized path" do
      s = Serializers::FileSystemSerializer.new
      m1 = CodeObjects::MethodObject.new(nil, 'meth')
      m2 = CodeObjects::MethodObject.new(nil, 'meth', :class)
      expect(s.serialized_path(m1)).not_to eq s.serialized_path(m2)
    end

    it "serializes path from overload tag" do
      YARD.parse_string <<-'eof'
        class Foo
          # @overload bar
          def bar; end
        end
      eof

      serializer = Serializers::FileSystemSerializer.new
      object = Registry.at('Foo#bar').tag(:overload)
      expect(serializer.serialized_path(object)).to eq "Foo/bar_i.html"
    end

    it "maps matching case sensitive object names to different files on disk" do
      Registry.clear
      o1 = CodeObjects::ClassObject.new(:root, "AB")
      o2 = CodeObjects::ClassObject.new(:root, "Ab")
      s = Serializers::FileSystemSerializer.new
      expect([["AB_.html", "Ab.html"], ["AB.html", "Ab_.html"]]).to include(
        [s.serialized_path(o1), s.serialized_path(o2)]
      )
    end

    it "handles case sensitivity of nested paths for objects with matching names" do
      Registry.clear
      YARD.parse_string <<-eof
        class Abc; class D; end end
        class ABC; class D; end end
      eof

      s = Serializers::FileSystemSerializer.new
      expect(s.serialized_path(Registry.at('ABC::D'))).to eq "ABC/D.html"
      expect(s.serialized_path(Registry.at('Abc::D'))).to eq "Abc/D.html"
    end
  end

  describe "#serialize" do
    it "serializes to the correct path" do
      yard = CodeObjects::ClassObject.new(nil, :FooBar)
      meth = CodeObjects::MethodObject.new(yard, :baz, :class)
      meth2 = CodeObjects::MethodObject.new(yard, :baz)

      {'foo/FooBar/baz_c.txt' => meth,
        'foo/FooBar/baz_i.txt' => meth2,
        'foo/FooBar.txt' => yard}.each do |path, obj|
        io = StringIO.new
        expect(File).to receive(:open).with(path, 'wb').and_yield(io)
        expect(io).to receive(:write).with("data")

        s = Serializers::FileSystemSerializer.new(:basepath => 'foo', :extension => 'txt')
        s.serialize(obj, "data")
      end
    end

    it "guarantees the directory exists" do
      o1 = CodeObjects::ClassObject.new(nil, :Really)
      o2 = CodeObjects::ClassObject.new(o1, :Long)
      o3 = CodeObjects::ClassObject.new(o2, :PathName)
      obj = CodeObjects::MethodObject.new(o3, :foo)

      expect(FileUtils).to receive(:mkdir_p).once.with('doc/Really/Long/PathName')

      s = Serializers::FileSystemSerializer.new
      s.serialize(obj, "data")
    end
  end
end
yard-0.9.37/spec/serializers/spec_helper.rb000066400000000000000000000000531466601756300206710ustar00rootroot00000000000000# frozen_string_literal: true
include YARD
yard-0.9.37/spec/serializers/yardoc_serializer_spec.rb000066400000000000000000000061511466601756300231310ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

instance_eval do
  class YARD::Serializers::YardocSerializer
    public :dump
    public :internal_dump
  end
end

RSpec.describe YARD::Serializers::YardocSerializer do
  before do
    @serializer = YARD::Serializers::YardocSerializer.new('.yardoc')

    Registry.clear
    @foo = CodeObjects::ClassObject.new(:root, :Foo)
    @bar = CodeObjects::MethodObject.new(@foo, :bar)
  end

  describe "#dump" do
    it "maintains object equality when loading a dumped object" do
      newfoo = @serializer.internal_dump(@foo)
      expect(newfoo).to equal(@foo)
      expect(newfoo).to eq @foo
      expect(@foo).to equal(newfoo)
      expect(@foo).to eq newfoo
      expect(newfoo.hash).to eq @foo.hash
    end

    it "maintains hash key equality when loading a dumped object" do
      newfoo = @serializer.internal_dump(@foo)
      expect(@foo => 1).to have_key(newfoo)
      expect(newfoo => 1).to have_key(@foo)
    end
  end

  describe "#serialize" do
    it "accepts a hash of codeobjects (and write to root)" do
      data = {:root => Registry.root}
      marshaldata = Marshal.dump(data)
      filemock = double(:file)
      expect(filemock).to receive(:write).with(marshaldata)
      expect(File).to receive(:open!).with('.yardoc/objects/root.dat', 'wb').and_yield(filemock)
      @serializer.serialize(data)
    end
  end

  describe "#serialized_path" do
    it "handles String path name" do
      path = @serializer.serialized_path('Path::To#object')
      expect(path).to eq('objects/Path/To/object_i.dat')
    end

    it "handles special encoding characters" do
      path = @serializer.serialized_path('object$')
      expect(path).to eq('objects/object_24.dat')
    end
  end

  describe "#lock_for_writing" do
    it "creates a lock file during writing and cleans up" do
      expect(File).to receive(:open!).with(@serializer.processing_path, 'w')
      expect(File).to receive(:exist?).with(@serializer.processing_path).exactly(2).times.and_return(true)
      expect(File).to receive(:unlink).with(@serializer.processing_path)
      @serializer.lock_for_writing do
        expect(@serializer.locked_for_writing?).to eq true
      end
    end
  end

  describe "#complete?" do
    it "returns false if complete file does not exist" do
      allow(File).to receive(:exist?).with(@serializer.complete_lock_path).and_return(false)
      allow(File).to receive(:exist?).with(@serializer.processing_path).and_return(false)
      expect(@serializer.complete?).to eq false
    end

    it "returns false if processing file exists" do
      allow(File).to receive(:exist?).with(@serializer.complete_lock_path).and_return(true)
      allow(File).to receive(:exist?).with(@serializer.processing_path).and_return(true)
      expect(@serializer.complete?).to eq false
    end

    it "returns true if complete file exists with no processing file" do
      allow(File).to receive(:exist?).with(@serializer.complete_lock_path).and_return(true)
      allow(File).to receive(:exist?).with(@serializer.processing_path).and_return(false)
      expect(@serializer.complete?).to eq true
    end
  end
end
yard-0.9.37/spec/server/000077500000000000000000000000001466601756300150275ustar00rootroot00000000000000yard-0.9.37/spec/server/adapter_spec.rb000066400000000000000000000022011466601756300200010ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Server::Adapter do
  after(:all) { Server::Adapter.shutdown }

  describe "#add_library" do
    it "adds a library" do
      lib = LibraryVersion.new('yard')
      a = Adapter.new({})
      expect(a.libraries).to be_empty
      a.add_library(lib)
      expect(a.libraries['yard']).to eq [lib]
    end
  end

  describe "#start" do
    it "does not implement #start" do
      expect { Adapter.new({}).start }.to raise_error(NotImplementedError)
    end
  end

  describe ".setup" do
    it "adds template paths and helpers" do
      Adapter.setup
      expect(Templates::Template.extra_includes).to include(DocServerHelper)
      expect(Templates::Engine.template_paths).to include(YARD::ROOT + '/yard/server/templates')
    end
  end

  describe ".shutdown" do
    it "cleans up template paths and helpers" do
      Adapter.setup
      Adapter.shutdown
      expect(Templates::Template.extra_includes).not_to include(DocServerHelper)
      expect(Templates::Engine.template_paths).not_to include(YARD::ROOT + '/yard/server/templates')
    end
  end
end
yard-0.9.37/spec/server/commands/000077500000000000000000000000001466601756300166305ustar00rootroot00000000000000yard-0.9.37/spec/server/commands/base_spec.rb000066400000000000000000000052371466601756300211100ustar00rootroot00000000000000# frozen_string_literal: true

class MyProcCommand < Base
  def initialize(&block)
    self.class.send(:undef_method, :run)
    self.class.send(:define_method, :run, &block)
  end
end

class MyCacheCommand < Base
  def run; cache 'foo' end
end

RSpec.describe YARD::Server::Commands::Base do
  describe "#cache" do
    before do
      @command = MyCacheCommand.new(:adapter => mock_adapter, :caching => true)
      @command.request = mock_request(nil)
    end

    it "does not cache if caching == false" do
      expect(File).not_to receive(:open)
      @command.caching = false
      @command.run
    end

    it "requires document root to cache" do
      expect(File).not_to receive(:open)
      @command.adapter.document_root = nil
      @command.run
    end

    it "caches to path/to/file.html and create directories" do
      expect(FileUtils).to receive(:mkdir_p).with('/public/path/to')
      expect(File).to receive(:open).with('/public/path/to/file.html', anything)
      @command.request.path_info = '/path/to/file.html'
      @command.run
    end
  end

  describe "#redirect" do
    it "returns a valid redirection" do
      cmd = MyProcCommand.new { redirect '/foo' }
      expect(cmd.call(mock_request('/foo'))).to eq(
        [302, {"Content-Type" => "text/html", "Location" => "/foo"}, [""]]
      )
    end
  end

  describe "#call" do
    it "handles a NotFoundError and use message as body" do
      cmd = MyProcCommand.new { raise NotFoundError, "hello world" }
      s, _, b = *cmd.call(mock_request('/foo'))
      expect(s).to eq 404
      expect(b).to eq ["hello world"]
    end

    it "does not use message as body if not provided in NotFoundError" do
      cmd = MyProcCommand.new { raise NotFoundError }
      s, _, b = *cmd.call(mock_request('/foo'))
      expect(s).to eq 404
      expect(b).to eq ["Not found: /foo"]
    end

    it "handles 404 status code from #run" do
      cmd = MyProcCommand.new { self.status = 404 }
      s, _, b = *cmd.call(mock_request('/foo'))
      expect(s).to eq 404
      expect(b).to eq ["Not found: /foo"]
    end

    it "does not override body if status is 404 and body is defined" do
      cmd = MyProcCommand.new { self.body = "foo"; self.status = 404 }
      s, _, b = *cmd.call(mock_request('/bar'))
      expect(s).to eq 404
      expect(b).to eq ['foo']
    end

    it "handles body as Array" do
      cmd = MyProcCommand.new { self.body = ['a', 'b', 'c'] }
      _, _, b = *cmd.call(mock_request('/foo'))
      expect(b).to eq %w(a b c)
    end

    it "allows headers to be defined" do
      cmd = MyProcCommand.new { headers['Foo'] = 'BAR' }
      _, h, = *cmd.call(mock_request('/foo'))
      expect(h['Foo']).to eq 'BAR'
    end
  end
end
yard-0.9.37/spec/server/commands/library_command_spec.rb000066400000000000000000000020121466601756300233240ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Server::Commands::LibraryCommand do
  before do
    allow(Templates::Engine).to receive(:render)
    allow(Templates::Engine).to receive(:generate)
    allow(YARD).to receive(:parse)
    allow(Registry).to receive(:load)
    allow(Registry).to receive(:save)

    @cmd = LibraryCommand.new(:adapter => mock_adapter)
    @request = mock_request("/foo", :xhr? => false)
    @library = OpenStruct.new(:source_path => '.')
    @cmd.library = @library
    allow(@cmd).to receive(:load_yardoc).and_return(nil)
  end

  def call
    expect { @cmd.call(@request) }.to raise_error(NotImplementedError)
  end

  describe "#call" do
    it "raises NotImplementedError" do
      call
    end

    it "sets :rdoc as the default markup in incremental mode" do
      @cmd.incremental = true
      call
      expect(@cmd.options[:markup]).to eq :rdoc
    end

    it "sets :rdoc as the default markup in regular mode" do
      call
      expect(@cmd.options[:markup]).to eq :rdoc
    end
  end
end
yard-0.9.37/spec/server/doc_server_helper_spec.rb000066400000000000000000000045201466601756300220610ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

class MyDocServerSerializerRouter
  attr_accessor :request
  def docs_prefix; 'PREFIX' end
  def initialize; @request = mock_request end
end

class MockDocServerHelper
  include YARD::Templates::Helpers::BaseHelper
  include YARD::Templates::Helpers::HtmlHelper
  include YARD::Server::DocServerHelper

  attr_accessor :adapter
  attr_accessor :single_library
  attr_accessor :library

  def initialize
    @single_library = false
    @library = LibraryVersion.new('foo')
    @adapter = mock_adapter(:router => MyDocServerSerializerRouter.new)
    @serializer = YARD::Server::DocServerSerializer.new
    @object = YARD::Registry.root
  end

  def options; OpenStruct.new end
end

RSpec.describe YARD::Server::DocServerHelper do
  before do
    @helper = MockDocServerHelper.new
  end

  describe "#url_for" do
    it "does not link to /library/ if single_library = true" do
      @helper.single_library = true
      expect(@helper.url_for(Registry.root)).to eq "/PREFIX/toplevel"
    end

    it "returns /PREFIX/foo/version if foo has a version" do
      @helper.library = LibraryVersion.new('foo', 'bar')
      @helper.adapter.router.request.version_supplied = true
      expect(@helper.url_for(P('A'))).to eq '/PREFIX/foo/bar/A'
    end

    it "uses script name prefix if set" do
      @helper.adapter.router.request.script_name = '/mount/point'
      @helper.library = LibraryVersion.new('foo', 'bar')
      @helper.adapter.router.request.version_supplied = true
      expect(@helper.url_for(P('A'))).to eq '/mount/point/PREFIX/foo/bar/A'
    end
  end

  describe "#url_for_file" do
    it "properly links file objects using file/ prefix" do
      file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
      expect(@helper.url_for_file(file)).to eq '/PREFIX/foo/file/a/b/FooBar.md'
    end

    it "properly links anchor portion" do
      file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
      expect(@helper.url_for_file(file, 'anchor')).to eq '/PREFIX/foo/file/a/b/FooBar.md#anchor'
    end

    it "uses script name prefix if set" do
      @helper.adapter.router.request.script_name = '/mount/point'
      file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
      expect(@helper.url_for_file(file)).to eq '/mount/point/PREFIX/foo/file/a/b/FooBar.md'
    end
  end
end
yard-0.9.37/spec/server/doc_server_serializer_spec.rb000066400000000000000000000040631466601756300227550ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Server::DocServerSerializer do
  describe "#serialized_path" do
    before do
      Registry.clear
      @serializer = Server::DocServerSerializer.new
    end

    after(:all) { Server::Adapter.shutdown }

    it "returns '/PREFIX/library/toplevel' for root" do
      expect(@serializer.serialized_path(Registry.root)).to eq "toplevel"
    end

    it "returns /PREFIX/library/Object for Object in a library" do
      expect(@serializer.serialized_path(P('A::B::C'))).to eq 'A/B/C'
    end

    it "links to instance method as Class:method" do
      obj = CodeObjects::MethodObject.new(:root, :method)
      expect(@serializer.serialized_path(obj)).to eq 'toplevel:method'
    end

    it "links to class method as Class.method" do
      obj = CodeObjects::MethodObject.new(:root, :method, :class)
      expect(@serializer.serialized_path(obj)).to eq 'toplevel.method'
    end

    it "links to anchor for constant" do
      obj = CodeObjects::ConstantObject.new(:root, :FOO)
      expect(@serializer.serialized_path(obj)).to eq 'toplevel#FOO-constant'
    end

    it "links to anchor for class variable" do
      obj = CodeObjects::ClassVariableObject.new(:root, :@@foo)
      expect(@serializer.serialized_path(obj)).to eq 'toplevel#@@foo-classvariable'
    end

    it "links files using file/ prefix" do
      file = CodeObjects::ExtraFileObject.new('a/b/FooBar.md', '')
      expect(@serializer.serialized_path(file)).to eq 'file/FooBar'
    end

    it "escapes special characters" do
      obj = CodeObjects::MethodObject.new(:root, :method?)
      expect(@serializer.serialized_path(obj)).to eq 'toplevel:method%3F'
    end

    it "handles unicode data" do
      file = CodeObjects::ExtraFileObject.new("test\u0160", '')
      if file.name.encoding == Encoding.find("Windows-1252")
        expect(@serializer.serialized_path(file)).to eq 'file/test_8A'
      else
        expect(@serializer.serialized_path(file)).to eq 'file/test_C5A0'
      end
    end if defined?(::Encoding)
  end
end
yard-0.9.37/spec/server/rack_adapter_spec.rb000066400000000000000000000013561466601756300210130ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe "YARD::Server::RackMiddleware" do
  before do
    begin; require 'rack'; rescue LoadError; pending "rack required for these tests" end
    @superapp = double(:superapp)
    @app = YARD::Server::RackMiddleware.new(@superapp, :libraries => {'foo' => [LibraryVersion.new('foo', nil)]})
  end

  after(:all) { YARD::Server::Adapter.shutdown }

  it "handles requests" do
    expect(@app.call(Rack::MockRequest.env_for('/'))[0]).to eq 200
  end

  it "passes up to the next middleware on 404" do
    expect(@superapp).to receive(:call).and_return([200, {}, ['OK']])
    expect(@app.call(Rack::MockRequest.env_for('/INVALID'))).to eq [200, {}, ['OK']]
  end
end
yard-0.9.37/spec/server/router_spec.rb000066400000000000000000000077411466601756300177170ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

class MyRouterSpecRouter < Router
  def docs_prefix; 'mydocs/foo' end
  def list_prefix; 'mylist/foo' end
  def search_prefix; 'mysearch/foo' end

  def check_static_cache; nil end
end

RSpec.describe YARD::Server::Router do
  before do
    @adapter = mock_adapter
    @projects = @adapter.libraries['project']
    @request = mock_request
  end

  describe "#parse_library_from_path" do
    def parse(*args)
      @request.path_info = '/' + args.join('/')
      @router = MyRouterSpecRouter.new(@adapter)
      @router.request = @request
      @router.parse_library_from_path(args.flatten)
    end

    it "parses library and version name out of path" do
      expect(parse('project', '1.0.0')).to eq [@projects[0], []]
      expect(@request.version_supplied).to be true
    end

    it "parses library and use latest version if version is not supplied" do
      expect(parse('project')).to eq [@projects[1], []]
      expect(@request.version_supplied).to be false
    end

    it "parses library and use latest version if next component is not a version" do
      expect(parse('project', 'notaversion')).to eq [@projects[1], ['notaversion']]
      expect(@request.version_supplied).to be false
    end

    it "returns nil library if no library is found" do
      expect(parse('notproject')).to eq [nil, ['notproject']]
    end

    it "does not parse library or version if single_library == true" do
      allow(@adapter).to receive(:options).and_return(:single_library => true)
      expect(parse('notproject')).to eq [@projects[0], ['notproject']]
    end
  end

  describe "#route" do
    def route_to(route, command, script_name = '')
      req = mock_request(route, script_name)
      router = MyRouterSpecRouter.new(@adapter)
      expect(command).to receive(:new) do |*args|
        @command = command.allocate
        @command.send(:initialize, *args)
        class << @command; define_method(:call) {|*| self } end
        @command
      end
      router.call(req)
    end

    it "routes /docs/OBJECT to object if single_library = true" do
      allow(@adapter).to receive(:options).and_return(:single_library => true)
      route_to('/mydocs/foo/FOO', DisplayObjectCommand)
    end

    it "routes /docs" do
      route_to('/mydocs/foo', LibraryIndexCommand)
    end

    it "routes /docs as index for library if single_library == true" do
      allow(@adapter).to receive(:options).and_return(:single_library => true)
      route_to('/mydocs/foo/', DisplayObjectCommand)
    end

    it "routes /docs/name/version" do
      route_to('/mydocs/foo/project/1.0.0', DisplayObjectCommand)
      expect(@command.library).to eq @projects[0]
    end

    it "routes /docs/name/ to latest version of library" do
      route_to('/mydocs/foo/project', DisplayObjectCommand)
      expect(@command.library).to eq @projects[1]
    end

    it "routes /list/name/version/class" do
      route_to('/mylist/foo/project/1.0.0/class', ListCommand)
      expect(@command.library).to eq @projects[0]
    end

    it "routes /list/name/version/methods" do
      route_to('/mylist/foo/project/1.0.0/methods', ListCommand)
      expect(@command.library).to eq @projects[0]
    end

    it "routes /list/name/version/files" do
      route_to('/mylist/foo/project/1.0.0/files', ListCommand)
      expect(@command.library).to eq @projects[0]
    end

    it "routes /list/name to latest version of library" do
      route_to('/mylist/foo/project/class', ListCommand)
      expect(@command.library).to eq @projects[1]
    end

    it "routes /search/name/version" do
      route_to('/mysearch/foo/project/1.0.0', SearchCommand)
      expect(@command.library).to eq @projects[0]
    end

    it "routes /search/name to latest version of library" do
      route_to('/mysearch/foo/project', SearchCommand)
      expect(@command.library).to eq @projects[1]
    end

    it "searches static files for non-existent library" do
      route_to('/mydocs/foo/notproject', RootRequestCommand)
    end
  end
end
yard-0.9.37/spec/server/spec_helper.rb000066400000000000000000000011701466601756300176440ustar00rootroot00000000000000# frozen_string_literal: true

include Server
include Commands

def mock_adapter(opts = {})
  opts[:libraries] ||= {'project' => [LibraryVersion.new('project', '1.0.0'), LibraryVersion.new('project', '1.0.1')]}
  opts[:document_root] ||= '/public'
  opts[:options] ||= {:single_library => false, :caching => false}
  opts[:server_options] ||= {}
  OpenStruct.new(opts)
end

class MockRequest < OpenStruct
  def path; "#{script_name}#{path_info}" end
end

def mock_request(path_info = '/', script_name = '', extra_env = {})
  opts = {:path_info => path_info, :script_name => script_name}
  MockRequest.new(extra_env.merge(opts))
end
yard-0.9.37/spec/server/static_caching_spec.rb000066400000000000000000000033331466601756300213330ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Server::StaticCaching do
  include StaticCaching

  describe "#check_static_cache" do
    def adapter; @adapter ||= mock_adapter end
    def request; @request ||= MockRequest.new end

    it "returns nil if document root is not set" do
      adapter.document_root = nil
      expect(check_static_cache).to be nil
    end

    it "reads a file from document root if path matches file on system" do
      request.path_info = '/hello/world.html'
      expect(File).to receive(:file?).with('/public/hello/world.html').and_return(true)
      expect(File).to receive(:open).with('/public/hello/world.html', anything).and_return('body')
      s, _, b = *check_static_cache
      expect(s).to eq 200
      expect(b).to eq ["body"]
    end

    it "reads a file if path matches file on system + .html" do
      request.path_info = '/hello/world'
      expect(File).to receive(:file?).with('/public/hello/world.html').and_return(true)
      expect(File).to receive(:open).with('/public/hello/world.html', anything).and_return('body')
      s, _, b = *check_static_cache
      expect(s).to eq 200
      expect(b).to eq ["body"]
    end

    it "returns nil if no matching file is found" do
      request.path_info = '/hello/foo'
      expect(File).to receive(:file?).with('/public/hello/foo.html').and_return(false)
      expect(check_static_cache).to eq nil
    end

    it "adds mount point to cache location" do
      request.path_info = '/hello/world.html'
      request.script_name = '/mount/point'
      expect(File).to receive(:file?).with('/public/mount/point/hello/world.html').and_return(false)
      expect(check_static_cache).to eq nil
    end
  end
end
yard-0.9.37/spec/server/webrick_servlet_spec.rb000066400000000000000000000012311466601756300215550ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Server::WebrickServlet do
  describe "#do_GET" do
    it "performs a GET" do
      resp = OpenStruct.new
      class << resp
        def []=(name, value) (self.headers ||= {})[name] = value end
      end
      server = double(:server, :[] => nil)
      adapter = mock_adapter
      adapter.router = proc { [200, {'Header' => 'foo'}, ['body']] }
      WebrickServlet.new(server, adapter).do_GET(mock_request('/foo'), resp)
      expect(resp.status).to eq 200
      expect(resp.headers).to eq('Header' => 'foo')
      expect(resp.body).to eq 'body'
    end
  end
end
yard-0.9.37/spec/server_spec.rb000066400000000000000000000011321466601756300163630ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Server do
  describe ".register_static_path" do
    it "registers a static path" do
      YARD::Server.register_static_path 'foo'
      expect(YARD::Server::Commands::StaticFileCommand::STATIC_PATHS.last).to eq "foo"
    end

    it "does not duplicate paths" do
      paths = YARD::Server::Commands::StaticFileCommand::STATIC_PATHS
      count = paths.size
      YARD::Server.register_static_path 'foo2'
      YARD::Server.register_static_path 'foo2'
      expect(paths.size).to eq(count + 1)
      expect(paths.last).to eq 'foo2'
    end
  end
end
yard-0.9.37/spec/spec_helper.rb000066400000000000000000000173111466601756300163420ustar00rootroot00000000000000# frozen_string_literal: true
require "rubygems"
begin
  require "rspec"
rescue LoadError
  require "spec"
end

begin
  require 'bundler/setup'
rescue LoadError
  nil # noop
end

require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'yard'))

unless defined?(HAVE_RIPPER)
  begin require 'ripper'; rescue LoadError; nil end
  HAVE_RIPPER = defined?(::Ripper) && !ENV['LEGACY'] ? true : false
  LEGACY_PARSER = !HAVE_RIPPER

  class YARD::Parser::SourceParser
    def self.parser_type; @parser_type == :ruby ? :ruby18 : @parser_type end
  end if ENV['LEGACY']
end

begin
  require 'coveralls'
  Coveralls.wear!
end if ENV['CI'] && HAVE_RIPPER

NAMED_OPTIONAL_ARGUMENTS = RUBY_VERSION >= '2.1.0'

def parse_file(files, thisfile = __FILE__, log_level = log.level, ext = '.rb.txt')
  Registry.clear
  paths = Array(files).map { |file| File.join(File.dirname(thisfile), 'examples', file.to_s + ext) }
  YARD::Parser::SourceParser.parse(paths, [], log_level)
end

def described_in_docs(klass, meth, file = nil)
  YARD::Tags::Library.define_tag "RSpec Specification", :it, :with_raw_title_and_text

  # Parse the file (could be multiple files)
  if file
    filename = File.join(YARD::ROOT, file)
    YARD::Parser::SourceParser.new.parse(filename)
  else
    underscore = klass.class_name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.gsub('::', '/')
    $LOADED_FEATURES.find_all {|p| p.include? underscore }.each do |found_fname|
      next unless File.exist? found_fname
      YARD::Parser::SourceParser.new.parse(found_fname)
    end
  end

  # Get the object
  objname = klass.name + (meth[0, 1] == '#' ? meth : '::' + meth)
  obj = Registry.at(objname)
  raise "Cannot find object #{objname} described by spec." unless obj
  raise "#{obj.path} has no @it tags to spec." unless obj.has_tag? :it

  # Run examples
  describe(klass, meth) do
    obj.tags(:it).each do |it|
      path = File.relative_path(YARD::ROOT, obj.file)
      it(it.name + " (from #{path}:#{obj.line})") do
        begin
          eval(it.text)
        rescue => e
          e.set_backtrace(["#{path}:#{obj.line}:in @it tag specification"])
          raise e
        end
      end
    end
  end
end

def docspec(objname = self.class.description, klass = self.class.described_type)
  # Parse the file (could be multiple files)
  underscore = klass.class_name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.gsub('::', '/')
  $LOADED_FEATURES.find_all {|p| p.include? underscore }.each do |filename|
    filename = File.join(YARD::ROOT, filename)
    next unless File.exist? filename
    YARD::Parser::SourceParser.new.parse(filename)
  end

  # Get the object
  objname = klass.name + objname if objname =~ /^[^A-Z]/
  obj = Registry.at(objname)
  raise "Cannot find object #{objname} described by spec." unless obj
  raise "#{obj.path} has no @example tags to spec." unless obj.has_tag? :example

  # Run examples
  obj.tags(:example).each do |exs|
    exs.text.split(/\n/).each do |ex|
      begin
        hash = eval("{ #{ex} }")
        expect(hash.keys.first).to eq hash.values.first
      rescue => e
        raise e, "#{e.message}\nInvalid spec example in #{objname}:\n\n\t#{ex}\n"
      end
    end
  end
end

module Kernel
  require 'cgi'

  def p(*args)
    puts args.map {|arg| CGI.escapeHTML(arg.inspect) }.join("
    \n")
    args.first
  end

  def puts(str = '')
    STDOUT.puts str + "
    \n"
    str
  end
end if ENV['TM_APP_PATH']

RSpec.configure do |config|
  config.before(:each) { log.io = StringIO.new }

  config.raise_errors_for_deprecations!

  # isolate environment of each test
  # any other global settings which might be modified by a test should also
  # be saved and restored here
  config.around(:each) do |example|
    saved_level = log.level
    example.run
    log.level = saved_level
  end

  # rspec-expectations config goes here. You can use an alternate
  # assertion/expectation library such as wrong or the stdlib/minitest
  # assertions if you prefer.
  config.expect_with :rspec do |expectations|
    # This option will default to `true` in RSpec 4. It makes the `description`
    # and `failure_message` of custom matchers include text for helper methods
    # defined using `chain`, e.g.:
    #     be_bigger_than(2).and_smaller_than(4).description
    #     # => "be bigger than 2 and smaller than 4"
    # ...rather than:
    #     # => "be bigger than 2"
    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
  end

  # rspec-mocks config goes here. You can use an alternate test double
  # library (such as bogus or mocha) by changing the `mock_with` option here.
  config.mock_with :rspec do |mocks|
    # Prevents you from mocking or stubbing a method that does not exist on
    # a real object. This is generally recommended, and will default to
    # `true` in RSpec 4.
    # mocks.verify_partial_doubles = true # FIXME: Not yet working
  end

  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
  # have no way to turn it off -- the option exists only for backwards
  # compatibility in RSpec 3). It causes shared context metadata to be
  # inherited by the metadata hash of host groups and examples, rather than
  # triggering implicit auto-inclusion in groups with matching metadata.
  config.shared_context_metadata_behavior = :apply_to_host_groups

  # This allows you to limit a spec run to individual examples or groups
  # you care about by tagging them with `:focus` metadata. When nothing
  # is tagged with `:focus`, all examples get run. RSpec also provides
  # aliases for `it`, `describe`, and `context` that include `:focus`
  # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
  config.filter_run_when_matching :focus

  # Allows RSpec to persist some state between runs in order to support
  # the `--only-failures` and `--next-failure` CLI options. We recommend
  # you configure your source control system to ignore this file.
  config.example_status_persistence_file_path = "spec/examples.txt"

  # Limits the available syntax to the non-monkey patched syntax that is
  # recommended. For more details, see:
  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
  config.disable_monkey_patching!

  # This setting enables warnings. It's recommended, but in some cases may
  # be too noisy due to issues in dependencies.
  config.warnings = false

  # Many RSpec users commonly either run the entire suite or an individual
  # file, and it's useful to allow more verbose output when running an
  # individual spec file.
  if config.files_to_run.one?
    # Use the documentation formatter for detailed output,
    # unless a formatter has already been configured
    # (e.g. via a command-line flag).
    config.default_formatter = 'doc'
  end

  # Print the N slowest examples and example groups at the
  # end of the spec run, to help surface which specs are running
  # particularly slow.
  config.profile_examples = 5

  # Run specs in random order to surface order dependencies. If you find an
  # order dependency and want to debug it, you can fix the order by providing
  # the seed, which is printed after each run.
  #     --seed 1234
  # config.order = :random # FIXME: Not yet working

  # Seed global randomization in this process using the `--seed` CLI option.
  # Setting this allows you to use `--seed` to deterministically reproduce
  # test failures related to randomization by passing the same `--seed` value
  # as the one that triggered the failure.
  Kernel.srand config.seed
end

# Needed before including YARD to avoid a Logger load conflict because of the `include YARD` line
begin
  require 'asciidoctor'
rescue LoadError; end

YARD::Logger
include YARD
yard-0.9.37/spec/tags/000077500000000000000000000000001466601756300144575ustar00rootroot00000000000000yard-0.9.37/spec/tags/default_factory_spec.rb000066400000000000000000000137361466601756300212030ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Tags::DefaultFactory do
  before { @f = YARD::Tags::DefaultFactory.new }

  describe "#parse_tag" do
    it "does not have trailing whitespace on a regular freeform tag" do
      expect(@f.parse_tag('api', 'private     ').text).to eq "private"
    end
  end

  describe "#extract_types_and_name_from_text" do
    def parse_types(types)
      @f.send(:extract_types_and_name_from_text, types)
    end

    it "handles one type" do
      expect(parse_types('[A]')).to eq [nil, ['A'], ""]
    end

    it "handles a list of types" do
      expect(parse_types('[A, B, C]')).to eq [nil, ['A', 'B', 'C'], ""]
    end

    it "handles ducktypes" do
      expect(parse_types('[#foo]')).to eq [nil, ['#foo'], '']
    end

    %w(#foo= #<< #<=> #>> #== #=== Array<#<=>> Array<#==>).each do |meth|
      it "handles ducktypes with special method name #{meth}" do
        expect(parse_types("[#{meth}]")).to eq [nil, [meth], '']
      end
    end

    it "only parses #ducktypes inside brackets" do
      expect(parse_types("#ducktype")).to eq [nil, nil, '#ducktype']
    end

    it "returns the text before and after the type list" do
      expect(parse_types(' b  description')).to eq ['b', ['String'], 'description']
      expect(parse_types('b c  description (test)')).to eq [nil, nil, 'b c  description (test)']
    end

    it "does not allow types to start after a newline" do
      v = parse_types("   \n   [X]")
      expect(v).to eq [nil, nil, "[X]"]
    end

    it "handles a complex list of types" do
      v = parse_types(' [Test, Array, String]')
      expect(v).to include(["Test", "Array", "String"])
    end

    it "handles any of the following start/end delimiting chars: (), <>, {}, []" do
      a = parse_types('[a,b,c]')
      b = parse_types('')
      c = parse_types('(a,b,c)')
      d = parse_types('{a,b,c}')
      expect(a).to eq b
      expect(b).to eq c
      expect(c).to eq d
      expect(a).to include(['a', 'b', 'c'])
    end

    it "returns the text before the type list as the last element" do
      expect(parse_types('b[x, y, z]')).to eq ['b', ['x', 'y', 'z'], '']
      expect(parse_types('  ! ')).to eq ["!", ['x'], '']
    end

    it "returns text unparsed if there is no type list" do
      expect(parse_types(nil)).to eq [nil, nil, '']
      expect(parse_types('')).to eq [nil, nil, '']
      expect(parse_types('[]')).to eq [nil, nil, '[]']
    end

    it "allows A => B syntax" do
      v = parse_types(' [Test, Array {B => C}}, C>, String]')
      expect(v).to include(["Test", "Array {B => C}}, C>", "String"])
    end

    it "handles quoted values" do
      v = parse_types(' ["foo, bar", \'baz, qux\', in"them,iddle"]')
      expect(v).to include(["\"foo, bar\"", "'baz, qux'", 'in"them,iddle"'])
    end
  end

  describe "#parse_tag_with_types" do
    def parse_types(text)
      @f.send(:parse_tag_with_types, 'test', text)
    end

    it "parses given types and description" do
      expect(YARD::Tags::Tag).to receive(:new).with("test", "description", ["x", "y", "z"])
      parse_types(' [x, y, z] description')
    end

    it "parses given types only" do
      expect(YARD::Tags::Tag).to receive(:new).with("test", "", ["x", "y", "z"])
      parse_types(' [x, y, z] ')
    end

    it "allows type list to be omitted" do
      expect(YARD::Tags::Tag).to receive(:new).with('test', 'description', nil)
      parse_types('  description    ')
    end

    it "raises an error if a name is specified before type list" do
      expect { parse_types('b desc') }.to raise_error(YARD::Tags::TagFormatError, 'cannot specify a name before type list for \'@test\'')
    end
  end

  describe "#parse_tag_with_types_name_and_default" do
    def parse_types(text)
      @f.send(:parse_tag_with_types_name_and_default, 'test', text)
    end

    it "parses a standard type list with name before types (no default)" do
      expect(YARD::Tags::DefaultTag).to receive(:new).with("test", "description", ["x", "y", "z"], 'NAME', nil)
      parse_types('NAME [x, y, z] description')
    end

    it "parses a standard type list with name after types (no default)" do
      expect(YARD::Tags::DefaultTag).to receive(:new).with("test", "description", ["x", "y", "z"], 'NAME', nil)
      parse_types('  [x, y, z] NAME description')
    end

    it "parses a tag definition with name, typelist and default" do
      expect(YARD::Tags::DefaultTag).to receive(:new).with("test", "description", ["x", "y", "z"], 'NAME', ['default', 'values'])
      parse_types('  [x, y, z] NAME (default, values) description')
    end

    it "parses a tag definition with name, typelist and default when name is before type list" do
      expect(YARD::Tags::DefaultTag).to receive(:new).with("test", "description", ["x", "y", "z"], 'NAME', ['default', 'values'])
      parse_types(' NAME [x, y, z] (default, values) description')
    end

    it "allows typelist to be omitted" do
      expect(YARD::Tags::DefaultTag).to receive(:new).with("test", "description", nil, 'NAME', ['default', 'values'])
      parse_types('  NAME (default, values) description')
    end
  end

  describe "#parse_tag_with_options" do
    def parse_options(text)
      @f.parse_tag_with_options('option', text)
    end

    it "has a name before tag info" do
      t = parse_options("xyz key [Types] (default) description")
      expect(t.tag_name).to eq 'option'
      expect(t.name).to eq 'xyz'
    end

    it "parses the rest of the tag like DefaultTag" do
      t = parse_options("xyz key [Types] (default) description")
      expect(t.pair).to be_instance_of(Tags::DefaultTag)
      expect(t.pair.types).to eq ["Types"]
      expect(t.pair.name).to eq "key"
      expect(t.pair.defaults).to eq ["default"]
      expect(t.pair.text).to eq "description"
    end

    it "allows omitting default" do
      t = parse_options("xyz [Types] key")
      expect(t.pair).to be_instance_of(Tags::DefaultTag)
      expect(t.pair.name).to eq "key"
    end
  end
end
yard-0.9.37/spec/tags/default_tag_spec.rb000066400000000000000000000005441466601756300203000ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Tags::DefaultTag do
  it "creates a tag with defaults" do
    o = YARD::Tags::DefaultTag.new('tagname', 'desc', ['types'], 'name', ['defaults'])
    expect(o.defaults).to eq ['defaults']
    expect(o.tag_name).to eq 'tagname'
    expect(o.name).to eq 'name'
    expect(o.types).to eq ['types']
  end
end
yard-0.9.37/spec/tags/directives_spec.rb000066400000000000000000000334131466601756300201630ustar00rootroot00000000000000# frozen_string_literal: true

def tag_parse(content, object = nil, handler = nil)
  @parser = DocstringParser.new
  @parser.parse(content, object, handler)
  @parser
end

RSpec.describe YARD::Tags::ParseDirective do
  describe "#call" do
    after { Registry.clear }

    it "parses if handler=nil but use file=(stdin)" do
      tag_parse %(@!parse
        # Docstring here
        def foo; end
      )
      expect(Registry.at('#foo').docstring).to eq "Docstring here"
      expect(Registry.at('#foo').file).to eq '(stdin)'
    end

    it "allows parser type to be specified in type" do
      tag_parse %{@!parse [c]
        void Init_Foo() {
          rb_define_method(rb_cMyClass, "foo", foo, 1);
        }
      }
      expect(Registry.at('MyClass#foo')).not_to be nil
    end

    it "parses code in context of current handler" do
      src = <<-eof
        class A
          # @!parse
          #   def foo; end
          eval "def foo; end"
        end
      eof
      parser = YARD::Parser::SourceParser.new
      parser.file = "myfile.rb"
      parser.parse(StringIO.new(src))
      expect(Registry.at('A#foo').file).to eq 'myfile.rb'
    end
  end
end

RSpec.describe YARD::Tags::GroupDirective do
  describe "#call" do
    it "does nothing if handler=nil" do
      tag_parse("@!group foo")
    end

    it "sets group value in parser state (with handler)" do
      handler = OpenStruct.new(:extra_state => OpenStruct.new)
      tag_parse("@!group foo", nil, handler)
      expect(handler.extra_state.group).to eq 'foo'
    end
  end
end

RSpec.describe YARD::Tags::EndGroupDirective do
  describe "#call" do
    it "does nothing if handler=nil" do
      tag_parse("@!endgroup foo")
    end

    it "sets group value in parser state (with handler)" do
      handler = OpenStruct.new(:extra_state => OpenStruct.new(:group => "foo"))
      tag_parse("@!endgroup", nil, handler)
      expect(handler.extra_state.group).to be nil
    end
  end
end

RSpec.describe YARD::Tags::MacroDirective do
  def handler
    OpenStruct.new(:call_params => %w(a b c),
                   :caller_method => 'foo',
                   :scope => :instance, :visibility => :public,
                   :namespace => P('Foo::Bar'),
                   :parser => OpenStruct.new(:file => "(stdin)", :line => 1),
                   :statement => OpenStruct.new(:source => 'foo :a, :b, :c'))
  end

  after(:all) { Registry.clear }

  describe "#call" do
    it "defines new macro when [new] is provided" do
      tag_parse("@!macro [new] foo\n  foo")
      expect(CodeObjects::MacroObject.find('foo').macro_data).to eq 'foo'
    end

    it "defines new macro if text block is provided" do
      tag_parse("@!macro bar\n  bar")
      expect(CodeObjects::MacroObject.find('bar').macro_data).to eq 'bar'
    end

    it "expands macros and return #expanded_text to tag parser" do
      tag_parse("@!macro [new] foo\n  foo")
      expect(tag_parse("@!macro foo").text).to eq 'foo'
    end

    it "does not expand new macro if docstring is unattached" do
      expect(tag_parse("@!macro [new] foo\n  foo").text).not_to eq 'foo'
    end

    it "expands new anonymous macro even if docstring is unattached" do
      expect(tag_parse("@!macro\n  foo").text).to eq 'foo'
    end

    it "allows multiple macros to be expanded" do
      tag_parse("@!macro [new] foo\n  foo")
      tag_parse("@!macro bar\n  bar")
      expect(tag_parse("@!macro foo\n@!macro bar").text).to eq "foo\nbar"
    end

    it "allows anonymous macros" do
      tag_parse("@!macro\n  a b c", nil, handler)
      expect(@parser.text).to eq 'a b c'
    end

    it "expands call_params and caller_method using $N when handler is provided" do
      tag_parse("@!macro\n  $1 $2 $3", nil, handler)
      expect(@parser.text).to eq 'a b c'
    end

    it "attaches macro to method if one exists" do
      tag_parse("@!macro [attach] attached\n  $1 $2 $3", nil, handler)
      macro = CodeObjects::MacroObject.find('attached')
      expect(macro.method_object).to eq P('Foo::Bar.foo')
    end

    it "does not expand new attached macro if defined on class method" do
      baz = CodeObjects::MethodObject.new(P('Foo::Bar'), :baz, :class)
      expect(baz.visibility).to eq :public
      tag_parse("@!macro [attach] attached2\n  @!visibility private", baz, handler)
      macro = CodeObjects::MacroObject.find('attached2')
      expect(macro.method_object).to eq P('Foo::Bar.baz')
      expect(baz.visibility).to eq :public
    end

    it "expands macro if defined on class method and there is no data block" do
      tag_parse("@!macro [new] attached3\n  expanded_data")
      baz = CodeObjects::MethodObject.new(P('Foo::Bar'), :baz, :class)
      doc = DocstringParser.new.parse('@!macro attached3', baz, handler).to_docstring
      expect(doc).to eq 'expanded_data'
    end

    it "does not attach macros to class/modules but creates macro" do
      YARD::Registry.clear
      YARD.parse_string "module Foo; end"
      tag_parse("@!macro [attach] attached4\n  $1 $2 $3", YARD::Registry.at('Foo'), handler)
      macro = CodeObjects::MacroObject.find('attached4')
      expect(macro.method_object).to eq nil
      expect(log.io.string).to match(/Attaching macros to non-methods is unsupported/)
    end

    it "does not attempt to expand macro values if handler = nil" do
      tag_parse("@!macro [attach] xyz\n  $1 $2 $3")
    end
  end
end

RSpec.describe YARD::Tags::MethodDirective do
  describe "#call" do
    after { Registry.clear }

    it "uses entire docstring if no indented data is found" do
      YARD.parse_string <<-eof
        class Foo
          # @!method foo
          # @!method bar
          # @!scope class
        end
      eof
      expect(Registry.at('Foo.foo')).to be_a(CodeObjects::MethodObject)
      expect(Registry.at('Foo.bar')).to be_a(CodeObjects::MethodObject)
    end

    it "handles indented block text in @!method" do
      YARD.parse_string <<-eof
        # @!method foo(a)
        #   Docstring here
        #   @return [String] the foo
        # Ignore this
        # @param [String] a
      eof
      foo = Registry.at('#foo')
      expect(foo.docstring).to eq "Docstring here"
      expect(foo.docstring.tag(:return)).not_to be nil
      expect(foo.tag(:param)).to be nil
    end

    it "executes directives on object in indented block" do
      YARD.parse_string <<-eof
        class Foo
          # @!method foo(a)
          #   @!scope class
          #   @!visibility private
          # @!method bar
          #   Hello
          # Ignore this
        end
      eof
      foo = Registry.at('Foo.foo')
      expect(foo.visibility).to eq :private
      bar = Registry.at('Foo#bar')
      expect(bar.visibility).to eq :public
    end

    it "is able to define multiple @methods in docstring" do
      YARD.parse_string <<-eof
        class Foo
          # @!method foo1
          #   Docstring1
          # @!method foo2
          #   Docstring2
          # @!method foo3
          #   @!scope class
          #   Docstring3
        end
      eof
      foo1 = Registry.at('Foo#foo1')
      foo2 = Registry.at('Foo#foo2')
      foo3 = Registry.at('Foo.foo3')
      expect(foo1.docstring).to eq 'Docstring1'
      expect(foo2.docstring).to eq 'Docstring2'
      expect(foo3.docstring).to eq 'Docstring3'
    end

    it "defines the method inside namespace if attached to namespace object" do
      YARD.parse_string <<-eof
        module Foo
          # @!method foo
          #   Docstring1
          # @!method bar
          #   Docstring2
          class Bar
          end
        end
      eof
      expect(Registry.at('Foo::Bar#foo').docstring).to eq 'Docstring1'
      expect(Registry.at('Foo::Bar#bar').docstring).to eq 'Docstring2'
    end

    it "sets scope to class if signature has 'self.' prefix" do
      YARD.parse_string <<-eof
        # @!method self.foo
        # @!method self. bar
        # @!method self.baz()
        class Foo
        end
      eof
      %w(foo bar baz).each do |name|
        expect(Registry.at("Foo.#{name}")).to be_a(CodeObjects::MethodObject)
      end
    end

    it "defines parameters from signature" do
      YARD.parse_string <<-eof
        # @!method foo(a, b, c = nil)
      eof
      expect(Registry.at('#foo').parameters).to eq [['a', nil], ['b', nil], ['c', 'nil']]
    end

    it "is able to define method with module scope (module function)" do
      YARD.parse_string <<-eof
        # @!method foo
        #   @!scope module
        #   This is a docstring
        #   @return [Boolean] whether this is true
        class Foo
        end
      eof
      foo_c = Registry.at('Foo.foo')
      foo_i = Registry.at('Foo#foo')
      expect(foo_c).not_to be nil
      expect(foo_i).not_to be nil
      expect(foo_c).to be_module_function
      expect(foo_c.docstring).to eq foo_i.docstring
      expect(foo_c.tag(:return).text).to eq foo_i.tag(:return).text
    end
  end
end

RSpec.describe YARD::Tags::AttributeDirective do
  describe "#call" do
    after { Registry.clear }

    it "uses entire docstring if no indented data is found" do
      YARD.parse_string <<-eof
        class Foo
          # @!attribute foo
          # @!attribute bar
          # @!scope class
        end
      eof
      expect(Registry.at('Foo.foo')).to be_reader
      expect(Registry.at('Foo.bar')).to be_reader
    end

    it "handles indented block in @!attribute" do
      YARD.parse_string <<-eof
        # @!attribute foo
        #   Docstring here
        #   @return [String] the foo
        # Ignore this
        # @param [String] a
      eof
      foo = Registry.at('#foo')
      expect(foo.is_attribute?).to be true
      expect(foo.docstring).to eq "Docstring here"
      expect(foo.docstring.tag(:return)).not_to be nil
      expect(foo.tag(:param)).to be nil
    end

    it "is able to define multiple @attributes in docstring" do
      YARD.parse_string <<-eof
        class Foo
          # @!attribute [r] foo1
          #   Docstring1
          # @!attribute [w] foo2
          #   Docstring2
          # @!attribute foo3
          #   @!scope class
          #   Docstring3
        end
      eof
      foo1 = Registry.at('Foo#foo1')
      foo2 = Registry.at('Foo#foo2=')
      foo3 = Registry.at('Foo.foo3')
      foo4 = Registry.at('Foo.foo3=')
      expect(foo1).to be_reader
      expect(foo2).to be_writer
      expect(foo3).to be_reader
      expect(foo1.docstring).to eq 'Docstring1'
      expect(foo2.docstring).to eq 'Docstring2'
      expect(foo3.docstring).to eq 'Docstring3'
      expect(foo4).to be_writer
      expect(foo1.attr_info[:write]).to be nil
      expect(foo2.attr_info[:read]).to be nil
    end

    it "defines the attr inside namespace if attached to namespace object" do
      YARD.parse_string <<-eof
        module Foo
          # @!attribute [r] foo
          # @!attribute [r] bar
          class Bar
          end
        end
      eof
      expect(Registry.at('Foo::Bar#foo')).to be_reader
      expect(Registry.at('Foo::Bar#bar')).to be_reader
    end
  end

  it "sets scope to class if signature has 'self.' prefix" do
    YARD.parse_string <<-eof
      # @!attribute self.foo
      # @!attribute self. bar
      # @!attribute self.baz
      class Foo
      end
    eof
    %w(foo bar baz).each do |name|
      expect(Registry.at("Foo.#{name}")).to be_reader
    end
  end
end

RSpec.describe YARD::Tags::ScopeDirective do
  describe "#call" do
    after { Registry.clear }

    it "sets state on tag parser if object = nil" do
      tag_parse("@!scope class")
      expect(@parser.state.scope).to eq :class
    end

    it "sets state on tag parser if object is namespace" do
      object = CodeObjects::ClassObject.new(:root, 'Foo')
      tag_parse("@!scope class", object)
      expect(object[:scope]).to be nil
      expect(@parser.state.scope).to eq :class
    end

    it "sets scope on object if object is a method object" do
      object = CodeObjects::MethodObject.new(:root, 'foo')
      tag_parse("@!scope class", object)
      expect(object.scope).to eq :class
    end

    %w(class instance module).each do |type|
      it "allows #{type} as value" do
        tag_parse("@!scope #{type}")
        expect(@parser.state.scope).to eq type.to_sym
      end
    end

    %w(invalid foo FOO CLASS INSTANCE).each do |type|
      it "does not allow #{type} as value" do
        tag_parse("@!scope #{type}")
        expect(@parser.state.scope).to be nil
      end
    end
  end
end

RSpec.describe YARD::Tags::VisibilityDirective do
  describe "#call" do
    after { Registry.clear }

    it "sets visibility on tag parser if object = nil" do
      tag_parse("@!visibility private")
      expect(@parser.state.visibility).to eq :private
    end

    it "sets state on tag parser if object is namespace" do
      object = CodeObjects::ClassObject.new(:root, 'Foo')
      tag_parse("@!visibility protected", object)
      expect(object.visibility).to eq :protected
      expect(@parser.state.visibility).to be nil
    end

    it "sets visibility on object if object is a method object" do
      object = CodeObjects::MethodObject.new(:root, 'foo')
      tag_parse("@!visibility private", object)
      expect(object.visibility).to eq :private
    end

    %w(public private protected).each do |type|
      it "allows #{type} as value" do
        tag_parse("@!visibility #{type}")
        expect(@parser.state.visibility).to eq type.to_sym
      end
    end

    %w(invalid foo FOO PRIVATE INSTANCE).each do |type|
      it "does not allow #{type} as value" do
        tag_parse("@!visibility #{type}")
        expect(@parser.state.visibility).to be nil
      end
    end

    it "updates visibility on future methods" do
      Registry.clear
      YARD.parse_string <<-eof
        class Foo
          # @!visibility private


          def foo; end
          def bar; end
          def baz; end
        end
      eof
      %w(foo bar baz).each do |name|
        expect(Registry.at("Foo##{name}").visibility).to eq :private
      end
    end if YARD::Parser::SourceParser.parser_type == :ruby
  end
end
yard-0.9.37/spec/tags/library_spec.rb000066400000000000000000000027451466601756300174720ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Tags::Library do
  def tag(docstring)
    Docstring.new(docstring).tags.first
  end

  describe "#see_tag" do
    it "takes a URL" do
      expect(tag("@see http://example.com").name).to eq "http://example.com"
    end

    it "takes an object path" do
      expect(tag("@see String#reverse").name).to eq "String#reverse"
    end

    it "takes a description after the url/object" do
      tag = tag("@see http://example.com An Example Site")
      expect(tag.name).to eq "http://example.com"
      expect(tag.text).to eq "An Example Site"
    end
  end

  describe ".define_tag" do
    it "allows defining tags with '.' in the name (x.y.z defines method x_y_z)" do
      Tags::Library.define_tag("foo", 'x.y.z')
      Tags::Library.define_tag("foo2", 'x.y.zz', Tags::OverloadTag)
      expect(Tags::Library.instance.method(:x_y_z_tag)).not_to be nil
      expect(Tags::Library.instance.method(:x_y_zz_tag)).not_to be nil
      expect(tag('@x.y.z foo bar').text).to eq 'foo bar'
      expect(tag('@x.y.zz foo(bar)').signature).to eq 'foo(bar)'
    end
  end

  describe "#tag.explain_types" do
    it "can explain tag types" do
      expect(tag("@return [A, B]").explain_types).to eq "an A; a B of (Strings)"
    end

    it "returns nil if no types present" do
      expect(tag("@return").explain_types).to eq nil
    end

    it "returns nil if types are not parsable" do
      expect(tag("@return [$]").explain_types).to eq nil
    end
  end
end
yard-0.9.37/spec/tags/overload_tag_spec.rb000066400000000000000000000031701466601756300204650ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Tags::OverloadTag do
  before do
    @tag = Tags::OverloadTag.new(:overload, <<-'eof')
      def bar(a, b = 1, &block)
        Hello world
        @param a [String]
        @return [String]
    eof
  end

  it "parses the first line as a method signature" do
    expect(@tag.signature).to eq "def bar(a, b = 1, &block)"
    expect(@tag.parameters).to eq [['a', nil], ['b', "1"], ['&block', nil]]
  end

  it "parses the rest of the text as a new Docstring" do
    expect(@tag.docstring).to be_instance_of(Docstring)
    expect(@tag.docstring).to eq "Hello world"
  end

  it "sets Docstring's object after #object= is called" do
    m = double(:object)
    @tag.object = m
    expect(@tag.docstring.object).to eq m
  end

  it "responds to #tag, #tags and #has_tag?" do
    @tag.object = double(:object)
    expect(@tag.tags.size).to eq 2
    expect(@tag.tag(:param).name).to eq "a"
    expect(@tag.has_tag?(:return)).to be true
  end

  it "is not a CodeObjects::Base when not hooked up to an object" do
    @tag.object = nil
    expect(@tag.is_a?(CodeObjects::Base)).to be false
  end

  it "is a CodeObjects::Base when hooked up to an object" do
    @tag.object = double(:object)
    expect(@tag.object).to receive(:is_a?).at_least(3).times.with(CodeObjects::Base).and_return(true)
    expect(@tag.is_a?(CodeObjects::Base)).to be true
    expect(@tag.is_a?(CodeObjects::Base)).to be true
    expect(CodeObjects::Base === @tag).to be true
  end

  it "does not parse 'def' out of method name" do
    tag = Tags::OverloadTag.new(:overload, "default")
    expect(tag.signature).to eq "default"
  end
end
yard-0.9.37/spec/tags/ref_tag_list_spec.rb000066400000000000000000000032441466601756300204630ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Tags::RefTagList do
  before { YARD::Registry.clear }

  it "accepts symbol or string as owner's path and convert it into a proxy" do
    t = Tags::RefTagList.new('author', :String)
    expect(t.owner).to eq P(:String)
  end

  it "accepts proxy object as owner" do
    t = Tags::RefTagList.new('author', P(:String))
    expect(t.owner).to eq P(:String)
  end

  it "returns tags from a proxy object" do
    o = CodeObjects::ClassObject.new(:root, :String)
    t = Tags::Tag.new(:author, 'foo')
    o.docstring.add_tag(t)

    ref = Tags::RefTagList.new('author', :String)
    expect(ref.tags).to eq [t]
    expect(ref.tags.first.text).to eq 'foo'
  end

  it "returns named tags from a proxy object" do
    o = CodeObjects::ClassObject.new(:root, :String)
    p1 = Tags::Tag.new(:param, 'bar1', nil, 'foo')
    p2 = Tags::Tag.new(:param, 'bar2', nil, 'foo')
    p3 = Tags::Tag.new(:param, 'bar3', nil, 'bar')
    t1 = Tags::Tag.new(:return, 'blah')
    o.docstring.add_tag(p1, t1, p2, p3)

    ref = Tags::RefTagList.new('param', :String, 'foo')
    expect(ref.tags).to eq [p1, p2]
    expect(ref.tags.first.text).to eq 'bar1'
  end

  it "all tags should respond to #owner and be a RefTag" do
    o = CodeObjects::ClassObject.new(:root, :String)
    p1 = Tags::Tag.new(:param, 'bar1', nil, 'foo')
    p2 = Tags::Tag.new(:param, 'bar2', nil, 'foo')
    p3 = Tags::Tag.new(:param, 'bar3', nil, 'bar')
    t1 = Tags::Tag.new(:return, 'blah')
    o.docstring.add_tag(p1, t1, p2, p3)

    ref = Tags::RefTagList.new('param', :String)
    ref.tags.each do |t|
      expect(t).to be_kind_of(Tags::RefTag)
      expect(t.owner).to eq o
    end
  end
end
yard-0.9.37/spec/tags/types_explainer_spec.rb000066400000000000000000000154501466601756300212360ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Tags::TypesExplainer do
  Type = YARD::Tags::TypesExplainer::Type
  CollectionType = YARD::Tags::TypesExplainer::CollectionType
  FixedCollectionType = YARD::Tags::TypesExplainer::FixedCollectionType
  HashCollectionType = YARD::Tags::TypesExplainer::HashCollectionType
  Parser = YARD::Tags::TypesExplainer::Parser

  def parse(types)
    Parser.new(types).parse
  end

  def parse_fail(types)
    expect { parse(types) }.to raise_error(SyntaxError)
  end

  describe Type, '#to_s' do
    before { @t = Type.new(nil) }

    it "works for a class/module reference" do
      @t.name = "ClassModuleName"
      expect(@t.to_s).to eq "a ClassModuleName"
      expect(@t.to_s(false)).to eq "ClassModuleNames"

      @t.name = "XYZ"
      expect(@t.to_s).to eq "a XYZ"
      expect(@t.to_s(false)).to eq "XYZ's"

      @t.name = "Array"
      expect(@t.to_s).to eq "an Array"
      expect(@t.to_s(false)).to eq "Arrays"
    end

    it "works for a method (ducktype)" do
      @t.name = "#mymethod"
      expect(@t.to_s).to eq "an object that responds to #mymethod"
      expect(@t.to_s(false)).to eq "objects that respond to #mymethod"
    end

    it "works for a constant value" do
      ['false', 'true', 'nil', '4'].each do |name|
        @t.name = name
        expect(@t.to_s).to eq name
        expect(@t.to_s(false)).to eq name
      end
    end
  end

  describe CollectionType, '#to_s' do
    before { @t = CollectionType.new("Array", nil) }

    it "can contain one item" do
      @t.types = [Type.new("Object")]
      expect(@t.to_s).to eq "an Array of (Objects)"
    end

    it "can contain more than one item" do
      @t.types = [Type.new("Object"), Type.new("String"), Type.new("Symbol")]
      expect(@t.to_s).to eq "an Array of (Objects, Strings or Symbols)"
    end

    it "can contain nested collections" do
      @t.types = [CollectionType.new("List", [Type.new("Object")])]
      expect(@t.to_s).to eq "an Array of (a List of (Objects))"
    end
  end

  describe FixedCollectionType, '#to_s' do
    before { @t = FixedCollectionType.new("Array", nil) }

    it "can contain one item" do
      @t.types = [Type.new("Object")]
      expect(@t.to_s).to eq "an Array containing (an Object)"
    end

    it "can contain more than one item" do
      @t.types = [Type.new("Object"), Type.new("String"), Type.new("Symbol")]
      expect(@t.to_s).to eq "an Array containing (an Object followed by a String followed by a Symbol)"
    end

    it "can contain nested collections" do
      @t.types = [FixedCollectionType.new("List", [Type.new("Object")])]
      expect(@t.to_s).to eq "an Array containing (a List containing (an Object))"
    end
  end

  describe FixedCollectionType, '#to_s' do
    before { @t = HashCollectionType.new("Hash", nil, nil) }

    it "can contain a single key type and value type" do
      @t.key_types = [Type.new("Object")]
      @t.value_types = [Type.new("Object")]
      expect(@t.to_s).to eq "a Hash with keys made of (Objects) and values of (Objects)"
    end

    it "can contain multiple key types" do
      @t.key_types = [Type.new("Key"), Type.new("String")]
      @t.value_types = [Type.new("Object")]
      expect(@t.to_s).to eq "a Hash with keys made of (Keys or Strings) and values of (Objects)"
    end

    it "can contain multiple value types" do
      @t.key_types = [Type.new("String")]
      @t.value_types = [Type.new("true"), Type.new("false")]
      expect(@t.to_s).to eq "a Hash with keys made of (Strings) and values of (true or false)"
    end
  end

  describe Parser, '#parse' do
    it "parses a regular class name" do
      type = parse("MyClass")
      expect(type.size).to eq 1
      expect(type.first).to be_a(Type)
      expect(type.first.name).to eq "MyClass"
    end

    it "parses a path reference name" do
      type = parse("A::B")
      expect(type.size).to eq 1
      expect(type.first).to be_a(Type)
      expect(type.first.name).to eq "A::B"
    end

    it "parses a list of simple names" do
      type = parse("A, B::C, D, E")
      expect(type.size).to eq 4
      expect(type[0].name).to eq "A"
      expect(type[1].name).to eq "B::C"
      expect(type[2].name).to eq "D"
      expect(type[3].name).to eq "E"
    end

    it "parses a collection type" do
      type = parse("MyList")
      expect(type.first).to be_a(CollectionType)
      expect(type.first.types.size).to eq 1
      expect(type.first.name).to eq "MyList"
      expect(type.first.types.first.name).to eq "String"
    end

    it "allows a collection type without a name" do
      type = parse("")
      expect(type.first.name).to eq "Array"
    end

    it "allows a fixed collection type without a name" do
      type = parse("(String)")
      expect(type.first.name).to eq "Array"
    end

    it "allows a hash collection type without a name" do
      type = parse("{K=>V}")
      expect(type.first.name).to eq "Hash"
    end

    it "does not accept two commas in a row" do
      parse_fail "A,,B"
    end

    it "does not accept two types not separated by a comma" do
      parse_fail "A B"
    end

    it "does not allow a comma without a following type" do
      parse_fail "A, "
    end

    it "fails on any unrecognized character" do
      parse_fail "$"
    end
  end

  describe ".explain" do
    it "parses an arbitrarily nested collection type" do
      explain = YARD::Tags::TypesExplainer.explain("ArrayV})>>")
      result = "an Array of (Strings or an Array of (Symbols or a List containing
        (a String followed by a Hash with keys made of (K's) and values of (V's))))"
      expect(explain).to eq result.delete("\n").squeeze(' ')
    end

    it "parses various examples" do
      expect = {
        "Fixnum, Foo, Object, true" => "a Fixnum; a Foo; an Object; true",
        "#read" => "an object that responds to #read",
        "Array" => "an Array of (Strings, Symbols or objects that respond to #read)",
        "Set" => "a Set of (Numbers)",
        "Array(String, Symbol)" => "an Array containing (a String followed by a Symbol)",
        "Hash{String => Symbol, Number}" => "a Hash with keys made of (Strings) and values of (Symbols or Numbers)",
        "Array, List(String, Symbol, #to_s), {Foo, Bar => Symbol, Number}" => "an Array of (Foos or Bars);
          a List containing (a String followed by a Symbol followed by an object that responds to #to_s);
          a Hash with keys made of (Foos or Bars) and values of (Symbols or Numbers)",
        "#weird_method?, #<=>, #!=" => "an object that responds to #weird_method?;
          an object that responds to #<=>;
          an object that responds to #!="
      }
      expect.each do |input, expected|
        explain = YARD::Tags::TypesExplainer.explain(input)
        expect(explain).to eq expected.delete("\n").squeeze(' ')
      end
    end
  end
end
yard-0.9.37/spec/templates/000077500000000000000000000000001466601756300155175ustar00rootroot00000000000000yard-0.9.37/spec/templates/class_spec.rb000066400000000000000000000020201466601756300201550ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Templates::Engine.template(:default, :docstring) do
  before do
    Registry.clear
    YARD.parse_string <<-'eof'
      private
      # Comments
      # @abstract override this class
      # @author Test
      # @version 1.0
      # @see A
      # @see http://example.com Example
      class A < B
        # HI
        def method_missing(*args) end
        # @deprecated
        def a; end

        # constructor method!
        def initialize(test) end
      end

      class C < A; end

      class D
        # @private
        def initialize; end
      end
    eof
  end

  it "renders html format correctly" do
    html_equals(Registry.at('A').format(html_options), :class001)
  end

  it "renders text format correctly" do
    text_equals(Registry.at('A').format, :class001)
  end

  it "hides private constructors" do
    html_equals(Registry.at('D').format(html_options(:verifier => Verifier.new("!@private"))), :class002)
  end
end
yard-0.9.37/spec/templates/constant_spec.rb000066400000000000000000000026741466601756300207200ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/spec_helper"

RSpec.describe YARD::Templates::Engine.template(:default, :constant) do
  describe "fully dressed constant" do
    it "renders text format correctly" do
      YARD.parse_string <<-'eof'
        class YARD::CLI::YRI
          # Default search paths that should be loaded dynamically into YRI. These paths
          # take precedence over all other paths ({SEARCH_PATHS_FILE} and RubyGems
          # paths). To add a path, call:
          #
          #   DEFAULT_SEARCH_PATHS.push("/path/to/.yardoc")
          #
          # @return [Array] a list of extra search paths
          # @since 0.6.0
          DEFAULT_SEARCH_PATHS = []
        end
      eof
      text_equals(Registry.at('YARD::CLI::YRI::DEFAULT_SEARCH_PATHS').format(text_options), :constant001)
    end
  end

  describe "simple constant with no documentation" do
    it "renders text format correctly" do
      # Short constant should show on single line
      YARD.parse_string <<-'eof'
        MYCONST = 'foo'
      eof
      text_equals(Registry.at('MYCONST').format(text_options), :constant002)

      # Long constant should show on multiple lines, indented
      YARD.parse_string <<-'eof'
        MYCONST = [A, B, C, D, E, F, G, H, I, J, K, L,
          M, N, O, P, Q, R, S, T, U, V, W,
          X, Y, Z]
      eof
      text_equals(Registry.at('MYCONST').format(text_options), :constant003)
    end
  end
end
yard-0.9.37/spec/templates/engine_spec.rb000066400000000000000000000114321466601756300203240ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Templates::Engine do
  before { @paths = Engine.template_paths }
  after { Engine.template_paths = @paths }

  describe ".register_template_path" do
    it "registers a String path" do
      Engine.register_template_path('.')
      expect(Engine.template_paths.pop).to eq '.'
    end

    it "does not duplicate paths" do
      Engine.template_paths = []
      Engine.register_template_path('foo')
      Engine.register_template_path('foo')
      expect(Engine.template_paths).to eq ['foo']
    end
  end

  describe ".template!" do
    it "creates a module including Template" do
      mod = Engine.template!('path/to/template')
      expect(mod).to include(Template)
      expect(mod.full_path.to_s).to eq 'path/to/template'
    end

    it "creates a module including Template with full_path" do
      mod = Engine.template!('path/to/template2', '/full/path/to/template2')
      expect(mod).to include(Template)
      expect(mod.full_path.to_s).to eq '/full/path/to/template2'
    end
  end

  describe ".template" do
    it "raises an error if the template is not found" do
      expect { Engine.template(:a, :b, :c) }.to raise_error(ArgumentError)
    end

    it "creates a module including Template" do
      mock = double(:template)
      expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(['/full/path/template/name'])
      expect(Engine).to receive(:template!).with('template/name', ['/full/path/template/name']).and_return(mock)
      expect(Engine.template('template/name')).to eq mock
    end

    it "creates a Template from a relative Template path" do
      expect(Engine).to receive(:template_paths).and_return([])
      expect(File).to receive(:directory?).with("/full/path/template/notname").and_return(true)
      start_template = double(:start_template,
        :full_path  => '/full/path/template/name',
        :full_paths => ['/full/path/template/name'])
      expect(start_template).to receive(:is_a?).with(Template).and_return(true)
      mod = Engine.template(start_template, '..', 'notname')
      expect(mod).to include(Template)
      expect(mod.full_path.to_s).to eq "/full/path/template/notname"
    end

    it "creates a Template including other matching templates in path" do
      paths = ['/full/path/template/name', '/full/path2/template/name']
      expect(Engine).to receive(:find_template_paths).with(nil, 'template').at_least(1).times.and_return([])
      expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(paths)
      ancestors = Engine.template('template/name').ancestors.map(&:class_name)
      expect(ancestors).to include("Template__full_path2_template_name")
    end

    it "includes parent directories before other template paths" do
      paths = ['/full/path/template/name', '/full/path2/template/name']
      expect(Engine).to receive(:find_template_paths).with(nil, 'template/name').and_return(paths)
      ancestors = Engine.template('template/name').ancestors.map(&:class_name)
      expect(ancestors[0, 4]).to eq ["Template__full_path_template_name", "Template__full_path_template",
        "Template__full_path2_template_name", "Template__full_path2_template"]
    end
  end

  describe ".generate" do
    it "generates with fulldoc template" do
      mod = double(:template)
      options = TemplateOptions.new
      options.reset_defaults
      options.objects = [:a, :b, :c]
      options.object = Registry.root
      expect(mod).to receive(:run).with(options)
      expect(Engine).to receive(:template).with(:default, :fulldoc, :text).and_return(mod)
      Engine.generate([:a, :b, :c])
    end
  end

  describe ".render" do
    def loads_template(*args)
      expect(Engine).to receive(:template).with(*args).and_return(@template)
    end

    before(:all) do
      @object = CodeObjects::MethodObject.new(:root, :method)
    end

    before do
      @options = TemplateOptions.new
      @options.reset_defaults
      @options.object = @object
      @options.type = @object.type
      @template = double(:template, :include => nil)
      expect(@template).to receive(:run).with(@options)
    end

    it "accepts method call with no parameters" do
      loads_template(:default, :method, :text)
      @object.format
    end

    it "allows template key to be changed" do
      loads_template(:javadoc, :method, :text)
      @options.template = :javadoc
      @object.format(:template => :javadoc)
    end

    it "allows type key to be changed" do
      loads_template(:default, :fulldoc, :text)
      @options.type = :fulldoc
      @object.format(:type => :fulldoc)
    end

    it "allows format key to be changed" do
      loads_template(:default, :method, :html)
      @options.format = :html
      @object.format(:format => :html)
    end
  end
end
yard-0.9.37/spec/templates/examples/000077500000000000000000000000001466601756300173355ustar00rootroot00000000000000yard-0.9.37/spec/templates/examples/class001.html000066400000000000000000000111621466601756300215520ustar00rootroot00000000000000
    Class: A
  Abstract
  
  

    

    
  
  
    
    
    Inherits:
    
    
    
      B
      
        
      
          
    • Object
      • 
          
            
          
            
          
        
    
        show all
      
    
    
  
    
  

  
  
  
  
  

  

  
  
    
    
    Defined in:
    
    
    (stdin)
    
  
    
  

    


    Overview
    
  
    
    
    
  This class is abstract.
  
    override this class
    

    
Comments

  
    

    

    
  

  
    See Also:
    
  

    Author:
    

      
  
    
    • 
      
      
      
      
        
        
      Test
      
      
    
      • 
  

    

    Version:
    

      
  
    
    • 
      
      
      
      
        
        
      1.0
      
      
    
      • 
  

    


    
  
    Direct Known Subclasses
    
  
    C
    

    







  
    
    
      Instance Method Summary
      collapse
    
    

    
  


  
    
  
    Constructor Details
    
  
    
    
  
    
  
    #initialize(test)  ⇒ A 
  

  

  

    
  
    
    constructor method!

  
    

    

    
  


    
  
    
    
      
    

15
    
        		
    
      
    # File '(stdin)', line 15

def initialize(test) end
    
        		
  
    

    

    
  

    

    
  
    Dynamic Method Handling
    
  
    
    This class handles dynamic methods through the method_missing method
    
  
    
  
    
    
  
    
  
    #method_missing(*args)  
  

  

  

    
  
    
    HI

  
    

    

    
  


    
  
    
    
      
    

10
    
        		
    
      
    # File '(stdin)', line 10

def method_missing(*args) end
    
        		
  
    

    

    
  

    


  
    
    
    Instance Method Details
    

    
      
    
  
    
  
    #a  
  

  

  

    
  
    
    
    Deprecated. 
    


  
    

    

    
  


    
  
    
    
      
    

12
    
        		
    
      
    # File '(stdin)', line 12

def a; end
    
        		
  
    

    

    
    
  
    
yard-0.9.37/spec/templates/examples/class001.txt000066400000000000000000000007021466601756300214230ustar00rootroot00000000000000----------------------------------------------------------- Class: A < B

    Abstract. override this class

    Comments 

See Also:
---------

    - A
    - http://example.com - Example

Author:
-------

    Test

Version:
--------

    1.0


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

Direct Known Subclasses:
------------------------

    C

Instance methods:
-----------------

    a, initialize, method_missing


yard-0.9.37/spec/templates/examples/class002.html000066400000000000000000000007061466601756300215550ustar00rootroot00000000000000
    Class: D
  
  
  

    

    
  
  
    
    
    Inherits:
    
    
    
      Object
      
        
      
          
    • Object
      • 
          
            
          
        
    
        show all
      
    
    
  
    
  

  
  
  
  
  

  

  
  
    
    
    Defined in:
    
    
    (stdin)
    
  
    
  

    
yard-0.9.37/spec/templates/examples/constant001.txt000066400000000000000000000011201466601756300221420ustar00rootroot00000000000000------------------------- Constant: YARD::CLI::YRI::DEFAULT_SEARCH_PATHS

DEFAULT_SEARCH_PATHS = []

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

    Default search paths that should be loaded dynamically into YRI.
    These paths take precedence over all other paths (SEARCH_PATHS_FILE
    and RubyGems paths). To add a path, call: 
    
      DEFAULT_SEARCH_PATHS.push("/path/to/.yardoc")

Returns:
--------

    (Array) - a list of extra search paths


Since:
------

    0.6.0


------------------------------------------------------------------------yard-0.9.37/spec/templates/examples/constant002.txt000066400000000000000000000003551466601756300221540ustar00rootroot00000000000000------------------------------------------------------ Constant: MYCONST

MYCONST = 'foo'

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

------------------------------------------------------------------------yard-0.9.37/spec/templates/examples/constant003.txt000066400000000000000000000005041466601756300221510ustar00rootroot00000000000000------------------------------------------------------ Constant: MYCONST

MYCONST = 

    [A, B, C, D, E, F, G, H, I, J, K, L,
    M, N, O, P, Q, R, S, T, U, V, W,
    X, Y, Z]

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

------------------------------------------------------------------------yard-0.9.37/spec/templates/examples/method001.html000066400000000000000000000046751466601756300217400ustar00rootroot00000000000000
    Method: #m
    

    
  
    
    
    Defined in:
    
    
    
    (stdin)
    
    
  
    

    


    
  
    
    
    
  
    
  
    #m(x)  ⇒ String  (private)
  

  
    Also known as:
    x
    
  

  

    
  
    
    
    Deprecated. 
    for great justice
    
Comments

  
    

    

    
  
    Parameters:
    

      
  
    
    • 
      
        x
      
      
        (Hash)
      
      
      
        —
        
      the x argument
      
      
    
      • 
  

    

  
    
    
    
    Options Hash (x):
    
    
      
      
        
    • 
          :key1
          (String)
          
            
              — default:
              default
            
          
          
            — 
      first key
      
          
        
      • 
      
        
    • 
          :key2
          (Symbol)
          
            
          
          
            — 
      second key
      
          
        
      • 
      
    
    
  


    Returns:
    

      
  
    
    • 
      
      
        (String)
      
      
      
        —
        
      the result
      
      
    
      • 
  

    

    Raises:
    

      
  
    
    • 
      
      
        (Exception)
      
      
      
        —
        
      hi!
      
      
    
      • 
  

    


    
  
    
    
      
    

9
    
        		
    
      
    # File '(stdin)', line 9

def m(x) end
    
        		
  
    

    

    
  
    

    
yard-0.9.37/spec/templates/examples/method001.txt000066400000000000000000000012031466601756300215730ustar00rootroot00000000000000------------------------------------------------------------- Method: #m
                                                   (Defined in: (stdin))
                                                     (Also known as: #x)

    root.m(x) -> String (private)
------------------------------------------------------------------------

    Deprecated. for great justice

    Comments 

Parameters:
-----------

    (Hash) x - the x argument

Options Hash (x):
-----------------

    (String) :key1 - default: default - first key

    (Symbol) :key2 - second key

Returns:
--------

    (String) - the result

Raises:
-------

    (Exception) - hi!



yard-0.9.37/spec/templates/examples/method002.html000066400000000000000000000025151466601756300217300ustar00rootroot00000000000000
    Method: #m
    

    
  
    
    
    Defined in:
    
    
    
    (stdin)
    
    
  
    

    


    
  
    
    
    
  
    
  
    #m(x, y)   (private)
  

  

  

    
  
    
    Comments

  
    

    

    
  
  
    
  
    
    

  
    

    

    
  
    Parameters:
    

      
  
    
    • 
      
        x
      
      
        (String)
      
      
      
        —
        
      parameter x
      
      
    
      • 
  
    
    • 
      
        y
      
      
        (Boolean)
      
      
      
        —
        
      parameter y
      
      
    
      • 
  

    



    



    
  
    
    
      
    

6
    
        		
    
      
    # File '(stdin)', line 6

def m(x) end
    
        		
  
    

    

    
  
    

    
yard-0.9.37/spec/templates/examples/method002.txt000066400000000000000000000005461466601756300216050ustar00rootroot00000000000000------------------------------------------------------------- Method: #m
                                                   (Defined in: (stdin))

    root.m(x, y) (private)
------------------------------------------------------------------------

    Comments 


    
Parameters:
-----------

    (String) x - parameter x

    (Boolean) y - parameter y




yard-0.9.37/spec/templates/examples/method003.html000066400000000000000000000052311466601756300217270ustar00rootroot00000000000000
    Method: #m
    

    
  
    
    
    Defined in:
    
    
    
    (stdin)
    
    
  
    

    


    
  
    
    
    
  
    
  
    
      #m(x, y)   (private)
    
      #m(x, y, z)   (private)
    
  

  

  

    
  
    
    Method comments

  
    

    

    
  
  
    Overloads:
    
  
      
    
      
      
    • 
        #m(x, y)  
        
      
  
      
    Overload docstring

  
      

      

      
  
      Parameters:
      

        
  
    
      • 
      
        x
      
      
        (String)
      
      
      
        —
        
        parameter x
        
      
    
        • 
  
    
      • 
      
        y
      
      
        (Boolean)
      
      
      
        —
        
        parameter y
        
      
    
        • 
  

      



      
      
      • 
    
      
      
    • 
        #m(x, y, z)  
        
      
  
      
    

  
      

      

      
  
      Parameters:
      

        
  
    
      • 
      
        x
      
      
        (String)
      
      
      
        —
        
        parameter x
        
      
    
        • 
  
    
      • 
      
        y
      
      
        (Boolean)
      
      
      
        —
        
        parameter y
        
      
    
        • 
  
    
      • 
      
        z
      
      
        (Boolean)
      
      
      
        —
        
        parameter z
        
      
    
        • 
  

      



      
      
      • 
    
  
    



    
  
    
    
      
    

11
    
        		
    
      
    # File '(stdin)', line 11

def m(*args) end
    
        		
  
    

    

    
  
    

    
yard-0.9.37/spec/templates/examples/method003.txt000066400000000000000000000017551466601756300216110ustar00rootroot00000000000000------------------------------------------------------------- Method: #m
                                                   (Defined in: (stdin))

    root.m(x, y) (private)
    root.m(x, y, z) (private)
------------------------------------------------------------------------

    Method comments 

Overloads:
----------

------------------------------------------------------------------------
    root.m(x, y) (private)
------------------------------------------------------------------------
    
        Overload docstring 
    
    Parameters:
    -----------
    
        (String) x - parameter x
    
        (Boolean) y - parameter y
    
    

------------------------------------------------------------------------
    root.m(x, y, z) (private)
------------------------------------------------------------------------
    
        
    Parameters:
    -----------
    
        (String) x - parameter x
    
        (Boolean) y - parameter y
    
        (Boolean) z - parameter z
    
    



yard-0.9.37/spec/templates/examples/method004.html000066400000000000000000000014351466601756300217320ustar00rootroot00000000000000
    Method: #m
    

    
  
    
    
    Defined in:
    
    
    
    (stdin)
    
    
  
    

    


    
  
    
    
    
  
    
  
    #m(*args)  ⇒ void 
  

  

  

    
  
    
    
    This method returns an undefined value.
    

  
    

    

    
  


    
  
    
    
      
    

2
    
        		
    
      
    # File '(stdin)', line 2

def m(*args) end
    
        		
  
    

    

    
  
    

    
yard-0.9.37/spec/templates/examples/method004.txt000066400000000000000000000004531466601756300216040ustar00rootroot00000000000000------------------------------------------------------------- Method: #m
                                                   (Defined in: (stdin))

    root.m(*args) -> void 
------------------------------------------------------------------------

    This method returns an undefined value.
    


yard-0.9.37/spec/templates/examples/method005.html000066400000000000000000000033151466601756300217320ustar00rootroot00000000000000
    Method: #m
    

    
  
    
    
    Defined in:
    
    
    
    (stdin)
    
    
  
    

    


    
  
    
    
    
  
    
  
    
      #m(a)  ⇒ void 
    
      #m(b)  
    
  

  

  

    
  
    
    

  
    

    

    
  
  
    Overloads:
    
  
      
    
      
      
    • 
        #m(a)  ⇒ void 
        
      
  
      
    
      This method returns an undefined value.
      

  
      

      

      
  


      
      
      • 
    
      
      
    • 
        #m(b)  
        
      
  
      
    

  
      

      

      
  
      Parameters:
      

        
  
    
      • 
      
        b
      
      
        (String)
      
      
      
        —
        
        hi
        
      
    
        • 
  

      



      
      
      • 
    
  
    



    
  
    
    
      
    

5
    
        		
    
      
    # File '(stdin)', line 5

def m(*args) end
    
        		
  
    

    

    
  
    

    
yard-0.9.37/spec/templates/examples/method005.txt000066400000000000000000000014051466601756300216030ustar00rootroot00000000000000------------------------------------------------------------- Method: #m
                                                   (Defined in: (stdin))

    root.m(a) -> void 
    root.m(b) 
------------------------------------------------------------------------

    
Overloads:
----------

------------------------------------------------------------------------
    root.m(a) -> void 
------------------------------------------------------------------------
    
        This method returns an undefined value.
        
    

------------------------------------------------------------------------
    root.m(b) 
------------------------------------------------------------------------
    
        
    Parameters:
    -----------
    
        (String) b - hi
    
    



yard-0.9.37/spec/templates/examples/method006.html000066400000000000000000000032551466601756300217360ustar00rootroot00000000000000
    Method: #m
    

    
  
    
    
    Defined in:
    
    
    
    (stdin)
    
    
  
    

    


    
  
    
    
    
  
    
  
    #m(x, y, *args, kword1: 123, kword2:)  
  

  

  

    
  
    
    

  
    

    

    
  
    Parameters:
    

      
  
    
    • 
      
        x
      
      
        (String)
      
      
      
        —
        
      the x argument
      
      
    
      • 
  
    
    • 
      
        y
      
      
        (Boolean)
      
      
      
        —
        
      the y argument
      
      
    
      • 
  
    
    • 
      
        keyword
      
      
        (kword1)
      
      
      
        —
        
      1
      
      
    
      • 
  
    
    • 
      
        keyword
      
      
        (kword2)
      
      
      
        —
        
      2
      
      
    
      • 
  

    



    
  
    
    
      
    

5
    
        		
    
      
    # File '(stdin)', line 5

def m(x, y, *args, kword1: 123, kword2:, **) end
    
        		
  
    

    

    
  
    

    yard-0.9.37/spec/templates/examples/method006.txt000066400000000000000000000006431466601756300216070ustar00rootroot00000000000000------------------------------------------------------------- Method: #m
                                                   (Defined in: (stdin))

    root.m(x, y, *args, kword1: 123, kword2:) 
------------------------------------------------------------------------

    
Parameters:
-----------

    (String) x - the x argument

    (Boolean) y - the y argument

    (kword1) keyword - 1

    (kword2) keyword - 2



yard-0.9.37/spec/templates/examples/module001.dot000066400000000000000000000012731466601756300215560ustar00rootroot00000000000000A [label="{module A|+ \#attr1 [RW]\l+ \#attr2 [R]\l+ \#attr3 [RW]\l+ \#attr4 [W]\l|+ a\l+ \#a\l+ \#test_multi_overload\l+ \#test_overload\l+ \#void_meth\ \:\ void\l}" rank=sink];
A_Y [label="{class Y||}" rank=sink];
subgraph cluster_A_Y {
  label = "Y"; labelloc=b;
  
}

A_Q [label="{class Q||}" rank=sink];
subgraph cluster_A_Q {
  label = "Q"; labelloc=b;
  
}

A_X [label="{class X||}" rank=sink];
subgraph cluster_A_X {
  label = "X"; labelloc=b;
  
}
subgraph cluster_A {
  label = "A"; labelloc=b;
  
    A_Z [label="{module Z||}" rank=sink];
subgraph cluster_A_Z {
  label = "Z"; labelloc=b;
  
}

  
}

  A -> B [style=dotted arrowType=none];

  A -> BaseMod [style=dotted arrowType=none];
yard-0.9.37/spec/templates/examples/module001.html000066400000000000000000000300111466601756300217240ustar00rootroot00000000000000
    Module: A
  
  
  

    

    
  

  
  
  
  
  
    
      
    Includes:
    
      
    B, BaseMod
    
  
    
  
  

  
  
    
    
    Included in:
    
    
    TMP, TMP2
    
  
    
  

  
  
    
    
    Defined in:
    
    
    (stdin)
    
  
    
  

    


    Overview
    
  
    
    Comments

  
    

    

    
  


    Defined Under Namespace
    

    
  
    
      Modules: Z
    
  
    
      Classes: Q, X, Y
    
  

    

  
    
    Constant Summary

    collapse
  
    
  
    
    
      
        
    CONSTANT =
          
    
  
    
    A long docstring for the constant. With extra text
and newlines.

  
    

    

    
  


    
        
    
        
    'value'
    
      
        
    @@cvar =
          
    
  
    
    
    Deprecated. 
    


  
    

    

    
  


    
        
    
        
    'value'
    
      
    
    
  




  
    Instance Attribute Summary collapse
    
  
      
    
      
    • 
  
    
      #attr1  
    

    
  
  
  
  
    
    
  
  
  
  
  

  
    
      Returns the value of attribute attr1.
      
  

      • 

    
      
    • 
  
    
      #attr2  
    

    
  
  
  
  
    
      readonly
    
    
  
  
  
  
  

  
    
      Returns the value of attribute attr2.
      
  

      • 

    
      
    • 
  
    
      #attr3  
    

    
  
  
  
  
    
    
  
  
  
  
  

  
    
      
  

      • 

    
      
    • 
  
    
      #attr4  
    

    
  
  
  
  
    
    
      writeonly
    
  
  
  
  
  

  
    
      Sets the attribute attr4.
      
  

      • 

    
  
    



  
  
  
    Attributes included from BaseMod
    
  
    #base_attr1, #base_attr2, #base_attr3
    


  
    
    
      Class Method Summary
      collapse
    
    

    
  
    
    
      Instance Method Summary
      collapse
    
    

    
  


  
  
  
  
  
  
  
  
  
    Methods included from B
    
  
    #c, #d
    

  
  
  
  
  
  
  
    
    
    Instance Attribute Details
    
    
      
      
      
    
  
    
  
    #attr1  
  

  

  

    
  
    
    Returns the value of attribute attr1.

  
    

    

    
  


    
  
    
    
      
    

17
18
19
    
        		
    
      
    # File '(stdin)', line 17

def attr1
  @attr1
end
    
        		
  
    

    

    
    
      
      
      
    
  
    
  
    #attr2   (readonly)
  

  

  

    
  
    
    Returns the value of attribute attr2.

  
    

    

    
  


    
  
    
    
      
    

18
19
20
    
        		
    
      
    # File '(stdin)', line 18

def attr2
  @attr2
end
    
        		
  
    

    

    
    
      
      
      
    
  
    
  
    
      #attr3  ⇒ String 
    
      #attr3=(value)  
    
  

  

  

    
  
    
    

  
    

    

    
  
  
    Overloads:
    
  
      
    
      
      
    • 
        #attr3  ⇒ String 
        
      
  
      
    Returns a string.

  
      

      

      
  

      Returns:
      

        
  
    
      • 
      
      
        (String)
      
      
      
        —
        
        a string
        
      
    
        • 
  

      


      
      
      • 
    
      
      
    • 
        #attr3=(value)  
        
      
  
      
    
      This method returns an undefined value.
      

  
      

      

      
  
      Parameters:
      

        
  
    
      • 
      
        value
      
      
        (String)
      
      
      
        —
        
        sets the string
        
      
    
        • 
  

      



      
      
      • 
    
  
    



    
  
    
    
      
    

25
26
27
    
        		
    
      
    # File '(stdin)', line 25

def attr3
  @attr3
end
    
        		
  
    

    

    
    
      
      
      
    
  
    
  
    #attr4=(value)   (writeonly)
  

  

  

    
  
    
    Sets the attribute attr4

  
    

    

    
  
    Parameters:
    

      
  
    
    • 
      
        value
      
      
        
      
      
      
        —
        
      the value to set the attribute attr4 to.
      
      
    
      • 
  

    



    
  
    
    
      
    

27
28
29
    
        		
    
      
    # File '(stdin)', line 27

def attr4=(value)
  @attr4 = value
end
    
        		
  
    

    

    
    
  
    


  
    
    
    Class Method Details
    

    
      
    
  
    
  
    .a  
  

  

  

    
  
    
    
      
    

29
    
        		
    
      
    # File '(stdin)', line 29

def self.a; end
    
        		
  
    

    

    
    
  
    

  
    
    
    Instance Method Details
    

    
      
    
  
    
  
    #a  
  

  
    Also known as:
    b
    
  

  

    
  
    
    
      
    

30
    
        		
    
      
    # File '(stdin)', line 30

def a; end
    
        		
  
    

    

    
    
      
    
  
    
  
    
      #test_multi_overload(a)  
    
      #test_multi_overload(a, b)  
    
  

  

  

    
  
    
    

  
    

    

    
  


    
  
    
    
      
    

40
    
        		
    
      
    # File '(stdin)', line 40

def test_multi_overload(*args) end
    
        		
  
    

    

    
    
      
    
  
    
  
    #test_overload(a)  
  

  

  

    
  
    
    

  
    

    

    
  
  
    
  
    
    hello2

  
    

    

    
  
    Parameters:
    

      
  
    
    • 
      
        a
      
      
        (String)
      
      
      
        —
        
      hi
      
      
    
      • 
  

    



    



    
  
    
    
      
    

36
    
        		
    
      
    # File '(stdin)', line 36

def test_overload(*args) end
    
        		
  
    

    

    
    
      
    
  
    
  
    #void_meth  
  

  

  

    
  
    
    
    This method returns an undefined value.
    

  
    

    

    
  


    
  
    
    
      
    

43
    
        		
    
      
    # File '(stdin)', line 43

def void_meth; end
    
        		
  
    

    

    
    
  
    
yard-0.9.37/spec/templates/examples/module001.txt000066400000000000000000000006731466601756300216120ustar00rootroot00000000000000-------------------------------------------------------------- Module: A

    Comments 



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

Defined Under Namespace:
------------------------

    Z (modules)

    Q, X, Y (classes)

Includes:
---------

    D, E, F, A::B::C, B, BaseMod


Class methods:
--------------

    a


Instance methods:
-----------------

    a, test_multi_overload, test_overload, void_meth


yard-0.9.37/spec/templates/examples/module002.html000066400000000000000000000107371466601756300217420ustar00rootroot00000000000000
    Module: A
  
  
  

    

    
  

  
  
  
  
  

  

  
  
    
    
    Defined in:
    
    
    (stdin)
    
  
    
  

    





  
    Foo collapse
    
  
      
    
      
    • 
  
    
      #foo_attr  
    

    
  
  
  
  
    
    
  
  
  
  
  

  
    
      Returns the value of attribute foo_attr.
      
  

      • 

    
  
    




  
    
    
      Foo
      collapse
    
    

    
  
    
    
      Bar
      collapse
    
    

    
  
    
    
      Class Method Summary
      collapse
    
    

    
  


  
    
    
    Instance Attribute Details
    
    
      
      
      
    
  
    
  
    #foo_attr  
  

  

  

    
  
    
    Returns the value of attribute foo_attr.

  
    

    

    
  


    
  
    
    
      
    

3
4
5
    
        		
    
      
    # File '(stdin)', line 3

def foo_attr
  @foo_attr
end
    
        		
  
    

    

    
    
  
    


  
    
    
    Class Method Details
    

    
      
    
  
    
  
    .bar  
  

  

  

    
  
    
    
      
    

5
    
        		
    
      
    # File '(stdin)', line 5

def self.bar; end
    
        		
  
    

    

    
    
      
    
  
    
  
    .baz  
  

  

  

    
  
    
    
      
    

12
    
        		
    
      
    # File '(stdin)', line 12

def self.baz; end
    
        		
  
    

    

    
    
  
    

  
    
    
    Instance Method Details
    

    
      
    
  
    
  
    #baz  
  

  

  

    
  
    
    
      
    

8
    
        		
    
      
    # File '(stdin)', line 8

def baz; end
    
        		
  
    

    

    
    
      
    
  
    
  
    #foo  
  

  

  

    
  
    
    
      
    

4
    
        		
    
      
    # File '(stdin)', line 4

def foo; end
    
        		
  
    

    

    
    
  
    
yard-0.9.37/spec/templates/examples/module003.html000066400000000000000000000051731466601756300217410ustar00rootroot00000000000000
    Module: A
  
  
  

    

    
  

  
  
  
  
  
    
      
    Includes:
    
      
    B
    
  
    
  
  

  

  
  
    
    
    Defined in:
    
    
    (stdin)
    
  
    
  

    


  
    
    Constant Summary

    collapse
  
    
  
    
    
      
        
    FOO =
          
        
    
        
    2
    
      
    
    
  




  
    Instance Attribute Summary collapse
    
  
      
    
      
    • 
  
    
      #bar  
    

    
  
  
  
  
    
      readonly
    
    
  
  
  
  
  

  
    
      Returns the value of attribute bar.
      
  

      • 

    
  
    




  
    
    
      Instance Method Summary
      collapse
    
    

    
  


  
  
  
  
  
  
  
    
    
    Instance Attribute Details
    
    
      
      
      
    
  
    
  
    #bar   (readonly)
  

  

  

    
  
    
    Returns the value of attribute bar.

  
    

    

    
  


    
  
    
    
      
    

11
12
13
    
        		
    
      
    # File '(stdin)', line 11

def bar
  @bar
end
    
        		
  
    

    

    
    
  
    


  
    
    
    Instance Method Details
    

    
      
    
  
    
  
    #foo  
  

  

  

    
  
    
    
      
    

10
    
        		
    
      
    # File '(stdin)', line 10

def foo; end
    
        		
  
    

    

    
    
  
    
yard-0.9.37/spec/templates/examples/module004.html000066400000000000000000000124651466601756300217440ustar00rootroot00000000000000
    Class: A
  
  
  

    

    
  
  
    
    
    Inherits:
    
    
    
      Object
      
        
      
          
    • Object
      • 
          
            
          
        
    
        show all
      
    
    
  
    
  

  
  
  
    
      
    Extended by:
    
      
    Bar
    
  
    
  
  
  
  
    
      
    Includes:
    
      
    BarFooBar, Baz::ABC, Baz::XYZ, Foo
    
  
    
  
  

  

  
  
    
    
    Defined in:
    
    
    (stdin)
    
  
    
  

    





  
    Instance Attribute Summary collapse
    
  




  
    
    
      Booya
      collapse
    
    

    
      
      
        
    • 
  
    
      .baz  
    

    
  
  
    
      extended
      from Bar
    
  
  
  
  
  
  
  

  
    
      Docs for baz in Booya group.
      
  

      • 

      
        
    • 
  
    
      #baz_abc  
    

    
  
  
    
      included
      from Baz::ABC
    
  
  
  
  
  
  
  

  
    
      
  

      • 

      
    
    
  
    
    
      Instance Method Summary
      collapse
    
    

    
      
      
        
    • 
  
    
      #foo  
    

    
  
  
  
  
  
  
  
  

  
    
      This method is in A.
      
  

      • 

      
        
    • 
  
    
      #xyz  
    

    
  
  
    
      included
      from Foo
    
  
  
  
  
  
  
  

  
    
      Docs for xyz.
      
  

      • 

      
    
    
  


  
  
  
  
  
  
  
  
  
  
  
  
  
    Methods included from Baz::XYZ
    
  
    #baz_xyz
    

  
  
  
  
  
  
  
  
  
    Methods included from BarFooBar
    
  
    #bar_foo_bar
    

  
  
  
    
    
    Instance Attribute Details
    
    
      
      
      
    
  
    
  
    #bar_attr  
  

  

  
    
      Originally defined in module
        Foo
    
  

    
  
    
    Docs for bar_attr

  
    

    

    
  


    

    
    
  
    


  
    
    
    Class Method Details
    

    
      
    
  
    
  
    .baz  
  

  

  
    
      Originally defined in module
        Bar
    
  

    
  
    
    Docs for baz in Booya group

  
    

    

    
  


    

    
    
  
    

  
    
    
    Instance Method Details
    

    
      
    
  
    
  
    #baz_abc  
  

  

  
    
      Originally defined in module
        Baz::ABC
    
  

    

    
    
      
    
  
    
  
    #foo  
  

  

  

    
  
    
    This method is in A

  
    

    

    
  


    
  
    
    
      
    

3
    
        		
    
      
    # File '(stdin)', line 3

def foo; end
    
        		
  
    

    

    
    
      
    
  
    
  
    #xyz  
  

  

  
    
      Originally defined in module
        Foo
    
  

    
  
    
    Docs for xyz

  
    

    

    
  


    

    
    
  
    

yard-0.9.37/spec/templates/examples/module005.html000066400000000000000000000022771466601756300217450ustar00rootroot00000000000000
    Module: A




    

    











  
    
    
    Defined in:
    
    
    (stdin)
    
  
    


    



    
    
      Foo
      collapse
    
    

    
    

        
    FOO =

        
    
        
    1
    

        
    BAR =
          
    
  
    
    
    Deprecated. 
    


  
    

    

    



    
        
    
        
    2
    

    
    

    
    
      Bar
      collapse
    
    

    
    

        
    BAZ =

        
    
        
    3
    

    
    

    
    
      Constant Summary
      collapse
    
    

    
    

        
    WORLD =

        
    
        
    4
    

    
    yard-0.9.37/spec/templates/examples/tag001.txt000066400000000000000000000020351466601756300210720ustar00rootroot00000000000000------------------------------------------------------------- Method: #m
                                                   (Defined in: (stdin))

    root.m(opts = {}) {|a| ... } -> String 
------------------------------------------------------------------------

    Deprecated. for great justice

    Abstract. override me

    Comments 

Examples:
---------

    # Wash your car
    car.wash

    # To kill a mockingbird
    a = String.new
    flip(a.reverse)

Parameters:
-----------

    (Hash) opts - the options

Options Hash (opts):
--------------------

    (Object) :key - default: '' - hello

    (Object) :key2 - default: X - hello

Yields:
-------

    - a block

Yield Parameters:
-----------------

    (String) a - a value

Yield Returns:
--------------

    (Hash) - a hash

Returns:
--------

    (String) - the result

Raises:
-------

    (Exception) - Exception class

See Also:
---------

    - A
    - http://url.com
    - http://url.com - Example

Author:
-------

    Name

Since:
------

    1.0

Version:
--------

    1.0


yard-0.9.37/spec/templates/helpers/000077500000000000000000000000001466601756300171615ustar00rootroot00000000000000yard-0.9.37/spec/templates/helpers/base_helper_spec.rb000066400000000000000000000134221466601756300227730ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Templates::Helpers::BaseHelper do
  include YARD::Templates::Helpers::BaseHelper

  describe "#run_verifier" do
    it "runs verifier proc against list if provided" do
      mock = Verifier.new
      expect(mock).to receive(:call).with(1)
      expect(mock).to receive(:call).with(2)
      expect(mock).to receive(:call).with(3)
      expect(self).to receive(:options).at_least(1).times.and_return(Options.new.update(:verifier => mock))
      run_verifier [1, 2, 3]
    end

    it "prunes list if lambda returns false and only false" do
      mock = Verifier.new
      expect(self).to receive(:options).at_least(1).times.and_return(Options.new.update(:verifier => mock))
      expect(mock).to receive(:call).with(1).and_return(false)
      expect(mock).to receive(:call).with(2).and_return(true)
      expect(mock).to receive(:call).with(3).and_return(nil)
      expect(mock).to receive(:call).with(4).and_return("value")
      expect(run_verifier([1, 2, 3, 4])).to eq [2, 3, 4]
    end

    it "returns list if no verifier exists" do
      expect(self).to receive(:options).at_least(1).times.and_return(Options.new)
      expect(run_verifier([1, 2, 3])).to eq [1, 2, 3]
    end
  end

  describe "#h" do
    it "returns just the text" do
      expect(h("hello world")).to eq "hello world"
      expect(h(nil)).to eq nil
    end
  end

  describe "#link_object" do
    it "returns the title if provided" do
      expect(link_object(1, "title")).to eq "title"
      expect(link_object(Registry.root, "title")).to eq "title"
    end

    it "returns a path if argument is a Proxy or object" do
      expect(link_object(Registry.root)).to eq "Top Level Namespace"
      expect(link_object(P("Array"))).to eq "Array"
    end

    it "returns path of Proxified object if argument is a String or Symbol" do
      expect(link_object("Array")).to eq "Array"
      expect(link_object(:"A::B")).to eq "A::B"
    end

    it "returns the argument if not an object, proxy, String or Symbol" do
      expect(link_object(1)).to eq 1
    end
  end

  describe "#link_url" do
    it "returns the URL" do
      expect(link_url("http://url")).to eq "http://url"
    end
  end

  describe "#linkify" do
    let(:object) { Registry.root }
    # before do
    #   stub!(:object).and_return(Registry.root)
    # end

    it "calls #link_url for mailto: links" do
      expect(self).to receive(:link_url)
      linkify("mailto:steve@example.com")
    end

    it "calls #link_url for URL schemes (http://)" do
      expect(self).to receive(:link_url)
      linkify("http://example.com")
    end

    it "calls #link_file for file: links" do
      expect(self).to receive(:link_file).with('Filename', nil, 'anchor')
      linkify("file:Filename#anchor")
    end

    it "passes off to #link_object if argument is an object" do
      obj = CodeObjects::NamespaceObject.new(nil, :YARD)
      expect(self).to receive(:link_object).with(obj)
      linkify obj
    end

    it "returns empty string and warn if object does not exist" do
      expect(log).to receive(:warn).with(/Cannot find object .* for inclusion/)
      expect(linkify('include:NotExist')).to eq ''
    end

    it "passes off to #link_url if argument is recognized as a URL" do
      url = "http://yardoc.org/"
      expect(self).to receive(:link_url).with(url, nil, {:target => '_parent'})
      linkify url
    end

    it "calls #link_include_object for include:ObjectName" do
      obj = CodeObjects::NamespaceObject.new(:root, :Foo)
      expect(self).to receive(:link_include_object).with(obj)
      linkify 'include:Foo'
    end

    it "calls #link_include_file for include:file:path/to/file" do
      expect(File).to receive(:file?).with('path/to/file').and_return(true)
      expect(File).to receive(:read).with('path/to/file').and_return('FOO')
      expect(linkify('include:file:path/to/file')).to eq 'FOO'
    end

    it "does not allow include:file for path above pwd" do
      expect(log).to receive(:warn).with("Cannot include file from path `a/b/../../../../file'")
      expect(linkify('include:file:a/b/../../../../file')).to eq ''
    end

    it "warns if include:file:path does not exist" do
      expect(log).to receive(:warn).with(/Cannot find file .+ for inclusion/)
      expect(linkify('include:file:notexist')).to eq ''
    end
  end

  describe "#format_types" do
    it "returns the list of types separated by commas surrounded by brackets" do
      expect(format_types(['a', 'b', 'c'])).to eq '(a, b, c)'
    end

    it "returns the list of types without brackets if brackets=false" do
      expect(format_types(['a', 'b', 'c'], false)).to eq 'a, b, c'
    end

    it "returns an empty string if list is empty or nil" do
      expect(format_types(nil)).to eq ""
      expect(format_types([])).to eq ""
    end
  end

  describe "#format_object_type" do
    it "returns Exception if type is Exception" do
      obj = double(:object, :is_exception? => true)
      allow(obj).to receive(:is_a?) {|arg| arg == YARD::CodeObjects::ClassObject }
      expect(format_object_type(obj)).to eq "Exception"
    end

    it "returns Class if type is Class" do
      obj = double(:object, :is_exception? => false)
      allow(obj).to receive(:is_a?) {|arg| arg == YARD::CodeObjects::ClassObject }
      expect(format_object_type(obj)).to eq "Class"
    end

    it "returns object type in other cases" do
      obj = double(:object, :type => "value")
      expect(format_object_type(obj)).to eq "Value"
    end
  end

  describe "#format_object_title" do
    it "returns Top Level Namespace for root object" do
      expect(format_object_title(Registry.root)).to eq "Top Level Namespace"
    end

    it "returns 'type: title' in other cases" do
      obj = double(:object, :type => :class, :title => "A::B::C")
      expect(format_object_title(obj)).to eq "Class: A::B::C"
    end
  end
end
yard-0.9.37/spec/templates/helpers/html_helper_spec.rb000066400000000000000000000633731466601756300230370ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/shared_signature_examples"

RSpec.describe YARD::Templates::Helpers::HtmlHelper do
  include YARD::Templates::Helpers::BaseHelper
  include YARD::Templates::Helpers::HtmlHelper
  include YARD::Templates::Helpers::MethodHelper

  def options
    Templates::TemplateOptions.new.tap do |o|
      o.reset_defaults
      o.default_return = nil
    end
  end

  describe "#h" do
    it "uses #h to escape HTML" do
      expect(h('Usage: foo "bar" ')).to eq "Usage: foo "bar" <baz>"
    end
  end

  describe "#charset" do
    after { Encoding.default_external = 'utf-8' if defined?(Encoding) }

    it "returns foo if LANG=foo" do
      expect(ENV).to receive(:[]).with('LANG').and_return('shift_jis') if YARD.ruby18?
      Encoding.default_external = 'shift_jis' if defined?(Encoding)
      expect(charset).to eq 'shift_jis'
    end

    ['US-ASCII', 'binary', 'ASCII-8BIT'].each do |type|
      it "converts #{type} to iso-8859-1" do
        expect(ENV).to receive(:[]).with('LANG').and_return(type) if YARD.ruby18?
        Encoding.default_external = type if defined?(Encoding)
        expect(charset).to eq 'iso-8859-1'
      end
    end

    it "takes file encoding if there is a file" do
      @file = OpenStruct.new(:contents => String.new('foo').force_encoding('sjis'))
      # not the correct charset name, but good enough
      expect(['Shift_JIS', 'Windows-31J']).to include(charset)
    end if YARD.ruby19?

    it "takes file encoding if there is a file" do
      allow(ENV).to receive(:[]).with('LANG').and_return('utf-8') if YARD.ruby18?
      @file = OpenStruct.new(:contents => 'foo')
      expect(charset).to eq 'utf-8'
    end if YARD.ruby18?

    if YARD.ruby18?
      it "returns utf-8 if no LANG env is set" do
        expect(ENV).to receive(:[]).with('LANG').and_return(nil)
        expect(charset).to eq 'utf-8'
      end

      it "only returns charset part of lang" do
        expect(ENV).to receive(:[]).with('LANG').and_return('en_US.UTF-8')
        expect(charset).to eq 'utf-8'
      end
    end
  end

  describe "#format_types" do
    it "includes brackets by default" do
      text = ["String"]
      expect(self).to receive(:linkify).at_least(1).times.with("String", "String").and_return("String")
      expect(format_types(text)).to eq format_types(text, true)
      expect(format_types(text)).to eq "(String)"
    end

    it "avoids brackets if brackets=false" do
      expect(self).to receive(:linkify).with("String", "String").and_return("String")
      expect(self).to receive(:linkify).with("Symbol", "Symbol").and_return("Symbol")
      expect(format_types(["String", "Symbol"], false)).to eq "String, Symbol"
    end

    {"String" => [["String"],
        "String"],
      "A::B::C" => [["A::B::C"],
        "A::B::C"],
      "Array" => [["Array", "String"],
        "Array<String>"],
      "Array" => [["Array", "String", "Symbol"],
        "Array<String, Symbol>"],
      "Array<{String => Array}>" => [["Array", "String", "Array", "Symbol"],
        "Array<{String => " \
          "Array<Symbol>}>"]}.each do |text, values|
      it "links all classes in #{text}" do
        if text.count('<') > 0
          expect(self).to receive(:h).with('<').at_least(text.count('<')).times.and_return("<")
        end
        if text.count('>') > 0
          expect(self).to receive(:h).with('>').at_least(text.count('>')).times.and_return(">")
        end
        values[0].each {|v| expect(self).to receive(:linkify).with(v, v).and_return("#{v}") }
        expect(format_types([text], false)).to eq values[1]
      end
    end
  end

  describe "#htmlify" do
    it "handles various encodings" do
      allow(self).to receive(:object).and_return(Registry.root)
      text = String.new("\xB0\xB1")
      if defined?(Encoding)
        utf8 = Encoding.find('utf-8')

        Encoding.default_internal = utf8 unless Encoding.default_internal == utf8
        text = text.force_encoding('binary')
      end
      htmlify(text, :text)
      # TODO: add more encoding tests
    end

    it "returns pre-formatted text with :pre markup" do
      expect(htmlify("fo\no\n\nbar<>", :pre)).to eq "
    fo\no\n\nbar<>
    "
    end

    it "returns regular text with :text markup" do
      expect(htmlify("fo\no\n\nbar<>", :text)).to eq "fo
    o

    bar<>"
    end

    it "returns unmodified text with :none markup" do
      expect(htmlify("fo\no\n\nbar<>", :none)).to eq "fo\no\n\nbar<>"
    end

    it "highlights ruby if markup is :ruby" do
      expect(htmlify("class Foo; end", :ruby)).to match(/\A
    HI
    "
    end

    it "allows inline includes for {include:} in the middle of a line" do
      load_markup_provider(:rdoc)
      expect(File).to receive(:file?).with('foo.rdoc').and_return(true)
      expect(File).to receive(:read).with('foo.rdoc').and_return('HI')
      expect(htmlify("test {include:file:foo.rdoc}", :rdoc).gsub(/[\r?\n]+/, '')).to eq '
    test HI
    '
    end

    it "does not autolink URLs inside of {} (markdown specific)" do
      log.enter_level(Logger::FATAL) do
        pending 'This test depends on markdown' unless markup_class(:markdown)
      end
      expect(htmlify('{http://example.com Title}', :markdown).chomp).to match(
        %r{
    Title
    }
      )
      expect(htmlify('{http://example.com}', :markdown).chomp).to match(
        %r{
    http://example.com
    }
      )
    end

    it "creates tables (markdown specific)" do
      log.enter_level(Logger::FATAL) do
        supports_table = %w(RedcarpetCompat Kramdown::Document CommonMarker)
        unless supports_table.include?(markup_class(:markdown).to_s)
          pending "This test depends on a markdown engine that supports tables"
        end
      end

      markdown = <<-EOF.strip
        City    | State | Country
        --------|-------|--------
        Raleigh | NC    | US
        Seattle | WA    | US
      EOF

      html = htmlify(markdown, :markdown)
      expect(html).to match(//)
      expect(html).to match %r{}
      expect(html).to match %r{}
    end

    it "handles fenced code blocks (Redcarpet specific)" do
      log.enter_level(Logger::FATAL) do
        unless markup_class(:markdown).to_s == 'RedcarpetCompat'
          pending 'This test is Redcarpet specific'
        end
      end

      markdown = "Introduction:\n```ruby\nputs\n\nputs\n```"
      html = htmlify(markdown, :markdown)
      expect(html).to match %r{^
    Introduction:
    .*}m
    end

    it "sets env and env-yard attributes (AsciiDoc specific)" do
      adoc = <<-EOF.strip.gsub(/^ +/, "") # strip and unindent
        ifdef::env[]
        Attribute "env" is set, and its value is "{env}".
        endif::[]

        ifdef::env-yard[]
        Attribute "env-yard" is set, and its value is "{env-yard}".
        endif::[]
      EOF
      html = htmlify(adoc, :asciidoc)
      expect(html).to match(/"env" is set, and its value is "yard"./)
      expect(html).to match(/"env-yard" is set, and its value is ""./)
    end

    it "should not include the document title from the AsciiDoc header" do
      adoc = <<-EOF.strip.gsub(/^ +/, "") # strip and unindent
        = Project Name

        Introduction.

        == Installation

        Installation instructions.

        == Usage

        Usage instructions.
      EOF
      html = htmlify(adoc, :asciidoc)
      expect(html).to_not match(/Project Name/)
      expect(html).to include(%(
    Installation
    ))
    end
  end

  describe "#link_object" do
    let(:object) { CodeObjects::NamespaceObject.new(nil, :YARD) }

    it "returns the object path if there's no serializer and no title" do
      allow(self).to receive(:serializer).and_return(nil)
      expect(link_object(CodeObjects::NamespaceObject.new(nil, :YARD))).to eq "YARD"
    end

    it "returns the title if there's a title but no serializer" do
      allow(self).to receive(:serializer).and_return(nil)
      expect(link_object(CodeObjects::NamespaceObject.new(nil, :YARD), 'title')).to eq "title"
    end

    it "links objects from overload tag" do
      YARD.parse_string <<-'eof'
        module Foo
          class Bar; def a; end end
          class Baz
            # @overload a
            def a; end
          end
        end
      eof
      obj = Registry.at('Foo::Baz#a').tag(:overload)
      allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
      allow(self).to receive(:object).and_return(obj)
      expect(link_object("Bar#a")).to match(/href="Bar.html#a-instance_method"/)
    end

    it "uses relative path in title" do
      CodeObjects::ModuleObject.new(:root, :YARD)
      CodeObjects::ClassObject.new(P('YARD'), :Bar)
      allow(self).to receive(:object).and_return(CodeObjects::ModuleObject.new(P('YARD'), :Foo))
      allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
      expect(link_object("Bar")).to match %r{>Bar}
    end

    it "uses #title if overridden" do
      CodeObjects::ModuleObject.new(:root, :YARD)
      CodeObjects::ClassObject.new(P('YARD'), :Bar)
      allow(Registry.at('YARD::Bar')).to receive(:title).and_return('TITLE!')
      allow(self).to receive(:object).and_return(Registry.at('YARD::Bar'))
      allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
      expect(link_object("Bar")).to match %r{>TITLE!}
    end

    it "uses relative path to parent class in title" do
      root = CodeObjects::ModuleObject.new(:root, :YARD)
      obj = CodeObjects::ModuleObject.new(root, :SubModule)
      allow(self).to receive(:object).and_return(obj)
      allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
      expect(link_object("YARD")).to match %r{>YARD}
    end

    it "uses Klass.foo when linking to class method in current namespace" do
      root = CodeObjects::ModuleObject.new(:root, :Klass)
      CodeObjects::MethodObject.new(root, :foo, :class)
      allow(self).to receive(:object).and_return(root)
      allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
      expect(link_object("foo")).to match %r{>Klass.foo}
    end

    it "escapes method name in title" do
      YARD.parse_string <<-'eof'
        class Array
          def &(other)
          end
        end
      eof
      obj = Registry.at('Array#&')
      allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
      allow(self).to receive(:object).and_return(obj)
      expect(link_object("Array#&")).to match(/title="Array#& \(method\)"/)
    end
  end

  describe "#url_for" do
    before { Registry.clear }

    it "returns nil if serializer is nil" do
      allow(self).to receive(:serializer).and_return nil
      allow(self).to receive(:object).and_return Registry.root
      expect(url_for(P("Mod::Class#meth"))).to be nil
    end

    it "returns nil if object is hidden" do
      yard = CodeObjects::ModuleObject.new(:root, :YARD)

      allow(self).to receive(:serializer).and_return(Serializers::FileSystemSerializer.new)
      allow(self).to receive(:object).and_return Registry.root
      allow(self).to receive(:options).and_return OpenStruct.new(:verifier => Verifier.new('false'))

      expect(url_for(yard)).to be nil
    end

    it "returns nil if serializer does not implement #serialized_path" do
      allow(self).to receive(:serializer).and_return Serializers::Base.new
      allow(self).to receive(:object).and_return Registry.root
      expect(url_for(P("Mod::Class#meth"))).to be nil
    end

    it "links to a path/file for a namespace object" do
      allow(self).to receive(:serializer).and_return Serializers::FileSystemSerializer.new
      allow(self).to receive(:object).and_return Registry.root

      yard = CodeObjects::ModuleObject.new(:root, :YARD)
      expect(url_for(yard)).to eq 'YARD.html'
    end

    it "links to the object's namespace path/file and use the object as the anchor" do
      allow(self).to receive(:serializer).and_return Serializers::FileSystemSerializer.new
      allow(self).to receive(:object).and_return Registry.root

      yard = CodeObjects::ModuleObject.new(:root, :YARD)
      meth = CodeObjects::MethodObject.new(yard, :meth)
      expect(url_for(meth)).to eq 'YARD.html#meth-instance_method'
    end

    it "properly urlencodes methods with punctuation in links" do
      obj = CodeObjects::MethodObject.new(nil, :/)
      serializer = double(:serializer, :serialized_path => "file.html")
      allow(self).to receive(:serializer).and_return serializer
      allow(self).to receive(:object).and_return obj
      expect(url_for(obj)).to eq "#%2F-instance_method"
    end
  end

  describe "#anchor_for" do
    it "does not urlencode data when called directly" do
      obj = CodeObjects::MethodObject.new(nil, :/)
      expect(anchor_for(obj)).to eq "/-instance_method"
    end
  end

  describe "#resolve_links" do
    def parse_link(link)
      results = {}
      link =~ %r{(.+?)}m
      params = $1
      results[:inner_text] = $2
      params.scan(/\s*(\S+?)=['"](.+?)['"]\s*/).each do |key, value|
        results[key.to_sym] = value.gsub(/^["'](.+)["']$/, '\1')
      end
      results
    end

    it "escapes {} syntax with backslash (\\{foo bar})" do
      input  = '\{foo bar} \{XYZ} \{file:FOO} $\{N-M}'
      output = '{foo bar} {XYZ} {file:FOO} ${N-M}'
      expect(resolve_links(input)).to eq output
    end

    it "escapes {} syntax with ! (!{foo bar})" do
      input  = '!{foo bar} !{XYZ} !{file:FOO} $!{N-M}'
      output = '{foo bar} {XYZ} {file:FOO} ${N-M}'
      expect(resolve_links(input)).to eq output
    end

    it "links static files with file: prefix" do
      allow(self).to receive(:serializer).and_return Serializers::FileSystemSerializer.new
      allow(self).to receive(:object).and_return Registry.root

      expect(parse_link(resolve_links("{file:TEST.txt#abc}"))).to eq(
        :inner_text => "TEST",
        :title => "TEST",
        :href => "file.TEST.html#abc"
      )
      expect(parse_link(resolve_links("{file:TEST.txt title}"))).to eq(
        :inner_text => "title",
        :title => "title",
        :href => "file.TEST.html"
      )
    end

    it "creates regular links with http:// or https:// prefixes" do
      expect(parse_link(resolve_links("{http://example.com}"))).to eq(
        :inner_text => "http://example.com",
        :target => "_parent",
        :href => "http://example.com",
        :title => "http://example.com"
      )
      expect(parse_link(resolve_links("{http://example.com title}"))).to eq(
        :inner_text => "title",
        :target => "_parent",
        :href => "http://example.com",
        :title => "title"
      )
    end

    it "creates mailto links with mailto: prefixes" do
      expect(parse_link(resolve_links('{mailto:joanna@example.com}'))).to eq(
        :inner_text => 'mailto:joanna@example.com',
        :target => '_parent',
        :href => 'mailto:joanna@example.com',
        :title => 'mailto:joanna@example.com'
      )
      expect(parse_link(resolve_links('{mailto:steve@example.com Steve}'))).to eq(
        :inner_text => 'Steve',
        :target => '_parent',
        :href => 'mailto:steve@example.com',
        :title => 'Steve'
      )
    end

    it "ignores {links} that begin with |...|" do
      expect(resolve_links("{|x|x == 1}")).to eq "{|x|x == 1}"
    end

    it "gracefully ignores {} in links" do
      allow(self).to receive(:linkify).with('Foo', 'Foo').and_return('FOO')
      expect(resolve_links("{} {} {Foo Foo}")).to eq '{} {} FOO'
    end

    %w(tt code pre).each do |tag|
      it "ignores links in <#{tag}>" do
        text = "<#{tag}>{Foo}"
        expect(resolve_links(text)).to eq text
      end
    end

    it "resolves {Name}" do
      expect(self).to receive(:link_file).with('TEST', nil, nil).and_return('')
      resolve_links("{file:TEST}")
    end

    it "resolves ({Name})" do
      expect(self).to receive(:link_file).with('TEST', nil, nil).and_return('')
      resolve_links("({file:TEST})")
    end

    it "resolves link with newline in title-part" do
      expect(parse_link(resolve_links("{http://example.com foo\nbar}"))).to eq(
        :inner_text => "foo bar",
        :target => "_parent",
        :href => "http://example.com",
        :title => "foo bar"
      )
    end

    it "resolves links to methods whose names have been escaped" do
      expect(self).to receive(:linkify).with('Object#<<', nil).and_return('')
      resolve_links("{Object#<<}")
    end

    it "warns about missing reference at right file location for object" do
      YARD.parse_string <<-eof
        # Comments here
        # And a reference to {InvalidObject}
        class MyObject; end
      eof
      logger = double(:log)
      expect(logger).to receive(:warn).ordered.with(
        "In file `(stdin)':2: Cannot resolve link to InvalidObject from text:\n\t...{InvalidObject}"
      )
      allow(self).to receive(:log).and_return(logger)
      allow(self).to receive(:object).and_return(Registry.at('MyObject'))
      resolve_links(object.docstring)
    end

    it "shows ellipsis on either side if there is more on the line in a reference warning" do
      YARD.parse_string <<-eof
        # {InvalidObject1} beginning of line
        # end of line {InvalidObject2}
        # Middle of {InvalidObject3} line
        # {InvalidObject4}
        class MyObject; end
      eof
      logger = double(:log)
      expect(logger).to receive(:warn).ordered.with("In file `(stdin)':1: Cannot resolve link to InvalidObject1 from text:\n\t{InvalidObject1}...")
      expect(logger).to receive(:warn).ordered.with("In file `(stdin)':2: Cannot resolve link to InvalidObject2 from text:\n\t...{InvalidObject2}")
      expect(logger).to receive(:warn).ordered.with("In file `(stdin)':3: Cannot resolve link to InvalidObject3 from text:\n\t...{InvalidObject3}...")
      expect(logger).to receive(:warn).ordered.with("In file `(stdin)':4: Cannot resolve link to InvalidObject4 from text:\n\t{InvalidObject4}")
      allow(self).to receive(:log).and_return(logger)
      allow(self).to receive(:object).and_return(Registry.at('MyObject'))
      resolve_links(object.docstring)
    end

    it "warns about missing reference for file template (no object)" do
      @file = CodeObjects::ExtraFileObject.new('myfile.txt', '')
      logger = double(:log)
      expect(logger).to receive(:warn).ordered.with("In file `myfile.txt':3: Cannot resolve link to InvalidObject from text:\n\t...{InvalidObject Some Title}")
      allow(self).to receive(:log).and_return(logger)
      allow(self).to receive(:object).and_return(Registry.root)
      resolve_links(<<-eof)
        Hello world
        This is a line
        And {InvalidObject Some Title}
        And more.
      eof
    end

    it "warns if you link a constant namespace as if it were a class/module" do
      @file = CodeObjects::ExtraFileObject.new('myfile.txt', '')
      YARD.parse_string('CONST = 1')

      logger = double(:log)
      allow(self).to receive(:log).and_return(logger)
      expect(logger).to receive(:warn).ordered.with("The namespace of link \"::CONST#meth\" is a constant or invalid.")
      expect(logger).to receive(:warn).ordered.with("In file `myfile.txt':1: Cannot resolve link to ::CONST#meth from text:\n\t{::CONST#meth}")
      expect(resolve_links("{::CONST#meth}")).to eq('::CONST#meth')
    end
  end

  describe "#signature" do
    before do
      arrow = "⇒"
      @results = {
        :regular => "#foo #{arrow} Object",
        :default_return => "#foo #{arrow} Hello",
        :no_default_return => "#foo",
        :private_class => ".foo #{arrow} Object (private)",
        :single => "#foo #{arrow} String",
        :two_types => "#foo #{arrow} String, Symbol",
        :two_types_multitag => "#foo #{arrow} String, Symbol",
        :type_nil => "#foo #{arrow} Type?",
        :type_array => "#foo #{arrow} Type+",
        :multitype => "#foo #{arrow} Type, ...",
        :void => "#foo #{arrow} void",
        :hide_void => "#foo",
        :block => "#foo {|a, b, c| ... } #{arrow} Object",
        :empty_overload => "#foobar #{arrow} String"
      }
    end

    def format_types(types, _brackets = false) types.join(", ") end
    def signature(obj, link = false) super(obj, link).strip end

    it_should_behave_like "signature"

    it "links to regular method if overload name does not have the same method name" do
      YARD.parse_string <<-eof
        class Foo
          # @overload bar(a, b, c)
          def foo; end
        end
      eof
      serializer = double(:serializer)
      allow(serializer).to receive(:serialized_path).with(Registry.at('Foo')).and_return('')
      allow(self).to receive(:serializer).and_return(serializer)
      allow(self).to receive(:object).and_return(Registry.at('Foo'))
      expect(signature(Registry.at('Foo#foo').tag(:overload), true)).to eq(
        "#bar(a, b, c)  "
      )
    end
  end

  describe "#html_syntax_highlight" do
    subject do
      obj = OpenStruct.new
      obj.options = options
      obj.object = Registry.root
      obj.extend(Templates::Helpers::HtmlHelper)
      obj
    end

    it "returns empty string on nil input" do
      expect(subject.html_syntax_highlight(nil)).to eq ''
    end

    it "calls #html_syntax_highlight_ruby by default" do
      Registry.root.source_type = nil
      expect(subject).to receive(:html_syntax_highlight_ruby).with('def x; end')
      subject.html_syntax_highlight('def x; end')
    end

    it "calls #html_syntax_highlight_NAME if there's an object with a #source_type" do
      subject.object = OpenStruct.new(:source_type => :NAME)
      expect(subject).to receive(:html_markup_html) {|text| text }
      expect(subject).to receive(:html_syntax_highlight_NAME).and_return("foobar")
      expect(subject.htmlify('
    def x; end
    ', :html)).to eq(
        '
    foobar
    '
      )
    end

    it "adds !!!LANG to className in outputted pre tag" do
      subject.object = OpenStruct.new(:source_type => :LANG)
      expect(subject).to receive(:html_markup_html) {|text| text }
      expect(subject).to receive(:html_syntax_highlight_LANG).and_return("foobar")
      expect(subject.htmlify("
    !!!LANG\ndef x; end
    ", :html)).to eq(
        '
    foobar
    '
      )
    end

    it "calls html_syntax_highlight_NAME if source starts with !!!NAME" do
      expect(subject).to receive(:html_syntax_highlight_NAME).and_return("foobar")
      expect(subject.html_syntax_highlight(<<-eof
        !!!NAME
        def x; end
      eof
                                          )).to eq "foobar"
    end

    it "does not highlight if highlight option is false" do
      subject.options.highlight = false
      expect(subject).not_to receive(:html_syntax_highlight_ruby)
      expect(subject.html_syntax_highlight('def x; end')).to eq 'def x; end'
    end

    it "does not highlight if there is no highlight method specified by !!!NAME" do
      def subject.respond_to?(method, include_all = false)
        return false if method == 'html_syntax_highlight_NAME'
        super
      end
      expect(subject).not_to receive(:html_syntax_highlight_NAME)
      expect(subject.html_syntax_highlight("!!!NAME\ndef x; end")).to eq "def x; end"
    end

    it "highlights as ruby if htmlify(text, :ruby) is called" do
      expect(subject).to receive(:html_syntax_highlight_ruby).with('def x; end').and_return('x')
      expect(subject.htmlify('def x; end', :ruby)).to eq '
    x
    '
    end

    it "does not prioritize object source type when called directly" do
      expect(subject).to receive(:html_syntax_highlight_ruby).with('def x; end').and_return('x')
      subject.object = OpenStruct.new(:source_type => :c)
      expect(subject.html_syntax_highlight("def x; end")).to eq "x"
    end

    it "doesn't escape code snippets twice" do
      expect(subject.htmlify('
    {"foo" => 1}
    ', :html)).to eq(
        '
    {"foo" => 1}
    '
      )
    end

    it "highlights source when matching a pre lang= tag" do
      expect(subject.htmlify('
    x = 1
    ', :html)).to eq(
        '
    x = 1
    '
      )
    end

    it "highlights source when matching a code class= tag" do
      expect(subject.htmlify('
    x = 1
    ', :html)).to eq(
        '
    x = 1
    '
      )
    end
  end

  describe "#link_url" do
    it "adds target if scheme is provided" do
      expect(link_url("http://url.com")).to include(" target=\"_parent\"")
      expect(link_url("https://url.com")).to include(" target=\"_parent\"")
      expect(link_url("irc://url.com")).to include(" target=\"_parent\"")
      expect(link_url("../not/scheme")).not_to include("target")
    end
  end
end
yard-0.9.37/spec/templates/helpers/html_syntax_highlight_helper_spec.rb000066400000000000000000000063111466601756300264610ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Templates::Helpers::HtmlSyntaxHighlightHelper do
  include YARD::Templates::Helpers::HtmlHelper
  include YARD::Templates::Helpers::HtmlSyntaxHighlightHelper

  describe "#html_syntax_highlight" do
    let(:object) { CodeObjects::NamespaceObject.new(:root, :YARD) }

    before do
      Registry.root.source_type = :ruby
    end

    it "does not highlight source if options.highlight is false" do
      expect(self).to receive(:options).and_return(Options.new.update(:highlight => false))
      expect(html_syntax_highlight("def x\nend")).to eq "def x\nend"
    end

    it "highlights source (legacy)" do
      type = Parser::SourceParser.parser_type
      Parser::SourceParser.parser_type = :ruby18
      expect(self).to receive(:options).and_return(Options.new.update(:highlight => true))
      expect = "defx
        'x'+
        /x/iend"
      result = html_syntax_highlight("def x\n  'x' + /x/i\nend")
      html_equals_string(result, expect)
      Parser::SourceParser.parser_type = type
    end

    it "highlights source (ripper)" do
      expect(self).to receive(:options).and_return(Options.new.update(:highlight => true))
      Parser::SourceParser.parser_type = :ruby
      expect = "def x
        '
        x'
         + 
        /x
        /i\nend"
      result = html_syntax_highlight("def x\n  'x' + /x/i\nend")
      html_equals_string(result, expect)
    end if HAVE_RIPPER

    it "returns escaped unhighlighted source if a syntax error is found (ripper)" do
      allow(self).to receive(:options).and_return(Options.new.update(:highlight => true))
      expect(html_syntax_highlight("def &x; ... end")).to eq "def &x; ... end"
    end if HAVE_RIPPER

    it "returns escaped unhighlighted source if a syntax error is found (ripper)" do
      allow(self).to receive(:options).and_return(Options.new.update(:highlight => true))
      expect(html_syntax_highlight("$ git clone http://url")).to eq "$ git clone http://url"
    end if HAVE_RIPPER

    it "links constants/methods" do
      other = CodeObjects::NamespaceObject.new(:root, :Other)
      allow(self).to receive(:options).and_return(Options.new.update(:highlight => true))
      allow(self).to receive(:run_verifier).with([other]).and_return([other])
      allow(self).to receive(:link_object).with(other, "Other").and_return("LINK!")
      result = html_syntax_highlight("def x; Other end")
      html_equals_string(result, "def
        x;
        LINK! end")
    end if HAVE_RIPPER
  end
end
yard-0.9.37/spec/templates/helpers/markup/000077500000000000000000000000001466601756300204605ustar00rootroot00000000000000yard-0.9.37/spec/templates/helpers/markup/rdoc_markup_spec.rb000066400000000000000000000056011466601756300243270ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Templates::Helpers::Markup::RDocMarkup do
  describe "loading mechanism" do
    before { @good_libs = [] }

    def require(lib)
      return true if @good_libs.include?(lib)
      raise LoadError
    end

    def load_markup
      require 'rdoc/markup'
      require 'rdoc/markup/to_html'
      return :RDoc2
    rescue LoadError
      begin
        require 'rdoc/markup/simple_markup'
        require 'rdoc/markup/simple_markup/to_html'
        return :RDoc1
      rescue LoadError
        raise NameError, "could not load RDocMarkup (rdoc is not installed)"
      end
    end

    it "loads RDoc2.x if rdoc/markup is present" do
      @good_libs += ['rdoc/markup', 'rdoc/markup/to_html']
      expect(load_markup).to eq :RDoc2
    end

    it "fails on RDoc2.x if rdoc/markup/to_html is not present" do
      @good_libs += ['rdoc/markup']
      expect { load_markup }.to raise_error(NameError)
    end

    it "loads RDoc1.x if RDoc2 fails and rdoc/markup/simple_markup is present" do
      @good_libs += ['rdoc/markup/simple_markup', 'rdoc/markup/simple_markup/to_html']
      expect(load_markup).to eq :RDoc1
    end

    it "raises an error on loading if neither lib is present" do
      expect { load_markup }.to raise_error(NameError)
    end
  end

  describe "#to_html" do
    def to_html(text)
      html = YARD::Templates::Helpers::Markup::RDocMarkup.new(text).to_html
      html.strip.gsub(/\r?\n/, '')
    end

    it "handles typewriter text" do
      expect(to_html('Hello ++')).to eq '
    Hello <code>
    '
    end
  end

  describe "#fix_typewriter" do
    def fix_typewriter(text)
      YARD::Templates::Helpers::Markup::RDocMarkup.new('').send(:fix_typewriter, text)
    end

    it "converts +text+ to text" do
      expect(fix_typewriter("Some +typewriter text <+.")).to eq "Some typewriter text <."
      expect(fix_typewriter("Not +typewriter text.")).to eq "Not +typewriter text."
      expect(fix_typewriter("Alternating +type writer+ text +here+.")).to eq "Alternating type writer text here."
      expect(fix_typewriter("No ++problem.")).to eq "No ++problem."
      expect(fix_typewriter("Math + stuff +is ok+")).to eq "Math + stuff is ok"
      expect(fix_typewriter("Hello +{Foo}+ World")).to eq "Hello {Foo} World"
    end

    it "does not apply to code blocks" do
      expect(fix_typewriter("Hello +hello+")).to eq "Hello +hello+"
    end

    it "does not apply to HTML tag attributes" do
      expect(fix_typewriter("A+b+c")).to eq "A+b+c"
      expect(fix_typewriter("")).to eq ""
    end

    it "still applies inside of other tags" do
      expect(fix_typewriter("
    +foo+
    ")).to eq "
    foo
    "
    end
  end
end
yard-0.9.37/spec/templates/helpers/markup_helper_spec.rb000066400000000000000000000124611466601756300233620ustar00rootroot00000000000000# frozen_string_literal: true

module YARD::Templates::Helpers::MarkupHelper
  public :load_markup_provider, :markup_class, :markup_provider
end

class GeneratorMock
  attr_accessor :options
  include YARD::Templates::Helpers::MarkupHelper
  def initialize(options = Templates::TemplateOptions.new)
    self.options = options
  end
end

RSpec.describe YARD::Templates::Helpers::MarkupHelper do
  before do
    YARD::Templates::Helpers::MarkupHelper.clear_markup_cache
  end

  describe "#load_markup_provider" do
    before do
      allow(log).to receive(:error)
      @gen = GeneratorMock.new
      @gen.options.reset_defaults
    end

    it "exits on an invalid markup type" do
      @gen.options.markup = :invalid
      expect(@gen.load_markup_provider).to be false
    end

    it "fails when an invalid markup provider is specified" do
      @gen.options.update(:markup => :markdown, :markup_provider => :invalid)
      expect(@gen.load_markup_provider).to be false
      expect(@gen.markup_class).to eq nil
    end

    it "loads RDocMarkup if rdoc is specified and it is installed" do
      @gen.options.markup = :rdoc
      expect(@gen.load_markup_provider).to be true
      expect(@gen.markup_class).to eq YARD::Templates::Helpers::Markup::RDocMarkup
    end

    it "fails if RDoc cannot be loaded" do
      @gen.options.markup = :rdoc
      expect(@gen).to receive(:eval).with('::YARD::Templates::Helpers::Markup::RDocMarkup').and_raise(NameError)
      expect(@gen.load_markup_provider).to be false
      expect(@gen.markup_provider).to eq nil
    end

    it "searches through available markup providers for the markup type if none is set" do
      expect(@gen).to receive(:eval).with('::RedcarpetCompat').and_return(double(:bluecloth))
      expect(@gen).to receive(:require).with('redcarpet').and_return(true)
      expect(@gen).not_to receive(:require).with('maruku')
      @gen.options.markup = :markdown
      # this only raises an exception because we mock out require to avoid
      # loading any libraries but our implementation tries to return the library
      # name as a constant
      expect(@gen.load_markup_provider).to be true
      expect(@gen.markup_provider).to eq :redcarpet
    end

    it "continues searching if some of the providers are unavailable" do
      expect(@gen).to receive(:require).with('redcarpet').and_raise(LoadError)
      expect(@gen).to receive(:require).with('rdiscount').and_raise(LoadError)
      expect(@gen).to receive(:require).with('kramdown').and_raise(LoadError)
      expect(@gen).to receive(:require).with('bluecloth').and_raise(LoadError)
      expect(@gen).to receive(:require).with('maruku').and_raise(LoadError)
      expect(@gen).to receive(:require).with('rpeg-markdown').and_return(true)
      expect(@gen).to receive(:eval).with('::PEGMarkdown').and_return(true)
      @gen.options.markup = :markdown
      # this only raises an exception because we mock out require to avoid
      # loading any libraries but our implementation tries to return the library
      # name as a constant
      @gen.load_markup_provider
      expect(@gen.markup_provider).to eq :"rpeg-markdown"
    end

    it "overrides the search if `:markup_provider` is set in options" do
      expect(@gen).to receive(:require).with('rdiscount').and_return(true)
      expect(@gen).to receive(:eval).with('::RDiscount').and_return(true)
      @gen.options.update(:markup => :markdown, :markup_provider => :rdiscount)
      @gen.load_markup_provider
      expect(@gen.markup_provider).to eq :rdiscount
    end

    it "fails if no provider is found" do
      YARD::Templates::Helpers::MarkupHelper::MARKUP_PROVIDERS[:markdown].each do |p|
        expect(@gen).to receive(:require).with(p[:lib].to_s).and_raise(LoadError)
      end
      @gen.options.markup = :markdown
      expect(@gen.load_markup_provider).to be false
      expect(@gen.markup_provider).to eq nil
    end

    it "fails if overridden provider is not found" do
      expect(@gen).to receive(:require).with('rdiscount').and_raise(LoadError)
      @gen.options.update(:markup => :markdown, :markup_provider => :rdiscount)
      expect(@gen.load_markup_provider).to be false
      expect(@gen.markup_provider).to eq nil
    end

    it "fails if the markup type is not found" do
      expect(log).to receive(:error).with(/Invalid markup/)
      @gen.options.markup = :xxx
      expect(@gen.load_markup_provider).to be false
      expect(@gen.markup_provider).to eq nil
    end
  end

  describe "#markup_for_file" do
    include YARD::Templates::Helpers::MarkupHelper

    it "looks for a shebang line" do
      expect(markup_for_file("#!text\ntext here", 'file.rdoc')).to eq :text
    end

    it "returns the default markup type if no shebang is found or no valid ext is found" do
      allow(self).to receive(:options).and_return(Options.new.update(:markup => :default_type))
      expect(markup_for_file('', 'filename')).to eq :default_type
    end

    it "looks for a file extension if no shebang is found" do
      expect(markup_for_file('', 'filename.MD')).to eq :markdown
      expect(markup_for_file('', 'filename.ORG')).to eq :org
    end

    Templates::Helpers::MarkupHelper::MARKUP_EXTENSIONS.each do |type, exts|
      exts.each do |ext|
        it "recognizes .#{ext} as #{type} markup type" do
          expect(markup_for_file('', "filename.#{ext}")).to eq type
        end
      end
    end
  end
end
yard-0.9.37/spec/templates/helpers/method_helper_spec.rb000066400000000000000000000071121466601756300233400ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Templates::Helpers::MethodHelper do
  include YARD::Templates::Helpers::BaseHelper
  include YARD::Templates::Helpers::MethodHelper

  describe "#format_args" do
    it "displays keyword arguments" do
      params = [['a:', '1'], ['b:', '2'], ['**kwargs', nil]]
      YARD.parse_string 'def foo; end'
      allow(Registry.at('#foo')).to receive(:parameters) { params }
      expect(format_args(Registry.at('#foo'))).to eq '(a: 1, b: 2, **kwargs)'
    end

    it "does not show &blockarg if no @param tag and has @yield" do
      YARD.parse_string <<-'eof'
        # @yield blah
        def foo(&block); end
      eof
      expect(format_args(Registry.at('#foo'))).to eq ''
    end

    it "does not show &blockarg if no @param tag and has @yieldparam" do
      YARD.parse_string <<-'eof'
        # @yieldparam blah test
        def foo(&block); end
      eof
      expect(format_args(Registry.at('#foo'))).to eq ''
    end

    it "shows &blockarg if @param block is documented (even with @yield)" do
      YARD.parse_string <<-'eof'
        # @yield [a,b]
        # @yieldparam a test
        # @param block test
        def foo(&block) end
      eof
      expect(format_args(Registry.at('#foo'))).to eq '(&block)'
    end
  end

  describe "#format_block" do
    before { YARD::Registry.clear }

    it "shows block for method with yield" do
      YARD.parse_string <<-'eof'
        def foo; yield(a, b, c) end
      eof
      expect(format_block(Registry.at('#foo'))).to eq "{|a, b, c| ... }"
    end

    it "shows block for method with @yieldparam tags" do
      YARD.parse_string <<-'eof'
        # @yieldparam _self me!
        def foo; end
      eof
      expect(format_block(Registry.at('#foo'))).to eq "{|_self| ... }"
    end

    it "shows block for method with @yield but no types" do
      YARD.parse_string <<-'eof'
        # @yield blah
        # @yieldparam a
        def foo; end

        # @yield blah
        def foo2; end
      eof
      expect(format_block(Registry.at('#foo'))).to eq "{|a| ... }"
      expect(format_block(Registry.at('#foo2'))).to eq "{ ... }"
    end

    it "shows block for method with @yield and types" do
      YARD.parse_string <<-'eof'
        # @yield [a, b, c] blah
        # @yieldparam a
        def foo; end
      eof
      expect(format_block(Registry.at('#foo'))).to eq "{|a, b, c| ... }"
    end
  end

  describe "#format_constant" do
    include YARD::Templates::Helpers::HtmlHelper

    it "displays correctly constant values which are quoted symbols" do
      YARD.parse_string %(
        class TestFmtConst
          Foo = :''
          Bar = :BAR
          Baz = :'B+z'
        end
      )
      # html_syntax_highlight will be called by format_constant for
      # Foo, Bar and Baz and in turn will enquire for options.highlight
      expect(self).to receive(:options).exactly(3).times.and_return(
        Options.new.update(:highlight => false)
      )
      foo, bar, baz = %w(Foo Bar Baz).map do |c|
        Registry.at("TestFmtConst::#{c}").value
      end
      expect(format_constant(foo)).to eq ":''"
      expect(format_constant(bar)).to eq ':BAR'
      expect(format_constant(baz)).to eq ":'B+z'"
    end

    context "when an empty string is passed as param" do
      it "returns an empty string" do
        # html_syntax_highlight will be called by format_constant
        # and in turn will enquire for options.highlight
        expect(self).to receive(:options).once.and_return(
          Options.new.update(:highlight => false)
        )

        expect(format_constant("")).to eq ""
      end
    end
  end
end
yard-0.9.37/spec/templates/helpers/module_helper_spec.rb000066400000000000000000000017631466601756300233530ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Templates::Helpers::ModuleHelper do
  include YARD::Templates::Helpers::BaseHelper
  include YARD::Templates::Helpers::ModuleHelper

  describe "#prune_method_listing" do
    before { YARD::Registry.clear }
    let(:options) { OpenStruct.new }
    let(:object) { YARD::Registry.at("Foo#bar") }
    let(:objects) { [object] }

    it "filters aliases" do
      YARD.parse_string "class Foo; def orig; end; alias bar orig end"
      expect(prune_method_listing(objects)).to eq []
    end

    it "filters attributes" do
      YARD.parse_string "class Foo; attr_accessor :bar end"
      expect(prune_method_listing(objects)).to eq []
    end

    it "ignores methods if namespace object is filtered" do
      YARD.parse_string <<-eof
        # @author test
        class Foo
          def bar; end
        end
      eof

      options.verifier = YARD::Verifier.new('@author.text != "test"')
      expect(prune_method_listing(objects)).to eq []
    end
  end
end
yard-0.9.37/spec/templates/helpers/shared_signature_examples.rb000066400000000000000000000072311466601756300247360ustar00rootroot00000000000000# frozen_string_literal: true
RSpec.shared_examples_for "signature" do
  before do
    YARD::Registry.clear
    @options = Templates::TemplateOptions.new
    @options.reset_defaults
    allow(self).to receive(:options).and_return(@options)
  end

  def trim(sig) sig.gsub(/\s+/, ' ') end

  it "shows signature for regular instance method" do
    YARD.parse_string "def foo; end"
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:regular]
  end

  it "allows default return type to be changed" do
    @options.default_return = "Hello"
    YARD.parse_string "def foo; end"
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:default_return]
  end

  it "allows default return type to be omitted" do
    @options.default_return = ""
    YARD.parse_string "def foo; end"
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:no_default_return]
  end

  it "shows signature for private class method" do
    YARD.parse_string "class A; private; def self.foo; end end"
    expect(trim(signature(Registry.at('A.foo')))).to eq @results[:private_class]
  end

  it "shows return type for single type" do
    YARD.parse_string <<-'eof'
      # @return [String]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:single]
  end

  it "shows return type for 2 types" do
    YARD.parse_string <<-'eof'
      # @return [String, Symbol]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:two_types]
  end

  it "shows return type for 2 types over multiple tags" do
    YARD.parse_string <<-'eof'
      # @return [String]
      # @return [Symbol]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:two_types_multitag]
  end

  it "shows 'Type?' if return types are [Type, nil]" do
    YARD.parse_string <<-'eof'
      # @return [Type, nil]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:type_nil]
  end

  it "shows 'Type?' if return types are [Type, nil, nil] (extra nil)" do
    YARD.parse_string <<-'eof'
      # @return [Type, nil]
      # @return [nil]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:type_nil]
  end

  it "shows 'Type+' if return types are [Type, Array]" do
    YARD.parse_string <<-'eof'
      # @return [Type, ]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:type_array]
  end

  it "shows (Type, ...) for more than 2 return types" do
    YARD.parse_string <<-'eof'
      # @return [Type, ]
      # @return [AnotherType]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:multitype]
  end

  it "shows (void) for @return [void] by default" do
    YARD.parse_string <<-'eof'
      # @return [void]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:void]
  end

  it "does not show return for @return [void] if :hide_void_return is true" do
    @options.hide_void_return = true
    YARD.parse_string <<-'eof'
      # @return [void]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:hide_void]
  end

  it "shows block for method with yield" do
    YARD.parse_string <<-'eof'
      def foo; yield(a, b, c) end
    eof
    expect(trim(signature(Registry.at('#foo')))).to eq @results[:block]
  end

  it "uses regular return tag if the @overload is empty" do
    YARD.parse_string <<-'eof'
      # @overload foobar
      #   Hello world
      # @return [String]
      def foo; end
    eof
    expect(trim(signature(Registry.at('#foo').tag(:overload)))).to eq @results[:empty_overload]
  end
end
yard-0.9.37/spec/templates/helpers/text_helper_spec.rb000066400000000000000000000037201466601756300230450ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + "/shared_signature_examples"

RSpec.describe YARD::Templates::Helpers::TextHelper do
  include YARD::Templates::Helpers::BaseHelper
  include YARD::Templates::Helpers::TextHelper
  include YARD::Templates::Helpers::MethodHelper

  describe "#signature" do
    before do
      @results = {
        :regular => "root.foo -> Object",
        :default_return => "root.foo -> Hello",
        :no_default_return => "root.foo",
        :private_class => "A.foo -> Object (private)",
        :single => "root.foo -> String",
        :two_types => "root.foo -> (String, Symbol)",
        :two_types_multitag => "root.foo -> (String, Symbol)",
        :type_nil => "root.foo -> Type?",
        :type_array => "root.foo -> Type+",
        :multitype => "root.foo -> (Type, ...)",
        :void => "root.foo -> void",
        :hide_void => "root.foo",
        :block => "root.foo {|a, b, c| ... } -> Object",
        :empty_overload => 'root.foobar -> String'
      }
    end

    def signature(obj) super(obj).strip end

    it_should_behave_like "signature"
  end

  describe "#align_right" do
    it "aligns text right" do
      text = "Method: #some_method (SomeClass)"
      expect(align_right(text)).to eq ' ' * 40 + text
    end

    it "truncates text that is longer than allowed width" do
      text = "(Defined in: /home/user/.rip/.packages/some_gem-2460672e333ac07b9190ade88ec9a91c/long/path.rb)"
      expect(align_right(text)).to eq ' ' + text[0, 68] + '...'
    end
  end

  describe "#h" do
    let(:object) do
      YARD::CodeObjects::MethodObject.new(:root, :foo, :instance).tap do |o|
        o.docstring = "test"
      end
    end

    it "resolves links" do
      expect(h("{include:#foo} 1 2 3").strip).to eq "test 1 2 3"
    end

    it "uses title when present" do
      expect(h("{A b}").strip).to eq "b"
    end

    it "uses object name when no title is present" do
      expect(h("{A}").strip).to eq "A"
    end
  end
end
yard-0.9.37/spec/templates/markup_processor_integrations/000077500000000000000000000000001466601756300237035ustar00rootroot00000000000000yard-0.9.37/spec/templates/markup_processor_integrations/asciidoctor_spec.rb000066400000000000000000000025401466601756300275460ustar00rootroot00000000000000# frozen_string_literal: true

require File.dirname(__FILE__) + '/integration_spec_helper'

RSpec.describe 'Asciidoctor integration' do
  include_context 'shared helpers for markup processor integration specs'
  let(:markup) { :asciidoc }
  let(:markup_provider) { :asciidoctor }

  let(:document) do
    <<-ASCIIDOC
== Example code listings

Indented block of Ruby code:

    x = 1

Fenced block of Ruby code:

-----
x = 2
-----

Fenced and annotated block of Ruby code:

[source,ruby]
-----
x = 3
-----

Fenced and annotated block of non-Ruby code:

[source,bash]
-----
x = 4
-----

ASCIIDOC
  end

  it 'renders level 2 header' do
    expect(rendered_document).to match(header_regexp(2, 'Example code listings'))
  end

  it 'renders indented block of code, and applies Ruby syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '1'))
  end

  it 'renders fenced block of code, and applies Ruby syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '2'))
  end

  it 'renders fenced and annotated block of Ruby code, and applies syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '3'))
  end

  it 'renders fenced and annotated block of non-Ruby code, and does not apply syntax highlight' do
    expect(rendered_document).to match('x = 4')
  end
end
yard-0.9.37/spec/templates/markup_processor_integrations/integration_spec_helper.rb000066400000000000000000000025141466601756300311260ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.shared_context 'shared helpers for markup processor integration specs' do
  after do
    YARD::Templates::Helpers::MarkupHelper.clear_markup_cache
  end

  let(:rendered_document) { html_renderer.htmlify document }

  let(:template_options) do
    Templates::TemplateOptions.new.tap do |o|
      o.reset_defaults
      o.default_return = nil
      o.markup = markup
      o.markup_provider = markup_provider
    end
  end

  let(:html_renderer) do
    obj = OpenStruct.new
    obj.options = template_options
    obj.object = Registry.root
    obj.extend(Templates::Helpers::HtmlHelper)
    obj
  end

  before(:each) do
    if html_renderer.markup_class(markup).nil?
      skip "Missing markup renderer #{markup}"
    end
  end

  # Works only with one-liners.
  def highlighted_ruby_regexp(*identifiers)
    prefix = Regexp.escape '
    '
    any_span_tag = 'http://example.com
    '
      )
    end
  end

  describe 'Redcarpet' do
    let(:markup) { :markdown }
    let(:markup_provider) { :redcarpet }

    include_examples 'shared examples for markdown processors'


    it 'generates anchor tags for level 2 header' do
      expect(rendered_document).to include('
    Example code listings
    ')
    end

    it 'does not create line break via backslash' do
      expect(rendered_document).to include("commonmark line break with\\\na backslash")
    end
  end

  describe 'CommonMarker', if:  RUBY_VERSION >= '2.3' do
    let(:markup) { :markdown }
    let(:markup_provider) { :commonmarker }

    include_examples 'shared examples for markdown processors'

    it 'generates level 2 header without id' do
      expect(rendered_document).to include('
    Example code listings
    ')
    end

    it 'creates line break via backslash' do
      expect(rendered_document).to include("commonmark line break with
    \na backslash")
    end
  end
end
yard-0.9.37/spec/templates/markup_processor_integrations/rdoc_markdown_spec.rb000066400000000000000000000021441466601756300300740ustar00rootroot00000000000000# frozen_string_literal: true

require File.dirname(__FILE__) + '/integration_spec_helper'

RSpec.describe 'Markdown via RDoc integration' do
  include_context 'shared helpers for markup processor integration specs'
  let(:markup) { :markdown }
  let(:markup_provider) { :rdoc }

  let(:document) do
    <<-MARKDOWN
## Example code listings

Indented block of Ruby code:

    x = 1

Fenced block of Ruby code:

```
x = 2
```

Fenced and annotated block of Ruby code:

```ruby
x = 3
```

MARKDOWN
  end

  it 'renders level 2 header' do
    expect(rendered_document).to match(header_regexp(2, 'Example code listings'))
  end

  it 'renders indented block of code, and applies Ruby syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '1'))
  end

  it 'renders fenced block of code, and applies Ruby syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '2'))
  end

  it 'renders fenced and annotated block of Ruby code, and applies syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '3'))
  end
end
yard-0.9.37/spec/templates/markup_processor_integrations/rdoc_spec.rb000066400000000000000000000020311466601756300261650ustar00rootroot00000000000000# frozen_string_literal: true

require File.dirname(__FILE__) + '/integration_spec_helper'

RSpec.describe 'RDoc integration' do
  include_context 'shared helpers for markup processor integration specs'
  let(:markup) { :rdoc }
  # Must be nil as this is how this provider is defined.
  # See: https://github.com/lsegal/yard/commit/6634ae25878cd4fcb79.
  let(:markup_provider) { nil }

  let(:document) do
    <<-RDOC
== Example code listings

Verbatim block of Ruby code:

  x = 1

Verbatim non-Ruby block:

  This has nothing to do with Ruby.

RDOC
  end

  it 'renders level 2 header' do
    expect(rendered_document).to match(header_regexp(2, 'Example code listings'))
  end

  it 'renders indented block of code, and applies Ruby syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '1'))
  end

  it 'renders indented block of text which is not a piece of Ruby code, ' \
    'and does not apply syntax highlight' do
    expect(rendered_document).to match('This has nothing to do with Ruby.')
  end
end
yard-0.9.37/spec/templates/markup_processor_integrations/redcloth_spec.rb000066400000000000000000000032631466601756300270520ustar00rootroot00000000000000# frozen_string_literal: true

require File.dirname(__FILE__) + '/integration_spec_helper'

# Hack to fix RedCloth compat issues with MinGW compilation hosts
begin
  require 'redcloth'
rescue LoadError
  require 'rbconfig'
  RbConfig::CONFIG['arch'] = 'not_windows_dont_worry'
end

RSpec.describe 'RedCloth integration' do
  include_context 'shared helpers for markup processor integration specs'
  let(:markup) { :textile }
  let(:markup_provider) { :redcloth }

  let(:document) do
    <<-TEXTILE
h2. Example code listings

Example paragraph.

p. Example paragraph using 'p' tag.

p. Block of Ruby code using 'bc' tag:

bc. x = 1

p. Block of Ruby code using 'pre' tag:

pre. x = 2
TEXTILE
  end

  it 'renders level 2 header' do
    expect(rendered_document).to match(header_regexp(2, 'Example code listings'))
  end

  it 'renders paragraphs' do
    expect(rendered_document).
      to include('
    Example paragraph.
    ')
    # Textile may replace typewriter apostrophes here used as quotes with
    # something typographically better
    expect(rendered_document).
      to match(%r{
    Example paragraph using .*p.* tag.
    })
  end

  it 'renders bc. block, and applies Ruby syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '1'))
  end

  it 'renders pre. block, and applies Ruby syntax highlight' do
    expect(rendered_document).to match(highlighted_ruby_regexp('x', '=', '2'))
  end

  it "does not use hard breaks for newlines" do
    expect(html_renderer.htmlify("A\nB", :textile)).not_to include("= "2.1"
end
yard-0.9.37/spec/templates/module_spec.rb000066400000000000000000000104451466601756300203470ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Templates::Engine.template(:default, :module) do
  before do
    Registry.clear
    YARD.parse_string <<-'eof'
      module B
        def c; end
        def d; end
        private
        def e; end
      end

      module BaseMod
        attr_reader :base_attr1
        attr_writer :base_attr2
        attr_accessor :base_attr3
      end

      # Comments
      module A
        include BaseMod
        attr_accessor :attr1
        attr_reader :attr2

        # @overload attr3
        #   @return [String] a string
        # @overload attr3=(value)
        #   @param [String] value sets the string
        #   @return [void]
        attr_accessor :attr3

        attr_writer :attr4

        def self.a; end
        def a; end
        alias b a

        # @overload test_overload(a)
        #   hello2
        #   @param [String] a hi
        def test_overload(*args) end

        # @overload test_multi_overload(a)
        # @overload test_multi_overload(a, b)
        def test_multi_overload(*args) end

        # @return [void]
        def void_meth; end

        include B

        class Y; end
        class Q; end
        class X; end
        module Z; end
        # A long docstring for the constant. With extra text
        # and newlines.
        CONSTANT = 'value'
        @@cvar = 'value' # @deprecated
      end

      module TMP; include A end
      class TMP2; extend A end
    eof
  end

  it "renders html format correctly" do
    html_equals(Registry.at('A').format(html_options(:hide_void_return => true,
      :verifier => Verifier.new('object.type != :method || object.visibility == :public'))),
        :module001)
  end

  it "renders text format correctly" do
    YARD.parse_string <<-'eof'
      module A
        include D, E, F, A::B::C
      end
    eof

    text_equals(Registry.at('A').format(text_options), :module001)
  end

  it "renders dot format correctly" do
    expect(Registry.at('A').format(:format => :dot, :dependencies => true, :full => true)).to eq example_contents(:module001, 'dot')
  end

  it "renders groups correctly in html" do
    Registry.clear
    YARD.parse_string <<-'eof'
      module A
        # @group Foo
        attr_accessor :foo_attr
        def foo; end
        def self.bar; end

        # @group Bar
        def baz; end

        # @endgroup

        def self.baz; end
      end
    eof

    html_equals(Registry.at('A').format(html_options), :module002)
  end

  it "ignores overwritten/private attributes/constants from inherited list" do
    Registry.clear
    YARD.parse_string <<-'eof'
      module B
        attr_reader :foo
        attr_accessor :bar
        # @private
        attr_writer :baz
        FOO = 1
      end
      module A
        include B
        def foo; end
        attr_reader :bar
        FOO = 2
      end
    eof

    html_equals(Registry.at('A').
      format(html_options(:verifier => Verifier.new('!@private'))), :module003)
  end

  it "embeds mixins with :embed_mixins = ['Foo', 'Bar', 'Baz::A*']" do
    Registry.clear
    YARD.parse_string <<-'eof'
      class A
        # This method is in A
        def foo; end

        include Foo
        extend Bar
        include BarFooBar
        include Baz::XYZ
        include Baz::ABC
      end

      module BarFooBar
        def bar_foo_bar; end
      end

      module Foo
        def self.not_included; end

        # Docs for xyz
        def xyz; end
        # Docs for bar_attr
        attr_accessor :bar_attr
      end

      module Bar
        def self.not_included; end

        # @group Booya

        # Docs for baz in Booya group
        def baz; end
      end

      module Baz
        module XYZ
          # listed as inherited
          def baz_xyz; end
        end

        module ABC
          def baz_abc; end
        end
      end
    eof

    html_equals(Registry.at('A').format(html_options(:embed_mixins => ['Foo', 'Bar', 'Baz::A*'])), :module004)
  end

  it "renders constant groups correctly in html" do
    Registry.clear
    YARD.parse_string <<-'eof'
      module A
        # @group Foo
        FOO = 1

        # @deprecated
        BAR = 2

        # @group Bar
        BAZ = 3

        # @endgroup

        WORLD = 4
      end
    eof
    html_equals(Registry.at('A').format(html_options), :module005)
  end
end
yard-0.9.37/spec/templates/onefile_spec.rb000066400000000000000000000033361466601756300205040ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

class StringSerializer < YARD::Serializers::Base
  attr_accessor :files, :string
  def initialize(files, string)
    @files = files
    @string = string
  end

  def serialize(object, data)
    files << object
    string << data
  end
end

RSpec.describe YARD::Templates::Engine.template(:default, :onefile) do
  before do
    Registry.clear
    if defined?(::Encoding)
      @eenc = Encoding.default_external
      Encoding.default_external = 'ascii-8bit'
      @ienc = Encoding.default_internal
      Encoding.default_internal = 'ascii-8bit'
    end
  end

  after do
    if defined?(::Encoding)
      Encoding.default_internal = @ienc
      Encoding.default_external = @eenc
    end
  end

  def render
    @files = []
    @output = String.new("")
    YARD.parse_string <<-eof
      class A
        # Foo method
        # @return [String]
        def foo; end

        # Bar method
        # @return [Numeric]
        def bar; end
      end
    eof
    readme = CodeObjects::ExtraFileObject.new('README',
      "# This is a code comment\n\n# Top of file\n\n\nclass C; end")
    Templates::Engine.generate Registry.all(:class),
      :serializer => StringSerializer.new(@files, @output),
      :onefile => true, :format => :html, :readme => readme, :files => [readme,
        CodeObjects::ExtraFileObject.new('LICENSE', 'This is a license!')]
  end

  it "renders html" do
    render
    expect(@files).to eq ['index.html']
    expect(@output).to include("This is a code comment")
    expect(@output).to include("This is a license!")
    expect(@output).to include("Class: A")
    expect(@output).to include("Foo method")
    expect(@output).to include("Bar method")
  end
end
yard-0.9.37/spec/templates/section_spec.rb000066400000000000000000000104331466601756300205230ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Templates::Section do
  include YARD::Templates

  describe "#initialize" do
    it "converts first argument to splat if it is array" do
      s = Section.new(:name, [:foo, :bar])
      expect(s.name).to eq :name
      expect(s[0].name).to eq :foo
      expect(s[1].name).to eq :bar
    end

    it "allows initialization with Section objects" do
      s = Section.new(:name, [:foo, Section.new(:bar)])
      expect(s.name).to eq :name
      expect(s[0]).to eq Section.new(:foo)
      expect(s[1]).to eq Section.new(:bar)
    end

    it "makes a list of sections" do
      s = Section.new(:name, [:foo, [:bar]])
      expect(s).to eq Section.new(:name, Section.new(:foo, Section.new(:bar)))
    end
  end

  describe "#[]" do
    it "uses Array#[] if argument is integer" do
      expect(Section.new(:name, [:foo, :bar])[0].name).to eq :foo
    end

    it "returns new Section object if more than one argument" do
      expect(Section.new(:name, :foo, :bar, :baz)[1, 2]).to eq Section.new(:name, :bar, :baz)
    end

    it "returns new Section object if arg is Range" do
      expect(Section.new(:name, :foo, :bar, :baz)[1..2]).to eq Section.new(:name, :bar, :baz)
    end

    it "looks for section by name if arg is object" do
      expect(Section.new(:name, :foo, :bar, [:baz])[:bar][:baz]).to eq Section.new(:baz)
    end
  end

  describe "#eql?" do
    it "checks for equality of two equal sections" do
      expect(Section.new(:foo, [:a, :b])).to eql(Section.new(:foo, :a, :b))
      expect(Section.new(:foo, [:a, :b])).to eq Section.new(:foo, :a, :b)
    end

    it "is not equal if section names are different" do
      expect(Section.new(:foo, [:a, :b])).not_to eql(Section.new(:bar, :a, :b))
      expect(Section.new(:foo, [:a, :b])).not_to eq Section.new(:bar, :a, :b)
    end
  end

  describe "#==" do
    it "allows comparison to Symbol" do
      expect(Section.new(:foo, 2, 3)).to eq :foo
    end

    it "allows comparison to String" do
      expect(Section.new("foo", 2, 3)).to eq "foo"
    end

    it "allows comparison to Template" do
      t = YARD::Templates::Engine.template!(:xyzzy, '/full/path/xyzzy')
      expect(Section.new(t, 2, 3)).to eq t
    end

    it "allows comparison to Section" do
      expect(Section.new(1, [2, 3])).to eq Section.new(1, 2, 3)
    end

    it "allows comparison to Object" do
      expect(Section.new(1, [2, 3])).to eq 1
    end

    it "allows comparison to Array" do
      expect(Section.new(1, 2, [3])).to eq [1, [2, [3]]]
    end
  end

  describe "#to_a" do
    it "converts Section to regular Array list" do
      arr = Section.new(1, 2, [3, [4]]).to_a
      expect(arr.class).to eq Array
      expect(arr).to eq [1, [2, [3, [4]]]]
    end
  end

  describe "#place" do
    it "places objects as Sections" do
      expect(Section.new(1, 2, 3).place(4).before(3)).to eq [1, [2, 4, 3]]
    end

    it "places objects anywhere inside Section with before/after_any" do
      expect(Section.new(1, 2, [3, [4]]).place(5).after_any(4)).to eq [1, [2, [3, [4, 5]]]]
      expect(Section.new(1, 2, [3, [4]]).place(5).before_any(4)).to eq [1, [2, [3, [5, 4]]]]
    end

    it "allows multiple sections to be placed" do
      expect(Section.new(1, 2, 3).place(4, 5).after(3).to_a).to eq [1, [2, 3, 4, 5]]
      expect(Section.new(1, 2, 3).place(4, [5]).after(3).to_a).to eq [1, [2, 3, 4, [5]]]
    end
  end

  describe "#push" do
    it "pushes objects as Sections" do
      s = Section.new(:foo)
      s.push :bar
      expect(s[0]).to eq Section.new(:bar)
    end

    it "is aliased as #<<" do
      s = Section.new(1)
      s << :index
      expect(s[:index]).to be_a(Section)
    end
  end

  describe "#unshift" do
    it "unshifts objects as Sections" do
      s = Section.new(:foo)
      s.unshift :bar
      expect(s[0]).to eq Section.new(:bar)
    end
  end

  describe "#any" do
    it "finds item inside sections" do
      s = Section.new(:foo, Section.new(:bar, Section.new(:bar)))
      s.any(:bar).push(:baz)
      expect(s.to_a).to eq [:foo, [:bar, [:bar, :baz]]]
    end

    it "finds item in any deeply nested set of sections" do
      s = Section.new(:foo, Section.new(:bar, Section.new(:baz)))
      s.any(:baz).push(:qux)
      expect(s.to_a).to eq [:foo, [:bar, [:baz, [:qux]]]]
    end
  end
end
yard-0.9.37/spec/templates/spec_helper.rb000066400000000000000000000034641466601756300203440ustar00rootroot00000000000000# frozen_string_literal: true

include YARD::Templates

def only_copy?(result, example, type)
  return false unless defined?($COPY)

  if $COPY == :all || $COPY == example
    puts(result) unless $COPYT && $COPYT != type
  end
  $COPY ? true : false
end

def text_equals(result, expected_example)
  return if only_copy?(result, expected_example, :text)
  text_equals_string(result, example_contents(expected_example, :txt))
end

def text_equals_string(result, expected)
  expect(result).to eq expected
end

def html_equals(result, expected_example)
  return if only_copy?(result, expected_example, :html)
  html_equals_string(result, example_contents(expected_example))
end

def html_equals_string(result, expected)
  result = String.new(result)
  expected = String.new(expected)
  [expected, result].each do |value|
    value.gsub!(/(>)\s+|\s+(<)/, '\1\2')
    value.gsub!(/'/, "'")
    value.strip!
  end
  text_equals_string(result, expected)
end

def example_contents(filename, ext = 'html')
  File.read(File.join(File.dirname(__FILE__), 'examples', "#{filename}.#{ext}"))
end

module YARD::Templates::Engine
  class << self
    public :find_template_paths
  end
end

class TestHtmlTemplateOptions < Templates::TemplateOptions
  default_attr :markup, :none
  default_attr :default_return, ""
  default_attr :format, :html
  default_attr :highlight, false
end

class TestTextTemplateOptions < Templates::TemplateOptions
  default_attr :markup, :none
  default_attr :default_return, ""
  default_attr :format, :text
  default_attr :highlight, false
end

def html_options(opts = {})
  template_options(opts, TestHtmlTemplateOptions)
end

def text_options(opts = {})
  template_options(opts, TestTextTemplateOptions)
end

def template_options(opts, klass)
  options = klass.new
  options.reset_defaults
  options.update(opts)
  options
end
yard-0.9.37/spec/templates/tag_spec.rb000066400000000000000000000033471466601756300176400ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Templates::Engine.template(:default, :tags) do
  before { Registry.clear }

  describe "all known tags" do
    before do
      YARD.parse_string <<-'eof'
        # Comments
        # @abstract override me
        # @param [Hash] opts the options
        # @option opts :key ('') hello
        # @option opts :key2 (X) hello
        # @return [String] the result
        # @raise [Exception] Exception class
        # @deprecated for great justice
        # @see A
        # @see http://url.com
        # @see http://url.com Example
        # @author Name
        # @since 1.0
        # @version 1.0
        # @yield a block
        # @yieldparam [String] a a value
        # @yieldreturn [Hash] a hash
        # @example Wash your car
        #   car.wash
        # @example To kill a mockingbird
        #   a = String.new
        #   flip(a.reverse)
        def m(opts = {}) end
      eof
    end

    it "renders text format correctly" do
      text_equals(Registry.at('#m').format(text_options), :tag001)
    end
  end

  describe "param tags on non-methods" do
    it "does not display @param tags on non-method objects" do
      YARD.parse_string <<-'eof'
        # @param [#to_s] name the name
        module Foo; end
      eof

      expect { Registry.at('Foo').format(html_options) }
        .not_to raise_error
    end
  end

  describe "option tags on non-methods" do
    it "does not display @option tags on non-method objects" do
      YARD.parse_string <<-'eof'
        # @option opts name [#to_s] ('bar') the name
        module Foo; end
      eof

      expect { Registry.at('Foo').format(html_options) }
        .not_to raise_error
    end
  end
end
yard-0.9.37/spec/templates/template_spec.rb000066400000000000000000000321041466601756300206710ustar00rootroot00000000000000# frozen_string_literal: true
require File.dirname(__FILE__) + '/spec_helper'

RSpec.describe YARD::Templates::Template do
  def template(path)
    YARD::Templates::Engine.template!(path, '/full/path/' + path.to_s)
  end

  before :each do
    YARD::Templates::ErbCache.clear!
  end

  describe ".include_parent" do
    it "does not include parent directory if parent directory is a template root path" do
      mod = template('q')
      expect(mod).not_to include(template(''))
    end

    it "includes overridden parent directory" do
      allow(Engine).to receive(:template_paths).and_return(['/foo', '/bar'])
      expect(File).to receive(:directory?).with('/foo/a/b').and_return(true)
      expect(File).to receive(:directory?).with('/bar/a/b').and_return(false)
      expect(File).to receive(:directory?).with('/foo/a').at_least(1).times.and_return(true)
      expect(File).to receive(:directory?).with('/bar/a').at_least(1).times.and_return(true)
      ancestors = Engine.template('a/b').ancestors.map(&:class_name)
      expect(ancestors[0, 3]).to eq %w(Template__foo_a_b Template__bar_a Template__foo_a)
    end

    it "includes parent directory template if exists" do
      mod1 = template('x')
      mod2 = template('x/y')
      expect(mod2).to include(mod1)
    end
  end

  describe ".full_paths" do
    it "lists full_path" do
      mod = template(:a)
      expect(mod.full_paths).to eq ['/full/path/a']
    end

    it "lists paths of included modules" do
      mod = template(:a)
      mod.send(:include, template(:b))
      expect(mod.full_paths).to eq ['/full/path/a', '/full/path/b']
    end

    it "lists paths from modules of included modules" do
      mod = template(:c)
      mod.send(:include, template(:d))
      mod.send(:include, template(:a))
      expect(mod.full_paths).to eq ['c', 'a', 'b', 'd'].map {|o| '/full/path/' + o }
    end

    it "only lists full paths of modules that respond to full_paths" do
      mod = template(:d)
      mod.send(:include, Enumerable)
      expect(mod.full_paths).to eq ['/full/path/d']
    end
  end

  describe ".load_setup_rb" do
    it "loads setup.rb file for module" do
      expect(File).to receive(:file?).with('/full/path/e/setup.rb').and_return(true)
      expect(File).to receive(:read).with('/full/path/e/setup.rb').and_return(String.new('def success; end'))
      expect(template(:e).new).to respond_to(:success)
    end
  end

  describe ".T" do
    it "loads template from absolute path" do
      mod = template(:a)
      expect(Engine).to receive(:template).with('other')
      mod.T('other')
    end
  end

  describe ".find_file" do
    it "finds file in the module's full_path" do
      expect(File).to receive(:file?).with('/full/path/a/basename').and_return(false)
      expect(File).to receive(:file?).with('/full/path/b/basename').and_return(true)
      expect(template(:a).find_file('basename')).to eq '/full/path/b/basename'
    end

    it "returns nil if no file is found" do
      expect(File).to receive(:file?).with('/full/path/a/basename').and_return(false)
      expect(File).to receive(:file?).with('/full/path/b/basename').and_return(false)
      expect(template(:a).find_file('basename')).to be nil
    end
  end

  describe ".find_nth_file" do
    it "finds 2nd existing file in template paths" do
      expect(File).to receive(:file?).with('/full/path/a/basename').and_return(true)
      expect(File).to receive(:file?).with('/full/path/b/basename').and_return(true)
      expect(template(:a).find_nth_file('basename', 2)).to eq '/full/path/b/basename'
    end

    it "returns nil if no file is found" do
      expect(File).to receive(:file?).with('/full/path/a/basename').and_return(true)
      expect(File).to receive(:file?).with('/full/path/b/basename').and_return(true)
      expect(template(:a).find_nth_file('basename', 3)).to be nil
    end
  end

  describe ".extra_includes" do
    it "is included when a module is initialized" do
      module MyModule; end
      Template.extra_includes << MyModule
      expect(template(:e).new).to be_kind_of(MyModule)
    end

    it "supports lambdas in list" do
      module MyModule2; end
      Template.extra_includes << lambda {|opts| MyModule2 if opts.format == :html }
      expect(template(:f).new(:format => :html)).to be_kind_of(MyModule2)
      metaclass = (class << template(:g).new(:format => :text); self end)
      expect(metaclass.ancestors).not_to include(MyModule2)
    end
  end

  describe ".is_a?" do
    it "is kind of Template" do
      expect(template(:e).is_a?(Template)).to be true
    end
  end

  describe "#T" do
    it "delegates to class method" do
      expect(template(:e)).to receive(:T).with('test')
      template(:e).new.T('test')
    end
  end

  describe "#init" do
    it "is called during initialization" do
      module YARD::Templates::Engine::Template__full_path_e # rubocop:disable Style/ClassAndModuleCamelCase
        def init; sections 1, 2, 3 end
      end
      expect(template(:e).new.sections).to eq Section.new(nil, 1, 2, 3)
    end
  end

  describe "#file" do
    it "reads the file if it exists" do
      expect(File).to receive(:file?).with('/full/path/e/abc').and_return(true)
      expect(IO).to receive(:read).with('/full/path/e/abc').and_return('hello world')
      expect(template(:e).new.file('abc')).to eq 'hello world'
    end

    it "raises ArgumentError if the file does not exist" do
      expect(File).to receive(:file?).with('/full/path/e/abc').and_return(false)
      expect { template(:e).new.file('abc') }.to raise_error(ArgumentError)
    end

    it "replaces {{{__super__}}} with inherited template contents if allow_inherited=true" do
      expect(File).to receive(:file?).with('/full/path/a/abc').twice.and_return(true)
      expect(File).to receive(:file?).with('/full/path/b/abc').and_return(true)
      expect(IO).to receive(:read).with('/full/path/a/abc').and_return(String.new('foo {{{__super__}}}'))
      expect(IO).to receive(:read).with('/full/path/b/abc').and_return(String.new('bar'))
      expect(template(:a).new.file('abc', true)).to eq "foo bar"
    end

    it "does not replace {{{__super__}}} with inherited template contents if allow_inherited=false" do
      expect(File).to receive(:file?).with('/full/path/a/abc').and_return(true)
      expect(IO).to receive(:read).with('/full/path/a/abc').and_return('foo {{{__super__}}}')
      expect(template(:a).new.file('abc')).to eq "foo {{{__super__}}}"
    end
  end

  describe "#superb" do
    it "returns the inherited erb template contents" do
      expect(File).to receive(:file?).with('/full/path/a/test.erb').and_return(true)
      expect(File).to receive(:file?).with('/full/path/b/test.erb').and_return(true)
      expect(IO).to receive(:read).with('/full/path/b/test.erb').and_return('bar')
      template = template(:a).new
      template.section = :test
      expect(template.superb).to eq "bar"
    end

    it "works inside an erb template" do
      expect(File).to receive(:file?).with('/full/path/a/test.erb').twice.and_return(true)
      expect(File).to receive(:file?).with('/full/path/b/test.erb').and_return(true)
      expect(IO).to receive(:read).with('/full/path/a/test.erb').and_return('foo<%= superb %>!')
      expect(IO).to receive(:read).with('/full/path/b/test.erb').and_return('bar')
      template = template(:a).new
      template.section = :test
      expect(template.erb(:test)).to eq "foobar!"
    end
  end

  describe "#sections" do
    it "allows sections to be set if arguments are provided" do
      mod = template(:e).new
      mod.sections 1, 2, [3]
      expect(mod.sections).to eq Section.new(nil, 1, 2, [3])
    end
  end

  describe "#run" do
    it "renders all sections" do
      mod = template(:e).new
      allow(mod).to receive(:render_section) {|section| section.name.to_s }
      mod.sections :a, :b, :c
      expect(mod.run).to eq 'abc'
    end

    it "renders all sections with options" do
      mod = template(:e).new
      allow(mod).to receive(:render_section) {|section| section.name.to_s }
      expect(mod).to receive(:add_options).with({:a => 1}).and_yield
      mod.sections :a
      expect(mod.run(:a => 1)).to eq 'a'
    end

    it "runs section list if provided" do
      mod = template(:e).new
      expect(mod).to receive(:render_section).exactly(2).times do |section|
        expect([:q, :x]).to include(section.name)
        section.name.to_s
      end
      mod.run({}, [:q, :x])
    end

    it "accepts a nil section as empty string" do
      mod = template(:e).new
      allow(mod).to receive(:render_section) { nil }
      mod.sections :a
      expect(mod.run).to eq ""
    end
  end

  describe "#add_options" do
    it "sets instance variables in addition to options" do
      mod = template(:f).new
      mod.send(:add_options, :a => 1, :b => 2)
      expect(mod.options).to eq(:a => 1, :b => 2)
      expect(mod.instance_variable_get("@a")).to eq 1
      expect(mod.instance_variable_get("@b")).to eq 2
    end

    it "sets instance variables and options only for the block" do
      mod = template(:f).new
      mod.send(:add_options, :a => 100, :b => 200) do
        expect(mod.options).to eq(:a => 100, :b => 200)
      end
      expect(mod.options).not_to eq(:a => 100, :b => 200)
    end
  end

  describe "#render_section" do
    it "calls method if method exists by section name as Symbol" do
      mod = template(:f).new
      expect(mod).to receive(:respond_to?).with(:a).and_return(true)
      expect(mod).to receive(:respond_to?).with('a').and_return(true)
      expect(mod).to receive(:send).with(:a).and_return('a')
      expect(mod).to receive(:send).with('a').and_return('a')
      expect(mod.run({}, [:a, 'a'])).to eq 'aa'
    end

    it "calls erb if no method exists by section name" do
      mod = template(:f).new
      expect(mod).to receive(:respond_to?).with(:a).and_return(false)
      expect(mod).to receive(:respond_to?).with('a').and_return(false)
      expect(mod).to receive(:erb).with(:a).and_return('a')
      expect(mod).to receive(:erb).with('a').and_return('a')
      expect(mod.run({}, [:a, 'a'])).to eq 'aa'
    end

    it "runs a template if section is one" do
      mod2 = template(:g)
      expect(mod2).to receive(:run)
      mod = template(:f).new
      mod.sections mod2
      mod.run
    end

    it "runs a template instance if section is one" do
      mod2 = template(:g).new
      expect(mod2).to receive(:run)
      mod = template(:f).new
      mod.sections mod2
      mod.run
    end
  end

  describe "#yield" do
    it "yields a subsection" do
      mod = template(:e).new
      mod.sections :a, [:b, :c]
      class << mod
        def a; "(" + yield + ")" end
        def b; "b" end
        def c; "c" end
      end

      expect(mod.run).to eq "(b)"
    end

    it "yields a subsection within a yielded subsection" do
      mod = template(:e).new
      mod.sections :a, [:b, [:c]]
      class << mod
        def a; "(" + yield + ")" end
        def b; yield end
        def c; "c" end
      end

      expect(mod.run).to eq "(c)"
    end

    it "supports arbitrary nesting" do
      mod = template(:e).new
      mod.sections :a, [:b, [:c, [:d, [:e]]]]
      class << mod
        def a; "(" + yield + ")" end
        def b; yield end
        def c; yield end
        def d; yield end
        def e; "e" end
      end

      expect(mod.run).to eq "(e)"
    end

    it "yields first two elements if yield is called twice" do
      mod = template(:e).new
      mod.sections :a, [:b, :c, :d]
      class << mod
        def a; "(" + yield + yield + ")" end
        def b; 'b' end
        def c; "c" end
      end

      expect(mod.run).to eq "(bc)"
    end

    it "ignores any subsections inside subsection yields" do
      mod = template(:e).new
      mod.sections :a, [:b, [:c], :d]
      class << mod
        def a; "(" + yield + yield + ")" end
        def b; 'b' end
        def d; "d" end
      end

      expect(mod.run).to eq "(bd)"
    end

    it "allows extra options passed via yield" do
      mod = template(:e).new
      mod.sections :a, [:b]
      class << mod
        def a; "(" + yield(:x => "a") + ")" end
        def b; options.x + @x end
      end

      expect(mod.run).to eq "(aa)"
    end
  end

  describe "#yieldall" do
    it "yields all subsections" do
      mod = template(:e).new
      mod.sections :a, [:b, [:d, [:e]], :c]
      class << mod
        def a; "(" + yieldall + ")" end
        def b; "b" + yieldall end
        def c; "c" end
        def d; 'd' + yieldall end
        def e; 'e' end
      end

      expect(mod.run).to eq "(bdec)"
    end

    it "yields options to all subsections" do
      mod = template(:e).new
      mod.sections :a, [:b, :c]
      class << mod
        def a; "(" + yieldall(:x => "2") + ")" end
        def b; @x end
        def c; @x end
      end
      expect(mod.run).to eq "(22)"
    end

    it "yields all subsections more than once" do
      mod = template(:e).new
      mod.sections :a, [:b]
      class << mod
        def a; "(" + yieldall + yieldall + ")" end
        def b; "b" end
      end

      expect(mod.run).to eq "(bb)"
    end

    it "does not yield if no yieldall is called" do
      mod = template(:e).new
      mod.sections :a, [:b]
      class << mod
        def a; "()" end
        def b; "b" end
      end

      expect(mod.run).to eq "()"
    end
  end
end
yard-0.9.37/spec/verifier_spec.rb000066400000000000000000000060641466601756300167010ustar00rootroot00000000000000# frozen_string_literal: true

RSpec.describe YARD::Verifier do
  describe "#parse_expressions" do
    it "creates #__execute method" do
      v = Verifier.new("expr1")
      expect(v).to respond_to(:__execute)
    end

    it "parses @tagname into tag('tagname')" do
      obj = double(:object)
      expect(obj).to receive(:tag).with('return')
      Verifier.new('@return').call(obj)
    end

    it "parses @@tagname into object.tags('tagname')" do
      obj = double(:object)
      expect(obj).to receive(:tags).with('return')
      Verifier.new('@@return').call(obj)
    end

    it "allows namespaced tag using @{} syntax" do
      obj = double(:object)
      expect(obj).to receive(:tag).with('yard.return')
      Verifier.new('@{yard.return}').call(obj)
    end

    it "allows namespaced tags using @{} syntax" do
      obj = double(:object)
      expect(obj).to receive(:tags).with('yard.return')
      Verifier.new('@@{yard.return}').call(obj)
    end

    it "calls methods on tag object" do
      obj = double(:object)
      obj2 = double(:tag)
      expect(obj).to receive(:tag).with('return').and_return obj2
      expect(obj2).to receive(:foo)
      Verifier.new('@return.foo').call(obj)
    end

    it "sends any missing methods to object" do
      obj = double(:object)
      expect(obj).to receive(:has_tag?).with('return')
      Verifier.new('has_tag?("return")').call(obj)
    end

    it "allows multiple expressions" do
      obj = double(:object)
      expect(obj).to receive(:tag).with('return').and_return(true)
      expect(obj).to receive(:tag).with('param').and_return(false)
      expect(Verifier.new('@return', '@param').call(obj)).to be false
    end
  end

  describe "#o" do
    it "aliases object to o" do
      obj = double(:object)
      expect(obj).to receive(:a).ordered
      Verifier.new('o.a').call(obj)
    end
  end

  describe "#call" do
    it "doubles a nonexistent tag so that exceptions are not raised" do
      obj = double(:object)
      expect(obj).to receive(:tag).and_return(nil)
      expect(Verifier.new('@return.text').call(obj)).to be false
    end

    it "does not fail if no expressions were added" do
      expect { Verifier.new.call(nil) }.not_to raise_error
    end

    it "always ignores proxy objects and return true" do
      v = Verifier.new('tag(:x)')
      expect { expect(v.call(P('foo'))).to be true }.not_to raise_error
    end
  end

  describe "#expressions" do
    it "maintains a list of all unparsed expressions" do
      expect(Verifier.new('@return.text', '@private').expressions).to eq ['@return.text', '@private']
    end
  end

  describe "#expressions=" do
    it "recompiles expressions when attribute is modified" do
      obj = double(:object)
      expect(obj).to receive(:tag).with('return')
      v = Verifier.new
      v.expressions = ['@return']
      v.call(obj)
    end
  end

  describe "#add_expressions" do
    it "adds new expressions and recompile" do
      obj = double(:object)
      expect(obj).to receive(:tag).with('return')
      v = Verifier.new
      v.add_expressions '@return'
      v.call(obj)
    end
  end
end
yard-0.9.37/tasks/000077500000000000000000000000001466601756300137145ustar00rootroot00000000000000yard-0.9.37/tasks/prepare_tag.rake000066400000000000000000000030361466601756300170530ustar00rootroot00000000000000require 'json'
require 'tempfile'

namespace :release do
  desc 'Updates repository and tags VERSION=X.Y.Z'
  task :tag do
    restore_file = Tempfile.new
    restore_file.close
    at_exit { restore_file.unlink }

    version = ENV['VERSION']
    build_path = File.expand_path(File.join(`gem which samus`.strip, '..', '..', 'commands', 'build'))
    samus_contents = File.read(File.join(__dir__, '..', 'samus.json'))
    samus_json = JSON.parse(samus_contents.gsub('$version', version))

    samus_json['actions'].each do |action|
      env = {
        '_VERSION' => version,
        '__ORIG_BRANCH' => `git rev-parse --abbrev-ref HEAD`.strip,
        '__RESTORE_FILE' => restore_file.path,
      }
      (action['arguments'] || {}).each {|k, v| env["_#{k.upcase}"] = v }
      file = File.join(build_path, action['action'])
      shebang = File.readlines(file).first[%r{\A#!(?:\S+)/(.+)}, 1].strip.split(' ')
      cmd = [*shebang, file, *action['files']]
      puts "[C] #{action['action']} #{(action['files'] || []).join(' ')}"
      output = ""
      IO.popen(env, cmd) {|io| output = io.read }
      status = $?
      unless status.success?
        puts "[F] Last command failed with: #{status.to_i}"
        puts output
        exit(status.to_i)
      end
    end

    puts ""
    puts "Tag v#{version} created. To publish, type the following:"
    puts ""
    puts "  bundle exec rake release:push VERSION=#{version}"
  end

  desc 'Pushes the main branch and tag for VERSION=X.Y.Z'
  task :push do
    sh "git push origin main v#{ENV['VERSION']}"
  end
end
yard-0.9.37/tasks/update_error_map.rake000066400000000000000000000030321466601756300201060ustar00rootroot00000000000000# frozen_string_literal: true

# Script to generate the Error class name map in:
# lib/yard/handlers/c/base.rb

require 'open-uri'
require 'stringio'

desc 'Update the error class names map'
task :update_error_map do

  ERROR_C_URL = 'https://raw.githubusercontent.com/ruby/ruby/master/error.c'

  INIT_MATCH = /void\s+Init_Exception\(void\)\s*\{(.+?)^\}/m
  NAME_MATCH = /(\w+)\s*=\s*rb_define_class\("([^"]+)"/

  $stderr.puts "Downloading #{ERROR_C_URL} ..."
  content = open(ERROR_C_URL) { |io| io.read }

  $stderr.puts "Extracting class names ..."
  init_source = content.match(INIT_MATCH).captures.first
  map = init_source.scan(NAME_MATCH).sort_by { |key, value| key }

  $stderr.puts "Generating new lookup table ..."
  indent = '  ' * 4
  source = StringIO.new
  source.puts "#{indent}ERROR_CLASS_NAMES = {"
  map.each do |variable, name|
    source.puts "#{indent}  '#{variable}' => '#{name}',"
  end
  source.puts "#{indent}}"

  $stderr.puts source.string

  $stderr.puts "Patching 'lib/yard/handlers/c/base.rb' ..."
  CLASS_NAME_MAP_MATCH = /^\s+ERROR_CLASS_NAMES = {[^}]+}/

  PROJECT_PATH = File.expand_path('..', __dir__)
  C_BASE_HANDLER = File.join(PROJECT_PATH, 'lib/yard/handlers/c/base.rb')

  File.open(C_BASE_HANDLER, 'r+') { |file|
    content = file.read
    # .rstrip is added to avoid adding new empty lines due to the new lines
    # added by `.puts` when building the string.
    content.gsub!(CLASS_NAME_MAP_MATCH, source.string.rstrip)
    file.rewind
    file.truncate(0)
    file.write(content)
  }

  $stderr.puts "Done!"

end
yard-0.9.37/templates/000077500000000000000000000000001466601756300145655ustar00rootroot00000000000000yard-0.9.37/templates/default/000077500000000000000000000000001466601756300162115ustar00rootroot00000000000000yard-0.9.37/templates/default/class/000077500000000000000000000000001466601756300173165ustar00rootroot00000000000000yard-0.9.37/templates/default/class/dot/000077500000000000000000000000001466601756300201045ustar00rootroot00000000000000yard-0.9.37/templates/default/class/dot/setup.rb000066400000000000000000000001601466601756300215660ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/module/dot')

def init
  super
  sections.push :superklass
end
yard-0.9.37/templates/default/class/dot/superklass.erb000066400000000000000000000002451466601756300227730ustar00rootroot00000000000000<% if object.superclass.path != "Object" && object.superclass.path != "BasicObject" %>
  <%= format_path object %> -> <%= format_path object.superclass %>;
<% end %>yard-0.9.37/templates/default/class/html/000077500000000000000000000000001466601756300202625ustar00rootroot00000000000000yard-0.9.37/templates/default/class/html/constructor_details.erb000066400000000000000000000004751466601756300250540ustar00rootroot00000000000000
    
  
    Constructor Details
    
  <% if @ctor.namespace != object %>
    
    This class inherits a constructor from <%= linkify @ctor, @ctor.namespace.path %>
    
  <% else %>
    <%= yieldall :object => @ctor, :index => 0 %>
  <% end %>

    
yard-0.9.37/templates/default/class/html/setup.rb000066400000000000000000000000771466601756300217530ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/module/html')
yard-0.9.37/templates/default/class/html/subclasses.erb000066400000000000000000000002421466601756300231210ustar00rootroot00000000000000
    
  
    Direct Known Subclasses
    
  
    <%= @subclasses.map {|name, child| linkify(child, name) }.join(", ") %>
    

    
yard-0.9.37/templates/default/class/setup.rb000066400000000000000000000020001466601756300207730ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/module')

def init
  super
  sections.place(:subclasses).before(:children)
  sections.place(:constructor_details, [T('method_details')]).before(:methodmissing)
end

def constructor_details
  ctors = object.meths(:inherited => true, :included => true)
  @ctor = ctors.find(&:constructor?)
  return unless @ctor
  return if prune_method_listing([@ctor]).empty?
  erb(:constructor_details)
end

def subclasses
  return if object.path == "Object" # don't show subclasses for Object
  unless globals.subclasses
    globals.subclasses = {}
    list = run_verifier Registry.all(:class)
    list.each do |o|
      (globals.subclasses[o.superclass.path] ||= []) << o if o.superclass
    end
  end

  @subclasses = globals.subclasses[object.path]
  return if @subclasses.nil? || @subclasses.empty?
  @subclasses = @subclasses.sort_by(&:path).map do |child|
    name = child.path
    name = object.relative_path(child) if object.namespace
    [name, child]
  end
  erb(:subclasses)
end
yard-0.9.37/templates/default/class/text/000077500000000000000000000000001466601756300203025ustar00rootroot00000000000000yard-0.9.37/templates/default/class/text/setup.rb000066400000000000000000000003771466601756300217760ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/module/text')

def init
  super
  sections.place(:subclasses).before(:children)
  sections.delete(:children)
end

def format_object_title(object)
  "Class: #{object.title} < #{object.superclass.title}"
end
yard-0.9.37/templates/default/class/text/subclasses.erb000066400000000000000000000001721466601756300231430ustar00rootroot00000000000000Direct Known Subclasses:
------------------------

<%= indent(wrap(@subclasses.map {|name, child| name }.join(", "))) %>

yard-0.9.37/templates/default/constant/000077500000000000000000000000001466601756300200425ustar00rootroot00000000000000yard-0.9.37/templates/default/constant/text/000077500000000000000000000000001466601756300210265ustar00rootroot00000000000000yard-0.9.37/templates/default/constant/text/header.erb000066400000000000000000000003011466601756300227420ustar00rootroot00000000000000<%= title_align_right format_object_title(object) %>


<%= object.name %> = <%= object.value.size > 40 ? "\n\n" + indent(object.value) : object.value %>


<%= hr %>

<%= yieldall %>

<%= hr %>
yard-0.9.37/templates/default/constant/text/setup.rb000066400000000000000000000001201466601756300225040ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :header, [T('docstring')]
end
yard-0.9.37/templates/default/docstring/000077500000000000000000000000001466601756300202055ustar00rootroot00000000000000yard-0.9.37/templates/default/docstring/html/000077500000000000000000000000001466601756300211515ustar00rootroot00000000000000yard-0.9.37/templates/default/docstring/html/abstract.erb000066400000000000000000000002141466601756300234430ustar00rootroot00000000000000
    
  This <%= object.type %> is abstract.
  <%= htmlify_line object.tag(:abstract).text %>

    
yard-0.9.37/templates/default/docstring/html/deprecated.erb000066400000000000000000000001611466601756300237410ustar00rootroot00000000000000
    Deprecated. <%= htmlify_line object.tag(:deprecated).text %>
    
yard-0.9.37/templates/default/docstring/html/index.erb000066400000000000000000000001271466601756300227520ustar00rootroot00000000000000
    
  
    
    <%= yieldall %>
  
    

    
yard-0.9.37/templates/default/docstring/html/note.erb000066400000000000000000000002231466601756300226050ustar00rootroot00000000000000<% object.tags(:note).each do |tag| %>
  
    
    Note:
    <%= htmlify_line tag.text %>
  
    
<% end %>
yard-0.9.37/templates/default/docstring/html/private.erb000066400000000000000000000003231466601756300233130ustar00rootroot00000000000000
    
  This <%= object.type %> is part of a private API.
  You should avoid using this <%= object.type %> if possible, as it may be removed or be changed in the future.

    
yard-0.9.37/templates/default/docstring/html/returns_void.erb000066400000000000000000000001101466601756300243560ustar00rootroot00000000000000
    This method returns an undefined value.
    yard-0.9.37/templates/default/docstring/html/text.erb000066400000000000000000000000371466601756300226270ustar00rootroot00000000000000<%= htmlify(docstring_text) %>
yard-0.9.37/templates/default/docstring/html/todo.erb000066400000000000000000000002201466601756300226020ustar00rootroot00000000000000<% object.tags(:todo).each do |tag| %>
  
    
    TODO:
    <%= htmlify_line tag.text %>
  
    
<% end %>
yard-0.9.37/templates/default/docstring/setup.rb000066400000000000000000000024141466601756300216730ustar00rootroot00000000000000# frozen_string_literal: true
def init
  return if object.docstring.blank? && !object.has_tag?(:api)
  sections :index, [:private, :deprecated, :abstract, :todo, :note, :returns_void, :text], T('tags')
end

def private
  return unless object.has_tag?(:api) && object.tag(:api).text == 'private'
  erb(:private)
end

def abstract
  return unless object.has_tag?(:abstract)
  erb(:abstract)
end

def deprecated
  return unless object.has_tag?(:deprecated)
  erb(:deprecated)
end

def todo
  return unless object.has_tag?(:todo)
  erb(:todo)
end

def note
  return unless object.has_tag?(:note)
  erb(:note)
end

def returns_void
  return unless object.type == :method
  return if object.name == :initialize && object.scope == :instance
  return unless object.tags(:return).size == 1 && object.tag(:return).types == ['void']
  erb(:returns_void)
end

def docstring_text
  text = ""
  unless object.tags(:overload).size == 1 && object.docstring.empty?
    text = object.docstring
  end

  if text.strip.empty? && object.tags(:return).size == 1 && object.tag(:return).text
    text = object.tag(:return).text.gsub(/\A([a-z])/, &:downcase)
    text = "Returns #{text.sub(/\.\Z/, '')}." unless text.empty? || text =~ /^\s*return/i
    text = text.gsub(/\A([a-z])/, &:upcase)
  end

  text.strip
end
yard-0.9.37/templates/default/docstring/text/000077500000000000000000000000001466601756300211715ustar00rootroot00000000000000yard-0.9.37/templates/default/docstring/text/abstract.erb000066400000000000000000000001001466601756300234550ustar00rootroot00000000000000<%= indent(wrap("Abstract. #{object.tag(:abstract).text}")) %>

yard-0.9.37/templates/default/docstring/text/deprecated.erb000066400000000000000000000001041466601756300237560ustar00rootroot00000000000000<%= indent(wrap("Deprecated. #{object.tag(:deprecated).text}")) %>

yard-0.9.37/templates/default/docstring/text/index.erb000066400000000000000000000000211466601756300227630ustar00rootroot00000000000000
<%= yieldall %>
yard-0.9.37/templates/default/docstring/text/note.erb000066400000000000000000000001321466601756300226240ustar00rootroot00000000000000<% object.tags(:note).each do |tag| %>
<%= indent(wrap("Note: #{tag.text}")) %>

<% end %>yard-0.9.37/templates/default/docstring/text/private.erb000066400000000000000000000001061466601756300233320ustar00rootroot00000000000000<%= indent(wrap("This #{object.type} is part of a private API.")) %>

yard-0.9.37/templates/default/docstring/text/returns_void.erb000066400000000000000000000000761466601756300244110ustar00rootroot00000000000000<%= indent(wrap("This method returns an undefined value.")) %>yard-0.9.37/templates/default/docstring/text/text.erb000066400000000000000000000000601466601756300226430ustar00rootroot00000000000000<%= indent wrap(h(docstring_text.strip), 68) %>
yard-0.9.37/templates/default/docstring/text/todo.erb000066400000000000000000000001321466601756300226240ustar00rootroot00000000000000<% object.tags(:todo).each do |tag| %>
<%= indent(wrap("TODO: #{tag.text}")) %>

<% end %>yard-0.9.37/templates/default/fulldoc/000077500000000000000000000000001466601756300176415ustar00rootroot00000000000000yard-0.9.37/templates/default/fulldoc/html/000077500000000000000000000000001466601756300206055ustar00rootroot00000000000000yard-0.9.37/templates/default/fulldoc/html/css/000077500000000000000000000000001466601756300213755ustar00rootroot00000000000000yard-0.9.37/templates/default/fulldoc/html/css/common.css000066400000000000000000000000521466601756300233740ustar00rootroot00000000000000/* Override this file with custom rules */yard-0.9.37/templates/default/fulldoc/html/css/full_list.css000066400000000000000000000127661466601756300241200ustar00rootroot00000000000000body {
  margin: 0;
  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
  font-size: 13px;
  height: 101%;
  overflow-x: hidden;
  background: #fafafa;
}

h1 { padding: 12px 10px; padding-bottom: 0; margin: 0; font-size: 1.4em; }
.clear { clear: both; }
.fixed_header { position: fixed; background: #fff; width: 100%; padding-bottom: 10px; margin-top: 0; top: 0; z-index: 9999; height: 70px; }
#search { position: absolute; right: 5px; top: 9px; padding-left: 24px; }
#content.insearch #search, #content.insearch #noresults { background: url(data:image/gif;base64,R0lGODlhEAAQAPYAAP///wAAAPr6+pKSkoiIiO7u7sjIyNjY2J6engAAAI6OjsbGxjIyMlJSUuzs7KamppSUlPLy8oKCghwcHLKysqSkpJqamvT09Pj4+KioqM7OzkRERAwMDGBgYN7e3ujo6Ly8vCoqKjY2NkZGRtTU1MTExDw8PE5OTj4+PkhISNDQ0MrKylpaWrS0tOrq6nBwcKysrLi4uLq6ul5eXlxcXGJiYoaGhuDg4H5+fvz8/KKiohgYGCwsLFZWVgQEBFBQUMzMzDg4OFhYWBoaGvDw8NbW1pycnOLi4ubm5kBAQKqqqiQkJCAgIK6urnJyckpKSjQ0NGpqatLS0sDAwCYmJnx8fEJCQlRUVAoKCggICLCwsOTk5ExMTPb29ra2tmZmZmhoaNzc3KCgoBISEiIiIgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH/C05FVFNDQVBFMi4wAwEAAAAh/hpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh+QQJCAAAACwAAAAAEAAQAAAHaIAAgoMgIiYlg4kACxIaACEJCSiKggYMCRselwkpghGJBJEcFgsjJyoAGBmfggcNEx0flBiKDhQFlIoCCA+5lAORFb4AJIihCRbDxQAFChAXw9HSqb60iREZ1omqrIPdJCTe0SWI09GBACH5BAkIAAAALAAAAAAQABAAAAdrgACCgwc0NTeDiYozCQkvOTo9GTmDKy8aFy+NOBA7CTswgywJDTIuEjYFIY0JNYMtKTEFiRU8Pjwygy4ws4owPyCKwsMAJSTEgiQlgsbIAMrO0dKDGMTViREZ14kYGRGK38nHguHEJcvTyIEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDAggPg4iJAAMJCRUAJRIqiRGCBI0WQEEJJkWDERkYAAUKEBc4Po1GiKKJHkJDNEeKig4URLS0ICImJZAkuQAhjSi/wQyNKcGDCyMnk8u5rYrTgqDVghgZlYjcACTA1sslvtHRgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCQARAtOUoQRGRiFD0kJUYWZhUhKT1OLhR8wBaaFBzQ1NwAlkIszCQkvsbOHL7Y4q4IuEjaqq0ZQD5+GEEsJTDCMmIUhtgk1lo6QFUwJVDKLiYJNUd6/hoEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4uen4ICCA+IkIsDCQkVACWmhwSpFqAABQoQF6ALTkWFnYMrVlhWvIKTlSAiJiVVPqlGhJkhqShHV1lCW4cMqSkAR1ofiwsjJyqGgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCSMhREZGIYYGY2ElYebi56fhyWQniSKAKKfpaCLFlAPhl0gXYNGEwkhGYREUywag1wJwSkHNDU3D0kJYIMZQwk8MjPBLx9eXwuETVEyAC/BOKsuEjYFhoEAIfkECQgAAAAsAAAAABAAEAAAB2eAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4ueICImip6CIQkJKJ4kigynKaqKCyMnKqSEK05StgAGQRxPYZaENqccFgIID4KXmQBhXFkzDgOnFYLNgltaSAAEpxa7BQoQF4aBACH5BAkIAAAALAAAAAAQABAAAAdogACCg4SFggJiPUqCJSWGgkZjCUwZACQkgxGEXAmdT4UYGZqCGWQ+IjKGGIUwPzGPhAc0NTewhDOdL7Ykji+dOLuOLhI2BbaFETICx4MlQitdqoUsCQ2vhKGjglNfU0SWmILaj43M5oEAOwAAAAAAAAAAAA==) no-repeat center left; }
#full_list { padding: 0; list-style: none; margin-left: 0; margin-top: 80px; font-size: 1.1em; }
#full_list ul { padding: 0; }
#full_list li { padding: 0; margin: 0; list-style: none; }
#full_list li .item { padding: 5px 5px 5px 12px; }
#noresults { padding: 7px 12px; background: #fff; }
#content.insearch #noresults { margin-left: 7px; }
li.collapsed ul { display: none; }
li a.toggle { cursor: default; position: relative; left: -5px; top: 4px; text-indent: -999px; width: 10px; height: 9px; margin-left: -10px; display: block; float: left; background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAYAAABb0P4QAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAK8AAACvABQqw0mAAAABx0RVh0U29mdHdhcmUAQWRvYmUgRmlyZXdvcmtzIENTM5jWRgMAAAAVdEVYdENyZWF0aW9uIFRpbWUAMy8xNC8wOeNZPpQAAAE2SURBVDiNrZTBccIwEEXfelIAHUA6CZ24BGaWO+FuzZAK4k6gg5QAdGAq+Bxs2Yqx7BzyL7Llp/VfzZeQhCTc/ezuGzKKnKSzpCxXJM8fwNXda3df5RZETlIt6YUzSQDs93sl8w3wBZxCCE10GM1OcWbWjB2mWgEH4Mfdyxm3PSepBHibgQE2wLe7r4HjEidpnXMYdQPKEMJcsZ4zs2POYQOcaPfwMVOo58zsAdMt18BuoVDPxUJRacELbXv3hUIX2vYmOUvi8C8ydz/ThjXrqKqqLbDIAdsCKBd+Wo7GWa7o9qzOQHVVVXeAbs+yHHCH4aTsaCOQqunmUy1yBUAXkdMIfMlgF5EXLo2OpV/c/Up7jG4hhHcYLgWzAZXUc2b2ixsfvc/RmNNfOXD3Q/oeL9axJE1yT9IOoUu6MGUkAAAAAElFTkSuQmCC) no-repeat bottom left; }
li.collapsed a.toggle { cursor: default; background-position: top left; }
li { color: #666; cursor: pointer; }
li.deprecated { text-decoration: line-through; font-style: italic; }
li.odd { background: #f0f0f0; }
li.even { background: #fafafa; }
.item:hover { background: #ddd; }
li small:before { content: "("; }
li small:after { content: ")"; }
li small.search_info { display: none; }
a, a:visited { text-decoration: none; color: #05a; }
li.clicked > .item { background: #05a; color: #ccc; }
li.clicked > .item a, li.clicked > .item a:visited { color: #eee; }
li.clicked > .item a.toggle { opacity: 0.5; background-position: bottom right; }
li.collapsed.clicked a.toggle { background-position: top right; }
#search input { border: 1px solid #bbb; border-radius: 3px; }
#full_list_nav { margin-left: 10px; font-size: 0.9em; display: block; color: #aaa; }
#full_list_nav a, #nav a:visited { color: #358; }
#full_list_nav a:hover { background: transparent; color: #5af; }
#full_list_nav span:after { content: ' | '; }
#full_list_nav span:last-child:after { content: ''; }

#content h1 { margin-top: 0; }
li { white-space: nowrap; cursor: normal; }
li small { display: block; font-size: 0.8em; }
li small:before { content: ""; }
li small:after { content: ""; }
li small.search_info { display: none; }
#search { width: 170px; position: static; margin: 3px; margin-left: 10px; font-size: 0.9em; color: #666; padding-left: 0; padding-right: 24px; }
#content.insearch #search { background-position: center right; }
#search input { width: 110px; }

#full_list.insearch ul { display: block; }
#full_list.insearch .item { display: none; }
#full_list.insearch .found { display: block; padding-left: 11px !important; }
#full_list.insearch li a.toggle { display: none; }
#full_list.insearch li small.search_info { display: block; }
yard-0.9.37/templates/default/fulldoc/html/css/style.css000066400000000000000000000510551466601756300232550ustar00rootroot00000000000000html {
  width: 100%;
  height: 100%;
}
body {
  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
  font-size: 13px;
  width: 100%;
  margin: 0;
  padding: 0;
  display: flex;
  display: -webkit-flex;
  display: -ms-flexbox;
}

#nav {
  position: relative;
  width: 100%;
  height: 100%;
  border: 0;
  border-right: 1px dotted #eee;
  overflow: auto;
}
.nav_wrap {
  margin: 0;
  padding: 0;
  width: 20%;
  height: 100%;
  position: relative;
  display: flex;
  display: -webkit-flex;
  display: -ms-flexbox;
  flex-shrink: 0;
  -webkit-flex-shrink: 0;
  -ms-flex: 1 0;
}
#resizer {
  position: absolute;
  right: -5px;
  top: 0;
  width: 10px;
  height: 100%;
  cursor: col-resize;
  z-index: 9999;
}
#main {
  flex: 5 1;
  -webkit-flex: 5 1;
  -ms-flex: 5 1;
  outline: none;
  position: relative;
  background: #fff;
  padding: 1.2em;
  padding-top: 0.2em;
  box-sizing: border-box;
}

@media (max-width: 920px) {
  .nav_wrap { width: 100%; top: 0; right: 0; overflow: visible; position: absolute; }
  #resizer { display: none; }
  #nav {
    z-index: 9999;
    background: #fff;
    display: none;
    position: absolute;
    top: 40px;
    right: 12px;
    width: 500px;
    max-width: 80%;
    height: 80%;
    overflow-y: scroll;
    border: 1px solid #999;
    border-collapse: collapse;
    box-shadow: -7px 5px 25px #aaa;
    border-radius: 2px;
  }
}

@media (min-width: 920px) {
  body { height: 100%; overflow: hidden; }
  #main { height: 100%; overflow: auto; }
  #search { display: none; }
}

@media (max-width: 320px) {
  body { height: 100%; overflow: hidden; overflow-wrap: break-word; }
  #main { height: 100%; overflow: auto; }
}

#main img { max-width: 100%; }
h1 { font-size: 25px; margin: 1em 0 0.5em; padding-top: 4px; border-top: 1px dotted #d5d5d5; }
h1.noborder { border-top: 0px; margin-top: 0; padding-top: 4px; }
h1.title { margin-bottom: 10px; }
h1.alphaindex { margin-top: 0; font-size: 22px; }
h2 {
  padding: 0;
  padding-bottom: 3px;
  border-bottom: 1px #aaa solid;
  font-size: 1.4em;
  margin: 1.8em 0 0.5em;
  position: relative;
}
h2 small { font-weight: normal; font-size: 0.7em; display: inline; position: absolute; right: 0; }
h2 small a {
  display: block;
  height: 20px;
  border: 1px solid #aaa;
  border-bottom: 0;
  border-top-left-radius: 5px;
  background: #f8f8f8;
  position: relative;
  padding: 2px 7px;
}
a { font-weight: 550; }
.clear { clear: both; }
.inline { display: inline; }
.inline p:first-child { display: inline; }
.docstring, .tags, #filecontents { font-size: 15px; line-height: 1.5145em; }
.docstring p > code, .docstring p > tt, .tags p > code, .tags p > tt {
  color: #c7254e; background: #f9f2f4; padding: 2px 4px; font-size: 1em;
  border-radius: 4px;
}
.docstring h1, .docstring h2, .docstring h3, .docstring h4 { padding: 0; border: 0; border-bottom: 1px dotted #bbb; }
.docstring h1 { font-size: 1.2em; }
.docstring h2 { font-size: 1.1em; }
.docstring h3, .docstring h4 { font-size: 1em; border-bottom: 0; padding-top: 10px; }
.summary_desc .object_link a, .docstring .object_link a {
  font-family: monospace; font-size: 1.05em;
  color: #05a; background: #EDF4FA; padding: 2px 4px; font-size: 1em;
  border-radius: 4px;
}
.rdoc-term { padding-right: 25px; font-weight: bold; }
.rdoc-list p { margin: 0; padding: 0; margin-bottom: 4px; }
.summary_desc pre.code .object_link a, .docstring pre.code .object_link a {
  padding: 0px; background: inherit; color: inherit; border-radius: inherit;
}

/* style for 
    CityNC
     */
#filecontents table, .docstring table { border-collapse: collapse; }
#filecontents table th, #filecontents table td,
.docstring table th, .docstring table td { border: 1px solid #ccc; padding: 8px; padding-right: 17px; }
#filecontents table tr:nth-child(odd),
.docstring table tr:nth-child(odd) { background: #eee; }
#filecontents table tr:nth-child(even),
.docstring table tr:nth-child(even) { background: #fff; }
#filecontents table th, .docstring table th { background: #fff; }

/* style for 
       */
#filecontents li > p, .docstring li > p { margin: 0px; }
#filecontents ul, .docstring ul { padding-left: 20px; }
/* style for 
       */
#filecontents dl, .docstring dl { border: 1px solid #ccc; }
#filecontents dt, .docstring dt { background: #ddd; font-weight: bold; padding: 3px 5px; }
#filecontents dd, .docstring dd { padding: 5px 0px; margin-left: 18px; }
#filecontents dd > p, .docstring dd > p { margin: 0px; }

.note {
  color: #222;
  margin: 20px 0;
  padding: 10px;
  border: 1px solid #eee;
  border-radius: 3px;
  display: block;
}
.docstring .note {
  border-left-color: #ccc;
  border-left-width: 5px;
}
.note.todo { background: #ffffc5; border-color: #ececaa; }
.note.returns_void { background: #efefef; }
.note.deprecated { background: #ffe5e5; border-color: #e9dada; }
.note.title.deprecated { background: #ffe5e5; border-color: #e9dada; }
.note.private { background: #ffffc5; border-color: #ececaa; }
.note.title { padding: 3px 6px; font-size: 0.9em; font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif; display: inline; }
.summary_signature + .note.title { margin-left: 7px; }
h1 .note.title { font-size: 0.5em; font-weight: normal; padding: 3px 5px; position: relative; top: -3px; text-transform: capitalize; }
.note.title { background: #efefef; }
.note.title.constructor { color: #fff; background: #6a98d6; border-color: #6689d6; }
.note.title.writeonly { color: #fff; background: #45a638; border-color: #2da31d; }
.note.title.readonly { color: #fff; background: #6a98d6; border-color: #6689d6; }
.note.title.private { background: #d5d5d5; border-color: #c5c5c5; }
.note.title.not_defined_here { background: transparent; border: none; font-style: italic; }
.discussion .note { margin-top: 6px; }
.discussion .note:first-child { margin-top: 0; }

h3.inherited {
  font-style: italic;
  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
  font-weight: normal;
  padding: 0;
  margin: 0;
  margin-top: 12px;
  margin-bottom: 3px;
  font-size: 13px;
}
p.inherited {
  padding: 0;
  margin: 0;
  margin-left: 25px;
}

.box_info dl {
  margin: 0;
  border: 0;
  width: 100%;
  font-size: 1em;
  display: flex;
  display: -webkit-flex;
  display: -ms-flexbox;
}
.box_info dl dt {
  flex-shrink: 0;
  -webkit-flex-shrink: 1;
  -ms-flex-shrink: 1;
  width: 100px;
  text-align: right;
  font-weight: bold;
  border: 1px solid #aaa;
  border-width: 1px 0px 0px 1px;
  padding: 6px 0;
  padding-right: 10px;
}
.box_info dl dd {
  flex-grow: 1;
  -webkit-flex-grow: 1;
  -ms-flex: 1;
  max-width: 420px;
  padding: 6px 0;
  padding-right: 20px;
  border: 1px solid #aaa;
  border-width: 1px 1px 0 0;
  overflow: hidden;
  position: relative;
}
.box_info dl:last-child > * {
  border-bottom: 1px solid #aaa;
}
.box_info dl:nth-child(odd) > * { background: #eee; }
.box_info dl:nth-child(even) > * { background: #fff; }
.box_info dl > * { margin: 0; }

ul.toplevel { list-style: none; padding-left: 0; font-size: 1.1em; }
.index_inline_list { padding-left: 0; font-size: 1.1em; }

.index_inline_list li {
  list-style: none;
  display: inline-block;
  padding: 0 12px;
  line-height: 30px;
  margin-bottom: 5px;
}

dl.constants { margin-left: 10px; }
dl.constants dt { font-weight: bold; font-size: 1.1em; margin-bottom: 5px; }
dl.constants.compact dt { display: inline-block; font-weight: normal }
dl.constants dd { width: 75%; white-space: pre; font-family: monospace; margin-bottom: 18px; }
dl.constants .docstring .note:first-child { margin-top: 5px; }

.summary_desc {
  margin-left: 32px;
  display: block;
  font-family: sans-serif;
  font-size: 1.1em;
  margin-top: 8px;
  line-height: 1.5145em;
  margin-bottom: 0.8em;
}
.summary_desc tt { font-size: 0.9em; }
dl.constants .note { padding: 2px 6px; padding-right: 12px; margin-top: 6px; }
dl.constants .docstring { margin-left: 32px; font-size: 0.9em; font-weight: normal; }
dl.constants .tags { padding-left: 32px; font-size: 0.9em; line-height: 0.8em; }
dl.constants .discussion *:first-child { margin-top: 0; }
dl.constants .discussion *:last-child { margin-bottom: 0; }

.method_details { border-top: 1px dotted #ccc; margin-top: 25px; padding-top: 0; }
.method_details.first { border: 0; margin-top: 5px; }
.method_details.first h3.signature { margin-top: 1em; }
p.signature, h3.signature {
  font-size: 1.1em; font-weight: normal; font-family: Monaco, Consolas, Courier, monospace;
  padding: 6px 10px; margin-top: 1em;
  background: #E8F4FF; border: 1px solid #d8d8e5; border-radius: 5px;
}
p.signature tt,
h3.signature tt { font-family: Monaco, Consolas, Courier, monospace; }
p.signature .overload,
h3.signature .overload { display: block; }
p.signature .extras,
h3.signature .extras { font-weight: normal; font-family: sans-serif; color: #444; font-size: 1em; }
p.signature .not_defined_here,
h3.signature .not_defined_here,
p.signature .aliases,
h3.signature .aliases { display: block; font-weight: normal; font-size: 0.9em; font-family: sans-serif; margin-top: 0px; color: #555; }
p.signature .aliases .names,
h3.signature .aliases .names { font-family: Monaco, Consolas, Courier, monospace; font-weight: bold; color: #000; font-size: 1.2em; }

.tags .tag_title { font-size: 1.05em; margin-bottom: 0; font-weight: bold; }
.tags .tag_title tt { color: initial; padding: initial; background: initial; }
.tags ul { margin-top: 5px; padding-left: 30px; list-style: square; }
.tags ul li { margin-bottom: 3px; }
.tags ul .name { font-family: monospace; font-weight: bold; }
.tags ul .note { padding: 3px 6px; }
.tags { margin-bottom: 12px; }

.tags .examples .tag_title { margin-bottom: 10px; font-weight: bold; }
.tags .examples .inline p { padding: 0; margin: 0; font-weight: bold; font-size: 1em; }
.tags .examples .inline p:before { content: "▸"; font-size: 1em; margin-right: 5px; }

.tags .overload .overload_item { list-style: none; margin-bottom: 25px; }
.tags .overload .overload_item .signature {
  padding: 2px 8px;
  background: #F1F8FF; border: 1px solid #d8d8e5; border-radius: 3px;
}
.tags .overload .signature { margin-left: -15px; font-family: monospace; display: block; font-size: 1.1em; }
.tags .overload .docstring { margin-top: 15px; }

.defines { display: none; }

#method_missing_details .notice.this { position: relative; top: -8px; color: #888; padding: 0; margin: 0; }

.showSource { font-size: 0.9em; }
.showSource a, .showSource a:visited { text-decoration: none; color: #666; }

#content a, #content a:visited { text-decoration: none; color: #05a; }
#content a:hover { background: #ffffa5; }

ul.summary {
  list-style: none;
  font-family: monospace;
  font-size: 1em;
  line-height: 1.5em;
  padding-left: 0px;
}
ul.summary a, ul.summary a:visited {
  text-decoration: none; font-size: 1.1em;
}
ul.summary li { margin-bottom: 5px; }
.summary_signature { padding: 4px 8px; background: #f8f8f8; border: 1px solid #f0f0f0; border-radius: 5px; }
.summary_signature:hover { background: #CFEBFF; border-color: #A4CCDA; cursor: pointer; }
.summary_signature.deprecated { background: #ffe5e5; border-color: #e9dada; }
ul.summary.compact li { display: inline-block; margin: 0px 5px 0px 0px; line-height: 2.6em;}
ul.summary.compact .summary_signature { padding: 5px 7px; padding-right: 4px; }
#content .summary_signature:hover a,
#content .summary_signature:hover a:visited {
  background: transparent;
  color: #049;
}

p.inherited a { font-family: monospace; font-size: 0.9em; }
p.inherited { word-spacing: 5px; font-size: 1.2em; }

p.children { font-size: 1.2em; }
p.children a { font-size: 0.9em; }
p.children strong { font-size: 0.8em; }
p.children strong.modules { padding-left: 5px; }

ul.fullTree { display: none; padding-left: 0; list-style: none; margin-left: 0; margin-bottom: 10px; }
ul.fullTree ul { margin-left: 0; padding-left: 0; list-style: none; }
ul.fullTree li { text-align: center; padding-top: 18px; padding-bottom: 12px; background: url(data:image/gif;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAACXBIWXMAAAsTAAALEwEAmpwYAAAKT2lDQ1BQaG90b3Nob3AgSUNDIHByb2ZpbGUAAHjanVNnVFPpFj333vRCS4iAlEtvUhUIIFJCi4AUkSYqIQkQSoghodkVUcERRUUEG8igiAOOjoCMFVEsDIoK2AfkIaKOg6OIisr74Xuja9a89+bN/rXXPues852zzwfACAyWSDNRNYAMqUIeEeCDx8TG4eQuQIEKJHAAEAizZCFz/SMBAPh+PDwrIsAHvgABeNMLCADATZvAMByH/w/qQplcAYCEAcB0kThLCIAUAEB6jkKmAEBGAYCdmCZTAKAEAGDLY2LjAFAtAGAnf+bTAICd+Jl7AQBblCEVAaCRACATZYhEAGg7AKzPVopFAFgwABRmS8Q5ANgtADBJV2ZIALC3AMDOEAuyAAgMADBRiIUpAAR7AGDIIyN4AISZABRG8lc88SuuEOcqAAB4mbI8uSQ5RYFbCC1xB1dXLh4ozkkXKxQ2YQJhmkAuwnmZGTKBNA/g88wAAKCRFRHgg/P9eM4Ors7ONo62Dl8t6r8G/yJiYuP+5c+rcEAAAOF0ftH+LC+zGoA7BoBt/qIl7gRoXgugdfeLZrIPQLUAoOnaV/Nw+H48PEWhkLnZ2eXk5NhKxEJbYcpXff5nwl/AV/1s+X48/Pf14L7iJIEyXYFHBPjgwsz0TKUcz5IJhGLc5o9H/LcL//wd0yLESWK5WCoU41EScY5EmozzMqUiiUKSKcUl0v9k4t8s+wM+3zUAsGo+AXuRLahdYwP2SycQWHTA4vcAAPK7b8HUKAgDgGiD4c93/+8//UegJQCAZkmScQAAXkQkLlTKsz/HCAAARKCBKrBBG/TBGCzABhzBBdzBC/xgNoRCJMTCQhBCCmSAHHJgKayCQiiGzbAdKmAv1EAdNMBRaIaTcA4uwlW4Dj1wD/phCJ7BKLyBCQRByAgTYSHaiAFiilgjjggXmYX4IcFIBBKLJCDJiBRRIkuRNUgxUopUIFVIHfI9cgI5h1xGupE7yAAygvyGvEcxlIGyUT3UDLVDuag3GoRGogvQZHQxmo8WoJvQcrQaPYw2oefQq2gP2o8+Q8cwwOgYBzPEbDAuxsNCsTgsCZNjy7EirAyrxhqwVqwDu4n1Y8+xdwQSgUXACTYEd0IgYR5BSFhMWE7YSKggHCQ0EdoJNwkDhFHCJyKTqEu0JroR+cQYYjIxh1hILCPWEo8TLxB7iEPENyQSiUMyJ7mQAkmxpFTSEtJG0m5SI+ksqZs0SBojk8naZGuyBzmULCAryIXkneTD5DPkG+Qh8lsKnWJAcaT4U+IoUspqShnlEOU05QZlmDJBVaOaUt2ooVQRNY9aQq2htlKvUYeoEzR1mjnNgxZJS6WtopXTGmgXaPdpr+h0uhHdlR5Ol9BX0svpR+iX6AP0dwwNhhWDx4hnKBmbGAcYZxl3GK+YTKYZ04sZx1QwNzHrmOeZD5lvVVgqtip8FZHKCpVKlSaVGyovVKmqpqreqgtV81XLVI+pXlN9rkZVM1PjqQnUlqtVqp1Q61MbU2epO6iHqmeob1Q/pH5Z/YkGWcNMw09DpFGgsV/jvMYgC2MZs3gsIWsNq4Z1gTXEJrHN2Xx2KruY/R27iz2qqaE5QzNKM1ezUvOUZj8H45hx+Jx0TgnnKKeX836K3hTvKeIpG6Y0TLkxZVxrqpaXllirSKtRq0frvTau7aedpr1Fu1n7gQ5Bx0onXCdHZ4/OBZ3nU9lT3acKpxZNPTr1ri6qa6UbobtEd79up+6Ynr5egJ5Mb6feeb3n+hx9L/1U/W36p/VHDFgGswwkBtsMzhg8xTVxbzwdL8fb8VFDXcNAQ6VhlWGX4YSRudE8o9VGjUYPjGnGXOMk423GbcajJgYmISZLTepN7ppSTbmmKaY7TDtMx83MzaLN1pk1mz0x1zLnm+eb15vft2BaeFostqi2uGVJsuRaplnutrxuhVo5WaVYVVpds0atna0l1rutu6cRp7lOk06rntZnw7Dxtsm2qbcZsOXYBtuutm22fWFnYhdnt8Wuw+6TvZN9un2N/T0HDYfZDqsdWh1+c7RyFDpWOt6azpzuP33F9JbpL2dYzxDP2DPjthPLKcRpnVOb00dnF2e5c4PziIuJS4LLLpc+Lpsbxt3IveRKdPVxXeF60vWdm7Obwu2o26/uNu5p7ofcn8w0nymeWTNz0MPIQ+BR5dE/C5+VMGvfrH5PQ0+BZ7XnIy9jL5FXrdewt6V3qvdh7xc+9j5yn+M+4zw33jLeWV/MN8C3yLfLT8Nvnl+F30N/I/9k/3r/0QCngCUBZwOJgUGBWwL7+Hp8Ib+OPzrbZfay2e1BjKC5QRVBj4KtguXBrSFoyOyQrSH355jOkc5pDoVQfujW0Adh5mGLw34MJ4WHhVeGP45wiFga0TGXNXfR3ENz30T6RJZE3ptnMU85ry1KNSo+qi5qPNo3ujS6P8YuZlnM1VidWElsSxw5LiquNm5svt/87fOH4p3iC+N7F5gvyF1weaHOwvSFpxapLhIsOpZATIhOOJTwQRAqqBaMJfITdyWOCnnCHcJnIi/RNtGI2ENcKh5O8kgqTXqS7JG8NXkkxTOlLOW5hCepkLxMDUzdmzqeFpp2IG0yPTq9MYOSkZBxQqohTZO2Z+pn5mZ2y6xlhbL+xW6Lty8elQfJa7OQrAVZLQq2QqboVFoo1yoHsmdlV2a/zYnKOZarnivN7cyzytuQN5zvn//tEsIS4ZK2pYZLVy0dWOa9rGo5sjxxedsK4xUFK4ZWBqw8uIq2Km3VT6vtV5eufr0mek1rgV7ByoLBtQFr6wtVCuWFfevc1+1dT1gvWd+1YfqGnRs+FYmKrhTbF5cVf9go3HjlG4dvyr+Z3JS0qavEuWTPZtJm6ebeLZ5bDpaql+aXDm4N2dq0Dd9WtO319kXbL5fNKNu7g7ZDuaO/PLi8ZafJzs07P1SkVPRU+lQ27tLdtWHX+G7R7ht7vPY07NXbW7z3/T7JvttVAVVN1WbVZftJ+7P3P66Jqun4lvttXa1ObXHtxwPSA/0HIw6217nU1R3SPVRSj9Yr60cOxx++/p3vdy0NNg1VjZzG4iNwRHnk6fcJ3/ceDTradox7rOEH0x92HWcdL2pCmvKaRptTmvtbYlu6T8w+0dbq3nr8R9sfD5w0PFl5SvNUyWna6YLTk2fyz4ydlZ19fi753GDborZ752PO32oPb++6EHTh0kX/i+c7vDvOXPK4dPKy2+UTV7hXmq86X23qdOo8/pPTT8e7nLuarrlca7nuer21e2b36RueN87d9L158Rb/1tWeOT3dvfN6b/fF9/XfFt1+cif9zsu72Xcn7q28T7xf9EDtQdlD3YfVP1v+3Njv3H9qwHeg89HcR/cGhYPP/pH1jw9DBY+Zj8uGDYbrnjg+OTniP3L96fynQ89kzyaeF/6i/suuFxYvfvjV69fO0ZjRoZfyl5O/bXyl/erA6xmv28bCxh6+yXgzMV70VvvtwXfcdx3vo98PT+R8IH8o/2j5sfVT0Kf7kxmTk/8EA5jz/GMzLdsAAAAgY0hSTQAAeiUAAICDAAD5/wAAgOkAAHUwAADqYAAAOpgAABdvkl/FRgAAAHtJREFUeNqMzrEJAkEURdGzuhgZbSoYWcAWoBVsB4JgZAGmphsZCZYzTQgWNCYrDN9RvMmHx+X916SUBFbo8CzD1idXrLErw1mQttgXtyrOcQ/Ny5p4Qh+2XqLYYazsPWNTiuMkRxa4vcV+evuNAUOLIx5+c2hyzv7hNQC67Q+/HHmlEwAAAABJRU5ErkJggg==) no-repeat top center; }
ul.fullTree li:first-child { padding-top: 0; background: transparent; }
ul.fullTree li:last-child { padding-bottom: 0; }
.showAll ul.fullTree { display: block; }
.showAll .inheritName { display: none; }

#search { position: absolute; right: 12px; top: 0px; z-index: 9000; }
#search a {
  display: block; float: left;
  padding: 4px 8px; text-decoration: none; color: #05a; fill: #05a;
  border: 1px solid #d8d8e5;
  border-bottom-left-radius: 3px; border-bottom-right-radius: 3px;
  background: #F1F8FF;
  box-shadow: -1px 1px 3px #ddd;
}
#search a:hover { background: #f5faff; color: #06b; fill: #06b; }
#search a.active {
  background: #568; padding-bottom: 20px; color: #fff; fill: #fff;
  border: 1px solid #457;
  border-top-left-radius: 5px; border-top-right-radius: 5px;
}
#search a.inactive { color: #999; fill: #999; }
.inheritanceTree, .toggleDefines {
  float: right;
  border-left: 1px solid #aaa;
  position: absolute; top: 0; right: 0;
  height: 100%;
  background: #f6f6f6;
  padding: 5px;
  min-width: 55px;
  text-align: center;
}

#menu { font-size: 1.3em; color: #bbb; }
#menu .title, #menu a { font-size: 0.7em; }
#menu .title a { font-size: 1em; }
#menu .title { color: #555; }
#menu a, #menu a:visited { color: #333; text-decoration: none; border-bottom: 1px dotted #bbd; }
#menu a:hover { color: #05a; }

#footer { margin-top: 15px; border-top: 1px solid #ccc; text-align: center; padding: 7px 0; color: #999; }
#footer a, #footer a:visited { color: #444; text-decoration: none; border-bottom: 1px dotted #bbd; }
#footer a:hover { color: #05a; }

#listing ul.alpha { font-size: 1.1em; }
#listing ul.alpha { margin: 0; padding: 0; padding-bottom: 10px; list-style: none; }
#listing ul.alpha li.letter { font-size: 1.4em; padding-bottom: 10px; }
#listing ul.alpha ul { margin: 0; padding-left: 15px; }
#listing ul small { color: #666; font-size: 0.7em; }

li.r1 { background: #f0f0f0; }
li.r2 { background: #fafafa; }

#content ul.summary li.deprecated .summary_signature a,
#content ul.summary li.deprecated .summary_signature a:visited { text-decoration: line-through; font-style: italic; }

#toc {
  position: relative;
  float: right;
  overflow-x: auto;
  right: -3px;
  margin-left: 20px;
  margin-bottom: 20px;
  padding: 20px; padding-right: 30px;
  max-width: 300px;
  z-index: 5000;
  background: #fefefe;
  border: 1px solid #ddd;
  box-shadow: -2px 2px 6px #bbb;
}
#toc .title { margin: 0; }
#toc ol { padding-left: 1.8em; }
#toc li { font-size: 1.1em; line-height: 1.7em; }
#toc > ol > li { font-size: 1.1em; font-weight: bold; }
#toc ol > li > ol { font-size: 0.9em; }
#toc ol ol > li > ol { padding-left: 2.3em; }
#toc ol + li { margin-top: 0.3em; }
#toc.hidden { padding: 10px; background: #fefefe; box-shadow: none; }
#toc.hidden:hover { background: #fafafa; }
#filecontents h1 + #toc.nofloat { margin-top: 0; }
@media (max-width: 560px) {
  #toc {
    margin-left: 0;
    margin-top: 16px;
    float: none;
    max-width: none;
  }
}

/* syntax highlighting */
.source_code { display: none; padding: 3px 8px; border-left: 8px solid #ddd; margin-top: 5px; }
#filecontents pre.code, .docstring pre.code, .source_code pre { font-family: monospace; }
#filecontents pre.code, .docstring pre.code { display: block; }
.source_code .lines { padding-right: 12px; color: #555; text-align: right; }
#filecontents pre.code, .docstring pre.code,
.tags pre.example {
  padding: 9px 14px;
  margin-top: 4px;
  border: 1px solid #e1e1e8;
  background: #f7f7f9;
  border-radius: 4px;
  font-size: 1em;
  overflow-x: auto;
  line-height: 1.2em;
}
pre.code { color: #000; tab-size: 2; }
pre.code .info.file { color: #555; }
pre.code .val { color: #036A07; }
pre.code .tstring_content,
pre.code .heredoc_beg, pre.code .heredoc_end,
pre.code .qwords_beg, pre.code .qwords_end, pre.code .qwords_sep,
pre.code .words_beg, pre.code .words_end, pre.code .words_sep,
pre.code .qsymbols_beg, pre.code .qsymbols_end, pre.code .qsymbols_sep,
pre.code .symbols_beg, pre.code .symbols_end, pre.code .symbols_sep,
pre.code .tstring, pre.code .dstring { color: #036A07; }
pre.code .fid, pre.code .rubyid_new, pre.code .rubyid_to_s,
pre.code .rubyid_to_sym, pre.code .rubyid_to_f,
pre.code .dot + pre.code .id,
pre.code .rubyid_to_i pre.code .rubyid_each { color: #0085FF; }
pre.code .comment { color: #0066FF; }
pre.code .const, pre.code .constant { color: #585CF6; }
pre.code .label,
pre.code .symbol { color: #C5060B; }
pre.code .kw,
pre.code .rubyid_require,
pre.code .rubyid_extend,
pre.code .rubyid_include { color: #0000FF; }
pre.code .ivar { color: #318495; }
pre.code .gvar,
pre.code .rubyid_backref,
pre.code .rubyid_nth_ref { color: #6D79DE; }
pre.code .regexp, .dregexp { color: #036A07; }
pre.code a { border-bottom: 1px dotted #bbf; }
/* inline code */
*:not(pre) > code {
	padding: 1px 3px 1px 3px;
	border: 1px solid #E1E1E8;
	background: #F7F7F9;
	border-radius: 4px;
}

/* Color fix for links */
#content .summary_desc pre.code .id > .object_link a, /* identifier */
#content .docstring pre.code .id > .object_link a { color: #0085FF; }
#content .summary_desc pre.code .const > .object_link a, /* constant */
#content .docstring pre.code .const > .object_link a { color: #585CF6; }
yard-0.9.37/templates/default/fulldoc/html/frames.erb000066400000000000000000000011051466601756300225510ustar00rootroot00000000000000


  
	<%= options.title %>




yard-0.9.37/templates/default/fulldoc/html/full_list.erb000066400000000000000000000024301466601756300232730ustar00rootroot00000000000000
>
  
    
    
    <% stylesheets_full_list.each do |stylesheet| %>
      
    <% end %>

    <% javascripts_full_list.each do |javascript| %>
      
    <% end %>

    <%= @list_title %>
    
  
  
    
      
      
      
        
      <%= @list_title %>
      
        
      
          <% menu_lists.each do |list| %>
            
              <%= list[:title] %>
            
          <% end %>
        
      

        
      
      

      
        
        <%= erb "full_list_#{@list_type}" %>
      
      
    
      
  

yard-0.9.37/templates/default/fulldoc/html/full_list_class.erb000066400000000000000000000002511466601756300244570ustar00rootroot00000000000000
    • <%= link_object(Registry.root, Registry.root.title, nil, false) %>
      • 
<%= class_list %>
yard-0.9.37/templates/default/fulldoc/html/full_list_file.erb000066400000000000000000000004161466601756300242740ustar00rootroot00000000000000<% even_odd = 'odd'  %>
<% @items.each do |item| %>
  
    • 
    
      <%= link_file item %>
      
  
      • 
  <% even_odd = (even_odd == 'even' ? 'odd' : 'even') %>
<% end %>
yard-0.9.37/templates/default/fulldoc/html/full_list_method.erb000066400000000000000000000005251466601756300246360ustar00rootroot00000000000000<% even_odd = 'odd'  %>
<% @items.each do |item| %>
  
    • 
    
      
      <%= linkify item, h(item.name(true)) %>
      <%= item.namespace.title %>
    
      
  
      • 
  <% even_odd = (even_odd == 'even' ? 'odd' : 'even') %>
<% end %>
yard-0.9.37/templates/default/fulldoc/html/js/000077500000000000000000000000001466601756300212215ustar00rootroot00000000000000yard-0.9.37/templates/default/fulldoc/html/js/app.js000066400000000000000000000242461466601756300223470ustar00rootroot00000000000000(function () {
  var localStorage = {},
    sessionStorage = {};
  try {
    localStorage = window.localStorage;
  } catch (e) {}
  try {
    sessionStorage = window.sessionStorage;
  } catch (e) {}

  function createSourceLinks() {
    $(".method_details_list .source_code").before(
      "[View source]"
    );
    $(".toggleSource").toggle(
      function () {
        $(this).parent().nextAll(".source_code").slideDown(100);
        $(this).text("Hide source");
      },
      function () {
        $(this).parent().nextAll(".source_code").slideUp(100);
        $(this).text("View source");
      }
    );
  }

  function createDefineLinks() {
    var tHeight = 0;
    $(".defines").after(" more...");
    $(".toggleDefines").toggle(
      function () {
        tHeight = $(this).parent().prev().height();
        $(this).prev().css("display", "inline");
        $(this).parent().prev().height($(this).parent().height());
        $(this).text("(less)");
      },
      function () {
        $(this).prev().hide();
        $(this).parent().prev().height(tHeight);
        $(this).text("more...");
      }
    );
  }

  function createFullTreeLinks() {
    var tHeight = 0;
    $(".inheritanceTree").toggle(
      function () {
        tHeight = $(this).parent().prev().height();
        $(this).parent().toggleClass("showAll");
        $(this).text("(hide)");
        $(this).parent().prev().height($(this).parent().height());
      },
      function () {
        $(this).parent().toggleClass("showAll");
        $(this).parent().prev().height(tHeight);
        $(this).text("show all");
      }
    );
  }

  function searchFrameButtons() {
    $(".full_list_link").click(function () {
      toggleSearchFrame(this, $(this).attr("href"));
      return false;
    });
    window.addEventListener("message", function (e) {
      if (e.data === "navEscape") {
        $("#nav").slideUp(100);
        $("#search a").removeClass("active inactive");
        $(window).focus();
      }
    });

    $(window).resize(function () {
      if ($("#search:visible").length === 0) {
        $("#nav").removeAttr("style");
        $("#search a").removeClass("active inactive");
        $(window).focus();
      }
    });
  }

  function toggleSearchFrame(id, link) {
    var frame = $("#nav");
    $("#search a").removeClass("active").addClass("inactive");
    if (frame.attr("src") === link && frame.css("display") !== "none") {
      frame.slideUp(100);
      $("#search a").removeClass("active inactive");
    } else {
      $(id).addClass("active").removeClass("inactive");
      if (frame.attr("src") !== link) frame.attr("src", link);
      frame.slideDown(100);
    }
  }

  function linkSummaries() {
    $(".summary_signature").click(function () {
      document.location = $(this).find("a").attr("href");
    });
  }

  function summaryToggle() {
    $(".summary_toggle").click(function (e) {
      e.preventDefault();
      localStorage.summaryCollapsed = $(this).text();
      $(".summary_toggle").each(function () {
        $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
        var next = $(this).parent().parent().nextAll("ul.summary").first();
        if (next.hasClass("compact")) {
          next.toggle();
          next.nextAll("ul.summary").first().toggle();
        } else if (next.hasClass("summary")) {
          var list = $('
        ');
          list.html(next.html());
          list.find(".summary_desc, .note").remove();
          list.find("a").each(function () {
            $(this).html($(this).find("strong").html());
            $(this).parent().html($(this)[0].outerHTML);
          });
          next.before(list);
          next.toggle();
        }
      });
      return false;
    });
    if (localStorage.summaryCollapsed == "collapse") {
      $(".summary_toggle").first().click();
    } else {
      localStorage.summaryCollapsed = "expand";
    }
  }

  function constantSummaryToggle() {
    $(".constants_summary_toggle").click(function (e) {
      e.preventDefault();
      localStorage.summaryCollapsed = $(this).text();
      $(".constants_summary_toggle").each(function () {
        $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
        var next = $(this).parent().parent().nextAll("dl.constants").first();
        if (next.hasClass("compact")) {
          next.toggle();
          next.nextAll("dl.constants").first().toggle();
        } else if (next.hasClass("constants")) {
          var list = $('
        ');
          list.html(next.html());
          list.find("dt").each(function () {
            $(this).addClass("summary_signature");
            $(this).text($(this).text().split("=")[0]);
            if ($(this).has(".deprecated").length) {
              $(this).addClass("deprecated");
            }
          });
          // Add the value of the constant as "Tooltip" to the summary object
          list.find("pre.code").each(function () {
            console.log($(this).parent());
            var dt_element = $(this).parent().prev();
            var tooltip = $(this).text();
            if (dt_element.hasClass("deprecated")) {
              tooltip = "Deprecated. " + tooltip;
            }
            dt_element.attr("title", tooltip);
          });
          list.find(".docstring, .tags, dd").remove();
          next.before(list);
          next.toggle();
        }
      });
      return false;
    });
    if (localStorage.summaryCollapsed == "collapse") {
      $(".constants_summary_toggle").first().click();
    } else {
      localStorage.summaryCollapsed = "expand";
    }
  }

  function generateTOC() {
    if ($("#filecontents").length === 0) return;
    var _toc = $('
          ');
    var show = false;
    var toc = _toc;
    var counter = 0;
    var tags = ["h2", "h3", "h4", "h5", "h6"];
    var i;
    var curli;
    if ($("#filecontents h1").length > 1) tags.unshift("h1");
    for (i = 0; i < tags.length; i++) {
      tags[i] = "#filecontents " + tags[i];
    }
    var lastTag = parseInt(tags[0][1], 10);
    $(tags.join(", ")).each(function () {
      if ($(this).parents(".method_details .docstring").length != 0) return;
      if (this.id == "filecontents") return;
      show = true;
      var thisTag = parseInt(this.tagName[1], 10);
      if (this.id.length === 0) {
        var proposedId = $(this).attr("toc-id");
        if (typeof proposedId != "undefined") this.id = proposedId;
        else {
          var proposedId = $(this)
            .text()
            .replace(/[^a-z0-9-]/gi, "_");
          if ($("#" + proposedId).length > 0) {
            proposedId += counter;
            counter++;
          }
          this.id = proposedId;
        }
      }
      if (thisTag > lastTag) {
        for (i = 0; i < thisTag - lastTag; i++) {
          if (typeof curli == "undefined") {
            curli = $("
        1. ");
            toc.append(curli);
          }
          toc = $("
            ");
          curli.append(toc);
          curli = undefined;
        }
      }
      if (thisTag < lastTag) {
        for (i = 0; i < lastTag - thisTag; i++) {
          toc = toc.parent();
          toc = toc.parent();
        }
      }
      var title = $(this).attr("toc-title");
      if (typeof title == "undefined") title = $(this).text();
      curli = $('
          1. ' + title + "
            2. ");
      toc.append(curli);
      lastTag = thisTag;
    });
    if (!show) return;
    html =
      '';
    $("#content").prepend(html);
    $("#toc").append(_toc);
    $("#toc .hide_toc").toggle(
      function () {
        $("#toc .top").slideUp("fast");
        $("#toc").toggleClass("hidden");
        $("#toc .title small").toggle();
      },
      function () {
        $("#toc .top").slideDown("fast");
        $("#toc").toggleClass("hidden");
        $("#toc .title small").toggle();
      }
    );
  }

  function navResizeFn(e) {
    if (e.which !== 1) {
      navResizeFnStop();
      return;
    }

    sessionStorage.navWidth = e.pageX.toString();
    $(".nav_wrap").css("width", e.pageX);
    $(".nav_wrap").css("-ms-flex", "inherit");
  }

  function navResizeFnStop() {
    $(window).unbind("mousemove", navResizeFn);
    window.removeEventListener("message", navMessageFn, false);
  }

  function navMessageFn(e) {
    if (e.data.action === "mousemove") navResizeFn(e.data.event);
    if (e.data.action === "mouseup") navResizeFnStop();
  }

  function navResizer() {
    $("#resizer").mousedown(function (e) {
      e.preventDefault();
      $(window).mousemove(navResizeFn);
      window.addEventListener("message", navMessageFn, false);
    });
    $(window).mouseup(navResizeFnStop);

    if (sessionStorage.navWidth) {
      navResizeFn({ which: 1, pageX: parseInt(sessionStorage.navWidth, 10) });
    }
  }

  function navExpander() {
    if (typeof pathId === "undefined") return;
    var done = false,
      timer = setTimeout(postMessage, 500);
    function postMessage() {
      if (done) return;
      clearTimeout(timer);
      var opts = { action: "expand", path: pathId };
      document.getElementById("nav").contentWindow.postMessage(opts, "*");
      done = true;
    }

    window.addEventListener(
      "message",
      function (event) {
        if (event.data === "navReady") postMessage();
        return false;
      },
      false
    );
  }

  function mainFocus() {
    var hash = window.location.hash;
    if (hash !== "" && $(hash)[0]) {
      $(hash)[0].scrollIntoView();
    }

    setTimeout(function () {
      $("#main").focus();
    }, 10);
  }

  function navigationChange() {
    // This works around the broken anchor navigation with the YARD template.
    window.onpopstate = function () {
      var hash = window.location.hash;
      if (hash !== "" && $(hash)[0]) {
        $(hash)[0].scrollIntoView();
      }
    };
  }

  $(document).ready(function () {
    navResizer();
    navExpander();
    createSourceLinks();
    createDefineLinks();
    createFullTreeLinks();
    searchFrameButtons();
    linkSummaries();
    summaryToggle();
    constantSummaryToggle();
    generateTOC();
    mainFocus();
    navigationChange();
  });
})();
yard-0.9.37/templates/default/fulldoc/html/js/full_list.js000066400000000000000000000147021466601756300235600ustar00rootroot00000000000000(function() {

var $clicked = $(null);
var searchTimeout = null;
var searchCache = [];
var caseSensitiveMatch = false;
var ignoreKeyCodeMin = 8;
var ignoreKeyCodeMax = 46;
var commandKey = 91;

RegExp.escape = function(text) {
    return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
}

function escapeShortcut() {
  $(document).keydown(function(evt) {
    if (evt.which == 27) {
      window.parent.postMessage('navEscape', '*');
    }
  });
}

function navResizer() {
  $(window).mousemove(function(e) {
    window.parent.postMessage({
      action: 'mousemove', event: {pageX: e.pageX, which: e.which}
    }, '*');
  }).mouseup(function(e) {
    window.parent.postMessage({action: 'mouseup'}, '*');
  });
  window.parent.postMessage("navReady", "*");
}

function clearSearchTimeout() {
  clearTimeout(searchTimeout);
  searchTimeout = null;
}

function enableLinks() {
  // load the target page in the parent window
  $('#full_list li').on('click', function(evt) {
    $('#full_list li').removeClass('clicked');
    $clicked = $(this);
    $clicked.addClass('clicked');
    evt.stopPropagation();

    if (evt.target.tagName === 'A') return true;

    var elem = $clicked.find('> .item .object_link a')[0];
    var e = evt.originalEvent;
    var newEvent = new MouseEvent(evt.originalEvent.type);
    newEvent.initMouseEvent(e.type, e.canBubble, e.cancelable, e.view, e.detail, e.screenX, e.screenY, e.clientX, e.clientY, e.ctrlKey, e.altKey, e.shiftKey, e.metaKey, e.button, e.relatedTarget);
    elem.dispatchEvent(newEvent);
    evt.preventDefault();
    return false;
  });
}

function enableToggles() {
  // show/hide nested classes on toggle click
  $('#full_list a.toggle').on('click', function(evt) {
    evt.stopPropagation();
    evt.preventDefault();
    $(this).parent().parent().toggleClass('collapsed');
    $(this).attr('aria-expanded', function (i, attr) {
        return attr == 'true' ? 'false' : 'true'
    });
    highlight();
  });

  // navigation of nested classes using keyboard
  $('#full_list a.toggle').on('keypress',function(evt) {
    // enter key is pressed
    if (evt.which == 13) {
      evt.stopPropagation();
      evt.preventDefault();
      $(this).parent().parent().toggleClass('collapsed');
      $(this).attr('aria-expanded', function (i, attr) {
          return attr == 'true' ? 'false' : 'true'
      });
      highlight();
    }
  });
}

function populateSearchCache() {
  $('#full_list li .item').each(function() {
    var $node = $(this);
    var $link = $node.find('.object_link a');
    if ($link.length > 0) {
      searchCache.push({
        node: $node,
        link: $link,
        name: $link.text(),
        fullName: $link.attr('title').split(' ')[0]
      });
    }
  });
}

function enableSearch() {
  $('#search input').keyup(function(event) {
    if (ignoredKeyPress(event)) return;
    if (this.value === "") {
      clearSearch();
    } else {
      performSearch(this.value);
    }
  });

  $('#full_list').after("");
}

function ignoredKeyPress(event) {
  if (
    (event.keyCode > ignoreKeyCodeMin && event.keyCode < ignoreKeyCodeMax) ||
    (event.keyCode == commandKey)
  ) {
    return true;
  } else {
    return false;
  }
}

function clearSearch() {
  clearSearchTimeout();
  $('#full_list .found').removeClass('found').each(function() {
    var $link = $(this).find('.object_link a');
    $link.text($link.text());
  });
  $('#full_list, #content').removeClass('insearch');
  $clicked.parents().removeClass('collapsed');
  highlight();
}

function performSearch(searchString) {
  clearSearchTimeout();
  $('#full_list, #content').addClass('insearch');
  $('#noresults').text('').hide();
  partialSearch(searchString, 0);
}

function partialSearch(searchString, offset) {
  var lastRowClass = '';
  var i = null;
  for (i = offset; i < Math.min(offset + 50, searchCache.length); i++) {
    var item = searchCache[i];
    var searchName = (searchString.indexOf('::') != -1 ? item.fullName : item.name);
    var matchString = buildMatchString(searchString);
    var matchRegexp = new RegExp(matchString, caseSensitiveMatch ? "" : "i");
    if (searchName.match(matchRegexp) == null) {
      item.node.removeClass('found');
      item.link.text(item.link.text());
    }
    else {
      item.node.addClass('found');
      item.node.removeClass(lastRowClass).addClass(lastRowClass == 'r1' ? 'r2' : 'r1');
      lastRowClass = item.node.hasClass('r1') ? 'r1' : 'r2';
      item.link.html(item.name.replace(matchRegexp, "$&"));
    }
  }
  if(i == searchCache.length) {
    searchDone();
  } else {
    searchTimeout = setTimeout(function() {
      partialSearch(searchString, i);
    }, 0);
  }
}

function searchDone() {
  searchTimeout = null;
  highlight();
  var found = $('#full_list li:visible').size();
  if (found === 0) {
    $('#noresults').text('No results were found.');
  } else {
    // This is read out to screen readers
    $('#noresults').text('There are ' + found + ' results.');
  }
  $('#noresults').show();
  $('#content').removeClass('insearch');
}

function buildMatchString(searchString, event) {
  caseSensitiveMatch = searchString.match(/[A-Z]/) != null;
  var regexSearchString = RegExp.escape(searchString);
  if (caseSensitiveMatch) {
    regexSearchString += "|" +
      $.map(searchString.split(''), function(e) { return RegExp.escape(e); }).
      join('.+?');
  }
  return regexSearchString;
}

function highlight() {
  $('#full_list li:visible').each(function(n) {
    $(this).removeClass('even odd').addClass(n % 2 == 0 ? 'odd' : 'even');
  });
}

/**
 * Expands the tree to the target element and its immediate
 * children.
 */
function expandTo(path) {
  var $target = $(document.getElementById('object_' + path));
  $target.addClass('clicked');
  $target.removeClass('collapsed');
  $target.parentsUntil('#full_list', 'li').removeClass('collapsed');

  $target.find('a.toggle').attr('aria-expanded', 'true')
  $target.parentsUntil('#full_list', 'li').each(function(i, el) {
    $(el).find('> div > a.toggle').attr('aria-expanded', 'true');
  });

  if($target[0]) {
    window.scrollTo(window.scrollX, $target.offset().top - 250);
    highlight();
  }
}

function windowEvents(event) {
  var msg = event.data;
  if (msg.action === "expand") {
    expandTo(msg.path);
  }
  return false;
}

window.addEventListener("message", windowEvents, false);

$(document).ready(function() {
  escapeShortcut();
  navResizer();
  enableLinks();
  enableToggles();
  populateSearchCache();
  enableSearch();
});

})();
yard-0.9.37/templates/default/fulldoc/html/js/jquery.js000066400000000000000000002672541466601756300231160ustar00rootroot00000000000000/*! jQuery v1.7.1 jquery.com | jquery.org/license */
(function(a,b){function cy(a){return f.isWindow(a)?a:a.nodeType===9?a.defaultView||a.parentWindow:!1}function cv(a){if(!ck[a]){var b=c.body,d=f("<"+a+">").appendTo(b),e=d.css("display");d.remove();if(e==="none"||e===""){cl||(cl=c.createElement("iframe"),cl.frameBorder=cl.width=cl.height=0),b.appendChild(cl);if(!cm||!cl.createElement)cm=(cl.contentWindow||cl.contentDocument).document,cm.write((c.compatMode==="CSS1Compat"?"":"")+""),cm.close();d=cm.createElement(a),cm.body.appendChild(d),e=f.css(d,"display"),b.removeChild(cl)}ck[a]=e}return ck[a]}function cu(a,b){var c={};f.each(cq.concat.apply([],cq.slice(0,b)),function(){c[this]=a});return c}function ct(){cr=b}function cs(){setTimeout(ct,0);return cr=f.now()}function cj(){try{return new a.ActiveXObject("Microsoft.XMLHTTP")}catch(b){}}function ci(){try{return new a.XMLHttpRequest}catch(b){}}function cc(a,c){a.dataFilter&&(c=a.dataFilter(c,a.dataType));var d=a.dataTypes,e={},g,h,i=d.length,j,k=d[0],l,m,n,o,p;for(g=1;g0){if(c!=="border")for(;g=0===c})}function S(a){return!a||!a.parentNode||a.parentNode.nodeType===11}function K(){return!0}function J(){return!1}function n(a,b,c){var d=b+"defer",e=b+"queue",g=b+"mark",h=f._data(a,d);h&&(c==="queue"||!f._data(a,e))&&(c==="mark"||!f._data(a,g))&&setTimeout(function(){!f._data(a,e)&&!f._data(a,g)&&(f.removeData(a,d,!0),h.fire())},0)}function m(a){for(var b in a){if(b==="data"&&f.isEmptyObject(a[b]))continue;if(b!=="toJSON")return!1}return!0}function l(a,c,d){if(d===b&&a.nodeType===1){var e="data-"+c.replace(k,"-$1").toLowerCase();d=a.getAttribute(e);if(typeof d=="string"){try{d=d==="true"?!0:d==="false"?!1:d==="null"?null:f.isNumeric(d)?parseFloat(d):j.test(d)?f.parseJSON(d):d}catch(g){}f.data(a,c,d)}else d=b}return d}function h(a){var b=g[a]={},c,d;a=a.split(/\s+/);for(c=0,d=a.length;c)[^>]*$|#([\w\-]*)$)/,j=/\S/,k=/^\s+/,l=/\s+$/,m=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,n=/^[\],:{}\s]*$/,o=/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,p=/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,q=/(?:^|:|,)(?:\s*\[)+/g,r=/(webkit)[ \/]([\w.]+)/,s=/(opera)(?:.*version)?[ \/]([\w.]+)/,t=/(msie) ([\w.]+)/,u=/(mozilla)(?:.*? rv:([\w.]+))?/,v=/-([a-z]|[0-9])/ig,w=/^-ms-/,x=function(a,b){return(b+"").toUpperCase()},y=d.userAgent,z,A,B,C=Object.prototype.toString,D=Object.prototype.hasOwnProperty,E=Array.prototype.push,F=Array.prototype.slice,G=String.prototype.trim,H=Array.prototype.indexOf,I={};e.fn=e.prototype={constructor:e,init:function(a,d,f){var g,h,j,k;if(!a)return this;if(a.nodeType){this.context=this[0]=a,this.length=1;return this}if(a==="body"&&!d&&c.body){this.context=c,this[0]=c.body,this.selector=a,this.length=1;return this}if(typeof a=="string"){a.charAt(0)!=="<"||a.charAt(a.length-1)!==">"||a.length<3?g=i.exec(a):g=[null,a,null];if(g&&(g[1]||!d)){if(g[1]){d=d instanceof e?d[0]:d,k=d?d.ownerDocument||d:c,j=m.exec(a),j?e.isPlainObject(d)?(a=[c.createElement(j[1])],e.fn.attr.call(a,d,!0)):a=[k.createElement(j[1])]:(j=e.buildFragment([g[1]],[k]),a=(j.cacheable?e.clone(j.fragment):j.fragment).childNodes);return e.merge(this,a)}h=c.getElementById(g[2]);if(h&&h.parentNode){if(h.id!==g[2])return f.find(a);this.length=1,this[0]=h}this.context=c,this.selector=a;return this}return!d||d.jquery?(d||f).find(a):this.constructor(d).find(a)}if(e.isFunction(a))return f.ready(a);a.selector!==b&&(this.selector=a.selector,this.context=a.context);return e.makeArray(a,this)},selector:"",jquery:"1.7.1",length:0,size:function(){return this.length},toArray:function(){return F.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this[this.length+a]:this[a]},pushStack:function(a,b,c){var d=this.constructor();e.isArray(a)?E.apply(d,a):e.merge(d,a),d.prevObject=this,d.context=this.context,b==="find"?d.selector=this.selector+(this.selector?" ":"")+c:b&&(d.selector=this.selector+"."+b+"("+c+")");return d},each:function(a,b){return e.each(this,a,b)},ready:function(a){e.bindReady(),A.add(a);return this},eq:function(a){a=+a;return a===-1?this.slice(a):this.slice(a,a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(F.apply(this,arguments),"slice",F.call(arguments).join(","))},map:function(a){return this.pushStack(e.map(this,function(b,c){return a.call(b,c,b)}))},end:function(){return this.prevObject||this.constructor(null)},push:E,sort:[].sort,splice:[].splice},e.fn.init.prototype=e.fn,e.extend=e.fn.extend=function(){var a,c,d,f,g,h,i=arguments[0]||{},j=1,k=arguments.length,l=!1;typeof i=="boolean"&&(l=i,i=arguments[1]||{},j=2),typeof i!="object"&&!e.isFunction(i)&&(i={}),k===j&&(i=this,--j);for(;j0)return;A.fireWith(c,[e]),e.fn.trigger&&e(c).trigger("ready").off("ready")}},bindReady:function(){if(!A){A=e.Callbacks("once memory");if(c.readyState==="complete")return setTimeout(e.ready,1);if(c.addEventListener)c.addEventListener("DOMContentLoaded",B,!1),a.addEventListener("load",e.ready,!1);else if(c.attachEvent){c.attachEvent("onreadystatechange",B),a.attachEvent("onload",e.ready);var b=!1;try{b=a.frameElement==null}catch(d){}c.documentElement.doScroll&&b&&J()}}},isFunction:function(a){return e.type(a)==="function"},isArray:Array.isArray||function(a){return e.type(a)==="array"},isWindow:function(a){return a&&typeof a=="object"&&"setInterval"in a},isNumeric:function(a){return!isNaN(parseFloat(a))&&isFinite(a)},type:function(a){return a==null?String(a):I[C.call(a)]||"object"},isPlainObject:function(a){if(!a||e.type(a)!=="object"||a.nodeType||e.isWindow(a))return!1;try{if(a.constructor&&!D.call(a,"constructor")&&!D.call(a.constructor.prototype,"isPrototypeOf"))return!1}catch(c){return!1}var d;for(d in a);return d===b||D.call(a,d)},isEmptyObject:function(a){for(var b in a)return!1;return!0},error:function(a){throw new Error(a)},parseJSON:function(b){if(typeof b!="string"||!b)return null;b=e.trim(b);if(a.JSON&&a.JSON.parse)return a.JSON.parse(b);if(n.test(b.replace(o,"@").replace(p,"]").replace(q,"")))return(new Function("return "+b))();e.error("Invalid JSON: "+b)},parseXML:function(c){var d,f;try{a.DOMParser?(f=new DOMParser,d=f.parseFromString(c,"text/xml")):(d=new ActiveXObject("Microsoft.XMLDOM"),d.async="false",d.loadXML(c))}catch(g){d=b}(!d||!d.documentElement||d.getElementsByTagName("parsererror").length)&&e.error("Invalid XML: "+c);return d},noop:function(){},globalEval:function(b){b&&j.test(b)&&(a.execScript||function(b){a.eval.call(a,b)})(b)},camelCase:function(a){return a.replace(w,"ms-").replace(v,x)},nodeName:function(a,b){return a.nodeName&&a.nodeName.toUpperCase()===b.toUpperCase()},each:function(a,c,d){var f,g=0,h=a.length,i=h===b||e.isFunction(a);if(d){if(i){for(f in a)if(c.apply(a[f],d)===!1)break}else for(;g0&&a[0]&&a[j-1]||j===0||e.isArray(a));if(k)for(;i1?i.call(arguments,0):b,j.notifyWith(k,e)}}function l(a){return function(c){b[a]=arguments.length>1?i.call(arguments,0):c,--g||j.resolveWith(j,b)}}var b=i.call(arguments,0),c=0,d=b.length,e=Array(d),g=d,h=d,j=d<=1&&a&&f.isFunction(a.promise)?a:f.Deferred(),k=j.promise();if(d>1){for(;c
      a",d=q.getElementsByTagName("*"),e=q.getElementsByTagName("a")[0];if(!d||!d.length||!e)return{};g=c.createElement("select"),h=g.appendChild(c.createElement("option")),i=q.getElementsByTagName("input")[0],b={leadingWhitespace:q.firstChild.nodeType===3,tbody:!q.getElementsByTagName("tbody").length,htmlSerialize:!!q.getElementsByTagName("link").length,style:/top/.test(e.getAttribute("style")),hrefNormalized:e.getAttribute("href")==="/a",opacity:/^0.55/.test(e.style.opacity),cssFloat:!!e.style.cssFloat,checkOn:i.value==="on",optSelected:h.selected,getSetAttribute:q.className!=="t",enctype:!!c.createElement("form").enctype,html5Clone:c.createElement("nav").cloneNode(!0).outerHTML!=="<:nav>",submitBubbles:!0,changeBubbles:!0,focusinBubbles:!1,deleteExpando:!0,noCloneEvent:!0,inlineBlockNeedsLayout:!1,shrinkWrapBlocks:!1,reliableMarginRight:!0},i.checked=!0,b.noCloneChecked=i.cloneNode(!0).checked,g.disabled=!0,b.optDisabled=!h.disabled;try{delete q.test}catch(s){b.deleteExpando=!1}!q.addEventListener&&q.attachEvent&&q.fireEvent&&(q.attachEvent("onclick",function(){b.noCloneEvent=!1}),q.cloneNode(!0).fireEvent("onclick")),i=c.createElement("input"),i.value="t",i.setAttribute("type","radio"),b.radioValue=i.value==="t",i.setAttribute("checked","checked"),q.appendChild(i),k=c.createDocumentFragment(),k.appendChild(q.lastChild),b.checkClone=k.cloneNode(!0).cloneNode(!0).lastChild.checked,b.appendChecked=i.checked,k.removeChild(i),k.appendChild(q),q.innerHTML="",a.getComputedStyle&&(j=c.createElement("div"),j.style.width="0",j.style.marginRight="0",q.style.width="2px",q.appendChild(j),b.reliableMarginRight=(parseInt((a.getComputedStyle(j,null)||{marginRight:0}).marginRight,10)||0)===0);if(q.attachEvent)for(o in{submit:1,change:1,focusin:1})n="on"+o,p=n in q,p||(q.setAttribute(n,"return;"),p=typeof q[n]=="function"),b[o+"Bubbles"]=p;k.removeChild(q),k=g=h=j=q=i=null,f(function(){var a,d,e,g,h,i,j,k,m,n,o,r=c.getElementsByTagName("body")[0];!r||(j=1,k="position:absolute;top:0;left:0;width:1px;height:1px;margin:0;",m="visibility:hidden;border:0;",n="style='"+k+"border:5px solid #000;padding:0;'",o="
      "+""+"
      ",a=c.createElement("div"),a.style.cssText=m+"width:0;height:0;position:static;top:0;margin-top:"+j+"px",r.insertBefore(a,r.firstChild),q=c.createElement("div"),a.appendChild(q),q.innerHTML="
      t
      ",l=q.getElementsByTagName("td"),p=l[0].offsetHeight===0,l[0].style.display="",l[1].style.display="none",b.reliableHiddenOffsets=p&&l[0].offsetHeight===0,q.innerHTML="",q.style.width=q.style.paddingLeft="1px",f.boxModel=b.boxModel=q.offsetWidth===2,typeof q.style.zoom!="undefined"&&(q.style.display="inline",q.style.zoom=1,b.inlineBlockNeedsLayout=q.offsetWidth===2,q.style.display="",q.innerHTML="
      ",b.shrinkWrapBlocks=q.offsetWidth!==2),q.style.cssText=k+m,q.innerHTML=o,d=q.firstChild,e=d.firstChild,h=d.nextSibling.firstChild.firstChild,i={doesNotAddBorder:e.offsetTop!==5,doesAddBorderForTableAndCells:h.offsetTop===5},e.style.position="fixed",e.style.top="20px",i.fixedPosition=e.offsetTop===20||e.offsetTop===15,e.style.position=e.style.top="",d.style.overflow="hidden",d.style.position="relative",i.subtractsBorderForOverflowNotVisible=e.offsetTop===-5,i.doesNotIncludeMarginInBodyOffset=r.offsetTop!==j,r.removeChild(a),q=a=null,f.extend(b,i))});return b}();var j=/^(?:\{.*\}|\[.*\])$/,k=/([A-Z])/g;f.extend({cache:{},uuid:0,expando:"jQuery"+(f.fn.jquery+Math.random()).replace(/\D/g,""),noData:{embed:!0,object:"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",applet:!0},hasData:function(a){a=a.nodeType?f.cache[a[f.expando]]:a[f.expando];return!!a&&!m(a)},data:function(a,c,d,e){if(!!f.acceptData(a)){var g,h,i,j=f.expando,k=typeof c=="string",l=a.nodeType,m=l?f.cache:a,n=l?a[j]:a[j]&&j,o=c==="events";if((!n||!m[n]||!o&&!e&&!m[n].data)&&k&&d===b)return;n||(l?a[j]=n=++f.uuid:n=j),m[n]||(m[n]={},l||(m[n].toJSON=f.noop));if(typeof c=="object"||typeof c=="function")e?m[n]=f.extend(m[n],c):m[n].data=f.extend(m[n].data,c);g=h=m[n],e||(h.data||(h.data={}),h=h.data),d!==b&&(h[f.camelCase(c)]=d);if(o&&!h[c])return g.events;k?(i=h[c],i==null&&(i=h[f.camelCase(c)])):i=h;return i}},removeData:function(a,b,c){if(!!f.acceptData(a)){var d,e,g,h=f.expando,i=a.nodeType,j=i?f.cache:a,k=i?a[h]:h;if(!j[k])return;if(b){d=c?j[k]:j[k].data;if(d){f.isArray(b)||(b in d?b=[b]:(b=f.camelCase(b),b in d?b=[b]:b=b.split(" ")));for(e=0,g=b.length;e-1)return!0;return!1},val:function(a){var c,d,e,g=this[0];{if(!!arguments.length){e=f.isFunction(a);return this.each(function(d){var g=f(this),h;if(this.nodeType===1){e?h=a.call(this,d,g.val()):h=a,h==null?h="":typeof h=="number"?h+="":f.isArray(h)&&(h=f.map(h,function(a){return a==null?"":a+""})),c=f.valHooks[this.nodeName.toLowerCase()]||f.valHooks[this.type];if(!c||!("set"in c)||c.set(this,h,"value")===b)this.value=h}})}if(g){c=f.valHooks[g.nodeName.toLowerCase()]||f.valHooks[g.type];if(c&&"get"in c&&(d=c.get(g,"value"))!==b)return d;d=g.value;return typeof d=="string"?d.replace(q,""):d==null?"":d}}}}),f.extend({valHooks:{option:{get:function(a){var b=a.attributes.value;return!b||b.specified?a.value:a.text}},select:{get:function(a){var b,c,d,e,g=a.selectedIndex,h=[],i=a.options,j=a.type==="select-one";if(g<0)return null;c=j?g:0,d=j?g+1:i.length;for(;c=0}),c.length||(a.selectedIndex=-1);return c}}},attrFn:{val:!0,css:!0,html:!0,text:!0,data:!0,width:!0,height:!0,offset:!0},attr:function(a,c,d,e){var g,h,i,j=a.nodeType;if(!!a&&j!==3&&j!==8&&j!==2){if(e&&c in f.attrFn)return f(a)[c](d);if(typeof a.getAttribute=="undefined")return f.prop(a,c,d);i=j!==1||!f.isXMLDoc(a),i&&(c=c.toLowerCase(),h=f.attrHooks[c]||(u.test(c)?x:w));if(d!==b){if(d===null){f.removeAttr(a,c);return}if(h&&"set"in h&&i&&(g=h.set(a,d,c))!==b)return g;a.setAttribute(c,""+d);return d}if(h&&"get"in h&&i&&(g=h.get(a,c))!==null)return g;g=a.getAttribute(c);return g===null?b:g}},removeAttr:function(a,b){var c,d,e,g,h=0;if(b&&a.nodeType===1){d=b.toLowerCase().split(p),g=d.length;for(;h=0}})});var z=/^(?:textarea|input|select)$/i,A=/^([^\.]*)?(?:\.(.+))?$/,B=/\bhover(\.\S+)?\b/,C=/^key/,D=/^(?:mouse|contextmenu)|click/,E=/^(?:focusinfocus|focusoutblur)$/,F=/^(\w*)(?:#([\w\-]+))?(?:\.([\w\-]+))?$/,G=function(a){var b=F.exec(a);b&&(b[1]=(b[1]||"").toLowerCase(),b[3]=b[3]&&new RegExp("(?:^|\\s)"+b[3]+"(?:\\s|$)"));return b},H=function(a,b){var c=a.attributes||{};return(!b[1]||a.nodeName.toLowerCase()===b[1])&&(!b[2]||(c.id||{}).value===b[2])&&(!b[3]||b[3].test((c["class"]||{}).value))},I=function(a){return f.event.special.hover?a:a.replace(B,"mouseenter$1 mouseleave$1")};
f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3||a.nodeType===8||!c||!d||!(h=f._data(a)))){d.handler&&(p=d,d=p.handler),d.guid||(d.guid=f.guid++),j=h.events,j||(h.events=j={}),i=h.handle,i||(h.handle=i=function(a){return typeof f!="undefined"&&(!a||f.event.triggered!==a.type)?f.event.dispatch.apply(i.elem,arguments):b},i.elem=a),c=f.trim(I(c)).split(" ");for(k=0;k=0&&(h=h.slice(0,-1),k=!0),h.indexOf(".")>=0&&(i=h.split("."),h=i.shift(),i.sort());if((!e||f.event.customEvent[h])&&!f.event.global[h])return;c=typeof c=="object"?c[f.expando]?c:new f.Event(h,c):new f.Event(h),c.type=h,c.isTrigger=!0,c.exclusive=k,c.namespace=i.join("."),c.namespace_re=c.namespace?new RegExp("(^|\\.)"+i.join("\\.(?:.*\\.)?")+"(\\.|$)"):null,o=h.indexOf(":")<0?"on"+h:"";if(!e){j=f.cache;for(l in j)j[l].events&&j[l].events[h]&&f.event.trigger(c,d,j[l].handle.elem,!0);return}c.result=b,c.target||(c.target=e),d=d!=null?f.makeArray(d):[],d.unshift(c),p=f.event.special[h]||{};if(p.trigger&&p.trigger.apply(e,d)===!1)return;r=[[e,p.bindType||h]];if(!g&&!p.noBubble&&!f.isWindow(e)){s=p.delegateType||h,m=E.test(s+h)?e:e.parentNode,n=null;for(;m;m=m.parentNode)r.push([m,s]),n=m;n&&n===e.ownerDocument&&r.push([n.defaultView||n.parentWindow||a,s])}for(l=0;le&&i.push({elem:this,matches:d.slice(e)});for(j=0;j0?this.on(b,null,a,c):this.trigger(b)},f.attrFn&&(f.attrFn[b]=!0),C.test(b)&&(f.event.fixHooks[b]=f.event.keyHooks),D.test(b)&&(f.event.fixHooks[b]=f.event.mouseHooks)}),function(){function x(a,b,c,e,f,g){for(var h=0,i=e.length;h0){k=j;break}}j=j[a]}e[h]=k}}}function w(a,b,c,e,f,g){for(var h=0,i=e.length;h+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,d="sizcache"+(Math.random()+"").replace(".",""),e=0,g=Object.prototype.toString,h=!1,i=!0,j=/\\/g,k=/\r\n/g,l=/\W/;[0,0].sort(function(){i=!1;return 0});var m=function(b,d,e,f){e=e||[],d=d||c;var h=d;if(d.nodeType!==1&&d.nodeType!==9)return[];if(!b||typeof b!="string")return e;var i,j,k,l,n,q,r,t,u=!0,v=m.isXML(d),w=[],x=b;do{a.exec(""),i=a.exec(x);if(i){x=i[3],w.push(i[1]);if(i[2]){l=i[3];break}}}while(i);if(w.length>1&&p.exec(b))if(w.length===2&&o.relative[w[0]])j=y(w[0]+w[1],d,f);else{j=o.relative[w[0]]?[d]:m(w.shift(),d);while(w.length)b=w.shift(),o.relative[b]&&(b+=w.shift()),j=y(b,j,f)}else{!f&&w.length>1&&d.nodeType===9&&!v&&o.match.ID.test(w[0])&&!o.match.ID.test(w[w.length-1])&&(n=m.find(w.shift(),d,v),d=n.expr?m.filter(n.expr,n.set)[0]:n.set[0]);if(d){n=f?{expr:w.pop(),set:s(f)}:m.find(w.pop(),w.length===1&&(w[0]==="~"||w[0]==="+")&&d.parentNode?d.parentNode:d,v),j=n.expr?m.filter(n.expr,n.set):n.set,w.length>0?k=s(j):u=!1;while(w.length)q=w.pop(),r=q,o.relative[q]?r=w.pop():q="",r==null&&(r=d),o.relative[q](k,r,v)}else k=w=[]}k||(k=j),k||m.error(q||b);if(g.call(k)==="[object Array]")if(!u)e.push.apply(e,k);else if(d&&d.nodeType===1)for(t=0;k[t]!=null;t++)k[t]&&(k[t]===!0||k[t].nodeType===1&&m.contains(d,k[t]))&&e.push(j[t]);else for(t=0;k[t]!=null;t++)k[t]&&k[t].nodeType===1&&e.push(j[t]);else s(k,e);l&&(m(l,h,e,f),m.uniqueSort(e));return e};m.uniqueSort=function(a){if(u){h=i,a.sort(u);if(h)for(var b=1;b0},m.find=function(a,b,c){var d,e,f,g,h,i;if(!a)return[];for(e=0,f=o.order.length;e":function(a,b){var c,d=typeof b=="string",e=0,f=a.length;if(d&&!l.test(b)){b=b.toLowerCase();for(;e=0)?c||d.push(h):c&&(b[g]=!1));return!1},ID:function(a){return a[1].replace(j,"")},TAG:function(a,b){return a[1].replace(j,"").toLowerCase()},CHILD:function(a){if(a[1]==="nth"){a[2]||m.error(a[0]),a[2]=a[2].replace(/^\+|\s*/g,"");var b=/(-?)(\d*)(?:n([+\-]?\d*))?/.exec(a[2]==="even"&&"2n"||a[2]==="odd"&&"2n+1"||!/\D/.test(a[2])&&"0n+"+a[2]||a[2]);a[2]=b[1]+(b[2]||1)-0,a[3]=b[3]-0}else a[2]&&m.error(a[0]);a[0]=e++;return a},ATTR:function(a,b,c,d,e,f){var g=a[1]=a[1].replace(j,"");!f&&o.attrMap[g]&&(a[1]=o.attrMap[g]),a[4]=(a[4]||a[5]||"").replace(j,""),a[2]==="~="&&(a[4]=" "+a[4]+" ");return a},PSEUDO:function(b,c,d,e,f){if(b[1]==="not")if((a.exec(b[3])||"").length>1||/^\w/.test(b[3]))b[3]=m(b[3],null,null,c);else{var g=m.filter(b[3],c,d,!0^f);d||e.push.apply(e,g);return!1}else if(o.match.POS.test(b[0])||o.match.CHILD.test(b[0]))return!0;return b},POS:function(a){a.unshift(!0);return a}},filters:{enabled:function(a){return a.disabled===!1&&a.type!=="hidden"},disabled:function(a){return a.disabled===!0},checked:function(a){return a.checked===!0},selected:function(a){a.parentNode&&a.parentNode.selectedIndex;return a.selected===!0},parent:function(a){return!!a.firstChild},empty:function(a){return!a.firstChild},has:function(a,b,c){return!!m(c[3],a).length},header:function(a){return/h\d/i.test(a.nodeName)},text:function(a){var b=a.getAttribute("type"),c=a.type;return a.nodeName.toLowerCase()==="input"&&"text"===c&&(b===c||b===null)},radio:function(a){return a.nodeName.toLowerCase()==="input"&&"radio"===a.type},checkbox:function(a){return a.nodeName.toLowerCase()==="input"&&"checkbox"===a.type},file:function(a){return a.nodeName.toLowerCase()==="input"&&"file"===a.type},password:function(a){return a.nodeName.toLowerCase()==="input"&&"password"===a.type},submit:function(a){var b=a.nodeName.toLowerCase();return(b==="input"||b==="button")&&"submit"===a.type},image:function(a){return a.nodeName.toLowerCase()==="input"&&"image"===a.type},reset:function(a){var b=a.nodeName.toLowerCase();return(b==="input"||b==="button")&&"reset"===a.type},button:function(a){var b=a.nodeName.toLowerCase();return b==="input"&&"button"===a.type||b==="button"},input:function(a){return/input|select|textarea|button/i.test(a.nodeName)},focus:function(a){return a===a.ownerDocument.activeElement}},setFilters:{first:function(a,b){return b===0},last:function(a,b,c,d){return b===d.length-1},even:function(a,b){return b%2===0},odd:function(a,b){return b%2===1},lt:function(a,b,c){return bc[3]-0},nth:function(a,b,c){return c[3]-0===b},eq:function(a,b,c){return c[3]-0===b}},filter:{PSEUDO:function(a,b,c,d){var e=b[1],f=o.filters[e];if(f)return f(a,c,b,d);if(e==="contains")return(a.textContent||a.innerText||n([a])||"").indexOf(b[3])>=0;if(e==="not"){var g=b[3];for(var h=0,i=g.length;h=0}},ID:function(a,b){return a.nodeType===1&&a.getAttribute("id")===b},TAG:function(a,b){return b==="*"&&a.nodeType===1||!!a.nodeName&&a.nodeName.toLowerCase()===b},CLASS:function(a,b){return(" "+(a.className||a.getAttribute("class"))+" ").indexOf(b)>-1},ATTR:function(a,b){var c=b[1],d=m.attr?m.attr(a,c):o.attrHandle[c]?o.attrHandle[c](a):a[c]!=null?a[c]:a.getAttribute(c),e=d+"",f=b[2],g=b[4];return d==null?f==="!=":!f&&m.attr?d!=null:f==="="?e===g:f==="*="?e.indexOf(g)>=0:f==="~="?(" "+e+" ").indexOf(g)>=0:g?f==="!="?e!==g:f==="^="?e.indexOf(g)===0:f==="$="?e.substr(e.length-g.length)===g:f==="|="?e===g||e.substr(0,g.length+1)===g+"-":!1:e&&d!==!1},POS:function(a,b,c,d){var e=b[2],f=o.setFilters[e];if(f)return f(a,c,b,d)}}},p=o.match.POS,q=function(a,b){return"\\"+(b-0+1)};for(var r in o.match)o.match[r]=new RegExp(o.match[r].source+/(?![^\[]*\])(?![^\(]*\))/.source),o.leftMatch[r]=new RegExp(/(^(?:.|\r|\n)*?)/.source+o.match[r].source.replace(/\\(\d+)/g,q));var s=function(a,b){a=Array.prototype.slice.call(a,0);if(b){b.push.apply(b,a);return b}return a};try{Array.prototype.slice.call(c.documentElement.childNodes,0)[0].nodeType}catch(t){s=function(a,b){var c=0,d=b||[];if(g.call(a)==="[object Array]")Array.prototype.push.apply(d,a);else if(typeof a.length=="number")for(var e=a.length;c",e.insertBefore(a,e.firstChild),c.getElementById(d)&&(o.find.ID=function(a,c,d){if(typeof c.getElementById!="undefined"&&!d){var e=c.getElementById(a[1]);return e?e.id===a[1]||typeof e.getAttributeNode!="undefined"&&e.getAttributeNode("id").nodeValue===a[1]?[e]:b:[]}},o.filter.ID=function(a,b){var c=typeof a.getAttributeNode!="undefined"&&a.getAttributeNode("id");return a.nodeType===1&&c&&c.nodeValue===b}),e.removeChild(a),e=a=null}(),function(){var a=c.createElement("div");a.appendChild(c.createComment("")),a.getElementsByTagName("*").length>0&&(o.find.TAG=function(a,b){var c=b.getElementsByTagName(a[1]);if(a[1]==="*"){var d=[];for(var e=0;c[e];e++)c[e].nodeType===1&&d.push(c[e]);c=d}return c}),a.innerHTML="",a.firstChild&&typeof a.firstChild.getAttribute!="undefined"&&a.firstChild.getAttribute("href")!=="#"&&(o.attrHandle.href=function(a){return a.getAttribute("href",2)}),a=null}(),c.querySelectorAll&&function(){var a=m,b=c.createElement("div"),d="__sizzle__";b.innerHTML="
      ";if(!b.querySelectorAll||b.querySelectorAll(".TEST").length!==0){m=function(b,e,f,g){e=e||c;if(!g&&!m.isXML(e)){var h=/^(\w+$)|^\.([\w\-]+$)|^#([\w\-]+$)/.exec(b);if(h&&(e.nodeType===1||e.nodeType===9)){if(h[1])return s(e.getElementsByTagName(b),f);if(h[2]&&o.find.CLASS&&e.getElementsByClassName)return s(e.getElementsByClassName(h[2]),f)}if(e.nodeType===9){if(b==="body"&&e.body)return s([e.body],f);if(h&&h[3]){var i=e.getElementById(h[3]);if(!i||!i.parentNode)return s([],f);if(i.id===h[3])return s([i],f)}try{return s(e.querySelectorAll(b),f)}catch(j){}}else if(e.nodeType===1&&e.nodeName.toLowerCase()!=="object"){var k=e,l=e.getAttribute("id"),n=l||d,p=e.parentNode,q=/^\s*[+~]/.test(b);l?n=n.replace(/'/g,"\\$&"):e.setAttribute("id",n),q&&p&&(e=e.parentNode);try{if(!q||p)return s(e.querySelectorAll("[id='"+n+"'] "+b),f)}catch(r){}finally{l||k.removeAttribute("id")}}}return a(b,e,f,g)};for(var e in a)m[e]=a[e];b=null}}(),function(){var a=c.documentElement,b=a.matchesSelector||a.mozMatchesSelector||a.webkitMatchesSelector||a.msMatchesSelector;if(b){var d=!b.call(c.createElement("div"),"div"),e=!1;try{b.call(c.documentElement,"[test!='']:sizzle")}catch(f){e=!0}m.matchesSelector=function(a,c){c=c.replace(/\=\s*([^'"\]]*)\s*\]/g,"='$1']");if(!m.isXML(a))try{if(e||!o.match.PSEUDO.test(c)&&!/!=/.test(c)){var f=b.call(a,c);if(f||!d||a.document&&a.document.nodeType!==11)return f}}catch(g){}return m(c,null,null,[a]).length>0}}}(),function(){var a=c.createElement("div");a.innerHTML="
      ";if(!!a.getElementsByClassName&&a.getElementsByClassName("e").length!==0){a.lastChild.className="e";if(a.getElementsByClassName("e").length===1)return;o.order.splice(1,0,"CLASS"),o.find.CLASS=function(a,b,c){if(typeof b.getElementsByClassName!="undefined"&&!c)return b.getElementsByClassName(a[1])},a=null}}(),c.documentElement.contains?m.contains=function(a,b){return a!==b&&(a.contains?a.contains(b):!0)}:c.documentElement.compareDocumentPosition?m.contains=function(a,b){return!!(a.compareDocumentPosition(b)&16)}:m.contains=function(){return!1},m.isXML=function(a){var b=(a?a.ownerDocument||a:0).documentElement;return b?b.nodeName!=="HTML":!1};var y=function(a,b,c){var d,e=[],f="",g=b.nodeType?[b]:b;while(d=o.match.PSEUDO.exec(a))f+=d[0],a=a.replace(o.match.PSEUDO,"");a=o.relative[a]?a+"*":a;for(var h=0,i=g.length;h0)for(h=g;h=0:f.filter(a,this).length>0:this.filter(a).length>0)},closest:function(a,b){var c=[],d,e,g=this[0];if(f.isArray(a)){var h=1;while(g&&g.ownerDocument&&g!==b){for(d=0;d-1:f.find.matchesSelector(g,a)){c.push(g);break}g=g.parentNode;if(!g||!g.ownerDocument||g===b||g.nodeType===11)break}}c=c.length>1?f.unique(c):c;return this.pushStack(c,"closest",a)},index:function(a){if(!a)return this[0]&&this[0].parentNode?this.prevAll().length:-1;if(typeof a=="string")return f.inArray(this[0],f(a));return f.inArray(a.jquery?a[0]:a,this)},add:function(a,b){var c=typeof a=="string"?f(a,b):f.makeArray(a&&a.nodeType?[a]:a),d=f.merge(this.get(),c);return this.pushStack(S(c[0])||S(d[0])?d:f.unique(d))},andSelf:function(){return this.add(this.prevObject)}}),f.each({parent:function(a){var b=a.parentNode;return b&&b.nodeType!==11?b:null},parents:function(a){return f.dir(a,"parentNode")},parentsUntil:function(a,b,c){return f.dir(a,"parentNode",c)},next:function(a){return f.nth(a,2,"nextSibling")},prev:function(a){return f.nth(a,2,"previousSibling")},nextAll:function(a){return f.dir(a,"nextSibling")},prevAll:function(a){return f.dir(a,"previousSibling")},nextUntil:function(a,b,c){return f.dir(a,"nextSibling",c)},prevUntil:function(a,b,c){return f.dir(a,"previousSibling",c)},siblings:function(a){return f.sibling(a.parentNode.firstChild,a)},children:function(a){return f.sibling(a.firstChild)},contents:function(a){return f.nodeName(a,"iframe")?a.contentDocument||a.contentWindow.document:f.makeArray(a.childNodes)}},function(a,b){f.fn[a]=function(c,d){var e=f.map(this,b,c);L.test(a)||(d=c),d&&typeof d=="string"&&(e=f.filter(d,e)),e=this.length>1&&!R[a]?f.unique(e):e,(this.length>1||N.test(d))&&M.test(a)&&(e=e.reverse());return this.pushStack(e,a,P.call(arguments).join(","))}}),f.extend({filter:function(a,b,c){c&&(a=":not("+a+")");return b.length===1?f.find.matchesSelector(b[0],a)?[b[0]]:[]:f.find.matches(a,b)},dir:function(a,c,d){var e=[],g=a[c];while(g&&g.nodeType!==9&&(d===b||g.nodeType!==1||!f(g).is(d)))g.nodeType===1&&e.push(g),g=g[c];return e},nth:function(a,b,c,d){b=b||1;var e=0;for(;a;a=a[c])if(a.nodeType===1&&++e===b)break;return a},sibling:function(a,b){var c=[];for(;a;a=a.nextSibling)a.nodeType===1&&a!==b&&c.push(a);return c}});var V="abbr|article|aside|audio|canvas|datalist|details|figcaption|figure|footer|header|hgroup|mark|meter|nav|output|progress|section|summary|time|video",W=/ jQuery\d+="(?:\d+|null)"/g,X=/^\s+/,Y=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/ig,Z=/<([\w:]+)/,$=/",""],legend:[1,"
      ","
      "],thead:[1,"","
      "],tr:[2,"","
      "],td:[3,"","
      "],col:[2,"","
      "],area:[1,"",""],_default:[0,"",""]},bh=U(c);bg.optgroup=bg.option,bg.tbody=bg.tfoot=bg.colgroup=bg.caption=bg.thead,bg.th=bg.td,f.support.htmlSerialize||(bg._default=[1,"div
      ","
      "]),f.fn.extend({text:function(a){if(f.isFunction(a))return this.each(function(b){var c=f(this);c.text(a.call(this,b,c.text()))});if(typeof a!="object"&&a!==b)return this.empty().append((this[0]&&this[0].ownerDocument||c).createTextNode(a));return f.text(this)},wrapAll:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapAll(a.call(this,b))});if(this[0]){var b=f(a,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&b.insertBefore(this[0]),b.map(function(){var a=this;while(a.firstChild&&a.firstChild.nodeType===1)a=a.firstChild;return a}).append(this)}return this},wrapInner:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapInner(a.call(this,b))});return this.each(function(){var b=f(this),c=b.contents();c.length?c.wrapAll(a):b.append(a)})},wrap:function(a){var b=f.isFunction(a);return this.each(function(c){f(this).wrapAll(b?a.call(this,c):a)})},unwrap:function(){return this.parent().each(function(){f.nodeName(this,"body")||f(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this)});if(arguments.length){var a=f.clean(arguments);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this.nextSibling)});if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,f.clean(arguments));return a}},remove:function(a,b){for(var c=0,d;(d=this[c])!=null;c++)if(!a||f.filter(a,[d]).length)!b&&d.nodeType===1&&(f.cleanData(d.getElementsByTagName("*")),f.cleanData([d])),d.parentNode&&d.parentNode.removeChild(d);return this},empty:function()
{for(var a=0,b;(b=this[a])!=null;a++){b.nodeType===1&&f.cleanData(b.getElementsByTagName("*"));while(b.firstChild)b.removeChild(b.firstChild)}return this},clone:function(a,b){a=a==null?!1:a,b=b==null?a:b;return this.map(function(){return f.clone(this,a,b)})},html:function(a){if(a===b)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(W,""):null;if(typeof a=="string"&&!ba.test(a)&&(f.support.leadingWhitespace||!X.test(a))&&!bg[(Z.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Y,"<$1>");try{for(var c=0,d=this.length;c1&&l0?this.clone(!0):this).get();f(e[h])[b](j),d=d.concat(j)}return this.pushStack(d,a,e.selector)}}),f.extend({clone:function(a,b,c){var d,e,g,h=f.support.html5Clone||!bc.test("<"+a.nodeName)?a.cloneNode(!0):bo(a);if((!f.support.noCloneEvent||!f.support.noCloneChecked)&&(a.nodeType===1||a.nodeType===11)&&!f.isXMLDoc(a)){bk(a,h),d=bl(a),e=bl(h);for(g=0;d[g];++g)e[g]&&bk(d[g],e[g])}if(b){bj(a,h);if(c){d=bl(a),e=bl(h);for(g=0;d[g];++g)bj(d[g],e[g])}}d=e=null;return h},clean:function(a,b,d,e){var g;b=b||c,typeof b.createElement=="undefined"&&(b=b.ownerDocument||b[0]&&b[0].ownerDocument||c);var h=[],i;for(var j=0,k;(k=a[j])!=null;j++){typeof k=="number"&&(k+="");if(!k)continue;if(typeof k=="string")if(!_.test(k))k=b.createTextNode(k);else{k=k.replace(Y,"<$1>");var l=(Z.exec(k)||["",""])[1].toLowerCase(),m=bg[l]||bg._default,n=m[0],o=b.createElement("div");b===c?bh.appendChild(o):U(b).appendChild(o),o.innerHTML=m[1]+k+m[2];while(n--)o=o.lastChild;if(!f.support.tbody){var p=$.test(k),q=l==="table"&&!p?o.firstChild&&o.firstChild.childNodes:m[1]===""&&!p?o.childNodes:[];for(i=q.length-1;i>=0;--i)f.nodeName(q[i],"tbody")&&!q[i].childNodes.length&&q[i].parentNode.removeChild(q[i])}!f.support.leadingWhitespace&&X.test(k)&&o.insertBefore(b.createTextNode(X.exec(k)[0]),o.firstChild),k=o.childNodes}var r;if(!f.support.appendChecked)if(k[0]&&typeof (r=k.length)=="number")for(i=0;i=0)return b+"px"}}}),f.support.opacity||(f.cssHooks.opacity={get:function(a,b){return br.test((b&&a.currentStyle?a.currentStyle.filter:a.style.filter)||"")?parseFloat(RegExp.$1)/100+"":b?"1":""},set:function(a,b){var c=a.style,d=a.currentStyle,e=f.isNumeric(b)?"alpha(opacity="+b*100+")":"",g=d&&d.filter||c.filter||"";c.zoom=1;if(b>=1&&f.trim(g.replace(bq,""))===""){c.removeAttribute("filter");if(d&&!d.filter)return}c.filter=bq.test(g)?g.replace(bq,e):g+" "+e}}),f(function(){f.support.reliableMarginRight||(f.cssHooks.marginRight={get:function(a,b){var c;f.swap(a,{display:"inline-block"},function(){b?c=bz(a,"margin-right","marginRight"):c=a.style.marginRight});return c}})}),c.defaultView&&c.defaultView.getComputedStyle&&(bA=function(a,b){var c,d,e;b=b.replace(bs,"-$1").toLowerCase(),(d=a.ownerDocument.defaultView)&&(e=d.getComputedStyle(a,null))&&(c=e.getPropertyValue(b),c===""&&!f.contains(a.ownerDocument.documentElement,a)&&(c=f.style(a,b)));return c}),c.documentElement.currentStyle&&(bB=function(a,b){var c,d,e,f=a.currentStyle&&a.currentStyle[b],g=a.style;f===null&&g&&(e=g[b])&&(f=e),!bt.test(f)&&bu.test(f)&&(c=g.left,d=a.runtimeStyle&&a.runtimeStyle.left,d&&(a.runtimeStyle.left=a.currentStyle.left),g.left=b==="fontSize"?"1em":f||0,f=g.pixelLeft+"px",g.left=c,d&&(a.runtimeStyle.left=d));return f===""?"auto":f}),bz=bA||bB,f.expr&&f.expr.filters&&(f.expr.filters.hidden=function(a){var b=a.offsetWidth,c=a.offsetHeight;return b===0&&c===0||!f.support.reliableHiddenOffsets&&(a.style&&a.style.display||f.css(a,"display"))==="none"},f.expr.filters.visible=function(a){return!f.expr.filters.hidden(a)});var bD=/%20/g,bE=/\[\]$/,bF=/\r?\n/g,bG=/#.*$/,bH=/^(.*?):[ \t]*([^\r\n]*)\r?$/mg,bI=/^(?:color|date|datetime|datetime-local|email|hidden|month|number|password|range|search|tel|text|time|url|week)$/i,bJ=/^(?:about|app|app\-storage|.+\-extension|file|res|widget):$/,bK=/^(?:GET|HEAD)$/,bL=/^\/\//,bM=/\?/,bN=/)<[^<]*)*<\/script>/gi,bO=/^(?:select|textarea)/i,bP=/\s+/,bQ=/([?&])_=[^&]*/,bR=/^([\w\+\.\-]+:)(?:\/\/([^\/?#:]*)(?::(\d+))?)?/,bS=f.fn.load,bT={},bU={},bV,bW,bX=["*/"]+["*"];try{bV=e.href}catch(bY){bV=c.createElement("a"),bV.href="",bV=bV.href}bW=bR.exec(bV.toLowerCase())||[],f.fn.extend({load:function(a,c,d){if(typeof a!="string"&&bS)return bS.apply(this,arguments);if(!this.length)return this;var e=a.indexOf(" ");if(e>=0){var g=a.slice(e,a.length);a=a.slice(0,e)}var h="GET";c&&(f.isFunction(c)?(d=c,c=b):typeof c=="object"&&(c=f.param(c,f.ajaxSettings.traditional),h="POST"));var i=this;f.ajax({url:a,type:h,dataType:"html",data:c,complete:function(a,b,c){c=a.responseText,a.isResolved()&&(a.done(function(a){c=a}),i.html(g?f("
      ").append(c.replace(bN,"")).find(g):c)),d&&i.each(d,[c,b,a])}});return this},serialize:function(){return f.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?f.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||bO.test(this.nodeName)||bI.test(this.type))}).map(function(a,b){var c=f(this).val();return c==null?null:f.isArray(c)?f.map(c,function(a,c){return{name:b.name,value:a.replace(bF,"\r\n")}}):{name:b.name,value:c.replace(bF,"\r\n")}}).get()}}),f.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(a,b){f.fn[b]=function(a){return this.on(b,a)}}),f.each(["get","post"],function(a,c){f[c]=function(a,d,e,g){f.isFunction(d)&&(g=g||e,e=d,d=b);return f.ajax({type:c,url:a,data:d,success:e,dataType:g})}}),f.extend({getScript:function(a,c){return f.get(a,b,c,"script")},getJSON:function(a,b,c){return f.get(a,b,c,"json")},ajaxSetup:function(a,b){b?b_(a,f.ajaxSettings):(b=a,a=f.ajaxSettings),b_(a,b);return a},ajaxSettings:{url:bV,isLocal:bJ.test(bW[1]),global:!0,type:"GET",contentType:"application/x-www-form-urlencoded",processData:!0,async:!0,accepts:{xml:"application/xml, text/xml",html:"text/html",text:"text/plain",json:"application/json, text/javascript","*":bX},contents:{xml:/xml/,html:/html/,json:/json/},responseFields:{xml:"responseXML",text:"responseText"},converters:{"* text":a.String,"text html":!0,"text json":f.parseJSON,"text xml":f.parseXML},flatOptions:{context:!0,url:!0}},ajaxPrefilter:bZ(bT),ajaxTransport:bZ(bU),ajax:function(a,c){function w(a,c,l,m){if(s!==2){s=2,q&&clearTimeout(q),p=b,n=m||"",v.readyState=a>0?4:0;var o,r,u,w=c,x=l?cb(d,v,l):b,y,z;if(a>=200&&a<300||a===304){if(d.ifModified){if(y=v.getResponseHeader("Last-Modified"))f.lastModified[k]=y;if(z=v.getResponseHeader("Etag"))f.etag[k]=z}if(a===304)w="notmodified",o=!0;else try{r=cc(d,x),w="success",o=!0}catch(A){w="parsererror",u=A}}else{u=w;if(!w||a)w="error",a<0&&(a=0)}v.status=a,v.statusText=""+(c||w),o?h.resolveWith(e,[r,w,v]):h.rejectWith(e,[v,w,u]),v.statusCode(j),j=b,t&&g.trigger("ajax"+(o?"Success":"Error"),[v,d,o?r:u]),i.fireWith(e,[v,w]),t&&(g.trigger("ajaxComplete",[v,d]),--f.active||f.event.trigger("ajaxStop"))}}typeof a=="object"&&(c=a,a=b),c=c||{};var d=f.ajaxSetup({},c),e=d.context||d,g=e!==d&&(e.nodeType||e instanceof f)?f(e):f.event,h=f.Deferred(),i=f.Callbacks("once memory"),j=d.statusCode||{},k,l={},m={},n,o,p,q,r,s=0,t,u,v={readyState:0,setRequestHeader:function(a,b){if(!s){var c=a.toLowerCase();a=m[c]=m[c]||a,l[a]=b}return this},getAllResponseHeaders:function(){return s===2?n:null},getResponseHeader:function(a){var c;if(s===2){if(!o){o={};while(c=bH.exec(n))o[c[1].toLowerCase()]=c[2]}c=o[a.toLowerCase()]}return c===b?null:c},overrideMimeType:function(a){s||(d.mimeType=a);return this},abort:function(a){a=a||"abort",p&&p.abort(a),w(0,a);return this}};h.promise(v),v.success=v.done,v.error=v.fail,v.complete=i.add,v.statusCode=function(a){if(a){var b;if(s<2)for(b in a)j[b]=[j[b],a[b]];else b=a[v.status],v.then(b,b)}return this},d.url=((a||d.url)+"").replace(bG,"").replace(bL,bW[1]+"//"),d.dataTypes=f.trim(d.dataType||"*").toLowerCase().split(bP),d.crossDomain==null&&(r=bR.exec(d.url.toLowerCase()),d.crossDomain=!(!r||r[1]==bW[1]&&r[2]==bW[2]&&(r[3]||(r[1]==="http:"?80:443))==(bW[3]||(bW[1]==="http:"?80:443)))),d.data&&d.processData&&typeof d.data!="string"&&(d.data=f.param(d.data,d.traditional)),b$(bT,d,c,v);if(s===2)return!1;t=d.global,d.type=d.type.toUpperCase(),d.hasContent=!bK.test(d.type),t&&f.active++===0&&f.event.trigger("ajaxStart");if(!d.hasContent){d.data&&(d.url+=(bM.test(d.url)?"&":"?")+d.data,delete d.data),k=d.url;if(d.cache===!1){var x=f.now(),y=d.url.replace(bQ,"$1_="+x);d.url=y+(y===d.url?(bM.test(d.url)?"&":"?")+"_="+x:"")}}(d.data&&d.hasContent&&d.contentType!==!1||c.contentType)&&v.setRequestHeader("Content-Type",d.contentType),d.ifModified&&(k=k||d.url,f.lastModified[k]&&v.setRequestHeader("If-Modified-Since",f.lastModified[k]),f.etag[k]&&v.setRequestHeader("If-None-Match",f.etag[k])),v.setRequestHeader("Accept",d.dataTypes[0]&&d.accepts[d.dataTypes[0]]?d.accepts[d.dataTypes[0]]+(d.dataTypes[0]!=="*"?", "+bX+"; q=0.01":""):d.accepts["*"]);for(u in d.headers)v.setRequestHeader(u,d.headers[u]);if(d.beforeSend&&(d.beforeSend.call(e,v,d)===!1||s===2)){v.abort();return!1}for(u in{success:1,error:1,complete:1})v[u](d[u]);p=b$(bU,d,c,v);if(!p)w(-1,"No Transport");else{v.readyState=1,t&&g.trigger("ajaxSend",[v,d]),d.async&&d.timeout>0&&(q=setTimeout(function(){v.abort("timeout")},d.timeout));try{s=1,p.send(l,w)}catch(z){if(s<2)w(-1,z);else throw z}}return v},param:function(a,c){var d=[],e=function(a,b){b=f.isFunction(b)?b():b,d[d.length]=encodeURIComponent(a)+"="+encodeURIComponent(b)};c===b&&(c=f.ajaxSettings.traditional);if(f.isArray(a)||a.jquery&&!f.isPlainObject(a))f.each(a,function(){e(this.name,this.value)});else for(var g in a)ca(g,a[g],c,e);return d.join("&").replace(bD,"+")}}),f.extend({active:0,lastModified:{},etag:{}});var cd=f.now(),ce=/(\=)\?(&|$)|\?\?/i;f.ajaxSetup({jsonp:"callback",jsonpCallback:function(){return f.expando+"_"+cd++}}),f.ajaxPrefilter("json jsonp",function(b,c,d){var e=b.contentType==="application/x-www-form-urlencoded"&&typeof b.data=="string";if(b.dataTypes[0]==="jsonp"||b.jsonp!==!1&&(ce.test(b.url)||e&&ce.test(b.data))){var g,h=b.jsonpCallback=f.isFunction(b.jsonpCallback)?b.jsonpCallback():b.jsonpCallback,i=a[h],j=b.url,k=b.data,l="$1"+h+"$2";b.jsonp!==!1&&(j=j.replace(ce,l),b.url===j&&(e&&(k=k.replace(ce,l)),b.data===k&&(j+=(/\?/.test(j)?"&":"?")+b.jsonp+"="+h))),b.url=j,b.data=k,a[h]=function(a){g=[a]},d.always(function(){a[h]=i,g&&f.isFunction(i)&&a[h](g[0])}),b.converters["script json"]=function(){g||f.error(h+" was not called");return g[0]},b.dataTypes[0]="json";return"script"}}),f.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/javascript|ecmascript/},converters:{"text script":function(a){f.globalEval(a);return a}}}),f.ajaxPrefilter("script",function(a){a.cache===b&&(a.cache=!1),a.crossDomain&&(a.type="GET",a.global=!1)}),f.ajaxTransport("script",function(a){if(a.crossDomain){var d,e=c.head||c.getElementsByTagName("head")[0]||c.documentElement;return{send:function(f,g){d=c.createElement("script"),d.async="async",a.scriptCharset&&(d.charset=a.scriptCharset),d.src=a.url,d.onload=d.onreadystatechange=function(a,c){if(c||!d.readyState||/loaded|complete/.test(d.readyState))d.onload=d.onreadystatechange=null,e&&d.parentNode&&e.removeChild(d),d=b,c||g(200,"success")},e.insertBefore(d,e.firstChild)},abort:function(){d&&d.onload(0,1)}}}});var cf=a.ActiveXObject?function(){for(var a in ch)ch[a](0,1)}:!1,cg=0,ch;f.ajaxSettings.xhr=a.ActiveXObject?function(){return!this.isLocal&&ci()||cj()}:ci,function(a){f.extend(f.support,{ajax:!!a,cors:!!a&&"withCredentials"in a})}(f.ajaxSettings.xhr()),f.support.ajax&&f.ajaxTransport(function(c){if(!c.crossDomain||f.support.cors){var d;return{send:function(e,g){var h=c.xhr(),i,j;c.username?h.open(c.type,c.url,c.async,c.username,c.password):h.open(c.type,c.url,c.async);if(c.xhrFields)for(j in c.xhrFields)h[j]=c.xhrFields[j];c.mimeType&&h.overrideMimeType&&h.overrideMimeType(c.mimeType),!c.crossDomain&&!e["X-Requested-With"]&&(e["X-Requested-With"]="XMLHttpRequest");try{for(j in e)h.setRequestHeader(j,e[j])}catch(k){}h.send(c.hasContent&&c.data||null),d=function(a,e){var j,k,l,m,n;try{if(d&&(e||h.readyState===4)){d=b,i&&(h.onreadystatechange=f.noop,cf&&delete ch[i]);if(e)h.readyState!==4&&h.abort();else{j=h.status,l=h.getAllResponseHeaders(),m={},n=h.responseXML,n&&n.documentElement&&(m.xml=n),m.text=h.responseText;try{k=h.statusText}catch(o){k=""}!j&&c.isLocal&&!c.crossDomain?j=m.text?200:404:j===1223&&(j=204)}}}catch(p){e||g(-1,p)}m&&g(j,k,m,l)},!c.async||h.readyState===4?d():(i=++cg,cf&&(ch||(ch={},f(a).unload(cf)),ch[i]=d),h.onreadystatechange=d)},abort:function(){d&&d(0,1)}}}});var ck={},cl,cm,cn=/^(?:toggle|show|hide)$/,co=/^([+\-]=)?([\d+.\-]+)([a-z%]*)$/i,cp,cq=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]],cr;f.fn.extend({show:function(a,b,c){var d,e;if(a||a===0)return this.animate(cu("show",3),a,b,c);for(var g=0,h=this.length;g=i.duration+this.startTime){this.now=this.end,this.pos=this.state=1,this.update(),i.animatedProperties[this.prop]=!0;for(b in i.animatedProperties)i.animatedProperties[b]!==!0&&(g=!1);if(g){i.overflow!=null&&!f.support.shrinkWrapBlocks&&f.each(["","X","Y"],function(a,b){h.style["overflow"+b]=i.overflow[a]}),i.hide&&f(h).hide();if(i.hide||i.show)for(b in i.animatedProperties)f.style(h,b,i.orig[b]),f.removeData(h,"fxshow"+b,!0),f.removeData(h,"toggle"+b,!0);d=i.complete,d&&(i.complete=!1,d.call(h))}return!1}i.duration==Infinity?this.now=e:(c=e-this.startTime,this.state=c/i.duration,this.pos=f.easing[i.animatedProperties[this.prop]](this.state,c,0,1,i.duration),this.now=this.start+(this.end-this.start)*this.pos),this.update();return!0}},f.extend(f.fx,{tick:function(){var a,b=f.timers,c=0;for(;c-1,k={},l={},m,n;j?(l=e.position(),m=l.top,n=l.left):(m=parseFloat(h)||0,n=parseFloat(i)||0),f.isFunction(b)&&(b=b.call(a,c,g)),b.top!=null&&(k.top=b.top-g.top+m),b.left!=null&&(k.left=b.left-g.left+n),"using"in b?b.using.call(a,k):e.css(k)}},f.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),c=this.offset(),d=cx.test(b[0].nodeName)?{top:0,left:0}:b.offset();c.top-=parseFloat(f.css(a,"marginTop"))||0,c.left-=parseFloat(f.css(a,"marginLeft"))||0,d.top+=parseFloat(f.css(b[0],"borderTopWidth"))||0,d.left+=parseFloat(f.css(b[0],"borderLeftWidth"))||0;return{top:c.top-d.top,left:c.left-d.left}},offsetParent:function(){return this.map(function(){var a=this.offsetParent||c.body;while(a&&!cx.test(a.nodeName)&&f.css(a,"position")==="static")a=a.offsetParent;return a})}}),f.each(["Left","Top"],function(a,c){var d="scroll"+c;f.fn[d]=function(c){var e,g;if(c===b){e=this[0];if(!e)return null;g=cy(e);return g?"pageXOffset"in g?g[a?"pageYOffset":"pageXOffset"]:f.support.boxModel&&g.document.documentElement[d]||g.document.body[d]:e[d]}return this.each(function(){g=cy(this),g?g.scrollTo(a?f(g).scrollLeft():c,a?c:f(g).scrollTop()):this[d]=c})}}),f.each(["Height","Width"],function(a,c){var d=c.toLowerCase();f.fn["inner"+c]=function(){var a=this[0];return a?a.style?parseFloat(f.css(a,d,"padding")):this[d]():null},f.fn["outer"+c]=function(a){var b=this[0];return b?b.style?parseFloat(f.css(b,d,a?"margin":"border")):this[d]():null},f.fn[d]=function(a){var e=this[0];if(!e)return a==null?null:this;if(f.isFunction(a))return this.each(function(b){var c=f(this);c[d](a.call(this,b,c[d]()))});if(f.isWindow(e)){var g=e.document.documentElement["client"+c],h=e.document.body;return e.document.compatMode==="CSS1Compat"&&g||h&&h["client"+c]||g}if(e.nodeType===9)return Math.max(e.documentElement["client"+c],e.body["scroll"+c],e.documentElement["scroll"+c],e.body["offset"+c],e.documentElement["offset"+c]);if(a===b){var i=f.css(e,d),j=parseFloat(i);return f.isNumeric(j)?j:i}return this.css(d,typeof a=="string"?a:a+"px")}}),a.jQuery=a.$=f,typeof define=="function"&&define.amd&&define.amd.jQuery&&define("jquery",[],function(){return f})})(window);yard-0.9.37/templates/default/fulldoc/html/setup.rb000066400000000000000000000163671466601756300223070ustar00rootroot00000000000000# frozen_string_literal: true
include Helpers::ModuleHelper

def init
  options.objects = objects = run_verifier(options.objects)

  return serialize_onefile if options.onefile
  generate_assets
  serialize('_index.html')
  options.files.each_with_index do |file, _i|
    serialize_file(file, file.title)
  end

  options.delete(:objects)
  options.delete(:files)

  objects.each do |object|
    begin
      serialize(object)
    rescue => e
      path = options.serializer.serialized_path(object)
      log.error "Exception occurred while generating '#{path}'"
      log.backtrace(e)
    end
  end
end

# Generate an HTML document for the specified object. This method is used by
# most of the objects found in the Registry.
# @param [CodeObject] object to be saved to HTML
def serialize(object)
  options.object = object
  serialize_index(options) if object == '_index.html' && options.readme.nil?
  Templates::Engine.with_serializer(object, options.serializer) do
    T('layout').run(options)
  end
end

# Generate the documentation output in one file (--one-file) which will load the
# contents of all the javascript and css and output the entire contents without
# depending on any additional files
def serialize_onefile
  Templates::Engine.with_serializer('index.html', options.serializer) do
    T('onefile').run(options)
  end
end

# Generate the index document for the output
# @params [Hash] options contains data and flags that influence the output
def serialize_index(options)
  Templates::Engine.with_serializer('index.html', options.serializer) do
    T('layout').run(options.merge(:index => true))
  end
end

# Generate a single HTML file with the layout template applied. This is generally
# the README file or files specified on the command-line.
#
# @param [File] file object to be saved to the output
# @param [String] title currently unused
#
# @see layout#diskfile
def serialize_file(file, title = nil) # rubocop:disable Lint/UnusedMethodArgument
  options.object = Registry.root
  options.file = file
  outfile = 'file.' + file.name + '.html'

  serialize_index(options) if file == options.readme
  Templates::Engine.with_serializer(outfile, options.serializer) do
    T('layout').run(options)
  end
  options.delete(:file)
end

#
# Generates a file to the output with the specified contents.
#
# @example saving a custom html file to the documentation root
#
#   asset('my_custom.html','Custom File')
#
# @param [String] path relative to the document output where the file will be
#   created.
# @param [String] content the contents that are saved to the file.
def asset(path, content)
  if options.serializer
    log.capture("Generating asset #{path}") do
      options.serializer.serialize(path, content)
    end
  end
end

# @return [Array] Stylesheet files that are additionally loaded for the
#   searchable full lists, e.g., Class List, Method List, File List
# @since 0.7.0
def stylesheets_full_list
  %w(css/full_list.css css/common.css)
end

# @return [Array] Javascript files that are additionally loaded for the
#   searchable full lists, e.g., Class List, Method List, File List.
# @since 0.7.0
def javascripts_full_list
  %w(js/jquery.js js/full_list.js)
end

# Sets the HTML language lang="value" where value is the value returned from
# this method. Defaults to nil which does not set the lang attribute.
def html_lang
  nil
end

def menu_lists
  Object.new.extend(T('layout')).menu_lists
end

# Generates all the javascript files, stylesheet files, menu lists
# (i.e. class, method, and file) based on the the values returned from the
# layout's menu_list method, and the frameset in the documentation output
#
def generate_assets
  @object = Registry.root

  layout = Object.new.extend(T('layout'))
  (layout.javascripts + javascripts_full_list +
      layout.stylesheets + stylesheets_full_list).uniq.each do |file|
    asset(file, file(file, true))
  end
  layout.menu_lists.each do |list|
    list_generator_method = "generate_#{list[:type]}_list"
    if respond_to?(list_generator_method)
      send(list_generator_method)
    else
      log.error "Unable to generate '#{list[:title]}' list because no method " \
                "'#{list_generator_method}' exists"
    end
  end

  generate_frameset
end

# Generate a searchable method list in the output
# @see ModuleHelper#prune_method_listing
def generate_method_list
  @items = prune_method_listing(Registry.all(:method), false)
  @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }
  @items = @items.sort_by {|m| m.name.to_s }
  @list_title = "Method List"
  @list_type = "method"
  generate_list_contents
end

# Generate a searchable class list in the output
def generate_class_list
  @items = options.objects if options.objects
  @list_title = "Class List"
  @list_type = "class"
  generate_list_contents
end

# Generate a searchable file list in the output
def generate_file_list
  @file_list = true
  @items = options.files
  @list_title = "File List"
  @list_type = "file"
  generate_list_contents
  @file_list = nil
end

def generate_list_contents
  asset(url_for_list(@list_type), erb(:full_list))
end

# Generate the frame documentation in the output
def generate_frameset
  @javascripts = javascripts_full_list
  @stylesheets = stylesheets_full_list
  asset(url_for_frameset, erb(:frames))
end

# @api private
class TreeContext
  def initialize
    @depth = 0
    @even_odd = Alternator.new(:even, :odd)
  end

  def nest
    @depth += 1
    yield
    @depth -= 1
  end

  # @return [String] Returns a css pixel offset, e.g. "30px"
  def indent
    "#{(@depth + 2) * 15}px"
  end

  def classes
    classes = []
    classes << 'collapsed' if @depth > 0
    classes << @even_odd.next if @depth < 2
    classes
  end

  class Alternator
    def initialize(first, second)
      @next = first
      @after = second
    end

    def next
      @next, @after = @after, @next
      @after
    end
  end
end

# @return [String] HTML output of the classes to be displayed in the
#    full_list_class template.
def class_list(root = Registry.root, tree = TreeContext.new)
  out = String.new("")
  children = run_verifier(root.children)
  if root == Registry.root
    children += @items.select {|o| o.namespace.is_a?(CodeObjects::Proxy) }
  end
  children.compact.sort_by(&:path).each do |child|
    next unless child.is_a?(CodeObjects::NamespaceObject)
    name = child.namespace.is_a?(CodeObjects::Proxy) ? child.path : child.name
    has_children = run_verifier(child.children).any? {|o| o.is_a?(CodeObjects::NamespaceObject) }
    out << "
    • "
    out << "
      "
    accessible_props = "aria-label='#{name} child nodes' aria-expanded='false' aria-controls='object_#{child.path}'"
    out << " " if has_children
    out << linkify(child, name)
    out << " < #{child.superclass.name}" if child.is_a?(CodeObjects::ClassObject) && child.superclass
    out << ""
    out << child.namespace.title
    out << ""
    out << "
      "
    tree.nest do
      labeled_by = "aria-labelledby='object_#{child.path}'"
      out << "
        #{class_list(child, tree)}
      " if has_children
    end
    out << "
      • "
  end
  out
end
yard-0.9.37/templates/default/layout/000077500000000000000000000000001466601756300175265ustar00rootroot00000000000000yard-0.9.37/templates/default/layout/dot/000077500000000000000000000000001466601756300203145ustar00rootroot00000000000000yard-0.9.37/templates/default/layout/dot/header.erb000066400000000000000000000002461466601756300222400ustar00rootroot00000000000000digraph yard {
  graph [rankdir=BT rank=sink outputMode=nodesfirst packMode="graph" splines=true];
  node [shape=record rank=sink rankType=sink];

  <%= yieldall %>
}yard-0.9.37/templates/default/layout/dot/setup.rb000066400000000000000000000003611466601756300220010ustar00rootroot00000000000000# frozen_string_literal: true
attr_reader :contents

def init
  if object
    type = object.root? ? :module : object.type
    sections :header, [T(type)]
  else
    sections :header, [:contents]
  end
end

def header
  tidy erb(:header)
end
yard-0.9.37/templates/default/layout/html/000077500000000000000000000000001466601756300204725ustar00rootroot00000000000000yard-0.9.37/templates/default/layout/html/breadcrumb.erb000066400000000000000000000012451466601756300232740ustar00rootroot00000000000000
yard-0.9.37/templates/default/layout/html/files.erb000066400000000000000000000004541466601756300222710ustar00rootroot00000000000000<% if @files && @files.size > 0 %>
  
      File Listing
      
  
        
  <% n = 1 %>
  <% @files.each_with_index do |file, i| %>
    
      • <%= link_file(file) %>
        • 
    <% n = n == 2 ? 1 : 2 %>
  <% end %>
  
      
<% end %>

      
yard-0.9.37/templates/default/layout/html/footer.erb000066400000000000000000000003351466601756300224630ustar00rootroot00000000000000
yard-0.9.37/templates/default/layout/html/headers.erb000066400000000000000000000010401466601756300225720ustar00rootroot00000000000000


  <%= h @page_title %>
  <% if options.title && @page_title != options.title %>
    — <%= h options.title %>
  <% end %>

<% stylesheets.each do |stylesheet| %>
  
<% end %>
<%= erb :script_setup %>
<% javascripts.each do |javascript| %>
  
<% end %>
yard-0.9.37/templates/default/layout/html/index.erb000066400000000000000000000001051466601756300222670ustar00rootroot00000000000000
      <%= options.title %>
      
<%= yieldall %>
yard-0.9.37/templates/default/layout/html/layout.erb000066400000000000000000000007261466601756300225060ustar00rootroot00000000000000

  
    <%= erb(:headers) %>
  
  
    
      
      
      
      
    
      

    
      
      

      
      <%= yieldall %>
      

      <%= erb(:footer) %>
    
      
  
yard-0.9.37/templates/default/layout/html/listing.erb000066400000000000000000000001331466601756300226320ustar00rootroot00000000000000
      
  
      Alphabetic Index
      
  <%= yieldall %>

      
yard-0.9.37/templates/default/layout/html/objects.erb000066400000000000000000000016011466601756300226130ustar00rootroot00000000000000
      Namespace Listing A-Z
      

<% if Registry.root.meths(:included => false).size > 0 %>
  
      • <%= linkify(Registry.root) %>
      
<% end %>

<% i = 0 %>

      
  
      
    
      <% @objects_by_letter.sort_by {|l,o| l.to_s }.each do |letter, objects| %>
        <% if (i += 1) % 8 == 0 %>
          
          <% i = 0 %>
        <% end %>
        
        
          
      • <%= letter %>
        • 
          
          
            <% objects.each do |obj| %>
              
        • 
                <%= linkify obj, obj.name %>
                <% if !obj.namespace.root? %>
                  (<%= obj.namespace.path %>)
                <% end %>
              
          • 
            <% end %>
          
        
        
      
      <% end %>
          		
  
      

      
yard-0.9.37/templates/default/layout/html/script_setup.erb000066400000000000000000000002341466601756300237070ustar00rootroot00000000000000
yard-0.9.37/templates/default/layout/html/search.erb000066400000000000000000000007321466601756300224330ustar00rootroot00000000000000yard-0.9.37/templates/default/layout/html/setup.rb000066400000000000000000000045051466601756300221630ustar00rootroot00000000000000# frozen_string_literal: true
def init
  @breadcrumb = []
  @page_title = ''
  @breadcrumb_title = ''
  if @onefile
    sections :layout
  elsif defined?(@file) && @file
    if @file.attributes[:namespace]
      @object = options.object = Registry.at(@file.attributes[:namespace]) || Registry.root
    end
    @breadcrumb_title = "File: " + @file.title
    @page_title = @breadcrumb_title
    sections :layout, [:diskfile]
  elsif @contents
    sections :layout, [:contents]
  else
    case object
    when '_index.html'
      @page_title = options.title
      sections :layout, [:index, [:listing, [:files, :objects]]]
    when CodeObjects::Base
      unless object.root?
        cur = object.namespace
        until cur.root?
          @breadcrumb.unshift(cur)
          cur = cur.namespace
        end
      end

      @page_title = format_object_title(object)
      type = object.root? ? :module : object.type
      sections :layout, [T(type)]
    end
  end
end

attr_reader :contents

def index
  @objects_by_letter = {}
  objects = Registry.all(:class, :module).sort_by {|o| o.name.to_s }
  objects = run_verifier(objects)
  objects.each {|o| (@objects_by_letter[o.name.to_s[0, 1].upcase] ||= []) << o }
  erb(:index)
end

def layout
  @nav_url = url_for_list(!(defined?(@file) && @file) || options.index ? 'class' : 'file')

  @path =
    if !object || object.is_a?(String)
      nil
    elsif defined?(@file) && @file
      @file.path
    elsif !object.is_a?(YARD::CodeObjects::NamespaceObject)
      object.parent.path
    else
      object.path
    end

  erb(:layout)
end

def diskfile
  @file.attributes[:markup] ||= markup_for_file('', @file.filename)
  data = htmlify(@file.contents, @file.attributes[:markup])
  "
      " + data + "
      "
end

# @return [Array] core javascript files for layout
# @since 0.7.0
def javascripts
  %w(js/jquery.js js/app.js)
end

# @return [Array] core stylesheets for the layout
# @since 0.7.0
def stylesheets
  %w(css/style.css css/common.css)
end

# @return [ArrayString}>] the list of search links and drop-down menus
# @since 0.7.0
def menu_lists
  [{:type => 'class', :title => 'Classes', :search_title => 'Class List'},
    {:type => 'method', :title => 'Methods', :search_title => 'Method List'},
    {:type => 'file', :title => 'Files', :search_title => 'File List'}]
end
yard-0.9.37/templates/default/method/000077500000000000000000000000001466601756300174715ustar00rootroot00000000000000yard-0.9.37/templates/default/method/html/000077500000000000000000000000001466601756300204355ustar00rootroot00000000000000yard-0.9.37/templates/default/method/html/header.erb000066400000000000000000000006501466601756300223600ustar00rootroot00000000000000
      Method: <%= object.path %>
      

      
  
      
    
      Defined in:
      
    
      
    <%= object.file %><% if object.files.size > 1 %>,
      
      <%= object.files[1..-1].map {|f| f.first }.join(",
       ") %>
      
    <% end %>
    
  



      
  
      
    <%= yieldall :index => 0 %>
  
      

      yard-0.9.37/templates/default/method/setup.rb000066400000000000000000000001251466601756300211540ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :header, [T('method_details')]
end
yard-0.9.37/templates/default/method/text/000077500000000000000000000000001466601756300204555ustar00rootroot00000000000000yard-0.9.37/templates/default/method/text/header.erb000066400000000000000000000000171466601756300223750ustar00rootroot00000000000000<%= yieldall %>yard-0.9.37/templates/default/method_details/000077500000000000000000000000001466601756300211765ustar00rootroot00000000000000yard-0.9.37/templates/default/method_details/html/000077500000000000000000000000001466601756300221425ustar00rootroot00000000000000yard-0.9.37/templates/default/method_details/html/header.erb000066400000000000000000000001271466601756300240640ustar00rootroot00000000000000
      
  <%= yieldall %>

      yard-0.9.37/templates/default/method_details/html/method_signature.erb000066400000000000000000000015751466601756300262050ustar00rootroot00000000000000
      
  <% if object.tags(:overload).size == 1 %>
    <%= signature(object.tag(:overload), false) %>
  <% elsif object.tags(:overload).size > 1 %>
    <% object.tags(:overload).each do |overload| %>
      <%= signature(overload, false) %>
    <% end %>
  <% else %>
    <%= signature(object, false) %>
  <% end %>

  <% if object.aliases.size > 0 %>
    Also known as:
    <%= object.aliases.map {|o|
      "" + h(o.name.to_s) + "" }.join(", ") %>
    
  <% end %>

  <% if owner != object.namespace %>
    
      Originally defined in <%= object.namespace.type %>
        <%= linkify object, owner.relative_path(object.namespace) %>
    
  <% end %>

      yard-0.9.37/templates/default/method_details/html/source.erb000066400000000000000000000005551466601756300241410ustar00rootroot00000000000000
      
  
      
    
      
      <%= "\n\n\n" %><%= h format_lines(object) %>
      
          		
    
      
      # File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %><%= "\n\n" %><%= html_syntax_highlight object.source %>
      
          		
  
      

      yard-0.9.37/templates/default/method_details/setup.rb000066400000000000000000000003711466601756300226640ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :header, [:method_signature, T('docstring'), :source]
end

def source
  return if owner != object.namespace
  return if Tags::OverloadTag === object
  return if object.source.nil?
  erb(:source)
end
yard-0.9.37/templates/default/method_details/text/000077500000000000000000000000001466601756300221625ustar00rootroot00000000000000yard-0.9.37/templates/default/method_details/text/header.erb000066400000000000000000000004051466601756300241030ustar00rootroot00000000000000<%= title_align_right format_object_title(object) %>

<%= align_right "(Defined in: #{object.file})" %>
<% if object.aliases.size > 0 %>

<%= align_right "(Also known as: #{object.aliases.map {|o| o.name(true).to_s }.join(',')})" %>
<% end %>

<%= yieldall %>

yard-0.9.37/templates/default/method_details/text/method_signature.erb000066400000000000000000000004641466601756300262210ustar00rootroot00000000000000
<% if object.tags(:overload).size == 1 %>
<%= indent wrap(signature(object.tag(:overload))) %>
<% elsif object.tags(:overload).size > 1 %>
<% object.tags(:overload).each do |overload| %>
<%= indent wrap(signature(overload)) %>
<% end %>
<% else %>
<%= indent wrap(signature(object)) %>
<% end %>
<%= hr %>

yard-0.9.37/templates/default/method_details/text/setup.rb000066400000000000000000000003371466601756300236520ustar00rootroot00000000000000# frozen_string_literal: true
def init
  super
  sections.last.pop
end

def format_object_title(object)
  title = "Method: #{object.name(true)}"
  title += " (#{object.namespace})" unless object.namespace.root?
  title
end
yard-0.9.37/templates/default/module/000077500000000000000000000000001466601756300174765ustar00rootroot00000000000000yard-0.9.37/templates/default/module/dot/000077500000000000000000000000001466601756300202645ustar00rootroot00000000000000yard-0.9.37/templates/default/module/dot/child.erb000066400000000000000000000001201466601756300220320ustar00rootroot00000000000000<%= format_path object %> [label="{<%= yieldall.gsub("\n", '') %>}" rank=sink];
yard-0.9.37/templates/default/module/dot/dependencies.erb000066400000000000000000000002131466601756300234000ustar00rootroot00000000000000<% object.mixins(:instance).each do |obj| %>
  <%= format_path object %> -> <%= format_path obj %> [style=dotted arrowType=none];
<% end %>yard-0.9.37/templates/default/module/dot/header.erb000066400000000000000000000003021466601756300222010ustar00rootroot00000000000000subgraph cluster_<%= format_path object %> {
  label = "<%= h(object.name) unless object.path == "" %>"; labelloc=b;
  <% for obj in @modules %>
    <%= yieldall :object => obj %>
  <% end %>
}
yard-0.9.37/templates/default/module/dot/info.erb000066400000000000000000000011161466601756300217100ustar00rootroot00000000000000<%= object.type %> <%= h object.name %>
<% if options.full %>
|
<% object.attributes.each do |scope, list| %>
<% list.sort_by {|name, rw| name.to_s }.each do |name, rw| %>
<%= uml_visibility(rw.values.compact.first) %> <%= h (rw[:read]||rw[:write]).name(true).gsub(/=$/,'') %> [<%= 'R' if rw[:read] %><%= 'W' if rw[:write] %>]\l
<% end %>
<% end %>
|
<% method_listing.each do |obj| %>
<%= uml_visibility obj %> <%= h obj.name(true) %>
<%= h(" : #{obj.tag(:return).types.first}") if obj.has_tag?(:return) && obj.tag(:return).types && obj.tag(:return).types.size > 0 %>\l
<% end %>
<% end %>yard-0.9.37/templates/default/module/dot/setup.rb000066400000000000000000000006261466601756300217550ustar00rootroot00000000000000# frozen_string_literal: true
def init
  @modules = object.children.select {|o| o.type == :module }
  @classes = object.children.select {|o| o.type == :class }
  sections :child, [:info], :classes, [T('class')], :header, [T('module')], :dependencies
end

def dependencies
  return unless options.dependencies
  erb(:dependencies)
end

def classes
  @classes.map {|k| yieldall :object => k }.join("\n")
end
yard-0.9.37/templates/default/module/html/000077500000000000000000000000001466601756300204425ustar00rootroot00000000000000yard-0.9.37/templates/default/module/html/attribute_details.erb000066400000000000000000000006441466601756300246500ustar00rootroot00000000000000<% scopes(attr_listing) do |list, scope| %>
  
      
    
      <%= scope.to_s.capitalize %> Attribute Details
      
    <% list.each_with_index do |meth, i| %>
      <% rw = meth.attr_info %>
      
      <%= yieldall :object => meth, :owner => object, :index => i %>
    <% end %>
  
      
<% end %>
yard-0.9.37/templates/default/module/html/attribute_summary.erb000066400000000000000000000004071466601756300247150ustar00rootroot00000000000000<% groups(attr_listing, "Attribute") do |list, name| %>
  
      <%= name %> collapse
      
  
        
    <% list.each do |meth| %>
      <%= yieldall :item => meth %>
    <% end %>
  
      
<% end %>
yard-0.9.37/templates/default/module/html/box_info.erb000066400000000000000000000023231466601756300227370ustar00rootroot00000000000000
      
  <% if CodeObjects::ClassObject === object && object.superclass %>
  
      
    
      Inherits:
      
    
      
      <%= linkify object.superclass %>
      <% if object.superclass.name != :BasicObject %>
        
        
          
      • <%= linkify P(:Object) %>
        • 
          <% object.inheritance_tree.reverse.each_with_index do |obj, i| %>
            
          <% end %>
        
      
        show all
      <% end %>
    
      
  
      
  <% end %>

  <% [[:class, "Extended by"], [:instance, "Includes"]].each do |scope, name| %>
  <% if (mix = run_verifier(object.mixins(scope))).size > 0 %>
  
      
      
      <%= name %>:
      
      
      <%= mix.sort_by {|o| o.path }.map {|o| linkify(o) }.join(", ") %>
      
  
      
  <% end %>
  <% end %>

  <% if (mixed_into = mixed_into(object)).size > 0 %>
  
      
    
      Included in:
      
    
      <%= mixed_into.sort_by {|o| o.path }.map {|o| linkify(o) }.join(", ") %>
      
  
      
  <% end %>

  <% unless object.root? %>
  
      
    
      Defined in:
      
    
      <%= erb(:defines) %>
      
  
      
  <% end %>

      

yard-0.9.37/templates/default/module/html/children.erb000066400000000000000000000004431466601756300227250ustar00rootroot00000000000000
      Defined Under Namespace
      

      
  <% @inner.each do |name, list| %>
    <% if list.size > 0 %>
      <%= name.to_s.capitalize %>: <%= list.map {|child| linkify(child, child.name(true)) }.join(", ") %>
    <% end %>
  <% end %>

      
yard-0.9.37/templates/default/module/html/constant_summary.erb000066400000000000000000000010751466601756300245450ustar00rootroot00000000000000<% if constant_listing.size > 0 %>
  <% groups(constant_listing, "Constant") do |list, name| %>
    
      
      <%= name %>
      collapse
    
      

    
      
      <% list.each do |cnst| %>
        
      <%= cnst.name %> =
          <%= yieldall :object => cnst %>
        
      
        
      <%= format_constant cnst.value %>
      
      <% end %>
    
      
  <% end %>
<% end %>
yard-0.9.37/templates/default/module/html/defines.erb000066400000000000000000000002731466601756300225530ustar00rootroot00000000000000<%= object.file ? object.file : '(unknown)' %><% if object.files.size > 1 %>,
      
  <%= object.files[1..-1].map {|f| f.first }.join(",
       ") %>      
<% end %>yard-0.9.37/templates/default/module/html/header.erb000066400000000000000000000005621466601756300223670ustar00rootroot00000000000000
      <%= format_object_title(object) %>
  <% if object.has_tag?(:abstract) %>Abstract<% end %>
  <% if object.has_tag?(:deprecated) %>Deprecated<% end %>
  <% if object.has_tag?(:api) && object.tag(:api).text == 'private' %>Private<% end %>

      
yard-0.9.37/templates/default/module/html/inherited_attributes.erb000066400000000000000000000011721466601756300253560ustar00rootroot00000000000000<% found_method = false %>
<% inherited_attr_list do |superclass, attribs| %>
  <% if attr_listing.size == 0 && !found_method %>
      Instance Attribute Summary
      <% end %>
  <% found_method = true %>
  
      Attributes <%= superclass.type == :class ? 'inherited' : 'included' %> from <%= linkify superclass %>
      
  
      <%= attribs.map do |method|
      name = method.name(true).gsub(/=$/, '')
      if superclass.type == :module && object.instance_mixins.include?(superclass)
        name = "##{name}" unless name =~ /^#/
      end
      linkify(method, name)
    end.join(", ")
  %>
      
<% end %>
yard-0.9.37/templates/default/module/html/inherited_constants.erb000066400000000000000000000006351466601756300252070ustar00rootroot00000000000000<% found_const = false %>
<% inherited_constant_list do |superclass, consts| %>
  <% if constant_listing.size == 0 && !found_const %>
      Constant Summary
      <% end %>
  <% found_const = true %>
  
      Constants <%= superclass.type == :class ? 'inherited' : 'included' %>
     from <%= linkify superclass %>
      
  
      <%= consts.map {|c| linkify c }.join(", ") %>
      
<% end %>
yard-0.9.37/templates/default/module/html/inherited_methods.erb000066400000000000000000000020051466601756300246270ustar00rootroot00000000000000<% found_method = false %>
<% object.inheritance_tree(true)[1..-1].each do |superclass| %>
  <% next if superclass.is_a?(YARD::CodeObjects::Proxy) %>
  <% next if options.embed_mixins.size > 0 && options.embed_mixins_match?(superclass) != false %>
  <% meths = prune_method_listing(superclass.meths(:included => false, :inherited => false)) %>
  <% meths.reject! {|m| object.child(:scope => m.scope, :name => m.name) != nil } %>
  <% meths.reject! {|m| m.is_alias? || m.is_attribute? } %>
  <% next if meths.size == 0 %>
  <% if method_listing.size == 0 && !found_method %>
      Method Summary
      <% end %>
  <% found_method = true %>
  
      Methods <%= superclass.type == :class ? 'inherited' : 'included' %> from <%= linkify superclass %>
      
  
      <%=
    meths.sort_by {|o| o.name.to_s }.map do |m|
      name = m.name(true)
      name = name.gsub(/^#/,'') if superclass.type == :module && object.class_mixins.include?(superclass)
      linkify(m, name)
    end.join(", ")
  %>
      
<% end %>yard-0.9.37/templates/default/module/html/item_summary.erb000066400000000000000000000036561466601756300236610ustar00rootroot00000000000000
    • 
  
    <% if @item.tags(:overload).size == 1 %>
      <%= signature(@item.tag(:overload), true, false, !@item.attr_info) %>
    <% else %>
      <%= signature(@item, true, false, !@item.attr_info) %>
    <% end %>

    <% if @item.aliases.size > 0 %>
      (also: <%= @item.aliases.map {|o| h(o.name(true)) }.join(", ") %>)
    <% end %>
  
  <% if object != @item.namespace %>
    
      <%= @item.namespace.type == :class ? 'inherited' : (@item.scope == :class ? 'extended' : 'included') %>
      from <%= linkify @item, object.relative_path(@item.namespace) %>
    
  <% end %>
  <% if @item.constructor? %>
    constructor
  <% end %>
  <% if rw = @item.attr_info %>
    <% if !run_verifier([rw[:read]].compact).empty? && run_verifier([rw[:write]].compact).empty? %>
      readonly
    <% end %>
    <% if !run_verifier([rw[:write]].compact).empty? && run_verifier([rw[:read]].compact).empty? %>
      writeonly
    <% end %>
  <% end %>
  <% if @item.visibility != :public %><%= @item.visibility %><% end %>
  <% if @item.has_tag?(:abstract) %>abstract<% end %>
  <% if @item.has_tag?(:deprecated) %>deprecated<% end %>
  <% if @item.has_tag?(:api) && @item.tag(:api).text == 'private' %>private<% end %>

  <% if @item.has_tag?(:deprecated) %>
    Deprecated. <%= htmlify_line @item.tag(:deprecated).text %>
  <% else %>
    <%= htmlify_line docstring_summary(@item) %>
  <% end %>

      • 
yard-0.9.37/templates/default/module/html/method_details_list.erb000066400000000000000000000005061466601756300251550ustar00rootroot00000000000000<% scopes(method_listing(false)) do |list, scope| %>
  
      
    
      <%= scope.to_s.capitalize %> Method Details
      

    <% list.each_with_index do |meth, i| %>
      <%= yieldall :object => meth, :owner => object, :index => i %>
    <% end %>
  
      
<% end %>
yard-0.9.37/templates/default/module/html/method_summary.erb000066400000000000000000000005111466601756300241660ustar00rootroot00000000000000<% if method_listing.size > 0 %>
  <% groups(method_listing) do |list, name| %>
    
      
      <%= name %>
      collapse
    
      

    
        
      <% list.each do |meth| %>
        <%= yieldall :item => meth %>
      <% end %>
    
      
  <% end %>
<% end %>yard-0.9.37/templates/default/module/html/methodmissing.erb000066400000000000000000000007241466601756300240110ustar00rootroot00000000000000
      
  
      Dynamic Method Handling
      
  
      
    This class handles dynamic methods through the method_missing method
    <% if @mm.namespace != object %>
      in the class <%= linkify @mm, @mm.namespace.path %>
    <% end %>
  
      
  <% if @mm.namespace == object %>
    <%= yieldall :object => @mm, :index => 0 %>
  <% end %>

      
yard-0.9.37/templates/default/module/html/pre_docstring.erb000066400000000000000000000000211466601756300237670ustar00rootroot00000000000000
      Overview
      yard-0.9.37/templates/default/module/setup.rb000066400000000000000000000124511466601756300211660ustar00rootroot00000000000000# frozen_string_literal: true
include Helpers::ModuleHelper

def init
  sections :header, :box_info, :pre_docstring, T('docstring'), :children,
    :constant_summary, [T('docstring')], :inherited_constants,
    :attribute_summary, [:item_summary], :inherited_attributes,
    :method_summary, [:item_summary], :inherited_methods,
    :methodmissing, [T('method_details')],
    :attribute_details, [T('method_details')],
    :method_details_list, [T('method_details')]
end

def pre_docstring
  return if object.docstring.blank?
  erb(:pre_docstring)
end

def children
  @inner = [[:modules, []], [:classes, []]]
  object.children.each do |child|
    @inner[0][1] << child if child.type == :module
    @inner[1][1] << child if child.type == :class
  end
  @inner.map! {|v| [v[0], run_verifier(v[1].sort_by {|o| o.name.to_s })] }
  return if (@inner[0][1].size + @inner[1][1].size) == 0
  erb(:children)
end

def methodmissing
  mms = object.meths(:inherited => true, :included => true)
  @mm = mms.find {|o| o.name == :method_missing && o.scope == :instance }
  erb(:methodmissing) if @mm
end

def method_listing(include_specials = true)
  return @smeths ||= method_listing.reject {|o| special_method?(o) } unless include_specials
  return @meths if defined?(@meths) && @meths
  @meths = object.meths(:inherited => false, :included => !options.embed_mixins.empty?)
  unless options.embed_mixins.empty?
    @meths = @meths.reject {|m| options.embed_mixins_match?(m.namespace) == false }
  end
  @meths = sort_listing(prune_method_listing(@meths))
  @meths
end

def special_method?(meth)
  return true if meth.name(true) == '#method_missing'
  return true if meth.constructor?
  false
end

def attr_listing
  return @attrs if defined?(@attrs) && @attrs
  @attrs = []
  object.inheritance_tree(true).each do |superclass|
    next if superclass.is_a?(CodeObjects::Proxy)
    next if !options.embed_mixins.empty? &&
            !options.embed_mixins_match?(superclass)
    [:class, :instance].each do |scope|
      superclass.attributes[scope].each do |_name, rw|
        attr = prune_method_listing([rw[:read], rw[:write]].compact, false).first
        @attrs << attr if attr
      end
    end
    break if options.embed_mixins.empty?
  end
  @attrs = sort_listing(@attrs)
end

def constant_listing
  return @constants if defined?(@constants) && @constants
  @constants = object.constants(:included => false, :inherited => false)
  @constants += object.cvars
  @constants = run_verifier(@constants)
  @constants
end

def sort_listing(list)
  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
end

def inherited_attr_list
  object.inheritance_tree(true)[1..-1].each do |superclass|
    next if superclass.is_a?(YARD::CodeObjects::Proxy)
    next if !options.embed_mixins.empty? && options.embed_mixins_match?(superclass) != false
    attribs = superclass.attributes[:instance]
    attribs = attribs.select {|name, _rw| object.child(:scope => :instance, :name => name).nil? }
    attribs = attribs.sort_by {|args| args.first.to_s }.map {|_n, m| m[:read] || m[:write] }
    attribs = prune_method_listing(attribs, false)
    yield superclass, attribs unless attribs.empty?
  end
end

def inherited_constant_list
  object.inheritance_tree(true)[1..-1].each do |superclass|
    next if superclass.is_a?(YARD::CodeObjects::Proxy)
    next if !options.embed_mixins.empty? && options.embed_mixins_match?(superclass) != false
    consts = superclass.constants(:included => false, :inherited => false)
    consts = consts.select {|const| object.child(:type => :constant, :name => const.name).nil? }
    consts = consts.sort_by {|const| const.name.to_s }
    consts = run_verifier(consts)
    yield superclass, consts unless consts.empty?
  end
end

def docstring_full(obj)
  docstring = obj.tags(:overload).size == 1 && obj.docstring.empty? ?
    obj.tag(:overload).docstring : obj.docstring

  if docstring.summary.empty? && obj.tags(:return).size == 1 && obj.tag(:return).text
    docstring = Docstring.new(obj.tag(:return).text.gsub(/\A([a-z])/, &:upcase).strip)
  end

  docstring
end

def docstring_summary(obj)
  docstring_full(obj).summary
end

def groups(list, type = "Method")
  groups_data = object.groups
  if groups_data
    list.each {|m| groups_data |= [m.group] if m.group && owner != m.namespace }
    others = list.select {|m| !m.group || !groups_data.include?(m.group) }
    groups_data.each do |name|
      items = list.select {|m| m.group == name }
      yield(items, name) unless items.empty?
    end
  else
    others = []
    group_data = {}
    list.each do |itm|
      if itm.group
        (group_data[itm.group] ||= []) << itm
      else
        others << itm
      end
    end
    group_data.each {|group, items| yield(items, group) unless items.empty? }
  end

  return if others.empty?
  if others.first.respond_to?(:scope)
    scopes(others) {|items, scope| yield(items, "#{scope.to_s.capitalize} #{type} Summary") }
  else
    yield(others, "#{type} Summary")
  end
end

def scopes(list)
  [:class, :instance].each do |scope|
    items = list.select {|m| m.scope == scope }
    yield(items, scope) unless items.empty?
  end
end

def mixed_into(object)
  unless globals.mixed_into
    globals.mixed_into = {}
    list = run_verifier Registry.all(:class, :module)
    list.each {|o| o.mixins.each {|m| (globals.mixed_into[m.path] ||= []) << o } }
  end

  globals.mixed_into[object.path] || []
end
yard-0.9.37/templates/default/module/text/000077500000000000000000000000001466601756300204625ustar00rootroot00000000000000yard-0.9.37/templates/default/module/text/children.erb000066400000000000000000000003301466601756300227400ustar00rootroot00000000000000Defined Under Namespace:
------------------------

<% @inner.each do |name, list| %>
<% if list.size > 0 %>
<% text = list.map {|c| c.name }.join(", ") + " (#{name})" %>
<%= indent(wrap(text)) %>

<% end %>
<% end %>yard-0.9.37/templates/default/module/text/class_meths_list.erb000066400000000000000000000002161466601756300245130ustar00rootroot00000000000000<% if class_meths.size > 0 %>
Class methods:
--------------

<%= indent wrap(class_meths.map {|o| o.name.to_s }.join(", "), 68) %>


<% end %>yard-0.9.37/templates/default/module/text/extends.erb000066400000000000000000000002071466601756300226250ustar00rootroot00000000000000<% if object.mixins(:class).size > 0 %>
Extended by:
------------

<%= indent wrap(object.mixins(:class).join(", "), 68) %>


<% end %>yard-0.9.37/templates/default/module/text/header.erb000066400000000000000000000001231466601756300224000ustar00rootroot00000000000000<%= title_align_right format_object_title(object) %>

<%= yieldall %>

<%= hr %>


yard-0.9.37/templates/default/module/text/includes.erb000066400000000000000000000002071466601756300227610ustar00rootroot00000000000000<% if object.mixins(:instance).size > 0 %>
Includes:
---------

<%= indent wrap(object.mixins(:instance).join(", "), 68) %>


<% end %>yard-0.9.37/templates/default/module/text/instance_meths_list.erb000066400000000000000000000002321466601756300252100ustar00rootroot00000000000000<% if instance_meths.size > 0 %>
Instance methods:
-----------------

<%= indent wrap(instance_meths.map {|o| o.name.to_s }.join(", "), 68) %>


<% end %>yard-0.9.37/templates/default/module/text/setup.rb000066400000000000000000000005161466601756300221510ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :header, [T('docstring')], :children, :includes, :extends,
    :class_meths_list, :instance_meths_list
end

def class_meths
  @classmeths ||= method_listing.select {|o| o.scope == :class }
end

def instance_meths
  @instmeths ||= method_listing.select {|o| o.scope == :instance }
end
yard-0.9.37/templates/default/onefile/000077500000000000000000000000001466601756300176325ustar00rootroot00000000000000yard-0.9.37/templates/default/onefile/html/000077500000000000000000000000001466601756300205765ustar00rootroot00000000000000yard-0.9.37/templates/default/onefile/html/files.erb000066400000000000000000000001511466601756300223670ustar00rootroot00000000000000<% @files.each do |file| %>
  <% @file = file %>
  
      <%= file.title %>
      
  <%= diskfile %>
<% end %>yard-0.9.37/templates/default/onefile/html/headers.erb000066400000000000000000000003141466601756300227010ustar00rootroot00000000000000

yard-0.9.37/templates/default/onefile/html/layout.erb000066400000000000000000000010311466601756300226000ustar00rootroot00000000000000

  
    
    <%= defined?(@title) ? @title : '' %>
    <%= erb(:headers) %>
  
  
    
      
      
      <%= defined?(@title) ? @title : '' %>
      
      <%= yieldall %>
    
      

    <%= erb(:footer) %>
  

yard-0.9.37/templates/default/onefile/html/readme.erb000066400000000000000000000001071466601756300225230ustar00rootroot00000000000000
      
  <%= htmlify(parse_top_comments_from_file) %>

      yard-0.9.37/templates/default/onefile/html/setup.rb000066400000000000000000000030661466601756300222700ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/layout/html')
include YARD::Parser::Ruby::Legacy

def init
  override_serializer
  @object = YARD::Registry.root
  @files.shift
  @objects.delete(YARD::Registry.root)
  @objects.unshift(YARD::Registry.root)
  sections :layout, [:readme, :files, :all_objects]
end

def all_objects
  @objects.map {|obj| obj.format(options) }.join("\n")
end

def layout
  layout = Object.new.extend(T('layout'))
  @css_data = layout.stylesheets.map {|sheet| read_asset(sheet) }.join("\n")
  @js_data = layout.javascripts.map {|script| read_asset(script) }.join("")

  erb(:layout)
end

def read_asset(file)
  file = T('fulldoc').find_file(file)
  return unless file
  data = File.read(file)
  superfile = self.class.find_nth_file('fulldoc', 2)
  data.gsub!('{{{__super__}}}', superfile ? IO.read(superfile) : "")
  data
end

private

def parse_top_comments_from_file
  return unless defined?(@readme) && @readme
  return @readme.contents unless @readme.filename =~ /\.rb$/
  data = ""
  tokens = TokenList.new(@readme.contents)
  tokens.each do |token|
    break unless token.is_a?(RubyToken::TkCOMMENT) || token.is_a?(RubyToken::TkNL)
    data += (token.text[/\A#\s{0,1}(.*)/, 1] || "\n")
  end
  YARD::Docstring.new(data)
end

def override_serializer
  return if @serializer.nil?
  class << @serializer
    define_method(:serialize) do |object, data|
      return unless object == 'index.html'
      super(object, data)
    end

    define_method(:serialized_path) do |object|
      return object if object.is_a?(String)
      'index.html'
    end
  end
end
yard-0.9.37/templates/default/root/000077500000000000000000000000001466601756300171745ustar00rootroot00000000000000yard-0.9.37/templates/default/root/dot/000077500000000000000000000000001466601756300177625ustar00rootroot00000000000000yard-0.9.37/templates/default/root/dot/child.erb000066400000000000000000000001331466601756300215340ustar00rootroot00000000000000<% if inner = yieldall.gsub("\n", '') %>
Root [label="{<%= inner %>}" rank=sink];
<% end %>yard-0.9.37/templates/default/root/dot/setup.rb000066400000000000000000000001411466601756300214430ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/module/dot')

def format_path(_object)
  ""
end
yard-0.9.37/templates/default/root/html/000077500000000000000000000000001466601756300201405ustar00rootroot00000000000000yard-0.9.37/templates/default/root/html/setup.rb000066400000000000000000000000771466601756300216310ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/module/html')
yard-0.9.37/templates/default/tags/000077500000000000000000000000001466601756300171475ustar00rootroot00000000000000yard-0.9.37/templates/default/tags/html/000077500000000000000000000000001466601756300201135ustar00rootroot00000000000000yard-0.9.37/templates/default/tags/html/example.erb000066400000000000000000000006051466601756300222410ustar00rootroot00000000000000<% if object.has_tag?(:example) %>
  
      
    
      Examples:
      
    <% object.tags(:example).each do |tag| %>
      <% unless tag.name.empty? %>
        
      <%= htmlify_line(tag.name) %>
      
      <% end %>
      
      <%= html_syntax_highlight(tag.text) %>
      
    <% end %>
  
      
<% end %>yard-0.9.37/templates/default/tags/html/index.erb000066400000000000000000000000531466601756300217120ustar00rootroot00000000000000
      
  <%= yieldall %>

      yard-0.9.37/templates/default/tags/html/option.erb000066400000000000000000000016531466601756300221220ustar00rootroot00000000000000<% if object.has_tag?(:option) && object.respond_to?(:parameters) %>
  <% object.parameters.each do |param, default| %>
    <% tags = object.tags(:option).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
    <% next if tags.empty? %>
    
      Options Hash (<%= param %>):
      
    
        
      <% for tag in tags %>
        
      • 
          <%= tag.pair.name %>
          <%= format_types(tag.pair.types || ['Object']) %>
          
            <% if tag.pair.defaults %>
              — default:
              <%= tag.pair.defaults.map {|t| "#{h t}" }.join(", ") %>
            <% end %>
          
          <% if tag.pair.text && tag.pair.text =~ /\S/ %>
            — <%= htmlify_line(tag.pair.text) %>
          <% end %>
        
        • 
      <% end %>
    
      
  <% end %>
<% end %>
yard-0.9.37/templates/default/tags/html/overload.erb000066400000000000000000000010461466601756300224210ustar00rootroot00000000000000<% if object.tags(:overload).size == 1 %>
  <%= yieldall :object => object.tag(:overload) %>
<% elsif object.has_tag?(:overload) && object.tags(:overload).any? {|o| !o.docstring.blank? } %>
  
      Overloads:
      
  
        
    <% object.tags(:overload).each do |overload| %>
      <% next if overload.docstring.blank? %>
      
      • 
        <%= signature(overload, false, false) %>
        <%= yieldall :object => overload %>
      
        • 
    <% end %>
  
      
<% end %>yard-0.9.37/templates/default/tags/html/see.erb000066400000000000000000000003171466601756300213620ustar00rootroot00000000000000<% if object.has_tag?(:see) %>
  
      See Also:
      
  
        
    <% for tag in object.tags(:see) %>
      
      • <%= linkify(tag.name, tag.text) %>
        • 
    <% end %>
  
      
<% end %>yard-0.9.37/templates/default/tags/html/tag.erb000066400000000000000000000014771466601756300213710ustar00rootroot00000000000000
      <%= (defined?(@label) && @label) ? @label : YARD::Tags::Library.labels[@name] %>:
      

        
  <% object.tags(@name).each do |tag| %>
    
      • 
      <% unless @no_names %>
        <%= h tag.name %>
      <% end %>
      <% unless @no_types %>
        <%= format_types(tag.types) %>
      <% end %>
      <% if @name == :param && (o=object.parameters.find {|a| [tag.name.to_s, tag.name.to_s + ":"].include?(a[0]) }) && o[1] %>
        (defaults to: <%= h o[1] %>)
      <% end %>
      <% if tag.text && !tag.text.empty? %>
        <% unless (@no_types || tag.types.nil? || tag.types.empty?) && @no_names %>—<% end %>
        <%= htmlify_line(tag.text) %>
      <% end %>
    
        • 
  <% end %>

      
yard-0.9.37/templates/default/tags/setup.rb000066400000000000000000000025221466601756300206350ustar00rootroot00000000000000# frozen_string_literal: true
def init
  tags = Tags::Library.visible_tags - [:abstract, :deprecated, :note, :todo]
  create_tag_methods(tags - [:example, :option, :overload, :see])
  sections :index, tags.map {|t| t.to_s.tr('.', '_').to_sym }
  sections.any(:overload).push(T('docstring'))
end

def return
  if object.type == :method
    return if object.constructor?
    return if object.tags(:return).size == 1 && object.tag(:return).types == ['void']
  end
  tag(:return)
end

def param
  tag(:param) if object.type == :method
end

private

def tag(name, opts = nil)
  return unless object.has_tag?(name)
  opts ||= options_for_tag(name)
  @no_names = opts[:no_names] ? true : false
  @no_types = opts[:no_types] ? true : false
  @name = name
  out = erb('tag')
  @no_names = nil
  @no_types = nil
  out
end

def create_tag_methods(tags)
  tags.each do |tag|
    tag_meth = tag.to_s.tr('.', '_')
    next if respond_to?(tag_meth)
    instance_eval(<<-eof, __FILE__, __LINE__ + 1)
      def #{tag_meth}; tag(#{tag.inspect}) end
    eof
  end
end

def options_for_tag(tag)
  opts = {:no_types => true, :no_names => true}
  case Tags::Library.factory_method_for(tag)
  when :with_types
    opts[:no_types] = false
  when :with_types_and_name
    opts[:no_types] = false
    opts[:no_names] = false
  when :with_name
    opts[:no_names] = false
  end
  opts
end
yard-0.9.37/templates/default/tags/text/000077500000000000000000000000001466601756300201335ustar00rootroot00000000000000yard-0.9.37/templates/default/tags/text/example.erb000066400000000000000000000004301466601756300222550ustar00rootroot00000000000000<% if object.has_tag?(:example) %>

Examples:
---------

<% object.tags(:example).each_with_index do |tag, i| %>
<%= indent("# " + tag.name + "\n") if tag.name %>
<%= indent(format_source(tag.text)) + "\n" %>
<%= "\n" if i < object.tags(:example).size - 1 %>
<% end %>
<% end %>

yard-0.9.37/templates/default/tags/text/index.erb000066400000000000000000000000201466601756300217240ustar00rootroot00000000000000<%= yieldall %>
yard-0.9.37/templates/default/tags/text/option.erb000066400000000000000000000011521466601756300221340ustar00rootroot00000000000000<% if object.has_tag?(:option) %>
<% object.parameters.each do |param, default| %>
<% tags = object.tags(:option).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
<% next if tags.empty? %>
Options Hash (<%= param %>):
--------------<%= hr(param.to_s.length) %>--

<% for tag in tags %>
<% text = "" %>
<% text += format_types(tag.pair.types || ['Object']) %>
<% text += " " + tag.pair.name.to_s %>
<% if tag.pair.defaults %>
<% text += " - default: " + tag.pair.defaults.join(", ") %>
<% end %>
<% text += " - " + tag.pair.text if tag.pair.text %>
<%= indent(wrap(text)) %>

<% end %>
<% end %>
<% end %>
yard-0.9.37/templates/default/tags/text/overload.erb000066400000000000000000000005731466601756300224450ustar00rootroot00000000000000<% if object.tags(:overload).size == 1 %>
<%= wrap(yieldall(:object => object.tag(:overload))) %>
<% elsif object.has_tag?(:overload) %>
Overloads:
----------

<% object.tags(:overload).each do |overload| %>
<% if overload.tags.size > 0 %>
<%= hr %>

<%= indent signature(overload) %>

<%= hr %>

<%= indent(wrap(yieldall(:object => overload))) %>

<% end %>
<% end %>
<% end %>
yard-0.9.37/templates/default/tags/text/see.erb000066400000000000000000000003421466601756300214000ustar00rootroot00000000000000<% if object.has_tag?(:see) %>
See Also:
---------

<% for tag in object.tags(:see) %>
<% text = "- " + tag.name %>
<% text += " - " + tag.text if tag.text && !tag.text.empty? %>
<%= indent(wrap(text)) %>
<% end %>
<% end %>

yard-0.9.37/templates/default/tags/text/tag.erb000066400000000000000000000007051466601756300214020ustar00rootroot00000000000000<% title = (defined?(@label) && @label) ? @label : YARD::Tags::Library.labels[@name] %>
<%= title %>:
<%= hr(title.length) %>-

<% object.tags(@name).each do |tag| %>
<% text = "" %>
<% text += format_types(tag.types) + " " unless @no_types || tag.types.nil? %>
<% text += tag.name.to_s + " " unless @no_names %>
<% text += "- " unless @no_names && @no_types %>
<% text += tag.text if tag.text && !tag.text.empty? %>
<%= indent wrap(text) %>

<% end %>
yard-0.9.37/templates/guide/000077500000000000000000000000001466601756300156625ustar00rootroot00000000000000yard-0.9.37/templates/guide/class/000077500000000000000000000000001466601756300167675ustar00rootroot00000000000000yard-0.9.37/templates/guide/class/html/000077500000000000000000000000001466601756300177335ustar00rootroot00000000000000yard-0.9.37/templates/guide/class/html/setup.rb000066400000000000000000000000751466601756300214220ustar00rootroot00000000000000# frozen_string_literal: true
include T('guide/module/html')
yard-0.9.37/templates/guide/docstring/000077500000000000000000000000001466601756300176565ustar00rootroot00000000000000yard-0.9.37/templates/guide/docstring/html/000077500000000000000000000000001466601756300206225ustar00rootroot00000000000000yard-0.9.37/templates/guide/docstring/html/setup.rb000066400000000000000000000001021466601756300223000ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/docstring/html')
yard-0.9.37/templates/guide/fulldoc/000077500000000000000000000000001466601756300173125ustar00rootroot00000000000000yard-0.9.37/templates/guide/fulldoc/html/000077500000000000000000000000001466601756300202565ustar00rootroot00000000000000yard-0.9.37/templates/guide/fulldoc/html/css/000077500000000000000000000000001466601756300210465ustar00rootroot00000000000000yard-0.9.37/templates/guide/fulldoc/html/css/style.css000066400000000000000000000122311466601756300227170ustar00rootroot00000000000000body { color: #3e4349; font-family: Georgia, serif; font-size: 17px; margin: 0; }
h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000; font-family: Georgia, serif; }
h1 { color: #040; }
h2 { color: #060; }
h3 { color: #070; }
h4 { color: #080; }
h5 { color: #090; }
#sidebar h2 { color: #2f2; }
strong { color: #000; }
.object_link, tt, code { font-family: 'Consolas', 'BitStream Vera Sans Mono', monospace; font-size: 14px; }
.method_header .path, .module_header .path { font-family: 'Consolas', 'BitStream Vera Sans Mono', monospace; }
.method_header .path.space, .module_header .path.space { padding-left: 5px; }
.method_header { font-size: 0.95em; }
.method_body { margin-left: 2em; }
.tags h3, .tags h4 { font-size: 0.9em; font-weight: bold; color: #3e4349; }
.tags .param .name { font-style: italic; }
.tags .option .name { font-family: monospace; color: #000; font-size: 0.8em; }
.tags .option .type, .tags .param .type { font-size: 10px; vertical-align: super; }
.tags .option .type tt, .tags .param .type tt,
.tags .option .type tt .object_link, .tags .param .type tt .object_link { font-size: 10px; }
.module_methods { margin-left: 2em; }
.method_header .since, .module_header .since { font-size: 0.75em; color: #888; vertical-align: super; }
ul { list-style: square; }
.inline { display: inline; }
.inline p:first-child { display: inline; }
.inline p { font-family: Georgia, serif; font-size: 16px; color: #3e4349; }
#filecontents table, .docstring table { border-collapse: collapse; }
#filecontents table th, #filecontents table td,
.docstring table th, .docstring table td { border: 1px solid #ccc; padding: 8px; padding-right: 17px; }
#filecontents table tr:nth-child(odd),
.docstring table tr:nth-child(odd) { background: #eee; }
#filecontents table tr:nth-child(even),
.docstring table tr:nth-child(even) { background: #fff; }
#filecontents table th, .docstring table th { background: #fff; }
.docstring .note { margin: 1em 0; }
.docstring h1, .docstring h2, .docstring h3, .docstring h4 { padding: 0; border: 0; border-bottom: 1px dotted #bbb; }
.docstring h1 { font-size: 1.2em; }
.docstring h2 { font-size: 1.1em; }
.docstring h3 { font-size: 1.1em; }
.docstring h4 { font-size: 1.0em; font-weight: bold; }
.docstring h5 { font-size: 1.0em; font-weight: bold; }
.docstring h6 { font-size: 1.0em; font-weight: bold; }
#filecontents strong { font-weight: normal; color: #000; }
.readonly { font-size: 0.75em; color: #888; vertical-align: super; }
.rdoc-term { padding-right: 25px; font-weight: bold; }
.rdoc-list p { margin: 0; padding: 0; margin-bottom: 4px; }

#page { width: 940px; margin: 0px auto; }
#top_nav { background: #7d0; padding: 8px 12px; }
#inner_nav { width: 940px; margin: 0px auto; }
#inner_nav a { border: 0; text-decoration: none; color: #777; }
#inner_nav a:hover { color: #222; }
#top_nav .links { display: block; float: right; }
#content { margin-left: 30px; width: 660px; float: left; }
#sidebar { float: left; width: 200px; float: left; padding: 18px 10px; padding-top: 0; }
#sidebar h2 { font-weight: 100; color: #3e4349; font-size: 1.45em; }
#sidebar ol { padding-left: 16px; margin-left: 0; list-style: square; }
#sidebar a { color: #468; text-decoration: none; }
#sidebar a:hover { color: #000; background: #8e0; padding: 4px; }
#sidebar ol.top { padding-left: 0; margin-left: 0; list-style: none; }
#sidebar a { font-size: 0.9em; }
#footer { margin: 0 auto; width: 940px; text-align: center; margin-top: 30px; padding: 20px 0; color: #888; font-size: 0.8em; border-top: 1px dotted #bbb; }
#footer a { color: #444; }
#links strong { font-size: 0.95em; font-weight: normal; color: #000; }

a { color: #268; text-decoration: none; }
a:hover { color: #6ae; }

/* syntax highlighting */
.source_code { display: none; padding: 3px 8px; border-left: 8px solid #ddd; margin-top: 5px; }
#filecontents pre.code, .docstring pre.code, .source_code pre { font-family: monospace; }
#filecontents pre.code, .docstring pre.code { display: block; }
.source_code .lines { padding-right: 12px; color: #555; text-align: right; }
#filecontents pre.code, .docstring pre.code,
.tags pre.example {
  font-size: 0.9em;
  padding: 7px 30px;
  margin: 15px -30px;
  margin-left: -30px;
  background: #eee;
  line-height: 1.3em;
  font-family: 'Consolas', 'BitStream Vera Sans Mono', monospace;
 }
pre.code { color: #3e4349; }
pre.code .info.file { color: #555; }
pre.code .val { color: #036A07; }
pre.code .tstring_content,
pre.code .heredoc_beg, pre.code .heredoc_end,
pre.code .qwords_beg, pre.code .qwords_end,
pre.code .tstring, pre.code .dstring { color: #036A07; }
pre.code .fid, pre.code .rubyid_new, pre.code .rubyid_to_s,
pre.code .rubyid_to_sym, pre.code .rubyid_to_f,
pre.code .dot + pre.code .id,
pre.code .rubyid_to_i pre.code .rubyid_each { color: #0085FF; }
pre.code .comment { color: #0066FF; }
pre.code .const, pre.code .constant { color: #585CF6; }
pre.code .symbol { color: #C5060B; }
pre.code .kw,
pre.code .label,
pre.code .rubyid_require,
pre.code .rubyid_extend,
pre.code .rubyid_include { color: #0000FF; }
pre.code .ivar { color: #318495; }
pre.code .gvar,
pre.code .rubyid_backref,
pre.code .rubyid_nth_ref { color: #6D79DE; }
pre.code .regexp, .dregexp { color: #036A07; }
pre.code a { border-bottom: 1px dotted #bbf; }
yard-0.9.37/templates/guide/fulldoc/html/js/000077500000000000000000000000001466601756300206725ustar00rootroot00000000000000yard-0.9.37/templates/guide/fulldoc/html/js/app.js000066400000000000000000000021161466601756300220100ustar00rootroot00000000000000function generateTOC() {
  if ($('#filecontents').length == 0) return;
  var _toc = $('
        ');
  var show = false;
  var toc = _toc;
  var counter = 0;
  var tags = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
  for (i in tags) { tags[i] = '#filecontents > ' + tags[i] }
  var lastTag = parseInt(tags[0][1]);
  $(tags.join(', ')).each(function() {
    if (this.id == "filecontents") return;
    show = true;
    var thisTag = parseInt(this.tagName[1]);
    if (this.id.length == 0) {
      var proposedId = $(this).text().replace(/[^a-z0-9-]/ig, '_');
      if ($('#' + proposedId).length > 0) proposedId += counter++;
      this.id = proposedId;
    }
    if (thisTag > lastTag) {
      for (var i = 0; i < thisTag - lastTag; i++) {
        var tmp = $('
          '); toc.append(tmp); toc = tmp;
      }
    }
    if (thisTag < lastTag) {
      for (var i = 0; i < lastTag - thisTag; i++) toc = toc.parent();
    }
    toc.append('
        1. ' + $(this).text() + '
          2. ');
    lastTag = thisTag;
  });
  if (!show) return;
  $('#toc').append()
  $('#toc').append(_toc);
}
yard-0.9.37/templates/guide/fulldoc/html/setup.rb000066400000000000000000000035461466601756300217530ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/fulldoc/html')

module OverrideFileLinks
  def resolve_links(text)
    result = ''
    log.enter_level(Logger::ERROR) { result = super }
    result
  end

  def url_for(object, *args)
    if CodeObjects::ExtraFileObject === object && object == options.readme
      'index.html'
    else
      super
    end
  end
end

Template.extra_includes << OverrideFileLinks

def init
  class << options.serializer
    define_method(:serialized_path) do |object|
      if CodeObjects::ExtraFileObject === object
        super(object).sub(/^file\./, '').downcase
      else
        super(object)
      end
    end
  end if options.serializer

  return serialize_onefile if options.onefile

  generate_assets
  options.delete(:objects)
  options.files.each {|file| serialize_file(file) }
  serialize_file(options.readme) if options.readme
end

def generate_assets
  %w(js/jquery.js js/app.js css/style.css css/common.css).each do |file|
    asset(file, file(file, true))
  end
end

def serialize_file(file)
  index = options.files.index(file)
  outfile = file.name.downcase + '.html'
  options.file = file
  if file.attributes[:namespace]
    options.object = Registry.at(file.attributes[:namespace])
  end
  options.object ||= Registry.root

  if file == options.readme
    serialize_index(options)
  else
    serialize_index(options) if !options.readme && index == 0
    Templates::Engine.with_serializer(outfile, options.serializer) do
      T('layout').run(options)
    end
  end
  options.delete(:file)
end

def serialize_onefile
  layout = Object.new.extend(T('layout'))
  options.css_data = layout.stylesheets.map {|sheet| file(sheet, true) }.join("\n")
  options.js_data = layout.javascripts.map {|script| file(script, true) }.join("")
  Templates::Engine.with_serializer('onefile.html', options.serializer) do
    T('onefile').run(options)
  end
end
yard-0.9.37/templates/guide/layout/000077500000000000000000000000001466601756300171775ustar00rootroot00000000000000yard-0.9.37/templates/guide/layout/html/000077500000000000000000000000001466601756300201435ustar00rootroot00000000000000yard-0.9.37/templates/guide/layout/html/layout.erb000066400000000000000000000041341466601756300221540ustar00rootroot00000000000000

  
    <%= erb(:headers) %>
		
  
  
		
          
			
          
				<% if options.readme != options.file && options.title %>
					<%= options.title %>: <%= @page_title %>
					
						<% links = [@prevfile ? link_file(@prevfile, '←') : nil,
						            link_file('index.html', '↑'),
									@nextfile ? link_file(@nextfile, '→') : nil].compact %>
						<%= links.join(" ") %>
					
				<% end %>
			
          
		
          
		
          
			
	    
          <%= yieldall %>
          
		
          
		
          
    <%= erb(:footer) %>
  

yard-0.9.37/templates/guide/layout/html/setup.rb000066400000000000000000000010551466601756300216310ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/layout/html')

def init
  super

  @topfile = options.readme
  if options.files
    if @topfile
      @toptitle = @topfile.attributes[:title] || "Documentation Overview"
    end
    @page_title = @file == options.readme ? options.title : @file.title

    index = options.files.index(@file)
    if index
      @prevfile = index > 0 ? (options.files[index - 1] || options.readme) : nil
      @nextfile = options.files[index + 1]
    end
  end
end

def diskfile
  options.including_object = @object
  super
end
yard-0.9.37/templates/guide/method/000077500000000000000000000000001466601756300171425ustar00rootroot00000000000000yard-0.9.37/templates/guide/method/html/000077500000000000000000000000001466601756300201065ustar00rootroot00000000000000yard-0.9.37/templates/guide/method/html/header.erb000066400000000000000000000024331466601756300220320ustar00rootroot00000000000000
          
  <% if options.in_module %>
    <% if object.constructor? %>
      self.new(<%= format_args(object) %>) <%= format_block(object) %>
    <% else %>
      <%= object.scope == :class ? 'self.' : '' %><%= object.is_attribute? ? object.name.to_s.sub(/=$/, '') : object.name %><% if object.is_attribute? %>
        <% rw = object.attr_info %>
        <% if rw && rw[:read] && !rw[:write] %>readonly
        <% elsif rw && !rw[:read] && rw[:write] %>writeonly
        <% end %>
        <% else %>(<%= format_args(object) %>) <%= format_block(object) %><% end %>
    <% end %>
  <% else %>
    def <%= options.including_object.relative_path(object.namespace) %><%= object.send(:sep) %><%= object.name %>(<%= format_args(object) %>) <%= format_block(object) %>
  <% end %>
  <% if object.has_tag?(:since) && object.namespace.tag(:since) != object.tag(:since) %>since <%= object.tag(:since).text %><% end %>

          

          <%= yieldall %>
          yard-0.9.37/templates/guide/method/html/setup.rb000066400000000000000000000010241466601756300215700ustar00rootroot00000000000000# frozen_string_literal: true
def init
  sections :header, [T('docstring')]
end

def format_args(object)
  return if object.parameters.nil?
  params = object.parameters
  if object.has_tag?(:yield) || object.has_tag?(:yieldparam)
    params.reject! do |param|
      param[0].to_s[0, 1] == "&" &&
        !object.tags(:param).any? {|t| t.name == param[0][1..-1] }
    end
  end

  if params.empty?
    ""
  else
    args = params.map {|n, v| v ? "#{h n} = #{h v}" : "" + n.to_s + "" }.join(", ")
    args
  end
end
yard-0.9.37/templates/guide/module/000077500000000000000000000000001466601756300171475ustar00rootroot00000000000000yard-0.9.37/templates/guide/module/html/000077500000000000000000000000001466601756300201135ustar00rootroot00000000000000yard-0.9.37/templates/guide/module/html/header.erb000066400000000000000000000005531466601756300220400ustar00rootroot00000000000000
          
  <%= object.type %> <%= object.namespace == Registry.root ? '' : object.namespace.path + '::' %><%= object.name %>
  <% if object.has_tag?(:since) %>since <%= object.tag(:since).text %><% end %>

          

          
  <%= yieldall %>

          yard-0.9.37/templates/guide/module/html/method_list.erb000066400000000000000000000002411466601756300231150ustar00rootroot00000000000000
          
  <% @meths.each_with_index do |meth, i| %>
    <%= yieldall(:object => meth, :index => i, :in_module => true) %>
  <% end %>

          yard-0.9.37/templates/guide/module/html/setup.rb000066400000000000000000000013501466601756300215770ustar00rootroot00000000000000# frozen_string_literal: true
include Helpers::ModuleHelper

def init
  sections :header, [T('docstring')], :method_list, [T('method')]
end

def method_list
  @meths = object.meths(:inherited => false, :included => false)
  cons = @meths.find(&:constructor?)
  @meths = @meths.reject {|meth| special_method?(meth) }
  @meths = sort_listing(prune_method_listing(@meths, false))
  @meths.unshift(cons) if cons
  erb(:method_list)
end

def sort_listing(list)
  list.sort_by {|o| [o.scope.to_s, o.name.to_s.downcase] }
end

def special_method?(meth)
  return true if meth.writer? && meth.attr_info[:read]
  return true if meth.name(true) == 'new'
  return true if meth.name(true) == '#method_missing'
  return true if meth.constructor?
  false
end
yard-0.9.37/templates/guide/onefile/000077500000000000000000000000001466601756300173035ustar00rootroot00000000000000yard-0.9.37/templates/guide/onefile/html/000077500000000000000000000000001466601756300202475ustar00rootroot00000000000000yard-0.9.37/templates/guide/onefile/html/files.erb000066400000000000000000000001151466601756300220400ustar00rootroot00000000000000<% @files.each do |file| %>
  <% @file = file %>
  <%= diskfile %>
<% end %>
yard-0.9.37/templates/guide/onefile/html/setup.rb000066400000000000000000000001611466601756300217320ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/onefile/html')

def init
  sections :layout, [:toc, :files]
end
yard-0.9.37/templates/guide/onefile/html/toc.erb000066400000000000000000000001301466601756300215200ustar00rootroot00000000000000
          <%= @title %>
          

          Table of Contents
          

          
yard-0.9.37/templates/guide/tags/000077500000000000000000000000001466601756300166205ustar00rootroot00000000000000yard-0.9.37/templates/guide/tags/html/000077500000000000000000000000001466601756300175645ustar00rootroot00000000000000yard-0.9.37/templates/guide/tags/html/setup.rb000066400000000000000000000002521466601756300212500ustar00rootroot00000000000000# frozen_string_literal: true
include T('default/tags/html')

def init
  super
  [:since, :see, :return].each do |section|
    sections[:index].delete(section)
  end
end
yard-0.9.37/yard.gemspec000066400000000000000000000020201466601756300150650ustar00rootroot00000000000000# frozen_string_literal: true
require File.expand_path('../lib/yard/version', __FILE__)

Gem::Specification.new do |s|
  s.name          = "yard"
  s.summary       = "Documentation tool for consistent and usable documentation in Ruby."
  s.description   = <<-eof
    YARD is a documentation generation tool for the Ruby programming language.
    It enables the user to generate consistent, usable documentation that can be
    exported to a number of formats very easily, and also supports extending for
    custom Ruby constructs such as custom class level definitions.
  eof
  s.version       = YARD::VERSION
  s.author        = "Loren Segal"
  s.email         = "lsegal@soen.ca"
  s.homepage      = "http://yardoc.org"
  s.platform      = Gem::Platform::RUBY
  s.files         = Dir['{lib,docs,po,templates}/**/*', '.yardopts*', 'CHANGELOG.md', 'LICENSE', 'LEGAL', 'README.md']
  s.require_paths = ['lib']
  s.executables   = ['yard', 'yardoc', 'yri']
  s.license = 'MIT' if s.respond_to?(:license=)
  s.metadata['yard.run'] = 'yri'
end