From 1338cdb1b7ec222f43ab948e77f8d20ecb33721e Mon Sep 17 00:00:00 2001 From: Huck Boles Date: Fri, 2 Jun 2023 18:45:35 -0500 Subject: [PATCH] moved: README to docs dir --- docs/build/docs/definitions.html | 25 ++++++++ docs/build/docs/expansions.html | 28 +++++++++ docs/build/docs/flags.html | 59 +++++++++++++++++++ docs/build/docs/header.html | 4 ++ docs/build/docs/structure.html | 14 +++++ docs/build/docs/syntax.html | 40 +++++++++++++ docs/build/index.html | 1 + .../README => docs}/pattern/base/default.meta | 0 .../README => docs}/pattern/body/default.meta | 0 .../README => docs}/pattern/foot/default.meta | 0 .../README => docs}/pattern/head/default.meta | 0 {files/README => docs}/source/default.meta | 0 .../README => docs}/source/docs/default.meta | 0 .../source/docs/definitions.meta | 0 .../source/docs/expansions.meta | 12 +++- {files/README => docs}/source/docs/flags.meta | 5 +- .../README => docs}/source/docs/header.meta | 2 +- .../source/docs/structure.meta | 0 .../README => docs}/source/docs/syntax.meta | 7 ++- {files/README => docs}/source/index.meta | 9 +-- tests/readme.rs | 2 +- 21 files changed, 196 insertions(+), 12 deletions(-) create mode 100644 docs/build/docs/definitions.html create mode 100644 docs/build/docs/expansions.html create mode 100644 docs/build/docs/flags.html create mode 100644 docs/build/docs/header.html create mode 100644 docs/build/docs/structure.html create mode 100644 docs/build/docs/syntax.html create mode 100644 docs/build/index.html rename {files/README => docs}/pattern/base/default.meta (100%) rename {files/README => docs}/pattern/body/default.meta (100%) rename {files/README => docs}/pattern/foot/default.meta (100%) rename {files/README => docs}/pattern/head/default.meta (100%) rename {files/README => docs}/source/default.meta (100%) rename {files/README => docs}/source/docs/default.meta (100%) rename {files/README => docs}/source/docs/definitions.meta (100%) rename {files/README => docs}/source/docs/expansions.meta (87%) rename {files/README => docs}/source/docs/flags.meta (93%) rename {files/README => docs}/source/docs/header.meta (100%) rename {files/README => docs}/source/docs/structure.meta (100%) rename {files/README => docs}/source/docs/syntax.meta (93%) rename {files/README => docs}/source/index.meta (73%) diff --git a/docs/build/docs/definitions.html b/docs/build/docs/definitions.html new file mode 100644 index 0000000..107e42b --- /dev/null +++ b/docs/build/docs/definitions.html @@ -0,0 +1,25 @@ +definitionshome

definitions - 0.1.3

definining variables and patterns

rules

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).

a block consists of a sigil for the definition type, followed by braces that surround assignment statements.

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 and underscores [a-zA-Z0-9_], 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 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. 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. 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 (!).

values

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.

patterns can also be assigned as DEFAULT, for overriding globally defined patterns.

scope

any value defined in a file called default.meta in the source 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 value normally.

examples

${ 
+   *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 }
+}
made with metaforge \ No newline at end of file diff --git a/docs/build/docs/expansions.html b/docs/build/docs/expansions.html new file mode 100644 index 0000000..a2bb9a7 --- /dev/null +++ b/docs/build/docs/expansions.html @@ -0,0 +1,28 @@ +expansionshome

expansions - 0.1.3

expanding variables and patterns in a file

syntax

a sigil followed by braces, with an identifier inside.

happens inside the source, expanding to the relevant value when the file is built

examples

...this is a string with a ${variable} to be expanded...
+
+...this line has a &{pattern} inside of it...
+
+...this @{array} will be replaced...

behavior

