├── .github ├── ISSUE_TEMPLATE │ └── bug-report-or-feature-request.md ├── pull_request_template.md └── workflows │ └── test.yml ├── .gitignore ├── Build.rakumod ├── CONTRIBUTING.md ├── CREDITS ├── LICENSE ├── META6.json ├── Makefile ├── README.md ├── doc ├── Language │ ├── 101-basics.rakudoc │ ├── 5to6-nutshell.rakudoc │ ├── 5to6-overview.rakudoc │ ├── 5to6-perlfunc.rakudoc │ ├── 5to6-perlop.rakudoc │ ├── 5to6-perlsyn.rakudoc │ ├── 5to6-perlvar.rakudoc │ ├── REPL.rakudoc │ ├── about.rakudoc │ ├── brackets.rakudoc │ ├── classtut.rakudoc │ ├── community.rakudoc │ ├── compilation.rakudoc │ ├── concurrency.rakudoc │ ├── containers.rakudoc │ ├── contexts.rakudoc │ ├── control.rakudoc │ ├── create-cli.rakudoc │ ├── enumeration.rakudoc │ ├── exceptions.rakudoc │ ├── experimental.rakudoc │ ├── faq.rakudoc │ ├── filename-extensions.rakudoc │ ├── functions.rakudoc │ ├── glossary.rakudoc │ ├── grammar_tutorial.rakudoc │ ├── grammars.rakudoc │ ├── hashmap.rakudoc │ ├── haskell-to-p6.rakudoc │ ├── intro.rakudoc │ ├── io-guide.rakudoc │ ├── io.rakudoc │ ├── ipc.rakudoc │ ├── iterating.rakudoc │ ├── js-nutshell.rakudoc │ ├── list.rakudoc │ ├── math.rakudoc │ ├── module-packages.rakudoc │ ├── modules-core.rakudoc │ ├── modules-extra.rakudoc │ ├── modules.rakudoc │ ├── mop.rakudoc │ ├── nativecall.rakudoc │ ├── nativetypes.rakudoc │ ├── newline.rakudoc │ ├── numerics.rakudoc │ ├── objects.rakudoc │ ├── operators.rakudoc │ ├── optut.rakudoc │ ├── packages.rakudoc │ ├── performance.rakudoc │ ├── phasers.rakudoc │ ├── pod.rakudoc │ ├── pragmas.rakudoc │ ├── py-nutshell.rakudoc │ ├── quoting.rakudoc │ ├── rb-nutshell.rakudoc │ ├── regexes-best-practices.rakudoc │ ├── regexes.rakudoc │ ├── setbagmix.rakudoc │ ├── signatures.rakudoc │ ├── slangs.rakudoc │ ├── statement-prefixes.rakudoc │ ├── structures.rakudoc │ ├── subscripts.rakudoc │ ├── syntax.rakudoc │ ├── system.rakudoc │ ├── tables.rakudoc │ ├── temporal.rakudoc │ ├── terms.rakudoc │ ├── testing.rakudoc │ ├── traits.rakudoc │ ├── traps.rakudoc │ ├── typesystem.rakudoc │ ├── unicode.rakudoc │ ├── unicode_ascii.rakudoc │ ├── unicode_entry.rakudoc │ └── variables.rakudoc ├── Native │ └── int.rakudoc ├── Programs │ ├── 01-debugging.rakudoc │ ├── 02-reading-docs.rakudoc │ ├── 03-environment-variables.rakudoc │ ├── 04-running-raku.rakudoc │ └── README.md ├── Type │ ├── AST.rakudoc │ ├── Allomorph.rakudoc │ ├── Any.rakudoc │ ├── Array.rakudoc │ ├── Associative.rakudoc │ ├── Attribute.rakudoc │ ├── Backtrace.rakudoc │ ├── Backtrace │ │ └── Frame.rakudoc │ ├── Bag.rakudoc │ ├── BagHash.rakudoc │ ├── Baggy.rakudoc │ ├── Blob.rakudoc │ ├── Block.rakudoc │ ├── Bool.rakudoc │ ├── Buf.rakudoc │ ├── CX │ │ ├── Done.rakudoc │ │ ├── Emit.rakudoc │ │ ├── Last.rakudoc │ │ ├── Next.rakudoc │ │ ├── Proceed.rakudoc │ │ ├── Redo.rakudoc │ │ ├── Return.rakudoc │ │ ├── Succeed.rakudoc │ │ ├── Take.rakudoc │ │ └── Warn.rakudoc │ ├── CallFrame.rakudoc │ ├── Callable.rakudoc │ ├── Cancellation.rakudoc │ ├── Capture.rakudoc │ ├── Channel.rakudoc │ ├── Code.rakudoc │ ├── Collation.rakudoc │ ├── CompUnit.rakudoc │ ├── CompUnit │ │ ├── PrecompilationRepository.rakudoc │ │ ├── Repository.rakudoc │ │ └── Repository │ │ │ ├── FileSystem.rakudoc │ │ │ └── Installation.rakudoc │ ├── Compiler.rakudoc │ ├── Complex.rakudoc │ ├── ComplexStr.rakudoc │ ├── Cool.rakudoc │ ├── CurrentThreadScheduler.rakudoc │ ├── Date.rakudoc │ ├── DateTime.rakudoc │ ├── Dateish.rakudoc │ ├── Distribution.rakudoc │ ├── Distribution │ │ ├── Hash.rakudoc │ │ ├── Locally.rakudoc │ │ ├── Path.rakudoc │ │ └── Resource.rakudoc │ ├── Distro.rakudoc │ ├── Duration.rakudoc │ ├── Encoding.rakudoc │ ├── Encoding │ │ └── Registry.rakudoc │ ├── Endian.rakudoc │ ├── Enumeration.rakudoc │ ├── Exception.rakudoc │ ├── Failure.rakudoc │ ├── FatRat.rakudoc │ ├── ForeignCode.rakudoc │ ├── Format.rakudoc │ ├── Formatter.rakudoc │ ├── Grammar.rakudoc │ ├── Hash.rakudoc │ ├── HyperSeq.rakudoc │ ├── HyperWhatever.rakudoc │ ├── IO.rakudoc │ ├── IO │ │ ├── ArgFiles.rakudoc │ │ ├── CatHandle.rakudoc │ │ ├── Handle.rakudoc │ │ ├── Notification.rakudoc │ │ ├── Notification │ │ │ └── Change.rakudoc │ │ ├── Path.rakudoc │ │ ├── Path │ │ │ ├── Cygwin.rakudoc │ │ │ ├── Parts.rakudoc │ │ │ ├── QNX.rakudoc │ │ │ ├── Unix.rakudoc │ │ │ └── Win32.rakudoc │ │ ├── Pipe.rakudoc │ │ ├── Socket.rakudoc │ │ ├── Socket │ │ │ ├── Async.rakudoc │ │ │ ├── Async │ │ │ │ └── ListenSocket.rakudoc │ │ │ └── INET.rakudoc │ │ ├── Spec.rakudoc │ │ ├── Spec │ │ │ ├── Cygwin.rakudoc │ │ │ ├── QNX.rakudoc │ │ │ ├── Unix.rakudoc │ │ │ └── Win32.rakudoc │ │ └── Special.rakudoc │ ├── Instant.rakudoc │ ├── Int.rakudoc │ ├── IntStr.rakudoc │ ├── Iterable.rakudoc │ ├── IterationBuffer.rakudoc │ ├── Iterator.rakudoc │ ├── Junction.rakudoc │ ├── Kernel.rakudoc │ ├── Label.rakudoc │ ├── List.rakudoc │ ├── Lock.rakudoc │ ├── Lock │ │ ├── Async.rakudoc │ │ └── ConditionVariable.rakudoc │ ├── Macro.rakudoc │ ├── Map.rakudoc │ ├── Match.rakudoc │ ├── Metamodel │ │ ├── AttributeContainer.rakudoc │ │ ├── C3MRO.rakudoc │ │ ├── ClassHOW.rakudoc │ │ ├── ConcreteRoleHOW.rakudoc │ │ ├── CurriedRoleHOW.rakudoc │ │ ├── DefiniteHOW.rakudoc │ │ ├── Documenting.rakudoc │ │ ├── EnumHOW.rakudoc │ │ ├── Finalization.rakudoc │ │ ├── MROBasedMethodDispatch.rakudoc │ │ ├── MethodContainer.rakudoc │ │ ├── Mixins.rakudoc │ │ ├── MultipleInheritance.rakudoc │ │ ├── Naming.rakudoc │ │ ├── PackageHOW.rakudoc │ │ ├── ParametricRoleGroupHOW.rakudoc │ │ ├── ParametricRoleHOW.rakudoc │ │ ├── Primitives.rakudoc │ │ ├── PrivateMethodContainer.rakudoc │ │ ├── RoleContainer.rakudoc │ │ ├── RolePunning.rakudoc │ │ ├── Stashing.rakudoc │ │ ├── Trusting.rakudoc │ │ └── Versioning.rakudoc │ ├── Method.rakudoc │ ├── Mix.rakudoc │ ├── MixHash.rakudoc │ ├── Mixy.rakudoc │ ├── Mu.rakudoc │ ├── NFC.rakudoc │ ├── NFD.rakudoc │ ├── NFKC.rakudoc │ ├── NFKD.rakudoc │ ├── Nil.rakudoc │ ├── Num.rakudoc │ ├── NumStr.rakudoc │ ├── Numeric.rakudoc │ ├── ObjAt.rakudoc │ ├── Order.rakudoc │ ├── Pair.rakudoc │ ├── Parameter.rakudoc │ ├── Perl.rakudoc │ ├── Pod │ │ ├── Block.rakudoc │ │ ├── Block │ │ │ ├── Code.rakudoc │ │ │ ├── Comment.rakudoc │ │ │ ├── Declarator.rakudoc │ │ │ ├── Named.rakudoc │ │ │ ├── Para.rakudoc │ │ │ └── Table.rakudoc │ │ ├── Defn.rakudoc │ │ ├── FormattingCode.rakudoc │ │ ├── Heading.rakudoc │ │ └── Item.rakudoc │ ├── Positional.rakudoc │ ├── PositionalBindFailover.rakudoc │ ├── PredictiveIterator.rakudoc │ ├── Proc.rakudoc │ ├── Proc │ │ └── Async.rakudoc │ ├── Promise.rakudoc │ ├── Proxy.rakudoc │ ├── PseudoStash.rakudoc │ ├── QuantHash.rakudoc │ ├── RaceSeq.rakudoc │ ├── Raku.rakudoc │ ├── RakuAST.rakudoc │ ├── RakuAST │ │ ├── Doc.rakudoc │ │ └── Doc │ │ │ ├── Block.rakudoc │ │ │ ├── Declarator.rakudoc │ │ │ ├── DeclaratorTarget.rakudoc │ │ │ ├── Markup.rakudoc │ │ │ └── Paragraph.rakudoc │ ├── Range.rakudoc │ ├── Rat.rakudoc │ ├── RatStr.rakudoc │ ├── Rational.rakudoc │ ├── Real.rakudoc │ ├── Regex.rakudoc │ ├── Routine.rakudoc │ ├── Routine │ │ └── WrapHandle.rakudoc │ ├── Scalar.rakudoc │ ├── Scheduler.rakudoc │ ├── Semaphore.rakudoc │ ├── Seq.rakudoc │ ├── Sequence.rakudoc │ ├── Set.rakudoc │ ├── SetHash.rakudoc │ ├── Setty.rakudoc │ ├── Signature.rakudoc │ ├── Slip.rakudoc │ ├── Stash.rakudoc │ ├── Str.rakudoc │ ├── StrDistance.rakudoc │ ├── Stringy.rakudoc │ ├── Sub.rakudoc │ ├── Submethod.rakudoc │ ├── Supplier.rakudoc │ ├── Supplier │ │ └── Preserving.rakudoc │ ├── Supply.rakudoc │ ├── Systemic.rakudoc │ ├── Tap.rakudoc │ ├── Telemetry.rakudoc │ ├── Telemetry │ │ ├── Instrument │ │ │ ├── Thread.rakudoc │ │ │ ├── ThreadPool.rakudoc │ │ │ └── Usage.rakudoc │ │ ├── Period.rakudoc │ │ └── Sampler.rakudoc │ ├── Test.rakudoc │ ├── Thread.rakudoc │ ├── ThreadPoolScheduler.rakudoc │ ├── UInt.rakudoc │ ├── Uni.rakudoc │ ├── Unicode.rakudoc │ ├── VM.rakudoc │ ├── ValueObjAt.rakudoc │ ├── Variable.rakudoc │ ├── Version.rakudoc │ ├── Whatever.rakudoc │ ├── WhateverCode.rakudoc │ ├── X │ │ ├── AdHoc.rakudoc │ │ ├── Anon │ │ │ ├── Augment.rakudoc │ │ │ └── Multi.rakudoc │ │ ├── Assignment │ │ │ └── RO.rakudoc │ │ ├── Attribute │ │ │ ├── NoPackage.rakudoc │ │ │ ├── Package.rakudoc │ │ │ ├── Required.rakudoc │ │ │ └── Undeclared.rakudoc │ │ ├── Augment │ │ │ └── NoSuchType.rakudoc │ │ ├── Bind.rakudoc │ │ ├── Bind │ │ │ ├── NativeType.rakudoc │ │ │ └── Slice.rakudoc │ │ ├── Caller │ │ │ └── NotDynamic.rakudoc │ │ ├── Cannot │ │ │ ├── Empty.rakudoc │ │ │ └── Lazy.rakudoc │ │ ├── Channel │ │ │ ├── ReceiveOnClosed.rakudoc │ │ │ └── SendOnClosed.rakudoc │ │ ├── Comp.rakudoc │ │ ├── Composition │ │ │ └── NotComposable.rakudoc │ │ ├── Constructor │ │ │ └── Positional.rakudoc │ │ ├── Control.rakudoc │ │ ├── ControlFlow.rakudoc │ │ ├── ControlFlow │ │ │ └── Return.rakudoc │ │ ├── DateTime │ │ │ └── TimezoneClash.rakudoc │ │ ├── Declaration │ │ │ ├── Scope.rakudoc │ │ │ └── Scope │ │ │ │ └── Multi.rakudoc │ │ ├── Does │ │ │ └── TypeObject.rakudoc │ │ ├── Dynamic │ │ │ └── NotFound.rakudoc │ │ ├── Eval │ │ │ └── NoSuchLang.rakudoc │ │ ├── Export │ │ │ └── NameClash.rakudoc │ │ ├── IO.rakudoc │ │ ├── IO │ │ │ ├── BinaryMode.rakudoc │ │ │ ├── Chdir.rakudoc │ │ │ ├── Chmod.rakudoc │ │ │ ├── Chown.rakudoc │ │ │ ├── Copy.rakudoc │ │ │ ├── Cwd.rakudoc │ │ │ ├── Dir.rakudoc │ │ │ ├── DoesNotExist.rakudoc │ │ │ ├── Link.rakudoc │ │ │ ├── Mkdir.rakudoc │ │ │ ├── Move.rakudoc │ │ │ ├── Rename.rakudoc │ │ │ ├── Rmdir.rakudoc │ │ │ ├── Symlink.rakudoc │ │ │ └── Unlink.rakudoc │ │ ├── Inheritance │ │ │ ├── NotComposed.rakudoc │ │ │ └── Unsupported.rakudoc │ │ ├── Method │ │ │ ├── InvalidQualifier.rakudoc │ │ │ ├── NotFound.rakudoc │ │ │ └── Private │ │ │ │ ├── Permission.rakudoc │ │ │ │ └── Unqualified.rakudoc │ │ ├── Mixin │ │ │ └── NotComposable.rakudoc │ │ ├── NYI.rakudoc │ │ ├── NoDispatcher.rakudoc │ │ ├── Numeric │ │ │ ├── CannotConvert.rakudoc │ │ │ ├── DivideByZero.rakudoc │ │ │ └── Real.rakudoc │ │ ├── OS.rakudoc │ │ ├── Obsolete.rakudoc │ │ ├── OutOfRange.rakudoc │ │ ├── Package │ │ │ └── Stubbed.rakudoc │ │ ├── Parameter │ │ │ ├── Default.rakudoc │ │ │ ├── MultipleTypeConstraints.rakudoc │ │ │ ├── Placeholder.rakudoc │ │ │ ├── Twigil.rakudoc │ │ │ └── WrongOrder.rakudoc │ │ ├── Phaser │ │ │ ├── Multiple.rakudoc │ │ │ └── PrePost.rakudoc │ │ ├── Placeholder │ │ │ ├── Block.rakudoc │ │ │ └── Mainline.rakudoc │ │ ├── Pod.rakudoc │ │ ├── Proc │ │ │ ├── Async.rakudoc │ │ │ ├── Async │ │ │ │ ├── AlreadyStarted.rakudoc │ │ │ │ ├── BindOrUse.rakudoc │ │ │ │ ├── CharsOrBytes.rakudoc │ │ │ │ ├── MustBeStarted.rakudoc │ │ │ │ ├── OpenForWriting.rakudoc │ │ │ │ └── TapBeforeSpawn.rakudoc │ │ │ └── Unsuccessful.rakudoc │ │ ├── Promise │ │ │ ├── CauseOnlyValidOnBroken.rakudoc │ │ │ └── Vowed.rakudoc │ │ ├── Redeclaration.rakudoc │ │ ├── Role │ │ │ └── Initialization.rakudoc │ │ ├── Scheduler │ │ │ └── CueInNaNSeconds.rakudoc │ │ ├── Seq │ │ │ └── Consumed.rakudoc │ │ ├── Sequence │ │ │ └── Deduction.rakudoc │ │ ├── Signature │ │ │ ├── NameClash.rakudoc │ │ │ └── Placeholder.rakudoc │ │ ├── Str │ │ │ ├── Match │ │ │ │ └── x.rakudoc │ │ │ └── Numeric.rakudoc │ │ ├── StubCode.rakudoc │ │ ├── Syntax.rakudoc │ │ ├── Syntax │ │ │ ├── Augment │ │ │ │ └── WithoutMonkeyTyping.rakudoc │ │ │ ├── Comment │ │ │ │ └── Embedded.rakudoc │ │ │ ├── Confused.rakudoc │ │ │ ├── InfixInTermPosition.rakudoc │ │ │ ├── Malformed.rakudoc │ │ │ ├── Missing.rakudoc │ │ │ ├── NegatedPair.rakudoc │ │ │ ├── NoSelf.rakudoc │ │ │ ├── Number │ │ │ │ └── RadixOutOfRange.rakudoc │ │ │ ├── P5.rakudoc │ │ │ ├── Perl5Var.rakudoc │ │ │ ├── Regex │ │ │ │ ├── Adverb.rakudoc │ │ │ │ └── SolitaryQuantifier.rakudoc │ │ │ ├── Reserved.rakudoc │ │ │ ├── Self │ │ │ │ └── WithoutObject.rakudoc │ │ │ ├── Signature │ │ │ │ └── InvocantMarker.rakudoc │ │ │ ├── Term │ │ │ │ └── MissingInitializer.rakudoc │ │ │ ├── UnlessElse.rakudoc │ │ │ └── Variable │ │ │ │ ├── Match.rakudoc │ │ │ │ ├── Numeric.rakudoc │ │ │ │ └── Twigil.rakudoc │ │ ├── Temporal.rakudoc │ │ ├── Temporal │ │ │ └── InvalidFormat.rakudoc │ │ ├── TypeCheck.rakudoc │ │ ├── TypeCheck │ │ │ ├── Assignment.rakudoc │ │ │ ├── Binding.rakudoc │ │ │ ├── Return.rakudoc │ │ │ └── Splice.rakudoc │ │ └── Undeclared.rakudoc │ ├── atomicint.rakudoc │ ├── independent-routines.rakudoc │ └── utf8.rakudoc └── announcements.rakudoc ├── lib ├── Pod │ ├── Cache.rakumod │ └── Convenience.rakumod └── Test-Files.rakumod ├── resources └── i18n │ ├── de │ └── README.de.md │ ├── es │ └── README.es.md │ ├── fr │ └── README.fr.md │ ├── it │ └── README.it.md │ ├── jp │ └── README.jp.md │ ├── nl │ └── README.nl.md │ ├── pt │ └── README.pt.md │ └── zh │ └── README.zh.md ├── t ├── 00-meta.rakutest ├── 02-pod-valid.rakutest ├── 03-tests-valid.rakutest └── 05-tabs.rakutest ├── type-graph.txt ├── util ├── clean-spell ├── create-brackets-table.raku ├── dumpast.raku ├── github-action-test.sh ├── missing-types.raku ├── new-type.raku ├── perl-nbsp.raku ├── sort-words.raku ├── test-modified.sh ├── test-website.raku ├── unskip.raku └── update-and-test ├── writing-docs ├── CREATING-NEW-DOCS.md ├── EXAMPLES.md ├── INDEXING.md ├── README.md ├── STYLEGUIDE.md └── TESTING.md └── xt ├── 01-raku-version.rakutest ├── an-grammar.rakutest ├── aspell.rakutest ├── braces.rakutest ├── camelia-invocations.rakutest ├── check-signatures.rakutest ├── double-dots.rakutest ├── duplicates.rakutest ├── examples-compilation.rakutest ├── final-newline.rakutest ├── headings.rakutest ├── lib-test-files.raku ├── lib-test-files.rakutest ├── perl-nbsp.rakutest ├── pws ├── code.pws └── words.pws ├── rakuast-compare.rakutest ├── rakuast-validate.rakutest ├── rakudoc-l.rakutest ├── rakudoc-types.rakutest ├── return-type.rakutest ├── routine-definitions.rakutest ├── search-categories.rakutest ├── space-after-comma.rakutest ├── trailing-whitespace.rakutest ├── type-graph.rakutest ├── vim-mode.rakutest ├── word-variants.rakutest └── words.rakutest /.github/ISSUE_TEMPLATE/bug-report-or-feature-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report or feature request 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: docs 6 | assignees: '' 7 | 8 | --- 9 | 10 | ## Problem or new feature 11 | 12 | A clear and concise description of what the bug is, including links to the page where you have found it. 13 | 14 | ## Suggestions 15 | 16 | If applicable, suggest something towards the solution. 17 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | ## The problem 2 | 3 | 4 | ## Solution provided 5 | 6 | 18 | -------------------------------------------------------------------------------- /.github/workflows/test.yml: -------------------------------------------------------------------------------- 1 | name: test 2 | on: 3 | push: 4 | branches: [ master ] 5 | paths: 6 | - 'doc/**' 7 | pull_request: 8 | branches: [ master ] 9 | paths: 10 | - 'doc/**' 11 | 12 | jobs: 13 | test: 14 | runs-on: ubuntu-latest 15 | steps: 16 | - uses: actions/checkout@v2 17 | 18 | - name: Run tests 19 | run: ./util/github-action-test.sh t 20 | env: 21 | TEST_IMAGE: docker.io/jjmerelo/perl6-doccer:latest 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Precompilation folders 2 | lib/.precomp 3 | .pod-precomp 4 | .pod-cache 5 | 6 | # Generated files for testing 7 | xt/pws/aspell.pws 8 | retest 9 | 10 | # Cached file for building pages 11 | util/Grammar.nqp 12 | 13 | # IDE 14 | *.iml 15 | 16 | # website clone for testing 17 | doc-website 18 | -------------------------------------------------------------------------------- /Build.rakumod: -------------------------------------------------------------------------------- 1 | class Build { 2 | BEGIN { 3 | note q:to/END/; 4 | This repository is not intended to be installed! 5 | View the latest HTML version at https://docs.raku.org/ 6 | Command line viewer at https://github.com/raku/rakudoc 7 | END 8 | die; 9 | } 10 | } 11 | -------------------------------------------------------------------------------- /META6.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "Raku doc", 3 | "description": "Raku™ documentation", 4 | "version": "2.0", 5 | "raku": "6.*", 6 | "authors": [ 7 | "raku" 8 | ], 9 | "auth": "raku", 10 | "test-depends": [ 11 | "Cro::HTTP::Client", 12 | "HTTP::UserAgent", 13 | "File::Temp", 14 | "Test::META", 15 | "Doc::TypeGraph" 16 | ], 17 | "build-depends": [], 18 | "provides": { 19 | "Test-Files": "lib/Test-Files.rakumod", 20 | "Pod::Cache": "lib/Pod/Cache.rakumod", 21 | "Pod::Convenience": "lib/Pod/Convenience.rakumod" 22 | }, 23 | "support": { 24 | "source": "git://github.com/Raku/doc.git" 25 | }, 26 | "license": "Artistic-2.0", 27 | "tags": [ 28 | "raku", 29 | "pod6", 30 | "rakudoc", 31 | "documentation", 32 | "reference", 33 | "perl6" 34 | ], 35 | "source-url": "git://github.com/Raku/doc.git", 36 | "meta6": "0" 37 | } 38 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: test xtest push help 2 | 3 | help: 4 | @echo "Usage: make [test|xtest|push]" 5 | @echo "" 6 | @echo "Options:" 7 | @echo " test: run the basic test suite" 8 | @echo " xtest: run all tests" 9 | @echo " push: run the basic test suite and git push" 10 | 11 | # Common tests - also run by CI 12 | test: 13 | if [ "${TEST_JOBS}" != "" ]; then prove --ext=rakutest -j ${TEST_JOBS} -e raku t; else prove --ext=rakutest -e raku t; fi 14 | 15 | # Extended tests - should be run by authors before committing 16 | xtest: 17 | if [ "${TEST_JOBS}" != "" ]; then prove --ext=rakutest -j ${TEST_JOBS} -e raku t xt; else prove --ext=rakutest -e raku t xt; fi 18 | 19 | push: test 20 | git pull --rebase && git push 21 | -------------------------------------------------------------------------------- /doc/Language/about.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Language") :subkind("Language") :category("beginning") 2 | 3 | =TITLE About the docs 4 | 5 | =SUBTITLE How to contribute to Raku and to the documents, how to generate the docs locally 6 | 7 | This document collection represents the on-going effort to document the 8 | Raku programming language with the goals of being comprehensive, 9 | easy to use, easy to navigate, and useful to both newcomers and experienced 10 | Raku programmers. 11 | 12 | An L is available. 13 | 14 | The official source for this documentation is located at 15 | L. 16 | 17 | =head1 Structure 18 | 19 | All of the documentation is written in Raku Pod and kept in the C 20 | directory. These files are processed are rendered to HTML, and also 21 | processed into some generated pages, using the C<.rakudoc> files as 22 | sources. 23 | 24 | =head1 Generating HTML from Pod 25 | 26 | The build process is managed through a separate repository, 27 | L. 28 | 29 | =head1 Contributing 30 | 31 | For a quick introduction to Raku Pod, see L. 32 | 33 | For historic details about the Raku Pod specification, see L. 34 | 35 | For information on how to contribute to the documentation, please 36 | read L. 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Language/filename-extensions.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Language") :subkind("Language") :category("beginning") 2 | 3 | =TITLE Filename extensions 4 | 5 | =SUBTITLE The extensions recommended for files with Raku content. 6 | 7 | =begin table 8 | File contents | Extension | Historic extensions 9 | ======================================================== 10 | Raku script | .raku | .pl, .p6 11 | Raku module | .rakumod | .pm, .pm6 12 | Raku documentation | .rakudoc | .pm, pm6, pod, pod6 13 | Test files in raku | .rakutest | .t 14 | Not Quite Perl (NQP) | .nqp | 15 | =end table 16 | 17 | Note that in most cases, the historic extensions will still work. 18 | 19 | =head1 Introduction 20 | 21 | An extension is the part of the filename after the final '.'; if no '.' 22 | is present, there is no extension. 23 | 24 | Filename extensions can be used to associate behavior with the file content, such as opening 25 | a specialized reader or editor, running a program with the file content as input, etc. 26 | Even when it is not required by the operating system, filename extensions can provide a useful 27 | reminder about the contents of the file. 28 | 29 | =head1 History 30 | 31 | The Raku language was originally known as Perl 6, and this is reflected in the historic column 32 | above. Please use the current extensions whenever possible when generating new code. 33 | 34 | =end pod 35 | -------------------------------------------------------------------------------- /doc/Native/int.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class int 4 | 5 | =SUBTITLE Native integer 6 | 7 | class int is Int { } 8 | 9 | This class is used to represent integers that are native to the compiler, 10 | operating system and architecture the interpreter is compiled in. 11 | 12 | More information in L as well as in 13 | the section on L. 14 | 15 | 16 | =end pod 17 | -------------------------------------------------------------------------------- /doc/Programs/README.md: -------------------------------------------------------------------------------- 1 | Attention contributors 2 | ====================== 3 | 4 | Files in this directory are sorted by file name to generate the index 5 | for the "Programs" tab (in contrast to the other tabs which are 6 | indexed in order by each file's "=TITLE" entry). 7 | -------------------------------------------------------------------------------- /doc/Type/AST.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class AST 4 | 5 | =SUBTITLE Abstract representation of a piece of source code 6 | 7 | class AST { } 8 | 9 | An C or I is a partially processed representation 10 | of a program. ASTs are return values of the C quoting construct, 11 | and are typically used within macros to generate code that is inserted 12 | in the calling location of the macro. 13 | 14 | There is no API defined for ASTs yet. Hopefully that will emerge as 15 | part of the work on macros. 16 | 17 | =end pod 18 | -------------------------------------------------------------------------------- /doc/Type/CX/Done.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class CX::Done 4 | 5 | =SUBTITLE Done control exception 6 | 7 | class CX::Done does X::Control { } 8 | 9 | A L to be used to 10 | indicate a supply block is finished by calling C. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. 19 | 20 | =end pod 21 | -------------------------------------------------------------------------------- /doc/Type/CX/Emit.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Emit 4 | 5 | =SUBTITLE Emit control exception 6 | 7 | role CX::Emit does X::Control { } 8 | 9 | A L to be used when 10 | emit is used inside a L|/type/Supply> block. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. 19 | 20 | =end pod 21 | -------------------------------------------------------------------------------- /doc/Type/CX/Last.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Last 4 | 5 | =SUBTITLE Last control exception 6 | 7 | role CX::Last does X::Control { } 8 | 9 | A L that is thrown 10 | when C is called. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. Since this type of exception is to be 19 | consumed by type and not really by the content of the message, this is a generic 20 | message, similar to all other C exceptions. 21 | 22 | =end pod 23 | -------------------------------------------------------------------------------- /doc/Type/CX/Next.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Next 4 | 5 | =SUBTITLE Next control exception 6 | 7 | role CX::Next does X::Control { } 8 | 9 | A L that is triggered 10 | when C is called. 11 | 12 | =for code 13 | for ^10 { 14 | CONTROL { 15 | when CX::Next { say "We're next" }; 16 | } 17 | next if $_ %% 2; 18 | say "We're in $_"; 19 | } 20 | 21 | This will print: 22 | 23 | =for code :lang 24 | We're next 25 | We're in 1 26 | We're next 27 | We're in 3 28 | We're next 29 | We're in 5 30 | We're next 31 | We're in 7 32 | We're next 33 | We're in 9 34 | 35 | 36 | =head1 Methods 37 | 38 | =head2 method message 39 | 40 | method message() 41 | 42 | Returns C<''>. 43 | 44 | =end pod 45 | -------------------------------------------------------------------------------- /doc/Type/CX/Proceed.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Proceed 4 | 5 | =SUBTITLE Proceed control exception 6 | 7 | role CX::Proceed does X::Control { } 8 | 9 | A L to be used when 10 | C is used within C or C blocks. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. 19 | 20 | =end pod 21 | -------------------------------------------------------------------------------- /doc/Type/CX/Redo.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Redo 4 | 5 | =SUBTITLE Redo control exception 6 | 7 | role CX::Redo does X::Control { } 8 | 9 | A L thrown when 10 | C is called. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. 19 | 20 | =end pod 21 | -------------------------------------------------------------------------------- /doc/Type/CX/Return.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Return 4 | 5 | =SUBTITLE Return control exception 6 | 7 | role CX::Next does X::Control { } 8 | 9 | A L to be used when 10 | return is called from within a sub. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. 19 | 20 | =end pod 21 | -------------------------------------------------------------------------------- /doc/Type/CX/Succeed.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Succeed 4 | 5 | =SUBTITLE Succeed control exception 6 | 7 | role CX::Succeed does X::Control { } 8 | 9 | A L thrown when 10 | C is called from a C or C block. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. 19 | 20 | =end pod 21 | -------------------------------------------------------------------------------- /doc/Type/CX/Take.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Take 4 | 5 | =SUBTITLE Take control exception 6 | 7 | role CX::Take does X::Control { } 8 | 9 | A L triggered by 10 | C. 11 | 12 | =head1 Methods 13 | 14 | =head2 method message 15 | 16 | method message() 17 | 18 | Returns C<''>. 19 | 20 | =end pod 21 | -------------------------------------------------------------------------------- /doc/Type/CX/Warn.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role CX::Warn 4 | 5 | =SUBTITLE Control exception warning 6 | 7 | role CX::Warn does X::Control { } 8 | 9 | A L triggered when C is called to warn about any 10 | incidence. 11 | 12 | =head1 Methods 13 | 14 | =head2 method new 15 | 16 | C objects are created when a warning is thrown in any block. 17 | 18 | =end pod 19 | -------------------------------------------------------------------------------- /doc/Type/Cancellation.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Cancellation 4 | 5 | =SUBTITLE Removal of a task from a Scheduler before normal completion 6 | 7 | my class Cancellation {} 8 | 9 | A low level part of the Raku L 10 | system. Some L|/type/Scheduler> objects return a C with the 11 | L<.cue|/type/Scheduler#method_cue> method which can be used to cancel the 12 | scheduled execution before normal completion. C is a 13 | Boolean that is true after C is called. 14 | 15 | =head1 Methods 16 | 17 | =head2 method cancel 18 | 19 | method cancel() 20 | 21 | Usage: 22 | 23 | =begin code 24 | Cancellation.cancel 25 | =end code 26 | 27 | Cancels the scheduled execution of a task before normal completion. 28 | 29 | =end pod 30 | -------------------------------------------------------------------------------- /doc/Type/CompUnit/Repository.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("domain-specific") 2 | 3 | =TITLE role CompUnit::Repository 4 | 5 | =SUBTITLE CompUnit::Repository 6 | 7 | The C role defines the interface of the implementation 8 | of CompUnit::Repositories such as L|/type/CompUnit::Repository::Installation> 9 | and L|/type/CompUnit::Repository::FileSystem>. 10 | 11 | =head1 Methods 12 | 13 | =head2 method resolve 14 | 15 | method resolve(CompUnit::DependencySpecification $spec --> CompUnit:D) 16 | 17 | Returns a L|/type/CompUnit> mapped to the highest version distribution matching 18 | C<$spec> from the first repository in the repository chain that contains any 19 | version of a distribution matching C<$spec>. 20 | 21 | =head2 method need 22 | 23 | Loads and returns a L|/type/CompUnit> which is mapped to the highest version 24 | distribution matching C<$spec> from the first repository in the repository 25 | chain that contains any version of a distribution matching C<$spec>. 26 | 27 | =head2 method load 28 | 29 | method load(IO::Path:D $file --> CompUnit:D) 30 | 31 | Load the C<$file> and return a L|/type/CompUnit> object representing it. 32 | 33 | =head2 method loaded 34 | 35 | method loaded(--> Iterable:D) 36 | 37 | Returns all L|/type/CompUnit>s this repository has loaded. 38 | 39 | =end pod 40 | -------------------------------------------------------------------------------- /doc/Type/CurrentThreadScheduler.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class CurrentThreadScheduler 4 | 5 | =SUBTITLE Scheduler that synchronously executes code on the current thread 6 | 7 | =for code :skip-test 8 | class CurrentThreadScheduler does Scheduler {} 9 | 10 | C executes tasks on the current threads. This means 11 | that L blocks until the code has 12 | finished executing. 13 | 14 | =end pod 15 | -------------------------------------------------------------------------------- /doc/Type/Distribution.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("basic") 2 | 3 | =TITLE role Distribution 4 | 5 | =SUBTITLE Distribution 6 | 7 | role Distribution { } 8 | 9 | This role is an interface for objects that provide API access mapping META6 data 10 | to the files it represents. Objects that fulfill the C role can be 11 | read by e.g. 12 | L|/type/CompUnit::Repository::Installation>. 13 | Generally a C provides read access to a set of modules and 14 | metadata. These may be backed by the filesystem 15 | (L|/type/Distribution::Path>, 16 | L|/type/Distribution::Hash>) but could also read from an e.g. 17 | tar file or socket. 18 | 19 | =head1 Required Methods 20 | 21 | =head2 method meta 22 | 23 | method meta(--> Hash:D) { ... } 24 | 25 | Returns a Hash with the representation of the metadata. Please note that an 26 | actual C file does not need to exist, just a representation in that 27 | format. 28 | 29 | =head2 method content 30 | 31 | method content($name-path --> IO::Handle:D) { ... } 32 | 33 | Returns an L|/type/IO::Handle> to the file represented by C<$name-path>. C<$name-path> 34 | is a relative path as it would be found in the metadata such as C 35 | or C. 36 | 37 | =end pod 38 | -------------------------------------------------------------------------------- /doc/Type/Distribution/Hash.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Distribution::Hash 4 | 5 | =SUBTITLE Distribution::Hash 6 | 7 | =for code :preamble 8 | class Distribution::Hash does Distribution::Locally { } 9 | 10 | A L|/type/Distribution> implementation backed by the filesystem. It 11 | does not require a C file, essentially providing a lower level 12 | L|/type/Distribution::Path>. 13 | 14 | =head1 Methods 15 | 16 | =head2 method new 17 | 18 | method new($hash, :$prefix) 19 | 20 | Creates a new C instance from the metadata contained in 21 | C<$hash>. All paths in the metadata will be prefixed with C<:$prefix>. 22 | 23 | =head2 method meta 24 | 25 | method meta() 26 | 27 | Returns a Hash with the representation of the metadata. 28 | 29 | =head2 method content 30 | 31 | Please check 32 | L method in Distribution::Locally|/type/Distribution::Locally#method_content>. 33 | 34 | Returns an L|/type/IO::Handle> to the file represented by C<$name-path>. C<$name-path> 35 | is a relative path as it would be found in the metadata such as C 36 | or C. 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Type/Distribution/Locally.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Distribution::Locally 4 | 5 | =SUBTITLE Distribution::Locally 6 | 7 | role Distribution::Locally does Distribution { } 8 | 9 | Provides read access to specific files pointed at by a distributions metadata, 10 | providing the L 11 | method for L|/type/Distribution::Path> and 12 | L|/type/Distribution::Hash>. 13 | 14 | =head1 Methods 15 | 16 | =head2 method prefix 17 | 18 | A prefix path to be used in conjuncture with the paths found in the metadata. 19 | 20 | =head2 method content 21 | 22 | Provides L 23 | 24 | Returns an L|/type/IO::Handle> to the file represented by C<$name-path>. C<$name-path> 25 | is a relative path as it would be found in the metadata such as C 26 | or C, and these paths will be prefixed with 27 | L. 28 | 29 | =end pod 30 | -------------------------------------------------------------------------------- /doc/Type/Distribution/Path.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Distribution::Path 4 | 5 | =SUBTITLE Distribution::Path 6 | 7 | =for code :preamble 8 | class Distribution::Path does Distribution::Locally { } 9 | 10 | A L|/type/Distribution> implementation backed by the filesystem. It requires a 11 | C file at its root. 12 | 13 | =head1 Methods 14 | 15 | =head2 method new 16 | 17 | method new(IO::Path $prefix, IO::Path :$meta-file = IO::Path) 18 | 19 | Creates a new C instance from the C file found 20 | at the given C<$prefix>, and from which all paths in the metadata will be 21 | prefixed with. C<:$meta-file> may optionally be passed if a filename other than 22 | C needs to be used. 23 | 24 | =head2 method meta 25 | 26 | method meta(Distribution::Path:D:) 27 | 28 | Returns a Hash with the representation of the metadata. 29 | 30 | =head2 method content 31 | 32 | L 33 | 34 | Returns an L|/type/IO::Handle> to the file represented by C<$name-path>. C<$name-path> 35 | is a relative path as it would be found in the metadata such as C 36 | or C. 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Type/Distro.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Distro 4 | 5 | =SUBTITLE Distribution related information 6 | 7 | class Distro does Systemic { } 8 | 9 | Built-in class for providing distribution related information. Usually accessed 10 | through the L<$*DISTRO|/language/variables#index-entry-%24*DISTRO> dynamic 11 | variable. 12 | 13 | =head1 Methods 14 | 15 | =head2 method is-win 16 | 17 | Instance method returning a L|/type/Bool> indicating whether the distribution is a 18 | version of the Windows operating system. 19 | 20 | =head2 method path-sep 21 | 22 | Instance method returning the string that can be used to delimit elements in 23 | a path specification. 24 | 25 | =head2 method release 26 | 27 | Instance method returning the release information of the Distro object. Dies if 28 | the release information could not be established. 29 | 30 | =end pod 31 | -------------------------------------------------------------------------------- /doc/Type/Duration.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Duration 4 | 5 | =SUBTITLE Length of time 6 | 7 | class Duration is Cool does Real { } 8 | 9 | A C represents a length of time in atomic seconds, with 10 | fractions. Like an L|/type/Instant>, it is epoch-agnostic. 11 | 12 | Cs can be subtracted from or added to L|/type/Instant>s to yield another, 13 | new L|/type/Instant>. Subtracting one L|/type/Instant> from another yields a C. A 14 | C can also result from mathematical operations between two 15 | Cs when it makes sense (namely, the addition, subtraction, or modulus 16 | of two Cs). It can also be added, subtracted or divided modulo L|/type/Real> 17 | numbers. 18 | 19 | The type of object returned for other numeric operations is currently 20 | unspecified. 21 | 22 | =end pod 23 | -------------------------------------------------------------------------------- /doc/Type/Encoding/Registry.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Encoding::Registry 4 | 5 | =SUBTITLE Management of available encodings 6 | 7 | class Encoding::Registry {} 8 | 9 | C is initialized with a list of encoding that is 10 | available for any Raku application, namely: 11 | 12 | =item C 13 | =item C 14 | =item C 15 | =item C 16 | =item C 17 | =item C, C 18 | =item C 19 | =item C, C, C, C, C, C, C, C, C, C 20 | =item C 21 | =item C 22 | =item C 23 | 24 | =head1 Methods 25 | 26 | =head2 method name 27 | 28 | method register(Encoding $enc --> Nil) 29 | 30 | Register a new L|/type/Encoding>. 31 | 32 | X<|Types,Encoding::Encoder> 33 | X<|Types,Encoding::Decoder> 34 | =head2 method find 35 | 36 | method find(Str() $name) 37 | 38 | Finds an encoding by its name. Returns an C or 39 | C, depending on what had been registered. 40 | 41 | =end pod 42 | -------------------------------------------------------------------------------- /doc/Type/Endian.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("enum") :category("basic") 2 | 3 | =TITLE enum Endian 4 | 5 | =SUBTITLE Indicate endianness (6.d, 2018.12 and later) 6 | 7 | enum Endian ; 8 | 9 | X<|Reference,NativeEndian> 10 | X<|Reference,LittleEndian> 11 | X<|Reference,BigEndian> 12 | X<|Reference,Endian> 13 | An enum for indicating endianness, specifically with methods on C and 14 | C. Consists of C, C and C. 15 | 16 | =head1 Methods 17 | 18 | =head2 routine Numeric 19 | 20 | multi method Numeric(Endian:D --> Int:D) 21 | 22 | Returns the value part of the C pair. 23 | 24 | say NativeEndian.Numeric; # OUTPUT: «0␤» 25 | say LittleEndian.Numeric; # OUTPUT: «1␤» 26 | say BigEndian.Numeric; # OUTPUT: «2␤» 27 | 28 | Note that the actual numeric values are subject to change. So please use 29 | the named values instead. 30 | 31 | =end pod 32 | -------------------------------------------------------------------------------- /doc/Type/FatRat.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class FatRat 4 | 5 | =SUBTITLE Rational number (arbitrary-precision) 6 | 7 | class FatRat is Cool does Rational[Int, Int] {} 8 | 9 | A C is a rational number stored with arbitrary size numerator and 10 | denominator. Arithmetic operations involving a C and optionally L|/type/Int> 11 | or L|/type/Rat> objects return a C, avoiding loss of precision. 12 | 13 | Since, unlike L|/type/Rat>, FatRat arithmetics do not fall back L|/type/Num> at some 14 | point, there is a risk that repeated arithmetic operations generate 15 | pathologically large numerators and denominators. 16 | 17 | There are two common ways to generate C objects: through the 18 | C constructor, which generates them from numerator and 19 | denominator, or by calling the C<.FatRat> method on an L|/type/Int> or L|/type/Rat> 20 | object. 21 | 22 | =head1 Methods 23 | 24 | =head2 method raku 25 | 26 | multi method raku(FatRat:D: --> Str:D) 27 | 28 | Returns an implementation-specific string that produces an L object 29 | when given to L. 30 | 31 | =for code 32 | say FatRat.new(1, 2).raku; # OUTPUT: «FatRat.new(1, 2)␤» 33 | 34 | =end pod 35 | -------------------------------------------------------------------------------- /doc/Type/IO.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("domain-specific") 2 | 3 | =TITLE role IO 4 | 5 | =SUBTITLE Input/output related routines 6 | 7 | The role provides no methods, but exists so that C coercers, which 8 | coerce to L|/type/IO::Path>, correctly type-check the resultant value. The 9 | role is implemented by L|/type/IO::Path> and 10 | L|/type/IO::Special>. 11 | 12 | See also the related classes L|/type/IO::Handle> and 13 | L|/type/IO::Path>. 14 | 15 | =end pod 16 | -------------------------------------------------------------------------------- /doc/Type/IO/Path/Cygwin.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class IO::Path::Cygwin 4 | 5 | =SUBTITLE IO::Path pre-loaded with IO::Spec::Cygwin 6 | 7 | class IO::Path::Cygwin is IO::Path { } 8 | 9 | This sub-class of L«C|/type/IO::Path», pre-loaded with 10 | L«C|/type/IO::Spec::Cygwin» in the C<$.SPEC> attribute. 11 | 12 | =head1 Methods 13 | 14 | =head2 method new 15 | 16 | Same as L«C|/type/IO::Path#method_new», except 17 | C<:$SPEC> cannot be set and defaults to 18 | L«C|/type/IO::Spec::Cygwin», regardless of the operating 19 | system the code is being run on. 20 | 21 | =head2 method raku 22 | 23 | method raku(IO::Path::Cygwin:D: --> Str:D) 24 | 25 | Returns a string that, when given passed through L«C|/routine/EVAL» 26 | gives the original invocant back. 27 | 28 | =for code 29 | IO::Path::Cygwin.new("foo/bar").raku.say; 30 | # OUTPUT: IO::Path::Cygwin.new("foo/bar", :CWD("/home/camelia")) 31 | 32 | Note that this string includes the value of the C<.CWD> attribute that is set 33 | to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path 34 | object was created, by default. 35 | 36 | =end pod 37 | -------------------------------------------------------------------------------- /doc/Type/IO/Path/QNX.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class IO::Path::QNX 4 | 5 | =SUBTITLE IO::Path pre-loaded with IO::Spec::QNX 6 | 7 | class IO::Path::QNX is IO::Path { } 8 | 9 | This sub-class of L«C|/type/IO::Path», pre-loaded with 10 | L«C|/type/IO::Spec::QNX» in the C<$.SPEC> attribute. 11 | 12 | =head1 Methods 13 | 14 | =head2 method new 15 | 16 | Same as L«C|/type/IO::Path#method_new», except 17 | C<:$SPEC> cannot be set and defaults to 18 | L«C|/type/IO::Spec::QNX», regardless of the operating system 19 | the code is being run on. 20 | 21 | =head2 method raku 22 | 23 | method raku(IO::Path::QNX:D: --> Str:D) 24 | 25 | Returns a string that, when given passed through L«C|/routine/EVAL» 26 | gives the original invocant back. 27 | 28 | =for code 29 | IO::Path::QNX.new("foo/bar").raku.say; 30 | # OUTPUT: IO::Path::QNX.new("foo/bar", :CWD("/home/camelia")) 31 | 32 | Note that this string includes the value of the C<.CWD> attribute that is set 33 | to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path 34 | object was created, by default. 35 | 36 | =end pod 37 | -------------------------------------------------------------------------------- /doc/Type/IO/Path/Unix.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class IO::Path::Unix 4 | 5 | =SUBTITLE IO::Path pre-loaded with IO::Spec::Unix 6 | 7 | class IO::Path::Unix is IO::Path { } 8 | 9 | This sub-class of L«C|/type/IO::Path», pre-loaded with 10 | L«C|/type/IO::Spec::Unix» in the C<$.SPEC> attribute. 11 | 12 | =head1 Methods 13 | 14 | =head2 method new 15 | 16 | Same as L«C|/type/IO::Path#method_new», except 17 | C<:$SPEC> cannot be set and defaults to 18 | L«C|/type/IO::Spec::Unix», regardless of the operating system 19 | the code is being run on. 20 | 21 | =head2 method raku 22 | 23 | method raku(IO::Path::Unix:D: --> Str:D) 24 | 25 | Returns a string that, when given passed through L«C|/routine/EVAL» 26 | gives the original invocant back. 27 | 28 | =for code 29 | IO::Path::Unix.new("foo/bar").raku.say; 30 | # OUTPUT: IO::Path::Unix.new("foo/bar", :CWD("/home/camelia")) 31 | 32 | Note that this string includes the value of the C<.CWD> attribute that is set 33 | to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path 34 | object was created, by default. 35 | 36 | =end pod 37 | -------------------------------------------------------------------------------- /doc/Type/IO/Path/Win32.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class IO::Path::Win32 4 | 5 | =SUBTITLE IO::Path pre-loaded with IO::Spec::Win32 6 | 7 | class IO::Path::Win32 is IO::Path { } 8 | 9 | This sub-class of L«C|/type/IO::Path», pre-loaded with 10 | L«C|/type/IO::Spec::Win32» in the C<$.SPEC> attribute. 11 | 12 | =head1 Methods 13 | 14 | =head2 method new 15 | 16 | Same as L«C|/type/IO::Path#method_new», except 17 | C<:$SPEC> cannot be set and defaults to 18 | L«C|/type/IO::Spec::Win32», regardless of the operating system 19 | the code is being run on. 20 | 21 | =head2 method raku 22 | 23 | method raku(IO::Path::Win32:D: --> Str:D) 24 | 25 | Returns a string that, when given passed through L«C|/routine/EVAL» 26 | gives the original invocant back. 27 | 28 | =for code 29 | IO::Path::Win32.new("foo/bar").raku.say; 30 | # OUTPUT: IO::Path::Win32.new("foo/bar", :CWD("C:\\Users\\camelia")) 31 | 32 | Note that this string includes the value of the C<.CWD> attribute that is set 33 | to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path 34 | object was created, by default. 35 | 36 | =end pod 37 | -------------------------------------------------------------------------------- /doc/Type/IO/Pipe.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class IO::Pipe 4 | 5 | =SUBTITLE Buffered inter-process string or binary stream 6 | 7 | class IO::Pipe is IO::Handle {} 8 | 9 | An C object closely corresponds to a UNIX pipe. It has one end where 10 | it consumes string or binary data, and another where it reproduces the same 11 | data. It is buffered, so that a write without a read doesn't immediately 12 | block. 13 | 14 | Pipes can be easily constructed with L. 15 | 16 | =head1 Methods 17 | 18 | =head2 method close 19 | 20 | method close(IO::Pipe: --> Proc:D) 21 | 22 | Closes the pipe and returns L|/type/Proc> object from which the pipe originates. 23 | 24 | =head2 method IO 25 | 26 | method IO(IO::Pipe: --> IO::Path:U) 27 | 28 | Returns an L|/type/IO::Path> type object. 29 | 30 | =head2 method path 31 | 32 | method path(IO::Pipe: --> IO::Path:U) 33 | 34 | Returns an L|/type/IO::Path> type object. 35 | 36 | =head2 method proc 37 | 38 | method proc(IO::Pipe: --> Proc:D) 39 | 40 | Returns the L|/type/Proc> object from which the pipe originates. 41 | 42 | =end pod 43 | -------------------------------------------------------------------------------- /doc/Type/IO/Spec.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class IO::Spec 4 | 5 | =SUBTITLE Platform specific operations on file and directory paths 6 | 7 | class IO::Spec { } 8 | 9 | Objects of this class are not used directly but as a sub-class specific to 10 | the platform Raku is running on via the C<$*SPEC> variable which will contain 11 | an object of the appropriate type. 12 | 13 | The sub-classes are documented separately, with the platform-specific 14 | differences documented in L|/type/IO::Spec::Cygwin>, L|/type/IO::Spec::QNX>, 15 | L|/type/IO::Spec::Unix> and L|/type/IO::Spec::Win32>. 16 | 17 | =head1 About sub-classes IO::Spec::* 18 | 19 | The C classes provide low-level path operations. Unless 20 | you're creating your own high-level path manipulation routines, you don't 21 | need to use C. Use L«C|/type/IO::Path» instead. 22 | 23 | Beware that no special validation is done by these classes (e.g. check whether 24 | path contains a null character). It is the job of higher-level classes, like 25 | L«C|/type/IO::Path», to do that. 26 | 27 | =head1 Methods 28 | 29 | =end pod 30 | -------------------------------------------------------------------------------- /doc/Type/IO/Spec/QNX.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class IO::Spec::QNX 4 | 5 | =SUBTITLE Platform specific operations on file and directory paths QNX 6 | 7 | class IO::Spec::QNX is IO::Spec::Unix { } 8 | 9 | An object of this type is available via the variable C<$*SPEC> if the 10 | Raku interpreter is running on a C platform. 11 | 12 | About this class and its related classes also see 13 | L|/type/IO::Spec>. 14 | 15 | =head1 Methods 16 | 17 | =head2 method canonpath 18 | 19 | method canonpath(Str() $path, :$parent --> Str:D) 20 | 21 | Returns a string that is a canonical representation of C<$path>. If C<:$parent> 22 | is set to true, will also clean up references to parent directories. B 23 | the routine does not access the filesystem, so no symlinks are followed. 24 | 25 | IO::Spec::QNX.canonpath("foo//../bar/../ber").say; 26 | # OUTPUT: «foo/../bar/../ber␤» 27 | 28 | IO::Spec::QNX.canonpath("foo///./../bar/../ber").say; 29 | # OUTPUT: «foo/../bar/../ber␤» 30 | 31 | IO::Spec::QNX.canonpath("foo///./../bar/../ber", :parent).say; 32 | # OUTPUT: «ber␤» 33 | 34 | =end pod 35 | -------------------------------------------------------------------------------- /doc/Type/Macro.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Macro 4 | 5 | =SUBTITLE Compile-time routine 6 | 7 | class Macro is Routine { } 8 | 9 | A macro is a Routine whose invocation typically happens during 10 | parsing. By returning an L|/type/AST>, a macro can inject code into 11 | the calling location. 12 | 13 | =end pod 14 | -------------------------------------------------------------------------------- /doc/Type/Metamodel/ConcreteRoleHOW.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("metamodel") 2 | 3 | =TITLE role Metamodel::ConcreteRoleHOW 4 | 5 | =SUBTITLE Provides an implementation of a concrete instance of a role 6 | 7 | =for code :skip-test 8 | class Metamodel::ConcreteRoleHOW 9 | does Metamodel::Naming 10 | does Metamodel::Versioning 11 | does Metamodel::PrivateMethodContainer 12 | does Metamodel::MethodContainer 13 | does Metamodel::MultiMethodContainer 14 | does Metamodel::AttributeContainer 15 | does Metamodel::RoleContainer 16 | does Metamodel::MultipleInheritance 17 | does Metamodel::ArrayType 18 | does Metamodel::Concretization {} 19 | 20 | I: this class is part of the Rakudo implementation, and is not 21 | a part of the language specification. 22 | 23 | You can use this to build roles, in the same way that C can be used to 24 | build classes: 25 | 26 | =for code 27 | my $a = Metamodel::ConcreteRoleHOW.new_type(name => "Bar"); 28 | $a.^compose; 29 | say $a.^roles; # OUTPUT: «(Mu)␤» 30 | 31 | The main difference with 32 | L|/type/Metamodel::ClassHOW#method_new_type> is that you 33 | can mix-in roles in this newly created one. 34 | 35 | This class is Rakudo specific, and provided only for completeness. Not really 36 | intended to be used by the final user. 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Type/Metamodel/Finalization.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("metamodel") 2 | 3 | =TITLE role Metamodel::Finalization 4 | 5 | =SUBTITLE Metaobject supporting object finalization 6 | 7 | X<|Reference,DESTROY metamodel> 8 | 9 | role Metamodel::Finalization { ... } 10 | 11 | I: this role is part of the Rakudo implementation, and is not 12 | a part of the language specification. 13 | 14 | This role takes care that C submethods are called (if they 15 | exist) when an object is garbage-collected. 16 | 17 | =head1 Methods 18 | 19 | =head2 method setup_finalization 20 | 21 | method setup_finalization($obj) 22 | 23 | Collects the C submethods from this class and all its 24 | superclasses, and marks the class as needing action on garbage 25 | collection. 26 | 27 | A metamodel for a kind that implements finalization semantics must call 28 | this method at type composition time. 29 | 30 | =head2 method destroyers 31 | 32 | method destroyers($obj --> List:D) 33 | 34 | Returns a list of all finalization methods. 35 | 36 | =end pod 37 | -------------------------------------------------------------------------------- /doc/Type/Metamodel/Naming.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("metamodel") 2 | 3 | =TITLE role Metamodel::Naming 4 | 5 | =SUBTITLE Metaobject that supports named types 6 | 7 | role Metamodel::Naming { } 8 | 9 | I: this role is part of the Rakudo implementation, and is not 10 | a part of the language specification. 11 | 12 | L role for (optionally) named things, like classes, 13 | roles and enums. 14 | 15 | =head1 Methods 16 | 17 | =head2 method name 18 | 19 | method name($type) 20 | 21 | Returns the name of the metaobject, if any. 22 | 23 | say 42.^name; # OUTPUT: «Int␤» 24 | 25 | =head2 method set_name 26 | 27 | method set_name($type, $new_name) 28 | 29 | Sets the new name of the metaobject. 30 | 31 | =end pod 32 | -------------------------------------------------------------------------------- /doc/Type/Metamodel/PackageHOW.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("metamodel") 2 | 3 | =TITLE class Metamodel::PackageHOW 4 | 5 | =SUBTITLE Metaobject representing a Raku package. 6 | 7 | class Metamodel::PackageHOW 8 | does Metamodel::Naming 9 | does Metamodel::Documenting 10 | does Metamodel::Stashing 11 | does Metamodel::TypePretense 12 | does Metamodel::MethodDelegation { } 13 | 14 | I: this class is part of the Rakudo implementation, and is not 15 | a part of the language specification. 16 | 17 | C is the metaclass behind the C keyword. 18 | 19 | package P {}; 20 | say P.HOW; # OUTPUT: «Perl6::Metamodel::PackageHOW.new␤» 21 | 22 | =head1 Methods 23 | 24 | =head2 method archetypes 25 | 26 | method archetypes() 27 | 28 | Returns the archetypes for this model, that is, the properties a metatype can 29 | implement. 30 | 31 | =head2 method new 32 | 33 | method new(*%named) 34 | 35 | Creates a new C. 36 | 37 | =head2 method new_type 38 | 39 | method new_type(:$name = '', :$repr, :$ver, :$auth) 40 | 41 | Creates a new package, with optional representation, version and auth field. 42 | 43 | =head2 compose 44 | 45 | method compose($obj, :$compiler_services) 46 | 47 | Sets the metapackage as composed. 48 | 49 | =head2 is_composed 50 | 51 | method is_composed($obj) 52 | 53 | Returns the composed status of the metapackage. 54 | 55 | =end pod 56 | -------------------------------------------------------------------------------- /doc/Type/Metamodel/ParametricRoleGroupHOW.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("metamodel") 2 | 3 | =TITLE role Metamodel::ParametricRoleGroupHOW 4 | 5 | =SUBTITLE Represents a group of roles with different parameterizations 6 | 7 | class Metamodel::ParametricRoleGroupHOW 8 | does Metamodel::Naming 9 | does Metamodel::Documenting 10 | does Metamodel::Stashing 11 | does Metamodel::TypePretense 12 | does Metamodel::RolePunning 13 | does Metamodel::BoolificationProtocol {} 14 | 15 | I: this role is part of the Rakudo implementation, and is not 16 | a part of the language specification. 17 | 18 | A C groups a set of C, every one of them representing a single role declaration with their own parameter sets. 19 | 20 | =for code 21 | (role Zape[::T] {}).HOW.say; # OUTPUT: «Perl6::Metamodel::ParametricRoleHOW.new␤» 22 | Zape.HOW.say ; # OUTPUT: «Perl6::Metamodel::ParametricRoleGroupHOW.new␤» 23 | 24 | Cs need to be added to this kind of group: 25 | 26 | =for code 27 | my \zape := Metamodel::ParametricRoleGroupHOW.new_type( name => "zape"); 28 | my \zipi := Metamodel::ParametricRoleHOW.new_type( name => "zipi", group => zape); 29 | say zipi.HOW; # OUTPUT: «Perl6::Metamodel::ParametricRoleHOW.new␤» 30 | 31 | I: As most of the C classes, this class is here mainly for 32 | illustration purposes and it's not intended for the final user to instantiate. 33 | 34 | =end pod 35 | -------------------------------------------------------------------------------- /doc/Type/Metamodel/RoleContainer.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("metamodel") 2 | 3 | =TITLE role Metamodel::RoleContainer 4 | 5 | =SUBTITLE Metaobject that supports holding/containing roles 6 | 7 | role Metamodel::RoleContainer {} 8 | 9 | I: this role is part of the Rakudo implementation, and is not 10 | a part of the language specification. 11 | 12 | Implements the ability to hold roles to be held for composition. 13 | 14 | =for code :preamble 15 | class A does SomeRole {} 16 | 17 | roughly corresponds to 18 | 19 | =for code :preamble 20 | class A { 21 | BEGIN A.^add_role(SomeRole); 22 | } 23 | 24 | =head1 Methods 25 | 26 | =head2 method add_role 27 | 28 | method add_role($obj, Mu $role) 29 | 30 | Adds the C<$role> to the list of roles to be composed. 31 | 32 | =head2 method roles_to_compose 33 | 34 | method roles_to_compose($obj --> List:D) 35 | 36 | returns a list of roles added with C, which are to be composed 37 | at type composition time. 38 | 39 | =end pod 40 | -------------------------------------------------------------------------------- /doc/Type/Metamodel/RolePunning.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("metamodel") 2 | 3 | =TITLE role Metamodel::RolePunning 4 | 5 | =SUBTITLE Metaobject that supports I of roles. 6 | 7 | role Perl6::Metamodel::RolePunning {} 8 | 9 | I: this role is part of the Rakudo implementation, and is not 10 | a part of the language specification. 11 | 12 | Implements the ability to create objects from Cs without the intermediate 13 | need to use a class. Not intended to be used directly (will in fact error if 14 | it's Cd), but via punning of roles, as below. This is also Rakudo specific 15 | and not part of the spec. 16 | 17 | =for code 18 | role A { 19 | method b { 20 | return "punned" 21 | } 22 | }; 23 | my $a = A.new; 24 | say $a.b; # OUTPUT: «punned␤» 25 | 26 | =end pod 27 | -------------------------------------------------------------------------------- /doc/Type/Mixy.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("composite") 2 | 3 | =TITLE role Mixy 4 | 5 | =SUBTITLE Collection of distinct objects with Real weights 6 | 7 | role Mixy does Baggy { } 8 | 9 | A role for collections of weighted values. See L|/type/Mix> and L|/type/MixHash>. 10 | C objects differ from L|/type/Baggy> objects in that the weights of 11 | C are L|/type/Real>s rather than L|/type/Int>s. 12 | 13 | =head1 Methods 14 | 15 | =head2 method roll 16 | 17 | method roll($count = 1) 18 | 19 | Similar to a L|/type/Bag>.roll, but with L|/type/Real> weights rather than integral 20 | ones. 21 | 22 | =head2 method pick 23 | 24 | method pick($?) 25 | 26 | Throws an exception. The feature is not supported on the type, since there's no 27 | clear value to subtract from non-integral weights, to make it work. 28 | 29 | =head2 method grab 30 | 31 | method grab($?) 32 | 33 | Throws an exception. The feature is not supported on the type, since there's no 34 | clear value to subtract from non-integral weights, to make it work. 35 | 36 | =head2 method kxxv 37 | 38 | method kxxv() 39 | 40 | Throws an exception. The feature is not supported on the type, since there's no 41 | clear value to subtract from non-integral weights, to make it work. 42 | 43 | =head1 See Also 44 | 45 | L 46 | 47 | =end pod 48 | -------------------------------------------------------------------------------- /doc/Type/NFC.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("composite") 2 | 3 | =TITLE class NFC 4 | 5 | =SUBTITLE Codepoint string in Normal Form C (composed) 6 | 7 | class NFC is Uni {} 8 | 9 | A Codepoint string in Unicode Normalization Form C. It is created by Canonical Decomposition, 10 | followed by Canonical Composition. For more information on what this means, see 11 | L. 12 | 13 | =end pod 14 | -------------------------------------------------------------------------------- /doc/Type/NFD.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("composite") 2 | 3 | =TITLE class NFD 4 | 5 | =SUBTITLE Codepoint string in Normal Form D (decomposed) 6 | 7 | class NFD is Uni {} 8 | 9 | A Codepoint string in the "D" L 10 | 11 | =end pod 12 | -------------------------------------------------------------------------------- /doc/Type/NFKC.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("composite") 2 | 3 | =TITLE class NFKC 4 | 5 | =SUBTITLE Codepoint string in Normal Form KC (compatibility composed) 6 | 7 | class NFKC is Uni {} 8 | 9 | A Codepoint string in Unicode Normalization Form KC. It is created by Compatibility Decomposition, 10 | followed by Canonical Composition. For more information on what this means, see 11 | L. 12 | =end pod 13 | -------------------------------------------------------------------------------- /doc/Type/NFKD.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("composite") 2 | 3 | =TITLE class NFKD 4 | 5 | =SUBTITLE Codepoint string in Normal Form KD (compatibility decomposed) 6 | 7 | class NFKD is Uni {} 8 | 9 | A Codepoint string in Unicode Normalization Form KD. It is created by Compatibility Decomposition. 10 | For more information on what this means, see L. 11 | 12 | =end pod 13 | -------------------------------------------------------------------------------- /doc/Type/ObjAt.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class ObjAt 4 | 5 | =SUBTITLE Unique identification for an object 6 | 7 | class ObjAt is Any {} 8 | 9 | Objects of type C are the return value of C<.WHICH> calls on other 10 | objects, and identify an object uniquely. 11 | 12 | If two objects compare equally via C<===>, their C<.WHICH> methods return 13 | the same ObjAt object. 14 | 15 | See also L|/type/ValueObjAt> for value types. 16 | 17 | =head1 Methods 18 | 19 | =head2 infix eqv 20 | 21 | multi infix:(ObjAt:D $a, ObjAt:D $b) 22 | 23 | Returns True if the two ObjAt are the same, that is, if the object they identify 24 | is the same. 25 | 26 | my @foo = [2,3,1]; 27 | my @bar := @foo; 28 | say @foo.WHICH eqv @bar.WHICH; # OUTPUT: «True␤» 29 | 30 | =end pod 31 | -------------------------------------------------------------------------------- /doc/Type/Order.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("enum") :category("domain-specific") 2 | 3 | =TITLE enum Order 4 | 5 | =SUBTITLE Human readable form for comparison operators. 6 | X<|Reference,Less>X<|Reference,Same>X<|Reference,More> 7 | 8 | enum Order (:Less(-1), :Same(0), :More(1)); 9 | 10 | =head1 Operators 11 | 12 | =head2 infix cmp 13 | 14 | multi infix:(\a, \b --> Order:D) 15 | 16 | C will first try to compare operands as strings (via coercion to L|/type/Stringy>), and, failing that, will try to compare numerically via the C«<=>» operator or any other type-appropriate comparison operator. See also L operator|/routine/cmp#(Operators)_infix_cmp>. 17 | 18 | 19 | =head2 infix C«<=>» 20 | 21 | multi infix:«<=>»(Int:D \a, Int:D \b --> Order:D) 22 | 23 | Specialized form for Int. 24 | 25 | =end pod 26 | -------------------------------------------------------------------------------- /doc/Type/Perl.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Perl 4 | 5 | =SUBTITLE Perl related information 6 | 7 | class Perl is Raku { } 8 | 9 | A class that provides the same internal language information as the 10 | L class. Only maintained for historical reasons. 11 | 12 | =end pod 13 | -------------------------------------------------------------------------------- /doc/Type/Pod/Block.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Block 4 | 5 | =SUBTITLE Block in a Pod document 6 | 7 | class Pod::Block { } 8 | 9 | Class for a Pod block, and base class for most other Pod classes. 10 | 11 | A Pod block has contents (more pod blocks or strings) and a config hash. 12 | 13 | Useful subclasses: 14 | 15 | =begin table 16 | 17 | Class Used for 18 | ===== ======== 19 | Pod::Block::Para paragraphs 20 | 21 | Pod::Block::Named named blocks 22 | 23 | Pod::Block::Declarator declarator blocks 24 | 25 | Pod::Block::Code code blocks 26 | 27 | Pod::Block::Comment comments 28 | 29 | Pod::Block::Table =begin/end table 30 | tabular data 31 | 32 | Pod::Heading =head1 etc. headings 33 | 34 | Pod::Item list items 35 | 36 | Pod::Defn definition lists 37 | 38 | Pod::FormattingCode formatting codes 39 | 40 | =end table 41 | 42 | =head1 Methods 43 | 44 | =head2 method contents 45 | 46 | method contents(--> Positional:D) 47 | 48 | Returns a list of contents of this block. 49 | 50 | =head2 method config 51 | 52 | method config(--> Map:D) 53 | 54 | Returns a hash of configs. 55 | 56 | =end pod 57 | -------------------------------------------------------------------------------- /doc/Type/Pod/Block/Code.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Block::Code 4 | 5 | =SUBTITLE Verbatim code block in a Pod document 6 | 7 | class Pod::Block::Code is Pod::Block { } 8 | 9 | Class for a code (verbatim) Pod block. 10 | 11 | =end pod 12 | -------------------------------------------------------------------------------- /doc/Type/Pod/Block/Comment.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Block::Comment 4 | 5 | =SUBTITLE Comment in a Pod document 6 | 7 | class Pod::Block::Comment is Pod::Block { } 8 | 9 | Class for a Pod comment. 10 | 11 | =end pod 12 | -------------------------------------------------------------------------------- /doc/Type/Pod/Block/Declarator.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Block::Declarator 4 | 5 | =SUBTITLE Declarator block in a Pod document 6 | 7 | class Pod::Block::Declarator is Pod::Block { } 8 | 9 | Class for a declarator Pod block 10 | 11 | =head1 Methods 12 | 13 | =head2 method leading 14 | 15 | method leading(Pod::Block::Declarator:D:) 16 | 17 | Returns the leading Pod comment attached to the declarator 18 | 19 | =head2 method trailing 20 | 21 | method trailing(Pod::Block::Declarator:D:) 22 | 23 | Returns the trailing Pod comment attached to the declarator 24 | 25 | =head2 method WHEREFORE 26 | 27 | method WHEREFORE(--> Mu) 28 | 29 | Returns the code object or metaobject to which the Pod block is attached to 30 | 31 | =end pod 32 | -------------------------------------------------------------------------------- /doc/Type/Pod/Block/Named.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Block::Named 4 | 5 | =SUBTITLE Named block in a Pod document 6 | 7 | class Pod::Block::Named is Pod::Block { } 8 | 9 | Class for a named Pod block. For example 10 | 11 | =begin code 12 | =begin MySection 13 | ... 14 | =end MySection 15 | =end code 16 | 17 | creates a C with name C. 18 | 19 | =head1 Methods 20 | 21 | =head2 method name 22 | 23 | method name(--> Str:D) 24 | 25 | Returns the name of the block. 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/Pod/Block/Para.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Block::Para 4 | 5 | =SUBTITLE Paragraph in a Pod document 6 | 7 | class Pod::Block::Para is Pod::Block { } 8 | 9 | Class for a Pod paragraph. 10 | 11 | =end pod 12 | -------------------------------------------------------------------------------- /doc/Type/Pod/Block/Table.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Block::Table 4 | 5 | =SUBTITLE Table in a Pod document 6 | 7 | class Pod::Block::Table is Pod::Block { } 8 | 9 | Class for a table in a Pod document. 10 | 11 | =head1 Methods 12 | 13 | =head2 method caption 14 | 15 | method caption(--> Str:D) 16 | 17 | Returns the associated caption of the table. 18 | 19 | =head2 method headers 20 | 21 | method headers(--> Positional:D) 22 | 23 | Returns a list of table headers. If no headers have been defined the 24 | list is empty. 25 | 26 | =end pod 27 | -------------------------------------------------------------------------------- /doc/Type/Pod/Defn.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Defn 4 | 5 | =SUBTITLE Pod definition list 6 | 7 | class Pod::Defn is Pod::Block { } 8 | 9 | Class for definition lists in a Pod document. 10 | 11 | =head1 Methods 12 | 13 | =head2 method term 14 | 15 | method term(--> Mu) 16 | 17 | =end pod 18 | -------------------------------------------------------------------------------- /doc/Type/Pod/FormattingCode.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::FormattingCode 4 | 5 | =SUBTITLE Pod formatting code 6 | 7 | class Pod::FormattingCode is Pod::Block { } 8 | 9 | Class for formatting codes in a Pod document. 10 | 11 | =head1 Methods 12 | 13 | =head2 method type 14 | 15 | method type(--> Mu) 16 | 17 | =head2 method meta 18 | 19 | method meta(--> Positional) 20 | 21 | =end pod 22 | -------------------------------------------------------------------------------- /doc/Type/Pod/Heading.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Heading 4 | 5 | =SUBTITLE Heading in a Pod document 6 | 7 | class Pod::Heading is Pod::Block { } 8 | 9 | Class for headings in a Pod document. 10 | 11 | =head1 Methods 12 | 13 | =head2 method level 14 | 15 | method level(--> Int) 16 | 17 | Returns the level of the heading, starting at 1. 18 | 19 | =end pod 20 | -------------------------------------------------------------------------------- /doc/Type/Pod/Item.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Pod::Item 4 | 5 | =SUBTITLE Item in a Pod enumeration list 6 | 7 | class Pod::Item is Pod::Block { } 8 | 9 | Class for items in Pod enumeration lists. 10 | 11 | =head1 Methods 12 | 13 | =head2 method level 14 | 15 | method level(--> Int) 16 | 17 | Returns the level of the enumeration list, starting at 1. 18 | 19 | =end pod 20 | -------------------------------------------------------------------------------- /doc/Type/Proxy.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Proxy 4 | 5 | =SUBTITLE Item container with custom storage and retrieval 6 | 7 | class Proxy {} 8 | 9 | A Proxy is an object that allows you to set a hook that executes whenever a 10 | value is retrieved from a container (C) or when it is set (C). 11 | Please note that C can introduce mutability at places where it would 12 | break behavior, e.g. in L|/type/Hash> keys. 13 | 14 | To create a container that returns twice what was stored in it, you do something 15 | like this: 16 | 17 | =begin code :method 18 | sub double() is rw { 19 | my $storage = 0; 20 | Proxy.new( 21 | FETCH => method () { $storage * 2 }, 22 | STORE => method ($new) { $storage = $new }, 23 | ) 24 | } 25 | my $doubled := double(); 26 | $doubled = 4; 27 | say $doubled; # OUTPUT: «8␤» 28 | =end code 29 | 30 | =head1 Methods 31 | 32 | =head2 method new 33 | 34 | method new(:&FETCH!, :&STORE! --> Proxy:D) 35 | 36 | Creates a new C object. C<&FETCH> is called with one argument (the 37 | proxy object) when the value is accessed, and must return the value that the 38 | fetch produces. C<&STORE> is called with two arguments (the proxy object, and 39 | the new value) when a new value is stored in the container. 40 | 41 | =end pod 42 | -------------------------------------------------------------------------------- /doc/Type/PseudoStash.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("composite") 2 | 3 | =TITLE class PseudoStash 4 | 5 | =SUBTITLE Stash type for pseudo-packages 6 | 7 | class PseudoStash is Map { } 8 | 9 | C is the stash type (hanging off C<.WHO>) that backs 10 | various pseudo-packages. So, when you do C or C, that 11 | gives back a C. In most cases, C gives 12 | back a L|/type/Stash>. Neither of these are objects the user is expected to 13 | create by themselves, but in case you have one, you can just use it like a 14 | hash. 15 | 16 | =for code 17 | my $a = 42; 18 | my $b = q/$a/; 19 | say MY::{$b}; 20 | # OUTPUT: «42␤» 21 | 22 | This shows how you can use a C to look up variables, by name, 23 | at runtime. 24 | 25 | =end pod 26 | -------------------------------------------------------------------------------- /doc/Type/Raku.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Raku 4 | 5 | =SUBTITLE Raku related information 6 | 7 | class Raku does Systemic { } 8 | 9 | Built-in class for providing information related to the implementation of 10 | the Raku language. Usually accessed through the L<$*RAKU|/language/variables#index-entry-%24*RAKU> 11 | dynamic variable. 12 | 13 | =head1 Methods 14 | 15 | =head2 method compiler 16 | 17 | Instance method returning the L object, of type 18 | L|/type/Compiler>, associated with the Raku object. 19 | 20 | =head2 method DISTROnames 21 | 22 | Instance / Class method returning the names of the L|/type/Distro> 23 | objects that are supported by this version of Raku. 24 | 25 | =head2 method KERNELnames 26 | 27 | Instance / Class method returning the names of the L|/type/Kernel> 28 | objects that are supported by this version of Raku. 29 | 30 | =head2 method VMnames 31 | 32 | Instance / Class method returning the names of the L|/type/VM> objects that 33 | are supported by this version of Raku. 34 | 35 | =head1 See Also 36 | 37 | L|/type/Systemic>, L|/type/Compiler>. 38 | 39 | =end pod 40 | -------------------------------------------------------------------------------- /doc/Type/Routine/WrapHandle.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Routine::WrapHandle 4 | 5 | =SUBTITLE Holds all information needed to unwrap a wrapped routine. 6 | 7 | class WrapHandle { ... } 8 | 9 | C is a I created and returned by 10 | L. Its only use is to unwrap wrapped routines. 11 | Either call L on a routine object or call 12 | the method C on a C object. 13 | 14 | sub f() { say 'f was called' } 15 | my $wrap-handle = &f.wrap({ say 'before'; callsame; say 'after' }); 16 | f; # OUTPUT: «before␤f was called␤after␤» 17 | $wrap-handle.restore; 18 | f; # OUTPUT: «f was called␤» 19 | 20 | As such private class, it may suffer any kind of changes without prior notice. 21 | It is only mentioned here since it is visible by the user who checks the return 22 | type of the C method. 23 | 24 | =head1 Methods 25 | 26 | =head2 method restore 27 | 28 | method restore(--> Bool:D) 29 | 30 | Unwraps a wrapped routine and returns C on success. 31 | 32 | =end pod 33 | -------------------------------------------------------------------------------- /doc/Type/Stash.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("composite") 2 | 3 | =TITLE class Stash 4 | 5 | =SUBTITLE Table for "our"-scoped symbols 6 | 7 | class Stash is Hash { } 8 | 9 | A C is a hash that is used for symbol tables at the package scoping level 10 | in Raku. 11 | 12 | To get a Stash, you can call the C<.WHO> pseudo-method on a package (because it 13 | answers the question I), or if you write the package name as 14 | a literal, append two colons: 15 | 16 | class Boring { 17 | class Nested { }; 18 | our sub package_sub { } 19 | my sub lexical { }; 20 | method a_method() { } 21 | } 22 | say Boring::.^name; # OUTPUT: «Stash␤» 23 | say Boring.WHO === Boring::; # OUTPUT: «True␤» 24 | 25 | Since it inherits from L|/type/Hash>, you can use all the usual hash 26 | functionality: 27 | 28 | =for code :skip-test 29 | say Boring::.keys.sort; # OUTPUT: «(&package_sub Nested)␤» 30 | say Boring::; # OUTPUT: «(Nested)␤» 31 | 32 | As the example above shows only "our"-scoped things appear in the C 33 | (nested classes are "our" by default, but can be excluded with "my".) Lexicals 34 | and methods are not included in a Stash, since they do not live in the package 35 | table. Lexicals live in a separate lexical pad, which is only visible from 36 | inside the scope. Methods (in the case that the package is also a class) have 37 | a separate method table, and are accessible through introspection on the 38 | class itself, via C<.can> and C<.^methods>. 39 | 40 | =end pod 41 | -------------------------------------------------------------------------------- /doc/Type/Stringy.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("basic") 2 | 3 | =TITLE role Stringy 4 | 5 | =SUBTITLE String or object that can act as a string 6 | 7 | role Stringy { ... } 8 | 9 | Common role for string types (such as Str). 10 | 11 | =end pod 12 | -------------------------------------------------------------------------------- /doc/Type/Supplier/Preserving.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Supplier::Preserving 4 | 5 | =SUBTITLE Cached live Supply factory 6 | 7 | class Supplier::Preserving is Supplier { } 8 | 9 | This is a factory for live L|/type/Supply>-type objects, and it 10 | provides the mechanism for emitting new values onto the supplies, whereby 11 | values are kept when no consumer has tapped into the L|/type/Supply>. Any tapping 12 | will consume the already stored and future values. 13 | 14 | Starting a preserving L|/type/Supply> and consuming its values after it is C: 15 | 16 | my $p = Supplier::Preserving.new; 17 | start for ^3 { 18 | $p.emit($_); 19 | LAST { 20 | say „done after { now - BEGIN now}s“; 21 | $p.done; 22 | } 23 | } 24 | sleep 2; 25 | react { 26 | whenever $p.Supply { $_.say; } 27 | whenever Promise.in(2) { done } 28 | } 29 | say „also done after { now - BEGIN now }s“ 30 | 31 | Will output: 32 | 33 | =for code :lang 34 | done after 0.0638467s 35 | 0 36 | 1 37 | 2 38 | also done after 4.0534119s 39 | 40 | =head1 Methods 41 | 42 | =head2 method new 43 | 44 | method new() 45 | 46 | The L|/type/Supplier> constructor. 47 | 48 | =end pod 49 | -------------------------------------------------------------------------------- /doc/Type/Tap.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Tap 4 | 5 | =SUBTITLE Subscription to a Supply 6 | 7 | class Tap {} 8 | 9 | A Tap is a subscription to a L|/type/Supply>. 10 | 11 | my $s = Supplier.new; 12 | my $tap = $s.Supply.on-close({ say "Tap closed" }).tap( 13 | -> $v { say "the value is $v" }, 14 | done => { say "Supply is done" }, 15 | quit => -> $ex { say "Supply finished with error $ex" }, 16 | ); 17 | 18 | # later 19 | $tap.close; 20 | 21 | =head1 Methods 22 | 23 | =head2 method close 24 | 25 | method close(Tap:D:) 26 | 27 | Closes the tap. 28 | 29 | =end pod 30 | -------------------------------------------------------------------------------- /doc/Type/Telemetry/Instrument/Thread.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Telemetry::Instrument::Thread 4 | 5 | =SUBTITLE Instrument for collecting Thread data 6 | 7 | class Telemetry::Instrument::Thread { } 8 | 9 | B This class is a Rakudo-specific feature and not standard Raku. 10 | 11 | Objects of this class are generally not created by themselves, but rather 12 | through making a Lshot. 13 | 14 | This class provides the following data points (in alphabetical order): 15 | 16 | =item tad 17 | 18 | The number of threads that ended with an exception (Bhreads-BborteB). 19 | 20 | =item tcd 21 | 22 | The number of threads that completed without any problem 23 | (Bhreads-BompleteB). 24 | 25 | =item thid 26 | 27 | Highest OS thread ID seen (Bhread-Bighest-B). 28 | 29 | =item tjd 30 | 31 | The number of threads that were joined (Bhreads-BoineB). 32 | 33 | =item tsd 34 | 35 | The number of threads that were started (Bhreads-BtarteB). 36 | 37 | =item tyd 38 | 39 | The number of times a thread was yielded (Bhreads-BieldeB). 40 | 41 | =end pod 42 | -------------------------------------------------------------------------------- /doc/Type/Telemetry/Period.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class Telemetry::Period 4 | 5 | =SUBTITLE Performance data over a period 6 | 7 | =begin code :preamble 8 | class Telemetry::Period is Telemetry { } 9 | =end code 10 | 11 | B This class is a Rakudo-specific feature and not standard Raku. 12 | 13 | =begin code 14 | # basic usage 15 | use Telemetry; 16 | my $t0 = Telemetry.new; 17 | # execute some code 18 | my $t1 = Telemetry.new; 19 | my $period = $t1 - $t0; # creates Telemetry::Period object 20 | say "Code took $period microseconds to execute"; 21 | =end code 22 | 23 | A C object contains the difference between two 24 | L|/type/Telemetry> objects. It is generally not created by calling 25 | .new, but it can be if needed. For all practical purposes, it is the same as 26 | the L|/type/Telemetry> object, but the B of the values is different (and 27 | the values are generally much smaller, as they usually are the difference of 28 | two big values of the L|/type/Telemetry> objects from which it was created). 29 | 30 | =end pod 31 | -------------------------------------------------------------------------------- /doc/Type/ThreadPoolScheduler.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class ThreadPoolScheduler 4 | 5 | =SUBTITLE Scheduler that distributes work among a pool of threads 6 | 7 | =begin code :skip-test 8 | class ThreadPoolScheduler does Scheduler {} 9 | =end code 10 | 11 | The C has a range of number of threads that it maintains, 12 | and it distributes work among those threads. When the upper limit of threads 13 | isn't reached yet, and there is work pending, it spawns new threads to handle 14 | the work. 15 | 16 | =head1 Methods 17 | 18 | =head2 new 19 | 20 | =for code 21 | method new(Int :$initial_threads = 0, Int :$max_threads = 8 * Kernel.cpu-cores) 22 | 23 | Creates a new C object with the given range of threads to 24 | maintain. 25 | 26 | The default value for C<:initial_threads> is B<0>, so no threads will be 27 | started when a C object is created by default. 28 | 29 | The default value for C<:max_threads> is B<64>, unless there appear to be 30 | more than 8 CPU cores available. In that case the default will be 8 times 31 | the number of CPU cores. 32 | 33 | See also the L 34 | environment variable to set the default maximum number of threads. 35 | 36 | As of release 2022.06 of the Rakudo compiler, it is also possible to specify 37 | C or C<*> as a value for C<:max_threads>, indicating that the maximum 38 | number of threads allowed by the operating system, will be used. 39 | 40 | =end pod 41 | -------------------------------------------------------------------------------- /doc/Type/UInt.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE Subset UInt 4 | 5 | =SUBTITLE Unsigned integer (arbitrary-precision) 6 | 7 | The C is defined as a subset of L|/type/Int>: 8 | 9 | =for code 10 | my subset UInt of Int where {not .defined or $_ >= 0}; 11 | 12 | Consequently, it cannot be instantiated or subclassed; however, that shouldn't affect most normal uses. 13 | 14 | Some examples of its behavior and uses: 15 | 16 | say UInt ~~ Int; # OUTPUT: «True␤» 17 | my UInt $u = 0xffff_ffff_ffff_ffff_ffff_ffff_ffff_ffff; # 64-bit unsigned value 18 | say $u.base(16); # OUTPUT: «FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF␤» (32 digits) 19 | ++$u; 20 | say $u.base(16); # OUTPUT: «100000000000000000000000000000000␤» (33 digits!) 21 | my Int $i = $u; 22 | say $i.base(16); # same as above 23 | say $u.^name; # OUTPUT: «Int␤» - UInt is a subset, so the type is still Int. 24 | say $i.^name; # OUTPUT: «Int␤» 25 | # Difference in assignment 26 | my UInt $a = 5; # nothing wrong 27 | my UInt $b = -5; # Exception about failed type check 28 | my UInt $c = 0; 29 | --$c; # Exception again 30 | CATCH { default { put .^name, ': ', .Str } }; 31 | # OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $b; expected UInt but got Int (-5)␤» 32 | 33 | # Non-assignment operations are fine 34 | my UInt $d = 0; 35 | say $d - 3; # OUTPUT: «-3␤» 36 | 37 | =end pod 38 | -------------------------------------------------------------------------------- /doc/Type/Unicode.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("domain-specific") 2 | 3 | =TITLE class Unicode 4 | 5 | =SUBTITLE Unicode related information 6 | 7 | class Unicode { } 8 | 9 | Built-in class for providing Unicode related information. Although it 10 | can be instantiated, these methods currently mostly make sense when called 11 | as class methods. In which case they represent the information of the 12 | supported version of Unicode in the current runtime. 13 | 14 | Available as of release 2023.02 of the Rakudo compiler. Available as an 15 | L for earlier 16 | versions of the Rakudo compiler. 17 | 18 | =head1 Methods 19 | 20 | =head2 method version 21 | 22 | method version(Unicode:) 23 | 24 | Returns a L«C|/type/Version» object representing the Unicode 25 | version. 26 | 27 | say Unicode.version; # OUTPUT: «v15.0␤» 28 | 29 | =head2 method NFG 30 | 31 | method NFG(Unicode:) 32 | 33 | Returns a L«C|/type/Bool» indicating whether complete 34 | L«C|/language/glossary#NFG» support is 35 | available. 36 | 37 | # on MoarVM 38 | say Unicode.NFG; # OUTPUT: «True␤» 39 | 40 | # on JVM 41 | say Unicode.NFG; # OUTPUT: «False␤» 42 | 43 | =end pod 44 | -------------------------------------------------------------------------------- /doc/Type/ValueObjAt.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("basic") 2 | 3 | =TITLE class ValueObjAt 4 | 5 | =SUBTITLE Unique identification for value types 6 | 7 | class ValueObjAt is ObjAt { } 8 | 9 | A subclass of L|/type/ObjAt> that should be used to indicate that a class 10 | produces objects that are value types - in other words, that are immutable after 11 | they have been initialized. 12 | 13 | my %h = a => 42; # mutable Hash 14 | say %h.WHICH; # OUTPUT: «ObjAt.new("Hash|1402...888")␤» 15 | 16 | my %m is Map = a => 42; # immutable Map 17 | say %m.WHICH; # OUTPUT: «ValueObjAt.new("Map|AAF...09F61F")␤» 18 | 19 | If you create a class that should be considered a value type, you should add 20 | a C method to that class that returns a C object, for 21 | instance: 22 | 23 | class YourClass { 24 | has $.foo; # note these are not mutable 25 | has $.bar; 26 | 27 | method WHICH() { 28 | ValueObjAt.new("YourClass|$!foo|$!bar"); 29 | } 30 | } 31 | 32 | Note that it is customary to always start the identifying string with the 33 | name of the object, followed by a "|". This to prevent confusion with other 34 | classes that may generate similar string values: the name of the class should 35 | then be enough of a differentiator to prevent collisions. 36 | 37 | =end pod 38 | -------------------------------------------------------------------------------- /doc/Type/X/Anon/Augment.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Anon::Augment 4 | 5 | =SUBTITLE Compilation error due to augmenting an anonymous package 6 | 7 | class X::Anon::Augment does X::Comp { } 8 | 9 | Compile time error thrown when trying to augment an anonymous package. 10 | 11 | For example 12 | 13 | =for code :skip-test 14 | use MONKEY-TYPING; 15 | augment class { } 16 | 17 | Dies with 18 | 19 | =for code :lang 20 | Cannot augment anonymous class 21 | 22 | =head1 Methods 23 | 24 | =head2 method package-kind 25 | 26 | method package-kind returns Str:D 27 | 28 | Returns the kind of package (module, class, grammar, ...) that the code 29 | tried to augment. 30 | 31 | =end pod 32 | -------------------------------------------------------------------------------- /doc/Type/X/Anon/Multi.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Anon::Multi 4 | 5 | =SUBTITLE Compilation error due to declaring an anonymous multi 6 | 7 | class X::Anon::Multi does X::Comp { } 8 | 9 | Compile time error thrown when an anonymous multi is being declared. 10 | 11 | For example 12 | 13 | =for code :skip-test 14 | multi method () { } 15 | 16 | dies with 17 | 18 | =for code :lang 19 | Cannot put multi on anonymous method 20 | 21 | =head1 Methods 22 | 23 | =head2 method multiness 24 | 25 | method multiness(--> Str:D) 26 | 27 | Returns a string describing the multiness that the original code used, for 28 | example C<"multi"> or C<"proto">. 29 | 30 | =head2 method routine-type 31 | 32 | method routine-type(--> Str:D) 33 | 34 | Returns a string describing the type of routine that was declared, for example 35 | C<"sub"> or C<"method">. 36 | 37 | =end pod 38 | -------------------------------------------------------------------------------- /doc/Type/X/Assignment/RO.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Assignment::RO 4 | 5 | =SUBTITLE Exception thrown when trying to assign to something read-only 6 | 7 | class X::Assignment::RO is Exception {} 8 | 9 | Code like 10 | 11 | sub f() { 42 }; 12 | f() = 'new value'; # throws an X::Assignment::RO 13 | CATCH { default { put .^name, ': ', .Str } }; 14 | # OUTPUT: «X::Assignment::RO: Cannot modify an immutable Any␤» 15 | 16 | throws an exception of type C. 17 | 18 | =head1 Methods 19 | 20 | =head2 method typename 21 | 22 | method typename(X::Assignment::RO:D: --> Str) 23 | 24 | Returns the type name of the value on the left-hand side 25 | 26 | =end pod 27 | -------------------------------------------------------------------------------- /doc/Type/X/Attribute/NoPackage.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Attribute::NoPackage 4 | 5 | =SUBTITLE Compilation error due to declaring an attribute outside of a package 6 | 7 | class X::Attribute::NoPackage does X::Comp { } 8 | 9 | Compile time error thrown when an attribute is declared where it does 10 | not make sense (for example in the mainline). 11 | 12 | For example 13 | 14 | =for code 15 | has $.x; 16 | 17 | Dies with 18 | 19 | =for code :lang 20 | You cannot declare attribute '$.x' here; maybe you'd like a class or a role? 21 | 22 | =head1 Methods 23 | 24 | =head2 method name 25 | 26 | method name(--> Str:D) 27 | 28 | Returns the name of the attribute 29 | 30 | =end pod 31 | -------------------------------------------------------------------------------- /doc/Type/X/Attribute/Package.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Attribute::Package 4 | 5 | =SUBTITLE Compilation error due to declaring an attribute in an ineligible package 6 | 7 | class X::Attribute::Package does X::Comp { } 8 | 9 | Compile time error, thrown when the compiler encounters an attribute 10 | declaration inside a package that does not support attributes. 11 | 12 | For example 13 | 14 | =for code :skip-test 15 | module A { has $.x } 16 | 17 | dies with 18 | 19 | =for code :lang 20 | A module cannot have attributes, but you tried to declare '$.x' 21 | 22 | =head1 Methods 23 | 24 | =head2 method name 25 | 26 | method name(--> Str:D) 27 | 28 | Returns the name of the attribute that triggered this error. 29 | 30 | =head2 method package-kind 31 | 32 | method package-kind(--> Str:D) 33 | 34 | Returns the kind of package (package, module) that doesn't support attributes. 35 | 36 | =end pod 37 | -------------------------------------------------------------------------------- /doc/Type/X/Attribute/Required.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Attribute::Required 4 | 5 | =SUBTITLE Compilation error due to not declaring an attribute with the C trait 6 | 7 | class X::Attribute::NoPackage does X::MOP { } 8 | 9 | Compile time error thrown when a required attribute is not assigned when 10 | creating an object. 11 | 12 | For example 13 | 14 | =for code 15 | my class Uses-required { 16 | has $.req is required 17 | }; 18 | my $object = Uses-required.new() 19 | 20 | Dies with 21 | 22 | =for code :lang 23 | OUTPUT: «(exit code 1) The attribute '$!req' is required, but you did not provide a value for it.␤» 24 | 25 | =head1 Methods 26 | 27 | =head2 method name 28 | 29 | method name(--> Str:D) 30 | 31 | Returns the name of the attribute. 32 | 33 | =head2 method why 34 | 35 | method why(--> Str:D) 36 | 37 | Returns the reason why that attribute is required, and it will be included in 38 | the message if provided. That reason is taken directly from the C 39 | trait. 40 | 41 | =for code :skip-test 42 | my class Uses-required { 43 | has $.req is required("because yes") 44 | }; 45 | my $object = Uses-required.new(); │ 46 | # OUTPUT: 47 | # «(exit code 1) The attribute '$!req' is required because because yes,␤ 48 | # but you did not provide a value for it.␤» 49 | 50 | 51 | 52 | =end pod 53 | -------------------------------------------------------------------------------- /doc/Type/X/Attribute/Undeclared.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Attribute::Undeclared 4 | 5 | =SUBTITLE Compilation error due to an undeclared attribute 6 | 7 | class X::Attribute::Undeclared is X::Undeclared { } 8 | 9 | Thrown when code refers to an attribute that has not been declared. 10 | 11 | For example the code 12 | 13 | =for code :skip-test 14 | class A { method m { $!notthere } } 15 | 16 | Produces the error 17 | 18 | =for code :lang 19 | Attribute $!notthere not declared in class A 20 | 21 | =head1 Methods 22 | 23 | =head2 method package-kind 24 | 25 | Returns the kind of package the attribute was used in (for example C, 26 | C) 27 | 28 | =head2 method package-name 29 | 30 | Returns the name of the package in which the offensive attribute reference 31 | was performed. 32 | 33 | =end pod 34 | -------------------------------------------------------------------------------- /doc/Type/X/Augment/NoSuchType.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Augment::NoSuchType 4 | 5 | =SUBTITLE Compilation error due to augmenting a non-existing type 6 | 7 | class X::Augment::NoSuchType does X::Comp { } 8 | 9 | Thrown when trying to augment a type which doesn't exist. 10 | 11 | For example 12 | 13 | =for code :skip-test 14 | use MONKEY-TYPING; 15 | augment class NoSuch { } 16 | 17 | dies with 18 | 19 | =for code :lang 20 | You tried to augment class NoSuch, but it does not exist 21 | 22 | =head1 Methods 23 | 24 | =head2 method package-kind 25 | 26 | method package-kind(--> Str:D) 27 | 28 | Returns the kind of package (class, grammar) that is being tried to augment 29 | 30 | =head2 method package 31 | 32 | Returns the name that was tried to augment, but which doesn't exist. 33 | 34 | =end pod 35 | -------------------------------------------------------------------------------- /doc/Type/X/Bind.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Bind 4 | 5 | =SUBTITLE Error due to binding to something that is not a variable or container 6 | 7 | class X::Bind is Exception {} 8 | 9 | If you write code like this: 10 | 11 | =begin code :skip-test 12 | floor(1.1) := 42; 13 | =end code 14 | 15 | it dies with an C exception: 16 | 17 | =begin code :lang 18 | Cannot use bind operator with this left-hand side 19 | =end code 20 | 21 | =end pod 22 | -------------------------------------------------------------------------------- /doc/Type/X/Bind/NativeType.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Bind::NativeType 4 | 5 | =SUBTITLE Compilation error due to binding to a natively typed variable 6 | 7 | class X::Bind::NativeType does X::Comp { } 8 | 9 | Compile-time error thrown when trying to bind to a natively typed variable. 10 | 11 | Since native variables explicitly don't have the concept of a container at 12 | runtime, it does not make sense to support both binding and assignment; 13 | Raku supports only assignment (which makes more sense, because native 14 | types are value types). 15 | 16 | For example the code 17 | 18 | =for code :skip-test 19 | my int $x := 3; 20 | 21 | dies with 22 | 23 | =for code :lang 24 | Cannot bind to natively typed variable '$x'; use assignment instead 25 | 26 | and can be fixed by writing it as 27 | 28 | my int $x = 3; 29 | 30 | =head1 Methods 31 | 32 | =head2 method name 33 | 34 | method name(--> Str:D) 35 | 36 | Returns the name of the variable. 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Type/X/Bind/Slice.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Bind::Slice 4 | 5 | =SUBTITLE Error due to binding to a slice 6 | 7 | class X::Bind::Slice is Exception {} 8 | 9 | When you try to bind to an array or hash slice: 10 | 11 | my @a; @a[0, 1] := [42]; 12 | CATCH { default { put .^name, ': ', .Str } }; 13 | # OUTPUT: «X::Bind::Slice: Cannot bind to Array slice␤» 14 | 15 | and 16 | 17 | my %h; %h := {}; 18 | CATCH { default { put .^name, ': ', .Str } }; 19 | # OUTPUT: «X::Bind::Slice: Cannot bind to Hash slice␤» 20 | 21 | you get an exception of type C<::Bind::Slice>. 22 | 23 | =head1 Methods 24 | 25 | =head2 method type 26 | 27 | method type(X::Bind::Slice:D:) 28 | 29 | returns the type object of the thing that you tried to slice-bind, for example 30 | L|/type/Array>, L|/type/List> or L|/type/Hash>. 31 | 32 | =end pod 33 | -------------------------------------------------------------------------------- /doc/Type/X/Caller/NotDynamic.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Caller::NotDynamic 4 | 5 | =SUBTITLE Error while trying to access a non dynamic variable through CALLER 6 | 7 | class X::Caller::NotDynamic is Exception { } 8 | 9 | Thrown when trying to access a non dynamic variable through CALLER 10 | 11 | A typical error message is 12 | 13 | =for code :lang 14 | Cannot access '$x' through CALLER, because it is not declared as dynamic 15 | 16 | =head1 Methods 17 | 18 | =head2 method symbol 19 | 20 | Returns the name of the symbol that was passed to CALLER. 21 | 22 | =end pod 23 | -------------------------------------------------------------------------------- /doc/Type/X/Cannot/Empty.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Cannot::Empty 4 | 5 | =SUBTITLE Error due to inappropriate usage of an empty collection 6 | 7 | class X::Cannot::Empty is Exception { } 8 | 9 | Error, typically wrapped in a L|/type/Failure>, when inappropriately 10 | using an empty collection. 11 | 12 | For example, the following stack implementation fails when trying to pop a value 13 | from an empty stack. Sink context causes the returned L|/type/Failure> to throw. 14 | 15 | =begin code 16 | class Stack { 17 | my class Node { 18 | has $.value; 19 | has Node $.next; 20 | } 21 | has Node $!next; 22 | 23 | method push($value) { 24 | $!next .= new(:$value, :$!next); 25 | self; 26 | } 27 | 28 | method pop() { 29 | fail X::Cannot::Empty.new(:action, :what(self.^name)) 30 | unless $!next; 31 | 32 | my $value = $!next.value; 33 | $!next .= next; 34 | $value; 35 | } 36 | } 37 | 38 | my $stack = Stack.new.push(42); 39 | say $stack.pop; # OUTPUT: «42␤» 40 | try $stack.pop; 41 | say $!.message; # OUTPUT: «Cannot pop from an empty Stack␤» 42 | =end code 43 | 44 | =head1 Methods 45 | 46 | =head2 method action 47 | 48 | method action() 49 | 50 | Verbal description of the inappropriate action. 51 | 52 | =head2 method what 53 | 54 | method what() 55 | 56 | Returns the type that was the target of the action. 57 | 58 | =end pod 59 | -------------------------------------------------------------------------------- /doc/Type/X/Cannot/Lazy.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Cannot::Lazy 4 | 5 | =SUBTITLE Error due to inappropriate usage of a lazy list 6 | 7 | class X::Cannot::Lazy is Exception { } 8 | 9 | Error thrown (or wrapped in a L|/type/Failure>) when inappropriately using a 10 | list that C<.is-lazy>. Such a list can be infinite which would make it 11 | impossible to iterate over all values. 12 | 13 | =head1 Methods 14 | 15 | =head2 method action 16 | 17 | method action() 18 | 19 | Verbal description of the inappropriate action. 20 | 21 | =head2 method what 22 | 23 | method what() 24 | 25 | Returns the type that was the target of the action, if it was not the 26 | lazy list itself. 27 | 28 | =end pod 29 | -------------------------------------------------------------------------------- /doc/Type/X/Channel/ReceiveOnClosed.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Channel::ReceiveOnClosed 4 | 5 | =SUBTITLE Error due to calling receive on a closed channel 6 | 7 | class X::Channel::ReceiveOnClosed {} 8 | 9 | This exception is thrown when a calling C on a L|/type/Channel> that has been closed: 10 | 11 | my $s = Channel.new; 12 | $s.close; 13 | $s.receive; # Cannot receive a message on a closed channel 14 | CATCH { default { put .^name, ': ', .Str } }; 15 | # OUTPUT: «X::Channel::ReceiveOnClosed: Cannot receive a message on a closed channel␤» 16 | 17 | =head1 Methods 18 | 19 | =head2 method channel 20 | 21 | method Channel(X::Channel::ReceiveOnClosed:D: --> Channel:D) 22 | 23 | Returns the Channel object on which the C method was called. 24 | 25 | =end pod 26 | -------------------------------------------------------------------------------- /doc/Type/X/Channel/SendOnClosed.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Channel::SendOnClosed 4 | 5 | =SUBTITLE Error due to calling send on a closed channel 6 | 7 | class X::Channel::SendOnClosed {} 8 | 9 | This exception is thrown when a calling C on a L|/type/Channel> that has been closed: 10 | 11 | my $s = Channel.new; 12 | $s.close; 13 | $s.send(42); 14 | CATCH { default { put .^name, ': ', .Str } }; 15 | # OUTPUT: «X::Channel::SendOnClosed: Cannot send a message on a closed channel␤» 16 | 17 | =head1 Methods 18 | 19 | =head2 method channel 20 | 21 | method Channel(X::Channel::SendOnClosed:D: --> Channel:D) 22 | 23 | Returns the Channel object on which the C method was called. 24 | 25 | =end pod 26 | -------------------------------------------------------------------------------- /doc/Type/X/Comp.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("exception") 2 | 3 | =TITLE role X::Comp 4 | 5 | =SUBTITLE Common role for compile-time errors 6 | 7 | role X::Comp is Exception { } 8 | 9 | Common role for compile-time errors. 10 | 11 | Note that since the backtrace of a compile time error generally shows 12 | routines from the compiler, not from user-space programs, the L|/type/Backtrace> 13 | returned from the L method is not very informative. Instead 14 | the exception carries its own C, C and C attributes 15 | and public accessors. 16 | 17 | If an error occurs while creating an object (like a class or routine) at 18 | compile time, generally the exception associated with it does not hold a 19 | reference to the object (for example a class would not be fully composed, and 20 | thus not usable). In those cases the name of the would-be-created object 21 | is included in the error message instead. 22 | 23 | =head1 Methods 24 | 25 | =head2 method filename 26 | 27 | The filename in which the compilation error occurred 28 | 29 | =head2 method line 30 | 31 | The line number in which the compilation error occurred. 32 | 33 | =head2 method column 34 | 35 | The column number of location where the compilation error occurred. 36 | (Rakudo does not implement that yet). 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Type/X/Composition/NotComposable.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Composition::NotComposable 4 | 5 | =SUBTITLE Compilation error due to composing an ineligible type 6 | 7 | class X::Composition::NotComposable is Exception { } 8 | 9 | Thrown when trying to compose a type into a target type, but the composer type 10 | cannot be used for composition (roles and enums are generally OK). 11 | 12 | For example 13 | 14 | =for code :skip-test 15 | class B { } 16 | class C does B { } 17 | 18 | dies with 19 | 20 | =for code :lang 21 | ===SORRY!=== 22 | ␤B is not composable, so C cannot compose it 23 | 24 | because C is reserved for role composition, and C is not a role, 25 | nor something that knows how to turn into a role. 26 | 27 | The fix is to either make C a role, or use inheritance 28 | (C) instead. 29 | 30 | =head1 Methods 31 | 32 | =head2 method target-name 33 | 34 | method target-name(--> Str:D) 35 | 36 | Returns the name of the type that should be composed, but failed. 37 | 38 | =head2 method composer 39 | 40 | method composer(--> Mu) 41 | 42 | Returns the type that should be composed into the target, but which isn't a 43 | role. 44 | 45 | =end pod 46 | -------------------------------------------------------------------------------- /doc/Type/X/Constructor/Positional.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Constructor::Positional 4 | 5 | =SUBTITLE Error due to passing positional arguments to a default constructor 6 | 7 | class X::Constructor::Positional is Exception { } 8 | 9 | Thrown from L when positional arguments are passed to it. 10 | 11 | For example 12 | 13 | class A { }; 14 | A.new(2, 3); 15 | CATCH { default { put .^name, ': ', .Str } }; 16 | # OUTPUT: «X::Constructor::Positional: Default constructor for 'A' only takes named arguments␤» 17 | 18 | =end pod 19 | -------------------------------------------------------------------------------- /doc/Type/X/Control.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE role X::Control 4 | 5 | =SUBTITLE Role for control exceptions 6 | 7 | role X::Control is Exception { } 8 | 9 | This role turns an exception into a 10 | L, such as 11 | L|/type/CX::Next> or L|/type/CX::Take>. It has got no code other than the definition. 12 | 13 | Since Rakudo 2019.03, Cing an object that mixes in this role 14 | C can raise a control exception which is caught by the L instead of L. 16 | This allows to define custom control exceptions. 17 | 18 | For example, the custom C control exception we define below: 19 | 20 | =begin code 21 | class CX::Vaya does X::Control { 22 | has $.message 23 | } 24 | 25 | sub ea { 26 | CONTROL { 27 | default { 28 | say "Controlled { .^name }: { .message }" 29 | } 30 | } 31 | CX::Vaya.new( message => "I messed up!" ).throw; 32 | 33 | } 34 | ea; 35 | # OUTPUT: «Controlled CX::Vaya: I messed up!␤» 36 | =end code 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Type/X/ControlFlow.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::ControlFlow 4 | 5 | =SUBTITLE Error due to calling a loop control command in an ineligible scope 6 | 7 | class X::ControlFlow is Exception { } 8 | 9 | Thrown when a control flow construct (such as C or C) is called 10 | outside the dynamic scope of an enclosing construct that is supposed to catch 11 | them. 12 | 13 | For example 14 | 15 | last; 16 | CATCH { default { put .^name, ': ', .Str } }; 17 | # OUTPUT: «X::ControlFlow: last without loop construct␤» 18 | 19 | =head1 Methods 20 | 21 | =head2 method illegal 22 | 23 | method illegal returns Str:D 24 | 25 | Returns the name of the control flow command that was called. 26 | 27 | =head2 method enclosing 28 | 29 | method enclosing returns Str:D 30 | 31 | Returns the name of the missing enclosing construct. 32 | 33 | =end pod 34 | -------------------------------------------------------------------------------- /doc/Type/X/ControlFlow/Return.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::ControlFlow::Return 4 | 5 | =SUBTITLE Error due to calling return outside a routine 6 | 7 | class X::ControlFlow::Return is X::ControlFlow { } 8 | 9 | Thrown when a C is called from outside a routine. 10 | 11 | return; 12 | CATCH { default { put .^name, ': ', .Str } }; 13 | # OUTPUT: «X::ControlFlow::Return: Attempt to return outside of any Routine␤» 14 | 15 | =end pod 16 | -------------------------------------------------------------------------------- /doc/Type/X/DateTime/TimezoneClash.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::DateTime::TimezoneClash 4 | 5 | =SUBTITLE Error due to using both time zone offset and :timezone 6 | 7 | =for code :skip-test 8 | class X::DateTime::TimezoneClash does X::Temporal is Exception { } 9 | 10 | This exception is thrown when code tries to create a L|/type/DateTime> object 11 | specifying both a time zone offset and the named argument C<:timezone>. 12 | 13 | =for code 14 | say DateTime.new('2015-12-24T12:23:00+0200'); # works 15 | say DateTime.new('2015-12-24T12:23:00', timezone => 7200); # works 16 | say DateTime.new('2015-12-24T12:23:00+0200', timezone => 7200); # exception 17 | 18 | =head1 Methods 19 | 20 | =head2 method message 21 | 22 | method message() 23 | 24 | Returns 'DateTime.new(Str): :timezone argument not allowed with a timestamp 25 | offset' 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/X/Declaration/Scope.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Declaration::Scope 4 | 5 | =SUBTITLE Compilation error due to a declaration with an ineligible scope 6 | 7 | =for code 8 | class X::Declaration::Scope does X::Comp { } 9 | 10 | Compile time error thrown when a declaration does not harmonize with the 11 | declared scope. 12 | 13 | For example 14 | 15 | =for code :skip-test 16 | has sub f() { } 17 | 18 | dies with 19 | 20 | =for code :lang 21 | ===SORRY!=== 22 | Cannot use 'has' with sub declaration 23 | 24 | =head1 Methods 25 | 26 | =head2 method scope 27 | 28 | method scope(--> Str:D) 29 | 30 | Returns a string representation of the scope, usually the same keyword that is 31 | used for the declaration (C<"my">, C<"our">, C<"has">, ...); 32 | 33 | =head2 method declaration 34 | 35 | method declaration(--> Str:D) 36 | 37 | Describes the symbol that has been declared in a wrong scope. 38 | 39 | =end pod 40 | -------------------------------------------------------------------------------- /doc/Type/X/Declaration/Scope/Multi.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Declaration::Scope::Multi 4 | 5 | =SUBTITLE Compilation error due to declaring a multi with an ineligible scope 6 | 7 | class X::Declaration::Scope::Multi is X::Declaration::Scope { } 8 | 9 | Thrown when a multi is declared with an incompatible scope. 10 | 11 | For example C dies with 12 | 13 | =for code :lang 14 | ===SORRY!=== 15 | Cannot use 'our' with individual multi candidates. Please declare an our-scoped proto instead 16 | 17 | =end pod 18 | -------------------------------------------------------------------------------- /doc/Type/X/Does/TypeObject.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Does::TypeObject 4 | 5 | =SUBTITLE Error due to mixing into a type object 6 | 7 | class X::Does::TypeObject is Exception {} 8 | 9 | When you try to add one or more roles to a type object with C after it 10 | has been composed, an error of type C is thrown: 11 | 12 | =for code 13 | Mu does Numeric; # Cannot use 'does' operator with a type object. 14 | 15 | The correct way to apply roles to a type is at declaration time: 16 | 17 | =for code :skip-test 18 | class GrassmannNumber does Numeric { ... }; 19 | role AlgebraDebugger does IO { ... }; 20 | grammar IntegralParser does AlgebraParser { ... }; 21 | 22 | Roles may only be runtime-mixed into defined object instances: 23 | 24 | =for code :skip-test 25 | GrassmannNumber.new does AlgebraDebugger; 26 | 27 | (This restriction may be worked around by using 28 | L, or 29 | with dark Metamodel magics, but this will likely result in a 30 | significant performance penalty.) 31 | 32 | =head1 Methods 33 | 34 | =head2 method type 35 | 36 | method type(X::Does::TypeObject:D: --> Mu:U) 37 | 38 | Returns the type object into which the code tried to mix in a role. 39 | 40 | =end pod 41 | -------------------------------------------------------------------------------- /doc/Type/X/Dynamic/NotFound.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Dynamic::NotFound 4 | 5 | =SUBTITLE Runtime error thrown when a dynamic variable does not exist 6 | 7 | class X::Dynamic::NotFound is Exception {} 8 | 9 | This exception is raised when a dynamic variable that has not been declared 10 | is used. 11 | 12 | =for code 13 | $*dynamic-not-found = 33; 14 | # OUTPUT: «Dynamic variable $*dynamic-not-found not found␤» 15 | 16 | =head1 Methods 17 | 18 | =head2 method name 19 | 20 | method name(--> Str:D) 21 | 22 | Returns the name of the variable that has not been found. 23 | 24 | =end pod 25 | -------------------------------------------------------------------------------- /doc/Type/X/Eval/NoSuchLang.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Eval::NoSuchLang 4 | 5 | =SUBTITLE Error due to specifying an unknown language for EVAL 6 | 7 | class X::Eval::NoSuchLang is Exception { } 8 | 9 | Error thrown when C specifies a language that the 10 | compiler does not know how to handle. 11 | 12 | For example 13 | 14 | EVAL 'boo', lang => "bar"; 15 | CATCH { default { put .^name, ': ', .Str } }; 16 | # OUTPUT: «X::Eval::NoSuchLang: No compiler available for language 'bar'␤» 17 | 18 | 19 | =head1 Methods 20 | 21 | =head2 method lang 22 | 23 | method lang() 24 | 25 | Returns the language that L did not know how to handle. 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/X/Export/NameClash.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Export::NameClash 4 | 5 | =SUBTITLE Compilation error due to exporting the same symbol twice 6 | 7 | class X::Export::NameClash does X::Comp { } 8 | 9 | Compile time error thrown when a symbol is exported twice. 10 | 11 | For example 12 | 13 | =for code :skip-test 14 | sub f() is export { }; 15 | { 16 | sub f() is export { } 17 | } 18 | 19 | 20 | dies with 21 | 22 | =for code :lang 23 | ===SORRY!=== 24 | A symbol '&f' has already been exported 25 | 26 | =head1 Methods 27 | 28 | =head2 method symbol 29 | 30 | Returns the symbol that is exported twice. 31 | 32 | =end pod 33 | -------------------------------------------------------------------------------- /doc/Type/X/IO.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("exception") 2 | 3 | =TITLE role X::IO 4 | 5 | =SUBTITLE IO related error 6 | 7 | role X::IO does X::OS {} 8 | 9 | Common role for IO related errors. 10 | 11 | This role does not provide any additional methods. 12 | 13 | =end pod 14 | -------------------------------------------------------------------------------- /doc/Type/X/IO/BinaryMode.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::BinaryMode 4 | 5 | =SUBTITLE Error while invoking methods on a handle in binary mode. 6 | 7 | =for code :skip-test 8 | class X::IO::BinaryMode does X::IO is Exception { } 9 | 10 | Thrown from certain L|/type/IO::Handle> methods if the handle is L. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Cannot do 'comb' on a handle in binary mode. 16 | 17 | =head1 Methods 18 | 19 | =head2 method trying 20 | 21 | Returns a string describing the failed operation; in this example, C. 22 | 23 | =end pod 24 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Chdir.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Chdir 4 | 5 | =SUBTITLE Error while trying to change the working directory 6 | 7 | =for code :skip-test 8 | class X::IO::Chdir does X::IO is Exception { } 9 | 10 | Error class when a L call failed. 11 | 12 | For example 13 | 14 | =for code 15 | chdir '/home/other' 16 | 17 | throws 18 | 19 | =for code :lang 20 | Failed to change the working directory to '/home/other': permission denied 21 | 22 | =head1 Methods 23 | 24 | =head2 method path 25 | 26 | Returns the path that was passed to the failed C call. 27 | 28 | =end pod 29 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Chmod.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Chmod 4 | 5 | =SUBTITLE Error while trying to change file permissions 6 | 7 | =for code :skip-test 8 | class X::IO::Chmod does X::IO is Exception { } 9 | 10 | Error class for failed C calls. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to set the mode of '/home/other' to '0o777': Permission denied 16 | 17 | =end pod 18 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Chown.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Chown 4 | 5 | =SUBTITLE Error while trying to change file ownership 6 | 7 | =for code :skip-test 8 | class X::IO::Chown does X::IO is Exception { } 9 | 10 | Error class for failed C calls. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to change owner of '/home/other' to :137/666: Permission denied 16 | 17 | =end pod 18 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Copy.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Copy 4 | 5 | =SUBTITLE Error while trying to copy a file 6 | 7 | =for code :skip-test 8 | class X::IO::Copy does X::IO is Exception { } 9 | 10 | Error class for failed file copy operations. A typical error message is 11 | 12 | =for code :lang 13 | Failed to copy 'source' to 'destination': permission denied 14 | 15 | =head1 Methods 16 | 17 | =head2 method from 18 | 19 | Returns the source of the failed copy operation 20 | 21 | =head2 method to 22 | 23 | Returns the destination of the failed copy operation 24 | 25 | =end pod 26 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Cwd.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Cwd 4 | 5 | =SUBTITLE Error while trying to determine the current working directory 6 | 7 | =for code :skip-test 8 | class X::IO::Cwd does X::IO is Exception { } 9 | 10 | Error class when the runtime fails to determine the current directory. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to get the working directory: permission denied 16 | 17 | =end pod 18 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Dir.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Dir 4 | 5 | =SUBTITLE Error while trying to get a directory's contents 6 | 7 | =for code :skip-test 8 | class X::IO::Dir does X::IO is Exception { } 9 | 10 | Error class that is thrown when a L call fails. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to get the directory contents of '/tmp/': No such file or directory 16 | 17 | =head1 Methods 18 | 19 | =head2 method path 20 | 21 | Returns the path that L failed to read. 22 | 23 | =end pod 24 | -------------------------------------------------------------------------------- /doc/Type/X/IO/DoesNotExist.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::DoesNotExist 4 | 5 | =SUBTITLE Error while doing file tests on a non existing path 6 | 7 | =for code :skip-test 8 | class X::IO::DoesNotExist does X::IO is Exception { } 9 | 10 | Thrown when doing file test operations on a non existing path. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to find 'euler-5.raku' while trying to do '.f' 16 | 17 | =head1 Methods 18 | 19 | =head2 method path 20 | 21 | Returns the path that was passed to the failed call. 22 | 23 | =head2 method trying 24 | 25 | Returns a string describing the failed operation. 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Link.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Link 4 | 5 | =SUBTITLE Error while trying to create a link 6 | 7 | =for code :skip-test 8 | class X::IO::Link does X::IO is Exception { } 9 | 10 | Error class for failed L operation. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to create link called 'my-link' on target 'does-not exist': Failed to link file 16 | 17 | =head1 Methods 18 | 19 | =head2 method target 20 | 21 | Returns the name of the link target, i.e. the existing file. 22 | 23 | =head2 method name 24 | 25 | Returns the name of the link that could not be created. 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Mkdir.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Mkdir 4 | 5 | =SUBTITLE Error while trying to create a directory 6 | 7 | =for code :skip-test 8 | class X::IO::Mkdir does X::IO is Exception { } 9 | 10 | Error class for failed L operations. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to create directory 'destination' with mode '0o755': File exists 16 | 17 | =head1 Methods 18 | 19 | =head2 method path 20 | 21 | Returns the path that the L operation failed to create. 22 | 23 | =head2 method mode 24 | 25 | Returns the permissions mask of the failed L operation as an L|/type/Int>. 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Move.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Move 4 | 5 | =SUBTITLE Error while trying to move a file 6 | 7 | =for code :skip-test 8 | class X::IO::Move does X::IO is Exception { } 9 | 10 | Error class for a failed file move operation. A typical 11 | error message is 12 | 13 | =for code :lang 14 | Failed to move '/tmp/alpha.raku' to 'test.raku': :createonly specified and destination exists 15 | 16 | =head1 Methods 17 | 18 | =head2 method from 19 | 20 | Returns the source of the failed L operation 21 | 22 | =head2 method to 23 | 24 | Returns the destination of the failed L operation 25 | 26 | =end pod 27 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Rename.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Rename 4 | 5 | =SUBTITLE Error while trying to rename a file or directory 6 | 7 | =for code :skip-test 8 | class X::IO::Rename does X::IO is Exception { } 9 | 10 | Error class for failed file or directory rename operations. A typical 11 | error message is 12 | 13 | =for code :lang 14 | Failed to rename 'source' to 'destination': is a directory 15 | 16 | =head1 Methods 17 | 18 | =head2 method from 19 | 20 | Returns the source of the failed rename operation 21 | 22 | =head2 method to 23 | 24 | Returns the destination of the failed rename operation 25 | 26 | =end pod 27 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Rmdir.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Rmdir 4 | 5 | =SUBTITLE Error while trying to remove a directory 6 | 7 | =for code :skip-test 8 | my class X::IO::Rmdir does X::IO is Exception { } 9 | 10 | Error class for failed L operations. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to remove the directory 'lib': Directory not empty 16 | 17 | =head1 Methods 18 | 19 | =head2 method path 20 | 21 | Returns the path L failed to remove 22 | 23 | =end pod 24 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Symlink.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Symlink 4 | 5 | =SUBTITLE Error while trying to create a symbolic link 6 | 7 | =for code :skip-test 8 | class X::IO::Symlink does X::IO is Exception { } 9 | 10 | Error class for failed L creation. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to create symlink called 'euler' on target '/home/myhome/euler-1.raku': Failed to symlink file: file already exist 16 | 17 | =head1 Methods 18 | 19 | =head2 method name 20 | 21 | Returns the path that L failed to create. 22 | 23 | =head2 method target 24 | 25 | Returns the path that L failed to create a link to. 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/X/IO/Unlink.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::IO::Unlink 4 | 5 | =SUBTITLE Error while trying to remove a file 6 | 7 | =for code :skip-test 8 | class X::IO::Unlink does X::IO is Exception { } 9 | 10 | Error class for failed L operation. 11 | 12 | A typical error message is 13 | 14 | =for code :lang 15 | Failed to remove the file 'secret': Permission defined 16 | 17 | =head1 Methods 18 | 19 | =head2 method path 20 | 21 | Returns the path that L failed to delete. 22 | 23 | =end pod 24 | -------------------------------------------------------------------------------- /doc/Type/X/Inheritance/Unsupported.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Inheritance::Unsupported 4 | 5 | =SUBTITLE Compilation error due to inheriting from an ineligible type 6 | 7 | class X::Inheritance::Unsupported does X::Comp { } 8 | 9 | Compile time error thrown when trying to inherit from a type that does 10 | not support inheritance (like a package or an enum). 11 | 12 | For example 13 | 14 | =for code :skip-test 15 | enum E ; 16 | class B is E { }; 17 | 18 | dies with 19 | 20 | =for code :lang 21 | ===SORRY!=== 22 | E does not support inheritance, so B cannot inherit from it 23 | 24 | =head1 Methods 25 | 26 | =head2 method child-typename 27 | 28 | The name of the type that tries to inherit. 29 | 30 | =head2 method parent 31 | 32 | The type object that the child tried to inherit from. 33 | 34 | =end pod 35 | -------------------------------------------------------------------------------- /doc/Type/X/Method/InvalidQualifier.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Method::InvalidQualifier 4 | 5 | =SUBTITLE Error due to calling a qualified method from an ineligible class 6 | 7 | class X::Method::InvalidQualifier is Exception { } 8 | 9 | Thrown when a method is call in the form C<$invocant.TheClass::method> if 10 | C<$invocant> does not conform to C. 11 | 12 | For example 13 | 14 | 1.Str::split(/a/); 15 | CATCH { default { put .^name, ': ', .Str } }; 16 | # OUTPUT: «X::Method::InvalidQualifier: Cannot dispatch to method split on Str because it is not inherited or done by Int␤» 17 | 18 | =head1 Methods 19 | 20 | =head2 method method 21 | 22 | method method(--> Str:D) 23 | 24 | Returns the name of the (unqualified) method. 25 | 26 | =head2 method invocant 27 | 28 | Returns the invocant of the failed, qualified method call 29 | 30 | =head2 method qualifier-type 31 | 32 | Returns the type by which the method call was qualified. 33 | 34 | =end pod 35 | -------------------------------------------------------------------------------- /doc/Type/X/Method/NotFound.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Method::NotFound 4 | 5 | =SUBTITLE Error due to calling a method that isn't there 6 | 7 | class X::Method::NotFound is Exception {} 8 | 9 | Thrown when the user tries to call a method that isn't there. 10 | 11 | For example 12 | 13 | =for code 14 | 1.no-such 15 | 16 | throws 17 | 18 | =for code :lang 19 | No such method 'no-such' for invocant of type 'Int' 20 | 21 | =head1 Methods 22 | 23 | =head2 method method 24 | 25 | method method(--> Str:D) 26 | 27 | Returns the method name that was invoked. 28 | 29 | =head2 method typename 30 | 31 | method typename(--> Str:D) 32 | 33 | Returns the name of the invocant type. 34 | 35 | =head2 method private 36 | 37 | method private(--> Bool:D) 38 | 39 | Returns C for private methods, and C for public methods. 40 | 41 | =head2 method addendum 42 | 43 | method addendum(--> Str:D) 44 | 45 | Returns additional explanations or hints. 46 | 47 | I: C was introduced in Rakudo 2019.03. 48 | 49 | =end pod 50 | -------------------------------------------------------------------------------- /doc/Type/X/Method/Private/Permission.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Method::Private::Permission 4 | 5 | =SUBTITLE Compilation error due to calling a private method without permission 6 | 7 | class X::Method::Private::Permission does X::Comp { } 8 | 9 | Compile time error thrown when the code contains a call to a private method 10 | that isn't defined in the current class, and when no appropriate trusts 11 | relation is defined that permits the private method call. 12 | 13 | For example 14 | 15 | =for code :skip-test 16 | 1!Int::foo 17 | 18 | dies with 19 | 20 | =for code :lang 21 | ===SORRY!=== 22 | Cannot call private method 'foo' on package Int because it does not trust GLOBAL 23 | 24 | =head1 Methods 25 | 26 | =head2 method method 27 | 28 | method method(--> Str:D) 29 | 30 | The name of the private method 31 | 32 | =head2 method source-package 33 | 34 | method source-package(--> Mu:D) 35 | 36 | Returns the type object that (supposedly) contains the private method. 37 | 38 | =head2 method calling-package 39 | 40 | method calling-package(--> Mu:D) 41 | 42 | Returns the package in which the calling code is, and which the source package 43 | does not trust. 44 | 45 | =end pod 46 | -------------------------------------------------------------------------------- /doc/Type/X/Method/Private/Unqualified.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Method::Private::Unqualified 4 | 5 | =SUBTITLE Compilation error due to an unqualified private method call 6 | 7 | class X::Method::Private::Unqualified does X::Comp { } 8 | 9 | Compile time error thrown when a private method call on anything but C 10 | is not fully qualified. 11 | 12 | For example 13 | 14 | =for code 15 | 1!priv 16 | 17 | dies with 18 | 19 | =for code :lang 20 | ===SORRY!=== 21 | Private method call to priv must be fully qualified with the package containing the method 22 | 23 | =head1 Methods 24 | 25 | =head2 method method 26 | 27 | method method(--> Str:D) 28 | 29 | Returns the name of the private method that triggered the error. 30 | 31 | =end pod 32 | -------------------------------------------------------------------------------- /doc/Type/X/Mixin/NotComposable.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Mixin::NotComposable 4 | 5 | =SUBTITLE Error due to using an ineligible type as a mixin 6 | 7 | class X::Mixin::NotComposable is Exception { } 8 | 9 | Thrown when a mixin with infix C or C is done with a composer that 10 | cannot be used for mixin. 11 | 12 | For example 13 | 14 | class B { }; 15 | 1 but B; 16 | CATCH { default { put .^name, ': ', .Str } }; 17 | # OUTPUT: «X::Mixin::NotComposable: Cannot mix in non-composable type B into object of type Int␤» 18 | 19 | The compile-time equivalent of this error is L|/type/X::Composition::NotComposable>. 20 | 21 | =head1 Methods 22 | 23 | =head2 method target 24 | 25 | method target() 26 | 27 | Returns the target of the failed mixin operation. 28 | 29 | =head2 method rolish 30 | 31 | method rolish() 32 | 33 | Returns the thing that could not act as a role for mixing it in 34 | 35 | =end pod 36 | -------------------------------------------------------------------------------- /doc/Type/X/NoDispatcher.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::NoDispatcher 4 | 5 | =SUBTITLE Error due to calling a dispatch command in an ineligible scope 6 | 7 | class X::NoDispatcher is Exception { } 8 | 9 | When a redispatcher like C is called without being in the 10 | dynamic scope of a call where a redispatch is possible, an X::NoDispatcher is 11 | thrown. 12 | 13 | For example 14 | 15 | nextsame; # In the mainline 16 | CATCH { default { put .^name, ': ', .Str } }; 17 | # OUTPUT: «X::NoDispatcher: nextsame is not in the dynamic scope of a dispatcher␤» 18 | 19 | =head1 Methods 20 | 21 | =head2 method redispatcher 22 | 23 | method redispatcher(--> Str:D) 24 | 25 | Returns the name of the redispatcher function that did not succeed. 26 | 27 | =end pod 28 | -------------------------------------------------------------------------------- /doc/Type/X/Numeric/CannotConvert.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Numeric::CannotConvert 4 | 5 | =SUBTITLE Error while trying to coerce a number to another type 6 | 7 | class X::Numeric::CannotConvert is Exception { } 8 | 9 | Occurs when an attempt to coerce an L|/type/Num#Inf> or 10 | a L|/type/Num#NaN> to a L|/type/Numeric> type. 11 | 12 | 13 | For example 14 | 15 | say Inf.Int; 16 | CATCH { default { put .^name, ': ', .Str } }; 17 | # OUTPUT: «X::Numeric::CannotConvert: Cannot convert Inf to Int␤» 18 | 19 | Most other conversion errors throw L|/type/X::Numeric::Real>. 20 | 21 | =head1 Methods 22 | 23 | =head2 method source 24 | 25 | method source() 26 | 27 | Returns the value that failed to coerce. 28 | 29 | =head2 method target 30 | 31 | method target() 32 | 33 | Returns the type to which the coercion was attempted. 34 | 35 | =head2 method reason 36 | 37 | method reason(--> Str:D) 38 | 39 | Returns the reason that the conversion failed. 40 | 41 | =end pod 42 | -------------------------------------------------------------------------------- /doc/Type/X/Numeric/DivideByZero.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Numeric::DivideByZero 4 | 5 | =SUBTITLE Error while trying to divide by zero 6 | 7 | class X::Numeric::DivideByZero is Exception { } 8 | 9 | Occurs when attempting to divide by zero. 10 | 11 | For example: 12 | 13 | say 1 / 0; 14 | CATCH { default { put .^name, ': ', .Str } }; 15 | # OUTPUT: «X::Numeric::DivideByZero: Attempt to divide by zero when coercing Rational to Str␤» 16 | 17 | Note that the error is only thrown when you attempt to do something with the result. A simple 18 | 19 | 1/0; # no Error 20 | 21 | will only generate a silent Failure. It's the C in the first example that triggers the exception. 22 | 23 | =head1 Methods 24 | 25 | =head2 method using 26 | 27 | method using() 28 | 29 | If present, returns the name of the operator used, e.g. C>. 30 | 31 | =head2 method details 32 | 33 | method details() 34 | 35 | If present, contains some details on the operation that caused the failure. 36 | 37 | =head2 method numerator 38 | 39 | method numerator() 40 | 41 | If present, returns the numerator of the operation. 42 | 43 | =end pod 44 | -------------------------------------------------------------------------------- /doc/Type/X/Numeric/Real.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Numeric::Real 4 | 5 | =SUBTITLE Error while trying to coerce a number to a Real type 6 | 7 | class X::Numeric::Real is Exception { } 8 | 9 | Occurs when an attempt to coerce a L|/type/Numeric> to a 10 | L|/type/Real>, L|/type/Num>, L|/type/Int> or 11 | L|/type/Rat> fails (due to a number with a nonzero imaginary part, for instance). 12 | 13 | For example 14 | 15 | say (1+2i).Int; 16 | CATCH { default { put .^name, ': ', .Str } }; 17 | # OUTPUT: «X::Numeric::Real: Can not convert 1+2i to Int: imaginary part not zero␤» 18 | 19 | =head1 Methods 20 | 21 | =head2 method source 22 | 23 | method source(--> Numeric:D) 24 | 25 | Returns the number that failed to coerce to L|/type/Real>. 26 | 27 | =head2 method target 28 | 29 | method target() 30 | 31 | Returns the type to which the coercion was attempted. 32 | 33 | =head2 method reason 34 | 35 | method reason(--> Str:D) 36 | 37 | Returns the reason that the conversion failed. 38 | 39 | =end pod 40 | -------------------------------------------------------------------------------- /doc/Type/X/OS.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("role") :category("exception") 2 | 3 | =TITLE role X::OS 4 | 5 | =SUBTITLE Error reported by the operating system 6 | 7 | role X::OS { has $.os-error } 8 | 9 | Common role for all exceptions that are triggered by some error 10 | reported by the operating system (failed IO, system calls, 11 | fork, memory allocation). 12 | 13 | =head1 Methods 14 | 15 | =head2 method os-error 16 | 17 | method os-error(--> Str:D) 18 | 19 | Returns the error as reported by the operating system. 20 | 21 | =end pod 22 | -------------------------------------------------------------------------------- /doc/Type/X/Obsolete.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Obsolete 4 | 5 | =SUBTITLE Compilation error due to use of obsolete syntax 6 | 7 | class X::Obsolete does X::Comp { } 8 | 9 | Syntax error thrown when the user is attempting to use constructs from 10 | other languages. 11 | 12 | For example 13 | 14 | =for code :skip-test 15 | m/abc/i 16 | 17 | dies with 18 | 19 | =for code :lang 20 | ===SORRY!=== 21 | Unsupported use of /i; in Raku please use :i 22 | 23 | =head1 Methods 24 | 25 | =head2 method old 26 | 27 | method old(--> Str:D) 28 | 29 | Returns a textual description of the obsolete syntax construct 30 | 31 | =head2 method replacement 32 | 33 | method replacement(--> Str:D) 34 | 35 | Describes what to use instead of the obsolete syntax. 36 | 37 | =head2 method when 38 | 39 | method when(--> Str:D) 40 | 41 | Returns a string describing the state of the language (usually 42 | C<" in Raku">). 43 | 44 | =end pod 45 | -------------------------------------------------------------------------------- /doc/Type/X/OutOfRange.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::OutOfRange 4 | 5 | =SUBTITLE Error due to indexing outside of an allowed range 6 | 7 | class X::OutOfRange is Exception { } 8 | 9 | General error when something (for example an array index) is out of an allowed 10 | range. 11 | 12 | For example 13 | 14 | say 42[2]; 15 | CATCH { default { put .^name, ': ', .Str } }; 16 | # OUTPUT: «X::OutOfRange: Index out of range. Is: 2, should be in 0..0␤» 17 | 18 | since scalars generally act as a one-element list. 19 | 20 | =head1 Methods 21 | 22 | =head2 method what 23 | 24 | method what(--> Str:D) 25 | 26 | Verbal description of the thing that was out of range (e.g. C<"array index">, 27 | C<"month">). 28 | 29 | =head2 method got 30 | 31 | method got() 32 | 33 | Returns the object that was considered out of range (often an integer) 34 | 35 | =head2 method range 36 | 37 | method range(--> Range:D) 38 | 39 | Returns a L|/type/Range> object describing the permissible range for the object 40 | returned from C<.got>. 41 | 42 | =head2 method comment 43 | 44 | method comment(--> Str) 45 | 46 | Returns an additional comment that is included in the error message. 47 | 48 | =end pod 49 | -------------------------------------------------------------------------------- /doc/Type/X/Package/Stubbed.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Package::Stubbed 4 | 5 | =SUBTITLE Compilation error due to a stubbed package that is never defined 6 | 7 | class X::Package::Stubbed does X::Comp { } 8 | 9 | Thrown at C time when there are packages stubbed but not later defined. 10 | 11 | For example 12 | 13 | =for code :skip-test 14 | class A { ... } # literal ... 15 | class B { ... } # literal ... 16 | 17 | dies with 18 | 19 | =for code :lang 20 | ===SORRY!=== 21 | The following packages were stubbed but not defined: 22 | A 23 | B 24 | 25 | =head1 Methods 26 | 27 | =head2 method packages 28 | 29 | method packages(--> Positional:D) 30 | 31 | Returns a list of packages that were stubbed but not defined. 32 | 33 | =end pod 34 | -------------------------------------------------------------------------------- /doc/Type/X/Parameter/Default.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Parameter::Default 4 | 5 | =SUBTITLE Compilation error due to an unallowed default value in a signature 6 | 7 | class X::Parameter::Default does X::Comp { } 8 | 9 | Compile-time error thrown when a parameter in a signature has default value, 10 | but isn't allowed to have one. That is the case with slurpy parameters 11 | (because a slurpy always binds successfully, even to zero arguments) 12 | and with mandatory parameters. 13 | 14 | Example: 15 | 16 | =for code :skip-test 17 | sub f($x! = 3) { } 18 | 19 | dies with 20 | 21 | =for code :lang 22 | ===SORRY!=== 23 | Cannot put default on required parameter $x 24 | 25 | And 26 | 27 | =for code :skip-test 28 | sub f(*@ = 3) { } 29 | 30 | dies with 31 | 32 | =for code :lang 33 | ===SORRY!=== 34 | Cannot put default on anonymous slurpy parameter 35 | 36 | =head1 Methods 37 | 38 | =head2 method how 39 | 40 | Returns a string describing how the parameter is qualified that makes 41 | it disallow default values, for example C<"slurpy"> or C<"mandatory">. 42 | 43 | =head2 method parameter 44 | 45 | Returns the parameter name 46 | 47 | =end pod 48 | -------------------------------------------------------------------------------- /doc/Type/X/Parameter/MultipleTypeConstraints.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Parameter::MultipleTypeConstraints 4 | 5 | =SUBTITLE Compilation error due to a parameter with multiple type constraints 6 | 7 | class X::Parameter::MultipleTypeConstraints does X::Comp { } 8 | 9 | Compile time error thrown when a parameter has multiple type constraints. 10 | This is not allowed in Raku.0. 11 | 12 | Example: 13 | 14 | =for code :skip-test 15 | sub f(Cool Real $x) { } 16 | 17 | dies with 18 | 19 | =for code :lang 20 | Parameter $x may only have one prefix type constraint 21 | 22 | =head1 Methods 23 | 24 | =head2 method parameter 25 | 26 | Returns the name of the offensive parameter. 27 | 28 | =end pod 29 | -------------------------------------------------------------------------------- /doc/Type/X/Parameter/Placeholder.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Parameter::Placeholder 4 | 5 | =SUBTITLE Compilation error due to an unallowed placeholder in a signature 6 | 7 | class X::Parameter::Placeholder does X::Comp { } 8 | 9 | Thrown when a placeholder parameter is used inside a signature where 10 | a normal parameter is expected. The reason is often that a named parameter 11 | C<:$param> was misspelled as C<$:param>. 12 | 13 | For example 14 | 15 | =for code :skip-test 16 | sub f($:param) { } 17 | 18 | dies with 19 | 20 | =for code :lang 21 | ===SORRY!=== 22 | In signature parameter, placeholder variables like $:param are illegal 23 | you probably meant a named parameter: ':$param' 24 | 25 | =head1 Methods 26 | 27 | =head2 method parameter 28 | 29 | The text of the offensive parameter declaration (C<$:param> in the example 30 | above). 31 | 32 | =head2 method right 33 | 34 | Suggestion on how to write the parameter declaration instead (C<:$param> in 35 | the example above). 36 | 37 | 38 | =end pod 39 | -------------------------------------------------------------------------------- /doc/Type/X/Parameter/Twigil.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Parameter::Twigil 4 | 5 | =SUBTITLE Compilation error due to an unallowed twigil in a signature 6 | 7 | class X::Parameter::Twigil does X::Comp { } 8 | 9 | Thrown when a parameter in a signature has a twigil that it may not have. 10 | Only C, C<.> and C<*> as twigils are allowed. 11 | 12 | Example: 13 | 14 | =for code :skip-test 15 | sub f($=foo) { } 16 | 17 | dies with 18 | 19 | =for code :lang 20 | ===SORRY!=== 21 | In signature parameter $=foo, it is illegal to use the = twigil 22 | 23 | =head1 Methods 24 | 25 | =head2 method parameter 26 | 27 | The name of the offensive parameter (C<$=foo> in the example above) 28 | 29 | =head2 method twigil 30 | 31 | The illegally used twigil. 32 | 33 | =end pod 34 | -------------------------------------------------------------------------------- /doc/Type/X/Parameter/WrongOrder.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Parameter::WrongOrder 4 | 5 | =SUBTITLE Compilation error due to passing parameters in the wrong order 6 | 7 | class X::Parameter::WrongOrder does X::Comp { } 8 | 9 | Compile time error that is thrown when parameters in a signature in the wrong 10 | order (for example if an optional parameter comes before a mandatory 11 | parameter). 12 | 13 | For example 14 | 15 | =for code :skip-test 16 | sub f($a?, $b) { } 17 | 18 | dies with 19 | 20 | =for code :lang 21 | ===SORRY!=== 22 | Cannot put required parameter $b after optional parameters 23 | 24 | =head1 Methods 25 | 26 | =head2 method misplaced 27 | 28 | Returns the kind of misplaced parameter (for example C<"mandatory">, 29 | C<"positional">). 30 | 31 | =head2 method parameter 32 | 33 | Returns the name of the (first) misplaced parameter 34 | 35 | =head2 method after 36 | 37 | Returns a string describing other parameters after which the current parameter 38 | was illegally placed (for example C<"variadic">, C<"positional"> or 39 | C<"optional">). 40 | 41 | =end pod 42 | -------------------------------------------------------------------------------- /doc/Type/X/Phaser/Multiple.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Phaser::Multiple 4 | 5 | =SUBTITLE Compilation error due to multiple phasers of the same type 6 | 7 | class X::Phaser::Multiple does X::Comp { } 8 | 9 | Thrown when multiple phasers of the same type occur in a block, but only one 10 | is allowed (for example C or C). 11 | 12 | For example 13 | 14 | =for code :skip-test 15 | CATCH { }; CATCH { } 16 | 17 | dies with 18 | 19 | =for code :lang 20 | ===SORRY!=== 21 | Only one CATCH block is allowed 22 | 23 | =head1 Methods 24 | 25 | =head2 method block 26 | 27 | Returns the name of the phaser that occurred more than once. 28 | 29 | =end pod 30 | -------------------------------------------------------------------------------- /doc/Type/X/Phaser/PrePost.rakudoc: -------------------------------------------------------------------------------- 1 | =begin pod :kind("Type") :subkind("class") :category("exception") 2 | 3 | =TITLE class X::Phaser::PrePost 4 | 5 | =SUBTITLE Error due to a false return value of a PRE/POST phaser 6 | 7 | =for code 8 | class X::Phaser::PrePost is Exception { } 9 | 10 | Thrown when the condition inside a C
 or C phaser evaluate to a
