Using modules to load a group of related functions - raku

I want to use Raku Modules to group some functions, I often use. Because these functions are all loosely coupled, I don't like to add them in a class.
I like the idea of use, where you can select, which functions should be imported, but I don't like it, that the functions, which are imported are then stored in the global namespace.
For example if I have a file my_util.pm6:
#content of my_util.pm6
unit module my_util;
our sub greet($who) is export(:greet) {
say $who;
}
sub greet2($who) is export(:greet2) {
say $who;
}
sub greet3($who) is export(:greet3) {
say $who;
}
and a file test.p6:
#!/usr/bin/perl6
#content of test.p6
use v6.c;
use lib '.';
use my_util :greet2;
greet("Bob"); #should not work (because no namespace given) and also doesn't work
greet2("Bob"); #should not work (because no namespace given) but actually works
greet3("Bob"); #should not work (because no namespace given) and also doesn't work
my_util::greet("Alice"); #works, but should not work (because it is not imported)
my_util::greet2("Alice"); #should work, but doesn't work
my_util::greet3("Alice"); #should not work (because it is not imported) and also doesn't work
I would like to call all functions via my_util::greet() and not via greet() only.
The function greet() defined in my_util.pm6 comes very close to my requirements, but because it is defined as our, it is always imported. What I like is the possibility, to select which functions should be imported and it should be possible to leave it in the namespace defined by the module (i.e. it doesn't pollute the global namespace)
Does anyone know, how I can achieve this?

To clear up some potential confusion...
Lexical scopes and package symbol tables are different things.
my adds a symbol to the current lexical scope.
our adds a symbol to the current lexical scope, and to the public symbol table of the current package.
use copies the requested symbols into the current lexical scope.
That's called "importing".
The :: separator does a package lookup – i.e. foo::greet looks up the symbol greet in the public symbol table of package foo.
This doesn't involve any "importing".
As for what you want to achieve...
The public symbol table of a package is the same no matter where it is referenced from... There is no mechanism for making individual symbols in it visible from different scopes.
You could make the colons part of the actual names of the subroutines...
sub foo::greet($who) is export(:greet) { say "Hello, $who!" }
# This subroutine is now literally called "foo::greet".
...but then you can't call it in the normal way anymore (because the parser would interpret that as rule 4 above), so you would have to use the clunky "indirect lexical lookup" syntax, which is obviously not what you want:
foo::greet "Sam"; # Could not find symbol '&greet'
::<&foo::greet>( "Sam" ); # Hello, Sam!
So, your best bet would be to either...
Declare the subroutines with our, and live with the fact that all of them can be accessed from all scopes that use the module.
Or:
Add the common prefix directly to the subroutine names, but using an unproblematic separator (such as the dash), and then import them normally:
unit module foo;
sub foo-greet($who) is export(:greet) { ... }
sub foo-greet2($who) is export(:greet2) { ... }
sub foo-greet3($who) is export(:greet3) { ... }

Related

Is there a way to require a module and change the name of some its bindings?

I need to test different implementations of the same function from one single unit test file, with different files holding different implementations.
The problem is that with normal requires, everything is imported without a name space, so functions with the same name cannot co-exist.
Is there a way to bind imported modules to a name space? Or to rename the elements of an imported module?
Something like
; All files contain a function named "fun" that needs to be tested.
(require
(rename "implementation-one.rkt" fun fun-one)
(rename "implementation-two.rkt" fun fun-two)
(rename "implementation-three.rkt" fun fun-three))
(check-equal? (fun-one 0) 0 "first implementation")
(check-equal? (fun-two 0) 0 "second implementation")
(check-equal? (fun-three 0) 0 "third implementation")
Here I'm importing the fun function from each implementation file, and renaming it so something else. This is not valid Racket though.
I looked into modules, but it seems that the same problem happens; when requiring a module everything inside is exposed without a name space.
Is there a way to specify the name of an imported module, or change the names of the contents of the module? Perhaps by renaming the module's bindings, or by encapsulating imports in a name space, or some sort of named import? How are name conflicts like this normally resolved in Racket?
Should modules contain structs and/or objects that encapsulate each implementation? Or is there a way to do it with simple modules that provide functions?
(require
(rename-in "implementation-one.rkt" [fun fun-one])
(rename-in "implementation-two.rkt" [fun fun-two])
(rename-in "implementation-three.rkt" [fun fun-three]))
This is not hard to find in the manual.

Separating operator definitions for a class to other files and using them

I have 4 files all in the same directory: main.rakumod, infix_ops.rakumod, prefix_ops.rakumod and script.raku:
main module has a class definition (class A)
*_ops modules have some operator routine definitions to write, e.g., $a1 + $a2 in an overloaded way.
script.raku tries to instantaniate A object(s) and use those user-defined operators.
Why 3 files not 1? Since class definition might be long and separating overloaded operator definitions in files seemed like a good idea for writing tidier code (easier to manage).
e.g.,
# main.rakumod
class A {
has $.x is rw;
}
# prefix_ops.rakumod
use lib ".";
use main;
multi prefix:<++>(A:D $obj) {
++$obj.x;
$obj;
}
and similar routines in infix_ops.rakumod. Now, in script.raku, my aim is to import main module only and see the overloaded operators also available:
# script.raku
use lib ".";
use main;
my $a = A.new(x => -1);
++$a;
but it naturally doesn't see ++ multi for A objects because main.rakumod doesn't know the *_ops.rakumod files as it stands. Is there a way I can achieve this? If I use prefix_ops in main.rakumod, it says 'use lib' may not be pre-compiled perhaps because of circular dependentness
it says 'use lib' may not be pre-compiled
The word "may" is ambiguous. Actually it cannot be precompiled.
The message would be better if it said something to the effect of "Don't put use lib in a module."
This has now been fixed per #codesections++'s comment below.
perhaps because of circular dependentness
No. use lib can only be used by the main program file, the one directly run by Rakudo.
Is there a way I can achieve this?
Here's one way.
We introduce a new file that's used by the other packages to eliminate the circularity. So now we have four files (I've rationalized the naming to stick to A or variants of it for the packages that contribute to the type A):
A-sawn.rakumod that's a role or class or similar:
unit role A-sawn;
Other packages that are to be separated out into their own files use the new "sawn" package and does or is it as appropriate:
use A-sawn;
unit class A-Ops does A-sawn;
multi prefix:<++>(A-sawn:D $obj) is export { ++($obj.x) }
multi postfix:<++>(A-sawn:D $obj) is export { ($obj.x)++ }
The A.rakumod file for the A type does the same thing. It also uses whatever other packages are to be pulled into the same A namespace; this will import symbols from it according to Raku's standard importing rules. And then relevant symbols are explicitly exported:
use A-sawn;
use A-Ops;
sub EXPORT { Map.new: OUTER:: .grep: /'fix:<'/ }
unit class A does A-sawn;
has $.x is rw;
Finally, with this setup in place, the main program can just use A;:
use lib '.';
use A;
my $a = A.new(x => -1);
say $a++; # A.new(x => -1)
say ++$a; # A.new(x => 1)
say ++$a; # A.new(x => 2)
The two main things here are:
Introducing an (empty) A-sawn package
This type eliminates circularity using the technique shown in #codesection's answer to Best Way to Resolve Circular Module Loading.
Raku culture has a fun generic term/meme for techniques that cut through circular problems: "circular saws". So I've used a -sawn suffix of the "sawn" typename as a convention when using this technique.[1]
Importing symbols into a package and then re-exporting them
This is done via sub EXPORT { Map.new: ... }.[2] See the doc for sub EXPORT.
The Map must contain a list of symbols (Pairs). For this case I've grepped through keys from the OUTER:: pseudopackage that refers to the symbol table of the lexical scope immediately outside the sub EXPORT the OUTER:: appears in. This is of course the lexical scope into which some symbols (for operators) have just been imported by the use Ops; statement. I then grep that symbol table for keys containing fix:<; this will catch all symbol keys with that string in their name (so infix:<..., prefix:<... etc.). Alter this code as needed to suit your needs.[3]
Footnotes
[1] As things stands this technique means coming up with a new name that's different from the one used by the consumer of the new type, one that won't conflict with any other packages. This suggests a suffix. I think -sawn is a reasonable choice for an unusual and distinctive and mnemonic suffix. That said, I imagine someone will eventually package this process up into a new language construct that does the work behind the scenes, generating the name and automating away the manual changes one has to make to packages with the shown technique.
[2] A critically important point is that, if a sub EXPORT is to do what you want, it must be placed outside the package definition to which it applies. And that in turn means it must be before a unit package declaration. And that in turn means any use statement relied on by that sub EXPORT must appear within the same or outer lexical scope. (This is explained in the doc but I think it bears summarizing here to try head off much head scratching because there's no error message if it's in the wrong place.)
[3] As with the circularity saw aspect discussed in footnote 1, I imagine someone will also eventually package up this import-and-export mechanism into a new construct, or, perhaps even better, an enhancement of Raku's built in use statement.
Hi #hanselmann here is how I would write this (in 3 files / same dir):
Define my class(es):
# MyClass.rakumod
unit module MyClass;
class A is export {
has $.x is rw;
}
Define my operators:
# Prefix_Ops.rakumod
unit module Prefix_Ops;
use MyClass;
multi prefix:<++>(A:D $obj) is export {
++$obj.x;
$obj;
}
Run my code:
# script.raku
use lib ".";
use MyClass;
use Prefix_Ops;
my $a = A.new(x => -1);
++$a;
say $a.x; #0
Taking my cue from the Module docs there are a couple of things I am doing different:
Avoiding the use of main (or Main, or MAIN) --- I am wary that MAIN is a reserved name and just want to keep clear of engaging any of that (cool) machinery
Bringing in the unit module declaration at the top of each 'rakumod' file ... it may be possible to use bare files in Raku ... but I have never tried this and would say that it is not obvious from the docs that it is even possible, or supported
Now since I wanted this to work first time you will note that I use the same file name and module name ... again it may be possible to do that differently (multiple modules in one file and so on) ... but I have not tried that either
Using the 'is export' trait where I want my script to be able to use these definitions ... as you will know from close study of the docs ;-) is that each module has it's own namespace (the "stash") and we need export to shove the exported definitions into the namespace of the script
As #raiph mentions you only need the script to define the module library location
Since you want your prefix multi to "know" about class A then you also need to use MyClass in the Prefix_Ops module
Anyway, all-in-all, I think that the raku module system exemplifies the unique combination of "easy things easy and hard thinks doable" ... all I had to do with your code (which was very close) was tweak a few filenames and sprinkle in some concise concepts like 'unit module' and 'is export' and it really does not look much different since raku keeps all the import/export machinery under the surface like the swan gliding over the river...

