Difference between revisions of "He/שימוש ב API"

From GnuCash
Jump to: navigation, search
(Edit Language box)
m (→‎תיעוד: style)
 
(24 intermediate revisions by the same user not shown)
Line 5: Line 5:
 
! scope="row"|שפות
 
! scope="row"|שפות
 
| [[Using the API|אנגלית]]
 
| [[Using the API|אנגלית]]
−
| [[de/GnuCash|גרמנית]]
 
−
| [[es/GnuCash|ספרדית]]
 
 
| [[{{PAGENAME}}|עִברִית]]
 
| [[{{PAGENAME}}|עִברִית]]
−
| [[pt/GnuCash|פורטוגזית]]
 
−
| [[fr/GnuCash|צרפתית]]
 
 
|}
 
|}
 
==כללי==
 
==כללי==
  
−
This page collects some examples on how to use the C API of gnucash for basic data type manipulation. The C API (also called "the engine") is the abstraction layer from any backend. That is, the GUI or plugin programmer should never access any XML or SQL himself but instead he only uses the functions from the C API to access the data.
+
עמוד זה מרכז מספר דוגמאות אודות אופן השימוש ב־C API של גנוקאש לצורך מניפולציה בסיסית בסוגי נתונים. C API (מכונה גם "המנוע") הוא שכבה שהפשטה מכל שרת. כלומר, מתכנת של מנשק המשתמש או מתכנת המתקעים לעולם לא יוכלו לגשת לאף אחד מתוכניות ה-XMLאו ה־SQL ישירות, במקום זאת הוא משתמש רק בפונקציות של מנשק ה־API כדי לגשת לנתונים.
  
 
== תיעוד ==
 
== תיעוד ==
−
As for documentation: Unfortunately there doesn't exist any up-to-date coherent set of documentation. Part of it is in [[Doxygen]], but part of it are only in the C header files.
+
באשר לתיעוד: לרוע המזל אין שום תיעוד קוהרנטי עדכני. חלקים נמצאים ב־[[He/דוקסיג'ן|דוקסיג'ן]], אבל חלקים נמצאים רק בכותרות (header) קובצי C.
  
