&{SOURCE} diff --git a/files/README/source/docs/default.meta b/files/README/source/docs/default.meta index f076710..8103058 100644 --- a/files/README/source/docs/default.meta +++ b/files/README/source/docs/default.meta @@ -1,7 +1,10 @@ ${ - 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 = '-{ ' } diff --git a/files/README/source/docs/definitions.meta b/files/README/source/docs/definitions.meta index 99259a9..ff507c2 100644 --- a/files/README/source/docs/definitions.meta +++ b/files/README/source/docs/definitions.meta @@ -1,6 +1,7 @@ ${ title = 'definitions' description = 'definining variables and patterns' + arr_sub = '@{' } ## rules @@ -11,25 +12,26 @@ text, and after any header settings (which are a special type of definition bloc 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. @@ -41,9 +43,9 @@ assignment in a local block can be made global again by prefixing it with an exc 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 @@ -52,33 +54,33 @@ directory is defined in all files in the current and child directories. 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 } } diff --git a/files/README/source/docs/expansions.meta b/files/README/source/docs/expansions.meta index 5b38ce5..6060114 100644 --- a/files/README/source/docs/expansions.meta +++ b/files/README/source/docs/expansions.meta @@ -1,6 +1,9 @@ ${ title = 'expansions' description = 'expanding variables and patterns in a file' + var_sub = '${' + arr_sub = '@{' + pat_sub = '&{' } ## syntax @@ -12,11 +15,11 @@ when the file is built ### 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 @@ -33,9 +36,9 @@ don't need any extra expansion. definition: ${var} - baz = "foo" - bar.baz = "quux" - quux = BLANK + baz = "foo" + bar.baz = "quux" + quux = BLANK } pattern [foo]:

${var}baz} ${var}quux}

@@ -55,7 +58,7 @@ parts of patterns. #### example - pattern [foo]:

${arr}bar}

+ pattern [foo]:

${arr_sub}bar}

defintion: ${arr} foo.bar = ['foo', 'bar', 'baz'] } @@ -97,9 +100,9 @@ so it is required to have at least a **default.meta** in the **pattern/base** di ### example - pattern [base]: ${pat}body} + pattern [base]: ${pat_sub}body} - pattern [body]: ${pat}SOURCE} + pattern [body]: ${pat_sub}SOURCE} source [SOURCE]: foo *bar* baz diff --git a/files/README/source/docs/header.meta b/files/README/source/docs/header.meta index 8213b6e..88a5351 100644 --- a/files/README/source/docs/header.meta +++ b/files/README/source/docs/header.meta @@ -9,14 +9,15 @@ define settings for the parser, allowing better control over how a single file g 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 @@ -25,22 +26,22 @@ normal definition blocks. ### 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 diff --git a/files/README/source/docs/structure.meta b/files/README/source/docs/structure.meta index a977057..b8c51dc 100644 --- a/files/README/source/docs/structure.meta +++ b/files/README/source/docs/structure.meta @@ -1,3 +1,8 @@ +${ + title = 'structure' + description = 'directory structure for metaforge' +} + ## file locations metaforge parses files with the **.meta** extension. @@ -17,9 +22,9 @@ files from the pattern directory the should generally contain html snippets, 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 diff --git a/files/README/source/docs/syntax.meta b/files/README/source/docs/syntax.meta index 56ff417..f8ae0b7 100644 --- a/files/README/source/docs/syntax.meta +++ b/files/README/source/docs/syntax.meta @@ -17,8 +17,8 @@ a sigil followed by assignment operations enclosed by brackets ${var} foo = 'bar' } ${pat} - foo.bar = "baz" - bar.baz = 'foo' + foo.bar = "baz" + bar.baz = 'foo' } ## strings @@ -49,7 +49,7 @@ whitespace and newlines between list values are accepted ] ## 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 @@ -59,9 +59,8 @@ anywhere in or across a line. ${com} foobar } ${com} - foobar - foobaz - } + foobar + foobaz } ## layout - optional header definition block @@ -72,18 +71,18 @@ anywhere in or across a line. ${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 diff --git a/files/README/source/index.meta b/files/README/source/index.meta index 327b995..079d07b 100644 --- a/files/README/source/index.meta +++ b/files/README/source/index.meta @@ -4,16 +4,22 @@ ${ 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 diff --git a/tests/readme.rs b/tests/readme.rs new file mode 100644 index 0000000..a64228a --- /dev/null +++ b/tests/readme.rs @@ -0,0 +1,18 @@ +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) +}

${title}

${title} - ${version}