.\" {PTM/WK/0.1 /21-08-1999/"kalkulator dowolnej precyzji"}
.\" wersja 1.06, z listopada 2000.
.\"
.\" dc.1 - the *roff document processor source for the dc manual
.\"
.\" This file is part of GNU dc.
.\" Copyright (C) 1994, 1997, 1998, 2000 Free Software Foundation, Inc.
.\"
.\" 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; see the file COPYING.  If not, write to:
.\"   The Free Software Foundation, Inc.
.\"   59 Temple Place, Suite 330
.\"   Boston, MA 02111 USA
.\"
.TH DC 1 "1997-03-25" "Projekt GNU"
.ds dc \fBdc\fP
.ds Dc \fBDc\fP
.SH NAZWA
dc - kalkulator dowolnej precyzji
.SH SKADNIA
.B dc
.RB [ -V ]
.RB [ --version ]
.RB [ -h ]
.RB [ --help ]
.RB [ -e
.IR wyra-skryptowe ]
.RB [ --expression=
.IR wyra-skryptowe ]
.RB [ -f
.IR plik-skryptu ]
.RI [ --file=
.RB plik-skryptu ]
.RI [ plik ...]
.SH OPIS
Dokument ten opisuje \fBdc\fR w wersji 1.06, z listopada 2000.
.PP
\fBdc\fR jest kalkulatorem pracujcym w odwrotnej notacji polskiej,
obsugujcym arytmetyk nieograniczonej precyzji.
Pozwala rwnie na definiowanie i wywoywanie makr.
Zwykle \fBdc\fR czyta ze standardowego wejcia. Jeli uyto argumentw
polecenia \fBdc\fR, to s one traktowane jak nazwy plikw. Zawarto tych
plikw jest odczytywana i wykonywana przez \fBdc\fR przed odczytem
standardowego wejcia.
Wszystkie zwyke wyniki kierowane s na standardowe wyjcie; wszystkie
komunikaty o bdach kierowane s na standardowe wyjcie bdw.
.PP
Kalkulator odwrotnej notacji polskiej przechowuje liczby na stosie.
Wprowadzenie liczby odkada j na stos.
Operacje arytmetyczne pobieraj argumenty ze stosu i odkadaj na nim wyniki.
.PP
W celu wprowadzenia liczby do \fBdc\fR wpisujemy cyfry z opcjonaln
kropk dziesitn. Nie jest rozpoznawana notacja wykadnicza.
Liczb ujemn poprzedzamy znakiem podkrelenia ``_''. Nie mona posuy
si w tym celu znakiem ``-'' (minus), gdy jest to dwuargumentowy operator
odejmowania.
Dwie kolejne liczby wprowadzamy oddzielajc je spacjami lub znakami nowej
linii.  Nie maj one znaczenia jako polecenia.
.SH OPCJE
\*(Dc mona wywoywa z nastpujcymi opcjami wiersza polece:
.TP
.B -V
.TP
.B --version
Wypisuje numer wersji uruchomionego \*(dc i informacj o prawach autorskich,
a nastpnie koczy dziaanie.
.TP
.B -h
.TP
.B --help
Wypisuje komunikat o sposobie wywoania, podajc w skrcie opcje wiersza
polece i adres, na ktry naley zgasza bdy, a nastpnie koczy dziaanie.
.TP
.B -e \fIskrypt\fP
.TP
.BI --expression= skrypt
Dodaje polecenia ze
.I skryptu
do zestawu polece, jakie maj by wykonane podczas przetwarzania wejcia.
.TP
.B -f \fIplik-skryptu\fP
.TP
.BI --file= plik-skryptu
Dodaje polecenia zawarte w
.I pliku-skryptu
do zestawu polece, jakie maj by wykonane podczas przetwarzania wejcia.
.PP
Jeeli po przetworzeniu powyszych opcji pozostan jeszcze jakie parametry
wiersza polece, to s one interpretowane jako nazwy plikw wejciowych,
ktre naley wykona.  Nazwa \fB-\fP odnosi si do standardowego strumienia
wejciowego.  Jeli nie podano ani opcji \fB-e\fP ani adnych plikw, to
polecenia do wykonania bd czytane ze standardowego wejcia.
.PD
.SH Polecenia wypisywania
.TP
.B p
Wypisuje warto z wierzchoka stosu, bez jego zmiany. Po wartoci wypisywany
jest znak nowej linii.
.TP
.B n
Wypisuje warto z wierzchoka stosu, zdejmujc j rwnoczenie ze stosu.
Nie wypisuje po niej znaku nowej linii.
.B P
Zdejmuje warto z wierzchoka stosu.
Jeli jest to acuch, to jest on po prostu wypisywany bez kocowego znaku
nowej linii. W przeciwnym razie jest to liczba, a cz cakowita jej
wartoci bezwzgldnej wypisywana jest jako strumie bajtw "o podstawie
(UCHAR_MAX+1)". Zakadajc, e (UCHAR_MAX+1) wynosi 256 (jak to jest
w wikszoci maszyn o 8-bitowych bajtach), funkcj t realizuje take
sekwencja \fBKSK 0k1/ [_1*]sx d0>x [256~aPd0<x]dsxx sxLKk\fP, z wyjtkiem
skutku ubocznego, jakim jest nadpisanie wartoci z rejestru x.
.TP
.B f
Wypisuje ca zawarto stosu
.ig
i zawarto wszystkich rejestrw,
..
nie zmieniajc niczego.
Jest polecenie przydatne w sytuacji, gdy si pogubilimy lub chcemy si
zorientowa, jaki by efekt pewnych polece.
.PD
.SH Arytmetyka
.TP
.B +
Zdejmuje ze stosu dwie wartoci, dodaje je i odkada wynik na stos.
Dokadno wyniku zaley wycznie od wartoci argumentw i jest
wystarczajco cisa.
.TP
.B -
Zdejmuje ze stosu dwie wartoci, odejmuje pierwsz zdjt od drugiej
i skada wynik ponownie na stos.
.TP
.B *
Zdejmuje ze stosu dwie wartoci, mnoy je i odkada wynik na stos.
Liczba cyfr uamkowych wyniku jest kontrolowana przez aktualn warto
dokadnoci (patrz niej) i liczby cyfr uamkowych mnoonych wartoci.
.TP
.B /
Zdejmuje ze stosu dwie wartoci, dzieli drug zdjt przez pierwsz
i odkada wynik ponownie na stos.
Liczba cyfr uamkowych wyniku okrelana jest przez warto dokadnoci.
.TP
.B %
Zdejmuje ze stosu dwie wartoci, oblicza reszt z dzielenia, jakie byoby
wykonane przez \fB/\fR i odkada wynik na stos.
Obliczona warto jest t sam, co otrzymana z sekwencji \fBSd dld/ Ld*-\fP.
.TP
.B ~
Zdejmuje ze stosu dwie wartoci, dzieli drug zdjt przez pierwsz.
Odkada na stos iloraz, a nastpnie reszt z dzielenia.
Dzielenie wykonywane jest z liczb cyfr uamkowych okrelon wartoci
dokadnoci.
(Funkcj t moe te spenia sekwencja \fBSdSn lnld/ LnLd%\fP, z nieco
odmiennym sprawdzaniem bdw.)
.TP
.B ^
Zdejmuje ze stosu dwie wartoci i wykonuje potgowanie, posugujc si
pierwsz zdjt jako wykadnikiem, za drug jako podstaw potgowania.
Uamkowa cz wykadnika jest ignorowana.
Warto dokadnoci okrela liczb cyfr uamkowych wyniku.
.TP
.B |
Zdejmuje ze stosu trzy wartoci i oblicza potgowanie modulo
[od tum: modular exponentiation == (a^b) mod c].
.br
Pierwsza ze zdjtych wartoci uywana jest jako dzielnik operacji
(reduction modulus).
Warto ta musi by niezerowa i powinna by liczb cakowit.
Druga uywana jest jako wykadnik i musi by liczb nieujemn,
a jej cz uamkowa zostanie zignorowana.
Trzecia z pobranych ze stosu wartoci okrela podstaw potgowania,
powinna ona by cakowita.
Dla maych liczb jest to zblione do sekwencji \fBSm^Lm%\fP, ale,
w odrnieniu od \fB^\fP, polecenie to dziaa z dowolnie duymi wykadnikami.
.TP
.B v
Zdejmuje ze stosu pojedyncz warto, oblicza jej pierwiastek kwadratowy
i odkada go na stos.
Warto dokadnoci okrela liczb cyfr uamkowych wyniku.
.PP
Na wikszo operacji arytmetycznych wpywa ``warto dokadnoci'', ktr
ustala si za pomoc polecenia \fBk\fR.
Domyln wartoci dokadnoci jest zero, co oznacza, e wszystkie dziaania
arytmetyczne z wyjtkiem dodawania i odejmowania daj wyniki cakowite.
.PP
Operacja reszty
.B %
wymaga pewnego wyjanienia:
zastosowana do argumentw  ``a'' i ``b'' daje w wyniku ``a - (b * (a / b))'',
gdzie ``a/b'' obliczane jest z biec dokadnoci.
.SH Kontrola stosu
.TP
.B c
Czyci stos, powoduje, e bdzie on pusty.
.TP
.B d
Powiela warto na wierzchoku stosu, odkadajc na stos jej kopi.
Zatem ``4d*p'' oblicza 4 podniesione do kwadratu i wypisuje wynik.
.TP
.B r
Zamienia miejscami dwie grne wartoci na stosie.
.SH Rejestry
\fBdc\fR udostpnia 256 rejestrw pamiciowych, kady nazwany pojedynczym
znakiem. W rejestrze mona przechowa liczb lub acuch znakowy i pniej
je odtworzy.
.TP
.BI s r
Zdejmuje warto z wierzchoka stosu i zapisuje w rejestrze \fIr\fR.
.TP
.BI l r
Kopiuje warto zawart w rejestrze \fIr\fR i odkada j na stos.
Nie zmienia to zawartoci \fIr\fR.
.PP
Kady z rejestrw posiada rwnie swj wasny stos. Biec wartoci rejestru
jest wierzchoek stosu rejestru.
.TP
.BI S r
Zdejmuje warto z wierzchoka stosu (gwnego) i odkada j na stosie
rejestru \fIr\fR. Poprzednia warto rejestru staje si niedostpna.
.TP
.BI L r
Zdejmuje warto z wierzchoka stosu rejestru \fIr\fR i odkada j
na gwnym stosie. Poprzednia warto stosu rejestru \fIr\fR,
jeli bya takowa, jest teraz dostpna poprzez polecenie \fBl\fIr\fR.
.ig
.PP
Polecenie
.B f
wypisuje list wszystkich rejestrw zawierajcych przechowywane wartoci,
razem z tymi zawartociami. Wypisywana jest tylko bieca zawarto kadego
z rejestrw (wierzchoek jego stosu).
..
.SH Parametry
\fBdc\fR posiada trzy parametry kontrolujce jego prac:
dokadno, podstaw systemu pozycyjnego wejcia i podstaw wyjcia.
Dokadno okrela liczb cyfr dziesitnych, jaka bdzie zachowana w wyniku
wikszoci operacji arytmetycznych.
Podstawa wejcia odpowiada za interpretacj wprowadzanych liczb; wszystkie
wprowadzane liczby uywaj tej podstawy.
Podstawa wyjcia uywana jest do wypisywania liczb.
.PP
Podstawa wejcia i wyjcia s odrbnymi parametrami; mona spowodowa,
e bd rne, co moe by uyteczne lub mylce.
Podstawa wejcia musi by liczb z zakresu od 2 do 16.
Podstawa wyjcia musi wynosi co najmniej 2.
Dokadno musi by rwna zeru lub wiksza. Dokadno zawsze okrelana jest
jako liczba cyfr dziesitnych, niezalenie od biecej podstawy wejcia czy
wyjcia.
.TP
.B i
Zdejmuje warto z wierzchoka stosu i posuguje si ni do ustawienia
podstawy wejcia.
.TP
.B o
Zdejmuje warto z wierzchoka stosu i posuguje si ni do ustawienia
podstawy wyjcia.
.TP
.B k
Zdejmuje warto z wierzchoka stosu i posuguje si ni do ustawienia
dokadnoci.
.TP
.B I
Odkada biec warto podstawy wejcia na stosie.
.TP
.B O
Odkada biec warto podstawy wyjcia na stosie.
.TP
.B K
Odkada biec dokadno na stosie.
.SH acuchy znakowe
.PP
\fBdc\fR oprcz pracy z liczbami moe te dziaa na acuchach znakowych.
acuchy mona jedynie wypisywa i wykonywa jako makra (co oznacza,
e zawarto acucha przetwarzana jest jako polecenia \fBdc\fR).
Stos i wszystkie rejestry mog przechowywa acuchy, a \fBdc\fR zawsze wie,
czy dany obiekt jest acuchem czy liczb.
Niektre z polece, jak np. operacje arytmetyczne, wymagaj liczb jako swych
argumentw i wywietlaj bdy, jeli dostarczono im acuch.
Inne akceptuj zarwno liczby, jak i acuchy znakowe. Na przykad,
polecenie
.B p
akceptuje oba rodzaje argumentw i wypisuje obiekt stosownie do jego typu.
.TP
.BI [ znaki ]
Tworzy acuch zawierajcy
.I znaki
(zawarte pomidzy nawiasami kwadratowymi \fB[\fR i \fB]\fR)
i odkada go na stos.
Na przykad,
.B [foo]P
wypisuje znaki
.B foo
(bez zakoczenia znakiem nowej linii).
.TP
.B a
Zdejmowany jest wierzchoek stosu.
Jeeli jest to liczba, to modszy bajt (low-order byte) tej liczby zamieniany
jest na acuch i odkadany na stos. W przeciwnym przypadku, wierzchoek stosu
by acuchem, a z powrotem na stos odkadany jest pierwszy znak tego
acucha.
.TP
.B x
Zdejmuje warto ze stosu i wykonuje j jako makro. Zwykle powinien to by
acuch znakowy. Jeeli jest to liczba, to zostanie po prostu zwrcona na stos.
Na przykad,
.B [1p]x
wykonuje makro
.BR 1p ,
ktre odkada
.B 1
na stosie i wypisuje
.B 1
w osobnym wierszu.
.PP
Makra s najczciej przechowywane w rejestrach:
.B [1p]sa
skaduje makro do wypisania
.B 1
w rejestrze
.BR a ,
za
.B lax
wywouje to makro.
.TP
.BI > r
Zdejmuje dwie wartoci ze stosu i porwnuje je, zakadajc, e s one liczbami,
wykonujc zawarto rejestru
.I r
jako makro, jeli pierwotny wierzchoek stosu jest wikszy.
Tak wic,
.B 1 2>a
wywoa zawarto rejestru
.B a
za
.B 2 1>a
nie wywoa.
.TP
.BI !> r
Podobnie, ale wywouje makro jeli pierwotny wierzchoek stosu nie jest
wikszy (jest mniejszy bd rwny) od liczby wystpujcej pod nim.
.TP
.BI < r
Podobnie, ale wywouje makro jeli pierwotny wierzchoek stosu jest mniejszy
od liczby wystpujcej pod nim.
.BI !< r
Podobnie, ale wywouje makro jeli pierwotny wierzchoek stosu nie jest
mniejszy (jest wikszy bd rwny) od liczby wystpujcej pod nim.
.TP
.BI = r
Podobnie, ale wywouje makro, gdy obie zdjte ze stosu liczby s rwne.
.TP
.BI != r
Podobnie, ale wywouje makro, gdy obie zdjte ze stosu liczby nie s rwne.
.ig
Jest to rwnie poprawna forma sprawdzenia rwnoci dwu acuchw.
..
.TP
.B ?
Czyta wiersz z terminala i wykonuje go. Polecenie to umoliwia makru
pobieranie danych od uytkownika.
.TP
.B q
powoduje zakoczenie pracy makra i makra, z ktrego byo ono wywoane.
Polecenie to wywoane na najwyszym poziomie lub z makra wywoanego
bezporednio z najwyszego poziomu spowoduje zakoczenie pracy \fBdc\fR.
.TP
.B Q
Zdejmuje ze stosu warto i uywa jej jako liczby poziomw wykonania makr,
jakie maj zosta zakoczone.
Tak wic,
.B 3Q
koczy prac trzech poziomw makr.
Polecenie
.B Q
nigdy nie powoduje zakoczenia pracy \fBdc\fR.
.SH Informacja o stanie
.TP
.B Z
Zdejmuje warto ze stosu, oblicza liczb jej cyfr (lub liczb znakw, jeli
jest to acuch) i odkada t liczb na stos.
.TP
.B X
Zdejmuje warto ze stosu, oblicza liczb jej cyfr uamkowych i odkada t
liczb na stos. Dla acuchw wartoci odkadan na stos jest
.\" -1.
0.
.TP
.B z
Odkada na stos biec wysoko stosu: liczb obiektw na stosie przed
wykonaniem polecenia \fBz\fR.
.SH Rne
.TP
.B !
Uruchamia reszt wiersza jako polecenie systemu.
Zauwa, e pierwszestwo w analizie skadni maj polecenia \fB!<\fP,
\fB!=\fP i \fB!>\fP, wic jeli chcemy uruchomi polecenie systemu
zaczynajce si od \fB<\fP, \fB>\fP lub \fB=\fP, to po \fB!\fP musimy
doda odstp.
.TP
.B #
Interpretuje reszt wiersza jako komentarz.
.TP
.BI : r
Zdejmuje ze stosu dwie grne wartoci. Warto, ktra bya drug od gry
stosu zostanie zachowana w tablicy
.IR r ,
indeksowanej wartoci byego wierzchoka stosu.
.TP
.BI ; r
Zdejmuje wierzchoek stosu i posuguje si nim jako indeksem tablicy
.IR r .
Wybrana w ten sposb warto jest nastpnie odkadana na stos.
Zauwa, e kada ze skadowanych na stosie instancji rejestru ma swoj
wasn, skojarzon z ni tablic.
Zatem, \fB1 0:a 0Sa 2 0:a La 0;ap\fP wypisze 1, gdy 2 zostao zapamitane
w instancji 0:a, ktra zostaa pniej odoona na stos.
.SH UWAGI
Operacje tablicowe
.B :
oraz
.B ;
s zwykle uywane wycznie przez tradycyjne implementacje \fBbc\fR.
(Program
.B bc
w wersji GNU jest samowystarczalny i nie potrzebuje \fBdc\fR by dziaa.)
.SH BDY
Bdy prosz zgasza (w jz.angielskim) na adres
.BR bug-dc@gnu.org .