Why does direct binding of an `our &foo` not work, but indirecting via a dynamic lookup does?

Why is there a difference between r1 and r2 when called outside of module TEST?
module TEST {
our &r1 := OUR::{'&r1'} := sub {
say 'routine 1'
}
r1(); # routine 1
our &r2 := sub {
say 'routine 2'
}
r2(); # routine 2
}
import TEST;
say TEST::.keys; # (&r1 &r2)
TEST::r1(); # routine 1
TEST::r2(); # Cannot invoke this object (REPR: Uninstantiable; Callable) ...
There is an error when trying to run subroutine r2 outside of module TEST where it was defined.
TL;DR Binding to an our is pointless. Binding to an OUR::<&foo> is effective. I like naming things... It seems you've invented a technique which I hereby dub "#jakar's double bind our".
Why the direct binding only works inside the module
In a comment on his answer to an earlier SO jnthn concludes that we could perhaps have an error message, or perhaps a warning, to the effect that:
binding to an our variable is pointless use of our.
(What he means is that the binding only works inside the module, not outside, as you have discovered.)
There's an old and still open issue Binding a variable at BEGIN time doesn't stick around for runtime that discusses the general problem in depth.
Why the dynamic lookup works outside the module
From Symbols that start with core namespaces always get exported, jnthn notes that:
stashes are always open to poke symbols in to.
So, ignoring use of symbols inside your module, your code is doing this:
module TEST {
OUR::{'&r1'} := sub { say 'routine 1' }
our &r2;
}
import TEST;
TEST::r1(); # routine 1
TEST::r2(); # Cannot invoke this object (REPR: Uninstantiable; Callable) ...
#jakar's double bind our
If one wants to be able to declare a symbol and use it both inside and outside the module and insists on using binding then your trick of declaring it with a double bind may be the best technique available:
our &r1 := OUR::{'&r1'} := sub { ... }
^^^^^^^^^^^^^^^^^^^^^^^^^^^ works *outside* module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ works *inside* module
Some things I'm curious about:
Have you been able to confirm any significant specific and practical advantage(s) that can be accrued from binding instead of assigning an our?
Do folk want to get around the "binding to an our variable is pointless" issue? If so, would they be happy to use #jakar's double bind our?
Does your technique apply to all sigils? (I would expect so but will leave it to you to explore such aspects. :))

