Module: Udb::Helpers::AntoraUtils

Defined in:
lib/udb_helpers/backend_helpers.rb

Class Method Summary collapse

Class Method Details

The syntax “class << self” causes all methods to be treated as class methods. Convert proprietary link format to legal AsciiDoc links.

They are converted to AsciiDoc external cross references in the form:

xref:<module>:<file>.adoc:#<anchor_name>[<link_text>])

where <> don’t appear in the actual cross reference (just there to indicate variable content).

For example,

%%UDB_DOC_LINK%inst;add;add instruction%%

is converted to:

xref:insts:add.adoc#udb:doc:add[add instruction]

Antora supports the module name after the “xref:”. In the example above, it the module name is “insts” and corresponds to the directory name the add.adoc file is located in. For more details, see:

https://docs.antora.org/antora/latest/page/xref/

and then

https://docs.antora.org/antora/latest/page/resource-id-coordinates/

Parameters:

  • path_or_str (Pathname or String)

Returns:



389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'lib/udb_helpers/backend_helpers.rb', line 389

def self.resolve_links(path_or_str)
  str =
    if path_or_str.is_a?(Pathname)
      path_or_str.read
    else
      path_or_str
    end
  str.gsub(/%%UDB_DOC_LINK%([^;%]+)\s*;\s*([^;%]+)\s*;\s*([^%]+)%%/) do
    type = Regexp.last_match[1]
    name = Regexp.last_match[2]
    link_text = Regexp.last_match[3]

    case type
    when "ext"
      "xref:exts:#{name}.adoc#udb:doc:ext:#{name}[#{link_text}]"
    when "ext_param"
      ext_name, param_name = name.split(".")
      "xref:exts:#{ext_name}.adoc#udb:doc:ext_param:#{ext_name}:#{param_name}[#{link_text}]"
    when "inst"
      "xref:insts:#{name}.adoc#udb:doc:inst:#{name}[#{link_text}]"
    when "csr"
      "xref:csrs:#{name}.adoc#udb:doc:csr:#{name}[#{link_text}]"
    when "csr_field"
      csr_name, field_name = name.split("*")
      "xref:csrs:#{csr_name}.adoc#udb:doc:csr_field:#{csr_name}:#{field_name}[#{link_text}]"
    when "func"
      # All functions are in the same file called "funcs.adoc".
      "xref:funcs:funcs.adoc#udb:doc:func:#{name}[#{link_text.gsub(']', '\]')}]"
    else
      raise "Unhandled link type of '#{type}' for '#{name}' with link_text '#{link_text}'"
    end
  end.gsub(/%%IDL_CODE_LINK%([^;%]+)\s*;\s*([^;%]+)\s*;\s*([^%]+)%%/) do
    type = Regexp.last_match[1]
    name = Regexp.last_match[2]
    link_text = Regexp.last_match[3]

    case type
    when "inst"
      inst_name, id = name.split(".")
      "xref:insts:#{inst_name}.adoc#idl:code:inst:#{inst_name}:#{id}[#{link_text}]"
    # TODO: Add csr and csr_field support
    else
      raise "Unhandled link type of '#{type}' for '#{name}' with link_text '#{link_text}'"
    end
  end
end