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

From GnuCash
Jump to: navigation, search
(תיעוד: fix ref)
m (תיעוד: style)
 
(7 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|צרפתית]]
 
 
|}
 
|}
 
==כללי==
 
==כללי==
  
עמוד זה מרכז מספר דוגמאות אודות אופן השימוש ב- C API של גנוקאש לצורך מניפולציה בסיסית בסוגי נתונים. C API (מכונה גם "המנוע") הוא שכבה שהפשטה מכל שרת. כלומר, מתכנת של מנשק המשתמש או מתכנת המתקעים לעולם לא יוכלו לגשת לאף אחד מתוכניות ה-XML או ה-SQL ישירות, במקום זאת הוא משתמש רק בפונקציות של מנשק ה- API כדי לגשת לנתונים.
+
עמוד זה מרכז מספר דוגמאות אודות אופן השימוש ב־C API של גנוקאש לצורך מניפולציה בסיסית בסוגי נתונים. C API (מכונה גם "המנוע") הוא שכבה שהפשטה מכל שרת. כלומר, מתכנת של מנשק המשתמש או מתכנת המתקעים לעולם לא יוכלו לגשת לאף אחד מתוכניות ה-XMLאו ה־SQL ישירות, במקום זאת הוא משתמש רק בפונקציות של מנשק ה־API כדי לגשת לנתונים.
  
 
== תיעוד ==
 
== תיעוד ==
באשר לתיעוד: לרוע המזל אין שום תיעוד קוהרנטי עדכני. חלקים נמצאים ב[[He/דוקסיג'ן|דוקסיג'ן]], אבל חלקים נמצאים רק בכותרות (header) קובצי C.
+
באשר לתיעוד: לרוע המזל אין שום תיעוד קוהרנטי עדכני. חלקים נמצאים ב־[[He/דוקסיג'ן|דוקסיג'ן]], אבל חלקים נמצאים רק בכותרות (header) קובצי C.
  
[{{BuildURL}}/docs/MAINT/modules.html סקירת פירקן] זמינה לחלקים שמתועדים בדוקסיג'ן. לדוגמה, קיימת קבוצת פירקנים תחת הכותרת "מנוע גנוקאש: Core, Non-GUI Accounting Functions" המכילה את אותם חלקים שעברו "דוקסיניזציה", לרבות ה'''חשבון''', אך אינה מכילה '''תנועות ופיצולים''' שהם סוגי הנתונים החשובים האחרים.
+
[{{BuildURL}}/docs/MAINT/modules.html רשימת פירקני גנוקאש] זמינה לחלקים שמתועדים בדוקסיג'ן. לדוגמה, קיימת קבוצת פירקנים תחת הכותרת "מנוע גנוקאש: Core, Non-GUI Accounting Functions" המכילה את אותם חלקים שעברו "דוקסיניזציה", לרבות אובייקט ה'''חשבון''', אך אינה מכילה את אובייקטי ה'''תנועות והפיצולים''', שהם שני סוגי הנתונים, החשובים, האחרים.
  
[[Media:gnucash_erd.png|מודל ישויות קשרים (ERD)]]<ref>https://he.wikipedia.org/wiki/מודל_ישויות_קשרים|מודל ישויות קשרים</ref> היא גרסה עדכנות (הוכנה למעשה ב מאי 2011, אך ללא שינויים עד אמצע 2017) המציגה את הסוגים והקשרים בין שדות המידע והטבלאות של גנוקאש (בצורת טבלאות דבר שכיח בתרשימי 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)
  
המקום היחיד בו ניתן למצוא מידע עדכני לבטח הם בכותרות הקבצים:
+
המקום היחיד בו לבטח ניתן למצוא מידע עדכני, הוא בכותרות הקבצים:
 
* libgnucash/engine/Split.h
 
* libgnucash/engine/Split.h
 
* libgnucash/engine/Transaction.h
 
* libgnucash/engine/Transaction.h
Line 52: Line 48:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
מכיוון שגנוקאש מסוגלת לטפל ברבוי-מטבעות, כל תנועה חייבת לכלול גם את הגדרת ''מטבע תנועה'':
+
מכיוון שגנוקאש מסוגלת לטפל ברבוי־מטבעות, כל תנועה חייבת לכלול גם את הגדרת ''מטבע תנועה'':
 
   
 
   
 
<syntaxhighlight lang="C">
 
<syntaxhighlight lang="C">
Line 70: Line 66:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
באשר ל- SetValue ו- SetAmount:  בתנועה למסחר רב-מטבעי או במסחר במניות, הסכום  והערך אינם בהכרך זהים, להפך. כל עוד מתמודדים עם מטבע אחד בלבד, הערך והסכום מוגדרים להיות זהים.
+
באשר ל־SetValue ו־SetAmount:  בתנועה למסחר רב־מטבעי או במסחר במניות, הסכום  והערך אינם בהכרך זהים, להפך. כל עוד מתמודדים עם מטבע אחד בלבד, הערך והסכום מוגדרים להיות זהים.
 
כעת נדרש לייצור גם את הפיצול השני כך שהתנועה תהיה מאוזנת ובעלת שני פיצולים לפחות (שורת חובה ושורת זכות), בדיוק כפי שתנועות נרשמות בהנהלת חשבונות כפולה:
 
כעת נדרש לייצור גם את הפיצול השני כך שהתנועה תהיה מאוזנת ובעלת שני פיצולים לפחות (שורת חובה ושורת זכות), בדיוק כפי שתנועות נרשמות בהנהלת חשבונות כפולה:
  
Line 90: Line 86:
  
 
== דוגמאות שימוש ==
 
== דוגמאות שימוש ==
ניתן למצא מספר דוגמאות ב- [[Python_shell#Usage_examples]].
+
ניתן למצא מספר דוגמאות ב־[Python_shell#Usage_examples]].
  
 
==הערות שוליים==
 
==הערות שוליים==
 
<references />
 
<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]].

הערות שוליים