4.45. 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.45.1. SECTION.new(Title Blocks Subsections)

SECTION.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.45.2. SECTION.is?(Val)

SECTION.is? returns whether Val is a section.

4.45.3. type section

A section in a doc.

4.45.3.1. Section.op_eq(Another_section)

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

4.45.3.2. Section.title

title method returns the title of the section.

4.45.3.3. Section.blocks

blocks method returns the blocks in the section.

4.45.3.4. Section.subsections

subsections method returns the subsections of the section.

4.45.3.5. Section.to_json_val

to_json_val converts the 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.45.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=[])