_

_ (pronounced "lowbar") is a meta utility package for the Raku programming language. Being meta means that _ is comprised of independent sub-packages, each with their own documentation and tests. Being a utility package means that each of _'s sub-packages is provides some helper functionality — the type of functionality that, if it weren't in _, might live in a ./utils directory or in a tiny module that would bloat your dependency tree.

_'s goal is to provide you with utilities that are correct by inspection: that is, with code so simple that you can look at it and tell that it is correct. To achieve this goal, each _ sub-package will always be:

1. A single file (not counting tests/docs)
2. with zero dependencies (not counting other _ files or core modules)
3. with no more than 70 lines

This means that you or any other Raku programmer can evaluate any _ sub-package by opening a single file and reading a page of code. If you have questions or concerns about any _ sub-packages, I encourage you to do just that.

However, just because you can doesn't mean that you must: each _ sub-package is also documented in the accompanying README file located in its directory. Similarly, as valuable as "proof by inspection" my be, it's no substitute for tests. (Recall Knuth's warning to a colleague: "Beware of bugs in the above code; I have only proved it correct, not tried it."). Accordingly, each sub-package also has its own tests.

NOTE: Once _ has a production release, it will guarantee backwards compatibility. However, _ is currently beta software and does not promise backwards compatibility.

For more information about _'s goals and plans, please see the announcement blog post.

Installation

Install _ with $ zef install _:auth<github:codesections>.

Usage

To use _, you can import all of _'s non-test functions with use _, all of its test functions with use _ :Test, or both sets with use _ :ALL. This style of importing is intended for prototyping/experimentation when you are not which _ functions you may use.

Alternatively, you can selectively import exported functions (or other symbols) by passing their name to the use _ statement. For example, here's how you could import the &dbg function from the Print::Dbg sub-package and the &wrap-words function from the Text::Wrap sub-package using a fully-qualified use statement:

use _:ver<0.0.1>:auth<fez:codesections> <&dbg &wrap-words>;

This style of imports is intended for later in the development process/when you want to pin to an exact _ version and ensure that _ does not cause unexpected name clashes.

sub-packages

_ includes the following sub-packages. You can find more information about each one in the README file in its directory.

• Pattern::Match - pattern match with Raku's full destructuring from signature binding. README; src

• Print::Dbg - better print-line debugging than .raku or dd. README; src

• Self::Recursion - provides &_ as an alias for &?ROUTINE for anonymous self-recursion. README; src

• Text::Paragraphs - provides a paragraphs function similar to lines except that it breaks text up into paragraphs rather than lines. README; src

• Text::Wrap - provides a wrap-words function that wraps text to a specified line length (a better alternative to Rakudo's private naive-word-wrapper). README; src

• Test::Doctest::Markdown - tests Raku code blocks from READMEs or other markdown files and, optionally, compares their output to # OUTPUT: «…» comments. README; src

• Test::Fluent - A thin wrapper over Test that lets you describe tests in declarator comments (#|) and to more fluently chain test methods.README; src

Contributing

You would be welcome to contribute to _'s development; you can help in any of the following ways:

• by opening an issue
  • to report a section of the documentation that you found unclear
  • to report a bug in an existing sub-package
  • to suggest a feature for an existing sub-package
  • to suggest a new sub-package
  • to discuss future plans for _/and of the questions from the announcement post
• by opening a pull request
  • to improve the documentation
  • to add tests for an exiting sub-package
  • to fix a bug
  • to add a feature for a sub-package
  • to add a new sub-package

(For the last two, it'd probably be a good idea to mention your idea in an issue first; that's not a requirement, but it might prevent you spending time of a feature that isn't a great fit for _).

All _ contributors agree to abide by the Raku Code of Conduct.

Roadmap

My initial goal for _ is to get it to a 1.0.0/stable release as soon as possible in order to provide guarantees regarding backwards compatibility. To that end, my priority is to decide what _'s overall approach to versioning will be and to implement that system. The announcement blog post has additional details about the versioning considerations.

Once _ has a stable release, the plan is to focus on growing _ to address other needs in the Raku ecosystem.