Class Copperlace

java.lang.Object
dev.mahe.copperlace.Copperlace
All Implemented Interfaces:
AutoCloseable
public final class Copperlace extends Object implements AutoCloseable
High-level Copperlace renderer for repeated renders from one configuration.

Copperlace compiles a config once and owns the resulting native ruleset until close() is called. Use this class when rendering more than one rule, or when rendering the same rule multiple times, so the config does not need to be parsed and compiled for each render.

Instances are AutoCloseable; callers should prefer try-with-resources.

  • Method Details

    • fromString

      public static Copperlace fromString(String config)
      Compiles a configuration string into a reusable renderer.
      Parameters:
      config - configuration text containing Copperlace rules
      Returns:
      a renderer backed by a native Copperlace ruleset
      Throws:
      IllegalArgumentException - if config is blank
      CopperlaceException - if the config cannot be parsed or compiled

    • fromStringWithProcessors

      public static Copperlace fromStringWithProcessors(String config, Map<String, CopperlaceProcessor> processors)
      Compiles a configuration string into a reusable renderer with custom processors.
      Parameters:
      config - configuration text containing Copperlace rules
      processors - custom processor callbacks keyed by processor name
      Returns:
      a renderer backed by a native Copperlace ruleset
      Throws:
      NullPointerException - if processors, a processor name, or a processor is null
      IllegalArgumentException - if config is blank
      CopperlaceException - if the config cannot be parsed or compiled

    • fromFile

      public static Copperlace fromFile(Path path)
      Loads and compiles a configuration file into a reusable renderer.
      Parameters:
      path - path to the configuration file
      Returns:
      a renderer backed by a native Copperlace ruleset
      Throws:
      NullPointerException - if path is null
      CopperlaceException - if the file cannot be loaded, parsed, or compiled

    • fromFileWithProcessors

      public static Copperlace fromFileWithProcessors(Path path, Map<String, CopperlaceProcessor> processors)
      Loads and compiles a configuration file into a reusable renderer with custom processors.
      Parameters:
      path - path to the configuration file
      processors - custom processor callbacks keyed by processor name
      Returns:
      a renderer backed by a native Copperlace ruleset
      Throws:
      NullPointerException - if path, processors, a processor name, or a processor is null
      CopperlaceException - if the file cannot be loaded, parsed, or compiled

    • fromFile

      public static Copperlace fromFile(String path)
      Loads and compiles a configuration file into a reusable renderer.
      Parameters:
      path - path to the configuration file
      Returns:
      a renderer backed by a native Copperlace ruleset
      Throws:
      IllegalArgumentException - if path is blank
      CopperlaceException - if the file cannot be loaded, parsed, or compiled

    • fromFileWithProcessors

      public static Copperlace fromFileWithProcessors(String path, Map<String, CopperlaceProcessor> processors)
      Loads and compiles a configuration file into a reusable renderer with custom processors.
      Parameters:
      path - path to the configuration file
      processors - custom processor callbacks keyed by processor name
      Returns:
      a renderer backed by a native Copperlace ruleset
      Throws:
      NullPointerException - if processors, a processor name, or a processor is null
      IllegalArgumentException - if path is blank
      CopperlaceException - if the file cannot be loaded, parsed, or compiled

    • renderString

      public static String renderString(String config, String rule)
      Renders one rule from a configuration string.

      This convenience method compiles the config, renders one rule, and releases the native ruleset. Use fromString(String) for repeated renders from the same config.

      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the rule to render
      Returns:
      rendered text for rule
      Throws:
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringWithProcessors

      public static String renderStringWithProcessors(String config, String rule, Map<String, CopperlaceProcessor> processors)
      Renders one rule from a configuration string with custom processors.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the rule to render
      processors - custom processor callbacks keyed by processor name
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if processors, a processor name, or a processor is null
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringWithProcessors

      public static String renderStringWithProcessors(String config, String rule, Map<String,String> context, Map<String, CopperlaceProcessor> processors)
      Renders one rule from a configuration string with custom processors and initial context values.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the rule to render
      context - initial render context values
      processors - custom processor callbacks keyed by processor name
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if context, processors, a key, value, processor name, or processor is null
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderString

      public static String renderString(String config, String rule, Map<String,String> context)
      Renders one rule from a configuration string with initial context values.

      This convenience method compiles the config, renders one rule, and releases the native ruleset. Use fromString(String) for repeated renders from the same config.

      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringInferred

      public static String renderStringInferred(String config, String rule)
      Renders one rule from a configuration string as text, returning formatted JSON for object-valued rules.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the rule to render
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringInferred

      public static String renderStringInferred(String config, String rule, Map<String,String> context)
      Renders one rule from a configuration string with initial context, returning formatted JSON for object-valued rules.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringStructuredJson

      public static String renderStringStructuredJson(String config, String rule)
      Renders one structured rule from a configuration string as formatted JSON text.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the structured rule to render
      Returns:
      formatted JSON for rule
      Throws:
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringStructuredJson

      public static String renderStringStructuredJson(String config, String rule, boolean formatJson)
      Renders one structured rule from a configuration string as JSON text.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the structured rule to render
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringStructuredJson

      public static String renderStringStructuredJson(String config, String rule, Map<String,String> context)
      Renders one structured rule from a configuration string as formatted JSON text with initial context values.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the structured rule to render
      context - initial render context values
      Returns:
      formatted JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderStringStructuredJson

      public static String renderStringStructuredJson(String config, String rule, Map<String,String> context, boolean formatJson)
      Renders one structured rule from a configuration string as JSON text with initial context values.
      Parameters:
      config - configuration text containing Copperlace rules
      rule - name of the structured rule to render
      context - initial render context values
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if config or rule is blank
      CopperlaceException - if parsing, compilation, or rendering fails

    • renderFile

      public static String renderFile(Path path, String rule)
      Renders one rule from a configuration file.

      This convenience method loads and compiles the file, renders one rule, and releases the native ruleset. Use fromFile(Path) for repeated renders from the same config.

      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if path is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileWithProcessors

      public static String renderFileWithProcessors(Path path, String rule, Map<String, CopperlaceProcessor> processors)
      Renders one rule from a configuration file with custom processors.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      processors - custom processor callbacks keyed by processor name
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if path, processors, a processor name, or a processor is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileWithProcessors

      public static String renderFileWithProcessors(Path path, String rule, Map<String,String> context, Map<String, CopperlaceProcessor> processors)
      Renders one rule from a configuration file with custom processors and initial context values.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      context - initial render context values
      processors - custom processor callbacks keyed by processor name
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if path, context, processors, a key, value, processor name, or processor is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFile

      public static String renderFile(Path path, String rule, Map<String,String> context)
      Renders one rule from a configuration file with initial context values.

      This convenience method loads and compiles the file, renders one rule, and releases the native ruleset. Use fromFile(Path) for repeated renders from the same config.

      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if path, context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileInferred

      public static String renderFileInferred(Path path, String rule)
      Renders one rule from a configuration file as text, returning formatted JSON for object-valued rules.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      NullPointerException - if path is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileInferred

      public static String renderFileInferred(Path path, String rule, Map<String,String> context)
      Renders one rule from a configuration file with initial context, returning formatted JSON for object-valued rules.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      NullPointerException - if path, context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(Path path, String rule)
      Renders one structured rule from a configuration file as formatted JSON text.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      Returns:
      formatted JSON for rule
      Throws:
      NullPointerException - if path is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(Path path, String rule, boolean formatJson)
      Renders one structured rule from a configuration file as JSON text.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      NullPointerException - if path is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(Path path, String rule, Map<String,String> context)
      Renders one structured rule from a configuration file as formatted JSON text with initial context values.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      context - initial render context values
      Returns:
      formatted JSON for rule
      Throws:
      NullPointerException - if path, context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(Path path, String rule, Map<String,String> context, boolean formatJson)
      Renders one structured rule from a configuration file as JSON text with initial context values.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      context - initial render context values
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      NullPointerException - if path, context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFile

      public static String renderFile(String path, String rule)
      Renders one rule from a configuration file.

      This convenience method loads and compiles the file, renders one rule, and releases the native ruleset. Use fromFile(String) for repeated renders from the same config.

      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      Returns:
      rendered text for rule
      Throws:
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileWithProcessors

      public static String renderFileWithProcessors(String path, String rule, Map<String, CopperlaceProcessor> processors)
      Renders one rule from a configuration file with custom processors.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      processors - custom processor callbacks keyed by processor name
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if processors, a processor name, or a processor is null
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileWithProcessors

      public static String renderFileWithProcessors(String path, String rule, Map<String,String> context, Map<String, CopperlaceProcessor> processors)
      Renders one rule from a configuration file with custom processors and initial context values.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      context - initial render context values
      processors - custom processor callbacks keyed by processor name
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if context, processors, a key, value, processor name, or processor is null
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFile

      public static String renderFile(String path, String rule, Map<String,String> context)
      Renders one rule from a configuration file with initial context values.

      This convenience method loads and compiles the file, renders one rule, and releases the native ruleset. Use fromFile(String) for repeated renders from the same config.

      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileInferred

      public static String renderFileInferred(String path, String rule)
      Renders one rule from a configuration file as text, returning formatted JSON for object-valued rules.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileInferred

      public static String renderFileInferred(String path, String rule, Map<String,String> context)
      Renders one rule from a configuration file with initial context, returning formatted JSON for object-valued rules.
      Parameters:
      path - path to the configuration file
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(String path, String rule)
      Renders one structured rule from a configuration file as formatted JSON text.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      Returns:
      formatted JSON for rule
      Throws:
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(String path, String rule, boolean formatJson)
      Renders one structured rule from a configuration file as JSON text.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(String path, String rule, Map<String,String> context)
      Renders one structured rule from a configuration file as formatted JSON text with initial context values.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      context - initial render context values
      Returns:
      formatted JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • renderFileStructuredJson

      public static String renderFileStructuredJson(String path, String rule, Map<String,String> context, boolean formatJson)
      Renders one structured rule from a configuration file as JSON text with initial context values.
      Parameters:
      path - path to the configuration file
      rule - name of the structured rule to render
      context - initial render context values
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if path or rule is blank
      CopperlaceException - if loading, parsing, compilation, or rendering fails

    • render

      public String render(String rule)
      Renders a named rule from the loaded config.

      Each call uses a fresh render context, so per-render bindings are consistent within one output but do not carry over to later renders.

      Parameters:
      rule - name of the rule to render
      Returns:
      rendered text for rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • render

      public String render(String rule, Map<String,String> context)
      Renders a named rule from the loaded config with initial context values.

      The provided context is scoped to this render only. Values resolve before config-defined context defaults and named rules.

      Parameters:
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • renderInferred

      public String renderInferred(String rule)
      Renders a named rule as text, returning formatted JSON for object-valued rules.
      Parameters:
      rule - name of the rule to render
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • renderInferred

      public String renderInferred(String rule, Map<String,String> context)
      Renders a named rule with initial context, returning formatted JSON for object-valued rules.
      Parameters:
      rule - name of the rule to render
      context - initial render context values
      Returns:
      rendered text, or formatted JSON for an object-valued rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule)
      Renders a named structured rule from the loaded config as formatted JSON text.
      Parameters:
      rule - name of the structured rule to render
      Returns:
      formatted JSON for rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule, boolean formatJson)
      Renders a named structured rule from the loaded config as JSON text.
      Parameters:
      rule - name of the structured rule to render
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule, Map<String,String> context)
      Renders a named structured rule from the loaded config as formatted JSON text with initial context values.
      Parameters:
      rule - name of the structured rule to render
      context - initial render context values
      Returns:
      formatted JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • renderStructuredJson

      public String renderStructuredJson(String rule, Map<String,String> context, boolean formatJson)
      Renders a named structured rule from the loaded config as JSON text with initial context values.
      Parameters:
      rule - name of the structured rule to render
      context - initial render context values
      formatJson - true to format JSON with tabs, false for compact JSON
      Returns:
      JSON for rule
      Throws:
      NullPointerException - if context, a context key, or a context value is null
      IllegalArgumentException - if rule is blank
      CopperlaceException - if this renderer is closed or rendering fails

    • close

      public void close()
      Releases the underlying native ruleset handle.

      Calling close more than once is allowed.

      Specified by:
      close in interface AutoCloseable