Add samples (#64)

* Change Namespace to Libproxy

* Add samples

Fixes: https://github.com/janbrummer/libproxy2/issues/33

9 files changed, 113 insertions, 127 deletions

diff --git a/docs/build-howto.md b/docs/build-howto.md
deleted file mode 100644
index 7ce0ef5..0000000
--- a/docs/build-howto.md
+++ /dev/null
@@ -1,123 +0,0 @@
-Title: Compiling with Libproxy
-Slug: building
-
-# Compiling with Libproxy
-
-The current stable API provides a small synchronous function set which makes it easy to add it to existing application and libraries.
-
-The following example is written in C but can be translated as well to every other programming language thanks to gobject-introspection. Furthermore there are
-several language samples provided in 'docs/samples' and also linked here in this main documentation.
-
-## Initialization
-
-First of all libproxy needs to be initialized. This is done with:
-
-```
-/**
- * px_proxy_factory_new:
- *
- * Creates a new pxProxyFactory instance. This instance should be kept
- * around as long as possible as it contains cached data to increase
- * performance.  Memory usage should be minimal (cache is small) and the
- * cache lifespan is handled automatically.
- *
- * @return A new pxProxyFactory instance or NULL on error
- */
-pxProxyFactory *px_proxy_factory_new (void);
-```
-
-## Get proxy information
-
-Determining whether a proxy server is need to access a given url use `px_proxy_factory_get_proxies`:
-
-```
-/**
- * px_proxy_factory_get_proxies:
- * @self: a #pxProxyFactpry
- * @url: Get proxxies for specificed URL
- *
- * Get which proxies to use for the specified URL.
- *
- * A NULL-terminated array of proxy strings is returned.
- * If the first proxy fails, the second should be tried, etc...
- * Don't forget to free the strings/array when you are done.
- * If an unrecoverable error occurs, this function returns NULL.
- *
- * Regarding performance: this method always blocks and may be called
- * in a separate thread (is thread-safe).  In most cases, the time
- * required to complete this function call is simply the time required
- * to read the configuration (i.e. from gconf, kconfig, etc).
- *
- * In the case of PAC, if no valid PAC is found in the cache (i.e.
- * configuration has changed, cache is invalid, etc), the PAC file is
- * downloaded and inserted into the cache. This is the most expensive
- * operation as the PAC is retrieved over the network. Once a PAC exists
- * in the cache, it is merely a javascript invocation to evaluate the PAC.
- * One should note that DNS can be called from within a PAC during
- * javascript invocation.
- *
- * In the case of WPAD, WPAD is used to automatically locate a PAC on the
- * network.  Currently, we only use DNS for this, but other methods may
- * be implemented in the future.  Once the PAC is located, normal PAC
- * performance (described above) applies.
- *
- * The format of the returned proxy strings are as follows:
- *   - http://[username:password@]proxy:port
- *   - socks://[username:password@]proxy:port
- *   - socks5://[username:password@]proxy:port
- *   - socks4://[username:password@]proxy:port
- *   - <procotol>://[username:password@]proxy:port
- *   - direct://
- * Please note that the username and password in the above URLs are optional
- * and should be use to authenticate the connection if present.
- *
- * For SOCKS proxies, when the protocol version is specified (socks4:// or
- * socks5://), it is expected that only this version is used. When only
- * socks:// is set, the client MUST try SOCKS version 5 protocol and, on
- * connection failure, fallback to SOCKS version 4.
- *
- * Other proxying protocols may exist. It is expected that the returned
- * configuration scheme shall match the network service name of the
- * proxy protocol or the service name of the protocol being proxied if the
- * previous does not exist. As an example, on Mac OS X you can configure a
- * RTSP streaming proxy. The expected returned configuration would be:
- *   - rtsp://[username:password@]proxy:port
- *
- * To free the returned value, call px_proxy_factory_free_proxies.
- *
- * @url The URL we are trying to reach
- * @return A NULL-terminated array of proxy strings to use
- */
-char **px_proxy_factory_get_proxies (pxProxyFactory *self, const char *url);
-```
-
-## Freeing proxy list
-
-Ensure unused proxy information is freed after user with `px_proxy_factory_free_proxies`:
-
-```
-/**
- * px_proxy_factory_free_proxies
- * @proxies: proxie array
- *
- * Frees the proxy array returned by px_proxy_factory_get_proxies when no
- * longer used.
- *
- * @since 0.4.16
- */
-void px_proxy_factory_free_proxies (char **proxies);
-```
-
-## Destruction
-
-To close and destroy the `pxProxyFactory` make use of:
-
-```
-/**
- * px_proxy_factory_free:
- * @self: a #pxProxyFactory
- *
- * Frees the pxProxyFactory instance when no longer used.
- */
-void px_proxy_factory_free (pxProxyFactory *self);
-```
diff --git a/docs/meson.build b/docs/meson.build
index a468de9..556a13d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -2,7 +2,10 @@ if get_option('docs')
 
 expand_content_md_files = [
   'configuration-logic.md',
-  'build-howto.md',
+  'perl.md',
+  'python.md',
+  'ruby.md',
+  'vala.md',
 ]
 
 toml_data = configuration_data()
diff --git a/docs/perl.md b/docs/perl.md
new file mode 100644
index 0000000..eee6bbe
--- /dev/null
+++ b/docs/perl.md
@@ -0,0 +1,21 @@
+Title: How to use libproxy in Perl
+Slug: snippets
+
+# How to use libproxy in Perl
+
+```
+#!/usr/bin/perl
+use warnings;
+use Glib::Object::Introspection;
+Glib::Object::Introspection->setup(
+  basename => 'Px',
+  version => '1.0',
+  package => 'Px');
+
+my $pf = new Px::ProxyFactory;
+
+$proxies = $pf->get_proxies("https://github.com/libproxy/libproxy");
+foreach my $proxy (@$proxies) {
+  print $proxy."\n";
+}
+```
diff --git a/docs/px.toml.in b/docs/px.toml.in
index 1c91b0a..5bc08c9 100644
--- a/docs/px.toml.in
+++ b/docs/px.toml.in
@@ -62,7 +62,10 @@ file_format = "{filename}#L{line}"
 [extra]
 content_files = [
   "configuration-logic.md",
-  "build-howto.md",
+  "perl.md",
+  "python.md",
+  "ruby.md",
+  "vala.md",
 ]
 
 content_images = [
diff --git a/docs/python.md b/docs/python.md
new file mode 100644
index 0000000..8094e0b
--- /dev/null
+++ b/docs/python.md
@@ -0,0 +1,30 @@
+Title: How to use libproxy in Python
+Slug: snippets
+
+# How to use libproxy in Python
+
+```
+import gi
+gi.require_version('Libproxy', '1.0')
+from gi.repository import Libproxy
+import requests
+
+url = 'https://github.com/libproxy/libproxy'
+
+pf = Libproxy.ProxyFactory()
+proxies = pf.get_proxies(url)
+
+success = False
+for proxy in proxies:
+    response = requests.get(url) #, proxies=proxies)
+    
+    if response.status_code == 200:
+        success = True
+        break
+
+if success:
+    print(f"The requested URL {url} could be retrieved using the current setup!")
+else:
+    print(f"The requested URL {url} could *NOT* be retrieved using the current setup")
+```
+
diff --git a/docs/ruby.md b/docs/ruby.md
new file mode 100644
index 0000000..ceddbd8
--- /dev/null
+++ b/docs/ruby.md
@@ -0,0 +1,20 @@
+Title: How to use libproxy in Ruby
+Slug: snippets
+
+# How to use libproxy in Ruby
+
+```
+#!/usr/bin/ruby
+
+require 'gir_ffi'
+GirFFI.setup :Libproxy
+
+pf = Libproxy::ProxyFactory.new()
+
+proxies = pf.get_proxies("https://github.com/libproxy/libproxy")
+proxies.each do |proxy|
+  puts proxy
+end
+
+pf.free()
+```
diff --git a/docs/vala.md b/docs/vala.md
new file mode 100644
index 0000000..b1332ac
--- /dev/null
+++ b/docs/vala.md
@@ -0,0 +1,32 @@
+Title: How to use libproxy in Vala
+Slug: snippets
+
+# How to use libproxy in Vala
+
+
+## Makefile
+
+```
+all: sample
+
+sample: sample.vala
+	valac --pkg libproxy-1.0 sample.vala
+
+clean:
+	rm sample
+```
+
+## Source
+
+```
+using px;
+
+void main() {
+  var pf = new px.ProxyFactory();
+  string[] proxies = pf.get_proxies("https://github.com/libproxy/libproxy");
+
+  foreach (string proxy in proxies) {
+    stdout.printf ("%s\n", proxy);
+  }
+}
+```
diff --git a/src/libproxy/meson.build b/src/libproxy/meson.build
index e088f0c..8fdd880 100644
--- a/src/libproxy/meson.build
+++ b/src/libproxy/meson.build
@@ -72,7 +72,7 @@ libproxy_gir = gnome.generate_gir(
   libproxy_lib,
   sources: libproxy_headers + libproxy_sources,
   nsversion: api_version,
-  namespace: 'Px',
+  namespace: 'Libproxy',
   export_packages: package_api_name,
   symbol_prefix: 'px',
   identifier_prefix: 'px',
diff --git a/src/libproxy/proxy-dbus.c b/src/libproxy/proxy-dbus.c
index e9d935b..1587c73 100644
--- a/src/libproxy/proxy-dbus.c
+++ b/src/libproxy/proxy-dbus.c
@@ -197,7 +197,7 @@ px_proxy_factory_get_proxies (pxProxyFactory *self,
 
 /**
  * px_proxy_factory_free_proxies
- * @proxies: proxy array
+ * @proxies: (array zero-terminated=1): a %NULL-terminated array of proxies
  *
  * Frees the proxy array returned by @px_proxy_factory_get_proxies when no
  * longer used.