6.47. kink/doc/model/SECTION

6.47.1. type section

A section of a kinkdoc.

See “Kinkdoc: API Documentation system” → “Data model” in the manual.

6.47.1.1. Section.title

`title` returns a `str` of the title of `Section`.

6.47.1.2. Section.blocks

`blocks` a `vec` of the `block` values of `Section`.

6.47.1.3. Section.subsections

`subsections` returns a `vec` of `section` values which are the subsections of `Section`.

6.47.1.4. Section.to_json_val

`to_json_val` returns a JSON value of `Section`.

See “Kinkdoc: API Documentation system” → “Data model” → “JSON Schema” in the manual.

Example

:SECTION.require_from('kink/doc/model/')
:BLOCK.require_from('kink/doc/model/')
:BLOCK_TYPE.require_from('kink/doc/model/')
:JSON.require_from('kink/json/')

:Doc <- SECTION.new(
  'Doc title'
  [ BLOCK.new(BLOCK_TYPE.paragraph 'hey!') ]
  [ SECTION.new(
      'Section title'
      []
      []
    )
  ]
)
:Json_val <- Doc.to_json_val
stdout.print_line(JSON.stringify(Json_val))
# Output:
# {
#   "blocks": [
#     {
#       "text": "hey!",
#       "type": "paragraph"
#     }
#   ],
#   "subsections": [
#     {
#       "blocks": [],
#       "subsections": [],
#       "title": "Section title"
#     }
#   ],
#   "title": "Doc title"
# }

6.47.1.5. Section.depth

`depth` returns an integer `num` of the depth of the tree of `Section`.

The depth of a `section` is defined as follows:

• If the `section` has no subsection, the depth is 1.

• If the `section` has one or more subsections, the depth of the `section` is the maximum depth of the subsections plus 1.

6.47.1.6. Section.limit_depth(Max_depth)

If the depth of `Section` is bigger than `Max_depth`, `limit_depth` returns a `section` which is not deeper than `Max_depth`. The result `section` has a same set of subsections as `Section`, except that branches deeper than `Max_depth` are flattened.

If the depth of `Section` is smaller than or equal to `Max_depth`, `limit_depth` returns `Section` itself.

Precondition

`Max_depth` must be an integer `num` which is bigger than or equal to 2.

Postcondition

`Result.depth` is smaller than or equal to `Max_depth`.

6.47.1.7. X == Y

Two sections are equal when they have equal titles, equal blocks and equal subsections.

Precondition

`Y` must be a `section`.

6.47.2. SECTION.new(Title Blocks Subsections)

`new` returns a new `section`.

Preconditions

`Title` must be a nonempty `str` which does not start or end with a whitespace character, and does not contain ASCII control characters.

`Blocks` must be a `vec` of `block` values.

`Subsections` must be a `vec` of `section` values.

6.47.3. SECTION.is?(Val)

`is?` returns whether `Val` is a `section`.

6.47.4. SECTION.from_json_val(Json_val ...[$config={}])

`from_json_val` makes a `section` value from `Json_val`.

Config methods:

• C.on_success($success): default = VAL.identity

• C.on_error($error): default = $raise

If `Json_val` matches the JSON Schema of kinkdoc sections, `from_json_val` tail-calls $success with a `section`.

If `Json_val` does not match the JSON Schema of kinkdoc sections, `from_json_val` tail-calls $error with a `str` of an error message.

Preconditions

`Json_val` must be a JSON value.

Example

:SECTION.require_from('kink/doc/model/')
:FLAT_MAP.require_from('kink/container/')

:Json_val <- FLAT_MAP.of(
  'title' 'Greeting program'
  'blocks' [
    FLAT_MAP.of(
      'type' 'paragraph'
      'text' 'This program outputs "hello world" to the standard output.'
    )
    FLAT_MAP.of(
      'type' 'paragraph'
      'text' 'The exit status hall be 0 when it terminates without an error.'
    )
  ]
  'subsections' []
)
:Section <- SECTION.from_json_val(Json_val)
stdout.print_line(Section.repr)
# => (section title="Greeting program" blocks=[(block type=BLOCK_TYPE.paragraph text="This program outputs \"hello world\" to the standard output.") (block type=BLOCK_TYPE.paragraph text="The exit status hall be 0 when it terminates without an error.")] subsections=[])