Initial commit

docs/modules/introduction/pages/concepts.adoc

@@ -0,0 +1,97 @@
+= Concepts
+include::ROOT:partial$component-attributes.adoc[]
+:uri-property-list: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/UnderstandXMLPlist.html
+
+Let's get to know Pkl by discussing some of its concepts and features.
+
+[[abstraction]]
+== Abstraction
+
+Configuration tends to grow larger and more complex over time, making it increasingly difficult to understand and maintain.
+Pkl can reduce the size and complexity of configuration by
+
+* describing similar configuration elements in terms of their differences
+* introducing abstractions for common configuration elements
+* separating configuration structure from configuration data
+* computing instead of enumerating configuration
+
+[[evaluation]]
+== Evaluation
+
+Pkl code lives in _modules_, a more fancy and general term for _files_.
+Evaluating a module produces an in-memory _data model_ that is roughly comparable to a JSON data model.
+If evaluation completes successfully, the Pkl evaluator converts the data model to an external representation and terminates with the status code zero.
+Otherwise, the evaluator prints an error message and terminates with a non-zero status code.
+
+[[immutability]]
+== Immutability
+
+All Pkl data is immutable.
+Manipulating a value always returns a new value, leaving the original value unchanged.
+Immutability eliminates many potential sources of errors.
+
+[[isolation]]
+== Isolation
+
+Evaluation of Pkl code is strictly sandboxed.
+Except for a few well-defined and well-controlled exceptions, Pkl code cannot interact with the outside world.
+Leaving aside bugs in the language implementation, the worst thing that buggy or malicious Pkl code can do is to consume CPU and memory resources until the evaluator gets killed.
+Over time, sandboxing will be further strengthened to cover fine-grained CPU and memory boxing.
+
+[[rendering]]
+== Rendering
+
+Converting a data model to an external representation is called _rendering_ the model.
+Pkl ships with renderers for the following data formats:
+
+* JSON
+* Jsonnet
+* Pcf (a static subset of Pkl)
+* (Java) Properties
+* {uri-property-list}[Property List]
+* XML
+* YAML
+
+Support for other formats can be added by writing a custom renderer in Pkl or Java.
+See xref:language-reference:index.adoc#module-output[Module Output] and xref:pkl-core:index.adoc#value-visitor[Value Visitor] for more information.
+
+[[resemblance]]
+== Resemblance
+
+By design, Pkl code tends to structurally and visually resemble the configuration it generates.
+This makes the code easier to read and write.
+
+[[reuse]]
+== Reuse
+
+Modules can reuse other modules by xref:language-reference:index.adoc#import-module[importing] them from local or remote locations.
+Imports can also be used to split up one large module into multiple smaller ones, increasing maintainability.
+A configurable security policy helps to keep imports under control.
+
+[[schema]]
+== Schema
+
+Configuration is structured data.
+Pkl supports -- but does not require -- to express this structure as a _configuration schema_, a set of classes defining configuration properties, their defaults, types, and constraints.
+Writing and maintaining a configuration schema takes some effort but, in return, provides these benefits:
+
+* Independent evolution of configuration schema and configuration data, often by different teams (for example service providers and service consumers).
+* Automatic xref:pkl-doc:index.adoc[documentation generation].
+* Strong validation of configuration, both during development time and runtime.
+* Statically typed access to configuration from xref:java-binding:codegen.adoc[Java] and other languages through code generation.
+* Schema-aware development tools, for example REPLs and editors with code completion support.
+
+[[template]]
+== Templating
+
+Pkl supports writing templates for objects and entire modules.
+Templates can be repeatedly turned into concrete configuration by filling in the blanks, and -- when necessary -- overriding defaults.
+Sharing template modules over the network can streamline complex configuration tasks for entire teams, organizations, and communities.
+
+[[usability]]
+== Usability
+
+Everybody needs a configuration solution, but nobody wants to spend a lot of time learning it.
+To reflect this reality, Pkl has a strong focus on usability.
+For example, error messages explain causes and possible solutions and object properties maintain definition order to avoid surprises.
+We hope that this focus on usability will make Pkl accessible to a wide audience of occasional users, while still leaving room for expert users and advanced use cases.