cecil 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7aebd276ab6179fdf0fda6e2f2e5931ce8ca8a6ae1ba6921dc4aef92e408419c
+  data.tar.gz: bb381be1145ef880aa4348a156166c82eb51bc3e8cae94545683fbe928207d0a
+SHA512:
+  metadata.gz: f311e7689597ca7d98bd9db7912d48e6bcc1105b73af29966ba4fc291ef77a0a0aedb6701a3700455b88ec9df8b8efc87e42467f7a4f2a612ab0d411fdc070c9
+  data.tar.gz: 9651d08d7bc741d6ee1548d89e0e87ab17bcd28aed7a91eb5715dad7741e5f97fc24bbc7da0c57a34691874bf6e010b45472bf3519dc4d85e9154655634c6a48

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,25 @@
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Lint/AssignmentInCondition:       { Enabled: false }
+Metrics/AbcSize:                  { Enabled: false }
+Metrics/BlockLength:              { Enabled: false }
+Metrics/ClassLength:              { Enabled: false }
+Metrics/CyclomaticComplexity:     { Enabled: false }
+Metrics/MethodLength:             { Enabled: false }
+Metrics/PerceivedComplexity:      { Enabled: false }
+Style/Documentation:              { Enabled: false }
+Style/FrozenStringLiteralComment: { Enabled: false }
+Style/NumericPredicate:           { Enabled: false }
+
+Layout/LineLength:
+  Max: 120

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.1.4

data/.yard/README.md

