codeblock 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 583c7a3edfb276f54463bc3c9a04ff035d9c7597b8f353fdc18b1076cfdf1b33
+  data.tar.gz: b6d7010884b4fc6a0347896d9a6029ce6c8e01cbc11ef2f0c0e3e8dd4441d395
+SHA512:
+  metadata.gz: b001b7883f3075a41638aa92f66935eb4b52ad3a7eb90b182d1b3ebc2950f11312787e4df387b63d69de4297fb4e472495093547781da1d8edaf5acaf5b551c4
+  data.tar.gz: 759e75ff240f9a12b4d06d67fd7af5ce536c0b0c896443ffbc30f7891d00d786147b180c7a914f7130494f82b3f44827fa61733a16283e92716e210716e5e7a1

data/README.md

@@ -0,0 +1,191 @@
+# CodeBlock
+
+CodeBlock assists in documenting code by importing working code for display in
+documentation. CodeBlock allows you to write working examples of code, then
+import that code into documentation without any copying or pasting. Features
+include:
+
+- import all of a file or just parts of it
+- strip out lines that are not relevent to the documentation
+- reference lines by name instead of line number
+
+CodeBlock itself is not a documentation system. It is intended for use in other
+documentation systems.
+
+## Basic usage
+
+Consider an example of a code file that I have for development of a DBMS system
+I'm developing called "Audrey". The code file looks like this:
+
+    #!/usr/bin/ruby -w
+    require 'audrey'
+    
+    # connect to database, creating it if necessary
+    Audrey.connect('/tmp/my.db', 'rw') do |db|
+        db['hero'] = 'Thor'
+        db['antagonist'] = 'Loki'
+    end
+    
+    # done
+    puts '[done]'
+
+In its simplest use, a new CodeBlock object simply slurps in a code file. The
+contents of the file are accessible in the object's to_s method. So, we might
+use CodeBlock like this:
+
+    require 'codeblock'
+    src_path = 'samples/plain.rb'
+    block = CodeBlock.new(File.read src_path)
+    puts block.to_s # => outputs the exact contents of the file
+
+So far that's not very useful. We could accomplish the same thing by simply
+slurping in the file contents. Let's look at a more advanced usage.
+
+Suppose you only want to display a certain block of code in your documentation.
+Now, you could just copy and paste the relevent block into your documentation,
+but that's redundant information. Your document doesn't get updated if you
+change the working example. That's where CodeBlock gets useful. With CodeBlock,
+you can name specific lines to import. Let's look at the same working code as
+above, but with a few additions.
+
+    #!/usr/bin/ruby -w
+    require 'audrey'
+    
+    # connect to database, creating it if necessary
+    Audrey.connect('/tmp/my.db', 'rw') do |db| ## name=begin
+        db['hero'] = 'Thor'
+        db['antagonist'] = 'Loki'
+    end ## name=finish
+    
+    # done
+    puts '[done]'
+
+That's the same working code... all we've done is added some comments that
+CodeBlock can interpret. Each line to which we want to add information has `##`
+followed by name=value pairs. In the above example, the lines are givens the
+names "begin" and "finish".
+
+To extract the block of code that starts with "begin" and ends with "finish",
+we set the CodeBlock#start and CodeBlock#end properties, like this:
+
+    src_path = 'samples/block.rb'
+    block = CodeBlock.new(File.read src_path)
+    block.start = 'begin'
+    block.end = 'finish'
+    block.to_s
+
+That retrieves just the lines indicated. Notice that `##` and everything after
+it is stripped from the lines:
+
+    Audrey.connect('/tmp/my.db', 'rw') do |db|
+        db['hero'] = 'Thor'
+        db['antagonist'] = 'Loki'
+    end
+
+## Skip lines
+
+You might find that in some situations its helpful to have code in your working
+file that isn't relevent to the documentation. In those case, you can indicate
+that a line should be skipped with skip=true:
+
+    Audrey.connect('/tmp/my.db', 'rw') do |db| ## name=start
+        db['hero'] = 'Thor'
+        puts db['hero'] ## skip=true
+    end ## name=end
+
+That will results in a code sample that doesn't include that line
+
+    Audrey.connect('/tmp/my.db', 'rw') do |db|
+        db['hero'] = 'Thor'
+    end
+
+## Line numbers
+
+You might want to include line numbers in your documentation. There are two ways
+to do this.
+
+First, you might want a string just of line numbers. Doing so would allow you to
+put the line numbers into an HTML <pre> tag alongside the code itself. To get
+line numbers simply call CodeBlock#line_nums_to_s. Doing so outputs something
+like as follows. Notice that the numbers are right justified.
+
+     1.
+     2.
+     3.
+     4.
+     5.
+     6.
+     7.
+     8.
+     9.
+    10.
+    11.
+    12.
+
+The line numbers match up with the lines that have been selected, not the line
+numbers in the file. That allows you to display code lines and line numbers that
+match up.
+
+To output the entire code block with line numbers, set the block's `line_nums`
+property to true:
+
+    block.line_nums = true
+    puts block.to_s
+
+That will output something like this:
+
+     1.  # connect to database, creating it if necessary
+     2.  Audrey.connect('/tmp/my.db', 'rw') do |db|
+     3.      db['hero'] = 'Thor'
+     4.      db['antagonist'] = 'Loki'
+     5.  end
+     6.  
+     7.  # read
+     8.  Audrey.connect('/tmp/my.db', 'rw') do |db|
+     9.      puts db['hero']
+    10.      puts db['antagonist']
+    11.  end
+    12.  
+    13.  # done
+    14.  puts '[done]'
+
+## Named lines
+
+Lines can be referenced by their names to get their line numbers. This allows
+you to give the number of a line in a block without having to change the line
+number when you modify the block. Access the line in the block's `named`
+property.
+
+In this example, we name one of the lines "Thor":
+
+    Audrey.connect('/tmp/my.db', 'rw') do |db| ## name=start
+        db['hero'] = 'Thor' ## name=Thor
+    end ## name=end
+
+Then, depending on how your documentation system works, you could reference the
+line number like this:
+
+    src_path = 'samples/named-lines.rb'
+    block = CodeBlock.new(File.read(src_path), 'se'=>true)
+    puts "In line number #{block.named['Thor'].number} we set a value."
+
+This will output as follows:
+
+    In line number 2 we set a value.
+
+## Install
+
+```
+gem install codeblock
+```
+
+## Author
+
+Mike O'Sullivan
+mike@idocs.com
+
+## History
+
+| version | date          | notes                                                 |
+|---------|---------------|-------------------------------------------------------|
+| 1.0     | June 18, 2020 | Initial upload.                                       |

