Re: Help Understanding syntax-propertize-function

[Stefan Monnier]

> I'm struggling to understand what `hcl--syntax-propertize-heredoc` is
> doing.
> Could you provide a high level explanation like you did with
> `hcl--syntax-propertize-function`.
> That helped me a lot.

> (defun hcl--syntax-propertize-heredoc (end)

The purpose of the function is to do the "syntax-propertize" of the
inside of a heredoc.  It presumes that point *may* be in a heredoc but
not necessarily.

>   (let ((ppss (syntax-ppss)))
>     (when (eq t (nth 3 ppss))

Here we fetched the syntax state at point and then we checked that we
are indeed inside a heredoc (or at least a "string like thing" that was
opened using the `|` syntax category; in this mode should should only
ever happen if we have placed this syntax because we found a heredoc
marker).

>       (let ((key (get-text-property (nth 8 ppss) 'hcl-here-doc-marker))

This fetches the string that was used in the heredoc opener and which
has to be used as heredoc closer.  It's been placed on the opening char
at position (nth 8 ppss) by the same code that placed the `|` syntax
property on that same character.

>             (case-fold-search nil))

I guess here that the code does that because HCL defines the heredoc
marker to be case-significant.

>         (when (re-search-forward
>                (concat "^\\(?:[ \t]*\\)" (regexp-quote key) "\\(\n\\)")
>                end 'move)

Here we look for the heredoc end marker.  If we can't find one before
`end`, it just means that the heredoc extends further and hence we have
nothing to do (we could actually remove/override any `|` syntax that
might appear before `end` in case such a thing is possible, but
apparently the rest of code is arranged so that this is not needed).

>           (let ((eol (match-beginning 1)))
>             (put-text-property eol (1+ eol)
>                                'syntax-table (string-to-syntax "|"))))))))

If we did find the heredoc end marker before `end`, then we mark it as
being the end by adding the `|` syntax to the ending character.


        Stefan