selectpdf 1.3.0 → 1.4.0

data/lib/selectpdf.rb

@@ -5,16 +5,172 @@ require 'json'
 require 'fileutils'
 
 #
-# SelectPdf Online REST API Ruby client library. Contains a powerful HTML to PDF converter.
+# SelectPdf Online REST API Ruby client library. Contains HTML to PDF converter, PDF merge, PDF to text extractor, search PDF.
 #
 #
 # Convert HTML to PDF
 #
-# {include:file:samples/simple_url_to_pdf.rb}
+#  require 'selectpdf'
+#  print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+#
+#  url = 'https://selectpdf.com'
+#  local_file = 'Test.pdf'
+#  api_key = 'Your API key here'
+#
+#  begin
+#    api = SelectPdf::HtmlToPdfClient.new(api_key)
+#
+#    api.page_size = SelectPdf::PageSize::A4
+#    api.margins = 0
+#    api.page_numbers = FALSE
+#    api.page_breaks_enhanced_algorithm = TRUE
+#
+#    api.convert_url_to_file(url, local_file)
+#  rescue SelectPdf::ApiException => e
+#    print("An error occurred: #{e}")
+#  end
+#
+# Merge PDFs from local disk or public url and save result into a file on disk.
+#
+#  require 'selectpdf'
+#
+#  $stdout.sync = true
+#  
+#  print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+#  
+#  test_url = 'https://selectpdf.com/demo/files/selectpdf.pdf'
+#  test_pdf = 'Input.pdf'
+#  local_file = 'Result.pdf'
+#  api_key = 'Your API key here'
+#  
+#  begin
+#    client = SelectPdf::PdfMergeClient.new(api_key)
+#  
+#    # set parameters - see full list at https://selectpdf.com/pdf-merge-api/
+#  
+#    # specify the pdf files that will be merged (order will be preserved in the final pdf)
+#    client.add_file(test_pdf) # add PDF from local file
+#    client.add_url_file(test_url) # add PDF from public url
+#    # client.add_file(test_pdf, 'pdf_password') # add PDF (that requires a password) from local file
+#    # client.add_url_file(test_url, 'pdf_password') # add PDF (that requires a password) from public url
+#  
+#    print "Starting pdf merge ...\n"
+#  
+#    # merge pdfs to local file
+#    client.save_to_file(local_file)
+#  
+#    # merge pdfs to memory
+#    # pdf = client.save
+#  
+#    print "Finished! Number of pages: #{client.number_of_pages}.\n"
+#  
+#    # get API usage
+#    usage_client = SelectPdf::UsageClient.new(api_key)
+#    usage = usage_client.get_usage(FALSE)
+#    print("Usage: #{usage}\n")
+#    print('Conversions remained this month: ', usage['available'], "\n")
+#  rescue SelectPdf::ApiException => e
+#    print("An error occurred: #{e}")
+#  end
+#
+# Extract text from PDF
+#
+#  require 'selectpdf'
+#
+#  $stdout.sync = true
+#
+#  print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+#
+#  test_url = 'https://selectpdf.com/demo/files/selectpdf.pdf'
+#  test_pdf = 'Input.pdf'
+#  local_file = 'Result.txt'
+#  api_key = 'Your API key here'
+#
+#  begin
+#    client = SelectPdf::PdfToTextClient.new(api_key)
+#
+#    # set parameters - see full list at https://selectpdf.com/pdf-to-text-api/
+#    client.start_page = 1 # start page (processing starts from here)
+#    client.end_page = 0 # end page (set 0 to process file til the end)
+#    client.output_format = SelectPdf::OutputFormat::TEXT # set output format (Text or HTML)
+#
+#    print "Starting pdf to text ...\n"
+#
+#    # convert local pdf to local text file
+#    client.text_from_file_to_file(test_pdf, local_file)
+#
+#    # extract text from local pdf to memory
+#    # text = client.text_from_file(test_pdf)
+#    # print text
+#
+#    # convert pdf from public url to local text file
+#    # client.text_from_url_to_file(test_url, local_file)
+#
+#    # extract text from pdf from public url to memory
+#    # text = client.text_from_url(test_url)
+#    # print text
+#
+#    print "Finished! Number of pages processed: #{client.number_of_pages}.\n"
+#
+#    # get API usage
+#    usage_client = SelectPdf::UsageClient.new(api_key)
+#    usage = usage_client.get_usage(FALSE)
+#    print("Usage: #{usage}\n")
+#    print('Conversions remained this month: ', usage['available'], "\n")
+#  rescue SelectPdf::ApiException => e
+#    print("An error occurred: #{e}")
+#  end
+#
+# Search Pdf
+#
+#    require 'selectpdf'
+#
+#    $stdout.sync = true
+#    
+#    print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+#    
+#    test_url = 'https://selectpdf.com/demo/files/selectpdf.pdf'
+#    test_pdf = 'Input.pdf'
+#    api_key = 'Your API key here'
+#    
+#    begin
+#      client = SelectPdf::PdfToTextClient.new(api_key)
+#    
+#      # set parameters - see full list at https://selectpdf.com/pdf-to-text-api/
+#      client.start_page = 1 # start page (processing starts from here)
+#      client.end_page = 0 # end page (set 0 to process file til the end)
+#      client.output_format = SelectPdf::OutputFormat::TEXT # set output format (Text or HTML)
+#    
+#      print "Starting search pdf ...\n"
+#    
+#      # search local pdf
+#      results = client.search_file(test_pdf, 'pdf')
+#    
+#      # search pdf from public url
+#      # results = client.search_url(test_url, 'pdf')
+#    
+#      print "Search results: #{results}.\nSearch results count: #{results.length}\n"
+#    
+#      print "Finished! Number of pages processed: #{client.number_of_pages}.\n"
+#    
+#      # get API usage
+#      usage_client = SelectPdf::UsageClient.new(api_key)
+#      usage = usage_client.get_usage(FALSE)
+#      print("Usage: #{usage}\n")
+#      print('Conversions remained this month: ', usage['available'], "\n")
+#    rescue SelectPdf::ApiException => e
+#      print("An error occurred: #{e}")
+#    end
+#
 module SelectPdf
