NAME
axs - afnix cross spreadsheet
SYNOPSIS
axs [options] file [arguments]
OPTIONS
[h]
prints the help message
[v]
prints the program version
[i path] path
add a directory path to the resolver
[e] mode
force the encoding mode
[f] assert
enable assertion checking
[f] nopath
do not set initial path
DESCRIPTION
axs invokes the AFNIX cross spreadsheet. The axs client is a font-end
tool for the AFNIX sheet and folio objects which are part of the
standard spreadsheet library. The axs client is built on top of the
AFNIX interpreter and therefore supports all the language
capabilities.
VERSION
The current version is the 1.5.2 release.
SEE ALSO
axc, axd, axi, axl
NOTES
AFNIX comes with an extensive documentation. The documentation is
available online or in the doc directory in the form of formated xhtml
documents.
AUTHOR
axs has been written by (amaury@afnix.org) Amaury Darsch.
GETTING STARTED
This chapter is short introduction to the AFNIX cross spreadsheet or
axs. The AFNIX spreadsheet is a special interpreter that provides
special commands to manipulate spreadsheets, made out of sheet and
folio. The axs interface is also designed to ease some operations like
loading or saving sheets.
Invocation and termination
The axs spreadsheet is started by typing the command axs. Once started,
the spreadsheet reads the commands from the terminal. Since the
spreadsheet is built on top of the AFNIX interpreter, any command is
in fact a special form that is executed by the interpreter. The natural
way to invoke the debugger is to pass the primary file to execute with
eventually some arguments.
zsh> axs PROGRAM [arguments]
When the spreadsheet is started, a prompt ’(axs)’ indicates that the
session is running. The session is terminated like any AFNIX
interpreted session by using ctrl-d.
zsh> axs PROGRAM
(axd)
Spreadsheet options
The available options can be seen with the -h option and the current
version with the -v option. This mode of operations is similar to the
one found with the AFNIX interpreter.
zsh> axs -h
usage: axs [options] [file] [arguments]
[h] print this help message
[v] print version information
[i] path add a path to the resolver
[f assert] enable assertion checking
Folio operations
The process of importing data requires first to create a folio which
will act as a collection of sheets. When starting from the beginning,
the best way is to create a new folio and then create, one or several
sheets in which data can be added or imported.
Creating a folio
The process of importing data requires first to create a folio. When
starting from the beginning, the best way is to create a new folio with
the axs:new command, then create one or several sheets with the
axs:create command and finally import data with the axs:import command.
(axs) axs:new "elements"
The axs:new command creates a new folio those name is given by the
argument. Without argument, the command creates an unnamed folio. The
command also returns the Folio object that can be later used for
special operations.
Saving a folio
The axs:save command writes a binary representation of the folio in a
file. The folio is serialized with the help of the AFNIX serialize
engine. The serialization is done in a file that can be reloaded with
the axs:open command.
(axs) axs:save "elements.xss"
(axs) axs:open "elements.xss"
Creating a default sheet
In order to import data, a sheet must be created in the folio. The
axs:create command creates a sheet in the folio. The command take an
optional argument which is the sheet name. The command also returns the
Sheet object that can be used for other special processing.
(axs) axs:create "data"
A new sheet named data is created and becoming the default one. Once
the sheet is created, the data can be added into it with the help of
the axs:import command. There is always a default sheet attached to a
folio. The default sheet is set by creating a new sheet or by using the
axs:select command.
Importing data in the sheet
The periodic table of the elements is a simple example that illustrates
the importation process. The original file is located into the exp/elem
directory. The elements.tbl file is a simple file that associates the
atomic number with an element name, it chemical symbol and other
parameters. An extract of the file is shown below.
# ------------------------------------------------------------
# - elements.tbl -
# - the periodic sheet of elements -
# ------------------------------------------------------------
# - element name sym weight bp (c) mp (c) density -
# ------------------------------------------------------------
1 "Hydrogen" "H" 1.00797 -252.7 -259.2 0.071
2 "Helium" "He" 4.0026 -268.9 -269.7 0.126
3 "Lithium" "Li" 6.939 1330 180.5 0.53
4 "Beryllium" "Be" 9.0122 2770 1277 1.85
5 "Boron" "B" 10.811 nil 2030 2.34
There are 112 rows in this sheet. Not all rows have data. A particular
cell, with no data is marked with the special symbol nil. Strings are
enclosed with double quotes. Integer and reals numbers differentiate
themselves automatically. A line with no data is ignored. A comment
starts with the # character.
(axs) axs:new "elements"
(axs) axs:create "data"
(axs) axs:import "elements.tbl"
(axs) axs:save "elements.xss"
After the axs:import command, the axs:save command writes the folio in
a file called elements.xss. Such file can be later used with the
axs:open command.
Folio reloading
Given a folio, the axs:open command reload the folio in memory and
permit the sheet manipulation. When a folio is loaded, the default
sheet can be selected. Using the previous example, and assuming a new
session is started:
# reload the folio
(axs) axs:open "elements.xss"
When the folio is loaded, the first sheet is set as the default sheet.
Folio information
When the folio is loaded, the axs:info command reports some information
about the folio.
(axs)axs:info
Object Value
Folio name elements
Current sheet data
In the previous example, the folio name is reported as well as the
default sheet.
Sheet operations
Sheets can be manipulated once loaded into a folio. There is always a
default sheet on which most of the operation apply. In certain cases,
the operations can also be done with the help of the sheet index.
Sheet information
The axs:list command displays the folio content with the sheet index,
sheet name and sheet length. This command permits to check, among other
things, that an importation process operated correctly.
(axs)axs:list
Sheet index Sheet name Sheet length
0 data 112
The command reports for each sheet, its name and size. The size is the
number of records which is the number of rows. After a axs:create
command, the axs:list command will report a sheet without element.
Viewing the sheet contents
The best way to visualize the sheet content is to use the axs:view
command. The command operates with the default sheet. Without argument,
the whole sheet is shown. With one argument, an integer number that
specifies the report length and eventually a secondary number that
specifies the starting index.
(axs)axs:view 5 10
11 Sodium Na 22.989800 892 97.800000 .97
12 Magnesium Mg 24.312000 1107 650 1.740000
13 Aluminum Al 26.981500 2450 660 2.700000
14 Silicon Si 28.086000 2680 1410 2.330000
15 Phosphorus P 30.984000 nil nil nil
Sorting a sheet
The axs:sort command sorts the default sheet. The sheet column as well
as well as the sorting mode are the sorting parameters. Without
argument the first column and the ascending mode are used to sort the
sheet. For example, a sorting on the second column in ascending order,
produces the following result:
(axs)axs:sort 1
(axs)axs:view 5
95 Americium Am 243.060000 nil nil nil
13 Aluminum Al 26.981500 2450 660 2.700000
18 Argon Ar 39.948000 -185.800000 -189.400000 1.400000
33 Arsenic As 74.992000 613 817 5.720000
51 Antimony Sb 121.750000 1380 630.500000 6.620000
On the other end, sorting in descending order produces the following
result:
(axs)axs:sort 1
(axs)axs:view 5
40 Zirconium Zr 91.220000 3580 1852 6.490000
30 Zinc Zn 65.370000 906 419.500000 7.140000
70 Ytterbium Yb 173.040000 1427 824 6.980000
39 Yttrium Y 88.905900 nil nil nil
54 Xenon Xe 131.300000 -108 -111.900000 3.060000
CROSS SPREADSHEET REFERENCE
This appendix is a reference of the AFNIX cross spreadsheet or axs.
The AFNIX cross spreadsheet is started with the axs command. All
control commands are bound to the axs nameset.
create
The axs:create command create a new sheet in the folio. In order to
succeed, a folio object must exist prior creating a sheet. Without
argument, a default sheet is created without name. The optional
argument is the sheet name
Syntax
axs:create axs:create "name"
(axs) axs:create "data"
This example create a sheet with the name data. Once the sheet has been
created, it becomes the default sheet.
export
The axs:export command exports the contents of the default sheet to the
specified file. When exported, the sheet is formatted in such way that
it can be read again with the import command.
Syntax
axs:export "file"
(axs) axs:export "elements.txt"
import
The axs:import command imports data into the current sheet. The data
must be formatted in such way that they are readable by the AFNIX
reader. In particular, the string must be placed between double quotes
and the character between single quotes. Blank and tabulation
characters are used as separators.
Syntax
axs:import "file"
(axs) axs:import "elements.tbl"
info
The axs:info command prints some information about the folio. Among the
information is the folio name and the current sheet. An optional output
stream argument can be used to write the sheet information.
Syntax
axs:info axs:info "file"
(axs) axs:info
insert
The axs:insert command insert data into the current sheet. The data are
seen as a vector of literals. When the command is executed, a record is
automatically created, filled with the data and inserted into the
sheet.
Syntax
axs:insert "data+"
(axs) axs:insert "hello" "world" 2000
In this example, a record of 3 elements is created with 2 strings and
one integer.
insert-info
The axs:insert-marker command insert marker data into the current
sheet. The data are seen as a vector of literals. When the command is
executed, the marker record is filled with the data. This command is
similar to the axs:insert. The marker record is primarily used to mark
the sheet columns.
Syntax
axs:insert-marker "data+"
(axs) axs:insert-marker "hello" "world" 2000
In this example, the 2 strings and one integer are added into the sheet
marker record.
insert-header
The axs:insert-header command insert header data into the current
sheet. The data are seen as a vector of literals. When the command is
executed, the header record is filled with the data. This command is
similar to the axs:insert
Syntax
axs:add-info "data+"
(axs) axs:add-info "hello" "world" 2000
In this example, the 2 strings and one integer are added into the sheet
informatino record.
insert-footer
The axs:insert-footer command insert footer data into the current
sheet. The data are seen as a vector of literals. When the command is
executed, the footer record is filled with the data. This command is
similar to the axs:insert
Syntax
axs:add-info "data+"
(axs) axs:add-info "hello" "world" 2000
In this example, the 2 strings and one integer are added into the sheet
informatino record.
new
The axs:new command create a new folio. Without argument an empty folio
is created. With one string argument, a new folio is created with the
argument name. with two arguments, a new folio is created by name and
info. If a folio already exists, it is closed prior the creation of the
new one.
Syntax
axs:new axs:new "name"
(axs) axs:new "elements"
open
The axs:open command open a new folio those name is the file name given
as the argument. The file name must corresponds to a serialized folio
that was generated with the axs:save command.
Syntax
axs:open "file"
(axs) axs:open "elements.xss"
save
The axs:save command saves the current folio into a file those name is
given as the argument. The axs:save command operates by serializing the
folio.
Syntax
axs:save "file"
(axs) axs:save "elements.xss"
select
The axs:select command selects a sheet by index. Since there is no
guarantee that the sheet name is unique, an index is more appropriate
to guarantee a unique selection. Once selected, the sheet becomes the
default one.
Syntax
axs:select "index"
(axs) axs:select 1
list
The axs:list command reports the folio contents. For each sheet, the
index, the sheet name and size is reported. With an argument, the
reported information is written to an output stream. By default, the
standard output is used for reporting.
Syntax
axs:list axs:list "file"
(axs) axs:list
view
The axs:view command display the sheet contents by using the cell
literal representation. Without argument, the entire tale is reported.
With one integer argument as the report size, only the specified number
of elements is reported. A second integer argument that acts as a
starting index can also be used.
Syntax
axs:view axs:view "length" axs:view "length" "start"
(axs) axs:view