Deprecate `helpers.mkRaw` in favour of `lib.generators.mkLuaInline`

[MattSturgeon]

Overview

Historically we have used our own mkRaw which produces an attrset that looks like { __raw = expr; }, however nixpkgs has had mkLuaInline for a while now (for use with its toLua generator). The nixpkgs function produces an attrset that looks like { _type = "lua-inline"; inherit expr; }.

We should add support for this in our toLua and begin transitioning usage of mkRaw to mkLuaInline.

Eventually we can deprecate our function in favour of mkLuaInline.

Even further in the future, we can deprecate __raw support in toLua.

See upstream usage in lib.generators.toLua and lib.generators.mkLuaInline definition.

TODO

• helpers.lua.mkLua should support nixpkg's "lua-inline" type. lib/lua: support nixpkg's "lua-inline" type #2012
• Transition internal __raw to use mkLuaInline
• Documentation should recommend mkLuaInline
• Add a deprecation warning to helpers.mkRaw
• (eventually) Add a deprecation warning to toLua when encountering __raw

Note: there's now also a lib.generators.toLua in nixpkgs, however we currently can't use it, because it has no support for mixed list+attrs tables.

[khaneliman]

I'm a fan of transitioning away from a custom function to one maintained upstream. That would increase consistency with other repos and lower the tech debt with managing our own library functions.

[MattSturgeon]

I agree. I felt a little hesitant because we'll still be maintaining our own "unkeyed attrs" system, however I don't think this needs to be all or nothing straight away.

We can come up with an upstream solution to mixed lua tables separately. Thankfully this is less significant than raw/inline lua, because it is used far less often.

[MattSturgeon]

Something else to consider is how we show raw/inline values in the docs.

lib.generators.toPretty has support for a custom "pretty print" type (allowPrettyValues), which is enabled in the docs usage.

I think ideally, our examples should show the function application not the resulting attrs.

We can also use literalExpression, e.g. literalExpression "lib.generators.mkLuaInline { foo = false; }", but this is only useful for whole examples, not small parts of them where we'd need __pretty.

[MattSturgeon]

We could have a mkLuaInlineLiteral, but since pretty-printers aren't supplied indentation information, we'd have to either work it out in advance or have no indentation.

mkLuaInlineLiteralIndented = indent: text: {
  __pretty =
    v:
    indent
    + "mkLuaInline "
    + generators.toPretty { inherit indent; } v;
  val = text;
};

It'd be nice if toPretty provided a way to call a pretty-printing function with additional information, such as the current indent and toPretty's args. Maybe if the pretty printer has __prettyWith instead of __pretty?

[GaetanLepage]

Thanks @MattSturgeon.
I agree with your migration plan. Doing it step by step looks great.

[MattSturgeon]

With the conversation around #1935, #2035 will be another place we have a migration away from recommending __raw
#2035 (review)

I'm starting to think we should postpone publicly deprecating mkRaw until after 24.11... We have enough things for users to migrate already when theyre upgrading from 24.05->24.11 😅

[khaneliman]

With the conversation around #1935, #2035 will be another place we have a migration away from recommending __raw
#2035 (review)

I'm starting to think we should postpone publicly deprecating mkRaw until after 24.11... We have enough things for users to migrate already when theyre upgrading from 24.05->24.11 😅

That makes sense actually.. there are a lot of deprecation notices throughout the codebase atm.