11 | false value.
12 | 
13 | For example
14 | 
15 |     sub f($x) { PRE { $x ~~ Int } };
16 |     f "foo";
17 |     CATCH { default { put .^name, ': ', .Str } };
18 |     # OUTPUT: X::Phaser::PrePost: Precondition '{ $x ~~ Int }' failed«␤»
19 | 
20 | =head1 Methods
21 | 
22 | =head2 method phaser
23 | 
24 |     method phaser(--> Str:D)
25 | 
26 | Returns the name of the failed phaser, C<"PRE"> or C<"POST">.
27 | 
28 | =head2 method condition
29 | 
30 |     method condition(--> Str:D)
31 | 
32 | Returns the part of the source code that describes the phaser condition.
33 | 
34 | =end pod
35 | 


--------------------------------------------------------------------------------
/doc/Type/X/Placeholder/Block.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Placeholder::Block
 4 | 
 5 | =SUBTITLE Compilation error due to a placeholder in an ineligible block
 6 | 
 7 |     class X::Placeholder::Block does X::Comp {}
 8 | 
 9 | Thrown when a placeholder variable is used in a block that does not allow a
10 | signature.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | class A { $^foo }
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | Placeholder variable $^foo may not be used here because the surrounding block takes no signature
21 | 
22 | =head1 Methods
23 | 
24 | =head2 method placeholder
25 | 
26 | Returns the name of the (first) illegally used placeholder.
27 | 
28 | =end pod
29 | 


