`class Base`

Provides structured access to a project directory which contains source code and guides.

Usage

To get an instance for the current project, use Base#instance.

Definitions

`def initialize(root = Dir.pwd)`

Initialize the project with the given root path.

Signature

parameter　root　String: The file-system path to the root of the project.

Implementation

def initialize(root = Dir.pwd)
	@root = root
	
	@source_path = Utopia::Path["/source"]
	
	@index = Decode::Index.new
	
	@links = Utopia::Content::Links.new(@root)
end

`attr :root`

The file-system path to the root of the project.

Signature

attribute　String

`attr :index`

The source code index which is used for generating pages.

Signature

attribute　Decode::Index

`def path_for(file_name)`

Return the absolute path for the given file name, if it exists in the project.

Example: Get README path

base = Utopia::Project::Base.new
base.path_for("readme.md") # => "/path/to/project/readme.md" or nil

Signature

parameter　file_name　String: The relative path to the project file, e.g. readme.md.
returns　String: The file-system path.

Implementation

def path_for(file_name)
	full_path = File.expand_path(file_name, @root)
	if File.exist?(full_path)
		return full_path
	end
end

`def update(paths)`

Update the index with the specified paths.

Signature

parameter　paths　Array(String): The paths to load and parse.

Implementation

def update(paths)
	@index.update(paths)
end

`def best(definitions)`

Given an array of defintions, return the best definition for the purposes of generating documentation.

Signature

returns　Decode::Definition | Nil

Implementation

def best(definitions)
	definitions.each do |definition|
		if definition.documentation
			return definition
		end
	end
	
	return definitions.first
end

`def lookup(path)`

Given a lexical path, find the best definition for that path.

Example: Lookup a definition

base = Utopia::Project::Base.local
_, definition = base.lookup(%i[Utopia Project Base])

Signature

returns　Tuple(Decode::Trie::Node, Decode::Definition)

Implementation

def lookup(path)
	if node = @index.trie.lookup(path.map(&:to_sym))
		return node, best(node.values)
	end
end

`def format(text, definition = nil, language: definition&.language, **options)`

Format the given text in the context of the given definition and language. See Utopia::Project::Base#document for details.

Example: Format text with code links

base = Utopia::Project::Base.new
base.format("See {Utopia::Project::Base#guides}.") # => XRB::MarkupString

Signature

returns　XRB::MarkupString

Implementation

def format(text, definition = nil, language: definition&.language, **options)
	if document = self.document(text, definition, language: language)
		return XRB::Markup.raw(
			document.to_html(**options)
		)
	end
end

`def document(text, definition = nil, language: definition&.language)`

Convert the given markdown text into HTML.

Updates source code references ({language identifier}) into links.

Example: Convert markdown to HTML

base = Utopia::Project::Base.new
doc = base.document("# Title")
doc.to_html # => "<h1>Title</h1>\n"

Signature

returns　Document

Implementation

def document(text, definition = nil, language: definition&.language)
	case text
	when Enumerable
		text = text.to_a.join("\n")
	when nil
		return nil
	end
	
	Document.new(text, self, definition: definition, default_language: language)
end

`def id_for(definition, suffix = nil)`

Compute a unique string which can be used as id attribute in the HTML output.

Example: Compute id for a definition

base = Utopia::Project::Base.local
_, definition = base.lookup(%i[Utopia Project Base])
base.id_for(definition) # => "Utopia::Project::Base"

Signature

returns　String

Implementation

def id_for(definition, suffix = nil)
	if suffix
		"#{definition.qualified_name}-#{suffix}"
	else
		definition.qualified_name
	end
end

`def link_for(definition)`

Compute a link href to the given definition for use within the HTML output.

Example: Link to a definition

base = Utopia::Project::Base.local
_, definition = base.lookup(%i[Utopia Project Base])
base.link_for(definition).to_s # => "/source/utopia/project/index#Utopia::Project::Base"

Signature

returns　XRB::Reference

Implementation

def link_for(definition)
	path = definition.lexical_path.map{|entry| entry.to_s}
	
	if definition.container?
		return XRB::Reference.new(@source_path + path + "index")
	else
		name = path.pop
		return XRB::Reference.new(@source_path + path + "index", fragment: id_for(definition))
	end
end

`def guides`

Enumerate over all available guides in order.

Example: List guide titles

base = Utopia::Project::Base.new
base.guides.each do |guide|
	puts guide.title
end

Signature

yields　{|guide| ...}

If a block is given.

parameter　guide　Guide

returns　Enumerator(Guide)

If no block given.

Implementation

def guides
	return to_enum(:guides) unless block_given?
	
	@links.index("/guides").each do |link|
		guide_path = File.join(@root, link.path)
		
		next unless File.directory?(guide_path)
		
		yield Guide.new(self, guide_path, link.info)
	end
end

`def gemspec`

Load and return the gemspec for this project.

Signature

returns　Gem::Specification | nil: The loaded gemspec, or nil if not found.

Implementation

def gemspec
	if gemspec_path = self.gemspec_path
		@gemspec ||= ::Gem::Specification.load(File.join(@root, gemspec_path))
	end
end