Have an imported module in a template be available when amending it

[ghyatzo]

Hello,

I'm still at the beginning of using pkl, so I still have to find my footing.
I am in the following situation:

module MyModule

import "SomeClasses.pkl"

typealias AvailableClasses = SomeClasses.Class1 | SomeClasses.Class2

myproperty: Listing<AvailableClasses>

In SomeClasses I define some objects and Only those are available to be chosen in myproperty. I wanted to see if it is possible to use the object directly as entries instead of relying on some mapping with strings.
Now when I want to amend that template I want to be able to do:

amends "MyModule.pkl"

myproperty = new Listing {
    (SomeClasses.Class1) { ... }
}

without importing SomeClasses.pkl again as that would be a bit tiresome.

My understanding is that amending shares all existing properties of the amended template/object, So I expected SomeClasses to exist in the scope.
I've also tried to use classlist = import("SomeClasses.pkl") but then I can't access classlist.Class1 as it complains that Cannot find module import 'classlist'

I am clearly misunderstansing something, is this possible? Or am I looking at it from the wrong perspective?
Thanks!

[HT154]

Two things going on here:

• An import statement introduced the equivalent of a local property. You'll find that locals aren't available in amending modules either.
• An import() expression only introduces the imported module's value, but it does not introduce the module's type.

I think you can get what you want by typealiasing each class into the module you're amending, but barring that you do need to import again.

[ghyatzo]

The concept of module value is not completely clear to me. What is it meant by that?

I've read that in the docs as well, and thought that import() was just a way to bind the imported module to a non const local property, as in: import "modulename.pkl" being just syntactic sugar for local const modulename = import("modulename.pkl")
but I'm clearly mistaken.

[HT154]

Take this module for example:

module MyModule

a: String = "hello"
b: Int = 0

You can think of this module as either a type or a value. Evaluating this module produces a representation of its value:

a = "hello"
b = 0

As a type, this is similar to a class with properties a and b, and in fact you can use it as a class, like so:

import "MyModule.pkl"

x = new MyModule {
  b = 2
}

As you've seen, the type/value distinction is made evident by the two different kinds of import:

• The import "MyModule.pkl" statement introduces a few things that all share one name:
  • The value of the module, bound to a local property, equivalent to local MyModule = import("MyModule.pkl")
  • The type of the module [NB: in Pkl, types and properties (and methods(?)) have separate namespaces], equivalent-ish to copy-pasting the module as a class in place of the import
  • A type sub-namespace that contains any classes defined in
• The import("MyModule.pkl") expression imports the value only, because expressions can only produce values, not types

Some corollaries:

• A module that amends another is like instantiating a class (new MyClass { ... }) in that it creates a value but does not introduce a new type (and therefore you can't define new properties).
• A module that extends another is like extending a class (class MySubclass extends MyClass { ... }) in that it creates a new type and can define new properties.
• Modules differ from classes in that they're also values

My terminology might be a little imprecise here so one of the core folks may be able to provide more color.

[ghyatzo]

I couldn't have asked for a better explanation. Thank you so much.

One last doubt, I suppose the exact content of the module value depend on the output property of the module itself, but is it just a string with the output or is it a more structured object?

By the way I think this extra example could be really useful in the docs to make it painfully clear!

[HT154]

It's actually surprisingly un-magical! When you run pkl eval without setting -x, the (String) content of output.text is the output.

pkl/stdlib/base.pkl

Lines 93 to 107 in 40a08af

	hidden output: ModuleOutput = new {
	value = outer
	renderer =
	let (format = read?("prop:pkl.outputFormat") ?? "pcf")
	if (format == "json") new JsonRenderer {}
	else if (format == "jsonnet") new jsonnet.Renderer {}
	else if (format == "pcf") new PcfRenderer {}
	else if (format == "plist") new PListRenderer {}
	else if (format == "properties") new PropertiesRenderer {}
	else if (format == "textproto") new protobuf.Renderer {}
	else if (format == "xml") new xml.Renderer {}
	else if (format == "yaml") new YamlRenderer {}
	else throw("Unknown output format: `\(format)`. Supported formats are `json`, `jsonnet`, `pcf`, `plist`, `properties`, `textproto`, `xml`, `yaml`.")
	text = renderer.renderDocument(value)
	}

As you can see, this is evaluating renderer.renderDocument(value). This has a few downstream effects:

• Setting output.text explicitly causes output.value and module.renderer to be ignored
• Setting output.renderer explicitly causes the --format flag to be ignored
• Evaluating an expression explicitly with -x also ignores output.renderer (see pkl eval ignores --format option on use of -x, --expression #774)
  • -x 'output.renderer.renderDocument(<expr>)' closes the gap
  • If the expression from -x results in a String, that string becomes the output
  • If the expression from -x results in another type, that string becomes the result of new PcfRenderer {}.renderValue(<expr>)

[ghyatzo]

mind has been open. Thanks for the clarity and exhaustiveness

[holzensp]

My terminology might be a little imprecise here so one of the core folks may be able to provide more color.

I think you're spot on, except for the namespaces.

I'd just add that if you really, REALLY want this, you can still

import "MyModule.pkl" as _myModule

// Either
hidden const MyModule = _myModule // <- To "re-export" the _value_
// or
typealias MyModule = _myModule // <- To "re-export" the _type_

You can't do both, though, because types and values actually occupy the same namespace (although there are places where only types, or only values are allowed). Also, what you're doing in your example, you cannot do; there is no way to re-export the module as a module, containing it's classes.

In general, this re-exporting is a bit of a smell (not a hard rule). It suggests you may have been splitting things up into separate modules a little too much.