--------------------------------------------------------------------------------
/doc/Type/X/Placeholder/Mainline.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Placeholder::Mainline
 4 | 
 5 | =SUBTITLE Compilation error due to a placeholder in the mainline
 6 | 
 7 |     class X::Placeholder::Mainline is X::Placeholder::Block { }
 8 | 
 9 | Thrown when a placeholder variable is used in the mainline, i.e. outside of
10 | any explicit block.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | $^x;
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Cannot use placeholder parameter $^x outside of a sub or block
22 | 
23 | Note that this error can also occur when you think something is a block,
24 | but it really is a L«postcircumfix:<{ }>|/routine/{ }», for example
25 | 
26 | =for code :skip-test
27 | my %h;
28 | say %h{ $^x };
29 | #     ^^^^^^^  not a block, so $^x is part of the mainline
30 | 
31 | =end pod
32 | 


--------------------------------------------------------------------------------
/doc/Type/X/Pod.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("role") :category("exception")
 2 | 
 3 | =TITLE role X::Pod
 4 | 
 5 | =SUBTITLE Pod related error
 6 | 
 7 |     role X::Pod { }
 8 | 
 9 | Common role for Pod related errors.
10 | 
11 | =end pod
12 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Async.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("role") :category("exception")
 2 | 
 3 | =TITLE role X::Proc::Async
 4 | 
 5 | =SUBTITLE Exception thrown by Proc::Async
 6 | 
 7 |     role X::Proc::Async is Exception { ... }
 8 | 
 9 | All exceptions thrown by L|/type/Proc::Async> do this common role.
