Syntax Overview

The language has a set number of object types, and each object can have a predetermined number of string parameters. Declaring an object starts by naming the object beginning with the @ symbol, followed by the string parameters which are started and ended with the " symbol, and separated by white space. Multiline string parameters can be used by placing """ on its own line at the beginning and end of the string. If you are adding children to an object that allows children, you close the object with the @end object. Every token is whitespace delimited, so indentation is unneccesary, but I use it heavily as a convention for readability.

Data Structures

For data, you can define:

• @string : a block of text with a name
• @map : an object containing @group , @value , or @list children
  • @group : an object that adds a @map to a queryable group
  • @value : exactly the same as a @string, but as a @map child
• @list : an object containing @map or @query children
  • @query : an object containing query commands that resolve to a @list

Here is what defining these data structures look like in collect:

							@string "name" "jakintosh"
				
@string "multiline-string"
	"""
	This is an example
	of a multiline string.
	"""
				
@map "my-cat"
	@value "name" "mochi"
	@value "color" "grey"
	@list "favorite-toys"
		@item "rainbow-toy"
		@item "raccoon-toy"
	@end
@end
				
@map "rainbow-toy"
	@group "catnip" "1"
	@value "name" "rainbow"
	@value "color" "rainbow"
@end
				
@map "raccoon-toy"
	@value "name" "bean paste"
	@value "color" "grey"
@end
				
@list "catnip-toys"
	@query
		@include "catnip"
	@end
@end
						

You'll notice how the @query object uses the names defined by the @group objects inside a @map. All @groups objects added to a @map must also have a unique integer ID that is used for sorting. There is a special @date object that allows a date to be added to a @map, which can also be used for sorting. Queries also have matching commands such as @exclude and @filter, as well as ordering commands like @reverse, @take, and @sort-by-date.

Logic Objects

For logic, there are two primary objects: @scope, which establishes a local context for object names and execution, and @switch, which provides for conditional logic.

Here's an example of what this can look like in practice:

							@string "blog-byline"
	"""
	x-byline: $exec($(this.author))(author-handle-renderer) | $(date)
	"""
				
@scope "blog-post-stub-renderer"
				
	@switch "spacing"
		@has-obj "iter.next" "\n"
		@default ""
				
	@render
		"""
		section:(class="blog stub") {$(this.title)}(a|href="./blog-post-$(this.slug).html")
			$>(blog-byline)$(spacing)
		"""
				
@end
						

Here, we first define a @string named "blog-byline" to use in the broader context, and then we create a new @scope for rendering a blog post stub. Inside that @scope, we define a @switch named "spacing", with two conditions: if it has an object (@has-obj) in the context at 'iter.next', it renders to "n", otherwise it is blank. Finally, we define a @render object, which can be thought of as the return value of the @scope. Whenever you try to render a scope, the string that it returns is whatever the @render object resolves to.

Text Rendering

The last major thing to know is that inside any of the string parameters in a collect tree, you can render values from the tree itself by using the $() syntax and placing the named path of the value you want to render between the parenthesis. You can see this above when we render $(this.title) inside the @render object.

There are also a few special forms of the $() syntax. The $>() form will maintain the current indentation on newlines in the rendered text. The $exec()() form takes two parameters, the name of a @map and the name of a @scope, then passes that @map into the @scope and executes its @render object. Finally, the $iter()() works the same as @exec()() except it passes in a @list to the @scope. The active @map during an execution of a @scope can be accessed using the 'this' object, and the entire @list can be accessed via the 'iter' object, and navigated with chains of '.prev' and '.next' specifiers.

Further Reading

At some point, I will write up a more complete and easily digestable guide to the language. In the meantime, you can explore its source code and some real examples of how it is used below. To give you an idea of its capability, this entire site was built by hand in plain text using collect.

• collect source code
• this site as collect
• this page as collect