data/lib/codeblock.rb

@@ -0,0 +1,606 @@
+require 'attparser'
+
+
+#===============================================================================
+# CodeBlock
+#
+class CodeBlock
+	# Version
+	VERSION = '1.0'
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	# First param should be the code that should be parsed. The remaining
+	# options follow the names of the various properties that can be set. So,
+	# for example, to create a block with named, starting and ending lines,
+	# you could do this:
+	#
+	#    block = CodeBlock.new(src, 'start'=>'a', 'end'=>'b')
+	#
+	# You might find that you are often naming the starting line "start" and the
+	# ending line "end". To simplify setting those common names, you can use the
+	# se ("start/end") option:
+	#    
+	#    block = CodeBlock.new(src, 'se'=>true)
+	#
+	# That is exactly equivelant to:
+	#
+	#    block = CodeBlock.new(src, 'start'=>'start', 'end'=>'end')
+	
+	def initialize(raw, opts={})
+		@lines_org = raw.lines
+		@keep_meta = opts['keep_meta'] || false
+		@tab = opts['tab'] || '    '
+		@indent = opts['indent']
+		@line_nums = opts['line_nums']
+		
+		# if 'se' param, set start and end to "start" and "end"
+		if opts['se']
+			@start = 'start'
+			@end = 'end'
+		else
+			@start = opts['start']
+			@end = opts['end']
+		end
+		
+		# if collapse is defined
+		if opts.has_key?('collapse')
+			@collapse = opts['collapse']
+		else
+			@collapse = true
+		end
+		
+		# if skip_skips is defined
+		if opts.has_key?('skip_skips')
+			@skip_skips = opts['skip_skips']
+		else
+			@skip_skips = true
+		end
+		
+		# initialize block object
+		@block_ob = nil
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# attribute readers
+	#
+	
+	# The name of the line that starts the block. Leave nil to start at the
+	# beginning of the file. If an ending line is given but that line is not
+	# found then an exception is raised.
+	attr_reader :start
+	
+	# The name of the line that ends the block. Leave nil for no ending line.
+	# If an ending line is given but that line is not found then an exception is
+	# raised.
+	attr_reader :end
+	
+	# The string to convert tab characters to. Defaults to four spaces.
+	attr_reader :tab
+	
+	# If set, indicates a string to put at the beginning of each line. For
+	# Markdown, a value of four spaces is a good choice. Defaults to nil.
+	attr_reader :indent
+	
+	# If true, then contiguous lines that contain just spaces are collapsed to a
+	# single space-only line.
+	attr_reader :collapse
+	
+	# If true, the line meta information (i.e. the ## and everything after it)
+	# is not stripped from the output lines. Defaults to false.
+	attr_reader :keep_meta
+	
+	
+	# If true, then lines that are marked to be skipped are not skipped.
+	# Defaults to false.
+	attr_reader :skip_skips
+	
+	# If true, line numbers are output with the block of code. Defaults to
+	# false.
+	attr_reader :line_nums
+	
+	# The full array of lines in the code.
+	attr_reader :lines_full
+	
+	#
+	# attribute readers
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# start=, end=, tab=
+	#
+	
+	# Sets the start property.
+	def start=(new_val)
+		@block_ob = nil
+		@start = new_val
+	end
+	
+	# Sets the end property.
+	def end=(new_val)
+		@block_ob = nil
+		@end = new_val
+	end
+	
+	# Sets the tab property.
+	def tab=(new_val)
+		@block_ob = nil
+		@tab = new_val
+	end
+	
+	# Sets the indent property.
+	def indent=(new_val)
+		@block_ob = nil
+		@indent = new_val
+	end
+	
+	# Sets the collapse property.
+	def collapse=(new_val)
+		@block_ob = nil
+		@collapse = new_val
+	end
+	
+	# Sets the keep_meta property.
+	def keep_meta=(new_val)
+		@block_ob = nil
+		@keep_meta = new_val
+	end
+	
+	# Sets the skip_skips property.
+	def skip_skips=(new_val)
+		@block_ob = nil
+		@skip_skips = new_val
+	end
+	
+	# Sets the line_nums property.
+	def line_nums=(new_val)
+		@block_ob = nil
+		@line_nums = new_val
+	end
+	
+	#
+	# start=, end=, tab=
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# sort-of delegate some methods to block()
+	# NOTE: I can't get delegate() to work for delegating to a method. Not sure
+	# what I'm doing wrong. Feel free to fix it.
+	#
+	
+	# Returns an array of the lines in the code block. Each element of the array
+	# is a CodeBlock::Line object.
+	def lines
+		return block.lines
+	end
+	
+	# Returns a string of the code block.
+	def to_s
+		return block.to_s
+	end
+	
+	# Returns a string of the line numbers, one number per line.
+	def line_nums_to_s
+		return block.line_nums_to_s
+	end
+	
+	# Returns a string of the notes for each each line. Notes are set with the
+	# `notes` attribute in the meta section of the line, like this:
+	#
+	#    db['hero'] = 'Thor' ## notes="Set the value in the database"
+	#
+	#  There will be as many lines in the string as lines in the code block.
+	#  Lines with no notes will be empty lines.
+	def notes_to_s
+		return block.notes_to_s
+	end
+	
+	# A hash of named lines.
+	def named
+		return block.named
+	end
+	
+	#
+	# sort-of delegate some methods to block()
+	#---------------------------------------------------------------------------
+	
+	
+	# private
+	private
+	
+	
+	#---------------------------------------------------------------------------
+	# block
+	#
+	def block()
+		# build block if necessary
+		if not @block_ob
+			@lines_full = @lines_org.map {|line| CodeBlock::Line.new(self, line)}
+			opts = {}
+			opts['start'] = @start
+			opts['end'] = @end
+			opts['tab'] = @tab
+			opts['collapse'] = @collapse
+			@block_ob = CodeBlock::Block.new(self, opts)
+		end
+		
+		# return
+		return @block_ob
+	end
+	#
+	# block
+	#---------------------------------------------------------------------------
+end
+#
+# CodeBlock
+#===============================================================================
+
+
+#===============================================================================
+# CodeBlock::Line
+#
+
+# A CodeBlock::Line represents a single line in the block of code. Generally you
+# will not need to instantiate a CodeBlock::Line object yourself.
+class CodeBlock::Line
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	# Accepts a CodeBlock object and the raw string from the code.
+	def initialize(code, raw)
+		@code = code
+		@raw = raw
+		@number = nil
+		@display = @raw
+		
+		# unless keep meta, else strip ## and everything after
+		if @code.keep_meta
+			@display = @raw
+		else
+			@display = @raw.sub(/\s*\#\#.*/mu, '')
+		end
+		
+		# remove trailing spaces
+		@display = @display.rstrip
+		
+		# attributes
+		if @raw.match(/\#\#/mu)
+			raw_atts = @raw.sub(/\A.*\#\#\s*/mu, '')
+			raw_atts = raw_atts.rstrip
+			@atts = AttParser.parse(raw_atts, 'infer'=>true)
+		else
+			@atts = {}
+		end
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# readers and accessors
+	#
+	
+	# Returns a hash of the name=value pairs set in the line's meta section.
+	attr_reader :atts
+	
+	# Returns the line's number in the code block.
+	attr_accessor :number
+	
+	#
+	# readers and accessors
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# convenience
+	#
+	
+	# Returns the value of 'name' in the line's attributes. Returns nil if no
+	# name was set.
+	def name
+		return @atts['name']
+	end
+	
+	# Returns the value of 'skip' in the line's attributes. Returns nil if no
+	# skip was set.
+	def skip
+		return @atts['skip']
+	end
+	
+	# Returns the value of 'notes' in the line's attributes. Returns nil if no
+	# notes were set.
+	def notes
+		return @atts['notes']
+	end
+	
+	#
+	# convenience
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_s
+	#
+	
+	# Returns the line as it should be displayed, taking into account tabs,
+	# indentation, line number, etc. If the line is to be skipped then nil is
+	# returned.
+	def to_s
+		if @atts['skip'] and (not @code.skip_skips)
+			return nil
+		else
+			return @display
+		end
+	end
+	#
+	# to_s
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# has_content?
+	#
+	
+	# Returns true if the line has any non-space characters.
+	def has_content?
+		return @display.match(/\S/mu)
+	end
+	
+	# Returns false if the line has any non-space characters.
+	def no_content?
+		return !has_content?
+	end
+	
+	#
+	# has_content?
+	#---------------------------------------------------------------------------
+end
+#
+# CodeBlock::Line
+#===============================================================================
+
+
+
+#===============================================================================
+# CodeBlock::Block
+#
+
+# This is the class that does the work of filtering which lines should be
+# displayed and which shouldn't. Generally you won't have to work directly with
+# this class.
+class CodeBlock::Block
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	def initialize(p_code, opts={})
+		@code = p_code
+		@collapse = opts['collapse']
+		@tab = opts['tab'] || '    '
+		@start = opts['start']
+		@end = opts['end']
+		
+		# build lines array
+		build_lines()
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# attribute readers
+	#
+	
+	# The array of CodeBlock::Line objects.
+	attr_reader :lines
+	
+	# A hash of named lines.
+	attr_reader :named
+	
+	#
+	# attribute readers
+	#---------------------------------------------------------------------------
+	
+	
+	
+	#---------------------------------------------------------------------------
+	# to_s
+	#
+	
+	# Builds the string that is returned by CodeBlock#to_s.
+	def to_s()
+		# $tm.hrm
+		rv = []
+		indent = @code.indent || ''
+		line_nums = @code.line_nums
+		
+		# get maximum width
+		if line_nums
+			max_width = @lines[-1].number.to_s.length
+		end
+		
+		# build return array
+		@lines.each do |line|
+			# get string
+			v = line.to_s
+			
+			# substitute tabs
+			if @tab
+				v = v.gsub(/\t/mu, @tab)
+			end
+			
+			# line numbers
+			if line_nums
+				v = line.number.to_s.rjust(max_width) + '.  ' + v
+			end
+			
+			# indent
+			v = indent + v
+			
+			# add to return array
+			rv.push v
+		end
+		
+		# return
+		return rv.join("\n")
+	end
+	#
+	# to_s
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# line_nums_to_s
+	#
+	
+	# Builds the string that is returned by CodeBlock#line_nums_to_s.
+	def line_nums_to_s
+		# $tm.hrm
+		rv = []
+		
+		# get maximum width
+		width = @lines[-1].number.to_s.length
+		
+		# loop through lines
+		@lines.each do |line|
+			rv.push line.number.to_s.rjust(width) + '.'
+		end
+		
+		# return
+		return rv.join("\n")
+	end
+	#
+	# line_nums_to_s
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# notes_to_s
+	#
+	
+	# Builds the string that is returned by CodeBlock#notes_to_s.
+	def notes_to_s
+		rv = []
+		
+		# loop through lines
+		@lines.each do |line|
+			rv.push line.notes || ''
+		end
+		
+		# return
+		return rv.join("\n")
+	end
+	#
+	# notes_to_s
+	#---------------------------------------------------------------------------
+	
+	
+	# private
+	private
+	
+	
+	#---------------------------------------------------------------------------
+	# build_lines
+	#
+	def build_lines
+		# $tm.hrm
+		@lines = []
+		
+		# starting line name
+		started = @start ? false : true
+		ended = false
+		
+		# get visible lines
+		@code.lines_full.each do |line|
+			# start if necessary
+			if (not started) and @start
+				started = line.atts['name'] == @start
+			end
+			
+			# add line
+			if started and (not ended)
+				if line.to_s
+					@lines.push line.clone
+				end
+			end
+			
+			# if ending line
+			if (not ended) and @end
+				ended = line.atts['name'] == @end
+			end
+		end
+		
+		# strip leading empty lines
+		while @lines.any? and (not @lines[0].to_s.match(/\S/mu))
+			@lines.shift
+		end
+		
+		# strip trailing empty lines
+		while @lines.any? and (not @lines[-1].to_s.match(/\S/mu))
+			@lines.pop
+		end
+		
+		# collapse
+		if @collapse
+			while collapse_find()
+			end
+		end
+		
+		# number lines
+		@lines.each_with_index() do |line, idx|
+			line.number = idx + 1
+		end
+		
+		# build hash of named lines
+		@named = {}
+		
+		# get named lines
+		@lines.each do |line|
+			if line.name
+				if @named[line.name]
+					raise 'https://motley.uno/messages/code/init/redundant-name: ' + line.name
+				end
+				
+				@named[line.name] = line
+			end
+		end
+	end
+	#
+	# build_lines
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# collapse_find
+	#
+	def collapse_find()
+		# loop through lines
+		@lines.each_with_index do|line, idx|
+			if idx > 0
+				if line.no_content? and @lines[idx-1].no_content?
+					@lines.delete_at(idx-1)
+					return true
+				end
+			end
+		end
+		
+		# didn't find anymore lines to collapse
+		return false
+	end
+	#
+	# collapse_find
+	#---------------------------------------------------------------------------
+end
+#
+# CodeBlock::Block
+#===============================================================================

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: codeblock
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Mike O'Sullivan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: attparser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Read a block of code from a working code file and format it.
+email: mike@idocs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/codeblock.rb
+homepage: https://rubygems.org/gems/codeblock
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Document a block of code
+test_files: []