Module: Giblish

Defined in:
lib/giblish/utils.rb,
lib/giblish.rb,
lib/giblish/cmdline.rb,
lib/giblish/version.rb,
lib/giblish/application.rb,
lib/giblish/docid/docid.rb,
lib/giblish/config_utils.rb,
lib/giblish/configurator.rb,
lib/giblish/resourcepaths.rb,
lib/giblish/treeconverter.rb,
lib/giblish/conversion_info.rb,
lib/giblish/gitrepos/gititf.rb,
lib/giblish/adocsrc_providers.rb,
lib/giblish/docattr_providers.rb,
lib/giblish/search/expand_adoc.rb,
lib/giblish/search/searchquery.rb,
lib/giblish/subtreeinfobuilder.rb,
lib/giblish/gitrepos/history_pb.rb,
lib/giblish/search/textsearcher.rb,
lib/giblish/search/headingindexer.rb,
lib/giblish/search/request_manager.rb,
lib/giblish/gitrepos/checkoutmanager.rb,
lib/giblish/indexbuilders/verbatimtree.rb,
lib/giblish/gitrepos/gitsummaryprovider.rb,
lib/giblish/indexbuilders/dotdigraphadoc.rb,
lib/giblish/indexbuilders/depgraphbuilder.rb,
lib/giblish/indexbuilders/subtree_indices.rb,
lib/giblish/github_trigger/webhook_manager.rb

Overview

Public: Contains a number of generic utility methods.

Defined Under Namespace

Modules: DocIdExtension Classes: AbsoluteLinkedCss, AddHistoryPostBuilder, AddSearchForm, AdocSrcItf, AsciidoctorLogger, CmdLine, CmdLineDocAttribs, Configurator, ConversionInfo, CopyAssetDirsPostBuild, CopyResourcesPreBuild, DataDelegator, DefaultConverter, DefaultHtmlGenerator, DependencyGraphPostBuilder, DirTreeConvert, DocAttrBuilder, DocAttributesBase, DotDigraphAdoc, EntryPoint, ExpandAdoc, FailedConversion, FileHistory, GenerateFromRefs, GiblishDefaultDocAttribs, GitCheckoutManager, GitItf, GitRepoConfigurator, GitRepoConvert, GitSummaryDataProvider, GraphPageBase, HeadingIndexer, HtmlLayoutConfig, LoadAdocSrcFromFile, PdfCustomStyle, PdfLayoutConfig, PdfMathPostbuilder, RelativeCssDocAttr, RequestManager, ResourcePaths, SearchDataRepo, SearchParameters, SearchQuery, SearchRepoCache, SrcFromFile, SrcFromString, SubtreeIndexBase, SubtreeIndexGit, SubtreeInfoBuilder, SubtreeSrcItf, SuccessfulConversion, TextSearcher, TreeConverter, VerbatimTree

Constant Summary collapse

VERSION = 
"2.2.2".freeze

Class Method Summary collapse

Class Method Details

.application ⇒ Object 



17
18
19
 
# File 'lib/giblish.rb', line 17

def application
  @application ||= Giblish::EntryPoint
end

.break_line(line, max_length) ⇒ Object

Break a line into rows of max_length, using ‘-’ semi-intelligently to split words if needed

return

an Array with the resulting rows

Raises:

  • (ArgumentError) 


238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/giblish/utils.rb', line 238

def break_line(line, max_length)
  too_short = 3
  return [line] if line.length <= too_short
  raise ArgumentError, "max_length must be larger than #{too_short - 1}" if max_length < too_short

  rows = []
  row = ""

  until line.empty?
    word, _sep, _remaining = line.strip.partition(" ")
    row_space = max_length - row.length

    # start word with a space if row is not empty
    sep = row.empty? ? "" : " "

    # if word fits in row, just insert it and take next word
    if row_space - (word.length + sep.length) >= 0
      row = "#{row}#{sep}#{word}"
      line = line.sub(word, "").strip
      next
    end

    # shall we split word or just move it to next row?
    if (row_space == max_length && word.length > row_space) ||
        (word.length > too_short && (row_space > too_short) && (word.length - row_space).abs > too_short)
      # we will split the word, using a '-'
      first_part = word[0..row_space - (1 + sep.length)]
      row = "#{row}#{sep}#{first_part}-"
      line = line.sub(first_part, "").strip
    end

    # start a new row
    rows << row
    row = ""
  end
  # need to add unfinished row if any
  rows << row unless row.empty?
  rows
