Merge pull request #42 from jamesramsay/default-values

Default values

README.md

@@ -53,10 +53,10 @@ hercule.transcludeString("# Title\n\n:[abstract](abstract.md)", function(output)
 Hercule extends the Markdown inline link syntax with a leading colon (`:`) to denote the link should transcluded.
 
 ```markdown
-This is an :[example link](example.md).
+This is an :[example link](foo.md).
 ```
 
-Output from `hercule examples/basic.md`:
+Output from `hercule examples/basic/main.md`:
 
 ```
 This is an example transclusion.
@@ -82,28 +82,65 @@ Jackdaws love my big sphinx of quartz.
 
 ## Advanced use: placeholders and references
 
-In addition to basic file transclusion, Hercule supports placeholders and references.
+As well as basic file transclusion, Hercule supports placeholders and references.
 Placeholders and references may be useful for increasing the _'dryness'_ of your source documents.
 
-`foo.md`
+Example placeholder link in `examples/advanced/foo.md`:
 
 ```markdown
 is an :[example placeholder](bar)
 ```
 
-In the example file `foo.md`, `bar` is being used as a placeholder.
-When we transclude `foo.md` into our document, the placeholder can be targeted to specify a file or string.
+In this example `bar` is being used as a placeholder link.
+When transcluding `foo.md`, the placeholder can be targeted by a reference file or string.
 
 ```markdown
-This document :[example link with references](foo.md bar:"example foobar!")
+This document :[example link with string reference](foo.md bar:"example foobar!")
 ```
 
-Output from `hercule examples/basic.md`:
+Output from `hercule examples/advanced/main.md`:
 
 ```
 This document is an example foobar!
 ```
 
+References are passed down to any nested transclusion links.
+
+## Advanced use: default placeholders
+
+Sometimes a file might be used in multiple contexts, some contexts requiring references and others not.
+Default placeholders help handle this situation more conveniently.
+
+The following example uses Apiary's [Markdown Syntax for Object Notation (MSON)](https://github.com/apiaryio/mson).
+
+```markdown
+## Properties
+
+- id: 1 (number, required)
+- name: Cucumber (string, required)
+- description: Essential for tzatziki (string, :[is required](required || "optional"))
+```
+
+Output from `hercule examples/default/main.md` without reference `required`:
+
+```markdown
+## Properties
+
+- id: 1 (number, required)
+- name: Cucumber (string, required)
+- description: Essential for tzatziki (string, optional)
+```
+
+Output from `hercule examples/default/main-override.md` with reference `required`:
+
+```markdown
+## Properties
+
+- id: 1 (number, required)
+- name: Cucumber (string, required)
+- description: Essential for tzatziki (string, required)
+```
+
 ## Whitespace sensitivity
 
 Leading whitespace is significant in Markdown.
@@ -120,6 +157,13 @@ Each line of `snippet.c` will be indented with the whitespace preceding it.
 
 ----
 
-## Related projects
+## Acknowledgments
+
+Special thanks:
+
+- [@zdne](https://github.com/zdne) for your feedback and ideas, particularly on syntax
+- [@MichaelHirn](https://github.com/MichaelHirn) for contributions including the default link behaviour
+
+Related projects:
 
 - [Grunt Hercule](https://github.com/chesleybrown/grunt-hercule): a Grunt task that wraps hercule

examples/advanced/main.md

@@ -0,0 +1 @@
+This document :[example link with string reference](foo.md bar:"example foobar!")

examples/basic/main.md

@@ -0,0 +1 @@
+This is an :[example link](foo.md).

examples/default/foo.md

@@ -0,0 +1,5 @@
+## Properties
+
+- id: 1 (number, required)
+- name: Cucumber (string, required)
+- description: Essential for tzatziki (string, :[is required](required || "optional"))

examples/default/main-override.md

@@ -0,0 +1 @@
+:[cucumber](foo.md required:"required")

examples/default/main.md

@@ -0,0 +1 @@
+:[cucumber](foo.md)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hercule",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Markdown transcluder",
   "main": "./lib/hercule",
   "scripts": {

src/grammar.coffee

@@ -38,7 +38,7 @@ placeholder = p:[a-zA-Z0-9]+ {
   return p.join("");
 }
 
-default = emptyString / string
+default = httpLink / fileLink / string
 
 link = httpLink / fileLink / string / reset
 
@@ -56,15 +56,7 @@ httpLink = left:("http://" / "https://") right:[^ ()]+ {
   };
 }
 
-emptyString = '\"' '\"' {
-  return {
-    "hrefType": "string",
-    "href": ""
-  };
-}
-
-
-string = '\"' s:([^\"]+) '\"' {
+string = '\"' s:([^\"]*) '\"' {
   return {
     "hrefType": "string",
     "href": s.join("")

src/hercule.coffee

@@ -18,16 +18,15 @@ transclude = (input, relativePath, parents, parentRefs, logger, cb) ->
     {href, hrefType, references, parents, whitespace, placeholder} = link
 
     matchingReferences = parentRefs.filter (ref) -> "#{ref.placeholder}" is "#{href}"
-    if matchingReferences[0]?
-      overridingReference = matchingReferences[0]
-      logger "Overriding reference: #{JSON.stringify overridingReference}"
-
-    if not matchingReferences[0]? and hrefType is "file"
-      href = path.join relativePath, href
-
+    overridingReference = matchingReferences[0] || link.default
     href = overridingReference.href if overridingReference?
     hrefType = overridingReference.hrefType if overridingReference?
 
+    if overridingReference?
+      logger "Overriding reference: #{JSON.stringify overridingReference}"
+    else if hrefType is "file"
+      href = path.join relativePath, href
+
     if _.contains parents, href
       logger "#{href} is in parents:\n#{JSON.stringify parents}"
       throw new Error("Circular reference detected")
@@ -38,8 +37,6 @@ transclude = (input, relativePath, parents, parentRefs, logger, cb) ->
 
     utils.inflate href, hrefType, (content) ->
       logger "Transcluding: #{href} (#{hrefType}) into #{parents[-1..][0]}"
-      if content is null && link.default
-        content = link.default.href
       transclude content, dir, parents, references, logger, (output) ->
         if output?
           # Preserve leading whitespace and trim excess new lines at EOF