all expansions are decided by the value defined for the identifier, following inheritance rules, and directory masking for variables and arrays.

variables

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.

example

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>

arrays

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.

example

pattern [foo]: <p>@{bar}</p>
+
+defintion: @{  foo.bar = ['foo', 'bar', 'baz'] }
+
+expands to: <p>foo</p><p>bar</p><p>baz</p>

it’s generally best to keep arrays inside small self-contained patterns, otherwise unwanted parts of the file may be duplicated.

patterns

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 .meta 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 DEFAULT, then default.meta is selected from the identified directory.

foo.bar => pattern/foo/bar/*.meta => pattern/foo/bar.meta => pattern/foo/bar/default.meta

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 BLANK will always expand to a blank string without errors.

if the identifier in the pattern is SOURCE, 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.

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

example

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>
made with metaforge \ No newline at end of file diff --git a/docs/build/docs/flags.html b/docs/build/docs/flags.html new file mode 100644 index 0000000..c4b5f60 --- /dev/null +++ b/docs/build/docs/flags.html @@ -0,0 +1,59 @@ +flagshome

flags - 0.1.3

available flags for running metaforge

available flags

-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
made with metaforge \ No newline at end of file diff --git a/docs/build/docs/header.html b/docs/build/docs/header.html new file mode 100644 index 0000000..7b65386 --- /dev/null +++ b/docs/build/docs/header.html @@ -0,0 +1,4 @@ +headershome

headers - 0.1.3

file headers to change behavior

header blocks

define settings for the parser, allowing better control over how a single file gets processed.

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 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 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 normal definition blocks.

example

#{ 
+   filetype = 'txt'
+   !pandoc = 'false'
+}

keywords

any

source

made with metaforge \ No newline at end of file diff --git a/docs/build/docs/structure.html b/docs/build/docs/structure.html new file mode 100644 index 0000000..9c7f9e5 --- /dev/null +++ b/docs/build/docs/structure.html @@ -0,0 +1,14 @@ +structurehome

structure - 0.1.3

directory structure for metaforge

file locations

metaforge parses files with the .meta extension.

files in the pattern directory are available for file expansion. default.meta files are fallback files if the pattern directory gets called without a defined value.

the structure of the source directory gets mirrored to the build directory as the site is build, with any .meta files becoming .html files, except default.meta files, which define default values for a directory and its children.

the source section of files in the source directory can be written in markdown and will converted to html.

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)

the build directory doesn’t need to exist, as metaforge will create a new one if it’s missing

a new skeleton site can be built in the given root directory by passing the –new flag to metaforge,

skeleton structure

./
+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
made with metaforge \ No newline at end of file diff --git a/docs/build/docs/syntax.html b/docs/build/docs/syntax.html new file mode 100644 index 0000000..16b757a --- /dev/null +++ b/docs/build/docs/syntax.html @@ -0,0 +1,40 @@ +syntaxhome

syntax - 0.1.3

basic syntax rules

sigils

definition block

a sigil followed by assignment operations enclosed by brackets

examples

${  foo = 'bar' }
+
+&{ 
+   foo.bar = "baz"
+   bar.baz = 'foo'
+}

strings

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.

examples

"foo bar baz\n"
+
+'foo
+bar
+baz'

arrays

a list of strings, separated by commas, enclosed by brackets. whitespace and newlines between list values are accepted

examples

[ 'foo', 'bar', 'baz', 'quux' ]
+
+["foo","bar","baz"]
+
+[
+    'foo',
+    'bar',
+    'baz'
+]

comments

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 anywhere in or across a line.

examples

-{  foobar }
+
+-{ 
+   foobar
+   foobaz }

layout

example

#{  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...
made with metaforge \ No newline at end of file diff --git a/docs/build/index.html b/docs/build/index.html new file mode 100644 index 0000000..b7c9631 --- /dev/null +++ b/docs/build/index.html @@ -0,0 +1 @@ +metaforge documentationhome

metaforge documentation - 0.1.3

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.

open files/README 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 rebuild it.

contents

new in this version

versions

made with metaforge \ No newline at end of file diff --git a/files/README/pattern/base/default.meta b/docs/pattern/base/default.meta similarity index 100% rename from files/README/pattern/base/default.meta rename to docs/pattern/base/default.meta diff --git a/files/README/pattern/body/default.meta b/docs/pattern/body/default.meta similarity index 100% rename from files/README/pattern/body/default.meta rename to docs/pattern/body/default.meta diff --git a/files/README/pattern/foot/default.meta b/docs/pattern/foot/default.meta similarity index 100% rename from files/README/pattern/foot/default.meta rename to docs/pattern/foot/default.meta diff --git a/files/README/pattern/head/default.meta b/docs/pattern/head/default.meta similarity index 100% rename from files/README/pattern/head/default.meta rename to docs/pattern/head/default.meta diff --git a/files/README/source/default.meta b/docs/source/default.meta similarity index 100% rename from files/README/source/default.meta rename to docs/source/default.meta diff --git a/files/README/source/docs/default.meta b/docs/source/docs/default.meta similarity index 100% rename from files/README/source/docs/default.meta rename to docs/source/docs/default.meta diff --git a/files/README/source/docs/definitions.meta b/docs/source/docs/definitions.meta similarity index 100% rename from files/README/source/docs/definitions.meta rename to docs/source/docs/definitions.meta diff --git a/files/README/source/docs/expansions.meta b/docs/source/docs/expansions.meta similarity index 87% rename from files/README/source/docs/expansions.meta rename to docs/source/docs/expansions.meta index f3d9212..165ebf9 100644 --- a/files/README/source/docs/expansions.meta +++ b/docs/source/docs/expansions.meta @@ -89,14 +89,22 @@ 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. +***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 diff --git a/files/README/source/docs/flags.meta b/docs/source/docs/flags.meta similarity index 93% rename from files/README/source/docs/flags.meta rename to docs/source/docs/flags.meta index 4a00fbf..e5fa294 100644 --- a/files/README/source/docs/flags.meta +++ b/docs/source/docs/flags.meta @@ -62,5 +62,6 @@ ${ --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 diff --git a/files/README/source/docs/header.meta b/docs/source/docs/header.meta similarity index 100% rename from files/README/source/docs/header.meta rename to docs/source/docs/header.meta index 1bda89c..60900a7 100644 --- a/files/README/source/docs/header.meta +++ b/docs/source/docs/header.meta @@ -40,8 +40,8 @@ normal definition blocks. - 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 diff --git a/files/README/source/docs/structure.meta b/docs/source/docs/structure.meta similarity index 100% rename from files/README/source/docs/structure.meta rename to docs/source/docs/structure.meta diff --git a/files/README/source/docs/syntax.meta b/docs/source/docs/syntax.meta similarity index 93% rename from files/README/source/docs/syntax.meta rename to docs/source/docs/syntax.meta index 72deca7..1f55255 100644 --- a/files/README/source/docs/syntax.meta +++ b/docs/source/docs/syntax.meta @@ -63,8 +63,11 @@ anywhere in or across a line. 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 diff --git a/files/README/source/index.meta b/docs/source/index.meta similarity index 73% rename from files/README/source/index.meta rename to docs/source/index.meta index fb8a466..2c13574 100644 --- a/files/README/source/index.meta +++ b/docs/source/index.meta @@ -6,10 +6,10 @@ 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. -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 @@ -24,11 +24,12 @@ you rebuild it. ## 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 diff --git a/tests/readme.rs b/tests/readme.rs index 01279d7..543bf2e 100644 --- a/tests/readme.rs +++ b/tests/readme.rs @@ -3,7 +3,7 @@ use eyre::Result; #[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(); -- 2.45.2