Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

User guide documentation update #5

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

User guide documentation update #5

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
20a399b
user_guide: demonstrate use of hexadecimal notation in enums
davidhicks Apr 11, 2017
e8e3fe2
user_guide: add example for use of _parent
davidhicks Apr 11, 2017
e5a6375
user_guide: demonstrate reference to enum values by id
davidhicks Apr 11, 2017
78f6e58
user_guide: add section on streams and substreams
davidhicks Apr 11, 2017
5f258c8
user_guide: add pitfall section on size/substreams
davidhicks Apr 11, 2017
25e86c7
user_guide: add min/max methods for arrays
davidhicks Apr 11, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 67 additions & 1 deletion user_guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -380,6 +380,21 @@ enums:
17: udp
----

Alternatively, hexadecimal notation can also be used to define an enumeration:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Totally ok, but I'd also noted that this is a service provided by YAML, not something specific to KS.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking that a new section of the document could be created for general syntax and a very brief overview of YAML and what it provides. This example I provided may be better suited there.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some Construct features are Python features, but I would advertise them just the same. Purpose of documentation is to show capabilities, not attribution. =) Just saying.


[source,yaml]
----
seq:
- id: key
type: u4
enum: keys
enums:
keys:
0x77696474: width #widt
0x68656967: height #heig
0x64657074: depth #dept
----

There are two things that should be done to declare a enum:

1. We add `enums` key on the type level (i.e. on the same level as
Expand Down Expand Up @@ -472,7 +487,25 @@ structure:

[source,yaml]
----
TODO
seq:
- id: header
type: file_header
- id: metadata
type: metadata_section
types:
file_header:
seq:
- id: version
type: u2
metadata_section:
seq:
- id: author
type: strz
encoding: UTF-8
- id: publisher
type: strz
encoding: UTF-8
if: _parent.header.version >= 2
----

==== `_root`
Expand Down Expand Up @@ -799,6 +832,39 @@ other value which was not listed explicitly.
_: rec_type_unknown
----

If an enumeration has already been defined, you can use references to
items in the enumeration instead of specifying integers a second time:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, if you defined key as enum, then you don't have much choice. You can't compare enums to integers without additional conversions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm good point, I'll update the text accordingly


[source,yaml]
----
seq:
- id: key
type: u4
enum: keys
- id: data
type:
switch-on: key
cases:
keys::width: data_field_width
keys::height: data_field_height
keys::depth: data_field_depth
types:
data_field_width:
seq:
#...
data_field_height:
seq:
#...
data_field_depth:
seq:
#...
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pedantic person in me cries for that misaligned #... ;)
And, anyway, seq is totally optional, so may be it's better to wrap it up as:

types:
  data_field_width: # ...
  data_field_height: # ...
  data_field_depth: # ...

for brevity.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, agreed

enums:
keys:
0x77696474: width #widt
0x68656967: height #heig
0x64657074: depth #dept
----

=== Instances: data beyond the sequence

So far we've done all the data specifications in `seq` - thus they'll
Expand Down