Rework Handling of Quotes in Named and Unnamed Arguments in STscript

[Wolfsblvt]

Core Issue

The handling of quotes in named and unnamed arguments within the STscript parser currently lacks consistency, leading to confusion and misunderstandings in the functionality, that would lead to people considering the current handling "a bug". The parser's behavior needs to be standardized to better align with user expectations and established usage patterns.

Extended Details

The inconsistency in how the STscript parser handles quotes across different types of arguments has led to significant confusion. Different users have developed varying habits and expectations based on their unique use cases, leading to conflicts when attempting to parse scripts. For example, while it would be ideal to retain quotes by default in both named and unnamed arguments for a developers perspective, the historical usage patterns and technical constraints make this approach impractical. In named arguments, quotes can be used or omitted without changing the result, which leads to inconsistencies and unpredictability. The situation is further complicated by the task to maintain backward compatibility, as breaking existing scripts could disrupt users who rely on the current behavior. These challenges necessitate a careful and systematic approach to resolving the issue, balancing the need for consistency with the need to respect existing user habits and scripts.

Overview of Things to Do

• [ ] Define and implement a consistent handling of quotes in named and unnamed arguments.
• [ ] Ensure backward compatibility where possible, while documenting and communicating any breaking changes.
• [ ] Update the parser and related components to reflect the new rules.
• [ ] Provide thorough documentation and support for users to adapt to the changes.

Structured Todo List

1. Code Changes

   • [ ] Parser Updates:
     • [ ] Modify the parser to treat quotes consistently in named arguments (no changes needed) while ignoring them in unnamed arguments.
     • [ ] Ensure that unnamed arguments are always treated as raw strings, with no special parsing of quotes.
   • [ ] Syntax Highlighting:
     • [ ] Update the syntax highlighting rules to reflect the new handling of quotes.
     • [ ] Ensure that named and unnamed arguments are clearly distinguished in the editor.
   • [ ] Escape Handling:
     • [ ] Implement or adjust escape handling so that the pipe (|) and backslash (\) are correctly processed within unnamed arguments.
     • [ ] Ensure that quotes no longer need to be escaped within unnamed arguments, in line with the new parsing rules.

2. Consistency Checks

   • [ ] Auto-complete:
     • [ ] Update the auto-complete functionality to align with the new parser rules, ensuring that it suggests valid syntax based on the updated behavior.
   • [ ] Validation of Escape Characters:
     • [ ] Implement or update validation checks to ensure that pipes and spaces are properly escaped, and that quotes are handled correctly according to the new rules.

3. Documentation

   • [ ] Update Existing Documentation:
     • [ ] Thoroughly revise the documentation to explain the new behavior of quotes in named and unnamed arguments.
     • [ ] Highlight the differences between the old and new parsing rules, especially regarding quote handling and escape sequences.
   • [ ] Create a Migration Guide:
     • [ ] Provide a step-by-step guide for users to update their scripts, including examples of common issues and how to resolve them.
   • [ ] Breaking Changes Announcement:
     • [ ] Draft and publish an announcement explaining the breaking changes, why they are necessary, and how users can adapt.
     • [ ] Include information on where users can find support and report issues.

4. User Support and Migration

   • [ ] In-Code Warnings and Utilities: (Optional)
     • [ ] Develop in-code utilities to automatically detect scripts that may be affected by the changes.
     • [ ] Implement warnings or notifications within the code editor to alert users when their script might contain deprecated or incorrect syntax.
   • [ ] Migration Tools: (Optional)
     • [ ] If feasible, provide tools or scripts to help users automatically update their existing scripts to comply with the new rules.
   • [ ] User Communication:
     • [ ] Prepare a comprehensive communication plan to ensure users are aware of the changes well in advance.
     • [ ] Offer guidance on how to test scripts under the new parser rules before fully migrating.

5. Additional Considerations

   • [ ] Future Planning: (Optional)
     • [ ] Document any potential future changes or enhancements that may be needed based on user feedback after the initial rollout.
     • [ ] Monitor the impact of the changes on the user base and be prepared to make further adjustments if necessary.

This issue requires careful coordination and clear communication across the dev team and with the user community. The focus is on ensuring a smooth transition while improving the overall consistency and reliability of STscript parsing.

Please tick the boxes

• [X] I have explained the issue clearly, and I included all relevant info
• [X] I have checked that this issue hasn't already been raised
• [X] I have checked the docs

[Wolfsblvt]

Okay, everyone should've figured out that this issue post is a slightly adjusted/curated but still AI generated response. It's accurate enough, and I was too lazy to type everything myself.

Here in my words, very blunt, what I think needs to be done.

• [ ] Quote Parsing
  • [ ] Change quote parsing in unnamed arguments to just not treat quotes as anything special anymore.
  • [ ] Fix/change escape characters in unnamed arguments to be consistent again with the new rules
• [ ] AutoComplete / Syntax Highlighting
  • [ ] Update/verify Syntax Highlighting
  • [ ] Update/verify Auto Complete
• [ ] Update Documentation
• [ ] Breaking Changes Info
  • [ ] Prepare Announcement
  • [ ] Write guide/steps how to migrate
  • [ ] (Optional) think about whether auto migration or in app warnings could be possible

Important take-aways are:

• Quotes are not being treated special in unnamed args anymore
• They still keep being delimiters in named args
• Splitting unnamed arguments doesn't usually happen anymore. If it happens, it's defined by the command after parsing. And then done splitting on spaces, respecting escaped spaces to combine parts
• Breaking changes need to be documented and warned about

[Wolfsblvt]

Originated as a discussion from the following issue: #2723

[github-actions[bot]]

This issue has gone 6 months without an update. To keep the ticket open, please indicate that it is still relevant in a comment below. Otherwise it will be closed in 7 days.