[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

SF.net SVN: ledger-smb: [742] trunk



Revision: 742
          http://svn.sourceforge.net/ledger-smb/?rev=742&view=rev
Author:   einhverfr
Date:     2006-12-07 11:30:21 -0800 (Thu, 07 Dec 2006)

Log Message:
-----------
Added command-line documentation from Louis Moore.

Modified Paths:
--------------
    trunk/CONTRIBUTORS
    trunk/doc/manual/LedgerSMB-manual.tex

Added Paths:
-----------
    trunk/doc/samples/
    trunk/doc/samples/lsmb01-cli-example.sh
    trunk/doc/samples/lsmb02-cli-example.pl

Modified: trunk/CONTRIBUTORS
===================================================================
--- trunk/CONTRIBUTORS	2006-12-07 19:26:20 UTC (rev 741)
+++ trunk/CONTRIBUTORS	2006-12-07 19:30:21 UTC (rev 742)
@@ -44,6 +44,8 @@
 John Hasler <john @ dhh.gt.org> has provided some double-entry information for
 the manual and miscellaneous documentation corrections.
 
+Louis B. Moore has provided the documentation on the command-line API.
+
 Original Authors of SQL-Ledger:
 ===================================
 Dieter Simader <dsimader @ sql-ledger.com>

Modified: trunk/doc/manual/LedgerSMB-manual.tex
===================================================================
--- trunk/doc/manual/LedgerSMB-manual.tex	2006-12-07 19:26:20 UTC (rev 741)
+++ trunk/doc/manual/LedgerSMB-manual.tex	2006-12-07 19:30:21 UTC (rev 742)
@@ -22,8 +22,6 @@
 \usepackage{metatron}
 
 \renewcommand{\abstractname}{Executive Summary}
-\newcommand{\mycustomer}[1][]{#1\space}
-\newcommand{\myproject}[1][]{#1\space}
 \title{Ledger-SMB Manual v. \version}
 \author{The LedgerSMB Core Team}
 \date{\today}
@@ -2297,6 +2295,332 @@
 upgrade the templates by copying the source template over the existing
 one, or one can edit the template to make the change.
 
+\section{An Introduction to the CLI}
+
+\subsection{Conventions}
+
+The command-line API will be referred to as the API.
+
+\subsection{Preliminaries}
+
+Logging into Ledger-SMB (1.2+) updates a row in the users\_conf table
+containing your account configuration defaults and other information. 
+The implication for API users of LSMB is that you must login as part 
+of running API scripts. For security purposes, it is recommended that
+scripts prompt for a password rather than storing it.
+
+All scripts included in the documentation can also be found in the doc/samples
+directory.
+
+Consider a simple example:
+
+ cd /usr/local/ledger-smb
+./ct.pl "login=name\&path=bin\&password=xxxxx\&action=search\&db=customer"
+
+The cd command moves your terminal session's current working directory into
+the main Ledger-SMB directory. Then the Ledger-SMB perl script ct.pl is called 
+with one long line as an argument. The argument is really several variable=value pairs
+separated by ampersands (\&). The value for the login variable is the username
+that Ledger-SMB is to use, and the value for the password variable is the plaintext password.
+
+To build our examples we will use a username of "clarkkent" who has a password
+of "lOis,lAn3".
+
+ cd /usr/local/ledger-smb
+./ct.pl "login=clarkkent\&path=bin\&password=lOis,lAn3\&action=search\&db=customer"
+
+If we execute these commands we will get the html for the search form for 
+the customer database. This result isn't useful in itself, but it shows we 
+are on the right track.
+
+
+\subsection{First Script: lsmb01-cli-example.sh}
+
+With a working example, we can start to build reproducible routines that we can grow
+to do some useful work.
+
+This is a bash script which:
+
+ 1. sets NOW to the current working directory
+ 2. prompts for and reads your Ledger-SMB login
+ 3. prompts for and reads (non-echoing) your Ledger-SMB password
+ 4. changes directory to /usr/local/ledger-smb
+ 5. constructs login and logout commands and a transaction command
+ 6. logins into ledger-smb (in a real program, output would be checked for
+    success or failure)
+ 7. executes the transaction
+ 8. logs out of ledger-smb (although this is not necessary)
+ 9. returns to the original working directory
+10. exits
+
+Running lsmb01-cli-example.sh produces:
+
+\$ lsmb01-cli-example.sh 
+
+Ledger-SMB login: clarkkent
+
+Ledger-SMB password: 
+
+\begin{verbatim}
+<body>
+
+<form method=post action=ct.pl>
+
+<input type=hidden name=db value=customer>
+
+<table width=100%>
+  <tr>
+    <th class=listtop>Search</th>
+.
+.
+.
+\end{verbatim}
+
+A script like this would work well for simple batch transactions, but
+bash is not a very friendly language for application programming.
+
+
+A nicer solution would be to use a language such as perl to drive the
+command line API.
+
+\subsubsection{Script 1 (Bash)}
+\begin{verbatim}
+#!/bin/bash
+#######################################################################
+#
+# lsmb01-cli-example.sh
+# Copyright (C) 2006. Louis B. Moore
+#
+# $Id: $
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+#
+#######################################################################
+
+NOW=`pwd`
+
+echo -n "Ledger-SMB login: "
+read LSLOGIN
+echo
+
+echo -n "Ledger-SMB password: "
+stty -echo
+read LSPWD
+stty echo
+echo
+
+ARG="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=search&db=customer"
+
+LGIN="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=login"
+LGOT="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=logout"
+
+cd /usr/local/ledger-smb
+
+./login.pl $LGIN 2>&1  > /dev/null
+./ct.pl $ARG
+./login.pl $LGOT 2>&1  > /dev/null
+
+cd $NOW
+
+exit 0
+\end{verbatim}
+
+
+\subsection{Second Script: lsmb02-cli-example.pl}
+
+Our second script is written in perl and logs you in but it still uses the API 
+in its simplest form, that is, it builds commands and then executes them. This 
+type of script can be used for more complex solutions than the simple bash script 
+above, though it is still fairly limited. If your needs require, rather than have 
+the script build and then execute the commands it could be written to generate a 
+shell script which is executed by hand. 
+
+This script begins by prompting for your Ledger-SMB login and password. Using
+the supplied values a login command is constructed and passed into the runLScmd
+subroutine. runLScmd changes directory to /usr/local/ledger-smb/ for the length 
+of the subroutine. It formats the command and executes it and returns both the 
+output and error information to the caller in a scalar.
+
+The script checks to see if there was an error in the login, exiting if there was.
+
+Next, the script reads some records which are stored in the program following the
+\_\_END\_\_ token. It takes each record in turn, formats it then feeds each transaction
+through runLScmd and looks at the results for a string that signals success.
+
+Once all the transactions are processed, runLScmd is called one last time to
+logout and the script exits.
+
+\subsubsection{Script 2 (Perl)}
+\begin{verbatim}
+#!/usr/bin/perl -w
+#
+#  File:         lsmb02-cli-example.pl
+#  Environment:  Ledger-SMB 1.2.0+
+#  Author:       Louis B. Moore
+#
+#  Copyright (C)   2006  Louis B. Moore
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+#
+#  Revision:
+#       $Id$
+#
+#
+
+use File::chdir;
+use HTML::Entities;
+
+
+print "\n\nLedger-SMB login: ";
+my $login = <STDIN>;
+chomp($login);
+
+
+print "\nLedger-SMB password: ";
+system("stty -echo");
+my $pwd = <STDIN>;
+system("stty echo");
+chomp($pwd);
+print "\n\n";
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=login';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+	print "\nLogin error\n";
+	exit;
+
+}
+
+
+while (<main::DATA>) {
+
+	chomp;
+	@rec = split(/\|/);
+
+	$arg = 'path=bin/mozilla&login=' . $login . '&password=' . $pwd .
+		'&action='       . escape(substr($rec[0],0,35)) .
+		'&db='           . $rec[1] .
+		'&name='         . escape(substr($rec[2],0,35)) .
+		'&vendornumber=' . $rec[3] .
+		'&address1='     . escape(substr($rec[4],0,35)) .
+		'&address2='     . escape(substr($rec[5],0,35)) .
+		'&city='         . escape(substr($rec[6],0,35)) .
+		'&state='        . escape(substr($rec[7],0,35)) .
+		'&zipcode='      . escape(substr($rec[8],0,35)) .
+		'&country='      . escape(substr($rec[9],0,35)) .
+		'&phone='        . escape(substr($rec[10],0,20)) .
+		'&tax_2150=1' .
+		'&taxaccounts=2150' .
+		'&taxincluded=0' .
+		'&terms=0';
+
+	$rc=runLScmd("./ct.pl",$arg);
+
+	if ($rc =~ m/Vendor saved!/) {
+
+		print "$rec[2] SAVED\n";
+
+	} else {
+
+		print "$rec[2] ERROR\n";
+
+	}
+
+}
+
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=logout';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+    print "\nLogout error\n";
+
+}
+
+exit;
+
+
+#*******************************************************
+# Subroutines
+#*******************************************************
+
+
+sub runLScmd {
+
+    my $cmd  = shift;
+    my $args = shift;
+    my $i    = 0;
+    my $results;
+
+    local $CWD = "/usr/local/ledger-smb/";
+
+    $cmd = $cmd . " \"" . $args . "\"";
+
+    $results = `$cmd 2>&1`;
+
+    return $results;
+
+}
+
+sub escape {
+
+    my $str = shift;
+
+    if ($str) {
+
+	decode_entities($str);
+	$str =~ s/([^a-zA-Z0-9_.-])/sprintf("%%%02x", ord($1))/ge;
+    }
+
+    return $str;
+
+}
+
+
+#*******************************************************
+# Record Format
+#*******************************************************
+#
+# action | db | name | vendornumber | address1 | address2 | city | state | zipcode | country | phone
+#
+
+__END__
+save|vendor|Parts are Us|1377|238 Riverview|Suite 11|Cheese Head|WI|56743|USA|555-123-3322|
+save|vendor|Widget Heaven|1378|41 S. Riparian Way||Show Me|MO|39793|USA|555-231-3309|
+save|vendor|Consolidated Spackle|1379|1010 Binary Lane|Dept 1101|Beverly Hills|CA|90210|USA|555-330-7639 x772|
+
+ 	  	 
+\end{verbatim}
+
+
 \clearpage 
 
 

Added: trunk/doc/samples/lsmb01-cli-example.sh
===================================================================
--- trunk/doc/samples/lsmb01-cli-example.sh	                        (rev 0)
+++ trunk/doc/samples/lsmb01-cli-example.sh	2006-12-07 19:30:21 UTC (rev 742)
@@ -0,0 +1,52 @@
+#!/bin/bash
+#######################################################################
+#
+# lsmb01-cli-example.sh
+# Copyright (C) 2006. Louis B. Moore
+#
+# $Id: $
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+#
+#######################################################################
+
+NOW=`pwd`
+
+echo -n "Ledger-SMB login: "
+read LSLOGIN
+echo
+
+echo -n "Ledger-SMB password: "
+stty -echo
+read LSPWD
+stty echo
+echo
+
+ARG="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=search&db=customer"
+
+LGIN="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=login"
+LGOT="login=${LSLOGIN}&password=${LSPWD}&path=bin&action=logout"
+
+cd /usr/local/ledger-smb
+
+./login.pl $LGIN 2>&1  > /dev/null
+./ct.pl $ARG
+./login.pl $LGOT 2>&1  > /dev/null
+
+cd $NOW
+
+exit 0
+
+
+ 	  	 

Added: trunk/doc/samples/lsmb02-cli-example.pl
===================================================================
--- trunk/doc/samples/lsmb02-cli-example.pl	                        (rev 0)
+++ trunk/doc/samples/lsmb02-cli-example.pl	2006-12-07 19:30:21 UTC (rev 742)
@@ -0,0 +1,155 @@
+#!/usr/bin/perl -w
+#
+#  File:         lsmb02-cli-example.pl
+#  Environment:  Ledger-SMB 1.2.0+
+#  Author:       Louis B. Moore
+#
+#  Copyright (C)   2006  Louis B. Moore
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+#
+#  Revision:
+#       $Id$
+#
+#
+
+use File::chdir;
+use HTML::Entities;
+
+
+print "\n\nLedger-SMB login: ";
+my $login = <STDIN>;
+chomp($login);
+
+
+print "\nLedger-SMB password: ";
+system("stty -echo");
+my $pwd = <STDIN>;
+system("stty echo");
+chomp($pwd);
+print "\n\n";
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=login';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+	print "\nLogin error\n";
+	exit;
+
+}
+
+
+while (<main::DATA>) {
+
+	chomp;
+	@rec = split(/\|/);
+
+	$arg = 'path=bin/mozilla&login=' . $login . '&password=' . $pwd .
+		'&action='       . escape(substr($rec[0],0,35)) .
+		'&db='           . $rec[1] .
+		'&name='         . escape(substr($rec[2],0,35)) .
+		'&vendornumber=' . $rec[3] .
+		'&address1='     . escape(substr($rec[4],0,35)) .
+		'&address2='     . escape(substr($rec[5],0,35)) .
+		'&city='         . escape(substr($rec[6],0,35)) .
+		'&state='        . escape(substr($rec[7],0,35)) .
+		'&zipcode='      . escape(substr($rec[8],0,35)) .
+		'&country='      . escape(substr($rec[9],0,35)) .
+		'&phone='        . escape(substr($rec[10],0,20)) .
+		'&tax_2150=1' .
+		'&taxaccounts=2150' .
+		'&taxincluded=0' .
+		'&terms=0';
+
+	$rc=runLScmd("./ct.pl",$arg);
+
+	if ($rc =~ m/Vendor saved!/) {
+
+		print "$rec[2] SAVED\n";
+
+	} else {
+
+		print "$rec[2] ERROR\n";
+
+	}
+
+}
+
+
+$cmd = "login=" . $login . '&password=' . $pwd . '&path=bin&action=logout';
+
+$signin = runLScmd("./login.pl",$cmd);
+
+if ( $signin =~ m/Error:/ ) {
+
+    print "\nLogout error\n";
+
+}
+
+exit;
+
+
+#*******************************************************
+# Subroutines
+#*******************************************************
+
+
+sub runLScmd {
+
+    my $cmd  = shift;
+    my $args = shift;
+    my $i    = 0;
+    my $results;
+
+    local $CWD = "/usr/local/ledger-smb/";
+
+    $cmd = $cmd . " \"" . $args . "\"";
+
+    $results = `$cmd 2>&1`;
+
+    return $results;
+
+}
+
+sub escape {
+
+    my $str = shift;
+
+    if ($str) {
+
+	decode_entities($str);
+	$str =~ s/([^a-zA-Z0-9_.-])/sprintf("%%%02x", ord($1))/ge;
+    }
+
+    return $str;
+
+}
+
+
+#*******************************************************
+# Record Format
+#*******************************************************
+#
+# action | db | name | vendornumber | address1 | address2 | city | state | zipcode | country | phone
+#
+
+__END__
+save|vendor|Parts are Us|1377|238 Riverview|Suite 11|Cheese Head|WI|56743|USA|555-123-3322|
+save|vendor|Widget Heaven|1378|41 S. Riparian Way||Show Me|MO|39793|USA|555-231-3309|
+save|vendor|Consolidated Spackle|1379|1010 Binary Lane|Dept 1101|Beverly Hills|CA|90210|USA|555-330-7639 x772|
+
+ 	  	 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.