Merge pull request #15 from briandominick/migrate-action

README.adoc

@@ -186,13 +186,17 @@ Repeat without the `--stdout` flag and you'll find the generated files in `_outp
 
 // tag::configuration[]
 
-=== Data Sources
+=== Parse Operations
+
+The primary type of action performed by LiquiDoc during a build step is parsing semi-structured data into any flat format desired.
+
+==== Data Sources
 
 Valid data sources come in a few different types.
 There are the built-in data types (YAML, JSON, XML, CSV) vs free-form type (files processed using regular expressions, designated by the `regex` data type).
 There is also a divide between simple one-record-per-line data types (CSV and regex), which produce one set of parameters for every line in the source file, versus nested data types that can reflect far more complex structures.
 
-==== Native Nested Data (YAML, JSON, XML)
+===== Native Nested Data (YAML, JSON, XML)
 
 The native nested formats are actually the most straightforward.
 So long as your filename has a conventional extension, you can just pass a file path for this setting.
@@ -203,7 +207,7 @@ For standard-format files that have non-standard file extensions (for example, `
 [source,yaml]
 .Example -- Instructing correct type for mislabeled JSON file
 ----
-compile:
+- action: parse
   data:
     file: _data/source_data_file.js
     type: json
@@ -214,7 +218,7 @@ compile:
 
 Once LiquiDoc knows the right file type, it will parse the file into a Ruby hash data structure for further processing.
 
-==== CSV Data
+===== CSV Data
 
 Data ingested from CSV files will use the first row as key names for columnar data in the subsequent rows, as shown below.
 
@@ -244,7 +248,7 @@ data[1].default #=> 300
 data[1].required #=> false
 ----
 
-==== Free-form Data
+===== Free-form Data
 
 Free-form data can only be parsed using regex patterns -- otherwise LiquiDoc has no idea what to consider data and what to consider noise.
 
@@ -266,7 +270,7 @@ G_H Some text for &hdf 1t`F false
 [source,yaml]
 .Example -- Instructing correct type for mislabeled JSON file
 ----
-compile:
+- action: parse
   data:
     file: _data/sample.free
     type: regex
@@ -304,7 +308,7 @@ Its use case is usually when you simply cannot control the form your source take
 The regex type is also handy when the content of some fields would be burdensome to store in conventional semi-structured formats like those natively parsed by LiquiDoc.
 This is the case for jumbled content containing characters that require escaping, so you can keep source like that from the example above in the simplest possible form.
 
-=== Templating
+==== Templating
 
 LiquiDoc will add the powers of Asciidoctor in a future release, enabling initial reformatting of complex source data _into_ AsciiDoc format using Liquid templates, followed by final publishing into rich formats such as PDF, HTML, and even slide presentations.
 Other template engines may be added, such as ERB, HAML, Handlebars.
@@ -436,13 +440,44 @@ A_B A thing that *SnASFHE&"\|+1Dsaghf true
 G_H Some text for &hdf 1t`F false
 ----
 
-=== Output
+==== Output
 
 After this parsing, files are written in any of the given output formats, or else just written to system as STDOUT (when you add the `--stdout` flag to your command or set `output: stdout` in your config file).
 Liquid templates can be used to produce any flat-file format imaginable.
 Just format valid syntax with your source data and Liquid template, then save with the proper extension, and you're all set.
 // end::usage[]
 
+=== Migrate Operations
+
+During the build process, different tools handle file assets variously, so your images and other embedded files are not always where they need to be relative to the current procedure.
+Migrate actions copy resource files to a temporary/uncommitted directory during the build procedure so they can be readily accessed by subsequent steps.
+
+In addition to designating `action: migrate`, migrate operations require just a few simple settings.
+
+[source,yaml]
+.Example -- Instructing file copies with 'migrate' action
+----
+- action: migrate
+  source: assets/images
+  target: _build/img
+  options:
+    inclusive: false
+- action: migrate
+  source: index-map.adoc
+  target: _build/index-map.adoc
+----
+
+The first action step above copies all the files in `assets/images` and copies them to `_build/img`.
+It will only recreate the contents of the source directory, not the directory path itself, because the *inclusive* option is set to `false` (though its default is `true`).
+When the both the source and target paths are directories and inclusive is `true`, the files are copied to `<target>/<source>`.
+When inclusive is `false`, they copy to `<target>/`.
+
+Individual files must be listed individually at this time, one per step, as in the second step.
+
+// === Render Operations
+
+// === Deploy Operations
+
 == Meta
 // tag::meta[]
 I get that this is the least sexy tool anyone has ever built.
@@ -464,7 +499,7 @@ But if you get what I'm trying to do, give a holler.
 // tag::contributing[]
 Contributions are very welcome.
 
-This repo is maintained by the former Technical Documentation Manager at Rocana (formerly ScalingData, now mostly acquired by Splunk), the original copyright holder of LiquiDoc.
+This repo is maintained by the former Technical Documentation Manager at Rocana (formerly ScalingData, now mostly acquired by Splunk),which is the original copyright holder of LiquiDoc.
 I taught myself basic Ruby scripting just to code LiquiDoc and related tooling.
 Therefore, *instructional pull requests are encouraged*.
 I have no ego around the code itself.

lib/content/cli-options.yml

@@ -0,0 +1,10 @@
+- slug: attributes-file
+  description: For passing in a standard YAML AsciiDoc attributes file.
+  default: _data/attributes.yml
+  flag: a
+- slug: attr
+  description: "For passing an AsciiDoc attribute parameter to Asciidoctor. Ex: --attr basedir=some/path --attr imagesdir=some/path/images"
+- slug: base
+  description:
+  default: ./
+  flag: b

lib/liquidoc.rb

@@ -7,22 +7,23 @@
 require 'logger'
 require 'csv'
 require 'crack/xml'
+require 'fileutils'
 
 # ===
 # Table of Contents
 # ===
 #
 # 1. dependencies stack
 # 2. default settings
-# 3. general methods
-# 4. object classes
-# 5. action-specific methods
-# 5a. parse methods
-# 5b. migrate methods
-# 5c. render methods
-# 6. text manipulation
-# 7. command/option parser
-# 8. executive method calls
+# 3. general procs def
+# 4. object classes def
+# 5. action-specific procs def
+# 5a. parse procs def
+# 5b. migrate procs def
+# 5c. render procs def
+# 6. text manipulation modules/classes def
+# 7. command/option parser def
+# 8. executive proc calls
 
 # ===
 # Default settings
@@ -33,7 +34,6 @@
 @configs_dir = @base_dir + '_configs'
 @templates_dir = @base_dir + '_templates/'
 @data_dir = @base_dir + '_data/'
-@output_dir = @base_dir + '_output/'
 @attributes_file_def = '_data/asciidoctor.yml'
 @attributes_file = @attributes_file_def
 @pdf_theme_file = 'theme/pdf-theme.yml'
@@ -48,7 +48,7 @@
 end
 
 # ===
-# Executive methods
+# Executive procs
 # ===
 
 # Establish source, template, index, etc details for build jobs from a config file
@@ -84,7 +84,9 @@ def iterate_build cfg
         liquify(data, build.template, build.output) # perform the liquify operation
       end
     when "migrate"
-      @logger.warn "Migrate actions not yet implemented."
+      inclusive = true
+      inclusive = step.options['inclusive'] if defined?(step.options['inclusive'])
+      copy_assets(step.source, step.target, inclusive)
     when "render"
       @logger.warn "Render actions not yet implemented."
     when "deploy"
@@ -182,6 +184,18 @@ def data
     return @@step['data']
   end
 
+  def source
+    return @@step['source']
+  end
+
+  def target
+    return @@step['target']
+  end
+
+  def options
+    return @@step['options']
+  end
+
   def builds
     return @@step['builds']
   end
@@ -202,15 +216,14 @@ class Build
   def initialize build, type
     @@build = build
     @@type = type
-    @@logger = Logger.new(STDOUT)
     required = []
     case type
     when "parse"
       required = ["template,output"]
-    when "render"
-      required = ["index,output"]
     when "migrate"
       required = ["source,target"]
+    when "render"
+      required = ["index,output"]
     end
     for req in required
       if (defined?(req)).nil?
@@ -231,14 +244,6 @@ def index
     @@build['index']
   end
 
-  def source
-    @@build['source']
-  end
-
-  def target
-    @@build['target']
-  end
-
 end #class Build
 
 class DataSrc
@@ -305,9 +310,9 @@ def pattern
 end
 
 # ===
-# Action-specific methods
-#
-# PARSE-type build methods
+# Action-specific procs
+# ===
+# PARSE-type build procs
 # ===
 
 # Pull in a semi-structured data file, converting contents to a Ruby hash
@@ -316,7 +321,7 @@ def ingest_data datasrc
   unless datasrc.is_a? Object
     raise "InvalidDataObject"
   end
-  # This method should really begin here, once the data object is in order
+  # This proc should really begin here, once the datasrc object is in order
   case datasrc.type
   when "yml"
     begin
@@ -407,8 +412,9 @@ def liquify datasrc, template_file, output
   end
   unless output.downcase == "stdout"
     output_file = output
+    base_path = File.dirname(output)
     begin
-      Dir.mkdir(@output_dir) unless File.exists?(@output_dir)
+      Dir.mkdir(base_path) unless File.exists?(base_path)
       File.open(output_file, 'w') { |file| file.write(rendered) } # saves file
     rescue Exception => ex
       @logger.error "Failed to save output.\n#{ex.class} #{ex.message}"
@@ -424,30 +430,36 @@ def liquify datasrc, template_file, output
 end
 
 # ===
-# MIGRATE-type methods
+# MIGRATE-type procs
 # ===
 
-# Copy images and other assets into output dir for HTML operations
-def copy_assets src, dest
-  if @recursive
-    dest = "#{dest}/#{src}"
-    recursively = "Recursively c"
-  else
-    recursively = "C"
-  end
-  @logger.debug "#{recursively}opying image assets to #{dest}"
+# Copy images and other files into target dir
+def copy_assets src, dest, inclusive=true
+  if File.file?(src) # for sources that are files
+    target_dir = File.dirname(dest)
+  else # if src is a directory
+    unless inclusive then src = src + "/." end
+    target_dir = dest
+  end
+  @logger.debug "Copying #{src} to #{dest}"
+  # puts "Dir name: " + File.dirname(dest)
+  # puts "Dir exists: " + File.exists?(File.dirname(dest)).to_s
   begin
-    FileUtils.mkdir_p(dest) unless File.exists?(dest)
-    FileUtils.cp_r(src, dest)
+    FileUtils.mkdir_p(dest) unless File.exists?(target_dir)
+    if File.directory?(src)
+      FileUtils.cp_r(src, dest)
+    else
+      FileUtils.cp(src, dest)
+    end
+    @logger.info "Copied assets."
   rescue Exception => ex
     @logger.warn "Problem while copying assets. #{ex.message}"
-    return
+    raise
   end
-  @logger.debug "\s\s#{recursively}opied: #{src} --> #{dest}/#{src}"
 end
 
 # ===
-# RENDER-type methods
+# RENDER-type procs
 # ===
 
 # Gather attributes from a fixed attributes file

lib/liquidoc/version.rb

@@ -1,3 +1,3 @@
 module Liquidoc
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end