+  # Multipart/form-data boundary
   MULTIPART_FORM_DATA_BOUNDARY = '------------SelectPdf_Api_Boundry_$'
+
+  # New line
   NEW_LINE = "\r\n"
-  CLIENT_VERSION = '1.3.0'
+
+  # Library version
+  CLIENT_VERSION = '1.4.0'
 
   attr_reader :code, :message
   #
@@ -470,7 +626,70 @@ module SelectPdf
   #
   # Code sample:
   #
-  # {include:file:samples/html_to_pdf_main.rb}
+  #  require 'selectpdf'
+  #
+  #  $stdout.sync = true
+  #  
+  #  print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+  #  
+  #  url = 'https://selectpdf.com'
+  #  local_file = 'Test.pdf'
+  #  api_key = 'Your API key here'
+  #  
+  #  begin
+  #    client = SelectPdf::HtmlToPdfClient.new(api_key)
+  #  
+  #    # set parameters - see full list at https://selectpdf.com/html-to-pdf-api/
+  #  
+  #    client.page_size = SelectPdf::PageSize::A4 # PDF page size
+  #    client.page_orientation = SelectPdf::PageOrientation::PORTRAIT # PDF page orientation
+  #    client.margins = 0 # PDF page margins
+  #    client.rendering_engine = SelectPdf::RenderingEngine::WEBKIT # rendering engine
+  #    client.conversion_delay = 1 # conversion delay
+  #    client.navigation_timeout = 30 # navigation timeout
+  #    client.page_numbers = FALSE # page numbers
+  #    client.page_breaks_enhanced_algorithm = TRUE # enhanced page break algorithm
+  #  
+  #    # additional properties
+  #  
+  #    # client.use_css_print = TRUE # enable CSS media print
+  #    # client.disable_javascript = TRUE # disable javascript
+  #    # client.disable_internal_links = TRUE # disable internal links
+  #    # client.disable_external_links = TRUE # disable external links
+  #    # client.keep_images_together = TRUE # keep images together
+  #    # client.scale_images = TRUE # scale images to create smaller pdfs
+  #    # client.single_page_pdf = TRUE # generate a single page PDF
+  #    # client.user_password = 'password' # secure the PDF with a password
+  #  
+  #    # generate automatic bookmarks
+  #  
+  #    # client.pdf_bookmarks_selectors = 'H1, H2' # create outlines (bookmarks) for the specified elements
+  #    # client.viewer_page_mode = SelectPdf::PageMode::USE_OUTLINES # display outlines (bookmarks) in viewer
+  #  
+  #    print "Starting conversion ...\n"
+  #  
+  #    # convert url to file
+  #    client.convert_url_to_file(url, local_file)
+  #  
+  #    # convert url to memory
+  #    # pdf = client.convert_url(url)
+  #  
+  #    # convert html string to file
+  #    # client.convert_html_string_to_file('This is some <b>html</b>.', local_file)
+  #  
+  #    # convert html string to memory
+  #    # pdf = client.convert_html_string('This is some <b>html</b>.')
+  #  
+  #    print "Finished! Number of pages: #{client.number_of_pages}.\n"
+  #  
+  #    # get API usage
+  #    usage_client = SelectPdf::UsageClient.new(api_key)
+  #    usage = usage_client.get_usage(FALSE)
+  #    print("Usage: #{usage}\n")
+  #    print('Conversions remained this month: ', usage['available'], "\n")
+  #  rescue SelectPdf::ApiException => e
+  #    print("An error occurred: #{e}")
+  #  end
   class HtmlToPdfClient < ApiClient
     # Construct the Html To Pdf Client.
     #
@@ -1525,4 +1744,880 @@ module SelectPdf
       return nil
     end
   end