10 | 
11 | =head1 Methods
12 | 
13 | =head2 method proc
14 | 
15 |     method proc(X::Proc::Async:D --> Proc::Async)
16 | 
17 | Returns the object that threw the exception.
18 | 
19 | =end pod
20 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Async/AlreadyStarted.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Proc::Async::AlreadyStarted
 4 | 
 5 | =SUBTITLE Error due to calling start on an already started Proc::Async object
 6 | 
 7 |     class X::Proc::Async::AlreadyStarted is Exception {}
 8 | 
 9 | When you call C twice on the same L|/type/Proc::Async>
10 | object, the second invocation will die with an
11 | C exception.
12 | 
13 |     my $proc = Proc::Async.new("echo");
14 |     $proc.start;
15 |     $proc.start;
16 |     CATCH { default { put .^name, ': ', .Str } };
17 |     # OUTPUT: «X::Proc::Async::AlreadyStarted: Process has already been started␤»
18 | 
19 | =end pod
20 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Async/BindOrUse.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Proc::Async::BindOrUse
 4 | 
 5 | =SUBTITLE Error due to trying to bind a handle that is also used
 6 | 
 7 | =for code :preamble
 8 | class X::Proc::Async::BindOrUse does X::Proc::Async {}
 9 | 
10 | In general, it occurs when there's some mistake in the direction the stream
11 | flows, for instance:
12 | 
13 | =for code
14 | my $p = Proc::Async.new("ls", :w);
15 | my $h = "ls.out".IO.open(:w);
16 | $p.bind-stdin($h);
17 | # Fails with OUTPUT: «Cannot both bind stdin to a handle and also use :w␤»
18 | 
19 | In this case, C is already bound and cannot be used again; one of them
20 | should flow C<:out> and the other one C<:w> to work correctly.
21 | 
22 | =end pod
23 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Async/CharsOrBytes.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Proc::Async::CharsOrBytes
 4 | 
 5 | =SUBTITLE Error due to tapping the same Proc::Async stream for both text and binary reading
 6 | 
 7 |     class X::Proc::Async::CharsOrBytes is Exception {}
 8 | 
 9 | A L|/type/Proc::Async> object allows subscription to the output or error stream
