tla-sbuilder 0.2.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a2598df840dc392c2decb758b1dbc7f057cd6e6a
-  data.tar.gz: c58a5b8370bb4571dd7d4b33f6f5acb9c8049115
+  metadata.gz: 13bb5aca53c85d8ae5b3943c8c37c23f745adc00
+  data.tar.gz: 5f22e716073199acd62eef8f1477b2562727374c
 SHA512:
-  metadata.gz: d64be8f51018a61900294b67cf884b19db0e752b98b935fde5c8c9565e9c93765afd1277896f57470153b587a44c0bb08fed3cbbf57e085dff7b68c78a58c114
-  data.tar.gz: 16637b1375dc71c8a281b04f42373c0e89d13805529baff758ed8e9bddf92163e697f6f2c1a3bd5824b300f3737b9843213f5f40da55122888c573ec4cb82ae0
+  metadata.gz: 2686dae3b6360eeafa1d6f71639515f718c0f45bd43067010ea740391ab3338e5086d51f24d7d4929c7ed8499b94d3f2967ecd69b855d24f90dc935e121d3fd3
+  data.tar.gz: 9412ebeb149ca0357e0340cdadc00c7b1d55df6778764464a880274b13f1759f79c47a86c18b13162eab0a0fe4bf59ce6cd661ca63ba87048e742e1b11a5acd9

data/README.md

@@ -1,12 +1,12 @@
 <link href="../site.css" rel="stylesheet"></link>
 [Readme](README.md) [Releases](RELEASES.md)
 
-# Sbuilder - A Specification Builder for TLA+ Tools - $Release:0.2.2$
+# Sbuilder - A Specification Builder for TLA+ Tools - $Release:0.3.4$
 