@@ -0,0 +1,492 @@
+# Cecil
+
+An experimental templating library for generating source code.
+
+Cecil templates look like the source code you want to generate thanks to Ruby's flexible syntax.
+
+## Features
+
+### Write templates in plain Ruby
+
+Call `Cecil::Code.generate_string` and pass it a block. Inside the block, add lines of code via backticks (or use `src` if you prefer). Cecil returns your generated source code as a string.
+
+#### Example
+
+```ruby
+model_code = Cecil::Code.generate_string do
+  # Use backticks to add lines of code
+  `import Model from '../model'`
+
+  # Multi-line strings work, too.
+  # Cecil preserves indentation.
+  `class User extends Model {
+    id: number
+    name: string
+    companyId: number | undefined
+  }`
+
+  # use #src if you prefer to avoid backticks
+  src "export type Username = User['name']"
+end
+
+puts model_code
+```
+
+Returns:
+
+```typescript
+import Model from '../model'
+class User extends Model {
+  id: number
+  name: string
+  companyId: number | undefined
+}
+export type Username = User['name']
+```
+
+### Interpolate values with Cecil's low-noise syntax
+
+Use `#[]` on the backticks to replace placeholders with actual values.
+
+By default, placeholders start with `$` and are followed by an identifier.
+
+Positional arguments match up with placeholders in order. Named arguments match placeholders by name.
+
+#### Example
+
+```ruby
+field = "user"
+types = ["string", "string[]"]
+default_value = ["SilentHaiku", "DriftingSnowfall"]
+field_class = "Model"
+
+Cecil::Code.generate_string do
+  # positional arguments match placeholders by position
+  `let $field: $FieldType = $default`[field, types.join('|'), default_value.sort.to_json]
+
+  # named arguments match placeholders by name
+  `let $field: $FieldClass<$Types> = new $FieldClass($default)`[
+    field: field,
+    FieldClass: field_class,
+    Types: types.join('|'),
+    default: default_value.sort.to_json
+  ]
+end
+```
+
+Returns:
+
+```typescript
+let user: string|string[] = ["DriftingSnowfall","SilentHaiku"]
+let user: Model<string|string[]> = new Model(["DriftingSnowfall","SilentHaiku"])
+```
+
+
+#### "Doesn't Ruby already have string interpolation?"
+
+Yes, but compare the readability of these two approaches:
+
+```ruby
+`let $field: $FieldClass<$Types> = new $FieldClass($default)`[
+  field: field,
+  FieldClass: field_class,
+  Types: types.join('|'),
+  default: default_value.sort.to_json
+]
+
+# vs
+
+field_types = types.join('|'),
+default_json = default_value.sort.to_json
+"let #{field}: #{field_class}<#{field_types}> = new #{field_class}(#{default_json})"
+```
+
+### Indents code blocks & closes brackets automatically
+
+Pass a block to `#[]` gets indented and open brackets get closed automatically.
+
+#### Example
+
+```ruby
+model = "User"
+field_name = "name"
+field_default = "Unnamed"
+
+Cecil::Code.generate_string do
+  `class $Class extends Model {`[model] do
+    # indentation is preserved
+    `id: number`
+
+    `override get $field() {`[field_name] do
+      `return super.$field ?? $defaultValue`[field_name, field_default.to_json]
+    end
+  end # the open bracket from `... Model {` gets closed with "}"
+end
+```
+
+Returns:
+
+```typescript
+class User extends Model {
+    id: number
+    override get name() {
+        return super.name ?? "Unnamed"
+    }
+}
+```
+
+### Emit source code to other locations
+
+When generating source code, things like functions, parameters, classes, etc, often need to be declared, imported, or otherwise setup or before being used.
+
+`content_for` can be used to add content to a different location of your file.
+
+Call `content_for(some_key) { ... }` with key and a block to store content under the key you provide. Call `content_for(some_key)` with the key and *no* block to insert your stored content at that location.
+
+#### Example
+
+```ruby
+models = [
+  { name: 'User', inherits: 'AuthModel' },
+  { name: 'Company', inherits: 'Model' },
+]
+
+Cecil::Code.generate_string do
+  # insert content collected for :imports
+  content_for :imports
+
+  models.each do |model|
+    ``
+    `class $Class extends $SuperClass {`[model[:name], model[:inherits]] do
+      `id: number`
+    end
+
+    content_for :imports do
+      # this gets inserted above
+      `import $SuperClass from '../models/$SuperClass'`[SuperClass: model[:inherits]]
+    end
+
+    content_for :registrations do
+      # this gets inserted below
+      `$SuperClass.registerAncestor($Class)`[model[:inherits], model[:name]]
+    end
+  end
+
+  ``
+  # insert content collected for :registrations
+  content_for :registrations
+end
+```
+
+Returns:
+
+```typescript
+import AuthModel from '../models/AuthModel'
+import Model from '../models/Model'
+
+class User extends AuthModel {
+    id: number
+}
+
+class Company extends Model {
+    id: number
+}
+
+AuthModel.registerAncestor(User)
+Model.registerAncestor(Company)
+```
+
+### Collect data as you go then use it earlier in the document
+
+The `#defer` method takes a block and waits to call it until the rest of the template is evaluated. The block's result is inserted at the location where `#defer` was called.
+
+This gives a similar ability to `#content_for`, but is more flexible because you can collect any kind of data, not just source code.
+
+#### Example
+
+```ruby
+models = [
+  { name: 'User', inherits: 'AuthModel' },
+  { name: 'Company', inherits: 'Model' },
+  { name: 'Candidate', inherits: 'AuthModel' },
+]
+
+Cecil::Code.generate_string do
+  superclasses = []
+
+  defer do
+    # This block gets called after the rest of the parent block is finished.
+    #
+    # By the time this block is called, the `superclasses` array is full of data
+    #
+    # Even though this block is called later, the output is added at the location where `defer` was called
+    `import { $SuperClasses } from '../models'`[superclasses.uniq.sort.join(', ')]
+    ``
+  end
+
+  models.each do |model|
+    superclasses << model[:inherits] # add more strings to `superclasses`, which is used in the block above
+
+    `class $Class extends $SuperClass {}`[model[:name], model[:inherits]]
+  end
+end
+```
+
+Returns:
+
+```typescript
+import { AuthModel, Model } from '../models'
+
+class User extends AuthModel {}
+class Company extends Model {}
+class Candidate extends AuthModel {}
+```
+
+### Customizable syntax and behaviors
+
+Easily customize the following features to make Cecil suit your needs/preferences:
+
+- placeholder syntax
+- auto-closing brackets
+- indentation
+
+Customizations are performed by subclassing {Cecil::Code `Cecil::Code`} and overriding the relevant methods.
+
+For example, Cecil comes with {Cecil::Lang::TypeScript `Cecil::Lang::TypeScript`} that you can use instead of of `Cecil::Code`. It has a few JavaScript/TypeScript-specific customizations. It's a subclass of `Cecil::Code` so it can be used the same way:
+
+```ruby
+Cecil::Lang::TypeScript.generate_string do
+  # ...
+end
+```
+
+## Use cases
+
+Things I've personally used Cecil to generate:
+
+- **serialization/deserialization code** generated from from specs (e.g. OpenAPI)
+- **diagrams** (e.g. Mermaid, PlantUML, Dot/Graphviz)
+    - ERDs/schemas
+    - state machine diagrams
+    - graphs
+    - data visualizations
+- **state machines** generated from a list of states and transitions
+- **test cases** generated from data that describes inputs/setup and expected outputs; because parameterized tests can be very hard to debug
+- **complex types** because meta-programming in TypeScript can get complex quickly
+
+## Quick Reference
+
+Reference documentation is on RubyDoc.info:
+  [gem](https://www.rubydoc.info/gems/cecil)
+  |
+  [repo](https://www.rubydoc.info/github/nicholaides/cecil/main)
+
+### Calling Cecil
+
+Call
+  {Cecil::Code.generate `Cecil::Code.generate`} /
+  {Cecil::Code.generate_string `generate_string`}
+  with a block and inside the block, use backticks or `#src` to emit lines of source code.
+  E.g.
+
+```ruby
+# returns a string
+Cecil::Code.generate_string do
+  `function greet() {}`
+  `function respond() {}`
+end
+
+# outputs to $stdout
+Cecil::Code.generate do
+  `function greet() {}`
+  `function respond() {}`
+end
+```
+
+See: {Cecil::BlockContext Methods available inside a Cecil block}
+
+### Emitting source code
+
+- {Cecil::BlockContext#src backticks/``` #`` ```/`#src`} emit source code.
+  E.g.:
+    ```ruby
+    Cecil::Code.generate_string do
+      `function greet() {}`
+      `function respond() {}`
+      src "function ask() {}"
+    end
+    # outputs:
+    # function greet() {}
+    # function respond() {}
+    # function ask() {}
+    ```
+
+- {Cecil::Node#with `#[]`} interpolates data into placeholders. E.g.
+    ```ruby
+    Cecil::Code.generate_string do
+      `function $fn() {}`["greet"]
+      `function $fn() {}`[fn: "respond"]
+    end
+    # outputs:
+    # function greet() {}
+    # function respond() {}
+    ```
+- {Cecil::Node#with `#[]`}`{ ... }` given a block, interpolates and indents the code emitted in its block.
+    E.g.
+    ```ruby
+    Cecil::Code.generate_string do
+      `function $fn() {`["greet"] do
+        `console.log("hello")`
+      end
+    end
+    # outputs:
+    # function greet() {
+    #     console.log("hello")
+    # }
+    ```
+- {Cecil::Node#<< `#<<`} adds code the last line of the block.
+    E.g.
+    ```ruby
+    Cecil::Code.generate_string do
+      `(function ${fn}Now() {`["greet"] do
+        `console.log("hello")`
+      end << ')()'
+    end
+    # outputs:
+    # (function greetNow() {
+    #     console.log("hello")
+    # })()
+    ```
+- {Cecil::BlockContext#content_for `#content_for`} emits source code to different locations
+- {Cecil::BlockContext#defer `#defer`} for waits to emit the given source until after data has been gathered
+
+### Customizing behavior for the language of the source code you're generating
+
+Many of Cecil's defaults can be customized by creating a subclass of {Cecil::Code `Cecil::Code`} and overriding methods to customize syntax and behavior of:
+- placeholder syntax
+- indentation
+- auto-closing brackets
+
+Currently, Cecil comes with:
+- {Cecil::Code `Cecil::Code`} for generic code
+- {Cecil::Lang::TypeScript `Cecil::Lang::TypeScript`} for JavaScript and TypeScript
+
+
+### Auto-closing brackets
+
+> Customize which opening brackets are auto-closed by overriding {Cecil::Code#block_ending_pairs `Cecil::Code#block_ending_pairs`} in a subclass.
+
+When nesting code blocks with `#[] { ... }`, open brackets at the end of the string get closed automatically.
+
+For example, notice how we don't have to manually provide a closing `}` in the following:
+
+```ruby
+`$var = {`[var: "user"] do
+  `id: 42`
+end
+```
+becomes
+```javascript
+user = {
+    id: 42
+}
+```
+
+#### Multiple brackets
+
+Every consecutive closing bracket at the end of the string gets closed. E.g.
+
+```ruby
+`$var = [{(`[var: "user"] do
+  `id: 42`
+end
+```
+
+becomes
+
+```javascript
+user = ([{
+    id: 42
+)}]
+```
+
+Currently, the algorithm is simplistic, so open brackets that aren't at the end of the string will *not* get closed.
+
+In this example, the `(` in `test(` needs to be closed manually:
+
+```ruby
+`test("getter $fn", () => {`[fn: 'getUsername'] do
+  `assert(false)`
+end << `)'
+```
+
+```javascript
+test("getter getUsername", () => {
+    assert(false)
+})
+```
+
+### Placeholder syntax
+
+Default placeholder rules:
+- start with `$`-- e.g. `$foo`
+- named with alpha-numeric and underscore -- e.g. `$foo_bar123`
+- names can optionally be surrounded by optional brackets -- e.g  `${my_placeholder}`
+
+Surrounding with brackets can be useful to separate a placeholder from subsequent characters that would otherwise get parsed as a placeholder.
+
+E.g. `function ${fn}Sync()`-- without curly brackets, the placeholder would be parsed as `fnSync`.
+
+Customize placeholder syntax by subclassing {Cecil::Code `Cecil::Code`}
+and overriding {Cecil::Code placeholder-related methods}.
+
+
+### Helper methods
+
+If you use your generator frequently it can be helpful to define reusable helper methods on a subclass of {Cecil::Code `Cecil::Code`}.
+
+For example, the {Cecil::Lang::TypeScript::Helpers `Cecil::Lang::TypeScript`][{Lang::TypeScript}] subclass defines several [helper methods} for generating TypeScript code.
+
+[{BlockContext#content_for}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/BlockContext#content_for-instance_method
+[{BlockContext#defer}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/BlockContext#defer-instance_method
+[{BlockContext#src}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/BlockContext#src-instance_method
+[{BlockContext}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/BlockContext
+[{Code.generate_string}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Code#generate_string-class_method
+[{Code.generate}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Code#generate-class_method
+[{Code}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Code
+[{Code#block_ending_pairs}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Code#block_ending_pairs-instance_method
+[{Lang::TypeScript}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Lang/TypeScript
+[{Lang::TypeScript::Helpers}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Lang/TypeScript/Helpers
+[{Lang::TypeScript.generate_string}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Lang/TypeScript#generate_string-class_method
+[{Lang::TypeScript.generate}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Code#generate-class_method
+[{Node#<<}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Node#<<-instance_method
+[{Node#with}]: https://www.rubydoc.info/github/nicholaides/cecil/main/Cecil/Node#with-instance_method
+
+## Installation
+
+Gem can be installed from github. Once I'm ready to bother with version numbers and releases and such, then I'll publish to Rubygems.
+
+From your shell:
+
+```sh
+bundle add cecil --github=nicholaides/cecil
+```
+
+Add it to your Gemfile like:
+
+```ruby
+gem 'cecil', github: 'nicholaides/cecil'
+```
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nicholaides/cecil.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/.yardopts

@@ -0,0 +1,2 @@
+--markup=markdown
+--readme=.yard/README.md

data/Gemfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in cecil.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"
+
+gem "retest", "~> 1.11"
+
+gem "yard", "~> 0.9.34"
+
+gem "webrick", "~> 1.8"

data/Gemfile.lock

@@ -0,0 +1,81 @@
+PATH
+  remote: .
+  specs:
+    cecil (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    diff-lcs (1.5.0)
+    ffi (1.16.3)
+    json (2.7.1)
+    language_server-protocol (3.17.0.3)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    parallel (1.24.0)
+    parser (3.3.0.2)
+      ast (~> 2.4.1)
+      racc
+    racc (1.7.3)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    regexp_parser (2.9.0)
+    retest (1.11.0)
+      listen (~> 3.2)
+      string-similarity (~> 2.1)
+      tty-option (~> 0.1)
+    rexml (3.2.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    rubocop (1.59.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.4)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.30.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    ruby-progressbar (1.13.0)
+    string-similarity (2.1.0)
+    tty-option (0.3.0)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
+    yard (0.9.34)
+
+PLATFORMS
+  arm64-darwin-22
+  arm64-darwin-23
+  x86_64-linux
+
+DEPENDENCIES
+  cecil!
+  rake (~> 13.0)
+  retest (~> 1.11)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  webrick (~> 1.8)
+  yard (~> 0.9.34)
+
+BUNDLED WITH
+   2.4.10

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Mike Nicholaides
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.