[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
SF.net SVN: ledger-smb: [742] trunk
- Subject: SF.net SVN: ledger-smb: [742] trunk
- From: ..hidden..
- Date: Thu, 07 Dec 2006 11:30:22 -0800
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.