File Content Syntax

Note

For usage examples see at Examples

Convertly recognizes three kinds of configuration files, identified by their extension, see for more details Files Types:

Extension	File	Role
icf	ICF — Input Configuration	Describes how to parse an input file
ocf	OCF — Output Configuration	Describes how to write an output file
vcf	VCF — Visual Configuration	Describes how to render a visualization

Note

This page covers the grammar shared by all three file types (Common), followed by the specific grammar of ICF and OCF. VCF is not documented yet.

Table of Contents

Section	Content
Common	Grammar and rules shared by ICF, OCF and VCF
ICF — Input Configuration	Import, Header, Variables, Parsing
OCF — Output Configuration	Header, Format, Writing-Header, Writing-Content
VCF — Visual Configuration	Not yet documented

Common

Other

The event variable, its fields, and its built-in methods are shared across all file types that use a code sub-section (see Parsing below). They are already fully documented on the Tokens page and are not repeated here to avoid duplication.

Note

If a standalone copy of the event reference is needed on this page instead of a link, let me know and I'll duplicate it here.

Caution

The different section order such has [HEADER] or [WRITING-CONTENT] are defined independently for each different file

Reserved

The following identifiers are reserved and cannot be redeclared as regular variables.

Name	Reserved For
file, type, extension / ext, separated / sep, using, indent_size	Header configuration fields
entry	Entry point of parsing
event	The variable passed into code sub-sections
i	Loop counter variable inside code sub-sections
magic, content	Header signature bytes & content body (see Writing Header)

Syntax

The rules below define the grammar used across the file content sections, following the notation from Syntax Definition.

Primitives

<none>    = none
<hex>     = 0x(0-7)+
<bin>     = 0b(0-1)+
<size_t>  = (0-9)+
<integer> = [-](0-9)+
<space>   = a space literally
<char>    = '.'
<string>  = ".*"
<regex>   = <string>
<boolean> = (true|t|1)|(false|f|0)

File Descriptors

<ext>       = icf|ocf|vcf
<path>      = <string>.<ext>
<file>      = (binary|b|0)|(textual|t|1)|(language|l|2)
<file_type> = (visual)|(input|stdin|1)|(output|stdout|0)

Variables & Scope

<var_type>    = (value|v)|(none)|<var_now>
<var_now>     = variables in the same section
<var_prev>    = variables in previous section
<var:SECTION> = variables in the given SECTION
<var>         = <var_now>|<var_prev>

event Methods (cross-reference, see Tokens)

<methods>         = see Tokens page, "Methods" section
<special_methods> = see Tokens page, "Special Methods" sub-section

Conditions & Instructions

<logical_operators>  = (&&)|(||)
<logical_comparator> = <|<=|>|>=|==|!=

<value2>      = <integer>|<special_methods>
<comparaison> = <value2> <logical_comparator> <value2>
<value1>      = <boolean>|<methods>|<comparaison>
<condition>   = <value1> (<logical_operators> <value1>)*
 
<loop>   = for (<condition>) {<instructions>}
<branch> = if (<condition>) {<instructions>}
 
<instruction>  = <branch>|<loop>|(ret <boolean>)
<instructions> = <instruction>*

Writing Parameters & Content

<parameter>     = (no-nl)|(indent:<size_t>)
<parameters>    = \[<parameter> (\| <parameter>)*\]
<extracted_var> = @<var>@
<content>       = (<string>|<extracted_var>)*

Rules

• A value can reference a variable from the same section or a previous one: var2 = var1, var2 = var1.sub, var1.sub2 = var1.sub1
• In separated mode, variables from other sections must be accessed as SECTION.var, to avoid shadow declarations
• Spaces around = / := and -> / <- are optional
• = (immediate) is used for a <string>; := (lazy) is used for a <regex>. Any = <string> can be replaced by := <regex>

Important

A code sub-section that doesn't end on ret <boolean> is treated as false by default.