−
[{{BuildURL}}/docs/MAINT/modules.html A module overview] is available for those parts that are documented in doxygen. For example, there is a module group entitled "GnuCash Engine: Core, Non-GUI Accounting Functions" which contains the doxygen-ized parts of this, including the "Account", but not including Transaction and Split which are the other important basic data types.
+
[{{BuildURL}}/docs/MAINT/modules.html רשימת פירקני גנוקאש] זמינה לחלקים שמתועדים בדוקסיג'ן. לדוגמה, קיימת קבוצת פירקנים תחת הכותרת "מנוע גנוקאש: Core, Non-GUI Accounting Functions" המכילה את אותם חלקים שעברו "דוקסיניזציה", לרבות אובייקט ה'''חשבון''', אך אינה מכילה את אובייקטי ה'''תנועות והפיצולים''', שהם שני סוגי הנתונים, החשובים, האחרים.
  
−
[[Media:gnucash_erd.png|Entity-Relationship Diagram]] is an up-to-date (May 2011, but the schema is unchanged in mid-2017) Entity-Relationship-Diagram (ERD) which shows those most important types of gnucash (in the form of tables, as common for an ERD):
+
[[Media:gnucash_erd.png| מודל ישויות קשרים (ERD)<ref>https://he.wikipedia.org/wiki/מודל_ישויות_קשרים</ref>]] היא גרסה עדכנות (הוכנה למעשה במאי 2011, אך לא השתנתה כלל עד אמצע 2017) מציג את סוגי הישויות ואת הקשרים בין שדות המידע, לטבלאות בגנוקאש (בצורת טבלאות דבר שכיח בתרשימי ERD):
 
* פיצול
 
* פיצול
 
* תנועה
 
* תנועה
Line 27: Line 23:
 
* ספר (typedef name: QofBook)
 
* ספר (typedef name: QofBook)
  
−
The only place that is for sure up-to-date are the header files:
+
המקום היחיד בו לבטח ניתן למצוא מידע עדכני, הוא בכותרות הקבצים:
 
* libgnucash/engine/Split.h
 
* libgnucash/engine/Split.h
 
* libgnucash/engine/Transaction.h
 
* libgnucash/engine/Transaction.h
Line 33: Line 29:
 
* libgnucash/engine/gnc-commodity.h
 
* libgnucash/engine/gnc-commodity.h
 
* libgnucash/engine/qofbook.h
 
* libgnucash/engine/qofbook.h
−
 
−
;This section is from a very old in-tree build:If you intend to use those basic types from outside of gnucash, the following set of libraries contains the functions needed for this basic C API:<s>
 
−
: src/libqof/qof/libgnc-qof.la
 
−
: src/core-utils/libgnc-core-utils.la
 
−
: src/gnc-module/libgnc-module.la
 
−
: src/engine/libgncmod-engine.la
 
−
: src/backend/xml/libgncmod-backend-xml.la
 
−
: src/app-utils/libgncmod-app-utils.la</s>
 
−
:in increasing order, i.e. the latter ones depend on the former ones.
 
−
 
−
;CuteCash is now removed:<s>In the C++ cutecash project, consequently those five important types appear again in separate header files which contain the C++ wrapper classes for the respective basic types:
 
−
:* src/gnc/Split.hpp
 
−
:* src/gnc/Transaction.hpp
 
−
:* src/gnc/Account.hpp
 
−
:* src/gnc/Commodity.hpp
 
−
:* src/gnc/Book.hpp</s>
 
  
 
== יצירת תנועה חדשה ==
 
== יצירת תנועה חדשה ==
−
Here's the code to create a new transaction (abbreviated by "txn") and populate it with data, using "almost correct" C code (in reality, all the variable declarations must appear on top and not within the code):
+
להלן הקוד ליצירת תנועה חדשה (להלן '''תנועה''') ואכלסה בנתונים תוך שימוש בקוד C "כמעט אמיתי" (במציאות כל הצהרות המשתנים חייבות להופיע בתחילת הקוד בראש התסריט ולא משולב בתוך שורות הקוד):
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
−
  Account *account = ...; // get this from somewhere
+
  Account *account = ...; // לקבל זאת מהיכן שהו
 
  QofBook *book = gnc_account_get_book(account);
 
  QofBook *book = gnc_account_get_book(account);
 
   
 
   
−
  Transaction *transaction = xaccMallocTransaction(book); // Creating the new transaction
+
  Transaction *transaction = xaccMallocTransaction(book); // יצירת התנועה החדשה
−
  xaccTransBeginEdit(transaction); // Opening it for editing
+
  xaccTransBeginEdit(transaction); // פתיחת התנועה לעריכה
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
The txn is created. We can set the txn-related data fields:
+
קוד התנועה נוצר. כעת ניתן להגדיר את שדות המידע הקשורים לקוד ההתנועה:
  
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
−
  xaccTransSetDatePostedSecs(transaction, 1234567); // Date of this txn
+
  xaccTransSetDatePostedSecs(transaction, 1234567); // תאריך התנועה
 
  xaccTransSetNum(transaction, "X23");
 
  xaccTransSetNum(transaction, "X23");
−
  xaccTransSetNotes(transaction, "Some notes, bla bla");
+
  xaccTransSetNotes(transaction, "הערות כל שהן...");
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
As gnucash is capable of multi-currency handling, every txn must have a "transaction currency" set:
+
מכיוון שגנוקאש מסוגלת לטפל ברבוי־מטבעות, כל תנועה חייבת לכלול גם את הגדרת ''מטבע תנועה'':
 
   
 
   
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
 
  Commodity *currency = xaccAccountGetCommodity(account);
 
  Commodity *currency = xaccAccountGetCommodity(account);
−
  xaccTransSetCurrency(transaction, currency); // Txn must have a commodity/currency set
+
  xaccTransSetCurrency(transaction, currency); //   תנועה חייבת לכלול גם הגדרות /סחורה/מטבעת
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
The actual amount/value of a transaction is given by its two or more splits. We create the first split:
+
הסכום/הערך בפועל של התנועה יתקבל על ידי שנים (או יותר)הפיצולים שלה. תחילה ייצורים את הפיצול הראשון:
  
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
 
  Split *split = xaccMallocSplit(book);
 
  Split *split = xaccMallocSplit(book);
−
  xaccTransAppendSplit(transaction, split); // Split belongs to this txn
+
  xaccTransAppendSplit(transaction, split); // הפיצול שייך לתנועה זו
−
  xaccAccountInsertSplit(account, split); // Split belongs to this account
+
  xaccAccountInsertSplit(account, split); // הפיצול שייך לחשבון זה
−
  gnc_numeric amount = gnc_numeric_create(123, 100); // 1.23
+
  gnc_numeric amount = gnc_numeric_create(123, 100); // 1.23 הסכום
 
  xaccSplitSetValue(split, amount);
 
  xaccSplitSetValue(split, amount);
 
  xaccSplitSetAmount(split, amount);
 
  xaccSplitSetAmount(split, amount);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
As for the SetValue and SetAmount: In multi-currency or stock trading txn, the amount is different from the value and vice versa. As long as you're dealing with exactly one currency, both value and amount are set to be the same value.
+
באשר ל־SetValue ו־SetAmount: בתנועה למסחר רב־מטבעי או במסחר במניות, הסכום  והערך אינם בהכרך זהים, להפך. כל עוד מתמודדים עם מטבע אחד בלבד, הערך והסכום מוגדרים להיות זהים.
−
 
+
כעת נדרש לייצור גם את הפיצול השני כך שהתנועה תהיה מאוזנת ובעלת שני פיצולים לפחות (שורת חובה ושורת זכות), בדיוק כפי שתנועות נרשמות בהנהלת חשבונות כפולה:
−
Then we create the second split so that we have a normal two-split transaction, as usual in the double-entry bookkeeping:
 
  
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
−
  Account* other_account = ...; // need to get this from somewhere
+
  Account* other_account = ...; // נדרש לקבל זאת מהיכן שהו
 
  Split *split2 = xaccMallocSplit(book);
 
  Split *split2 = xaccMallocSplit(book);
−
  xaccTransAppendSplit(transaction, split2); // Split belongs to this txn
+
  xaccTransAppendSplit(transaction, split2); // הפיצול שייך לתנועה הזו
−
  xaccAccountInsertSplit(other_account, split2); // Split belongs to this account
+
  xaccAccountInsertSplit(other_account, split2); // הפיצול שייך לחשבון זה
−
  gnc_numeric other_amount = gnc_numeric_create(-123, 100); // -1.23, the negative value for above
+
  gnc_numeric other_amount = gnc_numeric_create(-123, 100); // -1.23, הסכום מהפיצול הקודם אבל בסימן הפוך (מייצג חובה / זכות)
 
  xaccSplitSetValue(split, other_amount);
 
  xaccSplitSetValue(split, other_amount);
 
  xaccSplitSetAmount(split, other_amount);
 
  xaccSplitSetAmount(split, other_amount);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
In the end, we must finish the transaction editing by calling the CommitEdit function:
+
לבסוף, סיום עריכת התנועה על ידי קריאה לפונקציה CommitEdit:
  
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
−
  xaccTransCommitEdit(transaction); // We are finished editing
+
  xaccTransCommitEdit(transaction); // סיום העריכה
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== דוגמאות שימוש ==
 
== דוגמאות שימוש ==
−
ניתן למצא מספר דוגמאות ב- [[Python_shell#Usage_examples]].
+
ניתן למצא מספר דוגמאות ב־[Python_shell#Usage_examples]].
  
 +
==הערות שוליים==
 +
<references />
  
−
[[Category:He|פתוח]]
+
[[category:He|פתוח]]

Latest revision as of 17:30, 16 December 2021

שפות אנגלית עִברִית

כללי

עמוד זה מרכז מספר דוגמאות אודות אופן השימוש ב־C API של גנוקאש לצורך מניפולציה בסיסית בסוגי נתונים. C API (מכונה גם "המנוע") הוא שכבה שהפשטה מכל שרת. כלומר, מתכנת של מנשק המשתמש או מתכנת המתקעים לעולם לא יוכלו לגשת לאף אחד מתוכניות ה-XMLאו ה־SQL ישירות, במקום זאת הוא משתמש רק בפונקציות של מנשק ה־API כדי לגשת לנתונים.

תיעוד

באשר לתיעוד: לרוע המזל אין שום תיעוד קוהרנטי עדכני. חלקים נמצאים ב־דוקסיג'ן, אבל חלקים נמצאים רק בכותרות (header) קובצי C.

רשימת פירקני גנוקאש זמינה לחלקים שמתועדים בדוקסיג'ן. לדוגמה, קיימת קבוצת פירקנים תחת הכותרת "מנוע גנוקאש: Core, Non-GUI Accounting Functions" המכילה את אותם חלקים שעברו "דוקסיניזציה", לרבות אובייקט החשבון, אך אינה מכילה את אובייקטי התנועות והפיצולים, שהם שני סוגי הנתונים, החשובים, האחרים.

מודל ישויות קשרים (ERD)[1] היא גרסה עדכנות (הוכנה למעשה במאי 2011, אך לא השתנתה כלל עד אמצע 2017) מציג את סוגי הישויות ואת הקשרים בין שדות המידע, לטבלאות בגנוקאש (בצורת טבלאות דבר שכיח בתרשימי ERD):

  • פיצול
  • תנועה
  • חשבון
  • סחורה (typedef name: gnc_commodity)
  • ספר (typedef name: QofBook)

המקום היחיד בו לבטח ניתן למצוא מידע עדכני, הוא בכותרות הקבצים:

  • libgnucash/engine/Split.h
  • libgnucash/engine/Transaction.h
  • libgnucash/engine/Account.h
  • libgnucash/engine/gnc-commodity.h
  • libgnucash/engine/qofbook.h

יצירת תנועה חדשה

להלן הקוד ליצירת תנועה חדשה (להלן תנועה) ואכלסה בנתונים תוך שימוש בקוד C "כמעט אמיתי" (במציאות כל הצהרות המשתנים חייבות להופיע בתחילת הקוד בראש התסריט ולא משולב בתוך שורות הקוד): 

 Account *account = ...; // לקבל זאת מהיכן שהו
 QofBook *book = gnc_account_get_book(account);
 
 Transaction *transaction = xaccMallocTransaction(book); // יצירת התנועה החדשה
 xaccTransBeginEdit(transaction); // פתיחת התנועה לעריכה

קוד התנועה נוצר. כעת ניתן להגדיר את שדות המידע הקשורים לקוד ההתנועה: 

 xaccTransSetDatePostedSecs(transaction, 1234567); // תאריך התנועה 
 xaccTransSetNum(transaction, "X23");
 xaccTransSetNotes(transaction, "הערות כל שהן...");

מכיוון שגנוקאש מסוגלת לטפל ברבוי־מטבעות, כל תנועה חייבת לכלול גם את הגדרת מטבע תנועה: 

 Commodity *currency = xaccAccountGetCommodity(account);
 xaccTransSetCurrency(transaction, currency); //   תנועה חייבת לכלול גם הגדרות /סחורה/מטבעת

הסכום/הערך בפועל של התנועה יתקבל על ידי שנים (או יותר)הפיצולים שלה. תחילה ייצורים את הפיצול הראשון: 

 Split *split = xaccMallocSplit(book);
 xaccTransAppendSplit(transaction, split); // הפיצול שייך לתנועה זו
 xaccAccountInsertSplit(account, split); // הפיצול שייך לחשבון זה
 gnc_numeric amount = gnc_numeric_create(123, 100); // 1.23 הסכום
 xaccSplitSetValue(split, amount);
 xaccSplitSetAmount(split, amount);

באשר ל־SetValue ו־SetAmount: בתנועה למסחר רב־מטבעי או במסחר במניות, הסכום והערך אינם בהכרך זהים, להפך. כל עוד מתמודדים עם מטבע אחד בלבד, הערך והסכום מוגדרים להיות זהים. כעת נדרש לייצור גם את הפיצול השני כך שהתנועה תהיה מאוזנת ובעלת שני פיצולים לפחות (שורת חובה ושורת זכות), בדיוק כפי שתנועות נרשמות בהנהלת חשבונות כפולה: 

 Account* other_account = ...; // נדרש לקבל זאת מהיכן שהו
 Split *split2 = xaccMallocSplit(book);
 xaccTransAppendSplit(transaction, split2); // הפיצול שייך לתנועה הזו
 xaccAccountInsertSplit(other_account, split2); // הפיצול שייך לחשבון זה
 gnc_numeric other_amount = gnc_numeric_create(-123, 100); // -1.23, הסכום מהפיצול הקודם אבל בסימן הפוך (מייצג חובה / זכות)
 xaccSplitSetValue(split, other_amount);
 xaccSplitSetAmount(split, other_amount);

לבסוף, סיום עריכת התנועה על ידי קריאה לפונקציה CommitEdit: 

 xaccTransCommitEdit(transaction); // סיום העריכה

דוגמאות שימוש

ניתן למצא מספר דוגמאות ב־[Python_shell#Usage_examples]].

הערות שוליים

  1. ↑ https://he.wikipedia.org/wiki/מודל_ישויות_קשרים
Retrieved from "https://code.gnucash.org/wiki/index.php?title=He/שימוש_ב_API&oldid=20745"