Expansion Tag Parsing/Escaping Issue & Feature Suggestion for Docstring Parsing

Script Debugger Feature Requests
#1

I was updating some of my text expansions to make fuller use of of expansion tags, but I’m having an issue with expansion tags located in pairs of square brackets.

Example: [[[template:PLACEHOLDER]]]

I would expect this to expand to [MY_TEXT_HERE], but the triple opening bracket seems to prevent this from being parsed (the triple closing bracket does not seem to cause an issue). Is there an escape sequence, etc. that can be used, or is it simply a bug / edge case?

On a separate note, I came across this issue as I was updating my personal text expansion for handler docstrings…

(*    (CLASS) → CLASS

HANDLER DESCRIPTION.

Parameters:
NAME [CLASS] : PARAMETER DESCRIPTION.

Result:
[CLASS] : RESULT DESCRIPTION.    *)

…and this got me thinking – is there any sort of standard docstring format for AppleScript that could one day be parsed by Script Debugger to provide quick help for function completion, similar to Xcode? Could be very useful!

Swift uses ‘Documentation Comments’ (see here if interested) – an AppleScript-style version of this could look something like this:

(**
Handler description.

- Requires: Requirements.

- Parameters:
  - Identifier: Class - Description.

- Throws: Error information.

- Returns: Class - Return value.
*)

Thanks!

#2

I’m guessing you mean something other than what you typed. But the parser simply looks for the first [[ and then a matching ]], so if the first character it finds between the two tokens is a [, there’s no token match, meaning the content is just passed through.

#3

Thanks Shane (apologies if my previous example wasn’t that clear). So with the current parser, it’s not possible to have the expansion feature place user text in between a pair of square brackets:

e.g. first tag [[[template:PLACEHOLDER]]] is expanded → “PLACEHOLDER” highlighted → user types “string” → end result [string]

Looks I’d probably be better off changing to round brackets, since this doesn’t cause parsing issues:

e.g. ([[template:PLACEHOLDER]]) → … → (string)

Thanks!

#4

@tree_frog

Add spaces like this:
[ [[template:PLACEHOLDER]] ]

You should get what you want…
:wink:

1 Like
#5

The parser actually converts the tokens to different tokens — if you copy some text with placeholders and paste it into something like BBEdit, you will see #~ and ~#. It is possible to use these tokens directly:

[#~xxx~#]
Using these is less forgiving of mistakes, and they don’t work for all types of placeholders, but they’d probably work fine for this use case.

1 Like
#6

Thanks Jonas – that would be a close second, but it does leave the spaces hanging around afterwards since it’s part of a comment.

Amazing, Shane. This works perfectly. Thank you.