• The code:match sub-section can only be used with variables defined via full regex (:=)
• The event variable is a struct of <string>; the i variable is a <size_t>

ICF — Input Configuration

Extension: icf — describes how to parse an input file.

Note

Section order is fixed: [IMPORT] → [HEADER] → [VARIABLES] → [PARSING]

Import

from <path> import <var_prev:(VARIABLES|PARSING)> (, <var_prev:(VARIABLES|PARSING)>)*
import <path> (, <path>)*

Imports variables or parsing rules from another configuration file, either selectively (from ... import ...) or entirely (import ...).

Header

Field	Type	Description
file	<file>	Whether the file is binary, textual, or a language file
type	<file_type>	Whether this file is an input, output, or visual configuration
extension / ext	<string>	Expected file extension
separated / sep	<boolean>	Enables separated mode (see Rules)

Variables

var := <regex>
var ->
    start    = <string>
    start    = <boolean>
    end      = <string>
    end      = <boolean>
    contains = <string>
var <-
var.start    = <string>
var.start    = <boolean>
var.end      = <string>
var.end      = <boolean>
var.contains = <string>

A variable is defined either directly with a regex (var := <regex>), or through a set of boundary properties (start, end, contains) that define where its content begins, ends, or what it must contain — using either the block form (var -> ... ) or the dotted shorthand (var.start = ...).

Parsing

@var[:<var_type>]@
@def
using       = <var:VARIABLES>
start_with  = <var_now>|entry
start_after = <var_now>|entry

[
@code:match
<instructions>
]

[
@code:start
<instructions>
]

[
@code:end
<instructions>
]

• @var[:<var_type>]@ extracts a variable's value (matches the <extracted_var> rule from Syntax)
• @def starts a parsing definition, anchored to a variable from VARIABLES (using), and a starting point (start_with / start_after), either the current scope or the reserved entry point
• @code:match, @code:start, @code:end are the code sub-sections, each holding <instructions> — see Rules for their constraints (code:... restriction, default false return)

OCF — Output Configuration

Extension: ocf — describes how to write an output file.

Note

Section order is fixed: [HEADER] → [FORMAT] → [WRITING-HEADER] → [WRITING-CONTENT]

Header

Field	Type	Description
file	<file>	Whether the file is binary, textual, or a language file
extension / ext	<string>	File extension to produce
separated / sep	<boolean>	Enables separated mode (see Rules)
using	<path>	Path to an imported configuration file
indent_size	<size_t>	Default indentation size

Format

var ->
    ignored     = <boolean>
    keep_indent = <boolean>
    indent      = <size_t>
    before      = <string>
    after       = <string>
var.ignored     = <boolean>
var.keep_indent = <boolean>
var.indent      = <size_t>
var.before      = <string>
var.after       = <string>

var
var:sub-var
var:sub-var:sub-var...

Property	Type	Description
ignored	<boolean>	Excludes the variable from the output
keep_indent	<boolean>	Preserves the variable's original indentation
indent	<size_t>	Overrides the indentation applied to the variable
before	<string>	Text inserted immediately before the variable's value
after	<string>	Text inserted immediately after the variable's value

The var:sub-var:sub-var... chain targets a nested variable path and overwrite interaction on sub-var during writing

Writing Header

magic = <hex>
content = <string>
content:hex = <hex> (<space> <hex>)*
content:bin = <bin> (<space> <bin>)*

Defines the raw bytes written at the start of the output file. magic sets a fixed signature; content (or its :hex / :bin variants) sets literal header bytes as a string, hex sequence, or binary sequence.

Writing Content

@soi[<parameters>]
<content>
@eoi

@soi / @eoi mark the start and end of an output instance. <parameters> (see Syntax) configure formatting for that instance (e.g. no-nl, indent:<size_t>). The body follows the <content> rule: a mix of literal strings and @var@ extractions.

VCF — Visual Configuration

Extension: vcf — describes how to render a visualization.

Warning

Not documented yet.