+
+  # Pdf Merge with SelectPdf Online API.
+  #
+  # Code sample:
+  #
+  #  require 'selectpdf'
+  #
+  #  $stdout.sync = true
+  #  
+  #  print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+  #  
+  #  test_url = 'https://selectpdf.com/demo/files/selectpdf.pdf'
+  #  test_pdf = 'Input.pdf'
+  #  local_file = 'Result.pdf'
+  #  api_key = 'Your API key here'
+  #  
+  #  begin
+  #    client = SelectPdf::PdfMergeClient.new(api_key)
+  #  
+  #    # set parameters - see full list at https://selectpdf.com/pdf-merge-api/
+  #  
+  #    # specify the pdf files that will be merged (order will be preserved in the final pdf)
+  #    client.add_file(test_pdf) # add PDF from local file
+  #    client.add_url_file(test_url) # add PDF from public url
+  #    # client.add_file(test_pdf, 'pdf_password') # add PDF (that requires a password) from local file
+  #    # client.add_url_file(test_url, 'pdf_password') # add PDF (that requires a password) from public url
+  #  
+  #    print "Starting pdf merge ...\n"
+  #  
+  #    # merge pdfs to local file
+  #    client.save_to_file(local_file)
+  #  
+  #    # merge pdfs to memory
+  #    # pdf = client.save
+  #  
+  #    print "Finished! Number of pages: #{client.number_of_pages}.\n"
+  #  
+  #    # get API usage
+  #    usage_client = SelectPdf::UsageClient.new(api_key)
+  #    usage = usage_client.get_usage(FALSE)
+  #    print("Usage: #{usage}\n")
+  #    print('Conversions remained this month: ', usage['available'], "\n")
+  #  rescue SelectPdf::ApiException => e
+  #    print("An error occurred: #{e}")
+  #  end
+  class PdfMergeClient < ApiClient
+    # Construct the Pdf Merge Client.
+    #
+    # @param api_key API Key.
+    def initialize(api_key)
+      super()
+      @api_endpoint = 'https://selectpdf.com/api2/pdfmerge/'
+      @parameters['key'] = api_key
+
+      @file_idx = 0
+    end
+
+    # Add local PDF document to the list of input files.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @param user_password User password for the PDF document (optional).
+    def add_file(input_pdf, user_password = nil)
+      @file_idx += 1
+
+      @files["file_#{@file_idx}"] = input_pdf
+      @parameters.delete("url_#{@file_idx}")
+
+      if user_password.nil? || user_password.empty?
+        @parameters.delete("password_#{@file_idx}")
+      else
+        @parameters["password_#{@file_idx}"] = user_password
+      end
+    end
+
+    # Add remote PDF document to the list of input files.
+    #
+    # @param input_url Url of a remote PDF file.
+    # @param user_password User password for the PDF document (optional).
+    def add_url_file(input_url, user_password = nil)
+      @file_idx += 1
+
+      @parameters["url_#{@file_idx}"] = input_url
+      @files.delete("file_#{@file_idx}")
+
+      if user_password.nil? || user_password.empty?
+        @parameters.delete("password_#{@file_idx}")
+      else
+        @parameters["password_#{@file_idx}"] = user_password
+      end
+    end
+
+    # Merge all specified input pdfs and return the resulted PDF.
+    #
+    # @return Byte array containing the resulted PDF.
+    def save
+      @parameters['async'] = 'False'
+      @parameters['files_no'] = @file_idx
+
+      result = perform_post_as_multipart_formdata
+
+      @file_idx = 0
+      @files = {}
+
+      result
+    end
+
+    # Merge all specified input pdfs and writes the resulted PDF to a specified stream.
+    #
+    # @param stream The output stream where the resulted PDF will be written.
+    def save_to_stream(stream)
+      result = save
+      stream.write(result)
+    end
+
+    # Merge all specified input pdfs and writes the resulted PDF to a local file.
+    #
+    # @param file_path Local file including path if necessary.
+    def save_to_file(file_path)
+      result = save
+      File.open(file_path, 'wb') do |file|
+        file.write(result)
+      end
+    rescue ApiException
+      FileUtils.rm(file_path) if File.exist?(file_path)
+      raise
+    end
+
+    # Merge all specified input pdfs and return the resulted PDF. An asynchronous call is used.
+    #
+    # @return Byte array containing the resulted PDF.
+    def save_async
+      @parameters['files_no'] = @file_idx
+
+      job_id = start_async_job_multipart_form_data
+
+      if job_id.nil? || job_id.empty?
+        raise ApiException.new('An error occurred launching the asynchronous call.'), 'An error occurred launching the asynchronous call.'
+      end
+
+      no_pings = 0
+
+      while no_pings < @async_calls_max_pings
+        no_pings += 1
+
+        # sleep for a few seconds before next ping
+        sleep(@async_calls_ping_interval)
+
+        async_job_client = AsyncJobClient.new(@parameters['key'], @job_id)
+        async_job_client.api_endpoint = @api_async_endpoint
+
+        result = async_job_client.result
+
+        next if result.nil?
+
+        @number_of_pages = async_job_client.number_of_pages
+        @file_idx = 0
+        @files = {}
+
+        return result
+      end
+
+      @file_idx = 0
+      @files = {}
+
+      raise ApiException.new('Asynchronous call did not finish in expected timeframe.'), 'Asynchronous call did not finish in expected timeframe.'
+    end
+
+    # Merge all specified input pdfs and writes the resulted PDF to a specified stream. An asynchronous call is used.
+    #
+    # @param stream The output stream where the resulted PDF will be written.
+    def save_to_stream_async(stream)
+      result = save_async
+      stream.write(result)
+    end
+
+    # Merge all specified input pdfs and writes the resulted PDF to a local file. An asynchronous call is used.
+    #
+    # @param file_path Local file including path if necessary.
+    def save_to_file_async(file_path)
+      result = save_async
+      File.open(file_path, 'wb') do |file|
+        file.write(result)
+      end
+    rescue ApiException
+      FileUtils.rm(file_path) if File.exist?(file_path)
+      raise
+    end
+
+    # Set the PDF document title.
+    #
+    # @param doc_title Document title.
+    def doc_title=(doc_title)
+      @parameters['doc_title'] = doc_title
+    end
+
+    # Set the subject of the PDF document.
+    #
+    # @param doc_subject Document subject.
+    def doc_subject=(doc_subject)
+      @parameters['doc_subject'] = doc_subject
+    end
+
+    # Set the PDF document keywords.
+    #
+    # @param doc_keywords Document keywords.
+    def doc_keywords=(doc_keywords)
+      @parameters['doc_keywords'] = doc_keywords
+    end
+
+    # Set the name of the PDF document author.
+    #
+    # @param doc_author Document author.
+    def doc_author=(doc_author)
+      @parameters['doc_author'] = doc_author
+    end
+
+    # Add the date and time when the PDF document was created to the PDF document information. The default value is False.
+    #
+    # @param doc_add_creation_date Add creation date to the document metadata or not.
+    def doc_add_creation_date=(doc_add_creation_date)
+      @parameters['doc_add_creation_date'] = doc_add_creation_date
+    end
+
+    # Set the page layout to be used when the document is opened in a PDF viewer. The default value is SelectPdf::PageLayout::ONE_COLUMN.
+    #
+    # @param viewer_page_layout Page layout. Possible values: 0 (Single Page), 1 (One Column), 2 (Two Column Left), 3 (Two Column Right).
+    # Use constants from SelectPdf::PageLayout class.
+    def viewer_page_layout=(viewer_page_layout)
+      unless [0, 1, 2, 3].include?(viewer_page_layout)
+        raise ApiException.new('Allowed values for Page Layout: 0 (Single Page), 1 (One Column), 2 (Two Column Left), 3 (Two Column Right).'), 'Allowed values for Page Layout: 0 (Single Page), 1 (One Column), 2 (Two Column Left), 3 (Two Column Right).'
+      end
+
+      @parameters['viewer_page_layout'] = viewer_page_layout
+    end
+
+    # Set the document page mode when the pdf document is opened in a PDF viewer. The default value is SelectPdf::PageMode::USE_NONE.
+    #
+    # @param viewer_page_mode Page mode. Possible values: 0 (Use None), 1 (Use Outlines), 2 (Use Thumbs), 3 (Full Screen), 4 (Use OC), 5 (Use Attachments).
+    # Use constants from SelectPdf::PageMode class.
+    def viewer_page_mode=(viewer_page_mode)
+      unless [0, 1, 2, 3, 4, 5].include?(viewer_page_mode)
+        raise ApiException.new('Allowed values for Page Mode: 0 (Use None), 1 (Use Outlines), 2 (Use Thumbs), 3 (Full Screen), 4 (Use OC), 5 (Use Attachments).'),
+              'Allowed values for Page Mode: 0 (Use None), 1 (Use Outlines), 2 (Use Thumbs), 3 (Full Screen), 4 (Use OC), 5 (Use Attachments).'
+      end
+
+      @parameters['viewer_page_mode'] = viewer_page_mode
+    end
+
+    # Set a flag specifying whether to position the document's window in the center of the screen. The default value is False.
+    #
+    # @param viewer_center_window Center window or not.
+    def viewer_center_window=(viewer_center_window)
+      @parameters['viewer_center_window'] = viewer_center_window
+    end
+
+    # Set a flag specifying whether the window's title bar should display the document title taken from document information. The default value is False.
+    #
+    # @param viewer_display_doc_title Display title or not.
+    def viewer_display_doc_title=(viewer_display_doc_title)
+      @parameters['viewer_display_doc_title'] = viewer_display_doc_title
+    end
+
+    # Set a flag specifying whether to resize the document's window to fit the size of the first displayed page. The default value is False.
+    #
+    # @param viewer_fit_window Fit window or not.
+    def viewer_fit_window=(viewer_fit_window)
+      @parameters['viewer_fit_window'] = viewer_fit_window
+    end
+
+    # Set a flag specifying whether to hide the pdf viewer application's menu bar when the document is active. The default value is False.
+    #
+    # @param viewer_hide_menu_bar Hide menu bar or not.
+    def viewer_hide_menu_bar=(viewer_hide_menu_bar)
+      @parameters['viewer_hide_menu_bar'] = viewer_hide_menu_bar
+    end
+
+    # Set a flag specifying whether to hide the pdf viewer application's tool bars when the document is active. The default value is False.
+    #
+    # @param viewer_hide_toolbar Hide tool bars or not.
+    def viewer_hide_toolbar=(viewer_hide_toolbar)
+      @parameters['viewer_hide_toolbar'] = viewer_hide_toolbar
+    end
+
+    # Set a flag specifying whether to hide user interface elements in the document's window (such as scroll bars and navigation controls), leaving only the document's contents displayed.
+    #
+    # @param viewer_hide_window_ui Hide window UI or not.
+    def viewer_hide_window_ui=(viewer_hide_window_ui)
+      @parameters['viewer_hide_window_ui'] = viewer_hide_window_ui
+    end
+
+    # Set PDF user password.
+    #
+    # @param user_password PDF user password.
+    def user_password=(user_password)
+      @parameters['user_password'] = user_password
+    end
+
+    # Set PDF owner password.
+    #
+    # @param owner_password PDF owner password.
+    def owner_password=(owner_password)
+      @parameters['owner_password'] = owner_password
+    end
+
+    # Set the maximum amount of time (in seconds) for this job.
+    # The default value is 30 seconds. Use a larger value (up to 120 seconds allowed) for large documents.
+    #
+    # @param timeout Timeout in seconds.
+    def timeout=(timeout)
+      @parameters['timeout'] = timeout
+    end
+
+    # Set a custom parameter. Do not use this method unless advised by SelectPdf.
+    #
+    # @param parameter_name Parameter name.
+    # @param parameter_value Parameter value.
+    def set_custom_parameter(parameter_name, parameter_value)
+      @parameters[parameter_name] = parameter_value
+    end
+  end
+
+  # Pdf To Text Conversion with SelectPdf Online API.
+  #
+  # Code Sample for PDF To Text
+  #
+  #  require 'selectpdf'
+  #
+  #  $stdout.sync = true
+  #
+  #  print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+  #
+  #  test_url = 'https://selectpdf.com/demo/files/selectpdf.pdf'
+  #  test_pdf = 'Input.pdf'
+  #  local_file = 'Result.txt'
+  #  api_key = 'Your API key here'
+  #
+  #  begin
+  #    client = SelectPdf::PdfToTextClient.new(api_key)
+  #
+  #    # set parameters - see full list at https://selectpdf.com/pdf-to-text-api/
+  #    client.start_page = 1 # start page (processing starts from here)
+  #    client.end_page = 0 # end page (set 0 to process file til the end)
+  #    client.output_format = SelectPdf::OutputFormat::TEXT # set output format (Text or HTML)
+  #
+  #    print "Starting pdf to text ...\n"
+  #
+  #    # convert local pdf to local text file
+  #    client.text_from_file_to_file(test_pdf, local_file)
+  #
+  #    # extract text from local pdf to memory
+  #    # text = client.text_from_file(test_pdf)
+  #    # print text
+  #
+  #    # convert pdf from public url to local text file
+  #    # client.text_from_url_to_file(test_url, local_file)
+  #
+  #    # extract text from pdf from public url to memory
+  #    # text = client.text_from_url(test_url)
+  #    # print text
+  #
+  #    print "Finished! Number of pages processed: #{client.number_of_pages}.\n"
+  #
+  #    # get API usage
+  #    usage_client = SelectPdf::UsageClient.new(api_key)
+  #    usage = usage_client.get_usage(FALSE)
+  #    print("Usage: #{usage}\n")
+  #    print('Conversions remained this month: ', usage['available'], "\n")
+  #  rescue SelectPdf::ApiException => e
+  #    print("An error occurred: #{e}")
+  #  end
+  #
+  # Code Sample for Search Pdf
+  #
+  #    require 'selectpdf'
+  #
+  #    $stdout.sync = true
+  #    
+  #    print "This is SelectPdf-#{SelectPdf::CLIENT_VERSION}\n"
+  #    
+  #    test_url = 'https://selectpdf.com/demo/files/selectpdf.pdf'
+  #    test_pdf = 'Input.pdf'
+  #    api_key = 'Your API key here'
+  #    
+  #    begin
+  #      client = SelectPdf::PdfToTextClient.new(api_key)
+  #    
+  #      # set parameters - see full list at https://selectpdf.com/pdf-to-text-api/
+  #      client.start_page = 1 # start page (processing starts from here)
+  #      client.end_page = 0 # end page (set 0 to process file til the end)
+  #      client.output_format = SelectPdf::OutputFormat::TEXT # set output format (Text or HTML)
+  #    
+  #      print "Starting search pdf ...\n"
+  #    
+  #      # search local pdf
+  #      results = client.search_file(test_pdf, 'pdf')
+  #    
+  #      # search pdf from public url
+  #      # results = client.search_url(test_url, 'pdf')
+  #    
+  #      print "Search results: #{results}.\nSearch results count: #{results.length}\n"
+  #    
+  #      print "Finished! Number of pages processed: #{client.number_of_pages}.\n"
+  #    
+  #      # get API usage
+  #      usage_client = SelectPdf::UsageClient.new(api_key)
+  #      usage = usage_client.get_usage(FALSE)
+  #      print("Usage: #{usage}\n")
+  #      print('Conversions remained this month: ', usage['available'], "\n")
+  #    rescue SelectPdf::ApiException => e
+  #      print("An error occurred: #{e}")
+  #    end
+  #
+  class PdfToTextClient < ApiClient
+    # Construct the Pdf To Text Client.
+    #
+    # @param api_key API Key.
+    def initialize(api_key)
+      super()
+      @api_endpoint = 'https://selectpdf.com/api2/pdftotext/'
+      @parameters['key'] = api_key
+
+      @file_idx = 0
+    end
+
+    # Get the text from the specified pdf.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @return Extracted text.
+    def text_from_file(input_pdf)
+      @parameters['async'] = 'False'
+      @parameters['action'] = 'Convert'
+      @parameters.delete('url')
+
+      @files = {}
+      @files['inputPdf'] = input_pdf
+
+      perform_post_as_multipart_formdata
+    end
+
+    # Get the text from the specified pdf and write it to the specified text file.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @param output_file_path The output file where the resulted text will be written.
+    def text_from_file_to_file(input_pdf, output_file_path)
+      result = text_from_file(input_pdf)
+      File.open(output_file_path, 'wb') do |file|
+        file.write(result)
+      end
+    rescue ApiException
+      FileUtils.rm(output_file_path) if File.exist?(output_file_path)
+      raise
+    end
+
+    # Get the text from the specified pdf and write it to the specified stream.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @param stream The output stream where the resulted PDF will be written.
+    def text_from_file_to_stream(input_pdf, stream)
+      result = text_from_file(input_pdf)
+      stream.write(result)
+    end
+
+    # Get the text from the specified pdf with an asynchronous call.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @return Extracted text.
+    def text_from_file_async(input_pdf)
+      @parameters['action'] = 'Convert'
+      @parameters.delete('url')
+
+      @files = {}
+      @files['inputPdf'] = input_pdf
+
+      job_id = start_async_job_multipart_form_data
+
+      if job_id.nil? || job_id.empty?
+        raise ApiException.new('An error occurred launching the asynchronous call.'), 'An error occurred launching the asynchronous call.'
+      end
+
+      no_pings = 0
+
+      while no_pings < @async_calls_max_pings
+        no_pings += 1
+
+        # sleep for a few seconds before next ping
+        sleep(@async_calls_ping_interval)
+
+        async_job_client = AsyncJobClient.new(@parameters['key'], @job_id)
+        async_job_client.api_endpoint = @api_async_endpoint
+
+        result = async_job_client.result
+
+        next if result.nil?
+
+        @number_of_pages = async_job_client.number_of_pages
+
+        return result
+      end
+
+      raise ApiException.new('Asynchronous call did not finish in expected timeframe.'), 'Asynchronous call did not finish in expected timeframe.'
+    end
+
+    # Get the text from the specified pdf with an asynchronous call and write it to the specified text file.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @param output_file_path The output file where the resulted text will be written.
+    def text_from_file_to_file_async(input_pdf, output_file_path)
+      result = text_from_file_async(input_pdf)
+      File.open(output_file_path, 'wb') do |file|
+        file.write(result)
+      end
+    rescue ApiException
+      FileUtils.rm(output_file_path) if File.exist?(output_file_path)
+      raise
+    end
+
+    # Get the text from the specified pdf with an asynchronous call and write it to the specified stream.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @param stream The output stream where the resulted PDF will be written.
+    def text_from_file_to_stream_async(input_pdf, stream)
+      result = text_from_file_async(input_pdf)
+      stream.write(result)
+    end
+
+    # Get the text from the specified pdf.
+    #
+    # @param url Address of the PDF file.
+    # @return Extracted text.
+    def text_from_url(url)
+      if !url.downcase.start_with?('http://') && !url.downcase.start_with?('https://')
+        raise ApiException.new('The supported protocols for the PDFs available online are http:// and https://.'),
+              'The supported protocols for the PDFs available online are http:// and https://.'
+      end
+
+      if url.downcase.start_with?('http://localhost')
+        raise ApiException.new('Cannot convert local urls via this method. Use getTextFromFile instead.'),
+              'Cannot convert local urls via this method. Use text_from_file instead.'
+      end
+
+      @parameters['async'] = 'False'
+      @parameters['action'] = 'Convert'
+
+      @files = {}
+      @parameters['url'] = url
+
+      perform_post_as_multipart_formdata
+    end
+
+    # Get the text from the specified pdf and write it to the specified text file.
+    #
+    # @param url Address of the PDF file.
+    # @param output_file_path The output file where the resulted text will be written.
+    def text_from_url_to_file(url, output_file_path)
+      result = text_from_url(url)
+      File.open(output_file_path, 'wb') do |file|
+        file.write(result)
+      end
+    rescue ApiException
+      FileUtils.rm(output_file_path) if File.exist?(output_file_path)
+      raise
+    end
+
+    # Get the text from the specified pdf and write it to the specified stream.
+    #
+    # @param url Address of the PDF file.
+    # @param stream The output stream where the resulted PDF will be written.
+    def text_from_url_to_stream(url, stream)
+      result = text_from_url(url)
+      stream.write(result)
+    end
+
+    # Get the text from the specified pdf with an asynchronous call.
+    #
+    # @param url Address of the PDF file.
+    # @return Extracted text.
+    def text_from_url_async(url)
+      if !url.downcase.start_with?('http://') && !url.downcase.start_with?('https://')
+        raise ApiException.new('The supported protocols for the PDFs available online are http:// and https://.'),
+              'The supported protocols for the PDFs available online are http:// and https://.'
+      end
+
+      if url.downcase.start_with?('http://localhost')
+        raise ApiException.new('Cannot convert local urls via this method. Use getTextFromFile instead.'),
+              'Cannot convert local urls via this method. Use text_from_file_async instead.'
+      end
+
+      @parameters['action'] = 'Convert'
+
+      @files = {}
+      @parameters['url'] = url
+
+      job_id = start_async_job_multipart_form_data
+
+      if job_id.nil? || job_id.empty?
+        raise ApiException.new('An error occurred launching the asynchronous call.'), 'An error occurred launching the asynchronous call.'
+      end
+
+      no_pings = 0
+
+      while no_pings < @async_calls_max_pings
+        no_pings += 1
+
+        # sleep for a few seconds before next ping
+        sleep(@async_calls_ping_interval)
+
+        async_job_client = AsyncJobClient.new(@parameters['key'], @job_id)
+        async_job_client.api_endpoint = @api_async_endpoint
+
+        result = async_job_client.result
+
+        next if result.nil?
+
+        @number_of_pages = async_job_client.number_of_pages
+
+        return result
+      end
+
+      raise ApiException.new('Asynchronous call did not finish in expected timeframe.'),
+            'Asynchronous call did not finish in expected timeframe.'
+    end
+
+    # Get the text from the specified pdf with an asynchronous call and write it to the specified text file.
+    #
+    # @param url Address of the PDF file.
+    # @param output_file_path The output file where the resulted text will be written.
+    def text_from_url_to_file_async(url, output_file_path)
+      result = text_from_url_async(url)
+      File.open(output_file_path, 'wb') do |file|
+        file.write(result)
+      end
+    rescue ApiException
+      FileUtils.rm(output_file_path) if File.exist?(output_file_path)
+      raise
+    end
+
+    # Get the text from the specified pdf with an asynchronous call and write it to the specified stream.
+    #
+    # @param url Address of the PDF file.
+    # @param stream The output stream where the resulted PDF will be written.
+    def text_from_url_to_stream_async(url, stream)
+      result = text_from_url_async(url)
+      stream.write(result)
+    end
+
+    # Search for a specific text in a PDF document.
+    # Pages that participate to this operation are specified by start_page and end_page methods.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @param text_to_search Text to search.
+    # @param case_sensitive If the search is case sensitive or not.
+    # @param whole_words_only If the search works on whole words or not.
+    # @return List with text positions in the current PDF document.
+    def search_file(input_pdf, text_to_search, case_sensitive = FALSE, whole_words_only = FALSE)
+      if text_to_search.nil? || text_to_search.empty?
+        raise ApiException.new('Search text cannot be empty.'), 'Search text cannot be empty.'
+      end
+
+      @parameters['async'] = 'False'
+      @parameters['action'] = 'Search'
+      @parameters.delete('url')
+      @parameters['search_text'] = text_to_search
+      @parameters['case_sensitive'] = case_sensitive
+      @parameters['whole_words_only'] = whole_words_only
+
+      @files = {}
+      @files['inputPdf'] = input_pdf
+
+      @headers['Accept'] = 'text/json'
+
+      result = perform_post_as_multipart_formdata
+      return [] if result.nil? || result.empty?
+
+      JSON.parse(result)
+    end
+
+    # Search for a specific text in a PDF document with an asynchronous call.
+    # Pages that participate to this operation are specified by start_page and end_page methods.
+    #
+    # @param input_pdf Path to a local PDF file.
+    # @param text_to_search Text to search.
+    # @param case_sensitive If the search is case sensitive or not.
+    # @param whole_words_only If the search works on whole words or not.
+    # @return List with text positions in the current PDF document.
+    def search_file_async(input_pdf, text_to_search, case_sensitive = FALSE, whole_words_only = FALSE)
+      if text_to_search.nil? || text_to_search.empty?
+        raise ApiException.new('Search text cannot be empty.'), 'Search text cannot be empty.'
+      end
+
+      @parameters['action'] = 'Search'
+      @parameters.delete('url')
+      @parameters['search_text'] = text_to_search
+      @parameters['case_sensitive'] = case_sensitive
+      @parameters['whole_words_only'] = whole_words_only
+
+      @files = {}
+      @files['inputPdf'] = input_pdf
+
+      @headers['Accept'] = 'text/json'
+
+      job_id = start_async_job_multipart_form_data
+
+      if job_id.nil? || job_id.empty?
+        raise ApiException.new('An error occurred launching the asynchronous call.'),
+              'An error occurred launching the asynchronous call.'
+      end
+
+      no_pings = 0
+
+      while no_pings < @async_calls_max_pings
+        no_pings += 1
+
+        # sleep for a few seconds before next ping
+        sleep(@async_calls_ping_interval)
+
+        async_job_client = AsyncJobClient.new(@parameters['key'], @job_id)
+        async_job_client.api_endpoint = @api_async_endpoint
+
+        result = async_job_client.result
+
+        next if result.nil?
+
+        @number_of_pages = async_job_client.number_of_pages
+        return [] if result.empty?
+
+        return JSON.parse(result)
+      end
+
+      raise ApiException.new('Asynchronous call did not finish in expected timeframe.'),
+            'Asynchronous call did not finish in expected timeframe.'
+    end
+
+    # Search for a specific text in a PDF document.
+    # Pages that participate to this operation are specified by start_page and end_page methods.
+    #
+    # @param url Address of the PDF file.
+    # @param text_to_search Text to search.
+    # @param case_sensitive If the search is case sensitive or not.
+    # @param whole_words_only If the search works on whole words or not.
+    # @return List with text positions in the current PDF document.
+    def search_url(url, text_to_search, case_sensitive = FALSE, whole_words_only = FALSE)
+      if text_to_search.nil? || text_to_search.empty?
+        raise ApiException.new('Search text cannot be empty.'), 'Search text cannot be empty.'
+      end
+
+      @parameters['async'] = 'False'
+      @parameters['action'] = 'Search'
+      @parameters['search_text'] = text_to_search
+      @parameters['case_sensitive'] = case_sensitive
+      @parameters['whole_words_only'] = whole_words_only
+
+      @files = {}
+      @parameters['url'] = url
+
+      @headers['Accept'] = 'text/json'
+
+      result = perform_post_as_multipart_formdata
+      return [] if result.nil? || result.empty?
+
+      JSON.parse(result)
+    end
+
+    # Search for a specific text in a PDF document with an asynchronous call.
+    # Pages that participate to this operation are specified by start_page and end_page methods.
+    #
+    # @param url Address of the PDF file.
+    # @param text_to_search Text to search.
+    # @param case_sensitive If the search is case sensitive or not.
+    # @param whole_words_only If the search works on whole words or not.
+    # @return List with text positions in the current PDF document.
+    def search_url_async(url, text_to_search, case_sensitive = FALSE, whole_words_only = FALSE)
+      if text_to_search.nil? || text_to_search.empty?
+        raise ApiException.new('Search text cannot be empty.'), 'Search text cannot be empty.'
+      end
+
+      @parameters['action'] = 'Search'
+      @parameters['search_text'] = text_to_search
+      @parameters['case_sensitive'] = case_sensitive
+      @parameters['whole_words_only'] = whole_words_only
+
+      @files = {}
+      @parameters['url'] = url
+
+      @headers['Accept'] = 'text/json'
+
+      job_id = start_async_job_multipart_form_data
+
+      if job_id.nil? || job_id.empty?
+        raise ApiException.new('An error occurred launching the asynchronous call.'),
+              'An error occurred launching the asynchronous call.'
+      end
+
+      no_pings = 0
+
+      while no_pings < @async_calls_max_pings
+        no_pings += 1
+
+        # sleep for a few seconds before next ping
+        sleep(@async_calls_ping_interval)
+
+        async_job_client = AsyncJobClient.new(@parameters['key'], @job_id)
+        async_job_client.api_endpoint = @api_async_endpoint
+
+        result = async_job_client.result
+
+        next if result.nil?
+
+        @number_of_pages = async_job_client.number_of_pages
+        return [] if result.empty?
+
+        return JSON.parse(result)
+      end
+
+      raise ApiException.new('Asynchronous call did not finish in expected timeframe.'),
+            'Asynchronous call did not finish in expected timeframe.'
+    end
+
+    # Set Start Page number. Default value is 1 (first page of the document).
+    #
+    # @param start_page Start page number (1-based).
+    def start_page=(start_page)
+      @parameters['start_page'] = start_page
+    end
+
+    # Set End Page number. Default value is 0 (process till the last page of the document).
+    #
+    # @param end_page End page number (1-based).
+    def end_page=(end_page)
+      @parameters['end_page'] = end_page
+    end
+
+    # Set PDF user password.
+    #
+    # @param user_password PDF user password.
+    def user_password=(user_password)
+      @parameters['user_password'] = user_password
+    end
+
+    # Set the text layout. The default value is SelectPdf::TextLayout::ORIGINAL.
+    #
+    # @param text_layout The text layout. Possible values: Original, Reading. Use constants from SelectPdf::TextLayout class.
+    def text_layout=(text_layout)
+      unless [0, 1].include?(text_layout)
+        raise ApiException.new('Allowed values for Text Layout: 0 (Original), 1 (Reading).'), 'Allowed values for Text Layout: 0 (Original), 1 (Reading).'
+      end
+
+      @parameters['text_layout'] = text_layout
+    end
+
+    # Set the output format. The default value is SelectPdf::OutputFormat::TEXT.
+    #
+    # @param output_format The output format. Possible values: Text, Html. Use constants from SelectPdf::OutputFormat class.
+    def output_format=(output_format)
+      unless [0, 1].include?(output_format)
+        raise ApiException.new('Allowed values for Output Format: 0 (Text), 1 (Html).'), 'Allowed values for Output Format: 0 (Text), 1 (Html).'
+      end
+
+      @parameters['output_format'] = output_format
+    end
+
+    # Set the maximum amount of time (in seconds) for this job.
+    # The default value is 30 seconds. Use a larger value (up to 120 seconds allowed) for large documents.
+    #
+    # @param timeout Timeout in seconds.
+    def timeout=(timeout)
+      @parameters['timeout'] = timeout
+    end
+
+    # Set a custom parameter. Do not use this method unless advised by SelectPdf.
+    #
+    # @param parameter_name Parameter name.
+    # @param parameter_value Parameter value.
+    def set_custom_parameter(parameter_name, parameter_value)
+      @parameters[parameter_name] = parameter_value
+    end
+  end
 end