10 | either for bytes (L|/type/Blob>) or for text data (L|/type/Str>), but
11 | not for both. If you do try both, it throws an exception of type
12 | C.
13 | 
14 |     my $proc = Proc::Async.new('echo');
15 |     $proc.stdout.tap(&print);
16 |     $proc.stdout(:bin).tap(&print);
17 |     CATCH { default { put .^name, ': ', .Str } };
18 |     # OUTPUT: «X::Proc::Async::CharsOrBytes: Can only tap one of chars or bytes supply for stdout␤»
19 | 
20 | =head1 Methods
21 | 
22 | =head2 method handle
23 | 
24 |     method handle(X::Proc::Async::CharsOrBytes:D: --> Str:D)
25 | 
26 | Returns the name of the handle that was accessed both for text and for binary
27 | data, C or C.
28 | 
29 | =end pod
30 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Async/MustBeStarted.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Proc::Async::MustBeStarted
 4 | 
 5 | =SUBTITLE Error due to interacting with a Proc::Async stream before spawning its process
 6 | 
 7 |     class X::Proc::Async::MustBeStarted is Exception {}
 8 | 
 9 | Several methods from L|/type/Proc::Async> expect that the external program has been
10 | spawned (by calling C<.start> on it), including C, C, C and
11 | C. If one of those methods is called before C<.start> was called,
12 | they throw an exception of type C.
13 | 
14 |     Proc::Async.new('echo', :w).say(42);
15 |     CATCH { default { put .^name, ': ', .Str } };
16 |     # OUTPUT: «X::Proc::Async::MustBeStarted: Process must be started first before calling 'say'␤»
17 | 
18 | =head1 Methods
19 | 
20 | =head2 method method
21 | 
22 |     method method(X::Proc::Async::MustBeStarted:D --> Str:D)
23 | 
24 | Returns the name of the method that was illegally called before starting the
25 | external program.
26 | 
27 | =end pod
28 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Async/OpenForWriting.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Proc::Async::OpenForWriting
 4 | 
 5 | =SUBTITLE Error due to writing to a read-only Proc::Async object
 6 | 
 7 |     class X::Proc::Async::OpenForWriting is Exception {}
 8 | 
 9 | When a L|/type/Proc::Async> object is opened only for reading from the external
