4.46. kink/doc/model/SECTION

Provides sections in docs.

A section is a tree node of a kink doc.

The top level section corresponds to an entire doc.

The second level sections correspond to mods.

Sections on the third and further levels typically correspond to funs, types and methods.

4.46.1. SECTION.new(Title Blocks Subsections)

`new` makes a section.

Preconditions:

• `Title` must be a str

• `Blocks` must be a vec of blocks

• `Subsections` must be a vec of sections

4.46.2. SECTION.is?(Val)

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

4.46.3. type section

A section in a doc.

4.46.3.1. Section.op_eq(Another_section)

Two sections are equal when they have the same title, blocks and subsections.

Precondition:

• `Another_section` must be a section.

4.46.3.2. Section.title

`title` returns the title of the section.

4.46.3.3. Section.blocks

`blocks` returns the blocks of the section.

4.46.3.4. Section.subsections

`subsections` returns the subsections of the section.

4.46.3.5. Section.to_json_val

`to_json_val` converts `Section` to a JSON val.

Example:

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

:Doc <- SECTION.new(
  'Doc title'
  [ BLOCK.new_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"
# }

4.46.3.6. Section.depth

`depth` returns the depth of the tree of the section.

The depth 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.

4.46.3.7. Section.limit_depth(Max_depth)

`limit_depth` returns a section whose depth is smaller than or equal to `Max_depth`.

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

If the depth of `Section` is bigger than `Max_depth`, branches are flattened so that the result is limited to `Max_depth`.

Precondition:

• `Max_depth` must be an int num which is >= 2.

Usage note:

Formatters can use `limit_depth` to adapt the output to a specific format.

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

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

Preconditions:

• `Json_val` must be a json val output from Section.to_json_val.

• $config, if given, must be a fun which takes a `Conf` val.

`Conf` val has the following methods:

• Conf.on_success($success_cont): uses $success_cont as the success cont. If `on_success` is not called, VAL.identity is used as the default success cont.

• Conf.on_error($error_cont): uses $error_cont as the error cont. If `on_error` is not called, a fun which raises an exception is used as the default error cont.

When `from_json_val` can make a section val from `Json_val`, it tail-calls the success cont with the section.

When `from_json_val` fails to make a section, it tail-calls the error cont with an error message.

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=[Paragraph_block("This program outputs \"hello world\" to the standard output.") Paragraph_block("The exit status hall be 0 when it terminates without an error.")] subsections=[])