<commit_before>BirstConnect_Command
====================

Ruby script used to generalize running Birst commands.

Don't use this, it's still in very early stages of development.


ToDo:

* Intent - bare bones ruby and CL interface to Birst
* Basic usage examples (take from test)
* Explanation of camelcase
* Helper functions<commit_msg>README updates<commit_after>Birst_Command
====================

Birst Command is a Ruby gem that allows you to build Ruby scripts that interface
with the Birst Web API.


# Installation & Setup

Install the gem using `gem install Birst_Command` or using rvm or rbenv as you prefer.

After installing, you'll need to create a Birst Command config file that contains
the credentials you'll use to connect to Birst.  This config file should look like,

    {
        "wsdl": "https://login.bws.birst.com/CommandWebService.asmx?WSDL",
        "endpoint": "https://login.bws.birst.com/CommandWebService.asmx",
        "username": "<EMAIL>",
        "password": "<PASSWORD>"
    }

Most users should only need to modify the username and password.  Since I have a strong
aversion to storing passwords in plaintext, the password in the config file needs to
be an obfuscated password.  Birst Command comes with a password obfuscator that can be
executed via

    $ obfuscate_pwd.rb mypassword
    0x8GOZ5nA3oRSSS8ao1l6Q==

Copy and paste the obfuscated password into the config file and **save
to a secure location**.  If any attacker is able to get your
obfuscated password and knows it was created using this program, it
would be trivial to get your Birst login credentials.


# Usage

In your Ruby program, include the Birst Command gem and load the config file via

    require 'rubygems'
    require 'bundler/setup'
    require 'Birst_Command'

    Birst_Command::Config.read_config(File.join(File.dirname(__FILE__),"config.json"))

Birst commands are submitted in 


### camelCase/snake_case issues

Birst Command uses [Savon](http://savonrb.com/version2/client.html) as
the underlying framework used to communicate with the Birst SOAP API.
Savon expects commands in snake_case format and converts them into
camelCase when submitted to the Birst API (e.g., `list_spaces` is
converted to `listSpaces`).  This behavior is *not* configurable.
Savon also has options for converting the arguments of parameters from
snake_case into camelCase.  Unfortunately, the Birst Web API is not
entirely consistent in its use of camelCase for arguments (e.g.,
`spaceId` is used in `deleteSpace` but `spaceID` is used in
`listUsersInSpace`).  This inconsistency requires us to **submit
commands as snake_case and arguments as the camelCase that Birst
uses.**


ToDo:

* Basic usage examples (take from test)
* Helper functions
{'fraction_non_alphanumeric': 0.07619394823186293, 'fraction_numerical': 0.002916514764855997, 'mean_word_length': 4.3803921568627455, 'pattern_counts': {'":': 4, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1806157', 'n_tokens_mistral': 802, 'n_tokens_neox': 758, 'n_words': 349}