Merge branch 'master' into 1.17

docs/scarpet/api/Auxiliary.md

@@ -11,6 +11,8 @@ optional `mixer`. Default values for `volume`, `pitch` and `mixer` are `1.0`, `1
 Valid mixer options are `master`, `music`, `record`, `weather`, `block`, `hostile`,`neutral`, `player`, `ambient`
 and `voice`. `pos` can be either a block, triple of coords, or a list of thee numbers. Uses the same options as a
  corresponding `playsound` command.
+ 
+Throws `unknown_sound` if sound doesn't exist.
 
 ## Particles
 
@@ -21,12 +23,15 @@ of 0, and to all players nearby, but these options can be changed via optional a
 command on details on those options. Valid particle names are 
 for example `'angry_villager', 'item diamond', 'block stone', 'dust 0.8 0.1 0.1 4'`.
 
+Throws `unknown_particle` if particle doesn't exist.
+
 ### `particle_line(name, pos, pos2, density?, player?)`
 
 Renders a line of particles from point `pos` to `pos2` with supplied density (defaults to 1), which indicates how far 
 apart you would want particles to appear, so `0.1` means one every 10cm. If a player (or player name) is supplied, only
 that player will receive particles.
 
+Throws `unknown_particle` if particle doesn't exist.
 
 ### `particle_box(name, pos, pos2, density?, player?)`
 ### `particle_rect` (deprecated)
@@ -34,6 +39,8 @@ that player will receive particles.
 Renders a cuboid of particles between points `pos` and `pos2` with supplied density. If a player (or player name) is 
 supplied, only that player will receive particles.
 
+Throws `unknown_particle` if particle doesn't exist.
+
 ## Markers
 
 ### `draw_shape(shape, duration, key?, value?, ... )`, 
@@ -320,6 +327,10 @@ record to the file. Since files are closed after each write, sending multiple li
 write is beneficial for writing speed. To send multiple packs of data, either provide them flat or as a list in the
 third argument.
 
+Throws:
+- `nbt_read_error`: When failed to read NBT file.
+- `json_read_error`: When failed to read JSON file. The exception data will contain details about the problem.
+
 <pre>
 write_file('foo', 'shared_text, ['one', 'two']);
 write_file('foo', 'shared_text', 'three\n', 'four\n');
@@ -371,6 +382,8 @@ specific data directory is under `world/scripts/foo.data/bar/../baz.nbt`, and sh
 
 You can use app data to save non-vanilla information separately from the world and other scripts.
 
+Throws `nbt_read_error` if failed to read app data.
+
 ### `store_app_data(tag)`
 
 Note:  `store_app_data(tag, file)` and `store_app_data(tag, file, shared?)` usages deprecated. Use `write_file` instead.
@@ -525,6 +538,8 @@ Evaluates the expression `expr` with different dimension execution context. `smt
 world-localized block, so not `block('stone')`, or a string representing a dimension like:
  `'nether'`, `'the_nether'`, `'end'` or `'overworld'`, etc.
  
+Throws `unknown_dimension` if provided dimension can't be found.
+ 
 ### `view_distance()`
 Returns the view distance of the server.
 

docs/scarpet/api/BlocksAndWorldAccess.md

@@ -21,6 +21,8 @@ when it was used. Block values passed in various places like `scan` functions, e
 its properties are needed. This means that if the block at the location changes before its queried in the program this 
 might result in getting the later state, which might not be desired. Consider the following example:
 
+Throws `unknown_block` if provided input is not valid.
+
 <pre>set(10,10,10,'stone');
 scan(10,10,10,0,0,0, b = _);
 set(10,10,10,'air');
@@ -50,6 +52,8 @@ properties that the original source block may have contained.
 
 The returned value is either the block state that has been set, or `false` if block setting was skipped, or failed
 
+Throws `unknown_block` if provided block to set is not valid
+
 <pre>
 set(0,5,0,'bedrock')  => bedrock
 set(l(0,5,0), 'bedrock')  => bedrock
@@ -128,6 +132,8 @@ but doesn't open chests / containers, so have no effect on interactive blocks, l
 Returns true if placement/use was 
 successful, false otherwise.
 
+Throws `unknown_item` if `item` doesn't exist
+
 <pre>
 place_item('stone',x,y,z) // places a stone block on x,y,z block
 place_item('piston,x,y,z,'down') // places a piston facing down
@@ -146,6 +152,8 @@ If type is `null`, POI at position is removed. In any case, previous POI is also
 Interestingly, `unemployed`, and `nitwit` are not used in the game, meaning, they could be used as permanent spatial 
 markers for scarpet apps. `meeting` is the only one with increased max occupancy of 32.
 
+Throws `unknown_poi` if the provided point of interest doesn't exist 
+
 ### `set_biome(pos, biome_name, update=true)`
 
 Changes the biome at that block position. if update is specified and false, then chunk will not be refreshed
@@ -156,6 +164,8 @@ is only effective if you set it at y=0, and affects the entire column of. In the
 specific Y coordinate of the biome you want to change, and it affects roughly 4x4x4 area (give or take some random
 noise).
 
+Throws `unknown_biome` if the `biome_name` doesn't exist.
+
 ### `update(pos)`
 
 Causes a block update at position.
@@ -180,6 +190,8 @@ In item context, `true` means that breaking item has no nbt to use, `null` indic
 considered broken in process, and `nbt` type value, for a resulting NBT tag on a hypothetical tool. Its up to the 
 programmer to use that nbt to apply it where it belong
 
+Throws `unknown_item` if `tool` doesn't exist.
+
 Here is a sample code that can be used to mine blocks using items in player inventory, without using player context 
 for mining. Obviously, in this case the use of `harvest` would be much more applicable:
 
@@ -271,6 +283,8 @@ back in state definition in various applications where block properties are requ
 
 `block_state` can also accept block names as input, returning block's default state.
 
+Throws `unknown_block` if the provided input is not valid.
+
 <pre>
 set(x,y,z,'iron_trapdoor','half','top'); block_state(x,y,z)  => {waterlogged: false, half: top, open: false, ...}
 set(x,y,z,'iron_trapdoor','half','top'); block_state(x,y,z,'half')  => top
@@ -291,6 +305,8 @@ Without arguments, returns list of available tags, with block supplied (either b
 of tags the block belongs to, and if a tag is specified, returns `null` if tag is invalid, `false` if this block doesn't belong 
 to this tag, and `true` if the block belongs to the tag.
 
+Throws `unknown_block` if `block` doesn't exist
+
 ### `block_data(pos)`
 
 Return NBT string associated with specific location, or null if the block does not carry block data. Can be currently 
@@ -325,9 +341,9 @@ poi(x,y,z,5) => [['nether_portal',0,[7,8,9]],['nether_portal',0,[7,9,9]]] // two
 
 Without arguments, returns the list of biomes in the world.
 
-With block, or name, returns the name of the biome in that position, or null, if provided biome is not valid. 
+With block, or name, returns the name of the biome in that position, or throws `'unknown_biome'` if provided biome or block are not valid. 
 
-With an optional feature, it returns value for the specified attribute for that biome. Available and querable features include:
+With an optional feature, it returns value for the specified attribute for that biome. Available and queryable features include:
 * `'top_material'`: unlocalized block representing the top surface material
 * `'under_material'`: unlocalized block representing what sits below topsoil
 * `'category'`: the parent biome this biome is derived from. Possible values include:
@@ -724,6 +740,7 @@ If structure is not specified, it will return a set of structure names that are
 as keys, and same type of map values as with a single structure call. An empty set or an empty map would indicate that nothing
 should be generated there.
 
+Throws `unknown_structure` if structure doesn't exist.
 
 ### `structures(pos), structures(pos, structure_name)`
 
@@ -757,6 +774,8 @@ structure starts.
 Requires a `Structure Variant` or `Standard Structure` name (see above). If standard name is used, the variant of the 
 structure may depend on the biome, otherwise the default structure for this type will be generated.
 
+Throws `unknown_structure` if structure doesn't exist.
+
 ### `plop(pos, what)`
 
 Plops a structure or a feature at a given `pos`, so block, triple position coordinates or a list of coordinates. 

docs/scarpet/api/Inventories.md

@@ -28,14 +28,16 @@ an inventory, all API functions typically do nothing and return null.
 
 Most items returned are in the form of a triple of item name, count, and nbt or the extra data associated with an item. 
 
-### item_list(tag?)
+### `item_list(tag?)`
 
 With no arguments, returns a list of all items in the game. With an item tag provided, list items matching the tag, or `null` if tag is not valid.
 
-### item_tags(item, tag?)
+### `item_tags(item, tag?)`
 
 Returns list of tags the item belongs to, or, if tag is provided, `true` if an item maches the tag, `false` if it doesn't and `null` if that's not a valid tag
 
+Throws `unknown_item` if item doesn't exist.
+
 ### `stack_limit(item)`
 
 Returns number indicating what is the stack limit for the item. Its typically 1 (non-stackable), 16 (like buckets), 
@@ -43,6 +45,8 @@ or 64 - rest. It is recommended to consult this, as other inventory API function
 it is up to the programmer to keep it at bay. As of 1.13, game checks for negative numbers and setting an item to 
 negative is the same as empty.
 
+Throws `unknown_item` if item doesn't exist.
+
 <pre>
 stack_limit('wooden_axe') => 1
 stack_limit('ender_pearl') => 16
@@ -53,6 +57,8 @@ stack_limit('stone') => 64
 
 Returns the string representing the category of a given item, like `building_blocks`, `combat`, or `tools`.
 
+Throws `unknown_item` if item doesn't exist.
+
 <pre>
 item_category('wooden_axe') => tools
 item_category('ender_pearl') => misc
@@ -175,6 +181,8 @@ while( (slot = inventory_find(p, 'diamond', slot)) != null, 41, drop_item(p, slo
 inventory_drop(x,y,z, 0) => 64 // removed and spawned in the world a full stack of items
 </pre>
 
+Throws `unknown_item` if item doesn't exist.
+
 ### `inventory_remove(inventory, item, amount?)`
 
 Removes amount (defaults to 1) of item from inventory. If the inventory doesn't have the defined amount, nothing 

docs/scarpet/api/Scoreboard.md

@@ -14,6 +14,8 @@ Adds a new objective to scoreboard. If `criterion` is not specified, assumes `'d
 If the objective already exists, changes the criterion of that objective and returns `false`. If the criterion was not specified but the objective already exists, returns the current criterion.
 If the objective was added, returns `true`. If nothing is affected, returns `null`
 
+Throws `unknown_criterion` if criterion doesn't exist.
+
 <pre>
 scoreboard_add('counter')
 scoreboard_add('lvl','level')

docs/scarpet/language/FunctionsAndControlFlow.md

@@ -234,15 +234,73 @@ returns everywhere, but it would often lead to a messy code.
 
 It terminates entire program passing `expr` as the result of the program execution, or null if omitted.
 
-### `try(expr, catch_expr(_)?) ... throw(value?)`
+### `try(expr)` `try(expr, user_catch_expr)` `try(expr, type, catch_expr, type?, catch_expr?, ...)`
 
-`try` function evaluates expression, and continues further unless `throw` function is called anywhere 
-inside `expr`. In that case the `catch_expr` is evaluates with `_` set to the argument `throw` was called with. 
-This mechanic accepts skipping thrown value - it throws null instead, and catch expression - then try returns 
-null as well This mechanism allows to terminate large portion of a convoluted call stack and continue program 
-execution. There is only one level of exceptions currently in carpet, so if the inner function also defines 
-the `try` catchment area, it will received the exception first, but it can technically rethrow the value its 
-getting for the outer scope. Unhandled throw acts like an exit statement.
+`try` evaluates expression, allowing capturing exceptions that would be thrown inside `expr` statement. The exceptions can be
+thrown explicitly using `throw()` or internally by scarpet where code is correct but detects illegal state. The 2-argument form
+catches only user-thrown exceptions and one argument call `try(expr)` is equivalent to `try(expr, null)`, 
+or `try(expr, 'user_exception', null)`. If multiple `type-catch` pairs are defined, the execution terminates on the first 
+applicable type for the exception thrown. Therefore, even if the caught exception matches multiple filters, only 
+the first matching block will be executed.
+
+Catch expressions are evaluated with 
+`_` set to the value associated with the exception and `_trace` set to contain details about point of error (token, and line and 
+column positions), call stack and local
+variables at the time of failure. The `type` will catch any exception of that type and any subtype of this type.
+  
+
+You can use `try` mechanism to exit from large portion of a convoluted call stack and continue program execution, although catching
+exceptions is typically much more expensive comparing to not throwing them.
+
+The `try` function allows you to catch some scarpet exceptions for cases covering invalid data, like invalid
+blocks, biomes, dimensions and other things, that may have been modified by datapacks, resourcepacks or other mods,
+or when an error is outside of the programmers scope, such as problems when reading or decoding files.
+
+This is the hierarchy of the exceptions that could be thrown/caught in the with the `try` function:
+- `exception`: This is the base exception. Catching `'exception'` allows to catch everything that can be caught, 
+but like everywhere else, doing that sounds like a bad idea.
+  - `value_exception`: This is the parent for any exception that occurs due to an 
+  incorrect argument value provided to a built-in function
+    - `unknown_item`, `unknown_block`, `unknown_biome`, `unknown_sound`, `unknown_particle`, 
+    `unknown_poi_type`, `unknown_dimension`, `unknown_structure`, `unknown_criterion`: Specific 
+    errors thrown when a specified internal name does not exist or is invalid.
+  - `io_exception`: This is the parent for any exception that occurs due to an error handling external data.
+    - `nbt_read_error`: Incorrect input NBT file.
+    - `json_read_error`: Incorrect input JSON data.
+  - `user_exception`: Exception thrown by default with `throw` function.
+  
+Synopsis:
+<pre>
+inner_call() ->
+(
+   aaa = 'booyah';
+   try(
+      for (range(10), item_tags('stick'+_*'k'));
+   ,
+      print(_trace) // not caught, only catching user_exceptions
+   )
+);
+
+outer_call() -> 
+( 
+   try(
+      inner_call()
+   , 'exception', // catching everything
+      print(_trace)
+   ) 
+);
+</pre>
+Producing:
+```
+{stack: [[<app>, inner_call, 1, 14]], locals: {_a: 0, aaa: booyah, _: 1, _y: 0, _i: 1, _x: 0, _z: 0}, token: [item_tags, 5, 23]}
+```
+
+### `throw(value?)`, `throw(type, value)`, `throw(subtype, type, value)`
+
+Throws an exception that can be caught in a `try` block (see above). If ran without arguments, it will throw a `user_exception` 
+passing `null` as the value to the `catch_expr`. With two arguments you can mimic any other exception type thrown in scarpet.
+With 3 arguments, you can specify a custom exception acting as a `subtype` of a provided `type`, allowing to customize `try` 
+statements with custom exceptions.
 
 ### `if(cond, expr, cond?, expr?, ..., default?)`
 

docs/scarpet/resources/editors/idea/3.txt

@@ -4,6 +4,7 @@ _i
 _x
 _y
 _z
+_trace
 euler
 false
 null

docs/scarpet/resources/editors/npp/scarpet.xml

@@ -91,7 +91,7 @@
             </Keywords>
             <Keywords name="Keywords3">euler pi null true false</Keywords>
             <Keywords name="Keywords4">x y z p</Keywords>
-            <Keywords name="Keywords5">_ _i _a _x _y _z</Keywords>
+            <Keywords name="Keywords5">_ _i _a _x _y _z _trace</Keywords>
             <Keywords name="Keywords6">global_</Keywords>
             <Keywords name="Keywords7">
                 __command