+metaforge - v0.1.1
+
+a pattern driven static site generator for extensible snippet insertion.
+
+the full documentation is available in this repository under the **files/README/source/docs**
+directory. it's currently setup as a working example of a metaforge site, so you can poke around
+and see one way a site can be setup.
+
+building documentation:
+ $ cargo test -- --ignored readme
+
+this command can be run as many times as needed to regenerate the documentation, and is
+reccomended after upgrading to a new version to see what's changed.
<body>
- <a href="../index.html">home</a>
- <h1>${title}</h1>
+ <a href="${home}">home</a>
+ <div><h1><strong>${title}</strong> - <em>${version}</em></h1></div>
<p>${description}</p>
<article>
&{SOURCE}
${
- var = '${'
- arr = '@{'
- pat = '&{'
- head = '#{'
- com = '-{'
+ -{ index is a folder up in this directory }
+ home = '../index.html'
+ -{ using substitutions for example code so it doesn't mess up parsing }
+ var = '${ '
+ arr = '@{ '
+ pat = '&{ '
+ head = '#{ '
+ com = '-{ '
}
${
title = 'definitions'
description = 'definining variables and patterns'
+ arr_sub = '@{'
}
## rules
a block is a sigil for the definition type, followed by braces that
surround assignment statements
-assignments are identifiers, followed by an equals sign, then a value
+assignments are identifiers, followed by an equals sign (=), then a value
definition blocks can have spaces and new lines arbitrarily inserted
between each component, and support multiple assignments per block
## identifiers
-identifiers can contain alphanumeric ascii values as well as _ and separating dots .
+identifiers can contain alphanumeric ascii values and _ as well as separating dots (.)
variable identifiers without dots are available to any pattern called by the file
array identifiers without dots are available only to the pattern they are defined in
variable and array identifiers with separating dots use the final item
-as the variable, 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.
+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.
-pattern identifiers expand to a directory of files in the pattern
-directory by replacing .'s with /'s, appending necessary file extensions when called.
+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.
an identifier preceded by an star (*) will be marked as local to the file it is defined in.
values can be a double or single quoted string, if defining an array,
a value is a bracket surrounded, comma separated list of strings
-all values can optionally be assigned as BLANK, which expands to nothing
+all values can optionally be assigned as ***BLANK***, which expands to nothing
-patterns can also be assigned as DEFAULT, for overriding globally defined patterns.
+patterns can also be assigned as ***DEFAULT***, for overriding globally defined patterns.
## scope
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
+definition with a star (*), or for any files further down the chain, by defining a new
value normally.
## examples
${var}
- *foo = 'bar' ${com} foo is only equal to bar in this file }
- bar.baz = BLANK ${com} this only applies to pattern/bar/*.meta }
- baz = quux ${com} baz is equal to quux in every file called during
- expansion, unless it gets overridden }
+ *foo = 'bar' ${com} foo is only equal to bar in this file }
+ bar.baz = BLANK ${com} this only applies to pattern/bar/*.meta }
+ baz = quux ${com} baz is equal to quux in every file called during
+ expansion, unless it gets overridden }
}
${arr}
- bar = ['foo','bar']
- baz.blank = BLANK ${com} this inserts nothing }
+ bar = ['foo','bar']
+ baz.blank = BLANK ${com} this inserts nothing }
- foo.bar = [ 'foobar', 'foobaz' ]
- ${com} this will copy pattern/foo/*.meta twice, inserting 'foobar and 'foobaz'
- once each at the location of @{bar} }
+ foo.bar = [ 'foobar', 'foobaz' ]
+ ${com} this will copy pattern/foo/*.meta twice, inserting 'foobar and 'foobaz'
+ once each at the location of ${arr_sub}bar} }
}
${com} all of these patterns are only defined for this file }
*${pat}
- foo.bar = BLANK
- bar.default = DEFAULT
+ foo.bar = BLANK
+ bar.default = DEFAULT
- !baz = "bar"
- ${com} except for this definition, which
- continues down the expansion chain }
+ !baz = "bar"
+ ${com} except for this definition, which
+ continues down the expansion chain }
}
${
title = 'expansions'
description = 'expanding variables and patterns in a file'
+ var_sub = '${'
+ arr_sub = '@{'
+ pat_sub = '&{'
}
## syntax
### examples
- ...this is a string with a ${var}variable} to be expanded...
+ ...this is a string with a ${var_sub}variable} to be expanded...
- ...this line has a ${pat}pattern} inside of it...
+ ...this line has a ${pat_sub}pattern} inside of it...
- ...this ${arr}array} will be replaced...
+ ...this ${arr_sub}array} will be replaced...
## behavior
definition:
${var}
- baz = "foo"
- bar.baz = "quux"
- quux = BLANK
+ baz = "foo"
+ bar.baz = "quux"
+ quux = BLANK
}
pattern [foo]: <p>${var}baz} ${var}quux}</p>
#### example
- pattern [foo]: <p>${arr}bar}</p>
+ pattern [foo]: <p>${arr_sub}bar}</p>
defintion: ${arr} foo.bar = ['foo', 'bar', 'baz'] }
### example
- pattern [base]: <html>${pat}body}</html>
+ pattern [base]: <html>${pat_sub}body}</html>
- pattern [body]: <body>${pat}SOURCE}</body>
+ pattern [body]: <body>${pat_sub}SOURCE}</body>
source [SOURCE]: foo *bar* baz
processed.
header blocks works similarly as any other definition block, with keys consisting
-of pre-defined keywords, and values are booleans (unquoted) or strings, and the ***DEFAULT***
-option for overriding.
+of pre-defined keywords, and values consisting of booleans (unquoted) or strings,
+as well as ***DEFAULT*** option for overriding.
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
in a **default.meta** file, any keys preceded by an exclamation mark (!) get applied
-as global header settings, following the same inheritance rules as other global definitions.
+as header settings for the entire directory and children, following the same inheritance
+rules as other definitions.
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
### example
${head}
- filetype = 'txt'
- !pandoc = 'false'
+ filetype = 'txt'
+ !pandoc = 'false'
}
## keywords
### any
-- blank = BOOL - stops parsing and returns an empty string
-- panic_default = BOOL - if true, panics on an undefined default pattern
-- panic_undefined = BOOL - if true, panics on an undefined variable or array
-- equal_arrays = BOOL - if true, panics if arrays in the same pattern have different sizes
+- blank = **BOOL** - if true, stops parsing and returns an empty string
+- panic_default = **BOOL** - if true, panics on an undefined default pattern
+- panic_undefined = **BOOL** - if true, panics on an undefined variable or array
+- equal_arrays = **BOOL** - if true, panics if arrays in the same pattern have different sizes
### source
-- ignore = BOOL - stops parsing and skips this file, useful for ignoring directories with scoped definitions
-- filetype = STRING - change the filetype of the output file
-- source = STRING - change the the filetype of the source file
-- pandoc = BOOL - toggles if pandoc is ran on this file to convert between filetypes
+- ignore = **BOOL** - stops parsing and skips this file, useful for ignoring directories with scoped definitions
+- source = **STRING** - change the the filetype of the source file
+- filetype = **STRING** - change the filetype of the output file
+- pandoc = **BOOL** - toggles if pandoc is ran on this file to convert between filetypes
+${
+ title = 'structure'
+ description = 'directory structure for metaforge'
+}
+
## file locations
metaforge parses files with the **.meta** extension.
but can contain anything that you'd like to substitute.
required directories are:
-- source - site structure and contents
-- pattern - patterns for expansion
-- pattern/base - gets expanded to start building each pattern.
+- source (site structure and contents)
+- pattern (patterns for expansion)
+- pattern/base (gets expanded to start building each pattern)
the build directory doesn't need to exist, as metaforge will create a
new one if it's missing
${var} foo = 'bar' }
${pat}
- foo.bar = "baz"
- bar.baz = 'foo'
+ foo.bar = "baz"
+ bar.baz = 'foo'
}
## strings
]
## comments
-a comment sigil \- followed by a comment in braces
+a comment sigil \- followed by a comment in braces.
the only characters not allowed are braces.
comments get removed during the first pass through of parsing, and can occur
${com} foobar }
${com}
- foobar
- foobaz
- }
+ foobar
+ foobaz }
## layout
- optional header definition block
${head} foo = 'bar' } ${com} settings for parsing file }
${var}
- foo = 'foobar'
- bar.foo = 'foobaz'
+ foo = 'foobar'
+ bar.foo = 'foobaz'
}
${arr}
- foo = ['foobar','foobaz']
- foo.bar.baz = [ 'foobar', 'foobaz', 'barbaz' ]
+ foo = ['foobar','foobaz']
+ foo.bar.baz = [ 'foobar', 'foobaz', 'barbaz' ]
}
${pat}
- foo.bar = 'foobar'
- bar = "foo_bar"
+ foo.bar = 'foobar'
+ bar = "foo_bar"
}
# FOOBAR
this is the documentation for metaforge, generated by metaforge itself.
-currently it's unstyled html rendered by your browser, so it's pretty bare-bones right now, but
+currently it's unstyled html rendered by your browser, so it's pretty bare-bones, but
you can change that easily.
-open **files/README** in metaforge's repository, and explore the source and pattern
-files to get a glimpse into a working project.
+open **files/README** in metaforge's repository and explore the source and pattern
+files to get some examples.
+
+you can change anything in the **README** directory and see how it affects the site once
+you rebuild it.
## contents
- [syntax](docs/syntax.html)
- [definitions](docs/definitions.html)
- [expansions](docs/expansions.html)
- [structure](docs/structure.html)
-- [headers](docs/headers.html)
+- [headers](docs/header.html)
- [flags](docs/flags.html)
+
+## versions
+- 0.1.1: initial release
--- /dev/null
+use eyre::Result;
+
+#[test]
+#[ignore = "generates README site"]
+fn readme() -> Result<()> {
+ let dir = std::path::PathBuf::from("files/README")
+ .canonicalize()
+ .unwrap();
+
+ let mut opts = metaforge::Options::new();
+ opts.root = dir.clone();
+ opts.source = dir.join("source");
+ opts.build = dir.join("build");
+ opts.pattern = dir.join("pattern");
+ opts.clean = true;
+
+ metaforge::build_site(&opts)
+}
home / repos / metaforge.git / commitdiff