1 files changed, 63 insertions, 15 deletions

diff --git a/README.md b/README.md
index 69ca732..5bd146e 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,32 @@ the language of the code snippet can be provided and is useful to enable correct
 ```
 ~~~
 
-An identifier can also be a file name matching the following regex
+### Identifiers
+
+An identifier can either be a string, representing a macro to be used inside other code blocks, or a filename.
+In the latter, the code block will be considered a valid entry point for code generation.
+
+```{#types .rust}
+#[derive(Eq, Hash, PartialEq)]
+enum Key {
+  Macro(String),
+  Entry(PathBuf)
+}
+
+impl Key {
+  fn get_path(&self) -> Option<&PathBuf> {
+    match self {
+      Self::Entry(s) => Some(&s),
+      Self::Macro(_) => None
+    }
+  }
+}
+
+```
+
+There are currently 3 (possibly overlapping) scenarios in which an identifier is considered a valid filename.
+
+First, the filename matches the following regex
 
 ```{#regex_path .rust}
 static ref PATH: Regex =
@@ -57,8 +82,7 @@ static ref PATH: Regex =
   ).unwrap();
 ```
 
-In that case the code block is considered a valid **entry point** for the generation of a file with that name.
-The code block defines the content of the new file.
+For example
 
 ~~~
 ```{#file.py .python}
@@ -66,8 +90,10 @@ The code block defines the content of the new file.
 ```
 ~~~
 
-File names can be generated in subfolders using the `path` attribute.
-The following code block determines the content of file `path/to/file.py`.
+Second, the code block contains a `path` attribute.
+With this feature, we can generated a file into a more complex folder structure.
+
+For example, the following code block determines the content of file `path/to/file.py`.
 
 ~~~
 ```{#file.py .python path="path/to/"}
@@ -77,16 +103,30 @@ The following code block determines the content of file `path/to/file.py`.
 
 This path is relative to the current working directory, unless [the `-o`/`--output` flag is used](#command-line-interface).
 
+Third, the code contains the `entry` class.
+This is useful when declaring an entry point that doesn't match any of the previous cases.
+
+~~~
+```{#Dockerfile .dockerfile .entry}
+[Docker directives]
+```
+~~~
+
+Any ID that doesn't match any of the previous cases is considered an internal macro.
 Code blocks without an ID are ignored.
 
 ```{#code_block_gathering .rust}
 if !id.is_empty() {
   let key = {
-    let path = attrs.iter().find(|(k,_)| k == "path");
-    if let Some(path) = path {
-      format!("{}{}", path.1, id) 
+    <<regex_path_lazy>>
+    let entry = clss.contains(&String::from("entry"));
+    let path = attrs
+      .into_iter()
+      .find_map(|(k,p)| if k == "path" { Some(p.clone()) } else { None });
+    if entry || path.is_some() || PATH.is_match(id) {
+      Key::Entry(PathBuf::from(path.unwrap_or_default()).join(id)) 
     } else {
-      id.to_string()
+      Key::Macro(id.to_string())
     }
   };
   <<code_block>>
@@ -96,6 +136,8 @@ if !id.is_empty() {
 }
 ```
 
+### Redefining code blocks
+
 Code blocks are processed in order.
 By default, if an identifier is already defined, the code block is appended to the current corresponding value.
 
@@ -314,7 +356,7 @@ use std::collections::HashMap;
 ```
 
 ```{#types .rust}
-type Blocks<'a> = HashMap<String,Cow<'a,str>>;
+type Blocks<'a> = HashMap<Key,Cow<'a,str>>;
 ```
 
 Code blocks are wrapped into a [`Cow`](https://doc.rust-lang.org/stable/std/borrow/enum.Cow.html), i.e., a "copy-on-write" smart pointer, to avoid string duplication, unless strictly necessary.
@@ -366,7 +408,7 @@ In case we reach the maximum allowed depth we truncate code block substitution a
 |caps: &Captures| {
   if current_depth < max_depth {
     let block = blocks
-      .get(&caps[2])
+      .get(&Key::Macro(caps[2].to_string()))
       .expect("Block not present")
       .clone();
     indent(block, caps[1].len())
@@ -387,10 +429,11 @@ fn build(
   blocks: &Blocks,
   max_depth: u32
 ) {
-  <<regex_definition>>
+  <<regex_macro_lazy>>
   blocks
     .iter()
-    .for_each(|(path,code)| if PATH.is_match(path) { 
+    .filter_map(|(key,code)| { key.get_path().map(|k| (k,code)) })
+    .for_each(|(path,code)| {
       <<code_generation>>
     })
 }
@@ -506,11 +549,16 @@ use lazy_static::lazy_static;
 use regex::{Captures,Regex};
 ```
 
-We wrap the regex definition in a `lazy_static` macro
+We wrap the regex definitions in a `lazy_static` macro
 
-```{#regex_definition .rust}
+```{#regex_path_lazy .rust}
 lazy_static! {
   <<regex_path>>
+}
+```
+
+```{#regex_macro_lazy .rust}
+lazy_static! {
   <<regex_macro>>
 }
 ```