Mlx Array Convenience Initializer Macro

[robertmsale]

Proposed changes

Potential solution for #161.

This change introduces a new #mlx(...) expression macro to improve array literal ergonomics for MLXArray initialization while keeping expansion behavior explicit and testable:

• Adds #mlx as a public macro surface in MLX, so users can write:
  • #mlx([[1, 2], [3, 4]])
  • #mlx([[1, 2], [3, 4]], dtype: .int16)
• Validates nested literals are rectangular and numeric, and emits diagnostics for ragged/invalid input.
• Supports deep nested literals and shape inference during expansion.
• Implements dtype-aware expansion optimization:
  • Emits typed literal initialization directly for known integer dtypes and .float32 (avoids a trailing .asType(...) cast).
  • Falls back to .asType(...) for dynamic dtype expressions and dtypes that do not cleanly map to Swift literal typing (.float16, .bfloat16, .complex64, .float64, .bool).
• Defines mixed literal promotion semantics:
  • If any literal element is floating-point, expansion uses floating-point construction for the full array.
  • Provides warning when float is used and explicit integer dtype is specified

Tests and docs:

• Adds macro unit tests covering:
  • integer, float, mixed, deep-nested literals
  • dtype-specific expansion behavior
  • fallback behavior for dynamic/non-native dtypes
  • ragged-literal diagnostics
  • compiler warning when mixing float literals with integer dtypes
• Updates DocC initialization docs with a macro section, examples, and mixed-literal promotion notes.

Checklist

Put an x in the boxes that apply.

• I have read the CONTRIBUTING document
• I have run pre-commit run --all-files to format my code / installed pre-commit prior to committing changes
• I have added tests that prove my fix is effective or that my feature works
• I have updated the necessary documentation (if needed)

[davidkoski]

This is an interesting idea -- I guess using a macro is the only way to get compile-time checks. I am not sure on the naming: #mlx seems a bit vague. I don't suppose #MLXArray would work, would it? I suspect the name would clash in the macro definition. Maybe #mlxarray or #array?

[robertmsale]

Good point! I was worried that #MLXArray wouldn't work, but I think because macros get expanded before the AST is built, I replaced all #mlx macros with #MLXArray and all the tests passed successfully. It's kinda cool because it now reads like the thing it's initializing! You just throw a # behind it and suddenly can do nested arrays with strong shape & type guarantees, so that worked out pretty well!

[robertmsale]

Sorry @davidkoski, I ran the pre-commit code formatter initially, but made changes later and forgot to run it again.

I see there are proposed runtime solutions that mentioned this PR. I think the macros can be for highly optimized and compile-time checked literal shapes. It complements the runtime solutions, and all it requires is prefixing a # to the initializer!

[davidkoski]

Yeah, #161 looks really promising (but isn't ready as it doesn't work right now). You are right that it doesn't do build-time checks on the shape, but I do like the fact that it is just plain swift.

CI running again, but I saw some infrastructure issues earlier.