class Utopia::Project::Base

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

Attributes

index[R]

The source code index which is used for generating pages. @attribute [Decode::Index]

root[R]

The file-system path to the root of the project. @attribute [String]

Public Class Methods

local() click to toggle source
# File lib/utopia/project/base.rb, line 41
def self.local
        instance = self.new
        
        source_files = Dir.glob(
                File.expand_path("lib/**/*.rb", instance.root)
        )
        
        instance.update(source_files)
        
        return instance
end
new(root = Dir.pwd) click to toggle source

Initialize the project with the given root path. @parameter root [String] The file-system path to the root of the project.

# File lib/utopia/project/base.rb, line 55
def initialize(root = Dir.pwd)
        @root = root
        
        @source_path = Utopia::Path["/source"]
        
        @index = Decode::Index.new
        
        @links = Utopia::Content::Links.new(@root)
end

Public Instance Methods

best(definitions) click to toggle source

Given an array of defintions, return the best definition for the purposes of generating documentation. @returns [Decode::Definition | Nil]

# File lib/utopia/project/base.rb, line 91
def best(definitions)
        definitions.each do |definition|
                if definition.documentation
                        return definition
                end
        end
        
        return definitions.first
end
document(text, definition = nil, language: definition&.language) click to toggle source

Convert the given markdown text into HTML.

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

@returns [Document]

# File lib/utopia/project/base.rb, line 156
def document(text, definition = nil, language: definition&.language)
        Document.new(text, self, definition: definition, default_language: language)
end
document_for(definition) click to toggle source
# File lib/utopia/project/base.rb, line 109
def document_for(definition)
        document_path = File.join("lib", definition.lexical_path.map{|_| _.to_s.downcase}) + ".md"
        
        if File.exist?(document_path)
                document = self.document(File.read(document_path), definition)
                
                if document.first_child.type == :header
                        document.first_child.delete
                end
                
                return document
        end
end
format(text, definition = nil, language: definition&.language, **options) click to toggle source

Format the given text in the context of the given definition and language. See {document} for details. @returns [Trenni::MarkupString]

# File lib/utopia/project/base.rb, line 136
def format(text, definition = nil, language: definition&.language, **options)
        case text
        when Enumerable
                text = text.to_a.join("\n")
        when nil
                return nil
        end
        
        if document = self.document(text, definition, language: language)
                return Trenni::MarkupString.raw(
                        document.to_html(**options)
                )
        end
end
guides() { |guide| ... } click to toggle source

Enumerate over all available guides in order. @yields {|guide| …} If a block is given.

@parameter guide [Guide]

@returns [Enumerator(Guide)] If no block given.

# File lib/utopia/project/base.rb, line 187
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)
        end
end
id_for(definition, suffix = nil) click to toggle source

Compute a unique string which can be used as `id` attribute in the HTML output. @returns [String]

# File lib/utopia/project/base.rb, line 162
def id_for(definition, suffix = nil)
        if suffix
                "#{definition.qualified_name}-#{suffix}"
        else
                definition.qualified_name
        end
end
linkify(text, definition, language: definition&.language) click to toggle source
# File lib/utopia/project/base.rb, line 123
def linkify(text, definition, language: definition&.language)
        rewriter = Linkify.new(self, language, text)
        
        code = language.code_for(text, @index, relative_to: definition)
        
        code.extract(rewriter)
        
        return rewriter.apply
end
lookup(path) click to toggle source

Given a lexical path, find the best definition for that path. @returns [Tuple(Decode::Trie::Node, Decode::Definition)]

# File lib/utopia/project/base.rb, line 103
def lookup(path)
        if node = @index.trie.lookup(path.map(&:to_sym))
                return node, best(node.values)
        end
end
path_for(file_name) click to toggle source

Return the absolute path for the given file name, if it exists in the project. @parameter file_name [String] The relative path to the project file, e.g. `README.md`. @returns [String] The file-system path.

# File lib/utopia/project/base.rb, line 76
def path_for(file_name)
        full_path = File.expand_path(file_name, @root)
        if File.exist?(full_path)
                return full_path
        end
end
update(paths) click to toggle source

Update the index with the specified paths. @parameter paths [Array(String)] The paths to load and parse.

# File lib/utopia/project/base.rb, line 85
def update(paths)
        @index.update(paths)
end