Recipe creation syntax

[Pikachu920]

Opening this discussion to get suggestions/feedback on recipe syntax for #5204. The current syntax in that PR is like this:

on script load:
  create crafting recipe for gold sword with key "test":
    dirt, dirt, air
    air, dirt, air
    air, air, air

I don't mind this syntax, but some others have expressed rational concerns. For example, it gets really ugly when you use long lines and is kinda implemented in a hacky way. Another possible syntax I've considered is similar to the first but puts the ingredients under a "shape" subsection. I think this is slightly better than the first as it makes the purpose of the recipe lines clearer.

on script load:
  create crafting recipe for gold sword with key "test":
    shape:
      dirt, dirt, air
      air, dirt, air
      air, air, air

Keep in mind that the syntax should support all the different types of recipes (BlastingRecipe, CampfireRecipe, CookingRecipe, FurnaceRecipe, MerchantRecipe, ShapedRecipe, ShapelessRecipe, SmithingRecipe, SmokingRecipe and StonecuttingRecipe)

[Fusezion]

While I don't believe it would be possible to make any syntax support all possible recipes we could most likely make 2-3 separate syntaxes under the same stuff

I believe we should exclude MerchantRecipe until we properly add full support for merchants and villagers as merchants will be something that can be added when modules are added since there's a lot that goes into it

register a new [:shapeless] crafting recipe for %itemstack% with key %string%:
    shape: # I do like the idea of using shape for this the hacky method doesn't looks terrible

register a new smelting recipe for %itemstack% with key %string%:
    type: %cooking recipe% # not sure if we should add a type or hard code the accepted smelters in but this should include (furnace, blast, smoker, cooking recipe and campfire)
    cooking time: %timespan%
    experience: %integer/number%
    input: %itemstack%

register a new (:smithing|stonecutter) recipe for %itemstack% with key %string%

not sure how their section entries should look as both are pretty different and do different things but are the only ones left

[Moderocky]

Buckle up everybody this is gonna be a long one :')

TL;DR

1. This syntax style breaks a precedent
2. It may weaken the language as a result
3. There may be a better way of doing it

I have concerns about this style of syntax, but they're greater concerns about how we're intending to use sections.

So I initially raised reservations about this style of syntax with @APickledWalrus who had proposed this:

Now there are advantages to the structure, it's probably fast to parse, but it has some drawbacks.
We discussed this at length, so I'm going to try and explain it here.

Contracts

Skript, as a programming language, is built on a set of 'contracts' (or rules, if you prefer.) An ideal language follows its contracts for consistency.
For example, one of Java's contracts is that a new keyword always produces a brand new object. In return, you the programmer get the assurance that when you write new it's going to produce a new object. These contracts allow us to make reliable expectations about the language.
Note: Java has a very long list of these, all written out in the JLS - it's 840 pages long!

Why contracts are important

Contracts allow us to write reliable code. They allow us to trust our code.
Specifically, they allow us to write this code without massive adherence to the documentation, without having to check if each line is valid as we write.
The stricter and more reliable these contracts are, the more efficient our code-writing will be.
If you read the Java Specification, you could write huge amounts of perfect code without having to test it - you can trust it will work because you've followed the rules.

Do we have contracts in Skript?

Yes. They're implicit.
We have rules like:

• A line ending with a colon : should have an indented section below it.
• A hash # starts a comment.
• Doubling a meta character (##, %%, "") escapes it for use in text.
  They're not all written down in a list, they're just assumptions we can make about the language.

Skript has always had a de facto contract that every line within a code trigger will be some kind of effect, whether that's a direct one (kill player, set {var} to 10, "do X") or a more indirect one (if {x} is true: -> "if X, do Y...")
Code lines are 'atoms' - if you split them up any further they don't make sense.

How is this relevant?

In your (and @APickledWalrus) suggestion-

create a new diamond stored in {_var}:
  enchantments:
    Efficiency 5
    Fortune 3

create crafting recipe for gold sword with key "test":
    dirt, dirt, air
    air, dirt, air
    air, air, air

-we are violating this contract.
Lines within the code body like dirt, dirt, air or Efficiency 5 aren't effects.
In fact, you can see that the language wants them to be effects since they've been entered as such in the draft.

Is this contract important?

It makes Skript simple to read. I can take (almost) any line of Skript code on its own and infer what it does and where it should go.

Here are some examples:

• set {var} to 10
• if player is alive:
• loop all players:
• send "hello" to event-player

We cannot make these determinations about unqualified expressions:

• Efficiency 5
• air, string
• "hello"

Alternatives

Fortunately, this isn't the end of the world.
For most of these we can create simple alternative with section-relative effects or expressions.
For @APickledWalrus we came up with some tiny expressions like the name, the lore.

Honestly I think it looks better than his original proposal, but you might disagree.
The main advantage is it maintains our contract.

If you're willing, perhaps we can look for similar alternatives for recipes.

Conclusion

At the end of the day, we can make this change. We can get rid of our initial contract, open up Skript to this new style for sections. It could make Skript objectively better down the road.

But I don't want us to do this flippantly.
I want to make sure we all fully understand that this is a significant decision and it's going to have (good or bad) consequences for future development.

[Fusezion]

While I probably shouldn't be the one to say this as this is as this is more so for the dev team but could we not say that the style of how we do the if or/if and condition pr also breaks our rules/contract? #5165

Spawn Effect Section

(spawn|summon) %entitytypes% [%directions% %locations%]
(spawn|summon) %number% of %entitytypes% [%directions% %locations%]

I could argue that the spawn section doesn't follow our contract of displaying "new" when used, in this case, we basically just used
your preferred proposal of supporting something relative to the effect ex: spawn a zombie at the player: the relative expression would be event-entity or the zombie

Updated Syntax Style

I've come up with this syntax following my previous usage but removing the entries

# Relative Expressions
#  recipe ingredients
#  recipe key
#  recipe item
register a new [:shapeless] crafting recipe for %itemstack% with key %string%:
    set recipe ingredients to %itemstacks%
    add %itemstacks% to recipe ingredients
    remove recipe ingredients from recipe ingredients 
    
    # recipe key and recipe item are there incase people decide to save to a variable 

# Relative Expressions
#  recipe ingredient | you can't use multiple
#  recipe cook time | could be made something else
#  recipe experience
#  recipe type | this should include furnace, blast, smoker, cooking recipe and campfire
#  recipe key
#  recipe item
register a new smelting recipe for %itemstack% with key %string%:
    set recipe type to %recipe type%
    set recipe ingredient to %itemstack%
    set recipe experience to %number%
    set recipe cook time to %timespan%

# yeah got no clue still how this one should be done since Pikachu doesn't seem to really want many sections made
register a new (:smithing|stonecutter) recipe for %itemstack% with key %string%