Class: Brief::Briefcase
- Inherits:
-
Object
show all
- Includes:
- Documentation, DSL
- Defined in:
- lib/brief/briefcase.rb,
lib/brief/briefcase/initializer.rb,
lib/brief/briefcase/documentation.rb
Defined Under Namespace
Modules: Documentation
Classes: Initializer
Instance Attribute Summary collapse
Class Method Summary
collapse
Instance Method Summary
collapse
#render_documentation, #schema_map
Methods included from DSL
#action, #command, #define, #extend, #view
Constructor Details
#initialize(options = {}) ⇒ Briefcase
Creates a new briefcase
options:
- root: (required) the root folder of the briefcase project. will default to PWD
- app: (optional) the name of the app this briefcase should use
- logger: a logger instance, will default to Logger.new(STDOUT)
- href_builder: (optional) reference to a block which will be used to post-process any generated
href values for the documents in this briefcase. This will generally be used by
apps which render the briefcase content.
- asset_finder: (optional) reference to a block which will be used to find assets when used as attachments
or when embedding inline:svg through the special image markdown syntax
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
|
# File 'lib/brief/briefcase.rb', line 37
def initialize(options = {})
@options = options.to_mash
debug "Created briefcase instance #{ object_id } at #{ root }"
load_configuration
use(:app, options[:app]) if options[:app]
load_model_definitions
if Brief.case(false).nil?
Brief.case = self
end
@href_builder = options.fetch(:href_builder) { Brief.href_builder }
@asset_finder = options.fetch(:asset_finder) { method(:find_asset) }
Brief.cases[root.basename.to_s] ||= self
@logger = options.fetch(:logger, nil)
debug "Loading briefcase lib entries"
load_briefcase_lib_entries()
end
|
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(meth, *args, &block) ⇒ Object
386
387
388
389
390
391
392
393
394
395
|
# File 'lib/brief/briefcase.rb', line 386
def method_missing(meth, *args, &block)
if Brief.views.key?(meth.to_sym)
block = Brief.views[meth.to_sym]
block.call(self, args.)
elsif repository.respond_to?(meth)
repository.send(meth, *args, &block)
else
super
end
end
|
Instance Attribute Details
#asset_finder ⇒ Object
Returns the value of attribute asset_finder.
20
21
22
|
# File 'lib/brief/briefcase.rb', line 20
def asset_finder
@asset_finder
end
|
#href_builder ⇒ Object
Returns the value of attribute href_builder.
20
21
22
|
# File 'lib/brief/briefcase.rb', line 20
def href_builder
@href_builder
end
|
#model_definitions ⇒ Object
Returns the value of attribute model_definitions.
17
18
19
|
# File 'lib/brief/briefcase.rb', line 17
def model_definitions
@model_definitions
end
|
#options ⇒ Object
Returns the value of attribute options.
17
18
19
|
# File 'lib/brief/briefcase.rb', line 17
def options
@options
end
|
Class Method Details
.create_new_briefcase(options = {}) ⇒ Object
Instance Method Details
#app_config_path ⇒ Object
275
276
277
|
# File 'lib/brief/briefcase.rb', line 275
def app_config_path
uses_app? && app_path.join("config.rb")
end
|
#app_models ⇒ Object
287
288
289
|
# File 'lib/brief/briefcase.rb', line 287
def app_models
app_namespace.constants.map {|c| app_namespace.const_get(c) }
end
|
#app_models_folder ⇒ Object
279
280
281
|
# File 'lib/brief/briefcase.rb', line 279
def app_models_folder
uses_app? && app_path.join("models")
end
|
#app_namespace ⇒ Object
283
284
285
|
# File 'lib/brief/briefcase.rb', line 283
def app_namespace
Brief::Apps.find_namespace(options[:app])
end
|
#app_path ⇒ Object
271
272
273
|
# File 'lib/brief/briefcase.rb', line 271
def app_path
uses_app? && Brief::Apps.path_for(options[:app]).to_pathname
end
|
#as_default(params = {}) ⇒ Object
TODO The serialization of an entire briefcase at once is important enough to be its own module
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
# File 'lib/brief/briefcase.rb', line 173
def as_default(params={})
params.symbolize_keys!
base = info_hash
if params[:include_data] || params[:data]
base[:data] = data.as_json
end
if params[:include_schema] || params[:schema]
base[:schema] = schema_map(!!(params[:include_schema] == "full"))
end
if params[:include_documentation] || params[:documentation]
base[:documentation] = render_documentation
end
if params[:include_models] || params[:models]
model_settings = {
docs_path: docs_path
}
%w(urls content rendered attachments).each do |opt|
model_settings[opt.to_sym] = !!(params[opt.to_sym] || params["include_#{opt}".to_sym])
end
all = all_models.compact
base[:models] = all.map do |m|
m.document.refresh! if params[:refresh_models]
m.as_json(model_settings)
end
end
base
end
|
#as_full_export(options = {}) ⇒ Object
210
211
212
213
214
215
216
217
218
|
# File 'lib/brief/briefcase.rb', line 210
def as_full_export(options={})
options.reverse_merge!(content: true,
rendered: true,
models: true,
schema: true,
documentation: true,
attachments: true)
as_default(options)
end
|
#assets_path ⇒ Object
332
333
334
|
# File 'lib/brief/briefcase.rb', line 332
def assets_path
root.join(options.fetch(:assets_path) { config.assets_path }).expand_path
end
|
#assets_trail ⇒ Object
348
349
350
351
352
353
|
# File 'lib/brief/briefcase.rb', line 348
def assets_trail
@assets_trail ||= Hike::Trail.new(assets_path).tap do |trail|
trail.append_extensions '.svg', '.png', '.pdf', '.jpg', '.gif', '.mov'
assets_path.children.select(&:directory?).each {|dir| trail.prepend_path(assets_path); trail.append_path(assets_path.join(dir)) }
end
end
|
#briefcase_lib_path ⇒ Object
344
345
346
|
# File 'lib/brief/briefcase.rb', line 344
def briefcase_lib_path
root.join(options.fetch(:lib_path) { config.lib_path }).expand_path
end
|
#cache_key ⇒ Object
124
125
126
|
# File 'lib/brief/briefcase.rb', line 124
def cache_key
"#{slug}:#{repository.cache_key}"
end
|
#config(&block) ⇒ Object
234
235
236
237
238
|
# File 'lib/brief/briefcase.rb', line 234
def config(&block)
Brief::Configuration.instance.tap do |cfg|
cfg.instance_eval(&block) if block.respond_to?(:call)
end
end
|
#data ⇒ Object
226
227
228
|
# File 'lib/brief/briefcase.rb', line 226
def data
@data ||= data!
end
|
#data! ⇒ Object
230
231
232
|
# File 'lib/brief/briefcase.rb', line 230
def data!
@data = Brief::Data::Wrapper.new(root: data_path)
end
|
#data_path ⇒ Object
340
341
342
|
# File 'lib/brief/briefcase.rb', line 340
def data_path
root.join(options.fetch(:data_path) { config.data_path }).expand_path
end
|
#data_trail ⇒ Object
363
364
365
366
367
368
|
# File 'lib/brief/briefcase.rb', line 363
def data_trail
@docs_trail ||= Hike::Trail.new(data_path).tap do |trail|
trail.append_extensions '.yaml', '.js', '.json', '.xls', '.xlsx', '.csv', '.txt'
trail.append_path(data_path)
end
end
|
#debug(message) ⇒ Object
70
71
72
|
# File 'lib/brief/briefcase.rb', line 70
def debug message
logger.debug(message) if debug?
end
|
#debug? ⇒ Boolean
74
75
76
|
# File 'lib/brief/briefcase.rb', line 74
def debug?
options.fetch(:debug, nil) || ENV['BRIEF_DEBUG']
end
|
#docs_path ⇒ Object
336
337
338
|
# File 'lib/brief/briefcase.rb', line 336
def docs_path
root.join(options.fetch(:docs_path) { config.docs_path }).expand_path
end
|
#docs_trail ⇒ Object
355
356
357
358
359
360
|
# File 'lib/brief/briefcase.rb', line 355
def docs_trail
@docs_trail ||= Hike::Trail.new(docs_path).tap do |trail|
trail.append_extensions '.md', '.html.md', '.markdown'
docs_path.children.select(&:directory?).each {|dir| trail.prepend_path(docs_path); trail.append_path(docs_path.join(dir)) }
end
end
|
#find_asset(needle) ⇒ Object
327
328
329
330
|
# File 'lib/brief/briefcase.rb', line 327
def find_asset(needle)
found = assets_trail.find(needle)
found && Pathname(found)
end
|
#folder_name ⇒ Object
244
245
246
|
# File 'lib/brief/briefcase.rb', line 244
def folder_name
root.basename
end
|
#generic_model_class_for(document) ⇒ Object
#get_external_url_for(asset_path) ⇒ Object
166
167
168
|
# File 'lib/brief/briefcase.rb', line 166
def get_external_url_for(asset_path)
asset_finder.call(asset_path)
end
|
#get_href_for(brief_uri) ⇒ Object
162
163
164
|
# File 'lib/brief/briefcase.rb', line 162
def get_href_for(brief_uri)
href_builder.call(brief_uri)
end
|
#info_hash ⇒ Object
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
# File 'lib/brief/briefcase.rb', line 143
def info_hash
{
BRIEF_VERSION: Brief::VERSION,
views: Brief.views.keys,
key: folder_name.to_s.parameterize,
name: folder_name.to_s.titlecase,
settings: settings,
cache_key: cache_key,
root: root.to_s,
paths:{
docs_path: docs_path.to_s,
assets_path: assets_path.to_s,
models_path: models_path.to_s,
data_path: data_path.to_s,
lib_path: briefcase_lib_path.to_s
}
}
end
|
#load_briefcase_lib_entries ⇒ Object
78
79
80
81
82
83
84
85
|
# File 'lib/brief/briefcase.rb', line 78
def load_briefcase_lib_entries
begin
etc = Dir[briefcase_lib_path.join("**/*.rb")]
etc.each {|f| require(f) } if briefcase_lib_path.exist?
rescue => e
debug "Error while loading briefcase entries: #{ e.message }"
end
end
|
#load_configuration ⇒ Object
Loads the configuration for this briefcase, either from the current working directory or the configured path for the configuration file.
250
251
252
253
254
255
256
257
258
259
260
|
# File 'lib/brief/briefcase.rb', line 250
def load_configuration
config_path = options.fetch(:config_path) do
root.join('brief.rb')
end
if config_path.is_a?(String)
config_path = root.join(config_path)
end
run(config_path) if config_path.exist?
end
|
#load_model_definitions ⇒ Object
#log(message) ⇒ Object
66
67
68
|
# File 'lib/brief/briefcase.rb', line 66
def log message
logger.info(message)
end
|
#logger ⇒ Object
62
63
64
|
# File 'lib/brief/briefcase.rb', line 62
def logger
@logger ||= Logger.new(STDOUT)
end
|
#model(name_or_type) ⇒ Object
Returns a model name by its human readable description or its type alias
313
314
315
316
317
318
319
320
321
|
# File 'lib/brief/briefcase.rb', line 313
def model(name_or_type)
table = Brief::Model.table
table.fetch(name_or_type) do
table.values.find do |k|
k.name == name_or_type
end
end
end
|
#model_class_for(document) ⇒ Object
291
292
293
294
|
# File 'lib/brief/briefcase.rb', line 291
def model_class_for(document)
return generic_model_class_for(document) unless uses_app?
app_models.find {|k| k.type_alias == document.document_type } || generic_model_class_for(document)
end
|
#models_path ⇒ Object
370
371
372
373
374
375
376
377
378
379
380
|
# File 'lib/brief/briefcase.rb', line 370
def models_path
value = options.fetch(:models_path) { config.models_path }
if value.to_s.match(/\./)
Pathname(Brief.pwd).join(value)
elsif value.to_s.match(/\//)
Pathname(value)
else
root.join(value)
end
end
|
#present(style = "default", params = {}) ⇒ Object
Returns a Hash object which presents some view of the briefcase. Accepts a params hash of options that will be passed to the presenter.
The default presenter is Brief::Briefcase#as_default
113
114
115
116
117
118
119
120
121
122
|
# File 'lib/brief/briefcase.rb', line 113
def present(style="default", params={})
style = "default" if style.nil?
if respond_to?("as_#{style}")
send("as_#{style}", params)
elsif Brief.views.key?(style.to_sym)
block = Brief.views[style.to_sym]
block.call(self, params)
end
end
|
#repository ⇒ Object
382
383
384
|
# File 'lib/brief/briefcase.rb', line 382
def repository
@repository ||= Brief::Repository.new(self, options)
end
|
#root ⇒ Object
323
324
325
|
# File 'lib/brief/briefcase.rb', line 323
def root
Pathname(options.fetch(:root) { Brief.pwd }).expand_path
end
|
#run(code_or_file) ⇒ Object
262
263
264
265
|
# File 'lib/brief/briefcase.rb', line 262
def run(code_or_file)
code = code_or_file.is_a?(Pathname) ? code_or_file.read : code
instance_eval(code) rescue nil
end
|
#run_command(name, *args) ⇒ Object
Runs a command
Commands are defined in the briefcase configuration.
You define a command by passing a block. This block will get called with the briefcase, and whatever other arguments
93
94
95
96
97
98
99
100
101
|
# File 'lib/brief/briefcase.rb', line 93
def run_command(name, *args)
if handler = Brief.commands.fetch(name.to_sym)
block = handler[:handler]
args.unshift(self)
block.call(*args)
else
raise 'Command not found'
end
end
|
#run_command!(name, *args) ⇒ Object
runs a command but does not raise an error
104
105
106
|
# File 'lib/brief/briefcase.rb', line 104
def run_command!(name, *args)
run_command(name, *args) rescue nil
end
|
#server(options = {}) ⇒ Object
240
241
242
|
# File 'lib/brief/briefcase.rb', line 240
def server(options={})
@server ||= Brief::Server.new(self, options)
end
|
#settings ⇒ Object
132
133
134
|
# File 'lib/brief/briefcase.rb', line 132
def settings
@settings ||= settings!
end
|
#settings! ⇒ Object
136
137
138
139
140
141
|
# File 'lib/brief/briefcase.rb', line 136
def settings!
if root.join("settings.yml").exist?
y = YAML.load(root.join("settings.yml").read) rescue nil
(y || {}).to_mash
end
end
|
#slug ⇒ Object
128
129
130
|
# File 'lib/brief/briefcase.rb', line 128
def slug
options.fetch(:slug) { root.basename.to_s.parameterize }
end
|
#use(module_type = :app, module_id) ⇒ Object
220
221
222
223
224
|
# File 'lib/brief/briefcase.rb', line 220
def use(module_type=:app, module_id)
options[:app] = module_id.to_s
run(app_config_path) if app_path.try(&:exist?)
end
|
#uses_app? ⇒ Boolean
267
268
269
|
# File 'lib/brief/briefcase.rb', line 267
def uses_app?
options.key?(:app) && Brief::Apps.available?(options[:app].to_s)
end
|