flowtype definition of Iterable from immutable.js breaks other libs' Iterables

I just added immutable.js as a dependency to my project. I added
node_modules/immutable/dist/immutable.js.flow
to my .flowconfig.
The problem is that immutable exports an Iterable type, which is also a global type used in many other libraries that are in node_modules/, such as fbjs and react-native. For example one of the errors below.
node_modules/fbjs/lib/countDistinct.js.flow:22
22: function countDistinct<T1, T2>(iter: Iterable<T1>, selector: (item: T1) => T2): number {
^^^^^^^^^^^^ type application of identifier `Iterable`. Too few type arguments. Expected at least 2
32: declare class Iterable<K, V> extends _ImmutableIterable<K, V, typeof KeyedIterable, typeof IndexedIterable, typeof SetIterable> {}
^^^^ See type parameters of definition here. See lib: flow/immutable.js:32
In order to fix this I copied immutable.js.flow to my project and removed the .flowconfig line that includes it. In my copied file I rename Iterable to WhateverIterable and the errors are gone.
What is the best way to fix this thing without having to manually edit the immutable definitions?
The main problem is that node_modules/immutable/dist/immutable.js.flow is not written to be a library definition, so using it as one can cause errors.
What is immutable.js.flow
The docs refer to these files as declaration files. immutable.js.flow sits next to a file named immutable.js. Whenever Flow is asked to require immutable.js, it will resolve to immutable.js.flow instead. You can test this with the flow find-module command, which shows which file Flow resolves to when foo.js imports immutable:
$ flow find-module immutable foo.js
/Users/glevi/test/immutable/node_modules/immutable/dist/immutable.js.flow
Declaration files are written a little differently than libdefs. Library definitions declare a bunch of global things. They declare which variables, functions, types, classes, modules, etc are available globally, and declare the types of these things. Declaration files declare only the type of the module that they are shadowing.
A libdef for immutablejs would look like
declare module 'immutable' {
declare class Iterable<K,V> { ... }
...
}
while immutable.js.flow might look like
declare export class Iterable<K,V> { ... }
What should you do
In theory, you should not need to add node_modules/immutable/dist/immutable.js.flow to your .flowconfig. Flow should automatically use it whenever your code imports immutable.
If there is a problem with the immutable.js.flow that immutable ships with, then the best thing to do is to open a pull request or issue against immutable.js.flow or to submit a libdef to flow-typed.
A quick search shows someone working on a immutable libdef, so that might help too!

Including a module more than once

Suppose I have a module which defines some basic constants such as
integer, parameter :: i8 = selected_int_kind(8)
If I include this in my main program and I also include a module which does some other things (call this module functions) but functions also uses constants, then am I essentially including constants twice in my main program?
If so, is this bad? Can it be dangerous at all to include a module too many times in a program?
No, it is fine to do this. All you are doing with the use statement is providing access to the variables and functions defined in your module via use association. It is not like declaring variables each time they are use'd (they are in fact redeclared however).
The only thing to be wary of are circular dependencies, where module A uses module B and module B uses module A. This is not allowed.
Edit: From Metcalf et al. Fortran 95/2003 explained, pg. 72:
A module may contain use statements that access other modules. It must not access itself directly or indirectly through a chain of use statements, for example a accessing b and b accessing a.
Whilst this quote doesn't directly answer your question, it reiterates that really the only thing you can't do is have a circular dependency. So the following is perfectly valid:
module one_def
implicit none
integer, parameter :: one=1
end module one_def
module two_def
use one_def, only : one
implicit none
integer, parameter :: two=one+one
end module two_def
program test
use one_def, only : one
use two_def, only : two
implicit none
print*, two == one+one ! This prints .True.
end program