toml.bzl: Instructions file for Gemini CLI

GEMINI.md - Starlark Performance & Parsing Notes

Starlark Performance Best Practices

Based on profiling within this codebase and others, the following patterns are significantly more efficient in Starlark:

1. Prefer Operators Over Method Calls

Operators are built-in to the Starlark interpreter and avoid the overhead of method lookup and dispatch.

• List Append: Use list += [item] instead of list.append(item).
  • Result: += [item] is approximately 2x faster than .append().
• List Copy: Use list_copy = original[:] instead of list_copy = list(original).
  • Result: [:] slicing is approximately 2.5x faster than list().

Core Starlark Constraints

1. No while Loops: Bazel's Starlark dialect does not support while loops or recursion.

   • Workaround: Use for _ in range(MAX_ITERATIONS): with break for "bounded while" loops.
   • Strategy: Design the parser to be linear single-pass or structured in hierarchical passes.

2. String Immutability & Concatenation:

   • Strings are immutable.
   • Avoid repeated s += part in loops (O(N^2)).
   • Best Practice: Collect parts in a list and use "".join(parts) at the end.

3. Function Call Overhead:

   • Starlark function calls have measurable overhead.
   • Optimization: Inline simple logic where performance is critical (e.g., inside the inner character loop of a parser).

Parsing Performance

1. Native String Methods:

   • Use s.find(), s.rfind(), s.startswith(), s.endswith(), s.isdigit() whenever possible.
   • These run in Java/C++ native code and are significantly faster than iterating characters in Starlark.

2. Character Iteration:

   • Iterating a string (for char in string:) is slow in Starlark.
   • Alternative: Tokenize with split() or regular expressions (if efficient native regex available, or bazel-regex if imported).
   • Alternative: Use partition() to jump to delimiters.

3. List Comprehensions: