Public: Methods for retrieving lines from AsciiDoc source files, evaluating preprocessor directives as each line is read off the Array of lines.
Public: Initialize the PreprocessorReader object
# File lib/asciidoctor/reader.rb, line 538 def initialize document, data = nil, cursor = nil @document = document super data, cursor include_depth_default = document.attributes.fetch('max-include-depth', 64).to_i include_depth_default = 0 if include_depth_default < 0 # track both absolute depth for comparing to size of include stack and relative depth for reporting @maxdepth = {:abs => include_depth_default, :rel => include_depth_default} @include_stack = [] @includes = (document.references[:includes] ||= []) @skipping = false @conditional_stack = [] @include_processors = nil end
# File lib/asciidoctor/reader.rb, line 1005 def exceeded_max_depth? if (abs_maxdepth = @maxdepth[:abs]) > 0 && @include_stack.size >= abs_maxdepth @maxdepth[:rel] else false end end
# File lib/asciidoctor/reader.rb, line 1001 def include_depth @include_stack.size end
# File lib/asciidoctor/reader.rb, line 1117 def include_processors? if @include_processors.nil? if @document.extensions? && @document.extensions.include_processors? @include_processors = @document.extensions.load_include_processors(@document) true else @include_processors = false false end else @include_processors != false end end
Public: Override the Asciidoctor::Reader#peek_line method to pop the include stack if the last line has been reached and there's at least one include on the stack.
Returns the next line of the source data as a String if there are lines remaining in the current include context or a parent include context. Returns nil if there are no more lines remaining and the include stack is empty.
# File lib/asciidoctor/reader.rb, line 651 def peek_line direct = false if (line = super) line elsif @include_stack.empty? nil else pop_include peek_line direct end end
# File lib/asciidoctor/reader.rb, line 990 def pop_include if @include_stack.size > 0 @lines, @file, @dir, @path, @lineno, @maxdepth, @process_lines = @include_stack.pop # FIXME kind of a hack #Document::AttributeEntry.new('infile', @file).save_to_next_block @document #Document::AttributeEntry.new('indir', File.dirname(@file)).save_to_next_block @document @eof = @lines.empty? @look_ahead = 0 end end
# File lib/asciidoctor/reader.rb, line 552 def prepare_lines data, opts = {} if data.is_a?(String) if ::Asciidoctor::FORCE_ENCODING result = data.each_line.map {|line| "#{line.rstrip.force_encoding ::Encoding::UTF_8}#{::Asciidoctor::EOL}" } else result = data.each_line.map {|line| "#{line.rstrip}#{::Asciidoctor::EOL}" } end else if ::Asciidoctor::FORCE_ENCODING result = data.map {|line| "#{line.rstrip.force_encoding ::Encoding::UTF_8}#{::Asciidoctor::EOL}" } else result = data.map {|line| "#{line.rstrip}#{::Asciidoctor::EOL}" } end end # QUESTION should this work for AsciiDoc table cell content? Currently it does not. unless @document.nil? || !(@document.attributes.has_key? 'skip-front-matter') if (front_matter = skip_front_matter! result) @document.attributes['front-matter'] = front_matter.join.chomp end end # QUESTION should we chomp last line? (with or without the condense flag?) if opts.fetch(:condense, true) result.shift && @lineno += 1 while !(first = result.first).nil? && first == ::Asciidoctor::EOL result.pop while !(last = result.last).nil? && last == ::Asciidoctor::EOL end if (indent = opts.fetch(:indent, nil)) Lexer.reset_block_indent! result, indent.to_i end result end
Internal: Preprocess the directive (macro) to conditionally include content.
Preprocess the conditional inclusion directive (ifdef, ifndef, ifeval, endif) under the cursor. If the Reader is currently skipping content, then simply track the open and close delimiters of any nested conditional blocks. If the Reader is not skipping, mark whether the condition is satisfied and continue preprocessing recursively until the next line of available content is found.
directive - The conditional inclusion directive (ifdef, ifndef, ifeval, endif) target - The target, which is the name of one or more attributes that are
used in the condition (blank in the case of the ifeval directive)
delimiter - The conditional delimiter for multiple attributes ('+' means all
attributes must be defined or undefined, ',' means any of the attributes can be defined or undefined.
text - The text associated with this directive (occurring between the square brackets)
Used for a single-line conditional block in the case of the ifdef or ifndef directives, and for the conditional expression for the ifeval directive.
returns a Boolean indicating whether the cursor should be advanced
# File lib/asciidoctor/reader.rb, line 682 def preprocess_conditional_inclusion directive, target, delimiter, text # must have a target before brackets if ifdef or ifndef # must not have text between brackets if endif # don't honor match if it doesn't meet this criteria # QUESTION should we warn for these bogus declarations? if ((directive == 'ifdef' || directive == 'ifndef') && target.empty?) || (directive == 'endif' && !text.nil?) return false end if directive == 'endif' stack_size = @conditional_stack.size if stack_size > 0 pair = @conditional_stack.last if target.empty? || target == pair[:target] @conditional_stack.pop @skipping = @conditional_stack.empty? ? false : @conditional_stack.last[:skipping] else warn "asciidoctor: ERROR: #{line_info}: mismatched macro: endif::#{target}[], expected endif::#{pair[:target]}[]" end else warn "asciidoctor: ERROR: #{line_info}: unmatched macro: endif::#{target}[]" end return true end skip = false unless @skipping # QUESTION any way to wrap ifdef & ifndef logic up together? case directive when 'ifdef' case delimiter when nil # if the attribute is undefined, then skip skip = !@document.attributes.has_key?(target) when ',' # if any attribute is defined, then don't skip skip = !target.split(',').detect {|name| @document.attributes.has_key? name } when '+' # if any attribute is undefined, then skip skip = target.split('+').detect {|name| !@document.attributes.has_key? name } end when 'ifndef' case delimiter when nil # if the attribute is defined, then skip skip = @document.attributes.has_key?(target) when ',' # if any attribute is undefined, then don't skip skip = !target.split(',').detect {|name| !@document.attributes.has_key? name } when '+' # if any attribute is defined, then skip skip = target.split('+').detect {|name| @document.attributes.has_key? name } end when 'ifeval' # the text in brackets must match an expression # don't honor match if it doesn't meet this criteria if !target.empty? || !(expr_match = text.strip.match(REGEXP[:eval_expr])) return false end lhs = resolve_expr_val expr_match[1] # regex enforces a restrict set of math-related operations op = expr_match[2] rhs = resolve_expr_val expr_match[3] skip = !(lhs.send op.to_sym, rhs) end end # conditional inclusion block if directive == 'ifeval' || text.nil? @skipping = true if skip @conditional_stack << {:target => target, :skip => skip, :skipping => @skipping} # single line conditional inclusion else unless @skipping || skip # FIXME slight hack to skip past conditional line # but keep our synthetic line marked as processed conditional_line = peek_line true replace_line "#{text.rstrip}#{::Asciidoctor::EOL}" unshift conditional_line return true end end true end
Internal: Preprocess the directive (macro) to include the target document.
Preprocess the directive to include the target document. The scenarios are as follows:
If SafeMode is SECURE or greater, the directive is ignore and the include directive line is emitted verbatim.
Otherwise, if an include processor is specified pass the target and attributes to that processor and expect an Array of String lines in return.
Otherwise, if the max depth is greater than 0, and is not exceeded by the stack size, normalize the target path and read the lines onto the beginning of the Array of source data.
If none of the above apply, emit the include directive line verbatim.
target - The name of the source document to include as specified in the
target slot of the include::[] macro
returns a Boolean indicating whether the line under the cursor has changed.
# File lib/asciidoctor/reader.rb, line 792 def preprocess_include target, raw_attributes target = @document.sub_attributes target, :attribute_missing => 'drop-line' if target.empty? if @document.attributes.fetch('attribute-missing', COMPLIANCE[:attribute_missing]) == 'skip' false else advance true end # assume that if an include processor is given, the developer wants # to handle when and how to process the include elsif include_processors? && (processor = @include_processors.find {|candidate| candidate.handles? target }) advance # QUESTION should we use @document.parse_attribues? processor.process self, target, AttributeList.new(raw_attributes).parse true # if running in SafeMode::SECURE or greater, don't process this directive # however, be friendly and at least make it a link to the source document elsif @document.safe >= SafeMode::SECURE replace_line "link:#{target}[]#{::Asciidoctor::EOL}" # TODO make creating the output target a helper method #output_target = %(#{File.join(File.dirname(target), File.basename(target, File.extname(target)))}#{@document.attributes['outfilesuffix']}) #unshift "link:#{output_target}[]#{::Asciidoctor::EOL}" true elsif (abs_maxdepth = @maxdepth[:abs]) > 0 && @include_stack.size >= abs_maxdepth warn %Q(asciidoctor: ERROR: #{line_info}: maximum include depth of #{@maxdepth[:rel]} exceeded) false elsif abs_maxdepth > 0 if target.include?(':') && target.match(REGEXP[:uri_sniff]) unless @document.attributes.has_key? 'allow-uri-read' replace_line "link:#{target}[]#{::Asciidoctor::EOL}" return true end target_type = :uri include_file = path = target if @document.attributes.has_key? 'cache-uri' # caching requires the open-uri-cached gem to be installed # processing will be automatically aborted if these libraries can't be opened Helpers.require_library 'open-uri/cached', 'open-uri-cached' else Helpers.require_library 'open-uri' end else target_type = :file # include file is resolved relative to dir of current include, or base_dir if within original docfile include_file = @document.normalize_system_path(target, @dir, nil, :target_name => 'include file') if !File.file?(include_file) warn "asciidoctor: WARNING: #{line_info}: include file not found: #{include_file}" advance return true end #path = @document.relative_path include_file path = PathResolver.new.relative_path include_file, @document.base_dir end inc_lines = nil tags = nil attributes = {} if !raw_attributes.empty? # QUESTION should we use @document.parse_attribues? attributes = AttributeList.new(raw_attributes).parse if attributes.has_key? 'lines' inc_lines = [] attributes['lines'].split(REGEXP[:ssv_or_csv_delim]).each do |linedef| if linedef.include?('..') from, to = linedef.split('..').map(&:to_i) if to == -1 inc_lines << from inc_lines << 1.0/0.0 else inc_lines.concat Range.new(from, to).to_a end else inc_lines << linedef.to_i end end inc_lines = inc_lines.sort.uniq elsif attributes.has_key? 'tag' tags = [attributes['tag']] elsif attributes.has_key? 'tags' tags = attributes['tags'].split(REGEXP[:ssv_or_csv_delim]).uniq end end if !inc_lines.nil? if !inc_lines.empty? selected = [] inc_line_offset = 0 inc_lineno = 0 begin open(include_file) do |f| f.each_line do |l| inc_lineno += 1 take = inc_lines.first if take.is_a?(Float) && take.infinite? selected.push l inc_line_offset = inc_lineno if inc_line_offset == 0 else if f.lineno == take selected.push l inc_line_offset = inc_lineno if inc_line_offset == 0 inc_lines.shift end break if inc_lines.empty? end end end rescue warn "asciidoctor: WARNING: #{line_info}: include #{target_type} not readable: #{include_file}" advance return true end advance # FIXME not accounting for skipped lines in reader line numbering push_include selected, include_file, path, inc_line_offset, attributes end elsif !tags.nil? if !tags.empty? selected = [] inc_line_offset = 0 inc_lineno = 0 active_tag = nil begin open(include_file) do |f| f.each_line do |l| inc_lineno += 1 # must force encoding here since we're performing String operations on line l.force_encoding(::Encoding::UTF_8) if ::Asciidoctor::FORCE_ENCODING if !active_tag.nil? if l.include?("end::#{active_tag}[]") active_tag = nil else selected.push l inc_line_offset = inc_lineno if inc_line_offset == 0 end else tags.each do |tag| if l.include?("tag::#{tag}[]") active_tag = tag break end end end end end rescue warn "asciidoctor: WARNING: #{line_info}: include #{target_type} not readable: #{include_file}" advance return true end advance # FIXME not accounting for skipped lines in reader line numbering push_include selected, include_file, path, inc_line_offset, attributes end else begin advance push_include open(include_file) {|f| f.read }, include_file, path, 1, attributes rescue warn "asciidoctor: WARNING: #{line_info}: include #{target_type} not readable: #{include_file}" advance return true end end true else false end end
# File lib/asciidoctor/reader.rb, line 587 def process_line line return line unless @process_lines if line.chomp.empty? @look_ahead += 1 return '' end macroish = line.include?('::') && line.include?('[') if macroish && line.include?('if') && (match = line.match(REGEXP[:ifdef_macro])) # if escaped, mark as processed and return line unescaped if line.start_with? '\' @unescape_next_line = true @look_ahead += 1 line[1..-1] else if preprocess_conditional_inclusion(*match.captures) # move the pointer past the conditional line advance # treat next line as uncharted territory nil else # the line was not a valid conditional line # mark it as visited and return it @look_ahead += 1 line end end elsif @skipping advance nil elsif macroish && line.include?('include::') && (match = line.match(REGEXP[:include_macro])) # if escaped, mark as processed and return line unescaped if line.start_with? '\' @unescape_next_line = true @look_ahead += 1 line[1..-1] else # QUESTION should we strip whitespace from raw attributes in Substituters#parse_attributes? (check perf) if preprocess_include match[1], match[2].strip # peek again since the content has changed nil else # the line was not a valid include line and is unchanged # mark it as visited and return it @look_ahead += 1 line end end else # optimization to inline super #super @look_ahead += 1 line end end
# File lib/asciidoctor/reader.rb, line 963 def push_include data, file = nil, path = nil, lineno = 1, attributes = {} @include_stack << [@lines, @file, @dir, @path, @lineno, @maxdepth, @process_lines] @includes << Helpers.rootname(path) @file = file @dir = File.dirname file @path = path @lineno = lineno # NOTE only process lines in AsciiDoc files @process_lines = ASCIIDOC_EXTENSIONS[File.extname(@file)] if attributes.has_key? 'depth' depth = attributes['depth'].to_i depth = 1 if depth <= 0 @maxdepth = {:abs => (@include_stack.size - 1) + depth, :rel => depth} end # effectively fill the buffer @lines = prepare_lines data, :condense => false, :indent => attributes['indent'] # FIXME kind of a hack #Document::AttributeEntry.new('infile', @file).save_to_next_block @document #Document::AttributeEntry.new('indir', File.dirname(@file)).save_to_next_block @document if @lines.empty? pop_include else @eof = false @look_ahead = 0 end end
Private: Resolve the value of one side of the expression
Examples
expr = '"value"' resolve_expr_val(expr) # => "value" expr = '"value' resolve_expr_val(expr) # => "\"value" expr = '"{undefined}"' resolve_expr_val(expr) # => "" expr = '{undefined}' resolve_expr_val(expr) # => nil expr = '2' resolve_expr_val(expr) # => 2 @document.attributes['name'] = 'value' expr = '"{name}"' resolve_expr_val(expr) # => "value"
Returns The value of the expression, coerced to the appropriate type
# File lib/asciidoctor/reader.rb, line 1081 def resolve_expr_val(str) val = str type = nil if val.start_with?('"') && val.end_with?('"') || val.start_with?('\') && val.end_with?('\') type = :string val = val[1...-1] end # QUESTION should we substitute first? if val.include? '{' val = @document.sub_attributes val end unless type == :string if val.empty? val = nil elsif val.strip.empty? val = ' ' elsif val == 'true' val = true elsif val == 'false' val = false elsif val.include?('.') val = val.to_f else # fallback to coercing to integer, since we # require string values to be explicitly quoted val = val.to_i end end val end
TODO Document this override also, we now have the field in the super class, so perhaps just implement the logic there?
# File lib/asciidoctor/reader.rb, line 1016 def shift if @unescape_next_line @unescape_next_line = false super[1..-1] else super end end
Private: Ignore front-matter, commonly used in static site generators
# File lib/asciidoctor/reader.rb, line 1026 def skip_front_matter! data, increment_linenos = true front_matter = nil if data.size > 0 && data.first.chomp == '---' original_data = data.dup front_matter = [] data.shift @lineno += 1 if increment_linenos while !data.empty? && data.first.chomp != '---' front_matter.push data.shift @lineno += 1 if increment_linenos end if data.empty? data.unshift(*original_data) @lineno = 0 if increment_linenos front_matter = nil else data.shift @lineno += 1 if increment_linenos end end front_matter end
# File lib/asciidoctor/reader.rb, line 1131 def to_s %Q(#{self.class.name} [path: #{@path}, line #: #{@lineno}, include depth: #{@include_stack.size}, include stack: [#{@include_stack.map {|inc| inc.to_s}.join ', '}]]) end