-A tool to generate runnable specification models in
+A tool to generate runnable formal models in
 [TLA+ language](http://research.microsoft.com/en-us/um/people/lamport/tla/book.html)
-for [target systems](#TARGET-SYSTEM). Specification model can be
-verified using
+for [target systems](#TARGET-SYSTEM). Formal model can be verified
+using
 [TLA+ Tools](http://research.microsoft.com/en-us/um/people/lamport/tla/tools.html),
 and parts of it can be presented as
 [implementation blueprints](#BLUEPRINT) to developers.
@@ -14,16 +14,16 @@ and parts of it can be presented as
 See
 
 * [documentation](https://jarjuk.wordpress.com/sbuilder/) for
-  backgroun information, User's Guide and Developer's Guide
+  background information, User's Guide and Developer's Guide
 
-* [live documentation](http://jarjuk.github.io/tla-sbuilder/0.2.2/features.html)
-  (Cucumber tests) for more details on configuring Sbuilder, and on
-  features implemented by Sbuilder
+* [on-line documentation](http://jarjuk.github.io/tla-sbuilder.html)
+  (including Cucumber tests) for more details on configuring Sbuilder,
+  and on features implemented by Sbuilder
 
 
 ## <a id="TARGET-SYSTEM">Target Systems</a>
 
-Sbuilder supports modeling typical business IT systems, where a system
+Sbuilder supports modeling business IT systems, where system
 architecture identifies
 
 * **interfaces**: entry point providing access to services within the
@@ -40,60 +40,61 @@ architecture identifies
 
 ## <a id="ELEMENTS-OF">Runnable Specification Code</a>
 
-Sbuilder combines three main elements to create runnable TLA+
-Specification Code:
+Sbuilder combines three main elements to create runnable TLA+ formal
+model:
 
-1. **Interface specification**: Natively Sbuilder accepts
+1. **API interfaces**: Natively Sbuilder accepts
   [RESTfull](https://en.wikipedia.org/wiki/Representational_state_transfer)
   interface api specification expressed in
   [Swagger](http://swagger.io/)
-  [v2.0](http://swagger.io/specification/) format. Plugin system
-  allows importing API confiugration also from external systems,
-  e.g. from [salesforce](https://github.com/jarjuk/tla-sbuilder-salesforce)
+  [v2.0](http://swagger.io/specification/)
+  format. [API Loader Extension Point](#API_LOADER) allows importing
+  API confiugration also from external systems, e.g. from
+  [salesforce](https://github.com/jarjuk/tla-sbuilder-salesforce)
   
-2. **Specification extension**: Sbuilder tangles manually crafted code
-   snippets from Sbuilder *code repository* with the code generated
-   using *inteterface specifications*. The manual code snippets use
-   TLA+ language to model behavior and correctness criteria of the
-   target system.
-  
-3. **Setups**: To complete runnable code Sbuilder uses setups. A setup
-   is a sequence of interface operations, and their input parameters.
-   In addition, a setup may define domain cardinalities, or domain
-   values.  The tools allows defining multiple setups, each setup
-   resulting to a complete, runnable TLA+ code, allowing system model
-   to be run in various environment context
+2. **TLA Snippets**: Sbuilder tangles either manually crafted TLA
+   snippets from Sbuilder *code repository*, or snippets loaded using
+   [Snippet Loader Extension Point](#SNIPPET_LOADER), with code
+   created for *API interfaces*. *TLA -snippets* are also used to
+   specify correctness criteria for the system. Examples of *TLA
+   Snippets* are:
+
+	  * **state**: TLA+ variables modeling *database*
 
-Sbuilder uses following categories to organize *specification
-snippets* in its **code repository**:
+	  * **operator**: TLA+ language constructs, which enable "to define all
+		 the data structures and operations that occur in the specification"
 
-* **state**: TLA+ variables modeling *database*
+	  * **transaction**: pseudo code implementation of common behavior in
+		 modifying system state
 
-* **operator**: TLA+ language constructs, which enable "to define all
-   the data structures and operations that occur in the specification"
+	  * **service**: pseudo code implementation of target system
+	   *application services* using PlusCal procedures in TLA+ language
 
-* **transaction**: pseudo code implementation of common behavior in
-   modifying system state
+	  * **infrastructure**: pseudo code implementation of target system
+		*infrastructure services* using PlusCal procedures in TLA+ language
 
-* **service**: pseudo code implementation of target system
- *application services* using PlusCal procedures in TLA+ language
+	  * **interface**: implementation of *application interface* extension
+		  points using PlusCal macros in TLA+ language
 
-* **infrastructure**: pseudo code implementation of target system
-  *infrastructure services* using PlusCal procedures in TLA+ language
+	  * **correctness**: operator definitions, and INVARIANT directives in
+		TLA+ language specifying properties, which must be not violated in
+		specification executions
 
-* **interface**: implementation of *application interface* extension
-    points using PlusCal macros in TLA+ language
+	  * **possibility**: optional operator definitions to increase
+		confidence in correctness invariants
 
-* **correctness**: operator definitions, and INVARIANT directives in
-  TLA+ language specifying properties, which must be not violated in
-  specification executions
+	  * **assumption**: operator definitions, in TLA+ language specifying
+		properties on specification model constants, which must be not
+		violated.
 
-* **possibility**: optional operator definitions to increase
-  confidence in correctness invariants
+  
+3. **Setups**: To complete the runnable formal model Sbuilder uses
+   setups. A setup is a sequence of interface operations, and their
+   input parameters.  Setup also define domain cardinalities, or
+   domain values.  The tools allows defining multiple setups, each
+   setup resulting to a complete, runnable TLA+ code, allowing
+   application model to be run in various environment context
 
-* **assumption**: operator definitions, in TLA+ language specifying
-  properties on specification model constants, which must be not
-  violated.
 
 Sbuilder can generate <a id="BLUEPRINT">**implementation
 blueprints**</a> as depicted in section
@@ -102,84 +103,48 @@ blueprints* are html-pages including code snippets from Sbuilder *code
 repository*, or code generated based on *interface specifications*.
 
 
-## <a id="MODELING-PIPELINE">Modeling Pipeline</a>
-
-The picture below gives an overview, how Sbuilder -tool can be
-deployed in an "mainstream" software development process.
-
-The objective for creating a specification model is to get better
-understanding, to get the design right, and to write better code for
-the system being built - and thereby to justify the extra effort
-needed in modeling.
-
-
-![process](pics/process.jpg)
-
-We assume that services are currently implemented based on informal
-service specification documents written in English. We also assume
-that service interface is available in a machine readable format.
+## Two Operating Modes
 
-In the picture, process enhancements are highlighted in a box labeled
-"Pseudo code modeling". The output of the process enhancement are
-implementation blueprints, which are made available for developers at
-the side of current service implementation documentation. An
-implementation blueprint for a service contains pseudo code snippets
-extracted from specification model, relevant for implementing a
-particular service.
+Sbuilder supports two operating modes:
 
-Pseudo code modeling includes following tasks:
+* Modeling Pipeline
+* Embedded Mode
 
-- **accept API specification input**: Machine readable interface
-  specification is translated to TLA+ language.
 
-- **create domain model**: Interface parameters are mapped to
-  domains. In this task, we define domain resolvers in Sbuilder -tool,
-  and add TLA+ operators, and assumptions to verify that the resulting
-  domain model conforms to service specification. In practice,
-  creating a formal domain model results in "Gaining better
-  understanding" of the informal specification.
+### <a id="MODELING-PIPELINE">Modeling Pipeline</a>
 
-- **specify correctness**: In the spirit of Test Driven Development,
-  specifying correctness precedes specifying behavior. In this task,
-  we interpret test cases, (hopefully) presented in the informal
-  service specification, as TLA+ language operators and invariants.
+Sbuilder can be embedded into "mainstream" software development
+process to support specification and design up-front, before actually
+starting the implementation.
 
-- **model behavior**: Modeling behavior includes creating pseudo code
-  service implementation in TLA+ language. In this task, when we have
-  formal correctness criteria expressed in TLA+, running model checker
-  points out traces leading to violations any of the criteria, and
-  helps us in "Getting design right".
+In *Modeling Pipeline* mode, Sbuilder is used to create formal
+specification model of the application with the objectives 1) to get
+better understanding, 2) to get the design right, 3) and to write
+better code for the system being
+built. [more details](MODELING-PIPELINE.md)
 
-- **create implementation blueprint**: In the final task, modeler
-  defines web pages for implementation blueprints. A blueprint
-  collects relevant TLA+ snippets in Sbuilder code repository,
-  together with any other useful documentation, to help in
-  implementing a specific service. Web pages are made available for
-  service implementation to help developers to "Write better
-  code". Competent developers may understand TLA+ language, but, like
-  in software engineering generally, good comments in pseudo code
-  snippets will make blueprints more approachable.
 
 
-The picture above defines following roles:
+### <a id="EMBEDDED-MODE">Embedded Mode</a>
 
-* **architect**: expert role specifying services, and defining
-  interfaces 
+Adding a separate task to create a formal specification model calls
+for commitment, which may be
+[hard to achieve](https://jarjuk.wordpress.com/2016/06/08/sbuilder-roadmap/)
+in contemporary software development practices. In order to hide the
+complexities in creating a formal model, Sbuilder can be embedded into
+a framework, and to use implementation code in creating formal model
+of the application.
 
-* **modeler**: expert role crafting specification extensions, and
-using Sbuilder, and TLA+ tools to generate specification code, and
-to verify its correctness
+An example of embedded sbuilder is
+[sbuilder-ethereum](https://github.com/jarjuk/sbuilder-ethereum).
 
-* **developer**: expert role implementing IT system interface and
-service according to the service specification, interface definition,
-and Sbuilder blueprint.
 
 
 ## <a id="USAGE">Usage</a>
 
 ### Pre-requisites
 
-`Sbuilder` -tool requires Ruby 2.
+`Sbuilder` -tool requires Ruby 2.1
 
 To run the specification model created by Sbuilder -tool, you must
 have Java and
@@ -272,7 +237,8 @@ and observing **Error: Evaluating invariant** `possible_tag_with_invalid_address
 
 ### Create Own Model
 
-See [cucumber test](http://jarjuk.github.io/tla-sbuilder/0.2.2/features.html) for more details.
+See [on-line documentation](http://jarjuk.github.io/tla-sbuilder.html)
+for more details.
 
 Create default directories used by `sbuilder` in current working directory
 
@@ -325,7 +291,7 @@ controlling, how environment invokes interface operations, and in
 effect, by throttling number of states generated during model
 checking.
 
-To avoid enumering to0 large sets Sbuilder allows
+In order to avoid enumerating too large sets Sbuilder allows
 
 * fixing input parameter bindings in an interface operation. In cases,
   where domain sizes are not a problem, SBuilder allows TLA+ tool to
@@ -349,15 +315,21 @@ from the specification code.
 
 ## Extending Sbuilder
 
-Sbuilder defines an extension point to add API loader plugins. An API
+### <a id="API_LOADER">API Loader Extension Point</a>
+
+Sbuilder defines an *API Loader Extension Point* to load API
+interfaces, and data type definitions into Sbuilder context. An API
 loader is a Ruby class
 
-* using [Sbuilder::ApiLoader](lib/sbuilder/facade/api_loader.rb)
+* extending [Sbuilder::ApiLoaderPlugin](lib/sbuilder/facade/api_loader_plugin.rb)
+
+* using [Sbuilder::ApiLoader](lib/sbuilder/facade/api_loader_facade.rb)
   facade to integrate with Sbuilder
 
 * satisfying [`api_loader_facade` contract](lib/sbuilder/spec/api_loader_facade.rb)
 
-* used as demonstated in [cucumber tests](features/100-plugin-extension/010-api-loader-plugin.feature)
+* interacting with Sbuilder as demonstrated in
+  [cucumber tests](features/100-plugin-extension/010-api-loader-plugin.feature)
 
 For a plugin implementation example, see an Swagger API loader in
 Sbuilder:
@@ -368,9 +340,9 @@ Sbuilder:
 
 For example, to activate Sbuilder API loader plugin
 `Sbuilder::Interfaces::Salesforce::SalesforceLoader` implemented in
-`tla-sbuilder-salesforce` Gem using configuration hash shown below,
-add the following YAML snippet to `sbuilder.yaml` configuration file
-sub-section `extend.loaders`:
+`tla-sbuilder-salesforce` GEM using configuration hash shown below,
+add the following YAML snippet into `sbuilder.yaml` configuration file
+`extend.loaders` -section:
 
     extend:
           loaders:
@@ -396,6 +368,68 @@ In the example, `file` -property points to a plugin configuration
 file, and `cache` property gives name prefix for files, which the
 plugin may use to cache API content to speed up generation phase.
 
+### <a id="SNIPPET_LOADER">Snippet Loader Extension Point</a>
+
+Sbuilder defines an *Snippet Loader Extension Point* to load TLA
+snippets into Sbuilder context. An Snippet loader is a Ruby class
+
+* extending [Sbuilder::SnippetLoaderPlugin](lib/sbuilder/facade/snippet_loader_plugin.rb)
+
+* using [Sbuilder::SnippetLoaderFacade](lib/sbuilder/facade/snippet_loader_facade.rb)
+  facade to integrate with Sbuilder
+
+* satisfying interface specification
+  [`snippet_loader_plugin: signature`](lib/sbuilder/spec/snippet_loader.rb)
+
+* interacting with Sbuilder as demonstrated in
+  [cucumber tests](features/100-plugin-extension/200-snippet-loader-plugin.feature)
+
+For a plugin implementation, see an SnippetLoaderSimple example
+
+* [implementation](lib/sbuilder/snippet_loader_simple.rb)
+
+* [rpsec test](spec/sbuilder/snippet_loader_simple_spec.rb)
+
+
+For example, to activate `Sbuilder::Ethereum::Plugin` in
+[sbuilder-ethereum](https://github.com/jarjuk/sbuilder-ethereum) GEM,
+and to create a object instance with the name `solcLoader` use YAML
+configuration in `sbuilder.yaml` section `extend.loaders`:
+
+	extend:
+	  loaders:
+	  - className: Sbuilder::Ethereum::Plugin
+		gem: sbuilder-ethereum
+		configuration:
+		  solc_command: "/home/jj/work/sbuilder-ethereum/bin/solc"
+		objects:
+		- objectName: solcLoader
+		  configuration:
+			preferences:
+			  tla-trace: false
+
+In this example, class method `Sbuilder::Ethereum::Plugin.configure`
+accepts a setting `solc_command`, object method
+`Sbuilder::Ethereum::Plugin#configure` accepts `preferences` hash with
+a property `tla-trace`. See documentation for
+[sbuilder-ethereum](https://github.com/jarjuk/sbuilder-ethereum) GEM
+for more details on these settings.
+
+Plugin `Sbuilder::Ethereum::Plugin` hooks to *API Loader Extension
+Point* and to *Snippet Loader Extension Point*. Loading over these
+extensions points is activated using the following `sbuilder.yaml`
+configuration in `interfaces` and `snippets` -sections:
+
+	interfaces:
+	- objectName: solcLoader
+	  url:
+	  - solidity/demo1.sol
+	snippets:
+	- objectName: solcLoader
+	  snippets: 
+
+Notice, how this YAML snippet uses object instance name `objectName:
+solcLoader` defined in `extend.loaders` -section above.
 
 ## License 
 

data/VERSION

@@ -1 +1 @@
-0.2.2
+0.3.4

data/lib/cli/cli-customer.rb

@@ -27,6 +27,18 @@ module Sbuilder
     # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILDER_EXTENSION}
 
+    # ------------------------------------------------------------------
+    #{Sbuilder::CliText::SBUILDER_SNIPPETS}
+
+    snippets:
+
+      - className: Sbuilder::SnippetLoaderSimple 
+        snippets:
+
+            # make /customer(post) to map to name 'dummy'
+          - metatype: service_implementation
+            appName: /customers(post)
+            name: dummy
 
     # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILBER_INTERFACES}
@@ -96,12 +108,20 @@ module Sbuilder
     EOS
 
     EXTENSIONS_CUSTOMER_IF = <<-EOS.unindent
+
+    #{Sbuilder::CliText::EXTENSION_HEADER_PREFS}
+
     #{Sbuilder::CliText::EXTENSION_HEADER_IF}
     #
+    # 
     # Exampl uses dummy process, which should be replaced with real implementation
-    - interface-extension:
-          - matcher: /customers(post)
-            implementation: dummy
+    #
+    # DEPRECATED: use snippets property in sbuilder.yaml
+    # 
+    # - interface-extension:
+    #       - matcher: /customers(post)
+    #         implementation: dummy
+    # 
     EOS
     
 

data/lib/cli/cli-pet.rb

@@ -24,6 +24,18 @@ module Sbuilder
     # sbuilder
 
     SBUILDER_YAML_PET= <<-EOS
+    # sbuilder.ymal - for pet example
+    #
+    # ------------------------------------------------------------------
+    #{Sbuilder::CliText::SBUILDER_EXTENSION}
+    extend:
+      loaders: 
+
+         - className: Sbuilder::SnippetLoaderSimple
+           configuration:
+                src_dir: src/pet
+
+    # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILBER_INTERFACES}
 
     interfaces:
@@ -40,6 +52,34 @@ module Sbuilder
            file: #{FILE_INFRASTRUCTURE_PETSTORE}
 
 
+    # ------------------------------------------------------------------
+    #{Sbuilder::CliText::SBUILDER_SNIPPETS}
+    snippets:
+
+      - className: Sbuilder::SnippetLoaderSimple 
+        snippets:
+
+          - metatype: service_implementation
+            appName: /pets(post)
+            file: interface_post_pet.tla
+
+          - metatype: service_implementation
+            appName: /pets/{id}(delete)
+            file: interface_delete_pet.tla
+
+          - metatype: service_implementation
+            appName: /pets/{id}(get)
+            file: interface_get_pet.tla
+
+          - metatype: service_implementation
+            appName: /tags(post)
+            file: interface_post_tag.tla
+
+          - metatype: service_implementation
+            appName: /tags(put)
+            file: interface_put_tag.tla
+   
+
     # ------------------------------------------------------------------
     #{Sbuilder::CliText::SBUILDER_RESOLVERS}
     resolvers:
@@ -300,6 +340,9 @@ module Sbuilder
     EOS
 
     EXTENSIONS_PETSTORE_COMMON = <<-EOS
+
+    #{Sbuilder::CliText::EXTENSION_HEADER_PREFS}
+
     #{Sbuilder::CliText::EXTENSION_HEADER_DOM}
 
     #
@@ -320,25 +363,28 @@ module Sbuilder
 
     #{Sbuilder::CliText::EXTENSION_HEADER_SETUP}
 
-    - interface-extension:
-           - matcher: /pets(post)
-             implementation: post_pet
+    # - interface-extension:
+    #        - matcher: /pets(post)
+    #          implementation: post_pet
 
-           - matcher: /pets/{id}(delete)
-             implementation: delete_pet
+    #        - matcher: /pets/{id}(delete)
+    #          implementation: delete_pet
 
-           - matcher: /pets/{id}(get)
-             implementation: get_pet
+    #        - matcher: /pets/{id}(get)
+    #          implementation: get_pet
 
-           - matcher: /tags(post)
-             implementation: post_tag
+    #        - matcher: /tags(post)
+    #          implementation: post_tag
 
-           - matcher: /tags(put)
-             implementation: put_tag
+    #        - matcher: /tags(put)
+    #          implementation: put_tag
 
     EOS
 
     EXTENSIONS_PETSTORE_RUN1 = <<-EOS
+
+    #{Sbuilder::CliText::EXTENSION_HEADER_PREFS}
+
     #{Sbuilder::CliText::EXTENSION_HEADER_SETUP}
     #
     
@@ -370,6 +416,9 @@ module Sbuilder
 
     
     EXTENSIONS_PETSTORE_RUN2 = <<-EOS
+
+    #{Sbuilder::CliText::EXTENSION_HEADER_PREFS}
+
     #
     #
     
@@ -384,8 +433,10 @@ module Sbuilder
            - interface: /pets/{id}(get)
 
     EOS
-
     EXTENSIONS_PETSTORE_RUN_SVG = <<-EOS
+
+    #{Sbuilder::CliText::EXTENSION_HEADER_PREFS}
+
     #
     # Just enough behaviour to create a decent graph
     #
@@ -447,6 +498,9 @@ module Sbuilder
     
 
     EXTENSIONS_PETSTORE_RUN3 = <<-EOS
+
+    #{Sbuilder::CliText::EXTENSION_HEADER_PREFS}
+
     #
     #