More obvious build system integration

[keith-hall]

Hi,

Thanks for this great plugin. I wonder if we could make it slightly friendlier for new users by integrating with the build system a tiny bit more - specifically, I mean:

• when building, it is not clear that anything happened, because I have "show_panel_on_build": true (as per the ST default), and no panel is displayed on success or failure. Granted, showing the panel on success doesn't hold much merit, but it could be useful to see how long the build took and a confirmation of the path to the newly created .sublime-syntax file.
• currently, any exceptions that occur during the build are visible in the ST console. It'd be great if they could be caught and a more informative (where easily possible) error shown in the build panel. For example, I tried to use the built in !extend macro, and in _base, I gave a relative path to an existing syntax in my Packages folder, with the yaml-macros file itself in my User package, as I didn't want to make a copy of the base syntax but I wanted to work in my User package. YAML-Macros couldn't find the base file. New users that are using the built in macros and not writing their own may not think to look in the ST console.
  • incidentally, maybe it's outside of the scope of this plugin, but it'd be handy if, when referencing a syntax for extension, the extend macro could automatically find it - even if it is contained in a .sublime-package file. EDIT: though obviously it is best practice to have a concrete copy of the file being extended, it doesn't quite fit my use case of playing around :)

• I'm not sure how feasible this is, but it'd be great if, when a build fails, YAML-Macros wouldn't clear the contents of the .sublime-syntax file being generated, resulting in an ST error:

  error parsing lexer: Packages/User/example.sublime-syntax: Error trying to parse sublime-syntax: %YAML indicator is required in Packages\User\example.sublime-syntax:1:1

  I'd like it to keep the previous successfully built version if possible, please. I realize that the amount of output generated may be dependent on the macro that fails, and where in the process it fails and that could give vital clues as to why/where the macro is failing, so I'm expecting a "no" answer to this, but thought I'd mention it anyway. :) (Note that probably I wouldn't even want this if extend was more clever about finding the base syntax, as mentioned above.)

[Thom1729]

Thanks for the feedback! Your timing is ideal -- I'm hoping to get 3.0 out in the next couple of days. Along with a couple of new features, the major priorities are usability and output quality.

I'm not sure how feasible this is, but it'd be great if, when a build fails, YAML-Macros wouldn't clear the contents of the .sublime-syntax file being generated

This will be fixed in 3.0. On a failed build, the destination file will not be touched.

it'd be handy if, when referencing a syntax for extension, the extend macro could automatically find it - even if it is contained in a .sublime-package file.

This might be tricky, because the CLI doesn't have access to Sublime's convenience functions for this. Porting those functions to a standalone module would be a prerequisite.

when building, it is not clear that anything happened, because I have "show_panel_on_build": true (as per the ST default), and no panel is displayed on success or failure.

currently, any exceptions that occur during the build are visible in the ST console. It'd be great if they could be caught and a more informative (where easily possible) error shown in the build panel.

Error handling is the last major item on my to-do list for 3.0, and the build output panel certainly sounds like the best place to put it. I'll see what I can get in before the release.

[keith-hall]

the CLI doesn't have access to Sublime's convenience functions for this. Porting those functions to a standalone module would be a prerequisite.

I've started work on this over at https://github.com/forkeith/YAML-Macros/commit/2f23ed1adbae4300bccc7bfb92691bafdd585a0e, but I had to base it off the latest release branch as almost any newer commits seemed to give me ZipLoader errors. I may or may not get time to complete it, so feel free to use or not use it as you see fit :)

[Thom1729]

Thanks for the work on that.

In 3.0, I'm soft-deprecating the extend macro in favor of an apply macro that does less. As it stands, the following examples should do the same thing:

%YAML 1.2
%TAG ! tag:yaml-macros:YAMLMacros.lib.extend:
---
!extend
_base: foo.yaml
otherProp: test

%YAML 1.2
%TAG ! tag:yaml-macros:YAMLMacros.lib.extend:
---
!apply
- !include foo.yaml
- !merge
  otherProp: test

The new apply macro takes an array with an initial value and zero or more Operations. The Operations are applied in order to the initial value. To extend a file, you use the new include macro, which loads the file (applying any macros in that file).

The best way to integrate the sublime lookup functionality would probably be to have a new macro analogous to include. It could be used as follows:

%YAML 1.2
%TAG ! tag:yaml-macros:YAMLMacros.lib.extend:
---
!apply
- !sublime_resource foo.yaml
- !merge
  otherProp: test

This would allow users to include named files from built-in packages, installed packages, or user packages.

I'm a bit concerned that this could be brittle, though. An extension syntax will necessarily rely on internal implementation details of a specific version of another syntax. These details could change without warning. Two users could also have different versions of a dependency package installed, resulting in different builds. I think that if we bake in this kind of functionality, we have to solve that problem by specifying dependencies more strictly.

[keith-hall]

one thing I've noticed with using !apply instead of !extend is that Package Dev's syntax highlighting no longer works very well due to the extra indentation - I wonder what we can do about that?

vs

[Thom1729]

It looks PackageDev assumes that context names will be indented by one or two spaces. I'll have to consider how best to handle this.

In the mean time, you can use !include to factor out the extension into its own file. You can give it a .sublime-syntax.yaml-macros extension to get the appropriate highlighting without Sublime picking it up as a new syntax. I may just update the example to do this.

[keith-hall]

Nice, I'm really happy with this now - thanks! Do you want to keep this issue open to track the resource dependency part of the issue or shall we close it? :)

[Thom1729]

I think it's all set for now. I might slightly refactor the resource dependencies, but I think it's a complete feature as-is. Even if there are potential issues with importing resources blindly from other packages, it can be essential for importing resources from the same package.