end

.process_header_lines(lines, &block) ⇒ Object

Helper method that provides the user with a way of processing only the lines within the asciidoc header block. The user must return nil to get the next line.

ex: process_header_lines(file_path) do |line|

if line == "Quack!"
   myvar = "Donald!"
   1
else
   nil
end

end



133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/giblish/utils.rb', line 133

def process_header_lines(lines, &block)
  return unless block

  state = "before_header"
  lines.each do |line|
    case state
    when "before_header" then (state = "in_header" if line =~ /^[=+]^.*$/ || yield(line))
    when "in_header" then (state = "done" if line =~ /^\s*$/ || yield(line))
    when "done" then break
    end
  end
end

.process_header_lines_from_file(path, &block) ⇒ Object

Helper method that provides the user with a way of processing only the lines within the asciidoc header block. The user must return nil to get the next line.

ex: process_header_lines_from_file(file_path) do |line|

if line == "Quack!"
   myvar = "Donald!"
   1
else
   nil
end

end



160
161
162
163
164
165
 
# File 'lib/giblish/utils.rb', line 160

def process_header_lines_from_file(path, &block)
  return unless block

  lines = File.readlines(path)
  process_header_lines(lines, &block)
end

.to_fs_str(str) ⇒ Object

Convert a string into a string where all characters forbidden as part of filenames are replaced by an underscore ‘_’.

returns

a String most likely a valid filename in windows & linux

A comprehensive list of forbidden chars in different file systems can be found here: stackoverflow.com/a/31976060 In short, chars forbidden in any of Windows and Linux are: / < > : “ \ | ? *



220
221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/giblish/utils.rb', line 220

def to_fs_str(str)
  # printable chars -> '_'
  tmp = str.gsub(/[\/<>:"\\|?*]/, "_")
  # non-printable chars -> '_'
  tmp.gsub!(/[\x00-\x1F]/, "_")
  # remove heading/trailing spaces
  tmp.strip!
  # Windows disallows files ending in '.'
  tmp += "_" if tmp.end_with?(".")

  tmp
end

.to_valid_id(input_str, id_prefix = "_", id_separator = "_", use_checksum = false) ⇒ Object

transforms strings to valid asciidoctor id strings in some cases you want to add a semi-unique checksum. If you do, you are no longer compatible with asciidoctor’s generated ids



183
184
185
186
187
188
189
190
191
 
# File 'lib/giblish/utils.rb', line 183

def to_valid_id(input_str, id_prefix = "_", id_separator = "_", use_checksum = false)
  # use a basic checksum to reduce the risk for duplicate ids
  check_sum = use_checksum ? input_str.chars.reduce(0) { |sum, c| sum + c.ord } : ""

  id_str = input_str.strip.downcase.gsub(/[^a-z0-9]+/, id_separator)
  id_str = "#{id_prefix}#{check_sum}#{id_prefix}#{id_str}"
  id_str.gsub!(/#{Regexp.quote(id_separator)}+/, id_separator)
  id_str.chomp(id_separator)
end

.which(cmd) ⇒ Object

See stackoverflow.com/questions/2108727/which-in-ruby-checking-if-program-exists-in-path-from-ruby Cross-platform way of finding an executable in the $PATH.

Ex

which('ruby') #=> /usr/bin/ruby



199
200
201
202
203
204
205
206
207
208
 
# File 'lib/giblish/utils.rb', line 199

def which(cmd)
  exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [""]
  ENV["PATH"].split(File::PATH_SEPARATOR).each do |path|
    exts.each do |ext|
      exe = File.join(path, "#{cmd}#{ext}")
      return exe if File.executable?(exe) && !File.directory?(exe)
    end
  end
  nil
end

.with_captured_stderr ⇒ Object

runs the supplied block but redirect stderr to a string returns the string containing stderr contents



170
171
172
173
174
175
176
177
 
# File 'lib/giblish/utils.rb', line 170

def with_captured_stderr
  old_stderr = $stderr
  $stderr = StringIO.new("", "w")
  yield
  $stderr.string
ensure
  $stderr = old_stderr
end