10 | program (no C<:w> passed to open), and a write operation such as C,
11 | C and C is performed, an exception of type
12 | C is thrown:
13 | 
14 |     my $proc = Proc::Async.new("echo");
15 |     $proc.start;
16 |     $proc.say(42);
17 |     CATCH { default { put .^name, ': ', .Str } };
18 |     # OUTPUT: «X::Proc::Async::OpenForWriting: Process must be opened for writing with :w to call 'say'␤»
19 | 
20 | To fix that you can use writable commands with :w flag:
21 | 
22 |     my $prog = Proc::Async.new(:w, 'cat');
23 |     $prog.stdout.tap( -> $str {
24 |         print $str;
25 |     });
26 |     my $promise = $prog.start;
27 |     await $prog.say('foo');
28 |     $prog.close-stdin;
29 |     await $promise;
30 | 
31 | =head1 Methods
32 | 
33 | =head2 method method
34 | 
35 |     method method(X::Proc::Async::OpenForWriting:D:)
36 | 
37 | Returns the method name that was called and which caused the exception.
38 | 
39 | =end pod
40 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Async/TapBeforeSpawn.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Proc::Async::TapBeforeSpawn
 4 | 
 5 | =SUBTITLE Error due to tapping a Proc::Async stream after spawning its process
 6 | 
 7 |     class X::Proc::Async::TapBeforeSpawn is Exception {}
 8 | 
 9 | If the C or C methods of L|/type/Proc::Async> are
10 | called after the program has been Ced, an exception of type
11 | C is thrown.
12 | 
13 |     my $proc = Proc::Async.new("echo", "foo");
14 |     $proc.start;
15 |     $proc.stdout.tap(&print);
16 |     CATCH { default { put .^name, ': ', .Str } };
17 |     # OUTPUT: «X::Proc::Async::TapBeforeSpawn: To avoid data races, you must tap stdout before running the process␤»
18 | 
19 | The right way is the reverse order
20 | 
21 |     my $proc = Proc::Async.new("echo", "foo");
22 |     $proc.stdout.tap(&print);
23 |     await $proc.start;
24 | 
25 | =head1 Methods
26 | 
27 | =head2 method handle
28 | 
29 |     method handle(X::Proc::Async::TapBeforeSpawn:D: --> Str:D)
30 | 
31 | Returns the name of the handle (C or C) that was accessed after the
32 | program started.
33 | 
34 | =end pod
35 | 


--------------------------------------------------------------------------------
/doc/Type/X/Proc/Unsuccessful.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Proc::Unsuccessful
 4 | 
 5 | =SUBTITLE Exception thrown if a Proc object is sunk after the process it ran exited unsuccessfully
 6 | 
 7 |     class X::Proc::Unsuccessful is Exception {}
 8 | 
 9 | =head1 Methods
10 | 
11 | =head2 method proc
12 | 
13 |     method proc(X::Proc::Unsuccessful:D --> Proc)
14 | 
15 | Returns the object that threw the exception.
16 | 
17 | =end pod
18 | 


--------------------------------------------------------------------------------
/doc/Type/X/Promise/CauseOnlyValidOnBroken.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Promise::CauseOnlyValidOnBroken
 4 | 
 5 | =SUBTITLE Error due to asking why an unbroken promise has been broken.
 6 | 
 7 |     class X::Promise::CauseOnlyValidOnBroken is Exception { }
 8 | 
 9 | This exception is thrown when code expects a Promise to be broken,
10 | and asks why it has been broken, but the Promise has in fact,
11 | not yet been broken.
12 | 
13 | =head1 Methods
14 | 
15 | =head2 method promise
16 | 
17 |     method promise()
18 | 
19 | Returns the Promise that was asked about.
20 | 
21 | =head2 method status
22 | 
23 |     method status()
24 | 
25 | Returns the status the Promise had at that time.
26 | 
27 | =end pod
28 | 


--------------------------------------------------------------------------------
/doc/Type/X/Promise/Vowed.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Promise::Vowed
 4 | 
 5 | =SUBTITLE Error due to directly trying to keep/break a vowed promise.
 6 | 
 7 |     class X::Promise::Vowed is Exception { }
 8 | 
 9 | This exception is thrown when code tries to keep/break an already vowed
10 | promise without going through the corresponding C object.
11 | 
12 | =head1 Methods
13 | 
14 | =head2 method promise
15 | 
16 |     method promise()
17 | 
18 | Returns the vowed Promise.
19 | 
20 | =end pod
21 | 


--------------------------------------------------------------------------------
/doc/Type/X/Redeclaration.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Redeclaration
 4 | 
 5 | =SUBTITLE Compilation error due to declaring an already declared symbol
 6 | 
 7 |     class X::Redeclaration does X::Comp { }
 8 | 
 9 | Thrown when a symbol (variable, routine, type, parameter, ...) is redeclared.
10 | Note that redeclarations are generally fine in an inner scope, but if the
11 | redeclaration appears in the same scope as the original declaration,
12 | it usually indicates an error and is treated as one.
13 | 
14 | Examples
15 | 
16 | =for code
17 | my $x; my $x;
18 | 
19 | dies with
20 | 
21 | =for code :lang
22 | ===SORRY!===
23 | Redeclaration of symbol $x
24 | 
25 | It works with routines too:
26 | 
27 | =for code :skip-test
28 | sub f() { }
29 | sub f() { }
30 | 
31 | dies with
32 | 
33 | =for code :lang
34 | ===SORRY!===
35 | Redeclaration of routine f
36 | 
37 | But those are fine
38 | 
39 | =for code
40 | my $x;
41 | sub f() {
42 |     my $x;          # not a redeclaration,
43 |                     # because it's in an inner scope
44 |     sub f() { };    # same
45 | }
46 | 
47 | 
48 | =head1 Methods
49 | 
50 | =head2 method symbol
51 | 
52 | Returns the name of the symbol that was redeclared.
53 | 
54 | =head2 method what
55 | 
56 | Returns the kind of symbol that was redeclared. Usually C, but can
57 | also be C, C etc.
58 | 
59 | =head2 method postfix
60 | 
61 | Returns a string that is attached to the end of the error message. It
62 | usually explains the particular problem in more detail, or suggests
63 | way to fix the problem.
64 | 
65 | =end pod
66 | 


--------------------------------------------------------------------------------
/doc/Type/X/Role/Initialization.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Role::Initialization
 4 | 
 5 | =SUBTITLE Error due to passing an initialization value to an ineligible role
 6 | 
 7 |     class X::Role::Initialization is Exception { }
 8 | 
 9 | Thrown when the C syntax is used, but SomeRole does not have
10 | exactly one public attribute.
11 | 
12 | For example:
13 | 
14 | =begin code :skip-test
15 | role R { }; "D2" but R(2)
16 | CATCH { default { put .^name, ': ', .Str } }
17 | # OUTPUT: «X::Role::Initialization: Can only supply an initialization value for a role if it has a single public attribute, but this is not the case for 'R'␤»
18 | =end code
19 | 
20 | =head1 Methods
21 | 
22 | =head2 method role
23 | 
24 |     method role()
25 | 
26 | Returns the role that caused the error.
27 | 
28 | =end pod
29 | 


--------------------------------------------------------------------------------
/doc/Type/X/Scheduler/CueInNaNSeconds.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Scheduler::CueInNaNSeconds
 4 | 
 5 | =SUBTITLE Error caused by passing NaN to Scheduler.cue as :at, :in, or :every
 6 | 
 7 |     class X::Scheduler::CueInNaNSeconds is Exception { }
 8 | 
 9 | When calling C or C with
10 | C<:at>, C<:in>, or C<:every> as C, this exception gets thrown. For
11 | example, the following code:
12 | 
13 | =for code
14 | my Cancellation $c = $*SCHEDULER.cue({
15 |     say 'This will never output :(';
16 | }, at => NaN);
17 | 
18 | Throws with:
19 | 
20 | =for code :lang
21 | Cannot pass NaN as a number of seconds to Scheduler.cue
22 | 
23 | This class only exists in releases 2019.05 and later.
24 | 
25 | =end pod
26 | 


--------------------------------------------------------------------------------
/doc/Type/X/Seq/Consumed.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Seq::Consumed
 4 | 
 5 | =SUBTITLE Error due to trying to reuse a consumed sequence
 6 | 
 7 |     class X::Seq::Consumed is Exception { }
 8 | 
 9 | This exception is thrown when a piece of code tries to reuse
10 | a L|/type/Seq> which has already been iterated.
11 | 
12 | =end pod
13 | 


--------------------------------------------------------------------------------
/doc/Type/X/Sequence/Deduction.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Sequence::Deduction
 4 | 
 5 | =SUBTITLE Error due to constructing a sequence from ineligible input
 6 | 
 7 |     class X::Sequence::Deduction is Exception { }
 8 | 
 9 | Exception type thrown when the C<...> sequence operator is being called
10 | without an explicit closure, and the sequence cannot be deduced.
11 | 
12 | =end pod
13 | 


--------------------------------------------------------------------------------
/doc/Type/X/Signature/NameClash.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Signature::NameClash
 4 | 
 5 | =SUBTITLE Compilation error due to two named parameters with the same name
 6 | 
 7 |     my class X::Signature::NameClash does X::Comp { }
 8 | 
 9 | Compile time error thrown when two named parameters have the same name,
10 | potentially through aliases.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | sub f(:$a, :a(:@b)) { }
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Name a used for more than one named parameter
22 | 
23 | =head1 Methods
24 | 
25 | =head2 method name
26 | 
27 |     method name(--> Str:D)
28 | 
29 | Returns the name that was used for more than one parameter.
30 | 
31 | =end pod
32 | 


--------------------------------------------------------------------------------
/doc/Type/X/Signature/Placeholder.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Signature::Placeholder
 4 | 
 5 | =SUBTITLE Compilation error due to placeholders in a block with a signature
 6 | 
 7 | =for code
 8 | class X::Signature::Placeholder does X::Comp { }
 9 | 
10 | Compile time error thrown when a block has both an explicit signature
11 | and placeholder parameters.
12 | 
13 | For example
14 | 
15 | =for code :skip-test
16 | sub f() { $^x }
17 | 
18 | dies with
19 | 
20 | =for code :lang
21 | ===SORRY!===
22 | Placeholder variable '$^x' cannot override existing signature
23 | 
24 | =head1 Methods
25 | 
26 | =head2 method placeholder
27 | 
28 |     method placeholder(--> Str:D)
29 | 
30 | Returns the name of a placeholder that was used in a block that already
31 | had a signature.
32 | 
33 | =end pod
34 | 


--------------------------------------------------------------------------------
/doc/Type/X/Str/Match/x.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Str::Match::x
 4 | 
 5 | =SUBTITLE Invalid argument type for :x argument to Str matching methods
 6 | 
 7 |     class X::Str::Match::x is Exception { }
 8 | 
 9 | Error thrown (or wrapped in a L|/type/Failure>) if an invalid type is passed to the
10 | C<:x> argument of C or C. Only L|/type/Numeric> and
11 | L|/type/Range> types are allowed.
12 | 
13 | For example
14 | 
15 |     say "foobar".match("o",:x);
16 |     CATCH { default { put .^name, ': ', .Str } };
17 |     # OUTPUT: «X::Str::Match::x: in Str.match, got invalid value of type Str for :x, must be Int or Range␤»
18 | 
19 | =head1 Methods
20 | 
21 | =head2 method source
22 | 
23 |     method got(--> Str:D)
24 | 
25 | Returns the type of the invalid argument.
26 | 
27 | =end pod
28 | 


--------------------------------------------------------------------------------
/doc/Type/X/Str/Numeric.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Str::Numeric
 4 | 
 5 | =SUBTITLE Error while trying to coerce a string to a number
 6 | 
 7 |     class X::Str::Numeric is Exception { }
 8 | 
 9 | Error thrown (or wrapped in a L|/type/Failure>) when a conversion from string to
