sf_cli 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d070d17a818ef2dd2030a026e1e3b14a284eb1e4ce1bab9ed46c8f5811c2169
-  data.tar.gz: aa7aafc17f57d6d9df71e6969caad6c756965cfce76ca5583acd73799366b34c
+  metadata.gz: 9416d015ec2952621fe3525a9ed7177a68b98a86d3bced475eacf19d3ad88ce0
+  data.tar.gz: 545bb5c54d345c194c5b62e8599492a45b13ba156b6ce195d3fb1fe38bb0d656
 SHA512:
-  metadata.gz: ddfd91e3ddd1573938d9dbb9c27749eb8054475cee62d5565222f75ad2867fe1abf3dc3c5cc48a452a79991971532f89b233ddf1db491a83b9f28348fdd53eb0
-  data.tar.gz: 9df1154ec04b5acefddc469429163feed1ee432abd517048b0915d046c29d9d30a5e097153aa50a5774085720f91c68f86cda484ada9d667a6140cd15bcbe6bb
+  metadata.gz: bf7e32d0d73b0af136d8153b16b05cf837977f37bd2b95c0ab0cecd8fe23bef9cfcb64bda1a1b16dc1ae5ce92fbf239670c4282fd65df28ff0f4bd835f3810cc
+  data.tar.gz: 835a95c35ef507c44d5108b613f7300bd8723428fd897ffc64ce8b0d14d0837929dc416c8259e12b713814903f1e5d59e1832e5d57bb9785f3c9bc397d111f8a

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+## 0.0.4 - 2024-09-02
+- breaking change:
+  - Sf class doesn't exist anymore. You can not write like `sf = SfCli::Sf.new`. Instead of that,  global `sf` method is introduced. You can directly type like `sf.org.display`, which is as almost same usability as the original command. 
+- sf data query:
+  - support child-parent relationship
+  - support parent-children relationship
+  - add `--result-format` option
+- auto generation of Object Model (experimental)
+  - generates SF Object Classes automatically
+  - relationship is supported
+
+## 0.0.3 - 2024-08-25
+add command operations:
+
+- sf data get record
+- sf data create record
+- sf data update record
+- sf data delete record
+
+## 0.0.2 - 2024-08-18
+this version up was made by mistake.
+nothing was changed.
+
+## 0.0.1 - 2024-08-18
+support some command operations:
+
+- sf org login web
+- sf display
+- sf data query
+- sf sobject describe
+- sf sobject list
+- sf project generate
+- sf project generate manifest

data/README.rdoc

@@ -2,7 +2,7 @@
 https://badge.fury.io/rb/sf_cli.png
 
 This is a class library for introducing {Salesforce CLI}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm] to Ruby scripting.<br>
-It is designed to be similar usability to the command line interface.<br>
+It is designed to be similar usability to the original command.<br>
 Currently only *sf* command is the target of development.
 
 == prerequisite
@@ -21,6 +21,39 @@ then,
   $ bundle install
 
 == Examples
+=== Since 0.0.4
+  require 'sf_cli'
+  #
+  # login to org
+  #
+  sf.org.login_web
+  sf.org.login_web target_org: :dev  # if the org you login isn't the default one, you should give it alias name for later use. 
+
+  #
+  # get records
+  #
+  sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
+
+  Account = Struct.new(:Id, :Name) # you can manually prepare the object model
+  sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account
+
+  # child-parent relationship is supported
+  sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1'  #  [{Id: "abc", Name: "contact name", Account: {Name: "account name"}}]
+
+  # parent-children relationship is supported
+  sf.data.query 'SELECT Id, Name, (SELECT Name From Contacts) FROM Account Limit 1'  #  [{Id: "abc", Name: "account name", Contacts: [{Name: "contact name"}]}]
+
+  #
+  # get sobject schema
+  #
+  sf.sobject.describe :Case  # get Case Object schema information
+
+  #
+  # generate a Salesforce DX project with manifest generation option
+  #
+  sf.project.generate 'MyProject', manifest: true
+
+=== Before 0.0.3
   require 'sf_cli/sf'
 
   sf = SfCli::Sf.new
@@ -38,13 +71,26 @@ then,
   # generate a Salesforce DX project
   sf.project.generate 'MyProject'
 
+== \Object Model support (experimental, since 0.0.4)
+  require 'sf_cli'
+  require 'sf_cli/sf/model'
+
+  # generates Model Class for Contact and Account, accessing the org aliased as 'dev'
+  SfCli::Sf::Model.generate %w[Contact Account], target_org: :dev
+
+  c = Contact.new(:Name => "John Smith")
+  c.Name # => "John Smith"
 
-For more command details, see {Salesforce CLI Command Reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm]
+  rows = sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1', model_class: Contact
+  rows.size # => 1
+  rows.first.Name # => Name of the Contact
+  rows.first.Account.Name # => Name of the Account
 
 == Documents
+The following steps generate *doc* directory, which all documents are generated in.
   $ git clone https://github.com/tmkw/sf_cli.git
   $ cd sf_cli
   $ bundle install
   $ bundle exec rake rdoc
 
