This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <html><body><div class='index'> | |
| <div class='entry'><a href="issues.html#374"><span class='number'>374</span></a> [open] <span class='title'>Errors should not be adhoc in core</span></div> | |
| <div class='entry'><a href="issues.html#370"><span class='number'>370</span></a> [open] <span class='title'>A way around "multi-level classification"</span></div> | |
| <div class='entry'><a href="issues.html#366"><span class='number'>366</span></a> [open] <span class='title'>`next`, `last`, `redo` shouldn't fall through subroutines</span></div> | |
| <div class='entry'><a href="issues.html#362"><span class='number'>362</span></a> [open] <span class='title'>Expand DEPRECATED functionality.</span></div> | |
| <div class='entry'><a href="issues.html#369"><span class='number'>369</span></a> [open] <span class='title'>Provide `sort` with `:k` adverb (returns ordinal index)</span></div> | |
| <div class='entry'><a href="issues.html#368"><span class='number'>368</span></a> [open] <span class='title'>LinkedIn does not recognize "Raku Developer" as a job title.</span></div> | |
| <div class='entry'><a href="issues.html#361"><span class='number'>361</span></a> [open] <span class='title'>`LEAVE` phaser fires when errorring in argument binding</span></div> | |
| <div class='entry'><a href="issues.html#367"><span class='number'>367</span></a> [open] <span class='title'>Add :k option to min and max</span></div> | |
| <div class='entry'><a href="issues.html#373"><span class='number'>373</span></a> [open] <span class='title'>Rakudoc in third-party modules and some related topics</span></div> | |
| <div class='entry'><a href="issues.html#358"><span class='number'>358</span></a> [open] <span class='title'>Request to deprecate untwigiled attributes </span></div> | |
| <div class='entry'><a href="issues.html#365"><span class='number'>365</span></a> [open] <span class='title'>Spectesting is a minefield</span></div> | |
| <div class='entry'><a href="issues.html#357"><span class='number'>357</span></a> [open] <span class='title'>Handling of non-breaking spaces when splitting to words</span></div> | |
| <div class='entry'><a href="issues.html#364"><span class='number'>364</span></a> [open] <span class='title'>Supply blocks may reorder flow of execution</span></div> | |
| <div class='entry'><a href="issues.html#372"><span class='number'>372</span></a> [open] <span class='title'>Are Captures value types or not?</span></div> | |
| <div class='entry'><a href="issues.html#363"><span class='number'>363</span></a> [closed] <span class='title'>Feature request: snip counterpart for Str</span></div> | |
| <div class='entry'><a href="issues.html#371"><span class='number'>371</span></a> [closed] <span class='title'>Trailing declarator docs semantics need to be revisited</span></div> | |
| <div class='entry'><a href="issues.html#355"><span class='number'>355</span></a> [open] <span class='title'>Choose some precise (or rough) way to "adopt" modules in the Raku Module Adoption center</span></div> | |
| <div class='entry'><a href="issues.html#351"><span class='number'>351</span></a> [open] <span class='title'>Deprecation of flatmap is foggy and debatable</span></div> | |
| <div class='entry'><a href="issues.html#347"><span class='number'>347</span></a> [open] <span class='title'>The Path to Raku, revisited</span></div> | |
| <div class='entry'><a href="issues.html#343"><span class='number'>343</span></a> [open] <span class='title'>When and by whom should changes in Rakudo be documented?</span></div> | |
| <div class='entry'><a href="issues.html#346"><span class='number'>346</span></a> [open] <span class='title'>Semantics of hyper metaoperators - direction, "dwimminess", dimensions, etc.</span></div> | |
| <div class='entry'><a href="issues.html#345"><span class='number'>345</span></a> [closed] <span class='title'>The semantics of >>.foo feel wrong and possibly need changing</span></div> | |
| <div class='entry'><a href="issues.html#354"><span class='number'>354</span></a> [open] <span class='title'>`min` is presumptuous (on empty iterables)</span></div> | |
| <div class='entry'><a href="issues.html#350"><span class='number'>350</span></a> [closed] <span class='title'>Smartmatching to S/// is not a bug but a feature</span></div> | |
| <div class='entry'><a href="issues.html#342"><span class='number'>342</span></a> [closed] <span class='title'>"Failure is Nil" and the anomalies this leads to</span></div> | |
| <div class='entry'><a href="issues.html#344"><span class='number'>344</span></a> [open] <span class='title'>Interoperability of numeric type objects</span></div> | |
| <div class='entry'><a href="issues.html#353"><span class='number'>353</span></a> [open] <span class='title'>Artistic License not a default on Github</span></div> | |
| <div class='entry'><a href="issues.html#349"><span class='number'>349</span></a> [open] <span class='title'>Raku / Perl 6 books - CCR measures and beyond</span></div> | |
| <div class='entry'><a href="issues.html#348"><span class='number'>348</span></a> [open] <span class='title'>What to do with https://twitter.com/raku_news ?</span></div> | |
| <div class='entry'><a href="issues.html#352"><span class='number'>352</span></a> [open] <span class='title'>Wanted: new Raku Infrastructure jack-of-all-trades</span></div> | |
| <div class='entry'><a href="issues.html#339"><span class='number'>339</span></a> [open] <span class='title'>Should the `handles` trait delegate by name or by code reference?</span></div> | |
| <div class='entry'><a href="issues.html#338"><span class='number'>338</span></a> [closed] <span class='title'>Include line numbers in Pod::Blocks</span></div> | |
| <div class='entry'><a href="issues.html#337"><span class='number'>337</span></a> [open] <span class='title'>Function return types should also tell about the used assignment/container</span></div> | |
| <div class='entry'><a href="issues.html#335"><span class='number'>335</span></a> [open] <span class='title'>Does -I Directory Order Affect Whether Modules are Recompiled?</span></div> | |
| <div class='entry'><a href="issues.html#330"><span class='number'>330</span></a> [open] <span class='title'>modules.raku.org should be deprecated</span></div> | |
| <div class='entry'><a href="issues.html#334"><span class='number'>334</span></a> [closed] <span class='title'>Class construction: should we reconsider our approach for performance?</span></div> | |
| <div class='entry'><a href="issues.html#336"><span class='number'>336</span></a> [open] <span class='title'>Alternate name for MONKEY pragmas</span></div> | |
| <div class='entry'><a href="issues.html#341"><span class='number'>341</span></a> [closed] <span class='title'>Rakudoc Delimited Block Comments</span></div> | |
| <div class='entry'><a href="issues.html#328"><span class='number'>328</span></a> [closed] <span class='title'>Adding head, skip, tail as subroutines</span></div> | |
| <div class='entry'><a href="issues.html#333"><span class='number'>333</span></a> [open] <span class='title'>Specify an implementation neutral method for extracting pod</span></div> | |
| <div class='entry'><a href="issues.html#340"><span class='number'>340</span></a> [open] <span class='title'>Dependency hell in Raku</span></div> | |
| <div class='entry'><a href="issues.html#327"><span class='number'>327</span></a> [open] <span class='title'>Inherit(aliz)ability and compos(aliz)ability are too ad-hoc</span></div> | |
| <div class='entry'><a href="issues.html#326"><span class='number'>326</span></a> [open] <span class='title'>`div` and `mod` don't convert to Int, unlike everything else</span></div> | |
| <div class='entry'><a href="issues.html#332"><span class='number'>332</span></a> [open] <span class='title'>POD6 consistency problems</span></div> | |
| <div class='entry'><a href="issues.html#324"><span class='number'>324</span></a> [closed] <span class='title'>Taking responsibility for Raku Documentation issues</span></div> | |
| <div class='entry'><a href="issues.html#317"><span class='number'>317</span></a> [open] <span class='title'>Uniform approach to distributing important messages about Raku</span></div> | |
| <div class='entry'><a href="issues.html#313"><span class='number'>313</span></a> [open] <span class='title'>"Tight or" precedence level of //, min, max operators</span></div> | |
| <div class='entry'><a href="issues.html#308"><span class='number'>308</span></a> [open] <span class='title'>More flexible Phasers</span></div> | |
| <div class='entry'><a href="issues.html#323"><span class='number'>323</span></a> [closed] <span class='title'>Our symbol resolution implementation is totally counter-thread-safe</span></div> | |
| <div class='entry'><a href="issues.html#316"><span class='number'>316</span></a> [closed] <span class='title'>Preparing the Raku Ecosystem for the Future</span></div> | |
| <div class='entry'><a href="issues.html#312"><span class='number'>312</span></a> [closed] <span class='title'>Wrong behavior is specced for classify method</span></div> | |
| <div class='entry'><a href="issues.html#311"><span class='number'>311</span></a> [closed] <span class='title'>Make Junction a value object.</span></div> | |
| <div class='entry'><a href="issues.html#321"><span class='number'>321</span></a> [closed] <span class='title'>Allow "bare" indexing terms in documentation</span></div> | |
| <div class='entry'><a href="issues.html#315"><span class='number'>315</span></a> [open] <span class='title'>Make grammars called from grammars more intuitive</span></div> | |
| <div class='entry'><a href="issues.html#307"><span class='number'>307</span></a> [open] <span class='title'>Destructuring assignment lhs has different semantics from the corresponding literal</span></div> | |
| <div class='entry'><a href="issues.html#309"><span class='number'>309</span></a> [open] <span class='title'>A Mechanism for Adding Hooks into CURI for Custom Installation Output</span></div> | |
| <div class='entry'><a href="issues.html#314"><span class='number'>314</span></a> [open] <span class='title'>Operator precedence/associativity API needed</span></div> | |
| <div class='entry'><a href="issues.html#319"><span class='number'>319</span></a> [open] <span class='title'>Junctions with comparisons - or why is != meta</span></div> | |
| <div class='entry'><a href="issues.html#306"><span class='number'>306</span></a> [open] <span class='title'>No easy way to inspect distributions</span></div> | |
| <div class='entry'><a href="issues.html#305"><span class='number'>305</span></a> [open] <span class='title'>Semi-predicate situation with `is required` and defaults on native attributes</span></div> | |
| <div class='entry'><a href="issues.html#304"><span class='number'>304</span></a> [open] <span class='title'>INIT blocks in module does not behave nicely</span></div> | |
| <div class='entry'><a href="issues.html#299"><span class='number'>299</span></a> [open] <span class='title'>Edge cases of nominalizable typeobjects interactions</span></div> | |
| <div class='entry'><a href="issues.html#295"><span class='number'>295</span></a> [closed] <span class='title'>Moving distributions between distribution backends "duplicates" them</span></div> | |
| <div class='entry'><a href="issues.html#303"><span class='number'>303</span></a> [open] <span class='title'>Signature parameter introspection for type smileys/signature modifiers</span></div> | |
| <div class='entry'><a href="issues.html#298"><span class='number'>298</span></a> [closed] <span class='title'>Consider renaming default branch from master to main</span></div> | |
| <div class='entry'><a href="issues.html#302"><span class='number'>302</span></a> [open] <span class='title'>API reconciliation between Blob/Buf, CArray, and native array</span></div> | |
| <div class='entry'><a href="issues.html#291"><span class='number'>291</span></a> [closed] <span class='title'>Scalar.WHICH semantics is incorrect</span></div> | |
| <div class='entry'><a href="issues.html#301"><span class='number'>301</span></a> [open] <span class='title'>Issues with the design of `assuming` method</span></div> | |
| <div class='entry'><a href="issues.html#290"><span class='number'>290</span></a> [open] <span class='title'>"assuming" is a big word</span></div> | |
| <div class='entry'><a href="issues.html#294"><span class='number'>294</span></a> [open] <span class='title'>Particular scopes of PseudoStash'es are not clear</span></div> | |
| <div class='entry'><a href="issues.html#297"><span class='number'>297</span></a> [closed] <span class='title'>"In general, the left side of `~~` should not be auto-threading"</span></div> | |
| <div class='entry'><a href="issues.html#286"><span class='number'>286</span></a> [open] <span class='title'>Separate Community Resource pages</span></div> | |
| <div class='entry'><a href="issues.html#285"><span class='number'>285</span></a> [open] <span class='title'>Datish should have a `.fmt` command and its formatter should be deprecated</span></div> | |
| <div class='entry'><a href="issues.html#284"><span class='number'>284</span></a> [open] <span class='title'>Terminal circumfix token should have (optionally) higher precedence</span></div> | |
| <div class='entry'><a href="issues.html#293"><span class='number'>293</span></a> [open] <span class='title'>Subtyping by augmentation is too ad-hoc</span></div> | |
| <div class='entry'><a href="issues.html#283"><span class='number'>283</span></a> [open] <span class='title'>There should be a (relatively easy) way to specify how to test for non-Raku dependencies</span></div> | |
| <div class='entry'><a href="issues.html#292"><span class='number'>292</span></a> [closed] <span class='title'>Priority of `let` and `temp` operators give them WAT behavior</span></div> | |
| <div class='entry'><a href="issues.html#288"><span class='number'>288</span></a> [open] <span class='title'>Perl5 support specced in roast is questionable</span></div> | |
| <div class='entry'><a href="issues.html#287"><span class='number'>287</span></a> [open] <span class='title'>HyperWhatever in subscripts</span></div> | |
| <div class='entry'><a href="issues.html#296"><span class='number'>296</span></a> [open] <span class='title'>&-sigiled terms an possibly other emergent "features"</span></div> | |
| <div class='entry'><a href="issues.html#282"><span class='number'>282</span></a> [open] <span class='title'>Proposal: q:thru/DELIM/ heredocs</span></div> | |
| <div class='entry'><a href="issues.html#277"><span class='number'>277</span></a> [open] <span class='title'>We (probably) need Rakudo specs</span></div> | |
| <div class='entry'><a href="issues.html#270"><span class='number'>270</span></a> [closed] <span class='title'>new Coercion protocol creates an opportunity for more ergonomic coercions </span></div> | |
| <div class='entry'><a href="issues.html#262"><span class='number'>262</span></a> [closed] <span class='title'>The Raku Conference</span></div> | |
| <div class='entry'><a href="issues.html#269"><span class='number'>269</span></a> [closed] <span class='title'>conf.raku.org DNS record</span></div> | |
| <div class='entry'><a href="issues.html#276"><span class='number'>276</span></a> [open] <span class='title'>:ignoremark is overzealous</span></div> | |
| <div class='entry'><a href="issues.html#280"><span class='number'>280</span></a> [closed] <span class='title'>Preserving / Accessing Raku IRC Log History</span></div> | |
| <div class='entry'><a href="issues.html#268"><span class='number'>268</span></a> [closed] <span class='title'>Clarify "On Behalf of Community"</span></div> | |
| <div class='entry'><a href="issues.html#275"><span class='number'>275</span></a> [closed] <span class='title'>Expressing the idea that a function successfully returned nothing is difficult </span></div> | |
| <div class='entry'><a href="issues.html#279"><span class='number'>279</span></a> [open] <span class='title'>No literal syntax for sparse arrays</span></div> | |
| <div class='entry'><a href="issues.html#263"><span class='number'>263</span></a> [closed] <span class='title'>The Raku Foundation</span></div> | |
| <div class='entry'><a href="issues.html#272"><span class='number'>272</span></a> [closed] <span class='title'>The PS-process' acceptance policy doesn't match reality</span></div> | |
| <div class='entry'><a href="issues.html#260"><span class='number'>260</span></a> [closed] <span class='title'>Provide a way to explicitly set arg0 when calling a program</span></div> | |
| <div class='entry'><a href="issues.html#278"><span class='number'>278</span></a> [open] <span class='title'>Coercer methods for parametrised roles</span></div> | |
| <div class='entry'><a href="issues.html#259"><span class='number'>259</span></a> [closed] <span class='title'>Method `reverse` on ranges should produce ranges</span></div> | |
| <div class='entry'><a href="issues.html#257"><span class='number'>257</span></a> [closed] <span class='title'>Subdomain for the Raku Course</span></div> | |
| <div class='entry'><a href="issues.html#252"><span class='number'>252</span></a> [open] <span class='title'>Documentation and the ecosystem</span></div> | |
| <div class='entry'><a href="issues.html#251"><span class='number'>251</span></a> [open] <span class='title'>Add a forum to support the Raku community and provide a searchable repository of Q&A</span></div> | |
| <div class='entry'><a href="issues.html#258"><span class='number'>258</span></a> [closed] <span class='title'>Independent CI server for Raku modules and infrastructure</span></div> | |
| <div class='entry'><a href="issues.html#250"><span class='number'>250</span></a> [closed] <span class='title'>Documentation search categories are not standardized</span></div> | |
| <div class='entry'><a href="issues.html#255"><span class='number'>255</span></a> [open] <span class='title'>`constant` for many identifiers in single declaration</span></div> | |
| <div class='entry'><a href="issues.html#249"><span class='number'>249</span></a> [open] <span class='title'>Make react return values</span></div> | |
| <div class='entry'><a href="issues.html#254"><span class='number'>254</span></a> [open] <span class='title'>Name (and release date) proposal for 6.e</span></div> | |
| <div class='entry'><a href="issues.html#253"><span class='number'>253</span></a> [open] <span class='title'>Rakudo releases (and probably zef too) need a long-term support strategy</span></div> | |
| <div class='entry'><a href="issues.html#248"><span class='number'>248</span></a> [open] <span class='title'>raku --doc should get a pager</span></div> | |
| <div class='entry'><a href="issues.html#244"><span class='number'>244</span></a> [closed] <span class='title'>How should modules/distributions be handled when severe security issues are discovered?</span></div> | |
| <div class='entry'><a href="issues.html#239"><span class='number'>239</span></a> [open] <span class='title'>Taking care of repos in the "perl6" organization</span></div> | |
| <div class='entry'><a href="issues.html#235"><span class='number'>235</span></a> [open] <span class='title'>What is the philosophy of the Raku language</span></div> | |
| <div class='entry'><a href="issues.html#234"><span class='number'>234</span></a> [open] <span class='title'>To what extent are resources part of the API of a distribution?</span></div> | |
| <div class='entry'><a href="issues.html#238"><span class='number'>238</span></a> [closed] <span class='title'>What action should be taken in response to AlexDaniel's behavior with other developers</span></div> | |
| <div class='entry'><a href="issues.html#247"><span class='number'>247</span></a> [closed] <span class='title'>Using a Pager for POD6</span></div> | |
| <div class='entry'><a href="issues.html#233"><span class='number'>233</span></a> [open] <span class='title'>IO::Path and Distribution::Resource share many methods</span></div> | |
| <div class='entry'><a href="issues.html#246"><span class='number'>246</span></a> [open] <span class='title'>There's no effective way to communicate something to all people with commit bits in the different Raku repos and organizations</span></div> | |
| <div class='entry'><a href="issues.html#243"><span class='number'>243</span></a> [open] <span class='title'>Raku lacks a generic way of handling backend constants (signals, protocol families, etc.)</span></div> | |
| <div class='entry'><a href="issues.html#241"><span class='number'>241</span></a> [closed] <span class='title'>Add codesections to «meta» reviewers</span></div> | |
| <div class='entry'><a href="issues.html#232"><span class='number'>232</span></a> [open] <span class='title'>Add a "community" label for issues that don't fit existing labels</span></div> | |
| <div class='entry'><a href="issues.html#245"><span class='number'>245</span></a> [open] <span class='title'>How should modules/distributions be handled when severe security issues are discovered?</span></div> | |
| <div class='entry'><a href="issues.html#231"><span class='number'>231</span></a> [open] <span class='title'>Add a Raku blog site as "blogs.raku.org"</span></div> | |
| <div class='entry'><a href="issues.html#240"><span class='number'>240</span></a> [open] <span class='title'>Manage GitHub (and other) organization secrets</span></div> | |
| <div class='entry'><a href="issues.html#237"><span class='number'>237</span></a> [open] <span class='title'>`language` `rakudo` `moarvm` labels have no dev responsible for them</span></div> | |
| <div class='entry'><a href="issues.html#227"><span class='number'>227</span></a> [closed] <span class='title'>Coercion reconsidered and unified</span></div> | |
| <div class='entry'><a href="issues.html#236"><span class='number'>236</span></a> [open] <span class='title'>META6 specification only exists "de facto"</span></div> | |
| <div class='entry'><a href="issues.html#230"><span class='number'>230</span></a> [closed] <span class='title'>rx:s/ / is considered a null regex</span></div> | |
| <div class='entry'><a href="issues.html#229"><span class='number'>229</span></a> [open] <span class='title'>Ecosystem name resolution security problem</span></div> | |
| <div class='entry'><a href="issues.html#228"><span class='number'>228</span></a> [open] <span class='title'>Coercing a string with a Roman numeral throws an error</span></div> | |
| <div class='entry'><a href="issues.html#226"><span class='number'>226</span></a> [closed] <span class='title'>META6.json perl key</span></div> | |
| <div class='entry'><a href="issues.html#225"><span class='number'>225</span></a> [open] <span class='title'>Extended identifiers- reserving :sym puzzles me</span></div> | |
| <div class='entry'><a href="issues.html#224"><span class='number'>224</span></a> [open] <span class='title'>Extended identifiers-why and where, exactly?</span></div> | |
| <div class='entry'><a href="issues.html#223"><span class='number'>223</span></a> [open] <span class='title'>Map parameterized vs Hash parameterized</span></div> | |
| <div class='entry'><a href="issues.html#218"><span class='number'>218</span></a> [open] <span class='title'>Destructuring infinite ranges and sequences</span></div> | |
| <div class='entry'><a href="issues.html#213"><span class='number'>213</span></a> [open] <span class='title'>Loading of custom setting logic is undefined</span></div> | |
| <div class='entry'><a href="issues.html#209"><span class='number'>209</span></a> [open] <span class='title'>Exponentiation with Rat or FatRat exponent results in Num</span></div> | |
| <div class='entry'><a href="issues.html#212"><span class='number'>212</span></a> [open] <span class='title'>pl6anet.org is a name that does not reflect Raku</span></div> | |
| <div class='entry'><a href="issues.html#211"><span class='number'>211</span></a> [open] <span class='title'>The behaviour of -I and 'use lib' can be confusing if there is a META6.json in play</span></div> | |
| <div class='entry'><a href="issues.html#217"><span class='number'>217</span></a> [open] <span class='title'>Uncertain status of tests in the roast</span></div> | |
| <div class='entry'><a href="issues.html#222"><span class='number'>222</span></a> [open] <span class='title'>Introspection for operator precedence, associativity</span></div> | |
| <div class='entry'><a href="issues.html#221"><span class='number'>221</span></a> [open] <span class='title'>.max on Iterables sorts on keys instead of values.</span></div> | |
| <div class='entry'><a href="issues.html#210"><span class='number'>210</span></a> [open] <span class='title'>The raku-community-modules organization and its problems. </span></div> | |
| <div class='entry'><a href="issues.html#208"><span class='number'>208</span></a> [open] <span class='title'>Could Raku benefit from a Flags type?</span></div> | |
| <div class='entry'><a href="issues.html#220"><span class='number'>220</span></a> [closed] <span class='title'>There should be a way of change the default class for sigiled attributes on custom classes</span></div> | |
| <div class='entry'><a href="issues.html#215"><span class='number'>215</span></a> [closed] <span class='title'>Do we need :desc named in Test routines?</span></div> | |
| <div class='entry'><a href="issues.html#207"><span class='number'>207</span></a> [open] <span class='title'>Raku needs a modern doc format that is familiar to most people</span></div> | |
| <div class='entry'><a href="issues.html#214"><span class='number'>214</span></a> [closed] <span class='title'>Allow overriding of compiler-handled operators</span></div> | |
| <div class='entry'><a href="issues.html#204"><span class='number'>204</span></a> [open] <span class='title'>[WIP] Some parts of Raku are improperly named</span></div> | |
| <div class='entry'><a href="issues.html#199"><span class='number'>199</span></a> [open] <span class='title'>More language revision related questions needs resolving.</span></div> | |
| <div class='entry'><a href="issues.html#195"><span class='number'>195</span></a> [open] <span class='title'>Use of literal named parameters syntax for multi-dispatching</span></div> | |
| <div class='entry'><a href="issues.html#194"><span class='number'>194</span></a> [closed] <span class='title'>Gist type objects as `Foo:U` rather than `(Foo)`</span></div> | |
| <div class='entry'><a href="issues.html#206"><span class='number'>206</span></a> [open] <span class='title'>Current Rakudo (possibly MoarVM as well) development process hinders releasing</span></div> | |
| <div class='entry'><a href="issues.html#203"><span class='number'>203</span></a> [open] <span class='title'>Managing the Raku project as it is Coming of Age</span></div> | |
| <div class='entry'><a href="issues.html#198"><span class='number'>198</span></a> [closed] <span class='title'>Should IO::Path.child default to :secure semantics</span></div> | |
| <div class='entry'><a href="issues.html#197"><span class='number'>197</span></a> [closed] <span class='title'>Writing BOMs for *all* utf16 encodings</span></div> | |
| <div class='entry'><a href="issues.html#196"><span class='number'>196</span></a> [closed] <span class='title'>Only allow IO::Path.open to create an IO::Handle</span></div> | |
| <div class='entry'><a href="issues.html#201"><span class='number'>201</span></a> [closed] <span class='title'>Calling vararg functions from NativeCall</span></div> | |
| <div class='entry'><a href="issues.html#200"><span class='number'>200</span></a> [closed] <span class='title'>The Problem Solving Process is not working</span></div> | |
| <div class='entry'><a href="issues.html#193"><span class='number'>193</span></a> [open] <span class='title'>Raku and/or Rakudo trademarks</span></div> | |
| <div class='entry'><a href="issues.html#190"><span class='number'>190</span></a> [closed] <span class='title'>.? behavior on signature mismatch: clarification of semantics</span></div> | |
| <div class='entry'><a href="issues.html#186"><span class='number'>186</span></a> [open] <span class='title'>Nativecall, native trait library usage rework</span></div> | |
| <div class='entry'><a href="issues.html#182"><span class='number'>182</span></a> [open] <span class='title'>What should be the size of `int`? (and other NativeCall type issues)</span></div> | |
| <div class='entry'><a href="issues.html#181"><span class='number'>181</span></a> [closed] <span class='title'>Should we allow directories as destinations for IO::Path.copy/move?</span></div> | |
| <div class='entry'><a href="issues.html#180"><span class='number'>180</span></a> [open] <span class='title'>A better MOP API for wrapper kinds could exist</span></div> | |
| <div class='entry'><a href="issues.html#179"><span class='number'>179</span></a> [closed] <span class='title'>Give Travis.com permission to access raku-community-modules repositories</span></div> | |
| <div class='entry'><a href="issues.html#189"><span class='number'>189</span></a> [closed] <span class='title'>Should we make short-id2class accessible?</span></div> | |
| <div class='entry'><a href="issues.html#188"><span class='number'>188</span></a> [closed] <span class='title'>Should we have a :todo named argument in test routines?</span></div> | |
| <div class='entry'><a href="issues.html#185"><span class='number'>185</span></a> [open] <span class='title'>A way to control Rat's behavior when it is running out of range for its denominator</span></div> | |
| <div class='entry'><a href="issues.html#191"><span class='number'>191</span></a> [closed] <span class='title'>Should Rakudo fail at compile time if it's possible?</span></div> | |
| <div class='entry'><a href="issues.html#184"><span class='number'>184</span></a> [closed] <span class='title'>Should ¿? and ¡! be an alternative to "" ?</span></div> | |
| <div class='entry'><a href="issues.html#187"><span class='number'>187</span></a> [open] <span class='title'>Use a grammar for command line options</span></div> | |
| <div class='entry'><a href="issues.html#177"><span class='number'>177</span></a> [open] <span class='title'>Making a signature accept a list of Pairs</span></div> | |
| <div class='entry'><a href="issues.html#173"><span class='number'>173</span></a> [closed] <span class='title'>Redesign Exceptions for subclassing</span></div> | |
| <div class='entry'><a href="issues.html#176"><span class='number'>176</span></a> [closed] <span class='title'>Rounding issues</span></div> | |
| <div class='entry'><a href="issues.html#175"><span class='number'>175</span></a> [closed] <span class='title'>"Sequence" means too many things in Raku</span></div> | |
| <div class='entry'><a href="issues.html#172"><span class='number'>172</span></a> [closed] <span class='title'>No easy way of getting the N highest/lowest items on a list</span></div> | |
| <div class='entry'><a href="issues.html#174"><span class='number'>174</span></a> [closed] <span class='title'>Attributes could use more support for reflection</span></div> | |
| <div class='entry'><a href="issues.html#183"><span class='number'>183</span></a> [closed] <span class='title'>What should unicode subscripts do? (and should they do anything at all?)</span></div> | |
| <div class='entry'><a href="issues.html#169"><span class='number'>169</span></a> [closed] <span class='title'>New public interfaces are often added without any chance for general consensus</span></div> | |
| <div class='entry'><a href="issues.html#164"><span class='number'>164</span></a> [closed] <span class='title'>$*CWD is an IO::Path, IO::Path.CWD is a Str</span></div> | |
| <div class='entry'><a href="issues.html#160"><span class='number'>160</span></a> [open] <span class='title'>Errors indexing past the end of a List</span></div> | |
| <div class='entry'><a href="issues.html#171"><span class='number'>171</span></a> [open] <span class='title'>printf padding and wide East Asian characters</span></div> | |
| <div class='entry'><a href="issues.html#163"><span class='number'>163</span></a> [closed] <span class='title'>Implement Adverb::Eject in core</span></div> | |
| <div class='entry'><a href="issues.html#168"><span class='number'>168</span></a> [open] <span class='title'>Abandoned modules, deceased authors, etc. (Raku Community Modules)</span></div> | |
| <div class='entry'><a href="issues.html#159"><span class='number'>159</span></a> [open] <span class='title'>The development experience around the generate-and-export pattern has shortcomings</span></div> | |
| <div class='entry'><a href="issues.html#167"><span class='number'>167</span></a> [open] <span class='title'>RAKUDOLIB destiny?</span></div> | |
| <div class='entry'><a href="issues.html#170"><span class='number'>170</span></a> [closed] <span class='title'>Provide better interface for dispatchers</span></div> | |
| <div class='entry'><a href="issues.html#162"><span class='number'>162</span></a> [closed] <span class='title'>Allow single-element Map/Hash to be treated as a Pair</span></div> | |
| <div class='entry'><a href="issues.html#158"><span class='number'>158</span></a> [open] <span class='title'>A new website for raku.org</span></div> | |
| <div class='entry'><a href="issues.html#166"><span class='number'>166</span></a> [closed] <span class='title'>qqx not picking up quotes in Windows 7</span></div> | |
| <div class='entry'><a href="issues.html#161"><span class='number'>161</span></a> [closed] <span class='title'>Should $foo ~~ Failure mark Failure in $foo as handled?</span></div> | |
| <div class='entry'><a href="issues.html#155"><span class='number'>155</span></a> [closed] <span class='title'>Routine doc pages need front matter</span></div> | |
| <div class='entry'><a href="issues.html#154"><span class='number'>154</span></a> [open] <span class='title'>uint's confused with int's</span></div> | |
| <div class='entry'><a href="issues.html#151"><span class='number'>151</span></a> [closed] <span class='title'>Visibility of dynamic symbols in async blocks</span></div> | |
| <div class='entry'><a href="issues.html#147"><span class='number'>147</span></a> [open] <span class='title'>SEO for the keyword "rakulang" seems poor</span></div> | |
| <div class='entry'><a href="issues.html#146"><span class='number'>146</span></a> [closed] <span class='title'>Expose nqp::findcclass and nqp::notfindclass functionality</span></div> | |
| <div class='entry'><a href="issues.html#145"><span class='number'>145</span></a> [closed] <span class='title'>Creating accessors for private attributes without adding them to the BUILDPLAN</span></div> | |
| <div class='entry'><a href="issues.html#157"><span class='number'>157</span></a> [open] <span class='title'>IO::Socket::INET's methods for socket creation may need reconsideration</span></div> | |
| <div class='entry'><a href="issues.html#153"><span class='number'>153</span></a> [closed] <span class='title'>RFE: REPL dependency check for Readline</span></div> | |
| <div class='entry'><a href="issues.html#152"><span class='number'>152</span></a> [open] <span class='title'>RFE: returns for multiple variables</span></div> | |
| <div class='entry'><a href="issues.html#143"><span class='number'>143</span></a> [closed] <span class='title'>Generalization of the "settings" concept</span></div> | |
| <div class='entry'><a href="issues.html#150"><span class='number'>150</span></a> [open] <span class='title'>Expmod returns a default value instead of erroring out on libtommath errors</span></div> | |
| <div class='entry'><a href="issues.html#149"><span class='number'>149</span></a> [open] <span class='title'>Routines could use more support for reflection</span></div> | |
| <div class='entry'><a href="issues.html#139"><span class='number'>139</span></a> [open] <span class='title'>perl6-users mailing list</span></div> | |
| <div class='entry'><a href="issues.html#142"><span class='number'>142</span></a> [closed] <span class='title'>export trait must operate with declared package name</span></div> | |
| <div class='entry'><a href="issues.html#138"><span class='number'>138</span></a> [closed] <span class='title'>What should `val()` support?</span></div> | |
| <div class='entry'><a href="issues.html#148"><span class='number'>148</span></a> [closed] <span class='title'>Add Str.(r)index(@needles)</span></div> | |
| <div class='entry'><a href="issues.html#141"><span class='number'>141</span></a> [open] <span class='title'>change the raku spec versioning</span></div> | |
| <div class='entry'><a href="issues.html#137"><span class='number'>137</span></a> [closed] <span class='title'>How to provide coercers for new types in higher language versions</span></div> | |
| <div class='entry'><a href="issues.html#134"><span class='number'>134</span></a> [closed] <span class='title'>Update or replace draft SoC/CCoC</span></div> | |
| <div class='entry'><a href="issues.html#144"><span class='number'>144</span></a> [closed] <span class='title'>Test Raku modules against different OS, Rakudo versions</span></div> | |
| <div class='entry'><a href="issues.html#135"><span class='number'>135</span></a> [closed] <span class='title'>Add Dict/Tuple to the core</span></div> | |
| <div class='entry'><a href="issues.html#133"><span class='number'>133</span></a> [open] <span class='title'>Remove P5 regexes from Raku</span></div> | |
| <div class='entry'><a href="issues.html#132"><span class='number'>132</span></a> [closed] <span class='title'>Release manager for Rakudo 2019.12 and onward</span></div> | |
| <div class='entry'><a href="issues.html#140"><span class='number'>140</span></a> [closed] <span class='title'>Logo issues and discussion</span></div> | |
| <div class='entry'><a href="issues.html#130"><span class='number'>130</span></a> [open] <span class='title'>"Path to Raku" is missing change of linux module namespaces</span></div> | |
| <div class='entry'><a href="issues.html#129"><span class='number'>129</span></a> [closed] <span class='title'>FQN method calls may need clarification</span></div> | |
| <div class='entry'><a href="issues.html#128"><span class='number'>128</span></a> [closed] <span class='title'>Implementation of importing of classes with composite names perhaps needs better consideration</span></div> | |
| <div class='entry'><a href="issues.html#127"><span class='number'>127</span></a> [open] <span class='title'>Dynamic symbols resolution via &DYNAMIC is potentially a problem in user code</span></div> | |
| <div class='entry'><a href="issues.html#131"><span class='number'>131</span></a> [closed] <span class='title'>Harassment by another member of the community</span></div> | |
| <div class='entry'><a href="issues.html#125"><span class='number'>125</span></a> [closed] <span class='title'>IO::Socket::INET and IO::Socket::Async need a redesign in v6.e</span></div> | |
| <div class='entry'><a href="issues.html#121"><span class='number'>121</span></a> [open] <span class='title'>Check MoarVM out using OSS-fuzz</span></div> | |
| <div class='entry'><a href="issues.html#120"><span class='number'>120</span></a> [open] <span class='title'>Wikipedia and Wikidata curation</span></div> | |
| <div class='entry'><a href="issues.html#124"><span class='number'>124</span></a> [closed] <span class='title'>What's exactly our stance regarding other Raku implementations?</span></div> | |
| <div class='entry'><a href="issues.html#117"><span class='number'>117</span></a> [open] <span class='title'>Creditcard for cloud services</span></div> | |
| <div class='entry'><a href="issues.html#112"><span class='number'>112</span></a> [closed] <span class='title'>Role concretization needs big improvements.</span></div> | |
| <div class='entry'><a href="issues.html#111"><span class='number'>111</span></a> [open] <span class='title'>Raku needs better ways to deal with network addresses</span></div> | |
| <div class='entry'><a href="issues.html#119"><span class='number'>119</span></a> [open] <span class='title'>Generic name for FALLBACK and CALL-ME</span></div> | |
| <div class='entry'><a href="issues.html#123"><span class='number'>123</span></a> [open] <span class='title'>`Supply.map` should respect the `Slip` semantics as `List.map` does</span></div> | |
| <div class='entry'><a href="issues.html#116"><span class='number'>116</span></a> [open] <span class='title'>Apply for AWS credit</span></div> | |
| <div class='entry'><a href="issues.html#122"><span class='number'>122</span></a> [open] <span class='title'>List should have `.do` method as Supply</span></div> | |
| <div class='entry'><a href="issues.html#118"><span class='number'>118</span></a> [closed] <span class='title'>Perl 6 to Raku timeframe</span></div> | |
| <div class='entry'><a href="issues.html#115"><span class='number'>115</span></a> [open] <span class='title'>Open a blog</span></div> | |
| <div class='entry'><a href="issues.html#110"><span class='number'>110</span></a> [closed] <span class='title'>FQN method call needs support for parameterized roles.</span></div> | |
| <div class='entry'><a href="issues.html#107"><span class='number'>107</span></a> [open] <span class='title'>Delegation does not handle multi-methods.</span></div> | |
| <div class='entry'><a href="issues.html#103"><span class='number'>103</span></a> [closed] <span class='title'>Roles, submethods, constructors, destructors.</span></div> | |
| <div class='entry'><a href="issues.html#106"><span class='number'>106</span></a> [closed] <span class='title'>Decision to be taken on Raku filename extensions.</span></div> | |
| <div class='entry'><a href="issues.html#113"><span class='number'>113</span></a> [closed] <span class='title'>0.0.gist returns "0" instead of "0.0" but 0.0.perl works as expected</span></div> | |
| <div class='entry'><a href="issues.html#102"><span class='number'>102</span></a> [closed] <span class='title'>Use of cmake for build subsystem</span></div> | |
| <div class='entry'><a href="issues.html#99"><span class='number'>99</span></a> [closed] <span class='title'>Unification of Array/List and Hash/Map behaviors.</span></div> | |
| <div class='entry'><a href="issues.html#108"><span class='number'>108</span></a> [closed] <span class='title'>New Raku file extensions</span></div> | |
| <div class='entry'><a href="issues.html#98"><span class='number'>98</span></a> [open] <span class='title'>Perl6 is missing the ability to store sub signatures for later use. Think Callbacks.</span></div> | |
| <div class='entry'><a href="issues.html#101"><span class='number'>101</span></a> [closed] <span class='title'>Perl 6, if renamed, needs new filename extensions</span></div> | |
| <div class='entry'><a href="issues.html#97"><span class='number'>97</span></a> [open] <span class='title'>Clean interpolation for enumerated character classes</span></div> | |
| <div class='entry'><a href="issues.html#95"><span class='number'>95</span></a> [open] <span class='title'>Alert system for core developers</span></div> | |
| <div class='entry'><a href="issues.html#94"><span class='number'>94</span></a> [closed] <span class='title'>Reconsider Rakudo build structure</span></div> | |
| <div class='entry'><a href="issues.html#96"><span class='number'>96</span></a> [open] <span class='title'>MoarVM Support of Callbacks in a Different Thread</span></div> | |
| <div class='entry'><a href="issues.html#93"><span class='number'>93</span></a> [open] <span class='title'>Specify documentation URLs</span></div> | |
| <div class='entry'><a href="issues.html#92"><span class='number'>92</span></a> [open] <span class='title'>there is no security process for receiving security critical bug reports</span></div> | |
| <div class='entry'><a href="issues.html#100"><span class='number'>100</span></a> [open] <span class='title'>stage0 is a binary blob, how can we do without it?</span></div> | |
| <div class='entry'><a href="issues.html#105"><span class='number'>105</span></a> [closed] <span class='title'>Ecosystem stability issues</span></div> | |
| <div class='entry'><a href="issues.html#104"><span class='number'>104</span></a> [closed] <span class='title'>A threat of full CORE duplication for each language revision</span></div> | |
| <div class='entry'><a href="issues.html#91"><span class='number'>91</span></a> [open] <span class='title'>.perl should be replaced with a pluggable system</span></div> | |
| <div class='entry'><a href="issues.html#85"><span class='number'>85</span></a> [open] <span class='title'>Update Travis configuration so that it does not compile Rakudo every single time.</span></div> | |
| <div class='entry'><a href="issues.html#77"><span class='number'>77</span></a> [open] <span class='title'>What's up with hyper/race semantics?</span></div> | |
| <div class='entry'><a href="issues.html#73"><span class='number'>73</span></a> [open] <span class='title'>Should IO::Handle instances be possible to construct using file descriptors?</span></div> | |
| <div class='entry'><a href="issues.html#72"><span class='number'>72</span></a> [closed] <span class='title'>Ecosystem: versioning issues</span></div> | |
| <div class='entry'><a href="issues.html#76"><span class='number'>76</span></a> [open] <span class='title'>Make Rakudo read from META6 modules with :ver<>, :auth<> and :api<></span></div> | |
| <div class='entry'><a href="issues.html#75"><span class='number'>75</span></a> [open] <span class='title'>Mechanism for Reusing Function Definitions in NativeCall</span></div> | |
| <div class='entry'><a href="issues.html#90"><span class='number'>90</span></a> [open] <span class='title'>Support for custom HOWs isn't generic enough</span></div> | |
| <div class='entry'><a href="issues.html#74"><span class='number'>74</span></a> [closed] <span class='title'>One more approach for EXPORT problems.</span></div> | |
| <div class='entry'><a href="issues.html#88"><span class='number'>88</span></a> [open] <span class='title'>Language versioning.</span></div> | |
| <div class='entry'><a href="issues.html#81"><span class='number'>81</span></a> [closed] <span class='title'>"Perl" in the name "Perl 6" is confusing and irritating</span></div> | |
| <div class='entry'><a href="issues.html#86"><span class='number'>86</span></a> [closed] <span class='title'>pl6anet.org will be discontinued breaking "Recent Blog Posts" on perl6.org</span></div> | |
| <div class='entry'><a href="issues.html#71"><span class='number'>71</span></a> [closed] <span class='title'>No way of having new versions of CORE classes for new language revisions</span></div> | |
| <div class='entry'><a href="issues.html#69"><span class='number'>69</span></a> [open] <span class='title'>Status of the POD6 implementation</span></div> | |
| <div class='entry'><a href="issues.html#68"><span class='number'>68</span></a> [open] <span class='title'>[WIP] perl6-infra overview</span></div> | |
| <div class='entry'><a href="issues.html#70"><span class='number'>70</span></a> [open] <span class='title'>Official release of Raku implementation</span></div> | |
| <div class='entry'><a href="issues.html#67"><span class='number'>67</span></a> [closed] <span class='title'>[WIP] Detrapping</span></div> | |
| <div class='entry'><a href="issues.html#66"><span class='number'>66</span></a> [open] <span class='title'>Status of NativeCall is unclear</span></div> | |
| <div class='entry'><a href="issues.html#80"><span class='number'>80</span></a> [closed] <span class='title'>Core class version syntax</span></div> | |
| <div class='entry'><a href="issues.html#78"><span class='number'>78</span></a> [closed] <span class='title'>Documentation principles for making translation easier</span></div> | |
| <div class='entry'><a href="issues.html#65"><span class='number'>65</span></a> [closed] <span class='title'>Issue templates for every label</span></div> | |
| <div class='entry'><a href="issues.html#61"><span class='number'>61</span></a> [closed] <span class='title'>Samemark breaks regional indicator symbols, should it be this way?</span></div> | |
| <div class='entry'><a href="issues.html#57"><span class='number'>57</span></a> [open] <span class='title'>X::MyModule::Foo or MyModule::X::Foo ?</span></div> | |
| <div class='entry'><a href="issues.html#53"><span class='number'>53</span></a> [open] <span class='title'>Changelogging takes too much time and effort</span></div> | |
| <div class='entry'><a href="issues.html#64"><span class='number'>64</span></a> [closed] <span class='title'>[WIP] Decluttering</span></div> | |
| <div class='entry'><a href="issues.html#60"><span class='number'>60</span></a> [open] <span class='title'>Running some scripts without any input sometimes leads users to believe that the program is hanging</span></div> | |
| <div class='entry'><a href="issues.html#52"><span class='number'>52</span></a> [closed] <span class='title'>rakudo.party</span></div> | |
| <div class='entry'><a href="issues.html#63"><span class='number'>63</span></a> [open] <span class='title'>Should `without` allow chaining?</span></div> | |
| <div class='entry'><a href="issues.html#51"><span class='number'>51</span></a> [closed] <span class='title'>read-bits/read-ubits on Int as well?</span></div> | |
| <div class='entry'><a href="issues.html#50"><span class='number'>50</span></a> [closed] <span class='title'>Ambiguity in slicing with Ranges / WhateverCodes</span></div> | |
| <div class='entry'><a href="issues.html#59"><span class='number'>59</span></a> [open] <span class='title'>Need a substitute for Perl 5 die with newline for raising end-user errors?</span></div> | |
| <div class='entry'><a href="issues.html#62"><span class='number'>62</span></a> [open] <span class='title'>What can and what cannot be changed in 6.c-errata?</span></div> | |
| <div class='entry'><a href="issues.html#49"><span class='number'>49</span></a> [closed] <span class='title'>rt.perl.org is shutting down</span></div> | |
| <div class='entry'><a href="issues.html#58"><span class='number'>58</span></a> [open] <span class='title'>Ambiguity in pseudo-package and package reaction on missing symbols.</span></div> | |
| <div class='entry'><a href="issues.html#44"><span class='number'>44</span></a> [closed] <span class='title'>%0 and &0 should probably be syntax errors</span></div> | |
| <div class='entry'><a href="issues.html#43"><span class='number'>43</span></a> [closed] <span class='title'>require with non-sigiled arguments</span></div> | |
| <div class='entry'><a href="issues.html#56"><span class='number'>56</span></a> [open] <span class='title'>Clarifying dual-licensing on the site</span></div> | |
| <div class='entry'><a href="issues.html#41"><span class='number'>41</span></a> [open] <span class='title'>`once` block can be executed more than once</span></div> | |
| <div class='entry'><a href="issues.html#55"><span class='number'>55</span></a> [open] <span class='title'>LCM (support Rat and fail on lossy coercion)</span></div> | |
| <div class='entry'><a href="issues.html#54"><span class='number'>54</span></a> [open] <span class='title'>Release process changes</span></div> | |
| <div class='entry'><a href="issues.html#40"><span class='number'>40</span></a> [open] <span class='title'>Please beware of eliminating (or changing) documented features</span></div> | |
| <div class='entry'><a href="issues.html#39"><span class='number'>39</span></a> [closed] <span class='title'>Ecosystem content, quality and fragmentation issues.</span></div> | |
| <div class='entry'><a href="issues.html#35"><span class='number'>35</span></a> [closed] <span class='title'>Helper function on SetHashes</span></div> | |
| <div class='entry'><a href="issues.html#34"><span class='number'>34</span></a> [closed] <span class='title'>The status of PREVIEW modifier.</span></div> | |
| <div class='entry'><a href="issues.html#38"><span class='number'>38</span></a> [closed] <span class='title'>Maybe Any:D.await should return self?</span></div> | |
| <div class='entry'><a href="issues.html#33"><span class='number'>33</span></a> [open] <span class='title'>Push access to repositories in perl6 organization</span></div> | |
| <div class='entry'><a href="issues.html#37"><span class='number'>37</span></a> [open] <span class='title'>Editor modes for Raku</span></div> | |
| <div class='entry'><a href="issues.html#32"><span class='number'>32</span></a> [open] <span class='title'>perl6-infra: Host the Blin Toaster</span></div> | |
| <div class='entry'><a href="issues.html#36"><span class='number'>36</span></a> [open] <span class='title'>Removed Syntactic Feature (-i flag for in-place file editing)</span></div> | |
| <div class='entry'><a href="issues.html#47"><span class='number'>47</span></a> [closed] <span class='title'>Metaop semantics with QuantHashes</span></div> | |
| <div class='entry'><a href="issues.html#46"><span class='number'>46</span></a> [closed] <span class='title'>Moving tickets between rakudo and problem-solving repos is impossible</span></div> | |
| <div class='entry'><a href="issues.html#45"><span class='number'>45</span></a> [open] <span class='title'>Ecosystem issues and a corresponding dev</span></div> | |
| <div class='entry'><a href="issues.html#31"><span class='number'>31</span></a> [closed] <span class='title'>Language revision dependent spectests: change the approach.</span></div> | |
| <div class='entry'><a href="issues.html#27"><span class='number'>27</span></a> [closed] <span class='title'>What are the intended semantics of <== and <<==</span></div> | |
| <div class='entry'><a href="issues.html#22"><span class='number'>22</span></a> [closed] <span class='title'>Defining custom coercions from extant types</span></div> | |
| <div class='entry'><a href="issues.html#18"><span class='number'>18</span></a> [open] <span class='title'>take single letter CLI options with one leading hyphen, such as `-lwc`</span></div> | |
| <div class='entry'><a href="issues.html#21"><span class='number'>21</span></a> [open] <span class='title'>Semantics of coercion type on an "rw" parameter</span></div> | |
| <div class='entry'><a href="issues.html#17"><span class='number'>17</span></a> [closed] <span class='title'>`infrastructure` label and a corresponding subject-matter expert</span></div> | |
| <div class='entry'><a href="issues.html#20"><span class='number'>20</span></a> [closed] <span class='title'>How should Proc::Async.new, run and shell call cmd.exe?</span></div> | |
| <div class='entry'><a href="issues.html#26"><span class='number'>26</span></a> [closed] <span class='title'>Ecosystem: should we strive for integration with MetaCPAN</span></div> | |
| <div class='entry'><a href="issues.html#16"><span class='number'>16</span></a> [closed] <span class='title'>Create .Buf/.Blob coercers on Cool</span></div> | |
| <div class='entry'><a href="issues.html#30"><span class='number'>30</span></a> [open] <span class='title'>perl6-infra: service: Password handling</span></div> | |
| <div class='entry'><a href="issues.html#15"><span class='number'>15</span></a> [closed] <span class='title'>Test issue</span></div> | |
| <div class='entry'><a href="issues.html#29"><span class='number'>29</span></a> [open] <span class='title'>perl6-infra: group of services: DNS hosting</span></div> | |
| <div class='entry'><a href="issues.html#25"><span class='number'>25</span></a> [closed] <span class='title'>The label "infrastructure" is misspelled</span></div> | |
| <div class='entry'><a href="issues.html#28"><span class='number'>28</span></a> [open] <span class='title'>perl6-infra: rules and guidelines</span></div> | |
| <div class='entry'><a href="issues.html#14"><span class='number'>14</span></a> [closed] <span class='title'>Please add me to list of reviewers</span></div> | |
| <div class='entry'><a href="issues.html#24"><span class='number'>24</span></a> [open] <span class='title'>where blocks vs sub signatures</span></div> | |
| <div class='entry'><a href="issues.html#9"><span class='number'>9</span></a> [open] <span class='title'>Issues with security and reliability of our infrastructure</span></div> | |
| <div class='entry'><a href="issues.html#13"><span class='number'>13</span></a> [open] <span class='title'>Specify rounding mode in CORE</span></div> | |
| <div class='entry'><a href="issues.html#19"><span class='number'>19</span></a> [open] <span class='title'>Metadata licenses should be required before adding new modules to ecosystem</span></div> | |
| <div class='entry'><a href="issues.html#11"><span class='number'>11</span></a> [closed] <span class='title'>sprintf is a mess</span></div> | |
| <div class='entry'><a href="issues.html#10"><span class='number'>10</span></a> [open] <span class='title'>Inconsistent handling of too-large array index between match variables and regular arrays</span></div> | |
| <div class='entry'><a href="issues.html#5"><span class='number'>5</span></a> [open] <span class='title'>There's a huge PR/issue deficit in the Rakudo repo</span></div> | |
| <div class='entry'><a href="issues.html#8"><span class='number'>8</span></a> [closed] <span class='title'>.WHEN</span></div> | |
| <div class='entry'><a href="issues.html#7"><span class='number'>7</span></a> [closed] <span class='title'>Add tony-o to the list of reviewers</span></div> | |
| <div class='entry'><a href="issues.html#6"><span class='number'>6</span></a> [open] <span class='title'>New named parameters to .classify</span></div> | |
| <div class='entry'><a href="issues.html#4"><span class='number'>4</span></a> [open] <span class='title'>Some useful math/statistics functions are missing</span></div> | |
| <div class='entry'><a href="issues.html#3"><span class='number'>3</span></a> [closed] <span class='title'>Inconsistensy of container descriptor default value type for nominalizable types.</span></div> | |
| <div class='entry'><a href="issues.html#1"><span class='number'>1</span></a> [closed] <span class='title'>No formally defined process for working on problems</span></div> | |
| </div></body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| html { | |
| font-family: serif; | |
| font-size: 14pt; | |
| font-variant-ligatures: common-ligatures no-discretionary-ligatures no-historical-ligatures contextual; | |
| font-variant-numeric: oldstyle-nums; | |
| } | |
| body { | |
| margin-left: 3em; | |
| margin-right: 3em; | |
| } | |
| .issue > .body { | |
| margin-left: 2em; | |
| } | |
| .issue > .comment { | |
| margin-left: 2em; | |
| } | |
| .issue .header { | |
| font-size: 140%; | |
| background-color: #f0f0f0; | |
| } | |
| .issue > .comments { | |
| margin-left: 2em; | |
| } | |
| .issue .comment { | |
| padding-top: 1em; | |
| } | |
| .issue blockquote { | |
| border-left: .25em solid #a0a0a0; | |
| padding-left: 1em; | |
| } | |
This file has been truncated, but you can view the full file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <html><head><style>html { | |
| font-family: serif; | |
| font-size: 14pt; | |
| font-variant-ligatures: common-ligatures no-discretionary-ligatures no-historical-ligatures contextual; | |
| font-variant-numeric: oldstyle-nums; | |
| } | |
| body { | |
| margin-left: 3em; | |
| margin-right: 3em; | |
| } | |
| .issue > .body { | |
| margin-left: 2em; | |
| } | |
| .issue > .comment { | |
| margin-left: 2em; | |
| } | |
| .issue .header { | |
| font-size: 140%; | |
| background-color: #f0f0f0; | |
| } | |
| .issue > .comments { | |
| margin-left: 2em; | |
| } | |
| .issue .comment { | |
| padding-top: 1em; | |
| } | |
| .issue blockquote { | |
| border-left: .25em solid #a0a0a0; | |
| padding-left: 1em; | |
| } | |
| </style><link rel='stylesheet' href='issues.css'/></head><body><div class='issue' id="374"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/374"><span class='number'>374</span></a> - <span class='title'>Errors should not be adhoc in core</span></div> | |
| <div class='author'>[open]<span class='author'>@alabamenhu</span> opend this issue at <time datetime="2023-06-26T21:58:03Z">2023-06-26 21:58</time></div> | |
| </div> | |
| <div class='body'> | |
| <!--- Write a short description of the problem here. --> | |
| <p>Errors should not be <code>X::Adhoc</code> in core.</p> | |
| <!--- Provide more details here. *Do not* propose a solution. You can propose a solution later in the comments. --> | |
| <p>Adhoc errors only inform their issues via a message, which may not be easily parseable. As well, per the documentation</p> | |
| <blockquote> | |
| <p>Note that young code will often be prototyped using X::AdHoc and then later be revised to use more specific subtypes of Exception. As such it is usually best not to explicitly rely on receiving an X::AdHoc – in many cases using the string returned by the .message method, which all Exceptions must have, is preferable.</p> | |
| </blockquote> | |
| <p>However, this is complicated by the fact that the string returned by <code>.message</code> is also potentially unreliable, as LTA errors may be changed, improved, with data points in the message potentially being reorded, adjusted, etc.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5f3hOo"> | |
| <div class='header'> | |
| <span class='author'>@alabamenhu</span> commented at <time datetime="2023-06-26T22:11:24Z">2023-06-26 22:11</time> | |
| </div> | |
| <div class='body'> | |
| <p>This is fairly simple (if laborious) thing to do. The main issue is determining what error classes are needed so we're not creating a bunch of one-off errors when we could combine them. Additionally, the <code>Exception</code>s created (and extant ones) should be updated to ensure that, in contrast to the documentation, any actionable information is contained in attributes which the <code>message</code> function uses to convert into plain English. This will also make handling a potential internationalization of error messages much easier.</p> | |
| <p>(I posted this in problem-solving because it's sort of a partially Raku, partially Rakudo issue. I'm happy to go start working on a large PR updating all the <code>Exception</code>, but would want consensus on how to go about it first)</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f36Ax"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-27T00:02:21Z">2023-06-27 00:02</time> | |
| </div> | |
| <div class='body'> | |
| <p>I agree that it's both Raku and Rakudo issue at the same time. Changed the categorization of this problem accordingly.</p> | |
| <p>Solving this problem would involve not only updating Rakudo sources but adding tests to the roast. This is what's on the surface.</p> | |
| <p>Deeper goes the task of collecting the errors thrown using <code>nqp::die</code> throughout the sources of Rakudo and categorizing them.</p> | |
| <p>Another task is to see what could be done about the errors coming from NQP and, worse even, from VMs. These are adhocs by definition as currently there is no mechanism of mapping them into HLL classes.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f4u_E"> | |
| <div class='header'> | |
| <span class='author'>@alabamenhu</span> commented at <time datetime="2023-06-27T03:22:29Z">2023-06-27 03:22</time> | |
| </div> | |
| <div class='body'> | |
| <p>Per something I noted in IRC, I think in updating the <code>Exception</code> base class, we should do something akin to</p> | |
| <pre><code>class Exception { | |
| method message { self.MESSAGE } | |
| method MESSAGE is implementation-detail { 'Exception of type ' ~ self.WHAT.^name } | |
| } | |
| </code></pre> | |
| <p>Each exception class would generate its message based on <code>MESSAGE</code> (name for an example only). This would enable an internationalization module to do <code>INIT Exception.^find_method('message').wrap()</code> and not need to wrap the dozens of exception classes' methods which is not performant.</p> | |
| <p>At the same time, in reworking them, I'd make a rule that all pertinent information goes in an attribution that makes logical sense to be used in a <code>grep</code>/<code>when</code> area. The message just joins them into a human readable version. A mostly good example of this is <code>X::Method::NotFound</code>, where the message <em>No such method 'foo' for invocant of type 'Bar'</em> is derived from the attributes <code>method</code> (=<em>foo</em>), <code>typename</code> (=<em>Bar</em>), and <code>private</code> (=<em>false</em>). It does however have a new one <code>addendum</code> that is basically an adhoc and could warrant some review in an <code>Exception</code> rework.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f_PCP"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-28T00:41:54Z">2023-06-28 00:41</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>This would enable an internationalization module to do <code>INIT Exception.^find_method('message').wrap()</code></p> | |
| </blockquote> | |
| <p>I already dislike it:</p> | |
| <ol> | |
| <li><code>wrap</code> is a hack</li> | |
| <li>one would have to do it for nearly every exception class with <code>message</code> and would have to follow any changes in the core</li> | |
| <li>it would be necessary to know the internal implementation of complex <code>message</code> methods where a bunch of other methods are involved – as in your example with <code>X::Method::NoFound</code></li> | |
| </ol> | |
| <p>Besides, what worries me is that composite messages may require different order of their parts in other languages.</p> | |
| <p>I think internationalization must be done in a totally different way at Raku core level.</p> | |
| <p>First of all, there must be some pluggable mechanism where forming of complex messages can be offloaded to external modules. For example, the core could provide defaults via <code>X::L10N::<LN></code> modules, where <code><LN></code> is a language code.</p> | |
| <p>Second, there must be a way of obtaining atomic translations for standard strings and it must work at VM level. At the Raku level it would then make sense to use <code>printf</code> instead of string concatenations to allow language-specific word ordering.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5gCJsr"> | |
| <div class='header'> | |
| <span class='author'>@alabamenhu</span> commented at <time datetime="2023-06-28T10:43:47Z">2023-06-28 10:43</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <blockquote> | |
| <p>This would enable an internationalization module to do <code>INIT Exception.^find_method('message').wrap()</code></p> | |
| </blockquote> | |
| <p>I already dislike it:</p> | |
| <pre><code>1. `wrap` is a hack | |
| 2. one would have to do it for nearly every exception class with `message` and would have to follow any changes in the core | |
| 3. it would be necessary to know the internal implementation of complex `message` methods where a bunch of other methods are involved – as in your example with `X::Method::NoFound` | |
| </code></pre> | |
| <p>Besides, what worries me is that composite messages may require different order of their parts in other languages.</p> | |
| <p>I think internationalization must be done in a totally different way at Raku core level.</p> | |
| <p>First of all, there must be some pluggable mechanism where forming of complex messages can be offloaded to external modules. For example, the core could provide defaults via <code>X::L10N::<LN></code> modules, where <code><LN></code> is a language code.</p> | |
| <p>Second, there must be a way of obtaining atomic translations for standard strings and it must work at VM level. At the Raku level it would then make sense to use <code>printf</code> instead of string concatenations to allow language-specific word ordering.</p> | |
| </blockquote> | |
| <p>I just wonder if internationalized error messages should be something core handles. The idea of having a single <code>message</code> that farms out to individual <code>MESSAGE</code>s means only one wrap needs to be handled and has minimal extra overhead but a much easier implementation, but also pretty much says empatically "I'm not a part of core". If stuff is farmed out to a module, then complex messages can be handle pretty easily — frameworks are far more advanced today than the old <code>.po/.mo</code> standard. Do we consider the <code>Pod::To::</code> mechanism to be a part of Raku or Rakudo? I think that's a good model to follow. But that's probably a different problem solving issue (although certainly related — discussion of it sparked this issue).</p> | |
| <p>That said, the idea of including each piece of information (method, type, etc for <code>X::Method::NotFound</code>) would make rewriting complex messages much easier for such things. But the primary goal would be to allow better handling of errors. It's much easier to use <code>if .method eq 'foo'</code> or <code>if .type eq 'Bar'</code> on <code>X::Method::NotFound</code> than having to tease out that information based on the contents of <code>.message</code>. (I use <code>X::Method::NotFound</code> here as it's a good example of how to do things, but also of where work needs to be done — the <code>addendum</code>). If that's figure out, I think a lot more can be enabled.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5gMA-D"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-29T20:21:38Z">2023-06-29 20:21</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>I just wonder if internationalized error messages should be something core handles.</p> | |
| </blockquote> | |
| <p>I think it should. It's not ought to do it all itself, but providing a pluggable API would be very beneficial.</p> | |
| <p>Besides, having the API would also allow third party code to use it for their needs too.</p> | |
| <p>And don't forget about VM where having a way of providing localized messages is needed too.</p> | |
| <blockquote> | |
| <p>means only one wrap needs to be handled</p> | |
| </blockquote> | |
| <p>Any <code>wrap</code> is rather a hack. It is OK and sometimes even really useful when it comes to well isolated, controllable cases. But when it is supposed to affect the entire ecosystem of a program it is barely acceptable.</p> | |
| <blockquote> | |
| <p>but also pretty much says empatically "I'm not a part of core".</p> | |
| </blockquote> | |
| <p>Does it really matter? Say, my typical <code>$LANG</code> is en_US.UTF-8, but if I set it to, say, uk_UA.UTF-8 and there would be no core support for it then installing something like <code>X::L10N::UA</code> (though, perhaps, more sensible name would be <code>uk_UA</code>) from the ecosystem makes it no less clear that it is not a core thing. But why should anybody care? As long as it doesn't break one's code. Either core or installed L10N modules would be auto-loaded by the core based on the locale making the process transparent to a user.</p> | |
| <blockquote> | |
| <p>frameworks are far more advanced today than the old <code>.po/.mo</code> standard.</p> | |
| </blockquote> | |
| <p>I don't propose the exact replica of .po/.mo. Pluggability can mean that roles or classes in a L10N module may override methods of the original exceptions. In a way this is a cleaner replacement for <code>wrap</code>.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="373"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/373"><span class='number'>373</span></a> - <span class='title'>Rakudoc in third-party modules and some related topics</span></div> | |
| <div class='author'>[open]<span class='author'>@vrurg</span> opend this issue at <time datetime="2023-06-21T01:02:36Z">2023-06-21 01:02</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>This is a meta-issue as it is about to cover a few topics I stumbled upon while writing docs for my last module. Perhaps it would make sense to spawn more specialized issues later, but for now it feels to me like having more sense in providing general overview of the situation.</p> | |
| <p>It is also to be noted that I've got an answer to at least one of my question, but it was part of an undocumented conversation. Therefore it'd be included here as well. Other answers could be lurking out there too, but they're not known to me.</p> | |
| <p>I would try to structure this from the perspective of a module developer, possibly not very experienced with documenting in Raku.</p> | |
| <h3>Where To Start?</h3> | |
| <p>Turns out we don't have a manual on how to write manuals. Something I'd rather expect to be part of module development section in the Raku documentation, or be linked to from the section. What I would like to see there is:</p> | |
| <ol> | |
| <li>Where to start in general, including such topics as recommended sections and styling in general</li> | |
| <li>How to organize the docs from distribution perspective: file locations, pros and cons of using dedicated .rakudoc, or inlining into .rakumod, etc.</li> | |
| <li>What tools to use.</li> | |
| </ol> | |
| <p>I'd say this all is better be a single piece since, as a rule, writing docs is the final stage of project development.</p> | |
| <h3>Docs In An Installed Distribution</h3> | |
| <p>Giving further development to the item 2 from from above, there are cases when having documentation inlined into a .rakumod is not considered a good idea. My own latest example is <code>LibXML::Class::Manual</code> which is not a module and better not be. Other cases may include documenting classes which are declared within a module but one wants them to be available for a documentation reading tool by their full names:</p> | |
| <pre><code class="language-raku">unit module Foo; | |
| class Bar {...} | |
| </code></pre> | |
| <p>And then:</p> | |
| <pre><code>$ rakudoc Foo::Bar | |
| </code></pre> | |
| <p>Our current Raku documentation states that .rakudoc are to be placed under <em>doc/</em> directory of distribution source tree. But the directory is never included into precompiled installation. Thus, <code>zef install Foo</code> and then wiping zef's cache would leave one with no access to these docs whatsoever.</p> | |
| <p>Though, for the clarity, even having the cache preserved is of little help because one has to know where is it located before using it. Moreover, if they don't know about the cache existence then it's not much different from not having it in first place.</p> | |
| <h3>The Reading Tool</h3> | |
| <p>For those coming from Perl background, having <code>rakudoc</code> is quite natural expectation. To be frank, I don't know what is the situation with documentation readers in other languages, but having one should be considered an advantage. From this point of view I tend to consider having the <code>rakudoc</code> as the standard.</p> | |
| <p>Either way, there is no alternative to it presently. But in its current form it is barely useful too.</p> | |
| <p>First of all, it requires a document to follow its demands with regard to the structure and it is very rigid in these demands. In particular, it has to be <code>=TITLE</code>, not <code>=head TITLE</code>, not <code>=head1 TITLE</code>. But then again, why <code>=TITLE</code> and <code>=SUBTITLE</code>, after all? My own preference is man-styled docs with <code>=NAME</code>, <code>=SYNOPSIS</code>, <code>=DESCRIPTION</code>, etc. In large due to keeping in mind that this how they should be used too.</p> | |
| <p>The other requirement is to have <code>:kind</code>, <code>:subkind</code>, and <code>:category</code> keys on <code>=begin pod</code> – but what are they? What for? Seems like this is something apparent to The Raku Documentation project participants, but they are an undocumented mystery to me.</p> | |
| <p>It is understandable that since <code>rakudoc</code> is not part of Rakudo and, apparently and definitely, of the Raku language, I cannot impose any requirements on it. But without an alternative implementing more democratic rules I'd have these question open. It is irrelevant to me wether they'd be answered by <code>rakudoc</code> or somebody picks up the task and implements a "competitor".</p> | |
| <p>And then, once again, access to .rakudoc in precompiled distros...</p> | |
| <h3>Tooling?</h3> | |
| <p>Having some kind of standard tool or tools to deal with documentation, starting from verifying it and all the way down to producing output formats and even publishing them – it's a dream. Let it be here, just in case...</p> | |
| <p>BTW, with RakuAST implementing this part would become more feasible.</p> | |
| <h3>TOC?</h3> | |
| <p>I'm not even certain as to what to ask about here. Some documents (the above mentioned manual, in particular) tend to grow big. Having TOC would help a lot in navigating them. Even if it's not clickable since having a document overview already eases search for necessary information.</p> | |
| <p>Some docs are so tiny that TOC in them would be an overkill.</p> | |
| <p>Having TOC as a part of Rakudoc standard seems to be an advantage. Making it available for opt-in/opt-out would be great too.</p> | |
| <h3>Rakudoc Cross-linking</h3> | |
| <p><code>L<></code> tag is giving more questions than answers. The first and the biggest problem is when it comes down to multi-format output (HTML, Markdown, etc.) where there could not only be different file extensions but even different directory structure – if there is any directories at all like when everything is thrown into a single PDF, for example. There is a real-life case of https://raku.land where links in READMEs are very fragile and often just do not work.</p> | |
| <p>What aspects of linking we can take as axioms?</p> | |
| <ul> | |
| <li>anchors (explicit or implicit)</li> | |
| <li>inter-document</li> | |
| <li>cross-document</li> | |
| <li>the already mentioned multi-format output with different file extensions and URI schemas</li> | |
| </ul> | |
| <p>A typical question of linking would look like: in a doc for module <code>Foo::Bar::Baz</code> I need to link to a paragraph in <code>Foo::Fubar</code> documentation so, that it would work in a local HTML; on a web page; on a version control service provider like GitHub, GitLab, whatever else is one's choice; etc.</p> | |
| <p>Perhaps this question doesn't have a comprehensive answer, but at the moment there is barely anything reliable but WWW URLs. Not even relative paths are sufficiently good for the task.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5fXS8N"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-21T01:38:30Z">2023-06-21 01:38</time> | |
| </div> | |
| <div class='body'> | |
| <p>My own two cents.</p> | |
| <p>First, about TOC. Best is to have <code>=toc</code> so one can chose where exactly they want to see it. This is best in cases when a kind of preface is required.</p> | |
| <p>Speaking of links, @finanalyst has mentioned during our last RSC meeting that we can introduce, say <code>:id</code> configuration key, making it possible to create reliable links. The problem in general for now is when we have, say <code>=head My Ideas</code> there is no way to link to it in a way that when it gets renamed to <code>=head Our Ideas</code> the old <code>L<></code> tags would still point out to the section.</p> | |
| <p>Another matter to cover is that limiting links with only certain kinds of Rakudoc elements (like headings) make it harder for both the writer and the reader: <em>"See section L<Our Ideas>, where you would find a list with an item of interest."</em> Nah!</p> | |
| <pre><code>Look at the method L<foo|#method-foo> down below. | |
| ... | |
| =begin item :id<method-foo> | |
| B<C<method foo(...)>> | |
| Hope you found what you're looking for here! | |
| =end item | |
| </code></pre> | |
| <p>Having <code>:id</code> available for any (or almost any) kind of Rakudoc block would be very beneficial for docs readability.</p> | |
| <p>Another point is cross-module/-document linking. Speaking of the <code>Foo::Bar::Baz</code> -> <code>Foo::Fubar</code> example, best if one can simply use <code>L<Foo::Fubar|#some-id></code> and the rest would be taken care of by the tools. Moreover, I'd make the pipe <code>|</code> optional and have it just as `L<a href="Foo::Fubar#some-id">Foo::Fubar#some-id</a> in this particular case. Others would still require the separator.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fXT0a"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-21T01:44:37Z">2023-06-21 01:44</time> | |
| </div> | |
| <div class='body'> | |
| <p>Having to always define <code>:id</code> for any potential anchor is too much. Therefore some rules of implicit anchor naming must be defined. But they have to be clear and standard for any output format. Whatever is eventually generated in the output, anchor name in Rakudoc would only depend on what Rakudoc itself states. So, one would know that <code>=head Our Ideas</code> can be referenced as <code>#our-ideas</code> at any time.</p> | |
| <p>It feels to me that these rules are to be coded in RakuAST parser. Tools would simply pick up what they're offered with. This should also simplify producing links for something like <code>L<Our Ideas></code> as the corresponding object would already have the target anchor name in it.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fdzFX"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-21T20:43:47Z">2023-06-21 20:43</time> | |
| </div> | |
| <div class='body'> | |
| <p>I gave a 10 min presentation to the Core summit about changes needed in Rakudoc. | |
| As a result of the 3hours of discussion, I have rewritten the Rakudoc document / specification, making it backwards compatible, but also explaining a lot more about certain features of Rakudoc (aka POD6), such as metadata, the difference between code-oriented Rakudoc and page-oriented Rakudoc, directives vs blocks, etc.</p> | |
| <p>A first draft of the Rakudoc document is currently being reviewed by @lizmat As soon as she is through, it will be sent for a BETA review to people who have been implementing Rakudoc in various ways. After the BETA review and incorporating changes, the document will be placed somewhere (as a Raku/Doc PR) for a wider community review. Also I will release a series of blogs about the changes to explain the rationale behind them.</p> | |
| <p>As to the requests above (this is not an exhaustive list of the revisions):</p> | |
| <ul> | |
| <li>An original unimplemented specification in S26 (the speculation about POD6) was <code>P<:toc></code> which would place a TOC where the author wanted. This will be a part of the revised Rakudoc. | |
| <ul> | |
| <li>There is a problem in that for a large project like Raku documentation the designer will want to place the ToC in a standard place, such as a sidebar.</li> | |
| </ul> | |
| </li> | |
| <li>The idea of an <code>:id<some-custom-anchor></code> will be in the Rakudoc revision, and will be applied to all blocks. | |
| <ul> | |
| <li>It is for the author to guarantee that the id is unique, a conflict is resolved by the browser or renderer.</li> | |
| <li>If a <code>=head</code> block exists, then it automatically generates an anchor (as mentioned above), which is guaranteed to be unique. However, a custom <code>:id</code> will also generate an anchor at the same place. This way a document author can create an easy to remember anchor for their own documents.</li> | |
| <li>The ability to add custom <strong>metadata</strong> already exists by using the <code>=for</code> directive. So if a <code>=head1 This is a header</code> exists and the id needs to be customised, then the new code will be:</li> | |
| </ul> | |
| </li> | |
| </ul> | |
| <pre><code>=for head1 :to<easy_anchor> | |
| This is a header | |
| </code></pre> | |
| <p>A compliant renderer will be expected to generate both the <code>this_is_a_header</code> and the <code>easy_anchor</code> anchors.</p> | |
| <ul> | |
| <li>The need for a way to link by Module was noted at the Core summit with a new schema for <code>L<></code> and <code>P<></code> markup, namely <code>mod://Some::Module</code>. The syntax will be included in the Rakudoc revision, but the semantics have yet to be fully nailed down. It will link to the rakuland site though.</li> | |
| <li>About the <code>:kind</code> <code>:subkind</code> metadata in Raku documentation files, this is a poorly documented feature of POD6. This data is used by the Renderer of the Raku documentation to compile cross document indexes and secondary files. Only some metadata is specified by the new Rakudoc revision, and if it is not in the specification, then it is ignored, unless a customised renderer is used.</li> | |
| <li>About how to create documentation, and ways to view any module's documentation, this is indeed a need. There is a part of the META6 specification that includes a 'doc' directory, but this not used or recognised yet.</li> | |
| </ul> | |
| <p>In addition, the move to RakuAST will change Rakudoc considerably. It will no longer need to be accessed via the $=pod mechanism, but will be primarily found using an <code>.AST</code> call on a file.</p> | |
| <p>Hopes this explains some of the progress that is on its way.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ffhhg"> | |
| <div class='header'> | |
| <span class='author'>@patrickbkr</span> commented at <time datetime="2023-06-22T06:49:47Z">2023-06-22 06:49</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <ul> | |
| <li>The need for a way to link by Module was noted at the Core summit with a new schema for <code>L<></code> and <code>P<></code> markup, namely <code>mod://Some::Module</code>. The syntax will be included in the Rakudoc revision, but the semantics have yet to be fully nailed down. It will link to the rakuland site though.</li> | |
| </ul> | |
| </blockquote> | |
| <p>The specification shouldn't dictate, which platform module links are resolved to. Once raku.land has gained Rakudoc support it makes sense for docs.raku.org to link to raku.land (as that's currently the dominant platform). But other documentation providers should be free to link somewhere else. E.g. a command line documentation reader should try to resolve and display module links itself.</p> | |
| <p>@finanalyst I guess this is what you meant. But I wanted to be sure.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fgU8y"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-22T09:25:59Z">2023-06-22 09:25</time> | |
| </div> | |
| <div class='body'> | |
| <p>@patrickbkr yes, you're right about retaining a generic interface, but what I meant about 'the semantics have yet to be fully nailed down' is to work out how to do this. The reference to rakuland is more about an initial default. | |
| Because Rakudoc must be customisable, every renderer will have to be configurable in some way. I don't want to define how a renderer should be configured. | |
| However, by defining the behaviours of some blocks, say the way numbering works with <code>=head</code> and <code>=item</code>, Rakudoc is being specific about defaults, allowing Renderer developers to provide other behaviours. The <code>=config</code> directive to change behaviours. | |
| oO ( maybe we need to have a metadata option like :mod-prefix that by default is set to eg rakuland, then if a document writer wants a different behaviour, they could put</p> | |
| <pre><code>=config Markup-L mod-prefix 'https://another-site.eg/dist?' | |
| </code></pre> | |
| <p>) end of speculation | |
| Would this suit?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fgquZ"> | |
| <div class='header'> | |
| <span class='author'>@patrickbkr</span> commented at <time datetime="2023-06-22T10:28:04Z">2023-06-22 10:28</time> | |
| </div> | |
| <div class='body'> | |
| <p>I think documentation software will fall in one of several categories:</p> | |
| <ul> | |
| <li>Software to display the official Raku documentation which may contain links to ecosystem modules -> hard code raku.land or let the user decide via some configuration on the website</li> | |
| <li>Generic ecosystem module documentation viewers (raku.land, the rakudoc CLI tool) -> They should open links in their own interface.</li> | |
| <li>Software to create or display documentation potentially unrelated to Raku. (podlite?) -> Won't have module links.</li> | |
| <li>A company may have internal Raku code and documentation which they view in a private installation of e.g. raku.land. -> Configure that installation to resolve links to that private installation itself.</li> | |
| </ul> | |
| <p>Following the above categories I see two cases:</p> | |
| <ul> | |
| <li>the reader wants to change where such links go to (i.e. by setting some option in the viewer program / website)</li> | |
| <li>the software presenting the documentation decides</li> | |
| </ul> | |
| <p>@finanalyst Can you come up with an example where it would make sense for the mod-prefix to be specified in the documentation itself?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fiMMW"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-22T15:01:10Z">2023-06-22 15:01</time> | |
| </div> | |
| <div class='body'> | |
| <p>I don't think there must be any suggestion/defaults on the Rakudoc side as to where module links must point at. Neither implicit, by the standard; nor explicit by document creator. In the latter case there is always an option of inserting the link manually, as a URL, since it's about to be rigidly hardcoded anyway.</p> | |
| <p>This has to be 100% on the reader side.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fiUYu"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-22T15:21:00Z">2023-06-22 15:21</time> | |
| </div> | |
| <div class='body'> | |
| <p>@vrurg I'm having difficulties reconciling your two comments:</p> | |
| <blockquote> | |
| <p>best if one can simply use L<a href="Foo::Fubar%7C#some-id">Foo::Fubar|#some-id</a> and the rest would be taken care of by the tools. Moreover, I'd make the pipe | optional and have it just as `LFoo::Fubar#some-id in this particular case</p> | |
| </blockquote> | |
| <p>and recently</p> | |
| <blockquote> | |
| <p>don't think there must be any suggestion/defaults on the Rakudoc side as to where module links must point at. Neither implicit, by the standard; nor explicit by document creator. In the latter case there is always an option of inserting the link manually, as a URL, since it's about to be rigidly hardcoded anyway.</p> | |
| </blockquote> | |
| <p>The original desire seemed to be that in some documentation an author could say eg</p> | |
| <pre><code>This to-json method is similar to the L<to-json method in JSON::Fast|mod://JSON::Fast#to-json> | |
| </code></pre> | |
| <p>The renderer would have default mechanism to find <code>JSON::Fast</code> and point at the documentation.</p> | |
| <p>Personally I don't like the suggestion purely because it leaves too much to the tooling, but I could see it would be useful.</p> | |
| <p>But if such a functionality is wanted, how should a Renderer operate to become compliant?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fibXH"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-22T15:37:29Z">2023-06-22 15:37</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>The renderer would have default mechanism to find <code>JSON::Fast</code> and point at the documentation.</p> | |
| </blockquote> | |
| <p>I have combined the "renderer" and actual person-reader into a single term "reader". The point is that there is language side (the Rakudoc standard), the writer side (module/document author), and the "reader" side. Or, the other way around, "reader" is the one who reads Rakudoc sources.</p> | |
| <p>Not the best definitions, but OK for the purpose of defining where the final link is produced.</p> | |
| <blockquote> | |
| <p>Personally I don't like the suggestion purely because it leaves too much to the tooling, but I could see it would be useful.</p> | |
| </blockquote> | |
| <p>Dynamic or semi-dynamic things like URLs are better be left off to the tools. As much as we should do is to provide <em>recommendations</em>, but nothing more. Patrick has provided very good examples as to when the final URL can differ from our understanding of it. My other point would be that changing a standard is not a particularly fast paced process. Not to mention the need for the tools to update afterwards. But in case of a disastrous disappearance of the site, hardcoded in the standard, we better let tool developers to react as quick as they can.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fiqYK"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-22T16:00:31Z">2023-06-22 16:00</time> | |
| </div> | |
| <div class='body'> | |
| <p>The three terms are needed:</p> | |
| <ul> | |
| <li>reader - a human reading documentation about a module or functionality. The reader will want to use a method that is most convenient. There are three current useful methods: | |
| <ul> | |
| <li>HTML rendered pages (such as the Raku documentation suite), but also in pages rendered by Podlite.</li> | |
| <li>MarkDown rendered pages, eg. REAME.md</li> | |
| <li>An IDE, such as Comma</li> | |
| </ul> | |
| </li> | |
| <li>developer / document author - a human writing software or describing how to use software, which the reader will want to use. The writer uses Rakudoc, which is neutral about the output format.</li> | |
| <li>renderer - the software tool that converts Rakudoc instructions into a form useful to the reader. The renderer for the Raku documentation site is now <code>Raku::Pod::Render</code>.</li> | |
| </ul> | |
| <p>So the suggestion is to include in the standard for the minimum Rakudoc the schema for <code>L<></code> markup called <code>mod://</code>, in addition to the very common <code>https://</code>| <code>http://</code>. The aim is for <code>mod://</code> to be followed by the name of a Raku module.</p> | |
| <p>That part seems easy. The question is how to specify what a Rakudoc B<Renderer> should do when implementing that link? There may be multiple renderers (I am already planning a new renderer to work directly on RakuAST because <code>Raku::Pod::Render</code> works using <code>$=pod</code>).</p> | |
| <p>It seems to me that a default behaviour should be indicated in the Rakudoc documentation. This default can be changed in the future.</p> | |
| <p>However, this default can be changed / customised.</p> | |
| <p>I am <strong>ABSOLUTELY</strong> against hard-coded solutions. I wrote <code>Raku::Pod::Render</code> because <code>Pod::To::HTML</code> hard coded everything. The bits that are now put into Mustache templates were my first PRs to <code>Pod::To::HTML</code>.</p> | |
| <p>What I am trying to say is that even if there is maximum flexibility, there should be some reasonable defaults so that the first use of a Render can be as easy as possible for a new user.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ftQRO"> | |
| <div class='header'> | |
| <span class='author'>@ugexe</span> commented at <time datetime="2023-06-24T19:21:15Z">2023-06-24 19:21</time> | |
| </div> | |
| <div class='body'> | |
| <p>Something to consider when trying to create a URI scheme for this is that users should be able to link to a specific version like <code>mod://JSON::Fast:ver<42>#to-json</code>. The <code><</code> and <code>></code> would make it annoying to embed in <code>L<></code>.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ftRUS"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-24T19:43:34Z">2023-06-24 19:43</time> | |
| </div> | |
| <div class='body'> | |
| <p>That has a solution, one can use <code>L<<>></code> or <code>L«»</code>, unless you're referring to something else.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ftRXh"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-24T19:44:33Z">2023-06-24 19:44</time> | |
| </div> | |
| <div class='body'> | |
| <p>@ugexe the Rakudo grammar is actually good at handling this sort of bracing. | |
| For instance <code>C< L<> ></code> passes <code>L<></code> to the handler for C.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ftSz8"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-24T19:57:56Z">2023-06-24 19:57</time> | |
| </div> | |
| <div class='body'> | |
| <p>As long as the delimiters are balanced it'll work, unless the <code><></code> part is in the URL section(I don't know if that's a bug):</p> | |
| <pre><code class="language-raku">=begin pod | |
| L<mod://JSON::Fast:ver<42>#to-json> | |
| # Pod::FormattingCode.new(type => "L", meta => [], config => {}, contents => ["mod://JSON::Fast:ver<42>#to-json"]) | |
| L<test|mod://JSON::Fast:ver<42>#to-json> | |
| # Pod::FormattingCode.new(type => "L", meta => ["mod://JSON::Fast:ver<42"], config => {}, contents => ["test"]) | |
| L<<test|mod://JSON::Fast:ver<42>#to-json>> | |
| # Pod::FormattingCode.new(type => "L", meta => ["mod://JSON::Fast:ver<42>#to-json"], config => {}, contents => ["test"]) | |
| L«test|mod://JSON::Fast:ver<42>#to-json» | |
| # Pod::FormattingCode.new(type => "L", meta => ["mod://JSON::Fast:ver<42>#to-json"], config => {}, contents => ["test"]) | |
| =end pod | |
| </code></pre> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ftUPu"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-24T20:19:13Z">2023-06-24 20:19</time> | |
| </div> | |
| <div class='body'> | |
| <p>@CIAvash Good catch. I would say the second case is a bug. | |
| Have you tried this with RakuAST?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ftV9W"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-24T20:33:25Z">2023-06-24 20:33</time> | |
| </div> | |
| <div class='body'> | |
| <p>@finanalyst no, not sure how to do that. I'm still on Rakudo 2023.04. That doesn't support RakuDoc, does it?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ftXCb"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-24T20:52:21Z">2023-06-24 20:52</time> | |
| </div> | |
| <div class='body'> | |
| <p>@CIAvash RakuAST for RakuDoc is very bleeding edge. | |
| Using your tests in a file called ttt.rakudoc, I get.</p> | |
| <pre><code>$ RAKUDO_RAKUAST=1 raku -e "'ttt.rakudoc'.IO.slurp.AST.say" | |
| RakuAST::StatementList.new( | |
| RakuAST::Doc::Block.new( | |
| type => "pod", | |
| paragraphs => ( | |
| RakuAST::Doc::Paragraph.new( | |
| RakuAST::Doc::Markup.new( | |
| letter => "L", | |
| opener => "<", | |
| closer => ">", | |
| atoms => ( | |
| "mod://JSON::Fast:ver", | |
| RakuAST::Doc::Markup.new( | |
| letter => "", | |
| opener => "<", | |
| closer => ">", | |
| atoms => ( | |
| "42", | |
| ) | |
| ), | |
| "#to-json", | |
| ) | |
| ), | |
| "\n\n" | |
| ), | |
| RakuAST::Doc::Paragraph.new( | |
| RakuAST::Doc::Markup.new( | |
| letter => "L", | |
| opener => "<", | |
| closer => ">", | |
| atoms => ( | |
| "test|mod://JSON::Fast:ver", | |
| RakuAST::Doc::Markup.new( | |
| letter => "", | |
| opener => "<", | |
| closer => ">", | |
| atoms => ( | |
| "42", | |
| ) | |
| ), | |
| "#to-json", | |
| ) | |
| ), | |
| "\n\n" | |
| ), | |
| RakuAST::Doc::Paragraph.new( | |
| RakuAST::Doc::Markup.new( | |
| letter => "L", | |
| opener => "<<", | |
| closer => ">>", | |
| atoms => ( | |
| "test", | |
| ), | |
| meta => ( | |
| "mod://JSON::Fast:ver<42>#to-json", | |
| ) | |
| ), | |
| "\n\n" | |
| ), | |
| RakuAST::Doc::Paragraph.new( | |
| RakuAST::Doc::Markup.new( | |
| letter => "L", | |
| opener => "«", | |
| closer => "»", | |
| atoms => ( | |
| "test", | |
| ), | |
| meta => ( | |
| "mod://JSON::Fast:ver<42>#to-json", | |
| ) | |
| ), | |
| "\n\n" | |
| ), | |
| ) | |
| ) | |
| ) | |
| </code></pre> | |
| <p>So @ugexe was correct: the inner <code><></code> causes problems.</p> | |
| <p>The interesting thing is that both of the first two cases in your example are wrong, the first one subtly. Rakudo is parsing the <code><></code> after the <code>ver</code> as a FormatCode with letter ''.</p> | |
| <p>Using <code><< >></code> as the bracketing pair yields the correct form (the url should be in the <code>meta</code> attribute.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ft9nv"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-25T05:50:30Z">2023-06-25 05:50</time> | |
| </div> | |
| <div class='body'> | |
| <p>@finanalyst hmm, don't know if that's a bug or not, but using multiple angle brackets or <code>«»</code> is safer for sure.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fuOC3"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-25T08:53:39Z">2023-06-25 08:53</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>So @ugexe was correct: the inner <> causes problems.</p> | |
| </blockquote> | |
| <p>It indeed causes issues in the legacy $=pod generation. Am looking into this.</p> | |
| <blockquote> | |
| <p>The interesting thing is that both of the first two cases in your example are wrong, the first one subtly. Rakudo is parsing the <> after the ver as a FormatCode with letter ''.</p> | |
| </blockquote> | |
| <p>The rules according to S26 are that <em>if</em> you use the same delimiter inside a markup as the "outer" markup, they <em>must</em> balance. The easiest way to implement this, was to handle the as "letterless" markup codes. A "letterless" markup code can always just be stringified. One could argue the parser should do that for you, but I'm a little in two minds about that, as it would remove potentially valuable information.</p> | |
| <blockquote> | |
| <p>Using << >> as the bracketing pair yields the correct form (the url should be in the meta attribute.</p> | |
| </blockquote> | |
| <p>Different delimiters mean that you can have unbalanced as well, as they are completely ignored in markup parsing.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fuZ0X"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-25T10:01:15Z">2023-06-25 10:01</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>A "letterless" markup code can always just be stringified. One could argue the parser should do that for you, but I'm a little in two minds about that, as it would remove potentially valuable information.</p> | |
| </blockquote> | |
| <p>If the parser doesn't stringify, then a RakuAST-oriented renderer needs to look for letterless MC. Then this needs to be documented. It could be useful if a renderer is looking to do something with <code>:var<></code>, <code>:auth<></code> or <code>:api<></code>. That seems a long way ahead.</p> | |
| <blockquote> | |
| <p>Different delimiters mean that you can have unbalanced as well, as they are completely ignored in markup parsing.</p> | |
| </blockquote> | |
| <p>But that would allow unbalanced delimiters. A note in documentation would indicate that if different delimiters are used, the parser will not pick up an imbalance.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fual7"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-25T10:08:15Z">2023-06-25 10:08</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>But that would allow unbalanced delimiters. A note in documentation would indicate that if different delimiters are used, the parser will not pick up an imbalance.</p> | |
| </blockquote> | |
| <p>Sometimes you need to allow for unbalanced delimiters. <code>C« < »</code> comes to mind.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fucgD"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-25T10:18:13Z">2023-06-25 10:18</time> | |
| </div> | |
| <div class='body'> | |
| <p>https://github.com/rakudo/rakudo/commit/e66bcd670c fixes the <code>L<test|mod://JSON::Fast:ver<42>#to-json></code> case.</p> | |
| <pre><code class="language-raku">RakuAST::Doc::Markup.new( | |
| letter => "L", | |
| opener => "<", | |
| closer => ">", | |
| atoms => ( | |
| "test", | |
| ), | |
| meta => ( | |
| "mod://JSON::Fast:ver<42>#to-json", | |
| ) | |
| ) | |
| </code></pre> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fuyRF"> | |
| <div class='header'> | |
| <span class='author'>@ugexe</span> commented at <time datetime="2023-06-25T13:47:28Z">2023-06-25 13:47</time> | |
| </div> | |
| <div class='body'> | |
| <p>Some other things to consider that crossed my mind:</p> | |
| <p>Is this <code>mod://</code> string is meant to be an actual URI? If so I don't think we could use <code>:</code>, <code><</code>, or <code>></code> (among others) in the host portion of it. The <a href="https://en.wikipedia.org/wiki/File_URI_scheme">file URI scheme</a> solves a similar problem (that <code>/</code> can be contained in the first part -- i.e. the host) by starting the scheme with a triple slash ala <code>file:///</code> (thus e.g. <code>JSON::Fast</code> would end up in the path portion of the URI instead of host).</p> | |
| <p>Another other thing is that <code>:</code> <code><</code> <code>></code> would typically be URI encoded. This might not be a problem as most tooling can probably handle that conversion, but I do wonder if having the URI not parse-able by URI grammars in their initial form will lead to problems down the road. I'm not really sure there is a good solution for this, but it is worth being aware of.</p> | |
| <p>Third, while it doesn't map directly to raku syntax, it might be better to pass filters like we normally would with a URI, ala <code>mod:///Foo::Bar?version=1&api=2&auth="blorg"</code>. This also happens to solve some parts of the previous problem since we wouldn't be passing in <code><</code> and <code>></code>.</p> | |
| <p>Fourth, should we use a different prefix like <code>rakumod://</code>? That might make it easier to have something that would show up on e.g. https://en.wikipedia.org/wiki/List_of_URI_schemes since it wouldn't be using a super generic scheme <code>mod</code></p> | |
| <p>Finally, should this URI map to a distribution + module? For instance a distribution called <code>Net::HTTP</code> which provides a module <code>Net::HTTP::Get</code>: <code>rakumod:///Net::HTTP/Net::HTTP::GET?version=1&auth="github:ugexe"</code>. I.e. first path portion would be the distribution, the second path portion (which could be optional) would be something contained in that distribution.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fu0m-"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-25T14:17:06Z">2023-06-25 14:17</time> | |
| </div> | |
| <div class='body'> | |
| <p>It shouldn't be an actual URI, should it? Language implementation should create the RakuDoc data and then RakuDoc renderer should create the suitable link/whatever IMO.</p> | |
| <p>The old design docs mention <code>L<doc:Module::Name></code>: https://design.raku.org/S26.html#Links</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fu1sM"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-25T14:27:52Z">2023-06-25 14:27</time> | |
| </div> | |
| <div class='body'> | |
| <p>To respond to @ugexe , let me start with some initial ideas.</p> | |
| <p>The idea behind the <code>mod:</code> schema is to make it easier for a documentation writer to refer to a module without needing to know where the module is located.</p> | |
| <p>A link has two parts <code>L< 'the text shown in the documentation' | 'the meta data containing the link</code>>`. So when I say 'meta data', I mean the second bit.</p> | |
| <p>The metadata can already contain three schemas: <code>http://</code>, <code>https://</code>, <code>file://</code></p> | |
| <p>The original suggestion was to have quite a few more, but the one that seems to have usefulness is <code>toc:</code>, to which we are adding <code>index:</code>.</p> | |
| <p>The new schema requested was <code>mod:</code>, but <code>:rakumod</code> seems a better idea since I'm sure someone will want to reference a module in another language, which would increase complexity without much benefit.</p> | |
| <p>Since the idea is to make it easy to write and (read the raw Rakudoc), my feeling is that the <code>rakumod:</code> schema should be as close to the Raku standard idiom as possible.</p> | |
| <p>The question about the URI mapping is something I would call the 'semantics' of the schema (I'm probably technically wrong here). I would think that when a renderer creates the rendered version, for example an HTML <code><a></code> tab, it should create something like <code>Foo::Bar?version=1&api=2&auth="blorg"</code> from <code>L<< text | mod://Foo::Bar:ver<1>:api<2>:auth<blorg> >></code>.</p> | |
| <p>As to distribution / module parts, I think there is a question to be resolved. Where doe s the link to point at? Suppose we have a distribution <code>ExampleModule</code> structured as</p> | |
| <pre><code>ExampleModule/ | |
| docs/ | |
| README.rakudoc | |
| Moredetail.rakudoc | |
| lib/ | |
| ExampleModule.rakumod | |
| README.md | |
| </code></pre> | |
| <p>Now we have <code>L<looking at the Example module|rakumod://ExampleModule></code>, where does it reference? And an HTML URL is going to expect an HTML page to be served back.</p> | |
| <p>This indicates that a <code>Rakumod:</code> schema imposes an expectation on the site that is serving the link.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fu5SN"> | |
| <div class='header'> | |
| <span class='author'>@niner</span> commented at <time datetime="2023-06-25T15:13:40Z">2023-06-25 15:13</time> | |
| </div> | |
| <div class='body'> | |
| <p>Another point for rakumod: is that it's more self-documenting. It's crystal clear that the URI is identifying a Raku module.</p> | |
| <p>Since we want to use a URI to identify these modules, we must adhere to the URI syntax. Everything else would just put an unneeded burden on tool developers. As such a tool developer, I'd expect to be able to pass the actual link to a standard URI parser to get at the individual components (most of all the scheme to determine, how to link). The URI part after the initial <code>//</code> is the authority which is <code>[userinfo "@"] host [":" port]</code>. As we don't have that kind of information in rakumod links, it doesn't make sense to include the <code>//</code>. Thus a sensible URI would look like <code>rakumod:Foo::Bar</code></p> | |
| <p>As to the question of how to encode adverbs, I would suggest that we stick to URI syntax as @ugexe suggested: <code>rakumod:Foo::Bar?version=1&api=2&auth="blorg"</code>. The reasons are:</p> | |
| <ul> | |
| <li>Since tools will already use a URI parser for processing these links, getting the adverbs will be very straight forward, without having to parse the path part yet again.</li> | |
| <li>The <code>:version<1></code> syntax might be quite common, but it's by no means standard and by far not the only one. A benign alternative would be <code>:version(1)</code>, but syntactically it could also be <code>:version(1 + 2)</code> or really arbitrary code. I'm pretty sure we do not want to go down that route.</li> | |
| <li>If you argue, that the above is nonsense and we'd of course not allow full Raku syntax in these adverbs, then you'll have to answer how to e.g. quote <code>></code> characters contained in these fields (like auth <code>super>>fancy>>company</code>). The closer you stick to standard URI syntax, the more obvious the answers are.</li> | |
| <li>Even with <code>:version<1></code> you'll end up with the mentioned <code>> >></code> at the end of the link, which only makes it harder to read.</li> | |
| </ul> | |
| <p>Just a side node: technically, we don't want those links to be URIs, but IRIs instead. After all, we'll permit pretty much all of Unicode there as usual.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fu_GA"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-25T16:37:58Z">2023-06-25 16:37</time> | |
| </div> | |
| <div class='body'> | |
| <p>Maybe it's because I haven't been involved, but I still don't understand why the tools need to parse the <code>L<></code> link. Isn't it the job of Raku to provide the necessary and parsed data?</p> | |
| <p>For the dist/module linking, I think it needs to be standardized, so tools know what doc to show as the main document and in what order.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvMn7"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-25T18:15:40Z">2023-06-25 18:15</time> | |
| </div> | |
| <div class='body'> | |
| <p>FWIW, in RakuAST, anything after the <code>|</code> in <code>L<></code> will appear in the <code>meta</code> attribute. That it didn't so far in some cases, was a bug and that has been fixed.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvNYj"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-25T18:26:27Z">2023-06-25 18:26</time> | |
| </div> | |
| <div class='body'> | |
| <p>Just to be clear, I mean maybe Raku should do more than extracting the link, also parse it and provide an object representing the dist/module, since Raku already supports that syntax.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvNrU"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-25T18:32:13Z">2023-06-25 18:32</time> | |
| </div> | |
| <div class='body'> | |
| <p>@CIAvash Here's my take on your comment. (I hope I'm not stating the obvious)</p> | |
| <p>Rakudoc is a markup language that is quite neutral to the way a user will view the documentation. ('quite neutral' although it leans heavily to HTML).</p> | |
| <p>Rakudoc is eventually <strong>rendered</strong> to an output that the reader will view. So a Rakudoc <code>some text L<pointer|https://docs.raku.org/language/pod></code> will be output into HTML as</p> | |
| <pre><code>some text <a href="http://docs.raku.org/language/pod>pointer</a> | |
| </code></pre> | |
| <p>and into Markdown as</p> | |
| <pre><code>some text [pointer](http://docs.raku.org/language/pod) | |
| </code></pre> | |
| <p>and eventually into epub in an xhml version.</p> | |
| <p>Currently parses the Rakudoc into a <code>$=pod</code> tree as</p> | |
| <pre><code>[Pod::Block::Named.new(name => "pod", config => {}, contents => [Pod::Block::Para.new(config => {}, contents => ["some text ", Pod::FormattingCode.new(type => "L", meta => ["http://docs.raku.org/language/pod"], config => {}, contents => ["pointer"])])])] | |
| </code></pre> | |
| <p>It is the renderer that takes the pod block and turns it into html or markdown.</p> | |
| <p>In the future, it won't be a POD block, but an AST tree that is used by the Render. Here is the AST tree for the same file.</p> | |
| <pre><code>RakuAST::StatementList.new( | |
| RakuAST::Doc::Block.new( | |
| type => "pod", | |
| paragraphs => ( | |
| RakuAST::Doc::Paragraph.new( | |
| "some text ", | |
| RakuAST::Doc::Markup.new( | |
| letter => "L", | |
| opener => "«", | |
| closer => "»", | |
| atoms => ( | |
| "pointer", | |
| ), | |
| meta => ( | |
| "http://docs.raku.org/language/pod", | |
| ) | |
| ), | |
| "\n\n" | |
| ), | |
| ) | |
| ), | |
| ) | |
| </code></pre> | |
| <p>The current conversation is exactly about standardising the distribution / module order and what is intended by it.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvQEB"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-25T19:05:07Z">2023-06-25 19:05</time> | |
| </div> | |
| <div class='body'> | |
| <p>Yes, what I'm suggesting is that if Raku sees <code>L<rakumod:Some::Dist::Module:ver<1.0.0>></code> , it should generate more data in RakuDoc/RakuAST(if there won't be a pod block). So as an example:</p> | |
| <pre><code class="language-raku">RakuAST::StatementList.new( | |
| RakuAST::Doc::Block.new( | |
| type => "pod", | |
| paragraphs => ( | |
| RakuAST::Doc::Paragraph.new( | |
| "some text ", | |
| RakuAST::Doc::Markup.new( | |
| letter => "L", | |
| type => "module", # or something like that | |
| opener => "«", | |
| closer => "»", | |
| atoms => ( | |
| "Some::Dist::Module", | |
| ), | |
| meta => ( | |
| RakuAST::Doc::Module.new( | |
| dist => "Some::Dist", | |
| module => "Module", | |
| version => "1.0.0", | |
| ) | |
| ) | |
| ), | |
| "\n\n" | |
| ), | |
| ) | |
| ), | |
| ) | |
| </code></pre> | |
| <p>Again, just an example of what I mean.</p> | |
| <p>And maybe even something like <code>L<doc:language/pod></code> can be used to refer to official docs. (if their location is stable).</p> | |
| <p>And normal links continue to work as usual.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvQSH"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-25T19:08:35Z">2023-06-25 19:08</time> | |
| </div> | |
| <div class='body'> | |
| <p>Re: <code>RakuAST::Doc::Module</code>: it feels to me that this should be a more generally useful object, e.g. as a result of <code>use Some::Dist:ver<1.0.0></code>. So the name should probably not include the <code>::Doc</code> part.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvQYk"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-25T19:10:42Z">2023-06-25 19:10</time> | |
| </div> | |
| <div class='body'> | |
| <p>Yeah, it was just for sake of example, I didn't want to emphasize on the naming.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvQr5"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-25T19:17:25Z">2023-06-25 19:17</time> | |
| </div> | |
| <div class='body'> | |
| <p>@lizmat if I understand what you said, then <code>use Some::Distribution</code> and <code>L<xx|rakumod://Some::Distribution></code> could be more intimately linked. May be even get the data from the local installation???</p> | |
| <p>Also, for readability I prefer <code>rakumod://</code> to <code>rakumod:</code>. It is analogous to <code>file://</code> and <code>http://</code>. I accept that the <code>//</code> serve a purpose in <code>file:</code> etc, but I have never seen <code>http:</code> without a <code>http://</code></p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fvVn0"> | |
| <div class='header'> | |
| <span class='author'>@niner</span> commented at <time datetime="2023-06-25T19:57:44Z">2023-06-25 19:57</time> | |
| </div> | |
| <div class='body'> | |
| <p>That's because it doesn't make sense to use the HTTP protocol with something that isn't an HTTP server that's running on some host. So you will always find authority parts in HTTP URIs. You don't find them in mailto URIs like <code>mailto:foo@bar.org</code> or data URIs like <code>data:just%20a%20string</code>. You want it to be a URI? Then adhere to URI's syntax. Otherwise it is not a URI. If it just sorta, kinda looks like a URI, but really isn't, then it's just confusing.</p> | |
| <p>If the Raku parser is responsible for parsing that URI and turning it into some more capable object, then what is it supposed to do with e.g. https or file URIs?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fxE6T"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-26T05:58:08Z">2023-06-26 05:58</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>That's because it doesn't make sense to use the HTTP protocol with something that isn't an HTTP server that's running on some host. So you will always find authority parts in HTTP URIs. You don't find them in mailto URIs like <code>mailto:foo@bar.org</code> or data URIs like <code>data:just%20a%20string</code>. You want it to be a URI? Then adhere to URI's syntax. Otherwise it is not a URI. If it just sorta, kinda looks like a URI, but really isn't, then it's just confusing.</p> | |
| </blockquote> | |
| <p>I agree with the first part. I think it shouldn't be <code>rakumod://</code>, but I personally don't find <code>rakumod:</code> confusing.</p> | |
| <blockquote> | |
| <p>If the Raku parser is responsible for parsing that URI and turning it into some more capable object, then what is it supposed to do with e.g. https or file URIs?</p> | |
| </blockquote> | |
| <p>As I mentioned in my comment, they won't be treated specially, the URL will be what is inside <code>L<></code>.</p> | |
| <p>I think Raku should parse the <code>L<></code> link and create objects only when it's special. e.g. <code>rakumod:</code>, <code>rakudoc:</code> or maybe even <code>man:</code>(for manuals). And if that's not okay, maybe we should use a new code formatter for linking to documentations.</p> | |
| <p>But if others disagree with this approach, then what makes the most sense is using the URI scheme. Examples for that were given by @niner and @ugexe. another example I would add is the <a href="https://en.wikipedia.org/wiki/Magnet_URI_scheme">Magnet URI scheme</a>.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fxmta"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-26T07:08:11Z">2023-06-26 07:08</time> | |
| </div> | |
| <div class='body'> | |
| <p>One way of avoiding URI scheme and creating a new code formatter can be using <code>C<></code> inside <code>L<></code> to make it clear that we are linking to some code, but it may get verbose:</p> | |
| <pre><code class="language-raku">L<C<mod:Some::Dist:ver<1.0.0>>> | |
| L<C<mod:Some::Dist:ver<1.0.0>::Module::some_function()>> | |
| L<C<mod:Some::Dist:ver<1.0.0>::Class.some_method()>> | |
| L<C<mod:Some::Dist:ver<1.0.0>::Class.some_attribute>> | |
| </code></pre> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fxtSm"> | |
| <div class='header'> | |
| <span class='author'>@niner</span> commented at <time datetime="2023-06-26T07:26:41Z">2023-06-26 07:26</time> | |
| </div> | |
| <div class='body'> | |
| <p>That's one way, but why add this complication? Links contain labels and URIs. That's easy to understand and will certainly match expectations set up by all other important formats like HTML and Markdown. URIs are the perfect way to express such links as after all they are Universal Resource Identifiers. They really can identify anything. Adding a special <code>rakumod</code> scheme is exactly how our use-case is meant to be handled by URIs. All that's really unclear is what syntax to use for those adverbs.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fxtuk"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-26T07:28:00Z">2023-06-26 07:28</time> | |
| </div> | |
| <div class='body'> | |
| <p>For documentation ordering, I can only speak from my experience and the way I do it; I mostly put documentation inside the code, so based on that my suggestion would be:</p> | |
| <ol> | |
| <li>Look at the <code>docs</code> directory(if that's the new place to put the docs) and use the corresponding doc</li> | |
| <li>Use the README.rakudoc in <code>docs</code> directory(if the link points to the dist)</li> | |
| <li>Use doc from the Raku files(<code>.raku</code>, <code>.rakumod</code>)</li> | |
| <li>Use the README.md (or other readme files)</li> | |
| </ol> | |
| <p>One problem with this order, might be that developer used some documentation in the code, but the full documentation is in the README.md, …</p> | |
| <p>One way to solve this would be leaving it to the programmer to specify it, using the <code>=config</code> block.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fxz-V"> | |
| <div class='header'> | |
| <span class='author'>@CIAvash</span> commented at <time datetime="2023-06-26T07:42:11Z">2023-06-26 07:42</time> | |
| </div> | |
| <div class='body'> | |
| <p>@niner I don't know, maybe you're right, but that syntax is more familiar to Raku programmers.</p> | |
| <p>Using URI scheme:</p> | |
| <pre><code class="language-raku">L<rakumod:Some::Dist?version="1.0.0"> | |
| L<rakumod:Some::Dist?version="1.0.0"&module=Module&function="some_function"> | |
| L<rakumod:Some::Dist?version="1.0.0"&class=Class&method="some_method"> | |
| L<rakumod:Some::Dist?version="1.0.0"&class=Class&attribute=some_attribute> | |
| </code></pre> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f3KLY"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-26T21:34:41Z">2023-06-26 21:34</time> | |
| </div> | |
| <div class='body'> | |
| <p>Having read through the thread, I'm somewhat baffled with a couple of things.</p> | |
| <p>First of all, I like the URI approach in general. BTW, speaking of <code>rakumod:</code> vs. <code>rakumod://</code> – this can be left out for a document writer to decide, which one is preferred for them. That's not a big deal, in my view.</p> | |
| <p>The use of standard URI arguments also appeals to me. But there is a fly in the ointment: are we going to support <code>:ver<1.0+></code>? If so then I'd hate having to remember to write it as <code>version="1.0%2B"</code> since even right now I'm not sure if the code is correct, even though I was looking for it only a couple of minutes ago.</p> | |
| <p>The other question is about the interpretation of the "host" part of URI. In <code>L<rakumod:Foo::Bar></code> – is it about a distribution, or is it about a module? <code>rakudist:Foo::Bar</code> is one solution, but multiplying schemes isn't the best of the best. I would propose the following order:</p> | |
| <ol> | |
| <li><code>rakumod:Foo::Bar</code> points to a module. If it is not part of the current distribution then we expect it to be possible to locate the distro in an index of some kind.</li> | |
| <li><code>rakumod:Foo::Bar?in="Foo"</code> to use distribution "Foo".</li> | |
| <li><code>rakumod:Foo?module="Foo::Bar"</code> is the same, but it may have different meaning in a very specific case.</li> | |
| <li><code>rakumod:Foo::Bar?dist</code> is for cases when a distribution a module of the same name and we want to be explicit about linking to the distro. Useful for, say, pointing out to a download page. 'dist' could be aliased 'distribution' for purists sake. ;)</li> | |
| </ol> | |
| <p>Speaking of the difference between 2 and 3, it could play a role for a rare but not impossible case when a module has versions different from those on the distribution. Since we do not prohibit such discrepancies then they are allowed. In this case <code>rakumod:Foo::Bar?in="Foo"&ver="1.0"</code> would be about <code>Foo::Bar:ver<1.0></code> in the distribution <code>Foo</code>. Apparently, <code>rakumod:Foo?module="Foo::Bar"&ver=1.2"</code> is a link to distribution <code>Foo:ver<1.2></code>.</p> | |
| <p>Speaking of the advantages of using URI-complient meta, the arguments not used to select module/distribution version can be bypassed to the final link. If translated into a URL the arguments would be submitted to a web server.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f3TBJ"> | |
| <div class='header'> | |
| <span class='author'>@ugexe</span> commented at <time datetime="2023-06-26T21:47:25Z">2023-06-26 21:47</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>are we going to support :ver<1.0+>?</p> | |
| </blockquote> | |
| <p>I wouldn't think so. There isn't really anything it could link to that makes a lot of sense.</p> | |
| <blockquote> | |
| <p>rakumod:Foo::Bar?in="Foo" to use distribution "Foo".</p> | |
| </blockquote> | |
| <p>The only issue here is that the distribution always exists, but modules may not. For instance: a distribution that provides all of its functionality / code inside of a <code>bin/myapp</code> file.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f3db2"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-26T21:58:31Z">2023-06-26 21:58</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <blockquote> | |
| <p>are we going to support :ver<1.0+>?</p> | |
| </blockquote> | |
| <p>I wouldn't think so. There isn't really anything it could link to that makes a lot of sense.</p> | |
| </blockquote> | |
| <p>Not exactly. Say, I have a dependency with the same version mask and would like to link to the same version. But considering what may go wrong here, I wouldn't mind if this feature remains missing.</p> | |
| <blockquote> | |
| <blockquote> | |
| <p>rakumod:Foo::Bar?in="Foo" to use distribution "Foo".</p> | |
| </blockquote> | |
| <p>The only issue here is that the distribution always exists, but modules may not. For instance: a distribution that provides all of its functionality / code inside of a <code>bin/myapp</code> file.</p> | |
| </blockquote> | |
| <p>Are links pointing to nowhere is a big surprise to you? ;) I tend to check as many links in my docs as possible. In the future we may get a linter for Rakudoc too.</p> | |
| <p>Either way, we talk about documentation, not modules themselves. <code>rakumod:Foo::Bar?in="Foo"</code> could eventually lead me to <code>doc/Foo/Bar.rakudoc</code>, or to a render of it.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f3pNZ"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-26T22:49:06Z">2023-06-26 22:49</time> | |
| </div> | |
| <div class='body'> | |
| <p>I am unclear what to think about the complex syntax for distributions and modules. I think that the links are not to modules themselves, but to documentation about the distribution / modules. Locations within a document are not necessarily the names of classes/roles/sub etc, but are anchors defined by <code>=head</code> or <code>X<></code> markup. A heading might be eg a <code>sub</code> name, but that is a writers choice.</p> | |
| <p>If a link is expected to resolve to an HTML page, then the actual page served will depend on the server site.</p> | |
| <p>@ugexe are you against the <code>+</code> in the <code>ver<2.1+></code> ? If documentation changes between versions, I can see the need for <code>ver<2.1></code>, but not for <code>+</code>.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f33N7"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-26T23:50:53Z">2023-06-26 23:50</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>I think that the links are not to modules themselves, but to documentation about the distribution / modules.</p> | |
| </blockquote> | |
| <p>You're right. But to resolve a link to a module we'd need to locate its distribution. This could be especially relevant for local offline documentation browsers when they'd need to search through local caches.</p> | |
| <p>The point about module version vs. distribution version could be especially confusing. <code>:api</code> versioning could serve even better example to get the point. Imagine a distribution <code>Foo</code> where <code>Foo::Bar</code> module provides very conservative API which version could lag behind distro's API. Say, there is something like <code>"api": "1.5",</code> in META6, but <code>module Foo::Bar:api<1.1>;</code>. In this case, having <code>use Foo::Bar:api<1.1>;</code> in one's sources would naturally translate into <code>L<rakumod:Foo::Bar?api="1.1"></code> in the docs. The developer wouldn't care in which <code>Foo</code> distribution version the destination page is found as long as it documents the requested API version.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5f4VLq"> | |
| <div class='header'> | |
| <span class='author'>@ugexe</span> commented at <time datetime="2023-06-27T02:14:59Z">2023-06-27 02:14</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>@ugexe are you against the + in the ver<2.1+> ?</p> | |
| </blockquote> | |
| <p>There is nothing inherently wrong with including it, but I do think it will increase the complexity quite a bit since it now implies tooling needs methods of resolving these types of queries in the same way raku would (i.e. use the same sort order). I suppose if such a link did exist I would expect it to go to the latest distribution that is greater than 2.1 (similar to requesting a document without a version at all probably implies the latest version)</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5gJjX-"> | |
| <div class='header'> | |
| <span class='author'>@finanalyst</span> commented at <time datetime="2023-06-29T12:45:44Z">2023-06-29 12:45</time> | |
| </div> | |
| <div class='body'> | |
| <p>Rather than <code>rakumod:</code> perhaps it should be <code>rakudoc:</code> ? This would signal clearly that the link is to documentation, and not to code.</p> | |
| <p>It also implies that the documentation may be found in a <code>.rakudoc</code> or <code>.rakumod</code> file.</p> | |
| <p>It also means that the link is to sources written in <strong>Rakudoc</strong> and not just sources written in <strong>raku</strong>, which is possible because there are non-raku implementations of POD6 and hopefully of Rakudoc.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5gMBTn"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-06-29T20:22:55Z">2023-06-29 20:22</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>Rather than <code>rakumod:</code> perhaps it should be <code>rakudoc:</code> ?</p> | |
| </blockquote> | |
| <p>Makes sense to me.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="372"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/372"><span class='number'>372</span></a> - <span class='title'>Are Captures value types or not?</span></div> | |
| <div class='author'>[open]<span class='author'>@lizmat</span> opend this issue at <time datetime="2023-06-20T08:47:59Z">2023-06-20 08:47</time></div> | |
| </div> | |
| <div class='body'> | |
| <p><code>Capture</code> instances are currently implemented as being a value type (basically since https://github.com/rakudo/rakudo/commit/c855a0f439 ).</p> | |
| <p>However, since https://github.com/Raku/old-issue-tracker/issues/4360 it has made elements of it mutable (if they were created with containers).</p> | |
| <p>If an element in a <code>Capture</code> is changed, it's associated <code>.WHICH</code> will also change. This violates the principle of immutability of value types.</p> | |
| <p>Making <code>Capture</code> instances immutable, breaks spectests. | |
| Making the <code>Capture</code> class an object type, also breaks spectests.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5fRUPO"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-20T08:50:54Z">2023-06-20 08:50</time> | |
| </div> | |
| <div class='body'> | |
| <p>Propose to:</p> | |
| <ul> | |
| <li>keep <code>Capture</code> being a value type</li> | |
| <li>disallow mutations in the object (remove <code>is raw</code> from <code>AT-POS</code> / <code>AT-KEY</code>)</li> | |
| <li>adapt spectests accordingly</li> | |
| </ul> | |
| <p>Ideally to be done with a language level check, but I think that will turn out to be pretty hard to do.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fRkwA"> | |
| <div class='header'> | |
| <span class='author'>@jnthn</span> commented at <time datetime="2023-06-20T09:34:33Z">2023-06-20 09:34</time> | |
| </div> | |
| <div class='body'> | |
| <p>The primary purpose of <code>Capture</code> in the language is to model an argument list, and arguments may be mutated by <code>is rw</code> parameters. For example, consider:</p> | |
| <pre><code>sub foo($p is rw) { | |
| $p++; | |
| } | |
| my $x = 1; | |
| my \c = \($x); | |
| foo(|c); | |
| say c; | |
| </code></pre> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fRlVL"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-20T09:36:08Z">2023-06-20 09:36</time> | |
| </div> | |
| <div class='body'> | |
| <p>@jnthn So then it shouldn't be a value type then?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fRszb"> | |
| <div class='header'> | |
| <span class='author'>@jnthn</span> commented at <time datetime="2023-06-20T09:57:26Z">2023-06-20 09:57</time> | |
| </div> | |
| <div class='body'> | |
| <p>Correct, although it'd make sense for snapshot equality (<code>eqv</code>) to work.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="371"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/371"><span class='number'>371</span></a> - <span class='title'>Trailing declarator docs semantics need to be revisited</span></div> | |
| <div class='author'>[closed]<span class='author'>@lizmat</span> opend this issue at <time datetime="2023-05-18T10:43:30Z">2023-05-18 10:43</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>S26 states:</p> | |
| <blockquote> | |
| <p>Declarator blocks that start with C<#=> attach to the declarator declared at the start of the line immediately before them.</p> | |
| </blockquote> | |
| <p>Seems pretty clear cut, now doesn't it. However, the current implementation is way too lenient in attaching, and sometimes attaches to objects one might not expect. Some examples. Please note that all of these examples have been distilled from actual spectests! :-(</p> | |
| <pre><code class="language-raku">class A { | |
| has $.a; has $.b; #= trailing | |
| } | |
| </code></pre> | |
| <p>So, does the trailing doc attach to <code>$.a</code> or <code>$.b</code>? It attaches to <code>$.a</code>!</p> | |
| <pre><code class="language-raku">sub six(Str $param1, Str $param2) { | |
| #= trailing comment for six? | |
| } | |
| </code></pre> | |
| <p>So does this attach to the <code>sub six</code>? Or to <code>$param2</code>. It attaches to the sub, whereas <code>$param2</code> is the last object seen that can have declarator doc.</p> | |
| <pre><code class="language-raku">sub a { } | |
| ... many lines of code without declarable objects | |
| #= still attaches to &a | |
| </code></pre> | |
| <p>The trailing declarator can be <em>many</em> lines after the object it attaches to, if there's nothing declarable inbetween. This violates S26.</p> | |
| <p>Another example, where trailing docs are before the leading docs:</p> | |
| <pre><code class="language-raku">sub four {} | |
| #| before five | |
| #= after four | |
| sub five {} | |
| </code></pre> | |
| <p>I think this should at least be a worry, as this may indicate a mixup on leading/trailing doc, or a copy-pasto.</p> | |
| <p>And a more general issue, that could be considered a bug:</p> | |
| <pre><code class="language-raku">sub a { | |
| #= foo bar | |
| } | |
| </code></pre> | |
| <p>That actually attaches the trailing doc to <code>sub a</code>. But the object that lives in <code>$=pod</code>'s is <em>not</em> complete: its <code>WHEREFORE</code> is <code>Any</code>, <strong>unless</strong> you call <code>&a.WHY</code> after which it will be correct. But that's not very useful for rakudoc renderers, as it won't be able to see to what the pod applies to.</p> | |
| <p>I think we should have clearer rules on what the exact semantics are, and have more worries issued in situations where it would be unclear to which object a trailing doc should be attached to.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5ck2ap"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-05-18T14:38:04Z">2023-05-18 14:38</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <pre><code class="language-raku">sub six(Str $param1, Str $param2) { | |
| #= trailing comment for six? | |
| } | |
| </code></pre> | |
| <p>So does this attach to the sub six? Or to $param2. It attaches to the sub, whereas $param2 is the last object seen that can have declarator doc.</p> | |
| <pre><code></code></pre> | |
| </blockquote> | |
| <p>I think, unless we make it an error, attaching to the <code>sub</code> is sufficiently logical. The parameters belong to the signature's visual context, i.e. enclosed in parentheses, whereas the pod already belongs to the block context.</p> | |
| <p>But this is the only note I have. Because making this particular case an error would make better sense. As well as the other proposals too.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5c3fHu"> | |
| <div class='header'> | |
| <span class='author'>@alabamenhu</span> commented at <time datetime="2023-05-22T21:37:09Z">2023-05-22 21:37</time> | |
| </div> | |
| <div class='body'> | |
| <p>For what it's worth, I've used the</p> | |
| <pre><code>sub foo($a, $b) { | |
| #= description of foo | |
| } | |
| </code></pre> | |
| <p>In some of my code. I would be genuinely surprised (akin to the <code>my $a; my $b; #= attaches to $a</code> issue) if it didn't. Justification can come from the idea that the declaration of the parameters occurs inside the signature, and so is opaque to the trailing comment which effectively only sees <code>sub foo(…) { … }</code> and thus attaches accordingly.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5c6Ndy"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-05-23T08:15:42Z">2023-05-23 08:15</time> | |
| </div> | |
| <div class='body'> | |
| <p>But that implies some kind of scoping and style semantics: would the trailing declarator doc also apply to the sub in this case?</p> | |
| <pre><code class="language-raku">sub foo( | |
| $a, | |
| $b | |
| ) { | |
| #= description of foo | |
| } | |
| </code></pre> | |
| <p>At the grammar level, there's no functional difference between the two. The only way to make the difference, is to start looking at line numbers. And that becomes very fragile very quickly.</p> | |
| <p>Another solution might be to deprecate trailing declarator doc altogether?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5fROQy"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-06-20T08:33:29Z">2023-06-20 08:33</time> | |
| </div> | |
| <div class='body'> | |
| <p>At the RSC it was decided that the <em>last</em> declarator seen, will be used for attaching trailing declarator doc.</p> | |
| <p>Also that the declarator doc needs to start on the same line as the declarator, or at the start of the line immediately after that. This has now been implemented in RakuAST, and spectests have been adapted accordingly.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5gCMW3"> | |
| <div class='header'> | |
| <span class='author'>@alabamenhu</span> commented at <time datetime="2023-06-28T10:53:00Z">2023-06-28 10:53</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>At the RSC it was decided that the <em>last</em> declarator seen, will be used for attaching trailing declarator doc.</p> | |
| </blockquote> | |
| <p>Whelp, time for me to update a bunch of modules lol. But it's good that some standard has been set so it's clear how it will be handled.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="370"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/370"><span class='number'>370</span></a> - <span class='title'>A way around "multi-level classification"</span></div> | |
| <div class='author'>[open]<span class='author'>@2colours</span> opend this issue at <time datetime="2023-04-22T00:50:28Z">2023-04-22 00:50</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>A sister issue of https://github.com/Raku/doc/issues/4293.</p> | |
| <p>The capability of multi-level classification is nice but sometimes, it would be good to really just use an <code>Iterable</code> as a key of a flat <code>Hash</code>. It seems too broad to lose all control of the otherwise default behavior by introducing <code>Iterable</code>s in the classification.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5agbNE"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-04-22T00:53:04Z">2023-04-22 00:53</time> | |
| </div> | |
| <div class='body'> | |
| <p>A couple of ideas:</p> | |
| <ul> | |
| <li>an "adverb" to control multi-level classification; either opt-in or opt-out</li> | |
| <li>draw a distinction using containers (or conceptually rather itemization)</li> | |
| <li>draw a distinction using <code>Slip</code>s</li> | |
| </ul> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="369"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/369"><span class='number'>369</span></a> - <span class='title'>Provide `sort` with `:k` adverb (returns ordinal index)</span></div> | |
| <div class='author'>[open]<span class='author'>@jubilatious1</span> opend this issue at <time datetime="2023-04-11T21:41:36Z">2023-04-11 21:41</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>Similar to issue posted by @0rir (and comment by @0racle):</p> | |
| <h3>Provide <code>sort</code> with <code>:k</code> adverb (returns ordinal index)</h3> | |
| <p>Sometimes you don't need the values of a data structure returned in correct <code>sort</code> order--sometimes you just need the correct <code>order</code> (ordinal index) of those elements.</p> | |
| <p>In the R-programming language, you get two different functions to accomplish these tasks, <code>sort</code> and <code>order</code>:</p> | |
| <p>https://web.mit.edu/~r/current/lib/R/library/base/html/sort.html</p> | |
| <p>https://web.mit.edu/~r/current/lib/R/library/base/html/order.html</p> | |
| <p>Thx.</p> | |
| <hr /> | |
| <blockquote> | |
| <p>Putting my hand up as someone who has wanted <code>min</code>/<code>max</code> with <code>:k</code>.</p> | |
| <p>The ~~adverbs~~ named args should be similar to <code>first</code>, ie. <code>:v</code> just returns the value (default), <code>:k</code> returns the index, <code>:kv</code> returns a Seq of the index and value, and <code>:p</code> returns a Pair of the index and value.</p> | |
| </blockquote> | |
| <p><em>Originally posted by @0racle in https://github.com/Raku/problem-solving/issues/367#issuecomment-1499720683</em></p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5ZqDog"> | |
| <div class='header'> | |
| <span class='author'>@jubilatious1</span> commented at <time datetime="2023-04-11T22:15:24Z">2023-04-11 22:15</time> | |
| </div> | |
| <div class='body'> | |
| <p>Sampling/ordering code from the R-programming language, within the R-REPL:</p> | |
| <pre><code class="language-r">> samp1 <- sample(1:10, 10) | |
| > samp1 | |
| [1] 3 4 6 1 9 10 8 7 2 5 | |
| > order(samp1) | |
| [1] 4 9 1 2 10 3 8 7 5 6 | |
| > | |
| </code></pre> | |
| <p>Above, taking the <code>order()</code> of the <code>samp1</code> vector with the code <code>order(samp1)</code>:</p> | |
| <ul> | |
| <li> | |
| <p>Returns <code>4</code> in the first position, telling you that the lowest numeric value in <code>samp1</code> is in one-indexed position <code>4</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>1</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>9</code> in the second position, telling you that the second-lowest numeric value in <code>samp1</code> is in one-indexed position <code>9</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>2</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>1</code> in the third position, telling you that the third-lowest numeric value in <code>samp1</code> is in one-indexed position <code>1</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>3</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>2</code> in the fourth position, telling you that the fourth-lowest numeric value in <code>samp1</code> is in one-indexed position <code>2</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>4</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>10</code> in the fifth position, telling you that the fifth-lowest numeric value in <code>samp1</code> is in one-indexed position <code>10</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>5</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>3</code> in the sixth position, telling you that the sixth-lowest numeric value in <code>samp1</code> is in one-indexed position <code>3</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>6</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>8</code> in the seventh position, telling you that the seventh-lowest numeric value in <code>samp1</code> is in one-indexed position <code>8</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>7</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>7</code> in the eighth position, telling you that the eighth-lowest numeric value in <code>samp1</code> is in one-indexed position <code>7</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>8</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>5</code> in the ninth position, telling you that the ninth-lowest numeric value in <code>samp1</code> is in one-indexed position <code>5</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>9</code>).</p> | |
| </li> | |
| <li> | |
| <p>Returns <code>6</code> in the tenth position, telling you that the tenth-lowest numeric value in <code>samp1</code> is in one-indexed position <code>6</code> of the original <code>samp1</code> vector. (In this case, that value equals <code>10</code>).</p> | |
| </li> | |
| </ul> | |
| <hr /> | |
| <p>Meaning you can reorder the <code>samp1</code> vector ( <em><strong>or any other vector of identical length</strong></em>) based upon the index-output of <code>order(samp1)</code>:</p> | |
| <pre><code class="language-r">> samp1[order(samp1)] | |
| [1] 1 2 3 4 5 6 7 8 9 10 | |
| > | |
| </code></pre> | |
| <p>https://web.mit.edu/~r/current/lib/R/library/base/html/sort.html</p> | |
| <p>https://web.mit.edu/~r/current/lib/R/library/base/html/order.html</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ZqnJ4"> | |
| <div class='header'> | |
| <span class='author'>@0racle</span> commented at <time datetime="2023-04-12T00:42:38Z">2023-04-12 00:42</time> | |
| </div> | |
| <div class='body'> | |
| <p>Since I was quoted, I also think this feature would be useful. Notably, APL - which Larry was influenced by - does not have a <em>Sort</em> primitive, but it does have a <em>Grade</em> primitive that does exactly this</p> | |
| <pre><code class="language-apl"> ⍋ 3 4 6 1 9 10 8 7 2 5 | |
| 4 9 1 2 10 3 8 7 5 6 | |
| </code></pre> | |
| <p>So in APL (and it's decedents) Grade is seen as a more fundamental primitive, from which you can derive Sort. All this is to say that this concept of Grade (or <em>Order</em>) is useful in other algorithms (not just sort), and while it's possible (<code>*.pairs.sort(*.value)».key</code> is one way), having a simple <code>:k</code> option would be nice.</p> | |
| <p>Of course, unlike APL and R, Raku's indices would be 0-based, such that <code>@xs.sort ≡ @xs[@xs.sort(:k)]</code>.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ZtGL2"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-04-12T09:56:08Z">2023-04-12 09:56</time> | |
| </div> | |
| <div class='body'> | |
| <p>FWIW, if a sort is done with a Callable with a single positional argument, the list with indices basically already exists internally as part of the Schwartzian transform. So it looks to me that support for :k, :kv, :p could be easily derived by forcing a Schwarrtzian transform, and post-processing the indices list.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="368"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/368"><span class='number'>368</span></a> - <span class='title'>LinkedIn does not recognize "Raku Developer" as a job title.</span></div> | |
| <div class='author'>[open]<span class='author'>@bbkr</span> opend this issue at <time datetime="2023-04-01T14:38:19Z">2023-04-01 14:38</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>In LinkedIn when setting up "open to work" one has to choose job title. This title must be preselected - "Perl Developer" is present, but "Raku Developer" is nowhere to be found.</p> | |
| <p>It may be good idea to contact LinkedIn to add "Raku Developer" as an option.</p> | |
| <p>BTW: This issue is not about top search bar. This is about window where you set jobs that you are interested in.</p> | |
| </div> | |
| <div class='comments'> | |
| </div> | |
| </div> | |
| <div class='issue' id="367"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/367"><span class='number'>367</span></a> - <span class='title'>Add :k option to min and max</span></div> | |
| <div class='author'>[open]<span class='author'>@0rir</span> opend this issue at <time datetime="2023-03-27T21:32:30Z">2023-03-27 21:32</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>This is feature request for the addition of a <code>:k</code> option for appropriate types; <code>map</code> being the model.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5YmkSy"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-03-28T09:19:15Z">2023-03-28 09:19</time> | |
| </div> | |
| <div class='body'> | |
| <p>If I understand it correctly, you want it to produce the ordinal numbers of any matches?</p> | |
| <p>Could you give some code examples and expected result?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5YmnOg"> | |
| <div class='header'> | |
| <span class='author'>@jnthn</span> commented at <time datetime="2023-03-28T09:27:47Z">2023-03-28 09:27</time> | |
| </div> | |
| <div class='body'> | |
| <p>I figure it's about the list case of <code>min</code>, so <code>[4,1,2,-6,10].min(:k)</code> would evaluate to <code>3</code>, the index of the minimum element. While it's not mentioned, I imagine <code>:kv</code> and <code>:p</code> are implied by this request too.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5YoYkV"> | |
| <div class='header'> | |
| <span class='author'>@0rir</span> commented at <time datetime="2023-03-28T14:16:37Z">2023-03-28 14:16</time> | |
| </div> | |
| <div class='body'> | |
| <p>@lizmat, @jnthn, you both are entirely correct in what you say. | |
| I would have done better to reference <code>@a.first( @a.min)</code> as <code>:end</code> is also applicable.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5YpYV6"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-03-28T16:26:13Z">2023-03-28 16:26</time> | |
| </div> | |
| <div class='body'> | |
| <p>And I guess if there are multiple minimum / maximum values, it would produce multiple indices.</p> | |
| <p>@0rir I'm not sure how <code>:end</code> comes into play here?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5YpeI0"> | |
| <div class='header'> | |
| <span class='author'>@jnthn</span> commented at <time datetime="2023-03-28T16:43:26Z">2023-03-28 16:43</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>And I guess if there are multiple minimum / maximum values, it would produce multiple indices.</p> | |
| </blockquote> | |
| <p>Only if <code>min</code>/<code>max</code> have an option to do that already; otherwise, I'd keep it consistent with the value result.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5YqrX4"> | |
| <div class='header'> | |
| <span class='author'>@0rir</span> commented at <time datetime="2023-03-28T20:58:13Z">2023-03-28 20:58</time> | |
| </div> | |
| <div class='body'> | |
| <p>My thinking was to keep the return to the value element, the index or both in a <code>Pair</code>.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5ZY-vr"> | |
| <div class='header'> | |
| <span class='author'>@0racle</span> commented at <time datetime="2023-04-06T22:47:19Z">2023-04-06 22:47</time> | |
| </div> | |
| <div class='body'> | |
| <p>Putting my hand up as someone who has wanted <code>min</code>/<code>max</code> with <code>:k</code>.</p> | |
| <p>The ~~adverbs~~ named args should be similar to <code>first</code>, ie. <code>:v</code> just returns the value (default), <code>:k</code> returns the index, <code>:kv</code> returns a Seq of the index and value, and <code>:p</code> returns a Pair of the index and value.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="366"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/366"><span class='number'>366</span></a> - <span class='title'>`next`, `last`, `redo` shouldn't fall through subroutines</span></div> | |
| <div class='author'>[open]<span class='author'>@2colours</span> opend this issue at <time datetime="2023-03-08T11:18:36Z">2023-03-08 11:18</time></div> | |
| </div> | |
| <div class='body'> | |
| <!--- Write a short description of the problem here. --> | |
| <p>Inspired by https://github.com/Raku/doc/issues/4255 because it seems like this is an unnecessary trap to work with.</p> | |
| <!--- Provide more details here. *Do not* propose a solution. You can propose a solution later in the comments. --> | |
| <p>The <a href="https://design.raku.org/S04.html#The_Relationship_of_Lexical_and_Dynamic_Scopes">synopses actually do mention</a> the dynamic nature of a bare <code>next</code> (as opposed to a labelled <code>next</code>, for example) - however, this doesn't appear anywhere in <a href="https://github.com/Raku/roast/blob/master/S04-statements/next.t">the corresponding file of the specification</a>.</p> | |
| <p>In Raku, one can declare a <code>Block</code> that will act just like an actual inline block, including <code>next</code> behavior. <code>Sub</code>s have their own <code>return</code>. Implimentation differences aside (between <code>return</code> and <code>next</code> or <code>last</code>, that is), it really seems like a trap that <code>next</code> and the likes might implicitly have a broader scope of action than <code>return</code>, hence implicitly returning from a subroutine much "harder" than the actual <code>return</code> would.</p> | |
| <p>If somebody wants the fall-through behavior by default, chances are they don't need/want the tight <code>return</code> a <code>Sub</code> provides and they should really be thinking about using a <code>Block</code>. The code will also get clearer if a subroutine is really a lexical unit with the default control structures.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5XBiYk"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-03-08T11:29:14Z">2023-03-08 11:29</time> | |
| </div> | |
| <div class='body'> | |
| <p>My proposal would be to keep control exceptions like the ones <code>next</code> and <code>last</code> create, inside <code>Sub</code>s, hence throwing a similar exception to a legitimately missing loop to iterate.</p> | |
| <p>If somebody prefers the former (perhaps unspecified?) behavior:</p> | |
| <ul> | |
| <li>they can specify a CONTROL phaser to pass it through anyway</li> | |
| <li>I don't know how you feel about pragmas but there could be one to set the behavior for one <code>Sub</code> or the whole <code>CompUnit</code>, for example</li> | |
| </ul> | |
| <p>The topic of performance also came up from @lizmat . My stance on that is (besides the general sentiment of "it's better to be right slowly than wrong quickly"): the implementation doesn't need to be fast <em>immediately</em>. Loads of control structure optimizations will be available with RakuAST - in fact, most of the time, we could say it at compile time if an invalid <code>next</code> is used in a subroutine, by traversing from the usage of <code>next</code> towards the root <code>Sub</code>. At the very least, we can omit special handling when it's clear that there are no such control statements, or they are clearly scoped in a loop inside the <code>Sub</code>.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XCddJ"> | |
| <div class='header'> | |
| <span class='author'>@cfa</span> commented at <time datetime="2023-03-08T14:40:25Z">2023-03-08 14:40</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>The <a href="https://design.raku.org/S04.html#The_Relationship_of_Lexical_and_Dynamic_Scopes">synopses actually do mention</a> the dynamic nature of a bare <code>next</code> (as opposed to a labelled <code>next</code>, for example) - however, this doesn't appear anywhere in <a href="https://github.com/Raku/roast/blob/master/S04-statements/next.t">the corresponding file of the specification</a>.</p> | |
| </blockquote> | |
| <p>See https://github.com/Raku/roast/blob/master/S04-statements/last.t#L31-L39 for <code>last</code>.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XDPCH"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-03-08T16:33:15Z">2023-03-08 16:33</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <blockquote> | |
| <p>The <a href="https://design.raku.org/S04.html#The_Relationship_of_Lexical_and_Dynamic_Scopes">synopses actually do mention</a> the dynamic nature of a bare <code>next</code> (as opposed to a labelled <code>next</code>, for example) - however, this doesn't appear anywhere in <a href="https://github.com/Raku/roast/blob/master/S04-statements/next.t">the corresponding file of the specification</a>.</p> | |
| </blockquote> | |
| <p>See https://github.com/Raku/roast/blob/master/S04-statements/last.t#L31-L39 for <code>last</code>.</p> | |
| </blockquote> | |
| <p>I think this is the right place for design decisions anyway - so then the amendment woud be: introduce this in a new version, and modify the corresponding test.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XGChq"> | |
| <div class='header'> | |
| <span class='author'>@codesections</span> commented at <time datetime="2023-03-09T03:07:50Z">2023-03-09 03:07</time> | |
| </div> | |
| <div class='body'> | |
| <p>Hmm, my (tentative) thought is that the current behavior is reflects the correct design. A different way to phase this issue would be "<code>next</code>, <code>last</code>, and <code>redo</code> should have lexical scope rather than dynamic scope". But, phrased like that, I'm slightly inclined to disagree – it's very clear that <code>gather</code> is supposed to have dynamic scope, and <code>next</code>/<code>last</code>/<code>redo</code> "feel" similar enough to <code>gather</code> that I'm inclined to think that keeping their behavior consistent is the better design.</p> | |
| <p>On the other hand, lexical scope is more familiar to most programmers and I don't have <em>strong</em> feelings on the matter. So I'm certainly open to persuasion.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XJ0Mt"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-03-09T14:50:17Z">2023-03-09 14:50</time> | |
| </div> | |
| <div class='body'> | |
| <p>Just an example:</p> | |
| <pre><code class="language-raku">sub transform($v) { | |
| next if $v.contains("2"); | |
| "<$v>" | |
| } | |
| say (^20).map(&transform); | |
| </code></pre> | |
| <p>Even the <code>.map({...})</code> form is a good demonstration because the code block just cannot be in the same lexical scope where the iteration logic is located.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XJ12G"> | |
| <div class='header'> | |
| <span class='author'>@codesections</span> commented at <time datetime="2023-03-09T14:54:42Z">2023-03-09 14:54</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>Even the <code>.map({...})</code> form is a good demonstration because the code block just cannot be in the same lexical scope where the iteration logic is located.</p> | |
| </blockquote> | |
| <p>Well, it <em>can</em>:</p> | |
| <pre><code class="language-raku">say (^20).map({ | |
| next if .contains("2"); | |
| "<$_>" | |
| }); | |
| </code></pre> | |
| <p>But, more generally, I agree that there are times when a dynamic scope to <code>next</code> is useful/clearer.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XJ2rG"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-03-09T14:56:50Z">2023-03-09 14:56</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>Well, it <em>can</em>:</p> | |
| </blockquote> | |
| <p>You missed the point. The actual iterator logic is in <code>map</code> lexical scope, actually. :)</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XMjOQ"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-03-09T22:20:39Z">2023-03-09 22:20</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>Even the .map({...}) form is a good demonstration because the code block just cannot be in the same lexical scope where the iteration logic is located.</p> | |
| </blockquote> | |
| <p>The <code>.map({...})</code> form uses a <code>Block</code>, not a <code>Sub</code>. I'm not arguing against this behavior for a <code>Block</code> but a <code>Sub</code>. And consequently, that example looks like a good illustration of what I find confusing without any benefits.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XM_wS"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-03-10T00:17:27Z">2023-03-10 00:17</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>A different way to phase this issue would be "next, last, and redo should have lexical scope rather than dynamic scope"</p> | |
| </blockquote> | |
| <p>I don't think this reflects the <code>Block</code> vs <code>Sub</code> distinction. It's super useful and also fairly reasonable that a <code>Block</code> is transparent to all control structures. It could even look up all variables dynamically - I can imagine why that might be a bad idea but it could also make some sense. However, to have a subroutine that can be safely used as an independent unit of execution, is a different story.</p> | |
| <blockquote> | |
| <p>it's very clear that gather is supposed to have dynamic scope, and next/last/redo "feel" similar enough to gather that I'm inclined to think that keeping their behavior consistent is the better design.</p> | |
| </blockquote> | |
| <p>It seems to me that both statements can be challenged. I do think that <code>take</code> could also be taken as a cunning implicit callback and be subject to evalutation whether it's really worth it to let it slip through subroutines. However, let me point out that <code>take</code> does indeed have more of a callback interface that <code>next</code>, <code>last</code> and the likes don't have, and maybe for the better:</p> | |
| <pre><code class="language-raku">use v6.*; # To enforce next, last with return values | |
| gather for (1..10) { .take } # This is going to work | |
| (1..10).map: { .next } # This won't - has to use `next $_` | |
| (1..10).map: { .last } # This also won't - has to use `last $_` | |
| </code></pre> | |
| <p>Now, of course those control statements could be adopted to also have the OO-looking interface - which is also a modification that might interfere with existing code, and then we can still ask if it's really expressive or just confusing.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XNXcm"> | |
| <div class='header'> | |
| <span class='author'>@codesections</span> commented at <time datetime="2023-03-10T02:19:57Z">2023-03-10 02:19</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>I'm not arguing against this behavior for a Block but a Sub.</p> | |
| </blockquote> | |
| <p>IMO having this behavior differ between Blocks and Subs would be <em>highly</em> confusing.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XNsig"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-03-10T03:42:43Z">2023-03-10 03:42</time> | |
| </div> | |
| <div class='body'> | |
| <p>@2colours:</p> | |
| <blockquote> | |
| <p>The <code>.map({...})</code> form uses a <code>Block</code>, not a <code>Sub</code>. I'm not arguing against this behavior for a <code>Block</code> but a <code>Sub</code>. And consequently, that example looks like a good illustration of what I find confusing without any benefits.</p> | |
| </blockquote> | |
| <p>Are you sure about no benefits? I consider the <code>transform</code> sub from my example to be very beneficial as means of code clarification and organization. <code>.map(&transform)</code> (or <code>.map: &transform</code>) seems to be way more self-explanatory than using a block with all the same logic <code>transform</code> provides. Basically, the routine should've be named <code>transform-and-filter</code> for the full clarity of it.</p> | |
| <p>@codesections:</p> | |
| <blockquote> | |
| <p>IMO having this behavior differ between Blocks and Subs would be <em>highly</em> confusing.</p> | |
| </blockquote> | |
| <p>Not exactly. Think of <code>return</code> which is <code>routine</code>-scoped, so to say. The other point is that its semantics greatly differs from that of <code>next</code> and its "kins".</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XO6nV"> | |
| <div class='header'> | |
| <span class='author'>@patrickbkr</span> commented at <time datetime="2023-03-10T09:35:48Z">2023-03-10 09:35</time> | |
| </div> | |
| <div class='body'> | |
| <p>Just to throw in another code example that could potentially confuse me:</p> | |
| <pre><code>for @lists -> $x { | |
| $x.map({ process($_); next if !$_ } | |
| } | |
| </code></pre> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XSerm"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-03-10T20:57:05Z">2023-03-10 20:57</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>IMO having this behavior differ between Blocks and Subs would be highly confusing.</p> | |
| </blockquote> | |
| <p>Well, what can I say, I think this is <em>the whole point <code>Block</code>s exist in the first place</em> - to represent a piece of code with a scope that can be abstracted away while still providing inlining semantics. I can't see why this would be confusing - rather than <code>Sub</code> sometimes mimicking inlined behavior, by implicitly passing control flow back to the caller...</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5XS539"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-03-10T22:35:51Z">2023-03-10 22:35</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>The other point is that its semantics greatly differs from that of next and its "kins".</p> | |
| </blockquote> | |
| <p>Well, does it? Are they not all pragmatisms over structural code, sort of jumps that are at least guaranteed to be tied to certain control structures? I would say <code>return</code> and <code>next</code> are much more alike than <code>take</code> and <code>next</code> - I wonder if <code>take</code> is considered a control statement to begin with, it's not obvious at least. By semantics, it's much more like a callback.</p> | |
| <p>Also, food for thought: <a href="https://design.raku.org/S04.html#The_Relationship_of_Lexical_and_Dynamic_Scopes">linked part of synopsis</a> also says <code>For instance, next with a label will prefer to exit a loop lexotically</code> - and this is present in the current workings as well. <code>next BAR</code> isn't going to fall through anything but a bare <code>next</code> will - does this inconsistency seem as good as it did back when this language was going to be the new Perl?<br /> | |
| Also, if one does want the fallback behavior for a subroutine, it could still be made explicit, right? I have mentioned the idea of a pragma but at the end of the day, I wouldn't oppose something like <code>next *</code> either. The asterisk even plays nice with the symbolics of dynamic behavior.</p> | |
| <blockquote> | |
| <p><code>.map(&transform)</code> (or <code>.map: &transform</code>) seems to be way more self-explanatory than using a block with all the same logic transform provides</p> | |
| </blockquote> | |
| <p>I'm afraid this is a "let's agree to disagree" situation - that seems to me like a misuse of a subroutine. To me, it breaks the expectations of a subroutine - the expectation that a successfully executed subroutine won't interfere with the code of the caller - after all, that's part of the reason why I abstracted it away with a subroutine and not a <code>Block</code>, right?<br /> | |
| It can actually lead to weird thoughts: what return value does that subroutine even have? After all, <code>next</code> is not a callback, and indeed it terminates the control flow of the subroutine in the first place. Indeed, it behaves like an exception, without looking like one.</p> | |
| <blockquote> | |
| <p>Just to throw in another code example that could potentially confuse me:</p> | |
| <pre><code>for @lists -> $x { | |
| $x.map({ process($_); next if !$_ } | |
| } | |
| </code></pre> | |
| </blockquote> | |
| <p>@patrickbkr Could you please elaborate? Because here the <code>for</code> loop seems superfluous. So far, I haven't seen anybody questioning that <code>map</code>˙implies a loop, therefore all possible uses would hook up there, if anywhere.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="365"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/365"><span class='number'>365</span></a> - <span class='title'>Spectesting is a minefield</span></div> | |
| <div class='author'>[open]<span class='author'>@lizmat</span> opend this issue at <time datetime="2023-02-07T11:39:46Z">2023-02-07 11:39</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>Spectesting is a version minefield at the moment:</p> | |
| <pre><code>% rak '^use v6' t/spec --frequencies | |
| 1758:use v6; | |
| 30:use v6.c; | |
| 22:use v6.e.PREVIEW; | |
| 14:use v6.d; | |
| </code></pre> | |
| <p>A more precise:</p> | |
| <pre><code>% rak '{ "t/spec/$/" if .match(/^ <-[#]+[\S]>+ /) }' --/show-item-number t/spec/spectest.data | rak --files-from=- '^use v6' --frequencies | |
| 1332:use v6; | |
| 17:use v6.c; | |
| 14:use v6.e.PREVIEW; | |
| 9:use v6.d; | |
| </code></pre> | |
| <p>So this shows several issues that each may need a different problem solving issue.</p> | |
| <ol> | |
| <li> | |
| <p>there are <em>many</em> files in roast that are not actually being part of the spectest. Maybe these should be removed from roast or parked in a "archived" branch?</p> | |
| </li> | |
| <li> | |
| <p>The use of <code>use v6xxx</code> in test files. I think all of the <code>use v6</code> should be removed. They served a purpose in the days when there could be confusion with Perl, but nowadays that's not needed. And it's a potential problem.</p> | |
| </li> | |
| <li> | |
| <p>When we currently run a spectest, it is done with the <strong>CURRENT</strong> state of <code>v6.d</code>, which is <em>not</em> what the next version will be. We should have an easy way to run the spectests for a specific version of Raku, similar to what we're now doing with the RakuAST grammar (aka an environment variable)</p> | |
| </li> | |
| <li> | |
| <p>What the above doesn't show, is that roast is still using the old <code>.t</code> test extensions. I think these can and should be changed to use the new <code>.rakutest</code> extensions, as the 6.d release test files already live in a separate branch.</p> | |
| </li> | |
| </ol> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5UrUrl"> | |
| <div class='header'> | |
| <span class='author'>@JJ</span> commented at <time datetime="2023-02-07T11:46:42Z">2023-02-07 11:46</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>Spectesting is a version minefield at the moment:</p> | |
| <pre><code>% rak '^use v6' t/spec --frequencies | |
| 1758:use v6; | |
| 30:use v6.c; | |
| 22:use v6.e.PREVIEW; | |
| 14:use v6.d; | |
| </code></pre> | |
| <p>A more precise:</p> | |
| <pre><code>% rak '{ "t/spec/$/" if .match(/^ <-[#]+[\S]>+ /) }' --/show-item-number t/spec/spectest.data | rak --files-from=- '^use v6' --frequencies | |
| 1332:use v6; | |
| 17:use v6.c; | |
| 14:use v6.e.PREVIEW; | |
| 9:use v6.d; | |
| </code></pre> | |
| <p>So this shows several issues that each may need a different problem solving issue.</p> | |
| <pre><code>1. there are _many_ files in roast that are not actually being part of the spectest. Maybe these should be removed from roast or parked in a "archived" branch? | |
| </code></pre> | |
| </blockquote> | |
| <p>Wasn't there a file that stated which ones were actually used?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5Ur3hF"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-07T13:35:23Z">2023-02-07 13:35</time> | |
| </div> | |
| <div class='body'> | |
| <p>I think there is a bit of confusion about <code>.t</code> extension being "legacy" or "simply stable" - lately it seems that it's more the former, in which case the last point seems simple and straightforward.</p> | |
| <p>For the rest of the questions, I would refer to our discussion at #raku-dev on IRC: a readable form of a test helper like "skip this file if the version doesn't match a certain criterion" would probably help a lot. If I understand right, it would also mitigate the situation of datatest.spec quite a bit: the files themselves could say what version they belong to, which seems like a sane default for spectesting.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UsboG"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-02-07T15:09:51Z">2023-02-07 15:09</time> | |
| </div> | |
| <div class='body'> | |
| <p>Spectest must not be ran against a single version. Moreover, <em>each</em> test must have an explicit version. Not just <code>use v6</code> for which, I agree, there must be no place out there anymore. Otherwise, each particular test is designed for a particular language version. Vast majority of them are covering 6.c, apparently. It wouldn't be right to expect that something with no explicit <code>use v6.c</code>/<code>use v6.d</code> will continue to pass when 6.e becomes the default.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5Us4Ga"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-07T16:22:01Z">2023-02-07 16:22</time> | |
| </div> | |
| <div class='body'> | |
| <p>I think @vrurg made a good point, perhaps it would be more accurate to say: "one possible good point".</p> | |
| <p>What didn't seem to be clear in the short discussion on the IRC is how the two-dimensional nature of the question is solved:</p> | |
| <ul> | |
| <li>a spectest belongs to a set of versions of the language (I'm saying it this way because we need to account for deprecations and removals as well!)</li> | |
| <li>an actual compiler/runtime can implement and run different versions of the language</li> | |
| </ul> | |
| <p>So in theory, this could be an N:M situation - however, only those combinations make sense where the used runtime version is matched by the spectest, so it's much closer to a linear situation. It's worth thinking about the idea of @lizmat as well, namely that the used language version could be set directly, rather than always coming from the source.</p> | |
| <p>If I remember correctly, the topic of removal came up recently, as something that is "possible in theory but a hassle to actually achieve". Anyway, if there may be breaking changes (other than extensions) in the future, it would be good to at least give the specs the chance to describe that phenomenon.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5Us5oL"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-02-07T16:26:08Z">2023-02-07 16:26</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <ul> | |
| <li>an actual compiler/runtime can implement and run different versions of the language</li> | |
| </ul> | |
| </blockquote> | |
| <p>What??? It does, mind me...</p> | |
| <p>For the rest of version-related stuff: that's why there are many individual files. Each one can test a specific aspect using a concrete <code>use v6.x</code> pragma. If something is deprecated in 6.e – test it in a 6.e compunit. Period.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UtHnJ"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-07T17:04:00Z">2023-02-07 17:04</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>What??? I does, mind me...</p> | |
| </blockquote> | |
| <p>Not sure what this even means but it's hard to imagine it was anything constructive...</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UtXkJ"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-07T17:39:40Z">2023-02-07 17:39</time> | |
| </div> | |
| <div class='body'> | |
| <p>Anyway, what still seems to be missing: what about those spectests that <strong>aren't meant to be run, given a newer version, because their right outcome on the newer version is that they fail</strong>? Part of the reason I was trying to recite the "removal topic" (that apparently wasn't as interesting as the existence of compiler versions...) - if something is removed, the whole "language versions are scopes around each other" approach breaks down, or at least needs to be hacked. It would be good if at least the specification could deal with this situation in a clear way, period. And this is where both</p> | |
| <ul> | |
| <li>the separation of the spectest version and used runtime version</li> | |
| <li>and the "skip/fail/pass this test depending on language version in use" | |
| would turn relevant and useful.</li> | |
| </ul> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UusvG"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-02-07T22:09:37Z">2023-02-07 22:09</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>Not sure what this even means</p> | |
| </blockquote> | |
| <p>It was a mistype. "It does", not "I does".</p> | |
| <blockquote> | |
| <p>what about those spectests that aren't meant to be run, given a newer version, because their right outcome on the newer version is that they fail?</p> | |
| </blockquote> | |
| <p>Not sure I get you here, but they're supposed to be run with corresponding <code>use v6.x</code>. What is wrong about this statement?</p> | |
| <p>I wonder if you understand the meaning of <code>use v6.x</code> pragma.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UvUwx"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-08T00:22:59Z">2023-02-08 00:22</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>I wonder if you understand the meaning of use v6.x pragma.</p> | |
| </blockquote> | |
| <p>As much as you explained during the 2021 conference, I guess.</p> | |
| <p>I'm starting to think that we have completely different interpretations of what a run of a spectest means, what the output is. Frankly, the way liz talked about it is much easier for me to relate to.</p> | |
| <p>As I'm taking right now, a "spectest a la vrurg" tests the compiler, regardless of language version, in one run: version c stuff is guaranteed to work in version c mode, version d stuff is guaranteed to work in version d mode and so on. This test treats "<em>introduced</em> in language version c (and may belong to others as well!)" as "belongs to language version c (and only that)". This can only be sound if it's postulated that all language versions MUST include all the previous versions, with a hard stop - otherwise how could we be sure that the same compiler running in e.g "d" mode can still pass tests introduced in language version "c"?</p> | |
| <p>Now, this sort of spectesting makes actual removal of functionality impossible because in order to implement the language version that removed, say, a dozen of public functions and two types, one would still need to implement those versions that introduced and contained them - or else it couldn't even pass the tests that you are proposing, in the first place.</p> | |
| <p>This doesn't follow from the semantics of "use v6.x" in theory, does it? This "language version hierarchy" is more a pragma than a specification demand, right? Okay, that's how it is done in Rakudo, and one wouldn't want to write the same tests for different language versions either, when most of the time there are just no changes - however, the latter is mitigated by a combination of what @lizmat and I proposed (i.e "version under test" coming from a compiler setting, and all tests individually can check the version if different behaviors are needed).</p> | |
| <p>PS: you could write a little longer than three lines, and please keep the bantering bits (like that "compiler versions, no shit" crap) for yourself.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UzFYF"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-02-08T14:23:29Z">2023-02-08 14:23</time> | |
| </div> | |
| <div class='body'> | |
| <p>I haven't read past "<x> version mode". Give yourself an answer what that does mean. Then think of backward compatibility we provide – and you'd be surprised! I just have nothing more to add here.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UzM8o"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-08T14:44:12Z">2023-02-08 14:44</time> | |
| </div> | |
| <div class='body'> | |
| <p>Thank you for the constructivity again - the only question at this point is who that "we" might be.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UzZx3"> | |
| <div class='header'> | |
| <span class='author'>@niner</span> commented at <time datetime="2023-02-08T15:18:18Z">2023-02-08 15:18</time> | |
| </div> | |
| <div class='body'> | |
| <p>@vrurg there's actually one thing missing from the current spec test suite and the way we use it: | |
| Let's assume there is a test that tests that in Raku <code>1 + 1</code> is indeed 2. Since <code>&infix:sym<+></code> was already part of the first version, that test uses <code>use v6.c;</code>. There is however no test that ensures that this still holds in a comp unit that has a <code>use v6.d;</code> at the top. I.e. we only test that the intentional changes we make in later language versions are present, but don't test the negative: that there are no unintentional changes. Thus a compiler would be free to provide a working version of <code>+</code> in v6.c mode, but even completely remove it from 6.d.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UzfRH"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-02-08T15:27:23Z">2023-02-08 15:27</time> | |
| </div> | |
| <div class='body'> | |
| <p>What constructiveness do you expect? If I tell you that code written 7 years ago with <code>use v6.c</code> we expect to be ran today with, perhaps, just a couple of changes (some code rely on buggy behaviors), if that code used nothing beyond included into the roast back then or today – what would it mean to you? Let me guess, you knew about this paradigm.</p> | |
| <p>If we think further then it becomes clear that the compiler right now supports all language versions: 6.c, 6.d, and the upcoming 6.e. It means that one could <code>use</code> a <code>6.e</code> module from their <code>6.d</code> code and it will work. Perhaps not semantically (but it might happen even when the same language version compunits interact), but technically it will. So, all these language versions are in the compiler now.</p> | |
| <p>Then what is that <code>version mode</code> term means? Your statements are based on the term which has no meaning. How could I respond to something that's meaningless in its premise? The only thing which do make sense to me is a test for a language version. A test with <code>use 6.e</code> tests if something works for 6.e and nothing else. If I want to see that something works equally well for all language versions – I would take care to have the code ran under each version individually. It's just a technical matter and nothing else.</p> | |
| <p>The situation is like this: a compiler to claim full Raku support has to pass the roast and support all three language versions.</p> | |
| <p>If we speak about removal of tests then this is something separate and unrelated to versioning.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UzmKH"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-02-08T15:37:43Z">2023-02-08 15:37</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>Thus a compiler would be free to provide a working version of <code>+</code> in v6.c mode, but even completely remove it from 6.d.</p> | |
| </blockquote> | |
| <p>Just about time! :) I've mentioned this case above. It's a pure technical matter of how to implement that kind of testing. For the moment the cleanest way is to <code>EVAL</code> from within individual test files, like, for example:</p> | |
| <pre><code class="language-raku">use v6.e; | |
| EVALFILE "./must-work-everywhere.t"; | |
| </code></pre> | |
| <p>Or to use <code>is-run</code> test. See, for example, <code>S11-modules/versioning.t</code>. I always wanted <code>EVAL</code> to let its compunit use own language version, but never got there due to lack of time.</p> | |
| <p>And, of course, the option of letting the compiler to use different <em>default</em> language version is on the table too.</p> | |
| <p>But then, again, these are pure technical matters of how to get a task solved. I don't see a problem here.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5Uz_L7"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-08T16:38:59Z">2023-02-08 16:38</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>The situation is like this: a compiler to claim full Raku support has to pass the roast and support all three language versions.</p> | |
| </blockquote> | |
| <p>YES, thank you very much, this is the <strong>presumption</strong> that I also mentioned, have you bothered to read the comment, rather than boasting with not having read it:</p> | |
| <blockquote> | |
| <p>This can only be sound if it's postulated that all language versions MUST include all the previous versions, with a hard stop</p> | |
| </blockquote> | |
| <p>Let's keep it simple: where is this interpretation of the specification written down, as normative? All Raku compilers should be able to run all Raku code ever written, no matter how obsolete? This sounds debatable - but more importantly, it's not obvious whatsoever. It should be written down at a visible place, rather than deducible from an upset one-liner response.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5U0F3l"> | |
| <div class='header'> | |
| <span class='author'>@niner</span> commented at <time datetime="2023-02-08T16:57:40Z">2023-02-08 16:57</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <blockquote> | |
| <p>This can only be sound if it's postulated that all language versions MUST | |
| include all the previous versions, with a hard stop | |
| Let's keep it simple: where is this interpretation of the specification | |
| written down, as normative? All Raku compilers should be able to run all | |
| Raku code ever written, no matter how obsolete?</p> | |
| </blockquote> | |
| </blockquote> | |
| <p>I don't think this has ever been written down anywhere. The reason however is | |
| not that we didn't commit to it. Rather the opposite: maintaining eternal | |
| backwards compatibility is one of those values that sit so deep, that no one | |
| felt the need to codify it. It was pretty much a given, i.e. a common | |
| understanding and underlies many of the design principles. It's for example | |
| the reason why so many things are lexically scoped in Raku. It's one of the | |
| values we inherited from the Perl community. The only difference being that we | |
| tried to make maintaining that backwards compatibility less painful.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VCrCk"> | |
| <div class='header'> | |
| <span class='author'>@usev6</span> commented at <time datetime="2023-02-11T13:07:26Z">2023-02-11 13:07</time> | |
| </div> | |
| <div class='body'> | |
| <p>Back in 2015 @FROGGS and me used a hackathon to work on adding the ability to fudge tests for a specific version of Perl 6 (as it was called then). The idea was to be able to add a version to one or more tests or to a block with tests like this:</p> | |
| <pre><code>#?v6.0.0 | |
| is 2+2, 4; | |
| #?v6.0.5+ | |
| { | |
| is "Life, the Universe, and Everything".WHY, 42; | |
| is 42.WHAT, Int, 'some reason'; | |
| } | |
| #?v6.0.0..v6.0.2 2 | |
| is 2-2, 0; | |
| is 3*4, 12; | |
| #?v6.0.1..* | |
| is 2-2, 0; | |
| is 3*4, 12; | |
| </code></pre> | |
| <p>The above is taken from an old branch that still lives in the roast repo: https://github.com/Raku/roast/compare/master...fudge</p> | |
| <p>I wonder if this idea could still make sense (maybe in a different form).</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VCrbk"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-02-11T13:15:01Z">2023-02-11 13:15</time> | |
| </div> | |
| <div class='body'> | |
| <p>Interesting... hmmm</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VC2UZ"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-02-11T16:06:31Z">2023-02-11 16:06</time> | |
| </div> | |
| <div class='body'> | |
| <p>I would propose the following:</p> | |
| <ol> | |
| <li>remove all "use v6" specifications: it is clearly that they are meant to indicate Raku rather than Perl, and thus indicate tests that should run ok on <em>any</em> Raku version, including the current development version.</li> | |
| <li>check out whether the files in roast that have a specific version specification (6.c or 6.d) really indicate they need to be run with that version. If not, then remove those as well.</li> | |
| <li>Implement an environment variable <code>RAKU_DEFAULT_LANGUAGE_VERSION=</code> that would indicate the language version with which Raku should run <strong>IF</strong> there is no specific <code>use v6.x</code> mention.</li> | |
| </ol> | |
| <p>This should allow us to run all current non-version specific test files with <code>v6.e.PREVIEW</code> without needing to make any (further) changes to roast.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VC61N"> | |
| <div class='header'> | |
| <span class='author'>@niner</span> commented at <time datetime="2023-02-11T17:12:37Z">2023-02-11 17:12</time> | |
| </div> | |
| <div class='body'> | |
| <p>I don't really like making changes to rakudo just to avoid making changes for | |
| this single user. Instead of that environment variable, you could also have | |
| the the Makefile copy the files and prepend the appropriate use v6 statement | |
| (except they already have one). After all make is a really good tool when you | |
| need to propagate changes of a source to a target.</p> | |
| <p>This would have the advantage of having all those tests be part of a single | |
| test run. We could have this full tests run as a different target akin to | |
| stresstest.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VC65M"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-02-11T17:13:52Z">2023-02-11 17:13</time> | |
| </div> | |
| <div class='body'> | |
| <p>Don't you think such an environment variable would have more general applications?</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VC7wR"> | |
| <div class='header'> | |
| <span class='author'>@niner</span> commented at <time datetime="2023-02-11T17:29:57Z">2023-02-11 17:29</time> | |
| </div> | |
| <div class='body'> | |
| <p>In fact I don't :) Can't think of any</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VDCVc"> | |
| <div class='header'> | |
| <span class='author'>@usev6</span> commented at <time datetime="2023-02-11T19:26:52Z">2023-02-11 19:26</time> | |
| </div> | |
| <div class='body'> | |
| <p>Basically I'm agreeing with @vrurg (from far above):</p> | |
| <blockquote> | |
| <p>Moreover, <em>each</em> test must have an explicit version.</p> | |
| </blockquote> | |
| <p>Since roast <em>defines</em> Raku, it has to be clear, which test is part of a specific version of Raku.</p> | |
| <p>I wonder if this could -- at least in theory -- be achieved by "just"</p> | |
| <ol> | |
| <li>keeping different branches of roast (we already have <a href="https://github.com/Raku/roast/tree/6.c">6.c</a>, <a href="https://github.com/Raku/roast/tree/6.c-errata">6.c-errata</a> and <a href="https://github.com/Raku/roast/tree/6.d-errata">6.d-errata</a>),</li> | |
| <li>removing all version annotations from test files</li> | |
| <li>running spectest for a specific version (a specific branch) with a mechanism like @niner suggested (using <code>make</code> to prepend the appropriate statement before actually running the tests)</li> | |
| </ol> | |
| <p>To me this sounds like a clean separation of concerns. And in theory the released versions of Raku should be immutable, so there shouldn't be much need to adjust test files for old versions.</p> | |
| <p>The most obvious disadvantage would probably be the need to run different spectests (for all versions -- or probably for the corresponding branch <code>6.?-errata</code>). But if we want to keep backwards compatibility for Rakudo, maybe that's the price? (As a thought experiment, there could be a different implementation that just aims to be compatible with the current version.)</p> | |
| <p>I'm not sure it this idea really makes sense, but the idea came back to my mind each time I looked at the comments in here. So I thought I should mention it ...</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VDE1X"> | |
| <div class='header'> | |
| <span class='author'>@2colours</span> commented at <time datetime="2023-02-11T20:23:54Z">2023-02-11 20:23</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>As a thought experiment, there could be a different implementation that just aims to be compatible with the current version.</p> | |
| </blockquote> | |
| <p>This is what I thought, too, until the following statement happened:</p> | |
| <blockquote> | |
| <p>The situation is like this: a compiler to claim full Raku support has to pass the roast and support all three language versions.</p> | |
| </blockquote> | |
| <p>I think it's really about time to, well, specify the specification in this regard. When we talked about this with lizmat, the concept of "supported version" also came up - supported, as in the current language specification supports it, and not as in the compiler supports it; the compiler <strong>must</strong> support it. (Honestly, all of this sounds vague and fragile, without any precedent of removing a version from support.)</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VgVLW"> | |
| <div class='header'> | |
| <span class='author'>@lizmat</span> commented at <time datetime="2023-02-17T11:58:17Z">2023-02-17 11:58</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>running spectest for a specific version (a specific branch) with a mechanism like @niner suggested (using make to prepend the appropriate statement before actually running the tests)</p> | |
| </blockquote> | |
| <p>Although this would be nice for running spectests, it would make debugging issues in a specific test file <em>much</em> harder and error prone. The alternatives are:</p> | |
| <ul> | |
| <li>adding a <code>use v6.x</code> manually while testing (and then forgetting to remove it)</li> | |
| <li>using a make file for individual testing as well, which may hide issues</li> | |
| </ul> | |
| <p>Personally, if a test file is fudged, I much rather run the <code>rakudo.moar</code> version directly, optionally tweaking that, than going through a fudging process <em>every time</em>.</p> | |
| <p>Anyways, that's why I think having an environment variable to indicate the language version to be used in absence of a specific indication in a file, would be preferable.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5Vhryr"> | |
| <div class='header'> | |
| <span class='author'>@coke</span> commented at <time datetime="2023-02-17T16:39:00Z">2023-02-17 16:39</time> | |
| </div> | |
| <div class='body'> | |
| <p>Another wrinkle - spec tests were updated to work with Unicode 15 in January - but this breaks the spec test runs for v6.c when using the 2022.12, which only has Unicode 13 support. (sjn++ for reporting)</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VhtlT"> | |
| <div class='header'> | |
| <span class='author'>@sjn</span> commented at <time datetime="2023-02-17T16:44:35Z">2023-02-17 16:44</time> | |
| </div> | |
| <div class='body'> | |
| <p>For me, it would be nice with a visible warning (and pause) if I somehow run the spectests on code that is significantly older than the tests expect – perhaps noting that tests should be expected to fail, since they may be testing features that haven't been implemented in the currently-checked-out (old) code.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5VmlMx"> | |
| <div class='header'> | |
| <span class='author'>@vrurg</span> commented at <time datetime="2023-02-20T01:36:09Z">2023-02-20 01:36</time> | |
| </div> | |
| <div class='body'> | |
| <p>Can't get too deep into this, but so far I like the idea of fudging the most. So, tests which are not explicitly designed for a particular language version would have <code>#?raku-version</code> line as the start. And that is all we need for reliably testing under various <code>use v6.x</code> pragmas.</p> | |
| </div> | |
| </div> | |
| </div> | |
| </div> | |
| <div class='issue' id="364"> | |
| <div class='header'> | |
| <div class='title'><a href="https://github.com/Raku/problem-solving/issues/364"><span class='number'>364</span></a> - <span class='title'>Supply blocks may reorder flow of execution</span></div> | |
| <div class='author'>[open]<span class='author'>@patrickbkr</span> opend this issue at <time datetime="2023-01-27T13:33:52Z">2023-01-27 13:33</time></div> | |
| </div> | |
| <div class='body'> | |
| <p>This is a follow up of | |
| https://github.com/rakudo/rakudo/issues/5141 | |
| and | |
| https://github.com/rakudo/rakudo/pull/5158</p> | |
| <p>Consider the following piece of code:</p> | |
| <pre><code>my $p = Promise.new; | |
| my $s1 = supply { | |
| await $p; | |
| say "processing whenever" | |
| }; | |
| react { | |
| whenever $s1 { } | |
| $p.keep; | |
| say "end of react block"; | |
| } | |
| </code></pre> | |
| <p>That piece of code prints</p> | |
| <pre><code>end of react block | |
| processing whenever | |
| </code></pre> | |
| <p>This is unexpected. The order seems reversed. Why is this so?</p> | |
| <p>By default whenevers tap their supply instantly and as a result run the supply block they are connected to. This has a potential for deadlocking when that supply block (or one nested via more <code>whenevers</code>) contains an <code>emit</code> as the <code>emit</code> will call the whenever block of the original supply, but by definition only a single execution branch is allowed in a supply block at any time. | |
| Possibly (I'm not sure about that) there are other scenarios posing similar deadlock issues without recursion being involved.</p> | |
| <p>The currently implemented solution for this deadlock problem in https://github.com/rakudo/rakudo/commit/26a9c313297a21c11ac30f02349497822686f507 and https://github.com/rakudo/rakudo/commit/547839200a772e26ea164e9d1fd8c9cd4a5c2d9f works as follows. When - in the setup phase, during the processing of a whenever tapping - an await happens (be it a protect, acquire, lock or plain await) a continuation starting at the root of the whenever tapping is taken. Only after the supply block itself finished running the continuation is resumed. So the order in which the code is executed is dependent on whether there is any locking going on in code tapped by the whenever.</p> | |
| <p>This behavior is difficult for a unknowing programmer to follow. Even a programmer knowing about this behavior will potentially have a hard time knowing whether there is a lock somewhere in the tapped code that could cause this reordering of code. This is a case of action-at-a-distance.</p> | |
| <p>Also there still is a possibility of the code deadlocking left. That's detailed in https://github.com/rakudo/rakudo/issues/5141. I consider that a problem separate from this issue.</p> | |
| </div> | |
| <div class='comments'> | |
| <div class='comment' id="IC_kwDOCkcG5c5T1fC1"> | |
| <div class='header'> | |
| <span class='author'>@patrickbkr</span> commented at <time datetime="2023-01-27T13:45:25Z">2023-01-27 13:45</time> | |
| </div> | |
| <div class='body'> | |
| <p>In https://github.com/rakudo/rakudo/pull/5158 I tried replacing the continuation based solution strategy with a much simpler approach of just always executing whenever tapping <em>after</em> the supply block itself has run. That behavior is a lot easier to understand.</p> | |
| <p>It does contradict the syntax though. Currently whenever blocks can be placed anywhere in a supply block, which strongly suggests that they are processed where they are placed. Only executing them after having processed the supply block is thus highly counterintuitive.</p> | |
| <p>Additionally it makes code like the following impossible to write:</p> | |
| <pre><code># Simplified from t/spec/S17-promise/nonblocking-await.t | |
| my $started = Promise.new; | |
| my $ok = start react { | |
| whenever IO::Socket::Async.listen($s-address, $port) -> $conn { | |
| whenever $conn.Supply(:bin) -> $buf { | |
| await $conn.write: $buf; | |
| $conn.close; | |
| } | |
| } | |
| $started.keep; | |
| } | |
| </code></pre> | |
| <p>In that piece of code a <code>Promise</code> is used to track the set up of the <code>react</code> block. When delaying whenever tapping <em>after</em> the processing of the react block, then that <code>$started.keep</code> happens too early.</p> | |
| <p>I thus consider https://github.com/rakudo/rakudo/pull/5158 a non-solution. At the moment I have run out of ideas of how to solve this.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5T-5ed"> | |
| <div class='header'> | |
| <span class='author'>@jnthn</span> commented at <time datetime="2023-01-30T17:08:18Z">2023-01-30 17:08</time> | |
| </div> | |
| <div class='body'> | |
| <blockquote> | |
| <p>This is unexpected. The order seems reversed. Why is this so?</p> | |
| </blockquote> | |
| <p>A <code>supply</code> block (and thus <code>react</code>) provides concurrency control by enforcing one-message-at-a-time semantics: that is, we must completely process a message (reach the end of the <code>whenever</code> block) before we process the next one. An <code>await</code> inside of a <code>whenever</code> block thus prevents execution of any other <code>whenever</code> block starting until the <code>await</code>ed event completes. (If one wants more concurrency, the answer is to instead use a nested <code>whenever</code>; were <code>await</code> to have different semantics then there'd not be a means to achieve back pressure).</p> | |
| <p>The body of a <code>supply</code> or <code>react</code> block itself is much like an OO constructor: just as we expect the constructor to complete before we have a complete object ready to receive method calls, we expect the setup phase of the <code>supply</code> or <code>react</code> block to run to completion before it processes any other messages.</p> | |
| <p>Thus, the behavior in that example seems as intended.</p> | |
| <blockquote> | |
| <p>Currently whenever blocks can be placed anywhere in a supply block, which strongly suggests that they are processed where they are placed.</p> | |
| </blockquote> | |
| <p>Yes, it's important for correctness that the subscription is established right away.</p> | |
| <blockquote> | |
| <p>The currently implemented solution for this deadlock problem in https://github.com/rakudo/rakudo/commit/26a9c313297a21c11ac30f02349497822686f507 and https://github.com/rakudo/rakudo/commit/547839200a772e26ea164e9d1fd8c9cd4a5c2d9f works as follows. When - in the setup phase, during the processing of a whenever tapping - an await happens (be it a protect, acquire, lock or plain await) a continuation starting at the root of the whenever tapping is taken. Only after the supply block itself finished running the continuation is resumed. So the order in which the code is executed is dependent on whether there is any locking going on in code tapped by the whenever.</p> | |
| <p>This behavior is difficult for a unknowing programmer to follow. Even a programmer knowing about this behavior will potentially have a hard time knowing whether there is a lock somewhere in the tapped code that could cause this reordering of code. This is a case of action-at-a-distance.</p> | |
| </blockquote> | |
| <p>The core of the issue really is that <code>supply</code> and <code>react</code> are primarily a tool for managing existing concurrency, rather than as a means to introduce concurrency. However, in an attempt to DWIM, we try to permit a <code>supply</code> to immediately <code>emit</code> in its body, rather than just subscribe to other underlying sources and <code>emit</code> based upon events from those. The <code>BlockAddWheneverAwaiter</code> approach, as noted in https://github.com/rakudo/rakudo/issues/5141, seems to have shortcomings when one mixes <code>supply</code> blocks with use of a <code>Supplier</code>, for example.</p> | |
| <p>I picked the continuation juggling approach to resolve the conflicts over the alternative of scheduling the continuations using the normal thread pool scheduler and letting the standard <code>await</code> mechanism take over, primarily on the basis that if <code>supply</code> blocks really were going to have to get into the business of introducing concurrency, then at least they should avoiding introducing threading too. Perhaps, however, the latter would have been the lesser evil; I'm curious if that would solve the problem at hand here and be more robust generally.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5UC8N9"> | |
| <div class='header'> | |
| <span class='author'>@patrickbkr</span> commented at <time datetime="2023-01-31T09:48:40Z">2023-01-31 09:48</time> | |
| </div> | |
| <div class='body'> | |
| <p>Thanks for your input!</p> | |
| <blockquote> | |
| <blockquote> | |
| <p>This is unexpected. The order seems reversed. Why is this so?</p> | |
| </blockquote> | |
| <p>A <code>supply</code> block (and thus <code>react</code>) provides concurrency control by enforcing one-message-at-a-time semantics: that is, we must completely process a message (reach the end of the <code>whenever</code> block) before we process the next one. An <code>await</code> inside of a <code>whenever</code> block thus prevents execution of any other <code>whenever</code> block starting until the <code>await</code>ed event completes. (If one wants more concurrency, the answer is to instead use a nested <code>whenever</code>; were <code>await</code> to have different semantics then there'd not be a means to achieve back pressure).</p> | |
| </blockquote> | |
| <p>That question was meant as the heading for the following paragraph. But thanks for explaining anyways! ;-)</p> | |
| <blockquote> | |
| <p>Thus, the behavior in that example seems as intended.</p> | |
| </blockquote> | |
| <p>Which example are you refering to? The one in the first post does trigger the await magic and manages to change the order in which the supply block and tapping are executed.</p> | |
| <blockquote> | |
| <blockquote> | |
| <p>Currently whenever blocks can be placed anywhere in a supply block, which strongly suggests that they are processed where they are placed.</p> | |
| </blockquote> | |
| <p>Yes, it's important for correctness that the subscription is established right away.</p> | |
| </blockquote> | |
| <p>I agree.</p> | |
| <blockquote> | |
| <p>The core of the issue really is that <code>supply</code> and <code>react</code> are primarily a tool for managing existing concurrency, rather than as a means to introduce concurrency. However, in an attempt to DWIM, we try to permit a <code>supply</code> to immediately <code>emit</code> in its body, rather than just subscribe to other underlying sources and <code>emit</code> based upon events from those. The <code>BlockAddWheneverAwaiter</code> approach, as noted in <a href="https://github.com/rakudo/rakudo/issues/5141">rakudo/rakudo#5141</a>, seems to have shortcomings when one mixes <code>supply</code> blocks with use of a <code>Supplier</code>, for example.</p> | |
| <p>I picked the continuation juggling approach to resolve the conflicts over the alternative of scheduling the continuations using the normal thread pool scheduler and letting the standard <code>await</code> mechanism take over, primarily on the basis that if <code>supply</code> blocks really were going to have to get into the business of introducing concurrency, then at least they should avoiding introducing threading too. Perhaps, however, the latter would have been the lesser evil</p> | |
| </blockquote> | |
| <p>I can try implementing that. So that I get it right: I keep the BAWA (BlockAddWheneverAwaiter), but instead of putting the continuations in a list for later processing, I'd just instantly schedule the continuations on the ThreadPoolScheduler (<em>not</em> on the outer <code>$*AWAITER</code>, which would be a BlockingAwaiter and thus block the BAWA itself).</p> | |
| <blockquote> | |
| <p>I'm curious if that would solve the problem at hand here and be more robust generally.</p> | |
| </blockquote> | |
| <p>I guess that depends on whether we want to be pedantic. If the aspiration is to never have surprising order reversals, then queuing things on the thread pool isn't a step forward. I am confident though that having things in the thread pool will solve https://github.com/rakudo/rakudo/issues/5141 (the issue that made me explore the supply / whenever implementation in the first place). In that deadlock situation a continuation earlier in the list blocks on a lock a later continuation holds. But there is no "A waits on B, B waits on A" situation. So if the other continuations would be allowed to run, things would work out.</p> | |
| <p>It still feels wrong to give locks not being involved in the supply setup the same treatment. I think I'll start another experiment: I'll remove the entirety of the BlockAddWheneverAwaiter and see if the queue-on-recursion logic implemented in https://github.com/rakudo/rakudo/commit/547839200a772e26ea164e9d1fd8c9cd4a5c2d9f suffices to prevent deadlocks on construction. I think I have not yet seen a situation where a lock we need to resolve during construction has <em>not</em> been a recursion lock.</p> | |
| </div> | |
| </div> | |
| <div class='comment' id="IC_kwDOCkcG5c5Uc1Fu"> | |
| <div class='header'> | |
| <span class='author'>@patrickbkr</span> commented at <time datetime="2023-02-04T20:30:01Z">2023-02-04 20:30</time> | |
| </div> | |
| <div class='body'> | |
| <p>Just removing the BlockAddWheneverAwaiter logic basically means having recursing emits during supply construction instantly return and thus killing back-pressure. All tests and spectests pass except for a single test:</p> | |
| <pre><code>tap-ok Supply.zip( | |
| Supply.from-list("a".."e"), | |
| Supply.from-list("f".."k"), | |
| Supply.from-list("l".."p") | |
| ), | |
| [<a f l>,<b g m>,<c h n>,<d i o>,<e j p>], | |
| "zipping with 3 supplies works"; | |
| </code></pre> | |