Add valid to schema

[rotu]

This was previously undocumented per kaitai-io/kaitai_struct#944

Here's my attempt to document the admissible structure based on the current implementation and documentation at:

https://github.com/kaitai-io/kaitai_struct_compiler/blob/751f059f4a34dddcf7d8f75bd8f89c3ee07f53fc/shared/src/main/scala/io/kaitai/struct/format/ValidationSpec.scala

https://github.com/kaitai-io/kaitai_struct_compiler/blob/751f059f4a34dddcf7d8f75bd8f89c3ee07f53fc/shared/src/main/scala/io/kaitai/struct/languages/components/ValidateOps.scala

https://github.com/kaitai-io/kaitai_struct_doc/blob/c87ae4cb447abfb043bcbade1c8d601037469142/user_guide.adoc#valid-values

[generalmimon]

expected value that the parser should encounter at this point (or throw an error).

This entire sentence is weird and inaccurate (I don't like "expected value", "this point" or "(or throw an error)"). Instead of explaining how, I'll rather come up with something myself when I have time.

Unlike contents, this is the value after parsing.

What do you mean by this? Since 0.9 which introduced valid, contents has become a syntactic sugar for valid, so their runtime semantics is the same (the difference is that contents only works with fixed byte arrays and it doesn't use the expression language but a very special schema, but on the other hand the byte length is derived automatically, whereas valid also works with various data types and you can use the expression language to dynamically calculate the values used in valid/{eq,expr,any-of,min,max} constraints).

In other words, these two attributes are exactly equivalent and they generate the same code:

seq:
  - id: magic
    contents: [0xcd, 0x80]

seq:
  - id: magic
    size: 2
    valid: '[0xcd, 0x80]'

[rotu]

This entire sentence is weird and inaccurate (I don't like "expected value", "this point" or "(or throw an error)"). Instead of explaining how, I'll rather come up with something myself when I have time.

Agreed. I don't understand this very well so I just took a quick stab with my limited understanding. You're right - valid is considerably more flexible, and I'll update to fix it.

Unlike contents, this is the value after parsing.

What do you mean by this?

For instance, I have a value that's expected to be 0x0000ffff. { type: u4, valid: 0x0000ffff } checks that value after parsing (perhaps a better word would be "casting") it to its declared type (i.e. `u4').

---

I think the biggest limit to my understanding with the schema is that it's not quite clear which strings are supposed to be expressions, identifiers, or literal strings.