Class: Utopia::Project::Base

Inherits:
Object
  • Object
show all
Extended by:
Thread::Local
Defined in:
lib/utopia/project/base.rb

Overview

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(root = Dir.pwd) ⇒ Base

Initialize the project with the given root path.



55
56
57
58
59
60
61
62
63
 
# 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

Instance Attribute Details

#index ⇒ Object

The source code index which is used for generating pages.



71
72
73
 
# File 'lib/utopia/project/base.rb', line 71

def index
  @index
end

#root ⇒ Object (readonly)

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



67
68
69
 
# File 'lib/utopia/project/base.rb', line 67

def root
  @root
end

Class Method Details

.local ⇒ Object 



41
42
43
44
45
46
47
48
49
50
51
 
# 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

Instance Method Details

#best(definitions) ⇒ Object

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



91
92
93
94
95
96
97
98
99
 
# 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) ⇒ Object

Convert the given markdown text into HTML.

  • Updates source code references (‘identifier`) into links.

  • Uses Kramdown to convert the text into HTML.



133
134
135
136
137
138
139
 
# File 'lib/utopia/project/base.rb', line 133

def document(text, definition = nil, language: definition&.language)
  text = text&.gsub(/(?<!`){(.*?)}/) do |match|
    linkify($1, definition, language: language)
  end
  
  return Kramdown::Document.new(text, syntax_highlighter: nil)
end

#format(text, definition = nil, language: definition&.language) ⇒ Object

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



112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/utopia/project/base.rb', line 112

def format(text, definition = nil, language: definition&.language)
  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
    )
  end
end

#guides ⇒ Object

Enumerate over all available guides in order.



193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/utopia/project/base.rb', line 193

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) ⇒ Object

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



168
169
170
171
172
173
174
 
# File 'lib/utopia/project/base.rb', line 168

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

#link_for(definition) ⇒ Object

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



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/utopia/project/base.rb', line 178

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

#linkify(text, definition = nil, language: definition&.language) ⇒ Object

Replace source code references in the given text with HTML anchors.



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/utopia/project/base.rb', line 144

def linkify(text, definition = nil, language: definition&.language)
  reference = @index.languages.parse_reference(text, default_language: language)
  
  Trenni::Builder.fragment do |builder|
    if reference and definition = @index.lookup(reference, relative_to: definition)&.first
      builder.inline('a', href: link_for(definition)) do
        builder.inline('code', class: "language-#{definition.language.name}") do
          builder.text definition.qualified_form
        end
      end
    elsif reference
      builder.inline('code', class: "language-#{reference.language.name}") do
        builder.text text
      end
    else
      builder.inline('code') do
        builder.text text
      end
    end
  end
end

#lookup(path) ⇒ Object

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



103
104
105
106
107
 
# 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) ⇒ Object

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



76
77
78
79
80
81
 
# 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) ⇒ Object

Update the index with the specified paths.



85
86
87
 
# File 'lib/utopia/project/base.rb', line 85

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