1. Coding guideline

This article details the syntax, methodology and good practices recommended to code in nbz.

Browser setup

It is mandatory to setup our web browser with the browser engine and the user agent we want to use. Here you can find all supported browsers and user-agents:

Supported browsers and user_agents

# Setting up the browser

engine = 'chrome';
user_agent = 'default';
headless = True;


browser(engine, user_agent, headless);

Language features

Semi-colon

All sentences must end with semicolon " ; ".

Data types

Integer
Float
String
Boolean
List
File
WebElement

# Declaring variables

int_var = 15;

float_var = 15.1;

single_string_var = 'foo';
double_string_var = "bar";

boolean_var_true = true;

list = [];
list = [1, 2, 3, 'foo', 'bar', True];
append(list, 4);
append(list, 'test');

file = open('test.txt', 'r');

table = get_element(table_xpath);

Expressions operators

Precedence is not implemented. Use parentheses to feature it.

Arithmetic:

Operation Meaning

x + y Add / concate

x - y Difference

x * y Product

x / y Division

- x x negated

NOTE: Integer will be converted to string when concatenate both types.

Logical:

Operation Meaning

x > y x greater than y

x >= y x greater than or equal to y

x < y x less than y

x <= y x less than or equal to y

x == y x equal to y

x != y x not equal to y

Boolean:

Operation

not x

x and y

x or y

Flow control structures

Conditional statements

If statement