-This generates the documents in doc directory.
+*Or*, you can read the same documents online at {rubygems.org}[https://rubygems.org/gems/sf_cli]

data/lib/sf_cli/sf/core/base.rb

@@ -0,0 +1,80 @@
+module SfCli
+  module Sf
+    module Core
+      module Base
+        attr_reader :varbose
+
+        private
+
+        def exec(action, flags: {}, switches: {}, redirection: nil, raw_output: false, format: :json) # :doc:
+          cmd = %|sf #{category} #{action}#{as_flag_options(flags)}#{as_switch_options(switches, format)}#{redirect redirection}|
+          puts cmd if varbose
+
+          return `#{cmd}` if raw_output
+
+          json = JSON.parse `#{cmd}`
+          puts json if varbose
+          raise StandardError.new(json['message']) if json['status'] != 0
+
+          json
+        end
+
+        def category
+          self.class.name.split('::')[-2].downcase
+        end
+
+        def field_value_pairs(hash)
+          return nil if hash.nil?
+          return nil if hash.empty?
+
+          hash.each_with_object([]) do|(k,v), arr|
+            value = v.instance_of?(String) ? %|'#{v}'| : v
+            arr << %(#{k}=#{value})
+          end
+          .join(' ')
+        end
+
+        def as_flag_options(hash)
+          flag_options   = hash.map{|k,v| flag k, v}.reject(&:nil?).join(' ')
+          flag_options   = ' ' + flag_options unless flag_options.empty?
+
+          flag_options
+        end
+
+        def as_switch_options(hash, format)
+          if format.to_sym == :json
+            ' ' + {json: true}.merge(hash).each_with_object([]){|(k,v), arr| arr << %(--#{k}) if v}.join(' ')
+          else
+            return '' if hash.empty?
+            hash.each_with_object([]){|(k,v), arr| arr << %(--#{k}) if v}.join(' ')
+          end
+        end
+
+        def flag(name, arg)
+          arg ? %(--#{name} #{arg}) : nil
+        end
+
+        def os
+          @os ||= ENV['OS']
+        end
+
+        def redirect(option)
+          case option
+          when :null_stderr
+            null_stderr_redirection
+          else
+          end
+        end
+
+        def null_stderr_redirection
+          @null_stderr_redirection ||=
+            if os.eql?('Windows_NT')
+              ' 2>nul'
+            else
+              ' 2> /dev/null'
+            end
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/core.rb

@@ -0,0 +1,179 @@
+require_relative '../core/base'
+require_relative './helper_methods'
+
+module SfCli
+  module Sf
+    module Data
+      #
+      # ==== description
+      # The class representing *sf* *data*
+      #
+      # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+        include ::SfCli::Sf::Data::HelperMethods
+
+        # get object records using SQOL. (eqivalent to *sf* *data* *query*)
+        #
+        # *soql* --- SOQL<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        # *model_class* --- the object model class<br>
+        #
+        # == examples
+        #   sf.data.query 'SELECT Id, Name FROM Account LIMIT 1' # => [{Id: "abc", Name: "account name"}]
+        #
+        #   Account = Struct.new(:Id, :Name)
+        #   sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account struct object
+        #
+        #   # child-parent relationship is supported
+        #   sf.data.query 'SELECT Id, Name, Account.Name From Contact Limit 1'  #  [{Id: "abc", Name: "contact name", Account: {Name: "account name"}}]
+        #
+        #   # parent-children relationship is supported
+        #   sf.data.query 'SELECT Id, Name, (SELECT Name From Contacts) FROM Account Limit 1'  #  [{Id: "abc", Name: "account name", Contacts: [{Name: "contact name"}]}]
+        #
+        #   Account = Struct.new(:Id, :Name) # you can manually prepare the object model
+        #   sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_query_unified]
+        #
+        # About querying with auto generated object model, see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+        #
+        def query(soql, target_org: nil, format: nil, model_class: nil)
+          flags    = {
+            :"query"    => %("#{soql}"),
+            :"target-org" => target_org,
+            :"result-format" => format,
+          }
+
+          raw_output = format ? true : false
+          format = format || :json
+
+          result = exec(__method__, flags: flags, redirection: :null_stderr, raw_output: raw_output, format: format)
+          return result if raw_output
+
+          result['result']['records'].each_with_object([]) do |h, a|
+            record = prepare_record(h)
+            a << (model_class ? model_class.new(**record) : record)
+          end
+        end
+
+        # get a object record. (eqivalent to *sf* *data* *get* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *record_id* --- id of the object<br>
+        # *where* --- hash object that is used to identify a record<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        # *model_class* --- the object model class<br>
+        #
+        # ==== examples
+        #   sf.data.get_record :Account, record_id: 'xxxxxxx'
+        #   sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}
+        #
+        #   CustomObject = Struct.new(:Id, :Name)
+        #   sf.data.get_record :TheCustomObject__c, record_id: 'xxxxx', model_class: CustomObject  # returns a CustomObject struct object
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_get_record_unified]
+        #
+        def get_record(object_type, record_id: nil, where: nil, target_org: nil, model_class: nil)
+          where_conditions = field_value_pairs(where)
+          flags = {
+            :"sobject"    => object_type,
+            :"record-id"  => record_id,
+            :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          result = json['result']
+          result.delete 'attributes'
+
+          model_class ? model_class.new(**result) : result
+        end
+
+        # update a object record. (eqivalent to *sf* *data* *update* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *record_id* --- id of the object<br>
+        # *where* --- field values that is used to identify a record<br>
+        # *values* --- field values for update<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # ==== examples
+        #   sf.data.update_record :Account, record_id: 'xxxxxxx', values: {Name: 'New Account Name'}
+        #   sf.data.update_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}, values: {Phone: 'xxxxx', bar: 2000}
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_update_record_unified]
+        #
+        def update_record(object_type, record_id: nil, where: nil, values: nil, target_org: nil)
+          where_conditions  = field_value_pairs(where)
+          field_values      = field_value_pairs(values)
+          flags = {
+            :"sobject"    => object_type,
+            :"record-id"  => record_id,
+            :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+            :"values"     => (field_values.nil? ? nil : %|"#{field_values}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['id']
+        end
+
+        # create a object record. (eqivalent to *sf* *data* *create* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *values* --- field values to be assigned<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # ==== examples
+        #
+        #   sf.data.create_record :TheCustomObject__c, values: {Name: "John Smith", Age: 33} # creating a TheCustomObject record with name and age
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_create_record_unified]
+        #
+        def create_record(object_type, values: {}, target_org: nil)
+          field_values = field_value_pairs(values)
+          flags = {
+            :"sobject"    => object_type,
+            :"values"      => (field_values.nil? ? nil : %|"#{field_values}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['id']
+        end
+
+        # delete a object record. (eqivalent to *sf* *data* *delete* *record*)
+        #
+        # *object_type* --- \Object Type (ex. Account)<br>
+        # *record_id* --- id of the object<br>
+        # *where* --- hash object that is used to identify a record<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # ==== examples
+        #   sf.data.delete_record :Hoge__c, record_id: 'xxxxxxx'
+        #   sf.data.delete_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm#cli_reference_data_delete_record_unified]
+        #
+        def delete_record(object_type, record_id: nil, where: nil, target_org: nil)
+          where_conditions = field_value_pairs(where)
+          flags = {
+            :"sobject"    => object_type,
+            :"record-id"  => record_id,
+            :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
+            :"target-org" => target_org,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['id']
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/data/helper_methods.rb

@@ -0,0 +1,35 @@
+module SfCli
+  module Sf
+    module Data
+      module HelperMethods
+        def prepare_record(hash) # :doc:
+          hash.delete 'attributes'
+
+          hash.keys.each do |k|
+            if parent?(hash[k])
+              hash[k] = prepare_record(hash[k])
+            elsif children?(hash[k])
+              hash[k] = hash[k]['records'].map{|h| prepare_record(h)}
+            end
+          end
+
+          hash
+        end
+
+        def children?(h)
+          return false unless h.instance_of?(Hash)
+
+          h.has_key? 'records'
+        end
+
+        def parent?(h)
+          return false unless h.instance_of?(Hash)
+
+          h.has_key?('records') == false
+        end
+
+        private :prepare_record, :children?, :parent?
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/main.rb

@@ -0,0 +1,31 @@
+require 'singleton'
+require 'json'
+
+module SfCli
+  module Sf
+    # ==== description
+    # The entry class of sf command. It is returned by sf method.
+    # With including Singleton module, the instance of this class is guaranteed as singleton.
+    #
+    # ==== examples
+    #   sf             # returns a instance of SfCli::Sf
+    #   sf.org.display # you can follow the similar syntax to the original command by using method chain.
+    #
+    class Main
+      include Singleton
+
+      OPERATION_CATEGORIES = %w[Org Sobject Data Project]
+
+      OPERATION_CATEGORIES.each do |category|
+        require_relative %(#{category.downcase}/core)
+        attr_reader category.downcase.to_sym
+      end
+
+      def initialize
+        OPERATION_CATEGORIES.each do |category|
+          instance_variable_set(:"@#{category.downcase}", Object.const_get(%|::SfCli::Sf::#{category}::Core|).new)
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/class_definition.rb

@@ -0,0 +1,112 @@
+require_relative './schema'
+
+module SfCli
+  module Sf
+    module Model
+      class ClassDefinition
+        attr_reader :schema
+
+        def initialize(schema)
+          @schema = Schema.new(schema)
+        end
+
+        def to_s
+          <<~Klass
+            Class.new do
+              #{ class_methods }
+
+              field_names.each do |name|
+                attr_accessor name
+              end
+
+              #{ parent_relation_methods }
+              #{ children_relation_methods }
+
+              #{ define_initialize }
+
+              #{ define_to_h }
+            end
+          Klass
+        end
+
+        def define_initialize
+          <<~EOS
+            def initialize(attributes = {})
+              attributes.each do |k, v|
+                field_name = k.to_sym
+                if self.class.field_names.include?(field_name)
+                  #instance_variable_set ('@' + field_name.to_s).to_sym, v
+                  __send__ (field_name.to_s + '='), v
+                elsif self.class.parent_relations.find{|r| r[:name] == field_name}
+                  __send__ (field_name.to_s + '='), v
+                elsif self.class.children_relations.find{|r| r[:name] == field_name}
+                  __send__ (field_name.to_s + '='), (v.nil? ? [] : v)
+                end
+              end
+            end
+          EOS
+        end
+
+        def define_to_h
+          <<~EOS
+            def to_h(keys: nil)
+              self.class.field_names.each_with_object({}) do |name, hash|
+                if keys&.instance_of?(Array)
+                  hash[name] = __send__(name) if keys.include?(name)
+                else
+                  hash[name] = __send__(name)
+                end
+              end
+            end
+          EOS
+        end
+
+        def class_methods
+          <<~EOS
+            class << self
+              def field_names
+                @field_names ||= #{ schema.field_names }
+              end
+
+              def parent_relations
+                @parent_relations ||= #{ schema.parent_relations }
+              end
+
+              def children_relations
+                @children_relations ||= #{ schema.children_relations }
+              end
+            end
+          EOS
+        end
+
+        def parent_relation_methods
+          schema.parent_relations.each_with_object('') do |r, s|
+            s << <<~EOS
+              def #{r[:name]}
+                @#{r[:name]}
+              end
+
+              def #{r[:name]}=(attributes)
+                @#{r[:name]} = #{r[:class_name]}.new(attributes)
+              end
+            EOS
+          end
+        end
+
+        def children_relation_methods
+          schema.children_relations.each_with_object('') do |r, s|
+            s << <<~EOS
+              def #{r[:name]}
+                @#{r[:name]}
+              end
+
+              def #{r[:name]}=(records)
+                @#{r[:name]} = records.map{|attributes| #{r[:class_name]}.new(attributes)}
+              end
+            EOS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/generator.rb

@@ -0,0 +1,27 @@
+require_relative '../sobject/core'
+require_relative './class_definition'
+
+module SfCli
+  module Sf
+    module Model
+      class Generator
+        attr_reader :sf_sobject, :target_org
+
+        def initialize(target_org: nil)
+          @sf_sobject = ::SfCli::Sf::Sobject::Core.new
+          @target_org = target_org
+        end
+
+        def generate(object_name)
+          class_definition = ClassDefinition.new(describe object_name)
+
+          instance_eval "::#{object_name} = #{class_definition}"
+        end
+
+        def describe(object_name)
+          sf_sobject.describe object_name, target_org: target_org
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model/schema.rb

@@ -0,0 +1,33 @@
+module SfCli
+  module Sf
+    module Model
+      class Schema
+        attr_reader :schema
+
+        def initialize(schema)
+          @schema = schema
+        end
+
+        def name
+          schema['name']
+        end
+
+        def field_names
+          schema['fields'].map{|f| f['name'].to_sym}
+        end
+
+        def children_relations
+          schema['childRelationships']
+            .select{|r| r['relationshipName'].nil? == false}
+            .map{|r| {name: r['relationshipName'].to_sym, class_name: r['childSObject'].to_sym}}
+        end
+
+        def parent_relations
+          schema['fields']
+            .select{|f| f['relationshipName'].nil? == false && f['referenceTo']&.size > 0}
+            .map{|f| {name: f['relationshipName'].to_sym, class_name: f['referenceTo'].first.to_sym}}
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/model.rb

@@ -0,0 +1,21 @@
+require_relative 'model/generator'
+
+module SfCli
+  module Sf
+    #
+    # ==== description
+    # The module for \Object \Model definition and generation
+    #
+    # see the section {"Object Model support"}[link://files/README_rdoc.html#label-Object+Model+support+-28experimental-2C+since+0.0.4-29] in README.
+    #
+    module Model
+      def self.generate(object_names, target_org: nil)
+        generator = Generator.new(target_org: target_org)
+
+        object_names.each do |object_name|
+          generator.generate(object_name)
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/org/core.rb

@@ -0,0 +1,61 @@
+require_relative '../core/base'
+
+module SfCli
+  module Sf
+    module Org
+      #
+      # ==== description
+      # The class representing *sf* *org*.
+      #
+      # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+
+        ConnectionInfo = Struct.new(:id, :access_token, :alias, :instance_url, :user_name, :api_version, :status)
+
+        # login to the org by the browser. (equivalent to *sf* *org* *login* *web*)
+        #
+        # *target_org* --- an alias of paticular org, not default one<br>
+        # *instance_url* --- custom login url.
+        #
+        # == examples:
+        #   sf.org.login_web
+        #   sf.org.login_web target_org: :dev  # if the org you login isn't the default one, you should give it alias name for later use.
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm#cli_reference_org_login_web_unified]
+        #
+        def login_web(target_org: nil, instance_url: nil)
+          flags    = {
+            :"alias"        => target_org,
+            :"instance-url" => instance_url,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          exec(action, flags: flags)
+        end
+
+        #
+        # returns the org's connection information. (equivalent to *sf* *org* *display*)
+        #
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm#cli_reference_org_display_unified]
+        #
+        def display(target_org: nil)
+          flags    = {:"target-org" => target_org}
+          json = exec(__method__, flags: flags, redirection: :null_stderr)
+
+          ConnectionInfo.new(
+            id:           json['result']['id'],
+            access_token: json['result']['accessToken'],
+            alias:        json['result']['alias'],
+            instance_url: json['result']['instanceUrl'],
+            user_name:    json['result']['username'],
+            api_version:  json['result']['apiVersion'],
+            status:       json['result']['connectedStatus']
+          )
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/project/core.rb

@@ -0,0 +1,76 @@
+require_relative '../core/base'
+
+module SfCli
+  module Sf
+    module Project
+      # ==== description
+      # The class representing *sf* *project*
+      #
+      # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+
+        GenerateResult = Struct.new(:output_dir, :files, :raw_output, :warnings)
+
+        #
+        # generate a Salesforce project. (equivalent to *sf* *project* *generate*)
+        #
+        # *name*        --- project name<br>
+        # *template*    --- project template name<br>
+        # *output_dir*  --- output directory<br>
+        # *manifest*    --- switch to create manifest file in the project directory (manifest/package.xml). default: false
+        #
+        # For more command details, see the {reference document}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_generate_unified]
+        #
+        def generate(name, manifest: false, template: nil, output_dir: nil)
+          flags    = {
+            :name         => name,
+            :template     => template,
+            :"output-dir" => output_dir,
+          }
+          switches = {
+            manifest: manifest,
+          }
+          json = exec(__method__, flags: flags, switches: switches, redirection: :null_stderr)
+
+          GenerateResult.new(
+            output_dir: json['result']['outputDir'],
+            files:      json['result']['created'],
+            raw_output: json['result']['rawOutput'],
+            warnings:   json['warnings']
+          )
+        end
+
+        # generate the manifest file of a Salesforce project. (equivalent to *sf* *project* *generate* *manifest*)
+        #
+        # *metadata*    --- an array that consists of metadata type like CustomObject, Layout and so on.  (default: [])<br>
+        # *api_verson*  --- api version (default: nil)<br>
+        # *output_dir*  --- manifest's output directory in the project directory. You can use relative path from the project root (default: nil)<br>
+        # *from_org*    --- username or alias of the org that contains the metadata components from which to build a manifest (default: nil)<br>
+        # *source_dir*  --- paths to the local source files to include in the manifest (default: nil)
+        #
+        # == examples
+        #  sf.project.generate_manifest metadata: %w[CustomObject Layout]  # creates a package.xml, which is initialized with CustomObject and Layout
+        #  sf.project.generate_manifest from_org: <org_name>               # creates a package.xml, which is initialized with all metadata types in the org
+        #
+        # For more command details, see the {reference document}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm#cli_reference_project_generate_manifest_unified]
+        #
+        def generate_manifest(name: nil, output_dir: nil, api_version: nil, metadata: [], from_org: nil, source_dir: nil)
+          flags    = {
+            :name           => name,
+            :"metadata"     => (metadata.empty? ? nil : metadata.join(' ')),
+            :"from-org"     => from_org,
+            :"source-dir"   => source_dir,
+            :"output-dir"   => output_dir,
+            :"api-version"  => api_version,
+          }
+          action = __method__.to_s.tr('_', ' ')
+          json = exec(action, flags: flags, redirection: :null_stderr)
+
+          json['result']['path']
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli/sf/sobject/core.rb

@@ -0,0 +1,48 @@
+require_relative '../core/base'
+
+module SfCli
+  module Sf
+    module Sobject
+      # ==== description
+      # The class representing *sf* *sobject*
+      #
+      # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm
+      #
+      class Core
+        include ::SfCli::Sf::Core::Base
+
+        # returns a hash object containing the Salesforce object schema. (equivalent to *sf* *sobject* *describe*)
+        #
+        # *objectType* --- object type (ex: Account)<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm#cli_reference_sobject_describe_unified]
+        #
+        def describe(object_type, target_org: nil)
+          flags    = {
+            :"sobject"    => object_type,
+            :"target-org" => target_org,
+          }
+          json = exec(__method__, flags: flags, redirection: :null_stderr)
+          json['result']
+        end
+
+        # returns a list of Salesforce object API name. (equivalent to *sf* *sobject* *list*)
+        #
+        # *object_type* --- all or custom<br>
+        # *target_org* --- an alias of paticular org, not default one<br>
+        #
+        # For more command details, see {the command reference}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm#cli_reference_sobject_list_unified]
+        #
+        def list(object_type, target_org: nil)
+          flags    = {
+            :"sobject"    => (object_type.to_sym == :custom ? :custom : :all),
+            :"target-org" => target_org,
+          }
+          json = exec(__method__, flags: flags, redirection: :null_stderr)
+          json['result']
+        end
+      end
+    end
+  end
+end

data/lib/sf_cli.rb

@@ -1 +1,16 @@
-require 'sf_cli/sf'
+require 'sf_cli/sf/main'
+#
+# the global method that represents *sf* command.
+# This is desgined as the syntax suger, which can use with similar usability to the original.
+#
+# For command details, see the {reference document}[https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_unified.htm]
+#
+# == examples
+#   # you can follow the similar syntax to the original command by using method chain.
+#
+#   sf.org.display                            # same as original command 'sf org display'
+#   sf.data.query "SELECT Name FROM Account"  # same as original command 'sf data query "SELECT Name FROM Account"`
+#
+def sf
+  SfCli::Sf::Main.instance
+end

metadata

@@ -1,31 +1,38 @@
 --- !ruby/object:Gem::Specification
 name: sf_cli
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Takanobu Maekawa
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-08-25 00:00:00.000000000 Z
+date: 2024-09-01 00:00:00.000000000 Z
 dependencies: []
-description: This is a class library for introducing Salesforce CLI.Currenty only
-  sf command is the target of development.
+description: This is a class library for introducing Salesforce CLI to Ruby scripting.
+  Currenty only sf command is the target of development.
 email: 
 executables: []
 extensions: []
 extra_rdoc_files:
 - README.rdoc
+- CHANGELOG.md
 files:
+- CHANGELOG.md
 - README.rdoc
 - lib/sf_cli.rb
-- lib/sf_cli/sf.rb
-- lib/sf_cli/sf/base.rb
-- lib/sf_cli/sf/data.rb
-- lib/sf_cli/sf/org.rb
-- lib/sf_cli/sf/project.rb
-- lib/sf_cli/sf/sobject.rb
+- lib/sf_cli/sf/core/base.rb
+- lib/sf_cli/sf/data/core.rb
+- lib/sf_cli/sf/data/helper_methods.rb
+- lib/sf_cli/sf/main.rb
+- lib/sf_cli/sf/model.rb
+- lib/sf_cli/sf/model/class_definition.rb
+- lib/sf_cli/sf/model/generator.rb
+- lib/sf_cli/sf/model/schema.rb
+- lib/sf_cli/sf/org/core.rb
+- lib/sf_cli/sf/project/core.rb
+- lib/sf_cli/sf/sobject/core.rb
 homepage: https://github.com/tmkw/sf_cli
 licenses:
 - MIT

data/lib/sf_cli/sf/base.rb

@@ -1,34 +0,0 @@
-module SfCli
-  class Sf
-    class Base
-      def initialize(_sf)
-        @sf  = _sf
-      end
-
-      private
-
-      def exec(action, flags: {}, switches: {}, redirection: nil)
-        sf.exec(category, action, flags: flags, switches: switches, redirection: redirection)
-      end
-
-      def category
-        self.class.name.split('::').last.downcase
-      end
-
-      def field_value_pairs(hash)
-        return nil if hash.nil?
-        return nil if hash.empty?
-
-        hash.each_with_object([]) do|(k,v), arr|
-          value = v.instance_of?(String) ? %|'#{v}'| : v
-          arr << %(#{k}=#{value})
-        end
-        .join(' ')
-      end
-
-      def sf
-        @sf
-      end
-    end
-  end
-end

data/lib/sf_cli/sf/data.rb

@@ -1,148 +0,0 @@
-require_relative './base'
-
-module SfCli
-  class Sf
-    #
-    # ==== description
-    # The class representing *sf* *data*
-    #
-    # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_data_commands_unified.htm
-    #
-    class Data < Base
-
-      # get object records using SQOL. (eqivalent to *sf* *data* *query*)
-      #
-      # *soql* --- SOQL<br>
-      # *target_org* --- an alias of paticular org, not default one<br>
-      # *model_class* --- the data model class representing the record object.<br> 
-      #
-      # ==== examples
-      #   sf.data.query('SELECT Id, Name From Account Limit 3') # returns an array of Hash object
-      #
-      #   Account = Struct.new(:Id, :Name)
-      #   sf.data.query('SELECT Id, Name From Account Limit 3', model_class: Account)  # returns an array of Account struct object
-      #
-      def query(soql, target_org: nil, model_class: nil)
-        flags    = {
-          :"query"    => %("#{soql}"),
-          :"target-org" => target_org,
-        }
-        json = exec(__method__, flags: flags, redirection: :null_stderr)
-
-        json['result']['records'].each_with_object([]) do |h, a|
-          h.delete "attributes"
-          a << (model_class ? model_class.new(**h) : h)
-        end
-      end
-
-      # get a object record. (eqivalent to *sf* *data* *get* *record*)
-      #
-      # *object_type* --- Object Type (ex. Account)<br>
-      # *record_id* --- id of the object<br>
-      # *where* --- hash object that is used to identify a record<br>
-      # *target_org* --- an alias of paticular org, not default one<br>
-      # *model_class* --- the data model class representing the record object.<br> 
-      #
-      # ==== examples
-      #   sf.data.get_record :Account, record_id: 'xxxxxxx'
-      #   sf.data.get_record :Account, where: {Name: 'Jonny B.Good', Country: 'USA'}
-      #
-      #   CustomObject = Struct.new(:Id, :Name)
-      #   sf.data.get_record :TheCustomObject__c, record_id: 'xxxxx', model_class: CustomObject  # returns a CustomObject struct object
-      #
-      def get_record(object_type, record_id: nil, where: nil, target_org: nil, model_class: nil)
-        where_conditions = field_value_pairs(where)
-        flags = {
-          :"sobject"    => object_type,
-          :"record-id"  => record_id,
-          :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
-          :"target-org" => target_org,
-        }
-        action = __method__.to_s.tr('_', ' ')
-        json = exec(action, flags: flags, redirection: :null_stderr)
-
-        result = json['result']
-        result.delete 'attributes'
-
-        model_class ? model_class.new(**result) : result
-      end
-
-      # update a object record. (eqivalent to *sf* *data* *update* *record*)
-      #
-      # *object_type* --- Object Type (ex. Account)<br>
-      # *record_id* --- id of the object<br>
-      # *where* --- field values that is used to identify a record<br>
-      # *values* --- field values for update<br>
-      # *target_org* --- an alias of paticular org, not default one<br>
-      #
-      # ==== examples
-      #   sf.data.update_record :Account, record_id: 'xxxxxxx', values: {Name: 'New Account Name'}
-      #   sf.data.update_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}, values: {Phone: 'xxxxx', bar: 2000}
-      #
-      def update_record(object_type, record_id: nil, where: nil, values: nil, target_org: nil)
-        where_conditions  = field_value_pairs(where)
-        field_values      = field_value_pairs(values)
-        flags = {
-          :"sobject"    => object_type,
-          :"record-id"  => record_id,
-          :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
-          :"values"     => (field_values.nil? ? nil : %|"#{field_values}"|),
-          :"target-org" => target_org,
-        }
-        action = __method__.to_s.tr('_', ' ')
-        json = exec(action, flags: flags, redirection: :null_stderr)
-
-        json['result']['id']
-      end
-
-      # create a object record. (eqivalent to *sf* *data* *create* *record*)
-      #
-      # *object_type* --- Object Type (ex. Account)<br>
-      # *values* --- field values to be assigned<br>
-      # *target_org* --- an alias of paticular org, not default one<br>
-      #
-      # ==== examples
-      #
-      #   sf.data.create_record :TheCustomObject__c, values: {Name: "John Smith", Age: 33} # creating a TheCustomObject record with name and age
-      #
-      def create_record(object_type, values: {}, target_org: nil)
-        field_values = field_value_pairs(values)
-        flags = {
-          :"sobject"    => object_type,
-          :"values"      => (field_values.nil? ? nil : %|"#{field_values}"|),
-          :"target-org" => target_org,
-        }
-        action = __method__.to_s.tr('_', ' ')
-        json = exec(action, flags: flags, redirection: :null_stderr)
-
-        json['result']['id']
-      end
-
-      # delete a object record. (eqivalent to *sf* *data* *delete* *record*)
-      #
-      # *object_type* --- Object Type (ex. Account)<br>
-      # *record_id* --- id of the object<br>
-      # *where* --- hash object that is used to identify a record<br>
-      # *target_org* --- an alias of paticular org, not default one<br>
-      #
-      # ==== examples
-      #   sf.data.delete_record :Hoge__c, record_id: 'xxxxxxx'
-      #   sf.data.delete_record :Hoge__c, where: {Name: 'Jonny B.Good', Country: 'USA'}
-      #
-      #
-      def delete_record(object_type, record_id: nil, where: nil, target_org: nil)
-        where_conditions = field_value_pairs(where)
-        flags = {
-          :"sobject"    => object_type,
-          :"record-id"  => record_id,
-          :"where"      => (where_conditions.nil? ? nil : %|"#{where_conditions}"|),
-          :"target-org" => target_org,
-        }
-        action = __method__.to_s.tr('_', ' ')
-        json = exec(action, flags: flags, redirection: :null_stderr)
-
-        json['result']['id']
-      end
-    end
-  end
-end

data/lib/sf_cli/sf/org.rb

@@ -1,49 +0,0 @@
-require_relative './base'
-
-module SfCli
-  class Sf
-    #
-    # ==== description
-    # The class representing *sf* *org*.
-    #
-    # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_org_commands_unified.htm
-    #
-    class Org < Base
-      ConnectionInfo = Struct.new(:id, :access_token, :alias, :instance_url, :user_name, :api_version, :status)
-
-      # login to the org by the browser. (equivalent to *sf* *org* *login* *web*)
-      #
-      # *target_org* --- an alias of paticular org, not default one<br>
-      # *instance_url* --- custom login url.
-      #
-      def login_web(target_org: nil, instance_url: nil)
-        flags    = {
-          :"alias"        => target_org,
-          :"instance-url" => instance_url,
-        }
-        action = __method__.to_s.tr('_', ' ')
-        exec(action, flags: flags)
-      end
-
-      #
-      # returns the org's connection information. (equivalent to *sf* *org* *display*)
-      #
-      # *target_org* --- an alias of paticular org, not default one<br>
-      #
-      def display(target_org: nil)
-        flags    = {:"target-org" => target_org}
-        json = exec(__method__, flags: flags, redirection: :null_stderr)
-
-        ConnectionInfo.new(
-          id:           json['result']['id'],
-          access_token: json['result']['accessToken'],
-          alias:        json['result']['alias'],
-          instance_url: json['result']['instanceUrl'],
-          user_name:    json['result']['username'],
-          api_version:  json['result']['apiVersion'],
-          status:       json['result']['connectedStatus']
-        )
-      end
-    end
-  end
-end

data/lib/sf_cli/sf/project.rb

@@ -1,68 +0,0 @@
-require_relative './base'
-
-module SfCli
-  class Sf
-    # ==== description
-    # The class representing *sf* *project*
-    #
-    # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_project_commands_unified.htm
-    #
-    class Project < Base
-      GenerateResult = Struct.new(:output_dir, :files, :raw_output, :warnings)
-
-      #
-      # generate a Salesforce project. (equivalent to *sf* *project* *generate*)
-      #
-      # *name*        --- project name<br>
-      # *template*    --- project template name<br>
-      # *output_dir*  --- output directory<br>
-      # *manifest*    --- switch to create manifest file in the project directory (manifest/package.xml). default: false
-      #
-      def generate(name, manifest: false, template: nil, output_dir: nil)
-        flags    = {
-          :name         => name,
-          :template     => template,
-          :"output-dir" => output_dir,
-        }
-        switches = {
-          manifest: manifest,
-        }
-        json = exec(__method__, flags: flags, switches: switches, redirection: :null_stderr)
-
-        GenerateResult.new(
-          output_dir: json['result']['outputDir'],
-          files:      json['result']['created'],
-          raw_output: json['result']['rawOutput'],
-          warnings:   json['warnings']
-        )
-      end
-
-      # generate the manifest file of a Salesforce project. (equivalent to *sf* *project* *generate* *manifest*)
-      #
-      # *metadata*    --- an array that consists of metadata type like CustomObject, Layout and so on.  (default: [])<br>
-      # *api_verson*  --- api version (default: nil)<br>
-      # *output_dir*  --- manifest's output directory in the project directory. You can use relative path from the project root (default: nil)<br>
-      # *from_org*    --- username or alias of the org that contains the metadata components from which to build a manifest (default: nil)<br>
-      # *source_dir*  --- paths to the local source files to include in the manifest (default: nil)
-      #
-      # ==== examples
-      #   sf.project.generate_manifest metadata: %w[CustomObject Layout]  # creates a package.xml, which is initialized with CustomObject and Layout
-      #   sf.project.generate_manifest from_org: <org_name>               # creates a package.xml, which is initialized with all metadata types in the org
-      #
-      def generate_manifest(name: nil, output_dir: nil, api_version: nil, metadata: [], from_org: nil, source_dir: nil)
-        flags    = {
-          :name           => name,
-          :"metadata"     => (metadata.empty? ? nil : metadata.join(' ')),
-          :"from-org"     => from_org,
-          :"source-dir"   => source_dir,
-          :"output-dir"   => output_dir,
-          :"api-version"  => api_version,
-        }
-        action = __method__.to_s.tr('_', ' ')
-        json = exec(action, flags: flags, redirection: :null_stderr)
-
-        json['result']['path']
-      end
-    end
-  end
-end

data/lib/sf_cli/sf/sobject.rb

@@ -1,41 +0,0 @@
-require_relative './base'
-
-module SfCli
-  class Sf
-    # ==== description
-    # The class representing *sf* *sobject*
-    #
-    # command reference: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_sobject_commands_unified.htm
-    #
-    class Sobject < Base
-
-      # returns a hash object containing the Salesforce object schema. (equivalent to *sf* *sobject* *describe*)
-      #
-      # *objectType* --- object type (ex: Account)<br>
-      # *target_org* --- an alias of paticular org, not default one<br>
-      #
-      def describe(object_type, target_org: nil)
-        flags    = {
-          :"sobject"    => object_type,
-          :"target-org" => target_org,
-        }
-        json = exec(__method__, flags: flags, redirection: :null_stderr)
-        json['result']
-      end
-
-      # returns a list of Salesforce object API name. (equivalent to *sf* *sobject* *list*)
-      #
-      # *object_type* --- all or custom<br>
-      # *target_org* --- an alias of paticular org, not default one<br>
-      #
-      def list(object_type, target_org: nil)
-        flags    = {
-          :"sobject"    => (object_type.to_sym == :custom ? :custom : :all),
-          :"target-org" => target_org,
-        }
-        json = exec(__method__, flags: flags, redirection: :null_stderr)
-        json['result']
-      end
-    end
-  end
-end

data/lib/sf_cli/sf.rb

@@ -1,87 +0,0 @@
-require 'json'
-
-module SfCli
-  # ==== description
-  # The main class of *sf* command.
-  #
-  # https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_unified.htm
-  #
-  # ==== examples
-  #  sf = SfCli::Sf.new # use default org
-  #
-  #  # get the org connection infomation, as same as 'sf org display'
-  #  sf.org.display
-  #
-  #  # get Account records (equivalent to 'sf data query')
-  #  sf.data.query 'SELECT Id, Name FROM Account LIMIT 3' # => returns an array containing 3 records
-  #
-  class Sf
-    OPERATION_CATEGORIES = %w[Org Sobject Data Project]
-
-    # load each operation class and define as a attribute
-    OPERATION_CATEGORIES.each do |category|
-      require_relative %(sf/#{category.downcase})
-      attr_reader category.downcase.to_sym
-    end
-
-    attr_reader :varbose
-
-    def initialize
-      OPERATION_CATEGORIES.each do |category|
-        instance_variable_set(:"@#{category.downcase}", Object.const_get(%|::SfCli::Sf::#{category}|).new(self))
-      end
-    end
-
-    def exec(category, action, flags: {}, switches: {}, redirection: nil)
-      cmd = %|sf #{category} #{action}#{as_flag_options(flags)}#{as_switch_options(switches)}#{redirect redirection}|
-
-      puts cmd if varbose
-
-      json = JSON.parse `#{cmd}`
-
-      puts json if varbose
-
-      raise StandardError.new(json['message']) if json['status'] != 0
-
-      json
-    end
-
-    private
-
-    def as_flag_options(hash)
-      flag_options   = hash.map{|k,v| flag k, v}.reject(&:nil?).join(' ')
-      flag_options   = ' ' + flag_options unless flag_options.empty?
-
-      flag_options
-    end
-
-    def as_switch_options(hash)
-      ' ' + {json: true}.merge(hash).each_with_object([]){|(k,v), arr| arr << %(--#{k}) if v}.join(' ')
-    end
-
-    def flag(name, arg)
-      arg ? %(--#{name} #{arg}) : nil
-    end
-
-    def os
-      @os ||= ENV['OS']
-    end
-
-    def redirect(option)
-      case option
-      when :null_stderr
-        null_stderr_redirection
-      else
-      end
-    end
-
-    def null_stderr_redirection
-      @null_stderr_redirection ||=
-        if os.eql?('Windows_NT')
-          ' 2>nul'
-        else
-          ' 2> /dev/null'
-        end
-    end
-  end
-end