ceedling 1.0.0 → 1.0.1

data/lib/ceedling/parsing_parcels.rb

@@ -0,0 +1,77 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/encodinator'
+
+# This is a collection of parsing aids to be used in other modules
+class ParsingParcels
+
+  # This parser accepts a collection of lines which it will sweep through and tidy, giving the purified
+  # lines to the block (one line at a time) for further analysis. It analyzes a single line at a time, 
+  # which is far more memory efficient and faster for large files. However, this requires it to also 
+  # handle backslash line continuations as a single line at this point.
+  def code_lines(input)
+    comment_block = false
+    full_line = ''
+    input.each_line do |line|
+        m = line.match /(.*)\\\s*$/
+      if (!m.nil?)
+          full_line += m[1]
+      elsif full_line.empty?
+        _line, comment_block = clean_code_line( line, comment_block )
+        yield( _line )
+      else
+        _line, comment_block = clean_code_line( full_line + line, comment_block )
+        yield( _line )
+        full_line = ''
+      end
+    end    
+  end
+
+  private ######################################################################
+
+  def clean_code_line(line, comment_block)
+    _line = line.clean_encoding
+
+    # Remove line comments
+    _line.gsub!(/\/\/.*$/, '')
+
+    # Handle end of previously begun comment block
+    if comment_block
+      if _line.include?( '*/' )
+        # Turn off comment block handling state
+        comment_block = false
+        
+        # Remove everything up to end of comment block
+        _line.gsub!(/^.*\*\//, '')
+      else
+        # Ignore contents of the line if its entirely within a comment block
+        return '', comment_block        
+      end
+
+    end
+
+    # Block comments inside a C string are valid C, but we remove to simplify other parsing.
+    # No code we care about will be inside a C string.
+    # Note that we're not attempting the complex case of multiline string enclosed comment blocks
+    _line.gsub!(/"\s*\/\*.*"/, '')
+
+    # Remove single-line block comments
+    _line.gsub!(/\/\*.*\*\//, '')
+
+    # Handle beginning of any remaining multiline comment block
+    if _line.include?( '/*' )
+      comment_block = true
+
+      # Remove beginning of block comment
+      _line.gsub!(/\/\*.*/, '')
+    end
+
+    return _line, comment_block
+  end
+
+end

data/lib/ceedling/preprocessinator_extractor.rb

@@ -6,9 +6,13 @@
 # =========================================================================
 
 require 'ceedling/constants'
+require 'ceedling/encodinator'
+require 'ceedling/parsing_parcels'
 
 class PreprocessinatorExtractor 
  
+  constructor :parsing_parcels
+
   ##
   ## Preprocessor Expansion Output Handling
   ## ======================================
@@ -77,24 +81,35 @@ class PreprocessinatorExtractor
   # `input` must have the interface of IO -- StringIO for testing or File in typical use
   def extract_file_as_array_from_expansion(input, filepath)
 
-    # Iterate through all lines and alternate between extract and ignore modes.
-    # All lines between a '#' line containing the file name of our filepath and the
-    # next '#' line should be extracted.
-    #
-    # Notes:
-    #  1. Successive blocks can all be from the same source text file without a different, intervening '#' line.
-    #     Multiple back-to-back blocks could all begin with '# 99 "path/file.c"'.
-    #  2. The first line of the file could start a text block we care about.
-    #  3. End of file could end a text block.
-
-    base_name  = File.basename( filepath )
-    # Preprocessor output blocks take the form of '# <digits> <text> [optional digits]'
-    directive  = /^# \d+ \"/
-    # Preprocessor output blocks for the file we care about take the form of '# <digits> "path/filename.ext" [optional digits]'
-    marker     = /^# \d+ \".*#{Regexp.escape(base_name)}\"/
+    ##
+    ## Iterate through all lines and alternate between extract and ignore modes.
+    ## All lines between a '#' line containing the filepath to extract (a line marker) and the next '#' line should be extracted.
+    ##
+    ## GCC preprocessor output line marker format: `# <linenum> "<filename>" <flags>`
+    ## 
+    ## Documentation on line markers in GCC preprocessor output:
+    ##  https://gcc.gnu.org/onlinedocs/gcc-3.0.2/cpp_9.html
+    ##
+    ## Notes:
+    ##  1. Successive blocks can all be from the same source text file without a different, intervening '#' line.
+    ##     Multiple back-to-back blocks could all begin with '# 99 "path/file.c"'.
+    ##  2. The first line of the file could start a text block we care about.
+    ##  3. End of file could end a text block.
+    ##  4. Usually, the first line marker contains no trailing flag.
+    ##  5. Different preprocessors conforming to the GCC output standard may use different trailiing flags.
+    ##  6. Our simple ping-pong-between-line-markers extraction technique does not require decoding flags.
+    ##  
+
+    # Expand filepath under inspection to ensure proper match
+    extaction_filepath = File.expand_path( filepath )
+    # Preprocessor directive blocks generally take the form of '# <digits> <text> [optional digits]'
+    directive   = /^# \d+ \"/
+    # Line markers have the specific form of '# <digits> "path/filename.ext" [optional digits]' (see above)
+    line_marker = /^#\s\d+\s\"(.+)\"/
     # Boolean to ping pong between line-by-line extract/ignore
-    extract    = false
+    extract = false
 
+    # Collection of extracted lines
     lines = []
 
     # Use `each_line()` instead of `readlines()` (chomp removes newlines).
@@ -103,20 +118,15 @@ class PreprocessinatorExtractor
     input.each_line( chomp:true ) do |line|
       
       # Clean up any oddball characters in an otherwise ASCII document
-      encoding_options = {
-        :invalid           => :replace,  # Replace invalid byte sequences
-        :undef             => :replace,  # Replace anything not defined in ASCII
-        :replace           => '',        # Use a blank for those replacements
-        :universal_newline => true       # Always break lines with \n
-      }
-      line = line.encode("ASCII", **encoding_options).encode('UTF-8')
-
-      # Handle extraction if the line is not a preprocessor directive
+      line = line.clean_encoding
+
+      # Handle expansion extraction if the line is not a preprocessor directive
       if extract and not line =~ directive
         # Strip a line so we can omit useless blank lines
         _line = line.strip()
         # Restore text with left-side whitespace if previous stripping left some text
         _line = line.rstrip() if !_line.empty?
+        # Collect extracted lines
         lines << _line
 
       # Otherwise the line contained a preprocessor directive; drop out of extract mode
@@ -124,8 +134,12 @@ class PreprocessinatorExtractor
         extract = false
       end
 
-      # Enter extract mode if the line is a preprocessor directive with filename of interest
-      extract = true if line =~ marker
+      # Enter extract mode if the line is a preprocessor line marker with filepath of interest
+      matches = line.match( line_marker )
+      if matches and matches.size() > 1
+        filepath = File.expand_path( matches[1].strip() )
+        extract = true if extaction_filepath == filepath
+      end
     end
 
     return lines
@@ -143,11 +157,11 @@ class PreprocessinatorExtractor
     # Look for TEST_SOURCE_FILE("...") and TEST_INCLUDE_PATH("...") in a string (i.e. a file's contents as a string)
 
     regexes = [
-      /#{UNITY_TEST_SOURCE_FILE}.+?"\)/,
-      /#{UNITY_TEST_INCLUDE_PATH}.+?"\)/
+      /(#{PATTERNS::TEST_SOURCE_FILE})/,
+      /(#{PATTERNS::TEST_INCLUDE_PATH})/
     ]
 
-    return extract_tokens_by_regex_list( file_contents, *regexes )
+    return extract_tokens_by_regex_list( file_contents, *regexes ).map(&:first)
   end
 
 
@@ -204,7 +218,7 @@ class PreprocessinatorExtractor
     #  - Captures all text (non-greedily) after '#<directive>' on a first line through 0 or more line continuations up to a final newline.
     #  - Line continuations comprise a final '\' on a given line followed by whitespace & newline, wrapping to the next
     #    line up to a final '\' on that next line.
-    regex = /(#\s*#{directive}\s+.*?(\\\s*\n.*?)*)\n/
+    regex = /(#\s*#{directive}[^\n]*)\n/
 
     tokens = extract_tokens_by_regex_list( file_contents, regex )
 
@@ -232,7 +246,9 @@ class PreprocessinatorExtractor
 
     # For each regex provided, extract all matches from the source string
     regexes.each do |regex|
-      tokens += file_contents.scan( regex )
+      @parsing_parcels.code_lines( file_contents ) do |line|
+        tokens += line.scan( regex )
+      end
     end
 
     return tokens

data/lib/ceedling/preprocessinator_file_handler.rb

@@ -33,7 +33,7 @@ class PreprocessinatorFileHandler
     @tool_executor.exec( command )
 
     @file_wrapper.open( preprocessed_filepath, 'r' ) do |file|
-      contents = @preprocessinator_extractor.extract_file_as_array_from_expansion( file, preprocessed_filepath )
+      contents = @preprocessinator_extractor.extract_file_as_array_from_expansion( file, source_filepath )
     end
 
     # Bail out, skipping directives-only preprocessing if no extras are required
@@ -63,7 +63,7 @@ class PreprocessinatorFileHandler
     @file_wrapper.open( preprocessed_filepath, 'r' ) do |file|
       # Get code contents of preprocessed directives-only file as a string
       # TODO: Modify to process line-at-a-time for memory savings & performance boost
-      _contents = @preprocessinator_extractor.extract_file_as_string_from_expansion( file, preprocessed_filepath )
+      _contents = @preprocessinator_extractor.extract_file_as_string_from_expansion( file, source_filepath )
 
       # Extract pragmas and macros from 
       pragmas = @preprocessinator_extractor.extract_pragmas( _contents )
@@ -133,8 +133,8 @@ class PreprocessinatorFileHandler
     # ----------------------------------------------------
     #  - We rely on search paths at compilation rather than explicit #include paths
     #  - Match (#include ")((path/)+)(file") and reassemble string using first and last matching groups
-    _contents.gsub!( /(#include\s+")(([^\/]+\/)+)(.+")/, '\1\4' )
-    
+    _contents.gsub!( /(#include\s+")(?:(?:[^"\/]+\/)+)([^"\/]*")/, '\1\2' )
+
     # Write contents of final preprocessed file
     @file_wrapper.write( preprocessed_filepath, _contents )
   end
@@ -159,7 +159,7 @@ class PreprocessinatorFileHandler
     @tool_executor.exec( command )
 
     @file_wrapper.open( preprocessed_filepath, 'r' ) do |file|
-      contents = @preprocessinator_extractor.extract_file_as_array_from_expansion( file, preprocessed_filepath )
+      contents = @preprocessinator_extractor.extract_file_as_array_from_expansion( file, source_filepath )
     end
 
     preprocessed_filepath = @file_path_utils.form_preprocessed_file_directives_only_filepath( source_filepath, test )
@@ -178,7 +178,7 @@ class PreprocessinatorFileHandler
     @file_wrapper.open( preprocessed_filepath, 'r' ) do |file|
       # Get code contents of preprocessed directives-only file as a string
       # TODO: Modify to process line-at-a-time for memory savings & performance boost
-      _contents = @preprocessinator_extractor.extract_file_as_string_from_expansion( file, preprocessed_filepath )
+      _contents = @preprocessinator_extractor.extract_file_as_string_from_expansion( file, source_filepath )
 
       # Extract TEST_SOURCE_FILE() and TEST_INCLUDE_PATH()
       test_directives = @preprocessinator_extractor.extract_test_directive_macro_calls( _contents )

data/lib/ceedling/preprocessinator_includes_handler.rb

@@ -7,7 +7,7 @@
 
 class PreprocessinatorIncludesHandler
 
-  constructor :configurator, :tool_executor, :test_context_extractor, :yaml_wrapper, :loginator, :reportinator
+  constructor :configurator, :tool_executor, :test_context_extractor, :file_wrapper, :yaml_wrapper, :loginator, :reportinator
 
   ##
   ## Includes Extraction Overview

data/lib/ceedling/test_context_extractor.rb

@@ -8,10 +8,11 @@
 require 'ceedling/exceptions'
 require 'ceedling/file_path_utils'
 require 'ceedling/generator_test_runner' # From lib/ not vendor/unity/auto
+require 'ceedling/encodinator'
 
 class TestContextExtractor
 
-  constructor :configurator, :file_wrapper, :loginator
+  constructor :configurator, :file_wrapper, :loginator, :parsing_parcels
 
   def setup
     # Per test-file lookup hashes
@@ -52,7 +53,7 @@ class TestContextExtractor
     source_extras = []
     includes = []
 
-    code_lines( input ) do |line|
+    @parsing_parcels.code_lines( input ) do |line|
       if args.include?( :build_directive_include_paths )
         # Scan for build directives: TEST_INCLUDE_PATH()
         include_paths += extract_build_directive_include_paths( line )
@@ -98,7 +99,7 @@ class TestContextExtractor
   def extract_includes(input)
     includes = []
 
-    code_lines( input ) {|line| includes += _extract_includes( line ) }
+    @parsing_parcels.code_lines( input ) {|line| includes += _extract_includes( line ) }
 
     return includes.uniq
   end
@@ -130,7 +131,7 @@ class TestContextExtractor
     return val
   end
 
-  # Source header_includes within test file
+  # Source C includes within test file
   def lookup_source_includes_list(filepath)
     val = nil
     @lock.synchronize do
@@ -234,23 +235,13 @@ class TestContextExtractor
     end
   end
 
-  # Exposed for testing
-  def code_lines(input)
-    comment_block = false
-    # Far more memory efficient and faster (for large files) than slurping entire file into memory
-    input.each_line do |line|
-      _line, comment_block = clean_code_line( line, comment_block )
-      yield( _line )
-    end    
-  end
-
   private #################################
 
   def collect_build_directive_source_files(filepath, files)
     ingest_build_directive_source_files( filepath, files.uniq )
 
     debug_log_list(
-      "Extra source files found via #{UNITY_TEST_SOURCE_FILE}()",
+      "Extra source files found via TEST_SOURCE_FILE()",
       filepath,
       files
     )
@@ -260,7 +251,7 @@ class TestContextExtractor
     ingest_build_directive_include_paths( filepath, paths.uniq )
 
     debug_log_list(
-      "Search paths for #includes found via #{UNITY_TEST_INCLUDE_PATH}()",
+      "Search paths for #includes found via TEST_INCLUDE_PATH()",
       filepath,
       paths
     )
@@ -292,8 +283,8 @@ class TestContextExtractor
   def extract_build_directive_source_files(line)
     source_extras = []
 
-    # Look for TEST_SOURCE_FILE("<*>.<*>") statement
-    results = line.scan(/#{UNITY_TEST_SOURCE_FILE}\(\s*\"\s*(.+?\.\w+)*?\s*\"\s*\)/)
+    # Look for TEST_SOURCE_FILE("<*>") statement
+    results = line.scan(PATTERNS::TEST_SOURCE_FILE)
     results.each do |result|
       source_extras << FilePathUtils.standardize( result[0] )
     end
@@ -305,7 +296,7 @@ class TestContextExtractor
     include_paths = []
 
     # Look for TEST_INCLUDE_PATH("<*>") statements
-    results = line.scan(/#{UNITY_TEST_INCLUDE_PATH}\(\s*\"\s*(.+?)\s*\"\s*\)/)
+    results = line.scan(PATTERNS::TEST_INCLUDE_PATH)
     results.each do |result|
       include_paths << FilePathUtils.standardize( result[0] )
     end
@@ -370,58 +361,6 @@ class TestContextExtractor
     return filepath.to_s.to_sym
   end
 
-  def clean_code_line(line, comment_block)
-    _line = sanitize_encoding( line )
-
-    # Remove line comments
-    _line.gsub!(/\/\/.*$/, '')
-
-    # Handle end of previously begun comment block
-    if comment_block
-      if _line.include?( '*/' )
-        # Turn off comment block handling state
-        comment_block = false
-        
-        # Remove everything up to end of comment block
-        _line.gsub!(/^.*\*\//, '')
-      else
-        # Ignore contents of the line if its entirely within a comment block
-        return '', comment_block        
-      end
-
-    end
-
-    # Block comments inside a C string are valid C, but we remove to simplify other parsing.
-    # No code we care about will be inside a C string.
-    # Note that we're not attempting the complex case of multiline string enclosed comment blocks
-    _line.gsub!(/"\s*\/\*.*"/, '')
-
-    # Remove single-line block comments
-    _line.gsub!(/\/\*.*\*\//, '')
-
-    # Handle beginning of any remaining multiline comment block
-    if _line.include?( '/*' )
-      comment_block = true
-
-      # Remove beginning of block comment
-      _line.gsub!(/\/\*.*/, '')
-    end
-
-    return _line, comment_block
-  end
-
-  # Note: This method modifies encoding in place (encode!) in an attempt to reduce long string copies
-  def sanitize_encoding(content)
-    encoding_options = {
-      :invalid           => :replace,  # Replace invalid byte sequences
-      :undef             => :replace,  # Replace anything not defined in ASCII
-      :replace           => '',        # Use a blank for those replacements
-      :universal_newline => true       # Always break lines with \n
-    }
-
-    return content.encode("ASCII", **encoding_options).encode('UTF-8')
-  end
-
   def debug_log_list(message, filepath, list)
     msg = "#{message} in #{filepath}:"
     if list.empty?

data/lib/ceedling/test_invoker.rb

@@ -343,13 +343,14 @@ class TestInvoker
           test_pass          = @file_path_utils.form_pass_results_filepath( details[:paths][:results], details[:filepath] )
           test_fail          = @file_path_utils.form_fail_results_filepath( details[:paths][:results], details[:filepath] )
 
-          # Identify all the objects shall not be linked and then remove them from objects list.
+          # Assemble a list of object files from .c files that have been #included in the test file
           test_no_link_objects = 
             @file_path_utils.form_test_build_objects_filelist(
               details[:paths][:build],
               @helper.fetch_shallow_source_includes( details[:filepath] ))
-          
-          test_objects = test_objects.uniq - test_no_link_objects
+
+          # Redefine test_objects, removing any problematic object file that would otherwise get linked into the test executable
+          test_objects = (test_objects.uniq - test_no_link_objects)
 
           @lock.synchronize do
             details[:sources]         = test_sources

data/lib/ceedling/test_invoker_helper.rb

@@ -64,12 +64,12 @@ class TestInvokerHelper
       end
 
       if not valid_extension
-        error = "File '#{source}' specified with #{UNITY_TEST_SOURCE_FILE}() in #{test} is not a #{ext_message} source file"
+        error = "File '#{source}' specified with TEST_SOURCE_FILE() in #{test} is not a #{ext_message} source file"
         raise CeedlingException.new(error)
       end
 
       if @file_finder.find_build_input_file(filepath: source, complain: :ignore, context: TEST_SYM).nil?
-        error = "File '#{source}' specified with #{UNITY_TEST_SOURCE_FILE}() in #{test} cannot be found in the source file collection"
+        error = "File '#{source}' specified with TEST_SOURCE_FILE() in #{test} cannot be found in the source file collection"
         raise CeedlingException.new(error)
       end
     end
@@ -321,7 +321,7 @@ class TestInvokerHelper
         notice +=   "OPTIONS:\n" +
                     "  1. Doublecheck this test's #include statements.\n" +
                     "  2. Simplify complex macros or fully specify symbols for this test in :project ↳ :defines.\n" +
-                    "  3. If no header file corresponds to the needed source file, use the #{UNITY_TEST_SOURCE_FILE}()\n" +
+                    "  3. If no header file corresponds to the needed source file, use the TEST_SOURCE_FILE()\n" +
                     "     build diective macro in this test to inject a source file into the build.\n\n" +
                     "See the docs on conventions, paths, preprocessing, compilation symbols, and build directive macros.\n\n"
 

data/lib/ceedling/tool_executor.rb

@@ -134,7 +134,7 @@ class ToolExecutor
     args_index = 0
 
     # handle ${#} input replacement
-    if (element =~ TOOL_EXECUTOR_ARGUMENT_REPLACEMENT_PATTERN)
+    if (element =~ PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
       args_index = ($2.to_i - 1)
 
       if (args.nil? or args[args_index].nil?)
@@ -159,7 +159,7 @@ class ToolExecutor
     end
 
     # handle inline ruby string substitution
-    if (build_string =~ RUBY_STRING_REPLACEMENT_PATTERN)
+    if (build_string =~ PATTERNS::RUBY_STRING_REPLACEMENT)
       build_string.replace(@system_wrapper.module_eval(build_string))
     end
 
@@ -187,7 +187,7 @@ class ToolExecutor
 
     expansion.each do |item|
       # String eval substitution
-      if (item =~ RUBY_STRING_REPLACEMENT_PATTERN)
+      if (item =~ PATTERNS::RUBY_STRING_REPLACEMENT)
         elements << @system_wrapper.module_eval(item)
       # Global constants
       elsif (@system_wrapper.constants_include?(item))

data/lib/ceedling/tool_validator.rb

@@ -55,8 +55,8 @@ class ToolValidator
 
     # Skip everything if we've got an argument replacement pattern or Ruby string replacement in :executable
     # (Allow executable to be validated by shell at run time)
-    return true if (executable =~ TOOL_EXECUTOR_ARGUMENT_REPLACEMENT_PATTERN)
-    return true if (executable =~ RUBY_STRING_REPLACEMENT_PATTERN)
+    return true if (executable =~ PATTERNS::TOOL_EXECUTOR_ARGUMENT_REPLACEMENT)
+    return true if (executable =~ PATTERNS::RUBY_STRING_REPLACEMENT)
 
     # Extract the executable (including optional filepath) apart from any additional arguments
     # Be mindful of legal quote enclosures (e.g. `"Code Cruncher" foo bar`)

data/lib/version.rb

@@ -15,7 +15,7 @@
 module Ceedling
   module Version
     # Convenience constants for gem building, etc.
-    GEM = '1.0.0'
+    GEM = '1.0.1'
     TAG = GEM
 
     # If run as a script print Ceedling's version to $stdout

data/plugins/dependencies/example/boss/project.yml

@@ -27,9 +27,6 @@
   :test_threads: 8
   :compile_threads: 8
 
-  # you can specify different yaml config files which modify the existing one
-  :options_paths: []
-
   # enable release build (more details in release_build section below)
   :release_build: TRUE
 

data/plugins/dependencies/example/supervisor/project.yml

@@ -27,9 +27,6 @@
   :test_threads: 8
   :compile_threads: 8
 
-  # you can specify different yaml config files which modify the existing one
-  :options_paths: []
-
   # enable release build (more details in release_build section below)
   :release_build: TRUE
 

data/plugins/fff/README.md

@@ -1,6 +1,6 @@
 # A Fake Function Framework Plug-in for Ceedling
 
-This is a plug-in for [Ceedling](https://github.com/ThrowTheSwitch/Ceedling) to use the [Fake Function Framework](https://github.com/ElectronVector/fake_function_framework) for mocking instead of CMock.
+This is a plug-in for [Ceedling](https://github.com/ThrowTheSwitch/Ceedling) to use the [Fake Function Framework](https://github.com/meekrosoft/fff) for mocking instead of CMock.
 
 Using _fff_ provides less strict mocking than CMock, and can allow for more loosely-coupled tests.
 

data/plugins/fff/lib/fff_mock_generator.rb

@@ -5,6 +5,8 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
+require 'stringio'
+
 # Creates mock files from parsed header files that can be linked into applications.
 # The mocks created are compatible with CMock for use with Ceedling.
 

data/plugins/module_generator/README.md

@@ -35,6 +35,15 @@ In this example, we'd create 9 files total: 3 headers, 3 source files, and 3 tes
 files would be named `SecretLairModel`, `SecretLairConductor`, and `SecretLairHardware`. Isn't
 that nice?
 
+The module generator understands the following patterns:
+
+ - `src` -- generate only a source file
+ - `test` -- generate only a test file
+ - `dh` -- generate 6 files for the driver-hardware pattern
+ - `dih` -- generate 9 files for the driver-interrupt-hardware pattern
+ - `mch` -- generate 9 files for the model-conductor-hardware pattern
+ - `mvp` -- generate 9 files for the model-view-presenter pattern
+
 ### Paths
 
 The directories found in the project `:paths:` are reused. You can also specify an alternative default generation path using: 
@@ -97,13 +106,60 @@ You can see that more complicated structures will have files placed in the wrong
 time... no worries... you can move the file after it's created... but if your project has any kind of 
 consistent structure, the guessing engine does a good job of making it work.
 
-Three more quick notes about the path-matching:
+A few more quick notes about the path-matching:
 
 1. You can give multiple ordered hints that map roughly to folder nesting! `lab:secret:lair` will 
    happily match to put `lair.c` in a folder like `my/lab/secret/`.
 
-2. Whenever the matcher fails to find a good candidate (or if it finds multiple equally good 
-   candidates), it will always guess in the order you have the paths listed in your project.yml file
+2. If the matcher isn't given any path information or it finds multiple equally good candidates, 
+   it will always guess in the order you have the paths listed in your project.yml file
+
+3. If the matcher completely fails to find a good candidate, it will return an error, allowing you
+   to rectify the situation.
+
+4. What path is "first" when you're using `**` pattern in your `:paths:` specifications? The parent
+   folder is used first, then its children alphabetically, and so on. This is important when 
+   considering where files (or especially subfolders... see below) will be generated.
+
+### Adding to Paths
+
+In addition to the pattern matching above, you can add slashes (`/`) to your filename specification.
+When a slash is used instead of a colon (`:`), it will stop using pattern matching and assume the
+subdirectory is supposed to be there. If the subdir is NOT there, it will automatically add it.
+
+Let's try an example with our previous path specification:
+
+```
+:paths:
+  :source:
+    - src/**   #this might contain subfolders lab, lair, and other
+  :include:
+    - inc/**   #again, this might contain subfolders lab, lair, other, and shared
+  :test:
+    - test
+```
+
+Then, use the following command:
+
+```
+ceedling module:create[newlab/SecretLair]
+```
+
+This will create the following 3 files:
+
+ - `src/newlab/SecretLair.c`
+ - `inc/newlab/SecretLair.h`
+ - `test/newlab/TestSecretLair.c`
+
+Technically, you can start with a colon and specify part of a path, then use a slash
+to specify the remainder of the path to use. In most circumstances, this should work... however
+it suffers from the same potential issues as the matcher above, with the added joy of creating 
+new subdirectories for you without asking. 
+
+It's important to note the module generator doesn't care if these new subdirectories are covered 
+by the current path specification. This allows you to create the files before updating the
+`project.yml` file if desired, but it also means you might accidentally think you've created
+a file that Ceedling can see, when it can't. 
 
 ## Stubbing
 
@@ -130,7 +186,6 @@ follows the default ceedling structure... but what if you have a different struc
 
 ```
 :module_generator:
-  :project_root: ./
   :naming: :bumpy
   :includes: 
     - :src: []