if (condition){ #if code } [elif{ #elif code ] [ else{ #else code } ]

  # If statement

  num = 100;

  cond = 2 > 1;

  if(cond and num==100){
    #if code
  }
  elif(true){
    #elif code
  }
  else{
    #else code
  }

Loops

For loop
- Foreach
  
  for (ID(string) in ID(file)) { #code }
  
  This for is like a foreach loop. It iterates for all lines in a text file. Only allows files to iterate for the moment. It is mandatory to declare the variable you will use in the foreach before it.
```
  # Foreach loop

  url_list = open('NBZ/test/url_list.txt', 'r');

  url = '';

  for (url in url_list){
    get_url(url);
  }
```
- Explicit for
  
  for (start(integer), end(integer), mode){ #sentences }
  
  Available modes:
  
  Operator Meaning
  
  + Increase one position per iteration
  
  ++ Increase two positions per iteration
  
  - Decrease one position per iteration
  
  -- Decrease two positions per iteration
```
  # For loop

  for(0, 10, +){
    #code
  }
```

While loop

wile (condition){ #code }

  # While loop

  i = 0;
  while(i < 3){
    #code
    i = i + 1;
  }

Functions

Data types functions

int (parameter1(float | string))

Cast to integer type.
- parameter 1 -> value | variable to cast
```
  # Int casting

  a = 15.0;
  a = int(a);

  b = '15';
  b = int(b);
```
float (parameter1(integer | string))

Casto to float type.
- parameter 1 -> value | variable to cast
```
  # Float casting

  a = 15;
  a = float(a);

  b = '15.0';
  b = float(b);
```
str (parameter1(integer | float))

Cast to string type.
- parameter 1 -> value | variable to cast
```
  # String casting

  a = 15;
  a = str(a);

  b = 15.0;
  b = str(b);
```
sub_str (parameter1(string), parameter2(integer), [parameter3(integer)])

This function returns substring from bigger string. It allows reverse substring.
- parameter 1 -> string to substring
- parameter 2 -> initial character
- parameter 3 -> final character (optional). If you don't define last character, it will fo to the last one.
```
  # Sub string function

  a = 'github NBZ';

  b = sub_str(a, 0, 6);
  print(b); # -> github
```
len (parameter1(string))

This function returns the lenght of a compatible data type.
- parameter 1 -> value | variable
```
  # Len function

  a = 'Use NBZ';
  l = len(a);

  print(l); # -> 7
```
find (parameter1(string), parameter2(string))

This function returns the position where the substring is found. If don't exists, it returns -1.
- parameter 1 -> string where you want search
- parameter 2 -> string you want to find
```
  # Find function

  a = 'Use NBZ'

  f = find(a, 'Use '); # -> 0

  f = find(a, 'NBZ'); # -> 4

  f = find(a, 'foobar'); # -> -1
```
append (parameter1(list), parameter2(data))

This function add data at the end of the list.
- parameter 1 -> list to you want to add data
- parameter 2 -> data you want to add
```
  # Append function

  list = [];

  append(list, 1);

  append(list, 2);

  print(list); # -> [1, 2]
```
remove (parameter1(list), parameter2(data))

This function remove data from a list. If list contains duplicated data, like [1, 2, 1], this function will remove the first found element, in this case the first '1'.
- parameter 1 -> list from you want to remove data
- parameter 2 -> data you want to remove
```
  # Remove function

  list = [1, 2, 3, 1]

  remove(list, 2)

  print(list); # -> [1, 3, 1]

  remove(list, 1)

  print(list); # -> [3, 1]
```

User functions

User functions can be defined with the following sintax:

# User function definition

def my_function(){
        # code
}

# User function call

my_function();

NOTE: User functions does not allow parameters. All variables are global variables.

Built-in functions

Some built-in functions use xpath to interact with the web pages.

What is xpath?: # TODO url to xpath explanation

Basic functions
- browser (parameter1(string), parameter2(string))
  
  This function init the web browser
  - parameter 1 -> browser engine
  - parameter 2 -> user-agent
```
  browser('chrome', 'Opera on Mac');
```
- get_url (parameter1(string))
  
  Browser load the url
  - parameter -> target url
```
  get_url('http://www.github.com/zurdi15/NBZ');
```
- fill (parameter1(string), parameter2(integer) | (string) | (special-key), ..., parameterN(string) | (integer) | (special-key))
  
  Fill the element (usually a field) with given parameters. Also, NB provides you some keywords to emulate special keys.
  - parameter 1 -> field xpath
  - parameter 2 to parameter N -> list of inputs (strings or special keys)
  - Special keys:
    - ENTER
    - ESC
    - TAB
    - RETURN
```
  fill(field_xpath, 'foobar');
  fill(field_xpath, 'foo', 'bar', 'ENTER');
```
- clear (parameter1(string))
  
  This function clear the text field.
  - parameter 1 -> element xpath
```
  # Clear function

  clear(field_xpath);
```
- click (parameter1(string))
  
  This function clicks any element of the web page.
  - parameter 1 -> element xpath
```
  # Click function

  click(button_xpath);
```
- select (parameter1(string), parameter2(string))
  
  This function allow the user to select an option from a selector.
  - parameter 1 -> selector xpath
  - parameter 2 -> option xpath
```
  # Select function

  select(selector_xpath, option_xpath );
```
- wait (parameter1(integer))
  
  This function allows the user to wait X seconds before resuming the script.
  - parameter 1 -> seconds
```
  # Wait function

  wait(10);
```
- back ()
  
  This function allows the user to go back in the navigation history
```
  # Back function

  back();
```
- forward ()
  
  This function allows the user to go forward in the navigation history
```
  # Forward function

  forward();
```
- refresh ()
  
  This function allows the user to refresh the web page
```
  # Refresh function

  refresh();
```
- get_text (parameter1(string))
  
  This function get the visible text from a web page element.
  - parameter 1 -> element xpath
```
  # Get text function

  table_text = get_text(table_xpath);
```
- current_url ()
  
  This functions returns current browser url
```
  # Current url function

  browser('chrome', 'Opera on Mac);

  get_url('https://www.github.com/zurdi15/NBZ');

  cu = current_url();

  print(cu); # -> 'https://www.github.com/zurdi15/NBZ'
```
Sniffering functions
- check_net (parameter1(string), parameter2(string), ..., parameterN(string))
  
  This function allows the user to check if a network request has been made correctly. The user can choose to check requests using multiple parameters, a single word or a sentence.
  - parameter 1 -> type:
    - 'params'
    - 'keyword'
  - parameter 2 -> value to catch from the request. This function allow the following values:
    - request_ok -> returns boolean (True if request found, False if dont)
    - url -> url where the request was found
    - status_code -> request status code
    - timestamp -> request timestamp -parameter 3 to parameter N-1 -> list of parameters or keyword in a single request
  NOTE: keyword mode only allows one keyword
```
  # Check_net function

  req_ok = check_net('params', 'request_ok', 'q=github');
  req_url = check_net('params', 'url', 'q=github');
  req_status_code = check_net('params', 'status_code', 'q=github');
  req_timestamp = check_net('params', 'timestamp', 'q=github');
```
- export_net_report (parameter1(string))
  
  This function enables to save a complete net report of the bot script session on a .csv.
  - parameter 1 -> name to store the report. It will be stored at out/net_reports/{script_name}/complete_net_log_{parameter1}.csv
```
  # Export net report function

  browser('chrome', 'Chrome on Windows');

  export_net_report('test'); # stored at out/net_reports/{script_name}/complete_net_log_test.csv
```
- reset_har ()
  
  This function reset the HAR log (http request log to check petitions with check_net())
```
  # Reset HAR function

  browser('chrome', 'Chrome on Ubuntu');

  get_url('https://www.github.com/zurdi5/NBZ');

  check_net('params', 'status_code', 'q=github');

  reset_har();

  get_url('https://www.github.com/zurdi5/');

  check_net('params', 'status_code', 'q=github');
```
Advanced functions
- print (parameter1(string))
  
  Basic print function
  - parameter 1 -> something to print
```
  # Print function

  a = 10;
  b = ' times';

  print('Hello ' + a + b);

  $> Hello 10 times
```
- random (parameter1(integer), parameter2(integer))
  
  This function returns one random integer number between two limits.
  - parameter 1 -> initial limit random number
  - parameter 2 -> final limit random number
```
  # Random function

  num = random(0, 10);

  print(num);   # 6
```
- get_timestamp ([parameter1(string)])
  
  This function returns actual system timestamp. Without parameters, it returns complete timestamp as: year-month-day hour:minute:second
  
  With parameters, you can configure the output like:
  - %Y -> year
  - %m -> month
  - %d -> day
  - %H -> hour
  - %M -> minute
  - %S -> second
  - etc...
  Also you can construct your string parameter with other characters.
  - parameter 1 -> configuration string [optional]
```
  # Get timestamp function

  ts = get_timestamp();

  print(ts); # -> 2018-01-19 10:15:15


  ts2 = get_timestamp('%H:%M:%S');

  print(ts2); # -> 10:15:16
```
- timestamp_diff (parameter1(string), parameter2(string))
  
  This function returns the difference by subtracting two dates. Both dates must be like: %Y-%m-%d %H:%M:%S to be subtracted.
  - parameter 1 -> date 1 (string)
  - parameter 2 -> date 2 (string)
```
  # Timestamp diff function

  d1 = check_net('params', 'q=github', 'timestamp');
  d2 = get_timestamp();

  dif = timestamp_diff(d2, d1);
```
- open (parameter1(string), parameter2(string))
  
  This function open a file to use it in your script.
  - parameter 1 -> file path
  - parameter 2 -> mode
    - 'r' -> read mode
    - 'w' -> write mode (remove previous content of the file)
    - 'a' -> append mode (write just at the end of the file, keeping previous content)
```
  # Open function

  url_list = open('NBZ/test/url_list.txt', 'r');
```
- write (parameter1(file), parameter2(string))
  
  This function allows the user to write into a file. We need first to open the file in 'w' or 'a' mode. Writing '\n' write next in a new line.
  - parameter 1 -> file variable
  - parameter 2 -> value to write
```
  # Write function

  file = open('NBZ/test/url_list.txt', 'w');
  write(file, 'github' + '\n' + 'zurdi15');
```
- write_table_as_csv (parameter1(webelement), parameter2(file), parameter3(string), parameter4(string), parameter5(string))
  
  This function allows the user to write a table from a web into a csv format. Additionally, you can add some columns to the left of the table.
  - parameter 1 -> table (web element)
  - parameter 2 -> file (.csv where you will write)
  - parameter 3 -> csv delimiter
  - parameter 4 -> columns to add at left
  - parameter 5 -> columns to add at right
```
  # Write table as csv function

  file= open('NBZ/test/url_list.txt', 'w');

  table = get_element('table_xpath');

  write_table_as_csv(table, file, '|', 'col1|col2|', '|col7|col8');
```
- close (parameter1(file))
  
  This function close one file previously opened. Designed to close the file before reopen it in other mode.
  - parameter 1 -> file variable
```
  # Close function

  write_list = open('NBZ/test/url_list.txt', 'w');
  write(write_list, 'https://www.google.es' + '\n' +
                  'https://www.google.fr' + '\n' +
                  'https://www.google.it');

  close(write_list); # Close before reopen

  url_list = open('NBZ/test/url_list.txt', 'r');
```
- get_local_storage (parameter1(string))
  
  This functions allows the user to get a value from a local storage variable. This function only works with the current site you are in the browser.
  - parameter 1 -> local storage variable name
```
  # Set_local_storage function

  set_local_storage('var_ls', 'foobar');
```
- set_local_storage (parameter1(string), parameter2(string | integer))
  
  This function allows the user to set a value into a local storage variable. This function only works with the current site you are in the browser.
  - parameter 1 -> local storage variable name
  - parameter 2 -> value
```
  # Set_local_storage function

  set_local_storage('var_ls', 'foobar');
```
- get_cookie (parameter1(string))
  
  This functions allows the user to get a value from a cookie. This function only works with the current site you are in the browser.
  - parameter 1 -> cookie name
```
  # Get cookie function

  cookie = get_cookie('cookie_1');
```
- set_cookie (parameter1(string), parameter2(string | integer))
  
  This function allows the user to set a value into a cookie. This function only works with the current site you are in the browser.
  - parameter 1 -> cookie name
  - parameter 2 -> value
```
  # Set cookie function

  set_cookie('cookie_1', 'cookie_value');
```
- get_element (parameter1(string))
  
  This function returns a web element object from the web page.
  - parameter 1 -> web element xpath
```
  # Get element function

  table = get_element(table_xpath);
```
- children_num (parameter1(webelement))
  
  This function returns the number of children of a web element.
  - parameter 1 -> web element
```
  # Children num function

  selector = get_element(selector_xpath);

  options = children_num(selector);
```
- page_load_time ()
  
  This functions returns the time it takes the page to load in seconds.
```
  # Page load time function

  browser('Chrome on Windows');
  get_url('https://www.github.com/zurdi15/NBZ');

  time = page_load_time();
```
- scroll_to_bottom ()
  
  This function scrolls to the bottom of the web page.
```
  # Scroll to bottom function

  get_url('https://www.github.com/zurdi15/NBZ');

  scroll_to_bottom();
```
- scroll_to_top ()
  
  This function scrolls to the top of the web page.
```
  # Scroll to top function

  get_url('https://www.github.com/zurdi15/NBZ');

  scroll_to_top();
```
- execute_js (parameter1(string))
  
  This function allows the user to execute javascript into the browser, getting or setting anything. Also you can interact with the web like buttons, iframes, etc)
  - parameter 1 -> command to execute
```
  # Execute javascript function

  kuid = execute_js('return localStorage.getItem("var_ls")');

  execute_js('localStorage.setItem("var_ls", "foobar")');
```
- export_source_html (parameter1(string))
  
  This function save the html from the current web page.
  - parameter 1 -> path where user can save the html
```
  # Get source html function

  get_url('https://www.github.com/zurdi15/NBZ');

  get_source_html('/path/github_nbz.html');
  # -> saved on /path/github_nbz.html
```
- get_element_html (parameter1(string))
  
  This function returns the html code of a web element
  - parameter 1 -> web element xpath
```
  # Get element html

  html = get_element_html(element_xpath);
```
- screenshot (parameter1(string), parameter2(string))
  
  This function save a screenshot of the browser on its current state. This is useful to track in a visual way each step of the script.
  - parameter 1 -> path where user can save the screenshot
  - parameter 2 -> screenshot file name (file will be saved as .png format)
```
  # Screenshot function

  get_url('https://www.github.com/zurdi15/NBZ');

  screenshot('/path', 'github_nbz');
  # -> saved on /path/github_nbz.png
```
- wait_for_downloads ()
  
  This function wait for all the running downloads.
  
  NOTE: Only chrome is supported.
```
  # Wait for downloads function

  browser('chrome', 'default');

  get_url('https://github.com/zurdi15/NBZ/archive/master.zip');

  wait_for_downloads();
```
- get_environment_variable (parameter1(string))
  
  This function get the value of an environment variable.
  - parameter 1 -> name of the environment variable
```
  # Get environment variable function

  env_var = get_environment_variable('MY_ENV_VAR');
```
- get_parameter (parameter1(integer))
  
  This function returns the value of the script parameters.
  - parameter 1 -> index of the script parameter
```
  $>./nbz -s my_script.nbz -p "My script parameter"

  # Get parameter function

  env_var = get_parameter(0);

  # -> env_var = "My script parameter"
```

Feel free to improve or suggest anything about this software.

Home

Coding guideline

Browser setup
Languaje Features
- Semi-colon
- Data types
- Expression operators
- Flow control structures
  - If
  - For
  - While
- Data types functions
  - int
  - float
  - str
  - sub_str
  - len
  - find
  - append
  - remove
- User functions
- Built-in functions
  - Basic functions
    
    browser
    
    get_url
    
    fill
    
    clear
    
    click
    
    select
    
    wait
    
    back
    
    forward
    
    refresh
    
    get_text
    
    current_url
  - Sniffering functions
    
    check_net
    
    export_net_report
    
    reset_har
  - Advanced functions
    
    print
    
    random
    
    get_timestamp
    
    timestamp_diff
    
    open
    
    write
    
    write_table_as_csv
    
    close
    
    get_local_storage
    
    set_local_storage
    
    get_cookie
    
    set_cookie
    
    get_element
    
    children_num
    
    page_load_time
    
    scroll_to_bottom
    
    scroll_to_top
    
    execute_js
    
    export_source_html
    
    get_element_html
    
    screenshot
    
    wait_for_downloads
    
    get_environment_variable
    
    get_parameter

Browser engines and user agents

Script examples

Known bugs

Operation	Meaning
x + y	Add / concate
x - y	Difference
x * y	Product
x / y	Division
- x	x negated

Operation	Meaning
x > y	x greater than y
x >= y	x greater than or equal to y
x < y	x less than y
x <= y	x less than or equal to y
x == y	x equal to y
x != y	x not equal to y

Operator	Meaning
+	Increase one position per iteration
++	Increase two positions per iteration
-	Decrease one position per iteration
--	Decrease two positions per iteration

1. Coding guideline

Browser setup

Language features

Semi-colon

Data types

Expressions operators

Arithmetic:

Logical:

Boolean:

Flow control structures

Conditional statements

If statement

Loops

For loop

While loop

Functions

Data types functions

int (parameter1(float | string))

float (parameter1(integer | string))

str (parameter1(integer | float))

sub_str (parameter1(string), parameter2(integer), [parameter3(integer)])

len (parameter1(string))

find (parameter1(string), parameter2(string))

append (parameter1(list), parameter2(data))

remove (parameter1(list), parameter2(data))

User functions

Built-in functions

Basic functions

browser (parameter1(string), parameter2(string))

get_url (parameter1(string))

fill (parameter1(string), parameter2(integer) | (string) | (special-key), ..., parameterN(string) | (integer) | (special-key))

clear (parameter1(string))

click (parameter1(string))

select (parameter1(string), parameter2(string))

wait (parameter1(integer))

back ()

forward ()

refresh ()

get_text (parameter1(string))

current_url ()

Sniffering functions

check_net (parameter1(string), parameter2(string), ..., parameterN(string))

export_net_report (parameter1(string))

reset_har ()

Advanced functions

print (parameter1(string))

random (parameter1(integer), parameter2(integer))

get_timestamp ([parameter1(string)])

timestamp_diff (parameter1(string), parameter2(string))

open (parameter1(string), parameter2(string))

write (parameter1(file), parameter2(string))

write_table_as_csv (parameter1(webelement), parameter2(file), parameter3(string), parameter4(string), parameter5(string))

close (parameter1(file))

get_local_storage (parameter1(string))

set_local_storage (parameter1(string), parameter2(string | integer))

get_cookie (parameter1(string))

set_cookie (parameter1(string), parameter2(string | integer))

get_element (parameter1(string))

children_num (parameter1(webelement))

page_load_time ()

scroll_to_bottom ()

scroll_to_top ()

execute_js (parameter1(string))

export_source_html (parameter1(string))

get_element_html (parameter1(string))

screenshot (parameter1(string), parameter2(string))

wait_for_downloads ()

get_environment_variable (parameter1(string))

get_parameter (parameter1(integer))

Clone this wiki locally