--- /dev/null
+<!doctypehtml><html><head><title>definitions</title><meta content="definining variables and patterns"name=description><meta content="huck boles"name=author></head><body><a href=../index.html>home</a><div><h1><strong>definitions</strong> - <em>0.1.3</em></h1></div><p>definining variables and patterns</p><article><h2 id=rules>rules</h2><p>definition blocks are allowed in all files, but have to be before any source text, and after any header settings (which are a special type of definition block).</p><p>a block consists of a sigil for the definition type, followed by braces that surround assignment statements.</p><p>assignments are identifiers, followed by an equals sign (=), then a value</p><p>definition blocks can have spaces and new lines arbitrarily inserted between each component, and support multiple assignments per block.</p><h2 id=identifiers>identifiers</h2><p>identifiers can contain alphanumeric ascii values and underscores [a-zA-Z0-9_], as well as separating dots (.)</p><p>variable identifiers without dots are available to any pattern called by the file.</p><p>array identifiers without dots are available only to the pattern they are defined in.</p><p>variable and array identifiers with separating dots use the final item as the identifier, and the preceding items are expanded like a pattern identifier to make a mask on the definition. the definition is only valid in that pattern directory (not children), otherwise it is undefined.</p><p>pattern identifiers expand to a directory of files in the pattern directory by replacing .’s with /’s, appending necessary file extensions when called. the value selects a single file in the directory as the desired pattern.</p><p>an identifier preceded by an star (*) will be marked as local to the file it is defined in. entire blocks can be marked as local by preceding them with a star. if necessary, a single assignment in a local block can be made global again by prefixing it with an exclamation mark (!).</p><h2 id=values>values</h2><p>values can be a double or single quoted string, if defining an array, a value is a bracket surrounded, comma separated list of strings.</p><p>all values can optionally be assigned as <strong><em>BLANK</em></strong>, which expands to nothing.</p><p>patterns can also be assigned as <strong><em>DEFAULT</em></strong>, for overriding globally defined patterns.</p><h2 id=scope>scope</h2><p>any value defined in a file called <strong>default.meta</strong> in the source directory is defined in all files in the current and child directories.</p><p>values defined normally are defined for any file called in the chain of expansion. this value can be overridden, either for a single file in the chain by prefixing the definition with a star (*), or for any files further down the chain, by defining a new value normally.</p><h2 id=examples>examples</h2><pre><code>${
+ *foo = 'bar' -{ foo is only equal to bar in this file }
+ bar.baz = BLANK -{ this only applies to pattern/bar/*.meta }
+ baz = quux -{ baz is equal to quux in every file called during
+ expansion, unless it gets overridden }
+}
+
+@{
+ bar = ['foo','bar']
+ baz.blank = BLANK -{ this inserts nothing }
+
+ foo.bar = [ 'foobar', 'foobaz' ]
+ -{ this will copy pattern/foo/*.meta twice, inserting 'foobar and 'foobaz'
+ once each at the location of @{bar} }
+}
+
+-{ all of these patterns are only defined for this file }
+*&{
+ foo.bar = BLANK
+ bar.default = DEFAULT
+
+ !baz = "bar"
+ -{ except for this definition, which
+ continues down the expansion chain }
+}</code></pre></article></body><foot> made with <strong>metaforge</strong> </foot></html>
\ No newline at end of file
--- /dev/null
+<!doctypehtml><html><head><title>expansions</title><meta content="expanding variables and patterns in a file"name=description><meta content="huck boles"name=author></head><body><a href=../index.html>home</a><div><h1><strong>expansions</strong> - <em>0.1.3</em></h1></div><p>expanding variables and patterns in a file</p><article><h2 id=syntax>syntax</h2><p>a sigil followed by braces, with an identifier inside.</p><p>happens inside the source, expanding to the relevant value when the file is built</p><h3 id=examples>examples</h3><pre><code>...this is a string with a ${variable} to be expanded...
+
+...this line has a &{pattern} inside of it...
+
+...this @{array} will be replaced...</code></pre><h2 id=behavior>behavior</h2><p>all expansions are decided by the value defined for the identifier, following inheritance rules, and directory masking for variables and arrays.</p><h3 id=variables>variables</h3><p>variables are simply replaced by the defined value, with no other substitution. they’re useful for small things that are frequently changed in a pattern, but don’t need any extra expansion.</p><h4 id=example>example</h4><pre><code>definition:
+ ${
+ baz = "foo"
+ bar.baz = "quux"
+ quux = BLANK
+ }
+
+pattern [foo]: <p>${baz} ${ quux}</p>
+
+expanded [foo]: <p>foo </p>
+
+pattern [bar]: <p>${baz} ${ quux}</p>
+
+expanded [bar]: <p>quux </p></code></pre><h3 id=arrays>arrays</h3><p>arrays are similar to variables, but are closely related to the masking pattern. after all expansions happen in a pattern, each defined array maps its contents across copies of the pattern, resulting in a easy method for duplicating repetitive parts of patterns.</p><h4 id=example-1>example</h4><pre><code>pattern [foo]: <p>@{bar}</p>
+
+defintion: @{ foo.bar = ['foo', 'bar', 'baz'] }
+
+expands to: <p>foo</p><p>bar</p><p>baz</p></code></pre><p>it’s generally best to keep arrays inside small self-contained patterns, otherwise unwanted parts of the file may be duplicated.</p><h3 id=patterns>patterns</h3><p>patterns expand by looking for files using the pattern directory as a root. the identifier becomes a directory by changing .’s to /’s. if a defined value exists, it’s used as the filename, with a <strong>.meta</strong> extension added automatically. if no value is defined, metaforge next looks for files with the exact name in the identifier, again substituting .’s to /’s. if a file still hasn’t been found, or the pattern has most recently been defined as <strong><em>DEFAULT</em></strong>, then <strong>default.meta</strong> is selected from the identified directory.</p><h4 id=example-search>example search</h4><pre><code>foo.bar => pattern/foo/bar/*.meta => pattern/foo/bar.meta => pattern/foo/bar/default.meta</code></pre><p>if no file is found metaforge will either insert an empty string, or panic depending on the flags and header settings in effect. a pattern defined as <strong><em>BLANK</em></strong> will always expand to a blank string without errors.</p><p>if the identifier in the pattern is <strong><em>SOURCE</em></strong>, the pattern will expand using the processed source from the original calling file in the source directory. this goes through an extra step right before insertion, calling pandoc on the file to convert between the chosen filetypes.</p><p>once the filename is determined, it is parsed and expands any contained variables, arrays and patterns. if it is a <strong><em>SOURCE</em></strong> pattern, it is converted to html after the expansions. the expanded pattern is then inserted in place of the calling identifier.</p><h2 id=building>building</h2><p>as each file is built, the first thing expanded is the relevant <strong>base/[FILE].meta</strong> pattern, so it is required to have at least a <strong>default.meta</strong> in the <strong>pattern/base</strong> directory</p><h3 id=example-2>example</h3><pre><code>pattern [base]: <html>&{body}</html>
+
+pattern [body]: <body>&{SOURCE}</body>
+
+source [SOURCE]: foo *bar* baz
+
+expanded [base] : <html><body><p>foo <italic>bar</italic> baz</p></body></html></code></pre></article></body><foot> made with <strong>metaforge</strong> </foot></html>
\ No newline at end of file
--- /dev/null
+<!doctypehtml><html><head><title>flags</title><meta content="available flags for running metaforge"name=description><meta content="huck boles"name=author></head><body><a href=../index.html>home</a><div><h1><strong>flags</strong> - <em>0.1.3</em></h1></div><p>available flags for running metaforge</p><article><h2 id=available-flags>available flags</h2><pre><code>-r, --root <ROOT_DIR>
+ root directory, contains source, pattern and build directories
+ defaults to current working directory
+-s, --source <SOURCE_DIR>
+ source file directory, contains directory structure and .meta files for completed site
+ defaults to [root_dir]/source
+-b, --build <BUILD_DIR>
+ build directory, directory where the final site gets built
+ defaults to [root_dir]/build
+-p, --pattern <PATTERN_DIR>
+ pattern directory, contains .meta files that are available for expansion
+ defaults to [root_dir]/pattern
+-f, --file <FILENAME>
+ builds a single file and outputs it to stdout
+-l --parallel
+ enable parallel processing for faster build times
+ interleaves output from files in verbose mode
+-v, --verbose
+ enable extra output. repeated flags give more info
+ v => list source files/directories being created
+ vv => list expansions and substitutions
+ vvv => full debug information (function calls, interior parameters)
+-q, --quiet
+ minimal output
+-o, --output <OUTPUT_FILETYPE>
+ output filetype, defaults to html
+ options:
+ - html
+ - markdown
+ - json
+ - latex
+ - man
+ - txt
+ - asciidoc
+ - pdf
+-i, --input <INPUT_FILETYPE>
+ input filetype, defaults to markdown
+ options:
+ - markdown
+ - html
+ - json
+ - latex
+ - org
+-h, --help
+ print a brief help page
+-V, --version
+ print version
+ --clean
+ clean build directory before building site,
+ will remove anything currently in build directory
+ --new
+ create a new skeleton directory in the root dir
+ --force
+ don't stop building site if a single file fails
+ --undefined
+ panics and stops building site if any undefined variables are encountered
+ --no-pandoc
+ don't call pandoc on source files
+ allows metaforge to run without pandoc installed</code></pre></article></body><foot> made with <strong>metaforge</strong> </foot></html>
\ No newline at end of file
--- /dev/null
+<!doctypehtml><html><head><title>headers</title><meta content="file headers to change behavior"name=description><meta content="huck boles"name=author></head><body><a href=../index.html>home</a><div><h1><strong>headers</strong> - <em>0.1.3</em></h1></div><p>file headers to change behavior</p><article><h2 id=header-blocks>header blocks</h2><p>define settings for the parser, allowing better control over how a single file gets processed.</p><p>header blocks works similarly as any other definition block, with keys consisting of pre-defined keywords, and values consisting of booleans (unquoted) or strings, as well as <strong><em>DEFAULT</em></strong> option for overriding.</p><p>the header block must be the first block in a file, as it determines how the parser reads and constructs the rest of the file</p><p>in a <strong>default.meta</strong> file, any keys preceded by an exclamation mark (!) get applied as header settings for the entire directory and children, following the same inheritance rules as other definitions.</p><p>prefixing a definition block with an exclamation mark makes the entire block globally defined. inside, you can mark individual assignments as local by preceding them with a star (*) as in normal definition blocks.</p><h3 id=example>example</h3><pre><code>#{
+ filetype = 'txt'
+ !pandoc = 'false'
+}</code></pre><h2 id=keywords>keywords</h2><h3 id=any>any</h3><ul><li>blank = <strong>BOOL</strong> - if true, stops parsing and returns an empty string</li><li>panic_default = <strong>BOOL</strong> - if true, panics on an undefined default pattern</li><li>panic_undefined = <strong>BOOL</strong> - if true, panics on an undefined variable or array</li><li>source = <strong>STRING</strong> - change the the filetype of the source file</li><li>filetype = <strong>STRING</strong> - change the filetype of the output file</li><li>equal_arrays = <strong>BOOL</strong> - if true, panics if arrays in the same pattern have different sizes</li><li>pandoc = <strong>BOOL</strong> - toggles if pandoc is ran on this file to convert between filetypes, defaults to <em>true</em> in <strong>source</strong> dir, and <em>false</em> in <strong>pattern</strong> dir.</li></ul><h3 id=source>source</h3><ul><li>ignore = <strong>BOOL</strong> - stops parsing and skips this file, useful for ignoring directories with scoped definitions</li><li>copy_only = <strong>BOOL</strong> - copys file or directory without processing anything</li></ul></article></body><foot> made with <strong>metaforge</strong> </foot></html>
\ No newline at end of file
--- /dev/null
+<!doctypehtml><html><head><title>structure</title><meta content="directory structure for metaforge"name=description><meta content="huck boles"name=author></head><body><a href=../index.html>home</a><div><h1><strong>structure</strong> - <em>0.1.3</em></h1></div><p>directory structure for metaforge</p><article><h2 id=file-locations>file locations</h2><p>metaforge parses files with the <strong>.meta</strong> extension.</p><p>files in the pattern directory are available for file expansion. <strong>default.meta</strong> files are fallback files if the pattern directory gets called without a defined value.</p><p>the structure of the source directory gets mirrored to the build directory as the site is build, with any <strong>.meta</strong> files becoming <strong>.html</strong> files, except <strong>default.meta</strong> files, which define default values for a directory and its children.</p><p>the source section of files in the source directory can be written in markdown and will converted to html.</p><p>files from the pattern directory the should generally contain html snippets, but can contain anything that you’d like to substitute.</p><p>required directories are: - source (site structure and contents) - pattern (patterns for expansion) - pattern/base (gets expanded to start building each pattern)</p><p>the build directory doesn’t need to exist, as metaforge will create a new one if it’s missing</p><p>a new skeleton site can be built in the given root directory by passing the <strong><em>–new</em></strong> flag to metaforge,</p><h2 id=skeleton-structure>skeleton structure</h2><pre><code>./
+L pattern/
+| L base/
+| | L default.meta
+| L body/
+| | L default.meta
+| L head/
+| | L default.meta
+| L foot/
+| L default.meta
+L source/
+| L hello_world.meta
+L build/
+ L hello_world.html</code></pre></article></body><foot> made with <strong>metaforge</strong> </foot></html>
\ No newline at end of file
--- /dev/null
+<!doctypehtml><html><head><title>syntax</title><meta content="basic syntax rules"name=description><meta content="huck boles"name=author></head><body><a href=../index.html>home</a><div><h1><strong>syntax</strong> - <em>0.1.3</em></h1></div><p>basic syntax rules</p><article><h2 id=sigils>sigils</h2><ul><li>$ variables</li><li>@ arrays</li><li>& patterns</li><li># settings</li><li>- comments</li></ul><h2 id=definition-block>definition block</h2><p>a sigil followed by assignment operations enclosed by brackets</p><h3 id=examples>examples</h3><pre><code>${ foo = 'bar' }
+
+&{
+ foo.bar = "baz"
+ bar.baz = 'foo'
+}</code></pre><h2 id=strings>strings</h2><p>double or single quoted strings, double quoted strings require escaping control characters, and single quoted strings get copied as is. single quoted strings can stretch across newlines.</p><h3 id=examples-1>examples</h3><pre><code>"foo bar baz\n"
+
+'foo
+bar
+baz'</code></pre><h2 id=arrays>arrays</h2><p>a list of strings, separated by commas, enclosed by brackets. whitespace and newlines between list values are accepted</p><h3 id=examples-2>examples</h3><pre><code>[ 'foo', 'bar', 'baz', 'quux' ]
+
+["foo","bar","baz"]
+
+[
+ 'foo',
+ 'bar',
+ 'baz'
+]</code></pre><h2 id=comments>comments</h2><p>a comment sigil (-) followed by a comment in braces. the only characters not allowed are braces.</p><p>comments get removed during the first pass through of parsing, and can occur anywhere in or across a line.</p><h3 id=examples-3>examples</h3><pre><code>-{ foobar }
+
+-{
+ foobar
+ foobaz }</code></pre><h2 id=layout>layout</h2><ul><li>optional header definition block</li><li>optional variable, array, pattern definition blocks</li><li>source</li></ul><h3 id=example>example</h3><pre><code>#{ foo = 'bar' } -{ settings for parsing file }
+
+${
+ foo = 'foobar'
+ bar.foo = 'foobaz'
+}
+
+@{
+ foo = ['foobar','foobaz']
+ foo.bar.baz = [ 'foobar', 'foobaz', 'barbaz' ]
+}
+
+&{
+ foo.bar = 'foobar'
+ bar = "foo_bar"
+}
+
+# FOOBAR
+Foo bar baz quux lorem ipsum...</code></pre></article></body><foot> made with <strong>metaforge</strong> </foot></html>
\ No newline at end of file
--- /dev/null
+<!doctypehtml><html><head><title>metaforge documentation</title><meta name=description><meta content="huck boles"name=author></head><body><a href=./index.html>home</a><div><h1><strong>metaforge documentation</strong> - <em>0.1.3</em></h1></div><p></p><article><p>this is the documentation for metaforge, generated by metaforge itself.</p><p>currently it’s unstyled html rendered by your browser, so it’s pretty bare-bones.</p><p>open <strong>files/README</strong> in metaforge’s repository and explore the source and pattern files to get some examples of how this site works.</p><p>you can change anything in the <strong>README</strong> directory and see how it affects the site once you rebuild it.</p><h2 id=contents>contents</h2><ul><li><a href=docs/syntax.html>syntax</a></li><li><a href=docs/definitions.html>definitions</a></li><li><a href=docs/expansions.html>expansions</a></li><li><a href=docs/structure.html>structure</a></li><li><a href=docs/header.html>headers</a></li><li><a href=docs/flags.html>flags</a></li></ul><h2 id=new-in-this-version>new in this version</h2><ul><li>spaces are correctly preserved between directly adjacent substitutions</li><li>copy_only header directive</li><li>pandoc header now works on pattern files</li></ul><h2 id=versions>versions</h2><ul><li>0.1.3: grammar update, new header directives</li><li>0.1.2: multithreading</li><li>0.1.1: initial release</li></ul></article></body><foot> made with <strong>metaforge</strong> </foot></html>
\ No newline at end of file
goes through an extra step right before insertion, calling pandoc on the file
to convert between the chosen filetypes.
+***SOURCE*** can also be used as a standin for the source directory while writing expansions,
+allowing patterns to call the same source file every time, or source files to expand other
+source files.
+
+### example
+ ...lorem &{SOURCE.foo.bar} ipsum dolor...
+
once the filename is determined, it is parsed and expands any contained variables,
arrays and patterns. if it is a ***SOURCE*** pattern, it is converted to html after
the expansions. the expanded pattern is then inserted in place of the calling identifier.
## building
-as each file is built, the first thing expanded is the relevant **base/[FILE].meta** pattern,
-so it is required to have at least a **default.meta** in the **pattern/base** directory
+as each source file is built, the first thing expanded is the defined or default
+**[SOURCE]/base/[FILE].meta** pattern, so it is required to have at least a **default.meta**
+in the **pattern/base** directory
### example
--undefined
panics and stops building site if any undefined variables are encountered
--no-pandoc
- don't call pandoc on source files
- allows metaforge to run without pandoc installed
+ don't call pandoc on source files. allows metaforge to run without pandoc installed
+ --no-minify
+ don't minify resulting html
- source = **STRING** - change the the filetype of the source file
- filetype = **STRING** - change the filetype of the output file
- equal_arrays = **BOOL** - if true, panics if arrays in the same pattern have different sizes
-- pandoc = **BOOL** - toggles if pandoc is ran on this file to convert between filetypes, defaults to *true* in **source** dir, and *false* in **pattern** dir.
- minify = **BOOL** - toggles html minification
+- pandoc = **BOOL** - toggles if pandoc is ran on this file to convert between filetypes, defaults to *true* in **source** dir, and *false* in **pattern** dir.
### source
foobaz }
## layout
-- optional header definition block
-- optional variable, array, pattern definition blocks
+
+*all sections are optional*
+
+- header definition block
+- variable, array, pattern definition blocks
- source
### example
currently it's unstyled html rendered by your browser, so it's pretty bare-bones.
-open **files/README** in metaforge's repository and explore the source and pattern
+open **docs/source** in metaforge's repository and explore the source and pattern
files to get some examples of how this site works.
-you can change anything in the **README** directory and see how it affects the site once
+you can change anything in the **docs** directory and see how it affects the site once
you rebuild it.
## contents
## new in this version
- spaces are correctly preserved between directly adjacent substitutions
+- include from source dir
- copy_only header directive
- pandoc header now works on pattern files
-- html minification
+- html minification header and flags
## versions
-- 0.1.3: grammar update, new header directives
+- 0.1.3: grammar and headers
- 0.1.2: multithreading
- 0.1.1: initial release
#[test]
#[ignore = "generates README site"]
fn readme() -> Result<()> {
- let dir = std::path::PathBuf::from("files/README")
+ let dir = std::path::PathBuf::from("docs")
.canonicalize()
.unwrap();
home / repos / metaforge.git / commitdiff