10 | a number fails.
11 | 
12 | For example
13 | 
14 |     say +"42 answers";
15 |     CATCH { default { put .^name, ': ', .Str } };
16 |     # OUTPUT: «X::Str::Numeric: Cannot convert string to number: trailing characters after number in '42⏏ answers' (indicated by ⏏)␤»
17 | 
18 | =head1 Methods
19 | 
20 | =head2 method source
21 | 
22 |     method source(--> Str:D)
23 | 
24 | Returns the string that was attempted to convert to a number
25 | 
26 | =head2 method pos
27 | 
28 |     method pos(--> Int:D)
29 | 
30 | Gives the position into the string where the parsing failed.
31 | 
32 | =head2 method reason
33 | 
34 |     method reason(--> Int:D)
35 | 
36 | Verbal description of the reason why the conversion failed.
37 | 
38 | =end pod
39 | 


--------------------------------------------------------------------------------
/doc/Type/X/StubCode.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::StubCode
 4 | 
 5 | =SUBTITLE Runtime error due to execution of stub code
 6 | 
 7 |     class X::StubCode is Exception { }
 8 | 
 9 | Thrown when a piece of stub code (created via C or C<...>) is executed.
10 | 
11 | =head1 Methods
12 | 
13 | =head2 method message
14 | 
15 | Returns the custom message provided to C, or a reasonable default if none
16 | was provided.
17 | 
18 | =end pod
19 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("role") :category("exception")
 2 | 
 3 | =TITLE role X::Syntax
 4 | 
 5 | =SUBTITLE Syntax error thrown by the compiler
 6 | 
 7 |     role X::Syntax does X::Comp { }
 8 | 
 9 | Common role for syntax errors thrown by the compiler.
10 | 
11 | =end pod
12 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Augment/WithoutMonkeyTyping.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Augment::WithoutMonkeyTyping
 4 | 
 5 | =SUBTITLE Compilation error due to augmenting a type without the C pragma
 6 | 
 7 |     class X::Syntax::Augment::WithoutMonkeyTyping does X::Syntax { }
 8 | 
 9 | Compile time error thrown when C is used without C.
10 | 
11 | Since C is considered a rather unsafe and impolite action, you have
12 | to pre-declare your intent with the C pragma.
13 | 
14 | If you don't do that, like here
15 | 
16 | =for code :skip-test
17 | augment class Int { };
18 | 
19 | you get the error
20 | 
21 | =for code :lang
22 | ===SORRY!===
23 | augment not allowed without 'use MONKEY-TYPING'
24 | 
25 | =end pod
26 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Comment/Embedded.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Comment::Embedded
 4 | 
 5 | =SUBTITLE Compilation error due to a malformed inline comment
 6 | 
 7 |     class X::Syntax::Comment::Embedded does X::Syntax { }
 8 | 
 9 | Syntax error thrown when C<#`> is encountered and it is not followed by
10 | an opening curly brace.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | #`
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Opening bracket is required for #` comment
22 | 
23 | =end pod
24 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Confused.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Confused
 4 | 
 5 | =SUBTITLE Compilation error due to unrecognized syntax
 6 | 
 7 | =for code
 8 | class X::Syntax::Confused does X::Syntax { }
 9 | 
10 | The most general syntax error, if no more specific error message can be given.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | 1∞
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Confused
22 | 
23 | =end pod
24 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/InfixInTermPosition.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::InfixInTermPosition
 4 | 
 5 | =SUBTITLE Compilation error due to an infix in term position
 6 | 
 7 |     class X::Syntax::InfixInTermPosition does X::Syntax { }
 8 | 
 9 | Syntax error thrown when the parser expects a term, but finds an infix
10 | operator instead.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | 1, => 2;
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Preceding context expects a term, but found infix => instead
22 | 
23 | =head1 Methods
24 | 
25 | =head2 method infix
26 | 
27 |     method infix(--> Str:D)
28 | 
29 | Returns the symbol of the infix that was found in term position.
30 | 
31 | =end pod
32 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Malformed.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Malformed
 4 | 
 5 | =SUBTITLE Compilation error due to a malformed construct (usually a declarator)
 6 | 
 7 |     class X::Syntax::Malformed does X::Syntax {}
 8 | 
 9 | The Raku compiler throws errors of type C when it
10 | knows what kind of declaration it is parsing, and encounters a syntax error,
11 | but can't give a more specific error message.
12 | 
13 | =for code :skip-test
14 | my Int a;   # throws an X::Syntax::Malformed
15 | 
16 | produces
17 | 
18 | =for code :lang
19 | ===SORRY!===
20 | Malformed my
21 | at -e:1
22 | ------> my Int ⏏a
23 | 
24 | 
25 | =head1 Methods
26 | 
27 | =head2 method what
28 | 
29 |     method what(X::Syntax::Malformed:D: --> Str)
30 | 
31 | Returns a description of the thing that was being parsed.
32 | 
33 | =end pod
34 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Missing.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Missing
 4 | 
 5 | =SUBTITLE Compilation error due to a missing piece of syntax
 6 | 
 7 |     class X::Syntax::Missing does X::Syntax { }
 8 | 
 9 | Syntax error thrown when the previous piece of syntax requires the
10 | existence of another piece of syntax, and that second piece is missing.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | for 1, 2, 3;
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Missing block
22 | 
23 | because a C that is not a statement modifier must be followed by a block.
24 | 
25 | =head1 Methods
26 | 
27 | =head2 method what
28 | 
29 |     method what(--> Str:D)
30 | 
31 | Returns a string description of the missing syntax element.
32 | 
33 | =end pod
34 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/NegatedPair.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::NegatedPair
 4 | 
 5 | =SUBTITLE Compilation error due to passing an argument to a negated colonpair
 6 | 
 7 |     class X::Syntax::NegatedPair does X::Syntax { }
 8 | 
 9 | Thrown if a colonpair illegally has a value, for example C<:!a(1)>.
10 | This is an error because the C negation implies that the value is C.
11 | 
12 | A typical error message from this class is I.
14 | 
15 | =head1 Methods
16 | 
17 | =head2 method key
18 | 
19 | Returns the key of the pair that caused the error.
20 | 
21 | =end pod
22 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/NoSelf.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::NoSelf
 4 | 
 5 | =SUBTITLE Compilation error due to implicitly using a C that is not there
 6 | 
 7 |     class X::Syntax::NoSelf does X::Syntax { }
 8 | 
 9 | Compile time error thrown when C<$.foo> style calls are used where no invocant
10 | is available.
11 | 
12 | For example the code
13 | 
14 | =for code :skip-test
15 | $.meth;
16 | 
17 | in the program body throws the error
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Variable $.meth used where no 'self' is available
22 | 
23 | because C<$.meth> is short for C<$(self.meth)>, and there is no C
24 | available in mainline.
25 | 
26 | =head1 Methods
27 | 
28 | =head2 method variable
29 | 
30 | Returns the variable/method call that caused the error.
31 | 
32 | =end pod
33 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Number/RadixOutOfRange.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Number::RadixOutOfRange
 4 | 
 5 | =SUBTITLE Compilation error due to an unallowed radix in a number literal
 6 | 
 7 |     class X::Syntax::Number::RadixOutOfRange does X::Syntax { }
 8 | 
 9 | Syntax error that is thrown when the radix of a radix number is
10 | not allowed, like C«:1<1>» or C«:42».
11 | 
12 | =head1 Methods
13 | 
14 | =head2 method radix
15 | 
16 |     method radix(--> Int:D)
17 | 
18 | The offensive radix.
19 | 
20 | =end pod
21 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/P5.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::P5
 4 | 
 5 | =SUBTITLE Compilation error due to use of Perl-only syntax
 6 | 
 7 |     class X::Syntax::P5 does X::Syntax { }
 8 | 
 9 | Syntax error thrown when some piece of code is clearly Perl, not Raku.
10 | 
11 | For example
12 | 
13 | =for code :skip-test
14 | for my $a (1, 2) { };
15 | 
16 | dies with
17 | 
18 | =for code :lang
19 | ===SORRY!===
20 | This appears to be Perl code
21 | 
22 | 
23 | =end pod
24 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Perl5Var.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Perl5Var
 4 | 
 5 | =SUBTITLE Compilation error due to use of Perl-only default variables
 6 | 
 7 |     class X::Syntax::Perl5Var does X::Syntax { }
 8 | 
 9 | Syntax error thrown when some piece of code tries to use one of the old Perl
10 | variables (and it does not error for some other reason).
11 | 
12 | =for code :skip-test
13 | say $];
14 | 
15 | dies with
16 | 
17 | =for code :lang
18 | Unsupported use of $] variable; in Raku please use $*RAKU.version or $*RAKU.compiler.version
19 | 
20 | For every unsupported variable (which include most C<$^'letter'> constructs,
21 | as well as others like C<$">, the error message will mention that the
22 | variable is unsupported and the equivalent commands you could use.
23 | 
24 | 
25 | =end pod
26 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Regex/Adverb.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Regex::Adverb
 4 | 
 5 | =SUBTITLE Compilation error due to an unrecognized regex adverb
 6 | 
 7 |     class X::Syntax::Regex::Adverb does X::Syntax { }
 8 | 
 9 | Syntax error thrown when an unrecognized or illegal regex adverb is
10 | encountered.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | rx:g/a/
16 | 
17 | dies with
18 | 
19 | =begin code :lang
20 | ===SORRY!===
21 | Adverb g not allowed on rx
22 | =end code
23 | 
24 | because C<:g> belongs to a match operation, not a regex itself.
25 | 
26 | =head1 Methods
27 | 
28 | =head2 method adverb
29 | 
30 |     method adverb(--> Str:D)
31 | 
32 | Returns the illegally used adverb
33 | 
34 | =head2 method construct
35 | 
36 |     method construct(--> Str:D)
37 | 
38 | Returns the name of the construct that adverb was used on (C, C,
39 | C, C, C).
40 | 
41 | =end pod
42 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Regex/SolitaryQuantifier.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Regex::SolitaryQuantifier
 4 | 
 5 | =SUBTITLE Compilation error due to a regex quantifier without preceding atom
 6 | 
 7 |     class X::Syntax::Regex::SolitaryQuantifier does X::Syntax { }
 8 | 
 9 | Syntax error when a stand alone quantifier (without a preceding atom
10 | to quantify) is encountered in a regular expression.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | / * /;
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Quantifier quantifies nothing
22 | 
23 | =end pod
24 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Reserved.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Reserved
 4 | 
 5 | =SUBTITLE Compilation error due to use of syntax reserved for future use
 6 | 
 7 |     class X::Syntax::Reserved does X::Syntax { }
 8 | 
 9 | Syntax error thrown when a syntax is used which is reserved for future
10 | expansion.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | my @a();
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | The () shape syntax in array declarations is reserved
22 | 
23 | =head1 Methods
24 | 
25 | =head2 method reserved
26 | 
27 |     method reserved(--> Str:D)
28 | 
29 | Returns a text description of the reserved syntax.
30 | 
31 | =head2 method instead
32 | 
33 |     method instead(--> Str)
34 | 
35 | Describes what to use instead of the reserved syntax (if anything).
36 | 
37 | =end pod
38 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Self/WithoutObject.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Self::WithoutObject
 4 | 
 5 | =SUBTITLE Compilation error due to invoking C in an ineligible scope
 6 | 
 7 |     class X::Syntax::Self::WithoutObject does X::Syntax { }
 8 | 
 9 | Syntax error thrown when C is referenced in a place where no
10 | invocant is available.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | self;
16 | 
17 | outside a class or role declaration dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | 'self' used where no object is available
22 | 
23 | =end pod
24 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Signature/InvocantMarker.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Signature::InvocantMarker
 4 | 
 5 | =SUBTITLE Compilation error due to a misplaced invocant marker in a signature
 6 | 
 7 |     class X::Syntax::Signature::InvocantMarker does X::Syntax { }
 8 | 
 9 | Syntax error when the invocant in a signature is anywhere else than after the
10 | first parameter.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | :($a, $b: $c);
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Can only use : as invocant marker in a signature after the first parameter
22 | 
23 | See also: L|/type/Signature>.
24 | 
25 | =end pod
26 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Term/MissingInitializer.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Term::MissingInitializer
 4 | 
 5 | =SUBTITLE Compilation error due to declaring a term without initialization
 6 | 
 7 |     class X::Syntax::Term::MissingInitializer does X::Syntax { }
 8 | 
 9 | Syntax error when a term (a backslash variable) is declared without
10 | initialization assignment.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | my \foo;
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Term definition requires an initializer
22 | 
23 | Valid code would be
24 | 
25 | =for code
26 | my \foo = 42;
27 | 
28 | =end pod
29 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/UnlessElse.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::UnlessElse
 4 | 
 5 | =SUBTITLE Compilation error due to an C clause followed by C
 6 | 
 7 |     class X::Syntax::UnlessElse does X::Syntax { }
 8 | 
 9 | Syntax error thrown when an C clause is followed by an C clause.
10 | 
11 | For example
12 | 
13 | =for code :skip-test
14 | unless 1 { } else { };
15 | 
16 | dies with
17 | 
18 | =for code :lang
19 | ===SORRY!===
20 | "unless" does not take "else", please rewrite using "if"
21 | 
22 | =end pod
23 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Variable/Match.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Variable::Match
 4 | 
 5 | =SUBTITLE Compilation error due to declaring a match variable
 6 | 
 7 |     class X::Syntax::Variable::Match does X::Syntax { }
 8 | 
 9 | Syntax error thrown when a match variable like C«$» was declared.
10 | 
11 | For example
12 | 
13 | =for code :skip-test
14 | my $;
15 | 
16 | dies with
17 | 
18 | =for code :lang
19 | ===SORRY!===
20 | Cannot declare a match variable
21 | 
22 | =end pod
23 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Variable/Numeric.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Variable::Numeric
 4 | 
 5 | =SUBTITLE Compilation error due to declaring a numeric symbol
 6 | 
 7 |     class X::Syntax::Variable::Numeric does X::Syntax { }
 8 | 
 9 | Syntax error thrown when trying to declare numeric symbols.
10 | 
11 | For example
12 | 
13 | =for code :skip-test
14 | my @101;
15 | 
16 | dies with
17 | 
18 | =for code :lang
19 | ===SORRY!===
20 | Cannot declare a numeric variable
21 | 
22 | =head1 Methods
23 | 
24 | =head2 method what
25 | 
26 |     method what returns Str:D
27 | 
28 | Returns a verbal description of the kind of symbol that was declared (variable,
29 | parameter, attribute).
30 | 
31 | =end pod
32 | 


--------------------------------------------------------------------------------
/doc/Type/X/Syntax/Variable/Twigil.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Syntax::Variable::Twigil
 4 | 
 5 | =SUBTITLE Compilation error due to an unallowed twigil in a declaration
 6 | 
 7 |     class X::Syntax::Variable::Twigil does X::Syntax { }
 8 | 
 9 | Syntax error thrown when a variable with a twigil is used in an incompatible
10 | declaration.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | my $!foo;
16 | 
17 | dies with
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Cannot use ! twigil on my variable
22 | 
23 | =head1 Methods
24 | 
25 | =head2 method twigil
26 | 
27 |     method twigil(--> Str:D)
28 | 
29 | Returns the twigil that was illegally used
30 | 
31 | =head2 method scope
32 | 
33 |     method scope(--> Str:D)
34 | 
35 | Returns the scope that did not harmonize with the twigil.
36 | 
37 | =end pod
38 | 


--------------------------------------------------------------------------------
/doc/Type/X/Temporal.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("role") :category("exception")
 2 | 
 3 | =TITLE role X::Temporal
 4 | 
 5 | =SUBTITLE Error related to DateTime or Date
 6 | 
 7 |     role X::Temporal is Exception { }
 8 | 
 9 | A common exception type for all errors related to L|/type/DateTime> or L|/type/Date>.
10 | 
11 | =end pod
12 | 


--------------------------------------------------------------------------------
/doc/Type/X/Temporal/InvalidFormat.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Temporal::InvalidFormat
 4 | 
 5 | =SUBTITLE Error due to using an invalid format when creating a DateTime or Date
 6 | 
 7 | =for code :skip-test
 8 | class X::Temporal::InvalidFormat does X::Temporal is Exception { }
 9 | 
10 | This exception is thrown when code tries to create a L|/type/DateTime> or L|/type/Date> object
11 | using an invalid format.
12 | 
13 | =begin code :ok-test

14 | my $dt = Date.new("12/25/2015");
15 | CATCH { default { put .^name, ': ', .Str } };
16 | # OUTPUT: «X::Temporal::InvalidFormat: Invalid Date string '12/25/2015'; use yyyy-mm-dd instead␤»
17 | =end code
18 | 
19 | =head1 Methods
20 | 
21 | =head2 method invalid-str
22 | 
23 | Returns the invalid format string (C<12/25/2015> in the example above)
24 | 
25 | =head2 method target
26 | 
27 | Returns the target type (L|/type/Date> in the example above)
28 | 
29 | =head2 method format
30 | 
31 | Returns valid format strings for the target type in question, (C in the example above)
32 | 
33 | =end pod
34 | 


--------------------------------------------------------------------------------
/doc/Type/X/TypeCheck.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::TypeCheck
 4 | 
 5 | =SUBTITLE Error due to a failed type check
 6 | 
 7 |     class X::TypeCheck is Exception { }
 8 | 
 9 | Error class thrown when a type check fails.
10 | 
11 | =head1 Methods
12 | 
13 | =head2 method operation
14 | 
15 |     method operation(--> Str:D)
16 | 
17 | Returns a string description of the operation that failed, for example
18 | C<"assignment">, C<"binding">, C<"return">.
19 | 
20 | =head2 method got
21 | 
22 |     method got()
23 | 
24 | Returns the object that failed to type check
25 | 
26 | =head2 method expected
27 | 
28 |     method expected()
29 | 
30 | Returns the type object against which the check failed.
31 | 
32 | =end pod
33 | 


--------------------------------------------------------------------------------
/doc/Type/X/TypeCheck/Assignment.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::TypeCheck::Assignment
 4 | 
 5 | =SUBTITLE Error due to a failed type check during assignment
 6 | 
 7 |     class X::TypeCheck::Assignment is X::TypeCheck { }
 8 | 
 9 | Error class thrown when the type check of an assignment fails.
10 | 
11 | For example, this will die
12 | 
13 |     my Int $x = "foo";
14 |     CATCH { default { put .^name, ': ', .Str } };
15 |     # OUTPUT: «X::TypeCheck::Assignment: Type check failed in assignment to $x; expected Int but got Str ("foo")␤»
16 | 
17 | though compilers are allowed to detect obvious cases like this example
18 | and complain at compile time with a different error.
19 | 
20 | =end pod
21 | 


--------------------------------------------------------------------------------
/doc/Type/X/TypeCheck/Binding.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::TypeCheck::Binding
 4 | 
 5 | =SUBTITLE Error due to a failed type check during binding
 6 | 
 7 |     class X::TypeCheck::Binding is X::TypeCheck { }
 8 | 
 9 | Thrown when the type check of a binding operation fails.
10 | 
11 | For example:
12 | 
13 |     my Int $x := "foo";
14 |     CATCH { default { put .^name, ': ', .Str } };
15 |     # OUTPUT: «X::TypeCheck::Binding: Type check failed in binding; expected Int but got Str ("foo")␤»
16 | 
17 | Note that the compiler is free to detect obvious errors at compile time,
18 | and complain with a different error at compile time.
19 | 
20 | =end pod
21 | 


--------------------------------------------------------------------------------
/doc/Type/X/TypeCheck/Return.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::TypeCheck::Return
 4 | 
 5 | =SUBTITLE Error due to a failed typecheck during C
 6 | 
 7 |     class X::TypeCheck::Return is X::TypeCheck { }
 8 | 
 9 | Thrown when a return type check fails.
10 | 
11 | For example
12 | 
13 |     sub f(--> Int) { "foo" }
14 |     f();
15 |     CATCH { default { put .^name, ': ', .Str } };
16 |     # OUTPUT: «X::TypeCheck::Return: Type check failed for return value; expected Int but got Str ("foo")␤»
17 | 
18 | =end pod
19 | 


--------------------------------------------------------------------------------
/doc/Type/X/TypeCheck/Splice.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::TypeCheck::Splice
 4 | 
 5 | =SUBTITLE Compilation error due to a macro trying to splice a non-AST value
 6 | 
 7 |     class X::TypeCheck::Splice is X::TypeCheck does X::Comp { }
 8 | 
 9 | Compile time error thrown when a L|/type/Macro> or an unquote/hole in a C
10 | quote does not return an L|/type/AST>.
11 | 
12 | For example
13 | 
14 | =for code :skip-test
15 | use experimental :macros;
16 | macro quasi-ast { quasi { {{{'not AST'}}} };};
17 | say quasi-ast;
18 | 
19 | dies with
20 | 
21 | =for code :lang
22 | ===SORRY!===
23 | Type check failed in macro application; expected AST but got Str("not AST")
24 | 
25 | This is because you are purposefully creating something that does not evaluate to an abstract syntax tree. To fix, instead write
26 | 
27 | =for code
28 | use experimental :macros;
29 | macro an-ast {
30 |     quasi { 'yes AST' }
31 | }
32 | say an-ast;              # OUTPUT: «yes AST␤»
33 | 
34 | =head1 Methods
35 | 
36 | =head2 method action
37 | 
38 |     method action(--> Str:D)
39 | 
40 | Returns a verbal description of the action that triggered the error,
41 | C<"macro application"> or C<"unquote evaluation">.
42 | 
43 | =end pod
44 | 


--------------------------------------------------------------------------------
/doc/Type/X/Undeclared.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("exception")
 2 | 
 3 | =TITLE class X::Undeclared
 4 | 
 5 | =SUBTITLE Compilation error due to an undeclared symbol
 6 | 
 7 |     class X::Undeclared does X::Comp {}
 8 | 
 9 | Thrown when the compiler encounters a symbol that has not been declared,
10 | but needs to be.
11 | 
12 | Example
13 | 
14 | =for code :skip-test
15 | $x;
16 | 
17 | results in
18 | 
19 | =for code :lang
20 | ===SORRY!===
21 | Variable $x is not declared
22 | 
23 | =head1 Methods
24 | 
25 | =head2 method symbol
26 | 
27 | Returns the name of the undeclared symbol
28 | 
29 | =head2 method what
30 | 
31 | Returns the kind of symbol that was not declared (for example variable,
32 | type, routine).
33 | 
34 | Since The symbol wasn't declared, the compiler sometimes has to guess
35 | (or rather disambiguate) what kind of symbol it encounter that wasn't
36 | declared. For example if you write
37 | 
38 | =for code :skip-test
39 | say a;
40 | 
41 | Then the disambiguation defaults to reporting a missing subroutine, even
42 | though declaring a C would also make the error go away.
43 | 
44 | =end pod
45 | 


--------------------------------------------------------------------------------
/doc/Type/utf8.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin pod :kind("Type") :subkind("class") :category("composite")
 2 | 
 3 | =TITLE class utf8
 4 | 
 5 | =SUBTITLE Mutable uint8 buffer for utf8 binary data
 6 | 
 7 |     class utf8 does Blob[uint8] is repr('VMArray') {}
 8 | 
 9 | A C is a subtype of Blob which is specifically uint8 data for holding UTF-8
10 | encoded text.
11 | 
12 |     my utf8 $b = "hello".encode;
13 |     say $b[1].fmt("0x%X"); # OUTPUT: «0x65␤»
14 | 
15 | =end pod
16 | 


--------------------------------------------------------------------------------
/doc/announcements.rakudoc:
--------------------------------------------------------------------------------
 1 | =begin rakudoc :kind :subkind :category
 2 | =TITLE Announcements page
 3 | =SUBTITLE A date-stamped list of notes relevant to the Raku documentation site.
 4 | 
 5 | =begin Note :date<2024-05-12> :caption
 6 | An announcements page is now available. The most recent announcement will pop up when
 7 | the website is loaded, but it will not appear again.
 8 | 
 9 | Announcements can contain all the RakuDoc elements, including:
10 | =item lists as here
11 | =item format / markup codes such C, B, I, B>.
12 | 
13 | The only constraint is how much space is used in the popup.
14 | =end Note
15 | 
16 | 
17 | =end rakudoc
18 | 


--------------------------------------------------------------------------------
/lib/Pod/Cache.rakumod:
--------------------------------------------------------------------------------
 1 | unit class Pod::Cache;
 2 | 
 3 | =begin overview
 4 | 
 5 | Given a filename, generate a cached, rendered text version of the POD
 6 | in that file. Return the C of the cached file.
 7 | 
 8 | Use the new RakuAST generation as it's speedier (and more likely to be correct).
 9 | 
10 | =end overview
11 | 
12 | 
13 | method cache-file(Str $file --> Str) {
14 | 
15 |     # We only cache rakudoc files.
16 |     return $file if ! $file.ends-with('.rakudoc');
17 | 
18 |     my $outfile = '.pod-cache/' ~ $file;
19 |     my $output-io = $outfile.IO;
20 | 
21 |     my $in-time = $file.IO.modified;
22 |     my $out-time = $output-io.e ?? $output-io.modified !! 0;
23 | 
24 |     # If the input file is newer or the target file is empty, cache.
25 |     # The empty check helps in cases where the cache creation died for some reason
26 | 
27 |     if $in-time > $out-time || $output-io.s == 0 {
28 |        mkdir $output-io.dirname;
29 |        my $outfile = $output-io.open(:w);
30 |        LEAVE $outfile.close;
31 |        $outfile.lock;
32 | 
33 |        %*ENV="1"; # Activate AST mode
34 |        my $job = Proc::Async.new($*EXECUTABLE-NAME, '--doc', $file);
35 |        $job.stdout.tap(-> $buf {$outfile.print: $buf});
36 | 
37 |        my $has-error = ! await $job.start;
38 |        if $has-error {
39 |            note "Error occurred caching $file";
40 |        }
41 |     }
42 |     $outfile
43 | }
44 | 


--------------------------------------------------------------------------------
/lib/Pod/Convenience.rakumod:
--------------------------------------------------------------------------------
 1 | unit module Pod::Convenience;
 2 | 
 3 | =begin overview
 4 | 
 5 | Provide C<&extract-pod> which returns an object containing all the pod
 6 | elements from a given file.
 7 | 
 8 | =end overview
 9 | 
10 | # "File" class was deprecated; use the FileSystem if it's available, fall back to deprecated if not.
11 | # (should now work on both new and old rakudos, avoiding deprecation notice where possible
12 | my $class = ::("CompUnit::PrecompilationStore::FileSystem");
13 | if $class ~~ Failure {
14 |     $class = ::("CompUnit::PrecompilationStore::File");
15 | }
16 | 
17 | my $precomp-store = $class.new(:prefix($?FILE.IO.parent(3).child(".pod-precomp")));
18 | my $precomp = CompUnit::PrecompilationRepository::Default.new(store => $precomp-store);
19 | 
20 | sub extract-pod(IO() $file) is export {
21 |     use nqp;
22 |     # The file name is enough for the id because POD files don't have depends
23 |     my $id = nqp::sha1(~$file);
24 |     my $handle = $precomp.load($id,:since($file.modified))[0];
25 | 
26 |     if not $handle {
27 |         # precompile it
28 |         $precomp.precompile($file, $id, :force);
29 |         $handle = $precomp.load($id)[0];
30 |     }
31 | 
32 |     return nqp::atkey($handle.unit,'$=pod')[0];
33 | }
34 | 


--------------------------------------------------------------------------------
/lib/Test-Files.rakumod:
--------------------------------------------------------------------------------
 1 | unit class Test-Files;
 2 | 
 3 | =begin overview
 4 | 
 5 | Utility methods for generating lists of files for testing.
 6 | 
 7 | =end overview
 8 | 
 9 | #|(
10 |     Are we working with all the files in the repository?
11 | )
12 | method all-files() {
13 |     not (@*ARGS or %*ENV);
14 | }
15 | 
16 | #|(
17 |     Return list of files to test.
18 | 
19 |     If files were passed on the command line, use those.
20 | 
21 |     Otherwise, if the C environmental variable is set to
22 |     a space-separated list of files, use that. Any files specified
23 |     this way that don't exist are silently removed.
24 | )
25 | method files() {
26 |     my @files;
27 | 
28 |     if @*ARGS {
29 |         @files = @*ARGS;
30 |     } else {
31 |         if %*ENV {
32 |             @files = %*ENV.trim.split(/ \s /).grep(*.IO.e);
33 |         } else {
34 |             @files = qx.lines;
35 |         }
36 |     }
37 |     return @files.sort;
38 | }
39 | 
40 | #|(
41 |     Filtered list of C to return only Pod files.
42 | )
43 | method pods() {
44 |     return $.files.grep({$_.ends-with: '.rakudoc'})
45 | }
46 | 
47 | #|(
48 |     Filtered list of C to return only Pod files and markdown.
49 | )
50 | method documents() {
51 |     return $.files.grep({$_.ends-with: '.rakudoc' or $_.ends-with: '.md'})
52 | }
53 | 
54 | #|(
55 |     Filtered list of C to return only test files.
56 | )
57 | method tests() {
58 |     return $.files.grep({$_.ends-with: '.rakutest'})
59 | }
60 | 


