Urtext looks for all files with the extension .urtext in the folder from which it is initialized. It compiles these into a project which is then managed and updated on the fly, as text is written and updated. Multiple projects can be managed at once.

Although there is core Python library, much of Urtext is implemented in itself.  Urtext includes a base project that implements its core features and settings. The base project is included every time Urtext runs and is accessible from the project list. The EXEC() call is an abstraction on Python’s exec() method, which executes arbitrary Python code. Using the EXEC() call inside Urtext can access, modify and extend the calls provided in base project and even, if desired, access and modify the core library “on the fly.”

Base Project Calls

TARGET( ) or >( )

Specifies a target to dynamically populate with output.

Syntax

TARGET([ link, file, or virtual output ])
shorthand: >([ link, file or virtual output ])

Node Output

If no special syntax is included, the target is assumed to be an existing node in the project.

Using the link wrapper syntax inside TARGET()  is not required but is more readable and also provides a working link to the output node.

File Output

Using the file link syntax inside TARGET() will output the content to the specified file, creating the file if it does not exist.

Virtual Output

Several “virtual outputs” are available:

  • @self : sends the output to the node containing the dynamic definition, overwriting/updating any existing content.
  • @clipboard : sends the output to the system clipboard
  • @next_line : sends the output to the line following the dynamic definition
  • @log : sends the output to the project log, if it exists.
  • @console : sends the output to the Python console
  • @popup : sends the output to a popup
INCLUDE( ) or +( )

Specifies nodes to include when building a dynamic output.

INCLUDE([ parameter; parameter; ... ] [ flags ... ])
shorthand:
+([ parameter; parameter; ... ] [ flags ... ])
Use semicolon or newline to separate the arguments.

Example

[[ …
INCLUDE(keyword = example value)
…
]]

Parameters

  • key name operator value
    • key name may be:
      • any key name in the project, including system keys
      • * matches “any key”
    • operator may be one of:
      • = “equals / is”
      • ? “contains”
      • before “is before” (for comparing Timestamps)
      • after “is after” (for comparing Timestamps)
    • value may be:
      • any metadata value in — or not in — the project. Values not in the project will return empty results
      • * matches “any value”
  • * with no operator will include all nodes in the project

When multiple parameters are included in a single INCLUDE() call, only the nodes meeting all are included.

To include nodes from multiple independent parameters, use multiple INCLUDE() call.

Flags

  • -title_only : includes nodes that contain only a title, no additional text. See Node Titles for more information.
  • -untitled : includes only untitled nodes (nodes with no text except metadata, dynamic definitions, or embedded/escaped syntax.
  • -is_meta : includes only nodes for which the value(s) of the key and operator are themselves a node. See Nodes as Metadata Values.
  • -is_not_meta : includes only nodes for which the value(s) of the key and operator are not a node.
  • -dynamic : includes dynamic nodes. Not included by default.
EXCLUDE() or -()

Specifies nodes to exclude when building a dynamic output.

Always evaluated after INCLUDE()

Parameters

Accepts all the same parameters as INCLUDE():

  • key name operator value
    • key name may be:
      • any key name in the project, including system keys
      • * matches “any key”
    • operator may be one of:
      • = “equals / is”
      • ? “contains”
      • before “is before” (for comparing Timestamps)
      • after “is after” (for comparing Timestamps)
    • value may be:
      • any metadata value in — or not in — the project. Values not in the project will return empty results
      • * matches “any value”
  • * with no operator will include all nodes in the project

When multiple parameters are included in a single EXCLUDE() call, only the nodes meeting all parameters are exclude. To exclude nodes from multiple independent parameters, use multiple EXCLUDE() calls.

Flags

Accepts all the same flags as INCLUDE():

  • -title_only : includes nodes that contain only a title, no additional text. See Node Titles for more information.
  • -untitled : includes only untitled nodes (nodes with no text except metadata, dynamic definitions, or embedded/escaped syntax.
  • -is_meta : includes only nodes for which the value(s) of the key and operator are themselves a node. See Nodes as Metadata Values.
  • -is_not_meta : includes only nodes for which the value(s) of the key and operator are not a node.
  • -dynamic : includes dynamic nodes. Not included by default.

in addition to:

  • -including_as_descendants : When using TREE(), excludes the specified nodes even if they appear as descendants of included nodes.
SORT( )
Sorts the included nodes.

Syntax

SORT( [keyname(s)] [flag(s)] )

Key names may be any key in the included nodes, including system keys.

Flags

  •   -num or -n  : Sorts the results numerically if possible. See numerical_keys in project_settings to set keynames whose values should be parsed as numbers.
  • -reverse or -r : Reverses the sort order
SHOW( )

Templates the output of each node outputted in a dynamic definition.

Syntax

SHOW( [format pattern] )

Unicode is valid, as is arbitrary text. Newlines must be specified explicitly with \n or \r.

Format Patterns

The following format patterns are available.

COLLECT( )
Aggregates occurrences of metadata, including timestamps. Returns a separate item for each occurrence.

Syntax

COLLECT( [metadata key ] [ operator ] [value ] )

Parameters

Parameters are those for INCLUDE(), though only one key/operator/value group is accepted. To collect multiple outputs, use multiple COLLECT() calls. Note that COLLECT() collects metadata only from nodes that are included in the INCLUDE() call(s).

  • key name operator value
    • key name may be:
      • any key name in the project, including system keys
      • * matches “any key”
    • operator may be one of:
      • = “equals / is”
      • ? “contains”
      • before “is before” (for comparing Timestamps)
      • after “is after” (for comparing Timestamps)
    • value may be:
      • any metadata value in — or not in — the project. Values not in the project will return empty results
      • * matches “any value”
LIMIT( )
Limits the output to the specified number of results.

Syntax

LIMIT([number])

Accepts only a single integer.

Example

[[ >(| output node >) +(*) LIMIT(10) ]]
LOG( )

Outputs all project log (errors and information) to the specified node.

Syntax

LOG()

Takes no parameters.

INFO( )

Outputs statistics about the current project.

Syntax

INFO()

Takes no parameters.

WHEN( )

Specifies when a dynamic definition should be evaluated.

Syntax

WHEN( [flag(s)] )

Flags

  • -never : disable the dynamic definition
  • further documentation forthcoming
  • …
  • …