generamba 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 332df03b4189ec266771fed0a46ac00c293cfd8e
-  data.tar.gz: 1cd1b1d225d848aaba37f174a1dc83ade3910c6a
+  metadata.gz: 24caf4143f4768fca7cbfd8a18a313430d1fa939
+  data.tar.gz: 34b32af6b64878ea9f7eb9270068abc3db2b7319
 SHA512:
-  metadata.gz: 03f54f9ef17ce0c0990741abf416e9739aa3f730911f4e32766effc3407059997deac415e87cd13d5a18d0f9a3dc24bb8bd7fa577bbaafec2e89b9ca22ba8c9b
-  data.tar.gz: f32faebc7eebe5d40df08fa06593d92dde3381270c86aa464e47a9dcbee00bc1a92c5c8e3a3ad0a0038d14bb516db9f1f37ded6abfc8b4556b76e23f8a43fcee
+  metadata.gz: d980760d382847b92e4f29ada83d3aee1b28e6b608589d1ba637dfddcc6e4bd9096433be824c3415ced6185ae52f5ad1dd4b75a981436e2da34b614b9795f62a
+  data.tar.gz: 521afeb37243599c6e0ee235e03ee44b67045b8d4c948c7b90810a5ace0799e54f341476aed582d9720c42a74d94252cdc6418b4861692d778015a06fd0ceedd

data/.gitignore