--------------------------------------------------------------------------------
/t/00-meta.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | BEGIN plan :skip-all unless '.git'.IO.e;
 5 | 
 6 | use Test::META;
 7 | meta-ok;
 8 | 
 9 | done-testing;
10 | 


--------------------------------------------------------------------------------
/t/02-pod-valid.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | BEGIN plan :skip-all unless '.git'.IO.e;
 5 | 
 6 | use Test-Files;
 7 | 
 8 | =begin overview
 9 | 
10 | Ensure any text that isn't a code example is valid C.
11 | 
12 | =end overview
13 | 
14 | my @files = Test-Files.pods;
15 | 
16 | if @files {
17 |     plan +@files;
18 | } else {
19 |     plan :skip-all
20 | }
21 | 
22 | my %data;
23 | my $lock = Lock::Async.new;
24 | 
25 | my $verbose = %*ENV;
26 | 
27 | @files.race.map: -> $file {
28 |     react {
29 |         my $proc = Proc::Async.new([$*EXECUTABLE-NAME, '-c', '--doc', $file]);
30 | 
31 |         whenever $proc.stdout.lines {
32 |             ; #discard
33 |         }
34 | 
35 |         whenever $proc.stderr.lines {
36 |             # An error occurred
37 |             $verbose and diag("$file error: $_");
38 |             $lock.protect: {
39 |                 %data{$file} = False;
40 |             };
41 |         }
42 | 
43 |         whenever $proc.start {
44 |             $verbose and diag("processing $file");
45 |             $lock.protect: {
46 |                 if %data{$file}:!exists {
47 |                     %data{$file} = !.exitcode;  # 0 = True, anything else False
48 |                 }
49 |             };
50 |             done;
51 |         }
52 |     }
53 | }
54 | 
55 | for %data.keys.sort -> $file {
56 |     ok %data{$file}, "$file has clean Pod6";
57 | }
58 | 


--------------------------------------------------------------------------------
/t/03-tests-valid.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | BEGIN plan :skip-all unless '.git'.IO.e;
 5 | 
 6 | use Test-Files;
 7 | 
 8 | =begin overview
 9 | 
10 | Ensure any test file, including author tests, have clean syntax and POD
11 | 
12 | =end overview
13 | 
14 | my @files = Test-Files.tests;
15 | 
16 | if @files {
17 |     plan +@files;
18 | } else {
19 |     plan :skip-all
20 | }
21 | 
22 | my %data;
23 | my $lock = Lock::Async.new;
24 | 
25 | my $verbose = %*ENV // False;
26 | 
27 | @files.race.map: -> $file {
28 |     react {
29 |         my $proc = Proc::Async.new([$*EXECUTABLE-NAME, '-c', $file]);
30 | 
31 |         whenever $proc.stdout.lines {
32 |             ; #discard
33 |         }
34 | 
35 |         whenever $proc.stderr.lines {
36 |             # An error occurred
37 |             $verbose and diag("$file error: $_");
38 |             $lock.protect: {
39 |                 %data{$file} = False;
40 |             };
41 |         }
42 | 
43 |         whenever $proc.start {
44 |             $lock.protect: {
45 |                 if %data{$file}:!exists {
46 |                     %data{$file} = !.exitcode;  # 0 = True, anything else False
47 |                 }
48 |             };
49 |             done;
50 |         }
51 |     }
52 | }
53 | 
54 | for %data.keys.sort -> $file {
55 |     ok %data{$file}, "$file Pod6 and syntax check out";
56 | }
57 | 


--------------------------------------------------------------------------------
/t/05-tabs.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | BEGIN plan :skip-all unless '.git'.IO.e;
 5 | use Test-Files;
 6 | 
 7 | my @files = Test-Files.files\
 8 |     .grep({$_ ne 'LICENSE'|'Makefile'})\
 9 |     .grep({! $_.contains('custom-theme')});
10 | 
11 | plan +@files;
12 | 
13 | for @files -> $file {
14 |     my @lines;
15 |     my $line-no = 1;
16 |     for $file.IO.lines -> $line {
17 |         @lines.push($line-no) if $line.contains("\t");
18 |         $line-no++;
19 |     }
20 |     if @lines {
21 |         flunk "$file has tabs on lines: {@lines}";
22 |     } else {
23 |         pass "$file has no tabs";
24 |     }
25 | }
26 | 


--------------------------------------------------------------------------------
/util/dumpast.raku:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env raku
2 | 
3 | # Generate the rakudoc AST for a given file
4 | 
5 | unit sub MAIN($file);
6 | 
7 | .say for $file.IO.slurp.AST.rakudoc
8 | 
9 | 


--------------------------------------------------------------------------------
/util/github-action-test.sh:
--------------------------------------------------------------------------------
 1 | #!/bin/bash -
 2 | 
 3 | # This script is run by the step 'Run tests' in the GitHub workflow "test"
 4 | # See .github/workflows/test.yml
 5 | 
 6 | set -ex
 7 | set -o pipefail
 8 | 
 9 | : ${TEST_IMAGE:=docker.io/jjmerelo/perl6-doccer:latest}
10 | : ${RAKU_DOC_TEST_VERBOSE:=1}
11 | 
12 | # this default value allows one to run a command like
13 | # ./util/github-action-test.sh
14 | : ${GITHUB_WORKSPACE:=${PWD}}
15 | 
16 | # if no argument is given run tests from t/
17 | if [[ $# -eq 0 ]]; then
18 |   set -- t
19 | fi
20 | 
21 | docker run -t \
22 |   -v "${GITHUB_WORKSPACE}":/test:Z \
23 |   --entrypoint env \
24 |   "${TEST_IMAGE}" \
25 |   RAKU_DOC_TEST_VERBOSE=${RAKU_DOC_TEST_VERBOSE} \
26 |   prove6 "$@"
27 | 


--------------------------------------------------------------------------------
/util/missing-types.raku:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | # This script parses the type-graph.txt file and checks
 4 | # the existence of the corresponding rakudoc file for most entries
 5 | # skips: Metamodel and PROCESS types
 6 | 
 7 | use lib 'lib';
 8 | use Doc::TypeGraph;
 9 | 
10 | # These are core but not loaded by default.
11 | use Telemetry;
12 | use Test;
13 | 
14 | my $t = Doc::TypeGraph.new-from-file('type-graph.txt');
15 | 
16 | for $t.sorted  -> $type {
17 |     next if $type.name.index('Metamodel').defined || $type.name eq 'PROCESS';
18 |     my $actual = try ::($type.name);
19 |     printf "%-40s not defined in this version of Raku\n", $type.name()
20 |         if $actual === Any and $type.name ne "Any" | "Failure" | "Nil";
21 |     next unless $actual.^name eq $type.name;
22 |     my $filename = 'doc/Type/' ~ $type.name.subst(:g, '::', '/') ~ '.rakudoc';
23 |     printf "%-40s not found in documentation\n", $type.name() unless $filename.IO.e;
24 |     CATCH { default { } }
25 | }
26 | 


--------------------------------------------------------------------------------
/util/new-type.raku:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | # If the documentation for a type does not exist, create the skeleton of the doc
 4 | # $ raku util/new-type.raku --kind=role Some::Role
 5 | # this creates the file doc/Type/Some/Role.rakudoc
 6 | 
 7 | sub MAIN($typename, :$kind='class') {
 8 |     my @path-chunks =  $typename.split('::');
 9 |     my $filename = @path-chunks.pop ~ '.rakudoc';
10 |     my $path = 'doc/Type';
11 |     for @path-chunks -> $c {
12 |         $path ~= "/$c";
13 |         unless $path.IO.d {
14 |             mkdir $path.IO.mkdir;
15 |         }
16 |     }
17 | 
18 |     $path ~= "/$filename";
19 |     if $path.IO ~~ :e {
20 |         say "The file $path already exists.";
21 |         exit 1;
22 |     }
23 |     my $fh = open $path, :x;
24 | 
25 |     spurt $fh, Q:s:to/HEADER/;
26 |         =begin pod
27 | 
28 |         =TITLE $kind $typename
29 | 
30 |         =SUBTITLE ...
31 | 
32 |             $kind $typename is SuperClass { ... }
33 | 
34 |         Synopsis goes here
35 | 
36 |         HEADER
37 |     spurt $fh, Q:c:to/BODY/;
38 | 
39 |         =head1 Methods
40 | 
41 |         =head2 method flurb
42 | 
43 |             method flurb({$typename}:D: *@args --> Str)
44 | 
45 |         method description here
46 | 
47 |         =end pod
48 | 
49 |         BODY
50 |     $fh.close;
51 |     say "'$path' written";
52 |     say "(remember to 'git add $path')";
53 | }
54 | 


--------------------------------------------------------------------------------
/util/sort-words.raku:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | =begin overview
 4 | 
 5 | Sort words files as expected by xt/words.t
 6 | 
 7 | =end overview
 8 | 
 9 | my $word-io = $*PROGRAM.parent.parent.child('xt/pws/words.pws').IO;
10 | my $code-io = $*PROGRAM.parent.parent.child('xt/pws/code.pws').IO;
11 | 
12 | my @word = $word-io.lines;
13 | my @code = $code-io.lines;
14 | 
15 | my $header = @word.shift;
16 | 
17 | my $word-out = $word-io.open(:w);
18 | $word-out.say: $header;
19 | $word-out.say: @word.sort.unique.join("\n");
20 | 
21 | my $code-out = $code-io.open(:w);
22 | $code-out.say: @code.sort.unique.join("\n");
23 | 


--------------------------------------------------------------------------------
/util/test-modified.sh:
--------------------------------------------------------------------------------
1 | # This script will run make xtest on any files in the repository that have not yet been committed
2 | # use before 'git commit' to ensure your commit doesn't require correction.
3 | 
4 | export TEST_FILES=`git status --porcelain | grep ' M' | awk '{print $2}'`
5 | 
6 | [ "$TEST_FILES" = "" ] && echo "nothing to test"
7 | [ "$TEST_FILES" != "" ] && RAKULIB=. make xtest
8 | 


--------------------------------------------------------------------------------
/util/test-website.raku:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | my $dir = "doc-website".IO;
 4 | 
 5 | if $dir.d {
 6 |    run(, :cwd($dir));
 7 | } else {
 8 |     run();
 9 | }
10 | 
11 | my @files = $dir.child('Website').child('structure-sources').IO.dir;
12 | %*ENV=@files.join(' ');
13 | 
14 | run();
15 | 


--------------------------------------------------------------------------------
/util/update-and-test:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | =begin overview
 4 | 
 5 | Not everyone runs the extended test suite; this gives developers the ability
 6 | to test as they go; it updates the repository, runs xtest only on those
 7 | files that have changed in that update, and leaves a local C script
 8 | that can be rerun against those changes until xtest is clean.
 9 | 
10 | Note that test files are allowed to skip certain tests if they are run on a restricted
11 | subset of files; the full C should still be run on a regular basis.
12 | 
13 | =end overview
14 | 
15 | # Get the old and new commit IDs
16 | 
17 | sub get-rev {
18 |     run(, :out).out.slurp(:close).chomp;
19 | }
20 | 
21 | my $old-rev = get-rev;
22 | run();
23 | my $new-rev = get-rev;
24 | 
25 | 
26 | if $old-rev eq $new-rev {
27 |     say "No changes to test.";
28 | } else {
29 |     say "Updating prerequisites";
30 |     run();
31 | 
32 |     my $revs = $old-rev ~ ".." ~ $new-rev;
33 |     my $files = run('git', 'diff', '--name-only', $revs, :out).out.slurp(:close).chomp.split("\n").sort.join(" ");
34 |     my $outfile = "./retest";
35 | 
36 |     my $of = $outfile.IO.open(:w);
37 | 
38 |     $of.say: "#!/usr/bin/env raku";
39 |     $of.say: "\%*ENV='.';";
40 |     $of.say: "\%*ENV='$files';";
41 |     $of.say: "say \%*ENV;";
42 |     $of.say: "run().so";
43 | 
44 |     $of.close;
45 | 
46 |     run('chmod', 'a+x', $outfile);
47 | 
48 |     run($outfile).so;
49 |     say "Test same set of files again with $outfile";
50 | }
51 | 


--------------------------------------------------------------------------------
/writing-docs/CREATING-NEW-DOCS.md:
--------------------------------------------------------------------------------
 1 | ### A new (or existing) pod6 document currently must adhere to the following conventions:
 2 | 
 3 | 1. it must be valid Raku pod
 4 | 2. the first non-comment or non-empty line must be:
 5 | 
 6 |         =begin pod # optionally followed by :key %config pairs
 7 | 
 8 | 3. the second non-comment or non-empty line must be:
 9 | 
10 |         =TITLE ...text...
11 | 
12 | 4. an optional (but usually desired) subtitle must be the third non-comment or non-empty line:
13 | 
14 |         =SUBTITLE ...text...
15 | 
16 | 5. the last non-comment or non-empty line must be:
17 | 
18 |         =end pod
19 | 
20 | You can use
21 | 
22 |     TEST_FILES="files changed but not pushed" make xtest
23 | 
24 | To validate these and other conventions before committing.
25 | 
26 | ### Valid example:
27 | 
28 | ```
29 | # this is a valid, non-pod comment
30 | =begin pod :my-link # another comment
31 | =TITLE Working with Raku pod
32 | =SUBTITLE Alice in Wonderland
33 | # ... more valid pod and text
34 | =comment a pod comment # a valid comment
35 | =end pod
36 | # vi or emacs info
37 | ```
38 | 
39 | ### Invalid example:
40 | 
41 | ```
42 | =comment a pod comment # this is not a valid comment in this position
43 | =begin pod :my-link # another comment
44 | =TITLE Working with Raku pod
45 | =SUBTITLE Alice in Wonderland
46 | # ... more valid pod and text
47 | =end pod
48 | # vi or emacs info
49 | ```
50 | 


--------------------------------------------------------------------------------
/writing-docs/README.md:
--------------------------------------------------------------------------------
 1 | # How to help
 2 | 
 3 | Raku is not a small language, and documenting it and maintaining that
 4 | documentation takes a lot of effort. Any help is appreciated.
 5 | 
 6 | Here are some ways to contribute:
 7 | 
 8 |  * Add missing documentation for classes, roles, methods or operators. _Except
 9 |    superclasses & roles, those are already included in the website generated from this repository._
10 |  * Add usage examples to existing documentation.
11 |  * Proofread and correct the documentation.
12 |  * Tell us about missing documentation by [opening issues](https://github.com/Raku/doc/issues)
13 |  * Do a `git grep TODO` in this repository, and replace the TODO items by
14 |    actual documentation.
15 | 
16 | [Issues page](https://github.com/Raku/doc/issues) has a list of current issues and
17 | documentation parts that are known to be missing
18 | and [the CONTRIBUTING document](../CONTRIBUTING.md)
19 | explains briefly how to get started contributing documentation.
20 | 
21 | # Other docs
22 | 
23 | For specific topics, please see:
24 | 
25 |    * [CREATING-NEW-DOCS.md](CREATING-NEW-DOCS.md)
26 |    * [EXAMPLES.md](EXAMPLES.md)
27 |    * [INDEXING.md](INDEXING.md)
28 |    * [STYLEGUIDE.md](STYLEGUIDE.md)
29 | 
30 | # Pull Requests
31 | 
32 | The preferred mechanism for submitting content is [pull requests](https://github.com/Raku/doc/pulls).
33 | 
34 | When submitting a PR, please ensure that you've run `make xtest` for any modified files. See [Testing.md](Testing.md)
35 | for more details.
36 | 


--------------------------------------------------------------------------------
/xt/01-raku-version.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | 
 5 | use JSON::Fast;
 6 | 
 7 | =begin overview
 8 | 
 9 | Verify that the version of rakudo used to run the tests is recent enough.
10 | 
11 | To avoid issues with a mismatch on source or compilation testing, and to
12 | require a recent enough version for RakuAST classes.
13 | 
14 | =end overview
15 | 
16 | plan 1;
17 | 
18 | {
19 |     my $web = run('curl', '-L', '-H', "Accept: application/vnd.github+json", '-H', "X-GitHub-Api-Version: 2022-11-28", "https://api.github.com/repos/rakudo/rakudo/releases?per_page=1", :out, :err);
20 |     my $desired = Version.new((from-json $web.out.slurp(:close))[0]);
21 | 
22 |     my $actual = $*RAKU.compiler.version;
23 | 
24 |     ok $actual >= $desired, "using at least version $desired for testing (found $actual)";
25 | 
26 |     CATCH {
27 |         default {
28 |             flunk "Unable to check desired version; You may be offline.";
29 |         }
30 |     }
31 | }
32 | 


--------------------------------------------------------------------------------
/xt/braces.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | 
 5 | use Pod::Cache;
 6 | use Test-Files;
 7 | 
 8 | =begin overview
 9 | 
10 | Enforce B and B or B B.
11 | 
12 | =end overview
13 | 
14 | my @files = Test-Files.documents.grep(* ne "doc/Language/brackets.rakudoc");
15 | 
16 | if @files {
17 |     plan +@files;
18 | } else {
19 |     plan :skip-all
20 | }
21 | 
22 | sub test-it(Str $output, Str $file) {
23 |     my $ok = True;
24 | 
25 |     my $msg;
26 | 
27 |     my $line = $output.subst(/\s+/, ' ', :g)                         # canonicalize whitespace
28 |                       .subst('Opening bracket is required for', ''); # rakudo/rakudo#2672
29 | 
30 |     if $line ~~ /:i  ' ' 'braces' >> / {
31 |         $msg ~= "Found 'braces' without 'curly'. ";
32 |         $ok = False;
33 |     }
34 | 
35 |     if $line ~~ /:i  ' ' ('bracket' [s|ed]?) >> / {
36 |         $msg ~= "Found '{~$0}' without 'square' or 'angle'.";
37 |         $ok = False;
38 |     }
39 | 
40 |     ok $ok, $file ~ ($msg ?? ": $msg" !! "");
41 | }
42 | 
43 | for @files -> $file {
44 |     test-it(Pod::Cache.cache-file($file).IO.slurp, $file);
45 | }
46 | 


--------------------------------------------------------------------------------
/xt/double-dots.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | 
 5 | use Pod::Cache;
 6 | use Test-Files;
 7 | 
 8 | =begin overview
 9 | 
10 | Avoid using C<..> - usually a typo for C<.> or C<...>
11 | 
12 | =end overview
13 | 
14 | my @files = Test-Files.documents;
15 | 
16 | if @files {
17 |     plan +@files;
18 | } else {
19 |     plan :skip-all
20 | }
21 | 
22 | sub test-it(Str $output, Str $file) {
23 |     my $ok = True;
24 | 
25 |     for $output.lines -> $line {
26 |         if $line ~~ /  '..' ( | $) / {
27 |             diag "Failure on line `$line`";
28 |             $ok = False;
29 |         }
30 |     }
31 |     my $error = $file;
32 |     ok $ok, "$error: file contains ..";
33 | }
34 | 
35 | for @files -> $file {
36 |     test-it(Pod::Cache.cache-file($file).IO.slurp, $file)
37 | }
38 | 


--------------------------------------------------------------------------------
/xt/final-newline.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | use Test-Files;
 5 | 
 6 | =begin overview
 7 | 
 8 | Make sure that text files end in a newline
 9 | 
10 | =end overview
11 | 
12 | my @files = Test-Files.files\
13 |     .grep({$_ ne 'LICENSE'})\
14 |     .grep({! $_.contains: 'custom-theme'})\
15 |     .grep({! $_.contains: 'util/trigger-rebuild.txt'});
16 | 
17 | if @files {
18 |     plan +@files;
19 | } else {
20 |     plan :skip-all;
21 | }
22 | 
23 | for @files -> $file {
24 |     ok $file.IO.slurp.substr(*-1) eq "\n", "$file must end in a newline";
25 | }
26 | 


--------------------------------------------------------------------------------
/xt/lib-test-files.raku:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | use Test-Files;
 5 | 
 6 | =begin overview
 7 | 
 8 | Exercise Test-Files command line.
 9 | 
10 | L invokes this script and its results are reported out through that C<.t> file
11 | 
12 | =end overview
13 | 
14 | say Test-Files.files().join(',');
15 | say '---';
16 | say Test-Files.pods().join(',');
17 | say '---';
18 | say Test-Files.documents().join(',');
19 | say '---';
20 | say Test-Files.tests().join(',');
21 | say '---';
22 | 


--------------------------------------------------------------------------------
/xt/perl-nbsp.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | use Test-Files;
 5 | 
 6 | =begin overview
 7 | 
 8 | Ensure any text that mentions Perl uses a no-break space after it.
 9 | 
10 | =end overview
11 | 
12 | my @files = Test-Files.documents;
13 | 
14 | if @files {
15 |     plan +@files;
16 | } else {
17 |     plan :skip-all
18 | }
19 | 
20 | for @files.sort -> $file {
21 |     my $err-count = 0;
22 |     my $content = $file.IO.slurp;
23 |     for $content ~~ m:g/  'Perl' $=(\s+) \d / -> $match {
24 |         my $spaces = ~$match;
25 |         if $spaces.chars != 1 || $spaces.uniname ne "NO-BREAK SPACE" {
26 |             $err-count++;
27 |         }
28 |     }
29 |     my $error = $file;
30 |     if $err-count {
31 |         $error ~= " ($err-count instance{$err-count==1 ?? '' !! 's'})";
32 |     }
33 |     ok !$err-count, "$error: Perl followed by a version should have a single non-breaking space." ;
34 | }
35 | 


--------------------------------------------------------------------------------
/xt/return-type.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | use Test-Files;
 5 | 
 6 | # Every .rakudoc file in the Type directory.
 7 | my @files = Test-Files.pods.grep(* ~~ /Type | Language/);
 8 | 
 9 | if @files {
10 |     plan +@files;
11 | } else {
12 |     plan :skip-all
13 | }
14 | 
15 | for @files -> $file {
16 |     my @lines;
17 |     my Int $line-no = 1;
18 |     for $file.IO.lines -> $line {
19 |         if so $line ~~ /(multi|method|sub) .+? ')' \s+? 'returns' \s+? (|':')+? $/ {
20 |             @lines.push($line-no);
21 |         }
22 |         $line-no++;
23 |     }
24 |     if @lines {
25 |         flunk "$file uses 'returns' at lines: {@lines}; should be -->";
26 |     } else {
27 |         pass "$file return types are ok";
28 |     }
29 | }
30 | 


--------------------------------------------------------------------------------
/xt/trailing-whitespace.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | use Test-Files;
 5 | 
 6 | =begin overview
 7 | 
 8 | Make sure that no line includes trailing whitespace.
 9 | 
10 | =end overview
11 | 
12 | my @files = Test-Files.files.grep({$_ ne 'LICENSE'});
13 | 
14 | plan +@files;
15 | 
16 | for @files -> $file {
17 |     my $ok = True;
18 |     my $row = 0;
19 |     for $file.IO.lines -> $line {
20 |         ++$row;
21 |         if $line ~~ / \s $/ {
22 |            $ok = False; last;
23 |         }
24 |     }
25 |     my $error = $file;
26 |     $error ~= " (line $row)" if !$ok;
27 |     ok $ok, "$error: Must not have any trailing whitespace.";
28 | }
29 | 


--------------------------------------------------------------------------------
/xt/type-graph.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | use Doc::TypeGraph;
 5 | use Telemetry;
 6 | 
 7 | my $t = Doc::TypeGraph.new-from-file('type-graph.txt');
 8 | 
 9 | for $t.sorted -> $type {
10 |     next if $type.name.index('Metamodel').defined || $type.name eq 'PROCESS';
11 |     next if $type.packagetype eq 'role'|'module';
12 |     # these types does not support mro => whitelisted
13 |     next if $type.name eq any();
14 |     try {
15 |         my $expected = ~$type.mro;
16 |         my $got = ~::($type).^mro.map: *.^name;
17 |         is $got, $expected, $type;
18 |         CATCH {
19 |             default {
20 |                 flunk "Trouble with $type: $_";
21 |             }
22 |         }
23 |     }
24 | }
25 | 
26 | done-testing;
27 | 


--------------------------------------------------------------------------------
/xt/vim-mode.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | use Test-Files;
 5 | 
 6 | =begin overview
 7 | 
 8 | Make sure no files include the vim mode line.
 9 | 
10 | This was historically useful but is now considered harmful.
11 | 
12 | https://github.com/Raku/doc/issues/3058
13 | 
14 | =end overview
15 | 
16 | my @files = Test-Files.files;
17 | 
18 | if @files {
19 |     plan +@files;
20 | } else {
21 |     plan :skip-all;
22 | }
23 | 
24 | for @files -> $file {
25 |     nok $file.IO.slurp ~~ /^^ '# vim: '/, "$file must not contain vim mode line";
26 | }
27 | 


--------------------------------------------------------------------------------
/xt/words.rakutest:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env raku
 2 | 
 3 | use Test;
 4 | 
 5 | =begin overview
 6 | 
 7 | Verify setup of lexicon files used to drive C.
 8 | 
 9 | Avoid duplicates, verify header, lowercase, sorting.
10 | 
11 | =end overview
12 | 
13 | plan 6;
14 | 
15 | my @words = $*PROGRAM.parent.child('pws/words.pws').IO.lines;
16 | my @code = $*PROGRAM.parent.child('pws/code.pws').IO.lines;
17 | 
18 | my $header = @words.shift;
19 | 
20 | ok($header ~~  / 'personal_ws-1.1 en ' \d+  ' utf-8' /, "header on xt/pws/words.pws is correct");
21 | 
22 | sub sorted(@lexicon) {
23 |     return [&&] @lexicon.rotor(2 => -1).map({$_[0] lt $_[1]})
24 | }
25 | 
26 | ok(sorted(@words), "xt/pws/words.pws is sorted and unique");
27 | ok(sorted(@code), "xt/pws/code.pws is sorted and unique");
28 | 
29 | my @dupes = @words.Set ∩ @code.Set;
30 | 
31 | is(~@dupes, "", "No duplicates between xt/pws/words.pws and xt/pws/code.pws");
32 | 
33 | # are all the words lower case?
34 | # (ignore some unicode that aspell doesn't case fold as well as we do.
35 | sub get-uppers(@lexicon) {
36 |     @lexicon.grep({ .lc ne $_ }).grep({ ! $_.contains('Þ') })
37 | }
38 | 
39 | my $uppers = get-uppers(@words);
40 | is($uppers.elems, 0, "all words in xt/pws/words.pws are lowercase");
41 | diag $uppers if $uppers.elems;
42 | 
43 | $uppers = get-uppers(@code);
44 | is($uppers.elems, 0, "all words in xt/pws/code.pws are lowercase");
45 | diag $uppers if $uppers.elems;
46 | 


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