@@ -1,9 +1,4 @@
-.idea/.name
-.idea/Generamba.iml
-.idea/misc.xml
-.idea/modules.xml
-.idea/vcs.xml
-.idea/workspace.xml
+.idea/*
 .rakeTasks
 encodings.xml
 Gemfile.lock

data/README.md

@@ -1,4 +1,6 @@
-### Overview
+<p align="center">
+  <img src="http://i.imgur.com/1AwoVaN.png"/>
+</p>
 
 [![Build Status](https://travis-ci.org/rambler-digital-solutions/Generamba.svg)](https://travis-ci.org/rambler-digital-solutions/Generamba)
 [![Gem Version](https://badge.fury.io/rb/generamba.svg)](https://badge.fury.io/rb/generamba)
@@ -6,7 +8,12 @@
 
 **Generamba** is a code generator made for working with Xcode. Primarily it is designed to generate VIPER modules but it is quite easy to customize it for generation of any other classes (both in Objective-C and Swift).
 
-*We keep evolving Generamba:* [changelog](https://github.com/rambler-digital-solutions/Generamba/blob/develop/CHANGELOG.md), [release notes](https://github.com/rambler-digital-solutions/Generamba/releases).
+*We keep evolving Generamba:* 
+- [Vision](https://github.com/rambler-digital-solutions/Generamba/blob/develop/VISION.md),
+- [Changelog](https://github.com/rambler-digital-solutions/Generamba/blob/develop/CHANGELOG.md), 
+- [Release notes](https://github.com/rambler-digital-solutions/Generamba/releases).
+
+Besides it, we started work on 2.0 version with powerful DSL and plugins. Check the [release roadmap](https://github.com/rambler-digital-solutions/Generamba/blob/develop/docs/2.x/roadmap.md)!
 
 ![Generamba Screenshot](https://habrastorage.org/files/b98/770/b37/b98770b37dc54de98daf0e22fea38478.gif)
 

data/VISION.md

@@ -0,0 +1,41 @@
+# Vision
+
+Generamba is a tool with one primary role:
+
+> Routine tasks automation through code generation.
+
+At first it was designed to work only with Xcode - IDE for iOS/macOS, but as time passed we saw a lot of opportunities to use it in other circumstances, e.g. in frontend, Android and backend development.
+
+### What Is Generamba
+
+The Generamba core is a simple generator that takes a [liquid](https://shopify.github.io/liquid/) template and a set of parameters as an input and produces a text snippet as an output. Everything else is built upon this simple concept.
+
+There are a lot of IDE's, package managers and other stuff which is related to creating new code modules. We try to keep the core small but provide rich opportunities for integration with all these tools via plugins *(in development)* and templates *(ready to use)* systems.
+
+### General Aim
+
+Our general aim is to provide a simple yet extensible way to generate any piece of code. The beginner should be able to create new code modules without complex configuration process. Generamba capabilities should grow as fast as the user needs, providing ways to validate the environment status, integrations with different file systems and IDEs, complex statements inside templates and so on.
+
+### Templates
+
+Code templates are the fuel for Generamba. We use a [liquid](https://shopify.github.io/liquid/) markup, because of its beautiful syntax and the ability to implement really complex logic.
+
+Templates may be private as well as adopted for public. We provide a number of ways to install them - using local paths, remote git repository, public or private catalogs.
+
+We also maintain a [public catalog](https://github.com/rambler-digital-solutions/generamba-catalog) which has some popular templates for iOS/macOS projects.
+
+### Communication
+
+We try to keep all the discussion about Generamba within [GitHub issues](https://github.com/rambler-digital-solutions/Generamba/issues). This attitude allows us to keep our processes and intentions transparent.
+
+Besides it there is a private Telegram channel where maintainers discuss work questions. We are considering moving to Slack or Gitter at some point in the future - but we haven't grown big enough yet.
+
+### Contributions
+
+Despite main maintainers are engineers from Rambler&Co team, we are glad to welcome external contributors. Generamba has evolved a lot since the first alpha release thanks to a lot of ideas from its users that came in the form of issues and pull requests.
+
+The aim of our core team is to adopt Generamba possibilities to each user needs and provide him a way to extend its functionality himself.
+
+### ...
+
+The structure and idea of *VISION.md* file was taken from the [Danger](https://github.com/danger/danger) project and [@orta](https://github.com/orta).

data/docs/2.x/roadmap.md

@@ -0,0 +1,365 @@
+# Generamba 2.0 Roadmap
+### Overview
+
+The main aim of 2.0 release is to decouple Generamba from iOS/macOS development and make it available for other areas as well: backend, frontend, Android. 
+
+We'll definitely break the backwards compatibility with *Rambafile* and templates created for the 1.x Generamba versions. To simplify the upgrading process we're considering writing some automatic migration tools.
+
+### High-Level Tasks
+
+* Switch *Rambafile* from `yml` to a custom DSL format.
+	* Wrap repetitive tasks into *ramba*'s - the nearest analogs are *lane*'s from `fastlane`.
+	* Introduce the concept of two types of *plugins*: system (validation, save) and general-purpose.
+	* Allow the usage of different types of hooks - `before`, `after`, `error`.
+* Add validation plugins, that are available to check the environment before code generation.
+	* Extract the saving logic from the Generamba core to plugins, both to filesystem and Xcode.
+* Add saving plugins, that are available to process the text snippet created by generamba and save it somewhere.
+	* Extract the validation logic from the Generamba core to plugins, both for CocoaPods and Carthage.
+
+### Generamba Flow
+
+A typical generation process consists of three steps:
+	* validation
+	* generation
+	* saving
+
+#### Validation
+
+That step is used to validate the environment status before code generation. 	It's a perfect place to implement logic of checking the required packages versions, the presence of system libraries, git status and so on.
+
+If one of checks returns an error, the overall validation process doesn't stop until all of validation methods execute. This is crucial for a smooth user experience.
+
+#### Generation
+
+That's the core functionality of Generamba. A user provides a template name and some options which are used as an input. After the generation Generamba produces a text snippet as an output.
+
+There can be multiple generation actions as well. All of them are executed in the writing order and their results are stored in-memory.
+
+#### Saving
+
+This step defines what to do with a generation output. The most obvious options are to store it as a file in some directory on the disk, embed it in your IDE, upload somewhere or print in log.
+
+If there are multiple saving actions, each of them is applied to each generation output. They are executed in the writing order.
+
+### DSL
+
+#### Basic Rambafile Structure
+
+The main building block of *Rambafile* is `ramba`:
+
+```
+desc "Creates a new Xcode project"
+ramba :viper_module do
+  # Detailed description of generation steps
+end
+```
+
+The *Rambafile* may be monolithic as well as decomposed to multiple files. This is available via special functions:
+	- `ramba_import_local('path')` - imports the contents of `Rambafile` stored locally.
+	- `ramba_import_git('git', 'branch')` - imports the contents of Rambafile stored in remote git repository.
+
+#### Setting Options
+
+A user can set options in any part of *Rambafile* structure. It's important to note, that option, defined on the next level of method hierarchy, overwrites it's previous declaration. That allows to have a default value for some key and redefine it in each `ramba`.
+```
+set :project_name, 'MyProject'
+
+ramba :viper_module do
+  set :project_name, 'MyProject'
+end
+```
+
+It's also available to set an option using lambda:
+```
+set :date_string,  -> { 
+	"Current date: #{Date.now}"
+}
+```
+
+> How options are set in Rambafile...
+> 
+
+Besides `ramba` -specific options, there are template-specific options as well. They may correspond to a specific template and be defined in the *.rambaspec* file. 
+
+> The saving action for Xcode should behave differently depending on whether a generated file it's a code file or some resource. So, there is a special option for each file of Xcode templates:
+> `- {name: Router/RouterTests.m, path: Tests/Router/router_tests.m.liquid, is_resource: false}` 
+
+#### Hooks
+
+There are multiple types of hooks, which make possible to perform some action or redefine an option in certain moments of generation cycle.
+
+##### `before` hooks
+
+A user can specify a hook, that'll execute before a specific `ramba`:
+```
+before :viper_module do
+	# Some logic here...
+end
+```
+
+It's also possible to write a hook that'll execute before each `ramba`:
+```
+before_each do |ramba_name|
+	# Some logic here...
+end
+```
+
+##### `after` hooks
+
+A user can specify a hook, that'll execute after a specific `ramba`:
+```
+after :viper_module do
+	# Some logic here...
+end
+```
+
+It's also possible to write a hook that'll execute after each `ramba`:
+```
+after_each do |ramba_name|
+	# Some logic here...
+end
+```
+
+##### `error` hooks
+
+If any action returns an error, it's possible to customize the resulting behavior for a specific `ramba` :
+```
+error :viper_module do
+	# Some logic here...
+end
+```
+It's also possible to write a hook that'll execute in case of error in any `ramba`:
+```
+error_each do |ramba_name|
+	# Some logic here...
+end
+```
+
+#### `ramba` structure
+
+As we've already mentioned, `ramba` consists of three main steps. Multiple actions in each step are executed in the writing order.
+
+##### Validation actions
+
+```
+ramba :viper_module do
+	...
+	validate :validate_plugin_name do
+    set :some_option, 'some_value'
+    any_custom_action()
+  end
+  ...
+end
+```
+
+This notation means the following steps:
+	- The lambda passed to the validate action is executed.
+	- The plugin with name `validate_plugin_name` is called with options modified by lambda.
+
+The notation can be simplified to:
+```
+validate :validate_plugin_name
+```	
+
+##### Generation actions
+
+```
+ramba :viper_module do
+	...
+  gen :viper_module do
+    set :some_option, 'some_value'
+    any_custom_action(parameter1)
+ 	end
+  ...
+end
+```
+
+This notation means the following steps:
+	- The lambda passed to the gen action is executed.
+	* The `gen` command is called with a template *viper_module* and options modified by lambda.
+
+The notation can be simplified to:
+```
+gen :viper_module
+```	
+
+##### Saving actions
+
+```
+ramba :viper_module do
+	...
+	save :save_plugin_name do
+    set :some_option, 'some_value'
+    any_custom_action()
+  end
+  ...
+end
+```
+
+This notation means the following steps:
+	- The lambda passed to the saving action is executed.
+	- The plugin with name `save_plugin_name` is called with options modified by lambda.
+
+The notation can be simplified to:
+```
+save :save_plugin_name
+```	
+
+##### Custom Actions
+
+Besides system plugins (validation and saving), a user can create a general-purpose plugin which contains some specific reusable logic. E.g. a plugin which clears the environment - calls `git reset`, uninstalls some packages and so on. It's called simply by calling it's name:
+```
+ramba :viper_module do
+	...
+	any_custom_action()
+  ...
+end
+```
+
+##### Templates and Catalogs
+
+Templates and tempalte catalogs, used for code generation, can be specified right in the `ramba`'s.
+
+```
+ramba :viper_module do
+	catalog 'https://github.com/user/catalog', branch:'develop'
+	template 'viper_ios', version:'1.2.5'
+	template 'viper_ios2', path:'/local_templates'
+end
+```
+
+- `catalog` keyword specifies a custom template catalog (like https://github.com/rambler-digital-solutions/generamba-catalog).
+  - `branch` parameter specifies a concrete catalog branch
+- `template` keyword declares a template that needs to be installed
+  - `version` parameter specifies a concrete template version.
+  - `path` parameter specifies a local path to the template.
+  - `git` parameter specifies a remote repository path to a template.
+  - `branch` parameter is used together with `git` to specify a branch.
+  
+The `generamba template install` command aggregates all of the templates from the `Rambafile` and installs them in a `.generamba` hidden directory. When a user triggers some `ramba`, templates are loaded from this directory. The only exception are local templates - they are always installed from the specified in the `Rambafile` local path.
+
+### Plugins
+
+The main ideas behind plugin system are:
+
+	- Increase code reusability between different projects,
+	* Keep the Generamba core as simple as possible,
+	* Abstract from specific implementations of different IDEs,
+	* Allow users to easily extend Generamba functionality for their needs.
+
+As we've already mentioned, there are two types of plugins:
+
+	- System plugins - validation and saving,
+	* Custom plugins.
+
+The main difference between them is how system calls them during `ramba` execution.
+
+#### Plugin Structure
+
+```
+module Generamba
+  module Plugins
+		class CocoaPodsPackageVersionValidationPlugin < ValidationPlugin
+			# The main body of a plugin
+			def self.run(params)
+				# Loads Podfile
+				# Analyzez dependencies version
+				# Compares these versions to the passed options
+			end
+			
+			# The description of what this plugin does
+			def self.description
+        'Verifies dependencies version in the project Podfile'
+      end
+
+			# Explicitly declaring available plugin options
+			def self.available_options
+        [
+          Generamba::ConfigItem.new(key: :package_versions,
+                                    description: "The hash with dependencies names and required versions",
+                                    default_value: [])
+          ]
+      end
+
+			# Declaring the output parameters
+      def self.output
+        [
+          ['COCOAPODS_CHECK_RESULT', 'The result of dependency checking']
+        ]
+      end
+
+			# Who created this plugin
+      def self.authors
+        ["etolstoy"]
+      end
+		end
+	end
+end
+```
+
+The same structure applies to other kinds of plugins. The only difference is the base class for the plugin - it can be `ValidationPlugin`, `SavingPlugin`, `Plugin`. 
+
+We've borrowed the plugin structure from `fastlane`.
+
+#### Plugin Distribution
+
+To avoid over-engineering in this version plugins will be distributed together with Generamba binary. If there'll be a lot of community-created plugins, will think about switching to other distribution system.
+
+It's also possible to store plugins near the `Rambafile` in a separate directory `/plugins`. They'll be loaded by Generamba automatically.
+
+### Rambafile Example
+
+```
+ramba_import_local('path')
+ramba_import_git('git', 'branch')
+
+set :project_name, 'LiveJournal'
+
+before :viper_module do
+  set :company, 'Rambler&Co'
+  set :xcodeproj_path, 'LiveJournal.xcodeproj'
+  set :project_targets, ['LiveJournal1', 'LiveJournal2']
+  set :test_target, 'LiveJournalTests'
+end
+
+desc "Creates a simple VIPER module"
+ramba :viper_module do
+  validate :plugin_validate_name do
+    set :some_option, '456'
+    any_custom_action()
+  end
+
+  gen :template_name do
+    set :some_option, '123'
+    any_custom_action(parameter1)
+  end
+
+  save :file_system do
+    set :some_option, '789'
+  end
+
+  save :xcode_proj
+end
+
+desc "Creates a new Xcode project"
+ramba :create_project do
+  sh("liftoff") # Calling a shell script which invokes a 'liftoff' utility
+  add_pods(["Typhoon", "MagicalRecord"])
+
+  gen :app_delegate
+  gen :core_data_stack
+
+  save :file_system
+  save :xcode_proj
+end
+
+# It's called after each 'ramba' execution
+after_each do |ramba_name|
+  # Some logic here
+end
+
+# It's called in case of an error in any 'ramba'
+error :viper_module do
+  # Some error handling logic here
+end
+```

data/generamba.gemspec

@@ -21,8 +21,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.2'
 
   spec.add_runtime_dependency 'thor', '0.19.1'
-  spec.add_runtime_dependency 'xcodeproj', '1.2.0'
-  spec.add_runtime_dependency 'liquid', '3.0.6'
+  spec.add_runtime_dependency 'xcodeproj', '1.4.2'
+  spec.add_runtime_dependency 'liquid', '4.0.0'
   spec.add_runtime_dependency 'git', '1.2.9.1'
   spec.add_runtime_dependency 'cocoapods-core', '1.0.1'
   spec.add_runtime_dependency 'terminal-table', '1.4.5'

data/lib/generamba/template/helpers/rambaspec_validator.rb

@@ -32,7 +32,7 @@ module Generamba
           spec[TEMPLATE_NAME_KEY] != nil &&
           spec[TEMPLATE_AUTHOR_KEY] != nil &&
           spec[TEMPLATE_VERSION_KEY] != nil &&
-          spec[TEMPLATE_CODE_FILES_KEY] != nil
+          (spec[TEMPLATE_CODE_FILES_KEY] != nil || spec[TEMPLATE_TEST_FILES_KEY] != nil)
       return is_spec_valid
     end
 

data/lib/generamba/version.rb

@@ -1,5 +1,5 @@
 module Generamba
-  VERSION = '1.3.0'
-  RELEASE_DATE = '05.10.2016'
+  VERSION = '1.4.0'
+  RELEASE_DATE = '25.12.2016'
   RELEASE_LINK = "https://github.com/rambler-digital-solutions/Generamba/releases/tag/#{VERSION}"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: generamba
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Egor Tolstoy
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-05 00:00:00.000000000 Z
+date: 2016-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -32,28 +32,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.4.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: 1.4.2
 - !ruby/object:Gem::Dependency
   name: liquid
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.0.6
+        version: 4.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.0.6
+        version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: git
   requirement: !ruby/object:Gem::Requirement
@@ -184,9 +184,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- VISION.md
 - bin/console
 - bin/generamba
 - bin/setup
+- docs/2.x/roadmap.md
 - generamba.gemspec
 - lib/generamba.rb
 - lib/generamba/cli/cli.rb